summaryrefslogtreecommitdiff
path: root/tools/perf/scripts/python/net_dropmonitor.py
diff options
context:
space:
mode:
authorMichał Winiarski <michal.winiarski@intel.com>2021-12-14 21:33:34 +0200
committerMatt Roper <matthew.d.roper@intel.com>2021-12-17 21:50:06 -0800
commitc14adcbd1a9648dc9d16dfd12c1e9bc0c14ef6aa (patch)
tree9874cf71334512bdd8c9cad015775d21b1163db4 /tools/perf/scripts/python/net_dropmonitor.py
parent62e94f92e3977dbe67a6974ba7e5aa60c9a5e687 (diff)
drm/i915/gt: Use to_gt() helper
Use to_gt() helper consistently throughout the codebase. Pure mechanical s/i915->gt/to_gt(i915). No functional changes. Signed-off-by: Michał Winiarski <michal.winiarski@intel.com> Signed-off-by: Andi Shyti <andi.shyti@linux.intel.com> Reviewed-by: Matt Roper <matthew.d.roper@intel.com> Signed-off-by: Matt Roper <matthew.d.roper@intel.com> Link: https://patchwork.freedesktop.org/patch/msgid/20211214193346.21231-5-andi.shyti@linux.intel.com
Diffstat (limited to 'tools/perf/scripts/python/net_dropmonitor.py')
0 files changed, 0 insertions, 0 deletions
entation/.gitignore?id2=dae5597f253ae2d44432c8648d9a9205de057ddf'>Documentation/.gitignore3
-rw-r--r--Documentation/.renames.txt1191
-rw-r--r--Documentation/00-INDEX489
-rw-r--r--Documentation/ABI/README19
-rw-r--r--Documentation/ABI/obsolete/automount-tracefs-debugfs20
-rw-r--r--Documentation/ABI/obsolete/o2cb11
-rw-r--r--Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads5
-rw-r--r--Documentation/ABI/obsolete/procfs-i8k10
-rw-r--r--Documentation/ABI/obsolete/sysfs-block-zram119
-rw-r--r--Documentation/ABI/obsolete/sysfs-bus-iio174
-rw-r--r--Documentation/ABI/obsolete/sysfs-class-rfkill29
-rw-r--r--Documentation/ABI/obsolete/sysfs-class-typec48
-rw-r--r--Documentation/ABI/obsolete/sysfs-cpuidle9
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo (renamed from Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo)0
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku (renamed from Documentation/ABI/testing/sysfs-driver-hid-roccat-isku)0
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus99
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure (renamed from Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure)0
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus50
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua (renamed from Documentation/ABI/testing/sysfs-driver-hid-roccat-lua)0
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra55
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos (renamed from Documentation/ABI/testing/sysfs-driver-hid-roccat-ryos)0
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu (renamed from Documentation/ABI/testing/sysfs-driver-hid-roccat-savu)11
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-intel_pmc_bxt22
-rw-r--r--Documentation/ABI/obsolete/sysfs-driver-samsung-laptop10
-rw-r--r--Documentation/ABI/obsolete/sysfs-firmware-acpi8
-rw-r--r--Documentation/ABI/obsolete/sysfs-gpio40
-rw-r--r--Documentation/ABI/obsolete/sysfs-kernel-fadump_enabled9
-rw-r--r--Documentation/ABI/obsolete/sysfs-kernel-fadump_registered10
-rw-r--r--Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem10
-rw-r--r--Documentation/ABI/obsolete/sysfs-kernel-kexec-kdump71
-rw-r--r--Documentation/ABI/obsolete/sysfs-platform-ideapad-laptop8
-rw-r--r--Documentation/ABI/obsolete/sysfs-selinux-user12
-rw-r--r--Documentation/ABI/removed/devfs1
-rw-r--r--Documentation/ABI/removed/o2cb4
-rw-r--r--Documentation/ABI/removed/raw13941
-rw-r--r--Documentation/ABI/removed/sysfs-bus-nfit17
-rw-r--r--Documentation/ABI/removed/sysfs-class-cxl272
-rw-r--r--Documentation/ABI/removed/sysfs-class-rfkill13
-rw-r--r--Documentation/ABI/removed/sysfs-firmware-efi-vars12
-rw-r--r--Documentation/ABI/removed/sysfs-kernel-fadump_release_opalcore9
-rw-r--r--Documentation/ABI/removed/sysfs-kernel-uids (renamed from Documentation/ABI/testing/sysfs-kernel-uids)6
-rw-r--r--Documentation/ABI/removed/sysfs-mce37
-rw-r--r--Documentation/ABI/removed/sysfs-selinux-checkreqprot26
-rw-r--r--Documentation/ABI/removed/sysfs-selinux-disable29
-rw-r--r--Documentation/ABI/removed/video13941
-rw-r--r--Documentation/ABI/stable/firewire-cdev70
-rw-r--r--Documentation/ABI/stable/o2cb6
-rw-r--r--Documentation/ABI/stable/procfs-audit_loginuid27
-rw-r--r--Documentation/ABI/stable/sysfs-acpi-pmprofile42
-rw-r--r--Documentation/ABI/stable/sysfs-block881
-rw-r--r--Documentation/ABI/stable/sysfs-bus-firewire3
-rw-r--r--Documentation/ABI/stable/sysfs-bus-fsl-mc19
-rw-r--r--Documentation/ABI/stable/sysfs-bus-mhi44
-rw-r--r--Documentation/ABI/stable/sysfs-bus-nvmem50
-rw-r--r--Documentation/ABI/stable/sysfs-bus-usb8
-rw-r--r--Documentation/ABI/stable/sysfs-bus-vmbus187
-rw-r--r--Documentation/ABI/stable/sysfs-bus-w112
-rw-r--r--Documentation/ABI/stable/sysfs-bus-xen-backend11
-rw-r--r--Documentation/ABI/stable/sysfs-class-backlight15
-rw-r--r--Documentation/ABI/stable/sysfs-class-bluetooth9
-rw-r--r--Documentation/ABI/stable/sysfs-class-infiniband784
-rw-r--r--Documentation/ABI/stable/sysfs-class-rfkill50
-rw-r--r--Documentation/ABI/stable/sysfs-class-tpm147
-rw-r--r--Documentation/ABI/stable/sysfs-class-ubi9
-rw-r--r--Documentation/ABI/stable/sysfs-class-udc16
-rw-r--r--Documentation/ABI/stable/sysfs-devices28
-rw-r--r--Documentation/ABI/stable/sysfs-devices-node151
-rw-r--r--Documentation/ABI/stable/sysfs-devices-system-cpu92
-rw-r--r--Documentation/ABI/stable/sysfs-devices-system-xen_memory9
-rw-r--r--Documentation/ABI/stable/sysfs-driver-aspeed-vuart24
-rw-r--r--Documentation/ABI/stable/sysfs-driver-dma-idxd361
-rw-r--r--Documentation/ABI/stable/sysfs-driver-dma-ioatdma30
-rw-r--r--Documentation/ABI/stable/sysfs-driver-firmware-zynqmp256
-rw-r--r--Documentation/ABI/stable/sysfs-driver-ib_srp3
-rw-r--r--Documentation/ABI/stable/sysfs-driver-misc-cp50025
-rw-r--r--Documentation/ABI/stable/sysfs-driver-mlxreg-io815
-rw-r--r--Documentation/ABI/stable/sysfs-driver-qaic19
-rw-r--r--Documentation/ABI/stable/sysfs-driver-speakup395
-rw-r--r--Documentation/ABI/stable/sysfs-driver-usb-usbtmc35
-rw-r--r--Documentation/ABI/stable/sysfs-driver-w1_ds243813
-rw-r--r--Documentation/ABI/stable/sysfs-driver-w1_ds28e044
-rw-r--r--Documentation/ABI/stable/sysfs-driver-w1_ds28ea006
-rw-r--r--Documentation/ABI/stable/sysfs-firmware-efi-vars75
-rw-r--r--Documentation/ABI/stable/sysfs-firmware-opal-dump5
-rw-r--r--Documentation/ABI/stable/sysfs-firmware-opal-elog4
-rw-r--r--Documentation/ABI/stable/sysfs-fs-orangefs87
-rw-r--r--Documentation/ABI/stable/sysfs-hypervisor-xen135
-rw-r--r--Documentation/ABI/stable/sysfs-kernel-notes5
-rw-r--r--Documentation/ABI/stable/sysfs-kernel-time-aux-clocks5
-rw-r--r--Documentation/ABI/stable/sysfs-module25
-rw-r--r--Documentation/ABI/stable/sysfs-platform-wmi-bmof7
-rw-r--r--Documentation/ABI/stable/vdso22
-rw-r--r--Documentation/ABI/testing/configfs-acpi52
-rw-r--r--Documentation/ABI/testing/configfs-iio34
-rw-r--r--Documentation/ABI/testing/configfs-most241
-rw-r--r--Documentation/ABI/testing/configfs-rdma_cm30
-rw-r--r--Documentation/ABI/testing/configfs-spear-pcie-gadget38
-rw-r--r--Documentation/ABI/testing/configfs-stp-policy48
-rw-r--r--Documentation/ABI/testing/configfs-stp-policy-p_sys-t41
-rw-r--r--Documentation/ABI/testing/configfs-tsm-report145
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget96
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-acm7
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-ecm12
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-eem10
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-ffs12
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-hid10
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-loopback6
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-mass-storage24
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-midi14
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-midi254
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-printer6
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-rndis13
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-sourcesink16
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-subset10
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-tcm6
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-uac145
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy12
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-uac251
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-uvc399
-rw-r--r--Documentation/ABI/testing/debugfs-alienware-wmi64
-rw-r--r--Documentation/ABI/testing/debugfs-amd-iommu131
-rw-r--r--Documentation/ABI/testing/debugfs-cec-error-inj40
-rw-r--r--Documentation/ABI/testing/debugfs-cros-ec78
-rw-r--r--Documentation/ABI/testing/debugfs-cxl157
-rw-r--r--Documentation/ABI/testing/debugfs-dell-wmi-ddv34
-rw-r--r--Documentation/ABI/testing/debugfs-driver-dcc127
-rw-r--r--Documentation/ABI/testing/debugfs-driver-genwqe2
-rw-r--r--Documentation/ABI/testing/debugfs-driver-habanalabs323
-rw-r--r--Documentation/ABI/testing/debugfs-driver-qat109
-rw-r--r--Documentation/ABI/testing/debugfs-driver-qat_telemetry259
-rw-r--r--Documentation/ABI/testing/debugfs-dwc-pcie157
-rw-r--r--Documentation/ABI/testing/debugfs-ec11
-rw-r--r--Documentation/ABI/testing/debugfs-hisi-hpre193
-rw-r--r--Documentation/ABI/testing/debugfs-hisi-migration25
-rw-r--r--Documentation/ABI/testing/debugfs-hisi-sec166
-rw-r--r--Documentation/ABI/testing/debugfs-hisi-zip167
-rw-r--r--Documentation/ABI/testing/debugfs-hyperv23
-rw-r--r--Documentation/ABI/testing/debugfs-iio-ad946739
-rw-r--r--Documentation/ABI/testing/debugfs-iio-backend20
-rw-r--r--Documentation/ABI/testing/debugfs-intel-iommu276
-rw-r--r--Documentation/ABI/testing/debugfs-moxtet35
-rw-r--r--Documentation/ABI/testing/debugfs-msi-wmi-platform14
-rw-r--r--Documentation/ABI/testing/debugfs-pcie-ptm70
-rw-r--r--Documentation/ABI/testing/debugfs-pfo-nx-crypto28
-rw-r--r--Documentation/ABI/testing/debugfs-pktcdvd19
-rw-r--r--Documentation/ABI/testing/debugfs-scmi70
-rw-r--r--Documentation/ABI/testing/debugfs-scmi-raw208
-rw-r--r--Documentation/ABI/testing/debugfs-tpmi40
-rw-r--r--Documentation/ABI/testing/debugfs-vfio31
-rw-r--r--Documentation/ABI/testing/debugfs-wilco-ec45
-rw-r--r--Documentation/ABI/testing/dell-smbios-wmi41
-rw-r--r--Documentation/ABI/testing/dev-kmsg62
-rw-r--r--Documentation/ABI/testing/devlink-resource-mlxsw33
-rw-r--r--Documentation/ABI/testing/evm115
-rw-r--r--Documentation/ABI/testing/gpio-cdev28
-rw-r--r--Documentation/ABI/testing/ima_policy146
-rw-r--r--Documentation/ABI/testing/ppc-memtrace46
-rw-r--r--Documentation/ABI/testing/procfs-attr-current20
-rw-r--r--Documentation/ABI/testing/procfs-attr-exec20
-rw-r--r--Documentation/ABI/testing/procfs-attr-prev19
-rw-r--r--Documentation/ABI/testing/procfs-diskstats51
-rw-r--r--Documentation/ABI/testing/procfs-smaps_rollup42
-rw-r--r--Documentation/ABI/testing/pstore24
-rw-r--r--Documentation/ABI/testing/rtc-cdev50
-rw-r--r--Documentation/ABI/testing/securityfs-secrets-coco51
-rw-r--r--Documentation/ABI/testing/sysfs-amd-pmc13
-rw-r--r--Documentation/ABI/testing/sysfs-amd-pmf13
-rw-r--r--Documentation/ABI/testing/sysfs-ata163
-rw-r--r--Documentation/ABI/testing/sysfs-auxdisplay-linedisp90
-rw-r--r--Documentation/ABI/testing/sysfs-block230
-rw-r--r--Documentation/ABI/testing/sysfs-block-aoe45
-rw-r--r--Documentation/ABI/testing/sysfs-block-bcache7
-rw-r--r--Documentation/ABI/testing/sysfs-block-device119
-rw-r--r--Documentation/ABI/testing/sysfs-block-loop50
-rw-r--r--Documentation/ABI/testing/sysfs-block-rnbd64
-rw-r--r--Documentation/ABI/testing/sysfs-block-zram186
-rw-r--r--Documentation/ABI/testing/sysfs-bus-acpi54
-rw-r--r--Documentation/ABI/testing/sysfs-bus-auxiliary9
-rw-r--r--Documentation/ABI/testing/sysfs-bus-bcma2
-rw-r--r--Documentation/ABI/testing/sysfs-bus-cdx121
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coreboot45
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-cti247
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source21
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-etb1078
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x107
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x532
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel6
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-stm59
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc107
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm280
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe20
-rw-r--r--Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb31
-rw-r--r--Documentation/ABI/testing/sysfs-bus-counter477
-rw-r--r--Documentation/ABI/testing/sysfs-bus-css37
-rw-r--r--Documentation/ABI/testing/sysfs-bus-cxl626
-rw-r--r--Documentation/ABI/testing/sysfs-bus-dax153
-rw-r--r--Documentation/ABI/testing/sysfs-bus-dfl17
-rw-r--r--Documentation/ABI/testing/sysfs-bus-dfl-devices-emif25
-rw-r--r--Documentation/ABI/testing/sysfs-bus-dfl-devices-n3000-nios47
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices24
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-caps24
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme104
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa30
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-events12
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-format7
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-hisi_ptt113
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x755
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci199
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu37
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore13
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-dtl25
-rw-r--r--Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-pmu25
-rw-r--r--Documentation/ABI/testing/sysfs-bus-fcoe78
-rw-r--r--Documentation/ABI/testing/sysfs-bus-fsi46
-rw-r--r--Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo10
-rw-r--r--Documentation/ABI/testing/sysfs-bus-fsl-mc25
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k7
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa948026
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i2c-devices-hm635212
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr100
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x23
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i2c-devices-turris-omnia-mcu113
-rw-r--r--Documentation/ABI/testing/sysfs-bus-i3c163
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio1380
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-accel-adxl3727
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-ad9739a19
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta23
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-ad413020
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-ad719227
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-ad7280a13
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector39
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-hi843548
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-max1141013
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-mcp356453
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-mt636078
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-pac19349
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-adc-stm3221
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-bno05581
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-cdc-ad774611
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp4017
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-chemical-sunrise-co238
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x7
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-cros-ec18
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-dac61
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-dac-ad576631
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac8
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-dac-ltc268855
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm3222
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-distance-srf0817
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-dma-buffer19
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-filter-admv881818
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-frequency-ad95232
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-frequency-adf437111
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-frequency-admv101338
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-frequency-admv101423
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-health-afe440x39
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-humidity10
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad593335
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc15
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-inv_icm4260018
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-isl2950147
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-light-isl2901821
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als11
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-light-si113322
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-light-tsl258320
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-light-tsl277213
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc584320
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-meas-spec7
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp45318
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-proximity24
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-proximity-as393517
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s121027
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-sps3028
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-sx931010
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-sx932429
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-thermocouple18
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-timer-stm32143
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs31
-rw-r--r--Documentation/ABI/testing/sysfs-bus-iio-vf61016
-rw-r--r--Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth52
-rw-r--r--Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc54
-rw-r--r--Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti24
-rw-r--r--Documentation/ABI/testing/sysfs-bus-intel_th-output-devices15
-rw-r--r--Documentation/ABI/testing/sysfs-bus-mcb29
-rw-r--r--Documentation/ABI/testing/sysfs-bus-mdio101
-rw-r--r--Documentation/ABI/testing/sysfs-bus-mei51
-rw-r--r--Documentation/ABI/testing/sysfs-bus-mmc4
-rw-r--r--Documentation/ABI/testing/sysfs-bus-most299
-rw-r--r--Documentation/ABI/testing/sysfs-bus-moxtet-devices17
-rw-r--r--Documentation/ABI/testing/sysfs-bus-nfit233
-rw-r--r--Documentation/ABI/testing/sysfs-bus-nvdimm59
-rw-r--r--Documentation/ABI/testing/sysfs-bus-optee-devices17
-rw-r--r--Documentation/ABI/testing/sysfs-bus-papr-pmem75
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci438
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-devices-aer163
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-devices-avs8
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-devices-catpt17
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-devices-cciss44
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic26
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd4
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio8
-rw-r--r--Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd87
-rw-r--r--Documentation/ABI/testing/sysfs-bus-peci16
-rw-r--r--Documentation/ABI/testing/sysfs-bus-platform36
-rw-r--r--Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro325
-rw-r--r--Documentation/ABI/testing/sysfs-bus-platform-devices-occ-hwmon13
-rw-r--r--Documentation/ABI/testing/sysfs-bus-platform-drivers-amd_x3d_vcache12
-rw-r--r--Documentation/ABI/testing/sysfs-bus-platform-onboard-usb-dev9
-rw-r--r--Documentation/ABI/testing/sysfs-bus-rapidio201
-rw-r--r--Documentation/ABI/testing/sysfs-bus-rbd191
-rw-r--r--Documentation/ABI/testing/sysfs-bus-rpmsg20
-rw-r--r--Documentation/ABI/testing/sysfs-bus-siox90
-rw-r--r--Documentation/ABI/testing/sysfs-bus-soundwire-master23
-rw-r--r--Documentation/ABI/testing/sysfs-bus-soundwire-slave109
-rw-r--r--Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor40
-rw-r--r--Documentation/ABI/testing/sysfs-bus-surface_aggregator-tabletsw57
-rw-r--r--Documentation/ABI/testing/sysfs-bus-thunderbolt370
-rw-r--r--Documentation/ABI/testing/sysfs-bus-typec51
-rw-r--r--Documentation/ABI/testing/sysfs-bus-umc28
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb540
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg29
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb-lvstest25
-rw-r--r--Documentation/ABI/testing/sysfs-bus-vdpa57
-rw-r--r--Documentation/ABI/testing/sysfs-bus-vfio-mdev113
-rw-r--r--Documentation/ABI/testing/sysfs-bus-vmbus21
-rw-r--r--Documentation/ABI/testing/sysfs-bus-wmi81
-rw-r--r--Documentation/ABI/testing/sysfs-c2port7
-rw-r--r--Documentation/ABI/testing/sysfs-class2
-rw-r--r--Documentation/ABI/testing/sysfs-class-backlight186
-rw-r--r--Documentation/ABI/testing/sysfs-class-backlight-driver-adp887056
-rw-r--r--Documentation/ABI/testing/sysfs-class-backlight-driver-lm353332
-rw-r--r--Documentation/ABI/testing/sysfs-class-backlight-lm363911
-rw-r--r--Documentation/ABI/testing/sysfs-class-bdi97
-rw-r--r--Documentation/ABI/testing/sysfs-class-bsr25
-rw-r--r--Documentation/ABI/testing/sysfs-class-chromeos53
-rw-r--r--Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar74
-rw-r--r--Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc6
-rw-r--r--Documentation/ABI/testing/sysfs-class-cxl192
-rw-r--r--Documentation/ABI/testing/sysfs-class-devfreq95
-rw-r--r--Documentation/ABI/testing/sysfs-class-devfreq-event25
-rw-r--r--Documentation/ABI/testing/sysfs-class-devlink130
-rw-r--r--Documentation/ABI/testing/sysfs-class-drm8
-rw-r--r--Documentation/ABI/testing/sysfs-class-extcon46
-rw-r--r--Documentation/ABI/testing/sysfs-class-fc27
-rw-r--r--Documentation/ABI/testing/sysfs-class-fc_host23
-rw-r--r--Documentation/ABI/testing/sysfs-class-fc_remote_ports23
-rw-r--r--Documentation/ABI/testing/sysfs-class-firmware77
-rw-r--r--Documentation/ABI/testing/sysfs-class-firmware-attributes494
-rw-r--r--Documentation/ABI/testing/sysfs-class-fpga-bridge11
-rw-r--r--Documentation/ABI/testing/sysfs-class-fpga-manager60
-rw-r--r--Documentation/ABI/testing/sysfs-class-fpga-region9
-rw-r--r--Documentation/ABI/testing/sysfs-class-gnss17
-rw-r--r--Documentation/ABI/testing/sysfs-class-hwmon1075
-rw-r--r--Documentation/ABI/testing/sysfs-class-intel_pmt119
-rw-r--r--Documentation/ABI/testing/sysfs-class-intel_pmt-features134
-rw-r--r--Documentation/ABI/testing/sysfs-class-led64
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-driver-aw200xx5
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-driver-lm353352
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia28
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-flash27
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-multicolor24
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-trigger-netdev192
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-trigger-oneshot36
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-trigger-pattern50
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-trigger-tty62
-rw-r--r--Documentation/ABI/testing/sysfs-class-led-trigger-usbport13
-rw-r--r--Documentation/ABI/testing/sysfs-class-leds-gt683r12
-rw-r--r--Documentation/ABI/testing/sysfs-class-mei78
-rw-r--r--Documentation/ABI/testing/sysfs-class-mic178
-rw-r--r--Documentation/ABI/testing/sysfs-class-mic.txt157
-rw-r--r--Documentation/ABI/testing/sysfs-class-mtd16
-rw-r--r--Documentation/ABI/testing/sysfs-class-mux16
-rw-r--r--Documentation/ABI/testing/sysfs-class-net156
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-batman-adv15
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-cdc_ncm25
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-dsa14
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-janz-ican319
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-mesh108
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-peak_usb19
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-phydev75
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-qmi76
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-queues56
-rw-r--r--Documentation/ABI/testing/sysfs-class-net-statistics60
-rw-r--r--Documentation/ABI/testing/sysfs-class-ocxl51
-rw-r--r--Documentation/ABI/testing/sysfs-class-pktcdvd72
-rw-r--r--Documentation/ABI/testing/sysfs-class-platform-profile50
-rw-r--r--Documentation/ABI/testing/sysfs-class-power837
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-gaokun27
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-ltc4162l82
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-max1720x32
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-mp26299
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-rt946719
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-rt947132
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-rt975630
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-surface15
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-twl403033
-rw-r--r--Documentation/ABI/testing/sysfs-class-power-wilco40
-rw-r--r--Documentation/ABI/testing/sysfs-class-powercap4
-rw-r--r--Documentation/ABI/testing/sysfs-class-pwm27
-rw-r--r--Documentation/ABI/testing/sysfs-class-rapidio59
-rw-r--r--Documentation/ABI/testing/sysfs-class-rc74
-rw-r--r--Documentation/ABI/testing/sysfs-class-rc-nuvoton15
-rw-r--r--Documentation/ABI/testing/sysfs-class-regulator117
-rw-r--r--Documentation/ABI/testing/sysfs-class-remoteproc104
-rw-r--r--Documentation/ABI/testing/sysfs-class-rnbd-client133
-rw-r--r--Documentation/ABI/testing/sysfs-class-rnbd-server58
-rw-r--r--Documentation/ABI/testing/sysfs-class-rtc91
-rw-r--r--Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration6
-rw-r--r--Documentation/ABI/testing/sysfs-class-rtrs-client146
-rw-r--r--Documentation/ABI/testing/sysfs-class-rtrs-server53
-rw-r--r--Documentation/ABI/testing/sysfs-class-scsi_host90
-rw-r--r--Documentation/ABI/testing/sysfs-class-scsi_tape109
-rw-r--r--Documentation/ABI/testing/sysfs-class-spi-eeprom19
-rw-r--r--Documentation/ABI/testing/sysfs-class-stm24
-rw-r--r--Documentation/ABI/testing/sysfs-class-stm_source11
-rw-r--r--Documentation/ABI/testing/sysfs-class-switchtec96
-rw-r--r--Documentation/ABI/testing/sysfs-class-tee15
-rw-r--r--Documentation/ABI/testing/sysfs-class-thermal259
-rw-r--r--Documentation/ABI/testing/sysfs-class-tsm19
-rw-r--r--Documentation/ABI/testing/sysfs-class-typec375
-rw-r--r--Documentation/ABI/testing/sysfs-class-usb_power_delivery284
-rw-r--r--Documentation/ABI/testing/sysfs-class-usb_role27
-rw-r--r--Documentation/ABI/testing/sysfs-class-uwb_rc159
-rw-r--r--Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc57
-rw-r--r--Documentation/ABI/testing/sysfs-class-vduse33
-rw-r--r--Documentation/ABI/testing/sysfs-class-wakeup76
-rw-r--r--Documentation/ABI/testing/sysfs-class-watchdog129
-rw-r--r--Documentation/ABI/testing/sysfs-class-zram24
-rw-r--r--Documentation/ABI/testing/sysfs-dev7
-rw-r--r--Documentation/ABI/testing/sysfs-devices-consumer9
-rw-r--r--Documentation/ABI/testing/sysfs-devices-coredump10
-rw-r--r--Documentation/ABI/testing/sysfs-devices-edac31
-rw-r--r--Documentation/ABI/testing/sysfs-devices-mapping62
-rw-r--r--Documentation/ABI/testing/sysfs-devices-memory75
-rw-r--r--Documentation/ABI/testing/sysfs-devices-online2
-rw-r--r--Documentation/ABI/testing/sysfs-devices-pci-host-bridge45
-rw-r--r--Documentation/ABI/testing/sysfs-devices-physical_location42
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD117
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget10
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-docg310
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-dock39
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-ipmi242
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs126
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb8
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-soc-ipa114
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu174
-rw-r--r--Documentation/ABI/testing/sysfs-devices-platform-trackpoint115
-rw-r--r--Documentation/ABI/testing/sysfs-devices-power91
-rw-r--r--Documentation/ABI/testing/sysfs-devices-removable20
-rw-r--r--Documentation/ABI/testing/sysfs-devices-soc51
-rw-r--r--Documentation/ABI/testing/sysfs-devices-software_node10
-rw-r--r--Documentation/ABI/testing/sysfs-devices-state_synced29
-rw-r--r--Documentation/ABI/testing/sysfs-devices-supplier9
-rw-r--r--Documentation/ABI/testing/sysfs-devices-system-cpu639
-rw-r--r--Documentation/ABI/testing/sysfs-devices-system-ibm-rtl10
-rw-r--r--Documentation/ABI/testing/sysfs-devices-vfio-dev8
-rw-r--r--Documentation/ABI/testing/sysfs-devices-virtual-misc-tdx_guest63
-rw-r--r--Documentation/ABI/testing/sysfs-devices-waiting_for_supplier17
-rw-r--r--Documentation/ABI/testing/sysfs-devices-xenbus41
-rw-r--r--Documentation/ABI/testing/sysfs-driver-altera-cvp8
-rw-r--r--Documentation/ABI/testing/sysfs-driver-amd-sfh13
-rw-r--r--Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing27
-rw-r--r--Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator31
-rw-r--r--Documentation/ABI/testing/sysfs-driver-ccp105
-rw-r--r--Documentation/ABI/testing/sysfs-driver-chromeos-acpi152
-rw-r--r--Documentation/ABI/testing/sysfs-driver-eud9
-rw-r--r--Documentation/ABI/testing/sysfs-driver-framer-pef22568
-rw-r--r--Documentation/ABI/testing/sysfs-driver-fsi-master-gpio10
-rw-r--r--Documentation/ABI/testing/sysfs-driver-ge-achc15
-rw-r--r--Documentation/ABI/testing/sysfs-driver-genwqe11
-rw-r--r--Documentation/ABI/testing/sysfs-driver-habanalabs265
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid12
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-appletb-kbd13
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-corsair15
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-corsair-void38
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-lenovo10
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp19
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff39
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-ntrig73
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-picolcd2
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-roccat-kone21
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus96
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus49
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra49
-rw-r--r--Documentation/ABI/testing/sysfs-driver-hid-wiimote12
-rw-r--r--Documentation/ABI/testing/sysfs-driver-input-cros-ec-keyb6
-rw-r--r--Documentation/ABI/testing/sysfs-driver-input-exc300026
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intc_sar54
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon93
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intel-m10-bmc36
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update61
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon198
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intel-xe-sriov159
-rw-r--r--Documentation/ABI/testing/sysfs-driver-intel_sdsi90
-rw-r--r--Documentation/ABI/testing/sysfs-driver-jz4780-efuse20
-rw-r--r--Documentation/ABI/testing/sysfs-driver-panfrost-profiling10
-rw-r--r--Documentation/ABI/testing/sysfs-driver-panthor-profiling10
-rw-r--r--Documentation/ABI/testing/sysfs-driver-pciback19
-rw-r--r--Documentation/ABI/testing/sysfs-driver-ppi21
-rw-r--r--Documentation/ABI/testing/sysfs-driver-qaic18
-rw-r--r--Documentation/ABI/testing/sysfs-driver-qat167
-rw-r--r--Documentation/ABI/testing/sysfs-driver-qat_ras41
-rw-r--r--Documentation/ABI/testing/sysfs-driver-qat_rl226
-rw-r--r--Documentation/ABI/testing/sysfs-driver-samsung-laptop20
-rw-r--r--Documentation/ABI/testing/sysfs-driver-spi-intel20
-rw-r--r--Documentation/ABI/testing/sysfs-driver-st12
-rw-r--r--Documentation/ABI/testing/sysfs-driver-sunxi-sid22
-rw-r--r--Documentation/ABI/testing/sysfs-driver-tegra-fuse2
-rw-r--r--Documentation/ABI/testing/sysfs-driver-toshiba_acpi42
-rw-r--r--Documentation/ABI/testing/sysfs-driver-toshiba_haps22
-rw-r--r--Documentation/ABI/testing/sysfs-driver-typec-displayport74
-rw-r--r--Documentation/ABI/testing/sysfs-driver-uacce57
-rw-r--r--Documentation/ABI/testing/sysfs-driver-ucsi-ccg6
-rw-r--r--Documentation/ABI/testing/sysfs-driver-ufs1770
-rw-r--r--Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid29
-rw-r--r--Documentation/ABI/testing/sysfs-driver-uniwill-laptop53
-rw-r--r--Documentation/ABI/testing/sysfs-driver-w1_ds28e1724
-rw-r--r--Documentation/ABI/testing/sysfs-driver-w1_therm190
-rw-r--r--Documentation/ABI/testing/sysfs-driver-wacom30
-rw-r--r--Documentation/ABI/testing/sysfs-driver-xdata49
-rw-r--r--Documentation/ABI/testing/sysfs-driver-xen-blkback29
-rw-r--r--Documentation/ABI/testing/sysfs-driver-xen-blkfront11
-rw-r--r--Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager16
-rw-r--r--Documentation/ABI/testing/sysfs-driver-zynqmp-fpga73
-rw-r--r--Documentation/ABI/testing/sysfs-edac-ecs74
-rw-r--r--Documentation/ABI/testing/sysfs-edac-memory-repair206
-rw-r--r--Documentation/ABI/testing/sysfs-edac-scrub85
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-acpi319
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-dmi110
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-dmi-entries114
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-dmi-tables22
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-efi25
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-efi-esrt87
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-efi-runtime-map14
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-gsmi2
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-initrd8
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-lefi-boardinfo35
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-memmap20
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-ofw26
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-opal-powercap31
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-opal-psr18
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-opal-sensor-groups21
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-papr-energy-scale-info29
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg103
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-sfi15
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-sgi_uv160
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm28
-rw-r--r--Documentation/ABI/testing/sysfs-fs-erofs45
-rw-r--r--Documentation/ABI/testing/sysfs-fs-ext413
-rw-r--r--Documentation/ABI/testing/sysfs-fs-f2fs923
-rw-r--r--Documentation/ABI/testing/sysfs-fs-ubifs35
-rw-r--r--Documentation/ABI/testing/sysfs-fs-virtiofs11
-rw-r--r--Documentation/ABI/testing/sysfs-fs-xfs28
-rw-r--r--Documentation/ABI/testing/sysfs-gpio27
-rw-r--r--Documentation/ABI/testing/sysfs-hypervisor-xen46
-rw-r--r--Documentation/ABI/testing/sysfs-i2c-bmp08531
-rw-r--r--Documentation/ABI/testing/sysfs-ibft10
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-address_bits10
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-boot_params23
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-btf25
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-cpu_byteorder12
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers24
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-fadump59
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-fscaps2
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-hardlockup_count7
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-iommu_groups50
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-irq60
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-kexec-kdump61
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-livepatch53
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-cma44
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-damon559
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-hugepages14
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-ksm15
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-memory-tiers25
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-mempolicy4
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave54
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-numa28
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-swap16
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage18
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-oops_count6
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-rcu_stall_count6
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-reboot40
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-slab230
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-softlockup_count7
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-vmcoreinfo2
-rw-r--r--Documentation/ABI/testing/sysfs-kernel-warn_count6
-rw-r--r--Documentation/ABI/testing/sysfs-mce97
-rw-r--r--Documentation/ABI/testing/sysfs-memory-page-offline4
-rw-r--r--Documentation/ABI/testing/sysfs-module41
-rw-r--r--Documentation/ABI/testing/sysfs-nvmem-cells21
-rw-r--r--Documentation/ABI/testing/sysfs-ocfs212
-rw-r--r--Documentation/ABI/testing/sysfs-platform-alienware-wmi14
-rw-r--r--Documentation/ABI/testing/sysfs-platform-asus-laptop23
-rw-r--r--Documentation/ABI/testing/sysfs-platform-asus-wmi193
-rw-r--r--Documentation/ABI/testing/sysfs-platform-at9110
-rw-r--r--Documentation/ABI/testing/sysfs-platform-ayaneo-ec19
-rw-r--r--Documentation/ABI/testing/sysfs-platform-brcmstb-memc15
-rw-r--r--Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg8
-rw-r--r--Documentation/ABI/testing/sysfs-platform-chipidea-usb29
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dell-laptop20
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dell-privacy-wmi71
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dell-smbios21
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv9
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dfl-fme246
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dfl-port101
-rw-r--r--Documentation/ABI/testing/sysfs-platform-dptf157
-rw-r--r--Documentation/ABI/testing/sysfs-platform-eeepc-laptop14
-rw-r--r--Documentation/ABI/testing/sysfs-platform-hidma9
-rw-r--r--Documentation/ABI/testing/sysfs-platform-hidma-mgmt97
-rw-r--r--Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl18
-rw-r--r--Documentation/ABI/testing/sysfs-platform-ideapad-laptop37
-rw-r--r--Documentation/ABI/testing/sysfs-platform-intel-ifs52
-rw-r--r--Documentation/ABI/testing/sysfs-platform-intel-pmc22
-rw-r--r--Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update13
-rw-r--r--Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt12
-rw-r--r--Documentation/ABI/testing/sysfs-platform-kim5
-rw-r--r--Documentation/ABI/testing/sysfs-platform-lg-laptop36
-rw-r--r--Documentation/ABI/testing/sysfs-platform-mellanox-bootctl162
-rw-r--r--Documentation/ABI/testing/sysfs-platform-mellanox-pmc64
-rw-r--r--Documentation/ABI/testing/sysfs-platform-oxp25
-rw-r--r--Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb217
-rw-r--r--Documentation/ABI/testing/sysfs-platform-power-on-reason12
-rw-r--r--Documentation/ABI/testing/sysfs-platform-renesas_usb317
-rw-r--r--Documentation/ABI/testing/sysfs-platform-silicom30
-rw-r--r--Documentation/ABI/testing/sysfs-platform-sst-atom26
-rw-r--r--Documentation/ABI/testing/sysfs-platform-twl4030-usb8
-rw-r--r--Documentation/ABI/testing/sysfs-platform-usbip-vudc38
-rw-r--r--Documentation/ABI/testing/sysfs-platform-wilco-ec58
-rw-r--r--Documentation/ABI/testing/sysfs-platform_profile40
-rw-r--r--Documentation/ABI/testing/sysfs-power300
-rw-r--r--Documentation/ABI/testing/sysfs-pps-gen43
-rw-r--r--Documentation/ABI/testing/sysfs-pps-gen-tio6
-rw-r--r--Documentation/ABI/testing/sysfs-profiling2
-rw-r--r--Documentation/ABI/testing/sysfs-ptp48
-rw-r--r--Documentation/ABI/testing/sysfs-secvar130
-rw-r--r--Documentation/ABI/testing/sysfs-timecard293
-rw-r--r--Documentation/ABI/testing/sysfs-tty52
-rw-r--r--Documentation/ABI/testing/sysfs-uevent51
-rw-r--r--Documentation/ABI/testing/sysfs-wusb_cbaf100
-rw-r--r--Documentation/ABI/testing/usb-charger-uevent54
-rw-r--r--Documentation/ABI/testing/usb-uevent27
-rw-r--r--Documentation/BUG-HUNTING246
l---------[-rw-r--r--]Documentation/Changes396
-rw-r--r--Documentation/CodeOfConflict27
-rw-r--r--Documentation/CodingStyle949
-rw-r--r--Documentation/DMA-API-HOWTO.txt969
-rw-r--r--Documentation/DMA-API.txt704
-rw-r--r--Documentation/DMA-ISA-LPC.txt151
-rw-r--r--Documentation/DMA-attributes.txt102
-rw-r--r--Documentation/DocBook/.gitignore15
-rw-r--r--Documentation/DocBook/80211.tmpl582
-rw-r--r--Documentation/DocBook/Makefile232
-rw-r--r--Documentation/DocBook/alsa-driver-api.tmpl140
-rw-r--r--Documentation/DocBook/crypto-API.tmpl2113
-rw-r--r--Documentation/DocBook/debugobjects.tmpl441
-rw-r--r--Documentation/DocBook/device-drivers.tmpl458
-rw-r--r--Documentation/DocBook/deviceiobook.tmpl323
-rw-r--r--Documentation/DocBook/drm.tmpl4231
-rw-r--r--Documentation/DocBook/filesystems.tmpl425
-rw-r--r--Documentation/DocBook/gadget.tmpl793
-rw-r--r--Documentation/DocBook/genericirq.tmpl520
-rw-r--r--Documentation/DocBook/kernel-api.tmpl331
-rw-r--r--Documentation/DocBook/kernel-hacking.tmpl1310
-rw-r--r--Documentation/DocBook/kernel-locking.tmpl2151
-rw-r--r--Documentation/DocBook/kgdb.tmpl918
-rw-r--r--Documentation/DocBook/libata.tmpl1625
-rw-r--r--Documentation/DocBook/librs.tmpl289
-rw-r--r--Documentation/DocBook/lsm.tmpl265
-rw-r--r--Documentation/DocBook/media/Makefile388
-rw-r--r--Documentation/DocBook/media/bayer.png.b64171
-rw-r--r--Documentation/DocBook/media/constraints.png.b6459
-rw-r--r--Documentation/DocBook/media/crop.gif.b64105
-rw-r--r--Documentation/DocBook/media/dvb/.gitignore1
-rw-r--r--Documentation/DocBook/media/dvb/audio.xml1314
-rw-r--r--Documentation/DocBook/media/dvb/ca.xml582
-rw-r--r--Documentation/DocBook/media/dvb/demux.xml1145
-rw-r--r--Documentation/DocBook/media/dvb/dvbapi.xml141
-rw-r--r--Documentation/DocBook/media/dvb/dvbproperty.xml1317
-rw-r--r--Documentation/DocBook/media/dvb/dvbstb.pdfbin1881 -> 0 bytes-rw-r--r--Documentation/DocBook/media/dvb/examples.xml365
-rw-r--r--Documentation/DocBook/media/dvb/frontend.xml1548
-rw-r--r--Documentation/DocBook/media/dvb/intro.xml212
-rw-r--r--Documentation/DocBook/media/dvb/kdapi.xml2309
-rw-r--r--Documentation/DocBook/media/dvb/net.xml156
-rw-r--r--Documentation/DocBook/media/dvb/video.xml1968
-rw-r--r--Documentation/DocBook/media/dvbstb.png.b64398
-rw-r--r--Documentation/DocBook/media/fieldseq_bt.gif.b64447
-rw-r--r--Documentation/DocBook/media/fieldseq_tb.gif.b64445
-rw-r--r--Documentation/DocBook/media/nv12mt.gif.b6437
-rw-r--r--Documentation/DocBook/media/nv12mt_example.gif.b64121
-rw-r--r--Documentation/DocBook/media/pipeline.png.b64213
-rw-r--r--Documentation/DocBook/media/selection.png.b64206
-rw-r--r--Documentation/DocBook/media/v4l/.gitignore1
-rw-r--r--Documentation/DocBook/media/v4l/biblio.xml353
-rw-r--r--Documentation/DocBook/media/v4l/capture.c.xml659
-rw-r--r--Documentation/DocBook/media/v4l/common.xml1102
-rw-r--r--Documentation/DocBook/media/v4l/compat.xml2741
-rw-r--r--Documentation/DocBook/media/v4l/controls.xml5464
-rw-r--r--Documentation/DocBook/media/v4l/crop.pdfbin5846 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/dev-capture.xml110
-rw-r--r--Documentation/DocBook/media/v4l/dev-codec.xml27
-rw-r--r--Documentation/DocBook/media/v4l/dev-effect.xml17
-rw-r--r--Documentation/DocBook/media/v4l/dev-event.xml43
-rw-r--r--Documentation/DocBook/media/v4l/dev-osd.xml149
-rw-r--r--Documentation/DocBook/media/v4l/dev-output.xml106
-rw-r--r--Documentation/DocBook/media/v4l/dev-overlay.xml368
-rw-r--r--Documentation/DocBook/media/v4l/dev-radio.xml49
-rw-r--r--Documentation/DocBook/media/v4l/dev-raw-vbi.xml345
-rw-r--r--Documentation/DocBook/media/v4l/dev-rds.xml196
-rw-r--r--Documentation/DocBook/media/v4l/dev-sdr.xml120
-rw-r--r--Documentation/DocBook/media/v4l/dev-sliced-vbi.xml706
-rw-r--r--Documentation/DocBook/media/v4l/dev-subdev.xml484
-rw-r--r--Documentation/DocBook/media/v4l/dev-teletext.xml29
-rw-r--r--Documentation/DocBook/media/v4l/driver.xml200
-rw-r--r--Documentation/DocBook/media/v4l/fdl-appendix.xml671
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_bt.pdfbin9185 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_tb.pdfbin9173 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/func-close.xml62
-rw-r--r--Documentation/DocBook/media/v4l/func-ioctl.xml71
-rw-r--r--Documentation/DocBook/media/v4l/func-mmap.xml183
-rw-r--r--Documentation/DocBook/media/v4l/func-munmap.xml76
-rw-r--r--Documentation/DocBook/media/v4l/func-open.xml113
-rw-r--r--Documentation/DocBook/media/v4l/func-poll.xml142
-rw-r--r--Documentation/DocBook/media/v4l/func-read.xml181
-rw-r--r--Documentation/DocBook/media/v4l/func-select.xml130
-rw-r--r--Documentation/DocBook/media/v4l/func-write.xml128
-rw-r--r--Documentation/DocBook/media/v4l/gen-errors.xml77
-rw-r--r--Documentation/DocBook/media/v4l/io.xml1533
-rw-r--r--Documentation/DocBook/media/v4l/keytable.c.xml172
-rw-r--r--Documentation/DocBook/media/v4l/libv4l.xml160
-rw-r--r--Documentation/DocBook/media/v4l/lirc_device_interface.xml255
-rw-r--r--Documentation/DocBook/media/v4l/media-controller.xml89
-rw-r--r--Documentation/DocBook/media/v4l/media-func-close.xml59
-rw-r--r--Documentation/DocBook/media/v4l/media-func-ioctl.xml73
-rw-r--r--Documentation/DocBook/media/v4l/media-func-open.xml94
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-device-info.xml132
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml280
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-links.xml216
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-setup-link.xml84
-rw-r--r--Documentation/DocBook/media/v4l/pipeline.pdfbin20276 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-grey.xml62
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-m420.xml139
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12.xml143
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12m.xml153
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml66
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv16.xml166
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv16m.xml170
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv24.xml121
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml937
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml236
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml83
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml44
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml47
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml44
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml46
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml40
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10.xml90
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml34
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml28
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml99
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb12.xml90
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-uv8.xml62
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-uyvy.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-vyuy.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y10.xml79
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y10b.xml43
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y12.xml79
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y16.xml81
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y41p.xml149
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv410.xml133
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml147
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv420.xml149
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml154
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml153
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuyv.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml154
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yvyu.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml1801
-rw-r--r--Documentation/DocBook/media/v4l/planar-apis.xml62
-rw-r--r--Documentation/DocBook/media/v4l/remote_controllers.xml320
-rw-r--r--Documentation/DocBook/media/v4l/selection-api.xml324
-rw-r--r--Documentation/DocBook/media/v4l/selections-common.xml180
-rw-r--r--Documentation/DocBook/media/v4l/subdev-formats.xml4038
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia614
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg63
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-full.dia1588
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-full.svg163
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia1152
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg116
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml709
-rw-r--r--Documentation/DocBook/media/v4l/v4l2grab.c.xml164
-rw-r--r--Documentation/DocBook/media/v4l/vbi_525.pdfbin3395 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/vbi_625.pdfbin3683 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/vbi_hsync.pdfbin7405 -> 0 bytes-rw-r--r--Documentation/DocBook/media/v4l/vidioc-create-bufs.xml165
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-cropcap.xml166
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml207
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml227
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml249
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml468
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml214
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml189
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml133
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml159
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml259
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml264
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml181
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumaudio.xml76
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml79
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enuminput.xml316
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumoutput.xml201
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumstd.xml389
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-expbuf.xml210
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-audio.xml172
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-audioout.xml138
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-crop.xml129
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml133
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml341
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-edid.xml162
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml189
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml427
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml459
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fmt.xml204
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-frequency.xml148
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-input.xml83
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml175
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-modulator.xml240
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-output.xml85
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-parm.xml314
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-priority.xml135
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-selection.xml239
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml255
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-std.xml98
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-tuner.xml578
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-log-status.xml41
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-overlay.xml74
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml94
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-qbuf.xml192
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml110
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querybuf.xml105
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querycap.xml344
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-queryctrl.xml650
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querystd.xml75
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-reqbufs.xml137
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml188
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-streamon.xml128
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml157
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml159
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml124
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml158
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml183
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml141
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml165
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml129
-rw-r--r--Documentation/DocBook/media/vbi_525.gif.b6484
-rw-r--r--Documentation/DocBook/media/vbi_625.gif.b6490
-rw-r--r--Documentation/DocBook/media/vbi_hsync.gif.b6443
-rw-r--r--Documentation/DocBook/media_api.tmpl88
-rw-r--r--Documentation/DocBook/mtdnand.tmpl1292
-rw-r--r--Documentation/DocBook/networking.tmpl111
-rw-r--r--Documentation/DocBook/rapidio.tmpl158
-rw-r--r--Documentation/DocBook/regulator.tmpl304
-rw-r--r--Documentation/DocBook/s390-drivers.tmpl161
-rw-r--r--Documentation/DocBook/scsi.tmpl409
-rw-r--r--Documentation/DocBook/sh.tmpl105
-rw-r--r--Documentation/DocBook/stylesheet.xsl10
-rw-r--r--Documentation/DocBook/tracepoint.tmpl112
-rw-r--r--Documentation/DocBook/uio-howto.tmpl1050
-rw-r--r--Documentation/DocBook/usb.tmpl980
-rw-r--r--Documentation/DocBook/w1.tmpl101
-rw-r--r--Documentation/DocBook/writing-an-alsa-driver.tmpl6221
-rw-r--r--Documentation/DocBook/writing_musb_glue_layer.tmpl873
-rw-r--r--Documentation/DocBook/writing_usb_driver.tmpl412
-rw-r--r--Documentation/DocBook/z8530book.tmpl371
-rw-r--r--Documentation/EDID/1024x768.S44
-rw-r--r--Documentation/EDID/1280x1024.S44
-rw-r--r--Documentation/EDID/1600x1200.S44
-rw-r--r--Documentation/EDID/1680x1050.S44
-rw-r--r--Documentation/EDID/1920x1080.S44
-rw-r--r--Documentation/EDID/800x600.S41
-rw-r--r--Documentation/EDID/HOWTO.txt58
-rw-r--r--Documentation/EDID/Makefile26
-rw-r--r--Documentation/EDID/edid.S272
-rw-r--r--Documentation/EDID/hex1
-rw-r--r--Documentation/HOWTO609
-rw-r--r--Documentation/IPMI.txt719
-rw-r--r--Documentation/IRQ-affinity.txt65
-rw-r--r--Documentation/IRQ-domain.txt223
-rw-r--r--Documentation/IRQ.txt22
-rw-r--r--Documentation/Intel-IOMMU.txt111
-rw-r--r--Documentation/Kconfig28
-rw-r--r--Documentation/Makefile118
-rw-r--r--Documentation/ManagementStyle276
-rw-r--r--Documentation/PCI/00-INDEX14
-rw-r--r--Documentation/PCI/MSI-HOWTO.txt587
-rw-r--r--Documentation/PCI/PCIEBUS-HOWTO.txt217
-rw-r--r--Documentation/PCI/acpi-info.rst192
-rw-r--r--Documentation/PCI/boot-interrupts.rst159
-rw-r--r--Documentation/PCI/controller/index.rst10
-rw-r--r--Documentation/PCI/controller/rcar-pcie-firmware.rst32
-rw-r--r--Documentation/PCI/endpoint/function/binding/pci-ntb.rst38
-rw-r--r--Documentation/PCI/endpoint/function/binding/pci-test.rst26
-rw-r--r--Documentation/PCI/endpoint/index.rst21
-rw-r--r--Documentation/PCI/endpoint/pci-endpoint-cfs.rst138
-rw-r--r--Documentation/PCI/endpoint/pci-endpoint.rst259
-rw-r--r--Documentation/PCI/endpoint/pci-ntb-function.rst348
-rw-r--r--Documentation/PCI/endpoint/pci-ntb-howto.rst158
-rw-r--r--Documentation/PCI/endpoint/pci-nvme-function.rst13
-rw-r--r--Documentation/PCI/endpoint/pci-test-function.rst103
-rw-r--r--Documentation/PCI/endpoint/pci-test-howto.rst220
-rw-r--r--Documentation/PCI/endpoint/pci-vntb-function.rst129
-rw-r--r--Documentation/PCI/endpoint/pci-vntb-howto.rst169
-rw-r--r--Documentation/PCI/index.rst22
-rw-r--r--Documentation/PCI/msi-howto.rst297
-rw-r--r--Documentation/PCI/pci-error-recovery.rst472
-rw-r--r--Documentation/PCI/pci-error-recovery.txt431
-rw-r--r--Documentation/PCI/pci-iov-howto.rst171
-rw-r--r--Documentation/PCI/pci-iov-howto.txt135
-rw-r--r--Documentation/PCI/pci.rst578
-rw-r--r--Documentation/PCI/pci.txt635
-rw-r--r--Documentation/PCI/pcieaer-howto.rst257
-rw-r--r--Documentation/PCI/pcieaer-howto.txt270
-rw-r--r--Documentation/PCI/pciebus-howto.rst228
-rw-r--r--Documentation/PCI/sysfs-pci.rst138
-rw-r--r--Documentation/PCI/tph.rst132
-rw-r--r--Documentation/RCU/00-INDEX36
-rw-r--r--Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg474
-rw-r--r--Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg662
-rw-r--r--Documentation/RCU/Design/Data-Structures/Data-Structures.rst1196
-rw-r--r--Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg939
-rw-r--r--Documentation/RCU/Design/Data-Structures/TreeLevel.svg828
-rw-r--r--Documentation/RCU/Design/Data-Structures/TreeMapping.svg305
-rw-r--r--Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg380
-rw-r--r--Documentation/RCU/Design/Data-Structures/blkd_task.svg631
-rw-r--r--Documentation/RCU/Design/Data-Structures/nxtlist.svg386
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/ExpRCUFlow.svg830
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg830
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst521
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg275
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg275
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg287
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg323
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg323
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg335
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg335
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg347
-rw-r--r--Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg311
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst648
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg486
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg646
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-dyntick.svg700
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-cleanup.svg1133
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg1309
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-1.svg658
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-2.svg656
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-3.svg636
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg5135
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg775
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg1095
-rw-r--r--Documentation/RCU/Design/Memory-Ordering/rcu_node-lock.svg229
-rw-r--r--Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg374
-rw-r--r--Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg639
-rw-r--r--Documentation/RCU/Design/Requirements/Requirements.rst2866
-rw-r--r--Documentation/RCU/NMI-RCU.rst123
-rw-r--r--Documentation/RCU/NMI-RCU.txt120
-rw-r--r--Documentation/RCU/RTFP.txt120
-rw-r--r--Documentation/RCU/UP.rst152
-rw-r--r--Documentation/RCU/UP.txt135
-rw-r--r--Documentation/RCU/arrayRCU.txt141
-rw-r--r--Documentation/RCU/checklist.rst556
-rw-r--r--Documentation/RCU/checklist.txt437
-rw-r--r--Documentation/RCU/index.rst37
-rw-r--r--Documentation/RCU/listRCU.rst511
-rw-r--r--Documentation/RCU/listRCU.txt315
-rw-r--r--Documentation/RCU/lockdep-splat.rst115
-rw-r--r--Documentation/RCU/lockdep-splat.txt110
-rw-r--r--Documentation/RCU/lockdep.rst119
-rw-r--r--Documentation/RCU/lockdep.txt112
-rw-r--r--Documentation/RCU/rcu.rst93
-rw-r--r--Documentation/RCU/rcu.txt96
-rw-r--r--Documentation/RCU/rcu_dereference.rst502
-rw-r--r--Documentation/RCU/rcu_dereference.txt371
-rw-r--r--Documentation/RCU/rcubarrier.rst377
-rw-r--r--Documentation/RCU/rcubarrier.txt321
-rw-r--r--Documentation/RCU/rculist_nulls.rst215
-rw-r--r--Documentation/RCU/rculist_nulls.txt172
-rw-r--r--Documentation/RCU/rcuref.rst158
-rw-r--r--Documentation/RCU/rcuref.txt132
-rw-r--r--Documentation/RCU/stallwarn.rst491
-rw-r--r--Documentation/RCU/stallwarn.txt250
-rw-r--r--Documentation/RCU/torture.rst374
-rw-r--r--Documentation/RCU/torture.txt334
-rw-r--r--Documentation/RCU/trace.txt554
-rw-r--r--Documentation/RCU/whatisRCU.rst1415
-rw-r--r--Documentation/RCU/whatisRCU.txt1031
-rw-r--r--Documentation/SAK.txt88
-rw-r--r--Documentation/SM501.txt71
-rw-r--r--Documentation/SecurityBugs38
-rw-r--r--Documentation/SubmitChecklist109
-rw-r--r--Documentation/SubmittingDrivers163
-rw-r--r--Documentation/SubmittingPatches807
-rw-r--r--Documentation/VGA-softcursor.txt39
-rw-r--r--Documentation/accel/amdxdna/amdnpu.rst281
-rw-r--r--Documentation/accel/amdxdna/index.rst11
-rw-r--r--Documentation/accel/index.rst20
-rw-r--r--Documentation/accel/introduction.rst110
-rw-r--r--Documentation/accel/qaic/aic080.rst14
-rw-r--r--Documentation/accel/qaic/aic100.rst538
-rw-r--r--Documentation/accel/qaic/index.rst14
-rw-r--r--Documentation/accel/qaic/qaic.rst209
-rw-r--r--Documentation/accel/rocket/index.rst19
-rw-r--r--Documentation/accounting/.gitignore1
-rw-r--r--Documentation/accounting/Makefile7
-rw-r--r--Documentation/accounting/cgroupstats.rst31
-rw-r--r--Documentation/accounting/cgroupstats.txt27
-rw-r--r--Documentation/accounting/delay-accounting.rst214
-rw-r--r--Documentation/accounting/delay-accounting.txt117
-rw-r--r--Documentation/accounting/getdelays.c546
-rw-r--r--Documentation/accounting/index.rst14
-rw-r--r--Documentation/accounting/psi.rst188
-rw-r--r--Documentation/accounting/taskstats-struct.rst199
-rw-r--r--Documentation/accounting/taskstats-struct.txt180
-rw-r--r--Documentation/accounting/taskstats.rst182
-rw-r--r--Documentation/accounting/taskstats.txt181
-rw-r--r--Documentation/acpi/apei/einj.txt177
-rw-r--r--Documentation/acpi/apei/output_format.txt147
-rw-r--r--Documentation/acpi/debug.txt148
-rw-r--r--Documentation/acpi/dsdt-override.txt7
-rw-r--r--Documentation/acpi/enumeration.txt361
-rw-r--r--Documentation/acpi/gpio-properties.txt96
-rw-r--r--Documentation/acpi/initrd_table_override.txt94
-rw-r--r--Documentation/acpi/method-customizing.txt73
-rw-r--r--Documentation/acpi/method-tracing.txt26
-rw-r--r--Documentation/acpi/namespace.txt388
-rw-r--r--Documentation/acpi/scan_handlers.txt77
-rw-r--r--Documentation/acpi/video_extension.txt106
-rw-r--r--Documentation/admin-guide/LSM/LoadPin.rst31
-rw-r--r--Documentation/admin-guide/LSM/SELinux.rst44
-rw-r--r--Documentation/admin-guide/LSM/SafeSetID.rst118
-rw-r--r--Documentation/admin-guide/LSM/Smack.rst871
-rw-r--r--Documentation/admin-guide/LSM/Yama.rst75
-rw-r--r--Documentation/admin-guide/LSM/apparmor.rst54
-rw-r--r--Documentation/admin-guide/LSM/index.rst51
-rw-r--r--Documentation/admin-guide/LSM/ipe.rst835
-rw-r--r--Documentation/admin-guide/LSM/landlock.rst158
-rw-r--r--Documentation/admin-guide/LSM/tomoyo.rst52
-rw-r--r--Documentation/admin-guide/RAS/address-translation.rst24
-rw-r--r--Documentation/admin-guide/RAS/error-decoding.rst21
-rw-r--r--Documentation/admin-guide/RAS/index.rst7
-rw-r--r--Documentation/admin-guide/RAS/main.rst1087
-rw-r--r--Documentation/admin-guide/README.rst360
-rw-r--r--Documentation/admin-guide/abi-obsolete-files.rst7
-rw-r--r--Documentation/admin-guide/abi-obsolete.rst13
-rw-r--r--Documentation/admin-guide/abi-removed-files.rst7
-rw-r--r--Documentation/admin-guide/abi-removed.rst7
-rw-r--r--Documentation/admin-guide/abi-stable-files.rst7
-rw-r--r--Documentation/admin-guide/abi-stable.rst16
-rw-r--r--Documentation/admin-guide/abi-testing-files.rst7
-rw-r--r--Documentation/admin-guide/abi-testing.rst22
-rw-r--r--Documentation/admin-guide/abi.rst29
-rw-r--r--Documentation/admin-guide/acpi/cppc_sysfs.rst78
-rw-r--r--Documentation/admin-guide/acpi/fan_performance_states.rst90
-rw-r--r--Documentation/admin-guide/acpi/index.rst14
-rw-r--r--Documentation/admin-guide/acpi/initrd_table_override.rst115
-rw-r--r--Documentation/admin-guide/acpi/ssdt-overlays.rst181
-rw-r--r--Documentation/admin-guide/aoe/aoe.rst150
-rw-r--r--Documentation/admin-guide/aoe/autoload.sh (renamed from Documentation/aoe/autoload.sh)0
-rw-r--r--Documentation/admin-guide/aoe/examples.rst23
-rw-r--r--Documentation/admin-guide/aoe/index.rst17
-rw-r--r--Documentation/admin-guide/aoe/status.sh (renamed from Documentation/aoe/status.sh)0
-rw-r--r--Documentation/admin-guide/aoe/todo.rst17
-rw-r--r--Documentation/admin-guide/aoe/udev-install.sh (renamed from Documentation/aoe/udev-install.sh)0
-rw-r--r--Documentation/admin-guide/aoe/udev.txt26
-rw-r--r--Documentation/admin-guide/auxdisplay/cfag12864b.rst98
-rw-r--r--Documentation/admin-guide/auxdisplay/index.rst16
-rw-r--r--Documentation/admin-guide/auxdisplay/ks0108.rst50
-rw-r--r--Documentation/admin-guide/bcache.rst644
-rw-r--r--Documentation/admin-guide/binderfs.rst87
-rw-r--r--Documentation/admin-guide/binfmt-misc.rst151
-rw-r--r--Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg (renamed from Documentation/blockdev/drbd/DRBD-8.3-data-packets.svg)0
-rw-r--r--Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg (renamed from Documentation/blockdev/drbd/DRBD-data-packets.svg)0
-rw-r--r--Documentation/admin-guide/blockdev/drbd/conn-states-8.dot (renamed from Documentation/blockdev/drbd/conn-states-8.dot)0
-rw-r--r--Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst42
-rw-r--r--Documentation/admin-guide/blockdev/drbd/disk-states-8.dot (renamed from Documentation/blockdev/drbd/disk-states-8.dot)0
-rw-r--r--Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot (renamed from Documentation/blockdev/drbd/drbd-connection-state-overview.dot)0
-rw-r--r--Documentation/admin-guide/blockdev/drbd/figures.rst30
-rw-r--r--Documentation/admin-guide/blockdev/drbd/index.rst19
-rw-r--r--Documentation/admin-guide/blockdev/drbd/peer-states-8.dot8
-rw-r--r--Documentation/admin-guide/blockdev/floppy.rst255
-rw-r--r--Documentation/admin-guide/blockdev/index.rst17
-rw-r--r--Documentation/admin-guide/blockdev/nbd.rst31
-rw-r--r--Documentation/admin-guide/blockdev/paride.rst207
-rw-r--r--Documentation/admin-guide/blockdev/ramdisk.rst153
-rw-r--r--Documentation/admin-guide/blockdev/zoned_loop.rst182
-rw-r--r--Documentation/admin-guide/blockdev/zram.rst569
-rw-r--r--Documentation/admin-guide/bootconfig.rst327
-rw-r--r--Documentation/admin-guide/braille-console.rst38
-rw-r--r--Documentation/admin-guide/btmrvl.rst124
-rw-r--r--Documentation/admin-guide/bug-bisect.rst165
-rw-r--r--Documentation/admin-guide/bug-hunting.rst370
-rw-r--r--Documentation/admin-guide/cgroup-v1/blkio-controller.rst301
-rw-r--r--Documentation/admin-guide/cgroup-v1/cgroups.rst697
-rw-r--r--Documentation/admin-guide/cgroup-v1/cpuacct.rst50
-rw-r--r--Documentation/admin-guide/cgroup-v1/cpusets.rst884
-rw-r--r--Documentation/admin-guide/cgroup-v1/devices.rst132
-rw-r--r--Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst131
-rw-r--r--Documentation/admin-guide/cgroup-v1/hugetlb.rst139
-rw-r--r--Documentation/admin-guide/cgroup-v1/index.rst31
-rw-r--r--Documentation/admin-guide/cgroup-v1/memcg_test.rst344
-rw-r--r--Documentation/admin-guide/cgroup-v1/memory.rst964
-rw-r--r--Documentation/admin-guide/cgroup-v1/misc.rst4
-rw-r--r--Documentation/admin-guide/cgroup-v1/net_cls.rst44
-rw-r--r--Documentation/admin-guide/cgroup-v1/net_prio.rst57
-rw-r--r--Documentation/admin-guide/cgroup-v1/pids.rst93
-rw-r--r--Documentation/admin-guide/cgroup-v1/rdma.rst117
-rw-r--r--Documentation/admin-guide/cgroup-v2.rst3430
-rw-r--r--Documentation/admin-guide/cifs/authors.rst69
-rw-r--r--Documentation/admin-guide/cifs/changes.rst9
-rw-r--r--Documentation/admin-guide/cifs/index.rst21
-rw-r--r--Documentation/admin-guide/cifs/introduction.rst53
-rw-r--r--Documentation/admin-guide/cifs/todo.rst133
-rw-r--r--Documentation/admin-guide/cifs/usage.rst864
-rwxr-xr-xDocumentation/admin-guide/cifs/winucase_convert.pl (renamed from Documentation/filesystems/cifs/winucase_convert.pl)2
-rw-r--r--Documentation/admin-guide/clearing-warn-once.rst9
-rw-r--r--Documentation/admin-guide/cpu-load.rst117
-rw-r--r--Documentation/admin-guide/cputopology.rst101
-rw-r--r--Documentation/admin-guide/dell_rbu.rst128
-rw-r--r--Documentation/admin-guide/device-mapper/cache-policies.rst131
-rw-r--r--Documentation/admin-guide/device-mapper/cache.rst337
-rw-r--r--Documentation/admin-guide/device-mapper/delay.rst54
-rw-r--r--Documentation/admin-guide/device-mapper/dm-clone.rst333
-rw-r--r--Documentation/admin-guide/device-mapper/dm-crypt.rst212
-rw-r--r--Documentation/admin-guide/device-mapper/dm-dust.rst305
-rw-r--r--Documentation/admin-guide/device-mapper/dm-ebs.rst51
-rw-r--r--Documentation/admin-guide/device-mapper/dm-flakey.rst88
-rw-r--r--Documentation/admin-guide/device-mapper/dm-ima.rst715
-rw-r--r--Documentation/admin-guide/device-mapper/dm-init.rst133
-rw-r--r--Documentation/admin-guide/device-mapper/dm-integrity.rst308
-rw-r--r--Documentation/admin-guide/device-mapper/dm-io.rst75
-rw-r--r--Documentation/admin-guide/device-mapper/dm-log.rst57
-rw-r--r--Documentation/admin-guide/device-mapper/dm-pcache.rst202
-rw-r--r--Documentation/admin-guide/device-mapper/dm-queue-length.rst48
-rw-r--r--Documentation/admin-guide/device-mapper/dm-raid.rst423
-rw-r--r--Documentation/admin-guide/device-mapper/dm-service-time.rst101
-rw-r--r--Documentation/admin-guide/device-mapper/dm-uevent.rst110
-rw-r--r--Documentation/admin-guide/device-mapper/dm-zoned.rst194
-rw-r--r--Documentation/admin-guide/device-mapper/era.rst116
-rw-r--r--Documentation/admin-guide/device-mapper/index.rst49
-rw-r--r--Documentation/admin-guide/device-mapper/kcopyd.rst47
-rw-r--r--Documentation/admin-guide/device-mapper/linear.rst63
-rw-r--r--Documentation/admin-guide/device-mapper/log-writes.rst145
-rw-r--r--Documentation/admin-guide/device-mapper/persistent-data.rst88
-rw-r--r--Documentation/admin-guide/device-mapper/snapshot.rst196
-rw-r--r--Documentation/admin-guide/device-mapper/statistics.rst225
-rw-r--r--Documentation/admin-guide/device-mapper/striped.rst61
-rw-r--r--Documentation/admin-guide/device-mapper/switch.rst141
-rw-r--r--Documentation/admin-guide/device-mapper/thin-provisioning.rst427
-rw-r--r--Documentation/admin-guide/device-mapper/unstriped.rst135
-rw-r--r--Documentation/admin-guide/device-mapper/vdo-design.rst633
-rw-r--r--Documentation/admin-guide/device-mapper/vdo.rst413
-rw-r--r--Documentation/admin-guide/device-mapper/verity.rst265
-rw-r--r--Documentation/admin-guide/device-mapper/writecache.rst114
-rw-r--r--Documentation/admin-guide/device-mapper/zero.rst37
-rw-r--r--Documentation/admin-guide/devices.rst268
-rw-r--r--Documentation/admin-guide/devices.txt3082
-rw-r--r--Documentation/admin-guide/dynamic-debug-howto.rst383
-rw-r--r--Documentation/admin-guide/edid.rst27
-rw-r--r--Documentation/admin-guide/efi-stub.rst103
-rw-r--r--Documentation/admin-guide/ext4.rst613
-rw-r--r--Documentation/admin-guide/features.rst3
-rw-r--r--Documentation/admin-guide/filesystem-monitoring.rst78
-rw-r--r--Documentation/admin-guide/gpio/gpio-aggregator.rst218
-rw-r--r--Documentation/admin-guide/gpio/gpio-mockup.rst59
-rw-r--r--Documentation/admin-guide/gpio/gpio-sim.rst137
-rw-r--r--Documentation/admin-guide/gpio/gpio-virtuser.rst177
-rw-r--r--Documentation/admin-guide/gpio/index.rst21
-rw-r--r--Documentation/admin-guide/gpio/obsolete.rst13
-rw-r--r--Documentation/admin-guide/hw-vuln/attack_vector_controls.rst236
-rw-r--r--Documentation/admin-guide/hw-vuln/core-scheduling.rst226
-rw-r--r--Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst91
-rw-r--r--Documentation/admin-guide/hw-vuln/gather_data_sampling.rst109
-rw-r--r--Documentation/admin-guide/hw-vuln/index.rst29
-rw-r--r--Documentation/admin-guide/hw-vuln/indirect-target-selection.rst168
-rw-r--r--Documentation/admin-guide/hw-vuln/l1d_flush.rst69
-rw-r--r--Documentation/admin-guide/hw-vuln/l1tf.rst615
-rw-r--r--Documentation/admin-guide/hw-vuln/mds.rst303
-rw-r--r--Documentation/admin-guide/hw-vuln/multihit.rst167
-rw-r--r--Documentation/admin-guide/hw-vuln/old_microcode.rst21
-rw-r--r--Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst269
-rw-r--r--Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst96
-rw-r--r--Documentation/admin-guide/hw-vuln/rsb.rst268
-rw-r--r--Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst150
-rw-r--r--Documentation/admin-guide/hw-vuln/spectre.rst725
-rw-r--r--Documentation/admin-guide/hw-vuln/srso.rst242
-rw-r--r--Documentation/admin-guide/hw-vuln/tsx_async_abort.rst270
-rw-r--r--Documentation/admin-guide/hw-vuln/vmscape.rst110
-rw-r--r--Documentation/admin-guide/hw_random.rst104
-rw-r--r--Documentation/admin-guide/index.rst198
-rw-r--r--Documentation/admin-guide/init.rst48
-rw-r--r--Documentation/admin-guide/initrd.rst383
-rw-r--r--Documentation/admin-guide/iostats.rst187
-rw-r--r--Documentation/admin-guide/java.rst423
-rw-r--r--Documentation/admin-guide/jfs.rst66
-rw-r--r--Documentation/admin-guide/kdump/gdbmacros.txt323
-rw-r--r--Documentation/admin-guide/kdump/index.rst20
-rw-r--r--Documentation/admin-guide/kdump/kdump.rst612
-rw-r--r--Documentation/admin-guide/kdump/vmcoreinfo.rst596
-rw-r--r--Documentation/admin-guide/kernel-parameters.rst135
-rw-r--r--Documentation/admin-guide/kernel-parameters.txt8531
-rw-r--r--Documentation/admin-guide/kernel-per-CPU-kthreads.rst325
-rw-r--r--Documentation/admin-guide/laptops/alienware-wmi.rst127
-rw-r--r--Documentation/admin-guide/laptops/asus-laptop.rst271
-rw-r--r--Documentation/admin-guide/laptops/disk-shock-protection.rst151
-rw-r--r--Documentation/admin-guide/laptops/index.rst20
-rw-r--r--Documentation/admin-guide/laptops/laptop-mode.rst770
-rw-r--r--Documentation/admin-guide/laptops/lg-laptop.rst82
-rw-r--r--Documentation/admin-guide/laptops/samsung-galaxybook.rst174
-rw-r--r--Documentation/admin-guide/laptops/sony-laptop.rst174
-rw-r--r--Documentation/admin-guide/laptops/sonypi.rst158
-rw-r--r--Documentation/admin-guide/laptops/thinkpad-acpi.rst1691
-rw-r--r--Documentation/admin-guide/laptops/toshiba_haps.rst87
-rw-r--r--Documentation/admin-guide/laptops/uniwill-laptop.rst60
-rw-r--r--Documentation/admin-guide/lcd-panel-cgram.rst27
-rw-r--r--Documentation/admin-guide/ldm.rst121
-rw-r--r--Documentation/admin-guide/lockup-watchdogs.rst83
-rw-r--r--Documentation/admin-guide/md.rst811
-rw-r--r--Documentation/admin-guide/media/au0828-cardlist.rst39
-rw-r--r--Documentation/admin-guide/media/avermedia.rst94
-rw-r--r--Documentation/admin-guide/media/bt8xx.rst157
-rw-r--r--Documentation/admin-guide/media/bttv-cardlist.rst683
-rw-r--r--Documentation/admin-guide/media/bttv.rst1762
-rw-r--r--Documentation/admin-guide/media/building.rst357
-rw-r--r--Documentation/admin-guide/media/c3-isp.dot26
-rw-r--r--Documentation/admin-guide/media/c3-isp.rst101
-rw-r--r--Documentation/admin-guide/media/cafe_ccic.rst62
-rw-r--r--Documentation/admin-guide/media/cardlist.rst29
-rw-r--r--Documentation/admin-guide/media/cec.rst467
-rw-r--r--Documentation/admin-guide/media/ci.rst77
-rw-r--r--Documentation/admin-guide/media/cx18-cardlist.rst17
-rw-r--r--Documentation/admin-guide/media/cx231xx-cardlist.rst99
-rw-r--r--Documentation/admin-guide/media/cx23885-cardlist.rst267
-rw-r--r--Documentation/admin-guide/media/cx88-cardlist.rst383
-rw-r--r--Documentation/admin-guide/media/cx88.rst58
-rw-r--r--Documentation/admin-guide/media/dvb-drivers.rst15
-rw-r--r--Documentation/admin-guide/media/dvb-usb-a800-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-af9005-cardlist.rst20
-rw-r--r--Documentation/admin-guide/media/dvb-usb-af9015-cardlist.rst80
-rw-r--r--Documentation/admin-guide/media/dvb-usb-af9035-cardlist.rst74
-rw-r--r--Documentation/admin-guide/media/dvb-usb-anysee-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-au6610-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-az6007-cardlist.rst20
-rw-r--r--Documentation/admin-guide/media/dvb-usb-az6027-cardlist.rst24
-rw-r--r--Documentation/admin-guide/media/dvb-usb-ce6230-cardlist.rst18
-rw-r--r--Documentation/admin-guide/media/dvb-usb-cinergyT2-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-cxusb-cardlist.rst40
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dib0700-cardlist.rst162
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dibusb-mb-cardlist.rst42
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dibusb-mc-cardlist.rst30
-rw-r--r--Documentation/admin-guide/media/dvb-usb-digitv-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dtt200u-cardlist.rst22
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dtv5100-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dvbsky-cardlist.rst42
-rw-r--r--Documentation/admin-guide/media/dvb-usb-dw2102-cardlist.rst56
-rw-r--r--Documentation/admin-guide/media/dvb-usb-ec168-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-gl861-cardlist.rst20
-rw-r--r--Documentation/admin-guide/media/dvb-usb-gp8psk-cardlist.rst22
-rw-r--r--Documentation/admin-guide/media/dvb-usb-lmedm04-cardlist.rst20
-rw-r--r--Documentation/admin-guide/media/dvb-usb-m920x-cardlist.rst26
-rw-r--r--Documentation/admin-guide/media/dvb-usb-mxl111sf-cardlist.rst36
-rw-r--r--Documentation/admin-guide/media/dvb-usb-nova-t-usb2-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-opera1-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-pctv452e-cardlist.rst20
-rw-r--r--Documentation/admin-guide/media/dvb-usb-rtl28xxu-cardlist.rst80
-rw-r--r--Documentation/admin-guide/media/dvb-usb-technisat-usb2-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-ttusb2-cardlist.rst24
-rw-r--r--Documentation/admin-guide/media/dvb-usb-umt-010-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-vp702x-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb-usb-vp7045-cardlist.rst18
-rw-r--r--Documentation/admin-guide/media/dvb-usb-zd1301-cardlist.rst16
-rw-r--r--Documentation/admin-guide/media/dvb.rst12
-rw-r--r--Documentation/admin-guide/media/dvb_intro.rst616
-rw-r--r--Documentation/admin-guide/media/dvb_references.rst29
-rw-r--r--Documentation/admin-guide/media/em28xx-cardlist.rst448
-rw-r--r--Documentation/admin-guide/media/faq.rst216
-rw-r--r--Documentation/admin-guide/media/fimc.rst153
-rw-r--r--Documentation/admin-guide/media/frontend-cardlist.rst226
-rw-r--r--Documentation/admin-guide/media/gspca-cardlist.rst451
-rw-r--r--Documentation/admin-guide/media/i2c-cardlist.rst287
-rw-r--r--Documentation/admin-guide/media/imx.rst714
-rw-r--r--Documentation/admin-guide/media/imx6q-sabreauto.dot51
-rw-r--r--Documentation/admin-guide/media/imx6q-sabresd.dot56
-rw-r--r--Documentation/admin-guide/media/imx7.rst221
-rw-r--r--Documentation/admin-guide/media/index.rst61
-rw-r--r--Documentation/admin-guide/media/intro.rst27
-rw-r--r--Documentation/admin-guide/media/ipu3.rst596
-rw-r--r--Documentation/admin-guide/media/ipu3_rcb.svg331
-rw-r--r--Documentation/admin-guide/media/ipu6-isys.rst161
-rw-r--r--Documentation/admin-guide/media/ipu6_isys_graph.svg548
-rw-r--r--Documentation/admin-guide/media/ivtv-cardlist.rst139
-rw-r--r--Documentation/admin-guide/media/ivtv.rst218
-rw-r--r--Documentation/admin-guide/media/lmedm04.rst107
-rw-r--r--Documentation/admin-guide/media/mali-c55-graph.dot19
-rw-r--r--Documentation/admin-guide/media/mali-c55.rst413
-rw-r--r--Documentation/admin-guide/media/mgb4.rst385
-rw-r--r--Documentation/admin-guide/media/misc-cardlist.rst28
-rw-r--r--Documentation/admin-guide/media/omap3isp.rst92
-rw-r--r--Documentation/admin-guide/media/opera-firmware.rst33
-rw-r--r--Documentation/admin-guide/media/other-usb-cardlist.rst78
-rw-r--r--Documentation/admin-guide/media/pci-cardlist.rst108
-rw-r--r--Documentation/admin-guide/media/philips.rst247
-rw-r--r--Documentation/admin-guide/media/platform-cardlist.rst87
-rw-r--r--Documentation/admin-guide/media/qcom_camss.rst185
-rw-r--r--Documentation/admin-guide/media/qcom_camss_8x96_graph.dot106
-rw-r--r--Documentation/admin-guide/media/qcom_camss_graph.dot43
-rw-r--r--Documentation/admin-guide/media/radio-cardlist.rst43
-rw-r--r--Documentation/admin-guide/media/raspberrypi-pisp-be.dot20
-rw-r--r--Documentation/admin-guide/media/raspberrypi-pisp-be.rst109
-rw-r--r--Documentation/admin-guide/media/raspberrypi-rp1-cfe.dot27
-rw-r--r--Documentation/admin-guide/media/raspberrypi-rp1-cfe.rst78
-rw-r--r--Documentation/admin-guide/media/rcar-fdp1.rst39
-rw-r--r--Documentation/admin-guide/media/remote-controller.rst76
-rw-r--r--Documentation/admin-guide/media/rkcif-rk3568-vicap.dot8
-rw-r--r--Documentation/admin-guide/media/rkcif.rst79
-rw-r--r--Documentation/admin-guide/media/rkisp1.dot18
-rw-r--r--Documentation/admin-guide/media/rkisp1.rst204
-rw-r--r--Documentation/admin-guide/media/saa7134-cardlist.rst803
-rw-r--r--Documentation/admin-guide/media/saa7134.rst89
-rw-r--r--Documentation/admin-guide/media/saa7164-cardlist.rst71
-rw-r--r--Documentation/admin-guide/media/si470x.rst167
-rw-r--r--Documentation/admin-guide/media/si4713.rst192
-rw-r--r--Documentation/admin-guide/media/si476x.rst160
-rw-r--r--Documentation/admin-guide/media/siano-cardlist.rst56
-rw-r--r--Documentation/admin-guide/media/starfive_camss.rst72
-rw-r--r--Documentation/admin-guide/media/starfive_camss_graph.dot12
-rw-r--r--Documentation/admin-guide/media/technisat.rst100
-rw-r--r--Documentation/admin-guide/media/ttusb-dec.rst45
-rw-r--r--Documentation/admin-guide/media/tuner-cardlist.rst102
-rw-r--r--Documentation/admin-guide/media/usb-cardlist.rst149
-rw-r--r--Documentation/admin-guide/media/v4l-drivers.rst39
-rw-r--r--Documentation/admin-guide/media/vimc.dot26
-rw-r--r--Documentation/admin-guide/media/vimc.rst110
-rw-r--r--Documentation/admin-guide/media/visl.rst185
-rw-r--r--Documentation/admin-guide/media/vivid.rst1361
-rw-r--r--Documentation/admin-guide/media/zoran-cardlist.rst51
-rw-r--r--Documentation/admin-guide/mm/cma_debugfs.rst31
-rw-r--r--Documentation/admin-guide/mm/concepts.rst220
-rw-r--r--Documentation/admin-guide/mm/damon/index.rst17
-rw-r--r--Documentation/admin-guide/mm/damon/lru_sort.rst316
-rw-r--r--Documentation/admin-guide/mm/damon/reclaim.rst323
-rw-r--r--Documentation/admin-guide/mm/damon/start.rst178
-rw-r--r--Documentation/admin-guide/mm/damon/stat.rst86
-rw-r--r--Documentation/admin-guide/mm/damon/usage.rst684
-rw-r--r--Documentation/admin-guide/mm/hugetlbpage.rst490
-rw-r--r--Documentation/admin-guide/mm/idle_page_tracking.rst118
-rw-r--r--Documentation/admin-guide/mm/index.rst45
-rw-r--r--Documentation/admin-guide/mm/kho.rst115
-rw-r--r--Documentation/admin-guide/mm/ksm.rst323
-rw-r--r--Documentation/admin-guide/mm/memory-hotplug.rst696
-rw-r--r--Documentation/admin-guide/mm/multigen_lru.rst163
-rw-r--r--Documentation/admin-guide/mm/nommu-mmap.rst283
-rw-r--r--Documentation/admin-guide/mm/numa_memory_policy.rst523
-rw-r--r--Documentation/admin-guide/mm/numaperf.rst176
-rw-r--r--Documentation/admin-guide/mm/pagemap.rst317
-rw-r--r--Documentation/admin-guide/mm/shrinker_debugfs.rst133
-rw-r--r--Documentation/admin-guide/mm/slab.rst469
-rw-r--r--Documentation/admin-guide/mm/soft-dirty.rst45
-rw-r--r--Documentation/admin-guide/mm/transhuge.rst745
-rw-r--r--Documentation/admin-guide/mm/userfaultfd.rst430
-rw-r--r--Documentation/admin-guide/mm/zswap.rst138
-rw-r--r--Documentation/admin-guide/module-signing.rst290
-rw-r--r--Documentation/admin-guide/mono.rst70
-rw-r--r--Documentation/admin-guide/namespaces/compatibility-list.rst43
-rw-r--r--Documentation/admin-guide/namespaces/index.rst11
-rw-r--r--Documentation/admin-guide/namespaces/resource-control.rst18
-rw-r--r--Documentation/admin-guide/nfs/index.rst14
-rw-r--r--Documentation/admin-guide/nfs/nfs-client.rst144
-rw-r--r--Documentation/admin-guide/nfs/nfs-idmapper.rst78
-rw-r--r--Documentation/admin-guide/nfs/nfs-rdma.rst292
-rw-r--r--Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst40
-rw-r--r--Documentation/admin-guide/nfs/nfsroot.rst364
-rw-r--r--Documentation/admin-guide/nfs/pnfs-block-server.rst42
-rw-r--r--Documentation/admin-guide/nfs/pnfs-scsi-server.rst24
-rw-r--r--Documentation/admin-guide/numastat.rst55
-rw-r--r--Documentation/admin-guide/nvme-multipath.rst72
-rw-r--r--Documentation/admin-guide/parport.rst286
-rw-r--r--Documentation/admin-guide/perf-security.rst325
-rw-r--r--Documentation/admin-guide/perf/alibaba_pmu.rst105
-rw-r--r--Documentation/admin-guide/perf/ampere_cspmu.rst29
-rw-r--r--Documentation/admin-guide/perf/arm-ccn.rst61
-rw-r--r--Documentation/admin-guide/perf/arm-cmn.rst65
-rw-r--r--Documentation/admin-guide/perf/arm-ni.rst17
-rw-r--r--Documentation/admin-guide/perf/arm_dsu_pmu.rst29
-rw-r--r--Documentation/admin-guide/perf/cxl.rst68
-rw-r--r--Documentation/admin-guide/perf/dwc_pcie_pmu.rst94
-rw-r--r--Documentation/admin-guide/perf/fujitsu_uncore_pmu.rst115
-rw-r--r--Documentation/admin-guide/perf/hisi-pcie-pmu.rst148
-rw-r--r--Documentation/admin-guide/perf/hisi-pmu.rst177
-rw-r--r--Documentation/admin-guide/perf/hns3-pmu.rst136
-rw-r--r--Documentation/admin-guide/perf/imx-ddr.rst100
-rw-r--r--Documentation/admin-guide/perf/index.rst32
-rw-r--r--Documentation/admin-guide/perf/meson-ddr-pmu.rst70
-rw-r--r--Documentation/admin-guide/perf/mrvl-odyssey-ddr-pmu.rst80
-rw-r--r--Documentation/admin-guide/perf/mrvl-odyssey-tad-pmu.rst37
-rw-r--r--Documentation/admin-guide/perf/mrvl-pem-pmu.rst56
-rw-r--r--Documentation/admin-guide/perf/nvidia-pmu.rst333
-rw-r--r--Documentation/admin-guide/perf/qcom_l2_pmu.rst39
-rw-r--r--Documentation/admin-guide/perf/qcom_l3_pmu.rst26
-rw-r--r--Documentation/admin-guide/perf/starfive_starlink_pmu.rst46
-rw-r--r--Documentation/admin-guide/perf/thunderx2-pmu.rst44
-rw-r--r--Documentation/admin-guide/perf/xgene-pmu.rst49
-rw-r--r--Documentation/admin-guide/pm/amd-pstate.rst802
-rw-r--r--Documentation/admin-guide/pm/cpufreq.rst725
-rw-r--r--Documentation/admin-guide/pm/cpufreq_drivers.rst274
-rw-r--r--Documentation/admin-guide/pm/cpuidle.rst666
-rw-r--r--Documentation/admin-guide/pm/index.rst12
-rw-r--r--Documentation/admin-guide/pm/intel-speed-select.rst939
-rw-r--r--Documentation/admin-guide/pm/intel_epb.rst41
-rw-r--r--Documentation/admin-guide/pm/intel_idle.rst316
-rw-r--r--Documentation/admin-guide/pm/intel_pstate.rst888
-rw-r--r--Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst184
-rw-r--r--Documentation/admin-guide/pm/sleep-states.rst291
-rw-r--r--Documentation/admin-guide/pm/strategies.rst56
-rw-r--r--Documentation/admin-guide/pm/suspend-flows.rst270
-rw-r--r--Documentation/admin-guide/pm/system-wide.rst11
-rw-r--r--Documentation/admin-guide/pm/working-state.rst18
-rw-r--r--Documentation/admin-guide/pnp.rst285
-rw-r--r--Documentation/admin-guide/pstore-blk.rst234
-rw-r--r--Documentation/admin-guide/quickly-build-trimmed-linux.rst1097
-rw-r--r--Documentation/admin-guide/ramoops.rst177
-rw-r--r--Documentation/admin-guide/rapidio.rst107
-rw-r--r--Documentation/admin-guide/reporting-issues.rst1764
-rw-r--r--Documentation/admin-guide/reporting-regressions.rst451
-rw-r--r--Documentation/admin-guide/rtc.rst140
-rw-r--r--Documentation/admin-guide/serial-console.rst147
-rw-r--r--Documentation/admin-guide/spkguide.txt1625
-rw-r--r--Documentation/admin-guide/svga.rst250
-rw-r--r--Documentation/admin-guide/syscall-user-dispatch.rst99
-rw-r--r--Documentation/admin-guide/sysctl/abi.rst34
-rw-r--r--Documentation/admin-guide/sysctl/fs.rst374
-rw-r--r--Documentation/admin-guide/sysctl/index.rst104
-rw-r--r--Documentation/admin-guide/sysctl/kernel.rst1738
-rw-r--r--Documentation/admin-guide/sysctl/net.rst544
-rw-r--r--Documentation/admin-guide/sysctl/sunrpc.rst25
-rw-r--r--Documentation/admin-guide/sysctl/user.rst84
-rw-r--r--Documentation/admin-guide/sysctl/vm.rst1125
-rw-r--r--Documentation/admin-guide/sysfs-rules.rst192
-rw-r--r--Documentation/admin-guide/sysrq.rst312
-rw-r--r--Documentation/admin-guide/tainted-kernels.rst191
-rw-r--r--Documentation/admin-guide/thermal/index.rst9
-rw-r--r--Documentation/admin-guide/thermal/intel_powerclamp.rst345
-rw-r--r--Documentation/admin-guide/thermal/intel_thermal_throttle.rst91
-rw-r--r--Documentation/admin-guide/thunderbolt.rst384
-rw-r--r--Documentation/admin-guide/ufs.rst68
-rw-r--r--Documentation/admin-guide/unicode.rst188
-rw-r--r--Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst2222
-rw-r--r--Documentation/admin-guide/vga-softcursor.rst62
-rw-r--r--Documentation/admin-guide/video-output.rst34
-rw-r--r--Documentation/admin-guide/workload-tracing.rst606
-rw-r--r--Documentation/admin-guide/xfs.rst551
-rw-r--r--Documentation/aoe/aoe.txt143
-rw-r--r--Documentation/aoe/todo.txt14
-rw-r--r--Documentation/aoe/udev.txt26
-rw-r--r--Documentation/applying-patches.txt454
-rw-r--r--Documentation/arch/arc/arc.rst85
-rw-r--r--Documentation/arch/arc/features.rst3
-rw-r--r--Documentation/arch/arc/index.rst17
-rw-r--r--Documentation/arch/arm/arm.rst212
-rw-r--r--Documentation/arch/arm/booting.rst237
-rw-r--r--Documentation/arch/arm/cluster-pm-race-avoidance.rst533
-rw-r--r--Documentation/arch/arm/features.rst3
-rw-r--r--Documentation/arch/arm/firmware.rst72
-rw-r--r--Documentation/arch/arm/google/chromebook-boot-flow.rst69
-rw-r--r--Documentation/arch/arm/index.rst85
-rw-r--r--Documentation/arch/arm/interrupts.rst169
-rw-r--r--Documentation/arch/arm/ixp4xx.rst173
-rw-r--r--Documentation/arch/arm/kernel_mode_neon.rst124
-rw-r--r--Documentation/arch/arm/kernel_user_helpers.rst268
-rw-r--r--Documentation/arch/arm/keystone/knav-qmss.rst60
-rw-r--r--Documentation/arch/arm/keystone/overview.rst74
-rw-r--r--Documentation/arch/arm/marvell.rst527
-rw-r--r--Documentation/arch/arm/mem_alignment.rst63
-rw-r--r--Documentation/arch/arm/memory.rst103
-rw-r--r--Documentation/arch/arm/microchip.rst230
-rw-r--r--Documentation/arch/arm/netwinder.rst85
-rw-r--r--Documentation/arch/arm/nwfpe/index.rst13
-rw-r--r--Documentation/arch/arm/nwfpe/netwinder-fpe.rst162
-rw-r--r--Documentation/arch/arm/nwfpe/notes.rst32
-rw-r--r--Documentation/arch/arm/nwfpe/nwfpe.rst74
-rw-r--r--Documentation/arch/arm/nwfpe/todo.rst72
-rw-r--r--Documentation/arch/arm/omap/dss.rst372
-rw-r--r--Documentation/arch/arm/omap/index.rst12
-rw-r--r--Documentation/arch/arm/omap/omap.rst18
-rw-r--r--Documentation/arch/arm/omap/omap_pm.rst165
-rw-r--r--Documentation/arch/arm/porting.rst137
-rw-r--r--Documentation/arch/arm/pxa/mfp.rst288
-rw-r--r--Documentation/arch/arm/sa1100/assabet.rst301
-rw-r--r--Documentation/arch/arm/sa1100/cerf.rst35
-rw-r--r--Documentation/arch/arm/sa1100/index.rst13
-rw-r--r--Documentation/arch/arm/sa1100/lart.rst15
-rw-r--r--Documentation/arch/arm/sa1100/serial_uart.rst51
-rw-r--r--Documentation/arch/arm/samsung/bootloader-interface.rst81
-rwxr-xr-xDocumentation/arch/arm/samsung/clksrc-change-registers.awk (renamed from Documentation/arm/Samsung/clksrc-change-registers.awk)2
-rw-r--r--Documentation/arch/arm/samsung/gpio.rst32
-rw-r--r--Documentation/arch/arm/samsung/index.rst12
-rw-r--r--Documentation/arch/arm/samsung/overview.rst76
-rw-r--r--Documentation/arch/arm/setup.rst108
-rw-r--r--Documentation/arch/arm/spear/overview.rst66
-rw-r--r--Documentation/arch/arm/sti/overview.rst32
-rw-r--r--Documentation/arch/arm/sti/stih407-overview.rst19
-rw-r--r--Documentation/arch/arm/sti/stih418-overview.rst21
-rw-r--r--Documentation/arch/arm/stm32/overview.rst34
-rw-r--r--Documentation/arch/arm/stm32/stm32-dma-mdma-chaining.rst415
-rw-r--r--Documentation/arch/arm/stm32/stm32f429-overview.rst25
-rw-r--r--Documentation/arch/arm/stm32/stm32f746-overview.rst32
-rw-r--r--Documentation/arch/arm/stm32/stm32f769-overview.rst34
-rw-r--r--Documentation/arch/arm/stm32/stm32h743-overview.rst33
-rw-r--r--Documentation/arch/arm/stm32/stm32h750-overview.rst34
-rw-r--r--Documentation/arch/arm/stm32/stm32mp13-overview.rst37
-rw-r--r--Documentation/arch/arm/stm32/stm32mp151-overview.rst36
-rw-r--r--Documentation/arch/arm/stm32/stm32mp157-overview.rst20
-rw-r--r--Documentation/arch/arm/sunxi.rst170
-rw-r--r--Documentation/arch/arm/sunxi/clocks.rst57
-rw-r--r--Documentation/arch/arm/swp_emulation.rst27
-rw-r--r--Documentation/arch/arm/tcm.rst161
-rw-r--r--Documentation/arch/arm/uefi.rst72
-rw-r--r--Documentation/arch/arm/vfp/release-notes.rst57
-rw-r--r--Documentation/arch/arm/vlocks.rst212
-rw-r--r--Documentation/arch/arm64/acpi_object_usage.rst809
-rw-r--r--Documentation/arch/arm64/amu.rst119
-rw-r--r--Documentation/arch/arm64/arm-acpi.rst575
-rw-r--r--Documentation/arch/arm64/arm-cca.rst69
-rw-r--r--Documentation/arch/arm64/asymmetric-32bit.rst163
-rw-r--r--Documentation/arch/arm64/booting.rst608
-rw-r--r--Documentation/arch/arm64/cpu-feature-registers.rst419
-rw-r--r--Documentation/arch/arm64/cpu-hotplug.rst79
-rw-r--r--Documentation/arch/arm64/elf_hwcaps.rst452
-rw-r--r--Documentation/arch/arm64/features.rst3
-rw-r--r--Documentation/arch/arm64/gcs.rst227
-rw-r--r--Documentation/arch/arm64/hugetlbpage.rst43
-rw-r--r--Documentation/arch/arm64/index.rst42
-rw-r--r--Documentation/arch/arm64/kasan-offsets.sh26
-rw-r--r--Documentation/arch/arm64/kdump.rst92
-rw-r--r--Documentation/arch/arm64/legacy_instructions.rst68
-rw-r--r--Documentation/arch/arm64/memory-tagging-extension.rst375
-rw-r--r--Documentation/arch/arm64/memory.rst100
-rw-r--r--Documentation/arch/arm64/mops.rst44
-rw-r--r--Documentation/arch/arm64/perf.rst238
-rw-r--r--Documentation/arch/arm64/pointer-authentication.rst142
-rw-r--r--Documentation/arch/arm64/ptdump.rst94
-rw-r--r--Documentation/arch/arm64/silicon-errata.rst307
-rw-r--r--Documentation/arch/arm64/sme.rst461
-rw-r--r--Documentation/arch/arm64/sve.rst619
-rw-r--r--Documentation/arch/arm64/tagged-address-abi.rst179
-rw-r--r--Documentation/arch/arm64/tagged-pointers.rst89
-rw-r--r--Documentation/arch/index.rst27
-rw-r--r--Documentation/arch/loongarch/booting.rst42
-rw-r--r--Documentation/arch/loongarch/features.rst3
-rw-r--r--Documentation/arch/loongarch/index.rst22
-rw-r--r--Documentation/arch/loongarch/introduction.rst390
-rw-r--r--Documentation/arch/loongarch/irq-chip-model.rst256
-rw-r--r--Documentation/arch/m68k/buddha-driver.rst209
-rw-r--r--Documentation/arch/m68k/features.rst3
-rw-r--r--Documentation/arch/m68k/index.rst20
-rw-r--r--Documentation/arch/m68k/kernel-options.rst911
-rw-r--r--Documentation/arch/mips/booting.rst28
-rw-r--r--Documentation/arch/mips/features.rst3
-rw-r--r--Documentation/arch/mips/index.rst21
-rw-r--r--Documentation/arch/mips/ingenic-tcu.rst71
-rw-r--r--Documentation/arch/nios2/features.rst3
-rw-r--r--Documentation/arch/nios2/index.rst12
-rw-r--r--Documentation/arch/nios2/nios2.rst24
-rw-r--r--Documentation/arch/openrisc/features.rst3
-rw-r--r--Documentation/arch/openrisc/index.rst20
-rw-r--r--Documentation/arch/openrisc/openrisc_port.rst127
-rw-r--r--Documentation/arch/openrisc/todo.rst15
-rw-r--r--Documentation/arch/parisc/debugging.rst46
-rw-r--r--Documentation/arch/parisc/features.rst3
-rw-r--r--Documentation/arch/parisc/index.rst20
-rw-r--r--Documentation/arch/parisc/registers.rst154
-rw-r--r--Documentation/arch/powerpc/associativity.rst105
-rw-r--r--Documentation/arch/powerpc/booting.rst110
-rw-r--r--Documentation/arch/powerpc/bootwrapper.rst131
-rw-r--r--Documentation/arch/powerpc/cpu_families.rst219
-rw-r--r--Documentation/arch/powerpc/cpu_features.rst60
-rw-r--r--Documentation/arch/powerpc/dawr-power9.rst101
-rw-r--r--Documentation/arch/powerpc/dexcr.rst195
-rw-r--r--Documentation/arch/powerpc/dscr.rst87
-rw-r--r--Documentation/arch/powerpc/eeh-pci-error-recovery.rst335
-rw-r--r--Documentation/arch/powerpc/elf_hwcaps.rst232
-rw-r--r--Documentation/arch/powerpc/elfnote.rst41
-rw-r--r--Documentation/arch/powerpc/features.rst3
-rw-r--r--Documentation/arch/powerpc/firmware-assisted-dump.rst396
-rw-r--r--Documentation/arch/powerpc/htm.rst104
-rw-r--r--Documentation/arch/powerpc/hvcs.rst581
-rw-r--r--Documentation/arch/powerpc/imc.rst199
-rw-r--r--Documentation/arch/powerpc/index.rst49
-rw-r--r--Documentation/arch/powerpc/isa-versions.rst101
-rw-r--r--Documentation/arch/powerpc/kasan.txt58
-rw-r--r--Documentation/arch/powerpc/kaslr-booke32.rst42
-rw-r--r--Documentation/arch/powerpc/kvm-nested.rst656
-rw-r--r--Documentation/arch/powerpc/mpc52xx.rst43
-rw-r--r--Documentation/arch/powerpc/papr_hcalls.rst313
-rw-r--r--Documentation/arch/powerpc/pci_iov_resource_on_powernv.rst312
-rw-r--r--Documentation/arch/powerpc/pmu-ebb.rst138
-rw-r--r--Documentation/arch/powerpc/ptrace.rst157
-rw-r--r--Documentation/arch/powerpc/qe_firmware.rst296
-rw-r--r--Documentation/arch/powerpc/syscall64-abi.rst153
-rw-r--r--Documentation/arch/powerpc/transactional_memory.rst274
-rw-r--r--Documentation/arch/powerpc/ultravisor.rst1117
-rw-r--r--Documentation/arch/powerpc/vas-api.rst305
-rw-r--r--Documentation/arch/powerpc/vcpudispatch_stats.rst75
-rw-r--r--Documentation/arch/powerpc/vmemmap_dedup.rst101
-rw-r--r--Documentation/arch/powerpc/vpa-dtl.rst156
-rw-r--r--Documentation/arch/riscv/acpi.rst10
-rw-r--r--Documentation/arch/riscv/boot-image-header.rst59
-rw-r--r--Documentation/arch/riscv/boot.rst169
-rw-r--r--Documentation/arch/riscv/cmodx.rst130
-rw-r--r--Documentation/arch/riscv/features.rst3
-rw-r--r--Documentation/arch/riscv/hwprobe.rst381
-rw-r--r--Documentation/arch/riscv/index.rst25
-rw-r--r--Documentation/arch/riscv/patch-acceptance.rst59
-rw-r--r--Documentation/arch/riscv/uabi.rst86
-rw-r--r--Documentation/arch/riscv/vector.rst140
-rw-r--r--Documentation/arch/riscv/vm-layout.rst136
-rw-r--r--Documentation/arch/s390/3270.ChangeLog (renamed from Documentation/s390/3270.ChangeLog)2
-rw-r--r--Documentation/arch/s390/3270.rst298
-rw-r--r--Documentation/arch/s390/cds.rst530
-rw-r--r--Documentation/arch/s390/common_io.rst140
-rw-r--r--Documentation/arch/s390/config3270.sh (renamed from Documentation/s390/config3270.sh)0
-rw-r--r--Documentation/arch/s390/driver-model.rst307
-rw-r--r--Documentation/arch/s390/features.rst3
-rw-r--r--Documentation/arch/s390/index.rst31
-rw-r--r--Documentation/arch/s390/mm.rst111
-rw-r--r--Documentation/arch/s390/monreader.rst212
-rw-r--r--Documentation/arch/s390/pci.rst133
-rw-r--r--Documentation/arch/s390/qeth.rst64
-rw-r--r--Documentation/arch/s390/s390dbf.rst477
-rw-r--r--Documentation/arch/s390/text_files.rst11
-rw-r--r--Documentation/arch/s390/vfio-ap-locking.rst115
-rw-r--r--Documentation/arch/s390/vfio-ap.rst1129
-rw-r--r--Documentation/arch/s390/vfio-ccw.rst445
-rw-r--r--Documentation/arch/s390/zfcpdump.rst50
-rw-r--r--Documentation/arch/sh/booting.rst12
-rw-r--r--Documentation/arch/sh/features.rst3
-rw-r--r--Documentation/arch/sh/index.rst50
-rw-r--r--Documentation/arch/sh/new-machine.rst277
-rw-r--r--Documentation/arch/sh/register-banks.rst40
-rw-r--r--Documentation/arch/sparc/adi.rst286
-rw-r--r--Documentation/arch/sparc/console.rst9
-rw-r--r--Documentation/arch/sparc/features.rst3
-rw-r--r--Documentation/arch/sparc/index.rst13
-rw-r--r--Documentation/arch/sparc/oradax/dax-hv-api.txt1433
-rw-r--r--Documentation/arch/sparc/oradax/oracle-dax.rst445
-rw-r--r--Documentation/arch/x86/amd-debugging.rst368
-rw-r--r--Documentation/arch/x86/amd-hfi.rst133
-rw-r--r--Documentation/arch/x86/amd-memory-encryption.rst278
-rw-r--r--Documentation/arch/x86/amd_hsmp.rst192
-rw-r--r--Documentation/arch/x86/boot.rst1464
-rw-r--r--Documentation/arch/x86/booting-dt.rst21
-rw-r--r--Documentation/arch/x86/buslock.rst133
-rw-r--r--Documentation/arch/x86/cpuinfo.rst202
-rw-r--r--Documentation/arch/x86/earlyprintk.rst151
-rw-r--r--Documentation/arch/x86/elf_auxvec.rst53
-rw-r--r--Documentation/arch/x86/entry_64.rst110
-rw-r--r--Documentation/arch/x86/exception-tables.rst357
-rw-r--r--Documentation/arch/x86/features.rst3
-rw-r--r--Documentation/arch/x86/i386/IO-APIC.rst123
-rw-r--r--Documentation/arch/x86/i386/index.rst10
-rw-r--r--Documentation/arch/x86/ifs.rst2
-rw-r--r--Documentation/arch/x86/index.rst46
-rw-r--r--Documentation/arch/x86/intel-hfi.rst72
-rw-r--r--Documentation/arch/x86/intel_txt.rst227
-rw-r--r--Documentation/arch/x86/iommu.rst151
-rw-r--r--Documentation/arch/x86/kernel-stacks.rst152
-rw-r--r--Documentation/arch/x86/mds.rst209
-rw-r--r--Documentation/arch/x86/microcode.rst240
-rw-r--r--Documentation/arch/x86/mtrr.rst354
-rw-r--r--Documentation/arch/x86/orc-unwinder.rst182
-rw-r--r--Documentation/arch/x86/pat.rst240
-rw-r--r--Documentation/arch/x86/pti.rst193
-rw-r--r--Documentation/arch/x86/resume.svg4
-rw-r--r--Documentation/arch/x86/sgx.rst302
-rw-r--r--Documentation/arch/x86/shstk.rst179
-rw-r--r--Documentation/arch/x86/suspend.svg4
-rw-r--r--Documentation/arch/x86/sva.rst286
-rw-r--r--Documentation/arch/x86/tdx.rst446
-rw-r--r--Documentation/arch/x86/tlb.rst83
-rw-r--r--Documentation/arch/x86/topology.rst421
-rw-r--r--Documentation/arch/x86/tsx_async_abort.rst117
-rw-r--r--Documentation/arch/x86/usb-legacy-support.rst41
-rw-r--r--Documentation/arch/x86/x86_64/5level-paging.rst58
-rw-r--r--Documentation/arch/x86/x86_64/cpu-hotplug-spec.rst24
-rw-r--r--Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst78
-rw-r--r--Documentation/arch/x86/x86_64/fred.rst96
-rw-r--r--Documentation/arch/x86/x86_64/fsgs.rst199
-rw-r--r--Documentation/arch/x86/x86_64/index.rst17
-rw-r--r--Documentation/arch/x86/x86_64/machinecheck.rst33
-rw-r--r--Documentation/arch/x86/x86_64/mm.rst180
-rw-r--r--Documentation/arch/x86/x86_64/uefi.rst75
-rw-r--r--Documentation/arch/x86/xstate.rst174
-rw-r--r--Documentation/arch/x86/zero-page.rst47
-rw-r--r--Documentation/arch/xtensa/atomctl.rst51
-rw-r--r--Documentation/arch/xtensa/booting.rst22
-rw-r--r--Documentation/arch/xtensa/features.rst3
-rw-r--r--Documentation/arch/xtensa/index.rst14
-rw-r--r--Documentation/arch/xtensa/mmu.rst198
-rw-r--r--Documentation/arm/00-INDEX52
-rw-r--r--Documentation/arm/Atmel/README124
-rw-r--r--Documentation/arm/Booting218
-rw-r--r--Documentation/arm/CCN.txt52
-rw-r--r--Documentation/arm/IXP4xx172
-rw-r--r--Documentation/arm/Interrupts167
-rw-r--r--Documentation/arm/Marvell/README284
-rw-r--r--Documentation/arm/Netwinder78
-rw-r--r--Documentation/arm/OMAP/DSS362
-rw-r--r--Documentation/arm/OMAP/omap_pm154
-rw-r--r--Documentation/arm/Porting135
-rw-r--r--Documentation/arm/README204
-rw-r--r--Documentation/arm/SA1100/ADSBitsy43
-rw-r--r--Documentation/arm/SA1100/Assabet300
-rw-r--r--Documentation/arm/SA1100/Brutus66
-rw-r--r--Documentation/arm/SA1100/CERF29
-rw-r--r--Documentation/arm/SA1100/FreeBird21
-rw-r--r--Documentation/arm/SA1100/GraphicsClient98
-rw-r--r--Documentation/arm/SA1100/GraphicsMaster53
-rw-r--r--Documentation/arm/SA1100/HUW_WEBPANEL17
-rw-r--r--Documentation/arm/SA1100/Itsy39
-rw-r--r--Documentation/arm/SA1100/LART14
-rw-r--r--Documentation/arm/SA1100/PLEB11
-rw-r--r--Documentation/arm/SA1100/Pangolin23
-rw-r--r--Documentation/arm/SA1100/Tifon7
-rw-r--r--Documentation/arm/SA1100/Victor16
-rw-r--r--Documentation/arm/SA1100/Yopy2
-rw-r--r--Documentation/arm/SA1100/empeg2
-rw-r--r--Documentation/arm/SA1100/nanoEngine11
-rw-r--r--Documentation/arm/SA1100/serial_UART47
-rw-r--r--Documentation/arm/SH-Mobile/.gitignore1
-rw-r--r--Documentation/arm/SPEAr/overview.txt63
-rw-r--r--Documentation/arm/Samsung-S3C24XX/CPUfreq.txt75
-rw-r--r--Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt58
-rw-r--r--Documentation/arm/Samsung-S3C24XX/GPIO.txt171
-rw-r--r--Documentation/arm/Samsung-S3C24XX/H1940.txt40
-rw-r--r--Documentation/arm/Samsung-S3C24XX/NAND.txt30
-rw-r--r--Documentation/arm/Samsung-S3C24XX/Overview.txt318
-rw-r--r--Documentation/arm/Samsung-S3C24XX/S3C2412.txt120
-rw-r--r--Documentation/arm/Samsung-S3C24XX/S3C2413.txt21
-rw-r--r--Documentation/arm/Samsung-S3C24XX/SMDK2440.txt56
-rw-r--r--Documentation/arm/Samsung-S3C24XX/Suspend.txt137
-rw-r--r--Documentation/arm/Samsung-S3C24XX/USB-Host.txt93
-rw-r--r--Documentation/arm/Samsung/GPIO.txt40
-rw-r--r--Documentation/arm/Samsung/Overview.txt86
-rw-r--r--Documentation/arm/Setup129
-rw-r--r--Documentation/arm/VFP/release-notes.txt55
-rw-r--r--Documentation/arm/cluster-pm-race-avoidance.txt498
-rw-r--r--Documentation/arm/firmware.txt70
-rw-r--r--Documentation/arm/kernel_mode_neon.txt121
-rw-r--r--Documentation/arm/kernel_user_helpers.txt267
-rw-r--r--Documentation/arm/mem_alignment58
-rw-r--r--Documentation/arm/memory.txt88
-rw-r--r--Documentation/arm/nwfpe/NOTES29
-rw-r--r--Documentation/arm/nwfpe/README70
-rw-r--r--Documentation/arm/nwfpe/README.FPE156
-rw-r--r--Documentation/arm/nwfpe/TODO67
-rw-r--r--Documentation/arm/pxa/mfp.txt286
-rw-r--r--Documentation/arm/sti/overview.txt33
-rw-r--r--Documentation/arm/sti/stih407-overview.txt18
-rw-r--r--Documentation/arm/sti/stih415-overview.txt12
-rw-r--r--Documentation/arm/sti/stih416-overview.txt12
-rw-r--r--Documentation/arm/sti/stih418-overview.txt20
-rw-r--r--Documentation/arm/sunxi/README61
-rw-r--r--Documentation/arm/sunxi/clocks.txt56
-rw-r--r--Documentation/arm/swp_emulation27
-rw-r--r--Documentation/arm/tcm.txt155
-rw-r--r--Documentation/arm/uefi.txt64
-rw-r--r--Documentation/arm/vlocks.txt211
-rw-r--r--Documentation/arm64/acpi_object_usage.txt593
-rw-r--r--Documentation/arm64/arm-acpi.txt505
-rw-r--r--Documentation/arm64/booting.txt224
-rw-r--r--Documentation/arm64/legacy_instructions.txt57
-rw-r--r--Documentation/arm64/memory.txt94
-rw-r--r--Documentation/arm64/tagged-pointers.txt34
-rw-r--r--Documentation/assoc_array.txt574
-rw-r--r--Documentation/atomic_bitops.txt69
-rw-r--r--Documentation/atomic_ops.txt634
-rw-r--r--Documentation/atomic_t.txt367
-rw-r--r--Documentation/auxdisplay/.gitignore1
-rw-r--r--Documentation/auxdisplay/Makefile7
-rw-r--r--Documentation/auxdisplay/cfag12864b105
-rw-r--r--Documentation/auxdisplay/cfag12864b-example.c281
-rw-r--r--Documentation/auxdisplay/ks010855
-rw-r--r--Documentation/backlight/lp855x-driver.txt66
-rw-r--r--Documentation/bad_memory.txt45
-rw-r--r--Documentation/basic_profiling.txt56
-rw-r--r--Documentation/bcache.txt448
-rw-r--r--Documentation/binfmt_misc.txt124
-rw-r--r--Documentation/blackfin/00-INDEX10
-rw-r--r--Documentation/blackfin/Makefile5
-rw-r--r--Documentation/blackfin/bfin-gpio-notes.txt71
-rw-r--r--Documentation/blackfin/bfin-spi-notes.txt16
-rw-r--r--Documentation/blackfin/gptimers-example.c83
-rw-r--r--Documentation/block/00-INDEX28
-rw-r--r--Documentation/block/bfq-iosched.rst606
-rw-r--r--Documentation/block/biodoc.txt1180
-rw-r--r--Documentation/block/biovecs.rst151
-rw-r--r--Documentation/block/biovecs.txt111
-rw-r--r--Documentation/block/blk-mq.rst153
-rw-r--r--Documentation/block/capability.txt15
-rw-r--r--Documentation/block/cfq-iosched.txt292
-rw-r--r--Documentation/block/cmdline-partition.rst56
-rw-r--r--Documentation/block/cmdline-partition.txt39
-rw-r--r--Documentation/block/data-integrity.rst248
-rw-r--r--Documentation/block/data-integrity.txt283
-rw-r--r--Documentation/block/deadline-iosched.rst72
-rw-r--r--Documentation/block/deadline-iosched.txt75
-rw-r--r--Documentation/block/index.rst24
-rw-r--r--Documentation/block/inline-encryption.rst550
-rw-r--r--Documentation/block/ioprio.rst178
-rw-r--r--Documentation/block/ioprio.txt183
-rw-r--r--Documentation/block/kyber-iosched.rst15
-rw-r--r--Documentation/block/null_blk.rst151
-rw-r--r--Documentation/block/null_blk.txt72
-rw-r--r--Documentation/block/pr.rst119
-rw-r--r--Documentation/block/queue-sysfs.txt138
-rw-r--r--Documentation/block/request.txt88
-rw-r--r--Documentation/block/stat.rst103
-rw-r--r--Documentation/block/stat.txt82
-rw-r--r--Documentation/block/switching-sched.rst35
-rw-r--r--Documentation/block/switching-sched.txt37
-rw-r--r--Documentation/block/ublk.rst441
-rw-r--r--Documentation/block/writeback_cache_control.rst95
-rw-r--r--Documentation/block/writeback_cache_control.txt86
-rw-r--r--Documentation/blockdev/00-INDEX18
-rw-r--r--Documentation/blockdev/README.DAC960756
-rw-r--r--Documentation/blockdev/cciss.txt194
-rw-r--r--Documentation/blockdev/cpqarray.txt93
-rw-r--r--Documentation/blockdev/drbd/README.txt16
-rw-r--r--Documentation/blockdev/drbd/data-structure-v9.txt38
-rw-r--r--Documentation/blockdev/drbd/node-states-8.dot14
-rw-r--r--Documentation/blockdev/floppy.txt245
-rw-r--r--Documentation/blockdev/mflash.txt84
-rw-r--r--Documentation/blockdev/nbd.txt31
-rw-r--r--Documentation/blockdev/paride.txt417
-rw-r--r--Documentation/blockdev/ramdisk.txt174
-rw-r--r--Documentation/blockdev/zram.txt189
-rw-r--r--Documentation/bpf/bpf_design_QA.rst351
-rw-r--r--Documentation/bpf/bpf_devel_QA.rst704
-rw-r--r--Documentation/bpf/bpf_iterators.rst589
-rw-r--r--Documentation/bpf/bpf_licensing.rst92
-rw-r--r--Documentation/bpf/bpf_prog_run.rst117
-rw-r--r--Documentation/bpf/btf.rst1210
-rw-r--r--Documentation/bpf/clang-notes.rst36
-rw-r--r--Documentation/bpf/classic_vs_extended.rst376
-rw-r--r--Documentation/bpf/cpumasks.rst384
-rw-r--r--Documentation/bpf/drgn.rst213
-rw-r--r--Documentation/bpf/faq.rst11
-rw-r--r--Documentation/bpf/fs_kfuncs.rst21
-rw-r--r--Documentation/bpf/graph_ds_impl.rst267
-rw-r--r--Documentation/bpf/helpers.rst7
-rw-r--r--Documentation/bpf/index.rst45
-rw-r--r--Documentation/bpf/kfuncs.rst712
-rw-r--r--Documentation/bpf/libbpf/index.rst33
-rw-r--r--Documentation/bpf/libbpf/libbpf_build.rst37
-rw-r--r--Documentation/bpf/libbpf/libbpf_naming_convention.rst193
-rw-r--r--Documentation/bpf/libbpf/libbpf_overview.rst236
-rw-r--r--Documentation/bpf/libbpf/program_types.rst253
-rw-r--r--Documentation/bpf/linux-notes.rst84
-rw-r--r--Documentation/bpf/llvm_reloc.rst546
-rw-r--r--Documentation/bpf/map_array.rst263
-rw-r--r--Documentation/bpf/map_bloom_filter.rst174
-rw-r--r--Documentation/bpf/map_cgroup_storage.rst169
-rw-r--r--Documentation/bpf/map_cgrp_storage.rst109
-rw-r--r--Documentation/bpf/map_cpumap.rst177
-rw-r--r--Documentation/bpf/map_devmap.rst238
-rw-r--r--Documentation/bpf/map_hash.rst265
-rw-r--r--Documentation/bpf/map_lpm_trie.rst197
-rw-r--r--Documentation/bpf/map_lru_hash_update.dot172
-rw-r--r--Documentation/bpf/map_of_maps.rst130
-rw-r--r--Documentation/bpf/map_queue_stack.rst146
-rw-r--r--Documentation/bpf/map_sk_storage.rst159
-rw-r--r--Documentation/bpf/map_sockmap.rst498
-rw-r--r--Documentation/bpf/map_xskmap.rst192
-rw-r--r--Documentation/bpf/maps.rst82
-rw-r--r--Documentation/bpf/other.rst10
-rw-r--r--Documentation/bpf/prog_cgroup_sockopt.rst162
-rw-r--r--Documentation/bpf/prog_cgroup_sysctl.rst125
-rw-r--r--Documentation/bpf/prog_flow_dissector.rst147
-rw-r--r--Documentation/bpf/prog_lsm.rst143
-rw-r--r--Documentation/bpf/prog_sk_lookup.rst98
-rw-r--r--Documentation/bpf/programs.rst12
-rw-r--r--Documentation/bpf/redirect.rst81
-rw-r--r--Documentation/bpf/ringbuf.rst206
-rw-r--r--Documentation/bpf/s390.rst205
-rw-r--r--Documentation/bpf/standardization/abi.rst28
-rw-r--r--Documentation/bpf/standardization/index.rst18
-rw-r--r--Documentation/bpf/standardization/instruction-set.rst790
-rw-r--r--Documentation/bpf/syscall_api.rst11
-rw-r--r--Documentation/bpf/test_debug.rst9
-rw-r--r--Documentation/bpf/verifier.rst560
-rw-r--r--Documentation/braille-console.txt34
-rw-r--r--Documentation/bt8xxgpio.txt67
-rw-r--r--Documentation/btmrvl.txt119
-rw-r--r--Documentation/bus-devices/ti-gpmc.txt122
-rw-r--r--Documentation/bus-virt-phys-mapping.txt208
-rw-r--r--Documentation/cachetlb.txt403
-rw-r--r--Documentation/cdrom/00-INDEX11
-rw-r--r--Documentation/cdrom/Makefile21
-rw-r--r--Documentation/cdrom/cdrom-standard.rst1047
-rw-r--r--Documentation/cdrom/cdrom-standard.tex1022
-rw-r--r--Documentation/cdrom/ide-cd538
-rw-r--r--Documentation/cdrom/index.rst17
-rw-r--r--Documentation/cdrom/packet-writing.txt132
-rw-r--r--Documentation/cgroups/00-INDEX28
-rw-r--r--Documentation/cgroups/blkio-controller.txt394
-rw-r--r--Documentation/cgroups/cgroups.txt678
-rw-r--r--Documentation/cgroups/cpuacct.txt49
-rw-r--r--Documentation/cgroups/cpusets.txt839
-rw-r--r--Documentation/cgroups/devices.txt116
-rw-r--r--Documentation/cgroups/freezer-subsystem.txt123
-rw-r--r--Documentation/cgroups/hugetlb.txt45
-rw-r--r--Documentation/cgroups/memcg_test.txt280
-rw-r--r--Documentation/cgroups/memory.txt875
-rw-r--r--Documentation/cgroups/net_cls.txt39
-rw-r--r--Documentation/cgroups/net_prio.txt55
-rw-r--r--Documentation/cgroups/unified-hierarchy.txt461
-rw-r--r--Documentation/circular-buffers.txt243
-rw-r--r--Documentation/clk.txt299
-rw-r--r--Documentation/cma/debugfs.txt21
-rw-r--r--Documentation/coccinelle.txt324
-rw-r--r--Documentation/conf.py591
-rw-r--r--Documentation/connector/.gitignore1
-rw-r--r--Documentation/connector/Makefile16
-rw-r--r--Documentation/connector/cn_test.c201
-rw-r--r--Documentation/connector/connector.txt188
-rw-r--r--Documentation/connector/ucon.c250
-rw-r--r--Documentation/console/console.txt144
-rw-r--r--Documentation/core-api/asm-annotations.rst222
-rw-r--r--Documentation/core-api/assoc_array.rst564
-rw-r--r--Documentation/core-api/boot-time-mm.rst41
-rw-r--r--Documentation/core-api/cachetlb.rst398
-rw-r--r--Documentation/core-api/cgroup.rst9
-rw-r--r--Documentation/core-api/circular-buffers.rst237
-rw-r--r--Documentation/core-api/cleanup.rst8
-rw-r--r--Documentation/core-api/cpu_hotplug.rst761
-rw-r--r--Documentation/core-api/debug-objects.rst310
-rw-r--r--Documentation/core-api/debugging-via-ohci1394.rst185
-rw-r--r--Documentation/core-api/dma-api-howto.rst935
-rw-r--r--Documentation/core-api/dma-api.rst868
-rw-r--r--Documentation/core-api/dma-attributes.rst150
-rw-r--r--Documentation/core-api/dma-isa-lpc.rst152
-rw-r--r--Documentation/core-api/entry.rst279
-rw-r--r--Documentation/core-api/errseq.rst159
-rw-r--r--Documentation/core-api/floating-point.rst78
-rw-r--r--Documentation/core-api/folio_queue.rst209
-rw-r--r--Documentation/core-api/genalloc.rst144
-rw-r--r--Documentation/core-api/generic-radix-tree.rst12
-rw-r--r--Documentation/core-api/genericirq.rst444
-rw-r--r--Documentation/core-api/gfp_mask-from-fs-io.rst70
-rw-r--r--Documentation/core-api/idr.rst84
-rw-r--r--Documentation/core-api/index.rst149
-rw-r--r--Documentation/core-api/irq/concepts.rst25
-rw-r--r--Documentation/core-api/irq/index.rst11
-rw-r--r--Documentation/core-api/irq/irq-affinity.rst70
-rw-r--r--Documentation/core-api/irq/irq-domain.rst320
-rw-r--r--Documentation/core-api/irq/irqflags-tracing.rst52
-rw-r--r--Documentation/core-api/kernel-api.rst430
-rw-r--r--Documentation/core-api/kho/bindings/kho.yaml43
-rw-r--r--Documentation/core-api/kho/bindings/memblock/memblock.yaml39
-rw-r--r--Documentation/core-api/kho/bindings/memblock/reserve-mem.yaml40
-rw-r--r--Documentation/core-api/kho/bindings/sub-fdt.yaml27
-rw-r--r--Documentation/core-api/kho/concepts.rst74
-rw-r--r--Documentation/core-api/kho/fdt.rst80
-rw-r--r--Documentation/core-api/kho/index.rst13
-rw-r--r--Documentation/core-api/kobject.rst434
-rw-r--r--Documentation/core-api/kref.rst328
-rw-r--r--Documentation/core-api/librs.rst212
-rw-r--r--Documentation/core-api/list.rst776
-rw-r--r--Documentation/core-api/liveupdate.rst61
-rw-r--r--Documentation/core-api/local_ops.rst202
-rw-r--r--Documentation/core-api/maple_tree.rst221
-rw-r--r--Documentation/core-api/memory-allocation.rst188
-rw-r--r--Documentation/core-api/memory-hotplug.rst195
-rw-r--r--Documentation/core-api/min_heap.rst302
-rw-r--r--Documentation/core-api/mm-api.rst134
-rw-r--r--Documentation/core-api/netlink.rst102
-rw-r--r--Documentation/core-api/packing.rst345
-rw-r--r--Documentation/core-api/padata.rst178
-rw-r--r--Documentation/core-api/parser.rst17
-rw-r--r--Documentation/core-api/pin_user_pages.rst286
-rw-r--r--Documentation/core-api/printk-basics.rst112
-rw-r--r--Documentation/core-api/printk-formats.rst705
-rw-r--r--Documentation/core-api/printk-index.rst137
-rw-r--r--Documentation/core-api/protection-keys.rst120
-rw-r--r--Documentation/core-api/rbtree.rst429
-rw-r--r--Documentation/core-api/real-time/architecture-porting.rst109
-rw-r--r--Documentation/core-api/real-time/differences.rst242
-rw-r--r--Documentation/core-api/real-time/index.rst16
-rw-r--r--Documentation/core-api/real-time/theory.rst116
-rw-r--r--Documentation/core-api/refcount-vs-atomic.rst193
-rw-r--r--Documentation/core-api/swiotlb.rst321
-rw-r--r--Documentation/core-api/symbol-namespaces.rst168
-rw-r--r--Documentation/core-api/this_cpu_ops.rst347
-rw-r--r--Documentation/core-api/timekeeping.rst190
-rw-r--r--Documentation/core-api/tracepoint.rst55
-rw-r--r--Documentation/core-api/unaligned-memory-access.rst265
-rw-r--r--Documentation/core-api/union_find.rst106
-rw-r--r--Documentation/core-api/watch_queue.rst343
-rw-r--r--Documentation/core-api/workqueue.rst789
-rw-r--r--Documentation/core-api/wrappers/atomic_bitops.rst18
-rw-r--r--Documentation/core-api/wrappers/atomic_t.rst19
-rw-r--r--Documentation/core-api/wrappers/memory-barriers.rst18
-rw-r--r--Documentation/core-api/xarray.rst510
-rw-r--r--Documentation/cpu-freq/amd-powernow.txt38
-rw-r--r--Documentation/cpu-freq/boost.txt93
-rw-r--r--Documentation/cpu-freq/core.rst113
-rw-r--r--Documentation/cpu-freq/core.txt123
-rw-r--r--Documentation/cpu-freq/cpu-drivers.rst285
-rw-r--r--Documentation/cpu-freq/cpu-drivers.txt274
-rw-r--r--Documentation/cpu-freq/cpufreq-nforce2.txt19
-rw-r--r--Documentation/cpu-freq/cpufreq-stats.rst136
-rw-r--r--Documentation/cpu-freq/cpufreq-stats.txt128
-rw-r--r--Documentation/cpu-freq/governors.txt269
-rw-r--r--Documentation/cpu-freq/index.rst36
-rw-r--r--Documentation/cpu-freq/index.txt54
-rw-r--r--Documentation/cpu-freq/intel-pstate.txt64
-rw-r--r--Documentation/cpu-freq/pcc-cpufreq.txt207
-rw-r--r--Documentation/cpu-freq/user-guide.txt224
-rw-r--r--Documentation/cpu-hotplug.txt452
-rw-r--r--Documentation/cpu-load.txt113
-rw-r--r--Documentation/cpuidle/core.txt23
-rw-r--r--Documentation/cpuidle/driver.txt37
-rw-r--r--Documentation/cpuidle/governor.txt28
-rw-r--r--Documentation/cpuidle/sysfs.txt92
-rw-r--r--Documentation/cputopology.txt111
-rw-r--r--Documentation/crc32.txt182
-rw-r--r--Documentation/cris/README195
-rw-r--r--Documentation/crypto/api-aead.rst26
-rw-r--r--Documentation/crypto/api-akcipher.rst23
-rw-r--r--Documentation/crypto/api-digest.rst38
-rw-r--r--Documentation/crypto/api-intro.rst262
-rw-r--r--Documentation/crypto/api-intro.txt248
-rw-r--r--Documentation/crypto/api-kpp.rst41
-rw-r--r--Documentation/crypto/api-rng.rst17
-rw-r--r--Documentation/crypto/api-samples.rst187
-rw-r--r--Documentation/crypto/api-sig.rst18
-rw-r--r--Documentation/crypto/api-skcipher.rst38
-rw-r--r--Documentation/crypto/api.rst14
-rw-r--r--Documentation/crypto/architecture.rst414
-rw-r--r--Documentation/crypto/asymmetric-keys.rst424
-rw-r--r--Documentation/crypto/asymmetric-keys.txt312
-rw-r--r--Documentation/crypto/async-tx-api.rst270
-rw-r--r--Documentation/crypto/async-tx-api.txt225
-rw-r--r--Documentation/crypto/crypto_engine.rst80
-rw-r--r--Documentation/crypto/descore-readme.rst414
-rw-r--r--Documentation/crypto/descore-readme.txt352
-rw-r--r--Documentation/crypto/devel-algos.rst238
-rw-r--r--Documentation/crypto/device_drivers/index.rst9
-rw-r--r--Documentation/crypto/device_drivers/octeontx2.rst25
-rw-r--r--Documentation/crypto/index.rst30
-rw-r--r--Documentation/crypto/intro.rst74
-rw-r--r--Documentation/crypto/krb5.rst262
-rw-r--r--Documentation/crypto/sha3.rst130
-rw-r--r--Documentation/crypto/userspace-if.rst409
-rw-r--r--Documentation/dcdbas.txt91
-rw-r--r--Documentation/debugging-modules.txt22
-rw-r--r--Documentation/debugging-via-ohci1394.txt184
-rw-r--r--Documentation/dell_rbu.txt100
-rw-r--r--Documentation/dev-tools/autofdo.rst168
-rw-r--r--Documentation/dev-tools/checkpatch.rst1262
-rw-r--r--Documentation/dev-tools/checkuapi.rst477
-rw-r--r--Documentation/dev-tools/clang-format.rst184
-rw-r--r--Documentation/dev-tools/coccinelle.rst511
-rw-r--r--Documentation/dev-tools/gcov.rst285
-rw-r--r--Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst93
-rw-r--r--Documentation/dev-tools/index.rst48
-rw-r--r--Documentation/dev-tools/kasan.rst571
-rw-r--r--Documentation/dev-tools/kcov.rst379
-rw-r--r--Documentation/dev-tools/kcsan.rst377
-rw-r--r--Documentation/dev-tools/kfence.rst340
-rw-r--r--Documentation/dev-tools/kmemleak.rst259
-rw-r--r--Documentation/dev-tools/kmsan.rst435
-rw-r--r--Documentation/dev-tools/kselftest.rst447
-rw-r--r--Documentation/dev-tools/ktap.rst314
-rw-r--r--Documentation/dev-tools/kunit/api/clk.rst10
-rw-r--r--Documentation/dev-tools/kunit/api/functionredirection.rst162
-rw-r--r--Documentation/dev-tools/kunit/api/index.rst48
-rw-r--r--Documentation/dev-tools/kunit/api/of.rst13
-rw-r--r--Documentation/dev-tools/kunit/api/platformdevice.rst10
-rw-r--r--Documentation/dev-tools/kunit/api/resource.rst22
-rw-r--r--Documentation/dev-tools/kunit/api/test.rst10
-rw-r--r--Documentation/dev-tools/kunit/architecture.rst196
-rw-r--r--Documentation/dev-tools/kunit/faq.rst104
-rw-r--r--Documentation/dev-tools/kunit/index.rst109
-rw-r--r--Documentation/dev-tools/kunit/kunit_suitememorydiagram.svg81
-rw-r--r--Documentation/dev-tools/kunit/run_manual.rst106
-rw-r--r--Documentation/dev-tools/kunit/run_wrapper.rst337
-rw-r--r--Documentation/dev-tools/kunit/running_tips.rst448
-rw-r--r--Documentation/dev-tools/kunit/start.rst309
-rw-r--r--Documentation/dev-tools/kunit/style.rst213
-rw-r--r--Documentation/dev-tools/kunit/usage.rst1214
-rw-r--r--Documentation/dev-tools/lkmm/docs/access-marking.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/cheatsheet.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/control-dependencies.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/explanation.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/glossary.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/herd-representation.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/index.rst21
-rw-r--r--Documentation/dev-tools/lkmm/docs/litmus-tests.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/locking.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/ordering.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/readme.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/recipes.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/references.rst11
-rw-r--r--Documentation/dev-tools/lkmm/docs/simple.rst11
-rw-r--r--Documentation/dev-tools/lkmm/index.rst15
-rw-r--r--Documentation/dev-tools/lkmm/readme.rst11
-rw-r--r--Documentation/dev-tools/propeller.rst162
-rw-r--r--Documentation/dev-tools/sparse.rst104
-rw-r--r--Documentation/dev-tools/testing-devices.rst47
-rw-r--r--Documentation/dev-tools/testing-overview.rst182
-rw-r--r--Documentation/dev-tools/ubsan.rst79
-rw-r--r--Documentation/development-process/1.Intro274
-rw-r--r--Documentation/development-process/2.Process478
-rw-r--r--Documentation/development-process/3.Early-stage212
-rw-r--r--Documentation/development-process/4.Coding399
-rw-r--r--Documentation/development-process/5.Posting307
-rw-r--r--Documentation/development-process/6.Followthrough206
-rw-r--r--Documentation/development-process/7.AdvancedTopics173
-rw-r--r--Documentation/development-process/8.Conclusion70
-rw-r--r--Documentation/device-mapper/cache-policies.txt97
-rw-r--r--Documentation/device-mapper/cache.txt298
-rw-r--r--Documentation/device-mapper/delay.txt26
-rw-r--r--Documentation/device-mapper/dm-crypt.txt96
-rw-r--r--Documentation/device-mapper/dm-flakey.txt53
-rw-r--r--Documentation/device-mapper/dm-io.txt75
-rw-r--r--Documentation/device-mapper/dm-log.txt54
-rw-r--r--Documentation/device-mapper/dm-queue-length.txt39
-rw-r--r--Documentation/device-mapper/dm-raid.txt226
-rw-r--r--Documentation/device-mapper/dm-service-time.txt91
-rw-r--r--Documentation/device-mapper/dm-uevent.txt97
-rw-r--r--Documentation/device-mapper/era.txt108
-rw-r--r--Documentation/device-mapper/kcopyd.txt47
-rw-r--r--Documentation/device-mapper/linear.txt61
-rw-r--r--Documentation/device-mapper/log-writes.txt140
-rw-r--r--Documentation/device-mapper/persistent-data.txt84
-rw-r--r--Documentation/device-mapper/snapshot.txt168
-rw-r--r--Documentation/device-mapper/statistics.txt186
-rw-r--r--Documentation/device-mapper/striped.txt57
-rw-r--r--Documentation/device-mapper/switch.txt138
-rw-r--r--Documentation/device-mapper/thin-provisioning.txt389
-rw-r--r--Documentation/device-mapper/verity.txt172
-rw-r--r--Documentation/device-mapper/zero.txt37
-rw-r--r--Documentation/devices.txt3355
-rw-r--r--Documentation/devicetree/00-INDEX12
-rw-r--r--Documentation/devicetree/bindings/.gitignore9
-rw-r--r--Documentation/devicetree/bindings/.yamllint44
-rw-r--r--Documentation/devicetree/bindings/ABI.rst42
-rw-r--r--Documentation/devicetree/bindings/ABI.txt39
-rw-r--r--Documentation/devicetree/bindings/Makefile86
-rw-r--r--Documentation/devicetree/bindings/access-controllers/access-controllers.yaml84
-rw-r--r--Documentation/devicetree/bindings/arc/axs101.txt7
-rw-r--r--Documentation/devicetree/bindings/arc/axs103.txt8
-rw-r--r--Documentation/devicetree/bindings/arc/eznps.txt7
-rw-r--r--Documentation/devicetree/bindings/arc/hsdk.txt7
-rw-r--r--Documentation/devicetree/bindings/arc/interrupts.txt24
-rw-r--r--Documentation/devicetree/bindings/arc/pct.txt2
-rw-r--r--Documentation/devicetree/bindings/arc/snps,archs-pct.yaml33
-rw-r--r--Documentation/devicetree/bindings/arm/actions.yaml53
-rw-r--r--Documentation/devicetree/bindings/arm/adapteva.txt7
-rw-r--r--Documentation/devicetree/bindings/arm/airoha,en7581-chip-scu.yaml42
-rw-r--r--Documentation/devicetree/bindings/arm/airoha.yaml32
-rw-r--r--Documentation/devicetree/bindings/arm/al,alpine.txt88
-rw-r--r--Documentation/devicetree/bindings/arm/altera.txt14
-rw-r--r--Documentation/devicetree/bindings/arm/altera.yaml91
-rw-r--r--Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.txt11
-rw-r--r--Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.yaml133
-rw-r--r--Documentation/devicetree/bindings/arm/altera/socfpga-sdram-edac.txt15
-rw-r--r--Documentation/devicetree/bindings/arm/altera/socfpga-system.txt13
-rw-r--r--Documentation/devicetree/bindings/arm/amazon,al.yaml35
-rw-r--r--Documentation/devicetree/bindings/arm/amd,pensando.yaml26
-rw-r--r--Documentation/devicetree/bindings/arm/amd,seattle.yaml24
-rw-r--r--Documentation/devicetree/bindings/arm/amlogic.txt14
-rw-r--r--Documentation/devicetree/bindings/arm/amlogic.yaml278
-rw-r--r--Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.yaml65
-rw-r--r--Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-mx-secbus2.yaml42
-rw-r--r--Documentation/devicetree/bindings/arm/apm.yaml28
-rw-r--r--Documentation/devicetree/bindings/arm/apple.yaml352
-rw-r--r--Documentation/devicetree/bindings/arm/apple/apple,pmgr.yaml147
-rw-r--r--Documentation/devicetree/bindings/arm/arch_timer.txt96
-rw-r--r--Documentation/devicetree/bindings/arm/arm,cci-400.yaml211
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-catu.yaml104
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml81
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml352
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-dummy-sink.yaml77
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml81
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-dynamic-funnel.yaml133
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-dynamic-replicator.yaml133
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-etb10.yaml99
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-etm.yaml163
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-static-funnel.yaml97
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-static-replicator.yaml128
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-stm.yaml104
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-tmc.yaml167
-rw-r--r--Documentation/devicetree/bindings/arm/arm,coresight-tpiu.yaml98
-rw-r--r--Documentation/devicetree/bindings/arm/arm,corstone1000.yaml45
-rw-r--r--Documentation/devicetree/bindings/arm/arm,embedded-trace-extension.yaml77
-rw-r--r--Documentation/devicetree/bindings/arm/arm,integrator.yaml49
-rw-r--r--Documentation/devicetree/bindings/arm/arm,juno-fpga-apb-regs.yaml61
-rw-r--r--Documentation/devicetree/bindings/arm/arm,morello.yaml35
-rw-r--r--Documentation/devicetree/bindings/arm/arm,realview.yaml88
-rw-r--r--Documentation/devicetree/bindings/arm/arm,scu.yaml46
-rw-r--r--Documentation/devicetree/bindings/arm/arm,trace-buffer-extension.yaml50
-rw-r--r--Documentation/devicetree/bindings/arm/arm,versatile-sysreg.yaml35
-rw-r--r--Documentation/devicetree/bindings/arm/arm,versatile.yaml49
-rw-r--r--Documentation/devicetree/bindings/arm/arm,vexpress-juno.yaml231
-rw-r--r--Documentation/devicetree/bindings/arm/arm-boards159
-rw-r--r--Documentation/devicetree/bindings/arm/armada-370-xp.txt24
-rw-r--r--Documentation/devicetree/bindings/arm/armada-375.txt9
-rw-r--r--Documentation/devicetree/bindings/arm/armada-38x.txt27
-rw-r--r--Documentation/devicetree/bindings/arm/armada-39x.txt20
-rw-r--r--Documentation/devicetree/bindings/arm/armadeus.txt6
-rw-r--r--Documentation/devicetree/bindings/arm/aspeed/aspeed,sbc.yaml37
-rw-r--r--Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml115
-rw-r--r--Documentation/devicetree/bindings/arm/atmel,sama5d2-secumod.yaml49
-rw-r--r--Documentation/devicetree/bindings/arm/atmel-at91.txt157
-rw-r--r--Documentation/devicetree/bindings/arm/atmel-at91.yaml294
-rw-r--r--Documentation/devicetree/bindings/arm/atmel-pmc.txt14
-rw-r--r--Documentation/devicetree/bindings/arm/atmel-sysregs.txt48
-rw-r--r--Documentation/devicetree/bindings/arm/axiado.yaml23
-rw-r--r--Documentation/devicetree/bindings/arm/axis.yaml36
-rw-r--r--Documentation/devicetree/bindings/arm/axxia.txt12
-rw-r--r--Documentation/devicetree/bindings/arm/axxia.yaml23
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/bcm2835.yaml66
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351-cpu-method.txt36
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.txt10
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm11351.yaml23
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.txt15
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm21664.yaml23
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm23550.yaml23
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt8
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.txt8
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml114
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm53573.yaml39
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcm63138.txt76
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,bcmbca.yaml153
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt169
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.txt31
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,cygnus.yaml31
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,hr2.yaml30
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,ns2.yaml25
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,nsp.yaml83
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,stingray.yaml26
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/brcm,vulcan-soc.yaml24
-rw-r--r--Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml167
-rw-r--r--Documentation/devicetree/bindings/arm/bitmain.yaml23
-rw-r--r--Documentation/devicetree/bindings/arm/blaize.yaml40
-rw-r--r--Documentation/devicetree/bindings/arm/bst.yaml31
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda.txt15
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda.yaml24
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda/combophy.txt17
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda/hb-sregs.yaml49
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda/l2ecc.txt15
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda/l2ecc.yaml42
-rw-r--r--Documentation/devicetree/bindings/arm/calxeda/mem-ctrlr.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/cavium,thunder-88xx.yaml19
-rw-r--r--Documentation/devicetree/bindings/arm/cavium-thunder.txt10
-rw-r--r--Documentation/devicetree/bindings/arm/cci-control-port.yaml38
-rw-r--r--Documentation/devicetree/bindings/arm/cci.txt227
-rw-r--r--Documentation/devicetree/bindings/arm/ccn.txt21
-rw-r--r--Documentation/devicetree/bindings/arm/cirrus/cirrus,ep9301.yaml38
-rw-r--r--Documentation/devicetree/bindings/arm/cix.yaml26
-rw-r--r--Documentation/devicetree/bindings/arm/coresight.txt199
-rw-r--r--Documentation/devicetree/bindings/arm/cpu-enable-method/al,alpine-smp24
-rw-r--r--Documentation/devicetree/bindings/arm/cpu-enable-method/nuvoton,npcm750-smp42
-rw-r--r--Documentation/devicetree/bindings/arm/cpus.txt437
-rw-r--r--Documentation/devicetree/bindings/arm/cpus.yaml701
-rw-r--r--Documentation/devicetree/bindings/arm/davinci.txt17
-rw-r--r--Documentation/devicetree/bindings/arm/davinci/cp-intc.txt27
-rw-r--r--Documentation/devicetree/bindings/arm/digicolor.txt6
-rw-r--r--Documentation/devicetree/bindings/arm/digicolor.yaml20
-rw-r--r--Documentation/devicetree/bindings/arm/exynos/power_domain.txt52
-rw-r--r--Documentation/devicetree/bindings/arm/exynos/smp-sysram.txt38
-rw-r--r--Documentation/devicetree/bindings/arm/firmware/linaro,optee-tz.yaml67
-rw-r--r--Documentation/devicetree/bindings/arm/firmware/sdei.txt42
-rw-r--r--Documentation/devicetree/bindings/arm/firmware/tlm,trusted-foundations.txt20
-rw-r--r--Documentation/devicetree/bindings/arm/firmware/tlm,trusted-foundations.yaml46
-rw-r--r--Documentation/devicetree/bindings/arm/freescale/fsl,imx51-m4if.yaml41
-rw-r--r--Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-pm.yaml50
-rw-r--r--Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-sim.yaml40
-rw-r--r--Documentation/devicetree/bindings/arm/freescale/fsl,vf610-mscm-cpucfg.txt14
-rw-r--r--Documentation/devicetree/bindings/arm/freescale/fsl,vf610-mscm-ir.txt33
-rw-r--r--Documentation/devicetree/bindings/arm/fsl.txt134
-rw-r--r--Documentation/devicetree/bindings/arm/fsl.yaml1801
-rw-r--r--Documentation/devicetree/bindings/arm/fw-cfg.txt72
-rw-r--r--Documentation/devicetree/bindings/arm/gemini.yaml95
-rw-r--r--Documentation/devicetree/bindings/arm/gic-v3.txt118
-rw-r--r--Documentation/devicetree/bindings/arm/gic.txt152
-rw-r--r--Documentation/devicetree/bindings/arm/global_timer.txt27
-rw-r--r--Documentation/devicetree/bindings/arm/google.yaml54
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/cpuctrl.yaml74
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/hi3798cv200-perictrl.yaml64
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/hi6220-domain-ctrl.yaml68
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/hip04-bootwrapper.yaml35
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/hip04-fabric.yaml27
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/pctrl.yaml34
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/controller/sysctrl.yaml149
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt105
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml70
-rw-r--r--Documentation/devicetree/bindings/arm/hisilicon/low-pin-count.yaml61
-rw-r--r--Documentation/devicetree/bindings/arm/hpe,gxp.yaml27
-rw-r--r--Documentation/devicetree/bindings/arm/idle-states.txt699
-rw-r--r--Documentation/devicetree/bindings/arm/insignal-boards.txt8
-rw-r--r--Documentation/devicetree/bindings/arm/intel,keembay.yaml24
-rw-r--r--Documentation/devicetree/bindings/arm/intel,socfpga.yaml40
-rw-r--r--Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml45
-rw-r--r--Documentation/devicetree/bindings/arm/keystone/keystone.txt20
-rw-r--r--Documentation/devicetree/bindings/arm/keystone/ti,k3-sci-common.yaml46
-rw-r--r--Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml124
-rw-r--r--Documentation/devicetree/bindings/arm/kirkwood.txt27
-rw-r--r--Documentation/devicetree/bindings/arm/l2cc.txt82
-rw-r--r--Documentation/devicetree/bindings/arm/lge.yaml28
-rw-r--r--Documentation/devicetree/bindings/arm/linux,dummy-virt.yaml20
-rw-r--r--Documentation/devicetree/bindings/arm/lpc32xx-mic.txt38
-rw-r--r--Documentation/devicetree/bindings/arm/lpc32xx.txt8
-rw-r--r--Documentation/devicetree/bindings/arm/marvell,berlin.txt152
-rw-r--r--Documentation/devicetree/bindings/arm/marvell,berlin.yaml45
-rw-r--r--Documentation/devicetree/bindings/arm/marvell,dove.txt22
-rw-r--r--Documentation/devicetree/bindings/arm/marvell,kirkwood.txt98
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/98dx3236-resume-ctrl.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/armada-370-xp-pmsu.txt (renamed from Documentation/devicetree/bindings/arm/armada-370-xp-pmsu.txt)0
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/armada-37xx.yaml49
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/armada-380-mpcore-soc-ctrl.txt (renamed from Documentation/devicetree/bindings/arm/armada-380-mpcore-soc-ctrl.txt)0
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/armada-38x.yaml70
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/armada-7k-8k.yaml128
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/armada-cpu-reset.txt (renamed from Documentation/devicetree/bindings/arm/armada-cpu-reset.txt)0
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/coherency-fabric.txt (renamed from Documentation/devicetree/bindings/arm/coherency-fabric.txt)5
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,ac5.yaml32
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,armada-370-xp.yaml78
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,armada375.yaml21
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,armada390.yaml32
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,dove.yaml35
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,kirkwood.yaml266
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/marvell,orion5x.yaml37
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/mvebu-cpu-config.txt20
-rw-r--r--Documentation/devicetree/bindings/arm/marvell/mvebu-system-controller.txt (renamed from Documentation/devicetree/bindings/arm/mvebu-system-controller.txt)0
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek.txt31
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek.yaml466
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.yaml167
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,g3dsys.txt30
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml145
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-pcie-mirror.yaml42
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml105
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7986-wed-pcie.yaml43
-rw-r--r--Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt30
-rw-r--r--Documentation/devicetree/bindings/arm/microchip,sparx5.yaml67
-rw-r--r--Documentation/devicetree/bindings/arm/moxart.txt12
-rw-r--r--Documentation/devicetree/bindings/arm/moxart.yaml20
-rw-r--r--Documentation/devicetree/bindings/arm/mrvl/feroceon.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/mrvl/intc.txt60
-rw-r--r--Documentation/devicetree/bindings/arm/mrvl/mrvl.txt14
-rw-r--r--Documentation/devicetree/bindings/arm/mrvl/mrvl.yaml46
-rw-r--r--Documentation/devicetree/bindings/arm/mrvl/tauros2.txt17
-rw-r--r--Documentation/devicetree/bindings/arm/mrvl/timer.txt13
-rw-r--r--Documentation/devicetree/bindings/arm/msm/qcom,idle-state.txt84
-rw-r--r--Documentation/devicetree/bindings/arm/msm/qcom,kpss-acc.txt30
-rw-r--r--Documentation/devicetree/bindings/arm/msm/qcom,saw2.txt57
-rw-r--r--Documentation/devicetree/bindings/arm/msm/ssbi.txt18
-rw-r--r--Documentation/devicetree/bindings/arm/msm/timer.txt47
-rw-r--r--Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml44
-rw-r--r--Documentation/devicetree/bindings/arm/mstar/mstar,smpctrl.yaml40
-rw-r--r--Documentation/devicetree/bindings/arm/mstar/mstar.yaml46
-rw-r--r--Documentation/devicetree/bindings/arm/nspire.txt14
-rw-r--r--Documentation/devicetree/bindings/arm/nuvoton/nuvoton,ma35d1.yaml30
-rw-r--r--Documentation/devicetree/bindings/arm/nuvoton/nuvoton,npcm.yaml36
-rw-r--r--Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml71
-rw-r--r--Documentation/devicetree/bindings/arm/nxp/lpc32xx.yaml26
-rw-r--r--Documentation/devicetree/bindings/arm/olimex.txt6
-rw-r--r--Documentation/devicetree/bindings/arm/omap/crossbar.txt6
-rw-r--r--Documentation/devicetree/bindings/arm/omap/ctrl.txt5
-rw-r--r--Documentation/devicetree/bindings/arm/omap/intc.txt27
-rw-r--r--Documentation/devicetree/bindings/arm/omap/l3-noc.txt1
-rw-r--r--Documentation/devicetree/bindings/arm/omap/l4.txt15
-rw-r--r--Documentation/devicetree/bindings/arm/omap/mpu.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/omap/omap.txt102
-rw-r--r--Documentation/devicetree/bindings/arm/omap/prcm.txt7
-rw-r--r--Documentation/devicetree/bindings/arm/omap/prm-inst.txt31
-rw-r--r--Documentation/devicetree/bindings/arm/omap/timer.txt44
-rw-r--r--Documentation/devicetree/bindings/arm/picoxcell.txt24
-rw-r--r--Documentation/devicetree/bindings/arm/pmu.txt44
-rw-r--r--Documentation/devicetree/bindings/arm/pmu.yaml133
-rw-r--r--Documentation/devicetree/bindings/arm/primecell.txt46
-rw-r--r--Documentation/devicetree/bindings/arm/primecell.yaml39
-rw-r--r--Documentation/devicetree/bindings/arm/psci.txt102
-rw-r--r--Documentation/devicetree/bindings/arm/psci.yaml263
-rw-r--r--Documentation/devicetree/bindings/arm/qcom,coresight-ctcu.yaml88
-rw-r--r--Documentation/devicetree/bindings/arm/qcom,coresight-remote-etm.yaml55
-rw-r--r--Documentation/devicetree/bindings/arm/qcom,coresight-tnoc.yaml113
-rw-r--r--Documentation/devicetree/bindings/arm/qcom,coresight-tpda.yaml128
-rw-r--r--Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml167
-rw-r--r--Documentation/devicetree/bindings/arm/qcom-soc.yaml70
-rw-r--r--Documentation/devicetree/bindings/arm/qcom.yaml1241
-rw-r--r--Documentation/devicetree/bindings/arm/rda.yaml24
-rw-r--r--Documentation/devicetree/bindings/arm/realtek.yaml60
-rw-r--r--Documentation/devicetree/bindings/arm/rockchip.txt28
-rw-r--r--Documentation/devicetree/bindings/arm/rockchip.yaml1309
-rw-r--r--Documentation/devicetree/bindings/arm/rockchip/pmu-sram.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/rockchip/pmu.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/rockchip/pmu.yaml77
-rw-r--r--Documentation/devicetree/bindings/arm/rockchip/smp-sram.txt30
-rw-r--r--Documentation/devicetree/bindings/arm/rtsm-dcscb.txt19
-rw-r--r--Documentation/devicetree/bindings/arm/samsung-boards.txt27
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt100
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/exynos-chipid.txt12
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/interrupt-combiner.txt52
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/pmu.txt69
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/samsung-boards.yaml271
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/samsung-secure-firmware.yaml33
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/samsung-soc.yaml40
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/sysreg.txt19
-rw-r--r--Documentation/devicetree/bindings/arm/secure.txt70
-rw-r--r--Documentation/devicetree/bindings/arm/shmobile.txt63
-rw-r--r--Documentation/devicetree/bindings/arm/sirf.txt11
-rw-r--r--Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml25
-rw-r--r--Documentation/devicetree/bindings/arm/socionext/synquacer.yaml28
-rw-r--r--Documentation/devicetree/bindings/arm/socionext/uniphier.yaml70
-rw-r--r--Documentation/devicetree/bindings/arm/sp810.yaml80
-rw-r--r--Documentation/devicetree/bindings/arm/spear-misc.txt9
-rw-r--r--Documentation/devicetree/bindings/arm/spear-timer.txt18
-rw-r--r--Documentation/devicetree/bindings/arm/spear.txt26
-rw-r--r--Documentation/devicetree/bindings/arm/spear.yaml28
-rw-r--r--Documentation/devicetree/bindings/arm/spear/shirq.txt48
-rw-r--r--Documentation/devicetree/bindings/arm/sprd.txt11
-rw-r--r--Documentation/devicetree/bindings/arm/sprd/sprd.yaml45
-rw-r--r--Documentation/devicetree/bindings/arm/ste-u300.txt46
-rw-r--r--Documentation/devicetree/bindings/arm/sti.txt23
-rw-r--r--Documentation/devicetree/bindings/arm/sti.yaml29
-rw-r--r--Documentation/devicetree/bindings/arm/stm32/st,mlahb.yaml71
-rw-r--r--Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml76
-rw-r--r--Documentation/devicetree/bindings/arm/stm32/stm32.yaml218
-rw-r--r--Documentation/devicetree/bindings/arm/sunplus,sp7021.yaml29
-rw-r--r--Documentation/devicetree/bindings/arm/sunxi.txt12
-rw-r--r--Documentation/devicetree/bindings/arm/sunxi.yaml1114
-rw-r--r--Documentation/devicetree/bindings/arm/sunxi/allwinner,sun4i-a10-mbus.yaml168
-rw-r--r--Documentation/devicetree/bindings/arm/sunxi/allwinner,sun6i-a31-cpuconfig.yaml38
-rw-r--r--Documentation/devicetree/bindings/arm/sunxi/allwinner,sun9i-a80-prcm.yaml33
-rw-r--r--Documentation/devicetree/bindings/arm/tegra.txt41
-rw-r--r--Documentation/devicetree/bindings/arm/tegra.yaml272
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra-ccplex-cluster.yaml50
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml217
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-axi2apb.yaml40
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra194-cbb.yaml97
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-ahb.txt17
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-emc.txt100
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt12
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-mc.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt115
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra234-cbb.yaml74
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra30-actmon.txt32
-rw-r--r--Documentation/devicetree/bindings/arm/tegra/nvidia,tegra30-mc.txt18
-rw-r--r--Documentation/devicetree/bindings/arm/tesla.yaml27
-rw-r--r--Documentation/devicetree/bindings/arm/ti/k3.yaml230
-rw-r--r--Documentation/devicetree/bindings/arm/ti/nspire.yaml27
-rw-r--r--Documentation/devicetree/bindings/arm/ti/omap.yaml193
-rw-r--r--Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml29
-rw-r--r--Documentation/devicetree/bindings/arm/ti/ti,keystone.yaml42
-rw-r--r--Documentation/devicetree/bindings/arm/topology.txt475
-rw-r--r--Documentation/devicetree/bindings/arm/toshiba.yaml26
-rw-r--r--Documentation/devicetree/bindings/arm/twd.txt48
-rw-r--r--Documentation/devicetree/bindings/arm/ux500.yaml73
-rw-r--r--Documentation/devicetree/bindings/arm/ux500/boards.txt83
-rw-r--r--Documentation/devicetree/bindings/arm/versatile-fpga-irq.txt36
-rw-r--r--Documentation/devicetree/bindings/arm/versatile-sysreg.txt10
-rw-r--r--Documentation/devicetree/bindings/arm/vexpress-config.yaml285
-rw-r--r--Documentation/devicetree/bindings/arm/vexpress-sysreg.txt103
-rw-r--r--Documentation/devicetree/bindings/arm/vexpress-sysreg.yaml96
-rw-r--r--Documentation/devicetree/bindings/arm/vexpress.txt229
-rw-r--r--Documentation/devicetree/bindings/arm/vic.txt41
-rw-r--r--Documentation/devicetree/bindings/arm/vt8500.txt22
-rw-r--r--Documentation/devicetree/bindings/arm/vt8500.yaml29
-rw-r--r--Documentation/devicetree/bindings/arm/vt8500/via,vt8500-intc.txt16
-rw-r--r--Documentation/devicetree/bindings/arm/vt8500/via,vt8500-timer.txt15
-rw-r--r--Documentation/devicetree/bindings/arm/xen.txt45
-rw-r--r--Documentation/devicetree/bindings/arm/xilinx.txt7
-rw-r--r--Documentation/devicetree/bindings/ata/ahci-common.yaml123
-rw-r--r--Documentation/devicetree/bindings/ata/ahci-platform.txt80
-rw-r--r--Documentation/devicetree/bindings/ata/ahci-platform.yaml208
-rw-r--r--Documentation/devicetree/bindings/ata/ahci-st.txt50
-rw-r--r--Documentation/devicetree/bindings/ata/allwinner,sun4i-a10-ahci.yaml47
-rw-r--r--Documentation/devicetree/bindings/ata/allwinner,sun8i-r40-ahci.yaml67
-rw-r--r--Documentation/devicetree/bindings/ata/apm,xgene-ahci.yaml65
-rw-r--r--Documentation/devicetree/bindings/ata/apm-xgene.txt79
-rw-r--r--Documentation/devicetree/bindings/ata/arasan,cf-spear1340.yaml70
-rw-r--r--Documentation/devicetree/bindings/ata/ata-generic.yaml58
-rw-r--r--Documentation/devicetree/bindings/ata/atmel-at91_cf.txt19
-rw-r--r--Documentation/devicetree/bindings/ata/baikal,bt1-ahci.yaml115
-rw-r--r--Documentation/devicetree/bindings/ata/brcm,sata-brcm.yaml87
-rw-r--r--Documentation/devicetree/bindings/ata/cavium,ebt3000-compact-flash.yaml59
-rw-r--r--Documentation/devicetree/bindings/ata/cavium-compact-flash.txt30
-rw-r--r--Documentation/devicetree/bindings/ata/ceva,ahci-1v84.yaml187
-rw-r--r--Documentation/devicetree/bindings/ata/cirrus,ep9312-pata.yaml42
-rw-r--r--Documentation/devicetree/bindings/ata/cortina,gemini-sata-bridge.yaml107
-rw-r--r--Documentation/devicetree/bindings/ata/eswin,eic7700-ahci.yaml79
-rw-r--r--Documentation/devicetree/bindings/ata/exynos-sata.txt30
-rw-r--r--Documentation/devicetree/bindings/ata/faraday,ftide010.yaml91
-rw-r--r--Documentation/devicetree/bindings/ata/fsl,ahci.yaml64
-rw-r--r--Documentation/devicetree/bindings/ata/fsl,imx-pata.yaml42
-rw-r--r--Documentation/devicetree/bindings/ata/fsl,pq-sata.yaml60
-rw-r--r--Documentation/devicetree/bindings/ata/fsl-sata.txt29
-rw-r--r--Documentation/devicetree/bindings/ata/imx-pata.txt17
-rw-r--r--Documentation/devicetree/bindings/ata/imx-sata.txt36
-rw-r--r--Documentation/devicetree/bindings/ata/imx-sata.yaml133
-rw-r--r--Documentation/devicetree/bindings/ata/intel,ixp4xx-compact-flash.yaml62
-rw-r--r--Documentation/devicetree/bindings/ata/marvell,orion-sata.yaml83
-rw-r--r--Documentation/devicetree/bindings/ata/marvell.txt22
-rw-r--r--Documentation/devicetree/bindings/ata/mediatek,mtk-ahci.yaml98
-rw-r--r--Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml175
-rw-r--r--Documentation/devicetree/bindings/ata/pata-arasan.txt39
-rw-r--r--Documentation/devicetree/bindings/ata/pata-common.yaml53
-rw-r--r--Documentation/devicetree/bindings/ata/qcom-sata.txt48
-rw-r--r--Documentation/devicetree/bindings/ata/renesas,rcar-sata.yaml84
-rw-r--r--Documentation/devicetree/bindings/ata/rockchip,dwc-ahci.yaml130
-rw-r--r--Documentation/devicetree/bindings/ata/sata-common.yaml57
-rw-r--r--Documentation/devicetree/bindings/ata/sata_highbank.txt44
-rw-r--r--Documentation/devicetree/bindings/ata/sata_highbank.yaml95
-rw-r--r--Documentation/devicetree/bindings/ata/sata_rcar.txt23
-rw-r--r--Documentation/devicetree/bindings/ata/snps,dwc-ahci-common.yaml106
-rw-r--r--Documentation/devicetree/bindings/ata/snps,dwc-ahci.yaml84
-rw-r--r--Documentation/devicetree/bindings/ata/st,ahci.yaml72
-rw-r--r--Documentation/devicetree/bindings/ata/tegra-sata.txt32
-rw-r--r--Documentation/devicetree/bindings/ata/ti,da850-ahci.yaml39
-rw-r--r--Documentation/devicetree/bindings/ata/ti,dm816-ahci.yaml43
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml44
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/gpio-7-segment.yaml55
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/hit,hd44780.yaml127
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/holtek,ht16k33.yaml104
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml55
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/maxim,max6959.yaml44
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/modtronix,lcd2s.yaml58
-rw-r--r--Documentation/devicetree/bindings/board/fsl,bcsr.yaml32
-rw-r--r--Documentation/devicetree/bindings/board/fsl,fpga-qixis-i2c.yaml128
-rw-r--r--Documentation/devicetree/bindings/board/fsl,fpga-qixis.yaml91
-rw-r--r--Documentation/devicetree/bindings/btmrvl.txt29
-rw-r--r--Documentation/devicetree/bindings/bus/allwinner,sun50i-a64-de2.yaml88
-rw-r--r--Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml82
-rw-r--r--Documentation/devicetree/bindings/bus/arm,integrator-ap-lm.yaml83
-rw-r--r--Documentation/devicetree/bindings/bus/aspeed,ast2600-ahbc.yaml37
-rw-r--r--Documentation/devicetree/bindings/bus/baikal,bt1-apb.yaml90
-rw-r--r--Documentation/devicetree/bindings/bus/baikal,bt1-axi.yaml107
-rw-r--r--Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt34
-rw-r--r--Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml67
-rw-r--r--Documentation/devicetree/bindings/bus/cznic,moxtet.yaml94
-rw-r--r--Documentation/devicetree/bindings/bus/fsl,imx8mp-aipstz.yaml104
-rw-r--r--Documentation/devicetree/bindings/bus/fsl,imx8qxp-pixel-link-msi-bus.yaml232
-rw-r--r--Documentation/devicetree/bindings/bus/fsl,spba-bus.yaml68
-rw-r--r--Documentation/devicetree/bindings/bus/imx-weim.txt82
-rw-r--r--Documentation/devicetree/bindings/bus/microsoft,vmbus.yaml66
-rw-r--r--Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml37
-rw-r--r--Documentation/devicetree/bindings/bus/mvebu-mbus.txt3
-rw-r--r--Documentation/devicetree/bindings/bus/nvidia,tegra20-gmi.txt128
-rw-r--r--Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml84
-rw-r--r--Documentation/devicetree/bindings/bus/palmbus.yaml80
-rw-r--r--Documentation/devicetree/bindings/bus/qcom,ssbi.yaml63
-rw-r--r--Documentation/devicetree/bindings/bus/qcom,ssc-block-bus.yaml144
-rw-r--r--Documentation/devicetree/bindings/bus/renesas,bsc.txt46
-rw-r--r--Documentation/devicetree/bindings/bus/renesas,bsc.yaml74
-rw-r--r--Documentation/devicetree/bindings/bus/simple-pm-bus.txt44
-rw-r--r--Documentation/devicetree/bindings/bus/simple-pm-bus.yaml77
-rw-r--r--Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml103
-rw-r--r--Documentation/devicetree/bindings/bus/st,stm32-etzpc.yaml96
-rw-r--r--Documentation/devicetree/bindings/bus/st,stm32mp25-rifsc.yaml109
-rw-r--r--Documentation/devicetree/bindings/bus/ti,da850-mstpri.txt20
-rw-r--r--Documentation/devicetree/bindings/bus/ti-gpmc.txt130
-rw-r--r--Documentation/devicetree/bindings/bus/ti-sysc.yaml215
-rw-r--r--Documentation/devicetree/bindings/bus/ts-nbus.txt50
-rw-r--r--Documentation/devicetree/bindings/bus/xlnx,versal-net-cdx.yaml82
-rw-r--r--Documentation/devicetree/bindings/c6x/clocks.txt40
-rw-r--r--Documentation/devicetree/bindings/c6x/dscr.txt127
-rw-r--r--Documentation/devicetree/bindings/c6x/emifa.txt62
-rw-r--r--Documentation/devicetree/bindings/c6x/interrupt.txt104
-rw-r--r--Documentation/devicetree/bindings/c6x/soc.txt28
-rw-r--r--Documentation/devicetree/bindings/c6x/timer64.txt26
-rw-r--r--Documentation/devicetree/bindings/cache/andestech,ax45mp-cache.yaml103
-rw-r--r--Documentation/devicetree/bindings/cache/baikal,bt1-l2-ctl.yaml63
-rw-r--r--Documentation/devicetree/bindings/cache/freescale-l2cache.txt55
-rw-r--r--Documentation/devicetree/bindings/cache/l2c2x0.yaml241
-rw-r--r--Documentation/devicetree/bindings/cache/marvell,kirkwood-cache.yaml45
-rw-r--r--Documentation/devicetree/bindings/cache/marvell,tauros2-cache.yaml39
-rw-r--r--Documentation/devicetree/bindings/cache/qcom,llcc.yaml319
-rw-r--r--Documentation/devicetree/bindings/cache/sifive,ccache0.yaml217
-rw-r--r--Documentation/devicetree/bindings/cache/socionext,uniphier-system-cache.yaml101
-rw-r--r--Documentation/devicetree/bindings/cache/starfive,jh8100-starlink-cache.yaml66
-rw-r--r--Documentation/devicetree/bindings/chosen.txt46
-rw-r--r--Documentation/devicetree/bindings/chrome/google,cros-ec-typec.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/actions,owl-cmu.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/adi,axi-clkgen.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/airoha,en7523-scu.yaml100
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ahb-clk.yaml108
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb0-clk.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-apb1-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-axi-clk.yaml61
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml153
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-cpu-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-display-clk.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-gates-clk.yaml151
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mbus-clk.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mmc-clk.yaml87
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod0-clk.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-mod1-clk.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-osc-clk.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll1-clk.yaml71
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll3-clk.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll5-clk.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-pll6-clk.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-tcon-ch0-clk.yaml77
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-usb-clk.yaml166
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ve-clk.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun55i-a523-ccu.yaml136
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun5i-a13-ahb-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun6i-a31-pll6-clk.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-gmac-clk.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun7i-a20-out-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun8i-a83t-de2-clk.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun8i-h3-bus-gates-clk.yaml103
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-ahb-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-apb0-clk.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-cpus-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-de-clks.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-gt-clk.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-mmc-config-clk.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-pll4-clk.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-clks.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-mod-clk.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/allwinner,sun9i-a80-usb-phy-clk.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/alphascale,acc.txt115
-rw-r--r--Documentation/devicetree/bindings/clock/alphascale,asm9260-clock-controller.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/altr_socfpga.txt30
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,a1-peripherals-clkc.yaml78
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,a1-pll-clkc.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.yaml201
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,c3-peripherals-clkc.yaml120
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,c3-pll-clkc.yaml62
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.yaml85
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.yaml37
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,meson8-clkc.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,meson8-ddr-clkc.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml96
-rw-r--r--Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/apm,xgene-device-clock.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/apm,xgene-socpll-clock.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/apple,nco.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/arm,syscon-icst.yaml110
-rw-r--r--Documentation/devicetree/bindings/clock/arm-integrator.txt34
-rw-r--r--Documentation/devicetree/bindings/clock/at91-clock.txt463
-rw-r--r--Documentation/devicetree/bindings/clock/atmel,at91rm9200-pmc.yaml162
-rw-r--r--Documentation/devicetree/bindings/clock/atmel,at91sam9x5-sckc.yaml73
-rw-r--r--Documentation/devicetree/bindings/clock/axi-clkgen.txt22
-rw-r--r--Documentation/devicetree/bindings/clock/axis,artpec6-clkctrl.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/axis,artpec8-clock.yaml213
-rw-r--r--Documentation/devicetree/bindings/clock/axs10x-i2s-pll-clock.txt25
-rw-r--r--Documentation/devicetree/bindings/clock/baikal,bt1-ccu-div.yaml196
-rw-r--r--Documentation/devicetree/bindings/clock/baikal,bt1-ccu-pll.yaml131
-rw-r--r--Documentation/devicetree/bindings/clock/bcm-cygnus-clock.txt34
-rw-r--r--Documentation/devicetree/bindings/clock/bitmain,bm1880-clk.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,bcm53573-ilp.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,bcm63268-timer-clocks.yaml40
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.yaml44
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,iproc-clocks.yaml417
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,kona-ccu.txt139
-rw-r--r--Documentation/devicetree/bindings/clock/brcm,kona-ccu.yaml181
-rw-r--r--Documentation/devicetree/bindings/clock/calxeda.txt17
-rw-r--r--Documentation/devicetree/bindings/clock/calxeda.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/canaan,k210-clk.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/cirrus,cs2000-cp.yaml90
-rw-r--r--Documentation/devicetree/bindings/clock/cirrus,ep7209-clk.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/cirrus,lochnagar.yaml78
-rw-r--r--Documentation/devicetree/bindings/clock/clk-exynos-audss.txt95
-rw-r--r--Documentation/devicetree/bindings/clock/clk-s5pv210-audss.txt53
-rw-r--r--Documentation/devicetree/bindings/clock/clock-bindings.txt171
-rw-r--r--Documentation/devicetree/bindings/clock/clps711x-clock.txt19
-rw-r--r--Documentation/devicetree/bindings/clock/efm32-clock.txt11
-rw-r--r--Documentation/devicetree/bindings/clock/emev2-clock.txt98
-rw-r--r--Documentation/devicetree/bindings/clock/exynos3250-clock.txt57
-rw-r--r--Documentation/devicetree/bindings/clock/exynos4-clock.txt43
-rw-r--r--Documentation/devicetree/bindings/clock/exynos4415-clock.txt38
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5250-clock.txt41
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5260-clock.txt190
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5410-clock.txt45
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5420-clock.txt42
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5433-clock.txt462
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5440-clock.txt28
-rw-r--r--Documentation/devicetree/bindings/clock/exynos7-clock.txt108
-rw-r--r--Documentation/devicetree/bindings/clock/fixed-clock.txt23
-rw-r--r--Documentation/devicetree/bindings/clock/fixed-clock.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/fixed-factor-clock.txt24
-rw-r--r--Documentation/devicetree/bindings/clock/fixed-factor-clock.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/fixed-mmio-clock.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,flexspi-clock.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,imx8-acm.yaml282
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,imx8m-anatop.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,imx8ulp-sim-lpav.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,imx93-anatop.yaml42
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,plldig.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,qoriq-clock-legacy.yaml84
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,qoriq-clock.yaml207
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,sai-clock.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,scu-clk.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/fsl,vf610-ccm.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/fujitsu,mb86s70-crg11.txt26
-rw-r--r--Documentation/devicetree/bindings/clock/gated-fixed-clock.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/google,gs101-clock.yaml184
-rw-r--r--Documentation/devicetree/bindings/clock/gpio-gate-clock.txt21
-rw-r--r--Documentation/devicetree/bindings/clock/gpio-gate-clock.yaml42
-rw-r--r--Documentation/devicetree/bindings/clock/gpio-mux-clock.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/hi3620-clock.txt20
-rw-r--r--Documentation/devicetree/bindings/clock/hi3660-clock.txt47
-rw-r--r--Documentation/devicetree/bindings/clock/hi3670-clock.txt43
-rw-r--r--Documentation/devicetree/bindings/clock/hi6220-clock.txt52
-rw-r--r--Documentation/devicetree/bindings/clock/hisi-crg.txt50
-rw-r--r--Documentation/devicetree/bindings/clock/hisilicon,hi3559av100-clock.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/hix5hd2-clock.txt31
-rw-r--r--Documentation/devicetree/bindings/clock/idt,versaclock5.yaml195
-rw-r--r--Documentation/devicetree/bindings/clock/img,boston-clock.txt31
-rw-r--r--Documentation/devicetree/bindings/clock/img,pistachio-clk.yaml136
-rw-r--r--Documentation/devicetree/bindings/clock/imx1-clock.txt26
-rw-r--r--Documentation/devicetree/bindings/clock/imx1-clock.yaml42
-rw-r--r--Documentation/devicetree/bindings/clock/imx21-clock.txt28
-rw-r--r--Documentation/devicetree/bindings/clock/imx21-clock.yaml42
-rw-r--r--Documentation/devicetree/bindings/clock/imx23-clock.txt71
-rw-r--r--Documentation/devicetree/bindings/clock/imx23-clock.yaml85
-rw-r--r--Documentation/devicetree/bindings/clock/imx25-clock.txt161
-rw-r--r--Documentation/devicetree/bindings/clock/imx25-clock.yaml178
-rw-r--r--Documentation/devicetree/bindings/clock/imx27-clock.txt28
-rw-r--r--Documentation/devicetree/bindings/clock/imx27-clock.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/imx28-clock.txt94
-rw-r--r--Documentation/devicetree/bindings/clock/imx28-clock.yaml108
-rw-r--r--Documentation/devicetree/bindings/clock/imx31-clock.txt91
-rw-r--r--Documentation/devicetree/bindings/clock/imx31-clock.yaml112
-rw-r--r--Documentation/devicetree/bindings/clock/imx35-clock.txt113
-rw-r--r--Documentation/devicetree/bindings/clock/imx35-clock.yaml131
-rw-r--r--Documentation/devicetree/bindings/clock/imx5-clock.txt29
-rw-r--r--Documentation/devicetree/bindings/clock/imx5-clock.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/imx6q-clock.txt31
-rw-r--r--Documentation/devicetree/bindings/clock/imx6q-clock.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/imx6sl-clock.txt10
-rw-r--r--Documentation/devicetree/bindings/clock/imx6sl-clock.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/imx6sll-clock.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/imx6sx-clock.txt13
-rw-r--r--Documentation/devicetree/bindings/clock/imx6sx-clock.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/imx6ul-clock.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/imx7d-clock.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml110
-rw-r--r--Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml88
-rw-r--r--Documentation/devicetree/bindings/clock/imx8m-clock.yaml133
-rw-r--r--Documentation/devicetree/bindings/clock/imx8mp-audiomix.yaml84
-rw-r--r--Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml103
-rw-r--r--Documentation/devicetree/bindings/clock/imx8ulp-cgc-clock.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/imx8ulp-pcc-clock.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/imx93-clock.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/imxrt1050-clock.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/ingenic,cgu.yaml132
-rw-r--r--Documentation/devicetree/bindings/clock/intel,agilex.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/intel,agilex5-clkmgr.yaml40
-rw-r--r--Documentation/devicetree/bindings/clock/intel,cgu-lgm.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/intel,easic-n5x.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/intel,stratix10.yaml35
-rw-r--r--Documentation/devicetree/bindings/clock/keystone-gate.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/keystone-pll.txt12
-rw-r--r--Documentation/devicetree/bindings/clock/loongson,ls1x-clk.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/loongson,ls2k-clk.yaml77
-rw-r--r--Documentation/devicetree/bindings/clock/lsi,axm5516-clks.txt29
-rw-r--r--Documentation/devicetree/bindings/clock/lsi,axm5516-clks.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/lsi,nspire-cx-clock.yaml33
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,ap80x-clock.yaml54
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,armada-370-corediv-clock.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,armada-3700-periph-clock.yaml96
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,armada-3700-tbg-clock.yaml54
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,armada-3700-uart-clock.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,armada-xp-cpu-clock.yaml44
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,berlin2-clk.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,cp110-clock.yaml70
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,dove-divider-clock.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,mmp2-audio-clock.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,mmp2-clock.yaml69
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,mmp2.txt21
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,mvebu-core-clock.yaml94
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,pxa1908.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/marvell,pxa1928.txt21
-rw-r--r--Documentation/devicetree/bindings/clock/marvell-armada-370-gating-clock.yaml227
-rw-r--r--Documentation/devicetree/bindings/clock/maxim,max77686.txt46
-rw-r--r--Documentation/devicetree/bindings/clock/maxim,max77802.txt44
-rw-r--r--Documentation/devicetree/bindings/clock/maxim,max9485.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,apmixedsys.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,ethsys.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,infracfg.yaml87
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt2701-hifsys.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt6795-clock.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt7621-sysc.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt7622-pciesys.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt7622-ssusbsys.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt7988-ethwarp.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt7988-xfi-pll.yaml48
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8186-clock.yaml56
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8186-fhctl.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8186-sys-clock.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8188-clock.yaml93
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8188-sys-clock.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8192-clock.yaml191
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8192-sys-clock.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8195-clock.yaml238
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8195-sys-clock.yaml76
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8196-clock.yaml112
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8196-sys-clock.yaml107
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8365-clock.yaml42
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mt8365-sys-clock.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,mtmips-sysc.yaml77
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,pericfg.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,syscon.yaml112
-rw-r--r--Documentation/devicetree/bindings/clock/mediatek,topckgen.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/microchip,lan966x-gck.yaml71
-rw-r--r--Documentation/devicetree/bindings/clock/microchip,mpfs-ccc.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/microchip,mpfs-clkcfg.yaml88
-rw-r--r--Documentation/devicetree/bindings/clock/microchip,pic32mzda-clk.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/milbeaut-clock.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/moxa,moxart-clock.txt48
-rw-r--r--Documentation/devicetree/bindings/clock/moxa,moxart-clock.yaml38
-rw-r--r--Documentation/devicetree/bindings/clock/mstar,msc313-cpupll.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/mstar,msc313-mpll.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/mvebu-core-clock.txt78
-rw-r--r--Documentation/devicetree/bindings/clock/mvebu-corediv-clock.txt22
-rw-r--r--Documentation/devicetree/bindings/clock/mvebu-cpu-clock.txt22
-rw-r--r--Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt191
-rw-r--r--Documentation/devicetree/bindings/clock/nspire-clock.txt24
-rw-r--r--Documentation/devicetree/bindings/clock/nuvoton,ma35d1-clk.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/nuvoton,npcm750-clk.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/nuvoton,npcm845-clk.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra114-car.txt63
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra124-car.txt65
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra124-car.yaml110
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt155
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra20-car.txt63
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra20-car.yaml99
-rw-r--r--Documentation/devicetree/bindings/clock/nvidia,tegra30-car.txt63
-rw-r--r--Documentation/devicetree/bindings/clock/nxp,imx95-blk-ctl.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/nxp,imx95-display-master-csr.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/nxp,lpc1850-ccu.yaml104
-rw-r--r--Documentation/devicetree/bindings/clock/nxp,lpc1850-cgu.yaml99
-rw-r--r--Documentation/devicetree/bindings/clock/nxp,lpc3220-clk.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/nxp,lpc3220-usb-clk.yaml35
-rw-r--r--Documentation/devicetree/bindings/clock/pistachio-clock.txt123
-rw-r--r--Documentation/devicetree/bindings/clock/prima2-clock.txt73
-rw-r--r--Documentation/devicetree/bindings/clock/pwm-clock.txt26
-rw-r--r--Documentation/devicetree/bindings/clock/pwm-clock.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/pxa-clock.txt1
-rw-r--r--Documentation/devicetree/bindings/clock/qca,ath79-pll.yaml70
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,a53pll.yaml70
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,a7pll.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,aoncc-sm8250.yaml61
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,audiocc-sm8250.yaml61
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,camcc-sm8250.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,dispcc-sc8280xp.yaml85
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,dispcc-sm6125.yaml106
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,dispcc-sm6350.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,dispcc-sm8x50.yaml123
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-apq8064.yaml99
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-apq8084.yaml87
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-ipq4019.yaml54
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-ipq6018.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-ipq8064.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-ipq8074.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-mdm9607.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-mdm9615.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8660.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8909.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8916.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8953.yaml79
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8974.yaml62
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8976.yaml84
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8994.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8996.yaml69
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-msm8998.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-qcm2290.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-qcs404.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sc7180.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sc7280.yaml86
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sc8280xp.yaml122
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sdm660.yaml62
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sdm845.yaml101
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sdx55.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sdx65.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm6115.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm6125.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm6350.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm8150.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm8250.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm8350.yaml79
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc-sm8450.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc.txt27
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gcc.yaml41
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,glymur-dispcc.yaml98
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,glymur-gcc.yaml121
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gpucc-sdm660.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,gpucc.yaml96
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,hfpll.yaml69
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,ipq5018-gcc.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,ipq5332-gcc.yaml83
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,ipq5424-apss-clk.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,ipq9574-cmn-pll.yaml79
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,ipq9574-gcc.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,ipq9574-nsscc.yaml145
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,kpss-acc-v1.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,kpss-gcc.yaml88
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,krait-cc.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,lcc.txt21
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,lcc.yaml120
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,milos-camcc.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,milos-dispcc.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,milos-gcc.yaml62
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,milos-videocc.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,mmcc.txt23
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,mmcc.yaml346
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,msm8996-cbf.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,msm8998-gpucc.yaml56
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qca8k-nsscc.yaml86
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcm2290-dispcc.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcm2290-gpucc.yaml77
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcs404-turingcc.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcs615-dispcc.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcs615-gcc.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcs615-gpucc.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcs615-videocc.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qcs8300-gcc.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qdu1000-ecpricc.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,qdu1000-gcc.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,rpmcc.yaml166
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sa8775p-camcc.yaml81
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sa8775p-dispcc.yaml79
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sa8775p-gcc.yaml85
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sa8775p-videocc.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sar2130p-gcc.yaml65
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7180-camcc.yaml62
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7180-dispcc.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7180-lpasscorecc.yaml107
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7280-camcc.yaml61
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7280-dispcc.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscc.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc7280-lpasscorecc.yaml202
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc8180x-camcc.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sc8280xp-lpasscc.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sdm845-camcc.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sdm845-dispcc.yaml89
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sdm845-lpasscc.yaml47
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sdx75-gcc.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm4450-camcc.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm4450-dispcc.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml56
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6115-dispcc.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6115-gpucc.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6115-lpasscc.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6125-gpucc.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6350-camcc.yaml54
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6375-dispcc.yaml54
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6375-gcc.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm6375-gpucc.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm7150-camcc.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm7150-dispcc.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm7150-gcc.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm7150-videocc.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8150-camcc.yaml65
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8350-videocc.yaml70
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml95
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8450-dispcc.yaml86
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8450-videocc.yaml91
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml101
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8550-gcc.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml68
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8650-gcc.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,sm8750-gcc.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.yaml71
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,videocc.yaml166
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,x1e80100-camcc.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/qcom,x1e80100-gcc.yaml131
-rw-r--r--Documentation/devicetree/bindings/clock/qoriq-clock.txt153
-rw-r--r--Documentation/devicetree/bindings/clock/raspberrypi,rp1-clocks.yaml58
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,5p35023.yaml90
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,9series.yaml113
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml245
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,cpg-div6-clock.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt34
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml152
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt57
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,emev2-smu.yaml140
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt33
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt41
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt25
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt27
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.yaml73
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,r9a08g045-vbattb.yaml84
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,rcar-gen2-cpg-clocks.txt37
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,rcar-usb2-clock-sel.yaml101
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt29
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml89
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,rzv2h-cpg.yaml84
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt35
-rw-r--r--Documentation/devicetree/bindings/clock/renesas,versaclock7.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/riscv,rpmi-clock.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,px30-cru.yaml119
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3036-cru.yaml72
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3128-cru.yaml76
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3188-cru.txt61
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3188-cru.yaml78
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3228-cru.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.txt61
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3288-cru.yaml85
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3308-cru.yaml76
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.yaml74
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3368-cru.yaml78
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.yaml83
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3506-cru.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3528-cru.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3562-cru.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3568-cru.yaml73
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3576-cru.yaml56
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rk3588-cru.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rv1108-cru.yaml75
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rv1126-cru.yaml62
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip,rv1126b-cru.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/rockchip.txt77
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos-audss-clock.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos-clock.yaml60
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos-ext-clock.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos2200-cmu.yaml247
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos4412-isp-clock.yaml63
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos5260-clock.yaml382
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos5410-clock.yaml66
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos5433-clock.yaml524
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos7-clock.yaml272
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos7870-cmu.yaml227
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml193
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos850-clock.yaml353
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos8895-clock.yaml239
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynos990-clock.yaml164
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynosautov9-clock.yaml282
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,exynosautov920-clock.yaml298
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s2mps11.yaml45
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s3c2410-clock.txt50
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s3c2412-clock.txt50
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s3c2443-clock.txt56
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s3c6400-clock.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s3c64xx-clock.txt77
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s5pv210-audss-clock.yaml78
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.txt78
-rw-r--r--Documentation/devicetree/bindings/clock/samsung,s5pv210-clock.yaml79
-rw-r--r--Documentation/devicetree/bindings/clock/sifive/fu540-prci.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/sifive/fu740-prci.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/silabs,si5341.yaml223
-rw-r--r--Documentation/devicetree/bindings/clock/silabs,si5351.txt119
-rw-r--r--Documentation/devicetree/bindings/clock/silabs,si5351.yaml265
-rw-r--r--Documentation/devicetree/bindings/clock/silabs,si544.yaml54
-rw-r--r--Documentation/devicetree/bindings/clock/silabs,si570.txt39
-rw-r--r--Documentation/devicetree/bindings/clock/silabs,si570.yaml80
-rw-r--r--Documentation/devicetree/bindings/clock/skyworks,si521xx.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/snps,hsdk-pll-clock.txt28
-rw-r--r--Documentation/devicetree/bindings/clock/snps,pll-clock.txt28
-rw-r--r--Documentation/devicetree/bindings/clock/socionext,uniphier-clock.yaml67
-rw-r--r--Documentation/devicetree/bindings/clock/sophgo,cv1800-clk.yaml55
-rw-r--r--Documentation/devicetree/bindings/clock/sophgo,sg2042-clkgen.yaml61
-rw-r--r--Documentation/devicetree/bindings/clock/sophgo,sg2042-pll.yaml53
-rw-r--r--Documentation/devicetree/bindings/clock/sophgo,sg2042-rpgate.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/sophgo,sg2044-clk.yaml99
-rw-r--r--Documentation/devicetree/bindings/clock/spacemit,k1-pll.yaml50
-rw-r--r--Documentation/devicetree/bindings/clock/sprd,sc9860-clk.yaml159
-rw-r--r--Documentation/devicetree/bindings/clock/sprd,sc9863a-clk.yaml102
-rw-r--r--Documentation/devicetree/bindings/clock/sprd,ums512-clk.yaml71
-rw-r--r--Documentation/devicetree/bindings/clock/st,stm32-rcc.yaml144
-rw-r--r--Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.yaml131
-rw-r--r--Documentation/devicetree/bindings/clock/st,stm32mp21-rcc.yaml199
-rw-r--r--Documentation/devicetree/bindings/clock/st,stm32mp25-rcc.yaml219
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,clkgen-divmux.txt49
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,clkgen-mux.txt20
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt37
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,clkgen-prediv.txt36
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,clkgen-vcc.txt61
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,clkgen.txt64
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,flexgen.txt13
-rw-r--r--Documentation/devicetree/bindings/clock/st/st,quadfs.txt34
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7100-audclk.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7100-clkgen.yaml56
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7110-aoncrg.yaml107
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7110-ispcrg.yaml87
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7110-pll.yaml46
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7110-stgcrg.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7110-syscrg.yaml118
-rw-r--r--Documentation/devicetree/bindings/clock/starfive,jh7110-voutcrg.yaml90
-rw-r--r--Documentation/devicetree/bindings/clock/ste-u300-syscon-clock.txt80
-rw-r--r--Documentation/devicetree/bindings/clock/stericsson,u8500-clks.yaml178
-rw-r--r--Documentation/devicetree/bindings/clock/sunplus,sp7021-clkc.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/sunxi.txt204
-rw-r--r--Documentation/devicetree/bindings/clock/tesla,fsd-clock.yaml198
-rw-r--r--Documentation/devicetree/bindings/clock/thead,th1520-clk-ap.yaml64
-rw-r--r--Documentation/devicetree/bindings/clock/ti,am62-audio-refclk.yaml43
-rw-r--r--Documentation/devicetree/bindings/clock/ti,am654-ehrpwm-tbclk.yaml39
-rw-r--r--Documentation/devicetree/bindings/clock/ti,cdce706.txt4
-rw-r--r--Documentation/devicetree/bindings/clock/ti,cdce925.yaml103
-rw-r--r--Documentation/devicetree/bindings/clock/ti,clkctrl.yaml65
-rw-r--r--Documentation/devicetree/bindings/clock/ti,lmk04832.yaml209
-rw-r--r--Documentation/devicetree/bindings/clock/ti,sci-clk.yaml49
-rw-r--r--Documentation/devicetree/bindings/clock/ti-keystone-pllctrl.txt20
-rw-r--r--Documentation/devicetree/bindings/clock/ti/adpll.txt39
-rw-r--r--Documentation/devicetree/bindings/clock/ti/apll.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/ti/autoidle.txt39
-rw-r--r--Documentation/devicetree/bindings/clock/ti/clockdomain.txt5
-rw-r--r--Documentation/devicetree/bindings/clock/ti/composite.txt54
-rw-r--r--Documentation/devicetree/bindings/clock/ti/davinci/da8xx-cfgchip.txt93
-rw-r--r--Documentation/devicetree/bindings/clock/ti/davinci/pll.txt96
-rw-r--r--Documentation/devicetree/bindings/clock/ti/davinci/psc.txt71
-rw-r--r--Documentation/devicetree/bindings/clock/ti/divider.txt114
-rw-r--r--Documentation/devicetree/bindings/clock/ti/dpll.txt22
-rw-r--r--Documentation/devicetree/bindings/clock/ti/dra7-atl.txt8
-rw-r--r--Documentation/devicetree/bindings/clock/ti/fapll.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/ti/fixed-factor-clock.txt43
-rw-r--r--Documentation/devicetree/bindings/clock/ti/gate.txt106
-rw-r--r--Documentation/devicetree/bindings/clock/ti/interface.txt56
-rw-r--r--Documentation/devicetree/bindings/clock/ti/mux.txt76
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,autoidle.yaml34
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,clksel.yaml51
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,composite-clock.yaml82
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,divider-clock.yaml179
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,fixed-factor-clock.yaml76
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,gate-clock.yaml125
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,interface-clock.yaml71
-rw-r--r--Documentation/devicetree/bindings/clock/ti/ti,mux-clock.yaml125
-rw-r--r--Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pipllct.yaml57
-rw-r--r--Documentation/devicetree/bindings/clock/toshiba,tmpv770x-pismu.yaml52
-rw-r--r--Documentation/devicetree/bindings/clock/vf610-clock.txt41
-rw-r--r--Documentation/devicetree/bindings/clock/xgene.txt111
-rw-r--r--Documentation/devicetree/bindings/clock/xlnx,clocking-wizard.yaml83
-rw-r--r--Documentation/devicetree/bindings/clock/xlnx,vcu.yaml59
-rw-r--r--Documentation/devicetree/bindings/clock/xlnx,versal-clk.yaml146
-rw-r--r--Documentation/devicetree/bindings/common-properties.txt45
-rw-r--r--Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml88
-rw-r--r--Documentation/devicetree/bindings/connector/usb-connector.yaml531
-rw-r--r--Documentation/devicetree/bindings/counter/fsl,ftm-quaddec.yaml36
-rw-r--r--Documentation/devicetree/bindings/counter/interrupt-counter.yaml62
-rw-r--r--Documentation/devicetree/bindings/counter/ti,am62-ecap-capture.yaml61
-rw-r--r--Documentation/devicetree/bindings/counter/ti-eqep.yaml67
-rw-r--r--Documentation/devicetree/bindings/cpu/cpu-capacity.txt238
-rw-r--r--Documentation/devicetree/bindings/cpu/idle-states.yaml928
-rw-r--r--Documentation/devicetree/bindings/cpufreq/airoha,en7581-cpufreq.yaml55
-rw-r--r--Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml128
-rw-r--r--Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt65
-rw-r--r--Documentation/devicetree/bindings/cpufreq/brcm,stb-avs-cpu-freq.txt76
-rw-r--r--Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt64
-rw-r--r--Documentation/devicetree/bindings/cpufreq/cpufreq-exynos5440.txt28
-rw-r--r--Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek-hw.yaml70
-rw-r--r--Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml406
-rw-r--r--Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt89
-rw-r--r--Documentation/devicetree/bindings/cpufreq/imx-cpufreq-dt.txt37
-rw-r--r--Documentation/devicetree/bindings/cpufreq/mediatek,mt8196-cpufreq-hw.yaml82
-rw-r--r--Documentation/devicetree/bindings/cpufreq/nvidia,tegra124-cpufreq.txt40
-rw-r--r--Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt56
-rw-r--r--Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml211
-rw-r--r--Documentation/devicetree/bindings/cpufreq/qemu,virtual-cpufreq.yaml48
-rw-r--r--Documentation/devicetree/bindings/cris/axis.txt9
-rw-r--r--Documentation/devicetree/bindings/cris/boards.txt8
-rw-r--r--Documentation/devicetree/bindings/cris/interrupts.txt23
-rw-r--r--Documentation/devicetree/bindings/crypto/allwinner,sun4i-a10-crypto.yaml95
-rw-r--r--Documentation/devicetree/bindings/crypto/allwinner,sun8i-ce.yaml103
-rw-r--r--Documentation/devicetree/bindings/crypto/allwinner,sun8i-ss.yaml60
-rw-r--r--Documentation/devicetree/bindings/crypto/amd,ccp-seattle-v1a.yaml41
-rw-r--r--Documentation/devicetree/bindings/crypto/amd-ccp.txt19
-rw-r--r--Documentation/devicetree/bindings/crypto/amlogic,gxl-crypto.yaml52
-rw-r--r--Documentation/devicetree/bindings/crypto/arm,cryptocell.yaml53
-rw-r--r--Documentation/devicetree/bindings/crypto/aspeed,ast2500-hace.yaml53
-rw-r--r--Documentation/devicetree/bindings/crypto/aspeed,ast2600-acry.yaml49
-rw-r--r--Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-aes.yaml72
-rw-r--r--Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-sha.yaml66
-rw-r--r--Documentation/devicetree/bindings/crypto/atmel,at91sam9g46-tdes.yaml70
-rw-r--r--Documentation/devicetree/bindings/crypto/atmel-crypto.txt68
-rw-r--r--Documentation/devicetree/bindings/crypto/axis,artpec6-crypto.yaml39
-rw-r--r--Documentation/devicetree/bindings/crypto/brcm,spum-crypto.yaml44
-rw-r--r--Documentation/devicetree/bindings/crypto/cortina,sl3516-crypto.yaml50
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl,sec-v4.0-mon.yaml167
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl,sec-v4.0.yaml318
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl,sec2.0.yaml144
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-dcp.txt17
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-dcp.yaml56
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt15
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml74
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-imx-scc.yaml54
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-sec2.txt68
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-sec4.txt455
-rw-r--r--Documentation/devicetree/bindings/crypto/fsl-sec6.txt157
-rw-r--r--Documentation/devicetree/bindings/crypto/hisilicon,hip06-sec.yaml134
-rw-r--r--Documentation/devicetree/bindings/crypto/img,hash-accelerator.yaml69
-rw-r--r--Documentation/devicetree/bindings/crypto/img-hash.txt27
-rw-r--r--Documentation/devicetree/bindings/crypto/inside-secure,safexcel-eip93.yaml67
-rw-r--r--Documentation/devicetree/bindings/crypto/inside-secure,safexcel.yaml88
-rw-r--r--Documentation/devicetree/bindings/crypto/intel,ixp4xx-crypto.yaml56
-rw-r--r--Documentation/devicetree/bindings/crypto/intel,keembay-ocs-aes.yaml45
-rw-r--r--Documentation/devicetree/bindings/crypto/intel,keembay-ocs-ecc.yaml47
-rw-r--r--Documentation/devicetree/bindings/crypto/intel,keembay-ocs-hcu.yaml46
-rw-r--r--Documentation/devicetree/bindings/crypto/marvell,orion-crypto.yaml133
-rw-r--r--Documentation/devicetree/bindings/crypto/mv_cesa.txt20
-rw-r--r--Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-aes.yaml52
-rw-r--r--Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-hash.yaml52
-rw-r--r--Documentation/devicetree/bindings/crypto/omap-aes.txt31
-rw-r--r--Documentation/devicetree/bindings/crypto/omap-des.txt30
-rw-r--r--Documentation/devicetree/bindings/crypto/omap-sham.txt28
-rw-r--r--Documentation/devicetree/bindings/crypto/picochip-spacc.txt23
-rw-r--r--Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml50
-rw-r--r--Documentation/devicetree/bindings/crypto/qcom,prng.yaml70
-rw-r--r--Documentation/devicetree/bindings/crypto/qcom-qce.txt25
-rw-r--r--Documentation/devicetree/bindings/crypto/qcom-qce.yaml178
-rw-r--r--Documentation/devicetree/bindings/crypto/rockchip,rk3288-crypto.yaml127
-rw-r--r--Documentation/devicetree/bindings/crypto/samsung-slimsss.yaml45
-rw-r--r--Documentation/devicetree/bindings/crypto/samsung-sss.txt34
-rw-r--r--Documentation/devicetree/bindings/crypto/samsung-sss.yaml57
-rw-r--r--Documentation/devicetree/bindings/crypto/st,stm32-crc.yaml38
-rw-r--r--Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml74
-rw-r--r--Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml94
-rw-r--r--Documentation/devicetree/bindings/crypto/starfive,jh7110-crypto.yaml96
-rw-r--r--Documentation/devicetree/bindings/crypto/ti,am62l-dthev2.yaml50
-rw-r--r--Documentation/devicetree/bindings/crypto/ti,omap-sham.yaml56
-rw-r--r--Documentation/devicetree/bindings/crypto/ti,omap2-aes.yaml58
-rw-r--r--Documentation/devicetree/bindings/crypto/ti,omap4-des.yaml65
-rw-r--r--Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml98
-rw-r--r--Documentation/devicetree/bindings/crypto/xlnx,versal-trng.yaml35
-rw-r--r--Documentation/devicetree/bindings/crypto/xlnx,zynqmp-aes.yaml37
-rw-r--r--Documentation/devicetree/bindings/csky/cpus.txt73
-rw-r--r--Documentation/devicetree/bindings/csky/pmu.txt38
-rw-r--r--Documentation/devicetree/bindings/devfreq/event/exynos-ppmu.txt110
-rw-r--r--Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml74
-rw-r--r--Documentation/devicetree/bindings/devfreq/event/samsung,exynos-nocp.yaml48
-rw-r--r--Documentation/devicetree/bindings/devfreq/event/samsung,exynos-ppmu.yaml169
-rw-r--r--Documentation/devicetree/bindings/devfreq/nvidia,tegra30-actmon.yaml129
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-backend.yaml272
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-engine.yaml117
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun4i-a10-display-frontend.yaml124
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun4i-a10-hdmi.yaml170
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tcon.yaml677
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun4i-a10-tv-encoder.yaml56
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun6i-a31-drc.yaml124
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml136
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml140
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml253
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-hdmi-phy.yaml115
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun8i-r40-tcon-top.yaml329
-rw-r--r--Documentation/devicetree/bindings/display/allwinner,sun9i-a80-deu.yaml120
-rw-r--r--Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.yaml157
-rw-r--r--Documentation/devicetree/bindings/display/amlogic,meson-g12a-dw-mipi-dsi.yaml118
-rw-r--r--Documentation/devicetree/bindings/display/amlogic,meson-vpu.yaml149
-rw-r--r--Documentation/devicetree/bindings/display/apple,h7-display-pipe-mipi.yaml83
-rw-r--r--Documentation/devicetree/bindings/display/apple,h7-display-pipe.yaml88
-rw-r--r--Documentation/devicetree/bindings/display/arm,hdlcd.yaml89
-rw-r--r--Documentation/devicetree/bindings/display/arm,komeda.yaml131
-rw-r--r--Documentation/devicetree/bindings/display/arm,malidp.yaml119
-rw-r--r--Documentation/devicetree/bindings/display/arm,pl11x.yaml173
-rw-r--r--Documentation/devicetree/bindings/display/armada/marvell,dove-lcd.txt (renamed from Documentation/devicetree/bindings/drm/armada/marvell,dove-lcd.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/atmel,lcdc-display.yaml103
-rw-r--r--Documentation/devicetree/bindings/display/atmel,lcdc.yaml70
-rw-r--r--Documentation/devicetree/bindings/display/atmel/atmel,hlcdc-display-controller.yaml63
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml191
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml85
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml83
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml116
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml48
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml40
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml45
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml36
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml49
-rw-r--r--Documentation/devicetree/bindings/display/bridge/adi,adv7511.yaml236
-rw-r--r--Documentation/devicetree/bindings/display/bridge/adi,adv7533.yaml188
-rw-r--r--Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml187
-rw-r--r--Documentation/devicetree/bindings/display/bridge/analogix,anx7814.yaml109
-rw-r--r--Documentation/devicetree/bindings/display/bridge/analogix,dp.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/bridge/anx6345.yaml94
-rw-r--r--Documentation/devicetree/bindings/display/bridge/cdns,dsi.yaml180
-rw-r--r--Documentation/devicetree/bindings/display/bridge/cdns,mhdp8546.yaml164
-rw-r--r--Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml123
-rw-r--r--Documentation/devicetree/bindings/display/bridge/chrontel,ch7033.yaml77
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,imx8mp-hdmi-tx.yaml114
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,imx8qxp-ldb.yaml173
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,imx8qxp-pixel-combiner.yaml144
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,imx8qxp-pixel-link.yaml144
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,imx8qxp-pxl2dpi.yaml108
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,imx93-mipi-dsi.yaml115
-rw-r--r--Documentation/devicetree/bindings/display/bridge/fsl,ldb.yaml122
-rw-r--r--Documentation/devicetree/bindings/display/bridge/google,cros-ec-anx7688.yaml80
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ingenic,jz4780-hdmi.yaml84
-rw-r--r--Documentation/devicetree/bindings/display/bridge/intel,keembay-dsi.yaml93
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ite,it6263.yaml251
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ite,it6505.yaml156
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ite,it66121.yaml133
-rw-r--r--Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml124
-rw-r--r--Documentation/devicetree/bindings/display/bridge/lontium,lt9211.yaml117
-rw-r--r--Documentation/devicetree/bindings/display/bridge/lontium,lt9611.yaml124
-rw-r--r--Documentation/devicetree/bindings/display/bridge/lvds-codec.yaml187
-rw-r--r--Documentation/devicetree/bindings/display/bridge/megachips,stdp2690-ge-b850v3-fw.yaml111
-rw-r--r--Documentation/devicetree/bindings/display/bridge/microchip,sam9x75-lvds.yaml55
-rw-r--r--Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml218
-rw-r--r--Documentation/devicetree/bindings/display/bridge/nxp,ptn3460.yaml106
-rw-r--r--Documentation/devicetree/bindings/display/bridge/nxp,tda998x.yaml116
-rw-r--r--Documentation/devicetree/bindings/display/bridge/parade,ps8622.yaml115
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ps8640.yaml121
-rw-r--r--Documentation/devicetree/bindings/display/bridge/renesas,dsi-csi2-tx.yaml170
-rw-r--r--Documentation/devicetree/bindings/display/bridge/renesas,dsi.yaml248
-rw-r--r--Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml130
-rw-r--r--Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml235
-rw-r--r--Documentation/devicetree/bindings/display/bridge/samsung,mipi-dsim.yaml309
-rw-r--r--Documentation/devicetree/bindings/display/bridge/sil,sii8620.yaml108
-rw-r--r--Documentation/devicetree/bindings/display/bridge/sil,sii9022.yaml147
-rw-r--r--Documentation/devicetree/bindings/display/bridge/sil,sii9234.yaml110
-rw-r--r--Documentation/devicetree/bindings/display/bridge/simple-bridge.yaml95
-rw-r--r--Documentation/devicetree/bindings/display/bridge/snps,dw-mipi-dsi.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/bridge/solomon,ssd2825.yaml141
-rw-r--r--Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml66
-rw-r--r--Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.yaml115
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ti,dlpc3433.yaml117
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ti,sn65dsi83.yaml191
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml273
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ti,tdp158.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml119
-rw-r--r--Documentation/devicetree/bindings/display/bridge/toshiba,tc358762.yaml87
-rw-r--r--Documentation/devicetree/bindings/display/bridge/toshiba,tc358764.yaml89
-rw-r--r--Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.yaml203
-rw-r--r--Documentation/devicetree/bindings/display/bridge/toshiba,tc358768.yaml131
-rw-r--r--Documentation/devicetree/bindings/display/bridge/toshiba,tc358775.yaml233
-rw-r--r--Documentation/devicetree/bindings/display/bridge/waveshare,dsi2dpi.yaml103
-rw-r--r--Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt (renamed from Documentation/devicetree/bindings/video/cirrus,clps711x-fb.txt)10
-rw-r--r--Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml53
-rw-r--r--Documentation/devicetree/bindings/display/connector/dp-connector.yaml105
-rw-r--r--Documentation/devicetree/bindings/display/connector/dvi-connector.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/connector/vga-connector.yaml47
-rw-r--r--Documentation/devicetree/bindings/display/dp-aux-bus.yaml37
-rw-r--r--Documentation/devicetree/bindings/display/dsi-controller.yaml93
-rw-r--r--Documentation/devicetree/bindings/display/elgin,jg10309-01.yaml54
-rw-r--r--Documentation/devicetree/bindings/display/faraday,tve200.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/fsl,lcdif.yaml218
-rw-r--r--Documentation/devicetree/bindings/display/fsl,ls1021a-dcu.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/fsl,vf610-tcon.yaml43
-rw-r--r--Documentation/devicetree/bindings/display/google,goldfish-fb.txt17
-rw-r--r--Documentation/devicetree/bindings/display/himax,hx8357.yaml78
-rw-r--r--Documentation/devicetree/bindings/display/hisilicon/dw-dsi.txt72
-rw-r--r--Documentation/devicetree/bindings/display/hisilicon/hisi-ade.txt64
-rw-r--r--Documentation/devicetree/bindings/display/ilitek,ili9225.txt25
-rw-r--r--Documentation/devicetree/bindings/display/ilitek,ili9486.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx-display-subsystem.yaml36
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx-lcdc.yaml146
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx-parallel-display.yaml74
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml118
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx6q-ipu.yaml97
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx6q-ldb.yaml193
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx6qp-pre.yaml55
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx6qp-prg.yaml54
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8mp-hdmi-pai.yaml69
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8mp-hdmi-pvi.yaml84
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-axi-performance-counter.yaml57
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-blit-engine.yaml204
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-blitblend.yaml41
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-clut.yaml44
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-command-sequencer.yaml67
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-constframe.yaml44
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-display-engine.yaml152
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-dither.yaml45
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-extdst.yaml72
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-fetchunit.yaml141
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-filter.yaml43
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-framegen.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-gammacor.yaml32
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-layerblend.yaml39
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-matrix.yaml44
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-pixel-engine.yaml250
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-rop.yaml43
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-safety.yaml34
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-scaling-engine.yaml83
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-signature.yaml53
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-store.yaml96
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc-tcon.yaml45
-rw-r--r--Documentation/devicetree/bindings/display/imx/fsl,imx8qxp-dc.yaml236
-rw-r--r--Documentation/devicetree/bindings/display/imx/nxp,imx8mq-dcss.yaml107
-rw-r--r--Documentation/devicetree/bindings/display/ingenic,ipu.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/ingenic,lcd.yaml128
-rw-r--r--Documentation/devicetree/bindings/display/intel,keembay-display.yaml72
-rw-r--r--Documentation/devicetree/bindings/display/intel,keembay-msscam.yaml43
-rw-r--r--Documentation/devicetree/bindings/display/lvds-data-mapping.yaml115
-rw-r--r--Documentation/devicetree/bindings/display/lvds-dual-ports.yaml63
-rw-r--r--Documentation/devicetree/bindings/display/lvds.yaml31
-rw-r--r--Documentation/devicetree/bindings/display/marvell,pxa2xx-lcdc.txt36
-rw-r--r--Documentation/devicetree/bindings/display/marvell,pxa300-gcu.txt17
-rw-r--r--Documentation/devicetree/bindings/display/mayqueen,pixpaper.yaml63
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,aal.yaml137
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,ccorr.yaml109
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,cec.yaml52
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,color.yaml122
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,dither.yaml109
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,dp.yaml138
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml153
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,dsc.yaml107
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.yaml151
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,ethdr.yaml208
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,gamma.yaml115
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,hdmi-ddc.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,hdmi.yaml136
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,merge.yaml137
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,mt8195-hdmi-ddc.yaml41
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,mt8195-hdmi.yaml151
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,od.yaml97
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,ovl-2l.yaml113
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,ovl.yaml133
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,padding.yaml87
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,postmask.yaml104
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,rdma.yaml144
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,split.yaml114
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,ufoe.yaml107
-rw-r--r--Documentation/devicetree/bindings/display/mediatek/mediatek,wdma.yaml89
-rw-r--r--Documentation/devicetree/bindings/display/mipi-dsi-bus.txt235
-rw-r--r--Documentation/devicetree/bindings/display/msm/dp-controller.yaml372
-rw-r--r--Documentation/devicetree/bindings/display/msm/dpu-common.yaml56
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml482
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-phy-10nm.yaml101
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-phy-14nm.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-phy-20nm.yaml70
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-phy-28nm.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-phy-7nm.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi-phy-common.yaml41
-rw-r--r--Documentation/devicetree/bindings/display/msm/gmu.yaml422
-rw-r--r--Documentation/devicetree/bindings/display/msm/gpu.yaml534
-rw-r--r--Documentation/devicetree/bindings/display/msm/hdmi.yaml241
-rw-r--r--Documentation/devicetree/bindings/display/msm/mdp4.yaml131
-rw-r--r--Documentation/devicetree/bindings/display/msm/mdss-common.yaml106
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,glymur-mdss.yaml264
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,mdp5.yaml157
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml226
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,msm8998-dpu.yaml101
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,msm8998-mdss.yaml278
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,qcm2290-dpu.yaml90
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,qcm2290-mdss.yaml215
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,qcs8300-mdss.yaml286
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sa8775p-mdss.yaml464
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sar2130p-mdss.yaml443
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc7180-dpu.yaml125
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc7180-mdss.yaml322
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc7280-dpu.yaml114
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc7280-mdss.yaml444
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc8180x-dpu.yaml103
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc8180x-mdss.yaml359
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sc8280xp-mdss.yaml155
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sdm670-mdss.yaml292
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sdm845-dpu.yaml98
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sdm845-mdss.yaml288
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6115-dpu.yaml93
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6115-mdss.yaml203
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6125-mdss.yaml223
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6150-dpu.yaml108
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6150-mdss.yaml255
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6350-mdss.yaml225
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm6375-mdss.yaml218
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm7150-dpu.yaml143
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm7150-mdss.yaml464
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8150-dpu.yaml94
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml347
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8250-mdss.yaml350
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8350-mdss.yaml244
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8450-mdss.yaml364
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8550-mdss.yaml353
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8650-dpu.yaml137
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8650-mdss.yaml341
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,sm8750-mdss.yaml474
-rw-r--r--Documentation/devicetree/bindings/display/msm/qcom,x1e80100-mdss.yaml255
-rw-r--r--Documentation/devicetree/bindings/display/multi-inno,mi0283qt.txt27
-rw-r--r--Documentation/devicetree/bindings/display/panel/abt,y030xx067a.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/panel/advantech,idk-1110wr.yaml84
-rw-r--r--Documentation/devicetree/bindings/display/panel/advantech,idk-2121wr.yaml112
-rw-r--r--Documentation/devicetree/bindings/display/panel/anbernic,rg35xx-plus-panel.yaml67
-rw-r--r--Documentation/devicetree/bindings/display/panel/apple,summit.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/panel/arm,rtsm-display.yaml27
-rw-r--r--Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml51
-rw-r--r--Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.yaml33
-rw-r--r--Documentation/devicetree/bindings/display/panel/asus,z00t-tm5p5-nt35596.yaml59
-rw-r--r--Documentation/devicetree/bindings/display/panel/auo,a030jtn01.yaml60
-rw-r--r--Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.yaml31
-rw-r--r--Documentation/devicetree/bindings/display/panel/boe,bf060y8m-aj0.yaml83
-rw-r--r--Documentation/devicetree/bindings/display/panel/boe,himax8279d.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/panel/boe,td4320.yaml65
-rw-r--r--Documentation/devicetree/bindings/display/panel/boe,th101mb31ig002-28a.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/panel/boe,tv101wum-ll2.yaml63
-rw-r--r--Documentation/devicetree/bindings/display/panel/boe,tv101wum-nl6.yaml93
-rw-r--r--Documentation/devicetree/bindings/display/panel/display-timing.txt1
-rw-r--r--Documentation/devicetree/bindings/display/panel/display-timings.yaml76
-rw-r--r--Documentation/devicetree/bindings/display/panel/dlc,dlc0700yzg-1.yaml31
-rw-r--r--Documentation/devicetree/bindings/display/panel/ebbg,ft8719.yaml74
-rw-r--r--Documentation/devicetree/bindings/display/panel/elida,kd35t133.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/panel/fascontek,fs035vg158.yaml59
-rw-r--r--Documentation/devicetree/bindings/display/panel/feixin,k101-im2ba02.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/panel/feiyang,fy07024di26a30d.yaml65
-rw-r--r--Documentation/devicetree/bindings/display/panel/focaltech,gpt3.yaml56
-rw-r--r--Documentation/devicetree/bindings/display/panel/himax,hx8279.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/panel/himax,hx83102.yaml83
-rw-r--r--Documentation/devicetree/bindings/display/panel/himax,hx83112a.yaml76
-rw-r--r--Documentation/devicetree/bindings/display/panel/himax,hx83112b.yaml73
-rw-r--r--Documentation/devicetree/bindings/display/panel/himax,hx8394.yaml94
-rw-r--r--Documentation/devicetree/bindings/display/panel/hydis,hv101hd1.yaml60
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,il79900a.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,ili9322.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,ili9341.yaml100
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,ili9805.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,ili9806e.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/panel/ilitek,ili9881c.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.yaml50
-rw-r--r--Documentation/devicetree/bindings/display/panel/innolux,ej030na.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/panel/innolux,p097pfg.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/panel/jadard,jd9365da-h3.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/panel/jdi,lpm102a188a.yaml96
-rw-r--r--Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.yaml74
-rw-r--r--Documentation/devicetree/bindings/display/panel/kingdisplay,kd035g6-54nt.yaml65
-rw-r--r--Documentation/devicetree/bindings/display/panel/leadtek,ltk035c5444t.yaml60
-rw-r--r--Documentation/devicetree/bindings/display/panel/leadtek,ltk050h3146w.yaml56
-rw-r--r--Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml56
-rw-r--r--Documentation/devicetree/bindings/display/panel/lg,ld070wx3-sl01.yaml60
-rw-r--r--Documentation/devicetree/bindings/display/panel/lg,lg4573.yaml46
-rw-r--r--Documentation/devicetree/bindings/display/panel/lg,sw43408.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.yaml62
-rw-r--r--Documentation/devicetree/bindings/display/panel/logicpd,type28.yaml42
-rw-r--r--Documentation/devicetree/bindings/display/panel/mantix,mlaf057we51-x.yaml76
-rw-r--r--Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.yaml92
-rw-r--r--Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.yaml89
-rw-r--r--Documentation/devicetree/bindings/display/panel/nec,nl8048hl11.yaml65
-rw-r--r--Documentation/devicetree/bindings/display/panel/newvision,nv3051d.yaml64
-rw-r--r--Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml62
-rw-r--r--Documentation/devicetree/bindings/display/panel/novatek,nt35950.yaml109
-rw-r--r--Documentation/devicetree/bindings/display/panel/novatek,nt36523.yaml108
-rw-r--r--Documentation/devicetree/bindings/display/panel/novatek,nt36672a.yaml90
-rw-r--r--Documentation/devicetree/bindings/display/panel/novatek,nt36672e.yaml66
-rw-r--r--Documentation/devicetree/bindings/display/panel/novatek,nt37801.yaml69
-rw-r--r--Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.yaml72
-rw-r--r--Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.yaml52
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-common-dual.yaml47
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-common.yaml167
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-dpi.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml86
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-edp-legacy.yaml117
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-edp.yaml188
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-lvds.yaml77
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-mipi-dbi-spi.yaml171
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml96
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml106
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-simple.yaml385
-rw-r--r--Documentation/devicetree/bindings/display/panel/panel-timing.yaml213
-rw-r--r--Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.yaml31
-rw-r--r--Documentation/devicetree/bindings/display/panel/powertip,hx8238a.yaml29
-rw-r--r--Documentation/devicetree/bindings/display/panel/powertip,st7272.yaml29
-rw-r--r--Documentation/devicetree/bindings/display/panel/raspberrypi,7inch-touchscreen.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/panel/raydium,rm67191.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/panel/raydium,rm67200.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/panel/raydium,rm68200.yaml56
-rw-r--r--Documentation/devicetree/bindings/display/panel/raydium,rm692e5.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/panel/raydium,rm69380.yaml90
-rw-r--r--Documentation/devicetree/bindings/display/panel/renesas,r61307.yaml94
-rw-r--r--Documentation/devicetree/bindings/display/panel/renesas,r69328.yaml73
-rw-r--r--Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml78
-rw-r--r--Documentation/devicetree/bindings/display/panel/ronbo,rb070d30.yaml47
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,amoled-mipi-dsi.yaml77
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,ams495qa01.yaml60
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,ams581vf01.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,ams639rq08.yaml80
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,atna33xc20.yaml116
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,ld9040.yaml107
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,lms380kf01.yaml99
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,lms397kf04.yaml90
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6d16d0.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6d27a1.yaml99
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6d7aa0.yaml71
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e3fc2x01.yaml81
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e3ha8.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.yaml69
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e88a0-ams427ap24.yaml65
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e88a0-ams452ef01.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml97
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,s6e8aa5x01-ams561ra01.yaml55
-rw-r--r--Documentation/devicetree/bindings/display/panel/samsung,sofef00.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/panel/seiko,43wvf1g.yaml52
-rw-r--r--Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.yaml83
-rw-r--r--Documentation/devicetree/bindings/display/panel/sharp,lq079l1sx01.yaml99
-rw-r--r--Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml94
-rw-r--r--Documentation/devicetree/bindings/display/panel/sharp,lq150x1lg11.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/panel/sharp,ls037v7dw01.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/panel/sharp,ls043t1le01.yaml53
-rw-r--r--Documentation/devicetree/bindings/display/panel/sharp,ls060t1sx01.yaml58
-rw-r--r--Documentation/devicetree/bindings/display/panel/sitronix,st7701.yaml144
-rw-r--r--Documentation/devicetree/bindings/display/panel/sitronix,st7789v.yaml78
-rw-r--r--Documentation/devicetree/bindings/display/panel/sony,acx424akp.yaml59
-rw-r--r--Documentation/devicetree/bindings/display/panel/sony,acx565akm.yaml57
-rw-r--r--Documentation/devicetree/bindings/display/panel/sony,td4353-jdi.yaml85
-rw-r--r--Documentation/devicetree/bindings/display/panel/sony,tulip-truly-nt35521.yaml73
-rw-r--r--Documentation/devicetree/bindings/display/panel/startek,kd070fhfid015.yaml69
-rw-r--r--Documentation/devicetree/bindings/display/panel/startek,startek-kd050c.yaml33
-rw-r--r--Documentation/devicetree/bindings/display/panel/synaptics,r63353.yaml63
-rw-r--r--Documentation/devicetree/bindings/display/panel/synaptics,td4300-panel.yaml89
-rw-r--r--Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.yaml33
-rw-r--r--Documentation/devicetree/bindings/display/panel/ti,nspire.yaml36
-rw-r--r--Documentation/devicetree/bindings/display/panel/tpo,td.yaml67
-rw-r--r--Documentation/devicetree/bindings/display/panel/tpo,tpg110.yaml104
-rw-r--r--Documentation/devicetree/bindings/display/panel/truly,nt35597-2K-display.yaml97
-rw-r--r--Documentation/devicetree/bindings/display/panel/visionox,g2647fb105.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml59
-rw-r--r--Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml70
-rw-r--r--Documentation/devicetree/bindings/display/panel/visionox,rm692e5.yaml77
-rw-r--r--Documentation/devicetree/bindings/display/panel/visionox,vtdr6130.yaml63
-rw-r--r--Documentation/devicetree/bindings/display/panel/xinpeng,xpp055c272.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/renesas,cmm.yaml67
-rw-r--r--Documentation/devicetree/bindings/display/renesas,du.yaml950
-rw-r--r--Documentation/devicetree/bindings/display/renesas,rzg2l-du.yaml176
-rw-r--r--Documentation/devicetree/bindings/display/renesas,shmobile-lcdc.yaml130
-rw-r--r--Documentation/devicetree/bindings/display/repaper.txt52
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,analogix-dp.yaml124
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,dw-dp.yaml149
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml184
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,dw-mipi-dsi.yaml168
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,inno-hdmi.yaml146
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,lvds.yaml170
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.yaml129
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,rk3399-cdn-dp.yaml170
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,rk3588-dw-hdmi-qp.yaml200
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip,rk3588-mipi-dsi2.yaml121
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml42
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml126
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/rockchip-vop2.yaml315
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos-hdmi-ddc.yaml41
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos-hdmi.yaml226
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos-mixer.yaml142
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos5-dp.yaml163
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos5433-decon.yaml145
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos5433-mic.yaml93
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,exynos7-decon.yaml142
-rw-r--r--Documentation/devicetree/bindings/display/samsung/samsung,fimd.yaml196
-rw-r--r--Documentation/devicetree/bindings/display/sharp,ls010b7dh04.yaml92
-rw-r--r--Documentation/devicetree/bindings/display/simple-framebuffer.yaml212
-rw-r--r--Documentation/devicetree/bindings/display/sitronix,st7567.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/sitronix,st7571.yaml78
-rw-r--r--Documentation/devicetree/bindings/display/sitronix,st7586.yaml61
-rw-r--r--Documentation/devicetree/bindings/display/sitronix,st7735r.yaml72
-rw-r--r--Documentation/devicetree/bindings/display/sm501fb.txt (renamed from Documentation/devicetree/bindings/fb/sm501fb.txt)2
-rw-r--r--Documentation/devicetree/bindings/display/snps,arcpgu.txt35
-rw-r--r--Documentation/devicetree/bindings/display/solomon,ssd-common.yaml42
-rw-r--r--Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml269
-rw-r--r--Documentation/devicetree/bindings/display/solomon,ssd132x.yaml89
-rw-r--r--Documentation/devicetree/bindings/display/solomon,ssd133x.yaml45
-rw-r--r--Documentation/devicetree/bindings/display/sprd/sprd,display-subsystem.yaml65
-rw-r--r--Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dpu.yaml77
-rw-r--r--Documentation/devicetree/bindings/display/sprd/sprd,sharkl3-dsi-host.yaml88
-rw-r--r--Documentation/devicetree/bindings/display/ssd1289fb.txt (renamed from Documentation/devicetree/bindings/video/ssd1289fb.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/st,stih4xx.txt241
-rw-r--r--Documentation/devicetree/bindings/display/st,stm32-dsi.yaml136
-rw-r--r--Documentation/devicetree/bindings/display/st,stm32-ltdc.yaml128
-rw-r--r--Documentation/devicetree/bindings/display/st,stm32mp25-lvds.yaml130
-rw-r--r--Documentation/devicetree/bindings/display/ste,mcde.yaml168
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra114-mipi.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra114-tsec.yaml68
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-dpaux.yaml151
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-sor.yaml197
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra124-vic.yaml72
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-dc.yaml85
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-display.yaml308
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra186-dsi-padctl.yaml45
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-csi.yaml138
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dc.yaml182
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-dsi.yaml158
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-epp.yaml75
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr2d.yaml73
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-gr3d.yaml213
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-hdmi.yaml125
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml441
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-isp.yaml74
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-mpe.yaml78
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-tvo.yaml57
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-vi.yaml218
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-vip.yaml41
-rw-r--r--Documentation/devicetree/bindings/display/tegra/nvidia,tegra210-csi.yaml55
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,am625-oldi.yaml79
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml349
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt (renamed from Documentation/devicetree/bindings/video/ti,dra7-dss.txt)7
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,j721e-dss.yaml208
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,k2g-dss.yaml105
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt (renamed from Documentation/devicetree/bindings/video/ti,omap-dss.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt (renamed from Documentation/devicetree/bindings/video/ti,omap2-dss.txt)6
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt (renamed from Documentation/devicetree/bindings/video/ti,omap3-dss.txt)6
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt (renamed from Documentation/devicetree/bindings/video/ti,omap4-dss.txt)6
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt (renamed from Documentation/devicetree/bindings/video/ti,omap5-dss.txt)6
-rw-r--r--Documentation/devicetree/bindings/display/ti/ti,tpd12s015.txt (renamed from Documentation/devicetree/bindings/video/ti,tpd12s015.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/tilcdc/panel.txt (renamed from Documentation/devicetree/bindings/drm/tilcdc/panel.txt)2
-rw-r--r--Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt82
-rw-r--r--Documentation/devicetree/bindings/display/via,vt8500-fb.txt (renamed from Documentation/devicetree/bindings/video/via,vt8500-fb.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/wm,prizm-ge-rops.txt (renamed from Documentation/devicetree/bindings/video/wm,prizm-ge-rops.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/wm,wm8505-fb.txt (renamed from Documentation/devicetree/bindings/video/wm,wm8505-fb.txt)0
-rw-r--r--Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml242
-rw-r--r--Documentation/devicetree/bindings/display/xylon,logicvc-display.yaml301
-rw-r--r--Documentation/devicetree/bindings/dma/adi,axi-dmac.yaml129
-rw-r--r--Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml57
-rw-r--r--Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml102
-rw-r--r--Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml62
-rw-r--r--Documentation/devicetree/bindings/dma/altr,msgdma.yaml63
-rw-r--r--Documentation/devicetree/bindings/dma/apm,xgene-storm-dma.yaml59
-rw-r--r--Documentation/devicetree/bindings/dma/apm-xgene-dma.txt47
-rw-r--r--Documentation/devicetree/bindings/dma/apple,admac.yaml96
-rw-r--r--Documentation/devicetree/bindings/dma/arm,dma-350.yaml44
-rw-r--r--Documentation/devicetree/bindings/dma/arm,pl330.yaml92
-rw-r--r--Documentation/devicetree/bindings/dma/arm-pl08x.yaml140
-rw-r--r--Documentation/devicetree/bindings/dma/arm-pl330.txt44
-rw-r--r--Documentation/devicetree/bindings/dma/atmel,at91sam9g45-dma.yaml68
-rw-r--r--Documentation/devicetree/bindings/dma/atmel,sama5d4-dma.yaml82
-rw-r--r--Documentation/devicetree/bindings/dma/atmel-dma.txt42
-rw-r--r--Documentation/devicetree/bindings/dma/atmel-xdma.txt54
-rw-r--r--Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt57
-rw-r--r--Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.yaml102
-rw-r--r--Documentation/devicetree/bindings/dma/brcm,iproc-sba.yaml41
-rw-r--r--Documentation/devicetree/bindings/dma/cirrus,ep9301-dma-m2m.yaml84
-rw-r--r--Documentation/devicetree/bindings/dma/cirrus,ep9301-dma-m2p.yaml144
-rw-r--r--Documentation/devicetree/bindings/dma/dma-common.yaml52
-rw-r--r--Documentation/devicetree/bindings/dma/dma-controller.yaml22
-rw-r--r--Documentation/devicetree/bindings/dma/dma-router.yaml43
-rw-r--r--Documentation/devicetree/bindings/dma/dma.txt82
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,edma.yaml344
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,elo-dma.yaml137
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,elo3-dma.yaml125
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,eloplus-dma.yaml132
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,imx-dma.yaml70
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,imx-sdma.yaml151
-rw-r--r--Documentation/devicetree/bindings/dma/fsl,mxs-dma.yaml134
-rw-r--r--Documentation/devicetree/bindings/dma/fsl-edma.txt76
-rw-r--r--Documentation/devicetree/bindings/dma/fsl-imx-dma.txt48
-rw-r--r--Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt85
-rw-r--r--Documentation/devicetree/bindings/dma/fsl-mxs-dma.txt60
-rw-r--r--Documentation/devicetree/bindings/dma/fsl-qdma.yaml135
-rw-r--r--Documentation/devicetree/bindings/dma/ingenic,dma.yaml99
-rw-r--r--Documentation/devicetree/bindings/dma/intel,ldma.yaml116
-rw-r--r--Documentation/devicetree/bindings/dma/jz4780-dma.txt56
-rw-r--r--Documentation/devicetree/bindings/dma/k3dma.txt5
-rw-r--r--Documentation/devicetree/bindings/dma/loongson,ls1b-apbdma.yaml65
-rw-r--r--Documentation/devicetree/bindings/dma/loongson,ls2x-apbdma.yaml62
-rw-r--r--Documentation/devicetree/bindings/dma/marvell,mmp-dma.yaml72
-rw-r--r--Documentation/devicetree/bindings/dma/marvell,orion-xor.yaml84
-rw-r--r--Documentation/devicetree/bindings/dma/marvell,xor-v2.yaml61
-rw-r--r--Documentation/devicetree/bindings/dma/mediatek,mt7622-hsdma.yaml63
-rw-r--r--Documentation/devicetree/bindings/dma/mediatek,uart-dma.yaml124
-rw-r--r--Documentation/devicetree/bindings/dma/milbeaut-m10v-hdmac.txt32
-rw-r--r--Documentation/devicetree/bindings/dma/milbeaut-m10v-xdmac.txt24
-rw-r--r--Documentation/devicetree/bindings/dma/mmp-dma.txt77
-rw-r--r--Documentation/devicetree/bindings/dma/moxa,moxart-dma.txt4
-rw-r--r--Documentation/devicetree/bindings/dma/mv-xor.txt40
-rw-r--r--Documentation/devicetree/bindings/dma/nbpfaxi.txt61
-rw-r--r--Documentation/devicetree/bindings/dma/nvidia,tegra186-gpc-dma.yaml118
-rw-r--r--Documentation/devicetree/bindings/dma/nvidia,tegra20-apbdma.yaml100
-rw-r--r--Documentation/devicetree/bindings/dma/nvidia,tegra210-adma.yaml158
-rw-r--r--Documentation/devicetree/bindings/dma/nxp,lpc3220-dmamux.yaml49
-rw-r--r--Documentation/devicetree/bindings/dma/owl-dma.yaml80
-rw-r--r--Documentation/devicetree/bindings/dma/qcom,adm.yaml99
-rw-r--r--Documentation/devicetree/bindings/dma/qcom,bam-dma.yaml121
-rw-r--r--Documentation/devicetree/bindings/dma/qcom,gpi.yaml121
-rw-r--r--Documentation/devicetree/bindings/dma/qcom_adm.txt62
-rw-r--r--Documentation/devicetree/bindings/dma/qcom_bam_dma.txt44
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,nbpfaxi.txt69
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt95
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml175
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml234
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,rzn1-dmamux.yaml51
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt37
-rw-r--r--Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml104
-rw-r--r--Documentation/devicetree/bindings/dma/shdma.txt84
-rw-r--r--Documentation/devicetree/bindings/dma/sifive,fu540-c000-pdma.yaml80
-rw-r--r--Documentation/devicetree/bindings/dma/sirfsoc-dma.txt43
-rw-r--r--Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml184
-rw-r--r--Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.yaml160
-rw-r--r--Documentation/devicetree/bindings/dma/snps-dma.txt63
-rw-r--r--Documentation/devicetree/bindings/dma/socionext,uniphier-mio-dmac.yaml63
-rw-r--r--Documentation/devicetree/bindings/dma/socionext,uniphier-xdmac.yaml62
-rw-r--r--Documentation/devicetree/bindings/dma/sophgo,cv1800b-dmamux.yaml51
-rw-r--r--Documentation/devicetree/bindings/dma/spacemit,k1-pdma.yaml68
-rw-r--r--Documentation/devicetree/bindings/dma/sprd,sc9860-dma.yaml92
-rw-r--r--Documentation/devicetree/bindings/dma/st_fdma.txt86
-rw-r--r--Documentation/devicetree/bindings/dma/ste-coh901318.txt32
-rw-r--r--Documentation/devicetree/bindings/dma/ste-dma40.txt139
-rw-r--r--Documentation/devicetree/bindings/dma/stericsson,dma40.yaml178
-rw-r--r--Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml119
-rw-r--r--Documentation/devicetree/bindings/dma/stm32/st,stm32-dma3.yaml141
-rw-r--r--Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml67
-rw-r--r--Documentation/devicetree/bindings/dma/stm32/st,stm32-mdma.yaml106
-rw-r--r--Documentation/devicetree/bindings/dma/sun6i-dma.txt45
-rw-r--r--Documentation/devicetree/bindings/dma/tegra20-apbdma.txt44
-rw-r--r--Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt68
-rw-r--r--Documentation/devicetree/bindings/dma/ti-edma.txt207
-rw-r--r--Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml266
-rw-r--r--Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml195
-rw-r--r--Documentation/devicetree/bindings/dma/ti/k3-udma.yaml193
-rw-r--r--Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt124
-rw-r--r--Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt75
-rw-r--r--Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml88
-rw-r--r--Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml74
-rw-r--r--Documentation/devicetree/bindings/dpll/dpll-device.yaml76
-rw-r--r--Documentation/devicetree/bindings/dpll/dpll-pin.yaml45
-rw-r--r--Documentation/devicetree/bindings/dpll/microchip,zl30731.yaml115
-rw-r--r--Documentation/devicetree/bindings/drm/atmel/hlcdc-dc.txt53
-rw-r--r--Documentation/devicetree/bindings/drm/bridge/dw_hdmi.txt50
-rw-r--r--Documentation/devicetree/bindings/drm/i2c/tda998x.txt29
-rw-r--r--Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt83
-rw-r--r--Documentation/devicetree/bindings/drm/imx/hdmi.txt58
-rw-r--r--Documentation/devicetree/bindings/drm/imx/ldb.txt146
-rw-r--r--Documentation/devicetree/bindings/drm/msm/gpu.txt52
-rw-r--r--Documentation/devicetree/bindings/drm/msm/hdmi.txt48
-rw-r--r--Documentation/devicetree/bindings/drm/msm/mdp.txt48
-rw-r--r--Documentation/devicetree/bindings/drm/tilcdc/slave.txt18
-rw-r--r--Documentation/devicetree/bindings/drm/tilcdc/tfp410.txt21
-rw-r--r--Documentation/devicetree/bindings/drm/tilcdc/tilcdc.txt29
-rw-r--r--Documentation/devicetree/bindings/dsp/fsl,dsp.yaml249
-rw-r--r--Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml93
-rw-r--r--Documentation/devicetree/bindings/dsp/mediatek,mt8195-dsp.yaml105
-rw-r--r--Documentation/devicetree/bindings/dts-coding-style.rst213
-rw-r--r--Documentation/devicetree/bindings/dvfs/performance-domain.yaml79
-rw-r--r--Documentation/devicetree/bindings/edac/altr,socfpga-ecc-manager.yaml324
-rw-r--r--Documentation/devicetree/bindings/edac/amazon,al-mc-edac.yaml66
-rw-r--r--Documentation/devicetree/bindings/edac/apm,xgene-edac.yaml202
-rw-r--r--Documentation/devicetree/bindings/edac/aspeed,ast2400-sdram-edac.yaml48
-rw-r--r--Documentation/devicetree/bindings/edac/dmc-520.yaml61
-rw-r--r--Documentation/devicetree/bindings/eeprom.txt28
-rw-r--r--Documentation/devicetree/bindings/eeprom/at24.yaml232
-rw-r--r--Documentation/devicetree/bindings/eeprom/at25.yaml158
-rw-r--r--Documentation/devicetree/bindings/eeprom/microchip,93lc46b.yaml70
-rw-r--r--Documentation/devicetree/bindings/eeprom/st,m24lr.yaml52
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/acer,aspire1-ec.yaml60
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/google,cros-ec.yaml326
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/gw,gsc.yaml193
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/huawei,gaokun3-ec.yaml124
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/kontron,sl28cpld.yaml158
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/lenovo,thinkpad-t14s-ec.yaml50
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/lenovo,yoga-c630-ec.yaml83
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/microsoft,surface-sam.yaml47
-rw-r--r--Documentation/devicetree/bindings/embedded-controller/traverse,ten64-controller.yaml40
-rw-r--r--Documentation/devicetree/bindings/example-schema.yaml279
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-max3355.txt21
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-palmas.txt5
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-ptn5150.yaml73
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt25
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-sm5502.txt23
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-usb-gpio.txt18
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml55
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-usbc-tusb320.yaml43
-rw-r--r--Documentation/devicetree/bindings/extcon/fcs,fsa880.yaml52
-rw-r--r--Documentation/devicetree/bindings/extcon/linux,extcon-usb-gpio.yaml43
-rw-r--r--Documentation/devicetree/bindings/extcon/maxim,max14526.yaml80
-rw-r--r--Documentation/devicetree/bindings/extcon/maxim,max77843.yaml41
-rw-r--r--Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml66
-rw-r--r--Documentation/devicetree/bindings/extcon/richtek,rt8973a-muic.yaml49
-rw-r--r--Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml57
-rw-r--r--Documentation/devicetree/bindings/extcon/wlf,arizona.yaml126
-rw-r--r--Documentation/devicetree/bindings/fb/mxsfb.txt49
-rw-r--r--Documentation/devicetree/bindings/firmware/amlogic,meson-gxbb-sm.yaml39
-rw-r--r--Documentation/devicetree/bindings/firmware/arm,scmi.yaml589
-rw-r--r--Documentation/devicetree/bindings/firmware/arm,scpi.yaml249
-rw-r--r--Documentation/devicetree/bindings/firmware/brcm,kona-smc.yaml39
-rw-r--r--Documentation/devicetree/bindings/firmware/coreboot.txt33
-rw-r--r--Documentation/devicetree/bindings/firmware/cznic,turris-mox-rwtm.txt19
-rw-r--r--Documentation/devicetree/bindings/firmware/cznic,turris-omnia-mcu.yaml86
-rw-r--r--Documentation/devicetree/bindings/firmware/fsl,scu.yaml227
-rw-r--r--Documentation/devicetree/bindings/firmware/google,gs101-acpm-ipc.yaml96
-rw-r--r--Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml94
-rw-r--r--Documentation/devicetree/bindings/firmware/intel,stratix10-svc.yaml108
-rw-r--r--Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml216
-rw-r--r--Documentation/devicetree/bindings/firmware/nvidia,tegra210-bpmp.txt35
-rw-r--r--Documentation/devicetree/bindings/firmware/nxp,imx95-scmi-pinctrl.yaml53
-rw-r--r--Documentation/devicetree/bindings/firmware/nxp,imx95-scmi.yaml72
-rw-r--r--Documentation/devicetree/bindings/firmware/qcom,scm.yaml245
-rw-r--r--Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml53
-rw-r--r--Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml60
-rw-r--r--Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml177
-rw-r--r--Documentation/devicetree/bindings/fpga/altera-pr-ip.txt12
-rw-r--r--Documentation/devicetree/bindings/fpga/altera-socfpga-a10-fpga-mgr.txt19
-rw-r--r--Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt2
-rw-r--r--Documentation/devicetree/bindings/fpga/altr,fpga-passive-serial.yaml74
-rw-r--r--Documentation/devicetree/bindings/fpga/altr,freeze-bridge-controller.yaml41
-rw-r--r--Documentation/devicetree/bindings/fpga/altr,socfpga-fpga2sdram-bridge.yaml33
-rw-r--r--Documentation/devicetree/bindings/fpga/altr,socfpga-hps2fpga-bridge.yaml49
-rw-r--r--Documentation/devicetree/bindings/fpga/fpga-bridge.yaml30
-rw-r--r--Documentation/devicetree/bindings/fpga/fpga-region.yaml354
-rw-r--r--Documentation/devicetree/bindings/fpga/intel,stratix10-soc-fpga-mgr.yaml36
-rw-r--r--Documentation/devicetree/bindings/fpga/lattice,ice40-fpga-mgr.yaml59
-rw-r--r--Documentation/devicetree/bindings/fpga/lattice,sysconfig.yaml81
-rw-r--r--Documentation/devicetree/bindings/fpga/lattice-machxo2-spi.txt29
-rw-r--r--Documentation/devicetree/bindings/fpga/microchip,mpf-spi-fpga-mgr.yaml45
-rw-r--r--Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.yaml52
-rw-r--r--Documentation/devicetree/bindings/fpga/xlnx,fpga-selectmap.yaml86
-rw-r--r--Documentation/devicetree/bindings/fpga/xlnx,fpga-slave-serial.yaml80
-rw-r--r--Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml67
-rw-r--r--Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml33
-rw-r--r--Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml36
-rw-r--r--Documentation/devicetree/bindings/fsi/aspeed,ast2400-cf-fsi-master.yaml81
-rw-r--r--Documentation/devicetree/bindings/fsi/aspeed,ast2600-fsi-master.yaml121
-rw-r--r--Documentation/devicetree/bindings/fsi/fsi-controller.yaml66
-rw-r--r--Documentation/devicetree/bindings/fsi/fsi-master-gpio.yaml63
-rw-r--r--Documentation/devicetree/bindings/fsi/fsi.txt156
-rw-r--r--Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml66
-rw-r--r--Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml44
-rw-r--r--Documentation/devicetree/bindings/fsi/ibm,p9-fsi-controller.yaml45
-rw-r--r--Documentation/devicetree/bindings/fsi/ibm,p9-occ.yaml40
-rw-r--r--Documentation/devicetree/bindings/fsi/ibm,p9-sbefifo.yaml46
-rw-r--r--Documentation/devicetree/bindings/fsi/ibm,p9-scom.yaml38
-rw-r--r--Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt40
-rw-r--r--Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml88
-rw-r--r--Documentation/devicetree/bindings/gnss/brcm,bcm4751.yaml70
-rw-r--r--Documentation/devicetree/bindings/gnss/gnss-common.yaml49
-rw-r--r--Documentation/devicetree/bindings/gnss/mediatek.yaml60
-rw-r--r--Documentation/devicetree/bindings/gnss/sirfstar.yaml77
-rw-r--r--Documentation/devicetree/bindings/gnss/u-blox,neo-6m.yaml73
-rw-r--r--Documentation/devicetree/bindings/goldfish/audio.txt17
-rw-r--r--Documentation/devicetree/bindings/goldfish/battery.txt17
-rw-r--r--Documentation/devicetree/bindings/goldfish/events.txt17
-rw-r--r--Documentation/devicetree/bindings/goldfish/pipe.txt17
-rw-r--r--Documentation/devicetree/bindings/goldfish/tty.txt17
-rw-r--r--Documentation/devicetree/bindings/gpio/8xxx_gpio.txt74
-rw-r--r--Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt36
-rw-r--r--Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.yaml63
-rw-r--r--Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml51
-rw-r--r--Documentation/devicetree/bindings/gpio/airoha,en7523-gpio.yaml66
-rw-r--r--Documentation/devicetree/bindings/gpio/altr-pio-1.0.yaml75
-rw-r--r--Documentation/devicetree/bindings/gpio/apm,xgene-gpio-sb.yaml94
-rw-r--r--Documentation/devicetree/bindings/gpio/apple,smc-gpio.yaml29
-rw-r--r--Documentation/devicetree/bindings/gpio/aspeed,ast2400-gpio.yaml169
-rw-r--r--Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml87
-rw-r--r--Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml81
-rw-r--r--Documentation/devicetree/bindings/gpio/blaize,blzp1600-gpio.yaml77
-rw-r--r--Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml72
-rw-r--r--Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml111
-rw-r--r--Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt52
-rw-r--r--Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml100
-rw-r--r--Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml69
-rw-r--r--Documentation/devicetree/bindings/gpio/cavium,octeon-3860-gpio.yaml62
-rw-r--r--Documentation/devicetree/bindings/gpio/cavium-octeon-gpio.txt49
-rw-r--r--Documentation/devicetree/bindings/gpio/cdns,gpio.yaml84
-rw-r--r--Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt17
-rw-r--r--Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.yaml49
-rw-r--r--Documentation/devicetree/bindings/gpio/delta,tn48m-gpio.yaml39
-rw-r--r--Documentation/devicetree/bindings/gpio/exar,xra1403.yaml75
-rw-r--r--Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml84
-rw-r--r--Documentation/devicetree/bindings/gpio/faraday,ftgpio010.yaml65
-rw-r--r--Documentation/devicetree/bindings/gpio/fsl,imx8qxp-sc-gpio.yaml39
-rw-r--r--Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml95
-rw-r--r--Documentation/devicetree/bindings/gpio/fsl-imx-gpio.txt32
-rw-r--r--Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml114
-rw-r--r--Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt20
-rw-r--r--Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml50
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-74x164.txt22
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt30
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-adnp.txt1
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-altera.txt43
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-atlas7.txt50
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-clps711x.txt28
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-consumer-common.yaml64
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-davinci.txt62
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-davinci.yaml187
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-delay.yaml79
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt39
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-ep9301.yaml157
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-exar.txt5
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-fan.txt40
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-latch.yaml94
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-lp3943.txt37
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-max732x.txt59
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt85
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mm-lantiq.txt38
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mmio.yaml162
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-msm.txt26
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mvebu.txt53
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml156
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mxs.txt88
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-mxs.yaml206
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-nmk.txt31
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-omap.txt39
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-palmas.txt27
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-pca953x.txt39
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml231
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt71
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-poweroff.txt36
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-rda.yaml50
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-restart.txt54
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-samsung.txt41
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-stericsson-coh901.txt7
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-stmpe.txt18
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt42
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-stp-xway.yaml99
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-sx150x.txt40
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-thunderx.txt27
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-twl4030.txt29
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt45
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-tz1090.txt88
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-vf610.txt55
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-vf610.yaml135
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-virtio.yaml59
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt32
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-xgene.txt22
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-xilinx.txt48
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-zevio.txt16
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-zynq.txt26
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-zynq.yaml116
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio.txt254
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio_atmel.txt25
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio_lpc32xx.txt43
-rw-r--r--Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml56
-rw-r--r--Documentation/devicetree/bindings/gpio/idt,32434-gpio.yaml67
-rw-r--r--Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml73
-rw-r--r--Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml54
-rw-r--r--Documentation/devicetree/bindings/gpio/lacie,netxbig-gpio-ext.yaml60
-rw-r--r--Documentation/devicetree/bindings/gpio/lantiq,gpio-mm-lantiq.yaml54
-rw-r--r--Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml168
-rw-r--r--Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml43
-rw-r--r--Documentation/devicetree/bindings/gpio/maxim,max31910.yaml104
-rw-r--r--Documentation/devicetree/bindings/gpio/maxim,max7360-gpio.yaml83
-rw-r--r--Documentation/devicetree/bindings/gpio/maxim,max77759-gpio.yaml44
-rw-r--r--Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.yaml72
-rw-r--r--Documentation/devicetree/bindings/gpio/microchip,mpfs-gpio.yaml99
-rw-r--r--Documentation/devicetree/bindings/gpio/microchip,pic32mzda-gpio.yaml71
-rw-r--r--Documentation/devicetree/bindings/gpio/moxa,moxart-gpio.txt19
-rw-r--r--Documentation/devicetree/bindings/gpio/mrvl-gpio.txt69
-rw-r--r--Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml172
-rw-r--r--Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml61
-rw-r--r--Documentation/devicetree/bindings/gpio/nuvoton,sgpio.yaml87
-rw-r--r--Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml219
-rw-r--r--Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt40
-rw-r--r--Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml110
-rw-r--r--Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.yaml78
-rw-r--r--Documentation/devicetree/bindings/gpio/nxp,lpc3220-gpio.yaml50
-rw-r--r--Documentation/devicetree/bindings/gpio/nxp,pcf8575.yaml144
-rw-r--r--Documentation/devicetree/bindings/gpio/pisosr-gpio.yaml67
-rw-r--r--Documentation/devicetree/bindings/gpio/pl061-gpio.txt10
-rw-r--r--Documentation/devicetree/bindings/gpio/pl061-gpio.yaml69
-rw-r--r--Documentation/devicetree/bindings/gpio/qca,ar7100-gpio.yaml60
-rw-r--r--Documentation/devicetree/bindings/gpio/qcom,wcd934x-gpio.yaml47
-rw-r--r--Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml108
-rw-r--r--Documentation/devicetree/bindings/gpio/realtek,rtd-gpio.yaml69
-rw-r--r--Documentation/devicetree/bindings/gpio/renesas,em-gio.yaml70
-rw-r--r--Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt63
-rw-r--r--Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml153
-rw-r--r--Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml99
-rw-r--r--Documentation/devicetree/bindings/gpio/sifive,gpio.yaml93
-rw-r--r--Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml145
-rw-r--r--Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt60
-rw-r--r--Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml101
-rw-r--r--Documentation/devicetree/bindings/gpio/spacemit,k1-gpio.yaml96
-rw-r--r--Documentation/devicetree/bindings/gpio/spear_spics.txt50
-rw-r--r--Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml124
-rw-r--r--Documentation/devicetree/bindings/gpio/sprd,gpio.yaml75
-rw-r--r--Documentation/devicetree/bindings/gpio/st,nomadik-gpio.yaml96
-rw-r--r--Documentation/devicetree/bindings/gpio/st,spear-spics-gpio.yaml82
-rw-r--r--Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml57
-rw-r--r--Documentation/devicetree/bindings/gpio/ti,keystone-dsp-gpio.yaml65
-rw-r--r--Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml108
-rw-r--r--Documentation/devicetree/bindings/gpio/ti,twl4030-gpio.yaml61
-rw-r--r--Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml69
-rw-r--r--Documentation/devicetree/bindings/gpio/trivial-gpio.yaml112
-rw-r--r--Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml63
-rw-r--r--Documentation/devicetree/bindings/gpio/xlnx,gpio-xilinx.yaml155
-rw-r--r--Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml46
-rw-r--r--Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml71
-rw-r--r--Documentation/devicetree/bindings/gpu/apple,agx.yaml100
-rw-r--r--Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml335
-rw-r--r--Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml207
-rw-r--r--Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml185
-rw-r--r--Documentation/devicetree/bindings/gpu/arm,mali-valhall-csf.yaml185
-rw-r--r--Documentation/devicetree/bindings/gpu/aspeed,ast2400-gfx.yaml63
-rw-r--r--Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.yaml138
-rw-r--r--Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvdec.yaml106
-rw-r--r--Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml135
-rw-r--r--Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml94
-rw-r--r--Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml156
-rw-r--r--Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml185
-rw-r--r--Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml138
-rw-r--r--Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt43
-rw-r--r--Documentation/devicetree/bindings/gpu/nvidia,gk20a.yaml171
-rw-r--r--Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt378
-rw-r--r--Documentation/devicetree/bindings/gpu/samsung-g2d.txt28
-rw-r--r--Documentation/devicetree/bindings/gpu/samsung-g2d.yaml86
-rw-r--r--Documentation/devicetree/bindings/gpu/samsung-rotator.txt27
-rw-r--r--Documentation/devicetree/bindings/gpu/samsung-rotator.yaml56
-rw-r--r--Documentation/devicetree/bindings/gpu/samsung-scaler.yaml94
-rw-r--r--Documentation/devicetree/bindings/gpu/st,stih4xx.txt243
-rw-r--r--Documentation/devicetree/bindings/gpu/vivante,gc.yaml76
-rw-r--r--Documentation/devicetree/bindings/graph.txt130
-rw-r--r--Documentation/devicetree/bindings/hid/hid-over-i2c.txt28
-rw-r--r--Documentation/devicetree/bindings/hsi/nokia-modem.txt12
-rw-r--r--Documentation/devicetree/bindings/hsi/omap-ssi.txt15
-rw-r--r--Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml38
-rw-r--r--Documentation/devicetree/bindings/hwinfo/renesas,prr.yaml37
-rw-r--r--Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml60
-rw-r--r--Documentation/devicetree/bindings/hwinfo/samsung,s5pv210-chipid.yaml30
-rw-r--r--Documentation/devicetree/bindings/hwinfo/ti,k3-socinfo.yaml40
-rw-r--r--Documentation/devicetree/bindings/hwinfo/via,vt8500-scc-id.yaml37
-rw-r--r--Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml53
-rw-r--r--Documentation/devicetree/bindings/hwlock/hwlock.txt59
-rw-r--r--Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml55
-rw-r--r--Documentation/devicetree/bindings/hwlock/sprd,hwspinlock-r3p0.yaml50
-rw-r--r--Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.yaml49
-rw-r--r--Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml46
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,ad741x.yaml38
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml70
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml51
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml134
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml63
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml52
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml100
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml127
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml81
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml159
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,max31760.yaml42
-rw-r--r--Documentation/devicetree/bindings/hwmon/adi,max31827.yaml119
-rw-r--r--Documentation/devicetree/bindings/hwmon/ads1015.txt73
-rw-r--r--Documentation/devicetree/bindings/hwmon/adt7475.yaml141
-rw-r--r--Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml53
-rw-r--r--Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml54
-rw-r--r--Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml77
-rw-r--r--Documentation/devicetree/bindings/hwmon/apm,xgene-slimpro-hwmon.yaml30
-rw-r--r--Documentation/devicetree/bindings/hwmon/aspeed,g6-pwm-tach.yaml74
-rw-r--r--Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt73
-rw-r--r--Documentation/devicetree/bindings/hwmon/baikal,bt1-pvt.yaml105
-rw-r--r--Documentation/devicetree/bindings/hwmon/cirrus,lochnagar.yaml35
-rw-r--r--Documentation/devicetree/bindings/hwmon/fan-common.yaml79
-rw-r--r--Documentation/devicetree/bindings/hwmon/g762.txt47
-rw-r--r--Documentation/devicetree/bindings/hwmon/gmt,g762.yaml95
-rw-r--r--Documentation/devicetree/bindings/hwmon/gpio-fan.yaml63
-rw-r--r--Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml45
-rw-r--r--Documentation/devicetree/bindings/hwmon/hwmon-common.yaml19
-rw-r--r--Documentation/devicetree/bindings/hwmon/ibm,occ-hwmon.yaml39
-rw-r--r--Documentation/devicetree/bindings/hwmon/ibm,opal-sensor.yaml37
-rw-r--r--Documentation/devicetree/bindings/hwmon/ibmpowernv.txt23
-rw-r--r--Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml37
-rw-r--r--Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml78
-rw-r--r--Documentation/devicetree/bindings/hwmon/kontron,sl28cpld-hwmon.yaml28
-rw-r--r--Documentation/devicetree/bindings/hwmon/lantiq,cputemp.yaml30
-rw-r--r--Documentation/devicetree/bindings/hwmon/lltc,ltc2978.yaml103
-rw-r--r--Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml44
-rw-r--r--Documentation/devicetree/bindings/hwmon/lltc,ltc4286.yaml49
-rw-r--r--Documentation/devicetree/bindings/hwmon/lm75.yaml105
-rw-r--r--Documentation/devicetree/bindings/hwmon/lm90.txt44
-rw-r--r--Documentation/devicetree/bindings/hwmon/ltc2978.txt39
-rw-r--r--Documentation/devicetree/bindings/hwmon/ltc2990.txt36
-rw-r--r--Documentation/devicetree/bindings/hwmon/max6697.txt (renamed from Documentation/devicetree/bindings/i2c/max6697.txt)0
-rw-r--r--Documentation/devicetree/bindings/hwmon/maxim,max20730.yaml65
-rw-r--r--Documentation/devicetree/bindings/hwmon/maxim,max31790.yaml84
-rw-r--r--Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml91
-rw-r--r--Documentation/devicetree/bindings/hwmon/maxim,max6650.yaml69
-rw-r--r--Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml111
-rw-r--r--Documentation/devicetree/bindings/hwmon/microchip,lan966x.yaml53
-rw-r--r--Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml43
-rw-r--r--Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml44
-rw-r--r--Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml164
-rw-r--r--Documentation/devicetree/bindings/hwmon/national,lm90.yaml240
-rw-r--r--Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt88
-rw-r--r--Documentation/devicetree/bindings/hwmon/nsa320-mcu.txt20
-rw-r--r--Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml142
-rw-r--r--Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt41
-rw-r--r--Documentation/devicetree/bindings/hwmon/nuvoton,nct6775.yaml57
-rw-r--r--Documentation/devicetree/bindings/hwmon/nuvoton,nct7363.yaml65
-rw-r--r--Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml144
-rw-r--r--Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml36
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/adi,adp1050.yaml60
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/adi,lt3074.yaml50
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/adi,max17616.yaml52
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml77
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/isil,isl68137.yaml151
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/mps,mp2975.yaml75
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/mps,mpq8785.yaml74
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/ti,lm25066.yaml69
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/ti,tps25990.yaml83
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml62
-rw-r--r--Documentation/devicetree/bindings/hwmon/pmbus/vicor,pli1209bc.yaml62
-rw-r--r--Documentation/devicetree/bindings/hwmon/pwm-fan.txt12
-rw-r--r--Documentation/devicetree/bindings/hwmon/pwm-fan.yaml116
-rw-r--r--Documentation/devicetree/bindings/hwmon/renesas,isl28022.yaml64
-rw-r--r--Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml43
-rw-r--r--Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml61
-rw-r--r--Documentation/devicetree/bindings/hwmon/sophgo,sg2042-hwmon-mcu.yaml47
-rw-r--r--Documentation/devicetree/bindings/hwmon/st,stts751.yaml41
-rw-r--r--Documentation/devicetree/bindings/hwmon/st,tsc1641.yaml63
-rw-r--r--Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml70
-rw-r--r--Documentation/devicetree/bindings/hwmon/syna,as370.yaml32
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,adc128d818.yaml62
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml56
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,amc6821.yaml108
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml172
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml121
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,lm87.yaml70
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml56
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml66
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml104
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tmp421.yaml109
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml113
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml92
-rw-r--r--Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml52
-rw-r--r--Documentation/devicetree/bindings/hwmon/vexpress.txt2
-rw-r--r--Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml40
-rw-r--r--Documentation/devicetree/bindings/hwrng/atmel-trng.txt16
-rw-r--r--Documentation/devicetree/bindings/hwrng/brcm,iproc-rng200.txt12
-rw-r--r--Documentation/devicetree/bindings/hwrng/omap_rng.txt22
-rw-r--r--Documentation/devicetree/bindings/hwrng/timeriomem_rng.txt18
-rw-r--r--Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml63
-rw-r--r--Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml58
-rw-r--r--Documentation/devicetree/bindings/i2c/apm,xgene-slimpro-i2c.yaml36
-rw-r--r--Documentation/devicetree/bindings/i2c/apple,i2c.yaml77
-rw-r--r--Documentation/devicetree/bindings/i2c/arm,i2c-versatile.yaml29
-rw-r--r--Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml68
-rw-r--r--Documentation/devicetree/bindings/i2c/atmel,at91sam-i2c.yaml142
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt20
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml54
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,brcmstb-i2c.yaml96
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt37
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml71
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,kona-i2c.txt35
-rw-r--r--Documentation/devicetree/bindings/i2c/brcm,kona-i2c.yaml59
-rw-r--r--Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml75
-rw-r--r--Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml66
-rw-r--r--Documentation/devicetree/bindings/i2c/hisilicon,ascend910-i2c.yaml73
-rw-r--r--Documentation/devicetree/bindings/i2c/hisilicon,hix5hd2-i2c.yaml51
-rw-r--r--Documentation/devicetree/bindings/i2c/hpe,gxp-i2c.yaml59
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-altera.txt39
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt86
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml135
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-at91.txt34
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-atr.yaml34
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-axxia.txt2
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-cadence.txt24
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-cbus-gpio.txt4
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-cros-ec-tunnel.txt39
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-davinci.txt20
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml173
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-designware.txt45
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-efm32.txt34
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-exynos5.txt53
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml151
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-gate.yaml38
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-gpio.txt32
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-gpio.yaml99
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt24
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml85
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-imx.txt40
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-imx.yaml127
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-iop3xx.txt20
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-jz4780.txt35
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-meson.txt24
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mpc.txt64
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mpc.yaml101
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml136
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt81
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml107
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.yaml122
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt61
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt53
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml174
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt93
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml103
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux-reg.txt74
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux.txt60
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mux.yaml87
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt44
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mxs.txt25
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-mxs.yaml54
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-nomadik.txt23
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-ocores.txt69
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-octeon.txt6
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-omap.txt31
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-owl.yaml62
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-pca-platform.txt27
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-pnx.txt36
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-pxa-pci-ce4100.txt4
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-pxa.txt33
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-pxa.yaml74
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-rcar.txt32
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-riic.txt29
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-rk3x.txt56
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml149
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt60
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt40
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-sirf.txt19
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-st-ddci2c.txt15
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-st.txt41
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-sunxi-p2wi.txt41
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-versatile.txt10
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-virtio.yaml51
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-vt8500.txt24
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-xiic.txt22
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-xlp9xx.txt22
-rw-r--r--Documentation/devicetree/bindings/i2c/ibm,i2c-fsi.yaml76
-rw-r--r--Documentation/devicetree/bindings/i2c/ina209.txt18
-rw-r--r--Documentation/devicetree/bindings/i2c/ina2xx.txt22
-rw-r--r--Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml90
-rw-r--r--Documentation/devicetree/bindings/i2c/loongson,ls2x-i2c.yaml51
-rw-r--r--Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml142
-rw-r--r--Documentation/devicetree/bindings/i2c/mediatek,mt7621-i2c.yaml61
-rw-r--r--Documentation/devicetree/bindings/i2c/microchip,corei2c.yaml58
-rw-r--r--Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml77
-rw-r--r--Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml44
-rw-r--r--Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt75
-rw-r--r--Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml224
-rw-r--r--Documentation/devicetree/bindings/i2c/nxp,lpc1788-i2c.yaml54
-rw-r--r--Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml56
-rw-r--r--Documentation/devicetree/bindings/i2c/nxp,pnx-i2c.yaml49
-rw-r--r--Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml114
-rw-r--r--Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml367
-rw-r--r--Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml147
-rw-r--r--Documentation/devicetree/bindings/i2c/qcom,i2c-qup.txt40
-rw-r--r--Documentation/devicetree/bindings/i2c/qcom,i2c-qup.yaml103
-rw-r--r--Documentation/devicetree/bindings/i2c/realtek,rtl9301-i2c.yaml104
-rw-r--r--Documentation/devicetree/bindings/i2c/renesas,iic-emev2.yaml54
-rw-r--r--Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml166
-rw-r--r--Documentation/devicetree/bindings/i2c/renesas,riic.yaml162
-rw-r--r--Documentation/devicetree/bindings/i2c/renesas,rmobile-iic.yaml149
-rw-r--r--Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml80
-rw-r--r--Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml163
-rw-r--r--Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml170
-rw-r--r--Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml58
-rw-r--r--Documentation/devicetree/bindings/i2c/socionext,uniphier-fi2c.yaml55
-rw-r--r--Documentation/devicetree/bindings/i2c/socionext,uniphier-i2c.yaml55
-rw-r--r--Documentation/devicetree/bindings/i2c/spacemit,k1-i2c.yaml64
-rw-r--r--Documentation/devicetree/bindings/i2c/sprd,sc9860-i2c.yaml65
-rw-r--r--Documentation/devicetree/bindings/i2c/st,nomadik-i2c.yaml153
-rw-r--r--Documentation/devicetree/bindings/i2c/st,sti-i2c.yaml71
-rw-r--r--Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml193
-rw-r--r--Documentation/devicetree/bindings/i2c/ti,bq32k.txt18
-rw-r--r--Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml96
-rw-r--r--Documentation/devicetree/bindings/i2c/trivial-devices.txt103
-rw-r--r--Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml67
-rw-r--r--Documentation/devicetree/bindings/i2c/wm,wm8505-i2c.yaml47
-rw-r--r--Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml60
-rw-r--r--Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml72
-rw-r--r--Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml72
-rw-r--r--Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml65
-rw-r--r--Documentation/devicetree/bindings/i3c/i3c.yaml196
-rw-r--r--Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml52
-rw-r--r--Documentation/devicetree/bindings/i3c/renesas,i3c.yaml185
-rw-r--r--Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml95
-rw-r--r--Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml56
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml89
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml93
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml89
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adxl367.yaml80
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml67
-rw-r--r--Documentation/devicetree/bindings/iio/accel/adi,adxl380.yaml95
-rw-r--r--Documentation/devicetree/bindings/iio/accel/bma180.txt24
-rw-r--r--Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml56
-rw-r--r--Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml119
-rw-r--r--Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml55
-rw-r--r--Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml71
-rw-r--r--Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml82
-rw-r--r--Documentation/devicetree/bindings/iio/accel/fsl,mma8452.yaml65
-rw-r--r--Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml72
-rw-r--r--Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml69
-rw-r--r--Documentation/devicetree/bindings/iio/accel/lis302.txt (renamed from Documentation/devicetree/bindings/misc/lis302.txt)8
-rw-r--r--Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/accel/murata,sca3300.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml95
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adc.yaml87
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml246
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4030.yaml110
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4080.yaml101
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4130.yaml262
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4170-4.yaml554
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml268
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml155
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml127
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml182
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml483
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7191.yaml149
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml257
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7280a.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml110
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7298.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7380.yaml316
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7405.yaml60
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7476.yaml226
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml427
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7625.yaml176
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml191
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7779.yaml152
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml99
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7923.yaml81
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7944.yaml213
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad7949.yaml102
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml73
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml80
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,ade9000.yaml94
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml140
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,max11410.yaml177
-rw-r--r--Documentation/devicetree/bindings/iio/adc/adi,max14001.yaml89
-rw-r--r--Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml96
-rw-r--r--Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml43
-rw-r--r--Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.yaml153
-rw-r--r--Documentation/devicetree/bindings/iio/adc/aspeed,ast2400-adc.yaml56
-rw-r--r--Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml95
-rw-r--r--Documentation/devicetree/bindings/iio/adc/at91_adc.txt87
-rw-r--r--Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml100
-rw-r--r--Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml121
-rw-r--r--Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml67
-rw-r--r--Documentation/devicetree/bindings/iio/adc/brcm,iproc-static-adc.yaml65
-rw-r--r--Documentation/devicetree/bindings/iio/adc/cc10001_adc.txt22
-rw-r--r--Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml47
-rw-r--r--Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/adc/da9150-gpadc.txt16
-rw-r--r--Documentation/devicetree/bindings/iio/adc/dlg,da9150-gpadc.yaml35
-rw-r--r--Documentation/devicetree/bindings/iio/adc/envelope-detector.yaml86
-rw-r--r--Documentation/devicetree/bindings/iio/adc/fsl,imx25-gcq.yaml131
-rw-r--r--Documentation/devicetree/bindings/iio/adc/fsl,imx7d-adc.yaml62
-rw-r--r--Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml88
-rw-r--r--Documentation/devicetree/bindings/iio/adc/gehc,pmc-adc.yaml86
-rw-r--r--Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml91
-rw-r--r--Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml60
-rw-r--r--Documentation/devicetree/bindings/iio/adc/marvell,berlin2-adc.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/adc/max1027-adc.txt22
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max11100.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max1118.yaml64
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max11205.yaml69
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml81
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max34408.yaml139
-rw-r--r--Documentation/devicetree/bindings/iio/adc/maxim,max9611.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/adc/mcp320x.txt30
-rw-r--r--Documentation/devicetree/bindings/iio/adc/mcp3422.txt17
-rw-r--r--Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml87
-rw-r--r--Documentation/devicetree/bindings/iio/adc/mediatek,mt6359-auxadc.yaml35
-rw-r--r--Documentation/devicetree/bindings/iio/adc/mediatek,mt6360-adc.yaml31
-rw-r--r--Documentation/devicetree/bindings/iio/adc/microchip,mcp3201.yaml79
-rw-r--r--Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml205
-rw-r--r--Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml93
-rw-r--r--Documentation/devicetree/bindings/iio/adc/microchip,pac1921.yaml71
-rw-r--r--Documentation/devicetree/bindings/iio/adc/microchip,pac1934.yaml120
-rw-r--r--Documentation/devicetree/bindings/iio/adc/motorola,cpcap-adc.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nuvoton,nau7802.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nuvoton,nct7201.yaml70
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nuvoton,npcm750-adc.yaml67
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nuvoton-nau7802.txt18
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nxp,imx8qxp-adc.yaml85
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml86
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nxp,lpc1850-adc.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/adc/nxp,lpc3220-adc.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml166
-rw-r--r--Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt46
-rw-r--r--Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml66
-rw-r--r--Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt129
-rw-r--r--Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml308
-rw-r--r--Documentation/devicetree/bindings/iio/adc/renesas,r9a09g077-adc.yaml135
-rw-r--r--Documentation/devicetree/bindings/iio/adc/renesas,rcar-gyroadc.yaml141
-rw-r--r--Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml170
-rw-r--r--Documentation/devicetree/bindings/iio/adc/renesas,rzn1-adc.yaml111
-rw-r--r--Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml63
-rw-r--r--Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt24
-rw-r--r--Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml94
-rw-r--r--Documentation/devicetree/bindings/iio/adc/rohm,bd79104.yaml76
-rw-r--r--Documentation/devicetree/bindings/iio/adc/rohm,bd79112.yaml104
-rw-r--r--Documentation/devicetree/bindings/iio/adc/rohm,bd79124.yaml114
-rw-r--r--Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml167
-rw-r--r--Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/adc/sophgo,cv1800b-saradc.yaml83
-rw-r--r--Documentation/devicetree/bindings/iio/adc/sprd,sc2720-adc.yaml103
-rw-r--r--Documentation/devicetree/bindings/iio/adc/st,spear600-adc.yaml69
-rw-r--r--Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml613
-rw-r--r--Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml429
-rw-r--r--Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml42
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml55
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc0832.yaml57
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc084s021.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc108s102.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc12138.yaml87
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc128s052.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,adc161s626.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml131
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads1100.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads1119.yaml155
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads124s08.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml79
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml182
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads7138.yaml63
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml110
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads7950.yaml65
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads8344.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,am3359-adc.yaml75
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml70
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,palmas-gpadc.yaml70
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,tlc4541.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml119
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,twl4030-madc.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml43
-rw-r--r--Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt18
-rw-r--r--Documentation/devicetree/bindings/iio/adc/twl4030-madc.txt24
-rw-r--r--Documentation/devicetree/bindings/iio/adc/vf610-adc.txt22
-rw-r--r--Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml85
-rw-r--r--Documentation/devicetree/bindings/iio/adc/xilinx-xadc.txt50
-rw-r--r--Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml236
-rw-r--r--Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml371
-rw-r--r--Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml172
-rw-r--r--Documentation/devicetree/bindings/iio/afe/current-sense-amplifier.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/afe/current-sense-shunt.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/afe/temperature-sense-rtd.yaml101
-rw-r--r--Documentation/devicetree/bindings/iio/afe/temperature-transducer.yaml114
-rw-r--r--Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml96
-rw-r--r--Documentation/devicetree/bindings/iio/amplifiers/adi,ada4250.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml101
-rw-r--r--Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml69
-rw-r--r--Documentation/devicetree/bindings/iio/cdc/adi,ad7746.yaml77
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/ams,ccs811.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/aosong,ags02ma.yaml47
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/atlas,sensor.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml62
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/sciosense,ens160.yaml70
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/senseair,sunrise.yaml55
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/sensirion,scd4x.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/chemical/winsen,mhz19b.yaml33
-rw-r--r--Documentation/devicetree/bindings/iio/common.yaml37
-rw-r--r--Documentation/devicetree/bindings/iio/dac/ad7303.txt23
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad3530r.yaml100
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml248
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml267
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml72
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5446.yaml138
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml96
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5592r.yaml204
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5696.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml169
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml140
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml65
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml196
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml97
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml63
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad7303.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad8460.yaml164
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ad9739a.yaml95
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,axi-dac.yaml125
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ltc2664.yaml181
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ltc2672.yaml160
-rw-r--r--Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml147
-rw-r--r--Documentation/devicetree/bindings/iio/dac/dac.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/dac/dpot-dac.yaml64
-rw-r--r--Documentation/devicetree/bindings/iio/dac/fsl,vf610-dac.yaml55
-rw-r--r--Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml77
-rw-r--r--Documentation/devicetree/bindings/iio/dac/max5821.txt14
-rw-r--r--Documentation/devicetree/bindings/iio/dac/maxim,ds4424.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/dac/maxim,max5522.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/dac/maxim,max5821.yaml44
-rw-r--r--Documentation/devicetree/bindings/iio/dac/microchip,mcp4725.yaml90
-rw-r--r--Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/dac/microchip,mcp4821.yaml86
-rw-r--r--Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/dac/nxp,lpc1850-dac.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml81
-rw-r--r--Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml114
-rw-r--r--Documentation/devicetree/bindings/iio/dac/ti,dac082s085.yaml73
-rw-r--r--Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/dac/ti,dac7311.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/dac/ti,dac7512.yaml42
-rw-r--r--Documentation/devicetree/bindings/iio/dac/ti,dac7612.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml86
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adf4350.txt86
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adf4371.yaml70
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,adf4350.yaml199
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,adf4377.yaml102
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml127
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml154
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml145
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,admv4420.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/frequency/adi,adrf6780.yaml134
-rw-r--r--Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml62
-rw-r--r--Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml57
-rw-r--r--Documentation/devicetree/bindings/iio/gyroscope/invensense,itg3200.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml70
-rw-r--r--Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml98
-rw-r--r--Documentation/devicetree/bindings/iio/health/maxim,max30100.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml76
-rw-r--r--Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml56
-rw-r--r--Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/humidity/dht11.txt14
-rw-r--r--Documentation/devicetree/bindings/iio/humidity/dht11.yaml41
-rw-r--r--Documentation/devicetree/bindings/iio/humidity/sciosense,ens210.yaml55
-rw-r--r--Documentation/devicetree/bindings/iio/humidity/st,hts221.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml63
-rw-r--r--Documentation/devicetree/bindings/iio/iio-bindings.txt97
-rw-r--r--Documentation/devicetree/bindings/iio/impedance-analyzer/adi,ad5933.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml165
-rw-r--r--Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml144
-rw-r--r--Documentation/devicetree/bindings/iio/imu/adi,adis16550.yaml74
-rw-r--r--Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml99
-rw-r--r--Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml80
-rw-r--r--Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/imu/bosch,bno055.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/imu/bosch,smi240.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/imu/bosch,smi330.yaml90
-rw-r--r--Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml110
-rw-r--r--Documentation/devicetree/bindings/iio/imu/invensense,icm45600.yaml90
-rw-r--r--Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml121
-rw-r--r--Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml79
-rw-r--r--Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml125
-rw-r--r--Documentation/devicetree/bindings/iio/light/adux1020.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/light/ams,as73211.yaml57
-rw-r--r--Documentation/devicetree/bindings/iio/light/amstaos,tsl2563.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/light/amstaos,tsl2591.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/light/apds9300.txt22
-rw-r--r--Documentation/devicetree/bindings/iio/light/avago,apds9300.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/light/bh1750.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/light/brcm,apds9160.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/light/capella,cm3605.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/light/capella,cm36651.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/light/cm36651.txt26
-rw-r--r--Documentation/devicetree/bindings/iio/light/dynaimage,al3010.yaml47
-rw-r--r--Documentation/devicetree/bindings/iio/light/dynaimage,al3320a.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/light/gp2ap020a00f.txt21
-rw-r--r--Documentation/devicetree/bindings/iio/light/isl29018.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/light/liteon,ltr390.yaml56
-rw-r--r--Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml58
-rw-r--r--Documentation/devicetree/bindings/iio/light/liteon,ltrf216a.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/light/maxim,max44009.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/light/noa1305.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/light/rohm,bh1745.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/light/rohm,bu27034anuc.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/light/sharp,gp2ap002.yaml87
-rw-r--r--Documentation/devicetree/bindings/iio/light/sharp,gp2ap020a00f.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/light/st,uvis25.yaml42
-rw-r--r--Documentation/devicetree/bindings/iio/light/st,vl6180.yaml44
-rw-r--r--Documentation/devicetree/bindings/iio/light/stk33xx.yaml62
-rw-r--r--Documentation/devicetree/bindings/iio/light/ti,opt3001.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/light/ti,opt4001.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/light/tsl2563.txt19
-rw-r--r--Documentation/devicetree/bindings/iio/light/tsl2583.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/light/tsl2772.yaml84
-rw-r--r--Documentation/devicetree/bindings/iio/light/upisemi,us5182.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/light/vishay,vcnl4000.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/light/vishay,vcnl4035.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/light/vishay,veml6030.yaml107
-rw-r--r--Documentation/devicetree/bindings/iio/light/vishay,veml6046x00.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/light/vishay,veml6075.yaml64
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt18
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/allegromicro,als31300.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8974.yaml57
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml96
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/fsl,mag3110.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/hmc5843.txt21
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/honeywell,hmc5843.yaml43
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/infineon,tlv493d-a1b6.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/pni,rm3100.yaml42
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/silabs,si7210.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml75
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/voltafield,af8133j.yaml59
-rw-r--r--Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml112
-rw-r--r--Documentation/devicetree/bindings/iio/mount-matrix.txt203
-rw-r--r--Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.yaml79
-rw-r--r--Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml51
-rw-r--r--Documentation/devicetree/bindings/iio/potentiometer/max5432.yaml44
-rw-r--r--Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp41010.yaml49
-rw-r--r--Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp4131.yaml104
-rw-r--r--Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp4531.yaml116
-rw-r--r--Documentation/devicetree/bindings/iio/potentiometer/renesas,x9250.yaml78
-rw-r--r--Documentation/devicetree/bindings/iio/potentiostat/ti,lmp91000.yaml68
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/aosong,adp810.yaml45
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/bmp085.yaml123
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/fsl,mpl3115.yaml71
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml145
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml158
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/hoperf,hp03.yaml47
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/infineon,dps310.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/invensense,icp10100.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/meas,ms5611.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/murata,zpa2326.yaml64
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/pressure/sensirion,sdp500.yaml46
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml74
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/as3935.txt28
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/awinic,aw96103.yaml61
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml86
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml35
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/maxbotix,mb1232.yaml60
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml60
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/nicera,d3323aa.yaml62
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/parallax-ping.yaml53
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml131
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml202
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml98
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/semtech,sx9500.yaml50
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/st,vl53l0x.yaml47
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/tyhx,hx9023s.yaml93
-rw-r--r--Documentation/devicetree/bindings/iio/proximity/vishay,vcnl3020.yaml64
-rw-r--r--Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml177
-rw-r--r--Documentation/devicetree/bindings/iio/resolver/adi,ad2s90.yaml63
-rw-r--r--Documentation/devicetree/bindings/iio/samsung,sensorhub-rinato.yaml73
-rw-r--r--Documentation/devicetree/bindings/iio/sensorhub.txt25
-rw-r--r--Documentation/devicetree/bindings/iio/st,st-sensors.yaml202
-rw-r--r--Documentation/devicetree/bindings/iio/st-sensors.txt55
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml559
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/maxim,max31855k.yaml76
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/maxim,max31856.yaml56
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml54
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/melexis,mlx90614.yaml52
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/melexis,mlx90632.yaml74
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/microchip,mcp9600.yaml120
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/ti,tmp006.yaml48
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/ti,tmp007.yaml57
-rw-r--r--Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml51
-rw-r--r--Documentation/devicetree/bindings/incomplete-devices.yaml285
-rw-r--r--Documentation/devicetree/bindings/index.rst10
-rw-r--r--Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt108
-rw-r--r--Documentation/devicetree/bindings/input/adafruit,seesaw-gamepad.yaml63
-rw-r--r--Documentation/devicetree/bindings/input/adc-joystick.yaml127
-rw-r--r--Documentation/devicetree/bindings/input/adc-keys.yaml103
-rw-r--r--Documentation/devicetree/bindings/input/adi,adp5588.yaml139
-rw-r--r--Documentation/devicetree/bindings/input/ads7846.txt91
-rw-r--r--Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml120
-rw-r--r--Documentation/devicetree/bindings/input/ariel-pwrbutton.yaml58
-rw-r--r--Documentation/devicetree/bindings/input/atmel,captouch.yaml59
-rw-r--r--Documentation/devicetree/bindings/input/atmel,maxtouch.txt32
-rw-r--r--Documentation/devicetree/bindings/input/atmel,maxtouch.yaml121
-rw-r--r--Documentation/devicetree/bindings/input/awinic,aw86927.yaml48
-rw-r--r--Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml1148
-rw-r--r--Documentation/devicetree/bindings/input/brcm,bcm-keypad.txt1
-rw-r--r--Documentation/devicetree/bindings/input/cap11xx.txt59
-rw-r--r--Documentation/devicetree/bindings/input/cirrus,cs40l50.yaml68
-rw-r--r--Documentation/devicetree/bindings/input/cirrus,ep9307-keypad.yaml87
-rw-r--r--Documentation/devicetree/bindings/input/clps711x-keypad.txt4
-rw-r--r--Documentation/devicetree/bindings/input/cpcap-pwrbutton.txt20
-rw-r--r--Documentation/devicetree/bindings/input/cros-ec-keyb.txt72
-rw-r--r--Documentation/devicetree/bindings/input/cypress,cyapa.yaml49
-rw-r--r--Documentation/devicetree/bindings/input/cypress,tm2-touchkey.yaml73
-rw-r--r--Documentation/devicetree/bindings/input/cypress-sf.yaml61
-rw-r--r--Documentation/devicetree/bindings/input/dlg,da7280.yaml248
-rw-r--r--Documentation/devicetree/bindings/input/dlg,da9062-onkey.yaml38
-rw-r--r--Documentation/devicetree/bindings/input/dlink,dir685-touchkeys.txt21
-rw-r--r--Documentation/devicetree/bindings/input/e3x0-button.txt2
-rw-r--r--Documentation/devicetree/bindings/input/elan,ekth3000.yaml81
-rw-r--r--Documentation/devicetree/bindings/input/elan,ekth6915.yaml84
-rw-r--r--Documentation/devicetree/bindings/input/elan_i2c.txt34
-rw-r--r--Documentation/devicetree/bindings/input/elants_i2c.txt33
-rw-r--r--Documentation/devicetree/bindings/input/fsl,mpr121-touchkey.yaml90
-rw-r--r--Documentation/devicetree/bindings/input/fsl,scu-key.yaml42
-rw-r--r--Documentation/devicetree/bindings/input/fsl-mma8450.txt12
-rw-r--r--Documentation/devicetree/bindings/input/goodix,gt7375p.yaml89
-rw-r--r--Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml69
-rw-r--r--Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml140
-rw-r--r--Documentation/devicetree/bindings/input/gpio-beeper.txt13
-rw-r--r--Documentation/devicetree/bindings/input/gpio-beeper.yaml33
-rw-r--r--Documentation/devicetree/bindings/input/gpio-decoder.txt23
-rw-r--r--Documentation/devicetree/bindings/input/gpio-keys-polled.txt38
-rw-r--r--Documentation/devicetree/bindings/input/gpio-keys.txt48
-rw-r--r--Documentation/devicetree/bindings/input/gpio-keys.yaml181
-rw-r--r--Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt46
-rw-r--r--Documentation/devicetree/bindings/input/gpio-matrix-keypad.yaml103
-rw-r--r--Documentation/devicetree/bindings/input/gpio-mouse.yaml68
-rw-r--r--Documentation/devicetree/bindings/input/gpio-vibrator.yaml39
-rw-r--r--Documentation/devicetree/bindings/input/hid-over-i2c.yaml85
-rw-r--r--Documentation/devicetree/bindings/input/ibm,op-panel.yaml50
-rw-r--r--Documentation/devicetree/bindings/input/ilitek,ili2901.yaml66
-rw-r--r--Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml67
-rw-r--r--Documentation/devicetree/bindings/input/imx-keypad.txt53
-rw-r--r--Documentation/devicetree/bindings/input/imx-keypad.yaml85
-rw-r--r--Documentation/devicetree/bindings/input/input-reset.txt2
-rw-r--r--Documentation/devicetree/bindings/input/input.yaml64
-rw-r--r--Documentation/devicetree/bindings/input/iqs269a.yaml648
-rw-r--r--Documentation/devicetree/bindings/input/iqs626a.yaml878
-rw-r--r--Documentation/devicetree/bindings/input/iqs62x-keys.yaml132
-rw-r--r--Documentation/devicetree/bindings/input/lpc32xx-key.txt31
-rw-r--r--Documentation/devicetree/bindings/input/matrix-keymap.txt28
-rw-r--r--Documentation/devicetree/bindings/input/matrix-keymap.yaml48
-rw-r--r--Documentation/devicetree/bindings/input/max77650-onkey.yaml38
-rw-r--r--Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml86
-rw-r--r--Documentation/devicetree/bindings/input/mediatek,pmic-keys.yaml95
-rw-r--r--Documentation/devicetree/bindings/input/microchip,cap11xx.yaml226
-rw-r--r--Documentation/devicetree/bindings/input/microchip,qt1050.txt78
-rw-r--r--Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt3
-rw-r--r--Documentation/devicetree/bindings/input/nxp,lpc3220-key.yaml61
-rw-r--r--Documentation/devicetree/bindings/input/pine64,pinephone-keyboard.yaml66
-rw-r--r--Documentation/devicetree/bindings/input/pwm-beeper.txt7
-rw-r--r--Documentation/devicetree/bindings/input/pwm-beeper.yaml41
-rw-r--r--Documentation/devicetree/bindings/input/pwm-vibrator.yaml59
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml89
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml75
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt43
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml65
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt89
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt46
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt22
-rw-r--r--Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.yaml47
-rw-r--r--Documentation/devicetree/bindings/input/raydium_i2c_ts.txt19
-rw-r--r--Documentation/devicetree/bindings/input/regulator-haptic.txt21
-rw-r--r--Documentation/devicetree/bindings/input/regulator-haptic.yaml43
-rw-r--r--Documentation/devicetree/bindings/input/rotary-encoder.txt36
-rw-r--r--Documentation/devicetree/bindings/input/rotary-encoder.yaml90
-rw-r--r--Documentation/devicetree/bindings/input/samsung,s3c6410-keypad.yaml121
-rw-r--r--Documentation/devicetree/bindings/input/samsung-keypad.txt74
-rw-r--r--Documentation/devicetree/bindings/input/sprd,sc27xx-vibrator.yaml31
-rw-r--r--Documentation/devicetree/bindings/input/stmpe-keypad.txt41
-rw-r--r--Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt62
-rw-r--r--Documentation/devicetree/bindings/input/syna,rmi4.yaml293
-rw-r--r--Documentation/devicetree/bindings/input/tca8418_keypad.txt10
-rw-r--r--Documentation/devicetree/bindings/input/ti,drv260x.txt50
-rw-r--r--Documentation/devicetree/bindings/input/ti,drv260x.yaml109
-rw-r--r--Documentation/devicetree/bindings/input/ti,drv2667.txt17
-rw-r--r--Documentation/devicetree/bindings/input/ti,drv266x.yaml49
-rw-r--r--Documentation/devicetree/bindings/input/ti,nspire-keypad.txt60
-rw-r--r--Documentation/devicetree/bindings/input/ti,nspire-keypad.yaml74
-rw-r--r--Documentation/devicetree/bindings/input/ti,palmas-pwrbutton.txt1
-rw-r--r--Documentation/devicetree/bindings/input/ti,tca8418.yaml61
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/adi,ad7879.yaml150
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml70
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ar1021.txt15
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/auo_pixcir_ts.txt6
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs5xx.yaml75
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml769
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt23
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/bu21013.txt28
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/bu21029.txt35
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml62
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt46
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml72
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml148
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml111
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt55
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml133
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml94
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt19
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/elan,ektf2127.yaml58
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml74
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/fsl,imx6ul-tsc.yaml111
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/fsl-mx25-tcq.txt34
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml96
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/goodix.txt29
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/goodix.yaml81
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/hideep.txt41
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml64
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/himax,hx852es.yaml81
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/hycon,hy46xx.yaml119
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/hynitron,cst816x.yaml65
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml65
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ilitek_ts_i2c.yaml76
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml109
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/lpc32xx-tsc.txt16
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/maxim,max11801.yaml46
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml96
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/melfas_mip4.txt20
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/mms114.txt34
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml75
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/neonode,zforce.yaml72
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/novatek,nvt-ts.yaml62
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/nxp,lpc3220-tsc.yaml43
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml68
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt26
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.yaml86
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/rohm,bu21013.yaml95
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.yaml54
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/semtech,sx8654.yaml52
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml91
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/sis_i2c.txt31
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/sitronix,st1232.yaml79
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/sitronix-st1232.txt24
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/st,stmfts.yaml72
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/stmpe.txt43
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/sun4i.txt38
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/sx8654.txt16
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ti,ads7843.yaml183
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ti,am3359-tsc.yaml76
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml128
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ti,tsc2007.yaml77
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt59
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/toradex,vf50-touchscreen.yaml77
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt29
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml219
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/ts4800-ts.txt11
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt42
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt41
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/zeitec,zet6223.yaml62
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/zforce_ts.txt34
-rw-r--r--Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml125
-rw-r--r--Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt19
-rw-r--r--Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt21
-rw-r--r--Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.yaml36
-rw-r--r--Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml104
-rw-r--r--Documentation/devicetree/bindings/interconnect/interconnect.txt86
-rw-r--r--Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml147
-rw-r--r--Documentation/devicetree/bindings/interconnect/mediatek,mt8183-emi.yaml51
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml65
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,glymur-rpmh.yaml172
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,kaanapali-rpmh.yaml124
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,milos-rpmh.yaml136
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml77
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,msm8953.yaml100
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,msm8974.yaml62
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml126
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml145
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml89
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml93
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,qcs615-rpmh.yaml73
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,qcs8300-rpmh.yaml72
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml70
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml28
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml50
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,rpmh-common.yaml43
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml144
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml98
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sar2130p-rpmh.yaml117
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml124
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml49
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml108
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml92
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml152
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm6350-rpmh.yaml125
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm7150-rpmh.yaml84
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml124
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml139
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml136
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,sm8750-rpmh.yaml136
-rw-r--r--Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml83
-rw-r--r--Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml317
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.txt38
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml65
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.yaml49
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml47
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt18
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/allwinner,sun67i-sc-nmi.txt27
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml67
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml65
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/altr,msi-controller.yaml65
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.yaml46
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml94
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/andestech,plicsw.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/apm,xgene1-msi.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml133
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml144
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml313
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml78
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml267
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml244
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,nvic.yaml62
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.yaml61
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/arm,vic.yaml81
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.yaml46
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.yaml62
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2500-scu-ic.yaml52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml90
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt42
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml90
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2712-msix.yaml60
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt110
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.yaml162
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.yaml49
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt41
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.yaml81
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml91
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt90
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml152
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt29
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml72
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-mx.txt18
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.txt25
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.yaml50
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/chrp,open-pic.yaml78
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/cirrus,clps711x-intc.txt41
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/cirrus,ep7209-intc.yaml71
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/cnxt,cx92755-ic.yaml47
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.yaml43
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt21
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/econet,en751221-intc.yaml78
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.yaml34
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.yaml51
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,icoll.yaml45
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,imx8qxp-dc-intc.yaml318
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml72
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.yaml116
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.yaml137
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,ls-msi.yaml79
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml161
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,mu-msi.yaml95
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,tzic.yaml48
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/fsl,vf610-mscm-ir.yaml62
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.yaml47
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.yaml76
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.yaml79
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml66
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml60
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml71
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml56
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/interrupts.txt20
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/jcore,aic.yaml43
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/kontron,sl28cpld-intc.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,cpu-interrupt-controller.yaml34
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml59
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml61
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml57
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml124
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml51
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml62
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml57
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.txt18
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.yaml43
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-gicp.yaml50
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-sei.yaml58
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,armada-370-xp-mpic.txt38
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.yaml52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,cp110-icu.yaml101
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,mpic.yaml63
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,orion-bridge-intc.yaml52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/marvell,orion-intc.txt48
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml86
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.yaml67
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/microchip,lan966x-oic.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/microchip,pic32mzda-evic.yaml60
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/microchip,sama7g5-eic.yaml73
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt60
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml132
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.yaml63
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/msi-controller.yaml46
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/msi.txt135
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mstar,mst-intc.yaml64
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mti,cpu-interrupt-controller.yaml46
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml146
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml39
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra-ictlr.txt43
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.yaml82
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.yaml68
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.txt23
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.yaml38
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.yaml45
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-cpu-intc.yaml61
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-misc-intc.yaml52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml118
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml106
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ralink,rt2880-intc.yaml54
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.yaml43
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml105
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt27
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.yaml107
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt34
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml94
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml80
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml282
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/renesas,rzv2h-icu.yaml280
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml180
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.yaml73
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/riscv,imsics.yaml172
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-mpxy-system-msi.yaml67
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/riscv,rpmi-system-msi.yaml74
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml96
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt53
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml185
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.yaml42
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.yaml48
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.yaml48
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.txt32
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.yaml64
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml53
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml62
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/sophgo,sg2042-msi.yaml63
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/st,spear300-shirq.yaml67
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt35
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml65
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml116
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/starfive,jh8100-intc.yaml61
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml62
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800-irqc.yaml49
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml49
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-sswi.yaml108
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.yaml50
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt36
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.yaml63
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt28
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.yaml52
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu33
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu.yaml55
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml163
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml119
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml107
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.yaml76
-rw-r--r--Documentation/devicetree/bindings/interrupt-controller/xlnx,intc.yaml82
-rw-r--r--Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml66
-rw-r--r--Documentation/devicetree/bindings/iommu/apple,dart.yaml92
-rw-r--r--Documentation/devicetree/bindings/iommu/apple,sart.yaml59
-rw-r--r--Documentation/devicetree/bindings/iommu/arm,smmu-v3.yaml95
-rw-r--r--Documentation/devicetree/bindings/iommu/arm,smmu.txt71
-rw-r--r--Documentation/devicetree/bindings/iommu/arm,smmu.yaml710
-rw-r--r--Documentation/devicetree/bindings/iommu/iommu.txt24
-rw-r--r--Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml242
-rw-r--r--Documentation/devicetree/bindings/iommu/nvidia,tegra20-gart.txt14
-rw-r--r--Documentation/devicetree/bindings/iommu/qcom,apq8064-iommu.yaml78
-rw-r--r--Documentation/devicetree/bindings/iommu/qcom,iommu.yaml132
-rw-r--r--Documentation/devicetree/bindings/iommu/qcom,tbu.yaml69
-rw-r--r--Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt41
-rw-r--r--Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml141
-rw-r--r--Documentation/devicetree/bindings/iommu/riscv,iommu.yaml147
-rw-r--r--Documentation/devicetree/bindings/iommu/rockchip,iommu.txt26
-rw-r--r--Documentation/devicetree/bindings/iommu/rockchip,iommu.yaml89
-rw-r--r--Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt70
-rw-r--r--Documentation/devicetree/bindings/iommu/samsung,sysmmu.yaml99
-rw-r--r--Documentation/devicetree/bindings/iommu/sprd,iommu.yaml57
-rw-r--r--Documentation/devicetree/bindings/iommu/ti,omap-iommu.txt33
-rw-r--r--Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml39
-rw-r--r--Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.yaml44
-rw-r--r--Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml109
-rw-r--r--Documentation/devicetree/bindings/ipmi/ipmb-dev.yaml56
-rw-r--r--Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml67
-rw-r--r--Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml63
-rw-r--r--Documentation/devicetree/bindings/ipmi/nuvoton,npcm750-kcs-bmc.yaml55
-rw-r--r--Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml38
-rw-r--r--Documentation/devicetree/bindings/jailhouse.txt8
-rw-r--r--Documentation/devicetree/bindings/leds/allwinner,sun50i-a100-ledc.yaml137
-rw-r--r--Documentation/devicetree/bindings/leds/ams,as3645a.yaml130
-rw-r--r--Documentation/devicetree/bindings/leds/awinic,aw200xx.yaml173
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/88pm860x.txt (renamed from Documentation/devicetree/bindings/video/backlight/88pm860x.txt)0
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/apple,dwi-bl.yaml57
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/arc,arc2c0608.yaml108
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/awinic,aw99706.yaml101
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/common.yaml53
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml41
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/kinetic,ktd253.yaml49
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml46
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml86
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml44
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml142
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/lp855x-backlight.yaml149
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml121
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml71
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml91
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml263
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/richtek,rt4831-backlight.yaml67
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/sky81452-backlight.txt (renamed from Documentation/devicetree/bindings/video/backlight/sky81452-backlight.txt)0
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/ti,lm3509.yaml136
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/ti,lp8864.yaml80
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/tps65217-backlight.txt (renamed from Documentation/devicetree/bindings/video/backlight/tps65217-backlight.txt)0
-rw-r--r--Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.yaml36
-rw-r--r--Documentation/devicetree/bindings/leds/common.txt56
-rw-r--r--Documentation/devicetree/bindings/leds/common.yaml323
-rw-r--r--Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml99
-rw-r--r--Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml36
-rw-r--r--Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml61
-rw-r--r--Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml37
-rw-r--r--Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml193
-rw-r--r--Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml171
-rw-r--r--Documentation/devicetree/bindings/leds/kinetic,ktd2692.yaml87
-rw-r--r--Documentation/devicetree/bindings/leds/leds-aw2013.yaml104
-rw-r--r--Documentation/devicetree/bindings/leds/leds-bcm63138.yaml102
-rw-r--r--Documentation/devicetree/bindings/leds/leds-bcm6328.yaml400
-rw-r--r--Documentation/devicetree/bindings/leds/leds-bcm6358.txt143
-rw-r--r--Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml41
-rw-r--r--Documentation/devicetree/bindings/leds/leds-consumer.yaml67
-rw-r--r--Documentation/devicetree/bindings/leds/leds-cpcap.txt29
-rw-r--r--Documentation/devicetree/bindings/leds/leds-cr0014114.txt66
-rw-r--r--Documentation/devicetree/bindings/leds/leds-el15203000.txt69
-rw-r--r--Documentation/devicetree/bindings/leds/leds-gpio.txt66
-rw-r--r--Documentation/devicetree/bindings/leds/leds-gpio.yaml85
-rw-r--r--Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml61
-rw-r--r--Documentation/devicetree/bindings/leds/leds-is31fl32xx.txt52
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lgm.yaml135
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lm3532.txt105
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lm3601x.txt51
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lm36274.txt85
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lm3697.txt73
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lp50xx.yaml164
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lp55xx.txt228
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lp55xx.yaml292
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lp8860.txt29
-rw-r--r--Documentation/devicetree/bindings/leds/leds-lt3593.txt37
-rw-r--r--Documentation/devicetree/bindings/leds/leds-max77650.yaml49
-rw-r--r--Documentation/devicetree/bindings/leds/leds-mt6360.yaml191
-rw-r--r--Documentation/devicetree/bindings/leds/leds-netxbig.txt92
-rw-r--r--Documentation/devicetree/bindings/leds/leds-ns2.txt9
-rw-r--r--Documentation/devicetree/bindings/leds/leds-pm8941-wled.txt43
-rw-r--r--Documentation/devicetree/bindings/leds/leds-powernv.txt26
-rw-r--r--Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml86
-rw-r--r--Documentation/devicetree/bindings/leds/leds-pwm.txt50
-rw-r--r--Documentation/devicetree/bindings/leds/leds-pwm.yaml78
-rw-r--r--Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml307
-rw-r--r--Documentation/devicetree/bindings/leds/leds-rt4505.yaml58
-rw-r--r--Documentation/devicetree/bindings/leds/leds-sgm3140.yaml65
-rw-r--r--Documentation/devicetree/bindings/leds/leds-spi-byte.txt44
-rw-r--r--Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt49
-rw-r--r--Documentation/devicetree/bindings/leds/maxim,max77693.yaml105
-rw-r--r--Documentation/devicetree/bindings/leds/mediatek,mt6370-flashlight.yaml41
-rw-r--r--Documentation/devicetree/bindings/leds/mediatek,mt6370-indicator.yaml80
-rw-r--r--Documentation/devicetree/bindings/leds/nxp,pca953x.yaml94
-rw-r--r--Documentation/devicetree/bindings/leds/nxp,pca955x.yaml158
-rw-r--r--Documentation/devicetree/bindings/leds/nxp,pca963x.yaml140
-rw-r--r--Documentation/devicetree/bindings/leds/nxp,pca995x.yaml83
-rw-r--r--Documentation/devicetree/bindings/leds/onnn,ncp5623.yaml98
-rw-r--r--Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml84
-rw-r--r--Documentation/devicetree/bindings/leds/pca963x.txt48
-rw-r--r--Documentation/devicetree/bindings/leds/qcom,pm8058-led.yaml57
-rw-r--r--Documentation/devicetree/bindings/leds/qcom,spmi-flash-led.yaml123
-rw-r--r--Documentation/devicetree/bindings/leds/register-bit-led.txt99
-rw-r--r--Documentation/devicetree/bindings/leds/register-bit-led.yaml95
-rw-r--r--Documentation/devicetree/bindings/leds/regulator-led.yaml55
-rw-r--r--Documentation/devicetree/bindings/leds/richtek,rt8515.yaml111
-rw-r--r--Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml81
-rw-r--r--Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml42
-rw-r--r--Documentation/devicetree/bindings/leds/silergy,sy7802.yaml100
-rw-r--r--Documentation/devicetree/bindings/leds/skyworks,aat1290.yaml95
-rw-r--r--Documentation/devicetree/bindings/leds/sprd,sc2731-bltc.yaml53
-rw-r--r--Documentation/devicetree/bindings/leds/st,led1202.yaml132
-rw-r--r--Documentation/devicetree/bindings/leds/tca6507.txt49
-rw-r--r--Documentation/devicetree/bindings/leds/ti,lp8860.yaml90
-rw-r--r--Documentation/devicetree/bindings/leds/ti,tca6507.yaml135
-rw-r--r--Documentation/devicetree/bindings/leds/ti,tlc59116.yaml90
-rw-r--r--Documentation/devicetree/bindings/leds/ti,tps61310.yaml120
-rw-r--r--Documentation/devicetree/bindings/leds/ti.lm36922.yaml110
-rw-r--r--Documentation/devicetree/bindings/leds/trigger-source.yaml26
-rw-r--r--Documentation/devicetree/bindings/loongarch/cpus.yaml61
-rw-r--r--Documentation/devicetree/bindings/loongarch/loongson.yaml34
-rw-r--r--Documentation/devicetree/bindings/lpddr2/lpddr2-timings.txt52
-rw-r--r--Documentation/devicetree/bindings/lpddr2/lpddr2.txt102
-rw-r--r--Documentation/devicetree/bindings/mailbox/allwinner,sun6i-a31-msgbox.yaml80
-rw-r--r--Documentation/devicetree/bindings/mailbox/altera-mailbox.txt7
-rw-r--r--Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml53
-rw-r--r--Documentation/devicetree/bindings/mailbox/apm,xgene-slimpro-mbox.yaml62
-rw-r--r--Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml96
-rw-r--r--Documentation/devicetree/bindings/mailbox/arm,mhu.yaml168
-rw-r--r--Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml207
-rw-r--r--Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml224
-rw-r--r--Documentation/devicetree/bindings/mailbox/arm-mhu.txt43
-rw-r--r--Documentation/devicetree/bindings/mailbox/aspeed,ast2700-mailbox.yaml68
-rw-r--r--Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.yaml40
-rw-r--r--Documentation/devicetree/bindings/mailbox/brcm,bcm74110-mbox.yaml64
-rw-r--r--Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.yaml63
-rw-r--r--Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.yaml66
-rw-r--r--Documentation/devicetree/bindings/mailbox/cix,sky1-mbox.yaml77
-rw-r--r--Documentation/devicetree/bindings/mailbox/fsl,mu.yaml197
-rw-r--r--Documentation/devicetree/bindings/mailbox/google,gs101-mbox.yaml69
-rw-r--r--Documentation/devicetree/bindings/mailbox/hisilicon,hi3660-mailbox.txt51
-rw-r--r--Documentation/devicetree/bindings/mailbox/hisilicon,hi6220-mailbox.txt74
-rw-r--r--Documentation/devicetree/bindings/mailbox/mailbox.txt38
-rw-r--r--Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.yaml42
-rw-r--r--Documentation/devicetree/bindings/mailbox/mediatek,gce-mailbox.yaml83
-rw-r--r--Documentation/devicetree/bindings/mailbox/mediatek,gce-props.yaml52
-rw-r--r--Documentation/devicetree/bindings/mailbox/mediatek,mt8196-gpueb-mbox.yaml64
-rw-r--r--Documentation/devicetree/bindings/mailbox/microchip,mpfs-mailbox.yaml57
-rw-r--r--Documentation/devicetree/bindings/mailbox/microchip,sbi-ipc.yaml123
-rw-r--r--Documentation/devicetree/bindings/mailbox/mtk,adsp-mbox.yaml56
-rw-r--r--Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml137
-rw-r--r--Documentation/devicetree/bindings/mailbox/omap-mailbox.txt131
-rw-r--r--Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml291
-rw-r--r--Documentation/devicetree/bindings/mailbox/qcom,cpucp-mbox.yaml54
-rw-r--r--Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml88
-rw-r--r--Documentation/devicetree/bindings/mailbox/riscv,rpmi-shmem-mbox.yaml124
-rw-r--r--Documentation/devicetree/bindings/mailbox/riscv,sbi-mpxy-mbox.yaml51
-rw-r--r--Documentation/devicetree/bindings/mailbox/rockchip,rk3368-mailbox.yaml56
-rw-r--r--Documentation/devicetree/bindings/mailbox/sophgo,cv1800b-mailbox.yaml60
-rw-r--r--Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml69
-rw-r--r--Documentation/devicetree/bindings/mailbox/st,sti-mailbox.yaml53
-rw-r--r--Documentation/devicetree/bindings/mailbox/st,stm32-ipcc.yaml76
-rw-r--r--Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml89
-rw-r--r--Documentation/devicetree/bindings/mailbox/ti,message-manager.txt50
-rw-r--r--Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml295
-rw-r--r--Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml79
-rw-r--r--Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml253
-rw-r--r--Documentation/devicetree/bindings/marvell.txt516
-rw-r--r--Documentation/devicetree/bindings/media/allegro,al5e.yaml105
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml129
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml78
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml94
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml68
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml143
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml101
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun6i-a31-mipi-csi2.yaml137
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-de2-rotate.yaml70
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-mipi-csi2.yaml125
-rw-r--r--Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml83
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml47
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,c3-isp.yaml88
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,c3-mipi-adapter.yaml111
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,c3-mipi-csi2.yaml127
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml141
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml59
-rw-r--r--Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml48
-rw-r--r--Documentation/devicetree/bindings/media/amphion,vpu.yaml178
-rw-r--r--Documentation/devicetree/bindings/media/arm,mali-c55.yaml86
-rw-r--r--Documentation/devicetree/bindings/media/aspeed,video-engine.yaml70
-rw-r--r--Documentation/devicetree/bindings/media/atmel,isc.yaml113
-rw-r--r--Documentation/devicetree/bindings/media/atmel-isi.txt91
-rw-r--r--Documentation/devicetree/bindings/media/brcm,bcm2835-unicam.yaml127
-rw-r--r--Documentation/devicetree/bindings/media/cdns,csi2rx.yaml210
-rw-r--r--Documentation/devicetree/bindings/media/cdns,csi2tx.txt99
-rw-r--r--Documentation/devicetree/bindings/media/cec/amlogic,meson-gx-ao-cec.yaml92
-rw-r--r--Documentation/devicetree/bindings/media/cec/cec-common.yaml28
-rw-r--r--Documentation/devicetree/bindings/media/cec/cec-gpio.yaml74
-rw-r--r--Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml63
-rw-r--r--Documentation/devicetree/bindings/media/cec/samsung,s5p-cec.yaml66
-rw-r--r--Documentation/devicetree/bindings/media/cec/st,stih-cec.yaml66
-rw-r--r--Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml57
-rw-r--r--Documentation/devicetree/bindings/media/cnm,wave521c.yaml61
-rw-r--r--Documentation/devicetree/bindings/media/coda.txt30
-rw-r--r--Documentation/devicetree/bindings/media/coda.yaml107
-rw-r--r--Documentation/devicetree/bindings/media/exynos-fimc-lite.txt16
-rw-r--r--Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt15
-rw-r--r--Documentation/devicetree/bindings/media/exynos4-fimc-is.txt49
-rw-r--r--Documentation/devicetree/bindings/media/exynos5-gsc.txt30
-rw-r--r--Documentation/devicetree/bindings/media/fsl,imx-capture-subsystem.yaml37
-rw-r--r--Documentation/devicetree/bindings/media/fsl,imx6-mipi-csi2.yaml143
-rw-r--r--Documentation/devicetree/bindings/media/fsl,imx6q-vdoa.yaml42
-rw-r--r--Documentation/devicetree/bindings/media/fsl,imx6ull-pxp.yaml87
-rw-r--r--Documentation/devicetree/bindings/media/fsl,imx8qm-isi.yaml117
-rw-r--r--Documentation/devicetree/bindings/media/fsl,imx8qxp-isi.yaml106
-rw-r--r--Documentation/devicetree/bindings/media/gpio-ir-receiver.txt16
-rw-r--r--Documentation/devicetree/bindings/media/gpio-ir-receiver.yaml43
-rw-r--r--Documentation/devicetree/bindings/media/hix5hd2-ir.txt11
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adi,ad5820.yaml56
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adi,adp1653.txt38
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adi,adv7180.yaml189
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adi,adv7343.txt (renamed from Documentation/devicetree/bindings/media/i2c/adv7343.txt)0
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adi,adv748x.yaml212
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adi,adv7604.yaml158
-rw-r--r--Documentation/devicetree/bindings/media/i2c/adv7604.txt70
-rw-r--r--Documentation/devicetree/bindings/media/i2c/alliedvision,alvium-csi2.yaml81
-rw-r--r--Documentation/devicetree/bindings/media/i2c/aptina,mt9p031.yaml109
-rw-r--r--Documentation/devicetree/bindings/media/i2c/aptina,mt9v032.txt41
-rw-r--r--Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml75
-rw-r--r--Documentation/devicetree/bindings/media/i2c/asahi-kasei,ak7375.yaml54
-rw-r--r--Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml68
-rw-r--r--Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.yaml47
-rw-r--r--Documentation/devicetree/bindings/media/i2c/dongwoon,dw9719.yaml89
-rw-r--r--Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml97
-rw-r--r--Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.yaml41
-rw-r--r--Documentation/devicetree/bindings/media/i2c/galaxycore,gc0308.yaml108
-rw-r--r--Documentation/devicetree/bindings/media/i2c/galaxycore,gc05a2.yaml112
-rw-r--r--Documentation/devicetree/bindings/media/i2c/galaxycore,gc08a3.yaml112
-rw-r--r--Documentation/devicetree/bindings/media/i2c/galaxycore,gc2145.yaml113
-rw-r--r--Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml119
-rw-r--r--Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml137
-rw-r--r--Documentation/devicetree/bindings/media/i2c/isil,isl79987.yaml113
-rw-r--r--Documentation/devicetree/bindings/media/i2c/maxim,max2175.txt59
-rw-r--r--Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml416
-rw-r--r--Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml121
-rw-r--r--Documentation/devicetree/bindings/media/i2c/maxim,max96714.yaml174
-rw-r--r--Documentation/devicetree/bindings/media/i2c/maxim,max96717.yaml157
-rw-r--r--Documentation/devicetree/bindings/media/i2c/melexis,mlx90640.txt20
-rw-r--r--Documentation/devicetree/bindings/media/i2c/micron,mt9m111.txt37
-rw-r--r--Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml133
-rw-r--r--Documentation/devicetree/bindings/media/i2c/mt9m111.txt28
-rw-r--r--Documentation/devicetree/bindings/media/i2c/mt9p031.txt40
-rw-r--r--Documentation/devicetree/bindings/media/i2c/mt9v032.txt39
-rw-r--r--Documentation/devicetree/bindings/media/i2c/nokia,smia.txt63
-rw-r--r--Documentation/devicetree/bindings/media/i2c/nxp,tda19971.yaml162
-rw-r--r--Documentation/devicetree/bindings/media/i2c/onnn,ar0521.yaml112
-rw-r--r--Documentation/devicetree/bindings/media/i2c/onnn,mt9m001.txt38
-rw-r--r--Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml123
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ov2640.txt46
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ov2659.txt38
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,og01a1b.yaml107
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,og0ve1b.yaml97
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml147
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov02e10.yaml152
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov08x40.yaml120
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov2640.txt41
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov2659.txt47
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml112
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov2685.yaml102
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov2735.yaml108
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml130
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml149
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml141
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml108
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml75
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml98
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml93
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5675.yaml122
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml141
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov6211.yaml96
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov64a40.yaml103
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml113
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov7670.txt55
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml134
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov7740.txt47
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov8856.yaml131
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov8858.yaml108
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml108
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml95
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ovti,ov9650.txt36
-rw-r--r--Documentation/devicetree/bindings/media/i2c/panasonic,amg88xx.txt19
-rw-r--r--Documentation/devicetree/bindings/media/i2c/rda,rda5807.yaml67
-rw-r--r--Documentation/devicetree/bindings/media/i2c/samsung,s5k5baf.yaml105
-rw-r--r--Documentation/devicetree/bindings/media/i2c/samsung,s5k6a3.yaml102
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx111.yaml105
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml128
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx219.yaml112
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx258.yaml135
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml76
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx283.yaml107
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml146
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx296.yaml106
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml82
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml100
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml94
-rw-r--r--Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml115
-rw-r--r--Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml175
-rw-r--r--Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml113
-rw-r--r--Documentation/devicetree/bindings/media/i2c/st,vd55g1.yaml137
-rw-r--r--Documentation/devicetree/bindings/media/i2c/st,vd56g3.yaml139
-rw-r--r--Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml136
-rw-r--r--Documentation/devicetree/bindings/media/i2c/thine,thp7312.yaml223
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml133
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml147
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml441
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,ths8200.txt (renamed from Documentation/devicetree/bindings/media/i2c/ths8200.txt)0
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,tvp514x.txt (renamed from Documentation/devicetree/bindings/media/i2c/tvp514x.txt)0
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,tvp5150.yaml133
-rw-r--r--Documentation/devicetree/bindings/media/i2c/ti,tvp7002.txt (renamed from Documentation/devicetree/bindings/media/i2c/tvp7002.txt)0
-rw-r--r--Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt55
-rw-r--r--Documentation/devicetree/bindings/media/i2c/toshiba,tc358743.txt48
-rw-r--r--Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml180
-rw-r--r--Documentation/devicetree/bindings/media/img,e5010-jpeg-enc.yaml75
-rw-r--r--Documentation/devicetree/bindings/media/img-ir-rev1.txt2
-rw-r--r--Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml95
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml65
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml65
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml168
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml82
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml65
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml66
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml65
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml90
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mt7622-cir.yaml55
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mt8173-mdp.yaml169
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mt8173-vpu.yaml74
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml161
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml140
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml198
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml179
-rw-r--r--Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml285
-rw-r--r--Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml82
-rw-r--r--Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml75
-rw-r--r--Documentation/devicetree/bindings/media/meson-ir.txt14
-rw-r--r--Documentation/devicetree/bindings/media/microchip,csi2dc.yaml199
-rw-r--r--Documentation/devicetree/bindings/media/microchip,sama5d4-vdec.yaml46
-rw-r--r--Documentation/devicetree/bindings/media/microchip,xisc.yaml129
-rw-r--r--Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml43
-rw-r--r--Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml72
-rw-r--r--Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml119
-rw-r--r--Documentation/devicetree/bindings/media/nxp,dw100.yaml69
-rw-r--r--Documentation/devicetree/bindings/media/nxp,imx-mipi-csi2.yaml233
-rw-r--r--Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml87
-rw-r--r--Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml190
-rw-r--r--Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml121
-rw-r--r--Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml202
-rw-r--r--Documentation/devicetree/bindings/media/nxp,imx8mq-vpu.yaml68
-rw-r--r--Documentation/devicetree/bindings/media/pxa-camera.txt1
-rw-r--r--Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml253
-rw-r--r--Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml86
-rw-r--r--Documentation/devicetree/bindings/media/qcom,msm8939-camss.yaml254
-rw-r--r--Documentation/devicetree/bindings/media/qcom,msm8953-camss.yaml337
-rw-r--r--Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml386
-rw-r--r--Documentation/devicetree/bindings/media/qcom,msm8996-venus.yaml157
-rw-r--r--Documentation/devicetree/bindings/media/qcom,qcm2290-camss.yaml243
-rw-r--r--Documentation/devicetree/bindings/media/qcom,qcm2290-venus.yaml130
-rw-r--r--Documentation/devicetree/bindings/media/qcom,qcs8300-camss.yaml336
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sa8775p-camss.yaml361
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sc7180-venus.yaml122
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sc7280-camss.yaml425
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sc7280-venus.yaml131
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sc8280xp-camss.yaml531
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml404
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sdm660-venus.yaml159
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sdm670-camss.yaml318
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml379
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml122
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sdm845-venus.yaml131
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sm8250-camss.yaml492
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml135
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sm8550-camss.yaml597
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sm8550-iris.yaml199
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sm8650-camss.yaml375
-rw-r--r--Documentation/devicetree/bindings/media/qcom,sm8750-iris.yaml186
-rw-r--r--Documentation/devicetree/bindings/media/qcom,venus-common.yaml73
-rw-r--r--Documentation/devicetree/bindings/media/qcom,x1e80100-camss.yaml367
-rw-r--r--Documentation/devicetree/bindings/media/raspberrypi,pispbe.yaml63
-rw-r--r--Documentation/devicetree/bindings/media/raspberrypi,rp1-cfe.yaml93
-rw-r--r--Documentation/devicetree/bindings/media/rc.txt1
-rw-r--r--Documentation/devicetree/bindings/media/rc.yaml164
-rw-r--r--Documentation/devicetree/bindings/media/rcar_vin.txt88
-rw-r--r--Documentation/devicetree/bindings/media/renesas,ceu.yaml82
-rw-r--r--Documentation/devicetree/bindings/media/renesas,csi2.yaml170
-rw-r--r--Documentation/devicetree/bindings/media/renesas,drif.yaml269
-rw-r--r--Documentation/devicetree/bindings/media/renesas,fcp.yaml107
-rw-r--r--Documentation/devicetree/bindings/media/renesas,fdp1.yaml69
-rw-r--r--Documentation/devicetree/bindings/media/renesas,imr.yaml67
-rw-r--r--Documentation/devicetree/bindings/media/renesas,isp.yaml246
-rw-r--r--Documentation/devicetree/bindings/media/renesas,jpu.yaml65
-rw-r--r--Documentation/devicetree/bindings/media/renesas,r9a09g057-ivc.yaml103
-rw-r--r--Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml227
-rw-r--r--Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml182
-rw-r--r--Documentation/devicetree/bindings/media/renesas,vin.yaml361
-rw-r--r--Documentation/devicetree/bindings/media/renesas,vsp1.txt43
-rw-r--r--Documentation/devicetree/bindings/media/renesas,vsp1.yaml134
-rw-r--r--Documentation/devicetree/bindings/media/rockchip,px30-vip.yaml124
-rw-r--r--Documentation/devicetree/bindings/media/rockchip,rk3568-vepu.yaml69
-rw-r--r--Documentation/devicetree/bindings/media/rockchip,rk3568-vicap.yaml172
-rw-r--r--Documentation/devicetree/bindings/media/rockchip,vdec.yaml158
-rw-r--r--Documentation/devicetree/bindings/media/rockchip-isp1.yaml341
-rw-r--r--Documentation/devicetree/bindings/media/rockchip-rga.yaml86
-rw-r--r--Documentation/devicetree/bindings/media/rockchip-vpu.yaml108
-rw-r--r--Documentation/devicetree/bindings/media/s5p-mfc.txt51
-rw-r--r--Documentation/devicetree/bindings/media/samsung,exynos4210-csis.yaml170
-rw-r--r--Documentation/devicetree/bindings/media/samsung,exynos4210-fimc.yaml152
-rw-r--r--Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml225
-rw-r--r--Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-lite.yaml63
-rw-r--r--Documentation/devicetree/bindings/media/samsung,exynos5250-gsc.yaml109
-rw-r--r--Documentation/devicetree/bindings/media/samsung,fimc.yaml278
-rw-r--r--Documentation/devicetree/bindings/media/samsung,s5c73m3.yaml165
-rw-r--r--Documentation/devicetree/bindings/media/samsung,s5p-mfc.yaml195
-rw-r--r--Documentation/devicetree/bindings/media/samsung,s5pv210-jpeg.yaml122
-rw-r--r--Documentation/devicetree/bindings/media/samsung-fimc.txt211
-rw-r--r--Documentation/devicetree/bindings/media/samsung-mipi-csis.txt81
-rw-r--r--Documentation/devicetree/bindings/media/samsung-s5c73m3.txt97
-rw-r--r--Documentation/devicetree/bindings/media/samsung-s5k5baf.txt58
-rw-r--r--Documentation/devicetree/bindings/media/samsung-s5k6a3.txt33
-rw-r--r--Documentation/devicetree/bindings/media/sh_mobile_ceu.txt18
-rw-r--r--Documentation/devicetree/bindings/media/silabs,si470x.yaml48
-rw-r--r--Documentation/devicetree/bindings/media/snps,dw-hdmi-rx.yaml132
-rw-r--r--Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt18
-rw-r--r--Documentation/devicetree/bindings/media/st,st-delta.txt17
-rw-r--r--Documentation/devicetree/bindings/media/st,st-hva.txt24
-rw-r--r--Documentation/devicetree/bindings/media/st,stih4xx.txt32
-rw-r--r--Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml122
-rw-r--r--Documentation/devicetree/bindings/media/st,stm32-dcmipp.yaml130
-rw-r--r--Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml70
-rw-r--r--Documentation/devicetree/bindings/media/st,stm32mp25-csi.yaml124
-rw-r--r--Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml53
-rw-r--r--Documentation/devicetree/bindings/media/starfive,jh7110-camss.yaml180
-rw-r--r--Documentation/devicetree/bindings/media/sunxi-ir.txt25
-rw-r--r--Documentation/devicetree/bindings/media/ti,cal.yaml177
-rw-r--r--Documentation/devicetree/bindings/media/ti,da850-vpif.txt106
-rw-r--r--Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml100
-rw-r--r--Documentation/devicetree/bindings/media/ti,vpe.yaml64
-rw-r--r--Documentation/devicetree/bindings/media/video-interface-devices.yaml410
-rw-r--r--Documentation/devicetree/bindings/media/video-interfaces.txt240
-rw-r--r--Documentation/devicetree/bindings/media/video-interfaces.yaml241
-rw-r--r--Documentation/devicetree/bindings/media/video-mux.yaml106
-rw-r--r--Documentation/devicetree/bindings/media/xilinx/video.txt4
-rw-r--r--Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml209
-rw-r--r--Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt2
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/arm,pl172.yaml222
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/arm,pl35x-smc.yaml156
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/atmel,ebi.txt137
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/brcm,brcmstb-memc-ddr.yaml70
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml48
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.yaml42
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/canaan,k210-sram.yaml52
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml146
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml74
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2-timings.yaml135
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml204
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr3-timings.yaml157
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr3.yaml243
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr4.yaml35
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr5.yaml46
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/exynos-srom.yaml93
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/fsl,ddr.yaml106
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/fsl,ifc.yaml135
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/fsl,imx-weim-peripherals.yaml31
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/fsl,imx-weim.yaml201
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/ifc.txt79
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/imx8m-ddrc.yaml73
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml53
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ingenic,jz4780-nemc.txt75
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ingenic,nemc-peripherals.yaml46
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml95
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-bus-controller.yaml107
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml80
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/marvell,mvebu-sdram-controller.yaml31
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mc-peripheral-props.yaml44
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mediatek,mt7621-memc.yaml32
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.yaml185
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml144
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt1
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt21
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nuvoton,npcm-memory-controller.yaml50
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt36
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml550
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-mc.yaml157
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra186-mc.yaml356
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.yaml249
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml79
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra210-emc.yaml93
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml355
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.yaml172
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/qca,ath79-ddr-controller.yaml54
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/qcom,ebi2-peripheral-props.yaml90
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/qcom,ebi2.yaml156
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/renesas,dbsc.yaml56
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml149
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/renesas,rzg3e-xspi.yaml142
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt44
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml384
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/samsung,exynos4210-srom-peripheral-props.yaml35
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/samsung,exynos5422-dmc.yaml139
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/samsung,s5pv210-dmc.yaml33
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/snps,dw-umctl2-ddrc.yaml117
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi-props.yaml144
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml128
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/st,stm32mp25-omm.yaml226
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/starfive,jh7110-dmc.yaml74
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/synopsys.txt11
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ti,da8xx-ddrctl.yaml35
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ti,gpmc-child.yaml252
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml190
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt2
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/ti/emif.txt37
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml57
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/xlnx,versal-net-ddrmc5.yaml41
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/xlnx,zynq-ddrc-a05.yaml37
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/xlnx,zynqmp-ocmc-1.0.yaml45
-rw-r--r--Documentation/devicetree/bindings/metag/meta-intc.txt82
-rw-r--r--Documentation/devicetree/bindings/metag/meta.txt30
-rw-r--r--Documentation/devicetree/bindings/metag/pdc-intc.txt105
-rw-r--r--Documentation/devicetree/bindings/mfd/ab8500.txt159
-rw-r--r--Documentation/devicetree/bindings/mfd/actions,atc260x.yaml183
-rw-r--r--Documentation/devicetree/bindings/mfd/adi,adp5585.yaml313
-rw-r--r--Documentation/devicetree/bindings/mfd/adi,max77541.yaml68
-rw-r--r--Documentation/devicetree/bindings/mfd/airoha,en7581-gpio-sysctl.yaml90
-rw-r--r--Documentation/devicetree/bindings/mfd/allwinner,sun4i-a10-ts.yaml76
-rw-r--r--Documentation/devicetree/bindings/mfd/allwinner,sun6i-a31-prcm.yaml222
-rw-r--r--Documentation/devicetree/bindings/mfd/allwinner,sun8i-a23-prcm.yaml168
-rw-r--r--Documentation/devicetree/bindings/mfd/altera-a10sr.txt56
-rw-r--r--Documentation/devicetree/bindings/mfd/ampere,smpro.yaml42
-rw-r--r--Documentation/devicetree/bindings/mfd/ams,as3711.yaml223
-rw-r--r--Documentation/devicetree/bindings/mfd/apple,smc.yaml84
-rw-r--r--Documentation/devicetree/bindings/mfd/arizona.txt95
-rw-r--r--Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml67
-rw-r--r--Documentation/devicetree/bindings/mfd/as3711.txt73
-rw-r--r--Documentation/devicetree/bindings/mfd/as3722.txt7
-rw-r--r--Documentation/devicetree/bindings/mfd/aspeed,ast2x00-scu.yaml166
-rw-r--r--Documentation/devicetree/bindings/mfd/aspeed-lpc.yaml202
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel,at91sam9260-gpbr.yaml45
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel,at91sam9260-matrix.yaml52
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml99
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel,sama5d2-flexcom.yaml98
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel-gpbr.txt15
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt51
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel-matrix.txt24
-rw-r--r--Documentation/devicetree/bindings/mfd/atmel-smc.txt3
-rw-r--r--Documentation/devicetree/bindings/mfd/axp20x.txt96
-rw-r--r--Documentation/devicetree/bindings/mfd/bfticu.txt1
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm59056.txt39
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm59056.yaml76
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml177
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml194
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml162
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml130
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml236
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml246
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,cru.yaml108
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,misc.yaml60
-rw-r--r--Documentation/devicetree/bindings/mfd/brcm,twd.yaml69
-rw-r--r--Documentation/devicetree/bindings/mfd/canaan,k210-sysctl.yaml109
-rw-r--r--Documentation/devicetree/bindings/mfd/cirrus,lochnagar.yaml365
-rw-r--r--Documentation/devicetree/bindings/mfd/cirrus,madera.yaml297
-rw-r--r--Documentation/devicetree/bindings/mfd/cros-ec.txt65
-rw-r--r--Documentation/devicetree/bindings/mfd/da9052-i2c.txt60
-rw-r--r--Documentation/devicetree/bindings/mfd/da9055.txt2
-rw-r--r--Documentation/devicetree/bindings/mfd/da9063.txt93
-rw-r--r--Documentation/devicetree/bindings/mfd/da9150.txt35
-rw-r--r--Documentation/devicetree/bindings/mfd/delta,tn48m-cpld.yaml90
-rw-r--r--Documentation/devicetree/bindings/mfd/dlg,da9052.yaml89
-rw-r--r--Documentation/devicetree/bindings/mfd/dlg,da9063.yaml329
-rw-r--r--Documentation/devicetree/bindings/mfd/ene-kb3930.yaml55
-rw-r--r--Documentation/devicetree/bindings/mfd/ene-kb930.yaml65
-rw-r--r--Documentation/devicetree/bindings/mfd/fsl,mc13xxx.yaml300
-rw-r--r--Documentation/devicetree/bindings/mfd/fsl,mcu-mpc8349emitx.yaml53
-rw-r--r--Documentation/devicetree/bindings/mfd/fsl-imx25-tsadc.txt47
-rw-r--r--Documentation/devicetree/bindings/mfd/hi6421.txt4
-rw-r--r--Documentation/devicetree/bindings/mfd/hisilicon,hi6421-spmi-pmic.yaml133
-rw-r--r--Documentation/devicetree/bindings/mfd/hisilicon,hi655x.txt33
-rw-r--r--Documentation/devicetree/bindings/mfd/iqs62x.yaml170
-rw-r--r--Documentation/devicetree/bindings/mfd/khadas,mcu.yaml44
-rw-r--r--Documentation/devicetree/bindings/mfd/lp3943.txt2
-rw-r--r--Documentation/devicetree/bindings/mfd/marvell,88pm886-a1.yaml80
-rw-r--r--Documentation/devicetree/bindings/mfd/max14577.txt146
-rw-r--r--Documentation/devicetree/bindings/mfd/max77620.txt162
-rw-r--r--Documentation/devicetree/bindings/mfd/max77650.yaml149
-rw-r--r--Documentation/devicetree/bindings/mfd/max77686.txt82
-rw-r--r--Documentation/devicetree/bindings/mfd/max77693.txt121
-rw-r--r--Documentation/devicetree/bindings/mfd/max8925.txt64
-rw-r--r--Documentation/devicetree/bindings/mfd/max8998.txt119
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max14577.yaml196
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max5970.yaml156
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max7360.yaml191
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77686.yaml132
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77693.yaml191
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77705.yaml172
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77714.yaml68
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77759.yaml99
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77802.yaml194
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max77843.yaml145
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max8925.yaml145
-rw-r--r--Documentation/devicetree/bindings/mfd/maxim,max8998.yaml324
-rw-r--r--Documentation/devicetree/bindings/mfd/mc13xxx.txt158
-rw-r--r--Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml135
-rw-r--r--Documentation/devicetree/bindings/mfd/mediatek,mt6360.yaml247
-rw-r--r--Documentation/devicetree/bindings/mfd/mediatek,mt6370.yaml282
-rw-r--r--Documentation/devicetree/bindings/mfd/mediatek,mt6397.yaml600
-rw-r--r--Documentation/devicetree/bindings/mfd/mediatek,mt8195-scpsys.yaml71
-rw-r--r--Documentation/devicetree/bindings/mfd/mfd.txt52
-rw-r--r--Documentation/devicetree/bindings/mfd/motorola-cpcap.txt78
-rw-r--r--Documentation/devicetree/bindings/mfd/mps,mp2629.yaml64
-rw-r--r--Documentation/devicetree/bindings/mfd/mscc,ocelot.yaml163
-rw-r--r--Documentation/devicetree/bindings/mfd/mt6397.txt70
-rw-r--r--Documentation/devicetree/bindings/mfd/mxs-lradc.yaml134
-rw-r--r--Documentation/devicetree/bindings/mfd/netronix,ntxec.yaml65
-rw-r--r--Documentation/devicetree/bindings/mfd/nxp,bbnsm.yaml101
-rw-r--r--Documentation/devicetree/bindings/mfd/nxp,lpc1850-creg.yaml148
-rw-r--r--Documentation/devicetree/bindings/mfd/nxp,pf1550.yaml161
-rw-r--r--Documentation/devicetree/bindings/mfd/omap-usb-host.txt8
-rw-r--r--Documentation/devicetree/bindings/mfd/palmas.txt3
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom,pm8008.yaml156
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt75
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml359
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom,tcsr.txt22
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml77
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt97
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml107
-rw-r--r--Documentation/devicetree/bindings/mfd/qcom-rpm.txt264
-rw-r--r--Documentation/devicetree/bindings/mfd/qnap,ts433-mcu.yaml46
-rw-r--r--Documentation/devicetree/bindings/mfd/renesas,r2a11302ft.yaml58
-rw-r--r--Documentation/devicetree/bindings/mfd/retu.txt24
-rw-r--r--Documentation/devicetree/bindings/mfd/richtek,rt4831.yaml90
-rw-r--r--Documentation/devicetree/bindings/mfd/richtek,rt5033.yaml138
-rw-r--r--Documentation/devicetree/bindings/mfd/richtek,rt5120.yaml178
-rw-r--r--Documentation/devicetree/bindings/mfd/ricoh,rn5t618.yaml111
-rw-r--r--Documentation/devicetree/bindings/mfd/rk808.txt177
-rw-r--r--Documentation/devicetree/bindings/mfd/rn5t618.txt36
-rw-r--r--Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml223
-rw-r--r--Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml429
-rw-r--r--Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml261
-rw-r--r--Documentation/devicetree/bindings/mfd/rockchip,rk816.yaml274
-rw-r--r--Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml393
-rw-r--r--Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml286
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd71815-pmic.yaml201
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd71828-pmic.yaml212
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.yaml244
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd71847-pmic.yaml228
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml127
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd9576-pmic.yaml123
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd96801-pmic.yaml177
-rw-r--r--Documentation/devicetree/bindings/mfd/rohm,bd96802-pmic.yaml101
-rw-r--r--Documentation/devicetree/bindings/mfd/s2mpa01.txt90
-rw-r--r--Documentation/devicetree/bindings/mfd/s2mps11.txt139
-rw-r--r--Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.yaml117
-rw-r--r--Documentation/devicetree/bindings/mfd/samsung,s2dos05.yaml99
-rw-r--r--Documentation/devicetree/bindings/mfd/samsung,s2mpa01.yaml91
-rw-r--r--Documentation/devicetree/bindings/mfd/samsung,s2mps11.yaml307
-rw-r--r--Documentation/devicetree/bindings/mfd/samsung,s5m8767.yaml296
-rw-r--r--Documentation/devicetree/bindings/mfd/silergy,sy7636a.yaml94
-rw-r--r--Documentation/devicetree/bindings/mfd/sky81452.txt2
-rw-r--r--Documentation/devicetree/bindings/mfd/spacemit,p1.yaml86
-rw-r--r--Documentation/devicetree/bindings/mfd/sprd,sc2731.yaml244
-rw-r--r--Documentation/devicetree/bindings/mfd/sprd,ums512-glbreg.yaml73
-rw-r--r--Documentation/devicetree/bindings/mfd/st,stm32-lptimer.yaml177
-rw-r--r--Documentation/devicetree/bindings/mfd/st,stm32-timers.yaml190
-rw-r--r--Documentation/devicetree/bindings/mfd/st,stmfx.yaml122
-rw-r--r--Documentation/devicetree/bindings/mfd/st,stmpe.yaml297
-rw-r--r--Documentation/devicetree/bindings/mfd/st,stpmic1.yaml340
-rw-r--r--Documentation/devicetree/bindings/mfd/stericsson,ab8500.yaml521
-rw-r--r--Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml299
-rw-r--r--Documentation/devicetree/bindings/mfd/stmpe.txt29
-rw-r--r--Documentation/devicetree/bindings/mfd/sun6i-prcm.txt59
-rw-r--r--Documentation/devicetree/bindings/mfd/syscon-common.yaml68
-rw-r--r--Documentation/devicetree/bindings/mfd/syscon.txt20
-rw-r--r--Documentation/devicetree/bindings/mfd/syscon.yaml279
-rw-r--r--Documentation/devicetree/bindings/mfd/tc3589x.txt6
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml85
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,bq25703a.yaml117
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,lp8732.yaml112
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml117
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml88
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml106
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,nspire-misc.yaml51
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,tps65086.yaml125
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,tps65910.yaml315
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,tps6594.yaml196
-rw-r--r--Documentation/devicetree/bindings/mfd/ti,twl.yaml585
-rw-r--r--Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt2
-rw-r--r--Documentation/devicetree/bindings/mfd/ti-lmu.txt269
-rw-r--r--Documentation/devicetree/bindings/mfd/tps6105x.txt62
-rw-r--r--[-rwxr-xr-x]Documentation/devicetree/bindings/mfd/tps6507x.txt0
-rw-r--r--Documentation/devicetree/bindings/mfd/tps65910.txt201
-rw-r--r--Documentation/devicetree/bindings/mfd/tps65912.txt49
-rw-r--r--Documentation/devicetree/bindings/mfd/twl-familly.txt47
-rw-r--r--Documentation/devicetree/bindings/mfd/twl4030-audio.txt46
-rw-r--r--Documentation/devicetree/bindings/mfd/twl4030-power.txt48
-rw-r--r--Documentation/devicetree/bindings/mfd/twl6040.txt8
-rw-r--r--Documentation/devicetree/bindings/mfd/wlf,arizona.yaml281
-rw-r--r--Documentation/devicetree/bindings/mfd/wm831x.txt81
-rw-r--r--Documentation/devicetree/bindings/mfd/x-powers,ac100.yaml116
-rw-r--r--Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml421
-rw-r--r--Documentation/devicetree/bindings/mfd/xylon,logicvc.yaml63
-rw-r--r--Documentation/devicetree/bindings/mfd/zii,rave-sp.yaml63
-rw-r--r--Documentation/devicetree/bindings/mipi/dsi/mipi-dsi-bus.txt98
-rw-r--r--Documentation/devicetree/bindings/mipi/nvidia,tegra114-mipi.txt41
-rw-r--r--Documentation/devicetree/bindings/mips/ath79-soc.txt21
-rw-r--r--Documentation/devicetree/bindings/mips/brcm/brcm,bmips.txt8
-rw-r--r--Documentation/devicetree/bindings/mips/brcm/soc.txt158
-rw-r--r--Documentation/devicetree/bindings/mips/brcm/soc.yaml120
-rw-r--r--Documentation/devicetree/bindings/mips/cavium/cib.txt2
-rw-r--r--Documentation/devicetree/bindings/mips/cavium/ciu3.txt27
-rw-r--r--Documentation/devicetree/bindings/mips/cavium/sata-uctl.txt42
-rw-r--r--Documentation/devicetree/bindings/mips/cpu_irq.txt47
-rw-r--r--Documentation/devicetree/bindings/mips/cpus.yaml118
-rw-r--r--Documentation/devicetree/bindings/mips/econet.yaml26
-rw-r--r--Documentation/devicetree/bindings/mips/img/pistachio-marduk.txt10
-rw-r--r--Documentation/devicetree/bindings/mips/img/xilfpga.txt83
-rw-r--r--Documentation/devicetree/bindings/mips/ingenic/devices.yaml58
-rw-r--r--Documentation/devicetree/bindings/mips/lantiq/fpi-bus.txt31
-rw-r--r--Documentation/devicetree/bindings/mips/lantiq/lantiq,cgu.yaml32
-rw-r--r--Documentation/devicetree/bindings/mips/lantiq/lantiq,dma-xway.yaml32
-rw-r--r--Documentation/devicetree/bindings/mips/lantiq/lantiq,ebu.yaml32
-rw-r--r--Documentation/devicetree/bindings/mips/lantiq/lantiq,pmu.yaml32
-rw-r--r--Documentation/devicetree/bindings/mips/lantiq/rcu.txt69
-rw-r--r--Documentation/devicetree/bindings/mips/loongson/devices.yaml56
-rw-r--r--Documentation/devicetree/bindings/mips/loongson/ls2k-reset.yaml38
-rw-r--r--Documentation/devicetree/bindings/mips/loongson/rs780e-acpi.yaml42
-rw-r--r--Documentation/devicetree/bindings/mips/mobileye.yaml37
-rw-r--r--Documentation/devicetree/bindings/mips/mscc.txt42
-rw-r--r--Documentation/devicetree/bindings/mips/mti,mips-cm.yaml57
-rw-r--r--Documentation/devicetree/bindings/mips/ni.txt7
-rw-r--r--Documentation/devicetree/bindings/mips/pic32/microchip,pic32mzda.txt31
-rw-r--r--Documentation/devicetree/bindings/mips/ralink.txt17
-rw-r--r--Documentation/devicetree/bindings/mips/ralink.yaml88
-rw-r--r--Documentation/devicetree/bindings/mips/realtek-rtl.yaml28
-rw-r--r--Documentation/devicetree/bindings/misc/allwinner,sunxi-sid.txt17
-rw-r--r--Documentation/devicetree/bindings/misc/arm-charlcd.txt18
-rw-r--r--Documentation/devicetree/bindings/misc/aspeed,ast2400-cvic.yaml60
-rw-r--r--Documentation/devicetree/bindings/misc/at25.txt35
-rw-r--r--Documentation/devicetree/bindings/misc/atmel-ssc.txt49
-rw-r--r--Documentation/devicetree/bindings/misc/bmp085.txt24
-rw-r--r--Documentation/devicetree/bindings/misc/brcm,kona-smc.txt15
-rw-r--r--Documentation/devicetree/bindings/misc/fsl,dpaa2-console.yaml26
-rw-r--r--Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt40
-rw-r--r--Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml187
-rw-r--r--Documentation/devicetree/bindings/misc/ge-achc.yaml65
-rw-r--r--Documentation/devicetree/bindings/misc/idt,89hpesx.yaml72
-rw-r--r--Documentation/devicetree/bindings/misc/intel,ixp4xx-ahb-queue-manager.yaml51
-rw-r--r--Documentation/devicetree/bindings/misc/lwn,bk4-spi.yaml54
-rw-r--r--Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.yaml44
-rw-r--r--Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.txt12
-rw-r--r--Documentation/devicetree/bindings/misc/nvidia,tegra20-apbmisc.yaml51
-rw-r--r--Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml56
-rw-r--r--Documentation/devicetree/bindings/misc/pci1de4,1.yaml137
-rw-r--r--Documentation/devicetree/bindings/misc/pvpanic-mmio.txt29
-rw-r--r--Documentation/devicetree/bindings/misc/qcom,fastrpc.yaml149
-rw-r--r--Documentation/devicetree/bindings/misc/qemu,vcpu-stall-detector.yaml57
-rw-r--r--Documentation/devicetree/bindings/misc/sram.txt51
-rw-r--r--Documentation/devicetree/bindings/misc/ti,dac7512.txt20
-rw-r--r--Documentation/devicetree/bindings/misc/ti,fpc202.yaml94
-rw-r--r--Documentation/devicetree/bindings/misc/ti,j721e-esm.yaml53
-rw-r--r--Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml140
-rw-r--r--Documentation/devicetree/bindings/misc/xlnx,tmr-inject.yaml47
-rw-r--r--Documentation/devicetree/bindings/misc/xlnx,tmr-manager.yaml47
-rw-r--r--Documentation/devicetree/bindings/mmc/allwinner,sun4i-a10-mmc.yaml111
-rw-r--r--Documentation/devicetree/bindings/mmc/amlogic,meson-gx-mmc.yaml79
-rw-r--r--Documentation/devicetree/bindings/mmc/amlogic,meson-mx-sdhc.yaml70
-rw-r--r--Documentation/devicetree/bindings/mmc/amlogic,meson-mx-sdio.yaml97
-rw-r--r--Documentation/devicetree/bindings/mmc/arasan,sdhci.txt27
-rw-r--r--Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml336
-rw-r--r--Documentation/devicetree/bindings/mmc/arm,pl18x.yaml251
-rw-r--r--Documentation/devicetree/bindings/mmc/aspeed,sdhci.yaml107
-rw-r--r--Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml106
-rw-r--r--Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml93
-rw-r--r--Documentation/devicetree/bindings/mmc/atmel-hsmci.txt73
-rw-r--r--Documentation/devicetree/bindings/mmc/bluefield-dw-mshc.txt29
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhci.txt18
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.yaml54
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,iproc-sdhci.yaml64
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt21
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.yaml48
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.yaml119
-rw-r--r--Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt23
-rw-r--r--Documentation/devicetree/bindings/mmc/cavium-mmc.txt57
-rw-r--r--Documentation/devicetree/bindings/mmc/cdns,sdhci.yaml158
-rw-r--r--Documentation/devicetree/bindings/mmc/davinci_mmc.txt33
-rw-r--r--Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt93
-rw-r--r--Documentation/devicetree/bindings/mmc/fsl,esdhc.yaml107
-rw-r--r--Documentation/devicetree/bindings/mmc/fsl-esdhc.txt36
-rw-r--r--Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt41
-rw-r--r--Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml216
-rw-r--r--Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt24
-rw-r--r--Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml65
-rw-r--r--Documentation/devicetree/bindings/mmc/fujitsu,sdhci-fujitsu.yaml66
-rw-r--r--Documentation/devicetree/bindings/mmc/hisilicon,hi3798cv200-dw-mshc.yaml97
-rw-r--r--Documentation/devicetree/bindings/mmc/img-dw-mshc.txt29
-rw-r--r--Documentation/devicetree/bindings/mmc/ingenic,mmc.yaml107
-rw-r--r--Documentation/devicetree/bindings/mmc/k3-dw-mshc.txt31
-rw-r--r--Documentation/devicetree/bindings/mmc/litex,mmc.yaml78
-rw-r--r--Documentation/devicetree/bindings/mmc/loongson,ls2k0500-mmc.yaml112
-rw-r--r--Documentation/devicetree/bindings/mmc/marvell,dove-sdhci.yaml44
-rw-r--r--Documentation/devicetree/bindings/mmc/marvell,orion-sdio.yaml44
-rw-r--r--Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.yaml260
-rw-r--r--Documentation/devicetree/bindings/mmc/microchip,dw-sparx5-sdhci.yaml67
-rw-r--r--Documentation/devicetree/bindings/mmc/microchip,sdhci-pic32.yaml66
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-card.txt31
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-card.yaml100
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-controller-common.yaml365
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-controller.yaml49
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt25
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml48
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml43
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt25
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml64
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-slot.yaml48
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-spi-slot.txt31
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc-spi-slot.yaml77
-rw-r--r--Documentation/devicetree/bindings/mmc/mmc.txt141
-rw-r--r--Documentation/devicetree/bindings/mmc/mmci.txt61
-rw-r--r--Documentation/devicetree/bindings/mmc/mtk-sd.yaml403
-rw-r--r--Documentation/devicetree/bindings/mmc/mxs-mmc.txt27
-rw-r--r--Documentation/devicetree/bindings/mmc/mxs-mmc.yaml63
-rw-r--r--Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml45
-rw-r--r--Documentation/devicetree/bindings/mmc/nuvoton,ma35d1-sdhci.yaml87
-rw-r--r--Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt38
-rw-r--r--Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.yaml313
-rw-r--r--Documentation/devicetree/bindings/mmc/orion-sdio.txt17
-rw-r--r--Documentation/devicetree/bindings/mmc/owl-mmc.yaml67
-rw-r--r--Documentation/devicetree/bindings/mmc/pxa-mmc.txt6
-rw-r--r--Documentation/devicetree/bindings/mmc/renesas,mmcif.txt32
-rw-r--r--Documentation/devicetree/bindings/mmc/renesas,mmcif.yaml135
-rw-r--r--Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml314
-rw-r--r--Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt25
-rw-r--r--Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml130
-rw-r--r--Documentation/devicetree/bindings/mmc/samsung,exynos-dw-mshc.yaml171
-rw-r--r--Documentation/devicetree/bindings/mmc/samsung,s3c6410-sdhci.yaml81
-rw-r--r--Documentation/devicetree/bindings/mmc/samsung-sdhci.txt32
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-am654.yaml241
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-common.yaml32
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-dove.txt14
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-fujitsu.txt30
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-msm.txt55
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-msm.yaml277
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-pxa.txt50
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-pxa.yaml149
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-sirf.txt18
-rw-r--r--Documentation/devicetree/bindings/mmc/sdhci-st.txt15
-rw-r--r--Documentation/devicetree/bindings/mmc/snps,dwcmshc-sdhci.yaml194
-rw-r--r--Documentation/devicetree/bindings/mmc/socfpga-dw-mshc.txt23
-rw-r--r--Documentation/devicetree/bindings/mmc/socionext,milbeaut-m10v-sdhci-3.0.yaml79
-rw-r--r--Documentation/devicetree/bindings/mmc/socionext,uniphier-sd.yaml117
-rw-r--r--Documentation/devicetree/bindings/mmc/spacemit,sdhci.yaml53
-rw-r--r--Documentation/devicetree/bindings/mmc/sprd,sdhci-r11.yaml112
-rw-r--r--Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml75
-rw-r--r--Documentation/devicetree/bindings/mmc/sunplus,mmc.yaml61
-rw-r--r--Documentation/devicetree/bindings/mmc/sunxi-mmc.txt43
-rw-r--r--Documentation/devicetree/bindings/mmc/synopsys-dw-mshc-common.yaml66
-rw-r--r--Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt109
-rw-r--r--Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.yaml105
-rw-r--r--Documentation/devicetree/bindings/mmc/ti,da830-mmc.yaml61
-rw-r--r--Documentation/devicetree/bindings/mmc/ti,omap2430-sdhci.yaml169
-rw-r--r--Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt60
-rw-r--r--Documentation/devicetree/bindings/mmc/ti-omap.txt28
-rw-r--r--Documentation/devicetree/bindings/mmc/tmio_mmc.txt27
-rw-r--r--Documentation/devicetree/bindings/mmc/usdhi6rol0.txt6
-rw-r--r--Documentation/devicetree/bindings/mmc/vt8500-sdmmc.txt23
-rw-r--r--Documentation/devicetree/bindings/mmc/wm,wm8505-sdhc.yaml66
-rw-r--r--Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml146
-rw-r--r--Documentation/devicetree/bindings/mtd/amlogic,meson-nand.yaml124
-rw-r--r--Documentation/devicetree/bindings/mtd/arasan,nand-controller.yaml58
-rw-r--r--Documentation/devicetree/bindings/mtd/arm,pl353-nand-r2p1.yaml52
-rw-r--r--Documentation/devicetree/bindings/mtd/arm-versatile.txt8
-rw-r--r--Documentation/devicetree/bindings/mtd/atmel,dataflash.yaml55
-rw-r--r--Documentation/devicetree/bindings/mtd/atmel-dataflash.txt17
-rw-r--r--Documentation/devicetree/bindings/mtd/atmel-nand.txt144
-rw-r--r--Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml279
-rw-r--r--Documentation/devicetree/bindings/mtd/cdns,hp-nfc.yaml84
-rw-r--r--Documentation/devicetree/bindings/mtd/davinci-nand.txt94
-rw-r--r--Documentation/devicetree/bindings/mtd/denali,nand.yaml153
-rw-r--r--Documentation/devicetree/bindings/mtd/denali-nand.txt23
-rw-r--r--Documentation/devicetree/bindings/mtd/elm.txt16
-rw-r--r--Documentation/devicetree/bindings/mtd/flctl-nand.txt2
-rw-r--r--Documentation/devicetree/bindings/mtd/fsl,vf610-nfc.yaml89
-rw-r--r--Documentation/devicetree/bindings/mtd/fsl-quadspi.txt35
-rw-r--r--Documentation/devicetree/bindings/mtd/fsl-upm-nand.txt12
-rw-r--r--Documentation/devicetree/bindings/mtd/fsmc-nand.txt6
-rw-r--r--Documentation/devicetree/bindings/mtd/gpio-control-nand.txt6
-rw-r--r--Documentation/devicetree/bindings/mtd/gpmc-nand.txt137
-rw-r--r--Documentation/devicetree/bindings/mtd/gpmc-nor.txt98
-rw-r--r--Documentation/devicetree/bindings/mtd/gpmc-onenand.txt46
-rw-r--r--Documentation/devicetree/bindings/mtd/gpmi-nand.txt58
-rw-r--r--Documentation/devicetree/bindings/mtd/gpmi-nand.yaml197
-rw-r--r--Documentation/devicetree/bindings/mtd/hisi504-nand.txt4
-rw-r--r--Documentation/devicetree/bindings/mtd/hisilicon,fmc-spi-nor.txt24
-rw-r--r--Documentation/devicetree/bindings/mtd/ibm,ndfc.txt (renamed from Documentation/devicetree/bindings/powerpc/4xx/ndfc.txt)0
-rw-r--r--Documentation/devicetree/bindings/mtd/ingenic,nand.yaml139
-rw-r--r--Documentation/devicetree/bindings/mtd/intel,lgm-ebunand.yaml90
-rw-r--r--Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml127
-rw-r--r--Documentation/devicetree/bindings/mtd/loongson,ls1b-nand-controller.yaml122
-rw-r--r--Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt4
-rw-r--r--Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt2
-rw-r--r--Documentation/devicetree/bindings/mtd/m25p80.txt32
-rw-r--r--Documentation/devicetree/bindings/mtd/marvell,nand-controller.yaml226
-rw-r--r--Documentation/devicetree/bindings/mtd/mediatek,mtk-nfc.yaml154
-rw-r--r--Documentation/devicetree/bindings/mtd/mediatek,nand-ecc-engine.yaml63
-rw-r--r--Documentation/devicetree/bindings/mtd/microchip,mchp23k256.txt18
-rw-r--r--Documentation/devicetree/bindings/mtd/microchip,mchp48l640.yaml47
-rw-r--r--Documentation/devicetree/bindings/mtd/mtd-physmap.txt89
-rw-r--r--Documentation/devicetree/bindings/mtd/mtd-physmap.yaml236
-rw-r--r--Documentation/devicetree/bindings/mtd/mtd.yaml117
-rw-r--r--Documentation/devicetree/bindings/mtd/mxc-nand.txt19
-rw-r--r--Documentation/devicetree/bindings/mtd/mxc-nand.yaml44
-rw-r--r--Documentation/devicetree/bindings/mtd/mxic-nand.txt36
-rw-r--r--Documentation/devicetree/bindings/mtd/mxicy,nand-ecc-engine.yaml77
-rw-r--r--Documentation/devicetree/bindings/mtd/nand-chip.yaml74
-rw-r--r--Documentation/devicetree/bindings/mtd/nand-controller.yaml71
-rw-r--r--Documentation/devicetree/bindings/mtd/nand-macronix.txt27
-rw-r--r--Documentation/devicetree/bindings/mtd/nand.txt21
-rw-r--r--Documentation/devicetree/bindings/mtd/nuvoton,ma35d1-nand.yaml95
-rw-r--r--Documentation/devicetree/bindings/mtd/nvidia-tegra20-nand.txt64
-rw-r--r--Documentation/devicetree/bindings/mtd/nxp,lpc1773-spifi.yaml74
-rw-r--r--Documentation/devicetree/bindings/mtd/orion-nand.txt2
-rw-r--r--Documentation/devicetree/bindings/mtd/partition.txt71
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.yaml30
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/binman.yaml53
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/brcm,bcm4908-partitions.yaml72
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.yaml50
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-cfe-nor-partitions.txt24
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-imagetag.txt45
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/brcm,trx.txt42
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml185
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml76
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/linux,ubi.yaml75
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml100
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/partition.yaml141
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/partitions.yaml42
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/qcom,smem-part.yaml62
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/redboot-fis.yaml48
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/seama.yaml44
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/tplink,safeloader-partitions.yaml57
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/u-boot.yaml56
-rw-r--r--Documentation/devicetree/bindings/mtd/partitions/ubi-volume.yaml40
-rw-r--r--Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt43
-rw-r--r--Documentation/devicetree/bindings/mtd/qcom,nandc.yaml241
-rw-r--r--Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml111
-rw-r--r--Documentation/devicetree/bindings/mtd/realtek,rtl9301-ecc.yaml41
-rw-r--r--Documentation/devicetree/bindings/mtd/renesas-nandc.yaml66
-rw-r--r--Documentation/devicetree/bindings/mtd/rockchip,nand-controller.yaml165
-rw-r--r--Documentation/devicetree/bindings/mtd/samsung,s5pv210-onenand.yaml65
-rw-r--r--Documentation/devicetree/bindings/mtd/spear_smi.txt2
-rw-r--r--Documentation/devicetree/bindings/mtd/spi-nand.yaml28
-rw-r--r--Documentation/devicetree/bindings/mtd/st,stm32-fmc2-nand.yaml158
-rw-r--r--Documentation/devicetree/bindings/mtd/st-fsm.txt1
-rw-r--r--Documentation/devicetree/bindings/mtd/sunxi-nand.txt45
-rw-r--r--Documentation/devicetree/bindings/mtd/technologic,nand.yaml45
-rw-r--r--Documentation/devicetree/bindings/mtd/ti,am654-hbmc.yaml71
-rw-r--r--Documentation/devicetree/bindings/mtd/ti,davinci-nand.yaml124
-rw-r--r--Documentation/devicetree/bindings/mtd/ti,elm.yaml72
-rw-r--r--Documentation/devicetree/bindings/mtd/ti,gpmc-nand.yaml126
-rw-r--r--Documentation/devicetree/bindings/mtd/ti,gpmc-onenand.yaml84
-rw-r--r--Documentation/devicetree/bindings/mux/adi,adg792a.txt75
-rw-r--r--Documentation/devicetree/bindings/mux/adi,adgs1408.txt48
-rw-r--r--Documentation/devicetree/bindings/mux/gpio-mux.yaml103
-rw-r--r--Documentation/devicetree/bindings/mux/mux-consumer.yaml67
-rw-r--r--Documentation/devicetree/bindings/mux/mux-controller.yaml205
-rw-r--r--Documentation/devicetree/bindings/mux/reg-mux.yaml146
-rw-r--r--Documentation/devicetree/bindings/net/actions,owl-emac.yaml96
-rw-r--r--Documentation/devicetree/bindings/net/adi,adin.yaml84
-rw-r--r--Documentation/devicetree/bindings/net/adi,adin1110.yaml81
-rw-r--r--Documentation/devicetree/bindings/net/aeonsemi,as21xxx.yaml122
-rw-r--r--Documentation/devicetree/bindings/net/airoha,an7583-mdio.yaml59
-rw-r--r--Documentation/devicetree/bindings/net/airoha,en7581-eth.yaml199
-rw-r--r--Documentation/devicetree/bindings/net/airoha,en7581-npu.yaml99
-rw-r--r--Documentation/devicetree/bindings/net/airoha,en8811h.yaml56
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun4i-a10-emac.yaml67
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun4i-a10-mdio.yaml68
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun4i-emac.txt19
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun4i-mdio.txt27
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.txt27
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun7i-a20-gmac.yaml66
-rw-r--r--Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml415
-rw-r--r--Documentation/devicetree/bindings/net/altera_tse.txt114
-rw-r--r--Documentation/devicetree/bindings/net/altr,gmii-to-sgmii-2.0.yaml49
-rw-r--r--Documentation/devicetree/bindings/net/altr,socfpga-stmmac.yaml178
-rw-r--r--Documentation/devicetree/bindings/net/altr,tse.yaml168
-rw-r--r--Documentation/devicetree/bindings/net/amd,xgbe-seattle-v1a.yaml147
-rw-r--r--Documentation/devicetree/bindings/net/amd-xgbe-phy.txt48
-rw-r--r--Documentation/devicetree/bindings/net/amd-xgbe.txt47
-rw-r--r--Documentation/devicetree/bindings/net/amlogic,g12a-mdio-mux.yaml80
-rw-r--r--Documentation/devicetree/bindings/net/amlogic,gxl-mdio-mux.yaml64
-rw-r--r--Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml182
-rw-r--r--Documentation/devicetree/bindings/net/anarion-gmac.txt25
-rw-r--r--Documentation/devicetree/bindings/net/apm,xgene-enet.yaml115
-rw-r--r--Documentation/devicetree/bindings/net/apm,xgene-mdio-rgmii.yaml54
-rw-r--r--Documentation/devicetree/bindings/net/apm-xgene-enet.txt76
-rw-r--r--Documentation/devicetree/bindings/net/arc_emac.txt39
-rw-r--r--Documentation/devicetree/bindings/net/asix,ax88178.yaml70
-rw-r--r--Documentation/devicetree/bindings/net/asix,ax88796c.yaml74
-rw-r--r--Documentation/devicetree/bindings/net/aspeed,ast2600-mdio.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/amlogic,w155s2-bt.yaml63
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/bluetooth-controller.yaml29
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/brcm,bcm4377-bluetooth.yaml82
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/brcm,bluetooth.yaml163
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/marvell,88w8897.yaml49
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/marvell,sd8897-bt.yaml79
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/mediatek,bluetooth.txt80
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/mediatek,mt7622-bluetooth.yaml51
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/mediatek,mt7921s-bluetooth.yaml55
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/nokia,h4p-bluetooth.txt51
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/nxp,88w8987-bt.yaml109
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml259
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/realtek,bluetooth.yaml68
-rw-r--r--Documentation/devicetree/bindings/net/bluetooth/ti,bluetooth.yaml95
-rw-r--r--Documentation/devicetree/bindings/net/brcm,amac.yaml88
-rw-r--r--Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml158
-rw-r--r--Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml55
-rw-r--r--Documentation/devicetree/bindings/net/brcm,bcm6368-mdio-mux.yaml52
-rw-r--r--Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt78
-rw-r--r--Documentation/devicetree/bindings/net/brcm,bcmgenet.txt121
-rw-r--r--Documentation/devicetree/bindings/net/brcm,bcmgenet.yaml142
-rw-r--r--Documentation/devicetree/bindings/net/brcm,iproc-mdio.yaml38
-rw-r--r--Documentation/devicetree/bindings/net/brcm,mdio-mux-iproc.yaml79
-rw-r--r--Documentation/devicetree/bindings/net/brcm,systemport.txt30
-rw-r--r--Documentation/devicetree/bindings/net/brcm,systemport.yaml86
-rw-r--r--Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt39
-rw-r--r--Documentation/devicetree/bindings/net/brcm,unimac-mdio.yaml89
-rw-r--r--Documentation/devicetree/bindings/net/btusb.txt44
-rw-r--r--Documentation/devicetree/bindings/net/calxeda-xgmac.txt18
-rw-r--r--Documentation/devicetree/bindings/net/calxeda-xgmac.yaml49
-rw-r--r--Documentation/devicetree/bindings/net/can/allwinner,sun4i-a10-can.yaml80
-rw-r--r--Documentation/devicetree/bindings/net/can/atmel,at91sam9263-can.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/can/atmel-can.txt14
-rw-r--r--Documentation/devicetree/bindings/net/can/bosch,c_can.yaml116
-rw-r--r--Documentation/devicetree/bindings/net/can/bosch,m_can.yaml200
-rw-r--r--Documentation/devicetree/bindings/net/can/c_can.txt54
-rw-r--r--Documentation/devicetree/bindings/net/can/can-controller.yaml27
-rw-r--r--Documentation/devicetree/bindings/net/can/can-transceiver.yaml20
-rw-r--r--Documentation/devicetree/bindings/net/can/cc770.txt2
-rw-r--r--Documentation/devicetree/bindings/net/can/ctu,ctucanfd.yaml66
-rw-r--r--Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml225
-rw-r--r--Documentation/devicetree/bindings/net/can/fsl-flexcan.txt29
-rw-r--r--Documentation/devicetree/bindings/net/can/holt_hi311x.txt23
-rw-r--r--Documentation/devicetree/bindings/net/can/ifi_canfd.txt15
-rw-r--r--Documentation/devicetree/bindings/net/can/m_can.txt67
-rw-r--r--Documentation/devicetree/bindings/net/can/microchip,mcp2510.yaml70
-rw-r--r--Documentation/devicetree/bindings/net/can/microchip,mcp251x.txt25
-rw-r--r--Documentation/devicetree/bindings/net/can/microchip,mcp251xfd.yaml86
-rw-r--r--Documentation/devicetree/bindings/net/can/microchip,mpfs-can.yaml56
-rw-r--r--Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml134
-rw-r--r--Documentation/devicetree/bindings/net/can/rcar_can.txt43
-rw-r--r--Documentation/devicetree/bindings/net/can/renesas,rcar-can.yaml139
-rw-r--r--Documentation/devicetree/bindings/net/can/renesas,rcar-canfd.yaml299
-rw-r--r--Documentation/devicetree/bindings/net/can/rockchip,rk3568v2-canfd.yaml74
-rw-r--r--Documentation/devicetree/bindings/net/can/sja1000.txt57
-rw-r--r--Documentation/devicetree/bindings/net/can/st,stm32-bxcan.yaml96
-rw-r--r--Documentation/devicetree/bindings/net/can/ti,tcan4x5x.yaml199
-rw-r--r--Documentation/devicetree/bindings/net/can/ti_hecc.txt32
-rw-r--r--Documentation/devicetree/bindings/net/can/xilinx,can.yaml169
-rw-r--r--Documentation/devicetree/bindings/net/can/xilinx_can.txt44
-rw-r--r--Documentation/devicetree/bindings/net/cavium-mdio.txt61
-rw-r--r--Documentation/devicetree/bindings/net/cavium-pip.txt6
-rw-r--r--Documentation/devicetree/bindings/net/cdns,macb.yaml252
-rw-r--r--Documentation/devicetree/bindings/net/cdns-emac.txt19
-rw-r--r--Documentation/devicetree/bindings/net/cirrus,cs89x0.txt13
-rw-r--r--Documentation/devicetree/bindings/net/cirrus,ep9301-eth.yaml59
-rw-r--r--Documentation/devicetree/bindings/net/cortina,gemini-ethernet.yaml137
-rw-r--r--Documentation/devicetree/bindings/net/cortina.txt21
-rw-r--r--Documentation/devicetree/bindings/net/cpsw-phy-sel.txt2
-rw-r--r--Documentation/devicetree/bindings/net/cpsw.txt52
-rw-r--r--Documentation/devicetree/bindings/net/davicom,dm9000.yaml59
-rw-r--r--Documentation/devicetree/bindings/net/davicom,dm9051.yaml62
-rw-r--r--Documentation/devicetree/bindings/net/davicom-dm9000.txt28
-rw-r--r--Documentation/devicetree/bindings/net/davinci-mdio.txt33
-rw-r--r--Documentation/devicetree/bindings/net/davinci_emac.txt3
-rw-r--r--Documentation/devicetree/bindings/net/dsa/arrow,xrs700x.yaml74
-rw-r--r--Documentation/devicetree/bindings/net/dsa/brcm,b53.yaml276
-rw-r--r--Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml167
-rw-r--r--Documentation/devicetree/bindings/net/dsa/dsa-port.yaml81
-rw-r--r--Documentation/devicetree/bindings/net/dsa/dsa.txt119
-rw-r--r--Documentation/devicetree/bindings/net/dsa/dsa.yaml55
-rw-r--r--Documentation/devicetree/bindings/net/dsa/hirschmann,hellcreek.yaml132
-rw-r--r--Documentation/devicetree/bindings/net/dsa/lan9303.txt100
-rw-r--r--Documentation/devicetree/bindings/net/dsa/lantiq,gswip.yaml350
-rw-r--r--Documentation/devicetree/bindings/net/dsa/marvell,mv88e6060.yaml88
-rw-r--r--Documentation/devicetree/bindings/net/dsa/marvell,mv88e6xxx.yaml337
-rw-r--r--Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml847
-rw-r--r--Documentation/devicetree/bindings/net/dsa/micrel,ks8995.yaml135
-rw-r--r--Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml264
-rw-r--r--Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml193
-rw-r--r--Documentation/devicetree/bindings/net/dsa/motorcomm,yt921x.yaml167
-rw-r--r--Documentation/devicetree/bindings/net/dsa/mscc,ocelot.yaml260
-rw-r--r--Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml212
-rw-r--r--Documentation/devicetree/bindings/net/dsa/qca,ar9331.yaml161
-rw-r--r--Documentation/devicetree/bindings/net/dsa/qca8k.yaml321
-rw-r--r--Documentation/devicetree/bindings/net/dsa/realtek.yaml390
-rw-r--r--Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml152
-rw-r--r--Documentation/devicetree/bindings/net/dsa/vitesse,vsc73xx.yaml194
-rw-r--r--Documentation/devicetree/bindings/net/emac_rockchip.txt50
-rw-r--r--Documentation/devicetree/bindings/net/engleder,tsnep.yaml119
-rw-r--r--Documentation/devicetree/bindings/net/eswin,eic7700-eth.yaml129
-rw-r--r--Documentation/devicetree/bindings/net/ethernet-controller.yaml355
-rw-r--r--Documentation/devicetree/bindings/net/ethernet-phy-package.yaml52
-rw-r--r--Documentation/devicetree/bindings/net/ethernet-phy.yaml321
-rw-r--r--Documentation/devicetree/bindings/net/ethernet-switch-port.yaml26
-rw-r--r--Documentation/devicetree/bindings/net/ethernet-switch.yaml85
-rw-r--r--Documentation/devicetree/bindings/net/ethernet.txt32
-rw-r--r--Documentation/devicetree/bindings/net/ezchip_enet.txt15
-rw-r--r--Documentation/devicetree/bindings/net/faraday,ftgmac100.yaml120
-rw-r--r--Documentation/devicetree/bindings/net/faraday,ftmac.txt24
-rw-r--r--Documentation/devicetree/bindings/net/fixed-link.txt43
-rw-r--r--Documentation/devicetree/bindings/net/fsl,cpm-enet.yaml59
-rw-r--r--Documentation/devicetree/bindings/net/fsl,cpm-mdio.yaml55
-rw-r--r--Documentation/devicetree/bindings/net/fsl,enetc-ierb.yaml38
-rw-r--r--Documentation/devicetree/bindings/net/fsl,enetc-mdio.yaml60
-rw-r--r--Documentation/devicetree/bindings/net/fsl,enetc.yaml89
-rw-r--r--Documentation/devicetree/bindings/net/fsl,fec.yaml277
-rw-r--r--Documentation/devicetree/bindings/net/fsl,fman-dtsec.yaml167
-rw-r--r--Documentation/devicetree/bindings/net/fsl,fman-mdio.yaml123
-rw-r--r--Documentation/devicetree/bindings/net/fsl,fman-muram.yaml40
-rw-r--r--Documentation/devicetree/bindings/net/fsl,fman-port.yaml75
-rw-r--r--Documentation/devicetree/bindings/net/fsl,fman.yaml210
-rw-r--r--Documentation/devicetree/bindings/net/fsl,gianfar-mdio.yaml112
-rw-r--r--Documentation/devicetree/bindings/net/fsl,gianfar.yaml246
-rw-r--r--Documentation/devicetree/bindings/net/fsl,qoriq-mc-dpmac.yaml56
-rw-r--r--Documentation/devicetree/bindings/net/fsl-fec.txt62
-rw-r--r--Documentation/devicetree/bindings/net/fsl-tsec-phy.txt140
-rw-r--r--Documentation/devicetree/bindings/net/gpmc-eth.txt97
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-femac-mdio.txt22
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-femac.txt41
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt21
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-hix5hd2-gmac.txt34
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-hns-dsaf.txt90
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-hns-mdio.txt27
-rw-r--r--Documentation/devicetree/bindings/net/hisilicon-hns-nic.txt76
-rw-r--r--Documentation/devicetree/bindings/net/ibm,emac.txt205
-rw-r--r--Documentation/devicetree/bindings/net/icplus-ip101ag.txt19
-rw-r--r--Documentation/devicetree/bindings/net/idt,3243x-emac.yaml73
-rw-r--r--Documentation/devicetree/bindings/net/ieee802154/adf7242.txt18
-rw-r--r--Documentation/devicetree/bindings/net/ieee802154/at86rf230.txt27
-rw-r--r--Documentation/devicetree/bindings/net/ieee802154/atmel,at86rf233.yaml66
-rw-r--r--Documentation/devicetree/bindings/net/ieee802154/ca8210.txt28
-rw-r--r--Documentation/devicetree/bindings/net/ieee802154/mcr20a.txt23
-rw-r--r--Documentation/devicetree/bindings/net/ieee802154/mrf24j40.txt20
-rw-r--r--Documentation/devicetree/bindings/net/ingenic,mac.yaml77
-rw-r--r--Documentation/devicetree/bindings/net/intel,dwmac-plat.yaml137
-rw-r--r--Documentation/devicetree/bindings/net/intel,ixp46x-ptp-timer.yaml54
-rw-r--r--Documentation/devicetree/bindings/net/intel,ixp4xx-ethernet.yaml111
-rw-r--r--Documentation/devicetree/bindings/net/intel,ixp4xx-hss.yaml123
-rw-r--r--Documentation/devicetree/bindings/net/ipq806x-dwmac.txt35
-rw-r--r--Documentation/devicetree/bindings/net/keystone-netcp.txt62
-rw-r--r--Documentation/devicetree/bindings/net/lantiq,etop-xway.yaml68
-rw-r--r--Documentation/devicetree/bindings/net/lantiq,pef2256.yaml213
-rw-r--r--Documentation/devicetree/bindings/net/lantiq,xrx200-net.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/litex,liteeth.yaml97
-rw-r--r--Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml114
-rw-r--r--Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml113
-rw-r--r--Documentation/devicetree/bindings/net/lpc-eth.txt23
-rw-r--r--Documentation/devicetree/bindings/net/macb.txt30
-rw-r--r--Documentation/devicetree/bindings/net/marvell,aquantia.yaml122
-rw-r--r--Documentation/devicetree/bindings/net/marvell,armada-370-neta.yaml79
-rw-r--r--Documentation/devicetree/bindings/net/marvell,armada-380-neta-bm.yaml60
-rw-r--r--Documentation/devicetree/bindings/net/marvell,dfx-server.yaml62
-rw-r--r--Documentation/devicetree/bindings/net/marvell,mvusb.yaml69
-rw-r--r--Documentation/devicetree/bindings/net/marvell,orion-mdio.yaml60
-rw-r--r--Documentation/devicetree/bindings/net/marvell,pp2.yaml305
-rw-r--r--Documentation/devicetree/bindings/net/marvell,prestera.yaml91
-rw-r--r--Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt21
-rw-r--r--Documentation/devicetree/bindings/net/marvell-orion-mdio.txt39
-rw-r--r--Documentation/devicetree/bindings/net/marvell-orion-net.txt1
-rw-r--r--Documentation/devicetree/bindings/net/marvell-pp2.txt61
-rw-r--r--Documentation/devicetree/bindings/net/marvell-pxa168.txt4
-rw-r--r--Documentation/devicetree/bindings/net/maxim,ds26522.yaml40
-rw-r--r--Documentation/devicetree/bindings/net/maxlinear,gpy2xx.yaml48
-rw-r--r--Documentation/devicetree/bindings/net/mctp-i2c-controller.yaml92
-rw-r--r--Documentation/devicetree/bindings/net/mdio-gpio.txt26
-rw-r--r--Documentation/devicetree/bindings/net/mdio-gpio.yaml57
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux-gpio.txt127
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux-gpio.yaml103
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux-mmioreg.txt75
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux-mmioreg.yaml78
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux-multiplexer.yaml81
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux.txt136
-rw-r--r--Documentation/devicetree/bindings/net/mdio-mux.yaml41
-rw-r--r--Documentation/devicetree/bindings/net/mdio.txt1
-rw-r--r--Documentation/devicetree/bindings/net/mdio.yaml116
-rw-r--r--Documentation/devicetree/bindings/net/mediatek,net.yaml647
-rw-r--r--Documentation/devicetree/bindings/net/mediatek,star-emac.yaml107
-rw-r--r--Documentation/devicetree/bindings/net/mediatek-dwmac.yaml190
-rw-r--r--Documentation/devicetree/bindings/net/meson-dwmac.txt25
-rw-r--r--Documentation/devicetree/bindings/net/micrel,ks8851.yaml98
-rw-r--r--Documentation/devicetree/bindings/net/micrel-ks8851.txt18
-rw-r--r--Documentation/devicetree/bindings/net/micrel-ksz90x1.txt173
-rw-r--r--Documentation/devicetree/bindings/net/micrel.txt22
-rw-r--r--Documentation/devicetree/bindings/net/microchip,enc28j60.txt56
-rw-r--r--Documentation/devicetree/bindings/net/microchip,lan78xx.txt53
-rw-r--r--Documentation/devicetree/bindings/net/microchip,lan8650.yaml74
-rw-r--r--Documentation/devicetree/bindings/net/microchip,lan95xx.yaml67
-rw-r--r--Documentation/devicetree/bindings/net/microchip,lan966x-switch.yaml171
-rw-r--r--Documentation/devicetree/bindings/net/microchip,sparx5-switch.yaml269
-rw-r--r--Documentation/devicetree/bindings/net/motorcomm,yt8xxx.yaml151
-rw-r--r--Documentation/devicetree/bindings/net/moxa,moxart-mac.txt21
-rw-r--r--Documentation/devicetree/bindings/net/mscc,miim.yaml71
-rw-r--r--Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml223
-rw-r--r--Documentation/devicetree/bindings/net/mscc-phy-vsc8531.yaml131
-rw-r--r--Documentation/devicetree/bindings/net/network-class.yaml46
-rw-r--r--Documentation/devicetree/bindings/net/nfc/marvell,nci.yaml170
-rw-r--r--Documentation/devicetree/bindings/net/nfc/nxp,nci.yaml63
-rw-r--r--Documentation/devicetree/bindings/net/nfc/nxp,pn532.yaml65
-rw-r--r--Documentation/devicetree/bindings/net/nfc/nxp,pn544.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/nfc/nxp-nci.txt35
-rw-r--r--Documentation/devicetree/bindings/net/nfc/pn544.txt35
-rw-r--r--Documentation/devicetree/bindings/net/nfc/samsung,s3fwrn5.yaml99
-rw-r--r--Documentation/devicetree/bindings/net/nfc/st,st-nci.yaml105
-rw-r--r--Documentation/devicetree/bindings/net/nfc/st,st21nfca.yaml64
-rw-r--r--Documentation/devicetree/bindings/net/nfc/st,st95hf.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/nfc/st21nfca.txt40
-rw-r--r--Documentation/devicetree/bindings/net/nfc/st21nfcb.txt33
-rw-r--r--Documentation/devicetree/bindings/net/nfc/ti,trf7970a.yaml106
-rw-r--r--Documentation/devicetree/bindings/net/nfc/trf7970a.txt44
-rw-r--r--Documentation/devicetree/bindings/net/nixge.txt92
-rw-r--r--Documentation/devicetree/bindings/net/nvidia,tegra234-mgbe.yaml162
-rw-r--r--Documentation/devicetree/bindings/net/nxp,dwmac-imx.yaml111
-rw-r--r--Documentation/devicetree/bindings/net/nxp,lpc-eth.yaml48
-rw-r--r--Documentation/devicetree/bindings/net/nxp,lpc1850-dwmac.yaml85
-rw-r--r--Documentation/devicetree/bindings/net/nxp,netc-blk-ctrl.yaml105
-rw-r--r--Documentation/devicetree/bindings/net/nxp,s32-dwmac.yaml105
-rw-r--r--Documentation/devicetree/bindings/net/nxp,tja11xx.yaml127
-rw-r--r--Documentation/devicetree/bindings/net/pcs/fsl,lynx-pcs.yaml40
-rw-r--r--Documentation/devicetree/bindings/net/pcs/mediatek,sgmiisys.yaml102
-rw-r--r--Documentation/devicetree/bindings/net/pcs/renesas,rzn1-miic.yaml252
-rw-r--r--Documentation/devicetree/bindings/net/pcs/snps,dw-xpcs.yaml136
-rw-r--r--Documentation/devicetree/bindings/net/phy.txt41
-rw-r--r--Documentation/devicetree/bindings/net/pse-pd/microchip,pd692x0.yaml192
-rw-r--r--Documentation/devicetree/bindings/net/pse-pd/podl-pse-regulator.yaml40
-rw-r--r--Documentation/devicetree/bindings/net/pse-pd/pse-controller.yaml128
-rw-r--r--Documentation/devicetree/bindings/net/pse-pd/skyworks,si3474.yaml144
-rw-r--r--Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml127
-rw-r--r--Documentation/devicetree/bindings/net/qca,ar71xx.yaml194
-rw-r--r--Documentation/devicetree/bindings/net/qca,ar803x.yaml177
-rw-r--r--Documentation/devicetree/bindings/net/qca,qca7000.yaml109
-rw-r--r--Documentation/devicetree/bindings/net/qca,qca808x.yaml54
-rw-r--r--Documentation/devicetree/bindings/net/qca-qca7000-spi.txt47
-rw-r--r--Documentation/devicetree/bindings/net/qcom,bam-dmux.yaml92
-rw-r--r--Documentation/devicetree/bindings/net/qcom,ethqos.yaml144
-rw-r--r--Documentation/devicetree/bindings/net/qcom,ipa.yaml278
-rw-r--r--Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml119
-rw-r--r--Documentation/devicetree/bindings/net/qcom,ipq8064-mdio.yaml61
-rw-r--r--Documentation/devicetree/bindings/net/qcom,ipq9574-ppe.yaml533
-rw-r--r--Documentation/devicetree/bindings/net/qcom,qca807x.yaml184
-rw-r--r--Documentation/devicetree/bindings/net/qcom-emac.txt111
-rw-r--r--Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml83
-rw-r--r--Documentation/devicetree/bindings/net/realtek,rtl9301-mdio.yaml86
-rw-r--r--Documentation/devicetree/bindings/net/realtek,rtl9301-switch.yaml175
-rw-r--r--Documentation/devicetree/bindings/net/renesas,ether.yaml131
-rw-r--r--Documentation/devicetree/bindings/net/renesas,etheravb.yaml375
-rw-r--r--Documentation/devicetree/bindings/net/renesas,ethertsn.yaml130
-rw-r--r--Documentation/devicetree/bindings/net/renesas,r8a779f0-ether-switch.yaml262
-rw-r--r--Documentation/devicetree/bindings/net/renesas,rzn1-gmac.yaml75
-rw-r--r--Documentation/devicetree/bindings/net/renesas,rzv2h-gbeth.yaml303
-rw-r--r--Documentation/devicetree/bindings/net/rfkill-gpio.yaml56
-rw-r--r--Documentation/devicetree/bindings/net/rockchip,emac.yaml115
-rw-r--r--Documentation/devicetree/bindings/net/rockchip-dwmac.txt68
-rw-r--r--Documentation/devicetree/bindings/net/rockchip-dwmac.yaml186
-rw-r--r--Documentation/devicetree/bindings/net/samsung-sxgbe.txt10
-rw-r--r--Documentation/devicetree/bindings/net/sff,sfp.yaml143
-rw-r--r--Documentation/devicetree/bindings/net/sh_eth.txt57
-rw-r--r--Documentation/devicetree/bindings/net/smsc,lan9115.yaml108
-rw-r--r--Documentation/devicetree/bindings/net/smsc,lan91c111.yaml61
-rw-r--r--Documentation/devicetree/bindings/net/smsc-lan87xx.txt27
-rw-r--r--Documentation/devicetree/bindings/net/smsc-lan91c111.txt15
-rw-r--r--Documentation/devicetree/bindings/net/smsc911x.txt35
-rw-r--r--Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt168
-rw-r--r--Documentation/devicetree/bindings/net/snps,dwmac.yaml736
-rw-r--r--Documentation/devicetree/bindings/net/socfpga-dwmac.txt31
-rw-r--r--Documentation/devicetree/bindings/net/socionext,synquacer-netsec.yaml73
-rw-r--r--Documentation/devicetree/bindings/net/socionext,uniphier-ave4.yaml142
-rw-r--r--Documentation/devicetree/bindings/net/sophgo,cv1800b-dwmac.yaml114
-rw-r--r--Documentation/devicetree/bindings/net/sophgo,sg2044-dwmac.yaml151
-rw-r--r--Documentation/devicetree/bindings/net/spacemit,k1-emac.yaml81
-rw-r--r--Documentation/devicetree/bindings/net/starfive,jh7110-dwmac.yaml190
-rw-r--r--Documentation/devicetree/bindings/net/sti-dwmac.txt6
-rw-r--r--Documentation/devicetree/bindings/net/stm32-dwmac.yaml219
-rw-r--r--Documentation/devicetree/bindings/net/stmmac.txt69
-rw-r--r--Documentation/devicetree/bindings/net/sunplus,sp7021-emac.yaml143
-rw-r--r--Documentation/devicetree/bindings/net/tesla,fsd-ethqos.yaml118
-rw-r--r--Documentation/devicetree/bindings/net/thead,th1520-gmac.yaml112
-rw-r--r--Documentation/devicetree/bindings/net/ti,cc1352p7.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml241
-rw-r--r--Documentation/devicetree/bindings/net/ti,davinci-mdio.yaml80
-rw-r--r--Documentation/devicetree/bindings/net/ti,dp83822.yaml147
-rw-r--r--Documentation/devicetree/bindings/net/ti,dp83867.yaml141
-rw-r--r--Documentation/devicetree/bindings/net/ti,dp83869.yaml100
-rw-r--r--Documentation/devicetree/bindings/net/ti,icss-iep.yaml58
-rw-r--r--Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml233
-rw-r--r--Documentation/devicetree/bindings/net/ti,icssm-prueth.yaml233
-rw-r--r--Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml319
-rw-r--r--Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml153
-rw-r--r--Documentation/devicetree/bindings/net/ti,pruss-ecap.yaml32
-rw-r--r--Documentation/devicetree/bindings/net/toshiba,visconti-dwmac.yaml92
-rw-r--r--Documentation/devicetree/bindings/net/vertexcom-mse102x.yaml71
-rw-r--r--Documentation/devicetree/bindings/net/via,vt8500-rhine.yaml41
-rw-r--r--Documentation/devicetree/bindings/net/via-rhine.txt17
-rw-r--r--Documentation/devicetree/bindings/net/wireless/brcm,bcm4329-fmac.yaml165
-rw-r--r--Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt41
-rw-r--r--Documentation/devicetree/bindings/net/wireless/esp,esp8089.yaml43
-rw-r--r--Documentation/devicetree/bindings/net/wireless/ieee80211.yaml44
-rw-r--r--Documentation/devicetree/bindings/net/wireless/marvell,sd8787.yaml92
-rw-r--r--Documentation/devicetree/bindings/net/wireless/mediatek,mt76.yaml390
-rw-r--r--Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml99
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qca,ath9k.yaml106
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt30
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ath10k.yaml394
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ath11k-pci.yaml146
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ath11k.yaml469
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ath12k-wsi.yaml210
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ath12k.yaml104
-rw-r--r--Documentation/devicetree/bindings/net/wireless/qcom,ipq5332-wifi.yaml315
-rw-r--r--Documentation/devicetree/bindings/net/wireless/ralink,rt2880.yaml49
-rw-r--r--Documentation/devicetree/bindings/net/wireless/realtek,rtl8188e.yaml50
-rw-r--r--Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml129
-rw-r--r--Documentation/devicetree/bindings/net/wireless/ti,wl1251.txt31
-rw-r--r--Documentation/devicetree/bindings/net/wireless/ti,wlcore.txt47
-rw-r--r--Documentation/devicetree/bindings/net/wireless/ti,wlcore.yaml141
-rw-r--r--Documentation/devicetree/bindings/net/wireless/wireless-controller.yaml23
-rw-r--r--Documentation/devicetree/bindings/net/wiznet,w5x00.txt50
-rw-r--r--Documentation/devicetree/bindings/net/xlnx,axi-ethernet.yaml200
-rw-r--r--Documentation/devicetree/bindings/net/xlnx,emaclite.yaml68
-rw-r--r--Documentation/devicetree/bindings/net/xlnx,gmii-to-rgmii.yaml60
-rw-r--r--Documentation/devicetree/bindings/nios2/nios2.txt4
-rw-r--r--Documentation/devicetree/bindings/nios2/timer.txt19
-rw-r--r--Documentation/devicetree/bindings/npu/arm,ethos.yaml79
-rw-r--r--Documentation/devicetree/bindings/npu/rockchip,rk3588-rknn-core.yaml112
-rw-r--r--Documentation/devicetree/bindings/nvec/nvidia,nvec.txt21
-rw-r--r--Documentation/devicetree/bindings/nvme/apple,nvme-ans.yaml119
-rw-r--r--Documentation/devicetree/bindings/nvmem/airoha,an8855-efuse.yaml123
-rw-r--r--Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml57
-rw-r--r--Documentation/devicetree/bindings/nvmem/amlogic,meson-gxbb-efuse.yaml61
-rw-r--r--Documentation/devicetree/bindings/nvmem/amlogic,meson6-efuse.yaml58
-rw-r--r--Documentation/devicetree/bindings/nvmem/apple,efuses.yaml51
-rw-r--r--Documentation/devicetree/bindings/nvmem/apple,spmi-nvmem.yaml54
-rw-r--r--Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml73
-rw-r--r--Documentation/devicetree/bindings/nvmem/brcm,ocotp.yaml39
-rw-r--r--Documentation/devicetree/bindings/nvmem/fsl,layerscape-sfp.yaml63
-rw-r--r--Documentation/devicetree/bindings/nvmem/fsl,scu-ocotp.yaml56
-rw-r--r--Documentation/devicetree/bindings/nvmem/fsl,t1023-sfp.yaml37
-rw-r--r--Documentation/devicetree/bindings/nvmem/fsl,vf610-ocotp.yaml47
-rw-r--r--Documentation/devicetree/bindings/nvmem/imx-iim.yaml59
-rw-r--r--Documentation/devicetree/bindings/nvmem/imx-ocotp.yaml91
-rw-r--r--Documentation/devicetree/bindings/nvmem/ingenic,jz4780-efuse.yaml45
-rw-r--r--Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml55
-rw-r--r--Documentation/devicetree/bindings/nvmem/layouts/fixed-layout.yaml62
-rw-r--r--Documentation/devicetree/bindings/nvmem/layouts/kontron,sl28-vpd.yaml69
-rw-r--r--Documentation/devicetree/bindings/nvmem/layouts/nvmem-layout.yaml32
-rw-r--r--Documentation/devicetree/bindings/nvmem/layouts/onie,tlv-layout.yaml147
-rw-r--r--Documentation/devicetree/bindings/nvmem/layouts/u-boot,env.yaml139
-rw-r--r--Documentation/devicetree/bindings/nvmem/lpc1850-otp.txt20
-rw-r--r--Documentation/devicetree/bindings/nvmem/maxim,max77759-nvmem.yaml32
-rw-r--r--Documentation/devicetree/bindings/nvmem/mediatek,efuse.yaml110
-rw-r--r--Documentation/devicetree/bindings/nvmem/microchip,lan9662-otpc.yaml45
-rw-r--r--Documentation/devicetree/bindings/nvmem/microchip,sama7g5-otpc.yaml51
-rw-r--r--Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml49
-rw-r--r--Documentation/devicetree/bindings/nvmem/nintendo-otp.yaml44
-rw-r--r--Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml45
-rw-r--r--Documentation/devicetree/bindings/nvmem/nvmem-deprecated-cells.yaml28
-rw-r--r--Documentation/devicetree/bindings/nvmem/nvmem-provider.yaml18
-rw-r--r--Documentation/devicetree/bindings/nvmem/nvmem.txt1
-rw-r--r--Documentation/devicetree/bindings/nvmem/nvmem.yaml92
-rw-r--r--Documentation/devicetree/bindings/nvmem/nxp,lpc1857-eeprom.yaml61
-rw-r--r--Documentation/devicetree/bindings/nvmem/nxp,s32g-ocotp-nvmem.yaml45
-rw-r--r--Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml137
-rw-r--r--Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml56
-rw-r--r--Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml58
-rw-r--r--Documentation/devicetree/bindings/nvmem/renesas,rcar-efuse.yaml68
-rw-r--r--Documentation/devicetree/bindings/nvmem/renesas,rcar-otp.yaml43
-rw-r--r--Documentation/devicetree/bindings/nvmem/rmem.yaml54
-rw-r--r--Documentation/devicetree/bindings/nvmem/rockchip,otp.yaml148
-rw-r--r--Documentation/devicetree/bindings/nvmem/rockchip-efuse.yaml73
-rw-r--r--Documentation/devicetree/bindings/nvmem/snvs-lpgpr.yaml41
-rw-r--r--Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml84
-rw-r--r--Documentation/devicetree/bindings/nvmem/sprd,sc2731-efuse.yaml39
-rw-r--r--Documentation/devicetree/bindings/nvmem/sprd,ums312-efuse.yaml61
-rw-r--r--Documentation/devicetree/bindings/nvmem/st,stm32-romem.yaml73
-rw-r--r--Documentation/devicetree/bindings/nvmem/sunplus,sp7021-ocotp.yaml79
-rw-r--r--Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.yaml42
-rw-r--r--Documentation/devicetree/bindings/nvmem/zii,rave-sp-eeprom.yaml54
-rw-r--r--Documentation/devicetree/bindings/open-pic.txt98
-rw-r--r--Documentation/devicetree/bindings/openrisc/opencores/or1ksim.txt39
-rw-r--r--Documentation/devicetree/bindings/opp/allwinner,sun50i-h6-operating-points.yaml135
-rw-r--r--Documentation/devicetree/bindings/opp/operating-points-v2-ti-cpu.yaml110
-rw-r--r--Documentation/devicetree/bindings/opp/opp-v1.yaml67
-rw-r--r--Documentation/devicetree/bindings/opp/opp-v2-base.yaml247
-rw-r--r--Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml309
-rw-r--r--Documentation/devicetree/bindings/opp/opp-v2-qcom-adreno.yaml96
-rw-r--r--Documentation/devicetree/bindings/opp/opp-v2-qcom-level.yaml63
-rw-r--r--Documentation/devicetree/bindings/opp/opp-v2.yaml475
-rw-r--r--Documentation/devicetree/bindings/opp/ti,omap-opp-supply.yaml101
-rw-r--r--Documentation/devicetree/bindings/panel/ampire,am800480r3tmqwa1h.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/auo,b101aw03.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/auo,b101ean01.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/auo,b101xtn01.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/auo,b116xw03.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/auo,b133htn01.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/auo,b133xtn01.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/avic,tm070ddh03.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/chunghwa,claa101wa01a.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/chunghwa,claa101wb03.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/edt,et057090dhu.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/edt,et070080dh6.txt10
-rw-r--r--Documentation/devicetree/bindings/panel/edt,etm0700g0dh6.txt10
-rw-r--r--Documentation/devicetree/bindings/panel/foxlink,fl500wvr00-a0t.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/giantplus,gpg482739qs5.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/innolux,at043tn24.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/innolux,n116bge.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/innolux,n156bge-l21.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/innolux,zj070na-01p.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/lg,ld070wx3-sl01.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/lg,lh500wx1-sd03.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/lg,lp129qe.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/ortustech,com43h4m85ulc.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/panasonic,vvx10f004b00.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/samsung,ld9040.txt66
-rw-r--r--Documentation/devicetree/bindings/panel/samsung,ltn101nt05.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/samsung,ltn140at29-301.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/samsung,s6e8aa0.txt56
-rw-r--r--Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt49
-rw-r--r--Documentation/devicetree/bindings/panel/shelly,sca07010-bfn-lnn.txt7
-rw-r--r--Documentation/devicetree/bindings/panel/simple-panel.txt21
-rw-r--r--Documentation/devicetree/bindings/pci/83xx-512x-pci.txt40
-rw-r--r--Documentation/devicetree/bindings/pci/altr,pcie-root-port.yaml123
-rw-r--r--Documentation/devicetree/bindings/pci/amazon,al-alpine-v3-pcie.yaml71
-rw-r--r--Documentation/devicetree/bindings/pci/amd,versal2-mdb-host.yaml143
-rw-r--r--Documentation/devicetree/bindings/pci/amlogic,axg-pcie.yaml135
-rw-r--r--Documentation/devicetree/bindings/pci/apm,xgene-pcie.yaml84
-rw-r--r--Documentation/devicetree/bindings/pci/apple,pcie.yaml194
-rw-r--r--Documentation/devicetree/bindings/pci/axis,artpec6-pcie.yaml118
-rw-r--r--Documentation/devicetree/bindings/pci/baikal,bt1-pcie.yaml168
-rw-r--r--Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt63
-rw-r--r--Documentation/devicetree/bindings/pci/brcm,iproc-pcie.yaml174
-rw-r--r--Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml237
-rw-r--r--Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.yaml50
-rw-r--r--Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.yaml72
-rw-r--r--Documentation/devicetree/bindings/pci/cdns-pcie-ep.yaml24
-rw-r--r--Documentation/devicetree/bindings/pci/cdns-pcie-host.yaml37
-rw-r--r--Documentation/devicetree/bindings/pci/cdns-pcie.yaml25
-rw-r--r--Documentation/devicetree/bindings/pci/cix,sky1-pcie-host.yaml83
-rw-r--r--Documentation/devicetree/bindings/pci/designware-pcie.txt28
-rw-r--r--Documentation/devicetree/bindings/pci/faraday,ftpci100.yaml174
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,imx6q-pcie-common.yaml255
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,imx6q-pcie-ep.yaml195
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt40
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.yaml256
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,layerscape-pcie-ep.yaml99
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,layerscape-pcie.yaml182
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,mpc8xxx-pci.yaml113
-rw-r--r--Documentation/devicetree/bindings/pci/fsl,pci.txt27
-rw-r--r--Documentation/devicetree/bindings/pci/hisilicon,kirin-pcie.yaml181
-rw-r--r--Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt69
-rw-r--r--Documentation/devicetree/bindings/pci/host-generic-pci.txt100
-rw-r--r--Documentation/devicetree/bindings/pci/host-generic-pci.yaml181
-rw-r--r--Documentation/devicetree/bindings/pci/intel,ixp4xx-pci.yaml100
-rw-r--r--Documentation/devicetree/bindings/pci/intel,keembay-pcie-ep.yaml69
-rw-r--r--Documentation/devicetree/bindings/pci/intel,keembay-pcie.yaml97
-rw-r--r--Documentation/devicetree/bindings/pci/intel-gw-pcie.yaml117
-rw-r--r--Documentation/devicetree/bindings/pci/layerscape-pci.txt42
-rw-r--r--Documentation/devicetree/bindings/pci/loongson.yaml62
-rw-r--r--Documentation/devicetree/bindings/pci/marvell,armada-3700-pcie.yaml103
-rw-r--r--Documentation/devicetree/bindings/pci/marvell,armada8k-pcie.yaml100
-rw-r--r--Documentation/devicetree/bindings/pci/marvell,kirkwood-pcie.yaml280
-rw-r--r--Documentation/devicetree/bindings/pci/mbvl,gpex40-pcie.yaml173
-rw-r--r--Documentation/devicetree/bindings/pci/mediatek,mt7621-pcie.yaml177
-rw-r--r--Documentation/devicetree/bindings/pci/mediatek-pcie-cfg.yaml39
-rw-r--r--Documentation/devicetree/bindings/pci/mediatek-pcie-gen3.yaml353
-rw-r--r--Documentation/devicetree/bindings/pci/mediatek-pcie-mt7623.yaml164
-rw-r--r--Documentation/devicetree/bindings/pci/mediatek-pcie.yaml438
-rw-r--r--Documentation/devicetree/bindings/pci/microchip,pcie-host.yaml97
-rw-r--r--Documentation/devicetree/bindings/pci/mvebu-pci.txt304
-rw-r--r--Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml319
-rw-r--r--Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie.yaml380
-rw-r--r--Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt476
-rw-r--r--Documentation/devicetree/bindings/pci/nxp,s32g-pcie.yaml130
-rw-r--r--Documentation/devicetree/bindings/pci/pci-ep-bus.yaml58
-rw-r--r--Documentation/devicetree/bindings/pci/pci-ep.yaml127
-rw-r--r--Documentation/devicetree/bindings/pci/pci-keystone.txt63
-rw-r--r--Documentation/devicetree/bindings/pci/pci-rcar-gen2.txt66
-rw-r--r--Documentation/devicetree/bindings/pci/pci.txt20
-rw-r--r--Documentation/devicetree/bindings/pci/plda,xpressrich3-axi-common.yaml81
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-common.yaml135
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-ep.yaml332
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sa8255p.yaml122
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sa8775p.yaml183
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sc7280.yaml195
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sc8180x.yaml168
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sc8280xp.yaml180
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sm8150.yaml165
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sm8250.yaml181
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sm8350.yaml170
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sm8450.yaml185
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-sm8550.yaml183
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie-x1e80100.yaml173
-rw-r--r--Documentation/devicetree/bindings/pci/qcom,pcie.yaml782
-rw-r--r--Documentation/devicetree/bindings/pci/ralink,rt3883-pci.txt5
-rw-r--r--Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml118
-rw-r--r--Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml130
-rw-r--r--Documentation/devicetree/bindings/pci/rcar-pci-ep.yaml93
-rw-r--r--Documentation/devicetree/bindings/pci/rcar-pci-host.yaml139
-rw-r--r--Documentation/devicetree/bindings/pci/rcar-pci.txt47
-rw-r--r--Documentation/devicetree/bindings/pci/renesas,pci-rcar-gen2.yaml190
-rw-r--r--Documentation/devicetree/bindings/pci/renesas,r9a08g045-pcie.yaml249
-rw-r--r--Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-common.yaml69
-rw-r--r--Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie-ep.yaml70
-rw-r--r--Documentation/devicetree/bindings/pci/rockchip,rk3399-pcie.yaml133
-rw-r--r--Documentation/devicetree/bindings/pci/rockchip-dw-pcie-common.yaml132
-rw-r--r--Documentation/devicetree/bindings/pci/rockchip-dw-pcie-ep.yaml95
-rw-r--r--Documentation/devicetree/bindings/pci/rockchip-dw-pcie.yaml180
-rw-r--r--Documentation/devicetree/bindings/pci/samsung,exynos-pcie.yaml119
-rw-r--r--Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt65
-rw-r--r--Documentation/devicetree/bindings/pci/sifive,fu740-pcie.yaml120
-rw-r--r--Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml267
-rw-r--r--Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml203
-rw-r--r--Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml245
-rw-r--r--Documentation/devicetree/bindings/pci/socionext,uniphier-pcie-ep.yaml134
-rw-r--r--Documentation/devicetree/bindings/pci/socionext,uniphier-pcie.yaml121
-rw-r--r--Documentation/devicetree/bindings/pci/sophgo,sg2042-pcie-host.yaml64
-rw-r--r--Documentation/devicetree/bindings/pci/sophgo,sg2044-pcie.yaml122
-rw-r--r--Documentation/devicetree/bindings/pci/spacemit,k1-pcie-host.yaml157
-rw-r--r--Documentation/devicetree/bindings/pci/spear13xx-pcie.txt14
-rw-r--r--Documentation/devicetree/bindings/pci/st,spear1340-pcie.yaml45
-rw-r--r--Documentation/devicetree/bindings/pci/st,stm32-pcie-common.yaml33
-rw-r--r--Documentation/devicetree/bindings/pci/st,stm32-pcie-ep.yaml73
-rw-r--r--Documentation/devicetree/bindings/pci/st,stm32-pcie-host.yaml112
-rw-r--r--Documentation/devicetree/bindings/pci/starfive,jh7110-pcie.yaml126
-rw-r--r--Documentation/devicetree/bindings/pci/ti,am65-pci-ep.yaml76
-rw-r--r--Documentation/devicetree/bindings/pci/ti,am65-pci-host.yaml148
-rw-r--r--Documentation/devicetree/bindings/pci/ti,j721e-pci-ep.yaml143
-rw-r--r--Documentation/devicetree/bindings/pci/ti,j721e-pci-host.yaml206
-rw-r--r--Documentation/devicetree/bindings/pci/ti-pci.txt61
-rw-r--r--Documentation/devicetree/bindings/pci/toshiba,tc9563.yaml179
-rw-r--r--Documentation/devicetree/bindings/pci/toshiba,visconti-pcie.yaml111
-rw-r--r--Documentation/devicetree/bindings/pci/v3,v360epc-pci.yaml100
-rw-r--r--Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt15
-rw-r--r--Documentation/devicetree/bindings/pci/versatile.txt59
-rw-r--r--Documentation/devicetree/bindings/pci/versatile.yaml93
-rw-r--r--Documentation/devicetree/bindings/pci/xgene-pci.txt57
-rw-r--r--Documentation/devicetree/bindings/pci/xilinx-pcie.txt62
-rw-r--r--Documentation/devicetree/bindings/pci/xilinx-versal-cpm.yaml137
-rw-r--r--Documentation/devicetree/bindings/pci/xlnx,axi-pcie-host.yaml88
-rw-r--r--Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml156
-rw-r--r--Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml146
-rw-r--r--Documentation/devicetree/bindings/peci/nuvoton,npcm-peci.yaml56
-rw-r--r--Documentation/devicetree/bindings/peci/peci-aspeed.yaml72
-rw-r--r--Documentation/devicetree/bindings/peci/peci-controller.yaml33
-rw-r--r--Documentation/devicetree/bindings/perf/amlogic,g12-ddr-pmu.yaml54
-rw-r--r--Documentation/devicetree/bindings/perf/apm,xgene-pmu.yaml142
-rw-r--r--Documentation/devicetree/bindings/perf/arm,ccn.yaml40
-rw-r--r--Documentation/devicetree/bindings/perf/arm,cmn.yaml70
-rw-r--r--Documentation/devicetree/bindings/perf/arm,coresight-pmu.yaml39
-rw-r--r--Documentation/devicetree/bindings/perf/arm,dsu-pmu.yaml44
-rw-r--r--Documentation/devicetree/bindings/perf/arm,ni.yaml30
-rw-r--r--Documentation/devicetree/bindings/perf/arm,smmu-v3-pmcg.yaml70
-rw-r--r--Documentation/devicetree/bindings/perf/fsl-imx-ddr.yaml89
-rw-r--r--Documentation/devicetree/bindings/perf/marvell-cn10k-ddr.yaml37
-rw-r--r--Documentation/devicetree/bindings/perf/marvell-cn10k-tad.yaml63
-rw-r--r--Documentation/devicetree/bindings/perf/riscv,pmu.yaml160
-rw-r--r--Documentation/devicetree/bindings/perf/spe-pmu.yaml40
-rw-r--r--Documentation/devicetree/bindings/perf/starfive,jh8100-starlink-pmu.yaml46
-rw-r--r--Documentation/devicetree/bindings/phy/airoha,en7581-pcie-phy.yaml69
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun4i-a10-usb-phy.yaml107
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun50i-a64-usb-phy.yaml116
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun50i-h6-usb-phy.yaml107
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun50i-h6-usb3-phy.yaml49
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun5i-a13-usb-phy.yaml95
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml84
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-usb-phy.yaml121
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun8i-a23-usb-phy.yaml104
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun8i-a83t-usb-phy.yaml124
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun8i-h3-usb-phy.yaml167
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun8i-r40-usb-phy.yaml121
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun8i-v3s-usb-phy.yaml88
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,sun9i-a80-usb-phy.yaml132
-rw-r--r--Documentation/devicetree/bindings/phy/allwinner,suniv-f1c100s-usb-phy.yaml83
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,axg-mipi-dphy.yaml70
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,g12a-mipi-dphy-analog.yaml23
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,g12a-usb2-phy.yaml81
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,g12a-usb3-pcie-phy.yaml64
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,meson-axg-mipi-pcie-analog.yaml23
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,meson-axg-pcie.yaml52
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,meson-gxl-usb2-phy.yaml56
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,meson8-hdmi-tx-phy.yaml65
-rw-r--r--Documentation/devicetree/bindings/phy/amlogic,meson8b-usb2-phy.yaml64
-rw-r--r--Documentation/devicetree/bindings/phy/apm,xgene-phy.yaml169
-rw-r--r--Documentation/devicetree/bindings/phy/apm-xgene-phy.txt79
-rw-r--r--Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.yaml59
-rw-r--r--Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml62
-rw-r--r--Documentation/devicetree/bindings/phy/berlin-sata-phy.txt36
-rw-r--r--Documentation/devicetree/bindings/phy/berlin-usb-phy.txt16
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml78
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml199
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.yaml77
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,kona-usb2-phy.txt15
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,kona-usb2-phy.yaml36
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,ns2-drd-phy.yaml62
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,ns2-pcie-phy.yaml41
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,sata-phy.yaml144
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,sr-pcie-phy.yaml46
-rw-r--r--Documentation/devicetree/bindings/phy/brcm,sr-usb-combo-phy.yaml65
-rw-r--r--Documentation/devicetree/bindings/phy/calxeda-combophy.yaml50
-rw-r--r--Documentation/devicetree/bindings/phy/cdns,dphy-rx.yaml42
-rw-r--r--Documentation/devicetree/bindings/phy/cdns,dphy.yaml57
-rw-r--r--Documentation/devicetree/bindings/phy/cdns,salvo-phy.yaml58
-rw-r--r--Documentation/devicetree/bindings/phy/dm816x-phy.txt24
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,imx8-pcie-phy.yaml102
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,imx8mp-hdmi-phy.yaml62
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.yaml165
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,imx8qm-hsio.yaml164
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,imx8qm-lvds-phy.yaml61
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,lynx-28g.yaml40
-rw-r--r--Documentation/devicetree/bindings/phy/fsl,mxs-usbphy.yaml146
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml51
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,hi3670-usb3.yaml64
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,hi3798cv200-combphy.yaml56
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,hi6220-usb-phy.yaml35
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,hix5hd2-sata-phy.yaml48
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,inno-usb2-phy.yaml93
-rw-r--r--Documentation/devicetree/bindings/phy/hisilicon,phy-hi3670-pcie.yaml82
-rw-r--r--Documentation/devicetree/bindings/phy/hix5hd2-phy.txt22
-rw-r--r--Documentation/devicetree/bindings/phy/img,pistachio-usb-phy.yaml62
-rw-r--r--Documentation/devicetree/bindings/phy/ingenic,phy-usb.yaml58
-rw-r--r--Documentation/devicetree/bindings/phy/intel,combo-phy.yaml109
-rw-r--r--Documentation/devicetree/bindings/phy/intel,keembay-phy-usb.yaml44
-rw-r--r--Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml75
-rw-r--r--Documentation/devicetree/bindings/phy/intel,lgm-usb-phy.yaml58
-rw-r--r--Documentation/devicetree/bindings/phy/lantiq,ase-usb2-phy.yaml71
-rw-r--r--Documentation/devicetree/bindings/phy/lantiq,vrx200-pcie-phy.yaml95
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml57
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,armada-375-usb-cluster.yaml40
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,armada-380-comphy.yaml83
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml115
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,berlin2-sata-phy.yaml76
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,berlin2-usb-phy.yaml42
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,comphy-cp110.yaml167
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,mmp2-usb-phy.yaml37
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,mmp3-hsic-phy.yaml37
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,mmp3-usb-phy.yaml42
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,mvebu-sata-phy.yaml47
-rw-r--r--Documentation/devicetree/bindings/phy/marvell,pxa1928-usb-phy.yaml47
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml99
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml96
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,mt7621-pci-phy.yaml41
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,mt7628-usbphy.yaml74
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,mt7988-xfi-tphy.yaml80
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,mt8365-csi-rx.yaml79
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,pcie-phy.yaml75
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,tphy.yaml334
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml70
-rw-r--r--Documentation/devicetree/bindings/phy/mediatek,xsphy.yaml215
-rw-r--r--Documentation/devicetree/bindings/phy/microchip,lan966x-serdes.yaml59
-rw-r--r--Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml115
-rw-r--r--Documentation/devicetree/bindings/phy/mixel,mipi-dsi-phy.yaml93
-rw-r--r--Documentation/devicetree/bindings/phy/motorola,cpcap-usb-phy.yaml107
-rw-r--r--Documentation/devicetree/bindings/phy/motorola,mapphone-mdm6600.yaml81
-rw-r--r--Documentation/devicetree/bindings/phy/mscc,vsc7514-serdes.yaml56
-rw-r--r--Documentation/devicetree/bindings/phy/nuvoton,ma35d1-usb2-phy.yaml45
-rw-r--r--Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.yaml654
-rw-r--r--Documentation/devicetree/bindings/phy/nvidia,tegra186-xusb-padctl.yaml544
-rw-r--r--Documentation/devicetree/bindings/phy/nvidia,tegra194-xusb-padctl.yaml632
-rw-r--r--Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.yaml373
-rw-r--r--Documentation/devicetree/bindings/phy/nvidia,tegra210-xusb-padctl.yaml786
-rw-r--r--Documentation/devicetree/bindings/phy/nxp,ptn3222.yaml55
-rw-r--r--Documentation/devicetree/bindings/phy/phy-bindings.txt6
-rw-r--r--Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml166
-rw-r--r--Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml216
-rw-r--r--Documentation/devicetree/bindings/phy/phy-mvebu.txt43
-rw-r--r--Documentation/devicetree/bindings/phy/phy-rockchip-naneng-combphy.yaml153
-rw-r--r--Documentation/devicetree/bindings/phy/phy-rockchip-usbdp.yaml152
-rw-r--r--Documentation/devicetree/bindings/phy/phy-stih407-usb.txt24
-rw-r--r--Documentation/devicetree/bindings/phy/phy-stih41x-usb.txt24
-rw-r--r--Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml286
-rw-r--r--Documentation/devicetree/bindings/phy/phy-tegra194-p2u.yaml53
-rw-r--r--Documentation/devicetree/bindings/phy/qca,ar7100-usb-phy.yaml49
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,edp-phy.yaml87
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,hdmi-phy-other.yaml125
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,hdmi-phy-qmp.yaml95
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,ipq5332-uniphy-pcie-phy.yaml109
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml61
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml56
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml74
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,ipq8074-qmp-pcie-phy.yaml102
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,m31-eusb2-phy.yaml79
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-pcie-phy.yaml189
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-pcie-phy.yaml97
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-usb3-phy.yaml186
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,pcie2-phy.yaml86
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml205
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,sa8775p-dwmac-sgmii-phy.yaml60
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,sata-phy.yaml55
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml314
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml187
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml197
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb43dp-phy.yaml270
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,snps-eusb2-phy.yaml88
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml84
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,usb-hs-28nm.yaml90
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,usb-hs-phy.yaml116
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,usb-hsic-phy.yaml67
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml184
-rw-r--r--Documentation/devicetree/bindings/phy/qcom,usb-ss.yaml83
-rw-r--r--Documentation/devicetree/bindings/phy/qcom-apq8064-sata-phy.txt24
-rw-r--r--Documentation/devicetree/bindings/phy/qcom-dwc3-usb-phy.txt39
-rw-r--r--Documentation/devicetree/bindings/phy/qcom-ipq806x-sata-phy.txt23
-rw-r--r--Documentation/devicetree/bindings/phy/qcom-usb-ipq4019-phy.yaml52
-rw-r--r--Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt51
-rw-r--r--Documentation/devicetree/bindings/phy/realtek,usb2phy.yaml175
-rw-r--r--Documentation/devicetree/bindings/phy/realtek,usb3phy.yaml107
-rw-r--r--Documentation/devicetree/bindings/phy/renesas,r8a779f0-ether-serdes.yaml54
-rw-r--r--Documentation/devicetree/bindings/phy/renesas,rcar-gen2-usb-phy.yaml123
-rw-r--r--Documentation/devicetree/bindings/phy/renesas,rcar-gen3-pcie-phy.yaml53
-rw-r--r--Documentation/devicetree/bindings/phy/renesas,rzg3e-usb3-phy.yaml63
-rw-r--r--Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml162
-rw-r--r--Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml78
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml248
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,pcie3-phy.yaml116
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml73
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3228-hdmi-phy.yaml97
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3288-dp-phy.yaml41
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3399-emmc-phy.yaml64
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3399-pcie-phy.yaml45
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3399-typec-phy.yaml116
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3588-hdptx-phy.yaml120
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip,rk3588-mipi-dcphy.yaml87
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip-inno-csi-dphy.yaml141
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip-mipi-dphy-rx0.yaml73
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt37
-rw-r--r--Documentation/devicetree/bindings/phy/rockchip-usb-phy.yaml78
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,dp-video-phy.yaml40
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,exynos-hdmi-phy.yaml43
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,exynos-pcie-phy.yaml51
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,exynos2200-eusb2-phy.yaml80
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,exynos5250-sata-phy.yaml64
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,mipi-video-phy.yaml133
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml114
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,usb2-phy.yaml102
-rw-r--r--Documentation/devicetree/bindings/phy/samsung,usb3-drd-phy.yaml255
-rw-r--r--Documentation/devicetree/bindings/phy/samsung-phy.txt176
-rw-r--r--Documentation/devicetree/bindings/phy/socionext,uniphier-ahci-phy.yaml132
-rw-r--r--Documentation/devicetree/bindings/phy/socionext,uniphier-pcie-phy.yaml105
-rw-r--r--Documentation/devicetree/bindings/phy/socionext,uniphier-usb2-phy.yaml83
-rw-r--r--Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml163
-rw-r--r--Documentation/devicetree/bindings/phy/socionext,uniphier-usb3ss-phy.yaml146
-rw-r--r--Documentation/devicetree/bindings/phy/sophgo,cv1800b-usb2-phy.yaml54
-rw-r--r--Documentation/devicetree/bindings/phy/st,spear1310-miphy.yaml53
-rw-r--r--Documentation/devicetree/bindings/phy/st,stih407-usb2-phy.yaml63
-rw-r--r--Documentation/devicetree/bindings/phy/st,stm32mp25-combophy.yaml119
-rw-r--r--Documentation/devicetree/bindings/phy/st-spear-miphy.txt15
-rw-r--r--Documentation/devicetree/bindings/phy/starfive,jh7110-dphy-rx.yaml71
-rw-r--r--Documentation/devicetree/bindings/phy/starfive,jh7110-dphy-tx.yaml68
-rw-r--r--Documentation/devicetree/bindings/phy/starfive,jh7110-pcie-phy.yaml58
-rw-r--r--Documentation/devicetree/bindings/phy/starfive,jh7110-usb-phy.yaml50
-rw-r--r--Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt37
-rw-r--r--Documentation/devicetree/bindings/phy/sun9i-usb-phy.txt38
-rw-r--r--Documentation/devicetree/bindings/phy/sunplus,sp7021-usb2-phy.yaml73
-rw-r--r--Documentation/devicetree/bindings/phy/ti,da830-usb-phy.yaml53
-rw-r--r--Documentation/devicetree/bindings/phy/ti,dm8168-usb-phy.yaml58
-rw-r--r--Documentation/devicetree/bindings/phy/ti,keystone-usbphy.yaml37
-rw-r--r--Documentation/devicetree/bindings/phy/ti,omap-usb2.yaml80
-rw-r--r--Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.yaml98
-rw-r--r--Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml169
-rw-r--r--Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml259
-rw-r--r--Documentation/devicetree/bindings/phy/ti,tcan104x-can.yaml133
-rw-r--r--Documentation/devicetree/bindings/phy/ti-phy.txt56
-rw-r--r--Documentation/devicetree/bindings/phy/transmit-amplitude.yaml103
-rw-r--r--Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml105
-rw-r--r--Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt6
-rw-r--r--Documentation/devicetree/bindings/pinctrl/actions,s500-pinctrl.yaml242
-rw-r--r--Documentation/devicetree/bindings/pinctrl/actions,s700-pinctrl.yaml204
-rw-r--r--Documentation/devicetree/bindings/pinctrl/actions,s900-pinctrl.yaml219
-rw-r--r--Documentation/devicetree/bindings/pinctrl/airoha,an7583-pinctrl.yaml402
-rw-r--r--Documentation/devicetree/bindings/pinctrl/airoha,en7581-pinctrl.yaml403
-rw-r--r--Documentation/devicetree/bindings/pinctrl/allwinner,sun4i-a10-pinctrl.yaml315
-rw-r--r--Documentation/devicetree/bindings/pinctrl/allwinner,sun55i-a523-pinctrl.yaml175
-rw-r--r--Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt70
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml73
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-common.yaml64
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml71
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml75
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml80
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml82
-rw-r--r--Documentation/devicetree/bindings/pinctrl/amlogic,pinctrl-a4.yaml139
-rw-r--r--Documentation/devicetree/bindings/pinctrl/apple,pinctrl.yaml135
-rw-r--r--Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml223
-rw-r--r--Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml253
-rw-r--r--Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml537
-rw-r--r--Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt150
-rw-r--r--Documentation/devicetree/bindings/pinctrl/atmel,at91-pio4-pinctrl.txt99
-rw-r--r--Documentation/devicetree/bindings/pinctrl/atmel,at91rm9200-pinctrl.yaml184
-rw-r--r--Documentation/devicetree/bindings/pinctrl/awinic,aw9523-pinctrl.yaml139
-rw-r--r--Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt87
-rw-r--r--Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.yaml132
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.txt461
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm11351-pinctrl.yaml259
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm21664-pinctrl.yaml151
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm2712c0-pinctrl.yaml137
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt74
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.yaml120
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm4908-pinctrl.yaml73
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml151
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml172
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml135
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml97
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml214
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml225
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,cygnus-gpio.txt98
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,cygnus-pinmux.txt2
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,iproc-gpio.yaml111
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,ns-pinmux.yaml90
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,ns2-pinmux.yaml111
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,nsp-gpio.txt80
-rw-r--r--Documentation/devicetree/bindings/pinctrl/brcm,nsp-pinmux.txt79
-rw-r--r--Documentation/devicetree/bindings/pinctrl/canaan,k210-fpioa.yaml180
-rw-r--r--Documentation/devicetree/bindings/pinctrl/canaan,k230-pinctrl.yaml127
-rw-r--r--Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.yaml186
-rw-r--r--Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml114
-rw-r--r--Documentation/devicetree/bindings/pinctrl/cix,sky1-pinctrl.yaml91
-rw-r--r--Documentation/devicetree/bindings/pinctrl/cnxt,cx92755-pinctrl.txt86
-rw-r--r--Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt68
-rw-r--r--Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml158
-rw-r--r--Documentation/devicetree/bindings/pinctrl/eswin,eic7700-pinctrl.yaml156
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx-pinctrl.txt5
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx35-pinctrl.txt33
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx35-pinctrl.yaml184
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx51-pinctrl.txt32
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx53-pinctrl.txt32
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx6dl-pinctrl.txt38
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx6q-pinctrl.txt38
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx6sl-pinctrl.txt39
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx6sx-pinctrl.txt36
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.yaml113
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx7ulp-iomuxc1.yaml99
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx8m-pinctrl.yaml90
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx8ulp-pinctrl.yaml82
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imx9-pinctrl.yaml86
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imxrt1050.yaml79
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,imxrt1170.yaml77
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,mxs-pinctrl.txt127
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,scu-pinctrl.yaml74
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,vf610-iomuxc.yaml83
-rw-r--r--Documentation/devicetree/bindings/pinctrl/fsl,vf610-pinctrl.txt41
-rw-r--r--Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt14
-rw-r--r--Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt127
-rw-r--r--Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt227
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.yaml191
-rw-r--r--Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml76
-rw-r--r--Documentation/devicetree/bindings/pinctrl/intel,pinctrl-keembay.yaml136
-rw-r--r--Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-falcon.txt (renamed from Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt)0
-rw-r--r--Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt158
-rw-r--r--Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt97
-rw-r--r--Documentation/devicetree/bindings/pinctrl/loongson,ls2k-pinctrl.yaml123
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,ac5-pinctrl.yaml73
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,ap806-pinctrl.yaml61
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-370-pinctrl.txt13
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-375-pinctrl.txt10
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-38x-pinctrl.txt26
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-39x-pinctrl.txt36
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-7k-pinctrl.yaml72
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-98dx3236-pinctrl.txt46
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada-xp-pinctrl.txt52
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,armada3710-xb-pinctrl.yaml124
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,berlin2-soc-pinctrl.yaml86
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt64
-rw-r--r--Documentation/devicetree/bindings/pinctrl/marvell,orion-pinctrl.txt4
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt65xx-pinctrl.yaml181
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt6779-pinctrl.yaml248
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt6795-pinctrl.yaml228
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt6878-pinctrl.yaml211
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt6893-pinctrl.yaml193
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt7620-pinctrl.yaml298
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt7621-pinctrl.yaml261
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt7622-pinctrl.yaml401
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt76x8-pinctrl.yaml450
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt7981-pinctrl.yaml480
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt7986-pinctrl.yaml462
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt7988-pinctrl.yaml580
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8183-pinctrl.yaml239
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8186-pinctrl.yaml275
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8188-pinctrl.yaml232
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8189-pinctrl.yaml213
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8192-pinctrl.yaml184
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8195-pinctrl.yaml286
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8196-pinctrl.yaml236
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mediatek,mt8365-pinctrl.yaml230
-rw-r--r--Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt96
-rw-r--r--Documentation/devicetree/bindings/pinctrl/microchip,mcp23s08.yaml161
-rw-r--r--Documentation/devicetree/bindings/pinctrl/microchip,mpfs-pinctrl-iomux0.yaml89
-rw-r--r--Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt60
-rw-r--r--Documentation/devicetree/bindings/pinctrl/microchip,pic64gx-pinctrl-gpio2.yaml74
-rw-r--r--Documentation/devicetree/bindings/pinctrl/microchip,sparx5-sgpio.yaml168
-rw-r--r--Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.yaml127
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nuvoton,ma35d1-pinctrl.yaml178
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nuvoton,npcm7xx-pinctrl.txt216
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml215
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nuvoton,wpcm450-pinctrl.yaml162
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra-pinmux-common.yaml178
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.txt131
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra114-pinmux.yaml153
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt153
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.yaml174
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-xusb-padctl.txt12
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra186-pinmux.yaml285
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.yaml282
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt143
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.yaml110
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.txt166
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.yaml140
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-aon.yaml81
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-common.yaml52
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux.yaml142
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.txt144
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nvidia,tegra30-pinmux.yaml174
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nxp,lpc1850-scu.txt57
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nxp,lpc1850-scu.yaml79
-rw-r--r--Documentation/devicetree/bindings/pinctrl/nxp,s32g2-siul2-pinctrl.yaml123
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml173
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-atlas7.txt109
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt137
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-max77620.txt127
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt150
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-palmas.txt9
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-rk805.txt63
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt252
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml220
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt2
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-st.txt39
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl.yaml45
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml133
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt88
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.yaml110
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt179
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.yaml129
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,glymur-tlmm.yaml133
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.yaml103
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq5018-tlmm.yaml123
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq5332-tlmm.yaml118
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq5424-tlmm.yaml114
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq6018-pinctrl.yaml118
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt95
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.yaml108
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.yaml121
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,ipq9574-tlmm.yaml114
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,kaanapali-tlmm.yaml127
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,lpass-lpi-common.yaml75
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml119
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.yaml106
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,milos-tlmm.yaml133
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml101
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt90
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.yaml110
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8909-tlmm.yaml138
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt186
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.yaml152
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8917-pinctrl.yaml160
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8953-pinctrl.yaml136
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt181
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.yaml150
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt112
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.yaml165
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8976-pinctrl.yaml122
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.yaml148
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.yaml168
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.yaml157
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt217
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.yaml632
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt164
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.yaml200
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,qcm2290-tlmm.yaml122
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.yaml161
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,qcs615-tlmm.yaml124
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,qcs8300-tlmm.yaml118
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,qdu1000-tlmm.yaml119
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml131
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sar2130p-tlmm.yaml138
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.yaml144
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sc7280-lpass-lpi-pinctrl.yaml113
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml130
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sc8180x-tlmm.yaml138
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-lpass-lpi-pinctrl.yaml114
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sc8280xp-tlmm.yaml137
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdm630-pinctrl.yaml173
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdm660-lpass-lpi-pinctrl.yaml109
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdm670-tlmm.yaml112
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.yaml155
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdx55-pinctrl.yaml122
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdx65-tlmm.yaml153
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sdx75-tlmm.yaml131
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm4250-lpass-lpi-pinctrl.yaml118
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm4450-tlmm.yaml135
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm6115-lpass-lpi-pinctrl.yaml100
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm6115-tlmm.yaml138
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm6125-tlmm.yaml136
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm6350-tlmm.yaml148
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm6375-tlmm.yaml142
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm7150-tlmm.yaml146
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.yaml159
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8250-lpass-lpi-pinctrl.yaml120
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8250-pinctrl.yaml120
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8350-lpass-lpi-pinctrl.yaml102
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8350-tlmm.yaml135
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8450-lpass-lpi-pinctrl.yaml123
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8450-tlmm.yaml134
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8550-lpass-lpi-pinctrl.yaml113
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8550-tlmm.yaml148
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8650-lpass-lpi-pinctrl.yaml111
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8650-tlmm.yaml141
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,sm8750-tlmm.yaml138
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,tlmm-common.yaml101
-rw-r--r--Documentation/devicetree/bindings/pinctrl/qcom,x1e80100-tlmm.yaml137
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ralink,rt2880-pinctrl.yaml141
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ralink,rt305x-pinctrl.yaml206
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ralink,rt3352-pinctrl.yaml243
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ralink,rt3883-pinctrl.yaml261
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ralink,rt5350-pinctrl.yaml206
-rw-r--r--Documentation/devicetree/bindings/pinctrl/raspberrypi,rp1-gpio.yaml231
-rw-r--r--Documentation/devicetree/bindings/pinctrl/realtek,rtd1315e-pinctrl.yaml188
-rw-r--r--Documentation/devicetree/bindings/pinctrl/realtek,rtd1319d-pinctrl.yaml187
-rw-r--r--Documentation/devicetree/bindings/pinctrl/realtek,rtd1619b-pinctrl.yaml186
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt168
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml196
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,r9a09g077-pinctrl.yaml172
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,rza1-ports.yaml187
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.yaml98
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml226
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-poeg.yaml86
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,rzn1-pinctrl.yaml126
-rw-r--r--Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml167
-rw-r--r--Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt157
-rw-r--r--Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml194
-rw-r--r--Documentation/devicetree/bindings/pinctrl/samsung,pinctrl-gpio-bank.yaml52
-rw-r--r--Documentation/devicetree/bindings/pinctrl/samsung,pinctrl-pins-cfg.yaml80
-rw-r--r--Documentation/devicetree/bindings/pinctrl/samsung,pinctrl-wakeup-interrupt.yaml115
-rw-r--r--Documentation/devicetree/bindings/pinctrl/samsung,pinctrl.yaml417
-rw-r--r--Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt356
-rw-r--r--Documentation/devicetree/bindings/pinctrl/semtech,sx1501q.yaml251
-rw-r--r--Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.yaml84
-rw-r--r--Documentation/devicetree/bindings/pinctrl/sophgo,cv1800-pinctrl.yaml122
-rw-r--r--Documentation/devicetree/bindings/pinctrl/sophgo,sg2042-pinctrl.yaml129
-rw-r--r--Documentation/devicetree/bindings/pinctrl/spacemit,k1-pinctrl.yaml142
-rw-r--r--Documentation/devicetree/bindings/pinctrl/sprd,sc9860-pinctrl.yaml199
-rw-r--r--Documentation/devicetree/bindings/pinctrl/st,stm32-hdp.yaml187
-rw-r--r--Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml383
-rw-r--r--Documentation/devicetree/bindings/pinctrl/starfive,jh7100-pinctrl.yaml306
-rw-r--r--Documentation/devicetree/bindings/pinctrl/starfive,jh7110-aon-pinctrl.yaml124
-rw-r--r--Documentation/devicetree/bindings/pinctrl/starfive,jh7110-sys-pinctrl.yaml142
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ste,nomadik.txt7
-rw-r--r--Documentation/devicetree/bindings/pinctrl/sunplus,sp7021-pinctrl.yaml377
-rw-r--r--Documentation/devicetree/bindings/pinctrl/thead,th1520-pinctrl.yaml176
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ti,da850-pupd.txt55
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ti,iodelay.txt47
-rw-r--r--Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt13
-rw-r--r--Documentation/devicetree/bindings/pinctrl/toshiba,visconti-pinctrl.yaml97
-rw-r--r--Documentation/devicetree/bindings/pinctrl/xlnx,pinctrl-zynq.yaml210
-rw-r--r--Documentation/devicetree/bindings/pinctrl/xlnx,versal-pinctrl.yaml279
-rw-r--r--Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.txt105
-rw-r--r--Documentation/devicetree/bindings/pinctrl/xlnx,zynqmp-pinctrl.yaml353
-rw-r--r--Documentation/devicetree/bindings/pmem/pmem-region.yaml48
-rw-r--r--Documentation/devicetree/bindings/power/actions,s500-sps.yaml39
-rw-r--r--Documentation/devicetree/bindings/power/allwinner,sun20i-d1-ppu.yaml57
-rw-r--r--Documentation/devicetree/bindings/power/allwinner,sun50i-h6-prcm-ppu.yaml42
-rw-r--r--Documentation/devicetree/bindings/power/amlogic,meson-ee-pwrc.yaml184
-rw-r--r--Documentation/devicetree/bindings/power/amlogic,meson-gx-pwrc.txt63
-rw-r--r--Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml49
-rw-r--r--Documentation/devicetree/bindings/power/apple,pmgr-pwrstate.yaml90
-rw-r--r--Documentation/devicetree/bindings/power/avs/qcom,cpr.yaml161
-rw-r--r--Documentation/devicetree/bindings/power/bq2415x.txt47
-rw-r--r--Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml51
-rw-r--r--Documentation/devicetree/bindings/power/brcm,bcm63xx-power.yaml44
-rw-r--r--Documentation/devicetree/bindings/power/da9150-charger.txt26
-rw-r--r--Documentation/devicetree/bindings/power/domain-idle-state.yaml81
-rw-r--r--Documentation/devicetree/bindings/power/fsl,imx-gpc.txt59
-rw-r--r--Documentation/devicetree/bindings/power/fsl,imx-gpc.yaml148
-rw-r--r--Documentation/devicetree/bindings/power/fsl,imx-gpcv2.yaml144
-rw-r--r--Documentation/devicetree/bindings/power/fsl,scu-pd.yaml42
-rw-r--r--Documentation/devicetree/bindings/power/isp1704.txt17
-rw-r--r--Documentation/devicetree/bindings/power/ltc2941.txt27
-rw-r--r--Documentation/devicetree/bindings/power/mediatek,mt8196-gpufreq.yaml117
-rw-r--r--Documentation/devicetree/bindings/power/mediatek,power-controller.yaml268
-rw-r--r--Documentation/devicetree/bindings/power/mti,mips-cpc.yaml37
-rw-r--r--Documentation/devicetree/bindings/power/opp.txt25
-rw-r--r--Documentation/devicetree/bindings/power/pd-samsung.yaml68
-rw-r--r--Documentation/devicetree/bindings/power/power-controller.txt1
-rw-r--r--Documentation/devicetree/bindings/power/power-domain.yaml135
-rw-r--r--Documentation/devicetree/bindings/power/power_domain.txt118
-rw-r--r--Documentation/devicetree/bindings/power/qcom,kpss-acc-v2.yaml44
-rw-r--r--Documentation/devicetree/bindings/power/qcom,rpmpd.yaml218
-rw-r--r--Documentation/devicetree/bindings/power/raspberrypi,bcm2835-power.yaml42
-rw-r--r--Documentation/devicetree/bindings/power/renesas,apmu.yaml57
-rw-r--r--Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml71
-rw-r--r--Documentation/devicetree/bindings/power/renesas,sysc-rmobile.txt100
-rw-r--r--Documentation/devicetree/bindings/power/renesas,sysc-rmobile.yaml121
-rw-r--r--Documentation/devicetree/bindings/power/reset/apple,smc-reboot.yaml40
-rw-r--r--Documentation/devicetree/bindings/power/reset/atmel,at91sam9260-shdwc.yaml82
-rw-r--r--Documentation/devicetree/bindings/power/reset/atmel,sama5d2-shdwc.yaml122
-rw-r--r--Documentation/devicetree/bindings/power/reset/axxia-reset.txt (renamed from Documentation/devicetree/bindings/power_supply/axxia-reset.txt)0
-rw-r--r--Documentation/devicetree/bindings/power/reset/brcm,bcm21664-resetmgr.yaml31
-rw-r--r--Documentation/devicetree/bindings/power/reset/gemini-poweroff.txt17
-rw-r--r--Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml65
-rw-r--r--Documentation/devicetree/bindings/power/reset/gpio-restart.yaml79
-rw-r--r--Documentation/devicetree/bindings/power/reset/keystone-reset.txt4
-rw-r--r--Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt4
-rw-r--r--Documentation/devicetree/bindings/power/reset/nvmem-reboot-mode.yaml54
-rw-r--r--Documentation/devicetree/bindings/power/reset/ocelot-reset.txt19
-rw-r--r--Documentation/devicetree/bindings/power/reset/qcom,pon.yaml154
-rw-r--r--Documentation/devicetree/bindings/power/reset/qcom,pshold.yaml35
-rw-r--r--Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt (renamed from Documentation/devicetree/bindings/power_supply/qnap-poweroff.txt)3
-rw-r--r--Documentation/devicetree/bindings/power/reset/reboot-mode.yaml49
-rw-r--r--Documentation/devicetree/bindings/power/reset/regulator-poweroff.yaml37
-rw-r--r--Documentation/devicetree/bindings/power/reset/restart-handler.yaml30
-rw-r--r--Documentation/devicetree/bindings/power/reset/restart-poweroff.txt (renamed from Documentation/devicetree/bindings/power_supply/restart-poweroff.txt)0
-rw-r--r--Documentation/devicetree/bindings/power/reset/st-reset.txt6
-rw-r--r--Documentation/devicetree/bindings/power/reset/syscon-poweroff.txt23
-rw-r--r--Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml66
-rw-r--r--Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml57
-rw-r--r--Documentation/devicetree/bindings/power/reset/syscon-reboot.txt23
-rw-r--r--Documentation/devicetree/bindings/power/reset/syscon-reboot.yaml98
-rw-r--r--Documentation/devicetree/bindings/power/reset/toradex,smarc-ec.yaml52
-rw-r--r--Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.yaml82
-rw-r--r--Documentation/devicetree/bindings/power/rockchip,power-controller.yaml262
-rw-r--r--Documentation/devicetree/bindings/power/rockchip-io-domain.txt83
-rw-r--r--Documentation/devicetree/bindings/power/rockchip-io-domain.yaml414
-rw-r--r--Documentation/devicetree/bindings/power/rx51-battery.txt25
-rw-r--r--Documentation/devicetree/bindings/power/starfive,jh7110-pmu.yaml45
-rw-r--r--Documentation/devicetree/bindings/power/supply/adc-battery.yaml70
-rw-r--r--Documentation/devicetree/bindings/power/supply/battery.yaml184
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq2415x.yaml97
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq24190.yaml100
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq24257.yaml124
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq24735.yaml89
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq2515x.yaml92
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq256xx.yaml126
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq25890.yaml127
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq25980.yaml112
-rw-r--r--Documentation/devicetree/bindings/power/supply/bq27xxx.yaml125
-rw-r--r--Documentation/devicetree/bindings/power/supply/charger-manager.yaml217
-rw-r--r--Documentation/devicetree/bindings/power/supply/cpcap-battery.yaml87
-rw-r--r--Documentation/devicetree/bindings/power/supply/cpcap-charger.yaml106
-rw-r--r--Documentation/devicetree/bindings/power/supply/cw2015_battery.yaml77
-rw-r--r--Documentation/devicetree/bindings/power/supply/dlg,da9150-charger.yaml52
-rw-r--r--Documentation/devicetree/bindings/power/supply/dlg,da9150-fuel-gauge.yaml51
-rw-r--r--Documentation/devicetree/bindings/power/supply/gpio-charger.yaml100
-rw-r--r--Documentation/devicetree/bindings/power/supply/ingenic,battery.yaml61
-rw-r--r--Documentation/devicetree/bindings/power/supply/isp1704.yaml42
-rw-r--r--Documentation/devicetree/bindings/power/supply/lego,ev3-battery.yaml55
-rw-r--r--Documentation/devicetree/bindings/power/supply/lltc,lt3651-charger.yaml44
-rw-r--r--Documentation/devicetree/bindings/power/supply/lltc,ltc294x.yaml66
-rw-r--r--Documentation/devicetree/bindings/power/supply/ltc4162-l.yaml73
-rw-r--r--Documentation/devicetree/bindings/power/supply/max77650-charger.yaml37
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,ds2760.yaml43
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max14577.yaml84
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max14656.yaml45
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml128
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max17042.yaml84
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max17201.yaml58
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max77693.yaml70
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max77705.yaml50
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max77976.yaml44
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max8903.yaml67
-rw-r--r--Documentation/devicetree/bindings/power/supply/maxim,max8971.yaml68
-rw-r--r--Documentation/devicetree/bindings/power/supply/mediatek,mt6370-charger.yaml96
-rw-r--r--Documentation/devicetree/bindings/power/supply/microchip,ucs1002.yaml51
-rw-r--r--Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml38
-rw-r--r--Documentation/devicetree/bindings/power/supply/mt6360_charger.yaml47
-rw-r--r--Documentation/devicetree/bindings/power/supply/nokia,n900-battery.yaml49
-rw-r--r--Documentation/devicetree/bindings/power/supply/olpc-battery.yaml27
-rw-r--r--Documentation/devicetree/bindings/power/supply/pegatron,chagall-ec.yaml49
-rw-r--r--Documentation/devicetree/bindings/power/supply/power-supply.yaml27
-rw-r--r--Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml83
-rw-r--r--Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml128
-rw-r--r--Documentation/devicetree/bindings/power/supply/qcom,pm8941-charger.yaml178
-rw-r--r--Documentation/devicetree/bindings/power/supply/qcom,pm8941-coincell.yaml67
-rw-r--r--Documentation/devicetree/bindings/power/supply/qcom,pmi8998-charger.yaml82
-rw-r--r--Documentation/devicetree/bindings/power/supply/richtek,rt5033-battery.yaml54
-rw-r--r--Documentation/devicetree/bindings/power/supply/richtek,rt5033-charger.yaml67
-rw-r--r--Documentation/devicetree/bindings/power/supply/richtek,rt9455.yaml90
-rw-r--r--Documentation/devicetree/bindings/power/supply/richtek,rt9467.yaml82
-rw-r--r--Documentation/devicetree/bindings/power/supply/richtek,rt9471.yaml73
-rw-r--r--Documentation/devicetree/bindings/power/supply/richtek,rt9756.yaml72
-rw-r--r--Documentation/devicetree/bindings/power/supply/rohm,bd99954.yaml164
-rw-r--r--Documentation/devicetree/bindings/power/supply/samsung,battery.yaml56
-rw-r--r--Documentation/devicetree/bindings/power/supply/sbs,sbs-battery.yaml84
-rw-r--r--Documentation/devicetree/bindings/power/supply/sbs,sbs-charger.yaml55
-rw-r--r--Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml111
-rw-r--r--Documentation/devicetree/bindings/power/supply/sc2731-charger.yaml33
-rw-r--r--Documentation/devicetree/bindings/power/supply/sc27xx-fg.yaml73
-rw-r--r--Documentation/devicetree/bindings/power/supply/st,stc3117.yaml74
-rw-r--r--Documentation/devicetree/bindings/power/supply/stericsson,ab8500-btemp.yaml75
-rw-r--r--Documentation/devicetree/bindings/power/supply/stericsson,ab8500-chargalg.yaml39
-rw-r--r--Documentation/devicetree/bindings/power/supply/stericsson,ab8500-charger.yaml124
-rw-r--r--Documentation/devicetree/bindings/power/supply/stericsson,ab8500-fg.yaml79
-rw-r--r--Documentation/devicetree/bindings/power/supply/summit,smb347-charger.yaml181
-rw-r--r--Documentation/devicetree/bindings/power/supply/ti,lp8727.yaml90
-rw-r--r--Documentation/devicetree/bindings/power/supply/ti,twl6030-charger.yaml48
-rw-r--r--Documentation/devicetree/bindings/power/supply/tps65090-charger.yaml36
-rw-r--r--Documentation/devicetree/bindings/power/supply/tps65217-charger.yaml43
-rw-r--r--Documentation/devicetree/bindings/power/supply/twl4030-charger.yaml68
-rw-r--r--Documentation/devicetree/bindings/power/supply/x-powers,axp20x-ac-power-supply.yaml35
-rw-r--r--Documentation/devicetree/bindings/power/supply/x-powers,axp20x-battery-power-supply.yaml51
-rw-r--r--Documentation/devicetree/bindings/power/supply/x-powers,axp20x-usb-power-supply.yaml104
-rw-r--r--Documentation/devicetree/bindings/power/ti-smartreflex.txt47
-rw-r--r--Documentation/devicetree/bindings/power/twl-charger.txt20
-rw-r--r--Documentation/devicetree/bindings/power/wakeup-source.txt73
-rw-r--r--Documentation/devicetree/bindings/power_supply/ab8500/btemp.txt16
-rw-r--r--Documentation/devicetree/bindings/power_supply/ab8500/chargalg.txt16
-rw-r--r--Documentation/devicetree/bindings/power_supply/ab8500/charger.txt25
-rw-r--r--Documentation/devicetree/bindings/power_supply/ab8500/fg.txt58
-rw-r--r--Documentation/devicetree/bindings/power_supply/charger-manager.txt81
-rw-r--r--Documentation/devicetree/bindings/power_supply/gpio-charger.txt27
-rw-r--r--Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt23
-rw-r--r--Documentation/devicetree/bindings/power_supply/lp8727_charger.txt44
-rw-r--r--Documentation/devicetree/bindings/power_supply/max17042_battery.txt18
-rw-r--r--Documentation/devicetree/bindings/power_supply/max8925_batter.txt18
-rw-r--r--Documentation/devicetree/bindings/power_supply/msm-poweroff.txt17
-rw-r--r--Documentation/devicetree/bindings/power_supply/olpc_battery.txt5
-rw-r--r--Documentation/devicetree/bindings/power_supply/power_supply.txt23
-rw-r--r--Documentation/devicetree/bindings/power_supply/sbs_sbs-battery.txt23
-rw-r--r--Documentation/devicetree/bindings/power_supply/ti,bq24735.txt32
-rw-r--r--Documentation/devicetree/bindings/power_supply/tps65090.txt17
-rw-r--r--Documentation/devicetree/bindings/powerpc/4xx/akebono.txt2
-rw-r--r--Documentation/devicetree/bindings/powerpc/4xx/emac.txt148
-rw-r--r--Documentation/devicetree/bindings/powerpc/4xx/hsta.txt1
-rw-r--r--Documentation/devicetree/bindings/powerpc/4xx/ppc440spe-adma.txt2
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/board.txt102
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/cache_sram.txt20
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/gpio.txt38
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/network.txt43
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe.txt115
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/cpus.txt8
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/dcsr.txt11
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/diu.txt2
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/dma.txt208
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/ecm.txt4
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/fman.txt604
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/gtm.txt31
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt12
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt23
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mcm.txt4
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mcu-mpc8349emitx.txt17
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mem-ctrlr.txt27
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mpc5121-psc.txt28
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mpc512x_lpbfifo.txt21
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt4
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/mpic.txt231
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt116
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/pamu.txt2
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/pmc.txt63
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/pmc.yaml152
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/raideng.txt2
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/scfg.txt18
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/srio-rmu.txt4
-rw-r--r--Documentation/devicetree/bindings/powerpc/fsl/srio.txt3
-rw-r--r--Documentation/devicetree/bindings/powerpc/ibm,powerpc-cpu-features.txt248
-rw-r--r--Documentation/devicetree/bindings/powerpc/ibm,vas.txt22
-rw-r--r--Documentation/devicetree/bindings/powerpc/nintendo/gamecube.txt2
-rw-r--r--Documentation/devicetree/bindings/powerpc/nintendo/wii.txt24
-rw-r--r--Documentation/devicetree/bindings/powerpc/opal/oppanel-opal.txt14
-rw-r--r--Documentation/devicetree/bindings/powerpc/opal/power-mgt.txt118
-rw-r--r--Documentation/devicetree/bindings/powerpc/opal/sensor-groups.txt27
-rw-r--r--Documentation/devicetree/bindings/powerpc/sleep.yaml47
-rw-r--r--Documentation/devicetree/bindings/pps/pps-gpio.txt20
-rw-r--r--Documentation/devicetree/bindings/pps/pps-gpio.yaml49
-rw-r--r--Documentation/devicetree/bindings/ptp/brcm,ptp-dte.txt19
-rw-r--r--Documentation/devicetree/bindings/ptp/fsl,ptp.yaml156
-rw-r--r--Documentation/devicetree/bindings/ptp/nxp,ptp-netc.yaml63
-rw-r--r--Documentation/devicetree/bindings/ptp/ptp-idt82p33.yaml45
-rw-r--r--Documentation/devicetree/bindings/ptp/ptp-idtcm.yaml69
-rw-r--r--Documentation/devicetree/bindings/ptp/ptp-ines.txt35
-rw-r--r--Documentation/devicetree/bindings/ptp/timestamper.txt42
-rw-r--r--Documentation/devicetree/bindings/pwm/adi,axi-pwmgen.yaml57
-rw-r--r--Documentation/devicetree/bindings/pwm/airoha,en7581-pwm.yaml34
-rw-r--r--Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml115
-rw-r--r--Documentation/devicetree/bindings/pwm/apple,s5l-fpwm.yaml52
-rw-r--r--Documentation/devicetree/bindings/pwm/argon40,fan-hat.yaml48
-rw-r--r--Documentation/devicetree/bindings/pwm/atmel,at91sam-pwm.yaml52
-rw-r--r--Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml35
-rw-r--r--Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt29
-rw-r--r--Documentation/devicetree/bindings/pwm/atmel-pwm.txt33
-rw-r--r--Documentation/devicetree/bindings/pwm/atmel-tcb-pwm.txt16
-rw-r--r--Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.yaml42
-rw-r--r--Documentation/devicetree/bindings/pwm/brcm,iproc-pwm.yaml45
-rw-r--r--Documentation/devicetree/bindings/pwm/brcm,kona-pwm.txt21
-rw-r--r--Documentation/devicetree/bindings/pwm/brcm,kona-pwm.yaml51
-rw-r--r--Documentation/devicetree/bindings/pwm/cirrus,clps711x-pwm.txt5
-rw-r--r--Documentation/devicetree/bindings/pwm/cirrus,ep9301-pwm.yaml53
-rw-r--r--Documentation/devicetree/bindings/pwm/clk-pwm.yaml46
-rw-r--r--Documentation/devicetree/bindings/pwm/fsl,vf610-ftm-pwm.yaml97
-rw-r--r--Documentation/devicetree/bindings/pwm/google,cros-ec-pwm.yaml57
-rw-r--r--Documentation/devicetree/bindings/pwm/img-pwm.txt2
-rw-r--r--Documentation/devicetree/bindings/pwm/imx-pwm.txt27
-rw-r--r--Documentation/devicetree/bindings/pwm/imx-pwm.yaml86
-rw-r--r--Documentation/devicetree/bindings/pwm/imx-tpm-pwm.yaml66
-rw-r--r--Documentation/devicetree/bindings/pwm/intel,keembay-pwm.yaml46
-rw-r--r--Documentation/devicetree/bindings/pwm/intel,lgm-pwm.yaml47
-rw-r--r--Documentation/devicetree/bindings/pwm/iqs620a-pwm.yaml34
-rw-r--r--Documentation/devicetree/bindings/pwm/kontron,sl28cpld-pwm.yaml35
-rw-r--r--Documentation/devicetree/bindings/pwm/loongson,ls7a-pwm.yaml67
-rw-r--r--Documentation/devicetree/bindings/pwm/lpc32xx-pwm.txt12
-rw-r--r--Documentation/devicetree/bindings/pwm/marvell,berlin-pwm.yaml44
-rw-r--r--Documentation/devicetree/bindings/pwm/marvell,pxa-pwm.yaml71
-rw-r--r--Documentation/devicetree/bindings/pwm/mediatek,mt2712-pwm.yaml100
-rw-r--r--Documentation/devicetree/bindings/pwm/mediatek,pwm-disp.yaml81
-rw-r--r--Documentation/devicetree/bindings/pwm/microchip,corepwm.yaml83
-rw-r--r--Documentation/devicetree/bindings/pwm/mxs-pwm.txt17
-rw-r--r--Documentation/devicetree/bindings/pwm/mxs-pwm.yaml53
-rw-r--r--Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.txt27
-rw-r--r--Documentation/devicetree/bindings/pwm/nvidia,tegra20-pwm.yaml95
-rw-r--r--Documentation/devicetree/bindings/pwm/nxp,lpc1850-sct-pwm.yaml54
-rw-r--r--Documentation/devicetree/bindings/pwm/nxp,lpc3220-pwm.yaml44
-rw-r--r--Documentation/devicetree/bindings/pwm/nxp,mc33xs2410.yaml118
-rw-r--r--Documentation/devicetree/bindings/pwm/nxp,pca9685-pwm.txt2
-rw-r--r--Documentation/devicetree/bindings/pwm/opencores,pwm.yaml56
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-amlogic.yaml181
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt30
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-bcm2835.yaml42
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt52
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-gpio.yaml46
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-hibvt.txt23
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-lp3943.txt2
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-nexus-node.yaml65
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-rockchip.txt20
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml108
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-samsung.txt51
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-samsung.yaml130
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-sifive.yaml72
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-st.txt8
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-sun4i.txt20
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-tiecap.txt29
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-tiecap.yaml63
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.txt29
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.yaml64
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm-tipwmss.txt33
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm.txt11
-rw-r--r--Documentation/devicetree/bindings/pwm/pwm.yaml36
-rw-r--r--Documentation/devicetree/bindings/pwm/pxa-pwm.txt30
-rw-r--r--Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.yaml99
-rw-r--r--Documentation/devicetree/bindings/pwm/renesas,rzg2l-gpt.yaml378
-rw-r--r--Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt28
-rw-r--r--Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.yaml94
-rw-r--r--Documentation/devicetree/bindings/pwm/snps,dw-apb-timers-pwm2.yaml67
-rw-r--r--Documentation/devicetree/bindings/pwm/sophgo,sg2042-pwm.yaml60
-rw-r--r--Documentation/devicetree/bindings/pwm/spear-pwm.txt2
-rw-r--r--Documentation/devicetree/bindings/pwm/sprd,ums512-pwm.yaml66
-rw-r--r--Documentation/devicetree/bindings/pwm/st,stmpe-pwm.txt18
-rw-r--r--Documentation/devicetree/bindings/pwm/sunplus,sp7021-pwm.yaml42
-rw-r--r--Documentation/devicetree/bindings/pwm/thead,th1520-pwm.yaml48
-rw-r--r--Documentation/devicetree/bindings/pwm/ti,omap-dmtimer-pwm.yaml59
-rw-r--r--Documentation/devicetree/bindings/pwm/ti,twl-pwm.txt17
-rw-r--r--Documentation/devicetree/bindings/pwm/ti,twl-pwmled.txt17
-rw-r--r--Documentation/devicetree/bindings/pwm/toshiba,pwm-visconti.yaml45
-rw-r--r--Documentation/devicetree/bindings/pwm/via,vt8500-pwm.yaml43
-rw-r--r--Documentation/devicetree/bindings/pwm/vt8500-pwm.txt18
-rw-r--r--Documentation/devicetree/bindings/regmap/regmap.txt56
-rw-r--r--Documentation/devicetree/bindings/regulator/88pg86x.txt22
-rw-r--r--Documentation/devicetree/bindings/regulator/act8865-regulator.txt92
-rw-r--r--Documentation/devicetree/bindings/regulator/active-semi,act8600.yaml139
-rw-r--r--Documentation/devicetree/bindings/regulator/active-semi,act8846.yaml167
-rw-r--r--Documentation/devicetree/bindings/regulator/active-semi,act8865.yaml158
-rw-r--r--Documentation/devicetree/bindings/regulator/active-semi,act8945a.yaml271
-rw-r--r--Documentation/devicetree/bindings/regulator/adi,adp5055-regulator.yaml157
-rw-r--r--Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml50
-rw-r--r--Documentation/devicetree/bindings/regulator/adi,max77541-regulator.yaml38
-rw-r--r--Documentation/devicetree/bindings/regulator/adi,max77857.yaml86
-rw-r--r--Documentation/devicetree/bindings/regulator/allwinner,sun20i-d1-system-ldos.yaml37
-rw-r--r--Documentation/devicetree/bindings/regulator/anatop-regulator.txt37
-rw-r--r--Documentation/devicetree/bindings/regulator/anatop-regulator.yaml93
-rw-r--r--Documentation/devicetree/bindings/regulator/awinic,aw37503.yaml78
-rw-r--r--Documentation/devicetree/bindings/regulator/brcm,bcm59054.yaml56
-rw-r--r--Documentation/devicetree/bindings/regulator/brcm,bcm59056.yaml51
-rw-r--r--Documentation/devicetree/bindings/regulator/cpcap-regulator.txt35
-rw-r--r--Documentation/devicetree/bindings/regulator/da9210.txt21
-rw-r--r--Documentation/devicetree/bindings/regulator/da9211.txt68
-rw-r--r--Documentation/devicetree/bindings/regulator/dlg,da9121.yaml213
-rw-r--r--Documentation/devicetree/bindings/regulator/dlg,da9210.yaml52
-rw-r--r--Documentation/devicetree/bindings/regulator/dlg,da9211.yaml103
-rw-r--r--Documentation/devicetree/bindings/regulator/dlg,slg51000.yaml132
-rw-r--r--Documentation/devicetree/bindings/regulator/fan53555.txt23
-rw-r--r--Documentation/devicetree/bindings/regulator/fcs,fan53555.yaml73
-rw-r--r--Documentation/devicetree/bindings/regulator/fitipower,fp9931.yaml110
-rw-r--r--Documentation/devicetree/bindings/regulator/fixed-regulator.txt34
-rw-r--r--Documentation/devicetree/bindings/regulator/fixed-regulator.yaml160
-rw-r--r--Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml54
-rw-r--r--Documentation/devicetree/bindings/regulator/gpio-regulator.txt41
-rw-r--r--Documentation/devicetree/bindings/regulator/gpio-regulator.yaml122
-rw-r--r--Documentation/devicetree/bindings/regulator/hisilicon,hi655x-regulator.txt29
-rw-r--r--Documentation/devicetree/bindings/regulator/infineon,ir38060.yaml45
-rw-r--r--Documentation/devicetree/bindings/regulator/lltc,ltc3676.yaml167
-rw-r--r--Documentation/devicetree/bindings/regulator/lm363x-regulator.txt108
-rw-r--r--Documentation/devicetree/bindings/regulator/lp872x.txt5
-rw-r--r--Documentation/devicetree/bindings/regulator/max77650-regulator.yaml35
-rw-r--r--Documentation/devicetree/bindings/regulator/max77802.txt88
-rw-r--r--Documentation/devicetree/bindings/regulator/max8660.txt47
-rw-r--r--Documentation/devicetree/bindings/regulator/max8660.yaml73
-rw-r--r--Documentation/devicetree/bindings/regulator/max8893.yaml88
-rw-r--r--Documentation/devicetree/bindings/regulator/max8952.txt52
-rw-r--r--Documentation/devicetree/bindings/regulator/max8973-regulator.txt21
-rw-r--r--Documentation/devicetree/bindings/regulator/max8997-regulator.txt146
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max14577.yaml78
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max20086.yaml107
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max20411.yaml58
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max77686.yaml83
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max77693.yaml60
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max77802.yaml86
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max77826.yaml67
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max77838.yaml68
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max77843.yaml65
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max8952.yaml109
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max8973.yaml141
-rw-r--r--Documentation/devicetree/bindings/regulator/maxim,max8997.yaml446
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6316b-regulator.yaml76
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6316c-regulator.yaml76
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6316d-regulator.yaml75
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6331-regulator.yaml280
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6332-regulator.yaml119
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6357-regulator.yaml284
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml250
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6363-regulator.yaml146
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6397-regulator.yaml238
-rw-r--r--Documentation/devicetree/bindings/regulator/mediatek,mt6873-dvfsrc-regulator.yaml45
-rw-r--r--Documentation/devicetree/bindings/regulator/microchip,mcp16502.yaml200
-rw-r--r--Documentation/devicetree/bindings/regulator/mp8859.txt22
-rw-r--r--Documentation/devicetree/bindings/regulator/mps,mp5416.yaml78
-rw-r--r--Documentation/devicetree/bindings/regulator/mps,mp886x.yaml63
-rw-r--r--Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml59
-rw-r--r--Documentation/devicetree/bindings/regulator/mps,mpq7920.yaml117
-rw-r--r--Documentation/devicetree/bindings/regulator/mps,mpq7932.yaml68
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6311-regulator.txt35
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6315-regulator.yaml68
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6323-regulator.txt237
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6359-regulator.yaml385
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6360-regulator.yaml107
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6380-regulator.txt89
-rw-r--r--Documentation/devicetree/bindings/regulator/mt6397-regulator.txt217
-rw-r--r--Documentation/devicetree/bindings/regulator/nvidia,tegra-regulators-coupling.txt65
-rw-r--r--Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml288
-rw-r--r--Documentation/devicetree/bindings/regulator/nxp,pf0900.yaml163
-rw-r--r--Documentation/devicetree/bindings/regulator/nxp,pf5300.yaml54
-rw-r--r--Documentation/devicetree/bindings/regulator/nxp,pf8x00-regulator.yaml190
-rw-r--r--Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml87
-rw-r--r--Documentation/devicetree/bindings/regulator/palmas-pmic.txt9
-rw-r--r--Documentation/devicetree/bindings/regulator/pbias-regulator.txt7
-rw-r--r--Documentation/devicetree/bindings/regulator/pfuze100.txt299
-rw-r--r--Documentation/devicetree/bindings/regulator/pfuze100.yaml199
-rw-r--r--Documentation/devicetree/bindings/regulator/pv88060.txt124
-rw-r--r--Documentation/devicetree/bindings/regulator/pv88080.txt62
-rw-r--r--Documentation/devicetree/bindings/regulator/pv88090.txt65
-rw-r--r--Documentation/devicetree/bindings/regulator/pwm-regulator.txt27
-rw-r--r--Documentation/devicetree/bindings/regulator/pwm-regulator.yaml127
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,qca6390-pmu.yaml244
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,rpm-regulator.yaml128
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml609
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,sdm845-refgen-regulator.yaml60
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml145
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml439
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml58
-rw-r--r--Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml106
-rw-r--r--Documentation/devicetree/bindings/regulator/raspberrypi,7inch-touchscreen-panel-regulator-v2.yaml61
-rw-r--r--Documentation/devicetree/bindings/regulator/raspberrypi,7inch-touchscreen-panel-regulator.yaml44
-rw-r--r--Documentation/devicetree/bindings/regulator/regulator-max77620.txt222
-rw-r--r--Documentation/devicetree/bindings/regulator/regulator-output.yaml39
-rw-r--r--Documentation/devicetree/bindings/regulator/regulator.txt93
-rw-r--r--Documentation/devicetree/bindings/regulator/regulator.yaml307
-rw-r--r--Documentation/devicetree/bindings/regulator/renesas,raa215300.yaml85
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt4801-regulator.yaml89
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt4803.yaml68
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt4831-regulator.yaml36
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt5133.yaml178
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt5190a-regulator.yaml141
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt5739.yaml73
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt5759-regulator.yaml90
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt6160-regulator.yaml61
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt6190.yaml79
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rt6245-regulator.yaml87
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rtmv20-regulator.yaml160
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rtq2134-regulator.yaml106
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rtq2208.yaml207
-rw-r--r--Documentation/devicetree/bindings/regulator/richtek,rtq6752-regulator.yaml77
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml117
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml105
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.yaml161
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml156
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd9576-regulator.yaml40
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd96801-regulator.yaml63
-rw-r--r--Documentation/devicetree/bindings/regulator/rohm,bd96802-regulator.yaml44
-rw-r--r--Documentation/devicetree/bindings/regulator/s5m8767-regulator.txt163
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mpa01.yaml62
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mps11.yaml44
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mps13.yaml44
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mps14.yaml61
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mps15.yaml44
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mpu02.yaml44
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s2mpu05.yaml47
-rw-r--r--Documentation/devicetree/bindings/regulator/samsung,s5m8767.yaml100
-rw-r--r--Documentation/devicetree/bindings/regulator/silergy,sy8106a.yaml52
-rw-r--r--Documentation/devicetree/bindings/regulator/silergy,sy8824x.yaml45
-rw-r--r--Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml47
-rw-r--r--Documentation/devicetree/bindings/regulator/siliconmitus,sm5703-regulator.yaml49
-rw-r--r--Documentation/devicetree/bindings/regulator/socionext,uniphier-regulator.yaml99
-rw-r--r--Documentation/devicetree/bindings/regulator/sprd,sc2731-regulator.yaml46
-rw-r--r--Documentation/devicetree/bindings/regulator/st,stm32-booster.yaml47
-rw-r--r--Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml57
-rw-r--r--Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.yaml68
-rw-r--r--Documentation/devicetree/bindings/regulator/ti,tps62360.yaml98
-rw-r--r--Documentation/devicetree/bindings/regulator/ti,tps62864.yaml63
-rw-r--r--Documentation/devicetree/bindings/regulator/ti,tps62870.yaml52
-rw-r--r--Documentation/devicetree/bindings/regulator/ti,tps65132.yaml87
-rw-r--r--Documentation/devicetree/bindings/regulator/ti,tps65219.yaml198
-rw-r--r--Documentation/devicetree/bindings/regulator/ti-abb-regulator.txt12
-rw-r--r--Documentation/devicetree/bindings/regulator/tps62360-regulator.txt44
-rw-r--r--Documentation/devicetree/bindings/regulator/tps65023.txt60
-rw-r--r--Documentation/devicetree/bindings/regulator/tps65090.txt2
-rw-r--r--Documentation/devicetree/bindings/regulator/tps65218.txt92
-rw-r--r--Documentation/devicetree/bindings/regulator/twl-regulator.txt67
-rw-r--r--Documentation/devicetree/bindings/regulator/vctrl-regulator.yaml80
-rw-r--r--Documentation/devicetree/bindings/regulator/vexpress.txt2
-rw-r--r--Documentation/devicetree/bindings/regulator/vqmmc-ipq4019-regulator.yaml43
-rw-r--r--Documentation/devicetree/bindings/regulator/wlf,arizona.yaml41
-rw-r--r--Documentation/devicetree/bindings/remoteproc/amlogic,meson-mx-ao-arc.yaml87
-rw-r--r--Documentation/devicetree/bindings/remoteproc/fsl,imx-rproc.yaml150
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ingenic,vpu.yaml77
-rw-r--r--Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml262
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml218
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,glink-edge.yaml97
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,glink-rpm-edge.yaml98
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,milos-pas.yaml198
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,msm8916-mss-pil.yaml345
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml392
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,pas-common.yaml88
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,pil-info.yaml46
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt102
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,qcs404-cdsp-pil.yaml164
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,qcs404-pas.yaml95
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,rpm-proc.yaml171
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sa8775p-pas.yaml176
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sc7180-mss-pil.yaml247
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml186
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sc7280-adsp-pil.yaml195
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sc7280-mss-pil.yaml268
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sc7280-wpss-pil.yaml211
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sc8280xp-pas.yaml152
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sdm845-adsp-pil.yaml163
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sdx55-pas.yaml110
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sm6115-pas.yaml157
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sm6350-pas.yaml168
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sm6375-pas.yaml145
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sm8150-pas.yaml196
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sm8350-pas.yaml192
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml289
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,smd-edge.yaml118
-rw-r--r--Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.yaml321
-rw-r--r--Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml65
-rw-r--r--Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml196
-rw-r--r--Documentation/devicetree/bindings/remoteproc/st-rproc.txt41
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,davinci-rproc.txt77
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,k3-dsp-rproc.yaml211
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,k3-m4f-rproc.yaml125
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,k3-r5f-rproc.yaml345
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,keystone-rproc.txt182
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,omap-remoteproc.yaml331
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,pru-consumer.yaml60
-rw-r--r--Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml243
-rw-r--r--Documentation/devicetree/bindings/remoteproc/wkup_m3_rproc.txt52
-rw-r--r--Documentation/devicetree/bindings/remoteproc/xlnx,zynqmp-r5fss.yaml371
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/google,open-dice.yaml46
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/nvidia,tegra210-emc-table.yaml31
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/nvidia,tegra264-bpmp-shmem.yaml48
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/phram.yaml47
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/qcom,cmd-db.yaml46
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml66
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/ramoops.yaml144
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt134
-rw-r--r--Documentation/devicetree/bindings/reserved-memory/xen,shared-memory.txt24
-rw-r--r--Documentation/devicetree/bindings/reset/allwinner,sun6i-a31-clock-reset.yaml68
-rw-r--r--Documentation/devicetree/bindings/reset/allwinner,sunxi-clock-reset.txt21
-rw-r--r--Documentation/devicetree/bindings/reset/altr,rst-mgr.yaml55
-rw-r--r--Documentation/devicetree/bindings/reset/amlogic,meson-axg-audio-arb.yaml56
-rw-r--r--Documentation/devicetree/bindings/reset/amlogic,meson-reset.yaml49
-rw-r--r--Documentation/devicetree/bindings/reset/atmel,at91sam9260-reset.yaml75
-rw-r--r--Documentation/devicetree/bindings/reset/bitmain,bm1880-reset.yaml36
-rw-r--r--Documentation/devicetree/bindings/reset/brcm,bcm21664-resetmgr.txt14
-rw-r--r--Documentation/devicetree/bindings/reset/brcm,bcm4908-misc-pcie-reset.yaml39
-rw-r--r--Documentation/devicetree/bindings/reset/brcm,bcm63138-pmb.txt19
-rw-r--r--Documentation/devicetree/bindings/reset/brcm,bcm6345-reset.yaml39
-rw-r--r--Documentation/devicetree/bindings/reset/brcm,bcm7216-pcie-sata-rescal.yaml41
-rw-r--r--Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.yaml48
-rw-r--r--Documentation/devicetree/bindings/reset/canaan,k210-rst.yaml40
-rw-r--r--Documentation/devicetree/bindings/reset/canaan,k230-rst.yaml39
-rw-r--r--Documentation/devicetree/bindings/reset/delta,tn48m-reset.yaml35
-rw-r--r--Documentation/devicetree/bindings/reset/eswin,eic7700-reset.yaml42
-rw-r--r--Documentation/devicetree/bindings/reset/fsl,imx-src.txt49
-rw-r--r--Documentation/devicetree/bindings/reset/fsl,imx-src.yaml70
-rw-r--r--Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml65
-rw-r--r--Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.yaml58
-rw-r--r--Documentation/devicetree/bindings/reset/img,pistachio-reset.txt55
-rw-r--r--Documentation/devicetree/bindings/reset/intel,rcu-gw.yaml65
-rw-r--r--Documentation/devicetree/bindings/reset/lantiq,reset.yaml49
-rw-r--r--Documentation/devicetree/bindings/reset/marvell,berlin2-reset.yaml38
-rw-r--r--Documentation/devicetree/bindings/reset/microchip,rst.yaml64
-rw-r--r--Documentation/devicetree/bindings/reset/nuvoton,ma35d1-reset.yaml46
-rw-r--r--Documentation/devicetree/bindings/reset/nuvoton,npcm750-reset.yaml76
-rw-r--r--Documentation/devicetree/bindings/reset/nxp,lpc1850-rgu.yaml101
-rw-r--r--Documentation/devicetree/bindings/reset/qca,ar7100-reset.yaml40
-rw-r--r--Documentation/devicetree/bindings/reset/qcom,aoss-reset.yaml52
-rw-r--r--Documentation/devicetree/bindings/reset/qcom,pdc-global.yaml51
-rw-r--r--Documentation/devicetree/bindings/reset/renesas,rst.yaml70
-rw-r--r--Documentation/devicetree/bindings/reset/renesas,rzg2l-usbphy-ctrl.yaml106
-rw-r--r--Documentation/devicetree/bindings/reset/renesas,rzv2h-usb2phy-reset.yaml61
-rw-r--r--Documentation/devicetree/bindings/reset/sirf,rstc.txt42
-rw-r--r--Documentation/devicetree/bindings/reset/snps,axs10x-reset.yaml48
-rw-r--r--Documentation/devicetree/bindings/reset/snps,dw-reset.yaml39
-rw-r--r--Documentation/devicetree/bindings/reset/snps,hsdk-reset.txt28
-rw-r--r--Documentation/devicetree/bindings/reset/socfpga-reset.txt13
-rw-r--r--Documentation/devicetree/bindings/reset/socionext,uniphier-glue-reset.yaml110
-rw-r--r--Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml72
-rw-r--r--Documentation/devicetree/bindings/reset/sophgo,sg2042-reset.yaml42
-rw-r--r--Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt42
-rw-r--r--Documentation/devicetree/bindings/reset/st,sti-powerdown.txt47
-rw-r--r--Documentation/devicetree/bindings/reset/st,sti-softreset.txt8
-rw-r--r--Documentation/devicetree/bindings/reset/st,stih407-picophyreset.yaml47
-rw-r--r--Documentation/devicetree/bindings/reset/st,stih407-powerdown.yaml49
-rw-r--r--Documentation/devicetree/bindings/reset/st,stm32-rcc.txt6
-rw-r--r--Documentation/devicetree/bindings/reset/st,stm32mp1-rcc.txt6
-rw-r--r--Documentation/devicetree/bindings/reset/starfive,jh7100-reset.yaml38
-rw-r--r--Documentation/devicetree/bindings/reset/sunplus,reset.yaml38
-rw-r--r--Documentation/devicetree/bindings/reset/thead,th1520-reset.yaml50
-rw-r--r--Documentation/devicetree/bindings/reset/ti,sci-reset.yaml50
-rw-r--r--Documentation/devicetree/bindings/reset/ti,tps380x-reset.yaml49
-rw-r--r--Documentation/devicetree/bindings/reset/ti-syscon-reset.txt91
-rw-r--r--Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml53
-rw-r--r--Documentation/devicetree/bindings/reset/zynq-reset.txt68
-rw-r--r--Documentation/devicetree/bindings/riscv/andes.yaml25
-rw-r--r--Documentation/devicetree/bindings/riscv/anlogic.yaml27
-rw-r--r--Documentation/devicetree/bindings/riscv/canaan.yaml47
-rw-r--r--Documentation/devicetree/bindings/riscv/cpus.yaml233
-rw-r--r--Documentation/devicetree/bindings/riscv/eswin.yaml29
-rw-r--r--Documentation/devicetree/bindings/riscv/extensions.yaml904
-rw-r--r--Documentation/devicetree/bindings/riscv/microchip.yaml52
-rw-r--r--Documentation/devicetree/bindings/riscv/sifive.yaml35
-rw-r--r--Documentation/devicetree/bindings/riscv/spacemit.yaml32
-rw-r--r--Documentation/devicetree/bindings/riscv/starfive.yaml47
-rw-r--r--Documentation/devicetree/bindings/riscv/sunxi.yaml74
-rw-r--r--Documentation/devicetree/bindings/riscv/tenstorrent.yaml28
-rw-r--r--Documentation/devicetree/bindings/riscv/thead.yaml33
-rw-r--r--Documentation/devicetree/bindings/rng/SUNW,n2-rng.yaml50
-rw-r--r--Documentation/devicetree/bindings/rng/airoha,en7581-trng.yaml38
-rw-r--r--Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml43
-rw-r--r--Documentation/devicetree/bindings/rng/apm,rng.txt17
-rw-r--r--Documentation/devicetree/bindings/rng/apm,x-gene-rng.yaml47
-rw-r--r--Documentation/devicetree/bindings/rng/arm-cctrng.yaml52
-rw-r--r--Documentation/devicetree/bindings/rng/atmel,at91-trng.yaml56
-rw-r--r--Documentation/devicetree/bindings/rng/brcm,bcm2835.txt13
-rw-r--r--Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml82
-rw-r--r--Documentation/devicetree/bindings/rng/brcm,bcm74110-rng.yaml35
-rw-r--r--Documentation/devicetree/bindings/rng/brcm,iproc-rng200.yaml36
-rw-r--r--Documentation/devicetree/bindings/rng/hisi-rng.yaml32
-rw-r--r--Documentation/devicetree/bindings/rng/imx-rng.yaml52
-rw-r--r--Documentation/devicetree/bindings/rng/ingenic,rng.yaml36
-rw-r--r--Documentation/devicetree/bindings/rng/ingenic,trng.yaml43
-rw-r--r--Documentation/devicetree/bindings/rng/inside-secure,safexcel-eip76.yaml84
-rw-r--r--Documentation/devicetree/bindings/rng/intel,ixp46x-rng.yaml35
-rw-r--r--Documentation/devicetree/bindings/rng/microchip,pic32-rng.yaml40
-rw-r--r--Documentation/devicetree/bindings/rng/microsoft,vmgenid.yaml49
-rw-r--r--Documentation/devicetree/bindings/rng/mtk-rng.yaml55
-rw-r--r--Documentation/devicetree/bindings/rng/nuvoton,npcm-rng.yaml37
-rw-r--r--Documentation/devicetree/bindings/rng/qcom,prng.txt17
-rw-r--r--Documentation/devicetree/bindings/rng/rockchip,rk3568-rng.yaml61
-rw-r--r--Documentation/devicetree/bindings/rng/rockchip,rk3588-rng.yaml60
-rw-r--r--Documentation/devicetree/bindings/rng/samsung,exynos4-rng.yaml45
-rw-r--r--Documentation/devicetree/bindings/rng/samsung,exynos5250-trng.yaml76
-rw-r--r--Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml36
-rw-r--r--Documentation/devicetree/bindings/rng/st,rng.yaml35
-rw-r--r--Documentation/devicetree/bindings/rng/st,stm32-rng.yaml97
-rw-r--r--Documentation/devicetree/bindings/rng/starfive,jh7110-trng.yaml59
-rw-r--r--Documentation/devicetree/bindings/rng/ti,keystone-rng.yaml50
-rw-r--r--Documentation/devicetree/bindings/rng/ti,omap-rom-rng.yaml41
-rw-r--r--Documentation/devicetree/bindings/rng/timeriomem_rng.yaml48
-rw-r--r--Documentation/devicetree/bindings/rng/xiphera,xip8001b-trng.yaml33
-rw-r--r--Documentation/devicetree/bindings/rtc/abracon,abx80x.yaml98
-rw-r--r--Documentation/devicetree/bindings/rtc/adi,max31335.yaml72
-rw-r--r--Documentation/devicetree/bindings/rtc/allwinner,sun4i-a10-rtc.yaml43
-rw-r--r--Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml197
-rw-r--r--Documentation/devicetree/bindings/rtc/alphascale,asm9260-rtc.yaml50
-rw-r--r--Documentation/devicetree/bindings/rtc/amlogic,a4-rtc.yaml68
-rw-r--r--Documentation/devicetree/bindings/rtc/amlogic,meson-vrtc.yaml44
-rw-r--r--Documentation/devicetree/bindings/rtc/amlogic,meson6-rtc.yaml63
-rw-r--r--Documentation/devicetree/bindings/rtc/apm,xgene-rtc.yaml45
-rw-r--r--Documentation/devicetree/bindings/rtc/arm,pl031.yaml58
-rw-r--r--Documentation/devicetree/bindings/rtc/armada-380-rtc.txt22
-rw-r--r--Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.txt15
-rw-r--r--Documentation/devicetree/bindings/rtc/atmel,at91rm9200-rtc.yaml56
-rw-r--r--Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt23
-rw-r--r--Documentation/devicetree/bindings/rtc/atmel,at91sam9260-rtt.yaml72
-rw-r--r--Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.yaml51
-rw-r--r--Documentation/devicetree/bindings/rtc/cdns,rtc.txt25
-rw-r--r--Documentation/devicetree/bindings/rtc/cirrus,ep9301-rtc.yaml42
-rw-r--r--Documentation/devicetree/bindings/rtc/cpcap-rtc.txt18
-rw-r--r--Documentation/devicetree/bindings/rtc/dallas,ds1339.txt18
-rw-r--r--Documentation/devicetree/bindings/rtc/dallas,ds1390.txt18
-rw-r--r--Documentation/devicetree/bindings/rtc/digicolor-rtc.txt17
-rw-r--r--Documentation/devicetree/bindings/rtc/dw-apb.txt32
-rw-r--r--Documentation/devicetree/bindings/rtc/epson,rtc7301.yaml51
-rw-r--r--Documentation/devicetree/bindings/rtc/epson,rx6110.txt39
-rw-r--r--Documentation/devicetree/bindings/rtc/epson,rx8900.yaml52
-rw-r--r--Documentation/devicetree/bindings/rtc/faraday,ftrtc010.yaml58
-rw-r--r--Documentation/devicetree/bindings/rtc/fsl,ls-ftm-alarm.yaml73
-rw-r--r--Documentation/devicetree/bindings/rtc/fsl,scu-rtc.yaml31
-rw-r--r--Documentation/devicetree/bindings/rtc/fsl,stmp3xxx-rtc.yaml51
-rw-r--r--Documentation/devicetree/bindings/rtc/haoyu,hym8563.txt30
-rw-r--r--Documentation/devicetree/bindings/rtc/haoyu,hym8563.yaml56
-rw-r--r--Documentation/devicetree/bindings/rtc/imxdi-rtc.txt17
-rw-r--r--Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml43
-rw-r--r--Documentation/devicetree/bindings/rtc/ingenic,rtc.yaml114
-rw-r--r--Documentation/devicetree/bindings/rtc/intersil,isl12022.yaml64
-rw-r--r--Documentation/devicetree/bindings/rtc/isil,isl12026.txt28
-rw-r--r--Documentation/devicetree/bindings/rtc/isil,isl12057.txt78
-rw-r--r--Documentation/devicetree/bindings/rtc/isil,isl1208.yaml100
-rw-r--r--Documentation/devicetree/bindings/rtc/loongson,rtc.yaml57
-rw-r--r--Documentation/devicetree/bindings/rtc/lpc32xx-rtc.txt15
-rw-r--r--Documentation/devicetree/bindings/rtc/marvell,armada-380-rtc.yaml51
-rw-r--r--Documentation/devicetree/bindings/rtc/marvell,pxa-rtc.yaml40
-rw-r--r--Documentation/devicetree/bindings/rtc/maxim,ds1742.txt12
-rw-r--r--Documentation/devicetree/bindings/rtc/maxim-ds1302.txt46
-rw-r--r--Documentation/devicetree/bindings/rtc/mediatek,mt2712-rtc.yaml39
-rw-r--r--Documentation/devicetree/bindings/rtc/mediatek,mt7622-rtc.yaml52
-rw-r--r--Documentation/devicetree/bindings/rtc/microchip,mpfs-rtc.yaml69
-rw-r--r--Documentation/devicetree/bindings/rtc/microchip,pic32-rtc.txt21
-rw-r--r--Documentation/devicetree/bindings/rtc/microcrystal,rv3028.yaml57
-rw-r--r--Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml66
-rw-r--r--Documentation/devicetree/bindings/rtc/moxa,moxart-rtc.txt12
-rw-r--r--Documentation/devicetree/bindings/rtc/mstar,msc313-rtc.yaml49
-rw-r--r--Documentation/devicetree/bindings/rtc/mstar,ssd202d-rtc.yaml35
-rw-r--r--Documentation/devicetree/bindings/rtc/nuvoton,ma35d1-rtc.yaml48
-rw-r--r--Documentation/devicetree/bindings/rtc/nuvoton,nct3018y.yaml45
-rw-r--r--Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.txt24
-rw-r--r--Documentation/devicetree/bindings/rtc/nvidia,tegra20-rtc.yaml62
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,lpc1788-rtc.yaml63
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,lpc3220-rtc.yaml49
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,pcf2123.yaml47
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,pcf2127.yaml56
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,pcf85063.yaml113
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,pcf8523.yaml45
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,pcf85363.yaml60
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,pcf8563.yaml56
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt16
-rw-r--r--Documentation/devicetree/bindings/rtc/nxp,s32g-rtc.yaml72
-rw-r--r--Documentation/devicetree/bindings/rtc/orion-rtc.txt18
-rw-r--r--Documentation/devicetree/bindings/rtc/pxa-rtc.txt14
-rw-r--r--Documentation/devicetree/bindings/rtc/qcom-pm8xxx-rtc.yaml98
-rw-r--r--Documentation/devicetree/bindings/rtc/realtek,rtd119x.txt16
-rw-r--r--Documentation/devicetree/bindings/rtc/renesas,rz-rtca3.yaml84
-rw-r--r--Documentation/devicetree/bindings/rtc/renesas,rzn1-rtc.yaml74
-rw-r--r--Documentation/devicetree/bindings/rtc/renesas,sh-rtc.yaml77
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-cmos.txt3
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-ds1307.yaml102
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-mxc.yaml61
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-mxc_v2.yaml46
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-omap.txt27
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-opal.txt7
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-palmas.txt7
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc-st-lpc.txt28
-rw-r--r--Documentation/devicetree/bindings/rtc/rtc.yaml71
-rw-r--r--Documentation/devicetree/bindings/rtc/s3c-rtc.txt23
-rw-r--r--Documentation/devicetree/bindings/rtc/s3c-rtc.yaml62
-rw-r--r--Documentation/devicetree/bindings/rtc/sa1100-rtc.txt17
-rw-r--r--Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml57
-rw-r--r--Documentation/devicetree/bindings/rtc/snvs-rtc.txt1
-rw-r--r--Documentation/devicetree/bindings/rtc/sophgo,cv1800b-rtc.yaml86
-rw-r--r--Documentation/devicetree/bindings/rtc/spear-rtc.txt17
-rw-r--r--Documentation/devicetree/bindings/rtc/sprd,sc2731-rtc.yaml33
-rw-r--r--Documentation/devicetree/bindings/rtc/st,m41t80.yaml73
-rw-r--r--Documentation/devicetree/bindings/rtc/st,m48t86.yaml38
-rw-r--r--Documentation/devicetree/bindings/rtc/st,stm32-rtc.yaml172
-rw-r--r--Documentation/devicetree/bindings/rtc/stmp3xxx-rtc.txt21
-rw-r--r--Documentation/devicetree/bindings/rtc/sun6i-rtc.txt17
-rw-r--r--Documentation/devicetree/bindings/rtc/sunplus,sp7021-rtc.yaml56
-rw-r--r--Documentation/devicetree/bindings/rtc/sunxi-rtc.txt17
-rw-r--r--Documentation/devicetree/bindings/rtc/ti,bq32000.yaml49
-rw-r--r--Documentation/devicetree/bindings/rtc/ti,k3-rtc.yaml62
-rw-r--r--Documentation/devicetree/bindings/rtc/trivial-rtc.yaml105
-rw-r--r--Documentation/devicetree/bindings/rtc/twl-rtc.txt12
-rw-r--r--Documentation/devicetree/bindings/rtc/via,vt8500-rtc.txt15
-rw-r--r--Documentation/devicetree/bindings/rtc/xgene-rtc.txt28
-rw-r--r--Documentation/devicetree/bindings/rtc/xlnx,zynqmp-rtc.yaml84
-rw-r--r--Documentation/devicetree/bindings/scsi/hisilicon-sas.txt98
-rw-r--r--Documentation/devicetree/bindings/security/tpm/st33zp24-i2c.txt36
-rw-r--r--Documentation/devicetree/bindings/security/tpm/st33zp24-spi.txt34
-rw-r--r--Documentation/devicetree/bindings/serial/8250.txt66
-rw-r--r--Documentation/devicetree/bindings/serial/8250.yaml349
-rw-r--r--Documentation/devicetree/bindings/serial/8250_omap.yaml126
-rw-r--r--Documentation/devicetree/bindings/serial/actions,owl-uart.yaml48
-rw-r--r--Documentation/devicetree/bindings/serial/altera_jtaguart.txt5
-rw-r--r--Documentation/devicetree/bindings/serial/altera_uart.txt8
-rw-r--r--Documentation/devicetree/bindings/serial/altr,juart-1.0.yaml19
-rw-r--r--Documentation/devicetree/bindings/serial/altr,uart-1.0.yaml25
-rw-r--r--Documentation/devicetree/bindings/serial/amlogic,meson-uart.yaml105
-rw-r--r--Documentation/devicetree/bindings/serial/arc-uart.txt26
-rw-r--r--Documentation/devicetree/bindings/serial/arm,dcc.yaml30
-rw-r--r--Documentation/devicetree/bindings/serial/arm,mps2-uart.yaml46
-rw-r--r--Documentation/devicetree/bindings/serial/arm,sbsa-uart.yaml38
-rw-r--r--Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml200
-rw-r--r--Documentation/devicetree/bindings/serial/atmel-usart.txt60
-rw-r--r--Documentation/devicetree/bindings/serial/axis,etraxfs-uart.txt19
-rw-r--r--Documentation/devicetree/bindings/serial/brcm,bcm2835-aux-uart.yaml46
-rw-r--r--Documentation/devicetree/bindings/serial/brcm,bcm6345-uart.txt30
-rw-r--r--Documentation/devicetree/bindings/serial/brcm,bcm6345-uart.yaml47
-rw-r--r--Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml95
-rw-r--r--Documentation/devicetree/bindings/serial/cavium-uart.txt19
-rw-r--r--Documentation/devicetree/bindings/serial/cdns,uart.txt20
-rw-r--r--Documentation/devicetree/bindings/serial/cdns,uart.yaml82
-rw-r--r--Documentation/devicetree/bindings/serial/cirrus,clps711x-uart.txt31
-rw-r--r--Documentation/devicetree/bindings/serial/cirrus,ep7209-uart.yaml56
-rw-r--r--Documentation/devicetree/bindings/serial/cnxt,cx92755-usart.yaml48
-rw-r--r--Documentation/devicetree/bindings/serial/digicolor-usart.txt27
-rw-r--r--Documentation/devicetree/bindings/serial/efm32-uart.txt20
-rw-r--r--Documentation/devicetree/bindings/serial/esp,esp32-acm.yaml42
-rw-r--r--Documentation/devicetree/bindings/serial/esp,esp32-uart.yaml51
-rw-r--r--Documentation/devicetree/bindings/serial/fsl,s32-linflexuart.yaml50
-rw-r--r--Documentation/devicetree/bindings/serial/fsl-imx-uart.txt29
-rw-r--r--Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml153
-rw-r--r--Documentation/devicetree/bindings/serial/fsl-lpuart.txt31
-rw-r--r--Documentation/devicetree/bindings/serial/fsl-lpuart.yaml98
-rw-r--r--Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt45
-rw-r--r--Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml94
-rw-r--r--Documentation/devicetree/bindings/serial/ingenic,uart.yaml103
-rw-r--r--Documentation/devicetree/bindings/serial/lantiq,asc.yaml56
-rw-r--r--Documentation/devicetree/bindings/serial/lantiq_asc.txt16
-rw-r--r--Documentation/devicetree/bindings/serial/litex,liteuart.yaml40
-rw-r--r--Documentation/devicetree/bindings/serial/marvell,armada-3700-uart.yaml102
-rw-r--r--Documentation/devicetree/bindings/serial/maxim,max310x.txt36
-rw-r--r--Documentation/devicetree/bindings/serial/maxim,max310x.yaml74
-rw-r--r--Documentation/devicetree/bindings/serial/mediatek,uart.yaml126
-rw-r--r--Documentation/devicetree/bindings/serial/microchip,pic32mzda-uart.yaml53
-rw-r--r--Documentation/devicetree/bindings/serial/mrvl,pxa-ssp.txt65
-rw-r--r--Documentation/devicetree/bindings/serial/mrvl-serial.txt4
-rw-r--r--Documentation/devicetree/bindings/serial/mtk-uart.txt26
-rw-r--r--Documentation/devicetree/bindings/serial/nuvoton,ma35d1-serial.yaml48
-rw-r--r--Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.yaml61
-rw-r--r--Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.txt37
-rw-r--r--Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml125
-rw-r--r--Documentation/devicetree/bindings/serial/nvidia,tegra264-utc.yaml73
-rw-r--r--Documentation/devicetree/bindings/serial/nxp,lpc3220-hsuart.yaml39
-rw-r--r--Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt33
-rw-r--r--Documentation/devicetree/bindings/serial/nxp,sc16is7xx.yaml133
-rw-r--r--Documentation/devicetree/bindings/serial/nxp-lpc32xx-hsuart.txt14
-rw-r--r--Documentation/devicetree/bindings/serial/omap_serial.txt30
-rw-r--r--Documentation/devicetree/bindings/serial/pl011.txt51
-rw-r--r--Documentation/devicetree/bindings/serial/pl011.yaml130
-rw-r--r--Documentation/devicetree/bindings/serial/qca,ar9330-uart.txt34
-rw-r--r--Documentation/devicetree/bindings/serial/qca,ar9330-uart.yaml50
-rw-r--r--Documentation/devicetree/bindings/serial/qcom,msm-uart.txt25
-rw-r--r--Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml56
-rw-r--r--Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt78
-rw-r--r--Documentation/devicetree/bindings/serial/qcom,msm-uartdm.yaml125
-rw-r--r--Documentation/devicetree/bindings/serial/qcom,sa8255p-geni-uart.yaml69
-rw-r--r--Documentation/devicetree/bindings/serial/qcom,serial-geni-qcom.yaml87
-rw-r--r--Documentation/devicetree/bindings/serial/rda,8810pl-uart.yaml46
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,em-uart.yaml74
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,hscif.yaml158
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,rsci.yaml83
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,sci-serial.txt59
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,sci.yaml109
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,scif.yaml285
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,scifa.yaml112
-rw-r--r--Documentation/devicetree/bindings/serial/renesas,scifb.yaml103
-rw-r--r--Documentation/devicetree/bindings/serial/rs485.txt32
-rw-r--r--Documentation/devicetree/bindings/serial/rs485.yaml65
-rw-r--r--Documentation/devicetree/bindings/serial/samsung_uart.txt58
-rw-r--r--Documentation/devicetree/bindings/serial/samsung_uart.yaml227
-rw-r--r--Documentation/devicetree/bindings/serial/serial-peripheral-props.yaml41
-rw-r--r--Documentation/devicetree/bindings/serial/serial.yaml133
-rw-r--r--Documentation/devicetree/bindings/serial/sifive-serial.yaml65
-rw-r--r--Documentation/devicetree/bindings/serial/sirf-uart.txt47
-rw-r--r--Documentation/devicetree/bindings/serial/snps,arc-uart.yaml51
-rw-r--r--Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt73
-rw-r--r--Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml194
-rw-r--r--Documentation/devicetree/bindings/serial/socionext,milbeaut-usio-uart.yaml56
-rw-r--r--Documentation/devicetree/bindings/serial/socionext,uniphier-uart.yaml51
-rw-r--r--Documentation/devicetree/bindings/serial/sprd-uart.txt7
-rw-r--r--Documentation/devicetree/bindings/serial/sprd-uart.yaml82
-rw-r--r--Documentation/devicetree/bindings/serial/st,asc.yaml55
-rw-r--r--Documentation/devicetree/bindings/serial/st,stm32-uart.yaml133
-rw-r--r--Documentation/devicetree/bindings/serial/st-asc.txt18
-rw-r--r--Documentation/devicetree/bindings/serial/sunplus,sp7021-uart.yaml56
-rw-r--r--Documentation/devicetree/bindings/serial/via,vt8500-uart.yaml46
-rw-r--r--Documentation/devicetree/bindings/serial/vt8500-uart.txt27
-rw-r--r--Documentation/devicetree/bindings/serial/xlnx,opb-uartlite.yaml88
-rw-r--r--Documentation/devicetree/bindings/serio/allwinner,sun4i-a10-ps2.yaml51
-rw-r--r--Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt23
-rw-r--r--Documentation/devicetree/bindings/serio/arm,pl050.yaml67
-rw-r--r--Documentation/devicetree/bindings/serio/ps2-gpio.yaml64
-rw-r--r--Documentation/devicetree/bindings/sifive/sifive-blocks-ip-versioning.txt38
-rw-r--r--Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.yaml48
-rw-r--r--Documentation/devicetree/bindings/slimbus/qcom,slim-ngd.yaml120
-rw-r--r--Documentation/devicetree/bindings/slimbus/slimbus.yaml96
-rw-r--r--Documentation/devicetree/bindings/soc/altera/altr,sys-mgr.yaml51
-rw-r--r--Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.yaml50
-rw-r--r--Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-clk-measure.yaml42
-rw-r--r--Documentation/devicetree/bindings/soc/amlogic/amlogic,meson-gx-hhi-sysctrl.yaml207
-rw-r--r--Documentation/devicetree/bindings/soc/aspeed/uart-routing.yaml56
-rw-r--r--Documentation/devicetree/bindings/soc/bcm/brcm,bcm23550-cdc.yaml35
-rw-r--r--Documentation/devicetree/bindings/soc/bcm/brcm,bcm2711-avs-monitor.yaml44
-rw-r--r--Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.yaml112
-rw-r--r--Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.yaml53
-rw-r--r--Documentation/devicetree/bindings/soc/cirrus/cirrus,ep9301-syscon.yaml94
-rw-r--r--Documentation/devicetree/bindings/soc/dove/pmu.txt56
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/bman-portals.txt56
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/bman.txt135
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/cpm.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/cpm/brg.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/brg.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/cpm/i2c.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/i2c.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/cpm/pic.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/pic.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/cpm/usb.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/cpm/usb.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml193
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-tsa.yaml205
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-firmware.yaml48
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-ic.yaml47
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-muram.yaml70
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-si.yaml40
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-siram.yaml39
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-tsa.yaml210
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe-ucc-qmc.yaml197
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,qe.yaml148
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,ucc-hdlc.yaml140
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/gpio.txt56
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe/firmware.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/firmware.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe/par_io.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/par_io.txt)2
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe/pincfg.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/pincfg.txt)2
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe/ucc.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/ucc.txt)2
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/qe/usb.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/qe/usb.txt)1
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/serial.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/cpm_qe/serial.txt)0
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/cpm_qe/uqe_serial.txt17
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,bman-portal.yaml52
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,bman.yaml83
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,imx23-digctl.yaml53
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-dcfg.yaml67
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-scfg.yaml60
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,ls1028a-reset.yaml56
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,qman-fqd.yaml69
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,qman-portal.yaml112
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,qman.yaml93
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,rcpm.yaml87
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/fsl,vf610-src.yaml47
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/guts.txt (renamed from Documentation/devicetree/bindings/powerpc/fsl/guts.txt)8
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/qman-portals.txt154
-rw-r--r--Documentation/devicetree/bindings/soc/fsl/qman.txt175
-rw-r--r--Documentation/devicetree/bindings/soc/google/google,gs101-pmu-intr-gen.yaml35
-rw-r--r--Documentation/devicetree/bindings/soc/hisilicon/hisilicon,hi3660-usb3-otg-bc.yaml46
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,aips-bus.yaml52
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx-anatop.yaml146
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx-iomuxc-gpr.yaml90
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mm-disp-blk-ctrl.yaml94
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mm-vpu-blk-ctrl.yaml164
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mn-disp-blk-ctrl.yaml97
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hdmi-blk-ctrl.yaml99
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hsio-blk-ctrl.yaml92
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-media-blk-ctrl.yaml169
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx8mq-vpu-blk-ctrl.yaml71
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx93-media-blk-ctrl.yaml115
-rw-r--r--Documentation/devicetree/bindings/soc/imx/fsl,imx93-src.yaml97
-rw-r--r--Documentation/devicetree/bindings/soc/imx/imx8m-soc.yaml86
-rw-r--r--Documentation/devicetree/bindings/soc/intel/intel,hps-copy-engine.yaml51
-rw-r--r--Documentation/devicetree/bindings/soc/intel/intel,lgm-syscon.yaml57
-rw-r--r--Documentation/devicetree/bindings/soc/litex/litex,soc-controller.yaml40
-rw-r--r--Documentation/devicetree/bindings/soc/loongson/loongson,ls2k-pmc.yaml83
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/devapc.yaml61
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mediatek,ccorr.yaml68
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml52
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mediatek,mt8183-dvfsrc.yaml84
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mediatek,mutex.yaml122
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mediatek,pwrap.yaml168
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mediatek,wdma.yaml81
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml94
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/pwrap.txt58
-rw-r--r--Documentation/devicetree/bindings/soc/mediatek/scpsys.txt79
-rw-r--r--Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml219
-rw-r--r--Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-mss-top-sysreg.yaml58
-rw-r--r--Documentation/devicetree/bindings/soc/microchip/microchip,mpfs-sys-controller.yaml50
-rw-r--r--Documentation/devicetree/bindings/soc/microchip/microchip,sparx5-cpu-syscon.yaml49
-rw-r--r--Documentation/devicetree/bindings/soc/mobileye/mobileye,eyeq5-olb.yaml352
-rw-r--r--Documentation/devicetree/bindings/soc/nuvoton/nuvoton,gfxi.yaml39
-rw-r--r--Documentation/devicetree/bindings/soc/nuvoton/nuvoton,npcm-gcr.yaml50
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.yaml123
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,apr-services.yaml53
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,apr.yaml211
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,dcc.yaml45
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,eud.yaml79
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml170
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,gsbi.txt88
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,gsbi.yaml132
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,msm8976-ramp-controller.yaml36
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,pbs.yaml46
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml126
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,rpm-master-stats.yaml71
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,rpm.yaml116
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml289
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,sa8255p-geni-se-qup.yaml107
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,saw2.yaml120
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,se-common-props.yaml26
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml152
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,smd.yaml69
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,smem.yaml98
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.yaml145
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,smsm.yaml150
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml137
-rw-r--r--Documentation/devicetree/bindings/soc/qcom/qcom-stats.yaml67
-rw-r--r--Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g011-sys.yaml43
-rw-r--r--Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g057-sys.yaml55
-rw-r--r--Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml64
-rw-r--r--Documentation/devicetree/bindings/soc/renesas/renesas,rzv2m-pwc.yaml56
-rw-r--r--Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml73
-rw-r--r--Documentation/devicetree/bindings/soc/renesas/renesas.yaml630
-rw-r--r--Documentation/devicetree/bindings/soc/rockchip/grf.yaml382
-rw-r--r--Documentation/devicetree/bindings/soc/samsung/exynos-pmu.yaml235
-rw-r--r--Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml207
-rw-r--r--Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml133
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-adamv.yaml50
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-ahci-glue.yaml77
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-dwc3-glue.yaml106
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-mioctrl.yaml65
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-perictrl.yaml64
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sdctrl.yaml61
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue-debug.yaml68
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-soc-glue.yaml114
-rw-r--r--Documentation/devicetree/bindings/soc/socionext/socionext,uniphier-sysctrl.yaml104
-rw-r--r--Documentation/devicetree/bindings/soc/sophgo/sophgo,cv1800b-top-syscon.yaml80
-rw-r--r--Documentation/devicetree/bindings/soc/sophgo/sophgo,sg2044-top-syscon.yaml49
-rw-r--r--Documentation/devicetree/bindings/soc/sophgo/sophgo.yaml52
-rw-r--r--Documentation/devicetree/bindings/soc/spacemit/spacemit,k1-syscon.yaml95
-rw-r--r--Documentation/devicetree/bindings/soc/sprd/sprd,sc9863a-glbregs.yaml55
-rw-r--r--Documentation/devicetree/bindings/soc/starfive/starfive,jh7110-syscon.yaml93
-rw-r--r--Documentation/devicetree/bindings/soc/sti/st,sti-syscon.yaml55
-rw-r--r--Documentation/devicetree/bindings/soc/tegra/nvidia,nvec.yaml84
-rw-r--r--Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-ahb.yaml40
-rw-r--r--Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-flowctrl.yaml41
-rw-r--r--Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml416
-rw-r--r--Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml96
-rw-r--r--Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt18
-rw-r--r--Documentation/devicetree/bindings/soc/ti/sci-pm-domain.yaml59
-rw-r--r--Documentation/devicetree/bindings/soc/ti/ti,am654-serdes-ctrl.yaml43
-rw-r--r--Documentation/devicetree/bindings/soc/ti/ti,j721e-system-controller.yaml137
-rw-r--r--Documentation/devicetree/bindings/soc/ti/ti,j784s4-bist.yaml63
-rw-r--r--Documentation/devicetree/bindings/soc/ti/ti,pruss.yaml557
-rw-r--r--Documentation/devicetree/bindings/soc/ti/wkup-m3-ipc.yaml175
-rw-r--r--Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml280
-rw-r--r--Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu-settings.yaml43
-rw-r--r--Documentation/devicetree/bindings/sound/ac97-bus.txt32
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau1372.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau1373.yaml111
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau1701.txt4
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau17x1.yaml52
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau1977.yaml94
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau7002.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/adi,adau7118.yaml87
-rw-r--r--Documentation/devicetree/bindings/sound/adi,axi-i2s.txt9
-rw-r--r--Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/adi,max98388.yaml79
-rw-r--r--Documentation/devicetree/bindings/sound/adi,max98396.yaml141
-rw-r--r--Documentation/devicetree/bindings/sound/adi,ssm2305.txt14
-rw-r--r--Documentation/devicetree/bindings/sound/adi,ssm2518.yaml49
-rw-r--r--Documentation/devicetree/bindings/sound/adi,ssm2602.txt19
-rw-r--r--Documentation/devicetree/bindings/sound/ak4104.txt25
-rw-r--r--Documentation/devicetree/bindings/sound/ak4118.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/ak4554.c11
-rw-r--r--Documentation/devicetree/bindings/sound/ak4642.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/alc5623.txt25
-rw-r--r--Documentation/devicetree/bindings/sound/alc5632.txt43
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-codec.yaml346
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml149
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml158
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun50i-a64-codec-analog.yaml44
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun50i-h6-dmic.yaml87
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun8i-a23-codec-analog.yaml41
-rw-r--r--Documentation/devicetree/bindings/sound/allwinner,sun8i-a33-codec.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,aiu.yaml118
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-fifo.yaml112
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-pdm.yaml82
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-sound-card.yaml181
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.yaml86
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.yaml79
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.yaml88
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,axg-tdm-iface.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,g12a-toacodec.yaml56
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,g12a-tohdmitx.yaml54
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,gx-sound-card.yaml113
-rw-r--r--Documentation/devicetree/bindings/sound/amlogic,t9015.yaml70
-rw-r--r--Documentation/devicetree/bindings/sound/apple,mca.yaml140
-rw-r--r--Documentation/devicetree/bindings/sound/arm,pl041.yaml62
-rw-r--r--Documentation/devicetree/bindings/sound/armada-370db-audio.txt1
-rw-r--r--Documentation/devicetree/bindings/sound/arndale.txt24
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4104.yaml49
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4375.yaml60
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4458.yaml77
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4554.yaml27
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4613.yaml59
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4619.yaml62
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak4642.yaml59
-rw-r--r--Documentation/devicetree/bindings/sound/asahi-kasei,ak5558.yaml48
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,asoc-wm8904.yaml84
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,at91-ssc.yaml109
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,at91sam9g20ek-wm8731.yaml72
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,sam9x5-wm8731-audio.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,sama5d2-classd.yaml105
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,sama5d2-i2s.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/atmel,sama5d2-pdmic.yaml98
-rw-r--r--Documentation/devicetree/bindings/sound/atmel-at91sam9g20ek-wm8731-audio.txt26
-rw-r--r--Documentation/devicetree/bindings/sound/atmel-sam9x5-wm8731-audio.txt35
-rw-r--r--Documentation/devicetree/bindings/sound/atmel-wm8904.txt55
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph-card.yaml57
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph-card2.yaml49
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph-port.yaml131
-rw-r--r--Documentation/devicetree/bindings/sound/audio-graph.yaml53
-rw-r--r--Documentation/devicetree/bindings/sound/audio-iio-aux.yaml64
-rw-r--r--Documentation/devicetree/bindings/sound/awinic,aw8738.yaml54
-rw-r--r--Documentation/devicetree/bindings/sound/awinic,aw87390.yaml58
-rw-r--r--Documentation/devicetree/bindings/sound/awinic,aw88395.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt92
-rw-r--r--Documentation/devicetree/bindings/sound/brcm,bcm2835-i2s.txt25
-rw-r--r--Documentation/devicetree/bindings/sound/brcm,bcm2835-i2s.yaml51
-rw-r--r--Documentation/devicetree/bindings/sound/brcm,bcm63xx-audio.txt29
-rw-r--r--Documentation/devicetree/bindings/sound/brcm,cygnus-audio.txt63
-rw-r--r--Documentation/devicetree/bindings/sound/cdns,xtfpga-i2s.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs35l41.yaml215
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml159
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs4234.yaml74
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs4270.yaml59
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs4271.yaml111
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs42l42.yaml226
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml314
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs42l51.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs42l84.yaml56
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs42xx8.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs48l32.yaml195
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,cs530x.yaml93
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,ep9301-i2s.yaml82
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,lochnagar.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/cirrus,madera.yaml118
-rw-r--r--Documentation/devicetree/bindings/sound/component-common.yaml21
-rw-r--r--Documentation/devicetree/bindings/sound/cs35l33.txt124
-rw-r--r--Documentation/devicetree/bindings/sound/cs35l34.txt62
-rw-r--r--Documentation/devicetree/bindings/sound/cs35l35.txt181
-rw-r--r--Documentation/devicetree/bindings/sound/cs35l36.txt168
-rw-r--r--Documentation/devicetree/bindings/sound/cs4265.txt29
-rw-r--r--Documentation/devicetree/bindings/sound/cs4270.txt21
-rw-r--r--Documentation/devicetree/bindings/sound/cs4271.txt50
-rw-r--r--Documentation/devicetree/bindings/sound/cs42l56.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/cs42l73.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/cs42xx8.txt28
-rw-r--r--Documentation/devicetree/bindings/sound/cs43130.txt67
-rw-r--r--Documentation/devicetree/bindings/sound/cs53l30.txt44
-rw-r--r--Documentation/devicetree/bindings/sound/da7218.txt102
-rw-r--r--Documentation/devicetree/bindings/sound/da9055.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/dai-common.yaml18
-rw-r--r--Documentation/devicetree/bindings/sound/dai-params.yaml37
-rw-r--r--Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt60
-rw-r--r--Documentation/devicetree/bindings/sound/davinci-mcasp-audio.yaml202
-rw-r--r--Documentation/devicetree/bindings/sound/davinci-mcbsp.yaml113
-rw-r--r--Documentation/devicetree/bindings/sound/designware-i2s.txt31
-rw-r--r--Documentation/devicetree/bindings/sound/dialog,da7219.yaml238
-rw-r--r--Documentation/devicetree/bindings/sound/dlg,da7213.yaml103
-rw-r--r--Documentation/devicetree/bindings/sound/dmic-codec.yaml58
-rw-r--r--Documentation/devicetree/bindings/sound/es8328.txt38
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es71x4.yaml62
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es7241.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es8316.yaml78
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es8326.yaml120
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es8328.yaml86
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es8375.yaml71
-rw-r--r--Documentation/devicetree/bindings/sound/everest,es8389.yaml50
-rw-r--r--Documentation/devicetree/bindings/sound/foursemi,fs2105s.yaml101
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,asrc.txt60
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,aud2htx.yaml66
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,audmix.yaml142
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,easrc.yaml109
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,esai.txt58
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,esai.yaml136
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,imx-asrc.yaml189
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,imx-audio-es8328.yaml111
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,imx95-cm7-sof.yaml64
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,micfil.yaml96
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,mqs.yaml117
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,mxs-audio-sgtl5000.yaml81
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml147
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,rpmsg.yaml134
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,sai.yaml262
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,saif.yaml83
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,sgtl5000.yaml113
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,sof-cpu.yaml27
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,spdif.txt58
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,spdif.yaml160
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,ssi.txt87
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,ssi.yaml194
-rw-r--r--Documentation/devicetree/bindings/sound/fsl,xcvr.yaml160
-rw-r--r--Documentation/devicetree/bindings/sound/fsl-asoc-card.txt82
-rw-r--r--Documentation/devicetree/bindings/sound/fsl-asoc-card.yaml243
-rw-r--r--Documentation/devicetree/bindings/sound/fsl-sai.txt73
-rw-r--r--Documentation/devicetree/bindings/sound/google,chv3-codec.yaml31
-rw-r--r--Documentation/devicetree/bindings/sound/google,chv3-i2s.yaml44
-rw-r--r--Documentation/devicetree/bindings/sound/google,cros-ec-codec.yaml78
-rw-r--r--Documentation/devicetree/bindings/sound/google,sc7180-trogdor.yaml137
-rw-r--r--Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml182
-rw-r--r--Documentation/devicetree/bindings/sound/hdmi.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/hisilicon,hi6210-i2s.txt42
-rw-r--r--Documentation/devicetree/bindings/sound/img,i2s-in.txt47
-rw-r--r--Documentation/devicetree/bindings/sound/img,i2s-out.txt51
-rw-r--r--Documentation/devicetree/bindings/sound/img,parallel-out.txt44
-rw-r--r--Documentation/devicetree/bindings/sound/img,pistachio-internal-dac.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/img,spdif-in.txt41
-rw-r--r--Documentation/devicetree/bindings/sound/img,spdif-out.txt44
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audio-card.yaml131
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audio-es8328.txt60
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audio-hdmi.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt56
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audio-spdif.txt36
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt53
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audmux.txt28
-rw-r--r--Documentation/devicetree/bindings/sound/imx-audmux.yaml119
-rw-r--r--Documentation/devicetree/bindings/sound/infineon,peb2466.yaml91
-rw-r--r--Documentation/devicetree/bindings/sound/ingenic,aic.yaml90
-rw-r--r--Documentation/devicetree/bindings/sound/ingenic,codec.yaml63
-rw-r--r--Documentation/devicetree/bindings/sound/ingenic,jz4740-i2s.txt23
-rw-r--r--Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml90
-rw-r--r--Documentation/devicetree/bindings/sound/invensense,ics43432.yaml51
-rw-r--r--Documentation/devicetree/bindings/sound/irondevice,sma1303.yaml48
-rw-r--r--Documentation/devicetree/bindings/sound/irondevice,sma1307.yaml53
-rw-r--r--Documentation/devicetree/bindings/sound/linux,bt-sco.yaml41
-rw-r--r--Documentation/devicetree/bindings/sound/linux,spdif.yaml42
-rw-r--r--Documentation/devicetree/bindings/sound/loongson,ls-audio-card.yaml70
-rw-r--r--Documentation/devicetree/bindings/sound/loongson,ls1b-ac97.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/loongson,ls2k1000-i2s.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/marvell,mmp-sspa.yaml105
-rw-r--r--Documentation/devicetree/bindings/sound/marvell,pxa2xx-ac97.txt27
-rw-r--r--Documentation/devicetree/bindings/sound/max98090.txt51
-rw-r--r--Documentation/devicetree/bindings/sound/max98095.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/max98357a.txt14
-rw-r--r--Documentation/devicetree/bindings/sound/max98373.txt40
-rw-r--r--Documentation/devicetree/bindings/sound/max9860.txt28
-rw-r--r--Documentation/devicetree/bindings/sound/max98925.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max9759.yaml45
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98088.yaml47
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98090.yaml84
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98095.yaml54
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98357a.yaml52
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98371.yaml42
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98390.yaml60
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98504.yaml86
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98520.yaml35
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max9867.yaml60
-rw-r--r--Documentation/devicetree/bindings/sound/maxim,max98925.yaml98
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt2701-audio.yaml116
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt2701-wm8960.yaml54
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt7986-afe.yaml160
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt7986-wm8960.yaml67
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8173-afe-pcm.yaml98
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8183-audio.yaml228
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8183_da7219.yaml49
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8183_mt6358_ts3a227.yaml59
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml241
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml136
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8189-afe-pcm.yaml178
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8189-nau8825.yaml101
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8365-afe.yaml130
-rw-r--r--Documentation/devicetree/bindings/sound/mediatek,mt8365-mt6357.yaml107
-rw-r--r--Documentation/devicetree/bindings/sound/microchip,sama7g5-i2smcc.yaml115
-rw-r--r--Documentation/devicetree/bindings/sound/microchip,sama7g5-pdmc.yaml105
-rw-r--r--Documentation/devicetree/bindings/sound/microchip,sama7g5-spdifrx.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/microchip,sama7g5-spdiftx.yaml78
-rw-r--r--Documentation/devicetree/bindings/sound/mikroe,mikroe-proto.txt23
-rw-r--r--Documentation/devicetree/bindings/sound/mrvl,pxa-ssp.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/mrvl,pxa2xx-pcm.txt15
-rw-r--r--Documentation/devicetree/bindings/sound/mscc,zl38060.yaml72
-rw-r--r--Documentation/devicetree/bindings/sound/mt2701-cs42448.txt43
-rw-r--r--Documentation/devicetree/bindings/sound/mt6351.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/mt6358.txt26
-rw-r--r--Documentation/devicetree/bindings/sound/mt6359.yaml61
-rw-r--r--Documentation/devicetree/bindings/sound/mt6797-afe-pcm.txt42
-rw-r--r--Documentation/devicetree/bindings/sound/mt6797-mt6351.txt14
-rw-r--r--Documentation/devicetree/bindings/sound/mt8173-max98090.txt15
-rw-r--r--Documentation/devicetree/bindings/sound/mt8173-rt5650-rt5514.txt15
-rw-r--r--Documentation/devicetree/bindings/sound/mt8173-rt5650-rt5676.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/mt8173-rt5650.txt31
-rw-r--r--Documentation/devicetree/bindings/sound/mt8186-afe-pcm.yaml180
-rw-r--r--Documentation/devicetree/bindings/sound/mt8186-mt6366-da7219-max98357.yaml197
-rw-r--r--Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml201
-rw-r--r--Documentation/devicetree/bindings/sound/mt8192-afe-pcm.yaml105
-rw-r--r--Documentation/devicetree/bindings/sound/mt8192-mt6359-rt1015-rt5682.yaml203
-rw-r--r--Documentation/devicetree/bindings/sound/mt8195-afe-pcm.yaml200
-rw-r--r--Documentation/devicetree/bindings/sound/mt8195-mt6359.yaml202
-rw-r--r--Documentation/devicetree/bindings/sound/mtk-btcvsd-snd.txt24
-rw-r--r--Documentation/devicetree/bindings/sound/mvebu-audio.txt14
-rw-r--r--Documentation/devicetree/bindings/sound/mxs-audio-sgtl5000.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/mxs-saif.txt41
-rw-r--r--Documentation/devicetree/bindings/sound/neofidelity,ntp8835.yaml73
-rw-r--r--Documentation/devicetree/bindings/sound/neofidelity,ntp8918.yaml72
-rw-r--r--Documentation/devicetree/bindings/sound/nuvoton,nau8315.yaml44
-rw-r--r--Documentation/devicetree/bindings/sound/nuvoton,nau8325.yaml80
-rw-r--r--Documentation/devicetree/bindings/sound/nuvoton,nau8821.yaml148
-rw-r--r--Documentation/devicetree/bindings/sound/nuvoton,nau8822.yaml58
-rw-r--r--Documentation/devicetree/bindings/sound/nuvoton,nau8824.yaml190
-rw-r--r--Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml253
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.txt48
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-alc5632.yaml74
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-common.yaml87
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-graph-card.yaml200
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max9808x.yaml90
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt53
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.yaml97
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5631.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.txt52
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5640.yaml84
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.txt67
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-rt5677.yaml100
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.yaml67
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.txt21
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-trimslice.yaml33
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.txt40
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8753.yaml79
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.txt60
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm8903.yaml93
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.txt60
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra-audio-wm9712.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra186-asrc.yaml83
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml101
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-ac97.txt36
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-ac97.yaml82
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-das.txt12
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-das.yaml36
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.txt30
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-i2s.yaml77
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra20-spdif.yaml88
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml172
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-adx.yaml79
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml197
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-amx.yaml81
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml100
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml117
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-mbdrc.yaml48
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-mixer.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-mvc.yaml78
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-ope.yaml88
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-peq.yaml49
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra210-sfc.yaml75
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt30
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.yaml198
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.txt27
-rw-r--r--Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.yaml67
-rw-r--r--Documentation/devicetree/bindings/sound/nxp,lpc3220-i2s.yaml73
-rw-r--r--Documentation/devicetree/bindings/sound/nxp,tfa989x.yaml99
-rw-r--r--Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/omap-dmic.txt1
-rw-r--r--Documentation/devicetree/bindings/sound/omap-mcbsp.txt1
-rw-r--r--Documentation/devicetree/bindings/sound/omap-mcpdm.txt21
-rw-r--r--Documentation/devicetree/bindings/sound/omap-twl4030.txt62
-rw-r--r--Documentation/devicetree/bindings/sound/option,gtm601.yaml42
-rw-r--r--Documentation/devicetree/bindings/sound/pcm1792a.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/pcm3060.txt23
-rw-r--r--Documentation/devicetree/bindings/sound/pcm512x.txt52
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,apq8016-sbc-sndcard.yaml205
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-cpu.txt43
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-cpu.yaml290
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-rx-macro.yaml157
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml162
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-va-macro.yaml187
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,lpass-wsa-macro.yaml122
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-digital-codec.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,pm4125-codec.yaml134
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,pm4125-sdw.yaml79
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,pm8916-wcd-analog-codec.yaml153
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6adm-routing.yaml39
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6adm.yaml51
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6afe.yaml81
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6apm-dai.yaml34
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6apm-lpass-dais.yaml35
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6apm.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6asm-dais.yaml96
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6asm.yaml68
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6core.yaml39
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-clocks.yaml41
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6dsp-lpass-ports.yaml164
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6prm.yaml50
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,q6usb.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,sm8250.yaml217
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd9335.yaml156
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd934x.yaml239
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd937x-sdw.yaml127
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd937x.yaml82
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd938x-sdw.yaml70
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml84
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd939x-sdw.yaml69
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd939x.yaml99
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wcd93xx-common.yaml95
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wsa881x.yaml71
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wsa883x.yaml98
-rw-r--r--Documentation/devicetree/bindings/sound/qcom,wsa8840.yaml83
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,alc203.yaml36
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,alc5623.yaml54
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,alc5632.yaml63
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt1015.yaml41
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt1015p.yaml43
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt1016.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt1019.yaml35
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5514.yaml70
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5616.yaml61
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5631.yaml67
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5640.yaml146
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5645.yaml131
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5659.yaml129
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5677.yaml135
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5682.yaml156
-rw-r--r--Documentation/devicetree/bindings/sound/realtek,rt5682s.yaml150
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,fsi.txt31
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,fsi.yaml87
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,idt821034.yaml75
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rsnd.txt455
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rsnd.yaml541
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt67
-rw-r--r--Documentation/devicetree/bindings/sound/renesas,rz-ssi.yaml113
-rw-r--r--Documentation/devicetree/bindings/sound/richtek,rt9120.yaml62
-rw-r--r--Documentation/devicetree/bindings/sound/richtek,rt9123.yaml63
-rw-r--r--Documentation/devicetree/bindings/sound/richtek,rt9123p.yaml48
-rw-r--r--Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml61
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,i2s-tdm.yaml191
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,pdm.yaml123
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,rk3036-codec.yaml58
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt36
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,rk3308-codec.yaml102
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml74
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip,rk3576-sai.yaml144
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-i2s.txt37
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-i2s.yaml140
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-max98090.txt42
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-rt5645.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/rockchip-spdif.yaml109
-rw-r--r--Documentation/devicetree/bindings/sound/rohm,bd28623.yaml70
-rw-r--r--Documentation/devicetree/bindings/sound/rt1011.txt42
-rw-r--r--Documentation/devicetree/bindings/sound/rt1308.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/rt274.txt33
-rw-r--r--Documentation/devicetree/bindings/sound/rt5631.txt48
-rw-r--r--Documentation/devicetree/bindings/sound/rt5640.txt53
-rw-r--r--Documentation/devicetree/bindings/sound/rt5651.txt63
-rw-r--r--Documentation/devicetree/bindings/sound/rt5660.txt47
-rw-r--r--Documentation/devicetree/bindings/sound/rt5663.txt60
-rw-r--r--Documentation/devicetree/bindings/sound/rt5665.txt68
-rw-r--r--Documentation/devicetree/bindings/sound/rt5668.txt50
-rw-r--r--Documentation/devicetree/bindings/sound/rt5677.txt76
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml153
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,arndale.yaml45
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml145
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,odroid.yaml92
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,odroidx2-max98090.txt35
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,smdk-wm8994.txt14
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,smdk5250.yaml38
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,snow.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/samsung,tm2.yaml82
-rw-r--r--Documentation/devicetree/bindings/sound/samsung-i2s.txt82
-rw-r--r--Documentation/devicetree/bindings/sound/samsung-i2s.yaml162
-rw-r--r--Documentation/devicetree/bindings/sound/serial-midi.yaml54
-rw-r--r--Documentation/devicetree/bindings/sound/sgtl5000.txt39
-rw-r--r--Documentation/devicetree/bindings/sound/simple-audio-amplifier.yaml45
-rw-r--r--Documentation/devicetree/bindings/sound/simple-audio-mux.yaml51
-rw-r--r--Documentation/devicetree/bindings/sound/simple-card.txt160
-rw-r--r--Documentation/devicetree/bindings/sound/simple-card.yaml571
-rw-r--r--Documentation/devicetree/bindings/sound/sirf-audio-codec.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/sirf-usp.txt27
-rw-r--r--Documentation/devicetree/bindings/sound/snow.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/snps,designware-i2s.yaml197
-rw-r--r--Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml102
-rw-r--r--Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml75
-rw-r--r--Documentation/devicetree/bindings/sound/sound-card-common.yaml34
-rw-r--r--Documentation/devicetree/bindings/sound/sound-dai.yaml20
-rw-r--r--Documentation/devicetree/bindings/sound/spacemit,k1-i2s.yaml87
-rw-r--r--Documentation/devicetree/bindings/sound/spdif-receiver.txt10
-rw-r--r--Documentation/devicetree/bindings/sound/spdif-transmitter.txt10
-rw-r--r--Documentation/devicetree/bindings/sound/sprd,pcm-platform.yaml56
-rw-r--r--Documentation/devicetree/bindings/sound/sprd,sc9860-mcdt.yaml47
-rw-r--r--Documentation/devicetree/bindings/sound/ssm2518.txt20
-rw-r--r--Documentation/devicetree/bindings/sound/st,sta32x.txt9
-rw-r--r--Documentation/devicetree/bindings/sound/st,sta350.txt2
-rw-r--r--Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt164
-rw-r--r--Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml139
-rw-r--r--Documentation/devicetree/bindings/sound/st,stm32-sai.yaml227
-rw-r--r--Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml91
-rw-r--r--Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/starfive,jh7110-tdm.yaml98
-rw-r--r--Documentation/devicetree/bindings/sound/tas2552.txt14
-rw-r--r--Documentation/devicetree/bindings/sound/tas5720.txt28
-rw-r--r--Documentation/devicetree/bindings/sound/tda7419.txt38
-rw-r--r--Documentation/devicetree/bindings/sound/tdm-slot.txt15
-rw-r--r--Documentation/devicetree/bindings/sound/test-component.yaml33
-rw-r--r--Documentation/devicetree/bindings/sound/ti,ads117x.txt11
-rw-r--r--Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml139
-rw-r--r--Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml145
-rw-r--r--Documentation/devicetree/bindings/sound/ti,omap-twl4030.yaml98
-rw-r--r--Documentation/devicetree/bindings/sound/ti,omap4-mcpdm.yaml73
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm1681.txt15
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm1681.yaml43
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm1754.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm1862.yaml76
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml108
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm512x.yaml101
-rw-r--r--Documentation/devicetree/bindings/sound/ti,pcm6240.yaml179
-rw-r--r--Documentation/devicetree/bindings/sound/ti,src4xxx.yaml48
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas2562.yaml83
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas2770.yaml90
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas2781.yaml299
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas27xx.yaml85
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas57xx.yaml137
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas5805m.yaml57
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tas6424.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tlv320adc3xxx.yaml164
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tlv320adcx140.yaml209
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tlv320aic32x4.yaml101
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tlv320aic3x.yaml166
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tlv320dac3100.yaml126
-rw-r--r--Documentation/devicetree/bindings/sound/ti,tpa6130a2.yaml55
-rw-r--r--Documentation/devicetree/bindings/sound/ti,ts3a227e.yaml94
-rw-r--r--Documentation/devicetree/bindings/sound/ti,twl4030-audio.yaml90
-rw-r--r--Documentation/devicetree/bindings/sound/tlv320aic31xx.txt61
-rw-r--r--Documentation/devicetree/bindings/sound/tlv320aic32x4.txt30
-rw-r--r--Documentation/devicetree/bindings/sound/tlv320aic3x.txt67
-rw-r--r--Documentation/devicetree/bindings/sound/tpa6130a2.txt27
-rw-r--r--Documentation/devicetree/bindings/sound/trivial-codec.yaml79
-rw-r--r--Documentation/devicetree/bindings/sound/ts3a227e.txt31
-rw-r--r--Documentation/devicetree/bindings/sound/tscs42xx.txt22
-rw-r--r--Documentation/devicetree/bindings/sound/tscs454.txt23
-rw-r--r--Documentation/devicetree/bindings/sound/uda1334.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/ux500-msp.txt1
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,arizona.yaml119
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8524.yaml40
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8731.yaml99
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8782.yaml47
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8804.yaml58
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8903.yaml115
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8904.yaml203
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8940.yaml60
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8960.yaml134
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8962.yaml124
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8978.yaml61
-rw-r--r--Documentation/devicetree/bindings/sound/wlf,wm8994.yaml194
-rw-r--r--Documentation/devicetree/bindings/sound/wm8510.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8523.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/wm8580.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/wm8711.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8728.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8731.txt27
-rw-r--r--Documentation/devicetree/bindings/sound/wm8737.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8741.txt13
-rw-r--r--Documentation/devicetree/bindings/sound/wm8750.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8753.txt40
-rw-r--r--Documentation/devicetree/bindings/sound/wm8770.txt16
-rw-r--r--Documentation/devicetree/bindings/sound/wm8776.txt18
-rw-r--r--Documentation/devicetree/bindings/sound/wm8804.txt25
-rw-r--r--Documentation/devicetree/bindings/sound/wm8903.txt69
-rw-r--r--Documentation/devicetree/bindings/sound/wm8904.txt33
-rw-r--r--Documentation/devicetree/bindings/sound/wm8960.txt31
-rw-r--r--Documentation/devicetree/bindings/sound/wm8962.txt39
-rw-r--r--Documentation/devicetree/bindings/sound/wm8994.txt78
-rw-r--r--Documentation/devicetree/bindings/sound/xlnx,audio-formatter.yaml72
-rw-r--r--Documentation/devicetree/bindings/sound/xlnx,i2s.yaml65
-rw-r--r--Documentation/devicetree/bindings/sound/xlnx,spdif.yaml77
-rw-r--r--Documentation/devicetree/bindings/sound/xmos,xvf3500.yaml63
-rw-r--r--Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml285
-rw-r--r--Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml86
-rw-r--r--Documentation/devicetree/bindings/spi/adi,axi-spi-engine.yaml90
-rw-r--r--Documentation/devicetree/bindings/spi/airoha,en7581-snand.yaml70
-rw-r--r--Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml84
-rw-r--r--Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml121
-rw-r--r--Documentation/devicetree/bindings/spi/amlogic,a1-spifc.yaml44
-rw-r--r--Documentation/devicetree/bindings/spi/amlogic,a4-spifc.yaml82
-rw-r--r--Documentation/devicetree/bindings/spi/amlogic,a4-spisg.yaml59
-rw-r--r--Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml116
-rw-r--r--Documentation/devicetree/bindings/spi/amlogic,meson6-spifc.yaml54
-rw-r--r--Documentation/devicetree/bindings/spi/apple,spi.yaml66
-rw-r--r--Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml61
-rw-r--r--Documentation/devicetree/bindings/spi/aspeed,ast2600-fmc.yaml84
-rw-r--r--Documentation/devicetree/bindings/spi/atmel,at91rm9200-spi.yaml93
-rw-r--r--Documentation/devicetree/bindings/spi/atmel,quadspi.yaml102
-rw-r--r--Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.yaml53
-rw-r--r--Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt22
-rw-r--r--Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.yaml50
-rw-r--r--Documentation/devicetree/bindings/spi/brcm,bcm63xx-hsspi.yaml134
-rw-r--r--Documentation/devicetree/bindings/spi/brcm,bcm63xx-spi.yaml71
-rw-r--r--Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml196
-rw-r--r--Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml42
-rw-r--r--Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml198
-rw-r--r--Documentation/devicetree/bindings/spi/cdns,xspi.yaml101
-rw-r--r--Documentation/devicetree/bindings/spi/cirrus,ep9301-spi.yaml70
-rw-r--r--Documentation/devicetree/bindings/spi/efm32-spi.txt41
-rw-r--r--Documentation/devicetree/bindings/spi/fsl,dspi-peripheral-props.yaml30
-rw-r--r--Documentation/devicetree/bindings/spi/fsl,dspi.yaml134
-rw-r--r--Documentation/devicetree/bindings/spi/fsl,espi.yaml65
-rw-r--r--Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml111
-rw-r--r--Documentation/devicetree/bindings/spi/fsl,spi.yaml74
-rw-r--r--Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt37
-rw-r--r--Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml106
-rw-r--r--Documentation/devicetree/bindings/spi/fsl-spi.txt60
-rw-r--r--Documentation/devicetree/bindings/spi/hpe,gxp-spifi.yaml56
-rw-r--r--Documentation/devicetree/bindings/spi/ibm,spi-fsi.yaml55
-rw-r--r--Documentation/devicetree/bindings/spi/icpdas-lp8841-spi-rtc.txt54
-rw-r--r--Documentation/devicetree/bindings/spi/ingenic,spi.yaml75
-rw-r--r--Documentation/devicetree/bindings/spi/jcore,spi.txt34
-rw-r--r--Documentation/devicetree/bindings/spi/loongson,ls2k-spi.yaml46
-rw-r--r--Documentation/devicetree/bindings/spi/marvell,armada-3700-spi.yaml55
-rw-r--r--Documentation/devicetree/bindings/spi/marvell,mmp2-ssp.yaml85
-rw-r--r--Documentation/devicetree/bindings/spi/marvell,orion-spi.yaml102
-rw-r--r--Documentation/devicetree/bindings/spi/mediatek,spi-mt65xx.yaml121
-rw-r--r--Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml99
-rw-r--r--Documentation/devicetree/bindings/spi/mediatek,spi-mtk-snfi.yaml124
-rw-r--r--Documentation/devicetree/bindings/spi/mediatek,spi-slave-mt27xx.yaml58
-rw-r--r--Documentation/devicetree/bindings/spi/microchip,mpfs-spi.yaml152
-rw-r--r--Documentation/devicetree/bindings/spi/microchip,spi-pic32.txt34
-rw-r--r--Documentation/devicetree/bindings/spi/mikrotik,rb4xx-spi.yaml38
-rw-r--r--Documentation/devicetree/bindings/spi/mxicy,mx25f0a-spi.yaml65
-rw-r--r--Documentation/devicetree/bindings/spi/mxs-spi.txt26
-rw-r--r--Documentation/devicetree/bindings/spi/mxs-spi.yaml59
-rw-r--r--Documentation/devicetree/bindings/spi/nuvoton,npcm-fiu.txt58
-rw-r--r--Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.yaml72
-rw-r--r--Documentation/devicetree/bindings/spi/nuvoton,wpcm450-fiu.yaml61
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt42
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.yaml100
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.txt38
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra20-sflash.yaml81
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.txt38
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra20-slink.yaml90
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra210-quad-peripheral-props.yaml32
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml111
-rw-r--r--Documentation/devicetree/bindings/spi/nxp,lpc3220-spi.yaml44
-rw-r--r--Documentation/devicetree/bindings/spi/nxp,sc18is.yaml51
-rw-r--r--Documentation/devicetree/bindings/spi/omap-spi.txt47
-rw-r--r--Documentation/devicetree/bindings/spi/omap-spi.yaml117
-rw-r--r--Documentation/devicetree/bindings/spi/qca,ar934x-spi.yaml43
-rw-r--r--Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.yaml119
-rw-r--r--Documentation/devicetree/bindings/spi/qcom,spi-qcom-qspi.yaml100
-rw-r--r--Documentation/devicetree/bindings/spi/qcom,spi-qpic-snand.yaml89
-rw-r--r--Documentation/devicetree/bindings/spi/qcom,spi-qup.txt103
-rw-r--r--Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml94
-rw-r--r--Documentation/devicetree/bindings/spi/ralink,mt7621-spi.yaml61
-rw-r--r--Documentation/devicetree/bindings/spi/realtek,rtl-spi.yaml41
-rw-r--r--Documentation/devicetree/bindings/spi/realtek,rtl9301-snand.yaml62
-rw-r--r--Documentation/devicetree/bindings/spi/renesas,hspi.yaml58
-rw-r--r--Documentation/devicetree/bindings/spi/renesas,rspi.yaml155
-rw-r--r--Documentation/devicetree/bindings/spi/renesas,rzv2h-rspi.yaml141
-rw-r--r--Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml79
-rw-r--r--Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml198
-rw-r--r--Documentation/devicetree/bindings/spi/rockchip-sfc.yaml93
-rw-r--r--Documentation/devicetree/bindings/spi/samsung,spi-peripheral-props.yaml33
-rw-r--r--Documentation/devicetree/bindings/spi/samsung,spi.yaml194
-rw-r--r--Documentation/devicetree/bindings/spi/sh-hspi.txt29
-rw-r--r--Documentation/devicetree/bindings/spi/sh-msiof.txt71
-rw-r--r--Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.txt28
-rw-r--r--Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml204
-rw-r--r--Documentation/devicetree/bindings/spi/socionext,f-ospi.yaml57
-rw-r--r--Documentation/devicetree/bindings/spi/socionext,synquacer-spi.yaml73
-rw-r--r--Documentation/devicetree/bindings/spi/socionext,uniphier-spi.yaml56
-rw-r--r--Documentation/devicetree/bindings/spi/spi-ath79.txt24
-rw-r--r--Documentation/devicetree/bindings/spi/spi-bus.txt95
-rw-r--r--Documentation/devicetree/bindings/spi/spi-cadence.txt31
-rw-r--r--Documentation/devicetree/bindings/spi/spi-cadence.yaml92
-rw-r--r--Documentation/devicetree/bindings/spi/spi-clps711x.txt32
-rw-r--r--Documentation/devicetree/bindings/spi/spi-controller.yaml216
-rw-r--r--Documentation/devicetree/bindings/spi/spi-davinci.txt22
-rw-r--r--Documentation/devicetree/bindings/spi/spi-dw.txt24
-rw-r--r--Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt57
-rw-r--r--Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml103
-rw-r--r--Documentation/devicetree/bindings/spi/spi-gpio.txt31
-rw-r--r--Documentation/devicetree/bindings/spi/spi-gpio.yaml74
-rw-r--r--Documentation/devicetree/bindings/spi/spi-img-spfi.txt1
-rw-r--r--Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt46
-rw-r--r--Documentation/devicetree/bindings/spi/spi-meson.txt22
-rw-r--r--Documentation/devicetree/bindings/spi/spi-mux.yaml87
-rw-r--r--Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml97
-rw-r--r--Documentation/devicetree/bindings/spi/spi-orion.txt19
-rw-r--r--Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml131
-rw-r--r--Documentation/devicetree/bindings/spi/spi-pl022.yaml111
-rw-r--r--Documentation/devicetree/bindings/spi/spi-rockchip.txt45
-rw-r--r--Documentation/devicetree/bindings/spi/spi-rockchip.yaml120
-rw-r--r--Documentation/devicetree/bindings/spi/spi-rspi.txt69
-rw-r--r--Documentation/devicetree/bindings/spi/spi-samsung.txt109
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sc18is602.txt23
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sg2044-nor.yaml54
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sifive.yaml87
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sirf.txt41
-rw-r--r--Documentation/devicetree/bindings/spi/spi-st-ssc.txt40
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sun4i.txt24
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sun6i.txt24
-rw-r--r--Documentation/devicetree/bindings/spi/spi-sunplus-sp7021.yaml78
-rw-r--r--Documentation/devicetree/bindings/spi/spi-xilinx.yaml55
-rw-r--r--Documentation/devicetree/bindings/spi/spi-zynqmp-qspi.yaml81
-rw-r--r--Documentation/devicetree/bindings/spi/spi_atmel.txt31
-rw-r--r--Documentation/devicetree/bindings/spi/spi_pl022.txt70
-rw-r--r--Documentation/devicetree/bindings/spi/sprd,sc9860-spi.yaml72
-rw-r--r--Documentation/devicetree/bindings/spi/sprd,spi-adi.yaml103
-rw-r--r--Documentation/devicetree/bindings/spi/sqi-pic32.txt18
-rw-r--r--Documentation/devicetree/bindings/spi/st,ssc-spi.yaml61
-rw-r--r--Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml89
-rw-r--r--Documentation/devicetree/bindings/spi/st,stm32-spi.yaml130
-rw-r--r--Documentation/devicetree/bindings/spi/st,stm32mp25-ospi.yaml106
-rw-r--r--Documentation/devicetree/bindings/spi/ti,qspi.yaml96
-rw-r--r--Documentation/devicetree/bindings/spi/ti_qspi.txt28
-rw-r--r--Documentation/devicetree/bindings/spi/xlnx,zynq-qspi.yaml59
-rw-r--r--Documentation/devicetree/bindings/spmi/apple,spmi.yaml57
-rw-r--r--Documentation/devicetree/bindings/spmi/hisilicon,hisi-spmi-controller.yaml70
-rw-r--r--Documentation/devicetree/bindings/spmi/mtk,spmi-mtk-pmif.yaml82
-rw-r--r--Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt65
-rw-r--r--Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.yaml128
-rw-r--r--Documentation/devicetree/bindings/spmi/qcom,x1e80100-spmi-pmic-arb.yaml140
-rw-r--r--Documentation/devicetree/bindings/spmi/spmi.txt41
-rw-r--r--Documentation/devicetree/bindings/spmi/spmi.yaml75
-rw-r--r--Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml163
-rw-r--r--Documentation/devicetree/bindings/sram/qcom,imem.yaml99
-rw-r--r--Documentation/devicetree/bindings/sram/qcom,ocmem.yaml123
-rw-r--r--Documentation/devicetree/bindings/sram/sram.yaml306
-rw-r--r--Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt16
-rw-r--r--Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt47
-rw-r--r--Documentation/devicetree/bindings/staging/iio/adc/spear-adc.txt26
-rw-r--r--Documentation/devicetree/bindings/submitting-patches.rst114
-rw-r--r--Documentation/devicetree/bindings/submitting-patches.txt67
-rw-r--r--Documentation/devicetree/bindings/thermal/airoha,en7581-thermal.yaml48
-rw-r--r--Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml179
-rw-r--r--Documentation/devicetree/bindings/thermal/amazon,al-thermal.yaml50
-rw-r--r--Documentation/devicetree/bindings/thermal/amlogic,thermal.yaml65
-rw-r--r--Documentation/devicetree/bindings/thermal/armada-thermal.txt24
-rw-r--r--Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml48
-rw-r--r--Documentation/devicetree/bindings/thermal/brcm,avs-tmon.yaml56
-rw-r--r--Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.yaml47
-rw-r--r--Documentation/devicetree/bindings/thermal/brcm,ns-thermal.yaml60
-rw-r--r--Documentation/devicetree/bindings/thermal/brcm,sr-thermal.yaml121
-rw-r--r--Documentation/devicetree/bindings/thermal/db8500-thermal.txt44
-rw-r--r--Documentation/devicetree/bindings/thermal/dlg,da9062-thermal.yaml35
-rw-r--r--Documentation/devicetree/bindings/thermal/exynos-thermal.txt121
-rw-r--r--Documentation/devicetree/bindings/thermal/fsl,imx91-tmu.yaml87
-rw-r--r--Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml39
-rw-r--r--Documentation/devicetree/bindings/thermal/generic-adc-thermal.yaml85
-rw-r--r--Documentation/devicetree/bindings/thermal/hisilicon,tsensor.yaml57
-rw-r--r--Documentation/devicetree/bindings/thermal/imx-thermal.txt24
-rw-r--r--Documentation/devicetree/bindings/thermal/imx-thermal.yaml114
-rw-r--r--Documentation/devicetree/bindings/thermal/imx8mm-thermal.yaml72
-rw-r--r--Documentation/devicetree/bindings/thermal/loongson,ls2k-thermal.yaml71
-rw-r--r--Documentation/devicetree/bindings/thermal/marvell,armada-ap806-thermal.yaml46
-rw-r--r--Documentation/devicetree/bindings/thermal/marvell,armada370-thermal.yaml37
-rw-r--r--Documentation/devicetree/bindings/thermal/max77620_thermal.txt70
-rw-r--r--Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml148
-rw-r--r--Documentation/devicetree/bindings/thermal/mediatek,thermal.yaml106
-rw-r--r--Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml388
-rw-r--r--Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.yaml34
-rw-r--r--Documentation/devicetree/bindings/thermal/nvidia,tegra30-tsensor.yaml70
-rw-r--r--Documentation/devicetree/bindings/thermal/qcom,spmi-temp-alarm.yaml84
-rw-r--r--Documentation/devicetree/bindings/thermal/qcom-lmh.yaml88
-rw-r--r--Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm-hc.yaml149
-rw-r--r--Documentation/devicetree/bindings/thermal/qcom-spmi-adc-tm5.yaml263
-rw-r--r--Documentation/devicetree/bindings/thermal/qcom-tsens.yaml441
-rw-r--r--Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml118
-rw-r--r--Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.yaml153
-rw-r--r--Documentation/devicetree/bindings/thermal/rcar-thermal.txt38
-rw-r--r--Documentation/devicetree/bindings/thermal/rcar-thermal.yaml155
-rw-r--r--Documentation/devicetree/bindings/thermal/renesas,r9a08g045-tsu.yaml93
-rw-r--r--Documentation/devicetree/bindings/thermal/renesas,r9a09g047-tsu.yaml91
-rw-r--r--Documentation/devicetree/bindings/thermal/rockchip-thermal.txt68
-rw-r--r--Documentation/devicetree/bindings/thermal/rockchip-thermal.yaml178
-rw-r--r--Documentation/devicetree/bindings/thermal/rzg2l-thermal.yaml79
-rw-r--r--Documentation/devicetree/bindings/thermal/samsung,exynos-thermal.yaml185
-rw-r--r--Documentation/devicetree/bindings/thermal/socionext,uniphier-thermal.yaml55
-rw-r--r--Documentation/devicetree/bindings/thermal/sprd-thermal.yaml112
-rw-r--r--Documentation/devicetree/bindings/thermal/st,stih407-thermal.yaml58
-rw-r--r--Documentation/devicetree/bindings/thermal/st,stm32-thermal.yaml80
-rw-r--r--Documentation/devicetree/bindings/thermal/st-thermal.txt42
-rw-r--r--Documentation/devicetree/bindings/thermal/tegra-soctherm.txt55
-rw-r--r--Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml122
-rw-r--r--Documentation/devicetree/bindings/thermal/thermal-idle.yaml152
-rw-r--r--Documentation/devicetree/bindings/thermal/thermal-sensor.yaml77
-rw-r--r--Documentation/devicetree/bindings/thermal/thermal-zones.yaml359
-rw-r--r--Documentation/devicetree/bindings/thermal/thermal.txt595
-rw-r--r--Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml57
-rw-r--r--Documentation/devicetree/bindings/thermal/ti,j72xx-thermal.yaml97
-rw-r--r--Documentation/devicetree/bindings/thermal/ti_soc_thermal.txt14
-rw-r--r--Documentation/devicetree/bindings/timer/actions,owl-timer.yaml107
-rw-r--r--Documentation/devicetree/bindings/timer/allwinner,sun4i-a10-timer.yaml101
-rw-r--r--Documentation/devicetree/bindings/timer/allwinner,sun4i-timer.txt17
-rw-r--r--Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.txt26
-rw-r--r--Documentation/devicetree/bindings/timer/allwinner,sun5i-a13-hstimer.yaml77
-rw-r--r--Documentation/devicetree/bindings/timer/altr,timer-1.0.yaml39
-rw-r--r--Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt15
-rw-r--r--Documentation/devicetree/bindings/timer/amlogic,meson6-timer.yaml54
-rw-r--r--Documentation/devicetree/bindings/timer/andestech,plmt0.yaml53
-rw-r--r--Documentation/devicetree/bindings/timer/arm,arch_timer.yaml128
-rw-r--r--Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml123
-rw-r--r--Documentation/devicetree/bindings/timer/arm,armv7m-systick.yaml54
-rw-r--r--Documentation/devicetree/bindings/timer/arm,global_timer.yaml48
-rw-r--r--Documentation/devicetree/bindings/timer/arm,mps2-timer.yaml49
-rw-r--r--Documentation/devicetree/bindings/timer/arm,sp804.txt29
-rw-r--r--Documentation/devicetree/bindings/timer/arm,sp804.yaml97
-rw-r--r--Documentation/devicetree/bindings/timer/arm,twd-timer.yaml56
-rw-r--r--Documentation/devicetree/bindings/timer/brcm,bcm2835-system-timer.txt22
-rw-r--r--Documentation/devicetree/bindings/timer/brcm,bcm2835-system-timer.yaml50
-rw-r--r--Documentation/devicetree/bindings/timer/brcm,bcmbca-timer.yaml40
-rw-r--r--Documentation/devicetree/bindings/timer/brcm,kona-timer.txt25
-rw-r--r--Documentation/devicetree/bindings/timer/brcm,kona-timer.yaml52
-rw-r--r--Documentation/devicetree/bindings/timer/cadence,ttc-timer.txt17
-rw-r--r--Documentation/devicetree/bindings/timer/cdns,ttc.yaml72
-rw-r--r--Documentation/devicetree/bindings/timer/cirrus,clps711x-timer.txt29
-rw-r--r--Documentation/devicetree/bindings/timer/cirrus,clps711x-timer.yaml45
-rw-r--r--Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml49
-rw-r--r--Documentation/devicetree/bindings/timer/cnxt,cx92755-timer.yaml49
-rw-r--r--Documentation/devicetree/bindings/timer/csky,gx6605s-timer.yaml40
-rw-r--r--Documentation/devicetree/bindings/timer/csky,mptimer.yaml46
-rw-r--r--Documentation/devicetree/bindings/timer/digicolor-timer.txt18
-rw-r--r--Documentation/devicetree/bindings/timer/econet,en751221-timer.yaml80
-rw-r--r--Documentation/devicetree/bindings/timer/energymicro,efm32-timer.txt23
-rw-r--r--Documentation/devicetree/bindings/timer/ezchip,nps400-timer.yaml45
-rw-r--r--Documentation/devicetree/bindings/timer/faraday,fttmr010.yaml89
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,ftm-timer.txt31
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,ftm-timer.yaml62
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,gtm.yaml83
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,imxgpt.txt18
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml108
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,timrot.yaml48
-rw-r--r--Documentation/devicetree/bindings/timer/fsl,vf610-pit.yaml59
-rw-r--r--Documentation/devicetree/bindings/timer/hpe,gxp-timer.yaml47
-rw-r--r--Documentation/devicetree/bindings/timer/img,pistachio-gptimer.yaml69
-rw-r--r--Documentation/devicetree/bindings/timer/ingenic,sysost.yaml63
-rw-r--r--Documentation/devicetree/bindings/timer/ingenic,tcu.yaml302
-rw-r--r--Documentation/devicetree/bindings/timer/intel,ixp4xx-timer.yaml43
-rw-r--r--Documentation/devicetree/bindings/timer/jcore,pit.yaml43
-rw-r--r--Documentation/devicetree/bindings/timer/loongson,ls1x-pwmtimer.yaml48
-rw-r--r--Documentation/devicetree/bindings/timer/lsi,zevio-timer.txt33
-rw-r--r--Documentation/devicetree/bindings/timer/lsi,zevio-timer.yaml56
-rw-r--r--Documentation/devicetree/bindings/timer/marvell,armada-370-timer.yaml88
-rw-r--r--Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt44
-rw-r--r--Documentation/devicetree/bindings/timer/marvell,orion-timer.txt17
-rw-r--r--Documentation/devicetree/bindings/timer/marvell,orion-timer.yaml43
-rw-r--r--Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt17
-rw-r--r--Documentation/devicetree/bindings/timer/mediatek,timer.yaml87
-rw-r--r--Documentation/devicetree/bindings/timer/moxa,moxart-timer.txt17
-rw-r--r--Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml46
-rw-r--r--Documentation/devicetree/bindings/timer/mstar,msc313e-timer.yaml46
-rw-r--r--Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.yaml54
-rw-r--r--Documentation/devicetree/bindings/timer/nvidia,tegra-timer.yaml149
-rw-r--r--Documentation/devicetree/bindings/timer/nvidia,tegra186-timer.yaml108
-rw-r--r--Documentation/devicetree/bindings/timer/nvidia,tegra20-timer.txt24
-rw-r--r--Documentation/devicetree/bindings/timer/nvidia,tegra30-timer.txt28
-rw-r--r--Documentation/devicetree/bindings/timer/nxp,lpc3220-timer.yaml55
-rw-r--r--Documentation/devicetree/bindings/timer/nxp,s32g2-stm.yaml64
-rw-r--r--Documentation/devicetree/bindings/timer/nxp,sysctr-timer.yaml65
-rw-r--r--Documentation/devicetree/bindings/timer/nxp,tpm-timer.yaml65
-rw-r--r--Documentation/devicetree/bindings/timer/ralink,cevt-systick.yaml38
-rw-r--r--Documentation/devicetree/bindings/timer/ralink,rt2880-timer.yaml44
-rw-r--r--Documentation/devicetree/bindings/timer/rda,8810pl-timer.yaml47
-rw-r--r--Documentation/devicetree/bindings/timer/realtek,otto-timer.yaml63
-rw-r--r--Documentation/devicetree/bindings/timer/realtek,rtd1625-systimer.yaml47
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,cmt.txt79
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,cmt.yaml206
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,em-sti.yaml46
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,mtu2.txt42
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,mtu2.yaml76
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,ostm.yaml79
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml306
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,tmu.txt44
-rw-r--r--Documentation/devicetree/bindings/timer/renesas,tmu.yaml136
-rw-r--r--Documentation/devicetree/bindings/timer/riscv,timer.yaml52
-rw-r--r--Documentation/devicetree/bindings/timer/rockchip,rk-timer.yaml66
-rw-r--r--Documentation/devicetree/bindings/timer/rockchip,rk3288-timer.txt18
-rw-r--r--Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt88
-rw-r--r--Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.yaml247
-rw-r--r--Documentation/devicetree/bindings/timer/sifive,clint.yaml106
-rw-r--r--Documentation/devicetree/bindings/timer/snps,arc-timer.yaml45
-rw-r--r--Documentation/devicetree/bindings/timer/snps,archs-gfrc.yaml30
-rw-r--r--Documentation/devicetree/bindings/timer/snps,archs-rtc.yaml30
-rw-r--r--Documentation/devicetree/bindings/timer/snps,dw-apb-timer.yaml84
-rw-r--r--Documentation/devicetree/bindings/timer/socionext,milbeaut-timer.yaml40
-rw-r--r--Documentation/devicetree/bindings/timer/sprd,sc9860-timer.yaml68
-rw-r--r--Documentation/devicetree/bindings/timer/st,nomadik-mtu.yaml58
-rw-r--r--Documentation/devicetree/bindings/timer/st,spear-timer.yaml36
-rw-r--r--Documentation/devicetree/bindings/timer/st,stih407-lpc28
-rw-r--r--Documentation/devicetree/bindings/timer/st,stm32-timer.yaml48
-rw-r--r--Documentation/devicetree/bindings/timer/stericsson-u300-apptimer.txt18
-rw-r--r--Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml56
-rw-r--r--Documentation/devicetree/bindings/timer/ti,da830-timer.yaml68
-rw-r--r--Documentation/devicetree/bindings/timer/ti,keystone-timer.txt29
-rw-r--r--Documentation/devicetree/bindings/timer/ti,keystone-timer.yaml63
-rw-r--r--Documentation/devicetree/bindings/timer/ti,timer-dm.yaml159
-rw-r--r--Documentation/devicetree/bindings/timer/via,vt8500-timer.yaml51
-rw-r--r--Documentation/devicetree/bindings/timer/xlnx,xps-timer.yaml92
-rw-r--r--Documentation/devicetree/bindings/timestamp/hardware-timestamps-common.yaml29
-rw-r--r--Documentation/devicetree/bindings/timestamp/hte-consumer.yaml39
-rw-r--r--Documentation/devicetree/bindings/timestamp/nvidia,tegra194-hte.yaml140
-rw-r--r--Documentation/devicetree/bindings/tpm/google,cr50.yaml65
-rw-r--r--Documentation/devicetree/bindings/tpm/ibm,vtpm.yaml104
-rw-r--r--Documentation/devicetree/bindings/tpm/microsoft,ftpm.yaml47
-rw-r--r--Documentation/devicetree/bindings/tpm/tcg,tpm-tis-i2c.yaml91
-rw-r--r--Documentation/devicetree/bindings/tpm/tcg,tpm-tis-mmio.yaml49
-rw-r--r--Documentation/devicetree/bindings/tpm/tcg,tpm_tis-spi.yaml76
-rw-r--r--Documentation/devicetree/bindings/tpm/tpm-common.yaml87
-rw-r--r--Documentation/devicetree/bindings/trigger-source/adi,util-sigma-delta-spi.yaml49
-rw-r--r--Documentation/devicetree/bindings/trigger-source/gpio-trigger.yaml40
-rw-r--r--Documentation/devicetree/bindings/trigger-source/pwm-trigger.yaml37
-rw-r--r--Documentation/devicetree/bindings/trivial-devices.yaml500
-rw-r--r--Documentation/devicetree/bindings/ufs/amd,versal2-ufs.yaml61
-rw-r--r--Documentation/devicetree/bindings/ufs/cdns,ufshc.yaml73
-rw-r--r--Documentation/devicetree/bindings/ufs/hisilicon,ufs.yaml90
-rw-r--r--Documentation/devicetree/bindings/ufs/mediatek,ufs.yaml102
-rw-r--r--Documentation/devicetree/bindings/ufs/qcom,sc7180-ufshc.yaml167
-rw-r--r--Documentation/devicetree/bindings/ufs/qcom,sm8650-ufshc.yaml180
-rw-r--r--Documentation/devicetree/bindings/ufs/qcom,ufs-common.yaml67
-rw-r--r--Documentation/devicetree/bindings/ufs/qcom,ufs.yaml240
-rw-r--r--Documentation/devicetree/bindings/ufs/renesas,ufs.yaml73
-rw-r--r--Documentation/devicetree/bindings/ufs/rockchip,rk3576-ufshc.yaml105
-rw-r--r--Documentation/devicetree/bindings/ufs/samsung,exynos-ufs.yaml133
-rw-r--r--Documentation/devicetree/bindings/ufs/snps,tc-dwc-g210.yaml51
-rw-r--r--Documentation/devicetree/bindings/ufs/sprd,ums9620-ufs.yaml79
-rw-r--r--Documentation/devicetree/bindings/ufs/ti,j721e-ufs.yaml90
-rw-r--r--Documentation/devicetree/bindings/ufs/ufs-common.yaml129
-rw-r--r--Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt57
-rw-r--r--Documentation/devicetree/bindings/unittest.txt5
-rw-r--r--Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.yaml108
-rw-r--r--Documentation/devicetree/bindings/usb/am33xx-usb.txt15
-rw-r--r--Documentation/devicetree/bindings/usb/amlogic,meson-g12a-usb-ctrl.yaml237
-rw-r--r--Documentation/devicetree/bindings/usb/analogix,anx7411.yaml70
-rw-r--r--Documentation/devicetree/bindings/usb/apple,dwc3.yaml80
-rw-r--r--Documentation/devicetree/bindings/usb/aspeed,ast2600-udc.yaml52
-rw-r--r--Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml139
-rw-r--r--Documentation/devicetree/bindings/usb/atmel-usb.txt101
-rw-r--r--Documentation/devicetree/bindings/usb/brcm,bcm3384-usb.txt11
-rw-r--r--Documentation/devicetree/bindings/usb/brcm,bcm7445-ehci.yaml59
-rw-r--r--Documentation/devicetree/bindings/usb/brcm,bdc.yaml50
-rw-r--r--Documentation/devicetree/bindings/usb/brcm,usb-pinmap.yaml73
-rw-r--r--Documentation/devicetree/bindings/usb/cdns,usb3.yaml111
-rw-r--r--Documentation/devicetree/bindings/usb/chipidea,usb2-common.yaml203
-rw-r--r--Documentation/devicetree/bindings/usb/chipidea,usb2-imx.yaml309
-rw-r--r--Documentation/devicetree/bindings/usb/ci-hdrc-imx.txt35
-rw-r--r--Documentation/devicetree/bindings/usb/ci-hdrc-qcom.txt17
-rw-r--r--Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt24
-rw-r--r--Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml121
-rw-r--r--Documentation/devicetree/bindings/usb/ci-hdrc-zevio.txt17
-rw-r--r--Documentation/devicetree/bindings/usb/cypress,cypd4226.yaml93
-rw-r--r--Documentation/devicetree/bindings/usb/cypress,hx3.yaml89
-rw-r--r--Documentation/devicetree/bindings/usb/da8xx-usb.txt81
-rw-r--r--Documentation/devicetree/bindings/usb/dwc2.txt38
-rw-r--r--Documentation/devicetree/bindings/usb/dwc2.yaml205
-rw-r--r--Documentation/devicetree/bindings/usb/dwc3-cavium.txt28
-rw-r--r--Documentation/devicetree/bindings/usb/dwc3-st.txt18
-rw-r--r--Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml158
-rw-r--r--Documentation/devicetree/bindings/usb/dwc3.txt50
-rw-r--r--Documentation/devicetree/bindings/usb/ehci-omap.txt32
-rw-r--r--Documentation/devicetree/bindings/usb/ehci-orion.txt20
-rw-r--r--Documentation/devicetree/bindings/usb/ehci-st.txt7
-rw-r--r--Documentation/devicetree/bindings/usb/eswin,eic7700-usb.yaml94
-rw-r--r--Documentation/devicetree/bindings/usb/exynos-usb.txt117
-rw-r--r--Documentation/devicetree/bindings/usb/faraday,fotg210.yaml78
-rw-r--r--Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml108
-rw-r--r--Documentation/devicetree/bindings/usb/fcs,fusb302.yaml67
-rw-r--r--Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml143
-rw-r--r--Documentation/devicetree/bindings/usb/fsl,imx8mq-dwc3.yaml48
-rw-r--r--Documentation/devicetree/bindings/usb/fsl,imx8qm-cdns3.yaml103
-rw-r--r--Documentation/devicetree/bindings/usb/fsl,ls1028a.yaml55
-rw-r--r--Documentation/devicetree/bindings/usb/fsl,usb2.yaml95
-rw-r--r--Documentation/devicetree/bindings/usb/fsl,usbmisc.yaml93
-rw-r--r--Documentation/devicetree/bindings/usb/fsl-usb.txt83
-rw-r--r--Documentation/devicetree/bindings/usb/generic-ehci.yaml190
-rw-r--r--Documentation/devicetree/bindings/usb/generic-ohci.yaml182
-rw-r--r--Documentation/devicetree/bindings/usb/generic-xhci.yaml97
-rw-r--r--Documentation/devicetree/bindings/usb/generic.txt24
-rw-r--r--Documentation/devicetree/bindings/usb/genesys,gl850g.yaml113
-rw-r--r--Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml116
-rw-r--r--Documentation/devicetree/bindings/usb/hisilicon,hi3798mv200-dwc3.yaml99
-rw-r--r--Documentation/devicetree/bindings/usb/hisilicon,histb-xhci.txt45
-rw-r--r--Documentation/devicetree/bindings/usb/ingenic,musb.yaml79
-rw-r--r--Documentation/devicetree/bindings/usb/intel,ixp4xx-udc.yaml39
-rw-r--r--Documentation/devicetree/bindings/usb/intel,keembay-dwc3.yaml77
-rw-r--r--Documentation/devicetree/bindings/usb/iproc-udc.txt21
-rw-r--r--Documentation/devicetree/bindings/usb/isp1301.txt25
-rw-r--r--Documentation/devicetree/bindings/usb/ite,it5205.yaml72
-rw-r--r--Documentation/devicetree/bindings/usb/keystone-phy.txt20
-rw-r--r--Documentation/devicetree/bindings/usb/keystone-usb.txt42
-rw-r--r--Documentation/devicetree/bindings/usb/lpc32xx-udc.txt28
-rw-r--r--Documentation/devicetree/bindings/usb/marvell,pxau2o-ehci.yaml62
-rw-r--r--Documentation/devicetree/bindings/usb/maxim,max33359.yaml81
-rw-r--r--Documentation/devicetree/bindings/usb/maxim,max3420-udc.yaml67
-rw-r--r--Documentation/devicetree/bindings/usb/maxim,max3421.txt23
-rw-r--r--Documentation/devicetree/bindings/usb/mediatek,mt6360-tcpc.yaml100
-rw-r--r--Documentation/devicetree/bindings/usb/mediatek,mt6370-tcpc.yaml36
-rw-r--r--Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml233
-rw-r--r--Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml354
-rw-r--r--Documentation/devicetree/bindings/usb/mediatek,musb.yaml115
-rw-r--r--Documentation/devicetree/bindings/usb/microchip,mpfs-musb.yaml69
-rw-r--r--Documentation/devicetree/bindings/usb/microchip,usb2514.yaml90
-rw-r--r--Documentation/devicetree/bindings/usb/microchip,usb5744.yaml110
-rw-r--r--Documentation/devicetree/bindings/usb/msm-hsusb.txt95
-rw-r--r--Documentation/devicetree/bindings/usb/mxs-phy.txt21
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra-xudc.yaml211
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.yaml200
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra186-xusb.yaml171
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra194-xusb.yaml175
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt23
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt72
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra210-xusb.yaml195
-rw-r--r--Documentation/devicetree/bindings/usb/nvidia,tegra234-xusb.yaml186
-rw-r--r--Documentation/devicetree/bindings/usb/nxp,isp1760.yaml67
-rw-r--r--Documentation/devicetree/bindings/usb/nxp,lpc3220-udc.yaml50
-rw-r--r--Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml93
-rw-r--r--Documentation/devicetree/bindings/usb/nxp,ptn5110.yaml74
-rw-r--r--Documentation/devicetree/bindings/usb/octeon-usb.txt62
-rw-r--r--Documentation/devicetree/bindings/usb/ohci-da8xx.txt23
-rw-r--r--Documentation/devicetree/bindings/usb/ohci-nxp.txt24
-rw-r--r--Documentation/devicetree/bindings/usb/ohci-omap3.txt15
-rw-r--r--Documentation/devicetree/bindings/usb/ohci-st.txt5
-rw-r--r--Documentation/devicetree/bindings/usb/omap-usb.txt2
-rw-r--r--Documentation/devicetree/bindings/usb/onnn,nb7vpq904m.yaml139
-rw-r--r--Documentation/devicetree/bindings/usb/parade,ps5511.yaml108
-rw-r--r--Documentation/devicetree/bindings/usb/parade,ps8830.yaml144
-rw-r--r--Documentation/devicetree/bindings/usb/pxa-usb.txt2
-rw-r--r--Documentation/devicetree/bindings/usb/qcom,dwc3.txt66
-rw-r--r--Documentation/devicetree/bindings/usb/qcom,dwc3.yaml641
-rw-r--r--Documentation/devicetree/bindings/usb/qcom,pmic-typec.yaml248
-rw-r--r--Documentation/devicetree/bindings/usb/qcom,snps-dwc3.yaml660
-rw-r--r--Documentation/devicetree/bindings/usb/qcom,wcd939x-usbss.yaml101
-rw-r--r--Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml80
-rw-r--r--Documentation/devicetree/bindings/usb/realtek,rtd-type-c.yaml82
-rw-r--r--Documentation/devicetree/bindings/usb/realtek,rts5411.yaml92
-rw-r--r--Documentation/devicetree/bindings/usb/renesas,rzg3e-xhci.yaml95
-rw-r--r--Documentation/devicetree/bindings/usb/renesas,rzn1-usbf.yaml68
-rw-r--r--Documentation/devicetree/bindings/usb/renesas,rzv2m-usb3drd.yaml129
-rw-r--r--Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml119
-rw-r--r--Documentation/devicetree/bindings/usb/renesas,usb3-peri.yaml150
-rw-r--r--Documentation/devicetree/bindings/usb/renesas,usbhs.yaml183
-rw-r--r--Documentation/devicetree/bindings/usb/renesas_usbhs.txt29
-rw-r--r--Documentation/devicetree/bindings/usb/richtek,rt1711h.txt44
-rw-r--r--Documentation/devicetree/bindings/usb/richtek,rt1711h.yaml103
-rw-r--r--Documentation/devicetree/bindings/usb/richtek,rt1719.yaml85
-rw-r--r--Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml181
-rw-r--r--Documentation/devicetree/bindings/usb/rockchip,rk3399-dwc3.yaml115
-rw-r--r--Documentation/devicetree/bindings/usb/samsung,exynos-dwc3.yaml229
-rw-r--r--Documentation/devicetree/bindings/usb/samsung,exynos-usb2.yaml107
-rw-r--r--Documentation/devicetree/bindings/usb/samsung-hsotg.txt40
-rw-r--r--Documentation/devicetree/bindings/usb/samsung-usbphy.txt117
-rw-r--r--Documentation/devicetree/bindings/usb/smsc,usb3503.yaml159
-rw-r--r--Documentation/devicetree/bindings/usb/snps,dwc3-common.yaml432
-rw-r--r--Documentation/devicetree/bindings/usb/snps,dwc3.yaml106
-rw-r--r--Documentation/devicetree/bindings/usb/spacemit,k1-dwc3.yaml121
-rw-r--r--Documentation/devicetree/bindings/usb/spear-usb.txt39
-rw-r--r--Documentation/devicetree/bindings/usb/st,stusb160x.yaml91
-rw-r--r--Documentation/devicetree/bindings/usb/st,typec-stm32g0.yaml91
-rw-r--r--Documentation/devicetree/bindings/usb/starfive,jh7110-usb.yaml115
-rw-r--r--Documentation/devicetree/bindings/usb/ti,am62-usb.yaml107
-rw-r--r--Documentation/devicetree/bindings/usb/ti,hd3ss3220.yaml89
-rw-r--r--Documentation/devicetree/bindings/usb/ti,j721e-usb.yaml112
-rw-r--r--Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml92
-rw-r--r--Documentation/devicetree/bindings/usb/ti,tps6598x.yaml159
-rw-r--r--Documentation/devicetree/bindings/usb/ti,tusb1046.yaml50
-rw-r--r--Documentation/devicetree/bindings/usb/ti,tusb73x0-pci.yaml55
-rw-r--r--Documentation/devicetree/bindings/usb/ti,twl4030-usb.yaml74
-rw-r--r--Documentation/devicetree/bindings/usb/ti,twl6030-usb.yaml48
-rw-r--r--Documentation/devicetree/bindings/usb/ti,usb8020b.yaml69
-rw-r--r--Documentation/devicetree/bindings/usb/ti,usb8041.yaml69
-rw-r--r--Documentation/devicetree/bindings/usb/twlxxxx-usb.txt40
-rw-r--r--Documentation/devicetree/bindings/usb/udc-xilinx.txt18
-rw-r--r--Documentation/devicetree/bindings/usb/ulpi.txt20
-rw-r--r--Documentation/devicetree/bindings/usb/usb-device.yaml126
-rw-r--r--Documentation/devicetree/bindings/usb/usb-drd.yaml79
-rw-r--r--Documentation/devicetree/bindings/usb/usb-ehci.txt38
-rw-r--r--Documentation/devicetree/bindings/usb/usb-hcd.yaml52
-rw-r--r--Documentation/devicetree/bindings/usb/usb-hub.yaml84
-rw-r--r--Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt41
-rw-r--r--Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml73
-rw-r--r--Documentation/devicetree/bindings/usb/usb-ohci.txt28
-rw-r--r--Documentation/devicetree/bindings/usb/usb-switch-ports.yaml68
-rw-r--r--Documentation/devicetree/bindings/usb/usb-switch.yaml28
-rw-r--r--Documentation/devicetree/bindings/usb/usb-uhci.txt15
-rw-r--r--Documentation/devicetree/bindings/usb/usb-uhci.yaml88
-rw-r--r--Documentation/devicetree/bindings/usb/usb-xhci.txt21
-rw-r--r--Documentation/devicetree/bindings/usb/usb-xhci.yaml48
-rw-r--r--Documentation/devicetree/bindings/usb/usb.yaml64
-rw-r--r--Documentation/devicetree/bindings/usb/usb251xb.yaml278
-rw-r--r--Documentation/devicetree/bindings/usb/usb3503.txt36
-rw-r--r--Documentation/devicetree/bindings/usb/usb4604.txt19
-rw-r--r--Documentation/devicetree/bindings/usb/usbmisc-imx.txt16
-rw-r--r--Documentation/devicetree/bindings/usb/vialab,vl817.yaml70
-rw-r--r--Documentation/devicetree/bindings/usb/willsemi,wusb3801.yaml76
-rw-r--r--Documentation/devicetree/bindings/usb/xlnx,usb2.yaml47
-rw-r--r--Documentation/devicetree/bindings/vendor-prefixes.txt213
-rw-r--r--Documentation/devicetree/bindings/vendor-prefixes.yaml1911
-rw-r--r--Documentation/devicetree/bindings/video/adi,adv7123.txt50
-rw-r--r--Documentation/devicetree/bindings/video/adi,adv7511.txt88
-rw-r--r--Documentation/devicetree/bindings/video/analog-tv-connector.txt25
-rw-r--r--Documentation/devicetree/bindings/video/arm,pl11x.txt109
-rw-r--r--Documentation/devicetree/bindings/video/atmel,lcdc.txt89
-rw-r--r--Documentation/devicetree/bindings/video/backlight/gpio-backlight.txt16
-rw-r--r--Documentation/devicetree/bindings/video/backlight/lp855x.txt70
-rw-r--r--Documentation/devicetree/bindings/video/backlight/max8925-backlight.txt10
-rw-r--r--Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt35
-rw-r--r--Documentation/devicetree/bindings/video/bridge/ps8622.txt31
-rw-r--r--Documentation/devicetree/bindings/video/bridge/ptn3460.txt39
-rw-r--r--Documentation/devicetree/bindings/video/display-timing.txt110
-rw-r--r--Documentation/devicetree/bindings/video/dvi-connector.txt35
-rw-r--r--Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt46
-rw-r--r--Documentation/devicetree/bindings/video/exynos7-decon.txt68
-rw-r--r--Documentation/devicetree/bindings/video/exynos_dp.txt120
-rw-r--r--Documentation/devicetree/bindings/video/exynos_dsim.txt84
-rw-r--r--Documentation/devicetree/bindings/video/exynos_hdmi.txt43
-rw-r--r--Documentation/devicetree/bindings/video/exynos_hdmiddc.txt15
-rw-r--r--Documentation/devicetree/bindings/video/exynos_hdmiphy.txt15
-rw-r--r--Documentation/devicetree/bindings/video/exynos_mixer.txt26
-rw-r--r--Documentation/devicetree/bindings/video/fsl,imx-fb.txt55
-rw-r--r--Documentation/devicetree/bindings/video/hdmi-connector.txt29
-rw-r--r--Documentation/devicetree/bindings/video/lgphilips,lb035q02.txt33
-rw-r--r--Documentation/devicetree/bindings/video/panel-dpi.txt45
-rw-r--r--Documentation/devicetree/bindings/video/panel-dsi-cm.txt29
-rw-r--r--Documentation/devicetree/bindings/video/renesas,du.txt88
-rw-r--r--Documentation/devicetree/bindings/video/rockchip-drm.txt19
-rw-r--r--Documentation/devicetree/bindings/video/rockchip-vop.txt58
-rw-r--r--Documentation/devicetree/bindings/video/samsung-fimd.txt110
-rw-r--r--Documentation/devicetree/bindings/video/sharp,ls037v7dw01.txt43
-rw-r--r--Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt33
-rw-r--r--Documentation/devicetree/bindings/video/simple-framebuffer.txt86
-rw-r--r--Documentation/devicetree/bindings/video/sony,acx565akm.txt30
-rw-r--r--Documentation/devicetree/bindings/video/ssd1307fb.txt28
-rw-r--r--Documentation/devicetree/bindings/video/thine,thc63lvdm83d50
-rw-r--r--Documentation/devicetree/bindings/video/ti,opa362.txt38
-rw-r--r--Documentation/devicetree/bindings/video/ti,tfp410.txt41
-rw-r--r--Documentation/devicetree/bindings/video/toppoly,td028ttec1.txt30
-rw-r--r--Documentation/devicetree/bindings/video/tpo,td043mtea1.txt33
-rw-r--r--Documentation/devicetree/bindings/video/vga-connector.txt36
-rw-r--r--Documentation/devicetree/bindings/virtio/mmio.txt17
-rw-r--r--Documentation/devicetree/bindings/virtio/mmio.yaml67
-rw-r--r--Documentation/devicetree/bindings/virtio/pci-iommu.yaml99
-rw-r--r--Documentation/devicetree/bindings/virtio/virtio-device.yaml41
-rw-r--r--Documentation/devicetree/bindings/w1/amd,axi-1wire-host.yaml44
-rw-r--r--Documentation/devicetree/bindings/w1/fsl-imx-owire.txt19
-rw-r--r--Documentation/devicetree/bindings/w1/fsl-imx-owire.yaml48
-rw-r--r--Documentation/devicetree/bindings/w1/maxim,ds2482.yaml46
-rw-r--r--Documentation/devicetree/bindings/w1/omap-hdq.txt7
-rw-r--r--Documentation/devicetree/bindings/w1/w1-gpio.txt22
-rw-r--r--Documentation/devicetree/bindings/w1/w1-gpio.yaml43
-rw-r--r--Documentation/devicetree/bindings/w1/w1-uart.yaml59
-rw-r--r--Documentation/devicetree/bindings/w1/w1.txt25
-rw-r--r--Documentation/devicetree/bindings/watchdog/airoha,en7581-wdt.yaml51
-rw-r--r--Documentation/devicetree/bindings/watchdog/allwinner,sun4i-a10-wdt.yaml98
-rw-r--r--Documentation/devicetree/bindings/watchdog/alphascale,asm9260-wdt.yaml70
-rw-r--r--Documentation/devicetree/bindings/watchdog/amlogic,meson-gxbb-wdt.yaml50
-rw-r--r--Documentation/devicetree/bindings/watchdog/amlogic,meson6-wdt.yaml50
-rw-r--r--Documentation/devicetree/bindings/watchdog/apple,wdt.yaml63
-rw-r--r--Documentation/devicetree/bindings/watchdog/arm,sbsa-gwdt.yaml50
-rw-r--r--Documentation/devicetree/bindings/watchdog/arm,sp805.yaml75
-rw-r--r--Documentation/devicetree/bindings/watchdog/arm,twd-wdt.yaml50
-rw-r--r--Documentation/devicetree/bindings/watchdog/arm-smc-wdt.yaml39
-rw-r--r--Documentation/devicetree/bindings/watchdog/aspeed,ast2400-wdt.yaml146
-rw-r--r--Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml33
-rw-r--r--Documentation/devicetree/bindings/watchdog/atmel,at91sam9-wdt.yaml127
-rw-r--r--Documentation/devicetree/bindings/watchdog/atmel,sama5d4-wdt.yaml81
-rw-r--r--Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt9
-rw-r--r--Documentation/devicetree/bindings/watchdog/atmel-wdt.txt50
-rw-r--r--Documentation/devicetree/bindings/watchdog/brcm,bcm2835-pm-wdog.txt18
-rw-r--r--Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.yaml43
-rw-r--r--Documentation/devicetree/bindings/watchdog/brcm,kona-wdt.txt15
-rw-r--r--Documentation/devicetree/bindings/watchdog/brcm,kona-wdt.yaml41
-rw-r--r--Documentation/devicetree/bindings/watchdog/cadence-wdt.txt24
-rw-r--r--Documentation/devicetree/bindings/watchdog/cdns,wdt-r1p2.yaml62
-rw-r--r--Documentation/devicetree/bindings/watchdog/cirrus,ep9301-wdt.yaml42
-rw-r--r--Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml45
-rw-r--r--Documentation/devicetree/bindings/watchdog/davinci-wdt.txt24
-rw-r--r--Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml54
-rw-r--r--Documentation/devicetree/bindings/watchdog/dw_wdt.txt21
-rw-r--r--Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.yaml67
-rw-r--r--Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml37
-rw-r--r--Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt20
-rw-r--r--Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.yaml128
-rw-r--r--Documentation/devicetree/bindings/watchdog/fsl-imx7ulp-wdt.yaml67
-rw-r--r--Documentation/devicetree/bindings/watchdog/gpio-wdt.txt28
-rw-r--r--Documentation/devicetree/bindings/watchdog/img,pdc-wdt.yaml55
-rw-r--r--Documentation/devicetree/bindings/watchdog/imgpdc-wdt.txt19
-rw-r--r--Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt12
-rw-r--r--Documentation/devicetree/bindings/watchdog/intel,keembay-wdt.yaml60
-rw-r--r--Documentation/devicetree/bindings/watchdog/kontron,sl28cpld-wdt.yaml40
-rw-r--r--Documentation/devicetree/bindings/watchdog/lantiq,wdt.yaml57
-rw-r--r--Documentation/devicetree/bindings/watchdog/linux,wdt-gpio.yaml68
-rw-r--r--Documentation/devicetree/bindings/watchdog/loongson,ls1x-wdt.yaml43
-rw-r--r--Documentation/devicetree/bindings/watchdog/marvel.txt46
-rw-r--r--Documentation/devicetree/bindings/watchdog/marvell,armada-3700-wdt.yaml41
-rw-r--r--Documentation/devicetree/bindings/watchdog/marvell,cn10624-wdt.yaml83
-rw-r--r--Documentation/devicetree/bindings/watchdog/marvell,orion-wdt.yaml100
-rw-r--r--Documentation/devicetree/bindings/watchdog/maxim,max63xx.yaml45
-rw-r--r--Documentation/devicetree/bindings/watchdog/mediatek,mt7621-wdt.yaml40
-rw-r--r--Documentation/devicetree/bindings/watchdog/mediatek,mtk-wdt.yaml92
-rw-r--r--Documentation/devicetree/bindings/watchdog/meson6-wdt.txt13
-rw-r--r--Documentation/devicetree/bindings/watchdog/microchip,pic32-dmt.txt19
-rw-r--r--Documentation/devicetree/bindings/watchdog/microchip,pic32-wdt.txt18
-rw-r--r--Documentation/devicetree/bindings/watchdog/moxa,moxart-watchdog.txt15
-rw-r--r--Documentation/devicetree/bindings/watchdog/mpc8xxx-wdt.txt25
-rw-r--r--Documentation/devicetree/bindings/watchdog/mstar,msc313e-wdt.yaml40
-rw-r--r--Documentation/devicetree/bindings/watchdog/mtk-wdt.txt13
-rw-r--r--Documentation/devicetree/bindings/watchdog/nuvoton,npcm750-wdt.yaml60
-rw-r--r--Documentation/devicetree/bindings/watchdog/nxp,lpc1850-wwdt.yaml52
-rw-r--r--Documentation/devicetree/bindings/watchdog/nxp,pnx4008-wdt.yaml37
-rw-r--r--Documentation/devicetree/bindings/watchdog/nxp,s32g2-swt.yaml54
-rw-r--r--Documentation/devicetree/bindings/watchdog/of-xilinx-wdt.txt23
-rw-r--r--Documentation/devicetree/bindings/watchdog/omap-wdt.txt14
-rw-r--r--Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt17
-rw-r--r--Documentation/devicetree/bindings/watchdog/qca,ar7130-wdt.yaml33
-rw-r--r--Documentation/devicetree/bindings/watchdog/qca-ar7130-wdt.txt13
-rw-r--r--Documentation/devicetree/bindings/watchdog/qcom,pm8916-wdt.yaml56
-rw-r--r--Documentation/devicetree/bindings/watchdog/qcom-wdt.txt24
-rw-r--r--Documentation/devicetree/bindings/watchdog/qcom-wdt.yaml150
-rw-r--r--Documentation/devicetree/bindings/watchdog/ralink,rt2880-wdt.yaml46
-rw-r--r--Documentation/devicetree/bindings/watchdog/realtek,otto-wdt.yaml90
-rw-r--r--Documentation/devicetree/bindings/watchdog/realtek,rtd1295-watchdog.yaml38
-rw-r--r--Documentation/devicetree/bindings/watchdog/renesas,r9a09g057-wdt.yaml99
-rw-r--r--Documentation/devicetree/bindings/watchdog/renesas,rcar-gen3-wwdt.yaml114
-rw-r--r--Documentation/devicetree/bindings/watchdog/renesas,rza-wdt.yaml51
-rw-r--r--Documentation/devicetree/bindings/watchdog/renesas,rzg2l-wdt.yaml111
-rw-r--r--Documentation/devicetree/bindings/watchdog/renesas,rzn1-wdt.yaml50
-rw-r--r--Documentation/devicetree/bindings/watchdog/renesas,wdt.yaml106
-rw-r--r--Documentation/devicetree/bindings/watchdog/rt2880-wdt.txt19
-rw-r--r--Documentation/devicetree/bindings/watchdog/samsung-wdt.txt34
-rw-r--r--Documentation/devicetree/bindings/watchdog/samsung-wdt.yaml132
-rw-r--r--Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt14
-rw-r--r--Documentation/devicetree/bindings/watchdog/snps,dw-wdt.yaml111
-rw-r--r--Documentation/devicetree/bindings/watchdog/socionext,uniphier-wdt.yaml30
-rw-r--r--Documentation/devicetree/bindings/watchdog/sprd,sp9860-wdt.yaml64
-rw-r--r--Documentation/devicetree/bindings/watchdog/st,stm32-iwdg.yaml64
-rw-r--r--Documentation/devicetree/bindings/watchdog/st_lpc_wdt.txt41
-rw-r--r--Documentation/devicetree/bindings/watchdog/starfive,jh7100-wdt.yaml93
-rw-r--r--Documentation/devicetree/bindings/watchdog/stericsson-coh901327.txt19
-rw-r--r--Documentation/devicetree/bindings/watchdog/sunplus,sp7021-wdt.yaml47
-rw-r--r--Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt14
-rw-r--r--Documentation/devicetree/bindings/watchdog/technologic,ts7200-wdt.yaml45
-rw-r--r--Documentation/devicetree/bindings/watchdog/ti,davinci-wdt.yaml55
-rw-r--r--Documentation/devicetree/bindings/watchdog/ti,omap2-wdt.yaml51
-rw-r--r--Documentation/devicetree/bindings/watchdog/ti,rti-wdt.yaml87
-rw-r--r--Documentation/devicetree/bindings/watchdog/toshiba,visconti-wdt.yaml48
-rw-r--r--Documentation/devicetree/bindings/watchdog/ts4800-wdt.txt25
-rw-r--r--Documentation/devicetree/bindings/watchdog/twl4030-wdt.txt10
-rw-r--r--Documentation/devicetree/bindings/watchdog/watchdog.yaml33
-rw-r--r--Documentation/devicetree/bindings/watchdog/xlnx,versal-wwdt.yaml50
-rw-r--r--Documentation/devicetree/bindings/watchdog/xlnx,xps-timebase-wdt.yaml68
-rw-r--r--Documentation/devicetree/bindings/watchdog/zii,rave-sp-wdt.yaml47
-rw-r--r--Documentation/devicetree/bindings/watchdog/zii,rave-wdt.yaml49
-rw-r--r--Documentation/devicetree/bindings/writing-bindings.rst132
-rw-r--r--Documentation/devicetree/bindings/writing-schema.rst257
-rw-r--r--Documentation/devicetree/bindings/x86/ce4100.txt37
-rw-r--r--Documentation/devicetree/bindings/x86/interrupt.txt26
-rw-r--r--Documentation/devicetree/bindings/xilinx.txt173
-rw-r--r--Documentation/devicetree/bindings/xillybus/xillybus.txt2
-rw-r--r--Documentation/devicetree/booting-without-of.txt1529
-rw-r--r--Documentation/devicetree/changesets.rst37
-rw-r--r--Documentation/devicetree/changesets.txt40
-rw-r--r--Documentation/devicetree/dynamic-resolution-notes.rst27
-rw-r--r--Documentation/devicetree/dynamic-resolution-notes.txt25
-rw-r--r--Documentation/devicetree/index.rst30
-rw-r--r--Documentation/devicetree/kernel-api.rst57
-rw-r--r--Documentation/devicetree/of_unittest.rst224
-rw-r--r--Documentation/devicetree/of_unittest.txt197
-rw-r--r--Documentation/devicetree/overlay-notes.rst150
-rw-r--r--Documentation/devicetree/overlay-notes.txt133
-rw-r--r--Documentation/devicetree/todo.txt10
-rw-r--r--Documentation/devicetree/usage-model.rst420
-rw-r--r--Documentation/devicetree/usage-model.txt415
-rw-r--r--Documentation/digsig.txt96
-rw-r--r--Documentation/dma-buf-sharing.txt465
-rw-r--r--Documentation/dmaengine/00-INDEX8
-rw-r--r--Documentation/dmaengine/client.txt199
-rw-r--r--Documentation/dmaengine/dmatest.txt92
-rw-r--r--Documentation/dmaengine/provider.txt379
-rw-r--r--Documentation/doc-guide/checktransupdate.rst54
-rw-r--r--Documentation/doc-guide/contributing.rst300
-rw-r--r--Documentation/doc-guide/hello.dot3
-rw-r--r--Documentation/doc-guide/index.rst22
-rw-r--r--Documentation/doc-guide/kernel-doc.rst605
-rw-r--r--Documentation/doc-guide/maintainer-profile.rst52
-rw-r--r--Documentation/doc-guide/parse-headers.rst187
-rw-r--r--Documentation/doc-guide/sphinx.rst562
-rw-r--r--Documentation/doc-guide/svg_image.svg10
-rw-r--r--Documentation/docutils.conf7
-rw-r--r--Documentation/dontdiff260
-rw-r--r--Documentation/driver-api/80211/cfg80211.rst178
-rw-r--r--Documentation/driver-api/80211/index.rst17
-rw-r--r--Documentation/driver-api/80211/introduction.rst17
-rw-r--r--Documentation/driver-api/80211/mac80211-advanced.rst239
-rw-r--r--Documentation/driver-api/80211/mac80211.rst155
-rw-r--r--Documentation/driver-api/acpi/index.rst9
-rw-r--r--Documentation/driver-api/acpi/linuxized-acpica.rst279
-rw-r--r--Documentation/driver-api/acpi/scan_handlers.rst83
-rw-r--r--Documentation/driver-api/aperture.rst13
-rw-r--r--Documentation/driver-api/auxiliary_bus.rst49
-rw-r--r--Documentation/driver-api/backlight/lp855x-driver.rst81
-rw-r--r--Documentation/driver-api/basics.rst133
-rw-r--r--Documentation/driver-api/clk.rst312
-rw-r--r--Documentation/driver-api/coco/index.rst12
-rw-r--r--Documentation/driver-api/coco/measurement-registers.rst12
-rw-r--r--Documentation/driver-api/component.rst19
-rw-r--r--Documentation/driver-api/connector.rst157
-rw-r--r--Documentation/driver-api/console.rst152
-rw-r--r--Documentation/driver-api/crypto/iaa/iaa-crypto.rst849
-rw-r--r--Documentation/driver-api/crypto/iaa/index.rst20
-rw-r--r--Documentation/driver-api/crypto/index.rst20
-rw-r--r--Documentation/driver-api/cxl/allocation/dax.rst60
-rw-r--r--Documentation/driver-api/cxl/allocation/hugepages.rst32
-rw-r--r--Documentation/driver-api/cxl/allocation/page-allocator.rst54
-rw-r--r--Documentation/driver-api/cxl/allocation/reclaim.rst51
-rw-r--r--Documentation/driver-api/cxl/conventions.rst182
-rw-r--r--Documentation/driver-api/cxl/devices/device-types.rst165
-rw-r--r--Documentation/driver-api/cxl/index.rst54
-rw-r--r--Documentation/driver-api/cxl/linux/access-coordinates.rst178
-rw-r--r--Documentation/driver-api/cxl/linux/cxl-driver.rst630
-rw-r--r--Documentation/driver-api/cxl/linux/dax-driver.rst43
-rw-r--r--Documentation/driver-api/cxl/linux/early-boot.rst137
-rw-r--r--Documentation/driver-api/cxl/linux/example-configurations/hb-interleave.rst314
-rw-r--r--Documentation/driver-api/cxl/linux/example-configurations/intra-hb-interleave.rst291
-rw-r--r--Documentation/driver-api/cxl/linux/example-configurations/multi-interleave.rst401
-rw-r--r--Documentation/driver-api/cxl/linux/example-configurations/single-device.rst246
-rw-r--r--Documentation/driver-api/cxl/linux/memory-hotplug.rst78
-rw-r--r--Documentation/driver-api/cxl/linux/overview.rst103
-rw-r--r--Documentation/driver-api/cxl/maturity-map.rst202
-rw-r--r--Documentation/driver-api/cxl/platform/acpi.rst76
-rw-r--r--Documentation/driver-api/cxl/platform/acpi/cedt.rst62
-rw-r--r--Documentation/driver-api/cxl/platform/acpi/dsdt.rst28
-rw-r--r--Documentation/driver-api/cxl/platform/acpi/hmat.rst32
-rw-r--r--Documentation/driver-api/cxl/platform/acpi/slit.rst21
-rw-r--r--Documentation/driver-api/cxl/platform/acpi/srat.rst71
-rw-r--r--Documentation/driver-api/cxl/platform/bios-and-efi.rst262
-rw-r--r--Documentation/driver-api/cxl/platform/cdat.rst118
-rw-r--r--Documentation/driver-api/cxl/platform/example-configs.rst13
-rw-r--r--Documentation/driver-api/cxl/platform/example-configurations/flexible.rst296
-rw-r--r--Documentation/driver-api/cxl/platform/example-configurations/hb-interleave.rst107
-rw-r--r--Documentation/driver-api/cxl/platform/example-configurations/multi-dev-per-hb.rst90
-rw-r--r--Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst136
-rw-r--r--Documentation/driver-api/cxl/theory-of-operation.rst415
-rw-r--r--Documentation/driver-api/devfreq.rst30
-rw-r--r--Documentation/driver-api/device-io.rst519
-rw-r--r--Documentation/driver-api/device_link.rst320
-rw-r--r--Documentation/driver-api/dma-buf.rst382
-rw-r--r--Documentation/driver-api/dmaengine/client.rst388
-rw-r--r--Documentation/driver-api/dmaengine/dmatest.rst232
-rw-r--r--Documentation/driver-api/dmaengine/index.rst55
-rw-r--r--Documentation/driver-api/dmaengine/provider.rst659
-rw-r--r--Documentation/driver-api/dmaengine/pxa_dma.rst190
-rw-r--r--Documentation/driver-api/dpll.rst635
-rw-r--r--Documentation/driver-api/driver-model/binding.rst98
-rw-r--r--Documentation/driver-api/driver-model/bus.rst146
-rw-r--r--Documentation/driver-api/driver-model/design-patterns.rst116
-rw-r--r--Documentation/driver-api/driver-model/device.rst120
-rw-r--r--Documentation/driver-api/driver-model/devres.rst467
-rw-r--r--Documentation/driver-api/driver-model/driver.rst286
-rw-r--r--Documentation/driver-api/driver-model/index.rst23
-rw-r--r--Documentation/driver-api/driver-model/overview.rst124
-rw-r--r--Documentation/driver-api/driver-model/platform.rst247
-rw-r--r--Documentation/driver-api/driver-model/porting.rst448
-rw-r--r--Documentation/driver-api/early-userspace/buffer-format.rst132
-rw-r--r--Documentation/driver-api/early-userspace/early_userspace_support.rst154
-rw-r--r--Documentation/driver-api/early-userspace/index.rst18
-rw-r--r--Documentation/driver-api/edac.rst298
-rw-r--r--Documentation/driver-api/eisa.rst230
-rw-r--r--Documentation/driver-api/extcon.rst255
-rw-r--r--Documentation/driver-api/firewire.rst50
-rw-r--r--Documentation/driver-api/firmware/built-in-fw.rst33
-rw-r--r--Documentation/driver-api/firmware/core.rst17
-rw-r--r--Documentation/driver-api/firmware/direct-fs-lookup.rst30
-rw-r--r--Documentation/driver-api/firmware/efi/index.rst16
-rw-r--r--Documentation/driver-api/firmware/fallback-mechanisms.rst308
-rw-r--r--Documentation/driver-api/firmware/firmware-usage-guidelines.rst49
-rw-r--r--Documentation/driver-api/firmware/firmware_cache.rst51
-rw-r--r--Documentation/driver-api/firmware/fw_search_path.rst31
-rw-r--r--Documentation/driver-api/firmware/fw_upload.rst127
-rw-r--r--Documentation/driver-api/firmware/index.rst19
-rw-r--r--Documentation/driver-api/firmware/introduction.rst27
-rw-r--r--Documentation/driver-api/firmware/lookup-order.rst20
-rw-r--r--Documentation/driver-api/firmware/other_interfaces.rst51
-rw-r--r--Documentation/driver-api/firmware/request_firmware.rst80
-rw-r--r--Documentation/driver-api/fpga/fpga-bridge.rst25
-rw-r--r--Documentation/driver-api/fpga/fpga-mgr.rst168
-rw-r--r--Documentation/driver-api/fpga/fpga-programming.rst107
-rw-r--r--Documentation/driver-api/fpga/fpga-region.rst112
-rw-r--r--Documentation/driver-api/fpga/index.rst15
-rw-r--r--Documentation/driver-api/fpga/intro.rst54
-rw-r--r--Documentation/driver-api/frame-buffer.rst62
-rw-r--r--Documentation/driver-api/generic-counter.rst573
-rw-r--r--Documentation/driver-api/generic_pt.rst137
-rw-r--r--Documentation/driver-api/gpio/board.rst281
-rw-r--r--Documentation/driver-api/gpio/bt8xxgpio.rst62
-rw-r--r--Documentation/driver-api/gpio/consumer.rst470
-rw-r--r--Documentation/driver-api/gpio/driver.rst777
-rw-r--r--Documentation/driver-api/gpio/drivers-on-gpio.rst119
-rw-r--r--Documentation/driver-api/gpio/index.rst51
-rw-r--r--Documentation/driver-api/gpio/intro.rst112
-rw-r--r--Documentation/driver-api/gpio/legacy-boards.rst298
-rw-r--r--Documentation/driver-api/gpio/pca953x.rst552
-rw-r--r--Documentation/driver-api/gpio/using-gpio.rst50
-rw-r--r--Documentation/driver-api/hsi.rst88
-rw-r--r--Documentation/driver-api/hte/hte.rst79
-rw-r--r--Documentation/driver-api/hte/index.rst22
-rw-r--r--Documentation/driver-api/hte/tegra-hte.rst47
-rw-r--r--Documentation/driver-api/hw-recoverable-errors.rst60
-rw-r--r--Documentation/driver-api/i2c.rst48
-rw-r--r--Documentation/driver-api/i3c/device-driver-api.rst9
-rw-r--r--Documentation/driver-api/i3c/index.rst11
-rw-r--r--Documentation/driver-api/i3c/master-driver-api.rst9
-rw-r--r--Documentation/driver-api/i3c/protocol.rst203
-rw-r--r--Documentation/driver-api/iio/buffers.rst126
-rw-r--r--Documentation/driver-api/iio/core.rst182
-rw-r--r--Documentation/driver-api/iio/hw-consumer.rst50
-rw-r--r--Documentation/driver-api/iio/index.rst18
-rw-r--r--Documentation/driver-api/iio/intro.rst33
-rw-r--r--Documentation/driver-api/iio/triggered-buffers.rst69
-rw-r--r--Documentation/driver-api/iio/triggers.rst78
-rw-r--r--Documentation/driver-api/index.rst158
-rw-r--r--Documentation/driver-api/infiniband.rst124
-rw-r--r--Documentation/driver-api/infrastructure.rst103
-rw-r--r--Documentation/driver-api/input.rst49
-rw-r--r--Documentation/driver-api/interconnect.rst140
-rw-r--r--Documentation/driver-api/io-mapping.rst91
-rw-r--r--Documentation/driver-api/io_ordering.rst51
-rw-r--r--Documentation/driver-api/ioctl.rst253
-rw-r--r--Documentation/driver-api/ipmb.rst109
-rw-r--r--Documentation/driver-api/ipmi.rst807
-rw-r--r--Documentation/driver-api/isa.rst122
-rw-r--r--Documentation/driver-api/libata.rst1000
-rw-r--r--Documentation/driver-api/mailbox.rst129
-rw-r--r--Documentation/driver-api/md/index.rst12
-rw-r--r--Documentation/driver-api/md/md-cluster.rst385
-rw-r--r--Documentation/driver-api/md/raid5-cache.rst111
-rw-r--r--Documentation/driver-api/md/raid5-ppl.rst47
-rw-r--r--Documentation/driver-api/media/camera-sensor.rst158
-rw-r--r--Documentation/driver-api/media/cec-core.rst502
-rw-r--r--Documentation/driver-api/media/drivers/bttv-devel.rst116
-rw-r--r--Documentation/driver-api/media/drivers/ccs/ccs-regs.asc1041
-rw-r--r--Documentation/driver-api/media/drivers/ccs/ccs.rst82
-rwxr-xr-xDocumentation/driver-api/media/drivers/ccs/mk-ccs-regs480
-rw-r--r--Documentation/driver-api/media/drivers/contributors.rst131
-rw-r--r--Documentation/driver-api/media/drivers/cx2341x-devel.rst3685
-rw-r--r--Documentation/driver-api/media/drivers/cx88-devel.rst113
-rw-r--r--Documentation/driver-api/media/drivers/dvb-usb.rst357
-rw-r--r--Documentation/driver-api/media/drivers/fimc-devel.rst33
-rw-r--r--Documentation/driver-api/media/drivers/frontends.rst32
-rw-r--r--Documentation/driver-api/media/drivers/index.rst41
-rw-r--r--Documentation/driver-api/media/drivers/ipu6.rst190
-rw-r--r--Documentation/driver-api/media/drivers/pvrusb2.rst202
-rw-r--r--Documentation/driver-api/media/drivers/pxa_camera.rst194
-rw-r--r--Documentation/driver-api/media/drivers/radiotrack.rst168
-rw-r--r--Documentation/driver-api/media/drivers/rkisp1.rst43
-rw-r--r--Documentation/driver-api/media/drivers/saa7134-devel.rst67
-rw-r--r--Documentation/driver-api/media/drivers/sh_mobile_ceu_camera.rst142
-rw-r--r--Documentation/driver-api/media/drivers/tuners.rst133
-rw-r--r--Documentation/driver-api/media/drivers/vidtv.rst513
-rw-r--r--Documentation/driver-api/media/drivers/vimc-devel.rst15
-rw-r--r--Documentation/driver-api/media/drivers/zoran.rst575
-rw-r--r--Documentation/driver-api/media/dtv-ca.rst6
-rw-r--r--Documentation/driver-api/media/dtv-common.rst53
-rw-r--r--Documentation/driver-api/media/dtv-core.rst39
-rw-r--r--Documentation/driver-api/media/dtv-demux.rst84
-rw-r--r--Documentation/driver-api/media/dtv-frontend.rst445
-rw-r--r--Documentation/driver-api/media/dtv-net.rst6
-rw-r--r--Documentation/driver-api/media/index.rst54
-rw-r--r--Documentation/driver-api/media/maintainer-entry-profile.rst206
-rw-r--r--Documentation/driver-api/media/mc-core.rst341
-rw-r--r--Documentation/driver-api/media/rc-core.rst88
-rw-r--r--Documentation/driver-api/media/tx-rx.rst144
-rw-r--r--Documentation/driver-api/media/v4l2-async.rst5
-rw-r--r--Documentation/driver-api/media/v4l2-cci.rst5
-rw-r--r--Documentation/driver-api/media/v4l2-common.rst8
-rw-r--r--Documentation/driver-api/media/v4l2-controls.rst820
-rw-r--r--Documentation/driver-api/media/v4l2-core.rst30
-rw-r--r--Documentation/driver-api/media/v4l2-dev.rst367
-rw-r--r--Documentation/driver-api/media/v4l2-device.rst146
-rw-r--r--Documentation/driver-api/media/v4l2-dv-timings.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-event.rst181
-rw-r--r--Documentation/driver-api/media/v4l2-fh.rst136
-rw-r--r--Documentation/driver-api/media/v4l2-flash-led-class.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-fwnode.rst5
-rw-r--r--Documentation/driver-api/media/v4l2-intro.rst76
-rw-r--r--Documentation/driver-api/media/v4l2-isp.rst49
-rw-r--r--Documentation/driver-api/media/v4l2-jpeg.rst10
-rw-r--r--Documentation/driver-api/media/v4l2-mc.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-mediabus.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-mem2mem.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-rect.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-subdev.rst644
-rw-r--r--Documentation/driver-api/media/v4l2-tuner.rst8
-rw-r--r--Documentation/driver-api/media/v4l2-tveeprom.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-videobuf2.rst12
-rw-r--r--Documentation/driver-api/mei/hdcp.rst32
-rw-r--r--Documentation/driver-api/mei/iamt.rst101
-rw-r--r--Documentation/driver-api/mei/index.rst18
-rw-r--r--Documentation/driver-api/mei/mei-client-bus.rst168
-rw-r--r--Documentation/driver-api/mei/mei.rst213
-rw-r--r--Documentation/driver-api/mei/nfc.rst28
-rw-r--r--Documentation/driver-api/memory-devices/index.rst18
-rw-r--r--Documentation/driver-api/memory-devices/ti-emif.rst64
-rw-r--r--Documentation/driver-api/memory-devices/ti-gpmc.rst179
-rw-r--r--Documentation/driver-api/men-chameleon-bus.rst187
-rw-r--r--Documentation/driver-api/message-based.rst12
-rw-r--r--Documentation/driver-api/misc_devices.rst5
-rw-r--r--Documentation/driver-api/miscellaneous.rst48
-rw-r--r--Documentation/driver-api/mmc/index.rst14
-rw-r--r--Documentation/driver-api/mmc/mmc-async-req.rst98
-rw-r--r--Documentation/driver-api/mmc/mmc-dev-attrs.rst91
-rw-r--r--Documentation/driver-api/mmc/mmc-dev-parts.rst41
-rw-r--r--Documentation/driver-api/mmc/mmc-test.rst299
-rw-r--r--Documentation/driver-api/mmc/mmc-tools.rst37
-rw-r--r--Documentation/driver-api/mtd/index.rst12
-rw-r--r--Documentation/driver-api/mtd/nand_ecc.rst763
-rw-r--r--Documentation/driver-api/mtd/spi-intel.rst90
-rw-r--r--Documentation/driver-api/mtd/spi-nor.rst205
-rw-r--r--Documentation/driver-api/mtdnand.rst1006
-rw-r--r--Documentation/driver-api/nfc/index.rst11
-rw-r--r--Documentation/driver-api/nfc/nfc-hci.rst311
-rw-r--r--Documentation/driver-api/nfc/nfc-pn544.rst34
-rw-r--r--Documentation/driver-api/ntb.rst263
-rw-r--r--Documentation/driver-api/nvdimm/btt.rst285
-rw-r--r--Documentation/driver-api/nvdimm/firmware-activate.rst86
-rw-r--r--Documentation/driver-api/nvdimm/index.rst13
-rw-r--r--Documentation/driver-api/nvdimm/nvdimm.rst657
-rw-r--r--Documentation/driver-api/nvdimm/security.rst143
-rw-r--r--Documentation/driver-api/nvmem.rst202
-rw-r--r--Documentation/driver-api/parport-lowlevel.rst1837
-rw-r--r--Documentation/driver-api/pci/index.rst20
-rw-r--r--Documentation/driver-api/pci/p2pdma.rst182
-rw-r--r--Documentation/driver-api/pci/pci.rst59
-rw-r--r--Documentation/driver-api/pci/tsm.rst21
-rw-r--r--Documentation/driver-api/phy/index.rst18
-rw-r--r--Documentation/driver-api/phy/phy.rst223
-rw-r--r--Documentation/driver-api/phy/samsung-usb2.rst137
-rw-r--r--Documentation/driver-api/pin-control.rst1510
-rw-r--r--Documentation/driver-api/pldmfw/driver-ops.rst56
-rw-r--r--Documentation/driver-api/pldmfw/file-format.rst203
-rw-r--r--Documentation/driver-api/pldmfw/index.rst71
-rw-r--r--Documentation/driver-api/pm/cpuidle.rst279
-rw-r--r--Documentation/driver-api/pm/devices.rst880
-rw-r--r--Documentation/driver-api/pm/index.rst19
-rw-r--r--Documentation/driver-api/pm/notifiers.rst74
-rw-r--r--Documentation/driver-api/pm/types.rst7
-rw-r--r--Documentation/driver-api/pps.rst311
-rw-r--r--Documentation/driver-api/ptp.rst137
-rw-r--r--Documentation/driver-api/pwm.rst191
-rw-r--r--Documentation/driver-api/pwrseq.rst95
-rw-r--r--Documentation/driver-api/rapidio/index.rst15
-rw-r--r--Documentation/driver-api/rapidio/mport_cdev.rst110
-rw-r--r--Documentation/driver-api/rapidio/rapidio.rst362
-rw-r--r--Documentation/driver-api/rapidio/rio_cm.rst135
-rw-r--r--Documentation/driver-api/rapidio/sysfs.rst7
-rw-r--r--Documentation/driver-api/rapidio/tsi721.rst112
-rw-r--r--Documentation/driver-api/regulator.rst170
-rw-r--r--Documentation/driver-api/reset.rst220
-rw-r--r--Documentation/driver-api/rfkill.rst132
-rw-r--r--Documentation/driver-api/s390-drivers.rst135
-rw-r--r--Documentation/driver-api/scsi.rst336
-rw-r--r--Documentation/driver-api/serial/driver.rst105
-rw-r--r--Documentation/driver-api/serial/index.rst27
-rw-r--r--Documentation/driver-api/serial/serial-iso7816.rst90
-rw-r--r--Documentation/driver-api/serial/serial-rs485.rst135
-rw-r--r--Documentation/driver-api/slimbus.rst132
-rw-r--r--Documentation/driver-api/sm501.rst74
-rw-r--r--Documentation/driver-api/soundwire/bra.rst336
-rw-r--r--Documentation/driver-api/soundwire/bra_cadence.rst66
-rw-r--r--Documentation/driver-api/soundwire/error_handling.rst65
-rw-r--r--Documentation/driver-api/soundwire/index.rst20
-rw-r--r--Documentation/driver-api/soundwire/locking.rst108
-rw-r--r--Documentation/driver-api/soundwire/stream.rst527
-rw-r--r--Documentation/driver-api/soundwire/summary.rst200
-rw-r--r--Documentation/driver-api/spi.rst53
-rw-r--r--Documentation/driver-api/surface_aggregator/client-api.rst38
-rw-r--r--Documentation/driver-api/surface_aggregator/client.rst397
-rw-r--r--Documentation/driver-api/surface_aggregator/clients/cdev.rst204
-rw-r--r--Documentation/driver-api/surface_aggregator/clients/dtx.rst718
-rw-r--r--Documentation/driver-api/surface_aggregator/clients/index.rst23
-rw-r--r--Documentation/driver-api/surface_aggregator/clients/san.rst44
-rw-r--r--Documentation/driver-api/surface_aggregator/index.rst21
-rw-r--r--Documentation/driver-api/surface_aggregator/internal-api.rst67
-rw-r--r--Documentation/driver-api/surface_aggregator/internal.rst578
-rw-r--r--Documentation/driver-api/surface_aggregator/overview.rst79
-rw-r--r--Documentation/driver-api/surface_aggregator/ssh.rst346
-rw-r--r--Documentation/driver-api/switchtec.rst102
-rw-r--r--Documentation/driver-api/sync_file.rst86
-rw-r--r--Documentation/driver-api/target.rst52
-rw-r--r--Documentation/driver-api/tee.rst66
-rw-r--r--Documentation/driver-api/thermal/cpu-cooling-api.rst107
-rw-r--r--Documentation/driver-api/thermal/cpu-idle-cooling.rst199
-rw-r--r--Documentation/driver-api/thermal/exynos_thermal.rst90
-rw-r--r--Documentation/driver-api/thermal/exynos_thermal_emulation.rst61
-rw-r--r--Documentation/driver-api/thermal/index.rst19
-rw-r--r--Documentation/driver-api/thermal/intel_dptf.rst434
-rw-r--r--Documentation/driver-api/thermal/nouveau_thermal.rst96
-rw-r--r--Documentation/driver-api/thermal/power_allocator.rst281
-rw-r--r--Documentation/driver-api/thermal/sysfs-api.rst433
-rw-r--r--Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst55
-rw-r--r--Documentation/driver-api/tty/console.rst45
-rw-r--r--Documentation/driver-api/tty/index.rst75
-rw-r--r--Documentation/driver-api/tty/moxa-smartio.rst197
-rw-r--r--Documentation/driver-api/tty/n_gsm.rst192
-rw-r--r--Documentation/driver-api/tty/n_tty.rst22
-rw-r--r--Documentation/driver-api/tty/tty_buffer.rst49
-rw-r--r--Documentation/driver-api/tty/tty_driver.rst130
-rw-r--r--Documentation/driver-api/tty/tty_internals.rst31
-rw-r--r--Documentation/driver-api/tty/tty_ioctl.rst10
-rw-r--r--Documentation/driver-api/tty/tty_ldisc.rst85
-rw-r--r--Documentation/driver-api/tty/tty_port.rst71
-rw-r--r--Documentation/driver-api/tty/tty_struct.rst81
-rw-r--r--Documentation/driver-api/uio-howto.rst730
-rw-r--r--Documentation/driver-api/usb/URB.rst290
-rw-r--r--Documentation/driver-api/usb/anchors.rst72
-rw-r--r--Documentation/driver-api/usb/bulk-streams.rst83
-rw-r--r--Documentation/driver-api/usb/callbacks.rst159
-rw-r--r--Documentation/driver-api/usb/dma.rst110
-rw-r--r--Documentation/driver-api/usb/dwc3.rst711
-rw-r--r--Documentation/driver-api/usb/error-codes.rst210
-rw-r--r--Documentation/driver-api/usb/gadget.rst510
-rw-r--r--Documentation/driver-api/usb/hotplug.rst154
-rw-r--r--Documentation/driver-api/usb/index.rst31
-rw-r--r--Documentation/driver-api/usb/persist.rst171
-rw-r--r--Documentation/driver-api/usb/power-management.rst798
-rw-r--r--Documentation/driver-api/usb/typec.rst234
-rw-r--r--Documentation/driver-api/usb/typec_bus.rst122
-rw-r--r--Documentation/driver-api/usb/usb.rst1057
-rw-r--r--Documentation/driver-api/usb/usb3-debug-port.rst152
-rw-r--r--Documentation/driver-api/usb/writing_musb_glue_layer.rst720
-rw-r--r--Documentation/driver-api/usb/writing_usb_driver.rst328
-rw-r--r--Documentation/driver-api/vfio-mediated-device.rst273
-rw-r--r--Documentation/driver-api/vfio-pci-device-specific-driver-acceptance.rst35
-rw-r--r--Documentation/driver-api/vfio.rst707
-rw-r--r--Documentation/driver-api/virtio/index.rst11
-rw-r--r--Documentation/driver-api/virtio/virtio.rst145
-rw-r--r--Documentation/driver-api/virtio/writing_virtio_drivers.rst196
-rw-r--r--Documentation/driver-api/vme.rst297
-rw-r--r--Documentation/driver-api/w1.rst67
-rw-r--r--Documentation/driver-api/wbrf.rst78
-rw-r--r--Documentation/driver-api/wmi.rst20
-rw-r--r--Documentation/driver-api/xilinx/eemi.rst40
-rw-r--r--Documentation/driver-api/xilinx/index.rst16
-rw-r--r--Documentation/driver-api/xillybus.rst379
-rw-r--r--Documentation/driver-api/zorro.rst104
-rw-r--r--Documentation/driver-model/binding.txt98
-rw-r--r--Documentation/driver-model/bus.txt143
-rw-r--r--Documentation/driver-model/class.txt147
-rw-r--r--Documentation/driver-model/design-patterns.txt116
-rw-r--r--Documentation/driver-model/device.txt106
-rw-r--r--Documentation/driver-model/devres.txt341
-rw-r--r--Documentation/driver-model/driver.txt214
-rw-r--r--Documentation/driver-model/overview.txt123
-rw-r--r--Documentation/driver-model/platform.txt230
-rw-r--r--Documentation/driver-model/porting.txt445
-rw-r--r--Documentation/dvb/README.dvb-usb232
-rw-r--r--Documentation/dvb/avermedia.txt301
-rw-r--r--Documentation/dvb/bt8xx.txt98
-rw-r--r--Documentation/dvb/cards.txt123
-rw-r--r--Documentation/dvb/ci.txt212
-rw-r--r--Documentation/dvb/contributors.txt96
-rw-r--r--Documentation/dvb/faq.txt159
-rwxr-xr-xDocumentation/dvb/get_dvb_firmware942
-rw-r--r--Documentation/dvb/lmedm04.txt81
-rw-r--r--Documentation/dvb/opera-firmware.txt27
-rw-r--r--Documentation/dvb/readme.txt62
-rw-r--r--Documentation/dvb/technisat.txt78
-rw-r--r--Documentation/dvb/ttusb-dec.txt45
-rw-r--r--Documentation/dvb/udev.txt46
-rw-r--r--Documentation/dynamic-debug-howto.txt340
-rw-r--r--Documentation/early-userspace/README151
-rw-r--r--Documentation/early-userspace/buffer-format.txt112
-rw-r--r--Documentation/edac.txt775
-rw-r--r--Documentation/edac/features.rst103
-rw-r--r--Documentation/edac/index.rst12
-rw-r--r--Documentation/edac/memory_repair.rst152
-rw-r--r--Documentation/edac/scrub.rst342
-rw-r--r--Documentation/efi-stub.txt84
-rw-r--r--Documentation/eisa.txt203
-rw-r--r--Documentation/email-clients.txt263
-rw-r--r--Documentation/extcon/porting-android-switch-class123
-rw-r--r--Documentation/fault-injection/fault-injection.rst611
-rw-r--r--Documentation/fault-injection/fault-injection.txt269
-rw-r--r--Documentation/fault-injection/index.rst20
-rw-r--r--Documentation/fault-injection/notifier-error-inject.rst98
-rw-r--r--Documentation/fault-injection/notifier-error-inject.txt99
-rw-r--r--Documentation/fault-injection/nvme-fault-injection.rst178
-rw-r--r--Documentation/fault-injection/provoke-crashes.rst57
-rw-r--r--Documentation/fault-injection/provoke-crashes.txt38
-rw-r--r--Documentation/fb/00-INDEX75
-rw-r--r--Documentation/fb/api.rst307
-rw-r--r--Documentation/fb/api.txt306
-rw-r--r--Documentation/fb/arkfb.rst68
-rw-r--r--Documentation/fb/arkfb.txt68
-rw-r--r--Documentation/fb/aty128fb.rst73
-rw-r--r--Documentation/fb/aty128fb.txt72
-rw-r--r--Documentation/fb/cirrusfb.rst94
-rw-r--r--Documentation/fb/cirrusfb.txt97
-rw-r--r--Documentation/fb/cmap_xfbdev.rst56
-rw-r--r--Documentation/fb/cmap_xfbdev.txt53
-rw-r--r--Documentation/fb/deferred_io.rst79
-rw-r--r--Documentation/fb/deferred_io.txt75
-rw-r--r--Documentation/fb/efifb.rst71
-rw-r--r--Documentation/fb/efifb.txt31
-rw-r--r--Documentation/fb/ep93xx-fb.rst136
-rw-r--r--Documentation/fb/ep93xx-fb.txt135
-rw-r--r--Documentation/fb/fbcon.rst354
-rw-r--r--Documentation/fb/fbcon.txt324
-rw-r--r--Documentation/fb/framebuffer.rst353
-rw-r--r--Documentation/fb/framebuffer.txt343
-rw-r--r--Documentation/fb/gxfb.rst52
-rw-r--r--Documentation/fb/gxfb.txt52
-rw-r--r--Documentation/fb/index.rst59
-rw-r--r--Documentation/fb/intel810.rst287
-rw-r--r--Documentation/fb/intel810.txt278
-rw-r--r--Documentation/fb/intelfb.txt149
-rw-r--r--Documentation/fb/internals.rst86
-rw-r--r--Documentation/fb/internals.txt82
-rw-r--r--Documentation/fb/lxfb.rst52
-rw-r--r--Documentation/fb/lxfb.txt52
-rw-r--r--Documentation/fb/matroxfb.rst438
-rw-r--r--Documentation/fb/matroxfb.txt413
-rw-r--r--Documentation/fb/metronomefb.rst38
-rw-r--r--Documentation/fb/metronomefb.txt36
-rw-r--r--Documentation/fb/modedb.rst182
-rw-r--r--Documentation/fb/modedb.txt151
-rw-r--r--Documentation/fb/pvr2fb.rst66
-rw-r--r--Documentation/fb/pvr2fb.txt65
-rw-r--r--Documentation/fb/pxafb.rst173
-rw-r--r--Documentation/fb/pxafb.txt142
-rw-r--r--Documentation/fb/s3fb.rst82
-rw-r--r--Documentation/fb/s3fb.txt82
-rw-r--r--Documentation/fb/sa1100fb.rst37
-rw-r--r--Documentation/fb/sa1100fb.txt39
-rw-r--r--Documentation/fb/sh7760fb.rst130
-rw-r--r--Documentation/fb/sh7760fb.txt131
-rw-r--r--Documentation/fb/sisfb.rst160
-rw-r--r--Documentation/fb/sisfb.txt158
-rw-r--r--Documentation/fb/sm501.rst15
-rw-r--r--Documentation/fb/sm501.txt10
-rw-r--r--Documentation/fb/sm712fb.rst35
-rw-r--r--Documentation/fb/sstfb.rst204
-rw-r--r--Documentation/fb/sstfb.txt174
-rw-r--r--Documentation/fb/tgafb.rst71
-rw-r--r--Documentation/fb/tgafb.txt69
-rw-r--r--Documentation/fb/tridentfb.rst78
-rw-r--r--Documentation/fb/tridentfb.txt70
-rw-r--r--Documentation/fb/udlfb.rst169
-rw-r--r--Documentation/fb/udlfb.txt159
-rw-r--r--Documentation/fb/uvesafb.rst188
-rw-r--r--Documentation/fb/uvesafb.txt183
-rw-r--r--Documentation/fb/vesafb.rst190
-rw-r--r--Documentation/fb/vesafb.txt181
-rw-r--r--Documentation/fb/viafb.rst297
-rw-r--r--Documentation/fb/viafb.txt252
-rw-r--r--Documentation/fb/vt8623fb.rst64
-rw-r--r--Documentation/fb/vt8623fb.txt64
-rw-r--r--Documentation/features/arch-support.txt12
-rw-r--r--Documentation/features/core/cBPF-JIT/arch-support.txt30
-rw-r--r--Documentation/features/core/eBPF-JIT/arch-support.txt30
-rw-r--r--Documentation/features/core/generic-idle-thread/arch-support.txt30
-rw-r--r--Documentation/features/core/jump-labels/arch-support.txt30
-rw-r--r--Documentation/features/core/mseal_sys_mappings/arch-support.txt30
-rw-r--r--Documentation/features/core/thread-info-in-task/arch-support.txt30
-rw-r--r--Documentation/features/core/tracehook/arch-support.txt30
-rw-r--r--Documentation/features/debug/KASAN/arch-support.txt30
-rw-r--r--Documentation/features/debug/debug-vm-pgtable/arch-support.txt30
-rw-r--r--Documentation/features/debug/gcov-profile-all/arch-support.txt30
-rw-r--r--Documentation/features/debug/kcov/arch-support.txt30
-rw-r--r--Documentation/features/debug/kgdb/arch-support.txt30
-rw-r--r--Documentation/features/debug/kmemleak/arch-support.txt30
-rw-r--r--Documentation/features/debug/kprobes-on-ftrace/arch-support.txt30
-rw-r--r--Documentation/features/debug/kprobes/arch-support.txt30
-rw-r--r--Documentation/features/debug/kretprobes/arch-support.txt30
-rw-r--r--Documentation/features/debug/optprobes/arch-support.txt30
-rw-r--r--Documentation/features/debug/stackprotector/arch-support.txt30
-rw-r--r--Documentation/features/debug/uprobes/arch-support.txt30
-rw-r--r--Documentation/features/debug/user-ret-profiler/arch-support.txt30
-rw-r--r--Documentation/features/io/dma-contiguous/arch-support.txt30
-rw-r--r--Documentation/features/locking/cmpxchg-local/arch-support.txt30
-rw-r--r--Documentation/features/locking/lockdep/arch-support.txt30
-rw-r--r--Documentation/features/locking/queued-rwlocks/arch-support.txt30
-rw-r--r--Documentation/features/locking/queued-spinlocks/arch-support.txt30
-rw-r--r--Documentation/features/perf/kprobes-event/arch-support.txt30
-rw-r--r--Documentation/features/perf/perf-regs/arch-support.txt30
-rw-r--r--Documentation/features/perf/perf-stackdump/arch-support.txt30
-rw-r--r--Documentation/features/sched/membarrier-sync-core/arch-support.txt69
-rw-r--r--Documentation/features/sched/numa-balancing/arch-support.txt30
-rw-r--r--Documentation/features/seccomp/seccomp-filter/arch-support.txt30
-rw-r--r--Documentation/features/time/arch-tick-broadcast/arch-support.txt30
-rw-r--r--Documentation/features/time/clockevents/arch-support.txt30
-rw-r--r--Documentation/features/time/context-tracking/arch-support.txt30
-rw-r--r--Documentation/features/time/irq-time-acct/arch-support.txt30
-rw-r--r--Documentation/features/time/virt-cpuacct/arch-support.txt30
-rw-r--r--Documentation/features/vm/ELF-ASLR/arch-support.txt31
-rw-r--r--Documentation/features/vm/THP/arch-support.txt30
-rw-r--r--Documentation/features/vm/TLB/arch-support.txt30
-rw-r--r--Documentation/features/vm/huge-vmap/arch-support.txt30
-rw-r--r--Documentation/features/vm/ioremap_prot/arch-support.txt30
-rw-r--r--Documentation/features/vm/pte_special/arch-support.txt30
-rw-r--r--Documentation/filesystems/.gitignore1
-rw-r--r--Documentation/filesystems/00-INDEX159
-rw-r--r--Documentation/filesystems/9p.rst277
-rw-r--r--Documentation/filesystems/9p.txt161
-rw-r--r--Documentation/filesystems/Locking578
-rw-r--r--Documentation/filesystems/Makefile7
-rw-r--r--Documentation/filesystems/adfs.rst108
-rw-r--r--Documentation/filesystems/adfs.txt75
-rw-r--r--Documentation/filesystems/affs.rst250
-rw-r--r--Documentation/filesystems/affs.txt222
-rw-r--r--Documentation/filesystems/afs.rst251
-rw-r--r--Documentation/filesystems/afs.txt247
-rw-r--r--Documentation/filesystems/api-summary.rst147
-rw-r--r--Documentation/filesystems/autofs-mount-control.rst410
-rw-r--r--Documentation/filesystems/autofs.rst580
-rw-r--r--Documentation/filesystems/autofs4-mount-control.txt393
-rw-r--r--Documentation/filesystems/autofs4.txt520
-rw-r--r--Documentation/filesystems/automount-support.rst98
-rw-r--r--Documentation/filesystems/automount-support.txt118
-rw-r--r--Documentation/filesystems/befs.rst128
-rw-r--r--Documentation/filesystems/befs.txt117
-rw-r--r--Documentation/filesystems/bfs.rst60
-rw-r--r--Documentation/filesystems/bfs.txt57
-rw-r--r--Documentation/filesystems/btrfs.rst43
-rw-r--r--Documentation/filesystems/btrfs.txt270
-rw-r--r--Documentation/filesystems/buffer.rst12
-rw-r--r--Documentation/filesystems/caching/backend-api.rst479
-rw-r--r--Documentation/filesystems/caching/backend-api.txt703
-rw-r--r--Documentation/filesystems/caching/cachefiles.rst662
-rw-r--r--Documentation/filesystems/caching/cachefiles.txt501
-rw-r--r--Documentation/filesystems/caching/fscache.rst348
-rw-r--r--Documentation/filesystems/caching/fscache.txt443
-rw-r--r--Documentation/filesystems/caching/index.rst12
-rw-r--r--Documentation/filesystems/caching/netfs-api.rst452
-rw-r--r--Documentation/filesystems/caching/netfs-api.txt915
-rw-r--r--Documentation/filesystems/caching/object.txt320
-rw-r--r--Documentation/filesystems/caching/operations.txt213
-rw-r--r--Documentation/filesystems/ceph.rst221
-rw-r--r--Documentation/filesystems/ceph.txt148
-rw-r--r--Documentation/filesystems/cifs/AUTHORS57
-rw-r--r--Documentation/filesystems/cifs/CHANGES1065
-rw-r--r--Documentation/filesystems/cifs/README753
-rw-r--r--Documentation/filesystems/cifs/TODO104
-rw-r--r--Documentation/filesystems/cifs/cifs.txt31
-rw-r--r--Documentation/filesystems/coda.rst1670
-rw-r--r--Documentation/filesystems/coda.txt1673
-rw-r--r--Documentation/filesystems/configfs.rst487
-rw-r--r--Documentation/filesystems/configfs/Makefile3
-rw-r--r--Documentation/filesystems/configfs/configfs.txt484
-rw-r--r--Documentation/filesystems/configfs/configfs_example_explicit.c483
-rw-r--r--Documentation/filesystems/configfs/configfs_example_macros.c446
-rw-r--r--Documentation/filesystems/cramfs.rst123
-rw-r--r--Documentation/filesystems/cramfs.txt76
-rw-r--r--Documentation/filesystems/dax.rst305
-rw-r--r--Documentation/filesystems/dax.txt94
-rw-r--r--Documentation/filesystems/debugfs.rst243
-rw-r--r--Documentation/filesystems/debugfs.txt191
-rw-r--r--Documentation/filesystems/devpts.rst36
-rw-r--r--Documentation/filesystems/devpts.txt132
-rw-r--r--Documentation/filesystems/directory-locking127
-rw-r--r--Documentation/filesystems/directory-locking.rst286
-rw-r--r--Documentation/filesystems/dlmfs.rst140
-rw-r--r--Documentation/filesystems/dlmfs.txt130
-rw-r--r--Documentation/filesystems/dnotify.rst75
-rw-r--r--Documentation/filesystems/dnotify.txt70
-rw-r--r--Documentation/filesystems/dnotify_test.c34
-rw-r--r--Documentation/filesystems/ecryptfs.rst86
-rw-r--r--Documentation/filesystems/ecryptfs.txt77
-rw-r--r--Documentation/filesystems/efivarfs.rst43
-rw-r--r--Documentation/filesystems/efivarfs.txt16
-rw-r--r--Documentation/filesystems/erofs.rst369
-rw-r--r--Documentation/filesystems/exofs.txt185
-rw-r--r--Documentation/filesystems/ext2.rst398
-rw-r--r--Documentation/filesystems/ext2.txt384
-rw-r--r--Documentation/filesystems/ext3.rst14
-rw-r--r--Documentation/filesystems/ext3.txt215
-rw-r--r--Documentation/filesystems/ext4.txt629
-rw-r--r--Documentation/filesystems/ext4/about.rst44
-rw-r--r--Documentation/filesystems/ext4/allocators.rst56
-rw-r--r--Documentation/filesystems/ext4/atomic_writes.rst225
-rw-r--r--Documentation/filesystems/ext4/attributes.rst191
-rw-r--r--Documentation/filesystems/ext4/bigalloc.rst34
-rw-r--r--Documentation/filesystems/ext4/bitmaps.rst21
-rw-r--r--Documentation/filesystems/ext4/blockgroup.rst138
-rw-r--r--Documentation/filesystems/ext4/blockmap.rst49
-rw-r--r--Documentation/filesystems/ext4/blocks.rst144
-rw-r--r--Documentation/filesystems/ext4/checksums.rst73
-rw-r--r--Documentation/filesystems/ext4/directory.rst454
-rw-r--r--Documentation/filesystems/ext4/dynamic.rst14
-rw-r--r--Documentation/filesystems/ext4/eainode.rst18
-rw-r--r--Documentation/filesystems/ext4/globals.rst17
-rw-r--r--Documentation/filesystems/ext4/group_descr.rst173
-rw-r--r--Documentation/filesystems/ext4/ifork.rst194
-rw-r--r--Documentation/filesystems/ext4/index.rst14
-rw-r--r--Documentation/filesystems/ext4/inlinedata.rst37
-rw-r--r--Documentation/filesystems/ext4/inode_table.rst9
-rw-r--r--Documentation/filesystems/ext4/inodes.rst580
-rw-r--r--Documentation/filesystems/ext4/journal.rst761
-rw-r--r--Documentation/filesystems/ext4/mmp.rst77
-rw-r--r--Documentation/filesystems/ext4/orphan.rst42
-rw-r--r--Documentation/filesystems/ext4/overview.rst30
-rw-r--r--Documentation/filesystems/ext4/special_inodes.rst55
-rw-r--r--Documentation/filesystems/ext4/super.rst841
-rw-r--r--Documentation/filesystems/ext4/verity.rst44
-rw-r--r--Documentation/filesystems/f2fs.rst1035
-rw-r--r--Documentation/filesystems/f2fs.txt576
-rw-r--r--Documentation/filesystems/fiemap.rst217
-rw-r--r--Documentation/filesystems/fiemap.txt229
-rw-r--r--Documentation/filesystems/files.rst123
-rw-r--r--Documentation/filesystems/files.txt123
-rw-r--r--Documentation/filesystems/fscrypt.rst1597
-rw-r--r--Documentation/filesystems/fsverity.rst912
-rw-r--r--Documentation/filesystems/fuse.txt423
-rw-r--r--Documentation/filesystems/fuse/fuse-io-uring.rst99
-rw-r--r--Documentation/filesystems/fuse/fuse-io.rst45
-rw-r--r--Documentation/filesystems/fuse/fuse-passthrough.rst133
-rw-r--r--Documentation/filesystems/fuse/fuse.rst440
-rw-r--r--Documentation/filesystems/fuse/index.rst14
-rw-r--r--Documentation/filesystems/gfs2-glocks.txt231
-rw-r--r--Documentation/filesystems/gfs2-uevents.txt100
-rw-r--r--Documentation/filesystems/gfs2.txt45
-rw-r--r--Documentation/filesystems/gfs2/glocks.rst249
-rw-r--r--Documentation/filesystems/gfs2/index.rst64
-rw-r--r--Documentation/filesystems/gfs2/uevents.rst112
-rw-r--r--Documentation/filesystems/hfs.rst87
-rw-r--r--Documentation/filesystems/hfs.txt82
-rw-r--r--Documentation/filesystems/hfsplus.rst61
-rw-r--r--Documentation/filesystems/hfsplus.txt59
-rw-r--r--Documentation/filesystems/hpfs.rst353
-rw-r--r--Documentation/filesystems/hpfs.txt296
-rw-r--r--Documentation/filesystems/idmappings.rst1039
-rw-r--r--Documentation/filesystems/index.rst124
-rw-r--r--Documentation/filesystems/inotify.rst90
-rw-r--r--Documentation/filesystems/inotify.txt79
-rw-r--r--Documentation/filesystems/iomap/design.rst459
-rw-r--r--Documentation/filesystems/iomap/index.rst13
-rw-r--r--Documentation/filesystems/iomap/operations.rst785
-rw-r--r--Documentation/filesystems/iomap/porting.rst120
-rw-r--r--Documentation/filesystems/isofs.rst64
-rw-r--r--Documentation/filesystems/isofs.txt48
-rw-r--r--Documentation/filesystems/jfs.txt52
-rw-r--r--Documentation/filesystems/journalling.rst213
-rw-r--r--Documentation/filesystems/locking.rst669
-rw-r--r--Documentation/filesystems/locks.rst65
-rw-r--r--Documentation/filesystems/locks.txt68
-rw-r--r--Documentation/filesystems/logfs.txt241
-rw-r--r--Documentation/filesystems/mandatory-locking.txt171
-rw-r--r--Documentation/filesystems/mount_api.rst811
-rw-r--r--Documentation/filesystems/multigrain-ts.rst125
-rw-r--r--Documentation/filesystems/ncpfs.txt12
-rw-r--r--Documentation/filesystems/netfs_library.rst1051
-rw-r--r--Documentation/filesystems/nfs/00-INDEX26
-rw-r--r--Documentation/filesystems/nfs/Exporting149
-rw-r--r--Documentation/filesystems/nfs/client-identifier.rst216
-rw-r--r--Documentation/filesystems/nfs/exporting.rst240
-rw-r--r--Documentation/filesystems/nfs/fault_injection.txt69
-rw-r--r--Documentation/filesystems/nfs/idmapper.txt75
-rw-r--r--Documentation/filesystems/nfs/index.rst18
-rw-r--r--Documentation/filesystems/nfs/knfsd-stats.rst122
-rw-r--r--Documentation/filesystems/nfs/knfsd-stats.txt159
-rw-r--r--Documentation/filesystems/nfs/localio.rst357
-rw-r--r--Documentation/filesystems/nfs/nfs-rdma.txt276
-rw-r--r--Documentation/filesystems/nfs/nfs.txt136
-rw-r--r--Documentation/filesystems/nfs/nfs41-server.rst256
-rw-r--r--Documentation/filesystems/nfs/nfs41-server.txt173
-rw-r--r--Documentation/filesystems/nfs/nfsd-admin-interfaces.txt41
-rw-r--r--Documentation/filesystems/nfs/nfsd-io-modes.rst153
-rw-r--r--Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst547
-rw-r--r--Documentation/filesystems/nfs/nfsroot.txt302
-rw-r--r--Documentation/filesystems/nfs/pnfs-block-server.txt37
-rw-r--r--Documentation/filesystems/nfs/pnfs.rst78
-rw-r--r--Documentation/filesystems/nfs/pnfs.txt110
-rw-r--r--Documentation/filesystems/nfs/reexport.rst117
-rw-r--r--Documentation/filesystems/nfs/rpc-cache.rst220
-rw-r--r--Documentation/filesystems/nfs/rpc-cache.txt202
-rw-r--r--Documentation/filesystems/nfs/rpc-server-gss.rst93
-rw-r--r--Documentation/filesystems/nfs/rpc-server-gss.txt91
-rw-r--r--Documentation/filesystems/nilfs2.rst286
-rw-r--r--Documentation/filesystems/nilfs2.txt270
-rw-r--r--Documentation/filesystems/ntfs.txt451
-rw-r--r--Documentation/filesystems/ntfs3.rst123
-rw-r--r--Documentation/filesystems/ocfs2-online-filecheck.rst99
-rw-r--r--Documentation/filesystems/ocfs2.rst117
-rw-r--r--Documentation/filesystems/ocfs2.txt106
-rw-r--r--Documentation/filesystems/omfs.rst112
-rw-r--r--Documentation/filesystems/omfs.txt106
-rw-r--r--Documentation/filesystems/orangefs.rst556
-rw-r--r--Documentation/filesystems/overlayfs.rst833
-rw-r--r--Documentation/filesystems/overlayfs.txt226
-rw-r--r--Documentation/filesystems/path-lookup.rst1390
-rw-r--r--Documentation/filesystems/path-lookup.txt4
-rw-r--r--Documentation/filesystems/pohmelfs/design_notes.txt72
-rw-r--r--Documentation/filesystems/pohmelfs/info.txt99
-rw-r--r--Documentation/filesystems/pohmelfs/network_protocol.txt227
-rw-r--r--Documentation/filesystems/porting485
-rw-r--r--Documentation/filesystems/porting.rst1336
-rw-r--r--Documentation/filesystems/proc.rst2454
-rw-r--r--Documentation/filesystems/proc.txt1869
-rw-r--r--Documentation/filesystems/propagate_umount.txt484
-rw-r--r--Documentation/filesystems/qnx6.rst196
-rw-r--r--Documentation/filesystems/qnx6.txt174
-rw-r--r--Documentation/filesystems/quota.rst85
-rw-r--r--Documentation/filesystems/quota.txt65
-rw-r--r--Documentation/filesystems/ramfs-rootfs-initramfs.rst368
-rw-r--r--Documentation/filesystems/ramfs-rootfs-initramfs.txt359
-rw-r--r--Documentation/filesystems/relay.rst491
-rw-r--r--Documentation/filesystems/relay.txt494
-rw-r--r--Documentation/filesystems/resctrl.rst1932
-rw-r--r--Documentation/filesystems/romfs.rst194
-rw-r--r--Documentation/filesystems/romfs.txt186
-rw-r--r--Documentation/filesystems/seq_file.rst396
-rw-r--r--Documentation/filesystems/seq_file.txt338
-rw-r--r--Documentation/filesystems/sharedsubtree.rst994
-rw-r--r--Documentation/filesystems/sharedsubtree.txt939
-rw-r--r--Documentation/filesystems/smb/cifsroot.rst105
-rw-r--r--Documentation/filesystems/smb/index.rst11
-rw-r--r--Documentation/filesystems/smb/ksmbd.rst186
-rw-r--r--Documentation/filesystems/smb/smbdirect.rst103
-rw-r--r--Documentation/filesystems/splice.rst22
-rw-r--r--Documentation/filesystems/spufs.txt521
-rw-r--r--Documentation/filesystems/spufs/index.rst13
-rw-r--r--Documentation/filesystems/spufs/spu_create.rst131
-rw-r--r--Documentation/filesystems/spufs/spu_run.rst138
-rw-r--r--Documentation/filesystems/spufs/spufs.rst273
-rw-r--r--Documentation/filesystems/squashfs.rst323
-rw-r--r--Documentation/filesystems/squashfs.txt259
-rw-r--r--Documentation/filesystems/sysfs-pci.txt120
-rw-r--r--Documentation/filesystems/sysfs-tagging.txt42
-rw-r--r--Documentation/filesystems/sysfs.rst435
-rw-r--r--Documentation/filesystems/sysfs.txt380
-rw-r--r--Documentation/filesystems/sysv-fs.txt197
-rw-r--r--Documentation/filesystems/tmpfs.rst276
-rw-r--r--Documentation/filesystems/tmpfs.txt148
-rw-r--r--Documentation/filesystems/ubifs-authentication.rst448
-rw-r--r--Documentation/filesystems/ubifs.rst137
-rw-r--r--Documentation/filesystems/ubifs.txt119
-rw-r--r--Documentation/filesystems/udf.rst75
-rw-r--r--Documentation/filesystems/udf.txt82
-rw-r--r--Documentation/filesystems/ufs.txt60
-rw-r--r--Documentation/filesystems/vfat.rst387
-rw-r--r--Documentation/filesystems/vfat.txt336
-rw-r--r--Documentation/filesystems/vfs.rst1555
-rw-r--r--Documentation/filesystems/vfs.txt1171
-rw-r--r--Documentation/filesystems/virtiofs.rst76
-rw-r--r--Documentation/filesystems/xfs-delayed-logging-design.txt793
-rw-r--r--Documentation/filesystems/xfs-self-describing-metadata.txt350
-rw-r--r--Documentation/filesystems/xfs.txt350
-rw-r--r--Documentation/filesystems/xfs/index.rst14
-rw-r--r--Documentation/filesystems/xfs/xfs-delayed-logging-design.rst1087
-rw-r--r--Documentation/filesystems/xfs/xfs-maintainer-entry-profile.rst194
-rw-r--r--Documentation/filesystems/xfs/xfs-online-fsck-design.rst5279
-rw-r--r--Documentation/filesystems/xfs/xfs-self-describing-metadata.rst353
-rw-r--r--Documentation/filesystems/zonefs.rst485
-rw-r--r--Documentation/firmware-guide/acpi/DSD-properties-rules.rst103
-rw-r--r--Documentation/firmware-guide/acpi/acpi-lid.rst114
-rw-r--r--Documentation/firmware-guide/acpi/aml-debugger.rst75
-rw-r--r--Documentation/firmware-guide/acpi/apei/einj.rst271
-rw-r--r--Documentation/firmware-guide/acpi/apei/output_format.rst150
-rw-r--r--Documentation/firmware-guide/acpi/chromeos-acpi-device.rst362
-rw-r--r--Documentation/firmware-guide/acpi/debug.rst132
-rw-r--r--Documentation/firmware-guide/acpi/dsd/data-node-references.rst94
-rw-r--r--Documentation/firmware-guide/acpi/dsd/graph.rst170
-rw-r--r--Documentation/firmware-guide/acpi/dsd/leds.rst102
-rw-r--r--Documentation/firmware-guide/acpi/dsd/phy.rst201
-rw-r--r--Documentation/firmware-guide/acpi/enumeration.rst733
-rw-r--r--Documentation/firmware-guide/acpi/extcon-intel-int3496.rst33
-rw-r--r--Documentation/firmware-guide/acpi/gpio-properties.rst336
-rw-r--r--Documentation/firmware-guide/acpi/i2c-muxes.rst61
-rw-r--r--Documentation/firmware-guide/acpi/index.rst31
-rw-r--r--Documentation/firmware-guide/acpi/intel-pmc-mux.rst153
-rw-r--r--Documentation/firmware-guide/acpi/lpit.rst33
-rw-r--r--Documentation/firmware-guide/acpi/method-tracing.rst238
-rw-r--r--Documentation/firmware-guide/acpi/namespace.rst400
-rw-r--r--Documentation/firmware-guide/acpi/non-d0-probe.rst78
-rw-r--r--Documentation/firmware-guide/acpi/osi.rst187
-rw-r--r--Documentation/firmware-guide/acpi/video_extension.rst121
-rw-r--r--Documentation/firmware-guide/index.rst13
-rw-r--r--Documentation/firmware_class/README128
-rw-r--r--Documentation/flexible-arrays.txt120
-rw-r--r--Documentation/fmc/00-INDEX38
-rw-r--r--Documentation/fmc/API.txt47
-rw-r--r--Documentation/fmc/FMC-and-SDB.txt88
-rw-r--r--Documentation/fmc/carrier.txt311
-rw-r--r--Documentation/fmc/fmc-chardev.txt64
-rw-r--r--Documentation/fmc/fmc-fakedev.txt36
-rw-r--r--Documentation/fmc/fmc-trivial.txt17
-rw-r--r--Documentation/fmc/fmc-write-eeprom.txt98
-rw-r--r--Documentation/fmc/identifiers.txt168
-rw-r--r--Documentation/fmc/mezzanine.txt123
-rw-r--r--Documentation/fmc/parameters.txt56
-rw-r--r--Documentation/fpga/dfl.rst687
-rw-r--r--Documentation/fpga/index.rst17
-rw-r--r--Documentation/frv/README.txt51
-rw-r--r--Documentation/frv/atomic-ops.txt134
-rw-r--r--Documentation/frv/booting.txt182
-rw-r--r--Documentation/frv/clock.txt65
-rw-r--r--Documentation/frv/configuring.txt125
-rw-r--r--Documentation/frv/features.txt310
-rw-r--r--Documentation/frv/gdbinit102
-rw-r--r--Documentation/frv/gdbstub.txt130
-rw-r--r--Documentation/frv/kernel-ABI.txt262
-rw-r--r--Documentation/frv/mmu-layout.txt306
-rw-r--r--Documentation/futex-requeue-pi.txt131
-rw-r--r--Documentation/gcov.txt257
-rw-r--r--Documentation/gdb-kernel-debugging.txt160
-rw-r--r--Documentation/gpio/00-INDEX14
-rw-r--r--Documentation/gpio/board.txt154
-rw-r--r--Documentation/gpio/consumer.txt340
-rw-r--r--Documentation/gpio/driver.txt192
-rw-r--r--Documentation/gpio/gpio-legacy.txt775
-rw-r--r--Documentation/gpio/gpio.txt119
-rw-r--r--Documentation/gpio/sysfs.txt155
-rw-r--r--Documentation/gpu/afbc.rst235
-rw-r--r--Documentation/gpu/amdgpu/amd-hardware-list-info.rst23
-rw-r--r--Documentation/gpu/amdgpu/amdgpu-glossary.rst237
-rw-r--r--Documentation/gpu/amdgpu/apu-asic-info-table.csv18
-rw-r--r--Documentation/gpu/amdgpu/debugfs.rst210
-rw-r--r--Documentation/gpu/amdgpu/debugging.rst105
-rw-r--r--Documentation/gpu/amdgpu/dgpu-asic-info-table.csv30
-rw-r--r--Documentation/gpu/amdgpu/display/config_example.svg414
-rw-r--r--Documentation/gpu/amdgpu/display/dc-arch-overview.svg731
-rw-r--r--Documentation/gpu/amdgpu/display/dc-components.svg732
-rw-r--r--Documentation/gpu/amdgpu/display/dc-debug.rst305
-rw-r--r--Documentation/gpu/amdgpu/display/dc-glossary.rst231
-rw-r--r--Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg1125
-rw-r--r--Documentation/gpu/amdgpu/display/dcn-blocks.rst57
-rw-r--r--Documentation/gpu/amdgpu/display/dcn-overview.rst232
-rw-r--r--Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg1370
-rw-r--r--Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg1529
-rw-r--r--Documentation/gpu/amdgpu/display/display-contributing.rst168
-rw-r--r--Documentation/gpu/amdgpu/display/display-manager.rst180
-rw-r--r--Documentation/gpu/amdgpu/display/global_sync_vblank.svg485
-rw-r--r--Documentation/gpu/amdgpu/display/index.rst97
-rw-r--r--Documentation/gpu/amdgpu/display/mpo-cursor.svg435
-rw-r--r--Documentation/gpu/amdgpu/display/mpo-overview.rst242
-rw-r--r--Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg220
-rw-r--r--Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg171
-rw-r--r--Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg958
-rw-r--r--Documentation/gpu/amdgpu/display/pipeline_4k_split.svg1062
-rw-r--r--Documentation/gpu/amdgpu/display/programming-model-dcn.rst162
-rw-r--r--Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg339
-rw-r--r--Documentation/gpu/amdgpu/display/single-display-mpo.svg266
-rw-r--r--Documentation/gpu/amdgpu/display/trace-groups-table.csv29
-rw-r--r--Documentation/gpu/amdgpu/driver-core.rst213
-rw-r--r--Documentation/gpu/amdgpu/driver-misc.rst130
-rw-r--r--Documentation/gpu/amdgpu/flashing.rst33
-rw-r--r--Documentation/gpu/amdgpu/gc/index.rst52
-rw-r--r--Documentation/gpu/amdgpu/gc/mes.rst38
-rw-r--r--Documentation/gpu/amdgpu/index.rst24
-rw-r--r--Documentation/gpu/amdgpu/module-parameters.rst7
-rw-r--r--Documentation/gpu/amdgpu/pipe_and_queue_abstraction.svg1279
-rw-r--r--Documentation/gpu/amdgpu/process-isolation.rst59
-rw-r--r--Documentation/gpu/amdgpu/ras.rst62
-rw-r--r--Documentation/gpu/amdgpu/thermal.rst170
-rw-r--r--Documentation/gpu/amdgpu/userq.rst203
-rw-r--r--Documentation/gpu/amdgpu/xgmi.rst5
-rw-r--r--Documentation/gpu/automated_testing.rst171
-rw-r--r--Documentation/gpu/backlight.rst12
-rw-r--r--Documentation/gpu/bridge/dw-hdmi.rst15
-rw-r--r--Documentation/gpu/dp-mst/topology-figure-1.dot52
-rw-r--r--Documentation/gpu/dp-mst/topology-figure-2.dot56
-rw-r--r--Documentation/gpu/dp-mst/topology-figure-3.dot59
-rw-r--r--Documentation/gpu/driver-uapi.rst34
-rw-r--r--Documentation/gpu/drivers.rst35
-rw-r--r--Documentation/gpu/drm-client.rst18
-rw-r--r--Documentation/gpu/drm-compute.rst54
-rw-r--r--Documentation/gpu/drm-internals.rst250
-rw-r--r--Documentation/gpu/drm-kms-helpers.rst498
-rw-r--r--Documentation/gpu/drm-kms.rst666
-rw-r--r--Documentation/gpu/drm-mm.rst575
-rw-r--r--Documentation/gpu/drm-uapi.rst764
-rw-r--r--Documentation/gpu/drm-usage-stats.rst217
-rw-r--r--Documentation/gpu/drm-vm-bind-async.rst309
-rw-r--r--Documentation/gpu/drm-vm-bind-locking.rst582
-rw-r--r--Documentation/gpu/i915.rst747
-rw-r--r--Documentation/gpu/imagination/index.rst13
-rw-r--r--Documentation/gpu/imagination/uapi.rst171
-rw-r--r--Documentation/gpu/implementation_guidelines.rst10
-rw-r--r--Documentation/gpu/index.rst31
-rw-r--r--Documentation/gpu/introduction.rst176
-rw-r--r--Documentation/gpu/kms-properties.csv99
-rw-r--r--Documentation/gpu/komeda-kms.rst488
-rw-r--r--Documentation/gpu/mcde.rst8
-rw-r--r--Documentation/gpu/meson.rst55
-rw-r--r--Documentation/gpu/msm-crash-dump.rst98
-rw-r--r--Documentation/gpu/msm-preemption.rst99
-rw-r--r--Documentation/gpu/nouveau.rst32
-rw-r--r--Documentation/gpu/nova/core/devinit.rst61
-rw-r--r--Documentation/gpu/nova/core/falcon.rst158
-rw-r--r--Documentation/gpu/nova/core/fwsec.rst181
-rw-r--r--Documentation/gpu/nova/core/guidelines.rst24
-rw-r--r--Documentation/gpu/nova/core/todo.rst399
-rw-r--r--Documentation/gpu/nova/core/vbios.rst181
-rw-r--r--Documentation/gpu/nova/guidelines.rst69
-rw-r--r--Documentation/gpu/nova/index.rst34
-rw-r--r--Documentation/gpu/panfrost.rst49
-rw-r--r--Documentation/gpu/panthor.rst56
-rw-r--r--Documentation/gpu/pl111.rst6
-rw-r--r--Documentation/gpu/rfc/color_pipeline.rst378
-rw-r--r--Documentation/gpu/rfc/gpusvm.rst118
-rw-r--r--Documentation/gpu/rfc/i915_gem_lmem.rst22
-rw-r--r--Documentation/gpu/rfc/i915_scheduler.rst152
-rw-r--r--Documentation/gpu/rfc/i915_small_bar.h189
-rw-r--r--Documentation/gpu/rfc/i915_small_bar.rst47
-rw-r--r--Documentation/gpu/rfc/i915_vm_bind.h290
-rw-r--r--Documentation/gpu/rfc/i915_vm_bind.rst245
-rw-r--r--Documentation/gpu/rfc/index.rst40
-rw-r--r--Documentation/gpu/tegra.rst178
-rw-r--r--Documentation/gpu/todo.rst911
-rw-r--r--Documentation/gpu/tve200.rst6
-rw-r--r--Documentation/gpu/v3d.rst28
-rw-r--r--Documentation/gpu/vc4.rst108
-rw-r--r--Documentation/gpu/vga-switcheroo.rst98
-rw-r--r--Documentation/gpu/vgaarbiter.rst191
-rw-r--r--Documentation/gpu/vkms.rst287
-rw-r--r--Documentation/gpu/xe/index.rst31
-rw-r--r--Documentation/gpu/xe/xe-drm-usage-stats.rst10
-rw-r--r--Documentation/gpu/xe/xe_configfs.rst16
-rw-r--r--Documentation/gpu/xe/xe_cs.rst8
-rw-r--r--Documentation/gpu/xe/xe_debugging.rst7
-rw-r--r--Documentation/gpu/xe/xe_devcoredump.rst14
-rw-r--r--Documentation/gpu/xe/xe_device.rst10
-rw-r--r--Documentation/gpu/xe/xe_exec_queue.rst20
-rw-r--r--Documentation/gpu/xe/xe_firmware.rst43
-rw-r--r--Documentation/gpu/xe/xe_gt_freq.rst17
-rw-r--r--Documentation/gpu/xe/xe_gt_mcr.rst13
-rw-r--r--Documentation/gpu/xe/xe_map.rst8
-rw-r--r--Documentation/gpu/xe/xe_migrate.rst8
-rw-r--r--Documentation/gpu/xe/xe_mm.rst29
-rw-r--r--Documentation/gpu/xe/xe_pcode.rst23
-rw-r--r--Documentation/gpu/xe/xe_pm.rst14
-rw-r--r--Documentation/gpu/xe/xe_rtp.rst20
-rw-r--r--Documentation/gpu/xe/xe_tile.rst14
-rw-r--r--Documentation/gpu/xe/xe_wa.rst14
-rw-r--r--Documentation/gpu/xen-front.rst31
-rw-r--r--Documentation/gpu/zynqmp.rst147
-rw-r--r--Documentation/hid/amd-sfh-hid.rst145
-rw-r--r--Documentation/hid/hid-alps.rst184
-rw-r--r--Documentation/hid/hid-bpf.rst527
-rw-r--r--Documentation/hid/hid-sensor.rst242
-rw-r--r--Documentation/hid/hid-sensor.txt224
-rw-r--r--Documentation/hid/hid-transport.rst359
-rw-r--r--Documentation/hid/hid-transport.txt317
-rw-r--r--Documentation/hid/hiddev.rst251
-rw-r--r--Documentation/hid/hiddev.txt205
-rw-r--r--Documentation/hid/hidintro.rst524
-rw-r--r--Documentation/hid/hidraw.rst180
-rw-r--r--Documentation/hid/hidraw.txt119
-rw-r--r--Documentation/hid/hidreport-parsing.rst49
-rw-r--r--Documentation/hid/index.rst22
-rw-r--r--Documentation/hid/intel-ish-hid.rst581
-rw-r--r--Documentation/hid/intel-thc-hid.rst596
-rw-r--r--Documentation/hid/uhid.rst193
-rw-r--r--Documentation/hid/uhid.txt187
-rw-r--r--Documentation/highuid.txt77
-rw-r--r--Documentation/hsi.txt75
-rw-r--r--Documentation/hw_random.txt90
-rw-r--r--Documentation/hwmon/ab850022
-rw-r--r--Documentation/hwmon/abituguru92
-rw-r--r--Documentation/hwmon/abituguru-datasheet312
-rw-r--r--Documentation/hwmon/abituguru-datasheet.rst336
-rw-r--r--Documentation/hwmon/abituguru.rst113
-rw-r--r--Documentation/hwmon/abituguru365
-rw-r--r--Documentation/hwmon/abituguru3.rst75
-rw-r--r--Documentation/hwmon/abx50028
-rw-r--r--Documentation/hwmon/acbel-fsg032.rst80
-rw-r--r--Documentation/hwmon/acpi_power_meter51
-rw-r--r--Documentation/hwmon/acpi_power_meter.rst77
-rw-r--r--Documentation/hwmon/ad731425
-rw-r--r--Documentation/hwmon/ad7314.rst34
-rw-r--r--Documentation/hwmon/adc128d81847
-rw-r--r--Documentation/hwmon/adc128d818.rst50
-rw-r--r--Documentation/hwmon/adm1021113
-rw-r--r--Documentation/hwmon/adm102551
-rw-r--r--Documentation/hwmon/adm1025.rst60
-rw-r--r--Documentation/hwmon/adm102693
-rw-r--r--Documentation/hwmon/adm1026.rst101
-rw-r--r--Documentation/hwmon/adm103135
-rw-r--r--Documentation/hwmon/adm1031.rst43
-rw-r--r--Documentation/hwmon/adm1177.rst36
-rw-r--r--Documentation/hwmon/adm1266.rst37
-rw-r--r--Documentation/hwmon/adm127592
-rw-r--r--Documentation/hwmon/adm1275.rst172
-rw-r--r--Documentation/hwmon/adm9240177
-rw-r--r--Documentation/hwmon/adm9240.rst201
-rw-r--r--Documentation/hwmon/adp1050.rst123
-rw-r--r--Documentation/hwmon/ads101576
-rw-r--r--Documentation/hwmon/ads782858
-rw-r--r--Documentation/hwmon/ads7828.rst65
-rw-r--r--Documentation/hwmon/adt741073
-rw-r--r--Documentation/hwmon/adt7410.rst94
-rw-r--r--Documentation/hwmon/adt741142
-rw-r--r--Documentation/hwmon/adt7411.rst50
-rw-r--r--Documentation/hwmon/adt746267
-rw-r--r--Documentation/hwmon/adt7462.rst70
-rw-r--r--Documentation/hwmon/adt747073
-rw-r--r--Documentation/hwmon/adt7470.rst94
-rw-r--r--Documentation/hwmon/adt7475117
-rw-r--r--Documentation/hwmon/adt7475.rst157
-rw-r--r--Documentation/hwmon/aht10.rst64
-rw-r--r--Documentation/hwmon/amc6821102
-rw-r--r--Documentation/hwmon/amc6821.rst113
-rw-r--r--Documentation/hwmon/aquacomputer_d5next.rst117
-rw-r--r--Documentation/hwmon/asb10072
-rw-r--r--Documentation/hwmon/asb100.rst73
-rw-r--r--Documentation/hwmon/asc7621296
-rw-r--r--Documentation/hwmon/asc7621.rst326
-rw-r--r--Documentation/hwmon/aspeed-g6-pwm-tach.rst26
-rw-r--r--Documentation/hwmon/aspeed-pwm-tacho.rst24
-rw-r--r--Documentation/hwmon/asus_ec_sensors.rst91
-rw-r--r--Documentation/hwmon/asus_rog_ryujin.rst47
-rw-r--r--Documentation/hwmon/asus_wmi_sensors.rst78
-rw-r--r--Documentation/hwmon/bcm54140.rst45
-rw-r--r--Documentation/hwmon/bel-pfe.rst112
-rw-r--r--Documentation/hwmon/bpa-rs600.rst74
-rw-r--r--Documentation/hwmon/bt1-pvt.rst117
-rw-r--r--Documentation/hwmon/cgbc-hwmon.rst63
-rw-r--r--Documentation/hwmon/chipcap2.rst73
-rw-r--r--Documentation/hwmon/coretemp181
-rw-r--r--Documentation/hwmon/coretemp.rst195
-rw-r--r--Documentation/hwmon/corsair-cpro.rst49
-rw-r--r--Documentation/hwmon/corsair-psu.rst101
-rw-r--r--Documentation/hwmon/cros_ec_hwmon.rst31
-rw-r--r--Documentation/hwmon/crps.rst97
-rw-r--r--Documentation/hwmon/da905261
-rw-r--r--Documentation/hwmon/da9052.rst78
-rw-r--r--Documentation/hwmon/da905547
-rw-r--r--Documentation/hwmon/da9055.rst57
-rw-r--r--Documentation/hwmon/dell-smm-hwmon.rst407
-rw-r--r--Documentation/hwmon/dme1737328
-rw-r--r--Documentation/hwmon/dme1737.rst364
-rw-r--r--Documentation/hwmon/dps920ab.rst73
-rw-r--r--Documentation/hwmon/drivetemp.rst70
-rw-r--r--Documentation/hwmon/ds1621187
-rw-r--r--Documentation/hwmon/ds1621.rst217
-rw-r--r--Documentation/hwmon/ds62034
-rw-r--r--Documentation/hwmon/ds620.rst38
-rw-r--r--Documentation/hwmon/emc140359
-rw-r--r--Documentation/hwmon/emc1403.rst91
-rw-r--r--Documentation/hwmon/emc210333
-rw-r--r--Documentation/hwmon/emc2103.rst37
-rw-r--r--Documentation/hwmon/emc2305.rst36
-rw-r--r--Documentation/hwmon/emc6w20142
-rw-r--r--Documentation/hwmon/emc6w201.rst47
-rw-r--r--Documentation/hwmon/f71805f167
-rw-r--r--Documentation/hwmon/f71805f.rst181
-rw-r--r--Documentation/hwmon/f71882fg138
-rw-r--r--Documentation/hwmon/f71882fg.rst193
-rw-r--r--Documentation/hwmon/fam15h_power37
-rw-r--r--Documentation/hwmon/fam15h_power.rst131
-rw-r--r--Documentation/hwmon/fsp-3y.rst28
-rw-r--r--Documentation/hwmon/ftsteutates.rst42
-rw-r--r--Documentation/hwmon/g760a36
-rw-r--r--Documentation/hwmon/g760a.rst40
-rw-r--r--Documentation/hwmon/g76265
-rw-r--r--Documentation/hwmon/g762.rst74
-rw-r--r--Documentation/hwmon/gigabyte_waterforce.rst47
-rw-r--r--Documentation/hwmon/gl518sm73
-rw-r--r--Documentation/hwmon/gl518sm.rst80
-rw-r--r--Documentation/hwmon/gpd-fan.rst78
-rw-r--r--Documentation/hwmon/gsc-hwmon.rst53
-rw-r--r--Documentation/hwmon/gxp-fan-ctrl.rst28
-rw-r--r--Documentation/hwmon/hih613037
-rw-r--r--Documentation/hwmon/hih6130.rst45
-rw-r--r--Documentation/hwmon/hp-wmi-sensors.rst140
-rw-r--r--Documentation/hwmon/hs3001.rst37
-rw-r--r--Documentation/hwmon/htu2146
-rw-r--r--Documentation/hwmon/htu31.rst37
-rw-r--r--Documentation/hwmon/hwmon-kernel-api.rst381
-rw-r--r--Documentation/hwmon/hwmon-kernel-api.txt107
-rw-r--r--Documentation/hwmon/ibm-cffps.rst57
-rw-r--r--Documentation/hwmon/ibmaem38
-rw-r--r--Documentation/hwmon/ibmaem.rst44
-rw-r--r--Documentation/hwmon/ibmpowernv41
-rw-r--r--Documentation/hwmon/ibmpowernv.rst87
-rw-r--r--Documentation/hwmon/ina20993
-rw-r--r--Documentation/hwmon/ina209.rst99
-rw-r--r--Documentation/hwmon/ina233.rst75
-rw-r--r--Documentation/hwmon/ina238.rst109
-rw-r--r--Documentation/hwmon/ina2xx64
-rw-r--r--Documentation/hwmon/ina2xx.rst163
-rw-r--r--Documentation/hwmon/ina3221.rst74
-rw-r--r--Documentation/hwmon/index.rst290
-rw-r--r--Documentation/hwmon/inspur-ipsps1.rst79
-rw-r--r--Documentation/hwmon/intel-m10-bmc-hwmon.rst78
-rw-r--r--Documentation/hwmon/ir35221.rst92
-rw-r--r--Documentation/hwmon/ir36021.rst63
-rw-r--r--Documentation/hwmon/ir38064.rst90
-rw-r--r--Documentation/hwmon/isl28022.rst64
-rw-r--r--Documentation/hwmon/isl68137.rst635
-rw-r--r--Documentation/hwmon/it87262
-rw-r--r--Documentation/hwmon/it87.rst385
-rw-r--r--Documentation/hwmon/jc42102
-rw-r--r--Documentation/hwmon/jc42.rst152
-rw-r--r--Documentation/hwmon/k10temp77
-rw-r--r--Documentation/hwmon/k10temp.rst134
-rw-r--r--Documentation/hwmon/k8temp55
-rw-r--r--Documentation/hwmon/k8temp.rst62
-rw-r--r--Documentation/hwmon/kbatt.rst60
-rw-r--r--Documentation/hwmon/kfan.rst39
-rw-r--r--Documentation/hwmon/lan966x.rst40
-rw-r--r--Documentation/hwmon/lineage-pem77
-rw-r--r--Documentation/hwmon/lineage-pem.rst85
-rw-r--r--Documentation/hwmon/lm25066120
-rw-r--r--Documentation/hwmon/lm25066.rst139
-rw-r--r--Documentation/hwmon/lm6377
-rw-r--r--Documentation/hwmon/lm63.rst95
-rw-r--r--Documentation/hwmon/lm7047
-rw-r--r--Documentation/hwmon/lm70.rst69
-rw-r--r--Documentation/hwmon/lm7390
-rw-r--r--Documentation/hwmon/lm73.rst98
-rw-r--r--Documentation/hwmon/lm7592
-rw-r--r--Documentation/hwmon/lm75.rst183
-rw-r--r--Documentation/hwmon/lm7738
-rw-r--r--Documentation/hwmon/lm77.rst45
-rw-r--r--Documentation/hwmon/lm7868
-rw-r--r--Documentation/hwmon/lm78.rst80
-rw-r--r--Documentation/hwmon/lm8063
-rw-r--r--Documentation/hwmon/lm80.rst74
-rw-r--r--Documentation/hwmon/lm8385
-rw-r--r--Documentation/hwmon/lm83.rst97
-rw-r--r--Documentation/hwmon/lm85230
-rw-r--r--Documentation/hwmon/lm85.rst286
-rw-r--r--Documentation/hwmon/lm8777
-rw-r--r--Documentation/hwmon/lm87.rst86
-rw-r--r--Documentation/hwmon/lm90275
-rw-r--r--Documentation/hwmon/lm90.rst703
-rw-r--r--Documentation/hwmon/lm9237
-rw-r--r--Documentation/hwmon/lm92.rst48
-rw-r--r--Documentation/hwmon/lm93309
-rw-r--r--Documentation/hwmon/lm93.rst312
-rw-r--r--Documentation/hwmon/lm9523441
-rw-r--r--Documentation/hwmon/lm95234.rst48
-rw-r--r--Documentation/hwmon/lm9524541
-rw-r--r--Documentation/hwmon/lm95245.rst48
-rw-r--r--Documentation/hwmon/lochnagar.rst83
-rw-r--r--Documentation/hwmon/lt3074.rst72
-rw-r--r--Documentation/hwmon/lt7182s.rst92
-rw-r--r--Documentation/hwmon/ltc294584
-rw-r--r--Documentation/hwmon/ltc2945.rst92
-rw-r--r--Documentation/hwmon/ltc2947.rst100
-rw-r--r--Documentation/hwmon/ltc2978157
-rw-r--r--Documentation/hwmon/ltc2978.rst491
-rw-r--r--Documentation/hwmon/ltc2990.rst62
-rw-r--r--Documentation/hwmon/ltc2991.rst43
-rw-r--r--Documentation/hwmon/ltc2992.rst56
-rw-r--r--Documentation/hwmon/ltc3815.rst67
-rw-r--r--Documentation/hwmon/ltc415147
-rw-r--r--Documentation/hwmon/ltc4151.rst55
-rw-r--r--Documentation/hwmon/ltc421551
-rw-r--r--Documentation/hwmon/ltc4215.rst59
-rw-r--r--Documentation/hwmon/ltc4245102
-rw-r--r--Documentation/hwmon/ltc4245.rst111
-rw-r--r--Documentation/hwmon/ltc426056
-rw-r--r--Documentation/hwmon/ltc4260.rst64
-rw-r--r--Documentation/hwmon/ltc426163
-rw-r--r--Documentation/hwmon/ltc4261.rst71
-rw-r--r--Documentation/hwmon/ltc4282.rst133
-rw-r--r--Documentation/hwmon/ltc4286.rst95
-rw-r--r--Documentation/hwmon/macsmc-hwmon.rst71
-rw-r--r--Documentation/hwmon/max127.rst45
-rw-r--r--Documentation/hwmon/max15301.rst95
-rw-r--r--Documentation/hwmon/max1606466
-rw-r--r--Documentation/hwmon/max16064.rst75
-rw-r--r--Documentation/hwmon/max16065105
-rw-r--r--Documentation/hwmon/max16065.rst127
-rw-r--r--Documentation/hwmon/max161929
-rw-r--r--Documentation/hwmon/max1619.rst29
-rw-r--r--Documentation/hwmon/max16601.rst145
-rw-r--r--Documentation/hwmon/max166860
-rw-r--r--Documentation/hwmon/max1668.rst70
-rw-r--r--Documentation/hwmon/max17616.rst62
-rw-r--r--Documentation/hwmon/max19760
-rw-r--r--Documentation/hwmon/max197.rst70
-rw-r--r--Documentation/hwmon/max20730.rst82
-rw-r--r--Documentation/hwmon/max20751.rst84
-rw-r--r--Documentation/hwmon/max31722.rst46
-rw-r--r--Documentation/hwmon/max31730.rst44
-rw-r--r--Documentation/hwmon/max31760.rst77
-rw-r--r--Documentation/hwmon/max31785.rst66
-rw-r--r--Documentation/hwmon/max31790.rst45
-rw-r--r--Documentation/hwmon/max31827.rst144
-rw-r--r--Documentation/hwmon/max34440127
-rw-r--r--Documentation/hwmon/max34440.rst220
-rw-r--r--Documentation/hwmon/max6620.rst46
-rw-r--r--Documentation/hwmon/max663949
-rw-r--r--Documentation/hwmon/max6639.rst55
-rw-r--r--Documentation/hwmon/max664221
-rw-r--r--Documentation/hwmon/max665064
-rw-r--r--Documentation/hwmon/max6650.rst74
-rw-r--r--Documentation/hwmon/max669758
-rw-r--r--Documentation/hwmon/max6697.rst91
-rw-r--r--Documentation/hwmon/max77705.rst41
-rw-r--r--Documentation/hwmon/max868875
-rw-r--r--Documentation/hwmon/max8688.rst85
-rw-r--r--Documentation/hwmon/mc13783-adc74
-rw-r--r--Documentation/hwmon/mc13783-adc.rst89
-rw-r--r--Documentation/hwmon/mc33xs2410_hwmon.rst34
-rw-r--r--Documentation/hwmon/mc34vr500.rst32
-rw-r--r--Documentation/hwmon/mcp302129
-rw-r--r--Documentation/hwmon/mcp3021.rst38
-rw-r--r--Documentation/hwmon/menf21bmc50
-rw-r--r--Documentation/hwmon/menf21bmc.rst55
-rw-r--r--Documentation/hwmon/mlxreg-fan.rst70
-rw-r--r--Documentation/hwmon/mp2856.rst98
-rw-r--r--Documentation/hwmon/mp2869.rst175
-rw-r--r--Documentation/hwmon/mp2888.rst113
-rw-r--r--Documentation/hwmon/mp2891.rst179
-rw-r--r--Documentation/hwmon/mp2925.rst151
-rw-r--r--Documentation/hwmon/mp29502.rst93
-rw-r--r--Documentation/hwmon/mp2975.rst128
-rw-r--r--Documentation/hwmon/mp2993.rst150
-rw-r--r--Documentation/hwmon/mp5023.rst84
-rw-r--r--Documentation/hwmon/mp5920.rst91
-rw-r--r--Documentation/hwmon/mp5990.rst106
-rw-r--r--Documentation/hwmon/mp9941.rst92
-rw-r--r--Documentation/hwmon/mp9945.rst117
-rw-r--r--Documentation/hwmon/mpq8785.rst109
-rw-r--r--Documentation/hwmon/nct668357
-rw-r--r--Documentation/hwmon/nct6683.rst71
-rw-r--r--Documentation/hwmon/nct6775200
-rw-r--r--Documentation/hwmon/nct6775.rst289
-rw-r--r--Documentation/hwmon/nct7363.rst35
-rw-r--r--Documentation/hwmon/nct780232
-rw-r--r--Documentation/hwmon/nct7802.rst38
-rw-r--r--Documentation/hwmon/nct790460
-rw-r--r--Documentation/hwmon/nct7904.rst67
-rw-r--r--Documentation/hwmon/npcm750-pwm-fan.rst26
-rw-r--r--Documentation/hwmon/nsa320.rst64
-rw-r--r--Documentation/hwmon/ntc_thermistor98
-rw-r--r--Documentation/hwmon/ntc_thermistor.rst111
-rw-r--r--Documentation/hwmon/nzxt-kraken2.rst42
-rw-r--r--Documentation/hwmon/nzxt-kraken3.rst77
-rw-r--r--Documentation/hwmon/nzxt-smart2.rst62
-rw-r--r--Documentation/hwmon/occ.rst153
-rw-r--r--Documentation/hwmon/pc87360184
-rw-r--r--Documentation/hwmon/pc87360.rst198
-rw-r--r--Documentation/hwmon/pc8742759
-rw-r--r--Documentation/hwmon/pc87427.rst63
-rw-r--r--Documentation/hwmon/pcf859190
-rw-r--r--Documentation/hwmon/pcf8591.rst98
-rw-r--r--Documentation/hwmon/peci-cputemp.rst90
-rw-r--r--Documentation/hwmon/peci-dimmtemp.rst57
-rw-r--r--Documentation/hwmon/pim4328.rst105
-rw-r--r--Documentation/hwmon/pli1209bc.rst75
-rw-r--r--Documentation/hwmon/pm6764tr.rst32
-rw-r--r--Documentation/hwmon/pmbus212
-rw-r--r--Documentation/hwmon/pmbus-core283
-rw-r--r--Documentation/hwmon/pmbus-core.rst410
-rw-r--r--Documentation/hwmon/pmbus.rst277
-rw-r--r--Documentation/hwmon/powerz.rst30
-rw-r--r--Documentation/hwmon/powr122045
-rw-r--r--Documentation/hwmon/powr1220.rst53
-rw-r--r--Documentation/hwmon/pt5161l.rst42
-rw-r--r--Documentation/hwmon/pwm-fan17
-rw-r--r--Documentation/hwmon/pwm-fan.rst32
-rw-r--r--Documentation/hwmon/pxe1610.rst107
-rw-r--r--Documentation/hwmon/q54sj108a2.rst54
-rw-r--r--Documentation/hwmon/qnap-mcu-hwmon.rst27
-rw-r--r--Documentation/hwmon/raspberrypi-hwmon.rst25
-rw-r--r--Documentation/hwmon/sa67.rst41
-rw-r--r--Documentation/hwmon/sbrmi.rst79
-rw-r--r--Documentation/hwmon/sbtsi_temp.rst42
-rw-r--r--Documentation/hwmon/sch562727
-rw-r--r--Documentation/hwmon/sch5627.rst45
-rw-r--r--Documentation/hwmon/sch563634
-rw-r--r--Documentation/hwmon/sch5636.rst37
-rw-r--r--Documentation/hwmon/scpi-hwmon.rst36
-rw-r--r--Documentation/hwmon/sfctemp.rst33
-rw-r--r--Documentation/hwmon/sg2042-mcu.rst78
-rw-r--r--Documentation/hwmon/sht1574
-rw-r--r--Documentation/hwmon/sht15.rst83
-rw-r--r--Documentation/hwmon/sht2149
-rw-r--r--Documentation/hwmon/sht21.rst72
-rw-r--r--Documentation/hwmon/sht3x.rst112
-rw-r--r--Documentation/hwmon/sht4x.rst59
-rw-r--r--Documentation/hwmon/shtc143
-rw-r--r--Documentation/hwmon/shtc1.rst67
-rw-r--r--Documentation/hwmon/sis5595106
-rw-r--r--Documentation/hwmon/sis5595.rst123
-rw-r--r--Documentation/hwmon/sl28cpld.rst36
-rw-r--r--Documentation/hwmon/smm665157
-rw-r--r--Documentation/hwmon/smpro-hwmon.rst102
-rw-r--r--Documentation/hwmon/smsc47b397163
-rw-r--r--Documentation/hwmon/smsc47b397.rst197
-rw-r--r--Documentation/hwmon/smsc47m163
-rw-r--r--Documentation/hwmon/smsc47m1.rst86
-rw-r--r--Documentation/hwmon/smsc47m192103
-rw-r--r--Documentation/hwmon/smsc47m192.rst116
-rw-r--r--Documentation/hwmon/sparx5-temp.rst33
-rw-r--r--Documentation/hwmon/spd5118.rst63
-rw-r--r--Documentation/hwmon/stpddc60.rst90
-rw-r--r--Documentation/hwmon/submitting-patches110
-rw-r--r--Documentation/hwmon/submitting-patches.rst149
-rw-r--r--Documentation/hwmon/surface_fan.rst25
-rw-r--r--Documentation/hwmon/sy7636a-hwmon.rst26
-rw-r--r--Documentation/hwmon/sysfs-interface760
-rw-r--r--Documentation/hwmon/sysfs-interface.rst656
-rw-r--r--Documentation/hwmon/tc654.rst34
-rw-r--r--Documentation/hwmon/tc74.rst23
-rw-r--r--Documentation/hwmon/thmc5074
-rw-r--r--Documentation/hwmon/thmc50.rst89
-rw-r--r--Documentation/hwmon/tmp10226
-rw-r--r--Documentation/hwmon/tmp102.rst31
-rw-r--r--Documentation/hwmon/tmp10328
-rw-r--r--Documentation/hwmon/tmp103.rst33
-rw-r--r--Documentation/hwmon/tmp108.rst49
-rw-r--r--Documentation/hwmon/tmp40157
-rw-r--r--Documentation/hwmon/tmp401.rst80
-rw-r--r--Documentation/hwmon/tmp42144
-rw-r--r--Documentation/hwmon/tmp421.rst76
-rw-r--r--Documentation/hwmon/tmp464.rst73
-rw-r--r--Documentation/hwmon/tmp513.rst103
-rw-r--r--Documentation/hwmon/tps23861.rst41
-rw-r--r--Documentation/hwmon/tps25990.rst147
-rw-r--r--Documentation/hwmon/tps4042264
-rw-r--r--Documentation/hwmon/tps40422.rst73
-rw-r--r--Documentation/hwmon/tps53679.rst195
-rw-r--r--Documentation/hwmon/tps546d24.rst35
-rw-r--r--Documentation/hwmon/tsc1641.rst87
-rw-r--r--Documentation/hwmon/twl4030-madc-hwmon45
-rw-r--r--Documentation/hwmon/twl4030-madc-hwmon.rst49
-rw-r--r--Documentation/hwmon/ucd9000110
-rw-r--r--Documentation/hwmon/ucd9000.rst137
-rw-r--r--Documentation/hwmon/ucd9200112
-rw-r--r--Documentation/hwmon/ucd9200.rst124
-rw-r--r--Documentation/hwmon/userspace-tools40
-rw-r--r--Documentation/hwmon/userspace-tools.rst43
-rw-r--r--Documentation/hwmon/vexpress34
-rw-r--r--Documentation/hwmon/vexpress.rst41
-rw-r--r--Documentation/hwmon/via686a78
-rw-r--r--Documentation/hwmon/via686a.rst84
-rw-r--r--Documentation/hwmon/vt1211206
-rw-r--r--Documentation/hwmon/vt1211.rst226
-rw-r--r--Documentation/hwmon/w83627ehf190
-rw-r--r--Documentation/hwmon/w83627ehf.rst248
-rw-r--r--Documentation/hwmon/w83627hf115
-rw-r--r--Documentation/hwmon/w83627hf.rst124
-rw-r--r--Documentation/hwmon/w83773g.rst35
-rw-r--r--Documentation/hwmon/w83781d453
-rw-r--r--Documentation/hwmon/w83781d.rst513
-rw-r--r--Documentation/hwmon/w83791d161
-rw-r--r--Documentation/hwmon/w83791d.rst180
-rw-r--r--Documentation/hwmon/w83792d173
-rw-r--r--Documentation/hwmon/w83792d.rst199
-rw-r--r--Documentation/hwmon/w83793106
-rw-r--r--Documentation/hwmon/w83793.rst113
-rw-r--r--Documentation/hwmon/w83795127
-rw-r--r--Documentation/hwmon/w83795.rst142
-rw-r--r--Documentation/hwmon/w83l785ts40
-rw-r--r--Documentation/hwmon/w83l785ts.rst45
-rw-r--r--Documentation/hwmon/w83l786ng54
-rw-r--r--Documentation/hwmon/w83l786ng.rst66
-rw-r--r--Documentation/hwmon/wm831x37
-rw-r--r--Documentation/hwmon/wm831x.rst40
-rw-r--r--Documentation/hwmon/wm835026
-rw-r--r--Documentation/hwmon/wm8350.rst30
-rw-r--r--Documentation/hwmon/xdp710.rst83
-rw-r--r--Documentation/hwmon/xdpe12284.rst106
-rw-r--r--Documentation/hwmon/xdpe152c4.rst118
-rw-r--r--Documentation/hwmon/xgene-hwmon.rst36
-rw-r--r--Documentation/hwmon/zl6100160
-rw-r--r--Documentation/hwmon/zl6100.rst259
-rw-r--r--Documentation/hwspinlock.txt307
-rw-r--r--Documentation/i2c/busses/i2c-ali153542
-rw-r--r--Documentation/i2c/busses/i2c-ali1535.rst45
-rw-r--r--Documentation/i2c/busses/i2c-ali156327
-rw-r--r--Documentation/i2c/busses/i2c-ali1563.rst30
-rw-r--r--Documentation/i2c/busses/i2c-ali15x3112
-rw-r--r--Documentation/i2c/busses/i2c-ali15x3.rst122
-rw-r--r--Documentation/i2c/busses/i2c-amd-mp2.rst25
-rw-r--r--Documentation/i2c/busses/i2c-amd75625
-rw-r--r--Documentation/i2c/busses/i2c-amd756.rst29
-rw-r--r--Documentation/i2c/busses/i2c-amd811141
-rw-r--r--Documentation/i2c/busses/i2c-amd8111.rst43
-rw-r--r--Documentation/i2c/busses/i2c-diolan-u2c26
-rw-r--r--Documentation/i2c/busses/i2c-diolan-u2c.rst29
-rw-r--r--Documentation/i2c/busses/i2c-i801164
-rw-r--r--Documentation/i2c/busses/i2c-i801.rst192
-rw-r--r--Documentation/i2c/busses/i2c-ismt36
-rw-r--r--Documentation/i2c/busses/i2c-ismt.rst44
-rw-r--r--Documentation/i2c/busses/i2c-mlxcpld.rst57
-rw-r--r--Documentation/i2c/busses/i2c-nforce250
-rw-r--r--Documentation/i2c/busses/i2c-nforce2.rst53
-rw-r--r--Documentation/i2c/busses/i2c-nvidia-gpu.rst20
-rw-r--r--Documentation/i2c/busses/i2c-ocores68
-rw-r--r--Documentation/i2c/busses/i2c-ocores.rst70
-rw-r--r--Documentation/i2c/busses/i2c-parport177
-rw-r--r--Documentation/i2c/busses/i2c-parport-light22
-rw-r--r--Documentation/i2c/busses/i2c-parport.rst190
-rw-r--r--Documentation/i2c/busses/i2c-pca-isa23
-rw-r--r--Documentation/i2c/busses/i2c-pca-isa.rst26
-rw-r--r--Documentation/i2c/busses/i2c-piix4110
-rw-r--r--Documentation/i2c/busses/i2c-piix4.rst174
-rw-r--r--Documentation/i2c/busses/i2c-sis559559
-rw-r--r--Documentation/i2c/busses/i2c-sis5595.rst68
-rw-r--r--Documentation/i2c/busses/i2c-sis63058
-rw-r--r--Documentation/i2c/busses/i2c-sis630.rst63
-rw-r--r--Documentation/i2c/busses/i2c-sis96x73
-rw-r--r--Documentation/i2c/busses/i2c-sis96x.rst82
-rw-r--r--Documentation/i2c/busses/i2c-taos-evm46
-rw-r--r--Documentation/i2c/busses/i2c-taos-evm.rst48
-rw-r--r--Documentation/i2c/busses/i2c-via34
-rw-r--r--Documentation/i2c/busses/i2c-via.rst40
-rw-r--r--Documentation/i2c/busses/i2c-viapro73
-rw-r--r--Documentation/i2c/busses/i2c-viapro.rst77
-rw-r--r--Documentation/i2c/busses/index.rst32
-rw-r--r--Documentation/i2c/busses/scx200_acb32
-rw-r--r--Documentation/i2c/busses/scx200_acb.rst37
-rw-r--r--Documentation/i2c/dev-interface214
-rw-r--r--Documentation/i2c/dev-interface.rst221
-rw-r--r--Documentation/i2c/dma-considerations.rst71
-rw-r--r--Documentation/i2c/fault-codes124
-rw-r--r--Documentation/i2c/fault-codes.rst135
-rw-r--r--Documentation/i2c/functionality148
-rw-r--r--Documentation/i2c/functionality.rst156
-rw-r--r--Documentation/i2c/gpio-fault-injection.rst136
-rw-r--r--Documentation/i2c/i2c-address-translators.rst96
-rw-r--r--Documentation/i2c/i2c-protocol88
-rw-r--r--Documentation/i2c/i2c-protocol.rst96
-rw-r--r--Documentation/i2c/i2c-stub64
-rw-r--r--Documentation/i2c/i2c-stub.rst66
-rw-r--r--Documentation/i2c/i2c-sysfs.rst387
-rw-r--r--Documentation/i2c/i2c-topology.rst412
-rw-r--r--Documentation/i2c/i2c_bus.svg1342
-rw-r--r--Documentation/i2c/index.rst75
-rw-r--r--Documentation/i2c/instantiating-devices248
-rw-r--r--Documentation/i2c/instantiating-devices.rst272
-rw-r--r--Documentation/i2c/muxes/i2c-mux-gpio83
-rw-r--r--Documentation/i2c/muxes/i2c-mux-gpio.rst85
-rw-r--r--Documentation/i2c/old-module-parameters44
-rw-r--r--Documentation/i2c/old-module-parameters.rst55
-rw-r--r--Documentation/i2c/slave-eeprom-backend14
-rw-r--r--Documentation/i2c/slave-eeprom-backend.rst26
-rw-r--r--Documentation/i2c/slave-interface179
-rw-r--r--Documentation/i2c/slave-interface.rst201
-rw-r--r--Documentation/i2c/slave-testunit-backend.rst235
-rw-r--r--Documentation/i2c/smbus-protocol273
-rw-r--r--Documentation/i2c/smbus-protocol.rst324
-rw-r--r--Documentation/i2c/summary43
-rw-r--r--Documentation/i2c/summary.rst82
-rw-r--r--Documentation/i2c/ten-bit-addresses24
-rw-r--r--Documentation/i2c/ten-bit-addresses.rst33
-rw-r--r--Documentation/i2c/upgrading-clients279
-rw-r--r--Documentation/i2c/writing-clients403
-rw-r--r--Documentation/i2c/writing-clients.rst403
-rw-r--r--Documentation/ia64/.gitignore1
-rw-r--r--Documentation/ia64/IRQ-redir.txt69
-rw-r--r--Documentation/ia64/Makefile5
-rw-r--r--Documentation/ia64/README43
-rw-r--r--Documentation/ia64/aliasing-test.c263
-rw-r--r--Documentation/ia64/aliasing.txt221
-rw-r--r--Documentation/ia64/efirtc.txt128
-rw-r--r--Documentation/ia64/err_inject.txt1068
-rw-r--r--Documentation/ia64/fsys.txt286
-rw-r--r--Documentation/ia64/mca.txt194
-rw-r--r--Documentation/ia64/serial.txt151
-rw-r--r--Documentation/ia64/xen.txt183
-rw-r--r--Documentation/ide/00-INDEX14
-rw-r--r--Documentation/ide/ChangeLog.ide-cd.1994-2004268
-rw-r--r--Documentation/ide/ChangeLog.ide-floppy.1996-200263
-rw-r--r--Documentation/ide/ChangeLog.ide-tape.1995-2002257
-rw-r--r--Documentation/ide/ide-tape.txt65
-rw-r--r--Documentation/ide/ide.txt256
-rw-r--r--Documentation/ide/warm-plug-howto.txt18
-rw-r--r--Documentation/iio/ad3552r.rst73
-rw-r--r--Documentation/iio/ad4000.rst220
-rw-r--r--Documentation/iio/ad4030.rst180
-rw-r--r--Documentation/iio/ad4695.rst269
-rw-r--r--Documentation/iio/ad7191.rst119
-rw-r--r--Documentation/iio/ad7380.rst212
-rw-r--r--Documentation/iio/ad7606.rst189
-rw-r--r--Documentation/iio/ad7625.rst91
-rw-r--r--Documentation/iio/ad7944.rst178
-rw-r--r--Documentation/iio/ade9000.rst268
-rw-r--r--Documentation/iio/adis16475.rst384
-rw-r--r--Documentation/iio/adis16480.rst446
-rw-r--r--Documentation/iio/adis16550.rst376
-rw-r--r--Documentation/iio/adxl313.rst293
-rw-r--r--Documentation/iio/adxl345.rst443
-rw-r--r--Documentation/iio/adxl380.rst233
-rw-r--r--Documentation/iio/bno055.rst51
-rw-r--r--Documentation/iio/ep93xx_adc.rst40
-rw-r--r--Documentation/iio/iio_adc.rst305
-rw-r--r--Documentation/iio/iio_configfs.rst102
-rw-r--r--Documentation/iio/iio_devbuf.rst152
-rw-r--r--Documentation/iio/iio_dmabuf_api.rst54
-rw-r--r--Documentation/iio/iio_tools.rst27
-rw-r--r--Documentation/iio/index.rst40
-rw-r--r--Documentation/iio/opt4060.rst61
-rw-r--r--Documentation/images/COPYING-logo21
-rw-r--r--Documentation/images/logo.gif (renamed from Documentation/logo.gif)bin16335 -> 16335 bytes-rw-r--r--Documentation/images/logo.svg2040
-rw-r--r--Documentation/index.rst129
-rw-r--r--Documentation/infiniband/core_locking.rst116
-rw-r--r--Documentation/infiniband/core_locking.txt114
-rw-r--r--Documentation/infiniband/index.rst24
-rw-r--r--Documentation/infiniband/ipoib.rst115
-rw-r--r--Documentation/infiniband/ipoib.txt105
-rw-r--r--Documentation/infiniband/opa_vnic.rst159
-rw-r--r--Documentation/infiniband/sysfs.rst6
-rw-r--r--Documentation/infiniband/sysfs.txt66
-rw-r--r--Documentation/infiniband/tag_matching.rst69
-rw-r--r--Documentation/infiniband/ucaps.rst71
-rw-r--r--Documentation/infiniband/user_mad.rst166
-rw-r--r--Documentation/infiniband/user_mad.txt153
-rw-r--r--Documentation/infiniband/user_verbs.rst75
-rw-r--r--Documentation/infiniband/user_verbs.txt69
-rw-r--r--Documentation/init.txt49
-rw-r--r--Documentation/initrd.txt366
-rw-r--r--Documentation/input/alps.txt319
-rw-r--r--Documentation/input/amijoy.txt184
-rw-r--r--Documentation/input/appletouch.txt85
-rw-r--r--Documentation/input/atarikbd.txt709
-rw-r--r--Documentation/input/bcm5974.txt65
-rw-r--r--Documentation/input/cd32.txt19
-rw-r--r--Documentation/input/cma3000_d0x.txt115
-rw-r--r--Documentation/input/cs461x.txt45
-rw-r--r--Documentation/input/devices/alps.rst390
-rw-r--r--Documentation/input/devices/amijoy.rst272
-rw-r--r--Documentation/input/devices/appletouch.rst94
-rw-r--r--Documentation/input/devices/atarikbd.rst820
-rw-r--r--Documentation/input/devices/bcm5974.rst70
-rw-r--r--Documentation/input/devices/cma3000_d0x.rst139
-rw-r--r--Documentation/input/devices/cs461x.rst43
-rw-r--r--Documentation/input/devices/edt-ft5x06.rst71
-rw-r--r--Documentation/input/devices/elantech.rst841
-rw-r--r--Documentation/input/devices/iforce-protocol.rst381
-rw-r--r--Documentation/input/devices/index.rst19
-rw-r--r--Documentation/input/devices/joystick-parport.rst611
-rw-r--r--Documentation/input/devices/ntrig.rst137
-rw-r--r--Documentation/input/devices/pxrc.rst56
-rw-r--r--Documentation/input/devices/rotary-encoder.rst135
-rw-r--r--Documentation/input/devices/sentelic.rst901
-rw-r--r--Documentation/input/devices/walkera0701.rst128
-rw-r--r--Documentation/input/devices/xpad.rst234
-rw-r--r--Documentation/input/devices/yealink.rst225
-rw-r--r--Documentation/input/edt-ft5x06.txt54
-rw-r--r--Documentation/input/elantech.txt817
-rw-r--r--Documentation/input/event-codes.rst478
-rw-r--r--Documentation/input/event-codes.txt348
-rw-r--r--Documentation/input/ff.rst265
-rw-r--r--Documentation/input/ff.txt221
-rw-r--r--Documentation/input/gamepad.rst210
-rw-r--r--Documentation/input/gamepad.txt159
-rw-r--r--Documentation/input/gameport-programming.rst233
-rw-r--r--Documentation/input/gameport-programming.txt187
-rw-r--r--Documentation/input/gpio-tilt.txt103
-rw-r--r--Documentation/input/iforce-protocol.txt258
-rw-r--r--Documentation/input/index.rst19
-rw-r--r--Documentation/input/input-programming.rst367
-rw-r--r--Documentation/input/input-programming.txt302
-rw-r--r--Documentation/input/input.rst281
-rw-r--r--Documentation/input/input.txt290
-rw-r--r--Documentation/input/input_kapi.rst14
-rw-r--r--Documentation/input/input_uapi.rst19
-rw-r--r--Documentation/input/interactive.fig42
-rw-r--r--Documentation/input/interactive.svg24
-rw-r--r--Documentation/input/joydev/index.rst14
-rw-r--r--Documentation/input/joydev/joystick-api.rst348
-rw-r--r--Documentation/input/joydev/joystick.rst586
-rw-r--r--Documentation/input/joystick-api.txt314
-rw-r--r--Documentation/input/joystick-parport.txt542
-rw-r--r--Documentation/input/joystick.txt586
-rw-r--r--Documentation/input/multi-touch-protocol.rst415
-rw-r--r--Documentation/input/multi-touch-protocol.txt418
-rw-r--r--Documentation/input/notifier.rst55
-rw-r--r--Documentation/input/notifier.txt52
-rw-r--r--Documentation/input/ntrig.txt126
-rw-r--r--Documentation/input/rotary-encoder.txt121
-rw-r--r--Documentation/input/sentelic.txt873
-rw-r--r--Documentation/input/shape.fig65
-rw-r--r--Documentation/input/shape.svg39
-rw-r--r--Documentation/input/uinput.rst245
-rw-r--r--Documentation/input/userio.rst85
-rw-r--r--Documentation/input/walkera0701.txt109
-rw-r--r--Documentation/input/xpad.txt226
-rw-r--r--Documentation/input/yealink.txt216
-rw-r--r--Documentation/intel_txt.txt210
-rw-r--r--Documentation/io-mapping.txt82
-rw-r--r--Documentation/io_ordering.txt47
-rw-r--r--Documentation/ioctl/00-INDEX12
-rw-r--r--Documentation/ioctl/botching-up-ioctls.txt219
-rw-r--r--Documentation/ioctl/cdrom.txt966
-rw-r--r--Documentation/ioctl/hdio.txt1071
-rw-r--r--Documentation/ioctl/ioctl-decoding.txt24
-rw-r--r--Documentation/ioctl/ioctl-number.txt331
-rw-r--r--Documentation/iostats.txt164
-rw-r--r--Documentation/irqflags-tracing.txt50
-rw-r--r--Documentation/isapnp.txt14
-rw-r--r--Documentation/isdn/00-INDEX50
-rw-r--r--Documentation/isdn/CREDITS70
-rw-r--r--Documentation/isdn/HiSax.cert96
-rw-r--r--Documentation/isdn/INTERFACE759
-rw-r--r--Documentation/isdn/INTERFACE.CAPI355
-rw-r--r--Documentation/isdn/INTERFACE.fax163
-rw-r--r--Documentation/isdn/README599
-rw-r--r--Documentation/isdn/README.FAQ26
-rw-r--r--Documentation/isdn/README.HiSax659
-rw-r--r--Documentation/isdn/README.act2000104
-rw-r--r--Documentation/isdn/README.audio138
-rw-r--r--Documentation/isdn/README.avmb1187
-rw-r--r--Documentation/isdn/README.concap259
-rw-r--r--Documentation/isdn/README.diversion127
-rw-r--r--Documentation/isdn/README.fax45
-rw-r--r--Documentation/isdn/README.gigaset421
-rw-r--r--Documentation/isdn/README.hfc-pci41
-rw-r--r--Documentation/isdn/README.hysdn195
-rw-r--r--Documentation/isdn/README.icn148
-rw-r--r--Documentation/isdn/README.mISDN6
-rw-r--r--Documentation/isdn/README.pcbit40
-rw-r--r--Documentation/isdn/README.sc281
-rw-r--r--Documentation/isdn/README.syncppp58
-rw-r--r--Documentation/isdn/README.x25184
-rw-r--r--Documentation/isdn/credits.rst73
-rw-r--r--Documentation/isdn/index.rst21
-rw-r--r--Documentation/isdn/interface_capi.rst336
-rw-r--r--Documentation/isdn/m_isdn.rst9
-rw-r--r--Documentation/isdn/syncPPP.FAQ224
-rw-r--r--Documentation/ja_JP/HOWTO644
-rw-r--r--Documentation/ja_JP/SubmitChecklist111
-rw-r--r--Documentation/ja_JP/SubmittingPatches719
-rw-r--r--Documentation/ja_JP/stable_api_nonsense.txt263
-rw-r--r--Documentation/ja_JP/stable_kernel_rules.txt84
-rw-r--r--Documentation/java.txt404
-rw-r--r--Documentation/kasan.txt170
-rw-r--r--Documentation/kbuild/00-INDEX14
-rw-r--r--Documentation/kbuild/Kconfig.recursion-issue-0157
-rw-r--r--Documentation/kbuild/Kconfig.recursion-issue-0263
-rw-r--r--Documentation/kbuild/Kconfig.select-break33
-rw-r--r--Documentation/kbuild/bash-completion.rst65
-rw-r--r--Documentation/kbuild/gcc-plugins.rst133
-rw-r--r--Documentation/kbuild/gendwarfksyms.rst395
-rw-r--r--Documentation/kbuild/headers_install.rst44
-rw-r--r--Documentation/kbuild/headers_install.txt47
-rw-r--r--Documentation/kbuild/index.rst33
-rw-r--r--Documentation/kbuild/issues.rst15
-rw-r--r--Documentation/kbuild/kbuild.rst349
-rw-r--r--Documentation/kbuild/kbuild.txt235
-rw-r--r--Documentation/kbuild/kconfig-language.rst811
-rw-r--r--Documentation/kbuild/kconfig-language.txt395
-rw-r--r--Documentation/kbuild/kconfig-macro-language.rst247
-rw-r--r--Documentation/kbuild/kconfig.rst295
-rw-r--r--Documentation/kbuild/kconfig.txt237
-rw-r--r--Documentation/kbuild/llvm.rst225
-rw-r--r--Documentation/kbuild/makefiles.rst1698
-rw-r--r--Documentation/kbuild/makefiles.txt1410
-rw-r--r--Documentation/kbuild/modules.rst512
-rw-r--r--Documentation/kbuild/modules.txt541
-rw-r--r--Documentation/kbuild/reproducible-builds.rst140
-rw-r--r--Documentation/kdump/gdbmacros.txt201
-rw-r--r--Documentation/kdump/kdump.txt487
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt362
-rw-r--r--Documentation/kernel-docs.txt724
-rw-r--r--Documentation/kernel-hacking/false-sharing.rst206
-rw-r--r--Documentation/kernel-hacking/hacking.rst830
-rw-r--r--Documentation/kernel-hacking/index.rst12
-rw-r--r--Documentation/kernel-hacking/locking.rst1454
-rw-r--r--Documentation/kernel-parameters.txt4045
-rw-r--r--Documentation/kernel-per-CPU-kthreads.txt273
-rw-r--r--Documentation/kmemcheck.txt754
-rw-r--r--Documentation/kmemleak.txt203
-rw-r--r--Documentation/ko_KR/HOWTO588
-rw-r--r--Documentation/ko_KR/stable_api_nonsense.txt195
-rw-r--r--Documentation/kobject.txt415
-rw-r--r--Documentation/kprobes.txt731
-rw-r--r--Documentation/kref.txt303
-rw-r--r--Documentation/kselftest.txt69
-rw-r--r--Documentation/laptops/.gitignore2
-rw-r--r--Documentation/laptops/00-INDEX22
-rw-r--r--Documentation/laptops/Makefile5
-rw-r--r--Documentation/laptops/asus-laptop.txt257
-rw-r--r--Documentation/laptops/disk-shock-protection.txt149
-rw-r--r--Documentation/laptops/dslm.c166
-rw-r--r--Documentation/laptops/freefall.c174
-rw-r--r--Documentation/laptops/laptop-mode.txt782
-rw-r--r--Documentation/laptops/sony-laptop.txt144
-rw-r--r--Documentation/laptops/sonypi.txt152
-rw-r--r--Documentation/laptops/thinkpad-acpi.txt1479
-rw-r--r--Documentation/laptops/toshiba_haps.txt76
-rw-r--r--Documentation/ldm.txt109
-rw-r--r--Documentation/leds/00-INDEX22
-rw-r--r--Documentation/leds/index.rst32
-rw-r--r--Documentation/leds/leds-blinkm.rst107
-rw-r--r--Documentation/leds/leds-blinkm.txt80
-rw-r--r--Documentation/leds/leds-cht-wcove.rst38
-rw-r--r--Documentation/leds/leds-class-flash.rst90
-rw-r--r--Documentation/leds/leds-class-flash.txt22
-rw-r--r--Documentation/leds/leds-class-multicolor.rst106
-rw-r--r--Documentation/leds/leds-class.rst260
-rw-r--r--Documentation/leds/leds-class.txt97
-rw-r--r--Documentation/leds/leds-el15203000.rst140
-rw-r--r--Documentation/leds/leds-lm3556.rst137
-rw-r--r--Documentation/leds/leds-lm3556.txt85
-rw-r--r--Documentation/leds/leds-lp3944.rst59
-rw-r--r--Documentation/leds/leds-lp3944.txt50
-rw-r--r--Documentation/leds/leds-lp5521.rst115
-rw-r--r--Documentation/leds/leds-lp5521.txt101
-rw-r--r--Documentation/leds/leds-lp5523.rst147
-rw-r--r--Documentation/leds/leds-lp5523.txt100
-rw-r--r--Documentation/leds/leds-lp5562.rst137
-rw-r--r--Documentation/leds/leds-lp5562.txt120
-rw-r--r--Documentation/leds/leds-lp55xx.rst224
-rw-r--r--Documentation/leds/leds-lp55xx.txt194
-rw-r--r--Documentation/leds/leds-mlxcpld.rst118
-rw-r--r--Documentation/leds/leds-mt6370-rgb.rst64
-rw-r--r--Documentation/leds/leds-qcom-lpg.rst78
-rw-r--r--Documentation/leds/leds-sc27xx.rst27
-rw-r--r--Documentation/leds/leds-st1202.rst34
-rw-r--r--Documentation/leds/ledtrig-oneshot.rst44
-rw-r--r--Documentation/leds/ledtrig-oneshot.txt59
-rw-r--r--Documentation/leds/ledtrig-transient.rst160
-rw-r--r--Documentation/leds/ledtrig-transient.txt152
-rw-r--r--Documentation/leds/ledtrig-usbport.rst46
-rw-r--r--Documentation/leds/uleds.rst37
-rw-r--r--Documentation/leds/well-known-leds.txt111
-rw-r--r--Documentation/litmus-tests/README80
-rw-r--r--Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus32
-rw-r--r--Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus25
-rw-r--r--Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus35
-rw-r--r--Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus30
-rw-r--r--Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus34
-rw-r--r--Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus30
-rw-r--r--Documentation/litmus-tests/locking/DCL-broken.litmus54
-rw-r--r--Documentation/litmus-tests/locking/DCL-fixed.litmus55
-rw-r--r--Documentation/litmus-tests/locking/RM-broken.litmus41
-rw-r--r--Documentation/litmus-tests/locking/RM-fixed.litmus41
-rw-r--r--Documentation/litmus-tests/rcu/RCU+sync+free.litmus42
-rw-r--r--Documentation/litmus-tests/rcu/RCU+sync+read.litmus37
-rw-r--r--Documentation/livepatch/api.rst30
-rw-r--r--Documentation/livepatch/callbacks.rst133
-rw-r--r--Documentation/livepatch/cumulative-patches.rst102
-rw-r--r--Documentation/livepatch/index.rst24
-rw-r--r--Documentation/livepatch/livepatch.rst448
-rw-r--r--Documentation/livepatch/module-elf-format.rst305
-rw-r--r--Documentation/livepatch/reliable-stacktrace.rst309
-rw-r--r--Documentation/livepatch/shadow-vars.rst226
-rw-r--r--Documentation/livepatch/system-state.rst167
-rw-r--r--Documentation/local_ops.txt191
-rw-r--r--Documentation/locking/00-INDEX16
-rw-r--r--Documentation/locking/futex-requeue-pi.rst132
-rw-r--r--Documentation/locking/hwspinlock.rst441
-rw-r--r--Documentation/locking/index.rst33
-rw-r--r--Documentation/locking/lglock.txt166
-rw-r--r--Documentation/locking/lockdep-design.rst663
-rw-r--r--Documentation/locking/lockdep-design.txt286
-rw-r--r--Documentation/locking/lockstat.rst204
-rw-r--r--Documentation/locking/lockstat.txt183
-rw-r--r--Documentation/locking/locktorture.rst169
-rw-r--r--Documentation/locking/locktorture.txt147
-rw-r--r--Documentation/locking/locktypes.rst555
-rw-r--r--Documentation/locking/mutex-design.rst170
-rw-r--r--Documentation/locking/mutex-design.txt157
-rw-r--r--Documentation/locking/percpu-rw-semaphore.rst28
-rw-r--r--Documentation/locking/pi-futex.rst122
-rw-r--r--Documentation/locking/preempt-locking.rst144
-rw-r--r--Documentation/locking/robust-futex-ABI.rst184
-rw-r--r--Documentation/locking/robust-futexes.rst221
-rw-r--r--Documentation/locking/rt-mutex-design.rst574
-rw-r--r--Documentation/locking/rt-mutex-design.txt781
-rw-r--r--Documentation/locking/rt-mutex.rst77
-rw-r--r--Documentation/locking/rt-mutex.txt79
-rw-r--r--Documentation/locking/seqlock.rst242
-rw-r--r--Documentation/locking/spinlocks.rst165
-rw-r--r--Documentation/locking/spinlocks.txt167
-rw-r--r--Documentation/locking/ww-mutex-design.rst393
-rw-r--r--Documentation/locking/ww-mutex-design.txt344
-rw-r--r--Documentation/lockup-watchdogs.txt63
-rw-r--r--Documentation/logo.txt13
-rw-r--r--Documentation/lzo.txt164
-rw-r--r--Documentation/m68k/00-INDEX7
-rw-r--r--Documentation/m68k/README.buddha210
-rw-r--r--Documentation/m68k/kernel-options.txt884
-rw-r--r--Documentation/magic-number.txt160
-rw-r--r--Documentation/mailbox.txt122
-rw-r--r--Documentation/maintainer/configure-git.rst30
-rw-r--r--Documentation/maintainer/feature-and-driver-maintainers.rst166
-rw-r--r--Documentation/maintainer/index.rst19
-rw-r--r--Documentation/maintainer/maintainer-entry-profile.rst115
-rw-r--r--Documentation/maintainer/messy-diffstat.rst96
-rw-r--r--Documentation/maintainer/modifying-patches.rst50
-rw-r--r--Documentation/maintainer/pull-requests.rst176
-rw-r--r--Documentation/maintainer/rebasing-and-merging.rst222
-rw-r--r--Documentation/md-cluster.txt176
-rw-r--r--Documentation/md.txt613
-rw-r--r--Documentation/media-framework.txt372
-rw-r--r--Documentation/memory-barriers.txt1658
-rw-r--r--Documentation/memory-devices/ti-emif.txt57
-rw-r--r--Documentation/memory-hotplug.txt450
-rw-r--r--Documentation/metag/00-INDEX4
-rw-r--r--Documentation/metag/kernel-ABI.txt256
-rw-r--r--Documentation/mhi/index.rst18
-rw-r--r--Documentation/mhi/mhi.rst218
-rw-r--r--Documentation/mhi/topology.rst60
-rw-r--r--Documentation/mic/Makefile1
-rw-r--r--Documentation/mic/mic_overview.txt66
-rw-r--r--Documentation/mic/mpssd/.gitignore1
-rw-r--r--Documentation/mic/mpssd/Makefile19
-rwxr-xr-xDocumentation/mic/mpssd/micctrl173
-rwxr-xr-xDocumentation/mic/mpssd/mpss202
-rw-r--r--Documentation/mic/mpssd/mpssd.c1728
-rw-r--r--Documentation/mic/mpssd/mpssd.h102
-rw-r--r--Documentation/mic/mpssd/sysfs.c102
-rw-r--r--Documentation/mips/00-INDEX4
-rw-r--r--Documentation/mips/AU1xxx_IDE.README122
-rw-r--r--Documentation/misc-devices/Makefile1
-rw-r--r--Documentation/misc-devices/ad525x_dpot.rst57
-rw-r--r--Documentation/misc-devices/ad525x_dpot.txt57
-rw-r--r--Documentation/misc-devices/amd-sbi.rst101
-rw-r--r--Documentation/misc-devices/apds990x.rst128
-rw-r--r--Documentation/misc-devices/apds990x.txt111
-rw-r--r--Documentation/misc-devices/bh1770glc.rst135
-rw-r--r--Documentation/misc-devices/bh1770glc.txt116
-rw-r--r--Documentation/misc-devices/c2port.rst94
-rw-r--r--Documentation/misc-devices/c2port.txt90
-rw-r--r--Documentation/misc-devices/dw-xdata-pcie.rst64
-rw-r--r--Documentation/misc-devices/eeprom96
-rw-r--r--Documentation/misc-devices/ibmvmc.rst227
-rw-r--r--Documentation/misc-devices/ics932s40131
-rw-r--r--Documentation/misc-devices/ics932s401.rst36
-rw-r--r--Documentation/misc-devices/index.rst31
-rw-r--r--Documentation/misc-devices/isl2900362
-rw-r--r--Documentation/misc-devices/isl29003.rst75
-rw-r--r--Documentation/misc-devices/lis3lv02d93
-rw-r--r--Documentation/misc-devices/lis3lv02d.rst99
-rw-r--r--Documentation/misc-devices/max6875110
-rw-r--r--Documentation/misc-devices/max6875.rst136
-rw-r--r--Documentation/misc-devices/mei/.gitignore1
-rw-r--r--Documentation/misc-devices/mei/Makefile5
-rw-r--r--Documentation/misc-devices/mei/TODO2
-rw-r--r--Documentation/misc-devices/mei/mei-amt-version.c479
-rw-r--r--Documentation/misc-devices/mei/mei-client-bus.txt141
-rw-r--r--Documentation/misc-devices/mei/mei.txt223
-rw-r--r--Documentation/misc-devices/mrvl_cn10k_dpi.rst52
-rw-r--r--Documentation/misc-devices/oxsemi-tornado.rst131
-rw-r--r--Documentation/misc-devices/pci-endpoint-test.rst56
-rw-r--r--Documentation/misc-devices/spear-pcie-gadget.rst170
-rw-r--r--Documentation/misc-devices/spear-pcie-gadget.txt130
-rw-r--r--Documentation/misc-devices/tps6594-pfsm.rst87
-rw-r--r--Documentation/misc-devices/uacce.rst179
-rw-r--r--Documentation/misc-devices/xilinx_sdfec.rst292
-rw-r--r--Documentation/mm/active_mm.rst95
-rw-r--r--Documentation/mm/allocation-profiling.rst104
-rw-r--r--Documentation/mm/arch_pgtable_helpers.rst250
-rw-r--r--Documentation/mm/balance.rst100
-rw-r--r--Documentation/mm/bootmem.rst5
-rw-r--r--Documentation/mm/damon/api.rst20
-rw-r--r--Documentation/mm/damon/design.rst827
-rw-r--r--Documentation/mm/damon/faq.rst27
-rw-r--r--Documentation/mm/damon/index.rst45
-rw-r--r--Documentation/mm/damon/maintainer-profile.rst103
-rw-r--r--Documentation/mm/damon/monitoring_intervals_tuning_example.rst247
-rw-r--r--Documentation/mm/free_page_reporting.rst38
-rw-r--r--Documentation/mm/highmem.rst213
-rw-r--r--Documentation/mm/hmm.rst441
-rw-r--r--Documentation/mm/hugetlbfs_reserv.rst595
-rw-r--r--Documentation/mm/hwpoison.rst182
-rw-r--r--Documentation/mm/index.rst66
-rw-r--r--Documentation/mm/ksm.rst85
-rw-r--r--Documentation/mm/memfd_preservation.rst23
-rw-r--r--Documentation/mm/memory-model.rst175
-rw-r--r--Documentation/mm/mmu_notifier.rst97
-rw-r--r--Documentation/mm/multigen_lru.rst269
-rw-r--r--Documentation/mm/numa.rst148
-rw-r--r--Documentation/mm/oom.rst5
-rw-r--r--Documentation/mm/overcommit-accounting.rst85
-rw-r--r--Documentation/mm/page_allocation.rst5
-rw-r--r--Documentation/mm/page_cache.rst15
-rw-r--r--Documentation/mm/page_frags.rst43
-rw-r--r--Documentation/mm/page_migration.rst207
-rw-r--r--Documentation/mm/page_owner.rst265
-rw-r--r--Documentation/mm/page_reclaim.rst5
-rw-r--r--Documentation/mm/page_table_check.rst80
-rw-r--r--Documentation/mm/page_tables.rst281
-rw-r--r--Documentation/mm/physical_memory.rst635
-rw-r--r--Documentation/mm/process_addrs.rst916
-rw-r--r--Documentation/mm/remap_file_pages.rst31
-rw-r--r--Documentation/mm/shmfs.rst5
-rw-r--r--Documentation/mm/slab.rst12
-rw-r--r--Documentation/mm/split_page_table_lock.rst107
-rw-r--r--Documentation/mm/swap-table.rst69
-rw-r--r--Documentation/mm/swap.rst5
-rw-r--r--Documentation/mm/transhuge.rst192
-rw-r--r--Documentation/mm/unevictable-lru.rst559
-rw-r--r--Documentation/mm/vmalloc.rst5
-rw-r--r--Documentation/mm/vmalloced-kernel-stacks.rst153
-rw-r--r--Documentation/mm/vmemmap_dedup.rst231
-rw-r--r--Documentation/mm/zsmalloc.rst269
-rw-r--r--Documentation/mmc/00-INDEX8
-rw-r--r--Documentation/mmc/mmc-async-req.txt87
-rw-r--r--Documentation/mmc/mmc-dev-attrs.txt84
-rw-r--r--Documentation/mmc/mmc-dev-parts.txt40
-rw-r--r--Documentation/mn10300/ABI.txt149
-rw-r--r--Documentation/mn10300/compartmentalisation.txt60
-rw-r--r--Documentation/module-signing.txt241
-rw-r--r--Documentation/mono.txt66
-rw-r--r--Documentation/mtd/nand/pxa3xx-nand.txt113
-rw-r--r--Documentation/mtd/nand_ecc.txt714
-rw-r--r--Documentation/mtd/spi-nor.txt62
-rw-r--r--Documentation/namespaces/compatibility-list.txt39
-rw-r--r--Documentation/namespaces/resource-control.txt14
-rw-r--r--Documentation/netlabel/00-INDEX10
-rw-r--r--Documentation/netlabel/cipso_ipv4.rst56
-rw-r--r--Documentation/netlabel/cipso_ipv4.txt48
-rw-r--r--Documentation/netlabel/draft_ietf.rst5
-rw-r--r--Documentation/netlabel/index.rst21
-rw-r--r--Documentation/netlabel/introduction.rst52
-rw-r--r--Documentation/netlabel/introduction.txt46
-rw-r--r--Documentation/netlabel/lsm_interface.rst53
-rw-r--r--Documentation/netlabel/lsm_interface.txt47
-rw-r--r--Documentation/netlink/genetlink-c.yaml406
-rw-r--r--Documentation/netlink/genetlink-legacy.yaml473
-rw-r--r--Documentation/netlink/genetlink.yaml353
-rw-r--r--Documentation/netlink/netlink-raw.yaml517
-rw-r--r--Documentation/netlink/specs/binder.yaml93
-rw-r--r--Documentation/netlink/specs/conntrack.yaml642
-rw-r--r--Documentation/netlink/specs/devlink.yaml2338
-rw-r--r--Documentation/netlink/specs/dpll.yaml681
-rw-r--r--Documentation/netlink/specs/em.yaml113
-rw-r--r--Documentation/netlink/specs/ethtool.yaml2850
-rw-r--r--Documentation/netlink/specs/fou.yaml132
-rw-r--r--Documentation/netlink/specs/handshake.yaml132
-rw-r--r--Documentation/netlink/specs/index.rst13
-rw-r--r--Documentation/netlink/specs/lockd.yaml45
-rw-r--r--Documentation/netlink/specs/mptcp_pm.yaml395
-rw-r--r--Documentation/netlink/specs/net_shaper.yaml363
-rw-r--r--Documentation/netlink/specs/netdev.yaml808
-rw-r--r--Documentation/netlink/specs/nfsd.yaml224
-rw-r--r--Documentation/netlink/specs/nftables.yaml1532
-rw-r--r--Documentation/netlink/specs/nl80211.yaml1933
-rw-r--r--Documentation/netlink/specs/nlctrl.yaml208
-rw-r--r--Documentation/netlink/specs/ovpn.yaml508
-rw-r--r--Documentation/netlink/specs/ovs_datapath.yaml160
-rw-r--r--Documentation/netlink/specs/ovs_flow.yaml1002
-rw-r--r--Documentation/netlink/specs/ovs_vport.yaml172
-rw-r--r--Documentation/netlink/specs/psp.yaml282
-rw-r--r--Documentation/netlink/specs/rt-addr.yaml195
-rw-r--r--Documentation/netlink/specs/rt-link.yaml2555
-rw-r--r--Documentation/netlink/specs/rt-neigh.yaml453
-rw-r--r--Documentation/netlink/specs/rt-route.yaml324
-rw-r--r--Documentation/netlink/specs/rt-rule.yaml275
-rw-r--r--Documentation/netlink/specs/tc.yaml4210
-rw-r--r--Documentation/netlink/specs/tcp_metrics.yaml169
-rw-r--r--Documentation/netlink/specs/team.yaml206
-rw-r--r--Documentation/netlink/specs/wireguard.yaml298
-rw-r--r--Documentation/networking/00-INDEX238
-rw-r--r--Documentation/networking/3c509.txt213
-rw-r--r--Documentation/networking/6lowpan.rst53
-rw-r--r--Documentation/networking/6pack.rst191
-rw-r--r--Documentation/networking/6pack.txt175
-rw-r--r--Documentation/networking/LICENSE.qla3xxx46
-rw-r--r--Documentation/networking/LICENSE.qlcnic288
-rw-r--r--Documentation/networking/LICENSE.qlge288
-rw-r--r--Documentation/networking/Makefile1
-rw-r--r--Documentation/networking/PLIP.txt215
-rw-r--r--Documentation/networking/README.ipw2100293
-rw-r--r--Documentation/networking/README.ipw2200472
-rw-r--r--Documentation/networking/README.sb1000207
-rw-r--r--Documentation/networking/af_xdp.rst855
-rw-r--r--Documentation/networking/alias.rst49
-rw-r--r--Documentation/networking/alias.txt40
-rw-r--r--Documentation/networking/altera_tse.txt263
-rw-r--r--Documentation/networking/arcnet-hardware.rst3232
-rw-r--r--Documentation/networking/arcnet-hardware.txt3133
-rw-r--r--Documentation/networking/arcnet.rst568
-rw-r--r--Documentation/networking/arcnet.txt556
-rw-r--r--Documentation/networking/atm.rst14
-rw-r--r--Documentation/networking/atm.txt8
-rw-r--r--Documentation/networking/ax25.rst17
-rw-r--r--Documentation/networking/ax25.txt10
-rw-r--r--Documentation/networking/bareudp.rst59
-rw-r--r--Documentation/networking/batman-adv.rst168
-rw-r--r--Documentation/networking/batman-adv.txt202
-rw-r--r--Documentation/networking/baycom.txt158
-rw-r--r--Documentation/networking/bonding.rst2917
-rw-r--r--Documentation/networking/bonding.txt2743
-rw-r--r--Documentation/networking/bridge.rst335
-rw-r--r--Documentation/networking/bridge.txt15
-rw-r--r--Documentation/networking/caif/Linux-CAIF.txt175
-rw-r--r--Documentation/networking/caif/README109
-rw-r--r--Documentation/networking/caif/caif.rst138
-rw-r--r--Documentation/networking/caif/index.rst12
-rw-r--r--Documentation/networking/caif/linux_caif.rst195
-rw-r--r--Documentation/networking/caif/spi_porting.txt208
-rw-r--r--Documentation/networking/can.rst1570
-rw-r--r--Documentation/networking/can.txt1216
-rw-r--r--Documentation/networking/can_ucan_protocol.rst332
-rw-r--r--Documentation/networking/cdc_mbim.rst355
-rw-r--r--Documentation/networking/cdc_mbim.txt339
-rw-r--r--Documentation/networking/checksum-offloads.rst143
-rw-r--r--Documentation/networking/cops.txt63
-rw-r--r--Documentation/networking/cs89x0.txt624
-rw-r--r--Documentation/networking/cxacru.txt100
-rw-r--r--Documentation/networking/cxgb.txt352
-rw-r--r--Documentation/networking/dccp.txt207
-rw-r--r--Documentation/networking/dctcp.rst52
-rw-r--r--Documentation/networking/dctcp.txt43
-rw-r--r--Documentation/networking/de4x5.txt178
-rw-r--r--Documentation/networking/decnet.txt232
-rw-r--r--Documentation/networking/device_drivers/atm/cxacru-cf.py (renamed from Documentation/networking/cxacru-cf.py)0
-rw-r--r--Documentation/networking/device_drivers/atm/cxacru.rst120
-rw-r--r--Documentation/networking/device_drivers/atm/fore200e.rst66
-rw-r--r--Documentation/networking/device_drivers/atm/index.rst20
-rw-r--r--Documentation/networking/device_drivers/atm/iphase.rst193
-rw-r--r--Documentation/networking/device_drivers/can/can327.rst331
-rw-r--r--Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst638
-rw-r--r--Documentation/networking/device_drivers/can/ctu/fsm_txt_buffer_user.svg151
-rw-r--r--Documentation/networking/device_drivers/can/freescale/flexcan.rst54
-rw-r--r--Documentation/networking/device_drivers/can/index.rst22
-rw-r--r--Documentation/networking/device_drivers/cellular/index.rst18
-rw-r--r--Documentation/networking/device_drivers/cellular/qualcomm/rmnet.rst210
-rw-r--r--Documentation/networking/device_drivers/ethernet/3com/3c509.rst249
-rw-r--r--Documentation/networking/device_drivers/ethernet/3com/vortex.rst459
-rw-r--r--Documentation/networking/device_drivers/ethernet/altera/altera_tse.rst286
-rw-r--r--Documentation/networking/device_drivers/ethernet/amazon/ena.rst471
-rw-r--r--Documentation/networking/device_drivers/ethernet/amd/pds_core.rst139
-rw-r--r--Documentation/networking/device_drivers/ethernet/amd/pds_vdpa.rst85
-rw-r--r--Documentation/networking/device_drivers/ethernet/amd/pds_vfio_pci.rst79
-rw-r--r--Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst556
-rw-r--r--Documentation/networking/device_drivers/ethernet/chelsio/cxgb.rst393
-rw-r--r--Documentation/networking/device_drivers/ethernet/cirrus/cs89x0.rst647
-rw-r--r--Documentation/networking/device_drivers/ethernet/davicom/dm9000.rst171
-rw-r--r--Documentation/networking/device_drivers/ethernet/dec/dmfe.rst71
-rw-r--r--Documentation/networking/device_drivers/ethernet/dlink/dl2k.rst314
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa.rst269
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst161
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver.rst186
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst12
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst194
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst406
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/dpaa2/switch-driver.rst217
-rw-r--r--Documentation/networking/device_drivers/ethernet/freescale/gianfar.rst51
-rw-r--r--Documentation/networking/device_drivers/ethernet/google/gve.rst175
-rw-r--r--Documentation/networking/device_drivers/ethernet/huawei/hinic.rst128
-rw-r--r--Documentation/networking/device_drivers/ethernet/huawei/hinic3.rst137
-rw-r--r--Documentation/networking/device_drivers/ethernet/index.rst73
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/e100.rst185
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/e1000.rst458
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/e1000e.rst378
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/fm10k.rst137
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/i40e.rst778
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/iavf.rst326
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/ice.rst1219
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/idpf.rst160
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/igb.rst208
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/igbvf.rst60
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst552
-rw-r--r--Documentation/networking/device_drivers/ethernet/intel/ixgbevf.rst62
-rw-r--r--Documentation/networking/device_drivers/ethernet/marvell/octeon_ep.rst41
-rw-r--r--Documentation/networking/device_drivers/ethernet/marvell/octeon_ep_vf.rst24
-rw-r--r--Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst433
-rw-r--r--Documentation/networking/device_drivers/ethernet/mellanox/mlx5/counters.rst1380
-rw-r--r--Documentation/networking/device_drivers/ethernet/mellanox/mlx5/index.rst25
-rw-r--r--Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst171
-rw-r--r--Documentation/networking/device_drivers/ethernet/mellanox/mlx5/switchdev.rst281
-rw-r--r--Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst229
-rw-r--r--Documentation/networking/device_drivers/ethernet/meta/fbnic.rst192
-rw-r--r--Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst120
-rw-r--r--Documentation/networking/device_drivers/ethernet/mucse/rnpgbe.rst17
-rw-r--r--Documentation/networking/device_drivers/ethernet/neterion/s2io.rst196
-rw-r--r--Documentation/networking/device_drivers/ethernet/netronome/nfp.rst374
-rw-r--r--Documentation/networking/device_drivers/ethernet/pensando/ionic.rst306
-rw-r--r--Documentation/networking/device_drivers/ethernet/pensando/ionic_rdma.rst52
-rw-r--r--Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst194
-rw-r--r--Documentation/networking/device_drivers/ethernet/smsc/smc9.rst48
-rw-r--r--Documentation/networking/device_drivers/ethernet/stmicro/stmmac.rst700
-rw-r--r--Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst143
-rw-r--r--Documentation/networking/device_drivers/ethernet/ti/cpsw.rst587
-rw-r--r--Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst242
-rw-r--r--Documentation/networking/device_drivers/ethernet/ti/icssg_prueth.rst56
-rw-r--r--Documentation/networking/device_drivers/ethernet/ti/tlan.rst140
-rw-r--r--Documentation/networking/device_drivers/ethernet/wangxun/ngbe.rst14
-rw-r--r--Documentation/networking/device_drivers/ethernet/wangxun/ngbevf.rst16
-rw-r--r--Documentation/networking/device_drivers/ethernet/wangxun/txgbe.rst20
-rw-r--r--Documentation/networking/device_drivers/ethernet/wangxun/txgbevf.rst16
-rw-r--r--Documentation/networking/device_drivers/fddi/defza.rst63
-rw-r--r--Documentation/networking/device_drivers/fddi/index.rst19
-rw-r--r--Documentation/networking/device_drivers/fddi/skfp.rst253
-rw-r--r--Documentation/networking/device_drivers/hamradio/baycom.rst174
-rw-r--r--Documentation/networking/device_drivers/hamradio/index.rst19
-rw-r--r--Documentation/networking/device_drivers/hamradio/z8530drv.rst686
-rw-r--r--Documentation/networking/device_drivers/index.rst25
-rw-r--r--Documentation/networking/device_drivers/wifi/index.rst19
-rw-r--r--Documentation/networking/device_drivers/wifi/intel/ipw2100.rst323
-rw-r--r--Documentation/networking/device_drivers/wifi/intel/ipw2200.rst526
-rw-r--r--Documentation/networking/device_drivers/wwan/index.rst19
-rw-r--r--Documentation/networking/device_drivers/wwan/iosm.rst96
-rw-r--r--Documentation/networking/device_drivers/wwan/t7xx.rst214
-rw-r--r--Documentation/networking/devlink/am65-nuss-cpsw-switch.rst26
-rw-r--r--Documentation/networking/devlink/bnxt.rst84
-rw-r--r--Documentation/networking/devlink/devlink-dpipe.rst252
-rw-r--r--Documentation/networking/devlink/devlink-eswitch-attr.rst89
-rw-r--r--Documentation/networking/devlink/devlink-flash.rst121
-rw-r--r--Documentation/networking/devlink/devlink-health.rst138
-rw-r--r--Documentation/networking/devlink/devlink-info.rst224
-rw-r--r--Documentation/networking/devlink/devlink-linecard.rst122
-rw-r--r--Documentation/networking/devlink/devlink-params.rst167
-rw-r--r--Documentation/networking/devlink/devlink-port.rst484
-rw-r--r--Documentation/networking/devlink/devlink-region.rst83
-rw-r--r--Documentation/networking/devlink/devlink-reload.rst90
-rw-r--r--Documentation/networking/devlink/devlink-resource.rst76
-rw-r--r--Documentation/networking/devlink/devlink-selftests.rst38
-rw-r--r--Documentation/networking/devlink/devlink-trap.rst640
-rw-r--r--Documentation/networking/devlink/etas_es58x.rst36
-rw-r--r--Documentation/networking/devlink/hns3.rst30
-rw-r--r--Documentation/networking/devlink/i40e.rst93
-rw-r--r--Documentation/networking/devlink/ice.rst487
-rw-r--r--Documentation/networking/devlink/index.rst104
-rw-r--r--Documentation/networking/devlink/ionic.rst29
-rw-r--r--Documentation/networking/devlink/iosm.rst162
-rw-r--r--Documentation/networking/devlink/ixgbe.rst171
-rw-r--r--Documentation/networking/devlink/kvaser_pciefd.rst24
-rw-r--r--Documentation/networking/devlink/kvaser_usb.rst33
-rw-r--r--Documentation/networking/devlink/mlx4.rst56
-rw-r--r--Documentation/networking/devlink/mlx5.rst421
-rw-r--r--Documentation/networking/devlink/mlxsw.rst105
-rw-r--r--Documentation/networking/devlink/mv88e6xxx.rst28
-rw-r--r--Documentation/networking/devlink/netdevsim.rst99
-rw-r--r--Documentation/networking/devlink/nfp.rst68
-rw-r--r--Documentation/networking/devlink/octeontx2.rst79
-rw-r--r--Documentation/networking/devlink/prestera.rst141
-rw-r--r--Documentation/networking/devlink/qed.rst26
-rw-r--r--Documentation/networking/devlink/sfc.rst71
-rw-r--r--Documentation/networking/devlink/stmmac.rst40
-rw-r--r--Documentation/networking/devlink/ti-cpsw-switch.rst31
-rw-r--r--Documentation/networking/devlink/zl3073x.rst65
-rw-r--r--Documentation/networking/devmem.rst419
-rw-r--r--Documentation/networking/diagnostic/index.rst17
-rw-r--r--Documentation/networking/diagnostic/twisted_pair_layer1_diagnostics.rst784
-rw-r--r--Documentation/networking/dl2k.txt282
-rw-r--r--Documentation/networking/dm9000.txt167
-rw-r--r--Documentation/networking/dmfe.txt66
-rw-r--r--Documentation/networking/dns_resolver.rst153
-rw-r--r--Documentation/networking/dns_resolver.txt157
-rw-r--r--Documentation/networking/driver.rst127
-rw-r--r--Documentation/networking/driver.txt93
-rw-r--r--Documentation/networking/dsa/b53.rst183
-rw-r--r--Documentation/networking/dsa/bcm_sf2.rst115
-rw-r--r--Documentation/networking/dsa/configuration.rst458
-rw-r--r--Documentation/networking/dsa/dsa.rst1140
-rw-r--r--Documentation/networking/dsa/index.rst13
-rw-r--r--Documentation/networking/dsa/lan9303.rst37
-rw-r--r--Documentation/networking/dsa/sja1105.rst445
-rw-r--r--Documentation/networking/e100.txt197
-rw-r--r--Documentation/networking/e1000.txt461
-rw-r--r--Documentation/networking/e1000e.txt312
-rw-r--r--Documentation/networking/eql.rst373
-rw-r--r--Documentation/networking/eql.txt528
-rw-r--r--Documentation/networking/ethtool-netlink.rst2635
-rw-r--r--Documentation/networking/failover.rst18
-rw-r--r--Documentation/networking/fib_trie.rst149
-rw-r--r--Documentation/networking/fib_trie.txt145
-rw-r--r--Documentation/networking/filter.rst685
-rw-r--r--Documentation/networking/filter.txt1297
-rw-r--r--Documentation/networking/fore200e.txt64
-rw-r--r--Documentation/networking/framerelay.txt39
-rw-r--r--Documentation/networking/gen_stats.rst129
-rw-r--r--Documentation/networking/gen_stats.txt117
-rw-r--r--Documentation/networking/generic-hdlc.rst170
-rw-r--r--Documentation/networking/generic-hdlc.txt132
-rw-r--r--Documentation/networking/generic_netlink.rst9
-rw-r--r--Documentation/networking/generic_netlink.txt3
-rw-r--r--Documentation/networking/gianfar.txt42
-rw-r--r--Documentation/networking/gtp.rst251
-rw-r--r--Documentation/networking/i40e.txt118
-rw-r--r--Documentation/networking/i40evf.txt47
-rw-r--r--Documentation/networking/ieee802154.rst184
-rw-r--r--Documentation/networking/ieee802154.txt151
-rw-r--r--Documentation/networking/igb.txt129
-rw-r--r--Documentation/networking/igbvf.txt80
-rw-r--r--Documentation/networking/ila.rst296
-rw-r--r--Documentation/networking/index.rst143
-rw-r--r--Documentation/networking/ioam6-sysctl.rst26
-rw-r--r--Documentation/networking/iou-zcrx.rst202
-rw-r--r--Documentation/networking/ip-sysctl.rst3784
-rw-r--r--Documentation/networking/ip-sysctl.txt1858
-rw-r--r--Documentation/networking/ip_dynaddr.rst40
-rw-r--r--Documentation/networking/ip_dynaddr.txt29
-rw-r--r--Documentation/networking/ipddp.txt73
-rw-r--r--Documentation/networking/iphase.txt158
-rw-r--r--Documentation/networking/ipsec.rst46
-rw-r--r--Documentation/networking/ipsec.txt38
-rw-r--r--Documentation/networking/ipv6.rst78
-rw-r--r--Documentation/networking/ipv6.txt72
-rw-r--r--Documentation/networking/ipvlan.rst189
-rw-r--r--Documentation/networking/ipvlan.txt107
-rw-r--r--Documentation/networking/ipvs-sysctl.rst332
-rw-r--r--Documentation/networking/ipvs-sysctl.txt232
-rw-r--r--Documentation/networking/irda.txt10
-rw-r--r--Documentation/networking/iso15765-2.rst386
-rw-r--r--Documentation/networking/ixgb.txt433
-rw-r--r--Documentation/networking/ixgbe.txt349
-rw-r--r--Documentation/networking/ixgbevf.txt52
-rw-r--r--Documentation/networking/j1939.rst1135
-rw-r--r--Documentation/networking/kapi.rst162
-rw-r--r--Documentation/networking/kcm.rst290
-rw-r--r--Documentation/networking/l2tp.rst786
-rw-r--r--Documentation/networking/l2tp.txt348
-rw-r--r--Documentation/networking/lapb-module.rst305
-rw-r--r--Documentation/networking/lapb-module.txt263
-rw-r--r--Documentation/networking/ltpc.txt131
-rw-r--r--Documentation/networking/mac80211-injection.rst106
-rw-r--r--Documentation/networking/mac80211-injection.txt67
-rw-r--r--Documentation/networking/mac80211_hwsim/README68
-rw-r--r--Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst80
-rw-r--r--Documentation/networking/mctp.rst320
-rw-r--r--Documentation/networking/mpls-sysctl.rst57
-rw-r--r--Documentation/networking/mpls-sysctl.txt29
-rw-r--r--Documentation/networking/mptcp-sysctl.rst153
-rw-r--r--Documentation/networking/mptcp.rst156
-rw-r--r--Documentation/networking/msg_zerocopy.rst265
-rw-r--r--Documentation/networking/multi-pf-netdev.rst174
-rw-r--r--Documentation/networking/multiqueue.rst78
-rw-r--r--Documentation/networking/multiqueue.txt79
-rw-r--r--Documentation/networking/napi.rst505
-rw-r--r--Documentation/networking/net_cachelines/index.rst16
-rw-r--r--Documentation/networking/net_cachelines/inet_connection_sock.rst51
-rw-r--r--Documentation/networking/net_cachelines/inet_sock.rst47
-rw-r--r--Documentation/networking/net_cachelines/net_device.rst193
-rw-r--r--Documentation/networking/net_cachelines/netns_ipv4_sysctl.rst163
-rw-r--r--Documentation/networking/net_cachelines/snmp.rst141
-rw-r--r--Documentation/networking/net_cachelines/tcp_sock.rst170
-rw-r--r--Documentation/networking/net_dim.rst218
-rw-r--r--Documentation/networking/net_failover.rst182
-rw-r--r--Documentation/networking/netconsole.rst462
-rw-r--r--Documentation/networking/netconsole.txt177
-rw-r--r--Documentation/networking/netdev-FAQ.txt224
-rw-r--r--Documentation/networking/netdev-features.rst195
-rw-r--r--Documentation/networking/netdev-features.txt167
-rw-r--r--Documentation/networking/netdevices.rst418
-rw-r--r--Documentation/networking/netdevices.txt107
-rw-r--r--Documentation/networking/netfilter-sysctl.rst17
-rw-r--r--Documentation/networking/netif-msg.rst95
-rw-r--r--Documentation/networking/netif-msg.txt79
-rw-r--r--Documentation/networking/netlink_mmap.txt332
-rw-r--r--Documentation/networking/netmem.rst98
-rw-r--r--Documentation/networking/nexthop-group-resilient.rst293
-rw-r--r--Documentation/networking/nf_conntrack-sysctl.rst231
-rw-r--r--Documentation/networking/nf_conntrack-sysctl.txt177
-rw-r--r--Documentation/networking/nf_flowtable.rst235
-rw-r--r--Documentation/networking/nfc.rst132
-rw-r--r--Documentation/networking/nfc.txt128
-rw-r--r--Documentation/networking/oa-tc6-framework.rst497
-rw-r--r--Documentation/networking/openvswitch.rst251
-rw-r--r--Documentation/networking/openvswitch.txt248
-rw-r--r--Documentation/networking/operstates.rst187
-rw-r--r--Documentation/networking/operstates.txt162
-rw-r--r--Documentation/networking/packet_mmap.rst1084
-rw-r--r--Documentation/networking/packet_mmap.txt1068
-rw-r--r--Documentation/networking/page_pool.rst199
-rw-r--r--Documentation/networking/phonet.rst230
-rw-r--r--Documentation/networking/phonet.txt214
-rw-r--r--Documentation/networking/phy-link-topology.rst121
-rw-r--r--Documentation/networking/phy.rst564
-rw-r--r--Documentation/networking/phy.txt339
-rw-r--r--Documentation/networking/pktgen.rst422
-rw-r--r--Documentation/networking/pktgen.txt323
-rw-r--r--Documentation/networking/plip.rst222
-rw-r--r--Documentation/networking/policy-routing.txt150
-rw-r--r--Documentation/networking/ppp_generic.rst456
-rw-r--r--Documentation/networking/ppp_generic.txt432
-rw-r--r--Documentation/networking/proc_net_tcp.rst57
-rw-r--r--Documentation/networking/proc_net_tcp.txt48
-rw-r--r--Documentation/networking/pse-pd/index.rst10
-rw-r--r--Documentation/networking/pse-pd/introduction.rst73
-rw-r--r--Documentation/networking/pse-pd/pse-pi.rst301
-rw-r--r--Documentation/networking/psp.rst183
-rw-r--r--Documentation/networking/radiotap-headers.rst159
-rw-r--r--Documentation/networking/radiotap-headers.txt152
-rw-r--r--Documentation/networking/ray_cs.txt150
-rw-r--r--Documentation/networking/rds.rst448
-rw-r--r--Documentation/networking/rds.txt355
-rw-r--r--Documentation/networking/regulatory.rst209
-rw-r--r--Documentation/networking/regulatory.txt214
-rw-r--r--Documentation/networking/representors.rst262
-rw-r--r--Documentation/networking/rxrpc.rst1162
-rw-r--r--Documentation/networking/rxrpc.txt947
-rw-r--r--Documentation/networking/s2io.txt141
-rw-r--r--Documentation/networking/scaling.rst589
-rw-r--r--Documentation/networking/scaling.txt445
-rw-r--r--Documentation/networking/sctp.rst42
-rw-r--r--Documentation/networking/sctp.txt35
-rw-r--r--Documentation/networking/secid.rst20
-rw-r--r--Documentation/networking/secid.txt14
-rw-r--r--Documentation/networking/seg6-sysctl.rst42
-rw-r--r--Documentation/networking/segmentation-offloads.rst190
-rw-r--r--Documentation/networking/sfp-phylink.rst405
-rw-r--r--Documentation/networking/skbuff.rst37
-rw-r--r--Documentation/networking/skfp.txt220
-rw-r--r--Documentation/networking/smc-sysctl.rst113
-rw-r--r--Documentation/networking/smc9.txt42
-rw-r--r--Documentation/networking/snmp_counter.rst1789
-rw-r--r--Documentation/networking/spider_net.txt204
-rw-r--r--Documentation/networking/sriov.rst25
-rw-r--r--Documentation/networking/statistics.rst238
-rw-r--r--Documentation/networking/stmmac.txt369
-rw-r--r--Documentation/networking/strparser.rst247
-rw-r--r--Documentation/networking/switchdev.rst564
-rw-r--r--Documentation/networking/switchdev.txt59
-rw-r--r--Documentation/networking/sysfs-tagging.rst48
-rw-r--r--Documentation/networking/tc-actions-env-rules.rst29
-rw-r--r--Documentation/networking/tc-actions-env-rules.txt30
-rw-r--r--Documentation/networking/tc-queue-filters.rst37
-rw-r--r--Documentation/networking/tcp-thin.rst52
-rw-r--r--Documentation/networking/tcp-thin.txt47
-rw-r--r--Documentation/networking/tcp.txt106
-rw-r--r--Documentation/networking/tcp_ao.rst453
-rw-r--r--Documentation/networking/team.rst8
-rw-r--r--Documentation/networking/team.txt2
-rw-r--r--Documentation/networking/timestamping.rst851
-rw-r--r--Documentation/networking/timestamping.txt457
-rw-r--r--Documentation/networking/timestamping/.gitignore3
-rw-r--r--Documentation/networking/timestamping/Makefile14
-rw-r--r--Documentation/networking/timestamping/hwtstamp_config.c134
-rw-r--r--Documentation/networking/timestamping/timestamping.c528
-rw-r--r--Documentation/networking/timestamping/txtimestamp.c549
-rw-r--r--Documentation/networking/tipc.rst215
-rw-r--r--Documentation/networking/tlan.txt117
-rw-r--r--Documentation/networking/tls-handshake.rst222
-rw-r--r--Documentation/networking/tls-offload-layers.svg1
-rw-r--r--Documentation/networking/tls-offload-reorder-bad.svg1
-rw-r--r--Documentation/networking/tls-offload-reorder-good.svg1
-rw-r--r--Documentation/networking/tls-offload.rst540
-rw-r--r--Documentation/networking/tls.rst346
-rw-r--r--Documentation/networking/tproxy.rst109
-rw-r--r--Documentation/networking/tproxy.txt84
-rw-r--r--Documentation/networking/tuntap.rst259
-rw-r--r--Documentation/networking/tuntap.txt227
-rw-r--r--Documentation/networking/udplite.rst291
-rw-r--r--Documentation/networking/udplite.txt278
-rw-r--r--Documentation/networking/vortex.txt448
-rw-r--r--Documentation/networking/vrf.rst464
-rw-r--r--Documentation/networking/vxge.txt93
-rw-r--r--Documentation/networking/vxlan.rst88
-rw-r--r--Documentation/networking/vxlan.txt47
-rw-r--r--Documentation/networking/x25-iface.rst81
-rw-r--r--Documentation/networking/x25-iface.txt123
-rw-r--r--Documentation/networking/x25.rst46
-rw-r--r--Documentation/networking/x25.txt44
-rw-r--r--Documentation/networking/xdp-rx-metadata.rst161
-rw-r--r--Documentation/networking/xfrm/index.rst13
-rw-r--r--Documentation/networking/xfrm/xfrm_device.rst206
-rw-r--r--Documentation/networking/xfrm/xfrm_proc.rst119
-rw-r--r--Documentation/networking/xfrm/xfrm_sync.rst192
-rw-r--r--Documentation/networking/xfrm/xfrm_sysctl.rst11
-rw-r--r--Documentation/networking/xfrm_proc.txt74
-rw-r--r--Documentation/networking/xfrm_sync.txt169
-rw-r--r--Documentation/networking/xfrm_sysctl.txt4
-rw-r--r--Documentation/networking/xsk-tx-metadata.rst147
-rw-r--r--Documentation/networking/z8530drv.txt657
-rw-r--r--Documentation/nfc/nfc-hci.txt290
-rw-r--r--Documentation/nfc/nfc-pn544.txt32
-rw-r--r--Documentation/nios2/README23
-rw-r--r--Documentation/nommu-mmap.txt291
-rw-r--r--Documentation/numastat.txt27
-rw-r--r--Documentation/nvdimm/maintainer-entry-profile.rst60
-rw-r--r--Documentation/nvme/feature-and-quirk-policy.rst77
-rw-r--r--Documentation/nvme/index.rst12
-rw-r--r--Documentation/nvme/nvme-pci-endpoint-target.rst368
-rw-r--r--Documentation/oops-tracing.txt279
-rw-r--r--Documentation/padata.txt160
-rw-r--r--Documentation/parisc/00-INDEX6
-rw-r--r--Documentation/parisc/debugging39
-rw-r--r--Documentation/parisc/registers129
-rw-r--r--Documentation/parport-lowlevel.txt1471
-rw-r--r--Documentation/parport.txt267
-rw-r--r--Documentation/pcmcia/.gitignore1
-rw-r--r--Documentation/pcmcia/Makefile7
-rw-r--r--Documentation/pcmcia/crc32hash.c32
-rw-r--r--Documentation/pcmcia/devicetable.rst37
-rw-r--r--Documentation/pcmcia/devicetable.txt33
-rw-r--r--Documentation/pcmcia/driver-changes.rst160
-rw-r--r--Documentation/pcmcia/driver-changes.txt152
-rw-r--r--Documentation/pcmcia/driver.rst30
-rw-r--r--Documentation/pcmcia/driver.txt30
-rw-r--r--Documentation/pcmcia/index.rst20
-rw-r--r--Documentation/pcmcia/locking.rst133
-rw-r--r--Documentation/pcmcia/locking.txt118
-rw-r--r--Documentation/peci/index.rst16
-rw-r--r--Documentation/peci/peci.rst51
-rw-r--r--Documentation/percpu-rw-semaphore.txt27
-rw-r--r--Documentation/phy.txt152
-rw-r--r--Documentation/phy/samsung-usb2.txt135
-rw-r--r--Documentation/pi-futex.txt121
-rw-r--r--Documentation/pinctrl.txt1419
-rw-r--r--Documentation/platform/x86-laptop-drivers.txt18
-rw-r--r--Documentation/pnp.txt251
-rw-r--r--Documentation/power/00-INDEX46
-rw-r--r--Documentation/power/apm-acpi.rst36
-rw-r--r--Documentation/power/apm-acpi.txt32
-rw-r--r--Documentation/power/basic-pm-debugging.rst269
-rw-r--r--Documentation/power/basic-pm-debugging.txt229
-rw-r--r--Documentation/power/charger-manager.rst205
-rw-r--r--Documentation/power/charger-manager.txt200
-rw-r--r--Documentation/power/devices.txt697
-rw-r--r--Documentation/power/drivers-testing.rst52
-rw-r--r--Documentation/power/drivers-testing.txt46
-rw-r--r--Documentation/power/energy-model.rst419
-rw-r--r--Documentation/power/freezing-of-tasks.rst256
-rw-r--r--Documentation/power/freezing-of-tasks.txt230
-rw-r--r--Documentation/power/index.rst47
-rw-r--r--Documentation/power/interface.txt75
-rw-r--r--Documentation/power/notifiers.txt55
-rw-r--r--Documentation/power/opp.rst381
-rw-r--r--Documentation/power/opp.txt362
-rw-r--r--Documentation/power/pci.rst1132
-rw-r--r--Documentation/power/pci.txt1025
-rw-r--r--Documentation/power/pm_qos_interface.rst212
-rw-r--r--Documentation/power/pm_qos_interface.txt224
-rw-r--r--Documentation/power/power_supply_class.rst288
-rw-r--r--Documentation/power/power_supply_class.txt214
-rw-r--r--Documentation/power/powercap/dtpm.rst212
-rw-r--r--Documentation/power/powercap/powercap.rst262
-rw-r--r--Documentation/power/powercap/powercap.txt236
-rw-r--r--Documentation/power/regulator/consumer.rst257
-rw-r--r--Documentation/power/regulator/consumer.txt218
-rw-r--r--Documentation/power/regulator/design.rst38
-rw-r--r--Documentation/power/regulator/design.txt33
-rw-r--r--Documentation/power/regulator/machine.rst97
-rw-r--r--Documentation/power/regulator/machine.txt100
-rw-r--r--Documentation/power/regulator/overview.rst178
-rw-r--r--Documentation/power/regulator/overview.txt171
-rw-r--r--Documentation/power/regulator/regulator.rst32
-rw-r--r--Documentation/power/regulator/regulator.txt30
-rw-r--r--Documentation/power/runtime_pm.rst960
-rw-r--r--Documentation/power/runtime_pm.txt912
-rw-r--r--Documentation/power/s2ram.rst87
-rw-r--r--Documentation/power/s2ram.txt85
-rw-r--r--Documentation/power/shutdown-debugging.rst53
-rw-r--r--Documentation/power/states.txt109
-rw-r--r--Documentation/power/suspend-and-cpuhotplug.rst287
-rw-r--r--Documentation/power/suspend-and-cpuhotplug.txt275
-rw-r--r--Documentation/power/suspend-and-interrupts.rst137
-rw-r--r--Documentation/power/suspend-and-interrupts.txt135
-rw-r--r--Documentation/power/swsusp-and-swap-files.rst63
-rw-r--r--Documentation/power/swsusp-and-swap-files.txt60
-rw-r--r--Documentation/power/swsusp-dmcrypt.rst140
-rw-r--r--Documentation/power/swsusp-dmcrypt.txt138
-rw-r--r--Documentation/power/swsusp.rst503
-rw-r--r--Documentation/power/swsusp.txt429
-rw-r--r--Documentation/power/tricks.rst29
-rw-r--r--Documentation/power/tricks.txt27
-rw-r--r--Documentation/power/userland-swsusp.rst193
-rw-r--r--Documentation/power/userland-swsusp.txt170
-rw-r--r--Documentation/power/video.rst213
-rw-r--r--Documentation/power/video.txt185
-rw-r--r--Documentation/powerpc/00-INDEX32
-rw-r--r--Documentation/powerpc/bootwrapper.txt141
-rw-r--r--Documentation/powerpc/cpu_families.txt221
-rw-r--r--Documentation/powerpc/cpu_features.txt56
-rw-r--r--Documentation/powerpc/cxl.txt379
-rw-r--r--Documentation/powerpc/eeh-pci-error-recovery.txt334
-rw-r--r--Documentation/powerpc/firmware-assisted-dump.txt270
-rw-r--r--Documentation/powerpc/hvcs.txt567
-rw-r--r--Documentation/powerpc/mpc52xx.txt39
-rw-r--r--Documentation/powerpc/pci_iov_resource_on_powernv.txt301
-rw-r--r--Documentation/powerpc/pmu-ebb.txt137
-rw-r--r--Documentation/powerpc/ptrace.txt151
-rw-r--r--Documentation/powerpc/qe_firmware.txt295
-rw-r--r--Documentation/powerpc/transactional_memory.txt198
-rw-r--r--Documentation/pps/pps.txt233
-rw-r--r--Documentation/prctl/.gitignore3
-rw-r--r--Documentation/prctl/Makefile8
-rw-r--r--Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c97
-rw-r--r--Documentation/prctl/disable-tsc-on-off-stress-test.c96
-rw-r--r--Documentation/prctl/disable-tsc-test.c95
-rw-r--r--Documentation/prctl/no_new_privs.txt57
-rw-r--r--Documentation/prctl/seccomp_filter.txt225
-rw-r--r--Documentation/preempt-locking.txt135
-rw-r--r--Documentation/printk-formats.txt291
-rw-r--r--Documentation/process/1.Intro.rst268
-rw-r--r--Documentation/process/2.Process.rst494
-rw-r--r--Documentation/process/3.Early-stage.rst223
-rw-r--r--Documentation/process/4.Coding.rst425
-rw-r--r--Documentation/process/5.Posting.rst363
-rw-r--r--Documentation/process/6.Followthrough.rst219
-rw-r--r--Documentation/process/7.AdvancedTopics.rst196
-rw-r--r--Documentation/process/8.Conclusion.rst73
-rw-r--r--Documentation/process/adding-syscalls.rst661
-rw-r--r--Documentation/process/applying-patches.rst444
-rw-r--r--Documentation/process/backporting.rst604
-rw-r--r--Documentation/process/botching-up-ioctls.rst225
-rw-r--r--Documentation/process/changes.rst568
-rw-r--r--Documentation/process/code-of-conduct-interpretation.rst250
-rw-r--r--Documentation/process/code-of-conduct.rst86
-rw-r--r--Documentation/process/coding-style.rst1290
-rw-r--r--Documentation/process/contribution-maturity-model.rst109
-rw-r--r--Documentation/process/cve.rst121
-rw-r--r--Documentation/process/debugging/driver_development_debugging_guide.rst235
-rw-r--r--Documentation/process/debugging/gdb-kernel-debugging.rst175
-rw-r--r--Documentation/process/debugging/index.rst80
-rw-r--r--Documentation/process/debugging/kgdb.rst937
-rw-r--r--Documentation/process/debugging/media_specific_debugging_guide.rst180
-rw-r--r--Documentation/process/debugging/userspace_debugging_guide.rst280
-rw-r--r--Documentation/process/deprecated.rst374
-rw-r--r--Documentation/process/development-process.rst27
-rw-r--r--Documentation/process/email-clients.rst361
-rw-r--r--Documentation/process/embargoed-hardware-issues.rst358
-rw-r--r--Documentation/process/handling-regressions.rst796
-rw-r--r--Documentation/process/howto.rst625
-rw-r--r--Documentation/process/index.rst117
-rw-r--r--Documentation/process/kernel-docs.rst381
-rw-r--r--Documentation/process/kernel-driver-statement.rst202
-rw-r--r--Documentation/process/kernel-enforcement-statement.rst163
-rw-r--r--Documentation/process/license-rules.rst487
-rw-r--r--Documentation/process/maintainer-handbooks.rst22
-rw-r--r--Documentation/process/maintainer-kvm-x86.rst390
-rw-r--r--Documentation/process/maintainer-netdev.rst552
-rw-r--r--Documentation/process/maintainer-pgp-guide.rst911
-rw-r--r--Documentation/process/maintainer-soc-clean-dts.rst26
-rw-r--r--Documentation/process/maintainer-soc.rst209
-rw-r--r--Documentation/process/maintainer-tip.rst848
-rw-r--r--Documentation/process/maintainers.rst1
-rw-r--r--Documentation/process/management-style.rst290
-rw-r--r--Documentation/process/programming-language.rst58
-rw-r--r--Documentation/process/researcher-guidelines.rst170
-rw-r--r--Documentation/process/security-bugs.rst116
-rw-r--r--Documentation/process/stable-api-nonsense.rst204
-rw-r--r--Documentation/process/stable-kernel-rules.rst234
-rw-r--r--Documentation/process/submit-checklist.rst137
-rw-r--r--Documentation/process/submitting-patches.rst935
-rw-r--r--Documentation/process/volatile-considered-harmful.rst125
-rw-r--r--Documentation/pti/pti_intel_mid.txt99
-rw-r--r--Documentation/ptp/.gitignore1
-rw-r--r--Documentation/ptp/Makefile8
-rw-r--r--Documentation/ptp/ptp.txt89
-rw-r--r--Documentation/ptp/testptp.c519
-rw-r--r--Documentation/ptp/testptp.mk33
-rw-r--r--Documentation/pwm.txt122
-rw-r--r--Documentation/ramoops.txt128
-rw-r--r--Documentation/rapidio/rapidio.txt351
-rw-r--r--Documentation/rapidio/sysfs.txt158
-rw-r--r--Documentation/rapidio/tsi721.txt62
-rw-r--r--Documentation/rbtree.txt392
-rw-r--r--Documentation/remoteproc.txt299
-rw-r--r--Documentation/rfkill.txt123
-rw-r--r--Documentation/robust-futex-ABI.txt182
-rw-r--r--Documentation/robust-futexes.txt218
-rw-r--r--Documentation/rpmsg.txt293
-rw-r--r--Documentation/rtc.txt207
-rw-r--r--Documentation/rust/arch-support.rst25
-rw-r--r--Documentation/rust/coding-guidelines.rst487
-rw-r--r--Documentation/rust/general-information.rst161
-rw-r--r--Documentation/rust/index.rst67
-rw-r--r--Documentation/rust/quick-start.rst366
-rw-r--r--Documentation/rust/testing.rst236
-rw-r--r--Documentation/s390/00-INDEX28
-rw-r--r--Documentation/s390/3270.txt271
-rw-r--r--Documentation/s390/CommonIO125
-rw-r--r--Documentation/s390/DASD73
-rw-r--r--Documentation/s390/Debugging390.txt2142
-rw-r--r--Documentation/s390/cds.txt472
-rw-r--r--Documentation/s390/driver-model.txt287
-rw-r--r--Documentation/s390/kvm.txt125
-rw-r--r--Documentation/s390/monreader.txt197
-rw-r--r--Documentation/s390/qeth.txt50
-rw-r--r--Documentation/s390/s390dbf.txt667
-rw-r--r--Documentation/s390/zfcpdump.txt52
-rw-r--r--Documentation/scheduler/00-INDEX18
-rw-r--r--Documentation/scheduler/completion.rst293
-rw-r--r--Documentation/scheduler/completion.txt248
-rw-r--r--Documentation/scheduler/index.rst34
-rw-r--r--Documentation/scheduler/membarrier.rst39
-rw-r--r--Documentation/scheduler/sched-arch.rst72
-rw-r--r--Documentation/scheduler/sched-arch.txt74
-rw-r--r--Documentation/scheduler/sched-bwc.rst246
-rw-r--r--Documentation/scheduler/sched-bwc.txt122
-rw-r--r--Documentation/scheduler/sched-capacity.rst442
-rw-r--r--Documentation/scheduler/sched-deadline.rst919
-rw-r--r--Documentation/scheduler/sched-deadline.txt525
-rw-r--r--Documentation/scheduler/sched-debug.rst54
-rw-r--r--Documentation/scheduler/sched-design-CFS.rst256
-rw-r--r--Documentation/scheduler/sched-design-CFS.txt242
-rw-r--r--Documentation/scheduler/sched-domains.rst80
-rw-r--r--Documentation/scheduler/sched-domains.txt77
-rw-r--r--Documentation/scheduler/sched-eevdf.rst43
-rw-r--r--Documentation/scheduler/sched-energy.rst404
-rw-r--r--Documentation/scheduler/sched-ext.rst367
-rw-r--r--Documentation/scheduler/sched-nice-design.rst112
-rw-r--r--Documentation/scheduler/sched-nice-design.txt108
-rw-r--r--Documentation/scheduler/sched-pelt.c109
-rw-r--r--Documentation/scheduler/sched-rt-group.rst190
-rw-r--r--Documentation/scheduler/sched-rt-group.txt183
-rw-r--r--Documentation/scheduler/sched-stats.rst205
-rw-r--r--Documentation/scheduler/sched-stats.txt154
-rw-r--r--Documentation/scheduler/sched-util-clamp.rst741
-rw-r--r--Documentation/scheduler/schedutil.rst172
-rw-r--r--Documentation/scheduler/text_files.rst5
-rw-r--r--Documentation/scsi/00-INDEX110
-rw-r--r--Documentation/scsi/53c700.rst134
-rw-r--r--Documentation/scsi/53c700.txt135
-rw-r--r--Documentation/scsi/BusLogic.rst581
-rw-r--r--Documentation/scsi/BusLogic.txt566
-rw-r--r--Documentation/scsi/ChangeLog.1992-19972023
-rw-r--r--Documentation/scsi/ChangeLog.lpfc40
-rw-r--r--Documentation/scsi/ChangeLog.megaraid10
-rw-r--r--Documentation/scsi/ChangeLog.megaraid_sas54
-rw-r--r--Documentation/scsi/ChangeLog.ncr53c8xx16
-rw-r--r--Documentation/scsi/ChangeLog.sym53c8xx14
-rw-r--r--Documentation/scsi/ChangeLog.sym53c8xx_210
-rw-r--r--Documentation/scsi/FlashPoint.rst176
-rw-r--r--Documentation/scsi/FlashPoint.txt163
-rw-r--r--Documentation/scsi/LICENSE.qla2xxx290
-rw-r--r--Documentation/scsi/LICENSE.qla4xxx289
-rw-r--r--Documentation/scsi/Mylex.txt5
-rw-r--r--Documentation/scsi/NinjaSCSI.rst164
-rw-r--r--Documentation/scsi/NinjaSCSI.txt128
-rw-r--r--Documentation/scsi/aacraid.rst177
-rw-r--r--Documentation/scsi/aacraid.txt150
-rw-r--r--Documentation/scsi/advansys.rst272
-rw-r--r--Documentation/scsi/advansys.txt243
-rw-r--r--Documentation/scsi/aha152x.rst204
-rw-r--r--Documentation/scsi/aha152x.txt183
-rw-r--r--Documentation/scsi/aic79xx.rst593
-rw-r--r--Documentation/scsi/aic79xx.txt497
-rw-r--r--Documentation/scsi/aic7xxx.rst458
-rw-r--r--Documentation/scsi/aic7xxx.txt394
-rw-r--r--Documentation/scsi/arcmsr_spec.rst908
-rw-r--r--Documentation/scsi/arcmsr_spec.txt574
-rw-r--r--Documentation/scsi/bfa.rst92
-rw-r--r--Documentation/scsi/bfa.txt82
-rw-r--r--Documentation/scsi/bnx2fc.rst81
-rw-r--r--Documentation/scsi/bnx2fc.txt75
-rw-r--r--Documentation/scsi/cxgb3i.rst90
-rw-r--r--Documentation/scsi/cxgb3i.txt84
-rw-r--r--Documentation/scsi/dc395x.rst114
-rw-r--r--Documentation/scsi/dc395x.txt102
-rw-r--r--Documentation/scsi/dpti.rst92
-rw-r--r--Documentation/scsi/dpti.txt83
-rw-r--r--Documentation/scsi/dtc3x80.txt43
-rw-r--r--Documentation/scsi/g_NCR5380.rst93
-rw-r--r--Documentation/scsi/g_NCR5380.txt63
-rw-r--r--Documentation/scsi/hpsa.rst129
-rw-r--r--Documentation/scsi/hpsa.txt130
-rw-r--r--Documentation/scsi/hptiop.rst215
-rw-r--r--Documentation/scsi/hptiop.txt184
-rw-r--r--Documentation/scsi/in2000.txt202
-rw-r--r--Documentation/scsi/index.rst78
-rw-r--r--Documentation/scsi/libsas.rst458
-rw-r--r--Documentation/scsi/libsas.txt395
-rw-r--r--Documentation/scsi/link_power_management_policy.rst25
-rw-r--r--Documentation/scsi/link_power_management_policy.txt19
-rw-r--r--Documentation/scsi/lpfc.rst81
-rw-r--r--Documentation/scsi/lpfc.txt83
-rw-r--r--Documentation/scsi/megaraid.rst77
-rw-r--r--Documentation/scsi/megaraid.txt70
-rw-r--r--Documentation/scsi/ncr53c8xx.rst2169
-rw-r--r--Documentation/scsi/ncr53c8xx.txt1824
-rw-r--r--Documentation/scsi/osd.txt197
-rw-r--r--Documentation/scsi/osst.txt218
-rw-r--r--Documentation/scsi/ppa.rst18
-rw-r--r--Documentation/scsi/ppa.txt14
-rw-r--r--Documentation/scsi/qlogicfas.rst87
-rw-r--r--Documentation/scsi/qlogicfas.txt78
-rw-r--r--Documentation/scsi/scsi-changer.rst184
-rw-r--r--Documentation/scsi/scsi-changer.txt180
-rw-r--r--Documentation/scsi/scsi-generic.rst107
-rw-r--r--Documentation/scsi/scsi-generic.txt101
-rw-r--r--Documentation/scsi/scsi-parameters.rst108
-rw-r--r--Documentation/scsi/scsi-parameters.txt133
-rw-r--r--Documentation/scsi/scsi.rst44
-rw-r--r--Documentation/scsi/scsi.txt44
-rw-r--r--Documentation/scsi/scsi_eh.rst485
-rw-r--r--Documentation/scsi/scsi_eh.txt488
-rw-r--r--Documentation/scsi/scsi_fc_transport.rst593
-rw-r--r--Documentation/scsi/scsi_fc_transport.txt496
-rw-r--r--Documentation/scsi/scsi_mid_low_api.rst1222
-rw-r--r--Documentation/scsi/scsi_mid_low_api.txt1401
-rw-r--r--Documentation/scsi/scsi_transport_srp/Makefile7
-rw-r--r--Documentation/scsi/scsi_transport_srp/figures.rst6
-rw-r--r--Documentation/scsi/sd-parameters.rst27
-rw-r--r--Documentation/scsi/smartpqi.rst78
-rw-r--r--Documentation/scsi/st.rst678
-rw-r--r--Documentation/scsi/st.txt526
-rw-r--r--Documentation/scsi/sym53c500_cs.rst29
-rw-r--r--Documentation/scsi/sym53c500_cs.txt23
-rw-r--r--Documentation/scsi/sym53c8xx_2.rst1209
-rw-r--r--Documentation/scsi/sym53c8xx_2.txt1048
-rw-r--r--Documentation/scsi/tcm_qla2xxx.rst36
-rw-r--r--Documentation/scsi/tmscsim.txt443
-rw-r--r--Documentation/scsi/ufs.rst210
-rw-r--r--Documentation/scsi/ufs.txt133
-rw-r--r--Documentation/scsi/wd719x.rst24
-rw-r--r--Documentation/scsi/wd719x.txt21
-rw-r--r--Documentation/security/00-INDEX26
-rw-r--r--Documentation/security/IMA-templates.rst111
-rw-r--r--Documentation/security/IMA-templates.txt88
-rw-r--r--Documentation/security/LSM.txt34
-rw-r--r--Documentation/security/SCTP.rst344
-rw-r--r--Documentation/security/SELinux.txt27
-rw-r--r--Documentation/security/Smack.txt717
-rw-r--r--Documentation/security/Yama.txt73
-rw-r--r--Documentation/security/apparmor.txt39
-rw-r--r--Documentation/security/credentials.rst559
-rw-r--r--Documentation/security/credentials.txt581
-rw-r--r--Documentation/security/digsig.rst101
-rw-r--r--Documentation/security/index.rst22
-rw-r--r--Documentation/security/ipe.rst446
-rw-r--r--Documentation/security/keys-ecryptfs.txt68
-rw-r--r--Documentation/security/keys-request-key.txt202
-rw-r--r--Documentation/security/keys-trusted-encrypted.txt160
-rw-r--r--Documentation/security/keys.txt1433
-rw-r--r--Documentation/security/keys/core.rst1849
-rw-r--r--Documentation/security/keys/ecryptfs.rst73
-rw-r--r--Documentation/security/keys/index.rst11
-rw-r--r--Documentation/security/keys/request-key.rst207
-rw-r--r--Documentation/security/keys/trusted-encrypted.rst567
-rw-r--r--Documentation/security/landlock.rst149
-rw-r--r--Documentation/security/lsm-development.rst17
-rw-r--r--Documentation/security/lsm.rst131
-rw-r--r--Documentation/security/sak.rst91
-rw-r--r--Documentation/security/secrets/coco.rst103
-rw-r--r--Documentation/security/secrets/index.rst9
-rw-r--r--Documentation/security/self-protection.rst316
-rw-r--r--Documentation/security/siphash.rst199
-rw-r--r--Documentation/security/snp-tdx-threat-model.rst253
-rw-r--r--Documentation/security/tomoyo.txt55
-rw-r--r--Documentation/security/tpm/index.rst13
-rw-r--r--Documentation/security/tpm/tpm-security.rst216
-rw-r--r--Documentation/security/tpm/tpm_event_log.rst55
-rw-r--r--Documentation/security/tpm/tpm_ffa_crb.rst65
-rw-r--r--Documentation/security/tpm/tpm_ftpm_tee.rst27
-rw-r--r--Documentation/security/tpm/tpm_tis.rst46
-rw-r--r--Documentation/security/tpm/tpm_vtpm_proxy.rst50
-rw-r--r--Documentation/security/tpm/xen-tpmfront.rst124
-rw-r--r--Documentation/serial-console.txt109
-rw-r--r--Documentation/serial/00-INDEX16
-rw-r--r--Documentation/serial/README.cycladesZ8
-rw-r--r--Documentation/serial/driver460
-rw-r--r--Documentation/serial/moxa-smartio523
-rw-r--r--Documentation/serial/n_gsm.txt89
-rw-r--r--Documentation/serial/rocket.txt189
-rw-r--r--Documentation/serial/serial-rs485.txt136
-rw-r--r--Documentation/serial/tty.txt301
-rw-r--r--Documentation/sgi-ioc4.txt45
-rw-r--r--Documentation/sh/new-machine.txt278
-rw-r--r--Documentation/sh/register-banks.txt33
-rw-r--r--Documentation/smsc_ece1099.txt56
-rw-r--r--Documentation/sound/alsa-configuration.rst2833
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt2321
-rw-r--r--Documentation/sound/alsa/Audigy-mixer.txt345
-rw-r--r--Documentation/sound/alsa/Audiophile-Usb.txt442
-rw-r--r--Documentation/sound/alsa/Bt87x.txt78
-rw-r--r--Documentation/sound/alsa/CMIPCI.txt254
-rw-r--r--Documentation/sound/alsa/Channel-Mapping-API.txt153
-rw-r--r--Documentation/sound/alsa/ControlNames.txt107
-rw-r--r--Documentation/sound/alsa/HD-Audio-Controls.txt116
-rw-r--r--Documentation/sound/alsa/HD-Audio-Models.txt314
-rw-r--r--Documentation/sound/alsa/HD-Audio.txt863
-rw-r--r--Documentation/sound/alsa/Joystick.txt86
-rw-r--r--Documentation/sound/alsa/MIXART.txt100
-rw-r--r--Documentation/sound/alsa/OSS-Emulation.txt305
-rw-r--r--Documentation/sound/alsa/Procfile.txt234
-rw-r--r--Documentation/sound/alsa/README.maya44163
-rw-r--r--Documentation/sound/alsa/SB-Live-mixer.txt356
-rw-r--r--Documentation/sound/alsa/VIA82xx-mixer.txt8
-rw-r--r--Documentation/sound/alsa/alsa-parameters.txt135
-rw-r--r--Documentation/sound/alsa/compress_offload.txt234
-rw-r--r--Documentation/sound/alsa/emu10k1-jack.txt74
-rw-r--r--Documentation/sound/alsa/hda_codec.txt322
-rw-r--r--Documentation/sound/alsa/hdspm.txt362
-rw-r--r--Documentation/sound/alsa/powersave.txt41
-rw-r--r--Documentation/sound/alsa/seq_oss.html409
-rw-r--r--Documentation/sound/alsa/serial-u16550.txt88
-rw-r--r--Documentation/sound/alsa/soc/DAI.txt56
-rw-r--r--Documentation/sound/alsa/soc/DPCM.txt380
-rw-r--r--Documentation/sound/alsa/soc/clocking.txt51
-rw-r--r--Documentation/sound/alsa/soc/codec.txt179
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt305
-rw-r--r--Documentation/sound/alsa/soc/jack.txt71
-rw-r--r--Documentation/sound/alsa/soc/machine.txt93
-rw-r--r--Documentation/sound/alsa/soc/overview.txt95
-rw-r--r--Documentation/sound/alsa/soc/platform.txt79
-rw-r--r--Documentation/sound/alsa/soc/pops_clicks.txt52
-rw-r--r--Documentation/sound/alsa/timestamping.txt200
-rw-r--r--Documentation/sound/cards/audigy-mixer.rst306
-rw-r--r--Documentation/sound/cards/audiophile-usb.rst550
-rw-r--r--Documentation/sound/cards/bt87x.rst83
-rw-r--r--Documentation/sound/cards/cmipci.rst272
-rw-r--r--Documentation/sound/cards/emu-mixer.rst226
-rw-r--r--Documentation/sound/cards/emu10k1-jack.rst78
-rw-r--r--Documentation/sound/cards/hdspm.rst379
-rw-r--r--Documentation/sound/cards/img-spdif-in.rst53
-rw-r--r--Documentation/sound/cards/index.rst21
-rw-r--r--Documentation/sound/cards/joystick.rst91
-rw-r--r--Documentation/sound/cards/maya44.rst186
-rw-r--r--Documentation/sound/cards/mixart.rst110
-rwxr-xr-xDocumentation/sound/cards/multisound.sh1139
-rw-r--r--Documentation/sound/cards/pcmtest.rst120
-rw-r--r--Documentation/sound/cards/sb-live-mixer.rst376
-rw-r--r--Documentation/sound/cards/serial-u16550.rst93
-rw-r--r--Documentation/sound/cards/via82xx-mixer.rst8
-rw-r--r--Documentation/sound/codecs/cs35l56.rst305
-rw-r--r--Documentation/sound/codecs/index.rst9
-rw-r--r--Documentation/sound/designs/channel-mapping-api.rst164
-rw-r--r--Documentation/sound/designs/compress-accel.rst134
-rw-r--r--Documentation/sound/designs/compress-offload.rst329
-rw-r--r--Documentation/sound/designs/control-names.rst142
-rw-r--r--Documentation/sound/designs/index.rst19
-rw-r--r--Documentation/sound/designs/jack-controls.rst48
-rw-r--r--Documentation/sound/designs/jack-injection.rst166
-rw-r--r--Documentation/sound/designs/midi-2.0.rst584
-rw-r--r--Documentation/sound/designs/oss-emulation.rst336
-rw-r--r--Documentation/sound/designs/powersave.rst43
-rw-r--r--Documentation/sound/designs/procfile.rst238
-rw-r--r--Documentation/sound/designs/seq-oss.rst371
-rw-r--r--Documentation/sound/designs/timestamping.rst215
-rw-r--r--Documentation/sound/designs/tracepoints.rst172
-rw-r--r--Documentation/sound/hd-audio/controls.rst121
-rw-r--r--Documentation/sound/hd-audio/dp-mst.rst101
-rw-r--r--Documentation/sound/hd-audio/index.rst12
-rw-r--r--Documentation/sound/hd-audio/intel-multi-link.rst312
-rw-r--r--Documentation/sound/hd-audio/models.rst809
-rw-r--r--Documentation/sound/hd-audio/notes.rst892
-rw-r--r--Documentation/sound/hd-audio/realtek-pc-beep.rst129
-rw-r--r--Documentation/sound/index.rst24
-rw-r--r--Documentation/sound/kernel-api/alsa-driver-api.rst135
-rw-r--r--Documentation/sound/kernel-api/index.rst8
-rw-r--r--Documentation/sound/kernel-api/writing-an-alsa-driver.rst4064
-rw-r--r--Documentation/sound/oss/ALS66
-rw-r--r--Documentation/sound/oss/AudioExcelDSP16101
-rw-r--r--Documentation/sound/oss/CMI8330152
-rw-r--r--Documentation/sound/oss/ESS34
-rw-r--r--Documentation/sound/oss/ESS186855
-rw-r--r--Documentation/sound/oss/Introduction459
-rw-r--r--Documentation/sound/oss/MultiSound1137
-rw-r--r--Documentation/sound/oss/OPL36
-rw-r--r--Documentation/sound/oss/Opti218
-rw-r--r--Documentation/sound/oss/PAS16162
-rw-r--r--Documentation/sound/oss/PSS41
-rw-r--r--Documentation/sound/oss/PSS-updates88
-rw-r--r--Documentation/sound/oss/README.OSS1455
-rw-r--r--Documentation/sound/oss/README.modules106
-rw-r--r--Documentation/sound/oss/README.ymfsb107
-rw-r--r--Documentation/sound/oss/SoundPro105
-rw-r--r--Documentation/sound/oss/Soundblaster53
-rw-r--r--Documentation/sound/oss/Tropez+26
-rw-r--r--Documentation/sound/oss/VIBRA1680
-rw-r--r--Documentation/sound/oss/WaveArtist170
-rw-r--r--Documentation/sound/oss/btaudio92
-rw-r--r--Documentation/sound/oss/mwave185
-rw-r--r--Documentation/sound/oss/oss-parameters.txt51
-rw-r--r--Documentation/sound/oss/ultrasound30
-rw-r--r--Documentation/sound/soc/clocking.rst58
-rw-r--r--Documentation/sound/soc/codec-to-codec.rst115
-rw-r--r--Documentation/sound/soc/codec.rst190
-rw-r--r--Documentation/sound/soc/dai.rst64
-rw-r--r--Documentation/sound/soc/dapm-graph.svg375
-rw-r--r--Documentation/sound/soc/dapm.rst422
-rw-r--r--Documentation/sound/soc/dpcm.rst387
-rw-r--r--Documentation/sound/soc/index.rst21
-rw-r--r--Documentation/sound/soc/jack.rst72
-rw-r--r--Documentation/sound/soc/machine.rst123
-rw-r--r--Documentation/sound/soc/overview.rst69
-rw-r--r--Documentation/sound/soc/platform.rst78
-rw-r--r--Documentation/sound/soc/pops-clicks.rst55
-rw-r--r--Documentation/sound/soc/usb.rst482
-rw-r--r--Documentation/sound/utimers.rst126
-rw-r--r--Documentation/sparse.txt108
-rw-r--r--Documentation/sphinx-static/custom.css153
-rw-r--r--Documentation/sphinx-static/theme_overrides.css120
-rw-r--r--Documentation/sphinx-static/theme_rtd_colors.css37
-rw-r--r--Documentation/sphinx/automarkup.py306
-rw-r--r--Documentation/sphinx/kernel_abi.py173
-rw-r--r--Documentation/sphinx/kernel_feat.py137
-rwxr-xr-xDocumentation/sphinx/kernel_include.py527
-rw-r--r--Documentation/sphinx/kerneldoc-preamble.sty234
-rw-r--r--Documentation/sphinx/kerneldoc.py313
-rw-r--r--Documentation/sphinx/kfigure.py655
-rwxr-xr-xDocumentation/sphinx/maintainers_include.py197
-rw-r--r--Documentation/sphinx/min_requirements.txt11
-rwxr-xr-xDocumentation/sphinx/parser_yaml.py123
-rw-r--r--Documentation/sphinx/requirements.txt4
-rwxr-xr-xDocumentation/sphinx/rstFlatTable.py365
-rw-r--r--Documentation/sphinx/templates/kernel-toc.html19
-rw-r--r--Documentation/sphinx/templates/translations.html15
-rw-r--r--Documentation/sphinx/translations.py99
-rw-r--r--Documentation/spi/.gitignore2
-rw-r--r--Documentation/spi/00-INDEX22
-rw-r--r--Documentation/spi/Makefile8
-rw-r--r--Documentation/spi/butterfly68
-rw-r--r--Documentation/spi/butterfly.rst74
-rw-r--r--Documentation/spi/ep93xx_spi105
-rw-r--r--Documentation/spi/index.rst21
-rw-r--r--Documentation/spi/pxa2xx241
-rw-r--r--Documentation/spi/spi-lm70llp79
-rw-r--r--Documentation/spi/spi-lm70llp.rst84
-rw-r--r--Documentation/spi/spi-sc18is60236
-rw-r--r--Documentation/spi/spi-sc18is602.rst39
-rw-r--r--Documentation/spi/spi-summary612
-rw-r--r--Documentation/spi/spi-summary.rst714
-rw-r--r--Documentation/spi/spidev149
-rw-r--r--Documentation/spi/spidev.rst191
-rw-r--r--Documentation/spi/spidev_fdx.c158
-rw-r--r--Documentation/spi/spidev_test.c318
-rw-r--r--Documentation/stable_api_nonsense.txt190
-rw-r--r--Documentation/stable_kernel_rules.txt132
-rw-r--r--Documentation/staging/crc32.rst189
-rw-r--r--Documentation/staging/index.rst16
-rw-r--r--Documentation/staging/lzo.rst202
-rw-r--r--Documentation/staging/magic-number.rst84
-rw-r--r--Documentation/staging/remoteproc.rst360
-rw-r--r--Documentation/staging/rpmsg.rst299
-rw-r--r--Documentation/staging/speculation.rst91
-rw-r--r--Documentation/staging/static-keys.rst328
-rw-r--r--Documentation/staging/xz.rst98
-rw-r--r--Documentation/static-keys.txt286
-rw-r--r--Documentation/subsystem-apis.rst93
-rw-r--r--Documentation/sunrpc/xdr/nfs4_1.x186
-rw-r--r--Documentation/svga.txt276
-rw-r--r--Documentation/sysctl/00-INDEX16
-rw-r--r--Documentation/sysctl/README75
-rw-r--r--Documentation/sysctl/abi.txt54
-rw-r--r--Documentation/sysctl/fs.txt300
-rw-r--r--Documentation/sysctl/kernel.txt935
-rw-r--r--Documentation/sysctl/net.txt304
-rw-r--r--Documentation/sysctl/sunrpc.txt20
-rw-r--r--Documentation/sysctl/vm.txt815
-rw-r--r--Documentation/sysfs-rules.txt184
-rw-r--r--Documentation/sysrq.txt255
-rw-r--r--Documentation/target/index.rst19
-rw-r--r--Documentation/target/scripts.rst5
-rwxr-xr-xDocumentation/target/target-export-device80
-rwxr-xr-xDocumentation/target/tcm_mod_builder.py968
-rw-r--r--Documentation/target/tcm_mod_builder.rst149
-rw-r--r--Documentation/target/tcm_mod_builder.txt145
-rw-r--r--Documentation/target/tcmu-design.rst405
-rw-r--r--Documentation/target/tcmu-design.txt391
-rw-r--r--Documentation/tee/amd-tee.rst90
-rw-r--r--Documentation/tee/index.rst21
-rw-r--r--Documentation/tee/op-tee.rst166
-rw-r--r--Documentation/tee/qtee.rst96
-rw-r--r--Documentation/tee/tee.rst22
-rw-r--r--Documentation/tee/ts-tee.rst71
-rw-r--r--Documentation/thermal/cpu-cooling-api.txt43
-rw-r--r--Documentation/thermal/exynos_thermal77
-rw-r--r--Documentation/thermal/exynos_thermal_emulation53
-rw-r--r--Documentation/thermal/intel_powerclamp.txt307
-rw-r--r--Documentation/thermal/nouveau_thermal82
-rw-r--r--Documentation/thermal/sysfs-api.txt401
-rw-r--r--Documentation/thermal/x86_pkg_temperature_thermal47
-rw-r--r--Documentation/this_cpu_ops.txt332
-rw-r--r--Documentation/timers/.gitignore1
-rw-r--r--Documentation/timers/00-INDEX20
-rw-r--r--Documentation/timers/Makefile5
-rw-r--r--Documentation/timers/NO_HZ.txt348
-rw-r--r--Documentation/timers/delay_sleep_functions.rst121
-rw-r--r--Documentation/timers/highres.rst250
-rw-r--r--Documentation/timers/highres.txt249
-rw-r--r--Documentation/timers/hpet.rst30
-rw-r--r--Documentation/timers/hpet.txt30
-rw-r--r--Documentation/timers/hpet_example.c294
-rw-r--r--Documentation/timers/hrtimers.rst173
-rw-r--r--Documentation/timers/hrtimers.txt178
-rw-r--r--Documentation/timers/index.rst22
-rw-r--r--Documentation/timers/no_hz.rst317
-rw-r--r--Documentation/timers/timekeeping.rst180
-rw-r--r--Documentation/timers/timekeeping.txt179
-rw-r--r--Documentation/timers/timer_stats.txt73
-rw-r--r--Documentation/timers/timers-howto.txt105
-rw-r--r--Documentation/tools/index.rst21
-rw-r--r--Documentation/tools/rtla/Makefile53
-rw-r--r--Documentation/tools/rtla/common_appendix.txt24
-rw-r--r--Documentation/tools/rtla/common_hist_options.txt23
-rw-r--r--Documentation/tools/rtla/common_options.txt129
-rw-r--r--Documentation/tools/rtla/common_osnoise_description.txt8
-rw-r--r--Documentation/tools/rtla/common_osnoise_options.txt39
-rw-r--r--Documentation/tools/rtla/common_timerlat_aa.txt7
-rw-r--r--Documentation/tools/rtla/common_timerlat_description.txt18
-rw-r--r--Documentation/tools/rtla/common_timerlat_options.txt67
-rw-r--r--Documentation/tools/rtla/common_top_options.txt3
-rw-r--r--Documentation/tools/rtla/index.rst27
-rw-r--r--Documentation/tools/rtla/rtla-hwnoise.rst109
-rw-r--r--Documentation/tools/rtla/rtla-osnoise-hist.rst68
-rw-r--r--Documentation/tools/rtla/rtla-osnoise-top.rst63
-rw-r--r--Documentation/tools/rtla/rtla-osnoise.rst59
-rw-r--r--Documentation/tools/rtla/rtla-timerlat-hist.rst113
-rw-r--r--Documentation/tools/rtla/rtla-timerlat-top.rst136
-rw-r--r--Documentation/tools/rtla/rtla-timerlat.rst54
-rw-r--r--Documentation/tools/rtla/rtla.rst48
-rw-r--r--Documentation/tools/rv/Makefile52
-rw-r--r--Documentation/tools/rv/common_appendix.rst16
-rw-r--r--Documentation/tools/rv/common_ikm.rst21
-rw-r--r--Documentation/tools/rv/index.rst25
-rw-r--r--Documentation/tools/rv/rv-list.rst43
-rw-r--r--Documentation/tools/rv/rv-mon-sched.rst69
-rw-r--r--Documentation/tools/rv/rv-mon-wip.rst44
-rw-r--r--Documentation/tools/rv/rv-mon-wwnr.rst43
-rw-r--r--Documentation/tools/rv/rv-mon.rst55
-rw-r--r--Documentation/tools/rv/rv.rst63
-rw-r--r--Documentation/tpm/xen-tpmfront.txt113
-rw-r--r--Documentation/trace/boottime-trace.rst301
-rw-r--r--Documentation/trace/coresight.txt299
-rw-r--r--Documentation/trace/coresight/coresight-config.rst294
-rw-r--r--Documentation/trace/coresight/coresight-cpu-debug.rst193
-rw-r--r--Documentation/trace/coresight/coresight-dummy.rst32
-rw-r--r--Documentation/trace/coresight/coresight-ect.rst226
-rw-r--r--Documentation/trace/coresight/coresight-etm4x-reference.rst827
-rw-r--r--Documentation/trace/coresight/coresight-perf.rst189
-rw-r--r--Documentation/trace/coresight/coresight-tpda.rst52
-rw-r--r--Documentation/trace/coresight/coresight-tpdm.rst45
-rw-r--r--Documentation/trace/coresight/coresight-trbe.rst38
-rw-r--r--Documentation/trace/coresight/coresight.rst686
-rw-r--r--Documentation/trace/coresight/index.rst9
-rw-r--r--Documentation/trace/coresight/panic.rst362
-rw-r--r--Documentation/trace/coresight/ultrasoc-smb.rst83
-rw-r--r--Documentation/trace/debugging.rst161
-rw-r--r--Documentation/trace/eprobetrace.rst269
-rw-r--r--Documentation/trace/events-kmem.rst119
-rw-r--r--Documentation/trace/events-kmem.txt107
-rw-r--r--Documentation/trace/events-msr.rst40
-rw-r--r--Documentation/trace/events-nmi.rst45
-rw-r--r--Documentation/trace/events-nmi.txt43
-rw-r--r--Documentation/trace/events-power.rst104
-rw-r--r--Documentation/trace/events-power.txt96
-rw-r--r--Documentation/trace/events.rst1123
-rw-r--r--Documentation/trace/events.txt496
-rw-r--r--Documentation/trace/fprobe.rst198
-rw-r--r--Documentation/trace/fprobetrace.rst251
-rw-r--r--Documentation/trace/ftrace-design.rst395
-rw-r--r--Documentation/trace/ftrace-design.txt382
-rw-r--r--Documentation/trace/ftrace-uses.rst348
-rw-r--r--Documentation/trace/ftrace.rst3809
-rw-r--r--Documentation/trace/ftrace.txt2846
-rw-r--r--Documentation/trace/hisi-ptt.rst304
-rw-r--r--Documentation/trace/histogram-design.rst2118
-rw-r--r--Documentation/trace/histogram.rst3071
-rw-r--r--Documentation/trace/hwlat_detector.rst88
-rw-r--r--Documentation/trace/index.rst104
-rw-r--r--Documentation/trace/intel_th.rst150
-rw-r--r--Documentation/trace/kprobes.rst789
-rw-r--r--Documentation/trace/kprobetrace.rst285
-rw-r--r--Documentation/trace/kprobetrace.txt172
-rw-r--r--Documentation/trace/mmiotrace.rst184
-rw-r--r--Documentation/trace/mmiotrace.txt164
-rw-r--r--Documentation/trace/osnoise-tracer.rst180
-rw-r--r--Documentation/trace/postprocess/decode_msr.py37
-rw-r--r--Documentation/trace/postprocess/trace-pagealloc-postprocess.pl6
-rw-r--r--Documentation/trace/postprocess/trace-vmscan-postprocess.pl63
-rw-r--r--Documentation/trace/ring-buffer-design.rst983
-rw-r--r--Documentation/trace/ring-buffer-design.txt955
-rw-r--r--Documentation/trace/ring-buffer-map.rst106
-rw-r--r--Documentation/trace/rv/da_monitor_instrumentation.rst171
-rw-r--r--Documentation/trace/rv/deterministic_automata.rst184
-rw-r--r--Documentation/trace/rv/index.rst17
-rw-r--r--Documentation/trace/rv/linear_temporal_logic.rst134
-rw-r--r--Documentation/trace/rv/monitor_rtapp.rst133
-rw-r--r--Documentation/trace/rv/monitor_sched.rst402
-rw-r--r--Documentation/trace/rv/monitor_synthesis.rst271
-rw-r--r--Documentation/trace/rv/monitor_wip.rst55
-rw-r--r--Documentation/trace/rv/monitor_wwnr.rst45
-rw-r--r--Documentation/trace/rv/runtime-verification.rst231
-rw-r--r--Documentation/trace/stm.rst143
-rw-r--r--Documentation/trace/sys-t.rst62
-rw-r--r--Documentation/trace/timerlat-tracer.rst260
-rw-r--r--Documentation/trace/tracepoint-analysis.rst338
-rw-r--r--Documentation/trace/tracepoint-analysis.txt327
-rw-r--r--Documentation/trace/tracepoints.rst180
-rw-r--r--Documentation/trace/tracepoints.txt145
-rw-r--r--Documentation/trace/uprobetracer.rst186
-rw-r--r--Documentation/trace/uprobetracer.txt159
-rw-r--r--Documentation/trace/user_events.rst304
-rw-r--r--Documentation/translations/index.rst59
-rw-r--r--Documentation/translations/it_IT/RCU/index.rst19
-rw-r--r--Documentation/translations/it_IT/RCU/torture.rst369
-rw-r--r--Documentation/translations/it_IT/admin-guide/README.rst12
-rw-r--r--Documentation/translations/it_IT/admin-guide/kernel-parameters.rst12
-rw-r--r--Documentation/translations/it_IT/arch/riscv/patch-acceptance.rst60
-rw-r--r--Documentation/translations/it_IT/core-api/index.rst30
-rw-r--r--Documentation/translations/it_IT/core-api/memory-allocation.rst13
-rw-r--r--Documentation/translations/it_IT/core-api/symbol-namespaces.rst163
-rw-r--r--Documentation/translations/it_IT/dev-tools/clang-format.rst197
-rw-r--r--Documentation/translations/it_IT/dev-tools/index.rst17
-rw-r--r--Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst11
-rw-r--r--Documentation/translations/it_IT/disclaimer-ita.rst6
-rw-r--r--Documentation/translations/it_IT/doc-guide/index.rst24
-rw-r--r--Documentation/translations/it_IT/doc-guide/kernel-doc.rst607
-rw-r--r--Documentation/translations/it_IT/doc-guide/parse-headers.rst195
-rw-r--r--Documentation/translations/it_IT/doc-guide/sphinx.rst501
-rw-r--r--Documentation/translations/it_IT/i2c/i2c-protocol.rst99
-rw-r--r--Documentation/translations/it_IT/i2c/index.rst46
-rw-r--r--Documentation/translations/it_IT/i2c/summary.rst84
-rw-r--r--Documentation/translations/it_IT/index.rst137
-rw-r--r--Documentation/translations/it_IT/kernel-hacking/hacking.rst870
-rw-r--r--Documentation/translations/it_IT/kernel-hacking/index.rst16
-rw-r--r--Documentation/translations/it_IT/kernel-hacking/locking.rst1498
-rw-r--r--Documentation/translations/it_IT/locking/index.rst20
-rw-r--r--Documentation/translations/it_IT/locking/lockdep-design.rst678
-rw-r--r--Documentation/translations/it_IT/locking/lockstat.rst230
-rw-r--r--Documentation/translations/it_IT/locking/locktorture.rst181
-rw-r--r--Documentation/translations/it_IT/locking/locktypes.rst547
-rw-r--r--Documentation/translations/it_IT/maintainer/configure-git.rst10
-rw-r--r--Documentation/translations/it_IT/process/1.Intro.rst297
-rw-r--r--Documentation/translations/it_IT/process/2.Process.rst530
-rw-r--r--Documentation/translations/it_IT/process/3.Early-stage.rst242
-rw-r--r--Documentation/translations/it_IT/process/4.Coding.rst450
-rw-r--r--Documentation/translations/it_IT/process/5.Posting.rst381
-rw-r--r--Documentation/translations/it_IT/process/6.Followthrough.rst247
-rw-r--r--Documentation/translations/it_IT/process/7.AdvancedTopics.rst210
-rw-r--r--Documentation/translations/it_IT/process/8.Conclusion.rst84
-rw-r--r--Documentation/translations/it_IT/process/adding-syscalls.rst643
-rw-r--r--Documentation/translations/it_IT/process/applying-patches.rst15
-rw-r--r--Documentation/translations/it_IT/process/botching-up-ioctls.rst249
-rw-r--r--Documentation/translations/it_IT/process/changes.rst553
-rw-r--r--Documentation/translations/it_IT/process/code-of-conduct.rst12
-rw-r--r--Documentation/translations/it_IT/process/coding-style.rst1230
-rw-r--r--Documentation/translations/it_IT/process/deprecated.rst409
-rw-r--r--Documentation/translations/it_IT/process/development-process.rst32
-rw-r--r--Documentation/translations/it_IT/process/email-clients.rst376
-rw-r--r--Documentation/translations/it_IT/process/howto.rst642
-rw-r--r--Documentation/translations/it_IT/process/index.rst107
-rw-r--r--Documentation/translations/it_IT/process/kernel-docs.rst18
-rw-r--r--Documentation/translations/it_IT/process/kernel-driver-statement.rst211
-rw-r--r--Documentation/translations/it_IT/process/kernel-enforcement-statement.rst175
-rw-r--r--Documentation/translations/it_IT/process/license-rules.rst500
-rw-r--r--Documentation/translations/it_IT/process/maintainer-handbooks.rst24
-rw-r--r--Documentation/translations/it_IT/process/maintainer-pgp-guide.rst941
-rw-r--r--Documentation/translations/it_IT/process/maintainer-tip.rst10
-rw-r--r--Documentation/translations/it_IT/process/maintainers.rst13
-rw-r--r--Documentation/translations/it_IT/process/management-style.rst295
-rw-r--r--Documentation/translations/it_IT/process/programming-language.rst68
-rw-r--r--Documentation/translations/it_IT/process/security-bugs.rst12
-rw-r--r--Documentation/translations/it_IT/process/stable-api-nonsense.rst209
-rw-r--r--Documentation/translations/it_IT/process/stable-kernel-rules.rst248
-rw-r--r--Documentation/translations/it_IT/process/submit-checklist.rst142
-rw-r--r--Documentation/translations/it_IT/process/submitting-patches.rst930
-rw-r--r--Documentation/translations/it_IT/process/volatile-considered-harmful.rst134
-rw-r--r--Documentation/translations/it_IT/staging/index.rst13
-rw-r--r--Documentation/translations/it_IT/staging/magic-number.rst90
-rw-r--r--Documentation/translations/it_IT/subsystem-apis.rst47
-rw-r--r--Documentation/translations/ja_JP/SubmittingPatches747
-rw-r--r--Documentation/translations/ja_JP/disclaimer-ja_JP.rst24
-rw-r--r--Documentation/translations/ja_JP/index.rst20
-rw-r--r--Documentation/translations/ja_JP/process/howto.rst629
-rw-r--r--Documentation/translations/ja_JP/process/submit-checklist.rst163
-rw-r--r--Documentation/translations/ja_JP/stable_api_nonsense.txt263
-rw-r--r--Documentation/translations/ja_JP/stable_kernel_rules.txt84
-rw-r--r--Documentation/translations/ko_KR/core-api/wrappers/memory-barriers.rst18
-rw-r--r--Documentation/translations/ko_KR/index.rst19
-rw-r--r--Documentation/translations/ko_KR/memory-barriers.txt2952
-rw-r--r--Documentation/translations/ko_KR/process/howto.rst619
-rw-r--r--Documentation/translations/ko_KR/stable_api_nonsense.txt195
-rw-r--r--Documentation/translations/sp_SP/disclaimer-sp.rst9
-rw-r--r--Documentation/translations/sp_SP/index.rst81
-rw-r--r--Documentation/translations/sp_SP/memory-barriers.txt3134
-rw-r--r--Documentation/translations/sp_SP/process/1.Intro.rst302
-rw-r--r--Documentation/translations/sp_SP/process/2.Process.rst543
-rw-r--r--Documentation/translations/sp_SP/process/3.Early-stage.rst241
-rw-r--r--Documentation/translations/sp_SP/process/4.Coding.rst470
-rw-r--r--Documentation/translations/sp_SP/process/5.Posting.rst391
-rw-r--r--Documentation/translations/sp_SP/process/6.Followthrough.rst230
-rw-r--r--Documentation/translations/sp_SP/process/7.AdvancedTopics.rst214
-rw-r--r--Documentation/translations/sp_SP/process/8.Conclusion.rst82
-rw-r--r--Documentation/translations/sp_SP/process/adding-syscalls.rst632
-rw-r--r--Documentation/translations/sp_SP/process/code-of-conduct.rst97
-rw-r--r--Documentation/translations/sp_SP/process/coding-style.rst1315
-rw-r--r--Documentation/translations/sp_SP/process/contribution-maturity-model.rst120
-rw-r--r--Documentation/translations/sp_SP/process/deprecated.rst381
-rw-r--r--Documentation/translations/sp_SP/process/development-process.rst32
-rw-r--r--Documentation/translations/sp_SP/process/email-clients.rst374
-rw-r--r--Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst341
-rw-r--r--Documentation/translations/sp_SP/process/handling-regressions.rst797
-rw-r--r--Documentation/translations/sp_SP/process/howto.rst617
-rw-r--r--Documentation/translations/sp_SP/process/index.rst32
-rw-r--r--Documentation/translations/sp_SP/process/kernel-docs.rst186
-rw-r--r--Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst174
-rw-r--r--Documentation/translations/sp_SP/process/magic-number.rst89
-rw-r--r--Documentation/translations/sp_SP/process/maintainer-kvm-x86.rst465
-rw-r--r--Documentation/translations/sp_SP/process/management-style.rst299
-rw-r--r--Documentation/translations/sp_SP/process/programming-language.rst53
-rw-r--r--Documentation/translations/sp_SP/process/researcher-guidelines.rst150
-rw-r--r--Documentation/translations/sp_SP/process/security-bugs.rst103
-rw-r--r--Documentation/translations/sp_SP/process/submit-checklist.rst134
-rw-r--r--Documentation/translations/sp_SP/process/submitting-patches.rst919
-rw-r--r--Documentation/translations/sp_SP/scheduler/index.rst10
-rw-r--r--Documentation/translations/sp_SP/scheduler/sched-bwc.rst287
-rw-r--r--Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst277
-rw-r--r--Documentation/translations/sp_SP/scheduler/sched-eevdf.rst58
-rw-r--r--Documentation/translations/sp_SP/wrappers/memory-barriers.rst19
-rw-r--r--Documentation/translations/zh_CN/PCI/acpi-info.rst139
-rw-r--r--Documentation/translations/zh_CN/PCI/index.rst34
-rw-r--r--Documentation/translations/zh_CN/PCI/msi-howto.rst244
-rw-r--r--Documentation/translations/zh_CN/PCI/pci-iov-howto.rst169
-rw-r--r--Documentation/translations/zh_CN/PCI/pci.rst514
-rw-r--r--Documentation/translations/zh_CN/PCI/pciebus-howto.rst192
-rw-r--r--Documentation/translations/zh_CN/PCI/sysfs-pci.rst126
-rw-r--r--Documentation/translations/zh_CN/accounting/delay-accounting.rst112
-rw-r--r--Documentation/translations/zh_CN/accounting/index.rst25
-rw-r--r--Documentation/translations/zh_CN/accounting/psi.rst155
-rw-r--r--Documentation/translations/zh_CN/accounting/taskstats.rst145
-rw-r--r--Documentation/translations/zh_CN/admin-guide/README.rst291
-rw-r--r--Documentation/translations/zh_CN/admin-guide/bootconfig.rst293
-rw-r--r--Documentation/translations/zh_CN/admin-guide/bug-bisect.rst81
-rw-r--r--Documentation/translations/zh_CN/admin-guide/bug-hunting.rst331
-rw-r--r--Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst9
-rw-r--r--Documentation/translations/zh_CN/admin-guide/cpu-load.rst105
-rw-r--r--Documentation/translations/zh_CN/admin-guide/cputopology.rst96
-rw-r--r--Documentation/translations/zh_CN/admin-guide/index.rst132
-rw-r--r--Documentation/translations/zh_CN/admin-guide/init.rst54
-rw-r--r--Documentation/translations/zh_CN/admin-guide/lockup-watchdogs.rst66
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst29
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst263
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst228
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst124
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst345
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/index.rst49
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/ksm.rst198
-rw-r--r--Documentation/translations/zh_CN/admin-guide/numastat.rst48
-rw-r--r--Documentation/translations/zh_CN/admin-guide/reporting-issues.rst1368
-rw-r--r--Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst370
-rw-r--r--Documentation/translations/zh_CN/admin-guide/sysrq.rst280
-rw-r--r--Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst157
-rw-r--r--Documentation/translations/zh_CN/admin-guide/unicode.rst170
-rw-r--r--Documentation/translations/zh_CN/arch/arm/Booting175
-rw-r--r--Documentation/translations/zh_CN/arch/arm/kernel_user_helpers.txt284
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/amu.rst100
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/booting.txt246
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/elf_hwcaps.rst240
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/hugetlbpage.rst45
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/index.rst19
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/legacy_instructions.txt72
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/memory.txt114
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/perf.rst86
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/silicon-errata.txt74
-rw-r--r--Documentation/translations/zh_CN/arch/arm64/tagged-pointers.txt52
-rw-r--r--Documentation/translations/zh_CN/arch/index.rst28
-rw-r--r--Documentation/translations/zh_CN/arch/loongarch/booting.rst48
-rw-r--r--Documentation/translations/zh_CN/arch/loongarch/features.rst8
-rw-r--r--Documentation/translations/zh_CN/arch/loongarch/index.rst27
-rw-r--r--Documentation/translations/zh_CN/arch/loongarch/introduction.rst353
-rw-r--r--Documentation/translations/zh_CN/arch/loongarch/irq-chip-model.rst244
-rw-r--r--Documentation/translations/zh_CN/arch/mips/booting.rst34
-rw-r--r--Documentation/translations/zh_CN/arch/mips/features.rst13
-rw-r--r--Documentation/translations/zh_CN/arch/mips/index.rst29
-rw-r--r--Documentation/translations/zh_CN/arch/mips/ingenic-tcu.rst72
-rw-r--r--Documentation/translations/zh_CN/arch/openrisc/index.rst32
-rw-r--r--Documentation/translations/zh_CN/arch/openrisc/openrisc_port.rst127
-rw-r--r--Documentation/translations/zh_CN/arch/openrisc/todo.rst23
-rw-r--r--Documentation/translations/zh_CN/arch/parisc/debugging.rst45
-rw-r--r--Documentation/translations/zh_CN/arch/parisc/index.rst31
-rw-r--r--Documentation/translations/zh_CN/arch/parisc/registers.rst156
-rw-r--r--Documentation/translations/zh_CN/arch/riscv/boot-image-header.rst69
-rw-r--r--Documentation/translations/zh_CN/arch/riscv/boot.rst155
-rw-r--r--Documentation/translations/zh_CN/arch/riscv/index.rst31
-rw-r--r--Documentation/translations/zh_CN/arch/riscv/patch-acceptance.rst33
-rw-r--r--Documentation/translations/zh_CN/arch/riscv/vm-layout.rst104
-rw-r--r--Documentation/translations/zh_CN/block/blk-mq.rst130
-rw-r--r--Documentation/translations/zh_CN/block/data-integrity.rst192
-rw-r--r--Documentation/translations/zh_CN/block/index.rst35
-rw-r--r--Documentation/translations/zh_CN/core-api/assoc_array.rst473
-rw-r--r--Documentation/translations/zh_CN/core-api/boot-time-mm.rst49
-rw-r--r--Documentation/translations/zh_CN/core-api/cachetlb.rst333
-rw-r--r--Documentation/translations/zh_CN/core-api/circular-buffers.rst210
-rw-r--r--Documentation/translations/zh_CN/core-api/cpu_hotplug.rst661
-rw-r--r--Documentation/translations/zh_CN/core-api/errseq.rst145
-rw-r--r--Documentation/translations/zh_CN/core-api/genalloc.rst109
-rw-r--r--Documentation/translations/zh_CN/core-api/generic-radix-tree.rst23
-rw-r--r--Documentation/translations/zh_CN/core-api/genericirq.rst409
-rw-r--r--Documentation/translations/zh_CN/core-api/gfp_mask-from-fs-io.rst66
-rw-r--r--Documentation/translations/zh_CN/core-api/idr.rst80
-rw-r--r--Documentation/translations/zh_CN/core-api/index.rst148
-rw-r--r--Documentation/translations/zh_CN/core-api/irq/concepts.rst26
-rw-r--r--Documentation/translations/zh_CN/core-api/irq/index.rst22
-rw-r--r--Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst78
-rw-r--r--Documentation/translations/zh_CN/core-api/irq/irq-domain.rst237
-rw-r--r--Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst47
-rw-r--r--Documentation/translations/zh_CN/core-api/kernel-api.rst378
-rw-r--r--Documentation/translations/zh_CN/core-api/kobject.rst379
-rw-r--r--Documentation/translations/zh_CN/core-api/kref.rst311
-rw-r--r--Documentation/translations/zh_CN/core-api/local_ops.rst196
-rw-r--r--Documentation/translations/zh_CN/core-api/memory-allocation.rst138
-rw-r--r--Documentation/translations/zh_CN/core-api/memory-hotplug.rst119
-rw-r--r--Documentation/translations/zh_CN/core-api/mm-api.rst131
-rw-r--r--Documentation/translations/zh_CN/core-api/packing.rst160
-rw-r--r--Documentation/translations/zh_CN/core-api/padata.rst161
-rw-r--r--Documentation/translations/zh_CN/core-api/printk-basics.rst111
-rw-r--r--Documentation/translations/zh_CN/core-api/printk-formats.rst597
-rw-r--r--Documentation/translations/zh_CN/core-api/protection-keys.rst99
-rw-r--r--Documentation/translations/zh_CN/core-api/rbtree.rst391
-rw-r--r--Documentation/translations/zh_CN/core-api/refcount-vs-atomic.rst156
-rw-r--r--Documentation/translations/zh_CN/core-api/symbol-namespaces.rst133
-rw-r--r--Documentation/translations/zh_CN/core-api/this_cpu_ops.rst285
-rw-r--r--Documentation/translations/zh_CN/core-api/unaligned-memory-access.rst229
-rw-r--r--Documentation/translations/zh_CN/core-api/union_find.rst92
-rw-r--r--Documentation/translations/zh_CN/core-api/watch_queue.rst313
-rw-r--r--Documentation/translations/zh_CN/core-api/workqueue.rst696
-rw-r--r--Documentation/translations/zh_CN/core-api/xarray.rst373
-rw-r--r--Documentation/translations/zh_CN/cpu-freq/core.rst109
-rw-r--r--Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst256
-rw-r--r--Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst133
-rw-r--r--Documentation/translations/zh_CN/cpu-freq/index.rst47
-rw-r--r--Documentation/translations/zh_CN/dev-tools/gcov.rst264
-rw-r--r--Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst167
-rw-r--r--Documentation/translations/zh_CN/dev-tools/index.rst41
-rw-r--r--Documentation/translations/zh_CN/dev-tools/kasan.rst476
-rw-r--r--Documentation/translations/zh_CN/dev-tools/kcov.rst359
-rw-r--r--Documentation/translations/zh_CN/dev-tools/kcsan.rst320
-rw-r--r--Documentation/translations/zh_CN/dev-tools/kmemleak.rst229
-rw-r--r--Documentation/translations/zh_CN/dev-tools/kmsan.rst392
-rw-r--r--Documentation/translations/zh_CN/dev-tools/sparse.rst110
-rw-r--r--Documentation/translations/zh_CN/dev-tools/testing-overview.rst163
-rw-r--r--Documentation/translations/zh_CN/dev-tools/ubsan.rst88
-rw-r--r--Documentation/translations/zh_CN/devicetree/changesets.rst37
-rw-r--r--Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst31
-rw-r--r--Documentation/translations/zh_CN/devicetree/index.rst45
-rw-r--r--Documentation/translations/zh_CN/devicetree/kernel-api.rst58
-rw-r--r--Documentation/translations/zh_CN/devicetree/of_unittest.rst189
-rw-r--r--Documentation/translations/zh_CN/devicetree/overlay-notes.rst140
-rw-r--r--Documentation/translations/zh_CN/devicetree/usage-model.rst330
-rw-r--r--Documentation/translations/zh_CN/disclaimer-zh_CN.rst7
-rw-r--r--Documentation/translations/zh_CN/doc-guide/checktransupdate.rst55
-rw-r--r--Documentation/translations/zh_CN/doc-guide/contributing.rst238
-rw-r--r--Documentation/translations/zh_CN/doc-guide/index.rst28
-rw-r--r--Documentation/translations/zh_CN/doc-guide/kernel-doc.rst499
-rw-r--r--Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst43
-rw-r--r--Documentation/translations/zh_CN/doc-guide/parse-headers.rst187
-rw-r--r--Documentation/translations/zh_CN/doc-guide/sphinx.rst412
-rw-r--r--Documentation/translations/zh_CN/driver-api/gpio/index.rst66
-rw-r--r--Documentation/translations/zh_CN/driver-api/index.rst129
-rw-r--r--Documentation/translations/zh_CN/driver-api/io_ordering.rst60
-rw-r--r--Documentation/translations/zh_CN/driver-api/phy/index.rst20
-rw-r--r--Documentation/translations/zh_CN/driver-api/phy/phy.rst212
-rw-r--r--Documentation/translations/zh_CN/filesystems/debugfs.rst221
-rw-r--r--Documentation/translations/zh_CN/filesystems/dnotify.rst67
-rw-r--r--Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst211
-rw-r--r--Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst97
-rw-r--r--Documentation/translations/zh_CN/filesystems/gfs2.rst57
-rw-r--r--Documentation/translations/zh_CN/filesystems/index.rst44
-rw-r--r--Documentation/translations/zh_CN/filesystems/inotify.rst80
-rw-r--r--Documentation/translations/zh_CN/filesystems/sysfs.txt373
-rw-r--r--Documentation/translations/zh_CN/filesystems/tmpfs.rst146
-rw-r--r--Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst354
-rw-r--r--Documentation/translations/zh_CN/filesystems/ubifs.rst114
-rw-r--r--Documentation/translations/zh_CN/filesystems/virtiofs.rst58
-rw-r--r--Documentation/translations/zh_CN/glossary.rst37
-rw-r--r--Documentation/translations/zh_CN/how-to.rst473
-rw-r--r--Documentation/translations/zh_CN/iio/ep93xx_adc.rst48
-rw-r--r--Documentation/translations/zh_CN/iio/iio_configfs.rst106
-rw-r--r--Documentation/translations/zh_CN/iio/index.rst22
-rw-r--r--Documentation/translations/zh_CN/index.rst155
-rw-r--r--Documentation/translations/zh_CN/infiniband/core_locking.rst115
-rw-r--r--Documentation/translations/zh_CN/infiniband/index.rst40
-rw-r--r--Documentation/translations/zh_CN/infiniband/ipoib.rst111
-rw-r--r--Documentation/translations/zh_CN/infiniband/opa_vnic.rst156
-rw-r--r--Documentation/translations/zh_CN/infiniband/sysfs.rst21
-rw-r--r--Documentation/translations/zh_CN/infiniband/tag_matching.rst63
-rw-r--r--Documentation/translations/zh_CN/infiniband/user_mad.rst164
-rw-r--r--Documentation/translations/zh_CN/infiniband/user_verbs.rst72
-rw-r--r--Documentation/translations/zh_CN/kbuild/gcc-plugins.rst126
-rw-r--r--Documentation/translations/zh_CN/kbuild/headers_install.rst39
-rw-r--r--Documentation/translations/zh_CN/kbuild/index.rst36
-rw-r--r--Documentation/translations/zh_CN/kbuild/kbuild.rst325
-rw-r--r--Documentation/translations/zh_CN/kbuild/kconfig.rst259
-rw-r--r--Documentation/translations/zh_CN/kbuild/llvm.rst203
-rw-r--r--Documentation/translations/zh_CN/kbuild/reproducible-builds.rst114
-rw-r--r--Documentation/translations/zh_CN/kernel-hacking/hacking.rst707
-rw-r--r--Documentation/translations/zh_CN/kernel-hacking/index.rst22
-rw-r--r--Documentation/translations/zh_CN/locking/index.rst43
-rw-r--r--Documentation/translations/zh_CN/locking/mutex-design.rst145
-rw-r--r--Documentation/translations/zh_CN/locking/spinlocks.rst149
-rw-r--r--Documentation/translations/zh_CN/maintainer/configure-git.rst62
-rw-r--r--Documentation/translations/zh_CN/maintainer/index.rst21
-rw-r--r--Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst92
-rw-r--r--Documentation/translations/zh_CN/maintainer/modifying-patches.rst51
-rw-r--r--Documentation/translations/zh_CN/maintainer/pull-requests.rst148
-rw-r--r--Documentation/translations/zh_CN/maintainer/rebasing-and-merging.rst165
-rw-r--r--Documentation/translations/zh_CN/mm/active_mm.rst90
-rw-r--r--Documentation/translations/zh_CN/mm/balance.rst81
-rw-r--r--Documentation/translations/zh_CN/mm/damon/api.rst32
-rw-r--r--Documentation/translations/zh_CN/mm/damon/design.rst140
-rw-r--r--Documentation/translations/zh_CN/mm/damon/faq.rst31
-rw-r--r--Documentation/translations/zh_CN/mm/damon/index.rst32
-rw-r--r--Documentation/translations/zh_CN/mm/free_page_reporting.rst38
-rw-r--r--Documentation/translations/zh_CN/mm/highmem.rst151
-rw-r--r--Documentation/translations/zh_CN/mm/hmm.rst355
-rw-r--r--Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst437
-rw-r--r--Documentation/translations/zh_CN/mm/hwpoison.rst166
-rw-r--r--Documentation/translations/zh_CN/mm/index.rst69
-rw-r--r--Documentation/translations/zh_CN/mm/ksm.rst70
-rw-r--r--Documentation/translations/zh_CN/mm/memory-model.rst135
-rw-r--r--Documentation/translations/zh_CN/mm/mmu_notifier.rst97
-rw-r--r--Documentation/translations/zh_CN/mm/numa.rst101
-rw-r--r--Documentation/translations/zh_CN/mm/overcommit-accounting.rst85
-rw-r--r--Documentation/translations/zh_CN/mm/page_frags.rst38
-rw-r--r--Documentation/translations/zh_CN/mm/page_migration.rst228
-rw-r--r--Documentation/translations/zh_CN/mm/page_owner.rst216
-rw-r--r--Documentation/translations/zh_CN/mm/page_table_check.rst69
-rw-r--r--Documentation/translations/zh_CN/mm/page_tables.rst221
-rw-r--r--Documentation/translations/zh_CN/mm/physical_memory.rst356
-rw-r--r--Documentation/translations/zh_CN/mm/remap_file_pages.rst32
-rw-r--r--Documentation/translations/zh_CN/mm/split_page_table_lock.rst96
-rw-r--r--Documentation/translations/zh_CN/mm/vmalloced-kernel-stacks.rst133
-rw-r--r--Documentation/translations/zh_CN/mm/zsmalloc.rst78
-rw-r--r--Documentation/translations/zh_CN/networking/alias.rst56
-rw-r--r--Documentation/translations/zh_CN/networking/generic-hdlc.rst176
-rw-r--r--Documentation/translations/zh_CN/networking/index.rst159
-rw-r--r--Documentation/translations/zh_CN/networking/mptcp-sysctl.rst139
-rw-r--r--Documentation/translations/zh_CN/networking/msg_zerocopy.rst223
-rw-r--r--Documentation/translations/zh_CN/networking/napi.rst362
-rw-r--r--Documentation/translations/zh_CN/networking/netif-msg.rst92
-rw-r--r--Documentation/translations/zh_CN/networking/netmem.rst92
-rw-r--r--Documentation/translations/zh_CN/networking/timestamping.rst674
-rw-r--r--Documentation/translations/zh_CN/networking/vxlan.rst85
-rw-r--r--Documentation/translations/zh_CN/networking/xfrm_proc.rst126
-rw-r--r--Documentation/translations/zh_CN/peci/index.rst26
-rw-r--r--Documentation/translations/zh_CN/peci/peci.rst54
-rw-r--r--Documentation/translations/zh_CN/power/energy-model.rst210
-rw-r--r--Documentation/translations/zh_CN/power/index.rst56
-rw-r--r--Documentation/translations/zh_CN/power/opp.rst341
-rw-r--r--Documentation/translations/zh_CN/process/1.Intro.rst195
-rw-r--r--Documentation/translations/zh_CN/process/2.Process.rst364
-rw-r--r--Documentation/translations/zh_CN/process/3.Early-stage.rst168
-rw-r--r--Documentation/translations/zh_CN/process/4.Coding.rst293
-rw-r--r--Documentation/translations/zh_CN/process/5.Posting.rst253
-rw-r--r--Documentation/translations/zh_CN/process/6.Followthrough.rst157
-rw-r--r--Documentation/translations/zh_CN/process/7.AdvancedTopics.rst147
-rw-r--r--Documentation/translations/zh_CN/process/8.Conclusion.rst69
-rw-r--r--Documentation/translations/zh_CN/process/code-of-conduct-interpretation.rst108
-rw-r--r--Documentation/translations/zh_CN/process/code-of-conduct.rst72
-rw-r--r--Documentation/translations/zh_CN/process/coding-style.rst1072
-rw-r--r--Documentation/translations/zh_CN/process/cve.rst89
-rw-r--r--Documentation/translations/zh_CN/process/development-process.rst25
-rw-r--r--Documentation/translations/zh_CN/process/email-clients.rst334
-rw-r--r--Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst228
-rw-r--r--Documentation/translations/zh_CN/process/howto.rst495
-rw-r--r--Documentation/translations/zh_CN/process/index.rst102
-rw-r--r--Documentation/translations/zh_CN/process/kernel-driver-statement.rst199
-rw-r--r--Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst151
-rw-r--r--Documentation/translations/zh_CN/process/license-rules.rst370
-rw-r--r--Documentation/translations/zh_CN/process/magic-number.rst82
-rw-r--r--Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst789
-rw-r--r--Documentation/translations/zh_CN/process/management-style.rst207
-rw-r--r--Documentation/translations/zh_CN/process/programming-language.rst53
-rw-r--r--Documentation/translations/zh_CN/process/researcher-guidelines.rst129
-rw-r--r--Documentation/translations/zh_CN/process/security-bugs.rst84
-rw-r--r--Documentation/translations/zh_CN/process/stable-api-nonsense.rst155
-rw-r--r--Documentation/translations/zh_CN/process/stable-kernel-rules.rst64
-rw-r--r--Documentation/translations/zh_CN/process/submit-checklist.rst110
-rw-r--r--Documentation/translations/zh_CN/process/submitting-patches.rst658
-rw-r--r--Documentation/translations/zh_CN/process/volatile-considered-harmful.rst106
-rw-r--r--Documentation/translations/zh_CN/rust/arch-support.rst27
-rw-r--r--Documentation/translations/zh_CN/rust/coding-guidelines.rst204
-rw-r--r--Documentation/translations/zh_CN/rust/general-information.rst76
-rw-r--r--Documentation/translations/zh_CN/rust/index.rst59
-rw-r--r--Documentation/translations/zh_CN/rust/quick-start.rst229
-rw-r--r--Documentation/translations/zh_CN/rust/testing.rst215
-rw-r--r--Documentation/translations/zh_CN/scheduler/completion.rst256
-rw-r--r--Documentation/translations/zh_CN/scheduler/index.rst45
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-arch.rst71
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-bwc.rst204
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-capacity.rst390
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-debug.rst51
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst205
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-domains.rst72
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-energy.rst351
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-nice-design.rst99
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-stats.rst156
-rw-r--r--Documentation/translations/zh_CN/scheduler/schedutil.rst164
-rw-r--r--Documentation/translations/zh_CN/scsi/index.rst92
-rw-r--r--Documentation/translations/zh_CN/scsi/libsas.rst425
-rw-r--r--Documentation/translations/zh_CN/scsi/link_power_management_policy.rst32
-rw-r--r--Documentation/translations/zh_CN/scsi/scsi-parameters.rst118
-rw-r--r--Documentation/translations/zh_CN/scsi/scsi.rst48
-rw-r--r--Documentation/translations/zh_CN/scsi/scsi_eh.rst482
-rw-r--r--Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst1174
-rw-r--r--Documentation/translations/zh_CN/scsi/sd-parameters.rst38
-rw-r--r--Documentation/translations/zh_CN/scsi/wd719x.rst35
-rw-r--r--Documentation/translations/zh_CN/security/IMA-templates.rst97
-rw-r--r--Documentation/translations/zh_CN/security/SCTP.rst317
-rw-r--r--Documentation/translations/zh_CN/security/credentials.rst479
-rw-r--r--Documentation/translations/zh_CN/security/digsig.rst103
-rw-r--r--Documentation/translations/zh_CN/security/index.rst34
-rw-r--r--Documentation/translations/zh_CN/security/ipe.rst398
-rw-r--r--Documentation/translations/zh_CN/security/keys/index.rst22
-rw-r--r--Documentation/translations/zh_CN/security/landlock.rst123
-rw-r--r--Documentation/translations/zh_CN/security/lsm-development.rst19
-rw-r--r--Documentation/translations/zh_CN/security/lsm.rst95
-rw-r--r--Documentation/translations/zh_CN/security/sak.rst86
-rw-r--r--Documentation/translations/zh_CN/security/secrets/coco.rst96
-rw-r--r--Documentation/translations/zh_CN/security/secrets/index.rst14
-rw-r--r--Documentation/translations/zh_CN/security/self-protection.rst271
-rw-r--r--Documentation/translations/zh_CN/security/siphash.rst195
-rw-r--r--Documentation/translations/zh_CN/security/snp-tdx-threat-model.rst209
-rw-r--r--Documentation/translations/zh_CN/security/tpm/index.rst20
-rw-r--r--Documentation/translations/zh_CN/security/tpm/tpm-security.rst151
-rw-r--r--Documentation/translations/zh_CN/security/tpm/tpm_event_log.rst49
-rw-r--r--Documentation/translations/zh_CN/security/tpm/tpm_ftpm_tee.rst31
-rw-r--r--Documentation/translations/zh_CN/security/tpm/tpm_tis.rst43
-rw-r--r--Documentation/translations/zh_CN/security/tpm/tpm_vtpm_proxy.rst51
-rw-r--r--Documentation/translations/zh_CN/security/tpm/xen-tpmfront.rst114
-rw-r--r--Documentation/translations/zh_CN/sound/hd-audio/controls.rst102
-rw-r--r--Documentation/translations/zh_CN/sound/hd-audio/index.rst14
-rw-r--r--Documentation/translations/zh_CN/sound/index.rst22
-rw-r--r--Documentation/translations/zh_CN/staging/index.rst26
-rw-r--r--Documentation/translations/zh_CN/staging/speculation.rst85
-rw-r--r--Documentation/translations/zh_CN/staging/xz.rst100
-rw-r--r--Documentation/translations/zh_CN/subsystem-apis.rst109
-rw-r--r--Documentation/translations/zh_CN/userspace-api/accelerators/ocxl.rst168
-rw-r--r--Documentation/translations/zh_CN/userspace-api/ebpf/index.rst22
-rw-r--r--Documentation/translations/zh_CN/userspace-api/ebpf/syscall.rst29
-rw-r--r--Documentation/translations/zh_CN/userspace-api/futex2.rst80
-rw-r--r--Documentation/translations/zh_CN/userspace-api/index.rst47
-rw-r--r--Documentation/translations/zh_CN/userspace-api/no_new_privs.rst57
-rw-r--r--Documentation/translations/zh_CN/userspace-api/seccomp_filter.rst293
-rw-r--r--Documentation/translations/zh_CN/userspace-api/sysfs-platform_profile.rst40
-rw-r--r--Documentation/translations/zh_CN/video4linux/omap3isp.txt277
-rw-r--r--Documentation/translations/zh_CN/video4linux/v4l2-framework.txt958
-rw-r--r--Documentation/translations/zh_CN/virt/acrn/cpuid.rst56
-rw-r--r--Documentation/translations/zh_CN/virt/acrn/index.rst25
-rw-r--r--Documentation/translations/zh_CN/virt/acrn/introduction.rst52
-rw-r--r--Documentation/translations/zh_CN/virt/acrn/io-request.rst99
-rw-r--r--Documentation/translations/zh_CN/virt/guest-halt-polling.rst87
-rw-r--r--Documentation/translations/zh_CN/virt/index.rst38
-rw-r--r--Documentation/translations/zh_CN/virt/ne_overview.rst88
-rw-r--r--Documentation/translations/zh_CN/virt/paravirt_ops.rst41
-rw-r--r--Documentation/translations/zh_TW/IRQ.txt41
-rw-r--r--Documentation/translations/zh_TW/admin-guide/README.rst295
-rw-r--r--Documentation/translations/zh_TW/admin-guide/bootconfig.rst294
-rw-r--r--Documentation/translations/zh_TW/admin-guide/bug-bisect.rst85
-rw-r--r--Documentation/translations/zh_TW/admin-guide/bug-hunting.rst334
-rw-r--r--Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst16
-rw-r--r--Documentation/translations/zh_TW/admin-guide/cpu-load.rst112
-rw-r--r--Documentation/translations/zh_TW/admin-guide/cputopology.rst97
-rw-r--r--Documentation/translations/zh_TW/admin-guide/index.rst136
-rw-r--r--Documentation/translations/zh_TW/admin-guide/init.rst58
-rw-r--r--Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst67
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst30
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst264
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst229
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst125
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst346
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/index.rst50
-rw-r--r--Documentation/translations/zh_TW/admin-guide/mm/ksm.rst199
-rw-r--r--Documentation/translations/zh_TW/admin-guide/reporting-issues.rst1370
-rw-r--r--Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst371
-rw-r--r--Documentation/translations/zh_TW/admin-guide/security-bugs.rst78
-rw-r--r--Documentation/translations/zh_TW/admin-guide/sysrq.rst281
-rw-r--r--Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst161
-rw-r--r--Documentation/translations/zh_TW/admin-guide/unicode.rst174
-rw-r--r--Documentation/translations/zh_TW/arch/arm/Booting176
-rw-r--r--Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt285
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/amu.rst104
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/booting.txt251
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst244
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/hugetlbpage.rst49
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/index.rst23
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt77
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/memory.txt119
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/perf.rst88
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt79
-rw-r--r--Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt57
-rw-r--r--Documentation/translations/zh_TW/arch/index.rst29
-rw-r--r--Documentation/translations/zh_TW/arch/loongarch/booting.rst49
-rw-r--r--Documentation/translations/zh_TW/arch/loongarch/features.rst9
-rw-r--r--Documentation/translations/zh_TW/arch/loongarch/index.rst28
-rw-r--r--Documentation/translations/zh_TW/arch/loongarch/introduction.rst354
-rw-r--r--Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst158
-rw-r--r--Documentation/translations/zh_TW/arch/mips/booting.rst35
-rw-r--r--Documentation/translations/zh_TW/arch/mips/features.rst14
-rw-r--r--Documentation/translations/zh_TW/arch/mips/index.rst30
-rw-r--r--Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst73
-rw-r--r--Documentation/translations/zh_TW/arch/openrisc/index.rst33
-rw-r--r--Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst128
-rw-r--r--Documentation/translations/zh_TW/arch/openrisc/todo.rst24
-rw-r--r--Documentation/translations/zh_TW/arch/parisc/debugging.rst46
-rw-r--r--Documentation/translations/zh_TW/arch/parisc/index.rst32
-rw-r--r--Documentation/translations/zh_TW/arch/parisc/registers.rst157
-rw-r--r--Documentation/translations/zh_TW/cpu-freq/core.rst110
-rw-r--r--Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst257
-rw-r--r--Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst134
-rw-r--r--Documentation/translations/zh_TW/cpu-freq/index.rst48
-rw-r--r--Documentation/translations/zh_TW/dev-tools/gcov.rst265
-rw-r--r--Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst164
-rw-r--r--Documentation/translations/zh_TW/dev-tools/index.rst43
-rw-r--r--Documentation/translations/zh_TW/dev-tools/kasan.rst460
-rw-r--r--Documentation/translations/zh_TW/dev-tools/sparse.rst91
-rw-r--r--Documentation/translations/zh_TW/dev-tools/testing-overview.rst162
-rw-r--r--Documentation/translations/zh_TW/disclaimer-zh_TW.rst11
-rw-r--r--Documentation/translations/zh_TW/filesystems/debugfs.rst223
-rw-r--r--Documentation/translations/zh_TW/filesystems/index.rst31
-rw-r--r--Documentation/translations/zh_TW/filesystems/sysfs.txt377
-rw-r--r--Documentation/translations/zh_TW/filesystems/tmpfs.rst147
-rw-r--r--Documentation/translations/zh_TW/filesystems/virtiofs.rst60
-rw-r--r--Documentation/translations/zh_TW/index.rst134
-rw-r--r--Documentation/translations/zh_TW/io_ordering.txt68
-rw-r--r--Documentation/translations/zh_TW/process/1.Intro.rst199
-rw-r--r--Documentation/translations/zh_TW/process/2.Process.rst369
-rw-r--r--Documentation/translations/zh_TW/process/3.Early-stage.rst172
-rw-r--r--Documentation/translations/zh_TW/process/4.Coding.rst297
-rw-r--r--Documentation/translations/zh_TW/process/5.Posting.rst246
-rw-r--r--Documentation/translations/zh_TW/process/6.Followthrough.rst156
-rw-r--r--Documentation/translations/zh_TW/process/7.AdvancedTopics.rst137
-rw-r--r--Documentation/translations/zh_TW/process/8.Conclusion.rst73
-rw-r--r--Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst112
-rw-r--r--Documentation/translations/zh_TW/process/code-of-conduct.rst76
-rw-r--r--Documentation/translations/zh_TW/process/coding-style.rst1087
-rw-r--r--Documentation/translations/zh_TW/process/development-process.rst30
-rw-r--r--Documentation/translations/zh_TW/process/email-clients.rst329
-rw-r--r--Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst232
-rw-r--r--Documentation/translations/zh_TW/process/howto.rst499
-rw-r--r--Documentation/translations/zh_TW/process/index.rst67
-rw-r--r--Documentation/translations/zh_TW/process/kernel-driver-statement.rst203
-rw-r--r--Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst155
-rw-r--r--Documentation/translations/zh_TW/process/license-rules.rst372
-rw-r--r--Documentation/translations/zh_TW/process/magic-number.rst76
-rw-r--r--Documentation/translations/zh_TW/process/management-style.rst211
-rw-r--r--Documentation/translations/zh_TW/process/programming-language.rst75
-rw-r--r--Documentation/translations/zh_TW/process/stable-api-nonsense.rst159
-rw-r--r--Documentation/translations/zh_TW/process/stable-kernel-rules.rst68
-rw-r--r--Documentation/translations/zh_TW/process/submit-checklist.rst114
-rw-r--r--Documentation/translations/zh_TW/process/submitting-patches.rst659
-rw-r--r--Documentation/translations/zh_TW/process/volatile-considered-harmful.rst110
-rw-r--r--Documentation/unaligned-memory-access.txt262
-rw-r--r--Documentation/unicode.txt175
-rw-r--r--Documentation/unshare.txt295
-rw-r--r--Documentation/usb/CREDITS8
-rw-r--r--Documentation/usb/URB.txt261
-rw-r--r--Documentation/usb/WUSB-Design-overview.txt439
-rw-r--r--Documentation/usb/acm.rst132
-rw-r--r--Documentation/usb/acm.txt128
-rw-r--r--Documentation/usb/anchors.txt79
-rw-r--r--Documentation/usb/authorization.rst129
-rw-r--r--Documentation/usb/authorization.txt92
-rw-r--r--Documentation/usb/bulk-streams.txt78
-rw-r--r--Documentation/usb/callbacks.txt134
-rw-r--r--Documentation/usb/chipidea.rst134
-rw-r--r--Documentation/usb/chipidea.txt92
-rw-r--r--Documentation/usb/dma.txt133
-rw-r--r--Documentation/usb/dwc3.rst53
-rw-r--r--Documentation/usb/dwc3.txt45
-rw-r--r--Documentation/usb/ehci.rst230
-rw-r--r--Documentation/usb/ehci.txt214
-rw-r--r--Documentation/usb/error-codes.txt175
-rw-r--r--Documentation/usb/functionfs-desc.rst39
-rw-r--r--Documentation/usb/functionfs.rst106
-rw-r--r--Documentation/usb/functionfs.txt67
-rw-r--r--Documentation/usb/gadget-testing.rst1152
-rw-r--r--Documentation/usb/gadget-testing.txt775
-rw-r--r--Documentation/usb/gadget_configfs.rst399
-rw-r--r--Documentation/usb/gadget_configfs.txt384
-rw-r--r--Documentation/usb/gadget_hid.rst457
-rw-r--r--Documentation/usb/gadget_hid.txt452
-rw-r--r--Documentation/usb/gadget_multi.rst165
-rw-r--r--Documentation/usb/gadget_multi.txt150
-rw-r--r--Documentation/usb/gadget_printer.rst523
-rw-r--r--Documentation/usb/gadget_printer.txt510
-rw-r--r--Documentation/usb/gadget_serial.rst289
-rw-r--r--Documentation/usb/gadget_serial.txt286
-rw-r--r--Documentation/usb/gadget_uvc.rst380
-rw-r--r--Documentation/usb/hotplug.txt148
-rw-r--r--Documentation/usb/index.rst40
-rw-r--r--Documentation/usb/iuu_phoenix.rst94
-rw-r--r--Documentation/usb/iuu_phoenix.txt84
-rw-r--r--Documentation/usb/linux.inf2
-rw-r--r--Documentation/usb/mass-storage.rst243
-rw-r--r--Documentation/usb/mass-storage.txt225
-rw-r--r--Documentation/usb/misc_usbsevseg.rst51
-rw-r--r--Documentation/usb/misc_usbsevseg.txt46
-rw-r--r--Documentation/usb/mtouchusb.rst84
-rw-r--r--Documentation/usb/mtouchusb.txt72
-rw-r--r--Documentation/usb/ohci.rst35
-rw-r--r--Documentation/usb/ohci.txt32
-rw-r--r--Documentation/usb/persist.txt165
-rw-r--r--Documentation/usb/power-management.txt760
-rw-r--r--Documentation/usb/proc_usb_info.txt390
-rw-r--r--Documentation/usb/raw-gadget.rst91
-rw-r--r--Documentation/usb/rio.txt138
-rw-r--r--Documentation/usb/text_files.rst23
-rw-r--r--Documentation/usb/usb-help.rst17
-rw-r--r--Documentation/usb/usb-help.txt16
-rw-r--r--Documentation/usb/usb-serial.rst537
-rw-r--r--Documentation/usb/usb-serial.txt493
-rw-r--r--Documentation/usb/usbdevfs-drop-permissions.c120
-rw-r--r--Documentation/usb/usbip_protocol.rst452
-rw-r--r--Documentation/usb/usbmon.rst375
-rw-r--r--Documentation/usb/usbmon.txt355
-rw-r--r--Documentation/usb/wusb-cbaf130
-rw-r--r--Documentation/userspace-api/ELF.rst34
-rw-r--r--Documentation/userspace-api/accelerators/ocxl.rst179
-rw-r--r--Documentation/userspace-api/check_exec.rst144
-rw-r--r--Documentation/userspace-api/dcdbas.rst99
-rw-r--r--Documentation/userspace-api/dma-buf-alloc-exchange.rst389
-rw-r--r--Documentation/userspace-api/dma-buf-heaps.rst67
-rw-r--r--Documentation/userspace-api/ebpf/index.rst17
-rw-r--r--Documentation/userspace-api/ebpf/syscall.rst24
-rw-r--r--Documentation/userspace-api/futex2.rst86
-rw-r--r--Documentation/userspace-api/fwctl/fwctl-cxl.rst142
-rw-r--r--Documentation/userspace-api/fwctl/fwctl.rst286
-rw-r--r--Documentation/userspace-api/fwctl/index.rst14
-rw-r--r--Documentation/userspace-api/fwctl/pds_fwctl.rst46
-rw-r--r--Documentation/userspace-api/gpio/chardev.rst116
-rw-r--r--Documentation/userspace-api/gpio/chardev_v1.rst131
-rw-r--r--Documentation/userspace-api/gpio/error-codes.rst79
-rw-r--r--Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst41
-rw-r--r--Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst84
-rw-r--r--Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst125
-rw-r--r--Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst54
-rw-r--r--Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst49
-rw-r--r--Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst74
-rw-r--r--Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst63
-rw-r--r--Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst66
-rw-r--r--Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst55
-rw-r--r--Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst89
-rw-r--r--Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst87
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst152
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst50
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst67
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst88
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst58
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst61
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst54
-rw-r--r--Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst81
-rw-r--r--Documentation/userspace-api/gpio/index.rst18
-rw-r--r--Documentation/userspace-api/gpio/obsolete.rst11
-rw-r--r--Documentation/userspace-api/gpio/sysfs.rst171
-rw-r--r--Documentation/userspace-api/index.rst77
-rw-r--r--Documentation/userspace-api/ioctl/cdrom.rst1242
-rw-r--r--Documentation/userspace-api/ioctl/hdio.rst547
-rw-r--r--Documentation/userspace-api/ioctl/index.rst15
-rw-r--r--Documentation/userspace-api/ioctl/ioctl-decoding.rst31
-rw-r--r--Documentation/userspace-api/ioctl/ioctl-number.rst416
-rw-r--r--Documentation/userspace-api/iommufd.rst384
-rw-r--r--Documentation/userspace-api/isapnp.rst15
-rw-r--r--Documentation/userspace-api/landlock.rst710
-rw-r--r--Documentation/userspace-api/liveupdate.rst20
-rw-r--r--Documentation/userspace-api/lsm.rst73
-rw-r--r--Documentation/userspace-api/media/cec/cec-api.rst41
-rw-r--r--Documentation/userspace-api/media/cec/cec-func-close.rst43
-rw-r--r--Documentation/userspace-api/media/cec/cec-func-ioctl.rst63
-rw-r--r--Documentation/userspace-api/media/cec/cec-func-open.rst74
-rw-r--r--Documentation/userspace-api/media/cec/cec-func-poll.rst74
-rw-r--r--Documentation/userspace-api/media/cec/cec-funcs.rst23
-rw-r--r--Documentation/userspace-api/media/cec/cec-header.rst13
-rw-r--r--Documentation/userspace-api/media/cec/cec-intro.rst42
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst152
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst106
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst367
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst94
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst245
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst294
-rw-r--r--Documentation/userspace-api/media/cec/cec-ioc-receive.rst400
-rw-r--r--Documentation/userspace-api/media/cec/cec-pin-error-inj.rst371
-rw-r--r--Documentation/userspace-api/media/cec/cec.h.rst.exceptions580
-rw-r--r--Documentation/userspace-api/media/conf_nitpick.py111
-rw-r--r--Documentation/userspace-api/media/drivers/aspeed-video.rst65
-rw-r--r--Documentation/userspace-api/media/drivers/camera-sensor.rst106
-rw-r--r--Documentation/userspace-api/media/drivers/ccs.rst114
-rw-r--r--Documentation/userspace-api/media/drivers/cx2341x-uapi.rst177
-rw-r--r--Documentation/userspace-api/media/drivers/dw100.rst84
-rw-r--r--Documentation/userspace-api/media/drivers/imx-uapi.rst125
-rw-r--r--Documentation/userspace-api/media/drivers/index.rst41
-rw-r--r--Documentation/userspace-api/media/drivers/mali-c55.rst55
-rw-r--r--Documentation/userspace-api/media/drivers/max2175.rst64
-rw-r--r--Documentation/userspace-api/media/drivers/npcm-video.rst66
-rw-r--r--Documentation/userspace-api/media/drivers/omap3isp-uapi.rst208
-rw-r--r--Documentation/userspace-api/media/drivers/thp7312.rst39
-rw-r--r--Documentation/userspace-api/media/drivers/uvcvideo.rst321
-rw-r--r--Documentation/userspace-api/media/drivers/vgxy61.rst25
-rw-r--r--Documentation/userspace-api/media/dvb/ca-fclose.rst40
-rw-r--r--Documentation/userspace-api/media/dvb/ca-fopen.rst72
-rw-r--r--Documentation/userspace-api/media/dvb/ca-get-cap.rst46
-rw-r--r--Documentation/userspace-api/media/dvb/ca-get-descr-info.rst43
-rw-r--r--Documentation/userspace-api/media/dvb/ca-get-msg.rst50
-rw-r--r--Documentation/userspace-api/media/dvb/ca-get-slot-info.rst56
-rw-r--r--Documentation/userspace-api/media/dvb/ca-reset.rst43
-rw-r--r--Documentation/userspace-api/media/dvb/ca-send-msg.rst50
-rw-r--r--Documentation/userspace-api/media/dvb/ca-set-descr.rst46
-rw-r--r--Documentation/userspace-api/media/dvb/ca.h.rst.exceptions25
-rw-r--r--Documentation/userspace-api/media/dvb/ca.rst25
-rw-r--r--Documentation/userspace-api/media/dvb/ca_data_types.rst9
-rw-r--r--Documentation/userspace-api/media/dvb/ca_function_calls.rst20
-rw-r--r--Documentation/userspace-api/media/dvb/ca_high_level.rst157
-rw-r--r--Documentation/userspace-api/media/dvb/demux.rst23
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-add-pid.rst47
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-expbuf.rst87
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-fclose.rst42
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-fopen.rst88
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-fread.rst77
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-fwrite.rst70
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst62
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-get-stc.rst64
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-mmap.rst115
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-munmap.rst52
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-qbuf.rst85
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-querybuf.rst64
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-remove-pid.rst48
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-reqbufs.rst75
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst48
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-set-filter.rst55
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst64
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-start.rst65
-rw-r--r--Documentation/userspace-api/media/dvb/dmx-stop.rst44
-rw-r--r--Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions62
-rw-r--r--Documentation/userspace-api/media/dvb/dmx_fcalls.rst30
-rw-r--r--Documentation/userspace-api/media/dvb/dmx_types.rst10
-rw-r--r--Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst25
-rw-r--r--Documentation/userspace-api/media/dvb/dvb-frontend-event.rst15
-rw-r--r--Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst119
-rw-r--r--Documentation/userspace-api/media/dvb/dvbapi.rst113
-rw-r--r--Documentation/userspace-api/media/dvb/dvbproperty.rst126
-rw-r--r--Documentation/userspace-api/media/dvb/dvbstb.svg17
-rw-r--r--Documentation/userspace-api/media/dvb/examples.rst16
-rw-r--r--Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst74
-rw-r--r--Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst47
-rw-r--r--Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst45
-rw-r--r--Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst50
-rw-r--r--Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst48
-rw-r--r--Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst53
-rw-r--r--Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst52
-rw-r--r--Documentation/userspace-api/media/dvb/fe-get-event.rst67
-rw-r--r--Documentation/userspace-api/media/dvb/fe-get-frontend.rst58
-rw-r--r--Documentation/userspace-api/media/dvb/fe-get-info.rst59
-rw-r--r--Documentation/userspace-api/media/dvb/fe-get-property.rst75
-rw-r--r--Documentation/userspace-api/media/dvb/fe-read-ber.rst49
-rw-r--r--Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst49
-rw-r--r--Documentation/userspace-api/media/dvb/fe-read-snr.rst49
-rw-r--r--Documentation/userspace-api/media/dvb/fe-read-status.rst62
-rw-r--r--Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst51
-rw-r--r--Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst55
-rw-r--r--Documentation/userspace-api/media/dvb/fe-set-frontend.rst68
-rw-r--r--Documentation/userspace-api/media/dvb/fe-set-tone.rst56
-rw-r--r--Documentation/userspace-api/media/dvb/fe-set-voltage.rst60
-rw-r--r--Documentation/userspace-api/media/dvb/fe-type-t.rst91
-rw-r--r--Documentation/userspace-api/media/dvb/fe_property_parameters.rst1013
-rw-r--r--Documentation/userspace-api/media/dvb/frontend-header.rst6
-rw-r--r--Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst75
-rw-r--r--Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst105
-rw-r--r--Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst294
-rw-r--r--Documentation/userspace-api/media/dvb/frontend-stat-properties.rst245
-rw-r--r--Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions247
-rw-r--r--Documentation/userspace-api/media/dvb/frontend.rst56
-rw-r--r--Documentation/userspace-api/media/dvb/frontend_f_close.rst46
-rw-r--r--Documentation/userspace-api/media/dvb/frontend_f_open.rst104
-rw-r--r--Documentation/userspace-api/media/dvb/frontend_fcalls.rst24
-rw-r--r--Documentation/userspace-api/media/dvb/frontend_legacy_api.rst38
-rw-r--r--Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst18
-rw-r--r--Documentation/userspace-api/media/dvb/headers.rst46
-rw-r--r--Documentation/userspace-api/media/dvb/intro.rst183
-rw-r--r--Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst26
-rw-r--r--Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst1642
-rw-r--r--Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst61
-rw-r--r--Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst883
-rw-r--r--Documentation/userspace-api/media/dvb/legacy_dvb_video.rst2430
-rw-r--r--Documentation/userspace-api/media/dvb/net-add-if.rst52
-rw-r--r--Documentation/userspace-api/media/dvb/net-get-if.rst50
-rw-r--r--Documentation/userspace-api/media/dvb/net-remove-if.rst46
-rw-r--r--Documentation/userspace-api/media/dvb/net-types.rst9
-rw-r--r--Documentation/userspace-api/media/dvb/net.h.rst.exceptions13
-rw-r--r--Documentation/userspace-api/media/dvb/net.rst41
-rw-r--r--Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst13
-rw-r--r--Documentation/userspace-api/media/fdl-appendix.rst471
-rw-r--r--Documentation/userspace-api/media/gen-errors.rst94
-rw-r--r--Documentation/userspace-api/media/glossary.rst217
-rw-r--r--Documentation/userspace-api/media/index.rst67
-rw-r--r--Documentation/userspace-api/media/intro.rst46
-rw-r--r--Documentation/userspace-api/media/mediactl/media-controller-intro.rst33
-rw-r--r--Documentation/userspace-api/media/mediactl/media-controller-model.rst41
-rw-r--r--Documentation/userspace-api/media/mediactl/media-controller.rst49
-rw-r--r--Documentation/userspace-api/media/mediactl/media-func-close.rst43
-rw-r--r--Documentation/userspace-api/media/mediactl/media-func-ioctl.rst63
-rw-r--r--Documentation/userspace-api/media/mediactl/media-func-open.rst65
-rw-r--r--Documentation/userspace-api/media/mediactl/media-funcs.rst26
-rw-r--r--Documentation/userspace-api/media/mediactl/media-header.rst13
-rw-r--r--Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst106
-rw-r--r--Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst146
-rw-r--r--Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst145
-rw-r--r--Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst294
-rw-r--r--Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst65
-rw-r--r--Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst65
-rw-r--r--Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst77
-rw-r--r--Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst51
-rw-r--r--Documentation/userspace-api/media/mediactl/media-types.rst431
-rw-r--r--Documentation/userspace-api/media/mediactl/media.h.rst.exceptions35
-rw-r--r--Documentation/userspace-api/media/mediactl/request-api.rst253
-rw-r--r--Documentation/userspace-api/media/mediactl/request-func-close.rst45
-rw-r--r--Documentation/userspace-api/media/mediactl/request-func-ioctl.rst63
-rw-r--r--Documentation/userspace-api/media/mediactl/request-func-poll.rst73
-rw-r--r--Documentation/userspace-api/media/rc/keytable.c.rst176
-rw-r--r--Documentation/userspace-api/media/rc/lirc-dev-intro.rst176
-rw-r--r--Documentation/userspace-api/media/rc/lirc-dev.rst14
-rw-r--r--Documentation/userspace-api/media/rc/lirc-func.rst26
-rw-r--r--Documentation/userspace-api/media/rc/lirc-get-features.rst174
-rw-r--r--Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst69
-rw-r--r--Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst47
-rw-r--r--Documentation/userspace-api/media/rc/lirc-get-send-mode.rst71
-rw-r--r--Documentation/userspace-api/media/rc/lirc-get-timeout.rst57
-rw-r--r--Documentation/userspace-api/media/rc/lirc-header.rst20
-rw-r--r--Documentation/userspace-api/media/rc/lirc-read.rst65
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst46
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst49
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst46
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst55
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst41
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst47
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst51
-rw-r--r--Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst56
-rw-r--r--Documentation/userspace-api/media/rc/lirc-write.rst72
-rw-r--r--Documentation/userspace-api/media/rc/lirc.h.rst.exceptions87
-rw-r--r--Documentation/userspace-api/media/rc/rc-intro.rst24
-rw-r--r--Documentation/userspace-api/media/rc/rc-protos.rst454
-rw-r--r--Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst144
-rw-r--r--Documentation/userspace-api/media/rc/rc-table-change.rst18
-rw-r--r--Documentation/userspace-api/media/rc/rc-tables.rst759
-rw-r--r--Documentation/userspace-api/media/rc/remote_controllers.rst46
-rw-r--r--Documentation/userspace-api/media/typical_media_device.svg107
-rw-r--r--Documentation/userspace-api/media/v4l/app-pri.rst31
-rw-r--r--Documentation/userspace-api/media/v4l/audio.rst98
-rw-r--r--Documentation/userspace-api/media/v4l/bayer.svg30
-rw-r--r--Documentation/userspace-api/media/v4l/biblio.rst450
-rw-r--r--Documentation/userspace-api/media/v4l/buffer.rst803
-rw-r--r--Documentation/userspace-api/media/v4l/capture-example.rst14
-rw-r--r--Documentation/userspace-api/media/v4l/capture.c.rst665
-rw-r--r--Documentation/userspace-api/media/v4l/colorspaces-defs.rst176
-rw-r--r--Documentation/userspace-api/media/v4l/colorspaces-details.rst776
-rw-r--r--Documentation/userspace-api/media/v4l/colorspaces.rst164
-rw-r--r--Documentation/userspace-api/media/v4l/common-defs.rst14
-rw-r--r--Documentation/userspace-api/media/v4l/common.rst61
-rw-r--r--Documentation/userspace-api/media/v4l/compat.rst19
-rw-r--r--Documentation/userspace-api/media/v4l/constraints.svg11
-rw-r--r--Documentation/userspace-api/media/v4l/control.rst524
-rw-r--r--Documentation/userspace-api/media/v4l/crop.rst318
-rw-r--r--Documentation/userspace-api/media/v4l/crop.svg281
-rw-r--r--Documentation/userspace-api/media/v4l/depth-formats.rst18
-rw-r--r--Documentation/userspace-api/media/v4l/dev-capture.rst101
-rw-r--r--Documentation/userspace-api/media/v4l/dev-decoder.rst1128
-rw-r--r--Documentation/userspace-api/media/v4l/dev-encoder.rst730
-rw-r--r--Documentation/userspace-api/media/v4l/dev-event.rst48
-rw-r--r--Documentation/userspace-api/media/v4l/dev-mem2mem.rst44
-rw-r--r--Documentation/userspace-api/media/v4l/dev-meta.rst89
-rw-r--r--Documentation/userspace-api/media/v4l/dev-osd.rst151
-rw-r--r--Documentation/userspace-api/media/v4l/dev-output.rst98
-rw-r--r--Documentation/userspace-api/media/v4l/dev-overlay.rst327
-rw-r--r--Documentation/userspace-api/media/v4l/dev-radio.rst53
-rw-r--r--Documentation/userspace-api/media/v4l/dev-raw-vbi.rst292
-rw-r--r--Documentation/userspace-api/media/v4l/dev-rds.rst176
-rw-r--r--Documentation/userspace-api/media/v4l/dev-sdr.rst108
-rw-r--r--Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst661
-rw-r--r--Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst425
-rw-r--r--Documentation/userspace-api/media/v4l/dev-subdev.rst694
-rw-r--r--Documentation/userspace-api/media/v4l/dev-touch.rst57
-rw-r--r--Documentation/userspace-api/media/v4l/devices.rst27
-rw-r--r--Documentation/userspace-api/media/v4l/diff-v4l.rst667
-rw-r--r--Documentation/userspace-api/media/v4l/dmabuf.rst162
-rw-r--r--Documentation/userspace-api/media/v4l/dv-timings.rst60
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst675
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst4169
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst2675
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst94
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst65
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst160
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst189
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst84
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst175
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst58
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst95
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst106
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst90
-rw-r--r--Documentation/userspace-api/media/v4l/extended-controls.rst174
-rw-r--r--Documentation/userspace-api/media/v4l/field-order.rst166
-rw-r--r--Documentation/userspace-api/media/v4l/fieldseq_bt.svg2612
-rw-r--r--Documentation/userspace-api/media/v4l/fieldseq_tb.svg2609
-rw-r--r--Documentation/userspace-api/media/v4l/format.rst91
-rw-r--r--Documentation/userspace-api/media/v4l/fourcc.rst33
-rw-r--r--Documentation/userspace-api/media/v4l/func-close.rst45
-rw-r--r--Documentation/userspace-api/media/v4l/func-ioctl.rst58
-rw-r--r--Documentation/userspace-api/media/v4l/func-mmap.rst137
-rw-r--r--Documentation/userspace-api/media/v4l/func-munmap.rst54
-rw-r--r--Documentation/userspace-api/media/v4l/func-open.rst79
-rw-r--r--Documentation/userspace-api/media/v4l/func-poll.rst113
-rw-r--r--Documentation/userspace-api/media/v4l/func-read.rst130
-rw-r--r--Documentation/userspace-api/media/v4l/func-select.rst116
-rw-r--r--Documentation/userspace-api/media/v4l/func-write.rst81
-rw-r--r--Documentation/userspace-api/media/v4l/hist-v4l2.rst1276
-rw-r--r--Documentation/userspace-api/media/v4l/hsv-formats.rst20
-rw-r--r--Documentation/userspace-api/media/v4l/io.rst49
-rw-r--r--Documentation/userspace-api/media/v4l/libv4l-introduction.rst180
-rw-r--r--Documentation/userspace-api/media/v4l/libv4l.rst14
-rw-r--r--Documentation/userspace-api/media/v4l/meta-formats.rst29
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-arm-mali-c55.rst84
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst87
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-d4xx.rst253
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-generic.rst341
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst82
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst57
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst40
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst90
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-uvc-msxu-1-5.rst23
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-uvc.rst54
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-vivid.rst37
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst169
-rw-r--r--Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst130
-rw-r--r--Documentation/userspace-api/media/v4l/mmap.rst285
-rw-r--r--Documentation/userspace-api/media/v4l/mt2110t.svg315
-rw-r--r--Documentation/userspace-api/media/v4l/nv12mt.svg451
-rw-r--r--Documentation/userspace-api/media/v4l/nv12mt_example.svg1590
-rw-r--r--Documentation/userspace-api/media/v4l/open.rst238
-rw-r--r--Documentation/userspace-api/media/v4l/pipeline.dot14
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-bayer.rst35
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst32
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-compressed.rst280
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-indexed.rst48
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-intro.rst52
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-inzi.rst83
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-m420.rst72
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst158
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst483
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-rawnn-cru.rst143
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-reserved.rst288
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-rgb.rst1279
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst31
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst35
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst31
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst35
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst56
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst56
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst56
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst33
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst346
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst77
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst25
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst29
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst75
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst78
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst88
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst78
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst148
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst72
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst75
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst56
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst53
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst68
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst51
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst67
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-uv8.rst48
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst124
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst241
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-y12i.rst37
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-y16i.rst74
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-y8i.rst67
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst216
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst1456
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-z16.rst67
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt.rst39
-rw-r--r--Documentation/userspace-api/media/v4l/planar-apis.rst62
-rw-r--r--Documentation/userspace-api/media/v4l/querycap.rst35
-rw-r--r--Documentation/userspace-api/media/v4l/rw.rst47
-rw-r--r--Documentation/userspace-api/media/v4l/sdr-formats.rst23
-rw-r--r--Documentation/userspace-api/media/v4l/selection-api-configuration.rst138
-rw-r--r--Documentation/userspace-api/media/v4l/selection-api-examples.rst85
-rw-r--r--Documentation/userspace-api/media/v4l/selection-api-intro.rst29
-rw-r--r--Documentation/userspace-api/media/v4l/selection-api-targets.rst21
-rw-r--r--Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst40
-rw-r--r--Documentation/userspace-api/media/v4l/selection-api.rst17
-rw-r--r--Documentation/userspace-api/media/v4l/selection.svg1152
-rw-r--r--Documentation/userspace-api/media/v4l/selections-common.rst24
-rw-r--r--Documentation/userspace-api/media/v4l/standard.rst186
-rw-r--r--Documentation/userspace-api/media/v4l/streaming-par.rst34
-rw-r--r--Documentation/userspace-api/media/v4l/subdev-formats.rst9132
-rw-r--r--Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg303
-rw-r--r--Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg743
-rw-r--r--Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg541
-rw-r--r--Documentation/userspace-api/media/v4l/tch-formats.rst19
-rw-r--r--Documentation/userspace-api/media/v4l/tuner.rst86
-rw-r--r--Documentation/userspace-api/media/v4l/user-func.rst86
-rw-r--r--Documentation/userspace-api/media/v4l/userp.rst122
-rw-r--r--Documentation/userspace-api/media/v4l/v4l2-isp.rst67
-rw-r--r--Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst55
-rw-r--r--Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst82
-rw-r--r--Documentation/userspace-api/media/v4l/v4l2.rst414
-rw-r--r--Documentation/userspace-api/media/v4l/v4l2grab-example.rst18
-rw-r--r--Documentation/userspace-api/media/v4l/v4l2grab.c.rst170
-rw-r--r--Documentation/userspace-api/media/v4l/vbi_525.svg812
-rw-r--r--Documentation/userspace-api/media/v4l/vbi_625.svg861
-rw-r--r--Documentation/userspace-api/media/v4l/vbi_hsync.svg312
-rw-r--r--Documentation/userspace-api/media/v4l/video.rst69
-rw-r--r--Documentation/userspace-api/media/v4l/videodev.rst14
-rw-r--r--Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions614
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst141
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-cropcap.rst133
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst155
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst160
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst218
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-dqevent.rst377
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst159
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst169
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst105
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst266
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst186
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst194
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst139
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst53
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst58
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enuminput.rst229
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst153
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-enumstd.rst351
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-expbuf.rst162
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-audio.rst124
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst99
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-crop.rst110
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst100
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst317
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-edid.rst146
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst144
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst553
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst331
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst154
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst103
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-input.rst63
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst124
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst193
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-output.rst65
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-parm.rst269
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-priority.rst91
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-selection.rst190
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst202
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-std.rst82
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst464
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-log-status.rst47
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-overlay.rst52
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst56
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-qbuf.rst197
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst86
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-querybuf.rst78
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-querycap.rst289
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst706
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-querystd.rst69
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst86
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst207
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst137
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-streamon.rst105
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst113
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst131
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst163
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst103
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst127
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst154
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst126
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst164
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst125
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst104
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst113
-rw-r--r--Documentation/userspace-api/media/v4l/yuv-formats.rst275
-rw-r--r--Documentation/userspace-api/mfd_noexec.rst86
-rw-r--r--Documentation/userspace-api/mseal.rst209
-rw-r--r--Documentation/userspace-api/netlink/c-code-gen.rst109
-rw-r--r--Documentation/userspace-api/netlink/genetlink-legacy.rst292
-rw-r--r--Documentation/userspace-api/netlink/index.rst21
-rw-r--r--Documentation/userspace-api/netlink/intro-specs.rst159
-rw-r--r--Documentation/userspace-api/netlink/intro.rst687
-rw-r--r--Documentation/userspace-api/netlink/netlink-raw.rst194
-rw-r--r--Documentation/userspace-api/netlink/specs.rst467
-rw-r--r--Documentation/userspace-api/no_new_privs.rst63
-rw-r--r--Documentation/userspace-api/ntsync.rst385
-rw-r--r--Documentation/userspace-api/perf_ring_buffer.rst830
-rw-r--r--Documentation/userspace-api/seccomp_filter.rst376
-rw-r--r--Documentation/userspace-api/spec_ctrl.rst120
-rw-r--r--Documentation/userspace-api/sysfs-platform_profile.rst80
-rw-r--r--Documentation/userspace-api/tee.rst39
-rw-r--r--Documentation/userspace-api/unshare.rst332
-rw-r--r--Documentation/userspace-api/vduse.rst233
-rw-r--r--Documentation/vDSO/.gitignore2
-rw-r--r--Documentation/vDSO/Makefile15
-rw-r--r--Documentation/vDSO/parse_vdso.c269
-rw-r--r--Documentation/vDSO/vdso_standalone_test_x86.c128
-rw-r--r--Documentation/vDSO/vdso_test.c52
-rw-r--r--Documentation/vfio.txt458
-rw-r--r--Documentation/vgaarbiter.txt192
-rw-r--r--Documentation/video-output.txt34
-rw-r--r--Documentation/video4linux/4CCs.txt32
-rw-r--r--Documentation/video4linux/API.html27
-rw-r--r--Documentation/video4linux/CARDLIST.au08286
-rw-r--r--Documentation/video4linux/CARDLIST.bttv167
-rw-r--r--Documentation/video4linux/CARDLIST.cx2388547
-rw-r--r--Documentation/video4linux/CARDLIST.cx8891
-rw-r--r--Documentation/video4linux/CARDLIST.em28xx96
-rw-r--r--Documentation/video4linux/CARDLIST.ivtv24
-rw-r--r--Documentation/video4linux/CARDLIST.saa7134194
-rw-r--r--Documentation/video4linux/CARDLIST.saa716411
-rw-r--r--Documentation/video4linux/CARDLIST.tm600016
-rw-r--r--Documentation/video4linux/CARDLIST.tuner91
-rw-r--r--Documentation/video4linux/CARDLIST.usbvision67
-rw-r--r--Documentation/video4linux/Makefile1
-rw-r--r--Documentation/video4linux/README.cpia2130
-rw-r--r--Documentation/video4linux/README.cx8867
-rw-r--r--Documentation/video4linux/README.davinci-vpbe93
-rw-r--r--Documentation/video4linux/README.ir72
-rw-r--r--Documentation/video4linux/README.ivtv186
-rw-r--r--Documentation/video4linux/README.pvrusb2212
-rw-r--r--Documentation/video4linux/README.saa713482
-rw-r--r--Documentation/video4linux/Zoran510
-rw-r--r--Documentation/video4linux/bttv/CONTRIBUTORS25
-rw-r--r--Documentation/video4linux/bttv/Cards960
-rw-r--r--Documentation/video4linux/bttv/ICs37
-rw-r--r--Documentation/video4linux/bttv/Insmod-options172
-rw-r--r--Documentation/video4linux/bttv/MAKEDEV27
-rw-r--r--Documentation/video4linux/bttv/Modprobe.conf11
-rw-r--r--Documentation/video4linux/bttv/Modules.conf14
-rw-r--r--Documentation/video4linux/bttv/PROBLEMS62
-rw-r--r--Documentation/video4linux/bttv/README90
-rw-r--r--Documentation/video4linux/bttv/README.WINVIEW33
-rw-r--r--Documentation/video4linux/bttv/README.freeze74
-rw-r--r--Documentation/video4linux/bttv/README.quirks83
-rw-r--r--Documentation/video4linux/bttv/Sound-FAQ148
-rw-r--r--Documentation/video4linux/bttv/Specs3
-rw-r--r--Documentation/video4linux/bttv/THANKS24
-rw-r--r--Documentation/video4linux/bttv/Tuners115
-rw-r--r--Documentation/video4linux/cafe_ccic54
-rw-r--r--Documentation/video4linux/cpia2_overview.txt38
-rw-r--r--Documentation/video4linux/cx18.txt30
-rw-r--r--Documentation/video4linux/cx2341x/README.hm12120
-rw-r--r--Documentation/video4linux/cx2341x/README.vbi45
-rw-r--r--Documentation/video4linux/cx2341x/fw-calling.txt69
-rw-r--r--Documentation/video4linux/cx2341x/fw-decoder-api.txt297
-rw-r--r--Documentation/video4linux/cx2341x/fw-decoder-regs.txt817
-rw-r--r--Documentation/video4linux/cx2341x/fw-dma.txt96
-rw-r--r--Documentation/video4linux/cx2341x/fw-encoder-api.txt709
-rw-r--r--Documentation/video4linux/cx2341x/fw-memory.txt139
-rw-r--r--Documentation/video4linux/cx2341x/fw-osd-api.txt350
-rw-r--r--Documentation/video4linux/cx2341x/fw-upload.txt49
-rw-r--r--Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt54
-rwxr-xr-xDocumentation/video4linux/extract_xc3028.pl1717
-rw-r--r--Documentation/video4linux/fimc.txt148
-rw-r--r--Documentation/video4linux/gspca.txt408
-rw-r--r--Documentation/video4linux/hauppauge-wintv-cx88-ir.txt54
-rw-r--r--Documentation/video4linux/lifeview.txt42
-rw-r--r--Documentation/video4linux/meye.txt123
-rw-r--r--Documentation/video4linux/not-in-cx2388x-datasheet.txt41
-rw-r--r--Documentation/video4linux/omap3isp.txt279
-rw-r--r--Documentation/video4linux/omap4_camera.txt60
-rw-r--r--Documentation/video4linux/pxa_camera.txt174
-rw-r--r--Documentation/video4linux/radiotrack.txt147
-rw-r--r--Documentation/video4linux/sh_mobile_ceu_camera.txt139
-rw-r--r--Documentation/video4linux/si470x.txt129
-rw-r--r--Documentation/video4linux/si4713.txt176
-rw-r--r--Documentation/video4linux/si476x.txt187
-rw-r--r--Documentation/video4linux/soc-camera.txt164
-rw-r--r--Documentation/video4linux/uvcvideo.txt239
-rw-r--r--Documentation/video4linux/v4l2-controls.txt752
-rw-r--r--Documentation/video4linux/v4l2-framework.txt1156
-rw-r--r--Documentation/video4linux/v4l2-pci-skeleton.c924
-rw-r--r--Documentation/video4linux/videobuf355
-rw-r--r--Documentation/video4linux/vivid.txt1129
-rw-r--r--Documentation/video4linux/zr364xx.txt69
-rw-r--r--Documentation/virt/acrn/cpuid.rst46
-rw-r--r--Documentation/virt/acrn/index.rst12
-rw-r--r--Documentation/virt/acrn/introduction.rst43
-rw-r--r--Documentation/virt/acrn/io-request.rst97
-rw-r--r--Documentation/virt/coco/sev-guest.rst243
-rw-r--r--Documentation/virt/coco/tdx-guest.rst52
-rw-r--r--Documentation/virt/guest-halt-polling.rst84
-rw-r--r--Documentation/virt/hyperv/clocks.rst82
-rw-r--r--Documentation/virt/hyperv/coco.rst397
-rw-r--r--Documentation/virt/hyperv/hibernation.rst336
-rw-r--r--Documentation/virt/hyperv/index.rst15
-rw-r--r--Documentation/virt/hyperv/overview.rst207
-rw-r--r--Documentation/virt/hyperv/vmbus.rst346
-rw-r--r--Documentation/virt/hyperv/vpci.rst316
-rw-r--r--Documentation/virt/index.rst25
-rw-r--r--Documentation/virt/kvm/api.rst9353
-rw-r--r--Documentation/virt/kvm/arm/fw-pseudo-registers.rst151
-rw-r--r--Documentation/virt/kvm/arm/hyp-abi.rst78
-rw-r--r--Documentation/virt/kvm/arm/hypercalls.rst203
-rw-r--r--Documentation/virt/kvm/arm/index.rst15
-rw-r--r--Documentation/virt/kvm/arm/ptp_kvm.rst35
-rw-r--r--Documentation/virt/kvm/arm/pvtime.rst82
-rw-r--r--Documentation/virt/kvm/arm/vcpu-features.rst48
-rw-r--r--Documentation/virt/kvm/devices/README (renamed from Documentation/virtual/kvm/devices/README)0
-rw-r--r--Documentation/virt/kvm/devices/arm-vgic-its.rst215
-rw-r--r--Documentation/virt/kvm/devices/arm-vgic-v3.rst376
-rw-r--r--Documentation/virt/kvm/devices/arm-vgic.rst156
-rw-r--r--Documentation/virt/kvm/devices/index.rst19
-rw-r--r--Documentation/virt/kvm/devices/mpic.rst58
-rw-r--r--Documentation/virt/kvm/devices/s390_flic.rst170
-rw-r--r--Documentation/virt/kvm/devices/vcpu.rst293
-rw-r--r--Documentation/virt/kvm/devices/vfio.rst61
-rw-r--r--Documentation/virt/kvm/devices/vm.rst402
-rw-r--r--Documentation/virt/kvm/devices/xics.rst92
-rw-r--r--Documentation/virt/kvm/devices/xive.rst247
-rw-r--r--Documentation/virt/kvm/halt-polling.rst153
-rw-r--r--Documentation/virt/kvm/index.rst22
-rw-r--r--Documentation/virt/kvm/locking.rst318
-rw-r--r--Documentation/virt/kvm/loongarch/hypercalls.rst89
-rw-r--r--Documentation/virt/kvm/loongarch/index.rst10
-rw-r--r--Documentation/virt/kvm/ppc-pv.rst222
-rw-r--r--Documentation/virt/kvm/review-checklist.rst122
-rw-r--r--Documentation/virt/kvm/s390/index.rst13
-rw-r--r--Documentation/virt/kvm/s390/s390-diag.rst140
-rw-r--r--Documentation/virt/kvm/s390/s390-pv-boot.rst84
-rw-r--r--Documentation/virt/kvm/s390/s390-pv-dump.rst64
-rw-r--r--Documentation/virt/kvm/s390/s390-pv.rst116
-rw-r--r--Documentation/virt/kvm/vcpu-requests.rst294
-rw-r--r--Documentation/virt/kvm/x86/amd-memory-encryption.rst613
-rw-r--r--Documentation/virt/kvm/x86/cpuid.rst124
-rw-r--r--Documentation/virt/kvm/x86/errata.rst87
-rw-r--r--Documentation/virt/kvm/x86/hypercalls.rst192
-rw-r--r--Documentation/virt/kvm/x86/index.rst19
-rw-r--r--Documentation/virt/kvm/x86/intel-tdx.rst268
-rw-r--r--Documentation/virt/kvm/x86/mmu.rst509
-rw-r--r--Documentation/virt/kvm/x86/msr.rst390
-rw-r--r--Documentation/virt/kvm/x86/nested-vmx.rst244
-rw-r--r--Documentation/virt/kvm/x86/running-nested-guests.rst278
-rw-r--r--Documentation/virt/kvm/x86/timekeeping.rst645
-rw-r--r--Documentation/virt/ne_overview.rst100
-rw-r--r--Documentation/virt/paravirt_ops.rst35
-rw-r--r--Documentation/virt/uml/user_mode_linux_howto_v2.rst1240
-rw-r--r--Documentation/virtual/00-INDEX11
-rw-r--r--Documentation/virtual/kvm/00-INDEX26
-rw-r--r--Documentation/virtual/kvm/api.txt3592
-rw-r--r--Documentation/virtual/kvm/cpuid.txt60
-rw-r--r--Documentation/virtual/kvm/devices/arm-vgic.txt116
-rw-r--r--Documentation/virtual/kvm/devices/mpic.txt53
-rw-r--r--Documentation/virtual/kvm/devices/s390_flic.txt94
-rw-r--r--Documentation/virtual/kvm/devices/vfio.txt22
-rw-r--r--Documentation/virtual/kvm/devices/vm.txt85
-rw-r--r--Documentation/virtual/kvm/devices/xics.txt66
-rw-r--r--Documentation/virtual/kvm/hypercalls.txt83
-rw-r--r--Documentation/virtual/kvm/locking.txt168
-rw-r--r--Documentation/virtual/kvm/mmu.txt448
-rw-r--r--Documentation/virtual/kvm/msr.txt266
-rw-r--r--Documentation/virtual/kvm/nested-vmx.txt251
-rw-r--r--Documentation/virtual/kvm/ppc-pv.txt212
-rw-r--r--Documentation/virtual/kvm/review-checklist.txt38
-rw-r--r--Documentation/virtual/kvm/s390-diag.txt82
-rw-r--r--Documentation/virtual/kvm/timekeeping.txt612
-rw-r--r--Documentation/virtual/paravirt_ops.txt32
-rw-r--r--Documentation/virtual/uml/UserModeLinux-HOWTO.txt4589
-rw-r--r--Documentation/vm/.gitignore2
-rw-r--r--Documentation/vm/00-INDEX40
-rw-r--r--Documentation/vm/active_mm.txt83
-rw-r--r--Documentation/vm/balance93
-rw-r--r--Documentation/vm/cleancache.txt277
-rw-r--r--Documentation/vm/frontswap.txt278
-rw-r--r--Documentation/vm/highmem.txt162
-rw-r--r--Documentation/vm/hugetlbpage.txt335
-rw-r--r--Documentation/vm/hwpoison.txt187
-rw-r--r--Documentation/vm/ksm.txt97
-rw-r--r--Documentation/vm/numa149
-rw-r--r--Documentation/vm/numa_memory_policy.txt452
-rw-r--r--Documentation/vm/overcommit-accounting80
-rw-r--r--Documentation/vm/page_migration149
-rw-r--r--Documentation/vm/page_owner.txt81
-rw-r--r--Documentation/vm/pagemap.txt161
-rw-r--r--Documentation/vm/remap_file_pages.txt27
-rw-r--r--Documentation/vm/slub.txt283
-rw-r--r--Documentation/vm/soft-dirty.txt43
-rw-r--r--Documentation/vm/split_page_table_lock94
-rw-r--r--Documentation/vm/transhuge.txt387
-rw-r--r--Documentation/vm/unevictable-lru.txt688
-rw-r--r--Documentation/vm/zsmalloc.txt70
-rw-r--r--Documentation/vm/zswap.txt68
-rw-r--r--Documentation/vme_api.txt406
-rw-r--r--Documentation/volatile-considered-harmful.txt119
-rw-r--r--Documentation/w1/00-INDEX10
-rw-r--r--Documentation/w1/index.rst21
-rw-r--r--Documentation/w1/masters/00-INDEX12
-rw-r--r--Documentation/w1/masters/ds248231
-rw-r--r--Documentation/w1/masters/ds2482.rst39
-rw-r--r--Documentation/w1/masters/ds249068
-rw-r--r--Documentation/w1/masters/ds2490.rst72
-rw-r--r--Documentation/w1/masters/index.rst15
-rw-r--r--Documentation/w1/masters/mxc-w112
-rw-r--r--Documentation/w1/masters/mxc-w1.rst17
-rw-r--r--Documentation/w1/masters/omap-hdq46
-rw-r--r--Documentation/w1/masters/omap-hdq.rst54
-rw-r--r--Documentation/w1/masters/w1-gpio33
-rw-r--r--Documentation/w1/masters/w1-gpio.rst47
-rw-r--r--Documentation/w1/masters/w1-uart.rst54
-rw-r--r--Documentation/w1/slaves/00-INDEX8
-rw-r--r--Documentation/w1/slaves/index.rst16
-rw-r--r--Documentation/w1/slaves/w1_ds240625
-rw-r--r--Documentation/w1/slaves/w1_ds2406.rst27
-rw-r--r--Documentation/w1/slaves/w1_ds2413.rst59
-rw-r--r--Documentation/w1/slaves/w1_ds242347
-rw-r--r--Documentation/w1/slaves/w1_ds2423.rst54
-rw-r--r--Documentation/w1/slaves/w1_ds2438.rst86
-rw-r--r--Documentation/w1/slaves/w1_ds28e0436
-rw-r--r--Documentation/w1/slaves/w1_ds28e04.rst41
-rw-r--r--Documentation/w1/slaves/w1_ds28e17.rst72
-rw-r--r--Documentation/w1/slaves/w1_therm50
-rw-r--r--Documentation/w1/slaves/w1_therm.rst144
-rw-r--r--Documentation/w1/w1-generic.rst133
-rw-r--r--Documentation/w1/w1-netlink.rst202
-rw-r--r--Documentation/w1/w1.generic113
-rw-r--r--Documentation/w1/w1.netlink189
-rw-r--r--Documentation/watchdog/Makefile1
-rw-r--r--Documentation/watchdog/convert_drivers_to_kernel_api.rst218
-rw-r--r--Documentation/watchdog/convert_drivers_to_kernel_api.txt218
-rw-r--r--Documentation/watchdog/hpwdt.rst77
-rw-r--r--Documentation/watchdog/hpwdt.txt95
-rw-r--r--Documentation/watchdog/index.rst25
-rw-r--r--Documentation/watchdog/mlx-wdt.rst66
-rw-r--r--Documentation/watchdog/pcwd-watchdog.rst71
-rw-r--r--Documentation/watchdog/pcwd-watchdog.txt66
-rw-r--r--Documentation/watchdog/src/.gitignore2
-rw-r--r--Documentation/watchdog/src/Makefile5
-rw-r--r--Documentation/watchdog/src/watchdog-simple.c24
-rw-r--r--Documentation/watchdog/src/watchdog-test.c86
-rw-r--r--Documentation/watchdog/watchdog-api.rst271
-rw-r--r--Documentation/watchdog/watchdog-api.txt237
-rw-r--r--Documentation/watchdog/watchdog-kernel-api.rst350
-rw-r--r--Documentation/watchdog/watchdog-kernel-api.txt226
-rw-r--r--Documentation/watchdog/watchdog-parameters.rst730
-rw-r--r--Documentation/watchdog/watchdog-parameters.txt399
-rw-r--r--Documentation/watchdog/watchdog-pm.rst22
-rw-r--r--Documentation/watchdog/wdt.rst63
-rw-r--r--Documentation/watchdog/wdt.txt50
-rw-r--r--Documentation/wimax/README.i2400m260
-rw-r--r--Documentation/wimax/README.wimax81
-rw-r--r--Documentation/wmi/acpi-interface.rst106
-rw-r--r--Documentation/wmi/devices/alienware-wmi.rst322
-rw-r--r--Documentation/wmi/devices/dell-wmi-ddv.rst319
-rw-r--r--Documentation/wmi/devices/index.rst22
-rw-r--r--Documentation/wmi/devices/lenovo-wmi-gamezone.rst202
-rw-r--r--Documentation/wmi/devices/lenovo-wmi-other.rst108
-rw-r--r--Documentation/wmi/devices/msi-wmi-platform.rst198
-rw-r--r--Documentation/wmi/devices/uniwill-laptop.rst198
-rw-r--r--Documentation/wmi/devices/wmi-bmof.rst25
-rw-r--r--Documentation/wmi/driver-development-guide.rst192
-rw-r--r--Documentation/wmi/index.rst20
-rw-r--r--Documentation/workqueue.txt388
-rw-r--r--Documentation/x86/00-INDEX20
-rw-r--r--Documentation/x86/boot.txt1131
-rw-r--r--Documentation/x86/early-microcode.txt42
-rw-r--r--Documentation/x86/earlyprintk.txt136
-rw-r--r--Documentation/x86/entry_64.txt104
-rw-r--r--Documentation/x86/exception-tables.txt292
-rw-r--r--Documentation/x86/i386/IO-APIC.txt119
-rw-r--r--Documentation/x86/intel_mpx.txt244
-rw-r--r--Documentation/x86/mtrr.txt305
-rw-r--r--Documentation/x86/pat.txt160
-rw-r--r--Documentation/x86/tlb.txt75
-rw-r--r--Documentation/x86/usb-legacy-support.txt44
-rw-r--r--Documentation/x86/x86_64/00-INDEX16
-rw-r--r--Documentation/x86/x86_64/boot-options.txt284
-rw-r--r--Documentation/x86/x86_64/cpu-hotplug-spec21
-rw-r--r--Documentation/x86/x86_64/fake-numa-for-cpusets67
-rw-r--r--Documentation/x86/x86_64/kernel-stacks101
-rw-r--r--Documentation/x86/x86_64/machinecheck83
-rw-r--r--Documentation/x86/x86_64/mm.txt42
-rw-r--r--Documentation/x86/x86_64/uefi.txt42
-rw-r--r--Documentation/x86/zero-page.txt37
-rw-r--r--Documentation/xillybus.txt380
-rw-r--r--Documentation/xtensa/atomctl.txt44
-rw-r--r--Documentation/xtensa/mmu.txt64
-rw-r--r--Documentation/xz.txt121
-rw-r--r--Documentation/zh_CN/CodingStyle694
-rw-r--r--Documentation/zh_CN/HOWTO538
-rw-r--r--Documentation/zh_CN/IRQ.txt39
-rw-r--r--Documentation/zh_CN/SecurityBugs50
-rw-r--r--Documentation/zh_CN/SubmittingDrivers164
-rw-r--r--Documentation/zh_CN/SubmittingPatches412
-rw-r--r--Documentation/zh_CN/arm/Booting175
-rw-r--r--Documentation/zh_CN/arm/kernel_user_helpers.txt284
-rw-r--r--Documentation/zh_CN/arm64/booting.txt219
-rw-r--r--Documentation/zh_CN/arm64/legacy_instructions.txt72
-rw-r--r--Documentation/zh_CN/arm64/memory.txt114
-rw-r--r--Documentation/zh_CN/arm64/tagged-pointers.txt52
-rw-r--r--Documentation/zh_CN/basic_profiling.txt71
-rw-r--r--Documentation/zh_CN/email-clients.txt210
-rw-r--r--Documentation/zh_CN/filesystems/sysfs.txt372
-rw-r--r--Documentation/zh_CN/gpio.txt658
-rw-r--r--Documentation/zh_CN/io_ordering.txt67
-rw-r--r--Documentation/zh_CN/magic-number.txt155
-rw-r--r--Documentation/zh_CN/oops-tracing.txt212
-rw-r--r--Documentation/zh_CN/sparse.txt100
-rw-r--r--Documentation/zh_CN/stable_api_nonsense.txt157
-rw-r--r--Documentation/zh_CN/stable_kernel_rules.txt66
-rw-r--r--Documentation/zh_CN/video4linux/omap3isp.txt277
-rw-r--r--Documentation/zh_CN/video4linux/v4l2-framework.txt976
-rw-r--r--Documentation/zh_CN/volatile-considered-harmful.txt113
-rw-r--r--Documentation/zorro.txt103
13893 files changed, 1563373 insertions, 504825 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 000000000000..d6dc7c9b8e25
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: GPL-2.0-only
+output
+*.pyc
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/00-INDEX b/Documentation/00-INDEX
deleted file mode 100644
index cd077ca0e1b8..000000000000
--- a/Documentation/00-INDEX
+++ /dev/null
@@ -1,489 +0,0 @@
-
-This is a brief list of all the files in ./linux/Documentation and what
-they contain. If you add a documentation file, please list it here in
-alphabetical order as well, or risk being hunted down like a rabid dog.
-Please keep the descriptions small enough to fit on one line.
- Thanks -- Paul G.
-
-Following translations are available on the WWW:
-
- - Japanese, maintained by the JF Project (jf@listserv.linux.or.jp), at
- http://linuxjf.sourceforge.jp/
-
-00-INDEX
- - this file.
-ABI/
- - info on kernel <-> userspace ABI and relative interface stability.
-
-BUG-HUNTING
- - brute force method of doing binary search of patches to find bug.
-Changes
- - list of changes that break older software packages.
-CodingStyle
- - how the maintainers expect the C code in the kernel to look.
-DMA-API.txt
- - DMA API, pci_ API & extensions for non-consistent memory machines.
-DMA-API-HOWTO.txt
- - Dynamic DMA mapping Guide
-DMA-ISA-LPC.txt
- - How to do DMA with ISA (and LPC) devices.
-DMA-attributes.txt
- - listing of the various possible attributes a DMA region can have
-DocBook/
- - directory with DocBook templates etc. for kernel documentation.
-EDID/
- - directory with info on customizing EDID for broken gfx/displays.
-HOWTO
- - the process and procedures of how to do Linux kernel development.
-IPMI.txt
- - info on Linux Intelligent Platform Management Interface (IPMI) Driver.
-IRQ-affinity.txt
- - how to select which CPU(s) handle which interrupt events on SMP.
-IRQ-domain.txt
- - info on interrupt numbering and setting up IRQ domains.
-IRQ.txt
- - description of what an IRQ is.
-Intel-IOMMU.txt
- - basic info on the Intel IOMMU virtualization support.
-Makefile
- - some files in Documentation dir are actually sample code to build
-ManagementStyle
- - how to (attempt to) manage kernel hackers.
-RCU/
- - directory with info on RCU (read-copy update).
-SAK.txt
- - info on Secure Attention Keys.
-SM501.txt
- - Silicon Motion SM501 multimedia companion chip
-SecurityBugs
- - procedure for reporting security bugs found in the kernel.
-SubmitChecklist
- - Linux kernel patch submission checklist.
-SubmittingDrivers
- - procedure to get a new driver source included into the kernel tree.
-SubmittingPatches
- - procedure to get a source patch included into the kernel tree.
-VGA-softcursor.txt
- - how to change your VGA cursor from a blinking underscore.
-accounting/
- - documentation on accounting and taskstats.
-acpi/
- - info on ACPI-specific hooks in the kernel.
-aoe/
- - description of AoE (ATA over Ethernet) along with config examples.
-applying-patches.txt
- - description of various trees and how to apply their patches.
-arm/
- - directory with info about Linux on the ARM architecture.
-arm64/
- - directory with info about Linux on the 64 bit ARM architecture.
-assoc_array.txt
- - generic associative array intro.
-atomic_ops.txt
- - semantics and behavior of atomic and bitmask operations.
-auxdisplay/
- - misc. LCD driver documentation (cfag12864b, ks0108).
-backlight/
- - directory with info on controlling backlights in flat panel displays
-bad_memory.txt
- - how to use kernel parameters to exclude bad RAM regions.
-basic_profiling.txt
- - basic instructions for those who wants to profile Linux kernel.
-bcache.txt
- - Block-layer cache on fast SSDs to improve slow (raid) I/O performance.
-binfmt_misc.txt
- - info on the kernel support for extra binary formats.
-blackfin/
- - directory with documentation for the Blackfin arch.
-block/
- - info on the Block I/O (BIO) layer.
-blockdev/
- - info on block devices & drivers
-braille-console.txt
- - info on how to use serial devices for Braille support.
-bt8xxgpio.txt
- - info on how to modify a bt8xx video card for GPIO usage.
-btmrvl.txt
- - info on Marvell Bluetooth driver usage.
-bus-devices/
- - directory with info on TI GPMC (General Purpose Memory Controller)
-bus-virt-phys-mapping.txt
- - how to access I/O mapped memory from within device drivers.
-cachetlb.txt
- - describes the cache/TLB flushing interfaces Linux uses.
-cdrom/
- - directory with information on the CD-ROM drivers that Linux has.
-cgroups/
- - cgroups features, including cpusets and memory controller.
-circular-buffers.txt
- - how to make use of the existing circular buffer infrastructure
-clk.txt
- - info on the common clock framework
-coccinelle.txt
- - info on how to get and use the Coccinelle code checking tool.
-connector/
- - docs on the netlink based userspace<->kernel space communication mod.
-console/
- - documentation on Linux console drivers.
-cpu-freq/
- - info on CPU frequency and voltage scaling.
-cpu-hotplug.txt
- - document describing CPU hotplug support in the Linux kernel.
-cpu-load.txt
- - document describing how CPU load statistics are collected.
-cpuidle/
- - info on CPU_IDLE, CPU idle state management subsystem.
-cputopology.txt
- - documentation on how CPU topology info is exported via sysfs.
-crc32.txt
- - brief tutorial on CRC computation
-cris/
- - directory with info about Linux on CRIS architecture.
-crypto/
- - directory with info on the Crypto API.
-dcdbas.txt
- - information on the Dell Systems Management Base Driver.
-debugging-modules.txt
- - some notes on debugging modules after Linux 2.6.3.
-debugging-via-ohci1394.txt
- - how to use firewire like a hardware debugger memory reader.
-dell_rbu.txt
- - document demonstrating the use of the Dell Remote BIOS Update driver.
-development-process/
- - how to work with the mainline kernel development process.
-device-mapper/
- - directory with info on Device Mapper.
-devices.txt
- - plain ASCII listing of all the nodes in /dev/ with major minor #'s.
-devicetree/
- - directory with info on device tree files used by OF/PowerPC/ARM
-digsig.txt
- -info on the Digital Signature Verification API
-dma-buf-sharing.txt
- - the DMA Buffer Sharing API Guide
-dontdiff
- - file containing a list of files that should never be diff'ed.
-driver-model/
- - directory with info about Linux driver model.
-dvb/
- - info on Linux Digital Video Broadcast (DVB) subsystem.
-dynamic-debug-howto.txt
- - how to use the dynamic debug (dyndbg) feature.
-early-userspace/
- - info about initramfs, klibc, and userspace early during boot.
-edac.txt
- - information on EDAC - Error Detection And Correction
-efi-stub.txt
- - How to use the EFI boot stub to bypass GRUB or elilo on EFI systems.
-eisa.txt
- - info on EISA bus support.
-email-clients.txt
- - info on how to use e-mail to send un-mangled (git) patches.
-extcon/
- - directory with porting guide for Android kernel switch driver.
-fault-injection/
- - dir with docs about the fault injection capabilities infrastructure.
-fb/
- - directory with info on the frame buffer graphics abstraction layer.
-filesystems/
- - info on the vfs and the various filesystems that Linux supports.
-firmware_class/
- - request_firmware() hotplug interface info.
-flexible-arrays.txt
- - how to make use of flexible sized arrays in linux
-fmc/
- - information about the FMC bus abstraction
-frv/
- - Fujitsu FR-V Linux documentation.
-futex-requeue-pi.txt
- - info on requeueing of tasks from a non-PI futex to a PI futex
-gcov.txt
- - use of GCC's coverage testing tool "gcov" with the Linux kernel
-gpio/
- - gpio related documentation
-hid/
- - directory with information on human interface devices
-highuid.txt
- - notes on the change from 16 bit to 32 bit user/group IDs.
-hsi.txt
- - HSI subsystem overview.
-hwspinlock.txt
- - hardware spinlock provides hardware assistance for synchronization
-timers/
- - info on the timer related topics
-hw_random.txt
- - info on Linux support for random number generator in i8xx chipsets.
-hwmon/
- - directory with docs on various hardware monitoring drivers.
-i2c/
- - directory with info about the I2C bus/protocol (2 wire, kHz speed).
-i2o/
- - directory with info about the Linux I2O subsystem.
-x86/i386/
- - directory with info about Linux on Intel 32 bit architecture.
-ia64/
- - directory with info about Linux on Intel 64 bit architecture.
-infiniband/
- - directory with documents concerning Linux InfiniBand support.
-init.txt
- - what to do when the kernel can't find the 1st process to run.
-initrd.txt
- - how to use the RAM disk as an initial/temporary root filesystem.
-input/
- - info on Linux input device support.
-intel_txt.txt
- - info on intel Trusted Execution Technology (intel TXT).
-io-mapping.txt
- - description of io_mapping functions in linux/io-mapping.h
-io_ordering.txt
- - info on ordering I/O writes to memory-mapped addresses.
-ioctl/
- - directory with documents describing various IOCTL calls.
-iostats.txt
- - info on I/O statistics Linux kernel provides.
-irqflags-tracing.txt
- - how to use the irq-flags tracing feature.
-isapnp.txt
- - info on Linux ISA Plug & Play support.
-isdn/
- - directory with info on the Linux ISDN support, and supported cards.
-java.txt
- - info on the in-kernel binary support for Java(tm).
-ja_JP/
- - directory with Japanese translations of various documents
-kbuild/
- - directory with info about the kernel build process.
-kdump/
- - directory with mini HowTo on getting the crash dump code to work.
-kernel-doc-nano-HOWTO.txt
- - mini HowTo on generation and location of kernel documentation files.
-kernel-docs.txt
- - listing of various WWW + books that document kernel internals.
-kernel-parameters.txt
- - summary listing of command line / boot prompt args for the kernel.
-kernel-per-CPU-kthreads.txt
- - List of all per-CPU kthreads and how they introduce jitter.
-kmemcheck.txt
- - info on dynamic checker that detects uses of uninitialized memory.
-kmemleak.txt
- - info on how to make use of the kernel memory leak detection system
-ko_KR/
- - directory with Korean translations of various documents
-kobject.txt
- - info of the kobject infrastructure of the Linux kernel.
-kprobes.txt
- - documents the kernel probes debugging feature.
-kref.txt
- - docs on adding reference counters (krefs) to kernel objects.
-kselftest.txt
- - small unittests for (some) individual codepaths in the kernel.
-laptops/
- - directory with laptop related info and laptop driver documentation.
-ldm.txt
- - a brief description of LDM (Windows Dynamic Disks).
-leds/
- - directory with info about LED handling under Linux.
-local_ops.txt
- - semantics and behavior of local atomic operations.
-locking/
- - directory with info about kernel locking primitives
-lockup-watchdogs.txt
- - info on soft and hard lockup detectors (aka nmi_watchdog).
-logo.gif
- - full colour GIF image of Linux logo (penguin - Tux).
-logo.txt
- - info on creator of above logo & site to get additional images from.
-lzo.txt
- - kernel LZO decompressor input formats
-m68k/
- - directory with info about Linux on Motorola 68k architecture.
-magic-number.txt
- - list of magic numbers used to mark/protect kernel data structures.
-mailbox.txt
- - How to write drivers for the common mailbox framework (IPC).
-md.txt
- - info on boot arguments for the multiple devices driver.
-media-framework.txt
- - info on media framework, its data structures, functions and usage.
-memory-barriers.txt
- - info on Linux kernel memory barriers.
-memory-devices/
- - directory with info on parts like the Texas Instruments EMIF driver
-memory-hotplug.txt
- - Hotpluggable memory support, how to use and current status.
-metag/
- - directory with info about Linux on Meta architecture.
-mips/
- - directory with info about Linux on MIPS architecture.
-misc-devices/
- - directory with info about devices using the misc dev subsystem
-mmc/
- - directory with info about the MMC subsystem
-mn10300/
- - directory with info about the mn10300 architecture port
-module-signing.txt
- - Kernel module signing for increased security when loading modules.
-mtd/
- - directory with info about memory technology devices (flash)
-mono.txt
- - how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
-namespaces/
- - directory with various information about namespaces
-netlabel/
- - directory with information on the NetLabel subsystem.
-networking/
- - directory with info on various aspects of networking with Linux.
-nfc/
- - directory relating info about Near Field Communications support.
-nommu-mmap.txt
- - documentation about no-mmu memory mapping support.
-numastat.txt
- - info on how to read Numa policy hit/miss statistics in sysfs.
-oops-tracing.txt
- - how to decode those nasty internal kernel error dump messages.
-padata.txt
- - An introduction to the "padata" parallel execution API
-parisc/
- - directory with info on using Linux on PA-RISC architecture.
-parport.txt
- - how to use the parallel-port driver.
-parport-lowlevel.txt
- - description and usage of the low level parallel port functions.
-pcmcia/
- - info on the Linux PCMCIA driver.
-percpu-rw-semaphore.txt
- - RCU based read-write semaphore optimized for locking for reading
-phy.txt
- - Description of the generic PHY framework.
-pi-futex.txt
- - documentation on lightweight priority inheritance futexes.
-pinctrl.txt
- - info on pinctrl subsystem and the PINMUX/PINCONF and drivers
-pnp.txt
- - Linux Plug and Play documentation.
-power/
- - directory with info on Linux PCI power management.
-powerpc/
- - directory with info on using Linux with the PowerPC.
-prctl/
- - directory with info on the priveledge control subsystem
-preempt-locking.txt
- - info on locking under a preemptive kernel.
-printk-formats.txt
- - how to get printk format specifiers right
-pps/
- - directory with information on the pulse-per-second support
-ptp/
- - directory with info on support for IEEE 1588 PTP clocks in Linux.
-pwm.txt
- - info on the pulse width modulation driver subsystem
-ramoops.txt
- - documentation of the ramoops oops/panic logging module.
-rapidio/
- - directory with info on RapidIO packet-based fabric interconnect
-rbtree.txt
- - info on what red-black trees are and what they are for.
-remoteproc.txt
- - info on how to handle remote processor (e.g. AMP) offloads/usage.
-rfkill.txt
- - info on the radio frequency kill switch subsystem/support.
-robust-futex-ABI.txt
- - documentation of the robust futex ABI.
-robust-futexes.txt
- - a description of what robust futexes are.
-rpmsg.txt
- - info on the Remote Processor Messaging (rpmsg) Framework
-rtc.txt
- - notes on how to use the Real Time Clock (aka CMOS clock) driver.
-s390/
- - directory with info on using Linux on the IBM S390.
-scheduler/
- - directory with info on the scheduler.
-scsi/
- - directory with info on Linux scsi support.
-security/
- - directory that contains security-related info
-serial/
- - directory with info on the low level serial API.
-serial-console.txt
- - how to set up Linux with a serial line console as the default.
-sgi-ioc4.txt
- - description of the SGI IOC4 PCI (multi function) device.
-sh/
- - directory with info on porting Linux to a new architecture.
-smsc_ece1099.txt
- -info on the smsc Keyboard Scan Expansion/GPIO Expansion device.
-sound/
- - directory with info on sound card support.
-sparse.txt
- - info on how to obtain and use the sparse tool for typechecking.
-spi/
- - overview of Linux kernel Serial Peripheral Interface (SPI) support.
-stable_api_nonsense.txt
- - info on why the kernel does not have a stable in-kernel api or abi.
-stable_kernel_rules.txt
- - rules and procedures for the -stable kernel releases.
-static-keys.txt
- - info on how static keys allow debug code in hotpaths via patching
-svga.txt
- - short guide on selecting video modes at boot via VGA BIOS.
-sysfs-rules.txt
- - How not to use sysfs.
-sysctl/
- - directory with info on the /proc/sys/* files.
-sysrq.txt
- - info on the magic SysRq key.
-target/
- - directory with info on generating TCM v4 fabric .ko modules
-this_cpu_ops.txt
- - List rationale behind and the way to use this_cpu operations.
-thermal/
- - directory with information on managing thermal issues (CPU/temp)
-trace/
- - directory with info on tracing technologies within linux
-unaligned-memory-access.txt
- - info on how to avoid arch breaking unaligned memory access in code.
-unicode.txt
- - info on the Unicode character/font mapping used in Linux.
-unshare.txt
- - description of the Linux unshare system call.
-usb/
- - directory with info regarding the Universal Serial Bus.
-vDSO/
- - directory with info regarding virtual dynamic shared objects
-vfio.txt
- - info on Virtual Function I/O used in guest/hypervisor instances.
-vgaarbiter.txt
- - info on enable/disable the legacy decoding on different VGA devices
-video-output.txt
- - sysfs class driver interface to enable/disable a video output device.
-video4linux/
- - directory with info regarding video/TV/radio cards and linux.
-virtual/
- - directory with information on the various linux virtualizations.
-vm/
- - directory with info on the Linux vm code.
-vme_api.txt
- - file relating info on the VME bus API in linux
-volatile-considered-harmful.txt
- - Why the "volatile" type class should not be used
-w1/
- - directory with documents regarding the 1-wire (w1) subsystem.
-watchdog/
- - how to auto-reboot Linux if it has "fallen and can't get up". ;-)
-wimax/
- - directory with info about Intel Wireless Wimax Connections
-workqueue.txt
- - information on the Concurrency Managed Workqueue implementation
-x86/x86_64/
- - directory with info on Linux support for AMD x86-64 (Hammer) machines.
-xillybus.txt
- - Overview and basic ui of xillybus driver
-xtensa/
- - directory with documents relating to arch/xtensa port/implementation
-xz.txt
- - how to make use of the XZ data compression within linux kernel
-zh_CN/
- - directory with Chinese translations of various documents
-zorro.txt
- - info on writing drivers for Zorro bus devices found on Amigas.
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 1fafc4b0753b..315fffe1f831 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -1,4 +1,5 @@
-This directory attempts to document the ABI between the Linux kernel and
+This part of the documentation inside Documentation/ABI directory
+attempts to document the ABI between the Linux kernel and
userspace, and the relative stability of these interfaces. Due to the
everchanging nature of Linux, and the differing maturity levels, these
interfaces should be used by userspace programs in different ways.
@@ -32,7 +33,7 @@ The different levels of stability are:
layout of the files below for details on how to do this.)
obsolete/
- This directory documents interfaces that are still remaining in
+ This directory documents interfaces that are still remaining in
the kernel, but are marked to be removed at some later point in
time. The description of the interface will document the reason
why it is obsolete and when it can be expected to be removed.
@@ -45,7 +46,9 @@ Every file in these directories will contain the following information:
What: Short description of the interface
Date: Date created
-KernelVersion: Kernel version this feature first showed up in.
+KernelVersion: (Optional) Kernel version this feature first showed up in.
+ Note: git history often provides more accurate version
+ info, so this field may be omitted.
Contact: Primary contact for this interface (may be a mailing list)
Description: Long description of the interface and how to use it.
Users: All users of this interface who wish to be notified when
@@ -58,6 +61,14 @@ Users: All users of this interface who wish to be notified when
be changed further.
+Note:
+ The fields should be use a simple notation, compatible with ReST markup.
+ Also, the file **should not** have a top-level index, like::
+
+ ===
+ foo
+ ===
+
How things move between levels:
Interfaces in stable may move to obsolete, as long as the proper
@@ -84,4 +95,4 @@ stable:
- Kernel-internal symbols. Do not rely on the presence, absence, location, or
type of any kernel symbol, either in System.map files or the kernel binary
- itself. See Documentation/stable_api_nonsense.txt.
+ itself. See Documentation/process/stable-api-nonsense.rst.
diff --git a/Documentation/ABI/obsolete/automount-tracefs-debugfs b/Documentation/ABI/obsolete/automount-tracefs-debugfs
new file mode 100644
index 000000000000..a5196ec78cb5
--- /dev/null
+++ b/Documentation/ABI/obsolete/automount-tracefs-debugfs
@@ -0,0 +1,20 @@
+What: /sys/kernel/debug/tracing
+Date: May 2008
+KernelVersion: 2.6.27
+Contact: linux-trace-kernel@vger.kernel.org
+Description:
+
+ The ftrace was first added to the kernel, its interface was placed
+ into the debugfs file system under the "tracing" directory. Access
+ to the files were in /sys/kernel/debug/tracing. As systems wanted
+ access to the tracing interface without having to enable debugfs, a
+ new interface was created called "tracefs". This was a stand alone
+ file system and was usually mounted in /sys/kernel/tracing.
+
+ To allow older tooling to continue to operate, when mounting
+ debugfs, the tracefs file system would automatically get mounted in
+ the "tracing" directory of debugfs. The tracefs interface was added
+ in January 2015 in the v4.1 kernel.
+
+ All tooling should now be using tracefs directly and the "tracing"
+ directory in debugfs should be removed by January 2030.
diff --git a/Documentation/ABI/obsolete/o2cb b/Documentation/ABI/obsolete/o2cb
new file mode 100644
index 000000000000..8f39b596731d
--- /dev/null
+++ b/Documentation/ABI/obsolete/o2cb
@@ -0,0 +1,11 @@
+What: /sys/o2cb
+Date: Dec 2005
+KernelVersion: 2.6.16
+Contact: ocfs2-devel@lists.linux.dev
+Description: Ocfs2-tools looks at 'interface-revision' for versioning
+ information. Each logmask/ file controls a set of debug prints
+ and can be written into with the strings "allow", "deny", or
+ "off". Reading the file returns the current state.
+ Was renamed to /sys/fs/u2cb/
+Users: ocfs2-tools. It's sufficient to mail proposed changes to
+ ocfs2-devel@lists.linux.dev.
diff --git a/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads b/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads
deleted file mode 100644
index b0b0eeb20fe3..000000000000
--- a/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads
+++ /dev/null
@@ -1,5 +0,0 @@
-What: /proc/sys/vm/nr_pdflush_threads
-Date: June 2012
-Contact: Wanpeng Li <liwp@linux.vnet.ibm.com>
-Description: Since pdflush is replaced by per-BDI flusher, the interface of old pdflush
- exported in /proc/sys/vm/ should be removed.
diff --git a/Documentation/ABI/obsolete/procfs-i8k b/Documentation/ABI/obsolete/procfs-i8k
new file mode 100644
index 000000000000..32df4d5bdd15
--- /dev/null
+++ b/Documentation/ABI/obsolete/procfs-i8k
@@ -0,0 +1,10 @@
+What: /proc/i8k
+Date: November 2001
+KernelVersion: 2.4.14
+Contact: Pali Rohár <pali@kernel.org>
+Description: Legacy interface for getting/setting sensor information like
+ fan speed, temperature, serial number, hotkey status etc
+ on Dell Laptops.
+ Since the driver is now using the standard hwmon sysfs interface,
+ the procfs interface is deprecated.
+Users: https://github.com/vitorafsr/i8kutils
diff --git a/Documentation/ABI/obsolete/sysfs-block-zram b/Documentation/ABI/obsolete/sysfs-block-zram
deleted file mode 100644
index 720ea92cfb2e..000000000000
--- a/Documentation/ABI/obsolete/sysfs-block-zram
+++ /dev/null
@@ -1,119 +0,0 @@
-What: /sys/block/zram<id>/num_reads
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The num_reads file is read-only and specifies the number of
- reads (failed or successful) done on this device.
- Now accessible via zram<id>/stat node.
-
-What: /sys/block/zram<id>/num_writes
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The num_writes file is read-only and specifies the number of
- writes (failed or successful) done on this device.
- Now accessible via zram<id>/stat node.
-
-What: /sys/block/zram<id>/invalid_io
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The invalid_io file is read-only and specifies the number of
- non-page-size-aligned I/O requests issued to this device.
- Now accessible via zram<id>/io_stat node.
-
-What: /sys/block/zram<id>/failed_reads
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The failed_reads file is read-only and specifies the number of
- failed reads happened on this device.
- Now accessible via zram<id>/io_stat node.
-
-What: /sys/block/zram<id>/failed_writes
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The failed_writes file is read-only and specifies the number of
- failed writes happened on this device.
- Now accessible via zram<id>/io_stat node.
-
-What: /sys/block/zram<id>/notify_free
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The notify_free file is read-only. Depending on device usage
- scenario it may account a) the number of pages freed because
- of swap slot free notifications or b) the number of pages freed
- because of REQ_DISCARD requests sent by bio. The former ones
- are sent to a swap block device when a swap slot is freed, which
- implies that this disk is being used as a swap disk. The latter
- ones are sent by filesystem mounted with discard option,
- whenever some data blocks are getting discarded.
- Now accessible via zram<id>/io_stat node.
-
-What: /sys/block/zram<id>/zero_pages
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The zero_pages file is read-only and specifies number of zero
- filled pages written to this disk. No memory is allocated for
- such pages.
- Now accessible via zram<id>/mm_stat node.
-
-What: /sys/block/zram<id>/orig_data_size
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The orig_data_size file is read-only and specifies uncompressed
- size of data stored in this disk. This excludes zero-filled
- pages (zero_pages) since no memory is allocated for them.
- Unit: bytes
- Now accessible via zram<id>/mm_stat node.
-
-What: /sys/block/zram<id>/compr_data_size
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The compr_data_size file is read-only and specifies compressed
- size of data stored in this disk. So, compression ratio can be
- calculated using orig_data_size and this statistic.
- Unit: bytes
- Now accessible via zram<id>/mm_stat node.
-
-What: /sys/block/zram<id>/mem_used_total
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The mem_used_total file is read-only and specifies the amount
- of memory, including allocator fragmentation and metadata
- overhead, allocated for this disk. So, allocator space
- efficiency can be calculated using compr_data_size and this
- statistic.
- Unit: bytes
- Now accessible via zram<id>/mm_stat node.
-
-What: /sys/block/zram<id>/mem_used_max
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The mem_used_max file is read/write and specifies the amount
- of maximum memory zram have consumed to store compressed data.
- For resetting the value, you should write "0". Otherwise,
- you could see -EINVAL.
- Unit: bytes
- Downgraded to write-only node: so it's possible to set new
- value only; its current value is stored in zram<id>/mm_stat
- node.
-
-What: /sys/block/zram<id>/mem_limit
-Date: August 2015
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The mem_limit file is read/write and specifies the maximum
- amount of memory ZRAM can use to store the compressed data.
- The limit could be changed in run time and "0" means disable
- the limit. No limit is the initial state. Unit: bytes
- Downgraded to write-only node: so it's possible to set new
- value only; its current value is stored in zram<id>/mm_stat
- node.
diff --git a/Documentation/ABI/obsolete/sysfs-bus-iio b/Documentation/ABI/obsolete/sysfs-bus-iio
new file mode 100644
index 000000000000..a13523561958
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-bus-iio
@@ -0,0 +1,174 @@
+What: /sys/bus/iio/devices/iio:deviceX/buffer/length
+KernelVersion: 2.6.35
+Contact: linux-iio@vger.kernel.org
+Description:
+ Number of scans contained by the buffer.
+
+ Since Kernel 5.11, multiple buffers are supported.
+ so, it is better to use, instead:
+
+ /sys/bus/iio/devices/iio:deviceX/bufferY/length
+
+What: /sys/bus/iio/devices/iio:deviceX/buffer/enable
+KernelVersion: 2.6.35
+Contact: linux-iio@vger.kernel.org
+Description:
+ Actually start the buffer capture up. Will start trigger
+ if first device and appropriate.
+
+ Since Kernel 5.11, multiple buffers are supported.
+ so, it is better to use, instead:
+
+ /sys/bus/iio/devices/iio:deviceX/bufferY/enable
+
+What: /sys/bus/iio/devices/iio:deviceX/scan_elements
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ Directory containing interfaces for elements that will be
+ captured for a single triggered sample set in the buffer.
+
+ Since kernel 5.11 the scan_elements attributes are merged into
+ the bufferY directory, to be configurable per buffer.
+
+What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en
+What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en
+What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_en
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_en
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_en
+What: /sys/.../iio:deviceX/scan_elements/in_magn_x_en
+What: /sys/.../iio:deviceX/scan_elements/in_magn_y_en
+What: /sys/.../iio:deviceX/scan_elements/in_magn_z_en
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_en
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_en
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_tilt_comp_en
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_tilt_comp_en
+What: /sys/.../iio:deviceX/scan_elements/in_timestamp_en
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_en
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY_en
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY-voltageZ_en
+What: /sys/.../iio:deviceX/scan_elements/in_incli_x_en
+What: /sys/.../iio:deviceX/scan_elements/in_incli_y_en
+What: /sys/.../iio:deviceX/scan_elements/in_pressureY_en
+What: /sys/.../iio:deviceX/scan_elements/in_pressure_en
+What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_en
+What: /sys/.../iio:deviceX/scan_elements/in_proximity_en
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ Scan element control for triggered data capture.
+
+ Since kernel 5.11 the scan_elements attributes are merged into
+ the bufferY directory, to be configurable per buffer.
+
+What: /sys/.../iio:deviceX/scan_elements/in_accel_type
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_type
+What: /sys/.../iio:deviceX/scan_elements/in_magn_type
+What: /sys/.../iio:deviceX/scan_elements/in_incli_type
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY_type
+What: /sys/.../iio:deviceX/scan_elements/in_voltage_type
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_type
+What: /sys/.../iio:deviceX/scan_elements/in_timestamp_type
+What: /sys/.../iio:deviceX/scan_elements/in_pressureY_type
+What: /sys/.../iio:deviceX/scan_elements/in_pressure_type
+What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_type
+What: /sys/.../iio:deviceX/scan_elements/in_proximity_type
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ Description of the scan element data storage within the buffer
+ and hence the form in which it is read from user-space.
+ Form is [be|le]:[s|u]bits/storagebits[>>shift].
+ be or le specifies big or little endian. s or u specifies if
+ signed (2's complement) or unsigned. bits is the number of bits
+ of data and storagebits is the space (after padding) that it
+ occupies in the buffer. shift if specified, is the shift that
+ needs to be applied prior to masking out unused bits. Some
+ devices put their data in the middle of the transferred elements
+ with additional information on both sides. Note that some
+ devices will have additional information in the unused bits
+ so to get a clean value, the bits value must be used to mask
+ the buffer output value appropriately. The storagebits value
+ also specifies the data alignment. So s48/64>>2 will be a
+ signed 48 bit integer stored in a 64 bit location aligned to
+ a 64 bit boundary. To obtain the clean value, shift right 2
+ and apply a mask to zero the top 16 bits of the result.
+ For other storage combinations this attribute will be extended
+ appropriately.
+
+ Since kernel 5.11 the scan_elements attributes are merged into
+ the bufferY directory, to be configurable per buffer.
+
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY_index
+What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_index
+What: /sys/.../iio:deviceX/scan_elements/in_accel_x_index
+What: /sys/.../iio:deviceX/scan_elements/in_accel_y_index
+What: /sys/.../iio:deviceX/scan_elements/in_accel_z_index
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_index
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_index
+What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_index
+What: /sys/.../iio:deviceX/scan_elements/in_magn_x_index
+What: /sys/.../iio:deviceX/scan_elements/in_magn_y_index
+What: /sys/.../iio:deviceX/scan_elements/in_magn_z_index
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_index
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_index
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_tilt_comp_index
+What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_tilt_comp_index
+What: /sys/.../iio:deviceX/scan_elements/in_incli_x_index
+What: /sys/.../iio:deviceX/scan_elements/in_incli_y_index
+What: /sys/.../iio:deviceX/scan_elements/in_timestamp_index
+What: /sys/.../iio:deviceX/scan_elements/in_pressureY_index
+What: /sys/.../iio:deviceX/scan_elements/in_pressure_index
+What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_index
+What: /sys/.../iio:deviceX/scan_elements/in_proximity_index
+KernelVersion: 2.6.37
+Description:
+ A single positive integer specifying the position of this
+ scan element in the buffer. Note these are not dependent on
+ what is enabled and may not be contiguous. Thus for user-space
+ to establish the full layout these must be used in conjunction
+ with all _en attributes to establish which channels are present,
+ and the relevant _type attributes to establish the data storage
+ format.
+
+ Since kernel 5.11 the scan_elements attributes are merged into
+ the bufferY directory, to be configurable per buffer.
+
+What: /sys/bus/iio/devices/iio:deviceX/buffer/watermark
+KernelVersion: 4.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ A single positive integer specifying the maximum number of scan
+ elements to wait for.
+
+ Poll will block until the watermark is reached.
+
+ Blocking read will wait until the minimum between the requested
+ read amount or the low water mark is available.
+
+ Non-blocking read will retrieve the available samples from the
+ buffer even if there are less samples then watermark level. This
+ allows the application to block on poll with a timeout and read
+ the available samples after the timeout expires and thus have a
+ maximum delay guarantee.
+
+ Since Kernel 5.11, multiple buffers are supported.
+ so, it is better to use, instead:
+
+ /sys/bus/iio/devices/iio:deviceX/bufferY/watermark
+
+What: /sys/bus/iio/devices/iio:deviceX/buffer/data_available
+KernelVersion: 4.16
+Contact: linux-iio@vger.kernel.org
+Description:
+ A read-only value indicating the bytes of data available in the
+ buffer. In the case of an output buffer, this indicates the
+ amount of empty space available to write data to. In the case of
+ an input buffer, this indicates the amount of data available for
+ reading.
+
+ Since Kernel 5.11, multiple buffers are supported.
+ so, it is better to use, instead:
+
+ /sys/bus/iio/devices/iio:deviceX/bufferY/data_available
diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill
deleted file mode 100644
index ff60ad9eca4c..000000000000
--- a/Documentation/ABI/obsolete/sysfs-class-rfkill
+++ /dev/null
@@ -1,29 +0,0 @@
-rfkill - radio frequency (RF) connector kill switch support
-
-For details to this subsystem look at Documentation/rfkill.txt.
-
-What: /sys/class/rfkill/rfkill[0-9]+/state
-Date: 09-Jul-2007
-KernelVersion v2.6.22
-Contact: linux-wireless@vger.kernel.org
-Description: Current state of the transmitter.
- This file is deprecated and scheduled to be removed in 2014,
- because its not possible to express the 'soft and hard block'
- state of the rfkill driver.
-Values: A numeric value.
- 0: RFKILL_STATE_SOFT_BLOCKED
- transmitter is turned off by software
- 1: RFKILL_STATE_UNBLOCKED
- transmitter is (potentially) active
- 2: RFKILL_STATE_HARD_BLOCKED
- transmitter is forced off by something outside of
- the driver's control.
-
-What: /sys/class/rfkill/rfkill[0-9]+/claim
-Date: 09-Jul-2007
-KernelVersion v2.6.22
-Contact: linux-wireless@vger.kernel.org
-Description: This file is deprecated because there no longer is a way to
- claim just control over a single rfkill instance.
- This file is scheduled to be removed in 2012.
-Values: 0: Kernel handles events
diff --git a/Documentation/ABI/obsolete/sysfs-class-typec b/Documentation/ABI/obsolete/sysfs-class-typec
new file mode 100644
index 000000000000..32623514ee87
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-class-typec
@@ -0,0 +1,48 @@
+These files are deprecated and will be removed. The same files are available
+under /sys/bus/typec (see Documentation/ABI/testing/sysfs-bus-typec).
+
+What: /sys/class/typec/<port|partner|cable>/<dev>/svid
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The SVID (Standard or Vendor ID) assigned by USB-IF for this
+ alternate mode.
+
+What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Every supported mode will have its own directory. The name of
+ a mode will be "mode<index>" (for example mode1), where <index>
+ is the actual index to the mode VDO returned by Discover Modes
+ USB power delivery command.
+
+What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/description
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows description of the mode. The description is optional for
+ the drivers, just like with the Billboard Devices.
+
+What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/vdo
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows the VDO in hexadecimal returned by Discover Modes command
+ for this mode.
+
+What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/active
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows if the mode is active or not. The attribute can be used
+ for entering/exiting the mode with partners and cable plugs, and
+ with the port alternate modes it can be used for disabling
+ support for specific alternate modes. Entering/exiting modes is
+ supported as synchronous operation so write(2) to the attribute
+ does not return until the enter/exit mode operation has
+ finished. The attribute is notified when the mode is
+ entered/exited so poll(2) on the attribute wakes up.
+ Entering/exiting a mode will also generate uevent KOBJ_CHANGE.
+
+ Valid values: yes, no
diff --git a/Documentation/ABI/obsolete/sysfs-cpuidle b/Documentation/ABI/obsolete/sysfs-cpuidle
new file mode 100644
index 000000000000..972cc11d3434
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-cpuidle
@@ -0,0 +1,9 @@
+What: /sys/devices/system/cpu/cpuidle/current_governor_ro
+Date: April, 2020
+Contact: linux-pm@vger.kernel.org
+Description:
+ current_governor_ro shows current using cpuidle governor, but read only.
+ with the update that cpuidle governor can be changed at runtime in default,
+ both current_governor and current_governor_ro co-exist under
+ /sys/devices/system/cpu/cpuidle/ file, it's duplicate so make
+ current_governor_ro obsolete.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo
index 55e281b0071a..55e281b0071a 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku
index c601d0f2ac46..c601d0f2ac46 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus
index 833fd59926a7..545e69f43229 100644
--- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus
@@ -1,3 +1,14 @@
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/actual_profile
+Date: October 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The integer value of this attribute ranges from 0-4.
+ When read, this attribute returns the number of the actual
+ profile. This value is persistent, so its equivalent to the
+ profile that's active when the mouse is powered on next time.
+ When written, this file sets the number of the startup profile
+ and the mouse activates this profile immediately.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/startup_profile
Date: October 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -22,6 +33,40 @@ Description: When read, this file returns the raw integer version number of the
Please read binary attribute info which contains firmware version.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/info
+Date: November 2012
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: When read, this file returns general data like firmware version.
+ When written, the device can be reset.
+ The data is 8 bytes long.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro
+Date: October 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store a macro with max 500 key/button strokes
+ internally.
+ When written, this file lets one set the sequence for a specific
+ button for a specific profile. Button and profile numbers are
+ included in written data. The data has to be 2082 bytes long.
+ This file is writeonly.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_buttons
+Date: August 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store 5 profiles which can be switched by the
+ press of a button. A profile is split in settings and buttons.
+ profile_buttons holds information about button layout.
+ When written, this file lets one write the respective profile
+ buttons back to the mouse. The data has to be 77 bytes long.
+ The mouse will reject invalid data.
+ Which profile to write is determined by the profile number
+ contained in the data.
+ Before reading this file, control has to be written to select
+ which profile to read.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_buttons
Date: August 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -34,6 +79,22 @@ Description: The mouse can store 5 profiles which can be switched by the
Write control to select profile and read profile_buttons instead.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings
+Date: October 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store 5 profiles which can be switched by the
+ press of a button. A profile is split in settings and buttons.
+ profile_settings holds information like resolution, sensitivity
+ and light effects.
+ When written, this file lets one write the respective profile
+ settings back to the mouse. The data has to be 43 bytes long.
+ The mouse will reject invalid data.
+ Which profile to write is determined by the profile number
+ contained in the data.
+ Before reading this file, control has to be written to select
+ which profile to read.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_settings
Date: August 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -45,4 +106,40 @@ Description: The mouse can store 5 profiles which can be switched by the
The returned data is 43 bytes in size.
This file is readonly.
Write control to select profile and read profile_settings instead.
-Users: http://roccat.sourceforge.net \ No newline at end of file
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor
+Date: October 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse has a tracking- and a distance-control-unit. These
+ can be activated/deactivated and the lift-off distance can be
+ set. The data has to be 6 bytes long.
+ This file is writeonly.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/talk
+Date: May 2011
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: Used to active some easy* functions of the mouse from outside.
+ The data has to be 16 bytes long.
+ This file is writeonly.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu
+Date: October 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: When written a calibration process for the tracking control unit
+ can be initiated/cancelled. Also lets one read/write sensor
+ registers.
+ The data has to be 4 bytes long.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image
+Date: October 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: When read the mouse returns a 30x30 pixel image of the
+ sampled underground. This works only in the course of a
+ calibration process initiated with tcu.
+ The returned data is 1028 bytes in size.
+ This file is readonly.
+Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure
index 41a9b7fbfc79..41a9b7fbfc79 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus
index 4a98e02b6c6a..ab01631e1e0f 100644
--- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus
@@ -8,6 +8,17 @@ Description: The integer value of this attribute ranges from 1-4.
Has never been used. If bookkeeping is done, it's done in userland tools.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile
+Date: January 2011
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The integer value of this attribute ranges from 0-4.
+ When read, this attribute returns the number of the active
+ profile.
+ When written, the mouse activates this profile immediately.
+ The profile that's active when powered down is the same that's
+ active when the mouse is powered on.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_x
Date: January 2011
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -40,6 +51,29 @@ Description: When read, this file returns the raw integer version number of the
Obsoleted by binary sysfs attribute "info".
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/info
+Date: November 2012
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: When read, this file returns general data like firmware version.
+ When written, the device can be reset.
+ The data is 6 bytes long.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons
+Date: January 2011
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store 5 profiles which can be switched by the
+ press of a button. A profile is split in settings and buttons.
+ profile_buttons holds information about button layout.
+ When written, this file lets one write the respective profile
+ buttons back to the mouse. The data has to be 23 bytes long.
+ The mouse will reject invalid data.
+ Which profile to write is determined by the profile number
+ contained in the data.
+ Before reading this file, control has to be written to select
+ which profile to read.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_buttons
Date: January 2011
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -52,6 +86,22 @@ Description: The mouse can store 5 profiles which can be switched by the
Write control to select profile and read profile_buttons instead.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings
+Date: January 2011
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store 5 profiles which can be switched by the
+ press of a button. A profile is split in settings and buttons.
+ profile_settings holds information like resolution, sensitivity
+ and light effects.
+ When written, this file lets one write the respective profile
+ settings back to the mouse. The data has to be 16 bytes long.
+ The mouse will reject invalid data.
+ Which profile to write is determined by the profile number
+ contained in the data.
+ Before reading this file, control has to be written to select
+ which profile to read.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_settings
Date: January 2011
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua
index 31c6c4c8ba2b..31c6c4c8ba2b 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
index 87ac87e9556d..66545c587a64 100644
--- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
@@ -5,12 +5,15 @@ Description: It is possible to switch the cpi setting of the mouse with the
press of a button.
When read, this file returns the raw number of the actual cpi
setting reported by the mouse. This number has to be further
- processed to receive the real dpi value.
+ processed to receive the real dpi value:
+ ===== ====
VALUE DPI
+ ===== ====
1 400
2 800
4 1600
+ ===== ====
This file is readonly.
Has never been used. If bookkeeping is done, it's done in userland tools.
@@ -37,6 +40,29 @@ Description: When read, this file returns the raw integer version number of the
Please use binary attribute "info" which provides this information.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info
+Date: November 2012
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: When read, this file returns general data like firmware version.
+ When written, the device can be reset.
+ The data is 6 bytes long.
+Users: http://roccat.sourceforge.net
+
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons
+Date: August 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store 5 profiles which can be switched by the
+ press of a button. A profile is split in settings and buttons.
+ profile_buttons holds information about button layout.
+ When written, this file lets one write the respective profile
+ buttons back to the mouse. The data has to be 19 bytes long.
+ The mouse will reject invalid data.
+ Which profile to write is determined by the profile number
+ contained in the data.
+ Before reading this file, control has to be written to select
+ which profile to read.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_buttons
Date: August 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -49,6 +75,22 @@ Description: The mouse can store 5 profiles which can be switched by the
Write control to select profile and read profile_buttons instead.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings
+Date: August 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: The mouse can store 5 profiles which can be switched by the
+ press of a button. A profile is split in settings and buttons.
+ profile_settings holds information like resolution, sensitivity
+ and light effects.
+ When written, this file lets one write the respective profile
+ settings back to the mouse. The data has to be 13 bytes long.
+ The mouse will reject invalid data.
+ Which profile to write is determined by the profile number
+ contained in the data.
+ Before reading this file, control has to be written to select
+ which profile to read.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_settings
Date: August 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
@@ -62,6 +104,17 @@ Description: The mouse can store 5 profiles which can be switched by the
Write control to select profile and read profile_settings instead.
Users: http://roccat.sourceforge.net
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings
+Date: August 2010
+Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
+Description: When read, this file returns the settings stored in the mouse.
+ The size of the data is 3 bytes and holds information on the
+ startup_profile.
+ When written, this file lets write settings back to the mouse.
+ The data has to be 3 bytes long. The mouse will reject invalid
+ data.
+Users: http://roccat.sourceforge.net
+
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/startup_profile
Date: August 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-ryos b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos
index 1d6a8cf9dc0a..1d6a8cf9dc0a 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-ryos
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu
index f1e02a98bd9d..99fda67fce18 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu
@@ -3,9 +3,10 @@ Date: Mai 2012
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
Description: The mouse can store 5 profiles which can be switched by the
press of a button. A profile is split into general settings and
- button settings. buttons holds informations about button layout.
- When written, this file lets one write the respective profile
- buttons to the mouse. The data has to be 47 bytes long.
+ button settings. The buttons variable holds information about
+ button layout. When written, this file lets one write the
+ respective profile buttons to the mouse. The data has to be
+ 47 bytes long.
The mouse will reject invalid data.
Which profile to write is determined by the profile number
contained in the data.
@@ -26,8 +27,8 @@ Date: Mai 2012
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
Description: The mouse can store 5 profiles which can be switched by the
press of a button. A profile is split into general settings and
- button settings. profile holds informations like resolution, sensitivity
- and light effects.
+ button settings. A profile holds information like resolution,
+ sensitivity and light effects.
When written, this file lets one write the respective profile
settings back to the mouse. The data has to be 43 bytes long.
The mouse will reject invalid data.
diff --git a/Documentation/ABI/obsolete/sysfs-driver-intel_pmc_bxt b/Documentation/ABI/obsolete/sysfs-driver-intel_pmc_bxt
new file mode 100644
index 000000000000..39d5659f388b
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-driver-intel_pmc_bxt
@@ -0,0 +1,22 @@
+These files allow sending arbitrary IPC commands to the PMC/SCU which
+may be dangerous. These will be removed eventually and should not be
+used in any new applications.
+
+What: /sys/bus/platform/devices/INT34D2:00/simplecmd
+Date: Jun 2015
+KernelVersion: 4.1
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This interface allows userspace to send an arbitrary
+ IPC command to the PMC/SCU.
+
+ Format: %d %d where first number is command and
+ second number is subcommand.
+
+What: /sys/bus/platform/devices/INT34D2:00/northpeak
+Date: Jun 2015
+KernelVersion: 4.1
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This interface allows userspace to enable and disable
+ Northpeak through the PMC/SCU.
+
+ Format: %u.
diff --git a/Documentation/ABI/obsolete/sysfs-driver-samsung-laptop b/Documentation/ABI/obsolete/sysfs-driver-samsung-laptop
new file mode 100644
index 000000000000..204c3f3a1d78
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-driver-samsung-laptop
@@ -0,0 +1,10 @@
+What: /sys/devices/platform/samsung/battery_life_extender
+Date: December 1, 2011
+KernelVersion: 3.3
+Contact: Corentin Chary <corentin.chary@gmail.com>
+Description: Max battery charge level can be modified, battery cycle
+ life can be extended by reducing the max battery charge
+ level.
+
+ - 0 means normal battery mode (100% charge)
+ - 1 means battery life extender mode (80% charge)
diff --git a/Documentation/ABI/obsolete/sysfs-firmware-acpi b/Documentation/ABI/obsolete/sysfs-firmware-acpi
new file mode 100644
index 000000000000..6715a71bec3d
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-firmware-acpi
@@ -0,0 +1,8 @@
+What: /sys/firmware/acpi/hotplug/force_remove
+Date: Mar 2017
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ Since the force_remove is inherently broken and dangerous to
+ use for some hotplugable resources like memory (because ignoring
+ the offline failure might lead to memory corruption and crashes)
+ enabling this knob is not safe and thus unsupported.
diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio
new file mode 100644
index 000000000000..0d3f12c4dcbd
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -0,0 +1,40 @@
+What: /sys/class/gpio/
+Date: July 2008
+KernelVersion: 2.6.27
+Contact: Linus Walleij <linusw@kernel.org>
+Description:
+
+ As a Kconfig option, individual GPIO signals may be accessed from
+ userspace. GPIOs are only made available to userspace by an explicit
+ "export" operation. If a given GPIO is not claimed for use by
+ kernel code, it may be exported by userspace (and unexported later).
+ Kernel code may export it for complete or partial access.
+
+ GPIOs are identified as they are inside the kernel, using integers in
+ the range 0..INT_MAX. See Documentation/admin-guide/gpio for more information.
+
+ ::
+
+ /sys/class/gpio
+ /export ... asks the kernel to export a GPIO to userspace
+ /unexport ... to return a GPIO to the kernel
+ /gpioN ... for each exported GPIO #N OR
+ /value ... always readable, writes fail for input GPIOs
+ /direction ... r/w as: in, out (default low); write: high, low
+ /edge ... r/w as: none, falling, rising, both
+ /active_low ... r/w as: 0, 1
+ /gpiochipN ... for each gpiochip; #N is its first GPIO
+ /base ... (r/o) same as N
+ /label ... (r/o) descriptive chip name
+ /ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1)
+ /gpio<OFFSET>
+ /value ... always readable, writes fail for input GPIOs
+ /direction ... r/w as: in, out (default low); write: high, low
+ /chipX ... for each gpiochip; #X is the gpio device ID
+ /export ... asks the kernel to export a GPIO at HW offset X to userspace
+ /unexport ... to return a GPIO at HW offset X to the kernel
+ /label ... (r/o) descriptive chip name
+ /ngpio ... (r/o) number of GPIOs exposed by the chip
+
+ This ABI is obsoleted by Documentation/ABI/testing/gpio-cdev and will be
+ removed after 2020.
diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_enabled b/Documentation/ABI/obsolete/sysfs-kernel-fadump_enabled
new file mode 100644
index 000000000000..e9c2de8b3688
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_enabled
@@ -0,0 +1,9 @@
+This ABI is renamed and moved to a new location /sys/kernel/fadump/enabled.
+
+What: /sys/kernel/fadump_enabled
+Date: Feb 2012
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Primarily used to identify whether the FADump is enabled in
+ the kernel or not.
+User: Kdump service
diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered b/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered
new file mode 100644
index 000000000000..dae880b1a5d5
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered
@@ -0,0 +1,10 @@
+This ABI is renamed and moved to a new location /sys/kernel/fadump/registered.
+
+What: /sys/kernel/fadump_registered
+Date: Feb 2012
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Helps to control the dump collect feature from userspace.
+ Setting 1 to this file enables the system to collect the
+ dump and 0 to disable it.
+User: Kdump service
diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem b/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem
new file mode 100644
index 000000000000..ca2396edb5f1
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem
@@ -0,0 +1,10 @@
+This ABI is renamed and moved to a new location /sys/kernel/fadump/release_mem.
+
+What: /sys/kernel/fadump_release_mem
+Date: Feb 2012
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: write only
+ This is a special sysfs file and only available when
+ the system is booted to capture the vmcore using FADump.
+ It is used to release the memory reserved by FADump to
+ save the crash dump.
diff --git a/Documentation/ABI/obsolete/sysfs-kernel-kexec-kdump b/Documentation/ABI/obsolete/sysfs-kernel-kexec-kdump
new file mode 100644
index 000000000000..ba26a6a1d2be
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-kernel-kexec-kdump
@@ -0,0 +1,71 @@
+NOTE: all the ABIs listed in this file are deprecated and will be removed after 2028.
+
+Here are the alternative ABIs:
++------------------------------------+-----------------------------------------+
+| Deprecated | Alternative |
++------------------------------------+-----------------------------------------+
+| /sys/kernel/kexec_loaded | /sys/kernel/kexec/loaded |
++------------------------------------+-----------------------------------------+
+| /sys/kernel/kexec_crash_loaded | /sys/kernel/kexec/crash_loaded |
++------------------------------------+-----------------------------------------+
+| /sys/kernel/kexec_crash_size | /sys/kernel/kexec/crash_size |
++------------------------------------+-----------------------------------------+
+| /sys/kernel/crash_elfcorehdr_size | /sys/kernel/kexec/crash_elfcorehdr_size |
++------------------------------------+-----------------------------------------+
+| /sys/kernel/kexec_crash_cma_ranges | /sys/kernel/kexec/crash_cma_ranges |
++------------------------------------+-----------------------------------------+
+
+
+What: /sys/kernel/kexec_loaded
+Date: Jun 2006
+Contact: kexec@lists.infradead.org
+Description: read only
+ Indicates whether a new kernel image has been loaded
+ into memory using the kexec system call. It shows 1 if
+ a kexec image is present and ready to boot, or 0 if none
+ is loaded.
+User: kexec tools, kdump service
+
+What: /sys/kernel/kexec_crash_loaded
+Date: Jun 2006
+Contact: kexec@lists.infradead.org
+Description: read only
+ Indicates whether a crash (kdump) kernel is currently
+ loaded into memory. It shows 1 if a crash kernel has been
+ successfully loaded for panic handling, or 0 if no crash
+ kernel is present.
+User: Kexec tools, Kdump service
+
+What: /sys/kernel/kexec_crash_size
+Date: Dec 2009
+Contact: kexec@lists.infradead.org
+Description: read/write
+ Shows the amount of memory reserved for loading the crash
+ (kdump) kernel. It reports the size, in bytes, of the
+ crash kernel area defined by the crashkernel= parameter.
+ This interface also allows reducing the crashkernel
+ reservation by writing a smaller value, and the reclaimed
+ space is added back to the system RAM.
+User: Kdump service
+
+What: /sys/kernel/crash_elfcorehdr_size
+Date: Aug 2023
+Contact: kexec@lists.infradead.org
+Description: read only
+ Indicates the preferred size of the memory buffer for the
+ ELF core header used by the crash (kdump) kernel. It defines
+ how much space is needed to hold metadata about the crashed
+ system, including CPU and memory information. This information
+ is used by the user space utility kexec to support updating the
+ in-kernel kdump image during hotplug operations.
+User: Kexec tools
+
+What: /sys/kernel/kexec_crash_cma_ranges
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description: read only
+ Provides information about the memory ranges reserved from
+ the Contiguous Memory Allocator (CMA) area that are allocated
+ to the crash (kdump) kernel. It lists the start and end physical
+ addresses of CMA regions assigned for crashkernel use.
+User: kdump service
diff --git a/Documentation/ABI/obsolete/sysfs-platform-ideapad-laptop b/Documentation/ABI/obsolete/sysfs-platform-ideapad-laptop
new file mode 100644
index 000000000000..c1dbd19c679c
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-platform-ideapad-laptop
@@ -0,0 +1,8 @@
+What: /sys/bus/platform/devices/VPC2004:*/conservation_mode
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: platform-driver-x86@vger.kernel.org
+Description:
+ Controls whether the conservation mode is enabled or not.
+ This feature limits the maximum battery charge percentage to
+ around 50-60% in order to prolong the lifetime of the battery.
diff --git a/Documentation/ABI/obsolete/sysfs-selinux-user b/Documentation/ABI/obsolete/sysfs-selinux-user
new file mode 100644
index 000000000000..8ab7557f283f
--- /dev/null
+++ b/Documentation/ABI/obsolete/sysfs-selinux-user
@@ -0,0 +1,12 @@
+What: /sys/fs/selinux/user
+Date: April 2005 (predates git)
+KernelVersion: 2.6.12-rc2 (predates git)
+Contact: selinux@vger.kernel.org
+Description:
+
+ The selinuxfs "user" node allows userspace to request a list
+ of security contexts that can be reached for a given SELinux
+ user from a given starting context. This was used by libselinux
+ when various login-style programs requested contexts for
+ users, but libselinux stopped using it in 2020.
+ Kernel support will be removed no sooner than Dec 2025.
diff --git a/Documentation/ABI/removed/devfs b/Documentation/ABI/removed/devfs
index 0020c49933c4..24fb35adf277 100644
--- a/Documentation/ABI/removed/devfs
+++ b/Documentation/ABI/removed/devfs
@@ -5,6 +5,7 @@ Description:
devfs has been unmaintained for a number of years, has unfixable
races, contains a naming policy within the kernel that is
against the LSB, and can be replaced by using udev.
+
The files fs/devfs/*, include/linux/devfs_fs*.h were removed,
along with the assorted devfs function calls throughout the
kernel tree.
diff --git a/Documentation/ABI/removed/o2cb b/Documentation/ABI/removed/o2cb
index 20c91adca6d4..61cff238fbe8 100644
--- a/Documentation/ABI/removed/o2cb
+++ b/Documentation/ABI/removed/o2cb
@@ -1,10 +1,10 @@
What: /sys/o2cb symlink
Date: May 2011
KernelVersion: 3.0
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description: This is a symlink: /sys/o2cb to /sys/fs/o2cb. The symlink is
removed when new versions of ocfs2-tools which know to look
in /sys/fs/o2cb are sufficiently prevalent. Don't code new
software to look here, it should try /sys/fs/o2cb instead.
Users: ocfs2-tools. It's sufficient to mail proposed changes to
- ocfs2-devel@oss.oracle.com.
+ ocfs2-devel@lists.linux.dev.
diff --git a/Documentation/ABI/removed/raw1394 b/Documentation/ABI/removed/raw1394
index ec333e676322..9ec7ec493920 100644
--- a/Documentation/ABI/removed/raw1394
+++ b/Documentation/ABI/removed/raw1394
@@ -7,6 +7,7 @@ Description:
to implement sensible device security policies, and its low level
of abstraction that required userspace clients to duplicate much
of the kernel's ieee1394 core functionality.
+
Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of
firewire-core.
diff --git a/Documentation/ABI/removed/sysfs-bus-nfit b/Documentation/ABI/removed/sysfs-bus-nfit
new file mode 100644
index 000000000000..277437005def
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-bus-nfit
@@ -0,0 +1,17 @@
+What: /sys/bus/nd/devices/regionX/nfit/ecc_unit_size
+Date: Aug, 2017
+KernelVersion: v4.14 (Removed v4.18)
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Size of a write request to a DIMM that will not incur a
+ read-modify-write cycle at the memory controller.
+
+ When the nfit driver initializes it runs an ARS (Address Range
+ Scrub) operation across every pmem range. Part of that process
+ involves determining the ARS capabilities of a given address
+ range. One of the capabilities that is reported is the 'Clear
+ Uncorrectable Error Range Length Unit Size' (see: ACPI 6.2
+ section 9.20.7.4 Function Index 1 - Query ARS Capabilities).
+ This property indicates the boundary at which the NVDIMM may
+ need to perform read-modify-write cycles to maintain ECC (Error
+ Correcting Code) blocks.
diff --git a/Documentation/ABI/removed/sysfs-class-cxl b/Documentation/ABI/removed/sysfs-class-cxl
new file mode 100644
index 000000000000..266c413b96e8
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-class-cxl
@@ -0,0 +1,272 @@
+The cxl driver was removed in 6.15.
+
+Please note that attributes that are shared between devices are stored in
+the directory pointed to by the symlink device/.
+For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
+/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
+
+
+Slave contexts (eg. /sys/class/cxl/afu0.0s):
+
+What: /sys/class/cxl/<afu>/afu_err_buf
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ AFU Error Buffer contents. The contents of this file are
+ application specific and depends on the AFU being used.
+ Applications interacting with the AFU can use this attribute
+ to know about the current error condition and take appropriate
+ action like logging the event etc.
+
+
+What: /sys/class/cxl/<afu>/irqs_max
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Decimal value of maximum number of interrupts that can be
+ requested by userspace. The default on probe is the maximum
+ that hardware can support (eg. 2037). Write values will limit
+ userspace applications to that many userspace interrupts. Must
+ be >= irqs_min.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/irqs_min
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Decimal value of the minimum number of interrupts that
+ userspace must request on a CXL_START_WORK ioctl. Userspace may
+ omit the num_interrupts field in the START_WORK IOCTL to get
+ this minimum automatically.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/mmio_size
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Decimal value of the size of the MMIO space that may be mmapped
+ by userspace.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/modes_supported
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ List of the modes this AFU supports. One per line.
+ Valid entries are: "dedicated_process" and "afu_directed"
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/mode
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ The current mode the AFU is using. Will be one of the modes
+ given in modes_supported. Writing will change the mode
+ provided that no user contexts are attached.
+Users: https://github.com/ibm-capi/libcxl
+
+
+What: /sys/class/cxl/<afu>/prefault_mode
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Set the mode for prefaulting in segments into the segment table
+ when performing the START_WORK ioctl. Only applicable when
+ running under hashed page table mmu.
+ Possible values:
+
+ ======================= ======================================
+ none No prefaulting (default)
+ work_element_descriptor Treat the work element
+ descriptor as an effective address and
+ prefault what it points to.
+ all all segments process calling
+ START_WORK maps.
+ ======================= ======================================
+
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/reset
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: write only
+ Writing 1 here will reset the AFU provided there are not
+ contexts active on the AFU.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/api_version
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Decimal value of the current version of the kernel/user API.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/api_version_compatible
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Decimal value of the lowest version of the userspace API
+ this kernel supports.
+Users: https://github.com/ibm-capi/libcxl
+
+
+AFU configuration records (eg. /sys/class/cxl/afu0.0/cr0):
+
+An AFU may optionally export one or more PCIe like configuration records, known
+as AFU configuration records, which will show up here (if present).
+
+What: /sys/class/cxl/<afu>/cr<config num>/vendor
+Date: February 2015, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Hexadecimal value of the vendor ID found in this AFU
+ configuration record.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/cr<config num>/device
+Date: February 2015, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Hexadecimal value of the device ID found in this AFU
+ configuration record.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/cr<config num>/class
+Date: February 2015, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Hexadecimal value of the class code found in this AFU
+ configuration record.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>/cr<config num>/config
+Date: February 2015, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ This binary file provides raw access to the AFU configuration
+ record. The format is expected to match the either the standard
+ or extended configuration space defined by the PCIe
+ specification.
+Users: https://github.com/ibm-capi/libcxl
+
+
+
+Master contexts (eg. /sys/class/cxl/afu0.0m)
+
+What: /sys/class/cxl/<afu>m/mmio_size
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Decimal value of the size of the MMIO space that may be mmapped
+ by userspace. This includes all slave contexts space also.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>m/pp_mmio_len
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Decimal value of the Per Process MMIO space length.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<afu>m/pp_mmio_off
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ (not in a guest)
+ Decimal value of the Per Process MMIO space offset.
+Users: https://github.com/ibm-capi/libcxl
+
+
+Card info (eg. /sys/class/cxl/card0)
+
+What: /sys/class/cxl/<card>/caia_version
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Identifies the CAIA Version the card implements.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/psl_revision
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Identifies the revision level of the PSL.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/base_image
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ (not in a guest)
+ Identifies the revision level of the base image for devices
+ that support loadable PSLs. For FPGAs this field identifies
+ the image contained in the on-adapter flash which is loaded
+ during the initial program load.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/image_loaded
+Date: September 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ (not in a guest)
+ Will return "user" or "factory" depending on the image loaded
+ onto the card.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/load_image_on_perst
+Date: December 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ (not in a guest)
+ Valid entries are "none", "user", and "factory".
+ "none" means PERST will not cause image to be loaded to the
+ card. A power cycle is required to load the image.
+ "none" could be useful for debugging because the trace arrays
+ are preserved.
+
+ "user" and "factory" means PERST will cause either the user or
+ user or factory image to be loaded.
+ Default is to reload on PERST whichever image the card has
+ loaded.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/reset
+Date: October 2014, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: write only
+ Writing 1 will issue a PERST to card provided there are no
+ contexts active on any one of the card AFUs. This may cause
+ the card to reload the FPGA depending on load_image_on_perst.
+ Writing -1 will do a force PERST irrespective of any active
+ contexts on the card AFUs.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/perst_reloads_same_image
+Date: July 2015, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ (not in a guest)
+ Trust that when an image is reloaded via PERST, it will not
+ have changed.
+
+ == =================================================
+ 0 don't trust, the image may be different (default)
+ 1 trust that the image will not change.
+ == =================================================
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/psl_timebase_synced
+Date: March 2016, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Returns 1 if the psl timebase register is synchronized
+ with the core timebase register, 0 otherwise.
+Users: https://github.com/ibm-capi/libcxl
+
+What: /sys/class/cxl/<card>/tunneled_ops_supported
+Date: May 2018, removed February 2025
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Returns 1 if tunneled operations are supported in capi mode,
+ 0 otherwise.
+Users: https://github.com/ibm-capi/libcxl
diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill
new file mode 100644
index 000000000000..20cb688af173
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-class-rfkill
@@ -0,0 +1,13 @@
+rfkill - radio frequency (RF) connector kill switch support
+
+For details to this subsystem look at Documentation/driver-api/rfkill.rst.
+
+What: /sys/class/rfkill/rfkill[0-9]+/claim
+Date: 09-Jul-2007
+KernelVersion: v2.6.22
+Contact: linux-wireless@vger.kernel.org
+Description: This file was deprecated because there no longer was a way to
+ claim just control over a single rfkill instance.
+ This file was scheduled to be removed in 2012, and was removed
+ in 2016.
+Values: 0: Kernel handles events
diff --git a/Documentation/ABI/removed/sysfs-firmware-efi-vars b/Documentation/ABI/removed/sysfs-firmware-efi-vars
new file mode 100644
index 000000000000..8d97368b149b
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-firmware-efi-vars
@@ -0,0 +1,12 @@
+What: /sys/firmware/efi/vars
+Date: April 2004, removed March 2023
+Description:
+ This directory exposed interfaces for interacting with
+ EFI variables. For more information on EFI variables,
+ see 'Variable Services' in the UEFI specification
+ (section 7.2 in specification version 2.3 Errata D).
+
+ The 'efivars' sysfs interface was removed in March of 2023,
+ after being considered deprecated no later than September
+ of 2020. Its functionality has been replaced by the
+ 'efivarfs' filesystem.
diff --git a/Documentation/ABI/removed/sysfs-kernel-fadump_release_opalcore b/Documentation/ABI/removed/sysfs-kernel-fadump_release_opalcore
new file mode 100644
index 000000000000..a8d46cd0f4e6
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-kernel-fadump_release_opalcore
@@ -0,0 +1,9 @@
+This ABI is moved to /sys/firmware/opal/mpipl/release_core.
+
+What: /sys/kernel/fadump_release_opalcore
+Date: Sep 2019
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: write only
+ The sysfs file is available when the system is booted to
+ collect the dump on OPAL based machine. It used to release
+ the memory used to collect the opalcore.
diff --git a/Documentation/ABI/testing/sysfs-kernel-uids b/Documentation/ABI/removed/sysfs-kernel-uids
index 28f14695a852..85a90b86ce1e 100644
--- a/Documentation/ABI/testing/sysfs-kernel-uids
+++ b/Documentation/ABI/removed/sysfs-kernel-uids
@@ -1,14 +1,14 @@
What: /sys/kernel/uids/<uid>/cpu_shares
-Date: December 2007
+Date: December 2007, finally removed in kernel v2.6.34-rc1
Contact: Dhaval Giani <dhaval@linux.vnet.ibm.com>
Srivatsa Vaddagiri <vatsa@linux.vnet.ibm.com>
Description:
The /sys/kernel/uids/<uid>/cpu_shares tunable is used
to set the cpu bandwidth a user is allowed. This is a
- propotional value. What that means is that if there
+ proportional value. What that means is that if there
are two users logged in, each with an equal number of
shares, then they will get equal CPU bandwidth. Another
example would be, if User A has shares = 1024 and user
B has shares = 2048, User B will get twice the CPU
bandwidth user A will. For more details refer
- Documentation/scheduler/sched-design-CFS.txt
+ Documentation/scheduler/sched-design-CFS.rst
diff --git a/Documentation/ABI/removed/sysfs-mce b/Documentation/ABI/removed/sysfs-mce
new file mode 100644
index 000000000000..ef5dd2a80918
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-mce
@@ -0,0 +1,37 @@
+What: /sys/devices/system/machinecheck/machinecheckX/tolerant
+Contact: Borislav Petkov <bp@suse.de>
+Date: Dec, 2021
+Description:
+ Unused and obsolete after the advent of recoverable machine
+ checks (see last sentence below) and those are present since
+ 2010 (Nehalem).
+
+ Original description:
+
+ The entries appear for each CPU, but they are truly shared
+ between all CPUs.
+
+ Tolerance level. When a machine check exception occurs for a
+ non corrected machine check the kernel can take different
+ actions.
+
+ Since machine check exceptions can happen any time it is
+ sometimes risky for the kernel to kill a process because it
+ defies normal kernel locking rules. The tolerance level
+ configures how hard the kernel tries to recover even at some
+ risk of deadlock. Higher tolerant values trade potentially
+ better uptime with the risk of a crash or even corruption
+ (for tolerant >= 3).
+
+ == ===========================================================
+ 0 always panic on uncorrected errors, log corrected errors
+ 1 panic or SIGBUS on uncorrected errors, log corrected errors
+ 2 SIGBUS or log uncorrected errors, log corrected errors
+ 3 never panic or SIGBUS, log all errors (for testing only)
+ == ===========================================================
+
+ Default: 1
+
+ Note this only makes a difference if the CPU allows recovery
+ from a machine check exception. Current x86 CPUs generally
+ do not.
diff --git a/Documentation/ABI/removed/sysfs-selinux-checkreqprot b/Documentation/ABI/removed/sysfs-selinux-checkreqprot
new file mode 100644
index 000000000000..f599a0a87e8b
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-selinux-checkreqprot
@@ -0,0 +1,26 @@
+What: /sys/fs/selinux/checkreqprot
+Date: April 2005 (predates git)
+KernelVersion: 2.6.12-rc2 (predates git)
+Contact: selinux@vger.kernel.org
+Description:
+
+ REMOVAL UPDATE: The SELinux checkreqprot functionality was removed in
+ March 2023, the original deprecation notice is shown below.
+
+ The selinuxfs "checkreqprot" node allows SELinux to be configured
+ to check the protection requested by userspace for mmap/mprotect
+ calls instead of the actual protection applied by the kernel.
+ This was a compatibility mechanism for legacy userspace and
+ for the READ_IMPLIES_EXEC personality flag. However, if set to
+ 1, it weakens security by allowing mappings to be made executable
+ without authorization by policy. The default value of checkreqprot
+ at boot was changed starting in Linux v4.4 to 0 (i.e. check the
+ actual protection), and Android and Linux distributions have been
+ explicitly writing a "0" to /sys/fs/selinux/checkreqprot during
+ initialization for some time. Support for setting checkreqprot to 1
+ will be removed no sooner than June 2021, at which point the kernel
+ will always cease using checkreqprot internally and will always
+ check the actual protections being applied upon mmap/mprotect calls.
+ The checkreqprot selinuxfs node will remain for backward compatibility
+ but will discard writes of the "0" value and will reject writes of the
+ "1" value when this mechanism is removed.
diff --git a/Documentation/ABI/removed/sysfs-selinux-disable b/Documentation/ABI/removed/sysfs-selinux-disable
new file mode 100644
index 000000000000..cb783c64cab3
--- /dev/null
+++ b/Documentation/ABI/removed/sysfs-selinux-disable
@@ -0,0 +1,29 @@
+What: /sys/fs/selinux/disable
+Date: April 2005 (predates git)
+KernelVersion: 2.6.12-rc2 (predates git)
+Contact: selinux@vger.kernel.org
+Description:
+
+ REMOVAL UPDATE: The SELinux runtime disable functionality was removed
+ in March 2023, the original deprecation notice is shown below.
+
+ The selinuxfs "disable" node allows SELinux to be disabled at runtime
+ prior to a policy being loaded into the kernel. If disabled via this
+ mechanism, SELinux will remain disabled until the system is rebooted.
+
+ The preferred method of disabling SELinux is via the "selinux=0" boot
+ parameter, but the selinuxfs "disable" node was created to make it
+ easier for systems with primitive bootloaders that did not allow for
+ easy modification of the kernel command line. Unfortunately, allowing
+ for SELinux to be disabled at runtime makes it difficult to secure the
+ kernel's LSM hooks using the "__ro_after_init" feature.
+
+ Thankfully, the need for the SELinux runtime disable appears to be
+ gone, the default Kconfig configuration disables this selinuxfs node,
+ and only one of the major distributions, Fedora, supports disabling
+ SELinux at runtime. Fedora is in the process of removing the
+ selinuxfs "disable" node and once that is complete we will start the
+ slow process of removing this code from the kernel.
+
+ More information on /sys/fs/selinux/disable can be found under the
+ CONFIG_SECURITY_SELINUX_DISABLE Kconfig option.
diff --git a/Documentation/ABI/removed/video1394 b/Documentation/ABI/removed/video1394
index c39c25aee77b..1905d35a6619 100644
--- a/Documentation/ABI/removed/video1394
+++ b/Documentation/ABI/removed/video1394
@@ -8,6 +8,7 @@ Description:
performance issues in its first generation. Any video1394 user had
to use raw1394 + libraw1394 too because video1394 did not provide
asynchronous I/O for device discovery and configuration.
+
Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of
firewire-core.
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
index 16d030827368..261f85b13154 100644
--- a/Documentation/ABI/stable/firewire-cdev
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -14,13 +14,17 @@ Description:
Each /dev/fw* is associated with one IEEE 1394 node, which can
be remote or local nodes. Operations on a /dev/fw* file have
different scope:
+
- The 1394 node which is associated with the file:
+
- Asynchronous request transmission
- Get the Configuration ROM
- Query node ID
- Query maximum speed of the path between this node
and local node
+
- The 1394 bus (i.e. "card") to which the node is attached to:
+
- Isochronous stream transmission and reception
- Asynchronous stream transmission and reception
- Asynchronous broadcast request transmission
@@ -31,7 +35,9 @@ Description:
manager
- Query cycle time
- Bus reset initiation, bus reset event reception
+
- All 1394 buses:
+
- Allocation of IEEE 1212 address ranges on the local
link layers, reception of inbound requests to such
an address range, asynchronous response transmission
@@ -43,6 +49,7 @@ Description:
userland implement different access permission models, some
operations are restricted to /dev/fw* files that are associated
with a local node:
+
- Addition of descriptors or directories to the local
nodes' Configuration ROM
- PHY packet transmission and reception
@@ -55,49 +62,50 @@ Description:
The following file operations are supported:
open(2)
- Currently the only useful flags are O_RDWR.
+ Currently the only useful flags are O_RDWR.
ioctl(2)
- Initiate various actions. Some take immediate effect, others
- are performed asynchronously while or after the ioctl returns.
- See the inline documentation in <linux/firewire-cdev.h> for
- descriptions of all ioctls.
+ Initiate various actions. Some take immediate effect, others
+ are performed asynchronously while or after the ioctl returns.
+ See the inline documentation in <linux/firewire-cdev.h> for
+ descriptions of all ioctls.
poll(2), select(2), epoll_wait(2) etc.
- Watch for events to become available to be read.
+ Watch for events to become available to be read.
read(2)
- Receive various events. There are solicited events like
- outbound asynchronous transaction completion or isochronous
- buffer completion, and unsolicited events such as bus resets,
- request reception, or PHY packet reception. Always use a read
- buffer which is large enough to receive the largest event that
- could ever arrive. See <linux/firewire-cdev.h> for descriptions
- of all event types and for which ioctls affect reception of
- events.
+ Receive various events. There are solicited events like
+ outbound asynchronous transaction completion or isochronous
+ buffer completion, and unsolicited events such as bus resets,
+ request reception, or PHY packet reception. Always use a read
+ buffer which is large enough to receive the largest event that
+ could ever arrive. See <linux/firewire-cdev.h> for descriptions
+ of all event types and for which ioctls affect reception of
+ events.
mmap(2)
- Allocate a DMA buffer for isochronous reception or transmission
- and map it into the process address space. The arguments should
- be used as follows: addr = NULL, length = the desired buffer
- size, i.e. number of packets times size of largest packet,
- prot = at least PROT_READ for reception and at least PROT_WRITE
- for transmission, flags = MAP_SHARED, fd = the handle to the
- /dev/fw*, offset = 0.
+ Allocate a DMA buffer for isochronous reception or transmission
+ and map it into the process address space. The arguments should
+ be used as follows: addr = NULL, length = the desired buffer
+ size, i.e. number of packets times size of largest packet,
+ prot = at least PROT_READ for reception and at least PROT_WRITE
+ for transmission, flags = MAP_SHARED, fd = the handle to the
+ /dev/fw*, offset = 0.
Isochronous reception works in packet-per-buffer fashion except
for multichannel reception which works in buffer-fill mode.
munmap(2)
- Unmap the isochronous I/O buffer from the process address space.
+ Unmap the isochronous I/O buffer from the process address space.
close(2)
- Besides stopping and freeing I/O contexts that were associated
- with the file descriptor, back out any changes to the local
- nodes' Configuration ROM. Deallocate isochronous channels and
- bandwidth at the IRM that were marked for kernel-assisted
- re- and deallocation.
-
-Users: libraw1394
- libdc1394
- tools like jujuutils, fwhack, ...
+ Besides stopping and freeing I/O contexts that were associated
+ with the file descriptor, back out any changes to the local
+ nodes' Configuration ROM. Deallocate isochronous channels and
+ bandwidth at the IRM that were marked for kernel-assisted
+ re- and deallocation.
+
+Users: libraw1394;
+ libdc1394;
+ libhinawa;
+ tools like linux-firewire-utils, fwhack, ...
diff --git a/Documentation/ABI/stable/o2cb b/Documentation/ABI/stable/o2cb
index 5eb1545e0b8d..3a83b5c54e93 100644
--- a/Documentation/ABI/stable/o2cb
+++ b/Documentation/ABI/stable/o2cb
@@ -1,10 +1,10 @@
-What: /sys/fs/o2cb/ (was /sys/o2cb)
+What: /sys/fs/o2cb/
Date: Dec 2005
KernelVersion: 2.6.16
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description: Ocfs2-tools looks at 'interface-revision' for versioning
information. Each logmask/ file controls a set of debug prints
and can be written into with the strings "allow", "deny", or
"off". Reading the file returns the current state.
Users: ocfs2-tools. It's sufficient to mail proposed changes to
- ocfs2-devel@oss.oracle.com.
+ ocfs2-devel@lists.linux.dev.
diff --git a/Documentation/ABI/stable/procfs-audit_loginuid b/Documentation/ABI/stable/procfs-audit_loginuid
new file mode 100644
index 000000000000..cda405178391
--- /dev/null
+++ b/Documentation/ABI/stable/procfs-audit_loginuid
@@ -0,0 +1,27 @@
+What: Audit Login UID
+Date: 2005-02-01
+KernelVersion: 2.6.11-rc2 1e2d1492e178 ("[PATCH] audit: handle loginuid through proc")
+Contact: linux-audit@redhat.com
+Users: audit and login applications
+Description:
+ The /proc/$pid/loginuid pseudofile is written to set and
+ read to get the audit login UID of process $pid as a
+ decimal unsigned int (%u, u32). If it is unset,
+ permissions are not needed to set it. The accessor must
+ have CAP_AUDIT_CONTROL in the initial user namespace to
+ write it if it has been set. It cannot be written again
+ if AUDIT_FEATURE_LOGINUID_IMMUTABLE is enabled. It
+ cannot be unset if AUDIT_FEATURE_ONLY_UNSET_LOGINUID is
+ enabled.
+
+What: Audit Login Session ID
+Date: 2008-03-13
+KernelVersion: 2.6.25-rc7 1e0bd7550ea9 ("[PATCH] export sessionid alongside the loginuid in procfs")
+Contact: linux-audit@redhat.com
+Users: audit and login applications
+Description:
+ The /proc/$pid/sessionid pseudofile is read to get the
+ audit login session ID of process $pid as a decimal
+ unsigned int (%u, u32). It is set automatically,
+ serially assigned with each new login.
+
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile
index 964c7a8afb26..cd55e421d921 100644
--- a/Documentation/ABI/stable/sysfs-acpi-pmprofile
+++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -1,22 +1,28 @@
-What: /sys/firmware/acpi/pm_profile
+What: /sys/firmware/acpi/pm_profile
Date: 03-Nov-2011
KernelVersion: v3.2
Contact: linux-acpi@vger.kernel.org
-Description: The ACPI pm_profile sysfs interface exports the platform
- power management (and performance) requirement expectations
- as provided by BIOS. The integer value is directly passed as
- retrieved from the FADT ACPI table.
-Values: For possible values see ACPI specification:
- 5.2.9 Fixed ACPI Description Table (FADT)
- Field: Preferred_PM_Profile
+Description: The ACPI pm_profile sysfs interface exposes the preferred
+ power management (and performance) profile of the platform
+ as provided in the ACPI FADT Preferred_PM_Profile field.
- Currently these values are defined by spec:
- 0 Unspecified
- 1 Desktop
- 2 Mobile
- 3 Workstation
- 4 Enterprise Server
- 5 SOHO Server
- 6 Appliance PC
- 7 Performance Server
- >7 Reserved
+ The integer value is directly passed as retrieved from the FADT.
+
+Values: For the possible values refer to the Preferred_PM_Profile field
+ definition in Table 5.9 "FADT Format", Section 5.2.9 "Fixed ACPI
+ Description Table (FADT)" of the ACPI specification.
+
+ As of ACPI 6.5, the following values are defined:
+
+ == =================
+ 0 Unspecified
+ 1 Desktop
+ 2 Mobile
+ 3 Workstation
+ 4 Enterprise Server
+ 5 SOHO Server
+ 6 Appliance PC
+ 7 Performance Server
+ 8 Tablet
+ >8 Reserved
+ == =================
diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block
new file mode 100644
index 000000000000..0ed10aeff86b
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-block
@@ -0,0 +1,881 @@
+What: /sys/block/<disk>/alignment_offset
+Date: April 2009
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Storage devices may report a physical block size that is
+ bigger than the logical block size (for instance a drive
+ with 4KB physical sectors exposing 512-byte logical
+ blocks to the operating system). This parameter
+ indicates how many bytes the beginning of the device is
+ offset from the disk's natural alignment.
+
+
+What: /sys/block/<disk>/discard_alignment
+Date: May 2011
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Devices that support discard functionality may
+ internally allocate space in units that are bigger than
+ the exported logical block size. The discard_alignment
+ parameter indicates how many bytes the beginning of the
+ device is offset from the internal allocation unit's
+ natural alignment.
+
+What: /sys/block/<disk>/atomic_write_max_bytes
+Date: February 2024
+Contact: Himanshu Madhani <himanshu.madhani@oracle.com>
+Description:
+ [RO] This parameter specifies the maximum atomic write
+ size reported by the device. This parameter is relevant
+ for merging of writes, where a merged atomic write
+ operation must not exceed this number of bytes.
+ This parameter may be greater than the value in
+ atomic_write_unit_max_bytes as
+ atomic_write_unit_max_bytes will be rounded down to a
+ power-of-two and atomic_write_unit_max_bytes may also be
+ limited by some other queue limits, such as max_segments.
+ This parameter - along with atomic_write_unit_min_bytes
+ and atomic_write_unit_max_bytes - will not be larger than
+ max_hw_sectors_kb, but may be larger than max_sectors_kb.
+
+
+What: /sys/block/<disk>/atomic_write_unit_min_bytes
+Date: February 2024
+Contact: Himanshu Madhani <himanshu.madhani@oracle.com>
+Description:
+ [RO] This parameter specifies the smallest block which can
+ be written atomically with an atomic write operation. All
+ atomic write operations must begin at a
+ atomic_write_unit_min boundary and must be multiples of
+ atomic_write_unit_min. This value must be a power-of-two.
+
+
+What: /sys/block/<disk>/atomic_write_unit_max_bytes
+Date: February 2024
+Contact: Himanshu Madhani <himanshu.madhani@oracle.com>
+Description:
+ [RO] This parameter defines the largest block which can be
+ written atomically with an atomic write operation. This
+ value must be a multiple of atomic_write_unit_min and must
+ be a power-of-two. This value will not be larger than
+ atomic_write_max_bytes.
+
+
+What: /sys/block/<disk>/atomic_write_boundary_bytes
+Date: February 2024
+Contact: Himanshu Madhani <himanshu.madhani@oracle.com>
+Description:
+ [RO] A device may need to internally split an atomic write I/O
+ which straddles a given logical block address boundary. This
+ parameter specifies the size in bytes of the atomic boundary if
+ one is reported by the device. This value must be a
+ power-of-two and at least the size as in
+ atomic_write_unit_max_bytes.
+ Any attempt to merge atomic write I/Os must not result in a
+ merged I/O which crosses this boundary (if any).
+
+
+What: /sys/block/<disk>/diskseq
+Date: February 2021
+Contact: Matteo Croce <teknoraver@meta.com>
+Description:
+ The /sys/block/<disk>/diskseq files reports the disk
+ sequence number, which is a monotonically increasing
+ number assigned to every drive.
+ Some devices, like the loop device, refresh such number
+ every time the backing file is changed.
+ The value type is 64 bit unsigned.
+
+
+What: /sys/block/<disk>/inflight
+Date: October 2009
+Contact: Jens Axboe <axboe@kernel.dk>, Nikanth Karthikesan <knikanth@suse.de>
+Description:
+ Reports the number of I/O requests currently in progress
+ (pending / in flight) in a device driver. This can be less
+ than the number of requests queued in the block device queue.
+ The report contains 2 fields: one for read requests
+ and one for write requests.
+ The value type is unsigned int.
+ Cf. Documentation/block/stat.rst which contains a single value for
+ requests in flight.
+ This is related to /sys/block/<disk>/queue/nr_requests
+ and for SCSI device also its queue_depth.
+
+
+What: /sys/block/<disk>/integrity/device_is_integrity_capable
+Date: July 2014
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Indicates whether a storage device is capable of storing
+ integrity metadata. Set if the device is T10 PI-capable.
+ This flag is set to 1 if the storage media is formatted
+ with T10 Protection Information. If the storage media is
+ not formatted with T10 Protection Information, this flag
+ is set to 0.
+
+
+What: /sys/block/<disk>/integrity/format
+Date: June 2008
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Metadata format for integrity capable block device.
+ E.g. T10-DIF-TYPE1-CRC.
+ This field describes the type of T10 Protection Information
+ that the block device can send and receive.
+ If the device can store application integrity metadata but
+ no T10 Protection Information profile is used, this field
+ contains "nop".
+ If the device does not support integrity metadata, this
+ field contains "none".
+
+
+What: /sys/block/<disk>/integrity/protection_interval_bytes
+Date: July 2015
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Describes the number of data bytes which are protected
+ by one integrity tuple. Typically the device's logical
+ block size.
+
+
+What: /sys/block/<disk>/integrity/read_verify
+Date: June 2008
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Indicates whether the block layer should verify the
+ integrity of read requests serviced by devices that
+ support sending integrity metadata.
+
+
+What: /sys/block/<disk>/integrity/tag_size
+Date: June 2008
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Number of bytes of integrity tag space available per
+ protection_interval_bytes, which is typically
+ the device's logical block size.
+ This field describes the size of the application tag
+ if the storage device is formatted with T10 Protection
+ Information and permits use of the application tag.
+ The tag_size is reported in bytes and indicates the
+ space available for adding an opaque tag to each block
+ (protection_interval_bytes).
+ If the device does not support T10 Protection Information
+ (even if the device provides application integrity
+ metadata space), this field is set to 0.
+
+
+What: /sys/block/<disk>/integrity/write_generate
+Date: June 2008
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Indicates whether the block layer should automatically
+ generate checksums for write requests bound for
+ devices that support receiving integrity metadata.
+
+
+What: /sys/block/<disk>/partscan
+Date: May 2024
+Contact: Christoph Hellwig <hch@lst.de>
+Description:
+ The /sys/block/<disk>/partscan files reports if partition
+ scanning is enabled for the disk. It returns "1" if partition
+ scanning is enabled, or "0" if not. The value type is a 32-bit
+ unsigned integer, but only "0" and "1" are valid values.
+
+
+What: /sys/block/<disk>/<partition>/alignment_offset
+Date: April 2009
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Storage devices may report a physical block size that is
+ bigger than the logical block size (for instance a drive
+ with 4KB physical sectors exposing 512-byte logical
+ blocks to the operating system). This parameter
+ indicates how many bytes the beginning of the partition
+ is offset from the disk's natural alignment.
+
+
+What: /sys/block/<disk>/<partition>/discard_alignment
+Date: May 2011
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ Devices that support discard functionality may
+ internally allocate space in units that are bigger than
+ the exported logical block size. The discard_alignment
+ parameter indicates how many bytes the beginning of the
+ partition is offset from the internal allocation unit's
+ natural alignment.
+
+
+What: /sys/block/<disk>/<partition>/stat
+Date: February 2008
+Contact: Jerome Marchand <jmarchan@redhat.com>
+Description:
+ The /sys/block/<disk>/<partition>/stat files display the
+ I/O statistics of partition <partition>. The format is the
+ same as the format of /sys/block/<disk>/stat.
+
+
+What: /sys/block/<disk>/queue/add_random
+Date: June 2010
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This file allows to turn off the disk entropy contribution.
+ Default value of this file is '1'(on).
+
+
+What: /sys/block/<disk>/queue/chunk_sectors
+Date: September 2016
+Contact: Hannes Reinecke <hare@suse.com>
+Description:
+ [RO] chunk_sectors has different meaning depending on the type
+ of the disk. For a RAID device (dm-raid), chunk_sectors
+ indicates the size in 512B sectors of the RAID volume stripe
+ segment. For a zoned block device, either host-aware or
+ host-managed, chunk_sectors indicates the size in 512B sectors
+ of the zones of the device, with the eventual exception of the
+ last zone of the device which may be smaller.
+
+
+What: /sys/block/<disk>/queue/crypto/
+Date: February 2022
+Contact: linux-block@vger.kernel.org
+Description:
+ The presence of this subdirectory of /sys/block/<disk>/queue/
+ indicates that the device supports inline encryption. This
+ subdirectory contains files which describe the inline encryption
+ capabilities of the device. For more information about inline
+ encryption, refer to Documentation/block/inline-encryption.rst.
+
+
+What: /sys/block/<disk>/queue/crypto/hw_wrapped_keys
+Date: February 2025
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] The presence of this file indicates that the device
+ supports hardware-wrapped inline encryption keys, i.e. key blobs
+ that can only be unwrapped and used by dedicated hardware. For
+ more information about hardware-wrapped inline encryption keys,
+ see Documentation/block/inline-encryption.rst.
+
+
+What: /sys/block/<disk>/queue/crypto/max_dun_bits
+Date: February 2022
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This file shows the maximum length, in bits, of data unit
+ numbers accepted by the device in inline encryption requests.
+
+
+What: /sys/block/<disk>/queue/crypto/modes/<mode>
+Date: February 2022
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] For each crypto mode (i.e., encryption/decryption
+ algorithm) the device supports with inline encryption, a file
+ will exist at this location. It will contain a hexadecimal
+ number that is a bitmask of the supported data unit sizes, in
+ bytes, for that crypto mode.
+
+ Currently, the crypto modes that may be supported are:
+
+ * AES-256-XTS
+ * AES-128-CBC-ESSIV
+ * Adiantum
+
+ For example, if a device supports AES-256-XTS inline encryption
+ with data unit sizes of 512 and 4096 bytes, the file
+ /sys/block/<disk>/queue/crypto/modes/AES-256-XTS will exist and
+ will contain "0x1200".
+
+
+What: /sys/block/<disk>/queue/crypto/num_keyslots
+Date: February 2022
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This file shows the number of keyslots the device has for
+ use with inline encryption.
+
+
+What: /sys/block/<disk>/queue/crypto/raw_keys
+Date: February 2025
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] The presence of this file indicates that the device
+ supports raw inline encryption keys, i.e. keys that are managed
+ in raw, plaintext form in software.
+
+
+What: /sys/block/<disk>/queue/dax
+Date: June 2016
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This file indicates whether the device supports Direct
+ Access (DAX), used by CPU-addressable storage to bypass the
+ pagecache. It shows '1' if true, '0' if not.
+
+
+What: /sys/block/<disk>/queue/discard_granularity
+Date: May 2011
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] Devices that support discard functionality may internally
+ allocate space using units that are bigger than the logical
+ block size. The discard_granularity parameter indicates the size
+ of the internal allocation unit in bytes if reported by the
+ device. Otherwise the discard_granularity will be set to match
+ the device's physical block size. A discard_granularity of 0
+ means that the device does not support discard functionality.
+
+
+What: /sys/block/<disk>/queue/discard_max_bytes
+Date: May 2011
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RW] While discard_max_hw_bytes is the hardware limit for the
+ device, this setting is the software limit. Some devices exhibit
+ large latencies when large discards are issued, setting this
+ value lower will make Linux issue smaller discards and
+ potentially help reduce latencies induced by large discard
+ operations.
+
+
+What: /sys/block/<disk>/queue/discard_max_hw_bytes
+Date: July 2015
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Devices that support discard functionality may have
+ internal limits on the number of bytes that can be trimmed or
+ unmapped in a single operation. The `discard_max_hw_bytes`
+ parameter is set by the device driver to the maximum number of
+ bytes that can be discarded in a single operation. Discard
+ requests issued to the device must not exceed this limit. A
+ `discard_max_hw_bytes` value of 0 means that the device does not
+ support discard functionality.
+
+
+What: /sys/block/<disk>/queue/discard_zeroes_data
+Date: May 2011
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] Will always return 0. Don't rely on any specific behavior
+ for discards, and don't read this file.
+
+
+What: /sys/block/<disk>/queue/dma_alignment
+Date: May 2022
+Contact: linux-block@vger.kernel.org
+Description:
+ Reports the alignment that user space addresses must have to be
+ used for raw block device access with O_DIRECT and other driver
+ specific passthrough mechanisms.
+
+
+What: /sys/block/<disk>/queue/fua
+Date: May 2018
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Whether or not the block driver supports the FUA flag for
+ write requests. FUA stands for Force Unit Access. If the FUA
+ flag is set that means that write requests must bypass the
+ volatile cache of the storage device.
+
+
+What: /sys/block/<disk>/queue/hw_sector_size
+Date: January 2008
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This is the hardware sector size of the device, in bytes.
+
+
+What: /sys/block/<disk>/queue/independent_access_ranges/
+Date: October 2021
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] The presence of this sub-directory of the
+ /sys/block/xxx/queue/ directory indicates that the device is
+ capable of executing requests targeting different sector ranges
+ in parallel. For instance, single LUN multi-actuator hard-disks
+ will have an independent_access_ranges directory if the device
+ correctly advertises the sector ranges of its actuators.
+
+ The independent_access_ranges directory contains one directory
+ per access range, with each range described using the sector
+ (RO) attribute file to indicate the first sector of the range
+ and the nr_sectors (RO) attribute file to indicate the total
+ number of sectors in the range starting from the first sector of
+ the range. For example, a dual-actuator hard-disk will have the
+ following independent_access_ranges entries.::
+
+ $ tree /sys/block/<disk>/queue/independent_access_ranges/
+ /sys/block/<disk>/queue/independent_access_ranges/
+ |-- 0
+ | |-- nr_sectors
+ | `-- sector
+ `-- 1
+ |-- nr_sectors
+ `-- sector
+
+ The sector and nr_sectors attributes use 512B sector unit,
+ regardless of the actual block size of the device. Independent
+ access ranges do not overlap and include all sectors within the
+ device capacity. The access ranges are numbered in increasing
+ order of the range start sector, that is, the sector attribute
+ of range 0 always has the value 0.
+
+
+What: /sys/block/<disk>/queue/io_poll
+Date: November 2015
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] When read, this file shows whether polling is enabled (1)
+ or disabled (0). Writing '0' to this file will disable polling
+ for this device. Writing any non-zero value will enable this
+ feature.
+
+
+What: /sys/block/<disk>/queue/io_poll_delay
+Date: November 2016
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This was used to control what kind of polling will be
+ performed. It is now fixed to -1, which is classic polling.
+ In this mode, the CPU will repeatedly ask for completions
+ without giving up any time.
+ <deprecated>
+
+
+What: /sys/block/<disk>/queue/io_timeout
+Date: November 2018
+Contact: Weiping Zhang <zhangweiping@didiglobal.com>
+Description:
+ [RW] io_timeout is the request timeout in milliseconds. If a
+ request does not complete in this time then the block driver
+ timeout handler is invoked. That timeout handler can decide to
+ retry the request, to fail it or to start a device recovery
+ strategy.
+
+
+What: /sys/block/<disk>/queue/iostats
+Date: January 2009
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This file is used to control (on/off) the iostats
+ accounting of the disk.
+
+What: /sys/block/<disk>/queue/iostats_passthrough
+Date: October 2024
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This file is used to control (on/off) the iostats
+ accounting of the disk for passthrough commands.
+
+
+What: /sys/block/<disk>/queue/logical_block_size
+Date: May 2009
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] This is the smallest unit the storage device can address.
+ It is typically 512 bytes.
+
+
+What: /sys/block/<disk>/queue/max_active_zones
+Date: July 2020
+Contact: Niklas Cassel <niklas.cassel@wdc.com>
+Description:
+ [RO] For zoned block devices (zoned attribute indicating
+ "host-managed" or "host-aware"), the sum of zones belonging to
+ any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED,
+ is limited by this value. If this value is 0, there is no limit.
+
+ If the host attempts to exceed this limit, the driver should
+ report this error with BLK_STS_ZONE_ACTIVE_RESOURCE, which user
+ space may see as the EOVERFLOW errno.
+
+
+What: /sys/block/<disk>/queue/max_discard_segments
+Date: February 2017
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] The maximum number of DMA scatter/gather entries in a
+ discard request.
+
+
+What: /sys/block/<disk>/queue/max_hw_sectors_kb
+Date: September 2004
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This is the maximum number of kilobytes supported in a
+ single data transfer.
+
+
+What: /sys/block/<disk>/queue/max_integrity_segments
+Date: September 2010
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Maximum number of elements in a DMA scatter/gather list
+ with integrity data that will be submitted by the block layer
+ core to the associated block driver.
+
+
+What: /sys/block/<disk>/queue/max_open_zones
+Date: July 2020
+Contact: Niklas Cassel <niklas.cassel@wdc.com>
+Description:
+ [RO] For zoned block devices (zoned attribute indicating
+ "host-managed" or "host-aware"), the sum of zones belonging to
+ any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, is
+ limited by this value. If this value is 0, there is no limit.
+
+
+What: /sys/block/<disk>/queue/max_sectors_kb
+Date: September 2004
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This is the maximum number of kilobytes that the block
+ layer will allow for a filesystem request. Must be smaller than
+ or equal to the maximum size allowed by the hardware. Write 0
+ to use default kernel settings.
+
+
+What: /sys/block/<disk>/queue/max_segment_size
+Date: March 2010
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Maximum size in bytes of a single element in a DMA
+ scatter/gather list.
+
+What: /sys/block/<disk>/queue/max_write_streams
+Date: November 2024
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Maximum number of write streams supported, 0 if not
+ supported. If supported, valid values are 1 through
+ max_write_streams, inclusive.
+
+What: /sys/block/<disk>/queue/write_stream_granularity
+Date: November 2024
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Granularity of a write stream in bytes. The granularity
+ of a write stream is the size that should be discarded or
+ overwritten together to avoid write amplification in the device.
+
+What: /sys/block/<disk>/queue/max_segments
+Date: March 2010
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] Maximum number of elements in a DMA scatter/gather list
+ that is submitted to the associated block driver.
+
+
+What: /sys/block/<disk>/queue/minimum_io_size
+Date: April 2009
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] Storage devices may report a granularity or preferred
+ minimum I/O size which is the smallest request the device can
+ perform without incurring a performance penalty. For disk
+ drives this is often the physical block size. For RAID arrays
+ it is often the stripe chunk size. A properly aligned multiple
+ of minimum_io_size is the preferred request size for workloads
+ where a high number of I/O operations is desired.
+
+
+What: /sys/block/<disk>/queue/nomerges
+Date: January 2010
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] Standard I/O elevator operations include attempts to merge
+ contiguous I/Os. For known random I/O loads these attempts will
+ always fail and result in extra cycles being spent in the
+ kernel. This allows one to turn off this behavior on one of two
+ ways: When set to 1, complex merge checks are disabled, but the
+ simple one-shot merges with the previous I/O request are
+ enabled. When set to 2, all merge tries are disabled. The
+ default value is 0 - which enables all types of merge tries.
+
+
+What: /sys/block/<disk>/queue/nr_requests
+Date: July 2003
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This controls how many requests may be allocated in the
+ block layer. Noted this value only represents the quantity for a
+ single blk_mq_tags instance. The actual number for the entire
+ device depends on the hardware queue count, whether elevator is
+ enabled, and whether tags are shared.
+
+
+What: /sys/block/<disk>/queue/nr_zones
+Date: November 2018
+Contact: Damien Le Moal <damien.lemoal@wdc.com>
+Description:
+ [RO] nr_zones indicates the total number of zones of a zoned
+ block device ("host-aware" or "host-managed" zone model). For
+ regular block devices, the value is always 0.
+
+
+What: /sys/block/<disk>/queue/optimal_io_size
+Date: April 2009
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] Storage devices may report an optimal I/O size, which is
+ the device's preferred unit for sustained I/O. This is rarely
+ reported for disk drives. For RAID arrays it is usually the
+ stripe width or the internal track size. A properly aligned
+ multiple of optimal_io_size is the preferred request size for
+ workloads where sustained throughput is desired. If no optimal
+ I/O size is reported this file contains 0.
+
+
+What: /sys/block/<disk>/queue/physical_block_size
+Date: May 2009
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] This is the smallest unit a physical storage device can
+ write atomically. It is usually the same as the logical block
+ size but may be bigger. One example is SATA drives with 4KB
+ sectors that expose a 512-byte logical block size to the
+ operating system. For stacked block devices the
+ physical_block_size variable contains the maximum
+ physical_block_size of the component devices.
+
+
+What: /sys/block/<disk>/queue/read_ahead_kb
+Date: May 2004
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] Maximum number of kilobytes to read-ahead for filesystems
+ on this block device.
+
+ For MADV_HUGEPAGE, the readahead size may exceed this setting
+ since its granularity is based on the hugepage size.
+
+
+What: /sys/block/<disk>/queue/rotational
+Date: January 2009
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This file is used to stat if the device is of rotational
+ type or non-rotational type.
+
+
+What: /sys/block/<disk>/queue/rq_affinity
+Date: September 2008
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] If this option is '1', the block layer will migrate request
+ completions to the cpu "group" that originally submitted the
+ request. For some workloads this provides a significant
+ reduction in CPU cycles due to caching effects.
+
+ For storage configurations that need to maximize distribution of
+ completion processing setting this option to '2' forces the
+ completion to run on the requesting cpu (bypassing the "group"
+ aggregation logic).
+
+
+What: /sys/block/<disk>/queue/scheduler
+Date: October 2004
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] When read, this file will display the current and available
+ IO schedulers for this block device. The currently active IO
+ scheduler will be enclosed in [] brackets. Writing an IO
+ scheduler name to this file will switch control of this block
+ device to that new IO scheduler. Note that writing an IO
+ scheduler name to this file will attempt to load that IO
+ scheduler module, if it isn't already present in the system.
+
+
+What: /sys/block/<disk>/queue/stable_writes
+Date: September 2020
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] This file will contain '1' if memory must not be modified
+ while it is being used in a write request to this device. When
+ this is the case and the kernel is performing writeback of a
+ page, the kernel will wait for writeback to complete before
+ allowing the page to be modified again, rather than allowing
+ immediate modification as is normally the case. This
+ restriction arises when the device accesses the memory multiple
+ times where the same data must be seen every time -- for
+ example, once to calculate a checksum and once to actually write
+ the data. If no such restriction exists, this file will contain
+ '0'. This file is writable for testing purposes.
+
+What: /sys/block/<disk>/queue/virt_boundary_mask
+Date: April 2021
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This file shows the I/O segment memory alignment mask for
+ the block device. I/O requests to this device will be split
+ between segments wherever either the memory address of the end
+ of the previous segment or the memory address of the beginning
+ of the current segment is not aligned to virt_boundary_mask + 1
+ bytes.
+
+
+What: /sys/block/<disk>/queue/wbt_lat_usec
+Date: November 2016
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] If the device is registered for writeback throttling, then
+ this file shows the target minimum read latency. If this latency
+ is exceeded in a given window of time (see curr_win_nsec), then
+ the writeback throttling will start scaling back writes. Writing
+ a value of '0' to this file disables the feature. Writing a
+ value of '-1' to this file resets the value to the default
+ setting.
+
+
+What: /sys/block/<disk>/queue/write_cache
+Date: April 2016
+Contact: linux-block@vger.kernel.org
+Description:
+ [RW] When read, this file will display whether the device has
+ write back caching enabled or not. It will return "write back"
+ for the former case, and "write through" for the latter. Writing
+ to this file can change the kernels view of the device, but it
+ doesn't alter the device state. This means that it might not be
+ safe to toggle the setting from "write back" to "write through",
+ since that will also eliminate cache flushes issued by the
+ kernel.
+
+
+What: /sys/block/<disk>/queue/write_same_max_bytes
+Date: January 2012
+Contact: Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+ [RO] Some devices support a write same operation in which a
+ single data block can be written to a range of several
+ contiguous blocks on storage. This can be used to wipe areas on
+ disk or to initialize drives in a RAID configuration.
+ write_same_max_bytes indicates how many bytes can be written in
+ a single write same command. If write_same_max_bytes is 0, write
+ same is not supported by the device.
+
+
+What: /sys/block/<disk>/queue/write_zeroes_max_bytes
+Date: November 2016
+Contact: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
+Description:
+ [RO] Devices that support write zeroes operation in which a
+ single request can be issued to zero out the range of contiguous
+ blocks on storage without having any payload in the request.
+ This can be used to optimize writing zeroes to the devices.
+ write_zeroes_max_bytes indicates how many bytes can be written
+ in a single write zeroes command. If write_zeroes_max_bytes is
+ 0, write zeroes is not supported by the device.
+
+
+What: /sys/block/<disk>/queue/write_zeroes_unmap_max_hw_bytes
+Date: January 2025
+Contact: Zhang Yi <yi.zhang@huawei.com>
+Description:
+ [RO] This file indicates whether a device supports zeroing data
+ in a specified block range without incurring the cost of
+ physically writing zeroes to the media for each individual
+ block. If this parameter is set to write_zeroes_max_bytes, the
+ device implements a zeroing operation which opportunistically
+ avoids writing zeroes to media while still guaranteeing that
+ subsequent reads from the specified block range will return
+ zeroed data. This operation is a best-effort optimization, a
+ device may fall back to physically writing zeroes to the media
+ due to other factors such as misalignment or being asked to
+ clear a block range smaller than the device's internal
+ allocation unit. If this parameter is set to 0, the device may
+ have to write each logical block media during a zeroing
+ operation.
+
+
+What: /sys/block/<disk>/queue/write_zeroes_unmap_max_bytes
+Date: January 2025
+Contact: Zhang Yi <yi.zhang@huawei.com>
+Description:
+ [RW] While write_zeroes_unmap_max_hw_bytes is the hardware limit
+ for the device, this setting is the software limit. Since the
+ unmap write zeroes operation is a best-effort optimization, some
+ devices may still physically writing zeroes to media. So the
+ speed of this operation is not guaranteed. Writing a value of
+ '0' to this file disables this operation. Otherwise, this
+ parameter should be equal to write_zeroes_unmap_max_hw_bytes.
+
+
+What: /sys/block/<disk>/queue/zone_append_max_bytes
+Date: May 2020
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This is the maximum number of bytes that can be written to
+ a sequential zone of a zoned block device using a zone append
+ write operation (REQ_OP_ZONE_APPEND). This value is always 0 for
+ regular block devices.
+
+
+What: /sys/block/<disk>/queue/zone_write_granularity
+Date: January 2021
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] This indicates the alignment constraint, in bytes, for
+ write operations in sequential zones of zoned block devices
+ (devices with a zoned attributed that reports "host-managed" or
+ "host-aware"). This value is always 0 for regular block devices.
+
+
+What: /sys/block/<disk>/queue/zoned
+Date: September 2016
+Contact: Damien Le Moal <damien.lemoal@wdc.com>
+Description:
+ [RO] zoned indicates if the device is a zoned block device and
+ the zone model of the device if it is indeed zoned. The
+ possible values indicated by zoned are "none" for regular block
+ devices and "host-aware" or "host-managed" for zoned block
+ devices. The characteristics of host-aware and host-managed
+ zoned block devices are described in the ZBC (Zoned Block
+ Commands) and ZAC (Zoned Device ATA Command Set) standards.
+ These standards also define the "drive-managed" zone model.
+ However, since drive-managed zoned block devices do not support
+ zone commands, they will be treated as regular block devices and
+ zoned will report "none".
+
+
+What: /sys/block/<disk>/hidden
+Date: March 2023
+Contact: linux-block@vger.kernel.org
+Description:
+ [RO] the block device is hidden. it doesn’t produce events, and
+ can’t be opened from userspace or using blkdev_get*.
+ Used for the underlying components of multipath devices.
+
+
+What: /sys/block/<disk>/stat
+Date: February 2008
+Contact: Jerome Marchand <jmarchan@redhat.com>
+Description:
+ The /sys/block/<disk>/stat files displays the I/O
+ statistics of disk <disk>. They contain 11 fields:
+
+ == ==============================================
+ 1 reads completed successfully
+ 2 reads merged
+ 3 sectors read
+ 4 time spent reading (ms)
+ 5 writes completed
+ 6 writes merged
+ 7 sectors written
+ 8 time spent writing (ms)
+ 9 I/Os currently in progress
+ 10 time spent doing I/Os (ms)
+ 11 weighted time spent doing I/Os (ms)
+ 12 discards completed
+ 13 discards merged
+ 14 sectors discarded
+ 15 time spent discarding (ms)
+ 16 flush requests completed
+ 17 time spent flushing (ms)
+ == ==============================================
+
+ For more details refer Documentation/admin-guide/iostats.rst
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire
index 41e5a0cd1e3e..9ac9eddb82ef 100644
--- a/Documentation/ABI/stable/sysfs-bus-firewire
+++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -47,6 +47,7 @@ Description:
IEEE 1394 node device attribute.
Read-only and immutable.
Values: 1: The sysfs entry represents a local node (a controller card).
+
0: The sysfs entry represents a remote node.
@@ -125,7 +126,9 @@ Description:
Read-only attribute, immutable during the target's lifetime.
Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
Colon-separated hexadecimal string representations of
+
u64 EUI-64 : u24 directory_ID : u16 LUN
+
without 0x prefixes, without whitespace. The former sbp2 driver
(removed in 2.6.37 after being superseded by firewire-sbp2) used
a somewhat shorter format which was not as close to SAM.
diff --git a/Documentation/ABI/stable/sysfs-bus-fsl-mc b/Documentation/ABI/stable/sysfs-bus-fsl-mc
new file mode 100644
index 000000000000..58f06c7eeed7
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-fsl-mc
@@ -0,0 +1,19 @@
+What: /sys/bus/fsl-mc/rescan
+Date: January 2021
+KernelVersion: 5.12
+Contact: Ioana Ciornei <ioana.ciornei@nxp.com>
+Description: Writing a non-zero value to this attribute will
+ force a rescan of fsl-mc bus in the system and
+ synchronize the objects under fsl-mc bus and the
+ Management Complex firmware.
+Users: Userspace drivers and management tools
+
+What: /sys/bus/fsl-mc/autorescan
+Date: January 2021
+KernelVersion: 5.12
+Contact: Ioana Ciornei <ioana.ciornei@nxp.com>
+Description: Writing a zero value to this attribute will
+ disable the DPRC IRQs on which automatic rescan
+ of the fsl-mc bus is performed. A non-zero value
+ will enable the DPRC IRQs.
+Users: Userspace drivers and management tools
diff --git a/Documentation/ABI/stable/sysfs-bus-mhi b/Documentation/ABI/stable/sysfs-bus-mhi
new file mode 100644
index 000000000000..8b9698fa0beb
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-mhi
@@ -0,0 +1,44 @@
+What: /sys/bus/mhi/devices/.../serialnumber
+Date: Sept 2020
+KernelVersion: 5.10
+Contact: mhi@lists.linux.dev
+Description: The file holds the serial number of the client device obtained
+ using a BHI (Boot Host Interface) register read after at least
+ one attempt to power up the device has been done. If read
+ without having the device power on at least once, the file will
+ read all 0's.
+Users: Any userspace application or clients interested in device info.
+
+What: /sys/bus/mhi/devices/.../oem_pk_hash
+Date: Sept 2020
+KernelVersion: 5.10
+Contact: mhi@lists.linux.dev
+Description: The file holds the OEM PK Hash value of the endpoint device
+ obtained using a BHI (Boot Host Interface) register read after
+ at least one attempt to power up the device has been done. If
+ read without having the device power on at least once, the file
+ will read all 0's.
+Users: Any userspace application or clients interested in device info.
+
+What: /sys/bus/mhi/devices/.../soc_reset
+Date: April 2022
+KernelVersion: 5.19
+Contact: mhi@lists.linux.dev
+Description: Initiates a SoC reset on the MHI controller. A SoC reset is
+ a reset of last resort, and will require a complete re-init.
+ This can be useful as a method of recovery if the device is
+ non-responsive, or as a means of loading new firmware as a
+ system administration task.
+
+What: /sys/bus/mhi/devices/.../trigger_edl
+Date: April 2024
+KernelVersion: 6.10
+Contact: mhi@lists.linux.dev
+Description: Writing a non-zero value to this file will force devices to
+ enter EDL (Emergency Download) mode. This entry only exists for
+ devices capable of entering the EDL mode using the standard EDL
+ triggering mechanism defined in the MHI spec v1.2. Once in EDL
+ mode, the flash programmer image can be downloaded to the
+ device to enter the flash programmer execution environment.
+ This can be useful if user wants to use QDL (Qualcomm Download,
+ which is used to download firmware over EDL) to update firmware.
diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem
new file mode 100644
index 000000000000..0ae8cb074acf
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-nvmem
@@ -0,0 +1,50 @@
+What: /sys/bus/nvmem/devices/.../force_ro
+Date: June 2024
+KernelVersion: 6.11
+Contact: Marek Vasut <marex@denx.de>
+Description:
+ This read/write attribute allows users to set read-write
+ devices as read-only and back to read-write from userspace.
+ This can be used to unlock and relock write-protection of
+ devices which are generally locked, except during sporadic
+ programming operation.
+ Read returns '0' or '1' for read-write or read-only modes
+ respectively.
+ Write parses one of 'YyTt1NnFf0', or [oO][NnFf] for "on"
+ and "off", i.e. what kstrtobool() supports.
+ Note: This file is only present if CONFIG_NVMEM_SYSFS
+ is enabled.
+
+What: /sys/bus/nvmem/devices/.../nvmem
+Date: July 2015
+KernelVersion: 4.2
+Contact: Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+Description:
+ This file allows user to read/write the raw NVMEM contents.
+ Permissions for write to this file depends on the nvmem
+ provider configuration.
+ Note: This file is only present if CONFIG_NVMEM_SYSFS
+ is enabled
+
+ ex::
+
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
+
+What: /sys/bus/nvmem/devices/.../type
+Date: November 2018
+KernelVersion: 5.0
+Contact: Alexandre Belloni <alexandre.belloni@bootlin.com>
+Description:
+ This read-only attribute allows user to read the NVMEM
+ device type. Supported types are "Unknown", "EEPROM",
+ "OTP", "Battery backed", "FRAM".
+ Note: This file is only present if CONFIG_NVMEM_SYSFS
+ is enabled.
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d9672f..cad4bc232520 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
hubs this facility is always enabled and their device
directories will not contain this file.
- For more information, see Documentation/usb/persist.txt.
+ For more information, see Documentation/driver-api/usb/persist.rst.
What: /sys/bus/usb/devices/.../power/autosuspend
Date: March 2007
@@ -50,8 +50,10 @@ Description:
Tools can use this file and the connected_duration file to
compute the percentage of time that a device has been active.
- For example,
- echo $((100 * `cat active_duration` / `cat connected_duration`))
+ For example::
+
+ echo $((100 * `cat active_duration` / `cat connected_duration`))
+
will give an integer percentage. Note that this does not
account for counter wrap.
Users:
diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus
new file mode 100644
index 000000000000..3066feae1d8d
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-vmbus
@@ -0,0 +1,187 @@
+What: /sys/bus/vmbus/hibernation
+Date: Jan 2021
+KernelVersion: 5.12
+Contact: Dexuan Cui <decui@microsoft.com>
+Description: Whether the host supports hibernation for the VM.
+Users: Daemon that sets up swap partition/file for hibernation.
+
+What: /sys/bus/vmbus/devices/<UUID>/id
+Date: Jul 2009
+KernelVersion: 2.6.31
+Contact: K. Y. Srinivasan <kys@microsoft.com>
+Description: The VMBus child_relid of the device's primary channel
+Users: tools/hv/lsvmbus
+
+What: /sys/bus/vmbus/devices/<UUID>/class_id
+Date: Jul 2009
+KernelVersion: 2.6.31
+Contact: K. Y. Srinivasan <kys@microsoft.com>
+Description: The VMBus interface type GUID of the device
+Users: tools/hv/lsvmbus
+
+What: /sys/bus/vmbus/devices/<UUID>/device_id
+Date: Jul 2009
+KernelVersion: 2.6.31
+Contact: K. Y. Srinivasan <kys@microsoft.com>
+Description: The VMBus interface instance GUID of the device
+Users: tools/hv/lsvmbus
+
+What: /sys/bus/vmbus/devices/<UUID>/channel_vp_mapping
+Date: Jul 2015
+KernelVersion: 4.2.0
+Contact: K. Y. Srinivasan <kys@microsoft.com>
+Description: The mapping of which primary/sub channels are bound to which
+ Virtual Processors.
+ Format: <channel's child_relid:the bound cpu's number>
+Users: tools/hv/lsvmbus
+
+What: /sys/bus/vmbus/devices/<UUID>/device
+Date: Dec. 2015
+KernelVersion: 4.5
+Contact: K. Y. Srinivasan <kys@microsoft.com>
+Description: The 16 bit device ID of the device
+Users: tools/hv/lsvmbus and user level RDMA libraries
+
+What: /sys/bus/vmbus/devices/<UUID>/vendor
+Date: Dec. 2015
+KernelVersion: 4.5
+Contact: K. Y. Srinivasan <kys@microsoft.com>
+Description: The 16 bit vendor ID of the device
+Users: tools/hv/lsvmbus and user level RDMA libraries
+
+What: /sys/bus/vmbus/devices/<UUID>/numa_node
+Date: Jul 2018
+KernelVersion: 4.19
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: This NUMA node to which the VMBUS device is
+ attached, or -1 if the node is unknown.
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Directory for per-channel information
+ NN is the VMBUS relid associated with the channel.
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: VCPU (sub)channel is affinitized to
+Users: tools/hv/lsvmbus and other debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/in_mask
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Host to guest channel interrupt mask
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/latency
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Channel signaling latency. This file is available only for
+ performance critical channels (storage, network, etc.) that use
+ the monitor page mechanism.
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_mask
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Guest to host channel interrupt mask
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/pending
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Channel interrupt pending state. This file is available only for
+ performance critical channels (storage, network, etc.) that use
+ the monitor page mechanism.
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/read_avail
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Bytes available to read
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/write_avail
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Bytes available to write
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/events
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Number of times we have signaled the host
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/interrupts
+Date: September. 2017
+KernelVersion: 4.14
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Number of times we have taken an interrupt (incoming)
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/subchannel_id
+Date: January. 2018
+KernelVersion: 4.16
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Subchannel ID associated with VMBUS channel
+Users: Debugging tools and userspace drivers
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/monitor_id
+Date: January. 2018
+KernelVersion: 4.16
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Monitor bit associated with channel. This file is available only
+ for performance critical channels (storage, network, etc.) that
+ use the monitor page mechanism.
+Users: Debugging tools and userspace drivers
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/ring
+Date: January. 2018
+KernelVersion: 4.16
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description: Binary file created by uio_hv_generic for ring buffer
+Users: Userspace drivers
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/intr_in_full
+Date: February 2019
+KernelVersion: 5.0
+Contact: Michael Kelley <mikelley@microsoft.com>
+Description: Number of guest to host interrupts caused by the inbound ring
+ buffer transitioning from full to not full while a packet is
+ waiting for buffer space to become available
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/intr_out_empty
+Date: February 2019
+KernelVersion: 5.0
+Contact: Michael Kelley <mikelley@microsoft.com>
+Description: Number of guest to host interrupts caused by the outbound ring
+ buffer transitioning from empty to not empty
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_full_first
+Date: February 2019
+KernelVersion: 5.0
+Contact: Michael Kelley <mikelley@microsoft.com>
+Description: Number of write operations that were the first to encounter an
+ outbound ring buffer full condition
+Users: Debugging tools
+
+What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_full_total
+Date: February 2019
+KernelVersion: 5.0
+Contact: Michael Kelley <mikelley@microsoft.com>
+Description: Total number of write operations that encountered an outbound
+ ring buffer full condition
+Users: Debugging tools
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
new file mode 100644
index 000000000000..5cd5e872bcae
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -0,0 +1,12 @@
+What: /sys/bus/w1/devices/.../w1_master_timeout_us
+Date: April 2015
+Contact: Dmitry Khromov <dk@icelogic.net>
+Description: Bus scanning interval, microseconds component.
+ Some of 1-Wire devices commonly associated with physical access
+ control systems are attached/generate presence for as short as
+ 100 ms - hence the tens-to-hundreds milliseconds scan intervals
+ are required.
+
+ see Documentation/w1/w1-generic.rst for detailed information.
+Users: any user space application which wants to know bus scanning
+ interval
diff --git a/Documentation/ABI/stable/sysfs-bus-xen-backend b/Documentation/ABI/stable/sysfs-bus-xen-backend
index 3d5951c8bf5f..480a89edfa05 100644
--- a/Documentation/ABI/stable/sysfs-bus-xen-backend
+++ b/Documentation/ABI/stable/sysfs-bus-xen-backend
@@ -19,7 +19,7 @@ Date: April 2011
KernelVersion: 3.0
Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Description:
- The major:minor number (in hexidecimal) of the
+ The major:minor number (in hexadecimal) of the
physical device providing the storage for this backend
block device.
@@ -73,3 +73,12 @@ KernelVersion: 3.0
Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Description:
Number of sectors written by the frontend.
+
+What: /sys/bus/xen-backend/devices/*/state
+Date: August 2018
+KernelVersion: 4.19
+Contact: Joe Jin <joe.jin@oracle.com>
+Description:
+ The state of the device. One of: 'Unknown',
+ 'Initialising', 'Initialised', 'Connected', 'Closing',
+ 'Closed', 'Reconfiguring', 'Reconfigured'.
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
index 70302f370e7e..40b8c46b95b2 100644
--- a/Documentation/ABI/stable/sysfs-class-backlight
+++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -3,9 +3,11 @@ Date: April 2005
KernelVersion: 2.6.12
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
- Control BACKLIGHT power, values are FB_BLANK_* from fb.h
- - FB_BLANK_UNBLANK (0) : power on.
- - FB_BLANK_POWERDOWN (4) : power off
+ Control BACKLIGHT power, values are compatible with
+ FB_BLANK_* from fb.h
+
+ - 0 (FB_BLANK_UNBLANK) : power on.
+ - 4 (FB_BLANK_POWERDOWN) : power off
Users: HAL
What: /sys/class/backlight/<backlight>/brightness
@@ -24,7 +26,12 @@ Date: March 2006
KernelVersion: 2.6.17
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
- Show the actual brightness by querying the hardware.
+ Show the actual brightness by querying the hardware. Due
+ to implementation differences in hardware this may not
+ match the value in 'brightness'. For example some hardware
+ may treat blanking differently or have custom power saving
+ features. Userspace should generally use the values in
+ 'brightness' to make decisions.
Users: HAL
What: /sys/class/backlight/<backlight>/max_brightness
diff --git a/Documentation/ABI/stable/sysfs-class-bluetooth b/Documentation/ABI/stable/sysfs-class-bluetooth
new file mode 100644
index 000000000000..36be02471174
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-class-bluetooth
@@ -0,0 +1,9 @@
+What: /sys/class/bluetooth/hci<index>/reset
+Date: 14-Jan-2025
+KernelVersion: 6.13
+Contact: linux-bluetooth@vger.kernel.org
+Description: This write-only attribute allows users to trigger the vendor reset
+ method on the Bluetooth device when arbitrary data is written.
+ The reset may or may not be done through the device transport
+ (e.g., UART/USB), and can also be done through an out-of-band
+ approach such as GPIO.
diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
new file mode 100644
index 000000000000..694f23a03a28
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-class-infiniband
@@ -0,0 +1,784 @@
+sysfs interface common for all infiniband devices
+-------------------------------------------------
+
+What: /sys/class/infiniband/<device>/node_type
+What: /sys/class/infiniband/<device>/node_guid
+What: /sys/class/infiniband/<device>/sys_image_guid
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ===========================================
+ node_type: (RO) Node type (CA, RNIC, usNIC, usNIC UDP,
+ switch or router)
+
+ node_guid: (RO) Node GUID
+
+ sys_image_guid: (RO) System image GUID
+ =============== ===========================================
+
+
+What: /sys/class/infiniband/<device>/node_desc
+Date: Feb, 2006
+KernelVersion: v2.6.17
+Contact: linux-rdma@vger.kernel.org
+Description:
+ (RW) Update the node description with information such as the
+ node's hostname, so that IB network management software can tie
+ its view to the real world.
+
+
+What: /sys/class/infiniband/<device>/fw_ver
+Date: Jun, 2016
+KernelVersion: v4.10
+Contact: linux-rdma@vger.kernel.org
+Description:
+ (RO) Display firmware version
+
+
+What: /sys/class/infiniband/<device>/ports/<port-num>/lid
+What: /sys/class/infiniband/<device>/ports/<port-num>/rate
+What: /sys/class/infiniband/<device>/ports/<port-num>/lid_mask_count
+What: /sys/class/infiniband/<device>/ports/<port-num>/sm_sl
+What: /sys/class/infiniband/<device>/ports/<port-num>/sm_lid
+What: /sys/class/infiniband/<device>/ports/<port-num>/state
+What: /sys/class/infiniband/<device>/ports/<port-num>/phys_state
+What: /sys/class/infiniband/<device>/ports/<port-num>/cap_mask
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: linux-rdma@vger.kernel.org
+Description:
+
+ =============== ===============================================
+ lid: (RO) Port LID
+
+ rate: (RO) Port data rate (active width * active
+ speed)
+
+ lid_mask_count: (RO) Port LID mask count
+
+ sm_sl: (RO) Subnet manager SL for port's subnet
+
+ sm_lid: (RO) Subnet manager LID for port's subnet
+
+ state: (RO) Port state (DOWN, INIT, ARMED, ACTIVE or
+ ACTIVE_DEFER)
+
+ phys_state: (RO) Port physical state (Sleep, Polling,
+ LinkUp, etc)
+
+ cap_mask: (RO) Port capability mask. 2 bits here are
+ settable- IsCommunicationManagementSupported
+ (set when CM module is loaded) and IsSM (set
+ via open of issmN file).
+ =============== ===============================================
+
+
+What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer
+Date: Oct, 2010
+KernelVersion: v2.6.37
+Contact: linux-rdma@vger.kernel.org
+Description:
+ (RO) Link layer type information (Infiniband or Ethernet type)
+
+
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/symbol_error
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_remote_physical_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_switch_relay_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/link_error_recovery
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_constraint_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_contraint_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/local_link_integrity_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/excessive_buffer_overrun_errors
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_data
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_data
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_packets
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_packets
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/unicast_rcv_packets
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/unicast_xmit_packets
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/multicast_rcv_packets
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/multicast_xmit_packets
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/link_downed
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_discards
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/VL15_dropped
+What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_wait
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: linux-rdma@vger.kernel.org
+Description:
+ **Errors info**:
+
+ symbol_error: (RO) Total number of minor link errors detected on
+ one or more physical lanes.
+
+ port_rcv_errors : (RO) Total number of packets containing an
+ error that were received on the port.
+
+ port_rcv_remote_physical_errors : (RO) Total number of packets
+ marked with the EBP delimiter received on the port.
+
+ port_rcv_switch_relay_errors : (RO) Total number of packets
+ received on the port that were discarded because they could not
+ be forwarded by the switch relay.
+
+ link_error_recovery: (RO) Total number of times the Port
+ Training state machine has successfully completed the link error
+ recovery process.
+
+ port_xmit_constraint_errors: (RO) Total number of packets not
+ transmitted from the switch physical port due to outbound raw
+ filtering or failing outbound partition or IP version check.
+
+ port_rcv_constraint_errors: (RO) Total number of packets
+ received on the switch physical port that are discarded due to
+ inbound raw filtering or failing inbound partition or IP version
+ check.
+
+ local_link_integrity_errors: (RO) The number of times that the
+ count of local physical errors exceeded the threshold specified
+ by LocalPhyErrors
+
+ excessive_buffer_overrun_errors: (RO) This counter, indicates an
+ input buffer overrun. It indicates possible misconfiguration of
+ a port, either by the Subnet Manager (SM) or by user
+ intervention. It can also indicate hardware issues or extremely
+ poor link signal integrity
+
+ **Data info**:
+
+ port_xmit_data: (RO) Total number of data octets, divided by 4
+ (lanes), transmitted on all VLs. This is 64 bit counter
+
+ port_rcv_data: (RO) Total number of data octets, divided by 4
+ (lanes), received on all VLs. This is 64 bit counter.
+
+ port_xmit_packets: (RO) Total number of packets transmitted on
+ all VLs from this port. This may include packets with errors.
+ This is 64 bit counter.
+
+ port_rcv_packets: (RO) Total number of packets (this may include
+ packets containing Errors. This is 64 bit counter.
+
+ link_downed: (RO) Total number of times the Port Training state
+ machine has failed the link error recovery process and downed
+ the link.
+
+ unicast_rcv_packets: (RO) Total number of unicast packets,
+ including unicast packets containing errors.
+
+ unicast_xmit_packets: (RO) Total number of unicast packets
+ transmitted on all VLs from the port. This may include unicast
+ packets with errors.
+
+ multicast_rcv_packets: (RO) Total number of multicast packets,
+ including multicast packets containing errors.
+
+ multicast_xmit_packets: (RO) Total number of multicast packets
+ transmitted on all VLs from the port. This may include multicast
+ packets with errors.
+
+ **Misc info**:
+
+ port_xmit_discards: (RO) Total number of outbound packets
+ discarded by the port because the port is down or congested.
+
+ VL15_dropped: (RO) Number of incoming VL15 packets dropped due
+ to resource limitations (e.g., lack of buffers) of the port.
+
+ port_xmit_wait: (RO) The number of ticks during which the port
+ had data to transmit but no data was sent during the entire tick
+ (either because of insufficient credits or because of lack of
+ arbitration).
+
+ Each of these files contains the corresponding value from the
+ port's Performance Management PortCounters attribute, as
+ described in the InfiniBand Architecture Specification.
+
+
+What: /sys/class/infiniband/<device-name>/hw_counters/lifespan
+What: /sys/class/infiniband/<device-name>/ports/<port-num>/hw_counters/lifespan
+Date: May, 2016
+KernelVersion: 4.6
+Contact: linux-rdma@vger.kernel.org
+Description:
+ The optional "hw_counters" subdirectory can be under either the
+ parent device or the port subdirectories or both. If present,
+ there are a list of counters provided by the hardware. They may
+ match some of the counters in the counters directory, but they
+ often include many other counters. In addition to the various
+ counters, there will be a file named "lifespan" that configures
+ how frequently the core should update the counters when they are
+ being accessed (counters are not updated if they are not being
+ accessed). The lifespan is in milliseconds and defaults to 10
+ unless set to something else by the driver. Users may echo a
+ value between 0-10000 to the lifespan file to set the length
+ of time between updates in milliseconds.
+
+
+What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index>
+Date: November 29, 2015
+KernelVersion: 4.4.0
+Contact: linux-rdma@vger.kernel.org
+Description: The net-device's name associated with the GID resides
+ at index <gid-index>.
+
+What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index>
+Date: November 29, 2015
+KernelVersion: 4.4.0
+Contact: linux-rdma@vger.kernel.org
+Description: The RoCE type of the associated GID resides at index <gid-index>.
+ This could either be "IB/RoCE v1" for IB and RoCE v1 based GIDs
+ or "RoCE v2" for RoCE v2 based GIDs.
+
+
+What: /sys/class/infiniband_mad/umad<N>/ibdev
+What: /sys/class/infiniband_mad/umad<N>/port
+What: /sys/class/infiniband_mad/issm<N>/ibdev
+What: /sys/class/infiniband_mad/issm<N>/port
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: linux-rdma@vger.kernel.org
+Description:
+ Each port of each InfiniBand device has a "umad" device and an
+ "issm" device attached. For example, a two-port HCA will have
+ two umad devices and two issm devices, while a switch will have
+ one device of each type (for switch port 0).
+
+ ======= =====================================
+ ibdev: (RO) Show Infiniband (IB) device name
+
+ port: (RO) Display port number
+ ======= =====================================
+
+
+What: /sys/class/infiniband_mad/abi_version
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: linux-rdma@vger.kernel.org
+Description:
+ (RO) Value is incremented if any changes are made that break
+ userspace ABI compatibility of umad & issm devices.
+
+
+What: /sys/class/infiniband_verbs/uverbs<N>/ibdev
+What: /sys/class/infiniband_verbs/uverbs<N>/abi_version
+Date: Sept, 2005
+KernelVersion: v2.6.14
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ===========================================
+ ibdev: (RO) Display Infiniband (IB) device name
+
+ abi_version: (RO) Show ABI version of IB device specific
+ interfaces.
+ =============== ===========================================
+
+
+What: /sys/class/infiniband_verbs/abi_version
+Date: Sep, 2005
+KernelVersion: v2.6.14
+Contact: linux-rdma@vger.kernel.org
+Description:
+ (RO) Value is incremented if any changes are made that break
+ userspace ABI compatibility of uverbs devices.
+
+
+sysfs interface for Mellanox IB HCA low-level driver (mthca)
+------------------------------------------------------------
+
+What: /sys/class/infiniband/mthcaX/hw_rev
+What: /sys/class/infiniband/mthcaX/hca_type
+What: /sys/class/infiniband/mthcaX/board_id
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ================================================
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Host Channel Adapter type: MT23108, MT25208
+ (MT23108 compat mode), MT25208 or MT25204
+
+ board_id: (RO) Manufacturing board ID
+ =============== ================================================
+
+
+sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
+----------------------------------------------------------
+
+What: /sys/class/infiniband/mlx4_X/hw_rev
+What: /sys/class/infiniband/mlx4_X/hca_type
+What: /sys/class/infiniband/mlx4_X/board_id
+Date: Sep, 2007
+KernelVersion: v2.6.24
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ===============================
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Host channel adapter type
+
+ board_id: (RO) Manufacturing board ID
+ =============== ===============================
+
+
+What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n>
+What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/admin_guids/<n>
+What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/pkeys/<n>
+What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/mcgs/
+What: /sys/class/infiniband/mlx4_X/iov/ports/<pci-slot-num>/ports/<m>/gid_idx/0
+What: /sys/class/infiniband/mlx4_X/iov/ports/<pci-slot-num>/ports/<m>/pkey_idx/<n>
+Date: Aug, 2012
+KernelVersion: v3.6.15
+Contact: linux-rdma@vger.kernel.org
+Description:
+ The sysfs iov directory is used to manage and examine the port
+ P_Key and guid paravirtualization. This directory is added only
+ for the master -- slaves do not have it.
+
+ Under iov/ports, the administrator may examine the gid and P_Key
+ tables as they are present in the device (and as are seen in the
+ "network view" presented to the SM).
+
+ The "pkeys" and "gids" subdirectories contain one file for each
+ entry in the port's P_Key or GID table respectively. For
+ example, ports/1/pkeys/10 contains the value at index 10 in port
+ 1's P_Key table.
+
+ ======================= ==========================================
+ gids/<n>: (RO) The physical port gids n = 0..127
+
+ admin_guids/<n>: (RW) Allows examining or changing the
+ administrative state of a given GUID
+ n = 0..127
+
+ pkeys/<n>: (RO) Displays the contents of the physical
+ key table n = 0..126
+
+ mcgs/: (RO) Multicast group table
+
+ <m>/gid_idx/0: (RO) Display the GID mapping m = 1..2
+
+ <m>/pkey_idx/<n>: (RW) Writable except for RoCE pkeys.
+ m = 1..2, n = 0..126
+
+ Under the iov/<pci slot number>
+ directories, the admin may map the index
+ numbers in the physical tables (as under
+ iov/ports) to the paravirtualized index
+ numbers that guests see.
+
+ For example, if the administrator, for
+ port 1 on guest 2 maps physical pkey
+ index 10 to virtual index 1, then that
+ guest, whenever it uses its pkey index
+ 1, will actually be using the real pkey
+ index 10.
+ ======================= ==========================================
+
+
+What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled
+What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/enable_smi_admin
+Date: May, 2014
+KernelVersion: v3.15.7
+Contact: linux-rdma@vger.kernel.org
+Description:
+ Enabling QP0 on VFs for selected VF/port. By default, no VFs are
+ enabled for QP0 operation.
+
+ ================= ==== ===========================================
+ smi_enabled: (RO) Indicates whether smi is currently enabled
+ for the indicated VF/port
+
+ enable_smi_admin: (RW) Used by the admin to request that smi
+ capability be enabled or disabled for the
+ indicated VF/port. 0 = disable, 1 = enable.
+ ================= ==== ===========================================
+
+ The requested enablement will occur at the next reset of the VF
+ (e.g. driver restart on the VM which owns the VF).
+
+
+sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
+-----------------------------------------------------
+
+What: /sys/class/infiniband/cxgb4_X/hw_rev
+What: /sys/class/infiniband/cxgb4_X/hca_type
+What: /sys/class/infiniband/cxgb4_X/board_id
+Date: Apr, 2010
+KernelVersion: v2.6.35
+Contact: linux-rdma@vger.kernel.org
+Description:
+
+ =============== =============================================
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Driver short name. Should normally match
+ the name in its bus driver structure (e.g.
+ pci_driver::name)
+
+ board_id: (RO) Manufacturing board id. (Vendor + device
+ information)
+ =============== =============================================
+
+
+sysfs interface for Intel IB driver qib
+---------------------------------------
+
+What: /sys/class/infiniband/qibX/version
+What: /sys/class/infiniband/qibX/hw_rev
+What: /sys/class/infiniband/qibX/hca_type
+What: /sys/class/infiniband/qibX/board_id
+What: /sys/class/infiniband/qibX/boardversion
+What: /sys/class/infiniband/qibX/nctxts
+What: /sys/class/infiniband/qibX/localbus_info
+What: /sys/class/infiniband/qibX/tempsense
+What: /sys/class/infiniband/qibX/serial
+What: /sys/class/infiniband/qibX/nfreectxts
+What: /sys/class/infiniband/qibX/chip_reset
+Date: May, 2010
+KernelVersion: v2.6.35
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ======================================================
+ version: (RO) Display version information of installed software
+ and drivers.
+
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Host channel adapter type
+
+ board_id: (RO) Manufacturing board id
+
+ boardversion: (RO) Current version of the chip architecture
+
+ nctxts: (RO) Return the number of user ports (contexts)
+ available
+
+ localbus_info: (RO) Human readable localbus info
+
+ tempsense: (RO) Display temp sense registers in decimal
+
+ serial: (RO) Serial number of the HCA
+
+ nfreectxts: (RO) The number of free user ports (contexts)
+ available.
+
+ chip_reset: (WO) Reset the chip if possible by writing
+ "reset" to this file. Only allowed if no user
+ contexts are open that use chip resources.
+ =============== ======================================================
+
+
+What: /sys/class/infiniband/qibX/ports/<N>/sl2vl/[0-15]
+Date: May, 2010
+KernelVersion: v2.6.35
+Contact: linux-rdma@vger.kernel.org
+Description:
+ (RO) The directory contains 16 files numbered 0-15 that specify
+ the Service Level (SL). Listing the SL files returns the Virtual
+ Lane (VL) as programmed by the SL.
+
+What: /sys/class/infiniband/qibX/ports/<N>/CCMgtA/cc_settings_bin
+What: /sys/class/infiniband/qibX/ports/<N>/CCMgtA/cc_table_bin
+Date: May, 2010
+KernelVersion: v2.6.35
+Contact: linux-rdma@vger.kernel.org
+Description:
+ Per-port congestion control. Both are binary attributes.
+
+ =============== ================================================
+ cc_table_bin (RO) Congestion control table size followed by
+ table entries.
+
+ cc_settings_bin (RO) Congestion settings: port control, control
+ map and an array of 16 entries for the
+ congestion entries - increase, timer, event log
+ trigger threshold and the minimum injection rate
+ delay.
+ =============== ================================================
+
+What: /sys/class/infiniband/qibX/ports/<N>/linkstate/loopback
+What: /sys/class/infiniband/qibX/ports/<N>/linkstate/led_override
+What: /sys/class/infiniband/qibX/ports/<N>/linkstate/hrtbt_enable
+What: /sys/class/infiniband/qibX/ports/<N>/linkstate/status
+What: /sys/class/infiniband/qibX/ports/<N>/linkstate/status_str
+Date: May, 2010
+KernelVersion: v2.6.35
+Contact: linux-rdma@vger.kernel.org
+Description:
+ [to be documented]
+
+ =============== ===============================================
+ loopback: (WO)
+ led_override: (WO)
+ hrtbt_enable: (RW)
+ status: (RO)
+
+ status_str: (RO) Displays information about the link state,
+ possible cable/switch problems, and hardware
+ errors. Possible states are- "Initted",
+ "Present", "IB_link_up", "IB_configured" or
+ "Fatal_Hardware_Error".
+ =============== ===============================================
+
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/rc_resends
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/seq_naks
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/rdma_seq
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/rnr_naks
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/other_naks
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/rc_timeouts
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/look_pkts
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/pkt_drops
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/dma_wait
+What: /sys/class/infiniband/qibX/ports/<N>/diag_counters/unaligned
+Date: May, 2010
+KernelVersion: v2.6.35
+Contact: linux-rdma@vger.kernel.org
+Description:
+ [to be documented]
+
+
+sysfs interface for Mellanox Connect-IB HCA driver mlx5
+-------------------------------------------------------
+
+What: /sys/class/infiniband/mlx5_X/hw_rev
+What: /sys/class/infiniband/mlx5_X/hca_type
+What: /sys/class/infiniband/mlx5_X/reg_pages
+What: /sys/class/infiniband/mlx5_X/fw_pages
+Date: Jul, 2013
+KernelVersion: v3.11
+Contact: linux-rdma@vger.kernel.org
+Description:
+ [to be documented]
+
+
+sysfs interface for Cisco VIC (usNIC) Verbs Driver
+--------------------------------------------------
+
+What: /sys/class/infiniband/usnic_X/board_id
+What: /sys/class/infiniband/usnic_X/config
+What: /sys/class/infiniband/usnic_X/qp_per_vf
+What: /sys/class/infiniband/usnic_X/max_vf
+What: /sys/class/infiniband/usnic_X/cq_per_vf
+What: /sys/class/infiniband/usnic_X/iface
+Date: Sep, 2013
+KernelVersion: v3.14
+Contact: Christian Benvenuti <benve@cisco.com>,
+ Dave Goodell <dgoodell@cisco.com>,
+ linux-rdma@vger.kernel.org
+Description:
+
+ =============== ===============================================
+ board_id: (RO) Manufacturing board id
+
+ config: (RO) Report the configuration for this PF
+
+ qp_per_vf: (RO) Queue pairs per virtual function.
+
+ max_vf: (RO) Max virtual functions
+
+ cq_per_vf: (RO) Completion queue per virtual function
+
+ iface: (RO) Shows which network interface this usNIC
+ entry is associated to (visible with ifconfig).
+ =============== ===============================================
+
+What: /sys/class/infiniband/usnic_X/qpn/summary
+What: /sys/class/infiniband/usnic_X/qpn/context
+Date: Sep, 2013
+KernelVersion: v3.14
+Contact: Christian Benvenuti <benve@cisco.com>,
+ Dave Goodell <dgoodell@cisco.com>,
+ linux-rdma@vger.kernel.org
+Description:
+ [to be documented]
+
+
+sysfs interface for Emulex RoCE HCA Driver
+------------------------------------------
+
+What: /sys/class/infiniband/ocrdmaX/hw_rev
+Date: Feb, 2014
+KernelVersion: v3.14
+Description:
+ hw_rev: (RO) Hardware revision number
+
+What: /sys/class/infiniband/ocrdmaX/hca_type
+Date: Jun, 2014
+KernelVersion: v3.16
+Contact: linux-rdma@vger.kernel.org
+Description:
+ hca_type: (RO) Display FW version
+
+
+sysfs interface for Intel Omni-Path driver (HFI1)
+-------------------------------------------------
+
+What: /sys/class/infiniband/hfi1_X/hw_rev
+What: /sys/class/infiniband/hfi1_X/board_id
+What: /sys/class/infiniband/hfi1_X/nctxts
+What: /sys/class/infiniband/hfi1_X/serial
+What: /sys/class/infiniband/hfi1_X/chip_reset
+What: /sys/class/infiniband/hfi1_X/boardversion
+What: /sys/class/infiniband/hfi1_X/nfreectxts
+What: /sys/class/infiniband/hfi1_X/tempsense
+Date: May, 2016
+KernelVersion: v4.6
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== =============================================
+ hw_rev: (RO) Hardware revision number
+
+ board_id: (RO) Manufacturing board id
+
+ nctxts: (RO) Total contexts available.
+
+ serial: (RO) Board serial number
+
+ chip_reset: (WO) Write "reset" to this file to reset the
+ chip if possible. Only allowed if no user
+ contexts are open that use chip resources.
+
+ boardversion: (RO) Human readable board info
+
+ nfreectxts: (RO) The number of free user ports (contexts)
+ available.
+
+ tempsense: (RO) Thermal sense information
+ =============== =============================================
+
+
+What: /sys/class/infiniband/hfi1_X/ports/<N>/CCMgtA/cc_settings_bin
+What: /sys/class/infiniband/hfi1_X/ports/<N>/CCMgtA/cc_table_bin
+What: /sys/class/infiniband/hfi1_X/ports/<N>/CCMgtA/cc_prescan
+Date: May, 2016
+KernelVersion: v4.6
+Contact: linux-rdma@vger.kernel.org
+Description:
+ Per-port congestion control.
+
+ =============== ================================================
+ cc_table_bin (RO) CCA tables used by PSM2 Congestion control
+ table size followed by table entries. Binary
+ attribute.
+
+ cc_settings_bin (RO) Congestion settings: port control, control
+ map and an array of 16 entries for the
+ congestion entries - increase, timer, event log
+ trigger threshold and the minimum injection rate
+ delay. Binary attribute.
+
+ cc_prescan (RW) enable prescanning for faster BECN
+ response. Write "on" to enable and "off" to
+ disable.
+ =============== ================================================
+
+What: /sys/class/infiniband/hfi1_X/ports/<N>/sc2vl/[0-31]
+What: /sys/class/infiniband/hfi1_X/ports/<N>/sl2sc/[0-31]
+What: /sys/class/infiniband/hfi1_X/ports/<N>/vl2mtu/[0-15]
+Date: May, 2016
+KernelVersion: v4.6
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ===================================================
+ sc2vl/: (RO) 32 files (0 - 31) used to translate sl->vl
+
+ sl2sc/: (RO) 32 files (0 - 31) used to translate sl->sc
+
+ vl2mtu/: (RO) 16 files (0 - 15) used to determine MTU for vl
+ =============== ===================================================
+
+
+What: /sys/class/infiniband/hfi1_X/sdma_<N>/cpu_list
+What: /sys/class/infiniband/hfi1_X/sdma_<N>/vl
+Date: Sept, 2016
+KernelVersion: v4.8
+Contact: linux-rdma@vger.kernel.org
+Description:
+ sdma<N>/ contains one directory per sdma engine (0 - 15)
+
+ =============== ==============================================
+ cpu_list: (RW) List of cpus for user-process to sdma
+ engine assignment.
+
+ vl: (RO) Displays the virtual lane (vl) the sdma
+ engine maps to.
+ =============== ==============================================
+
+ This interface gives the user control on the affinity settings
+ for the device. As an example, to set an sdma engine irq
+ affinity and thread affinity of a user processes to use the
+ sdma engine, which is "near" in terms of NUMA configuration, or
+ physical cpu location, the user will do::
+
+ echo "3" > /proc/irq/<N>/smp_affinity_list
+ echo "4-7" > /sys/devices/.../sdma3/cpu_list
+ cat /sys/devices/.../sdma3/vl
+ 0
+ echo "8" > /proc/irq/<M>/smp_affinity_list
+ echo "9-12" > /sys/devices/.../sdma4/cpu_list
+ cat /sys/devices/.../sdma4/vl
+ 1
+
+ to make sure that when a process runs on cpus 4,5,6, or 7, and
+ uses vl=0, then sdma engine 3 is selected by the driver, and
+ also the interrupt of the sdma engine 3 is steered to cpu 3.
+ Similarly, when a process runs on cpus 9,10,11, or 12 and sets
+ vl=1, then engine 4 will be selected and the irq of the sdma
+ engine 4 is steered to cpu 8. This assumes that in the above N
+ is the irq number of "sdma3", and M is irq number of "sdma4" in
+ the /proc/interrupts file.
+
+sysfs interface for QLogic qedr NIC Driver
+------------------------------------------
+
+What: /sys/class/infiniband/qedrX/hw_rev
+What: /sys/class/infiniband/qedrX/hca_type
+Date: Oct, 2016
+KernelVersion: v4.10
+Contact: linux-rdma@vger.kernel.org
+Description:
+
+ =============== ==== ========================
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Display HCA type
+ =============== ==== ========================
+
+
+sysfs interface for VMware Paravirtual RDMA driver
+--------------------------------------------------
+
+What: /sys/class/infiniband/vmw_pvrdmaX/hw_rev
+What: /sys/class/infiniband/vmw_pvrdmaX/hca_type
+What: /sys/class/infiniband/vmw_pvrdmaX/board_id
+Date: Oct, 2016
+KernelVersion: v4.10
+Contact: linux-rdma@vger.kernel.org
+Description:
+
+ =============== ==== =====================================
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Host channel adapter type
+
+ board_id: (RO) Display PVRDMA manufacturing board ID
+ =============== ==== =====================================
+
+
+sysfs interface for Broadcom NetXtreme-E RoCE driver
+----------------------------------------------------
+
+What: /sys/class/infiniband/bnxt_reX/hw_rev
+What: /sys/class/infiniband/bnxt_reX/hca_type
+Date: Feb, 2017
+KernelVersion: v4.11
+Contact: linux-rdma@vger.kernel.org
+Description:
+ =============== ==== =========================
+ hw_rev: (RO) Hardware revision number
+
+ hca_type: (RO) Host channel adapter type
+ =============== ==== =========================
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 097f522c33bb..67b605e3dd16 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -1,10 +1,9 @@
rfkill - radio frequency (RF) connector kill switch support
-For details to this subsystem look at Documentation/rfkill.txt.
+For details to this subsystem look at Documentation/driver-api/rfkill.rst.
-For the deprecated /sys/class/rfkill/*/state and
-/sys/class/rfkill/*/claim knobs of this interface look in
-Documentation/ABI/obsolete/sysfs-class-rfkill.
+For the deprecated ``/sys/class/rfkill/*/claim`` knobs of this interface look in
+Documentation/ABI/removed/sysfs-class-rfkill.
What: /sys/class/rfkill
Date: 09-Jul-2007
@@ -12,12 +11,12 @@ KernelVersion: v2.6.22
Contact: linux-wireless@vger.kernel.org,
Description: The rfkill class subsystem folder.
Each registered rfkill driver is represented by an rfkillX
- subfolder (X being an integer > 0).
+ subfolder (X being an integer >= 0).
What: /sys/class/rfkill/rfkill[0-9]+/name
Date: 09-Jul-2007
-KernelVersion v2.6.22
+KernelVersion: v2.6.22
Contact: linux-wireless@vger.kernel.org
Description: Name assigned by driver to this key (interface or driver name).
Values: arbitrary string.
@@ -25,7 +24,7 @@ Values: arbitrary string.
What: /sys/class/rfkill/rfkill[0-9]+/type
Date: 09-Jul-2007
-KernelVersion v2.6.22
+KernelVersion: v2.6.22
Contact: linux-wireless@vger.kernel.org
Description: Driver type string ("wlan", "bluetooth", etc).
Values: See include/linux/rfkill.h.
@@ -33,21 +32,46 @@ Values: See include/linux/rfkill.h.
What: /sys/class/rfkill/rfkill[0-9]+/persistent
Date: 09-Jul-2007
-KernelVersion v2.6.22
+KernelVersion: v2.6.22
Contact: linux-wireless@vger.kernel.org
Description: Whether the soft blocked state is initialised from non-volatile
storage at startup.
+Values: A numeric value:
+
+ - 0: false
+ - 1: true
+
+
+What: /sys/class/rfkill/rfkill[0-9]+/state
+Date: 09-Jul-2007
+KernelVersion: v2.6.22
+Contact: linux-wireless@vger.kernel.org
+Description: Current state of the transmitter.
+ This file was scheduled to be removed in 2014, but due to its
+ large number of users it will be sticking around for a bit
+ longer. Despite it being marked as stable, the newer "hard" and
+ "soft" interfaces should be preferred, since it is not possible
+ to express the 'soft and hard block' state of the rfkill driver
+ through this interface. There will likely be another attempt to
+ remove it in the future.
Values: A numeric value.
- 0: false
- 1: true
+
+ 0: RFKILL_STATE_SOFT_BLOCKED
+ transmitter is turned off by software
+ 1: RFKILL_STATE_UNBLOCKED
+ transmitter is (potentially) active
+ 2: RFKILL_STATE_HARD_BLOCKED
+ transmitter is forced off by something outside of
+ the driver's control.
What: /sys/class/rfkill/rfkill[0-9]+/hard
Date: 12-March-2010
-KernelVersion v2.6.34
+KernelVersion: v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current hardblock state. This file is read only.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
1: active
@@ -57,11 +81,13 @@ Values: A numeric value.
What: /sys/class/rfkill/rfkill[0-9]+/soft
Date: 12-March-2010
-KernelVersion v2.6.34
+KernelVersion: v2.6.34
Contact: linux-wireless@vger.kernel.org
Description: Current softblock state. This file is read and write.
Values: A numeric value.
+
0: inactive
The transmitter is (potentially) active.
+
1: active
The transmitter is turned off by software.
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm
index 9f790eebb5d2..411d5895bed4 100644
--- a/Documentation/ABI/stable/sysfs-class-tpm
+++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -1,7 +1,7 @@
What: /sys/class/tpm/tpmX/device/
Date: April 2005
KernelVersion: 2.6.12
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The device/ directory under a specific TPM instance exposes
the properties of that TPM chip
@@ -9,7 +9,7 @@ Description: The device/ directory under a specific TPM instance exposes
What: /sys/class/tpm/tpmX/device/active
Date: April 2006
KernelVersion: 2.6.17
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "active" property prints a '1' if the TPM chip is accepting
commands. An inactive TPM chip still contains all the state of
an active chip (Storage Root Key, NVRAM, etc), and can be
@@ -21,7 +21,7 @@ Description: The "active" property prints a '1' if the TPM chip is accepting
What: /sys/class/tpm/tpmX/device/cancel
Date: June 2005
KernelVersion: 2.6.13
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "cancel" property allows you to cancel the currently
pending TPM command. Writing any value to cancel will call the
TPM vendor specific cancel operation.
@@ -29,14 +29,14 @@ Description: The "cancel" property allows you to cancel the currently
What: /sys/class/tpm/tpmX/device/caps
Date: April 2005
KernelVersion: 2.6.12
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "caps" property contains TPM manufacturer and version info.
- Example output:
+ Example output::
- Manufacturer: 0x53544d20
- TCG version: 1.2
- Firmware version: 8.16
+ Manufacturer: 0x53544d20
+ TCG version: 1.2
+ Firmware version: 8.16
Manufacturer is a hex dump of the 4 byte manufacturer info
space in a TPM. TCG version shows the TCG TPM spec level that
@@ -46,7 +46,7 @@ Description: The "caps" property contains TPM manufacturer and version info.
What: /sys/class/tpm/tpmX/device/durations
Date: March 2011
KernelVersion: 3.1
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "durations" property shows the 3 vendor-specific values
used to wait for a short, medium and long TPM command. All
TPM commands are categorized as short, medium or long in
@@ -54,9 +54,9 @@ Description: The "durations" property shows the 3 vendor-specific values
any longer than necessary before starting to poll for a
result.
- Example output:
+ Example output::
- 3015000 4508000 180995000 [original]
+ 3015000 4508000 180995000 [original]
Here the short, medium and long durations are displayed in
usecs. "[original]" indicates that the values are displayed
@@ -69,7 +69,7 @@ Description: The "durations" property shows the 3 vendor-specific values
What: /sys/class/tpm/tpmX/device/enabled
Date: April 2006
KernelVersion: 2.6.17
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "enabled" property prints a '1' if the TPM chip is enabled,
meaning that it should be visible to the OS. This property
may be visible but produce a '0' after some operation that
@@ -78,7 +78,7 @@ Description: The "enabled" property prints a '1' if the TPM chip is enabled,
What: /sys/class/tpm/tpmX/device/owned
Date: April 2006
KernelVersion: 2.6.17
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "owned" property produces a '1' if the TPM_TakeOwnership
ordinal has been executed successfully in the chip. A '0'
indicates that ownership hasn't been taken.
@@ -86,20 +86,20 @@ Description: The "owned" property produces a '1' if the TPM_TakeOwnership
What: /sys/class/tpm/tpmX/device/pcrs
Date: April 2005
KernelVersion: 2.6.12
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "pcrs" property will dump the current value of all Platform
Configuration Registers in the TPM. Note that since these
values may be constantly changing, the output is only valid
for a snapshot in time.
- Example output:
+ Example output::
- PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
- ...
+ PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+ ...
The number of PCRs and hex bytes needed to represent a PCR
value will vary depending on TPM chip version. For TPM 1.1 and
@@ -109,77 +109,102 @@ Description: The "pcrs" property will dump the current value of all Platform
What: /sys/class/tpm/tpmX/device/pubek
Date: April 2005
KernelVersion: 2.6.12
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "pubek" property will return the TPM's public endorsement
key if possible. If the TPM has had ownership established and
is version 1.2, the pubek will not be available without the
owner's authorization. Since the TPM driver doesn't store any
secrets, it can't authorize its own request for the pubek,
making it unaccessible. The public endorsement key is gener-
- ated at TPM menufacture time and exists for the life of the
+ ated at TPM manufacture time and exists for the life of the
chip.
- Example output:
-
- Algorithm: 00 00 00 01
- Encscheme: 00 03
- Sigscheme: 00 01
- Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
- Modulus length: 256
- Modulus:
- B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
- 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
- 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
- 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
- D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
- 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
- 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
- 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
- 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
- A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
- 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
- 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
- E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
- F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
- F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
- C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
-
- Possible values:
-
- Algorithm: TPM_ALG_RSA (1)
- Encscheme: TPM_ES_RSAESPKCSv15 (2)
+ Example output::
+
+ Algorithm: 00 00 00 01
+ Encscheme: 00 03
+ Sigscheme: 00 01
+ Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
+ Modulus length: 256
+ Modulus:
+ B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
+ 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
+ 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
+ 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
+ D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
+ 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
+ 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
+ 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
+ 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
+ A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
+ 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
+ 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
+ E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
+ F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
+ F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
+ C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
+
+ Possible values::
+
+ Algorithm: TPM_ALG_RSA (1)
+ Encscheme: TPM_ES_RSAESPKCSv15 (2)
TPM_ES_RSAESOAEP_SHA1_MGF1 (3)
- Sigscheme: TPM_SS_NONE (1)
- Parameters, a byte string of 3 u32 values:
+ Sigscheme: TPM_SS_NONE (1)
+ Parameters, a byte string of 3 u32 values:
Key Length (bits): 00 00 08 00 (2048)
Num primes: 00 00 00 02 (2)
Exponent Size: 00 00 00 00 (0 means the
default exp)
- Modulus Length: 256 (bytes)
- Modulus: The 256 byte Endorsement Key modulus
+ Modulus Length: 256 (bytes)
+ Modulus: The 256 byte Endorsement Key modulus
What: /sys/class/tpm/tpmX/device/temp_deactivated
Date: April 2006
KernelVersion: 2.6.17
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "temp_deactivated" property returns a '1' if the chip has
- been temporarily dectivated, usually until the next power
+ been temporarily deactivated, usually until the next power
cycle. Whether a warm boot (reboot) will clear a TPM chip
from a temp_deactivated state is platform specific.
What: /sys/class/tpm/tpmX/device/timeouts
Date: March 2011
KernelVersion: 3.1
-Contact: tpmdd-devel@lists.sf.net
+Contact: linux-integrity@vger.kernel.org
Description: The "timeouts" property shows the 4 vendor-specific values
for the TPM's interface spec timeouts. The use of these
timeouts is defined by the TPM interface spec that the chip
conforms to.
- Example output:
+ Example output::
- 750000 750000 750000 750000 [original]
+ 750000 750000 750000 750000 [original]
The four timeout values are shown in usecs, with a trailing
"[original]" or "[adjusted]" depending on whether the values
were scaled by the driver to be reported in usec from msecs.
+
+What: /sys/class/tpm/tpmX/tpm_version_major
+Date: October 2019
+KernelVersion: 5.5
+Contact: linux-integrity@vger.kernel.org
+Description: The "tpm_version_major" property shows the TCG spec major version
+ implemented by the TPM device.
+
+ Example output::
+
+ 2
+
+What: /sys/class/tpm/tpmX/pcr-<H>/<N>
+Date: March 2021
+KernelVersion: 5.12
+Contact: linux-integrity@vger.kernel.org
+Description: produces output in compact hex representation for PCR
+ number N from hash bank H. N is the numeric value of
+ the PCR number and H is the crypto string
+ representation of the hash
+
+ Example output::
+
+ cat /sys/class/tpm/tpm0/pcr-sha256/7
+ 2ED93F199692DC6788EFA6A1FE74514AB9760B2A6CEEAEF6C808C13E4ABB0D42
diff --git a/Documentation/ABI/stable/sysfs-class-ubi b/Documentation/ABI/stable/sysfs-class-ubi
index 18d471d9faea..a6b324014692 100644
--- a/Documentation/ABI/stable/sysfs-class-ubi
+++ b/Documentation/ABI/stable/sysfs-class-ubi
@@ -107,6 +107,15 @@ Contact: Artem Bityutskiy <dedekind@infradead.org>
Description:
Number of physical eraseblocks reserved for bad block handling.
+What: /sys/class/ubi/ubiX/ro_mode
+Date: April 2016
+KernelVersion: 4.7
+Contact: linux-mtd@lists.infradead.org
+Description:
+ Contains ASCII "1\n" if the read-only flag is set on this
+ device, and "0\n" if it is cleared. UBI devices mark themselves
+ as read-only when they detect an unrecoverable error.
+
What: /sys/class/ubi/ubiX/total_eraseblocks
Date: July 2006
KernelVersion: 2.6.22
diff --git a/Documentation/ABI/stable/sysfs-class-udc b/Documentation/ABI/stable/sysfs-class-udc
index 85d3dac2e204..d1e2f3ec1fc9 100644
--- a/Documentation/ABI/stable/sysfs-class-udc
+++ b/Documentation/ABI/stable/sysfs-class-udc
@@ -55,14 +55,6 @@ Description:
Indicates the maximum USB speed supported by this port.
Users:
-What: /sys/class/udc/<udc>/maximum_speed
-Date: June 2011
-KernelVersion: 3.1
-Contact: Felipe Balbi <balbi@kernel.org>
-Description:
- Indicates the maximum USB speed supported by this port.
-Users:
-
What: /sys/class/udc/<udc>/soft_connect
Date: June 2011
KernelVersion: 3.1
@@ -91,3 +83,11 @@ Description:
'configured', and 'suspended'; however not all USB Device
Controllers support reporting all states.
Users:
+
+What: /sys/class/udc/<udc>/function
+Date: June 2017
+KernelVersion: 4.13
+Contact: Felipe Balbi <balbi@kernel.org>
+Description:
+ Prints out name of currently running USB Gadget Driver.
+Users:
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 43f78b88da28..98a8ef99ac5f 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -1,10 +1,32 @@
-# Note: This documents additional properties of any device beyond what
-# is documented in Documentation/sysfs-rules.txt
+Note:
+ This documents additional properties of any device beyond what
+ is documented in Documentation/admin-guide/sysfs-rules.rst
-What: /sys/devices/*/of_path
+What: /sys/devices/*/of_node
Date: February 2015
Contact: Device Tree mailing list <devicetree@vger.kernel.org>
Description:
Any device associated with a device-tree node will have
an of_path symlink pointing to the corresponding device
node in /sys/firmware/devicetree/
+
+What: /sys/devices/*/devspec
+Date: October 2016
+Contact: Device Tree mailing list <devicetree@vger.kernel.org>
+Description:
+ If CONFIG_OF is enabled, then this file is present. When
+ read, it returns full name of the device node.
+
+What: /sys/devices/*/obppath
+Date: October 2016
+Contact: Device Tree mailing list <devicetree@vger.kernel.org>
+Description:
+ If CONFIG_OF is enabled, then this file is present. When
+ read, it returns full name of the device node.
+
+What: /sys/devices/*/dev
+Date: Jun 2006
+Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+ Major and minor numbers of the character device corresponding
+ to the device (in <major>:<minor> format).
diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node
index 5b2d0f08867c..2d0e023f22a7 100644
--- a/Documentation/ABI/stable/sysfs-devices-node
+++ b/Documentation/ABI/stable/sysfs-devices-node
@@ -54,14 +54,14 @@ Date: October 2002
Contact: Linux Memory Management list <linux-mm@kvack.org>
Description:
Provides information about the node's distribution and memory
- utilization. Similar to /proc/meminfo, see Documentation/filesystems/proc.txt
+ utilization. Similar to /proc/meminfo, see Documentation/filesystems/proc.rst
What: /sys/devices/system/node/nodeX/numastat
Date: October 2002
Contact: Linux Memory Management list <linux-mm@kvack.org>
Description:
The node's hit/miss statistics, in units of pages.
- See Documentation/numastat.txt
+ See Documentation/admin-guide/numastat.rst
What: /sys/devices/system/node/nodeX/distance
Date: October 2002
@@ -90,4 +90,149 @@ Date: December 2009
Contact: Lee Schermerhorn <lee.schermerhorn@hp.com>
Description:
The node's huge page size control/query attributes.
- See Documentation/vm/hugetlbpage.txt \ No newline at end of file
+ See Documentation/admin-guide/mm/hugetlbpage.rst
+
+What: /sys/devices/system/node/nodeX/accessY/
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The node's relationship to other nodes for access class "Y".
+
+What: /sys/devices/system/node/nodeX/accessY/initiators/
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The directory containing symlinks to memory initiator
+ nodes that have class "Y" access to this target node's
+ memory. CPUs and other memory initiators in nodes not in
+ the list accessing this node's memory may have different
+ performance.
+
+What: /sys/devices/system/node/nodeX/accessY/targets/
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The directory containing symlinks to memory targets that
+ this initiator node has class "Y" access.
+
+What: /sys/devices/system/node/nodeX/accessY/initiators/read_bandwidth
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ This node's read bandwidth in MB/s when accessed from
+ nodes found in this access class's linked initiators.
+
+What: /sys/devices/system/node/nodeX/accessY/initiators/read_latency
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ This node's read latency in nanoseconds when accessed
+ from nodes found in this access class's linked initiators.
+
+What: /sys/devices/system/node/nodeX/accessY/initiators/write_bandwidth
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ This node's write bandwidth in MB/s when accessed from
+ found in this access class's linked initiators.
+
+What: /sys/devices/system/node/nodeX/accessY/initiators/write_latency
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ This node's write latency in nanoseconds when access
+ from nodes found in this class's linked initiators.
+
+What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The directory containing attributes for the memory-side cache
+ level 'Y'.
+
+What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/indexing
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The caches associativity indexing: 0 for direct mapped,
+ non-zero if indexed.
+
+What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/line_size
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The number of bytes accessed from the next cache level on a
+ cache miss.
+
+What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/size
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The size of this memory side cache in bytes.
+
+What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/write_policy
+Date: December 2018
+Contact: Keith Busch <keith.busch@intel.com>
+Description:
+ The cache write policy: 0 for write-back, 1 for write-through,
+ other or unknown.
+
+What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/address_mode
+Date: March 2025
+Contact: Dave Jiang <dave.jiang@intel.com>
+Description:
+ The address mode: 0 for reserved, 1 for extended-linear.
+
+What: /sys/devices/system/node/nodeX/x86/sgx_total_bytes
+Date: November 2021
+Contact: Jarkko Sakkinen <jarkko@kernel.org>
+Description:
+ The total amount of SGX physical memory in bytes.
+
+What: /sys/devices/system/node/nodeX/memory_failure/total
+Date: January 2023
+Contact: Jiaqi Yan <jiaqiyan@google.com>
+Description:
+ The total number of raw poisoned pages (pages containing
+ corrupted data due to memory errors) on a NUMA node.
+
+What: /sys/devices/system/node/nodeX/memory_failure/ignored
+Date: January 2023
+Contact: Jiaqi Yan <jiaqiyan@google.com>
+Description:
+ Of the raw poisoned pages on a NUMA node, how many pages are
+ ignored by memory error recovery attempt, usually because
+ support for this type of pages is unavailable, and kernel
+ gives up the recovery.
+
+What: /sys/devices/system/node/nodeX/memory_failure/failed
+Date: January 2023
+Contact: Jiaqi Yan <jiaqiyan@google.com>
+Description:
+ Of the raw poisoned pages on a NUMA node, how many pages are
+ failed by memory error recovery attempt. This usually means
+ a key recovery operation failed.
+
+What: /sys/devices/system/node/nodeX/memory_failure/delayed
+Date: January 2023
+Contact: Jiaqi Yan <jiaqiyan@google.com>
+Description:
+ Of the raw poisoned pages on a NUMA node, how many pages are
+ delayed by memory error recovery attempt. Delayed poisoned
+ pages usually will be retried by kernel.
+
+What: /sys/devices/system/node/nodeX/memory_failure/recovered
+Date: January 2023
+Contact: Jiaqi Yan <jiaqiyan@google.com>
+Description:
+ Of the raw poisoned pages on a NUMA node, how many pages are
+ recovered by memory error recovery attempt.
+
+What: /sys/devices/system/node/nodeX/reclaim
+Date: June 2025
+Contact: Linux Memory Management list <linux-mm@kvack.org>
+Description:
+ Perform user-triggered proactive reclaim on a NUMA node.
+ This interface is equivalent to the memcg variant.
+
+ See Documentation/admin-guide/cgroup-v2.rst
diff --git a/Documentation/ABI/stable/sysfs-devices-system-cpu b/Documentation/ABI/stable/sysfs-devices-system-cpu
index 33c133e2a631..cf78bd99f6c8 100644
--- a/Documentation/ABI/stable/sysfs-devices-system-cpu
+++ b/Documentation/ABI/stable/sysfs-devices-system-cpu
@@ -23,3 +23,95 @@ Description: Default value for the Data Stream Control Register (DSCR) on
here).
If set by a process it will be inherited by child processes.
Values: 64 bit unsigned integer (bit field)
+
+What: /sys/devices/system/cpu/cpuX/topology/die_id
+Description: the CPU die ID of cpuX. Typically it is the hardware platform's
+ identifier (rather than the kernel's). The actual value is
+ architecture and platform dependent.
+Values: integer
+
+What: /sys/devices/system/cpu/cpuX/topology/core_id
+Description: the CPU core ID of cpuX. Typically it is the hardware platform's
+ identifier (rather than the kernel's). The actual value is
+ architecture and platform dependent.
+Values: integer
+
+What: /sys/devices/system/cpu/cpuX/topology/cluster_id
+Description: the cluster ID of cpuX. Typically it is the hardware platform's
+ identifier (rather than the kernel's). The actual value is
+ architecture and platform dependent.
+Values: integer
+
+What: /sys/devices/system/cpu/cpuX/topology/book_id
+Description: the book ID of cpuX. Typically it is the hardware platform's
+ identifier (rather than the kernel's). The actual value is
+ architecture and platform dependent. it's only used on s390.
+Values: integer
+
+What: /sys/devices/system/cpu/cpuX/topology/drawer_id
+Description: the drawer ID of cpuX. Typically it is the hardware platform's
+ identifier (rather than the kernel's). The actual value is
+ architecture and platform dependent. it's only used on s390.
+Values: integer
+
+What: /sys/devices/system/cpu/cpuX/topology/core_cpus
+Description: internal kernel map of CPUs within the same core.
+ (deprecated name: "thread_siblings")
+Values: hexadecimal bitmask.
+
+What: /sys/devices/system/cpu/cpuX/topology/core_cpus_list
+Description: human-readable list of CPUs within the same core.
+ The format is like 0-3, 8-11, 14,17.
+ (deprecated name: "thread_siblings_list").
+Values: decimal list.
+
+What: /sys/devices/system/cpu/cpuX/topology/package_cpus
+Description: internal kernel map of the CPUs sharing the same physical_package_id.
+ (deprecated name: "core_siblings").
+Values: hexadecimal bitmask.
+
+What: /sys/devices/system/cpu/cpuX/topology/package_cpus_list
+Description: human-readable list of CPUs sharing the same physical_package_id.
+ The format is like 0-3, 8-11, 14,17.
+ (deprecated name: "core_siblings_list")
+Values: decimal list.
+
+What: /sys/devices/system/cpu/cpuX/topology/die_cpus
+Description: internal kernel map of CPUs within the same die.
+Values: hexadecimal bitmask.
+
+What: /sys/devices/system/cpu/cpuX/topology/die_cpus_list
+Description: human-readable list of CPUs within the same die.
+ The format is like 0-3, 8-11, 14,17.
+Values: decimal list.
+
+What: /sys/devices/system/cpu/cpuX/topology/cluster_cpus
+Description: internal kernel map of CPUs within the same cluster.
+Values: hexadecimal bitmask.
+
+What: /sys/devices/system/cpu/cpuX/topology/cluster_cpus_list
+Description: human-readable list of CPUs within the same cluster.
+ The format is like 0-3, 8-11, 14,17.
+Values: decimal list.
+
+What: /sys/devices/system/cpu/cpuX/topology/book_siblings
+Description: internal kernel map of cpuX's hardware threads within the same
+ book_id. it's only used on s390.
+Values: hexadecimal bitmask.
+
+What: /sys/devices/system/cpu/cpuX/topology/book_siblings_list
+Description: human-readable list of cpuX's hardware threads within the same
+ book_id.
+ The format is like 0-3, 8-11, 14,17. it's only used on s390.
+Values: decimal list.
+
+What: /sys/devices/system/cpu/cpuX/topology/drawer_siblings
+Description: internal kernel map of cpuX's hardware threads within the same
+ drawer_id. it's only used on s390.
+Values: hexadecimal bitmask.
+
+What: /sys/devices/system/cpu/cpuX/topology/drawer_siblings_list
+Description: human-readable list of cpuX's hardware threads within the same
+ drawer_id.
+ The format is like 0-3, 8-11, 14,17. it's only used on s390.
+Values: decimal list.
diff --git a/Documentation/ABI/stable/sysfs-devices-system-xen_memory b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
index caa311d59ac1..6d83f95a8a8e 100644
--- a/Documentation/ABI/stable/sysfs-devices-system-xen_memory
+++ b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
@@ -75,3 +75,12 @@ Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Description:
Amount (in KiB) of low (or normal) memory in the
balloon.
+
+What: /sys/devices/system/xen_memory/xen_memory0/scrub_pages
+Date: September 2018
+KernelVersion: 4.20
+Contact: xen-devel@lists.xenproject.org
+Description:
+ Control scrubbing pages before returning them to Xen for others domains
+ use. Can be set with xen_scrub_pages cmdline
+ parameter. Default value controlled with CONFIG_XEN_SCRUB_PAGES_DEFAULT.
diff --git a/Documentation/ABI/stable/sysfs-driver-aspeed-vuart b/Documentation/ABI/stable/sysfs-driver-aspeed-vuart
new file mode 100644
index 000000000000..950cafc9443a
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-aspeed-vuart
@@ -0,0 +1,24 @@
+What: /sys/bus/platform/drivers/aspeed-vuart/*/lpc_address
+Date: April 2017
+Contact: Jeremy Kerr <jk@ozlabs.org>
+Description: Configures which IO port the host side of the UART
+ will appear on the host <-> BMC LPC bus.
+Users: OpenBMC. Proposed changes should be mailed to
+ openbmc@lists.ozlabs.org
+
+What: /sys/bus/platform/drivers/aspeed-vuart/*/sirq
+Date: April 2017
+Contact: Jeremy Kerr <jk@ozlabs.org>
+Description: Configures which interrupt number the host side of
+ the UART will appear on the host <-> BMC LPC bus.
+Users: OpenBMC. Proposed changes should be mailed to
+ openbmc@lists.ozlabs.org
+
+What: /sys/bus/platform/drivers/aspeed-vuart/*/sirq_polarity
+Date: July 2019
+Contact: Oskar Senft <osk@google.com>
+Description: Configures the polarity of the serial interrupt to the
+ host via the BMC LPC bus.
+ Set to 0 for active-low or 1 for active-high.
+Users: OpenBMC. Proposed changes should be mailed to
+ openbmc@lists.ozlabs.org
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd
new file mode 100644
index 000000000000..4a355e6747ae
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd
@@ -0,0 +1,361 @@
+What: /sys/bus/dsa/devices/dsa<m>/version
+Date: Apr 15, 2020
+KernelVersion: 5.8.0
+Contact: dmaengine@vger.kernel.org
+Description: The hardware version number.
+
+What: /sys/bus/dsa/devices/dsa<m>/cdev_major
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The major number that the character device driver assigned to
+ this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/errors
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The error information for this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_batch_size
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The largest number of work descriptors in a batch.
+ It's not visible when the device does not support batch.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_work_queues_size
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The maximum work queue size supported by this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_engines
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The maximum number of engines supported by this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_groups
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The maximum number of groups can be created under this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_read_buffers
+Date: Dec 10, 2021
+KernelVersion: 5.17.0
+Contact: dmaengine@vger.kernel.org
+Description: The total number of read buffers supported by this device.
+ The read buffers represent resources within the DSA
+ implementation, and these resources are allocated by engines to
+ support operations. See DSA spec v1.2 9.2.4 Total Read Buffers.
+ It's not visible when the device does not support Read Buffer
+ allocation control.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_transfer_size
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The number of bytes to be read from the source address to
+ perform the operation. The maximum transfer size is dependent on
+ the workqueue the descriptor was submitted to.
+
+What: /sys/bus/dsa/devices/dsa<m>/max_work_queues
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The maximum work queue number that this device supports.
+
+What: /sys/bus/dsa/devices/dsa<m>/numa_node
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The numa node number for this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/op_cap
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The operation capability bit mask specify the operation types
+ supported by the this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/pasid_enabled
+Date: Oct 27, 2020
+KernelVersion: 5.11.0
+Contact: dmaengine@vger.kernel.org
+Description: To indicate if user PASID (process address space identifier) is
+ enabled or not for this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/state
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The state information of this device. It can be either enabled
+ or disabled.
+
+What: /sys/bus/dsa/devices/dsa<m>/group<m>.<n>
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The assigned group under this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/engine<m>.<n>
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The assigned engine under this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/wq<m>.<n>
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The assigned work queue under this device.
+
+What: /sys/bus/dsa/devices/dsa<m>/configurable
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: To indicate if this device is configurable or not.
+
+What: /sys/bus/dsa/devices/dsa<m>/read_buffer_limit
+Date: Dec 10, 2021
+KernelVersion: 5.17.0
+Contact: dmaengine@vger.kernel.org
+Description: The maximum number of read buffers that may be in use at
+ one time by operations that access low bandwidth memory in the
+ device. See DSA spec v1.2 9.2.8 GENCFG on Global Read Buffer Limit.
+ It's not visible when the device does not support Read Buffer
+ allocation control.
+
+What: /sys/bus/dsa/devices/dsa<m>/cmd_status
+Date: Aug 28, 2020
+KernelVersion: 5.10.0
+Contact: dmaengine@vger.kernel.org
+Description: The last executed device administrative command's status/error.
+ Also last configuration error overloaded.
+ Writing to it will clear the status.
+
+What: /sys/bus/dsa/devices/dsa<m>/iaa_cap
+Date: Sept 14, 2022
+KernelVersion: 6.0.0
+Contact: dmaengine@vger.kernel.org
+Description: IAA (IAX) capability mask. Exported to user space for application
+ consumption. This attribute should only be visible on IAA devices
+ that are version 2 or later.
+
+What: /sys/bus/dsa/devices/dsa<m>/event_log_size
+Date: Sept 14, 2022
+KernelVersion: 6.4.0
+Contact: dmaengine@vger.kernel.org
+Description: The event log size to be configured. Default is 64 entries and
+ occupies 4k size if the evl entry is 64 bytes. It's visible
+ only on platforms that support the capability.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/block_on_fault
+Date: Oct 27, 2020
+KernelVersion: 5.11.0
+Contact: dmaengine@vger.kernel.org
+Description: To indicate block on fault is allowed or not for the work queue
+ to support on demand paging.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/group_id
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The group id that this work queue belongs to.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/size
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The work queue size for this work queue.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/type
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The type of this work queue, it can be "kernel" type for work
+ queue usages in the kernel space or "user" type for work queue
+ usages by applications in user space.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/cdev_minor
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The minor number assigned to this work queue by the character
+ device driver.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/mode
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The work queue mode type for this work queue.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/priority
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The priority value of this work queue, it is a value relative to
+ other work queue in the same group to control quality of service
+ for dispatching work from multiple workqueues in the same group.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/state
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The current state of the work queue.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/threshold
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The number of entries in this work queue that may be filled
+ via a limited portal.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/max_transfer_size
+Date: Aug 28, 2020
+KernelVersion: 5.10.0
+Contact: dmaengine@vger.kernel.org
+Description: The max transfer sized for this workqueue. Cannot exceed device
+ max transfer size. Configurable parameter.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/max_batch_size
+Date: Aug 28, 2020
+KernelVersion: 5.10.0
+Contact: dmaengine@vger.kernel.org
+Description: The max batch size for this workqueue. Cannot exceed device
+ max batch size. Configurable parameter.
+ It's not visible when the device does not support batch.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/ats_disable
+Date: Nov 13, 2020
+KernelVersion: 5.11.0
+Contact: dmaengine@vger.kernel.org
+Description: Indicate whether ATS disable is turned on for the workqueue.
+ 0 indicates ATS is on, and 1 indicates ATS is off for the workqueue.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/prs_disable
+Date: Sept 14, 2022
+KernelVersion: 6.4.0
+Contact: dmaengine@vger.kernel.org
+Description: Controls whether PRS disable is turned on for the workqueue.
+ 0 indicates PRS is on, and 1 indicates PRS is off for the
+ workqueue. This option overrides block_on_fault attribute
+ if set. It's visible only on platforms that support the
+ capability.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/occupancy
+Date: May 25, 2021
+KernelVersion: 5.14.0
+Contact: dmaengine@vger.kernel.org
+Description: Show the current number of entries in this WQ if WQ Occupancy
+ Support bit WQ capabilities is 1.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/enqcmds_retries
+Date: Oct 29, 2021
+KernelVersion: 5.17.0
+Contact: dmaengine@vger.kernel.org
+Description: Indicate the number of retires for an enqcmds submission on a sharedwq.
+ A max value to set attribute is capped at 64.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/op_config
+Date: Sept 14, 2022
+KernelVersion: 6.0.0
+Contact: dmaengine@vger.kernel.org
+Description: Shows the operation capability bits displayed in bitmap format
+ presented by %*pb printk() output format specifier.
+ The attribute can be configured when the WQ is disabled in
+ order to configure the WQ to accept specific bits that
+ correlates to the operations allowed. It's visible only
+ on platforms that support the capability.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/driver_name
+Date: Sept 8, 2023
+KernelVersion: 6.7.0
+Contact: dmaengine@vger.kernel.org
+Description: Name of driver to be bounded to the wq.
+
+What: /sys/bus/dsa/devices/engine<m>.<n>/group_id
+Date: Oct 25, 2019
+KernelVersion: 5.6.0
+Contact: dmaengine@vger.kernel.org
+Description: The group that this engine belongs to.
+
+What: /sys/bus/dsa/devices/group<m>.<n>/use_read_buffer_limit
+Date: Dec 10, 2021
+KernelVersion: 5.17.0
+Contact: dmaengine@vger.kernel.org
+Description: Enable the use of global read buffer limit for the group. See DSA
+ spec v1.2 9.2.18 GRPCFG Use Global Read Buffer Limit.
+ It's not visible when the device does not support Read Buffer
+ allocation control.
+
+What: /sys/bus/dsa/devices/group<m>.<n>/read_buffers_allowed
+Date: Dec 10, 2021
+KernelVersion: 5.17.0
+Contact: dmaengine@vger.kernel.org
+Description: Indicates max number of read buffers that may be in use at one time
+ by all engines in the group. See DSA spec v1.2 9.2.18 GRPCFG Read
+ Buffers Allowed.
+ It's not visible when the device does not support Read Buffer
+ allocation control.
+
+What: /sys/bus/dsa/devices/group<m>.<n>/read_buffers_reserved
+Date: Dec 10, 2021
+KernelVersion: 5.17.0
+Contact: dmaengine@vger.kernel.org
+Description: Indicates the number of Read Buffers reserved for the use of
+ engines in the group. See DSA spec v1.2 9.2.18 GRPCFG Read Buffers
+ Reserved.
+ It's not visible when the device does not support Read Buffer
+ allocation control.
+
+What: /sys/bus/dsa/devices/group<m>.<n>/desc_progress_limit
+Date: Sept 14, 2022
+KernelVersion: 6.0.0
+Contact: dmaengine@vger.kernel.org
+Description: Allows control of the number of work descriptors that can be
+ concurrently processed by an engine in the group as a fraction
+ of the Maximum Work Descriptors in Progress value specified in
+ the ENGCAP register. The acceptable values are 0 (default),
+ 1 (1/2 of max value), 2 (1/4 of the max value), and 3 (1/8 of
+ the max value). It's visible only on platforms that support
+ the capability.
+
+What: /sys/bus/dsa/devices/group<m>.<n>/batch_progress_limit
+Date: Sept 14, 2022
+KernelVersion: 6.0.0
+Contact: dmaengine@vger.kernel.org
+Description: Allows control of the number of batch descriptors that can be
+ concurrently processed by an engine in the group as a fraction
+ of the Maximum Batch Descriptors in Progress value specified in
+ the ENGCAP register. The acceptable values are 0 (default),
+ 1 (1/2 of max value), 2 (1/4 of the max value), and 3 (1/8 of
+ the max value). It's visible only on platforms that support
+ the capability.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/dsa<x>\!wq<m>.<n>/file<y>/cr_faults
+Date: Sept 14, 2022
+KernelVersion: 6.4.0
+Contact: dmaengine@vger.kernel.org
+Description: Show the number of Completion Record (CR) faults this application
+ has caused.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/dsa<x>\!wq<m>.<n>/file<y>/cr_fault_failures
+Date: Sept 14, 2022
+KernelVersion: 6.4.0
+Contact: dmaengine@vger.kernel.org
+Description: Show the number of Completion Record (CR) faults failures that this
+ application has caused. The failure counter is incremented when the
+ driver cannot fault in the address for the CR. Typically this is caused
+ by a bad address programmed in the submitted descriptor or a malicious
+ submitter is using bad CR address on purpose.
+
+What: /sys/bus/dsa/devices/wq<m>.<n>/dsa<x>\!wq<m>.<n>/file<y>/pid
+Date: Sept 14, 2022
+KernelVersion: 6.4.0
+Contact: dmaengine@vger.kernel.org
+Description: Show the process id of the application that opened the file. This is
+ helpful information for a monitor daemon that wants to kill the
+ application that opened the file.
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma
new file mode 100644
index 000000000000..3a4e2cd0ddcc
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma
@@ -0,0 +1,30 @@
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/cap
+Date: December 3, 2009
+KernelVersion: 2.6.32
+Contact: dmaengine@vger.kernel.org
+Description: Capabilities the DMA supports.Currently there are DMA_PQ, DMA_PQ_VAL,
+ DMA_XOR,DMA_XOR_VAL,DMA_INTERRUPT.
+
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_active
+Date: December 3, 2009
+KernelVersion: 2.6.32
+Contact: dmaengine@vger.kernel.org
+Description: The number of descriptors active in the ring.
+
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_size
+Date: December 3, 2009
+KernelVersion: 2.6.32
+Contact: dmaengine@vger.kernel.org
+Description: Descriptor ring size, total number of descriptors available.
+
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/version
+Date: December 3, 2009
+KernelVersion: 2.6.32
+Contact: dmaengine@vger.kernel.org
+Description: Version of ioatdma device.
+
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/intr_coalesce
+Date: August 8, 2017
+KernelVersion: 4.14
+Contact: dmaengine@vger.kernel.org
+Description: Tune-able interrupt delay value per channel basis.
diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
new file mode 100644
index 000000000000..c3fec3c835af
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
@@ -0,0 +1,256 @@
+What: /sys/devices/platform/firmware\:zynqmp-firmware/ggs*
+Date: March 2020
+KernelVersion: 5.6
+Contact: "Jolly Shah" <jollys@xilinx.com>
+Description:
+ Read/Write PMU global general storage register value,
+ GLOBAL_GEN_STORAGE{0:3}.
+ Global general storage register that can be used
+ by system to pass information between masters.
+
+ The register is reset during system or power-on
+ resets. Three registers are used by the FSBL and
+ other Xilinx software products: GLOBAL_GEN_STORAGE{4:6}.
+
+ Usage::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+ # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+
+ Example::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+ # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+
+Users: Xilinx
+
+What: /sys/devices/platform/firmware\:zynqmp-firmware/pggs*
+Date: March 2020
+KernelVersion: 5.6
+Contact: "Jolly Shah" <jollys@xilinx.com>
+Description:
+ Read/Write PMU persistent global general storage register
+ value, PERS_GLOB_GEN_STORAGE{0:3}.
+ Persistent global general storage register that
+ can be used by system to pass information between
+ masters.
+
+ This register is only reset by the power-on reset
+ and maintains its value through a system reset.
+ Four registers are used by the FSBL and other Xilinx
+ software products: PERS_GLOB_GEN_STORAGE{4:7}.
+ Register is reset only by a POR reset.
+
+ Usage::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+ # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+
+ Example::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+ # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+
+Users: Xilinx
+
+What: /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+Date: March 2020
+KernelVersion: 5.6
+Contact: "Jolly Shah" <jollys@xilinx.com>
+Description:
+ This sysfs interface allows to set the shutdown scope for the
+ next shutdown request. When the next shutdown is performed, the
+ platform specific portion of PSCI-system_off can use the chosen
+ shutdown scope.
+
+ Following are available shutdown scopes(subtypes):
+
+ subsystem:
+ Only the APU along with all of its peripherals
+ not used by other processing units will be
+ shut down. This may result in the FPD power
+ domain being shut down provided that no other
+ processing unit uses FPD peripherals or DRAM.
+ ps_only:
+ The complete PS will be shut down, including the
+ RPU, PMU, etc. Only the PL domain (FPGA)
+ remains untouched.
+ system:
+ The complete system/device is shut down.
+
+ Usage::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+ # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+
+ Example::
+
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+ # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+
+Users: Xilinx
+
+What: /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+Date: March 2020
+KernelVersion: 5.6
+Contact: "Jolly Shah" <jollys@xilinx.com>
+Description:
+ This sysfs interface allows to set the health status. If PMUFW
+ is compiled with CHECK_HEALTHY_BOOT, it will check the healthy
+ bit on FPD WDT expiration. If healthy bit is set by a user
+ application running in Linux, PMUFW will do APU only restart. If
+ healthy bit is not set during FPD WDT expiration, PMUFW will do
+ system restart.
+
+ Usage:
+
+ Set healthy bit::
+
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+
+ Unset healthy bit::
+
+ # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+
+Users: Xilinx
+
+What: /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "Ronak Jain" <ronak.jain@xilinx.com>
+Description:
+ This sysfs interface allows user to configure features at
+ runtime. The user can enable or disable features running at
+ firmware as well as the user can configure the parameters of
+ the features at runtime. The supported features are over
+ temperature and external watchdog. Here, the external watchdog
+ is completely different than the /dev/watchdog as the external
+ watchdog is running on the firmware and it is used to monitor
+ the health of firmware not APU(Linux). Also, the external
+ watchdog is interfaced outside of the zynqmp soc.
+
+ The supported config ids are for the feature configuration is,
+ 1. PM_FEATURE_OVERTEMP_STATUS = 1, the user can enable or
+ disable the over temperature feature.
+ 2. PM_FEATURE_OVERTEMP_VALUE = 2, the user can configure the
+ over temperature limit in Degree Celsius.
+ 3. PM_FEATURE_EXTWDT_STATUS = 3, the user can enable or disable
+ the external watchdog feature.
+ 4. PM_FEATURE_EXTWDT_VALUE = 4, the user can configure the
+ external watchdog feature.
+
+ Usage:
+
+ Select over temperature config ID to enable/disable feature
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+
+ Check over temperature config ID is selected or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ The expected result is 1.
+
+ Select over temperature config ID to configure OT limit
+ # echo 2 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+
+ Check over temperature config ID is selected or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ The expected result is 2.
+
+ Select external watchdog config ID to enable/disable feature
+ # echo 3 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+
+ Check external watchdog config ID is selected or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ The expected result is 3.
+
+ Select external watchdog config ID to configure time interval
+ # echo 4 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+
+ Check external watchdog config ID is selected or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ The expected result is 4.
+
+Users: Xilinx
+
+What: /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "Ronak Jain" <ronak.jain@xilinx.com>
+Description:
+ This sysfs interface allows to configure features at runtime.
+ The user can enable or disable features running at firmware.
+ Also, the user can configure the parameters of the features
+ at runtime. The supported features are over temperature and
+ external watchdog. Here, the external watchdog is completely
+ different than the /dev/watchdog as the external watchdog is
+ running on the firmware and it is used to monitor the health
+ of firmware not APU(Linux). Also, the external watchdog is
+ interfaced outside of the zynqmp soc.
+
+ By default the features are disabled in the firmware. The user
+ can enable features by querying appropriate config id of the
+ features.
+
+ The default limit for the over temperature is 90 Degree Celsius.
+ The default timer interval for the external watchdog is 570ms.
+
+ The supported config ids are for the feature configuration is,
+ 1. PM_FEATURE_OVERTEMP_STATUS = 1, the user can enable or
+ disable the over temperature feature.
+ 2. PM_FEATURE_OVERTEMP_VALUE = 2, the user can configure the
+ over temperature limit in Degree Celsius.
+ 3. PM_FEATURE_EXTWDT_STATUS = 3, the user can enable or disable
+ the external watchdog feature.
+ 4. PM_FEATURE_EXTWDT_VALUE = 4, the user can configure the
+ external watchdog feature.
+
+ Usage:
+
+ Enable over temperature feature
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+
+ Check whether the over temperature feature is enabled or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+ The expected result is 1.
+
+ Disable over temperature feature
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+
+ Check whether the over temperature feature is disabled or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+ The expected result is 0.
+
+ Configure over temperature limit to 50 Degree Celsius
+ # echo 2 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ # echo 50 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+
+ Check whether the over temperature limit is configured or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+ The expected result is 50.
+
+ Enable external watchdog feature
+ # echo 3 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+
+ Check whether the external watchdog feature is enabled or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+ The expected result is 1.
+
+ Disable external watchdog feature
+ # echo 3 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+
+ Check whether the external watchdog feature is disabled or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+ The expected result is 0.
+
+ Configure external watchdog timer interval to 500ms
+ # echo 4 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_id
+ # echo 500 > /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+
+ Check whether the external watchdog timer interval is configured or not
+ # cat /sys/devices/platform/firmware\:zynqmp-firmware/feature_config_value
+ The expected result is 500.
+
+Users: Xilinx
diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp
index 7049a2b50359..bada15a329f7 100644
--- a/Documentation/ABI/stable/sysfs-driver-ib_srp
+++ b/Documentation/ABI/stable/sysfs-driver-ib_srp
@@ -6,6 +6,7 @@ Description: Interface for making ib_srp connect to a new target.
One can request ib_srp to connect to a new target by writing
a comma-separated list of login parameters to this sysfs
attribute. The supported parameters are:
+
* id_ext, a 16-digit hexadecimal number specifying the eight
byte identifier extension in the 16-byte SRP target port
identifier. The target port identifier is sent by ib_srp
@@ -67,6 +68,8 @@ Description: Interface for making ib_srp connect to a new target.
initiator is allowed to queue per SCSI host. The default
value for this parameter is 62. The lowest supported value
is 2.
+ * max_it_iu_size, a decimal number specifying the maximum
+ initiator to target information unit length.
What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/ibdev
Date: January 2, 2006
diff --git a/Documentation/ABI/stable/sysfs-driver-misc-cp500 b/Documentation/ABI/stable/sysfs-driver-misc-cp500
new file mode 100644
index 000000000000..525bd18a2db4
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-misc-cp500
@@ -0,0 +1,25 @@
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/0000:XX:XX.X/version
+Date: June 2024
+KernelVersion: 6.11
+Contact: Gerhard Engleder <eg@keba.com>
+Description: Version of the FPGA configuration bitstream as printable string.
+ This file is read only.
+Users: KEBA
+
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/0000:XX:XX.X/keep_cfg
+Date: June 2024
+KernelVersion: 6.11
+Contact: Gerhard Engleder <eg@keba.com>
+Description: Flag which signals if FPGA shall keep or reload configuration
+ bitstream on reset. Normal FPGA behavior and default is to keep
+ configuration bitstream and to only reset the configured logic.
+
+ Reloading configuration on reset enables an update of the
+ configuration bitstream with a simple reboot. Otherwise it is
+ necessary to power cycle the device to reload the new
+ configuration bitstream.
+
+ This file is read/write. The values are as follows:
+ 1 = keep configuration bitstream on reset, default
+ 0 = reload configuration bitstream on reset
+Users: KEBA
diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
new file mode 100644
index 000000000000..f59461111221
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io
@@ -0,0 +1,815 @@
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_health
+Date: June 2018
+KernelVersion: 4.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows ASIC health status. The possible values are:
+ 0 - health failed, 2 - health OK, 3 - ASIC in booting state.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version
+Date: June 2018
+KernelVersion: 4.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which CPLD versions have been burned
+ on carrier and switch boards.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/fan_dir
+Date: December 2018
+KernelVersion: 5.0
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows the system fans direction:
+ forward direction - relevant bit is set 0;
+ reversed direction - relevant bit is set 1.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_version
+Date: November 2018
+KernelVersion: 5.0
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which CPLD versions have been burned
+ on LED or Gearbox board.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_enable
+Date: November 2018
+KernelVersion: 5.0
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files enable and disable the access to the JTAG domain.
+ By default access to the JTAG domain is disabled.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/select_iio
+Date: June 2018
+KernelVersion: 4.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows iio devices selection.
+
+ Attribute select_iio can be written with 0 or with 1. It
+ selects which one of iio devices can be accessed.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/psu1_on
+ /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/psu2_on
+ /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pwr_cycle
+ /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pwr_down
+Date: June 2018
+KernelVersion: 4.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow asserting system power cycling, switching
+ power supply units on and off and system's main power domain
+ shutdown.
+ Expected behavior:
+ When pwr_cycle is written 1: auxiliary power domain will go
+ down and after short period (about 1 second) up.
+ When psu1_on or psu2_on is written 1, related unit will be
+ disconnected from the power source, when written 0 - connected.
+ If both are written 1 - power supplies main power domain will
+ go down.
+ When pwr_down is written 1, system's main power domain will go
+ down.
+
+ The files are write only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_aux_pwr_or_ref
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_asic_thermal
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_halt
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_hotswap_or_wd
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_fw_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_main_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_short_pb
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_reset
+Date: June 2018
+KernelVersion: 4.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show the system reset cause, as following: power
+ auxiliary outage or power refresh, ASIC thermal shutdown, halt,
+ hotswap, watchdog, firmware reset, long press power button,
+ short press power button, software reset. Value 1 in file means
+ this is reset cause, 0 - otherwise. Only one of the above
+ causes could be 1 at the same time, representing only last
+ reset cause.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_comex
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_system
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_voltmon_upgrade_fail
+Date: November 2018
+KernelVersion: 5.0
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show the system reset cause, as following: ComEx
+ power fail, reset from ComEx, system platform reset, reset
+ due to voltage monitor devices upgrade failure,
+ Value 1 in file means this is reset cause, 0 - otherwise.
+ Only one bit could be 1 at the same time, representing only
+ the last reset cause.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_version
+Date: November 2018
+KernelVersion: 5.0
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which CPLD versions have been burned
+ on LED board.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd
+Date: June 2019
+KernelVersion: 5.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show the system reset cause, as following:
+ COMEX thermal shutdown; wathchdog power off or reset was derived
+ by one of the next components: COMEX, switch board or by Small Form
+ Factor mezzanine, reset requested from ASIC, reset caused by BIOS
+ reload. Value 1 in file means this is reset cause, 0 - otherwise.
+ Only one of the above causes could be 1 at the same time, representing
+ only last reset cause.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/config1
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/config2
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show system static topology identification
+ like system's static I2C topology, number and type of FPGA
+ devices within the system and so on.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_ac_pwr_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_platform
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_soc
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sw_pwr_off
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show the system reset causes, as following: reset
+ due to AC power failure, reset invoked from software by
+ assertion reset signal through CPLD. reset caused by signal
+ asserted by SOC through ACPI register, reset invoked from
+ software by assertion power off signal through CPLD.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pcie_asic_reset_dis
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows to retain ASIC up during PCIe root complex
+ reset, when attribute is set 1.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/vpd_wp
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows to overwrite system VPD hardware write
+ protection when attribute is set 1.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/voltreg_update_status
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file exposes the configuration update status of burnable
+ voltage regulator devices. The status values are as following:
+ 0 - OK; 1 - CRC failure; 2 = I2C failure; 3 - in progress.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ufm_version
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file exposes the firmware version of burnable voltage
+ regulator devices.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version_min
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version_min
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_version_min
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_version_min
+Date: July 2020
+KernelVersion: 5.9
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which CPLD part numbers and minor
+ versions have been burned CPLD devices equipped on a
+ system.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/bios_active_image
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/bios_auth_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/bios_upgrade_fail
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: The files represent BIOS statuses:
+
+ bios_active_image: location of current active BIOS image:
+ 0: Top, 1: Bottom.
+ The reported value should correspond to value expected by OS
+ in case of BIOS safe mode is 0. This bit is related to Intel
+ top-swap feature of DualBios on the same flash.
+
+ bios_auth_fail: BIOS upgrade is failed because provided BIOS
+ image is not signed correctly.
+
+ bios_upgrade_fail: BIOS upgrade is failed by some other
+ reason not because authentication. For example due to
+ physical SPI flash problem.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc1_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc2_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc3_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc4_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc5_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc6_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc7_enable
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc8_enable
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow line cards enable state control.
+ Expected behavior:
+ When lc{n}_enable is written 1, related line card is released
+ from the reset state, when 0 - is hold in reset state.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc1_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc2_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc3_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc4_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc5_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc6_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc7_pwr
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc8_pwr
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files switching line cards power on and off.
+ Expected behavior:
+ When lc{n}_pwr is written 1, related line card is powered
+ on, when written 0 - powered off.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc1_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc2_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc3_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc4_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc5_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc6_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc7_rst_mask
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lc8_rst_mask
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files clear line card reset bit enforced by ASIC, when it
+ sets it due to some abnormal ASIC behavior.
+ Expected behavior:
+ When lc{n}_rst_mask is written 1, related line card reset bit
+ is cleared, when written 0 - no effect.
+
+ The files are write only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/os_started
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file, when written 1, indicates to programmable devices
+ that OS is taking control over it.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pm_mgmt_en
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file assigns power management control ownership.
+ When power management control is provided by hardware, hardware
+ will automatically power off one or more line previously
+ powered line cards in case system power budget is getting
+ insufficient. It could be in case when some of power units lost
+ power good state.
+ When pm_mgmt_en is written 1, power management control by
+ software is enabled, 0 - power management control by hardware.
+ Note that for any setting of pm_mgmt_en attribute hardware will
+ not allow to power on any new line card in case system power
+ budget is insufficient.
+ Same in case software will try to power on several line cards
+ at once - hardware will power line cards while system has
+ enough power budget.
+ Default is 0.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/psu3_on
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/psu4_on
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files switching power supply units on and off.
+ Expected behavior:
+ When psu3_on or psu4_on is written 1, related unit will be
+ disconnected from the power source, when written 0 - connected.
+
+ The files are write only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/shutdown_unlock
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows to unlock ASIC after thermal shutdown event.
+ When system thermal shutdown is enforced by ASIC, ASIC is
+ getting locked and after system boot it will not be available.
+ Software can decide to unlock it by setting this attribute to
+ 1 and then perform system power cycle by setting pwr_cycle
+ attribute to 1 (power cycle of main power domain).
+ Before setting shutdown_unlock to 1 it is recommended to
+ validate that system reboot cause is reset_asic_thermal or
+ reset_thermal_spc_or_pciesw.
+ In case shutdown_unlock is not set 1, the only way to release
+ ASIC from locking - is full system power cycle through the
+ external power distribution unit.
+ Default is 1.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/cpld1_pn
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/cpld1_version
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/cpld1_version_min
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which CPLD major and minor versions
+ and part number has been burned CPLD device on line card.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/fpga1_pn
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/fpga1_version
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/fpga1_version_min
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which FPGA major and minor versions
+ and part number has been burned FPGA device on line card.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/vpd_wp
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allow to overwrite line card VPD hardware write
+ protection mode. When attribute is set 1 - write protection is
+ disabled, when 0 - enabled.
+ Default is 0.
+ If the system is in locked-down mode writing this file will not
+ be allowed.
+ The purpose if this file is to allow line card VPD burning
+ during production flow.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/reset_aux_pwr_or_ref
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/reset_dc_dc_pwr_fail
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/reset_fpga_not_done
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/reset_from_chassis
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/reset_line_card
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/reset_pwr_off_from_chassis
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show the line reset cause, as following: power
+ auxiliary outage or power refresh, DC-to-DC power failure, FPGA reset
+ failed, line card reset failed, power off from chassis.
+ Value 1 in file means this is reset cause, 0 - otherwise. Only one of
+ the above causes could be 1 at the same time, representing only last
+ reset cause.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/cpld_upgrade_en
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/fpga_upgrade_en
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow CPLD and FPGA burning. Value 1 in file means burning
+ is enabled, 0 - otherwise.
+ If the system is in locked-down mode writing these files will
+ not be allowed.
+ The purpose of these files to allow line card CPLD and FPGA
+ upgrade through the JTAG daisy-chain.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/qsfp_pwr_en
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/pwr_en
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow to power on/off all QSFP ports and whole line card.
+ The attributes are set 1 for power on, 0 - for power off.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/agb_spi_burn_en
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/fpga_spi_burn_en
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow gearboxes and FPGA SPI flash burning.
+ The attributes are set 1 to enable burning, 0 - to disable.
+ If the system is in locked-down mode writing these files will
+ not be allowed.
+ The purpose of these files to allow line card Gearboxes and FPGA
+ burning during production flow.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/max_power
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/i2c-*/*-0032/mlxreg-io.*/hwmon/hwmon*/config
+Date: October 2021
+KernelVersion: 5.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files provide the maximum powered required for line card
+ feeding and line card configuration Id.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/phy_reset
+Date: May 2022
+KernelVersion: 5.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows to reset PHY 88E1548 when attribute is set 0
+ due to some abnormal PHY behavior.
+ Expected behavior:
+ When phy_reset is written 1, all PHY 88E1548 are released
+ from the reset state, when 0 - are hold in reset state.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/mac_reset
+Date: May 2022
+KernelVersion: 5.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows to reset ASIC MT52132 when attribute is set 0
+ due to some abnormal ASIC behavior.
+ Expected behavior:
+ When mac_reset is written 1, the ASIC MT52132 is released
+ from the reset state, when 0 - is hold in reset state.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/qsfp_pwr_good
+Date: May 2022
+KernelVersion: 5.19
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows QSFP ports power status. The value is set to 0
+ when one of any QSFP ports is plugged. The value is set to 1 when
+ there are no any QSFP ports are plugged.
+ The possible values are:
+ 0 - Power good, 1 - Not power good.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic2_health
+Date: July 2022
+KernelVersion: 5.20
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows 2-nd ASIC health status. The possible values are:
+ 0 - health failed, 2 - health OK, 3 - ASIC in booting state.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic2_reset
+Date: July 2022
+KernelVersion: 5.20
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow to each of ASICs by writing 1.
+
+ The files are write only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/comm_chnl_ready
+Date: July 2022
+KernelVersion: 5.20
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file is used to indicate remote end (for example BMC) that system
+ host CPU is ready for sending telemetry data to remote end.
+ For indication the file should be written 1.
+
+ The file is write only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/config3
+Date: January 2020
+KernelVersion: 5.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: The file indicates COME module hardware configuration.
+ The value is pushed by hardware through GPIO pins.
+ The purpose is to expose some minor BOM changes for the same system SKU.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_pwr_converter_fail
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows the system reset cause due to power converter
+ devices failure.
+ Value 1 in file means this is reset cause, 0 - otherwise.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_ap_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_ap_reset
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files aim to monitor the status of the External Root of Trust (EROT)
+ processor's RESET output to the Application Processor (AP).
+ By reading this file, could be determined if the EROT has invalidated or
+ revoked AP Firmware, at which point it will hold the AP in RESET until a
+ valid firmware is loaded. This protects the AP from running an
+ unauthorized firmware. In the normal flow, the AP reset should be released
+ after the EROT validates the integrity of the FW, and it should be done so
+ as quickly as possible so that the AP boots before the CPU starts to
+ communicate to each ASIC.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_recovery
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_recovery
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_reset
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_reset
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files aim to perform External Root of Trust (EROT) recovery
+ sequence after EROT device failure.
+ These EROT devices protect ASICs from unauthorized access and in normal
+ flow their reset should be released with system power – earliest power
+ up stage, so that EROTs can begin boot and authentication process before
+ CPU starts to communicate to ASICs.
+ Issuing a reset to the EROT while asserting the recovery signal will cause
+ the EROT Application Processor to enter recovery mode so that the EROT FW
+ can be updated/recovered.
+ For reset/recovery the related file should be toggled by 1/0.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot1_wp
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/erot2_wp
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow access to External Root of Trust (EROT) for reset
+ and recovery sequence after EROT device failure.
+ Default is 0 (programming disabled).
+ If the system is in locked-down mode writing this file will not be allowed.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/spi_chnl_select
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file allows SPI chip selection for External Root of Trust (EROT)
+ device Out-of-Band recovery.
+ File can be written with 0 or with 1. It selects which EROT can be accessed
+ through SPI device.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/asic_pg_fail
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak vadimp@nvidia.com
+Description: This file shows ASIC Power Good status.
+ Value 1 in file means ASIC Power Good failed, 0 - otherwise.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd1_boot_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd2_boot_fail
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd_fail
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak vadimp@nvidia.com
+Description: These files are related to clock boards status in system.
+ - clk_brd1_boot_fail: warning about 1-st clock board failed to boot from CI.
+ - clk_brd2_boot_fail: warning about 2-nd clock board failed to boot from CI.
+ - clk_brd_fail: error about common clock board boot failure.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/clk_brd_prog_en
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file enables programming of clock boards.
+ Default is 0 (programming disabled).
+ If the system is in locked-down mode writing this file will not be allowed.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/pwr_converter_prog_en
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file enables programming of power converters.
+ Default is 0 (programming disabled).
+ If the system is in locked-down mode writing this file will not be allowed.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_ac_ok_fail
+Date: February 2023
+KernelVersion: 6.3
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows the system reset cause due to AC power failure.
+ Value 1 in file means this is reset cause, 0 - otherwise.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld5_pn
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld5_version
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld5_version_min
+Date: August 2023
+KernelVersion: 6.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show with which CPLD part numbers, version and minor
+ versions have been burned the 5-th CPLD device equipped on a
+ system.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/jtag_cap
+Date: August 2023
+KernelVersion: 6.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file indicates the available method of CPLD/FPGA devices
+ field update through the JTAG chain:
+
+ b00 - field update through LPC bus register memory space.
+ b01 - Reserved.
+ b10 - Reserved.
+ b11 - field update through CPU GPIOs bit-banging.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/lid_open
+Date: August 2023
+KernelVersion: 6.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: 1 - indicates that system lid is opened, otherwise 0.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_long_pwr_pb
+Date: August 2023
+KernelVersion: 6.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file if set 1 indicates that system has been reset by
+ long press of power button.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_dc_dc_pwr_fail
+Date: August 2023
+KernelVersion: 6.6
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows 1 in case the system reset happened due to the
+ failure of any DC-DC power converter devices equipped on the
+ switch board.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/global_wp_request
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file when written 1 activates request to allow access to
+ the write protected flashes. Such request can be performed only
+ for system equipped with BMC (Board Management Controller),
+ which can grant access to protected flashes. In case BMC allows
+ access - it will respond with "global_wp_response". BMC decides
+ regarding time window of granted access. After granted window is
+ expired, BMC will change value back to 0.
+ Default value is 0.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/global_wp_response
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file, when set 1, indicates that access to protected
+ flashes have been granted to host CPU by BMC.
+ Default value is 0.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/shutdown_unlock
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: When ASICs are getting overheated, system protection
+ hardware mechanism enforces system reboot. After system
+ reboot ASICs come up in locked state. To unlock ASICs,
+ this file should be written 1
+ Default value is 0.
+
+ The file is read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/boot_progress
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show the Data Process Unit board boot progress
+ state. Valid states are:
+ - 4 : OS starting.
+ - 5 : OS running.
+ - 6 : Low-Power Standby.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/dpu_id
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: This file shows hardware Id of Data Process Unit board.
+
+ The file is read only.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/reset_aux_pwr_or_reload
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/reset_dpu_thermal
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/reset_from_main_board
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files expose the cause of the most recent reset of the Data
+ Processing Unit (DPU) board. The possible causes are:
+ - Power auxiliary outage or power reload.
+ - Thermal shutdown.
+ - Reset request from the main board.
+ Value 1 in file means this is reset cause, 0 - otherwise. Only one of
+ the above causes could be 1 at the same time, representing only last
+ reset cause.
+
+ The files are read only.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/perst_rst
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/phy_rst
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/tpm_rst
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/usbphy_rst
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files allow to reset hardware components of Data Process
+ Unit board. Respectively PCI, Ethernet PHY, TPM and USB PHY
+ resets.
+ Default values for all the attributes is 1. Writing 0 will
+ cause reset of the related component.
+
+ The files are read/write.
+
+What: /sys/devices/platform/mlxplat/i2c_mlxcpld.*/i2c-*/i2c-*/*-00**/mlxreg-io.*/hwmon/hwmon*/ufm_upgrade
+Date: May 2025
+KernelVersion: 6.16
+Contact: Vadim Pasternak <vadimp@nvidia.com>
+Description: These files show status of Unified Fabric Manager upgrade.
+ state. 0 - means upgrade is done, 1 - otherwise.
+
+ The file is read only.
diff --git a/Documentation/ABI/stable/sysfs-driver-qaic b/Documentation/ABI/stable/sysfs-driver-qaic
new file mode 100644
index 000000000000..c767a93342b3
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-qaic
@@ -0,0 +1,19 @@
+What: /sys/bus/pci/drivers/qaic/XXXX:XX:XX.X/accel/accel<minor_nr>/dbc<N>_state
+Date: October 2025
+KernelVersion: 6.19
+Contact: Jeff Hugo <jeff.hugo@oss.qualcomm.com>
+Description: Represents the current state of DMA Bridge channel (DBC). Below are the possible
+ states:
+
+ =================== ==========================================================
+ IDLE (0) DBC is free and can be activated
+ ASSIGNED (1) DBC is activated and a workload is running on device
+ BEFORE_SHUTDOWN (2) Sub-system associated with this workload has crashed and
+ it will shutdown soon
+ AFTER_SHUTDOWN (3) Sub-system associated with this workload has crashed and
+ it has shutdown
+ BEFORE_POWER_UP (4) Sub-system associated with this workload is shutdown and
+ it will be powered up soon
+ AFTER_POWER_UP (5) Sub-system associated with this workload is now powered up
+ =================== ==========================================================
+Users: Any userspace application or clients interested in DBC state.
diff --git a/Documentation/ABI/stable/sysfs-driver-speakup b/Documentation/ABI/stable/sysfs-driver-speakup
new file mode 100644
index 000000000000..bcb6831aa114
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-speakup
@@ -0,0 +1,395 @@
+What: /sys/accessibility/speakup/attrib_bleep
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Beeps the PC speaker when there is an attribute change such as
+ foreground or background color when using speakup review
+ commands. One = on, zero = off.
+
+What: /sys/accessibility/speakup/bell_pos
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This works much like a typewriter bell. If for example 72 is
+ echoed to bell_pos, it will beep the PC speaker when typing on
+ a line past character 72.
+
+What: /sys/accessibility/speakup/bleeps
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This controls whether one hears beeps through the PC speaker
+ when using speakup's review commands.
+ TODO: what values does it accept?
+
+What: /sys/accessibility/speakup/bleep_time
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This controls the duration of the PC speaker beeps speakup
+ produces.
+ TODO: What are the units? Jiffies?
+
+What: /sys/accessibility/speakup/cursor_time
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This controls cursor delay when using arrow keys. When a
+ connection is very slow, with the default setting, when moving
+ with the arrows, or backspacing etc. speakup says the incorrect
+ characters. Set this to a higher value to adjust for the delay
+ and better synchronisation between cursor position and speech.
+
+What: /sys/accessibility/speakup/cur_phonetic
+KernelVersion: 6.2
+Contact: speakup@linux-speakup.org
+Description: This allows speakup to speak letters phoneticaly when arrowing through
+ a word letter by letter. This doesn't affect the spelling when typing
+ the characters. When cur_phonetic=1, speakup will speak characters
+ phoneticaly when arrowing over a letter. When cur_phonetic=0, speakup
+ will speak letters as normally.
+
+What: /sys/accessibility/speakup/delimiters
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Delimit a word from speakup.
+ TODO: add more info
+
+What: /sys/accessibility/speakup/ex_num
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO:
+
+What: /sys/accessibility/speakup/key_echo
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Controls if speakup speaks keys when they are typed. One = on,
+ zero = off or don't echo keys.
+
+What: /sys/accessibility/speakup/keymap
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Speakup keymap remaps keys to Speakup functions.
+ It uses a binary
+ format. A special program called genmap is needed to compile a
+ textual keymap into the binary format which is then loaded into
+ /sys/accessibility/speakup/keymap.
+
+What: /sys/accessibility/speakup/no_interrupt
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Controls if typing interrupts output from speakup. With
+ no_interrupt set to zero, typing on the keyboard will interrupt
+ speakup if for example
+ the say screen command is used before the
+ entire screen is read.
+
+ With no_interrupt set to one, if the say
+ screen command is used, and one then types on the keyboard,
+ speakup will continue to say the whole screen regardless until
+ it finishes.
+
+What: /sys/accessibility/speakup/punc_all
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This is a list of all the punctuation speakup should speak when
+ punc_level is set to four.
+
+What: /sys/accessibility/speakup/punc_level
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Controls the level of punctuation spoken as the screen is
+ displayed, not reviewed. Levels range from zero no punctuation,
+ to four, all punctuation. One corresponds to punc_some, two
+ corresponds to punc_most, and three as well as four both
+ correspond to punc_all. Some hardware synthesizers may have
+ different levels each corresponding to three and four for
+ punc_level. Also note that if punc_level is set to zero, and
+ key_echo is set to one, typed punctuation is still spoken as it
+ is typed.
+
+What: /sys/accessibility/speakup/punc_most
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This is a list of all the punctuation speakup should speak when
+ punc_level is set to two.
+
+What: /sys/accessibility/speakup/punc_some
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This is a list of all the punctuation speakup should speak when
+ punc_level is set to one.
+
+What: /sys/accessibility/speakup/reading_punc
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Almost the same as punc_level, the differences being that
+ reading_punc controls the level of punctuation when reviewing
+ the screen with speakup's screen review commands. The other
+ difference is that reading_punc set to three speaks punc_all,
+ and reading_punc set to four speaks all punctuation, including
+ spaces.
+
+What: /sys/accessibility/speakup/repeats
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: A list of characters speakup repeats. Normally, when there are
+ more than three characters in a row, speakup
+ just reads three of
+ those characters. For example, "......" would be read as dot,
+ dot, dot. If a . is added to the list of characters in repeats,
+ "......" would be read as dot, dot, dot, times six.
+
+What: /sys/accessibility/speakup/say_control
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: If set to one, speakup speaks shift, alt and control when those
+ keys are pressed. If say_control is set to zero, shift, ctrl,
+ and alt are not spoken when they are pressed.
+
+What: /sys/accessibility/speakup/say_word_ctl
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO:
+
+What: /sys/accessibility/speakup/silent
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO:
+
+What: /sys/accessibility/speakup/spell_delay
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This controls how fast a word is spelled
+ when speakup's say word
+ review command is pressed twice quickly to speak the current
+ word being reviewed. Zero just speaks the letters one after
+ another, while values one through four
+ seem to introduce more of
+ a pause between the spelling of each letter by speakup.
+
+What: /sys/accessibility/speakup/synth
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the synthesizer driver currently in use. Reading
+ synth returns the synthesizer driver currently in use. Writing
+ synth switches to the given synthesizer driver, provided it is
+ either built into the kernel, or already loaded as a module.
+
+What: /sys/accessibility/speakup/synth_direct
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Sends whatever is written to synth_direct
+ directly to the speech synthesizer in use, bypassing speakup.
+ This could be used to make the synthesizer speak
+ a string, or to
+ send control sequences to the synthesizer to change how the
+ synthesizer behaves.
+
+What: /sys/accessibility/speakup/version
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Reading version returns the version of speakup, and the version
+ of the synthesizer driver currently in use.
+
+What: /sys/accessibility/speakup/i18n/announcements
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This file contains various general announcements, most of which
+ cannot be categorized. You will find messages such as "You
+ killed Speakup", "I'm alive", "leaving help", "parked",
+ "unparked", and others. You will also find the names of the
+ screen edges and cursor tracking modes here.
+
+What: /sys/accessibility/speakup/i18n/chartab
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO
+
+What: /sys/accessibility/speakup/i18n/ctl_keys
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Here, you will find names of control keys. These are used with
+ Speakup's say_control feature.
+
+What: /sys/accessibility/speakup/i18n/function_names
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Here, you will find a list of names for Speakup functions.
+ These are used by the help system. For example, suppose that
+ you have activated help mode, and you pressed
+ keypad 3. Speakup
+ says: "keypad 3 is character, say next."
+ The message "character, say next" names a Speakup function, and
+ it comes from this function_names file.
+
+What: /sys/accessibility/speakup/i18n/states
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This file contains names for key states.
+ Again, these are part of the help system. For instance, if you
+ had pressed speakup + keypad 3, you would hear:
+ "speakup keypad 3 is go to bottom edge."
+
+ The speakup key is depressed, so the name of the key state is
+ speakup.
+
+ This part of the message comes from the states collection.
+
+What: /sys/accessibility/speakup/i18n/characters
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Through this sys entry, Speakup gives you the ability to change
+ how Speakup pronounces a given character. You could, for
+ example, change how some punctuation characters are spoken. You
+ can even change how Speakup will pronounce certain letters. For
+ further details see '12. Changing the Pronunciation of
+ Characters' in Speakup User's Guide (file spkguide.txt in
+ source).
+
+What: /sys/accessibility/speakup/i18n/colors
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: When you use the "say attributes" function, Speakup says the
+ name of the foreground and background colors. These names come
+ from the i18n/colors file.
+
+What: /sys/accessibility/speakup/i18n/formatted
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This group of messages contains embedded formatting codes, to
+ specify the type and width of displayed data. If you change
+ these, you must preserve all of the formatting codes, and they
+ must appear in the order used by the default messages.
+
+What: /sys/accessibility/speakup/i18n/key_names
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Again, key_names is used by Speakup's help system. In the
+ previous example, Speakup said that you pressed "keypad 3."
+ This name came from the key_names file.
+
+What: /sys/accessibility/speakup/<synth-name>/
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: In `/sys/accessibility/speakup` is a directory corresponding to
+ the synthesizer driver currently in use (E.G) `soft` for the
+ soft driver. This directory contains files which control the
+ speech synthesizer itself,
+ as opposed to controlling the speakup
+ screen reader. The parameters in this directory have the same
+ names and functions across all
+ supported synthesizers. The range
+ of values for freq, pitch, rate, and vol is the same for all
+ supported synthesizers, with the given range being internally
+ mapped by the driver to more or less fit the range of values
+ supported for a given parameter by the individual synthesizer.
+ Below is a description of values and parameters for soft
+ synthesizer, which is currently the most commonly used.
+
+What: /sys/accessibility/speakup/<synth-name>/caps_start
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This is the string that is sent to the synthesizer to cause it
+ to start speaking uppercase letters. For the soft synthesizer
+ and most others, this causes the pitch of the voice to rise
+ above the currently set pitch.
+
+What: /sys/accessibility/speakup/<synth-name>/caps_stop
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This is the string sent to the synthesizer to cause it to stop
+ speaking uppercase letters. In the case of the soft synthesizer
+ and most others, this returns the pitch of the voice
+ down to the
+ currently set pitch.
+
+What: /sys/accessibility/speakup/<synth-name>/delay_time
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO:
+
+What: /sys/accessibility/speakup/<synth-name>/direct
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Controls if punctuation is spoken by speakup, or by the
+ synthesizer.
+
+ For example, speakup speaks ">" as "greater", while
+ the espeak synthesizer used by the soft driver speaks "greater
+ than". Zero lets speakup speak the punctuation. One lets the
+ synthesizer itself speak punctuation.
+
+What: /sys/accessibility/speakup/<synth-name>/freq
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the frequency of the speech synthesizer. Range is
+ 0-9.
+
+What: /sys/accessibility/speakup/<synth-name>/flush_time
+KernelVersion: 5.12
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the timeout to wait for the synthesizer flush to
+ complete. This can be used when the cable gets faulty and flush
+ notifications are getting lost.
+
+What: /sys/accessibility/speakup/<synth-name>/full_time
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO:
+
+What: /sys/accessibility/speakup/<synth-name>/jiffy_delta
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: This controls how many jiffys the kernel gives to the
+ synthesizer. Setting this too high can make a system unstable,
+ or even crash it.
+
+What: /sys/accessibility/speakup/<synth-name>/pitch
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the pitch of the synthesizer. The range is 0-9.
+
+What: /sys/accessibility/speakup/<synth-name>/inflection
+KernelVersion: 5.8
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the inflection of the synthesizer, i.e. the pitch
+ range. The range is 0-9.
+
+What: /sys/accessibility/speakup/<synth-name>/punct
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the amount of punctuation spoken by the
+ synthesizer. The range for the soft driver seems to be 0-2.
+ TODO: How is this related to speakup's punc_level, or
+ reading_punc.
+
+What: /sys/accessibility/speakup/<synth-name>/rate
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the rate of the synthesizer. Range is from zero
+ slowest, to nine fastest.
+
+What: /sys/accessibility/speakup/<synth-name>/tone
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the tone of the speech synthesizer. The range for
+ the soft driver seems to be 0-2. This seems to make no
+ difference if using espeak and the espeakup connector.
+ TODO: does espeakup support different tonalities?
+
+What: /sys/accessibility/speakup/<synth-name>/trigger_time
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: TODO:
+
+What: /sys/accessibility/speakup/<synth-name>/voice
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the voice used by the synthesizer if the
+ synthesizer can speak in more than one voice. The range for the
+ soft driver is 0-7. Note that while espeak supports multiple
+ voices, this parameter will not set the voice when the espeakup
+ connector is used between speakup and espeak.
+
+What: /sys/accessibility/speakup/<synth-name>/vol
+KernelVersion: 2.6
+Contact: speakup@linux-speakup.org
+Description: Gets or sets the volume of the speech synthesizer. Range is 0-9,
+ with zero being the softest, and nine being the loudest.
+
diff --git a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc
index e960cd027e1e..a9e123ba32cd 100644
--- a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc
+++ b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc
@@ -25,38 +25,3 @@ Description:
4.2.2.
The files are read only.
-
-
-What: /sys/bus/usb/drivers/usbtmc/*/TermChar
-Date: August 2008
-Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-Description:
- This file is the TermChar value to be sent to the USB TMC
- device as described by the document, "Universal Serial Bus Test
- and Measurement Class Specification
- (USBTMC) Revision 1.0" as published by the USB-IF.
-
- Note that the TermCharEnabled file determines if this value is
- sent to the device or not.
-
-
-What: /sys/bus/usb/drivers/usbtmc/*/TermCharEnabled
-Date: August 2008
-Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-Description:
- This file determines if the TermChar is to be sent to the
- device on every transaction or not. For more details about
- this, please see the document, "Universal Serial Bus Test and
- Measurement Class Specification (USBTMC) Revision 1.0" as
- published by the USB-IF.
-
-
-What: /sys/bus/usb/drivers/usbtmc/*/auto_abort
-Date: August 2008
-Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-Description:
- This file determines if the transaction of the USB TMC
- device is to be automatically aborted if there is any error.
- For more details about this, please see the document,
- "Universal Serial Bus Test and Measurement Class Specification
- (USBTMC) Revision 1.0" as published by the USB-IF.
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds2438 b/Documentation/ABI/stable/sysfs-driver-w1_ds2438
new file mode 100644
index 000000000000..d2e7681cc287
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds2438
@@ -0,0 +1,13 @@
+What: /sys/bus/w1/devices/.../page1
+Date: April 2021
+Contact: Luiz Sampaio <sampaio.ime@gmail.com>
+Description: read the contents of the page1 of the DS2438
+ see Documentation/w1/slaves/w1_ds2438.rst for detailed information
+Users: any user space application which wants to communicate with DS2438
+
+What: /sys/bus/w1/devices/.../offset
+Date: April 2021
+Contact: Luiz Sampaio <sampaio.ime@gmail.com>
+Description: write the contents to the offset register of the DS2438
+ see Documentation/w1/slaves/w1_ds2438.rst for detailed information
+Users: any user space application which wants to communicate with DS2438
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
new file mode 100644
index 000000000000..534e63731a49
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -0,0 +1,6 @@
+What: /sys/bus/w1/devices/.../w1_seq
+Date: Apr 2015
+Contact: Matt Campbell <mattrcampbell@gmail.com>
+Description: Support for the DS28EA00 chain sequence function
+ see Documentation/w1/slaves/w1_therm.rst for detailed information
+Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars
deleted file mode 100644
index 5def20b9019e..000000000000
--- a/Documentation/ABI/stable/sysfs-firmware-efi-vars
+++ /dev/null
@@ -1,75 +0,0 @@
-What: /sys/firmware/efi/vars
-Date: April 2004
-Contact: Matt Domsch <Matt_Domsch@dell.com>
-Description:
- This directory exposes interfaces for interactive with
- EFI variables. For more information on EFI variables,
- see 'Variable Services' in the UEFI specification
- (section 7.2 in specification version 2.3 Errata D).
-
- In summary, EFI variables are named, and are classified
- into separate namespaces through the use of a vendor
- GUID. They also have an arbitrary binary value
- associated with them.
-
- The efivars module enumerates these variables and
- creates a separate directory for each one found. Each
- directory has a name of the form "<key>-<vendor guid>"
- and contains the following files:
-
- attributes: A read-only text file enumerating the
- EFI variable flags. Potential values
- include:
-
- EFI_VARIABLE_NON_VOLATILE
- EFI_VARIABLE_BOOTSERVICE_ACCESS
- EFI_VARIABLE_RUNTIME_ACCESS
- EFI_VARIABLE_HARDWARE_ERROR_RECORD
- EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS
-
- See the EFI documentation for an
- explanation of each of these variables.
-
- data: A read-only binary file that can be read
- to attain the value of the EFI variable
-
- guid: The vendor GUID of the variable. This
- should always match the GUID in the
- variable's name.
-
- raw_var: A binary file that can be read to obtain
- a structure that contains everything
- there is to know about the variable.
- For structure definition see "struct
- efi_variable" in the kernel sources.
-
- This file can also be written to in
- order to update the value of a variable.
- For this to work however, all fields of
- the "struct efi_variable" passed must
- match byte for byte with the structure
- read out of the file, save for the value
- portion.
-
- **Note** the efi_variable structure
- read/written with this file contains a
- 'long' type that may change widths
- depending on your underlying
- architecture.
-
- size: As ASCII representation of the size of
- the variable's value.
-
-
- In addition, two other magic binary files are provided
- in the top-level directory and are used for adding and
- removing variables:
-
- new_var: Takes a "struct efi_variable" and
- instructs the EFI firmware to create a
- new variable.
-
- del_var: Takes a "struct efi_variable" and
- instructs the EFI firmware to remove any
- variable that has a matching vendor GUID
- and variable key name.
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump
index 32fe7f5c4880..1f74f45327ba 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-dump
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump
@@ -7,6 +7,7 @@ Description:
This is only for the powerpc/powernv platform.
+ =============== ===============================================
initiate_dump: When '1' is written to it,
we will initiate a dump.
Read this file for supported commands.
@@ -19,8 +20,11 @@ Description:
and ID of the dump, use the id and type files.
Do not rely on any particular size of dump
type or dump id.
+ =============== ===============================================
Each dump has the following files:
+
+ =============== ===============================================
id: An ASCII representation of the dump ID
in hex (e.g. '0x01')
type: An ASCII representation of the type of
@@ -39,3 +43,4 @@ Description:
inaccessible.
Reading this file will get a list of
supported actions.
+ =============== ===============================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog
index e1f3058f5954..7c8a61a2d005 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-elog
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog
@@ -38,6 +38,7 @@ Description:
For each log entry (directory), there are the following
files:
+ ============== ================================================
id: An ASCII representation of the ID of the
error log, in hex - e.g. "0x01".
@@ -57,4 +58,5 @@ Description:
Shortly after acknowledging it, the log
entry will be removed from sysfs.
Reading this file will list the supported
- operations (curently just acknowledge). \ No newline at end of file
+ operations (currently just acknowledge).
+ ============== ================================================
diff --git a/Documentation/ABI/stable/sysfs-fs-orangefs b/Documentation/ABI/stable/sysfs-fs-orangefs
new file mode 100644
index 000000000000..affdb114bd33
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-fs-orangefs
@@ -0,0 +1,87 @@
+What: /sys/fs/orangefs/perf_counters/*
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Counters and settings for various caches.
+ Read only.
+
+
+What: /sys/fs/orangefs/perf_counter_reset
+Date: June 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ echo a 0 or a 1 into perf_counter_reset to
+ reset all the counters in
+ /sys/fs/orangefs/perf_counters
+ except ones with PINT_PERF_PRESERVE set.
+
+
+What: /sys/fs/orangefs/perf_time_interval_secs
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Length of perf counter intervals in
+ seconds.
+
+
+What: /sys/fs/orangefs/perf_history_size
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ The perf_counters cache statistics have N, or
+ perf_history_size, samples. The default is
+ one.
+
+ Every perf_time_interval_secs the (first)
+ samples are reset.
+
+ If N is greater than one, the "current" set
+ of samples is reset, and the samples from the
+ other N-1 intervals remain available.
+
+
+What: /sys/fs/orangefs/op_timeout_secs
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Service operation timeout in seconds.
+
+
+What: /sys/fs/orangefs/slot_timeout_secs
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ "Slot" timeout in seconds. A "slot"
+ is an indexed buffer in the shared
+ memory segment used for communication
+ between the kernel module and userspace.
+ Slots are requested and waited for,
+ the wait times out after slot_timeout_secs.
+
+
+What: /sys/fs/orangefs/acache/*
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Attribute cache configurable settings.
+
+
+What: /sys/fs/orangefs/ncache/*
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Name cache configurable settings.
+
+
+What: /sys/fs/orangefs/capcache/*
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Capability cache configurable settings.
+
+
+What: /sys/fs/orangefs/ccache/*
+Date: Jun 2015
+Contact: Mike Marshall <hubcap@omnibond.com>
+Description:
+ Credential cache configurable settings.
diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen
new file mode 100644
index 000000000000..be9ca9981bb1
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-hypervisor-xen
@@ -0,0 +1,135 @@
+What: /sys/hypervisor/compilation/compile_date
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Contains the build time stamp of the Xen hypervisor
+ Might return "<denied>" in case of special security settings
+ in the hypervisor.
+
+What: /sys/hypervisor/compilation/compiled_by
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Contains information who built the Xen hypervisor
+ Might return "<denied>" in case of special security settings
+ in the hypervisor.
+
+What: /sys/hypervisor/compilation/compiler
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Compiler which was used to build the Xen hypervisor
+ Might return "<denied>" in case of special security settings
+ in the hypervisor.
+
+What: /sys/hypervisor/properties/capabilities
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Space separated list of supported guest system types. Each type
+ is in the format: <class>-<major>.<minor>-<arch>
+ With:
+
+ ======== ============================================
+ <class>: "xen" -- x86: paravirtualized, arm: standard
+ "hvm" -- x86 only: fully virtualized
+ <major>: major guest interface version
+ <minor>: minor guest interface version
+ <arch>: architecture, e.g.:
+ "x86_32": 32 bit x86 guest without PAE
+ "x86_32p": 32 bit x86 guest with PAE
+ "x86_64": 64 bit x86 guest
+ "armv7l": 32 bit arm guest
+ "aarch64": 64 bit arm guest
+ ======== ============================================
+
+What: /sys/hypervisor/properties/changeset
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Changeset of the hypervisor (git commit)
+ Might return "<denied>" in case of special security settings
+ in the hypervisor.
+
+What: /sys/hypervisor/properties/features
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Features the Xen hypervisor supports for the guest as defined
+ in include/xen/interface/features.h printed as a hex value.
+
+What: /sys/hypervisor/properties/pagesize
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Default page size of the hypervisor printed as a hex value.
+ Might return "0" in case of special security settings
+ in the hypervisor.
+
+What: /sys/hypervisor/properties/virtual_start
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Virtual address of the hypervisor as a hex value.
+
+What: /sys/hypervisor/type
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Type of hypervisor:
+ "xen": Xen hypervisor
+
+What: /sys/hypervisor/uuid
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ UUID of the guest as known to the Xen hypervisor.
+
+What: /sys/hypervisor/version/extra
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ The Xen version is in the format <major>.<minor><extra>
+ This is the <extra> part of it.
+ Might return "<denied>" in case of special security settings
+ in the hypervisor.
+
+What: /sys/hypervisor/version/major
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ The Xen version is in the format <major>.<minor><extra>
+ This is the <major> part of it.
+
+What: /sys/hypervisor/version/minor
+Date: March 2009
+KernelVersion: 2.6.30
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ The Xen version is in the format <major>.<minor><extra>
+ This is the <minor> part of it.
+
+What: /sys/hypervisor/start_flags/*
+Date: March 2023
+KernelVersion: 6.3.0
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ All bits in Xen's start-flags are represented as
+ boolean files, returning '1' if set, '0' otherwise.
+ This takes the place of the defunct /proc/xen/capabilities,
+ which would contain "control_d" on dom0, and be empty
+ otherwise. This flag is now exposed as "initdomain" in
+ addition to the "privileged" flag; all other possible flags
+ are accessible as "unknownXX".
diff --git a/Documentation/ABI/stable/sysfs-kernel-notes b/Documentation/ABI/stable/sysfs-kernel-notes
new file mode 100644
index 000000000000..2c76ee9e67f7
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-kernel-notes
@@ -0,0 +1,5 @@
+What: /sys/kernel/notes
+Date: July 2009
+Contact: <linux-kernel@vger.kernel.org>
+Description: The /sys/kernel/notes file contains the binary representation
+ of the running vmlinux's .notes section.
diff --git a/Documentation/ABI/stable/sysfs-kernel-time-aux-clocks b/Documentation/ABI/stable/sysfs-kernel-time-aux-clocks
new file mode 100644
index 000000000000..825508f42af6
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-kernel-time-aux-clocks
@@ -0,0 +1,5 @@
+What: /sys/kernel/time/aux_clocks/<ID>/enable
+Date: May 2025
+Contact: Thomas Gleixner <tglx@linutronix.de>
+Description:
+ Controls the enablement of auxiliary clock timekeepers.
diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module
index 6272ae5fb366..41b1f16e8795 100644
--- a/Documentation/ABI/stable/sysfs-module
+++ b/Documentation/ABI/stable/sysfs-module
@@ -1,8 +1,7 @@
-What: /sys/module
-Description:
- The /sys/module tree consists of the following structure:
+The /sys/module tree consists of the following structure:
- /sys/module/MODULENAME
+What: /sys/module/<MODULENAME>
+Description:
The name of the module that is in the kernel. This
module name will always show up if the module is loaded as a
dynamic module. If it is built directly into the kernel, it
@@ -12,7 +11,8 @@ Description:
Note: The conditions of creation in the built-in case are not
by design and may be removed in the future.
- /sys/module/MODULENAME/parameters
+What: /sys/module/<MODULENAME>/parameters
+Description:
This directory contains individual files that are each
individual parameters of the module that are able to be
changed at runtime. See the individual module
@@ -25,10 +25,23 @@ Description:
individual driver documentation for details as to the
stability of the different parameters.
- /sys/module/MODULENAME/refcnt
+What: /sys/module/<MODULENAME>/refcnt
+Description:
If the module is able to be unloaded from the kernel, this file
will contain the current reference count of the module.
Note: If the module is built into the kernel, or if the
CONFIG_MODULE_UNLOAD kernel configuration value is not enabled,
this file will not be present.
+
+What: /sys/module/<MODULENAME>/srcversion
+Date: Jun 2005
+Description:
+ If the module source has MODULE_VERSION, this file will contain
+ the checksum of the source code.
+
+What: /sys/module/<MODULENAME>/version
+Date: Jun 2005
+Description:
+ If the module source has MODULE_VERSION, this file will contain
+ the version of the source code.
diff --git a/Documentation/ABI/stable/sysfs-platform-wmi-bmof b/Documentation/ABI/stable/sysfs-platform-wmi-bmof
new file mode 100644
index 000000000000..2881244e3f09
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-platform-wmi-bmof
@@ -0,0 +1,7 @@
+What: /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof
+Date: Jun 2017
+KernelVersion: 4.13
+Description:
+ Binary MOF metadata used to describe the details of available ACPI WMI interfaces.
+
+ See Documentation/wmi/devices/wmi-bmof.rst for details.
diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 7cdfc28cc2c6..85dbb6a160df 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -1,11 +1,19 @@
+What: vDSO
+Date: July 2011
+KernelVersion: 3.0
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+
On some architectures, when the kernel loads any userspace program it
maps an ELF DSO into that program's address space. This DSO is called
the vDSO and it often contains useful and highly-optimized alternatives
to real syscalls.
-These functions are called just like ordinary C function according to
-your platform's ABI. Call them from a sensible context. (For example,
-if you set CS on x86 to something strange, the vDSO functions are
+These functions are called according to your platform's ABI. On many
+platforms they are called just like ordinary C function. On other platforms
+(ex: powerpc) they are called with the same convention as system calls which
+is different from ordinary C functions. Call them from a sensible context.
+(For example, if you set CS on x86 to something strange, the vDSO functions are
within their rights to crash.) In addition, if you pass a bad
pointer to a vDSO function, you might get SIGSEGV instead of -EFAULT.
@@ -16,12 +24,14 @@ The vDSO uses symbol versioning; whenever you request a symbol from the
vDSO, specify the version you are expecting.
Programs that dynamically link to glibc will use the vDSO automatically.
-Otherwise, you can use the reference parser in Documentation/vDSO/parse_vdso.c.
+Otherwise, you can use the reference parser in
+tools/testing/selftests/vDSO/parse_vdso.c.
Unless otherwise noted, the set of symbols with any given version and the
ABI of those symbols is considered stable. It may vary across architectures,
though.
-(As of this writing, this ABI documentation as been confirmed for x86_64.
+Note:
+ As of this writing, this ABI documentation as been confirmed for x86_64.
The maintainers of the other vDSO-using architectures should confirm
- that it is correct for their architecture.)
+ that it is correct for their architecture.
diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi
new file mode 100644
index 000000000000..c09b640c3cb1
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-acpi
@@ -0,0 +1,52 @@
+What: /config/acpi
+Date: July 2016
+KernelVersion: 4.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ This represents the ACPI subsystem entry point directory. It
+ contains sub-groups corresponding to ACPI configurable options.
+
+What: /config/acpi/table
+Date: July 2016
+KernelVersion: 4.8
+Description:
+
+ This group contains the configuration for user defined ACPI
+ tables. The attributes of a user define table are:
+
+ aml
+ - a binary attribute that the user can use to
+ fill in the ACPI aml definitions. Once the aml
+ data is written to this file and the file is
+ closed the table will be loaded and ACPI devices
+ will be enumerated. To check if the operation is
+ successful the user must check the error code
+ for close(). If the operation is successful,
+ subsequent writes to this attribute will fail.
+
+ The rest of the attributes are read-only and are valid only
+ after the table has been loaded by filling the aml entry:
+
+ signature
+ - ASCII table signature
+
+ length
+ - length of table in bytes, including the header
+
+ revision
+ - ACPI Specification minor version number
+
+ oem_id
+ - ASCII OEM identification
+
+ oem_table_id
+ - ASCII OEM table identification
+
+ oem_revision
+ - OEM revision number
+
+ asl_compiler_id
+ - ASCII ASL compiler vendor ID
+
+ asl_compiler_revision
+ - ASL compiler version
diff --git a/Documentation/ABI/testing/configfs-iio b/Documentation/ABI/testing/configfs-iio
new file mode 100644
index 000000000000..1637fcb50f56
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-iio
@@ -0,0 +1,34 @@
+What: /config/iio
+Date: October 2015
+KernelVersion: 4.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ This represents Industrial IO configuration entry point
+ directory. It contains sub-groups corresponding to IIO
+ objects.
+
+What: /config/iio/triggers
+Date: October 2015
+KernelVersion: 4.4
+Description:
+ Industrial IO software triggers directory.
+
+What: /config/iio/triggers/hrtimers
+Date: October 2015
+KernelVersion: 4.4
+Description:
+ High resolution timers directory. Creating a directory here
+ will result in creating a hrtimer trigger in the IIO subsystem.
+
+What: /config/iio/devices
+Date: April 2016
+KernelVersion: 4.7
+Description:
+ Industrial IO software devices directory.
+
+What: /config/iio/devices/dummy
+Date: April 2016
+KernelVersion: 4.7
+Description:
+ Dummy IIO devices directory. Creating a directory here will result
+ in creating a dummy IIO device in the IIO subsystem.
diff --git a/Documentation/ABI/testing/configfs-most b/Documentation/ABI/testing/configfs-most
new file mode 100644
index 000000000000..0a4b8649aa5a
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-most
@@ -0,0 +1,241 @@
+What: /sys/kernel/config/most_<component>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description: Interface is used to configure and connect device channels
+ to component drivers.
+
+ Attributes are visible only when configfs is mounted. To mount
+ configfs in /sys/kernel/config directory use:
+ # mount -t configfs none /sys/kernel/config/
+
+
+What: /sys/kernel/config/most_cdev/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size
+ configure the buffer size for this channel
+
+ subbuffer_size
+ configure the sub-buffer size for this channel
+ (needed for synchronous and isochronous data)
+
+
+ num_buffers
+ configure number of buffers used for this
+ channel
+
+ datatype
+ configure type of data that will travel over
+ this channel
+
+ direction
+ configure whether this link will be an input
+ or output
+
+ dbr_size
+ configure DBR data buffer size (this is used
+ for MediaLB communication only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communication only)
+
+ device
+ name of the device the link is to be attached to
+
+ channel
+ name of the channel the link is to be attached to
+
+ comp_params
+ pass parameters needed by some components
+
+ create_link
+ write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link
+ write '1' to this attribute to destroy an
+ active link
+
+What: /sys/kernel/config/most_video/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size
+ configure the buffer size for this channel
+
+ subbuffer_size
+ configure the sub-buffer size for this channel
+ (needed for synchronous and isochronous data)
+
+
+ num_buffers
+ configure number of buffers used for this
+ channel
+
+ datatype
+ configure type of data that will travel over
+ this channel
+
+ direction
+ configure whether this link will be an input
+ or output
+
+ dbr_size
+ configure DBR data buffer size (this is used
+ for MediaLB communication only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communication only)
+
+ device
+ name of the device the link is to be attached to
+
+ channel
+ name of the channel the link is to be attached to
+
+ comp_params
+ pass parameters needed by some components
+
+ create_link
+ write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link
+ write '1' to this attribute to destroy an
+ active link
+
+What: /sys/kernel/config/most_net/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size
+ configure the buffer size for this channel
+
+ subbuffer_size
+ configure the sub-buffer size for this channel
+ (needed for synchronous and isochronous data)
+
+
+ num_buffers
+ configure number of buffers used for this
+ channel
+
+ datatype
+ configure type of data that will travel over
+ this channel
+
+ direction
+ configure whether this link will be an input
+ or output
+
+ dbr_size
+ configure DBR data buffer size (this is used
+ for MediaLB communication only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communication only)
+
+ device
+ name of the device the link is to be attached to
+
+ channel
+ name of the channel the link is to be attached to
+
+ comp_params
+ pass parameters needed by some components
+
+ create_link
+ write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link
+ write '1' to this attribute to destroy an
+ active link
+
+What: /sys/kernel/config/most_sound/<card>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ create_card
+ write '1' to this attribute to trigger the
+ registration of the sound card with the ALSA
+ subsystem.
+
+What: /sys/kernel/config/most_sound/<card>/<link>
+Date: March 8, 2019
+KernelVersion: 5.2
+Description:
+ The attributes:
+
+ buffer_size
+ configure the buffer size for this channel
+
+ subbuffer_size
+ configure the sub-buffer size for this channel
+ (needed for synchronous and isochronous data)
+
+
+ num_buffers
+ configure number of buffers used for this
+ channel
+
+ datatype
+ configure type of data that will travel over
+ this channel
+
+ direction
+ configure whether this link will be an input
+ or output
+
+ dbr_size
+ configure DBR data buffer size (this is used
+ for MediaLB communication only)
+
+ packets_per_xact
+ configure the number of packets that will be
+ collected from the network before being
+ transmitted via USB (this is used for USB
+ communication only)
+
+ device
+ name of the device the link is to be attached to
+
+ channel
+ name of the channel the link is to be attached to
+
+ comp_params
+ pass parameters needed by some components
+
+ create_link
+ write '1' to this attribute to trigger the
+ creation of the link. In case of speculative
+ configuration, the creation is post-poned until
+ a physical device is being attached to the bus.
+
+ destroy_link
+ write '1' to this attribute to destroy an
+ active link
diff --git a/Documentation/ABI/testing/configfs-rdma_cm b/Documentation/ABI/testing/configfs-rdma_cm
new file mode 100644
index 000000000000..74f9506f42e7
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-rdma_cm
@@ -0,0 +1,30 @@
+What: /config/rdma_cm
+Date: November 29, 2015
+KernelVersion: 4.4.0
+Description: Interface is used to configure RDMA-cable HCAs in respect to
+ RDMA-CM attributes.
+
+ Attributes are visible only when configfs is mounted. To mount
+ configfs in /config directory use:
+ # mount -t configfs none /config/
+
+ In order to set parameters related to a specific HCA, a directory
+ for this HCA has to be created:
+ mkdir -p /config/rdma_cm/<hca>
+
+
+What: /config/rdma_cm/<hca>/ports/<port-num>/default_roce_mode
+Date: November 29, 2015
+KernelVersion: 4.4.0
+Description: RDMA-CM based connections from HCA <hca> at port <port-num>
+ will be initiated with this RoCE type as default.
+ The possible RoCE types are either "IB/RoCE v1" or "RoCE v2".
+ This parameter has RW access.
+
+What: /config/rdma_cm/<hca>/ports/<port-num>/default_roce_tos
+Date: February 7, 2017
+KernelVersion: 4.11.0
+Description: RDMA-CM QPs from HCA <hca> at port <port-num>
+ will be created with this TOS as default.
+ This can be overridden by using the rdma_set_option API.
+ The possible RoCE TOS values are 0-255.
diff --git a/Documentation/ABI/testing/configfs-spear-pcie-gadget b/Documentation/ABI/testing/configfs-spear-pcie-gadget
index 875988146a63..cf877bd341df 100644
--- a/Documentation/ABI/testing/configfs-spear-pcie-gadget
+++ b/Documentation/ABI/testing/configfs-spear-pcie-gadget
@@ -1,7 +1,7 @@
What: /config/pcie-gadget
Date: Feb 2011
KernelVersion: 2.6.37
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Interface is used to configure selected dual mode PCIe controller
@@ -10,22 +10,24 @@ Description:
This interfaces can be used to show spear's PCIe device capability.
Nodes are only visible when configfs is mounted. To mount configfs
- in /config directory use:
- # mount -t configfs none /config/
+ in /config directory use::
- For nth PCIe Device Controller
- /config/pcie-gadget.n/
- link ... used to enable ltssm and read its status.
- int_type ...used to configure and read type of supported
- interrupt
- no_of_msi ... used to configure number of MSI vector needed and
+ # mount -t configfs none /config/
+
+ For nth PCIe Device Controller /config/pcie-gadget.n/:
+
+ =============== ======================================================
+ link used to enable ltssm and read its status.
+ int_type used to configure and read type of supported interrupt
+ no_of_msi used to configure number of MSI vector needed and
to read no of MSI granted.
- inta ... write 1 to assert INTA and 0 to de-assert.
- send_msi ... write MSI vector to be sent.
- vendor_id ... used to write and read vendor id (hex)
- device_id ... used to write and read device id (hex)
- bar0_size ... used to write and read bar0_size
- bar0_address ... used to write and read bar0 mapped area in hex.
- bar0_rw_offset ... used to write and read offset of bar0 where
- bar0_data will be written or read.
- bar0_data ... used to write and read data at bar0_rw_offset.
+ inta write 1 to assert INTA and 0 to de-assert.
+ send_msi write MSI vector to be sent.
+ vendor_id used to write and read vendor id (hex)
+ device_id used to write and read device id (hex)
+ bar0_size used to write and read bar0_size
+ bar0_address used to write and read bar0 mapped area in hex.
+ bar0_rw_offset used to write and read offset of bar0 where bar0_data
+ will be written or read.
+ bar0_data used to write and read data at bar0_rw_offset.
+ =============== ======================================================
diff --git a/Documentation/ABI/testing/configfs-stp-policy b/Documentation/ABI/testing/configfs-stp-policy
new file mode 100644
index 000000000000..421ce6825c66
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-stp-policy
@@ -0,0 +1,48 @@
+What: /config/stp-policy
+Date: June 2015
+KernelVersion: 4.3
+Description:
+ This group contains policies mandating Master/Channel allocation
+ for software sources wishing to send trace data over an STM
+ device.
+
+What: /config/stp-policy/<device>.<policy>
+Date: June 2015
+KernelVersion: 4.3
+Description:
+ This group is the root of a policy; its name is a concatenation
+ of an stm device name to which this policy applies and an
+ arbitrary string. If <device> part doesn't match an existing
+ stm device, mkdir will fail with ENODEV; if that device already
+ has a policy assigned to it, mkdir will fail with EBUSY.
+
+What: /config/stp-policy/<device>.<policy>/device
+Date: June 2015
+KernelVersion: 4.3
+Description:
+ STM device to which this policy applies, read only. Same as the
+ <device> component of its parent directory.
+
+What: /config/stp-policy/<device>.<policy>/<node>
+Date: June 2015
+KernelVersion: 4.3
+Description:
+ Policy node is a string identifier that software clients will
+ use to request a master/channel to be allocated and assigned to
+ them.
+
+What: /config/stp-policy/<device>.<policy>/<node>/masters
+Date: June 2015
+KernelVersion: 4.3
+Description:
+ Range of masters from which to allocate for users of this node.
+ Write two numbers: the first master and the last master number.
+
+What: /config/stp-policy/<device>.<policy>/<node>/channels
+Date: June 2015
+KernelVersion: 4.3
+Description:
+ Range of channels from which to allocate for users of this node.
+ Write two numbers: the first channel and the last channel
+ number.
+
diff --git a/Documentation/ABI/testing/configfs-stp-policy-p_sys-t b/Documentation/ABI/testing/configfs-stp-policy-p_sys-t
new file mode 100644
index 000000000000..b290d1c00dcf
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-stp-policy-p_sys-t
@@ -0,0 +1,41 @@
+What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/uuid
+Date: June 2018
+KernelVersion: 4.19
+Description:
+ UUID source identifier string, RW.
+ Default value is randomly generated at the mkdir <node> time.
+ Data coming from trace sources that use this <node> will be
+ tagged with this UUID in the MIPI SyS-T packet stream, to
+ allow the decoder to discern between different sources
+ within the same master/channel range, and identify the
+ higher level decoders that may be needed for each source.
+
+What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/do_len
+Date: June 2018
+KernelVersion: 4.19
+Description:
+ Include payload length in the MIPI SyS-T header, boolean.
+ If enabled, the SyS-T protocol encoder will include payload
+ length in each packet's metadata. This is normally redundant
+ if the underlying transport protocol supports marking message
+ boundaries (which STP does), so this is off by default.
+
+What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/ts_interval
+Date: June 2018
+KernelVersion: 4.19
+Description:
+ Time interval in milliseconds. Include a timestamp in the
+ MIPI SyS-T packet metadata, if this many milliseconds have
+ passed since the previous packet from this source. Zero is
+ the default and stands for "never send the timestamp".
+
+What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/clocksync_interval
+Date: June 2018
+KernelVersion: 4.19
+Description:
+ Time interval in milliseconds. Send a CLOCKSYNC packet if
+ this many milliseconds have passed since the previous
+ CLOCKSYNC packet from this source. Zero is the default and
+ stands for "never send the CLOCKSYNC". It makes sense to
+ use this option with sources that generate constant and/or
+ periodic data, like stm_heartbeat.
diff --git a/Documentation/ABI/testing/configfs-tsm-report b/Documentation/ABI/testing/configfs-tsm-report
new file mode 100644
index 000000000000..534408bc1408
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-tsm-report
@@ -0,0 +1,145 @@
+What: /sys/kernel/config/tsm/report/$name/inblob
+Date: September, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (WO) Up to 64 bytes of user specified binary data. For replay
+ protection this should include a nonce, but the kernel does not
+ place any restrictions on the content.
+
+What: /sys/kernel/config/tsm/report/$name/outblob
+Date: September, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) Binary attestation report generated from @inblob and other
+ options The format of the report is implementation specific
+ where the implementation is conveyed via the @provider
+ attribute.
+
+What: /sys/kernel/config/tsm/report/$name/auxblob
+Date: October, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) Optional supplemental data that a TSM may emit, visibility
+ of this attribute depends on TSM, and may be empty if no
+ auxiliary data is available.
+
+ When @provider is "sev_guest" this file contains the
+ "cert_table" from SEV-ES Guest-Hypervisor Communication Block
+ Standardization v2.03 Section 4.1.8.1 MSG_REPORT_REQ.
+ https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56421.pdf
+
+What: /sys/kernel/config/tsm/report/$name/manifestblob
+Date: January, 2024
+KernelVersion: v6.10
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) Optional supplemental data that a TSM may emit, visibility
+ of this attribute depends on TSM, and may be empty if no
+ manifest data is available.
+
+ See 'service_provider' for information on the format of the
+ manifest blob.
+
+What: /sys/kernel/config/tsm/report/$name/provider
+Date: September, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) A name for the format-specification of @outblob like
+ "sev_guest" [1] or "tdx_guest" [2] in the near term, or a
+ common standard format in the future.
+
+ [1]: SEV Secure Nested Paging Firmware ABI Specification
+ Revision 1.55 Table 22
+ https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf
+
+ [2]: Intel® Trust Domain Extensions Data Center Attestation
+ Primitives : Quote Generation Library and Quote Verification
+ Library Revision 0.8 Appendix 4,5
+ https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf
+
+What: /sys/kernel/config/tsm/report/$name/generation
+Date: September, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) The value in this attribute increments each time @inblob or
+ any option is written. Userspace can detect conflicts by
+ checking generation before writing to any attribute and making
+ sure the number of writes matches expectations after reading
+ @outblob, or it can prevent conflicts by creating a report
+ instance per requesting context.
+
+What: /sys/kernel/config/tsm/report/$name/privlevel
+Date: September, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (WO) Attribute is visible if a TSM implementation provider
+ supports the concept of attestation reports for TVMs running at
+ different privilege levels, like SEV-SNP "VMPL", specify the
+ privilege level via this attribute. The minimum acceptable
+ value is conveyed via @privlevel_floor and the maximum
+ acceptable value is TSM_PRIVLEVEL_MAX (3).
+
+What: /sys/kernel/config/tsm/report/$name/privlevel_floor
+Date: September, 2023
+KernelVersion: v6.7
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) Indicates the minimum permissible value that can be written
+ to @privlevel.
+
+What: /sys/kernel/config/tsm/report/$name/service_provider
+Date: January, 2024
+KernelVersion: v6.10
+Contact: linux-coco@lists.linux.dev
+Description:
+ (WO) Attribute is visible if a TSM implementation provider
+ supports the concept of attestation reports from a service
+ provider for TVMs, like SEV-SNP running under an SVSM.
+ Specifying the service provider via this attribute will create
+ an attestation report as specified by the service provider.
+ The only currently supported service provider is "svsm".
+
+ For the "svsm" service provider, see the Secure VM Service Module
+ for SEV-SNP Guests v1.00 Section 7. For the doc, search for
+ "site:amd.com "Secure VM Service Module for SEV-SNP
+ Guests", docID: 58019"
+
+What: /sys/kernel/config/tsm/report/$name/service_guid
+Date: January, 2024
+KernelVersion: v6.10
+Contact: linux-coco@lists.linux.dev
+Description:
+ (WO) Attribute is visible if a TSM implementation provider
+ supports the concept of attestation reports from a service
+ provider for TVMs, like SEV-SNP running under an SVSM.
+ Specifying an empty/null GUID (00000000-0000-0000-0000-000000)
+ requests all active services within the service provider be
+ part of the attestation report. Specifying a GUID request
+ an attestation report of just the specified service using the
+ manifest form specified by the service_manifest_version
+ attribute.
+
+ See 'service_provider' for information on the format of the
+ service guid.
+
+What: /sys/kernel/config/tsm/report/$name/service_manifest_version
+Date: January, 2024
+KernelVersion: v6.10
+Contact: linux-coco@lists.linux.dev
+Description:
+ (WO) Attribute is visible if a TSM implementation provider
+ supports the concept of attestation reports from a service
+ provider for TVMs, like SEV-SNP running under an SVSM.
+ Indicates the service manifest version requested for the
+ attestation report (default 0). If this field is not set by
+ the user, the default manifest version of the service (the
+ service's initial/first manifest version) is returned.
+
+ See 'service_provider' for information on the format of the
+ service manifest version.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget
index 95a36589a66b..a8bb896def54 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget
+++ b/Documentation/ABI/testing/configfs-usb-gadget
@@ -12,18 +12,24 @@ Description:
The attributes of a gadget:
- UDC - bind a gadget to UDC/unbind a gadget;
- write UDC's name found in /sys/class/udc/*
- to bind a gadget, empty string "" to unbind.
-
- bDeviceClass - USB device class code
- bDeviceSubClass - USB device subclass code
- bDeviceProtocol - USB device protocol code
- bMaxPacketSize0 - maximum endpoint 0 packet size
- bcdDevice - bcd device release number
- bcdUSB - bcd USB specification version number
- idProduct - product ID
- idVendor - vendor ID
+ ================ ============================================
+ UDC bind a gadget to UDC/unbind a gadget;
+ write UDC's name found in /sys/class/udc/*
+ to bind a gadget, empty string "" to unbind.
+
+ max_speed maximum speed the driver supports. Valid
+ names are super-speed-plus, super-speed,
+ high-speed, full-speed, and low-speed.
+
+ bDeviceClass USB device class code
+ bDeviceSubClass USB device subclass code
+ bDeviceProtocol USB device protocol code
+ bMaxPacketSize0 maximum endpoint 0 packet size
+ bcdDevice bcd device release number
+ bcdUSB bcd USB specification version number
+ idProduct product ID
+ idVendor vendor ID
+ ================ ============================================
What: /config/usb-gadget/gadget/configs
Date: Jun 2013
@@ -37,8 +43,10 @@ KernelVersion: 3.11
Description:
The attributes of a configuration:
- bmAttributes - configuration characteristics
- MaxPower - maximum power consumption from the bus
+ ================ ======================================
+ bmAttributes configuration characteristics
+ MaxPower maximum power consumption from the bus
+ ================ ======================================
What: /config/usb-gadget/gadget/configs/config/strings
Date: Jun 2013
@@ -53,7 +61,9 @@ KernelVersion: 3.11
Description:
The attributes:
- configuration - configuration description
+ ================ =========================
+ configuration configuration description
+ ================ =========================
What: /config/usb-gadget/gadget/functions
@@ -72,8 +82,10 @@ Description:
The attributes:
- compatible_id - 8-byte string for "Compatible ID"
- sub_compatible_id - 8-byte string for "Sub Compatible ID"
+ ================= =====================================
+ compatible_id 8-byte string for "Compatible ID"
+ sub_compatible_id 8-byte string for "Sub Compatible ID"
+ ================= =====================================
What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property>
Date: May 2014
@@ -85,16 +97,19 @@ Description:
The attributes:
- type - value 1..7 for interpreting the data
- 1: unicode string
- 2: unicode string with environment variable
- 3: binary
- 4: little-endian 32-bit
- 5: big-endian 32-bit
- 6: unicode string with a symbolic link
- 7: multiple unicode strings
- data - blob of data to be interpreted depending on
+ ===== ===============================================
+ type value 1..7 for interpreting the data
+
+ - 1: unicode string
+ - 2: unicode string with environment variable
+ - 3: binary
+ - 4: little-endian 32-bit
+ - 5: big-endian 32-bit
+ - 6: unicode string with a symbolic link
+ - 7: multiple unicode strings
+ data blob of data to be interpreted depending on
type
+ ===== ===============================================
What: /config/usb-gadget/gadget/strings
Date: Jun 2013
@@ -109,9 +124,11 @@ KernelVersion: 3.11
Description:
The attributes:
- serialnumber - gadget's serial number (string)
- product - gadget's product description
- manufacturer - gadget's manufacturer description
+ ============ =================================
+ serialnumber gadget's serial number (string)
+ product gadget's product description
+ manufacturer gadget's manufacturer description
+ ============ =================================
What: /config/usb-gadget/gadget/os_desc
Date: May 2014
@@ -119,8 +136,23 @@ KernelVersion: 3.16
Description:
This group contains "OS String" extension handling attributes.
- use - flag turning "OS Desctiptors" support on/off
- b_vendor_code - one-byte value used for custom per-device and
+ ============= ===============================================
+ use flag turning "OS Descriptors" support on/off
+ b_vendor_code one-byte value used for custom per-device and
per-interface requests
- qw_sign - an identifier to be reported as "OS String"
+ qw_sign an identifier to be reported as "OS String"
proper
+ ============= ===============================================
+
+What: /config/usb-gadget/gadget/webusb
+Date: Dec 2022
+KernelVersion: 6.3
+Description:
+ This group contains "WebUSB" extension handling attributes.
+
+ ============= ===============================================
+ use flag turning "WebUSB" support on/off
+ bcdVersion bcd WebUSB specification version number
+ bVendorCode one-byte value used for custom per-device
+ landingPage UTF-8 encoded URL of the device's landing page
+ ============= ===============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-acm b/Documentation/ABI/testing/configfs-usb-gadget-acm
index d21092d75a05..25e68be9eb66 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-acm
+++ b/Documentation/ABI/testing/configfs-usb-gadget-acm
@@ -6,3 +6,10 @@ Description:
This item contains just one readonly attribute: port_num.
It contains the port number of the /dev/ttyGS<n> device
associated with acm function's instance "name".
+
+What: /config/usb-gadget/gadget/functions/acm.name/protocol
+Date: Aug 2024
+KernelVersion: 6.13
+Description:
+ Reported bInterfaceProtocol for the ACM device. For legacy
+ reasons, this defaults to 1 (USB_CDC_ACM_PROTO_AT_V25TER).
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm
index 0addf7704b4c..732101ca9d0b 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-ecm
+++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm
@@ -4,13 +4,17 @@ KernelVersion: 3.11
Description:
The attributes:
- ifname - network device interface name associated with
+ ifname
+ - network device interface name associated with
this function instance
- qmult - queue length multiplier for high and
+ qmult
+ - queue length multiplier for high and
super speed
- host_addr - MAC address of host's end of this
+ host_addr
+ - MAC address of host's end of this
Ethernet over USB link
- dev_addr - MAC address of device's end of this
+ dev_addr
+ - MAC address of device's end of this
Ethernet over USB link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem
index a4c57158fcde..178c3d5fb647 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-eem
+++ b/Documentation/ABI/testing/configfs-usb-gadget-eem
@@ -4,11 +4,13 @@ KernelVersion: 3.11
Description:
The attributes:
- ifname - network device interface name associated with
+ ========== =============================================
+ ifname network device interface name associated with
this function instance
- qmult - queue length multiplier for high and
+ qmult queue length multiplier for high and
super speed
- host_addr - MAC address of host's end of this
+ host_addr MAC address of host's end of this
Ethernet over USB link
- dev_addr - MAC address of device's end of this
+ dev_addr MAC address of device's end of this
Ethernet over USB link
+ ========== =============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ffs b/Documentation/ABI/testing/configfs-usb-gadget-ffs
index e39b27653c65..bf8936ff6d38 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-ffs
+++ b/Documentation/ABI/testing/configfs-usb-gadget-ffs
@@ -4,6 +4,14 @@ KernelVersion: 3.13
Description: The purpose of this directory is to create and remove it.
A corresponding USB function instance is created/removed.
- There are no attributes here.
- All parameters are set through FunctionFS.
+ All attributes are read only:
+
+ ============= ============================================
+ ready 1 if the function is ready to be used, E.G.
+ if userspace has written descriptors and
+ strings to ep0, so the gadget can be
+ enabled - 0 otherwise.
+ ============= ============================================
+
+ All other parameters are set through FunctionFS.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid
index f12e00e6baa3..748705c4cb58 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-hid
+++ b/Documentation/ABI/testing/configfs-usb-gadget-hid
@@ -4,8 +4,10 @@ KernelVersion: 3.19
Description:
The attributes:
- protocol - HID protocol to use
- report_desc - blob corresponding to HID report descriptors
+ ============= ============================================
+ protocol HID protocol to use
+ report_desc blob corresponding to HID report descriptors
except the data passed through /dev/hidg<N>
- report_length - HID report length
- subclass - HID device subclass to use
+ report_length HID report length
+ subclass HID device subclass to use
+ ============= ============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-loopback b/Documentation/ABI/testing/configfs-usb-gadget-loopback
index 9aae5bfb9908..e6c6ba5ac7ff 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-loopback
+++ b/Documentation/ABI/testing/configfs-usb-gadget-loopback
@@ -4,5 +4,7 @@ KernelVersion: 3.13
Description:
The attributes:
- qlen - depth of loopback queue
- bulk_buflen - buffer length
+ ======= =======================
+ qlen depth of loopback queue
+ buflen buffer length
+ ======= =======================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
index 9931fb0d63ba..fc0328069267 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
+++ b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
@@ -4,12 +4,14 @@ KernelVersion: 3.13
Description:
The attributes:
- stall - Set to permit function to halt bulk endpoints.
+ =========== ==============================================
+ stall Set to permit function to halt bulk endpoints.
Disabled on some USB devices known not to work
correctly. You should set it to true.
- num_buffers - Number of pipeline buffers. Valid numbers
+ num_buffers Number of pipeline buffers. Valid numbers
are 2..4. Available only if
CONFIG_USB_GADGET_DEBUG_FILES is set.
+ =========== ==============================================
What: /config/usb-gadget/gadget/functions/mass_storage.name/lun.name
Date: Oct 2013
@@ -17,15 +19,23 @@ KernelVersion: 3.13
Description:
The attributes:
- file - The path to the backing file for the LUN.
+ ============ ==============================================
+ file The path to the backing file for the LUN.
Required if LUN is not marked as removable.
- ro - Flag specifying access to the LUN shall be
+ ro Flag specifying access to the LUN shall be
read-only. This is implied if CD-ROM emulation
is enabled as well as when it was impossible
to open "filename" in R/W mode.
- removable - Flag specifying that LUN shall be indicated as
+ removable Flag specifying that LUN shall be indicated as
being removable.
- cdrom - Flag specifying that LUN shall be reported as
+ cdrom Flag specifying that LUN shall be reported as
being a CD-ROM.
- nofua - Flag specifying that FUA flag
+ nofua Flag specifying that FUA flag
in SCSI WRITE(10,12)
+ forced_eject This write-only file is useful only when
+ the function is active. It causes the backing
+ file to be forcibly detached from the LUN,
+ regardless of whether the host has allowed it.
+ Any non-zero number of bytes written will
+ result in ejection.
+ ============ ==============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi b/Documentation/ABI/testing/configfs-usb-gadget-midi
index 6b341df7249c..07389cddd51a 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-midi
+++ b/Documentation/ABI/testing/configfs-usb-gadget-midi
@@ -4,9 +4,11 @@ KernelVersion: 3.19
Description:
The attributes:
- index - index value for the USB MIDI adapter
- id - ID string for the USB MIDI adapter
- buflen - MIDI buffer length
- qlen - USB read request queue length
- in_ports - number of MIDI input ports
- out_ports - number of MIDI output ports
+ ========== ====================================
+ index index value for the USB MIDI adapter
+ id ID string for the USB MIDI adapter
+ buflen MIDI buffer length
+ qlen USB read request queue length
+ in_ports number of MIDI input ports
+ out_ports number of MIDI output ports
+ ========== ====================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi2 b/Documentation/ABI/testing/configfs-usb-gadget-midi2
new file mode 100644
index 000000000000..d76a52e2ca7f
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-midi2
@@ -0,0 +1,54 @@
+What: /config/usb-gadget/gadget/functions/midi2.name
+Date: Jul 2023
+KernelVersion: 6.6
+Description:
+ The attributes:
+
+ ============ ===============================================
+ process_ump Flag to process UMP Stream messages (0 or 1)
+ static_block Flag for static blocks (0 or 1)
+ iface_name MIDI interface name string
+ ============ ===============================================
+
+What: /config/usb-gadget/gadget/functions/midi2.name/ep.number
+Date: Jul 2023
+KernelVersion: 6.6
+Description:
+ This group contains a UMP Endpoint configuration.
+ A new Endpoint starts from 0, and can be up to 3.
+
+ The attributes:
+
+ ============= ===============================================
+ protocol_caps MIDI protocol capabilities (1, 2 or 3 for both)
+ protocol Default MIDI protocol (1 or 2)
+ ep_name UMP Endpoint name string
+ product_id Product ID string
+ manufacturer Manufacture ID (24 bit)
+ family Device family ID (16 bit)
+ model Device model ID (16 bit)
+ sw_revision Software Revision (32 bit)
+ ============= ===============================================
+
+What: /config/usb-gadget/gadget/functions/midi2.name/ep.number/block.number
+Date: Jul 2023
+KernelVersion: 6.6
+Description:
+ This group contains a UMP Function Block configuration.
+ A new block starts from 0, and can be up to 31.
+
+ The attributes:
+
+ ================= ==============================================
+ name Function Block name string
+ direction 1: input, 2: output, 3: bidirectional
+ first_group The first UMP Group number (0-15)
+ num_groups The number of groups in this FB (1-16)
+ midi1_first_group The first UMP Group number for MIDI 1.0 (0-15)
+ midi1_num_groups The number of groups for MIDI 1.0 (0-16)
+ ui_hint 0: unknown, 1: receiver, 2: sender, 3: both
+ midi_ci_version Supported MIDI-CI version number (8 bit)
+ is_midi1 Legacy MIDI 1.0 device (0, 1 or 2)
+ sysex8_streams Max number of SysEx8 streams (8 bit)
+ active Active FB flag (0 or 1)
+ ================= ==============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-printer b/Documentation/ABI/testing/configfs-usb-gadget-printer
index 6b0714e3c605..7aa731bac2da 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-printer
+++ b/Documentation/ABI/testing/configfs-usb-gadget-printer
@@ -4,6 +4,8 @@ KernelVersion: 4.1
Description:
The attributes:
- pnp_string - Data to be passed to the host in pnp string
- q_len - Number of requests per endpoint
+ ========== ===========================================
+ pnp_string Data to be passed to the host in pnp string
+ q_len Number of requests per endpoint
+ ========== ===========================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis
index e32879b84b4d..9416eda7fe93 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-rndis
+++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis
@@ -4,11 +4,16 @@ KernelVersion: 3.11
Description:
The attributes:
- ifname - network device interface name associated with
+ ========= =============================================
+ ifname network device interface name associated with
this function instance
- qmult - queue length multiplier for high and
+ qmult queue length multiplier for high and
super speed
- host_addr - MAC address of host's end of this
+ host_addr MAC address of host's end of this
Ethernet over USB link
- dev_addr - MAC address of device's end of this
+ dev_addr MAC address of device's end of this
Ethernet over USB link
+ class USB interface class, default is 02 (hex)
+ subclass USB interface subclass, default is 06 (hex)
+ protocol USB interface protocol, default is 00 (hex)
+ ========= =============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
index 29477c319f61..1f3d31b607b7 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
+++ b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
@@ -4,9 +4,13 @@ KernelVersion: 3.13
Description:
The attributes:
- pattern - 0 (all zeros), 1 (mod63), 2 (none)
- isoc_interval - 1..16
- isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss)
- isoc_mult - 0..2 (hs/ss only)
- isoc_maxburst - 0..15 (ss only)
- qlen - buffer length
+ ============== ==================================
+ pattern 0 (all zeros), 1 (mod63), 2 (none)
+ isoc_interval 1..16
+ isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss)
+ isoc_mult 0..2 (hs/ss only)
+ isoc_maxburst 0..15 (ss only)
+ buflen buffer length
+ bulk_qlen depth of queue for bulk
+ iso_qlen depth of queue for iso
+ ============== ==================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset
index 9373e2c51ea4..0061b864351f 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-subset
+++ b/Documentation/ABI/testing/configfs-usb-gadget-subset
@@ -4,11 +4,13 @@ KernelVersion: 3.11
Description:
The attributes:
- ifname - network device interface name associated with
+ ========== =============================================
+ ifname network device interface name associated with
this function instance
- qmult - queue length multiplier for high and
+ qmult queue length multiplier for high and
super speed
- host_addr - MAC address of host's end of this
+ host_addr MAC address of host's end of this
Ethernet over USB link
- dev_addr - MAC address of device's end of this
+ dev_addr MAC address of device's end of this
Ethernet over USB link
+ ========== =============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-tcm b/Documentation/ABI/testing/configfs-usb-gadget-tcm
new file mode 100644
index 000000000000..a29ed2dd6173
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-tcm
@@ -0,0 +1,6 @@
+What: /config/usb-gadget/gadget/functions/tcm.name
+Date: Dec 2015
+KernelVersion: 4.5
+Description:
+ There are no attributes because all the configuration
+ is performed in the "target" subsystem of configfs.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1
index 8ba9a123316e..64188a85592b 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uac1
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1
@@ -1,12 +1,41 @@
What: /config/usb-gadget/gadget/functions/uac1.name
-Date: Sep 2014
-KernelVersion: 3.18
+Date: June 2017
+KernelVersion: 4.14
Description:
The attributes:
- audio_buf_size - audio buffer size
- fn_cap - capture pcm device file name
- fn_cntl - control device file name
- fn_play - playback pcm device file name
- req_buf_size - ISO OUT endpoint request buffer size
- req_count - ISO OUT endpoint request count
+ ===================== =======================================
+ c_chmask capture channel mask
+ c_srate list of capture sampling rates (comma-separated)
+ c_ssize capture sample size (bytes)
+ c_mute_present capture mute control enable
+ c_volume_present capture volume control enable
+ c_volume_min capture volume control min value
+ (in 1/256 dB)
+ c_volume_max capture volume control max value
+ (in 1/256 dB)
+ c_volume_res capture volume control resolution
+ (in 1/256 dB)
+ p_chmask playback channel mask
+ p_srate list of playback sampling rates (comma-separated)
+ p_ssize playback sample size (bytes)
+ p_mute_present playback mute control enable
+ p_volume_present playback volume control enable
+ p_volume_min playback volume control min value
+ (in 1/256 dB)
+ p_volume_max playback volume control max value
+ (in 1/256 dB)
+ p_volume_res playback volume control resolution
+ (in 1/256 dB)
+ req_number the number of pre-allocated requests
+ for both capture and playback
+ function_name name of the interface
+ p_it_name playback input terminal name
+ p_it_ch_name playback channels name
+ p_ot_name playback output terminal name
+ p_fu_vol_name playback mute/volume functional unit name
+ c_it_name capture input terminal name
+ c_it_ch_name capture channels name
+ c_ot_name capture output terminal name
+ c_fu_vol_name capture mute/volume functional unit name
+ ===================== =======================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy b/Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy
new file mode 100644
index 000000000000..b2eaefd9bc49
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy
@@ -0,0 +1,12 @@
+What: /config/usb-gadget/gadget/functions/uac1_legacy.name
+Date: Sep 2014
+KernelVersion: 3.18
+Description:
+ The attributes:
+
+ audio_buf_size - audio buffer size
+ fn_cap - capture pcm device file name
+ fn_cntl - control device file name
+ fn_play - playback pcm device file name
+ req_buf_size - ISO OUT endpoint request buffer size
+ req_count - ISO OUT endpoint request count
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2
index 2bfdd4efa9bd..133e995c3e92 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uac2
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2
@@ -4,9 +4,48 @@ KernelVersion: 3.18
Description:
The attributes:
- c_chmask - capture channel mask
- c_srate - capture sampling rate
- c_ssize - capture sample size (bytes)
- p_chmask - playback channel mask
- p_srate - playback sampling rate
- p_ssize - playback sample size (bytes)
+ ===================== =======================================
+ c_chmask capture channel mask
+ c_srate list of capture sampling rates (comma-separated)
+ c_ssize capture sample size (bytes)
+ c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto)
+ c_sync capture synchronization type
+ (async/adaptive)
+ c_mute_present capture mute control enable
+ c_volume_present capture volume control enable
+ c_volume_min capture volume control min value
+ (in 1/256 dB)
+ c_volume_max capture volume control max value
+ (in 1/256 dB)
+ c_volume_res capture volume control resolution
+ (in 1/256 dB)
+ fb_max maximum extra bandwidth in async mode
+ p_chmask playback channel mask
+ p_srate list of playback sampling rates (comma-separated)
+ p_ssize playback sample size (bytes)
+ p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto)
+ p_mute_present playback mute control enable
+ p_volume_present playback volume control enable
+ p_volume_min playback volume control min value
+ (in 1/256 dB)
+ p_volume_max playback volume control max value
+ (in 1/256 dB)
+ p_volume_res playback volume control resolution
+ (in 1/256 dB)
+ req_number the number of pre-allocated requests
+ for both capture and playback
+ function_name name of the interface
+ if_ctrl_name topology control name
+ clksrc_in_name input clock name
+ clksrc_out_name output clock name
+ p_it_name playback input terminal name
+ p_it_ch_name playback input first channel name
+ p_ot_name playback output terminal name
+ p_fu_vol_name playback mute/volume function unit name
+ c_it_name capture input terminal name
+ c_it_ch_name capture input first channel name
+ c_ot_name capture output terminal name
+ c_fu_vol_name capture mute/volume functional unit name
+ c_terminal_type code of the capture terminal type
+ p_terminal_type code of the playback terminal type
+ ===================== =======================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc
index 2f4a0051b32d..b6720768d63d 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uvc
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc
@@ -1,265 +1,438 @@
What: /config/usb-gadget/gadget/functions/uvc.name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: UVC function directory
- streaming_maxburst - 0..15 (ss only)
- streaming_maxpacket - 1..1023 (fs), 1..3072 (hs/ss)
- streaming_interval - 1..16
+ =================== =============================
+ streaming_maxburst 0..15 (ss only)
+ streaming_maxpacket 1..1023 (fs), 1..3072 (hs/ss)
+ streaming_interval 1..16
+ function_name string [32]
+ =================== =============================
What: /config/usb-gadget/gadget/functions/uvc.name/control
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Control descriptors
+ All attributes read only except enable_interrupt_ep:
+
+ =================== =============================
+ bInterfaceNumber USB interface number for this
+ streaming interface
+ enable_interrupt_ep flag to enable the interrupt
+ endpoint for the VC interface
+ =================== =============================
+
What: /config/usb-gadget/gadget/functions/uvc.name/control/class
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/class/ss
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Super speed control class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/class/fs
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Full speed control class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Terminal descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Output terminal descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output/default
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Default output terminal descriptors
- All attributes read only:
- iTerminal - index of string descriptor
- bSourceID - id of the terminal to which this terminal
+ All attributes read only except bSourceID:
+
+ ============== =============================================
+ iTerminal index of string descriptor
+ bSourceID id of the terminal to which this terminal
is connected
- bAssocTerminal - id of the input terminal to which this output
+ bAssocTerminal id of the input terminal to which this output
terminal is associated
- wTerminalType - terminal type
- bTerminalID - a non-zero id of this terminal
+ wTerminalType terminal type
+ bTerminalID a non-zero id of this terminal
+ ============== =============================================
What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Camera terminal descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera/default
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Default camera terminal descriptors
- All attributes read only:
- bmControls - bitmap specifying which controls are
- supported for the video stream
- wOcularFocalLength - the value of Locular
- wObjectiveFocalLengthMax- the value of Lmin
- wObjectiveFocalLengthMin- the value of Lmax
- iTerminal - index of string descriptor
- bAssocTerminal - id of the output terminal to which
- this terminal is connected
- wTerminalType - terminal type
- bTerminalID - a non-zero id of this terminal
+ All attributes read only except bmControls, which is read/write:
+
+ ======================== ====================================
+ bmControls bitmap specifying which controls are
+ supported for the video stream
+ wOcularFocalLength the value of Locular
+ wObjectiveFocalLengthMax the value of Lmin
+ wObjectiveFocalLengthMin the value of Lmax
+ iTerminal index of string descriptor
+ bAssocTerminal id of the output terminal to which
+ this terminal is connected
+ wTerminalType terminal type
+ bTerminalID a non-zero id of this terminal
+ ======================== ====================================
What: /config/usb-gadget/gadget/functions/uvc.name/control/processing
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Processing unit descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/processing/default
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Default processing unit descriptors
- All attributes read only:
- iProcessing - index of string descriptor
- bmControls - bitmap specifying which controls are
+ All attributes read only except bmControls, which is read/write:
+
+ =============== ========================================
+ iProcessing index of string descriptor
+ bmControls bitmap specifying which controls are
supported for the video stream
- wMaxMultiplier - maximum digital magnification x100
- bSourceID - id of the terminal to which this unit is
+ wMaxMultiplier maximum digital magnification x100
+ bSourceID id of the terminal to which this unit is
connected
- bUnitID - a non-zero id of this unit
+ bUnitID a non-zero id of this unit
+ =============== ========================================
+
+What: /config/usb-gadget/gadget/functions/uvc.name/control/extensions
+Date: Nov 2022
+KernelVersion: 6.1
+Description: Extension unit descriptors
+
+What: /config/usb-gadget/gadget/functions/uvc.name/control/extensions/name
+Date: Nov 2022
+KernelVersion: 6.1
+Description: Extension Unit (XU) Descriptor
+
+ bLength, bUnitID and iExtension are read-only. All others are
+ read-write.
+
+ ================= ========================================
+ bLength size of the descriptor in bytes
+ bUnitID non-zero ID of this unit
+ guidExtensionCode Vendor-specific code identifying the XU
+ bNumControls number of controls in this XU
+ bNrInPins number of input pins for this unit
+ baSourceID list of the IDs of the units or terminals
+ to which this XU is connected
+ bControlSize size of the bmControls field in bytes
+ bmControls list of bitmaps detailing which vendor
+ specific controls are supported
+ iExtension index of a string descriptor that describes
+ this extension unit
+ ================= ========================================
What: /config/usb-gadget/gadget/functions/uvc.name/control/header
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Control header descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/control/header/name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Specific control header descriptors
dwClockFrequency
bcdUVC
What: /config/usb-gadget/gadget/functions/uvc.name/streaming
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Streaming descriptors
+ All attributes read only:
+
+ ================ =============================
+ bInterfaceNumber USB interface number for this
+ streaming interface
+ ================ =============================
+
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Streaming class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/ss
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Super speed streaming class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/hs
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: High speed streaming class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/fs
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Full speed streaming class descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Color matching descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching/default
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Default color matching descriptors
- All attributes read only:
- bMatrixCoefficients - matrix used to compute luma and
- chroma values from the color primaries
- bTransferCharacteristics- optoelectronic transfer
- characteristic of the source picutre,
- also called the gamma function
- bColorPrimaries - color primaries and the reference
- white
+ All attributes read/write:
+
+ ======================== ======================================
+ bMatrixCoefficients matrix used to compute luma and
+ chroma values from the color primaries
+ bTransferCharacteristics optoelectronic transfer
+ characteristic of the source picture,
+ also called the gamma function
+ bColorPrimaries color primaries and the reference
+ white
+ ======================== ======================================
+
+What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching/name
+Date: Dec 2022
+KernelVersion: 6.3
+Description: Additional color matching descriptors
+
+ All attributes read/write:
+
+ ======================== ======================================
+ bMatrixCoefficients matrix used to compute luma and
+ chroma values from the color primaries
+ bTransferCharacteristics optoelectronic transfer
+ characteristic of the source picture,
+ also called the gamma function
+ bColorPrimaries color primaries and the reference
+ white
+ ======================== ======================================
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: MJPEG format descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Specific MJPEG format descriptors
All attributes read only,
except bmaControls and bDefaultFrameIndex:
- bmaControls - this format's data for bmaControls in
+
+ =================== =====================================
+ bFormatIndex unique id for this format descriptor;
+ only defined after parent header is
+ linked into the streaming class;
+ read-only
+ bmaControls this format's data for bmaControls in
the streaming header
- bmInterfaceFlags - specifies interlace information,
+ bmInterlaceFlags specifies interlace information,
read-only
- bAspectRatioY - the X dimension of the picture aspect
+ bAspectRatioY the X dimension of the picture aspect
ratio, read-only
- bAspectRatioX - the Y dimension of the picture aspect
+ bAspectRatioX the Y dimension of the picture aspect
ratio, read-only
- bmFlags - characteristics of this format,
+ bmFlags characteristics of this format,
read-only
- bDefaultFrameIndex - optimum frame index for this stream
+ bDefaultFrameIndex optimum frame index for this stream
+ =================== =====================================
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Specific MJPEG frame descriptors
- dwFrameInterval - indicates how frame interval can be
- programmed; a number of values
- separated by newline can be specified
- dwDefaultFrameInterval - the frame interval the device would
- like to use as default
- dwMaxVideoFrameBufferSize- the maximum number of bytes the
- compressor will produce for a video
- frame or still image
- dwMaxBitRate - the maximum bit rate at the shortest
- frame interval in bps
- dwMinBitRate - the minimum bit rate at the longest
- frame interval in bps
- wHeight - height of decoded bitmap frame in px
- wWidth - width of decoded bitmam frame in px
- bmCapabilities - still image support, fixed frame-rate
- support
+ ========================= =====================================
+ bFrameIndex unique id for this framedescriptor;
+ only defined after parent format is
+ linked into the streaming header;
+ read-only
+ dwFrameInterval indicates how frame interval can be
+ programmed; a number of values
+ separated by newline can be specified
+ dwDefaultFrameInterval the frame interval the device would
+ like to use as default
+ dwMaxVideoFrameBufferSize the maximum number of bytes the
+ compressor will produce for a video
+ frame or still image
+ dwMaxBitRate the maximum bit rate at the shortest
+ frame interval in bps
+ dwMinBitRate the minimum bit rate at the longest
+ frame interval in bps
+ wHeight height of decoded bitmap frame in px
+ wWidth width of decoded bitmam frame in px
+ bmCapabilities still image support, fixed frame-rate
+ support
+ ========================= =====================================
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Uncompressed format descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Specific uncompressed format descriptors
- bmaControls - this format's data for bmaControls in
+ ================== =======================================
+ bFormatIndex unique id for this format descriptor;
+ only defined after parent header is
+ linked into the streaming class;
+ read-only
+ bmaControls this format's data for bmaControls in
the streaming header
- bmInterfaceFlags - specifies interlace information,
+ bmInterlaceFlags specifies interlace information,
read-only
- bAspectRatioY - the X dimension of the picture aspect
+ bAspectRatioY the X dimension of the picture aspect
ratio, read-only
- bAspectRatioX - the Y dimension of the picture aspect
+ bAspectRatioX the Y dimension of the picture aspect
ratio, read-only
- bDefaultFrameIndex - optimum frame index for this stream
- bBitsPerPixel - number of bits per pixel used to
+ bDefaultFrameIndex optimum frame index for this stream
+ bBitsPerPixel number of bits per pixel used to
specify color in the decoded video
frame
- guidFormat - globally unique id used to identify
+ guidFormat globally unique id used to identify
stream-encoding format
+ ================== =======================================
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Specific uncompressed frame descriptors
- dwFrameInterval - indicates how frame interval can be
- programmed; a number of values
- separated by newline can be specified
- dwDefaultFrameInterval - the frame interval the device would
- like to use as default
- dwMaxVideoFrameBufferSize- the maximum number of bytes the
- compressor will produce for a video
- frame or still image
- dwMaxBitRate - the maximum bit rate at the shortest
- frame interval in bps
- dwMinBitRate - the minimum bit rate at the longest
- frame interval in bps
- wHeight - height of decoded bitmap frame in px
- wWidth - width of decoded bitmam frame in px
- bmCapabilities - still image support, fixed frame-rate
- support
+ ========================= =====================================
+ bFrameIndex unique id for this framedescriptor;
+ only defined after parent format is
+ linked into the streaming header;
+ read-only
+ dwFrameInterval indicates how frame interval can be
+ programmed; a number of values
+ separated by newline can be specified
+ dwDefaultFrameInterval the frame interval the device would
+ like to use as default
+ dwMaxVideoFrameBufferSize the maximum number of bytes the
+ compressor will produce for a video
+ frame or still image
+ dwMaxBitRate the maximum bit rate at the shortest
+ frame interval in bps
+ dwMinBitRate the minimum bit rate at the longest
+ frame interval in bps
+ wHeight height of decoded bitmap frame in px
+ wWidth width of decoded bitmam frame in px
+ bmCapabilities still image support, fixed frame-rate
+ support
+ ========================= =====================================
+
+What: /config/usb-gadget/gadget/functions/uvc.name/streaming/framebased
+Date: Sept 2024
+KernelVersion: 5.15
+Description: Framebased format descriptors
+
+What: /config/usb-gadget/gadget/functions/uvc.name/streaming/framebased/name
+Date: Sept 2024
+KernelVersion: 5.15
+Description: Specific framebased format descriptors
+
+ ================== =======================================
+ bFormatIndex unique id for this format descriptor;
+ only defined after parent header is
+ linked into the streaming class;
+ read-only
+ bmaControls this format's data for bmaControls in
+ the streaming header
+ bmInterlaceFlags specifies interlace information,
+ read-only
+ bAspectRatioY the X dimension of the picture aspect
+ ratio, read-only
+ bAspectRatioX the Y dimension of the picture aspect
+ ratio, read-only
+ bDefaultFrameIndex optimum frame index for this stream
+ bBitsPerPixel number of bits per pixel used to
+ specify color in the decoded video
+ frame
+ guidFormat globally unique id used to identify
+ stream-encoding format
+ ================== =======================================
+
+What: /config/usb-gadget/gadget/functions/uvc.name/streaming/framebased/name/name
+Date: Sept 2024
+KernelVersion: 5.15
+Description: Specific framebased frame descriptors
+
+ ========================= =====================================
+ bFrameIndex unique id for this framedescriptor;
+ only defined after parent format is
+ linked into the streaming header;
+ read-only
+ dwFrameInterval indicates how frame interval can be
+ programmed; a number of values
+ separated by newline can be specified
+ dwDefaultFrameInterval the frame interval the device would
+ like to use as default
+ dwBytesPerLine Specifies the number of bytes per line
+ of video for packed fixed frame size
+ formats, allowing the receiver to
+ perform stride alignment of the video.
+ If the bVariableSize value (above) is
+ TRUE (1), or if the format does not
+ permit such alignment, this value shall
+ be set to zero (0).
+ dwMaxBitRate the maximum bit rate at the shortest
+ frame interval in bps
+ dwMinBitRate the minimum bit rate at the longest
+ frame interval in bps
+ wHeight height of decoded bitmap frame in px
+ wWidth width of decoded bitmam frame in px
+ bmCapabilities still image support, fixed frame-rate
+ support
+ ========================= =====================================
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Streaming header descriptors
What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header/name
Date: Dec 2014
-KernelVersion: 3.20
+KernelVersion: 4.0
Description: Specific streaming header descriptors
All attributes read only:
- bTriggerUsage - how the host software will respond to
+
+ ==================== =====================================
+ bTriggerUsage how the host software will respond to
a hardware trigger interrupt event
- bTriggerSupport - flag specifying if hardware
+ bTriggerSupport flag specifying if hardware
triggering is supported
- bStillCaptureMethod - method of still image caputre
+ bStillCaptureMethod method of still image capture
supported
- bTerminalLink - id of the output terminal to which
+ bTerminalLink id of the output terminal to which
the video endpoint of this interface
is connected
- bmInfo - capabilities of this video streaming
+ bmInfo capabilities of this video streaming
interface
+ ==================== =====================================
+
+What: /sys/class/udc/udc.name/device/gadget/video4linux/video.name/function_name
+Date: May 2018
+KernelVersion: 4.19
+Description: UVC configfs function instance name
diff --git a/Documentation/ABI/testing/debugfs-alienware-wmi b/Documentation/ABI/testing/debugfs-alienware-wmi
new file mode 100644
index 000000000000..c7f525d6baac
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-alienware-wmi
@@ -0,0 +1,64 @@
+What: /sys/kernel/debug/alienware-wmi-<wmi_device_name>/system_description
+Date: March 2025
+KernelVersion: 6.15
+Contact: Kurt Borja <kuurtb@gmail.com>
+Description:
+ This file exposes the raw ``system_description`` number reported
+ by the WMAX device.
+
+ Only present on devices with the AWCC interface.
+
+ See Documentation/admin-guide/laptops/alienware-wmi.rst for
+ details.
+
+ RO
+
+What: /sys/kernel/debug/alienware-wmi-<wmi_device_name>/hwmon_data
+Date: March 2025
+KernelVersion: 6.15
+Contact: Kurt Borja <kuurtb@gmail.com>
+Description:
+ This file exposes HWMON private data.
+
+ Includes fan sensor count, temperature sensor count, internal
+ fan IDs and internal temp IDs.
+
+ See Documentation/admin-guide/laptops/alienware-wmi.rst for
+ details.
+
+ RO
+
+What: /sys/kernel/debug/alienware-wmi-<wmi_device_name>/pprof_data
+Date: March 2025
+KernelVersion: 6.15
+Contact: Kurt Borja <kuurtb@gmail.com>
+Description:
+ This file exposes Platform Profile private data.
+
+ Includes internal mapping to platform profiles and thermal
+ profile IDs.
+
+ See Documentation/admin-guide/laptops/alienware-wmi.rst for
+ details.
+
+ RO
+
+What: /sys/kernel/debug/alienware-wmi-<wmi_device_name>/gpio_ctl/total_gpios
+Date: May 2025
+KernelVersion: 6.16
+Contact: Kurt Borja <kuurtb@gmail.com>
+Description:
+ Total number of GPIO pins reported by the device.
+
+ RO
+
+What: /sys/kernel/debug/alienware-wmi-<wmi_device_name>/gpio_ctl/pinX
+Date: May 2025
+KernelVersion: 6.16
+Contact: Kurt Borja <kuurtb@gmail.com>
+Description:
+ This file controls GPIO pin X status.
+
+ See Documentation/wmi/devices/alienware-wmi.rst for details.
+
+ RW
diff --git a/Documentation/ABI/testing/debugfs-amd-iommu b/Documentation/ABI/testing/debugfs-amd-iommu
new file mode 100644
index 000000000000..5621a66aa693
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-amd-iommu
@@ -0,0 +1,131 @@
+What: /sys/kernel/debug/iommu/amd/iommu<x>/mmio
+Date: January 2025
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file provides read/write access for user input. Users specify the
+ MMIO register offset for iommu<x>, and the file outputs the corresponding
+ MMIO register value of iommu<x>
+
+ Example::
+
+ $ echo "0x18" > /sys/kernel/debug/iommu/amd/iommu00/mmio
+ $ cat /sys/kernel/debug/iommu/amd/iommu00/mmio
+
+ Output::
+
+ Offset:0x18 Value:0x000c22000003f48d
+
+What: /sys/kernel/debug/iommu/amd/iommu<x>/capability
+Date: January 2025
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file provides read/write access for user input. Users specify the
+ capability register offset for iommu<x>, and the file outputs the
+ corresponding capability register value of iommu<x>.
+
+ Example::
+
+ $ echo "0x10" > /sys/kernel/debug/iommu/amd/iommu00/capability
+ $ cat /sys/kernel/debug/iommu/amd/iommu00/capability
+
+ Output::
+
+ Offset:0x10 Value:0x00203040
+
+What: /sys/kernel/debug/iommu/amd/iommu<x>/cmdbuf
+Date: January 2025
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file is a read-only output file containing iommu<x> command
+ buffer entries.
+
+ Examples::
+
+ $ cat /sys/kernel/debug/iommu/amd/iommu<x>/cmdbuf
+
+ Output::
+
+ CMD Buffer Head Offset:339 Tail Offset:339
+ 0: 00835001 10000001 00003c00 00000000
+ 1: 00000000 30000005 fffff003 7fffffff
+ 2: 00835001 10000001 00003c01 00000000
+ 3: 00000000 30000005 fffff003 7fffffff
+ 4: 00835001 10000001 00003c02 00000000
+ 5: 00000000 30000005 fffff003 7fffffff
+ 6: 00835001 10000001 00003c03 00000000
+ 7: 00000000 30000005 fffff003 7fffffff
+ 8: 00835001 10000001 00003c04 00000000
+ 9: 00000000 30000005 fffff003 7fffffff
+ 10: 00835001 10000001 00003c05 00000000
+ 11: 00000000 30000005 fffff003 7fffffff
+ [...]
+
+What: /sys/kernel/debug/iommu/amd/devid
+Date: January 2025
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file provides read/write access for user input. Users specify the
+ device ID, which can be used to dump IOMMU data structures such as the
+ interrupt remapping table and device table.
+
+ Example:
+
+ 1.
+ ::
+
+ $ echo 0000:01:00.0 > /sys/kernel/debug/iommu/amd/devid
+ $ cat /sys/kernel/debug/iommu/amd/devid
+
+ Output::
+
+ 0000:01:00.0
+
+ 2.
+ ::
+
+ $ echo 01:00.0 > /sys/kernel/debug/iommu/amd/devid
+ $ cat /sys/kernel/debug/iommu/amd/devid
+
+ Output::
+
+ 0000:01:00.0
+
+What: /sys/kernel/debug/iommu/amd/devtbl
+Date: January 2025
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file is a read-only output file containing the device table entry
+ for the device ID provided in /sys/kernel/debug/iommu/amd/devid.
+
+ Example::
+
+ $ cat /sys/kernel/debug/iommu/amd/devtbl
+
+ Output::
+
+ DeviceId QWORD[3] QWORD[2] QWORD[1] QWORD[0] iommu
+ 0000:01:00.0 0000000000000000 20000001373b8013 0000000000000038 6000000114d7b603 iommu3
+
+What: /sys/kernel/debug/iommu/amd/irqtbl
+Date: January 2025
+Contact: Dheeraj Kumar Srivastava <dheerajkumar.srivastava@amd.com>
+Description:
+ This file is a read-only output file containing valid IRT table entries
+ for the device ID provided in /sys/kernel/debug/iommu/amd/devid.
+
+ Example::
+
+ $ cat /sys/kernel/debug/iommu/amd/irqtbl
+
+ Output::
+
+ DeviceId 0000:01:00.0
+ IRT[0000] 0000000000000020 0000000000000241
+ IRT[0001] 0000000000000020 0000000000000841
+ IRT[0002] 0000000000000020 0000000000002041
+ IRT[0003] 0000000000000020 0000000000008041
+ IRT[0004] 0000000000000020 0000000000020041
+ IRT[0005] 0000000000000020 0000000000080041
+ IRT[0006] 0000000000000020 0000000000200041
+ IRT[0007] 0000000000000020 0000000000800041
+ [...]
diff --git a/Documentation/ABI/testing/debugfs-cec-error-inj b/Documentation/ABI/testing/debugfs-cec-error-inj
new file mode 100644
index 000000000000..c512f71bba8e
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-cec-error-inj
@@ -0,0 +1,40 @@
+What: /sys/kernel/debug/cec/*/error-inj
+Date: March 2018
+Contact: Hans Verkuil <hverkuil@kernel.org>
+Description:
+
+The CEC Framework allows for CEC error injection commands through
+debugfs. Drivers that support this will create an error-inj file
+through which the error injection commands can be given.
+
+The basic syntax is as follows:
+
+Leading spaces/tabs are ignored. If the next character is a '#' or the
+end of the line was reached, then the whole line is ignored. Otherwise
+a command is expected.
+
+It is up to the driver to decide what commands to implement. The only
+exception is that the command 'clear' without any arguments must be
+implemented and that it will remove all current error injection
+commands.
+
+This ensures that you can always do 'echo clear >error-inj' to clear any
+error injections without having to know the details of the driver-specific
+commands.
+
+Note that the output of 'error-inj' shall be valid as input to 'error-inj'.
+So this must work::
+
+ $ cat error-inj >einj.txt
+ $ cat einj.txt >error-inj
+
+Other than these basic rules described above this ABI is not considered
+stable and may change in the future.
+
+Drivers that implement this functionality must document the commands as
+part of the CEC documentation and must keep that documentation up to date
+when changes are made.
+
+The following CEC error injection implementations exist:
+
+- Documentation/userspace-api/media/cec/cec-pin-error-inj.rst
diff --git a/Documentation/ABI/testing/debugfs-cros-ec b/Documentation/ABI/testing/debugfs-cros-ec
new file mode 100644
index 000000000000..9a040c6f5e03
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-cros-ec
@@ -0,0 +1,78 @@
+What: /sys/kernel/debug/<cros-ec-device>/console_log
+Date: September 2017
+KernelVersion: 4.13
+Description:
+ If the EC supports the CONSOLE_READ command type, this file
+ can be used to grab the EC logs. The kernel polls for the log
+ and keeps its own buffer but userspace should grab this and
+ write it out to some logs.
+
+What: /sys/kernel/debug/<cros-ec-device>/panicinfo
+Date: September 2017
+KernelVersion: 4.13
+Description:
+ This file dumps the EC panic information from the previous
+ reboot. This file will only exist if the PANIC_INFO command
+ type is supported by the EC.
+
+What: /sys/kernel/debug/<cros-ec-device>/pdinfo
+Date: June 2018
+KernelVersion: 4.17
+Description:
+ This file provides the port role, muxes and power debug
+ information for all the USB PD/type-C ports available. If
+ the are no ports available, this file will be just an empty
+ file.
+
+What: /sys/kernel/debug/<cros-ec-device>/uptime
+Date: June 2019
+KernelVersion: 5.3
+Description:
+ A u32 providing the time since EC booted in ms. This is
+ is used for synchronizing the AP host time with the EC
+ log. An error is returned if the command is not supported
+ by the EC or there is a communication problem.
+
+What: /sys/kernel/debug/<cros-ec-device>/last_resume_result
+Date: June 2019
+KernelVersion: 5.3
+Description:
+ Some ECs have a feature where they will track transitions to
+ the (Intel) processor's SLP_S0 line, in order to detect cases
+ where a system failed to go into S0ix. When the system resumes,
+ an EC with this feature will return a summary of SLP_S0
+ transitions that occurred. The last_resume_result file returns
+ the most recent response from the AP's resume message to the EC.
+
+ The bottom 31 bits contain a count of the number of SLP_S0
+ transitions that occurred since the suspend message was
+ received. Bit 31 is set if the EC attempted to wake the
+ system due to a timeout when watching for SLP_S0 transitions.
+ Callers can use this to detect a wake from the EC due to
+ S0ix timeouts. The result will be zero if no suspend
+ transitions have been attempted, or the EC does not support
+ this feature.
+
+ Output will be in the format: "0x%08x\n".
+
+What: /sys/kernel/debug/<cros-ec-device>/suspend_timeout_ms
+Date: August 2022
+KernelVersion: 6.1
+Description:
+ Some ECs have a feature where they will track transitions of
+ a hardware-controlled sleep line, such as Intel's SLP_S0 line,
+ in order to detect cases where a system failed to go into deep
+ sleep states. The suspend_timeout_ms file controls the amount of
+ time in milliseconds the EC will wait before declaring a sleep
+ timeout event and attempting to wake the system.
+
+ Supply 0 to use the default value coded into EC firmware. Supply
+ 65535 (EC_HOST_SLEEP_TIMEOUT_INFINITE) to disable the EC sleep
+ failure detection mechanism. Values in between 0 and 65535
+ indicate the number of milliseconds the EC should wait after a
+ sleep transition before declaring a timeout. This includes both
+ the duration after a sleep command was received but before the
+ hardware line changed, as well as the duration between when the
+ hardware line changed and the kernel sent an EC resume command.
+
+ Output will be in the format: "%u\n".
diff --git a/Documentation/ABI/testing/debugfs-cxl b/Documentation/ABI/testing/debugfs-cxl
new file mode 100644
index 000000000000..2989d4da96c1
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-cxl
@@ -0,0 +1,157 @@
+What: /sys/kernel/debug/cxl/memX/inject_poison
+Date: April, 2023
+KernelVersion: v6.4
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) When a Device Physical Address (DPA) is written to this
+ attribute, the memdev driver sends an inject poison command to
+ the device for the specified address. The DPA must be 64-byte
+ aligned and the length of the injected poison is 64-bytes. If
+ successful, the device returns poison when the address is
+ accessed through the CXL.mem bus. Injecting poison adds the
+ address to the device's Poison List and the error source is set
+ to Injected. In addition, the device adds a poison creation
+ event to its internal Informational Event log, updates the
+ Event Status register, and if configured, interrupts the host.
+ It is not an error to inject poison into an address that
+ already has poison present and no error is returned. If the
+ device returns 'Inject Poison Limit Reached' an -EBUSY error
+ is returned to the user. The inject_poison attribute is only
+ visible for devices supporting the capability.
+
+ TEST-ONLY INTERFACE: This interface is intended for testing
+ and validation purposes only. It is not a data repair mechanism
+ and should never be used on production systems or live data.
+
+ DATA LOSS RISK: For CXL persistent memory (PMEM) devices,
+ poison injection can result in permanent data loss. Injected
+ poison may render data permanently inaccessible even after
+ clearing, as the clear operation writes zeros and does not
+ recover original data.
+
+ SYSTEM STABILITY RISK: For volatile memory, poison injection
+ can cause kernel crashes, system instability, or unpredictable
+ behavior if the poisoned addresses are accessed by running code
+ or critical kernel structures.
+
+What: /sys/kernel/debug/cxl/memX/clear_poison
+Date: April, 2023
+KernelVersion: v6.4
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) When a Device Physical Address (DPA) is written to this
+ attribute, the memdev driver sends a clear poison command to
+ the device for the specified address. Clearing poison removes
+ the address from the device's Poison List and writes 0 (zero)
+ for 64 bytes starting at address. It is not an error to clear
+ poison from an address that does not have poison set. If the
+ device cannot clear poison from the address, -ENXIO is returned.
+ The clear_poison attribute is only visible for devices
+ supporting the capability.
+
+ TEST-ONLY INTERFACE: This interface is intended for testing
+ and validation purposes only. It is not a data repair mechanism
+ and should never be used on production systems or live data.
+
+ CLEAR IS NOT DATA RECOVERY: This operation writes zeros to the
+ specified address range and removes the address from the poison
+ list. It does NOT recover or restore original data that may have
+ been present before poison injection. Any original data at the
+ cleared address is permanently lost and replaced with zeros.
+
+ CLEAR IS NOT A REPAIR MECHANISM: This interface is for testing
+ purposes only and should not be used as a data repair tool.
+ Clearing poison is fundamentally different from data recovery
+ or error correction.
+
+What: /sys/kernel/debug/cxl/regionX/inject_poison
+Date: August, 2025
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) When a Host Physical Address (HPA) is written to this
+ attribute, the region driver translates it to a Device
+ Physical Address (DPA) and identifies the corresponding
+ memdev. It then sends an inject poison command to that memdev
+ at the translated DPA. Refer to the memdev ABI entry at:
+ /sys/kernel/debug/cxl/memX/inject_poison for the detailed
+ behavior. This attribute is only visible if all memdevs
+ participating in the region support both inject and clear
+ poison commands.
+
+ TEST-ONLY INTERFACE: This interface is intended for testing
+ and validation purposes only. It is not a data repair mechanism
+ and should never be used on production systems or live data.
+
+ DATA LOSS RISK: For CXL persistent memory (PMEM) devices,
+ poison injection can result in permanent data loss. Injected
+ poison may render data permanently inaccessible even after
+ clearing, as the clear operation writes zeros and does not
+ recover original data.
+
+ SYSTEM STABILITY RISK: For volatile memory, poison injection
+ can cause kernel crashes, system instability, or unpredictable
+ behavior if the poisoned addresses are accessed by running code
+ or critical kernel structures.
+
+What: /sys/kernel/debug/cxl/regionX/clear_poison
+Date: August, 2025
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) When a Host Physical Address (HPA) is written to this
+ attribute, the region driver translates it to a Device
+ Physical Address (DPA) and identifies the corresponding
+ memdev. It then sends a clear poison command to that memdev
+ at the translated DPA. Refer to the memdev ABI entry at:
+ /sys/kernel/debug/cxl/memX/clear_poison for the detailed
+ behavior. This attribute is only visible if all memdevs
+ participating in the region support both inject and clear
+ poison commands.
+
+ TEST-ONLY INTERFACE: This interface is intended for testing
+ and validation purposes only. It is not a data repair mechanism
+ and should never be used on production systems or live data.
+
+ CLEAR IS NOT DATA RECOVERY: This operation writes zeros to the
+ specified address range and removes the address from the poison
+ list. It does NOT recover or restore original data that may have
+ been present before poison injection. Any original data at the
+ cleared address is permanently lost and replaced with zeros.
+
+ CLEAR IS NOT A REPAIR MECHANISM: This interface is for testing
+ purposes only and should not be used as a data repair tool.
+ Clearing poison is fundamentally different from data recovery
+ or error correction.
+
+What: /sys/kernel/debug/cxl/einj_types
+Date: January, 2024
+KernelVersion: v6.9
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) Prints the CXL protocol error types made available by
+ the platform in the format:
+
+ 0x<error number> <error type>
+
+ The possible error types are (as of ACPI v6.5):
+
+ 0x1000 CXL.cache Protocol Correctable
+ 0x2000 CXL.cache Protocol Uncorrectable non-fatal
+ 0x4000 CXL.cache Protocol Uncorrectable fatal
+ 0x8000 CXL.mem Protocol Correctable
+ 0x10000 CXL.mem Protocol Uncorrectable non-fatal
+ 0x20000 CXL.mem Protocol Uncorrectable fatal
+
+ The <error number> can be written to einj_inject to inject
+ <error type> into a chosen dport.
+
+What: /sys/kernel/debug/cxl/$dport_dev/einj_inject
+Date: January, 2024
+KernelVersion: v6.9
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) Writing an integer to this file injects the corresponding
+ CXL protocol error into $dport_dev ($dport_dev will be a device
+ name from /sys/bus/pci/devices). The integer to type mapping for
+ injection can be found by reading from einj_types. If the dport
+ was enumerated in RCH mode, a CXL 1.1 error is injected, otherwise
+ a CXL 2.0 error is injected.
diff --git a/Documentation/ABI/testing/debugfs-dell-wmi-ddv b/Documentation/ABI/testing/debugfs-dell-wmi-ddv
new file mode 100644
index 000000000000..81cfc788be15
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-dell-wmi-ddv
@@ -0,0 +1,34 @@
+What: /sys/kernel/debug/dell-wmi-ddv-<wmi_device_name>/fan_sensor_information
+Date: September 2022
+KernelVersion: 6.1
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ This file contains the contents of the fan sensor information
+ buffer, which contains fan sensor entries and a terminating
+ character (0xFF).
+
+ Each fan sensor entry contains:
+
+ - fan type (single byte)
+ - fan speed in RPM (two bytes, little endian)
+
+ See Documentation/wmi/devices/dell-wmi-ddv.rst for details.
+
+What: /sys/kernel/debug/dell-wmi-ddv-<wmi_device_name>/thermal_sensor_information
+Date: September 2022
+KernelVersion: 6.1
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ This file contains the contents of the thermal sensor information
+ buffer, which contains thermal sensor entries and a terminating
+ character (0xFF).
+
+ Each thermal sensor entry contains:
+
+ - thermal type (single byte)
+ - current temperature (single byte)
+ - min. temperature (single byte)
+ - max. temperature (single byte)
+ - unknown field (single byte)
+
+ See Documentation/wmi/devices/dell-wmi-ddv.rst for details.
diff --git a/Documentation/ABI/testing/debugfs-driver-dcc b/Documentation/ABI/testing/debugfs-driver-dcc
new file mode 100644
index 000000000000..27ed5919d21b
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-driver-dcc
@@ -0,0 +1,127 @@
+What: /sys/kernel/debug/dcc/.../ready
+Date: December 2022
+Contact: Souradeep Chowdhury <quic_schowdhu@quicinc.com>
+Description:
+ This file is used to check the status of the dcc
+ hardware if it's ready to receive user configurations.
+ A 'Y' here indicates dcc is ready.
+
+What: /sys/kernel/debug/dcc/.../trigger
+Date: December 2022
+Contact: Souradeep Chowdhury <quic_schowdhu@quicinc.com>
+Description:
+ This is the debugfs interface for manual software
+ triggers. The trigger can be invoked by writing '1'
+ to the file.
+
+What: /sys/kernel/debug/dcc/.../config_reset
+Date: December 2022
+Contact: Souradeep Chowdhury <quic_schowdhu@quicinc.com>
+Description:
+ This file is used to reset the configuration of
+ a dcc driver to the default configuration. When '1'
+ is written to the file, all the previous addresses
+ stored in the driver gets removed and users need to
+ reconfigure addresses again.
+
+What: /sys/kernel/debug/dcc/.../[list-number]/config
+Date: December 2022
+Contact: Souradeep Chowdhury <quic_schowdhu@quicinc.com>
+Description:
+ This stores the addresses of the registers which
+ can be read in case of a hardware crash or manual
+ software triggers. The input addresses type
+ can be one of following dcc instructions: read,
+ write, read-write, and loop type. The lists need to
+ be configured sequentially and not in a overlapping
+ manner; e.g. users can jump to list x only after
+ list y is configured and enabled. The input format for
+ each type is as follows:
+
+ i) Read instruction
+
+ ::
+
+ echo R <addr> <n> <bus> >/sys/kernel/debug/dcc/../[list-number]/config
+
+ where:
+
+ <addr>
+ The address to be read.
+
+ <n>
+ The addresses word count, starting from address <1>.
+ Each word is 32 bits (4 bytes). If omitted, defaulted
+ to 1.
+
+ <bus type>
+ The bus type, which can be either 'apb' or 'ahb'.
+ The default is 'ahb' if leaved out.
+
+ ii) Write instruction
+
+ ::
+
+ echo W <addr> <n> <bus type> > /sys/kernel/debug/dcc/../[list-number]/config
+
+ where:
+
+ <addr>
+ The address to be written.
+
+ <n>
+ The value to be written at <addr>.
+
+ <bus type>
+ The bus type, which can be either 'apb' or 'ahb'.
+
+ iii) Read-write instruction
+
+ ::
+
+ echo RW <addr> <n> <mask> > /sys/kernel/debug/dcc/../[list-number]/config
+
+ where:
+
+ <addr>
+ The address to be read and written.
+
+ <n>
+ The value to be written at <addr>.
+
+ <mask>
+ The value mask.
+
+ iv) Loop instruction
+
+ ::
+
+ echo L <loop count> <address count> <address>... > /sys/kernel/debug/dcc/../[list-number]/config
+
+ where:
+
+ <loop count>
+ Number of iterations
+
+ <address count>
+ total number of addresses to be written
+
+ <address>
+ Space-separated list of addresses.
+
+What: /sys/kernel/debug/dcc/.../[list-number]/enable
+Date: December 2022
+Contact: Souradeep Chowdhury <quic_schowdhu@quicinc.com>
+Description:
+ This debugfs interface is used for enabling the
+ the dcc hardware. A file named "enable" is in the
+ directory list number where users can enable/disable
+ the specific list by writing boolean (1 or 0) to the
+ file.
+
+ On enabling the dcc, all the addresses specified
+ by the user for the corresponding list is written
+ into dcc sram which is read by the dcc hardware
+ on manual or crash induced triggers. Lists must
+ be configured and enabled sequentially, e.g. list
+ 2 can only be enabled when list 1 have so.
diff --git a/Documentation/ABI/testing/debugfs-driver-genwqe b/Documentation/ABI/testing/debugfs-driver-genwqe
index 1c2f25674e8c..b45b016545d8 100644
--- a/Documentation/ABI/testing/debugfs-driver-genwqe
+++ b/Documentation/ABI/testing/debugfs-driver-genwqe
@@ -31,7 +31,7 @@ What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_regs
Date: Oct 2013
Contact: haver@linux.vnet.ibm.com
Description: Dump of the error registers before the last reset of
- the card occured.
+ the card occurred.
Only available for PF.
What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid0
diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs
new file mode 100644
index 000000000000..3318a14f35b9
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-driver-habanalabs
@@ -0,0 +1,323 @@
+What: /sys/kernel/debug/accel/<parent_device>/addr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets the device address to be used for read or write through
+ PCI bar, or the device VA of a host mapped memory to be read or
+ written directly from the host. The latter option is allowed
+ only when the IOMMU is disabled.
+ The acceptable value is a string that starts with "0x"
+
+What: /sys/kernel/debug/accel/<parent_device>/clk_gate
+Date: May 2020
+KernelVersion: 5.8
+Contact: ogabbay@kernel.org
+Description: This setting is now deprecated as clock gating is handled solely by the f/w
+
+What: /sys/kernel/debug/accel/<parent_device>/command_buffers
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays a list with information about the currently allocated
+ command buffers
+
+What: /sys/kernel/debug/accel/<parent_device>/command_submission
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays a list with information about the currently active
+ command submissions
+
+What: /sys/kernel/debug/accel/<parent_device>/command_submission_jobs
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays a list with detailed information about each JOB (CB) of
+ each active command submission
+
+What: /sys/kernel/debug/accel/<parent_device>/data32
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Allows the root user to read or write directly through the
+ device's PCI bar. Writing to this file generates a write
+ transaction while reading from the file generates a read
+ transaction. This custom interface is needed (instead of using
+ the generic Linux user-space PCI mapping) because the DDR bar
+ is very small compared to the DDR memory and only the driver can
+ move the bar before and after the transaction.
+
+ If the IOMMU is disabled, it also allows the root user to read
+ or write from the host a device VA of a host mapped memory
+
+What: /sys/kernel/debug/accel/<parent_device>/data64
+Date: Jan 2020
+KernelVersion: 5.6
+Contact: ogabbay@kernel.org
+Description: Allows the root user to read or write 64 bit data directly
+ through the device's PCI bar. Writing to this file generates a
+ write transaction while reading from the file generates a read
+ transaction. This custom interface is needed (instead of using
+ the generic Linux user-space PCI mapping) because the DDR bar
+ is very small compared to the DDR memory and only the driver can
+ move the bar before and after the transaction.
+
+ If the IOMMU is disabled, it also allows the root user to read
+ or write from the host a device VA of a host mapped memory
+
+What: /sys/kernel/debug/accel/<parent_device>/data_dma
+Date: Apr 2021
+KernelVersion: 5.13
+Contact: ogabbay@kernel.org
+Description: Allows the root user to read from the device's internal
+ memory (DRAM/SRAM) through a DMA engine.
+ This property is a binary blob that contains the result of the
+ DMA transfer.
+ This custom interface is needed (instead of using the generic
+ Linux user-space PCI mapping) because the amount of internal
+ memory is huge (>32GB) and reading it via the PCI bar will take
+ a very long time.
+ This interface doesn't support concurrency in the same device.
+ In GAUDI and GOYA, this action can cause undefined behavior
+ in case it is done while the device is executing user
+ workloads.
+ Only supported on GAUDI at this stage.
+
+What: /sys/kernel/debug/accel/<parent_device>/device
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Enables the root user to set the device to specific state.
+ Valid values are "disable", "enable", "suspend", "resume".
+ User can read this property to see the valid values
+
+What: /sys/kernel/debug/accel/<parent_device>/device_release_watchdog_timeout
+Date: Oct 2022
+KernelVersion: 6.2
+Contact: ttayar@habana.ai
+Description: The watchdog timeout value in seconds for a device release upon
+ certain error cases, after which the device is reset.
+
+What: /sys/kernel/debug/accel/<parent_device>/dma_size
+Date: Apr 2021
+KernelVersion: 5.13
+Contact: ogabbay@kernel.org
+Description: Specify the size of the DMA transaction when using DMA to read
+ from the device's internal memory. The value can not be larger
+ than 128MB. Writing to this value initiates the DMA transfer.
+ When the write is finished, the user can read the "data_dma"
+ blob
+
+What: /sys/kernel/debug/accel/<parent_device>/dump_razwi_events
+Date: Aug 2022
+KernelVersion: 5.20
+Contact: fkassabri@habana.ai
+Description: Dumps all razwi events to dmesg if exist.
+ After reading the status register of an existing event
+ the routine will clear the status register.
+ Usage: cat dump_razwi_events
+
+What: /sys/kernel/debug/accel/<parent_device>/dump_security_violations
+Date: Jan 2021
+KernelVersion: 5.12
+Contact: ogabbay@kernel.org
+Description: Dumps all security violations to dmesg. This will also ack
+ all security violations meanings those violations will not be
+ dumped next time user calls this API
+
+What: /sys/kernel/debug/accel/<parent_device>/engines
+Date: Jul 2019
+KernelVersion: 5.3
+Contact: ogabbay@kernel.org
+Description: Displays the status registers values of the device engines and
+ their derived idle status
+
+What: /sys/kernel/debug/accel/<parent_device>/i2c_addr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets I2C device address for I2C transaction that is generated
+ by the device's CPU, Not available when device is loaded with secured
+ firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/i2c_bus
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets I2C bus address for I2C transaction that is generated by
+ the device's CPU, Not available when device is loaded with secured
+ firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/i2c_data
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Triggers an I2C transaction that is generated by the device's
+ CPU. Writing to this file generates a write transaction while
+ reading from the file generates a read transaction, Not available
+ when device is loaded with secured firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/i2c_len
+Date: Dec 2021
+KernelVersion: 5.17
+Contact: obitton@habana.ai
+Description: Sets I2C length in bytes for I2C transaction that is generated by
+ the device's CPU, Not available when device is loaded with secured
+ firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/i2c_reg
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets I2C register id for I2C transaction that is generated by
+ the device's CPU, Not available when device is loaded with secured
+ firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/led0
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets the state of the first S/W led on the device, Not available
+ when device is loaded with secured firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/led1
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets the state of the second S/W led on the device, Not available
+ when device is loaded with secured firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/led2
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets the state of the third S/W led on the device, Not available
+ when device is loaded with secured firmware
+
+What: /sys/kernel/debug/accel/<parent_device>/memory_scrub
+Date: May 2022
+KernelVersion: 5.19
+Contact: dhirschfeld@habana.ai
+Description: Allows the root user to scrub the dram memory. The scrubbing
+ value can be set using the debugfs file memory_scrub_val.
+
+What: /sys/kernel/debug/accel/<parent_device>/memory_scrub_val
+Date: May 2022
+KernelVersion: 5.19
+Contact: dhirschfeld@habana.ai
+Description: The value to which the dram will be set to when the user
+ scrubs the dram using 'memory_scrub' debugfs file and
+ the scrubbing value when using module param 'memory_scrub'
+
+What: /sys/kernel/debug/accel/<parent_device>/mmu
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the hop values and physical address for a given ASID
+ and virtual address. The user should write the ASID and VA into
+ the file and then read the file to get the result.
+ e.g. to display info about VA 0x1000 for ASID 1 you need to do:
+ echo "1 0x1000" > /sys/kernel/debug/accel/<parent_device>/mmu
+
+What: /sys/kernel/debug/accel/<parent_device>/mmu_error
+Date: Mar 2021
+KernelVersion: 5.12
+Contact: fkassabri@habana.ai
+Description: Check and display page fault or access violation mmu errors for
+ all MMUs specified in mmu_cap_mask.
+ e.g. to display error info for MMU hw cap bit 9, you need to do:
+ echo "0x200" > /sys/kernel/debug/accel/<parent_device>/mmu_error
+ cat /sys/kernel/debug/accel/<parent_device>/mmu_error
+
+What: /sys/kernel/debug/accel/<parent_device>/monitor_dump
+Date: Mar 2022
+KernelVersion: 5.19
+Contact: osharabi@habana.ai
+Description: Allows the root user to dump monitors status from the device's
+ protected config space.
+ This property is a binary blob that contains the result of the
+ monitors registers dump.
+ This custom interface is needed (instead of using the generic
+ Linux user-space PCI mapping) because this space is protected
+ and cannot be accessed using PCI read.
+ This interface doesn't support concurrency in the same device.
+ Only supported on GAUDI.
+
+What: /sys/kernel/debug/accel/<parent_device>/monitor_dump_trig
+Date: Mar 2022
+KernelVersion: 5.19
+Contact: osharabi@habana.ai
+Description: Triggers dump of monitor data. The value to trigger the operation
+ must be 1. Triggering the monitor dump operation initiates dump of
+ current registers values of all monitors.
+ When the write is finished, the user can read the "monitor_dump"
+ blob
+
+What: /sys/kernel/debug/accel/<parent_device>/server_type
+Date: Feb 2024
+KernelVersion: 6.11
+Contact: trisin@habana.ai
+Description: Exposes the device's server type, maps to enum hl_server_type.
+
+What: /sys/kernel/debug/accel/<parent_device>/set_power_state
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Sets the PCI power state. Valid values are "1" for D0 and "2"
+ for D3Hot
+
+What: /sys/kernel/debug/accel/<parent_device>/skip_reset_on_timeout
+Date: Jun 2021
+KernelVersion: 5.13
+Contact: ynudelman@habana.ai
+Description: Sets the skip reset on timeout option for the device. Value of
+ "0" means device will be reset in case some CS has timed out,
+ otherwise it will not be reset.
+
+What: /sys/kernel/debug/accel/<parent_device>/state_dump
+Date: Oct 2021
+KernelVersion: 5.15
+Contact: ynudelman@habana.ai
+Description: Gets the state dump occurring on a CS timeout or failure.
+ State dump is used for debug and is created each time in case of
+ a problem in a CS execution, before reset.
+ Reading from the node returns the newest state dump available.
+ Writing an integer X discards X state dumps, so that the
+ next read would return X+1-st newest state dump.
+
+What: /sys/kernel/debug/accel/<parent_device>/stop_on_err
+Date: Mar 2020
+KernelVersion: 5.6
+Contact: ogabbay@kernel.org
+Description: Sets the stop-on_error option for the device engines. Value of
+ "0" is for disable, otherwise enable.
+ Relevant only for GOYA and GAUDI.
+
+What: /sys/kernel/debug/accel/<parent_device>/timeout_locked
+Date: Sep 2021
+KernelVersion: 5.16
+Contact: obitton@habana.ai
+Description: Sets the command submission timeout value in seconds.
+
+What: /sys/kernel/debug/accel/<parent_device>/userptr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays a list with information about the current user
+ pointers (user virtual addresses) that are pinned and mapped
+ to DMA addresses
+
+What: /sys/kernel/debug/accel/<parent_device>/userptr_lookup
+Date: Oct 2021
+KernelVersion: 5.15
+Contact: ogabbay@kernel.org
+Description: Allows to search for specific user pointers (user virtual
+ addresses) that are pinned and mapped to DMA addresses, and see
+ their resolution to the specific dma address.
+
+What: /sys/kernel/debug/accel/<parent_device>/vm
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays a list with information about all the active virtual
+ address mappings per ASID and all user mappings of HW blocks
diff --git a/Documentation/ABI/testing/debugfs-driver-qat b/Documentation/ABI/testing/debugfs-driver-qat
new file mode 100644
index 000000000000..3f1efbbad6ca
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-driver-qat
@@ -0,0 +1,109 @@
+What: /sys/kernel/debug/qat_<device>_<BDF>/fw_counters
+Date: November 2023
+KernelVersion: 6.6
+Contact: qat-linux@intel.com
+Description: (RO) Read returns the number of requests sent to the FW and the number of responses
+ received from the FW for each Acceleration Engine
+ Reported firmware counters::
+
+ <N>: Number of requests sent from Acceleration Engine N to FW and responses
+ Acceleration Engine N received from FW
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/config
+Date: November 2023
+KernelVersion: 6.6
+Contact: qat-linux@intel.com
+Description: (RW) Read returns value of the Heartbeat update period.
+ Write to the file changes this period value.
+
+ This period should reflect planned polling interval of device
+ health status. High frequency Heartbeat monitoring wastes CPU cycles
+ but minimizes the customer’s system downtime. Also, if there are
+ large service requests that take some time to complete, high frequency
+ Heartbeat monitoring could result in false reports of unresponsiveness
+ and in those cases, period needs to be increased.
+
+ This parameter is effective only for c3xxx, c62x, dh895xcc devices.
+ 4xxx has this value internally fixed to 200ms.
+
+ Default value is set to 500. Minimal allowed value is 200.
+ All values are expressed in milliseconds.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_failed
+Date: November 2023
+KernelVersion: 6.6
+Contact: qat-linux@intel.com
+Description: (RO) Read returns the number of times the device became unresponsive.
+
+ Attribute returns value of the counter which is incremented when
+ status query results negative.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_sent
+Date: November 2023
+KernelVersion: 6.6
+Contact: qat-linux@intel.com
+Description: (RO) Read returns the number of times the control process checked
+ if the device is responsive.
+
+ Attribute returns value of the counter which is incremented on
+ every status query.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/status
+Date: November 2023
+KernelVersion: 6.6
+Contact: qat-linux@intel.com
+Description: (RO) Read returns the device health status.
+
+ Returns 0 when device is healthy or -1 when is unresponsive
+ or the query failed to send.
+
+ The driver does not monitor for Heartbeat. It is left for a user
+ to poll the status periodically.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/pm_status
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description: (RO) Read returns power management information specific to the
+ QAT device.
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/cnv_errors
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description: (RO) Read returns, for each Acceleration Engine (AE), the number
+ of errors and the type of the last error detected by the device
+ when performing verified compression.
+ Reported counters::
+
+ <N>: Number of Compress and Verify (CnV) errors and type
+ of the last CnV error detected by Acceleration
+ Engine N.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/inject_error
+Date: March 2024
+KernelVersion: 6.8
+Contact: qat-linux@intel.com
+Description: (WO) Write to inject an error that simulates an heartbeat
+ failure. This is to be used for testing purposes.
+
+ After writing this file, the driver stops arbitration on a
+ random engine and disables the fetching of heartbeat counters.
+ If a workload is running on the device, a job submitted to the
+ accelerator might not get a response and a read of the
+ `heartbeat/status` attribute might report -1, i.e. device
+ unresponsive.
+ The error is unrecoverable thus the device must be restarted to
+ restore its functionality.
+
+ This attribute is available only when the kernel is built with
+ CONFIG_CRYPTO_DEV_QAT_ERROR_INJECTION=y.
+
+ A write of 1 enables error injection.
+
+ The following example shows how to enable error injection::
+
+ # cd /sys/kernel/debug/qat_<device>_<BDF>
+ # echo 1 > heartbeat/inject_error
diff --git a/Documentation/ABI/testing/debugfs-driver-qat_telemetry b/Documentation/ABI/testing/debugfs-driver-qat_telemetry
new file mode 100644
index 000000000000..06097ee0f154
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-driver-qat_telemetry
@@ -0,0 +1,259 @@
+What: /sys/kernel/debug/qat_<device>_<BDF>/telemetry/control
+Date: March 2024
+KernelVersion: 6.8
+Contact: qat-linux@intel.com
+Description: (RW) Enables/disables the reporting of telemetry metrics.
+
+ Allowed values to write:
+ ========================
+ * 0: disable telemetry
+ * 1: enable telemetry
+ * 2, 3, 4: enable telemetry and calculate minimum, maximum
+ and average for each counter over 2, 3 or 4 samples
+
+ Returned values:
+ ================
+ * 1-4: telemetry is enabled and running
+ * 0: telemetry is disabled
+
+ Example.
+
+ Writing '3' to this file starts the collection of
+ telemetry metrics. Samples are collected every second and
+ stored in a circular buffer of size 3. These values are then
+ used to calculate the minimum, maximum and average for each
+ counter. After enabling, counters can be retrieved through
+ the ``device_data`` file::
+
+ echo 3 > /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/control
+
+ Writing '0' to this file stops the collection of telemetry
+ metrics::
+
+ echo 0 > /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/control
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/telemetry/device_data
+Date: March 2024
+KernelVersion: 6.8
+Contact: qat-linux@intel.com
+Description: (RO) Reports device telemetry counters.
+ Reads report metrics about performance and utilization of
+ a QAT device:
+
+ ======================= ========================================
+ Field Description
+ ======================= ========================================
+ sample_cnt number of acquisitions of telemetry data
+ from the device. Reads are performed
+ every 1000 ms.
+ pci_trans_cnt number of PCIe partial transactions
+ max_rd_lat maximum logged read latency [ns] (could
+ be any read operation)
+ rd_lat_acc_avg average read latency [ns]
+ max_gp_lat max get to put latency [ns] (only takes
+ samples for AE0)
+ gp_lat_acc_avg average get to put latency [ns]
+ bw_in PCIe, write bandwidth [Mbps]
+ bw_out PCIe, read bandwidth [Mbps]
+ re_acc_avg average ring empty time [ns]
+ at_page_req_lat_avg Address Translator(AT), average page
+ request latency [ns]
+ at_trans_lat_avg AT, average page translation latency [ns]
+ at_max_tlb_used AT, maximum uTLB used
+ util_cpr<N> utilization of Compression slice N [%]
+ exec_cpr<N> execution count of Compression slice N
+ util_xlt<N> utilization of Translator slice N [%]
+ exec_xlt<N> execution count of Translator slice N
+ util_dcpr<N> utilization of Decompression slice N [%]
+ exec_dcpr<N> execution count of Decompression slice N
+ util_cnv<N> utilization of Compression and verify slice N [%]
+ exec_cnv<N> execution count of Compression and verify slice N
+ util_dcprz<N> utilization of Decompression slice N [%]
+ exec_dcprz<N> execution count of Decompression slice N
+ util_pke<N> utilization of PKE N [%]
+ exec_pke<N> execution count of PKE N
+ util_ucs<N> utilization of UCS slice N [%]
+ exec_ucs<N> execution count of UCS slice N
+ util_wat<N> utilization of Wireless Authentication
+ slice N [%]
+ exec_wat<N> execution count of Wireless Authentication
+ slice N
+ util_wcp<N> utilization of Wireless Cipher slice N [%]
+ exec_wcp<N> execution count of Wireless Cipher slice N
+ util_cph<N> utilization of Cipher slice N [%]
+ exec_cph<N> execution count of Cipher slice N
+ util_ath<N> utilization of Authentication slice N [%]
+ exec_ath<N> execution count of Authentication slice N
+ cmdq_wait_cnv<N> wait time for cmdq N to get Compression and verify
+ slice ownership
+ cmdq_exec_cnv<N> Compression and verify slice execution time while
+ owned by cmdq N
+ cmdq_drain_cnv<N> time taken for cmdq N to release Compression and
+ verify slice ownership
+ cmdq_wait_dcprz<N> wait time for cmdq N to get Decompression
+ slice N ownership
+ cmdq_exec_dcprz<N> Decompression slice execution time while
+ owned by cmdq N
+ cmdq_drain_dcprz<N> time taken for cmdq N to release Decompression
+ slice ownership
+ cmdq_wait_pke<N> wait time for cmdq N to get PKE slice ownership
+ cmdq_exec_pke<N> PKE slice execution time while owned by cmdq N
+ cmdq_drain_pke<N> time taken for cmdq N to release PKE slice
+ ownership
+ cmdq_wait_ucs<N> wait time for cmdq N to get UCS slice ownership
+ cmdq_exec_ucs<N> UCS slice execution time while owned by cmdq N
+ cmdq_drain_ucs<N> time taken for cmdq N to release UCS slice
+ ownership
+ cmdq_wait_ath<N> wait time for cmdq N to get Authentication slice
+ ownership
+ cmdq_exec_ath<N> Authentication slice execution time while owned
+ by cmdq N
+ cmdq_drain_ath<N> time taken for cmdq N to release Authentication
+ slice ownership
+ ======================= ========================================
+
+ The telemetry report file can be read with the following command::
+
+ cat /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/device_data
+
+ If ``control`` is set to 1, only the current values of the
+ counters are displayed::
+
+ <counter_name> <current>
+
+ If ``control`` is 2, 3 or 4, counters are displayed in the
+ following format::
+
+ <counter_name> <current> <min> <max> <avg>
+
+ If a device lacks of a specific accelerator, the corresponding
+ attribute is not reported.
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/kernel/debug/qat_<device>_<BDF>/telemetry/rp_<A/B/C/D>_data
+Date: March 2024
+KernelVersion: 6.8
+Contact: qat-linux@intel.com
+Description: (RW) Selects up to 4 Ring Pairs (RP) to monitor, one per file,
+ and report telemetry counters related to each.
+
+ Allowed values to write:
+ ========================
+ * 0 to ``<num_rps - 1>``:
+ Ring pair to be monitored. The value of ``num_rps`` can be
+ retrieved through ``/sys/bus/pci/devices/<BDF>/qat/num_rps``.
+ See Documentation/ABI/testing/sysfs-driver-qat.
+
+ Reads report metrics about performance and utilization of
+ the selected RP:
+
+ ======================= ========================================
+ Field Description
+ ======================= ========================================
+ sample_cnt number of acquisitions of telemetry data
+ from the device. Reads are performed
+ every 1000 ms
+ rp_num RP number associated with slot <A/B/C/D>
+ service_type service associated to the RP
+ pci_trans_cnt number of PCIe partial transactions
+ gp_lat_acc_avg average get to put latency [ns]
+ bw_in PCIe, write bandwidth [Mbps]
+ bw_out PCIe, read bandwidth [Mbps]
+ at_glob_devtlb_hit Message descriptor DevTLB hit rate
+ at_glob_devtlb_miss Message descriptor DevTLB miss rate
+ tl_at_payld_devtlb_hit Payload DevTLB hit rate
+ tl_at_payld_devtlb_miss Payload DevTLB miss rate
+ ======================= ========================================
+
+ Example.
+
+ Writing the value '32' to the file ``rp_C_data`` starts the
+ collection of telemetry metrics for ring pair 32::
+
+ echo 32 > /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/rp_C_data
+
+ Once a ring pair is selected, statistics can be read accessing
+ the file::
+
+ cat /sys/kernel/debug/qat_4xxx_0000:6b:00.0/telemetry/rp_C_data
+
+ If ``control`` is set to 1, only the current values of the
+ counters are displayed::
+
+ <counter_name> <current>
+
+ If ``control`` is 2, 3 or 4, counters are displayed in the
+ following format::
+
+ <counter_name> <current> <min> <max> <avg>
+
+
+ On QAT GEN4 devices there are 64 RPs on a PF, so the allowed
+ values are 0..63. This number is absolute to the device.
+ If Virtual Functions (VF) are used, the ring pair number can
+ be derived from the Bus, Device, Function of the VF:
+
+ ============ ====== ====== ====== ======
+ PCI BDF/VF RP0 RP1 RP2 RP3
+ ============ ====== ====== ====== ======
+ 0000:6b:0.1 RP 0 RP 1 RP 2 RP 3
+ 0000:6b:0.2 RP 4 RP 5 RP 6 RP 7
+ 0000:6b:0.3 RP 8 RP 9 RP 10 RP 11
+ 0000:6b:0.4 RP 12 RP 13 RP 14 RP 15
+ 0000:6b:0.5 RP 16 RP 17 RP 18 RP 19
+ 0000:6b:0.6 RP 20 RP 21 RP 22 RP 23
+ 0000:6b:0.7 RP 24 RP 25 RP 26 RP 27
+ 0000:6b:1.0 RP 28 RP 29 RP 30 RP 31
+ 0000:6b:1.1 RP 32 RP 33 RP 34 RP 35
+ 0000:6b:1.2 RP 36 RP 37 RP 38 RP 39
+ 0000:6b:1.3 RP 40 RP 41 RP 42 RP 43
+ 0000:6b:1.4 RP 44 RP 45 RP 46 RP 47
+ 0000:6b:1.5 RP 48 RP 49 RP 50 RP 51
+ 0000:6b:1.6 RP 52 RP 53 RP 54 RP 55
+ 0000:6b:1.7 RP 56 RP 57 RP 58 RP 59
+ 0000:6b:2.0 RP 60 RP 61 RP 62 RP 63
+ ============ ====== ====== ====== ======
+
+ The mapping is only valid for the BDFs of VFs on the host.
+
+
+ The service provided on a ring-pair varies depending on the
+ configuration. The configuration for a given device can be
+ queried and set using ``cfg_services``.
+ See Documentation/ABI/testing/sysfs-driver-qat for details.
+
+ The following table reports how ring pairs are mapped to VFs
+ on the PF 0000:6b:0.0 configured for `sym;asym` or `asym;sym`:
+
+ =========== ============ =========== ============ ===========
+ PCI BDF/VF RP0/service RP1/service RP2/service RP3/service
+ =========== ============ =========== ============ ===========
+ 0000:6b:0.1 RP 0 asym RP 1 sym RP 2 asym RP 3 sym
+ 0000:6b:0.2 RP 4 asym RP 5 sym RP 6 asym RP 7 sym
+ 0000:6b:0.3 RP 8 asym RP 9 sym RP10 asym RP11 sym
+ ... ... ... ... ...
+ =========== ============ =========== ============ ===========
+
+ All VFs follow the same pattern.
+
+
+ The following table reports how ring pairs are mapped to VFs on
+ the PF 0000:6b:0.0 configured for `dc`:
+
+ =========== ============ =========== ============ ===========
+ PCI BDF/VF RP0/service RP1/service RP2/service RP3/service
+ =========== ============ =========== ============ ===========
+ 0000:6b:0.1 RP 0 dc RP 1 dc RP 2 dc RP 3 dc
+ 0000:6b:0.2 RP 4 dc RP 5 dc RP 6 dc RP 7 dc
+ 0000:6b:0.3 RP 8 dc RP 9 dc RP10 dc RP11 dc
+ ... ... ... ... ...
+ =========== ============ =========== ============ ===========
+
+ The mapping of a RP to a service can be retrieved using
+ ``rp2srv`` from sysfs.
+ See Documentation/ABI/testing/sysfs-driver-qat for details.
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
diff --git a/Documentation/ABI/testing/debugfs-dwc-pcie b/Documentation/ABI/testing/debugfs-dwc-pcie
new file mode 100644
index 000000000000..92b76f52a408
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-dwc-pcie
@@ -0,0 +1,157 @@
+What: /sys/kernel/debug/dwc_pcie_<dev>/rasdes_debug/lane_detect
+Date: February 2025
+Contact: Shradha Todi <shradha.t@samsung.com>
+Description: (RW) Write the lane number to be checked for detection. Read
+ will return whether PHY indicates receiver detection on the
+ selected lane. The default selected lane is Lane0.
+
+What: /sys/kernel/debug/dwc_pcie_<dev>/rasdes_debug/rx_valid
+Date: February 2025
+Contact: Shradha Todi <shradha.t@samsung.com>
+Description: (RW) Write the lane number to be checked as valid or invalid.
+ Read will return the status of PIPE RXVALID signal of the
+ selected lane. The default selected lane is Lane0.
+
+What: /sys/kernel/debug/dwc_pcie_<dev>/rasdes_err_inj/<error>
+Date: February 2025
+Contact: Shradha Todi <shradha.t@samsung.com>
+Description: The "rasdes_err_inj" is a directory which can be used to inject
+ errors into the system. The possible errors that can be injected
+ are:
+
+ 1) tx_lcrc - TLP LCRC error injection TX Path
+ 2) b16_crc_dllp - 16b CRC error injection of ACK/NAK DLLP
+ 3) b16_crc_upd_fc - 16b CRC error injection of Update-FC DLLP
+ 4) tx_ecrc - TLP ECRC error injection TX Path
+ 5) fcrc_tlp - TLP's FCRC error injection TX Path
+ 6) parity_tsos - Parity error of TSOS
+ 7) parity_skpos - Parity error on SKPOS
+ 8) rx_lcrc - LCRC error injection RX Path
+ 9) rx_ecrc - ECRC error injection RX Path
+ 10) tlp_err_seq - TLPs SEQ# error
+ 11) ack_nak_dllp_seq - DLLPS ACK/NAK SEQ# error
+ 12) ack_nak_dllp - ACK/NAK DLLPs transmission block
+ 13) upd_fc_dllp - UpdateFC DLLPs transmission block
+ 14) nak_dllp - Always transmission for NAK DLLP
+ 15) inv_sync_hdr_sym - Invert SYNC header
+ 16) com_pad_ts1 - COM/PAD TS1 order set
+ 17) com_pad_ts2 - COM/PAD TS2 order set
+ 18) com_fts - COM/FTS FTS order set
+ 19) com_idl - COM/IDL E-idle order set
+ 20) end_edb - END/EDB symbol
+ 21) stp_sdp - STP/SDP symbol
+ 22) com_skp - COM/SKP SKP order set
+ 23) posted_tlp_hdr - Posted TLP Header credit value control
+ 24) non_post_tlp_hdr - Non-Posted TLP Header credit value control
+ 25) cmpl_tlp_hdr - Completion TLP Header credit value control
+ 26) posted_tlp_data - Posted TLP Data credit value control
+ 27) non_post_tlp_data - Non-Posted TLP Data credit value control
+ 28) cmpl_tlp_data - Completion TLP Data credit value control
+ 29) duplicate_tlp - Generates duplicate TLPs
+ 30) nullified_tlp - Generates Nullified TLPs
+
+ (WO) Write to the attribute will prepare controller to inject
+ the respective error in the next transmission of data.
+
+ Parameter required to write will change in the following ways:
+
+ - Errors 9 and 10 are sequence errors. The write command:
+
+ echo <count> <diff> > /sys/kernel/debug/dwc_pcie_<dev>/rasdes_err_inj/<error>
+
+ <count>
+ Number of errors to be injected
+ <diff>
+ The difference to add or subtract from natural
+ sequence number to generate sequence error.
+ Allowed range from -4095 to 4095
+
+ - Errors 23 to 28 are credit value error insertions. The write
+ command:
+
+ echo <count> <diff> <vc> > /sys/kernel/debug/dwc_pcie_<dev>/rasdes_err_inj/<error>
+
+ <count>
+ Number of errors to be injected
+ <diff>
+ The difference to add or subtract from UpdateFC
+ credit value. Allowed range from -4095 to 4095
+ <vc>
+ Target VC number
+
+ - All other errors. The write command:
+
+ echo <count> > /sys/kernel/debug/dwc_pcie_<dev>/rasdes_err_inj/<error>
+
+ <count>
+ Number of errors to be injected
+
+What: /sys/kernel/debug/dwc_pcie_<dev>/rasdes_event_counters/<event>/counter_enable
+Date: February 2025
+Contact: Shradha Todi <shradha.t@samsung.com>
+Description: The "rasdes_event_counters" is the directory which can be used
+ to collect statistical data about the number of times a certain
+ event has occurred in the controller. The list of possible
+ events are:
+
+ 1) EBUF Overflow
+ 2) EBUF Underrun
+ 3) Decode Error
+ 4) Running Disparity Error
+ 5) SKP OS Parity Error
+ 6) SYNC Header Error
+ 7) Rx Valid De-assertion
+ 8) CTL SKP OS Parity Error
+ 9) 1st Retimer Parity Error
+ 10) 2nd Retimer Parity Error
+ 11) Margin CRC and Parity Error
+ 12) Detect EI Infer
+ 13) Receiver Error
+ 14) RX Recovery Req
+ 15) N_FTS Timeout
+ 16) Framing Error
+ 17) Deskew Error
+ 18) Framing Error In L0
+ 19) Deskew Uncompleted Error
+ 20) Bad TLP
+ 21) LCRC Error
+ 22) Bad DLLP
+ 23) Replay Number Rollover
+ 24) Replay Timeout
+ 25) Rx Nak DLLP
+ 26) Tx Nak DLLP
+ 27) Retry TLP
+ 28) FC Timeout
+ 29) Poisoned TLP
+ 30) ECRC Error
+ 31) Unsupported Request
+ 32) Completer Abort
+ 33) Completion Timeout
+ 34) EBUF SKP Add
+ 35) EBUF SKP Del
+
+ (RW) Write 1 to enable the event counter and write 0 to disable
+ the event counter. Read will return whether the counter is
+ currently enabled or disabled. Counter is disabled by default.
+
+What: /sys/kernel/debug/dwc_pcie_<dev>/rasdes_event_counters/<event>/counter_value
+Date: February 2025
+Contact: Shradha Todi <shradha.t@samsung.com>
+Description: (RO) Read will return the current value of the event counter.
+ To reset the counter, counter should be disabled first and then
+ enabled back using the "counter_enable" attribute.
+
+What: /sys/kernel/debug/dwc_pcie_<dev>/rasdes_event_counters/<event>/lane_select
+Date: February 2025
+Contact: Shradha Todi <shradha.t@samsung.com>
+Description: (RW) Some lanes in the event list are lane specific events.
+ These include events from 1 to 11, as well as, 34 and 35. Write
+ the lane number for which you wish the counter to be enabled,
+ disabled, or value dumped. Read will return the current
+ selected lane number. Lane0 is selected by default.
+
+What: /sys/kernel/debug/dwc_pcie_<dev>/ltssm_status
+Date: February 2025
+Contact: Hans Zhang <18255117159@163.com>
+Description: (RO) Read will return the current PCIe LTSSM state in both
+ string and raw value.
diff --git a/Documentation/ABI/testing/debugfs-ec b/Documentation/ABI/testing/debugfs-ec
index 6546115a94da..ab6099daa8f5 100644
--- a/Documentation/ABI/testing/debugfs-ec
+++ b/Documentation/ABI/testing/debugfs-ec
@@ -6,7 +6,7 @@ Description:
General information like which GPE is assigned to the EC and whether
the global lock should get used.
Knowing the EC GPE one can watch the amount of HW events related to
-the EC here (XY -> GPE number from /sys/kernel/debug/ec/*/gpe):
+the EC here (XY -> GPE number from `/sys/kernel/debug/ec/*/gpe`):
/sys/firmware/acpi/interrupts/gpeXY
The io file is binary and a userspace tool located here:
@@ -14,7 +14,8 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec/
should get used to read out the 256 Embedded Controller registers
or writing to them.
-CAUTION: Do not write to the Embedded Controller if you don't know
-what you are doing! Rebooting afterwards also is a good idea.
-This can influence the way your machine is cooled and fans may
-not get switched on again after you did a wrong write.
+CAUTION:
+ Do not write to the Embedded Controller if you don't know
+ what you are doing! Rebooting afterwards also is a good idea.
+ This can influence the way your machine is cooled and fans may
+ not get switched on again after you did a wrong write.
diff --git a/Documentation/ABI/testing/debugfs-hisi-hpre b/Documentation/ABI/testing/debugfs-hisi-hpre
new file mode 100644
index 000000000000..29fb7d5ffc69
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-hisi-hpre
@@ -0,0 +1,193 @@
+What: /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/regs
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Dump debug registers from the HPRE cluster.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/cluster[0-3]/cluster_ctrl
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Write the HPRE core selection in the cluster into this file,
+ and then we can read the debug information of the core.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/rdclr_en
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: HPRE cores debug registers read clear control. 1 means enable
+ register read clear, otherwise 0. Writing to this file has no
+ functional effect, only enable or disable counters clear after
+ reading of these registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/current_qm
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: One HPRE controller has one PF and multiple VFs, each function
+ has a QM. Select the QM which below qm refers to.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/alg_qos
+Date: Jun 2021
+Contact: linux-crypto@vger.kernel.org
+Description: The <bdf> is related the function for PF and VF.
+ HPRE driver supports to configure each function's QoS, the driver
+ supports to write <bdf> value to alg_qos in the host. Such as
+ "echo <bdf> value > alg_qos". The qos value is 1~1000, means
+ 1/1000~1000/1000 of total QoS. The driver reading alg_qos to
+ get related QoS in the host and VM, Such as "cat alg_qos".
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/regs
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Dump debug registers from the HPRE.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/regs
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Dump debug registers from the QM.
+ Available for PF and VF in host. VF in guest currently only
+ has one debug register.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/current_q
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: One QM may contain multiple queues. Select specific queue to
+ show its debug registers in above regs.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/clear_enable
+Date: Sep 2019
+Contact: linux-crypto@vger.kernel.org
+Description: QM debug registers(regs) read clear control. 1 means enable
+ register read clear, otherwise 0.
+ Writing to this file has no functional effect, only enable or
+ disable counters clear after reading of these registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/err_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of invalid interrupts for
+ QM task completion.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/aeq_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of QM async event queue interrupts.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/abnormal_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of interrupts for QM abnormal event.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/create_qp_err
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of queue allocation errors.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/mb_err
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of failed QM mailbox commands.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/status
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the status of the QM.
+ Two states: work, stop.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/diff_regs
+Date: Mar 2022
+Contact: linux-crypto@vger.kernel.org
+Description: QM debug registers(regs) read hardware register value. This
+ node is used to show the change of the qm register values. This
+ node can be help users to check the change of register values.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/qm_state
+Date: Jan 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the state of the device.
+ 0: busy, 1: idle.
+ Only available for PF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/dev_timeout
+Date: Feb 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Set the wait time when stop queue fails. Available for both PF
+ and VF, and take no other effect on HPRE.
+ 0: not wait(default), others value: wait dev_timeout * 20 microsecond.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/qm/dev_state
+Date: Feb 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the stop queue status of the QM. The default value is 0,
+ if dev_timeout is set, when stop queue fails, the dev_state
+ will return non-zero value. Available for both PF and VF,
+ and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/diff_regs
+Date: Mar 2022
+Contact: linux-crypto@vger.kernel.org
+Description: HPRE debug registers(regs) read hardware register value. This
+ node is used to show the change of the register values. This
+ node can be help users to check the change of register values.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of sent requests.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/recv_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of received requests.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_busy_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of requests sent
+ with returning busy.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/send_fail_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of completed but error requests.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/invalid_req_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of invalid requests being received.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/overtime_thrhld
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Set the threshold time for counting the request which is
+ processed longer than the threshold.
+ 0: disable(default), 1: 1 microsecond.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/hpre_dfx/over_thrhld_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of time out requests.
+ Available for both PF and VF, and take no other effect on HPRE.
+
+What: /sys/kernel/debug/hisi_hpre/<bdf>/cap_regs
+Date: Oct 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the values of the qm and hpre capability bit registers and
+ support the query of device specifications to facilitate fault locating.
+ Available for both PF and VF, and take no other effect on HPRE.
diff --git a/Documentation/ABI/testing/debugfs-hisi-migration b/Documentation/ABI/testing/debugfs-hisi-migration
new file mode 100644
index 000000000000..2c01b2d387dd
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-hisi-migration
@@ -0,0 +1,25 @@
+What: /sys/kernel/debug/vfio/<device>/migration/hisi_acc/dev_data
+Date: Jan 2025
+KernelVersion: 6.13
+Contact: Longfang Liu <liulongfang@huawei.com>
+Description: Read the configuration data and some status data
+ required for device live migration. These data include device
+ status data, queue configuration data, some task configuration
+ data and device attribute data. The output format of the data
+ is defined by the live migration driver.
+
+What: /sys/kernel/debug/vfio/<device>/migration/hisi_acc/migf_data
+Date: Jan 2025
+KernelVersion: 6.13
+Contact: Longfang Liu <liulongfang@huawei.com>
+Description: Read the data from the last completed live migration.
+ This data includes the same device status data as in "dev_data".
+ The migf_data is the dev_data that is migrated.
+
+What: /sys/kernel/debug/vfio/<device>/migration/hisi_acc/cmd_state
+Date: Jan 2025
+KernelVersion: 6.13
+Contact: Longfang Liu <liulongfang@huawei.com>
+Description: Used to obtain the device command sending and receiving
+ channel status. Returns failure or success logs based on the
+ results.
diff --git a/Documentation/ABI/testing/debugfs-hisi-sec b/Documentation/ABI/testing/debugfs-hisi-sec
new file mode 100644
index 000000000000..82bf4a0dc7f7
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-hisi-sec
@@ -0,0 +1,166 @@
+What: /sys/kernel/debug/hisi_sec2/<bdf>/clear_enable
+Date: Oct 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Enabling/disabling of clear action after reading
+ the SEC debug registers.
+ 0: disable, 1: enable.
+ Only available for PF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/current_qm
+Date: Oct 2019
+Contact: linux-crypto@vger.kernel.org
+Description: One SEC controller has one PF and multiple VFs, each function
+ has a QM. This file can be used to select the QM which below
+ qm refers to.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/alg_qos
+Date: Jun 2021
+Contact: linux-crypto@vger.kernel.org
+Description: The <bdf> is related the function for PF and VF.
+ SEC driver supports to configure each function's QoS, the driver
+ supports to write <bdf> value to alg_qos in the host. Such as
+ "echo <bdf> value > alg_qos". The qos value is 1~1000, means
+ 1/1000~1000/1000 of total QoS. The driver reading alg_qos to
+ get related QoS in the host and VM, Such as "cat alg_qos".
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/qm_regs
+Date: Oct 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of QM related debug registers.
+ Available for PF and VF in host. VF in guest currently only
+ has one debug register.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/current_q
+Date: Oct 2019
+Contact: linux-crypto@vger.kernel.org
+Description: One QM of SEC may contain multiple queues. Select specific
+ queue to show its debug registers in above 'regs'.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/clear_enable
+Date: Oct 2019
+Contact: linux-crypto@vger.kernel.org
+Description: Enabling/disabling of clear action after reading
+ the SEC's QM debug registers.
+ 0: disable, 1: enable.
+ Only available for PF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/err_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of invalid interrupts for
+ QM task completion.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/aeq_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of QM async event queue interrupts.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/abnormal_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of interrupts for QM abnormal event.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/create_qp_err
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of queue allocation errors.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/mb_err
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of failed QM mailbox commands.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/status
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the status of the QM.
+ Two states: work, stop.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/diff_regs
+Date: Mar 2022
+Contact: linux-crypto@vger.kernel.org
+Description: QM debug registers(regs) read hardware register value. This
+ node is used to show the change of the qm register values. This
+ node can be help users to check the change of register values.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/qm_state
+Date: Jan 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the state of the device.
+ 0: busy, 1: idle.
+ Only available for PF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/dev_timeout
+Date: Feb 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Set the wait time when stop queue fails. Available for both PF
+ and VF, and take no other effect on SEC.
+ 0: not wait(default), others value: wait dev_timeout * 20 microsecond.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/qm/dev_state
+Date: Feb 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the stop queue status of the QM. The default value is 0,
+ if dev_timeout is set, when stop queue fails, the dev_state
+ will return non-zero value. Available for both PF and VF,
+ and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/diff_regs
+Date: Mar 2022
+Contact: linux-crypto@vger.kernel.org
+Description: SEC debug registers(regs) read hardware register value. This
+ node is used to show the change of the register values. This
+ node can be help users to check the change of register values.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/send_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of sent requests.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/recv_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of received requests.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/send_busy_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of requests sent with returning busy.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/err_bd_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of BD type error requests
+ to be received.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/invalid_req_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of invalid requests being received.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/sec_dfx/done_flag_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of completed but marked error requests
+ to be received.
+ Available for both PF and VF, and take no other effect on SEC.
+
+What: /sys/kernel/debug/hisi_sec2/<bdf>/cap_regs
+Date: Oct 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the values of the qm and sec capability bit registers and
+ support the query of device specifications to facilitate fault locating.
+ Available for both PF and VF, and take no other effect on SEC.
diff --git a/Documentation/ABI/testing/debugfs-hisi-zip b/Documentation/ABI/testing/debugfs-hisi-zip
new file mode 100644
index 000000000000..0abd65d27e9b
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-hisi-zip
@@ -0,0 +1,167 @@
+What: /sys/kernel/debug/hisi_zip/<bdf>/comp_core[01]/regs
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of compression cores related debug registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/decomp_core[0-5]/regs
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of decompression cores related debug registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/clear_enable
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Compression/decompression core debug registers read clear
+ control. 1 means enable register read clear, otherwise 0.
+ Writing to this file has no functional effect, only enable or
+ disable counters clear after reading of these registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/current_qm
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: One ZIP controller has one PF and multiple VFs, each function
+ has a QM. Select the QM which below qm refers to.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/alg_qos
+Date: Jun 2021
+Contact: linux-crypto@vger.kernel.org
+Description: The <bdf> is related the function for PF and VF.
+ ZIP driver supports to configure each function's QoS, the driver
+ supports to write <bdf> value to alg_qos in the host. Such as
+ "echo <bdf> value > alg_qos". The qos value is 1~1000, means
+ 1/1000~1000/1000 of total QoS. The driver reading alg_qos to
+ get related QoS in the host and VM, Such as "cat alg_qos".
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/regs
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: Dump of QM related debug registers.
+ Available for PF and VF in host. VF in guest currently only
+ has one debug register.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/current_q
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: One QM may contain multiple queues. Select specific queue to
+ show its debug registers in above regs.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/clear_enable
+Date: Nov 2018
+Contact: linux-crypto@vger.kernel.org
+Description: QM debug registers(regs) read clear control. 1 means enable
+ register read clear, otherwise 0.
+ Writing to this file has no functional effect, only enable or
+ disable counters clear after reading of these registers.
+ Only available for PF.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/err_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of invalid interrupts for
+ QM task completion.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/aeq_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of QM async event queue interrupts.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/abnormal_irq
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of interrupts for QM abnormal event.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/create_qp_err
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of queue allocation errors.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/mb_err
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the number of failed QM mailbox commands.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/status
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the status of the QM.
+ Two states: work, stop.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/diff_regs
+Date: Mar 2022
+Contact: linux-crypto@vger.kernel.org
+Description: QM debug registers(regs) read hardware register value. This
+ node is used to show the change of the qm registers value. This
+ node can be help users to check the change of register values.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/qm_state
+Date: Jan 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the state of the device.
+ 0: busy, 1: idle.
+ Only available for PF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/dev_timeout
+Date: Feb 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Set the wait time when stop queue fails. Available for both PF
+ and VF, and take no other effect on ZIP.
+ 0: not wait(default), others value: wait dev_timeout * 20 microsecond.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/qm/dev_state
+Date: Feb 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the stop queue status of the QM. The default value is 0,
+ if dev_timeout is set, when stop queue fails, the dev_state
+ will return non-zero value. Available for both PF and VF,
+ and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/diff_regs
+Date: Mar 2022
+Contact: linux-crypto@vger.kernel.org
+Description: ZIP debug registers(regs) read hardware register value. This
+ node is used to show the change of the registers value. this
+ node can be help users to check the change of register values.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/send_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of sent requests.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/recv_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of received requests.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/send_busy_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of requests received
+ with returning busy.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/zip_dfx/err_bd_cnt
+Date: Apr 2020
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the total number of BD type error requests
+ to be received.
+ Available for both PF and VF, and take no other effect on ZIP.
+
+What: /sys/kernel/debug/hisi_zip/<bdf>/cap_regs
+Date: Oct 2024
+Contact: linux-crypto@vger.kernel.org
+Description: Dump the values of the qm and zip capability bit registers and
+ support the query of device specifications to facilitate fault locating.
+ Available for both PF and VF, and take no other effect on ZIP.
diff --git a/Documentation/ABI/testing/debugfs-hyperv b/Documentation/ABI/testing/debugfs-hyperv
new file mode 100644
index 000000000000..9185e1b06bba
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-hyperv
@@ -0,0 +1,23 @@
+What: /sys/kernel/debug/hyperv/<UUID>/fuzz_test_state
+Date: October 2019
+KernelVersion: 5.5
+Contact: Branden Bonaby <brandonbonaby94@gmail.com>
+Description: Fuzz testing status of a vmbus device, whether its in an ON
+ state or a OFF state
+Users: Debugging tools
+
+What: /sys/kernel/debug/hyperv/<UUID>/delay/fuzz_test_buffer_interrupt_delay
+Date: October 2019
+KernelVersion: 5.5
+Contact: Branden Bonaby <brandonbonaby94@gmail.com>
+Description: Fuzz testing buffer interrupt delay value between 0 - 1000
+ microseconds (inclusive).
+Users: Debugging tools
+
+What: /sys/kernel/debug/hyperv/<UUID>/delay/fuzz_test_message_delay
+Date: October 2019
+KernelVersion: 5.5
+Contact: Branden Bonaby <brandonbonaby94@gmail.com>
+Description: Fuzz testing message delay value between 0 - 1000 microseconds
+ (inclusive).
+Users: Debugging tools
diff --git a/Documentation/ABI/testing/debugfs-iio-ad9467 b/Documentation/ABI/testing/debugfs-iio-ad9467
new file mode 100644
index 000000000000..0352fca1f7f2
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-iio-ad9467
@@ -0,0 +1,39 @@
+What: /sys/kernel/debug/iio/iio:deviceX/calibration_table_dump
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ This dumps the calibration table that was filled during the
+ digital interface tuning process.
+
+What: /sys/kernel/debug/iio/iio:deviceX/in_voltage_test_mode_available
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ List all the available test tones:
+ - off
+ - midscale_short
+ - pos_fullscale
+ - neg_fullscale
+ - checkerboard
+ - prbs23
+ - prbs9
+ - one_zero_toggle
+ - user
+ - bit_toggle
+ - sync
+ - one_bit_high
+ - mixed_bit_frequency
+ - ramp
+
+ Note that depending on the actual device being used, some of the
+ above might not be available (and they won't be listed when
+ reading the file).
+
+What: /sys/kernel/debug/iio/iio:deviceX/in_voltageY_test_mode
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ Writing to this file will initiate one of available test tone on
+ channel Y. Reading it, shows which test is running. In cases
+ where an IIO backend is available and supports the test tone,
+ additional information about the data correctness is given.
diff --git a/Documentation/ABI/testing/debugfs-iio-backend b/Documentation/ABI/testing/debugfs-iio-backend
new file mode 100644
index 000000000000..01ab94469432
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-iio-backend
@@ -0,0 +1,20 @@
+What: /sys/kernel/debug/iio/iio:deviceX/backendY/name
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ Name of Backend Y connected to device X.
+
+What: /sys/kernel/debug/iio/iio:deviceX/backendY/direct_reg_access
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ Directly access the registers of backend Y. Typical usage is:
+
+ Reading address 0x50
+ echo 0x50 > direct_reg_access
+ cat direct_reg_access
+
+ Writing address 0x50
+ echo 0x50 0x3 > direct_reg_access
+ //readback address 0x50
+ cat direct_reg_access
diff --git a/Documentation/ABI/testing/debugfs-intel-iommu b/Documentation/ABI/testing/debugfs-intel-iommu
new file mode 100644
index 000000000000..2ab8464504a9
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-intel-iommu
@@ -0,0 +1,276 @@
+What: /sys/kernel/debug/iommu/intel/iommu_regset
+Date: December 2023
+Contact: Jingqi Liu <Jingqi.liu@intel.com>
+Description:
+ This file dumps all the register contents for each IOMMU device.
+
+ Example in Kabylake:
+
+ ::
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/iommu_regset
+
+ IOMMU: dmar0 Register Base Address: 26be37000
+
+ Name Offset Contents
+ VER 0x00 0x0000000000000010
+ GCMD 0x18 0x0000000000000000
+ GSTS 0x1c 0x00000000c7000000
+ FSTS 0x34 0x0000000000000000
+ FECTL 0x38 0x0000000000000000
+
+ [...]
+
+ IOMMU: dmar1 Register Base Address: fed90000
+
+ Name Offset Contents
+ VER 0x00 0x0000000000000010
+ GCMD 0x18 0x0000000000000000
+ GSTS 0x1c 0x00000000c7000000
+ FSTS 0x34 0x0000000000000000
+ FECTL 0x38 0x0000000000000000
+
+ [...]
+
+ IOMMU: dmar2 Register Base Address: fed91000
+
+ Name Offset Contents
+ VER 0x00 0x0000000000000010
+ GCMD 0x18 0x0000000000000000
+ GSTS 0x1c 0x00000000c7000000
+ FSTS 0x34 0x0000000000000000
+ FECTL 0x38 0x0000000000000000
+
+ [...]
+
+What: /sys/kernel/debug/iommu/intel/ir_translation_struct
+Date: December 2023
+Contact: Jingqi Liu <Jingqi.liu@intel.com>
+Description:
+ This file dumps the table entries for Interrupt
+ remapping and Interrupt posting.
+
+ Example in Kabylake:
+
+ ::
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/ir_translation_struct
+
+ Remapped Interrupt supported on IOMMU: dmar0
+ IR table address:100900000
+
+ Entry SrcID DstID Vct IRTE_high IRTE_low
+ 0 00:0a.0 00000080 24 0000000000040050 000000800024000d
+ 1 00:0a.0 00000001 ef 0000000000040050 0000000100ef000d
+
+ Remapped Interrupt supported on IOMMU: dmar1
+ IR table address:100300000
+ Entry SrcID DstID Vct IRTE_high IRTE_low
+ 0 00:02.0 00000002 26 0000000000040010 000000020026000d
+
+ [...]
+
+ ****
+
+ Posted Interrupt supported on IOMMU: dmar0
+ IR table address:100900000
+ Entry SrcID PDA_high PDA_low Vct IRTE_high IRTE_low
+
+What: /sys/kernel/debug/iommu/intel/dmar_translation_struct
+Date: December 2023
+Contact: Jingqi Liu <Jingqi.liu@intel.com>
+Description:
+ This file dumps Intel IOMMU DMA remapping tables, such
+ as root table, context table, PASID directory and PASID
+ table entries in debugfs. For legacy mode, it doesn't
+ support PASID, and hence PASID field is defaulted to
+ '-1' and other PASID related fields are invalid.
+
+ Example in Kabylake:
+
+ ::
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/dmar_translation_struct
+
+ IOMMU dmar1: Root Table Address: 0x103027000
+ B.D.F Root_entry
+ 00:02.0 0x0000000000000000:0x000000010303e001
+
+ Context_entry
+ 0x0000000000000102:0x000000010303f005
+
+ PASID PASID_table_entry
+ -1 0x0000000000000000:0x0000000000000000:0x0000000000000000
+
+ IOMMU dmar0: Root Table Address: 0x103028000
+ B.D.F Root_entry
+ 00:0a.0 0x0000000000000000:0x00000001038a7001
+
+ Context_entry
+ 0x0000000000000000:0x0000000103220e7d
+
+ PASID PASID_table_entry
+ 0 0x0000000000000000:0x0000000000800002:0x00000001038a5089
+
+ [...]
+
+What: /sys/kernel/debug/iommu/intel/invalidation_queue
+Date: December 2023
+Contact: Jingqi Liu <Jingqi.liu@intel.com>
+Description:
+ This file exports invalidation queue internals of each
+ IOMMU device.
+
+ Example in Kabylake:
+
+ ::
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/invalidation_queue
+
+ Invalidation queue on IOMMU: dmar0
+ Base: 0x10022e000 Head: 20 Tail: 20
+ Index qw0 qw1 qw2
+ 0 0000000000000014 0000000000000000 0000000000000000
+ 1 0000000200000025 0000000100059c04 0000000000000000
+ 2 0000000000000014 0000000000000000 0000000000000000
+
+ qw3 status
+ 0000000000000000 0000000000000000
+ 0000000000000000 0000000000000000
+ 0000000000000000 0000000000000000
+
+ [...]
+
+ Invalidation queue on IOMMU: dmar1
+ Base: 0x10026e000 Head: 32 Tail: 32
+ Index qw0 qw1 status
+ 0 0000000000000004 0000000000000000 0000000000000000
+ 1 0000000200000025 0000000100059804 0000000000000000
+ 2 0000000000000011 0000000000000000 0000000000000000
+
+ [...]
+
+What: /sys/kernel/debug/iommu/intel/dmar_perf_latency
+Date: December 2023
+Contact: Jingqi Liu <Jingqi.liu@intel.com>
+Description:
+ This file is used to control and show counts of
+ execution time ranges for various types per DMAR.
+
+ Firstly, write a value to
+ /sys/kernel/debug/iommu/intel/dmar_perf_latency
+ to enable sampling.
+
+ The possible values are as follows:
+
+ * 0 - disable sampling all latency data
+
+ * 1 - enable sampling IOTLB invalidation latency data
+
+ * 2 - enable sampling devTLB invalidation latency data
+
+ * 3 - enable sampling intr entry cache invalidation latency data
+
+ Next, read /sys/kernel/debug/iommu/intel/dmar_perf_latency gives
+ a snapshot of sampling result of all enabled monitors.
+
+ Examples in Kabylake:
+
+ ::
+
+ 1) Disable sampling all latency data:
+
+ $ sudo echo 0 > /sys/kernel/debug/iommu/intel/dmar_perf_latency
+
+ 2) Enable sampling IOTLB invalidation latency data
+
+ $ sudo echo 1 > /sys/kernel/debug/iommu/intel/dmar_perf_latency
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/dmar_perf_latency
+
+ IOMMU: dmar0 Register Base Address: 26be37000
+ <0.1us 0.1us-1us 1us-10us 10us-100us 100us-1ms
+ inv_iotlb 0 0 0 0 0
+
+ 1ms-10ms >=10ms min(us) max(us) average(us)
+ inv_iotlb 0 0 0 0 0
+
+ [...]
+
+ IOMMU: dmar2 Register Base Address: fed91000
+ <0.1us 0.1us-1us 1us-10us 10us-100us 100us-1ms
+ inv_iotlb 0 0 18 0 0
+
+ 1ms-10ms >=10ms min(us) max(us) average(us)
+ inv_iotlb 0 0 2 2 2
+
+ 3) Enable sampling devTLB invalidation latency data
+
+ $ sudo echo 2 > /sys/kernel/debug/iommu/intel/dmar_perf_latency
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/dmar_perf_latency
+
+ IOMMU: dmar0 Register Base Address: 26be37000
+ <0.1us 0.1us-1us 1us-10us 10us-100us 100us-1ms
+ inv_devtlb 0 0 0 0 0
+
+ >=10ms min(us) max(us) average(us)
+ inv_devtlb 0 0 0 0
+
+ [...]
+
+What: /sys/kernel/debug/iommu/intel/<bdf>/domain_translation_struct
+Date: December 2023
+Contact: Jingqi Liu <Jingqi.liu@intel.com>
+Description:
+ This file dumps a specified page table of Intel IOMMU
+ in legacy mode or scalable mode.
+
+ For a device that only supports legacy mode, dump its
+ page table by the debugfs file in the debugfs device
+ directory. e.g.
+ /sys/kernel/debug/iommu/intel/0000:00:02.0/domain_translation_struct.
+
+ For a device that supports scalable mode, dump the
+ page table of specified pasid by the debugfs file in
+ the debugfs pasid directory. e.g.
+ /sys/kernel/debug/iommu/intel/0000:00:02.0/1/domain_translation_struct.
+
+ Examples in Kabylake:
+
+ ::
+
+ 1) Dump the page table of device "0000:00:02.0" that only supports legacy mode.
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/0000:00:02.0/domain_translation_struct
+
+ Device 0000:00:02.0 @0x1017f8000
+ IOVA_PFN PML5E PML4E
+ 0x000000008d800 | 0x0000000000000000 0x00000001017f9003
+ 0x000000008d801 | 0x0000000000000000 0x00000001017f9003
+ 0x000000008d802 | 0x0000000000000000 0x00000001017f9003
+
+ PDPE PDE PTE
+ 0x00000001017fa003 0x00000001017fb003 0x000000008d800003
+ 0x00000001017fa003 0x00000001017fb003 0x000000008d801003
+ 0x00000001017fa003 0x00000001017fb003 0x000000008d802003
+
+ [...]
+
+ 2) Dump the page table of device "0000:00:0a.0" with PASID "1" that
+ supports scalable mode.
+
+ $ sudo cat /sys/kernel/debug/iommu/intel/0000:00:0a.0/1/domain_translation_struct
+
+ Device 0000:00:0a.0 with pasid 1 @0x10c112000
+ IOVA_PFN PML5E PML4E
+ 0x0000000000000 | 0x0000000000000000 0x000000010df93003
+ 0x0000000000001 | 0x0000000000000000 0x000000010df93003
+ 0x0000000000002 | 0x0000000000000000 0x000000010df93003
+
+ PDPE PDE PTE
+ 0x0000000106ae6003 0x0000000104b38003 0x0000000147c00803
+ 0x0000000106ae6003 0x0000000104b38003 0x0000000147c01803
+ 0x0000000106ae6003 0x0000000104b38003 0x0000000147c02803
+
+ [...]
diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
new file mode 100644
index 000000000000..637d8587d03d
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-moxtet
@@ -0,0 +1,35 @@
+What: /sys/kernel/debug/moxtet/input
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) Read input from the shift registers, in hexadecimal.
+ Returns N+1 bytes, where N is the number of Moxtet connected
+ modules. The first byte is from the CPU board itself.
+
+ Example::
+
+ 101214
+
+ == =======================================
+ 10 CPU board with SD card
+ 12 2 = PCIe module, 1 = IRQ not active
+ 14 4 = Peridot module, 1 = IRQ not active
+ == =======================================
+
+What: /sys/kernel/debug/moxtet/output
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RW) Read last written value to the shift registers, in
+ hexadecimal, or write values to the shift registers, also
+ in hexadecimal.
+
+ Example::
+
+ 0102
+
+ == ================================================
+ 01 01 was last written, or is to be written, to the
+ first module's shift register
+ 02 the same for second module
+ == ================================================
diff --git a/Documentation/ABI/testing/debugfs-msi-wmi-platform b/Documentation/ABI/testing/debugfs-msi-wmi-platform
new file mode 100644
index 000000000000..71f9992168d8
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-msi-wmi-platform
@@ -0,0 +1,14 @@
+What: /sys/kernel/debug/msi-wmi-platform-<wmi_device_name>/*
+Date: April 2024
+KernelVersion: 6.10
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ This file allows to execute the associated WMI method with the same name.
+
+ To start the execution, write a buffer containing the method arguments
+ at file offset 0. Partial writes or writes at a different offset are not
+ supported.
+
+ The buffer returned by the WMI method can then be read from the file.
+
+ See Documentation/wmi/devices/msi-wmi-platform.rst for details.
diff --git a/Documentation/ABI/testing/debugfs-pcie-ptm b/Documentation/ABI/testing/debugfs-pcie-ptm
new file mode 100644
index 000000000000..602d41363571
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-pcie-ptm
@@ -0,0 +1,70 @@
+What: /sys/kernel/debug/pcie_ptm_*/local_clock
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RO) PTM local clock in nanoseconds. Applicable for both Root
+ Complex and Endpoint controllers.
+
+What: /sys/kernel/debug/pcie_ptm_*/master_clock
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RO) PTM master clock in nanoseconds. Applicable only for
+ Endpoint controllers.
+
+What: /sys/kernel/debug/pcie_ptm_*/t1
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RO) PTM T1 timestamp in nanoseconds. Applicable only for
+ Endpoint controllers.
+
+What: /sys/kernel/debug/pcie_ptm_*/t2
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RO) PTM T2 timestamp in nanoseconds. Applicable only for
+ Root Complex controllers.
+
+What: /sys/kernel/debug/pcie_ptm_*/t3
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RO) PTM T3 timestamp in nanoseconds. Applicable only for
+ Root Complex controllers.
+
+What: /sys/kernel/debug/pcie_ptm_*/t4
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RO) PTM T4 timestamp in nanoseconds. Applicable only for
+ Endpoint controllers.
+
+What: /sys/kernel/debug/pcie_ptm_*/context_update
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RW) Control the PTM context update mode. Applicable only for
+ Endpoint controllers.
+
+ Following values are supported:
+
+ * auto = PTM context auto update trigger for every 10ms
+
+ * manual = PTM context manual update. Writing 'manual' to this
+ file triggers PTM context update (default)
+
+What: /sys/kernel/debug/pcie_ptm_*/context_valid
+Date: May 2025
+Contact: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+ (RW) Control the PTM context validity (local clock timing).
+ Applicable only for Root Complex controllers. PTM context is
+ invalidated by hardware if the Root Complex enters low power
+ mode or changes link frequency.
+
+ Following values are supported:
+
+ * 0 = PTM context invalid (default)
+
+ * 1 = PTM context valid
diff --git a/Documentation/ABI/testing/debugfs-pfo-nx-crypto b/Documentation/ABI/testing/debugfs-pfo-nx-crypto
index 685d5a448423..f75a655c1531 100644
--- a/Documentation/ABI/testing/debugfs-pfo-nx-crypto
+++ b/Documentation/ABI/testing/debugfs-pfo-nx-crypto
@@ -4,42 +4,42 @@ KernelVersion: 3.4
Contact: Kent Yoder <key@linux.vnet.ibm.com>
Description:
- These debugfs interfaces are built by the nx-crypto driver, built in
+These debugfs interfaces are built by the nx-crypto driver, built in
arch/powerpc/crypto/nx.
Error Detection
===============
errors:
-- A u32 providing a total count of errors since the driver was loaded. The
-only errors counted here are those returned from the hcall, H_COP_OP.
+ A u32 providing a total count of errors since the driver was loaded. The
+ only errors counted here are those returned from the hcall, H_COP_OP.
last_error:
-- The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not
-recorded here (the hcall will retry until -EBUSY goes away).
+ The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not
+ recorded here (the hcall will retry until -EBUSY goes away).
last_error_pid:
-- The process ID of the process who received the most recent error from the
-hcall.
+ The process ID of the process who received the most recent error from the
+ hcall.
Device Use
==========
aes_bytes:
-- The total number of bytes encrypted using AES in any of the driver's
-supported modes.
+ The total number of bytes encrypted using AES in any of the driver's
+ supported modes.
aes_ops:
-- The total number of AES operations submitted to the hardware.
+ The total number of AES operations submitted to the hardware.
sha256_bytes:
-- The total number of bytes hashed by the hardware using SHA-256.
+ The total number of bytes hashed by the hardware using SHA-256.
sha256_ops:
-- The total number of SHA-256 operations submitted to the hardware.
+ The total number of SHA-256 operations submitted to the hardware.
sha512_bytes:
-- The total number of bytes hashed by the hardware using SHA-512.
+ The total number of bytes hashed by the hardware using SHA-512.
sha512_ops:
-- The total number of SHA-512 operations submitted to the hardware.
+ The total number of SHA-512 operations submitted to the hardware.
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd
deleted file mode 100644
index cf11736acb76..000000000000
--- a/Documentation/ABI/testing/debugfs-pktcdvd
+++ /dev/null
@@ -1,19 +0,0 @@
-What: /sys/kernel/debug/pktcdvd/pktcdvd[0-7]
-Date: Oct. 2006
-KernelVersion: 2.6.20
-Contact: Thomas Maier <balagi@justmail.de>
-Description:
-
-debugfs interface
------------------
-
-The pktcdvd module (packet writing driver) creates
-these files in debugfs:
-
-/sys/kernel/debug/pktcdvd/pktcdvd[0-7]/
- info (0444) Lots of driver statistics and infos.
-
-Example:
--------
-
-cat /sys/kernel/debug/pktcdvd/pktcdvd0/info
diff --git a/Documentation/ABI/testing/debugfs-scmi b/Documentation/ABI/testing/debugfs-scmi
new file mode 100644
index 000000000000..ee7179ab2edf
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-scmi
@@ -0,0 +1,70 @@
+What: /sys/kernel/debug/scmi/<n>/instance_name
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: The name of the underlying SCMI instance <n> described by
+ all the debugfs accessors rooted at /sys/kernel/debug/scmi/<n>,
+ expressed as the full name of the top DT SCMI node under which
+ this SCMI instance is rooted.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/atomic_threshold_us
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: An optional time value, expressed in microseconds, representing,
+ on this SCMI instance <n>, the threshold above which any SCMI
+ command, advertised to have an higher-than-threshold execution
+ latency, should not be considered for atomic mode of operation,
+ even if requested.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/transport/type
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: A string representing the type of transport configured for this
+ SCMI instance <n>.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/transport/is_atomic
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: A boolean stating if the transport configured on the underlying
+ SCMI instance <n> is capable of atomic mode of operation.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/transport/max_rx_timeout_ms
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: Timeout in milliseconds allowed for SCMI synchronous replies
+ for the currently configured SCMI transport for instance <n>.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/transport/max_msg_size
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: Max message size of allowed SCMI messages for the currently
+ configured SCMI transport for instance <n>.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/transport/tx_max_msg
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: Max number of concurrently allowed in-flight SCMI messages for
+ the currently configured SCMI transport for instance <n> on the
+ TX channels.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/transport/rx_max_msg
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: Max number of concurrently allowed in-flight SCMI messages for
+ the currently configured SCMI transport for instance <n> on the
+ RX channels.
+Users: Debugging, any userspace test suite
diff --git a/Documentation/ABI/testing/debugfs-scmi-raw b/Documentation/ABI/testing/debugfs-scmi-raw
new file mode 100644
index 000000000000..5847b96b3896
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-scmi-raw
@@ -0,0 +1,208 @@
+What: /sys/kernel/debug/scmi/<n>/raw/message
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw synchronous message injection/snooping facility; write
+ a complete SCMI synchronous command message (header included)
+ in little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n>.
+ Any subsequently received response can be read from this same
+ entry if it arrived within the configured timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/message_async
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw asynchronous message injection/snooping facility; write
+ a complete SCMI asynchronous command message (header included)
+ in little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n>.
+ Any subsequently received response can be read from this same
+ entry if it arrived within the configured timeout.
+ Any additional delayed response received afterwards can be read
+ from this same entry too if it arrived within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/message_poll
+Date: June 2025
+KernelVersion: 6.16
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw message injection/snooping facility using polling mode;
+ write a complete SCMI command message (header included) in
+ little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n>, using polling mode on
+ the reception path. (if transport is polling capable)
+ Any subsequently received response can be read from this same
+ entry if it arrived within the configured timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/message_poll_async
+Date: June 2025
+KernelVersion: 6.16
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw asynchronous message injection/snooping facility using
+ polling-mode; write a complete SCMI asynchronous command message
+ (header included) in little-endian binary format to have it sent
+ to the configured backend SCMI server for instance <n>, using
+ polling-mode on the reception path of the immediate part of the
+ asynchronous command. (if transport is polling capable)
+ Any subsequently received response can be read from this same
+ entry if it arrived within the configured timeout.
+ Any additional delayed response received afterwards can be read
+ from this same entry too if it arrived within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/errors
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw message errors facility; any kind of timed-out or
+ generally unexpectedly received SCMI message, for instance <n>,
+ can be read from this entry.
+ Each read gives back one message at time (receiving an EOF at
+ each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/notification
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw notification snooping facility; any notification
+ emitted by the backend SCMI server, for instance <n>, can be
+ read from this entry.
+ Each read gives back one message at time (receiving an EOF at
+ each message boundary).
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/reset
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw stack reset facility; writing a value to this entry
+ causes the internal queues of any kind of received message,
+ still pending to be read out for instance <n>, to be immediately
+ flushed.
+ Can be used to reset and clean the SCMI Raw stack between to
+ different test-run.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/channels/<m>/message
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw synchronous message injection/snooping facility; write
+ a complete SCMI synchronous command message (header included)
+ in little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n> through the <m> transport
+ channel.
+ Any subsequently received response can be read from this same
+ entry if it arrived on channel <m> within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+ Channel identifier <m> matches the SCMI protocol number which
+ has been associated with this transport channel in the DT
+ description, with base protocol number 0x10 being the default
+ channel for this instance.
+ Note that these per-channel entries rooted at <..>/channels
+ exist only if the transport is configured to have more than
+ one default channel.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/channels/<m>/message_async
+Date: March 2023
+KernelVersion: 6.3
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw asynchronous message injection/snooping facility; write
+ a complete SCMI asynchronous command message (header included)
+ in little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n> through the <m> transport
+ channel.
+ Any subsequently received response can be read from this same
+ entry if it arrived on channel <m> within the configured
+ timeout.
+ Any additional delayed response received afterwards can be read
+ from this same entry too if it arrived within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+ Channel identifier <m> matches the SCMI protocol number which
+ has been associated with this transport channel in the DT
+ description, with base protocol number 0x10 being the default
+ channel for this instance.
+ Note that these per-channel entries rooted at <..>/channels
+ exist only if the transport is configured to have more than
+ one default channel.
+Users: Debugging, any userspace test suite
+
+
+What: /sys/kernel/debug/scmi/<n>/raw/channels/<m>/message_poll
+Date: June 2025
+KernelVersion: 6.16
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw message injection/snooping facility using polling mode;
+ write a complete SCMI command message (header included) in
+ little-endian binary format to have it sent to the configured
+ backend SCMI server for instance <n> through the <m> transport
+ channel, using polling mode on the reception path.
+ (if transport is polling capable)
+ Any subsequently received response can be read from this same
+ entry if it arrived on channel <m> within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+ Channel identifier <m> matches the SCMI protocol number which
+ has been associated with this transport channel in the DT
+ description, with base protocol number 0x10 being the default
+ channel for this instance.
+ Note that these per-channel entries rooted at <..>/channels
+ exist only if the transport is configured to have more than
+ one default channel.
+Users: Debugging, any userspace test suite
+
+What: /sys/kernel/debug/scmi/<n>/raw/channels/<m>/message_poll_async
+Date: June 2025
+KernelVersion: 6.16
+Contact: cristian.marussi@arm.com
+Description: SCMI Raw asynchronous message injection/snooping facility using
+ polling-mode; write a complete SCMI asynchronous command message
+ (header included) in little-endian binary format to have it sent
+ to the configured backend SCMI server for instance <n> through
+ the <m> transport channel, using polling mode on the reception
+ path of the immediate part of the asynchronous command.
+ (if transport is polling capable)
+ Any subsequently received response can be read from this same
+ entry if it arrived on channel <m> within the configured
+ timeout.
+ Any additional delayed response received afterwards can be read
+ from this same entry too if it arrived within the configured
+ timeout.
+ Each write to the entry causes one command request to be built
+ and sent while the replies are read back one message at time
+ (receiving an EOF at each message boundary).
+ Channel identifier <m> matches the SCMI protocol number which
+ has been associated with this transport channel in the DT
+ description, with base protocol number 0x10 being the default
+ channel for this instance.
+ Note that these per-channel entries rooted at <..>/channels
+ exist only if the transport is configured to have more than
+ one default channel.
+Users: Debugging, any userspace test suite
diff --git a/Documentation/ABI/testing/debugfs-tpmi b/Documentation/ABI/testing/debugfs-tpmi
new file mode 100644
index 000000000000..c493a1403d2f
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-tpmi
@@ -0,0 +1,40 @@
+What: /sys/kernel/debug/tpmi-<n>/pfs_dump
+Date: November 2023
+KernelVersion: 6.6
+Contact: srinivas.pandruvada@linux.intel.com
+Description:
+The PFS (PM Feature Structure) table, shows details of each power
+management feature. This includes:
+tpmi_id, number of entries, entry size, offset, vsec offset, lock status
+and disabled status.
+Users: Debugging, any user space test suite
+
+What: /sys/kernel/debug/tpmi-<n>/tpmi-id-<n>/mem_dump
+Date: November 2023
+KernelVersion: 6.6
+Contact: srinivas.pandruvada@linux.intel.com
+Description:
+Shows the memory dump of the MMIO region for a TPMI ID.
+Users: Debugging, any user space test suite
+
+What: /sys/kernel/debug/tpmi-<n>/tpmi-id-<n>/mem_write
+Date: November 2023
+KernelVersion: 6.6
+Contact: srinivas.pandruvada@linux.intel.com
+Description:
+Allows to write at any offset. It doesn't check for Read/Write access
+as hardware will not allow to write at read-only memory. This write is
+at offset multiples of 4. The format is instance,offset,contents.
+Example:
+echo 0,0x20,0xff > mem_write
+echo 1,64,64 > mem_write
+Users: Debugging, any user space test suite
+
+What: /sys/kernel/debug/tpmi-<n>/plr/domain<n>/status
+Date: Aug 2024
+KernelVersion: 6.11
+Contact: Tero Kristo <tero.kristo@linux.intel.com>
+Description:
+Shows the currently active Performance Limit Reasons for die level and the
+individual CPUs under the die. The contents of this file are sticky, and
+clearing all the statuses can be done by writing "0\n" to this file.
diff --git a/Documentation/ABI/testing/debugfs-vfio b/Documentation/ABI/testing/debugfs-vfio
new file mode 100644
index 000000000000..70ec2d454686
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-vfio
@@ -0,0 +1,31 @@
+What: /sys/kernel/debug/vfio
+Date: December 2023
+KernelVersion: 6.8
+Contact: Longfang Liu <liulongfang@huawei.com>
+Description: This debugfs file directory is used for debugging
+ of vfio devices, it's a common directory for all vfio devices.
+ Vfio core will create a device subdirectory under this
+ directory.
+
+What: /sys/kernel/debug/vfio/<device>/migration
+Date: December 2023
+KernelVersion: 6.8
+Contact: Longfang Liu <liulongfang@huawei.com>
+Description: This debugfs file directory is used for debugging
+ of vfio devices that support live migration.
+ The debugfs of each vfio device that supports live migration
+ could be created under this directory.
+
+What: /sys/kernel/debug/vfio/<device>/migration/state
+Date: December 2023
+KernelVersion: 6.8
+Contact: Longfang Liu <liulongfang@huawei.com>
+Description: Read the live migration status of the vfio device.
+ The contents of the state file reflects the migration state
+ relative to those defined in the vfio_device_mig_state enum
+
+What: /sys/kernel/debug/vfio/<device>/migration/features
+Date: Oct 2025
+KernelVersion: 6.18
+Contact: Cédric Le Goater <clg@redhat.com>
+Description: Read the migration features of the vfio device.
diff --git a/Documentation/ABI/testing/debugfs-wilco-ec b/Documentation/ABI/testing/debugfs-wilco-ec
new file mode 100644
index 000000000000..682e3c09ef4d
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-wilco-ec
@@ -0,0 +1,45 @@
+What: /sys/kernel/debug/wilco_ec/h1_gpio
+Date: April 2019
+KernelVersion: 5.2
+Description:
+ As part of Chrome OS's FAFT (Fully Automated Firmware Testing)
+ tests, we need to ensure that the H1 chip is properly setting
+ some GPIO lines. The h1_gpio attribute exposes the state
+ of the lines:
+ - ENTRY_TO_FACT_MODE in BIT(0)
+ - SPI_CHROME_SEL in BIT(1)
+
+ Output will formatted with "0x%02x\n".
+
+What: /sys/kernel/debug/wilco_ec/raw
+Date: January 2019
+KernelVersion: 5.1
+Description:
+ Write and read raw mailbox commands to the EC.
+
+ You can write a hexadecimal sentence to raw, and that series of
+ bytes will be sent to the EC. Then, you can read the bytes of
+ response by reading from raw.
+
+ For writing, bytes 0-1 indicate the message type, one of enum
+ wilco_ec_msg_type. Byte 2+ consist of the data passed in the
+ request, starting at MBOX[0]. At least three bytes are required
+ for writing, two for the type and at least a single byte of
+ data.
+
+ Example::
+
+ // Request EC info type 3 (EC firmware build date)
+ // Corresponds with sending type 0x00f0 with
+ // MBOX = [38, 00, 03, 00]
+ $ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw
+ // View the result. The decoded ASCII result "12/21/18" is
+ // included after the raw hex.
+ // Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...]
+ $ cat /sys/kernel/debug/wilco_ec/raw
+ 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8...
+
+ Note that the first 16 bytes of the received MBOX[] will be
+ printed, even if some of the data is junk, and skipping bytes
+ 17 to 32. It is up to you to know how many of the first bytes of
+ data are the actual response.
diff --git a/Documentation/ABI/testing/dell-smbios-wmi b/Documentation/ABI/testing/dell-smbios-wmi
new file mode 100644
index 000000000000..f58229084469
--- /dev/null
+++ b/Documentation/ABI/testing/dell-smbios-wmi
@@ -0,0 +1,41 @@
+What: /dev/wmi/dell-smbios
+Date: November 2017
+KernelVersion: 4.15
+Contact: Dell.Client.Kernel@dell.com
+Description:
+ Perform SMBIOS calls on supported Dell machines.
+ through the Dell ACPI-WMI interface.
+
+ IOCTL's and buffer formats are defined in:
+ <uapi/linux/wmi.h>
+
+ 1) To perform an SMBIOS call from userspace, you'll need to
+ first determine the minimum size of the calling interface
+ buffer for your machine.
+ Platforms that contain larger buffers can return larger
+ objects from the system firmware.
+ Commonly this size is either 4k or 32k.
+
+ To determine the size of the buffer read() a u64 dword from
+ the WMI character device /dev/wmi/dell-smbios.
+
+ 2) After you've determined the minimum size of the calling
+ interface buffer, you can allocate a structure that represents
+ the structure documented above.
+
+ 3) In the 'length' object store the size of the buffer you
+ determined above and allocated.
+
+ 4) In this buffer object, prepare as necessary for the SMBIOS
+ call you're interested in. Typically SMBIOS buffers have
+ "class", "select", and "input" defined to values that coincide
+ with the data you are interested in.
+ Documenting class/select/input values is outside of the scope
+ of this documentation. Check with the libsmbios project for
+ further documentation on these values.
+
+ 6) Run the call by using ioctl() as described in the header.
+
+ 7) The output will be returned in the buffer object.
+
+ 8) Be sure to free up your allocated object.
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg
index bb820be48179..a377b6c093c9 100644
--- a/Documentation/ABI/testing/dev-kmsg
+++ b/Documentation/ABI/testing/dev-kmsg
@@ -6,13 +6,14 @@ Description: The /dev/kmsg character device node provides userspace access
to the kernel's printk buffer.
Injecting messages:
+
Every write() to the opened device node places a log entry in
the kernel's printk buffer.
The logged line can be prefixed with a <N> syslog prefix, which
carries the syslog priority and facility. The single decimal
prefix number is composed of the 3 lowest bits being the syslog
- priority and the higher bits the syslog facility number.
+ priority and the next 8 bits the syslog facility number.
If no prefix is given, the priority number is the default kernel
log priority and the facility number is set to LOG_USER (1). It
@@ -21,6 +22,7 @@ Description: The /dev/kmsg character device node provides userspace access
the messages can always be reliably determined.
Accessing the buffer:
+
Every read() from the opened device node receives one record
of the kernel's printk buffer.
@@ -48,6 +50,7 @@ Description: The /dev/kmsg character device node provides userspace access
if needed, without limiting the interface to a single reader.
The device supports seek with the following parameters:
+
SEEK_SET, 0
seek to the first entry in the buffer
SEEK_END, 0
@@ -56,6 +59,17 @@ Description: The /dev/kmsg character device node provides userspace access
seek after the last record available at the time
the last SYSLOG_ACTION_CLEAR was issued.
+ Other seek operations or offsets are not supported because of
+ the special behavior this device has. The device allows to read
+ or write only whole variable length messages (records) that are
+ stored in a ring buffer.
+
+ Because of the non-standard behavior also the error values are
+ non-standard. -ESPIPE is returned for non-zero offset. -EINVAL
+ is returned for other operations, e.g. SEEK_CUR. This behavior
+ and values are historical and could not be modified without the
+ risk of breaking userspace.
+
The output format consists of a prefix carrying the syslog
prefix including priority and facility, the 64 bit message
sequence number and the monotonic timestamp in microseconds,
@@ -76,26 +90,38 @@ Description: The /dev/kmsg character device node provides userspace access
readable context of the message, for reliable processing in
userspace.
- Example:
- 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
- SUBSYSTEM=acpi
- DEVICE=+acpi:PNP0A03:00
- 6,339,5140900,-;NET: Registered protocol family 10
- 30,340,5690716,-;udevd[80]: starting version 181
+ Example::
+
+ 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
+ SUBSYSTEM=acpi
+ DEVICE=+acpi:PNP0A03:00
+ 6,339,5140900,-;NET: Registered protocol family 10
+ 30,340,5690716,-;udevd[80]: starting version 181
The DEVICE= key uniquely identifies devices the following way:
- b12:8 - block dev_t
- c127:3 - char dev_t
- n8 - netdev ifindex
- +sound:card0 - subsystem:devname
+
+ ============ =================
+ b12:8 block dev_t
+ c127:3 char dev_t
+ n8 netdev ifindex
+ +sound:card0 subsystem:devname
+ ============ =================
The flags field carries '-' by default. A 'c' indicates a
- fragment of a line. All following fragments are flagged with
- '+'. Note, that these hints about continuation lines are not
- necessarily correct, and the stream could be interleaved with
- unrelated messages, but merging the lines in the output
- usually produces better human readable results. A similar
- logic is used internally when messages are printed to the
- console, /proc/kmsg or the syslog() syscall.
+ fragment of a line. Note, that these hints about continuation
+ lines are not necessarily correct, and the stream could be
+ interleaved with unrelated messages, but merging the lines in
+ the output usually produces better human readable results. A
+ similar logic is used internally when messages are printed to
+ the console, /proc/kmsg or the syslog() syscall.
+
+ By default, kernel tries to avoid fragments by concatenating
+ when it can and fragments are rare; however, when extended
+ console support is enabled, the in-kernel concatenation is
+ disabled and /dev/kmsg output will contain more fragments. If
+ the log consumer performs concatenation, the end result
+ should be the same. In the future, the in-kernel concatenation
+ may be removed entirely and /dev/kmsg users are recommended to
+ implement fragment handling.
Users: dmesg(1), userspace kernel log consumers
diff --git a/Documentation/ABI/testing/devlink-resource-mlxsw b/Documentation/ABI/testing/devlink-resource-mlxsw
new file mode 100644
index 000000000000..259ed2948ec0
--- /dev/null
+++ b/Documentation/ABI/testing/devlink-resource-mlxsw
@@ -0,0 +1,33 @@
+What: /kvd/
+Date: 08-Jan-2018
+KernelVersion: v4.16
+Contact: mlxsw@mellanox.com
+Description: The main database in the Spectrum device is a centralized
+ KVD database used for many of the tables used to configure
+ the chip including L2 FDB, L3 LPM, ECMP and more. The KVD
+ is divided into two sections, the first is hash-based table
+ and the second is a linear access table. The division
+ between the linear and hash-based sections is static and
+ require reload before the changes take effect.
+
+What: /kvd/linear
+Date: 08-Jan-2018
+KernelVersion: v4.16
+Contact: mlxsw@mellanox.com
+Description: The linear section of the KVD is managed by software as a
+ flat memory accessed using an index.
+
+What: /kvd/hash_single
+Date: 08-Jan-2018
+KernelVersion: v4.16
+Contact: mlxsw@mellanox.com
+Description: The hash based section of the KVD is managed by the switch
+ device. Used in case the key size is smaller or equal to
+ 64bit.
+
+What: /kvd/hash_double
+Date: 08-Jan-2018
+KernelVersion: v4.16
+Contact: mlxsw@mellanox.com
+Description: The hash based section of the KVD is managed by the switch
+ device. Used in case the key is larger than 64 bit.
diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm
index 8374d4557e5d..44750a933db4 100644
--- a/Documentation/ABI/testing/evm
+++ b/Documentation/ABI/testing/evm
@@ -1,4 +1,5 @@
-What: security/evm
+What: /sys/kernel/security/evm
+What: /sys/kernel/security/*/evm
Date: March 2011
Contact: Mimi Zohar <zohar@us.ibm.com>
Description:
@@ -7,17 +8,101 @@ Description:
HMAC-sha1 value across the extended attributes, storing the
value as the extended attribute 'security.evm'.
- EVM depends on the Kernel Key Retention System to provide it
- with a trusted/encrypted key for the HMAC-sha1 operation.
- The key is loaded onto the root's keyring using keyctl. Until
- EVM receives notification that the key has been successfully
- loaded onto the keyring (echo 1 > <securityfs>/evm), EVM
- can not create or validate the 'security.evm' xattr, but
- returns INTEGRITY_UNKNOWN. Loading the key and signaling EVM
- should be done as early as possible. Normally this is done
- in the initramfs, which has already been measured as part
- of the trusted boot. For more information on creating and
- loading existing trusted/encrypted keys, refer to:
- Documentation/keys-trusted-encrypted.txt. (A sample dracut
- patch, which loads the trusted/encrypted key and enables
- EVM, is available from http://linux-ima.sourceforge.net/#EVM.)
+ EVM supports two classes of security.evm. The first is
+ an HMAC-sha1 generated locally with a
+ trusted/encrypted key stored in the Kernel Key
+ Retention System. The second is a digital signature
+ generated either locally or remotely using an
+ asymmetric key. These keys are loaded onto root's
+ keyring using keyctl, and EVM is then enabled by
+ echoing a value to <securityfs>/evm made up of the
+ following bits:
+
+ === ==================================================
+ Bit Effect
+ === ==================================================
+ 0 Enable HMAC validation and creation
+ 1 Enable digital signature validation
+ 2 Permit modification of EVM-protected metadata at
+ runtime. Not supported if HMAC validation and
+ creation is enabled (deprecated).
+ 31 Disable further runtime modification of EVM policy
+ === ==================================================
+
+ For example::
+
+ echo 1 ><securityfs>/evm
+
+ will enable HMAC validation and creation
+
+ ::
+
+ echo 0x80000003 ><securityfs>/evm
+
+ will enable HMAC and digital signature validation and
+ HMAC creation and disable all further modification of policy.
+
+ ::
+
+ echo 0x80000006 ><securityfs>/evm
+
+ will enable digital signature validation, permit
+ modification of EVM-protected metadata and
+ disable all further modification of policy. This option is now
+ deprecated in favor of::
+
+ echo 0x80000002 ><securityfs>/evm
+
+ as the outstanding issues that prevent the usage of EVM portable
+ signatures have been solved.
+
+ Echoing a value is additive, the new value is added to the
+ existing initialization flags.
+
+ For example, after::
+
+ echo 2 ><securityfs>/evm
+
+ another echo can be performed::
+
+ echo 1 ><securityfs>/evm
+
+ and the resulting value will be 3.
+
+ Note that once an HMAC key has been loaded, it will no longer
+ be possible to enable metadata modification. Signaling that an
+ HMAC key has been loaded will clear the corresponding flag.
+ For example, if the current value is 6 (2 and 4 set)::
+
+ echo 1 ><securityfs>/evm
+
+ will set the new value to 3 (4 cleared).
+
+ Loading an HMAC key is the only way to disable metadata
+ modification.
+
+ Until key loading has been signaled EVM can not create
+ or validate the 'security.evm' xattr, but returns
+ INTEGRITY_UNKNOWN. Loading keys and signaling EVM
+ should be done as early as possible. Normally this is
+ done in the initramfs, which has already been measured
+ as part of the trusted boot. For more information on
+ creating and loading existing trusted/encrypted keys,
+ refer to:
+ Documentation/security/keys/trusted-encrypted.rst. Both
+ dracut (via 97masterkey and 98integrity) and systemd (via
+ core/ima-setup) have support for loading keys at boot
+ time.
+
+What: /sys/kernel/security/*/evm/evm_xattrs
+Date: April 2018
+Contact: Matthew Garrett <mjg59@google.com>
+Description:
+ Shows the set of extended attributes used to calculate or
+ validate the EVM signature, and allows additional attributes
+ to be added at runtime. Any signatures generated after
+ additional attributes are added (and on files possessing those
+ additional attributes) will only be valid if the same
+ additional attributes are configured on system boot. Writing
+ a single period (.) will lock the xattr list from any further
+ modification.
diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev
new file mode 100644
index 000000000000..c9689b2a6fed
--- /dev/null
+++ b/Documentation/ABI/testing/gpio-cdev
@@ -0,0 +1,28 @@
+What: /dev/gpiochip[0-9]+
+Date: November 2015
+KernelVersion: 4.4
+Contact: linux-gpio@vger.kernel.org
+Description:
+ The character device files /dev/gpiochip* are the interface
+ between GPIO chips and userspace.
+
+ The ioctl(2)-based ABI is defined in
+ [include/uapi]<linux/gpio.h> and documented in
+ Documentation/userspace-api/gpio/chardev.rst.
+
+ The following file operations are supported:
+
+ open(2)
+ Currently the only useful flags are O_RDWR.
+
+ ioctl(2)
+ Initiate various actions.
+
+ See Documentation/userspace-api/gpio/chardev.rst
+ for a description of all ioctls.
+
+ close(2)
+ Stops and free up the I/O contexts that was associated
+ with the file descriptor.
+
+Users: TBD
diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy
index d0d0c578324c..d4b3696a9efb 100644
--- a/Documentation/ABI/testing/ima_policy
+++ b/Documentation/ABI/testing/ima_policy
@@ -1,4 +1,4 @@
-What: security/ima/policy
+What: /sys/kernel/security/*/ima/policy
Date: May 2008
Contact: Mimi Zohar <zohar@us.ibm.com>
Description:
@@ -15,27 +15,70 @@ Description:
IMA appraisal, if configured, uses these file measurements
for local measurement appraisal.
- rule format: action [condition ...]
+ ::
- action: measure | dont_measure | appraise | dont_appraise | audit
- condition:= base | lsm [option]
- base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=]
- [fowner]]
+ rule format: action [condition ...]
+
+ action: measure | dont_measure | appraise | dont_appraise |
+ audit | dont_audit | hash | dont_hash
+ condition:= base | lsm [option]
+ base: [[func=] [mask=] [fsmagic=] [fsuuid=] [fsname=]
+ [fs_subtype=]
+ [uid=] [euid=] [gid=] [egid=]
+ [fowner=] [fgroup=]]
lsm: [[subj_user=] [subj_role=] [subj_type=]
[obj_user=] [obj_role=] [obj_type=]]
- option: [[appraise_type=]] [permit_directio]
-
- base: func:= [BPRM_CHECK][MMAP_CHECK][FILE_CHECK][MODULE_CHECK]
+ option: [digest_type=] [template=] [permit_directio]
+ [appraise_type=] [appraise_flag=]
+ [appraise_algos=] [keyrings=]
+ base:
+ func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
[FIRMWARE_CHECK]
- mask:= [MAY_READ] [MAY_WRITE] [MAY_APPEND] [MAY_EXEC]
+ [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
+ [KEXEC_CMDLINE] [KEY_CHECK] [CRITICAL_DATA]
+ [SETXATTR_CHECK][MMAP_CHECK_REQPROT]
+ mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
+ [[^]MAY_EXEC]
fsmagic:= hex value
fsuuid:= file system UUID (e.g 8bcbe394-4f13-4144-be8e-5aa9ea2ce2f6)
uid:= decimal value
- fowner:=decimal value
- lsm: are LSM specific
- option: appraise_type:= [imasig]
+ euid:= decimal value
+ gid:= decimal value
+ egid:= decimal value
+ fowner:= decimal value
+ fgroup:= decimal value
+ lsm: are LSM specific
+ option:
+ appraise_type:= [imasig] | [imasig|modsig] | [sigv3]
+ where 'imasig' is the original or the signature
+ format v2.
+ where 'modsig' is an appended signature,
+ where 'sigv3' is the signature format v3. (Currently
+ limited to fsverity digest based signatures
+ stored in security.ima xattr. Requires
+ specifying "digest_type=verity" first.)
- default policy:
+ appraise_flag:= [check_blacklist] (deprecated)
+ Setting the check_blacklist flag is no longer necessary.
+ All appraisal functions set it by default.
+ digest_type:= verity
+ Require fs-verity's file digest instead of the
+ regular IMA file hash.
+ keyrings:= list of keyrings
+ (eg, .builtin_trusted_keys|.ima). Only valid
+ when action is "measure" and func is KEY_CHECK.
+ template:= name of a defined IMA template type
+ (eg, ima-ng). Only valid when action is "measure".
+ pcr:= decimal value
+ label:= [selinux]|[kernel_info]|[data_label]
+ data_label:= a unique string used for grouping and limiting critical data.
+ For example, "selinux" to measure critical data for SELinux.
+ appraise_algos:= comma-separated list of hash algorithms
+ For example, "sha256,sha512" to only accept to appraise
+ files where the security.ima xattr was hashed with one
+ of these two algorithms.
+
+ default policy:
# PROC_SUPER_MAGIC
dont_measure fsmagic=0x9fa0
dont_appraise fsmagic=0x9fa0
@@ -49,11 +92,25 @@ Description:
dont_measure fsmagic=0x01021994
dont_appraise fsmagic=0x01021994
# RAMFS_MAGIC
- dont_measure fsmagic=0x858458f6
dont_appraise fsmagic=0x858458f6
+ # DEVPTS_SUPER_MAGIC
+ dont_measure fsmagic=0x1cd1
+ dont_appraise fsmagic=0x1cd1
+ # BINFMTFS_MAGIC
+ dont_measure fsmagic=0x42494e4d
+ dont_appraise fsmagic=0x42494e4d
# SECURITYFS_MAGIC
dont_measure fsmagic=0x73636673
dont_appraise fsmagic=0x73636673
+ # SELINUX_MAGIC
+ dont_measure fsmagic=0xf97cff8c
+ dont_appraise fsmagic=0xf97cff8c
+ # CGROUP_SUPER_MAGIC
+ dont_measure fsmagic=0x27e0eb
+ dont_appraise fsmagic=0x27e0eb
+ # NSFS_MAGIC
+ dont_measure fsmagic=0x6e736673
+ dont_appraise fsmagic=0x6e736673
measure func=BPRM_CHECK
measure func=FILE_MMAP mask=MAY_EXEC
@@ -69,10 +126,7 @@ Description:
Examples of LSM specific definitions:
- SELinux:
- # SELINUX_MAGIC
- dont_measure fsmagic=0xf97cff8c
- dont_appraise fsmagic=0xf97cff8c
+ SELinux::
dont_measure obj_type=var_log_t
dont_appraise obj_type=var_log_t
@@ -81,5 +135,57 @@ Description:
measure subj_user=system_u func=FILE_CHECK mask=MAY_READ
measure subj_role=system_r func=FILE_CHECK mask=MAY_READ
- Smack:
+ Smack::
+
measure subj_user=_ func=FILE_CHECK mask=MAY_READ
+
+ Example of measure rules using alternate PCRs::
+
+ measure func=KEXEC_KERNEL_CHECK pcr=4
+ measure func=KEXEC_INITRAMFS_CHECK pcr=5
+
+ Example of appraise rule allowing modsig appended signatures:
+
+ appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig|modsig
+
+ Example of measure rule using KEY_CHECK to measure all keys:
+
+ measure func=KEY_CHECK
+
+ Example of measure rule using KEY_CHECK to only measure
+ keys added to .builtin_trusted_keys or .ima keyring:
+
+ measure func=KEY_CHECK keyrings=.builtin_trusted_keys|.ima
+
+ Example of the special SETXATTR_CHECK appraise rule, that
+ restricts the hash algorithms allowed when writing to the
+ security.ima xattr of a file:
+
+ appraise func=SETXATTR_CHECK appraise_algos=sha256,sha384,sha512
+
+ Example of a 'measure' rule requiring fs-verity's digests
+ with indication of type of digest in the measurement list.
+
+ measure func=FILE_CHECK digest_type=verity \
+ template=ima-ngv2
+
+ Example of 'measure' and 'appraise' rules requiring fs-verity
+ signatures (format version 3) stored in security.ima xattr.
+
+ The 'measure' rule specifies the 'ima-sigv3' template option,
+ which includes the indication of type of digest and the file
+ signature in the measurement list.
+
+ measure func=BPRM_CHECK digest_type=verity \
+ template=ima-sigv3
+
+
+ The 'appraise' rule specifies the type and signature format
+ version (sigv3) required.
+
+ appraise func=BPRM_CHECK digest_type=verity \
+ appraise_type=sigv3
+
+ All of these policy rules could, for example, be constrained
+ either based on a filesystem's UUID (fsuuid) or based on LSM
+ labels.
diff --git a/Documentation/ABI/testing/ppc-memtrace b/Documentation/ABI/testing/ppc-memtrace
new file mode 100644
index 000000000000..9606aed33137
--- /dev/null
+++ b/Documentation/ABI/testing/ppc-memtrace
@@ -0,0 +1,46 @@
+What: /sys/kernel/debug/powerpc/memtrace
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: This folder contains the relevant debugfs files for the
+ hardware trace macro to use. CONFIG_PPC64_HARDWARE_TRACING
+ must be set.
+
+What: /sys/kernel/debug/powerpc/memtrace/enable
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: Write an integer containing the size in bytes of the memory
+ you want removed from each NUMA node to this file - it must be
+ aligned to the memblock size. This amount of RAM will be removed
+ from each NUMA node in the kernel mappings and the following
+ debugfs files will be created. Once memory is successfully
+ removed from each node, the following files are created. To
+ re-add memory to the kernel, echo 0 into this file (it will be
+ automatically onlined).
+
+What: /sys/kernel/debug/powerpc/memtrace/<node-id>
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: This directory contains information about the removed memory
+ from the specific NUMA node.
+
+What: /sys/kernel/debug/powerpc/memtrace/<node-id>/size
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: This contains the size of the memory removed from the node.
+
+What: /sys/kernel/debug/powerpc/memtrace/<node-id>/start
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: This contains the start address of the removed memory.
+
+What: /sys/kernel/debug/powerpc/memtrace/<node-id>/trace
+Date: Aug 2017
+KernelVersion: 4.14
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: This is where the hardware trace macro will output the trace
+ it generates.
diff --git a/Documentation/ABI/testing/procfs-attr-current b/Documentation/ABI/testing/procfs-attr-current
new file mode 100644
index 000000000000..198b9fe1c8e8
--- /dev/null
+++ b/Documentation/ABI/testing/procfs-attr-current
@@ -0,0 +1,20 @@
+What: /proc/*/attr/current
+Contact: linux-security-module@vger.kernel.org,
+ selinux@vger.kernel.org,
+ apparmor@lists.ubuntu.com
+Description: The current security information used by a Linux
+ security module (LSM) that is active on the system.
+ The details of permissions required to read from
+ this interface and hence obtain the security state
+ of the task identified is LSM dependent.
+ A process cannot write to this interface unless it
+ refers to itself.
+ The other details of permissions required to write to
+ this interface and hence change the security state of
+ the task identified are LSM dependent.
+ The format of the data used by this interface is LSM
+ dependent.
+ SELinux, Smack and AppArmor provide this interface.
+Users: SELinux user-space
+ Smack user-space
+ AppArmor user-space
diff --git a/Documentation/ABI/testing/procfs-attr-exec b/Documentation/ABI/testing/procfs-attr-exec
new file mode 100644
index 000000000000..34593866a7ab
--- /dev/null
+++ b/Documentation/ABI/testing/procfs-attr-exec
@@ -0,0 +1,20 @@
+What: /proc/*/attr/exec
+Contact: linux-security-module@vger.kernel.org,
+ selinux@vger.kernel.org,
+ apparmor@lists.ubuntu.com
+Description: The security information to be used on the process
+ by a Linux security module (LSM) active on the system
+ after a subsequent exec() call.
+ The details of permissions required to read from
+ this interface and hence obtain the security state
+ of the task identified is LSM dependent.
+ A process cannot write to this interface unless it
+ refers to itself.
+ The other details of permissions required to write to
+ this interface and hence change the security state of
+ the task identified are LSM dependent.
+ The format of the data used by this interface is LSM
+ dependent.
+ SELinux and AppArmor provide this interface.
+Users: SELinux user-space
+ AppArmor user-space
diff --git a/Documentation/ABI/testing/procfs-attr-prev b/Documentation/ABI/testing/procfs-attr-prev
new file mode 100644
index 000000000000..f990b3595839
--- /dev/null
+++ b/Documentation/ABI/testing/procfs-attr-prev
@@ -0,0 +1,19 @@
+What: /proc/*/attr/prev
+Contact: linux-security-module@vger.kernel.org,
+ selinux@vger.kernel.org,
+ apparmor@lists.ubuntu.com
+Description: The security information used on the process by
+ a Linux security module (LSM) active on the system
+ prior to the most recent exec() call.
+ The details of permissions required to read from
+ this interface is LSM dependent.
+ A process cannot write to this interface unless it
+ refers to itself.
+ The other details of permissions required to write to
+ this interface are LSM dependent.
+ The format of the data used by this interface is LSM
+ dependent.
+ SELinux and AppArmor provide this interface.
+Users: SELinux user-space
+ AppArmor user-space
+
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats
index f91a973a37fe..6a719cf2075c 100644
--- a/Documentation/ABI/testing/procfs-diskstats
+++ b/Documentation/ABI/testing/procfs-diskstats
@@ -5,18 +5,39 @@ Description:
The /proc/diskstats file displays the I/O statistics
of block devices. Each line contains the following 14
fields:
- 1 - major number
- 2 - minor mumber
- 3 - device name
- 4 - reads completed successfully
- 5 - reads merged
- 6 - sectors read
- 7 - time spent reading (ms)
- 8 - writes completed
- 9 - writes merged
- 10 - sectors written
- 11 - time spent writing (ms)
- 12 - I/Os currently in progress
- 13 - time spent doing I/Os (ms)
- 14 - weighted time spent doing I/Os (ms)
- For more details refer to Documentation/iostats.txt
+
+ == ===================================
+ 1 major number
+ 2 minor number
+ 3 device name
+ 4 reads completed successfully
+ 5 reads merged
+ 6 sectors read
+ 7 time spent reading (ms)
+ 8 writes completed
+ 9 writes merged
+ 10 sectors written
+ 11 time spent writing (ms)
+ 12 I/Os currently in progress
+ 13 time spent doing I/Os (ms)
+ 14 weighted time spent doing I/Os (ms)
+ == ===================================
+
+ Kernel 4.18+ appends four more fields for discard
+ tracking putting the total at 18:
+
+ == ===================================
+ 15 discards completed successfully
+ 16 discards merged
+ 17 sectors discarded
+ 18 time spent discarding
+ == ===================================
+
+ Kernel 5.5+ appends two more fields for flush requests:
+
+ == =====================================
+ 19 flush requests completed successfully
+ 20 time spent flushing
+ == =====================================
+
+ For more details refer to Documentation/admin-guide/iostats.rst
diff --git a/Documentation/ABI/testing/procfs-smaps_rollup b/Documentation/ABI/testing/procfs-smaps_rollup
new file mode 100644
index 000000000000..b446a7154a1b
--- /dev/null
+++ b/Documentation/ABI/testing/procfs-smaps_rollup
@@ -0,0 +1,42 @@
+What: /proc/pid/smaps_rollup
+Date: August 2017
+Contact: Daniel Colascione <dancol@google.com>
+Description:
+ This file provides pre-summed memory information for a
+ process. The format is almost identical to /proc/pid/smaps,
+ except instead of an entry for each VMA in a process,
+ smaps_rollup has a single entry (tagged "[rollup]")
+ for which each field is the sum of the corresponding
+ fields from all the maps in /proc/pid/smaps.
+ Additionally, the fields Pss_Anon, Pss_File and Pss_Shmem
+ are not present in /proc/pid/smaps. These fields represent
+ the sum of the Pss field of each type (anon, file, shmem).
+ For more details, see Documentation/filesystems/proc.rst
+ and the procfs man page.
+
+ Typical output looks like this::
+
+ 00100000-ff709000 ---p 00000000 00:00 0 [rollup]
+ Size: 1192 kB
+ KernelPageSize: 4 kB
+ MMUPageSize: 4 kB
+ Rss: 884 kB
+ Pss: 385 kB
+ Pss_Dirty: 68 kB
+ Pss_Anon: 301 kB
+ Pss_File: 80 kB
+ Pss_Shmem: 4 kB
+ Shared_Clean: 696 kB
+ Shared_Dirty: 0 kB
+ Private_Clean: 120 kB
+ Private_Dirty: 68 kB
+ Referenced: 884 kB
+ Anonymous: 68 kB
+ LazyFree: 0 kB
+ AnonHugePages: 0 kB
+ ShmemPmdMapped: 0 kB
+ Shared_Hugetlb: 0 kB
+ Private_Hugetlb: 0 kB
+ Swap: 0 kB
+ SwapPss: 0 kB
+ Locked: 385 kB
diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore
index 5fca9f5e10a3..d3cff4a7ee10 100644
--- a/Documentation/ABI/testing/pstore
+++ b/Documentation/ABI/testing/pstore
@@ -1,6 +1,7 @@
-Where: /sys/fs/pstore/... (or /dev/pstore/...)
+What: /sys/fs/pstore/...
+What: /dev/pstore/...
Date: March 2011
-Kernel Version: 2.6.39
+KernelVersion: 2.6.39
Contact: tony.luck@intel.com
Description: Generic interface to platform dependent persistent storage.
@@ -9,25 +10,25 @@ Description: Generic interface to platform dependent persistent storage.
provide a generic interface to show records captured in
the dying moments. In the case of a panic the last part
of the console log is captured, but other interesting
- data can also be saved.
+ data can also be saved::
- # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore
+ # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore
- $ ls -l /sys/fs/pstore/
- total 0
- -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1
+ $ ls -l /sys/fs/pstore/
+ total 0
+ -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1
Different users of this interface will result in different
filename prefixes. Currently two are defined:
- "dmesg" - saved console log
- "mce" - architecture dependent data from fatal h/w error
+ - "dmesg" - saved console log
+ - "mce" - architecture dependent data from fatal h/w error
Once the information in a file has been read, removing
the file will signal to the underlying persistent storage
- device that it can reclaim the space for later re-use.
+ device that it can reclaim the space for later re-use::
- $ rm /sys/fs/pstore/dmesg-erst-1
+ $ rm /sys/fs/pstore/dmesg-erst-1
The expectation is that all files in /sys/fs/pstore/
will be saved elsewhere and erased from persistent store
@@ -44,4 +45,3 @@ Description: Generic interface to platform dependent persistent storage.
backends are available, the preferred backend may be
set by passing the pstore.backend= argument to the kernel at
boot time.
-
diff --git a/Documentation/ABI/testing/rtc-cdev b/Documentation/ABI/testing/rtc-cdev
new file mode 100644
index 000000000000..25910c3c3d7e
--- /dev/null
+++ b/Documentation/ABI/testing/rtc-cdev
@@ -0,0 +1,50 @@
+What: /dev/rtcX
+Date: April 2005
+KernelVersion: 2.6.12
+Contact: linux-rtc@vger.kernel.org
+Description:
+ The ioctl interface to drivers for real-time clocks (RTCs).
+ Following actions are supported:
+
+ * RTC_RD_TIME, RTC_SET_TIME: Read or set the RTC time. Time
+ format is a Gregorian calendar date and 24 hour wall clock
+ time.
+
+ * RTC_AIE_ON, RTC_AIE_OFF: Enable or disable the alarm interrupt
+ for RTCs that support alarms
+
+ * RTC_ALM_READ, RTC_ALM_SET: Read or set the alarm time for
+ RTCs that support alarms. Can be set upto 24 hours in the
+ future. Requires a separate RTC_AIE_ON call to enable the
+ alarm interrupt. (Prefer to use RTC_WKALM_*)
+
+ * RTC_WKALM_RD, RTC_WKALM_SET: For RTCs that support a more
+ powerful interface, which can issue alarms beyond 24 hours and
+ enable IRQs in the same request.
+
+ * RTC_PIE_ON, RTC_PIE_OFF: Enable or disable the periodic
+ interrupt for RTCs that support periodic interrupts.
+
+ * RTC_UIE_ON, RTC_UIE_OFF: Enable or disable the update
+ interrupt for RTCs that support it.
+
+ * RTC_IRQP_READ, RTC_IRQP_SET: Read or set the frequency for
+ periodic interrupts for RTCs that support periodic interrupts.
+ Requires a separate RTC_PIE_ON call to enable the periodic
+ interrupts.
+
+ * RTC_VL_READ: Read the voltage inputs status of the RTC when
+ supported. The value is a bit field of RTC_VL_*, giving the
+ status of the main and backup voltages.
+
+ * RTC_VL_CLEAR: Clear the voltage status of the RTC. Some RTCs
+ need user interaction when the backup power provider is
+ replaced or charged to be able to clear the status.
+
+ The ioctl() calls supported by the older /dev/rtc interface are
+ also supported by the newer RTC class framework. However,
+ because the chips and systems are not standardized, some PC/AT
+ functionality might not be provided. And in the same way, some
+ newer features -- including those enabled by ACPI -- are exposed
+ by the RTC class framework, but can't be supported by the older
+ driver.
diff --git a/Documentation/ABI/testing/securityfs-secrets-coco b/Documentation/ABI/testing/securityfs-secrets-coco
new file mode 100644
index 000000000000..f2b6909155f9
--- /dev/null
+++ b/Documentation/ABI/testing/securityfs-secrets-coco
@@ -0,0 +1,51 @@
+What: security/secrets/coco
+Date: February 2022
+Contact: Dov Murik <dovmurik@linux.ibm.com>
+Description:
+ Exposes confidential computing (coco) EFI secrets to
+ userspace via securityfs.
+
+ EFI can declare memory area used by confidential computing
+ platforms (such as AMD SEV and SEV-ES) for secret injection by
+ the Guest Owner during VM's launch. The secrets are encrypted
+ by the Guest Owner and decrypted inside the trusted enclave,
+ and therefore are not readable by the untrusted host.
+
+ The efi_secret module exposes the secrets to userspace. Each
+ secret appears as a file under <securityfs>/secrets/coco,
+ where the filename is the GUID of the entry in the secrets
+ table. This module is loaded automatically by the EFI driver
+ if the EFI secret area is populated.
+
+ Two operations are supported for the files: read and unlink.
+ Reading the file returns the content of secret entry.
+ Unlinking the file overwrites the secret data with zeroes and
+ removes the entry from the filesystem. A secret cannot be read
+ after it has been unlinked.
+
+ For example, listing the available secrets::
+
+ # modprobe efi_secret
+ # ls -l /sys/kernel/security/secrets/coco
+ -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
+ -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
+ -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
+ -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910
+
+ Reading the secret data by reading a file::
+
+ # cat /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
+ the-content-of-the-secret-data
+
+ Wiping a secret by unlinking a file::
+
+ # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
+ # ls -l /sys/kernel/security/secrets/coco
+ -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
+ -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
+ -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
+
+ Note: The binary format of the secrets table injected by the
+ Guest Owner is described in
+ drivers/virt/coco/efi_secret/efi_secret.c under "Structure of
+ the EFI secret area".
diff --git a/Documentation/ABI/testing/sysfs-amd-pmc b/Documentation/ABI/testing/sysfs-amd-pmc
new file mode 100644
index 000000000000..c421b72844f1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-amd-pmc
@@ -0,0 +1,13 @@
+What: /sys/bus/platform/drivers/amd_pmc/*/smu_fw_version
+Date: October 2022
+Contact: Mario Limonciello <mario.limonciello@amd.com>
+Description: Reading this file reports the version of the firmware loaded to
+ System Management Unit (SMU) contained in AMD CPUs and
+ APUs.
+
+What: /sys/bus/platform/drivers/amd_pmc/*/smu_program
+Date: October 2022
+Contact: Mario Limonciello <mario.limonciello@amd.com>
+Description: Reading this file reports the program corresponding to the SMU
+ firmware version. The program field is used to disambiguate two
+ APU/CPU models that can share the same firmware binary.
diff --git a/Documentation/ABI/testing/sysfs-amd-pmf b/Documentation/ABI/testing/sysfs-amd-pmf
new file mode 100644
index 000000000000..7fc0e1c2b76b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-amd-pmf
@@ -0,0 +1,13 @@
+What: /sys/devices/platform/*/cnqf_enable
+Date: September 2022
+Contact: Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+Description: Reading this file tells if the AMD Platform Management(PMF)
+ Cool n Quiet Framework(CnQF) feature is enabled or not.
+
+ This feature is not enabled by default and gets only turned on
+ if OEM BIOS passes a "flag" to PMF ACPI function (index 11 or 12)
+ or in case the user writes "on".
+
+ To turn off CnQF user can write "off" to the sysfs node.
+ Note: Systems that support auto mode will not have this sysfs file
+ available.
diff --git a/Documentation/ABI/testing/sysfs-ata b/Documentation/ABI/testing/sysfs-ata
index 0a932155cbba..3daecac48964 100644
--- a/Documentation/ABI/testing/sysfs-ata
+++ b/Documentation/ABI/testing/sysfs-ata
@@ -1,99 +1,140 @@
-What: /sys/class/ata_...
-Date: August 2008
-Contact: Gwendal Grignou<gwendal@google.com>
+What: /sys/class/ata_*
Description:
-
-Provide a place in sysfs for storing the ATA topology of the system. This allows
-retrieving various information about ATA objects.
+ Provide a place in sysfs for storing the ATA topology of the
+ system. This allows retrieving various information about ATA
+ objects.
Files under /sys/class/ata_port
-------------------------------
- For each port, a directory ataX is created where X is the ata_port_id of
- the port. The device parent is the ata host device.
+For each port, a directory ataX is created where X is the ata_port_id of the
+port. The device parent is the ata host device.
+
-idle_irq (read)
+What: /sys/class/ata_port/ataX/nr_pmp_links
+What: /sys/class/ata_port/ataX/idle_irq
+Date: May, 2010
+KernelVersion: v2.6.37
+Contact: Gwendal Grignou <gwendal@chromium.org>
+Description:
+ nr_pmp_links: (RO) If a SATA Port Multiplier (PM) is
+ connected, the number of links behind it.
- Number of IRQ received by the port while idle [some ata HBA only].
+ idle_irq: (RO) Number of IRQ received by the port while
+ idle [some ata HBA only].
-nr_pmp_links (read)
- If a SATA Port Multiplier (PM) is connected, number of link behind it.
+What: /sys/class/ata_port/ataX/port_no
+Date: May, 2013
+KernelVersion: v3.11
+Contact: Gwendal Grignou <gwendal@chromium.org>
+Description:
+ (RO) Host local port number. While registering host controller,
+ port numbers are tracked based upon number of ports available on
+ the controller. This attribute is needed by udev for composing
+ persistent links in /dev/disk/by-path.
Files under /sys/class/ata_link
-------------------------------
- Behind each port, there is a ata_link. If there is a SATA PM in the
- topology, 15 ata_link objects are created.
+Behind each port, there is a ata_link. If there is a SATA PM in the topology, 15
+ata_link objects are created.
- If a link is behind a port, the directory name is linkX, where X is
- ata_port_id of the port.
- If a link is behind a PM, its name is linkX.Y where X is ata_port_id
- of the parent port and Y the PM port.
+If a link is behind a port, the directory name is linkX, where X is ata_port_id
+of the port. If a link is behind a PM, its name is linkX.Y where X is
+ata_port_id of the parent port and Y the PM port.
-hw_sata_spd_limit
- Maximum speed supported by the connected SATA device.
-
-sata_spd_limit
+What: /sys/class/ata_link/linkX[.Y]/hw_sata_spd_limit
+What: /sys/class/ata_link/linkX[.Y]/sata_spd_limit
+What: /sys/class/ata_link/linkX[.Y]/sata_spd
+Date: May, 2010
+KernelVersion: v2.6.37
+Contact: Gwendal Grignou <gwendal@chromium.org>
+Description:
+ hw_sata_spd_limit: (RO) Maximum speed supported by the
+ connected SATA device.
- Maximum speed imposed by libata.
+ sata_spd_limit: (RO) Maximum speed imposed by libata.
-sata_spd
+ sata_spd: (RO) Current speed of the link
+ eg. 1.5, 3 Gbps etc.
- Current speed of the link [1.5, 3Gps,...].
Files under /sys/class/ata_device
---------------------------------
- Behind each link, up to two ata device are created.
- The name of the directory is devX[.Y].Z where:
- - X is ata_port_id of the port where the device is connected,
- - Y the port of the PM if any, and
- - Z the device id: for PATA, there is usually 2 devices [0,1],
- only 1 for SATA.
+Behind each link, up to two ata devices are created.
+The name of the directory is devX[.Y].Z where:
+- X is ata_port_id of the port where the device is connected,
+- Y the port of the PM if any, and
+- Z the device id: for PATA, there is usually 2 devices [0,1], only 1 for SATA.
+
+
+What: /sys/class/ata_device/devX[.Y].Z/spdn_cnt
+What: /sys/class/ata_device/devX[.Y].Z/gscr
+What: /sys/class/ata_device/devX[.Y].Z/ering
+What: /sys/class/ata_device/devX[.Y].Z/id
+What: /sys/class/ata_device/devX[.Y].Z/pio_mode
+What: /sys/class/ata_device/devX[.Y].Z/xfer_mode
+What: /sys/class/ata_device/devX[.Y].Z/dma_mode
+What: /sys/class/ata_device/devX[.Y].Z/class
+Date: May, 2010
+KernelVersion: v2.6.37
+Contact: Gwendal Grignou <gwendal@chromium.org>
+Description:
+ spdn_cnt: (RO) Number of times libata decided to lower the
+ speed of link due to errors.
-class
- Device class. Can be "ata" for disk, "atapi" for packet device,
- "pmp" for PM, or "none" if no device was found behind the link.
+ gscr: (RO) Cached result of the dump of PM GSCR
+ register. Valid registers are:
-dma_mode
+ 0: SATA_PMP_GSCR_PROD_ID,
+ 1: SATA_PMP_GSCR_REV,
+ 2: SATA_PMP_GSCR_PORT_INFO,
+ 32: SATA_PMP_GSCR_ERROR,
+ 33: SATA_PMP_GSCR_ERROR_EN,
+ 64: SATA_PMP_GSCR_FEAT,
+ 96: SATA_PMP_GSCR_FEAT_EN,
+ 130: SATA_PMP_GSCR_SII_GPIO
- Transfer modes supported by the device when in DMA mode.
- Mostly used by PATA device.
+ Only valid if the device is a PM.
-pio_mode
+ ering: (RO) Formatted output of the error ring of the
+ device.
- Transfer modes supported by the device when in PIO mode.
- Mostly used by PATA device.
+ id: (RO) Cached result of IDENTIFY command, as
+ described in ATA8 7.16 and 7.17. Only valid if
+ the device is not a PM.
-xfer_mode
+ pio_mode: (RO) PIO transfer mode used by the device.
+ Mostly used by PATA devices.
- Current transfer mode.
+ xfer_mode: (RO) Current transfer mode. Mostly used by
+ PATA devices.
-id
+ dma_mode: (RO) DMA transfer mode used by the device.
+ Mostly used by PATA devices.
- Cached result of IDENTIFY command, as described in ATA8 7.16 and 7.17.
- Only valid if the device is not a PM.
+ class: (RO) Device class. Can be "ata" for disk,
+ "atapi" for packet device, "pmp" for PM, or
+ "none" if no device was found behind the link.
-gscr
- Cached result of the dump of PM GSCR register.
- Valid registers are:
- 0: SATA_PMP_GSCR_PROD_ID,
- 1: SATA_PMP_GSCR_REV,
- 2: SATA_PMP_GSCR_PORT_INFO,
- 32: SATA_PMP_GSCR_ERROR,
- 33: SATA_PMP_GSCR_ERROR_EN,
- 64: SATA_PMP_GSCR_FEAT,
- 96: SATA_PMP_GSCR_FEAT_EN,
- 130: SATA_PMP_GSCR_SII_GPIO
- Only valid if the device is a PM.
+What: /sys/class/ata_device/devX[.Y].Z/trim
+Date: May, 2015
+KernelVersion: v4.10
+Contact: Gwendal Grignou <gwendal@chromium.org>
+Description:
+ (RO) Shows the DSM TRIM mode currently used by the device. Valid
+ values are:
-spdn_cnt
+ unsupported: Drive does not support DSM TRIM
- Number of time libata decided to lower the speed of link due to errors.
+ unqueued: Drive supports unqueued DSM TRIM only
-ering
+ queued: Drive supports queued DSM TRIM
- Formatted output of the error ring of the device.
+ forced_unqueued: Drive's queued DSM support is known to
+ be buggy and only unqueued TRIM commands
+ are sent
diff --git a/Documentation/ABI/testing/sysfs-auxdisplay-linedisp b/Documentation/ABI/testing/sysfs-auxdisplay-linedisp
new file mode 100644
index 000000000000..55f1b559e84e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-auxdisplay-linedisp
@@ -0,0 +1,90 @@
+What: /sys/.../message
+Date: October 2021
+KernelVersion: 5.16
+Description:
+ Controls the text message displayed on character line displays.
+
+ Reading returns the current message with a trailing newline.
+ Writing updates the displayed message. Messages longer than the
+ display width will automatically scroll. Trailing newlines in
+ input are automatically trimmed.
+
+ Writing an empty string clears the display.
+
+ Example:
+ echo "Hello World" > message
+ cat message # Returns "Hello World\n"
+
+What: /sys/.../num_chars
+Date: November 2025
+KernelVersion: 6.18
+Contact: Jean-François Lessard <jefflessard3@gmail.com>
+Description:
+ Read-only attribute showing the character width capacity of
+ the line display device. Messages longer than this will scroll.
+
+ Example:
+ cat num_chars # Returns "16\n" for 16-char display
+
+What: /sys/.../scroll_step_ms
+Date: October 2021
+KernelVersion: 5.16
+Description:
+ Controls the scrolling speed for messages longer than the display
+ width, specified in milliseconds per scroll step.
+
+ Setting to 0 disables scrolling. Default is 500ms.
+
+ Example:
+ echo "250" > scroll_step_ms # 4Hz scrolling
+ cat scroll_step_ms # Returns "250\n"
+
+What: /sys/.../map_seg7
+Date: January 2024
+KernelVersion: 6.9
+Description:
+ Read/write binary blob representing the ASCII-to-7-segment
+ display conversion table used by the linedisp driver, as defined
+ by struct seg7_conversion_map in <linux/map_to_7segment.h>.
+
+ Only visible on displays with 7-segment capability.
+
+ This attribute is not human-readable. Writes must match the
+ struct size exactly, else -EINVAL is returned; reads return the
+ entire mapping as a binary blob.
+
+ This interface and its implementation match existing conventions
+ used in segment-mapped display drivers since 2005.
+
+ ABI note: This style of binary sysfs attribute *is an exception*
+ to current "one value per file, text only" sysfs rules, for
+ historical compatibility and driver uniformity. New drivers are
+ discouraged from introducing additional binary sysfs ABIs.
+
+ Reference interface guidance:
+ - include/uapi/linux/map_to_7segment.h
+
+What: /sys/.../map_seg14
+Date: January 2024
+KernelVersion: 6.9
+Description:
+ Read/write binary blob representing the ASCII-to-14-segment
+ display conversion table used by the linedisp driver, as defined
+ by struct seg14_conversion_map in <linux/map_to_14segment.h>.
+
+ Only visible on displays with 14-segment capability.
+
+ This attribute is not human-readable. Writes must match the
+ struct size exactly, else -EINVAL is returned; reads return the
+ entire mapping as a binary blob.
+
+ This interface and its implementation match existing conventions
+ used by segment-mapped display drivers since 2005.
+
+ ABI note: This style of binary sysfs attribute *is an exception*
+ to current "one value per file, text only" sysfs rules, for
+ historical compatibility and driver uniformity. New drivers are
+ discouraged from introducing additional binary sysfs ABIs.
+
+ Reference interface guidance:
+ - include/uapi/linux/map_to_14segment.h
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
deleted file mode 100644
index 8df003963d99..000000000000
--- a/Documentation/ABI/testing/sysfs-block
+++ /dev/null
@@ -1,230 +0,0 @@
-What: /sys/block/<disk>/stat
-Date: February 2008
-Contact: Jerome Marchand <jmarchan@redhat.com>
-Description:
- The /sys/block/<disk>/stat files displays the I/O
- statistics of disk <disk>. They contain 11 fields:
- 1 - reads completed successfully
- 2 - reads merged
- 3 - sectors read
- 4 - time spent reading (ms)
- 5 - writes completed
- 6 - writes merged
- 7 - sectors written
- 8 - time spent writing (ms)
- 9 - I/Os currently in progress
- 10 - time spent doing I/Os (ms)
- 11 - weighted time spent doing I/Os (ms)
- For more details refer Documentation/iostats.txt
-
-
-What: /sys/block/<disk>/<part>/stat
-Date: February 2008
-Contact: Jerome Marchand <jmarchan@redhat.com>
-Description:
- The /sys/block/<disk>/<part>/stat files display the
- I/O statistics of partition <part>. The format is the
- same as the above-written /sys/block/<disk>/stat
- format.
-
-
-What: /sys/block/<disk>/integrity/format
-Date: June 2008
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Metadata format for integrity capable block device.
- E.g. T10-DIF-TYPE1-CRC.
-
-
-What: /sys/block/<disk>/integrity/read_verify
-Date: June 2008
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Indicates whether the block layer should verify the
- integrity of read requests serviced by devices that
- support sending integrity metadata.
-
-
-What: /sys/block/<disk>/integrity/tag_size
-Date: June 2008
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Number of bytes of integrity tag space available per
- 512 bytes of data.
-
-
-What: /sys/block/<disk>/integrity/device_is_integrity_capable
-Date: July 2014
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Indicates whether a storage device is capable of storing
- integrity metadata. Set if the device is T10 PI-capable.
-
-
-What: /sys/block/<disk>/integrity/write_generate
-Date: June 2008
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Indicates whether the block layer should automatically
- generate checksums for write requests bound for
- devices that support receiving integrity metadata.
-
-What: /sys/block/<disk>/alignment_offset
-Date: April 2009
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Storage devices may report a physical block size that is
- bigger than the logical block size (for instance a drive
- with 4KB physical sectors exposing 512-byte logical
- blocks to the operating system). This parameter
- indicates how many bytes the beginning of the device is
- offset from the disk's natural alignment.
-
-What: /sys/block/<disk>/<partition>/alignment_offset
-Date: April 2009
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Storage devices may report a physical block size that is
- bigger than the logical block size (for instance a drive
- with 4KB physical sectors exposing 512-byte logical
- blocks to the operating system). This parameter
- indicates how many bytes the beginning of the partition
- is offset from the disk's natural alignment.
-
-What: /sys/block/<disk>/queue/logical_block_size
-Date: May 2009
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- This is the smallest unit the storage device can
- address. It is typically 512 bytes.
-
-What: /sys/block/<disk>/queue/physical_block_size
-Date: May 2009
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- This is the smallest unit a physical storage device can
- write atomically. It is usually the same as the logical
- block size but may be bigger. One example is SATA
- drives with 4KB sectors that expose a 512-byte logical
- block size to the operating system. For stacked block
- devices the physical_block_size variable contains the
- maximum physical_block_size of the component devices.
-
-What: /sys/block/<disk>/queue/minimum_io_size
-Date: April 2009
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Storage devices may report a granularity or preferred
- minimum I/O size which is the smallest request the
- device can perform without incurring a performance
- penalty. For disk drives this is often the physical
- block size. For RAID arrays it is often the stripe
- chunk size. A properly aligned multiple of
- minimum_io_size is the preferred request size for
- workloads where a high number of I/O operations is
- desired.
-
-What: /sys/block/<disk>/queue/optimal_io_size
-Date: April 2009
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Storage devices may report an optimal I/O size, which is
- the device's preferred unit for sustained I/O. This is
- rarely reported for disk drives. For RAID arrays it is
- usually the stripe width or the internal track size. A
- properly aligned multiple of optimal_io_size is the
- preferred request size for workloads where sustained
- throughput is desired. If no optimal I/O size is
- reported this file contains 0.
-
-What: /sys/block/<disk>/queue/nomerges
-Date: January 2010
-Contact:
-Description:
- Standard I/O elevator operations include attempts to
- merge contiguous I/Os. For known random I/O loads these
- attempts will always fail and result in extra cycles
- being spent in the kernel. This allows one to turn off
- this behavior on one of two ways: When set to 1, complex
- merge checks are disabled, but the simple one-shot merges
- with the previous I/O request are enabled. When set to 2,
- all merge tries are disabled. The default value is 0 -
- which enables all types of merge tries.
-
-What: /sys/block/<disk>/discard_alignment
-Date: May 2011
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Devices that support discard functionality may
- internally allocate space in units that are bigger than
- the exported logical block size. The discard_alignment
- parameter indicates how many bytes the beginning of the
- device is offset from the internal allocation unit's
- natural alignment.
-
-What: /sys/block/<disk>/<partition>/discard_alignment
-Date: May 2011
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Devices that support discard functionality may
- internally allocate space in units that are bigger than
- the exported logical block size. The discard_alignment
- parameter indicates how many bytes the beginning of the
- partition is offset from the internal allocation unit's
- natural alignment.
-
-What: /sys/block/<disk>/queue/discard_granularity
-Date: May 2011
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Devices that support discard functionality may
- internally allocate space using units that are bigger
- than the logical block size. The discard_granularity
- parameter indicates the size of the internal allocation
- unit in bytes if reported by the device. Otherwise the
- discard_granularity will be set to match the device's
- physical block size. A discard_granularity of 0 means
- that the device does not support discard functionality.
-
-What: /sys/block/<disk>/queue/discard_max_bytes
-Date: May 2011
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Devices that support discard functionality may have
- internal limits on the number of bytes that can be
- trimmed or unmapped in a single operation. Some storage
- protocols also have inherent limits on the number of
- blocks that can be described in a single command. The
- discard_max_bytes parameter is set by the device driver
- to the maximum number of bytes that can be discarded in
- a single operation. Discard requests issued to the
- device must not exceed this limit. A discard_max_bytes
- value of 0 means that the device does not support
- discard functionality.
-
-What: /sys/block/<disk>/queue/discard_zeroes_data
-Date: May 2011
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Devices that support discard functionality may return
- stale or random data when a previously discarded block
- is read back. This can cause problems if the filesystem
- expects discarded blocks to be explicitly cleared. If a
- device reports that it deterministically returns zeroes
- when a discarded area is read the discard_zeroes_data
- parameter will be set to one. Otherwise it will be 0 and
- the result of reading a discarded area is undefined.
-
-What: /sys/block/<disk>/queue/write_same_max_bytes
-Date: January 2012
-Contact: Martin K. Petersen <martin.petersen@oracle.com>
-Description:
- Some devices support a write same operation in which a
- single data block can be written to a range of several
- contiguous blocks on storage. This can be used to wipe
- areas on disk or to initialize drives in a RAID
- configuration. write_same_max_bytes indicates how many
- bytes can be written in a single write same command. If
- write_same_max_bytes is 0, write same is not supported
- by the device.
-
diff --git a/Documentation/ABI/testing/sysfs-block-aoe b/Documentation/ABI/testing/sysfs-block-aoe
new file mode 100644
index 000000000000..b5837765bcdd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-block-aoe
@@ -0,0 +1,45 @@
+What: /sys/block/etherd*/mac
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: Ed L. Cashin <ed.cashin@acm.org>
+Description:
+ (RO) The ethernet address of the remote Ata over Ethernet (AoE)
+ device.
+
+What: /sys/block/etherd*/netif
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: Ed L. Cashin <ed.cashin@acm.org>
+Description:
+ (RO) The names of the network interfaces on the localhost (comma
+ separated) through which we are communicating with the remote
+ AoE device.
+
+What: /sys/block/etherd*/state
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: Ed L. Cashin <ed.cashin@acm.org>
+Description:
+ (RO) Device status. The state attribute is "up" when the device
+ is ready for I/O and "down" if detected but unusable. The
+ "down,closewait" state shows that the device is still open and
+ cannot come up again until it has been closed. The "up,kickme"
+ state means that the driver wants to send more commands to the
+ target but found out there were already the max number of
+ commands waiting for a response. It will retry again after being
+ kicked by the periodic timer handler routine.
+
+What: /sys/block/etherd*/firmware-version
+Date: Apr, 2005
+KernelVersion: v2.6.12
+Contact: Ed L. Cashin <ed.cashin@acm.org>
+Description:
+ (RO) Version of the firmware in the target.
+
+What: /sys/block/etherd*/payload
+Date: Dec, 2012
+KernelVersion: v3.10
+Contact: Ed L. Cashin <ed.cashin@acm.org>
+Description:
+ (RO) The amount of user data transferred (in bytes) inside each AoE
+ command on the network, network headers excluded.
diff --git a/Documentation/ABI/testing/sysfs-block-bcache b/Documentation/ABI/testing/sysfs-block-bcache
index 9e4bbc5d51fd..9344a657ca70 100644
--- a/Documentation/ABI/testing/sysfs-block-bcache
+++ b/Documentation/ABI/testing/sysfs-block-bcache
@@ -106,13 +106,6 @@ Description:
will be discarded from the cache. Should not be turned off with
writeback caching enabled.
-What: /sys/block/<disk>/bcache/discard
-Date: November 2010
-Contact: Kent Overstreet <kent.overstreet@gmail.com>
-Description:
- For a cache, a boolean allowing discard/TRIM to be turned off
- or back on if the device supports it.
-
What: /sys/block/<disk>/bcache/bucket_size
Date: November 2010
Contact: Kent Overstreet <kent.overstreet@gmail.com>
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
new file mode 100644
index 000000000000..2d543cfa4079
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -0,0 +1,119 @@
+What: /sys/block/*/device/sw_activity
+Date: Jun, 2008
+KernelVersion: v2.6.27
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RW) Used by drivers which support software controlled activity
+ LEDs.
+
+ It has the following valid values:
+
+ == ========================================================
+ 0 OFF - the LED is not activated on activity
+ 1 BLINK_ON - the LED blinks on every 10ms when activity is
+ detected.
+ 2 BLINK_OFF - the LED is on when idle, and blinks off
+ every 10ms when activity is detected.
+ == ========================================================
+
+ Note that the user must turn sw_activity OFF it they wish to
+ control the activity LED via the em_message file.
+
+
+What: /sys/block/*/device/unload_heads
+Date: Sep, 2008
+KernelVersion: v2.6.28
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RW) Hard disk shock protection
+
+ Writing an integer value to this file will take the heads of the
+ respective drive off the platter and block all I/O operations
+ for the specified number of milliseconds.
+
+ - If the device does not support the unload heads feature,
+ access is denied with -EOPNOTSUPP.
+ - The maximal value accepted for a timeout is 30000
+ milliseconds.
+ - A previously set timeout can be cancelled and disk can resume
+ normal operation immediately by specifying a timeout of 0.
+ - Some hard drives only comply with an earlier version of the
+ ATA standard, but support the unload feature nonetheless.
+ There is no safe way Linux can detect these devices, so this
+ is not enabled by default. If it is known that your device
+ does support the unload feature, then you can tell the kernel
+ to enable it by writing -1. It can be disabled again by
+ writing -2.
+ - Values below -2 are rejected with -EINVAL
+
+ For more information, see
+ Documentation/admin-guide/laptops/disk-shock-protection.rst
+
+
+What: /sys/block/*/device/ncq_prio_enable
+Date: Oct, 2016
+KernelVersion: v4.10
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RW) Write to the file to turn on or off the SATA NCQ (native
+ command queueing) priority support. By default this feature is
+ turned off. If the device does not support the SATA NCQ
+ priority feature, writing "1" to this file results in an error
+ (see ncq_prio_supported).
+
+
+What: /sys/block/*/device/sas_ncq_prio_enable
+Date: Oct, 2016
+KernelVersion: v4.10
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RW) This is the equivalent of the ncq_prio_enable attribute
+ file for SATA devices connected to a SAS host-bus-adapter
+ (HBA) implementing support for the SATA NCQ priority feature.
+ This file does not exist if the HBA driver does not implement
+ support for the SATA NCQ priority feature, regardless of the
+ device support for this feature (see sas_ncq_prio_supported).
+
+
+What: /sys/block/*/device/ncq_prio_supported
+Date: Aug, 2021
+KernelVersion: v5.15
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RO) Indicates if the device supports the SATA NCQ (native
+ command queueing) priority feature.
+
+
+What: /sys/block/*/device/sas_ncq_prio_supported
+Date: Aug, 2021
+KernelVersion: v5.15
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RO) This is the equivalent of the ncq_prio_supported attribute
+ file for SATA devices connected to a SAS host-bus-adapter
+ (HBA) implementing support for the SATA NCQ priority feature.
+ This file does not exist if the HBA driver does not implement
+ support for the SATA NCQ priority feature, regardless of the
+ device support for this feature.
+
+
+What: /sys/block/*/device/cdl_supported
+Date: May, 2023
+KernelVersion: v6.5
+Contact: linux-scsi@vger.kernel.org
+Description:
+ (RO) Indicates if the device supports the command duration
+ limits feature found in some ATA and SCSI devices.
+
+
+What: /sys/block/*/device/cdl_enable
+Date: May, 2023
+KernelVersion: v6.5
+Contact: linux-scsi@vger.kernel.org
+Description:
+ (RW) For a device supporting the command duration limits
+ feature, write to the file to turn on or off the feature.
+ By default this feature is turned off.
+ Writing "1" to this file enables the use of command duration
+ limits for read and write commands in the kernel and turns on
+ the feature on the device. Writing "0" disables the feature.
diff --git a/Documentation/ABI/testing/sysfs-block-loop b/Documentation/ABI/testing/sysfs-block-loop
new file mode 100644
index 000000000000..627f4eb87286
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-block-loop
@@ -0,0 +1,50 @@
+What: /sys/block/loopX/loop/autoclear
+Date: Aug, 2010
+KernelVersion: v2.6.37
+Contact: linux-block@vger.kernel.org
+Description:
+ (RO) Shows if the device is in autoclear mode or not ( "1" or
+ "0"). Autoclear (if set) indicates that the loopback device will
+ self-distruct after last close.
+
+What: /sys/block/loopX/loop/backing_file
+Date: Aug, 2010
+KernelVersion: v2.6.37
+Contact: linux-block@vger.kernel.org
+Description:
+ (RO) The path of the backing file that the loop device maps its
+ data blocks to.
+
+What: /sys/block/loopX/loop/offset
+Date: Aug, 2010
+KernelVersion: v2.6.37
+Contact: linux-block@vger.kernel.org
+Description:
+ (RO) Start offset (in bytes).
+
+What: /sys/block/loopX/loop/sizelimit
+Date: Aug, 2010
+KernelVersion: v2.6.37
+Contact: linux-block@vger.kernel.org
+Description:
+ (RO) The size (in bytes) that the block device maps, starting
+ from the offset.
+
+What: /sys/block/loopX/loop/partscan
+Date: Aug, 2011
+KernelVersion: v3.10
+Contact: linux-block@vger.kernel.org
+Description:
+ (RO) Shows if automatic partition scanning is enabled for the
+ device or not ("1" or "0"). This can be requested individually
+ per loop device during its setup by setting LO_FLAGS_PARTSCAN in
+ in the ioctl request. By default, no partition tables are
+ scanned.
+
+What: /sys/block/loopX/loop/dio
+Date: Aug, 2015
+KernelVersion: v4.10
+Contact: linux-block@vger.kernel.org
+Description:
+ (RO) Shows if direct IO is being used to access backing file or
+ not ("1 or "0").
diff --git a/Documentation/ABI/testing/sysfs-block-rnbd b/Documentation/ABI/testing/sysfs-block-rnbd
new file mode 100644
index 000000000000..80b420b5d6b8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-block-rnbd
@@ -0,0 +1,64 @@
+What: /sys/block/rnbd<N>/rnbd/unmap_device
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: To unmap a volume, "normal" or "force" has to be written to:
+ /sys/block/rnbd<N>/rnbd/unmap_device
+
+ When "normal" is used, the operation will fail with EBUSY if any process
+ is using the device. When "force" is used, the device is also unmapped
+ when device is in use. All I/Os that are in progress will fail.
+
+ Example::
+
+ # echo "normal" > /sys/block/rnbd0/rnbd/unmap_device
+
+What: /sys/block/rnbd<N>/rnbd/state
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: The file contains the current state of the block device. The state file
+ returns "open" when the device is successfully mapped from the server
+ and accepting I/O requests. When the connection to the server gets
+ disconnected in case of an error (e.g. link failure), the state file
+ returns "closed" and all I/O requests submitted to it will fail with -EIO.
+
+What: /sys/block/rnbd<N>/rnbd/session
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RNBD uses RTRS session to transport the data between client and
+ server. The entry "session" contains the name of the session, that
+ was used to establish the RTRS session. It's the same name that
+ was passed as server parameter to the map_device entry.
+
+What: /sys/block/rnbd<N>/rnbd/mapping_path
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains the path that was passed as "device_path" to the map_device
+ operation.
+
+What: /sys/block/rnbd<N>/rnbd/access_mode
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains the device access mode: ro, rw or migration.
+
+What: /sys/block/rnbd<N>/rnbd/resize
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Write the number of sectors to change the size of the disk.
+
+What: /sys/block/rnbd<N>/rnbd/remap_device
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Remap the disconnected device if the session is not destroyed yet.
+
+What: /sys/block/rnbd<N>/rnbd/nr_poll_queues
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains the number of poll-mode queues
diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram
index 2e69e83bf510..36c57de0a10a 100644
--- a/Documentation/ABI/testing/sysfs-block-zram
+++ b/Documentation/ABI/testing/sysfs-block-zram
@@ -22,49 +22,6 @@ Description:
device. The reset operation frees all the memory associated
with this device.
-What: /sys/block/zram<id>/num_reads
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The num_reads file is read-only and specifies the number of
- reads (failed or successful) done on this device.
-
-What: /sys/block/zram<id>/num_writes
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The num_writes file is read-only and specifies the number of
- writes (failed or successful) done on this device.
-
-What: /sys/block/zram<id>/invalid_io
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The invalid_io file is read-only and specifies the number of
- non-page-size-aligned I/O requests issued to this device.
-
-What: /sys/block/zram<id>/failed_reads
-Date: February 2014
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The failed_reads file is read-only and specifies the number of
- failed reads happened on this device.
-
-What: /sys/block/zram<id>/failed_writes
-Date: February 2014
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The failed_writes file is read-only and specifies the number of
- failed writes happened on this device.
-
-What: /sys/block/zram<id>/max_comp_streams
-Date: February 2014
-Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
-Description:
- The max_comp_streams file is read-write and specifies the
- number of backend's zcomp_strm compression streams (number of
- concurrent compress operations).
-
What: /sys/block/zram<id>/comp_algorithm
Date: February 2014
Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
@@ -73,74 +30,24 @@ Description:
available and selected compression algorithms, change
compression algorithm selection.
-What: /sys/block/zram<id>/notify_free
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The notify_free file is read-only. Depending on device usage
- scenario it may account a) the number of pages freed because
- of swap slot free notifications or b) the number of pages freed
- because of REQ_DISCARD requests sent by bio. The former ones
- are sent to a swap block device when a swap slot is freed, which
- implies that this disk is being used as a swap disk. The latter
- ones are sent by filesystem mounted with discard option,
- whenever some data blocks are getting discarded.
-
-What: /sys/block/zram<id>/zero_pages
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The zero_pages file is read-only and specifies number of zero
- filled pages written to this disk. No memory is allocated for
- such pages.
-
-What: /sys/block/zram<id>/orig_data_size
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The orig_data_size file is read-only and specifies uncompressed
- size of data stored in this disk. This excludes zero-filled
- pages (zero_pages) since no memory is allocated for them.
- Unit: bytes
-
-What: /sys/block/zram<id>/compr_data_size
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The compr_data_size file is read-only and specifies compressed
- size of data stored in this disk. So, compression ratio can be
- calculated using orig_data_size and this statistic.
- Unit: bytes
-
-What: /sys/block/zram<id>/mem_used_total
-Date: August 2010
-Contact: Nitin Gupta <ngupta@vflare.org>
-Description:
- The mem_used_total file is read-only and specifies the amount
- of memory, including allocator fragmentation and metadata
- overhead, allocated for this disk. So, allocator space
- efficiency can be calculated using compr_data_size and this
- statistic.
- Unit: bytes
-
What: /sys/block/zram<id>/mem_used_max
Date: August 2014
Contact: Minchan Kim <minchan@kernel.org>
Description:
- The mem_used_max file is read/write and specifies the amount
- of maximum memory zram have consumed to store compressed data.
- For resetting the value, you should write "0". Otherwise,
- you could see -EINVAL.
+ The mem_used_max file is write-only and is used to reset
+ the counter of maximum memory zram have consumed to store
+ compressed data. For resetting the value, you should write
+ "0". Otherwise, you could see -EINVAL.
Unit: bytes
What: /sys/block/zram<id>/mem_limit
Date: August 2014
Contact: Minchan Kim <minchan@kernel.org>
Description:
- The mem_limit file is read/write and specifies the maximum
- amount of memory ZRAM can use to store the compressed data. The
- limit could be changed in run time and "0" means disable the
- limit. No limit is the initial state. Unit: bytes
+ The mem_limit file is write-only and specifies the maximum
+ amount of memory ZRAM can use to store the compressed data.
+ The limit could be changed in run time and "0" means disable
+ the limit. No limit is the initial state. Unit: bytes
What: /sys/block/zram<id>/compact
Date: August 2015
@@ -166,3 +73,80 @@ Description:
The mm_stat file is read-only and represents device's mm
statistics (orig_data_size, compr_data_size, etc.) in a format
similar to block layer statistics file format.
+
+What: /sys/block/zram<id>/debug_stat
+Date: July 2016
+Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+ The debug_stat file is read-only and represents various
+ device's debugging info useful for kernel developers. Its
+ format is not documented intentionally and may change
+ anytime without any notice.
+
+What: /sys/block/zram<id>/backing_dev
+Date: June 2017
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ The backing_dev file is read-write and set up backing
+ device for zram to write incompressible pages.
+ For using, user should enable CONFIG_ZRAM_WRITEBACK.
+
+What: /sys/block/zram<id>/idle
+Date: November 2018
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ idle file is write-only and mark zram slot as idle.
+ If system has mounted debugfs, user can see which slots
+ are idle via /sys/kernel/debug/zram/zram<id>/block_state
+
+What: /sys/block/zram<id>/writeback
+Date: November 2018
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ The writeback file is write-only and trigger idle and/or
+ huge page writeback to backing device.
+
+What: /sys/block/zram<id>/bd_stat
+Date: November 2018
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ The bd_stat file is read-only and represents backing device's
+ statistics (bd_count, bd_reads, bd_writes) in a format
+ similar to block layer statistics file format.
+
+What: /sys/block/zram<id>/writeback_limit_enable
+Date: November 2018
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ The writeback_limit_enable file is read-write and specifies
+ eanbe of writeback_limit feature. "1" means eable the feature.
+ No limit "0" is the initial state.
+
+What: /sys/block/zram<id>/writeback_limit
+Date: November 2018
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ The writeback_limit file is read-write and specifies the maximum
+ amount of writeback ZRAM can do. The limit could be changed
+ in run time.
+
+What: /sys/block/zram<id>/recomp_algorithm
+Date: November 2022
+Contact: Sergey Senozhatsky <senozhatsky@chromium.org>
+Description:
+ The recomp_algorithm file is read-write and allows to set
+ or show secondary compression algorithms.
+
+What: /sys/block/zram<id>/recompress
+Date: November 2022
+Contact: Sergey Senozhatsky <senozhatsky@chromium.org>
+Description:
+ The recompress file is write-only and triggers re-compression
+ with secondary compression algorithms.
+
+What: /sys/block/zram<id>/algorithm_params
+Date: August 2024
+Contact: Sergey Senozhatsky <senozhatsky@chromium.org>
+Description:
+ The algorithm_params file is write-only and is used to setup
+ compression algorithm parameters.
diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi
index 7fa9cbc75344..6f2b907a8013 100644
--- a/Documentation/ABI/testing/sysfs-bus-acpi
+++ b/Documentation/ABI/testing/sysfs-bus-acpi
@@ -1,17 +1,18 @@
What: /sys/bus/acpi/devices/.../path
Date: December 2006
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
This attribute indicates the full path of ACPI namespace
object associated with the device object. For example,
\_SB_.PCI0.
+
This file is not present for device objects representing
fixed ACPI hardware features (like power and sleep
buttons).
What: /sys/bus/acpi/devices/.../modalias
Date: July 2007
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
This attribute indicates the PNP IDs of the device object.
That is acpi:HHHHHHHH:[CCCCCCC:]. Where each HHHHHHHH or
@@ -19,7 +20,7 @@ Description:
What: /sys/bus/acpi/devices/.../hid
Date: April 2005
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
This attribute indicates the hardware ID (_HID) of the
device object. For example, PNP0103.
@@ -28,14 +29,14 @@ Description:
What: /sys/bus/acpi/devices/.../description
Date: October 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
This attribute contains the output of the device object's
_STR control method, if present.
What: /sys/bus/acpi/devices/.../adr
Date: October 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
This attribute contains the output of the device object's
_ADR control method, which is present for ACPI device
@@ -44,15 +45,54 @@ Description:
What: /sys/bus/acpi/devices/.../uid
Date: October 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
This attribute contains the output of the device object's
_UID control method, if present.
What: /sys/bus/acpi/devices/.../eject
Date: December 2006
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
Writing 1 to this attribute will trigger hot removal of
this device object. This file exists for every device
object that has _EJ0 method.
+
+What: /sys/bus/acpi/devices/.../status
+Date: Jan, 2014
+Contact: Rafael J. Wysocki <rafael@kernel.org>
+Description:
+ (RO) Returns the ACPI device status: enabled, disabled or
+ functioning or present, if the method _STA is present.
+
+ The return value is a decimal integer representing the device's
+ status bitmap:
+
+ =========== ==================================================
+ Bit [0] Set if the device is present.
+ Bit [1] Set if the device is enabled and decoding its
+ resources.
+ Bit [2] Set if the device should be shown in the UI.
+ Bit [3] Set if the device is functioning properly (cleared
+ if device failed its diagnostics).
+ Bit [4] Set if the battery is present.
+ Bits [31:5] Reserved (must be cleared)
+ =========== ==================================================
+
+ If bit [0] is clear, then bit 1 must also be clear (a device
+ that is not present cannot be enabled).
+
+ Bit 0 can be clear (not present) with bit [3] set (device is
+ functional). This case is used to indicate a valid device for
+ which no device driver should be loaded.
+
+ More special cases are covered in the ACPI specification.
+
+What: /sys/bus/acpi/devices/.../hrv
+Date: Apr, 2016
+Contact: Rafael J. Wysocki <rafael@kernel.org>
+Description:
+ (RO) Allows users to read the hardware version of non-PCI
+ hardware, if the _HRV control method is present. It is mostly
+ useful for non-PCI devices because lspci can list the hardware
+ version for PCI devices.
diff --git a/Documentation/ABI/testing/sysfs-bus-auxiliary b/Documentation/ABI/testing/sysfs-bus-auxiliary
new file mode 100644
index 000000000000..cc856079690f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-auxiliary
@@ -0,0 +1,9 @@
+What: /sys/bus/auxiliary/devices/.../irqs/
+Date: April, 2024
+Contact: Shay Drory <shayd@nvidia.com>
+Description:
+ The /sys/devices/.../irqs directory contains a variable set of
+ files, with each file is named as irq number similar to PCI PF
+ or VF's irq number located in msi_irqs directory.
+ These irq files are added and removed dynamically when an IRQ
+ is requested and freed respectively for the PCI SF.
diff --git a/Documentation/ABI/testing/sysfs-bus-bcma b/Documentation/ABI/testing/sysfs-bus-bcma
index 721b4aea3020..e93d3ddca844 100644
--- a/Documentation/ABI/testing/sysfs-bus-bcma
+++ b/Documentation/ABI/testing/sysfs-bus-bcma
@@ -3,7 +3,7 @@ Date: May 2011
KernelVersion: 3.0
Contact: Rafał Miłecki <zajec5@gmail.com>
Description:
- Each BCMA core has it's manufacturer id. See
+ Each BCMA core has its manufacturer id. See
include/linux/bcma/bcma.h for possible values.
What: /sys/bus/bcma/devices/.../id
diff --git a/Documentation/ABI/testing/sysfs-bus-cdx b/Documentation/ABI/testing/sysfs-bus-cdx
new file mode 100644
index 000000000000..e84277531414
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-cdx
@@ -0,0 +1,121 @@
+What: /sys/bus/cdx/rescan
+Date: March 2023
+Contact: nipun.gupta@amd.com
+Description:
+ Writing y/1/on to this file will cause rescan of the bus
+ and devices on the CDX bus. Any new devices are scanned and
+ added to the list of Linux devices and any devices removed are
+ also deleted from Linux.
+
+ For example::
+
+ # echo 1 > /sys/bus/cdx/rescan
+
+What: /sys/bus/cdx/devices/.../vendor
+Date: March 2023
+Contact: nipun.gupta@amd.com
+Description:
+ Vendor ID for this CDX device, in hexadecimal. Vendor ID is
+ 16 bit identifier which is specific to the device manufacturer.
+ Combination of Vendor ID and Device ID identifies a device.
+
+What: /sys/bus/cdx/devices/.../device
+Date: March 2023
+Contact: nipun.gupta@amd.com
+Description:
+ Device ID for this CDX device, in hexadecimal. Device ID is
+ 16 bit identifier to identify a device type within the range
+ of a device manufacturer.
+ Combination of Vendor ID and Device ID identifies a device.
+
+What: /sys/bus/cdx/devices/.../subsystem_vendor
+Date: July 2023
+Contact: puneet.gupta@amd.com
+Description:
+ Subsystem Vendor ID for this CDX device, in hexadecimal.
+ Subsystem Vendor ID is 16 bit identifier specific to the
+ card manufacturer.
+
+What: /sys/bus/cdx/devices/.../subsystem_device
+Date: July 2023
+Contact: puneet.gupta@amd.com
+Description:
+ Subsystem Device ID for this CDX device, in hexadecimal
+ Subsystem Device ID is 16 bit identifier specific to the
+ card manufacturer.
+
+What: /sys/bus/cdx/devices/.../class
+Date: July 2023
+Contact: puneet.gupta@amd.com
+Description:
+ This file contains the class of the CDX device, in hexadecimal.
+ Class is 24 bit identifier specifies the functionality of the device.
+
+What: /sys/bus/cdx/devices/.../revision
+Date: July 2023
+Contact: puneet.gupta@amd.com
+Description:
+ This file contains the revision field of the CDX device, in hexadecimal.
+ Revision is 8 bit revision identifier of the device.
+
+What: /sys/bus/cdx/devices/.../enable
+Date: October 2023
+Contact: abhijit.gangurde@amd.com
+Description:
+ CDX bus should be disabled before updating the devices in FPGA.
+ Writing n/0/off will attempt to disable the CDX bus and.
+ writing y/1/on will attempt to enable the CDX bus. Reading this file
+ gives the current state of the bus, 1 for enabled and 0 for disabled.
+
+ For example::
+
+ # echo 1 > /sys/bus/cdx/.../enable
+
+What: /sys/bus/cdx/devices/.../reset
+Date: March 2023
+Contact: nipun.gupta@amd.com
+Description:
+ Writing y/1/on to this file resets the CDX device or all devices
+ on the bus. On resetting the device, the corresponding driver is
+ notified twice, once before the device is being reset, and again
+ after the reset has been complete.
+
+ For example::
+
+ # echo 1 > /sys/bus/cdx/.../reset
+
+What: /sys/bus/cdx/devices/.../remove
+Date: March 2023
+Contact: tarak.reddy@amd.com
+Description:
+ Writing y/1/on to this file removes the corresponding
+ device from the CDX bus. If the device is to be reconfigured
+ reconfigured in the Hardware, the device can be removed, so
+ that the device driver does not access the device while it is
+ being reconfigured.
+
+ For example::
+
+ # echo 1 > /sys/bus/cdx/devices/.../remove
+
+What: /sys/bus/cdx/devices/.../resource<N>
+Date: July 2023
+Contact: puneet.gupta@amd.com
+Description:
+ The resource binary file contains the content of the memory
+ regions. These files can be m'maped from userspace.
+
+What: /sys/bus/cdx/devices/.../modalias
+Date: July 2023
+Contact: nipun.gupta@amd.com
+Description:
+ This attribute indicates the CDX ID of the device.
+ That is in the format:
+ cdx:vXXXXdXXXXsvXXXXsdXXXXcXXXXXX,
+ where:
+
+ - vXXXX contains the vendor ID;
+ - dXXXX contains the device ID;
+ - svXXXX contains the subsystem vendor ID;
+ - sdXXXX contains the subsystem device ID;
+ - cXXXXXX contains the device class.
diff --git a/Documentation/ABI/testing/sysfs-bus-coreboot b/Documentation/ABI/testing/sysfs-bus-coreboot
new file mode 100644
index 000000000000..8e8d6af24a4c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coreboot
@@ -0,0 +1,45 @@
+What: /sys/bus/coreboot
+Date: August 2022
+Contact: Jack Rosenthal <jrosenth@chromium.org>
+Description:
+ The coreboot bus provides a variety of virtual devices used to
+ access data structures created by the Coreboot BIOS.
+
+What: /sys/bus/coreboot/devices/cbmem-<id>
+Date: August 2022
+Contact: Jack Rosenthal <jrosenth@chromium.org>
+Description:
+ CBMEM is a downwards-growing memory region created by Coreboot,
+ and contains tagged data structures to be shared with payloads
+ in the boot process and the OS. Each CBMEM entry is given a
+ directory in /sys/bus/coreboot/devices based on its id.
+ A list of ids known to Coreboot can be found in the coreboot
+ source tree at
+ ``src/commonlib/bsd/include/commonlib/bsd/cbmem_id.h``.
+
+What: /sys/bus/coreboot/devices/cbmem-<id>/address
+Date: August 2022
+Contact: Jack Rosenthal <jrosenth@chromium.org>
+Description:
+ This is the physical memory address that the CBMEM entry's data
+ begins at, in hexadecimal (e.g., ``0x76ffe000``).
+
+What: /sys/bus/coreboot/devices/cbmem-<id>/size
+Date: August 2022
+Contact: Jack Rosenthal <jrosenth@chromium.org>
+Description:
+ This is the size of the CBMEM entry's data, in hexadecimal
+ (e.g., ``0x1234``).
+
+What: /sys/bus/coreboot/devices/cbmem-<id>/mem
+Date: August 2022
+Contact: Jack Rosenthal <jrosenth@chromium.org>
+Description:
+ A file exposing read/write access to the entry's data. Note
+ that this file does not support mmap(), as coreboot
+ does not guarantee that the data will be page-aligned.
+
+ The mode of this file is 0600. While there shouldn't be
+ anything security-sensitive contained in CBMEM, read access
+ requires root privileges given this is exposing a small subset
+ of physical memory.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
new file mode 100644
index 000000000000..a2aef7f5a6d7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
@@ -0,0 +1,247 @@
+What: /sys/bus/coresight/devices/<cti-name>/enable
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Enable/Disable the CTI hardware.
+
+What: /sys/bus/coresight/devices/<cti-name>/powered
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Indicate if the CTI hardware is powered.
+
+What: /sys/bus/coresight/devices/<cti-name>/ctmid
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Display the associated CTM ID
+
+What: /sys/bus/coresight/devices/<cti-name>/nr_trigger_cons
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Number of devices connected to triggers on this CTI
+
+What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/name
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Name of connected device <N>
+
+What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/in_signals
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Input trigger signals from connected device <N>
+
+What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/in_types
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Functional types for the input trigger signals
+ from connected device <N>
+
+What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/out_signals
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Output trigger signals to connected device <N>
+
+What: /sys/bus/coresight/devices/<cti-name>/triggers<N>/out_types
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Functional types for the output trigger signals
+ to connected device <N>
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/inout_sel
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Select the index for inen and outen registers.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/inen
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Read or write the CTIINEN register selected by inout_sel.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/outen
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Read or write the CTIOUTEN register selected by inout_sel.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/gate
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Read or write CTIGATE register.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/asicctl
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Read or write ASICCTL register.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/intack
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Write the INTACK register.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/appset
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Set CTIAPPSET register to activate channel. Read back to
+ determine current value of register.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/appclear
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Write APPCLEAR register to deactivate channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/apppulse
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Write APPPULSE to pulse a channel active for one clock
+ cycle.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/chinstatus
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Read current status of channel inputs.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/choutstatus
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) read current status of channel outputs.
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/triginstatus
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) read current status of input trigger signals
+
+What: /sys/bus/coresight/devices/<cti-name>/regs/trigoutstatus
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) read current status of output trigger signals.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/trigin_attach
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Attach a CTI input trigger to a CTM channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/trigin_detach
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Detach a CTI input trigger from a CTM channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_attach
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Attach a CTI output trigger to a CTM channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_detach
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Detach a CTI output trigger from a CTM channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_gate_enable
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Enable CTIGATE for single channel (Write) or list enabled
+ channels through the gate (R).
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_gate_disable
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Disable CTIGATE for single channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_set
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Activate a single channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_clear
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Deactivate a single channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_pulse
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Pulse a single channel - activate for a single clock cycle.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/trigout_filtered
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) List of output triggers filtered across all connections.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/trig_filter_enable
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Enable or disable trigger output signal filtering.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_inuse
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) show channels with at least one attached trigger signal.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_free
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) show channels with no attached trigger signals.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_sel
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (RW) Write channel number to select a channel to view, read to
+ see selected channel number.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_in
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Read to see input triggers connected to selected view
+ channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_out
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Read) Read to see output triggers connected to selected view
+ channel.
+
+What: /sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_reset
+Date: March 2020
+KernelVersion: 5.7
+Contact: Mike Leach or Mathieu Poirier
+Description: (Write) Clear all channel / trigger programming.
+
+What: /sys/bus/coresight/devices/<cti-name>/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source b/Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source
new file mode 100644
index 000000000000..321e3ee1fc9d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source
@@ -0,0 +1,21 @@
+What: /sys/bus/coresight/devices/dummy_source<N>/enable_source
+Date: Dec 2024
+KernelVersion: 6.14
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (RW) Enable/disable tracing of dummy source. A sink should be activated
+ before enabling the source. The path of coresight components linking
+ the source to the sink is configured and managed automatically by the
+ coresight framework.
+
+What: /sys/bus/coresight/devices/dummy_source<N>/traceid
+Date: Dec 2024
+KernelVersion: 6.14
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (R) Show the trace ID that will appear in the trace stream
+ coming from this trace entity.
+
+What: /sys/bus/coresight/devices/dummy_source<N>/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
index 4b8d6ec92e2b..f30526949687 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
@@ -4,14 +4,10 @@ KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
Description: (RW) Add/remove a sink from a trace path. There can be multiple
source for a single sink.
- ex: echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink
-What: /sys/bus/coresight/devices/<memory_map>.etb/status
-Date: November 2014
-KernelVersion: 3.19
-Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (R) List various control and status registers. The specific
- layout and content is driver specific.
+ ex::
+
+ echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink
What: /sys/bus/coresight/devices/<memory_map>.etb/trigger_cntr
Date: November 2014
@@ -22,3 +18,71 @@ Description: (RW) Disables write access to the Trace RAM by stopping the
following the trigger event. The number of 32-bit words written
into the Trace RAM following the trigger event is equal to the
value stored in this register+1 (from ARM ETB-TRM).
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rdp
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Defines the depth, in words, of the trace RAM in powers of
+ 2. The value is read directly from HW register RDP, 0x004.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/sts
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the ETB status register. The value
+ is read directly from HW register STS, 0x00C.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rrp
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the ETB RAM Read Pointer register
+ that is used to read entries from the Trace RAM over the APB
+ interface. The value is read directly from HW register RRP,
+ 0x014.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rwp
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the ETB RAM Write Pointer register
+ that is used to sets the write pointer to write entries from
+ the CoreSight bus into the Trace RAM. The value is read directly
+ from HW register RWP, 0x018.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/trg
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Similar to "trigger_cntr" above except that this value is
+ read directly from HW register TRG, 0x01C.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ctl
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the ETB Control register. The value
+ is read directly from HW register CTL, 0x020.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffsr
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the ETB Formatter and Flush Status
+ register. The value is read directly from HW register FFSR,
+ 0x300.
+
+What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffcr
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the ETB Formatter and Flush Control
+ register. The value is read directly from HW register FFCR,
+ 0x304.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
index b4d0b99afffb..245c322c91f1 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
@@ -8,13 +8,6 @@ Description: (RW) Enable/disable tracing on this specific trace entiry.
of coresight components linking the source to the sink is
configured and managed automatically by the coresight framework.
-What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/status
-Date: November 2014
-KernelVersion: 3.19
-Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (R) List various control and status registers. The specific
- layout and content is driver specific.
-
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_idx
Date: November 2014
KernelVersion: 3.19
@@ -29,7 +22,7 @@ Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
Description: (RW) Used in conjunction with @addr_idx. Specifies
characteristics about the address comparator being configure,
for example the access type, the kind of instruction to trace,
- processor contect ID to trigger on, etc. Individual fields in
+ processor context ID to trigger on, etc. Individual fields in
the access type register may vary on the version of the trace
entity.
@@ -38,7 +31,7 @@ Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
Description: (RW) Used in conjunction with @addr_idx. Specifies the range of
- addresses to trigger on. Inclusion or exclusion is specificed
+ addresses to trigger on. Inclusion or exclusion is specified
in the corresponding access type register.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_single
@@ -112,7 +105,7 @@ KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
Description: (RW) Mask to apply to all the context ID comparator.
-What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_val
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_pid
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
@@ -153,28 +146,28 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (R) Provides the number of address comparators pairs accessible
+Description: (Read) Provides the number of address comparators pairs accessible
on a trace unit, as specified by bit 3:0 of register ETMCCR.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (R) Provides the number of counters accessible on a trace unit,
+Description: (Read) Provides the number of counters accessible on a trace unit,
as specified by bit 15:13 of register ETMCCR.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (R) Provides the number of context ID comparator available on a
+Description: (Read) Provides the number of context ID comparator available on a
trace unit, as specified by bit 25:24 of register ETMCCR.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (W) Cancels all configuration on a trace unit and set it back
+Description: (Write) Cancels all configuration on a trace unit and set it back
to its boot configuration.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event
@@ -223,7 +216,7 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (R) Holds the current state of the sequencer.
+Description: (Read) Holds the current state of the sequencer.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq
Date: November 2014
@@ -243,7 +236,7 @@ What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/traceid
Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: (RW) Holds the trace ID that will appear in the trace stream
+Description: (RO) Holds the trace ID that will appear in the trace stream
coming from this trace entity.
What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/trigger_event
@@ -251,3 +244,85 @@ Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
Description: (RW) Define the event that controls the trigger.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cpu
+Date: October 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Holds the cpu number this tracer is affined to.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmccr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Configuration Code register
+ (0x004). The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmccer
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Configuration Code Extension
+ register (0x1e8). The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmscr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM System Configuration
+ register (0x014). The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmidr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM ID register (0x1e4). The
+ value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmcr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Main Control register (0x000).
+ The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtraceidr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Trace ID register (0x200).
+ The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmteevr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Trace Enable Event register
+ (0x020). The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtsscr
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Trace Start/Stop Control
+ register (0x018). The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr1
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Enable Control #1
+ register (0x024). The value is read directly from the HW.
+
+What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr2
+Date: September 2015
+KernelVersion: 4.4
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RO) Print the content of the ETM Enable Control #2
+ register (0x01c). The value is read directly from the HW.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
new file mode 100644
index 000000000000..6f19a6a5f2e1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
@@ -0,0 +1,532 @@
+What: /sys/bus/coresight/devices/etm<N>/enable_source
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Enable/disable tracing on this specific trace entiry.
+ Enabling a source implies the source has been configured
+ properly and a sink has been identidifed for it. The path
+ of coresight components linking the source to the sink is
+ configured and managed automatically by the coresight framework.
+
+What: /sys/bus/coresight/devices/etm<N>/cpu
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) The CPU this tracing entity is associated with.
+
+What: /sys/bus/coresight/devices/etm<N>/nr_pe_cmp
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of PE comparator inputs that are
+ available for tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/nr_addr_cmp
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of address comparator pairs that are
+ available for tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/nr_cntr
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of counters that are available for
+ tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/nr_ext_inp
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates how many external inputs are implemented.
+
+What: /sys/bus/coresight/devices/etm<N>/numcidc
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of Context ID comparators that are
+ available for tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/numvmidc
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of VMID comparators that are available
+ for tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/nrseqstate
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of sequencer states that are
+ implemented.
+
+What: /sys/bus/coresight/devices/etm<N>/nr_resource
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of resource selection pairs that are
+ available for tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/nr_ss_cmp
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the number of single-shot comparator controls that
+ are available for tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/reset
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Write) Cancels all configuration on a trace unit and set it back
+ to its boot configuration.
+
+What: /sys/bus/coresight/devices/etm<N>/mode
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls various modes supported by this ETM, for example
+ P0 instruction tracing, branch broadcast, cycle counting and
+ context ID tracing.
+
+What: /sys/bus/coresight/devices/etm<N>/pe
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls which PE to trace.
+
+What: /sys/bus/coresight/devices/etm<N>/event
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls the tracing of arbitrary events from bank 0 to 3.
+
+What: /sys/bus/coresight/devices/etm<N>/event_instren
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls the behavior of the events in bank 0 to 3.
+
+What: /sys/bus/coresight/devices/etm<N>/event_ts
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls the insertion of global timestamps in the trace
+ streams.
+
+What: /sys/bus/coresight/devices/etm<N>/syncfreq
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls how often trace synchronization requests occur.
+
+What: /sys/bus/coresight/devices/etm<N>/cyc_threshold
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Sets the threshold value for cycle counting.
+
+What: /sys/bus/coresight/devices/etm<N>/bb_ctrl
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls which regions in the memory map are enabled to
+ use branch broadcasting.
+
+What: /sys/bus/coresight/devices/etm<N>/event_vinst
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls instruction trace filtering.
+
+What: /sys/bus/coresight/devices/etm<N>/s_exlevel_vinst
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) In Secure state, each bit controls whether instruction
+ tracing is enabled for the corresponding exception level.
+
+What: /sys/bus/coresight/devices/etm<N>/ns_exlevel_vinst
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) In non-secure state, each bit controls whether instruction
+ tracing is enabled for the corresponding exception level.
+
+What: /sys/bus/coresight/devices/etm<N>/addr_idx
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select which address comparator or pair (of comparators) to
+ work with.
+
+What: /sys/bus/coresight/devices/etm<N>/addr_instdatatype
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls what type of comparison the trace unit performs.
+
+What: /sys/bus/coresight/devices/etm<N>/addr_single
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Used to setup single address comparator values.
+
+What: /sys/bus/coresight/devices/etm<N>/addr_range
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Used to setup address range comparator values.
+
+What: /sys/bus/coresight/devices/etm<N>/seq_idx
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select which sequensor.
+
+What: /sys/bus/coresight/devices/etm<N>/seq_state
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Use this to set, or read, the sequencer state.
+
+What: /sys/bus/coresight/devices/etm<N>/seq_event
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Moves the sequencer state to a specific state.
+
+What: /sys/bus/coresight/devices/etm<N>/seq_reset_event
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Moves the sequencer to state 0 when a programmed event
+ occurs.
+
+What: /sys/bus/coresight/devices/etm<N>/cntr_idx
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select which counter unit to work with.
+
+What: /sys/bus/coresight/devices/etm<N>/cntrldvr
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) This sets or returns the reload count value of the
+ specific counter.
+
+What: /sys/bus/coresight/devices/etm<N>/cntr_val
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) This sets or returns the current count value of the
+ specific counter.
+
+What: /sys/bus/coresight/devices/etm<N>/cntr_ctrl
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls the operation of the selected counter.
+
+What: /sys/bus/coresight/devices/etm<N>/res_idx
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select which resource selection unit to work with.
+
+What: /sys/bus/coresight/devices/etm<N>/res_ctrl
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Controls the selection of the resources in the trace unit.
+
+What: /sys/bus/coresight/devices/etm<N>/ctxid_idx
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select which context ID comparator to work with.
+
+What: /sys/bus/coresight/devices/etm<N>/ctxid_pid
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Get/Set the context ID comparator value to trigger on.
+
+What: /sys/bus/coresight/devices/etm<N>/ctxid_masks
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Mask for all 8 context ID comparator value
+ registers (if implemented).
+
+What: /sys/bus/coresight/devices/etm<N>/vmid_idx
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select which virtual machine ID comparator to work with.
+
+What: /sys/bus/coresight/devices/etm<N>/vmid_val
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Get/Set the virtual machine ID comparator value to
+ trigger on.
+
+What: /sys/bus/coresight/devices/etm<N>/vmid_masks
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Mask for all 8 virtual machine ID comparator value
+ registers (if implemented).
+
+What: /sys/bus/coresight/devices/etm<N>/addr_exlevel_s_ns
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Set the Exception Level matching bits for secure and
+ non-secure exception levels.
+
+What: /sys/bus/coresight/devices/etm<N>/vinst_pe_cmp_start_stop
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Access the start stop control register for PE input
+ comparators.
+
+What: /sys/bus/coresight/devices/etm<N>/addr_cmp_view
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the current settings for the selected address
+ comparator.
+
+What: /sys/bus/coresight/devices/etm<N>/sshot_idx
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Select the single shot control register to access.
+
+What: /sys/bus/coresight/devices/etm<N>/sshot_ctrl
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Access the selected single shot control register.
+
+What: /sys/bus/coresight/devices/etm<N>/sshot_status
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the current value of the selected single shot
+ status register.
+
+What: /sys/bus/coresight/devices/etm<N>/sshot_pe_ctrl
+Date: December 2019
+KernelVersion: 5.5
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Access the selected single show PE comparator control
+ register.
+
+What: /sys/bus/coresight/devices/etm<N>/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcoslsr
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the OS Lock Status Register (0x304).
+ The value it taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpdcr
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Power Down Control Register
+ (0x310). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpdsr
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Power Down Status Register
+ (0x314). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trclsr
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the SW Lock Status Register
+ (0xFB4). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcauthstatus
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Authentication Status Register
+ (0xFB8). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevid
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Device ID Register
+ (0xFC8). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevarch
+Date: January 2021
+KernelVersion: 5.12
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Device Architecture Register
+ (offset 0xFBC). The value is taken directly read
+ from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcdevtype
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Device Type Register
+ (0xFCC). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr0
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Peripheral ID0 Register
+ (0xFE0). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr1
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Peripheral ID1 Register
+ (0xFE4). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr2
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Peripheral ID2 Register
+ (0xFE8). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcpidr3
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the Peripheral ID3 Register
+ (0xFEC). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trcconfig
+Date: February 2016
+KernelVersion: 4.07
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the trace configuration register
+ (0x010) as currently set by SW.
+
+What: /sys/bus/coresight/devices/etm<N>/mgmt/trctraceid
+Date: February 2016
+KernelVersion: 4.07
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Print the content of the trace ID register (0x040).
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr0
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the tracing capabilities of the trace unit (0x1E0).
+ The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr1
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the tracing capabilities of the trace unit (0x1E4).
+ The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr2
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the maximum size of the data value, data address,
+ VMID, context ID and instruction address in the trace unit
+ (0x1E8). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr3
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the value associated with various resources
+ available to the trace unit. See the Trace Macrocell
+ architecture specification for more details (0x1E8).
+ The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr4
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns how many resources the trace unit supports (0x1F0).
+ The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr5
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns how many resources the trace unit supports (0x1F4).
+ The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr8
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the maximum speculation depth of the instruction
+ trace stream. (0x180). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr9
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the number of P0 right-hand keys that the trace unit
+ can use (0x184). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr10
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the number of P1 right-hand keys that the trace unit
+ can use (0x188). The value is taken directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr11
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the number of special P1 right-hand keys that the
+ trace unit can use (0x18C). The value is taken directly from
+ the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr12
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the number of conditional P1 right-hand keys that
+ the trace unit can use (0x190). The value is taken directly
+ from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/trcidr/trcidr13
+Date: April 2015
+KernelVersion: 4.01
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Returns the number of special conditional P1 right-hand keys
+ that the trace unit can use (0x194). The value is taken
+ directly from the HW.
+
+What: /sys/bus/coresight/devices/etm<N>/ts_source
+Date: October 2022
+KernelVersion: 6.1
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org> or Suzuki K Poulose <suzuki.poulose@arm.com>
+Description: (Read) When FEAT_TRF is implemented, value of TRFCR_ELx.TS used for
+ trace session. Otherwise -1 indicates an unknown time source. Check
+ trcidr0.tssize to see if a global timestamp is available.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel
index d75acda5e1b3..86938e9bbcde 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel
@@ -10,3 +10,9 @@ Date: November 2014
KernelVersion: 3.19
Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
Description: (RW) Defines input port priority order.
+
+What: /sys/bus/coresight/devices/<memory_map>.funnel/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
new file mode 100644
index 000000000000..848e2ffc1480
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
@@ -0,0 +1,59 @@
+What: /sys/bus/coresight/devices/<memory_map>.stm/enable_source
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Enable/disable tracing on this specific trace macrocell.
+ Enabling the trace macrocell implies it has been configured
+ properly and a sink has been identified for it. The path
+ of coresight components linking the source to the sink is
+ configured and managed automatically by the coresight framework.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/hwevent_enable
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Provides access to the HW event enable register, used in
+ conjunction with HW event bank select register.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/hwevent_select
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Gives access to the HW event block select register
+ (STMHEBSR) in order to configure up to 256 channels. Used in
+ conjunction with "hwevent_enable" register as described above.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/port_enable
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Provides access to the stimulus port enable register
+ (STMSPER). Used in conjunction with "port_select" described
+ below.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/port_select
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Used to determine which bank of stimulus port bit in
+ register STMSPER (see above) apply to.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/status
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) List various control and status registers. The specific
+ layout and content is driver specific.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/traceid
+Date: April 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Holds the trace ID that will appear in the trace stream
+ coming from this trace entity.
+
+What: /sys/bus/coresight/devices/<memory_map>.stm/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
index f38cded5fa22..55e298b9c4a4 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
@@ -6,3 +6,110 @@ Description: (RW) Disables write access to the Trace RAM by stopping the
formatter after a defined number of words have been stored
following the trigger event. Additional interface for this
driver are expected to be added as it matures.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rsz
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Defines the size, in 32-bit words, of the local RAM buffer.
+ The value is read directly from HW register RSZ, 0x004.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/sts
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC status register. The value
+ is read directly from HW register STS, 0x00C.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rrp
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC RAM Read Pointer register
+ that is used to read entries from the Trace RAM over the APB
+ interface. The value is read directly from HW register RRP,
+ 0x014.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rwp
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC RAM Write Pointer register
+ that is used to sets the write pointer to write entries from
+ the CoreSight bus into the Trace RAM. The value is read directly
+ from HW register RWP, 0x018.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/trg
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Similar to "trigger_cntr" above except that this value is
+ read directly from HW register TRG, 0x01C.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ctl
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC Control register. The value
+ is read directly from HW register CTL, 0x020.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffsr
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC Formatter and Flush Status
+ register. The value is read directly from HW register FFSR,
+ 0x300.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffcr
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC Formatter and Flush Control
+ register. The value is read directly from HW register FFCR,
+ 0x304.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/mode
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Shows the value held by the TMC Mode register, which
+ indicate the mode the device has been configured to enact. The
+ The value is read directly from the MODE register, 0x028.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/devid
+Date: March 2016
+KernelVersion: 4.7
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (Read) Indicates the capabilities of the Coresight TMC.
+ The value is read directly from the DEVID register, 0xFC8,
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/buffer_size
+Date: December 2018
+KernelVersion: 4.19
+Contact: Mathieu Poirier <mathieu.poirier@linaro.org>
+Description: (RW) Size of the trace buffer for TMC-ETR when used in SYSFS
+ mode. Writable only for TMC-ETR configurations. The value
+ should be aligned to the kernel pagesize.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/buf_modes_available
+Date: August 2023
+KernelVersion: 6.7
+Contact: Anshuman Khandual <anshuman.khandual@arm.com>
+Description: (Read) Shows all supported Coresight TMC-ETR buffer modes available
+ for the users to configure explicitly. This file is available only
+ for TMC ETR devices.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/buf_mode_preferred
+Date: August 2023
+KernelVersion: 6.7
+Contact: Anshuman Khandual <anshuman.khandual@arm.com>
+Description: (RW) Current Coresight TMC-ETR buffer mode selected. But user could
+ only provide a mode which is supported for a given ETR device. This
+ file is available only for TMC ETR devices.
+
+What: /sys/bus/coresight/devices/<memory_map>.tmc/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm
new file mode 100644
index 000000000000..98f1c6545027
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm
@@ -0,0 +1,280 @@
+What: /sys/bus/coresight/devices/<tpdm-name>/integration_test
+Date: January 2023
+KernelVersion: 6.2
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (Write) Run integration test for tpdm. Integration test
+ will generate test data for tpdm. It can help to make
+ sure that the trace path is enabled and the link configurations
+ are fine.
+
+ Accepts only one of the 2 values - 1 or 2.
+ 1 : Generate 64 bits data
+ 2 : Generate 32 bits data
+
+What: /sys/bus/coresight/devices/<tpdm-name>/reset_dataset
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (Write) Reset the dataset of the tpdm.
+
+ Accepts only one value - 1.
+ 1 : Reset the dataset of the tpdm
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_trig_type
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the trigger type of the DSB for tpdm.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Set the DSB trigger type to false
+ 1 : Set the DSB trigger type to true
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_trig_ts
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the trigger timestamp of the DSB for tpdm.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Set the DSB trigger type to false
+ 1 : Set the DSB trigger type to true
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_mode
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the programming mode of the DSB for tpdm.
+
+ Accepts the value needs to be greater than 0. What data
+ bits do is listed below.
+ Bit[0:1] : Test mode control bit for choosing the inputs.
+ Bit[3] : Set to 0 for low performance mode. Set to 1 for high
+ performance mode.
+ Bit[4:8] : Select byte lane for high performance mode.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_edge/ctrl_idx
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the index number of the edge detection for the DSB
+ subunit TPDM. Since there are at most 256 edge detections, this
+ value ranges from 0 to 255.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_edge/ctrl_val
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ Write a data to control the edge detection corresponding to
+ the index number. Before writing data to this sysfs file,
+ "ctrl_idx" should be written first to configure the index
+ number of the edge detection which needs to be controlled.
+
+ Accepts only one of the following values.
+ 0 - Rising edge detection
+ 1 - Falling edge detection
+ 2 - Rising and falling edge detection (toggle detection)
+
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_edge/ctrl_mask
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ Write a data to mask the edge detection corresponding to the index
+ number. Before writing data to this sysfs file, "ctrl_idx" should
+ be written first to configure the index number of the edge detection
+ which needs to be masked.
+
+ Accepts only one of the 2 values - 0 or 1.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_edge/edcr[0:15]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ Read a set of the edge control value of the DSB in TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_edge/edcmr[0:7]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ Read a set of the edge control mask of the DSB in TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_trig_patt/xpr[0:7]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the value of the trigger pattern for the DSB
+ subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_trig_patt/xpmr[0:7]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the mask of the trigger pattern for the DSB
+ subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_patt/tpr[0:7]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the value of the pattern for the DSB subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_patt/tpmr[0:7]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the mask of the pattern for the DSB subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_patt/enable_ts
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (Write) Set the pattern timestamp of DSB tpdm. Read
+ the pattern timestamp of DSB tpdm.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Disable DSB pattern timestamp.
+ 1 : Enable DSB pattern timestamp.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_patt/set_type
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (Write) Set the pattern type of DSB tpdm. Read
+ the pattern type of DSB tpdm.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Set the DSB pattern type to value.
+ 1 : Set the DSB pattern type to toggle.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_msr/msr[0:31]
+Date: March 2023
+KernelVersion: 6.7
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the MSR(mux select register) for the DSB subunit
+ TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_mode
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description: (Write) Set the data collection mode of CMB tpdm. Continuous
+ change creates CMB data set elements on every CMBCLK edge.
+ Trace-on-change creates CMB data set elements only when a new
+ data set element differs in value from the previous element
+ in a CMB data set.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Continuous CMB collection mode.
+ 1 : Trace-on-change CMB collection mode.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_trig_patt/xpr[0:1]
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the value of the trigger pattern for the CMB
+ subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_trig_patt/xpmr[0:1]
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the mask of the trigger pattern for the CMB
+ subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_patt/tpr[0:1]
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the value of the pattern for the CMB subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/dsb_patt/tpmr[0:1]
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the mask of the pattern for the CMB subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_patt/enable_ts
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (Write) Set the pattern timestamp of CMB tpdm. Read
+ the pattern timestamp of CMB tpdm.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Disable CMB pattern timestamp.
+ 1 : Enable CMB pattern timestamp.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_trig_ts
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the trigger timestamp of the CMB for tpdm.
+
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Set the CMB trigger type to false
+ 1 : Set the CMB trigger type to true
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_ts_all
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Read or write the status of timestamp upon all interface.
+ Only value 0 and 1 can be written to this node. Set this node to 1 to request
+ timestamp to all trace packet.
+ Accepts only one of the 2 values - 0 or 1.
+ 0 : Disable the timestamp of all trace packets.
+ 1 : Enable the timestamp of all trace packets.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/cmb_msr/msr[0:31]
+Date: January 2024
+KernelVersion: 6.9
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the MSR(mux select register) for the CMB subunit
+ TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/mcmb_trig_lane
+Date: Feb 2025
+KernelVersion 6.15
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get which lane participates in the output pattern
+ match cross trigger mechanism for the MCMB subunit TPDM.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/mcmb_lanes_select
+Date: Feb 2025
+KernelVersion 6.15
+Contact: Jinlong Mao (QUIC) <quic_jinlmao@quicinc.com>, Tao Zhang (QUIC) <quic_taozha@quicinc.com>
+Description:
+ (RW) Set/Get the enablement of the individual lane.
+
+What: /sys/bus/coresight/devices/<tpdm-name>/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe b/Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe
new file mode 100644
index 000000000000..8a4b749ed26e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-trbe
@@ -0,0 +1,20 @@
+What: /sys/bus/coresight/devices/trbe<cpu>/align
+Date: March 2021
+KernelVersion: 5.13
+Contact: Anshuman Khandual <anshuman.khandual@arm.com>
+Description: (Read) Shows the TRBE write pointer alignment. This value
+ is fetched from the TRBIDR register.
+
+What: /sys/bus/coresight/devices/trbe<cpu>/flag
+Date: March 2021
+KernelVersion: 5.13
+Contact: Anshuman Khandual <anshuman.khandual@arm.com>
+Description: (Read) Shows if TRBE updates in the memory are with access
+ and dirty flag updates as well. This value is fetched from
+ the TRBIDR register.
+
+What: /sys/bus/coresight/devices/trbe<cpu>/label
+Date: Aug 2025
+KernelVersion 6.18
+Contact: Mao Jinlong <quic_jinlmao@quicinc.com>
+Description: (Read) Show hardware context information of device.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb b/Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb
new file mode 100644
index 000000000000..f560918ae738
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-ultra_smb
@@ -0,0 +1,31 @@
+What: /sys/bus/coresight/devices/ultra_smb<N>/enable_sink
+Date: January 2023
+KernelVersion: 6.3
+Contact: Junhao He <hejunhao3@huawei.com>
+Description: (RW) Add/remove a SMB device from a trace path. There can be
+ multiple sources for a single SMB device.
+
+What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/buf_size
+Date: January 2023
+KernelVersion: 6.3
+Contact: Junhao He <hejunhao3@huawei.com>
+Description: (RO) Shows the buffer size of each UltraSoc SMB device.
+
+What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/buf_status
+Date: January 2023
+KernelVersion: 6.3
+Contact: Junhao He <hejunhao3@huawei.com>
+Description: (RO) Shows the value of UltraSoc SMB status register.
+ BIT(0) is zero means buffer is empty.
+
+What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/read_pos
+Date: January 2023
+KernelVersion: 6.3
+Contact: Junhao He <hejunhao3@huawei.com>
+Description: (RO) Shows the value of UltraSoc SMB Read Pointer register.
+
+What: /sys/bus/coresight/devices/ultra_smb<N>/mgmt/write_pos
+Date: January 2023
+KernelVersion: 6.3
+Contact: Junhao He <hejunhao3@huawei.com>
+Description: (RO) Shows the value of UltraSoc SMB Write Pointer register.
diff --git a/Documentation/ABI/testing/sysfs-bus-counter b/Documentation/ABI/testing/sysfs-bus-counter
new file mode 100644
index 000000000000..3e7eddd8aff3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-counter
@@ -0,0 +1,477 @@
+What: /sys/bus/counter/devices/counterX/cascade_counts_enable
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ Indicates the cascading of Counts on Counter X.
+
+ Valid attribute values are boolean.
+
+What: /sys/bus/counter/devices/counterX/external_input_phase_clock_select
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ Selects the external clock pin for phase counting mode of
+ Counter X.
+
+ MTCLKA-MTCLKB:
+ MTCLKA and MTCLKB pins are selected for the external
+ phase clock.
+
+ MTCLKC-MTCLKD:
+ MTCLKC and MTCLKD pins are selected for the external
+ phase clock.
+
+What: /sys/bus/counter/devices/counterX/external_input_phase_clock_select_available
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ Discrete set of available values for the respective device
+ configuration are listed in this file.
+
+What: /sys/bus/counter/devices/counterX/countY/count
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Count data of Count Y represented as a string.
+
+What: /sys/bus/counter/devices/counterX/countY/compare
+KernelVersion: 6.15
+Contact: linux-iio@vger.kernel.org
+Description:
+ If the counter device supports compare registers -- registers
+ used to compare counter channels against a particular count --
+ the compare count for channel Y is provided by this attribute.
+
+What: /sys/bus/counter/devices/counterX/countY/capture
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Historical capture of the Count Y count data.
+
+What: /sys/bus/counter/devices/counterX/countY/ceiling
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Count value ceiling for Count Y. This is the upper limit for the
+ respective counter.
+
+What: /sys/bus/counter/devices/counterX/countY/floor
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Count value floor for Count Y. This is the lower limit for the
+ respective counter.
+
+What: /sys/bus/counter/devices/counterX/countY/count_mode
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Count mode for channel Y. The ceiling and floor values for
+ Count Y are used by the count mode where required. The following
+ count modes are available:
+
+ normal:
+ Counting is continuous in either direction.
+
+ range limit:
+ An upper or lower limit is set, mimicking limit switches
+ in the mechanical counterpart. The upper limit is set to
+ the Count Y ceiling value, while the lower limit is set
+ to the Count Y floor value. The counter freezes at
+ count = ceiling when counting up, and at count = floor
+ when counting down. At either of these limits, the
+ counting is resumed only when the count direction is
+ reversed.
+
+ non-recycle:
+ The counter is disabled whenever a counter overflow or
+ underflow takes place. The counter is re-enabled when a
+ new count value is loaded to the counter via a preset
+ operation or direct write.
+
+ modulo-n:
+ A count value boundary is set between the Count Y floor
+ value and the Count Y ceiling value. The counter is
+ reset to the Count Y floor value at count = ceiling when
+ counting up, while the counter is set to the Count Y
+ ceiling value at count = floor when counting down; the
+ counter does not freeze at the boundary points, but
+ counts continuously throughout.
+
+ interrupt on terminal count:
+ The output signal is initially low, and will remain low
+ until the counter reaches zero. The output signal then
+ goes high and remains high until a new preset value is
+ set.
+
+ hardware retriggerable one-shot:
+ The output signal is initially high. The output signal
+ will go low by a trigger input signal, and will remain
+ low until the counter reaches zero. The output will then
+ go high and remain high until the next trigger. A
+ trigger results in loading the counter to the preset
+ value and setting the output signal low, thus starting
+ the one-shot pulse.
+
+ rate generator:
+ The output signal is initially high. When the counter
+ has decremented to 1, the output signal goes low for one
+ clock pulse. The output signal then goes high again, the
+ counter is reloaded to the preset value, and the process
+ repeats in a periodic manner as such.
+
+ square wave mode:
+ The output signal is initially high.
+
+ If the initial count is even, the counter is decremented
+ by two on succeeding clock pulses. When the count
+ expires, the output signal changes value and the
+ counter is reloaded to the preset value. The process
+ repeats in periodic manner as such.
+
+ If the initial count is odd, the initial count minus one
+ (an even number) is loaded and then is decremented by
+ two on succeeding clock pulses. One clock pulse after
+ the count expires, the output signal goes low and the
+ counter is reloaded to the preset value minus one.
+ Succeeding clock pulses decrement the count by two. When
+ the count expires, the output goes high again and the
+ counter is reloaded to the preset value minus one. The
+ process repeats in a periodic manner as such.
+
+ software triggered strobe:
+ The output signal is initially high. When the count
+ expires, the output will go low for one clock pulse and
+ then go high again. The counting sequence is "triggered"
+ by setting the preset value.
+
+ hardware triggered strobe:
+ The output signal is initially high. Counting is started
+ by a trigger input signal. When the count expires, the
+ output signal will go low for one clock pulse and then
+ go high again. A trigger results in loading the counter
+ to the preset value.
+
+What: /sys/bus/counter/devices/counterX/countY/count_mode_available
+What: /sys/bus/counter/devices/counterX/countY/error_noise_available
+What: /sys/bus/counter/devices/counterX/countY/function_available
+What: /sys/bus/counter/devices/counterX/countY/prescaler_available
+What: /sys/bus/counter/devices/counterX/countY/signalZ_action_available
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Discrete set of available values for the respective Count Y
+ configuration are listed in this file. Values are delimited by
+ newline characters.
+
+What: /sys/bus/counter/devices/counterX/countY/direction
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the count direction of Count
+ Y. Two count directions are available: forward and backward.
+
+ Some counter devices are able to determine the direction of
+ their counting. For example, quadrature encoding counters can
+ determine the direction of movement by evaluating the leading
+ phase of the respective A and B quadrature encoding signals.
+ This attribute exposes such count directions.
+
+What: /sys/bus/counter/devices/counterX/countY/enable
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Whether channel Y counter is enabled. Valid attribute values are
+ boolean.
+
+ This attribute is intended to serve as a pause/unpause mechanism
+ for Count Y. Suppose a counter device is used to count the total
+ movement of a conveyor belt: this attribute allows an operator
+ to temporarily pause the counter, service the conveyor belt,
+ and then finally unpause the counter to continue where it had
+ left off.
+
+What: /sys/bus/counter/devices/counterX/countY/error_noise
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates whether excessive noise is
+ present at the channel Y counter inputs.
+
+What: /sys/bus/counter/devices/counterX/countY/function
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Count function mode of Count Y; count function evaluation is
+ triggered by conditions specified by the Count Y signalZ_action
+ attributes. The following count functions are available:
+
+ increase:
+ Accumulated count is incremented.
+
+ decrease:
+ Accumulated count is decremented.
+
+ pulse-direction:
+ Rising edges on signal A updates the respective count.
+ The input level of signal B determines direction.
+
+ quadrature x1 a:
+ If direction is forward, rising edges on quadrature pair
+ signal A updates the respective count; if the direction
+ is backward, falling edges on quadrature pair signal A
+ updates the respective count. Quadrature encoding
+ determines the direction.
+
+ quadrature x1 b:
+ If direction is forward, rising edges on quadrature pair
+ signal B updates the respective count; if the direction
+ is backward, falling edges on quadrature pair signal B
+ updates the respective count. Quadrature encoding
+ determines the direction.
+
+ quadrature x2 a:
+ Any state transition on quadrature pair signal A updates
+ the respective count. Quadrature encoding determines the
+ direction.
+
+ quadrature x2 b:
+ Any state transition on quadrature pair signal B updates
+ the respective count. Quadrature encoding determines the
+ direction.
+
+ quadrature x4:
+ Any state transition on either quadrature pair signals
+ updates the respective count. Quadrature encoding
+ determines the direction.
+
+What: /sys/bus/counter/devices/counterX/countY/name
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the device-specific name of
+ Count Y. If possible, this should match the name of the
+ respective channel as it appears in the device datasheet.
+
+What: /sys/bus/counter/devices/counterX/countY/prescaler
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Configure the prescaler value associated with Count Y.
+ On the FlexTimer, the counter clock source passes through a
+ prescaler (i.e. a counter). This acts like a clock
+ divider.
+
+What: /sys/bus/counter/devices/counterX/countY/preset
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ If the counter device supports preset registers -- registers
+ used to load counter channels to a set count upon device-defined
+ preset operation trigger events -- the preset count for channel
+ Y is provided by this attribute.
+
+What: /sys/bus/counter/devices/counterX/countY/preset_enable
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Whether channel Y counter preset operation is enabled. Valid
+ attribute values are boolean.
+
+What: /sys/bus/counter/devices/counterX/countY/signalZ_action
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Action mode of Count Y for Signal Z. This attribute indicates
+ the condition of Signal Z that triggers the count function
+ evaluation for Count Y. The following action modes are
+ available:
+
+ none:
+ Signal does not trigger the count function. In
+ Pulse-Direction count function mode, this Signal is
+ evaluated as Direction.
+
+ rising edge:
+ Low state transitions to high state.
+
+ falling edge:
+ High state transitions to low state.
+
+ both edges:
+ Any state transition.
+
+What: /sys/bus/counter/devices/counterX/countY/num_overflows
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute indicates the number of overflows of count Y.
+
+What: /sys/bus/counter/devices/counterX/cascade_counts_enable_component_id
+What: /sys/bus/counter/devices/counterX/external_input_phase_clock_select_component_id
+What: /sys/bus/counter/devices/counterX/countY/capture_component_id
+What: /sys/bus/counter/devices/counterX/countY/ceiling_component_id
+What: /sys/bus/counter/devices/counterX/countY/compare_component_id
+What: /sys/bus/counter/devices/counterX/countY/count_mode_component_id
+What: /sys/bus/counter/devices/counterX/countY/direction_component_id
+What: /sys/bus/counter/devices/counterX/countY/enable_component_id
+What: /sys/bus/counter/devices/counterX/countY/error_noise_component_id
+What: /sys/bus/counter/devices/counterX/countY/floor_component_id
+What: /sys/bus/counter/devices/counterX/countY/num_overflows_component_id
+What: /sys/bus/counter/devices/counterX/countY/prescaler_component_id
+What: /sys/bus/counter/devices/counterX/countY/preset_component_id
+What: /sys/bus/counter/devices/counterX/countY/preset_enable_component_id
+What: /sys/bus/counter/devices/counterX/countY/signalZ_action_component_id
+What: /sys/bus/counter/devices/counterX/signalY/cable_fault_component_id
+What: /sys/bus/counter/devices/counterX/signalY/cable_fault_enable_component_id
+What: /sys/bus/counter/devices/counterX/signalY/filter_clock_prescaler_component_id
+What: /sys/bus/counter/devices/counterX/signalY/frequency_component_id
+What: /sys/bus/counter/devices/counterX/signalY/index_polarity_component_id
+What: /sys/bus/counter/devices/counterX/signalY/polarity_component_id
+What: /sys/bus/counter/devices/counterX/signalY/synchronous_mode_component_id
+KernelVersion: 5.16
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the component ID of the
+ respective extension or Synapse.
+
+What: /sys/bus/counter/devices/counterX/countY/spike_filter_ns
+KernelVersion: 5.14
+Contact: linux-iio@vger.kernel.org
+Description:
+ If the counter device supports programmable spike filter this
+ attribute indicates the value in nanoseconds where noise pulses
+ shorter or equal to configured value are ignored. Value 0 means
+ filter is disabled.
+
+What: /sys/bus/counter/devices/counterX/events_queue_size
+KernelVersion: 5.16
+Contact: linux-iio@vger.kernel.org
+Description:
+ Size of the Counter events queue in number of struct
+ counter_event data structures. The number of elements will be
+ rounded-up to a power of 2.
+
+What: /sys/bus/counter/devices/counterX/name
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the device-specific name of
+ the Counter. This should match the name of the device as it
+ appears in its respective datasheet.
+
+What: /sys/bus/counter/devices/counterX/num_counts
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the total number of Counts
+ belonging to the Counter.
+
+What: /sys/bus/counter/devices/counterX/num_signals
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the total number of Signals
+ belonging to the Counter.
+
+What: /sys/bus/counter/devices/counterX/signalY/cable_fault
+KernelVersion: 5.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates whether a differential
+ encoder cable fault (not connected or loose wires) is detected
+ for the respective channel of Signal Y. Valid attribute values
+ are boolean. Detection must first be enabled via the
+ corresponding cable_fault_enable attribute.
+
+What: /sys/bus/counter/devices/counterX/signalY/cable_fault_enable
+KernelVersion: 5.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Whether detection of differential encoder cable faults for the
+ respective channel of Signal Y is enabled. Valid attribute
+ values are boolean.
+
+What: /sys/bus/counter/devices/counterX/signalY/filter_clock_prescaler
+KernelVersion: 5.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Filter clock factor for input Signal Y. This prescaler value
+ affects the inputs of both quadrature pair signals.
+
+What: /sys/bus/counter/devices/counterX/signalY/index_polarity
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Active level of index input Signal Y; irrelevant in
+ non-synchronous load mode.
+
+What: /sys/bus/counter/devices/counterX/signalY/index_polarity_available
+What: /sys/bus/counter/devices/counterX/signalY/synchronous_mode_available
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Discrete set of available values for the respective Signal Y
+ configuration are listed in this file.
+
+What: /sys/bus/counter/devices/counterX/signalY/polarity
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Active level of Signal Y. The following polarity values are
+ available:
+
+ positive:
+ Signal high state considered active level (rising edge).
+
+ negative:
+ Signal low state considered active level (falling edge).
+
+What: /sys/bus/counter/devices/counterX/signalY/name
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the device-specific name of
+ Signal Y. If possible, this should match the name of the
+ respective signal as it appears in the device datasheet.
+
+What: /sys/bus/counter/devices/counterX/signalY/signal
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Signal level state of Signal Y. The following signal level
+ states are available:
+
+ low:
+ Low level state.
+
+ high:
+ High level state.
+
+What: /sys/bus/counter/devices/counterX/signalY/synchronous_mode
+KernelVersion: 5.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Configure the counter associated with Signal Y for
+ non-synchronous or synchronous load mode. Synchronous load mode
+ cannot be selected in non-quadrature (Pulse-Direction) clock
+ mode.
+
+ non-synchronous:
+ A logic low level is the active level at this index
+ input. The index function (as enabled via preset_enable)
+ is performed directly on the active level of the index
+ input.
+
+ synchronous:
+ Intended for interfacing with encoder Index output in
+ quadrature clock mode. The active level is configured
+ via index_polarity. The index function (as enabled via
+ preset_enable) is performed synchronously with the
+ quadrature clock on the active level of the index input.
+
+What: /sys/bus/counter/devices/counterX/signalY/frequency
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read-only attribute that indicates the signal Y frequency, in Hz.
diff --git a/Documentation/ABI/testing/sysfs-bus-css b/Documentation/ABI/testing/sysfs-bus-css
index 2979c40c10e9..d4d5cfb63b90 100644
--- a/Documentation/ABI/testing/sysfs-bus-css
+++ b/Documentation/ABI/testing/sysfs-bus-css
@@ -1,35 +1,56 @@
What: /sys/bus/css/devices/.../type
Date: March 2008
-Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
- linux-s390@vger.kernel.org
+Contact: linux-s390@vger.kernel.org
Description: Contains the subchannel type, as reported by the hardware.
This attribute is present for all subchannel types.
What: /sys/bus/css/devices/.../modalias
Date: March 2008
-Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
- linux-s390@vger.kernel.org
+Contact: linux-s390@vger.kernel.org
Description: Contains the module alias as reported with uevents.
It is of the format css:t<type> and present for all
subchannel types.
What: /sys/bus/css/drivers/io_subchannel/.../chpids
Date: December 2002
-Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
- linux-s390@vger.kernel.org
+Contact: linux-s390@vger.kernel.org
Description: Contains the ids of the channel paths used by this
subchannel, as reported by the channel subsystem
during subchannel recognition.
+
Note: This is an I/O-subchannel specific attribute.
Users: s390-tools, HAL
What: /sys/bus/css/drivers/io_subchannel/.../pimpampom
Date: December 2002
-Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
- linux-s390@vger.kernel.org
+Contact: linux-s390@vger.kernel.org
Description: Contains the PIM/PAM/POM values, as reported by the
channel subsystem when last queried by the common I/O
layer (this implies that this attribute is not necessarily
in sync with the values current in the channel subsystem).
+
Note: This is an I/O-subchannel specific attribute.
Users: s390-tools, HAL
+
+What: /sys/bus/css/devices/.../driver_override
+Date: June 2019
+Contact: linux-s390@vger.kernel.org
+Description: This file allows the driver for a device to be specified. When
+ specified, only a driver with a name matching the value written
+ to driver_override will have an opportunity to bind to the
+ device. The override is specified by writing a string to the
+ driver_override file (echo vfio-ccw > driver_override) and
+ may be cleared with an empty string (echo > driver_override).
+ This returns the device to standard matching rules binding.
+ Writing to driver_override does not automatically unbind the
+ device from its current driver or make any attempt to
+ automatically load the specified driver. If no driver with a
+ matching name is currently loaded in the kernel, the device
+ will not bind to any driver. This also allows devices to
+ opt-out of driver binding using a driver_override name such as
+ "none". Only a single driver may be specified in the override,
+ there is no support for parsing delimiters.
+
+ Note that unlike the mechanism of the same name for pci, this
+ file does not allow to override basic matching rules. I.e.,
+ the driver must still match the subchannel type of the device.
diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl
new file mode 100644
index 000000000000..c80a1b5a03db
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-cxl
@@ -0,0 +1,626 @@
+What: /sys/bus/cxl/flush
+Date: January, 2022
+KernelVersion: v5.18
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) If userspace manually unbinds a port the kernel schedules
+ all descendant memdevs for unbind. Writing '1' to this attribute
+ flushes that work.
+
+
+What: /sys/bus/cxl/devices/memX/firmware_version
+Date: December, 2020
+KernelVersion: v5.12
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) "FW Revision" string as reported by the Identify
+ Memory Device Output Payload in the CXL-2.0
+ specification.
+
+
+What: /sys/bus/cxl/devices/memX/payload_max
+Date: December, 2020
+KernelVersion: v5.12
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) Maximum size (in bytes) of the mailbox command payload
+ registers. Linux caps this at 1MB if the device reports a
+ larger size.
+
+
+What: /sys/bus/cxl/devices/memX/label_storage_size
+Date: May, 2021
+KernelVersion: v5.13
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) Size (in bytes) of the Label Storage Area (LSA).
+
+
+What: /sys/bus/cxl/devices/memX/ram/size
+Date: December, 2020
+KernelVersion: v5.12
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) "Volatile Only Capacity" as bytes. Represents the
+ identically named field in the Identify Memory Device Output
+ Payload in the CXL-2.0 specification.
+
+
+What: /sys/bus/cxl/devices/memX/ram/qos_class
+Date: May, 2023
+KernelVersion: v6.8
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) For CXL host platforms that support "QoS Telemetry"
+ this attribute conveys a comma delimited list of platform
+ specific cookies that identifies a QoS performance class
+ for the volatile partition of the CXL mem device. These
+ class-ids can be compared against a similar "qos_class"
+ published for a root decoder. While it is not required
+ that the endpoints map their local memory-class to a
+ matching platform class, mismatches are not recommended
+ and there are platform specific performance related
+ side-effects that may result. First class-id is displayed.
+
+
+What: /sys/bus/cxl/devices/memX/pmem/size
+Date: December, 2020
+KernelVersion: v5.12
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) "Persistent Only Capacity" as bytes. Represents the
+ identically named field in the Identify Memory Device Output
+ Payload in the CXL-2.0 specification.
+
+
+What: /sys/bus/cxl/devices/memX/pmem/qos_class
+Date: May, 2023
+KernelVersion: v6.8
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) For CXL host platforms that support "QoS Telemetry"
+ this attribute conveys a comma delimited list of platform
+ specific cookies that identifies a QoS performance class
+ for the persistent partition of the CXL mem device. These
+ class-ids can be compared against a similar "qos_class"
+ published for a root decoder. While it is not required
+ that the endpoints map their local memory-class to a
+ matching platform class, mismatches are not recommended
+ and there are platform specific performance related
+ side-effects that may result. First class-id is displayed.
+
+
+What: /sys/bus/cxl/devices/memX/serial
+Date: January, 2022
+KernelVersion: v5.18
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) 64-bit serial number per the PCIe Device Serial Number
+ capability. Mandatory for CXL devices, see CXL 2.0 8.1.12.2
+ Memory Device PCIe Capabilities and Extended Capabilities.
+
+
+What: /sys/bus/cxl/devices/memX/numa_node
+Date: January, 2022
+KernelVersion: v5.18
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) If NUMA is enabled and the platform has affinitized the
+ host PCI device for this memory device, emit the CPU node
+ affinity for this device.
+
+
+What: /sys/bus/cxl/devices/memX/security/state
+Date: June, 2023
+KernelVersion: v6.5
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) Reading this file will display the CXL security state for
+ that device. Such states can be: 'disabled', 'sanitize', when
+ a sanitization is currently underway; or those available only
+ for persistent memory: 'locked', 'unlocked' or 'frozen'. This
+ sysfs entry is select/poll capable from userspace to notify
+ upon completion of a sanitize operation.
+
+
+What: /sys/bus/cxl/devices/memX/security/sanitize
+Date: June, 2023
+KernelVersion: v6.5
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) Write a boolean 'true' string value to this attribute to
+ sanitize the device to securely re-purpose or decommission it.
+ This is done by ensuring that all user data and meta-data,
+ whether it resides in persistent capacity, volatile capacity,
+ or the LSA, is made permanently unavailable by whatever means
+ is appropriate for the media type. This functionality requires
+ the device to be disabled, that is, not actively decoding any
+ HPA ranges. This permits avoiding explicit global CPU cache
+ management, relying instead for it to be done when a region
+ transitions between software programmed and hardware committed
+ states. If this file is not present, then there is no hardware
+ support for the operation.
+
+
+What /sys/bus/cxl/devices/memX/security/erase
+Date: June, 2023
+KernelVersion: v6.5
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) Write a boolean 'true' string value to this attribute to
+ secure erase user data by changing the media encryption keys for
+ all user data areas of the device. This functionality requires
+ the device to be disabled, that is, not actively decoding any
+ HPA ranges. This permits avoiding explicit global CPU cache
+ management, relying instead for it to be done when a region
+ transitions between software programmed and hardware committed
+ states. If this file is not present, then there is no hardware
+ support for the operation.
+
+
+What: /sys/bus/cxl/devices/memX/firmware/
+Date: April, 2023
+KernelVersion: v6.5
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Firmware uploader mechanism. The different files under
+ this directory can be used to upload and activate new
+ firmware for CXL devices. The interfaces under this are
+ documented in sysfs-class-firmware.
+
+
+What: /sys/bus/cxl/devices/*/devtype
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL device objects export the devtype attribute which
+ mirrors the same value communicated in the DEVTYPE environment
+ variable for uevents for devices on the "cxl" bus.
+
+
+What: /sys/bus/cxl/devices/*/modalias
+Date: December, 2021
+KernelVersion: v5.18
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL device objects export the modalias attribute which
+ mirrors the same value communicated in the MODALIAS environment
+ variable for uevents for devices on the "cxl" bus.
+
+
+What: /sys/bus/cxl/devices/portX/uport
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL port objects are enumerated from either a platform
+ firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream
+ port with CXL component registers. The 'uport' symlink connects
+ the CXL portX object to the device that published the CXL port
+ capability.
+
+
+What: /sys/bus/cxl/devices/{port,endpoint}X/parent_dport
+Date: January, 2023
+KernelVersion: v6.3
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL port objects are instantiated for each upstream port in
+ a CXL/PCIe switch, and for each endpoint to map the
+ corresponding memory device into the CXL port hierarchy. When a
+ descendant CXL port (switch or endpoint) is enumerated it is
+ useful to know which 'dport' object in the parent CXL port
+ routes to this descendant. The 'parent_dport' symlink points to
+ the device representing the downstream port of a CXL switch that
+ routes to {port,endpoint}X.
+
+
+What: /sys/bus/cxl/devices/portX/dportY
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL port objects are enumerated from either a platform
+ firmware device (ACPI0017 and ACPI0016) or PCIe switch upstream
+ port with CXL component registers. The 'dportY' symlink
+ identifies one or more downstream ports that the upstream port
+ may target in its decode of CXL memory resources. The 'Y'
+ integer reflects the hardware port unique-id used in the
+ hardware decoder target list.
+
+
+What: /sys/bus/cxl/devices/portX/decoders_committed
+Date: October, 2023
+KernelVersion: v6.7
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) A memory device is considered active when any of its
+ decoders are in the "committed" state (See CXL 3.0 8.2.4.19.7
+ CXL HDM Decoder n Control Register). Hotplug and destructive
+ operations like "sanitize" are blocked while device is actively
+ decoding a Host Physical Address range. Note that this number
+ may be elevated without any regionX objects active or even
+ enumerated, as this may be due to decoders established by
+ platform firmware or a previous kernel (kexec).
+
+
+What: /sys/bus/cxl/devices/decoderX.Y
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL decoder objects are enumerated from either a platform
+ firmware description, or a CXL HDM decoder register set in a
+ PCIe device (see CXL 2.0 section 8.2.5.12 CXL HDM Decoder
+ Capability Structure). The 'X' in decoderX.Y represents the
+ cxl_port container of this decoder, and 'Y' represents the
+ instance id of a given decoder resource.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/{start,size}
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The 'start' and 'size' attributes together convey the
+ physical address base and number of bytes mapped in the
+ decoder's decode window. For decoders of devtype
+ "cxl_decoder_root" the address range is fixed. For decoders of
+ devtype "cxl_decoder_switch" the address is bounded by the
+ decode range of the cxl_port ancestor of the decoder's cxl_port,
+ and dynamically updates based on the active memory regions in
+ that address space.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/locked
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) CXL HDM decoders have the capability to lock the
+ configuration until the next device reset. For decoders of
+ devtype "cxl_decoder_root" there is no standard facility to
+ unlock them. For decoders of devtype "cxl_decoder_switch" a
+ secondary bus reset, of the PCIe bridge that provides the bus
+ for this decoders uport, unlocks / resets the decoder.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/target_list
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) Display a comma separated list of the current decoder
+ target configuration. The list is ordered by the current
+ configured interleave order of the decoder's dport instances.
+ Each entry in the list is a dport id.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/cap_{pmem,ram,type2,type3}
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) When a CXL decoder is of devtype "cxl_decoder_root", it
+ represents a fixed memory window identified by platform
+ firmware. A fixed window may only support a subset of memory
+ types. The 'cap_*' attributes indicate whether persistent
+ memory, volatile memory, accelerator memory, and / or expander
+ memory may be mapped behind this decoder's memory window.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/target_type
+Date: June, 2021
+KernelVersion: v5.14
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) When a CXL decoder is of devtype "cxl_decoder_switch", it
+ can optionally decode either accelerator memory (type-2) or
+ expander memory (type-3). The 'target_type' attribute indicates
+ the current setting which may dynamically change based on what
+ memory regions are activated in this decode hierarchy.
+
+
+What: /sys/bus/cxl/devices/endpointX/CDAT
+Date: July, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) If this sysfs entry is not present no DOE mailbox was
+ found to support CDAT data. If it is present and the length of
+ the data is 0 reading the CDAT data failed. Otherwise the CDAT
+ data is reported.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/mode
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) When a CXL decoder is of devtype "cxl_decoder_endpoint" it
+ translates from a host physical address range, to a device
+ local address range. Device-local address ranges are further
+ split into a 'ram' (volatile memory) range and 'pmem'
+ (persistent memory) range. The 'mode' attribute emits one of
+ 'ram', 'pmem', or 'none'. The 'none' indicates the decoder is
+ not actively decoding, or no DPA allocation policy has been
+ set.
+
+ 'mode' can be written, when the decoder is in the 'disabled'
+ state, with either 'ram' or 'pmem' to set the boundaries for the
+ next allocation.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/dpa_resource
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) When a CXL decoder is of devtype "cxl_decoder_endpoint",
+ and its 'dpa_size' attribute is non-zero, this attribute
+ indicates the device physical address (DPA) base address of the
+ allocation.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/dpa_size
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) When a CXL decoder is of devtype "cxl_decoder_endpoint" it
+ translates from a host physical address range, to a device local
+ address range. The range, base address plus length in bytes, of
+ DPA allocated to this decoder is conveyed in these 2 attributes.
+ Allocations can be mutated as long as the decoder is in the
+ disabled state. A write to 'dpa_size' releases the previous DPA
+ allocation and then attempts to allocate from the free capacity
+ in the device partition referred to by 'decoderX.Y/mode'.
+ Allocate and free requests can only be performed on the highest
+ instance number disabled decoder with non-zero size. I.e.
+ allocations are enforced to occur in increasing 'decoderX.Y/id'
+ order and frees are enforced to occur in decreasing
+ 'decoderX.Y/id' order.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/interleave_ways
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The number of targets across which this decoder's host
+ physical address (HPA) memory range is interleaved. The device
+ maps every Nth block of HPA (of size ==
+ 'interleave_granularity') to consecutive DPA addresses. The
+ decoder's position in the interleave is determined by the
+ device's (endpoint or switch) switch ancestry. For root
+ decoders their interleave is specified by platform firmware and
+ they only specify a downstream target order for host bridges.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/interleave_granularity
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The number of consecutive bytes of host physical address
+ space this decoder claims at address N before the decode rotates
+ to the next target in the interleave at address N +
+ interleave_granularity (assuming N is aligned to
+ interleave_granularity).
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/create_{pmem,ram}_region
+Date: May, 2022, January, 2023
+KernelVersion: v6.0 (pmem), v6.3 (ram)
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Write a string in the form 'regionZ' to start the process
+ of defining a new persistent, or volatile memory region
+ (interleave-set) within the decode range bounded by root decoder
+ 'decoderX.Y'. The value written must match the current value
+ returned from reading this attribute. An atomic compare exchange
+ operation is done on write to assign the requested id to a
+ region and allocate the region-id for the next creation attempt.
+ EBUSY is returned if the region name written does not match the
+ current cached value.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/delete_region
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) Write a string in the form 'regionZ' to delete that region,
+ provided it is currently idle / not bound to a driver.
+
+
+What: /sys/bus/cxl/devices/decoderX.Y/qos_class
+Date: May, 2023
+KernelVersion: v6.5
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) For CXL host platforms that support "QoS Telemetry" this
+ root-decoder-only attribute conveys a platform specific cookie
+ that identifies a QoS performance class for the CXL Window.
+ This class-id can be compared against a similar "qos_class"
+ published for each memory-type that an endpoint supports. While
+ it is not required that endpoints map their local memory-class
+ to a matching platform class, mismatches are not recommended and
+ there are platform specific side-effects that may result.
+
+
+What: /sys/bus/cxl/devices/regionZ/uuid
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Write a unique identifier for the region. This field must
+ be set for persistent regions and it must not conflict with the
+ UUID of another region. For volatile ram regions this
+ attribute is a read-only empty string.
+
+
+What: /sys/bus/cxl/devices/regionZ/interleave_granularity
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Set the number of consecutive bytes each device in the
+ interleave set will claim. The possible interleave granularity
+ values are determined by the CXL spec and the participating
+ devices.
+
+
+What: /sys/bus/cxl/devices/regionZ/interleave_ways
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Configures the number of devices participating in the
+ region is set by writing this value. Each device will provide
+ 1/interleave_ways of storage for the region.
+
+
+What: /sys/bus/cxl/devices/regionZ/size
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) System physical address space to be consumed by the region.
+ When written trigger the driver to allocate space out of the
+ parent root decoder's address space. When read the size of the
+ address space is reported and should match the span of the
+ region's resource attribute. Size shall be set after the
+ interleave configuration parameters. Once set it cannot be
+ changed, only freed by writing 0. The kernel makes no guarantees
+ that data is maintained over an address space freeing event, and
+ there is no guarantee that a free followed by an allocate
+ results in the same address being allocated. If extended linear
+ cache is present, the size indicates extended linear cache size
+ plus the CXL region size.
+
+What: /sys/bus/cxl/devices/regionZ/extended_linear_cache_size
+Date: October, 2025
+KernelVersion: v6.19
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The size of extended linear cache, if there is an extended
+ linear cache. Otherwise the attribute will not be visible.
+
+What: /sys/bus/cxl/devices/regionZ/mode
+Date: January, 2023
+KernelVersion: v6.3
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The mode of a region is established at region creation time
+ and dictates the mode of the endpoint decoder that comprise the
+ region. For more details on the possible modes see
+ /sys/bus/cxl/devices/decoderX.Y/mode
+
+
+What: /sys/bus/cxl/devices/regionZ/resource
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) A region is a contiguous partition of a CXL root decoder
+ address space. Region capacity is allocated by writing to the
+ size attribute, the resulting physical address space determined
+ by the driver is reflected here. It is therefore not useful to
+ read this before writing a value to the size attribute.
+
+
+What: /sys/bus/cxl/devices/regionZ/target[0..N]
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Write an endpoint decoder object name to 'targetX' where X
+ is the intended position of the endpoint device in the region
+ interleave and N is the 'interleave_ways' setting for the
+ region. ENXIO is returned if the write results in an impossible
+ to map decode scenario, like the endpoint is unreachable at that
+ position relative to the root decoder interleave. EBUSY is
+ returned if the position in the region is already occupied, or
+ if the region is not in a state to accept interleave
+ configuration changes. EINVAL is returned if the object name is
+ not an endpoint decoder. Once all positions have been
+ successfully written a final validation for decode conflicts is
+ performed before activating the region.
+
+
+What: /sys/bus/cxl/devices/regionZ/commit
+Date: May, 2022
+KernelVersion: v6.0
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RW) Write a boolean 'true' string value to this attribute to
+ trigger the region to transition from the software programmed
+ state to the actively decoding in hardware state. The commit
+ operation in addition to validating that the region is in proper
+ configured state, validates that the decoders are being
+ committed in spec mandated order (last committed decoder id +
+ 1), and checks that the hardware accepts the commit request.
+ Reading this value indicates whether the region is committed or
+ not.
+
+
+What: /sys/bus/cxl/devices/memX/trigger_poison_list
+Date: April, 2023
+KernelVersion: v6.4
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (WO) When a boolean 'true' is written to this attribute the
+ memdev driver retrieves the poison list from the device. The
+ list consists of addresses that are poisoned, or would result
+ in poison if accessed, and the source of the poison. This
+ attribute is only visible for devices supporting the
+ capability. The retrieved errors are logged as kernel
+ events when cxl_poison event tracing is enabled.
+
+
+What: /sys/bus/cxl/devices/regionZ/accessY/read_bandwidth
+ /sys/bus/cxl/devices/regionZ/accessY/write_bandwidth
+Date: Jan, 2024
+KernelVersion: v6.9
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The aggregated read or write bandwidth of the region. The
+ number is the accumulated read or write bandwidth of all CXL memory
+ devices that contributes to the region in MB/s. It is
+ identical data that should appear in
+ /sys/devices/system/node/nodeX/accessY/initiators/read_bandwidth or
+ /sys/devices/system/node/nodeX/accessY/initiators/write_bandwidth.
+ See Documentation/ABI/stable/sysfs-devices-node. access0 provides
+ the number to the closest initiator and access1 provides the
+ number to the closest CPU.
+
+
+What: /sys/bus/cxl/devices/regionZ/accessY/read_latency
+ /sys/bus/cxl/devices/regionZ/accessY/write_latency
+Date: Jan, 2024
+KernelVersion: v6.9
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The read or write latency of the region. The number is
+ the worst read or write latency of all CXL memory devices that
+ contributes to the region in nanoseconds. It is identical data
+ that should appear in
+ /sys/devices/system/node/nodeX/accessY/initiators/read_latency or
+ /sys/devices/system/node/nodeX/accessY/initiators/write_latency.
+ See Documentation/ABI/stable/sysfs-devices-node. access0 provides
+ the number to the closest initiator and access1 provides the
+ number to the closest CPU.
+
+
+What: /sys/bus/cxl/devices/nvdimm-bridge0/ndbusX/nmemY/cxl/dirty_shutdown
+Date: Feb, 2025
+KernelVersion: v6.15
+Contact: linux-cxl@vger.kernel.org
+Description:
+ (RO) The device dirty shutdown count value, which is the number
+ of times the device could have incurred in potential data loss.
+ The count is persistent across power loss and wraps back to 0
+ upon overflow. If this file is not present, the device does not
+ have the necessary support for dirty tracking.
diff --git a/Documentation/ABI/testing/sysfs-bus-dax b/Documentation/ABI/testing/sysfs-bus-dax
new file mode 100644
index 000000000000..b34266bfae49
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-dax
@@ -0,0 +1,153 @@
+What: /sys/bus/dax/devices/daxX.Y/align
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) Provides a way to specify an alignment for a dax device.
+ Values allowed are constrained by the physical address ranges
+ that back the dax device, and also by arch requirements.
+
+What: /sys/bus/dax/devices/daxX.Y/mapping
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (WO) Provides a way to allocate a mapping range under a dax
+ device. Specified in the format <start>-<end>.
+
+What: /sys/bus/dax/devices/daxX.Y/mapping[0..N]/start
+What: /sys/bus/dax/devices/daxX.Y/mapping[0..N]/end
+What: /sys/bus/dax/devices/daxX.Y/mapping[0..N]/page_offset
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) A dax device may have multiple constituent discontiguous
+ address ranges. These are represented by the different
+ 'mappingX' subdirectories. The 'start' attribute indicates the
+ start physical address for the given range. The 'end' attribute
+ indicates the end physical address for the given range. The
+ 'page_offset' attribute indicates the offset of the current
+ range in the dax device.
+
+What: /sys/bus/dax/devices/daxX.Y/resource
+Date: June, 2019
+KernelVersion: v5.3
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The resource attribute indicates the starting physical
+ address of a dax device. In case of a device with multiple
+ constituent ranges, it indicates the starting address of the
+ first range.
+
+What: /sys/bus/dax/devices/daxX.Y/size
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) The size attribute indicates the total size of a dax
+ device. For creating subdivided dax devices, or for resizing
+ an existing device, the new size can be written to this as
+ part of the reconfiguration process.
+
+What: /sys/bus/dax/devices/daxX.Y/numa_node
+Date: November, 2019
+KernelVersion: v5.5
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) If NUMA is enabled and the platform has affinitized the
+ backing device for this dax device, emit the CPU node
+ affinity for this device.
+
+What: /sys/bus/dax/devices/daxX.Y/target_node
+Date: February, 2019
+KernelVersion: v5.1
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The target-node attribute is the Linux numa-node that a
+ device-dax instance may create when it is online. Prior to
+ being online the device's 'numa_node' property reflects the
+ closest online cpu node which is the typical expectation of a
+ device 'numa_node'. Once it is online it becomes its own
+ distinct numa node.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/available_size
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The available_size attribute tracks available dax region
+ capacity. This only applies to volatile hmem devices, not pmem
+ devices, since pmem devices are defined by nvdimm namespace
+ boundaries.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/size
+Date: July, 2017
+KernelVersion: v5.1
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The size attribute indicates the size of a given dax region
+ in bytes.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/align
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The align attribute indicates alignment of the dax region.
+ Changes on align may not always be valid, when say certain
+ mappings were created with 2M and then we switch to 1G. This
+ validates all ranges against the new value being attempted, post
+ resizing.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/seed
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The seed device is a concept for dynamic dax regions to be
+ able to split the region amongst multiple sub-instances. The
+ seed device, similar to libnvdimm seed devices, is a device
+ that starts with zero capacity allocated and unbound to a
+ driver.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/create
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) The create interface to the dax region provides a way to
+ create a new unconfigured dax device under the given region, which
+ can then be configured (with a size etc.) and then probed.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/delete
+Date: October, 2020
+KernelVersion: v5.10
+Contact: nvdimm@lists.linux.dev
+Description:
+ (WO) The delete interface for a dax region provides for deletion
+ of any 0-sized and idle dax devices.
+
+What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/id
+Date: July, 2017
+KernelVersion: v5.1
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The id attribute indicates the region id of a dax region.
+
+What: /sys/bus/dax/devices/daxX.Y/memmap_on_memory
+Date: January, 2024
+KernelVersion: v6.8
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) Control the memmap_on_memory setting if the dax device
+ were to be hotplugged as system memory. This determines whether
+ the 'altmap' for the hotplugged memory will be placed on the
+ device being hotplugged (memmap_on_memory=1) or if it will be
+ placed on regular memory (memmap_on_memory=0). This attribute
+ must be set before the device is handed over to the 'kmem'
+ driver (i.e. hotplugged into system-ram). Additionally, this
+ depends on CONFIG_MHP_MEMMAP_ON_MEMORY, and a globally enabled
+ memmap_on_memory parameter for memory_hotplug. This is
+ typically set on the kernel command line -
+ memory_hotplug.memmap_on_memory set to 'true' or 'force'."
diff --git a/Documentation/ABI/testing/sysfs-bus-dfl b/Documentation/ABI/testing/sysfs-bus-dfl
new file mode 100644
index 000000000000..b0265ab17200
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-dfl
@@ -0,0 +1,17 @@
+What: /sys/bus/dfl/devices/dfl_dev.X/type
+Date: Aug 2020
+KernelVersion: 5.10
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. It returns type of DFL FIU of the device. Now DFL
+ supports 2 FIU types, 0 for FME, 1 for PORT.
+
+ Format: 0x%x
+
+What: /sys/bus/dfl/devices/dfl_dev.X/feature_id
+Date: Aug 2020
+KernelVersion: 5.10
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. It returns feature identifier local to its DFL FIU
+ type.
+
+ Format: 0x%x
diff --git a/Documentation/ABI/testing/sysfs-bus-dfl-devices-emif b/Documentation/ABI/testing/sysfs-bus-dfl-devices-emif
new file mode 100644
index 000000000000..817d14126d4d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-dfl-devices-emif
@@ -0,0 +1,25 @@
+What: /sys/bus/dfl/devices/dfl_dev.X/infX_cal_fail
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. It indicates if the calibration failed on this
+ memory interface. "1" for calibration failure, "0" for OK.
+ Format: %u
+
+What: /sys/bus/dfl/devices/dfl_dev.X/infX_init_done
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. It indicates if the initialization completed on
+ this memory interface. "1" for initialization complete, "0"
+ for not yet.
+ Format: %u
+
+What: /sys/bus/dfl/devices/dfl_dev.X/infX_clear
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Write-only. Writing "1" to this file will zero out all memory
+ data in this memory interface. Writing of other values is
+ invalid.
+ Format: %u
diff --git a/Documentation/ABI/testing/sysfs-bus-dfl-devices-n3000-nios b/Documentation/ABI/testing/sysfs-bus-dfl-devices-n3000-nios
new file mode 100644
index 000000000000..5335d742bcaf
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-dfl-devices-n3000-nios
@@ -0,0 +1,47 @@
+What: /sys/bus/dfl/devices/dfl_dev.X/fec_mode
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. Returns the FEC mode of the 25G links of the
+ ethernet retimers configured by Nios firmware. "rs" for Reed
+ Solomon FEC, "kr" for Fire Code FEC, "no" for NO FEC.
+ "not supported" if the FEC mode setting is not supported, this
+ happens when the Nios firmware version major < 3, or no link is
+ configured to 25G.
+ Format: string
+
+What: /sys/bus/dfl/devices/dfl_dev.X/retimer_A_mode
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. Returns the enumeration value of the working mode of
+ the retimer A configured by the Nios firmware. The value is
+ read out from shared registers filled by the Nios firmware. Now
+ the values could be:
+
+ - "0": Reset
+ - "1": 4x10G
+ - "2": 4x25G
+ - "3": 2x25G
+ - "4": 2x25G+2x10G
+ - "5": 1x25G
+
+ If the Nios firmware is updated in future to support more
+ retimer modes, more enumeration value is expected.
+ Format: 0x%x
+
+What: /sys/bus/dfl/devices/dfl_dev.X/retimer_B_mode
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. Returns the enumeration value of the working mode of
+ the retimer B configured by the Nios firmware. The value format
+ is the same as retimer_A_mode.
+
+What: /sys/bus/dfl/devices/dfl_dev.X/nios_fw_version
+Date: Oct 2020
+KernelVersion: 5.12
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read-only. Returns the version of the Nios firmware in the
+ FPGA. Its format is "major.minor.patch".
+ Format: %x.%x.%x
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices b/Documentation/ABI/testing/sysfs-bus-event_source-devices
new file mode 100644
index 000000000000..79b268319df1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices
@@ -0,0 +1,24 @@
+What: /sys/bus/event_source/devices/<pmu>
+Date: 2014/02/24
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Performance Monitoring Unit (<pmu>)
+
+ Each <pmu> directory, for a PMU device, is a name
+ optionally followed by an underscore and then either a
+ decimal or hexadecimal number. For example, cpu is a
+ PMU name without a suffix as is intel_bts,
+ uncore_imc_0 is a PMU name with a 0 numeric suffix,
+ ddr_pmu_87e1b0000000 is a PMU name with a hex
+ suffix. The hex suffix must be more than two
+ characters long to avoid ambiguity with PMUs like the
+ S390 cpum_cf.
+
+ Tools can treat PMUs with the same name that differ by
+ suffix as instances of the same PMU for the sake of,
+ for example, opening an event. For example, the PMUs
+ uncore_imc_free_running_0 and
+ uncore_imc_free_running_1 have an event data_read;
+ opening the data_read event on a PMU specified as
+ uncore_imc_free_running should be treated as opening
+ the data_read event on PMU uncore_imc_free_running_0
+ and PMU uncore_imc_free_running_1.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps b/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps
new file mode 100644
index 000000000000..a5f506f7d481
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-caps
@@ -0,0 +1,24 @@
+What: /sys/bus/event_source/devices/<dev>/caps
+Date: May 2022
+KernelVersion: 5.19
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ Attribute group to describe the capabilities exposed
+ for a particular pmu. Each attribute of this group can
+ expose information specific to a PMU, say pmu_name, so that
+ userspace can understand some of the feature which the
+ platform specific PMU supports.
+
+ One of the example available capability in supported platform
+ like Intel is pmu_name, which exposes underlying CPU name known
+ to the PMU driver.
+
+ Example output in powerpc:
+ grep . /sys/bus/event_source/devices/cpu/caps/*
+ /sys/bus/event_source/devices/cpu/caps/pmu_name:POWER9
+
+ The "branch_counter_nr" in the supported platform exposes the
+ maximum number of counters which can be shown in the u64 counters
+ of PERF_SAMPLE_BRANCH_COUNTERS, while the "branch_counter_width"
+ exposes the width of each counter. Both of them can be used by
+ the perf tool to parse the logged counters in each branch.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
new file mode 100644
index 000000000000..63a32ddcb95e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
@@ -0,0 +1,104 @@
+What: /sys/bus/event_source/devices/dfl_fmeX/format
+Date: April 2020
+KernelVersion: 5.8
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config for a particular pmu.
+ (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute under this group defines a bit range of the
+ perf_event_attr.config. All supported attributes are listed
+ below::
+
+ event = "config:0-11" - event ID
+ evtype = "config:12-15" - event type
+ portid = "config:16-23" - event source
+
+ For example::
+
+ fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff"
+
+ It shows this fab_mmio_read is a fabric type (0x02) event with
+ 0x06 local event id for overall monitoring (portid=0xff).
+
+What: /sys/bus/event_source/devices/dfl_fmeX/cpumask
+Date: April 2020
+KernelVersion: 5.8
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. This file always returns cpu which the PMU is bound
+ for access to all fme pmu performance monitoring events.
+
+What: /sys/bus/event_source/devices/dfl_fmeX/events
+Date: April 2020
+KernelVersion: 5.8
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Attribute group to describe performance monitoring
+ events specific to fme. Each attribute in this group describes
+ a single performance monitoring event supported by this fme pmu.
+ The name of the file is the name of the event.
+ (See ABI/testing/sysfs-bus-event_source-devices-events).
+
+ All supported performance monitoring events are listed below.
+
+ Basic events (evtype=0x00)::
+
+ clock = "event=0x00,evtype=0x00,portid=0xff"
+
+ Cache events (evtype=0x01)::
+
+ cache_read_hit = "event=0x00,evtype=0x01,portid=0xff"
+ cache_read_miss = "event=0x01,evtype=0x01,portid=0xff"
+ cache_write_hit = "event=0x02,evtype=0x01,portid=0xff"
+ cache_write_miss = "event=0x03,evtype=0x01,portid=0xff"
+ cache_hold_request = "event=0x05,evtype=0x01,portid=0xff"
+ cache_data_write_port_contention =
+ "event=0x06,evtype=0x01,portid=0xff"
+ cache_tag_write_port_contention =
+ "event=0x07,evtype=0x01,portid=0xff"
+ cache_tx_req_stall = "event=0x08,evtype=0x01,portid=0xff"
+ cache_rx_req_stall = "event=0x09,evtype=0x01,portid=0xff"
+ cache_eviction = "event=0x0a,evtype=0x01,portid=0xff"
+
+ Fabric events (evtype=0x02)::
+
+ fab_pcie0_read = "event=0x00,evtype=0x02,portid=0xff"
+ fab_pcie0_write = "event=0x01,evtype=0x02,portid=0xff"
+ fab_pcie1_read = "event=0x02,evtype=0x02,portid=0xff"
+ fab_pcie1_write = "event=0x03,evtype=0x02,portid=0xff"
+ fab_upi_read = "event=0x04,evtype=0x02,portid=0xff"
+ fab_upi_write = "event=0x05,evtype=0x02,portid=0xff"
+ fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff"
+ fab_mmio_write = "event=0x07,evtype=0x02,portid=0xff"
+ fab_port_pcie0_read = "event=0x00,evtype=0x02,portid=?"
+ fab_port_pcie0_write = "event=0x01,evtype=0x02,portid=?"
+ fab_port_pcie1_read = "event=0x02,evtype=0x02,portid=?"
+ fab_port_pcie1_write = "event=0x03,evtype=0x02,portid=?"
+ fab_port_upi_read = "event=0x04,evtype=0x02,portid=?"
+ fab_port_upi_write = "event=0x05,evtype=0x02,portid=?"
+ fab_port_mmio_read = "event=0x06,evtype=0x02,portid=?"
+ fab_port_mmio_write = "event=0x07,evtype=0x02,portid=?"
+
+ VTD events (evtype=0x03)::
+
+ vtd_port_read_transaction = "event=0x00,evtype=0x03,portid=?"
+ vtd_port_write_transaction = "event=0x01,evtype=0x03,portid=?"
+ vtd_port_devtlb_read_hit = "event=0x02,evtype=0x03,portid=?"
+ vtd_port_devtlb_write_hit = "event=0x03,evtype=0x03,portid=?"
+ vtd_port_devtlb_4k_fill = "event=0x04,evtype=0x03,portid=?"
+ vtd_port_devtlb_2m_fill = "event=0x05,evtype=0x03,portid=?"
+ vtd_port_devtlb_1g_fill = "event=0x06,evtype=0x03,portid=?"
+
+ VTD SIP events (evtype=0x04)::
+
+ vtd_sip_iotlb_4k_hit = "event=0x00,evtype=0x04,portid=0xff"
+ vtd_sip_iotlb_2m_hit = "event=0x01,evtype=0x04,portid=0xff"
+ vtd_sip_iotlb_1g_hit = "event=0x02,evtype=0x04,portid=0xff"
+ vtd_sip_slpwc_l3_hit = "event=0x03,evtype=0x04,portid=0xff"
+ vtd_sip_slpwc_l4_hit = "event=0x04,evtype=0x04,portid=0xff"
+ vtd_sip_rcc_hit = "event=0x05,evtype=0x04,portid=0xff"
+ vtd_sip_iotlb_4k_miss = "event=0x06,evtype=0x04,portid=0xff"
+ vtd_sip_iotlb_2m_miss = "event=0x07,evtype=0x04,portid=0xff"
+ vtd_sip_iotlb_1g_miss = "event=0x08,evtype=0x04,portid=0xff"
+ vtd_sip_slpwc_l3_miss = "event=0x09,evtype=0x04,portid=0xff"
+ vtd_sip_slpwc_l4_miss = "event=0x0a,evtype=0x04,portid=0xff"
+ vtd_sip_rcc_miss = "event=0x0b,evtype=0x04,portid=0xff"
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa
new file mode 100644
index 000000000000..3c7d132281b0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dsa
@@ -0,0 +1,30 @@
+What: /sys/bus/event_source/devices/dsa*/format
+Date: April 2021
+KernelVersion: 5.13
+Contact: Tom Zanussi <tom.zanussi@linux.intel.com>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config or
+ perf_event_attr.config1 for the IDXD DSA pmu. (See also
+ ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute in this group defines a bit range in
+ perf_event_attr.config or perf_event_attr.config1.
+ All supported attributes are listed below (See the
+ IDXD DSA Spec for possible attribute values)::
+
+ event_category = "config:0-3" - event category
+ event = "config:4-31" - event ID
+
+ filter_wq = "config1:0-31" - workqueue filter
+ filter_tc = "config1:32-39" - traffic class filter
+ filter_pgsz = "config1:40-43" - page size filter
+ filter_sz = "config1:44-51" - transfer size filter
+ filter_eng = "config1:52-59" - engine filter
+
+What: /sys/bus/event_source/devices/dsa*/cpumask
+Date: April 2021
+KernelVersion: 5.13
+Contact: Tom Zanussi <tom.zanussi@linux.intel.com>
+Description: Read-only. This file always returns the cpu to which the
+ IDXD DSA pmu is bound for access to all dsa pmu
+ performance monitoring events.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
index 505f080d20a1..0fe1b9487202 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
@@ -37,6 +37,14 @@ Description: Per-pmu performance monitoring events specific to the running syste
performance monitoring event supported by the <pmu>. The name
of the file is the name of the event.
+ As performance monitoring event names are case insensitive
+ in the perf tool, the perf tool only looks for all lower
+ case or all upper case event names in sysfs to avoid
+ scanning the directory. It is therefore required the
+ name of the event here is either completely lower or upper
+ case, with no mixed-case characters. Numbers, '.', '_', and
+ '-' are also allowed.
+
File contents:
<term>[=<value>][,<term>[=<value>]]...
@@ -47,7 +55,7 @@ Description: Per-pmu performance monitoring events specific to the running syste
If a <term> is specified alone (without an assigned value), it
is implied that 0x1 is assigned to that <term>.
- Examples (each of these lines would be in a seperate file):
+ Examples (each of these lines would be in a separate file):
event=0x2abc
event=0x423,inv,cmask=0x3
@@ -83,7 +91,7 @@ Description: Perf event scaling factors
A string representing a floating point value expressed in
scientific notation to be multiplied by the event count
- recieved from the kernel to match the unit specified in the
+ received from the kernel to match the unit specified in the
<event>.unit file.
Example:
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
index 77f47ff5ee02..df7ccc1b2fba 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -1,6 +1,6 @@
-Where: /sys/bus/event_source/devices/<dev>/format
+What: /sys/bus/event_source/devices/<dev>/format
Date: January 2012
-Kernel Version: 3.3
+KernelVersion: 3.3
Contact: Jiri Olsa <jolsa@redhat.com>
Description:
Attribute group to describe the magic bits that go into
@@ -10,7 +10,8 @@ Description:
name/value pairs.
Userspace must be prepared for the possibility that attributes
- define overlapping bit ranges. For example:
+ define overlapping bit ranges. For example::
+
attr1 = 'config:0-23'
attr2 = 'config:0-7'
attr3 = 'config:12-35'
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hisi_ptt b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hisi_ptt
new file mode 100644
index 000000000000..1119766564d7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hisi_ptt
@@ -0,0 +1,113 @@
+What: /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune
+Date: October 2022
+KernelVersion: 6.1
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: This directory contains files for tuning the PCIe link
+ parameters(events). Each file is named after the event
+ of the PCIe link.
+
+ See Documentation/trace/hisi-ptt.rst for more information.
+
+What: /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune/qos_tx_cpl
+Date: October 2022
+KernelVersion: 6.1
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (RW) Controls the weight of Tx completion TLPs, which influence
+ the proportion of outbound completion TLPs on the PCIe link.
+ The available tune data is [0, 1, 2]. Writing a negative value
+ will return an error, and out of range values will be converted
+ to 2. The value indicates a probable level of the event.
+
+What: /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune/qos_tx_np
+Date: October 2022
+KernelVersion: 6.1
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (RW) Controls the weight of Tx non-posted TLPs, which influence
+ the proportion of outbound non-posted TLPs on the PCIe link.
+ The available tune data is [0, 1, 2]. Writing a negative value
+ will return an error, and out of range values will be converted
+ to 2. The value indicates a probable level of the event.
+
+What: /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune/qos_tx_p
+Date: October 2022
+KernelVersion: 6.1
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (RW) Controls the weight of Tx posted TLPs, which influence the
+ proportion of outbound posted TLPs on the PCIe link.
+ The available tune data is [0, 1, 2]. Writing a negative value
+ will return an error, and out of range values will be converted
+ to 2. The value indicates a probable level of the event.
+
+What: /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune/rx_alloc_buf_level
+Date: October 2022
+KernelVersion: 6.1
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (RW) Control the allocated buffer watermark for inbound packets.
+ The packets will be stored in the buffer first and then transmitted
+ either when the watermark reached or when timed out.
+ The available tune data is [0, 1, 2]. Writing a negative value
+ will return an error, and out of range values will be converted
+ to 2. The value indicates a probable level of the event.
+
+What: /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune/tx_alloc_buf_level
+Date: October 2022
+KernelVersion: 6.1
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (RW) Control the allocated buffer watermark of outbound packets.
+ The packets will be stored in the buffer first and then transmitted
+ either when the watermark reached or when timed out.
+ The available tune data is [0, 1, 2]. Writing a negative value
+ will return an error, and out of range values will be converted
+ to 2. The value indicates a probable level of the event.
+
+What: /sys/devices/hisi_ptt<sicl_id>_<core_id>/root_port_filters
+Date: May 2023
+KernelVersion: 6.5
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: This directory contains the files providing the PCIe Root Port filters
+ information used for PTT trace. Each file is named after the supported
+ Root Port device name <domain>:<bus>:<device>.<function>.
+
+ See the description of the "filter" in Documentation/trace/hisi-ptt.rst
+ for more information.
+
+What: /sys/devices/hisi_ptt<sicl_id>_<core_id>/root_port_filters/multiselect
+Date: May 2023
+KernelVersion: 6.5
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (Read) Indicates if this kind of filter can be selected at the same
+ time as others filters, or must be used on it's own. 1 indicates
+ the former case and 0 indicates the latter.
+
+What: /sys/devices/hisi_ptt<sicl_id>_<core_id>/root_port_filters/<bdf>
+Date: May 2023
+KernelVersion: 6.5
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (Read) Indicates the filter value of this Root Port filter, which
+ can be used to control the TLP headers to trace by the PTT trace.
+
+What: /sys/devices/hisi_ptt<sicl_id>_<core_id>/requester_filters
+Date: May 2023
+KernelVersion: 6.5
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: This directory contains the files providing the PCIe Requester filters
+ information used for PTT trace. Each file is named after the supported
+ Endpoint device name <domain>:<bus>:<device>.<function>.
+
+ See the description of the "filter" in Documentation/trace/hisi-ptt.rst
+ for more information.
+
+What: /sys/devices/hisi_ptt<sicl_id>_<core_id>/requester_filters/multiselect
+Date: May 2023
+KernelVersion: 6.5
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (Read) Indicates if this kind of filter can be selected at the same
+ time as others filters, or must be used on it's own. 1 indicates
+ the former case and 0 indicates the latter.
+
+What: /sys/devices/hisi_ptt<sicl_id>_<core_id>/requester_filters/<bdf>
+Date: May 2023
+KernelVersion: 6.5
+Contact: Yicong Yang <yangyicong@hisilicon.com>
+Description: (Read) Indicates the filter value of this Requester filter, which
+ can be used to control the TLP headers to trace by the PTT trace.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
index f893337570c1..de390a010af8 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
@@ -1,10 +1,35 @@
+What: /sys/bus/event_source/devices/hv_24x7/format
+Date: September 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config for a particular pmu.
+ (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute under this group defines a bit range of the
+ perf_event_attr.config. All supported attributes are listed
+ below::
+
+ chip = "config:16-31"
+ core = "config:16-31"
+ domain = "config:0-3"
+ lpar = "config:0-15"
+ offset = "config:32-63"
+ vcpu = "config:16-31"
+
+ For example::
+
+ PM_PB_CYC = "domain=1,offset=0x80,chip=?,lpar=0x0"
+
+ In this event, '?' after chip specifies that
+ this value will be provided by user while running this event.
+
What: /sys/bus/event_source/devices/hv_24x7/interface/catalog
Date: February 2014
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
Description:
Provides access to the binary "24x7 catalog" provided by the
hypervisor on POWER7 and 8 systems. This catalog lists events
- avaliable from the powerpc "hv_24x7" pmu. Its format is
+ available from the powerpc "hv_24x7" pmu. Its format is
documented here:
https://raw.githubusercontent.com/jmesmon/catalog-24x7/master/hv-24x7-catalog.h
@@ -22,6 +47,34 @@ Description:
Exposes the "version" field of the 24x7 catalog. This is also
extractable from the provided binary "catalog" sysfs entry.
+What: /sys/devices/hv_24x7/interface/sockets
+Date: May 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: read only
+ This sysfs interface exposes the number of sockets present in the
+ system.
+
+What: /sys/devices/hv_24x7/interface/chipspersocket
+Date: May 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: read only
+ This sysfs interface exposes the number of chips per socket
+ present in the system.
+
+What: /sys/devices/hv_24x7/interface/coresperchip
+Date: May 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: read only
+ This sysfs interface exposes the number of cores per chip
+ present in the system.
+
+What: /sys/devices/hv_24x7/cpumask
+Date: July 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: read only
+ This sysfs file exposes the cpumask which is designated to make
+ HCALLs to retrieve hv-24x7 pmu event counter data.
+
What: /sys/bus/event_source/devices/hv_24x7/event_descs/<event-name>
Date: February 2014
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
index 3ca4e554d2f9..40f7cd240591 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
@@ -1,3 +1,34 @@
+What: /sys/bus/event_source/devices/hv_gpci/format
+Date: September 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config for a particular pmu.
+ (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute under this group defines a bit range of the
+ perf_event_attr.config. All supported attributes are listed
+ below::
+
+ counter_info_version = "config:16-23"
+ length = "config:24-31"
+ partition_id = "config:32-63"
+ request = "config:0-31"
+ sibling_part_id = "config:32-63"
+ hw_chip_id = "config:32-63"
+ offset = "config:32-63"
+ phys_processor_idx = "config:32-63"
+ secondary_index = "config:0-15"
+ starting_index = "config:32-63"
+
+ For example::
+
+ processor_core_utilization_instructions_completed = "request=0x94,
+ phys_processor_idx=?,counter_info_version=0x8,
+ length=8,offset=0x18"
+
+ In this event, '?' after phys_processor_idx specifies this value
+ this value will be provided by user while running this event.
+
What: /sys/bus/event_source/devices/hv_gpci/interface/collect_privileged
Date: February 2014
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
@@ -5,6 +36,7 @@ Description:
'0' if the hypervisor is configured to forbid access to event
counters being accumulated by other guests and to physical
domain event counters.
+
'1' if that access is allowed.
What: /sys/bus/event_source/devices/hv_gpci/interface/ga
@@ -41,3 +73,170 @@ Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
Description:
A number indicating the latest version of the gpci interface
that the kernel is aware of.
+
+What: /sys/devices/hv_gpci/cpumask
+Date: October 2020
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: read only
+ This sysfs file exposes the cpumask which is designated to make
+ HCALLs to retrieve hv-gpci pmu event counter data.
+
+What: /sys/devices/hv_gpci/interface/processor_bus_topology
+Date: July 2023
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: admin read only
+ This sysfs file exposes the system topology information by making HCALL
+ H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
+ PROCESSOR_BUS_TOPOLOGY(0xD0).
+
+ * This sysfs file will be created only for power10 and above platforms.
+
+ * User needs root privileges to read data from this sysfs file.
+
+ * This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
+ "H_AUTHORITY" or "H_PARAMETER" as the return type.
+
+ HCALL with return error type "H_AUTHORITY" can be resolved during
+ runtime by setting "Enable Performance Information Collection" option.
+
+ * The end user reading this sysfs file must decode the content as per
+ underlying platform/firmware.
+
+ Possible error codes while reading this sysfs file:
+
+ * "-EPERM" : Partition is not permitted to retrieve performance information,
+ required to set "Enable Performance Information Collection" option.
+
+ * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
+ or because of some hardware error. Refer to getPerfCountInfo documentation for
+ more information.
+
+ * "-EFBIG" : System information exceeds PAGE_SIZE.
+
+What: /sys/devices/hv_gpci/interface/processor_config
+Date: July 2023
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: admin read only
+ This sysfs file exposes the system topology information by making HCALL
+ H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
+ PROCESSOR_CONFIG(0x90).
+
+ * This sysfs file will be created only for power10 and above platforms.
+
+ * User needs root privileges to read data from this sysfs file.
+
+ * This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
+ "H_AUTHORITY" or "H_PARAMETER" as the return type.
+
+ HCALL with return error type "H_AUTHORITY" can be resolved during
+ runtime by setting "Enable Performance Information Collection" option.
+
+ * The end user reading this sysfs file must decode the content as per
+ underlying platform/firmware.
+
+ Possible error codes while reading this sysfs file:
+
+ * "-EPERM" : Partition is not permitted to retrieve performance information,
+ required to set "Enable Performance Information Collection" option.
+
+ * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
+ or because of some hardware error. Refer to getPerfCountInfo documentation for
+ more information.
+
+ * "-EFBIG" : System information exceeds PAGE_SIZE.
+
+What: /sys/devices/hv_gpci/interface/affinity_domain_via_virtual_processor
+Date: July 2023
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: admin read only
+ This sysfs file exposes the system topology information by making HCALL
+ H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
+ AFFINITY_DOMAIN_INFORMATION_BY_VIRTUAL_PROCESSOR(0xA0).
+
+ * This sysfs file will be created only for power10 and above platforms.
+
+ * User needs root privileges to read data from this sysfs file.
+
+ * This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
+ "H_AUTHORITY" or "H_PARAMETER" as the return type.
+
+ HCALL with return error type "H_AUTHORITY" can be resolved during
+ runtime by setting "Enable Performance Information Collection" option.
+
+ * The end user reading this sysfs file must decode the content as per
+ underlying platform/firmware.
+
+ Possible error codes while reading this sysfs file:
+
+ * "-EPERM" : Partition is not permitted to retrieve performance information,
+ required to set "Enable Performance Information Collection" option.
+
+ * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
+ or because of some hardware error. Refer to getPerfCountInfo documentation for
+ more information.
+
+ * "-EFBIG" : System information exceeds PAGE_SIZE.
+
+What: /sys/devices/hv_gpci/interface/affinity_domain_via_domain
+Date: July 2023
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: admin read only
+ This sysfs file exposes the system topology information by making HCALL
+ H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
+ AFFINITY_DOMAIN_INFORMATION_BY_DOMAIN(0xB0).
+
+ * This sysfs file will be created only for power10 and above platforms.
+
+ * User needs root privileges to read data from this sysfs file.
+
+ * This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
+ "H_AUTHORITY" or "H_PARAMETER" as the return type.
+
+ HCALL with return error type "H_AUTHORITY" can be resolved during
+ runtime by setting "Enable Performance Information Collection" option.
+
+ * The end user reading this sysfs file must decode the content as per
+ underlying platform/firmware.
+
+ Possible error codes while reading this sysfs file:
+
+ * "-EPERM" : Partition is not permitted to retrieve performance information,
+ required to set "Enable Performance Information Collection" option.
+
+ * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
+ or because of some hardware error. Refer to getPerfCountInfo documentation for
+ more information.
+
+ * "-EFBIG" : System information exceeds PAGE_SIZE.
+
+What: /sys/devices/hv_gpci/interface/affinity_domain_via_partition
+Date: July 2023
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: admin read only
+ This sysfs file exposes the system topology information by making HCALL
+ H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
+ AFFINITY_DOMAIN_INFORMATION_BY_PARTITION(0xB1).
+
+ * This sysfs file will be created only for power10 and above platforms.
+
+ * User needs root privileges to read data from this sysfs file.
+
+ * This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
+ "H_AUTHORITY" or "H_PARAMETER" as the return type.
+
+ HCALL with return error type "H_AUTHORITY" can be resolved during
+ runtime by setting "Enable Performance Information Collection" option.
+
+ * The end user reading this sysfs file must decode the content as per
+ underlying platform/firmware.
+
+ Possible error codes while reading this sysfs file:
+
+ * "-EPERM" : Partition is not permitted to retrieve performance information,
+ required to set "Enable Performance Information Collection" option.
+
+ * "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
+ or because of some hardware error. Refer to getPerfCountInfo documentation for
+ more information.
+
+ * "-EFBIG" : System information exceeds PAGE_SIZE.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu b/Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu
new file mode 100644
index 000000000000..d7af4919302e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-iommu
@@ -0,0 +1,37 @@
+What: /sys/bus/event_source/devices/dmar*/format
+Date: Jan 2023
+KernelVersion: 6.3
+Contact: Kan Liang <kan.liang@linux.intel.com>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config,
+ perf_event_attr.config1 or perf_event_attr.config2 for
+ the IOMMU pmu. (See also
+ ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute in this group defines a bit range in
+ perf_event_attr.config, perf_event_attr.config1,
+ or perf_event_attr.config2. All supported attributes
+ are listed below (See the VT-d Spec 4.0 for possible
+ attribute values)::
+
+ event = "config:0-27" - event ID
+ event_group = "config:28-31" - event group ID
+
+ filter_requester_en = "config1:0" - Enable Requester ID filter
+ filter_domain_en = "config1:1" - Enable Domain ID filter
+ filter_pasid_en = "config1:2" - Enable PASID filter
+ filter_ats_en = "config1:3" - Enable Address Type filter
+ filter_page_table_en= "config1:4" - Enable Page Table Level filter
+ filter_requester_id = "config1:16-31" - Requester ID filter
+ filter_domain = "config1:32-47" - Domain ID filter
+ filter_pasid = "config2:0-21" - PASID filter
+ filter_ats = "config2:24-28" - Address Type filter
+ filter_page_table = "config2:32-36" - Page Table Level filter
+
+What: /sys/bus/event_source/devices/dmar*/cpumask
+Date: Jan 2023
+KernelVersion: 6.3
+Contact: Kan Liang <kan.liang@linux.intel.com>
+Description: Read-only. This file always returns the CPU to which the
+ IOMMU pmu is bound for access to all IOMMU pmu performance
+ monitoring events.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore b/Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore
new file mode 100644
index 000000000000..b56e8f019fd4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-uncore
@@ -0,0 +1,13 @@
+What: /sys/bus/event_source/devices/uncore_*/alias
+Date: June 2021
+KernelVersion: 5.15
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Read-only. An attribute to describe the alias name of
+ the uncore PMU if an alias exists on some platforms.
+ The 'perf(1)' tool should treat both names the same.
+ They both can be used to access the uncore PMU.
+
+ Example:
+
+ $ cat /sys/devices/uncore_cha_2/alias
+ uncore_type_0_2
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-dtl b/Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-dtl
new file mode 100644
index 000000000000..7b7c789a5cf5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-dtl
@@ -0,0 +1,25 @@
+What: /sys/bus/event_source/devices/vpa_dtl/format
+Date: February 2025
+Contact: Linux on PowerPC Developer List <linuxppc-dev at lists.ozlabs.org>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config for a particular pmu.
+ (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute under this group defines a bit range of the
+ perf_event_attr.config. Supported attribute are listed
+ below::
+
+ event = "config:0-7" - event ID
+
+ For example::
+
+ dtl_cede = "event=0x1"
+
+What: /sys/bus/event_source/devices/vpa_dtl/events
+Date: February 2025
+Contact: Linux on PowerPC Developer List <linuxppc-dev at lists.ozlabs.org>
+Description: (RO) Attribute group to describe performance monitoring events
+ for the Virtual Processor Dispatch Trace Log. Each attribute in
+ this group describes a single performance monitoring event
+ supported by vpa_dtl pmu. The name of the file is the name of
+ the event (See ABI/testing/sysfs-bus-event_source-devices-events).
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-pmu b/Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-pmu
new file mode 100644
index 000000000000..a116aee9709a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-vpa-pmu
@@ -0,0 +1,25 @@
+What: /sys/bus/event_source/devices/vpa_pmu/format
+Date: November 2024
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: Read-only. Attribute group to describe the magic bits
+ that go into perf_event_attr.config for a particular pmu.
+ (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute under this group defines a bit range of the
+ perf_event_attr.config. Supported attribute are listed
+ below::
+
+ event = "config:0-31" - event ID
+
+ For example::
+
+ l1_to_l2_lat = "event=0x1"
+
+What: /sys/bus/event_source/devices/vpa_pmu/events
+Date: November 2024
+Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
+Description: Read-only. Attribute group to describe performance monitoring
+ events for the Virtual Processor Area events. Each attribute
+ in this group describes a single performance monitoring event
+ supported by vpa_pmu. The name of the file is the name of
+ the event (See ABI/testing/sysfs-bus-event_source-devices-events).
diff --git a/Documentation/ABI/testing/sysfs-bus-fcoe b/Documentation/ABI/testing/sysfs-bus-fcoe
index 21640eaad371..5a4f2091ac37 100644
--- a/Documentation/ABI/testing/sysfs-bus-fcoe
+++ b/Documentation/ABI/testing/sysfs-bus-fcoe
@@ -3,16 +3,19 @@ Date: August 2012
KernelVersion: TBD
Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org
Description: The FCoE bus. Attributes in this directory are control interfaces.
+
Attributes:
- ctlr_create: 'FCoE Controller' instance creation interface. Writing an
+ ctlr_create:
+ 'FCoE Controller' instance creation interface. Writing an
<ifname> to this file will allocate and populate sysfs with a
fcoe_ctlr_device (ctlr_X). The user can then configure any
per-port settings and finally write to the fcoe_ctlr_device's
'start' attribute to begin the kernel's discovery and login
process.
- ctlr_destroy: 'FCoE Controller' instance removal interface. Writing a
+ ctlr_destroy:
+ 'FCoE Controller' instance removal interface. Writing a
fcoe_ctlr_device's sysfs name to this file will log the
fcoe_ctlr_device out of the fabric or otherwise connected
FCoE devices. It will also free all kernel memory allocated
@@ -28,15 +31,17 @@ Description: 'FCoE Controller' instances on the fcoe bus.
1) Write interface name to ctlr_create 2) Configure the FCoE
Controller (ctlr_X) 3) Enable the FCoE Controller to begin
discovery and login. The FCoE Controller is destroyed by
- writing it's name, i.e. ctlr_X to the ctlr_delete file.
+ writing its name, i.e. ctlr_X to the ctlr_delete file.
Attributes:
- fcf_dev_loss_tmo: Device loss timeout peroid (see below). Changing
+ fcf_dev_loss_tmo:
+ Device loss timeout period (see below). Changing
this value will change the dev_loss_tmo for all
FCFs discovered by this controller.
- mode: Display or change the FCoE Controller's mode. Possible
+ mode:
+ Display or change the FCoE Controller's mode. Possible
modes are 'Fabric' and 'VN2VN'. If a FCoE Controller
is started in 'Fabric' mode then FIP FCF discovery is
initiated and ultimately a fabric login is attempted.
@@ -44,24 +49,31 @@ Attributes:
FIP VN2VN discovery and login is performed. A FCoE
Controller only supports one mode at a time.
- enabled: Whether an FCoE controller is enabled or disabled.
+ enabled:
+ Whether an FCoE controller is enabled or disabled.
0 if disabled, 1 if enabled. Writing either 0 or 1
to this file will enable or disable the FCoE controller.
- lesb/link_fail: Link Error Status Block (LESB) link failure count.
+ lesb/link_fail:
+ Link Error Status Block (LESB) link failure count.
- lesb/vlink_fail: Link Error Status Block (LESB) virtual link
+ lesb/vlink_fail:
+ Link Error Status Block (LESB) virtual link
failure count.
- lesb/miss_fka: Link Error Status Block (LESB) missed FCoE
+ lesb/miss_fka:
+ Link Error Status Block (LESB) missed FCoE
Initialization Protocol (FIP) Keep-Alives (FKA).
- lesb/symb_err: Link Error Status Block (LESB) symbolic error count.
+ lesb/symb_err:
+ Link Error Status Block (LESB) symbolic error count.
- lesb/err_block: Link Error Status Block (LESB) block error count.
+ lesb/err_block:
+ Link Error Status Block (LESB) block error count.
- lesb/fcs_error: Link Error Status Block (LESB) Fibre Channel
- Serivces error count.
+ lesb/fcs_error:
+ Link Error Status Block (LESB) Fibre Channel
+ Services error count.
Notes: ctlr_X (global increment starting at 0)
@@ -75,35 +87,45 @@ Description: 'FCoE FCF' instances on the fcoe bus. A FCF is a Fibre Channel
Fibre Channel frames into a FC fabric. It can also take
outbound FC frames and pack them in Ethernet packets to
be sent to their destination on the Ethernet segment.
+
Attributes:
- fabric_name: Identifies the fabric that the FCF services.
+ fabric_name:
+ Identifies the fabric that the FCF services.
- switch_name: Identifies the FCF.
+ switch_name:
+ Identifies the FCF.
- priority: The switch's priority amongst other FCFs on the same
+ priority:
+ The switch's priority amongst other FCFs on the same
fabric.
- selected: 1 indicates that the switch has been selected for use;
- 0 indicates that the swich will not be used.
+ selected:
+ 1 indicates that the switch has been selected for use;
+ 0 indicates that the switch will not be used.
- fc_map: The Fibre Channel MAP
+ fc_map:
+ The Fibre Channel MAP
- vfid: The Virtual Fabric ID
+ vfid:
+ The Virtual Fabric ID
- mac: The FCF's MAC address
+ mac:
+ The FCF's MAC address
- fka_peroid: The FIP Keep-Alive peroid
+ fka_period:
+ The FIP Keep-Alive period
fabric_state: The internal kernel state
- "Unknown" - Initialization value
- "Disconnected" - No link to the FCF/fabric
- "Connected" - Host is connected to the FCF
- "Deleted" - FCF is being removed from the system
- dev_loss_tmo: The device loss timeout peroid for this FCF.
+ - "Unknown" - Initialization value
+ - "Disconnected" - No link to the FCF/fabric
+ - "Connected" - Host is connected to the FCF
+ - "Deleted" - FCF is being removed from the system
+
+ dev_loss_tmo: The device loss timeout period for this FCF.
-Notes: A device loss infrastructre similar to the FC Transport's
+Notes: A device loss infrastructure similar to the FC Transport's
is present in fcoe_sysfs. It is nice to have so that a
link flapping adapter doesn't continually advance the count
used to identify the discovered FCF. FCFs will exist in a
diff --git a/Documentation/ABI/testing/sysfs-bus-fsi b/Documentation/ABI/testing/sysfs-bus-fsi
new file mode 100644
index 000000000000..76e0caa0c2b3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-fsi
@@ -0,0 +1,46 @@
+What: /sys/bus/platform/devices/../fsi-master/fsi0/rescan
+Date: May 2017
+KernelVersion: 4.12
+Contact: linux-fsi@lists.ozlabs.org
+Description:
+ Initiates a FSI master scan for all connected slave devices
+ on its links.
+
+What: /sys/bus/platform/devices/../fsi-master/fsi0/break
+Date: May 2017
+KernelVersion: 4.12
+Contact: linux-fsi@lists.ozlabs.org
+Description:
+ Sends an FSI BREAK command on a master's communication
+ link to any connected slaves. A BREAK resets connected
+ device's logic and preps it to receive further commands
+ from the master.
+
+What: /sys/bus/platform/devices/../fsi-master/fsi0/slave@00:00/term
+Date: May 2017
+KernelVersion: 4.12
+Contact: linux-fsi@lists.ozlabs.org
+Description:
+ Sends an FSI terminate command from the master to its
+ connected slave. A terminate resets the slave's state machines
+ that control access to the internally connected engines. In
+ addition the slave freezes its internal error register for
+ debugging purposes. This command is also needed to abort any
+ ongoing operation in case of an expired 'Master Time Out'
+ timer.
+
+What: /sys/bus/platform/devices/../fsi-master/fsi0/slave@00:00/raw
+Date: May 2017
+KernelVersion: 4.12
+Contact: linux-fsi@lists.ozlabs.org
+Description:
+ Provides a means of reading/writing a 32 bit value from/to a
+ specified FSI bus address.
+
+What: /sys/bus/platform/devices/../cfam_reset
+Date: Sept 2020
+KernelVersion: 5.10
+Contact: linux-fsi@lists.ozlabs.org
+Description:
+ Provides a means of resetting the cfam that is attached to the
+ FSI device.
diff --git a/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo b/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo
new file mode 100644
index 000000000000..c7393b4dd2d8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-fsi-devices-sbefifo
@@ -0,0 +1,10 @@
+What: /sys/bus/fsi/devices/XX.XX.00:06/sbefifoX/timeout
+KernelVersion: 5.15
+Contact: eajames@linux.ibm.com
+Description:
+ Indicates whether or not this SBE device has experienced a
+ timeout; i.e. the SBE did not respond within the time allotted
+ by the driver. A value of 1 indicates that a timeout has
+ occurred and no transfers have completed since the timeout. A
+ value of 0 indicates that no timeout has occurred, or if one
+ has, more recent transfers have completed successfully.
diff --git a/Documentation/ABI/testing/sysfs-bus-fsl-mc b/Documentation/ABI/testing/sysfs-bus-fsl-mc
new file mode 100644
index 000000000000..bf3c6af6ad89
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-fsl-mc
@@ -0,0 +1,25 @@
+What: /sys/bus/fsl-mc/drivers/.../bind
+Date: December 2016
+Contact: stuart.yoder@nxp.com
+Description:
+ Writing a device location to this file will cause
+ the driver to attempt to bind to the device found at
+ this location. The format for the location is Object.Id
+ and is the same as found in /sys/bus/fsl-mc/devices/.
+
+ For example::
+
+ # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/bind
+
+What: /sys/bus/fsl-mc/drivers/.../unbind
+Date: December 2016
+Contact: stuart.yoder@nxp.com
+Description:
+ Writing a device location to this file will cause the
+ driver to attempt to unbind from the device found at
+ this location. The format for the location is Object.Id
+ and is the same as found in /sys/bus/fsl-mc/devices/.
+
+ For example::
+
+ # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k b/Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k
new file mode 100644
index 000000000000..398b258fb770
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k
@@ -0,0 +1,7 @@
+What: /sys/bus/i2c/devices/.../trickle_charge_bypass
+Date: Jan 2017
+KernelVersion: 4.11
+Contact: Enric Balletbo i Serra <eballetbo@gmail.com>
+Description: Attribute for enable/disable the trickle charge bypass
+ The trickle_charge_bypass attribute allows the userspace to
+ enable/disable the Trickle charge FET bypass.
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
index 9de269bb0ae5..288bc2fa9547 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
@@ -3,19 +3,25 @@ Date: February 2011
Contact: Minkyu Kang <mk7.kang@samsung.com>
Description:
show what device is attached
- NONE - no device
- USB - USB device is attached
- UART - UART is attached
- CHARGER - Charger is attaced
- JIG - JIG is attached
+
+ ======= ======================
+ NONE no device
+ USB USB device is attached
+ UART UART is attached
+ CHARGER Charger is attached
+ JIG JIG is attached
+ ======= ======================
What: /sys/bus/i2c/devices/.../switch
Date: February 2011
Contact: Minkyu Kang <mk7.kang@samsung.com>
Description:
show or set the state of manual switch
- VAUDIO - switch to VAUDIO path
- UART - switch to UART path
- AUDIO - switch to AUDIO path
- DHOST - switch to DHOST path
- AUTO - switch automatically by device
+
+ ======= ==============================
+ VAUDIO switch to VAUDIO path
+ UART switch to UART path
+ AUDIO switch to AUDIO path
+ DHOST switch to DHOST path
+ AUTO switch automatically by device
+ ======= ==============================
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
index feb2e4a87075..4a251b7f11e4 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
@@ -1,20 +1,20 @@
-Where: /sys/bus/i2c/devices/.../heading0_input
+What: /sys/bus/i2c/devices/.../heading0_input
Date: April 2010
-Kernel Version: 2.6.36?
+KernelVersion: 2.6.36?
Contact: alan.cox@intel.com
Description: Reports the current heading from the compass as a floating
point value in degrees.
-Where: /sys/bus/i2c/devices/.../power_state
+What: /sys/bus/i2c/devices/.../power_state
Date: April 2010
-Kernel Version: 2.6.36?
+KernelVersion: 2.6.36?
Contact: alan.cox@intel.com
Description: Sets the power state of the device. 0 sets the device into
sleep mode, 1 wakes it up.
-Where: /sys/bus/i2c/devices/.../calibration
+What: /sys/bus/i2c/devices/.../calibration
Date: April 2010
-Kernel Version: 2.6.36?
+KernelVersion: 2.6.36?
Contact: alan.cox@intel.com
Description: Sets the calibration on or off (1 = on, 0 = off). See the
chip data sheet.
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr
new file mode 100644
index 000000000000..7c51ce8d38ba
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-m24lr
@@ -0,0 +1,100 @@
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/unlock
+Date: 2025-07-04
+KernelVersion: 6.17
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Write-only attribute used to present a password and unlock
+ access to protected areas of the M24LR chip, including
+ configuration registers such as the Sector Security Status
+ (SSS) bytes. A valid password must be written to enable write
+ access to these regions via the I2C interface.
+
+ Format:
+ - Hexadecimal string representing a 32-bit (4-byte) password
+ - Accepts 1 to 8 hex digits (e.g., "c", "1F", "a1b2c3d4")
+ - No "0x" prefix, whitespace, or trailing newline
+ - Case-insensitive
+
+ Behavior:
+ - If the password matches the internal stored value,
+ access to protected memory/configuration is granted
+ - If the password does not match the internally stored value,
+ it will fail silently
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/new_pass
+Date: 2025-07-04
+KernelVersion: 6.17
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Write-only attribute used to update the password required to
+ unlock the M24LR chip.
+
+ Format:
+ - Hexadecimal string representing a new 32-bit password
+ - Accepts 1 to 8 hex digits (e.g., "1A", "ffff", "c0ffee00")
+ - No "0x" prefix, whitespace, or trailing newline
+ - Case-insensitive
+
+ Behavior:
+ - Overwrites the current password stored in the I2C password
+ register
+ - Requires the device to be unlocked before changing the
+ password
+ - If the device is locked, the write silently fails
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/uid
+Date: 2025-07-04
+KernelVersion: 6.17
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Read-only attribute that exposes the 8-byte unique identifier
+ programmed into the M24LR chip at the factory.
+
+ Format:
+ - Lowercase hexadecimal string representing a 64-bit value
+ - 1 to 16 hex digits (e.g., "e00204f12345678")
+ - No "0x" prefix
+ - Includes a trailing newline
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/total_sectors
+Date: 2025-07-04
+KernelVersion: 6.17
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Read-only attribute that exposes the total number of EEPROM
+ sectors available in the M24LR chip.
+
+ Format:
+ - 1 to 2 hex digits (e.g. "F")
+ - No "0x" prefix
+ - Includes a trailing newline
+
+ Notes:
+ - Value is encoded by the chip and corresponds to the EEPROM
+ size (e.g., 3 = 4 kbit for M24LR04E-R)
+
+What: /sys/bus/i2c/devices/<busnum>-<primary-addr>/sss
+Date: 2025-07-04
+KernelVersion: 6.17
+Contact: Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+Description:
+ Read/write binary attribute representing the Sector Security
+ Status (SSS) bytes for all EEPROM sectors in STMicroelectronics
+ M24LR chips.
+
+ Each EEPROM sector has one SSS byte, which controls I2C and
+ RF access through protection bits and optional password
+ authentication.
+
+ Format:
+ - The file contains one byte per EEPROM sector
+ - Byte at offset N corresponds to sector N
+ - Binary access only; use tools like dd, Python, or C that
+ support byte-level I/O and offset control.
+
+ Notes:
+ - The number of valid bytes in this file is equal to the
+ value exposed by 'total_sectors' file
+ - Write access requires prior password authentication in
+ I2C mode
+ - Refer to the M24LR datasheet for full SSS bit layout
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
new file mode 100644
index 000000000000..b6c69eb80ca4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
@@ -0,0 +1,23 @@
+What: /sys/bus/i2c/.../idle_state
+Date: January 2019
+KernelVersion: 5.2
+Contact: Robert Shearman <robert.shearman@att.com>
+Description:
+ Value that exists only for mux devices that can be
+ written to control the behaviour of the multiplexer on
+ idle. Possible values:
+
+ =========== ===============================================
+ -2 disconnect on idle, i.e. deselect the last used
+ channel, which is useful when there is a device
+ with an address that conflicts with another
+ device on another mux on the same parent bus.
+ -1 leave the mux as-is, which is the most optimal
+ setting in terms of I2C operations and is the
+ default mode.
+ 0..<nchans> set the mux to a predetermined channel,
+ which is useful if there is one channel that is
+ used almost always, and you want to reduce the
+ latency for normal operations after rare
+ transactions on other channels
+ =========== ===============================================
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-turris-omnia-mcu b/Documentation/ABI/testing/sysfs-bus-i2c-devices-turris-omnia-mcu
new file mode 100644
index 000000000000..35a8f6dae5bf
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-turris-omnia-mcu
@@ -0,0 +1,113 @@
+What: /sys/bus/i2c/devices/<mcu_device>/board_revision
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains board revision number.
+
+ Only available if board information is burned in the MCU (older
+ revisions have board information burned in the ATSHA204-A chip).
+
+ Format: %u.
+
+What: /sys/bus/i2c/devices/<mcu_device>/first_mac_address
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains device first MAC address. Each Turris Omnia is
+ allocated 3 MAC addresses. The two additional addresses are
+ computed from the first one by incrementing it.
+
+ Only available if board information is burned in the MCU (older
+ revisions have board information burned in the ATSHA204-A chip).
+
+ Format: %pM.
+
+What: /sys/bus/i2c/devices/<mcu_device>/front_button_mode
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RW) The front button on the Turris Omnia router can be
+ configured either to change the intensity of all the LEDs on the
+ front panel, or to send the press event to the CPU as an
+ interrupt.
+
+ This file switches between these two modes:
+ - ``mcu`` makes the button press event be handled by the MCU to
+ change the LEDs panel intensity.
+ - ``cpu`` makes the button press event be handled by the CPU.
+
+ Format: %s.
+
+What: /sys/bus/i2c/devices/<mcu_device>/front_button_poweron
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RW) Newer versions of the microcontroller firmware of the
+ Turris Omnia router support powering off the router into true
+ low power mode. The router can be powered on by pressing the
+ front button.
+
+ This file configures whether front button power on is enabled.
+
+ This file is present only if the power off feature is supported
+ by the firmware.
+
+ Format: %i.
+
+What: /sys/bus/i2c/devices/<mcu_device>/fw_features
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Newer versions of the microcontroller firmware report the
+ features they support. These can be read from this file. If the
+ MCU firmware is too old, this file reads 0x0.
+
+ Format: 0x%x.
+
+What: /sys/bus/i2c/devices/<mcu_device>/fw_version_hash_application
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains the version hash (commit hash) of the application
+ part of the microcontroller firmware.
+
+ Format: %s.
+
+What: /sys/bus/i2c/devices/<mcu_device>/fw_version_hash_bootloader
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains the version hash (commit hash) of the bootloader
+ part of the microcontroller firmware.
+
+ Format: %s.
+
+What: /sys/bus/i2c/devices/<mcu_device>/mcu_type
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains the microcontroller type (STM32, GD32, MKL).
+
+ Format: %s.
+
+What: /sys/bus/i2c/devices/<mcu_device>/reset_selector
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains the selected factory reset level, determined by
+ how long the rear reset button was held by the user during board
+ reset.
+
+ Format: %i.
+
+What: /sys/bus/i2c/devices/<mcu_device>/serial_number
+Date: September 2024
+KernelVersion: 6.11
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RO) Contains the 64-bit board serial number in hexadecimal
+ format.
+
+ Only available if board information is burned in the MCU (older
+ revisions have board information burned in the ATSHA204-A chip).
+
+ Format: %016X.
diff --git a/Documentation/ABI/testing/sysfs-bus-i3c b/Documentation/ABI/testing/sysfs-bus-i3c
new file mode 100644
index 000000000000..c812ab180ff4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-i3c
@@ -0,0 +1,163 @@
+What: /sys/bus/i3c/devices/i3c-<bus-id>
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ An I3C bus. This directory will contain one sub-directory per
+ I3C device present on the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/current_master
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ Expose the master that owns the bus (<bus-id>-<master-pid>) at
+ the time this file is read. Note that bus ownership can change
+ overtime, so there's no guarantee that when the read() call
+ returns, the value returned is still valid.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/mode
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ I3C bus mode. Can be "pure", "mixed-fast" or "mixed-slow". See
+ the I3C specification for a detailed description of what each
+ of these modes implies.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/i3c_scl_frequency
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ The frequency (expressed in Hz) of the SCL signal when
+ operating in I3C SDR mode.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/i2c_scl_frequency
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ The frequency (expressed in Hz) of the SCL signal when
+ operating in I2C mode.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/dynamic_address
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ Dynamic address assigned to the master controller. This
+ address may change if the bus is re-initialized.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/bcr
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ BCR stands for Bus Characteristics Register and express the
+ device capabilities in term of speed, maximum read/write
+ length, etc. See the I3C specification for more details.
+ This entry describes the BCR of the master controller driving
+ the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/dcr
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ DCR stands for Device Characteristics Register and express the
+ device capabilities in term of exposed features. See the I3C
+ specification for more details.
+ This entry describes the DCR of the master controller driving
+ the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/pid
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ PID stands for Provisioned ID and is used to uniquely identify
+ a device on a bus. This PID contains information about the
+ vendor, the part and an instance ID so that several devices of
+ the same type can be connected on the same bus.
+ See the I3C specification for more details.
+ This entry describes the PID of the master controller driving
+ the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/hdrcap
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ Expose the HDR (High Data Rate) capabilities of a device.
+ Returns a list of supported HDR mode, each element is separated
+ by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl".
+ See the I3C specification for more details about these HDR
+ modes.
+
+ This entry describes the HDRCAP of the master controller
+ driving the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/hotjoin
+KernelVersion: 6.8
+Contact: linux-i3c@vger.kernel.org
+Description:
+ I3C’s Hot-Join mechanism allows an I3C Device to inform the
+ Active Controller that a newly-joined Target is present on the
+ I3C Bus and is ready to receive a Dynamic Address, in order to
+ become fully functional on the Bus. Hot-Join is used when the
+ Target is mounted on the same I3C bus and remains depowered
+ until needed or until the Target is physically inserted into the
+ I3C bus
+
+ This entry allows to enable or disable Hot-join of the Current
+ Controller driving the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ An I3C device present on I3C bus identified by <bus-id>. Note
+ that all devices are represented including the master driving
+ the bus.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/dynamic_address
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ Dynamic address assigned to device <bus-id>-<device-pid>. This
+ address may change if the bus is re-initialized.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/bcr
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ BCR stands for Bus Characteristics Register and express the
+ device capabilities in term of speed, maximum read/write
+ length, etc. See the I3C specification for more details.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/dcr
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ DCR stands for Device Characteristics Register and express the
+ device capabilities in term of exposed features. See the I3C
+ specification for more details.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/pid
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ PID stands for Provisioned ID and is used to uniquely identify
+ a device on a bus. This PID contains information about the
+ vendor, the part and an instance ID so that several devices of
+ the same type can be connected on the same bus.
+ See the I3C specification for more details.
+
+What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/hdrcap
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ Expose the HDR (High Data Rate) capabilities of a device.
+ Returns a list of supported HDR mode, each element is separated
+ by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl".
+
+ See the I3C specification for more details about these HDR
+ modes.
+
+What: /sys/bus/i3c/devices/<bus-id>-<device-pid>
+KernelVersion: 5.0
+Contact: linux-i3c@vger.kernel.org
+Description:
+ These directories are just symbolic links to
+ /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 3befcb19f414..5f87dcee78f7 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -15,6 +15,7 @@ Description:
based on hardware generated events (e.g. data ready) or
provided by a separate driver for other hardware (e.g.
periodic timer, GPIO or high resolution timer).
+
Contains trigger type specific elements. These do not
generalize well and hence are not documented in this file.
X is the IIO index of the trigger.
@@ -32,8 +33,68 @@ Description:
Description of the physical chip / device for device X.
Typically a part number.
+What: /sys/bus/iio/devices/iio:deviceX/label
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Optional symbolic label for a device.
+ This is useful for userspace to be able to better identify an
+ individual device.
+
+ The contents of the label are free-form, but there are some
+ standardized uses:
+
+ For proximity sensors which give the proximity (of a person) to
+ a certain wlan or wwan antenna the following standardized labels
+ are used:
+
+ * "proximity-wifi"
+ * "proximity-lte"
+ * "proximity-wifi-lte"
+ * "proximity-wifi-left"
+ * "proximity-wifi-right"
+
+ These are used to indicate to userspace that these proximity
+ sensors may be used to tune transmit power to ensure that
+ Specific Absorption Rate (SAR) limits are honored.
+ The "-left" and "-right" labels are for devices with multiple
+ antennas.
+
+ In some laptops/tablets the standardized proximity sensor labels
+ instead indicate proximity to a specific part of the device:
+
+ * "proximity-palmrest" indicates proximity to the keyboard's palmrest
+ * "proximity-palmrest-left" indicates proximity to the left part of the palmrest
+ * "proximity-palmrest-right" indicates proximity to the right part of the palmrest
+ * "proximity-lap" indicates the device is being used on someone's lap
+
+ Note "proximity-lap" is special in that its value may be
+ calculated by firmware from other sensor readings, rather then
+ being a raw sensor reading.
+
+ For accelerometers used in 2-in-1s with 360° (yoga-style) hinges,
+ which have an accelerometer in both their base and their display,
+ the following standardized labels are used:
+
+ * "accel-base"
+ * "accel-display"
+
+ For devices where an accelerometer is housed in the swivel camera subassembly
+ (for AR application), the following standardized label is used:
+
+ * "accel-camera"
+
+What: /sys/bus/iio/devices/iio:deviceX/current_timestamp_clock
+KernelVersion: 4.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ String identifying current posix clock used to timestamp
+ buffered samples and events for device X.
+
What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency
What: /sys/bus/iio/devices/iio:deviceX/buffer/sampling_frequency
+What: /sys/bus/iio/devices/iio:deviceX/events/sampling_frequency
What: /sys/bus/iio/devices/triggerX/sampling_frequency
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
@@ -42,19 +103,28 @@ Description:
resulting sampling frequency. In many devices this
parameter has an effect on input filters etc. rather than
simply controlling when the input is sampled. As this
- effects data ready triggers, hardware buffers and the sysfs
+ affects data ready triggers, hardware buffers and the sysfs
direct access interfaces, it may be found in any of the
- relevant directories. If it effects all of the above
+ relevant directories. If it affects all of the above
then it is to be found in the base device directory.
+ The stm32-timer-trigger has the additional characteristic that
+ a sampling_frequency of 0 is defined to stop sampling.
+
What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_sampling_frequency_available
What: /sys/.../iio:deviceX/buffer/sampling_frequency_available
What: /sys/bus/iio/devices/triggerX/sampling_frequency_available
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
- When the internal sampling clock can only take a small
- discrete set of values, this file lists those available.
+ When the internal sampling clock can only take a specific set of
+ frequencies, we can specify the available values with:
+
+ - a small discrete set of values like "0 2 4 6 8"
+ - a range with minimum, step and maximum frequencies like
+ "[min step max]"
What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio
KernelVersion: 2.6.38
@@ -81,6 +151,11 @@ Description:
unique to allow association with event codes. Units after
application of scale and offset are millivolts.
+ Channels with 'i' and 'q' modifiers always exist in pairs and both
+ channels refer to the same signal. The 'i' channel contains the in-phase
+ component of the signal while the 'q' channel contains the quadrature
+ component.
+
What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_raw
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
@@ -92,17 +167,32 @@ Description:
is required is a consistent labeling. Units after application
of scale and offset are millivolts.
-What: /sys/bus/iio/devices/iio:deviceX/in_currentY_raw
-What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_raw
-KernelVersion: 3.17
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_rms_raw
+KernelVersion: 6.18
Contact: linux-iio@vger.kernel.org
Description:
- Raw (unscaled no bias removal etc.) current measurement from
- channel Y. In special cases where the channel does not
- correspond to externally available input one of the named
- versions may be used. The number must always be specified and
+ Raw (unscaled) Root Mean Square (RMS) voltage measurement from
+ channel Y. Units after application of scale and offset are
+ millivolts.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_powerY_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_powerY_active_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_powerY_reactive_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_powerY_apparent_raw
+KernelVersion: 4.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled no bias removal etc.) power measurement from
+ channel Y. The number must always be specified and
unique to allow association with event codes. Units after
- application of scale and offset are milliamps.
+ application of scale and offset are milliwatts.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_powerY_powerfactor
+KernelVersion: 6.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Power factor measurement from channel Y. Power factor is the
+ ratio of active power to apparent power. The value is unitless.
What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceY_raw
KernelVersion: 3.2
@@ -111,7 +201,7 @@ Description:
Raw capacitance measurement from channel Y. Units after
application of scale and offset are nanofarads.
-What: /sys/.../iio:deviceX/in_capacitanceY-in_capacitanceZ_raw
+What: /sys/.../iio:deviceX/in_capacitanceY-capacitanceZ_raw
KernelVersion: 3.2
Contact: linux-iio@vger.kernel.org
Description:
@@ -122,8 +212,27 @@ Description:
is required is a consistent labeling. Units after application
of scale and offset are nanofarads.
+What: /sys/.../iio:deviceX/in_capacitanceY-capacitanceZ_zeropoint
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ For differential channels, this an offset that is applied
+ equally to both inputs. As the reading is of the difference
+ between the two inputs, this should not be applied to the _raw
+ reading by userspace (unlike _offset) and unlike calibbias
+ it does not affect the differential value measured because
+ the effect of _zeropoint cancels out across the two inputs
+ that make up the differential pair. It's purpose is to bring
+ the individual signals, before the differential is measured,
+ within the measurement range of the device. The naming is
+ chosen because if the separate inputs that make the
+ differential pair are drawn on a graph in their
+ _raw units, this is the value that the zero point on the
+ measurement axis represents. It is expressed with the
+ same scaling as _raw.
+
What: /sys/bus/iio/devices/iio:deviceX/in_temp_raw
-What: /sys/bus/iio/devices/iio:deviceX/in_tempX_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_tempY_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_x_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_y_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_ambient_raw
@@ -139,7 +248,8 @@ Description:
less measurements. Units after application of scale and offset
are milli degrees Celsius.
-What: /sys/bus/iio/devices/iio:deviceX/in_tempX_input
+What: /sys/bus/iio/devices/iio:deviceX/in_tempY_input
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_input
KernelVersion: 2.6.38
Contact: linux-iio@vger.kernel.org
Description:
@@ -156,6 +266,74 @@ Description:
Has all of the equivalent parameters as per voltageY. Units
after application of scale and offset are m/s^2.
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_linear_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_linear_y_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_linear_z_raw
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ As per in_accel_X_raw attributes, but minus the
+ acceleration due to gravity.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_gravity_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_gravity_y_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_gravity_z_raw
+KernelVersion: 4.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ Gravity in direction x, y or z (may be arbitrarily assigned
+ but should match other such assignments on device).
+ Units after application of scale and offset are m/s^2.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_y_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_z_raw
+KernelVersion: 6.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ Angular displacement between two consecutive samples on x, y or
+ z (may be arbitrarily assigned but should match other such
+ assignments on device).
+ In order to compute the total angular displacement during a
+ desired period of time, the application should sum-up the delta
+ angle samples acquired during that time.
+ Units after application of scale and offset are radians.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_y_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_z_raw
+KernelVersion: 6.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ The linear velocity change between two consecutive samples on x,
+ y or z (may be arbitrarily assigned but should match other such
+ assignments on device).
+ In order to compute the total linear velocity change during a
+ desired period of time, the application should sum-up the delta
+ velocity samples acquired during that time.
+ Units after application of scale and offset are meters per
+ second.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_angl_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_anglY_raw
+KernelVersion: 4.17
+Contact: linux-iio@vger.kernel.org
+Description:
+ Angle of rotation. Units after application of scale and offset
+ are radians.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_positionrelative_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_positionrelative_y_raw
+KernelVersion: 4.19
+Contact: linux-iio@vger.kernel.org
+Description:
+ Relative position in direction x or y on a pad (may be
+ arbitrarily assigned but should match other such assignments on
+ device).
+ Units after application of scale and offset are milli percents
+ from the pad's size in both directions. Should be calibrated by
+ the consumer.
+
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_raw
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_raw
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_raw
@@ -190,10 +368,21 @@ Description:
What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_peak_raw
What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_peak_raw
What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_peak_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_peak_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_peak_raw
KernelVersion: 2.6.36
Contact: linux-iio@vger.kernel.org
Description:
- Highest value since some reset condition. These
+ Highest value since some reset condition. These
+ attributes allow access to this and are otherwise
+ the direct equivalent of the <type>Y[_name]_raw attributes.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_trough_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_trough_raw
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Lowest value since some reset condition. These
attributes allow access to this and are otherwise
the direct equivalent of the <type>Y[_name]_raw attributes.
@@ -232,11 +421,11 @@ Contact: linux-iio@vger.kernel.org
Description:
Scaled humidity measurement in milli percent.
-What: /sys/bus/iio/devices/iio:deviceX/in_X_mean_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_Y_mean_raw
KernelVersion: 3.5
Contact: linux-iio@vger.kernel.org
Description:
- Averaged raw measurement from channel X. The number of values
+ Averaged raw measurement from channel Y. The number of values
used for averaging is device specific. The converting rules for
normal raw values also applies to the averaged raw values.
@@ -244,8 +433,12 @@ What: /sys/bus/iio/devices/iio:deviceX/in_accel_offset
What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_offset
What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_offset
What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_offset
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage_q_offset
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage_i_offset
What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_offset
What: /sys/bus/iio/devices/iio:deviceX/in_voltage_offset
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_i_offset
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_q_offset
What: /sys/bus/iio/devices/iio:deviceX/in_currentY_offset
What: /sys/bus/iio/devices/iio:deviceX/in_current_offset
What: /sys/bus/iio/devices/iio:deviceX/in_tempY_offset
@@ -255,6 +448,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_pressure_offset
What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset
What: /sys/bus/iio/devices/iio:deviceX/in_magn_offset
What: /sys/bus/iio/devices/iio:deviceX/in_rot_offset
+What: /sys/bus/iio/devices/iio:deviceX/in_angl_offset
+What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceY_offset
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
@@ -273,6 +468,7 @@ Description:
to the _raw output.
What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_q_scale
What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale
What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale
What: /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_scale
@@ -281,6 +477,7 @@ What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale
What: /sys/bus/iio/devices/iio:deviceX/in_currentY_scale
What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_scale
What: /sys/bus/iio/devices/iio:deviceX/in_current_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_current_q_scale
What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale
What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale
@@ -299,6 +496,17 @@ What: /sys/bus/iio/devices/iio:deviceX/in_pressure_scale
What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_scale
What: /sys/bus/iio/devices/iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_scale
What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_countY_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_angl_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_x_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_y_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_z_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_scale
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_scale
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
@@ -313,33 +521,98 @@ Description:
What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_i_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_q_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_capacitance_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibbias
-What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibbias
-What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_calibbias
What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_resistance_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/out_currentY_calibbias
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_calibbias
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
Hardware applied calibration offset (assumed to fix production
inaccuracies).
+ icm42600: For this device values are real physical offsets
+ expressed in SI units (m/s^2 for accelerometers and rad/s
+ for gyroscope)/
-What /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale
-What /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale
-what /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale
-what /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale
-What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibscale
-What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_calibbias_available
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_calibbias_available
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibbias_available
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_calibbias_available
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Available values of calibbias. Maybe expressed as either of:
+
+ - a small discrete set of values like "0 2 4 6 8"
+ - a range specified as "[min step max]"
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_convdelay
+KernelVersion: 6.17
+Contact: linux-iio@vger.kernel.org
+Description:
+ Delay of start of conversion from common reference point shared
+ by all channels. Can be writable when used to compensate for
+ delay variation introduced by external filters feeding a
+ simultaneous sampling ADC.
+
+ E.g., for the ad7606 ADC series, this value is intended as a
+ configurable time delay in seconds, to correct delay introduced
+ by an optional external filtering circuit.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_convdelay_available
+KernelVersion: 6.16
+Contact: linux-iio@vger.kernel.org
+Description:
+ Available values of convdelay. Maybe expressed as:
+
+ - a range specified as "[min step max]"
+
+ If shared across all channels, <type>_convdelay_available
+ is used.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_capacitance_calibscale
What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_both_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ir_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/out_currentY_calibscale
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_calibscale
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
@@ -347,6 +620,20 @@ Description:
production inaccuracies). If shared across all channels,
<type>_calibscale is used.
+What: /sys/bus/iio/devices/iio:deviceX/in_illuminanceY_calibscale_available
+What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_calibscale_available
+What: /sys/bus/iio/devices/iio:deviceX/in_proximityY_calibscale_available
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale_available
+KernelVersion: 4.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Available values of calibscale. Maybe expressed as either of:
+
+ - a small discrete set of values like "1 8 16"
+ - a range specified as "[min step max]"
+
+ If shared across all channels, <type>_calibscale_available is used.
+
What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibgender
What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibgender
What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibgender
@@ -386,10 +673,15 @@ Description:
to compute the calories burnt by the user.
What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale_available
-What: /sys/.../iio:deviceX/in_voltageX_scale_available
+What: /sys/.../iio:deviceX/in_anglvel_scale_available
+What: /sys/.../iio:deviceX/in_magn_scale_available
+What: /sys/.../iio:deviceX/in_illuminance_scale_available
+What: /sys/.../iio:deviceX/in_intensity_scale_available
+What: /sys/.../iio:deviceX/in_proximity_scale_available
+What: /sys/.../iio:deviceX/in_voltageY_scale_available
What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available
-What: /sys/.../iio:deviceX/out_voltageX_scale_available
-What: /sys/.../iio:deviceX/out_altvoltageX_scale_available
+What: /sys/.../iio:deviceX/out_voltageY_scale_available
+What: /sys/.../iio:deviceX/out_altvoltageY_scale_available
What: /sys/.../iio:deviceX/in_capacitance_scale_available
What: /sys/.../iio:deviceX/in_pressure_scale_available
What: /sys/.../iio:deviceX/in_pressureY_scale_available
@@ -397,19 +689,30 @@ KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
If a discrete set of scale values is available, they
- are listed in this attribute.
+ are listed in this attribute. Unlike illumination,
+ multiplying intensity by intensity_scale does not
+ yield value with any standardized unit.
-What /sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_hardwaregain
What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain
What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain
What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain
What: /sys/bus/iio/devices/iio:deviceX/in_intensity_clear_hardwaregain
+What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_hardwaregain
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
Hardware applied gain factor. If shared across all channels,
<type>_hardwaregain is used.
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_hardwaregain_available
+KernelVersion: 5.10
+Contact: linux-iio@vger.kernel.org
+Description:
+ Lists all available hardware applied gain factors. Shared across all
+ channels.
+
What: /sys/.../in_accel_filter_low_pass_3db_frequency
What: /sys/.../in_magn_filter_low_pass_3db_frequency
What: /sys/.../in_anglvel_filter_low_pass_3db_frequency
@@ -420,6 +723,16 @@ Description:
to the underlying data channel, then this parameter
gives the 3dB frequency of the filter in Hz.
+What: /sys/.../in_accel_filter_high_pass_3db_frequency
+What: /sys/.../in_anglvel_filter_high_pass_3db_frequency
+What: /sys/.../in_magn_filter_high_pass_3db_frequency
+KernelVersion: 4.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ If a known or controllable high pass filter is applied
+ to the underlying data channel, then this parameter
+ gives the 3dB frequency of the filter in Hz.
+
What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw
What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_raw
KernelVersion: 2.6.37
@@ -451,19 +764,26 @@ Contact: linux-iio@vger.kernel.org
Description:
Specifies the output powerdown mode.
DAC output stage is disconnected from the amplifier and
- 1kohm_to_gnd: connected to ground via an 1kOhm resistor,
+ 1kohm_to_gnd: connected to ground via an 1kOhm resistor,
+ 2.5kohm_to_gnd: connected to ground via a 2.5kOhm resistor,
6kohm_to_gnd: connected to ground via a 6kOhm resistor,
+ 7.7kohm_to_gnd: connected to ground via a 7.7kOhm resistor,
20kohm_to_gnd: connected to ground via a 20kOhm resistor,
+ 32kohm_to_gnd: connected to ground via a 32kOhm resistor,
+ 42kohm_to_gnd: connected to ground via a 42kOhm resistor,
+ 90kohm_to_gnd: connected to ground via a 90kOhm resistor,
100kohm_to_gnd: connected to ground via an 100kOhm resistor,
+ 125kohm_to_gnd: connected to ground via an 125kOhm resistor,
500kohm_to_gnd: connected to ground via a 500kOhm resistor,
+ 640kohm_to_gnd: connected to ground via a 640kOhm resistor,
three_state: left floating.
For a list of available output power down options read
outX_powerdown_mode_available. If Y is not present the
mode is shared across all outputs.
-What: /sys/.../iio:deviceX/out_votlageY_powerdown_mode_available
+What: /sys/.../iio:deviceX/out_voltageY_powerdown_mode_available
What: /sys/.../iio:deviceX/out_voltage_powerdown_mode_available
-What: /sys/.../iio:deviceX/out_altvotlageY_powerdown_mode_available
+What: /sys/.../iio:deviceX/out_altvoltageY_powerdown_mode_available
What: /sys/.../iio:deviceX/out_altvoltage_powerdown_mode_available
KernelVersion: 2.6.38
Contact: linux-iio@vger.kernel.org
@@ -491,8 +811,31 @@ Description:
Output frequency for channel Y in Hz. The number must always be
specified and unique if the output corresponds to a single
channel.
-
+ Some drivers have additional constraints:
+ ADF4371 has an integrated VCO with fundamendal output
+ frequency ranging from 4000000000 Hz 8000000000 Hz.
+
+ out_altvoltage0_frequency:
+ A divide by 1, 2, 4, 8, 16, 32 or circuit generates
+ frequencies from 62500000 Hz to 8000000000 Hz.
+ out_altvoltage1_frequency:
+ This channel duplicates the channel 0 frequency
+ out_altvoltage2_frequency:
+ A frequency doubler generates frequencies from
+ 8000000000 Hz to 16000000000 Hz.
+ out_altvoltage3_frequency:
+ A frequency quadrupler generates frequencies from
+ 16000000000 Hz to 32000000000 Hz.
+
+ Note: writes to one of the channels will affect the frequency of
+ all the other channels, since it involves changing the VCO
+ fundamental output frequency.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_i_phase
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_q_phase
What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_i_phase
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_q_phase
KernelVersion: 3.4.0
Contact: linux-iio@vger.kernel.org
Description:
@@ -502,6 +845,17 @@ Description:
specified and unique if the output corresponds to a single
channel.
+What: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw
+Date: May 2012
+KernelVersion: 3.5
+Contact: Johan Hovold <jhovold@gmail.com>
+Description:
+ Set/get output current for channel Y. Units after application
+ of scale and offset are milliamps.
+ For some devices current channels are used to specify
+ current supplied to elements used in taking a measurement
+ of a different type. E.g. LED currents.
+
What: /sys/bus/iio/devices/iio:deviceX/events
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
@@ -539,8 +893,12 @@ What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_rising_en
What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_falling_en
What: /sys/.../iio:deviceX/events/in_voltageY_thresh_rising_en
What: /sys/.../iio:deviceX/events/in_voltageY_thresh_falling_en
+What: /sys/.../iio:deviceX/events/in_voltageY_thresh_either_en
What: /sys/.../iio:deviceX/events/in_tempY_thresh_rising_en
What: /sys/.../iio:deviceX/events/in_tempY_thresh_falling_en
+What: /sys/.../iio:deviceX/events/in_capacitanceY_thresh_rising_en
+What: /sys/.../iio:deviceX/events/in_capacitanceY_thresh_falling_en
+What: /sys/.../iio:deviceX/events/in_pressure_thresh_rising_en
KernelVersion: 2.6.37
Contact: linux-iio@vger.kernel.org
Description:
@@ -553,6 +911,7 @@ Description:
<type>[Y][_name]_<raw|input>_thresh_falling_value may take
different values, but the device can only enable both thresholds
or neither.
+
Note the driver will assume the last p events requested are
to be enabled where p is how many it supports (which may vary
depending on the exact set requested. So if you want to be
@@ -568,6 +927,7 @@ What: /sys/.../iio:deviceX/events/in_accel_y_roc_rising_en
What: /sys/.../iio:deviceX/events/in_accel_y_roc_falling_en
What: /sys/.../iio:deviceX/events/in_accel_z_roc_rising_en
What: /sys/.../iio:deviceX/events/in_accel_z_roc_falling_en
+What: /sys/.../iio:deviceX/events/in_accel_x&y&z_roc_rising_en
What: /sys/.../iio:deviceX/events/in_anglvel_x_roc_rising_en
What: /sys/.../iio:deviceX/events/in_anglvel_x_roc_falling_en
What: /sys/.../iio:deviceX/events/in_anglvel_y_roc_rising_en
@@ -607,6 +967,7 @@ Description:
<type>[Y][_name]_<raw|input>_roc_falling_value may take
different values, but the device can only enable both rate of
change thresholds or neither.
+
Note the driver will assume the last p events requested are
to be enabled where p is however many it supports (which may
vary depending on the exact set requested. So if you want to be
@@ -616,6 +977,33 @@ Description:
a given event type is enabled a future point (and not those for
whatever event was previously enabled).
+What: /sys/.../events/in_capacitanceY_adaptive_thresh_rising_en
+What: /sys/.../events/in_capacitanceY_adaptive_thresh_falling_en
+KernelVersion: 5.13
+Contact: linux-iio@vger.kernel.org
+Description:
+ Adaptive thresholds are similar to normal fixed thresholds
+ but the value is expressed as an offset from a value which
+ provides a low frequency approximation of the channel itself.
+ Thus these detect if a rapid change occurs in the specified
+ direction which crosses tracking value + offset.
+ Tracking value calculation is devices specific.
+
+What: /sys/.../in_capacitanceY_adaptive_thresh_rising_timeout
+What: /sys/.../in_capacitanceY_adaptive_thresh_falling_timeout
+KernelVersion: 5.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ When adaptive thresholds are used, the tracking signal
+ may adjust too slowly to step changes in the raw signal.
+ Thus these specify the time in seconds for which the
+ difference between the slow tracking signal and the raw
+ signal is allowed to remain out-of-range before a reset
+ event occurs in which the tracking signal is made equal
+ to the raw signal, allowing slow tracking to resume and the
+ adaptive threshold event detection to function as expected.
+
+What: /sys/.../events/in_accel_mag_adaptive_rising_value
What: /sys/.../events/in_accel_thresh_rising_value
What: /sys/.../events/in_accel_thresh_falling_value
What: /sys/.../events/in_accel_x_raw_thresh_rising_value
@@ -651,18 +1039,27 @@ What: /sys/.../events/in_voltageY_raw_thresh_falling_value
What: /sys/.../events/in_tempY_raw_thresh_rising_value
What: /sys/.../events/in_tempY_raw_thresh_falling_value
What: /sys/.../events/in_illuminance0_thresh_falling_value
-what: /sys/.../events/in_illuminance0_thresh_rising_value
-what: /sys/.../events/in_proximity0_thresh_falling_value
-what: /sys/.../events/in_proximity0_thresh_rising_value
+What: /sys/.../events/in_illuminance0_thresh_rising_value
+What: /sys/.../events/in_proximity0_thresh_falling_value
+What: /sys/.../events/in_proximity0_thresh_rising_value
+What: /sys/.../events/in_illuminance_thresh_rising_value
+What: /sys/.../events/in_illuminance_thresh_falling_value
+What: /sys/.../events/in_capacitanceY_thresh_rising_value
+What: /sys/.../events/in_capacitanceY_thresh_falling_value
+What: /sys/.../events/in_capacitanceY_thresh_adaptive_rising_value
+What: /sys/.../events/in_capacitanceY_thresh_falling_rising_value
+What: /sys/.../events/in_pressure_thresh_rising_value
KernelVersion: 2.6.37
Contact: linux-iio@vger.kernel.org
Description:
Specifies the value of threshold that the device is comparing
against for the events enabled by
<type>Y[_name]_thresh[_rising|falling]_en.
+
If separate attributes exist for the two directions, but
direction is not specified for this attribute, then a single
threshold value applies to both directions.
+
The raw or input element of the name indicates whether the
value is in raw device units or in processed units (as _raw
and _input do on sysfs direct channel read attributes).
@@ -731,11 +1128,11 @@ What: /sys/.../events/in_tempY_thresh_rising_hysteresis
What: /sys/.../events/in_tempY_thresh_falling_hysteresis
What: /sys/.../events/in_tempY_thresh_either_hysteresis
What: /sys/.../events/in_illuminance0_thresh_falling_hysteresis
-what: /sys/.../events/in_illuminance0_thresh_rising_hysteresis
-what: /sys/.../events/in_illuminance0_thresh_either_hysteresis
-what: /sys/.../events/in_proximity0_thresh_falling_hysteresis
-what: /sys/.../events/in_proximity0_thresh_rising_hysteresis
-what: /sys/.../events/in_proximity0_thresh_either_hysteresis
+What: /sys/.../events/in_illuminance0_thresh_rising_hysteresis
+What: /sys/.../events/in_illuminance0_thresh_either_hysteresis
+What: /sys/.../events/in_proximity0_thresh_falling_hysteresis
+What: /sys/.../events/in_proximity0_thresh_rising_hysteresis
+What: /sys/.../events/in_proximity0_thresh_either_hysteresis
KernelVersion: 3.13
Contact: linux-iio@vger.kernel.org
Description:
@@ -745,14 +1142,16 @@ Description:
If separate attributes exist for the two directions, but
direction is not specified for this attribute, then a single
hysteresis value applies to both directions.
+
For falling events the hysteresis is added to the _value attribute for
this event to get the upper threshold for when the event goes back to
normal, for rising events the hysteresis is subtracted from the _value
attribute. E.g. if in_voltage0_raw_thresh_rising_value is set to 1200
and in_voltage0_raw_thresh_rising_hysteresis is set to 50. The event
will get activated once in_voltage0_raw goes above 1200 and will become
- deactived again once the value falls below 1150.
+ deactivated again once the value falls below 1150.
+What: /sys/.../events/in_accel_roc_rising_value
What: /sys/.../events/in_accel_x_raw_roc_rising_value
What: /sys/.../events/in_accel_x_raw_roc_falling_value
What: /sys/.../events/in_accel_y_raw_roc_rising_value
@@ -791,6 +1190,7 @@ Description:
Specifies the value of rate of change threshold that the
device is comparing against for the events enabled by
<type>[Y][_name]_roc[_rising|falling]_en.
+
If separate attributes exist for the two directions,
but direction is not specified for this attribute,
then a single threshold value applies to both directions.
@@ -798,6 +1198,8 @@ Description:
value is in raw device units or in processed units (as _raw
and _input do on sysfs direct channel read attributes).
+What: /sys/.../events/in_accel_mag_adaptive_rising_period
+What: /sys/.../events/in_accel_roc_rising_period
What: /sys/.../events/in_accel_x_thresh_rising_period
What: /sys/.../events/in_accel_x_thresh_falling_period
What: /sys/.../events/in_accel_x_roc_rising_period
@@ -873,6 +1275,7 @@ What: /sys/.../events/in_activity_jogging_thresh_rising_period
What: /sys/.../events/in_activity_jogging_thresh_falling_period
What: /sys/.../events/in_activity_running_thresh_rising_period
What: /sys/.../events/in_activity_running_thresh_falling_period
+What: /sys/.../events/in_illuminance_thresh_either_period
KernelVersion: 2.6.37
Contact: linux-iio@vger.kernel.org
Description:
@@ -880,6 +1283,26 @@ Description:
met before an event is generated. If direction is not
specified then this period applies to both directions.
+What: /sys/.../events/in_accel_thresh_rising_low_pass_filter_3db
+What: /sys/.../events/in_anglvel_thresh_rising_low_pass_filter_3db
+What: /sys/.../events/in_magn_thresh_rising_low_pass_filter_3db
+KernelVersion: 4.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ If a low pass filter can be applied to the event generation
+ this property gives its 3db frequency in Hz.
+ A value of zero disables the filter.
+
+What: /sys/.../events/in_accel_thresh_rising_high_pass_filter_3db
+What: /sys/.../events/in_anglvel_thresh_rising_high_pass_filter_3db
+What: /sys/.../events/in_magn_thresh_rising_high_pass_filter_3db
+KernelVersion: 4.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ If a high pass filter can be applied to the event generation
+ this property gives its 3db frequency in Hz.
+ A value of zero disables the filter.
+
What: /sys/.../events/in_activity_still_thresh_rising_en
What: /sys/.../events/in_activity_still_thresh_falling_en
What: /sys/.../events/in_activity_walking_thresh_rising_en
@@ -891,7 +1314,7 @@ What: /sys/.../events/in_activity_running_thresh_falling_en
KernelVersion: 3.19
Contact: linux-iio@vger.kernel.org
Description:
- Enables or disables activitity events. Depending on direction
+ Enables or disables activity events. Depending on direction
an event is generated when sensor ENTERS or LEAVES a given state.
What: /sys/.../events/in_activity_still_thresh_rising_value
@@ -946,6 +1369,41 @@ Description:
number or direction is not specified, applies to all channels of
this type.
+What: /sys/.../iio:deviceX/events/in_accel_x_mag_adaptive_rising_en
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_adaptive_rising_en
+What: /sys/.../iio:deviceX/events/in_accel_z_mag_adaptive_rising_en
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ Similar to in_accel_x_thresh[_rising|_falling]_en, but here the
+ magnitude of the channel is compared to the adaptive threshold.
+
+What: /sys/.../iio:deviceX/events/in_accel_mag_referenced_en
+What: /sys/.../iio:deviceX/events/in_accel_mag_referenced_rising_en
+What: /sys/.../iio:deviceX/events/in_accel_mag_referenced_falling_en
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_referenced_en
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_referenced_rising_en
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_referenced_falling_en
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Similar to in_accel_mag[_y][_rising|_falling]_en, but the event
+ value is relative to a reference magnitude. The reference magnitude
+ includes the graviational acceleration.
+
+What: /sys/.../iio:deviceX/events/in_accel_mag_referenced_value
+What: /sys/.../iio:deviceX/events/in_accel_mag_referenced_rising_value
+What: /sys/.../iio:deviceX/events/in_accel_mag_referenced_falling_value
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_referenced_value
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_referenced_rising_value
+What: /sys/.../iio:deviceX/events/in_accel_y_mag_referenced_falling_value
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ The value to which the reference magnitude of the channel is
+ compared. If the axis is not specified, it applies to all channels
+ of this type.
+
What: /sys/.../events/in_steps_change_en
KernelVersion: 4.0
Contact: linux-iio@vger.kernel.org
@@ -972,74 +1430,82 @@ Description:
The name of the trigger source being used, as per string given
in /sys/class/iio/triggerY/name.
-What: /sys/bus/iio/devices/iio:deviceX/buffer/length
-KernelVersion: 2.6.35
+What: /sys/bus/iio/devices/iio:deviceX/bufferY/length
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
Number of scans contained by the buffer.
-What: /sys/bus/iio/devices/iio:deviceX/buffer/bytes_per_datum
-KernelVersion: 2.6.37
-Contact: linux-iio@vger.kernel.org
-Description:
- Bytes per scan. Due to alignment fun, the scan may be larger
- than implied directly by the scan_element parameters.
-
-What: /sys/bus/iio/devices/iio:deviceX/buffer/enable
-KernelVersion: 2.6.35
+What: /sys/bus/iio/devices/iio:deviceX/bufferY/enable
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
Actually start the buffer capture up. Will start trigger
if first device and appropriate.
-What: /sys/bus/iio/devices/iio:deviceX/scan_elements
-KernelVersion: 2.6.37
+ Note that it might be impossible to configure other attributes,
+ (e.g.: events, scale, sampling rate) if they impact the currently
+ active buffer capture session.
+
+What: /sys/bus/iio/devices/iio:deviceX/bufferY
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
Directory containing interfaces for elements that will be
captured for a single triggered sample set in the buffer.
-What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en
-What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en
-What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_en
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_en
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_en
-What: /sys/.../iio:deviceX/scan_elements/in_magn_x_en
-What: /sys/.../iio:deviceX/scan_elements/in_magn_y_en
-What: /sys/.../iio:deviceX/scan_elements/in_magn_z_en
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_en
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_en
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_tilt_comp_en
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_tilt_comp_en
-What: /sys/.../iio:deviceX/scan_elements/in_timestamp_en
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_en
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY_en
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY-voltageZ_en
-What: /sys/.../iio:deviceX/scan_elements/in_incli_x_en
-What: /sys/.../iio:deviceX/scan_elements/in_incli_y_en
-What: /sys/.../iio:deviceX/scan_elements/in_pressureY_en
-What: /sys/.../iio:deviceX/scan_elements/in_pressure_en
-What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_en
-What: /sys/.../iio:deviceX/scan_elements/in_proximity_en
-KernelVersion: 2.6.37
+ Since kernel 5.11 the scan_elements attributes are merged into
+ the bufferY directory, to be configurable per buffer.
+
+What: /sys/.../iio:deviceX/bufferY/in_accel_x_en
+What: /sys/.../iio:deviceX/bufferY/in_accel_y_en
+What: /sys/.../iio:deviceX/bufferY/in_accel_z_en
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_x_en
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_y_en
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_z_en
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_x_en
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_y_en
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_z_en
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_x_en
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_y_en
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_z_en
+What: /sys/.../iio:deviceX/bufferY/in_magn_x_en
+What: /sys/.../iio:deviceX/bufferY/in_magn_y_en
+What: /sys/.../iio:deviceX/bufferY/in_magn_z_en
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_en
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_en
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_tilt_comp_en
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_tilt_comp_en
+What: /sys/.../iio:deviceX/bufferY/in_timestamp_en
+What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_en
+What: /sys/.../iio:deviceX/bufferY/in_voltageY_en
+What: /sys/.../iio:deviceX/bufferY/in_voltageY-voltageZ_en
+What: /sys/.../iio:deviceX/bufferY/in_incli_x_en
+What: /sys/.../iio:deviceX/bufferY/in_incli_y_en
+What: /sys/.../iio:deviceX/bufferY/in_pressureY_en
+What: /sys/.../iio:deviceX/bufferY/in_pressure_en
+What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_en
+What: /sys/.../iio:deviceX/bufferY/in_proximity_en
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
Scan element control for triggered data capture.
-What: /sys/.../iio:deviceX/scan_elements/in_accel_type
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_type
-What: /sys/.../iio:deviceX/scan_elements/in_magn_type
-What: /sys/.../iio:deviceX/scan_elements/in_incli_type
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY_type
-What: /sys/.../iio:deviceX/scan_elements/in_voltage_type
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_type
-What: /sys/.../iio:deviceX/scan_elements/in_timestamp_type
-What: /sys/.../iio:deviceX/scan_elements/in_pressureY_type
-What: /sys/.../iio:deviceX/scan_elements/in_pressure_type
-What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_type
-What: /sys/.../iio:deviceX/scan_elements/in_proximity_type
-KernelVersion: 2.6.37
+What: /sys/.../iio:deviceX/bufferY/in_accel_type
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_type
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_type
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_type
+What: /sys/.../iio:deviceX/bufferY/in_magn_type
+What: /sys/.../iio:deviceX/bufferY/in_incli_type
+What: /sys/.../iio:deviceX/bufferY/in_voltageY_type
+What: /sys/.../iio:deviceX/bufferY/in_voltage_type
+What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_type
+What: /sys/.../iio:deviceX/bufferY/in_timestamp_type
+What: /sys/.../iio:deviceX/bufferY/in_pressureY_type
+What: /sys/.../iio:deviceX/bufferY/in_pressure_type
+What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_type
+What: /sys/.../iio:deviceX/bufferY/in_proximity_type
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
Description of the scan element data storage within the buffer
@@ -1069,29 +1535,35 @@ Description:
If the type parameter can take one of a small set of values,
this attribute lists them.
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY_index
-What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_index
-What: /sys/.../iio:deviceX/scan_elements/in_accel_x_index
-What: /sys/.../iio:deviceX/scan_elements/in_accel_y_index
-What: /sys/.../iio:deviceX/scan_elements/in_accel_z_index
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_index
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_index
-What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_index
-What: /sys/.../iio:deviceX/scan_elements/in_magn_x_index
-What: /sys/.../iio:deviceX/scan_elements/in_magn_y_index
-What: /sys/.../iio:deviceX/scan_elements/in_magn_z_index
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_index
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_index
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_tilt_comp_index
-What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_tilt_comp_index
-What: /sys/.../iio:deviceX/scan_elements/in_incli_x_index
-What: /sys/.../iio:deviceX/scan_elements/in_incli_y_index
-What: /sys/.../iio:deviceX/scan_elements/in_timestamp_index
-What: /sys/.../iio:deviceX/scan_elements/in_pressureY_index
-What: /sys/.../iio:deviceX/scan_elements/in_pressure_index
-What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_index
-What: /sys/.../iio:deviceX/scan_elements/in_proximity_index
-KernelVersion: 2.6.37
+What: /sys/.../iio:deviceX/bufferY/in_voltageY_index
+What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_index
+What: /sys/.../iio:deviceX/bufferY/in_accel_x_index
+What: /sys/.../iio:deviceX/bufferY/in_accel_y_index
+What: /sys/.../iio:deviceX/bufferY/in_accel_z_index
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_x_index
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_y_index
+What: /sys/.../iio:deviceX/bufferY/in_deltaangl_z_index
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_x_index
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_y_index
+What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_z_index
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_x_index
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_y_index
+What: /sys/.../iio:deviceX/bufferY/in_anglvel_z_index
+What: /sys/.../iio:deviceX/bufferY/in_magn_x_index
+What: /sys/.../iio:deviceX/bufferY/in_magn_y_index
+What: /sys/.../iio:deviceX/bufferY/in_magn_z_index
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_index
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_index
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_tilt_comp_index
+What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_tilt_comp_index
+What: /sys/.../iio:deviceX/bufferY/in_incli_x_index
+What: /sys/.../iio:deviceX/bufferY/in_incli_y_index
+What: /sys/.../iio:deviceX/bufferY/in_timestamp_index
+What: /sys/.../iio:deviceX/bufferY/in_pressureY_index
+What: /sys/.../iio:deviceX/bufferY/in_pressure_index
+What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_index
+What: /sys/.../iio:deviceX/bufferY/in_proximity_index
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
A single positive integer specifying the position of this
@@ -1119,7 +1591,7 @@ Description:
This attribute is used to read the amount of quadrature error
present in the device at a given time.
-What: /sys/.../iio:deviceX/in_accelX_power_mode
+What: /sys/.../iio:deviceX/in_accelY_power_mode
KernelVersion: 3.11
Contact: linux-iio@vger.kernel.org
Description:
@@ -1131,6 +1603,9 @@ Description:
What: /sys/.../iio:deviceX/in_energy_input
What: /sys/.../iio:deviceX/in_energy_raw
+What: /sys/.../iio:deviceX/in_energyY_active_raw
+What: /sys/.../iio:deviceX/in_energyY_reactive_raw
+What: /sys/.../iio:deviceX/in_energyY_apparent_raw
KernelVersion: 4.0
Contact: linux-iio@vger.kernel.org
Description:
@@ -1143,9 +1618,9 @@ What: /sys/.../iio:deviceX/in_distance_raw
KernelVersion: 4.0
Contact: linux-iio@vger.kernel.org
Description:
- This attribute is used to read the distance covered by the user
- since the last reboot while activated. Units after application
- of scale are meters.
+ This attribute is used to read the measured distance to an object
+ or the distance covered by the user since the last reboot while
+ activated. Units after application of scale are meters.
What: /sys/bus/iio/devices/iio:deviceX/store_eeprom
KernelVersion: 3.4.0
@@ -1162,13 +1637,13 @@ KernelVersion: 3.4
Contact: linux-iio@vger.kernel.org
Description:
Proximity measurement indicating that some
- object is near the sensor, usually be observing
+ object is near the sensor, usually by observing
reflectivity of infrared or ultrasound emitted.
+
Often these sensors are unit less and as such conversion
- to SI units is not possible. Where it is, the units should
- be meters. If such a conversion is not possible, the reported
- values should behave in the same way as a distance, i.e. lower
- values indicate something is closer to the sensor.
+ to SI units is not possible. Higher proximity measurements
+ indicate closer objects, and vice versa. Units after
+ application of scale and offset are meters.
What: /sys/.../iio:deviceX/in_illuminance_input
What: /sys/.../iio:deviceX/in_illuminance_raw
@@ -1186,13 +1661,35 @@ Description:
What: /sys/.../iio:deviceX/in_intensityY_raw
What: /sys/.../iio:deviceX/in_intensityY_ir_raw
What: /sys/.../iio:deviceX/in_intensityY_both_raw
+What: /sys/.../iio:deviceX/in_intensityY_uv_raw
+What: /sys/.../iio:deviceX/in_intensityY_uva_raw
+What: /sys/.../iio:deviceX/in_intensityY_uvb_raw
+What: /sys/.../iio:deviceX/in_intensityY_duv_raw
+What: /sys/.../iio:deviceX/in_intensity_red_raw
+What: /sys/.../iio:deviceX/in_intensity_green_raw
+What: /sys/.../iio:deviceX/in_intensity_blue_raw
+What: /sys/.../iio:deviceX/in_intensity_clear_raw
KernelVersion: 3.4
Contact: linux-iio@vger.kernel.org
Description:
Unit-less light intensity. Modifiers both and ir indicate
- that measurements contains visible and infrared light
- components or just infrared light, respectively.
+ that measurements contain visible and infrared light
+ components or just infrared light, respectively. Modifier
+ uv indicates that measurements contain ultraviolet light
+ components. Modifiers uva, uvb and duv indicate that
+ measurements contain A, B or deep (C) ultraviolet light
+ components respectively.
+What: /sys/.../iio:deviceX/in_uvindex_input
+KernelVersion: 4.6
+Contact: linux-iio@vger.kernel.org
+Description:
+ UV light intensity index measuring the human skin's response to
+ different wavelength of sunlight weighted according to the
+ standardised CIE Erythemal Action Spectrum. UV index values range
+ from 0 (low) to >=11 (extreme).
+
+What: /sys/.../iio:deviceX/in_intensity_integration_time
What: /sys/.../iio:deviceX/in_intensity_red_integration_time
What: /sys/.../iio:deviceX/in_intensity_green_integration_time
What: /sys/.../iio:deviceX/in_intensity_blue_integration_time
@@ -1202,7 +1699,8 @@ KernelVersion: 3.12
Contact: linux-iio@vger.kernel.org
Description:
This attribute is used to get/set the integration time in
- seconds.
+ seconds. If shared across all channels of a given type,
+ <type>_integration_time is used.
What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_integration_time
KernelVersion: 4.0
@@ -1229,14 +1727,30 @@ Description:
Raw value of rotation from true/magnetic north measured with
or without compensation from tilt sensors.
-What: /sys/bus/iio/devices/iio:deviceX/in_currentX_raw
-KernelVersion: 3.18
+What: /sys/bus/iio/devices/iio:deviceX/in_currentY_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_raw
+KernelVersion: 3.17
Contact: linux-iio@vger.kernel.org
Description:
- Raw current measurement from channel X. Units are in milliamps
+ Raw current measurement from channel Y. Units are in milliamps
after application of scale and offset. If no offset or scale is
present, output should be considered as processed with the
- unit in milliamps.
+ unit in milliamps. In special cases where the channel does not
+ correspond to externally available input one of the named
+ versions may be used.
+
+ Channels with 'i' and 'q' modifiers always exist in pairs and both
+ channels refer to the same signal. The 'i' channel contains the in-phase
+ component of the signal while the 'q' channel contains the quadrature
+ component.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altcurrentY_rms_raw
+KernelVersion: 6.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled no bias removal etc.) Root Mean Square (RMS) current
+ measurement from channel Y. Units after application of scale and
+ offset are milliamps.
What: /sys/.../iio:deviceX/in_energy_en
What: /sys/.../iio:deviceX/in_distance_en
@@ -1281,21 +1795,34 @@ Description:
Specifies number of seconds in which we compute the steps
that occur in order to decide if the consumer is making steps.
-What: /sys/bus/iio/devices/iio:deviceX/buffer/watermark
-KernelVersion: 4.2
+What: /sys/bus/iio/devices/iio:deviceX/bufferY/watermark
+KernelVersion: 5.11
Contact: linux-iio@vger.kernel.org
Description:
A single positive integer specifying the maximum number of scan
elements to wait for.
+
Poll will block until the watermark is reached.
+
Blocking read will wait until the minimum between the requested
read amount or the low water mark is available.
+
Non-blocking read will retrieve the available samples from the
buffer even if there are less samples then watermark level. This
allows the application to block on poll with a timeout and read
the available samples after the timeout expires and thus have a
maximum delay guarantee.
+What: /sys/bus/iio/devices/iio:deviceX/bufferY/data_available
+KernelVersion: 5.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ A read-only value indicating the bytes of data available in the
+ buffer. In the case of an output buffer, this indicates the
+ amount of empty space available to write data to. In the case of
+ an input buffer, this indicates the amount of data available for
+ reading.
+
What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_enabled
KernelVersion: 4.2
Contact: linux-iio@vger.kernel.org
@@ -1308,16 +1835,29 @@ Description:
device settings allows it (e.g. if a trigger is set that samples
data differently that the hardware fifo does then hardware fifo
will not enabled).
+
If the hardware fifo is enabled and the level of the hardware
fifo reaches the hardware fifo watermark level the device will
flush its hardware fifo to the device buffer. Doing a non
blocking read on the device when no samples are present in the
device buffer will also force a flush.
+
When the hardware fifo is enabled there is no need to use a
trigger to use buffer mode since the watermark settings
guarantees that the hardware fifo is flushed to the device
buffer.
+What: /sys/bus/iio/devices/iio:device*/buffer/hwfifo_timeout
+KernelVersion: 4.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ A read/write property to provide capability to delay reporting of
+ samples till a timeout is reached. This allows host processors to
+ sleep, while the sensor is storing samples in its internal fifo.
+ The maximum timeout in seconds can be specified by setting
+ hwfifo_timeout.The current delay can be read by reading
+ hwfifo_timeout. A value of 0 means that there is no timeout.
+
What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_watermark
KernelVersion: 4.2
Contact: linux-iio@vger.kernel.org
@@ -1339,6 +1879,7 @@ Description:
A single positive integer specifying the minimum watermark level
for the hardware fifo of this device. If the device does not
have a hardware fifo this entry is not present.
+
If the user sets buffer/watermark to a value less than this one,
then the hardware watermark will remain unset.
@@ -1349,6 +1890,7 @@ Description:
A single positive integer specifying the maximum watermark level
for the hardware fifo of this device. If the device does not
have a hardware fifo this entry is not present.
+
If the user sets buffer/watermark to a value greater than this
one, then the hardware watermark will be capped at this value.
@@ -1360,7 +1902,559 @@ Description:
levels for the hardware fifo. This entry is optional and if it
is not present it means that all the values between
hwfifo_watermark_min and hwfifo_watermark_max are supported.
+
If the user sets buffer/watermark to a value greater than
hwfifo_watermak_min but not equal to any of the values in this
list, the driver will chose an appropriate value for the
hardware fifo watermark level.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_calibemissivity
+What: /sys/bus/iio/devices/iio:deviceX/in_tempY_calibemissivity
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_calibemissivity
+What: /sys/bus/iio/devices/iio:deviceX/in_tempY_object_calibemissivity
+KernelVersion: 4.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ The emissivity ratio of the surface in the field of view of the
+ contactless temperature sensor. Emissivity varies from 0 to 1,
+ with 1 being the emissivity of a black body.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_oversampling_ratio
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_oversampling_ratio
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_oversampling_ratio
+KernelVersion: 4.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Hardware applied number of measurements for acquiring one
+ data point. The HW will do <type>[_name]_oversampling_ratio
+ measurements and return the average value as output data. Each
+ value resulted from <type>[_name]_oversampling_ratio measurements
+ is considered as one sample for <type>[_name]_sampling_frequency.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_co2_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_ethanol_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_ethanol_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_h2_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_h2_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_o2_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_o2_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_voc_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_voc_raw
+KernelVersion: 4.3
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled no offset etc.) reading of a substance. Units
+ after application of scale and offset are percents.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_resistanceY_raw
+What: /sys/bus/iio/devices/iio:deviceX/out_resistance_raw
+What: /sys/bus/iio/devices/iio:deviceX/out_resistanceY_raw
+KernelVersion: 4.3
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled no offset etc.) resistance reading.
+ Units after application of scale and offset are ohms.
+
+What: /sys/bus/iio/devices/iio:deviceX/heater_enable
+KernelVersion: 4.1.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ '1' (enable) or '0' (disable) specifying the enable
+ of heater function. Same reading values apply.
+
+ This ABI is especially applicable for humidity sensors
+ to heatup the device and get rid of any condensation
+ in some humidity environment
+
+What: /sys/bus/iio/devices/iio:deviceX/in_ph_raw
+KernelVersion: 4.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled no offset etc.) pH reading of a substance as a negative
+ base-10 logarithm of hydrodium ions in a litre of water.
+
+What: /sys/bus/iio/devices/iio:deviceX/mount_matrix
+What: /sys/bus/iio/devices/iio:deviceX/in_mount_matrix
+What: /sys/bus/iio/devices/iio:deviceX/out_mount_matrix
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_mount_matrix
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_mount_matrix
+KernelVersion: 4.6
+Contact: linux-iio@vger.kernel.org
+Description:
+ Mounting matrix for IIO sensors. This is a rotation matrix which
+ informs userspace about sensor chip's placement relative to the
+ main hardware it is mounted on.
+
+ Main hardware placement is defined according to the local
+ reference frame related to the physical quantity the sensor
+ measures.
+
+ Given that the rotation matrix is defined in a board specific
+ way (platform data and / or device-tree), the main hardware
+ reference frame definition is left to the implementor's choice
+ (see below for a magnetometer example).
+
+ Applications should apply this rotation matrix to samples so
+ that when main hardware reference frame is aligned onto local
+ reference frame, then sensor chip reference frame is also
+ perfectly aligned with it.
+
+ Matrix is a 3x3 unitary matrix and typically looks like
+ [0, 1, 0; 1, 0, 0; 0, 0, -1]. Identity matrix
+ [1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and main hardware
+ are perfectly aligned with each other.
+
+ For example, a mounting matrix for a magnetometer sensor informs
+ userspace about sensor chip's ORIENTATION relative to the main
+ hardware.
+
+ More specifically, main hardware orientation is defined with
+ respect to the LOCAL EARTH GEOMAGNETIC REFERENCE FRAME where :
+
+ * Y is in the ground plane and positive towards magnetic North ;
+ * X is in the ground plane, perpendicular to the North axis and
+ positive towards the East ;
+ * Z is perpendicular to the ground plane and positive upwards.
+
+ An implementor might consider that for a hand-held device, a
+ 'natural' orientation would be 'front facing camera at the top'.
+ The main hardware reference frame could then be described as :
+
+ * Y is in the plane of the screen and is positive towards the
+ top of the screen ;
+ * X is in the plane of the screen, perpendicular to Y axis, and
+ positive towards the right hand side of the screen ;
+ * Z is perpendicular to the screen plane and positive out of the
+ screen.
+
+ Another example for a quadrotor UAV might be :
+
+ * Y is in the plane of the propellers and positive towards the
+ front-view camera;
+ * X is in the plane of the propellers, perpendicular to Y axis,
+ and positive towards the starboard side of the UAV ;
+ * Z is perpendicular to propellers plane and positive upwards.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_electricalconductivity_raw
+KernelVersion: 4.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled no offset etc.) electric conductivity reading.
+ Units after application of scale and offset are siemens per
+ meter.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_countY_raw
+KernelVersion: 4.10
+Contact: linux-iio@vger.kernel.org
+Description:
+ This interface is deprecated; please use the Counter subsystem.
+
+ Raw counter device counts from channel Y. For quadrature
+ counters, multiplication by an available [Y]_scale results in
+ the counts of a single quadrature signal phase from channel Y.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_indexY_raw
+KernelVersion: 4.10
+Contact: linux-iio@vger.kernel.org
+Description:
+ This interface is deprecated; please use the Counter subsystem.
+
+ Raw counter device index value from channel Y. This attribute
+ provides an absolute positional reference (e.g. a pulse once per
+ revolution) which may be used to home positional systems as
+ required.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count_count_direction_available
+KernelVersion: 4.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ This interface is deprecated; please use the Counter subsystem.
+
+ A list of possible counting directions which are:
+
+ - "up" : counter device is increasing.
+ - "down": counter device is decreasing.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_direction
+KernelVersion: 4.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ This interface is deprecated; please use the Counter subsystem.
+
+ Raw counter device counters direction for channel Y.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_label
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_label
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Optional symbolic label to a device channel.
+ If a label is defined for this channel add that to the channel
+ specific attributes. This is useful for userspace to be able to
+ better identify an individual channel.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_phaseY_raw
+KernelVersion: 4.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled) phase difference reading from channel Y.
+ Units after application of scale and offset are radians.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm2p5_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm2p5_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm4_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm4_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm10_input
+What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm10_input
+KernelVersion: 4.22
+Contact: linux-iio@vger.kernel.org
+Description:
+ Mass concentration reading of particulate matter in ug / m3.
+ pmX consists of particles with aerodynamic diameter less or
+ equal to X micrometers.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_illuminance_period_available
+Date: November 2019
+KernelVersion: 5.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of valid periods (in seconds) for which the light intensity
+ must be above the threshold level before interrupt is asserted.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency
+KernelVersion: 5.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ Center frequency in Hz for a notch filter. Used i.e. for line
+ noise suppression.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_thermocouple_type
+KernelVersion: 5.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ One of the following thermocouple types: B, E, J, K, N, R, S, T.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_calibambient
+What: /sys/bus/iio/devices/iio:deviceX/in_tempY_object_calibambient
+KernelVersion: 5.10
+Contact: linux-iio@vger.kernel.org
+Description:
+ Calibrated ambient temperature for object temperature
+ calculation in milli degrees Celsius.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_y_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_z_raw
+KernelVersion: 5.10
+Contact: linux-iio@vger.kernel.org
+Description:
+ Unscaled light intensity according to CIE 1931/DIN 5033 color space.
+ Units after application of scale are nano nanowatts per square meter.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_anglY_label
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Optional symbolic label for channel Y.
+ For Intel hid hinge sensor, the label values are:
+ hinge, keyboard, screen. It means the three channels
+ each correspond respectively to hinge angle, keyboard angle,
+ and screen angle.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_hysteresis_relative
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_hysteresis_relative
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specify the percent for light sensor relative to the channel
+ absolute value that a data field should change before an event
+ is generated. Units are a percentage of the prior reading.
+
+What: /sys/bus/iio/devices/iio:deviceX/calibration_auto_enable
+Date: June 2020
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Some sensors have the ability to apply auto calibration at
+ runtime. For example, it may be necessary to compensate for
+ contaminant build-up in a measurement chamber or optical
+ element deterioration that would otherwise lead to sensor drift.
+
+ Writing 1 or 0 to this attribute will respectively activate or
+ deactivate this auto calibration function.
+
+ Upon reading, the current status is returned.
+
+What: /sys/bus/iio/devices/iio:deviceX/calibration_forced_value
+Date: June 2020
+KernelVersion: 5.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Some sensors have the ability to apply a manual calibration using
+ a known measurement value, perhaps obtained from an external
+ reference device.
+
+ Writing a value to this function will force such a calibration
+ change. For the scd30 the value should be from the range
+ [400 1 2000].
+
+ Note for the scd30 that a valid value may only be obtained once
+ it is has been written. Until then any read back of this value
+ should be ignored. As for the scd4x an error will be returned
+ immediately if the manual calibration has failed.
+
+What: /sys/bus/iio/devices/iio:deviceX/calibration_forced_value_available
+KernelVersion: 5.15
+Contact: linux-iio@vger.kernel.org
+Description:
+ Available range for the forced calibration value, expressed as:
+
+ - a range specified as "[min step max]"
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sampling_frequency
+What: /sys/bus/iio/devices/iio:deviceX/in_powerY_sampling_frequency
+What: /sys/bus/iio/devices/iio:deviceX/in_currentY_sampling_frequency
+KernelVersion: 5.20
+Contact: linux-iio@vger.kernel.org
+Description:
+ Some devices have separate controls of sampling frequency for
+ individual channels. If multiple channels are enabled in a scan,
+ then the sampling_frequency of the scan may be computed from the
+ per channel sampling frequencies.
+
+What: /sys/.../events/in_accel_gesture_singletap_en
+What: /sys/.../events/in_accel_gesture_doubletap_en
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Device generates an event on a single or double tap.
+
+What: /sys/.../events/in_accel_gesture_singletap_value
+What: /sys/.../events/in_accel_gesture_doubletap_value
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies the threshold value that the device is comparing
+ against to generate the tap gesture event. The lower
+ threshold value increases the sensitivity of tap detection.
+ Units and the exact meaning of value are device-specific.
+
+What: /sys/.../events/in_accel_gesture_tap_value_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Lists all available threshold values which can be used to
+ modify the sensitivity of the tap detection.
+
+What: /sys/.../events/in_accel_gesture_singletap_reset_timeout
+What: /sys/.../events/in_accel_gesture_doubletap_reset_timeout
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies the timeout value in seconds for the tap detector
+ to not to look for another tap event after the event as
+ occurred. Basically the minimum quiet time between the two
+ single-tap's or two double-tap's.
+
+What: /sys/.../events/in_accel_gesture_tap_reset_timeout_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Lists all available tap reset timeout values. Units in seconds.
+
+What: /sys/.../events/in_accel_gesture_doubletap_tap2_min_delay
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies the minimum quiet time in seconds between the two
+ taps of a double tap.
+
+What: /sys/.../events/in_accel_gesture_doubletap_tap2_min_delay_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Lists all available delay values between two taps in the double
+ tap. Units in seconds.
+
+What: /sys/.../events/in_accel_gesture_tap_maxtomin_time
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies the maximum time difference allowed between upper
+ and lower peak of tap to consider it as the valid tap event.
+ Units in seconds.
+
+What: /sys/.../events/in_accel_gesture_tap_maxtomin_time_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Lists all available time values between upper peak to lower
+ peak. Units in seconds.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_rot_yaw_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_rot_pitch_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_rot_roll_raw
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled) euler angles readings. Units after
+ application of scale are deg.
+
+What: /sys/bus/iio/devices/iio:deviceX/serialnumber
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ An example format is 16-bytes, 2-digits-per-byte, HEX-string
+ representing the sensor unique ID number.
+
+What: /sys/bus/iio/devices/iio:deviceX/filter_type_available
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_type_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns a list with the possible filter modes. Options
+ for the attribute:
+
+ * "none" - Filter is disabled/bypassed.
+ * "sinc1" - The digital sinc1 filter. Fast 1st
+ conversion time. Poor noise performance.
+ * "sinc3" - The digital sinc3 filter. Moderate 1st
+ conversion time. Good noise performance.
+ * "sinc3+pf1" - Sinc3 + device specific Post Filter 1.
+ * "sinc3+pf2" - Sinc3 + device specific Post Filter 2.
+ * "sinc3+pf3" - Sinc3 + device specific Post Filter 3.
+ * "sinc3+pf4" - Sinc3 + device specific Post Filter 4.
+ * "sinc3+rej60" - Sinc3 + 60Hz rejection.
+ * "sinc3+sinc1" - Sinc3 + averaging by 8. Low 1st conversion
+ time.
+ * "sinc4" - Sinc 4. Excellent noise performance. Long
+ 1st conversion time.
+ * "sinc4+lp" - Sinc4 + Low Pass Filter.
+ * "sinc4+sinc1" - Sinc4 + averaging by 8. Low 1st conversion
+ time.
+ * "sinc4+rej60" - Sinc4 + 60Hz rejection.
+ * "sinc5" - The digital sinc5 filter. Excellent noise
+ performance
+ * "sinc5+avg" - Sinc5 + averaging by 4.
+ * "sinc5+pf1" - Sinc5 + device specific Post Filter 1.
+ * "sinc5+sinc1" - Sinc5 + Sinc1.
+ * "sinc5+sinc1+pf1" - Sinc5 + Sinc1 + device specific Post Filter 1.
+ * "sinc5+sinc1+pf2" - Sinc5 + Sinc1 + device specific Post Filter 2.
+ * "sinc5+sinc1+pf3" - Sinc5 + Sinc1 + device specific Post Filter 3.
+ * "sinc5+sinc1+pf4" - Sinc5 + Sinc1 + device specific Post Filter 4.
+ * "wideband" - filter with wideband low ripple passband
+ and sharp transition band.
+
+What: /sys/bus/iio/devices/iio:deviceX/filter_type
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_filter_type
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies which filter type apply to the channel. The possible
+ values are given by the filter_type_available attribute.
+
+What: /sys/.../events/in_proximity_thresh_either_runningperiod
+KernelVersion: 6.6
+Contact: linux-iio@vger.kernel.org
+Description:
+ A running period of time (in seconds) for which
+ in_proximity_thresh_either_runningcount amount of conditions
+ must occur before an event is generated. If direction is not
+ specified then this period applies to both directions.
+
+What: /sys/.../events/in_proximity_thresh_either_runningcount
+KernelVersion: 6.6
+Contact: linux-iio@vger.kernel.org
+Description:
+ Number of conditions that must occur, during a running
+ period, before an event is generated.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_colortemp_raw
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Represents light color temperature, which measures light color
+ temperature in Kelvin.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_chromaticity_x_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_chromaticity_y_raw
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ The x and y light color coordinate on the CIE 1931 chromaticity
+ diagram.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_mag_either_label
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_mag_rising_label
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_thresh_falling_label
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_thresh_rising_label
+What: /sys/bus/iio/devices/iio:deviceX/events/in_anglvelY_mag_rising_label
+What: /sys/bus/iio/devices/iio:deviceX/events/in_anglY_thresh_rising_label
+What: /sys/bus/iio/devices/iio:deviceX/events/in_phaseY_mag_rising_label
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Optional symbolic label to a device channel event.
+ If a label is defined for this event add that to the event
+ specific attributes. This is useful for userspace to be able to
+ better identify an individual event.
+
+What: /sys/.../events/in_accel_gesture_tap_wait_timeout
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Enable tap gesture confirmation with timeout.
+
+What: /sys/.../events/in_accel_gesture_tap_wait_dur
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Timeout value in seconds for tap gesture confirmation.
+
+What: /sys/.../events/in_accel_gesture_tap_wait_dur_available
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of available timeout value for tap gesture confirmation.
+
+What: /sys/.../iio:deviceX/in_shunt_resistor
+What: /sys/.../iio:deviceX/in_current_shunt_resistor
+What: /sys/.../iio:deviceX/in_power_shunt_resistor
+KernelVersion: 6.10
+Contact: linux-iio@vger.kernel.org
+Description:
+ The value of current sense resistor in Ohms.
+
+What: /sys/.../iio:deviceX/in_attention_input
+KernelVersion: 6.13
+Contact: linux-iio@vger.kernel.org
+Description:
+ Value representing the user's attention to the system expressed
+ in units as percentage. This usually means if the user is
+ looking at the screen or not.
+
+What: /sys/.../events/in_accel_value_available
+KernelVersion: 6.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of available threshold values for acceleration event
+ generation. Applies to all event types on in_accel channels.
+ Units after application of scale and offset are m/s^2.
+ Expressed as:
+
+ - a range specified as "[min step max]"
+
+What: /sys/.../events/in_accel_period_available
+KernelVersion: 6.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of available periods for accelerometer event detection in
+ seconds, expressed as:
+
+ - a range specified as "[min step max]"
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-accel-adxl372 b/Documentation/ABI/testing/sysfs-bus-iio-accel-adxl372
new file mode 100644
index 000000000000..47e34f865ca1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-accel-adxl372
@@ -0,0 +1,7 @@
+What: /sys/bus/iio/devices/triggerX/name = "adxl372-devX-peak"
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ The adxl372 accelerometer kernel module provides an additional trigger,
+ which sets the device in a mode in which it will record only the peak acceleration
+ sensed over the set period of time in the events sysfs.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-ad9739a b/Documentation/ABI/testing/sysfs-bus-iio-ad9739a
new file mode 100644
index 000000000000..ed59299e6f8d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-ad9739a
@@ -0,0 +1,19 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_operating_mode
+KernelVersion: 6.9
+Contact: linux-iio@vger.kernel.org
+Description:
+ DAC operating mode. One of the following modes can be selected:
+
+ * normal: This is DAC normal mode.
+ * mixed-mode: In this mode the output is effectively chopped at
+ the DAC sample rate. This has the effect of
+ reducing the power of the fundamental signal while
+ increasing the power of the images centered around
+ the DAC sample rate, thus improving the output
+ power of these images.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_operating_mode_available
+KernelVersion: 6.9
+Contact: linux-iio@vger.kernel.org
+Description:
+ Available operating modes.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta
new file mode 100644
index 000000000000..a5a8a579f4f3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta
@@ -0,0 +1,23 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sys_calibration
+KernelVersion: 5.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute, if available, initiates the system calibration procedure. This is done on a
+ single channel at a time. Write '1' to start the calibration.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sys_calibration_mode_available
+KernelVersion: 5.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute, if available, returns a list with the possible calibration modes.
+ There are two available options:
+ "zero_scale" - calibrate to zero scale
+ "full_scale" - calibrate to full scale
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sys_calibration_mode
+KernelVersion: 5.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute, if available, sets up the calibration mode used in the system calibration
+ procedure. Reading returns the current calibration mode.
+ Writing sets the system calibration mode.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130 b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
new file mode 100644
index 000000000000..d3fad27421d6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
@@ -0,0 +1,20 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
+KernelVersion: 6.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns a list with the possible filter modes.
+
+ This ABI is only kept for backwards compatibility and the values
+ returned are identical to filter_type_available attribute
+ documented in Documentation/ABI/testing/sysfs-bus-iio. Please,
+ use filter_type_available like ABI to provide filter options for
+ new drivers.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_filter_mode
+KernelVersion: 6.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ This ABI is only kept for backwards compatibility and the values
+ returned are identical to in_voltageY-voltageZ_filter_type
+ attribute documented in Documentation/ABI/testing/sysfs-bus-iio.
+ Please, use in_voltageY-voltageZ_filter_type for new drivers.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
new file mode 100644
index 000000000000..28be1cabf112
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
@@ -0,0 +1,27 @@
+What: /sys/bus/iio/devices/iio:deviceX/ac_excitation_en
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute, if available, is used to enable the AC
+ excitation mode found on some converters. In ac excitation mode,
+ the polarity of the excitation voltage is reversed on
+ alternate cycles, to eliminate DC errors.
+
+What: /sys/bus/iio/devices/iio:deviceX/bridge_switch_en
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute, if available, is used to close or open the
+ bridge power down switch found on some converters.
+ In bridge applications, such as strain gauges and load cells,
+ the bridge itself consumes the majority of the current in the
+ system. To minimize the current consumption of the system,
+ the bridge can be disconnected (when it is not being used
+ using the bridge_switch_en attribute.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Measure voltage from AIN2 pin connected to AIN(+)
+ and AIN(-) shorted.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7280a b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7280a
new file mode 100644
index 000000000000..83b7efe6aa07
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7280a
@@ -0,0 +1,13 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_balance_switch_en
+KernelVersion: 5.14
+Contact: linux-iio@vger.kernel.org
+Description:
+ Used to enable an output for balancing cells for time
+ controlled via in_voltage_Y-voltageZ_balance_switch_timer.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_balance_switch_timer
+KernelVersion: 5.14
+Contact: linux-iio@vger.kernel.org
+Description:
+ Time in seconds for which balance switch will be turned on.
+ Multiple of 71.5 seconds.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
new file mode 100644
index 000000000000..1c2a07f7a75e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
@@ -0,0 +1,39 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_invert
+Date: October 2016
+KernelVersion: 4.9
+Contact: Peter Rosin <peda@axentia.se>
+Description:
+ The DAC is used to find the peak level of an alternating
+ voltage input signal by a binary search using the output
+ of a comparator wired to an interrupt pin. Like so::
+
+ _
+ | \
+ input +------>-------|+ \
+ | \
+ .-------. | }---.
+ | | | / |
+ | dac|-->--|- / |
+ | | |_/ |
+ | | |
+ | | |
+ | irq|------<-------'
+ | |
+ '-------'
+
+ The boolean invert attribute (0/1) should be set when the
+ input signal is centered around the maximum value of the
+ dac instead of zero. The envelope detector will search
+ from below in this case and will also invert the result.
+
+ The edge/level of the interrupt is also switched to its
+ opposite value.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltageY_compare_interval
+Date: October 2016
+KernelVersion: 4.9
+Contact: Peter Rosin <peda@axentia.se>
+Description:
+ Number of milliseconds to wait for the comparator in each
+ step of the binary search for the input peak level. Needs
+ to relate to the frequency of the input signal.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435
new file mode 100644
index 000000000000..4b01150af397
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435
@@ -0,0 +1,48 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sensing_mode
+Date: August 2015
+KernelVersion: 4.2.0
+Contact: source@cogentembedded.com
+Description:
+ Program sensor type for threshold detector inputs.
+ Could be either "GND-Open" or "Supply-Open" mode. Y is a
+ threshold detector input channel. Channels 0..7, 8..15, 16..23
+ and 24..31 has common sensor types.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_voltageY_thresh_falling_value
+Date: August 2015
+KernelVersion: 4.2.0
+Contact: source@cogentembedded.com
+Description:
+ Channel Y low voltage threshold. If sensor input voltage goes lower then
+ this value then the threshold falling event is pushed.
+ Depending on in_voltageY_sensing_mode the low voltage threshold
+ is separately set for "GND-Open" and "Supply-Open" modes.
+ Channels 0..31 have common low threshold values, but could have different
+ sensing_modes.
+
+ The low voltage threshold range is between 2..21V.
+ Hysteresis between low and high thresholds can not be lower then 2 and
+ can not be odd.
+
+ If falling threshold results hysteresis to odd value then rising
+ threshold is automatically subtracted by one.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_voltageY_thresh_rising_value
+Date: August 2015
+KernelVersion: 4.2.0
+Contact: source@cogentembedded.com
+Description:
+ Channel Y high voltage threshold. If sensor input voltage goes higher then
+ this value then the threshold rising event is pushed.
+ Depending on in_voltageY_sensing_mode the high voltage threshold
+ is separately set for "GND-Open" and "Supply-Open" modes.
+
+ Channels 0..31 have common high threshold values, but could have different
+ sensing_modes.
+
+ The high voltage threshold range is between 3..22V.
+ Hysteresis between low and high thresholds can not be lower then 2 and
+ can not be odd.
+
+ If rising threshold results hysteresis to odd value then falling
+ threshold is automatically appended by one.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-max11410 b/Documentation/ABI/testing/sysfs-bus-iio-adc-max11410
new file mode 100644
index 000000000000..2a53c6b37360
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-max11410
@@ -0,0 +1,13 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage_filterY_notch_en
+Date: September 2022
+KernelVersion: 6.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Enable or disable a notch filter.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage_filterY_notch_center
+Date: September 2022
+KernelVersion: 6.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Center frequency of the notch filter in Hz.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-mcp3564 b/Documentation/ABI/testing/sysfs-bus-iio-adc-mcp3564
new file mode 100644
index 000000000000..b168aa44b233
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-mcp3564
@@ -0,0 +1,53 @@
+What: /sys/bus/iio/devices/iio:deviceX/boost_current_gain
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute is used to set the gain of the biasing current
+ circuit of the Delta-Sigma modulator. The different BOOST
+ settings are applied to the entire modulator circuit, including
+ the voltage reference buffers.
+
+What: /sys/bus/iio/devices/iio:deviceX/boost_current_gain_available
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns a list with the possible gain values for
+ the current biasing circuit of the Delta-Sigma modulator.
+
+What: /sys/bus/iio/devices/iio:deviceX/auto_zeroing_mux_enable
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute is used to enable the analog input multiplexer
+ auto-zeroing algorithm (the input multiplexer and the ADC
+ include an offset cancellation algorithm that cancels the offset
+ contribution of the ADC). When the offset cancellation algorithm
+ is enabled, ADC takes two conversions, one with the differential
+ input as VIN+/VIN-, one with VIN+/VIN- inverted. In this case the
+ conversion time is multiplied by two compared to the default
+ case where the algorithm is disabled. This technique allows the
+ cancellation of the ADC offset error and the achievement of
+ ultra-low offset without any digital calibration. The resulting
+ offset is the residue of the difference between the two
+ conversions, which is on the order of magnitude of the noise
+ floor. This offset is effectively canceled at every conversion,
+ so the residual offset error temperature drift is extremely low.
+ Write '1' to enable it, write '0' to disable it.
+
+What: /sys/bus/iio/devices/iio:deviceX/auto_zeroing_ref_enable
+KernelVersion: 6.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute is used to enable the chopping algorithm for the
+ internal voltage reference buffer. This setting has no effect
+ when external voltage reference is selected.
+ Internal voltage reference buffer injects a certain quantity of
+ 1/f noise into the system that can be modulated with the
+ incoming input signals and can limit the SNR performance at
+ higher Oversampling Ratio values (over 256). To overcome this
+ limitation, the buffer includes an auto-zeroing algorithm that
+ greatly reduces (cancels out) the 1/f noise and cancels the
+ offset value of the reference buffer. As a result, the SNR of
+ the system is not affected by this 1/f noise component of the
+ reference buffer, even at maximum oversampling ratio values.
+ Write '1' to enable it, write '0' to disable it.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-mt6360 b/Documentation/ABI/testing/sysfs-bus-iio-adc-mt6360
new file mode 100644
index 000000000000..e5a7b1c7cca3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-mt6360
@@ -0,0 +1,78 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage0_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 USBID ADC which connected to connector ID pin.
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage1_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 VBUS ADC with lower accuracy(+-75mA)
+ higher measure range(1~22mV)
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage2_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 VBUS ADC with higher accuracy(+-30mA)
+ lower measure range(1~9.76V)
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage3_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 VSYS ADC
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage4_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 VBAT ADC
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_current5_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 IBUS ADC
+ Calculating with scale and offset returns voltage in uA
+
+What: /sys/bus/iio/devices/iio:deviceX/in_current6_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 IBAT ADC
+ Calculating with scale and offset returns voltage in uA
+
+What: /sys/bus/iio/devices/iio:deviceX/in_current7_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 CHG_VDDP ADC
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_temp8_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 IC junction temperature
+ Calculating with scale and offset returns temperature in degree
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage9_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 VREF_TS ADC
+ Calculating with scale and offset returns voltage in uV
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage10_raw
+KernelVersion: 5.8.0
+Contact: gene_chen@richtek.com
+Description:
+ Indicated MT6360 TS ADC
+ Calculating with scale and offset returns voltage in uV
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-pac1934 b/Documentation/ABI/testing/sysfs-bus-iio-adc-pac1934
new file mode 100644
index 000000000000..625b7f867847
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-pac1934
@@ -0,0 +1,9 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_shunt_resistorY
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ The value of the shunt resistor may be known only at runtime
+ and set by a client application. This attribute allows to
+ set its value in micro-ohms. X is the IIO index of the device.
+ Y is the channel number. The value is used to calculate
+ current, power and accumulated energy.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32
new file mode 100644
index 000000000000..1975c7a1af34
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32
@@ -0,0 +1,21 @@
+What: /sys/bus/iio/devices/triggerX/trigger_polarity
+KernelVersion: 4.11
+Contact: fabrice.gasnier@st.com
+Description:
+ The STM32 ADC can be configured to use external trigger sources
+ (e.g. timers, pwm or exti gpio). Then, it can be tuned to start
+ conversions on external trigger by either:
+
+ - "rising-edge"
+ - "falling-edge"
+ - "both-edges".
+
+ Reading returns current trigger polarity.
+
+ Writing value before enabling conversions sets trigger polarity.
+
+What: /sys/bus/iio/devices/triggerX/trigger_polarity_available
+KernelVersion: 4.11
+Contact: fabrice.gasnier@st.com
+Description:
+ List all available trigger_polarity settings.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-bno055 b/Documentation/ABI/testing/sysfs-bus-iio-bno055
new file mode 100644
index 000000000000..f32b1644e986
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-bno055
@@ -0,0 +1,81 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_raw_range
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Raw (unscaled) range for acceleration readings. Unit after
+ application of scale is m/s^2. Note that this doesn't affects
+ the scale (which should be used when changing the maximum and
+ minimum readable value affects also the reading scaling factor).
+
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_raw_range
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Range for angular velocity readings in radians per second. Note
+ that this does not affects the scale (which should be used when
+ changing the maximum and minimum readable value affects also the
+ reading scaling factor).
+
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_raw_range_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of allowed values for in_accel_raw_range attribute
+
+What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_raw_range_available
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of allowed values for in_anglvel_raw_range attribute
+
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_calibration_fast_enable
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Can be 1 or 0. Enables/disables the "Fast Magnetometer
+ Calibration" HW function.
+
+What: /sys/bus/iio/devices/iio:deviceX/fusion_enable
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Can be 1 or 0. Enables/disables the "sensor fusion" (a.k.a.
+ NDOF) HW function.
+
+What: /sys/bus/iio/devices/iio:deviceX/calibration_data
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reports the binary calibration data blob for the IMU sensors.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_calibration_auto_status
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reports the autocalibration status for the accelerometer sensor.
+ Can be 0 (calibration non even enabled) or 1 to 5 where the greater
+ the number, the better the calibration status.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_gyro_calibration_auto_status
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reports the autocalibration status for the gyroscope sensor.
+ Can be 0 (calibration non even enabled) or 1 to 5 where the greater
+ the number, the better the calibration status.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_magn_calibration_auto_status
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reports the autocalibration status for the magnetometer sensor.
+ Can be 0 (calibration non even enabled) or 1 to 5 where the greater
+ the number, the better the calibration status.
+
+What: /sys/bus/iio/devices/iio:deviceX/sys_calibration_auto_status
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reports the status for the IMU overall autocalibration.
+ Can be 0 (calibration non even enabled) or 1 to 5 where the greater
+ the number, the better the calibration status.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-cdc-ad7746 b/Documentation/ABI/testing/sysfs-bus-iio-cdc-ad7746
new file mode 100644
index 000000000000..02ca8941dce1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-cdc-ad7746
@@ -0,0 +1,11 @@
+What: /sys/.../iio:deviceX/in_capacitableY_calibbias_calibration
+What: /sys/.../iio:deviceX/in_capacitableY_calibscale_calibration
+KernelVersion: 6.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Write 1 to trigger a calibration of the calibbias or
+ calibscale. For calibscale, a full scale capacitance should
+ be connected to the capacitance input and a
+ calibscale_calibration then started. For calibbias see
+ the device datasheet section on "capacitive system offset
+ calibration".
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp40 b/Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp40
new file mode 100644
index 000000000000..a95547e874f1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-sgp40
@@ -0,0 +1,17 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_temp_raw
+Date: August 2021
+KernelVersion: 5.15
+Contact: Andreas Klinger <ak@it-klinger.de>
+Description:
+ Set the temperature. This value is sent to the sensor for
+ temperature compensation.
+ Default value: 25000 (25 °C)
+
+What: /sys/bus/iio/devices/iio:deviceX/out_humidityrelative_raw
+Date: August 2021
+KernelVersion: 5.15
+Contact: Andreas Klinger <ak@it-klinger.de>
+Description:
+ Set the relative humidity. This value is sent to the sensor for
+ humidity compensation.
+ Default value: 50000 (50 % relative humidity)
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-sunrise-co2 b/Documentation/ABI/testing/sysfs-bus-iio-chemical-sunrise-co2
new file mode 100644
index 000000000000..ee7aeb11709b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-sunrise-co2
@@ -0,0 +1,38 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_calibration_factory
+Date: August 2021
+KernelVersion: 5.16
+Contact: Jacopo Mondi <jacopo@jmondi.org>
+Description:
+ Writing '1' triggers a 'Factory' calibration cycle.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_calibration_background
+Date: August 2021
+KernelVersion: 5.16
+Contact: Jacopo Mondi <jacopo@jmondi.org>
+Description:
+ Writing '1' triggers a 'Background' calibration cycle.
+
+What: /sys/bus/iio/devices/iio:deviceX/error_status_available
+Date: August 2021
+KernelVersion: 5.16
+Contact: Jacopo Mondi <jacopo@jmondi.org>
+Description:
+ Reading returns the list of possible chip error status.
+ Available options are:
+ - 'error_fatal': Analog front-end initialization error
+ - 'error_i2c': Read/write to non-existing register
+ - 'error_algorithm': Corrupted parameters
+ - 'error_calibration': Calibration has failed
+ - 'error_self_diagnostic': Internal interface failure
+ - 'error_out_of_range': Measured concentration out of scale
+ - 'error_memory': Error during memory operations
+ - 'error_no_measurement': Cleared at first measurement
+ - 'error_low_voltage': Sensor regulated voltage too low
+ - 'error_measurement_timeout': Unable to complete measurement
+
+What: /sys/bus/iio/devices/iio:deviceX/error_status
+Date: August 2021
+KernelVersion: 5.16
+Contact: Jacopo Mondi <jacopo@jmondi.org>
+Description:
+ Reading returns the current chip error status.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x
new file mode 100644
index 000000000000..d512f865600e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x
@@ -0,0 +1,7 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_concentration_VOC_short_raw
+Date: September 2015
+KernelVersion: 4.3
+Contact: Matt Ranostay <matt.ranostay@konsulko.com>
+Description:
+ Get the raw calibration VOC value from the sensor.
+ This value has little application outside of calibration.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
new file mode 100644
index 000000000000..9e3926243797
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
@@ -0,0 +1,18 @@
+What: /sys/bus/iio/devices/iio:deviceX/calibrate
+Date: July 2015
+KernelVersion: 4.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Writing '1' will perform a FOC (Fast Online Calibration). The
+ corresponding calibration offsets can be read from `*_calibbias`
+ entries.
+
+What: /sys/bus/iio/devices/iio:deviceX/id
+Date: September 2017
+KernelVersion: 4.14
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute is exposed by the CrOS EC sensors driver and
+ represents the sensor ID as exposed by the EC. This ID is used
+ by the Android sensor service hardware abstraction layer (sensor
+ HAL) through the Android container on ChromeOS.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac b/Documentation/ABI/testing/sysfs-bus-iio-dac
new file mode 100644
index 000000000000..810eaac5533c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dac
@@ -0,0 +1,61 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_currentY_toggle_en
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Toggle enable. Write 1 to enable toggle or 0 to disable it. This
+ is useful when one wants to change the DAC output codes. For
+ autonomous toggling, the way it should be done is:
+
+ - disable toggle operation;
+ - change out_currentY_rawN, where N is the integer value of the symbol;
+ - enable toggle operation.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_currentY_rawN
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute has the same meaning as out_currentY_raw. It is
+ specific to toggle enabled channels and refers to the DAC output
+ code in INPUT_N (_rawN), where N is the integer value of the symbol.
+ The same scale and offset as in out_currentY_raw applies.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_currentY_symbol
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Performs a SW switch to a predefined output symbol. This attribute
+ is specific to toggle enabled channels and allows switching between
+ multiple predefined symbols. Each symbol corresponds to a different
+ output, denoted as out_currentY_rawN, where N is the integer value
+ of the symbol. Writing an integer value N will select out_currentY_rawN.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_toggle_en
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Toggle enable. Write 1 to enable toggle or 0 to disable it. This
+ is useful when one wants to change the DAC output codes. For
+ autonomous toggling, the way it should be done is:
+
+ - disable toggle operation;
+ - change out_voltageY_rawN, where N is the integer value of the symbol;
+ - enable toggle operation.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_rawN
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute has the same meaning as out_currentY_raw. It is
+ specific to toggle enabled channels and refers to the DAC output
+ code in INPUT_N (_rawN), where N is the integer value of the symbol.
+ The same scale and offset as in out_currentY_raw applies.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_symbol
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Performs a SW switch to a predefined output symbol. This attribute
+ is specific to toggle enabled channels and allows switching between
+ multiple predefined symbols. Each symbol corresponds to a different
+ output, denoted as out_voltageY_rawN, where N is the integer value
+ of the symbol. Writing an integer value N will select out_voltageY_rawN.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac-ad5766 b/Documentation/ABI/testing/sysfs-bus-iio-dac-ad5766
new file mode 100644
index 000000000000..7fbcba15bf1e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dac-ad5766
@@ -0,0 +1,31 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_enable
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Dither enable. Write 1 to enable dither or 0 to disable it.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_invert
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Inverts the dither applied to the selected DAC channel. Dither is not
+ inverted by default. Write "1" to invert dither.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_scale_available
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Returns possible scalings available for the current channel.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_scale
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Scales the dither before it is applied to the selected channel.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_dither_source
+KernelVersion: 5.12
+Contact: linux-iio@vger.kernel.org
+Description:
+ Selects dither source applied to the selected channel. Write "0" to
+ select N0 source, write "1" to select N1 source.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac b/Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac
new file mode 100644
index 000000000000..580e93f373f6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dac-dpot-dac
@@ -0,0 +1,8 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw_available
+Date: October 2016
+KernelVersion: 4.9
+Contact: Peter Rosin <peda@axentia.se>
+Description:
+ The range of available values represented as the minimum value,
+ the step and the maximum value, all enclosed in square brackets.
+ Example: [0 1 256]
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac-ltc2688 b/Documentation/ABI/testing/sysfs-bus-iio-dac-ltc2688
new file mode 100644
index 000000000000..ae95a5477382
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dac-ltc2688
@@ -0,0 +1,55 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_en
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Dither enable. Write 1 to enable dither or 0 to disable it. This is useful
+ for changing the dither parameters. They way it should be done is:
+
+ - disable dither operation;
+ - change dither parameters (eg: frequency, phase...);
+ - enabled dither operation
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_raw
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ This raw, unscaled value refers to the dither signal amplitude.
+ The same scale as in out_voltageY_raw applies. However, the
+ offset might be different as it's always 0 for this attribute.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_raw_available
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Available range for dither raw amplitude values.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_offset
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Offset applied to out_voltageY_dither_raw. Read only attribute
+ always set to 0.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_frequency
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Sets the dither signal frequency. Units are in Hz.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_frequency_available
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Returns the available values for the dither frequency.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_phase
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Sets the dither signal phase. Units are in Radians.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_dither_phase_available
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Returns the available values for the dither phase.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
new file mode 100644
index 000000000000..91439d6d60b5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
@@ -0,0 +1,22 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_voltage_spi_clk_freq
+KernelVersion: 4.14
+Contact: arnaud.pouliquen@st.com
+Description:
+ For audio purpose only.
+
+ Used by audio driver to set/get the spi input frequency.
+
+ This is mandatory if DFSDM is slave on SPI bus, to
+ provide information on the SPI clock frequency during runtime
+ Notice that the SPI frequency should be a multiple of sample
+ frequency to ensure the precision.
+
+ if DFSDM input is SPI master:
+
+ Reading SPI clkout frequency,
+ error on writing
+
+ If DFSDM input is SPI Slave:
+
+ Reading returns value previously set.
+ Writing value before starting conversions.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
new file mode 100644
index 000000000000..9dae94aa880b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
@@ -0,0 +1,17 @@
+What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range
+Date: January 2017
+KernelVersion: 4.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ Show or set the maximum range between the sensor and the
+ first object echoed in meters. Default value is 6.020.
+ This setting limits the time the driver is waiting for a
+ echo.
+
+ Showing the range of available values is represented as the
+ minimum value, the step and the maximum value, all enclosed
+ in square brackets.
+
+ Example::
+
+ [0.043 0.043 11.008]
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dma-buffer b/Documentation/ABI/testing/sysfs-bus-iio-dma-buffer
new file mode 100644
index 000000000000..d526e6571001
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dma-buffer
@@ -0,0 +1,19 @@
+What: /sys/bus/iio/devices/iio:deviceX/buffer/length_align_bytes
+KernelVersion: 5.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ DMA buffers tend to have a alignment requirement for the
+ buffers. If this alignment requirement is not met samples might
+ be dropped from the buffer.
+
+ This property reports the alignment requirements in bytes.
+ This means that the buffer size in bytes needs to be a integer
+ multiple of the number reported by this file.
+
+ The alignment requirements in number of sample sets will depend
+ on the enabled channels and the bytes per channel. This means
+ that the alignment requirement in samples sets might change
+ depending on which and how many channels are enabled. Whereas
+ the alignment requirement reported in bytes by this property
+ will remain static and does not depend on which channels are
+ enabled.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818 b/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818
new file mode 100644
index 000000000000..c431f0a13cf5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-filter-admv8818
@@ -0,0 +1,18 @@
+What: /sys/bus/iio/devices/iio:deviceX/filter_mode_available
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading this returns the valid values that can be written to the
+ filter_mode attribute:
+
+ - auto -> Adjust bandpass filter to track changes in input clock rate.
+ - manual -> disable/unregister the clock rate notifier / input clock tracking.
+ - bypass -> bypass low pass filter, high pass filter and disable/unregister
+ the clock rate notifier
+
+What: /sys/bus/iio/devices/iio:deviceX/filter_mode
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute configures the filter mode.
+ Reading returns the actual mode.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
index a91aeabe7b24..d065cda7dd96 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
@@ -8,7 +8,9 @@ KernelVersion: 3.4.0
Contact: linux-iio@vger.kernel.org
Description:
Reading returns either '1' or '0'.
+
'1' means that the clock in question is present.
+
'0' means that the clock is missing.
What: /sys/bus/iio/devices/iio:deviceX/pllY_locked
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
new file mode 100644
index 000000000000..7fe6935d1448
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
@@ -0,0 +1,11 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns the datasheet name for channel Y::
+
+ out_altvoltage0_name: RF8x
+ out_altvoltage1_name: RFAUX8x
+ out_altvoltage2_name: RF16x
+ out_altvoltage3_name: RF32x
+
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1013 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1013
new file mode 100644
index 000000000000..9cf8cd0dd2df
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1013
@@ -0,0 +1,38 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0-altvoltage1_i_calibphase
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write unscaled value for the Local Oscillatior path quadrature I phase shift.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0-altvoltage1_q_calibphase
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write unscaled value for the Local Oscillatior path quadrature Q phase shift.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_i_calibbias
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write value for the Local Oscillatior Feedthrough Offset Calibration I Positive
+ side.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_q_calibbias
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write value for the Local Oscillatior Feedthrough Offset Calibration Q Positive side.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage1_i_calibbias
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write raw value for the Local Oscillatior Feedthrough Offset Calibration I Negative
+ side.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage1_q_calibbias
+KernelVersion:
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write raw value for the Local Oscillatior Feedthrough Offset Calibration Q Negative
+ side.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1014 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1014
new file mode 100644
index 000000000000..395010a0ef8b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-admv1014
@@ -0,0 +1,23 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_i_calibscale_coarse
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write value for the digital attenuator gain (IF_I) with coarse steps.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_q_calibscale_coarse
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write value for the digital attenuator gain (IF_Q) with coarse steps.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_i_calibscale_fine
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write value for the digital attenuator gain (IF_I) with fine steps.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_altvoltage0_q_calibscale_fine
+KernelVersion: 5.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Read/write value for the digital attenuator gain (IF_Q) with fine steps.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
new file mode 100644
index 000000000000..a8e04b41d9ff
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
@@ -0,0 +1,39 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_raw
+Date: May 2016
+KernelVersion:
+Contact: Andrew F. Davis <afd@ti.com>
+Description:
+ Get measured values from the ADC for these stages. Y is the
+ specific stage number corresponding to datasheet stage names
+ as follows:
+
+ == ==========
+ 1 LED2
+ 2 ALED2/LED3
+ 3 LED1
+ 4 ALED1/LED4
+ == ==========
+
+ Note that channels 5 and 6 represent LED2-ALED2 and LED1-ALED1
+ respectively which simply helper channels containing the
+ calculated difference in the value of stage 1 - 2 and 3 - 4.
+ The values are expressed in 24-bit twos complement.
+ The LED current for the stage is controlled via
+ out_currentY_raw.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_offset
+Date: May 2016
+KernelVersion:
+Contact: Andrew F. Davis <afd@ti.com>
+Description:
+ Get and set the offset cancellation DAC setting for these
+ stages. The values are expressed in 5-bit sign-magnitude.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_resistance
+What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_capacitance
+Date: May 2016
+KernelVersion:
+Contact: Andrew F. Davis <afd@ti.com>
+Description:
+ Get and set the resistance and the capacitance settings for the
+ Transimpedance Amplifier during the associated stage.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity b/Documentation/ABI/testing/sysfs-bus-iio-humidity
new file mode 100644
index 000000000000..cb0d7e75d297
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity
@@ -0,0 +1,10 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
+What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
+KernelVersion: 5.3.8
+Contact: linux-iio@vger.kernel.org
+Description:
+ Controls the heater device within the humidity sensor to get
+ rid of excess condensation.
+
+ In some devices, this is just a switch in which case 0 = OFF,
+ and 1 = ON.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad5933 b/Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad5933
new file mode 100644
index 000000000000..0e86747c67f8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad5933
@@ -0,0 +1,35 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_start
+Date: March 2019
+KernelVersion: 3.1.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Frequency sweep start frequency in Hz.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_increment
+Date: March 2019
+KernelVersion: 3.1.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Frequency increment in Hz (step size) between consecutive
+ frequency points along the sweep.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_points
+Date: March 2019
+KernelVersion: 3.1.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Number of frequency points (steps) in the frequency sweep.
+ This value, in conjunction with the
+ out_altvoltageY_frequency_start and the
+ out_altvoltageY_frequency_increment, determines the frequency
+ sweep range for the sweep operation.
+
+What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_settling_cycles
+Date: March 2019
+KernelVersion: 3.1.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Number of output excitation cycles (settling time cycles)
+ that are allowed to pass through the unknown impedance,
+ after each frequency increment, and before the ADC is triggered
+ to perform a conversion sequence of the response signal.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc b/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc
new file mode 100644
index 000000000000..8dbca113112d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc
@@ -0,0 +1,15 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_allow_async_readout
+Date: December 2015
+KernelVersion: 4.4
+Contact: linux-iio@vger.kernel.org
+Description:
+ By default (value '0'), the capture thread checks for the Conversion
+ Ready Flag to being set prior to committing a new value to the sample
+ buffer. This synchronizes the in-chip conversion rate with the
+ in-driver readout rate at the cost of an additional register read.
+
+ Writing '1' will remove the polling for the Conversion Ready Flags to
+ save the additional i2c transaction, which will improve the bandwidth
+ available for reading data. However, samples can be occasionally skipped
+ or repeated, depending on the beat between the capture and conversion
+ rates.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-inv_icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-inv_icm42600
new file mode 100644
index 000000000000..7eeacfb7650d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-inv_icm42600
@@ -0,0 +1,18 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_power_mode
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ Accelerometer power mode. Setting this attribute will set the
+ requested power mode to use if the ODR support it. If ODR
+ support only 1 mode, power mode will be enforced.
+ Reading this attribute will return the current accelerometer
+ power mode if the sensor is on, or the requested value if the
+ sensor is off. The value between real and requested value can
+ be different for ODR supporting only 1 mode.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_accel_power_mode_available
+KernelVersion: 6.11
+Contact: linux-iio@vger.kernel.org
+Description:
+ List of available accelerometer power modes that can be set in
+ in_accel_power_mode attribute.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-isl29501 b/Documentation/ABI/testing/sysfs-bus-iio-isl29501
new file mode 100644
index 000000000000..d009cfbbd72b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-isl29501
@@ -0,0 +1,47 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_agc_gain
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_agc_gain_bias
+KernelVersion: 4.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ This sensor has an automatic gain control (agc) loop
+ which sets the analog signal levels at an optimum
+ level by controlling programmable gain amplifiers. The
+ criteria for optimal gain is determined by the sensor.
+
+ Return the actual gain value as an integer in [0; 65536]
+ range when read from.
+
+ The agc gain read when measuring crosstalk shall be
+ written into in_proximity0_agc_gain_bias.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calib_phase_temp_a
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calib_phase_temp_b
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calib_phase_light_a
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calib_phase_light_b
+KernelVersion: 4.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ The sensor is able to perform correction of distance
+ measurements due to changing temperature and ambient
+ light conditions. It can be programmed to correct for
+ a second order error polynomial.
+
+ Phase data has to be collected when temperature and
+ ambient light are modulated independently.
+
+ Then a least squares curve fit to a second order
+ polynomial has to be generated from the data. The
+ resultant curves have the form ax^2 + bx + c.
+
+ From those two curves, a and b coefficients shall be
+ stored in in_proximity0_calib_phase_temp_a and
+ in_proximity0_calib_phase_temp_b for temperature and
+ in in_proximity0_calib_phase_light_a and
+ in_proximity0_calib_phase_light_b for ambient light.
+
+ Those values must be integer in [0; 8355840] range.
+
+ Finally, the c constant is set by the sensor
+ internally.
+
+ The value stored in sensor is displayed when read from.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
new file mode 100644
index 000000000000..220206a20d98
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
@@ -0,0 +1,21 @@
+What: /sys/bus/iio/devices/iio:deviceX/proximity_on_chip_ambient_infrared_suppression
+Date: January 2011
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ From ISL29018 Data Sheet (FN6619.4, Oct 8, 2012) regarding the
+ infrared suppression:
+
+ Scheme 0, makes full n (4, 8, 12, 16) bits (unsigned) proximity
+ detection. The range of Scheme 0 proximity count is from 0 to
+ 2^n. Logic 1 of this bit, Scheme 1, makes n-1 (3, 7, 11, 15)
+ bits (2's complementary) proximity_less_ambient detection. The
+ range of Scheme 1 proximity count is from -2^(n-1) to 2^(n-1).
+ The sign bit is extended for resolutions less than 16. While
+ Scheme 0 has wider dynamic range, Scheme 1 proximity detection
+ is less affected by the ambient IR noise variation.
+
+ == =============================================
+ 0 Sensing IR from LED and ambient
+ 1 Sensing IR from LED with ambient IR rejection
+ == =============================================
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
index 22c5ea670971..c476d48d0f82 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
@@ -41,14 +41,6 @@ Description:
Get the current light zone (0..4) as defined by the
in_illuminance0_threshY_{falling,rising} thresholds.
-What: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date: May 2012
-KernelVersion: 3.5
-Contact: Johan Hovold <jhovold@gmail.com>
-Description:
- Get output current for channel Y (0..255), that is,
- out_currentY_currentZ_raw, where Z is the current zone.
-
What: /sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw
Date: May 2012
KernelVersion: 3.5
@@ -59,3 +51,6 @@ Description:
These values correspond to the ALS-mapper target registers for
ALS-mapper Y + 1.
+
+ Note that out_currentY_raw provides the current for the
+ current zone.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-si1133 b/Documentation/ABI/testing/sysfs-bus-iio-light-si1133
new file mode 100644
index 000000000000..6f130cdb26a6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-si1133
@@ -0,0 +1,22 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ir_small_raw
+KernelVersion: 4.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Unit-less infrared intensity. The intensity is measured from 1
+ dark photodiode. "small" indicate the surface area capturing
+ infrared.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ir_large_raw
+KernelVersion: 4.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Unit-less infrared intensity. The intensity is measured from 4
+ dark photodiodes. "large" indicate the surface area capturing
+ infrared.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_intensity_large_raw
+KernelVersion: 4.18
+Contact: linux-iio@vger.kernel.org
+Description:
+ Unit-less light intensity with more diodes.
+
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2583 b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2583
new file mode 100644
index 000000000000..a2e19964e87e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2583
@@ -0,0 +1,20 @@
+What: /sys/bus/iio/devices/device[n]/in_illuminance_calibrate
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ This property causes an internal calibration of the als gain trim
+ value which is later used in calculating illuminance in lux.
+
+What: /sys/bus/iio/devices/device[n]/in_illuminance_lux_table
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ This property gets/sets the table of coefficients
+ used in calculating illuminance in lux.
+
+What: /sys/bus/iio/devices/device[n]/in_illuminance_input_target
+KernelVersion: 2.6.37
+Contact: linux-iio@vger.kernel.org
+Description:
+ This property is the known externally illuminance (in lux).
+ It is used in the process of calibrating the device accuracy.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772 b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772
new file mode 100644
index 000000000000..b2798b258bf7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772
@@ -0,0 +1,13 @@
+What: /sys/bus/iio/devices/device[n]/in_illuminance0_calibrate
+KernelVersion: 3.3-rc1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Causes an internal calibration of the als gain trim
+ value which is later used in calculating illuminance in lux.
+
+What: /sys/bus/iio/devices/device[n]/in_proximity0_calibrate
+KernelVersion: 3.3-rc1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Causes a recalculation and adjustment to the
+ proximity_thresh_rising_value.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
new file mode 100644
index 000000000000..13f099ef6a95
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
@@ -0,0 +1,20 @@
+What: /sys/bus/iio/devices/iio:deviceX/meas_conf
+What: /sys/bus/iio/devices/iio:deviceX/meas_conf_available
+KernelVersion: 4.5
+Contact: linux-iio@vger.kernel.org
+Description:
+ Current configuration and available configurations
+ for the bias current.
+
+ ============ ============================================
+ normal Normal measurement configurations (default)
+ positivebias Positive bias configuration
+ negativebias Negative bias configuration
+ disabled Only available on HMC5983. Disables magnetic
+ sensor and enables temperature sensor.
+ ============ ============================================
+
+ Note:
+ The effect of this configuration may vary
+ according to the device. For exact documentation
+ check the device's datasheet.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-meas-spec b/Documentation/ABI/testing/sysfs-bus-iio-meas-spec
new file mode 100644
index 000000000000..6d47e548eee5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-meas-spec
@@ -0,0 +1,7 @@
+What: /sys/bus/iio/devices/iio:deviceX/battery_low
+KernelVersion: 4.1.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns either '1' or '0'. '1' means that the
+ battery level supplied to sensor is below 2.25V.
+ This ABI is available for tsys02d, htu21, ms8607
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp4531 b/Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp4531
new file mode 100644
index 000000000000..2a91fbe394fc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-potentiometer-mcp4531
@@ -0,0 +1,8 @@
+What: /sys/bus/iio/devices/iio:deviceX/out_resistance_raw_available
+Date: October 2016
+KernelVersion: 4.9
+Contact: Peter Rosin <peda@axentia.se>
+Description:
+ The range of available values represented as the minimum value,
+ the step and the maximum value, all enclosed in square brackets.
+ Example: [0 1 256]
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity b/Documentation/ABI/testing/sysfs-bus-iio-proximity
new file mode 100644
index 000000000000..9b9d1cc9b703
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity
@@ -0,0 +1,24 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_nearlevel
+Date: March 2020
+KernelVersion: 5.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Near level for proximity sensors. This is a single integer
+ value that tells user space when an object should be
+ considered close to the device. If the value read from the
+ sensor is above or equal to the value in this file an object
+ should typically be considered near.
+
+What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+Date: March 2014
+KernelVersion: 3.15
+Contact: linux-iio@vger.kernel.org
+Description:
+ Proximity sensors sometimes have a controllable amplifier
+ on the signal from which time of flight measurements are
+ taken.
+ The appropriate values to take is dependent on both the
+ sensor and its operating environment:
+ * as3935 (0-31 range)
+ 18 = indoors (default)
+ 14 = outdoors
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
index 6708c5e264aa..1e5c40775a6c 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
+++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
@@ -1,16 +1,15 @@
-What /sys/bus/iio/devices/iio:deviceX/in_proximity_raw
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity_input
Date: March 2014
KernelVersion: 3.15
-Contact: Matt Ranostay <mranostay@gmail.com>
+Contact: Matt Ranostay <matt.ranostay@konsulko.com>
Description:
Get the current distance in meters of storm (1km steps)
1000-40000 = distance in meters
-What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date: March 2014
-KernelVersion: 3.15
-Contact: Matt Ranostay <mranostay@gmail.com>
+What /sys/bus/iio/devices/iio:deviceX/noise_level_tripped
+Date: May 2017
+KernelVersion: 4.13
+Contact: Matt Ranostay <matt.ranostay@konsulko.com>
Description:
- Show or set the gain boost of the amp, from 0-31 range.
- 18 = indoors (default)
- 14 = outdoors
+ When 1 the noise level is over the trip level and not reporting
+ valid data
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s1210 b/Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s1210
new file mode 100644
index 000000000000..f92c79342b93
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s1210
@@ -0,0 +1,27 @@
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_max
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns the current Degradation of Signal Reset Maximum
+ Threshold value in millivolts. Writing sets the value.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_max_available
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns the allowable voltage range for
+ in_altvoltage0_mag_rising_reset_max.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_min
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns the current Degradation of Signal Reset Minimum
+ Threshold value in millivolts. Writing sets the value.
+
+What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_min_available
+KernelVersion: 6.7
+Contact: linux-iio@vger.kernel.org
+Description:
+ Reading returns the allowable voltage range for
+ in_altvoltage0_mag_rising_reset_min.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sps30 b/Documentation/ABI/testing/sysfs-bus-iio-sps30
new file mode 100644
index 000000000000..06e1c272537b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-sps30
@@ -0,0 +1,28 @@
+What: /sys/bus/iio/devices/iio:deviceX/start_cleaning
+Date: December 2018
+KernelVersion: 5.0
+Contact: linux-iio@vger.kernel.org
+Description:
+ Writing 1 starts sensor self cleaning. Internal fan accelerates
+ to its maximum speed and keeps spinning for about 10 seconds in
+ order to blow out accumulated dust.
+
+What: /sys/bus/iio/devices/iio:deviceX/cleaning_period
+Date: January 2019
+KernelVersion: 5.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Sensor is capable of triggering self cleaning periodically.
+ Period can be changed by writing a new value here. Upon reading
+ the current one is returned. Units are seconds.
+
+ Writing 0 disables periodical self cleaning entirely.
+
+What: /sys/bus/iio/devices/iio:deviceX/cleaning_period_available
+Date: January 2019
+KernelVersion: 5.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ The range of available values in seconds represented as the
+ minimum value, the step and the maximum value, all enclosed in
+ square brackets.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sx9310 b/Documentation/ABI/testing/sysfs-bus-iio-sx9310
new file mode 100644
index 000000000000..3ac7759013e5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-sx9310
@@ -0,0 +1,10 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity3_comb_raw
+Date: February 2019
+KernelVersion: 5.6
+Contact: Daniel Campello <campello@chromium.org>
+Description:
+ Proximity measurement indicating that some object is
+ near the combined sensor. The combined sensor presents
+ proximity measurements constructed by hardware by
+ combining measurements taken from a given set of
+ physical sensors.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sx9324 b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
new file mode 100644
index 000000000000..a8342770e7cb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
@@ -0,0 +1,29 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_proximity<id>_setup
+Date: November 2021
+KernelVersion: 5.17
+Contact: Gwendal Grignou <gwendal@chromium.org>
+Description:
+ SX9324 has 3 inputs, CS0, CS1 and CS2. Hardware layout
+ defines if the input is
+
+ + not connected (HZ),
+ + grounded (GD),
+ + connected to an antenna where it can act as a base
+ (DS - data shield), or measured input (MI).
+
+ The sensor rotates measurement across 4 phases
+ (PH0, PH1, PH2, PH3), where the inputs are configured
+ and then measured.
+
+ By default, during the first phase, [PH0], CS0 is measured,
+ while CS1 and CS2 are used as shields.
+ `cat in_proximity0_setup` returns "MI,DS,DS".
+ [PH1], CS1 is measured, CS0 and CS2 are shield:
+ `cat in_proximity1_setup` returns "DS,MI,DS".
+ [PH2], CS2 is measured, CS0 and CS1 are shield:
+ `cat in_proximity1_setup` returns "DS,DS,MI".
+ [PH3], CS1 and CS2 are measured (combo mode):
+ `cat in_proximity1_setup` returns "DS,MI,MI".
+
+ Note, these are the chip default. Hardware layout will most
+ likely dictate different output. The entry is read-only.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-thermocouple b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
new file mode 100644
index 000000000000..01259df297ca
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
@@ -0,0 +1,18 @@
+What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv
+KernelVersion: 5.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Overvoltage or Undervoltage Input Fault. The internal circuitry
+ is protected from excessive voltages applied to the thermocouple
+ cables. The device can also detect if such a condition occurs.
+
+ Reading returns '1' if input voltage is negative or greater
+ than VDD, otherwise '0'.
+
+What: /sys/bus/iio/devices/iio:deviceX/fault_oc
+KernelVersion: 5.1
+Contact: linux-iio@vger.kernel.org
+Description:
+ Open-circuit fault. The detection of open-circuit faults,
+ such as those caused by broken thermocouple wires.
+ Reading returns '1' if fault, '0' otherwise.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
new file mode 100644
index 000000000000..05074c4a65e2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
@@ -0,0 +1,143 @@
+What: /sys/bus/iio/devices/triggerX/master_mode_available
+KernelVersion: 4.11
+Contact: benjamin.gaignard@st.com
+Description:
+ Reading returns the list possible master modes which are:
+
+
+ - "reset"
+ The UG bit from the TIMx_EGR register is
+ used as trigger output (TRGO).
+ - "enable"
+ The Counter Enable signal CNT_EN is used
+ as trigger output.
+ - "update"
+ The update event is selected as trigger output.
+ For instance a master timer can then be used
+ as a prescaler for a slave timer.
+ - "compare_pulse"
+ The trigger output send a positive pulse
+ when the CC1IF flag is to be set.
+ - "OC1REF"
+ OC1REF signal is used as trigger output.
+ - "OC2REF"
+ OC2REF signal is used as trigger output.
+ - "OC3REF"
+ OC3REF signal is used as trigger output.
+ - "OC4REF"
+ OC4REF signal is used as trigger output.
+
+ Additional modes (on TRGO2 only):
+
+ - "OC5REF"
+ OC5REF signal is used as trigger output.
+ - "OC6REF"
+ OC6REF signal is used as trigger output.
+ - "compare_pulse_OC4REF":
+ OC4REF rising or falling edges generate pulses.
+ - "compare_pulse_OC6REF":
+ OC6REF rising or falling edges generate pulses.
+ - "compare_pulse_OC4REF_r_or_OC6REF_r":
+ OC4REF or OC6REF rising edges generate pulses.
+ - "compare_pulse_OC4REF_r_or_OC6REF_f":
+ OC4REF rising or OC6REF falling edges generate
+ pulses.
+ - "compare_pulse_OC5REF_r_or_OC6REF_r":
+ OC5REF or OC6REF rising edges generate pulses.
+ - "compare_pulse_OC5REF_r_or_OC6REF_f":
+ OC5REF rising or OC6REF falling edges generate
+ pulses.
+
+ ::
+
+ +-----------+ +-------------+ +---------+
+ | Prescaler +-> | Counter | +-> | Master | TRGO(2)
+ +-----------+ +--+--------+-+ |-> | Control +-->
+ | | || +---------+
+ +--v--------+-+ OCxREF || +---------+
+ | Chx compare +----------> | Output | ChX
+ +-----------+-+ | | Control +-->
+ . | | +---------+
+ . | | .
+ +-----------v-+ OC6REF | .
+ | Ch6 compare +---------+>
+ +-------------+
+
+ Example with: "compare_pulse_OC4REF_r_or_OC6REF_r"::
+
+ X
+ X X
+ X . . X
+ X . . X
+ X . . X
+ count X . . . . X
+ . . . .
+ . . . .
+ +---------------+
+ OC4REF | . . |
+ +-+ . . +-+
+ . +---+ .
+ OC6REF . | | .
+ +-------+ +-------+
+ +-+ +-+
+ TRGO2 | | | |
+ +-+ +---+ +---------+
+
+What: /sys/bus/iio/devices/triggerX/master_mode
+KernelVersion: 4.11
+Contact: benjamin.gaignard@st.com
+Description:
+ Reading returns the current master modes.
+ Writing set the master mode
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count0_preset
+KernelVersion: 4.12
+Contact: benjamin.gaignard@st.com
+Description:
+ Reading returns the current preset value.
+ Writing sets the preset value.
+ When counting up the counter starts from 0 and fires an
+ event when reach preset value.
+ When counting down the counter start from preset value
+ and fire event when reach 0.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available
+KernelVersion: 4.12
+Contact: benjamin.gaignard@st.com
+Description:
+ Reading returns the list possible enable modes.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count0_enable_mode
+KernelVersion: 4.12
+Contact: benjamin.gaignard@st.com
+Description:
+ Configure the device counter enable modes, in all case
+ counting direction is set by in_count0_count_direction
+ attribute and the counter is clocked by the internal clock.
+
+ always:
+ Counter is always ON.
+
+ gated:
+ Counting is enabled when connected trigger signal
+ level is high else counting is disabled.
+
+ triggered:
+ Counting is enabled on rising edge of the connected
+ trigger, and remains enabled for the duration of this
+ selected mode.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count_trigger_mode_available
+KernelVersion: 4.13
+Contact: benjamin.gaignard@st.com
+Description:
+ Reading returns the list possible trigger modes.
+
+What: /sys/bus/iio/devices/iio:deviceX/in_count0_trigger_mode
+KernelVersion: 4.13
+Contact: benjamin.gaignard@st.com
+Description:
+ Configure the device counter trigger mode
+ counting direction is set by in_count0_count_direction
+ attribute and the counter is clocked by the connected trigger
+ rising edges.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs b/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs
index 5235e6c749ab..04ac62305018 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs
+++ b/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs
@@ -9,3 +9,34 @@ Description:
automated testing or in situations, where other trigger methods
are not applicable. For example no RTC or spare GPIOs.
X is the IIO index of the trigger.
+
+What: /sys/bus/iio/devices/triggerX/name
+KernelVersion: 2.6.39
+Contact: linux-iio@vger.kernel.org
+Description:
+ The name attribute holds a description string for the current
+ trigger. In order to associate the trigger with an IIO device
+ one should write this name string to
+ /sys/bus/iio/devices/iio:deviceY/trigger/current_trigger.
+
+What: /sys/bus/iio/devices/iio_sysfs_trigger/add_trigger
+KernelVersion: 2.6.39
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute is provided by the iio-trig-sysfs stand-alone
+ driver and it is used to activate the creation of a new trigger.
+ In order to achieve this, one should write a positive integer
+ into the associated file, which will serve as the id of the
+ trigger. If the trigger with the specified id is already present
+ in the system, an invalid argument message will be returned.
+
+What: /sys/bus/iio/devices/iio_sysfs_trigger/remove_trigger
+KernelVersion: 2.6.39
+Contact: linux-iio@vger.kernel.org
+Description:
+ This attribute is used to unregister and delete a previously
+ created trigger from the list of available triggers. In order to
+ achieve this, one should write a positive integer into the
+ associated file, representing the id of the trigger that needs
+ to be removed. If the trigger can't be found, an invalid
+ argument message will be returned to the user.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-vf610 b/Documentation/ABI/testing/sysfs-bus-iio-vf610
new file mode 100644
index 000000000000..491ead804488
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-vf610
@@ -0,0 +1,16 @@
+What: /sys/bus/iio/devices/iio:deviceX/in_conversion_mode
+KernelVersion: 4.2
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies the hardware conversion mode used. The three
+ available modes are "normal", "high-speed" and "low-power",
+ where the last is the default mode.
+
+
+What: /sys/bus/iio/devices/iio:deviceX/out_conversion_mode
+KernelVersion: 4.6
+Contact: linux-iio@vger.kernel.org
+Description:
+ Specifies the hardware conversion mode used within DAC.
+ The two available modes are "high-power" and "low-power",
+ where "low-power" mode is the default mode.
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth
new file mode 100644
index 000000000000..b7b2278fe042
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth
@@ -0,0 +1,52 @@
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/masters/*
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure output ports for STP masters. Writing -1
+ disables a master; any
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_port
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RO) Output port type:
+
+ == =========================
+ 0 not present,
+ 1 MSU (Memory Storage Unit)
+ 2 CTP (Common Trace Port)
+ 4 PTI (MIPI PTI).
+ == =========================
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_drop
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Data retention policy setting: keep (0) or drop (1)
+ incoming data while output port is in reset.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_null
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) STP NULL packet generation: enabled (1) or disabled (0).
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_flush
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Force flush data from byte packing buffer for the output
+ port.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_reset
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RO) Output port is in reset (1).
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_smcfreq
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) STP sync packet frequency for the port. Specifies the
+ number of clocks between mainenance packets.
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
new file mode 100644
index 000000000000..a74252e580a5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
@@ -0,0 +1,54 @@
+What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/wrap
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure MSC buffer wrapping. 1 == wrapping enabled.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/mode
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure MSC operating mode:
+
+ - "single", for contiguous buffer mode (high-order alloc);
+ - "multi", for multiblock mode;
+ - "ExI", for DCI handler mode;
+ - "debug", for debug mode;
+ - any of the currently loaded buffer sinks.
+
+ If operating mode changes, existing buffer is deallocated,
+ provided there are no active users and tracing is not enabled,
+ otherwise the write will fail.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/nr_pages
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure MSC buffer size for "single" or "multi" modes.
+
+ In single mode, this is a single number of pages, has to be
+ power of 2. In multiblock mode, this is a comma-separated list
+ of numbers of pages for each window to be allocated. Number of
+ windows is not limited.
+
+ Writing to this file deallocates existing buffer (provided
+ there are no active users and tracing is not enabled) and then
+ allocates a new one.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/win_switch
+Date: May 2019
+KernelVersion: 5.2
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Trigger window switch for the MSC's buffer, in
+ multi-window mode. In "multi" mode, accepts writes of "1", thereby
+ triggering a window switch for the buffer. Returns an error in any
+ other operating mode or attempts to write something other than "1".
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/stop_on_full
+Date: March 2020
+KernelVersion: 5.7
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure whether trace stops when the last available window
+ becomes full (1/y/Y) or wraps around and continues until the next
+ window becomes available again (0/n/N).
+
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti
new file mode 100644
index 000000000000..df0b24fd0218
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti
@@ -0,0 +1,24 @@
+What: /sys/bus/intel_th/devices/<intel_th_id>-pti/mode
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure PTI output width. Currently supported values
+ are 4, 8, 12, 16.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-pti/freerunning_clock
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) 0: PTI trace clock acts as a strobe which only toggles
+ when there is trace data to send. 1: PTI trace clock is a
+ free-running clock.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-pti/clock_divider
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Configure PTI port clock divider:
+ - 0: Intel TH clock rate,
+ - 1: 1/2 Intel TH clock rate,
+ - 2: 1/4 Intel TH clock rate,
+ - 3: 1/8 Intel TH clock rate.
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices
new file mode 100644
index 000000000000..d1f667104944
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices
@@ -0,0 +1,15 @@
+What: /sys/bus/intel_th/devices/<intel_th_id>-<device><id>/active
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RW) Writes of 1 or 0 enable or disable trace output to this
+ output device. Reads return current status. Requires that the
+ correstponding output port driver be loaded.
+
+What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/port
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description: (RO) Port number, corresponding to this output device on the
+ switch (GTH) or "unassigned" if the corresponding output
+ port driver is not loaded.
diff --git a/Documentation/ABI/testing/sysfs-bus-mcb b/Documentation/ABI/testing/sysfs-bus-mcb
new file mode 100644
index 000000000000..77947c509796
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-mcb
@@ -0,0 +1,29 @@
+What: /sys/bus/mcb/devices/mcb:X
+Date: March 2016
+KernelVersion: 4.7
+Contact: Johannes Thumshirn <jth@kernel.org>
+Description: Hardware chip or device hosting the MEN chameleon bus
+
+What: /sys/bus/mcb/devices/mcb:X/revision
+Date: March 2016
+KernelVersion: 4.7
+Contact: Johannes Thumshirn <jth@kernel.org>
+Description: The FPGA's revision number
+
+What: /sys/bus/mcb/devices/mcb:X/minor
+Date: March 2016
+KernelVersion: 4.7
+Contact: Johannes Thumshirn <jth@kernel.org>
+Description: The FPGA's minor number
+
+What: /sys/bus/mcb/devices/mcb:X/model
+Date: March 2016
+KernelVersion: 4.7
+Contact: Johannes Thumshirn <jth@kernel.org>
+Description: The FPGA's model number
+
+What: /sys/bus/mcb/devices/mcb:X/name
+Date: March 2016
+KernelVersion: 4.7
+Contact: Johannes Thumshirn <jth@kernel.org>
+Description: The FPGA's name
diff --git a/Documentation/ABI/testing/sysfs-bus-mdio b/Documentation/ABI/testing/sysfs-bus-mdio
index 491baaf4285f..38be04dfc05e 100644
--- a/Documentation/ABI/testing/sysfs-bus-mdio
+++ b/Documentation/ABI/testing/sysfs-bus-mdio
@@ -1,29 +1,72 @@
-What: /sys/bus/mdio_bus/devices/.../phy_id
-Date: November 2012
-KernelVersion: 3.8
-Contact: netdev@vger.kernel.org
-Description:
- This attribute contains the 32-bit PHY Identifier as reported
- by the device during bus enumeration, encoded in hexadecimal.
- This ID is used to match the device with the appropriate
- driver.
-
-What: /sys/bus/mdio_bus/devices/.../phy_interface
-Date: February 2014
-KernelVersion: 3.15
-Contact: netdev@vger.kernel.org
-Description:
- This attribute contains the PHY interface as configured by the
- Ethernet driver during bus enumeration, encoded in string.
- This interface mode is used to configure the Ethernet MAC with the
- appropriate mode for its data lines to the PHY hardware.
-
-What: /sys/bus/mdio_bus/devices/.../phy_has_fixups
-Date: February 2014
-KernelVersion: 3.15
-Contact: netdev@vger.kernel.org
-Description:
- This attribute contains the boolean value whether a given PHY
- device has had any "fixup" workaround running on it, encoded as
- a boolean. This information is provided to help troubleshooting
- PHY configurations.
+What: /sys/bus/mdio_bus/devices/.../statistics/
+What: /sys/class/mdio_bus/.../statistics/
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ This folder contains statistics about global and per
+ MDIO bus address statistics.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/transfers
+What: /sys/class/mdio_bus/.../transfers
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of transfers for this MDIO bus.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/errors
+What: /sys/class/mdio_bus/.../statistics/errors
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of transfer errors for this MDIO bus.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/writes
+What: /sys/class/mdio_bus/.../statistics/writes
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of write transactions for this MDIO bus.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/reads
+What: /sys/class/mdio_bus/.../statistics/reads
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of read transactions for this MDIO bus.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/transfers_<addr>
+What: /sys/class/mdio_bus/.../statistics/transfers_<addr>
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of transfers for this MDIO bus address.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/errors_<addr>
+What: /sys/class/mdio_bus/.../statistics/errors_<addr>
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of transfer errors for this MDIO bus address.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/writes_<addr>
+What: /sys/class/mdio_bus/.../statistics/writes_<addr>
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of write transactions for this MDIO bus address.
+
+What: /sys/bus/mdio_bus/devices/.../statistics/reads_<addr>
+What: /sys/class/mdio_bus/.../statistics/reads_<addr>
+Date: January 2020
+KernelVersion: 5.6
+Contact: netdev@vger.kernel.org
+Description:
+ Total number of read transactions for this MDIO bus address.
diff --git a/Documentation/ABI/testing/sysfs-bus-mei b/Documentation/ABI/testing/sysfs-bus-mei
index 2066f0bbd453..6e9a105fe5cb 100644
--- a/Documentation/ABI/testing/sysfs-bus-mei
+++ b/Documentation/ABI/testing/sysfs-bus-mei
@@ -4,4 +4,53 @@ KernelVersion: 3.10
Contact: Samuel Ortiz <sameo@linux.intel.com>
linux-mei@linux.intel.com
Description: Stores the same MODALIAS value emitted by uevent
- Format: mei:<mei device name>
+ Format: mei:<mei device name>:<device uuid>:<protocol version>
+
+What: /sys/bus/mei/devices/.../name
+Date: May 2015
+KernelVersion: 4.2
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client device name
+ Format: string
+
+What: /sys/bus/mei/devices/.../uuid
+Date: May 2015
+KernelVersion: 4.2
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client device uuid
+ Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+What: /sys/bus/mei/devices/.../version
+Date: Aug 2015
+KernelVersion: 4.3
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client protocol version
+ Format: %d
+
+What: /sys/bus/mei/devices/.../max_conn
+Date: Nov 2019
+KernelVersion: 5.5
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client maximum number of connections
+ Format: %d
+
+What: /sys/bus/mei/devices/.../fixed
+Date: Nov 2019
+KernelVersion: 5.5
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client fixed address, if any
+ Format: %d
+
+What: /sys/bus/mei/devices/.../vtag
+Date: Nov 2020
+KernelVersion: 5.9
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client vtag support status
+ Format: %d
+
+What: /sys/bus/mei/devices/.../max_len
+Date: Nov 2019
+KernelVersion: 5.5
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Stores mei client maximum message length
+ Format: %d
diff --git a/Documentation/ABI/testing/sysfs-bus-mmc b/Documentation/ABI/testing/sysfs-bus-mmc
new file mode 100644
index 000000000000..519f028d19cc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-mmc
@@ -0,0 +1,4 @@
+What: /sys/bus/mmc/devices/.../rev
+Date: October 2017
+Contact: Jin Qian <jinqian@android.com>
+Description: Extended CSD revision number
diff --git a/Documentation/ABI/testing/sysfs-bus-most b/Documentation/ABI/testing/sysfs-bus-most
new file mode 100644
index 000000000000..38cc03e408e7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-most
@@ -0,0 +1,299 @@
+What: /sys/bus/most/devices/<dev>/description
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Provides information about the physical location of the
+ device. Hardware attached via USB, for instance,
+ might return <1-1.1:1.0>
+Users:
+
+What: /sys/bus/most/devices/<dev>/interface
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the type of peripheral interface the device uses.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ If the network interface controller is attached via USB, a dci
+ directory is created that allows applications to read and
+ write the controller's DCI registers.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/arb_address
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to set an arbitrary DCI register address an
+ application wants to read from or write to.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/arb_value
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to read and write the DCI register whose address
+ is stored in arb_address.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_eui48_hi
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MAC address.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_eui48_lo
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MAC address.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_eui48_mi
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MAC address.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_filter
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MEP filter address.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_hash0
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MEP hash table.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_hash1
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MEP hash table.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_hash2
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MEP hash table.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/mep_hash3
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to check and configure the MEP hash table.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/ni_state
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the current network interface state.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/node_address
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the current node address.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/node_position
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the current node position.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/packet_bandwidth
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the configured packet bandwidth.
+Users:
+
+What: /sys/bus/most/devices/<dev>/dci/sync_ep
+Date: June 2016
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Triggers the controller's synchronization process for a certain
+ endpoint.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ For every channel of the device a directory is created, whose
+ name is dictated by the HDM. This enables an application to
+ collect information about the channel's capabilities and
+ configure it.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/available_datatypes
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the data types the channel can transport.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/available_directions
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the directions the channel is capable of.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/number_of_packet_buffers
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the number of packet buffers the channel can
+ handle.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/number_of_stream_buffers
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the number of streaming buffers the channel can
+ handle.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/size_of_packet_buffer
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the size of a packet buffer the channel can
+ handle.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/size_of_stream_buffer
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates the size of a streaming buffer the channel can
+ handle.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/set_number_of_buffers
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is to read back the configured number of buffers of
+ the channel.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/set_buffer_size
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is to read back the configured buffer size of the channel.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/set_direction
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is to read back the configured direction of the channel.
+ The following strings will be accepted::
+
+ 'tx',
+ 'rx'
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/set_datatype
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is to read back the configured data type of the channel.
+ The following strings will be accepted::
+
+ 'control',
+ 'async',
+ 'sync',
+ 'isoc_avp'
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/set_subbuffer_size
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is to read back the configured subbuffer size of
+ the channel.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/set_packets_per_xact
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is to read back the configured number of packets per
+ transaction of the channel. This is only applicable when
+ connected via USB.
+Users:
+
+What: /sys/bus/most/devices/<dev>/<channel>/channel_starving
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ Indicates whether channel ran out of buffers.
+Users:
+
+What: /sys/bus/most/drivers/most_core/components
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to retrieve a list of registered components.
+Users:
+
+What: /sys/bus/most/drivers/most_core/links
+Date: March 2017
+KernelVersion: 4.15
+Contact: Christian Gromm <christian.gromm@microchip.com>
+Description:
+ This is used to retrieve a list of established links.
+Users:
diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
new file mode 100644
index 000000000000..32dccc00d57d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
@@ -0,0 +1,17 @@
+What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) Moxtet module description. Format: string
+
+What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) Moxtet module ID. Format: %x
+
+What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name
+Date: March 2019
+KernelVersion: 5.3
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) Moxtet module name. Format: string
diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit
new file mode 100644
index 000000000000..ed483a11c58c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-nfit
@@ -0,0 +1,233 @@
+For all of the nmem device attributes under ``nfit/*``, see the 'NVDIMM Firmware
+Interface Table (NFIT)' section in the ACPI specification
+(http://www.uefi.org/specifications) for more details.
+
+What: /sys/bus/nd/devices/nmemX/nfit/serial
+Date: Jun, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Serial number of the NVDIMM (non-volatile dual in-line
+ memory module), assigned by the module vendor.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/handle
+Date: Apr, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The address (given by the _ADR object) of the device on its
+ parent bus of the NVDIMM device containing the NVDIMM region.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/device
+Date: Apr, 2015
+KernelVersion: v4.1
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Device id for the NVDIMM, assigned by the module vendor.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/rev_id
+Date: Jun, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Revision of the NVDIMM, assigned by the module vendor.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/phys_id
+Date: Apr, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Handle (i.e., instance number) for the SMBIOS (system
+ management BIOS) Memory Device structure describing the NVDIMM
+ containing the NVDIMM region.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/flags
+Date: Jun, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The flags in the NFIT memory device sub-structure indicate
+ the state of the data on the nvdimm relative to its energy
+ source or last "flush to persistence".
+
+ The attribute is a translation of the 'NVDIMM State Flags' field
+ in section 5.2.25.3 'NVDIMM Region Mapping' Structure of the
+ ACPI specification 6.2.
+
+ The health states are "save_fail", "restore_fail", "flush_fail",
+ "not_armed", "smart_event", "map_fail" and "smart_notify".
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/format
+What: /sys/bus/nd/devices/nmemX/nfit/format1
+What: /sys/bus/nd/devices/nmemX/nfit/formats
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The interface codes indicate support for persistent memory
+ mapped directly into system physical address space and / or a
+ block aperture access mechanism to the NVDIMM media.
+ The 'formats' attribute displays the number of supported
+ interfaces.
+
+ This layout is compatible with existing libndctl binaries that
+ only expect one code per-dimm as they will ignore
+ nmemX/nfit/formats and nmemX/nfit/formatN.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/vendor
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Vendor id of the NVDIMM.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/dsm_mask
+Date: May, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The bitmask indicates the supported device specific control
+ functions relative to the NVDIMM command family supported by the
+ device
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/family
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Displays the NVDIMM family command sets. Values
+ 0, 1, 2 and 3 correspond to NVDIMM_FAMILY_INTEL,
+ NVDIMM_FAMILY_HPE1, NVDIMM_FAMILY_HPE2 and NVDIMM_FAMILY_MSFT
+ respectively.
+
+ See the specifications for these command families here:
+ http://pmem.io/documents/NVDIMM_DSM_Interface-V1.6.pdf
+ https://github.com/HewlettPackard/hpe-nvm/blob/master/Documentation/
+ https://msdn.microsoft.com/library/windows/hardware/mt604741"
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/id
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) ACPI specification 6.2 section 5.2.25.9, defines an
+ identifier for an NVDIMM, which reflects the id attribute.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/subsystem_vendor
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Sub-system vendor id of the NVDIMM non-volatile memory
+ subsystem controller.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/subsystem_rev_id
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Sub-system revision id of the NVDIMM non-volatile memory subsystem
+ controller, assigned by the non-volatile memory subsystem
+ controller vendor.
+
+
+What: /sys/bus/nd/devices/nmemX/nfit/subsystem_device
+Date: Apr, 2016
+KernelVersion: v4.7
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) Sub-system device id for the NVDIMM non-volatile memory
+ subsystem controller, assigned by the non-volatile memory
+ subsystem controller vendor.
+
+
+What: /sys/bus/nd/devices/ndbusX/nfit/revision
+Date: Jun, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) ACPI NFIT table revision number.
+
+
+What: /sys/bus/nd/devices/ndbusX/nfit/scrub
+Date: Sep, 2016
+KernelVersion: v4.9
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) This shows the number of full Address Range Scrubs (ARS)
+ that have been completed since driver load time. Userspace can
+ wait on this using select/poll etc. A '+' at the end indicates
+ an ARS is in progress
+
+ Writing a value of 1 triggers an ARS scan.
+
+
+What: /sys/bus/nd/devices/ndbusX/nfit/hw_error_scrub
+Date: Sep, 2016
+KernelVersion: v4.9
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) Provides a way to toggle the behavior between just adding
+ the address (cache line) where the MCE happened to the poison
+ list and doing a full scrub. The former (selective insertion of
+ the address) is done unconditionally.
+
+ This attribute can have the following values written to it:
+
+ '0': Switch to the default mode where an exception will only
+ insert the address of the memory error into the poison and
+ badblocks lists.
+ '1': Enable a full scrub to happen if an exception for a memory
+ error is received.
+
+
+What: /sys/bus/nd/devices/ndbusX/nfit/dsm_mask
+Date: Jun, 2017
+KernelVersion: v4.13
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) The bitmask indicates the supported bus specific control
+ functions. See the section named 'NVDIMM Root Device _DSMs' in
+ the ACPI specification.
+
+What: /sys/bus/nd/devices/ndbusX/nfit/firmware_activate_noidle
+Date: Apr, 2020
+KernelVersion: v5.8
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RW) The Intel platform implementation of firmware activate
+ support exposes an option let the platform force idle devices in
+ the system over the activation event, or trust that the OS will
+ do it. The safe default is to let the platform force idle
+ devices since the kernel is already in a suspend state, and on
+ the chance that a driver does not properly quiesce bus-mastering
+ after a suspend callback the platform will handle it. However,
+ the activation might abort if, for example, platform firmware
+ determines that the activation time exceeds the max PCI-E
+ completion timeout. Since the platform does not know whether the
+ OS is running the activation from a suspend context it aborts,
+ but if the system owner trusts driver suspend callback to be
+ sufficient then 'firmware_activation_noidle' can be
+ enabled to bypass the activation abort.
+
+What: /sys/bus/nd/devices/regionX/nfit/range_index
+Date: Jun, 2015
+KernelVersion: v4.2
+Contact: nvdimm@lists.linux.dev
+Description:
+ (RO) A unique number provided by the BIOS to identify an address
+ range. Used by NVDIMM Region Mapping Structure to uniquely refer
+ to this structure. Value of 0 is reserved and not used as an
+ index.
diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm
new file mode 100644
index 000000000000..64eb8f4c6a41
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-nvdimm
@@ -0,0 +1,59 @@
+What: nvdimm
+Date: July 2020
+KernelVersion: 5.8
+Contact: Dan Williams <dan.j.williams@intel.com>
+Description:
+
+The libnvdimm sub-system implements a common sysfs interface for
+platform nvdimm resources. See Documentation/driver-api/nvdimm/.
+
+What: /sys/bus/event_source/devices/nmemX/format
+Date: February 2022
+KernelVersion: 5.18
+Contact: Kajol Jain <kjain@linux.ibm.com>
+Description: (RO) Attribute group to describe the magic bits
+ that go into perf_event_attr.config for a particular pmu.
+ (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+ Each attribute under this group defines a bit range of the
+ perf_event_attr.config. Supported attribute is listed
+ below::
+
+ event = "config:0-4" - event ID
+
+ For example::
+
+ ctl_res_cnt = "event=0x1"
+
+What: /sys/bus/event_source/devices/nmemX/events
+Date: February 2022
+KernelVersion: 5.18
+Contact: Kajol Jain <kjain@linux.ibm.com>
+Description: (RO) Attribute group to describe performance monitoring events
+ for the nvdimm memory device. Each attribute in this group
+ describes a single performance monitoring event supported by
+ this nvdimm pmu. The name of the file is the name of the event.
+ (See ABI/testing/sysfs-bus-event_source-devices-events). A
+ listing of the events supported by a given nvdimm provider type
+ can be found in Documentation/driver-api/nvdimm/$provider.
+
+What: /sys/bus/event_source/devices/nmemX/cpumask
+Date: February 2022
+KernelVersion: 5.18
+Contact: Kajol Jain <kjain@linux.ibm.com>
+Description: (RO) This sysfs file exposes the cpumask which is designated to
+ to retrieve nvdimm pmu event counter data.
+
+What: /sys/bus/nd/devices/nmemX/cxl/id
+Date: November 2022
+KernelVersion: 6.2
+Contact: Dave Jiang <dave.jiang@intel.com>
+Description: (RO) Show the id (serial) of the device. This is CXL specific.
+
+What: /sys/bus/nd/devices/nmemX/cxl/provider
+Date: November 2022
+KernelVersion: 6.2
+Contact: Dave Jiang <dave.jiang@intel.com>
+Description: (RO) Shows the CXL bridge device that ties to a CXL memory device
+ to this NVDIMM device. I.e. the parent of the device returned is
+ a /sys/bus/cxl/devices/memX instance.
diff --git a/Documentation/ABI/testing/sysfs-bus-optee-devices b/Documentation/ABI/testing/sysfs-bus-optee-devices
new file mode 100644
index 000000000000..af31e5a22d89
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-optee-devices
@@ -0,0 +1,17 @@
+What: /sys/bus/tee/devices/optee-ta-<uuid>/
+Date: May 2020
+KernelVersion 5.8
+Contact: op-tee@lists.trustedfirmware.org
+Description:
+ OP-TEE bus provides reference to registered drivers under this directory. The <uuid>
+ matches Trusted Application (TA) driver and corresponding TA in secure OS. Drivers
+ are free to create needed API under optee-ta-<uuid> directory.
+
+What: /sys/bus/tee/devices/optee-ta-<uuid>/need_supplicant
+Date: November 2023
+KernelVersion: 6.7
+Contact: op-tee@lists.trustedfirmware.org
+Description:
+ Allows to distinguish whether an OP-TEE based TA/device requires user-space
+ tee-supplicant to function properly or not. This attribute will be present for
+ devices which depend on tee-supplicant to be running.
diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem
new file mode 100644
index 000000000000..34ee8c59ab25
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem
@@ -0,0 +1,75 @@
+What: /sys/bus/nd/devices/nmemX/papr/flags
+Date: Apr, 2020
+KernelVersion: v5.8
+Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
+Description:
+ (RO) Report flags indicating various states of a
+ papr-pmem NVDIMM device. Each flag maps to a one or
+ more bits set in the dimm-health-bitmap retrieved in
+ response to H_SCM_HEALTH hcall. The details of the bit
+ flags returned in response to this hcall is available
+ at 'Documentation/arch/powerpc/papr_hcalls.rst' . Below are
+ the flags reported in this sysfs file:
+
+ * "not_armed"
+ Indicates that NVDIMM contents will not
+ survive a power cycle.
+ * "flush_fail"
+ Indicates that NVDIMM contents
+ couldn't be flushed during last
+ shut-down event.
+ * "restore_fail"
+ Indicates that NVDIMM contents
+ couldn't be restored during NVDIMM
+ initialization.
+ * "encrypted"
+ NVDIMM contents are encrypted.
+ * "smart_notify"
+ There is health event for the NVDIMM.
+ * "scrubbed"
+ Indicating that contents of the
+ NVDIMM have been scrubbed.
+ * "locked"
+ Indicating that NVDIMM contents can't
+ be modified until next power cycle.
+
+What: /sys/bus/nd/devices/nmemX/papr/perf_stats
+Date: May, 2020
+KernelVersion: v5.9
+Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
+Description:
+ (RO) Report various performance stats related to papr-scm NVDIMM
+ device. This attribute is only available for NVDIMM devices
+ that support reporting NVDIMM performance stats. Each stat is
+ reported on a new line with each line composed of a
+ stat-identifier followed by it value. Below are currently known
+ dimm performance stats which are reported:
+
+ * "CtlResCt" : Controller Reset Count
+ * "CtlResTm" : Controller Reset Elapsed Time
+ * "PonSecs " : Power-on Seconds
+ * "MemLife " : Life Remaining
+ * "CritRscU" : Critical Resource Utilization
+ * "HostLCnt" : Host Load Count
+ * "HostSCnt" : Host Store Count
+ * "HostSDur" : Host Store Duration
+ * "HostLDur" : Host Load Duration
+ * "MedRCnt " : Media Read Count
+ * "MedWCnt " : Media Write Count
+ * "MedRDur " : Media Read Duration
+ * "MedWDur " : Media Write Duration
+ * "CchRHCnt" : Cache Read Hit Count
+ * "CchWHCnt" : Cache Write Hit Count
+ * "FastWCnt" : Fast Write Count
+
+What: /sys/bus/nd/devices/nmemX/papr/health_bitmap_inject
+Date: Jan, 2022
+KernelVersion: v5.17
+Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
+Description:
+ (RO) Reports the health bitmap inject bitmap that is applied to
+ bitmap received from PowerVM via the H_SCM_HEALTH. This is used
+ to forcibly set specific bits returned from Hcall. These is then
+ used to simulate various health or shutdown states for an nvdimm
+ and are set by user-space tools like ndctl by issuing a PAPR DSM.
+
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
index b3bc50f650ee..b767db2c52cb 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -1,4 +1,5 @@
What: /sys/bus/pci/drivers/.../bind
+What: /sys/devices/pciX/.../bind
Date: December 2003
Contact: linux-pci@vger.kernel.org
Description:
@@ -7,11 +8,14 @@ Description:
this location. This is useful for overriding default
bindings. The format for the location is: DDDD:BB:DD.F.
That is Domain:Bus:Device.Function and is the same as
- found in /sys/bus/pci/devices/. For example:
- # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
+ found in /sys/bus/pci/devices/. For example::
+
+ # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
+
(Note: kernels before 2.6.28 may require echo -n).
What: /sys/bus/pci/drivers/.../unbind
+What: /sys/devices/pciX/.../unbind
Date: December 2003
Contact: linux-pci@vger.kernel.org
Description:
@@ -20,11 +24,14 @@ Description:
this location. This may be useful when overriding default
bindings. The format for the location is: DDDD:BB:DD.F.
That is Domain:Bus:Device.Function and is the same as
- found in /sys/bus/pci/devices/. For example:
- # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
+ found in /sys/bus/pci/devices/. For example::
+
+ # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
+
(Note: kernels before 2.6.28 may require echo -n).
What: /sys/bus/pci/drivers/.../new_id
+What: /sys/devices/pciX/.../new_id
Date: December 2003
Contact: linux-pci@vger.kernel.org
Description:
@@ -38,10 +45,12 @@ Description:
Class, Class Mask, and Private Driver Data. The Vendor ID
and Device ID fields are required, the rest are optional.
Upon successfully adding an ID, the driver will probe
- for the device and attempt to bind to it. For example:
- # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
+ for the device and attempt to bind to it. For example::
+
+ # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
What: /sys/bus/pci/drivers/.../remove_id
+What: /sys/devices/pciX/.../remove_id
Date: February 2009
Contact: Chris Wright <chrisw@sous-sol.org>
Description:
@@ -54,8 +63,9 @@ Description:
required, the rest are optional. After successfully
removing an ID, the driver will no longer support the
device. This is useful to ensure auto probing won't
- match the driver to the device. For example:
- # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
+ match the driver to the device. For example::
+
+ # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
What: /sys/bus/pci/rescan
Date: January 2009
@@ -90,6 +100,17 @@ Description:
This attribute indicates the mode that the irq vector named by
the file is in (msi vs. msix)
+What: /sys/bus/pci/devices/.../irq
+Date: August 2021
+Contact: Linux PCI developers <linux-pci@vger.kernel.org>
+Description:
+ If a driver has enabled MSI (not MSI-X), "irq" contains the
+ IRQ of the first MSI vector. Otherwise "irq" contains the
+ IRQ of the legacy INTx interrupt.
+
+ "irq" being set to 0 indicates that the device isn't
+ capable of generating legacy INTx interrupts.
+
What: /sys/bus/pci/devices/.../remove
Date: January 2009
Contact: Linux PCI developers <linux-pci@vger.kernel.org>
@@ -115,6 +136,23 @@ Description:
child buses, and re-discover devices removed earlier
from this part of the device tree.
+What: /sys/bus/pci/devices/.../reset_method
+Date: August 2021
+Contact: Amey Narkhede <ameynarkhede03@gmail.com>
+Description:
+ Some devices allow an individual function to be reset
+ without affecting other functions in the same slot.
+
+ For devices that have this support, a file named
+ reset_method is present in sysfs. Reading this file
+ gives names of the supported and enabled reset methods and
+ their ordering. Writing a space-separated list of names of
+ reset methods sets the reset methods and ordering to be
+ used when resetting the device. Writing an empty string
+ disables the ability to reset the device. Writing
+ "default" enables all supported reset methods in the
+ default ordering.
+
What: /sys/bus/pci/devices/.../reset
Date: July 2009
Contact: Michael S. Tsirkin <mst@redhat.com>
@@ -125,6 +163,17 @@ Description:
will be present in sysfs. Writing 1 to this file
will perform reset.
+What: /sys/bus/pci/devices/.../reset_subordinate
+Date: October 2024
+Contact: linux-pci@vger.kernel.org
+Description:
+ This is visible only for bridge devices. If you want to reset
+ all devices attached through the subordinate bus of a specific
+ bridge device, writing 1 to this will try to do it. This will
+ affect all devices attached to the system through this bridge
+ similiar to writing 1 to their individual "reset" file, so use
+ with caution.
+
What: /sys/bus/pci/devices/.../vpd
Date: February 2008
Contact: Ben Hutchings <bwh@kernel.org>
@@ -133,11 +182,11 @@ Description:
binary file containing the Vital Product Data for the
device. It should follow the VPD format defined in
PCI Specification 2.1 or 2.2, but users should consider
- that some devices may have malformatted data. If the
- underlying VPD has a writable section then the
+ that some devices may have incorrectly formatted data.
+ If the underlying VPD has a writable section then the
corresponding section of this file will be writable.
-What: /sys/bus/pci/devices/.../virtfnN
+What: /sys/bus/pci/devices/.../virtfn<N>
Date: March 2009
Contact: Yu Zhao <yu.zhao@intel.com>
Description:
@@ -164,6 +213,24 @@ Description:
The symbolic link points to the PCI device sysfs entry of the
Physical Function this device associates with.
+What: /sys/bus/pci/devices/.../modalias
+Date: May 2005
+Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+ This attribute indicates the PCI ID of the device object.
+
+ That is in the format:
+ pci:vXXXXXXXXdXXXXXXXXsvXXXXXXXXsdXXXXXXXXbcXXscXXiXX,
+ where:
+
+ - vXXXXXXXX contains the vendor ID;
+ - dXXXXXXXX contains the device ID;
+ - svXXXXXXXX contains the sub-vendor ID;
+ - sdXXXXXXXX contains the subsystem device ID;
+ - bcXX contains the device class;
+ - scXX contains the device subclass;
+ - iXX contains the device class programming interface.
+
What: /sys/bus/pci/slots/.../module
Date: June 2009
Contact: linux-pci@vger.kernel.org
@@ -189,10 +256,13 @@ What: /sys/bus/pci/devices/.../index
Date: July 2010
Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com
Description:
- Reading this attribute will provide the firmware
- given instance (SMBIOS type 41 device type instance) of the
- PCI device. The attribute will be created only if the firmware
- has given an instance number to the PCI device.
+ Reading this attribute will provide the firmware given instance
+ number of the PCI device. Depending on the platform this can
+ be for example the SMBIOS type 41 device type instance or the
+ user-defined ID (UID) on s390. The attribute will be created
+ only if the firmware has given an instance number to the PCI
+ device and that number is guaranteed to uniquely identify the
+ device in the system.
Users:
Userspace applications interested in knowing the
firmware assigned device type instance of the PCI
@@ -294,3 +364,341 @@ Description:
a firmware bug to the system vendor. Writing to this file
taints the kernel with TAINT_FIRMWARE_WORKAROUND, which
reduces the supportability of your system.
+
+What: /sys/bus/pci/devices/.../revision
+Date: November 2016
+Contact: Emil Velikov <emil.l.velikov@gmail.com>
+Description:
+ This file contains the revision field of the PCI device.
+ The value comes from device config space. The file is read only.
+
+What: /sys/bus/pci/devices/.../sriov_drivers_autoprobe
+Date: April 2017
+Contact: Bodong Wang<bodong@mellanox.com>
+Description:
+ This file is associated with the PF of a device that
+ supports SR-IOV. It determines whether newly-enabled VFs
+ are immediately bound to a driver. It initially contains
+ 1, which means the kernel automatically binds VFs to a
+ compatible driver immediately after they are enabled. If
+ an application writes 0 to the file before enabling VFs,
+ the kernel will not bind VFs to a driver.
+
+ A typical use case is to write 0 to this file, then enable
+ VFs, then assign the newly-created VFs to virtual machines.
+ Note that changing this file does not affect already-
+ enabled VFs. In this scenario, the user must first disable
+ the VFs, write 0 to sriov_drivers_autoprobe, then re-enable
+ the VFs.
+
+ This is similar to /sys/bus/pci/drivers_autoprobe, but
+ affects only the VFs associated with a specific PF.
+
+What: /sys/bus/pci/devices/.../p2pmem/size
+Date: November 2017
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description:
+ If the device has any Peer-to-Peer memory registered, this
+ file contains the total amount of memory that the device
+ provides (in decimal).
+
+What: /sys/bus/pci/devices/.../p2pmem/available
+Date: November 2017
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description:
+ If the device has any Peer-to-Peer memory registered, this
+ file contains the amount of memory that has not been
+ allocated (in decimal).
+
+What: /sys/bus/pci/devices/.../p2pmem/published
+Date: November 2017
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description:
+ If the device has any Peer-to-Peer memory registered, this
+ file contains a '1' if the memory has been published for
+ use outside the driver that owns the device.
+
+What: /sys/bus/pci/devices/.../p2pmem/allocate
+Date: August 2022
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description:
+ This file allows mapping p2pmem into userspace. For each
+ mmap() call on this file, the kernel will allocate a chunk
+ of Peer-to-Peer memory for use in Peer-to-Peer transactions.
+ This memory can be used in O_DIRECT calls to NVMe backed
+ files for Peer-to-Peer copies.
+
+What: /sys/bus/pci/devices/.../link/clkpm
+ /sys/bus/pci/devices/.../link/l0s_aspm
+ /sys/bus/pci/devices/.../link/l1_aspm
+ /sys/bus/pci/devices/.../link/l1_1_aspm
+ /sys/bus/pci/devices/.../link/l1_2_aspm
+ /sys/bus/pci/devices/.../link/l1_1_pcipm
+ /sys/bus/pci/devices/.../link/l1_2_pcipm
+Date: October 2019
+Contact: Heiner Kallweit <hkallweit1@gmail.com>
+Description: If ASPM is supported for an endpoint, these files can be
+ used to disable or enable the individual power management
+ states. Write y/1/on to enable, n/0/off to disable.
+
+What: /sys/bus/pci/devices/.../power_state
+Date: November 2020
+Contact: Linux PCI developers <linux-pci@vger.kernel.org>
+Description:
+ This file contains the current PCI power state of the device.
+ The value comes from the PCI kernel device state and can be one
+ of: "unknown", "error", "D0", D1", "D2", "D3hot", "D3cold".
+ The file is read only.
+
+What: /sys/bus/pci/devices/.../sriov_vf_total_msix
+Date: January 2021
+Contact: Leon Romanovsky <leonro@nvidia.com>
+Description:
+ This file is associated with a SR-IOV physical function (PF).
+ It contains the total number of MSI-X vectors available for
+ assignment to all virtual functions (VFs) associated with PF.
+ The value will be zero if the device doesn't support this
+ functionality. For supported devices, the value will be
+ constant and won't be changed after MSI-X vectors assignment.
+
+What: /sys/bus/pci/devices/.../sriov_vf_msix_count
+Date: January 2021
+Contact: Leon Romanovsky <leonro@nvidia.com>
+Description:
+ This file is associated with a SR-IOV virtual function (VF).
+ It allows configuration of the number of MSI-X vectors for
+ the VF. This allows devices that have a global pool of MSI-X
+ vectors to optimally divide them between VFs based on VF usage.
+
+ The values accepted are:
+ * > 0 - this number will be reported as the Table Size in the
+ VF's MSI-X capability
+ * < 0 - not valid
+ * = 0 - will reset to the device default value
+
+ The file is writable if the PF is bound to a driver that
+ implements ->sriov_set_msix_vec_count().
+
+What: /sys/bus/pci/devices/.../resourceN_resize
+Date: September 2022
+Contact: Alex Williamson <alex.williamson@redhat.com>
+Description:
+ These files provide an interface to PCIe Resizable BAR support.
+ A file is created for each BAR resource (N) supported by the
+ PCIe Resizable BAR extended capability of the device. Reading
+ each file exposes the bitmap of available resource sizes:
+
+ # cat resource1_resize
+ 00000000000001c0
+
+ The bitmap represents supported resource sizes for the BAR,
+ where bit0 = 1MB, bit1 = 2MB, bit2 = 4MB, etc. In the above
+ example the device supports 64MB, 128MB, and 256MB BAR sizes.
+
+ When writing the file, the user provides the bit position of
+ the desired resource size, for example:
+
+ # echo 7 > resource1_resize
+
+ This indicates to set the size value corresponding to bit 7,
+ 128MB. The resulting size is 2 ^ (bit# + 20). This definition
+ matches the PCIe specification of this capability.
+
+ In order to make use of resource resizing, all PCI drivers must
+ be unbound from the device and peer devices under the same
+ parent bridge may need to be soft removed. In the case of
+ VGA devices, writing a resize value will remove low level
+ console drivers from the device. Raw users of pci-sysfs
+ resourceN attributes must be terminated prior to resizing.
+ Success of the resizing operation is not guaranteed.
+
+What: /sys/bus/pci/devices/.../leds/*:enclosure:*/brightness
+What: /sys/class/leds/*:enclosure:*/brightness
+Date: August 2024
+KernelVersion: 6.12
+Description:
+ LED indications on PCIe storage enclosures which are controlled
+ through the NPEM interface (Native PCIe Enclosure Management,
+ PCIe r6.1 sec 6.28) are accessible as led class devices, both
+ below /sys/class/leds and below NPEM-capable PCI devices.
+
+ Although these led class devices could be manipulated manually,
+ in practice they are typically manipulated automatically by an
+ application such as ledmon(8).
+
+ The name of a led class device is as follows:
+ <bdf>:enclosure:<indication>
+ where:
+
+ - <bdf> is the domain, bus, device and function number
+ (e.g. 10000:02:05.0)
+ - <indication> is a short description of the LED indication
+
+ Valid indications per PCIe r6.1 table 6-27 are:
+
+ - ok (drive is functioning normally)
+ - locate (drive is being identified by an admin)
+ - fail (drive is not functioning properly)
+ - rebuild (drive is part of an array that is rebuilding)
+ - pfa (drive is predicted to fail soon)
+ - hotspare (drive is marked to be used as a replacement)
+ - ica (drive is part of an array that is degraded)
+ - ifa (drive is part of an array that is failed)
+ - idt (drive is not the right type for the connector)
+ - disabled (drive is disabled, removal is safe)
+ - specific0 to specific7 (enclosure-specific indications)
+
+ Broadly, the indications fall into one of these categories:
+
+ - to signify drive state (ok, locate, fail, idt, disabled)
+ - to signify drive role or state in a software RAID array
+ (rebuild, pfa, hotspare, ica, ifa)
+ - to signify any other role or state (specific0 to specific7)
+
+ Mandatory indications per PCIe r6.1 sec 7.9.19.2 comprise:
+ ok, locate, fail, rebuild. All others are optional.
+ A led class device is only visible if the corresponding
+ indication is supported by the device.
+
+ To manipulate the indications, write 0 (LED_OFF) or 1 (LED_ON)
+ to the "brightness" file. Note that manipulating an indication
+ may implicitly manipulate other indications at the vendor's
+ discretion. E.g. when the user lights up the "ok" indication,
+ the vendor may choose to automatically turn off the "fail"
+ indication. The current state of an indication can be
+ retrieved by reading its "brightness" file.
+
+ The PCIe Base Specification allows vendors leeway to choose
+ different colors or blinking patterns for the indications,
+ but they typically follow the IBPI standard. E.g. the "locate"
+ indication is usually presented as one or two LEDs blinking at
+ 4 Hz frequency:
+ https://en.wikipedia.org/wiki/International_Blinking_Pattern_Interpretation
+
+ PCI Firmware Specification r3.3 sec 4.7 defines a DSM interface
+ to facilitate shared access by operating system and platform
+ firmware to a device's NPEM registers. The kernel will use
+ this DSM interface where available, instead of accessing NPEM
+ registers directly. The DSM interface does not support the
+ enclosure-specific indications "specific0" to "specific7",
+ hence the corresponding led class devices are unavailable if
+ the DSM interface is used.
+
+What: /sys/bus/pci/devices/.../doe_features
+Date: March 2025
+Contact: Linux PCI developers <linux-pci@vger.kernel.org>
+Description:
+ This directory contains a list of the supported Data Object
+ Exchange (DOE) features. The features are the file name.
+ The contents of each file is the raw Vendor ID and data
+ object feature values.
+
+ The value comes from the device and specifies the vendor and
+ data object type supported. The lower (RHS of the colon) is
+ the data object type in hex. The upper (LHS of the colon)
+ is the vendor ID.
+
+ As all DOE devices must support the DOE discovery feature,
+ if DOE is supported you will at least see the doe_discovery
+ file, with this contents:
+
+ # cat doe_features/doe_discovery
+ 0001:00
+
+ If the device supports other features you will see other
+ files as well. For example if CMA/SPDM and secure CMA/SPDM
+ are supported the doe_features directory will look like
+ this:
+
+ # ls doe_features
+ 0001:01 0001:02 doe_discovery
+
+What: /sys/bus/pci/devices/.../serial_number
+Date: December 2025
+Contact: Matthew Wood <thepacketgeek@gmail.com>
+Description:
+ This is visible only for PCI devices that support the serial
+ number extended capability. The file is read only and due to
+ the possible sensitivity of accessible serial numbers, admin
+ only.
+
+What: /sys/bus/pci/devices/.../tsm/
+Contact: linux-coco@lists.linux.dev
+Description:
+ This directory only appears if a physical device function
+ supports authentication (PCIe CMA-SPDM), interface security
+ (PCIe TDISP), and is accepted for secure operation by the
+ platform TSM driver. This attribute directory appears
+ dynamically after the platform TSM driver loads. So, only after
+ the /sys/class/tsm/tsm0 device arrives can tools assume that
+ devices without a tsm/ attribute directory will never have one;
+ before that, the security capabilities of the device relative to
+ the platform TSM are unknown. See
+ Documentation/ABI/testing/sysfs-class-tsm.
+
+What: /sys/bus/pci/devices/.../tsm/connect
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RW) Write the name of a TSM (TEE Security Manager) device from
+ /sys/class/tsm to this file to establish a connection with the
+ device. This typically includes an SPDM (DMTF Security
+ Protocols and Data Models) session over PCIe DOE (Data Object
+ Exchange) and may also include PCIe IDE (Integrity and Data
+ Encryption) establishment. Reads from this attribute return the
+ name of the connected TSM or the empty string if not
+ connected. A TSM device signals its readiness to accept PCI
+ connection via a KOBJ_CHANGE event.
+
+What: /sys/bus/pci/devices/.../tsm/disconnect
+Contact: linux-coco@lists.linux.dev
+Description:
+ (WO) Write the name of the TSM device that was specified
+ to 'connect' to teardown the connection.
+
+What: /sys/bus/pci/devices/.../tsm/dsm
+Contact: linux-coco@lists.linux.dev
+Description: (RO) Return PCI device name of this device's DSM (Device
+ Security Manager). When a device is in the connected state it
+ indicates that the platform TSM (TEE Security Manager) has made
+ a secure-session connection with a device's DSM. A DSM is always
+ physical function 0 and when the device supports TDISP (TEE
+ Device Interface Security Protocol) its managed functions also
+ populate this tsm/dsm attribute. The managed functions of a DSM
+ are SR-IOV (Single Root I/O Virtualization) virtual functions,
+ non-zero functions of a multi-function device, or downstream
+ endpoints depending on whether the DSM is an SR-IOV physical
+ function, function0 of a multi-function device, or an upstream
+ PCIe switch port. This is a "link" TSM attribute, see
+ Documentation/ABI/testing/sysfs-class-tsm.
+
+What: /sys/bus/pci/devices/.../tsm/bound
+Contact: linux-coco@lists.linux.dev
+Description: (RO) Return the device name of the TSM when the device is in a
+ TDISP (TEE Device Interface Security Protocol) operational state
+ (LOCKED, RUN, or ERROR, not UNLOCKED). Bound devices consume
+ platform TSM resources and depend on the device's configuration
+ (e.g. BME (Bus Master Enable) and MSE (Memory Space Enable)
+ among other settings) to remain stable for the duration of the
+ bound state. This attribute is only visible for devices that
+ support TDISP operation, and it is only populated after
+ successful connect and TSM bind. The TSM bind operation is
+ initiated by VFIO/IOMMUFD. This is a "link" TSM attribute, see
+ Documentation/ABI/testing/sysfs-class-tsm.
+
+What: /sys/bus/pci/devices/.../authenticated
+Contact: linux-pci@vger.kernel.org
+Description:
+ When the device's tsm/ directory is present device
+ authentication (PCIe CMA-SPDM) and link encryption (PCIe IDE)
+ are handled by the platform TSM (TEE Security Manager). When the
+ tsm/ directory is not present this attribute reflects only the
+ native CMA-SPDM authentication state with the kernel's
+ certificate store.
+
+ If the attribute is not present, it indicates that
+ authentication is unsupported by the device, or the TSM has no
+ available authentication methods for the device.
+
+ When present and the tsm/ attribute directory is present, the
+ authenticated attribute is an alias for the device 'connect'
+ state. See the 'tsm/connect' attribute for more details.
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer
new file mode 100644
index 000000000000..5ed284523956
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer
@@ -0,0 +1,163 @@
+PCIe Device AER statistics
+--------------------------
+
+These attributes show up under all the devices that are AER capable. These
+statistical counters indicate the errors "as seen/reported by the device".
+Note that this may mean that if an endpoint is causing problems, the AER
+counters may increment at its link partner (e.g. root port) because the
+errors may be "seen" / reported by the link partner and not the
+problematic endpoint itself (which may report all counters as 0 as it never
+saw any problems).
+
+What: /sys/bus/pci/devices/<dev>/aer_dev_correctable
+Date: July 2018
+KernelVersion: 4.19.0
+Contact: linux-pci@vger.kernel.org, rajatja@google.com
+Description: List of correctable errors seen and reported by this
+ PCI device using ERR_COR. Note that since multiple errors may
+ be reported using a single ERR_COR message, thus
+ TOTAL_ERR_COR at the end of the file may not match the actual
+ total of all the errors in the file. Sample output::
+
+ localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
+ Receiver Error 2
+ Bad TLP 0
+ Bad DLLP 0
+ RELAY_NUM Rollover 0
+ Replay Timer Timeout 0
+ Advisory Non-Fatal 0
+ Corrected Internal Error 0
+ Header Log Overflow 0
+ TOTAL_ERR_COR 2
+
+What: /sys/bus/pci/devices/<dev>/aer_dev_fatal
+Date: July 2018
+KernelVersion: 4.19.0
+Contact: linux-pci@vger.kernel.org, rajatja@google.com
+Description: List of uncorrectable fatal errors seen and reported by this
+ PCI device using ERR_FATAL. Note that since multiple errors may
+ be reported using a single ERR_FATAL message, thus
+ TOTAL_ERR_FATAL at the end of the file may not match the actual
+ total of all the errors in the file. Sample output::
+
+ localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
+ Undefined 0
+ Data Link Protocol 0
+ Surprise Down Error 0
+ Poisoned TLP 0
+ Flow Control Protocol 0
+ Completion Timeout 0
+ Completer Abort 0
+ Unexpected Completion 0
+ Receiver Overflow 0
+ Malformed TLP 0
+ ECRC 0
+ Unsupported Request 0
+ ACS Violation 0
+ Uncorrectable Internal Error 0
+ MC Blocked TLP 0
+ AtomicOp Egress Blocked 0
+ TLP Prefix Blocked Error 0
+ TOTAL_ERR_FATAL 0
+
+What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal
+Date: July 2018
+KernelVersion: 4.19.0
+Contact: linux-pci@vger.kernel.org, rajatja@google.com
+Description: List of uncorrectable nonfatal errors seen and reported by this
+ PCI device using ERR_NONFATAL. Note that since multiple errors
+ may be reported using a single ERR_FATAL message, thus
+ TOTAL_ERR_NONFATAL at the end of the file may not match the
+ actual total of all the errors in the file. Sample output::
+
+ localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
+ Undefined 0
+ Data Link Protocol 0
+ Surprise Down Error 0
+ Poisoned TLP 0
+ Flow Control Protocol 0
+ Completion Timeout 0
+ Completer Abort 0
+ Unexpected Completion 0
+ Receiver Overflow 0
+ Malformed TLP 0
+ ECRC 0
+ Unsupported Request 0
+ ACS Violation 0
+ Uncorrectable Internal Error 0
+ MC Blocked TLP 0
+ AtomicOp Egress Blocked 0
+ TLP Prefix Blocked Error 0
+ TOTAL_ERR_NONFATAL 0
+
+PCIe Rootport AER statistics
+----------------------------
+
+These attributes show up under only the rootports (or root complex event
+collectors) that are AER capable. These indicate the number of error messages as
+"reported to" the rootport. Please note that the rootports also transmit
+(internally) the ERR_* messages for errors seen by the internal rootport PCI
+device, so these counters include them and are thus cumulative of all the error
+messages on the PCI hierarchy originating at that root port.
+
+What: /sys/bus/pci/devices/<dev>/aer_rootport_total_err_cor
+Date: July 2018
+KernelVersion: 4.19.0
+Contact: linux-pci@vger.kernel.org, rajatja@google.com
+Description: Total number of ERR_COR messages reported to rootport.
+
+What: /sys/bus/pci/devices/<dev>/aer_rootport_total_err_fatal
+Date: July 2018
+KernelVersion: 4.19.0
+Contact: linux-pci@vger.kernel.org, rajatja@google.com
+Description: Total number of ERR_FATAL messages reported to rootport.
+
+What: /sys/bus/pci/devices/<dev>/aer_rootport_total_err_nonfatal
+Date: July 2018
+KernelVersion: 4.19.0
+Contact: linux-pci@vger.kernel.org, rajatja@google.com
+Description: Total number of ERR_NONFATAL messages reported to rootport.
+
+PCIe AER ratelimits
+-------------------
+
+These attributes show up under all the devices that are AER capable.
+They represent configurable ratelimits of logs per error type.
+
+See Documentation/PCI/pcieaer-howto.rst for more info on ratelimits.
+
+What: /sys/bus/pci/devices/<dev>/aer/correctable_ratelimit_interval_ms
+Date: May 2025
+KernelVersion: 6.16.0
+Contact: linux-pci@vger.kernel.org
+Description: Writing 0 disables AER correctable error log ratelimiting.
+ Writing a positive value sets the ratelimit interval in ms.
+ Default is DEFAULT_RATELIMIT_INTERVAL (5000 ms).
+
+What: /sys/bus/pci/devices/<dev>/aer/correctable_ratelimit_burst
+Date: May 2025
+KernelVersion: 6.16.0
+Contact: linux-pci@vger.kernel.org
+Description: Ratelimit burst for correctable error logs. Writing a value
+ changes the number of errors (burst) allowed per interval
+ before ratelimiting. Reading gets the current ratelimit
+ burst. Default is DEFAULT_RATELIMIT_BURST (10).
+
+What: /sys/bus/pci/devices/<dev>/aer/nonfatal_ratelimit_interval_ms
+Date: May 2025
+KernelVersion: 6.16.0
+Contact: linux-pci@vger.kernel.org
+Description: Writing 0 disables AER non-fatal uncorrectable error log
+ ratelimiting. Writing a positive value sets the ratelimit
+ interval in ms. Default is DEFAULT_RATELIMIT_INTERVAL
+ (5000 ms).
+
+What: /sys/bus/pci/devices/<dev>/aer/nonfatal_ratelimit_burst
+Date: May 2025
+KernelVersion: 6.16.0
+Contact: linux-pci@vger.kernel.org
+Description: Ratelimit burst for non-fatal uncorrectable error logs.
+ Writing a value changes the number of errors (burst)
+ allowed per interval before ratelimiting. Reading gets the
+ current ratelimit burst. Default is DEFAULT_RATELIMIT_BURST
+ (10).
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-avs b/Documentation/ABI/testing/sysfs-bus-pci-devices-avs
new file mode 100644
index 000000000000..ebff3fa12055
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-avs
@@ -0,0 +1,8 @@
+What: /sys/devices/pci0000:00/<dev>/avs/fw_version
+Date: February 2024
+Contact: Cezary Rojewski <cezary.rojewski@intel.com>
+Description:
+ Version of AudioDSP firmware ASoC avs driver is communicating
+ with.
+
+ Format: %d.%d.%d.%d, type:major:minor:build.
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt b/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt
new file mode 100644
index 000000000000..f85db86d63e8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt
@@ -0,0 +1,17 @@
+What: /sys/devices/pci0000:00/<dev>/fw_version
+Date: September 2020
+Contact: Cezary Rojewski <cezary.rojewski@intel.com>
+Description:
+ Version of AudioDSP firmware ASoC catpt driver is
+ communicating with.
+
+ Format: %d.%d.%d.%d, type:major:minor:build.
+
+What: /sys/devices/pci0000:00/<dev>/fw_info
+Date: September 2020
+Contact: Cezary Rojewski <cezary.rojewski@intel.com>
+Description:
+ Detailed AudioDSP firmware build information including
+ build hash and log-providers hash. This information is
+ obtained during initial handshake with firmware.
+ Format: %s.
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
index 53d99edd1d75..92a94e1068c2 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
@@ -1,68 +1,68 @@
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
Date: March 2009
-Kernel Version: 2.6.30
+KernelVersion: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 0 model for logical drive
Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
Date: March 2009
-Kernel Version: 2.6.30
+KernelVersion: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 0 revision for logical
drive Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
Date: March 2009
-Kernel Version: 2.6.30
+KernelVersion: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 83 serial number for logical
drive Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
Date: March 2009
-Kernel Version: 2.6.30
+KernelVersion: 2.6.30
Contact: iss_storagedev@hp.com
Description: Displays the SCSI INQUIRY page 0 vendor for logical drive
Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
Date: March 2009
-Kernel Version: 2.6.30
+KernelVersion: 2.6.30
Contact: iss_storagedev@hp.com
Description: A symbolic link to /sys/block/cciss!cXdY
-Where: /sys/bus/pci/devices/<dev>/ccissX/rescan
+What: /sys/bus/pci/devices/<dev>/ccissX/rescan
Date: August 2009
-Kernel Version: 2.6.31
+KernelVersion: 2.6.31
Contact: iss_storagedev@hp.com
Description: Kicks of a rescan of the controller to discover logical
drive topology changes.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
Date: August 2009
-Kernel Version: 2.6.31
+KernelVersion: 2.6.31
Contact: iss_storagedev@hp.com
Description: Displays the 8-byte LUN ID used to address logical
drive Y of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
Date: August 2009
-Kernel Version: 2.6.31
+KernelVersion: 2.6.31
Contact: iss_storagedev@hp.com
Description: Displays the RAID level of logical drive Y of
controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
+What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
Date: August 2009
-Kernel Version: 2.6.31
+KernelVersion: 2.6.31
Contact: iss_storagedev@hp.com
Description: Displays the usage count (number of opens) of logical drive Y
of controller X.
-Where: /sys/bus/pci/devices/<dev>/ccissX/resettable
+What: /sys/bus/pci/devices/<dev>/ccissX/resettable
Date: February 2011
-Kernel Version: 2.6.38
+KernelVersion: 2.6.38
Contact: iss_storagedev@hp.com
Description: Value of 1 indicates the controller can honor the reset_devices
kernel parameter. Value of 0 indicates reset_devices cannot be
@@ -71,9 +71,9 @@ Description: Value of 1 indicates the controller can honor the reset_devices
a dump device, as kdump requires resetting the device in order
to work reliably.
-Where: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
+What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode
Date: July 2011
-Kernel Version: 3.0
+KernelVersion: 3.0
Contact: iss_storagedev@hp.com
Description: Value of "simple" indicates that the controller has been placed
in "simple mode". Value of "performant" indicates that the
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic b/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic
new file mode 100644
index 000000000000..4ec03cd36357
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic
@@ -0,0 +1,26 @@
+What: /sys/devices/pci0000:00/*/QEMU0001:00/capability for MMIO
+ /sys/bus/pci/drivers/pvpanic-pci/0000:00:0*.0/capability for PCI
+Date: Jan 2021
+Contact: zhenwei pi <pizhenwei@bytedance.com>
+Description:
+ Read-only attribute. Capabilities of pvpanic device which
+ are supported by QEMU.
+
+ Format: %x.
+
+ Detailed bit definition refers to section <Bit Definition>
+ from pvpanic device specification:
+ https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/specs/pvpanic.txt
+
+What: /sys/devices/pci0000:00/*/QEMU0001:00/events
+ /sys/bus/pci/drivers/pvpanic-pci/0000:00:0*.0/events for PCI
+Date: Jan 2021
+Contact: zhenwei pi <pizhenwei@bytedance.com>
+Description:
+ RW attribute. Set/get which features in-use. This attribute
+ is used to enable/disable feature(s) of pvpanic device.
+ Notice that this value should be a subset of capability.
+
+ Format: %x.
+
+ Also refer to pvpanic device specification.
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
index 60c60fa624b2..c90d97a80855 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
+++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
@@ -21,11 +21,11 @@ Description:
number returns the port to normal operation.
For example: To force the high-speed device attached to
- port 4 on bus 2 to run at full speed:
+ port 4 on bus 2 to run at full speed::
echo 4 >/sys/bus/usb/devices/usb2/../companion
- To return the port to high-speed operation:
+ To return the port to high-speed operation::
echo -4 >/sys/bus/usb/devices/usb2/../companion
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio b/Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio
new file mode 100644
index 000000000000..4d08f28dc871
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio
@@ -0,0 +1,8 @@
+What: /sys/bus/pci/drivers/janz-cmodio/.../modulbus_number
+Date: May 2010
+KernelVersion: 2.6.35
+Contact: Ira W. Snyder <ira.snyder@gmail.com>
+Description:
+ Value representing the HEX switch S2 of the janz carrier board CMOD-IO or CAN-PCI2
+
+ Read-only: value of the configuration switch (0..15)
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd
new file mode 100644
index 000000000000..fc82aa4e54b0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd
@@ -0,0 +1,87 @@
+What: /sys/bus/pci/drivers/xhci_hcd/.../dbc
+Date: June 2017
+Contact: Lu Baolu <baolu.lu@linux.intel.com>
+Description:
+ xHCI compatible USB host controllers (i.e. super-speed
+ USB3 controllers) are often implemented with the Debug
+ Capability (DbC). It can present a debug device which
+ is fully compliant with the USB framework and provides
+ the equivalent of a very high performance full-duplex
+ serial link for debug purpose.
+
+ The DbC debug device shares a root port with xHCI host.
+ When the DbC is enabled, the root port will be assigned
+ to the Debug Capability. Otherwise, it will be assigned
+ to xHCI.
+
+ Writing "enable" to this attribute will enable the DbC
+ functionality and the shared root port will be assigned
+ to the DbC device. Writing "disable" to this attribute
+ will disable the DbC functionality and the shared root
+ port will roll back to the xHCI.
+
+ Reading this attribute gives the state of the DbC. It
+ can be one of the following states: disabled, enabled,
+ initialized, connected, configured and stalled.
+
+What: /sys/bus/pci/drivers/xhci_hcd/.../dbc_idVendor
+Date: March 2023
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ This dbc_idVendor attribute lets us change the idVendor field
+ presented in the USB device descriptor by this xhci debug
+ device.
+ Value can only be changed while debug capability (DbC) is in
+ disabled state to prevent USB device descriptor change while
+ connected to a USB host.
+ The default value is 0x1d6b (Linux Foundation).
+ It can be any 16-bit integer.
+
+What: /sys/bus/pci/drivers/xhci_hcd/.../dbc_idProduct
+Date: March 2023
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ This dbc_idProduct attribute lets us change the idProduct field
+ presented in the USB device descriptor by this xhci debug
+ device.
+ Value can only be changed while debug capability (DbC) is in
+ disabled state to prevent USB device descriptor change while
+ connected to a USB host.
+ The default value is 0x0010. It can be any 16-bit integer.
+
+What: /sys/bus/pci/drivers/xhci_hcd/.../dbc_bcdDevice
+Date: March 2023
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ This dbc_bcdDevice attribute lets us change the bcdDevice field
+ presented in the USB device descriptor by this xhci debug
+ device.
+ Value can only be changed while debug capability (DbC) is in
+ disabled state to prevent USB device descriptor change while
+ connected to a USB host.
+ The default value is 0x0010. (device rev 0.10)
+ It can be any 16-bit integer.
+
+What: /sys/bus/pci/drivers/xhci_hcd/.../dbc_bInterfaceProtocol
+Date: March 2023
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ This attribute lets us change the bInterfaceProtocol field
+ presented in the USB Interface descriptor by the xhci debug
+ device.
+ Value can only be changed while debug capability (DbC) is in
+ disabled state to prevent USB descriptor change while
+ connected to a USB host.
+ The default value is 1 (GNU Remote Debug command).
+ Other permissible value is 0 which is for vendor defined debug
+ target.
+
+What: /sys/bus/pci/drivers/xhci_hcd/.../dbc_poll_interval_ms
+Date: February 2024
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ This attribute adjust the polling interval used to check for
+ DbC events. Unit is milliseconds. Accepted values range from 0
+ up to 5000. The default value is 64 ms.
+ This polling interval is used while DbC is enabled but has no
+ active data transfers.
diff --git a/Documentation/ABI/testing/sysfs-bus-peci b/Documentation/ABI/testing/sysfs-bus-peci
new file mode 100644
index 000000000000..87454ec5d981
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-peci
@@ -0,0 +1,16 @@
+What: /sys/bus/peci/rescan
+Date: July 2021
+KernelVersion: 5.18
+Contact: Iwona Winiarska <iwona.winiarska@intel.com>
+Description:
+ Writing a non-zero value to this attribute will
+ initiate scan for PECI devices on all PECI controllers
+ in the system.
+
+What: /sys/bus/peci/devices/<controller_id>-<device_addr>/remove
+Date: July 2021
+KernelVersion: 5.18
+Contact: Iwona Winiarska <iwona.winiarska@intel.com>
+Description:
+ Writing a non-zero value to this attribute will
+ remove the PECI device and any of its children.
diff --git a/Documentation/ABI/testing/sysfs-bus-platform b/Documentation/ABI/testing/sysfs-bus-platform
index 5172a6124b27..c4dfe7355c2d 100644
--- a/Documentation/ABI/testing/sysfs-bus-platform
+++ b/Documentation/ABI/testing/sysfs-bus-platform
@@ -18,3 +18,39 @@ Description:
devices to opt-out of driver binding using a driver_override
name such as "none". Only a single driver may be specified in
the override, there is no support for parsing delimiters.
+
+What: /sys/bus/platform/devices/.../numa_node
+Date: June 2020
+Contact: Barry Song <song.bao.hua@hisilicon.com>
+Description:
+ This file contains the NUMA node to which the platform device
+ is attached. It won't be visible if the node is unknown. The
+ value comes from an ACPI _PXM method or a similar firmware
+ source. Initial users for this file would be devices like
+ arm smmu which are populated by arm64 acpi_iort.
+
+What: /sys/bus/platform/devices/.../msi_irqs/
+Date: August 2021
+Contact: Barry Song <song.bao.hua@hisilicon.com>
+Description:
+ The /sys/devices/.../msi_irqs directory contains a variable set
+ of files, with each file being named after a corresponding msi
+ irq vector allocated to that device.
+
+What: /sys/bus/platform/devices/.../msi_irqs/<N>
+Date: August 2021
+Contact: Barry Song <song.bao.hua@hisilicon.com>
+Description:
+ This attribute will show "msi" if <N> is a valid msi irq
+
+What: /sys/bus/platform/devices/.../modalias
+Description:
+ Same as MODALIAS in the uevent at device creation.
+
+ A platform device that it is exposed via devicetree uses:
+
+ - of:N`of node name`T`type`
+
+ Other platform devices use, instead:
+
+ - platform:`driver name`
diff --git a/Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro b/Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro
new file mode 100644
index 000000000000..fead760dcf77
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro
@@ -0,0 +1,325 @@
+What: /sys/bus/platform/devices/smpro-errmon.*/error_[core|mem|pcie|other]_[ce|ue]
+KernelVersion: 6.1
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RO) Contains the 48-byte Ampere (Vendor-Specific) Error Record printed
+ in hex format according to the table below:
+
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | Offset | Field | Size (byte) | Description |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 00 | Error Type | 1 | See :ref:`the table below <smpro-error-types>` for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 01 | Subtype | 1 | See :ref:`the table below <smpro-error-types>` for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 02 | Instance | 2 | See :ref:`the table below <smpro-error-types>` for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 04 | Error status | 4 | See ARM RAS specification for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 08 | Error Address | 8 | See ARM RAS specification for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 16 | Error Misc 0 | 8 | See ARM RAS specification for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 24 | Error Misc 1 | 8 | See ARM RAS specification for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 32 | Error Misc 2 | 8 | See ARM RAS specification for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+ | 40 | Error Misc 3 | 8 | See ARM RAS specification for details |
+ +--------+---------------+-------------+------------------------------------------------------------+
+
+ The table below defines the value of error types, their subtype, subcomponent and instance:
+
+ .. _smpro-error-types:
+
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | Error Group | Error Type | Sub type | Sub component | Instance |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | CPM (core) | 0 | 0 | Snoop-Logic | CPM # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | CPM (core) | 0 | 2 | Armv8 Core 1 | CPM # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 1 | ERR1 | MCU # \| SLOT << 11 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 2 | ERR2 | MCU # \| SLOT << 11 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 3 | ERR3 | MCU # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 4 | ERR4 | MCU # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 5 | ERR5 | MCU # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 6 | ERR6 | MCU # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | MCU (mem) | 1 | 7 | Link Error | MCU # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | Mesh (other) | 2 | 0 | Cross Point | X \| (Y << 5) \| NS <<11 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | Mesh (other) | 2 | 1 | Home Node(IO) | X \| (Y << 5) \| NS <<11 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | Mesh (other) | 2 | 2 | Home Node(Mem) | X \| (Y << 5) \| NS <<11 \| device<<12 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | Mesh (other) | 2 | 4 | CCIX Node | X \| (Y << 5) \| NS <<11 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | 2P Link (other) | 3 | 0 | N/A | Altra 2P Link # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 0 | ERR0 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 1 | ERR1 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 2 | ERR2 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 3 | ERR3 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 4 | ERR4 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 5 | ERR5 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 6 | ERR6 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 7 | ERR7 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 8 | ERR8 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 9 | ERR9 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 10 | ERR10 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 11 | ERR11 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 12 | ERR12 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | GIC (other) | 5 | 13-21 | ERR13 | RC # + 1 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TCU | 100 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU0 | 0 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU1 | 1 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU2 | 2 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU3 | 3 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU4 | 4 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU5 | 5 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU6 | 6 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU7 | 7 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU8 | 8 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMMU (other) | 6 | TBU9 | 9 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PCIe AER (pcie) | 7 | Root | 0 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PCIe AER (pcie) | 7 | Device | 1 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PCIe RC (pcie) | 8 | RCA HB | 0 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PCIe RC (pcie) | 8 | RCB HB | 1 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PCIe RC (pcie) | 8 | RASDP | 8 | RC # |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | OCM (other) | 9 | ERR0 | 0 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | OCM (other) | 9 | ERR1 | 1 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | OCM (other) | 9 | ERR2 | 2 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMpro (other) | 10 | ERR0 | 0 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMpro (other) | 10 | ERR1 | 1 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | SMpro (other) | 10 | MPA_ERR | 2 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PMpro (other) | 11 | ERR0 | 0 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PMpro (other) | 11 | ERR1 | 1 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+ | PMpro (other) | 11 | MPA_ERR | 2 | 0 |
+ +-----------------+------------+----------+----------------+----------------------------------------+
+
+ Example::
+
+ # cat error_other_ue
+ 880807001e004010401040101500000001004010401040100c0000000000000000000000000000000000000000000000
+
+ The detail of each sysfs entries is as below:
+
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Error | Sysfs entry | Description (when triggered) |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Core's CE | /sys/bus/platform/devices/smpro-errmon.*/error_core_ce | Core has CE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Core's UE | /sys/bus/platform/devices/smpro-errmon.*/error_core_ue | Core has UE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Memory's CE | /sys/bus/platform/devices/smpro-errmon.*/error_mem_ce | Memory has CE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Memory's UE | /sys/bus/platform/devices/smpro-errmon.*/error_mem_ue | Memory has UE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | PCIe's CE | /sys/bus/platform/devices/smpro-errmon.*/error_pcie_ce | any PCIe controller has CE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | PCIe's UE | /sys/bus/platform/devices/smpro-errmon.*/error_pcie_ue | any PCIe controller has UE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Other's CE | /sys/bus/platform/devices/smpro-errmon.*/error_other_ce | any other CE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+ | Other's UE | /sys/bus/platform/devices/smpro-errmon.*/error_other_ue | any other UE error |
+ +-------------+---------------------------------------------------------+----------------------------------+
+
+ UE: Uncorrect-able Error
+ CE: Correct-able Error
+
+ For details, see section `3.3 Ampere (Vendor-Specific) Error Record Formats,
+ Altra Family RAS Supplement`.
+
+
+What: /sys/bus/platform/devices/smpro-errmon.*/overflow_[core|mem|pcie|other]_[ce|ue]
+KernelVersion: 6.1
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RO) Return the overflow status of each type HW error reported:
+
+ - 0 : No overflow
+ - 1 : There is an overflow and the oldest HW errors are dropped
+
+ The detail of each sysfs entries is as below:
+
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Overflow | Sysfs entry | Description |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Core's CE | /sys/bus/platform/devices/smpro-errmon.*/overflow_core_ce | Core CE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Core's UE | /sys/bus/platform/devices/smpro-errmon.*/overflow_core_ue | Core UE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Memory's CE | /sys/bus/platform/devices/smpro-errmon.*/overflow_mem_ce | Memory CE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Memory's UE | /sys/bus/platform/devices/smpro-errmon.*/overflow_mem_ue | Memory UE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | PCIe's CE | /sys/bus/platform/devices/smpro-errmon.*/overflow_pcie_ce | any PCIe controller CE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | PCIe's UE | /sys/bus/platform/devices/smpro-errmon.*/overflow_pcie_ue | any PCIe controller UE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Other's CE | /sys/bus/platform/devices/smpro-errmon.*/overflow_other_ce| any other CE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+ | Other's UE | /sys/bus/platform/devices/smpro-errmon.*/overflow_other_ue| other UE error overflow |
+ +-------------+-----------------------------------------------------------+---------------------------------------+
+
+ where:
+
+ - UE: Uncorrect-able Error
+ - CE: Correct-able Error
+
+What: /sys/bus/platform/devices/smpro-errmon.*/[error|warn]_[smpro|pmpro]
+KernelVersion: 6.1
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RO) Contains the internal firmware error/warning printed as hex format.
+
+ The detail of each sysfs entries is as below:
+
+ +---------------+------------------------------------------------------+--------------------------+
+ | Error | Sysfs entry | Description |
+ +---------------+------------------------------------------------------+--------------------------+
+ | SMpro error | /sys/bus/platform/devices/smpro-errmon.*/error_smpro | system has SMpro error |
+ +---------------+------------------------------------------------------+--------------------------+
+ | SMpro warning | /sys/bus/platform/devices/smpro-errmon.*/warn_smpro | system has SMpro warning |
+ +---------------+------------------------------------------------------+--------------------------+
+ | PMpro error | /sys/bus/platform/devices/smpro-errmon.*/error_pmpro | system has PMpro error |
+ +---------------+------------------------------------------------------+--------------------------+
+ | PMpro warning | /sys/bus/platform/devices/smpro-errmon.*/warn_pmpro | system has PMpro warning |
+ +---------------+------------------------------------------------------+--------------------------+
+
+ For details, see section `5.10 RAS Internal Error Register Definitions,
+ Altra Family Soc BMC Interface Specification`.
+
+What: /sys/bus/platform/devices/smpro-errmon.*/event_[vrd_warn_fault|vrd_hot|dimm_hot|dimm_2x_refresh]
+KernelVersion: 6.1 (event_[vrd_warn_fault|vrd_hot|dimm_hot]), 6.4 (event_dimm_2x_refresh)
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RO) Contains the detail information in case of VRD/DIMM warning/hot events
+ in hex format as below::
+
+ AAAA
+
+ where:
+
+ - ``AAAA``: The event detail information data
+
+ The detail of each sysfs entries is as below:
+
+ +---------------+---------------------------------------------------------------+---------------------+
+ | Event | Sysfs entry | Description |
+ +---------------+---------------------------------------------------------------+---------------------+
+ | VRD HOT | /sys/bus/platform/devices/smpro-errmon.*/event_vrd_hot | VRD Hot |
+ +---------------+---------------------------------------------------------------+---------------------+
+ | VR Warn/Fault | /sys/bus/platform/devices/smpro-errmon.*/event_vrd_warn_fault | VR Warning or Fault |
+ +---------------+---------------------------------------------------------------+---------------------+
+ | DIMM HOT | /sys/bus/platform/devices/smpro-errmon.*/event_dimm_hot | DIMM Hot |
+ +---------------+---------------------------------------------------------------+---------------------+
+ | DIMM 2X | /sys/bus/platform/devices/smpro-errmon.*/event_dimm_2x_refresh| DIMM 2x refresh rate|
+ | REFRESH RATE | | event in high temp |
+ +---------------+---------------------------------------------------------------+---------------------+
+
+ For more details, see section `5.7 GPI Status Registers and 5.9 Memory Error Register Definitions,
+ Altra Family Soc BMC Interface Specification`.
+
+What: /sys/bus/platform/devices/smpro-errmon.*/event_dimm[0-15]_syndrome
+KernelVersion: 6.4
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RO) The sysfs returns the 2-byte DIMM failure syndrome data for slot
+ 0-15 if it failed to initialize.
+
+ For more details, see section `5.11 Boot Stage Register Definitions,
+ Altra Family Soc BMC Interface Specification`.
+
+What: /sys/bus/platform/devices/smpro-misc.*/boot_progress
+KernelVersion: 6.1
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RO) Contains the boot stages information in hex as format below::
+
+ AABBCCCCCCCC
+
+ where:
+
+ - ``AA`` : The boot stages
+
+ - 00: SMpro firmware booting
+ - 01: PMpro firmware booting
+ - 02: ATF BL1 firmware booting
+ - 03: DDR initialization
+ - 04: DDR training report status
+ - 05: ATF BL2 firmware booting
+ - 06: ATF BL31 firmware booting
+ - 07: ATF BL32 firmware booting
+ - 08: UEFI firmware booting
+ - 09: OS booting
+
+ - ``BB`` : Boot status
+
+ - 00: Not started
+ - 01: Started
+ - 02: Completed without error
+ - 03: Failed.
+
+ - ``CCCCCCCC``: Boot status information defined for each boot stages
+
+ For details, see section `5.11 Boot Stage Register Definitions`
+ and section `6. Processor Boot Progress Codes, Altra Family Soc BMC
+ Interface Specification`.
+
+
+What: /sys/bus/platform/devices/smpro-misc*/soc_power_limit
+KernelVersion: 6.1
+Contact: Quan Nguyen <quan@os.amperecomputing.com>
+Description:
+ (RW) Contains the desired SoC power limit in Watt.
+ Writes to this sysfs set the desired SoC power limit (W).
+ Reads from this register return the current SoC power limit (W).
+ The value ranges:
+
+ - Minimum: 120 W
+ - Maximum: Socket TDP power
diff --git a/Documentation/ABI/testing/sysfs-bus-platform-devices-occ-hwmon b/Documentation/ABI/testing/sysfs-bus-platform-devices-occ-hwmon
new file mode 100644
index 000000000000..b24d7ab0278f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-platform-devices-occ-hwmon
@@ -0,0 +1,13 @@
+What: /sys/bus/platform/devices/occ-hwmon.X/ffdc
+KernelVersion: 5.15
+Contact: eajames@linux.ibm.com
+Description:
+ Contains the First Failure Data Capture from the SBEFIFO
+ hardware, if there is any from a previous transfer. Otherwise,
+ the file is empty. The data is cleared when it's been
+ completely read by a user. As the name suggests, only the data
+ from the first error is saved, until it's cleared upon read. The OCC hwmon driver, running on
+ a Baseboard Management Controller (BMC), communicates with
+ POWER9 and up processors over the Self-Boot Engine (SBE) FIFO.
+ In many error conditions, the SBEFIFO will return error data
+ indicating the type of error and system state, etc.
diff --git a/Documentation/ABI/testing/sysfs-bus-platform-drivers-amd_x3d_vcache b/Documentation/ABI/testing/sysfs-bus-platform-drivers-amd_x3d_vcache
new file mode 100644
index 000000000000..ac3431736f5c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-platform-drivers-amd_x3d_vcache
@@ -0,0 +1,12 @@
+What: /sys/bus/platform/drivers/amd_x3d_vcache/AMDI0101:00/amd_x3d_mode
+Date: November 2024
+KernelVersion: 6.13
+Contact: Basavaraj Natikar <Basavaraj.Natikar@amd.com>
+Description: (RW) AMD 3D V-Cache optimizer allows users to switch CPU core
+ rankings dynamically.
+
+ This file switches between these two modes:
+ - "frequency" cores within the faster CCD are prioritized before
+ those in the slower CCD.
+ - "cache" cores within the larger L3 CCD are prioritized before
+ those in the smaller L3 CCD.
diff --git a/Documentation/ABI/testing/sysfs-bus-platform-onboard-usb-dev b/Documentation/ABI/testing/sysfs-bus-platform-onboard-usb-dev
new file mode 100644
index 000000000000..b06a48c3c85a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-platform-onboard-usb-dev
@@ -0,0 +1,9 @@
+What: /sys/bus/platform/devices/<dev>/always_powered_in_suspend
+Date: June 2022
+KernelVersion: 5.20
+Contact: Matthias Kaehlcke <matthias@kaehlcke.net>
+ linux-usb@vger.kernel.org
+Description:
+ (RW) Controls whether the USB hub remains always powered
+ during system suspend or not. This attribute is not
+ available for non-hub devices.
diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio b/Documentation/ABI/testing/sysfs-bus-rapidio
new file mode 100644
index 000000000000..f8b6728dac10
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-rapidio
@@ -0,0 +1,201 @@
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>
+Description:
+ For each RapidIO device, the RapidIO subsystem creates files in
+ an individual subdirectory with the following name format of
+ device_name "nn:d:iiii", where:
+
+ ==== ========================================================
+ nn two-digit hexadecimal ID of RapidIO network where the
+ device resides
+ d device type: 'e' - for endpoint or 's' - for switch
+ iiii four-digit device destID for endpoints, or switchID for
+ switches
+ ==== ========================================================
+
+ For example, below is a list of device directories that
+ represents a typical RapidIO network with one switch, one host,
+ and two agent endpoints, as it is seen by the enumerating host
+ (with destID = 1)::
+
+ /sys/bus/rapidio/devices/00:e:0000
+ /sys/bus/rapidio/devices/00:e:0002
+ /sys/bus/rapidio/devices/00:s:0001
+
+ NOTE:
+ An enumerating or discovering endpoint does not create a
+ sysfs entry for itself, this is why an endpoint with destID=1
+ is not shown in the list.
+
+Attributes Common for All RapidIO Devices
+-----------------------------------------
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/did
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns the device identifier
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/vid
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns the device vendor identifier
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/device_rev
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns the device revision level
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/asm_did
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns identifier for the assembly containing the device
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/asm_rev
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns revision level of the assembly containing the
+ device
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/asm_vid
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns vendor identifier of the assembly containing the
+ device
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/destid
+Date: Mar, 2011
+KernelVersion: v2.6.3
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns device destination ID assigned by the enumeration
+ routine
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/lprev
+Date: Mar, 2011
+KernelVersion: v2.6.39
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns name of previous device (switch) on the path to the
+ device that that owns this attribute
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/modalias
+Date: Jul, 2013
+KernelVersion: v3.11
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns the device modalias
+
+What: /sys/bus/rapidio/devices/<nn>:<d>:<iiii>/config
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RW) Binary attribute to read from and write to the device
+ configuration registers using the RapidIO maintenance
+ transactions. This attribute is similar in behaviour to the
+ "config" attribute of PCI devices and provides an access to the
+ RapidIO device registers using standard file read and write
+ operations.
+
+RapidIO Switch Device Attributes
+--------------------------------
+
+RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports
+common and device-specific sysfs attributes for switches. Because switches are
+integrated into the RapidIO subsystem, it offers a method to create
+device-specific sysfs attributes by specifying a callback function that may be
+set by the switch initialization routine during enumeration or discovery
+process.
+
+What: /sys/bus/rapidio/devices/<nn>:<s>:<iiii>/routes
+Date: Nov, 2005
+KernelVersion: v2.6.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) reports switch routing information in "destID port" format.
+ This attribute reports only valid routing table entries, one
+ line for each entry.
+
+What: /sys/bus/rapidio/devices/<nn>:<s>:<iiii>/destid
+Date: Mar, 2011
+KernelVersion: v2.6.3
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) device destination ID of the associated device that defines
+ a route to the switch
+
+What: /sys/bus/rapidio/devices/<nn>:<s>:<iiii>/hopcount
+Date: Mar, 2011
+KernelVersion: v2.6.39
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) number of hops on the path to the switch
+
+What: /sys/bus/rapidio/devices/<nn>:<s>:<iiii>/lnext
+Date: Mar, 2011
+KernelVersion: v2.6.39
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) returns names of devices linked to the switch except one of
+ a device linked to the ingress port (reported as "lprev"). This
+ is an array names with number of lines equal to number of ports
+ in switch. If a switch port has no attached device, returns
+ "null" instead of a device name.
+
+Device-specific Switch Attributes
+---------------------------------
+
+IDT_GEN2-
+
+What: /sys/bus/rapidio/devices/<nn>:<s>:<iiii>/errlog
+Date: Oct, 2010
+KernelVersion: v2.6.37
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) reads contents of device error log until it is empty.
+
+RapidIO Bus Attributes
+----------------------
+
+What: /sys/bus/rapidio/scan
+Date: May, 2013
+KernelVersion: v3.11
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (WO) Allows to trigger enumeration discovery process from user
+ space. To initiate an enumeration or discovery process on
+ specific mport device, a user needs to write mport_ID (not
+ RapidIO destination ID) into this file. The mport_ID is a
+ sequential number (0 ... RIO_MAX_MPORTS) assigned to the mport
+ device. For example, for a machine with a single RapidIO
+ controller, mport_ID for that controller always will be 0. To
+ initiate RapidIO enumeration/discovery on all available mports a
+ user must write '-1' (or RIO_MPORT_ANY) into this attribute
+ file.
diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd
index 2ddd680929d8..417a2fe21be1 100644
--- a/Documentation/ABI/testing/sysfs-bus-rbd
+++ b/Documentation/ABI/testing/sysfs-bus-rbd
@@ -1,98 +1,173 @@
-What: /sys/bus/rbd/
-Date: November 2010
-Contact: Yehuda Sadeh <yehuda@newdream.net>,
- Sage Weil <sage@newdream.net>
+What: /sys/bus/rbd/add
+Date: Oct, 2010
+KernelVersion: v2.6.37
+Contact: Sage Weil <sage@newdream.net>
Description:
+ (WO) Add rbd block device.
-Being used for adding and removing rbd block devices.
+ Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
-Usage: <mon ip addr> <options> <pool name> <rbd image name> [snap name]
+ Example::
- $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
+ $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
-The snapshot name can be "-" or omitted to map the image read/write. A <dev-id>
-will be assigned for any registered block device. If snapshot is used, it will
-be mapped read-only.
+ The snapshot name can be "-" or omitted to map the image
+ read/write. A <dev-id> will be assigned for any registered block
+ device. If snapshot is used, it will be mapped read-only.
-Removal of a device:
- $ echo <dev-id> > /sys/bus/rbd/remove
+What: /sys/bus/rbd/remove
+Date: Oct, 2010
+KernelVersion: v2.6.37
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (WO) Remove rbd block device.
+
+ Usage: <dev-id> [force]
+
+ Example::
+
+ $ echo 2 > /sys/bus/rbd/remove
+
+ Optional "force" argument which when passed will wait for
+ running requests and then unmap the image. Requests sent to the
+ driver after initiating the removal will be failed. (August
+ 2016, since 4.9.)
+
What: /sys/bus/rbd/add_single_major
-Date: December 2013
-KernelVersion: 3.14
-Contact: Sage Weil <sage@inktank.com>
-Description: Available only if rbd module is inserted with single_major
+Date: Dec, 2013
+KernelVersion: v3.14
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (WO) Available only if rbd module is inserted with single_major
parameter set to true.
- Usage is the same as for /sys/bus/rbd/add. If present,
+
+ Usage is the same as for /sys/bus/rbd/add. If present, this
should be used instead of the latter: any attempts to use
- /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is
- available will fail for backwards compatibility reasons.
+ /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available
+ will fail for backwards compatibility reasons.
+
What: /sys/bus/rbd/remove_single_major
-Date: December 2013
-KernelVersion: 3.14
-Contact: Sage Weil <sage@inktank.com>
-Description: Available only if rbd module is inserted with single_major
+Date: Dec, 2013
+KernelVersion: v3.14
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (WO) Available only if rbd module is inserted with single_major
parameter set to true.
- Usage is the same as for /sys/bus/rbd/remove. If present,
+
+ Usage is the same as for /sys/bus/rbd/remove. If present, this
should be used instead of the latter: any attempts to use
/sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is
available will fail for backwards compatibility reasons.
-Entries under /sys/bus/rbd/devices/<dev-id>/
---------------------------------------------
-
-client_id
-
- The ceph unique client id that was assigned for this specific session.
-features
+What: /sys/bus/rbd/supported_features
+Date: Mar, 2017
+KernelVersion: v4.11
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (RO) Displays the features supported by the rbd module so that
+ userspace can generate meaningful error messages and spell out
+ unsupported features that need to be disabled.
+
+
+What: /sys/bus/rbd/devices/<dev-id>/size
+What: /sys/bus/rbd/devices/<dev-id>/major
+What: /sys/bus/rbd/devices/<dev-id>/client_id
+What: /sys/bus/rbd/devices/<dev-id>/pool
+What: /sys/bus/rbd/devices/<dev-id>/name
+What: /sys/bus/rbd/devices/<dev-id>/refresh
+What: /sys/bus/rbd/devices/<dev-id>/current_snap
+Date: Oct, 2010
+KernelVersion: v2.6.37
+Contact: Sage Weil <sage@newdream.net>
+Description:
- A hexadecimal encoding of the feature bits for this image.
+ ============== ================================================
+ size (RO) The size (in bytes) of the mapped block
+ device.
-major
+ major (RO) The block device major number.
- The block device major number.
+ client_id (RO) The ceph unique client id that was assigned
+ for this specific session.
-minor
+ pool (RO) The name of the storage pool where this rbd
+ image resides. An rbd image name is unique
+ within its pool.
- The block device minor number. (December 2013, since 3.14.)
+ name (RO) The name of the rbd image.
-name
+ refresh (WO) Writing to this file will reread the image
+ header data and set all relevant data structures
+ accordingly.
- The name of the rbd image.
+ current_snap (RO) The current snapshot for which the device
+ is mapped.
+ ============== ================================================
-image_id
- The unique id for the rbd image. (For rbd image format 1
- this is empty.)
+What: /sys/bus/rbd/devices/<dev-id>/pool_id
+Date: Jul, 2012
+KernelVersion: v3.6
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (RO) The unique identifier for the rbd image's pool. This is a
+ permanent attribute of the pool. A pool's id will never change.
-pool
- The name of the storage pool where this rbd image resides.
- An rbd image name is unique within its pool.
+What: /sys/bus/rbd/devices/<dev-id>/image_id
+What: /sys/bus/rbd/devices/<dev-id>/features
+Date: Oct, 2012
+KernelVersion: v3.7
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ ========= ===============================================
+ image_id (RO) The unique id for the rbd image. (For rbd
+ image format 1 this is empty.)
-pool_id
+ features (RO) A hexadecimal encoding of the feature bits
+ for this image.
+ ========= ===============================================
- The unique identifier for the rbd image's pool. This is
- a permanent attribute of the pool. A pool's id will never
- change.
-size
+What: /sys/bus/rbd/devices/<dev-id>/parent
+Date: Nov, 2012
+KernelVersion: v3.8
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (RO) Information identifying the chain of parent images in a
+ layered rbd image. Entries are separated by empty lines.
- The size (in bytes) of the mapped block device.
-refresh
+What: /sys/bus/rbd/devices/<dev-id>/minor
+Date: Dec, 2013
+KernelVersion: v3.14
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ (RO) The block device minor number.
- Writing to this file will reread the image header data and set
- all relevant datastructures accordingly.
-current_snap
+What: /sys/bus/rbd/devices/<dev-id>/snap_id
+What: /sys/bus/rbd/devices/<dev-id>/config_info
+What: /sys/bus/rbd/devices/<dev-id>/cluster_fsid
+What: /sys/bus/rbd/devices/<dev-id>/client_addr
+Date: Aug, 2016
+KernelVersion: v4.9
+Contact: Sage Weil <sage@newdream.net>
+Description:
+ ============ ================================================
+ snap_id (RO) The current snapshot's id.
- The current snapshot for which the device is mapped.
+ config_info (RO) The string written into
+ /sys/bus/rbd/add{,_single_major}.
-parent
+ cluster_fsid (RO) The ceph cluster UUID.
- Information identifying the chain of parent images in a layered rbd
- image. Entries are separated by empty lines.
+ client_addr (RO) The ceph unique client
+ entity_addr_t (address + nonce). The format is
+ <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
+ '[1:2:3:4:5:6:7:8]:1234/5678'.
+ ============ ================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-rpmsg b/Documentation/ABI/testing/sysfs-bus-rpmsg
index 189e419a5a2d..990fcc420935 100644
--- a/Documentation/ABI/testing/sysfs-bus-rpmsg
+++ b/Documentation/ABI/testing/sysfs-bus-rpmsg
@@ -73,3 +73,23 @@ Description:
This sysfs entry tells us whether the channel is a local
server channel that is announced (values are either
true or false).
+
+What: /sys/bus/rpmsg/devices/.../driver_override
+Date: April 2018
+KernelVersion: 4.18
+Contact: Bjorn Andersson <bjorn.andersson@linaro.org>
+Description:
+ Every rpmsg device is a communication channel with a remote
+ processor. Channels are identified by a textual name (see
+ /sys/bus/rpmsg/devices/.../name above) and have a local
+ ("source") rpmsg address, and remote ("destination") rpmsg
+ address.
+
+ The listening entity (or client) which communicates with a
+ remote processor is referred as rpmsg driver. The rpmsg device
+ and rpmsg driver are matched based on rpmsg device name and
+ rpmsg driver ID table.
+
+ This sysfs entry allows the rpmsg driver for a rpmsg device
+ to be specified which will override standard OF, ID table
+ and name matching.
diff --git a/Documentation/ABI/testing/sysfs-bus-siox b/Documentation/ABI/testing/sysfs-bus-siox
new file mode 100644
index 000000000000..50e80238f30d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-siox
@@ -0,0 +1,90 @@
+What: /sys/bus/siox/devices/siox-X/active
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ On reading represents the current state of the bus. If it
+ contains a "0" the bus is stopped and connected devices are
+ expected to not do anything because their watchdog triggered.
+ When the file contains a "1" the bus is operated and periodically
+ does a push-pull cycle to write and read data from the
+ connected devices.
+
+ When writing a "0" or "1" the bus moves to the described state.
+
+What: /sys/bus/siox/devices/siox-X/device_add
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Write-only file. Write
+
+ <type> <inbytes> <outbytes> <statustype>
+
+ to add a new device dynamically. <type> is the name that is used to match
+ to a driver (similar to the platform bus). <inbytes> and <outbytes> define
+ the length of the input and output shift register in bytes respectively.
+
+ <statustype> defines the 4 bit device type that is check to identify connection
+ problems.
+
+ The new device is added to the end of the existing chain.
+
+What: /sys/bus/siox/devices/siox-X/device_remove
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Write-only file. A single write removes the last device in the siox chain.
+
+What: /sys/bus/siox/devices/siox-X/poll_interval_ns
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Defines the interval between two poll cycles in nano seconds.
+ Note this is rounded to jiffies on writing. On reading the current value
+ is returned.
+
+What: /sys/bus/siox/devices/siox-X-Y/connected
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e.
+ communication with it is not ensured. "1" signals a working connection.
+
+What: /sys/bus/siox/devices/siox-X-Y/inbytes
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Read-only value reporting the inbytes value provided to siox-X/device_add
+
+What: /sys/bus/siox/devices/siox-X-Y/status_errors
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Counts the number of time intervals when the read status byte doesn't yield the
+ expected value.
+
+What: /sys/bus/siox/devices/siox-X-Y/type
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Read-only value reporting the type value provided to siox-X/device_add.
+
+What: /sys/bus/siox/devices/siox-X-Y/watchdog
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Read-only value reporting if the watchdog of the siox device is
+ active. "0" means the watchdog is not active and the device is expected to
+ be operational. "1" means the watchdog keeps the device in reset.
+
+What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Read-only value reporting the number to time intervals when the
+ watchdog was active.
+
+What: /sys/bus/siox/devices/siox-X-Y/outbytes
+KernelVersion: 4.16
+Contact: Thorsten Scherer <t.scherer@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Description:
+ Read-only value reporting the outbytes value provided to siox-X/device_add.
diff --git a/Documentation/ABI/testing/sysfs-bus-soundwire-master b/Documentation/ABI/testing/sysfs-bus-soundwire-master
new file mode 100644
index 000000000000..d2342911ffbb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-soundwire-master
@@ -0,0 +1,23 @@
+What: /sys/bus/soundwire/devices/sdw-master-<N>/revision
+ /sys/bus/soundwire/devices/sdw-master-<N>/clk_stop_modes
+ /sys/bus/soundwire/devices/sdw-master-<N>/clk_freq
+ /sys/bus/soundwire/devices/sdw-master-<N>/clk_gears
+ /sys/bus/soundwire/devices/sdw-master-<N>/default_col
+ /sys/bus/soundwire/devices/sdw-master-<N>/default_frame_rate
+ /sys/bus/soundwire/devices/sdw-master-<N>/default_row
+ /sys/bus/soundwire/devices/sdw-master-<N>/dynamic_shape
+ /sys/bus/soundwire/devices/sdw-master-<N>/err_threshold
+ /sys/bus/soundwire/devices/sdw-master-<N>/max_clk_freq
+
+Date: April 2020
+
+Contact: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
+ Bard Liao <yung-chuan.liao@linux.intel.com>
+ Vinod Koul <vkoul@kernel.org>
+
+Description: SoundWire Master-N DisCo properties.
+ These properties are defined by MIPI DisCo Specification
+ for SoundWire. They define various properties of the Master
+ and are used by the bus to configure the Master. clk_stop_modes
+ is a bitmask for simplifications and combines the
+ clock-stop-mode0 and clock-stop-mode1 properties.
diff --git a/Documentation/ABI/testing/sysfs-bus-soundwire-slave b/Documentation/ABI/testing/sysfs-bus-soundwire-slave
new file mode 100644
index 000000000000..fbf55834dfee
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-soundwire-slave
@@ -0,0 +1,109 @@
+What: /sys/bus/soundwire/devices/sdw:.../status
+ /sys/bus/soundwire/devices/sdw:.../device_number
+
+Date: September 2020
+
+Contact: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
+ Bard Liao <yung-chuan.liao@linux.intel.com>
+ Vinod Koul <vkoul@kernel.org>
+
+Description: SoundWire Slave status
+
+ These properties report the Slave status, e.g. if it
+ is UNATTACHED or not, and in the latter case show the
+ device_number. This status information is useful to
+ detect devices exposed by platform firmware but not
+ physically present on the bus, and conversely devices
+ not exposed in platform firmware but enumerated.
+
+What: /sys/bus/soundwire/devices/sdw:.../dev-properties/mipi_revision
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/wake_capable
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/test_mode_capable
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/clk_stop_mode1
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/simple_clk_stop_capable
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/clk_stop_timeout
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/ch_prep_timeout
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/reset_behave
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/high_PHY_capable
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/paging_support
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/bank_delay_support
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/p15_behave
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/master_count
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/source_ports
+ /sys/bus/soundwire/devices/sdw:.../dev-properties/sink_ports
+
+Date: May 2020
+
+Contact: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
+ Bard Liao <yung-chuan.liao@linux.intel.com>
+ Vinod Koul <vkoul@kernel.org>
+
+Description: SoundWire Slave DisCo properties.
+ These properties are defined by MIPI DisCo Specification
+ for SoundWire. They define various properties of the
+ SoundWire Slave and are used by the bus to configure
+ the Slave
+
+
+What: /sys/bus/soundwire/devices/sdw:.../dp0/max_word
+ /sys/bus/soundwire/devices/sdw:.../dp0/min_word
+ /sys/bus/soundwire/devices/sdw:.../dp0/words
+ /sys/bus/soundwire/devices/sdw:.../dp0/BRA_flow_controlled
+ /sys/bus/soundwire/devices/sdw:.../dp0/simple_ch_prep_sm
+ /sys/bus/soundwire/devices/sdw:.../dp0/imp_def_interrupts
+
+Date: May 2020
+
+Contact: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
+ Bard Liao <yung-chuan.liao@linux.intel.com>
+ Vinod Koul <vkoul@kernel.org>
+
+Description: SoundWire Slave Data Port-0 DisCo properties.
+ These properties are defined by MIPI DisCo Specification
+ for the SoundWire. They define various properties of the
+ Data port 0 are used by the bus to configure the Data Port 0.
+
+
+What: /sys/bus/soundwire/devices/sdw:.../dp<N>_src/max_word
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/min_word
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/words
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/type
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/max_grouping
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/simple_ch_prep_sm
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/ch_prep_timeout
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/imp_def_interrupts
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/min_ch
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/max_ch
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/channels
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/ch_combinations
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/max_async_buffer
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/block_pack_mode
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_src/port_encoding
+
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/max_word
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/min_word
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/words
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/type
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/max_grouping
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/simple_ch_prep_sm
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/ch_prep_timeout
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/imp_def_interrupts
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/min_ch
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/max_ch
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/channels
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/ch_combinations
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/max_async_buffer
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/block_pack_mode
+ /sys/bus/soundwire/devices/sdw:.../dp<N>_sink/port_encoding
+
+Date: May 2020
+
+Contact: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
+ Bard Liao <yung-chuan.liao@linux.intel.com>
+ Vinod Koul <vkoul@kernel.org>
+
+Description: SoundWire Slave Data Source/Sink Port-N DisCo properties.
+ These properties are defined by MIPI DisCo Specification
+ for SoundWire. They define various properties of the
+ Source/Sink Data port N and are used by the bus to configure
+ the Data Port N.
diff --git a/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor b/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor
new file mode 100644
index 000000000000..9ed5582ddea2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-spi-devices-spi-nor
@@ -0,0 +1,40 @@
+What: /sys/bus/spi/devices/.../spi-nor/jedec_id
+Date: April 2021
+KernelVersion: 5.14
+Contact: linux-mtd@lists.infradead.org
+Description: (RO) The JEDEC ID of the SPI NOR flash as reported by the
+ flash device.
+
+ The attribute is not present if the flash doesn't support
+ the "Read JEDEC ID" command (9Fh). This is the case for
+ non-JEDEC compliant flashes.
+
+What: /sys/bus/spi/devices/.../spi-nor/manufacturer
+Date: April 2021
+KernelVersion: 5.14
+Contact: linux-mtd@lists.infradead.org
+Description: (RO) Manufacturer of the SPI NOR flash.
+
+ The attribute is not present if the flash device isn't
+ known to the kernel and is only probed by its SFDP
+ tables.
+
+What: /sys/bus/spi/devices/.../spi-nor/partname
+Date: April 2021
+KernelVersion: 5.14
+Contact: linux-mtd@lists.infradead.org
+Description: (RO) Part name of the SPI NOR flash.
+
+ The attribute is optional. User space should not rely on
+ it to be present or even correct. Instead, user space
+ should read the jedec_id attribute.
+
+What: /sys/bus/spi/devices/.../spi-nor/sfdp
+Date: April 2021
+KernelVersion: 5.14
+Contact: linux-mtd@lists.infradead.org
+Description: (RO) This attribute is only present if the SPI NOR flash
+ device supports the "Read SFDP" command (5Ah).
+
+ If present, it contains the complete SFDP (serial flash
+ discoverable parameters) binary data of the flash.
diff --git a/Documentation/ABI/testing/sysfs-bus-surface_aggregator-tabletsw b/Documentation/ABI/testing/sysfs-bus-surface_aggregator-tabletsw
new file mode 100644
index 000000000000..74cd9d754e60
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-surface_aggregator-tabletsw
@@ -0,0 +1,57 @@
+What: /sys/bus/surface_aggregator/devices/01:0e:01:00:01/state
+Date: July 2022
+KernelVersion: 5.20
+Contact: Maximilian Luz <luzmaximilian@gmail.com>
+Description:
+ This attribute returns a string with the current type-cover
+ or device posture, as indicated by the embedded controller.
+ Currently returned posture states are:
+
+ - "disconnected": The type-cover has been disconnected.
+
+ - "closed": The type-cover has been folded closed and lies on
+ top of the display.
+
+ - "laptop": The type-cover is open and in laptop-mode, i.e.,
+ ready for normal use.
+
+ - "folded-canvas": The type-cover has been folded back
+ part-ways, but does not lie flush with the back side of the
+ device. In general, this means that the kick-stand is used
+ and extended atop of the cover.
+
+ - "folded-back": The type cover has been fully folded back and
+ lies flush with the back side of the device.
+
+ - "<unknown>": The current state is unknown to the driver, for
+ example due to newer as-of-yet unsupported hardware.
+
+ New states may be introduced with new hardware. Users therefore
+ must not rely on this list of states being exhaustive and
+ gracefully handle unknown states.
+
+What: /sys/bus/surface_aggregator/devices/01:26:01:00:01/state
+Date: July 2022
+KernelVersion: 5.20
+Contact: Maximilian Luz <luzmaximilian@gmail.com>
+Description:
+ This attribute returns a string with the current device posture, as indicated by the embedded controller. Currently
+ returned posture states are:
+
+ - "closed": The lid of the device is closed.
+
+ - "laptop": The lid of the device is opened and the device
+ operates as a normal laptop.
+
+ - "slate": The screen covers the keyboard or has been flipped
+ back and the device operates mainly based on touch input.
+
+ - "tablet": The device operates as tablet and exclusively
+ relies on touch input (or external peripherals).
+
+ - "<unknown>": The current state is unknown to the driver, for
+ example due to newer as-of-yet unsupported hardware.
+
+ New states may be introduced with new hardware. Users therefore
+ must not rely on this list of states being exhaustive and
+ gracefully handle unknown states.
diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt
new file mode 100644
index 000000000000..221b6c75ed93
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt
@@ -0,0 +1,370 @@
+What: /sys/bus/thunderbolt/devices/.../domainX/boot_acl
+Date: Jun 2018
+KernelVersion: 4.17
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Holds a comma separated list of device unique_ids that
+ are allowed to be connected automatically during system
+ startup (e.g boot devices). The list always contains
+ maximum supported number of unique_ids where unused
+ entries are empty. This allows the userspace software
+ to determine how many entries the controller supports.
+ If there are multiple controllers, each controller has
+ its own ACL list and size may be different between the
+ controllers.
+
+ System BIOS may have an option "Preboot ACL" or similar
+ that needs to be selected before this list is taken into
+ consideration.
+
+ Software always updates a full list in each write.
+
+ If a device is authorized automatically during boot its
+ boot attribute is set to 1.
+
+What: /sys/bus/thunderbolt/devices/.../domainX/deauthorization
+Date: May 2021
+KernelVersion: 5.12
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute tells whether the system supports
+ de-authorization of devices. Value of 1 means user can
+ de-authorize PCIe tunnel by writing 0 to authorized
+ attribute under each device.
+
+What: /sys/bus/thunderbolt/devices/.../domainX/iommu_dma_protection
+Date: Mar 2019
+KernelVersion: 4.21
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute tells whether the system uses IOMMU
+ for DMA protection. Value of 1 means IOMMU is used 0 means
+ it is not (DMA protection is solely based on Thunderbolt
+ security levels).
+
+What: /sys/bus/thunderbolt/devices/.../domainX/security
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute holds current Thunderbolt security level
+ set by the system BIOS. Possible values are:
+
+ ======= ==================================================
+ none All devices are automatically authorized
+ user Devices are only authorized based on writing
+ appropriate value to the authorized attribute
+ secure Require devices that support secure connect at
+ minimum. User needs to authorize each device.
+ dponly Automatically tunnel Display port (and USB). No
+ PCIe tunnels are created.
+ usbonly Automatically tunnel USB controller of the
+ connected Thunderbolt dock (and Display Port). All
+ PCIe links downstream of the dock are removed.
+ nopcie USB4 system where PCIe tunneling is disabled from
+ the BIOS.
+ ======= ==================================================
+
+What: /sys/bus/thunderbolt/devices/.../authorized
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute is used to authorize Thunderbolt devices
+ after they have been connected. If the device is not
+ authorized, no PCIe devices are available to the system.
+
+ Contents of this attribute will be 0 when the device is not
+ yet authorized.
+
+ Possible values are supported:
+
+ == ===================================================
+ 0 The device will be de-authorized (only supported if
+ deauthorization attribute under domain contains 1)
+ 1 The device will be authorized and connected
+ == ===================================================
+
+ When key attribute contains 32 byte hex string the possible
+ values are:
+
+ == ========================================================
+ 0 The device will be de-authorized (only supported if
+ deauthorization attribute under domain contains 1)
+ 1 The 32 byte hex string is added to the device NVM and
+ the device is authorized.
+ 2 Send a challenge based on the 32 byte hex string. If the
+ challenge response from device is valid, the device is
+ authorized. In case of failure errno will be ENOKEY if
+ the device did not contain a key at all, and
+ EKEYREJECTED if the challenge response did not match.
+ == ========================================================
+
+What: /sys/bus/thunderbolt/devices/.../boot
+Date: Jun 2018
+KernelVersion: 4.17
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute contains 1 if Thunderbolt device was already
+ authorized on boot and 0 otherwise.
+
+What: /sys/bus/thunderbolt/devices/.../generation
+Date: Jan 2020
+KernelVersion: 5.5
+Contact: Christian Kellner <christian@kellner.me>
+Description: This attribute contains the generation of the Thunderbolt
+ controller associated with the device. It will contain 4
+ for USB4.
+
+What: /sys/bus/thunderbolt/devices/.../key
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: When a devices supports Thunderbolt secure connect it will
+ have this attribute. Writing 32 byte hex string changes
+ authorization to use the secure connection method instead.
+ Writing an empty string clears the key and regular connection
+ method can be used again.
+
+What: /sys/bus/thunderbolt/devices/.../device
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute contains id of this device extracted from
+ the device DROM.
+
+What: /sys/bus/thunderbolt/devices/.../device_name
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute contains name of this device extracted from
+ the device DROM.
+
+What: /sys/bus/thunderbolt/devices/.../maxhopid
+Date: Jul 2021
+KernelVersion: 5.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Only set for XDomains. The maximum HopID the other host
+ supports as its input HopID.
+
+What: /sys/bus/thunderbolt/devices/.../rx_speed
+Date: Jan 2020
+KernelVersion: 5.5
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute reports the device RX speed per lane.
+ All RX lanes run at the same speed.
+
+What: /sys/bus/thunderbolt/devices/.../rx_lanes
+Date: Jan 2020
+KernelVersion: 5.5
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute reports number of RX lanes the device is
+ using simultaneously through its upstream port.
+
+What: /sys/bus/thunderbolt/devices/.../tx_speed
+Date: Jan 2020
+KernelVersion: 5.5
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute reports the TX speed per lane.
+ All TX lanes run at the same speed.
+
+What: /sys/bus/thunderbolt/devices/.../tx_lanes
+Date: Jan 2020
+KernelVersion: 5.5
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute reports number of TX lanes the device is
+ using simultaneously through its upstream port.
+
+What: /sys/bus/thunderbolt/devices/.../vendor
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute contains vendor id of this device extracted
+ from the device DROM.
+
+What: /sys/bus/thunderbolt/devices/.../vendor_name
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute contains vendor name of this device extracted
+ from the device DROM.
+
+What: /sys/bus/thunderbolt/devices/.../unique_id
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This attribute contains unique_id string of this device.
+ This is either read from hardware registers (UUID on
+ newer hardware) or based on UID from the device DROM.
+ Can be used to uniquely identify particular device.
+
+What: /sys/bus/thunderbolt/devices/.../nvm_version
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: If the device has upgradeable firmware the version
+ number is available here. Format: %x.%x, major.minor.
+ If the device is in safe mode reading the file returns
+ -ENODATA instead as the NVM version is not available.
+
+What: /sys/bus/thunderbolt/devices/.../nvm_authenticate
+Date: Sep 2017
+KernelVersion: 4.13
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: When new NVM image is written to the non-active NVM
+ area (through non_activeX NVMem device), the
+ authentication procedure is started by writing to
+ this file.
+ If everything goes well, the device is
+ restarted with the new NVM firmware. If the image
+ verification fails an error code is returned instead.
+
+ This file will accept writing values "1", "2" or "3".
+
+ - Writing "1" will flush the image to the storage
+ area and authenticate the image in one action.
+ - Writing "2" will run some basic validation on the image
+ and flush it to the storage area.
+ - Writing "3" will authenticate the image that is
+ currently written in the storage area. This is only
+ supported with USB4 devices and retimers.
+
+ When read holds status of the last authentication
+ operation if an error occurred during the process. This
+ is directly the status value from the DMA configuration
+ based mailbox before the device is power cycled. Writing
+ 0 here clears the status.
+
+What: /sys/bus/thunderbolt/devices/.../nvm_authenticate_on_disconnect
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mario Limonciello <mario.limonciello@outlook.com>
+Description: For supported devices, automatically authenticate the new Thunderbolt
+ image when the device is disconnected from the host system.
+
+ This file will accept writing values "1" or "2"
+
+ - Writing "1" will flush the image to the storage
+ area and prepare the device for authentication on disconnect.
+ - Writing "2" will run some basic validation on the image
+ and flush it to the storage area.
+
+What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/key
+Date: Jan 2018
+KernelVersion: 4.15
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This contains name of the property directory the XDomain
+ service exposes. This entry describes the protocol in
+ question. Following directories are already reserved by
+ the Apple XDomain specification:
+
+ ======== ===============================================
+ network IP/ethernet over Thunderbolt
+ targetdm Target disk mode protocol over Thunderbolt
+ extdisp External display mode protocol over Thunderbolt
+ ======== ===============================================
+
+What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/modalias
+Date: Jan 2018
+KernelVersion: 4.15
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Stores the same MODALIAS value emitted by uevent for
+ the XDomain service. Format: tbtsvc:kSpNvNrN
+
+What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcid
+Date: Jan 2018
+KernelVersion: 4.15
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This contains XDomain protocol identifier the XDomain
+ service supports.
+
+What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcvers
+Date: Jan 2018
+KernelVersion: 4.15
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This contains XDomain protocol version the XDomain
+ service supports.
+
+What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcrevs
+Date: Jan 2018
+KernelVersion: 4.15
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This contains XDomain software version the XDomain
+ service supports.
+
+What: /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcstns
+Date: Jan 2018
+KernelVersion: 4.15
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: This contains XDomain service specific settings as
+ bitmask. Format: %x
+
+What: /sys/bus/thunderbolt/devices/usb4_portX/connector
+Date: April 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Symlink to the USB Type-C connector. This link is only
+ created when USB Type-C Connector Class is enabled,
+ and only if the system firmware is capable of
+ describing the connection between a port and its
+ connector.
+
+What: /sys/bus/thunderbolt/devices/usb4_portX/link
+Date: Sep 2021
+KernelVersion: v5.14
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Returns the current link mode. Possible values are
+ "usb4", "tbt" and "none".
+
+What: /sys/bus/thunderbolt/devices/usb4_portX/offline
+Date: Sep 2021
+KernelVersion: v5.14
+Contact: Rajmohan Mani <rajmohan.mani@intel.com>
+Description: Writing 1 to this attribute puts the USB4 port into
+ offline mode. Only allowed when there is nothing
+ connected to the port (link attribute returns "none").
+ Once the port is in offline mode it does not receive any
+ hotplug events. This is used to update NVM firmware of
+ on-board retimers. Writing 0 puts the port back to
+ online mode.
+
+ This attribute is only visible if the platform supports
+ powering on retimers when there is no cable connected.
+
+What: /sys/bus/thunderbolt/devices/usb4_portX/rescan
+Date: Sep 2021
+KernelVersion: v5.14
+Contact: Rajmohan Mani <rajmohan.mani@intel.com>
+Description: When the USB4 port is in offline mode writing 1 to this
+ attribute forces rescan of the sideband for on-board
+ retimers. Each retimer appear under the USB4 port as if
+ the USB4 link was up. These retimers act in the same way
+ as if the cable was connected so upgrading their NVM
+ firmware can be done the usual way.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/device
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Retimer device identifier read from the hardware.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_authenticate
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: When new NVM image is written to the non-active NVM
+ area (through non_activeX NVMem device), the
+ authentication procedure is started by writing 1 to
+ this file. If everything goes well, the device is
+ restarted with the new NVM firmware. If the image
+ verification fails an error code is returned instead.
+
+ When read holds status of the last authentication
+ operation if an error occurred during the process.
+ Format: %x.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_version
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Holds retimer NVM version number. Format: %x.%x, major.minor.
+
+What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/vendor
+Date: Oct 2020
+KernelVersion: v5.9
+Contact: Mika Westerberg <mika.westerberg@linux.intel.com>
+Description: Retimer vendor identifier read from the hardware.
diff --git a/Documentation/ABI/testing/sysfs-bus-typec b/Documentation/ABI/testing/sysfs-bus-typec
new file mode 100644
index 000000000000..205d9c91e2e1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-typec
@@ -0,0 +1,51 @@
+What: /sys/bus/typec/devices/.../active
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows if the mode is active or not. The attribute can be used
+ for entering/exiting the mode. Entering/exiting modes is
+ supported as synchronous operation so write(2) to the attribute
+ does not return until the enter/exit mode operation has
+ finished. The attribute is notified when the mode is
+ entered/exited so poll(2) on the attribute wakes up.
+ Entering/exiting a mode will also generate uevent KOBJ_CHANGE.
+
+ Valid values are boolean.
+
+What: /sys/bus/typec/devices/.../description
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows description of the mode. The description is optional for
+ the drivers, just like with the Billboard Devices.
+
+What: /sys/bus/typec/devices/.../mode
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The index number of the mode returned by Discover Modes USB
+ Power Delivery command. Depending on the alternate mode, the
+ mode index may be significant.
+
+ With some alternate modes (SVIDs), the mode index is assigned
+ for specific functionality in the specification for that
+ alternate mode.
+
+ With other alternate modes, the mode index values are not
+ assigned, and can not be therefore used for identification. When
+ the mode index is not assigned, identifying the alternate mode
+ must be done with either mode VDO or the description.
+
+What: /sys/bus/typec/devices/.../svid
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The Standard or Vendor ID (SVID) assigned by USB-IF for this
+ alternate mode.
+
+What: /sys/bus/typec/devices/.../vdo
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows the VDO in hexadecimal returned by Discover Modes command
+ for this mode.
diff --git a/Documentation/ABI/testing/sysfs-bus-umc b/Documentation/ABI/testing/sysfs-bus-umc
deleted file mode 100644
index 948fec412446..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-umc
+++ /dev/null
@@ -1,28 +0,0 @@
-What: /sys/bus/umc/
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The Wireless Host Controller Interface (WHCI)
- specification describes a PCI-based device with
- multiple capabilities; the UWB Multi-interface
- Controller (UMC).
-
- The umc bus presents each of the individual
- capabilties as a device.
-
-What: /sys/bus/umc/devices/.../capability_id
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The ID of this capability, with 0 being the radio
- controller capability.
-
-What: /sys/bus/umc/devices/.../version
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The specification version this capability's hardware
- interface complies with.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index e5cc7633d013..af9b653422f1 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -1,45 +1,32 @@
-What: /sys/bus/usb/device/.../authorized
-Date: July 2008
-KernelVersion: 2.6.26
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- Authorized devices are available for use by device
- drivers, non-authorized one are not. By default, wired
- USB devices are authorized.
-
- Certified Wireless USB devices are not authorized
- initially and should be (by writing 1) after the
- device has been authenticated.
-
-What: /sys/bus/usb/device/.../wusb_cdid
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
+What: /sys/bus/usb/devices/<INTERFACE>/authorized
+Date: August 2015
Description:
- For Certified Wireless USB devices only.
+ This allows to authorize (1) or deauthorize (0)
+ individual interfaces instead a whole device
+ in contrast to the device authorization.
+ If a deauthorized interface will be authorized
+ so the driver probing must be triggered manually
+ by writing INTERFACE to /sys/bus/usb/drivers_probe
+ This allows to avoid side-effects with drivers
+ that need multiple interfaces.
- A devices's CDID, as 16 space-separated hex octets.
+ A deauthorized interface cannot be probed or claimed.
-What: /sys/bus/usb/device/.../wusb_ck
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
+What: /sys/bus/usb/devices/usbX/interface_authorized_default
+Date: August 2015
Description:
- For Certified Wireless USB devices only.
+ This is used as value that determines if interfaces
+ would be authorized by default.
+ The value can be 1 or 0. It's by default 1.
- Write the device's connection key (CK) to start the
- authentication of the device. The CK is 16
- space-separated hex octets.
-
-What: /sys/bus/usb/device/.../wusb_disconnect
+What: /sys/bus/usb/device/.../authorized
Date: July 2008
-KernelVersion: 2.6.27
+KernelVersion: 2.6.26
Contact: David Vrabel <david.vrabel@csr.com>
Description:
- For Certified Wireless USB devices only.
-
- Write a 1 to force the device to disconnect
- (equivalent to unplugging a wired USB device).
+ Authorized devices are available for use by device
+ drivers, non-authorized one are not. By default, wired
+ USB devices are authorized.
What: /sys/bus/usb/drivers/.../new_id
Date: October 2011
@@ -52,24 +39,27 @@ Description:
table at compile time. The format for the device ID is:
idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct
The vendor ID and device ID fields are required, the
- rest is optional. The Ref* tuple can be used to tell the
+ rest is optional. The `Ref*` tuple can be used to tell the
driver to use the same driver_data for the new device as
it is used for the reference device.
Upon successfully adding an ID, the driver will probe
- for the device and attempt to bind to it. For example:
- # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
+ for the device and attempt to bind to it. For example::
+
+ # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
Here add a new device (0458:7045) using driver_data from
- an already supported device (0458:704c):
- # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
+ an already supported device (0458:704c)::
+
+ # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
Reading from this file will list all dynamically added
device IDs in the same format, with one entry per
- line. For example:
- # cat /sys/bus/usb/drivers/foo/new_id
- 8086 10f5
- dead beef 06
- f00d cafe
+ line. For example::
+
+ # cat /sys/bus/usb/drivers/foo/new_id
+ 8086 10f5
+ dead beef 06
+ f00d cafe
The list will be truncated at PAGE_SIZE bytes due to
sysfs restrictions.
@@ -114,16 +104,21 @@ Description:
enabled for the device. Developer can write y/Y/1 or n/N/0 to
the file to enable/disable the feature.
-What: /sys/bus/usb/devices/.../removable
-Date: February 2012
-Contact: Matthew Garrett <mjg@redhat.com>
+What: /sys/bus/usb/devices/.../power/usb3_hardware_lpm_u1
+ /sys/bus/usb/devices/.../power/usb3_hardware_lpm_u2
+Date: November 2015
+Contact: Kevin Strasser <kevin.strasser@linux.intel.com>
+ Lu Baolu <baolu.lu@linux.intel.com>
Description:
- Some information about whether a given USB device is
- physically fixed to the platform can be inferred from a
- combination of hub descriptor bits and platform-specific data
- such as ACPI. This file will read either "removable" or
- "fixed" if the information is available, and "unknown"
- otherwise.
+ If CONFIG_PM is set and a USB 3.0 lpm-capable device is plugged
+ in to a xHCI host which supports link PM, it will check if U1
+ and U2 exit latencies have been set in the BOS descriptor; if
+ the check is passed and the host supports USB3 hardware LPM,
+ USB3 hardware LPM will be enabled for the device and the USB
+ device directory will contain two files named
+ power/usb3_hardware_lpm_u1 and power/usb3_hardware_lpm_u2. These
+ files hold a string value (enable or disable) indicating whether
+ or not USB3 hardware LPM U1 or U2 is enabled for the device.
What: /sys/bus/usb/devices/.../ltm_capable
Date: July 2012
@@ -137,22 +132,142 @@ Description:
The file will be present for all speeds of USB devices, and will
always read "no" for USB 1.1 and USB 2.0 devices.
-What: /sys/bus/usb/devices/.../(hub interface)/portX
+What: /sys/bus/usb/devices/<INTERFACE>/wireless_status
+Date: February 2023
+Contact: Bastien Nocera <hadess@hadess.net>
+Description:
+ Some USB devices use a USB receiver dongle to communicate
+ wirelessly with their device using proprietary protocols. This
+ attribute allows user-space to know whether the device is
+ connected to its receiver dongle, and, for example, consider
+ the device to be absent when choosing whether to show the
+ device's battery, show a headset in a list of outputs, or show
+ an on-screen keyboard if the only wireless keyboard is
+ turned off.
+ This attribute is not to be used to replace protocol specific
+ statuses available in WWAN, WLAN/Wi-Fi, Bluetooth, etc.
+ If the device does not use a receiver dongle with a wireless
+ device, then this attribute will not exist.
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>
Date: August 2012
Contact: Lan Tianyu <tianyu.lan@intel.com>
Description:
- The /sys/bus/usb/devices/.../(hub interface)/portX
+ The /sys/bus/usb/devices/.../<hub_interface>/port<X>
is usb port device's sysfs directory.
-What: /sys/bus/usb/devices/.../(hub interface)/portX/connect_type
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/connect_type
Date: January 2013
Contact: Lan Tianyu <tianyu.lan@intel.com>
Description:
Some platforms provide usb port connect types through ACPI.
This attribute is to expose these information to user space.
- The file will read "hotplug", "wired" and "not used" if the
+ The file will read "hotplug", "hardwired" and "not used" if the
information is available, and "unknown" otherwise.
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/location
+Date: October 2018
+Contact: Bjørn Mork <bjorn@mork.no>
+Description:
+ Some platforms provide usb port physical location through
+ firmware. This is used by the kernel to pair up logical ports
+ mapping to the same physical connector. The attribute exposes the
+ raw location value as a hex integer.
+
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/quirks
+Date: May 2018
+Contact: Nicolas Boichat <drinkcat@chromium.org>
+Description:
+ In some cases, we care about time-to-active for devices
+ connected on a specific port (e.g. non-standard USB port like
+ pogo pins), where the device to be connected is known in
+ advance, and behaves well according to the specification.
+ This attribute is a bit-field that controls the behavior of
+ a specific port:
+
+ - Bit 0 of this field selects the "old" enumeration scheme,
+ as it is considerably faster (it only causes one USB reset
+ instead of 2).
+
+ The old enumeration scheme can also be selected globally
+ using /sys/module/usbcore/parameters/old_scheme_first, but
+ it is often not desirable as the new scheme was introduced to
+ increase compatibility with more devices.
+ - Bit 1 reduces TRSTRCY to the 10 ms that are required by the
+ USB 2.0 specification, instead of the 50 ms that are normally
+ used to help make enumeration work better on some high speed
+ devices.
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/over_current_count
+Date: February 2018
+Contact: Richard Leitner <richard.leitner@skidata.com>
+Description:
+ Most hubs are able to detect over-current situations on their
+ ports and report them to the kernel. This attribute is to expose
+ the number of over-current situation occurred on a specific port
+ to user space. This file will contain an unsigned 32 bit value
+ which wraps to 0 after its maximum is reached. This file supports
+ poll() for monitoring changes to this value in user space.
+
+ Any time this value changes the corresponding hub device will send a
+ udev event with the following attributes::
+
+ OVER_CURRENT_PORT=/sys/bus/usb/devices/.../<hub_interface>/port<X>
+ OVER_CURRENT_COUNT=[current value of this sysfs attribute]
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/usb3_lpm_permit
+Date: November 2015
+Contact: Lu Baolu <baolu.lu@linux.intel.com>
+Description:
+ Some USB3.0 devices are not friendly to USB3 LPM. usb3_lpm_permit
+ attribute allows enabling/disabling usb3 lpm of a port. It takes
+ effect both before and after a usb device is enumerated. Supported
+ values are "0" if both u1 and u2 are NOT permitted, "u1" if only u1
+ is permitted, "u2" if only u2 is permitted, "u1_u2" if both u1 and
+ u2 are permitted.
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/connector
+Date: December 2021
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Link to the USB Type-C connector when available. This link is
+ only created when USB Type-C Connector Class is enabled, and
+ only if the system firmware is capable of describing the
+ connection between a port and its connector.
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/disable
+Date: June 2022
+Contact: Michael Grzeschik <m.grzeschik@pengutronix.de>
+Description:
+ This file controls the state of a USB port, including
+ Vbus power output (but only on hubs that support
+ power switching -- most hubs don't support it). If
+ a port is disabled, the port is unusable: Devices
+ attached to the port will not be detected, initialized,
+ or enumerated.
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/early_stop
+Date: Sep 2022
+Contact: Ray Chi <raychi@google.com>
+Description:
+ Some USB hosts have some watchdog mechanisms so that the device
+ may enter ramdump if it takes a long time during port initialization.
+ This attribute allows each port just has two attempts so that the
+ port initialization will be failed quickly. In addition, if a port
+ which is marked with early_stop has failed to initialize, it will ignore
+ all future connections until this attribute is clear.
+
+What: /sys/bus/usb/devices/.../<hub_interface>/port<X>/state
+Date: June 2023
+Contact: Roy Luo <royluo@google.com>
+Description:
+ Indicates current state of the USB device attached to the port.
+ Valid states are: 'not-attached', 'attached', 'powered',
+ 'reconnecting', 'unauthenticated', 'default', 'addressed',
+ 'configured', and 'suspended'. This file supports poll() to
+ monitor the state change from user space.
+
What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout
Date: May 2013
Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
@@ -179,3 +294,314 @@ Description:
Supported values are 0 - 15.
More information on how besl values map to microseconds can be found in
USB 2.0 ECN Errata for Link Power Management, section 4.10)
+
+What: /sys/bus/usb/devices/.../rx_lanes
+Date: March 2018
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ Number of rx lanes the device is using.
+ USB 3.2 adds Dual-lane support, 2 rx and 2 tx lanes over Type-C.
+ Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per
+ direction. Devices before USB 3.2 are single lane (rx_lanes = 1)
+
+What: /sys/bus/usb/devices/.../tx_lanes
+Date: March 2018
+Contact: Mathias Nyman <mathias.nyman@linux.intel.com>
+Description:
+ Number of tx lanes the device is using.
+ USB 3.2 adds Dual-lane support, 2 rx and 2 tx -lanes over Type-C.
+ Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per
+ direction. Devices before USB 3.2 are single lane (tx_lanes = 1)
+
+What: /sys/bus/usb/devices/.../typec
+Date: November 2023
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Symlink to the USB Type-C partner device. USB Type-C partner
+ represents the component that communicates over the
+ Configuration Channel (CC signal on USB Type-C connectors and
+ cables) with the local port.
+
+What: /sys/bus/usb/devices/usbX/bAlternateSetting
+Description:
+ The current interface alternate setting number, in decimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bcdDevice
+Description:
+ The device's release number, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bConfigurationValue
+Description:
+ While a USB device typically have just one configuration
+ setting, some devices support multiple configurations.
+
+ This value shows the current configuration, in decimal.
+
+ Changing its value will change the device's configuration
+ to another setting.
+
+ The number of configurations supported by a device is at:
+
+ /sys/bus/usb/devices/usbX/bNumConfigurations
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bDeviceClass
+Description:
+ Class code of the device, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bDeviceProtocol
+Description:
+ Protocol code of the device, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bDeviceSubClass
+Description:
+ Subclass code of the device, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bInterfaceClass
+Description:
+ Class code of the interface, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bInterfaceNumber
+Description:
+ Interface number, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bInterfaceProtocol
+Description:
+ Protocol code of the interface, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bInterfaceSubClass
+Description:
+ Subclass code of the interface, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bmAttributes
+Description:
+ Attributes of the current configuration, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bMaxPacketSize0
+Description:
+ Maximum endpoint 0 packet size, in decimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bMaxPower
+Description:
+ Maximum power consumption of the active configuration of
+ the device, in miliamperes.
+
+What: /sys/bus/usb/devices/usbX/bNumConfigurations
+Description:
+ Number of the possible configurations of the device, in
+ decimal. The current configuration is controlled via:
+
+ /sys/bus/usb/devices/usbX/bConfigurationValue
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bNumEndpoints
+Description:
+ Number of endpoints used on this interface, in hexadecimal.
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/bNumInterfaces
+Description:
+ Number of interfaces on this device, in decimal.
+
+What: /sys/bus/usb/devices/usbX/busnum
+Description:
+ Number of the bus.
+
+What: /sys/bus/usb/devices/usbX/configuration
+Description:
+ Contents of the string descriptor associated with the
+ current configuration. It may include the firmware version
+ of a device and/or its serial number.
+
+What: /sys/bus/usb/devices/usbX/descriptors
+Description:
+ Contains the interface descriptors, in binary.
+
+What: /sys/bus/usb/devices/usbX/bos_descriptors
+Date: March 2024
+Contact: Elbert Mai <code@elbertmai.com>
+Description:
+ Binary file containing the cached binary device object store (BOS)
+ of the device. This consists of the BOS descriptor followed by the
+ set of device capability descriptors. All descriptors read from
+ this file are in bus-endian format. Note that the kernel will not
+ request the BOS from a device if its bcdUSB is less than 0x0201.
+
+What: /sys/bus/usb/devices/usbX/idProduct
+Description:
+ Product ID, in hexadecimal.
+
+What: /sys/bus/usb/devices/usbX/idVendor
+Description:
+ Vendor ID, in hexadecimal.
+
+What: /sys/bus/usb/devices/usbX/devspec
+Description:
+ Displays the Device Tree Open Firmware node of the interface.
+
+What: /sys/bus/usb/devices/usbX/avoid_reset_quirk
+Description:
+ Most devices have this set to zero.
+
+ If the value is 1, enable a USB quirk that prevents this
+ device to use reset.
+
+ (read/write)
+
+What: /sys/bus/usb/devices/usbX/devnum
+Description:
+ USB interface device number, in decimal.
+
+What: /sys/bus/usb/devices/usbX/devpath
+Description:
+ String containing the USB interface device path.
+
+What: /sys/bus/usb/devices/usbX/manufacturer
+Description:
+ Vendor specific string containing the name of the
+ manufacturer of the device.
+
+What: /sys/bus/usb/devices/usbX/maxchild
+Description:
+ Number of ports of an USB hub
+
+What: /sys/bus/usb/devices/usbX/persist
+Description:
+ Keeps the device even if it gets disconnected.
+
+What: /sys/bus/usb/devices/usbX/product
+Description:
+ Vendor specific string containing the name of the
+ device's product.
+
+What: /sys/bus/usb/devices/usbX/speed
+Description:
+ Shows the device's max speed, according to the USB version,
+ in Mbps.
+ Can be:
+
+ ======= ====================
+ Unknown speed unknown
+ 1.5 Low speed
+ 15 Full speed
+ 480 High Speed
+ 5000 Super Speed
+ 10000 Super Speed+
+ 20000 Super Speed+ Gen 2x2
+ ======= ====================
+
+What: /sys/bus/usb/devices/usbX/supports_autosuspend
+Description:
+ Returns 1 if the device doesn't support autosuspend.
+ Otherwise, returns 0.
+
+What: /sys/bus/usb/devices/usbX/urbnum
+Description:
+ Number of URBs submitted for the whole device.
+
+What: /sys/bus/usb/devices/usbX/version
+Description:
+ String containing the USB device version, as encoded
+ at the BCD descriptor.
+
+What: /sys/bus/usb/devices/usbX/power/autosuspend
+Description:
+ Time in milliseconds for the device to autosuspend. If the
+ value is negative, then autosuspend is prevented.
+
+ (read/write)
+
+What: /sys/bus/usb/devices/usbX/power/active_duration
+Description:
+ The total time the device has not been suspended.
+
+What: /sys/bus/usb/devices/usbX/power/connected_duration
+Description:
+ The total time (in msec) that the device has been connected.
+
+What: /sys/bus/usb/devices/usbX/power/level
+Description:
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/bEndpointAddress
+Description:
+ The address of the endpoint described by this descriptor,
+ in hexadecimal. The endpoint direction on this bitmapped field
+ is also shown at:
+
+ /sys/bus/usb/devices/usbX/ep_<N>/direction
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/bInterval
+Description:
+ The interval of the endpoint as described on its descriptor,
+ in hexadecimal. The actual interval depends on the version
+ of the USB. Also shown in time units at
+ /sys/bus/usb/devices/usbX/ep_<N>/interval.
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/bLength
+Description:
+ Number of bytes of the endpoint descriptor, in hexadecimal.
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/bmAttributes
+Description:
+ Attributes which apply to the endpoint as described on its
+ descriptor, in hexadecimal. The endpoint type on this
+ bitmapped field is also shown at:
+
+ /sys/bus/usb/devices/usbX/ep_<N>/type
+
+ See USB specs for its meaning.
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/direction
+Description:
+ Direction of the endpoint. Can be:
+
+ - both (on control endpoints)
+ - in
+ - out
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/interval
+Description:
+ Interval for polling endpoint for data transfers, in
+ milisseconds or microseconds.
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/type
+Description:
+ Descriptor type. Can be:
+
+ - Control
+ - Isoc
+ - Bulk
+ - Interrupt
+ - unknown
+
+What: /sys/bus/usb/devices/usbX/ep_<N>/wMaxPacketSize
+Description:
+ Maximum packet size this endpoint is capable of
+ sending or receiving, in hexadecimal.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
index 70d00dfa443d..2f86e4223bfc 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
+++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -1,43 +1,46 @@
-Where: /sys/bus/usb/.../powered
+What: /sys/bus/usb/.../powered
Date: August 2008
-Kernel Version: 2.6.26
+KernelVersion: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: Controls whether the device's display will powered.
A value of 0 is off and a non-zero value is on.
-Where: /sys/bus/usb/.../mode_msb
-Where: /sys/bus/usb/.../mode_lsb
+What: /sys/bus/usb/.../mode_msb
+What: /sys/bus/usb/.../mode_lsb
Date: August 2008
-Kernel Version: 2.6.26
+KernelVersion: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: Controls the devices display mode.
For a 6 character display the values are
+
MSB 0x06; LSB 0x3F, and
+
for an 8 character display the values are
+
MSB 0x08; LSB 0xFF.
-Where: /sys/bus/usb/.../textmode
+What: /sys/bus/usb/.../textmode
Date: August 2008
-Kernel Version: 2.6.26
+KernelVersion: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: Controls the way the device interprets its text buffer.
raw: each character controls its segment manually
hex: each character is between 0-15
ascii: each character is between '0'-'9' and 'A'-'F'.
-Where: /sys/bus/usb/.../text
+What: /sys/bus/usb/.../text
Date: August 2008
-Kernel Version: 2.6.26
+KernelVersion: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: The text (or data) for the device to display
-Where: /sys/bus/usb/.../decimals
+What: /sys/bus/usb/.../decimals
Date: August 2008
-Kernel Version: 2.6.26
+KernelVersion: 2.6.26
Contact: Harrison Metzger <harrisonmetz@gmail.com>
Description: Controls the decimal places on the device.
To set the nth decimal place, give this field
- the value of 10 ** n. Assume this field has
+ the value of ``10 ** n``. Assume this field has
the value k and has 1 or more decimal places set,
to set the mth place (where m is not already set),
- change this fields value to k + 10 ** m.
+ change this fields value to ``k + 10 ** m``.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-lvstest b/Documentation/ABI/testing/sysfs-bus-usb-lvstest
index aae68fc2d842..ee0046dc4192 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb-lvstest
+++ b/Documentation/ABI/testing/sysfs-bus-usb-lvstest
@@ -4,14 +4,14 @@ driver is bound with root hub device.
What: /sys/bus/usb/devices/.../get_dev_desc
Date: March 2014
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Write to this node to issue "Get Device Descriptor"
for Link Layer Validation device. It is needed for TD.7.06.
What: /sys/bus/usb/devices/.../u1_timeout
Date: March 2014
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Set "U1 timeout" for the downstream port where Link Layer
Validation device is connected. Timeout value must be between 0
@@ -19,7 +19,7 @@ Description:
What: /sys/bus/usb/devices/.../u2_timeout
Date: March 2014
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Set "U2 timeout" for the downstream port where Link Layer
Validation device is connected. Timeout value must be between 0
@@ -27,21 +27,34 @@ Description:
What: /sys/bus/usb/devices/.../hot_reset
Date: March 2014
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Write to this node to issue "Reset" for Link Layer Validation
device. It is needed for TD.7.29, TD.7.31, TD.7.34 and TD.7.35.
What: /sys/bus/usb/devices/.../u3_entry
Date: March 2014
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Write to this node to issue "U3 entry" for Link Layer
Validation device. It is needed for TD.7.35 and TD.7.36.
What: /sys/bus/usb/devices/.../u3_exit
Date: March 2014
-Contact: Pratyush Anand <pratyush.anand@st.com>
+Contact: Pratyush Anand <pratyush.anand@gmail.com>
Description:
Write to this node to issue "U3 exit" for Link Layer
Validation device. It is needed for TD.7.36.
+
+What: /sys/bus/usb/devices/.../enable_compliance
+Date: July 2017
+Description:
+ Write to this node to set the port to compliance mode to test
+ with Link Layer Validation device. It is needed for TD.7.34.
+
+What: /sys/bus/usb/devices/.../warm_reset
+Date: July 2017
+Description:
+ Write to this node to issue "Warm Reset" for Link Layer Validation
+ device. It may be needed to properly reset an xHCI 1.1 host port if
+ compliance mode needed to be explicitly enabled.
diff --git a/Documentation/ABI/testing/sysfs-bus-vdpa b/Documentation/ABI/testing/sysfs-bus-vdpa
new file mode 100644
index 000000000000..2c833b5163f2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-vdpa
@@ -0,0 +1,57 @@
+What: /sys/bus/vdpa/drivers_autoprobe
+Date: March 2020
+Contact: virtualization@lists.linux.dev
+Description:
+ This file determines whether new devices are immediately bound
+ to a driver after the creation. It initially contains 1, which
+ means the kernel automatically binds devices to a compatible
+ driver immediately after they are created.
+
+ Writing "0" to this file disable this feature, any other string
+ enable it.
+
+What: /sys/bus/vdpa/driver_probe
+Date: March 2020
+Contact: virtualization@lists.linux.dev
+Description:
+ Writing a device name to this file will cause the kernel binds
+ devices to a compatible driver.
+
+ This can be useful when /sys/bus/vdpa/drivers_autoprobe is
+ disabled.
+
+What: /sys/bus/vdpa/drivers/.../bind
+Date: March 2020
+Contact: virtualization@lists.linux.dev
+Description:
+ Writing a device name to this file will cause the driver to
+ attempt to bind to the device. This is useful for overriding
+ default bindings.
+
+What: /sys/bus/vdpa/drivers/.../unbind
+Date: March 2020
+Contact: virtualization@lists.linux.dev
+Description:
+ Writing a device name to this file will cause the driver to
+ attempt to unbind from the device. This may be useful when
+ overriding default bindings.
+
+What: /sys/bus/vdpa/devices/.../driver_override
+Date: November 2021
+Contact: virtualization@lists.linux.dev
+Description:
+ This file allows the driver for a device to be specified.
+ When specified, only a driver with a name matching the value
+ written to driver_override will have an opportunity to bind to
+ the device. The override is specified by writing a string to the
+ driver_override file (echo vhost-vdpa > driver_override) and may
+ be cleared with an empty string (echo > driver_override).
+ This returns the device to standard matching rules binding.
+ Writing to driver_override does not automatically unbind the
+ device from its current driver or make any attempt to
+ automatically load the specified driver. If no driver with a
+ matching name is currently loaded in the kernel, the device will
+ not bind to any driver. This also allows devices to opt-out of
+ driver binding using a driver_override name such as "none".
+ Only a single driver may be specified in the override, there is
+ no support for parsing delimiters.
diff --git a/Documentation/ABI/testing/sysfs-bus-vfio-mdev b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
new file mode 100644
index 000000000000..59fc804265db
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
@@ -0,0 +1,113 @@
+What: /sys/.../<device>/mdev_supported_types/
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ This directory contains list of directories of currently
+ supported mediated device types and their details for
+ <device>. Supported type attributes are defined by the
+ vendor driver who registers with Mediated device framework.
+ Each supported type is a directory whose name is created
+ by adding the device driver string as a prefix to the
+ string provided by the vendor driver.
+
+What: /sys/.../<device>/mdev_supported_types/<type-id>/
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ This directory gives details of supported type, like name,
+ description, available_instances, device_api etc.
+ 'device_api' and 'available_instances' are mandatory
+ attributes to be provided by vendor driver. 'name',
+ 'description' and other vendor driver specific attributes
+ are optional.
+
+What: /sys/.../mdev_supported_types/<type-id>/create
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ Writing UUID to this file will create mediated device of
+ type <type-id> for parent device <device>. This is a
+ write-only file.
+ For example::
+
+ # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
+ /sys/devices/foo/mdev_supported_types/foo-1/create
+
+What: /sys/.../mdev_supported_types/<type-id>/devices/
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ This directory contains symbolic links pointing to mdev
+ devices sysfs entries which are created of this <type-id>.
+
+What: /sys/.../mdev_supported_types/<type-id>/available_instances
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ Reading this attribute will show the number of mediated
+ devices of type <type-id> that can be created. This is a
+ readonly file.
+Users:
+ Userspace applications interested in creating mediated
+ device of that type. Userspace application should check
+ the number of available instances could be created before
+ creating mediated device of this type.
+
+What: /sys/.../mdev_supported_types/<type-id>/device_api
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ Reading this attribute will show VFIO device API supported
+ by this type. For example, "vfio-pci" for a PCI device,
+ "vfio-platform" for platform device.
+
+What: /sys/.../mdev_supported_types/<type-id>/name
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ Reading this attribute will show human readable name of the
+ mediated device that will get created of type <type-id>.
+ This is optional attribute. For example: "Grid M60-0Q"
+Users:
+ Userspace applications interested in knowing the name of
+ a particular <type-id> that can help in understanding the
+ type of mediated device.
+
+What: /sys/.../mdev_supported_types/<type-id>/description
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ Reading this attribute will show description of the type of
+ mediated device that will get created of type <type-id>.
+ This is optional attribute. For example:
+ "2 heads, 512M FB, 2560x1600 maximum resolution"
+Users:
+ Userspace applications interested in knowing the details of
+ a particular <type-id> that can help in understanding the
+ features provided by that type of mediated device.
+
+What: /sys/.../<device>/<UUID>/
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ This directory represents device directory of mediated
+ device. It contains all the attributes related to mediated
+ device.
+
+What: /sys/.../<device>/<UUID>/mdev_type
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ This is symbolic link pointing to supported type, <type-id>
+ directory of which this mediated device is created.
+
+What: /sys/.../<device>/<UUID>/remove
+Date: October 2016
+Contact: Kirti Wankhede <kwankhede@nvidia.com>
+Description:
+ Writing '1' to this file destroys the mediated device. The
+ vendor driver can fail the remove() callback if that device
+ is active and the vendor driver doesn't support hot unplug.
+ Example::
+
+ # echo 1 > /sys/bus/mdev/devices/<UUID>/remove
diff --git a/Documentation/ABI/testing/sysfs-bus-vmbus b/Documentation/ABI/testing/sysfs-bus-vmbus
new file mode 100644
index 000000000000..91e6c065973c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-vmbus
@@ -0,0 +1,21 @@
+What: /sys/bus/vmbus/devices/.../driver_override
+Date: August 2019
+Contact: Stephen Hemminger <sthemmin@microsoft.com>
+Description:
+ This file allows the driver for a device to be specified which
+ will override standard static and dynamic ID matching. When
+ specified, only a driver with a name matching the value written
+ to driver_override will have an opportunity to bind to the
+ device. The override is specified by writing a string to the
+ driver_override file (echo uio_hv_generic > driver_override) and
+ may be cleared with an empty string (echo > driver_override).
+ This returns the device to standard matching rules binding.
+ Writing to driver_override does not automatically unbind the
+ device from its current driver or make any attempt to
+ automatically load the specified driver. If no driver with a
+ matching name is currently loaded in the kernel, the device
+ will not bind to any driver. This also allows devices to
+ opt-out of driver binding using a driver_override name such as
+ "none". Only a single driver may be specified in the override,
+ there is no support for parsing delimiters.
+
diff --git a/Documentation/ABI/testing/sysfs-bus-wmi b/Documentation/ABI/testing/sysfs-bus-wmi
new file mode 100644
index 000000000000..d71a219c610e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-wmi
@@ -0,0 +1,81 @@
+What: /sys/bus/wmi/devices/.../driver_override
+Date: February 2024
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ This file allows the driver for a device to be specified which
+ will override standard ID table matching.
+ When specified, only a driver with a name matching the value
+ written to driver_override will have an opportunity to bind
+ to the device.
+ The override is specified by writing a string to the
+ driver_override file (echo wmi-event-dummy > driver_override).
+ The override may be cleared with an empty string (echo > \
+ driver_override) which returns the device to standard matching
+ rules binding.
+ Writing to driver_override does not automatically unbind the
+ device from its current driver or make any attempt to automatically
+ load the specified driver. If no driver with a matching name is
+ currently loaded in the kernel, the device will not bind to any
+ driver.
+ This also allows devices to opt-out of driver binding using a
+ driver_override name such as "none". Only a single driver may be
+ specified in the override, there is no support for parsing delimiters.
+
+What: /sys/bus/wmi/devices/.../modalias
+Date: November 20:15
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+ This file contains the MODALIAS value emitted by uevent for a
+ given WMI device.
+
+ Format: wmi:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
+
+What: /sys/bus/wmi/devices/.../guid
+Date: November 2015
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+ This file contains the GUID used to match WMI devices to
+ compatible WMI drivers. This GUID is not necessarily unique
+ inside a given machine, it is solely used to identify the
+ interface exposed by a given WMI device.
+
+What: /sys/bus/wmi/devices/.../object_id
+Date: November 2015
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+ This file contains the WMI object ID used internally to construct
+ the ACPI method names used by non-event WMI devices. It contains
+ two ASCII letters.
+
+What: /sys/bus/wmi/devices/.../notify_id
+Date: November 2015
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+ This file contains the WMI notify ID used internally to map ACPI
+ events to WMI event devices. It contains two ASCII letters.
+
+What: /sys/bus/wmi/devices/.../instance_count
+Date: November 2015
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+ This file contains the number of WMI object instances being
+ present on a given WMI device. It contains a non-negative
+ number.
+
+What: /sys/bus/wmi/devices/.../expensive
+Date: November 2015
+Contact: Andy Lutomirski <luto@kernel.org>
+Description:
+ This file contains a boolean flag signaling if interacting with
+ the given WMI device will consume significant CPU resources.
+ The WMI driver core will take care of enabling/disabling such
+ WMI devices.
+
+What: /sys/bus/wmi/devices/.../setable
+Date: May 2017
+Contact: Darren Hart (VMware) <dvhart@infradead.org>
+Description:
+ This file contains a boolean flags signaling the data block
+ associated with the given WMI device is writable. If the
+ given WMI device is not associated with a data block, then
+ this file will not exist.
diff --git a/Documentation/ABI/testing/sysfs-c2port b/Documentation/ABI/testing/sysfs-c2port
index 716cffc457e9..f7b8cf6e4398 100644
--- a/Documentation/ABI/testing/sysfs-c2port
+++ b/Documentation/ABI/testing/sysfs-c2port
@@ -66,13 +66,6 @@ Description:
the "erase" command on the on-board flash of the connected
micro.
-What: /sys/class/c2port/c2portX/flash_erase
-Date: October 2008
-Contact: Rodolfo Giometti <giometti@linux.it>
-Description:
- The /sys/class/c2port/c2portX/flash_erase file show the
- on-board flash size of the connected micro.
-
What: /sys/class/c2port/c2portX/reset
Date: October 2008
Contact: Rodolfo Giometti <giometti@linux.it>
diff --git a/Documentation/ABI/testing/sysfs-class b/Documentation/ABI/testing/sysfs-class
index 676530fcf747..906735faa1b8 100644
--- a/Documentation/ABI/testing/sysfs-class
+++ b/Documentation/ABI/testing/sysfs-class
@@ -1,5 +1,5 @@
What: /sys/class/
-Date: Febuary 2006
+Date: February 2006
Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Description:
The /sys/class directory will consist of a group of
diff --git a/Documentation/ABI/testing/sysfs-class-backlight b/Documentation/ABI/testing/sysfs-class-backlight
new file mode 100644
index 000000000000..c453646b06e2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-backlight
@@ -0,0 +1,186 @@
+What: /sys/class/backlight/<backlight>/scale
+Date: July 2019
+KernelVersion: 5.4
+Contact: Daniel Thompson <daniel.thompson@linaro.org>
+Description:
+ Description of the scale of the brightness curve.
+
+ The human eye senses brightness approximately logarithmically,
+ hence linear changes in brightness are perceived as being
+ non-linear. To achieve a linear perception of brightness changes
+ controls like sliders need to apply a logarithmic mapping for
+ backlights with a linear brightness curve.
+
+ Possible values of the attribute are:
+
+ unknown
+ The scale of the brightness curve is unknown.
+
+ linear
+ The brightness changes linearly with each step. Brightness
+ controls should apply a logarithmic mapping for a linear
+ perception.
+
+ non-linear
+ The brightness changes non-linearly with each step. Brightness
+ controls should use a linear mapping for a linear perception.
+
+What: /sys/class/backlight/<backlight>/ambient_light_level
+Date: Apr, 2010
+KernelVersion: v2.6.35
+Contact: Michael Hennerich <michael.hennerich@analog.com>
+Description:
+ (RO) Get conversion value of the light sensor.
+
+ The value is automatically updated every 80 ms when the
+ light sensor is enabled.
+
+ The value range is device-driver specific:
+
+ For ADP8870:
+
+ It returns integer between 0 (dark) and 8000 (max ambient
+ brightness).
+
+ For ADP8860:
+
+ It returns a 13-bits integer.
+
+What: /sys/class/backlight/<backlight>/ambient_light_zone
+Date: Apr, 2010
+KernelVersion: v2.6.35
+Contact: Michael Hennerich <michael.hennerich@analog.com>,
+ device-drivers-devel@blackfin.uclinux.org
+
+Description:
+ (RW) Read or write the specific brightness level at which the
+ backlight operates.
+
+ The value meaning is device-driver specific:
+
+ For ADP8860:
+
+ == ==========================
+ 0 Off: Backlight set to 0 mA
+ 1 Level 1: daylight
+ 2 Level 2: bright
+ 3 Level 3: dark
+ == ==========================
+
+ For ADP8870:
+
+ == ==========================
+ 0 Off: Backlight set to 0 mA
+ 1 Level 1: daylight
+ 2 Level 2: bright
+ 3 Level 3: office
+ 4 Level 4: indoor
+ 5 Level 5: dark
+ == ==========================
+
+ Writing 0 returns to normal/automatic ambient light level
+ operation.
+
+ It can be enabled by writing the value stored in
+ /sys/class/backlight/<backlight>/max_brightness to
+ /sys/class/backlight/<backlight>/brightness.
+
+What: /sys/class/backlight/<backlight>/<ambient light zone>_max
+Date: Sep, 2009
+KernelVersion: v2.6.32
+Contact: device-drivers-devel@blackfin.uclinux.org
+Description:
+ Control the maximum brightness for <ambient light zone>
+ on this <backlight>. Values are between 0 and 127. This file
+ will also show the brightness level stored for this
+ <ambient light zone>.
+
+ The <ambient light zone> is device-driver specific:
+
+ For ADP5520 and ADP5501, <ambient light zone> can be:
+
+ =========== ================================================
+ Ambient sysfs entry
+ light zone
+ =========== ================================================
+ daylight /sys/class/backlight/<backlight>/daylight_max
+ office /sys/class/backlight/<backlight>/office_max
+ dark /sys/class/backlight/<backlight>/dark_max
+ =========== ================================================
+
+ For ADP8860, <ambient light zone> can be:
+
+ =========== ================================================
+ Ambient sysfs entry
+ light zone
+ =========== ================================================
+ l1_daylight /sys/class/backlight/<backlight>/l1_daylight_max
+ l2_office /sys/class/backlight/<backlight>/l2_office_max
+ l3_dark /sys/class/backlight/<backlight>/l3_dark_max
+ =========== ================================================
+
+ For ADP8870, <ambient light zone> can be:
+
+ =========== ================================================
+ Ambient sysfs entry
+ light zone
+ =========== ================================================
+ l1_daylight /sys/class/backlight/<backlight>/l1_daylight_max
+ l2_bright /sys/class/backlight/<backlight>/l2_bright_max
+ l3_office /sys/class/backlight/<backlight>/l3_office_max
+ l4_indoor /sys/class/backlight/<backlight>/l4_indoor_max
+ l5_dark /sys/class/backlight/<backlight>/l5_dark_max
+ =========== ================================================
+
+ See also: /sys/class/backlight/<backlight>/ambient_light_zone.
+
+What: /sys/class/backlight/<backlight>/<ambient light zone>_dim
+Date: Sep, 2009
+KernelVersion: v2.6.32
+Contact: device-drivers-devel@blackfin.uclinux.org
+Description:
+ Control the dim brightness for <ambient light zone>
+ on this <backlight>. Values are between 0 and 127, typically
+ set to 0. Full off when the backlight is disabled.
+ This file will also show the dim brightness level stored for
+ this <ambient light zone>.
+
+ The <ambient light zone> is device-driver specific:
+
+ For ADP5520 and ADP5501, <ambient light zone> can be:
+
+ =========== ================================================
+ Ambient sysfs entry
+ light zone
+ =========== ================================================
+ daylight /sys/class/backlight/<backlight>/daylight_dim
+ office /sys/class/backlight/<backlight>/office_dim
+ dark /sys/class/backlight/<backlight>/dark_dim
+ =========== ================================================
+
+ For ADP8860, <ambient light zone> can be:
+
+ =========== ================================================
+ Ambient sysfs entry
+ light zone
+ =========== ================================================
+ l1_daylight /sys/class/backlight/<backlight>/l1_daylight_dim
+ l2_office /sys/class/backlight/<backlight>/l2_office_dim
+ l3_dark /sys/class/backlight/<backlight>/l3_dark_dim
+ =========== ================================================
+
+ For ADP8870, <ambient light zone> can be:
+
+ =========== ================================================
+ Ambient sysfs entry
+ light zone
+ =========== ================================================
+ l1_daylight /sys/class/backlight/<backlight>/l1_daylight_dim
+ l2_bright /sys/class/backlight/<backlight>/l2_bright_dim
+ l3_office /sys/class/backlight/<backlight>/l3_office_dim
+ l4_indoor /sys/class/backlight/<backlight>/l4_indoor_dim
+ l5_dark /sys/class/backlight/<backlight>/l5_dark_dim
+ =========== ================================================
+
+ See also: /sys/class/backlight/<backlight>/ambient_light_zone.
+
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
deleted file mode 100644
index 33e648808117..000000000000
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
+++ /dev/null
@@ -1,56 +0,0 @@
-What: /sys/class/backlight/<backlight>/<ambient light zone>_max
-What: /sys/class/backlight/<backlight>/l1_daylight_max
-What: /sys/class/backlight/<backlight>/l2_bright_max
-What: /sys/class/backlight/<backlight>/l3_office_max
-What: /sys/class/backlight/<backlight>/l4_indoor_max
-What: /sys/class/backlight/<backlight>/l5_dark_max
-Date: May 2011
-KernelVersion: 3.0
-Contact: device-drivers-devel@blackfin.uclinux.org
-Description:
- Control the maximum brightness for <ambient light zone>
- on this <backlight>. Values are between 0 and 127. This file
- will also show the brightness level stored for this
- <ambient light zone>.
-
-What: /sys/class/backlight/<backlight>/<ambient light zone>_dim
-What: /sys/class/backlight/<backlight>/l2_bright_dim
-What: /sys/class/backlight/<backlight>/l3_office_dim
-What: /sys/class/backlight/<backlight>/l4_indoor_dim
-What: /sys/class/backlight/<backlight>/l5_dark_dim
-Date: May 2011
-KernelVersion: 3.0
-Contact: device-drivers-devel@blackfin.uclinux.org
-Description:
- Control the dim brightness for <ambient light zone>
- on this <backlight>. Values are between 0 and 127, typically
- set to 0. Full off when the backlight is disabled.
- This file will also show the dim brightness level stored for
- this <ambient light zone>.
-
-What: /sys/class/backlight/<backlight>/ambient_light_level
-Date: May 2011
-KernelVersion: 3.0
-Contact: device-drivers-devel@blackfin.uclinux.org
-Description:
- Get conversion value of the light sensor.
- This value is updated every 80 ms (when the light sensor
- is enabled). Returns integer between 0 (dark) and
- 8000 (max ambient brightness)
-
-What: /sys/class/backlight/<backlight>/ambient_light_zone
-Date: May 2011
-KernelVersion: 3.0
-Contact: device-drivers-devel@blackfin.uclinux.org
-Description:
- Get/Set current ambient light zone. Reading returns
- integer between 1..5 (1 = daylight, 2 = bright, ..., 5 = dark).
- Writing a value between 1..5 forces the backlight controller
- to enter the corresponding ambient light zone.
- Writing 0 returns to normal/automatic ambient light level
- operation. The ambient light sensing feature on these devices
- is an extension to the API documented in
- Documentation/ABI/stable/sysfs-class-backlight.
- It can be enabled by writing the value stored in
- /sys/class/backlight/<backlight>/max_brightness to
- /sys/class/backlight/<backlight>/brightness.
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
index 77cf7ac949af..8251e78abc49 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
@@ -4,10 +4,12 @@ KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
Get the ALS output channel used as input in
- ALS-current-control mode (0, 1), where
+ ALS-current-control mode (0, 1), where:
- 0 - out_current0 (backlight 0)
- 1 - out_current1 (backlight 1)
+ == ==========================
+ 0 out_current0 (backlight 0)
+ 1 out_current1 (backlight 1)
+ == ==========================
What: /sys/class/backlight/<backlight>/als_en
Date: May 2012
@@ -28,21 +30,25 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the brightness-mapping mode (0, 1), where
+ Set the brightness-mapping mode (0, 1), where:
- 0 - exponential mode
- 1 - linear mode
+ == ================
+ 0 exponential mode
+ 1 linear mode
+ == ================
What: /sys/class/backlight/<backlight>/pwm
Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the PWM-input control mask (5 bits), where
+ Set the PWM-input control mask (5 bits), where:
- bit 5 - PWM-input enabled in Zone 4
- bit 4 - PWM-input enabled in Zone 3
- bit 3 - PWM-input enabled in Zone 2
- bit 2 - PWM-input enabled in Zone 1
- bit 1 - PWM-input enabled in Zone 0
- bit 0 - PWM-input enabled
+ ===== ===========================
+ bit 5 PWM-input enabled in Zone 4
+ bit 4 PWM-input enabled in Zone 3
+ bit 3 PWM-input enabled in Zone 2
+ bit 2 PWM-input enabled in Zone 1
+ bit 1 PWM-input enabled in Zone 0
+ bit 0 PWM-input enabled
+ ===== ===========================
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-lm3639 b/Documentation/ABI/testing/sysfs-class-backlight-lm3639
new file mode 100644
index 000000000000..f7e92a82ea25
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-backlight-lm3639
@@ -0,0 +1,11 @@
+sysfs interface for Texas Instruments lm3639 backlight + flash led driver chip
+------------------------------------------------------------------------------
+
+What: /sys/class/backlight/<backlight>/bled_mode
+Date: Oct, 2012
+KernelVersion: v3.10
+Contact: dri-devel@lists.freedesktop.org
+Description:
+ (WO) Write to the backlight mapping mode. The backlight current
+ can be mapped for either exponential (value "0") or linear
+ mapping modes (default).
diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi
index d773d5697cf5..0d2abd88a18c 100644
--- a/Documentation/ABI/testing/sysfs-class-bdi
+++ b/Documentation/ABI/testing/sysfs-class-bdi
@@ -23,15 +23,17 @@ default
The default backing dev, used for non-block device backed
filesystems which do not provide their own BDI.
-Files under /sys/class/bdi/<bdi>/
----------------------------------
-
-read_ahead_kb (read-write)
-
+What: /sys/class/bdi/<bdi>/read_ahead_kb
+Date: January 2008
+Contact: Peter Zijlstra <a.p.zijlstra@chello.nl>
+Description:
Size of the read-ahead window in kilobytes
-min_ratio (read-write)
-
+ (read-write)
+What: /sys/class/bdi/<bdi>/min_ratio
+Date: January 2008
+Contact: Peter Zijlstra <a.p.zijlstra@chello.nl>
+Description:
Under normal circumstances each device is given a part of the
total write-back cache that relates to its current average
writeout speed in relation to the other devices.
@@ -40,8 +42,27 @@ min_ratio (read-write)
percentage of the write-back cache to a particular device.
For example, this is useful for providing a minimum QoS.
-max_ratio (read-write)
+ (read-write)
+What: /sys/class/bdi/<bdi>/min_ratio_fine
+Date: November 2022
+Contact: Stefan Roesch <shr@devkernel.io>
+Description:
+ Under normal circumstances each device is given a part of the
+ total write-back cache that relates to its current average
+ writeout speed in relation to the other devices.
+
+ The 'min_ratio_fine' parameter allows assigning a minimum reserve
+ of the write-back cache to a particular device. The value is
+ expressed as part of 1 million. For example, this is useful for
+ providing a minimum QoS.
+
+ (read-write)
+
+What: /sys/class/bdi/<bdi>/max_ratio
+Date: January 2008
+Contact: Peter Zijlstra <a.p.zijlstra@chello.nl>
+Description:
Allows limiting a particular device to use not more than the
given percentage of the write-back cache. This is useful in
situations where we want to avoid one device taking all or
@@ -49,7 +70,65 @@ max_ratio (read-write)
mount that is prone to get stuck, or a FUSE mount which cannot
be trusted to play fair.
-stable_pages_required (read-only)
+ (read-write)
+
+What: /sys/class/bdi/<bdi>/max_ratio_fine
+Date: November 2022
+Contact: Stefan Roesch <shr@devkernel.io>
+Description:
+ Allows limiting a particular device to use not more than the
+ given value of the write-back cache. The value is given as part
+ of 1 million. This is useful in situations where we want to avoid
+ one device taking all or most of the write-back cache. For example
+ in case of an NFS mount that is prone to get stuck, or a FUSE mount
+ which cannot be trusted to play fair.
+
+ (read-write)
+What: /sys/class/bdi/<bdi>/min_bytes
+Date: October 2022
+Contact: Stefan Roesch <shr@devkernel.io>
+Description:
+ Under normal circumstances each device is given a part of the
+ total write-back cache that relates to its current average
+ writeout speed in relation to the other devices.
+
+ The 'min_bytes' parameter allows assigning a minimum
+ percentage of the write-back cache to a particular device
+ expressed in bytes.
+ For example, this is useful for providing a minimum QoS.
+
+ (read-write)
+
+What: /sys/class/bdi/<bdi>/max_bytes
+Date: October 2022
+Contact: Stefan Roesch <shr@devkernel.io>
+Description:
+ Allows limiting a particular device to use not more than the
+ given 'max_bytes' of the write-back cache. This is useful in
+ situations where we want to avoid one device taking all or
+ most of the write-back cache. For example in case of an NFS
+ mount that is prone to get stuck, a FUSE mount which cannot be
+ trusted to play fair, or a nbd device.
+
+ (read-write)
+
+What: /sys/class/bdi/<bdi>/strict_limit
+Date: October 2022
+Contact: Stefan Roesch <shr@devkernel.io>
+Description:
+ Forces per-BDI checks for the share of given device in the write-back
+ cache even before the global background dirty limit is reached. This
+ is useful in situations where the global limit is much higher than
+ affordable for given relatively slow (or untrusted) device. Turning
+ strictlimit on has no visible effect if max_ratio is equal to 100%.
+
+ (read-write)
+What: /sys/class/bdi/<bdi>/stable_pages_required
+Date: January 2008
+Contact: Peter Zijlstra <a.p.zijlstra@chello.nl>
+Description:
If set, the backing device requires that all pages comprising a write
request must not be changed until writeout is complete.
+
+ (read-only)
diff --git a/Documentation/ABI/testing/sysfs-class-bsr b/Documentation/ABI/testing/sysfs-class-bsr
new file mode 100644
index 000000000000..7bf145d32cbc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-bsr
@@ -0,0 +1,25 @@
+What: /sys/class/bsr/bsr*/bsr_size
+Date: Jul, 2008
+KernelVersion: 2.6.27
+Contact: Arnd Bergmann <arnd@arndb.de>,
+ Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+ (RO) Size of the barrier-synchronization register (BSR)
+ register in bytes.
+
+What: /sys/class/bsr/bsr*/bsr_length
+Date: Jul, 2008
+KernelVersion: 2.6.27
+Contact: Arnd Bergmann <arnd@arndb.de>,
+ Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+ (RO) The length of memory region that can be mapped in bytes.
+
+What: /sys/class/bsr/bsr*/bsr_stride
+Date: Jul, 2008
+KernelVersion: 2.6.27
+Contact: Arnd Bergmann <arnd@arndb.de>,
+ Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+Description:
+ (RO) The stride or the interval at which the allocated BSR bytes
+ repeat within the mapping.
diff --git a/Documentation/ABI/testing/sysfs-class-chromeos b/Documentation/ABI/testing/sysfs-class-chromeos
new file mode 100644
index 000000000000..7fa5be6cc774
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-chromeos
@@ -0,0 +1,53 @@
+What: /sys/class/chromeos/<ec-device-name>/flashinfo
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ Show the EC flash information.
+
+What: /sys/class/chromeos/<ec-device-name>/kb_wake_angle
+Date: March 2018
+KernelVersion: 4.17
+Description:
+ Control the keyboard wake lid angle. Values are between
+ 0 and 360. This file will also show the keyboard wake lid
+ angle by querying the hardware.
+
+What: /sys/class/chromeos/<ec-device-name>/reboot
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ Tell the EC to reboot in various ways. Options are:
+
+ - "cancel": Cancel a pending reboot.
+ - "ro": Jump to RO without rebooting.
+ - "rw": Jump to RW without rebooting.
+ - "cold": Cold reboot.
+ - "disable-jump": Disable jump until next reboot.
+ - "hibernate": Hibernate the EC.
+ - "at-shutdown": Reboot after an AP shutdown.
+
+What: /sys/class/chromeos/<ec-device-name>/version
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ Show the information about the EC software and hardware.
+
+What: /sys/class/chromeos/cros_ec/usbpdmuxinfo
+Date: February 2025
+Description:
+ Show PD mux status for each typec port with following flags:
+ - "USB": USB connected
+ - "DP": DP connected
+ - "POLARITY": CC line Polarity inverted
+ - "HPD_IRQ": Hot Plug Detect interrupt is asserted
+ - "HPD_LVL": Hot Plug Detect level is asserted
+ - "SAFE": DP is in safe mode
+ - "TBT": TBT enabled
+ - "USB4": USB4 enabled
+
+What: /sys/class/chromeos/cros_ec/ap_mode_entry
+Date: February 2025
+Description:
+ Show if the AP mode entry EC feature is supported.
+ It indicates whether the EC waits for direction from the AP
+ to enter Type-C altmodes or USB4 mode.
diff --git a/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar
new file mode 100644
index 000000000000..57a037791403
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar
@@ -0,0 +1,74 @@
+What: /sys/class/chromeos/<ec-device-name>/lightbar/brightness
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ Writing to this file adjusts the overall brightness of
+ the lightbar, separate from any color intensity. The
+ valid range is 0 (off) to 255 (maximum brightness).
+
+What: /sys/class/chromeos/<ec-device-name>/lightbar/interval_msec
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ The lightbar is controlled by an embedded controller (EC),
+ which also manages the keyboard, battery charging, fans,
+ and other system hardware. To prevent unprivileged users
+ from interfering with the other EC functions, the rate at
+ which the lightbar control files can be read or written is
+ limited.
+
+ Reading this file will return the number of milliseconds
+ that must elapse between accessing any of the lightbar
+ functions through this interface. Going faster will simply
+ block until the necessary interval has lapsed. The interval
+ applies uniformly to all accesses of any kind by any user.
+
+What: /sys/class/chromeos/<ec-device-name>/lightbar/led_rgb
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ This allows you to control each LED segment. If the
+ lightbar is already running one of the automatic
+ sequences, you probably won’t see anything change because
+ your color setting will be almost immediately replaced.
+ To get useful results, you should stop the lightbar
+ sequence first.
+
+ The values written to this file are sets of four integers,
+ indicating LED, RED, GREEN, BLUE. The LED number is 0 to 3
+ to select a single segment, or 4 to set all four segments
+ to the same value at once. The RED, GREEN, and BLUE
+ numbers should be in the range 0 (off) to 255 (maximum).
+ You can update more than one segment at a time by writing
+ more than one set of four integers.
+
+What: /sys/class/chromeos/<ec-device-name>/lightbar/program
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ This allows you to upload and run custom lightbar sequences.
+
+What: /sys/class/chromeos/<ec-device-name>/lightbar/sequence
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ The Pixel lightbar has a number of built-in sequences
+ that it displays under various conditions, such as at
+ power on, shut down, or while running. Reading from this
+ file displays the current sequence that the lightbar is
+ displaying. Writing to this file allows you to change the
+ sequence.
+
+What: /sys/class/chromeos/<ec-device-name>/lightbar/userspace_control
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ This allows you to take the control of the lightbar. This
+ prevents the kernel from going through its normal
+ sequences.
+
+What: /sys/class/chromeos/<ec-device-name>/lightbar/version
+Date: August 2015
+KernelVersion: 4.2
+Description:
+ Show the information about the lightbar version.
diff --git a/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc
new file mode 100644
index 000000000000..38c5aaaaa89a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc
@@ -0,0 +1,6 @@
+What: /sys/class/chromeos/<ec-device-name>/vbc/vboot_context
+Date: October 2015
+KernelVersion: 4.4
+Description:
+ Read/write the verified boot context data included on a
+ small nvram space on some EC implementations.
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
deleted file mode 100644
index d46bba801aac..000000000000
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ /dev/null
@@ -1,192 +0,0 @@
-Note: Attributes that are shared between devices are stored in the directory
-pointed to by the symlink device/.
-Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
-/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
-
-
-Slave contexts (eg. /sys/class/cxl/afu0.0s):
-
-What: /sys/class/cxl/<afu>/irqs_max
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read/write
- Decimal value of maximum number of interrupts that can be
- requested by userspace. The default on probe is the maximum
- that hardware can support (eg. 2037). Write values will limit
- userspace applications to that many userspace interrupts. Must
- be >= irqs_min.
-
-What: /sys/class/cxl/<afu>/irqs_min
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the minimum number of interrupts that
- userspace must request on a CXL_START_WORK ioctl. Userspace may
- omit the num_interrupts field in the START_WORK IOCTL to get
- this minimum automatically.
-
-What: /sys/class/cxl/<afu>/mmio_size
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the size of the MMIO space that may be mmaped
- by userspace.
-
-What: /sys/class/cxl/<afu>/modes_supported
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- List of the modes this AFU supports. One per line.
- Valid entries are: "dedicated_process" and "afu_directed"
-
-What: /sys/class/cxl/<afu>/mode
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read/write
- The current mode the AFU is using. Will be one of the modes
- given in modes_supported. Writing will change the mode
- provided that no user contexts are attached.
-
-
-What: /sys/class/cxl/<afu>/prefault_mode
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read/write
- Set the mode for prefaulting in segments into the segment table
- when performing the START_WORK ioctl. Possible values:
- none: No prefaulting (default)
- work_element_descriptor: Treat the work element
- descriptor as an effective address and
- prefault what it points to.
- all: all segments process calling START_WORK maps.
-
-What: /sys/class/cxl/<afu>/reset
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: write only
- Writing 1 here will reset the AFU provided there are not
- contexts active on the AFU.
-
-What: /sys/class/cxl/<afu>/api_version
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the current version of the kernel/user API.
-
-What: /sys/class/cxl/<afu>/api_version_compatible
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the the lowest version of the userspace API
- this this kernel supports.
-
-
-AFU configuration records (eg. /sys/class/cxl/afu0.0/cr0):
-
-An AFU may optionally export one or more PCIe like configuration records, known
-as AFU configuration records, which will show up here (if present).
-
-What: /sys/class/cxl/<afu>/cr<config num>/vendor
-Date: February 2015
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Hexadecimal value of the vendor ID found in this AFU
- configuration record.
-
-What: /sys/class/cxl/<afu>/cr<config num>/device
-Date: February 2015
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Hexadecimal value of the device ID found in this AFU
- configuration record.
-
-What: /sys/class/cxl/<afu>/cr<config num>/class
-Date: February 2015
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Hexadecimal value of the class code found in this AFU
- configuration record.
-
-What: /sys/class/cxl/<afu>/cr<config num>/config
-Date: February 2015
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- This binary file provides raw access to the AFU configuration
- record. The format is expected to match the either the standard
- or extended configuration space defined by the PCIe
- specification.
-
-
-
-Master contexts (eg. /sys/class/cxl/afu0.0m)
-
-What: /sys/class/cxl/<afu>m/mmio_size
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the size of the MMIO space that may be mmaped
- by userspace. This includes all slave contexts space also.
-
-What: /sys/class/cxl/<afu>m/pp_mmio_len
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the Per Process MMIO space length.
-
-What: /sys/class/cxl/<afu>m/pp_mmio_off
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Decimal value of the Per Process MMIO space offset.
-
-
-Card info (eg. /sys/class/cxl/card0)
-
-What: /sys/class/cxl/<card>/caia_version
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Identifies the CAIA Version the card implements.
-
-What: /sys/class/cxl/<card>/psl_revision
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Identifies the revision level of the PSL.
-
-What: /sys/class/cxl/<card>/base_image
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Identifies the revision level of the base image for devices
- that support loadable PSLs. For FPGAs this field identifies
- the image contained in the on-adapter flash which is loaded
- during the initial program load.
-
-What: /sys/class/cxl/<card>/image_loaded
-Date: September 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read only
- Will return "user" or "factory" depending on the image loaded
- onto the card.
-
-What: /sys/class/cxl/<card>/load_image_on_perst
-Date: December 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: read/write
- Valid entries are "none", "user", and "factory".
- "none" means PERST will not cause image to be loaded to the
- card. A power cycle is required to load the image.
- "none" could be useful for debugging because the trace arrays
- are preserved.
- "user" and "factory" means PERST will cause either the user or
- user or factory image to be loaded.
- Default is to reload on PERST whichever image the card has
- loaded.
-
-What: /sys/class/cxl/<card>/reset
-Date: October 2014
-Contact: linuxppc-dev@lists.ozlabs.org
-Description: write only
- Writing 1 will issue a PERST to card which may cause the card
- to reload the FPGA depending on load_image_on_perst.
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
index ee39acacf6f8..df8ba88b9f6a 100644
--- a/Documentation/ABI/testing/sysfs-class-devfreq
+++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -7,6 +7,13 @@ Description:
The name of devfreq object denoted as ... is same as the
name of device using devfreq.
+What: /sys/class/devfreq/.../name
+Date: November 2019
+Contact: Chanwoo Choi <cw00.choi@samsung.com>
+Description:
+ The /sys/class/devfreq/.../name shows the name of device
+ of the corresponding devfreq object.
+
What: /sys/class/devfreq/.../governor
Date: September 2011
Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
@@ -30,38 +37,23 @@ Description:
The /sys/class/devfreq/.../target_freq shows the next governor
predicted target frequency of the corresponding devfreq object.
-What: /sys/class/devfreq/.../polling_interval
-Date: September 2011
-Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
-Description:
- The /sys/class/devfreq/.../polling_interval shows and sets
- the requested polling interval of the corresponding devfreq
- object. The values are represented in ms. If the value is
- less than 1 jiffy, it is considered to be 0, which means
- no polling. This value is meaningless if the governor is
- not polling; thus. If the governor is not using
- devfreq-provided central polling
- (/sys/class/devfreq/.../central_polling is 0), this value
- may be useless.
-
What: /sys/class/devfreq/.../trans_stat
Date: October 2012
Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
-Descrtiption:
- This ABI shows the statistics of devfreq behavior on a
- specific device. It shows the time spent in each state and
- the number of transitions between states.
+Description:
+ This ABI shows or clears the statistics of devfreq behavior
+ on a specific device. It shows the time spent in each state
+ and the number of transitions between states.
In order to activate this ABI, the devfreq target device
driver should provide the list of available frequencies
- with its profile.
+ with its profile. If need to reset the statistics of devfreq
+ behavior on a specific device, enter 0(zero) to 'trans_stat'
+ as following::
-What: /sys/class/devfreq/.../userspace/set_freq
-Date: September 2011
-Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
-Description:
- The /sys/class/devfreq/.../userspace/set_freq shows and
- sets the requested frequency for the devfreq object if
- userspace governor is in effect.
+ echo 0 > /sys/class/devfreq/.../trans_stat
+
+ If the transition table is bigger than PAGE_SIZE, reading
+ this will return an -EFBIG error.
What: /sys/class/devfreq/.../available_frequencies
Date: October 2012
@@ -98,3 +90,54 @@ Description:
frequency requested by governors and min_freq.
The max_freq overrides min_freq because max_freq may be
used to throttle devices to avoid overheating.
+
+What: /sys/class/devfreq/.../polling_interval
+Date: September 2011
+Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
+Description:
+ The /sys/class/devfreq/.../polling_interval shows and sets
+ the requested polling interval of the corresponding devfreq
+ object. The values are represented in ms. If the value is
+ less than 1 jiffy, it is considered to be 0, which means
+ no polling. This value is meaningless if the governor is
+ not polling.
+
+ A list of governors that support the node:
+ - simple_ondmenad
+ - tegra_actmon
+
+What: /sys/class/devfreq/.../userspace/set_freq
+Date: September 2011
+Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
+Description:
+ The /sys/class/devfreq/.../userspace/set_freq shows and
+ sets the requested frequency for the devfreq object if
+ userspace governor is in effect.
+
+ A list of governors that support the node:
+ - userspace
+
+What: /sys/class/devfreq/.../timer
+Date: July 2020
+Contact: Chanwoo Choi <cw00.choi@samsung.com>
+Description:
+ This ABI shows and stores the kind of work timer by users.
+ This work timer is used by devfreq workqueue in order to
+ monitor the device status such as utilization. The user
+ can change the work timer on runtime according to their demand
+ as following::
+
+ echo deferrable > /sys/class/devfreq/.../timer
+ echo delayed > /sys/class/devfreq/.../timer
+
+ A list of governors that support the node:
+ - simple_ondemand
+
+What: /sys/class/devfreq/.../related_cpus
+Date: June 2025
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description: The list of CPUs whose performance is closely related to the
+ frequency of this devfreq domain.
+
+ This file is only present if a specific devfreq device is
+ closely associated with a subset of CPUs.
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq-event b/Documentation/ABI/testing/sysfs-class-devfreq-event
new file mode 100644
index 000000000000..dbe48495e55a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-devfreq-event
@@ -0,0 +1,25 @@
+What: /sys/class/devfreq-event/event<x>/
+Date: January 2017
+Contact: Chanwoo Choi <cw00.choi@samsung.com>
+Description:
+ Provide a place in sysfs for the devfreq-event objects.
+ This allows accessing various devfreq-event specific variables.
+ The name of devfreq-event object denoted as 'event<x>' which
+ includes the unique number of 'x' for each devfreq-event object.
+
+What: /sys/class/devfreq-event/event<x>/name
+Date: January 2017
+Contact: Chanwoo Choi <cw00.choi@samsung.com>
+Description:
+ The /sys/class/devfreq-event/event<x>/name attribute contains
+ the name of the devfreq-event object. This attribute is
+ read-only.
+
+What: /sys/class/devfreq-event/event<x>/enable_count
+Date: January 2017
+Contact: Chanwoo Choi <cw00.choi@samsung.com>
+Description:
+ The /sys/class/devfreq-event/event<x>/enable_count attribute
+ contains the reference count to enable the devfreq-event
+ object. If the device is enabled, the value of attribute is
+ greater than zero.
diff --git a/Documentation/ABI/testing/sysfs-class-devlink b/Documentation/ABI/testing/sysfs-class-devlink
new file mode 100644
index 000000000000..8a21ce515f61
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-devlink
@@ -0,0 +1,130 @@
+What: /sys/class/devlink/.../
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ Provide a place in sysfs for the device link objects in the
+ kernel at any given time. The name of a device link directory,
+ denoted as ... above, is of the form <supplier>--<consumer>
+ where <supplier> is the supplier bus:device name and <consumer>
+ is the consumer bus:device name.
+
+What: /sys/class/devlink/.../auto_remove_on
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates if the device link will ever be
+ automatically removed by the driver core when the consumer and
+ supplier devices themselves are still present.
+
+ This will be one of the following strings:
+
+ - 'consumer unbind'
+ - 'supplier unbind'
+ - 'never'
+
+ 'consumer unbind' means the device link will be removed when
+ the consumer's driver is unbound from the consumer device.
+
+ 'supplier unbind' means the device link will be removed when
+ the supplier's driver is unbound from the supplier device.
+
+ 'never' means the device link will not be automatically removed
+ when as long as the supplier and consumer devices themselves
+ are still present.
+
+What: /sys/class/devlink/.../consumer
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file is a symlink to the consumer device's sysfs directory.
+
+What: /sys/class/devlink/.../runtime_pm
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates if the device link has any impact on the
+ runtime power management behavior of the consumer and supplier
+ devices. For example: Making sure the supplier doesn't enter
+ runtime suspend while the consumer is active.
+
+ This will be one of the following strings:
+
+ === ========================================
+ '0' Does not affect runtime power management
+ '1' Affects runtime power management
+ === ========================================
+
+What: /sys/class/devlink/.../status
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates the status of the device link. The status
+ of a device link is affected by whether the supplier and
+ consumer devices have been bound to their corresponding
+ drivers. The status of a device link also affects the binding
+ and unbinding of the supplier and consumer devices with their
+ drivers and also affects whether the software state of the
+ supplier device is synced with the hardware state of the
+ supplier device after boot up.
+ See also: sysfs-devices-state_synced.
+
+ This will be one of the following strings:
+
+ - 'not tracked'
+ - 'dormant'
+ - 'available'
+ - 'consumer probing'
+ - 'active'
+ - 'supplier unbinding'
+ - 'unknown'
+
+ 'not tracked' means this device link does not track the status
+ and has no impact on the binding, unbinding and syncing the
+ hardware and software device state.
+
+ 'dormant' means the supplier and the consumer devices have not
+ bound to their driver.
+
+ 'available' means the supplier has bound to its driver and is
+ available to supply resources to the consumer device.
+
+ 'consumer probing' means the consumer device is currently
+ trying to bind to its driver.
+
+ 'active' means the supplier and consumer devices have both
+ bound successfully to their drivers.
+
+ 'supplier unbinding' means the supplier devices is currently in
+ the process of unbinding from its driver.
+
+ 'unknown' means the state of the device link is not any of the
+ above. If this is ever the value, there's a bug in the kernel.
+
+What: /sys/class/devlink/.../supplier
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file is a symlink to the supplier device's sysfs directory.
+
+What: /sys/class/devlink/.../sync_state_only
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ This file indicates if the device link is limited to only
+ affecting the syncing of the hardware and software state of the
+ supplier device.
+
+ This will be one of the following strings:
+
+ === ================================
+ '0'
+ '1' Affects runtime power management
+ === ================================
+
+ '0' means the device link can affect other device behaviors
+ like binding/unbinding, suspend/resume, runtime power
+ management, etc.
+
+ '1' means the device link will only affect the syncing of
+ hardware and software state of the supplier device after boot
+ up and doesn't not affect other behaviors of the devices.
diff --git a/Documentation/ABI/testing/sysfs-class-drm b/Documentation/ABI/testing/sysfs-class-drm
new file mode 100644
index 000000000000..d23fed5e29a7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-drm
@@ -0,0 +1,8 @@
+What: /sys/class/drm/.../boot_display
+Date: January 2026
+Contact: Linux DRI developers <dri-devel@vger.kernel.org>
+Description:
+ This file indicates that displays connected to the device were
+ used to display the boot sequence. If a display connected to
+ the device was used to display the boot sequence the file will
+ be present and contain "1".
diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon
index 57a726232912..f8e705375b24 100644
--- a/Documentation/ABI/testing/sysfs-class-extcon
+++ b/Documentation/ABI/testing/sysfs-class-extcon
@@ -39,19 +39,22 @@ Description:
callback.
If the default callback for showing function is used, the
- format is like this:
- # cat state
- USB_OTG=1
- HDMI=0
- TA=1
- EAR_JACK=0
- #
+ format is like this::
+
+ # cat state
+ USB_OTG=1
+ HDMI=0
+ TA=1
+ EAR_JACK=0
+ #
+
In this example, the extcon device has USB_OTG and TA
cables attached and HDMI and EAR_JACK cables detached.
In order to update the state of an extcon device, enter a hex
- state number starting with 0x:
- # echo 0xHEX > state
+ state number starting with 0x::
+
+ # echo 0xHEX > state
This updates the whole state of the extcon device.
Inputs of all the methods are required to meet the
@@ -62,19 +65,19 @@ Description:
interface associated with each cable cannot update
multiple cable states of an extcon device simultaneously.
-What: /sys/class/extcon/.../cable.x/name
+What: /sys/class/extcon/.../cable.X/name
Date: February 2012
Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
Description:
- The /sys/class/extcon/.../cable.x/name shows the name of cable
- "x" (integer between 0 and 31) of an extcon device.
+ The /sys/class/extcon/.../cable.X/name shows the name of cable
+ "X" (integer between 0 and 31) of an extcon device.
-What: /sys/class/extcon/.../cable.x/state
+What: /sys/class/extcon/.../cable.X/state
Date: February 2012
Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
Description:
- The /sys/class/extcon/.../cable.x/state shows and stores the
- state of cable "x" (integer between 0 and 31) of an extcon
+ The /sys/class/extcon/.../cable.X/state shows and stores the
+ state of cable "X" (integer between 0 and 31) of an extcon
device. The state value is either 0 (detached) or 1
(attached).
@@ -84,12 +87,13 @@ Contact: MyungJoo Ham <myungjoo.ham@samsung.com>
Description:
Shows the relations of mutually exclusiveness. For example,
if the mutually_exclusive array of extcon device is
- {0x3, 0x5, 0xC, 0x0}, then the output is:
- # ls mutually_exclusive/
- 0x3
- 0x5
- 0xc
- #
+ {0x3, 0x5, 0xC, 0x0}, then the output is::
+
+ # ls mutually_exclusive/
+ 0x3
+ 0x5
+ 0xc
+ #
Note that mutually_exclusive is a sub-directory of the extcon
device and the file names under the mutually_exclusive
diff --git a/Documentation/ABI/testing/sysfs-class-fc b/Documentation/ABI/testing/sysfs-class-fc
new file mode 100644
index 000000000000..3057a6d3b8cf
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fc
@@ -0,0 +1,27 @@
+What: /sys/class/fc/fc_udev_device/appid_store
+Date: Aug 2021
+Contact: Muneendra Kumar <muneendra.kumar@broadconm.com>
+Description:
+ This interface allows an admin to set an FC application
+ identifier in the blkcg associated with a cgroup id. The
+ identifier is typically a UUID that is associated with
+ an application or logical entity such as a virtual
+ machine or container group. The application or logical
+ entity utilizes a block device via the cgroup id.
+ FC adapter drivers may query the identifier and tag FC
+ traffic based on the identifier. FC host and FC fabric
+ entities can utilize the application id and FC traffic
+ tag to identify traffic sources.
+
+ The interface expects a string "<cgroupid>:<appid>" where:
+ <cgroupid> is inode of the cgroup in hexadecimal
+ <appid> is user provided string upto 128 characters
+ in length.
+
+ If an appid_store is done for a cgroup id that already
+ has an appid set, the new value will override the
+ previous value.
+
+ If an admin wants to remove an FC application identifier
+ from a cgroup, an appid_store should be done with the
+ following string: "<cgroupid>:"
diff --git a/Documentation/ABI/testing/sysfs-class-fc_host b/Documentation/ABI/testing/sysfs-class-fc_host
new file mode 100644
index 000000000000..0a696cbd8232
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fc_host
@@ -0,0 +1,23 @@
+What: /sys/class/fc_host/hostX/statistics/fpin_cn_yyy
+Date: July 2020
+Contact: Shyam Sundar <ssundar@marvell.com>
+Description:
+ These files contain the number of congestion notification
+ events recorded by the F_Port, reported using fabric
+ performance impact notification (FPIN) event.
+
+What: /sys/class/fc_host/hostX/statistics/fpin_li_yyy
+Date: July 2020
+Contact: Shyam Sundar <ssundar@marvell.com>
+Description:
+ These files contain the number of link integrity error
+ events recorded by the F_Port/Nx_Port, reported using fabric
+ performance impact notification (FPIN) event.
+
+What: /sys/class/fc_host/hostX/statistics/fpin_dn_yyy
+Date: July 2020
+Contact: Shyam Sundar <ssundar@marvell.com>
+Description:
+ These files contain the number of delivery related errors
+ recorded by the F_Port/Nx_Port, reported using fabric
+ performance impact notification (FPIN) event.
diff --git a/Documentation/ABI/testing/sysfs-class-fc_remote_ports b/Documentation/ABI/testing/sysfs-class-fc_remote_ports
new file mode 100644
index 000000000000..55a951529e03
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fc_remote_ports
@@ -0,0 +1,23 @@
+What: /sys/class/fc_remote_ports/rport-X:Y-Z/statistics/fpin_cn_yyy
+Date: July 2020
+Contact: Shyam Sundar <ssundar@marvell.com>
+Description:
+ These files contain the number of congestion notification
+ events recorded by the F_Port/Nx_Port, reported using fabric
+ performance impact notification (FPIN) event.
+
+What: /sys/class/fc_remote_ports/rport-X:Y-Z/statistics/fpin_li_yyy
+Date: July 2020
+Contact: Shyam Sundar <ssundar@marvell.com>
+Description:
+ These files contain the number of link integrity error
+ events recorded by the F_Port/Nx_Port, reported using fabric
+ performance impact notification (FPIN) event.
+
+What: /sys/class/fc_remote_ports/rport-X:Y-Z/statistics/fpin_dn_yyy
+Date: July 2020
+Contact: Shyam Sundar <ssundar@marvell.com>
+Description:
+ These files contain the number of delivery related errors
+ recorded by the F_Port/Nx_Port, reported using fabric
+ performance impact notification (FPIN) event.
diff --git a/Documentation/ABI/testing/sysfs-class-firmware b/Documentation/ABI/testing/sysfs-class-firmware
new file mode 100644
index 000000000000..fba87a55f3ca
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-firmware
@@ -0,0 +1,77 @@
+What: /sys/class/firmware/.../data
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: The data sysfs file is used for firmware-fallback and for
+ firmware uploads. Cat a firmware image to this sysfs file
+ after you echo 1 to the loading sysfs file. When the firmware
+ image write is complete, echo 0 to the loading sysfs file. This
+ sequence will signal the completion of the firmware write and
+ signal the lower-level driver that the firmware data is
+ available.
+
+What: /sys/class/firmware/.../cancel
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: Write-only. For firmware uploads, write a "1" to this file to
+ request that the transfer of firmware data to the lower-level
+ device be canceled. This request will be rejected (EBUSY) if
+ the update cannot be canceled (e.g. a FLASH write is in
+ progress) or (ENODEV) if there is no firmware update in progress.
+
+What: /sys/class/firmware/.../error
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: Read-only. Returns a string describing a failed firmware
+ upload. This string will be in the form of <STATUS>:<ERROR>,
+ where <STATUS> will be one of the status strings described
+ for the status sysfs file and <ERROR> will be one of the
+ following: "hw-error", "timeout", "user-abort", "device-busy",
+ "invalid-file-size", "read-write-error", "flash-wearout". The
+ error sysfs file is only meaningful when the current firmware
+ upload status is "idle". If this file is read while a firmware
+ transfer is in progress, then the read will fail with EBUSY.
+
+What: /sys/class/firmware/.../loading
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: The loading sysfs file is used for both firmware-fallback and
+ for firmware uploads. Echo 1 onto the loading file to indicate
+ you are writing a firmware file to the data sysfs node. Echo
+ -1 onto this file to abort the data write or echo 0 onto this
+ file to indicate that the write is complete. For firmware
+ uploads, the zero value also triggers the transfer of the
+ firmware data to the lower-level device driver.
+
+What: /sys/class/firmware/.../remaining_size
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: Read-only. For firmware upload, this file contains the size
+ of the firmware data that remains to be transferred to the
+ lower-level device driver. The size value is initialized to
+ the full size of the firmware image that was previously
+ written to the data sysfs file. This value is periodically
+ updated during the "transferring" phase of the firmware
+ upload.
+ Format: "%u".
+
+What: /sys/class/firmware/.../status
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: Read-only. Returns a string describing the current status of
+ a firmware upload. The string will be one of the following:
+ idle, "receiving", "preparing", "transferring", "programming".
+
+What: /sys/class/firmware/.../timeout
+Date: July 2022
+KernelVersion: 5.19
+Contact: Russ Weight <russ.weight@linux.dev>
+Description: This file supports the timeout mechanism for firmware
+ fallback. This file has no affect on firmware uploads. For
+ more information on timeouts please see the documentation
+ for firmware fallback.
diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes
new file mode 100644
index 000000000000..2713efa509b4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes
@@ -0,0 +1,494 @@
+What: /sys/class/firmware-attributes/*/attributes/*/
+Date: February 2021
+KernelVersion: 5.11
+Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
+ Prasanth KSR <prasanth.ksr@dell.com>
+ Dell.Client.Kernel@dell.com
+Description:
+ A sysfs interface for systems management software to enable
+ configuration capability on supported systems. This directory
+ exposes interfaces for interacting with configuration options.
+
+ Unless otherwise specified in an attribute description all attributes are optional
+ and will accept UTF-8 input.
+
+ type:
+ A file that can be read to obtain the type of attribute.
+ This attribute is mandatory.
+
+ The following are known types:
+
+ - enumeration: a set of pre-defined valid values
+ - integer: a range of numerical values
+ - string
+
+ HP specific types
+ -----------------
+ - ordered-list - a set of ordered list valid values
+
+
+ All attribute types support the following values:
+
+ current_value:
+ A file that can be read to obtain the current
+ value of the <attr>.
+
+ This file can also be written to in order to update the value of a
+ <attr>
+
+ This attribute is mandatory.
+
+ default_value:
+ A file that can be read to obtain the default
+ value of the <attr>
+
+ display_name:
+ A file that can be read to obtain a user friendly
+ description of the at <attr>
+
+ display_name_language_code:
+ A file that can be read to obtain
+ the IETF language tag corresponding to the
+ "display_name" of the <attr>
+
+ "enumeration"-type specific properties:
+
+ possible_values:
+ A file that can be read to obtain the possible
+ values of the <attr>. Values are separated using
+ semi-colon (``;``).
+
+ "integer"-type specific properties:
+
+ min_value:
+ A file that can be read to obtain the lower
+ bound value of the <attr>
+
+ max_value:
+ A file that can be read to obtain the upper
+ bound value of the <attr>
+
+ scalar_increment:
+ A file that can be read to obtain the scalar value used for
+ increments of current_value this attribute accepts.
+
+ "string"-type specific properties:
+
+ max_length:
+ A file that can be read to obtain the maximum
+ length value of the <attr>
+
+ min_length:
+ A file that can be read to obtain the minimum
+ length value of the <attr>
+
+ Dell specific class extensions
+ ------------------------------
+
+ On Dell systems the following additional attributes are available:
+
+ dell_modifier:
+ A file that can be read to obtain attribute-level
+ dependency rule. It says an attribute X will become read-only or
+ suppressed, if/if-not attribute Y is configured.
+
+ modifier rules can be in following format::
+
+ [ReadOnlyIf:<attribute>=<value>]
+ [ReadOnlyIfNot:<attribute>=<value>]
+ [SuppressIf:<attribute>=<value>]
+ [SuppressIfNot:<attribute>=<value>]
+
+ For example::
+
+ AutoOnFri/dell_modifier has value,
+ [SuppressIfNot:AutoOn=SelectDays]
+
+ This means AutoOnFri will be suppressed in BIOS setup if AutoOn
+ attribute is not "SelectDays" and its value will not be effective
+ through sysfs until this rule is met.
+
+ Enumeration attributes also support the following:
+
+ dell_value_modifier:
+ A file that can be read to obtain value-level dependency.
+ This file is similar to dell_modifier but here, an
+ attribute's current value will be forcefully changed based
+ dependent attributes value.
+
+ dell_value_modifier rules can be in following format::
+
+ <value>[ForceIf:<attribute>=<value>]
+ <value>[ForceIfNot:<attribute>=<value>]
+
+ For example::
+
+ LegacyOrom/dell_value_modifier has value:
+ Disabled[ForceIf:SecureBoot=Enabled]
+
+ This means LegacyOrom's current value will be forced to
+ "Disabled" in BIOS setup if SecureBoot is Enabled and its
+ value will not be effective through sysfs until this rule is
+ met.
+
+ HP specific class extensions
+ ------------------------------
+
+ On HP systems the following additional attributes are available:
+
+ "ordered-list"-type specific properties:
+
+ elements:
+ A file that can be read to obtain the possible
+ list of values of the <attr>. Values are separated using
+ semi-colon (``;``) and listed according to their priority.
+ An element listed first has the highest priority. Writing
+ the list in a different order to current_value alters
+ the priority order for the particular attribute.
+
+What: /sys/class/firmware-attributes/*/authentication/
+Date: February 2021
+KernelVersion: 5.11
+Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
+ Prasanth KSR <prasanth.ksr@dell.com>
+ Dell.Client.Kernel@dell.com
+Description:
+ Devices support various authentication mechanisms which can be exposed
+ as a separate configuration object.
+
+ For example a "BIOS Admin" password and "System" Password can be set,
+ reset or cleared using these attributes.
+
+ - An "Admin" password is used for preventing modification to the BIOS
+ settings.
+ - A "System" password is required to boot a machine.
+
+ Change in any of these two authentication methods will also generate an
+ uevent KOBJ_CHANGE.
+
+ is_enabled:
+ A file that can be read to obtain a 0/1 flag to see if
+ <attr> authentication is enabled.
+ This attribute is mandatory.
+
+ role:
+ The type of authentication used.
+ This attribute is mandatory.
+
+ Known types:
+ bios-admin:
+ Representing BIOS administrator password
+ power-on:
+ Representing a password required to use
+ the system
+ system-mgmt:
+ Representing System Management password.
+ See Lenovo extensions section for details
+ HDD:
+ Representing HDD password
+ See Lenovo extensions section for details
+ NVMe:
+ Representing NVMe password
+ See Lenovo extensions section for details
+
+ mechanism:
+ The means of authentication. This attribute is mandatory.
+ Supported types are "password" or "certificate".
+
+ max_password_length:
+ A file that can be read to obtain the
+ maximum length of the Password
+
+ min_password_length:
+ A file that can be read to obtain the
+ minimum length of the Password
+
+ current_password:
+ A write only value used for privileged access such as
+ setting attributes when a system or admin password is set
+ or resetting to a new password
+
+ This attribute is mandatory when mechanism == "password".
+
+ new_password:
+ A write only value that when used in tandem with
+ current_password will reset a system or admin password.
+
+ Note, password management is session specific. If Admin password is set,
+ same password must be written into current_password file (required for
+ password-validation) and must be cleared once the session is over.
+ For example::
+
+ echo "password" > current_password
+ echo "disabled" > TouchScreen/current_value
+ echo "" > current_password
+
+ Drivers may emit a CHANGE uevent when a password is set or unset
+ userspace may check it again.
+
+ On Dell, Lenovo and HP systems, if Admin password is set, then all BIOS attributes
+ require password validation.
+ On Lenovo systems if you change the Admin password the new password is not active until
+ the next boot.
+
+ Lenovo specific class extensions
+ --------------------------------
+
+ On Lenovo systems the following additional settings are available:
+
+ role: system-mgmt This gives the same authority as the bios-admin password to control
+ security related features. The authorities allocated can be set via
+ the BIOS menu SMP Access Control Policy
+
+ role: HDD & NVMe This password is used to unlock access to the drive at boot. Note see
+ 'level' and 'index' extensions below.
+
+ lenovo_encoding:
+ The encoding method that is used. This can be either "ascii"
+ or "scancode". Default is set to "ascii"
+
+ lenovo_kbdlang:
+ The keyboard language method that is used. This is generally a
+ two char code (e.g. "us", "fr", "gr") and may vary per platform.
+ Default is set to "us"
+
+ level:
+ Available for HDD and NVMe authentication to set 'user' or 'master'
+ privilege level.
+ If only the user password is configured then this should be used to
+ unlock the drive at boot. If both master and user passwords are set
+ then either can be used. If a master password is set a user password
+ is required.
+ This attribute defaults to 'user' level
+
+ index:
+ Used with HDD and NVME authentication to set the drive index
+ that is being referenced (e.g hdd1, hdd2 etc)
+ This attribute defaults to device 1.
+
+ certificate, signature, save_signature:
+ These attributes are used for certificate based authentication. This is
+ used in conjunction with a signing server as an alternative to password
+ based authentication.
+ The user writes to the attribute(s) with a BASE64 encoded string obtained
+ from the signing server.
+ The attributes can be displayed to check the stored value.
+
+ Some usage examples:
+
+ Installing a certificate to enable feature::
+
+ echo "supervisor password" > authentication/Admin/current_password
+ echo "signed certificate" > authentication/Admin/certificate
+
+ Updating the installed certificate::
+
+ echo "signature" > authentication/Admin/signature
+ echo "signed certificate" > authentication/Admin/certificate
+
+ Removing the installed certificate::
+
+ echo "signature" > authentication/Admin/signature
+ echo "" > authentication/Admin/certificate
+
+ Changing a BIOS setting::
+
+ echo "signature" > authentication/Admin/signature
+ echo "save signature" > authentication/Admin/save_signature
+ echo Enable > attribute/PasswordBeep/current_value
+
+ You cannot enable certificate authentication if a supervisor password
+ has not been set.
+ Clearing the certificate results in no bios-admin authentication method
+ being configured allowing anyone to make changes.
+ After any of these operations the system must reboot for the changes to
+ take effect.
+ Admin and System certificates are supported from 2025 systems onward.
+
+ certificate_thumbprint:
+ Read only attribute used to display the MD5, SHA1 and SHA256 thumbprints
+ for the certificate installed in the BIOS.
+
+ certificate_to_password:
+ Write only attribute used to switch from certificate based authentication
+ back to password based.
+ Usage::
+
+ echo "signature" > authentication/Admin/signature
+ echo "password" > authentication/Admin/certificate_to_password
+
+ HP specific class extensions
+ --------------------------------
+
+ On HP systems the following additional settings are available:
+
+ role: enhanced-bios-auth:
+ This role is specific to Secure Platform Management (SPM) attribute.
+ It requires configuring an endorsement (kek) and signing certificate (sk).
+
+
+What: /sys/class/firmware-attributes/*/attributes/pending_reboot
+Date: February 2021
+KernelVersion: 5.11
+Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
+ Prasanth KSR <prasanth.ksr@dell.com>
+ Dell.Client.Kernel@dell.com
+Description:
+ A read-only attribute reads 1 if a reboot is necessary to apply
+ pending BIOS attribute changes. Also, an uevent_KOBJ_CHANGE is
+ generated when it changes to 1.
+
+ == =========================================
+ 0 All BIOS attributes setting are current
+ 1 A reboot is necessary to get pending BIOS
+ attribute changes applied
+ == =========================================
+
+ Note, userspace applications need to follow below steps for efficient
+ BIOS management,
+
+ 1. Check if admin password is set. If yes, follow session method for
+ password management as briefed under authentication section above.
+ 2. Before setting any attribute, check if it has any modifiers
+ or value_modifiers. If yes, incorporate them and then modify
+ attribute.
+
+ Drivers may emit a CHANGE uevent when this value changes and userspace
+ may check it again.
+
+What: /sys/class/firmware-attributes/*/attributes/reset_bios
+Date: February 2021
+KernelVersion: 5.11
+Contact: Divya Bharathi <Divya.Bharathi@Dell.com>,
+ Prasanth KSR <prasanth.ksr@dell.com>
+ Dell.Client.Kernel@dell.com
+Description:
+ This attribute can be used to reset the BIOS Configuration.
+ Specifically, it tells which type of reset BIOS configuration is being
+ requested on the host.
+
+ Reading from it returns a list of supported options encoded as:
+
+ - 'builtinsafe' (Built in safe configuration profile)
+ - 'lastknowngood' (Last known good saved configuration profile)
+ - 'factory' (Default factory settings configuration profile)
+ - 'custom' (Custom saved configuration profile)
+
+ The currently selected option is printed in square brackets as
+ shown below::
+
+ # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
+ # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
+ builtinsafe lastknowngood [factory] custom
+
+ Note that any changes to this attribute requires a reboot
+ for changes to take effect.
+
+What: /sys/class/firmware-attributes/*/attributes/save_settings
+Date: August 2023
+KernelVersion: 6.6
+Contact: Mark Pearson <mpearson-lenovo@squebb.ca>
+Description:
+ On Lenovo platforms there is a limitation in the number of times an attribute can be
+ saved. This is an architectural limitation and it limits the number of attributes
+ that can be modified to 48.
+ A solution for this is instead of the attribute being saved after every modification,
+ to allow a user to bulk set the attributes, and then trigger a final save. This allows
+ unlimited attributes.
+
+ Read the attribute to check what save mode is enabled (single or bulk).
+ E.g:
+ # cat /sys/class/firmware-attributes/thinklmi/attributes/save_settings
+ single
+
+ Write the attribute with 'bulk' to enable bulk save mode.
+ Write the attribute with 'single' to enable saving, after every attribute set.
+ The default setting is single mode.
+ E.g:
+ # echo bulk > /sys/class/firmware-attributes/thinklmi/attributes/save_settings
+
+ When in bulk mode write 'save' to trigger a save of all currently modified attributes.
+ Note, once a save has been triggered, in bulk mode, attributes can no longer be set and
+ will return a permissions error. This is to prevent users hitting the 48+ save limitation
+ (which requires entering the BIOS to clear the error condition)
+ E.g:
+ # echo save > /sys/class/firmware-attributes/thinklmi/attributes/save_settings
+
+What: /sys/class/firmware-attributes/*/attributes/debug_cmd
+Date: July 2021
+KernelVersion: 5.14
+Contact: Mark Pearson <markpearson@lenovo.com>
+Description:
+ This write only attribute can be used to send debug commands to the BIOS.
+ This should only be used when recommended by the BIOS vendor. Vendors may
+ use it to enable extra debug attributes or BIOS features for testing purposes.
+
+ Note that any changes to this attribute requires a reboot for changes to take effect.
+
+
+ HP specific class extensions - Secure Platform Manager (SPM)
+ --------------------------------
+
+What: /sys/class/firmware-attributes/*/authentication/SPM/kek
+Date: March 2023
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@hp.com>
+Description:
+ 'kek' Key-Encryption-Key is a write-only file that can be used to configure the
+ RSA public key that will be used by the BIOS to verify
+ signatures when setting the signing key. When written,
+ the bytes should correspond to the KEK certificate
+ (x509 .DER format containing an OU). The size of the
+ certificate must be less than or equal to 4095 bytes.
+
+What: /sys/class/firmware-attributes/*/authentication/SPM/sk
+Date: March 2023
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@hp.com>
+Description:
+ 'sk' Signature Key is a write-only file that can be used to configure the RSA
+ public key that will be used by the BIOS to verify signatures
+ when configuring BIOS settings and security features. When
+ written, the bytes should correspond to the modulus of the
+ public key. The exponent is assumed to be 0x10001.
+
+What: /sys/class/firmware-attributes/*/authentication/SPM/status
+Date: March 2023
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@hp.com>
+Description:
+ 'status' is a read-only file that returns ASCII text in JSON format reporting
+ the status information.
+
+ "State": "not provisioned | provisioned | provisioning in progress",
+ "Version": "Major.Minor",
+ "Nonce": <16-bit unsigned number display in base 10>,
+ "FeaturesInUse": <16-bit unsigned number display in base 10>,
+ "EndorsementKeyMod": "<256 bytes in base64>",
+ "SigningKeyMod": "<256 bytes in base64>"
+
+What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entries
+Date: March 2023
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@hp.com>
+Description:
+ 'audit_log_entries' is a read-only file that returns the events in the log.
+
+ Audit log entry format
+
+ Byte 0-15: Requested Audit Log entry (Each Audit log is 16 bytes)
+ Byte 16-127: Unused
+
+What: /sys/class/firmware-attributes/*/attributes/Sure_Start/audit_log_entry_count
+Date: March 2023
+KernelVersion: 5.18
+Contact: "Jorge Lopez" <jorge.lopez2@hp.com>
+Description:
+ 'audit_log_entry_count' is a read-only file that returns the number of existing
+ audit log events available to be read. Values are separated using comma. (``,``)
+
+ [No of entries],[log entry size],[Max number of entries supported]
+
+ log entry size identifies audit log size for the current BIOS version.
+ The current size is 16 bytes but it can be up to 128 bytes long in future BIOS
+ versions.
diff --git a/Documentation/ABI/testing/sysfs-class-fpga-bridge b/Documentation/ABI/testing/sysfs-class-fpga-bridge
new file mode 100644
index 000000000000..312ae2c579d8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fpga-bridge
@@ -0,0 +1,11 @@
+What: /sys/class/fpga_bridge/<bridge>/name
+Date: January 2016
+KernelVersion: 4.5
+Contact: Alan Tull <atull@opensource.altera.com>
+Description: Name of low level FPGA bridge driver.
+
+What: /sys/class/fpga_bridge/<bridge>/state
+Date: January 2016
+KernelVersion: 4.5
+Contact: Alan Tull <atull@opensource.altera.com>
+Description: Show bridge state as "enabled" or "disabled"
diff --git a/Documentation/ABI/testing/sysfs-class-fpga-manager b/Documentation/ABI/testing/sysfs-class-fpga-manager
new file mode 100644
index 000000000000..d78689c357a5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fpga-manager
@@ -0,0 +1,60 @@
+What: /sys/class/fpga_manager/<fpga>/name
+Date: August 2015
+KernelVersion: 4.3
+Contact: Alan Tull <atull@opensource.altera.com>
+Description: Name of low level fpga manager driver.
+
+What: /sys/class/fpga_manager/<fpga>/state
+Date: August 2015
+KernelVersion: 4.3
+Contact: Alan Tull <atull@opensource.altera.com>
+Description: Read fpga manager state as a string.
+ The intent is to provide enough detail that if something goes
+ wrong during FPGA programming (something that the driver can't
+ fix) then userspace can know, i.e. if the firmware request
+ fails, that could be due to not being able to find the firmware
+ file.
+
+ This is a superset of FPGA states and fpga manager driver
+ states. The fpga manager driver is walking through these steps
+ to get the FPGA into a known operating state. It's a sequence,
+ though some steps may get skipped. Valid FPGA states will vary
+ by manufacturer; this is a superset.
+
+ * unknown = can't determine state
+ * power off = FPGA power is off
+ * power up = FPGA reports power is up
+ * reset = FPGA held in reset state
+ * firmware request = firmware class request in progress
+ * firmware request error = firmware request failed
+ * write init = preparing FPGA for programming
+ * write init error = Error while preparing FPGA for programming
+ * write = FPGA ready to receive image data
+ * write error = Error while programming
+ * write complete = Doing post programming steps
+ * write complete error = Error while doing post programming
+ * operating = FPGA is programmed and operating
+
+What: /sys/class/fpga_manager/<fpga>/status
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read fpga manager status as a string.
+ If FPGA programming operation fails, it could be caused by crc
+ error or incompatible bitstream image. The intent of this
+ interface is to provide more detailed information for FPGA
+ programming errors to userspace. This is a list of strings for
+ the supported status.
+
+ * reconfig operation error - invalid operations detected by
+ reconfiguration hardware.
+ e.g. start reconfiguration
+ with errors not cleared
+ * reconfig CRC error - CRC error detected by
+ reconfiguration hardware.
+ * reconfig incompatible image - reconfiguration image is
+ incompatible with hardware
+ * reconfig IP protocol error - protocol errors detected by
+ reconfiguration hardware
+ * reconfig fifo overflow error - FIFO overflow detected by
+ reconfiguration hardware
diff --git a/Documentation/ABI/testing/sysfs-class-fpga-region b/Documentation/ABI/testing/sysfs-class-fpga-region
new file mode 100644
index 000000000000..bc7ec644acc9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-fpga-region
@@ -0,0 +1,9 @@
+What: /sys/class/fpga_region/<region>/compat_id
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: FPGA region id for compatibility check, e.g. compatibility
+ of the FPGA reconfiguration hardware and image. This value
+ is defined or calculated by the layer that is creating the
+ FPGA region. This interface returns the compat_id value or
+ just error code -ENOENT in case compat_id is not used.
diff --git a/Documentation/ABI/testing/sysfs-class-gnss b/Documentation/ABI/testing/sysfs-class-gnss
new file mode 100644
index 000000000000..9650f3a7fc03
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-gnss
@@ -0,0 +1,17 @@
+What: /sys/class/gnss/gnss<N>/type
+Date: May 2018
+KernelVersion: 4.18
+Contact: Johan Hovold <johan@kernel.org>
+Description:
+ The GNSS receiver type. The currently identified types reflect
+ the protocol(s) supported by the receiver:
+
+ ====== ===========
+ "NMEA" NMEA 0183
+ "SiRF" SiRF Binary
+ "UBX" UBX
+ ====== ===========
+
+ Note that also non-"NMEA" type receivers typically support a
+ subset of NMEA 0183 with vendor extensions (e.g. to allow
+ switching to a vendor protocol).
diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon
new file mode 100644
index 000000000000..cfd0d0bab483
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-hwmon
@@ -0,0 +1,1075 @@
+What: /sys/class/hwmon/hwmonX/name
+Description:
+ The chip name.
+ This should be a short, lowercase string, not containing
+ whitespace, dashes, or the wildcard character '*'.
+ This attribute represents the chip name. It is the only
+ mandatory attribute.
+ I2C devices get this attribute created automatically.
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/label
+Description:
+ A descriptive label that allows to uniquely identify a
+ device within the system.
+ The contents of the label are free-form.
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/update_interval
+Description:
+ The interval at which the chip will update readings.
+ Unit: millisecond
+
+ RW
+
+ Some devices have a variable update rate or interval.
+ This attribute can be used to change it to the desired value.
+
+What: /sys/class/hwmon/hwmonX/inY_min
+Description:
+ Voltage min value.
+
+ Unit: millivolt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/inY_lcrit
+Description:
+ Voltage critical min value.
+
+ Unit: millivolt
+
+ RW
+
+ If voltage drops to or below this limit, the system may
+ take drastic action such as power down or reset. At the very
+ least, it should report a fault.
+
+What: /sys/class/hwmon/hwmonX/inY_max
+Description:
+ Voltage max value.
+
+ Unit: millivolt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/inY_crit
+Description:
+ Voltage critical max value.
+
+ Unit: millivolt
+
+ RW
+
+ If voltage reaches or exceeds this limit, the system may
+ take drastic action such as power down or reset. At the very
+ least, it should report a fault.
+
+What: /sys/class/hwmon/hwmonX/inY_input
+Description:
+ Voltage input value.
+
+ Unit: millivolt
+
+ RO
+
+ Voltage measured on the chip pin.
+
+ Actual voltage depends on the scaling resistors on the
+ motherboard, as recommended in the chip datasheet.
+
+ This varies by chip and by motherboard.
+ Because of this variation, values are generally NOT scaled
+ by the chip driver, and must be done by the application.
+ However, some drivers (notably lm87 and via686a)
+ do scale, because of internal resistors built into a chip.
+ These drivers will output the actual voltage. Rule of
+ thumb: drivers should report the voltage values at the
+ "pins" of the chip.
+
+What: /sys/class/hwmon/hwmonX/inY_average
+Description:
+ Average voltage
+
+ Unit: millivolt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/inY_lowest
+Description:
+ Historical minimum voltage
+
+ Unit: millivolt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/inY_highest
+Description:
+ Historical maximum voltage
+
+ Unit: millivolt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/inY_reset_history
+Description:
+ Reset inX_lowest and inX_highest
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/in_reset_history
+Description:
+ Reset inX_lowest and inX_highest for all sensors
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/inY_label
+Description:
+ Suggested voltage channel label.
+
+ Text string
+
+ Should only be created if the driver has hints about what
+ this voltage channel is being used for, and user-space
+ doesn't. In all other cases, the label is provided by
+ user-space.
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/inY_enable
+Description:
+ Enable or disable the sensors.
+
+ When disabled the sensor read will return -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/inY_fault
+Description:
+ Reports a voltage hard failure (eg: shorted component)
+
+ - 1: Failed
+ - 0: Ok
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/cpuY_vid
+Description:
+ CPU core reference voltage.
+
+ Unit: millivolt
+
+ RO
+
+ Not always correct.
+
+What: /sys/class/hwmon/hwmonX/vrm
+Description:
+ Voltage Regulator Module version number.
+
+ RW (but changing it should no more be necessary)
+
+ Originally the VRM standard version multiplied by 10, but now
+ an arbitrary number, as not all standards have a version
+ number.
+
+ Affects the way the driver calculates the CPU core reference
+ voltage from the vid pins.
+
+What: /sys/class/hwmon/hwmonX/inY_rated_min
+Description:
+ Minimum rated voltage.
+
+ Unit: millivolt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/inY_rated_max
+Description:
+ Maximum rated voltage.
+
+ Unit: millivolt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/fanY_min
+Description:
+ Fan minimum value
+
+ Unit: revolution/min (RPM)
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/fanY_max
+Description:
+ Fan maximum value
+
+ Unit: revolution/min (RPM)
+
+ Only rarely supported by the hardware.
+ RW
+
+What: /sys/class/hwmon/hwmonX/fanY_input
+Description:
+ Fan input value.
+
+ Unit: revolution/min (RPM)
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/fanY_div
+Description:
+ Fan divisor.
+
+ Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
+
+ RW
+
+ Some chips only support values 1, 2, 4 and 8.
+ Note that this is actually an internal clock divisor, which
+ affects the measurable speed range, not the read value.
+
+What: /sys/class/hwmon/hwmonX/fanY_pulses
+Description:
+ Number of tachometer pulses per fan revolution.
+
+ Integer value, typically between 1 and 4.
+
+ RW
+
+ This value is a characteristic of the fan connected to the
+ device's input, so it has to be set in accordance with the fan
+ model.
+
+ Should only be created if the chip has a register to configure
+ the number of pulses. In the absence of such a register (and
+ thus attribute) the value assumed by all devices is 2 pulses
+ per fan revolution.
+
+What: /sys/class/hwmon/hwmonX/fanY_target
+Description:
+ Desired fan speed
+
+ Unit: revolution/min (RPM)
+
+ RW
+
+ Only makes sense if the chip supports closed-loop fan speed
+ control based on the measured fan speed.
+
+What: /sys/class/hwmon/hwmonX/fanY_label
+Description:
+ Suggested fan channel label.
+
+ Text string
+
+ Should only be created if the driver has hints about what
+ this fan channel is being used for, and user-space doesn't.
+ In all other cases, the label is provided by user-space.
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/fanY_enable
+Description:
+ Enable or disable the sensors.
+
+ When disabled the sensor read will return -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/fanY_fault
+Description:
+ Reports if a fan has reported failure.
+
+ - 1: Failed
+ - 0: Ok
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/pwmY
+Description:
+ Pulse width modulation fan control.
+
+ Integer value in the range 0 to 255
+
+ RW
+
+ 255 is max or 100%.
+
+What: /sys/class/hwmon/hwmonX/pwmY_enable
+Description:
+ Fan speed control method:
+
+ - 0: no fan speed control (i.e. fan at full speed)
+ - 1: manual fan speed control enabled (using `pwmY`)
+ - 2+: automatic fan speed control enabled
+
+ Check individual chip documentation files for automatic mode
+ details.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/pwmY_mode
+Description:
+ - 0: DC mode (direct current)
+ - 1: PWM mode (pulse-width modulation)
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/pwmY_freq
+Description:
+ Base PWM frequency in Hz.
+
+ Only possibly available when pwmN_mode is PWM, but not always
+ present even then.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/pwmY_auto_channels_temp
+Description:
+ Select which temperature channels affect this PWM output in
+ auto mode.
+
+ Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
+ Which values are possible depend on the chip used.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/pwmY_auto_pointZ_pwm
+What: /sys/class/hwmon/hwmonX/pwmY_auto_pointZ_temp
+What: /sys/class/hwmon/hwmonX/pwmY_auto_pointZ_temp_hyst
+Description:
+ Define the PWM vs temperature curve.
+
+ Number of trip points is chip-dependent. Use this for chips
+ which associate trip points to PWM output channels.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_auto_pointZ_pwm
+What: /sys/class/hwmon/hwmonX/tempY_auto_pointZ_temp
+What: /sys/class/hwmon/hwmonX/tempY_auto_pointZ_temp_hyst
+Description:
+ Define the PWM vs temperature curve.
+
+ Number of trip points is chip-dependent. Use this for chips
+ which associate trip points to temperature channels.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_type
+Description:
+ Sensor type selection.
+
+ Integers 1 to 6
+
+ RW
+
+ - 1: CPU embedded diode
+ - 2: 3904 transistor
+ - 3: thermal diode
+ - 4: thermistor
+ - 5: AMD AMDSI
+ - 6: Intel PECI
+
+ Not all types are supported by all chips
+
+What: /sys/class/hwmon/hwmonX/tempY_max
+Description:
+ Temperature max value.
+
+ Unit: millidegree Celsius (or millivolt, see below)
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_max_alarm
+Description:
+ Maximum temperature alarm flag.
+
+ - 0: OK
+ - 1: temperature has reached tempY_max
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_min
+Description:
+ Temperature min value.
+
+ Unit: millidegree Celsius
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_min_alarm
+Description:
+ Minimum temperature alarm flag.
+
+ - 0: OK
+ - 1: temperature has reached tempY_min
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_max_hyst
+Description:
+ Temperature hysteresis value for max limit.
+
+ Unit: millidegree Celsius
+
+ Must be reported as an absolute temperature, NOT a delta
+ from the max value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_min_hyst
+Description:
+ Temperature hysteresis value for min limit.
+ Unit: millidegree Celsius
+
+ Must be reported as an absolute temperature, NOT a delta
+ from the min value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_input
+Description:
+ Temperature input value.
+
+ Unit: millidegree Celsius
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_crit
+Description:
+ Temperature critical max value, typically greater than
+ corresponding temp_max values.
+
+ Unit: millidegree Celsius
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_crit_alarm
+Description:
+ Critical high temperature alarm flag.
+
+ - 0: OK
+ - 1: temperature has reached tempY_crit
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_crit_hyst
+Description:
+ Temperature hysteresis value for critical limit.
+
+ Unit: millidegree Celsius
+
+ Must be reported as an absolute temperature, NOT a delta
+ from the critical value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_emergency
+Description:
+ Temperature emergency max value, for chips supporting more than
+ two upper temperature limits. Must be equal or greater than
+ corresponding temp_crit values.
+
+ Unit: millidegree Celsius
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_emergency_alarm
+Description:
+ Emergency high temperature alarm flag.
+
+ - 0: OK
+ - 1: temperature has reached tempY_emergency
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_emergency_hyst
+Description:
+ Temperature hysteresis value for emergency limit.
+
+ Unit: millidegree Celsius
+
+ Must be reported as an absolute temperature, NOT a delta
+ from the emergency value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_lcrit
+Description:
+ Temperature critical min value, typically lower than
+ corresponding temp_min values.
+
+ Unit: millidegree Celsius
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_lcrit_hyst
+Description:
+ Temperature hysteresis value for critical min limit.
+
+ Unit: millidegree Celsius
+
+ Must be reported as an absolute temperature, NOT a delta
+ from the critical min value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_offset
+Description:
+ Temperature offset which is added to the temperature reading
+ by the chip.
+
+ Unit: millidegree Celsius
+
+ Read/Write value.
+
+What: /sys/class/hwmon/hwmonX/tempY_label
+Description:
+ Suggested temperature channel label.
+
+ Text string
+
+ Should only be created if the driver has hints about what
+ this temperature channel is being used for, and user-space
+ doesn't. In all other cases, the label is provided by
+ user-space.
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_lowest
+Description:
+ Historical minimum temperature
+
+ Unit: millidegree Celsius
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_highest
+Description:
+ Historical maximum temperature
+
+ Unit: millidegree Celsius
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_reset_history
+Description:
+ Reset temp_lowest and temp_highest
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/temp_reset_history
+Description:
+ Reset temp_lowest and temp_highest for all sensors
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/tempY_enable
+Description:
+ Enable or disable the sensors.
+
+ When disabled the sensor read will return -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/tempY_rated_min
+Description:
+ Minimum rated temperature.
+
+ Unit: millidegree Celsius
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/tempY_rated_max
+Description:
+ Maximum rated temperature.
+
+ Unit: millidegree Celsius
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/currY_max
+Description:
+ Current max value
+
+ Unit: milliampere
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/currY_min
+Description:
+ Current min value.
+
+ Unit: milliampere
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/currY_lcrit
+Description:
+ Current critical low value
+
+ Unit: milliampere
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/currY_crit
+Description:
+ Current critical high value.
+
+ Unit: milliampere
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/currY_input
+Description:
+ Current input value
+
+ Unit: milliampere
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/currY_average
+Description:
+ Average current use
+
+ Unit: milliampere
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/currY_lowest
+Description:
+ Historical minimum current
+
+ Unit: milliampere
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/currY_highest
+Description:
+ Historical maximum current
+ Unit: milliampere
+ RO
+
+What: /sys/class/hwmon/hwmonX/currY_reset_history
+Description:
+ Reset currX_lowest and currX_highest
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/curr_reset_history
+Description:
+ Reset currX_lowest and currX_highest for all sensors
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/currY_enable
+Description:
+ Enable or disable the sensors.
+
+ When disabled the sensor read will return -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/currY_rated_min
+Description:
+ Minimum rated current.
+
+ Unit: milliampere
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/currY_rated_max
+Description:
+ Maximum rated current.
+
+ Unit: milliampere
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_average
+Description:
+ Average power use
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_average_interval
+Description:
+ Power use averaging interval. A poll
+ notification is sent to this file if the
+ hardware changes the averaging interval.
+
+ Unit: milliseconds
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_average_interval_max
+Description:
+ Maximum power use averaging interval
+
+ Unit: milliseconds
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_average_interval_min
+Description:
+ Minimum power use averaging interval
+
+ Unit: milliseconds
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_average_highest
+Description:
+ Historical average maximum power use
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_average_lowest
+Description:
+ Historical average minimum power use
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_average_max
+Description:
+ A poll notification is sent to
+ `powerY_average` when power use
+ rises above this value.
+
+ Unit: microWatt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_average_min
+Description:
+ A poll notification is sent to
+ `powerY_average` when power use
+ sinks below this value.
+
+ Unit: microWatt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_input
+Description:
+ Instantaneous power use
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_input_highest
+Description:
+ Historical maximum power use
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_input_lowest
+Description:
+ Historical minimum power use
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_reset_history
+Description:
+ Reset input_highest, input_lowest,
+ average_highest and average_lowest.
+
+ WO
+
+What: /sys/class/hwmon/hwmonX/powerY_accuracy
+Description:
+ Accuracy of the power meter.
+
+ Unit: Percent
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_cap
+Description:
+ If power use rises above this limit, the
+ system should take action to reduce power use.
+ A poll notification is sent to this file if the
+ cap is changed by the hardware. The `*_cap`
+ files only appear if the cap is known to be
+ enforced by hardware.
+
+ Unit: microWatt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_cap_hyst
+Description:
+ Margin of hysteresis built around capping and
+ notification.
+
+ Unit: microWatt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_cap_max
+Description:
+ Maximum cap that can be set.
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_cap_min
+Description:
+ Minimum cap that can be set.
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_max
+Description:
+ Maximum power.
+
+ Unit: microWatt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_crit
+Description:
+ Critical maximum power.
+
+ If power rises to or above this limit, the
+ system is expected take drastic action to reduce
+ power consumption, such as a system shutdown or
+ a forced powerdown of some devices.
+
+ Unit: microWatt
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_enable
+Description:
+ Enable or disable the sensors.
+
+ When disabled the sensor read will return
+ -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/powerY_rated_min
+Description:
+ Minimum rated power.
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/powerY_rated_max
+Description:
+ Maximum rated power.
+
+ Unit: microWatt
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/energyY_input
+Description:
+ Cumulative energy use
+
+ Unit: microJoule
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/energyY_enable
+Description:
+ Enable or disable the sensors.
+
+ When disabled the sensor read will return
+ -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/humidityY_alarm
+Description:
+ Humidity limit detection
+
+ - 0: OK
+ - 1: Humidity limit has been reached
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_enable
+Description:
+ Enable or disable the sensors
+
+ When disabled the sensor read will return
+ -ENODATA.
+
+ - 1: Enable
+ - 0: Disable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/humidityY_fault
+Description:
+ Reports a humidity sensor failure.
+
+ - 1: Failed
+ - 0: Ok
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_input
+Description:
+ Humidity
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_label
+Description:
+ Suggested humidity channel label.
+
+ Text string
+
+ Should only be created if the driver has hints about what
+ this humidity channel is being used for, and user-space
+ doesn't. In all other cases, the label is provided by
+ user-space.
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_max
+Description:
+ Humidity max value.
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/humidityY_max_alarm
+Description:
+ Maximum humidity detection
+
+ - 0: OK
+ - 1: Maximum humidity detected
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_max_hyst
+Description:
+ Humidity hysteresis value for max limit.
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ Must be reported as an absolute humidity, NOT a delta
+ from the max value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/humidityY_min
+Description:
+ Humidity min value.
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/humidityY_min_alarm
+Description:
+ Minimum humidity detection
+
+ - 0: OK
+ - 1: Minimum humidity detected
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_min_hyst
+Description:
+ Humidity hysteresis value for min limit.
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ Must be reported as an absolute humidity, NOT a delta
+ from the min value.
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/humidityY_rated_min
+Description:
+ Minimum rated humidity.
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ RO
+
+What: /sys/class/hwmon/hwmonX/humidityY_rated_max
+Description:
+ Maximum rated humidity.
+
+ Unit: milli-percent (per cent mille, pcm)
+
+ RO
+
+
+What: /sys/class/hwmon/hwmonX/intrusionY_alarm
+Description:
+ Chassis intrusion detection
+
+ - 0: OK
+ - 1: intrusion detected
+
+ RW
+
+ Contrary to regular alarm flags which clear themselves
+ automatically when read, this one sticks until cleared by
+ the user. This is done by writing 0 to the file. Writing
+ other values is unsupported.
+
+What: /sys/class/hwmon/hwmonX/intrusionY_beep
+Description:
+ Chassis intrusion beep
+
+ - 0: disable
+ - 1: enable
+
+ RW
+
+What: /sys/class/hwmon/hwmonX/device/pec
+Description:
+ PEC support on I2C devices
+
+ - 0, off, n: disable
+ - 1, on, y: enable
+
+ RW
diff --git a/Documentation/ABI/testing/sysfs-class-intel_pmt b/Documentation/ABI/testing/sysfs-class-intel_pmt
new file mode 100644
index 000000000000..ed4c886a21b1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-intel_pmt
@@ -0,0 +1,119 @@
+What: /sys/class/intel_pmt/
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ The intel_pmt/ class directory contains information for
+ devices that expose hardware telemetry using Intel Platform
+ Monitoring Technology (PMT)
+
+What: /sys/class/intel_pmt/telem<x>
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ The telem<x> directory contains files describing an instance of
+ a PMT telemetry device that exposes hardware telemetry. Each
+ telem<x> directory has an associated telem file. This file
+ may be opened and mapped or read to access the telemetry space
+ of the device. The register layout of the telemetry space is
+ determined from an XML file that matches the PCI device id and
+ GUID for the device.
+
+What: /sys/class/intel_pmt/telem<x>/telem
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ (RO) The telemetry data for this telemetry device. This file
+ may be mapped or read to obtain the data.
+
+What: /sys/class/intel_pmt/telem<x>/guid
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ (RO) The GUID for this telemetry device. The GUID identifies
+ the version of the XML file for the parent device that is to
+ be used to get the register layout.
+
+What: /sys/class/intel_pmt/telem<x>/size
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ (RO) The size of telemetry region in bytes that corresponds to
+ the mapping size for the telem file.
+
+What: /sys/class/intel_pmt/telem<x>/offset
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ (RO) The offset of telemetry region in bytes that corresponds to
+ the mapping for the telem file.
+
+What: /sys/class/intel_pmt/crashlog<x>
+Date: October 2020
+KernelVersion: 5.10
+Contact: Alexander Duyck <alexander.h.duyck@linux.intel.com>
+Description:
+ The crashlog<x> directory contains files for configuring an
+ instance of a PMT crashlog device that can perform crash data
+ recording. Each crashlog<x> device has an associated crashlog
+ file. This file can be opened and mapped or read to access the
+ resulting crashlog buffer. The register layout for the buffer
+ can be determined from an XML file of specified GUID for the
+ parent device.
+
+What: /sys/class/intel_pmt/crashlog<x>/crashlog
+Date: October 2020
+KernelVersion: 5.10
+Contact: David Box <david.e.box@linux.intel.com>
+Description:
+ (RO) The crashlog buffer for this crashlog device. This file
+ may be mapped or read to obtain the data.
+
+What: /sys/class/intel_pmt/crashlog<x>/guid
+Date: October 2020
+KernelVersion: 5.10
+Contact: Alexander Duyck <alexander.h.duyck@linux.intel.com>
+Description:
+ (RO) The GUID for this crashlog device. The GUID identifies the
+ version of the XML file for the parent device that should be
+ used to determine the register layout.
+
+What: /sys/class/intel_pmt/crashlog<x>/size
+Date: October 2020
+KernelVersion: 5.10
+Contact: Alexander Duyck <alexander.h.duyck@linux.intel.com>
+Description:
+ (RO) The length of the result buffer in bytes that corresponds
+ to the size for the crashlog buffer.
+
+What: /sys/class/intel_pmt/crashlog<x>/offset
+Date: October 2020
+KernelVersion: 5.10
+Contact: Alexander Duyck <alexander.h.duyck@linux.intel.com>
+Description:
+ (RO) The offset of the buffer in bytes that corresponds
+ to the mapping for the crashlog device.
+
+What: /sys/class/intel_pmt/crashlog<x>/enable
+Date: October 2020
+KernelVersion: 5.10
+Contact: Alexander Duyck <alexander.h.duyck@linux.intel.com>
+Description:
+ (RW) Boolean value controlling if the crashlog functionality
+ is enabled for the crashlog device.
+
+What: /sys/class/intel_pmt/crashlog<x>/trigger
+Date: October 2020
+KernelVersion: 5.10
+Contact: Alexander Duyck <alexander.h.duyck@linux.intel.com>
+Description:
+ (RW) Boolean value controlling the triggering of the crashlog
+ device node. When read it provides data on if the crashlog has
+ been triggered. When written to it can be used to either clear
+ the current trigger by writing false, or to trigger a new
+ event if the trigger is not currently set.
diff --git a/Documentation/ABI/testing/sysfs-class-intel_pmt-features b/Documentation/ABI/testing/sysfs-class-intel_pmt-features
new file mode 100644
index 000000000000..cddb30e5bdf6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-intel_pmt-features
@@ -0,0 +1,134 @@
+What: /sys/class/intel_pmt/features-<PCI BDF>/
+Date: 2025-04-24
+KernelVersion: 6.16
+Contact: david.e.box@linux.intel.com
+Description:
+ The `features-<PCI BDF>/` directory represents the "features"
+ capability exposed by Intel PMT (Platform Monitoring Technology)
+ for the given PCI device.
+
+ Each directory corresponds to a PMT feature and contains
+ attributes describing the available telemetry, monitoring, or
+ control functionalities.
+
+Directory Structure:
+
+ /sys/class/intel_pmt/features-<PCI BDF>/
+ ├── accelerator_telemetry/ # Per-accelerator telemetry data
+ ├── crash_log/ # Contains system crash telemetry logs
+ ├── per_core_environment_telemetry/ # Environmental telemetry per core
+ ├── per_core_performance_telemetry/ # Performance telemetry per core
+ ├── per_rmid_energy_telemetry/ # Energy telemetry for RMIDs
+ ├── per_rmid_perf_telemetry/ # Performance telemetry for RMIDs
+ ├── tpmi_control/ # TPMI-related controls and telemetry
+ ├── tracing/ # PMT tracing features
+ └── uncore_telemetry/ # Uncore telemetry data
+
+Common Files (Present in all feature directories):
+
+ caps
+ - Read-only
+ - Lists available capabilities for this feature.
+
+ guids
+ - Read-only
+ - Lists GUIDs associated with this feature.
+
+Additional Attributes (Conditional Presence):
+
+ max_command_size
+ - Read-only
+ - Present if the feature supports out-of-band MCTP access.
+ - Maximum supported MCTP command size for out-of-band PMT access (bytes).
+
+ max_stream_size
+ - Read-only
+ - Present if the feature supports out-of-band MCTP access.
+ - Maximum supported MCTP stream size (bytes).
+
+ min_watcher_period_ms
+ - Read-only
+ - Present if the feature supports the watcher API.
+ The watcher API provides a writable control interface that allows user
+ configuration of monitoring behavior, such as setting the sampling or
+ reporting interval.
+ - Minimum supported time period for the watcher interface (milliseconds).
+
+ num_rmids
+ - Read-only
+ - Present if the feature supports RMID (Resource Monitoring ID) telemetry.
+ RMIDs are identifiers used by hardware to track and report resource usage,
+ such as memory bandwidth or energy consumption, on a per-logical-entity
+ basis (e.g., per core, thread, or process group).
+ - Maximum number of RMIDs tracked simultaneously.
+
+Example:
+For a device with PCI BDF `0000:00:03.1`, the directory tree could look like:
+
+ /sys/class/intel_pmt/features-0000:00:03.1/
+ ├── accelerator_telemetry/
+ │ ├── caps
+ │ ├── guids
+ │ ├── max_command_size
+ │ ├── max_stream_size
+ │ ├── min_watcher_period_ms
+ ├── crash_log/
+ │ ├── caps
+ │ ├── guids
+ │ ├── max_command_size
+ │ ├── max_stream_size
+ ├── per_core_environment_telemetry/
+ │ ├── caps
+ │ ├── guids
+ │ ├── max_command_size
+ │ ├── max_stream_size
+ │ ├── min_watcher_period_ms
+ ├── per_rmid_energy_telemetry/
+ │ ├── caps
+ │ ├── guids
+ │ ├── max_command_size
+ │ ├── max_stream_size
+ │ ├── min_watcher_period_ms
+ │ ├── num_rmids
+ ├── tpmi_control/
+ │ ├── caps
+ │ ├── guids
+ ├── tracing/
+ │ ├── caps
+ │ ├── guids
+ ├── uncore_telemetry/
+ │ ├── caps
+ │ ├── guids
+ │ ├── max_command_size
+ │ ├── max_stream_size
+ │ ├── min_watcher_period_ms
+
+Notes:
+ - Some attributes are only present if the corresponding feature supports
+ the capability (e.g., `max_command_size` for MCTP-capable features).
+ - Features supporting RMIDs include `num_rmids`.
+ - Features supporting the watcher API include `min_watcher_period_ms`.
+ - The `caps` file provides additional information about the functionality
+ of the feature.
+
+Example 'caps' content for the 'tracing' feature:
+
+ /sys/class/intel_pmt/features-0000:00:03.1/
+ ├── tracing/
+ │ ├── caps
+
+ telemetry Available: No
+ watcher Available: Yes
+ crashlog Available: No
+ streaming Available: No
+ threashold Available: No
+ window Available: No
+ config Available: Yes
+ tracing Available: No
+ inband Available: Yes
+ oob Available: Yes
+ secure_chan Available: No
+ pmt_sp Available: Yes
+ pmt_sp_policy Available: Yes
+ mailbox Available: Yes
+ bios_lock Available: Yes
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 3646ec85d513..0313b82644f2 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -3,17 +3,61 @@ Date: March 2006
KernelVersion: 2.6.17
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
- Set the brightness of the LED. Most LEDs don't
- have hardware brightness support so will just be turned on for
- non-zero brightness settings. The value is between 0 and
+ Set the brightness of the LED.
+
+ Most LEDs don't have hardware brightness support, so will
+ just be turned on for non-zero brightness settings.
+
+ .. Note::
+
+ For multicolor LEDs, writing to this file will update all
+ LEDs within the group to a calculated percentage of what
+ each color LED intensity is set to.
+
+ The percentage is calculated for each grouped LED via
+ the equation below::
+
+ led_brightness = brightness * multi_intensity/max_brightness
+
+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
+
+ The value is between 0 and
/sys/class/leds/<led>/max_brightness.
+ Writing 0 to this file clears active trigger.
+
+ Writing non-zero to this file while trigger is active changes the
+ top brightness trigger is going to use.
+
+
+
What: /sys/class/leds/<led>/max_brightness
Date: March 2006
KernelVersion: 2.6.17
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
- Maximum brightness level for this led, default is 255 (LED_FULL).
+ Maximum brightness level for this LED, default is 255 (LED_FULL).
+
+ If the LED does not support different brightness levels, this
+ should be 1.
+
+What: /sys/class/leds/<led>/brightness_hw_changed
+Date: January 2017
+KernelVersion: 4.11
+Description:
+ Last hardware set brightness level for this LED. Some LEDs
+ may be changed autonomously by hardware/firmware. Only LEDs
+ where this happens and the driver can detect this, will have
+ this file.
+
+ This file supports poll() to detect when the hardware changes
+ the brightness.
+
+ Reading this file will return the last brightness level set
+ by the hardware, this may be different from the current
+ brightness. Reading this file when no hw brightness change
+ event has happened will return an ENODATA error.
What: /sys/class/leds/<led>/trigger
Date: March 2006
@@ -21,10 +65,18 @@ KernelVersion: 2.6.17
Contact: Richard Purdie <rpurdie@rpsys.net>
Description:
Set the trigger for this LED. A trigger is a kernel based source
- of led events.
+ of LED events.
+
You can change triggers in a similar manner to the way an IO
scheduler is chosen. Trigger specific parameters can appear in
- /sys/class/leds/<led> once a given trigger is selected.
+ /sys/class/leds/<led> once a given trigger is selected. For
+ their documentation see `sysfs-class-led-trigger-*`.
+
+ Writing "none" removes the trigger for this LED.
+
+ Writing "default" sets the trigger to the LED's default trigger
+ (which would often be configured in the device tree for the
+ hardware).
What: /sys/class/leds/<led>/inverted
Date: January 2011
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-aw200xx b/Documentation/ABI/testing/sysfs-class-led-driver-aw200xx
new file mode 100644
index 000000000000..6d4449cf9d71
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-aw200xx
@@ -0,0 +1,5 @@
+What: /sys/class/leds/<led>/dim
+Date: May 2023
+Description: 64-level DIM current. If you write a negative value or
+ "auto", the dim will be calculated according to the
+ brightness.
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
index 620ebb3b9baa..e38a835d0a85 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
@@ -4,10 +4,12 @@ KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
Set the ALS output channel to use as input in
- ALS-current-control mode (1, 2), where
+ ALS-current-control mode (1, 2), where:
- 1 - out_current1
- 2 - out_current2
+ == ============
+ 1 out_current1
+ 2 out_current2
+ == ============
What: /sys/class/leds/<led>/als_en
Date: May 2012
@@ -22,16 +24,18 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the pattern generator fall and rise times (0..7), where
+ Set the pattern generator fall and rise times (0..7), where:
- 0 - 2048 us
- 1 - 262 ms
- 2 - 524 ms
- 3 - 1.049 s
- 4 - 2.097 s
- 5 - 4.194 s
- 6 - 8.389 s
- 7 - 16.78 s
+ == =======
+ 0 2048 us
+ 1 262 ms
+ 2 524 ms
+ 3 1.049 s
+ 4 2.097 s
+ 5 4.194 s
+ 6 8.389 s
+ 7 16.78 s
+ == =======
What: /sys/class/leds/<led>/id
Date: April 2012
@@ -45,21 +49,25 @@ Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the brightness-mapping mode (0, 1), where
+ Set the brightness-mapping mode (0, 1), where:
- 0 - exponential mode
- 1 - linear mode
+ == ================
+ 0 exponential mode
+ 1 linear mode
+ == ================
What: /sys/class/leds/<led>/pwm
Date: April 2012
KernelVersion: 3.5
Contact: Johan Hovold <jhovold@gmail.com>
Description:
- Set the PWM-input control mask (5 bits), where
+ Set the PWM-input control mask (5 bits), where:
- bit 5 - PWM-input enabled in Zone 4
- bit 4 - PWM-input enabled in Zone 3
- bit 3 - PWM-input enabled in Zone 2
- bit 2 - PWM-input enabled in Zone 1
- bit 1 - PWM-input enabled in Zone 0
- bit 0 - PWM-input enabled
+ ===== ===========================
+ bit 5 PWM-input enabled in Zone 4
+ bit 4 PWM-input enabled in Zone 3
+ bit 3 PWM-input enabled in Zone 2
+ bit 2 PWM-input enabled in Zone 1
+ bit 1 PWM-input enabled in Zone 0
+ bit 0 PWM-input enabled
+ ===== ===========================
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia
new file mode 100644
index 000000000000..369b4ae8be5f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia
@@ -0,0 +1,28 @@
+What: /sys/class/leds/<led>/device/brightness
+Date: July 2020
+KernelVersion: 5.9
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RW) On the front panel of the Turris Omnia router there is also
+ a button which can be used to control the intensity of all the
+ LEDs at once, so that if they are too bright, user can dim them.
+
+ The microcontroller cycles between 8 levels of this global
+ brightness (from 100% to 0%), but this setting can have any
+ integer value between 0 and 100. It is therefore convenient to be
+ able to change this setting from software.
+
+ Format: %i
+
+What: /sys/class/leds/<led>/device/gamma_correction
+Date: August 2023
+KernelVersion: 6.6
+Contact: Marek Behún <kabel@kernel.org>
+Description: (RW) Newer versions of the microcontroller firmware of the
+ Turris Omnia router support gamma correction for the RGB LEDs.
+ This feature can be enabled/disabled by writing to this file.
+
+ If the feature is not supported because the MCU firmware is too
+ old, the file always reads as 0, and writing to the file results
+ in the EOPNOTSUPP error.
+
+ Format: %i
diff --git a/Documentation/ABI/testing/sysfs-class-led-flash b/Documentation/ABI/testing/sysfs-class-led-flash
index 220a0270b47b..11e5677c3672 100644
--- a/Documentation/ABI/testing/sysfs-class-led-flash
+++ b/Documentation/ABI/testing/sysfs-class-led-flash
@@ -55,26 +55,35 @@ Description: read only
Flash faults are re-read after strobing the flash. Possible
flash faults:
- * led-over-voltage - flash controller voltage to the flash LED
+ * led-over-voltage
+ flash controller voltage to the flash LED
has exceeded the limit specific to the flash controller
- * flash-timeout-exceeded - the flash strobe was still on when
+ * flash-timeout-exceeded
+ the flash strobe was still on when
the timeout set by the user has expired; not all flash
controllers may set this in all such conditions
- * controller-over-temperature - the flash controller has
+ * controller-over-temperature
+ the flash controller has
overheated
- * controller-short-circuit - the short circuit protection
+ * controller-short-circuit
+ the short circuit protection
of the flash controller has been triggered
- * led-power-supply-over-current - current in the LED power
+ * led-power-supply-over-current
+ current in the LED power
supply has exceeded the limit specific to the flash
controller
- * indicator-led-fault - the flash controller has detected
+ * indicator-led-fault
+ the flash controller has detected
a short or open circuit condition on the indicator LED
- * led-under-voltage - flash controller voltage to the flash
+ * led-under-voltage
+ flash controller voltage to the flash
LED has been below the minimum limit specific to
the flash
- * controller-under-voltage - the input voltage of the flash
+ * controller-under-voltage
+ the input voltage of the flash
controller is below the limit under which strobing the
flash at full current will not be possible;
the condition persists until this flag is no longer set
- * led-over-temperature - the temperature of the LED has exceeded
+ * led-over-temperature
+ the temperature of the LED has exceeded
its allowed upper limit
diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor
new file mode 100644
index 000000000000..16fc827b10cb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-multicolor
@@ -0,0 +1,24 @@
+
+What: /sys/class/leds/<led>/multi_index
+Date: March 2020
+KernelVersion: 5.9
+Contact: Dan Murphy <dmurphy@ti.com>
+Description: read
+ The multi_index array, when read, will output the LED colors
+ as an array of strings as they are indexed in the
+ multi_intensity file.
+
+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
+
+What: /sys/class/leds/<led>/multi_intensity
+Date: March 2020
+KernelVersion: 5.9
+Contact: Dan Murphy <dmurphy@ti.com>
+Description: read/write
+ This file contains array of integers. Order of components is
+ described by the multi_index array. The maximum intensity should
+ not exceed /sys/class/leds/<led>/max_brightness.
+
+ For additional details please refer to
+ Documentation/leds/leds-class-multicolor.rst.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev
new file mode 100644
index 000000000000..ed46b37ab8a2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev
@@ -0,0 +1,192 @@
+What: /sys/class/leds/<led>/device_name
+Date: Dec 2017
+KernelVersion: 4.16
+Contact: linux-leds@vger.kernel.org
+Description:
+ Specifies the network device name to monitor.
+
+What: /sys/class/leds/<led>/interval
+Date: Dec 2017
+KernelVersion: 4.16
+Contact: linux-leds@vger.kernel.org
+Description:
+ Specifies the duration of the LED blink in milliseconds.
+ Defaults to 50 ms.
+
+ When offloaded is true, the interval value MUST be set to the
+ default value and cannot be changed.
+ Trying to set any value in this specific mode will return
+ an EINVAL error.
+
+What: /sys/class/leds/<led>/link
+Date: Dec 2017
+KernelVersion: 4.16
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link state of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ of the named network device.
+ Setting this value also immediately changes the LED state.
+
+
+What: /sys/class/leds/<led>/tx
+Date: Dec 2017
+KernelVersion: 4.16
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal transmission of data on the named network device.
+
+ If set to 0 (default), the LED will not blink on transmission.
+
+ If set to 1, the LED will blink for the milliseconds specified
+ in interval to signal transmission.
+
+ When offloaded is true, the blink interval is controlled by
+ hardware and won't reflect the value set in interval.
+
+What: /sys/class/leds/<led>/rx
+Date: Dec 2017
+KernelVersion: 4.16
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal reception of data on the named network device.
+
+ If set to 0 (default), the LED will not blink on reception.
+
+ If set to 1, the LED will blink for the milliseconds specified
+ in interval to signal reception.
+
+ When offloaded is true, the blink interval is controlled by
+ hardware and won't reflect the value set in interval.
+
+What: /sys/class/leds/<led>/offloaded
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: linux-leds@vger.kernel.org
+Description:
+ Communicate whether the LED trigger modes are offloaded to
+ hardware or whether software fallback is used.
+
+ If 0, the LED is using software fallback to blink.
+
+ If 1, the LED blinking in requested mode is offloaded to
+ hardware.
+
+What: /sys/class/leds/<led>/link_10
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link speed state of 10Mbps of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ speed of 10MBps of the named network device.
+ Setting this value also immediately changes the LED state.
+
+ Present only if the named network device supports 10Mbps link speed.
+
+What: /sys/class/leds/<led>/link_100
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link speed state of 100Mbps of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ speed of 100Mbps of the named network device.
+ Setting this value also immediately changes the LED state.
+
+ Present only if the named network device supports 100Mbps link speed.
+
+What: /sys/class/leds/<led>/link_1000
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link speed state of 1000Mbps of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ speed of 1000Mbps of the named network device.
+ Setting this value also immediately changes the LED state.
+
+ Present only if the named network device supports 1000Mbps link speed.
+
+What: /sys/class/leds/<led>/link_2500
+Date: Nov 2023
+KernelVersion: 6.8
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link speed state of 2500Mbps of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ speed of 2500Mbps of the named network device.
+ Setting this value also immediately changes the LED state.
+
+ Present only if the named network device supports 2500Mbps link speed.
+
+What: /sys/class/leds/<led>/link_5000
+Date: Nov 2023
+KernelVersion: 6.8
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link speed state of 5000Mbps of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ speed of 5000Mbps of the named network device.
+ Setting this value also immediately changes the LED state.
+
+ Present only if the named network device supports 5000Mbps link speed.
+
+What: /sys/class/leds/<led>/link_10000
+Date: Nov 2023
+KernelVersion: 6.8
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link speed state of 10000Mbps of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link state
+ speed of 10000Mbps of the named network device.
+ Setting this value also immediately changes the LED state.
+
+ Present only if the named network device supports 10000Mbps link speed.
+
+What: /sys/class/leds/<led>/half_duplex
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link half duplex state of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link half
+ duplex state of the named network device.
+ Setting this value also immediately changes the LED state.
+
+What: /sys/class/leds/<led>/full_duplex
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: linux-leds@vger.kernel.org
+Description:
+ Signal the link full duplex state of the named network device.
+
+ If set to 0 (default), the LED's normal state is off.
+
+ If set to 1, the LED's normal state reflects the link full
+ duplex state of the named network device.
+ Setting this value also immediately changes the LED state.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
new file mode 100644
index 000000000000..378a3a4df3c8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
@@ -0,0 +1,36 @@
+What: /sys/class/leds/<led>/delay_on
+Date: Jun 2012
+KernelVersion: 3.6
+Contact: linux-leds@vger.kernel.org
+Description:
+ Specifies for how many milliseconds the LED has to stay at
+ LED_FULL brightness after it has been armed.
+ Defaults to 100 ms.
+
+What: /sys/class/leds/<led>/delay_off
+Date: Jun 2012
+KernelVersion: 3.6
+Contact: linux-leds@vger.kernel.org
+Description:
+ Specifies for how many milliseconds the LED has to stay at
+ LED_OFF brightness after it has been armed.
+ Defaults to 100 ms.
+
+What: /sys/class/leds/<led>/invert
+Date: Jun 2012
+KernelVersion: 3.6
+Contact: linux-leds@vger.kernel.org
+Description:
+ Reverse the blink logic. If set to 0 (default) blink on for
+ delay_on ms, then blink off for delay_off ms, leaving the LED
+ normally off. If set to 1, blink off for delay_off ms, then
+ blink on for delay_on ms, leaving the LED normally on.
+ Setting this value also immediately changes the LED state.
+
+What: /sys/class/leds/<led>/shot
+Date: Jun 2012
+KernelVersion: 3.6
+Contact: linux-leds@vger.kernel.org
+Description:
+ Write any non-empty string to signal an events, this starts a
+ blink sequence if not already running.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern
new file mode 100644
index 000000000000..22f28f2e9ac4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern
@@ -0,0 +1,50 @@
+What: /sys/class/leds/<led>/pattern
+Date: September 2018
+KernelVersion: 4.20
+Description:
+ Specify a software pattern for the LED, that supports altering
+ the brightness for the specified duration with one software
+ timer. It can do gradual dimming and step change of brightness.
+
+ The pattern is given by a series of tuples, of brightness and
+ duration (ms).
+
+ The exact format is described in:
+ Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt
+
+What: /sys/class/leds/<led>/hr_pattern
+Date: April 2024
+Description:
+ Specify a software pattern for the LED, that supports altering
+ the brightness for the specified duration with one software
+ timer. It can do gradual dimming and step change of brightness.
+
+ Unlike the /sys/class/leds/<led>/pattern, this attribute runs
+ a pattern on high-resolution timer (hrtimer).
+
+What: /sys/class/leds/<led>/hw_pattern
+Date: September 2018
+KernelVersion: 4.20
+Description:
+ Specify a hardware pattern for the LED, for LED hardware that
+ supports autonomously controlling brightness over time, according
+ to some preprogrammed hardware patterns. It deactivates any active
+ software pattern.
+
+ Since different LED hardware can have different semantics of
+ hardware patterns, each driver is expected to provide its own
+ description for the hardware patterns in their documentation
+ file at Documentation/leds/.
+
+What: /sys/class/leds/<led>/repeat
+Date: September 2018
+KernelVersion: 4.20
+Description:
+ Specify a pattern repeat number. -1 means repeat indefinitely,
+ other negative numbers and number 0 are invalid.
+
+ This file will always return the originally written repeat
+ number.
+
+ It should be noticed that some leds, like EL15203000 may
+ only support indefinitely patterns, so they always store -1.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-tty b/Documentation/ABI/testing/sysfs-class-led-trigger-tty
new file mode 100644
index 000000000000..308fbc3627cd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-tty
@@ -0,0 +1,62 @@
+What: /sys/class/leds/<tty_led>/ttyname
+Date: Dec 2020
+KernelVersion: 5.10
+Contact: linux-leds@vger.kernel.org
+Description:
+ Specifies the tty device name of the triggering tty
+
+What: /sys/class/leds/<tty_led>/rx
+Date: February 2024
+KernelVersion: 6.8
+Description:
+ Signal reception (rx) of data on the named tty device.
+ If set to 0, the LED will not blink on reception.
+ If set to 1 (default), the LED will blink on reception.
+
+What: /sys/class/leds/<tty_led>/tx
+Date: February 2024
+KernelVersion: 6.8
+Description:
+ Signal transmission (tx) of data on the named tty device.
+ If set to 0, the LED will not blink on transmission.
+ If set to 1 (default), the LED will blink on transmission.
+
+What: /sys/class/leds/<tty_led>/cts
+Date: February 2024
+KernelVersion: 6.8
+Description:
+ CTS = Clear To Send
+ DCE is ready to accept data from the DTE.
+ If the line state is detected, the LED is switched on.
+ If set to 0 (default), the LED will not evaluate CTS.
+ If set to 1, the LED will evaluate CTS.
+
+What: /sys/class/leds/<tty_led>/dsr
+Date: February 2024
+KernelVersion: 6.8
+Description:
+ DSR = Data Set Ready
+ DCE is ready to receive and send data.
+ If the line state is detected, the LED is switched on.
+ If set to 0 (default), the LED will not evaluate DSR.
+ If set to 1, the LED will evaluate DSR.
+
+What: /sys/class/leds/<tty_led>/dcd
+Date: February 2024
+KernelVersion: 6.8
+Description:
+ DCD = Data Carrier Detect
+ DTE is receiving a carrier from the DCE.
+ If the line state is detected, the LED is switched on.
+ If set to 0 (default), the LED will not evaluate CAR (DCD).
+ If set to 1, the LED will evaluate CAR (DCD).
+
+What: /sys/class/leds/<tty_led>/rng
+Date: February 2024
+KernelVersion: 6.8
+Description:
+ RNG = Ring Indicator
+ DCE has detected an incoming ring signal on the telephone
+ line. If the line state is detected, the LED is switched on.
+ If set to 0 (default), the LED will not evaluate RNG.
+ If set to 1, the LED will evaluate RNG.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
new file mode 100644
index 000000000000..eb81152b8348
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
@@ -0,0 +1,13 @@
+What: /sys/class/leds/<led>/ports/<port>
+Date: September 2016
+KernelVersion: 4.9
+Contact: linux-leds@vger.kernel.org
+ linux-usb@vger.kernel.org
+Description:
+ Every dir entry represents a single USB port that can be
+ selected for the USB port trigger. Selecting ports makes trigger
+ observing them for any connected devices and lighting on LED if
+ there are any.
+
+ Echoing "1" value selects USB port. Echoing "0" unselects it.
+ Current state can be also read.
diff --git a/Documentation/ABI/testing/sysfs-class-leds-gt683r b/Documentation/ABI/testing/sysfs-class-leds-gt683r
index e4fae6026e79..b57ffb26e722 100644
--- a/Documentation/ABI/testing/sysfs-class-leds-gt683r
+++ b/Documentation/ABI/testing/sysfs-class-leds-gt683r
@@ -5,12 +5,14 @@ Contact: Janne Kanniainen <janne.kanniainen@gmail.com>
Description:
Set the mode of LEDs. You should notice that changing the mode
of one LED will update the mode of its two sibling devices as
- well.
+ well. Possible values are:
- 0 - normal
- 1 - audio
- 2 - breathing
+ == =========
+ 0 normal
+ 1 audio
+ 2 breathing
+ == =========
Normal: LEDs are fully on when enabled
Audio: LEDs brightness depends on sound level
- Breathing: LEDs brightness varies at human breathing rate \ No newline at end of file
+ Breathing: LEDs brightness varies at human breathing rate
diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei
index 80d9888a8ece..1db36ddf8e58 100644
--- a/Documentation/ABI/testing/sysfs-class-mei
+++ b/Documentation/ABI/testing/sysfs-class-mei
@@ -6,7 +6,7 @@ Description:
The mei/ class sub-directory belongs to mei device class
-What: /sys/class/mei/meiN/
+What: /sys/class/mei/mei<N>/
Date: May 2014
KernelVersion: 3.17
Contact: Tomas Winkler <tomas.winkler@intel.com>
@@ -14,7 +14,7 @@ Description:
The /sys/class/mei/meiN directory is created for
each probed mei device
-What: /sys/class/mei/meiN/fw_status
+What: /sys/class/mei/mei<N>/fw_status
Date: Nov 2014
KernelVersion: 3.19
Contact: Tomas Winkler <tomas.winkler@intel.com>
@@ -29,3 +29,77 @@ Description: Display fw status registers content
Also number of registers varies between 1 and 6
depending on generation.
+What: /sys/class/mei/mei<N>/hbm_ver
+Date: Aug 2016
+KernelVersion: 4.9
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display the negotiated HBM protocol version.
+
+ The HBM protocol version negotiated
+ between the driver and the device.
+
+What: /sys/class/mei/mei<N>/hbm_ver_drv
+Date: Aug 2016
+KernelVersion: 4.9
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display the driver HBM protocol version.
+
+ The HBM protocol version supported by the driver.
+
+What: /sys/class/mei/mei<N>/tx_queue_limit
+Date: Jan 2018
+KernelVersion: 4.16
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Configure tx queue limit
+
+ Set maximal number of pending writes
+ per opened session.
+
+What: /sys/class/mei/mei<N>/fw_ver
+Date: May 2018
+KernelVersion: 4.18
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display the ME firmware version.
+
+ The version of the platform ME firmware is in format:
+ <platform>:<major>.<minor>.<milestone>.<build_no>.
+ There can be up to three such blocks for different
+ FW components.
+
+What: /sys/class/mei/mei<N>/dev_state
+Date: Mar 2019
+KernelVersion: 5.1
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display the ME device state.
+
+ The device state can have following values:
+ INITIALIZING
+ INIT_CLIENTS
+ ENABLED
+ RESETTING
+ DISABLED
+ POWER_DOWN
+ POWER_UP
+
+What: /sys/class/mei/mei<N>/trc
+Date: Nov 2019
+KernelVersion: 5.5
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display trc status register content
+
+ The ME FW writes Glitch Detection HW (TRC)
+ status information into trc status register
+ for BIOS and OS to monitor fw health.
+
+What: /sys/class/mei/mei<N>/kind
+Date: Jul 2020
+KernelVersion: 5.8
+Contact: Tomas Winkler <tomas.winkler@intel.com>
+Description: Display kind of the device
+
+ Generic devices are marked as "mei"
+ while special purpose have their own
+ names.
+ Available options:
+ - mei: generic mei device.
+ - itouch: itouch (ipts) mei device.
diff --git a/Documentation/ABI/testing/sysfs-class-mic b/Documentation/ABI/testing/sysfs-class-mic
new file mode 100644
index 000000000000..5e5f36d10055
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-mic
@@ -0,0 +1,178 @@
+What: /sys/class/mic/
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ The mic class directory belongs to Intel MIC devices and
+ provides information per MIC device. An Intel MIC device is a
+ PCIe form factor add-in Coprocessor card based on the Intel Many
+ Integrated Core (MIC) architecture that runs a Linux OS.
+
+What: /sys/class/mic/mic<X>
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ The directories /sys/class/mic/mic0, /sys/class/mic/mic1 etc.,
+ represent MIC devices (0,1,..etc). Each directory has
+ information specific to that MIC device.
+
+What: /sys/class/mic/mic<X>/family
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ Provides information about the Coprocessor family for an Intel
+ MIC device. For example - "x100"
+
+What: /sys/class/mic/mic<X>/stepping
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ Provides information about the silicon stepping for an Intel
+ MIC device. For example - "A0" or "B0"
+
+What: /sys/class/mic/mic<X>/state
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ When read, this entry provides the current state of an Intel
+ MIC device in the context of the card OS. Possible values that
+ will be read are:
+
+
+ =============== ===============================================
+ "ready" The MIC device is ready to boot the card OS.
+ On reading this entry after an OSPM resume,
+ a "boot" has to be written to this entry if
+ the card was previously shutdown during OSPM
+ suspend.
+ "booting" The MIC device has initiated booting a card OS.
+ "online" The MIC device has completed boot and is online
+ "shutting_down" The card OS is shutting down.
+ "resetting" A reset has been initiated for the MIC device
+ "reset_failed" The MIC device has failed to reset.
+ =============== ===============================================
+
+ When written, this sysfs entry triggers different state change
+ operations depending upon the current state of the card OS.
+ Acceptable values are:
+
+
+ ========== ===================================================
+ "boot" Boot the card OS image specified by the combination
+ of firmware, ramdisk, cmdline and bootmode
+ sysfs entries.
+ "reset" Initiates device reset.
+ "shutdown" Initiates card OS shutdown.
+ ========== ===================================================
+
+What: /sys/class/mic/mic<X>/shutdown_status
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ An Intel MIC device runs a Linux OS during its operation. This
+ OS can shutdown because of various reasons. When read, this
+ entry provides the status on why the card OS was shutdown.
+ Possible values are:
+
+ ========== ===================================================
+ "nop" shutdown status is not applicable, when the card OS
+ is "online"
+ "crashed" Shutdown because of a HW or SW crash.
+ "halted" Shutdown because of a halt command.
+ "poweroff" Shutdown because of a poweroff command.
+ "restart" Shutdown because of a restart command.
+ ========== ===================================================
+
+What: /sys/class/mic/mic<X>/cmdline
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ An Intel MIC device runs a Linux OS during its operation. Before
+ booting this card OS, it is possible to pass kernel command line
+ options to configure various features in it, similar to
+ self-bootable machines. When read, this entry provides
+ information about the current kernel command line options set to
+ boot the card OS. This entry can be written to change the
+ existing kernel command line options. Typically, the user would
+ want to read the current command line options, append new ones
+ or modify existing ones and then write the whole kernel command
+ line back to this entry.
+
+What: /sys/class/mic/mic<X>/firmware
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ When read, this sysfs entry provides the path name under
+ /lib/firmware/ where the firmware image to be booted on the
+ card can be found. The entry can be written to change the
+ firmware image location under /lib/firmware/.
+
+What: /sys/class/mic/mic<X>/ramdisk
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ When read, this sysfs entry provides the path name under
+ /lib/firmware/ where the ramdisk image to be used during card
+ OS boot can be found. The entry can be written to change
+ the ramdisk image location under /lib/firmware/.
+
+What: /sys/class/mic/mic<X>/bootmode
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ When read, this sysfs entry provides the current bootmode for
+ the card. This sysfs entry can be written with the following
+ valid strings:
+ a) linux - Boot a Linux image.
+ b) flash - Boot an image for flash updates.
+
+What: /sys/class/mic/mic<X>/log_buf_addr
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ An Intel MIC device runs a Linux OS during its operation. For
+ debugging purpose and early kernel boot messages, the user can
+ access the card OS log buffer via debugfs. When read, this entry
+ provides the kernel virtual address of the buffer where the card
+ OS log buffer can be read. This entry is written by the host
+ configuration daemon to set the log buffer address. The correct
+ log buffer address to be written can be found in the System.map
+ file of the card OS.
+
+What: /sys/class/mic/mic<X>/log_buf_len
+Date: October 2013
+KernelVersion: 3.13
+Contact: Sudeep Dutt <sudeep.dutt@intel.com>
+Description:
+ An Intel MIC device runs a Linux OS during its operation. For
+ debugging purpose and early kernel boot messages, the user can
+ access the card OS log buffer via debugfs. When read, this entry
+ provides the kernel virtual address where the card OS log buffer
+ length can be read. This entry is written by host configuration
+ daemon to set the log buffer length address. The correct log
+ buffer length address to be written can be found in the
+ System.map file of the card OS.
+
+What: /sys/class/mic/mic<X>/heartbeat_enable
+Date: March 2015
+KernelVersion: 4.4
+Contact: Ashutosh Dixit <ashutosh.dixit@intel.com>
+Description:
+ The MIC drivers detect and inform user space about card crashes
+ via a heartbeat mechanism (see the description of
+ shutdown_status above). User space can turn off this
+ notification by setting heartbeat_enable to 0 and enable it by
+ setting this entry to 1. If this notification is disabled it is
+ the responsibility of user space to detect card crashes via
+ alternative means such as a network ping. This setting is
+ enabled by default.
diff --git a/Documentation/ABI/testing/sysfs-class-mic.txt b/Documentation/ABI/testing/sysfs-class-mic.txt
deleted file mode 100644
index 13f48afc534f..000000000000
--- a/Documentation/ABI/testing/sysfs-class-mic.txt
+++ /dev/null
@@ -1,157 +0,0 @@
-What: /sys/class/mic/
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- The mic class directory belongs to Intel MIC devices and
- provides information per MIC device. An Intel MIC device is a
- PCIe form factor add-in Coprocessor card based on the Intel Many
- Integrated Core (MIC) architecture that runs a Linux OS.
-
-What: /sys/class/mic/mic(x)
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- The directories /sys/class/mic/mic0, /sys/class/mic/mic1 etc.,
- represent MIC devices (0,1,..etc). Each directory has
- information specific to that MIC device.
-
-What: /sys/class/mic/mic(x)/family
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- Provides information about the Coprocessor family for an Intel
- MIC device. For example - "x100"
-
-What: /sys/class/mic/mic(x)/stepping
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- Provides information about the silicon stepping for an Intel
- MIC device. For example - "A0" or "B0"
-
-What: /sys/class/mic/mic(x)/state
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- When read, this entry provides the current state of an Intel
- MIC device in the context of the card OS. Possible values that
- will be read are:
- "offline" - The MIC device is ready to boot the card OS. On
- reading this entry after an OSPM resume, a "boot" has to be
- written to this entry if the card was previously shutdown
- during OSPM suspend.
- "online" - The MIC device has initiated booting a card OS.
- "shutting_down" - The card OS is shutting down.
- "reset_failed" - The MIC device has failed to reset.
- "suspending" - The MIC device is currently being prepared for
- suspend. On reading this entry, a "suspend" has to be written
- to the state sysfs entry to ensure the card is shutdown during
- OSPM suspend.
- "suspended" - The MIC device has been suspended.
-
- When written, this sysfs entry triggers different state change
- operations depending upon the current state of the card OS.
- Acceptable values are:
- "boot" - Boot the card OS image specified by the combination
- of firmware, ramdisk, cmdline and bootmode
- sysfs entries.
- "reset" - Initiates device reset.
- "shutdown" - Initiates card OS shutdown.
- "suspend" - Initiates card OS shutdown and also marks the card
- as suspended.
-
-What: /sys/class/mic/mic(x)/shutdown_status
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- An Intel MIC device runs a Linux OS during its operation. This
- OS can shutdown because of various reasons. When read, this
- entry provides the status on why the card OS was shutdown.
- Possible values are:
- "nop" - shutdown status is not applicable, when the card OS is
- "online"
- "crashed" - Shutdown because of a HW or SW crash.
- "halted" - Shutdown because of a halt command.
- "poweroff" - Shutdown because of a poweroff command.
- "restart" - Shutdown because of a restart command.
-
-What: /sys/class/mic/mic(x)/cmdline
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- An Intel MIC device runs a Linux OS during its operation. Before
- booting this card OS, it is possible to pass kernel command line
- options to configure various features in it, similar to
- self-bootable machines. When read, this entry provides
- information about the current kernel command line options set to
- boot the card OS. This entry can be written to change the
- existing kernel command line options. Typically, the user would
- want to read the current command line options, append new ones
- or modify existing ones and then write the whole kernel command
- line back to this entry.
-
-What: /sys/class/mic/mic(x)/firmware
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- When read, this sysfs entry provides the path name under
- /lib/firmware/ where the firmware image to be booted on the
- card can be found. The entry can be written to change the
- firmware image location under /lib/firmware/.
-
-What: /sys/class/mic/mic(x)/ramdisk
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- When read, this sysfs entry provides the path name under
- /lib/firmware/ where the ramdisk image to be used during card
- OS boot can be found. The entry can be written to change
- the ramdisk image location under /lib/firmware/.
-
-What: /sys/class/mic/mic(x)/bootmode
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- When read, this sysfs entry provides the current bootmode for
- the card. This sysfs entry can be written with the following
- valid strings:
- a) linux - Boot a Linux image.
- b) elf - Boot an elf image for flash updates.
-
-What: /sys/class/mic/mic(x)/log_buf_addr
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- An Intel MIC device runs a Linux OS during its operation. For
- debugging purpose and early kernel boot messages, the user can
- access the card OS log buffer via debugfs. When read, this entry
- provides the kernel virtual address of the buffer where the card
- OS log buffer can be read. This entry is written by the host
- configuration daemon to set the log buffer address. The correct
- log buffer address to be written can be found in the System.map
- file of the card OS.
-
-What: /sys/class/mic/mic(x)/log_buf_len
-Date: October 2013
-KernelVersion: 3.13
-Contact: Sudeep Dutt <sudeep.dutt@intel.com>
-Description:
- An Intel MIC device runs a Linux OS during its operation. For
- debugging purpose and early kernel boot messages, the user can
- access the card OS log buffer via debugfs. When read, this entry
- provides the kernel virtual address where the card OS log buffer
- length can be read. This entry is written by host configuration
- daemon to set the log buffer length address. The correct log
- buffer length address to be written can be found in the
- System.map file of the card OS.
diff --git a/Documentation/ABI/testing/sysfs-class-mtd b/Documentation/ABI/testing/sysfs-class-mtd
index 3b5c3bca9186..f77fa4f6d465 100644
--- a/Documentation/ABI/testing/sysfs-class-mtd
+++ b/Documentation/ABI/testing/sysfs-class-mtd
@@ -39,7 +39,7 @@ KernelVersion: 2.6.29
Contact: linux-mtd@lists.infradead.org
Description:
Major and minor numbers of the character device corresponding
- to the read-only variant of thie MTD device (in
+ to the read-only variant of the MTD device (in
<major>:<minor> format). In this case <minor> will be odd.
What: /sys/class/mtd/mtdX/erasesize
@@ -229,6 +229,14 @@ KernelVersion: 4.1
Contact: linux-mtd@lists.infradead.org
Description:
For a partition, the offset of that partition from the start
- of the master device in bytes. This attribute is absent on
- main devices, so it can be used to distinguish between
- partitions and devices that aren't partitions.
+ of the parent (another partition or a flash device) in bytes.
+ This attribute is absent on flash devices, so it can be used
+ to distinguish them from partitions.
+
+What: /sys/class/mtd/mtdX/oobavail
+Date: April 2018
+KernelVersion: 4.16
+Contact: linux-mtd@lists.infradead.org
+Description:
+ Number of bytes available for a client to place data into
+ the out of band area.
diff --git a/Documentation/ABI/testing/sysfs-class-mux b/Documentation/ABI/testing/sysfs-class-mux
new file mode 100644
index 000000000000..c58b7b6e1aa6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-mux
@@ -0,0 +1,16 @@
+What: /sys/class/mux/
+Date: April 2017
+KernelVersion: 4.13
+Contact: Peter Rosin <peda@axentia.se>
+Description:
+ The mux/ class sub-directory belongs to the Generic MUX
+ Framework and provides a sysfs interface for using MUX
+ controllers.
+
+What: /sys/class/mux/muxchip<N>/
+Date: April 2017
+KernelVersion: 4.13
+Contact: Peter Rosin <peda@axentia.se>
+Description:
+ A /sys/class/mux/muxchipN directory is created for each
+ probed MUX chip where N is a simple enumeration.
diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net
index 5ecfd72ba684..ebf21beba846 100644
--- a/Documentation/ABI/testing/sysfs-class-net
+++ b/Documentation/ABI/testing/sysfs-class-net
@@ -4,10 +4,13 @@ KernelVersion: 3.17
Contact: netdev@vger.kernel.org
Description:
Indicates the name assignment type. Possible values are:
- 1: enumerated by the kernel, possibly in an unpredictable way
- 2: predictably named by the kernel
- 3: named by userspace
- 4: renamed
+
+ == ==========================================================
+ 1 enumerated by the kernel, possibly in an unpredictable way
+ 2 predictably named by the kernel
+ 3 named by userspace
+ 4 renamed
+ == ==========================================================
What: /sys/class/net/<iface>/addr_assign_type
Date: July 2010
@@ -15,10 +18,13 @@ KernelVersion: 3.2
Contact: netdev@vger.kernel.org
Description:
Indicates the address assignment type. Possible values are:
- 0: permanent address
- 1: randomly generated
- 2: stolen from another device
- 3: set using dev_set_mac_address
+
+ == =============================
+ 0 permanent address
+ 1 randomly generated
+ 2 stolen from another device
+ 3 set using dev_set_mac_address
+ == =============================
What: /sys/class/net/<iface>/addr_len
Date: April 2005
@@ -39,6 +45,28 @@ Description:
Format is a string, e.g: 00:11:22:33:44:55 for an Ethernet MAC
address.
+What: /sys/class/net/<bridge iface>/bridge/group_fwd_mask
+Date: January 2012
+KernelVersion: 3.2
+Contact: netdev@vger.kernel.org
+Description:
+ Bitmask to allow forwarding of link local frames with address
+ 01-80-C2-00-00-0X on a bridge device. Only values that set bits
+ not matching BR_GROUPFWD_RESTRICTED in net/bridge/br_private.h
+ allowed.
+ Default value 0 does not forward any link local frames.
+
+ Restricted bits:
+
+ == ========================================================
+ 0 01-80-C2-00-00-00 Bridge Group Address used for STP
+ 1 01-80-C2-00-00-01 (MAC Control) 802.3 used for MAC PAUSE
+ 2 01-80-C2-00-00-02 (Link Aggregation) 802.3ad
+ == ========================================================
+
+ Any values not setting these bits can be used. Take special
+ care when forwarding control frames e.g. 802.1X-PAE or LLDP.
+
What: /sys/class/net/<iface>/broadcast
Date: April 2005
KernelVersion: 2.6.12
@@ -54,9 +82,12 @@ KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the current physical link state of the interface.
- Posssible values are:
- 0: physical link is down
- 1: physical link is up
+ Possible values are:
+
+ == =====================
+ 0 physical link is down
+ 1 physical link is up
+ == =====================
Note: some special devices, e.g: bonding and team drivers will
allow this attribute to be written to force a link state for
@@ -72,6 +103,24 @@ Description:
stacked (e.g: VLAN interfaces) but still have the same MAC
address as their parent device.
+What: /sys/class/net/<iface>/dev_port
+Date: February 2014
+KernelVersion: 3.15
+Contact: netdev@vger.kernel.org
+Description:
+ Indicates the port number of this network device, formatted
+ as a decimal value. Some NICs have multiple independent ports
+ on the same PCI bus, device and function. This attribute allows
+ userspace to distinguish the respective interfaces.
+
+ Note: some device drivers started to use 'dev_id' for this
+ purpose since long before 3.15 and have not adopted the new
+ attribute ever since. To query the port number, some tools look
+ exclusively at 'dev_port', while others only consult 'dev_id'.
+ If a network device has multiple client adapter ports as
+ described in the previous paragraph and does not set this
+ attribute to its port number, it's a kernel bug.
+
What: /sys/class/net/<iface>/dormant
Date: March 2006
KernelVersion: 2.6.17
@@ -87,18 +136,37 @@ Description:
authentication is performed (e.g: 802.1x). 'link_mode' attribute
will also reflect the dormant state.
-What: /sys/clas/net/<iface>/duplex
+What: /sys/class/net/<iface>/testing
+Date: April 2002
+KernelVersion: 5.8
+Contact: netdev@vger.kernel.org
+Description:
+ Indicates whether the interface is under test. Possible
+ values are:
+
+ == =============================
+ 0 interface is not being tested
+ 1 interface is being tested
+ == =============================
+
+ When an interface is under test, it cannot be expected
+ to pass packets as normal.
+
+What: /sys/class/net/<iface>/duplex
Date: October 2009
KernelVersion: 2.6.33
Contact: netdev@vger.kernel.org
Description:
Indicates the interface latest or current duplex value. Possible
values are:
- half: half duplex
- full: full duplex
+
+ ==== ===========
+ half half duplex
+ full full duplex
+ ==== ===========
Note: This attribute is only valid for interfaces that implement
- the ethtool get_settings method (mostly Ethernet).
+ the ethtool get_link_ksettings method (mostly Ethernet).
What: /sys/class/net/<iface>/flags
Date: April 2005
@@ -146,8 +214,11 @@ Description:
Indicates the interface link mode, as a decimal number. This
attribute should be used in conjunction with 'dormant' attribute
to determine the interface usability. Possible values:
- 0: default link mode
- 1: dormant link mode
+
+ == =================
+ 0 default link mode
+ 1 dormant link mode
+ == =================
What: /sys/class/net/<iface>/mtu
Date: April 2005
@@ -176,7 +247,9 @@ KernelVersion: 2.6.17
Contact: netdev@vger.kernel.org
Description:
Indicates the interface RFC2863 operational state as a string.
+
Possible values are:
+
"unknown", "notpresent", "down", "lowerlayerdown", "testing",
"dormant", "up".
@@ -205,7 +278,7 @@ Description:
an integer representing the link speed in Mbits/sec.
Note: this attribute is only valid for interfaces that implement
- the ethtool get_settings method (mostly Ethernet ).
+ the ethtool get_link_ksettings method (mostly Ethernet).
What: /sys/class/net/<iface>/tx_queue_len
Date: April 2005
@@ -232,3 +305,50 @@ Contact: netdev@vger.kernel.org
Description:
Indicates the unique physical switch identifier of a switch this
port belongs to, as a string.
+
+What: /sys/class/net/<iface>/phydev
+Date: May 2017
+KernelVersion: 4.13
+Contact: netdev@vger.kernel.org
+Description:
+ Symbolic link to the PHY device this network device is attached
+ to.
+
+What: /sys/class/net/<iface>/carrier_changes
+Date: Mar 2014
+KernelVersion: 3.15
+Contact: netdev@vger.kernel.org
+Description:
+ 32-bit unsigned integer counting the number of times the link has
+ seen a change from UP to DOWN and vice versa
+
+What: /sys/class/net/<iface>/carrier_up_count
+Date: Jan 2018
+KernelVersion: 4.16
+Contact: netdev@vger.kernel.org
+Description:
+ 32-bit unsigned integer counting the number of times the link has
+ been up
+
+What: /sys/class/net/<iface>/carrier_down_count
+Date: Jan 2018
+KernelVersion: 4.16
+Contact: netdev@vger.kernel.org
+Description:
+ 32-bit unsigned integer counting the number of times the link has
+ been down
+
+What: /sys/class/net/<iface>/threaded
+Date: Jan 2021
+KernelVersion: 5.12
+Contact: netdev@vger.kernel.org
+Description:
+ Boolean value to control the threaded mode per device. User could
+ set this value to enable/disable threaded mode for all napi
+ belonging to this device, without the need to do device up/down.
+
+ Possible values:
+ == ==================================
+ 0 threaded mode disabled for this dev
+ 1 threaded mode enabled for this dev
+ == ==================================
diff --git a/Documentation/ABI/testing/sysfs-class-net-batman-adv b/Documentation/ABI/testing/sysfs-class-net-batman-adv
deleted file mode 100644
index 7f34a95bb963..000000000000
--- a/Documentation/ABI/testing/sysfs-class-net-batman-adv
+++ /dev/null
@@ -1,15 +0,0 @@
-
-What: /sys/class/net/<iface>/batman-adv/iface_status
-Date: May 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Indicates the status of <iface> as it is seen by batman.
-
-What: /sys/class/net/<iface>/batman-adv/mesh_iface
-Date: May 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- The /sys/class/net/<iface>/batman-adv/mesh_iface file
- displays the batman mesh interface this <iface>
- currently is associated with.
-
diff --git a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
index 5cedf72df358..06416d0e163d 100644
--- a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
+++ b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
@@ -19,6 +19,25 @@ Description:
Set to 0 to pad all frames. Set greater than tx_max to
disable all padding.
+What: /sys/class/net/<iface>/cdc_ncm/ndp_to_end
+Date: Dec 2015
+KernelVersion: 4.5
+Contact: Bjørn Mork <bjorn@mork.no>
+Description:
+ Boolean attribute showing the status of the "NDP to
+ end" quirk. Defaults to 'N', except for devices
+ already known to need it enabled.
+
+ The "NDP to end" quirk makes the driver place the NDP
+ (the packet index table) after the payload. The NCM
+ specification does not mandate this, but some devices
+ are known to be more restrictive. Write 'Y' to this
+ attribute for temporary testing of a suspect device
+ failing to work with the default driver settings.
+
+ A device entry should be added to the driver if this
+ quirk is found to be required.
+
What: /sys/class/net/<iface>/cdc_ncm/rx_max
Date: May 2014
KernelVersion: 3.16
@@ -72,9 +91,9 @@ Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
- Bit 0: 16-bit NTB supported (set to 1)
- Bit 1: 32-bit NTB supported
- Bits 2 – 15: reserved (reset to zero; must be ignored by host)
+ - Bit 0: 16-bit NTB supported (set to 1)
+ - Bit 1: 32-bit NTB supported
+ - Bits 2 – 15: reserved (reset to zero; must be ignored by host)
What: /sys/class/net/<iface>/cdc_ncm/dwNtbInMaxSize
Date: May 2014
diff --git a/Documentation/ABI/testing/sysfs-class-net-dsa b/Documentation/ABI/testing/sysfs-class-net-dsa
new file mode 100644
index 000000000000..e2da26b44dd0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-net-dsa
@@ -0,0 +1,14 @@
+What: /sys/class/net/<iface>/dsa/tagging
+Date: August 2018
+KernelVersion: 4.20
+Contact: netdev@vger.kernel.org
+Description:
+ On read, this file returns a string indicating the type of
+ tagging protocol used by the DSA network devices that are
+ attached to this master interface.
+ On write, this file changes the tagging protocol of the
+ attached DSA switches, if this operation is supported by the
+ driver. Changing the tagging protocol must be done with the DSA
+ interfaces and the master interface all administratively down.
+ See the "name" field of each registered struct dsa_device_ops
+ for a list of valid values.
diff --git a/Documentation/ABI/testing/sysfs-class-net-janz-ican3 b/Documentation/ABI/testing/sysfs-class-net-janz-ican3
new file mode 100644
index 000000000000..fdbc03a2b8f8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-net-janz-ican3
@@ -0,0 +1,19 @@
+What: /sys/class/net/<iface>/termination
+Date: May 2010
+KernelVersion: 2.6.35
+Contact: Ira W. Snyder <ira.snyder@gmail.com>
+Description:
+ Value representing the can bus termination
+
+ Default: 1 (termination active)
+ Reading: get actual termination state
+ Writing: set actual termination state (0=no termination, 1=termination active)
+
+What: /sys/class/net/<iface>/fwinfo
+Date: May 2015
+KernelVersion: 3.19
+Contact: Andreas Gröger <andreas24groeger@gmail.com>
+Description:
+ Firmware stamp of ican3 module
+ Read-only: 32 byte string identification of the ICAN3 module
+ (known values: "JANZ-ICAN3 ICANOS 1.xx", "JANZ-ICAN3 CAL/CANopen 1.xx")
diff --git a/Documentation/ABI/testing/sysfs-class-net-mesh b/Documentation/ABI/testing/sysfs-class-net-mesh
deleted file mode 100644
index c46406296631..000000000000
--- a/Documentation/ABI/testing/sysfs-class-net-mesh
+++ /dev/null
@@ -1,108 +0,0 @@
-
-What: /sys/class/net/<mesh_iface>/mesh/aggregated_ogms
-Date: May 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Indicates whether the batman protocol messages of the
- mesh <mesh_iface> shall be aggregated or not.
-
-What: /sys/class/net/<mesh_iface>/mesh/<vlan_subdir>/ap_isolation
-Date: May 2011
-Contact: Antonio Quartulli <antonio@meshcoding.com>
-Description:
- Indicates whether the data traffic going from a
- wireless client to another wireless client will be
- silently dropped. <vlan_subdir> is empty when referring
- to the untagged lan.
-
-What: /sys/class/net/<mesh_iface>/mesh/bonding
-Date: June 2010
-Contact: Simon Wunderlich <sw@simonwunderlich.de>
-Description:
- Indicates whether the data traffic going through the
- mesh will be sent using multiple interfaces at the
- same time (if available).
-
-What: /sys/class/net/<mesh_iface>/mesh/bridge_loop_avoidance
-Date: November 2011
-Contact: Simon Wunderlich <sw@simonwunderlich.de>
-Description:
- Indicates whether the bridge loop avoidance feature
- is enabled. This feature detects and avoids loops
- between the mesh and devices bridged with the soft
- interface <mesh_iface>.
-
-What: /sys/class/net/<mesh_iface>/mesh/fragmentation
-Date: October 2010
-Contact: Andreas Langer <an.langer@gmx.de>
-Description:
- Indicates whether the data traffic going through the
- mesh will be fragmented or silently discarded if the
- packet size exceeds the outgoing interface MTU.
-
-What: /sys/class/net/<mesh_iface>/mesh/gw_bandwidth
-Date: October 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Defines the bandwidth which is propagated by this
- node if gw_mode was set to 'server'.
-
-What: /sys/class/net/<mesh_iface>/mesh/gw_mode
-Date: October 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Defines the state of the gateway features. Can be
- either 'off', 'client' or 'server'.
-
-What: /sys/class/net/<mesh_iface>/mesh/gw_sel_class
-Date: October 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Defines the selection criteria this node will use
- to choose a gateway if gw_mode was set to 'client'.
-
-What: /sys/class/net/<mesh_iface>/mesh/hop_penalty
-Date: Oct 2010
-Contact: Linus Lüssing <linus.luessing@web.de>
-Description:
- Defines the penalty which will be applied to an
- originator message's tq-field on every hop.
-
-What: /sys/class/net/<mesh_iface>/mesh/isolation_mark
-Date: Nov 2013
-Contact: Antonio Quartulli <antonio@meshcoding.com>
-Description:
- Defines the isolation mark (and its bitmask) which
- is used to classify clients as "isolated" by the
- Extended Isolation feature.
-
-What: /sys/class/net/<mesh_iface>/mesh/multicast_mode
-Date: Feb 2014
-Contact: Linus Lüssing <linus.luessing@web.de>
-Description:
- Indicates whether multicast optimizations are enabled
- or disabled. If set to zero then all nodes in the
- mesh are going to use classic flooding for any
- multicast packet with no optimizations.
-
-What: /sys/class/net/<mesh_iface>/mesh/network_coding
-Date: Nov 2012
-Contact: Martin Hundeboll <martin@hundeboll.net>
-Description:
- Controls whether Network Coding (using some magic
- to send fewer wifi packets but still the same
- content) is enabled or not.
-
-What: /sys/class/net/<mesh_iface>/mesh/orig_interval
-Date: May 2010
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Defines the interval in milliseconds in which batman
- sends its protocol messages.
-
-What: /sys/class/net/<mesh_iface>/mesh/routing_algo
-Date: Dec 2011
-Contact: Marek Lindner <mareklindner@neomailbox.ch>
-Description:
- Defines the routing procotol this mesh instance
- uses to find the optimal paths through the mesh.
diff --git a/Documentation/ABI/testing/sysfs-class-net-peak_usb b/Documentation/ABI/testing/sysfs-class-net-peak_usb
new file mode 100644
index 000000000000..9e3d0bf4d4b2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-net-peak_usb
@@ -0,0 +1,19 @@
+
+What: /sys/class/net/<iface>/peak_usb/can_channel_id
+Date: November 2022
+KernelVersion: 6.2
+Contact: Stephane Grosjean <s.grosjean@peak-system.com>
+Description:
+ PEAK PCAN-USB devices support user-configurable CAN channel
+ identifiers. Contrary to a USB serial number, these identifiers
+ are writable and can be set per CAN interface. This means that
+ if a USB device exports multiple CAN interfaces, each of them
+ can be assigned a unique channel ID.
+ This attribute provides read-only access to the currently
+ configured value of the channel identifier. Depending on the
+ device type, the identifier has a length of 8 or 32 bit. The
+ value read from this attribute is always an 8 digit 32 bit
+ hexadecimal value in big endian format. If the device only
+ supports an 8 bit identifier, the upper 24 bit of the value are
+ set to zero.
+
diff --git a/Documentation/ABI/testing/sysfs-class-net-phydev b/Documentation/ABI/testing/sysfs-class-net-phydev
new file mode 100644
index 000000000000..31615c59bff9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-net-phydev
@@ -0,0 +1,75 @@
+What: /sys/class/mdio_bus/<bus>/<device>/attached_dev
+Date: May 2017
+KernelVersion: 4.13
+Contact: netdev@vger.kernel.org
+Description:
+ Symbolic link to the network device this PHY device is
+ attached to.
+
+What: /sys/class/mdio_bus/<bus>/<device>/phy_has_fixups
+Date: February 2014
+KernelVersion: 3.15
+Contact: netdev@vger.kernel.org
+Description:
+ This attribute contains the boolean value whether a given PHY
+ device has had any "fixup" workaround running on it, encoded as
+ a boolean. This information is provided to help troubleshooting
+ PHY configurations.
+
+What: /sys/class/mdio_bus/<bus>/<device>/phy_id
+Date: November 2012
+KernelVersion: 3.8
+Contact: netdev@vger.kernel.org
+Description:
+ This attribute contains the 32-bit PHY Identifier as reported
+ by the device during bus enumeration, encoded in hexadecimal.
+ This ID is used to match the device with the appropriate
+ driver.
+
+What: /sys/class/mdio_bus/<bus>/<device>/c45_phy_ids/mmd<n>_device_id
+Date: June 2025
+KernelVersion: 6.17
+Contact: netdev@vger.kernel.org
+Description:
+ This attribute contains the 32-bit PHY Identifier as reported
+ by the device during bus enumeration, encoded in hexadecimal.
+ These C45 IDs are used to match the device with the appropriate
+ driver. These files are invisible to the C22 device.
+
+What: /sys/class/mdio_bus/<bus>/<device>/phy_interface
+Date: February 2014
+KernelVersion: 3.15
+Contact: netdev@vger.kernel.org
+Description:
+ This attribute contains the PHY interface as configured by the
+ Ethernet driver during bus enumeration, encoded in string.
+ This interface mode is used to configure the Ethernet MAC with the
+ appropriate mode for its data lines to the PHY hardware.
+
+ Possible values are:
+
+ <empty> (not available), mii, gmii, sgmii, tbi, rev-mii,
+ rmii, rgmii, rgmii-id, rgmii-rxid, rgmii-txid, rtbi, smii
+ xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui,
+ xaui, 10gbase-kr, unknown
+
+What: /sys/class/mdio_bus/<bus>/<device>/phy_standalone
+Date: May 2019
+KernelVersion: 5.3
+Contact: netdev@vger.kernel.org
+Description:
+ Boolean value indicating whether the PHY device is used in
+ standalone mode, without a net_device associated, by PHYLINK.
+ Attribute created only when this is the case.
+
+What: /sys/class/mdio_bus/<bus>/<device>/phy_dev_flags
+Date: March 2021
+KernelVersion: 5.13
+Contact: netdev@vger.kernel.org
+Description:
+ 32-bit hexadecimal number representing a bit mask of the
+ configuration bits passed from the consumer of the PHY
+ (Ethernet MAC, switch, etc.) to the PHY driver. The flags are
+ only used internally by the kernel and their placement are
+ not meant to be stable across kernel versions. This is intended
+ for facilitating the debugging of PHY drivers.
diff --git a/Documentation/ABI/testing/sysfs-class-net-qmi b/Documentation/ABI/testing/sysfs-class-net-qmi
new file mode 100644
index 000000000000..b028f5bc86db
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-net-qmi
@@ -0,0 +1,76 @@
+What: /sys/class/net/<iface>/qmi/raw_ip
+Date: Dec 2015
+KernelVersion: 4.4
+Contact: Bjørn Mork <bjorn@mork.no>
+Description:
+ Boolean. Default: 'N'
+
+ Set this to 'Y' to change the network device link
+ framing from '802.3' to 'raw-ip'.
+
+ The netdev will change to reflect the link framing
+ mode. The netdev is an ordinary ethernet device in
+ '802.3' mode, and the driver expects to exchange
+ frames with an ethernet header over the USB link. The
+ netdev is a headerless p-t-p device in 'raw-ip' mode,
+ and the driver expects to echange IPv4 or IPv6 packets
+ without any L2 header over the USB link.
+
+ Userspace is in full control of firmware configuration
+ through the delegation of the QMI protocol. Userspace
+ is responsible for coordination of driver and firmware
+ link framing mode, changing this setting to 'Y' if the
+ firmware is configured for 'raw-ip' mode.
+
+What: /sys/class/net/<iface>/qmi/add_mux
+Date: March 2017
+KernelVersion: 4.11
+Contact: Bjørn Mork <bjorn@mork.no>
+Description:
+ Unsigned integer.
+
+ Write a number ranging from 1 to 254 to add a qmap mux
+ based network device, supported by recent Qualcomm based
+ modems.
+
+ The network device will be called qmimux.
+
+ Userspace is in charge of managing the qmux network device
+ activation and data stream setup on the modem side by
+ using the proper QMI protocol requests.
+
+What: /sys/class/net/<iface>/qmi/del_mux
+Date: March 2017
+KernelVersion: 4.11
+Contact: Bjørn Mork <bjorn@mork.no>
+Description:
+ Unsigned integer.
+
+ Write a number ranging from 1 to 254 to delete a previously
+ created qmap mux based network device.
+
+What: /sys/class/net/<qmimux iface>/qmap/mux_id
+Date: January 2021
+KernelVersion: 5.12
+Contact: Daniele Palmas <dnlplm@gmail.com>
+Description:
+ Unsigned integer
+
+ Indicates the mux id associated to the qmimux network interface
+ during its creation.
+
+What: /sys/class/net/<iface>/qmi/pass_through
+Date: January 2021
+KernelVersion: 5.12
+Contact: Subash Abhinov Kasiviswanathan <quic_subashab@quicinc.com>
+Description:
+ Boolean. Default: 'N'
+
+ Set this to 'Y' to enable 'pass-through' mode, allowing packets
+ in MAP format to be passed on to the stack.
+
+ Normally the rmnet driver (CONFIG_RMNET) is then used to process
+ and demultiplex these packets.
+
+ 'Pass-through' mode can be enabled when the device is in
+ 'raw-ip' mode only.
diff --git a/Documentation/ABI/testing/sysfs-class-net-queues b/Documentation/ABI/testing/sysfs-class-net-queues
index 0c0df91b1516..84aa25e0d14d 100644
--- a/Documentation/ABI/testing/sysfs-class-net-queues
+++ b/Documentation/ABI/testing/sysfs-class-net-queues
@@ -1,4 +1,4 @@
-What: /sys/class/<iface>/queues/rx-<queue>/rps_cpus
+What: /sys/class/net/<iface>/queues/rx-<queue>/rps_cpus
Date: March 2010
KernelVersion: 2.6.35
Contact: netdev@vger.kernel.org
@@ -8,7 +8,7 @@ Description:
network device queue. Possible values depend on the number
of available CPU(s) in the system.
-What: /sys/class/<iface>/queues/rx-<queue>/rps_flow_cnt
+What: /sys/class/net/<iface>/queues/rx-<queue>/rps_flow_cnt
Date: April 2010
KernelVersion: 2.6.35
Contact: netdev@vger.kernel.org
@@ -16,7 +16,7 @@ Description:
Number of Receive Packet Steering flows being currently
processed by this particular network device receive queue.
-What: /sys/class/<iface>/queues/tx-<queue>/tx_timeout
+What: /sys/class/net/<iface>/queues/tx-<queue>/tx_timeout
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
@@ -24,7 +24,7 @@ Description:
Indicates the number of transmit timeout events seen by this
network interface transmit queue.
-What: /sys/class/<iface>/queues/tx-<queue>/tx_maxrate
+What: /sys/class/net/<iface>/queues/tx-<queue>/tx_maxrate
Date: March 2015
KernelVersion: 4.1
Contact: netdev@vger.kernel.org
@@ -32,17 +32,28 @@ Description:
A Mbps max-rate set for the queue, a value of zero means disabled,
default is disabled.
-What: /sys/class/<iface>/queues/tx-<queue>/xps_cpus
+What: /sys/class/net/<iface>/queues/tx-<queue>/xps_cpus
Date: November 2010
KernelVersion: 2.6.38
Contact: netdev@vger.kernel.org
Description:
Mask of the CPU(s) currently enabled to participate into the
Transmit Packet Steering packet processing flow for this
- network device transmit queue. Possible vaules depend on the
+ network device transmit queue. Possible values depend on the
number of available CPU(s) in the system.
-What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/hold_time
+What: /sys/class/net/<iface>/queues/tx-<queue>/xps_rxqs
+Date: June 2018
+KernelVersion: 4.18.0
+Contact: netdev@vger.kernel.org
+Description:
+ Mask of the receive queue(s) currently enabled to participate
+ into the Transmit Packet Steering packet processing flow for this
+ network device transmit queue. Possible values depend on the
+ number of available receive queue(s) in the network device.
+ Default is disabled.
+
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/hold_time
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
@@ -51,7 +62,7 @@ Description:
of this particular network device transmit queue.
Default value is 1000.
-What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/inflight
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/inflight
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
@@ -59,7 +70,7 @@ Description:
Indicates the number of bytes (objects) in flight on this
network device transmit queue.
-What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/limit
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
@@ -68,7 +79,7 @@ Description:
on this network device transmit queue. This value is clamped
to be within the bounds defined by limit_max and limit_min.
-What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit_max
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/limit_max
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
@@ -77,7 +88,7 @@ Description:
queued on this network device transmit queue. See
include/linux/dynamic_queue_limits.h for the default value.
-What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit_min
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/limit_min
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
@@ -85,3 +96,26 @@ Description:
Indicates the absolute minimum limit of bytes allowed to be
queued on this network device transmit queue. Default value is
0.
+
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/stall_thrs
+Date: Jan 2024
+KernelVersion: 6.9
+Contact: netdev@vger.kernel.org
+Description:
+ Tx completion stall detection threshold in ms. Kernel will
+ guarantee to detect all stalls longer than this threshold but
+ may also detect stalls longer than half of the threshold.
+
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/stall_cnt
+Date: Jan 2024
+KernelVersion: 6.9
+Contact: netdev@vger.kernel.org
+Description:
+ Number of detected Tx completion stalls.
+
+What: /sys/class/net/<iface>/queues/tx-<queue>/byte_queue_limits/stall_max
+Date: Jan 2024
+KernelVersion: 6.9
+Contact: netdev@vger.kernel.org
+Description:
+ Longest detected Tx completion stall. Write 0 to clear.
diff --git a/Documentation/ABI/testing/sysfs-class-net-statistics b/Documentation/ABI/testing/sysfs-class-net-statistics
index 397118de7b5e..53e508c6936a 100644
--- a/Documentation/ABI/testing/sysfs-class-net-statistics
+++ b/Documentation/ABI/testing/sysfs-class-net-statistics
@@ -1,4 +1,4 @@
-What: /sys/class/<iface>/statistics/collisions
+What: /sys/class/net/<iface>/statistics/collisions
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -6,7 +6,7 @@ Description:
Indicates the number of collisions seen by this network device.
This value might not be relevant with all MAC layers.
-What: /sys/class/<iface>/statistics/multicast
+What: /sys/class/net/<iface>/statistics/multicast
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -14,7 +14,7 @@ Description:
Indicates the number of multicast packets received by this
network device.
-What: /sys/class/<iface>/statistics/rx_bytes
+What: /sys/class/net/<iface>/statistics/rx_bytes
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -23,7 +23,7 @@ Description:
See the network driver for the exact meaning of when this
value is incremented.
-What: /sys/class/<iface>/statistics/rx_compressed
+What: /sys/class/net/<iface>/statistics/rx_compressed
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -32,7 +32,7 @@ Description:
network device. This value might only be relevant for interfaces
that support packet compression (e.g: PPP).
-What: /sys/class/<iface>/statistics/rx_crc_errors
+What: /sys/class/net/<iface>/statistics/rx_crc_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -41,7 +41,7 @@ Description:
by this network device. Note that the specific meaning might
depend on the MAC layer used by the interface.
-What: /sys/class/<iface>/statistics/rx_dropped
+What: /sys/class/net/<iface>/statistics/rx_dropped
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -51,7 +51,15 @@ Description:
packet processing. See the network driver for the exact
meaning of this value.
-What: /sys/class/<iface>/statistics/rx_fifo_errors
+What: /sys/class/net/<iface>/statistics/rx_errors
+Date: April 2005
+KernelVersion: 2.6.12
+Contact: netdev@vger.kernel.org
+Description:
+ Indicates the number of receive errors on this network device.
+ See the network driver for the exact meaning of this value.
+
+What: /sys/class/net/<iface>/statistics/rx_fifo_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -60,7 +68,7 @@ Description:
network device. See the network driver for the exact
meaning of this value.
-What: /sys/class/<iface>/statistics/rx_frame_errors
+What: /sys/class/net/<iface>/statistics/rx_frame_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -70,7 +78,7 @@ Description:
on the MAC layer protocol used. See the network driver for
the exact meaning of this value.
-What: /sys/class/<iface>/statistics/rx_length_errors
+What: /sys/class/net/<iface>/statistics/rx_length_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -79,7 +87,7 @@ Description:
error, oversized or undersized. See the network driver for the
exact meaning of this value.
-What: /sys/class/<iface>/statistics/rx_missed_errors
+What: /sys/class/net/<iface>/statistics/rx_missed_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -88,7 +96,15 @@ Description:
due to lack of capacity in the receive side. See the network
driver for the exact meaning of this value.
-What: /sys/class/<iface>/statistics/rx_over_errors
+What: /sys/class/net/<iface>/statistics/rx_nohandler
+Date: February 2016
+KernelVersion: 4.6
+Contact: netdev@vger.kernel.org
+Description:
+ Indicates the number of received packets that were dropped on
+ an inactive device by the network core.
+
+What: /sys/class/net/<iface>/statistics/rx_over_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -98,7 +114,7 @@ Description:
(e.g: larger than MTU). See the network driver for the exact
meaning of this value.
-What: /sys/class/<iface>/statistics/rx_packets
+What: /sys/class/net/<iface>/statistics/rx_packets
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -106,7 +122,7 @@ Description:
Indicates the total number of good packets received by this
network device.
-What: /sys/class/<iface>/statistics/tx_aborted_errors
+What: /sys/class/net/<iface>/statistics/tx_aborted_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -116,7 +132,7 @@ Description:
a medium collision). See the network driver for the exact
meaning of this value.
-What: /sys/class/<iface>/statistics/tx_bytes
+What: /sys/class/net/<iface>/statistics/tx_bytes
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -127,7 +143,7 @@ Description:
transmitted packets or all packets that have been queued for
transmission.
-What: /sys/class/<iface>/statistics/tx_carrier_errors
+What: /sys/class/net/<iface>/statistics/tx_carrier_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -136,7 +152,7 @@ Description:
because of carrier errors (e.g: physical link down). See the
network driver for the exact meaning of this value.
-What: /sys/class/<iface>/statistics/tx_compressed
+What: /sys/class/net/<iface>/statistics/tx_compressed
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -145,7 +161,7 @@ Description:
this might only be relevant for devices that support
compression (e.g: PPP).
-What: /sys/class/<iface>/statistics/tx_dropped
+What: /sys/class/net/<iface>/statistics/tx_dropped
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -154,7 +170,7 @@ Description:
See the driver for the exact reasons as to why the packets were
dropped.
-What: /sys/class/<iface>/statistics/tx_errors
+What: /sys/class/net/<iface>/statistics/tx_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -163,7 +179,7 @@ Description:
a network device. See the driver for the exact reasons as to
why the packets were dropped.
-What: /sys/class/<iface>/statistics/tx_fifo_errors
+What: /sys/class/net/<iface>/statistics/tx_fifo_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -172,7 +188,7 @@ Description:
FIFO error. See the driver for the exact reasons as to why the
packets were dropped.
-What: /sys/class/<iface>/statistics/tx_heartbeat_errors
+What: /sys/class/net/<iface>/statistics/tx_heartbeat_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -181,7 +197,7 @@ Description:
reported as heartbeat errors. See the driver for the exact
reasons as to why the packets were dropped.
-What: /sys/class/<iface>/statistics/tx_packets
+What: /sys/class/net/<iface>/statistics/tx_packets
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
@@ -190,7 +206,7 @@ Description:
device. See the driver for whether this reports the number of all
attempted or successful transmissions.
-What: /sys/class/<iface>/statistics/tx_window_errors
+What: /sys/class/net/<iface>/statistics/tx_window_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
new file mode 100644
index 000000000000..847a7edc3113
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-ocxl
@@ -0,0 +1,51 @@
+What: /sys/class/ocxl/<afu name>/afu_version
+Date: January 2018
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Version of the AFU, in the format <major>:<minor>
+ Reflects what is read in the configuration space of the AFU
+
+What: /sys/class/ocxl/<afu name>/contexts
+Date: January 2018
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Number of contexts for the AFU, in the format <n>/<max>
+ where:
+
+ ==== ===============================================
+ n number of currently active contexts, for debug
+ max maximum number of contexts supported by the AFU
+ ==== ===============================================
+
+What: /sys/class/ocxl/<afu name>/pp_mmio_size
+Date: January 2018
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Size of the per-process mmio area, as defined in the
+ configuration space of the AFU
+
+What: /sys/class/ocxl/<afu name>/global_mmio_size
+Date: January 2018
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Size of the global mmio area, as defined in the
+ configuration space of the AFU
+
+What: /sys/class/ocxl/<afu name>/global_mmio_area
+Date: January 2018
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Give access the global mmio area for the AFU
+
+What: /sys/class/ocxl/<afu name>/reload_on_reset
+Date: February 2020
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Control whether the FPGA is reloaded on a link reset. Enabled
+ through a vendor-specific logic block on the FPGA.
+
+ =========== ===========================================
+ 0 Do not reload FPGA image from flash
+ 1 Reload FPGA image from flash
+ unavailable The device does not support this capability
+ =========== ===========================================
diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd
deleted file mode 100644
index b1c3f0263359..000000000000
--- a/Documentation/ABI/testing/sysfs-class-pktcdvd
+++ /dev/null
@@ -1,72 +0,0 @@
-What: /sys/class/pktcdvd/
-Date: Oct. 2006
-KernelVersion: 2.6.20
-Contact: Thomas Maier <balagi@justmail.de>
-Description:
-
-sysfs interface
----------------
-
-The pktcdvd module (packet writing driver) creates
-these files in the sysfs:
-(<devid> is in format major:minor )
-
-/sys/class/pktcdvd/
- add (0200) Write a block device id (major:minor)
- to create a new pktcdvd device and map
- it to the block device.
-
- remove (0200) Write the pktcdvd device id (major:minor)
- to it to remove the pktcdvd device.
-
- device_map (0444) Shows the device mapping in format:
- pktcdvd[0-7] <pktdevid> <blkdevid>
-
-/sys/class/pktcdvd/pktcdvd[0-7]/
- dev (0444) Device id
- uevent (0200) To send an uevent.
-
-/sys/class/pktcdvd/pktcdvd[0-7]/stat/
- packets_started (0444) Number of started packets.
- packets_finished (0444) Number of finished packets.
-
- kb_written (0444) kBytes written.
- kb_read (0444) kBytes read.
- kb_read_gather (0444) kBytes read to fill write packets.
-
- reset (0200) Write any value to it to reset
- pktcdvd device statistic values, like
- bytes read/written.
-
-/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/
- size (0444) Contains the size of the bio write
- queue.
-
- congestion_off (0644) If bio write queue size is below
- this mark, accept new bio requests
- from the block layer.
-
- congestion_on (0644) If bio write queue size is higher
- as this mark, do no longer accept
- bio write requests from the block
- layer and wait till the pktcdvd
- device has processed enough bio's
- so that bio write queue size is
- below congestion off mark.
- A value of <= 0 disables congestion
- control.
-
-
-Example:
---------
-To use the pktcdvd sysfs interface directly, you can do:
-
-# create a new pktcdvd device mapped to /dev/hdc
-echo "22:0" >/sys/class/pktcdvd/add
-cat /sys/class/pktcdvd/device_map
-# assuming device pktcdvd0 was created, look at stat's
-cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written
-# print the device id of the mapped block device
-fgrep pktcdvd0 /sys/class/pktcdvd/device_map
-# remove device, using pktcdvd0 device id 253:0
-echo "253:0" >/sys/class/pktcdvd/remove
diff --git a/Documentation/ABI/testing/sysfs-class-platform-profile b/Documentation/ABI/testing/sysfs-class-platform-profile
new file mode 100644
index 000000000000..fcab26894ec3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-platform-profile
@@ -0,0 +1,50 @@
+What: /sys/class/platform-profile/platform-profile-X/name
+Date: March 2025
+KernelVersion: 6.14
+Description: Name of the class device given by the driver.
+
+ RO
+
+What: /sys/class/platform-profile/platform-profile-X/choices
+Date: March 2025
+KernelVersion: 6.14
+Description: This file contains a space-separated list of profiles supported
+ for this device.
+
+ Drivers must use the following standard profile-names:
+
+ ==================== ========================================
+ low-power Low power consumption
+ cool Cooler operation
+ quiet Quieter operation
+ balanced Balance between low power consumption
+ and performance
+ balanced-performance Balance between performance and low
+ power consumption with a slight bias
+ towards performance
+ performance High performance operation
+ max-power Higher performance operation that may exceed
+ internal battery draw limits when on AC power
+ custom Driver defined custom profile
+ ==================== ========================================
+
+ RO
+
+What: /sys/class/platform-profile/platform-profile-X/profile
+Date: March 2025
+KernelVersion: 6.14
+Description: Reading this file gives the current selected profile for this
+ device. Writing this file with one of the strings from
+ platform_profile_choices changes the profile to the new value.
+
+ This file can be monitored for changes by polling for POLLPRI,
+ POLLPRI will be signaled on any changes, independent of those
+ changes coming from a userspace write; or coming from another
+ source such as e.g. a hotkey triggered profile change handled
+ either directly by the embedded-controller or fully handled
+ inside the kernel.
+
+ This file may also emit the string 'custom' to indicate
+ that the driver is using a driver defined custom profile.
+
+ RW
diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index 369d2a2d7d3e..4b21d5d23251 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -1,3 +1,684 @@
+**General Properties**
+
+What: /sys/class/power_supply/<supply_name>/manufacturer
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the name of the device manufacturer.
+
+ Access: Read
+ Valid values: Represented as string
+
+What: /sys/class/power_supply/<supply_name>/model_name
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the name of the device model.
+
+ Access: Read
+ Valid values: Represented as string
+
+What: /sys/class/power_supply/<supply_name>/serial_number
+Date: January 2008
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the serial number of the device.
+
+ Access: Read
+ Valid values: Represented as string
+
+What: /sys/class/power_supply/<supply_name>/type
+Date: May 2010
+Contact: linux-pm@vger.kernel.org
+Description:
+ Describes the main type of the supply.
+
+ Access: Read
+ Valid values: "Battery", "UPS", "Mains", "USB", "Wireless"
+
+**Battery and USB properties**
+
+What: /sys/class/power_supply/<supply_name>/current_avg
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports an average IBAT current reading for the battery, over
+ a fixed period. Normally devices will provide a fixed interval
+ in which they average readings to smooth out the reported
+ value.
+
+ USB:
+
+ Reports an average IBUS current reading over a fixed period.
+ Normally devices will provide a fixed interval in which they
+ average readings to smooth out the reported value.
+
+ Access: Read
+
+ Valid values: Represented in microamps. Negative values are
+ used for discharging batteries, positive values for charging
+ batteries and for USB IBUS current.
+
+What: /sys/class/power_supply/<supply_name>/current_max
+Date: October 2010
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports the maximum IBAT current allowed into the battery.
+
+ USB:
+
+ Reports the maximum IBUS current the supply can support.
+
+ Access: Read
+ Valid values: Represented in microamps
+
+What: /sys/class/power_supply/<supply_name>/current_now
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+
+ Battery:
+
+ Reports an instant, single IBAT current reading for the
+ battery. This value is not averaged/smoothed.
+
+ Access: Read
+
+ USB:
+
+ Reports the IBUS current supplied now. This value is generally
+ read-only reporting, unless the 'online' state of the supply
+ is set to be programmable, in which case this value can be set
+ within the reported min/max range.
+
+ Access: Read, Write
+
+ Valid values: Represented in microamps. Negative values are
+ used for discharging batteries, positive values for charging
+ batteries and for USB IBUS current.
+
+What: /sys/class/power_supply/<supply_name>/temp
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports the current TBAT battery temperature reading.
+
+ USB:
+
+ Reports the current supply temperature reading. This would
+ normally be the internal temperature of the device itself
+ (e.g TJUNC temperature of an IC)
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/<supply_name>/temp_alert_max
+Date: July 2012
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Maximum TBAT temperature trip-wire value where the supply will
+ notify user-space of the event.
+
+ USB:
+
+ Maximum supply temperature trip-wire value where the supply
+ will notify user-space of the event.
+
+ This is normally used for the charging scenario where
+ user-space needs to know if the temperature has crossed an
+ upper threshold so it can take appropriate action (e.g. warning
+ user that the temperature is critically high, and charging has
+ stopped).
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/<supply_name>/temp_alert_min
+Date: July 2012
+Contact: linux-pm@vger.kernel.org
+Description:
+
+ Battery:
+
+ Minimum TBAT temperature trip-wire value where the supply will
+ notify user-space of the event.
+
+ USB:
+
+ Minimum supply temperature trip-wire value where the supply
+ will notify user-space of the event.
+
+ This is normally used for the charging scenario where user-space
+ needs to know if the temperature has crossed a lower threshold
+ so it can take appropriate action (e.g. warning user that
+ temperature level is high, and charging current has been
+ reduced accordingly to remedy the situation).
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/<supply_name>/temp_max
+Date: July 2014
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports the maximum allowed TBAT battery temperature for
+ charging.
+
+ USB:
+
+ Reports the maximum allowed supply temperature for operation.
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/<supply_name>/temp_min
+Date: July 2014
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports the minimum allowed TBAT battery temperature for
+ charging.
+
+ USB:
+
+ Reports the minimum allowed supply temperature for operation.
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/<supply_name>/voltage_max,
+Date: January 2008
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports the maximum safe VBAT voltage permitted for the
+ battery, during charging.
+
+ USB:
+
+ Reports the maximum VBUS voltage the supply can support.
+
+ Access: Read
+
+ Valid values: Represented in microvolts
+
+What: /sys/class/power_supply/<supply_name>/voltage_min,
+Date: January 2008
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports the minimum safe VBAT voltage permitted for the
+ battery, during discharging.
+
+ USB:
+
+ Reports the minimum VBUS voltage the supply can support.
+
+ Access: Read
+
+ Valid values: Represented in microvolts
+
+What: /sys/class/power_supply/<supply_name>/voltage_now,
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery:
+
+ Reports an instant, single VBAT voltage reading for the
+ battery. This value is not averaged/smoothed.
+
+ Access: Read
+
+ USB:
+
+ Reports the VBUS voltage supplied now. This value is generally
+ read-only reporting, unless the 'online' state of the supply
+ is set to be programmable, in which case this value can be set
+ within the reported min/max range.
+
+ Access: Read, Write
+
+ Valid values: Represented in microvolts
+
+**Battery Properties**
+
+What: /sys/class/power_supply/<supply_name>/capacity
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Fine grain representation of battery capacity.
+
+ Access: Read
+
+ Valid values: 0 - 100 (percent)
+
+What: /sys/class/power_supply/<supply_name>/capacity_alert_max
+Date: July 2012
+Contact: linux-pm@vger.kernel.org
+Description:
+ Maximum battery capacity trip-wire value where the supply will
+ notify user-space of the event. This is normally used for the
+ battery discharging scenario where user-space needs to know the
+ battery has dropped to an upper level so it can take
+ appropriate action (e.g. warning user that battery level is
+ low).
+
+ Access: Read, Write
+
+ Valid values: 0 - 100 (percent)
+
+What: /sys/class/power_supply/<supply_name>/capacity_alert_min
+Date: July 2012
+Contact: linux-pm@vger.kernel.org
+Description:
+ Minimum battery capacity trip-wire value where the supply will
+ notify user-space of the event. This is normally used for the
+ battery discharging scenario where user-space needs to know the
+ battery has dropped to a lower level so it can take
+ appropriate action (e.g. warning user that battery level is
+ critically low).
+
+ Access: Read, Write
+
+ Valid values: 0 - 100 (percent)
+
+What: /sys/class/power_supply/<supply_name>/capacity_error_margin
+Date: April 2019
+Contact: linux-pm@vger.kernel.org
+Description:
+ Battery capacity measurement becomes unreliable without
+ recalibration. This values provides the maximum error
+ margin expected to exist by the fuel gauge in percent.
+ Values close to 0% will be returned after (re-)calibration
+ has happened. Over time the error margin will increase.
+ 100% means, that the capacity related values are basically
+ completely useless.
+
+ Access: Read
+
+ Valid values: 0 - 100 (percent)
+
+What: /sys/class/power_supply/<supply_name>/capacity_level
+Date: June 2009
+Contact: linux-pm@vger.kernel.org
+Description:
+ Coarse representation of battery capacity.
+
+ Access: Read
+
+ Valid values:
+ "Unknown", "Critical", "Low", "Normal", "High",
+ "Full"
+
+What: /sys/class/power_supply/<supply_name>/charge_control_limit
+Date: Oct 2012
+Contact: linux-pm@vger.kernel.org
+Description:
+ Maximum allowable charging current. Used for charge rate
+ throttling for thermal cooling or improving battery health.
+
+ Access: Read, Write
+
+ Valid values: Represented in microamps
+
+What: /sys/class/power_supply/<supply_name>/charge_control_limit_max
+Date: Oct 2012
+Contact: linux-pm@vger.kernel.org
+Description:
+ Maximum legal value for the charge_control_limit property.
+
+ Access: Read
+
+ Valid values: Represented in microamps
+
+What: /sys/class/power_supply/<supply_name>/charge_control_start_threshold
+Date: April 2019
+Contact: linux-pm@vger.kernel.org
+Description:
+ Represents a battery percentage level, below which charging will
+ begin.
+
+ Access: Read, Write
+ Valid values: 0 - 100 (percent)
+
+What: /sys/class/power_supply/<supply_name>/charge_control_end_threshold
+Date: April 2019
+Contact: linux-pm@vger.kernel.org
+Description:
+ Represents a battery percentage level, above which charging will
+ stop. Not all hardware is capable of setting this to an arbitrary
+ percentage. Drivers will round written values to the nearest
+ supported value. Reading back the value will show the actual
+ threshold set by the driver.
+
+ Access: Read, Write
+
+ Valid values: 0 - 100 (percent)
+
+What: /sys/class/power_supply/<supply_name>/charge_type
+Date: July 2009
+Contact: linux-pm@vger.kernel.org
+Description:
+ Select the charging algorithm to use for a battery.
+
+ Standard:
+ Fully charge the battery at a moderate rate.
+ Fast:
+ Quickly charge the battery using fast-charge
+ technology. This is typically harder on the battery
+ than standard charging and may lower its lifespan.
+ Trickle:
+ Users who primarily operate the system while
+ plugged into an external power source can extend
+ battery life with this mode. Vendor tooling may
+ call this "Primarily AC Use".
+ Adaptive:
+ Automatically optimize battery charge rate based
+ on typical usage pattern.
+ Custom:
+ Use the charge_control_* properties to determine
+ when to start and stop charging. Advanced users
+ can use this to drastically extend battery life.
+ Long Life:
+ The charger reduces its charging rate in order to
+ prolong the battery health.
+ Bypass:
+ The charger bypasses the charging path around the
+ integrated converter allowing for a "smart" wall
+ adaptor to perform the power conversion externally.
+
+ Access: Read, Write
+
+ Reading this returns the current active value, e.g. 'Standard'.
+ Check charge_types to get the values supported by the battery.
+
+ Valid values:
+ "Unknown", "N/A", "Trickle", "Fast", "Standard",
+ "Adaptive", "Custom", "Long Life", "Bypass"
+
+What: /sys/class/power_supply/<supply_name>/charge_types
+Date: December 2024
+Contact: linux-pm@vger.kernel.org
+Description:
+ Identical to charge_type but reading returns a list of supported
+ charge-types with the currently active type surrounded by square
+ brackets, e.g.: "Fast [Standard] Long_Life".
+
+ power_supply class devices may support both charge_type and
+ charge_types for backward compatibility. In this case both will
+ always have the same active value and the active value can be
+ changed by writing either property.
+
+ Note charge-types which contain a space such as "Long Life" will
+ have the space replaced by a '_' resulting in e.g. "Long_Life".
+ When writing charge-types both variants are accepted.
+
+What: /sys/class/power_supply/<supply_name>/charge_term_current
+Date: July 2014
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the charging current value which is used to determine
+ when the battery is considered full and charging should end.
+
+ Access: Read
+
+ Valid values: Represented in microamps
+
+What: /sys/class/power_supply/<supply_name>/health
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the health of the battery or battery side of charger
+ functionality.
+
+ Access: Read
+
+ Valid values:
+ "Unknown", "Good", "Overheat", "Dead",
+ "Over voltage", "Under voltage", "Unspecified failure", "Cold",
+ "Watchdog timer expire", "Safety timer expire",
+ "Over current", "Calibration required", "Warm",
+ "Cool", "Hot", "No battery", "Blown fuse", "Cell imbalance"
+
+What: /sys/class/power_supply/<supply_name>/precharge_current
+Date: June 2017
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the charging current applied during pre-charging phase
+ for a battery charge cycle.
+
+ Access: Read
+
+ Valid values: Represented in microamps
+
+What: /sys/class/power_supply/<supply_name>/present
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports whether a battery is present or not in the system. If the
+ property does not exist, the battery is considered to be present.
+
+ Access: Read
+
+ Valid values:
+
+ == =======
+ 0: Absent
+ 1: Present
+ == =======
+
+What: /sys/class/power_supply/<supply_name>/status
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Represents the charging status of the battery. Normally this
+ is read-only reporting although for some supplies this can be
+ used to enable/disable charging to the battery.
+
+ Access: Read, Write
+
+ Valid values:
+ "Unknown", "Charging", "Discharging",
+ "Not charging", "Full"
+
+What: /sys/class/power_supply/<supply_name>/charge_behaviour
+Date: November 2021
+Contact: linux-pm@vger.kernel.org
+Description:
+ Represents the charging behaviour.
+
+ Access: Read, Write
+
+ Valid values:
+ ===================== ========================================
+ auto: Charge normally, respect thresholds
+ inhibit-charge: Do not charge while AC is attached
+ inhibit-charge-awake: inhibit-charge only when device is awake
+ force-discharge: Force discharge while AC is attached
+ ===================== ========================================
+
+What: /sys/class/power_supply/<supply_name>/technology
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Describes the battery technology supported by the supply.
+
+ Access: Read
+
+ Valid values:
+ "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
+ "NiCd", "LiMn"
+
+
+What: /sys/class/power_supply/<supply_name>/voltage_avg,
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports an average VBAT voltage reading for the battery, over a
+ fixed period. Normally devices will provide a fixed interval in
+ which they average readings to smooth out the reported value.
+
+ Access: Read
+
+ Valid values: Represented in microvolts
+
+What: /sys/class/power_supply/<supply_name>/cycle_count
+Date: January 2010
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the number of full charge + discharge cycles the
+ battery has undergone.
+
+ Access: Read
+
+ Valid values:
+ Integer > 0: representing full cycles
+ Integer = 0: cycle_count info is not available
+
+What: /sys/class/power_supply/<supply_name>/internal_resistance
+Date: August 2025
+Contact: linux-arm-msm@vger.kernel.org
+Description:
+ Represent the battery's internal resistance, often referred
+ to as Equivalent Series Resistance (ESR). It is a dynamic
+ parameter that reflects the opposition to current flow within
+ the cell. It is not a fixed value but varies significantly
+ based on several operational conditions, including battery
+ state of charge (SoC), temperature, and whether the battery
+ is in a charging or discharging state.
+
+ Access: Read
+
+ Valid values: Represented in microohms
+
+What: /sys/class/power_supply/<supply_name>/state_of_health
+Date: August 2025
+Contact: linux-arm-msm@vger.kernel.org
+Description:
+ The state_of_health parameter quantifies the overall condition
+ of a battery as a percentage, reflecting its ability to deliver
+ rated performance relative to its original specifications. It is
+ dynamically computed using a combination of learned capacity
+ and impedance-based degradation indicators, both of which evolve
+ over the battery's lifecycle.
+ Note that the exact algorithms are kept secret by most battery
+ vendors and the value from different battery vendors cannot be
+ compared with each other as there is no vendor-agnostic definition
+ of "performance". Also this usually cannot be used for any
+ calculations (i.e. this is not the factor between charge_full and
+ charge_full_design).
+
+ Access: Read
+
+ Valid values: 0 - 100 (percent)
+
+**USB Properties**
+
+What: /sys/class/power_supply/<supply_name>/input_current_limit
+Date: July 2014
+Contact: linux-pm@vger.kernel.org
+Description:
+ Details the incoming IBUS current limit currently set in the
+ supply. Normally this is configured based on the type of
+ connection made (e.g. A configured SDP should output a maximum
+ of 500mA so the input current limit is set to the same value).
+ Use preferably input_power_limit, and for problems that can be
+ solved using power limit use input_current_limit.
+
+ Access: Read, Write
+
+ Valid values: Represented in microamps
+
+What: /sys/class/power_supply/<supply_name>/input_voltage_limit
+Date: May 2019
+Contact: linux-pm@vger.kernel.org
+Description:
+ This entry configures the incoming VBUS voltage limit currently
+ set in the supply. Normally this is configured based on
+ system-level knowledge or user input (e.g. This is part of the
+ Pixel C's thermal management strategy to effectively limit the
+ input power to 5V when the screen is on to meet Google's skin
+ temperature targets). Note that this feature should not be
+ used for safety critical things.
+ Use preferably input_power_limit, and for problems that can be
+ solved using power limit use input_voltage_limit.
+
+ Access: Read, Write
+
+ Valid values: Represented in microvolts
+
+What: /sys/class/power_supply/<supply_name>/input_power_limit
+Date: May 2019
+Contact: linux-pm@vger.kernel.org
+Description:
+ This entry configures the incoming power limit currently set
+ in the supply. Normally this is configured based on
+ system-level knowledge or user input. Use preferably this
+ feature to limit the incoming power and use current/voltage
+ limit only for problems that can be solved using power limit.
+
+ Access: Read, Write
+
+ Valid values: Represented in microwatts
+
+What: /sys/class/power_supply/<supply_name>/online,
+Date: May 2007
+Contact: linux-pm@vger.kernel.org
+Description:
+ Indicates if VBUS is present for the supply. When the supply is
+ online, and the supply allows it, then it's possible to switch
+ between online states (e.g. Fixed -> Programmable for a PD_PPS
+ USB supply so voltage and current can be controlled).
+
+ Access: Read, Write
+
+ Valid values:
+
+ == ==================================================
+ 0: Offline
+ 1: Online Fixed - Fixed Voltage Supply
+ 2: Online Programmable - Programmable Voltage Supply
+ == ==================================================
+
+What: /sys/class/power_supply/<supply_name>/usb_type
+Date: March 2018
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports what type of USB connection is currently active for
+ the supply, for example it can show if USB-PD capable source
+ is attached.
+
+ Access: For power-supplies which consume USB power such
+ as battery charger chips, this indicates the type of
+ the connected USB power source and is Read-Only.
+
+ For power-supplies which act as a USB power-source such as
+ e.g. the UCS1002 USB Port Power Controller this is writable.
+
+ Valid values:
+ "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
+ "PD_DRP", "PD_PPS", "BrickID"
+
+**Device Specific Properties**
+
What: /sys/class/power/ds2760-battery.*/charge_now
Date: May 2010
KernelVersion: 2.6.35
@@ -22,7 +703,7 @@ Description:
What: /sys/class/power_supply/max14577-charger/device/fast_charge_timer
Date: October 2014
KernelVersion: 3.18.0
-Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com>
+Contact: Krzysztof Kozlowski <krzk@kernel.org>
Description:
This entry shows and sets the maximum time the max14577
charger operates in fast-charge mode. When the timer expires
@@ -30,13 +711,14 @@ Description:
will drop to 0 A) and will trigger interrupt.
Valid values:
+
- 5, 6 or 7 (hours),
- 0: disabled.
What: /sys/class/power_supply/max77693-charger/device/fast_charge_timer
Date: January 2015
KernelVersion: 3.19.0
-Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com>
+Contact: Krzysztof Kozlowski <krzk@kernel.org>
Description:
This entry shows and sets the maximum time the max77693
charger operates in fast-charge mode. When the timer expires
@@ -44,13 +726,14 @@ Description:
will drop to 0 A) and will trigger interrupt.
Valid values:
+
- 4 - 16 (hours), step by 2 (rounded down)
- 0: disabled.
What: /sys/class/power_supply/max77693-charger/device/top_off_threshold_current
Date: January 2015
KernelVersion: 3.19.0
-Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com>
+Contact: Krzysztof Kozlowski <krzk@kernel.org>
Description:
This entry shows and sets the charging current threshold for
entering top-off charging mode. When charging current in fast
@@ -58,6 +741,7 @@ Description:
interrupt and start top-off charging mode.
Valid values:
+
- 100000 - 200000 (microamps), step by 25000 (rounded down)
- 200000 - 350000 (microamps), step by 50000 (rounded down)
- 0: disabled.
@@ -65,7 +749,7 @@ Description:
What: /sys/class/power_supply/max77693-charger/device/top_off_timer
Date: January 2015
KernelVersion: 3.19.0
-Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com>
+Contact: Krzysztof Kozlowski <krzk@kernel.org>
Description:
This entry shows and sets the maximum time the max77693
charger operates in top-off charge mode. When the timer expires
@@ -73,4 +757,149 @@ Description:
will drop to 0 A) and will trigger interrupt.
Valid values:
+
+ - 0 - 70 (minutes), step by 10 (rounded down)
+
+What: /sys/class/power_supply/bq24257-charger/ovp_voltage
+Date: October 2015
+KernelVersion: 4.4.0
+Contact: Andreas Dannenberg <dannenberg@ti.com>
+Description:
+ This entry configures the overvoltage protection feature of bq24257-
+ type charger devices. This feature protects the device and other
+ components against damage from overvoltage on the input supply. See
+ device datasheet for details.
+
+ Valid values:
+
+ - 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000,
+ 10500000 (all uV)
+
+What: /sys/class/power_supply/bq24257-charger/in_dpm_voltage
+Date: October 2015
+KernelVersion: 4.4.0
+Contact: Andreas Dannenberg <dannenberg@ti.com>
+Description:
+ This entry configures the input dynamic power path management voltage of
+ bq24257-type charger devices. Once the supply drops to the configured
+ voltage, the input current limit is reduced down to prevent the further
+ drop of the supply. When the IC enters this mode, the charge current is
+ lower than the set value. See device datasheet for details.
+
+ Valid values:
+
+ - 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000,
+ 4760000 (all uV)
+
+What: /sys/class/power_supply/bq24257-charger/high_impedance_enable
+Date: October 2015
+KernelVersion: 4.4.0
+Contact: Andreas Dannenberg <dannenberg@ti.com>
+Description:
+ This entry allows enabling the high-impedance mode of bq24257-type
+ charger devices. If enabled, it places the charger IC into low power
+ standby mode with the switch mode controller disabled. When disabled,
+ the charger operates normally. See device datasheet for details.
+
+ Valid values:
+
+ - 1: enabled
+ - 0: disabled
+
+What: /sys/class/power_supply/bq24257-charger/sysoff_enable
+Date: October 2015
+KernelVersion: 4.4.0
+Contact: Andreas Dannenberg <dannenberg@ti.com>
+Description:
+ This entry allows enabling the sysoff mode of bq24257-type charger
+ devices. If enabled and the input is removed, the internal battery FET
+ is turned off in order to reduce the leakage from the BAT pin to less
+ than 1uA. Note that on some devices/systems this disconnects the battery
+ from the system. See device datasheet for details.
+
+ Valid values:
+
+ - 1: enabled
+ - 0: disabled
+
+What: /sys/class/power_supply/<supply_name>/manufacture_year
+Date: January 2020
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the year (following Gregorian calendar) when the device has been
+ manufactured.
+
+ Access: Read
+
+ Valid values: Reported as integer
+
+What: /sys/class/power_supply/<supply_name>/manufacture_month
+Date: January 2020
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the month when the device has been manufactured.
+
+ Access: Read
+
+ Valid values: 1-12
+
+What: /sys/class/power_supply/<supply_name>/manufacture_day
+Date: January 2020
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the day of month when the device has been manufactured.
+
+ Access: Read
+ Valid values: 1-31
+
+What: /sys/class/power_supply/<supply_name>/extensions/<extension_name>
+Date: March 2025
+Contact: linux-pm@vger.kernel.org
+Description:
+ Reports the extensions registered to the power supply.
+ Each entry is a link to the device which registered the extension.
+
+ Access: Read
+
+What: /sys/class/power_supply/max8971-charger/fast_charge_timer
+Date: May 2025
+KernelVersion: 6.15.0
+Contact: Svyatoslav Ryhel <clamor95@gmail.com>
+Description:
+ This entry shows and sets the maximum time the max8971
+ charger operates in fast-charge mode. When the timer expires
+ the device will terminate fast-charge mode (charging current
+ will drop to 0 A) and will trigger interrupt.
+
+ Valid values:
+
+ - 4 - 10 (hours), step by 1
+ - 0: disabled.
+
+What: /sys/class/power_supply/max8971-charger/top_off_threshold_current
+Date: May 2025
+KernelVersion: 6.15.0
+Contact: Svyatoslav Ryhel <clamor95@gmail.com>
+Description:
+ This entry shows and sets the charging current threshold for
+ entering top-off charging mode. When charging current in fast
+ charge mode drops below this value, the charger will trigger
+ interrupt and start top-off charging mode.
+
+ Valid values:
+
+ - 50000 - 200000 (microamps), step by 50000 (rounded down)
+
+What: /sys/class/power_supply/max8971-charger/top_off_timer
+Date: May 2025
+KernelVersion: 6.15.0
+Contact: Svyatoslav Ryhel <clamor95@gmail.com>
+Description:
+ This entry shows and sets the maximum time the max8971
+ charger operates in top-off charge mode. When the timer expires
+ the device will terminate top-off charge mode (charging current
+ will drop to 0 A) and will trigger interrupt.
+
+ Valid values:
+
- 0 - 70 (minutes), step by 10 (rounded down)
diff --git a/Documentation/ABI/testing/sysfs-class-power-gaokun b/Documentation/ABI/testing/sysfs-class-power-gaokun
new file mode 100644
index 000000000000..0633aed7b355
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-gaokun
@@ -0,0 +1,27 @@
+What: /sys/class/power_supply/gaokun-ec-battery/smart_charge_delay
+Date: March 2025
+KernelVersion: 6.15
+Contact: Pengyu Luo <mitltlatltl@gmail.com>
+Description:
+ This entry allows configuration of smart charging delay.
+
+ Smart charging behavior: when the power adapter is connected
+ for delay hours, battery charging will follow the rules of
+ charge_control_start_threshold and charge_control_end_threshold.
+ For more information about charge control, please refer to
+ sysfs-class-power.
+
+ Access: Read, Write
+
+ Valid values: In hours (non-negative)
+
+What: /sys/class/power_supply/gaokun-ec-battery/battery_adaptive_charge
+Date: March 2025
+KernelVersion: 6.15
+Contact: Pengyu Luo <mitltlatltl@gmail.com>
+Description:
+ This entry allows enabling battery adaptive charging.
+
+ Access: Read, Write
+
+ Valid values: 0 (disabled) or 1 (enabled)
diff --git a/Documentation/ABI/testing/sysfs-class-power-ltc4162l b/Documentation/ABI/testing/sysfs-class-power-ltc4162l
new file mode 100644
index 000000000000..ba30db93052b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-ltc4162l
@@ -0,0 +1,82 @@
+What: /sys/class/power_supply/ltc4162-l/charge_status
+Date: Januari 2021
+KernelVersion: 5.11
+Description:
+ Detailed charge status information as reported by the chip.
+
+ Access: Read
+
+ Valid values:
+ ilim_reg_active
+ thermal_reg_active
+ vin_uvcl_active
+ iin_limit_active
+ constant_current
+ constant_voltage
+ charger_off
+
+What: /sys/class/power_supply/ltc4162-l/ibat
+Date: Januari 2021
+KernelVersion: 5.11
+Description:
+ Battery input current as measured by the charger. Negative value
+ means that the battery is discharging.
+
+ Access: Read
+
+ Valid values: Signed value in microamps
+
+What: /sys/class/power_supply/ltc4162-l/vbat
+Date: Januari 2021
+KernelVersion: 5.11
+Description:
+ Battery voltage as measured by the charger.
+
+ Access: Read
+
+ Valid values: In microvolts
+
+What: /sys/class/power_supply/ltc4162-l/vbat_avg
+Date: Januari 2021
+KernelVersion: 5.11
+Description:
+ Battery voltage, averaged over time, as measured by the charger.
+
+ Access: Read
+
+ Valid values: In microvolts
+
+What: /sys/class/power_supply/ltc4162-l/force_telemetry
+Date: Januari 2021
+KernelVersion: 5.11
+Description:
+ To save battery current, the measurement system is disabled if
+ the battery is the only source of power. This affects all
+ voltage, current and temperature measurements.
+ Write a "1" to this to keep performing telemetry once every few
+ seconds, even when running on battery (as reported by the online
+ property, which is "1" when external power is available and "0"
+ when the system runs on battery).
+
+ Access: Read, Write
+
+ Valid values: 0 (disabled) or 1 (enabled)
+
+What: /sys/class/power_supply/ltc4162-l/arm_ship_mode
+Date: Januari 2021
+KernelVersion: 5.11
+Description:
+ The charger will normally drain the battery while inactive,
+ typically drawing about 54 microamps. Write a "1" to this
+ property to arm a special "ship" mode that extends shelf life
+ by reducing the leakage to about 2.8 microamps. The chip will
+ remain in this mode (and no longer respond to I2C commands)
+ until some external power-supply is attached raising the input
+ voltage above 1V. It will then automatically revert to "0".
+ Writing a "0" to the property cancels the "ship" mode request.
+ The ship mode, when armed, activates once the input voltage
+ drops below 1V.
+
+ Access: Read, Write
+
+ Valid values: 0 (disable) or 1 (enable)
diff --git a/Documentation/ABI/testing/sysfs-class-power-max1720x b/Documentation/ABI/testing/sysfs-class-power-max1720x
new file mode 100644
index 000000000000..7d895bfda9ce
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-max1720x
@@ -0,0 +1,32 @@
+What: /sys/class/power_supply/max1720x/temp_ain1
+Date: January 2025
+KernelVersion: 6.14
+Contact: Dimitri Fedrau <dimitri.fedrau@liebherr.com>
+Description:
+ Reports the current temperature reading from AIN1 thermistor.
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/max1720x/temp_ain2
+Date: January 2025
+KernelVersion: 6.14
+Contact: Dimitri Fedrau <dimitri.fedrau@liebherr.com>
+Description:
+ Reports the current temperature reading from AIN2 thermistor.
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
+
+What: /sys/class/power_supply/max1720x/temp_int
+Date: January 2025
+KernelVersion: 6.14
+Contact: Dimitri Fedrau <dimitri.fedrau@liebherr.com>
+Description:
+ Reports the current temperature reading from internal die.
+
+ Access: Read
+
+ Valid values: Represented in 1/10 Degrees Celsius
diff --git a/Documentation/ABI/testing/sysfs-class-power-mp2629 b/Documentation/ABI/testing/sysfs-class-power-mp2629
new file mode 100644
index 000000000000..914d67caac0d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-mp2629
@@ -0,0 +1,9 @@
+What: /sys/class/power_supply/mp2629_battery/batt_impedance_compen
+Date: April 2020
+KernelVersion: 5.7
+Description:
+ Represents a battery impedance compensation to accelerate charging.
+
+ Access: Read, Write
+
+ Valid values: Represented in milli-ohms. Valid range is [0, 140].
diff --git a/Documentation/ABI/testing/sysfs-class-power-rt9467 b/Documentation/ABI/testing/sysfs-class-power-rt9467
new file mode 100644
index 000000000000..619b7c45d145
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-rt9467
@@ -0,0 +1,19 @@
+What: /sys/class/power_supply/rt9467-*/sysoff_enable
+Date: Feb 2023
+KernelVersion: 6.3
+Contact: ChiaEn Wu <chiaen_wu@richtek.com>
+Description:
+ This entry allows enabling the sysoff mode of rt9467 charger
+ devices.
+ If enabled and the input is removed, the internal battery FET
+ is turned off to reduce the leakage from the BAT pin. See
+ device datasheet for details. It's commonly used when the
+ product enter shipping stage. After entering shipping mode,
+ only 'VBUS' or 'Power key" pressed can make it leave this mode.
+ 'Disable' also can help to leave it, but it's more like to
+ abort the action before the device really enter shipping mode.
+
+ Access: Read, Write
+ Valid values:
+ - 1: enabled
+ - 0: disabled
diff --git a/Documentation/ABI/testing/sysfs-class-power-rt9471 b/Documentation/ABI/testing/sysfs-class-power-rt9471
new file mode 100644
index 000000000000..0a390ee5ac21
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-rt9471
@@ -0,0 +1,32 @@
+What: /sys/class/power_supply/rt9471-*/sysoff_enable
+Date: Feb 2023
+KernelVersion: 6.3
+Contact: ChiYuan Huang <cy_huang@richtek.com>
+Description:
+ This entry allows enabling the sysoff mode of rt9471 charger devices.
+ If enabled and the input is removed, the internal battery FET is turned
+ off to reduce the leakage from the BAT pin. See device datasheet for details.
+ It's commonly used when the product enter shipping stage. After entering
+ shipping mode, only 'VBUS' or 'Power key" pressed can make it leave this
+ mode. 'Disable' also can help to leave it, but it's more like to abort
+ the action before the device really enter shipping mode.
+
+ Access: Read, Write
+ Valid values:
+ - 1: enabled
+ - 0: disabled
+
+What: /sys/class/power_supply/rt9471-*/port_detect_enable
+Date: Feb 2023
+KernelVersion: 6.3
+Contact: ChiYuan Huang <cy_huang@richtek.com>
+Description:
+ This entry allows enabling the USB BC12 port detect function of rt9471 charger
+ devices. If enabled and VBUS is inserted, device will start to do the BC12
+ port detect and report the usb port type when port detect is done. See
+ datasheet for details. Normally controlled when TypeC/USBPD port integrated.
+
+ Access: Read, Write
+ Valid values:
+ - 1: enabled
+ - 0: disabled
diff --git a/Documentation/ABI/testing/sysfs-class-power-rt9756 b/Documentation/ABI/testing/sysfs-class-power-rt9756
new file mode 100644
index 000000000000..c4d6c2b4715d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-rt9756
@@ -0,0 +1,30 @@
+What: /sys/class/power_supply/rt9756-*/watchdog_timer
+Date: Dec 2025
+KernelVersion: 6.19
+Contact: ChiYuan Huang <cy_huang@richtek.com>
+Description:
+ This entry shows and sets the watchdog timer when rt9756 charger
+ operates in charging mode. When the timer expires, the device
+ will disable the charging. To prevent the timer expires, any
+ host communication can make the timer restarted.
+
+ Access: Read, Write
+
+ Valid values:
+ - 500, 1000, 5000, 30000, 40000, 80000, 128000 or 255000 (milliseconds),
+ - 0: disabled
+
+What: /sys/class/power_supply/rt9756-*/operation_mode
+Date: Dec 2025
+KernelVersion: 6.19
+Contact: ChiYuan Huang <cy_huang@richtek.com>
+Description:
+ This entry shows and set the operation mode when rt9756 charger
+ operates in charging phase. If 'bypass' mode is used, internal
+ path will connect vbus directly to vbat. Else, default 'div2'
+ mode for the switch-cap charging.
+
+ Access: Read, Write
+
+ Valid values:
+ - 'bypass' or 'div2'
diff --git a/Documentation/ABI/testing/sysfs-class-power-surface b/Documentation/ABI/testing/sysfs-class-power-surface
new file mode 100644
index 000000000000..79cde4dcf2f5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-surface
@@ -0,0 +1,15 @@
+What: /sys/class/power_supply/<supply_name>/alarm
+Date: April 2021
+KernelVersion: 5.13
+Contact: Maximilian Luz <luzmaximilian@gmail.com>
+Description:
+ Battery trip point. When the remaining battery capacity crosses this
+ value in either direction, the system will be notified and if
+ necessary woken.
+
+ Set to zero to clear/disable.
+
+ Access: Read, Write
+
+ Valid values: In micro-Wh or micro-Ah, depending on the power unit
+ of the battery
diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030
new file mode 100644
index 000000000000..b52f7023f8ba
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-twl4030
@@ -0,0 +1,33 @@
+What: /sys/class/power_supply/twl4030_usb/mode
+Description:
+ Changing mode for USB port.
+ Writing to this can disable charging.
+
+ Possible values are:
+
+ ============= ===========================================
+ "auto" draw power as appropriate for detected
+ power source and battery status.
+ "off" do not draw any power.
+ "continuous" activate mode described as "linear" in
+ TWL data sheets. This uses whatever
+ current is available and doesn't switch off
+ when voltage drops.
+
+ This is useful for unstable power sources
+ such as bicycle dynamo, but care should
+ be taken that battery is not over-charged.
+ ============= ===========================================
+
+What: /sys/class/power_supply/twl4030_ac/mode
+Description:
+ Changing mode for 'ac' port.
+ Writing to this can disable charging.
+
+ Possible values are:
+
+ ====== ===========================================
+ "auto" draw power as appropriate for detected
+ power source and battery status.
+ "off" do not draw any power.
+ ====== ===========================================
diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco
new file mode 100644
index 000000000000..083c4641b4c4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-power-wilco
@@ -0,0 +1,40 @@
+What: /sys/class/power_supply/wilco-charger/charge_type
+Date: April 2019
+KernelVersion: 5.2
+Description:
+ What charging algorithm to use:
+
+ Standard:
+ Fully charges battery at a standard rate.
+ Adaptive:
+ Battery settings adaptively optimized based on
+ typical battery usage pattern.
+ Fast:
+ Battery charges over a shorter period.
+ Trickle:
+ Extends battery lifespan, intended for users who
+ primarily use their Chromebook while connected to AC.
+ Custom:
+ A low and high threshold percentage is specified.
+ Charging begins when level drops below
+ charge_control_start_threshold, and ceases when
+ level is above charge_control_end_threshold.
+ Long Life:
+ Customized charge rate for last longer battery life.
+ On Wilco device this mode is pre-configured in the factory
+ through EC's private PID. Switching to a different mode will
+ be denied by Wilco EC when Long Life mode is enabled.
+
+What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold
+Date: April 2019
+KernelVersion: 5.2
+Description:
+ Used when charge_type="Custom", as described above. Measured in
+ percentages. The valid range is [50, 95].
+
+What: /sys/class/power_supply/wilco-charger/charge_control_end_threshold
+Date: April 2019
+KernelVersion: 5.2
+Description:
+ Used when charge_type="Custom", as described above. Measured in
+ percentages. The valid range is [55, 100].
diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
index db3b3ff70d84..ca491ec4e693 100644
--- a/Documentation/ABI/testing/sysfs-class-powercap
+++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org
Description:
The powercap/ class sub directory belongs to the power cap
subsystem. Refer to
- Documentation/power/powercap/powercap.txt for details.
+ Documentation/power/powercap/powercap.rst for details.
What: /sys/class/powercap/<control type>
Date: September 2013
@@ -147,6 +147,6 @@ What: /sys/class/powercap/.../<power zone>/enabled
Date: September 2013
KernelVersion: 3.13
Contact: linux-pm@vger.kernel.org
-Description
+Description:
This allows to enable/disable power capping at power zone level.
This applies to current power zone and its children.
diff --git a/Documentation/ABI/testing/sysfs-class-pwm b/Documentation/ABI/testing/sysfs-class-pwm
index c479d77b67c5..0638c94d01ef 100644
--- a/Documentation/ABI/testing/sysfs-class-pwm
+++ b/Documentation/ABI/testing/sysfs-class-pwm
@@ -7,7 +7,7 @@ Description:
Framework and provides a sysfs interface for using PWM
channels.
-What: /sys/class/pwm/pwmchipN/
+What: /sys/class/pwm/pwmchip<N>/
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
@@ -16,14 +16,14 @@ Description:
probed PWM controller/chip where N is the base of the
PWM chip.
-What: /sys/class/pwm/pwmchipN/npwm
+What: /sys/class/pwm/pwmchip<N>/npwm
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
Description:
The number of PWM channels supported by the PWM chip.
-What: /sys/class/pwm/pwmchipN/export
+What: /sys/class/pwm/pwmchip<N>/export
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
@@ -31,14 +31,14 @@ Description:
Exports a PWM channel from the PWM chip for sysfs control.
Value is between 0 and /sys/class/pwm/pwmchipN/npwm - 1.
-What: /sys/class/pwm/pwmchipN/unexport
+What: /sys/class/pwm/pwmchip<N>/unexport
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
Description:
Unexports a PWM channel.
-What: /sys/class/pwm/pwmchipN/pwmX
+What: /sys/class/pwm/pwmchip<N>/pwmX
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
@@ -47,21 +47,21 @@ Description:
each exported PWM channel where X is the exported PWM
channel number.
-What: /sys/class/pwm/pwmchipN/pwmX/period
+What: /sys/class/pwm/pwmchip<N>/pwmX/period
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
Description:
Sets the PWM signal period in nanoseconds.
-What: /sys/class/pwm/pwmchipN/pwmX/duty_cycle
+What: /sys/class/pwm/pwmchip<N>/pwmX/duty_cycle
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
Description:
Sets the PWM signal duty cycle in nanoseconds.
-What: /sys/class/pwm/pwmchipN/pwmX/polarity
+What: /sys/class/pwm/pwmchip<N>/pwmX/polarity
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
@@ -69,7 +69,7 @@ Description:
Sets the output polarity of the PWM signal to "normal" or
"inversed".
-What: /sys/class/pwm/pwmchipN/pwmX/enable
+What: /sys/class/pwm/pwmchip<N>/pwmX/enable
Date: May 2013
KernelVersion: 3.11
Contact: H Hartley Sweeten <hsweeten@visionengravers.com>
@@ -77,3 +77,12 @@ Description:
Enable/disable the PWM signal.
0 is disabled
1 is enabled
+
+What: /sys/class/pwm/pwmchip<N>/pwmX/capture
+Date: June 2016
+KernelVersion: 4.8
+Contact: Lee Jones <lee@kernel.org>
+Description:
+ Capture information about a PWM signal. The output format is a
+ pair unsigned integers (period and duty cycle), separated by a
+ single space.
diff --git a/Documentation/ABI/testing/sysfs-class-rapidio b/Documentation/ABI/testing/sysfs-class-rapidio
new file mode 100644
index 000000000000..81e09145525a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rapidio
@@ -0,0 +1,59 @@
+What: /sys/class/rapidio_port
+Description:
+ On-chip RapidIO controllers and PCIe-to-RapidIO bridges
+ (referenced as "Master Port" or "mport") are presented in sysfs
+ as the special class of devices: "rapidio_port".
+ The /sys/class/rapidio_port subdirectory contains individual
+ subdirectories named as "rapidioN" where N = mport ID registered
+ with RapidIO subsystem.
+
+ NOTE: An mport ID is not a RapidIO destination ID assigned to a
+ given local mport device.
+
+What: /sys/class/rapidio_port/rapidio<N>/sys_size
+Date: Apr, 2014
+KernelVersion: v3.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+ (RO) reports RapidIO common transport system size:
+
+ 0 = small (8-bit destination ID, max. 256 devices),
+
+ 1 = large (16-bit destination ID, max. 65536 devices).
+
+What: /sys/class/rapidio_port/rapidio<N>/port_destid
+Date: Apr, 2014
+KernelVersion: v3.15
+Contact: Matt Porter <mporter@kernel.crashing.org>,
+ Alexandre Bounine <alexandre.bounine@idt.com>
+Description:
+
+(RO) reports RapidIO destination ID assigned to the given
+RapidIO mport device. If value 0xFFFFFFFF is returned this means
+that no valid destination ID have been assigned to the mport
+(yet). Normally, before enumeration/discovery have been executed
+only fabric enumerating mports have a valid destination ID
+assigned to them using "hdid=..." rapidio module parameter.
+
+After enumeration or discovery was performed for a given mport device,
+the corresponding subdirectory will also contain subdirectories for each
+child RapidIO device connected to the mport.
+
+The example below shows mport device subdirectory with several child RapidIO
+devices attached to it::
+
+ [rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
+ total 0
+ drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0001
+ drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0004
+ drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0007
+ drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0002
+ drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0003
+ drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0005
+ lrwxrwxrwx 1 root root 0 Feb 11 15:11 device -> ../../../0000:01:00.0
+ -r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
+ drwxr-xr-x 2 root root 0 Feb 11 15:11 power
+ lrwxrwxrwx 1 root root 0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
+ -r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
+ -rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent
diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc
index b65674da43bb..84e46d70d82b 100644
--- a/Documentation/ABI/testing/sysfs-class-rc
+++ b/Documentation/ABI/testing/sysfs-class-rc
@@ -1,111 +1,137 @@
What: /sys/class/rc/
Date: Apr 2010
KernelVersion: 2.6.35
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
The rc/ class sub-directory belongs to the Remote Controller
core and provides a sysfs interface for configuring infrared
remote controller receivers.
-What: /sys/class/rc/rcN/
+What: /sys/class/rc/rc<N>/
Date: Apr 2010
KernelVersion: 2.6.35
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
A /sys/class/rc/rcN directory is created for each remote
control receiver device where N is the number of the receiver.
-What: /sys/class/rc/rcN/protocols
+What: /sys/class/rc/rc<N>/protocols
Date: Jun 2010
KernelVersion: 2.6.36
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
Reading this file returns a list of available protocols,
- something like:
+ something like::
+
"rc5 [rc6] nec jvc [sony]"
+
Enabled protocols are shown in [] brackets.
+
Writing "+proto" will add a protocol to the list of enabled
protocols.
+
Writing "-proto" will remove a protocol from the list of enabled
protocols.
+
Writing "proto" will enable only "proto".
+
Writing "none" will disable all protocols.
+
Write fails with EINVAL if an invalid protocol combination or
unknown protocol name is used.
-What: /sys/class/rc/rcN/filter
+What: /sys/class/rc/rc<N>/filter
Date: Jan 2014
KernelVersion: 3.15
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
Sets the scancode filter expected value.
+
Use in combination with /sys/class/rc/rcN/filter_mask to set the
expected value of the bits set in the filter mask.
If the hardware supports it then scancodes which do not match
the filter will be ignored. Otherwise the write will fail with
an error.
+
This value may be reset to 0 if the current protocol is altered.
-What: /sys/class/rc/rcN/filter_mask
+What: /sys/class/rc/rc<N>/filter_mask
Date: Jan 2014
KernelVersion: 3.15
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
Sets the scancode filter mask of bits to compare.
Use in combination with /sys/class/rc/rcN/filter to set the bits
of the scancode which should be compared against the expected
value. A value of 0 disables the filter to allow all valid
scancodes to be processed.
+
If the hardware supports it then scancodes which do not match
the filter will be ignored. Otherwise the write will fail with
an error.
+
This value may be reset to 0 if the current protocol is altered.
-What: /sys/class/rc/rcN/wakeup_protocols
-Date: Feb 2014
-KernelVersion: 3.15
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+What: /sys/class/rc/rc<N>/wakeup_protocols
+Date: Feb 2017
+KernelVersion: 4.11
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
Reading this file returns a list of available protocols to use
- for the wakeup filter, something like:
- "rc5 rc6 nec jvc [sony]"
+ for the wakeup filter, something like::
+
+ "rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce"
+
+ Note that protocol variants are listed, so "nec", "sony",
+ "rc-5", "rc-6" have their different bit length encodings
+ listed if available.
+
The enabled wakeup protocol is shown in [] brackets.
- Writing "+proto" will add a protocol to the list of enabled
- wakeup protocols.
- Writing "-proto" will remove a protocol from the list of enabled
- wakeup protocols.
+
+ Only one protocol can be selected at a time.
+
Writing "proto" will use "proto" for wakeup events.
+
Writing "none" will disable wakeup.
+
Write fails with EINVAL if an invalid protocol combination or
unknown protocol name is used, or if wakeup is not supported by
the hardware.
-What: /sys/class/rc/rcN/wakeup_filter
+What: /sys/class/rc/rc<N>/wakeup_filter
Date: Jan 2014
KernelVersion: 3.15
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
Sets the scancode wakeup filter expected value.
+
Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to
set the expected value of the bits set in the wakeup filter mask
to trigger a system wake event.
+
If the hardware supports it and wakeup_filter_mask is not 0 then
scancodes which match the filter will wake the system from e.g.
suspend to RAM or power off.
+
Otherwise the write will fail with an error.
+
This value may be reset to 0 if the wakeup protocol is altered.
-What: /sys/class/rc/rcN/wakeup_filter_mask
+What: /sys/class/rc/rc<N>/wakeup_filter_mask
Date: Jan 2014
KernelVersion: 3.15
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Description:
Sets the scancode wakeup filter mask of bits to compare.
+
Use in combination with /sys/class/rc/rcN/wakeup_filter to set
the bits of the scancode which should be compared against the
expected value to trigger a system wake event.
+
If the hardware supports it and wakeup_filter_mask is not 0 then
scancodes which match the filter will wake the system from e.g.
suspend to RAM or power off.
+
Otherwise the write will fail with an error.
+
This value may be reset to 0 if the wakeup protocol is altered.
diff --git a/Documentation/ABI/testing/sysfs-class-rc-nuvoton b/Documentation/ABI/testing/sysfs-class-rc-nuvoton
new file mode 100644
index 000000000000..f7bad8ecd08f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rc-nuvoton
@@ -0,0 +1,15 @@
+What: /sys/class/rc/rc<N>/wakeup_data
+Date: Mar 2016
+KernelVersion: 4.6
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
+Description:
+ Reading this file returns the stored CIR wakeup sequence.
+ It starts with a pulse, followed by a space, pulse etc.
+ All values are in microseconds.
+ The same format can be used to store a wakeup sequence
+ in the Nuvoton chip by writing to this file.
+
+ Note: Some systems reset the stored wakeup sequence to a
+ factory default on each boot. On such systems store the
+ wakeup sequence in a file and set it on boot using e.g.
+ a udev rule.
diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
index bc578bc60628..475b9a372657 100644
--- a/Documentation/ABI/testing/sysfs-class-regulator
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -35,13 +35,13 @@ Description:
This will be one of the following strings:
- off
- on
- error
- fast
- normal
- idle
- standby
+ - off
+ - on
+ - error
+ - fast
+ - normal
+ - idle
+ - standby
"off" means the regulator is not supplying power to the
system.
@@ -74,9 +74,9 @@ Description:
This will be one of the following strings:
- 'voltage'
- 'current'
- 'unknown'
+ - 'voltage'
+ - 'current'
+ - 'unknown'
'voltage' means the regulator output voltage can be controlled
by software.
@@ -129,11 +129,11 @@ Description:
The opmode value can be one of the following strings:
- 'fast'
- 'normal'
- 'idle'
- 'standby'
- 'unknown'
+ - 'fast'
+ - 'normal'
+ - 'idle'
+ - 'standby'
+ - 'unknown'
The modes are described in include/linux/regulator/consumer.h
@@ -360,9 +360,9 @@ Description:
This will be one of the following strings:
- 'enabled'
- 'disabled'
- 'unknown'
+ - 'enabled'
+ - 'disabled'
+ - 'unknown'
'enabled' means the regulator is in bypass mode.
@@ -370,3 +370,84 @@ Description:
'unknown' means software cannot determine the state, or
the reported state is invalid.
+
+What: /sys/class/regulator/.../under_voltage
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ under_voltage. This indicates if the device reports an
+ under-voltage fault (1) or not (0).
+
+What: /sys/class/regulator/.../over_current
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ over_current. This indicates if the device reports an
+ over-current fault (1) or not (0).
+
+What: /sys/class/regulator/.../regulation_out
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ regulation_out. This indicates if the device reports an
+ out-of-regulation fault (1) or not (0).
+
+What: /sys/class/regulator/.../fail
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ fail. This indicates if the device reports an output failure
+ (1) or not (0).
+
+What: /sys/class/regulator/.../over_temp
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ over_temp. This indicates if the device reports an
+ over-temperature fault (1) or not (0).
+
+What: /sys/class/regulator/.../under_voltage_warn
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ under_voltage_warn. This indicates if the device reports an
+ under-voltage warning (1) or not (0).
+
+What: /sys/class/regulator/.../over_current_warn
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ over_current_warn. This indicates if the device reports an
+ over-current warning (1) or not (0).
+
+What: /sys/class/regulator/.../over_voltage_warn
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ over_voltage_warn. This indicates if the device reports an
+ over-voltage warning (1) or not (0).
+
+What: /sys/class/regulator/.../over_temp_warn
+Date: April 2022
+KernelVersion: 5.18
+Contact: Zev Weiss <zev@bewilderbeest.net>
+Description:
+ Some regulator directories will contain a field called
+ over_temp_warn. This indicates if the device reports an
+ over-temperature warning (1) or not (0).
diff --git a/Documentation/ABI/testing/sysfs-class-remoteproc b/Documentation/ABI/testing/sysfs-class-remoteproc
new file mode 100644
index 000000000000..b2b8e2db2503
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-remoteproc
@@ -0,0 +1,104 @@
+What: /sys/class/remoteproc/.../firmware
+Date: October 2016
+Contact: Matt Redfearn <matt.redfearn@mips.com>
+Description: Remote processor firmware
+
+ Reports the name of the firmware currently loaded to the
+ remote processor.
+
+ To change the running firmware, ensure the remote processor is
+ stopped (using /sys/class/remoteproc/.../state) and write a new filename.
+
+What: /sys/class/remoteproc/.../state
+Date: October 2016
+Contact: Matt Redfearn <matt.redfearn@mips.com>
+Description: Remote processor state
+
+ Reports the state of the remote processor, which will be one of:
+
+ - "offline"
+ - "suspended"
+ - "running"
+ - "crashed"
+ - "invalid"
+
+ "offline" means the remote processor is powered off.
+
+ "suspended" means that the remote processor is suspended and
+ must be woken to receive messages.
+
+ "running" is the normal state of an available remote processor
+
+ "crashed" indicates that a problem/crash has been detected on
+ the remote processor.
+
+ "invalid" is returned if the remote processor is in an
+ unknown state.
+
+ Writing this file controls the state of the remote processor.
+ The following states can be written:
+
+ - "start"
+ - "stop"
+
+ Writing "start" will attempt to start the processor running the
+ firmware indicated by, or written to,
+ /sys/class/remoteproc/.../firmware. The remote processor should
+ transition to "running" state.
+
+ Writing "stop" will attempt to halt the remote processor and
+ return it to the "offline" state.
+
+What: /sys/class/remoteproc/.../name
+Date: August 2019
+KernelVersion: 5.4
+Contact: Suman Anna <s-anna@ti.com>
+Description: Remote processor name
+
+ Reports the name of the remote processor. This can be used by
+ userspace in exactly identifying a remote processor and ease
+ up the usage in modifying the 'firmware' or 'state' files.
+
+What: /sys/class/remoteproc/.../coredump
+Date: July 2020
+Contact: Bjorn Andersson <bjorn.andersson@linaro.org>, Ohad Ben-Cohen <ohad@wizery.com>
+Description: Remote processor coredump configuration
+
+ Reports the coredump configuration of the remote processor,
+ which will be one of:
+
+ "disabled"
+ "enabled"
+ "inline"
+
+ "disabled" means no dump will be collected.
+
+ "enabled" means when the remote processor's coredump is
+ collected it will be copied to a separate buffer and that
+ buffer is exposed to userspace.
+
+ "inline" means when the remote processor's coredump is
+ collected userspace will directly read from the remote
+ processor's device memory. Extra buffer will not be used to
+ copy the dump. Also recovery process will not proceed until
+ all data is read by userspace.
+
+What: /sys/class/remoteproc/.../recovery
+Date: July 2020
+Contact: Bjorn Andersson <bjorn.andersson@linaro.org>, Ohad Ben-Cohen <ohad@wizery.com>
+Description: Remote processor recovery mechanism
+
+ Reports the recovery mechanism of the remote processor,
+ which will be one of:
+
+ "enabled"
+ "disabled"
+
+ "enabled" means, the remote processor will be automatically
+ recovered whenever it crashes. Moreover, if the remote
+ processor crashes while recovery is disabled, it will
+ be automatically recovered too as soon as recovery is enabled.
+
+ "disabled" means, a remote processor will remain in a crashed
+ state if it crashes. This is useful for debugging purposes;
+ without it, debugging a crash is substantially harder.
diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client
new file mode 100644
index 000000000000..0b5997ab3365
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
@@ -0,0 +1,133 @@
+What: /sys/class/rnbd-client
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Provide information about RNBD-client.
+ All sysfs files that are not read-only provide the usage information on read:
+
+ Example::
+
+ # cat /sys/class/rnbd-client/ctl/map_device
+
+ > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
+ > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
+ > [access_mode=<ro|rw|migration>] > map_device
+ >
+ > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
+
+What: /sys/class/rnbd-client/ctl/map_device
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Expected format is the following::
+
+ sessname=<name of the rtrs session>
+ path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
+ device_path=<full path on remote side>
+ [access_mode=<ro|rw|migration>]
+
+ Where:
+
+ sessname:
+ accepts a string not bigger than 256 chars, which identifies
+ a given session on the client and on the server.
+ I.e. "clt_hostname-srv_hostname" could be a natural choice.
+
+ path:
+ describes a connection between the client and the server by
+ specifying destination and, when required, the source address.
+ The addresses are to be provided in the following format::
+
+ ip:<IPv6>
+ ip:<IPv4>
+ gid:<GID>
+
+ for example::
+
+ path=ip:10.0.0.66
+
+ The single addr is treated as the destination.
+ The connection will be established to this server from any client IP address.
+
+ ::
+
+ path=ip:10.0.0.66,ip:10.0.1.66
+
+ First addr is the source address and the second is the destination.
+
+ If multiple "path=" options are specified multiple connection
+ will be established and data will be sent according to
+ the selected multipath policy (see RTRS mp_policy sysfs entry description).
+
+ device_path:
+ Path to the block device on the server side. Path is specified
+ relative to the directory on server side configured in the
+ 'dev_search_path' module parameter of the rnbd_server.
+ The rnbd_server prepends the <device_path> received from client
+ with <dev_search_path> and tries to open the
+ <dev_search_path>/<device_path> block device. On success,
+ a /dev/rnbd<N> device file, a /sys/block/rnbd<N>/
+ directory and an entry in /sys/class/rnbd-client/ctl/devices
+ will be created.
+
+ If 'dev_search_path' contains '%SESSNAME%', then each session can
+ have different devices namespace, e.g. server was configured with
+ the following parameter "dev_search_path=/run/rnbd-devs/%SESSNAME%",
+ client has this string "sessname=blya device_path=sda", then server
+ will try to open: /run/rnbd-devs/blya/sda.
+
+ access_mode:
+ the access_mode parameter specifies if the device is to be
+ mapped as "ro" read-only or "rw" read-write. The server allows
+ a device to be exported in rw mode only once. The "migration"
+ access mode has to be specified if a second mapping in read-write
+ mode is desired.
+
+ By default "rw" is used.
+
+ nr_poll_queues
+ specifies the number of poll-mode queues. If the IO has HIPRI flag,
+ the block-layer will send the IO via the poll-mode queue.
+ For fast network and device the polling is faster than interrupt-base
+ IO handling because it saves time for context switching, switching to
+ another process, handling the interrupt and switching back to the
+ issuing process.
+
+ Set -1 if you want to set it as the number of CPUs
+ By default rnbd client creates only irq-mode queues.
+
+ NOTICE: MUST make a unique session for a device using the poll-mode queues.
+
+ Exit Codes:
+
+ If the device is already mapped it will fail with EEXIST. If the input
+ has an invalid format it will return EINVAL. If the device path cannot
+ be found on the server, it will fail with ENOENT.
+
+ Finding device file after mapping
+ ---------------------------------
+
+ After mapping, the device file can be found by:
+ o The symlink /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>
+ points to /sys/block/<dev-name>. The last part of the symlink destination
+ is the same as the device name. By extracting the last part of the
+ path the path to the device /dev/<dev-name> can be build.
+
+ * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>/dev)
+
+ How to find the <device_id> of the device is described on the next
+ section.
+
+What: /sys/class/rnbd-client/ctl/devices/
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: For each device mapped on the client a new symbolic link is created as
+ /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>, which points
+ to the block device created by rnbd (/sys/block/rnbd<N>/).
+ The <device_id> of each device is created as follows:
+
+ - If the 'device_path' provided during mapping contains slashes ("/"),
+ they are replaced by exclamation mark ("!") and used as as the
+ <device_id>. Otherwise, the <device_id> will be the same as the
+ "device_path" provided.
diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-server b/Documentation/ABI/testing/sysfs-class-rnbd-server
new file mode 100644
index 000000000000..6c5996cd7cfb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rnbd-server
@@ -0,0 +1,58 @@
+What: /sys/class/rnbd-server
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: provide information about RNBD-server.
+
+What: /sys/class/rnbd-server/ctl/
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: When a client maps a device, a directory entry with the name of the
+ block device is created under /sys/class/rnbd-server/ctl/devices/.
+
+What: /sys/class/rnbd-server/ctl/devices/<device_name>/block_dev
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Is a symlink to the sysfs entry of the exported device.
+
+ Example:
+ block_dev -> ../../../../class/block/ram0
+
+What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: For each client a particular device is exported to, following directory will be
+ created:
+
+ /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/
+
+ When the device is unmapped by that client, the directory will be removed.
+
+What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/read_only
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains '1' if device is mapped read-only, otherwise '0'.
+
+What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/mapping_path
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains the relative device path provided by the user during mapping.
+
+What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/access_mode
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains the device access mode: ro, rw or migration.
+
+What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/force_close
+Date: Nov 2020
+KernelVersion: 5.10
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Write "1" to the file to close the device on server side. Please
+ note that the client side device will not be closed, read or
+ write to the device will get -ENOTCONN.
diff --git a/Documentation/ABI/testing/sysfs-class-rtc b/Documentation/ABI/testing/sysfs-class-rtc
new file mode 100644
index 000000000000..95984289a4ee
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rtc
@@ -0,0 +1,91 @@
+What: /sys/class/rtc/
+Date: March 2006
+KernelVersion: 2.6.17
+Contact: linux-rtc@vger.kernel.org
+Description:
+ The rtc/ class subdirectory belongs to the RTC subsystem.
+
+What: /sys/class/rtc/rtcX/
+Date: March 2006
+KernelVersion: 2.6.17
+Contact: linux-rtc@vger.kernel.org
+Description:
+ The /sys/class/rtc/rtc{0,1,2,3,...} directories correspond
+ to each RTC device.
+
+What: /sys/class/rtc/rtcX/date
+Date: March 2006
+KernelVersion: 2.6.17
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RO) RTC-provided date in YYYY-MM-DD format
+
+What: /sys/class/rtc/rtcX/hctosys
+Date: September 2009
+KernelVersion: 2.6.32
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RO) 1 if the RTC provided the system time at boot via the
+ CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
+
+What: /sys/class/rtc/rtcX/max_user_freq
+Date: October 2007
+KernelVersion: 2.6.24
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RW) The maximum interrupt rate an unprivileged user may request
+ from this RTC.
+
+What: /sys/class/rtc/rtcX/name
+Date: March 2006
+KernelVersion: 2.6.17
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RO) The name of the RTC corresponding to this sysfs directory
+
+What: /sys/class/rtc/rtcX/range
+Date: January 2018
+KernelVersion: 4.16
+Contact: linux-rtc@vger.kernel.org
+Description:
+ Valid time range for the RTC, as seconds from epoch, formatted
+ as [min, max]
+
+What: /sys/class/rtc/rtcX/since_epoch
+Date: March 2006
+KernelVersion: 2.6.17
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RO) RTC-provided time as the number of seconds since the epoch
+
+What: /sys/class/rtc/rtcX/time
+Date: March 2006
+KernelVersion: 2.6.17
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RO) RTC-provided time in 24-hour notation (hh:mm:ss)
+
+What: /sys/class/rtc/rtcX/offset
+Date: February 2016
+KernelVersion: 4.6
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RW) The amount which the rtc clock has been adjusted in
+ firmware. Visible only if the driver supports clock offset
+ adjustment. The unit is parts per billion, i.e. The number of
+ clock ticks which are added to or removed from the rtc's base
+ clock per billion ticks. A positive value makes a day pass more
+ slowly, longer, and a negative value makes a day pass more
+ quickly.
+
+What: /sys/class/rtc/rtcX/wakealarm
+Date: February 2007
+KernelVersion: 2.6.20
+Contact: linux-rtc@vger.kernel.org
+Description:
+ (RW) The time at which the clock will generate a system wakeup
+ event. This is a one shot wakeup event, so must be reset after
+ wake if a daily wakeup is required. Format is seconds since the
+ epoch by default, or if there's a leading +, seconds in the
+ future, or if there is a leading +=, seconds ahead of the
+ current alarm.
diff --git a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
index 4cf1e72222d9..ee8ed6494a01 100644
--- a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
+++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
@@ -1,11 +1,13 @@
-What: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock
+What: /sys/class/rtc/rtc0/device/rtc_calibration
Date: Oct 2011
KernelVersion: 3.0
Contact: Mark Godfrey <mark.godfrey@stericsson.com>
-Description: The rtc_calibration attribute allows the userspace to
+Description: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock
+ The rtc_calibration attribute allows the userspace to
calibrate the AB8500.s 32KHz Real Time Clock.
Every 60 seconds the AB8500 will correct the RTC's value
by adding to it the value of this attribute.
+
The range of the attribute is -127 to +127 in units of
30.5 micro-seconds (half-parts-per-million of the 32KHz clock)
Users: The /vendor/st-ericsson/base_utilities/core/rtc_calibration
diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client
new file mode 100644
index 000000000000..fecc59d1b96f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
@@ -0,0 +1,146 @@
+What: /sys/class/rtrs-client
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: When a user of RTRS API creates a new session, a directory entry with
+ the name of that session is created under /sys/class/rtrs-client/<session-name>/
+
+What: /sys/class/rtrs-client/<session-name>/add_path
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RW, adds a new path (connection) to an existing session. Expected format is the
+ following::
+
+ <[source addr,]destination addr>
+ *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
+
+What: /sys/class/rtrs-client/<session-name>/max_reconnect_attempts
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Maximum number reconnect attempts the client should make before giving up
+ after connection breaks unexpectedly.
+
+What: /sys/class/rtrs-client/<session-name>/mp_policy
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Multipath policy specifies which path should be selected on each IO:
+
+ round-robin (0):
+ select path in per CPU round-robin manner.
+
+ min-inflight (1):
+ select path with minimum inflights.
+
+ min-latency (2):
+ select path with minimum latency.
+
+What: /sys/class/rtrs-client/<session-name>/paths/
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Each path belonging to a given session is listed here by its source and
+ destination address. When a new path is added to a session by writing to
+ the "add_path" entry, a directory <src@dst> is created.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/state
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains "connected" if the session is connected to the peer and fully
+ functional. Otherwise the file contains "disconnected"
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/reconnect
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Write "1" to the file in order to reconnect the path.
+ Operation is blocking and returns 0 if reconnect was successful.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/disconnect
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Write "1" to the file in order to disconnect the path.
+ Operation blocks until RTRS path is disconnected.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/remove_path
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Write "1" to the file in order to disconnected and remove the path
+ from the session. Operation blocks until the path is disconnected
+ and removed from the session.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/hca_name
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the name of HCA the connection established on.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/hca_port
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the port number of active port traffic is going through.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/src_addr
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the source address of the path
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/dst_addr
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the destination address of the path
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/cur_latency
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the latency time calculated by the heart-beat messages.
+ Whenever the client sends heart-beat message, it checks the time gap
+ between sending the heart-beat message and receiving the ACK.
+ This value can be changed regularly.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reset_all
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RW, Read will return usage help, write 0 will clear all the statistics.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/cpu_migration
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's
+ not the case, the processing of an I/O response could be processed on a
+ different CPU than where it was originally submitted. This file shows
+ how many interrupts where generated on a non expected CPU.
+
+ "from:"
+ is the CPU on which the IRQ was expected, but not generated.
+ "to:"
+ is the CPU on which the IRQ was generated, but not expected.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains 2 unsigned int values, the first one records number of successful
+ reconnects in the path lifetime, the second one records number of failed
+ reconnects in the path lifetime.
+
+What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/rdma
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains statistics regarding rdma operations and inflight operations.
+ The output consists of 6 values::
+
+ <read-count> <read-total-size> <write-count> \
+ <write-total-size> <inflights> <failovered>
diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-server b/Documentation/ABI/testing/sysfs-class-rtrs-server
new file mode 100644
index 000000000000..b08601d80409
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-rtrs-server
@@ -0,0 +1,53 @@
+What: /sys/class/rtrs-server
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: When a user of RTRS API creates a new session on a client side, a
+ directory entry with the name of that session is created in here.
+
+What: /sys/class/rtrs-server/<session-name>/paths/
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: When new path is created by writing to "add_path" entry on client side,
+ a directory entry named as <source address>@<destination address> is created
+ on server.
+
+What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/disconnect
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: When "1" is written to the file, the RTRS session is being disconnected.
+ Operations is non-blocking and returns control immediately to the caller.
+
+What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/hca_name
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the name of HCA the connection established on.
+
+What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/hca_port
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the port number of active port traffic is going through.
+
+What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/src_addr
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the source address of the path
+
+What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/dst_addr
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: RO, Contains the destination address of the path
+
+What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/stats/rdma
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
+Description: Contains statistics regarding rdma operations and inflight operations.
+ The output consists of 5 values:
+ <read-count> <read-total-size> <write-count> <write-total-size> <inflights>
diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host
index 0eb255e7db12..7c98d8f43c45 100644
--- a/Documentation/ABI/testing/sysfs-class-scsi_host
+++ b/Documentation/ABI/testing/sysfs-class-scsi_host
@@ -27,3 +27,93 @@ Description: This file contains the current status of the "SSD Smart Path"
the direct i/o path to physical devices. This setting is
controller wide, affecting all configured logical drives on the
controller. This file is readable and writable.
+
+What: /sys/class/scsi_host/hostX/link_power_management_policy
+Date: Oct, 2007
+KernelVersion: v2.6.24
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RW) This parameter allows the user to read and set the link
+ (interface) power management.
+
+ There are four possible options:
+
+ min_power: Tell the controller to try to make the link use the
+ least possible power when possible. This may sacrifice some
+ performance due to increased latency when coming out of lower
+ power states.
+
+ max_performance: Generally, this means no power management.
+ Tell the controller to have performance be a priority over power
+ management.
+
+ medium_power: Tell the controller to enter a lower power state
+ when possible, but do not enter the lowest power state, thus
+ improving latency over min_power setting.
+
+ med_power_with_dipm: Identical to the existing medium_power
+ setting except that it enables dipm (device initiated power
+ management) on top, which makes it match the Windows IRST (Intel
+ Rapid Storage Technology) driver settings. This setting is also
+ close to min_power, except that:
+
+ a) It does not use host-initiated slumber mode, but it does
+ allow device-initiated slumber
+ b) It does not enable low power device sleep mode (DevSlp).
+
+What: /sys/class/scsi_host/hostX/em_message
+What: /sys/class/scsi_host/hostX/em_message_type
+Date: Jun, 2008
+KernelVersion: v2.6.27
+Contact: linux-ide@vger.kernel.org
+Description:
+ em_message: (RW) Enclosure management support. For the LED
+ protocol, writes and reads correspond to the LED message format
+ as defined in the AHCI spec.
+
+ The user must turn sw_activity (under `/sys/block/*/device/`)
+ OFF it they wish to control the activity LED via the em_message
+ file.
+
+ em_message_type: (RO) Displays the current enclosure management
+ protocol that is being used by the driver (for eg. LED, SAF-TE,
+ SES-2, SGPIO etc).
+
+What: /sys/class/scsi_host/hostX/ahci_port_cmd
+What: /sys/class/scsi_host/hostX/ahci_host_caps
+What: /sys/class/scsi_host/hostX/ahci_host_cap2
+Date: Mar, 2010
+KernelVersion: v2.6.35
+Contact: linux-ide@vger.kernel.org
+Description:
+ [to be documented]
+
+What: /sys/class/scsi_host/hostX/ahci_host_version
+Date: Mar, 2010
+KernelVersion: v2.6.35
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RO) Display the version of the AHCI spec implemented by the
+ host.
+
+What: /sys/class/scsi_host/hostX/em_buffer
+Date: Apr, 2010
+KernelVersion: v2.6.35
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RW) Allows access to AHCI EM (enclosure management) buffer
+ directly if the host supports EM.
+
+ For eg. the AHCI driver supports SGPIO EM messages but the
+ SATA/AHCI specs do not define the SGPIO message format of the EM
+ buffer. Different hardware(HW) vendors may have different
+ definitions. With the em_buffer attribute, this issue can be
+ solved by allowing HW vendors to provide userland drivers and
+ tools for their SGPIO initiators.
+
+What: /sys/class/scsi_host/hostX/em_message_supported
+Date: Oct, 2009
+KernelVersion: v2.6.39
+Contact: linux-ide@vger.kernel.org
+Description:
+ (RO) Displays supported enclosure management message types.
diff --git a/Documentation/ABI/testing/sysfs-class-scsi_tape b/Documentation/ABI/testing/sysfs-class-scsi_tape
new file mode 100644
index 000000000000..9be398b87ee9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-scsi_tape
@@ -0,0 +1,109 @@
+What: /sys/class/scsi_tape/*/stats/in_flight
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Show the number of I/Os currently in-flight between the st
+ module and the SCSI mid-layer.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/io_ns
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total amount of time spent waiting for all I/O
+ to and from the tape drive to complete. This includes all
+ reads, writes, and other SCSI commands issued to the tape
+ drive. An example of other SCSI commands would be tape
+ movement such as a rewind when a rewind tape device is
+ closed. This item is measured in nanoseconds.
+
+ To determine the amount of time spent waiting for other I/O
+ to complete subtract read_ns and write_ns from this value.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/other_cnt
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ The number of I/O requests issued to the tape drive other
+ than SCSI read/write requests.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/read_byte_cnt
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total number of bytes requested from the tape drive.
+ This value is presented in bytes because tape drives support
+ variable length block sizes.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/read_cnt
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total number of read requests issued to the tape
+ drive.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/read_ns
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total amount of time in nanoseconds waiting for
+ read I/O requests to complete.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/write_byte_cnt
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total number of bytes written to the tape drive.
+ This value is presented in bytes because tape drives support
+ variable length block sizes.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/write_cnt
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total number of write requests issued to the tape
+ drive.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/write_ms
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the total amount of time in nanoseconds waiting for
+ write I/O requests to complete.
+Users:
+
+
+What: /sys/class/scsi_tape/*/stats/resid_cnt
+Date: Apr 2015
+KernelVersion: 4.2
+Contact: Shane Seymour <shane.seymour@hp.com>
+Description:
+ Shows the number of times we found that a residual >0
+ was found when the SCSI midlayer indicated that there was
+ an error. For reads this may be a case of someone issuing
+ reads greater than the block size.
+Users:
diff --git a/Documentation/ABI/testing/sysfs-class-spi-eeprom b/Documentation/ABI/testing/sysfs-class-spi-eeprom
new file mode 100644
index 000000000000..1ff757982079
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-spi-eeprom
@@ -0,0 +1,19 @@
+What: /sys/class/spi_master/spi<bus>/spi<bus>.<dev>/fram
+Date: June 2021
+KernelVersion: 5.14
+Contact: Jiri Prchal <jiri.prchal@aksignal.cz>
+Description:
+ Contains the FRAM binary data. Same as EEPROM, just another file
+ name to indicate that it employs ferroelectric process.
+ It performs write operations at bus speed - no write delays.
+
+What: /sys/class/spi_master/spi<bus>/spi<bus>.<dev>/sernum
+Date: May 2021
+KernelVersion: 5.14
+Contact: Jiri Prchal <jiri.prchal@aksignal.cz>
+Description:
+ Contains the serial number of the Cypress FRAM (FM25VN) if it is
+ present. It will be displayed as a 8 byte hex string, as read
+ from the device.
+
+ This is a read-only attribute.
diff --git a/Documentation/ABI/testing/sysfs-class-stm b/Documentation/ABI/testing/sysfs-class-stm
new file mode 100644
index 000000000000..77ed3da0f68e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-stm
@@ -0,0 +1,24 @@
+What: /sys/class/stm/<stm>/masters
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description:
+ Shows first and last available to software master numbers on
+ this STM device.
+
+What: /sys/class/stm/<stm>/channels
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description:
+ Shows the number of channels per master on this STM device.
+
+What: /sys/class/stm/<stm>/hw_override
+Date: March 2016
+KernelVersion: 4.7
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description:
+ Reads as 0 if master numbers in the STP stream produced by
+ this stm device will match the master numbers assigned by
+ the software or 1 if the stm hardware overrides software
+ assigned masters.
diff --git a/Documentation/ABI/testing/sysfs-class-stm_source b/Documentation/ABI/testing/sysfs-class-stm_source
new file mode 100644
index 000000000000..57b8dd39bbf7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-stm_source
@@ -0,0 +1,11 @@
+What: /sys/class/stm_source/<stm_source>/stm_source_link
+Date: June 2015
+KernelVersion: 4.3
+Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com>
+Description:
+ stm_source device linkage to stm device, where its tracing data
+ is directed. Reads return an existing connection or "<none>" if
+ this stm_source is not connected to any stm device yet.
+ Write an existing (registered) stm device's name here to
+ connect that device. If a device is already connected to this
+ stm_source, it will first be disconnected.
diff --git a/Documentation/ABI/testing/sysfs-class-switchtec b/Documentation/ABI/testing/sysfs-class-switchtec
new file mode 100644
index 000000000000..76c7a661a595
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-switchtec
@@ -0,0 +1,96 @@
+switchtec - Microsemi Switchtec PCI Switch Management Endpoint
+
+For details on this subsystem look at Documentation/driver-api/switchtec.rst.
+
+What: /sys/class/switchtec
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: The switchtec class subsystem folder.
+ Each registered switchtec driver is represented by a switchtecX
+ subfolder (X being an integer >= 0).
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/component_id
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Component identifier as stored in the hardware (eg. PM8543)
+ (read only)
+Values: arbitrary string.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/component_revision
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Component revision stored in the hardware (read only)
+Values: integer.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/component_vendor
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Component vendor as stored in the hardware (eg. MICROSEM)
+ (read only)
+Values: arbitrary string.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/device_version
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Device version as stored in the hardware (read only)
+Values: integer.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/fw_version
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Currently running firmware version (read only)
+Values: integer (in hexadecimal).
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/partition
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Partition number for this device in the switch (read only)
+Values: integer.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/partition_count
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Total number of partitions in the switch (read only)
+Values: integer.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/product_id
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Product identifier as stored in the hardware (eg. PSX 48XG3)
+ (read only)
+Values: arbitrary string.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/product_revision
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Product revision stored in the hardware (eg. RevB)
+ (read only)
+Values: arbitrary string.
+
+
+What: /sys/class/switchtec/switchtec[0-9]+/product_vendor
+Date: 05-Jan-2017
+KernelVersion: v4.11
+Contact: Logan Gunthorpe <logang@deltatee.com>
+Description: Product vendor as stored in the hardware (eg. MICROSEM)
+ (read only)
+Values: arbitrary string.
diff --git a/Documentation/ABI/testing/sysfs-class-tee b/Documentation/ABI/testing/sysfs-class-tee
new file mode 100644
index 000000000000..c9144d16003e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-tee
@@ -0,0 +1,15 @@
+What: /sys/class/tee/tee{,priv}X/rpmb_routing_model
+Date: May 2024
+KernelVersion: 6.10
+Contact: op-tee@lists.trustedfirmware.org
+Description:
+ RPMB frames can be routed to the RPMB device via the
+ user-space daemon tee-supplicant or the RPMB subsystem
+ in the kernel. The value "user" means that the driver
+ will route the RPMB frames via user space. Conversely,
+ "kernel" means that the frames are routed via the RPMB
+ subsystem without assistance from tee-supplicant. It
+ should be assumed that RPMB frames are routed via user
+ space if the variable is absent. The primary purpose
+ of this variable is to let systemd know whether
+ tee-supplicant is needed in the early boot with initramfs.
diff --git a/Documentation/ABI/testing/sysfs-class-thermal b/Documentation/ABI/testing/sysfs-class-thermal
new file mode 100644
index 000000000000..968d89e15e8e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-thermal
@@ -0,0 +1,259 @@
+What: /sys/class/thermal/thermal_zoneX/type
+Description:
+ Strings which represent the thermal zone type.
+ This is given by thermal zone driver as part of registration.
+ E.g: "acpitz" indicates it's an ACPI thermal device.
+ In order to keep it consistent with hwmon sys attribute; this
+ should be a short, lowercase string, not containing spaces nor
+ dashes.
+
+ RO, Required
+
+What: /sys/class/thermal/thermal_zoneX/temp
+Description:
+ Current temperature as reported by thermal zone (sensor).
+
+ Unit: millidegree Celsius
+
+ RO, Required
+
+What: /sys/class/thermal/thermal_zoneX/mode
+Description:
+ One of the predefined values in [enabled, disabled].
+ This file gives information about the algorithm that is
+ currently managing the thermal zone. It can be either default
+ kernel based algorithm or user space application.
+
+ enabled
+ enable Kernel Thermal management.
+ disabled
+ Preventing kernel thermal zone driver actions upon
+ trip points so that user application can take full
+ charge of the thermal management.
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/policy
+Description:
+ One of the various thermal governors used for a particular zone.
+
+ RW, Required
+
+What: /sys/class/thermal/thermal_zoneX/available_policies
+Description:
+ Available thermal governors which can be used for a
+ particular zone.
+
+ RO, Required
+
+What: /sys/class/thermal/thermal_zoneX/trip_point_Y_temp
+Description:
+ The temperature above which trip point will be fired.
+
+ Unit: millidegree Celsius
+
+ RO, Optional
+
+What: /sys/class/thermal/thermal_zoneX/trip_point_Y_type
+Description:
+ Strings which indicate the type of the trip point.
+
+ E.g. it can be one of critical, hot, passive, `active[0-*]`
+ for ACPI thermal zone.
+
+ RO, Optional
+
+What: /sys/class/thermal/thermal_zoneX/trip_point_Y_hyst
+Description:
+ The hysteresis value for a trip point, represented as an
+ integer.
+
+ Unit: Celsius
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/cdevY
+Description:
+ Sysfs link to the thermal cooling device node where the sys I/F
+ for cooling device throttling control represents.
+
+ RO, Optional
+
+What: /sys/class/thermal/thermal_zoneX/cdevY_trip_point
+Description:
+ The trip point in this thermal zone which `cdev[0-*]` is
+ associated with; -1 means the cooling device is not
+ associated with any trip point.
+
+ RO, Optional
+
+What: /sys/class/thermal/thermal_zoneX/cdevY_weight
+Description:
+ The influence of `cdev[0-*]` in this thermal zone. This value
+ is relative to the rest of cooling devices in the thermal
+ zone. For example, if a cooling device has a weight double
+ than that of other, it's twice as effective in cooling the
+ thermal zone.
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/emul_temp
+Description:
+ Interface to set the emulated temperature method in thermal zone
+ (sensor). After setting this temperature, the thermal zone may
+ pass this temperature to platform emulation function if
+ registered or cache it locally. This is useful in debugging
+ different temperature threshold and its associated cooling
+ action. This is write only node and writing 0 on this node
+ should disable emulation.
+
+ Unit: millidegree Celsius
+
+ WO, Optional
+
+ WARNING:
+ Be careful while enabling this option on production systems,
+ because userland can easily disable the thermal policy by simply
+ flooding this sysfs node with low temperature values.
+
+
+What: /sys/class/thermal/thermal_zoneX/k_d
+Description:
+ The derivative term of the power allocator governor's PID
+ controller. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/k_i
+Description:
+ The integral term of the power allocator governor's PID
+ controller. This term allows the PID controller to compensate
+ for long term drift. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/k_po
+Description:
+ The proportional term of the power allocator governor's PID
+ controller during temperature overshoot. Temperature overshoot
+ is when the current temperature is above the "desired
+ temperature" trip point. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/k_pu
+Description:
+ The proportional term of the power allocator governor's PID
+ controller during temperature undershoot. Temperature undershoot
+ is when the current temperature is below the "desired
+ temperature" trip point. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/integral_cutoff
+Description:
+ Temperature offset from the desired temperature trip point
+ above which the integral term of the power allocator
+ governor's PID controller starts accumulating errors. For
+ example, if integral_cutoff is 0, then the integral term only
+ accumulates error when temperature is above the desired
+ temperature trip point. For more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ Unit: millidegree Celsius
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/slope
+Description:
+ The slope constant used in a linear extrapolation model
+ to determine a hotspot temperature based off the sensor's
+ raw readings. It is up to the device driver to determine
+ the usage of these values.
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/offset
+Description:
+ The offset constant used in a linear extrapolation model
+ to determine a hotspot temperature based off the sensor's
+ raw readings. It is up to the device driver to determine
+ the usage of these values.
+
+ RW, Optional
+
+What: /sys/class/thermal/thermal_zoneX/sustainable_power
+Description:
+ An estimate of the sustained power that can be dissipated by
+ the thermal zone. Used by the power allocator governor. For
+ more information see
+ Documentation/driver-api/thermal/power_allocator.rst
+
+ Unit: milliwatts
+
+ RW, Optional
+
+What: /sys/class/thermal/cooling_deviceX/type
+Description:
+ String which represents the type of device, e.g:
+
+ - for generic ACPI: should be "Fan", "Processor" or "LCD"
+ - for memory controller device on intel_menlow platform:
+ should be "Memory controller".
+
+ RO, Required
+
+What: /sys/class/thermal/cooling_deviceX/max_state
+Description:
+ The maximum permissible cooling state of this cooling device.
+
+ RO, Required
+
+What: /sys/class/thermal/cooling_deviceX/cur_state
+Description:
+ The current cooling state of this cooling device.
+ The value can any integer numbers between 0 and max_state:
+
+ - cur_state == 0 means no cooling
+ - cur_state == max_state means the maximum cooling.
+
+ RW, Required
+
+What: /sys/class/thermal/cooling_deviceX/stats/reset
+Description:
+ Writing any value resets the cooling device's statistics.
+
+ WO, Required
+
+What: /sys/class/thermal/cooling_deviceX/stats/time_in_state_ms:
+Description:
+ The amount of time spent by the cooling device in various
+ cooling states. The output will have "<state> <time>" pair
+ in each line, which will mean this cooling device spent <time>
+ msec of time at <state>.
+
+ Output will have one line for each of the supported states.
+
+ RO, Required
+
+What: /sys/class/thermal/cooling_deviceX/stats/total_trans
+Description:
+ A single positive value showing the total number of times
+ the state of a cooling device is changed.
+
+ RO, Required
+
+What: /sys/class/thermal/cooling_deviceX/stats/trans_table
+Description:
+ This gives fine grained information about all the cooling state
+ transitions. The cat output here is a two dimensional matrix,
+ where an entry <i,j> (row i, column j) represents the number
+ of transitions from State_i to State_j. If the transition
+ table is bigger than PAGE_SIZE, reading this will return
+ an -EFBIG error.
+
+ RO, Required
diff --git a/Documentation/ABI/testing/sysfs-class-tsm b/Documentation/ABI/testing/sysfs-class-tsm
new file mode 100644
index 000000000000..6fc1a5ac6da1
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-tsm
@@ -0,0 +1,19 @@
+What: /sys/class/tsm/tsmN
+Contact: linux-coco@lists.linux.dev
+Description:
+ "tsmN" is a device that represents the generic attributes of a
+ platform TEE Security Manager. It is typically a child of a
+ platform enumerated TSM device. /sys/class/tsm/tsmN/uevent
+ signals when the PCI layer is able to support establishment of
+ link encryption and other device-security features coordinated
+ through a platform tsm.
+
+What: /sys/class/tsm/tsmN/streamH.R.E
+Contact: linux-pci@vger.kernel.org
+Description:
+ (RO) When a host bridge has established a secure connection via
+ the platform TSM, symlink appears. The primary function of this
+ is have a system global review of TSM resource consumption
+ across host bridges. The link points to the endpoint PCI device
+ and matches the same link published by the host bridge. See
+ Documentation/ABI/testing/sysfs-devices-pci-host-bridge.
diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec
new file mode 100644
index 000000000000..38e101c17a00
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-typec
@@ -0,0 +1,375 @@
+USB Type-C port devices (eg. /sys/class/typec/port0/)
+
+What: /sys/class/typec/<port>/data_role
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The supported USB data roles. This attribute can be used for
+ requesting data role swapping on the port. Swapping is supported
+ as synchronous operation, so write(2) to the attribute will not
+ return until the operation has finished. The attribute is
+ notified about role changes so that poll(2) on the attribute
+ wakes up. Change on the role will also generate uevent
+ KOBJ_CHANGE on the port. The current role is show in brackets,
+ for example "[host] device" when DRP port is in host mode.
+
+ Valid values: host, device
+
+What: /sys/class/typec/<port>/power_role
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The supported power roles. This attribute can be used to request
+ power role swap on the port. Swapping is supported as
+ synchronous operation, so write(2) to the attribute will not
+ return until the operation has finished. The attribute is
+ notified about role changes so that poll(2) on the attribute
+ wakes up. Change on the role will also generate uevent
+ KOBJ_CHANGE. The current role is show in brackets, for example
+ "[source] sink" when in source mode.
+
+ Valid values: source, sink
+
+What: /sys/class/typec/<port>/port_type
+Date: May 2017
+Contact: Badhri Jagan Sridharan <Badhri@google.com>
+Description:
+ Indicates the type of the port. This attribute can be used for
+ requesting a change in the port type. Port type change is
+ supported as a synchronous operation, so write(2) to the
+ attribute will not return until the operation has finished.
+
+ Valid values:
+
+ ====== ==============================================
+ source (The port will behave as source only DFP port)
+ sink (The port will behave as sink only UFP port)
+ dual (The port will behave as dual-role-data and
+ dual-role-power port)
+ ====== ==============================================
+
+What: /sys/class/typec/<port>/vconn_source
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows is the port VCONN Source. This attribute can be used to
+ request VCONN swap to change the VCONN Source during connection
+ when both the port and the partner support USB Power Delivery.
+ Swapping is supported as synchronous operation, so write(2) to
+ the attribute will not return until the operation has finished.
+ The attribute is notified about VCONN source changes so that
+ poll(2) on the attribute wakes up. Change on VCONN source also
+ generates uevent KOBJ_CHANGE.
+
+ Valid values:
+
+ - "no" when the port is not the VCONN Source
+ - "yes" when the port is the VCONN Source
+
+What: /sys/class/typec/<port>/power_operation_mode
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows the current power operational mode the port is in. The
+ power operation mode means current level for VBUS. In case USB
+ Power Delivery communication is used for negotiating the levels,
+ power operation mode should show "usb_power_delivery".
+
+ Valid values:
+
+ - default
+ - 1.5A
+ - 3.0A
+ - usb_power_delivery
+
+What: /sys/class/typec/<port>/preferred_role
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The user space can notify the driver about the preferred role.
+ It should be handled as enabling of Try.SRC or Try.SNK, as
+ defined in USB Type-C specification, in the port drivers. By
+ default the preferred role should come from the platform.
+
+ Valid values: source, sink, none (to remove preference)
+
+What: /sys/class/typec/<port>/supported_accessory_modes
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Space separated list of accessory modes, defined in the USB
+ Type-C specification, the port supports.
+
+What: /sys/class/typec/<port>/usb_power_delivery_revision
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Revision number of the supported USB Power Delivery
+ specification, or 0.0 when USB Power Delivery is not supported.
+
+ Example values:
+ - "2.0": USB Power Delivery Release 2.0
+ - "3.0": USB Power Delivery Release 3.0
+ - "3.1": USB Power Delivery Release 3.1
+
+What: /sys/class/typec/<port>-{partner|cable}/usb_power_delivery_revision
+Date: January 2021
+Contact: Benson Leung <bleung@chromium.org>
+Description:
+ Revision number of the supported USB Power Delivery
+ specification of the port partner or cable, or 0.0 when USB
+ Power Delivery is not supported.
+
+ Example values:
+ - "2.0": USB Power Delivery Release 2.0
+ - "3.0": USB Power Delivery Release 3.0
+ - "3.1": USB Power Delivery Release 3.1
+
+What: /sys/class/typec/<port>/usb_typec_revision
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Revision number of the supported USB Type-C specification.
+
+What: /sys/class/typec/<port>/orientation
+Date: February 2020
+Contact: Badhri Jagan Sridharan <badhri@google.com>
+Description:
+ Indicates the active orientation of the Type-C connector.
+ Valid values:
+ - "normal": CC1 orientation
+ - "reverse": CC2 orientation
+ - "unknown": Orientation cannot be determined.
+
+What: /sys/class/typec/<port>/select_usb_power_delivery
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Lists the USB Power Delivery Capabilities that the port can
+ advertise to the partner. The currently used capabilities are in
+ brackets. Selection happens by writing to the file.
+
+What: /sys/class/typec/<port>/usb_capability
+Date: November 2024
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description: Lists the supported USB Modes. The default USB mode that is used
+ next time with the Enter_USB Message is in brackets. The default
+ mode can be changed by writing to the file when supported by the
+ driver.
+
+ Valid values:
+ - usb2 (USB 2.0)
+ - usb3 (USB 3.2)
+ - usb4 (USB4)
+
+USB Type-C partner devices (eg. /sys/class/typec/port0-partner/)
+
+What: /sys/class/typec/<port>-partner/accessory_mode
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows the Accessory Mode name when the partner is an Accessory.
+ The Accessory Modes are defined in USB Type-C Specification.
+
+What: /sys/class/typec/<port>-partner/supports_usb_power_delivery
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows if the partner supports USB Power Delivery communication:
+ Valid values: yes, no
+
+What: /sys/class/typec/<port>-partner/number_of_alternate_modes
+Date: November 2020
+Contact: Prashant Malani <pmalani@chromium.org>
+Description:
+ Shows the number of alternate modes which are advertised by the partner
+ during Power Delivery discovery. This file remains hidden until a value
+ greater than or equal to 0 is set by Type C port driver.
+
+What: /sys/class/typec/<port>-partner/type
+Date: December 2020
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description: USB Power Delivery Specification defines a set of product types
+ for the partner devices. This file will show the product type of
+ the partner if it is known. Dual-role capable partners will have
+ both UFP and DFP product types defined, but only one that
+ matches the current role will be active at the time. If the
+ product type of the partner is not visible to the device driver,
+ this file will not exist.
+
+ When the partner product type is detected, or changed with role
+ swap, uvevent is also raised that contains PRODUCT_TYPE=<product
+ type> (for example PRODUCT_TYPE=hub).
+
+ Valid values:
+
+ UFP / device role
+ ====================== ==========================
+ undefined -
+ hub PDUSB Hub
+ peripheral PDUSB Peripheral
+ psd Power Bank
+ ama Alternate Mode Adapter
+ ====================== ==========================
+
+ DFP / host role
+ ====================== ==========================
+ undefined -
+ hub PDUSB Hub
+ host PDUSB Host
+ power_brick Power Brick
+ amc Alternate Mode Controller
+ ====================== ==========================
+
+What: /sys/class/typec/<port>-partner/identity/
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This directory appears only if the port device driver is capable
+ of showing the result of Discover Identity USB power delivery
+ command. That will not always be possible even when USB power
+ delivery is supported, for example when USB power delivery
+ communication for the port is mostly handled in firmware. If the
+ directory exists, it will have an attribute file for every VDO
+ in Discover Identity command result.
+
+What: /sys/class/typec/<port>-partner/usb_mode
+Date: November 2024
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description: The USB Modes that the partner device supports. The active mode
+ is displayed in brackets. The active USB mode can be changed by
+ writing to this file when the port driver is able to send Data
+ Reset Message to the partner. That requires USB Power Delivery
+ contract between the partner and the port.
+
+ Valid values:
+ - usb2 (USB 2.0)
+ - usb3 (USB 3.2)
+ - usb4 (USB4)
+
+USB Type-C cable devices (eg. /sys/class/typec/port0-cable/)
+
+Note: Electronically Marked Cables will have a device also for one cable plug
+(eg. /sys/class/typec/port0-plug0). If the cable is active and has also SOP
+Double Prime controller (USB Power Deliver specification ch. 2.4) it will have
+second device also for the other plug. Both plugs may have alternate modes as
+described in USB Type-C and USB Power Delivery specifications.
+
+What: /sys/class/typec/<port>-cable/type
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description: USB Power Delivery Specification defines a set of product types
+ for the cables. This file will show the product type of the
+ cable if it is known. If the product type of the cable is not
+ visible to the device driver, this file will not exist.
+
+ When the cable product type is detected, uvevent is also raised
+ with PRODUCT_TYPE showing the product type of the cable.
+
+ Valid values:
+
+ ====================== ==========================
+ undefined -
+ active Active Cable
+ passive Passive Cable
+ ====================== ==========================
+
+What: /sys/class/typec/<port>-cable/plug_type
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows type of the plug on the cable:
+
+ - type-a - Standard A
+ - type-b - Standard B
+ - type-c
+ - captive
+
+What: /sys/class/typec/<port>-<plug>/number_of_alternate_modes
+Date: November 2020
+Contact: Prashant Malani <pmalani@chromium.org>
+Description:
+ Shows the number of alternate modes which are advertised by the plug
+ associated with a particular cable during Power Delivery discovery.
+ This file remains hidden until a value greater than or equal to 0
+ is set by Type C port driver.
+
+
+USB Type-C partner/cable Power Delivery Identity objects
+
+NOTE: The following attributes will be applicable to both
+partner (e.g /sys/class/typec/port0-partner/) and
+cable (e.g /sys/class/typec/port0-cable/) devices. Consequently, the example file
+paths below are prefixed with "/sys/class/typec/<port>-{partner|cable}/" to
+reflect this.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This directory appears only if the port device driver is capable
+ of showing the result of Discover Identity USB power delivery
+ command. That will not always be possible even when USB power
+ delivery is supported, for example when USB power delivery
+ communication for the port is mostly handled in firmware. If the
+ directory exists, it will have an attribute file for every VDO
+ in Discover Identity command result.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/id_header
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ ID Header VDO part of Discover Identity command result. The
+ value will show 0 until Discover Identity command result becomes
+ available. The value can be polled.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/cert_stat
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Cert Stat VDO part of Discover Identity command result. The
+ value will show 0 until Discover Identity command result becomes
+ available. The value can be polled.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/product
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Product VDO part of Discover Identity command result. The value
+ will show 0 until Discover Identity command result becomes
+ available. The value can be polled.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/product_type_vdo1
+Date: October 2020
+Contact: Prashant Malani <pmalani@chromium.org>
+Description:
+ 1st Product Type VDO of Discover Identity command result.
+ The value will show 0 until Discover Identity command result becomes
+ available and a valid Product Type VDO is returned.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/product_type_vdo2
+Date: October 2020
+Contact: Prashant Malani <pmalani@chromium.org>
+Description:
+ 2nd Product Type VDO of Discover Identity command result.
+ The value will show 0 until Discover Identity command result becomes
+ available and a valid Product Type VDO is returned.
+
+What: /sys/class/typec/<port>-{partner|cable}/identity/product_type_vdo3
+Date: October 2020
+Contact: Prashant Malani <pmalani@chromium.org>
+Description:
+ 3rd Product Type VDO of Discover Identity command result.
+ The value will show 0 until Discover Identity command result becomes
+ available and a valid Product Type VDO is returned.
+
+
+USB Type-C port alternate mode devices.
+
+What: /sys/class/typec/<port>/<alt mode>/supported_roles
+Date: April 2017
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Space separated list of the supported roles.
+
+ Valid values: source, sink
diff --git a/Documentation/ABI/testing/sysfs-class-usb_power_delivery b/Documentation/ABI/testing/sysfs-class-usb_power_delivery
new file mode 100644
index 000000000000..c754458a527e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-usb_power_delivery
@@ -0,0 +1,284 @@
+What: /sys/class/usb_power_delivery
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Directory for USB Power Delivery devices.
+
+What: /sys/class/usb_power_delivery/.../revision
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ File showing the USB Power Delivery Specification Revision used
+ in communication.
+
+What: /sys/class/usb_power_delivery/.../version
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This is an optional attribute file showing the version of the
+ specific revision of the USB Power Delivery Specification. In
+ most cases the specification version is not known and the file
+ is not available.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The source capabilities message "Source_Capabilities" contains a
+ set of Power Data Objects (PDO), each representing a type of
+ power supply. The order of the PDO objects is defined in the USB
+ Power Delivery Specification. Each PDO - power supply - will
+ have its own device, and the PDO device name will start with the
+ object position number as the first character followed by the
+ power supply type name (":" as delimiter).
+
+ /sys/class/usb_power_delivery/.../source_capabilities/<position>:<type>
+
+What: /sys/class/usb_power_delivery/.../sink-capabilities
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The sink capability message "Sink_Capabilities" contains a set
+ of Power Data Objects (PDO) just like with source capabilities,
+ but instead of describing the power capabilities, these objects
+ describe the power requirements.
+
+ The order of the objects in the sink capability message is the
+ same as with the source capabilities message.
+
+Fixed Supplies
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:fixed_supply
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Devices containing the attributes (the bit fields) defined for
+ Fixed Supplies.
+
+ The device "1:fixed_supply" is special. USB Power Delivery
+ Specification dictates that the first PDO (at object position
+ 1), and the only mandatory PDO, is always the vSafe5V Fixed
+ Supply Object. vSafe5V Object has additional fields defined for
+ it that the other Fixed Supply Objects do not have and that are
+ related to the USB capabilities rather than power capabilities.
+
+What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/dual_role_power
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file contains boolean value that tells does the device
+ support both source and sink power roles.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities/1:fixed_supply/usb_suspend_supported
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file shows the value of the USB Suspend Supported bit in
+ vSafe5V Fixed Supply Object. If the bit is set then the device
+ will follow the USB 2.0 and USB 3.2 rules for suspend and
+ resume.
+
+What: /sys/class/usb_power_delivery/.../sink-capabilities/1:fixed_supply/higher_capability
+Date: February 2023
+Contact: Saranya Gopal <saranya.gopal@linux.intel.com>
+Description:
+ This file shows the value of the Higher capability bit in
+ vsafe5V Fixed Supply Object. If the bit is set, then the sink
+ needs more than vsafe5V(eg. 12 V) to provide full functionality.
+ Valid values: 0, 1
+
+What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/unconstrained_power
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file shows the value of the Unconstrained Power bit in
+ vSafe5V Fixed Supply Object. The bit is set when an external
+ source of power, powerful enough to power the entire system on
+ its own, is available for the device.
+
+What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/usb_communication_capable
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file shows the value of the USB Communication Capable bit in
+ vSafe5V Fixed Supply Object.
+
+What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/dual_role_data
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file shows the value of the Dual-Role Data bit in vSafe5V
+ Fixed Supply Object. Dual role data means ability act as both
+ USB host and USB device.
+
+What: /sys/class/usb_power_delivery/.../<capability>/1:fixed_supply/unchunked_extended_messages_supported
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file shows the value of the Unchunked Extended Messages
+ Supported bit in vSafe5V Fixed Supply Object.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:fixed_supply/voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The voltage the supply supports in millivolts.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:fixed_supply/peak_current
+Date: October 2023
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file shows the value of the Fixed Power Source Peak Current
+ Capability field.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:fixed_supply/maximum_current
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Maximum current of the fixed source supply in milliamperes.
+
+What: /sys/class/usb_power_delivery/.../sink-capabilities/<position>:fixed_supply/operational_current
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Operational current of the sink in milliamperes.
+
+What: /sys/class/usb_power_delivery/.../sink-capabilities/<position>:fixed_supply/fast_role_swap_current
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This file contains the value of the "Fast Role Swap USB Type-C
+ Current" field that tells the current level the sink requires
+ after a Fast Role Swap.
+ 0 - Fast Swap not supported"
+ 1 - Default USB Power"
+ 2 - 1.5A@5V"
+ 3 - 3.0A@5V"
+
+Variable Supplies
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:variable_supply
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Variable Power Supply PDO.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:variable_supply/maximum_voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Maximum Voltage in millivolts.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:variable_supply/minimum_voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Minimum Voltage in millivolts.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:variable_supply/maximum_current
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The maximum current in milliamperes that the source can supply
+ at the given Voltage range.
+
+What: /sys/class/usb_power_delivery/.../sink-capabilities/<position>:variable_supply/operational_current
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The operational current in milliamperes that the sink requires
+ at the given Voltage range.
+
+Battery Supplies
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:battery
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Battery PDO.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:battery/maximum_voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Maximum Voltage in millivolts.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:battery/minimum_voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Minimum Voltage in millivolts.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:battery/maximum_power
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Maximum allowable Power in milliwatts.
+
+What: /sys/class/usb_power_delivery/.../sink-capabilities/<position>:battery/operational_power
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The operational power that the sink requires at the given
+ voltage range.
+
+Standard Power Range (SPR) Programmable Power Supplies
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:programmable_supply
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Programmable Power Supply (PPS) Augmented PDO (APDO).
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:programmable_supply/maximum_voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Maximum Voltage in millivolts.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:programmable_supply/minimum_voltage
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Minimum Voltage in millivolts.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:programmable_supply/maximum_current
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Maximum Current in milliamperes.
+
+What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:programmable_supply/pps_power_limited
+Date: May 2022
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The PPS Power Limited bit indicates whether or not the source
+ supply will exceed the rated output power if requested.
+
+Standard Power Range (SPR) Adjustable Voltage Supplies
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:spr_adjustable_voltage_supply
+Date: Oct 2025
+Contact: Badhri Jagan Sridharan <badhri@google.com>
+Description:
+ Adjustable Voltage Supply (AVS) Augmented PDO (APDO).
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:spr_adjustable_voltage_supply/maximum_current_9V_to_15V
+Date: Oct 2025
+Contact: Badhri Jagan Sridharan <badhri@google.com>
+Description:
+ Maximum Current for 9V to 15V range in milliamperes.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:spr_adjustable_voltage_supply/maximum_current_15V_to_20V
+Date: Oct 2025
+Contact: Badhri Jagan Sridharan <badhri@google.com>
+Description:
+ Maximum Current for greater than 15V till 20V range in
+ milliamperes.
+
+What: /sys/class/usb_power_delivery/.../<capability>/<position>:spr_adjustable_voltage_supply/peak_current
+Date: Oct 2025
+Contact: Badhri Jagan Sridharan <badhri@google.com>
+Description:
+ This file shows the value of the Adjustable Voltage Supply Peak Current
+ Capability field.
diff --git a/Documentation/ABI/testing/sysfs-class-usb_role b/Documentation/ABI/testing/sysfs-class-usb_role
new file mode 100644
index 000000000000..9fab3f06679e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-usb_role
@@ -0,0 +1,27 @@
+What: /sys/class/usb_role/
+Date: Jan 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Place in sysfs for USB Role Switches. USB Role Switch is a
+ device that can select the data role (host or device) for USB
+ port.
+
+What: /sys/class/usb_role/<switch>/role
+Date: Jan 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ The current role of the switch. This attribute can be used for
+ requesting role swapping with non-USB Type-C ports. With USB
+ Type-C ports, the ABI defined for USB Type-C connector class
+ must be used.
+
+ Valid values:
+ - none
+ - host
+ - device
+
+What: /sys/class/usb_role/<switch>/connector
+Date: Feb 2024
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Optional symlink to the USB Type-C connector.
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc
deleted file mode 100644
index 85f4875d16ac..000000000000
--- a/Documentation/ABI/testing/sysfs-class-uwb_rc
+++ /dev/null
@@ -1,159 +0,0 @@
-What: /sys/class/uwb_rc
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- Interfaces for WiMedia Ultra Wideband Common Radio
- Platform (UWB) radio controllers.
-
- Familiarity with the ECMA-368 'High Rate Ultra
- Wideband MAC and PHY Specification' is assumed.
-
-What: /sys/class/uwb_rc/beacon_timeout_ms
-Date: July 2008
-KernelVersion: 2.6.27
-Description:
- If no beacons are received from a device for at least
- this time, the device will be considered to have gone
- and it will be removed. The default is 3 superframes
- (~197 ms) as required by the specification.
-
-What: /sys/class/uwb_rc/uwbN/
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- An individual UWB radio controller.
-
-What: /sys/class/uwb_rc/uwbN/beacon
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- Write:
-
- <channel>
-
- to force a specific channel to be used when beaconing,
- or, if <channel> is -1, to prohibit beaconing. If
- <channel> is 0, then the default channel selection
- algorithm will be used. Valid channels depends on the
- radio controller's supported band groups.
-
- Reading returns the currently active channel, or -1 if
- the radio controller is not beaconing.
-
-What: /sys/class/uwb_rc/uwbN/ASIE
-Date: August 2014
-KernelVersion: 3.18
-Contact: linux-usb@vger.kernel.org
-Description:
-
- The application-specific information element (ASIE)
- included in this device's beacon, in space separated
- hex octets.
-
- Reading returns the current ASIE. Writing replaces
- the current ASIE with the one written.
-
-What: /sys/class/uwb_rc/uwbN/scan
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- Write:
-
- <channel> <type> [<bpst offset>]
-
- to start (or stop) scanning on a channel. <type> is one of:
- 0 - scan
- 1 - scan outside BP
- 2 - scan while inactive
- 3 - scanning disabled
- 4 - scan (with start time of <bpst offset>)
-
-What: /sys/class/uwb_rc/uwbN/mac_address
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- The EUI-48, in colon-separated hex octets, for this
- radio controller. A write will change the radio
- controller's EUI-48 but only do so while the device is
- not beaconing or scanning.
-
-What: /sys/class/uwb_rc/uwbN/wusbhc
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- A symlink to the device (if any) of the WUSB Host
- Controller PAL using this radio controller.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- A neighbour UWB device that has either been detected
- as part of a scan or is a member of the radio
- controllers beacon group.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- The time (using the radio controllers internal 1 ms
- interval superframe timer) of the last beacon from
- this device was received.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/DevAddr
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- The current DevAddr of this device in colon separated
- hex octets.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/EUI_48
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
-
- The EUI-48 of this device in colon separated hex
- octets.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- The latest IEs included in this device's beacon, in
- space separated hex octets with one IE per line.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/LQE
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- Link Quality Estimate - the Signal to Noise Ratio
- (SNR) of all packets received from this device in dB.
- This gives an estimate on a suitable PHY rate. Refer
- to [ECMA-368] section 13.3 for more details.
-
-What: /sys/class/uwb_rc/uwbN/<EUI-48>/RSSI
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: linux-usb@vger.kernel.org
-Description:
- Received Signal Strength Indication - the strength of
- the received signal in dB. LQE is a more useful
- measure of the radio link quality.
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc
deleted file mode 100644
index 5977e2875325..000000000000
--- a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc
+++ /dev/null
@@ -1,57 +0,0 @@
-What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_chid
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- Write the CHID (16 space-separated hex octets) for this host controller.
- This starts the host controller, allowing it to accept connection from
- WUSB devices.
-
- Set an all zero CHID to stop the host controller.
-
-What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_trust_timeout
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- Devices that haven't sent a WUSB packet to the host
- within 'wusb_trust_timeout' ms are considered to have
- disconnected and are removed. The default value of
- 4000 ms is the value required by the WUSB
- specification.
-
- Since this relates to security (specifically, the
- lifetime of PTKs and GTKs) it should not be changed
- from the default.
-
-What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_phy_rate
-Date: August 2009
-KernelVersion: 2.6.32
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The maximum PHY rate to use for all connected devices.
- This is only of limited use for testing and
- development as the hardware's automatic rate
- adaptation is better then this simple control.
-
- Refer to [ECMA-368] section 10.3.1.1 for the value to
- use.
-
-What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_dnts
-Date: June 2013
-KernelVersion: 3.11
-Contact: Thomas Pugliese <thomas.pugliese@gmail.com>
-Description:
- The device notification time slot (DNTS) count and inverval in
- milliseconds that the WUSB host should use. This controls how
- often the devices will have the opportunity to send
- notifications to the host.
-
-What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_retry_count
-Date: June 2013
-KernelVersion: 3.11
-Contact: Thomas Pugliese <thomas.pugliese@gmail.com>
-Description:
- The number of retries that the WUSB host should attempt
- before reporting an error for a bus transaction. The range of
- valid values is [0..15], where 0 indicates infinite retries.
diff --git a/Documentation/ABI/testing/sysfs-class-vduse b/Documentation/ABI/testing/sysfs-class-vduse
new file mode 100644
index 000000000000..2f2bc5c8fc48
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-vduse
@@ -0,0 +1,33 @@
+What: /sys/class/vduse/
+Date: Oct 2021
+KernelVersion: 5.15
+Contact: Yongji Xie <xieyongji@bytedance.com>
+Description:
+ The vduse/ class sub-directory belongs to the VDUSE
+ framework and provides a sysfs interface for configuring
+ VDUSE devices.
+
+What: /sys/class/vduse/control/
+Date: Oct 2021
+KernelVersion: 5.15
+Contact: Yongji Xie <xieyongji@bytedance.com>
+Description:
+ This directory entry is created for the control device
+ of VDUSE framework.
+
+What: /sys/class/vduse/<device-name>/
+Date: Oct 2021
+KernelVersion: 5.15
+Contact: Yongji Xie <xieyongji@bytedance.com>
+Description:
+ This directory entry is created when a VDUSE device is
+ created via the control device.
+
+What: /sys/class/vduse/<device-name>/msg_timeout
+Date: Oct 2021
+KernelVersion: 5.15
+Contact: Yongji Xie <xieyongji@bytedance.com>
+Description:
+ (RW) The timeout (in seconds) for waiting for the control
+ message's response from userspace. Default value is 30s.
+ Writing a '0' to the file means to disable the timeout.
diff --git a/Documentation/ABI/testing/sysfs-class-wakeup b/Documentation/ABI/testing/sysfs-class-wakeup
new file mode 100644
index 000000000000..754aab8b6dcd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-wakeup
@@ -0,0 +1,76 @@
+What: /sys/class/wakeup/
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ The /sys/class/wakeup/ directory contains pointers to all
+ wakeup sources in the kernel at that moment in time.
+
+What: /sys/class/wakeup/.../name
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the name of the wakeup source.
+
+What: /sys/class/wakeup/.../active_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of times the wakeup source was
+ activated.
+
+What: /sys/class/wakeup/.../event_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of signaled wakeup events
+ associated with the wakeup source.
+
+What: /sys/class/wakeup/.../wakeup_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of times the wakeup source might
+ abort suspend.
+
+What: /sys/class/wakeup/.../expire_count
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the number of times the wakeup source's
+ timeout has expired.
+
+What: /sys/class/wakeup/.../active_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the amount of time the wakeup source has
+ been continuously active, in milliseconds. If the wakeup
+ source is not active, this file contains '0'.
+
+What: /sys/class/wakeup/.../total_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the total amount of time this wakeup source
+ has been active, in milliseconds.
+
+What: /sys/class/wakeup/.../max_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the maximum amount of time this wakeup
+ source has been continuously active, in milliseconds.
+
+What: /sys/class/wakeup/.../last_change_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ This file contains the monotonic clock time when the wakeup
+ source was touched last time, in milliseconds.
+
+What: /sys/class/wakeup/.../prevent_suspend_time_ms
+Date: June 2019
+Contact: Tri Vo <trong@android.com>
+Description:
+ The file contains the total amount of time this wakeup source
+ has been preventing autosleep, in milliseconds.
diff --git a/Documentation/ABI/testing/sysfs-class-watchdog b/Documentation/ABI/testing/sysfs-class-watchdog
new file mode 100644
index 000000000000..70eabccf0557
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-watchdog
@@ -0,0 +1,129 @@
+What: /sys/class/watchdog/watchdogn/bootstatus
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It contains status of the watchdog
+ device at boot. It is equivalent to WDIOC_GETBOOTSTATUS of
+ ioctl interface.
+
+What: /sys/class/watchdog/watchdogn/options
+Date: April 2023
+Contact: Thomas Weißschuh
+Description:
+ It is a read only file. It contains options of watchdog device.
+
+What: /sys/class/watchdog/watchdogn/fw_version
+Date: April 2023
+Contact: Thomas Weißschuh
+Description:
+ It is a read only file. It contains firmware version of
+ watchdog device.
+
+What: /sys/class/watchdog/watchdogn/identity
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It contains identity string of
+ watchdog device.
+
+What: /sys/class/watchdog/watchdogn/nowayout
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read/write file. While reading, it gives '1'
+ if the device has the nowayout feature set, otherwise
+ it gives '0'. Writing a '1' to the file enables the
+ nowayout feature. Once set, the nowayout feature
+ cannot be disabled, so writing a '0' either has no
+ effect (if the feature was already disabled) or
+ results in a permission error.
+
+What: /sys/class/watchdog/watchdogn/state
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It gives active/inactive status of
+ watchdog device.
+
+What: /sys/class/watchdog/watchdogn/status
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It contains watchdog device's
+ internal status bits. It is equivalent to WDIOC_GETSTATUS
+ of ioctl interface.
+
+What: /sys/class/watchdog/watchdogn/timeleft
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It contains value of time left for
+ reset generation. It is equivalent to WDIOC_GETTIMELEFT of
+ ioctl interface.
+
+What: /sys/class/watchdog/watchdogn/timeout
+Date: August 2015
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It is read to know about current
+ value of timeout programmed.
+
+What: /sys/class/watchdog/watchdogn/pretimeout
+Date: December 2016
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It specifies the time in seconds before
+ timeout when the pretimeout interrupt is delivered. Pretimeout
+ is an optional feature.
+
+What: /sys/class/watchdog/watchdogn/pretimeout_available_governors
+Date: February 2017
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read only file. It shows the pretimeout governors
+ available for this watchdog.
+
+What: /sys/class/watchdog/watchdogn/pretimeout_governor
+Date: February 2017
+Contact: Wim Van Sebroeck <wim@iguana.be>
+Description:
+ It is a read/write file. When read, the currently assigned
+ pretimeout governor is returned. When written, it sets
+ the pretimeout governor.
+
+What: /sys/class/watchdog/watchdog1/access_cs0
+Date: August 2019
+Contact: Ivan Mikhaylov <i.mikhaylov@yadro.com>,
+ Alexander Amelkin <a.amelkin@yadro.com>
+Description:
+ It is a read/write file. This attribute exists only if the
+ system has booted from the alternate flash chip due to
+ expiration of a watchdog timer of AST2400/AST2500 when
+ alternate boot function was enabled with 'aspeed,alt-boot'
+ devicetree option for that watchdog or with an appropriate
+ h/w strapping (for WDT2 only).
+
+ At alternate flash the 'access_cs0' sysfs node provides:
+
+ ast2400:
+ a way to get access to the primary SPI flash
+ chip at CS0 after booting from the alternate
+ chip at CS1.
+ ast2500:
+ a way to restore the normal address mapping
+ from (CS0->CS1, CS1->CS0) to (CS0->CS0,
+ CS1->CS1).
+
+ Clearing the boot code selection and timeout counter also
+ resets to the initial state the chip select line mapping. When
+ the SoC is in normal mapping state (i.e. booted from CS0),
+ clearing those bits does nothing for both versions of the SoC.
+ For alternate boot mode (booted from CS1 due to wdt2
+ expiration) the behavior differs as described above.
+
+ This option can be used with wdt2 (watchdog1) only.
+
+ When read, the current status of the boot code selection is
+ shown. When written with any non-zero value, it clears
+ the boot code selection and the timeout counter, which results
+ in chipselect reset for AST2400/AST2500.
diff --git a/Documentation/ABI/testing/sysfs-class-zram b/Documentation/ABI/testing/sysfs-class-zram
new file mode 100644
index 000000000000..48ddacbe0e69
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-zram
@@ -0,0 +1,24 @@
+What: /sys/class/zram-control/
+Date: August 2015
+KernelVersion: 4.2
+Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+ The zram-control/ class sub-directory belongs to zram
+ device class
+
+What: /sys/class/zram-control/hot_add
+Date: August 2015
+KernelVersion: 4.2
+Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+ RO attribute. Read operation will cause zram to add a new
+ device and return its device id back to user (so one can
+ use /dev/zram<id>), or error code.
+
+What: /sys/class/zram-control/hot_remove
+Date: August 2015
+KernelVersion: 4.2
+Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
+Description:
+ WO attribute. Remove a specific /dev/zramX device, where X
+ is a device_id provided by user.
diff --git a/Documentation/ABI/testing/sysfs-dev b/Documentation/ABI/testing/sysfs-dev
index a9f2b8b0530f..d1739063e762 100644
--- a/Documentation/ABI/testing/sysfs-dev
+++ b/Documentation/ABI/testing/sysfs-dev
@@ -9,9 +9,10 @@ Description: The /sys/dev tree provides a method to look up the sysfs
the form "<major>:<minor>". These links point to the
corresponding sysfs path for the given device.
- Example:
- $ readlink /sys/dev/block/8:32
- ../../block/sdc
+ Example::
+
+ $ readlink /sys/dev/block/8:32
+ ../../block/sdc
Entries in /sys/dev/char and /sys/dev/block will be
dynamically created and destroyed as devices enter and
diff --git a/Documentation/ABI/testing/sysfs-devices-consumer b/Documentation/ABI/testing/sysfs-devices-consumer
new file mode 100644
index 000000000000..0809fda092e6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-consumer
@@ -0,0 +1,9 @@
+What: /sys/devices/.../consumer:<consumer>
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../consumer:<consumer> are symlinks to device
+ links where this device is the supplier. <consumer> denotes the
+ name of the consumer in that device link and is of the form
+ bus:device name. There can be zero or more of these symlinks
+ for a given device.
diff --git a/Documentation/ABI/testing/sysfs-devices-coredump b/Documentation/ABI/testing/sysfs-devices-coredump
new file mode 100644
index 000000000000..e459368533a4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-coredump
@@ -0,0 +1,10 @@
+What: /sys/devices/.../coredump
+Date: December 2017
+Contact: Arend van Spriel <aspriel@gmail.com>
+Description:
+ The /sys/devices/.../coredump attribute is only present when the
+ device is bound to a driver, which provides the .coredump()
+ callback. The attribute is write only. Anything written to this
+ file will trigger the .coredump() callback.
+
+ Available when CONFIG_DEV_COREDUMP is enabled.
diff --git a/Documentation/ABI/testing/sysfs-devices-edac b/Documentation/ABI/testing/sysfs-devices-edac
index 6568e0010e1a..256a9e990c0b 100644
--- a/Documentation/ABI/testing/sysfs-devices-edac
+++ b/Documentation/ABI/testing/sysfs-devices-edac
@@ -77,7 +77,7 @@ Description: Read/Write attribute file that controls memory scrubbing.
What: /sys/devices/system/edac/mc/mc*/max_location
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This attribute file displays the information about the last
available memory slot in this memory controller. It is used by
@@ -85,7 +85,7 @@ Description: This attribute file displays the information about the last
What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/size
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This attribute file will display the size of dimm or rank.
For dimm*/size, this is the size, in MB of the DIMM memory
@@ -96,14 +96,14 @@ Description: This attribute file will display the size of dimm or rank.
What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_dev_type
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This attribute file will display what type of DRAM device is
being utilized on this DIMM (x1, x2, x4, x8, ...).
What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_edac_mode
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This attribute file will display what type of Error detection
and correction is being utilized. For example: S4ECD4ED would
@@ -111,7 +111,7 @@ Description: This attribute file will display what type of Error detection
What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_label
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This control file allows this DIMM to have a label assigned
to it. With this label in the module, when errors occur
@@ -126,15 +126,32 @@ Description: This control file allows this DIMM to have a label assigned
What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_location
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This attribute file will display the location (csrow/channel,
branch/channel/slot or channel/slot) of the dimm or rank.
What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_mem_type
Date: April 2012
-Contact: Mauro Carvalho Chehab <m.chehab@samsung.com>
+Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
linux-edac@vger.kernel.org
Description: This attribute file will display what type of memory is
currently on this csrow. Normally, either buffered or
unbuffered memory (for example, Unbuffered-DDR3).
+
+What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_ce_count
+Date: October 2016
+Contact: linux-edac@vger.kernel.org
+Description: This attribute file displays the total count of correctable
+ errors that have occurred on this DIMM. This count is very important
+ to examine. CEs provide early indications that a DIMM is beginning
+ to fail. This count field should be monitored for non-zero values
+ and report such information to the system administrator.
+
+What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_ue_count
+Date: October 2016
+Contact: linux-edac@vger.kernel.org
+Description: This attribute file displays the total count of uncorrectable
+ errors that have occurred on this DIMM. If panic_on_ue is set, this
+ counter will not have a chance to increment, since EDAC will panic the
+ system
diff --git a/Documentation/ABI/testing/sysfs-devices-mapping b/Documentation/ABI/testing/sysfs-devices-mapping
new file mode 100644
index 000000000000..2eee1446ad4c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-mapping
@@ -0,0 +1,62 @@
+What: /sys/devices/uncore_iio_x/dieX
+Date: February 2020
+Contact: Alexander Antonov <alexander.antonov@linux.intel.com>
+Description:
+ Each IIO stack (PCIe root port) has its own IIO PMON block, so
+ each dieX file (where X is die number) holds "Segment:Root Bus"
+ for PCIe root port, which can be monitored by that IIO PMON
+ block.
+ For example, on 4-die Xeon platform with up to 6 IIO stacks per
+ die and, therefore, 6 IIO PMON blocks per die, the mapping of
+ IIO PMON block 0 exposes as the following::
+
+ $ ls /sys/devices/uncore_iio_0/die*
+ -r--r--r-- /sys/devices/uncore_iio_0/die0
+ -r--r--r-- /sys/devices/uncore_iio_0/die1
+ -r--r--r-- /sys/devices/uncore_iio_0/die2
+ -r--r--r-- /sys/devices/uncore_iio_0/die3
+
+ $ tail /sys/devices/uncore_iio_0/die*
+ ==> /sys/devices/uncore_iio_0/die0 <==
+ 0000:00
+ ==> /sys/devices/uncore_iio_0/die1 <==
+ 0000:40
+ ==> /sys/devices/uncore_iio_0/die2 <==
+ 0000:80
+ ==> /sys/devices/uncore_iio_0/die3 <==
+ 0000:c0
+
+ Which means::
+
+ IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000
+ IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000
+ IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000
+ IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000
+
+What: /sys/devices/uncore_upi_x/dieX
+Date: March 2022
+Contact: Alexander Antonov <alexander.antonov@linux.intel.com>
+Description:
+ Each /sys/devices/uncore_upi_X/dieY file holds "upi_Z,die_W"
+ value that means UPI link number X on die Y is connected to UPI
+ link Z on die W and this link between sockets can be monitored
+ by UPI PMON block.
+ For example, 4-die Sapphire Rapids platform has the following
+ UPI 0 topology::
+
+ # tail /sys/devices/uncore_upi_0/die*
+ ==> /sys/devices/uncore_upi_0/die0 <==
+ upi_1,die_1
+ ==> /sys/devices/uncore_upi_0/die1 <==
+ upi_0,die_3
+ ==> /sys/devices/uncore_upi_0/die2 <==
+ upi_1,die_3
+ ==> /sys/devices/uncore_upi_0/die3 <==
+ upi_0,die_1
+
+ Which means::
+
+ UPI link 0 on die 0 is connected to UPI link 1 on die 1
+ UPI link 0 on die 1 is connected to UPI link 0 on die 3
+ UPI link 0 on die 2 is connected to UPI link 1 on die 3
+ UPI link 0 on die 3 is connected to UPI link 0 on die 1 \ No newline at end of file
diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory
index deef3b5723cf..cec65827e602 100644
--- a/Documentation/ABI/testing/sysfs-devices-memory
+++ b/Documentation/ABI/testing/sysfs-devices-memory
@@ -13,21 +13,22 @@ What: /sys/devices/system/memory/memoryX/removable
Date: June 2008
Contact: Badari Pulavarty <pbadari@us.ibm.com>
Description:
- The file /sys/devices/system/memory/memoryX/removable
- indicates whether this memory block is removable or not.
- This is useful for a user-level agent to determine
- identify removable sections of the memory before attempting
- potentially expensive hot-remove memory operation
+ The file /sys/devices/system/memory/memoryX/removable is a
+ legacy interface used to indicated whether a memory block is
+ likely to be offlineable or not. Newer kernel versions return
+ "1" if and only if the kernel supports memory offlining.
Users: hotplug memory remove tools
- http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils
+ http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils
+ lsmem/chmem part of util-linux
What: /sys/devices/system/memory/memoryX/phys_device
Date: September 2008
Contact: Badari Pulavarty <pbadari@us.ibm.com>
Description:
The file /sys/devices/system/memory/memoryX/phys_device
- is read-only and is designed to show the name of physical
- memory device. Implementation is currently incomplete.
+ is read-only; it is a legacy interface only ever used on s390x
+ to expose the covered storage increment.
+Users: Legacy s390-tools lsmem/chmem
What: /sys/devices/system/memory/memoryX/phys_index
Date: September 2008
@@ -43,20 +44,25 @@ Date: September 2008
Contact: Badari Pulavarty <pbadari@us.ibm.com>
Description:
The file /sys/devices/system/memory/memoryX/state
- is read-write. When read, its contents show the
- online/offline state of the memory section. When written,
- root can toggle the the online/offline state of a removable
- memory section (see removable file description above)
- using the following commands.
- # echo online > /sys/devices/system/memory/memoryX/state
- # echo offline > /sys/devices/system/memory/memoryX/state
-
- For example, if /sys/devices/system/memory/memory22/removable
- contains a value of 1 and
- /sys/devices/system/memory/memory22/state contains the
- string "online" the following command can be executed by
- by root to offline that section.
- # echo offline > /sys/devices/system/memory/memory22/state
+ is read-write. When read, it returns the online/offline
+ state of the memory block. When written, root can toggle
+ the online/offline state of a memory block using the following
+ commands::
+
+ # echo online > /sys/devices/system/memory/memoryX/state
+ # echo offline > /sys/devices/system/memory/memoryX/state
+
+ On newer kernel versions, advanced states can be specified
+ when onlining to select a target zone: "online_movable"
+ selects the movable zone. "online_kernel" selects the
+ applicable kernel zone (DMA, DMA32, or Normal). However,
+ after successfully setting one of the advanced states,
+ reading the file will return "online"; the zone information
+ can be obtained via "valid_zones" instead.
+
+ While onlining is unlikely to fail, there are no guarantees
+ that offlining will succeed. Offlining is more likely to
+ succeed if "valid_zones" indicates "Movable".
Users: hotplug memory remove tools
http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils
@@ -66,8 +72,19 @@ Date: July 2014
Contact: Zhang Zhen <zhenzhang.zhang@huawei.com>
Description:
The file /sys/devices/system/memory/memoryX/valid_zones is
- read-only and is designed to show which zone this memory
- block can be onlined to.
+ read-only.
+
+ For online memory blocks, it returns in which zone memory
+ provided by a memory block is managed. If multiple zones
+ apply (not applicable for hotplugged memory), "None" is returned
+ and the memory block cannot be offlined.
+
+ For offline memory blocks, it returns by which zone memory
+ provided by a memory block can be managed when onlining.
+ The first returned zone ("default") will be used when setting
+ the state of an offline memory block to "online". Only one of
+ the kernel zones (DMA, DMA32, Normal) is applicable for a single
+ memory block.
What: /sys/devices/system/memoryX/nodeY
Date: October 2009
@@ -78,6 +95,7 @@ Description:
For example, the following symbolic link is created for
memory section 9 on node0:
+
/sys/devices/system/memory/memory9/node0 -> ../../node/node0
@@ -90,4 +108,13 @@ Description:
points to the corresponding /sys/devices/system/memory/memoryY
memory section directory. For example, the following symbolic
link is created for memory section 9 on node0.
+
/sys/devices/system/node/node0/memory9 -> ../../memory/memory9
+
+What: /sys/devices/system/memory/crash_hotplug
+Date: Aug 2023
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ (RO) indicates whether or not the kernel updates relevant kexec
+ segments on memory hot un/plug and/or on/offline events, avoiding the
+ need to reload kdump kernel.
diff --git a/Documentation/ABI/testing/sysfs-devices-online b/Documentation/ABI/testing/sysfs-devices-online
index f990026c0740..c3359fec2980 100644
--- a/Documentation/ABI/testing/sysfs-devices-online
+++ b/Documentation/ABI/testing/sysfs-devices-online
@@ -17,4 +17,4 @@ Description:
After a successful execution of the bus type's .offline()
callback the device cannot be used for any purpose until either
it is removed (i.e. device_del() is called for it), or its bus
- type's .online() is exeucted successfully.
+ type's .online() is executed successfully.
diff --git a/Documentation/ABI/testing/sysfs-devices-pci-host-bridge b/Documentation/ABI/testing/sysfs-devices-pci-host-bridge
new file mode 100644
index 000000000000..b91ec3450811
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-pci-host-bridge
@@ -0,0 +1,45 @@
+What: /sys/devices/pciDDDD:BB
+ /sys/devices/.../pciDDDD:BB
+Contact: linux-pci@vger.kernel.org
+Description:
+ A PCI host bridge device parents a PCI bus device topology. PCI
+ controllers may also parent host bridges. The DDDD:BB format
+ conveys the PCI domain (ACPI segment) number and root bus number
+ (in hexadecimal) of the host bridge. Note that the domain number
+ may be larger than the 16-bits that the "DDDD" format implies
+ for emulated host-bridges.
+
+What: pciDDDD:BB/firmware_node
+Contact: linux-pci@vger.kernel.org
+Description:
+ (RO) Symlink to the platform firmware device object "companion"
+ of the host bridge. For example, an ACPI device with an _HID of
+ PNP0A08 (/sys/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0A08:00). See
+ /sys/devices/pciDDDD:BB entry for details about the DDDD:BB
+ format.
+
+What: pciDDDD:BB/streamH.R.E
+Contact: linux-pci@vger.kernel.org
+Description:
+ (RO) When a platform has established a secure connection, PCIe
+ IDE, between two Partner Ports, this symlink appears. A stream
+ consumes a Stream ID slot in each of the Host bridge (H), Root
+ Port (R) and Endpoint (E). The link points to the Endpoint PCI
+ device in the Selective IDE Stream pairing. Specifically, "R"
+ and "E" represent the assigned Selective IDE Stream Register
+ Block in the Root Port and Endpoint, and "H" represents a
+ platform specific pool of stream resources shared by the Root
+ Ports in a host bridge. See /sys/devices/pciDDDD:BB entry for
+ details about the DDDD:BB format.
+
+What: pciDDDD:BB/available_secure_streams
+Contact: linux-pci@vger.kernel.org
+Description:
+ (RO) When a host bridge has Root Ports that support PCIe IDE
+ (link encryption and integrity protection) there may be a
+ limited number of Selective IDE Streams that can be used for
+ establishing new end-to-end secure links. This attribute
+ decrements upon secure link setup, and increments upon secure
+ link teardown. The in-use stream count is determined by counting
+ stream symlinks. See /sys/devices/pciDDDD:BB entry for details
+ about the DDDD:BB format.
diff --git a/Documentation/ABI/testing/sysfs-devices-physical_location b/Documentation/ABI/testing/sysfs-devices-physical_location
new file mode 100644
index 000000000000..202324b87083
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-physical_location
@@ -0,0 +1,42 @@
+What: /sys/devices/.../physical_location
+Date: March 2022
+Contact: Won Chung <wonchung@google.com>
+Description:
+ This directory contains information on physical location of
+ the device connection point with respect to the system's
+ housing.
+
+What: /sys/devices/.../physical_location/panel
+Date: March 2022
+Contact: Won Chung <wonchung@google.com>
+Description:
+ Describes which panel surface of the system’s housing the
+ device connection point resides on.
+
+What: /sys/devices/.../physical_location/vertical_position
+Date: March 2022
+Contact: Won Chung <wonchung@google.com>
+Description:
+ Describes vertical position of the device connection point on
+ the panel surface.
+
+What: /sys/devices/.../physical_location/horizontal_position
+Date: March 2022
+Contact: Won Chung <wonchung@google.com>
+Description:
+ Describes horizontal position of the device connection point on
+ the panel surface.
+
+What: /sys/devices/.../physical_location/dock
+Date: March 2022
+Contact: Won Chung <wonchung@google.com>
+Description:
+ "Yes" if the device connection point resides in a docking
+ station or a port replicator. "No" otherwise.
+
+What: /sys/devices/.../physical_location/lid
+Date: March 2022
+Contact: Won Chung <wonchung@google.com>
+Description:
+ "Yes" if the device connection point resides on the lid of
+ laptop system. "No" otherwise.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
new file mode 100644
index 000000000000..bc44bc903bc8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
@@ -0,0 +1,117 @@
+ ACPI Time and Alarm (TAD) device attributes.
+
+What: /sys/bus/platform/devices/ACPI000E:00/caps
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ (RO) Hexadecimal bitmask of the TAD attributes are reported by
+ the platform firmware (see ACPI 6.2, section 9.18.2):
+
+ ======= ======================================================
+ BIT(0): AC wakeup implemented if set
+ BIT(1): DC wakeup implemented if set
+ BIT(2): Get/set real time features implemented if set
+ BIT(3): Real time accuracy in milliseconds if set
+ BIT(4): Correct status reported for wakeups from S4/S5 if set
+ BIT(5): The AC timer wakes up from S4 if set
+ BIT(6): The AC timer wakes up from S5 if set
+ BIT(7): The DC timer wakes up from S4 if set
+ BIT(8): The DC timer wakes up from S5 if set
+ ======= ======================================================
+
+ The other bits are reserved.
+
+What: /sys/bus/platform/devices/ACPI000E:00/ac_alarm
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ (RW) The AC alarm timer value.
+
+ Reads return the current AC alarm timer value in seconds or
+ "disabled", if the AC alarm is not set to wake up the system.
+
+ Write a new AC alarm timer value in seconds or "disabled" to it
+ to set the AC alarm timer or to disable it, respectively.
+
+ If the AC alarm timer is set through this attribute and it
+ expires, it will immediately wake up the system from the S3
+ sleep state (and from S4/S5 too if supported) until its status
+ is explicitly cleared via the ac_status attribute.
+
+What: /sys/bus/platform/devices/ACPI000E:00/ac_policy
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ (RW) The AC alarm expired timer wake policy (see ACPI 6.2,
+ Section 9.18 for details).
+
+ Reads return the current expired timer wake delay for the AC
+ alarm timer or "never", if the policy is to discard AC timer
+ wakeups if the system is on DC power.
+
+ Write a new expired timer wake delay for the AC alarm timer in
+ seconds or "never" to it to set the expired timer wake delay for
+ the AC alarm timer or to set its expired wake policy to discard
+ wakeups if the system is on DC power, respectively.
+
+What: /sys/bus/platform/devices/ACPI000E:00/ac_status
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ (RW) The AC alarm status.
+
+ Reads return a hexadecimal bitmask representing the AC alarm
+ timer status with the following meaning of bits (see ACPI 6.2,
+ Section 9.18.5):
+
+ ======= ======================================================
+ Bit(0): The timer has expired if set.
+ Bit(1): The timer has woken up the system from a sleep state
+ (S3 or S4/S5 if supported) if set.
+ ======= ======================================================
+
+ The other bits are reserved.
+
+ Reads also cause the AC alarm timer status to be reset.
+
+ Another way to reset the status of the AC alarm timer is to
+ write (the number) 0 to this file.
+
+ If the status return value indicates that the timer has expired,
+ it will immediately wake up the system from the S3 sleep state
+ (and from S4/S5 too if supported) until its status is explicitly
+ cleared through this attribute.
+
+What: /sys/bus/platform/devices/ACPI000E:00/dc_alarm
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ (RW,optional) The DC alarm timer value.
+
+ This attribute is only present if the TAD supports a separate
+ DC timer.
+
+ It is analogous to the ac_alarm attribute.
+
+What: /sys/bus/platform/devices/ACPI000E:00/dc_policy
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+Description:
+ (RW,optional) The DC alarm expired timer wake policy.
+
+ This attribute is only present if the TAD supports a separate
+ DC timer.
+
+ It is analogous to the ac_policy attribute.
+
+What: /sys/bus/platform/devices/ACPI000E:00/dc_status
+Date: March 2018
+Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+
+Description:
+ (RW,optional) The DC alarm status.
+
+ This attribute is only present if the TAD supports a separate
+ DC timer.
+
+ It is analogous to the ac_status attribute.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
index d548eaac230a..40f29a01fd14 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
+++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
@@ -3,8 +3,9 @@ Date: April 2010
Contact: Fabien Chouteau <fabien.chouteau@barco.com>
Description:
Show the suspend state of an USB composite gadget.
- 1 -> suspended
- 0 -> resumed
+
+ - 1 -> suspended
+ - 0 -> resumed
(_UDC_ is the name of the USB Device Controller driver)
@@ -17,5 +18,6 @@ Description:
Storage mode.
Possible values are:
- 1 -> ignore the FUA flag
- 0 -> obey the FUA flag
+
+ - 1 -> ignore the FUA flag
+ - 0 -> obey the FUA flag
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3
index 8aa36716882f..378c42694bfb 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-docg3
+++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3
@@ -9,8 +9,10 @@ Description:
The protection has information embedded whether it blocks reads,
writes or both.
The result is:
- 0 -> the DPS is not keylocked
- 1 -> the DPS is keylocked
+
+ - 0 -> the DPS is not keylocked
+ - 1 -> the DPS is keylocked
+
Users: None identified so far.
What: /sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key
@@ -27,8 +29,12 @@ Description:
Entering the correct value toggle the lock, and can be observed
through f[0-3]_dps[01]_is_keylocked.
Possible values are:
+
- 8 bytes
+
Typical values are:
+
- "00000000"
- "12345678"
+
Users: None identified so far.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-dock b/Documentation/ABI/testing/sysfs-devices-platform-dock
new file mode 100644
index 000000000000..411c174de830
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-dock
@@ -0,0 +1,39 @@
+What: /sys/devices/platform/dock.<N>/docked
+Date: Dec, 2006
+KernelVersion: 2.6.19
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Value 1 or 0 indicates whether the software believes the
+ laptop is docked in a docking station.
+
+What: /sys/devices/platform/dock.<N>/undock
+Date: Dec, 2006
+KernelVersion: 2.6.19
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (WO) Writing to this file causes the software to initiate an
+ undock request to the firmware.
+
+What: /sys/devices/platform/dock.<N>/uid
+Date: Feb, 2007
+KernelVersion: v2.6.21
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Displays the docking station the laptop is docked to.
+
+What: /sys/devices/platform/dock.<N>/flags
+Date: May, 2007
+KernelVersion: v2.6.21
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Show dock station flags, useful for checking if undock
+ request has been made by the user (from the immediate_undock
+ option).
+
+What: /sys/devices/platform/dock.<N>/type
+Date: Aug, 2008
+KernelVersion: v2.6.27
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Display the dock station type- dock_station, ata_bay or
+ battery_bay.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ipmi b/Documentation/ABI/testing/sysfs-devices-platform-ipmi
new file mode 100644
index 000000000000..07df0ddc0b69
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-ipmi
@@ -0,0 +1,242 @@
+What: /sys/devices/platform/ipmi_bmc.*/firmware_revision
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) The major and minor revision of the firmware.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/aux_firmware_revision
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Holds additional information about the firmware revision,
+ such as boot block or internal data structure version numbers.
+ The meanings of the numbers are specific to the vendor
+ identified by Manufacturer ID.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/revision
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Device revision. Useful for identifying if significant
+ hardware changes have been made to the implementation of the
+ management controller.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/provides_device_sdrs
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Indicates whether device provides device sensor data
+ records (1) or not (0).
+
+
+What: /sys/devices/platform/ipmi_bmc.*/device_id
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Device id is specified by the manufacturer identified by
+ the Manufacturer ID field. This field allows controller specific
+ software to identify the unique application command, OEM
+ fields, and functionality that are provided by the controller
+
+
+What: /sys/devices/platform/ipmi_bmc.*/additional_device_support
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Lists the IPMI ‘logical device’ commands and functions
+ that the controller supports that are in addition to the
+ mandatory IPM and Application commands.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/ipmi_version
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Displays the IPMI Command Specification Version.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/manufacturer_id
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Identifies the manufacturer responsible for the
+ specification of functionality of the vendor (OEM)-specific
+ commands, codes, and interfaces used in the controller.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/product_id
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Displays a number that identifies a particular system,
+ module, add-in card, or board set. The number is specified
+ according to the manufacturer given by Manufacturer ID.
+
+For detailed definitions of the above attributes, refer to section 20.1 'Get
+Device ID Command' of the IPMI specification v2.0.
+
+
+What: /sys/devices/platform/ipmi_bmc.*/guid
+Date: Mar, 2006
+KernelVersion: v2.6.17
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) A GUID (Globally Unique ID), also referred to as a UUID
+ (Universally Unique Identifier), for the management controller,
+ as described in section 20.8 'Get Device GUID Command' of the
+ IPMI specification v2.0.
+
+
+What: /sys/devices/platform/ipmi_si.*/type
+Date: Sep, 2017
+KernelVersion: v4.15
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) The device interface for IPMI "kcs", "smic", "bt" or
+ "invalid"
+
+What: /sys/devices/platform/ipmi_si.*/idles
+What: /sys/devices/platform/ipmi_si.*/watchdog_pretimeouts
+What: /sys/devices/platform/ipmi_si.*/complete_transactions
+What: /sys/devices/platform/ipmi_si.*/events
+What: /sys/devices/platform/ipmi_si.*/interrupts
+What: /sys/devices/platform/ipmi_si.*/hosed_count
+What: /sys/devices/platform/ipmi_si.*/long_timeouts
+What: /sys/devices/platform/ipmi_si.*/flag_fetches
+What: /sys/devices/platform/ipmi_si.*/attentions
+What: /sys/devices/platform/ipmi_si.*/incoming_messages
+What: /sys/devices/platform/ipmi_si.*/short_timeouts
+Date: Sep, 2017
+KernelVersion: v4.15
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+
+ ====================== ========================================
+ idles (RO) Number of times the interface was
+ idle while being polled.
+
+ watchdog_pretimeouts (RO) Number of watchdog pretimeouts.
+
+ complete_transactions (RO) Number of completed messages.
+
+ events (RO) Number of IPMI events received from
+ the hardware.
+
+ interrupts (RO) Number of interrupts the driver
+ handled.
+
+ hosed_count (RO) Number of times the hardware didn't
+ follow the state machine.
+
+ long_timeouts (RO) Number of times the driver
+ requested a timer while nothing was in
+ progress.
+
+ flag_fetches (RO) Number of times the driver
+ requested flags from the hardware.
+
+ attentions (RO) Number of time the driver got an
+ ATTN from the hardware.
+
+ incoming_messages (RO) Number of asynchronous messages
+ received.
+
+ short_timeouts (RO) Number of times the driver
+ requested a timer while an operation was
+ in progress.
+ ====================== ========================================
+
+
+What: /sys/devices/platform/ipmi_si.*/interrupts_enabled
+Date: Sep, 2017
+KernelVersion: v4.15
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Indicates whether interrupts are enabled or not. The driver
+ disables interrupts when it gets into a situation where it
+ cannot handle messages due to lack of memory. Once that
+ situation clears up, it will re-enable interrupts.
+
+
+What: /sys/devices/platform/ipmi_si.*/params
+Date: Sep, 2017
+KernelVersion: v4.15
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ [to be documented]
+
+
+What: /sys/devices/platform/dmi-ipmi-ssif.*/type
+Date: Sep, 2017
+KernelVersion: v4.15
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ (RO) Shows the IMPI device interface type - "ssif" here.
+
+
+What: /sys/devices/platform/dmi-ipmi-ssif.*/hosed
+What: /sys/devices/platform/dmi-ipmi-ssif.*/alerts
+What: /sys/devices/platform/dmi-ipmi-ssif.*/sent_messages
+What: /sys/devices/platform/dmi-ipmi-ssif.*/sent_messages_parts
+What: /sys/devices/platform/dmi-ipmi-ssif.*/received_messages
+What: /sys/devices/platform/dmi-ipmi-ssif.*/received_message_parts
+What: /sys/devices/platform/dmi-ipmi-ssif.*/events
+What: /sys/devices/platform/dmi-ipmi-ssif.*/watchdog_pretimeouts
+What: /sys/devices/platform/dmi-ipmi-ssif.*/flag_fetches
+What: /sys/devices/platform/dmi-ipmi-ssif.*/send_retries
+What: /sys/devices/platform/dmi-ipmi-ssif.*/receive_retries
+What: /sys/devices/platform/dmi-ipmi-ssif.*/send_errors
+What: /sys/devices/platform/dmi-ipmi-ssif.*/receive_errors
+Date: Sep, 2017
+KernelVersion: v4.15
+Contact: openipmi-developer@lists.sourceforge.net
+Description:
+ ====================== ========================================
+ hosed (RO) Number of times the hardware didn't
+ follow the state machine.
+
+ alerts (RO) Number of alerts received.
+
+ sent_messages (RO) Number of total messages sent.
+
+ sent_message_parts (RO) Number of message parts sent.
+ Messages may be broken into parts if
+ they are long.
+
+ received_messages (RO) Number of message responses
+ received.
+
+ received_message_parts (RO) Number of message fragments
+ received.
+
+ events (RO) Number of received events.
+
+ watchdog_pretimeouts (RO) Number of watchdog pretimeouts.
+
+ flag_fetches (RO) Number of times a flag fetch was
+ requested.
+
+ send_retries (RO) Number of time a message was
+ retried.
+
+ receive_retries (RO) Number of times the receive of a
+ message was retried.
+
+ send_errors (RO) Number of times the send of a
+ message failed.
+
+ receive_errors (RO) Number of errors in receiving
+ messages.
+ ====================== ========================================
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs b/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs
new file mode 100644
index 000000000000..d1b3a95a5518
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-kunpeng_hccs
@@ -0,0 +1,126 @@
+What: /sys/devices/platform/HISI04Bx:00/chipX/all_linked
+What: /sys/devices/platform/HISI04Bx:00/chipX/linked_full_lane
+What: /sys/devices/platform/HISI04Bx:00/chipX/crc_err_cnt
+Date: November 2023
+KernelVersion: 6.6
+Contact: Huisong Li <lihuisong@huawei.com>
+Description:
+ The /sys/devices/platform/HISI04Bx:00/chipX/ directory
+ contains read-only attributes exposing some summarization
+ information of all HCCS ports under a specified chip.
+ The X in 'chipX' indicates the Xth chip on platform.
+
+ There are following attributes in this directory:
+
+ ================= ==== =========================================
+ all_linked: (RO) if all enabled ports on this chip are
+ linked (bool).
+ linked_full_lane: (RO) if all linked ports on this chip are full
+ lane (bool).
+ crc_err_cnt: (RO) total CRC err count for all ports on this
+ chip.
+ ================= ==== =========================================
+
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/all_linked
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/linked_full_lane
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/crc_err_cnt
+Date: November 2023
+KernelVersion: 6.6
+Contact: Huisong Li <lihuisong@huawei.com>
+Description:
+ The /sys/devices/platform/HISI04Bx:00/chipX/dieY/ directory
+ contains read-only attributes exposing some summarization
+ information of all HCCS ports under a specified die.
+ The Y in 'dieY' indicates the hardware id of the die on chip who
+ has chip id X.
+
+ There are following attributes in this directory:
+
+ ================= ==== =========================================
+ all_linked: (RO) if all enabled ports on this die are
+ linked (bool).
+ linked_full_lane: (RO) if all linked ports on this die are full
+ lane (bool).
+ crc_err_cnt: (RO) total CRC err count for all ports on this
+ die.
+ ================= ==== =========================================
+
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/type
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/lane_mode
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/enable
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/cur_lane_num
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/link_fsm
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/lane_mask
+What: /sys/devices/platform/HISI04Bx:00/chipX/dieY/hccsN/crc_err_cnt
+Date: November 2023
+KernelVersion: 6.6
+Contact: Huisong Li <lihuisong@huawei.com>
+Description:
+ The /sys/devices/platform/HISI04Bx/chipX/dieX/hccsN/ directory
+ contains read-only attributes exposing information about
+ a HCCS port. The N value in 'hccsN' indicates this port id.
+ The X in 'chipX' indicates the ID of the chip to which the
+ HCCS port belongs. For example, X ranges from to 'n - 1' if the
+ chip number on platform is n.
+ The Y in 'dieY' indicates the hardware id of the die to which
+ the hccs port belongs.
+ Note: type, lane_mode and enable are fixed attributes on running
+ platform.
+
+ The HCCS port have the following attributes:
+
+ ============= ==== =============================================
+ type: (RO) port type (string), e.g. HCCS-v1 -> H32
+ lane_mode: (RO) the lane mode of this port (string), e.g. x8
+ enable: (RO) indicate if this port is enabled (bool).
+ cur_lane_num: (RO) current lane number of this port.
+ link_fsm: (RO) link finite state machine of this port.
+ lane_mask: (RO) current lane mask of this port, every bit
+ indicates a lane.
+ crc_err_cnt: (RO) CRC err count on this port.
+ ============= ==== =============================================
+
+What: /sys/devices/platform/HISI04Bx:00/used_types
+Date: August 2024
+KernelVersion: 6.12
+Contact: Huisong Li <lihuisong@huawei.com>
+Description:
+ This interface is used to show all HCCS types used on the
+ platform, like, HCCS-v1, HCCS-v2 and so on.
+
+What: /sys/devices/platform/HISI04Bx:00/available_inc_dec_lane_types
+What: /sys/devices/platform/HISI04Bx:00/dec_lane_of_type
+What: /sys/devices/platform/HISI04Bx:00/inc_lane_of_type
+Date: August 2024
+KernelVersion: 6.12
+Contact: Huisong Li <lihuisong@huawei.com>
+Description:
+ These interfaces under /sys/devices/platform/HISI04Bx/ are
+ used to support the low power consumption feature of some
+ HCCS types by changing the number of lanes used. The interfaces
+ changing the number of lanes used are 'dec_lane_of_type' and
+ 'inc_lane_of_type' which require root privileges. These
+ interfaces aren't exposed if no HCCS type on platform support
+ this feature. Please note that decreasing lane number is only
+ allowed if all the specified HCCS ports are not busy.
+
+ The low power consumption interfaces are as follows:
+
+ ============================= ==== ================================
+ available_inc_dec_lane_types: (RO) available HCCS types (string) to
+ increase and decrease the number
+ of lane used, e.g. HCCS-v2.
+ dec_lane_of_type: (WO) input HCCS type supported
+ decreasing lane to decrease the
+ used lane number of all specified
+ HCCS type ports on platform to
+ the minimum.
+ You can query the 'cur_lane_num'
+ to get the minimum lane number
+ after executing successfully.
+ inc_lane_of_type: (WO) input HCCS type supported
+ increasing lane to increase the
+ used lane number of all specified
+ HCCS type ports on platform to
+ the full lane state.
+ ============================= ==== ================================
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
index 2107082426da..e45ac2e865d5 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
+++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
@@ -17,10 +17,10 @@ Description:
to overlay planes.
Selects the composition mode for the overlay. Possible values
- are
+ are:
- 0 - Alpha Blending
- 1 - ROP3
+ - 0 - Alpha Blending
+ - 1 - ROP3
What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position
Date: May 2012
@@ -30,7 +30,7 @@ Description:
to overlay planes.
Stores the x,y overlay position on the display in pixels. The
- position format is `[0-9]+,[0-9]+'.
+ position format is `[0-9]+,[0-9]+`.
What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3
Date: May 2012
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-soc-ipa b/Documentation/ABI/testing/sysfs-devices-platform-soc-ipa
new file mode 100644
index 000000000000..364b1ba41242
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-soc-ipa
@@ -0,0 +1,114 @@
+What: /sys/devices/platform/soc@X/XXXXXXX.ipa/
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The /sys/devices/platform/soc@X/XXXXXXX.ipa/ directory
+ contains read-only attributes exposing information about
+ an IPA device. The X values could vary, but are typically
+ "soc@0/1e40000.ipa".
+
+What: .../XXXXXXX.ipa/version
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/version file contains the IPA hardware
+ version, as a period-separated set of two or three integers
+ (e.g., "3.5.1" or "4.2").
+
+What: .../XXXXXXX.ipa/feature/
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/feature/ directory contains a set of
+ attributes describing features implemented by the IPA
+ hardware.
+
+What: .../XXXXXXX.ipa/feature/rx_offload
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/feature/rx_offload file contains a
+ string indicating the type of receive checksum offload
+ that is supported by the hardware. The possible values
+ are "MAPv4" or "MAPv5".
+
+What: .../XXXXXXX.ipa/feature/tx_offload
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/feature/tx_offload file contains a
+ string indicating the type of transmit checksum offload
+ that is supported by the hardware. The possible values
+ are "MAPv4" or "MAPv5".
+
+What: .../XXXXXXX.ipa/endpoint_id/
+Date: July 2022
+KernelVersion: v5.19
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/endpoint_id/ directory contains
+ attributes that define IDs associated with IPA
+ endpoints. The "rx" or "tx" in an endpoint name is
+ from the perspective of the AP. An endpoint ID is a
+ small unsigned integer.
+
+What: .../XXXXXXX.ipa/endpoint_id/modem_rx
+Date: July 2022
+KernelVersion: v5.19
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/endpoint_id/modem_rx file contains
+ the ID of the AP endpoint on which packets originating
+ from the embedded modem are received.
+
+What: .../XXXXXXX.ipa/endpoint_id/modem_tx
+Date: July 2022
+KernelVersion: v5.19
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/endpoint_id/modem_tx file contains
+ the ID of the AP endpoint on which packets destined
+ for the embedded modem are sent.
+
+What: .../XXXXXXX.ipa/endpoint_id/monitor_rx
+Date: July 2022
+KernelVersion: v5.19
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/endpoint_id/monitor_rx file contains
+ the ID of the AP endpoint on which IPA "monitor" data is
+ received. The monitor endpoint supplies replicas of
+ packets that enter the IPA hardware for processing.
+ Each replicated packet is preceded by a fixed-size "ODL"
+ header (see .../XXXXXXX.ipa/feature/monitor, above).
+ Large packets are truncated, to reduce the bandwidth
+ required to provide the monitor function.
+
+What: .../XXXXXXX.ipa/modem/
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/modem/ directory contains attributes
+ describing properties of the modem embedded in the SoC.
+
+What: .../XXXXXXX.ipa/modem/rx_endpoint_id
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/modem/rx_endpoint_id file duplicates
+ the value found in .../XXXXXXX.ipa/endpoint_id/modem_rx.
+
+What: .../XXXXXXX.ipa/modem/tx_endpoint_id
+Date: June 2021
+KernelVersion: v5.14
+Contact: Alex Elder <elder@kernel.org>
+Description:
+ The .../XXXXXXX.ipa/modem/tx_endpoint_id file duplicates
+ the value found in .../XXXXXXX.ipa/endpoint_id/modem_tx.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
new file mode 100644
index 000000000000..ee253b033280
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
@@ -0,0 +1,174 @@
+ Intel Stratix10 Remote System Update (RSU) device attributes
+
+What: /sys/devices/platform/stratix10-rsu.0/current_image
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the address in flash of currently running image.
+
+What: /sys/devices/platform/stratix10-rsu.0/fail_image
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the address in flash of failed image.
+
+What: /sys/devices/platform/stratix10-rsu.0/state
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the state of RSU system.
+ The state field has two parts: major error code in
+ upper 16 bits and minor error code in lower 16 bits.
+
+ b[15:0]
+ Currently used only when major error is 0xF006
+ (CPU watchdog timeout), in which case the minor
+ error code is the value reported by CPU to
+ firmware through the RSU notify command before
+ the watchdog timeout occurs.
+
+ b[31:16]
+ 0xF001 bitstream error
+ 0xF002 hardware access failure
+ 0xF003 bitstream corruption
+ 0xF004 internal error
+ 0xF005 device error
+ 0xF006 CPU watchdog timeout
+ 0xF007 internal unknown error
+
+What: /sys/devices/platform/stratix10-rsu.0/version
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the version number of RSU firmware. 19.3 or late
+ version includes information about the firmware which
+ reported the error.
+
+ pre 19.3:
+ b[31:0]
+ 0x0 version number
+
+ 19.3 or late:
+ b[15:0]
+ 0x1 version number
+ b[31:16]
+ 0x0 no error
+ 0x0DCF Decision CMF error
+ 0x0ACF Application CMF error
+
+What: /sys/devices/platform/stratix10-rsu.0/error_location
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the error offset inside the image that failed.
+
+What: /sys/devices/platform/stratix10-rsu.0/error_details
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) error code.
+
+What: /sys/devices/platform/stratix10-rsu.0/retry_counter
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) the current image's retry counter, which is used by
+ user to know how many times the images is still allowed
+ to reload itself before giving up and starting RSU
+ fail-over flow.
+
+What: /sys/devices/platform/stratix10-rsu.0/reboot_image
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (WO) the address in flash of image to be loaded on next
+ reboot command.
+
+What: /sys/devices/platform/stratix10-rsu.0/notify
+Date: August 2019
+KernelVersion: 5.4
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (WO) client to notify firmware with different actions.
+
+ b[15:0]
+ inform firmware the current software execution
+ stage.
+
+ == ===========================================
+ 0 the first stage bootloader didn't run or
+ didn't reach the point of launching second
+ stage bootloader.
+ 1 failed in second bootloader or didn't get
+ to the point of launching the operating
+ system.
+ 2 both first and second stage bootloader ran
+ and the operating system launch was
+ attempted.
+ == ===========================================
+
+ b[16]
+ == ===========================================
+ 1 firmware to reset current image retry
+ counter.
+ 0 no action.
+ == ===========================================
+
+ b[17]
+ == ===========================================
+ 1 firmware to clear RSU log
+ 0 no action.
+ == ===========================================
+
+ b[18]
+ this is negative logic
+
+ == ===========================================
+ 1 no action
+ 0 firmware record the notify code defined
+ in b[15:0].
+ == ===========================================
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf0
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 0 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf1
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 1 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf2
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 2 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/dcmf3
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) Decision firmware copy 3 version information.
+
+What: /sys/devices/platform/stratix10-rsu.0/max_retry
+Date: June 2020
+KernelVersion: 5.8
+Contact: Richard Gong <richard.gong@linux.intel.com>
+Description:
+ (RO) max retry parameter is stored in the firmware
+ decision IO section, as a byte located at offset 0x18c.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-trackpoint b/Documentation/ABI/testing/sysfs-devices-platform-trackpoint
new file mode 100644
index 000000000000..df11901a6b3d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-trackpoint
@@ -0,0 +1,115 @@
+What: /sys/devices/platform/i8042/.../sensitivity
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Trackpoint sensitivity.
+
+What: /sys/devices/platform/i8042/.../intertia
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Negative inertia factor. High values cause the cursor to
+ snap backward when the trackpoint is released.
+
+What: /sys/devices/platform/i8042/.../reach
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Backup range for z-axis press.
+
+What: /sys/devices/platform/i8042/.../draghys
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) The drag hysteresis controls how hard it is to drag with
+ z-axis pressed.
+
+What: /sys/devices/platform/i8042/.../mindrag
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Minimum amount of force needed to trigger dragging.
+
+What: /sys/devices/platform/i8042/.../speed
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Speed of the trackpoint cursor.
+
+What: /sys/devices/platform/i8042/.../thresh
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Minimum value for z-axis force required to trigger a press
+ or release, relative to the running average.
+
+What: /sys/devices/platform/i8042/.../upthresh
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) The offset from the running average required to generate a
+ select (click) on z-axis on release.
+
+What: /sys/devices/platform/i8042/.../ztime
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) This attribute determines how sharp a press has to be in
+ order to be recognized.
+
+What: /sys/devices/platform/i8042/.../jenks
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Minimum curvature in degrees required to generate a double
+ click without a release.
+
+What: /sys/devices/platform/i8042/.../skipback
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) When the skipback bit is set, backup cursor movement during
+ releases from drags will be suppressed. The default value for
+ this bit is 0.
+
+What: /sys/devices/platform/i8042/.../ext_dev
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Disable (0) or enable (1) external pointing device.
+
+What: /sys/devices/platform/i8042/.../press_to_select
+Date: Aug, 2005
+KernelVersion: 2.6.14
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Writing a value of 1 to this file will enable the Press to
+ Select functions like tapping the control stick to simulate a
+ left click, and writing 0 will disable it.
+
+What: /sys/devices/platform/i8042/.../drift_time
+Date: Dec, 2014
+KernelVersion: 3.19
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) This parameter controls the period of time to test for a
+ ‘hands off’ condition (i.e. when no force is applied) before a
+ drift (noise) calibration occurs.
+
+ IBM Trackpoints have a feature to compensate for drift by
+ recalibrating themselves periodically. By default, if for 0.5
+ seconds there is no change in position, it's used as the new
+ zero. This duration is too low. Often, the calibration happens
+ when the trackpoint is in fact being used.
diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power
index 676fdf5f2a99..9bf7c8a267c5 100644
--- a/Documentation/ABI/testing/sysfs-devices-power
+++ b/Documentation/ABI/testing/sysfs-devices-power
@@ -1,6 +1,6 @@
What: /sys/devices/.../power/
Date: January 2009
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../power directory contains attributes
allowing the user space to check and modify some power
@@ -8,7 +8,7 @@ Description:
What: /sys/devices/.../power/wakeup
Date: January 2009
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../power/wakeup attribute allows the user
space to check if the device is enabled to wake up the system
@@ -34,7 +34,7 @@ Description:
What: /sys/devices/.../power/control
Date: January 2009
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../power/control attribute allows the user
space to control the run-time power management of the device.
@@ -53,10 +53,10 @@ Description:
What: /sys/devices/.../power/async
Date: January 2009
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../async attribute allows the user space to
- enable or diasble the device's suspend and resume callbacks to
+ enable or disable the device's suspend and resume callbacks to
be executed asynchronously (ie. in separate threads, in parallel
with the main suspend/resume thread) during system-wide power
transitions (eg. suspend to RAM, hibernation).
@@ -79,7 +79,7 @@ Description:
What: /sys/devices/.../power/wakeup_count
Date: September 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_count attribute contains the number
of signaled wakeup events associated with the device. This
@@ -90,7 +90,7 @@ Description:
What: /sys/devices/.../power/wakeup_active_count
Date: September 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_active_count attribute contains the
number of times the processing of wakeup events associated with
@@ -102,7 +102,7 @@ Description:
What: /sys/devices/.../power/wakeup_abort_count
Date: February 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_abort_count attribute contains the
number of times the processing of a wakeup event associated with
@@ -114,7 +114,7 @@ Description:
What: /sys/devices/.../power/wakeup_expire_count
Date: February 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_expire_count attribute contains the
number of times a wakeup event associated with the device has
@@ -126,7 +126,7 @@ Description:
What: /sys/devices/.../power/wakeup_active
Date: September 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_active attribute contains either 1,
or 0, depending on whether or not a wakeup event associated with
@@ -138,7 +138,7 @@ Description:
What: /sys/devices/.../power/wakeup_total_time_ms
Date: September 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_total_time_ms attribute contains
the total time of processing wakeup events associated with the
@@ -149,7 +149,7 @@ Description:
What: /sys/devices/.../power/wakeup_max_time_ms
Date: September 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_max_time_ms attribute contains
the maximum time of processing a single wakeup event associated
@@ -161,7 +161,7 @@ Description:
What: /sys/devices/.../power/wakeup_last_time_ms
Date: September 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_last_time_ms attribute contains
the value of the monotonic clock corresponding to the time of
@@ -173,7 +173,7 @@ Description:
What: /sys/devices/.../power/wakeup_prevent_sleep_time_ms
Date: February 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../wakeup_prevent_sleep_time_ms attribute
contains the total time the device has been preventing
@@ -203,7 +203,7 @@ Description:
What: /sys/devices/.../power/pm_qos_resume_latency_us
Date: March 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../power/pm_qos_resume_latency_us attribute
contains the PM QoS resume latency limit for the given device,
@@ -211,7 +211,9 @@ Description:
device, after it has been suspended at run time, from a resume
request to the moment the device will be ready to process I/O,
in microseconds. If it is equal to 0, however, this means that
- the PM QoS resume latency may be arbitrary.
+ the PM QoS resume latency may be arbitrary and the special value
+ "n/a" means that user space cannot accept any resume latency at
+ all for the given device.
Not all drivers support this attribute. If it isn't supported,
it is not present.
@@ -221,7 +223,7 @@ Description:
What: /sys/devices/.../power/pm_qos_latency_tolerance_us
Date: January 2014
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../power/pm_qos_latency_tolerance_us attribute
contains the PM QoS active state latency tolerance limit for the
@@ -246,7 +248,7 @@ Description:
What: /sys/devices/.../power/pm_qos_no_power_off
Date: September 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/devices/.../power/pm_qos_no_power_off attribute
is used for manipulating the PM QoS "no power off" flag. If
@@ -259,18 +261,47 @@ Description:
This attribute has no effect on system-wide suspend/resume and
hibernation.
-What: /sys/devices/.../power/pm_qos_remote_wakeup
-Date: September 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+What: /sys/devices/.../power/runtime_status
+Date: April 2010
+Contact: Rafael J. Wysocki <rafael@kernel.org>
+Description:
+ The /sys/devices/.../power/runtime_status attribute contains
+ the current runtime PM status of the device, which may be
+ "suspended", "suspending", "resuming", "active", "error" (fatal
+ error), or "unsupported" (runtime PM is disabled).
+
+What: /sys/devices/.../power/runtime_active_time
+Date: Jul 2010
+Contact: Arjan van de Ven <arjan@linux.intel.com>
Description:
- The /sys/devices/.../power/pm_qos_remote_wakeup attribute
- is used for manipulating the PM QoS "remote wakeup required"
- flag. If set, this flag indicates to the kernel that the
- device is a source of user events that have to be signaled from
- its low-power states.
+ Reports the total time that the device has been active, in
+ milliseconds. Used for runtime PM statistics.
- Not all drivers support this attribute. If it isn't supported,
- it is not present.
+What: /sys/devices/.../power/runtime_suspended_time
+Date: Jul 2010
+Contact: Arjan van de Ven <arjan@linux.intel.com>
+Description:
+ Reports total time that the device has been suspended, in
+ milliseconds. Used for runtime PM statistics.
+
+What: /sys/devices/.../power/runtime_usage
+Date: Apr 2010
+Contact: Dominik Brodowski <linux@dominikbrodowski.net>
+Description:
+ Reports the runtime PM usage count of a device.
+
+What: /sys/devices/.../power/runtime_enabled
+Date: Apr 2010
+Contact: Dominik Brodowski <linux@dominikbrodowski.net>
+Description:
+ Is runtime PM enabled for this device?
+ States are "enabled", "disabled", "forbidden" or a
+ combination of the latter two.
+
+What: /sys/devices/.../power/runtime_active_kids
+Date: Apr 2010
+Contact: Dominik Brodowski <linux@dominikbrodowski.net>
+Description:
+ Reports the runtime PM children usage count of a device, or
+ 0 if the children will be ignored.
- This attribute has no effect on system-wide suspend/resume and
- hibernation.
diff --git a/Documentation/ABI/testing/sysfs-devices-removable b/Documentation/ABI/testing/sysfs-devices-removable
new file mode 100644
index 000000000000..754ecb4587ca
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-removable
@@ -0,0 +1,20 @@
+What: /sys/devices/.../removable
+Date: May 2021
+Contact: Rajat Jain <rajatxjain@gmail.com>
+Description:
+ Information about whether a given device can be removed from the
+ platform by the user. This is determined by its subsystem in a
+ bus / platform-specific way. This attribute is only present for
+ devices that can support determining such information:
+
+ =========== ===================================================
+ "removable" device can be removed from the platform by the user
+ "fixed" device is fixed to the platform / cannot be removed
+ by the user.
+ "unknown" The information is unavailable / cannot be deduced.
+ =========== ===================================================
+
+ Currently this is only supported by USB (which infers the
+ information from a combination of hub descriptor bits and
+ platform-specific data such as ACPI) and PCI (which gets this
+ from ACPI / device tree).
diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc
index 6d9cc253f2b2..5269808ec35f 100644
--- a/Documentation/ABI/testing/sysfs-devices-soc
+++ b/Documentation/ABI/testing/sysfs-devices-soc
@@ -1,6 +1,6 @@
What: /sys/devices/socX
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
The /sys/devices/ directory contains a sub-directory for each
System-on-Chip (SoC) device on a running platform. Information
@@ -14,42 +14,79 @@ Description:
What: /sys/devices/socX/machine
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
Read-only attribute common to all SoCs. Contains the SoC machine
name (e.g. Ux500).
What: /sys/devices/socX/family
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
Read-only attribute common to all SoCs. Contains SoC family name
(e.g. DB8500).
+ On many of ARM based silicon with SMCCC v1.2+ compliant firmware
+ this will contain the JEDEC JEP106 manufacturer’s identification
+ code. The format is "jep106:XXYY" where XX is identity code and
+ YY is continuation code.
+
+ This manufacturer’s identification code is defined by one
+ or more eight (8) bit fields, each consisting of seven (7)
+ data bits plus one (1) odd parity bit. It is a single field,
+ limiting the possible number of vendors to 126. To expand
+ the maximum number of identification codes, a continuation
+ scheme has been defined.
+
+ The specified mechanism is that an identity code of 0x7F
+ represents the "continuation code" and implies the presence
+ of an additional identity code field, and this mechanism
+ may be extended to multiple continuation codes followed
+ by the manufacturer's identity code.
+
+ For example, ARM has identity code 0x7F 0x7F 0x7F 0x7F 0x3B,
+ which is code 0x3B on the fifth 'page'. This is shortened
+ as JEP106 identity code of 0x3B and a continuation code of
+ 0x4 to represent the four continuation codes preceding the
+ identity code.
+
+What: /sys/devices/socX/serial_number
+Date: January 2019
+contact: Bjorn Andersson <bjorn.andersson@linaro.org>
+Description:
+ Read-only attribute supported by most SoCs. Contains the SoC's
+ serial number, if available.
+
What: /sys/devices/socX/soc_id
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
Read-only attribute supported by most SoCs. In the case of
ST-Ericsson's chips this contains the SoC serial number.
+ On many of ARM based silicon with SMCCC v1.2+ compliant firmware
+ this will contain the SOC ID appended to the family attribute
+ to ensure there is no conflict in this namespace across various
+ vendors. The format is "jep106:XXYY:ZZZZ" where XX is identity
+ code, YY is continuation code and ZZZZ is the SOC ID.
+
What: /sys/devices/socX/revision
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
Read-only attribute supported by most SoCs. Contains the SoC's
manufacturing revision number.
What: /sys/devices/socX/process
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
Read-only attribute supported ST-Ericsson's silicon. Contains the
the process by which the silicon chip was manufactured.
What: /sys/bus/soc
Date: January 2012
-contact: Lee Jones <lee.jones@linaro.org>
+contact: Lee Jones <lee@kernel.org>
Description:
The /sys/bus/soc/ directory contains the usual sub-folders
expected under most buses. /sys/bus/soc/devices is of particular
diff --git a/Documentation/ABI/testing/sysfs-devices-software_node b/Documentation/ABI/testing/sysfs-devices-software_node
new file mode 100644
index 000000000000..85df37de359f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-software_node
@@ -0,0 +1,10 @@
+What: /sys/devices/.../software_node/
+Date: January 2019
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ This directory contains the details about the device that are
+ assigned in kernel (i.e. software), as opposed to the
+ firmware_node directory which contains the details that are
+ assigned for the device in firmware. The main attributes in the
+ directory will show the properties the device has, and the
+ relationship it has to some of the other devices.
diff --git a/Documentation/ABI/testing/sysfs-devices-state_synced b/Documentation/ABI/testing/sysfs-devices-state_synced
new file mode 100644
index 000000000000..c64636ddac41
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-state_synced
@@ -0,0 +1,29 @@
+What: /sys/devices/.../state_synced
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../state_synced attribute is only present for
+ devices whose bus types or driver provides the .sync_state()
+ callback. The number read from it (0 or 1) reflects the value
+ of the device's 'state_synced' field. A value of 0 means the
+ .sync_state() callback hasn't been called yet. A value of 1
+ means the .sync_state() callback has been called.
+
+ Generally, if a device has sync_state() support and has some of
+ the resources it provides enabled at the time the kernel starts
+ (Eg: enabled by hardware reset or bootloader or anything that
+ run before the kernel starts), then it'll keep those resources
+ enabled and in a state that's compatible with the state they
+ were in at the start of the kernel. The device will stop doing
+ this only when the sync_state() callback has been called --
+ which happens only when all its consumer devices are registered
+ and have probed successfully. Resources that were left disabled
+ at the time the kernel starts are not affected or limited in
+ any way by sync_state() callbacks.
+
+ Writing "1" to this file will force a call to the device's
+ sync_state() function if it hasn't been called already. The
+ sync_state() call happens independent of the state of the
+ consumer devices.
+
+
diff --git a/Documentation/ABI/testing/sysfs-devices-supplier b/Documentation/ABI/testing/sysfs-devices-supplier
new file mode 100644
index 000000000000..207f5972e98d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-supplier
@@ -0,0 +1,9 @@
+What: /sys/devices/.../supplier:<supplier>
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../supplier:<supplier> are symlinks to device
+ links where this device is the consumer. <supplier> denotes the
+ name of the supplier in that device link and is of the form
+ bus:device name. There can be zero or more of these symlinks
+ for a given device.
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 99983e67c13c..3a05604c21bf 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -7,7 +7,7 @@ Description:
Individual CPU attributes are contained in subdirectories
named by the kernel's logical CPU number, e.g.:
- /sys/devices/system/cpu/cpu#/
+ /sys/devices/system/cpu/cpuX/
What: /sys/devices/system/cpu/kernel_max
/sys/devices/system/cpu/offline
@@ -34,7 +34,7 @@ Description: CPU topology files that describe kernel limits related to
present: cpus that have been identified as being present in
the system.
- See Documentation/cputopology.txt for more information.
+ See Documentation/admin-guide/cputopology.rst for more information.
What: /sys/devices/system/cpu/probe
@@ -50,10 +50,10 @@ Description: Dynamic addition and removal of CPU's. This is not hotplug
architecture specific.
release: writes to this file dynamically remove a CPU from
- the system. Information writtento the file to remove CPU's
+ the system. Information written to the file to remove CPU's
is architecture specific.
-What: /sys/devices/system/cpu/cpu#/node
+What: /sys/devices/system/cpu/cpuX/node
Date: October 2009
Contact: Linux memory management mailing list <linux-mm@kvack.org>
Description: Discover NUMA node a CPU belongs to
@@ -67,47 +67,51 @@ Description: Discover NUMA node a CPU belongs to
/sys/devices/system/cpu/cpu42/node2 -> ../../node/node2
-What: /sys/devices/system/cpu/cpu#/topology/core_id
- /sys/devices/system/cpu/cpu#/topology/core_siblings
- /sys/devices/system/cpu/cpu#/topology/core_siblings_list
- /sys/devices/system/cpu/cpu#/topology/physical_package_id
- /sys/devices/system/cpu/cpu#/topology/thread_siblings
- /sys/devices/system/cpu/cpu#/topology/thread_siblings_list
+What: /sys/devices/system/cpu/cpuX/topology/core_siblings
+ /sys/devices/system/cpu/cpuX/topology/core_siblings_list
+ /sys/devices/system/cpu/cpuX/topology/physical_package_id
+ /sys/devices/system/cpu/cpuX/topology/thread_siblings
+ /sys/devices/system/cpu/cpuX/topology/thread_siblings_list
+ /sys/devices/system/cpu/cpuX/topology/ppin
Date: December 2008
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
Description: CPU topology files that describe a logical CPU's relationship
to other cores and threads in the same physical package.
- One cpu# directory is created per logical CPU in the system,
+ One cpuX directory is created per logical CPU in the system,
e.g. /sys/devices/system/cpu/cpu42/.
Briefly, the files above are:
- core_id: the CPU core ID of cpu#. Typically it is the
- hardware platform's identifier (rather than the kernel's).
- The actual value is architecture and platform dependent.
-
- core_siblings: internal kernel map of cpu#'s hardware threads
+ core_siblings: internal kernel map of cpuX's hardware threads
within the same physical_package_id.
core_siblings_list: human-readable list of the logical CPU
- numbers within the same physical_package_id as cpu#.
+ numbers within the same physical_package_id as cpuX.
- physical_package_id: physical package id of cpu#. Typically
+ physical_package_id: physical package id of cpuX. Typically
corresponds to a physical socket number, but the actual value
is architecture and platform dependent.
- thread_siblings: internel kernel map of cpu#'s hardware
- threads within the same core as cpu#
+ thread_siblings: internal kernel map of cpuX's hardware
+ threads within the same core as cpuX
+
+ thread_siblings_list: human-readable list of cpuX's hardware
+ threads within the same core as cpuX
- thread_siblings_list: human-readable list of cpu#'s hardware
- threads within the same core as cpu#
+ ppin: human-readable Protected Processor Identification
+ Number of the socket the cpu# belongs to. There should be
+ one per physical_package_id. File is readable only to
+ admin.
- See Documentation/cputopology.txt for more information.
+ See Documentation/admin-guide/cputopology.rst for more information.
-What: /sys/devices/system/cpu/cpuidle/current_driver
+What: /sys/devices/system/cpu/cpuidle/available_governors
+ /sys/devices/system/cpu/cpuidle/current_driver
+ /sys/devices/system/cpu/cpuidle/current_governor
/sys/devices/system/cpu/cpuidle/current_governer_ro
+ /sys/devices/system/cpu/cpuidle/intel_c1_demotion
Date: September 2007
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
Description: Discover cpuidle policy and mechanism
@@ -117,16 +121,129 @@ Description: Discover cpuidle policy and mechanism
consumption during idle.
Idle policy (governor) is differentiated from idle mechanism
- (driver)
+ (driver).
+
+ available_governors: (RO) displays a space separated list of
+ available governors.
+
+ current_driver: (RO) displays current idle mechanism.
+
+ current_governor: (RW) displays current idle policy. Users can
+ switch the governor at runtime by writing to this file.
+
+ current_governor_ro: (RO) displays current idle policy.
+
+ intel_c1_demotion: (RW) enables/disables the C1 demotion
+ feature on Intel CPUs.
+
+ See Documentation/admin-guide/pm/cpuidle.rst,
+ Documentation/admin-guide/pm/intel_idle.rst, and
+ Documentation/driver-api/pm/cpuidle.rst for more information.
+
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/name
+ /sys/devices/system/cpu/cpuX/cpuidle/stateN/latency
+ /sys/devices/system/cpu/cpuX/cpuidle/stateN/power
+ /sys/devices/system/cpu/cpuX/cpuidle/stateN/time
+ /sys/devices/system/cpu/cpuX/cpuidle/stateN/usage
+ /sys/devices/system/cpu/cpuX/cpuidle/stateN/above
+ /sys/devices/system/cpu/cpuX/cpuidle/stateN/below
+Date: September 2007
+KernelVersion: v2.6.24
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ The directory /sys/devices/system/cpu/cpuX/cpuidle contains per
+ logical CPU specific cpuidle information for each online cpu X.
+ The processor idle states which are available for use have the
+ following attributes:
+
+ ======== ==== =================================================
+ name: (RO) Name of the idle state (string).
- current_driver: displays current idle mechanism
+ latency: (RO) The latency to exit out of this idle state (in
+ microseconds).
- current_governor_ro: displays current idle policy
+ power: (RO) The power consumed while in this idle state (in
+ milliwatts).
- See files in Documentation/cpuidle/ for more information.
+ time: (RO) The total time spent in this idle state
+ (in microseconds).
+
+ usage: (RO) Number of times this state was entered (a count).
+
+ above: (RO) Number of times this state was entered, but the
+ observed CPU idle duration was too short for it
+ (a count).
+
+ below: (RO) Number of times this state was entered, but the
+ observed CPU idle duration was too long for it
+ (a count).
+ ======== ==== =================================================
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/desc
+Date: February 2008
+KernelVersion: v2.6.25
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ (RO) A small description about the idle state (string).
+
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/disable
+Date: March 2012
+KernelVersion: v3.10
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ (RW) Option to disable this idle state (bool). The behavior and
+ the effect of the disable variable depends on the implementation
+ of a particular governor. In the ladder governor, for example,
+ it is not coherent, i.e. if one is disabling a light state, then
+ all deeper states are disabled as well, but the disable variable
+ does not reflect it. Likewise, if one enables a deep state but a
+ lighter state still is disabled, then this has no effect.
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/default_status
+Date: December 2019
+KernelVersion: v5.6
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ (RO) The default status of this state, "enabled" or "disabled".
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/residency
+Date: March 2014
+KernelVersion: v3.15
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ (RO) Display the target residency i.e. the minimum amount of
+ time (in microseconds) this cpu should spend in this idle state
+ to make the transition worth the effort.
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/s2idle/
+Date: March 2018
+KernelVersion: v4.17
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ Idle state usage statistics related to suspend-to-idle.
+ This attribute group is only present for states that can be
+ used in suspend-to-idle with suspended timekeeping.
-What: /sys/devices/system/cpu/cpu#/cpufreq/*
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/s2idle/time
+Date: March 2018
+KernelVersion: v4.17
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ Total time spent by the CPU in suspend-to-idle (with scheduler
+ tick suspended) after requesting this state.
+
+What: /sys/devices/system/cpu/cpuX/cpuidle/state<N>/s2idle/usage
+Date: March 2018
+KernelVersion: v4.17
+Contact: Linux power management list <linux-pm@vger.kernel.org>
+Description:
+ Total number of times this state has been requested by the CPU
+ while entering suspend-to-idle.
+
+What: /sys/devices/system/cpu/cpuX/cpufreq/*
Date: pre-git history
Contact: linux-pm@vger.kernel.org
Description: Discover and change clock speed of CPUs
@@ -140,11 +257,8 @@ Description: Discover and change clock speed of CPUs
See files in Documentation/cpu-freq/ for more information.
- In particular, read Documentation/cpu-freq/user-guide.txt
- to learn how to control the knobs.
-
-What: /sys/devices/system/cpu/cpu#/cpufreq/freqdomain_cpus
+What: /sys/devices/system/cpu/cpuX/cpufreq/freqdomain_cpus
Date: June 2013
Contact: linux-pm@vger.kernel.org
Description: Discover CPUs in the same CPU frequency coordination domain
@@ -156,13 +270,68 @@ Description: Discover CPUs in the same CPU frequency coordination domain
attribute is useful for user space DVFS controllers to get better
power/performance results for platforms using acpi-cpufreq.
- This file is only present if the acpi-cpufreq driver is in use.
+ This file is only present if the acpi-cpufreq or the cppc-cpufreq
+ drivers are in use.
+
+What: /sys/devices/system/cpu/cpuX/cpufreq/auto_select
+Date: May 2025
+Contact: linux-pm@vger.kernel.org
+Description: Autonomous selection enable
+
+ Read/write interface to control autonomous selection enable
+ Read returns autonomous selection status:
+ 0: autonomous selection is disabled
+ 1: autonomous selection is enabled
+
+ Write 'y' or '1' or 'on' to enable autonomous selection.
+ Write 'n' or '0' or 'off' to disable autonomous selection.
+
+ This file is only present if the cppc-cpufreq driver is in use.
+
+What: /sys/devices/system/cpu/cpuX/cpufreq/auto_act_window
+Date: May 2025
+Contact: linux-pm@vger.kernel.org
+Description: Autonomous activity window
+
+ This file indicates a moving utilization sensitivity window to
+ the platform's autonomous selection policy.
+
+ Read/write an integer represents autonomous activity window (in
+ microseconds) from/to this file. The max value to write is
+ 1270000000 but the max significand is 127. This means that if 128
+ is written to this file, 127 will be stored. If the value is
+ greater than 130, only the first two digits will be saved as
+ significand.
+
+ Writing a zero value to this file enable the platform to
+ determine an appropriate Activity Window depending on the workload.
+
+ Writing to this file only has meaning when Autonomous Selection is
+ enabled.
+
+ This file is only present if the cppc-cpufreq driver is in use.
+
+What: /sys/devices/system/cpu/cpuX/cpufreq/energy_performance_preference_val
+Date: May 2025
+Contact: linux-pm@vger.kernel.org
+Description: Energy performance preference
+
+ Read/write an 8-bit integer from/to this file. This file
+ represents a range of values from 0 (performance preference) to
+ 0xFF (energy efficiency preference) that influences the rate of
+ performance increase/decrease and the result of the hardware's
+ energy efficiency and performance optimization policies.
+
+ Writing to this file only has meaning when Autonomous Selection is
+ enabled.
+
+ This file is only present if the cppc-cpufreq driver is in use.
What: /sys/devices/system/cpu/cpu*/cache/index3/cache_disable_{0,1}
Date: August 2008
KernelVersion: 2.6.27
-Contact: discuss@x86-64.org
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
Description: Disable L3 cache indices
These files exist in every CPU's cache/index3 directory. Each
@@ -171,12 +340,12 @@ Description: Disable L3 cache indices
on a processor with this functionality will return the currently
disabled index for that node. There is one L3 structure per
node, or per internal node on MCM machines. Writing a valid
- index to one of these files will cause the specificed cache
+ index to one of these files will cause the specified cache
index to be disabled.
All AMD processors with L3 caches provide this functionality.
For details, see BKDGs at
- http://developer.amd.com/documentation/guides/Pages/default.aspx
+ https://www.amd.com/en/support/tech-docs?keyword=bios+kernel
What: /sys/devices/system/cpu/cpufreq/boost
@@ -186,20 +355,22 @@ Description: Processor frequency boosting control
This switch controls the boost setting for the whole system.
Boosting allows the CPU and the firmware to run at a frequency
- beyound it's nominal limit.
- More details can be found in Documentation/cpu-freq/boost.txt
+ beyond its nominal limit.
+
+ More details can be found in
+ Documentation/admin-guide/pm/cpufreq.rst
-What: /sys/devices/system/cpu/cpu#/crash_notes
- /sys/devices/system/cpu/cpu#/crash_notes_size
+What: /sys/devices/system/cpu/cpuX/crash_notes
+ /sys/devices/system/cpu/cpuX/crash_notes_size
Date: April 2013
Contact: kexec@lists.infradead.org
Description: address and size of the percpu note.
crash_notes: the physical address of the memory that holds the
- note of cpu#.
+ note of cpuX.
- crash_notes_size: size of the note of cpu#.
+ crash_notes_size: size of the note of cpuX.
What: /sys/devices/system/cpu/intel_pstate/max_perf_pct
@@ -223,7 +394,8 @@ Description: Parameters for the Intel P-state driver
no_turbo: limits the driver to selecting P states below the turbo
frequency range.
- More details can be found in Documentation/cpu-freq/intel-pstate.txt
+ More details can be found in
+ Documentation/admin-guide/pm/intel_pstate.rst
What: /sys/devices/system/cpu/cpu*/cache/index*/<set_of_attributes_mentioned_below>
Date: July 2014(documented, existed before August 2008)
@@ -232,42 +404,387 @@ Contact: Sudeep Holla <sudeep.holla@arm.com>
Description: Parameters for the CPU cache attributes
allocation_policy:
- - WriteAllocate: allocate a memory location to a cache line
- on a cache miss because of a write
- - ReadAllocate: allocate a memory location to a cache line
+ - WriteAllocate:
+ allocate a memory location to a cache line
+ on a cache miss because of a write
+ - ReadAllocate:
+ allocate a memory location to a cache line
on a cache miss because of a read
- - ReadWriteAllocate: both writeallocate and readallocate
+ - ReadWriteAllocate:
+ both writeallocate and readallocate
- attributes: LEGACY used only on IA64 and is same as write_policy
-
- coherency_line_size: the minimum amount of data in bytes that gets
+ coherency_line_size:
+ the minimum amount of data in bytes that gets
transferred from memory to cache
- level: the cache hierarcy in the multi-level cache configuration
+ level:
+ the cache hierarchy in the multi-level cache configuration
- number_of_sets: total number of sets in the cache, a set is a
+ number_of_sets:
+ total number of sets in the cache, a set is a
collection of cache lines with the same cache index
- physical_line_partition: number of physical cache line per cache tag
+ physical_line_partition:
+ number of physical cache line per cache tag
- shared_cpu_list: the list of logical cpus sharing the cache
+ shared_cpu_list:
+ the list of logical cpus sharing the cache
- shared_cpu_map: logical cpu mask containing the list of cpus sharing
+ shared_cpu_map:
+ logical cpu mask containing the list of cpus sharing
the cache
- size: the total cache size in kB
+ size:
+ the total cache size in kB
type:
- Instruction: cache that only holds instructions
- Data: cache that only caches data
- Unified: cache that holds both data and instructions
- ways_of_associativity: degree of freedom in placing a particular block
- of memory in the cache
+ ways_of_associativity:
+ degree of freedom in placing a particular block
+ of memory in the cache
write_policy:
- - WriteThrough: data is written to both the cache line
+ - WriteThrough:
+ data is written to both the cache line
and to the block in the lower-level memory
- - WriteBack: data is written only to the cache line and
+ - WriteBack:
+ data is written only to the cache line and
the modified cache line is written to main
memory only when it is replaced
+
+
+What: /sys/devices/system/cpu/cpu*/cache/index*/id
+Date: September 2016
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Cache id
+
+ The id provides a unique number for a specific instance of
+ a cache of a particular type. E.g. there may be a level
+ 3 unified cache on each socket in a server and we may
+ assign them ids 0, 1, 2, ...
+
+ Note that id value can be non-contiguous. E.g. level 1
+ caches typically exist per core, but there may not be a
+ power of two cores on a socket, so these caches may be
+ numbered 0, 1, 2, 3, 4, 5, 8, 9, 10, ...
+
+What: /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/turbo_stat
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/sub_turbo_stat
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/unthrottle
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/powercap
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/overtemp
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/supply_fault
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/overcurrent
+ /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/occ_reset
+Date: March 2016
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+ Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: POWERNV CPUFreq driver's frequency throttle stats directory and
+ attributes
+
+ 'cpuX/cpufreq/throttle_stats' directory contains the CPU frequency
+ throttle stat attributes for the chip. The throttle stats of a cpu
+ is common across all the cpus belonging to a chip. Below are the
+ throttle attributes exported in the 'throttle_stats' directory:
+
+ - turbo_stat : This file gives the total number of times the max
+ frequency is throttled to lower frequency in turbo (at and above
+ nominal frequency) range of frequencies.
+
+ - sub_turbo_stat : This file gives the total number of times the
+ max frequency is throttled to lower frequency in sub-turbo(below
+ nominal frequency) range of frequencies.
+
+ - unthrottle : This file gives the total number of times the max
+ frequency is unthrottled after being throttled.
+
+ - powercap : This file gives the total number of times the max
+ frequency is throttled due to 'Power Capping'.
+
+ - overtemp : This file gives the total number of times the max
+ frequency is throttled due to 'CPU Over Temperature'.
+
+ - supply_fault : This file gives the total number of times the
+ max frequency is throttled due to 'Power Supply Failure'.
+
+ - overcurrent : This file gives the total number of times the
+ max frequency is throttled due to 'Overcurrent'.
+
+ - occ_reset : This file gives the total number of times the max
+ frequency is throttled due to 'OCC Reset'.
+
+ The sysfs attributes representing different throttle reasons like
+ powercap, overtemp, supply_fault, overcurrent and occ_reset map to
+ the reasons provided by OCC firmware for throttling the frequency.
+
+What: /sys/devices/system/cpu/cpufreq/policyX/throttle_stats
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/turbo_stat
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/sub_turbo_stat
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/unthrottle
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/powercap
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/overtemp
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/supply_fault
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/overcurrent
+ /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/occ_reset
+Date: March 2016
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+ Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: POWERNV CPUFreq driver's frequency throttle stats directory and
+ attributes
+
+ 'policyX/throttle_stats' directory and all the attributes are same as
+ the /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats directory and
+ attributes which give the frequency throttle information of the chip.
+
+What: /sys/devices/system/cpu/cpuX/regs/
+ /sys/devices/system/cpu/cpuX/regs/identification/
+ /sys/devices/system/cpu/cpuX/regs/identification/midr_el1
+ /sys/devices/system/cpu/cpuX/regs/identification/revidr_el1
+ /sys/devices/system/cpu/cpuX/regs/identification/aidr_el1
+ /sys/devices/system/cpu/cpuX/regs/identification/smidr_el1
+Date: June 2016
+Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org>
+Description: AArch64 CPU registers
+
+ 'identification' directory exposes the CPU ID registers for
+ identifying model and revision of the CPU and SMCU.
+
+What: /sys/devices/system/cpu/aarch32_el0
+Date: May 2021
+Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org>
+Description: Identifies the subset of CPUs in the system that can execute
+ AArch32 (32-bit ARM) applications. If present, the same format as
+ /sys/devices/system/cpu/{offline,online,possible,present} is used.
+ If absent, then all or none of the CPUs can execute AArch32
+ applications and execve() will behave accordingly.
+
+What: /sys/devices/system/cpu/cpuX/cpu_capacity
+Date: December 2016
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: information about CPUs heterogeneity.
+
+ cpu_capacity: capacity of cpuX.
+
+What: /sys/devices/system/cpu/vulnerabilities
+ /sys/devices/system/cpu/vulnerabilities/gather_data_sampling
+ /sys/devices/system/cpu/vulnerabilities/indirect_target_selection
+ /sys/devices/system/cpu/vulnerabilities/itlb_multihit
+ /sys/devices/system/cpu/vulnerabilities/l1tf
+ /sys/devices/system/cpu/vulnerabilities/mds
+ /sys/devices/system/cpu/vulnerabilities/meltdown
+ /sys/devices/system/cpu/vulnerabilities/mmio_stale_data
+ /sys/devices/system/cpu/vulnerabilities/old_microcode
+ /sys/devices/system/cpu/vulnerabilities/reg_file_data_sampling
+ /sys/devices/system/cpu/vulnerabilities/retbleed
+ /sys/devices/system/cpu/vulnerabilities/spec_store_bypass
+ /sys/devices/system/cpu/vulnerabilities/spectre_v1
+ /sys/devices/system/cpu/vulnerabilities/spectre_v2
+ /sys/devices/system/cpu/vulnerabilities/srbds
+ /sys/devices/system/cpu/vulnerabilities/tsa
+ /sys/devices/system/cpu/vulnerabilities/tsx_async_abort
+ /sys/devices/system/cpu/vulnerabilities/vmscape
+Date: January 2018
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Information about CPU vulnerabilities
+
+ The files are named after the code names of CPU
+ vulnerabilities. The output of those files reflects the
+ state of the CPUs in the system. Possible output values:
+
+ ================ ==============================================
+ "Not affected" CPU is not affected by the vulnerability
+ "Vulnerable" CPU is affected and no mitigation in effect
+ "Mitigation: $M" CPU is affected and mitigation $M is in effect
+ ================ ==============================================
+
+ See also: Documentation/admin-guide/hw-vuln/index.rst
+
+What: /sys/devices/system/cpu/smt
+ /sys/devices/system/cpu/smt/active
+ /sys/devices/system/cpu/smt/control
+Date: June 2018
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Control Symmetric Multi Threading (SMT)
+
+ active: Tells whether SMT is active (enabled and siblings online)
+
+ control: Read/write interface to control SMT. Possible
+ values:
+
+ ================ =========================================
+ "on" SMT is enabled
+ "off" SMT is disabled
+ "<N>" SMT is enabled with N threads per core.
+ "forceoff" SMT is force disabled. Cannot be changed.
+ "notsupported" SMT is not supported by the CPU
+ "notimplemented" SMT runtime toggling is not
+ implemented for the architecture
+ ================ =========================================
+
+ If control status is "forceoff" or "notsupported" writes
+ are rejected. Note that enabling SMT on PowerPC skips
+ offline cores.
+
+What: /sys/devices/system/cpu/cpuX/power/energy_perf_bias
+Date: March 2019
+Contact: linux-pm@vger.kernel.org
+Description: Intel Energy and Performance Bias Hint (EPB)
+
+ EPB for the given CPU in a sliding scale 0 - 15, where a value
+ of 0 corresponds to a hint preference for highest performance
+ and a value of 15 corresponds to the maximum energy savings.
+
+ In order to change the EPB value for the CPU, write either
+ a number in the 0 - 15 sliding scale above, or one of the
+ strings: "performance", "balance-performance", "normal",
+ "balance-power", "power" (that represent values reflected by
+ their meaning), to this attribute.
+
+ This attribute is present for all online CPUs supporting the
+ Intel EPB feature.
+
+What: /sys/devices/system/cpu/umwait_control
+ /sys/devices/system/cpu/umwait_control/enable_c02
+ /sys/devices/system/cpu/umwait_control/max_time
+Date: May 2019
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Umwait control
+
+ enable_c02: Read/write interface to control umwait C0.2 state
+ Read returns C0.2 state status:
+ 0: C0.2 is disabled
+ 1: C0.2 is enabled
+
+ Write 'y' or '1' or 'on' to enable C0.2 state.
+ Write 'n' or '0' or 'off' to disable C0.2 state.
+
+ The interface is case insensitive.
+
+ max_time: Read/write interface to control umwait maximum time
+ in TSC-quanta that the CPU can reside in either C0.1
+ or C0.2 state. The time is an unsigned 32-bit number.
+ Note that a value of zero means there is no limit.
+ Low order two bits must be zero.
+
+What: /sys/devices/system/cpu/sev
+ /sys/devices/system/cpu/sev/vmpl
+Date: May 2024
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description: Secure Encrypted Virtualization (SEV) information
+
+ This directory is only present when running as an SEV-SNP guest.
+
+ vmpl: Reports the Virtual Machine Privilege Level (VMPL) at which
+ the SEV-SNP guest is running.
+
+
+What: /sys/devices/system/cpu/svm
+Date: August 2019
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+ Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Secure Virtual Machine
+
+ If 1, it means the system is using the Protected Execution
+ Facility in POWER9 and newer processors. i.e., it is a Secure
+ Virtual Machine.
+
+What: /sys/devices/system/cpu/cpuX/purr
+Date: Apr 2005
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: PURR ticks for this CPU since the system boot.
+
+ The Processor Utilization Resources Register (PURR) is
+ a 64-bit counter which provides an estimate of the
+ resources used by the CPU thread. The contents of this
+ register increases monotonically. This sysfs interface
+ exposes the number of PURR ticks for cpuX.
+
+What: /sys/devices/system/cpu/cpuX/spurr
+Date: Dec 2006
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: SPURR ticks for this CPU since the system boot.
+
+ The Scaled Processor Utilization Resources Register
+ (SPURR) is a 64-bit counter that provides a frequency
+ invariant estimate of the resources used by the CPU
+ thread. The contents of this register increases
+ monotonically. This sysfs interface exposes the number
+ of SPURR ticks for cpuX.
+
+What: /sys/devices/system/cpu/cpuX/idle_purr
+Date: Apr 2020
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: PURR ticks for cpuX when it was idle.
+
+ This sysfs interface exposes the number of PURR ticks
+ for cpuX when it was idle.
+
+What: /sys/devices/system/cpu/cpuX/idle_spurr
+Date: Apr 2020
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: SPURR ticks for cpuX when it was idle.
+
+ This sysfs interface exposes the number of SPURR ticks
+ for cpuX when it was idle.
+
+What: /sys/devices/system/cpu/cpuX/mte_tcf_preferred
+Date: July 2021
+Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org>
+Description: Preferred MTE tag checking mode
+
+ When a user program specifies more than one MTE tag checking
+ mode, this sysfs node is used to specify which mode should
+ be preferred when scheduling a task on that CPU. Possible
+ values:
+
+ ================ ==============================================
+ "sync" Prefer synchronous mode
+ "asymm" Prefer asymmetric mode
+ "async" Prefer asynchronous mode
+ ================ ==============================================
+
+ See also: Documentation/arch/arm64/memory-tagging-extension.rst
+
+What: /sys/devices/system/cpu/nohz_full
+Date: Apr 2015
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ (RO) the list of CPUs that are in nohz_full mode.
+ These CPUs are set by boot parameter "nohz_full=".
+
+What: /sys/devices/system/cpu/isolated
+Date: Apr 2015
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ (RO) the list of CPUs that are isolated and don't
+ participate in load balancing. These CPUs are set by
+ boot parameter "isolcpus=".
+
+What: /sys/devices/system/cpu/housekeeping
+Date: Oct 2025
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ (RO) the list of logical CPUs that are designated by the kernel as
+ "housekeeping". Each CPU are responsible for handling essential
+ system-wide background tasks, including RCU callbacks, delayed
+ timer callbacks, and unbound workqueues, minimizing scheduling
+ jitter on low-latency, isolated CPUs. These CPUs are set when boot
+ parameter "isolcpus=nohz" or "nohz_full=" is specified.
+
+What: /sys/devices/system/cpu/crash_hotplug
+Date: Aug 2023
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ (RO) indicates whether or not the kernel updates relevant kexec
+ segments on memory hot un/plug and/or on/offline events, avoiding the
+ need to reload kdump kernel.
+
+What: /sys/devices/system/cpu/enabled
+Date: Nov 2022
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ (RO) the list of CPUs that can be brought online.
diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
index b82deeaec314..1a8ee26e92ae 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
+++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
@@ -1,16 +1,18 @@
-What: state
+What: /sys/devices/system/ibm_rtl/state
Date: Sep 2010
KernelVersion: 2.6.37
Contact: Vernon Mauery <vernux@us.ibm.com>
Description: The state file allows a means by which to change in and
out of Premium Real-Time Mode (PRTM), as well as the
ability to query the current state.
- 0 => PRTM off
- 1 => PRTM enabled
+
+ - 0 => PRTM off
+ - 1 => PRTM enabled
+
Users: The ibm-prtm userspace daemon uses this interface.
-What: version
+What: /sys/devices/system/ibm_rtl/version
Date: Sep 2010
KernelVersion: 2.6.37
Contact: Vernon Mauery <vernux@us.ibm.com>
diff --git a/Documentation/ABI/testing/sysfs-devices-vfio-dev b/Documentation/ABI/testing/sysfs-devices-vfio-dev
new file mode 100644
index 000000000000..e21424fd9666
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-vfio-dev
@@ -0,0 +1,8 @@
+What: /sys/.../<device>/vfio-dev/vfioX/
+Date: September 2022
+Contact: Yi Liu <yi.l.liu@intel.com>
+Description:
+ This directory is created when the device is bound to a
+ vfio driver. The layout under this directory matches what
+ exists for a standard 'struct device'. 'X' is a unique
+ index marking this device in vfio.
diff --git a/Documentation/ABI/testing/sysfs-devices-virtual-misc-tdx_guest b/Documentation/ABI/testing/sysfs-devices-virtual-misc-tdx_guest
new file mode 100644
index 000000000000..8fca56c8c9df
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-virtual-misc-tdx_guest
@@ -0,0 +1,63 @@
+What: /sys/devices/virtual/misc/tdx_guest/measurements/MRNAME[:HASH]
+Date: April, 2025
+KernelVersion: v6.16
+Contact: linux-coco@lists.linux.dev
+Description:
+ Value of a TDX measurement register (MR). MRNAME and HASH above
+ are placeholders. The optional suffix :HASH is used for MRs
+ that have associated hash algorithms. See below for a complete
+ list of TDX MRs exposed via sysfs. Refer to Intel TDX Module
+ ABI Specification for the definition of TDREPORT and the full
+ list of TDX measurements.
+
+ Intel TDX Module ABI Specification can be found at:
+ https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html#architecture
+
+ See also:
+ https://docs.kernel.org/driver-api/coco/measurement-registers.html
+
+What: /sys/devices/virtual/misc/tdx_guest/measurements/mrconfigid
+Date: April, 2025
+KernelVersion: v6.16
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) MRCONFIGID - 48-byte immutable storage typically used for
+ software-defined ID for non-owner-defined configuration of the
+ guest TD – e.g., run-time or OS configuration.
+
+What: /sys/devices/virtual/misc/tdx_guest/measurements/mrowner
+Date: April, 2025
+KernelVersion: v6.16
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) MROWNER - 48-byte immutable storage typically used for
+ software-defined ID for the guest TD’s owner.
+
+What: /sys/devices/virtual/misc/tdx_guest/measurements/mrownerconfig
+Date: April, 2025
+KernelVersion: v6.16
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) MROWNERCONFIG - 48-byte immutable storage typically used
+ for software-defined ID for owner-defined configuration of the
+ guest TD – e.g., specific to the workload rather than the
+ run-time or OS.
+
+What: /sys/devices/virtual/misc/tdx_guest/measurements/mrtd:sha384
+Date: April, 2025
+KernelVersion: v6.16
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RO) MRTD - Measurement of the initial contents of the TD.
+
+What: /sys/devices/virtual/misc/tdx_guest/measurements/rtmr[0123]:sha384
+Date: April, 2025
+KernelVersion: v6.16
+Contact: linux-coco@lists.linux.dev
+Description:
+ (RW) RTMR[0123] - 4 Run-Time extendable Measurement Registers.
+ Read from any of these returns the current value of the
+ corresponding RTMR. Write extends the written buffer to the
+ RTMR. All writes must start at offset 0 and be 48 bytes in
+ size. Partial writes will result in EINVAL returned by the
+ write() syscall.
diff --git a/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier b/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier
new file mode 100644
index 000000000000..59d073d20db6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier
@@ -0,0 +1,17 @@
+What: /sys/devices/.../waiting_for_supplier
+Date: May 2020
+Contact: Saravana Kannan <saravanak@google.com>
+Description:
+ The /sys/devices/.../waiting_for_supplier attribute is only
+ present when fw_devlink kernel command line option is enabled
+ and is set to something stricter than "permissive". It is
+ removed once a device probes successfully (because the
+ information is no longer relevant). The number read from it (0
+ or 1) reflects whether the device is waiting for one or more
+ suppliers to be added and then linked to using device links
+ before the device can probe.
+
+ A value of 0 means the device is not waiting for any suppliers
+ to be added before it can probe. A value of 1 means the device
+ is waiting for one or more suppliers to be added before it can
+ probe.
diff --git a/Documentation/ABI/testing/sysfs-devices-xenbus b/Documentation/ABI/testing/sysfs-devices-xenbus
new file mode 100644
index 000000000000..fd796cb4f315
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-xenbus
@@ -0,0 +1,41 @@
+What: /sys/devices/*/xenbus/event_channels
+Date: February 2021
+Contact: Xen Developers mailing list <xen-devel@lists.xenproject.org>
+Description:
+ Number of Xen event channels associated with a kernel based
+ paravirtualized device frontend or backend.
+
+What: /sys/devices/*/xenbus/events
+Date: February 2021
+Contact: Xen Developers mailing list <xen-devel@lists.xenproject.org>
+Description:
+ Total number of Xen events received for a Xen pv device
+ frontend or backend.
+
+What: /sys/devices/*/xenbus/jiffies_eoi_delayed
+Date: February 2021
+Contact: Xen Developers mailing list <xen-devel@lists.xenproject.org>
+Description:
+ Summed up time in jiffies the EOI of an interrupt for a Xen
+ pv device has been delayed in order to avoid stalls due to
+ event storms. This value rising is a first sign for a rogue
+ other end of the pv device.
+
+What: /sys/devices/*/xenbus/spurious_events
+Date: February 2021
+Contact: Xen Developers mailing list <xen-devel@lists.xenproject.org>
+Description:
+ Number of events received for a Xen pv device which did not
+ require any action. Too many spurious events in a row will
+ trigger delayed EOI processing.
+
+What: /sys/devices/*/xenbus/spurious_threshold
+Date: February 2021
+Contact: Xen Developers mailing list <xen-devel@lists.xenproject.org>
+Description:
+ Controls the tolerated number of subsequent spurious events
+ before delayed EOI processing is triggered for a Xen pv
+ device. Default is 1. This can be modified in case the other
+ end of the pv device is issuing spurious events on a regular
+ basis and is known not to be malicious on purpose. Raising
+ the value for such cases can improve pv device performance.
diff --git a/Documentation/ABI/testing/sysfs-driver-altera-cvp b/Documentation/ABI/testing/sysfs-driver-altera-cvp
new file mode 100644
index 000000000000..fbd8078fd7ad
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-altera-cvp
@@ -0,0 +1,8 @@
+What: /sys/bus/pci/drivers/altera-cvp/chkcfg
+Date: May 2017
+KernelVersion: 4.13
+Contact: Anatolij Gustschin <agust@denx.de>
+Description:
+ Contains either 1 or 0 and controls if configuration
+ error checking in altera-cvp driver is turned on or
+ off.
diff --git a/Documentation/ABI/testing/sysfs-driver-amd-sfh b/Documentation/ABI/testing/sysfs-driver-amd-sfh
new file mode 100644
index 000000000000..c053126a83bb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-amd-sfh
@@ -0,0 +1,13 @@
+What: /sys/bus/pci/drivers/pcie_mp2_amd/*/hpd
+Date: April 2025
+Contact: mario.limonciello@amd.com
+Description:
+ Human presence detection (HPD) enable/disable.
+ When HPD is enabled, the device will be able to detect the
+ presence of a human and will send an interrupt that can be
+ used to wake the system from a low power state.
+ When HPD is disabled, the device will not be able to detect
+ the presence of a human.
+
+ Access: Read/Write
+ Valid values: enabled/disabled
diff --git a/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing b/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing
new file mode 100644
index 000000000000..910df0e5815a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing
@@ -0,0 +1,27 @@
+What: /sys/bus/platform/drivers/aspeed-uart-routing/\*/uart\*
+Date: September 2021
+Contact: Oskar Senft <osk@google.com>
+ Chia-Wei Wang <chiawei_wang@aspeedtech.com>
+Description: Selects the RX source of the UARTx device.
+
+ When read, each file shows the list of available options with currently
+ selected option marked by brackets "[]". The list of available options
+ depends on the selected file.
+
+ e.g.
+ cat /sys/bus/platform/drivers/aspeed-uart-routing/\*.uart_routing/uart1
+ [io1] io2 io3 io4 uart2 uart3 uart4 io6
+
+ In this case, UART1 gets its input from IO1 (physical serial port 1).
+
+Users: OpenBMC. Proposed changes should be mailed to
+ openbmc@lists.ozlabs.org
+
+What: /sys/bus/platform/drivers/aspeed-uart-routing/\*/io\*
+Date: September 2021
+Contact: Oskar Senft <osk@google.com>
+ Chia-Wei Wang <chiawei_wang@aspeedtech.com>
+Description: Selects the RX source of IOx serial port. The current selection
+ will be marked by brackets "[]".
+Users: OpenBMC. Proposed changes should be mailed to
+ openbmc@lists.ozlabs.org
diff --git a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
new file mode 100644
index 000000000000..90596d8bb51c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
@@ -0,0 +1,31 @@
+What: /sys/bus/i2c/devices/.../bd9571mwv-regulator.*.auto/backup_mode
+Date: Jul 2018
+KernelVersion: 4.19
+Contact: Geert Uytterhoeven <geert+renesas@glider.be>
+Description: Read/write the current state of DDR Backup Mode, which controls
+ if DDR power rails will be kept powered during system suspend.
+ ("on"/"1" = enabled, "off"/"0" = disabled).
+ Two types of power switches (or control signals) can be used:
+
+ A. With a momentary power switch (or pulse signal), DDR
+ Backup Mode is enabled by default when available, as the
+ PMIC will be configured only during system suspend.
+ B. With a toggle power switch (or level signal), the
+ following steps must be followed exactly:
+
+ 1. Configure PMIC for backup mode, to change the role of
+ the accessory power switch from a power switch to a
+ wake-up switch,
+ 2. Switch accessory power switch off, to prepare for
+ system suspend, which is a manual step not controlled
+ by software,
+ 3. Suspend system,
+ 4. Switch accessory power switch on, to resume the
+ system.
+
+ DDR Backup Mode must be explicitly enabled by the user,
+ to invoke step 1.
+
+ See also Documentation/devicetree/bindings/mfd/rohm,bd9571mwv.yaml.
+Users: User space applications for embedded boards equipped with a
+ BD9571MWV PMIC.
diff --git a/Documentation/ABI/testing/sysfs-driver-ccp b/Documentation/ABI/testing/sysfs-driver-ccp
new file mode 100644
index 000000000000..ee6b787eee7a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-ccp
@@ -0,0 +1,105 @@
+What: /sys/bus/pci/devices/<BDF>/fused_part
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/fused_part file reports
+ whether the CPU or APU has been fused to prevent tampering.
+ 0: Not fused
+ 1: Fused
+
+What: /sys/bus/pci/devices/<BDF>/debug_lock_on
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/debug_lock_on reports
+ whether the AMD CPU or APU has been unlocked for debugging.
+ Possible values:
+ 0: Not locked
+ 1: Locked
+
+What: /sys/bus/pci/devices/<BDF>/tsme_status
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/tsme_status file reports
+ the status of transparent secure memory encryption on AMD systems.
+ Possible values:
+ 0: Not active
+ 1: Active
+
+What: /sys/bus/pci/devices/<BDF>/anti_rollback_status
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/anti_rollback_status file reports
+ whether the PSP is enforcing rollback protection.
+ Possible values:
+ 0: Not enforcing
+ 1: Enforcing
+
+What: /sys/bus/pci/devices/<BDF>/rpmc_production_enabled
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/rpmc_production_enabled file reports
+ whether Replay Protected Monotonic Counter support has been enabled.
+ Possible values:
+ 0: Not enabled
+ 1: Enabled
+
+What: /sys/bus/pci/devices/<BDF>/rpmc_spirom_available
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/rpmc_spirom_available file reports
+ whether an Replay Protected Monotonic Counter supported SPI is installed
+ on the system.
+ Possible values:
+ 0: Not present
+ 1: Present
+
+What: /sys/bus/pci/devices/<BDF>/hsp_tpm_available
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/hsp_tpm_available file reports
+ whether the HSP TPM has been activated.
+ Possible values:
+ 0: Not activated or present
+ 1: Activated
+
+What: /sys/bus/pci/devices/<BDF>/rom_armor_enforced
+Date: June 2022
+KernelVersion: 5.19
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/rom_armor_enforced file reports
+ whether RomArmor SPI protection is enforced.
+ Possible values:
+ 0: Not enforced
+ 1: Enforced
+
+What: /sys/bus/pci/devices/<BDF>/bootloader_version
+Date: June 2023
+KernelVersion: 6.4
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/bootloader_version
+ file reports the firmware version of the AMD AGESA
+ bootloader.
+
+What: /sys/bus/pci/devices/<BDF>/tee_version
+Date: June 2023
+KernelVersion: 6.4
+Contact: mario.limonciello@amd.com
+Description:
+ The /sys/bus/pci/devices/<BDF>/tee_version
+ file reports the firmware version of the AMD Trusted
+ Execution Environment (TEE).
diff --git a/Documentation/ABI/testing/sysfs-driver-chromeos-acpi b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
new file mode 100644
index 000000000000..d46b1c85840d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-chromeos-acpi
@@ -0,0 +1,152 @@
+What: /sys/bus/platform/devices/GGL0001:*/BINF.2
+ /sys/bus/platform/devices/GOOG0016:*/BINF.2
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns active EC firmware of current boot (boolean).
+
+ == ===============================
+ 0 Read only (recovery) firmware.
+ 1 Rewritable firmware.
+ == ===============================
+
+What: /sys/bus/platform/devices/GGL0001:*/BINF.3
+ /sys/bus/platform/devices/GOOG0016:*/BINF.3
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns main firmware type for current boot (integer).
+
+ == =====================================
+ 0 Recovery.
+ 1 Normal.
+ 2 Developer.
+ 3 Netboot (factory installation only).
+ == =====================================
+
+What: /sys/bus/platform/devices/GGL0001:*/CHSW
+ /sys/bus/platform/devices/GOOG0016:*/CHSW
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns switch position for Chrome OS specific hardware
+ switches when the firmware is booted (integer).
+
+ ==== ===========================================
+ 0 No changes.
+ 2 Recovery button was pressed.
+ 4 Recovery button was pressed (EC firmware).
+ 32 Developer switch was enabled.
+ 512 Firmware write protection was disabled.
+ ==== ===========================================
+
+What: /sys/bus/platform/devices/GGL0001:*/FMAP
+ /sys/bus/platform/devices/GOOG0016:*/FMAP
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns physical memory address of the start of the main
+ processor firmware flashmap.
+
+What: /sys/bus/platform/devices/GGL0001:*/FRID
+ /sys/bus/platform/devices/GOOG0016:*/FRID
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns firmware version for the read-only portion of the
+ main processor firmware.
+
+What: /sys/bus/platform/devices/GGL0001:*/FWID
+ /sys/bus/platform/devices/GOOG0016:*/FWID
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns firmware version for the rewritable portion of the
+ main processor firmware.
+
+What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.0
+ /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.0
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns type of the GPIO signal for the Chrome OS specific
+ GPIO assignments (integer).
+
+ =========== ==================================
+ 1 Recovery button.
+ 2 Developer mode switch.
+ 3 Firmware write protection switch.
+ 256 to 511 Debug header GPIO 0 to GPIO 255.
+ =========== ==================================
+
+What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.1
+ /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.1
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns signal attributes of the GPIO signal (integer bitfield).
+
+ == =======================
+ 0 Signal is active low.
+ 1 Signal is active high.
+ == =======================
+
+What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.2
+ /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.2
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns the GPIO number on the specified GPIO
+ controller.
+
+What: /sys/bus/platform/devices/GGL0001:*/GPIO.X/GPIO.3
+ /sys/bus/platform/devices/GOOG0016:*/GPIO.X/GPIO.3
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns name of the GPIO controller.
+
+What: /sys/bus/platform/devices/GGL0001:*/HWID
+ /sys/bus/platform/devices/GOOG0016:*/HWID
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns hardware ID for the Chromebook.
+
+What: /sys/bus/platform/devices/GGL0001:*/MECK
+ /sys/bus/platform/devices/GOOG0016:*/MECK
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns the SHA-1 or SHA-256 hash that is read out of the
+ Management Engine extended registers during boot. The hash
+ is exported via ACPI so the OS can verify that the Management
+ Engine firmware has not changed. If Management Engine is not
+ present, or if the firmware was unable to read the extended registers, this buffer size can be zero.
+
+What: /sys/bus/platform/devices/GGL0001:*/VBNV.0
+ /sys/bus/platform/devices/GOOG0016:*/VBNV.0
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns offset in CMOS bank 0 of the verified boot non-volatile
+ storage block, counting from the first writable CMOS byte
+ (that is, 'offset = 0' is the byte following the 14 bytes of
+ clock data).
+
+What: /sys/bus/platform/devices/GGL0001:*/VBNV.1
+ /sys/bus/platform/devices/GOOG0016:*/VBNV.1
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Return the size in bytes of the verified boot non-volatile
+ storage block.
+
+What: /sys/bus/platform/devices/GGL0001:*/VDAT
+ /sys/bus/platform/devices/GOOG0016:*/VDAT
+Date: May 2022
+KernelVersion: 5.19
+Description:
+ Returns the verified boot data block shared between the
+ firmware verification step and the kernel verification step
+ (hex dump).
diff --git a/Documentation/ABI/testing/sysfs-driver-eud b/Documentation/ABI/testing/sysfs-driver-eud
new file mode 100644
index 000000000000..2bab0db2d2f0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-eud
@@ -0,0 +1,9 @@
+What: /sys/bus/platform/drivers/qcom_eud/.../enable
+Date: February 2022
+Contact: Souradeep Chowdhury <quic_schowdhu@quicinc.com>
+Description:
+ The Enable/Disable sysfs interface for Embedded
+ USB Debugger(EUD). This enables and disables the
+ EUD based on a 1 or a 0 value. By enabling EUD,
+ the user is able to activate the mini-usb hub of
+ EUD for debug and trace capabilities.
diff --git a/Documentation/ABI/testing/sysfs-driver-framer-pef2256 b/Documentation/ABI/testing/sysfs-driver-framer-pef2256
new file mode 100644
index 000000000000..29f97783bf07
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-framer-pef2256
@@ -0,0 +1,8 @@
+What: /sys/bus/platform/devices/xxx/version
+Date: Sep 2025
+Contact: netdev@vger.kernel.org
+Description: Reports the version of the PEF2256 framer
+
+ Access: Read
+
+ Valid values: Represented as string
diff --git a/Documentation/ABI/testing/sysfs-driver-fsi-master-gpio b/Documentation/ABI/testing/sysfs-driver-fsi-master-gpio
new file mode 100644
index 000000000000..1f29c8843cfd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-fsi-master-gpio
@@ -0,0 +1,10 @@
+What: /sys/bus/platform/devices/[..]/fsi-master-gpio/external_mode
+Date: Feb 2018
+KernelVersion: 4.17
+Contact: jk@ozlabs.org
+Description:
+ Controls access arbitration for GPIO-based FSI master. A
+ value of 0 (the default) sets normal mode, where the
+ driver performs FSI bus transactions, 1 sets external mode,
+ where the FSI bus is driven externally (for example, by
+ a debug device).
diff --git a/Documentation/ABI/testing/sysfs-driver-ge-achc b/Documentation/ABI/testing/sysfs-driver-ge-achc
new file mode 100644
index 000000000000..c3e77def4b20
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-ge-achc
@@ -0,0 +1,15 @@
+What: /sys/bus/spi/<dev>/update_firmware
+Date: Jul 2021
+Contact: sebastian.reichel@collabora.com
+Description: Write 1 to this file to update the ACHC microcontroller
+ firmware via the EzPort interface. For this the kernel
+ will load "achc.bin" via the firmware API (so usually
+ from /lib/firmware). The write will block until the FW
+ has either been flashed successfully or an error occurred.
+
+What: /sys/bus/spi/<dev>/reset
+Date: Jul 2021
+Contact: sebastian.reichel@collabora.com
+Description: This file represents the microcontroller's reset line.
+ 1 means the reset line is asserted, 0 means it's not
+ asserted. The file is read and writable.
diff --git a/Documentation/ABI/testing/sysfs-driver-genwqe b/Documentation/ABI/testing/sysfs-driver-genwqe
index 64ac6d567c4b..69d855dc4c47 100644
--- a/Documentation/ABI/testing/sysfs-driver-genwqe
+++ b/Documentation/ABI/testing/sysfs-driver-genwqe
@@ -29,8 +29,12 @@ What: /sys/class/genwqe/genwqe<n>_card/reload_bitstream
Date: May 2014
Contact: klebers@linux.vnet.ibm.com
Description: Interface to trigger a PCIe card reset to reload the bitstream.
+
+ ::
+
sudo sh -c 'echo 1 > \
/sys/class/genwqe/genwqe0_card/reload_bitstream'
+
If successfully, the card will come back with the bitstream set
on 'next_bitstream'.
@@ -64,8 +68,11 @@ Description: Base clock frequency of the card.
What: /sys/class/genwqe/genwqe<n>_card/device/sriov_numvfs
Date: Oct 2013
Contact: haver@linux.vnet.ibm.com
-Description: Enable VFs (1..15):
+Description: Enable VFs (1..15)::
+
sudo sh -c 'echo 15 > \
/sys/bus/pci/devices/0000\:1b\:00.0/sriov_numvfs'
- Disable VFs:
+
+ Disable VFs::
+
Write a 0 into the same sysfs entry.
diff --git a/Documentation/ABI/testing/sysfs-driver-habanalabs b/Documentation/ABI/testing/sysfs-driver-habanalabs
new file mode 100644
index 000000000000..4244f5af4b54
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-habanalabs
@@ -0,0 +1,265 @@
+What: /sys/class/accel/accel<n>/device/armcp_kernel_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the Linux kernel running on the device's CPU.
+ Will be DEPRECATED in Linux kernel version 5.10, and be
+ replaced with cpucp_kernel_ver
+
+What: /sys/class/accel/accel<n>/device/armcp_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the application running on the device's CPU
+ Will be DEPRECATED in Linux kernel version 5.10, and be
+ replaced with cpucp_ver
+
+What: /sys/class/accel/accel<n>/device/clk_max_freq_mhz
+Date: Jun 2019
+KernelVersion: 5.7
+Contact: ogabbay@kernel.org
+Description: Allows the user to set the maximum clock frequency, in MHz.
+ The device clock might be set to lower value than the maximum.
+ The user should read the clk_cur_freq_mhz to see the actual
+ frequency value of the device clock. This property is valid
+ only for the Gaudi ASIC family
+
+What: /sys/class/accel/accel<n>/device/clk_cur_freq_mhz
+Date: Jun 2019
+KernelVersion: 5.7
+Contact: ogabbay@kernel.org
+Description: Displays the current frequency, in MHz, of the device clock.
+ This property is valid only for the Gaudi ASIC family
+
+What: /sys/class/accel/accel<n>/device/cpld_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the Device's CPLD F/W
+
+What: /sys/class/accel/accel<n>/device/cpucp_kernel_ver
+Date: Oct 2020
+KernelVersion: 5.10
+Contact: ogabbay@kernel.org
+Description: Version of the Linux kernel running on the device's CPU
+
+What: /sys/class/accel/accel<n>/device/cpucp_ver
+Date: Oct 2020
+KernelVersion: 5.10
+Contact: ogabbay@kernel.org
+Description: Version of the application running on the device's CPU
+
+What: /sys/class/accel/accel<n>/device/device_type
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the code name of the device according to its type.
+ The supported values are: "GOYA"
+
+What: /sys/class/accel/accel<n>/device/eeprom
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: A binary file attribute that contains the contents of the
+ on-board EEPROM
+
+What: /sys/class/accel/accel<n>/device/fuse_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the device's version from the eFuse
+
+What: /sys/class/accel/accel<n>/device/fw_os_ver
+Date: Dec 2021
+KernelVersion: 5.18
+Contact: ogabbay@kernel.org
+Description: Version of the firmware OS running on the device's CPU
+
+What: /sys/class/accel/accel<n>/device/hard_reset
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Interface to trigger a hard-reset operation for the device.
+ Hard-reset will reset ALL internal components of the device
+ except for the PCI interface and the internal PLLs
+
+What: /sys/class/accel/accel<n>/device/hard_reset_cnt
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays how many times the device have undergone a hard-reset
+ operation since the driver was loaded
+
+What: /sys/class/accel/accel<n>/device/high_pll
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Allows the user to set the maximum clock frequency for MME, TPC
+ and IC when the power management profile is set to "automatic".
+ This property is valid only for the Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/ic_clk
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Allows the user to set the maximum clock frequency, in Hz, of
+ the Interconnect fabric. Writes to this parameter affect the
+ device only when the power management profile is set to "manual"
+ mode. The device IC clock might be set to lower value than the
+ maximum. The user should read the ic_clk_curr to see the actual
+ frequency value of the IC. This property is valid only for the
+ Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/ic_clk_curr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the current clock frequency, in Hz, of the Interconnect
+ fabric. This property is valid only for the Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/infineon_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the Device's power supply F/W code. Relevant only to GOYA and GAUDI
+
+What: /sys/class/accel/accel<n>/device/max_power
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Allows the user to set the maximum power consumption of the
+ device in milliwatts.
+
+What: /sys/class/accel/accel<n>/device/mme_clk
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Allows the user to set the maximum clock frequency, in Hz, of
+ the MME compute engine. Writes to this parameter affect the
+ device only when the power management profile is set to "manual"
+ mode. The device MME clock might be set to lower value than the
+ maximum. The user should read the mme_clk_curr to see the actual
+ frequency value of the MME. This property is valid only for the
+ Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/mme_clk_curr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the current clock frequency, in Hz, of the MME compute
+ engine. This property is valid only for the Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/module_id
+Date: Nov 2023
+KernelVersion: not yet upstreamed
+Contact: ogabbay@kernel.org
+Description: Displays the device's module id
+
+What: /sys/class/accel/accel<n>/device/parent_device
+Date: Nov 2023
+KernelVersion: 6.8
+Contact: ttayar@habana.ai
+Description: Displays the name of the parent device of the accel device
+
+What: /sys/class/accel/accel<n>/device/pci_addr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the PCI address of the device. This is needed so the
+ user would be able to open a device based on its PCI address
+
+What: /sys/class/accel/accel<n>/device/pm_mng_profile
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Power management profile. Values are "auto", "manual". In "auto"
+ mode, the driver will set the maximum clock frequency to a high
+ value when a user-space process opens the device's file (unless
+ it was already opened by another process). The driver will set
+ the max clock frequency to a low value when there are no user
+ processes that are opened on the device's file. In "manual"
+ mode, the user sets the maximum clock frequency by writing to
+ ic_clk, mme_clk and tpc_clk. This property is valid only for
+ the Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/preboot_btl_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the device's preboot F/W code
+
+What: /sys/class/accel/accel<n>/device/security_enabled
+Date: Oct 2022
+KernelVersion: 6.1
+Contact: obitton@habana.ai
+Description: Displays the device's security status
+
+What: /sys/class/accel/accel<n>/device/soft_reset
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Interface to trigger a soft-reset operation for the device.
+ Soft-reset will reset only the compute and DMA engines of the
+ device
+
+What: /sys/class/accel/accel<n>/device/soft_reset_cnt
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays how many times the device have undergone a soft-reset
+ operation since the driver was loaded
+
+What: /sys/class/accel/accel<n>/device/status
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Status of the card:
+
+ * "operational" - Device is available for work.
+ * "in reset" - Device is going through reset, will be
+ available shortly.
+ * "disabled" - Device is not usable.
+ * "needs reset" - Device is not usable until a hard reset
+ is initiated.
+ * "in device creation" - Device is not available yet, as it
+ is still initializing.
+ * "in reset after device release" - Device is going through
+ a compute-reset which is executed after a device release
+ (relevant for Gaudi2 only).
+
+What: /sys/class/accel/accel<n>/device/thermal_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the Device's thermal daemon
+
+What: /sys/class/accel/accel<n>/device/tpc_clk
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Allows the user to set the maximum clock frequency, in Hz, of
+ the TPC compute engines. Writes to this parameter affect the
+ device only when the power management profile is set to "manual"
+ mode. The device TPC clock might be set to lower value than the
+ maximum. The user should read the tpc_clk_curr to see the actual
+ frequency value of the TPC. This property is valid only for
+ Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/tpc_clk_curr
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Displays the current clock frequency, in Hz, of the TPC compute
+ engines. This property is valid only for the Goya ASIC family
+
+What: /sys/class/accel/accel<n>/device/uboot_ver
+Date: Jan 2019
+KernelVersion: 5.1
+Contact: ogabbay@kernel.org
+Description: Version of the u-boot running on the device's CPU
+
+What: /sys/class/accel/accel<n>/device/vrm_ver
+Date: Jan 2022
+KernelVersion: 5.17
+Contact: ogabbay@kernel.org
+Description: Version of the Device's Voltage Regulator Monitor F/W code. N/A to GOYA and GAUDI
diff --git a/Documentation/ABI/testing/sysfs-driver-hid b/Documentation/ABI/testing/sysfs-driver-hid
index 48942cacb0bf..a59533410871 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid
+++ b/Documentation/ABI/testing/sysfs-driver-hid
@@ -1,6 +1,6 @@
-What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
- For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
- Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
+What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor
+What: /sys/class/hidraw/hidraw<num>/device/report_descriptor
Date: Jan 2011
KernelVersion: 2.0.39
Contact: Alan Ott <alan@signal11.us>
@@ -9,9 +9,9 @@ Description: When read, this file returns the device's raw binary HID
This file cannot be written.
Users: HIDAPI library (http://www.signal11.us/oss/hidapi)
-What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
- For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
- Symlink : /sys/class/hidraw/hidraw<num>/device/country
+What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
+What: /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country
+What: /sys/class/hidraw/hidraw<num>/device/country
Date: February 2015
KernelVersion: 3.19
Contact: Olivier Gay <ogay@logitech.com>
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-appletb-kbd b/Documentation/ABI/testing/sysfs-driver-hid-appletb-kbd
new file mode 100644
index 000000000000..8c9718d83e9d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-hid-appletb-kbd
@@ -0,0 +1,13 @@
+What: /sys/bus/hid/drivers/hid-appletb-kbd/<dev>/mode
+Date: March, 2025
+KernelVersion: 6.15
+Contact: linux-input@vger.kernel.org
+Description:
+ The set of keys displayed on the Touch Bar.
+ Valid values are:
+ == =================
+ 0 Escape key only
+ 1 Function keys
+ 2 Media/brightness keys
+ 3 None
+ == =================
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-corsair b/Documentation/ABI/testing/sysfs-driver-hid-corsair
new file mode 100644
index 000000000000..b8827f0f12c4
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-hid-corsair
@@ -0,0 +1,15 @@
+What: /sys/bus/drivers/corsair/<dev>/macro_mode
+Date: August 2015
+KernelVersion: 4.2
+Contact: Clement Vuchener <clement.vuchener@gmail.com>
+Description: Get/set the current playback mode. "SW" for software mode
+ where G-keys triggers their regular key codes. "HW" for
+ hardware playback mode where the G-keys play their macro
+ from the on-board memory.
+
+
+What: /sys/bus/drivers/corsair/<dev>/current_profile
+Date: August 2015
+KernelVersion: 4.2
+Contact: Clement Vuchener <clement.vuchener@gmail.com>
+Description: Get/set the current selected profile. Values are from 1 to 3.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-corsair-void b/Documentation/ABI/testing/sysfs-driver-hid-corsair-void
new file mode 100644
index 000000000000..83fa625c0025
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-hid-corsair-void
@@ -0,0 +1,38 @@
+What: /sys/bus/hid/drivers/hid-corsair-void/<dev>/fw_version_headset
+Date: January 2024
+KernelVersion: 6.13
+Contact: Stuart Hayhurst <stuart.a.hayhurst@gmail.com>
+Description: (R) The firmware version of the headset
+ * Returns -ENODATA if no version was reported
+
+What: /sys/bus/hid/drivers/hid-corsair-void/<dev>/fw_version_receiver
+Date: January 2024
+KernelVersion: 6.13
+Contact: Stuart Hayhurst <stuart.a.hayhurst@gmail.com>
+Description: (R) The firmware version of the receiver
+
+What: /sys/bus/hid/drivers/hid-corsair-void/<dev>/microphone_up
+Date: July 2023
+KernelVersion: 6.13
+Contact: Stuart Hayhurst <stuart.a.hayhurst@gmail.com>
+Description: (R) Get the physical position of the microphone
+ * 1 -> Microphone up
+ * 0 -> Microphone down
+
+What: /sys/bus/hid/drivers/hid-corsair-void/<dev>/send_alert
+Date: July 2023
+KernelVersion: 6.13
+Contact: Stuart Hayhurst <stuart.a.hayhurst@gmail.com>
+Description: (W) Play a built-in notification from the headset (0 / 1)
+
+What: /sys/bus/hid/drivers/hid-corsair-void/<dev>/set_sidetone
+Date: December 2023
+KernelVersion: 6.13
+Contact: Stuart Hayhurst <stuart.a.hayhurst@gmail.com>
+Description: (W) Set the sidetone volume (0 - sidetone_max)
+
+What: /sys/bus/hid/drivers/hid-corsair-void/<dev>/sidetone_max
+Date: July 2024
+KernelVersion: 6.13
+Contact: Stuart Hayhurst <stuart.a.hayhurst@gmail.com>
+Description: (R) Report the maximum sidetone volume
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-lenovo b/Documentation/ABI/testing/sysfs-driver-hid-lenovo
index 53a0725962e1..aee85ca1f6be 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-lenovo
+++ b/Documentation/ABI/testing/sysfs-driver-hid-lenovo
@@ -3,14 +3,18 @@ Date: July 2011
Contact: linux-input@vger.kernel.org
Description: This controls if mouse clicks should be generated if the trackpoint is quickly pressed. How fast this press has to be
is being controlled by press_speed.
+
Values are 0 or 1.
+
Applies to Thinkpad USB Keyboard with TrackPoint.
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/dragging
Date: July 2011
Contact: linux-input@vger.kernel.org
Description: If this setting is enabled, it is possible to do dragging by pressing the trackpoint. This requires press_to_select to be enabled.
+
Values are 0 or 1.
+
Applies to Thinkpad USB Keyboard with TrackPoint.
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/release_to_select
@@ -25,7 +29,9 @@ Date: July 2011
Contact: linux-input@vger.kernel.org
Description: This setting controls if the mouse click events generated by pressing the trackpoint (if press_to_select is enabled) generate
a left or right mouse button click.
+
Values are 0 or 1.
+
Applies to Thinkpad USB Keyboard with TrackPoint.
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/sensitivity
@@ -39,12 +45,16 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-
Date: July 2011
Contact: linux-input@vger.kernel.org
Description: This setting controls how fast the trackpoint needs to be pressed to generate a mouse click if press_to_select is enabled.
+
Values are decimal integers from 1 (slowest) to 255 (fastest).
+
Applies to Thinkpad USB Keyboard with TrackPoint.
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/fn_lock
Date: July 2014
Contact: linux-input@vger.kernel.org
Description: This setting controls whether Fn Lock is enabled on the keyboard (i.e. if F1 is Mute or F1)
+
Values are 0 or 1
+
Applies to ThinkPad Compact (USB|Bluetooth) Keyboard with TrackPoint.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp b/Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp
new file mode 100644
index 000000000000..d8f831f2d6b5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp
@@ -0,0 +1,19 @@
+What: /sys/bus/hid/drivers/logitech-hidpp-device/<dev>/range
+Date: Jan, 2016
+KernelVersion: 4.6
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) This attribute controls the amount of 'turn' permitted in
+ Logitech G920 wheel. Reading from the file shows the current
+ range of the steering wheel. Writing a value within the min and
+ max boundary sets the range of the wheel.
+
+What: /sys/bus/hid/drivers/logitech-hidpp-device/<dev>/builtin_power_supply
+Date: Apr, 2017
+KernelVersion: 4.12
+Contact: linux-input@vger.kernel.org
+Description:
+ Presence of this file indicates that HID++ driver is capable of
+ handling battery properties in the kernel. This way, upower can
+ add a udev rule to decide whether or not it should use the
+ internal unifying support or the generic kernel one.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
index b3f6a2ac5007..de07be314efc 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
+++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
@@ -1,7 +1,7 @@
-What: /sys/module/hid_logitech/drivers/hid:logitech/<dev>/range.
+What: /sys/bus/hid/drivers/logitech/<dev>/range
Date: July 2011
KernelVersion: 3.2
-Contact: Michal Malý <madcatxster@gmail.com>
+Contact: Michal Malý <madcatxster@devoid-pointer.net>
Description: Display minimum, maximum and current range of the steering
wheel. Writing a value within min and max boundaries sets the
range of the wheel.
@@ -9,10 +9,12 @@ Description: Display minimum, maximum and current range of the steering
What: /sys/bus/hid/drivers/logitech/<dev>/alternate_modes
Date: Feb 2015
KernelVersion: 4.1
-Contact: Michal Malý <madcatxster@gmail.com>
+Contact: Michal Malý <madcatxster@devoid-pointer.net>
Description: Displays a set of alternate modes supported by a wheel. Each
mode is listed as follows:
+
Tag: Mode Name
+
Currently active mode is marked with an asterisk. List also
contains an abstract item "native" which always denotes the
native mode of the wheel. Echoing the mode tag switches the
@@ -24,18 +26,30 @@ Description: Displays a set of alternate modes supported by a wheel. Each
This entry is not created for devices that have only one mode.
Currently supported mode switches:
- Driving Force Pro:
+
+ Driving Force Pro::
+
DF-EX --> DFP
- G25:
+ G25::
+
DF-EX --> DFP --> G25
- G27:
+ G27::
+
DF-EX <*> DFP <-> G25 <-> G27
DF-EX <*--------> G25 <-> G27
DF-EX <*----------------> G27
- DFGT:
+ G29::
+
+ DF-EX <*> DFP <-> G25 <-> G27 <-> G29
+ DF-EX <*--------> G25 <-> G27 <-> G29
+ DF-EX <*----------------> G27 <-> G29
+ DF-EX <*------------------------> G29
+
+ DFGT::
+
DF-EX <*> DFP <-> DFGT
DF-EX <*--------> DFGT
@@ -45,8 +59,17 @@ Description: Displays a set of alternate modes supported by a wheel. Each
What: /sys/bus/hid/drivers/logitech/<dev>/real_id
Date: Feb 2015
KernelVersion: 4.1
-Contact: Michal Malý <madcatxster@gmail.com>
+Contact: Michal Malý <madcatxster@devoid-pointer.net>
Description: Displays the real model of the wheel regardless of any
alternate mode the wheel might be switched to.
It is a read-only value.
This entry is not created for devices that have only one mode.
+
+What: /sys/bus/hid/drivers/logitech/<dev>/combine_pedals
+Date: Sep 2016
+KernelVersion: 4.9
+Contact: Simon Wood <simon@mungewell.org>
+Description: Controls whether a combined value of accelerator and brake is
+ reported on the Y axis of the controller. Useful for older games
+ which can do not work with separate accelerator/brake axis.
+ Off ('0') by default, enabled by setting '1'.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-ntrig b/Documentation/ABI/testing/sysfs-driver-hid-ntrig
new file mode 100644
index 000000000000..0e323a5cec6c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-hid-ntrig
@@ -0,0 +1,73 @@
+What: /sys/bus/hid/drivers/ntrig/<dev>/activate_slack
+Date: May, 2010
+KernelVersion: 2.6.35
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Number of contact frames ignored before acknowledging the
+ start of activity (activating touch).
+
+
+What: /sys/bus/hid/drivers/ntrig/<dev>/decativate_slack
+Date: May, 2010
+KernelVersion: 2.6.35
+Contact: linux-input@vger.kernel.org
+Description:
+ (RW) Number of empty (no contact) frames ignored before
+ acknowledging the end of activity (deactivating touch).
+
+ When the last finger is removed from the device, it sends a
+ number of empty frames. By holding off on deactivation for a few
+ frames false erroneous disconnects can be tolerated, where the
+ sensor may mistakenly not detect a finger that is still present.
+
+
+What: /sys/bus/hid/drivers/ntrig/<dev>/activation_width
+What: /sys/bus/hid/drivers/ntrig/<dev>/activation_height
+Date: May, 2010
+KernelVersion: 2.6.35
+Contact: linux-input@vger.kernel.org
+Description:
+ Threholds to override activation slack.
+
+ ================= =====================================
+ activation_width (RW) Width threshold to immediately
+ start processing touch events.
+
+ activation_height (RW) Height threshold to immediately
+ start processing touch events.
+ ================= =====================================
+
+What: /sys/bus/hid/drivers/ntrig/<dev>/min_width
+What: /sys/bus/hid/drivers/ntrig/<dev>/min_height
+Date: May, 2010
+KernelVersion: 2.6.35
+Contact: linux-input@vger.kernel.org
+Description:
+ Minimum size contact accepted.
+
+ ========== ===========================================
+ min_width (RW) Minimum touch contact width to decide
+ activation and activity.
+
+ min_height (RW) Minimum touch contact height to decide
+ activation and activity.
+ ========== ===========================================
+
+
+What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_physical_width
+What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_physical_height
+Date: May, 2010
+KernelVersion: 2.6.35
+Contact: linux-input@vger.kernel.org
+Description:
+ (RO) These are internal ranges not used for normal events but
+ useful for tuning.
+
+
+What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_logical_width
+What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_logical_height
+Date: May, 2010
+KernelVersion: 2.6.35
+Contact: linux-input@vger.kernel.org
+Description:
+ (RO) The range for positions reported during activity.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-picolcd b/Documentation/ABI/testing/sysfs-driver-hid-picolcd
index 08579e7e1e89..98fd81ad76a1 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-picolcd
+++ b/Documentation/ABI/testing/sysfs-driver-hid-picolcd
@@ -39,5 +39,5 @@ Description: Make it possible to adjust defio refresh rate.
Note: As device can barely do 2 complete refreshes a second
it only makes sense to adjust this value if only one or two
tiles get changed and it's not appropriate to expect the application
- to flush it's tiny changes explicitely at higher than default rate.
+ to flush its tiny changes explicitly at higher than default rate.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
index 3ca3971109bf..11cd9bf0ad18 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
+++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
@@ -3,17 +3,21 @@ Date: March 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
Description: It is possible to switch the dpi setting of the mouse with the
press of a button.
+
When read, this file returns the raw number of the actual dpi
setting reported by the mouse. This number has to be further
- processed to receive the real dpi value.
+ processed to receive the real dpi value:
+ ===== =====
VALUE DPI
+ ===== =====
1 800
2 1200
3 1600
4 2000
5 2400
6 3200
+ ===== =====
This file is readonly.
Users: http://roccat.sourceforge.net
@@ -22,6 +26,7 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-
Date: March 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
Description: When read, this file returns the number of the actual profile.
+
This file is readonly.
Users: http://roccat.sourceforge.net
@@ -33,6 +38,7 @@ Description: When read, this file returns the raw integer version number of the
further usage in other programs. To receive the real version
number the decimal point has to be shifted 2 positions to the
left. E.g. a returned value of 138 means 1.38
+
This file is readonly.
Users: http://roccat.sourceforge.net
@@ -43,10 +49,13 @@ Description: The mouse can store 5 profiles which can be switched by the
press of a button. A profile holds information like button
mappings, sensitivity, the colors of the 5 leds and light
effects.
+
When read, these files return the respective profile. The
returned data is 975 bytes in size.
+
When written, this file lets one write the respective profile
data back to the mouse. The data has to be 975 bytes long.
+
The mouse will reject invalid data, whereas the profile number
stored in the profile doesn't need to fit the number of the
store.
@@ -58,6 +67,7 @@ Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
Description: When read, this file returns the settings stored in the mouse.
The size of the data is 36 bytes and holds information like the
startup_profile, tcu state and calibration_data.
+
When written, this file lets write settings back to the mouse.
The data has to be 36 bytes long. The mouse will reject invalid
data.
@@ -67,8 +77,10 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-
Date: March 2010
Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
Description: The integer value of this attribute ranges from 1 to 5.
+
When read, this attribute returns the number of the profile
that's active when the mouse is powered on.
+
When written, this file sets the number of the startup profile
and the mouse activates this profile immediately.
Users: http://roccat.sourceforge.net
@@ -80,9 +92,12 @@ Description: The mouse has a "Tracking Control Unit" which lets the user
calibrate the laser power to fit the mousepad surface.
When read, this file returns the current state of the TCU,
where 0 means off and 1 means on.
+
Writing 0 in this file will switch the TCU off.
+
Writing 1 in this file will start the calibration which takes
around 6 seconds to complete and activates the TCU.
+
Users: http://roccat.sourceforge.net
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/weight
@@ -93,14 +108,18 @@ Description: The mouse can be equipped with one of four supplied weights
and its value can be read out. When read, this file returns the
raw value returned by the mouse which eases further processing
in other software.
+
The values map to the weights as follows:
+ ===== ======
VALUE WEIGHT
+ ===== ======
0 none
1 5g
2 10g
3 15g
4 20g
+ ===== ======
This file is readonly.
Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus
deleted file mode 100644
index 7bd776f9c3c7..000000000000
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus
+++ /dev/null
@@ -1,96 +0,0 @@
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/actual_profile
-Date: October 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The integer value of this attribute ranges from 0-4.
- When read, this attribute returns the number of the actual
- profile. This value is persistent, so its equivalent to the
- profile that's active when the mouse is powered on next time.
- When written, this file sets the number of the startup profile
- and the mouse activates this profile immediately.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/info
-Date: November 2012
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: When read, this file returns general data like firmware version.
- When written, the device can be reset.
- The data is 8 bytes long.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro
-Date: October 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store a macro with max 500 key/button strokes
- internally.
- When written, this file lets one set the sequence for a specific
- button for a specific profile. Button and profile numbers are
- included in written data. The data has to be 2082 bytes long.
- This file is writeonly.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_buttons
-Date: August 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store 5 profiles which can be switched by the
- press of a button. A profile is split in settings and buttons.
- profile_buttons holds information about button layout.
- When written, this file lets one write the respective profile
- buttons back to the mouse. The data has to be 77 bytes long.
- The mouse will reject invalid data.
- Which profile to write is determined by the profile number
- contained in the data.
- Before reading this file, control has to be written to select
- which profile to read.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings
-Date: October 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store 5 profiles which can be switched by the
- press of a button. A profile is split in settings and buttons.
- profile_settings holds information like resolution, sensitivity
- and light effects.
- When written, this file lets one write the respective profile
- settings back to the mouse. The data has to be 43 bytes long.
- The mouse will reject invalid data.
- Which profile to write is determined by the profile number
- contained in the data.
- Before reading this file, control has to be written to select
- which profile to read.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor
-Date: October 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse has a tracking- and a distance-control-unit. These
- can be activated/deactivated and the lift-off distance can be
- set. The data has to be 6 bytes long.
- This file is writeonly.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/talk
-Date: May 2011
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: Used to active some easy* functions of the mouse from outside.
- The data has to be 16 bytes long.
- This file is writeonly.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu
-Date: October 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: When written a calibration process for the tracking control unit
- can be initiated/cancelled. Also lets one read/write sensor
- registers.
- The data has to be 4 bytes long.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image
-Date: October 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: When read the mouse returns a 30x30 pixel image of the
- sampled underground. This works only in the course of a
- calibration process initiated with tcu.
- The returned data is 1028 bytes in size.
- This file is readonly.
-Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus
deleted file mode 100644
index a10404f15a54..000000000000
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus
+++ /dev/null
@@ -1,49 +0,0 @@
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile
-Date: January 2011
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The integer value of this attribute ranges from 0-4.
- When read, this attribute returns the number of the active
- profile.
- When written, the mouse activates this profile immediately.
- The profile that's active when powered down is the same that's
- active when the mouse is powered on.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/info
-Date: November 2012
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: When read, this file returns general data like firmware version.
- When written, the device can be reset.
- The data is 6 bytes long.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons
-Date: January 2011
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store 5 profiles which can be switched by the
- press of a button. A profile is split in settings and buttons.
- profile_buttons holds information about button layout.
- When written, this file lets one write the respective profile
- buttons back to the mouse. The data has to be 23 bytes long.
- The mouse will reject invalid data.
- Which profile to write is determined by the profile number
- contained in the data.
- Before reading this file, control has to be written to select
- which profile to read.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings
-Date: January 2011
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store 5 profiles which can be switched by the
- press of a button. A profile is split in settings and buttons.
- profile_settings holds information like resolution, sensitivity
- and light effects.
- When written, this file lets one write the respective profile
- settings back to the mouse. The data has to be 16 bytes long.
- The mouse will reject invalid data.
- Which profile to write is determined by the profile number
- contained in the data.
- Before reading this file, control has to be written to select
- which profile to read.
-Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra
deleted file mode 100644
index 9fa9de30d14b..000000000000
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra
+++ /dev/null
@@ -1,49 +0,0 @@
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info
-Date: November 2012
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: When read, this file returns general data like firmware version.
- When written, the device can be reset.
- The data is 6 bytes long.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings
-Date: August 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store 5 profiles which can be switched by the
- press of a button. A profile is split in settings and buttons.
- profile_settings holds information like resolution, sensitivity
- and light effects.
- When written, this file lets one write the respective profile
- settings back to the mouse. The data has to be 13 bytes long.
- The mouse will reject invalid data.
- Which profile to write is determined by the profile number
- contained in the data.
- Before reading this file, control has to be written to select
- which profile to read.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons
-Date: August 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: The mouse can store 5 profiles which can be switched by the
- press of a button. A profile is split in settings and buttons.
- profile_buttons holds information about button layout.
- When written, this file lets one write the respective profile
- buttons back to the mouse. The data has to be 19 bytes long.
- The mouse will reject invalid data.
- Which profile to write is determined by the profile number
- contained in the data.
- Before reading this file, control has to be written to select
- which profile to read.
-Users: http://roccat.sourceforge.net
-
-What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings
-Date: August 2010
-Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
-Description: When read, this file returns the settings stored in the mouse.
- The size of the data is 3 bytes and holds information on the
- startup_profile.
- When written, this file lets write settings back to the mouse.
- The data has to be 3 bytes long. The mouse will reject invalid
- data.
-Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
index 39dfa5cb1cc5..3bf43d9dcdfe 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote
+++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
@@ -20,6 +20,7 @@ Description: This file contains the currently connected and initialized
the official Nintendo Nunchuck extension and classic is the
Nintendo Classic Controller extension. The motionp extension can
be combined with the other two.
+
Starting with kernel-version 3.11 Motion Plus hotplugging is
supported and if detected, it's no longer reported as static
extension. You will get uevent notifications for the motion-plus
@@ -39,9 +40,13 @@ Description: While a device is initialized by the wiimote driver, we perform
Other strings for each device-type are available and may be
added if new device-specific detections are added.
Currently supported are:
- gen10: First Wii Remote generation
- gen20: Second Wii Remote Plus generation (builtin MP)
+
+ ============= =======================================
+ gen10: First Wii Remote generation
+ gen20: Second Wii Remote Plus generation
+ (builtin MP)
balanceboard: Wii Balance Board
+ ============= =======================================
What: /sys/bus/hid/drivers/wiimote/<dev>/bboard_calib
Date: May 2013
@@ -54,6 +59,7 @@ Description: This attribute is only provided if the device was detected as a
First, 0kg values for all 4 sensors are written, followed by the
17kg values for all 4 sensors and last the 34kg values for all 4
sensors.
+
Calibration data is already applied by the kernel to all input
values but may be used by user-space to perform other
transformations.
@@ -68,9 +74,11 @@ Description: This attribute is only provided if the device was detected as a
is prefixed with a +/-. Each value is a signed 16bit number.
Data is encoded as decimal numbers and specifies the offsets of
the analog sticks of the pro-controller.
+
Calibration data is already applied by the kernel to all input
values but may be used by user-space to perform other
transformations.
+
Calibration data is detected by the kernel during device setup.
You can write "scan\n" into this file to re-trigger calibration.
You can also write data directly in the form "x1:y1 x2:y2" to
diff --git a/Documentation/ABI/testing/sysfs-driver-input-cros-ec-keyb b/Documentation/ABI/testing/sysfs-driver-input-cros-ec-keyb
new file mode 100644
index 000000000000..c7afc2328045
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-input-cros-ec-keyb
@@ -0,0 +1,6 @@
+What: /sys/class/input/input(x)/device/function_row_physmap
+Date: January 2021
+Contact: Philip Chen <philipchen@chromium.org>
+Description: A space separated list of scancodes for the top row keys,
+ ordered by the physical positions of the keys, from left
+ to right.
diff --git a/Documentation/ABI/testing/sysfs-driver-input-exc3000 b/Documentation/ABI/testing/sysfs-driver-input-exc3000
new file mode 100644
index 000000000000..704434b277b0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-input-exc3000
@@ -0,0 +1,26 @@
+What: /sys/bus/i2c/devices/xxx/fw_version
+Date: Aug 2020
+Contact: linux-input@vger.kernel.org
+Description: Reports the firmware version provided by the touchscreen, for example "00_T6" on a EXC80H60
+
+ Access: Read
+
+ Valid values: Represented as string
+
+What: /sys/bus/i2c/devices/xxx/model
+Date: Aug 2020
+Contact: linux-input@vger.kernel.org
+Description: Reports the model identification provided by the touchscreen, for example "Orion_1320" on a EXC80H60
+
+ Access: Read
+
+ Valid values: Represented as string
+
+What: /sys/bus/i2c/devices/xxx/type
+Date: Jan 2021
+Contact: linux-input@vger.kernel.org
+Description: Reports the type identification provided by the touchscreen, for example "PCAP82H80 Series"
+
+ Access: Read
+
+ Valid values: Represented as string
diff --git a/Documentation/ABI/testing/sysfs-driver-intc_sar b/Documentation/ABI/testing/sysfs-driver-intc_sar
new file mode 100644
index 000000000000..ec334b0e5ed9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intc_sar
@@ -0,0 +1,54 @@
+What: /sys/bus/platform/devices/INTC1092:00/intc_reg
+Date: August 2021
+KernelVersion: 5.15
+Contact: Shravan S <s.shravan@intel.com>,
+ An Sudhakar <sudhakar.an@intel.com>
+Description:
+ Specific Absorption Rate (SAR) regulatory mode is typically
+ derived based on information like mcc (Mobile Country Code) and
+ mnc (Mobile Network Code) that is available for the currently
+ attached LTE network. A userspace application is required to set
+ the current SAR regulatory mode on the Dynamic SAR driver using
+ this sysfs node. Such an application can also read back using
+ this sysfs node, the currently configured regulatory mode value
+ from the Dynamic SAR driver.
+
+ Acceptable regulatory modes are:
+ == ====
+ 0 FCC
+ 1 CE
+ 2 ISED
+ == ====
+
+ - The regulatory mode value has one of the above values.
+ - The default regulatory mode used in the driver is 0.
+
+What: /sys/bus/platform/devices/INTC1092:00/intc_data
+Date: August 2021
+KernelVersion: 5.15
+Contact: Shravan S <s.shravan@intel.com>,
+ An Sudhakar <sudhakar.an@intel.com>
+Description:
+ This sysfs entry is used to retrieve Dynamic SAR information
+ emitted/maintained by a BIOS that supports Dynamic SAR.
+
+ The retrieved information is in the order given below:
+ - device_mode
+ - bandtable_index
+ - antennatable_index
+ - sartable_index
+
+ The above information is sent as integer values separated
+ by a single space. This information can then be pushed to a
+ WWAN modem that uses this to control the transmit signal
+ level using the Band/Antenna/SAR table index information.
+ These parameters are derived/decided by aggregating
+ device-mode like laptop/tablet/clamshell etc. and the
+ proximity-sensor data available to the embedded controller on
+ given host. The regulatory mode configured on Dynamic SAR
+ driver also influences these values.
+
+ The userspace applications can poll for changes to this file
+ using POLLPRI event on file-descriptor (fd) obtained by opening
+ this sysfs entry. Application can then read this information from
+ the sysfs node and consume the given information.
diff --git a/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon b/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon
new file mode 100644
index 000000000000..a885e5316d02
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon
@@ -0,0 +1,93 @@
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/in0_input
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RO. Current Voltage in millivolt.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/power1_max
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RW. Card reactive sustained (PL1/Tau) power limit in microwatts.
+
+ The power controller will throttle the operating frequency
+ if the power averaged over a window (typically seconds)
+ exceeds this limit. A read value of 0 means that the PL1
+ power limit is disabled, writing 0 disables the
+ limit. Writing values > 0 will enable the power limit.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/power1_rated_max
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RO. Card default power limit (default TDP setting).
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/power1_max_interval
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RW. Sustained power limit interval (Tau in PL1/Tau) in
+ milliseconds over which sustained power is averaged.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/power1_crit
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RW. Card reactive critical (I1) power limit in microwatts.
+
+ Card reactive critical (I1) power limit in microwatts is exposed
+ for client products. The power controller will throttle the
+ operating frequency if the power averaged over a window exceeds
+ this limit.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/curr1_crit
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RW. Card reactive critical (I1) power limit in milliamperes.
+
+ Card reactive critical (I1) power limit in milliamperes is
+ exposed for server products. The power controller will throttle
+ the operating frequency if the power averaged over a window
+ exceeds this limit.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/energy1_input
+Date: February 2023
+KernelVersion: 6.2
+Contact: intel-gfx@lists.freedesktop.org
+Description: RO. Energy input of device or gt in microjoules.
+
+ For i915 device level hwmon devices (name "i915") this
+ reflects energy input for the entire device. For gt level
+ hwmon devices (name "i915_gtN") this reflects energy input
+ for the gt.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/fan1_input
+Date: November 2024
+KernelVersion: 6.12
+Contact: intel-gfx@lists.freedesktop.org
+Description: RO. Fan speed of device in RPM.
+
+ Only supported for particular Intel i915 graphics platforms.
+
+What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon<i>/temp1_input
+Date: November 2024
+KernelVersion: 6.12
+Contact: intel-gfx@lists.freedesktop.org
+Description: RO. GPU package temperature in millidegree Celsius.
+
+ Only supported for particular Intel i915 graphics platforms.
diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc
new file mode 100644
index 000000000000..faeae8fedb14
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc
@@ -0,0 +1,36 @@
+What: /sys/bus/.../drivers/intel-m10-bmc/.../bmc_version
+Date: June 2020
+KernelVersion: 5.10
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read only. Returns the hardware build version of Intel
+ MAX10 BMC chip.
+ Format: "0x%x".
+
+What: /sys/bus/.../drivers/intel-m10-bmc/.../bmcfw_version
+Date: June 2020
+KernelVersion: 5.10
+Contact: Xu Yilun <yilun.xu@intel.com>
+Description: Read only. Returns the firmware version of Intel MAX10
+ BMC chip.
+ Format: "0x%x".
+
+What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_address
+Date: January 2021
+KernelVersion: 5.12
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns the first MAC address in a block
+ of sequential MAC addresses assigned to the board
+ that is managed by the Intel MAX10 BMC. It is stored in
+ FLASH storage and is mirrored in the MAX10 BMC register
+ space.
+ Format: "%02x:%02x:%02x:%02x:%02x:%02x".
+
+What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_count
+Date: January 2021
+KernelVersion: 5.12
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns the number of sequential MAC
+ addresses assigned to the board managed by the Intel
+ MAX10 BMC. This value is stored in FLASH and is mirrored
+ in the MAX10 BMC register space.
+ Format: "%u".
diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update
new file mode 100644
index 000000000000..3a6ca780c75c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update
@@ -0,0 +1,61 @@
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/sr_root_entry_hash
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns the root entry hash for the static
+ region if one is programmed, else it returns the
+ string: "hash not programmed". This file is only
+ visible if the underlying device supports it.
+ Format: string.
+
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/pr_root_entry_hash
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns the root entry hash for the partial
+ reconfiguration region if one is programmed, else it
+ returns the string: "hash not programmed". This file
+ is only visible if the underlying device supports it.
+ Format: string.
+
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/bmc_root_entry_hash
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns the root entry hash for the BMC image
+ if one is programmed, else it returns the string:
+ "hash not programmed". This file is only visible if the
+ underlying device supports it.
+ Format: string.
+
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/sr_canceled_csks
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns a list of indices for canceled code
+ signing keys for the static region. The standard bitmap
+ list format is used (e.g. "1,2-6,9").
+
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/pr_canceled_csks
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns a list of indices for canceled code
+ signing keys for the partial reconfiguration region. The
+ standard bitmap list format is used (e.g. "1,2-6,9").
+
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/bmc_canceled_csks
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns a list of indices for canceled code
+ signing keys for the BMC. The standard bitmap list format
+ is used (e.g. "1,2-6,9").
+
+What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/flash_count
+Date: Sep 2022
+KernelVersion: 5.20
+Contact: Matthew Gerlach <matthew.gerlach@altera.com>
+Description: Read only. Returns number of times the secure update
+ staging area has been flashed.
+ Format: "%u".
diff --git a/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon b/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon
new file mode 100644
index 000000000000..d9e2b17c6872
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon
@@ -0,0 +1,198 @@
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power1_max
+Date: September 2023
+KernelVersion: 6.5
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Card reactive sustained (PL1) power limit in microwatts.
+
+ The power controller will throttle the operating frequency
+ if the power averaged over a window (typically seconds)
+ exceeds this limit. A read value of 0 means that the PL1
+ power limit is disabled, writing 0 disables the
+ limit. Writing values > 0 and <= TDP will enable the power limit.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power1_rated_max
+Date: September 2023
+KernelVersion: 6.5
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Card default power limit (default TDP setting).
+
+ Only supported for particular Intel Xe graphics platforms.
+
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/energy1_input
+Date: September 2023
+KernelVersion: 6.5
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Card energy input of device in microjoules.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power1_max_interval
+Date: October 2023
+KernelVersion: 6.6
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Card sustained power limit interval (Tau in PL1/Tau) in
+ milliseconds over which sustained power is averaged.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power2_max
+Date: February 2024
+KernelVersion: 6.8
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Package reactive sustained (PL1) power limit in microwatts.
+
+ The power controller will throttle the operating frequency
+ if the power averaged over a window (typically seconds)
+ exceeds this limit. A read value of 0 means that the PL1
+ power limit is disabled, writing 0 disables the
+ limit. Writing values > 0 and <= TDP will enable the power limit.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power2_rated_max
+Date: February 2024
+KernelVersion: 6.8
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Package default power limit (default TDP setting).
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power1_crit
+Date: May 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Card reactive critical (I1) power limit in microwatts.
+
+ Card reactive critical (I1) power limit in microwatts is exposed
+ for client products. The power controller will throttle the
+ operating frequency if the power averaged over a window exceeds
+ this limit.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/curr1_crit
+Date: May 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Card reactive critical (I1) power limit in milliamperes.
+
+ Card reactive critical (I1) power limit in milliamperes is
+ exposed for server products. The power controller will throttle
+ the operating frequency if the power averaged over a window
+ exceeds this limit.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/energy2_input
+Date: February 2024
+KernelVersion: 6.8
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Package energy input of device in microjoules.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power2_max_interval
+Date: February 2024
+KernelVersion: 6.8
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Package sustained power limit interval (Tau in PL1/Tau) in
+ milliseconds over which sustained power is averaged.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/in1_input
+Date: February 2024
+KernelVersion: 6.8
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Package current voltage in millivolt.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/temp2_input
+Date: March 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Package temperature in millidegree Celsius.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/temp3_input
+Date: March 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. VRAM temperature in millidegree Celsius.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/fan1_input
+Date: March 2025
+KernelVersion: 6.16
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Fan 1 speed in RPM.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/fan2_input
+Date: March 2025
+KernelVersion: 6.16
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Fan 2 speed in RPM.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/fan3_input
+Date: March 2025
+KernelVersion: 6.16
+Contact: intel-xe@lists.freedesktop.org
+Description: RO. Fan 3 speed in RPM.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power1_cap
+Date: May 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Card burst (PL2) power limit in microwatts.
+
+ The power controller will throttle the operating frequency
+ if the power averaged over a window (typically milli seconds)
+ exceeds this limit. A read value of 0 means that the PL2
+ power limit is disabled, writing 0 disables the limit.
+ PL2 is greater than PL1 and its time window is lesser
+ compared to PL1.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power2_cap
+Date: May 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Package burst (PL2) power limit in microwatts.
+
+ The power controller will throttle the operating frequency
+ if the power averaged over a window (typically milli seconds)
+ exceeds this limit. A read value of 0 means that the PL2
+ power limit is disabled, writing 0 disables the limit.
+ PL2 is greater than PL1 and its time window is lesser
+ compared to PL1.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power1_cap_interval
+Date: May 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Card burst power limit interval (Tau in PL2/Tau) in
+ milliseconds over which sustained power is averaged.
+
+ Only supported for particular Intel Xe graphics platforms.
+
+What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/power2_cap_interval
+Date: May 2025
+KernelVersion: 6.15
+Contact: intel-xe@lists.freedesktop.org
+Description: RW. Package burst power limit interval (Tau in PL2/Tau) in
+ milliseconds over which sustained power is averaged.
+
+ Only supported for particular Intel Xe graphics platforms.
diff --git a/Documentation/ABI/testing/sysfs-driver-intel-xe-sriov b/Documentation/ABI/testing/sysfs-driver-intel-xe-sriov
new file mode 100644
index 000000000000..2fd7e9b7bacc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intel-xe-sriov
@@ -0,0 +1,159 @@
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ This directory appears for the particular Intel Xe device when:
+
+ - device supports SR-IOV, and
+ - device is a Physical Function (PF), and
+ - driver support for the SR-IOV PF is enabled on given device.
+
+ This directory is used as a root for all attributes required to
+ manage both Physical Function (PF) and Virtual Functions (VFs).
+
+
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/pf/
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ This directory holds attributes related to the SR-IOV Physical
+ Function (PF).
+
+
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf1/
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf2/
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf<N>/
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ These directories hold attributes related to the SR-IOV Virtual
+ Functions (VFs).
+
+ Note that the VF number <N> is 1-based as described in PCI SR-IOV
+ specification as the Xe driver follows that naming schema.
+
+ There could be "vf1", "vf2" and so on, up to "vf<N>", where <N>
+ matches the value of the "sriov_totalvfs" attribute.
+
+
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/pf/profile/exec_quantum_ms
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/pf/profile/preempt_timeout_us
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/pf/profile/sched_priority
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf<n>/profile/exec_quantum_ms
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf<n>/profile/preempt_timeout_us
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf<n>/profile/sched_priority
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ These files expose scheduling parameters for the PF and its VFs, and
+ are visible only on Intel Xe platforms that use time-sliced GPU sharing.
+ They can be changed even if VFs are enabled and running and reflect the
+ settings of all tiles/GTs assigned to the given function.
+
+ exec_quantum_ms: (RW) unsigned integer
+ The GT execution quantum (EQ) in [ms] for the given function.
+ Actual quantum value might be aligned per HW/FW requirements.
+
+ Default is 0 (unlimited).
+
+ preempt_timeout_us: (RW) unsigned integer
+ The GT preemption timeout in [us] of the given function.
+ Actual timeout value might be aligned per HW/FW requirements.
+
+ Default is 0 (unlimited).
+
+ sched_priority: (RW/RO) string
+ The GT scheduling priority of the given function.
+
+ "low" - function will be scheduled on the GPU for its EQ/PT
+ only if function has any work already submitted.
+
+ "normal" - functions will be scheduled on the GPU for its EQ/PT
+ irrespective of whether it has submitted a work or not.
+
+ "high" - function will be scheduled on the GPU for its EQ/PT
+ in the next time-slice after the current one completes
+ and function has a work submitted.
+
+ Default is "low".
+
+ When read, this file will display the current and available
+ scheduling priorities. The currently active priority level will
+ be enclosed in square brackets, like:
+
+ [low] normal high
+
+ This file can be read-only if changing the priority is not
+ supported.
+
+ Writes to these attributes may fail with errors like:
+ -EINVAL if provided input is malformed or not recognized,
+ -EPERM if change is not applicable on given HW/FW,
+ -EIO if FW refuses to change the provisioning.
+
+ Reads from these attributes may fail with:
+ -EUCLEAN if value is not consistent across all tiles/GTs.
+
+
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/.bulk_profile/exec_quantum_ms
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/.bulk_profile/preempt_timeout_us
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/.bulk_profile/sched_priority
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ These files allows bulk reconfiguration of the scheduling parameters
+ of the PF or VFs and are available only for Intel Xe platforms with
+ GPU sharing based on the time-slice basis. These scheduling parameters
+ can be changed even if VFs are enabled and running.
+
+ exec_quantum_ms: (WO) unsigned integer
+ The GT execution quantum (EQ) in [ms] to be applied to all functions.
+ See sriov_admin/{pf,vf<N>}/profile/exec_quantum_ms for more details.
+
+ preempt_timeout_us: (WO) unsigned integer
+ The GT preemption timeout (PT) in [us] to be applied to all functions.
+ See sriov_admin/{pf,vf<N>}/profile/preempt_timeout_us for more details.
+
+ sched_priority: (RW/RO) string
+ The GT scheduling priority to be applied for all functions.
+ See sriov_admin/{pf,vf<N>}/profile/sched_priority for more details.
+
+ Writes to these attributes may fail with errors like:
+ -EINVAL if provided input is malformed or not recognized,
+ -EPERM if change is not applicable on given HW/FW,
+ -EIO if FW refuses to change the provisioning.
+
+
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf<n>/stop
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ This file allows to control scheduling of the VF on the Intel Xe GPU
+ platforms. It allows to implement custom policy mechanism in case VFs
+ are misbehaving or triggering adverse events above defined thresholds.
+
+ stop: (WO) bool
+ All GT executions of given function shall be immediately stopped.
+ To allow scheduling this VF again, the VF FLR must be triggered.
+
+ Writes to this attribute may fail with errors like:
+ -EINVAL if provided input is malformed or not recognized,
+ -EPERM if change is not applicable on given HW/FW,
+ -EIO if FW refuses to change the scheduling.
+
+
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/pf/device
+What: /sys/bus/pci/drivers/xe/.../sriov_admin/vf<n>/device
+Date: October 2025
+KernelVersion: 6.19
+Contact: intel-xe@lists.freedesktop.org
+Description:
+ These are symlinks to the underlying PCI device entry representing
+ given Xe SR-IOV function. For the PF, this link is always present.
+ For VFs, this link is present only for currently enabled VFs.
diff --git a/Documentation/ABI/testing/sysfs-driver-intel_sdsi b/Documentation/ABI/testing/sysfs-driver-intel_sdsi
new file mode 100644
index 000000000000..f8afed127107
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-intel_sdsi
@@ -0,0 +1,90 @@
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ This directory contains interface files for accessing Intel
+ On Demand (formerly Software Defined Silicon or SDSi) features
+ on a CPU. X represents the socket instance (though not the
+ socket ID). The socket ID is determined by reading the
+ registers file and decoding it per the specification.
+
+ Some files communicate with On Demand hardware through a
+ mailbox. Should the operation fail, one of the following error
+ codes may be returned:
+
+ ========== =====
+ Error Code Cause
+ ========== =====
+ EIO General mailbox failure. Log may indicate cause.
+ EBUSY Mailbox is owned by another agent.
+ EPERM On Demand capability is not enabled in hardware.
+ EPROTO Failure in mailbox protocol detected by driver.
+ See log for details.
+ EOVERFLOW For provision commands, the size of the data
+ exceeds what may be written.
+ ESPIPE Seeking is not allowed.
+ ETIMEDOUT Failure to complete mailbox transaction in time.
+ ========== =====
+
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/guid
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ (RO) The GUID for the registers file. The GUID identifies
+ the layout of the registers file in this directory.
+ Information about the register layouts for a particular GUID
+ is available at http://github.com/intel/intel-sdsi
+
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/registers
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ (RO) Contains information needed by applications to provision
+ a CPU and monitor status information. The layout of this file
+ is determined by the GUID in this directory. Information about
+ the layout for a particular GUID is available at
+ http://github.com/intel/intel-sdsi
+
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/provision_akc
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ (WO) Used to write an Authentication Key Certificate (AKC) to
+ the On Demand NVRAM for the CPU. The AKC is used to authenticate
+ a Capability Activation Payload. Mailbox command.
+
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/provision_cap
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ (WO) Used to write a Capability Activation Payload (CAP) to the
+ On Demand NVRAM for the CPU. CAPs are used to activate a given
+ CPU feature. A CAP is validated by On Demand hardware using a
+ previously provisioned AKC file. Upon successful authentication,
+ the CPU configuration is updated. A cold reboot is required to
+ fully activate the feature. Mailbox command.
+
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/meter_certificate
+Date: Nov 2022
+KernelVersion: 6.2
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ (RO) Used to read back the current meter certificate for the CPU
+ from Intel On Demand hardware. The meter certificate contains
+ utilization metrics of On Demand enabled features. Mailbox
+ command.
+
+What: /sys/bus/auxiliary/devices/intel_vsec.sdsi.X/state_certificate
+Date: Feb 2022
+KernelVersion: 5.18
+Contact: "David E. Box" <david.e.box@linux.intel.com>
+Description:
+ (RO) Used to read back the current state certificate for the CPU
+ from On Demand hardware. The state certificate contains
+ information about the current licenses on the CPU. Mailbox
+ command.
diff --git a/Documentation/ABI/testing/sysfs-driver-jz4780-efuse b/Documentation/ABI/testing/sysfs-driver-jz4780-efuse
new file mode 100644
index 000000000000..4cf595d681e6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-jz4780-efuse
@@ -0,0 +1,20 @@
+What: /sys/devices/*/<our-device>/nvmem
+Date: December 2017
+Contact: PrasannaKumar Muralidharan <prasannatsmkumar@gmail.com>
+Description: read-only access to the efuse on the Ingenic JZ4780 SoC
+ The SoC has a one time programmable 8K efuse that is
+ split into segments. The driver supports read only.
+ The segments are:
+
+ ===== ======== =================
+ 0x000 64 bit Random Number
+ 0x008 128 bit Ingenic Chip ID
+ 0x018 128 bit Customer ID
+ 0x028 3520 bit Reserved
+ 0x1E0 8 bit Protect Segment
+ 0x1E1 2296 bit HDMI Key
+ 0x300 2048 bit Security boot key
+ ===== ======== =================
+
+Users: any user space application which wants to read the Chip
+ and Customer ID
diff --git a/Documentation/ABI/testing/sysfs-driver-panfrost-profiling b/Documentation/ABI/testing/sysfs-driver-panfrost-profiling
new file mode 100644
index 000000000000..7597c420e54b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-panfrost-profiling
@@ -0,0 +1,10 @@
+What: /sys/bus/platform/drivers/panfrost/.../profiling
+Date: February 2024
+KernelVersion: 6.8.0
+Contact: Adrian Larumbe <adrian.larumbe@collabora.com>
+Description:
+ Get/set drm fdinfo's engine and cycles profiling status.
+ Valid values are:
+ 0: Don't enable fdinfo job profiling sources.
+ 1: Enable fdinfo job profiling sources, this enables both the GPU's
+ timestamp and cycle counter registers.
diff --git a/Documentation/ABI/testing/sysfs-driver-panthor-profiling b/Documentation/ABI/testing/sysfs-driver-panthor-profiling
new file mode 100644
index 000000000000..af05fccedc15
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-panthor-profiling
@@ -0,0 +1,10 @@
+What: /sys/bus/platform/drivers/panthor/.../profiling
+Date: September 2024
+KernelVersion: 6.11.0
+Contact: Adrian Larumbe <adrian.larumbe@collabora.com>
+Description:
+ Bitmask to enable drm fdinfo's job profiling measurements.
+ Valid values are:
+ 0: Don't enable fdinfo job profiling sources.
+ 1: Enable GPU cycle measurements for running jobs.
+ 2: Enable GPU timestamp sampling for running jobs.
diff --git a/Documentation/ABI/testing/sysfs-driver-pciback b/Documentation/ABI/testing/sysfs-driver-pciback
index 6a733bfa37e6..49f5fd0c8bbd 100644
--- a/Documentation/ABI/testing/sysfs-driver-pciback
+++ b/Documentation/ABI/testing/sysfs-driver-pciback
@@ -7,7 +7,22 @@ Description:
the format of DDDD:BB:DD.F-REG:SIZE:MASK will allow the guest
to write and read from the PCI device. That is Domain:Bus:
Device.Function-Register:Size:Mask (Domain is optional).
- For example:
- #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks
+ For example::
+
+ #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks
+
will allow the guest to read and write to the configuration
register 0x0E.
+
+What: /sys/bus/pci/drivers/pciback/allow_interrupt_control
+Date: Jan 2020
+KernelVersion: 5.6
+Contact: xen-devel@lists.xenproject.org
+Description:
+ List of devices which can have interrupt control flag (INTx,
+ MSI, MSI-X) set by a connected guest. It is meant to be set
+ only when the guest is a stubdomain hosting device model (qemu)
+ and the actual device is assigned to a HVM. It is not safe
+ (similar to permissive attribute) to set for a devices assigned
+ to a PV guest. The device is automatically removed from this
+ list when the connected pcifront terminates.
diff --git a/Documentation/ABI/testing/sysfs-driver-ppi b/Documentation/ABI/testing/sysfs-driver-ppi
index 7d1435bc976c..1a56fc507689 100644
--- a/Documentation/ABI/testing/sysfs-driver-ppi
+++ b/Documentation/ABI/testing/sysfs-driver-ppi
@@ -1,6 +1,6 @@
-What: /sys/devices/pnp0/<bus-num>/ppi/
+What: /sys/class/tpm/tpmX/ppi/
Date: August 2012
-Kernel Version: 3.6
+KernelVersion: 3.6
Contact: xiaoyan.zhang@intel.com
Description:
This folder includes the attributes related with PPI (Physical
@@ -8,9 +8,14 @@ Description:
folder makes sense. The folder path can be got by command
'find /sys/ -name 'pcrs''. For the detail information of PPI,
please refer to the PPI specification from
+
http://www.trustedcomputinggroup.org/
-What: /sys/devices/pnp0/<bus-num>/ppi/version
+ In Linux 4.2 ppi was moved to the character device directory.
+ A symlink from tpmX/device/ppi to tpmX/ppi to provide backwards
+ compatibility.
+
+What: /sys/class/tpm/tpmX/ppi/version
Date: August 2012
Contact: xiaoyan.zhang@intel.com
Description:
@@ -18,7 +23,7 @@ Description:
platform.
This file is readonly.
-What: /sys/devices/pnp0/<bus-num>/ppi/request
+What: /sys/class/tpm/tpmX/ppi/request
Date: August 2012
Contact: xiaoyan.zhang@intel.com
Description:
@@ -28,7 +33,7 @@ Description:
integer value range from 1 to 160, and 0 means no request.
This file can be read and written.
-What: /sys/devices/pnp0/00:<bus-num>/ppi/response
+What: /sys/class/tpm/tpmX/ppi/response
Date: August 2012
Contact: xiaoyan.zhang@intel.com
Description:
@@ -37,7 +42,7 @@ Description:
: <response description>".
This file is readonly.
-What: /sys/devices/pnp0/<bus-num>/ppi/transition_action
+What: /sys/class/tpm/tpmX/ppi/transition_action
Date: August 2012
Contact: xiaoyan.zhang@intel.com
Description:
@@ -47,7 +52,7 @@ Description:
description>".
This file is readonly.
-What: /sys/devices/pnp0/<bus-num>/ppi/tcg_operations
+What: /sys/class/tpm/tpmX/ppi/tcg_operations
Date: August 2012
Contact: xiaoyan.zhang@intel.com
Description:
@@ -58,7 +63,7 @@ Description:
This attribute is only supported by PPI version 1.2+.
This file is readonly.
-What: /sys/devices/pnp0/<bus-num>/ppi/vs_operations
+What: /sys/class/tpm/tpmX/ppi/vs_operations
Date: August 2012
Contact: xiaoyan.zhang@intel.com
Description:
diff --git a/Documentation/ABI/testing/sysfs-driver-qaic b/Documentation/ABI/testing/sysfs-driver-qaic
new file mode 100644
index 000000000000..f794fd734163
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-qaic
@@ -0,0 +1,18 @@
+What: /sys/bus/pci/drivers/qaic/XXXX:XX:XX.X/ce_count
+Date: May 2025
+KernelVersion: 6.17
+Contact: dri-devel@lists.freedesktop.org
+Description: Number of correctable errors received from device since driver is loaded.
+
+What: /sys/bus/pci/drivers/qaic/XXXX:XX:XX.X/ue_count
+Date: May 2025
+KernelVersion: 6.17
+Contact: dri-devel@lists.freedesktop.org
+Description: Number of uncorrectable errors received from device since driver is loaded.
+
+What: /sys/bus/pci/drivers/qaic/XXXX:XX:XX.X/ue_nonfatal_count
+Date: May 2025
+KernelVersion: 6.17
+Contact: dri-devel@lists.freedesktop.org
+Description: Number of uncorrectable non-fatal errors received from device since driver
+ is loaded.
diff --git a/Documentation/ABI/testing/sysfs-driver-qat b/Documentation/ABI/testing/sysfs-driver-qat
new file mode 100644
index 000000000000..b0561b9fc4eb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-qat
@@ -0,0 +1,167 @@
+What: /sys/bus/pci/devices/<BDF>/qat/state
+Date: June 2022
+KernelVersion: 6.0
+Contact: qat-linux@intel.com
+Description: (RW) Reports the current state of the QAT device. Write to
+ the file to start or stop the device.
+
+ The values are:
+
+ * up: the device is up and running
+ * down: the device is down
+
+
+ It is possible to transition the device from up to down only
+ if the device is up and vice versa.
+
+ This attribute is available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat/cfg_services
+Date: June 2022
+KernelVersion: 6.0
+Contact: qat-linux@intel.com
+Description: (RW) Reports the current configuration of the QAT device.
+ Write to the file to change the configured services.
+
+ One or more services can be enabled per device.
+ Certain configurations are restricted to specific device types;
+ where applicable this is explicitly indicated, for example
+ (qat_6xxx) denotes applicability exclusively to that device series.
+
+ The available services include:
+
+ * sym: Configures the device for symmetric cryptographic operations.
+ * asym: Configures the device for asymmetric cryptographic operations.
+ * dc: Configures the device for compression and decompression
+ operations.
+ * dcc: Similar to dc, but with the additional dc chaining feature
+ enabled, cipher then compress (qat_6xxx), hash then compression.
+ If this is not required choose dc.
+ * decomp: Configures the device for decompression operations (qat_6xxx).
+
+ Service combinations are permitted for all services except dcc.
+ On QAT GEN4 devices (qat_4xxx driver) a maximum of two services can be
+ combined and on QAT GEN6 devices (qat_6xxx driver ) a maximum of three
+ services can be combined.
+ The order of services is not significant. For instance, sym;asym is
+ functionally equivalent to asym;sym.
+
+ It is possible to set the configuration only if the device
+ is in the `down` state (see /sys/bus/pci/devices/<BDF>/qat/state)
+
+ The following example shows how to change the configuration of
+ a device configured for running crypto services in order to
+ run data compression::
+
+ # cat /sys/bus/pci/devices/<BDF>/qat/state
+ up
+ # cat /sys/bus/pci/devices/<BDF>/qat/cfg_services
+ sym;asym
+ # echo down > /sys/bus/pci/devices/<BDF>/qat/state
+ # echo dc > /sys/bus/pci/devices/<BDF>/qat/cfg_services
+ # echo up > /sys/bus/pci/devices/<BDF>/qat/state
+ # cat /sys/bus/pci/devices/<BDF>/qat/cfg_services
+ dc
+
+ This attribute is available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat/pm_idle_enabled
+Date: June 2023
+KernelVersion: 6.5
+Contact: qat-linux@intel.com
+Description: (RW) This configuration option provides a way to force the device into remaining in
+ the MAX power state.
+ If idle support is enabled the device will transition to the `MIN` power state when
+ idle, otherwise will stay in the MAX power state.
+ Write to the file to enable or disable idle support.
+
+ The values are:
+
+ * 0: idle support is disabled
+ * 1: idle support is enabled
+
+ Default value is 1.
+
+ It is possible to set the pm_idle_enabled value only if the device
+ is in the `down` state (see /sys/bus/pci/devices/<BDF>/qat/state)
+
+ The following example shows how to change the pm_idle_enabled of
+ a device::
+
+ # cat /sys/bus/pci/devices/<BDF>/qat/state
+ up
+ # cat /sys/bus/pci/devices/<BDF>/qat/pm_idle_enabled
+ 1
+ # echo down > /sys/bus/pci/devices/<BDF>/qat/state
+ # echo 0 > /sys/bus/pci/devices/<BDF>/qat/pm_idle_enabled
+ # echo up > /sys/bus/pci/devices/<BDF>/qat/state
+ # cat /sys/bus/pci/devices/<BDF>/qat/pm_idle_enabled
+ 0
+
+ This attribute is available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat/rp2srv
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) This attribute provides a way for a user to query a
+ specific ring pair for the type of service that it is currently
+ configured for.
+
+ When written to, the value is cached and used to perform the
+ read operation. Allowed values are in the range 0 to N-1, where
+ N is the max number of ring pairs supported by a device. This
+ can be queried using the attribute qat/num_rps.
+
+ A read returns the service associated to the ring pair queried.
+
+ The values are:
+
+ * dc: the ring pair is configured for running compression services
+ * sym: the ring pair is configured for running symmetric crypto
+ services
+ * asym: the ring pair is configured for running asymmetric crypto
+ services
+
+ Example usage::
+
+ # echo 1 > /sys/bus/pci/devices/<BDF>/qat/rp2srv
+ # cat /sys/bus/pci/devices/<BDF>/qat/rp2srv
+ sym
+
+ This attribute is available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat/num_rps
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RO) Returns the number of ring pairs that a single device has.
+
+ Example usage::
+
+ # cat /sys/bus/pci/devices/<BDF>/qat/num_rps
+ 64
+
+ This attribute is available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat/auto_reset
+Date: May 2024
+KernelVersion: 6.9
+Contact: qat-linux@intel.com
+Description: (RW) Reports the current state of the autoreset feature
+ for a QAT device
+
+ Write to the attribute to enable or disable device auto reset.
+
+ Device auto reset is disabled by default.
+
+ The values are:
+
+ * 1/Yy/on: auto reset enabled. If the device encounters an
+ unrecoverable error, it will be reset automatically.
+ * 0/Nn/off: auto reset disabled. If the device encounters an
+ unrecoverable error, it will not be reset.
+
+ This attribute is available for qat_4xxx and qat_6xxx devices.
diff --git a/Documentation/ABI/testing/sysfs-driver-qat_ras b/Documentation/ABI/testing/sysfs-driver-qat_ras
new file mode 100644
index 000000000000..82ceb04445ec
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-qat_ras
@@ -0,0 +1,41 @@
+What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_correctable
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description: (RO) Reports the number of correctable errors detected by the device.
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_nonfatal
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description: (RO) Reports the number of non fatal errors detected by the device.
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_fatal
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description: (RO) Reports the number of fatal errors detected by the device.
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_ras/reset_error_counters
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description: (WO) Write to resets all error counters of a device.
+
+ The following example reports how to reset the counters::
+
+ # echo 1 > /sys/bus/pci/devices/<BDF>/qat_ras/reset_error_counters
+ # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_correctable
+ 0
+ # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_nonfatal
+ 0
+ # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_fatal
+ 0
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
diff --git a/Documentation/ABI/testing/sysfs-driver-qat_rl b/Documentation/ABI/testing/sysfs-driver-qat_rl
new file mode 100644
index 000000000000..d534f89b4971
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-qat_rl
@@ -0,0 +1,226 @@
+What: /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (WO) This attribute is used to perform an operation on an SLA.
+ The supported operations are: add, update, rm, rm_all, and get.
+
+ Input values must be filled through the associated attribute in
+ this group before a write to this file.
+ If the operation completes successfully, the associated
+ attributes will be updated.
+ The associated attributes are: cir, pir, srv, rp, and id.
+
+ Supported operations:
+
+ * add: Creates a new SLA with the provided inputs from user.
+ * Inputs: cir, pir, srv, and rp
+ * Output: id
+
+ * get: Returns the configuration of the specified SLA in id attribute
+ * Inputs: id
+ * Outputs: cir, pir, srv, and rp
+
+ * update: Updates the SLA with new values set in the following attributes
+ * Inputs: id, cir, and pir
+
+ * rm: Removes the specified SLA in the id attribute.
+ * Inputs: id
+
+ * rm_all: Removes all the configured SLAs.
+ * Inputs: None
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_rl/rp
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) When read, reports the current assigned ring pairs for the
+ queried SLA.
+ When wrote to, configures the ring pairs associated to a new SLA.
+
+ The value is a 64-bit bit mask and is written/displayed in hex.
+ Each bit of this mask represents a single ring pair i.e.,
+ bit 1 == ring pair id 0; bit 3 == ring pair id 2.
+
+ Selected ring pairs must to be assigned to a single service,
+ i.e. the one provided with the srv attribute. The service
+ assigned to a certain ring pair can be checked by querying
+ the attribute qat/rp2srv.
+
+ The maximum number of ring pairs is 4 per SLA.
+
+ Applicability in sla_op:
+
+ * WRITE: add operation
+ * READ: get operation
+
+ Example usage::
+
+ ## Read
+ # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp
+ 0x5
+
+ ## Write
+ # echo 0x5 > /sys/bus/pci/devices/<BDF>/qat_rl/rp
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_rl/id
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) If written to, the value is used to retrieve a particular
+ SLA and operate on it.
+ This is valid only for the following operations: update, rm,
+ and get.
+ A read of this attribute is only guaranteed to have correct data
+ after creation of an SLA.
+
+ Applicability in sla_op:
+
+ * WRITE: rm and update operations
+ * READ: add and get operations
+
+ Example usage::
+
+ ## Read
+ ## Set attributes e.g. cir, pir, srv, etc
+ # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/id
+ 4
+
+ ## Write
+ # echo 7 > /sys/bus/pci/devices/<BDF>/qat_rl/id
+ # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp
+ 0x5 ## ring pair ID 0 and ring pair ID 2
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_rl/cir
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) Committed information rate (CIR). Rate guaranteed to be
+ achieved by a particular SLA. The value is expressed in
+ permille scale, i.e. 1000 refers to the maximum device
+ throughput for a selected service.
+
+ After sending a "get" to sla_op, this will be populated with the
+ CIR for that queried SLA.
+ Write to this file before sending an "add/update" sla_op, to set
+ the SLA to the specified value.
+
+ Applicability in sla_op:
+
+ * WRITE: add and update operations
+ * READ: get operation
+
+ Example usage::
+
+ ## Write
+ # echo 500 > /sys/bus/pci/devices/<BDF>/qat_rl/cir
+ # echo "add" /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+
+ ## Read
+ # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
+ # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/cir
+ 500
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_rl/pir
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) Peak information rate (PIR). The maximum rate that can be
+ achieved by that particular SLA. An SLA can reach a value
+ between CIR and PIR when the device is not fully utilized by
+ requests from other users (assigned to different SLAs).
+
+ After sending a "get" to sla_op, this will be populated with the
+ PIR for that queried SLA.
+ Write to this file before sending an "add/update" sla_op, to set
+ the SLA to the specified value.
+
+ Applicability in sla_op:
+
+ * WRITE: add and update operations
+ * READ: get operation
+
+ Example usage::
+
+ ## Write
+ # echo 750 > /sys/bus/pci/devices/<BDF>/qat_rl/pir
+ # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+
+ ## Read
+ # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
+ # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/pir
+ 750
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_rl/srv
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) Service (SRV). Represents the service (sym, asym, dc)
+ associated to an SLA.
+ Can be written to or queried to set/show the SRV type for an SLA.
+ The SRV attribute is used to specify the SRV type before adding
+ an SLA. After an SLA is configured, reports the service
+ associated to that SLA.
+
+ Applicability in sla_op:
+
+ * WRITE: add and update operations
+ * READ: get operation
+
+ Example usage::
+
+ ## Write
+ # echo "dc" > /sys/bus/pci/devices/<BDF>/qat_rl/srv
+ # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/id
+ 4
+
+ ## Read
+ # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
+ # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/srv
+ dc
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
+
+What: /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
+Date: January 2024
+KernelVersion: 6.7
+Contact: qat-linux@intel.com
+Description:
+ (RW) This file will return the remaining capability for a
+ particular service/sla. This is the remaining value that a new
+ SLA can be set to or a current SLA can be increased with.
+
+ Example usage::
+
+ # echo "asym" > /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
+ 250
+ # echo 250 > /sys/bus/pci/devices/<BDF>/qat_rl/cir
+ # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
+ # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
+ 0
+
+ This attribute is only available for qat_4xxx and qat_6xxx devices.
diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
index 63c1ad0212fc..408cb0ddf4aa 100644
--- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop
+++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
@@ -3,31 +3,23 @@ Date: January 1, 2010
KernelVersion: 2.6.33
Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Description: Some Samsung laptops have different "performance levels"
- that are can be modified by a function key, and by this
+ that can be modified by a function key, and by this
sysfs file. These values don't always make a whole lot
of sense, but some users like to modify them to keep
their fans quiet at all costs. Reading from this file
will show the current performance level. Writing to the
file can change this value.
+
Valid options:
- "silent"
- "normal"
- "overclock"
+ - "silent"
+ - "normal"
+ - "overclock"
+
Note that not all laptops support all of these options.
Specifically, not all support the "overclock" option,
and it's still unknown if this value even changes
anything, other than making the user feel a bit better.
-What: /sys/devices/platform/samsung/battery_life_extender
-Date: December 1, 2011
-KernelVersion: 3.3
-Contact: Corentin Chary <corentin.chary@gmail.com>
-Description: Max battery charge level can be modified, battery cycle
- life can be extended by reducing the max battery charge
- level.
- 0 means normal battery mode (100% charge)
- 1 means battery life extender mode (80% charge)
-
What: /sys/devices/platform/samsung/usb_charge
Date: December 1, 2011
KernelVersion: 3.3
diff --git a/Documentation/ABI/testing/sysfs-driver-spi-intel b/Documentation/ABI/testing/sysfs-driver-spi-intel
new file mode 100644
index 000000000000..d7c9139ddbf3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-spi-intel
@@ -0,0 +1,20 @@
+What: /sys/devices/.../intel_spi_protected
+Date: Feb 2025
+KernelVersion: 6.13
+Contact: Alexander Usyskin <alexander.usyskin@intel.com>
+Description: This attribute allows the userspace to check if the
+ Intel SPI flash controller is write protected from the host.
+
+What: /sys/devices/.../intel_spi_locked
+Date: Feb 2025
+KernelVersion: 6.13
+Contact: Alexander Usyskin <alexander.usyskin@intel.com>
+Description: This attribute allows the user space to check if the
+ Intel SPI flash controller locks supported opcodes.
+
+What: /sys/devices/.../intel_spi_bios_locked
+Date: Feb 2025
+KernelVersion: 6.13
+Contact: Alexander Usyskin <alexander.usyskin@intel.com>
+Description: This attribute allows the user space to check if the
+ Intel SPI flash controller BIOS region is locked for writes.
diff --git a/Documentation/ABI/testing/sysfs-driver-st b/Documentation/ABI/testing/sysfs-driver-st
new file mode 100644
index 000000000000..88cab66fd77f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-st
@@ -0,0 +1,12 @@
+What: /sys/bus/scsi/drivers/st/debug_flag
+Date: October 2015
+KernelVersion: ?.?
+Contact: shane.seymour@hpe.com
+Description:
+ This file allows you to turn debug output from the st driver
+ off if you write a '0' to the file or on if you write a '1'.
+ Note that debug output requires that the module be compiled
+ with the #define DEBUG set to a non-zero value (this is the
+ default). If DEBUG is set to 0 then this file will not
+ appear in sysfs as its presence is conditional upon debug
+ output support being compiled into the module.
diff --git a/Documentation/ABI/testing/sysfs-driver-sunxi-sid b/Documentation/ABI/testing/sysfs-driver-sunxi-sid
deleted file mode 100644
index ffb9536f6ecc..000000000000
--- a/Documentation/ABI/testing/sysfs-driver-sunxi-sid
+++ /dev/null
@@ -1,22 +0,0 @@
-What: /sys/devices/*/<our-device>/eeprom
-Date: August 2013
-Contact: Oliver Schinagl <oliver@schinagl.nl>
-Description: read-only access to the SID (Security-ID) on current
- A-series SoC's from Allwinner. Currently supports A10, A10s, A13
- and A20 CPU's. The earlier A1x series of SoCs exports 16 bytes,
- whereas the newer A20 SoC exposes 512 bytes split into sections.
- Besides the 16 bytes of SID, there's also an SJTAG area,
- HDMI-HDCP key and some custom keys. Below a quick overview, for
- details see the user manual:
- 0x000 128 bit root-key (sun[457]i)
- 0x010 128 bit boot-key (sun7i)
- 0x020 64 bit security-jtag-key (sun7i)
- 0x028 16 bit key configuration (sun7i)
- 0x02b 16 bit custom-vendor-key (sun7i)
- 0x02c 320 bit low general key (sun7i)
- 0x040 32 bit read-control access (sun7i)
- 0x064 224 bit low general key (sun7i)
- 0x080 2304 bit HDCP-key (sun7i)
- 0x1a0 768 bit high general key (sun7i)
-Users: any user space application which wants to read the SID on
- Allwinner's A-series of CPU's.
diff --git a/Documentation/ABI/testing/sysfs-driver-tegra-fuse b/Documentation/ABI/testing/sysfs-driver-tegra-fuse
index 69f5af632657..b8936fad2ccf 100644
--- a/Documentation/ABI/testing/sysfs-driver-tegra-fuse
+++ b/Documentation/ABI/testing/sysfs-driver-tegra-fuse
@@ -3,7 +3,7 @@ Date: February 2014
Contact: Peter De Schrijver <pdeschrijver@nvidia.com>
Description: read-only access to the efuses on Tegra20, Tegra30, Tegra114
and Tegra124 SoC's from NVIDIA. The efuses contain write once
- data programmed at the factory. The data is layed out in 32bit
+ data programmed at the factory. The data is laid out in 32bit
words in LSB first format. Each bit represents a single value
as decoded from the fuse registers. Bits order/assignment
exactly matches the HW registers, including any unused bits.
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
index eed922ef42e5..e5a438d84e1f 100644
--- a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
+++ b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
@@ -4,10 +4,12 @@ KernelVersion: 3.15
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the keyboard backlight operation mode, valid
values are:
+
* 0x1 -> FN-Z
* 0x2 -> AUTO (also called TIMER)
* 0x8 -> ON
* 0x10 -> OFF
+
Note that from kernel 3.16 onwards this file accepts all listed
parameters, kernel 3.15 only accepts the first two (FN-Z and
AUTO).
@@ -41,8 +43,10 @@ KernelVersion: 3.15
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This files controls the status of the touchpad and pointing
stick (if available), valid values are:
+
* 0 -> OFF
* 1 -> ON
+
Users: KToshiba
What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/available_kbd_modes
@@ -51,10 +55,12 @@ KernelVersion: 3.16
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file shows the supported keyboard backlight modes
the system supports, which can be:
+
* 0x1 -> FN-Z
* 0x2 -> AUTO (also called TIMER)
* 0x8 -> ON
* 0x10 -> OFF
+
Note that not all keyboard types support the listed modes.
See the entry named "available_kbd_modes"
Users: KToshiba
@@ -65,6 +71,7 @@ KernelVersion: 3.16
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file shows the current keyboard backlight type,
which can be:
+
* 1 -> Type 1, supporting modes FN-Z and AUTO
* 2 -> Type 2, supporting modes TIMER, ON and OFF
Users: KToshiba
@@ -75,10 +82,12 @@ KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the USB Sleep & Charge charging mode, which
can be:
+
* 0 -> Disabled (0x00)
* 1 -> Alternate (0x09)
* 2 -> Auto (0x21)
* 3 -> Typical (0x11)
+
Note that from kernel 4.1 onwards this file accepts all listed
values, kernel 4.0 only supports the first three.
Note that this feature only works when connected to power, if
@@ -93,8 +102,10 @@ Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the USB Sleep Functions under battery, and
set the level at which point they will be disabled, accepted
values can be:
+
* 0 -> Disabled
* 1-100 -> Battery level to disable sleep functions
+
Currently it prints two values, the first one indicates if the
feature is enabled or disabled, while the second one shows the
current battery level set.
@@ -107,8 +118,10 @@ Date: January 23, 2015
KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the USB Rapid Charge state, which can be:
+
* 0 -> Disabled
* 1 -> Enabled
+
Note that toggling this value requires a reboot for changes to
take effect.
Users: KToshiba
@@ -118,8 +131,10 @@ Date: January 23, 2015
KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the Sleep & Music state, which values can be:
+
* 0 -> Disabled
* 1 -> Enabled
+
Note that this feature only works when connected to power, if
you want to use it under battery, see the entry named
"sleep_functions_on_battery"
@@ -138,6 +153,7 @@ KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the state of the internal fan, valid
values are:
+
* 0 -> OFF
* 1 -> ON
@@ -147,8 +163,10 @@ KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the Special Functions (hotkeys) operation
mode, valid values are:
+
* 0 -> Normal Operation
* 1 -> Special Functions
+
In the "Normal Operation" mode, the F{1-12} keys are as usual
and the hotkeys are accessed via FN-F{1-12}.
In the "Special Functions" mode, the F{1-12} keys trigger the
@@ -163,8 +181,10 @@ KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls whether the laptop should turn ON whenever
the LID is opened, valid values are:
+
* 0 -> Disabled
* 1 -> Enabled
+
Note that toggling this value requires a reboot for changes to
take effect.
Users: KToshiba
@@ -174,8 +194,30 @@ Date: February 12, 2015
KernelVersion: 4.0
Contact: Azael Avalos <coproscefalo@gmail.com>
Description: This file controls the USB 3 functionality, valid values are:
+
* 0 -> Disabled (Acts as a regular USB 2)
* 1 -> Enabled (Full USB 3 functionality)
+
Note that toggling this value requires a reboot for changes to
take effect.
Users: KToshiba
+
+What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/cooling_method
+Date: 2016
+KernelVersion: 4.6
+Contact: Azael Avalos <coproscefalo@gmail.com>
+Description: This file controls the Cooling Method feature.
+ Reading this file prints two values, the first is the actual cooling method
+ and the second is the maximum cooling method supported.
+ When the maximum cooling method is ONE, valid values are:
+
+ * 0 -> Maximum Performance
+ * 1 -> Battery Optimized
+
+ When the maximum cooling method is TWO, valid values are:
+
+ * 0 -> Maximum Performance
+ * 1 -> Performance
+ * 2 -> Battery Optimized
+
+Users: KToshiba
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_haps b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
new file mode 100644
index 000000000000..c938690ce10d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
@@ -0,0 +1,22 @@
+What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/protection_level
+Date: August 16, 2014
+KernelVersion: 3.17
+Contact: Azael Avalos <coproscefalo@gmail.com>
+Description: This file controls the built-in accelerometer protection level,
+ valid values are:
+
+ * 0 -> Disabled
+ * 1 -> Low
+ * 2 -> Medium
+ * 3 -> High
+
+ The default potection value is set to 2 (Medium).
+Users: KToshiba
+
+What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/reset_protection
+Date: August 16, 2014
+KernelVersion: 3.17
+Contact: Azael Avalos <coproscefalo@gmail.com>
+Description: This file turns off the built-in accelerometer for a few
+ seconds and then restore normal operation. Accepting 1 as the
+ only parameter.
diff --git a/Documentation/ABI/testing/sysfs-driver-typec-displayport b/Documentation/ABI/testing/sysfs-driver-typec-displayport
new file mode 100644
index 000000000000..314acd54e13e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-typec-displayport
@@ -0,0 +1,74 @@
+What: /sys/bus/typec/devices/.../displayport/configuration
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ Shows the current DisplayPort configuration for the connector.
+ Valid values are USB, source and sink. Source means DisplayPort
+ source, and sink means DisplayPort sink.
+
+ All supported configurations are listed as space separated list
+ with the active one wrapped in square brackets.
+
+ Source example:
+
+ USB [source] sink
+
+ The configuration can be changed by writing to the file
+
+ Note. USB configuration does not equal to Exit Mode. It is
+ separate configuration defined in VESA DisplayPort Alt Mode on
+ USB Type-C Standard. Functionally it equals to the situation
+ where the mode has been exited (to exit the mode, see
+ Documentation/ABI/testing/sysfs-bus-typec, and use file
+ /sys/bus/typec/devices/.../active).
+
+What: /sys/bus/typec/devices/.../displayport/pin_assignment
+Date: July 2018
+Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com>
+Description:
+ VESA DisplayPort Alt Mode on USB Type-C Standard defines six
+ different pin assignments for USB Type-C connector that are
+ labeled A, B, C, D, E, and F. The supported pin assignments are
+ listed as space separated list with the active one wrapped in
+ square brackets.
+
+ Example:
+
+ C [D]
+
+ Pin assignment can be changed by writing to the file. It is
+ possible to set pin assignment before configuration has been
+ set, but the assignment will not be active before the
+ connector is actually configured.
+
+ Note. As of VESA DisplayPort Alt Mode on USB Type-C Standard
+ version 1.0b, pin assignments A, B, and F are deprecated. Only
+ pin assignment D can now carry simultaneously one channel of
+ USB SuperSpeed protocol. From user perspective pin assignments C
+ and E are equal, where all channels on the connector are used
+ for carrying DisplayPort protocol (allowing higher resolutions).
+
+What: /sys/bus/typec/devices/.../displayport/hpd
+Date: Dec 2022
+Contact: Badhri Jagan Sridharan <badhri@google.com>
+Description:
+ VESA DisplayPort Alt Mode on USB Type-C Standard defines how
+ HotPlugDetect(HPD) shall be supported on the USB-C connector when
+ operating in DisplayPort Alt Mode. This is a read only node which
+ reflects the current state of HPD.
+
+ Valid values:
+ - 1: when HPD’s logical state is high (HPD_High) as defined
+ by VESA DisplayPort Alt Mode on USB Type-C Standard.
+ - 0 when HPD’s logical state is low (HPD_Low) as defined by
+ VESA DisplayPort Alt Mode on USB Type-C Standard.
+
+What: /sys/bus/typec/devices/.../displayport/irq_hpd
+Date: June 2025
+Contact: RD Babiera <rdbabiera@google.com>
+Description:
+ IRQ_HPD events are sent over the USB PD protocol in Status Update and
+ Attention messages. IRQ_HPD can only be asserted when HPD is high,
+ and is asserted when an IRQ_HPD has been issued since the last Status
+ Update. This is a read only node that returns the number of IRQ events
+ raised in the driver's lifetime.
diff --git a/Documentation/ABI/testing/sysfs-driver-uacce b/Documentation/ABI/testing/sysfs-driver-uacce
new file mode 100644
index 000000000000..d3f0b8f3c589
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-uacce
@@ -0,0 +1,57 @@
+What: /sys/class/uacce/<dev_name>/api
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: linux-accelerators@lists.ozlabs.org
+Description: Api of the device
+ Can be any string and up to userspace to parse.
+ Application use the api to match the correct driver
+
+What: /sys/class/uacce/<dev_name>/flags
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: linux-accelerators@lists.ozlabs.org
+Description: Attributes of the device, see UACCE_DEV_xxx flag defined in uacce.h
+
+What: /sys/class/uacce/<dev_name>/available_instances
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: linux-accelerators@lists.ozlabs.org
+Description: Available instances left of the device
+ Return -ENODEV if uacce_ops get_available_instances is not provided
+
+What: /sys/class/uacce/<dev_name>/isolate_strategy
+Date: Nov 2022
+KernelVersion: 6.1
+Contact: linux-accelerators@lists.ozlabs.org
+Description: (RW) A sysfs node that configure the error threshold for the hardware
+ isolation strategy. This size is a configured integer value, which is the
+ number of threshold for hardware errors occurred in one hour. The default is 0.
+ 0 means never isolate the device. The maximum value is 65535. You can write
+ a number of threshold based on your hardware.
+
+What: /sys/class/uacce/<dev_name>/isolate
+Date: Nov 2022
+KernelVersion: 6.1
+Contact: linux-accelerators@lists.ozlabs.org
+Description: (R) A sysfs node that read the device isolated state. The value 1
+ means the device is unavailable. The 0 means the device is
+ available.
+
+What: /sys/class/uacce/<dev_name>/algorithms
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: linux-accelerators@lists.ozlabs.org
+Description: Algorithms supported by this accelerator, separated by new line.
+ Can be any string and up to userspace to parse.
+
+What: /sys/class/uacce/<dev_name>/region_mmio_size
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: linux-accelerators@lists.ozlabs.org
+Description: Size (bytes) of mmio region queue file
+
+What: /sys/class/uacce/<dev_name>/region_dus_size
+Date: Feb 2020
+KernelVersion: 5.7
+Contact: linux-accelerators@lists.ozlabs.org
+Description: Size (bytes) of dus region queue file
diff --git a/Documentation/ABI/testing/sysfs-driver-ucsi-ccg b/Documentation/ABI/testing/sysfs-driver-ucsi-ccg
new file mode 100644
index 000000000000..45cf62ad89e9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-ucsi-ccg
@@ -0,0 +1,6 @@
+What: /sys/bus/i2c/drivers/ucsi_ccg/.../do_flash
+Date: May 2019
+Contact: Ajay Gupta <ajayg@nvidia.com>
+Description:
+ Tell the driver for Cypress CCGx Type-C controller to attempt
+ firmware upgrade by writing [Yy1] to the file.
diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs
new file mode 100644
index 000000000000..a90612ab5780
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-ufs
@@ -0,0 +1,1770 @@
+What: /sys/bus/*/drivers/ufshcd/*/auto_hibern8
+Date: March 2018
+Contact: linux-scsi@vger.kernel.org
+Description:
+ This file contains the auto-hibernate idle timer setting of a
+ UFS host controller. A value of '0' means auto-hibernate is not
+ enabled. Otherwise the value is the number of microseconds of
+ idle time before the UFS host controller will autonomously put
+ the link into hibernate state. That will save power at the
+ expense of increased latency. Note that the hardware supports
+ 10-bit values with a power-of-ten multiplier which allows a
+ maximum value of 102300000. Refer to the UFS Host Controller
+ Interface specification for more details.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_type
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/device_type
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the device type. This is one of the UFS
+ device descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_class
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/device_class
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the device class. This is one of the UFS
+ device descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_sub_class
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/device_sub_class
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the UFS storage subclass. This is one of
+ the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/protocol
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/protocol
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the protocol supported by an UFS device.
+ This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_luns
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/number_of_luns
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows number of logical units. This is one of
+ the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_wluns
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/number_of_wluns
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows number of well known logical units.
+ This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/boot_enable
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/boot_enable
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows value that indicates whether the device is
+ enabled for boot. This is one of the UFS device descriptor
+ parameters. The full information about the descriptor could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/descriptor_access_enable
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/descriptor_access_enable
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows value that indicates whether the device
+ descriptor could be read after partial initialization phase
+ of the boot sequence. This is one of the UFS device descriptor
+ parameters. The full information about the descriptor could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/initial_power_mode
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/initial_power_mode
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows value that defines the power mode after
+ device initialization or hardware reset. This is one of
+ the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/high_priority_lun
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/high_priority_lun
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the high priority lun. This is one of
+ the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/secure_removal_type
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/secure_removal_type
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the secure removal type. This is one of
+ the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/support_security_lun
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/support_security_lun
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether the security lun is supported.
+ This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/bkops_termination_latency
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/bkops_termination_latency
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the background operations termination
+ latency. This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/initial_active_icc_level
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/initial_active_icc_level
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the initial active ICC level. This is one
+ of the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/specification_version
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/specification_version
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the specification version. This is one
+ of the UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturing_date
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/manufacturing_date
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the manufacturing date in BCD format.
+ This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturer_id
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/manufacturer_id
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the manufacturer ID. This is one of the
+ UFS device descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/rtt_capability
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/rtt_capability
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum number of outstanding RTTs
+ supported by the device. This is one of the UFS device
+ descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/rtc_update
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/rtc_update
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the frequency and method of the realtime
+ clock update. This is one of the UFS device descriptor
+ parameters. The full information about the descriptor
+ could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/ufs_features
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/ufs_features
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows which features are supported by the device.
+ This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be
+ found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/ffu_timeout
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/ffu_timeout
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the FFU timeout. This is one of the
+ UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/queue_depth
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/queue_depth
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the device queue depth. This is one of the
+ UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_version
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/device_version
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the device version. This is one of the
+ UFS device descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_secure_wpa
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/number_of_secure_wpa
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows number of secure write protect areas
+ supported by the device. This is one of the UFS device
+ descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/psa_max_data_size
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/psa_max_data_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum amount of data that may be
+ written during the pre-soldering phase of the PSA flow.
+ This is one of the UFS device descriptor parameters.
+ The full information about the descriptor could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/psa_state_timeout
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/psa_state_timeout
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the command maximum timeout for a change
+ in PSA state. This is one of the UFS device descriptor
+ parameters. The full information about the descriptor could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/interconnect_descriptor/unipro_version
+What: /sys/bus/platform/devices/*.ufs/interconnect_descriptor/unipro_version
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the MIPI UniPro version number in BCD format.
+ This is one of the UFS interconnect descriptor parameters.
+ The full information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/interconnect_descriptor/mphy_version
+What: /sys/bus/platform/devices/*.ufs/interconnect_descriptor/mphy_version
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the MIPI M-PHY version number in BCD format.
+ This is one of the UFS interconnect descriptor parameters.
+ The full information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/raw_device_capacity
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/raw_device_capacity
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the total memory quantity available to
+ the user to configure the device logical units. This is one
+ of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_number_of_luns
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/max_number_of_luns
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum number of logical units
+ supported by the UFS device. This is one of the UFS
+ geometry descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/segment_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/segment_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the segment size. This is one of the UFS
+ geometry descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/allocation_unit_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/allocation_unit_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the allocation unit size. This is one of
+ the UFS geometry descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/min_addressable_block_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/min_addressable_block_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the minimum addressable block size. This
+ is one of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at UFS
+ specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/optimal_read_block_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/optimal_read_block_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the optimal read block size. This is one
+ of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at UFS
+ specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/optimal_write_block_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/optimal_write_block_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the optimal write block size. This is one
+ of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at UFS
+ specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_in_buffer_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/max_in_buffer_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum data-in buffer size. This
+ is one of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at UFS
+ specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_out_buffer_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/max_out_buffer_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum data-out buffer size. This
+ is one of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at UFS
+ specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/rpmb_rw_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/rpmb_rw_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum number of RPMB frames allowed
+ in Security Protocol In/Out. This is one of the UFS geometry
+ descriptor parameters. The full information about the
+ descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/dyn_capacity_resource_policy
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/dyn_capacity_resource_policy
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the dynamic capacity resource policy. This
+ is one of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/data_ordering
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/data_ordering
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows support for out-of-order data transfer.
+ This is one of the UFS geometry descriptor parameters.
+ The full information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_number_of_contexts
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/max_number_of_contexts
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows maximum available number of contexts which
+ are supported by the device. This is one of the UFS geometry
+ descriptor parameters. The full information about the
+ descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/sys_data_tag_unit_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/sys_data_tag_unit_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows system data tag unit size. This is one of
+ the UFS geometry descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/sys_data_tag_resource_size
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/sys_data_tag_resource_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows maximum storage area size allocated by
+ the device to handle system data by the tagging mechanism.
+ This is one of the UFS geometry descriptor parameters.
+ The full information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/secure_removal_types
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/secure_removal_types
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows supported secure removal types. This is
+ one of the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/memory_types
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/memory_types
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows supported memory types. This is one of
+ the UFS geometry descriptor parameters. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/*_memory_max_alloc_units
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/*_memory_max_alloc_units
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum number of allocation units for
+ different memory types (system code, non persistent,
+ enhanced type 1-4). This is one of the UFS geometry
+ descriptor parameters. The full information about the
+ descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/*_memory_capacity_adjustment_factor
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/*_memory_capacity_adjustment_factor
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the memory capacity adjustment factor for
+ different memory types (system code, non persistent,
+ enhanced type 1-4). This is one of the UFS geometry
+ descriptor parameters. The full information about the
+ descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/health_descriptor/eol_info
+What: /sys/bus/platform/devices/*.ufs/health_descriptor/eol_info
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows preend of life information. This is one
+ of the UFS health descriptor parameters. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/health_descriptor/life_time_estimation_a
+What: /sys/bus/platform/devices/*.ufs/health_descriptor/life_time_estimation_a
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows indication of the device life time
+ (method a). This is one of the UFS health descriptor
+ parameters. The full information about the descriptor
+ could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/health_descriptor/life_time_estimation_b
+What: /sys/bus/platform/devices/*.ufs/health_descriptor/life_time_estimation_b
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows indication of the device life time
+ (method b). This is one of the UFS health descriptor
+ parameters. The full information about the descriptor
+ could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_descriptor/active_icc_levels_vcc*
+What: /sys/bus/platform/devices/*.ufs/power_descriptor/active_icc_levels_vcc*
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows maximum VCC, VCCQ and VCCQ2 value for
+ active ICC levels from 0 to 15. This is one of the UFS
+ power descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/manufacturer_name
+What: /sys/bus/platform/devices/*.ufs/string_descriptors/manufacturer_name
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file contains a device manufacturer name string.
+ The full information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/product_name
+What: /sys/bus/platform/devices/*.ufs/string_descriptors/product_name
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file contains a product name string. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/oem_id
+What: /sys/bus/platform/devices/*.ufs/string_descriptors/oem_id
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file contains a OEM ID string. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/serial_number
+What: /sys/bus/platform/devices/*.ufs/string_descriptors/serial_number
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file contains a device serial number string. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/product_revision
+What: /sys/bus/platform/devices/*.ufs/string_descriptors/product_revision
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file contains a product revision string. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/boot_lun_id
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows boot LUN information. This is one of
+ the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/lun_write_protect
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows LUN write protection status. This is one of
+ the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/lun_queue_depth
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows LUN queue depth. This is one of the UFS
+ unit descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/psa_sensitive
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows PSA sensitivity. This is one of the UFS
+ unit descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/lun_memory_type
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows LUN memory type. This is one of the UFS
+ unit descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/data_reliability
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file defines the device behavior when a power failure
+ occurs during a write operation. This is one of the UFS
+ unit descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/logical_block_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the size of addressable logical blocks
+ (calculated as an exponent with base 2). This is one of
+ the UFS unit descriptor parameters. The full information about
+ the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/logical_block_count
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows total number of addressable logical blocks.
+ This is one of the UFS unit descriptor parameters. The full
+ information about the descriptor could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/erase_block_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the erase block size. This is one of
+ the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/provisioning_type
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the thin provisioning type. This is one of
+ the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/physical_memory_resource_count
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the total physical memory resources. This is
+ one of the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/context_capabilities
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the context capabilities. This is one of
+ the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/large_unit_granularity
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the granularity of the LUN. This is one of
+ the UFS unit descriptor parameters. The full information
+ about the descriptor could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/device_init
+What: /sys/bus/platform/devices/*.ufs/flags/device_init
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the device init status. The full information
+ about the flag could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/permanent_wpe
+What: /sys/bus/platform/devices/*.ufs/flags/permanent_wpe
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether permanent write protection is enabled.
+ The full information about the flag could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/power_on_wpe
+What: /sys/bus/platform/devices/*.ufs/flags/power_on_wpe
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether write protection is enabled on all
+ logical units configured as power on write protected. The
+ full information about the flag could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/bkops_enable
+What: /sys/bus/platform/devices/*.ufs/flags/bkops_enable
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether the device background operations are
+ enabled. The full information about the flag could be
+ found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/life_span_mode_enable
+What: /sys/bus/platform/devices/*.ufs/flags/life_span_mode_enable
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether the device life span mode is enabled.
+ The full information about the flag could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/phy_resource_removal
+What: /sys/bus/platform/devices/*.ufs/flags/phy_resource_removal
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether physical resource removal is enable.
+ The full information about the flag could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/busy_rtc
+What: /sys/bus/platform/devices/*.ufs/flags/busy_rtc
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether the device is executing internal
+ operation related to real time clock. The full information
+ about the flag could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/disable_fw_update
+What: /sys/bus/platform/devices/*.ufs/flags/disable_fw_update
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether the device FW update is permanently
+ disabled. The full information about the flag could be found
+ at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/boot_lun_enabled
+What: /sys/bus/platform/devices/*.ufs/attributes/boot_lun_enabled
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the boot lun enabled UFS device attribute.
+ The full information about the attribute could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/current_power_mode
+What: /sys/bus/platform/devices/*.ufs/attributes/current_power_mode
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the current power mode UFS device attribute.
+ The full information about the attribute could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/active_icc_level
+What: /sys/bus/platform/devices/*.ufs/attributes/active_icc_level
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the active icc level UFS device attribute.
+ The full information about the attribute could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/ooo_data_enabled
+What: /sys/bus/platform/devices/*.ufs/attributes/ooo_data_enabled
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the out of order data transfer enabled UFS
+ device attribute. The full information about the attribute
+ could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/bkops_status
+What: /sys/bus/platform/devices/*.ufs/attributes/bkops_status
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the background operations status UFS device
+ attribute. The full information about the attribute could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/purge_status
+What: /sys/bus/platform/devices/*.ufs/attributes/purge_status
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the purge operation status UFS device
+ attribute. The full information about the attribute could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_data_in_size
+What: /sys/bus/platform/devices/*.ufs/attributes/max_data_in_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum data size in a DATA IN
+ UPIU. The full information about the attribute could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_data_out_size
+What: /sys/bus/platform/devices/*.ufs/attributes/max_data_out_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the maximum number of bytes that can be
+ requested with a READY TO TRANSFER UPIU. The full information
+ about the attribute could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/reference_clock_frequency
+What: /sys/bus/platform/devices/*.ufs/attributes/reference_clock_frequency
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the reference clock frequency UFS device
+ attribute. The full information about the attribute could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/configuration_descriptor_lock
+What: /sys/bus/platform/devices/*.ufs/attributes/configuration_descriptor_lock
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows whether the configuration descriptor is locked.
+ The full information about the attribute could be found at
+ UFS specifications 2.1. The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/max_number_of_rtt
+What: /sys/bus/platform/devices/*.ufs/attributes/max_number_of_rtt
+Date: May 2024
+Contact: Avri Altman <avri.altman@wdc.com>
+Description: This file provides the maximum current number of
+ outstanding RTTs in device that is allowed. bMaxNumOfRTT is a
+ read-write persistent attribute and is equal to two after device
+ manufacturing. It shall not be set to a value greater than
+ bDeviceRTTCap value, and it may be set only when the hw queues are
+ empty.
+
+ The file is read write.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/exception_event_control
+What: /sys/bus/platform/devices/*.ufs/attributes/exception_event_control
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the exception event control UFS device
+ attribute. The full information about the attribute could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/exception_event_status
+What: /sys/bus/platform/devices/*.ufs/attributes/exception_event_status
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the exception event status UFS device
+ attribute. The full information about the attribute could
+ be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/ffu_status
+What: /sys/bus/platform/devices/*.ufs/attributes/ffu_status
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file provides the ffu status UFS device attribute.
+ The full information about the attribute could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/psa_state
+What: /sys/bus/platform/devices/*.ufs/attributes/psa_state
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file show the PSA feature status. The full information
+ about the attribute could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/psa_data_size
+What: /sys/bus/platform/devices/*.ufs/attributes/psa_data_size
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the amount of data that the host plans to
+ load to all logical units in pre-soldering state.
+ The full information about the attribute could be found at
+ UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/class/scsi_device/*/device/dyn_cap_needed
+Date: February 2018
+Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
+Description: This file shows the amount of physical memory needed
+ to be removed from the physical memory resources pool of
+ the particular logical unit. The full information about
+ the attribute could be found at UFS specifications 2.1.
+
+ The file is read only.
+
+
+What: /sys/bus/platform/drivers/ufshcd/*/rpm_lvl
+What: /sys/bus/platform/devices/*.ufs/rpm_lvl
+Date: September 2014
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This entry could be used to set or show the UFS device
+ runtime power management level. The current driver
+ implementation supports 7 levels with next target states:
+
+ == ====================================================
+ 0 UFS device will stay active, UIC link will
+ stay active
+ 1 UFS device will stay active, UIC link will
+ hibernate
+ 2 UFS device will be moved to sleep, UIC link will
+ stay active
+ 3 UFS device will be moved to sleep, UIC link will
+ hibernate
+ 4 UFS device will be powered off, UIC link will
+ hibernate
+ 5 UFS device will be powered off, UIC link will
+ be powered off
+ 6 UFS device will be moved to deep sleep, UIC link
+ will be powered off. Note, deep sleep might not be
+ supported in which case this value will not be
+ accepted
+ == ====================================================
+
+What: /sys/bus/platform/drivers/ufshcd/*/rpm_target_dev_state
+What: /sys/bus/platform/devices/*.ufs/rpm_target_dev_state
+Date: February 2018
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This entry shows the target power mode of an UFS device
+ for the chosen runtime power management level.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/rpm_target_link_state
+What: /sys/bus/platform/devices/*.ufs/rpm_target_link_state
+Date: February 2018
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This entry shows the target state of an UFS UIC link
+ for the chosen runtime power management level.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/spm_lvl
+What: /sys/bus/platform/devices/*.ufs/spm_lvl
+Date: September 2014
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This entry could be used to set or show the UFS device
+ system power management level. The current driver
+ implementation supports 7 levels with next target states:
+
+ == ====================================================
+ 0 UFS device will stay active, UIC link will
+ stay active
+ 1 UFS device will stay active, UIC link will
+ hibernate
+ 2 UFS device will be moved to sleep, UIC link will
+ stay active
+ 3 UFS device will be moved to sleep, UIC link will
+ hibernate
+ 4 UFS device will be powered off, UIC link will
+ hibernate
+ 5 UFS device will be powered off, UIC link will
+ be powered off
+ 6 UFS device will be moved to deep sleep, UIC link
+ will be powered off. Note, deep sleep might not be
+ supported in which case this value will not be
+ accepted
+ == ====================================================
+
+What: /sys/bus/platform/drivers/ufshcd/*/spm_target_dev_state
+What: /sys/bus/platform/devices/*.ufs/spm_target_dev_state
+Date: February 2018
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This entry shows the target power mode of an UFS device
+ for the chosen system power management level.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/spm_target_link_state
+What: /sys/bus/platform/devices/*.ufs/spm_target_link_state
+Date: February 2018
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This entry shows the target state of an UFS UIC link
+ for the chosen system power management level.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/monitor_enable
+What: /sys/bus/platform/devices/*.ufs/monitor/monitor_enable
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the status of performance monitor enablement
+ and it can be used to start/stop the monitor. When the monitor
+ is stopped, the performance data collected is also cleared.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/monitor_chunk_size
+What: /sys/bus/platform/devices/*.ufs/monitor/monitor_chunk_size
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file tells the monitor to focus on requests transferring
+ data of specific chunk size (in Bytes). 0 means any chunk size.
+ It can only be changed when monitor is disabled.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_total_sectors
+What: /sys/bus/platform/devices/*.ufs/monitor/read_total_sectors
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how many sectors (in 512 Bytes) have been
+ sent from device to host after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_total_busy
+What: /sys/bus/platform/devices/*.ufs/monitor/read_total_busy
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how long (in micro seconds) has been spent
+ sending data from device to host after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_nr_requests
+What: /sys/bus/platform/devices/*.ufs/monitor/read_nr_requests
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how many read requests have been sent after
+ monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_max
+What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_max
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the maximum latency (in micro seconds) of
+ read requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_min
+What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_min
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the minimum latency (in micro seconds) of
+ read requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_avg
+What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_avg
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the average latency (in micro seconds) of
+ read requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/read_req_latency_sum
+What: /sys/bus/platform/devices/*.ufs/monitor/read_req_latency_sum
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the total latency (in micro seconds) of
+ read requests sent after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_total_sectors
+What: /sys/bus/platform/devices/*.ufs/monitor/write_total_sectors
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how many sectors (in 512 Bytes) have been sent
+ from host to device after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_total_busy
+What: /sys/bus/platform/devices/*.ufs/monitor/write_total_busy
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how long (in micro seconds) has been spent
+ sending data from host to device after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_nr_requests
+What: /sys/bus/platform/devices/*.ufs/monitor/write_nr_requests
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how many write requests have been sent after
+ monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_max
+What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_max
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the maximum latency (in micro seconds) of write
+ requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_min
+What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_min
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the minimum latency (in micro seconds) of write
+ requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_avg
+What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_avg
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the average latency (in micro seconds) of write
+ requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/monitor/write_req_latency_sum
+What: /sys/bus/platform/devices/*.ufs/monitor/write_req_latency_sum
+Date: January 2021
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the total latency (in micro seconds) of write
+ requests after monitor gets started.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_info/lane
+What: /sys/bus/platform/devices/*.ufs/power_info/lane
+Date: September 2023
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows how many lanes are enabled on the UFS link,
+ i.e., an output 2 means UFS link is operating with 2 lanes.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_info/mode
+What: /sys/bus/platform/devices/*.ufs/power_info/mode
+Date: September 2023
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the PA power mode of UFS.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_info/rate
+What: /sys/bus/platform/devices/*.ufs/power_info/rate
+Date: September 2023
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the speed rate of UFS link.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_info/gear
+What: /sys/bus/platform/devices/*.ufs/power_info/gear
+Date: September 2023
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the gear of UFS link.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_info/dev_pm
+What: /sys/bus/platform/devices/*.ufs/power_info/dev_pm
+Date: September 2023
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the UFS device power mode.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/power_info/link_state
+What: /sys/bus/platform/devices/*.ufs/power_info/link_state
+Date: September 2023
+Contact: Can Guo <quic_cang@quicinc.com>
+Description: This file shows the state of UFS link.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_presv_us_en
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows if preserve user-space was configured
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_shared_alloc_units
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_shared_alloc_units
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the shared allocated units of WB buffer
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_type
+What: /sys/bus/platform/devices/*.ufs/device_descriptor/wb_type
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the configured WB type.
+ 0x1 for shared buffer mode. 0x0 for dedicated buffer mode.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_buff_cap_adj
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_buff_cap_adj
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the total user-space decrease in shared
+ buffer mode.
+ The value of this parameter is 3 for TLC NAND when SLC mode
+ is used as WriteBooster Buffer. 2 for MLC NAND.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_alloc_units
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_max_alloc_units
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the Maximum total WriteBooster Buffer size
+ which is supported by the entire device.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_wb_luns
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_max_wb_luns
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the maximum number of luns that can support
+ WriteBooster.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_red_type
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_sup_red_type
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: The supportability of user space reduction mode
+ and preserve user space mode.
+ 00h: WriteBooster Buffer can be configured only in
+ user space reduction type.
+ 01h: WriteBooster Buffer can be configured only in
+ preserve user space type.
+ 02h: Device can be configured in either user space
+ reduction type or preserve user space type.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_wb_type
+What: /sys/bus/platform/devices/*.ufs/geometry_descriptor/wb_sup_wb_type
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: The supportability of WriteBooster Buffer type.
+
+ === ==========================================================
+ 00h LU based WriteBooster Buffer configuration
+ 01h Single shared WriteBooster Buffer configuration
+ 02h Supporting both LU based WriteBooster.
+ Buffer and Single shared WriteBooster Buffer configuration
+ === ==========================================================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_enable
+What: /sys/bus/platform/devices/*.ufs/flags/wb_enable
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the status of WriteBooster.
+
+ == ============================
+ 0 WriteBooster is not enabled.
+ 1 WriteBooster is enabled
+ == ============================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_en
+What: /sys/bus/platform/devices/*.ufs/flags/wb_flush_en
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows if flush is enabled.
+
+ == =================================
+ 0 Flush operation is not performed.
+ 1 Flush operation is performed.
+ == =================================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_during_h8
+What: /sys/bus/platform/devices/*.ufs/flags/wb_flush_during_h8
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: Flush WriteBooster Buffer during hibernate state.
+
+ == =================================================
+ 0 Device is not allowed to flush the
+ WriteBooster Buffer during link hibernate state.
+ 1 Device is allowed to flush the
+ WriteBooster Buffer during link hibernate state.
+ == =================================================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_avail_buf
+What: /sys/bus/platform/devices/*.ufs/attributes/wb_avail_buf
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the amount of unused WriteBooster buffer
+ available.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_cur_buf
+What: /sys/bus/platform/devices/*.ufs/attributes/wb_cur_buf
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the amount of unused current buffer.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_flush_status
+What: /sys/bus/platform/devices/*.ufs/attributes/wb_flush_status
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the flush operation status.
+
+
+ === ======================================
+ 00h idle
+ 01h Flush operation in progress
+ 02h Flush operation stopped prematurely.
+ 03h Flush operation completed successfully
+ 04h Flush operation general failure
+ === ======================================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_life_time_est
+What: /sys/bus/platform/devices/*.ufs/attributes/wb_life_time_est
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows an indication of the WriteBooster Buffer
+ lifetime based on the amount of performed program/erase cycles
+
+ === =============================================
+ 01h 0% - 10% WriteBooster Buffer life time used
+ ...
+ 0Ah 90% - 100% WriteBooster Buffer life time used
+ === =============================================
+
+ The file is read only.
+
+What: /sys/class/scsi_device/*/device/unit_descriptor/wb_buf_alloc_units
+Date: June 2020
+Contact: Asutosh Das <quic_asutoshd@quicinc.com>
+Description: This entry shows the configured size of WriteBooster buffer.
+ 0400h corresponds to 4GB.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/wb_on
+What: /sys/bus/platform/devices/*.ufs/wb_on
+Date: January 2021
+Contact: Bean Huo <beanhuo@micron.com>
+Description: This node is used to set or display whether UFS WriteBooster is
+ enabled. Echo 0 to this file to disable UFS WriteBooster or 1 to
+ enable it. The WriteBooster is enabled after power-on/reset,
+ however, it will be disabled/enable while CLK scaling down/up
+ (if the platform supports UFSHCD_CAP_CLK_SCALING). For a
+ platform that doesn't support UFSHCD_CAP_CLK_SCALING, we can
+ disable/enable WriteBooster through this sysfs node.
+
+What: /sys/bus/platform/drivers/ufshcd/*/enable_wb_buf_flush
+What: /sys/bus/platform/devices/*.ufs/enable_wb_buf_flush
+Date: July 2022
+Contact: Jinyoung Choi <j-young.choi@samsung.com>
+Description: This entry shows the status of WriteBooster buffer flushing
+ and it can be used to enable or disable the flushing.
+ If flushing is enabled, the device executes the flush
+ operation when the command queue is empty.
+
+What: /sys/bus/platform/drivers/ufshcd/*/wb_flush_threshold
+What: /sys/bus/platform/devices/*.ufs/wb_flush_threshold
+Date: June 2023
+Contact: Lu Hongfei <luhongfei@vivo.com>
+Description:
+ wb_flush_threshold represents the threshold for flushing WriteBooster buffer,
+ whose value expressed in unit of 10% granularity, such as '1' representing 10%,
+ '2' representing 20%, and so on.
+ If avail_wb_buff < wb_flush_threshold, it indicates that WriteBooster buffer needs to
+ be flushed, otherwise it is not necessary.
+
+Contact: Daniil Lunev <dlunev@chromium.org>
+What: /sys/bus/platform/drivers/ufshcd/*/capabilities/
+What: /sys/bus/platform/devices/*.ufs/capabilities/
+Date: August 2022
+Description: The group represents the effective capabilities of the
+ host-device pair. i.e. the capabilities which are enabled in the
+ driver for the specific host controller, supported by the host
+ controller and are supported and/or have compatible
+ configuration on the device side.
+
+Contact: Daniil Lunev <dlunev@chromium.org>
+What: /sys/bus/platform/drivers/ufshcd/*/capabilities/clock_scaling
+What: /sys/bus/platform/devices/*.ufs/capabilities/clock_scaling
+Date: August 2022
+Contact: Daniil Lunev <dlunev@chromium.org>
+Description: Indicates status of clock scaling.
+
+ == ============================
+ 0 Clock scaling is not supported.
+ 1 Clock scaling is supported.
+ == ============================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/capabilities/write_booster
+What: /sys/bus/platform/devices/*.ufs/capabilities/write_booster
+Date: August 2022
+Contact: Daniil Lunev <dlunev@chromium.org>
+Description: Indicates status of Write Booster.
+
+ == ============================
+ 0 Write Booster can not be enabled.
+ 1 Write Booster can be enabled.
+ == ============================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/rtc_update_ms
+What: /sys/bus/platform/devices/*.ufs/rtc_update_ms
+Date: November 2023
+Contact: Bean Huo <beanhuo@micron.com>
+Description:
+ rtc_update_ms indicates how often the host should synchronize or update the
+ UFS RTC. If set to 0, this will disable UFS RTC periodic update.
+
+What: /sys/devices/platform/.../ufshci_capabilities/version
+Date: August 2024
+Contact: Avri Altman <avri.altman@wdc.com>
+Description:
+ Host Capabilities register group: UFS version register.
+ Symbol - VER. This file shows the UFSHCD version.
+ Example: Version 3.12 would be represented as 0000_0312h.
+ The file is read only.
+
+What: /sys/devices/platform/.../ufshci_capabilities/product_id
+Date: August 2024
+Contact: Avri Altman <avri.altman@wdc.com>
+Description:
+ Host Capabilities register group: product ID register.
+ Symbol - HCPID. This file shows the UFSHCD product id.
+ The content of this register is vendor specific.
+ The file is read only.
+
+What: /sys/devices/platform/.../ufshci_capabilities/man_id
+Date: August 2024
+Contact: Avri Altman <avri.altman@wdc.com>
+Description:
+ Host Capabilities register group: manufacturer ID register.
+ Symbol - HCMID. This file shows the UFSHCD manufacturer id.
+ The Manufacturer ID is defined by JEDEC in JEDEC-JEP106.
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/critical_health
+What: /sys/bus/platform/devices/*.ufs/critical_health
+Date: February 2025
+Contact: Avri Altman <avri.altman@wdc.com>
+Description: Report the number of times a critical health event has been
+ reported by a UFS device. Further insight into the specific
+ issue can be gained by reading one of: bPreEOLInfo,
+ bDeviceLifeTimeEstA, bDeviceLifeTimeEstB,
+ bWriteBoosterBufferLifeTimeEst, and bRPMBLifeTimeEst.
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/clkscale_enable
+What: /sys/bus/platform/devices/*.ufs/clkscale_enable
+Date: January 2025
+Contact: Ziqi Chen <quic_ziqichen@quicinc.com>
+Description:
+ This attribute shows whether the UFS clock scaling is enabled or not.
+ And it can be used to enable/disable the clock scaling by writing
+ 1 or 0 to this attribute.
+
+ The attribute is read/write.
+
+What: /sys/bus/platform/drivers/ufshcd/*/clkgate_enable
+What: /sys/bus/platform/devices/*.ufs/clkgate_enable
+Date: January 2025
+Contact: Ziqi Chen <quic_ziqichen@quicinc.com>
+Description:
+ This attribute shows whether the UFS clock gating is enabled or not.
+ And it can be used to enable/disable the clock gating by writing
+ 1 or 0 to this attribute.
+
+ The attribute is read/write.
+
+What: /sys/bus/platform/drivers/ufshcd/*/clkgate_delay_ms
+What: /sys/bus/platform/devices/*.ufs/clkgate_delay_ms
+Date: January 2025
+Contact: Ziqi Chen <quic_ziqichen@quicinc.com>
+Description:
+ This attribute shows and sets the number of milliseconds of idle time
+ before the UFS driver starts to perform clock gating. This can
+ prevent the UFS from frequently performing clock gating/ungating.
+
+ The attribute is read/write.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_lvl_exception_count
+What: /sys/bus/platform/devices/*.ufs/device_lvl_exception_count
+Date: March 2025
+Contact: Bao D. Nguyen <quic_nguyenb@quicinc.com>
+Description:
+ This attribute is applicable to ufs devices compliant to the
+ JEDEC specifications version 4.1 or later. The
+ device_lvl_exception_count is a counter indicating the number of
+ times the device level exceptions have occurred since the last
+ time this variable is reset. Writing a 0 value to this
+ attribute will reset the device_lvl_exception_count. If the
+ device_lvl_exception_count reads a positive value, the user
+ application should read the device_lvl_exception_id attribute to
+ know more information about the exception.
+
+ The attribute is read/write.
+
+What: /sys/bus/platform/drivers/ufshcd/*/device_lvl_exception_id
+What: /sys/bus/platform/devices/*.ufs/device_lvl_exception_id
+Date: March 2025
+Contact: Bao D. Nguyen <quic_nguyenb@quicinc.com>
+Description:
+ Reading the device_lvl_exception_id returns the
+ qDeviceLevelExceptionID attribute of the ufs device JEDEC
+ specification version 4.1. The definition of the
+ qDeviceLevelExceptionID is the ufs device vendor specific
+ implementation. Refer to the device manufacturer datasheet for
+ more information on the meaning of the qDeviceLevelExceptionID
+ attribute value.
+
+ The attribute is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/wb_resize_enable
+What: /sys/bus/platform/devices/*.ufs/wb_resize_enable
+Date: April 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The host can enable the WriteBooster buffer resize by setting this
+ attribute.
+
+ ======== ======================================
+ idle There is no resize operation
+ decrease Decrease WriteBooster buffer size
+ increase Increase WriteBooster buffer size
+ ======== ======================================
+
+ The file is write only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_resize_hint
+What: /sys/bus/platform/devices/*.ufs/attributes/wb_resize_hint
+Date: April 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ wb_resize_hint indicates hint information about which type of resize
+ for WriteBooster buffer is recommended by the device.
+
+ ========= ======================================
+ keep Recommend keep the buffer size
+ decrease Recommend to decrease the buffer size
+ increase Recommend to increase the buffer size
+ ========= ======================================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_resize_status
+What: /sys/bus/platform/devices/*.ufs/attributes/wb_resize_status
+Date: April 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The host can check the resize operation status of the WriteBooster
+ buffer by reading this attribute.
+
+ ================ ========================================
+ idle Resize operation is not issued
+ in_progress Resize operation in progress
+ complete_success Resize operation completed successfully
+ general_failure Resize operation general failure
+ ================ ========================================
+
+ The file is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/hid/analysis_trigger
+What: /sys/bus/platform/devices/*.ufs/hid/analysis_trigger
+Date: May 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The host can enable or disable HID analysis operation.
+
+ ======= =========================================
+ disable disable HID analysis operation
+ enable enable HID analysis operation
+ ======= =========================================
+
+ The file is write only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/hid/defrag_trigger
+What: /sys/bus/platform/devices/*.ufs/hid/defrag_trigger
+Date: May 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The host can enable or disable HID defragmentation operation.
+
+ ======= =========================================
+ disable disable HID defragmentation operation
+ enable enable HID defragmentation operation
+ ======= =========================================
+
+ The attribute is write only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/hid/fragmented_size
+What: /sys/bus/platform/devices/*.ufs/hid/fragmented_size
+Date: May 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The total fragmented size in the device is reported through
+ this attribute.
+
+ The attribute is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/hid/defrag_size
+What: /sys/bus/platform/devices/*.ufs/hid/defrag_size
+Date: May 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The host sets the size to be defragmented by an HID
+ defragmentation operation.
+
+ The attribute is read/write.
+
+What: /sys/bus/platform/drivers/ufshcd/*/hid/progress_ratio
+What: /sys/bus/platform/devices/*.ufs/hid/progress_ratio
+Date: May 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ Defragmentation progress is reported by this attribute,
+ indicates the ratio of the completed defragmentation size
+ over the requested defragmentation size.
+
+ ==== ============================================
+ 1 1%
+ ...
+ 100 100%
+ ==== ============================================
+
+ The attribute is read only.
+
+What: /sys/bus/platform/drivers/ufshcd/*/hid/state
+What: /sys/bus/platform/devices/*.ufs/hid/state
+Date: May 2025
+Contact: Huan Tang <tanghuan@vivo.com>
+Description:
+ The HID state is reported by this attribute.
+
+ ==================== ===========================
+ idle Idle (analysis required)
+ analysis_in_progress Analysis in progress
+ defrag_required Defrag required
+ defrag_in_progress Defrag in progress
+ defrag_completed Defrag completed
+ defrag_not_required Defrag is not required
+ ==================== ===========================
+
+ The attribute is read only.
diff --git a/Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid b/Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid
new file mode 100644
index 000000000000..6892fe46cea8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid
@@ -0,0 +1,29 @@
+What: /sys/bus/pci/drivers/uio_pci_sva/<pci_dev>/pasid
+Date: September 2025
+Contact: Yaxing Guo <guoyaxing@bosc.ac.cn>
+Description:
+ Process Address Space ID (PASID) assigned by IOMMU driver to
+ the device for use with Shared Virtual Addressing (SVA).
+
+ This read-only attribute exposes the PASID (A 20-bit identifier
+ used in PCIe Address Translation Services and iommu table walks)
+ allocated by the IOMMU driver during sva device binding.
+
+ User-space UIO applications must read this attribute to obtain
+ the PASID and program it into the device's configuration registers.
+ This enables the device to perform DMA using user-space virtual
+ address, with address translation handled by IOMMU.
+
+ UIO User-space applications must:
+ - Opening device and Mapping the device's register space via /dev/uioX
+ (This triggers the IOMMU driver to allocate the PASID)
+ - Reading the PASID from sysfs
+ - Writing the PASID to a device-specific register (with example offset)
+ The code may be like:
+
+ map = mmap(..., "/dev/uio0", ...);
+
+ f = fopen("/sys/.../pasid", "r");
+ fscanf(f, "%d", &pasid);
+
+ map[REG_PASID_OFFSET] = pasid;
diff --git a/Documentation/ABI/testing/sysfs-driver-uniwill-laptop b/Documentation/ABI/testing/sysfs-driver-uniwill-laptop
new file mode 100644
index 000000000000..eaeb659793d2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-uniwill-laptop
@@ -0,0 +1,53 @@
+What: /sys/bus/platform/devices/INOU0000:XX/fn_lock_toggle_enable
+Date: November 2025
+KernelVersion: 6.19
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ Allows userspace applications to enable/disable the FN lock feature
+ of the integrated keyboard by writing "1"/"0" into this file.
+
+ Reading this file returns the current enable status of the FN lock functionality.
+
+What: /sys/bus/platform/devices/INOU0000:XX/super_key_toggle_enable
+Date: November 2025
+KernelVersion: 6.19
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ Allows userspace applications to enable/disable the super key functionality
+ of the integrated keyboard by writing "1"/"0" into this file.
+
+ Reading this file returns the current enable status of the super key functionality.
+
+What: /sys/bus/platform/devices/INOU0000:XX/touchpad_toggle_enable
+Date: November 2025
+KernelVersion: 6.19
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ Allows userspace applications to enable/disable the touchpad toggle functionality
+ of the integrated touchpad by writing "1"/"0" into this file.
+
+ Reading this file returns the current enable status of the touchpad toggle
+ functionality.
+
+What: /sys/bus/platform/devices/INOU0000:XX/rainbow_animation
+Date: November 2025
+KernelVersion: 6.19
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ Forces the integrated lightbar to display a rainbow animation when the machine
+ is not suspended. Writing "1"/"0" into this file enables/disables this
+ functionality.
+
+ Reading this file returns the current status of the rainbow animation functionality.
+
+What: /sys/bus/platform/devices/INOU0000:XX/breathing_in_suspend
+Date: November 2025
+KernelVersion: 6.19
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ Causes the integrated lightbar to display a breathing animation when the machine
+ has been suspended and is running on AC power. Writing "1"/"0" into this file
+ enables/disables this functionality.
+
+ Reading this file returns the current status of the breathing animation
+ functionality.
diff --git a/Documentation/ABI/testing/sysfs-driver-w1_ds28e17 b/Documentation/ABI/testing/sysfs-driver-w1_ds28e17
new file mode 100644
index 000000000000..e92aba4eb594
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-w1_ds28e17
@@ -0,0 +1,24 @@
+What: /sys/bus/w1/devices/19-<id>/speed
+Date: Sep 2017
+KernelVersion: 4.14
+Contact: Jan Kandziora <jjj@gmx.de>
+Description: When written, this file sets the I2C speed on the connected
+ DS28E17 chip. When read, it reads the current setting from
+ the DS28E17 chip.
+
+ Valid values: 100, 400, 900 [kBaud].
+
+ Default 100, can be set by w1_ds28e17.speed= module parameter.
+Users: w1_ds28e17 driver
+
+What: /sys/bus/w1/devices/19-<id>/stretch
+Date: Sep 2017
+KernelVersion: 4.14
+Contact: Jan Kandziora <jjj@gmx.de>
+Description: When written, this file sets the multiplier used to calculate
+ the busy timeout for I2C operations on the connected DS28E17
+ chip. When read, returns the current setting.
+ Valid values: 1 to 9.
+
+ Default 1, can be set by w1_ds28e17.stretch= module parameter.
+Users: w1_ds28e17 driver
diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm
new file mode 100644
index 000000000000..74642c73d29c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
@@ -0,0 +1,190 @@
+What: /sys/bus/w1/devices/.../alarms
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (RW) read or write TH and TL (Temperature High an Low) alarms.
+ Values shall be space separated and in the device range
+ (typical -55 degC to 125 degC), if not values will be trimmed
+ to device min/max capabilities. Values are integer as they are
+ stored in a 8bit register in the device. Lowest value is
+ automatically put to TL. Once set, alarms could be search at
+ master level, refer to Documentation/w1/w1-generic.rst for
+ detailed information
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/.../eeprom_cmd
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (WO) writing that file will either trigger a save of the
+ device data to its embedded EEPROM, either restore data
+ embedded in device EEPROM. Be aware that devices support
+ limited EEPROM writing cycles (typical 50k)
+
+ * 'save': save device RAM to EEPROM
+ * 'restore': restore EEPROM data in device RAM
+
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/.../ext_power
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (RO) return the power status by asking the device
+
+ * '0': device parasite powered
+ * '1': device externally powered
+ * '-xx': xx is kernel error when reading power status
+
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/.../resolution
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (RW) get or set the device resolution (on supported devices,
+ if not, this entry is not present). Note that the resolution
+ will be changed only in device RAM, so it will be cleared when
+ power is lost. Trigger a 'save' to EEPROM command to keep
+ values after power-on. Read or write are :
+
+ * '9..14': device resolution in bit
+ or resolution to set in bit
+ * '-xx': xx is kernel error when reading the resolution
+ * Anything else: do nothing
+
+ Some DS18B20 clones are fixed in 12-bit resolution, so the
+ actual resolution is read back from the chip and verified. Error
+ is reported if the results differ.
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/.../temperature
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (RO) return the temperature in 1/1000 degC.
+
+ * If a bulk read has been triggered, it will directly
+ return the temperature computed when the bulk read
+ occurred, if available. If not yet available, nothing
+ is returned (a debug kernel message is sent), you
+ should retry later on.
+ * If no bulk read has been triggered, it will trigger
+ a conversion and send the result. Note that the
+ conversion duration depend on the resolution (if
+ device support this feature). It takes 94ms in 9bits
+ resolution, 750ms for 12bits.
+
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/.../w1_slave
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (RW) return the temperature in 1/1000 degC.
+ *read*: return 2 lines with the hexa output data sent on the
+ bus, return the CRC check and temperature in 1/1000 degC
+ *write*:
+
+ * '0' : save the 2 or 3 bytes to the device EEPROM
+ (i.e. TH, TL and config register)
+ * '9..14' : set the device resolution in RAM
+ (if supported)
+ * Anything else: do nothing
+
+ refer to Documentation/w1/slaves/w1_therm.rst for detailed
+ information.
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/w1_bus_masterXX/therm_bulk_read
+Date: May 2020
+Contact: Akira Shimahara <akira215corp@gmail.com>
+Description:
+ (RW) trigger a bulk read conversion. read the status
+
+ *read*:
+ * '-1':
+ conversion in progress on at least 1 sensor
+ * '1' :
+ conversion complete but at least one sensor
+ value has not been read yet
+ * '0' :
+ no bulk operation. Reading temperature will
+ trigger a conversion on each device
+
+ *write*:
+ 'trigger': trigger a bulk read on all supporting
+ devices on the bus
+
+ Note that if a bulk read is sent but one sensor is not read
+ immediately, the next access to temperature on this device
+ will return the temperature measured at the time of issue
+ of the bulk read command (not the current temperature).
+Users: any user space application which wants to communicate with
+ w1_term device
+
+
+What: /sys/bus/w1/devices/.../conv_time
+Date: July 2020
+Contact: Ivan Zaentsev <ivan.zaentsev@wirenboard.ru>
+Description:
+ (RW) Get, set, or measure a temperature conversion time. The
+ setting remains active until a resolution change. Then it is
+ reset to default (datasheet) conversion time for a new
+ resolution.
+
+ *read*:
+ Actual conversion time in milliseconds.
+
+ *write*:
+ * '0':
+ Set the default conversion time from the datasheet.
+ * '1':
+ Measure and set the conversion time. Make a single
+ temperature conversion, measure an actual value.
+ Increase it by 20% for temperature range. A new
+ conversion time can be obtained by reading this
+ same attribute.
+ * other positive value:
+ Set the conversion time in milliseconds.
+
+Users: An application using the w1_term device
+
+
+What: /sys/bus/w1/devices/.../features
+Date: July 2020
+Contact: Ivan Zaentsev <ivan.zaentsev@wirenboard.ru>
+Description:
+ (RW) Control optional driver settings.
+ Bit masks to read/write (bitwise OR):
+
+ == ============================================================
+ 1 Enable check for conversion success. If byte 6 of
+ scratchpad memory is 0xC after conversion, and
+ temperature reads 85.00 (powerup value) or 127.94
+ (insufficient power) - return a conversion error.
+
+ 2 Enable poll for conversion completion. Generate read cycles
+ after the conversion start and wait for 1's. In parasite
+ power mode this feature is not available.
+ == ============================================================
+
+ *read*:
+ Currently selected features.
+
+ *write*:
+ Select features.
+
+Users: An application using the w1_term device
diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom
index c4f0fed64a6e..16acaa5712ec 100644
--- a/Documentation/ABI/testing/sysfs-driver-wacom
+++ b/Documentation/ABI/testing/sysfs-driver-wacom
@@ -1,6 +1,6 @@
What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed
Date: April 2010
-Kernel Version: 2.6.35
+KernelVersion: 2.6.35
Contact: linux-bluetooth@vger.kernel.org
Description:
The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed file
@@ -24,6 +24,7 @@ What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status0_luminance
Date: August 2014
Contact: linux-input@vger.kernel.org
Description:
+ <obsoleted by the LED class API now exported by the driver>
Writing to this file sets the status LED luminance (1..127)
when the stylus does not touch the tablet surface, and no
button is pressed on the stylus. This luminance level is
@@ -33,6 +34,7 @@ What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status1_luminance
Date: August 2014
Contact: linux-input@vger.kernel.org
Description:
+ <obsoleted by the LED class API now exported by the driver>
Writing to this file sets the status LED luminance (1..127)
when the stylus touches the tablet surface, or any button is
pressed on the stylus.
@@ -41,6 +43,7 @@ What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status_led0_select
Date: August 2014
Contact: linux-input@vger.kernel.org
Description:
+ <obsoleted by the LED class API now exported by the driver>
Writing to this file sets which one of the four (for Intuos 4
and Intuos 5) or of the right four (for Cintiq 21UX2 and Cintiq
24HD) status LEDs is active (0..3). The other three LEDs on the
@@ -50,6 +53,7 @@ What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status_led1_select
Date: August 2014
Contact: linux-input@vger.kernel.org
Description:
+ <obsoleted by the LED class API now exported by the driver>
Writing to this file sets which one of the left four (for Cintiq 21UX2
and Cintiq 24HD) status LEDs is active (0..3). The other three LEDs on
the left are always inactive.
@@ -75,5 +79,27 @@ Description:
When the Wacom Intuos 4 is connected over Bluetooth, the
image has to contain 256 bytes (64x32 px 1 bit colour).
The format is also scrambled, like in the USB mode, and it can
- be summarized by converting 76543210 into GECA6420.
+ be summarized by converting::
+
+ 76543210 into GECA6420.
HGFEDCBA HFDB7531
+
+What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/unpair_remote
+Date: July 2015
+Contact: linux-input@vger.kernel.org
+Description:
+ Writing the character sequence '*' followed by a newline to
+ this file will delete all of the current pairings on the
+ device. Other character sequences are reserved. This file is
+ write only.
+
+What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/<serial_number>/remote_mode
+Date: July 2015
+Contact: linux-input@vger.kernel.org
+Description:
+ <obsoleted by the LED class API now exported by the driver>
+ Reading from this file reports the mode status of the
+ remote as indicated by the LED lights on the device. If no
+ reports have been received from the paired device, reading
+ from this file will report '-1'. The mode is read-only
+ and cannot be set through the driver.
diff --git a/Documentation/ABI/testing/sysfs-driver-xdata b/Documentation/ABI/testing/sysfs-driver-xdata
new file mode 100644
index 000000000000..f574e8e6dca2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-xdata
@@ -0,0 +1,49 @@
+What: /sys/class/misc/drivers/dw-xdata-pcie.<device>/write
+Date: April 2021
+KernelVersion: 5.13
+Contact: Gustavo Pimentel <gustavo.pimentel@synopsys.com>
+Description: Allows the user to enable the PCIe traffic generator which
+ will create write TLPs frames - from the Root Complex to the
+ Endpoint direction or to disable the PCIe traffic generator
+ in all directions.
+
+ Write y/1/on to enable, n/0/off to disable
+
+ Usage e.g.
+ echo 1 > /sys/class/misc/dw-xdata-pcie.<device>/write
+ or
+ echo 0 > /sys/class/misc/dw-xdata-pcie.<device>/write
+
+ The user can read the current PCIe link throughput generated
+ through this generator in MB/s.
+
+ Usage e.g.
+ cat /sys/class/misc/dw-xdata-pcie.<device>/write
+ 204
+
+ The file is read and write.
+
+What: /sys/class/misc/dw-xdata-pcie.<device>/read
+Date: April 2021
+KernelVersion: 5.13
+Contact: Gustavo Pimentel <gustavo.pimentel@synopsys.com>
+Description: Allows the user to enable the PCIe traffic generator which
+ will create read TLPs frames - from the Endpoint to the Root
+ Complex direction or to disable the PCIe traffic generator
+ in all directions.
+
+ Write y/1/on to enable, n/0/off to disable
+
+ Usage e.g.
+ echo 1 > /sys/class/misc/dw-xdata-pcie.<device>/read
+ or
+ echo 0 > /sys/class/misc/dw-xdata-pcie.<device>/read
+
+ The user can read the current PCIe link throughput generated
+ through this generator in MB/s.
+
+ Usage e.g.
+ cat /sys/class/misc/dw-xdata-pcie.<device>/read
+ 199
+
+ The file is read and write.
diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkback b/Documentation/ABI/testing/sysfs-driver-xen-blkback
index 8bb43b66eb55..fac0f429a869 100644
--- a/Documentation/ABI/testing/sysfs-driver-xen-blkback
+++ b/Documentation/ABI/testing/sysfs-driver-xen-blkback
@@ -15,3 +15,32 @@ Description:
blkback. If the frontend tries to use more than
max_persistent_grants, the LRU kicks in and starts
removing 5% of max_persistent_grants every 100ms.
+
+What: /sys/module/xen_blkback/parameters/persistent_grant_unused_seconds
+Date: August 2018
+KernelVersion: 4.19
+Contact: Roger Pau Monné <roger.pau@citrix.com>
+Description:
+ How long a persistent grant is allowed to remain
+ allocated without being in use. The time is in
+ seconds, 0 means indefinitely long.
+ The default is 60 seconds.
+
+What: /sys/module/xen_blkback/parameters/buffer_squeeze_duration_ms
+Date: December 2019
+KernelVersion: 5.6
+Contact: Maximilian Heyne <mheyne@amazon.de>
+Description:
+ When memory pressure is reported to blkback this option
+ controls the duration in milliseconds that blkback will not
+ cache any page not backed by a grant mapping.
+ The default is 10ms.
+
+What: /sys/module/xen_blkback/parameters/feature_persistent
+Date: September 2020
+KernelVersion: 5.10
+Contact: Maximilian Heyne <mheyne@amazon.de>
+Description:
+ Whether to enable the persistent grants feature or not. Note
+ that this option only takes effect on newly connected backends.
+ The default is Y (enable).
diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkfront b/Documentation/ABI/testing/sysfs-driver-xen-blkfront
index c0a6cb7eb314..4d36c5a10546 100644
--- a/Documentation/ABI/testing/sysfs-driver-xen-blkfront
+++ b/Documentation/ABI/testing/sysfs-driver-xen-blkfront
@@ -1,4 +1,4 @@
-What: /sys/module/xen_blkfront/parameters/max
+What: /sys/module/xen_blkfront/parameters/max_indirect_segments
Date: June 2013
KernelVersion: 3.11
Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
@@ -8,3 +8,12 @@ Description:
is 32 - higher value means more potential throughput but more
memory usage. The backend picks the minimum of the frontend
and its default backend value.
+
+What: /sys/module/xen_blkfront/parameters/feature_persistent
+Date: September 2020
+KernelVersion: 5.10
+Contact: Maximilian Heyne <mheyne@amazon.de>
+Description:
+ Whether to enable the persistent grants feature or not. Note
+ that this option only takes effect on newly connected frontends.
+ The default is Y (enable).
diff --git a/Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager b/Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager
new file mode 100644
index 000000000000..57b9b68a73ee
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-xilinx-tmr-manager
@@ -0,0 +1,16 @@
+What: /sys/devices/platform/amba_pl/<dev>/errcnt
+Date: Nov 2022
+Contact: appana.durga.kedareswara.rao@amd.com
+Description: This control file provides the fault detection count.
+ This file cannot be written.
+ Example:
+ # cat /sys/devices/platform/amba_pl/44a10000.tmr_manager/errcnt
+ 1
+
+What: /sys/devices/platform/amba_pl/<dev>/dis_block_break
+Date: Nov 2022
+Contact: appana.durga.kedareswara.rao@amd.com
+Description: Write any value to it, This control file enables the break signal.
+ This file is write only.
+ Example:
+ # echo <any value> > /sys/devices/platform/amba_pl/44a10000.tmr_manager/dis_block_break
diff --git a/Documentation/ABI/testing/sysfs-driver-zynqmp-fpga b/Documentation/ABI/testing/sysfs-driver-zynqmp-fpga
new file mode 100644
index 000000000000..8f93d27b6d91
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-driver-zynqmp-fpga
@@ -0,0 +1,73 @@
+What: /sys/bus/platform/drivers/zynqmp_fpga_manager/firmware:zynqmp-firmware:pcap/status
+Date: February 2023
+KernelVersion: 6.4
+Contact: Nava kishore Manne <nava.kishore.manne@amd.com>
+Description: (RO) Read fpga status.
+ Read returns a hexadecimal value that tells the current status
+ of the FPGA device. Each bit position in the status value is
+ described Below(see ug570 chapter 9).
+ https://docs.xilinx.com/v/u/en-US/ug570-ultrascale-configuration
+
+ ====================== ==============================================
+ BIT(0) 0: No CRC error
+ 1: CRC error
+
+ BIT(1) 0: Decryptor security not set
+ 1: Decryptor security set
+
+ BIT(2) 0: MMCMs/PLLs are not locked
+ 1: MMCMs/PLLs are locked
+
+ BIT(3) 0: DCI not matched
+ 1: DCI matched
+
+ BIT(4) 0: Start-up sequence has not finished
+ 1: Start-up sequence has finished
+
+ BIT(5) 0: All I/Os are placed in High-Z state
+ 1: All I/Os behave as configured
+
+ BIT(6) 0: Flip-flops and block RAM are write disabled
+ 1: Flip-flops and block RAM are write enabled
+
+ BIT(7) 0: GHIGH_B_STATUS asserted
+ 1: GHIGH_B_STATUS deasserted
+
+ BIT(8) to BIT(10) Status of the mode pins
+
+ BIT(11) 0: Initialization has not finished
+ 1: Initialization finished
+
+ BIT(12) Value on INIT_B_PIN pin
+
+ BIT(13) 0: Signal not released
+ 1: Signal released
+
+ BIT(14) Value on DONE_PIN pin.
+
+ BIT(15) 0: No IDCODE_ERROR
+ 1: IDCODE_ERROR
+
+ BIT(16) 0: No SECURITY_ERROR
+ 1: SECURITY_ERROR
+
+ BIT(17) System Monitor over-temperature if set
+
+ BIT(18) to BIT(20) Start-up state machine (0 to 7)
+ Phase 0 = 000
+ Phase 1 = 001
+ Phase 2 = 011
+ Phase 3 = 010
+ Phase 4 = 110
+ Phase 5 = 111
+ Phase 6 = 101
+ Phase 7 = 100
+
+ BIT(25) to BIT(26) Indicates the detected bus width
+ 00 = x1
+ 01 = x8
+ 10 = x16
+ 11 = x32
+ ====================== ==============================================
+
+ The other bits are reserved.
diff --git a/Documentation/ABI/testing/sysfs-edac-ecs b/Documentation/ABI/testing/sysfs-edac-ecs
new file mode 100644
index 000000000000..87c885c4eb1a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-edac-ecs
@@ -0,0 +1,74 @@
+What: /sys/bus/edac/devices/<dev-name>/ecs_fruX
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ The sysfs EDAC bus devices /<dev-name>/ecs_fruX subdirectory
+ pertains to the memory media ECS (Error Check Scrub) control
+ feature, where <dev-name> directory corresponds to a device
+ registered with the EDAC device driver for the ECS feature.
+ /ecs_fruX belongs to the media FRUs (Field Replaceable Unit)
+ under the memory device.
+
+ The sysfs ECS attr nodes are only present if the parent
+ driver has implemented the corresponding attr callback
+ function and provided the necessary operations to the EDAC
+ device driver during registration.
+
+What: /sys/bus/edac/devices/<dev-name>/ecs_fruX/log_entry_type
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The log entry type of how the DDR5 ECS log is reported.
+
+ - 0 - per DRAM.
+
+ - 1 - per memory media FRU.
+
+ - All other values are reserved.
+
+What: /sys/bus/edac/devices/<dev-name>/ecs_fruX/mode
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The mode of how the DDR5 ECS counts the errors.
+ Error count is tracked based on two different modes
+ selected by DDR5 ECS Control Feature - Codeword mode and
+ Row Count mode. If the ECS is under Codeword mode, then
+ the error count increments each time a codeword with check
+ bit errors is detected. If the ECS is under Row Count mode,
+ then the error counter increments each time a row with
+ check bit errors is detected.
+
+ - 0 - ECS counts rows in the memory media that have ECC errors.
+
+ - 1 - ECS counts codewords with errors, specifically, it counts
+ the number of ECC-detected errors in the memory media.
+
+ - All other values are reserved.
+
+What: /sys/bus/edac/devices/<dev-name>/ecs_fruX/reset
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (WO) ECS reset ECC counter.
+
+ - 1 - reset ECC counter to the default value.
+
+ - All other values are reserved.
+
+What: /sys/bus/edac/devices/<dev-name>/ecs_fruX/threshold
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) DDR5 ECS threshold count per gigabits of memory cells.
+ The ECS error count is subject to the ECS Threshold count
+ per Gbit, which masks error counts less than the Threshold.
+
+ Supported values are 256, 1024 and 4096.
+
+ All other values are reserved.
diff --git a/Documentation/ABI/testing/sysfs-edac-memory-repair b/Documentation/ABI/testing/sysfs-edac-memory-repair
new file mode 100644
index 000000000000..0434a3b23ff3
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-edac-memory-repair
@@ -0,0 +1,206 @@
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ The sysfs EDAC bus devices /<dev-name>/mem_repairX subdirectory
+ pertains to the memory media repair features control, such as
+ PPR (Post Package Repair), memory sparing etc, where <dev-name>
+ directory corresponds to a device registered with the EDAC
+ device driver for the memory repair features.
+
+ Post Package Repair is a maintenance operation requests the memory
+ device to perform a repair operation on its media. It is a memory
+ self-healing feature that fixes a failing memory location by
+ replacing it with a spare row in a DRAM device. For example, a
+ CXL memory device with DRAM components that support PPR features may
+ implement PPR maintenance operations. DRAM components may support
+ two types of PPR functions: hard PPR, for a permanent row repair, and
+ soft PPR, for a temporary row repair. Soft PPR may be much faster
+ than hard PPR, but the repair is lost with a power cycle.
+
+ The sysfs attributes nodes for a repair feature are only
+ present if the parent driver has implemented the corresponding
+ attr callback function and provided the necessary operations
+ to the EDAC device driver during registration.
+
+ In some states of system configuration (e.g. before address
+ decoders have been configured), memory devices (e.g. CXL)
+ may not have an active mapping in the main host address
+ physical address map. As such, the memory to repair must be
+ identified by a device specific physical addressing scheme
+ using a device physical address(DPA). The DPA and other control
+ attributes to use will be presented in related error records.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/repair_type
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RO) Memory repair type. For eg. post package repair,
+ memory sparing etc. Valid values are:
+
+ - ppr - Post package repair.
+
+ - cacheline-sparing
+
+ - row-sparing
+
+ - bank-sparing
+
+ - rank-sparing
+
+ - All other values are reserved.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/persist_mode
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) Get/Set the current persist repair mode set for a
+ repair function. Persist repair modes supported in the
+ device, based on a memory repair function, either is temporary,
+ which is lost with a power cycle or permanent. Valid values are:
+
+ - 0 - Soft memory repair (temporary repair).
+
+ - 1 - Hard memory repair (permanent repair).
+
+ - All other values are reserved.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/repair_safe_when_in_use
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RO) True if memory media is accessible and data is retained
+ during the memory repair operation.
+ The data may not be retained and memory requests may not be
+ correctly processed during a repair operation. In such case
+ repair operation can not be executed at runtime. The memory
+ must be taken offline.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/hpa
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) Host Physical Address (HPA) of the memory to repair.
+ The HPA to use will be provided in related error records.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/dpa
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) Device Physical Address (DPA) of the memory to repair.
+ The specific DPA to use will be provided in related error
+ records.
+
+ In some states of system configuration (e.g. before address
+ decoders have been configured), memory devices (e.g. CXL)
+ may not have an active mapping in the main host address
+ physical address map. As such, the memory to repair must be
+ identified by a device specific physical addressing scheme
+ using a DPA. The device physical address(DPA) to use will be
+ presented in related error records.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/nibble_mask
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) Read/Write Nibble mask of the memory to repair.
+ Nibble mask identifies one or more nibbles in error on the
+ memory bus that produced the error event. Nibble Mask bit 0
+ shall be set if nibble 0 on the memory bus produced the
+ event, etc. For example, CXL PPR and sparing, a nibble mask
+ bit set to 1 indicates the request to perform repair
+ operation in the specific device. All nibble mask bits set
+ to 1 indicates the request to perform the operation in all
+ devices. Eg. for CXL memory repair, the specific value of
+ nibble mask to use will be provided in related error records.
+ For more details, See nibble mask field in CXL spec ver 3.1,
+ section 8.2.9.7.1.2 Table 8-103 soft PPR and section
+ 8.2.9.7.1.3 Table 8-104 hard PPR, section 8.2.9.7.1.4
+ Table 8-105 memory sparing.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/min_hpa
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/max_hpa
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/min_dpa
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/max_dpa
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The supported range of memory address that is to be
+ repaired. The memory device may give the supported range of
+ attributes to use and it will depend on the memory device
+ and the portion of memory to repair.
+ The userspace may receive the specific value of attributes
+ to use for a repair operation from the memory device via
+ related error records and trace events, for eg. CXL DRAM
+ and CXL general media error records in CXL memory devices.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/bank_group
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/bank
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/rank
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/row
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/column
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/channel
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/sub_channel
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The control attributes for the memory to be repaired.
+ The specific value of attributes to use depends on the
+ portion of memory to repair and will be reported to the host
+ in related error records and be available to userspace
+ in trace events, such as CXL DRAM and CXL general media
+ error records of CXL memory devices.
+
+ When readng back these attributes, it returns the current
+ value of memory requested to be repaired.
+
+ bank_group - The bank group of the memory to repair.
+
+ bank - The bank number of the memory to repair.
+
+ rank - The rank of the memory to repair. Rank is defined as a
+ set of memory devices on a channel that together execute a
+ transaction.
+
+ row - The row number of the memory to repair.
+
+ column - The column number of the memory to repair.
+
+ channel - The channel of the memory to repair. Channel is
+ defined as an interface that can be independently accessed
+ for a transaction.
+
+ sub_channel - The subchannel of the memory to repair.
+
+ The requirement to set these attributes varies based on the
+ repair function. The attributes in sysfs are not present
+ unless required for a repair function.
+
+ For example, CXL spec ver 3.1, Section 8.2.9.7.1.2 Table 8-103
+ soft PPR and Section 8.2.9.7.1.3 Table 8-104 hard PPR operations,
+ these attributes are not required to set. CXL spec ver 3.1,
+ Section 8.2.9.7.1.4 Table 8-105 memory sparing, these attributes
+ are required to set based on memory sparing granularity.
+
+What: /sys/bus/edac/devices/<dev-name>/mem_repairX/repair
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (WO) Issue the memory repair operation for the specified
+ memory repair attributes. The operation may fail if resources
+ are insufficient based on the requirements of the memory
+ device and repair function.
+
+ - 1 - Issue the repair operation.
+
+ - All other values are reserved.
diff --git a/Documentation/ABI/testing/sysfs-edac-scrub b/Documentation/ABI/testing/sysfs-edac-scrub
new file mode 100644
index 000000000000..ab6014743da5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-edac-scrub
@@ -0,0 +1,85 @@
+What: /sys/bus/edac/devices/<dev-name>/scrubX
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ The sysfs EDAC bus devices /<dev-name>/scrubX subdirectory
+ belongs to an instance of memory scrub control feature,
+ where <dev-name> directory corresponds to a device/memory
+ region registered with the EDAC device driver for the
+ scrub control feature.
+
+ The sysfs scrub attr nodes are only present if the parent
+ driver has implemented the corresponding attr callback
+ function and provided the necessary operations to the EDAC
+ device driver during registration.
+
+What: /sys/bus/edac/devices/<dev-name>/scrubX/addr
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The base address of the memory region to be scrubbed
+ for on-demand scrubbing. Setting address starts scrubbing.
+ The size must be set before that.
+
+ The readback addr value is non-zero if the requested
+ on-demand scrubbing is in progress, zero otherwise.
+
+What: /sys/bus/edac/devices/<dev-name>/scrubX/size
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The size of the memory region to be scrubbed
+ (on-demand scrubbing).
+
+What: /sys/bus/edac/devices/<dev-name>/scrubX/enable_background
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) Start/Stop background (patrol) scrubbing if supported.
+
+What: /sys/bus/edac/devices/<dev-name>/scrubX/min_cycle_duration
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RO) Supported minimum scrub cycle duration in seconds
+ by the memory scrubber.
+
+ Device-based scrub: returns the minimum scrub cycle
+ supported by the memory device.
+
+ Region-based scrub: returns the max of minimum scrub cycles
+ supported by individual memory devices that back the region.
+
+What: /sys/bus/edac/devices/<dev-name>/scrubX/max_cycle_duration
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RO) Supported maximum scrub cycle duration in seconds
+ by the memory scrubber.
+
+ Device-based scrub: returns the maximum scrub cycle supported
+ by the memory device.
+
+ Region-based scrub: returns the min of maximum scrub cycles
+ supported by individual memory devices that back the region.
+
+ If the memory device does not provide maximum scrub cycle
+ information, return the maximum supported value of the scrub
+ cycle field.
+
+What: /sys/bus/edac/devices/<dev-name>/scrubX/current_cycle_duration
+Date: March 2025
+KernelVersion: 6.15
+Contact: linux-edac@vger.kernel.org
+Description:
+ (RW) The current scrub cycle duration in seconds and must be
+ within the supported range by the memory scrubber.
+
+ Scrub has an overhead when running and that may want to be
+ reduced by taking longer to do it.
diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi
index b4436cca97a8..72e7c9161ce7 100644
--- a/Documentation/ABI/testing/sysfs-firmware-acpi
+++ b/Documentation/ABI/testing/sysfs-firmware-acpi
@@ -1,3 +1,46 @@
+What: /sys/firmware/acpi/fpdt/
+Date: Jan 2021
+Contact: Zhang Rui <rui.zhang@intel.com>
+Description:
+ ACPI Firmware Performance Data Table (FPDT) provides
+ information for firmware performance data for system boot,
+ S3 suspend and S3 resume. This sysfs entry contains the
+ performance data retrieved from the FPDT.
+
+ boot:
+ firmware_start_ns: Timer value logged at the beginning
+ of firmware image execution. In nanoseconds.
+ bootloader_load_ns: Timer value logged just prior to
+ loading the OS boot loader into memory.
+ In nanoseconds.
+ bootloader_launch_ns: Timer value logged just prior to
+ launching the currently loaded OS boot loader
+ image. In nanoseconds.
+ exitbootservice_start_ns: Timer value logged at the
+ point when the OS loader calls the
+ ExitBootServices function for UEFI compatible
+ firmware. In nanoseconds.
+ exitbootservice_end_ns: Timer value logged at the point
+ just prior to the OS loader gaining control
+ back from the ExitBootServices function for
+ UEFI compatible firmware. In nanoseconds.
+ suspend:
+ suspend_start_ns: Timer value recorded at the previous
+ OS write to SLP_TYP upon entry to S3. In
+ nanoseconds.
+ suspend_end_ns: Timer value recorded at the previous
+ firmware write to SLP_TYP used to trigger
+ hardware entry to S3. In nanoseconds.
+ resume:
+ resume_count: A count of the number of S3 resume cycles
+ since the last full boot sequence.
+ resume_avg_ns: Average timer value of all resume cycles
+ logged since the last full boot sequence,
+ including the most recent resume. In nanoseconds.
+ resume_prev_ns: Timer recorded at the end of the previous
+ platform runtime firmware S3 resume, just prior to
+ handoff to the OS waking vector. In nanoseconds.
+
What: /sys/firmware/acpi/bgrt/
Date: January 2012
Contact: Matthew Garrett <mjg@redhat.com>
@@ -12,11 +55,14 @@ Description:
image: The image bitmap. Currently a 32-bit BMP.
status: 1 if the image is valid, 0 if firmware invalidated it.
type: 0 indicates image is in BMP format.
+
+ ======== ===================================================
version: The version of the BGRT. Currently 1.
xoffset: The number of pixels between the left of the screen
and the left edge of the image.
yoffset: The number of pixels between the top of the screen
and the top edge of the image.
+ ======== ===================================================
What: /sys/firmware/acpi/hotplug/
Date: February 2013
@@ -33,27 +79,19 @@ Description:
The following setting is available to user space for each
hotplug profile:
+ ======== =======================================================
enabled: If set, the ACPI core will handle notifications of
- hotplug events associated with the given class of
- devices and will allow those devices to be ejected with
- the help of the _EJ0 control method. Unsetting it
- effectively disables hotplug for the correspoinding
- class of devices.
+ hotplug events associated with the given class of
+ devices and will allow those devices to be ejected with
+ the help of the _EJ0 control method. Unsetting it
+ effectively disables hotplug for the corresponding
+ class of devices.
+ ======== =======================================================
The value of the above attribute is an integer number: 1 (set)
or 0 (unset). Attempts to write any other values to it will
cause -EINVAL to be returned.
-What: /sys/firmware/acpi/hotplug/force_remove
-Date: May 2013
-Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
-Description:
- The number in this file (0 or 1) determines whether (1) or not
- (0) the ACPI subsystem will allow devices to be hot-removed even
- if they cannot be put offline gracefully (from the kernel's
- viewpoint). That number can be changed by writing a boolean
- value to this file.
-
What: /sys/firmware/acpi/interrupts/
Date: February 2008
Contact: Len Brown <lenb@kernel.org>
@@ -70,97 +108,101 @@ Description:
number of a "General Purpose Events" (GPE).
A GPE vectors to a specified handler in AML, which
- can do a anything the BIOS writer wants from
+ can do anything the BIOS writer wants from
OS context. GPE 0x12, for example, would vector
to a level or edge handler called _L12 or _E12.
The handler may do its business and return.
- Or the handler may send send a Notify event
+ Or the handler may send a Notify event
to a Linux device driver registered on an ACPI device,
such as a battery, or a processor.
- To figure out where all the SCI's are coming from,
+ To figure out where all the SCIs are coming from,
/sys/firmware/acpi/interrupts contains a file listing
every possible source, and the count of how many
- times it has triggered.
-
- $ cd /sys/firmware/acpi/interrupts
- $ grep . *
- error: 0
- ff_gbl_lock: 0 enable
- ff_pmtimer: 0 invalid
- ff_pwr_btn: 0 enable
- ff_rt_clk: 2 disable
- ff_slp_btn: 0 invalid
- gpe00: 0 invalid
- gpe01: 0 enable
- gpe02: 108 enable
- gpe03: 0 invalid
- gpe04: 0 invalid
- gpe05: 0 invalid
- gpe06: 0 enable
- gpe07: 0 enable
- gpe08: 0 invalid
- gpe09: 0 invalid
- gpe0A: 0 invalid
- gpe0B: 0 invalid
- gpe0C: 0 invalid
- gpe0D: 0 invalid
- gpe0E: 0 invalid
- gpe0F: 0 invalid
- gpe10: 0 invalid
- gpe11: 0 invalid
- gpe12: 0 invalid
- gpe13: 0 invalid
- gpe14: 0 invalid
- gpe15: 0 invalid
- gpe16: 0 invalid
- gpe17: 1084 enable
- gpe18: 0 enable
- gpe19: 0 invalid
- gpe1A: 0 invalid
- gpe1B: 0 invalid
- gpe1C: 0 invalid
- gpe1D: 0 invalid
- gpe1E: 0 invalid
- gpe1F: 0 invalid
- gpe_all: 1192
- sci: 1194
- sci_not: 0
-
- sci - The number of times the ACPI SCI
- has been called and claimed an interrupt.
-
- sci_not - The number of times the ACPI SCI
- has been called and NOT claimed an interrupt.
-
- gpe_all - count of SCI caused by GPEs.
-
- gpeXX - count for individual GPE source
-
- ff_gbl_lock - Global Lock
-
- ff_pmtimer - PM Timer
-
- ff_pwr_btn - Power Button
-
- ff_rt_clk - Real Time Clock
-
- ff_slp_btn - Sleep Button
-
- error - an interrupt that can't be accounted for above.
-
- invalid: it's either a GPE or a Fixed Event that
- doesn't have an event handler.
-
- disable: the GPE/Fixed Event is valid but disabled.
-
- enable: the GPE/Fixed Event is valid and enabled.
-
- Root has permission to clear any of these counters. Eg.
- # echo 0 > gpe11
-
- All counters can be cleared by clearing the total "sci":
- # echo 0 > sci
+ times it has triggered::
+
+ $ cd /sys/firmware/acpi/interrupts
+ $ grep . *
+ error: 0
+ ff_gbl_lock: 0 enable
+ ff_pmtimer: 0 invalid
+ ff_pwr_btn: 0 enable
+ ff_rt_clk: 2 disable
+ ff_slp_btn: 0 invalid
+ gpe00: 0 invalid
+ gpe01: 0 enable
+ gpe02: 108 enable
+ gpe03: 0 invalid
+ gpe04: 0 invalid
+ gpe05: 0 invalid
+ gpe06: 0 enable
+ gpe07: 0 enable
+ gpe08: 0 invalid
+ gpe09: 0 invalid
+ gpe0A: 0 invalid
+ gpe0B: 0 invalid
+ gpe0C: 0 invalid
+ gpe0D: 0 invalid
+ gpe0E: 0 invalid
+ gpe0F: 0 invalid
+ gpe10: 0 invalid
+ gpe11: 0 invalid
+ gpe12: 0 invalid
+ gpe13: 0 invalid
+ gpe14: 0 invalid
+ gpe15: 0 invalid
+ gpe16: 0 invalid
+ gpe17: 1084 enable
+ gpe18: 0 enable
+ gpe19: 0 invalid
+ gpe1A: 0 invalid
+ gpe1B: 0 invalid
+ gpe1C: 0 invalid
+ gpe1D: 0 invalid
+ gpe1E: 0 invalid
+ gpe1F: 0 invalid
+ gpe_all: 1192
+ sci: 1194
+ sci_not: 0
+
+ =========== ==================================================
+ sci The number of times the ACPI SCI
+ has been called and claimed an interrupt.
+
+ sci_not The number of times the ACPI SCI
+ has been called and NOT claimed an interrupt.
+
+ gpe_all count of SCI caused by GPEs.
+
+ gpeXX count for individual GPE source
+
+ ff_gbl_lock Global Lock
+
+ ff_pmtimer PM Timer
+
+ ff_pwr_btn Power Button
+
+ ff_rt_clk Real Time Clock
+
+ ff_slp_btn Sleep Button
+
+ error an interrupt that can't be accounted for above.
+
+ invalid it's either a GPE or a Fixed Event that
+ doesn't have an event handler.
+
+ disable the GPE/Fixed Event is valid but disabled.
+
+ enable the GPE/Fixed Event is valid and enabled.
+ =========== ==================================================
+
+ Root has permission to clear any of these counters. Eg.::
+
+ # echo 0 > gpe11
+
+ All counters can be cleared by clearing the total "sci"::
+
+ # echo 0 > sci
None of these counters has an effect on the function
of the system, they are simply statistics.
@@ -169,38 +211,61 @@ Description:
to enable/disable/clear ACPI interrupts in user space, which can be
used to debug some ACPI interrupt storm issues.
- Note that only writting to VALID GPE/Fixed Event is allowed,
+ Note that only writing to VALID GPE/Fixed Event is allowed,
i.e. user can only change the status of runtime GPE and
Fixed Event with event handler installed.
Let's take power button fixed event for example, please kill acpid
and other user space applications so that the machine won't shutdown
- when pressing the power button.
- # cat ff_pwr_btn
- 0 enabled
- # press the power button for 3 times;
- # cat ff_pwr_btn
- 3 enabled
- # echo disable > ff_pwr_btn
- # cat ff_pwr_btn
- 3 disabled
- # press the power button for 3 times;
- # cat ff_pwr_btn
- 3 disabled
- # echo enable > ff_pwr_btn
- # cat ff_pwr_btn
- 4 enabled
- /*
- * this is because the status bit is set even if the enable bit is cleared,
- * and it triggers an ACPI fixed event when the enable bit is set again
- */
- # press the power button for 3 times;
- # cat ff_pwr_btn
- 7 enabled
- # echo disable > ff_pwr_btn
- # press the power button for 3 times;
- # echo clear > ff_pwr_btn /* clear the status bit */
- # echo disable > ff_pwr_btn
- # cat ff_pwr_btn
- 7 enabled
+ when pressing the power button::
+
+ # cat ff_pwr_btn
+ 0 enabled
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 3 enabled
+ # echo disable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 3 disabled
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 3 disabled
+ # echo enable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 4 enabled
+ /*
+ * this is because the status bit is set even if the enable
+ * bit is cleared, and it triggers an ACPI fixed event when
+ * the enable bit is set again
+ */
+ # press the power button for 3 times;
+ # cat ff_pwr_btn
+ 7 enabled
+ # echo disable > ff_pwr_btn
+ # press the power button for 3 times;
+ # echo clear > ff_pwr_btn /* clear the status bit */
+ # echo disable > ff_pwr_btn
+ # cat ff_pwr_btn
+ 7 enabled
+
+What: /sys/firmware/acpi/memory_ranges/rangeX
+Date: February 2025
+Contact: Tony Luck <tony.luck@intel.com>
+Description:
+ On systems with the ACPI MRRM table reports the parameters for
+ each range.
+
+ base: Starting system physical address.
+
+ length: Length of this range in bytes.
+
+ node: NUMA node that this range belongs to. Negative numbers
+ indicate that the node number could not be determined (e.g
+ for an address range that is reserved for future hot add of
+ memory).
+
+ local_region_id: ID associated with access by agents
+ local to this range of addresses.
+ remote_region_id: ID associated with access by agents
+ non-local to this range of addresses.
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi b/Documentation/ABI/testing/sysfs-firmware-dmi
deleted file mode 100644
index c78f9ab01e56..000000000000
--- a/Documentation/ABI/testing/sysfs-firmware-dmi
+++ /dev/null
@@ -1,110 +0,0 @@
-What: /sys/firmware/dmi/
-Date: February 2011
-Contact: Mike Waychison <mikew@google.com>
-Description:
- Many machines' firmware (x86 and ia64) export DMI /
- SMBIOS tables to the operating system. Getting at this
- information is often valuable to userland, especially in
- cases where there are OEM extensions used.
-
- The kernel itself does not rely on the majority of the
- information in these tables being correct. It equally
- cannot ensure that the data as exported to userland is
- without error either.
-
- DMI is structured as a large table of entries, where
- each entry has a common header indicating the type and
- length of the entry, as well as a firmware-provided
- 'handle' that is supposed to be unique amongst all
- entries.
-
- Some entries are required by the specification, but many
- others are optional. In general though, users should
- never expect to find a specific entry type on their
- system unless they know for certain what their firmware
- is doing. Machine to machine experiences will vary.
-
- Multiple entries of the same type are allowed. In order
- to handle these duplicate entry types, each entry is
- assigned by the operating system an 'instance', which is
- derived from an entry type's ordinal position. That is
- to say, if there are 'N' multiple entries with the same type
- 'T' in the DMI tables (adjacent or spread apart, it
- doesn't matter), they will be represented in sysfs as
- entries "T-0" through "T-(N-1)":
-
- Example entry directories:
-
- /sys/firmware/dmi/entries/17-0
- /sys/firmware/dmi/entries/17-1
- /sys/firmware/dmi/entries/17-2
- /sys/firmware/dmi/entries/17-3
- ...
-
- Instance numbers are used in lieu of the firmware
- assigned entry handles as the kernel itself makes no
- guarantees that handles as exported are unique, and
- there are likely firmware images that get this wrong in
- the wild.
-
- Each DMI entry in sysfs has the common header values
- exported as attributes:
-
- handle : The 16bit 'handle' that is assigned to this
- entry by the firmware. This handle may be
- referred to by other entries.
- length : The length of the entry, as presented in the
- entry itself. Note that this is _not the
- total count of bytes associated with the
- entry_. This value represents the length of
- the "formatted" portion of the entry. This
- "formatted" region is sometimes followed by
- the "unformatted" region composed of nul
- terminated strings, with termination signalled
- by a two nul characters in series.
- raw : The raw bytes of the entry. This includes the
- "formatted" portion of the entry, the
- "unformatted" strings portion of the entry,
- and the two terminating nul characters.
- type : The type of the entry. This value is the same
- as found in the directory name. It indicates
- how the rest of the entry should be interpreted.
- instance: The instance ordinal of the entry for the
- given type. This value is the same as found
- in the parent directory name.
- position: The ordinal position (zero-based) of the entry
- within the entirety of the DMI entry table.
-
- === Entry Specialization ===
-
- Some entry types may have other information available in
- sysfs. Not all types are specialized.
-
- --- Type 15 - System Event Log ---
-
- This entry allows the firmware to export a log of
- events the system has taken. This information is
- typically backed by nvram, but the implementation
- details are abstracted by this table. This entry's data
- is exported in the directory:
-
- /sys/firmware/dmi/entries/15-0/system_event_log
-
- and has the following attributes (documented in the
- SMBIOS / DMI specification under "System Event Log (Type 15)":
-
- area_length
- header_start_offset
- data_start_offset
- access_method
- status
- change_token
- access_method_address
- header_format
- per_log_type_descriptor_length
- type_descriptors_supported_count
-
- As well, the kernel exports the binary attribute:
-
- raw_event_log : The raw binary bits of the event log
- as described by the DMI entry.
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
new file mode 100644
index 000000000000..b6c23807b804
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
@@ -0,0 +1,114 @@
+What: /sys/firmware/dmi/entries/
+Date: February 2011
+Contact: Mike Waychison <mikew@google.com>
+Description:
+ Many machines' firmware (x86 and arm64) export DMI /
+ SMBIOS tables to the operating system. Getting at this
+ information is often valuable to userland, especially in
+ cases where there are OEM extensions used.
+
+ The kernel itself does not rely on the majority of the
+ information in these tables being correct. It equally
+ cannot ensure that the data as exported to userland is
+ without error either.
+
+ DMI is structured as a large table of entries, where
+ each entry has a common header indicating the type and
+ length of the entry, as well as a firmware-provided
+ 'handle' that is supposed to be unique amongst all
+ entries.
+
+ Some entries are required by the specification, but many
+ others are optional. In general though, users should
+ never expect to find a specific entry type on their
+ system unless they know for certain what their firmware
+ is doing. Machine to machine experiences will vary.
+
+ Multiple entries of the same type are allowed. In order
+ to handle these duplicate entry types, each entry is
+ assigned by the operating system an 'instance', which is
+ derived from an entry type's ordinal position. That is
+ to say, if there are 'N' multiple entries with the same type
+ 'T' in the DMI tables (adjacent or spread apart, it
+ doesn't matter), they will be represented in sysfs as
+ entries "T-0" through "T-(N-1)":
+
+ Example entry directories::
+
+ /sys/firmware/dmi/entries/17-0
+ /sys/firmware/dmi/entries/17-1
+ /sys/firmware/dmi/entries/17-2
+ /sys/firmware/dmi/entries/17-3
+ ...
+
+ Instance numbers are used in lieu of the firmware
+ assigned entry handles as the kernel itself makes no
+ guarantees that handles as exported are unique, and
+ there are likely firmware images that get this wrong in
+ the wild.
+
+ Each DMI entry in sysfs has the common header values
+ exported as attributes:
+
+ ======== =================================================
+ handle The 16bit 'handle' that is assigned to this
+ entry by the firmware. This handle may be
+ referred to by other entries.
+ length The length of the entry, as presented in the
+ entry itself. Note that this is _not the
+ total count of bytes associated with the
+ entry. This value represents the length of
+ the "formatted" portion of the entry. This
+ "formatted" region is sometimes followed by
+ the "unformatted" region composed of nul
+ terminated strings, with termination signalled
+ by a two nul characters in series.
+ raw The raw bytes of the entry. This includes the
+ "formatted" portion of the entry, the
+ "unformatted" strings portion of the entry,
+ and the two terminating nul characters.
+ type The type of the entry. This value is the same
+ as found in the directory name. It indicates
+ how the rest of the entry should be interpreted.
+ instance The instance ordinal of the entry for the
+ given type. This value is the same as found
+ in the parent directory name.
+ position The ordinal position (zero-based) of the entry
+ within the entirety of the DMI entry table.
+ ======== =================================================
+
+ **Entry Specialization**
+
+ Some entry types may have other information available in
+ sysfs. Not all types are specialized.
+
+ **Type 15 - System Event Log**
+
+ This entry allows the firmware to export a log of
+ events the system has taken. This information is
+ typically backed by nvram, but the implementation
+ details are abstracted by this table. This entry's data
+ is exported in the directory::
+
+ /sys/firmware/dmi/entries/15-0/system_event_log
+
+ and has the following attributes (documented in the
+ SMBIOS / DMI specification under "System Event Log (Type 15)":
+
+ - area_length
+ - header_start_offset
+ - data_start_offset
+ - access_method
+ - status
+ - change_token
+ - access_method_address
+ - header_format
+ - per_log_type_descriptor_length
+ - type_descriptors_supported_count
+
+ As well, the kernel exports the binary attribute:
+
+ ============= ====================================
+ raw_event_log The raw binary bits of the event log
+ as described by the DMI entry.
+ ============= ====================================
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-tables b/Documentation/ABI/testing/sysfs-firmware-dmi-tables
new file mode 100644
index 000000000000..ff3cac8ed0bd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-dmi-tables
@@ -0,0 +1,22 @@
+What: /sys/firmware/dmi/tables/
+Date: April 2015
+Contact: Ivan Khoronzhuk <ivan.khoronzhuk@globallogic.com>
+Description:
+ The firmware provides DMI structures as a packed list of
+ data referenced by a SMBIOS table entry point. The SMBIOS
+ entry point contains general information, like SMBIOS
+ version, DMI table size, etc. The structure, content and
+ size of SMBIOS entry point is dependent on SMBIOS version.
+ The format of SMBIOS entry point and DMI structures
+ can be read in SMBIOS specification.
+
+ The dmi/tables provides raw SMBIOS entry point and DMI tables
+ through sysfs as an alternative to utilities reading them
+ from /dev/mem. The raw SMBIOS entry point and DMI table are
+ presented as binary attributes and are accessible via:
+
+ /sys/firmware/dmi/tables/smbios_entry_point
+ /sys/firmware/dmi/tables/DMI
+
+ The complete DMI information can be obtained using these two
+ tables.
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi b/Documentation/ABI/testing/sysfs-firmware-efi
index 05874da7ce80..927e362d4974 100644
--- a/Documentation/ABI/testing/sysfs-firmware-efi
+++ b/Documentation/ABI/testing/sysfs-firmware-efi
@@ -18,3 +18,28 @@ Contact: Dave Young <dyoung@redhat.com>
Description: It shows the physical address of config table entry in the EFI
system table.
Users: Kexec
+
+What: /sys/firmware/efi/systab
+Date: April 2005
+Contact: linux-efi@vger.kernel.org
+Description: Displays the physical addresses of all EFI Configuration
+ Tables found via the EFI System Table. The order in
+ which the tables are printed forms an ABI and newer
+ versions are always printed first, i.e. ACPI20 comes
+ before ACPI.
+Users: dmidecode
+
+What: /sys/firmware/efi/tables/rci2
+Date: July 2019
+Contact: Narendra K <Narendra.K@dell.com>, linux-bugs@dell.com
+Description: Displays the content of the Runtime Configuration Interface
+ Table version 2 on Dell EMC PowerEdge systems in binary format
+Users: It is used by Dell EMC OpenManage Server Administrator tool to
+ populate BIOS setup page.
+
+What: /sys/firmware/efi/ovmf_debug_log
+Date: July 2025
+Contact: Gerd Hoffmann <kraxel@redhat.com>, linux-efi@vger.kernel.org
+Description: Displays the content of the OVMF debug log buffer. The file is
+ only present in case the firmware supports logging to a memory
+ buffer.
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-esrt b/Documentation/ABI/testing/sysfs-firmware-efi-esrt
new file mode 100644
index 000000000000..4c2d440487dd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-efi-esrt
@@ -0,0 +1,87 @@
+What: /sys/firmware/efi/esrt/
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: Provides userland access to read the EFI System Resource Table
+ (ESRT), a catalog of firmware for which can be updated with
+ the UEFI UpdateCapsule mechanism described in section 7.5 of
+ the UEFI Standard.
+Users: fwupdate - https://github.com/rhinstaller/fwupdate
+
+What: /sys/firmware/efi/esrt/fw_resource_count
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The number of entries in the ESRT
+
+What: /sys/firmware/efi/esrt/fw_resource_count_max
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The maximum number of entries that /could/ be registered
+ in the allocation the table is currently in. This is
+ really only useful to the system firmware itself.
+
+What: /sys/firmware/efi/esrt/fw_resource_version
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The version of the ESRT structure provided by the firmware.
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: Each ESRT entry is identified by a GUID, and each gets a
+ subdirectory under entries/ .
+ example: /sys/firmware/efi/esrt/entries/entry0/
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/fw_type
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: What kind of firmware entry this is:
+
+ == ===============
+ 0 Unknown
+ 1 System Firmware
+ 2 Device Firmware
+ 3 UEFI Driver
+ == ===============
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/fw_class
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: This is the entry's guid, and will match the directory name.
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/fw_version
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The version of the firmware currently installed. This is a
+ 32-bit unsigned integer.
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/lowest_supported_fw_version
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The lowest version of the firmware that can be installed.
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/capsule_flags
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: Flags that must be passed to UpdateCapsule()
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/last_attempt_version
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The last firmware version for which an update was attempted.
+
+What: /sys/firmware/efi/esrt/entries/entry<N>/last_attempt_status
+Date: February 2015
+Contact: Peter Jones <pjones@redhat.com>
+Description: The result of the last firmware update attempt for the
+ firmware resource entry.
+
+ == ======================
+ 0 Success
+ 1 Insufficient resources
+ 2 Incorrect version
+ 3 Invalid format
+ 4 Authentication error
+ 5 AC power event
+ 6 Battery power event
+ == ======================
+
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
index c61b9b348e99..9c4d581be396 100644
--- a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
+++ b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
@@ -14,7 +14,7 @@ Description: Switching efi runtime services to virtual mode requires
/sys/firmware/efi/runtime-map/ is the directory the kernel
exports that information in.
- subdirectories are named with the number of the memory range:
+ subdirectories are named with the number of the memory range::
/sys/firmware/efi/runtime-map/0
/sys/firmware/efi/runtime-map/1
@@ -24,11 +24,13 @@ Description: Switching efi runtime services to virtual mode requires
Each subdirectory contains five files:
- attribute : The attributes of the memory range.
- num_pages : The size of the memory range in pages.
- phys_addr : The physical address of the memory range.
- type : The type of the memory range.
- virt_addr : The virtual address of the memory range.
+ ========= =========================================
+ attribute The attributes of the memory range.
+ num_pages The size of the memory range in pages.
+ phys_addr The physical address of the memory range.
+ type The type of the memory range.
+ virt_addr The virtual address of the memory range.
+ ========= =========================================
Above values are all hexadecimal numbers with the '0x' prefix.
Users: Kexec
diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
index 0faa0aaf4b6a..7a558354c1ee 100644
--- a/Documentation/ABI/testing/sysfs-firmware-gsmi
+++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
@@ -20,7 +20,7 @@ Description:
This directory has the same layout (and
underlying implementation as /sys/firmware/efi/vars.
- See Documentation/ABI/*/sysfs-firmware-efi-vars
+ See `Documentation/ABI/*/sysfs-firmware-efi-vars`
for more information on how to interact with
this structure.
diff --git a/Documentation/ABI/testing/sysfs-firmware-initrd b/Documentation/ABI/testing/sysfs-firmware-initrd
new file mode 100644
index 000000000000..20bf7cf77a19
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-initrd
@@ -0,0 +1,8 @@
+What: /sys/firmware/initrd
+Date: December 2023
+Contact: Alexander Graf <graf@amazon.com>
+Description:
+ When the kernel was booted with an initrd and the
+ "retain_initrd" option is set on the kernel command
+ line, /sys/firmware/initrd contains the contents of the
+ initrd that the kernel was booted with.
diff --git a/Documentation/ABI/testing/sysfs-firmware-lefi-boardinfo b/Documentation/ABI/testing/sysfs-firmware-lefi-boardinfo
new file mode 100644
index 000000000000..5e3f6148c52e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-lefi-boardinfo
@@ -0,0 +1,35 @@
+What: /sys/firmware/lefi/boardinfo
+Date: October 2020
+Contact: Tiezhu Yang <yangtiezhu@loongson.cn>
+Description:
+ Get mainboard and BIOS info easily on the Loongson platform,
+ this is useful to point out the current used mainboard type
+ and BIOS version when there exists problems related with
+ hardware or firmware.
+
+ The related structures are already defined in the interface
+ specification about firmware and kernel which are common
+ requirement and specific for Loongson64, so only add a new
+ boardinfo.c file in arch/mips/loongson64.
+
+ For example:
+
+ [loongson@linux ~]$ cat /sys/firmware/lefi/boardinfo
+ Board Info
+ Manufacturer : LEMOTE
+ Board Name : LEMOTE-LS3A4000-7A1000-1w-V01-pc
+ Family : LOONGSON3
+
+ BIOS Info
+ Vendor : Kunlun
+ Version : Kunlun-A1901-V4.1.3-20200414093938
+ ROM Size : 4 KB
+ Release Date : 2020-04-14
+
+ By the way, using dmidecode command can get the similar info if there
+ exists SMBIOS in firmware, but the fact is that there is no SMBIOS on
+ some machines, we can see nothing when execute dmidecode, like this:
+
+ [root@linux loongson]# dmidecode
+ # dmidecode 2.12
+ # No SMBIOS nor DMI entry point found, sorry.
diff --git a/Documentation/ABI/testing/sysfs-firmware-memmap b/Documentation/ABI/testing/sysfs-firmware-memmap
index eca0d65087dc..9205122fa4b1 100644
--- a/Documentation/ABI/testing/sysfs-firmware-memmap
+++ b/Documentation/ABI/testing/sysfs-firmware-memmap
@@ -20,7 +20,7 @@ Description:
the raw memory map to userspace.
The structure is as follows: Under /sys/firmware/memmap there
- are subdirectories with the number of the entry as their name:
+ are subdirectories with the number of the entry as their name::
/sys/firmware/memmap/0
/sys/firmware/memmap/1
@@ -34,14 +34,16 @@ Description:
Each directory contains three files:
- start : The start address (as hexadecimal number with the
+ ======== =====================================================
+ start The start address (as hexadecimal number with the
'0x' prefix).
- end : The end address, inclusive (regardless whether the
+ end The end address, inclusive (regardless whether the
firmware provides inclusive or exclusive ranges).
- type : Type of the entry as string. See below for a list of
+ type Type of the entry as string. See below for a list of
valid types.
+ ======== =====================================================
- So, for example:
+ So, for example::
/sys/firmware/memmap/0/start
/sys/firmware/memmap/0/end
@@ -54,12 +56,15 @@ Description:
- System RAM
- ACPI Tables
- ACPI Non-volatile Storage
+ - Unusable memory
+ - Persistent Memory (legacy)
+ - Persistent Memory
+ - Soft Reserved
- reserved
Following shell snippet can be used to display that memory
- map in a human-readable format:
+ map in a human-readable format::
- -------------------- 8< ----------------------------------------
#!/bin/bash
cd /sys/firmware/memmap
for dir in * ; do
@@ -68,4 +73,3 @@ Description:
type=$(cat $dir/type)
printf "%016x-%016x (%s)\n" $start $[ $end +1] "$type"
done
- -------------------- >8 ----------------------------------------
diff --git a/Documentation/ABI/testing/sysfs-firmware-ofw b/Documentation/ABI/testing/sysfs-firmware-ofw
index f562b188e71d..edcab3ccfcc0 100644
--- a/Documentation/ABI/testing/sysfs-firmware-ofw
+++ b/Documentation/ABI/testing/sysfs-firmware-ofw
@@ -1,6 +1,6 @@
What: /sys/firmware/devicetree/*
Date: November 2013
-Contact: Grant Likely <grant.likely@linaro.org>
+Contact: Grant Likely <grant.likely@arm.com>, devicetree@vger.kernel.org
Description:
When using OpenFirmware or a Flattened Device Tree to enumerate
hardware, the device tree structure will be exposed in this
@@ -26,3 +26,27 @@ Description:
name plus address). Properties are represented as files
in the directory. The contents of each file is the exact
binary data from the device tree.
+
+What: /sys/firmware/fdt
+Date: February 2015
+KernelVersion: 3.19
+Contact: Frank Rowand <frowand.list@gmail.com>, devicetree@vger.kernel.org
+Description:
+ Exports the FDT blob that was passed to the kernel by
+ the bootloader. This allows userland applications such
+ as kexec to access the raw binary. This blob is also
+ useful when debugging since it contains any changes
+ made to the blob by the bootloader.
+
+ The fact that this node does not reside under
+ /sys/firmware/device-tree is deliberate: FDT is also used
+ on arm64 UEFI/ACPI systems to communicate just the UEFI
+ and ACPI entry points, but the FDT is never unflattened
+ and used to configure the system.
+
+ A CRC32 checksum is calculated over the entire FDT
+ blob, and verified at late_initcall time. The sysfs
+ entry is instantiated only if the checksum is valid,
+ i.e., if the FDT blob has not been modified in the mean
+ time. Otherwise, a warning is printed.
+Users: kexec, debugging
diff --git a/Documentation/ABI/testing/sysfs-firmware-opal-powercap b/Documentation/ABI/testing/sysfs-firmware-opal-powercap
new file mode 100644
index 000000000000..d2d12ee89288
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-opal-powercap
@@ -0,0 +1,31 @@
+What: /sys/firmware/opal/powercap
+Date: August 2017
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Powercap directory for Powernv (P8, P9) servers
+
+ Each folder in this directory contains a
+ power-cappable component.
+
+What: /sys/firmware/opal/powercap/system-powercap
+ /sys/firmware/opal/powercap/system-powercap/powercap-min
+ /sys/firmware/opal/powercap/system-powercap/powercap-max
+ /sys/firmware/opal/powercap/system-powercap/powercap-current
+Date: August 2017
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: System powercap directory and attributes applicable for
+ Powernv (P8, P9) servers
+
+ This directory provides powercap information. It
+ contains below sysfs attributes:
+
+ - powercap-min : This file provides the minimum
+ possible powercap in Watt units
+
+ - powercap-max : This file provides the maximum
+ possible powercap in Watt units
+
+ - powercap-current : This file provides the current
+ powercap set on the system. Writing to this file
+ creates a request for setting a new-powercap. The
+ powercap requested must be between powercap-min
+ and powercap-max.
diff --git a/Documentation/ABI/testing/sysfs-firmware-opal-psr b/Documentation/ABI/testing/sysfs-firmware-opal-psr
new file mode 100644
index 000000000000..1e55b56a0f89
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-opal-psr
@@ -0,0 +1,18 @@
+What: /sys/firmware/opal/psr
+Date: August 2017
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Power-Shift-Ratio directory for Powernv P9 servers
+
+ Power-Shift-Ratio allows to provide hints the firmware
+ to shift/throttle power between different entities in
+ the system. Each attribute in this directory indicates
+ a settable PSR.
+
+What: /sys/firmware/opal/psr/cpu_to_gpu_X
+Date: August 2017
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: PSR sysfs attributes for Powernv P9 servers
+
+ Power-Shift-Ratio between CPU and GPU for a given chip
+ with chip-id X. This file gives the ratio (0-100)
+ which is used by OCC for power-capping.
diff --git a/Documentation/ABI/testing/sysfs-firmware-opal-sensor-groups b/Documentation/ABI/testing/sysfs-firmware-opal-sensor-groups
new file mode 100644
index 000000000000..fcb1fb4795b6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-opal-sensor-groups
@@ -0,0 +1,21 @@
+What: /sys/firmware/opal/sensor_groups
+Date: August 2017
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Sensor groups directory for POWER9 powernv servers
+
+ Each folder in this directory contains a sensor group
+ which are classified based on type of the sensor
+ like power, temperature, frequency, current, etc. They
+ can also indicate the group of sensors belonging to
+ different owners like CSM, Profiler, Job-Scheduler
+
+What: /sys/firmware/opal/sensor_groups/<sensor_group_name>/clear
+Date: August 2017
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Sysfs file to clear the min-max of all the sensors
+ belonging to the group.
+
+ Writing 1 to this file will clear the minimum and
+ maximum values of all the sensors in the group.
+ In POWER9, the min-max of a sensor is the historical minimum
+ and maximum value of the sensor cached by OCC.
diff --git a/Documentation/ABI/testing/sysfs-firmware-papr-energy-scale-info b/Documentation/ABI/testing/sysfs-firmware-papr-energy-scale-info
new file mode 100644
index 000000000000..f5cefb81ac9d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-papr-energy-scale-info
@@ -0,0 +1,29 @@
+What: /sys/firmware/papr/energy_scale_info
+Date: February 2022
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Directory hosting a set of platform attributes like
+ energy/frequency on Linux running as a PAPR guest.
+
+ Each file in a directory contains a platform
+ attribute hierarchy pertaining to performance/
+ energy-savings mode and processor frequency.
+
+What: /sys/firmware/papr/energy_scale_info/<id>
+Date: February 2022
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Energy, frequency attributes directory for POWERVM servers
+
+What: /sys/firmware/papr/energy_scale_info/<id>/desc
+Date: February 2022
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: String description of the energy attribute of <id>
+
+What: /sys/firmware/papr/energy_scale_info/<id>/value
+Date: February 2022
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: Numeric value of the energy attribute of <id>
+
+What: /sys/firmware/papr/energy_scale_info/<id>/value_desc
+Date: February 2022
+Contact: Linux for PowerPC mailing list <linuxppc-dev@lists.ozlabs.org>
+Description: String value of the energy attribute of <id>
diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
new file mode 100644
index 000000000000..54d1bfd0db12
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
@@ -0,0 +1,103 @@
+What: /sys/firmware/qemu_fw_cfg/
+Date: August 2015
+Contact: Gabriel Somlo <somlo@cmu.edu>
+Description:
+ Several different architectures supported by QEMU (x86, arm,
+ sun4*, ppc/mac) are provisioned with a firmware configuration
+ (fw_cfg) device, originally intended as a way for the host to
+ provide configuration data to the guest firmware. Starting
+ with QEMU v2.4, arbitrary fw_cfg file entries may be specified
+ by the user on the command line, which makes fw_cfg additionally
+ useful as an out-of-band, asynchronous mechanism for providing
+ configuration data to the guest userspace.
+
+ The authoritative guest-side hardware interface documentation
+ to the fw_cfg device can be found in "docs/specs/fw_cfg.rst"
+ in the QEMU source tree, or online at:
+ https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html
+
+ **SysFS fw_cfg Interface**
+
+ The fw_cfg sysfs interface described in this document is only
+ intended to display discoverable blobs (i.e., those registered
+ with the file directory), as there is no way to determine the
+ presence or size of "legacy" blobs (with selector keys between
+ 0x0002 and 0x0018) programmatically.
+
+ All fw_cfg information is shown under:
+
+ /sys/firmware/qemu_fw_cfg/
+
+ The only legacy blob displayed is the fw_cfg device revision:
+
+ /sys/firmware/qemu_fw_cfg/rev
+
+ **Discoverable fw_cfg blobs by selector key**
+
+ All discoverable blobs listed in the fw_cfg file directory are
+ displayed as entries named after their unique selector key
+ value, e.g.:
+
+ /sys/firmware/qemu_fw_cfg/by_key/32
+ /sys/firmware/qemu_fw_cfg/by_key/33
+ /sys/firmware/qemu_fw_cfg/by_key/34
+ ...
+
+ Each such fw_cfg sysfs entry has the following values exported
+ as attributes:
+
+ ==== ====================================================
+ name The 56-byte nul-terminated ASCII string used as the
+ blob's 'file name' in the fw_cfg directory.
+ size The length of the blob, as given in the fw_cfg
+ directory.
+ key The value of the blob's selector key as given in the
+ fw_cfg directory. This value is the same as used in
+ the parent directory name.
+ raw The raw bytes of the blob, obtained by selecting the
+ entry via the control register, and reading a number
+ of bytes equal to the blob size from the data
+ register.
+ ==== ====================================================
+
+ **Listing fw_cfg blobs by file name**
+
+ While the fw_cfg device does not impose any specific naming
+ convention on the blobs registered in the file directory,
+ QEMU developers have traditionally used path name semantics
+ to give each blob a descriptive name. For example::
+
+ "bootorder"
+ "genroms/kvmvapic.bin"
+ "etc/e820"
+ "etc/boot-fail-wait"
+ "etc/system-states"
+ "etc/table-loader"
+ "etc/acpi/rsdp"
+ "etc/acpi/tables"
+ "etc/smbios/smbios-tables"
+ "etc/smbios/smbios-anchor"
+ ...
+
+ In addition to the listing by unique selector key described
+ above, the fw_cfg sysfs driver also attempts to build a tree
+ of directories matching the path name components of fw_cfg
+ blob names, ending in symlinks to the by_key entry for each
+ "basename", as illustrated below (assume current directory is
+ /sys/firmware)::
+
+ qemu_fw_cfg/by_name/bootorder -> ../by_key/38
+ qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35
+ qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41
+ ...
+
+ Construction of the directory tree and symlinks is done on a
+ "best-effort" basis, as there is no guarantee that components
+ of fw_cfg blob names are always "well behaved". I.e., there is
+ the possibility that a symlink (basename) will conflict with
+ a dirname component of another fw_cfg blob, in which case the
+ creation of the offending /sys/firmware/qemu_fw_cfg/by_name
+ entry will be skipped.
+
+ The authoritative list of entries will continue to be found
+ under the /sys/firmware/qemu_fw_cfg/by_key directory.
diff --git a/Documentation/ABI/testing/sysfs-firmware-sfi b/Documentation/ABI/testing/sysfs-firmware-sfi
deleted file mode 100644
index 4be7d44aeacf..000000000000
--- a/Documentation/ABI/testing/sysfs-firmware-sfi
+++ /dev/null
@@ -1,15 +0,0 @@
-What: /sys/firmware/sfi/tables/
-Date: May 2010
-Contact: Len Brown <lenb@kernel.org>
-Description:
- SFI defines a number of small static memory tables
- so the kernel can get platform information from firmware.
-
- The tables are defined in the latest SFI specification:
- http://simplefirmware.org/documentation
-
- While the tables are used by the kernel, user-space
- can observe them this way:
-
- # cd /sys/firmware/sfi/tables
- # cat $TABLENAME > $TABLENAME.bin
diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv
index 4573fd4b7876..7fe9244b87bb 100644
--- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv
+++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv
@@ -1,27 +1,159 @@
What: /sys/firmware/sgi_uv/
-Date: August 2008
-Contact: Russ Anderson <rja@sgi.com>
+Date: September 2020
+Contact: Justin Ernst <justin.ernst@hpe.com>
Description:
The /sys/firmware/sgi_uv directory contains information
- about the SGI UV platform.
+ about the UV platform.
- Under that directory are a number of files:
+ Under that directory are a number of read-only attributes::
+ archtype
+ hub_type
+ hubless
partition_id
coherence_id
+ uv_type
+
+ The archtype entry contains the UV architecture type that
+ is used to select arch-dependent addresses and features.
+ It can be set via the OEM_ID in the ACPI MADT table or by
+ UVsystab entry both passed from UV BIOS.
+
+ The hub_type entry is used to select the type of hub which is
+ similar to uv_type but encoded in a binary format. Include
+ the file uv_hub.h to get the definitions.
+
+ The hubless entry basically is present and set only if there
+ is no hub. In this case the hub_type entry is not present.
The partition_id entry contains the partition id.
- SGI UV systems can be partitioned into multiple physical
+ UV systems can be partitioned into multiple physical
machines, which each partition running a unique copy
- of the operating system. Each partition will have a unique
- partition id. To display the partition id, use the command:
-
- cat /sys/firmware/sgi_uv/partition_id
+ of the operating system. Each partition will have a unique
+ partition id.
The coherence_id entry contains the coherence id.
- A partitioned SGI UV system can have one or more coherence
- domain. The coherence id indicates which coherence domain
- this partition is in. To display the coherence id, use the
- command:
+ A partitioned UV system can have one or more coherence
+ domains. The coherence id indicates which coherence domain
+ this partition is in.
+
+ The uv_type entry contains the hub revision number.
+ This value can be used to identify the UV system version::
+
+ "0.*" = Hubless UV ('*' is subtype)
+ "3.0" = UV2
+ "5.0" = UV3
+ "7.0" = UV4
+ "7.1" = UV4a
+ "9.0" = UV5
+
+ The /sys/firmware/sgi_uv directory also contains two directories::
+
+ hubs/
+ pcibuses/
+
+ The hubs directory contains a number of hub objects, each representing
+ a UV Hub visible to the BIOS. Each hub object's name is appended by a
+ unique ordinal value (ex. /sys/firmware/sgi_uv/hubs/hub_5)
+
+ Each hub object directory contains a number of read-only attributes::
+
+ cnode
+ location
+ name
+ nasid
+ shared
+ this_partition
+
+ The cnode entry contains the cnode number of the corresponding hub.
+ If a cnode value is not applicable, the value returned will be -1.
+
+ The location entry contains the location string of the corresponding hub.
+ This value is used to physically identify a hub within a system.
+
+ The name entry contains the name of the corresponding hub. This name can
+ be two variants::
+
+ "UVHub x.x" = A 'node' ASIC, connecting a CPU to the interconnect
+ fabric. The 'x.x' value represents the ASIC revision.
+ (ex. 'UVHub 5.0')
+
+ "NLxRouter" = A 'router ASIC, only connecting other ASICs to
+ the interconnect fabric. The 'x' value representing
+ the fabric technology version. (ex. 'NL8Router')
+
+ The nasid entry contains the nasid number of the corresponding hub.
+ If a nasid value is not applicable, the value returned will be -1.
+
+ The shared entry contains a boolean value describing whether the
+ corresponding hub is shared between system partitions.
+
+ The this_partition entry contains a boolean value describing whether
+ the corresponding hub is local to the current partition.
+
+ Each hub object directory also contains a number of port objects,
+ each representing a fabric port on the corresponding hub.
+ A port object's name is appended by a unique ordinal value
+ (ex. /sys/firmware/sgi_uv/hubs/hub_5/port_3)
+
+ Each port object directory contains a number of read-only attributes::
+
+ conn_hub
+ conn_port
+
+ The conn_hub entry contains a value representing the unique
+ ordinal value of the hub on the other end of the fabric
+ cable plugged into the port. If the port is disconnected,
+ the value returned will be -1.
+
+ The conn_port entry contains a value representing the unique
+ ordinal value of the port on the other end of the fabric cable
+ plugged into the port. If the port is disconnected, the value
+ returned will be -1.
+
+ Ex:
+ A value of '3' is read from:
+ /sys/firmware/sgi_uv/hubs/hub_5/port_3/conn_hub
+
+ and a value of '6' is read from:
+ /sys/firmware/sgi_uv/hubs/hub_5/port_3/conn_port
+
+ representing that this port is connected to:
+ /sys/firmware/sgi_uv/hubs/hub_3/port_6
+
+ The pcibuses directory contains a number of PCI bus objects.
+ Each PCI bus object's name is appended by its PCI bus address.
+ (ex. pcibus_0003:80)
+
+ Each pcibus object has a number of possible read-only attributes::
+
+ type
+ location
+ slot
+ ppb_addr
+ iio_stack
+
+ The type entry contains a value describing the type of IO at
+ the corresponding PCI bus address. Known possible values
+ across all UV versions are::
+
+ BASE IO
+ PCIe IO
+ PCIe SLOT
+ NODE IO
+ Riser
+ PPB
+
+ The location entry contains the location string of the UV Hub
+ of the CPU physically connected to the corresponding PCI bus.
+
+ The slot entry contains the physical slot number of the
+ corresponding PCI bus. This value is used to physically locate
+ PCI cards within a system.
+
+ The ppb_addr entry contains the PCI address string of the
+ bridged PCI bus. This entry is only present when the PCI bus
+ object type is 'PPB'.
- cat /sys/firmware/sgi_uv/coherence_id
+ The iio_stack entry contains a value describing the IIO stack
+ number that the corresponding PCI bus object is connected to.
diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
new file mode 100644
index 000000000000..26741cb84504
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
@@ -0,0 +1,28 @@
+What: /sys/firmware/turris-mox-rwtm/board_version
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) Board version burned into eFuses of this Turris Mox board.
+ Format: %i
+
+What: /sys/firmware/turris-mox-rwtm/mac_address*
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) MAC addresses burned into eFuses of this Turris Mox board.
+ Format: %pM
+
+What: /sys/firmware/turris-mox-rwtm/ram_size
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) RAM size in MiB of this Turris Mox board as was detected
+ during manufacturing and burned into eFuses. Can be 512 or 1024.
+ Format: %i
+
+What: /sys/firmware/turris-mox-rwtm/serial_number
+Date: August 2019
+KernelVersion: 5.4
+Contact: Marek Behún <kabel@kernel.org>
+Description: (Read) Serial number burned into eFuses of this Turris Mox device.
+ Format: %016X
diff --git a/Documentation/ABI/testing/sysfs-fs-erofs b/Documentation/ABI/testing/sysfs-fs-erofs
new file mode 100644
index 000000000000..76d9808ed581
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-fs-erofs
@@ -0,0 +1,45 @@
+What: /sys/fs/erofs/features/
+Date: November 2021
+Contact: "Huang Jianan" <huangjianan@oppo.com>
+Description: Shows all enabled kernel features.
+ Supported features:
+ zero_padding, compr_cfgs, big_pcluster, chunked_file,
+ device_table, compr_head2, sb_chksum, ztailpacking,
+ dedupe, fragments, 48bit, metabox.
+
+What: /sys/fs/erofs/<disk>/sync_decompress
+Date: November 2021
+Contact: "Huang Jianan" <huangjianan@oppo.com>
+Description: Control strategy of sync decompression:
+
+ - 0 (default, auto): enable for readpage, and enable for
+ readahead on atomic contexts only.
+ - 1 (force on): enable for readpage and readahead.
+ - 2 (force off): disable for all situations.
+
+What: /sys/fs/erofs/<disk>/drop_caches
+Date: November 2024
+Contact: "Guo Chunhai" <guochunhai@vivo.com>
+Description: Writing to this will drop compression-related caches,
+ currently used to drop in-memory pclusters and cached
+ compressed folios:
+
+ - 1 : invalidate cached compressed folios
+ - 2 : drop in-memory pclusters
+ - 3 : drop in-memory pclusters and cached compressed folios
+
+What: /sys/fs/erofs/accel
+Date: May 2025
+Contact: "Bo Liu" <liubo03@inspur.com>
+Description: Used to set or show hardware accelerators in effect
+ and multiple accelerators are separated by '\n'.
+ Supported accelerator(s): qat_deflate.
+ Disable all accelerators with an empty string (echo > accel).
+
+What: /sys/fs/erofs/<disk>/dir_ra_bytes
+Date: July 2025
+Contact: "Chao Yu" <chao@kernel.org>
+Description: Used to set or show readahead bytes during readdir(), by
+ default the value is 16384.
+
+ - 0: disable readahead.
diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4
index c631253cf85c..2edd0a6672d3 100644
--- a/Documentation/ABI/testing/sysfs-fs-ext4
+++ b/Documentation/ABI/testing/sysfs-fs-ext4
@@ -33,7 +33,7 @@ What: /sys/fs/ext4/<disk>/mb_order2_req
Date: March 2008
Contact: "Theodore Ts'o" <tytso@mit.edu>
Description:
- Tuning parameter which controls the minimum size for
+ Tuning parameter which controls the minimum size for
requests (as a power of 2) where the buddy cache is
used
@@ -45,8 +45,8 @@ Description:
parameter will have their blocks allocated out of a
block group specific preallocation pool, so that small
files are packed closely together. Each large file
- will have its blocks allocated out of its own unique
- preallocation pool.
+ will have its blocks allocated out of its own unique
+ preallocation pool.
What: /sys/fs/ext4/<disk>/inode_readahead_blks
Date: March 2008
@@ -109,3 +109,10 @@ Description:
write operation (since a 4k random write might turn
into a much larger write due to the zeroout
operation).
+
+What: /sys/fs/ext4/<disk>/journal_task
+Date: February 2019
+Contact: "Theodore Ts'o" <tytso@mit.edu>
+Description:
+ This file is read-only and shows the pid of journal thread in
+ current pid-namespace or 0 if task is unreachable.
diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs
index 2c4cc42006e8..770470e0598b 100644
--- a/Documentation/ABI/testing/sysfs-fs-f2fs
+++ b/Documentation/ABI/testing/sysfs-fs-f2fs
@@ -1,82 +1,941 @@
What: /sys/fs/f2fs/<disk>/gc_max_sleep_time
Date: July 2013
Contact: "Namjae Jeon" <namjae.jeon@samsung.com>
-Description:
- Controls the maximun sleep time for gc_thread. Time
- is in milliseconds.
+Description: Controls the maximum sleep time for gc_thread. Time
+ is in milliseconds.
What: /sys/fs/f2fs/<disk>/gc_min_sleep_time
Date: July 2013
Contact: "Namjae Jeon" <namjae.jeon@samsung.com>
-Description:
- Controls the minimum sleep time for gc_thread. Time
- is in milliseconds.
+Description: Controls the minimum sleep time for gc_thread. Time
+ is in milliseconds.
What: /sys/fs/f2fs/<disk>/gc_no_gc_sleep_time
Date: July 2013
Contact: "Namjae Jeon" <namjae.jeon@samsung.com>
-Description:
- Controls the default sleep time for gc_thread. Time
- is in milliseconds.
+Description: Controls the default sleep time for gc_thread. Time
+ is in milliseconds.
What: /sys/fs/f2fs/<disk>/gc_idle
Date: July 2013
Contact: "Namjae Jeon" <namjae.jeon@samsung.com>
-Description:
- Controls the victim selection policy for garbage collection.
+Description: Controls the victim selection policy for garbage collection.
+ Setting gc_idle = 0(default) will disable this option. Setting:
+
+ =========== ===============================================
+ gc_idle = 1 will select the Cost Benefit approach & setting
+ gc_idle = 2 will select the greedy approach & setting
+ gc_idle = 3 will select the age-threshold based approach.
+ =========== ===============================================
What: /sys/fs/f2fs/<disk>/reclaim_segments
Date: October 2013
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the issue rate of segment discard commands.
+Description: This parameter controls the number of prefree segments to be
+ reclaimed. If the number of prefree segments is larger than
+ the number of segments in the proportion to the percentage
+ over total volume size, f2fs tries to conduct checkpoint to
+ reclaim the prefree segments to free segments.
+ By default, 5% over total # of segments.
+
+What: /sys/fs/f2fs/<disk>/main_blkaddr
+Date: November 2019
+Contact: "Ramon Pantin" <pantin@google.com>
+Description: Shows first block address of MAIN area.
What: /sys/fs/f2fs/<disk>/ipu_policy
Date: November 2013
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the in-place-update policy.
+Description: Controls the in-place-update policy.
+ updates in f2fs. User can set:
+
+ ===== =============== ===================================================
+ value policy description
+ 0x00 DISABLE disable IPU(=default option in LFS mode)
+ 0x01 FORCE all the time
+ 0x02 SSR if SSR mode is activated
+ 0x04 UTIL if FS utilization is over threshold
+ 0x08 SSR_UTIL if SSR mode is activated and FS utilization is over
+ threshold
+ 0x10 FSYNC activated in fsync path only for high performance
+ flash storages. IPU will be triggered only if the
+ # of dirty pages over min_fsync_blocks.
+ (=default option)
+ 0x20 ASYNC do IPU given by asynchronous write requests
+ 0x40 NOCACHE disable IPU bio cache
+ 0x80 HONOR_OPU_WRITE use OPU write prior to IPU write if inode has
+ FI_OPU_WRITE flag
+ ===== =============== ===================================================
+
+ Refer segment.h for details.
What: /sys/fs/f2fs/<disk>/min_ipu_util
Date: November 2013
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the FS utilization condition for the in-place-update
- policies.
+Description: Controls the FS utilization condition for the in-place-update
+ policies. It is used by F2FS_IPU_UTIL and F2FS_IPU_SSR_UTIL policies.
What: /sys/fs/f2fs/<disk>/min_fsync_blocks
Date: September 2014
Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
-Description:
- Controls the dirty page count condition for the in-place-update
- policies.
+Description: Controls the dirty page count condition for the in-place-update
+ policies.
+
+What: /sys/fs/f2fs/<disk>/min_seq_blocks
+Date: August 2018
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Controls the dirty page count condition for batched sequential
+ writes in writepages.
+
+What: /sys/fs/f2fs/<disk>/min_hot_blocks
+Date: March 2017
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Controls the dirty page count condition for redefining hot data.
+
+What: /sys/fs/f2fs/<disk>/min_ssr_sections
+Date: October 2017
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Controls the free section threshold to trigger SSR allocation.
+ If this is large, SSR mode will be enabled early.
What: /sys/fs/f2fs/<disk>/max_small_discards
Date: November 2013
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the issue rate of small discard commands.
+Description: Controls the issue rate of discard commands that consist of small
+ blocks less than 2MB. The candidates to be discarded are cached during
+ checkpoint, and issued by issue_discard thread after checkpoint.
+ It is enabled by default.
+
+What: /sys/fs/f2fs/<disk>/max_ordered_discard
+Date: October 2022
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: Controls the maximum ordered discard, the unit size is one block(4KB).
+ Set it to 16 by default.
+
+What: /sys/fs/f2fs/<disk>/max_discard_request
+Date: December 2021
+Contact: "Konstantin Vyshetsky" <vkon@google.com>
+Description: Controls the number of discards a thread will issue at a time.
+ Higher number will allow the discard thread to finish its work
+ faster, at the cost of higher latency for incoming I/O.
+
+What: /sys/fs/f2fs/<disk>/min_discard_issue_time
+Date: December 2021
+Contact: "Konstantin Vyshetsky" <vkon@google.com>
+Description: Controls the interval the discard thread will wait between
+ issuing discard requests when there are discards to be issued and
+ no I/O aware interruptions occur.
+
+What: /sys/fs/f2fs/<disk>/mid_discard_issue_time
+Date: December 2021
+Contact: "Konstantin Vyshetsky" <vkon@google.com>
+Description: Controls the interval the discard thread will wait between
+ issuing discard requests when there are discards to be issued and
+ an I/O aware interruption occurs.
+
+What: /sys/fs/f2fs/<disk>/max_discard_issue_time
+Date: December 2021
+Contact: "Konstantin Vyshetsky" <vkon@google.com>
+Description: Controls the interval the discard thread will wait when there are
+ no discard operations to be issued.
+
+What: /sys/fs/f2fs/<disk>/discard_granularity
+Date: July 2017
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Controls discard granularity of inner discard thread. Inner thread
+ will not issue discards with size that is smaller than granularity.
+ The unit size is one block(4KB), now only support configuring
+ in range of [1, 512]. Default value is 16.
+ For small devices, default value is 1.
+
+What: /sys/fs/f2fs/<disk>/umount_discard_timeout
+Date: January 2019
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Set timeout to issue discard commands during umount.
+ Default: 5 secs
+
+What: /sys/fs/f2fs/<disk>/pending_discard
+Date: November 2021
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Shows the number of pending discard commands in the queue.
What: /sys/fs/f2fs/<disk>/max_victim_search
Date: January 2014
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the number of trials to find a victim segment.
+Description: Controls the number of trials to find a victim segment
+ when conducting SSR and cleaning operations. The default value
+ is 4096 which covers 8GB block address range.
+
+What: /sys/fs/f2fs/<disk>/migration_granularity
+Date: October 2018
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Controls migration granularity of garbage collection on large
+ section, it can let GC move partial segment{s} of one section
+ in one GC cycle, so that dispersing heavy overhead GC to
+ multiple lightweight one.
What: /sys/fs/f2fs/<disk>/dir_level
Date: March 2014
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the directory level for large directory.
+Description: Controls the directory level for large directory. If a
+ directory has a number of files, it can reduce the file lookup
+ latency by increasing this dir_level value. Otherwise, it
+ needs to decrease this value to reduce the space overhead.
+ The default value is 0.
What: /sys/fs/f2fs/<disk>/ram_thresh
Date: March 2014
Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com>
-Description:
- Controls the memory footprint used by f2fs.
+Description: Controls the memory footprint used by free nids and cached
+ nat entries. By default, 1 is set, which indicates
+ 10 MB / 1 GB RAM.
+
+What: /sys/fs/f2fs/<disk>/cp_interval
+Date: October 2015
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Controls the checkpoint timing, set to 60 seconds by default.
+
+What: /sys/fs/f2fs/<disk>/idle_interval
+Date: January 2016
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Controls the idle timing of system, if there is no FS operation
+ during given interval.
+ Set to 5 seconds by default.
+
+What: /sys/fs/f2fs/<disk>/discard_idle_interval
+Date: September 2018
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Contact: "Sahitya Tummala" <quic_stummala@quicinc.com>
+Description: Controls the idle timing of discard thread given
+ this time interval.
+ Default is 5 secs.
-What: /sys/fs/f2fs/<disk>/trim_sections
-Date: February 2015
+What: /sys/fs/f2fs/<disk>/gc_idle_interval
+Date: September 2018
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Contact: "Sahitya Tummala" <quic_stummala@quicinc.com>
+Description: Controls the idle timing for gc path. Set to 5 seconds by default.
+
+What: /sys/fs/f2fs/<disk>/iostat_enable
+Date: August 2017
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Controls to enable/disable IO stat.
+
+What: /sys/fs/f2fs/<disk>/ra_nid_pages
+Date: October 2015
+Contact: "Chao Yu" <chao2.yu@samsung.com>
+Description: Controls the count of nid pages to be readaheaded.
+ When building free nids, F2FS reads NAT blocks ahead for
+ speed up. Default is 0.
+
+What: /sys/fs/f2fs/<disk>/dirty_nats_ratio
+Date: January 2016
+Contact: "Chao Yu" <chao2.yu@samsung.com>
+Description: Controls dirty nat entries ratio threshold, if current
+ ratio exceeds configured threshold, checkpoint will
+ be triggered for flushing dirty nat entries.
+
+What: /sys/fs/f2fs/<disk>/lifetime_write_kbytes
+Date: January 2016
+Contact: "Shuoran Liu" <liushuoran@huawei.com>
+Description: Shows total written kbytes issued to disk.
+
+What: /sys/fs/f2fs/<disk>/features
+Date: July 2017
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: <deprecated: should use /sys/fs/f2fs/<disk>/feature_list/>
+ Shows all enabled features in current device.
+ Supported features:
+ encryption, blkzoned, extra_attr, projquota, inode_checksum,
+ flexible_inline_xattr, quota_ino, inode_crtime, lost_found,
+ verity, sb_checksum, casefold, readonly, compression, pin_file.
+
+What: /sys/fs/f2fs/<disk>/feature_list/
+Date: June 2021
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Expand /sys/fs/f2fs/<disk>/features to meet sysfs rule.
+ Supported on-disk features:
+ encryption, block_zoned (aka blkzoned), extra_attr,
+ project_quota (aka projquota), inode_checksum,
+ flexible_inline_xattr, quota_ino, inode_crtime, lost_found,
+ verity, sb_checksum, casefold, readonly, compression.
+ Note that, pin_file is moved into /sys/fs/f2fs/features/.
+
+What: /sys/fs/f2fs/features/
+Date: July 2017
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Shows all enabled kernel features.
+ Supported features:
+ encryption, block_zoned, extra_attr, project_quota,
+ inode_checksum, flexible_inline_xattr, quota_ino,
+ inode_crtime, lost_found, verity, sb_checksum,
+ casefold, readonly, compression, test_dummy_encryption_v2,
+ atomic_write, pin_file, encrypted_casefold, linear_lookup.
+
+What: /sys/fs/f2fs/<disk>/inject_rate
+Date: May 2016
+Contact: "Sheng Yong" <shengyong1@huawei.com>
+Description: Controls the injection rate of arbitrary faults.
+
+What: /sys/fs/f2fs/<disk>/inject_type
+Date: May 2016
+Contact: "Sheng Yong" <shengyong1@huawei.com>
+Description: Controls the injection type of arbitrary faults.
+
+What: /sys/fs/f2fs/<disk>/dirty_segments
+Date: October 2017
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Shows the number of dirty segments.
+
+What: /sys/fs/f2fs/<disk>/reserved_blocks
+Date: June 2017
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Controls target reserved blocks in system, the threshold
+ is soft, it could exceed current available user space.
+
+What: /sys/fs/f2fs/<disk>/current_reserved_blocks
+Date: October 2017
+Contact: "Yunlong Song" <yunlong.song@huawei.com>
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Shows current reserved blocks in system, it may be temporarily
+ smaller than target_reserved_blocks, but will gradually
+ increase to target_reserved_blocks when more free blocks are
+ freed by user later.
+
+What: /sys/fs/f2fs/<disk>/gc_urgent
+Date: August 2017
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Do background GC aggressively when set. Set to 0 by default.
+ gc urgent high(1): does GC forcibly in a period of given
+ gc_urgent_sleep_time and ignores I/O idling check. uses greedy
+ GC approach and turns SSR mode on.
+ gc urgent low(2): lowers the bar of checking I/O idling in
+ order to process outstanding discard commands and GC a
+ little bit aggressively. always uses cost benefit GC approach,
+ and will override age-threshold GC approach if ATGC is enabled
+ at the same time.
+ gc urgent mid(3): does GC forcibly in a period of given
+ gc_urgent_sleep_time and executes a mid level of I/O idling check.
+ always uses cost benefit GC approach, and will override
+ age-threshold GC approach if ATGC is enabled at the same time.
+
+What: /sys/fs/f2fs/<disk>/gc_urgent_sleep_time
+Date: August 2017
Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Controls sleep time of GC urgent mode. Set to 500ms by default.
+
+What: /sys/fs/f2fs/<disk>/readdir_ra
+Date: November 2017
+Contact: "Sheng Yong" <shengyong1@huawei.com>
+Description: Controls readahead inode block in readdir. Enabled by default.
+
+What: /sys/fs/f2fs/<disk>/gc_pin_file_thresh
+Date: January 2018
+Contact: Jaegeuk Kim <jaegeuk@kernel.org>
+Description: This indicates how many GC can be failed for the pinned
+ file. If it exceeds this, F2FS doesn't guarantee its pinning
+ state. 2048 trials is set by default, and 65535 as maximum.
+
+What: /sys/fs/f2fs/<disk>/extension_list
+Date: February 2018
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Used to control configure extension list:
+ - Query: cat /sys/fs/f2fs/<disk>/extension_list
+ - Add: echo '[h/c]extension' > /sys/fs/f2fs/<disk>/extension_list
+ - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list
+ - [h] means add/del hot file extension
+ - [c] means add/del cold file extension
+
+What: /sys/fs/f2fs/<disk>/unusable
+Date: April 2019
+Contact: "Daniel Rosenberg" <drosen@google.com>
+Description: If checkpoint=disable, it displays the number of blocks that
+ are unusable.
+ If checkpoint=enable it displays the number of blocks that
+ would be unusable if checkpoint=disable were to be set.
+
+What: /sys/fs/f2fs/<disk>/encoding
+Date: July 2019
+Contact: "Daniel Rosenberg" <drosen@google.com>
+Description: Displays name and version of the encoding set for the filesystem.
+ If no encoding is set, displays (none)
+
+What: /sys/fs/f2fs/<disk>/free_segments
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of free segments in disk.
+
+What: /sys/fs/f2fs/<disk>/cp_foreground_calls
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of checkpoint operations performed on demand. Available when
+ CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/cp_background_calls
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of checkpoint operations performed in the background to
+ free segments. Available when CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/gc_foreground_calls
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of garbage collection operations performed on demand.
+ Available when CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/gc_background_calls
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of garbage collection operations triggered in background.
+ Available when CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/moved_blocks_foreground
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of blocks moved by garbage collection in foreground.
+ Available when CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/moved_blocks_background
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Number of blocks moved by garbage collection in background.
+ Available when CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/avg_vblocks
+Date: September 2019
+Contact: "Hridya Valsaraju" <hridya@google.com>
+Description: Average number of valid blocks.
+ Available when CONFIG_F2FS_STAT_FS=y.
+
+What: /sys/fs/f2fs/<disk>/mounted_time_sec
+Date: February 2020
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Show the mounted time in secs of this partition.
+
+What: /sys/fs/f2fs/<disk>/data_io_flag
+Date: April 2020
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Give a way to attach REQ_META|FUA to data writes
+ given temperature-based bits. Now the bits indicate:
+
+ +-------------------+-------------------+
+ | REQ_META | REQ_FUA |
+ +------+------+-----+------+------+-----+
+ | 5 | 4 | 3 | 2 | 1 | 0 |
+ +------+------+-----+------+------+-----+
+ | Cold | Warm | Hot | Cold | Warm | Hot |
+ +------+------+-----+------+------+-----+
+
+What: /sys/fs/f2fs/<disk>/node_io_flag
+Date: June 2020
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Give a way to attach REQ_META|FUA to node writes
+ given temperature-based bits. Now the bits indicate:
+
+ +-------------------+-------------------+
+ | REQ_META | REQ_FUA |
+ +------+------+-----+------+------+-----+
+ | 5 | 4 | 3 | 2 | 1 | 0 |
+ +------+------+-----+------+------+-----+
+ | Cold | Warm | Hot | Cold | Warm | Hot |
+ +------+------+-----+------+------+-----+
+
+What: /sys/fs/f2fs/<disk>/iostat_period_ms
+Date: April 2020
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Give a way to change iostat_period time. 3secs by default.
+ The new iostat trace gives stats gap given the period.
+What: /sys/fs/f2fs/<disk>/max_io_bytes
+Date: December 2020
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: This gives a control to limit the bio size in f2fs.
+ Default is zero, which will follow underlying block layer limit,
+ whereas, if it has a certain bytes value, f2fs won't submit a
+ bio larger than that size.
+
+What: /sys/fs/f2fs/<disk>/stat/sb_status
+Date: December 2020
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: Show status of f2fs superblock in real time.
+
+ ====== ===================== =================================
+ value sb status macro description
+ 0x1 SBI_IS_DIRTY dirty flag for checkpoint
+ 0x2 SBI_IS_CLOSE specify unmounting
+ 0x4 SBI_NEED_FSCK need fsck.f2fs to fix
+ 0x8 SBI_POR_DOING recovery is doing or not
+ 0x10 SBI_NEED_SB_WRITE need to recover superblock
+ 0x20 SBI_NEED_CP need to checkpoint
+ 0x40 SBI_IS_SHUTDOWN shutdown by ioctl
+ 0x80 SBI_IS_RECOVERED recovered orphan/data
+ 0x100 SBI_CP_DISABLED CP was disabled last mount
+ 0x200 SBI_CP_DISABLED_QUICK CP was disabled quickly
+ 0x400 SBI_QUOTA_NEED_FLUSH need to flush quota info in CP
+ 0x800 SBI_QUOTA_SKIP_FLUSH skip flushing quota in current CP
+ 0x1000 SBI_QUOTA_NEED_REPAIR quota file may be corrupted
+ 0x2000 SBI_IS_RESIZEFS resizefs is in process
+ 0x4000 SBI_IS_FREEZING freefs is in process
+ ====== ===================== =================================
+
+What: /sys/fs/f2fs/<disk>/stat/cp_status
+Date: September 2022
+Contact: "Chao Yu" <chao.yu@oppo.com>
+Description: Show status of f2fs checkpoint in real time.
+
+ =============================== ==============================
+ cp flag value
+ CP_UMOUNT_FLAG 0x00000001
+ CP_ORPHAN_PRESENT_FLAG 0x00000002
+ CP_COMPACT_SUM_FLAG 0x00000004
+ CP_ERROR_FLAG 0x00000008
+ CP_FSCK_FLAG 0x00000010
+ CP_FASTBOOT_FLAG 0x00000020
+ CP_CRC_RECOVERY_FLAG 0x00000040
+ CP_NAT_BITS_FLAG 0x00000080
+ CP_TRIMMED_FLAG 0x00000100
+ CP_NOCRC_RECOVERY_FLAG 0x00000200
+ CP_LARGE_NAT_BITMAP_FLAG 0x00000400
+ CP_QUOTA_NEED_FSCK_FLAG 0x00000800
+ CP_DISABLED_FLAG 0x00001000
+ CP_DISABLED_QUICK_FLAG 0x00002000
+ CP_RESIZEFS_FLAG 0x00004000
+ =============================== ==============================
+
+What: /sys/fs/f2fs/<disk>/stat/issued_discard
+Date: December 2023
+Contact: "Zhiguo Niu" <zhiguo.niu@unisoc.com>
+Description: Shows the number of issued discard.
+
+What: /sys/fs/f2fs/<disk>/stat/queued_discard
+Date: December 2023
+Contact: "Zhiguo Niu" <zhiguo.niu@unisoc.com>
+Description: Shows the number of queued discard.
+
+What: /sys/fs/f2fs/<disk>/stat/undiscard_blks
+Date: December 2023
+Contact: "Zhiguo Niu" <zhiguo.niu@unisoc.com>
+Description: Shows the total number of undiscard blocks.
+
+What: /sys/fs/f2fs/<disk>/ckpt_thread_ioprio
+Date: January 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Give a way to change checkpoint merge daemon's io priority.
+ Its default value is "be,3", which means "BE" I/O class and
+ I/O priority "3". We can select the class between "rt" and "be",
+ and set the I/O priority within valid range of it. "," delimiter
+ is necessary in between I/O class and priority number.
+
+What: /sys/fs/f2fs/<disk>/ovp_segments
+Date: March 2021
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Shows the number of overprovision segments.
+
+What: /sys/fs/f2fs/<disk>/compr_written_block
+Date: March 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the block count written after compression since mount. Note
+ that when the compressed blocks are deleted, this count doesn't
+ decrease. If you write "0" here, you can initialize
+ compr_written_block and compr_saved_block to "0".
+
+What: /sys/fs/f2fs/<disk>/compr_saved_block
+Date: March 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the saved block count with compression since mount. Note
+ that when the compressed blocks are deleted, this count doesn't
+ decrease. If you write "0" here, you can initialize
+ compr_written_block and compr_saved_block to "0".
+
+What: /sys/fs/f2fs/<disk>/compr_new_inode
+Date: March 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the count of inode newly enabled for compression since mount.
+ Note that when the compression is disabled for the files, this count
+ doesn't decrease. If you write "0" here, you can initialize
+ compr_new_inode to "0".
+
+What: /sys/fs/f2fs/<disk>/atgc_candidate_ratio
+Date: May 2021
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: When ATGC is on, it controls candidate ratio in order to limit total
+ number of potential victim in all candidates, the value should be in
+ range of [0, 100], by default it was initialized as 20(%).
+
+What: /sys/fs/f2fs/<disk>/atgc_candidate_count
+Date: May 2021
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: When ATGC is on, it controls candidate count in order to limit total
+ number of potential victim in all candidates, by default it was
+ initialized as 10 (sections).
+
+What: /sys/fs/f2fs/<disk>/atgc_age_weight
+Date: May 2021
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: When ATGC is on, it controls age weight to balance weight proportion
+ in between aging and valid blocks, the value should be in range of
+ [0, 100], by default it was initialized as 60(%).
+
+What: /sys/fs/f2fs/<disk>/atgc_age_threshold
+Date: May 2021
+Contact: "Chao Yu" <yuchao0@huawei.com>
+Description: When ATGC is on, it controls age threshold to bypass GCing young
+ candidates whose age is not beyond the threshold, by default it was
+ initialized as 604800 seconds (equals to 7 days).
+
+What: /sys/fs/f2fs/<disk>/atgc_enabled
+Date: Feb 2024
+Contact: "Jinbao Liu" <liujinbao1@xiaomi.com>
+Description: It represents whether ATGC is on or off. The value is 1 which
+ indicates that ATGC is on, and 0 indicates that it is off.
+
+What: /sys/fs/f2fs/<disk>/gc_reclaimed_segments
+Date: July 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show how many segments have been reclaimed by GC during a specific
+ GC mode (0: GC normal, 1: GC idle CB, 2: GC idle greedy,
+ 3: GC idle AT, 4: GC urgent high, 5: GC urgent low 6: GC urgent mid)
+ You can re-initialize this value to "0".
+
+What: /sys/fs/f2fs/<disk>/gc_segment_mode
+Date: July 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: You can control for which gc mode the "gc_reclaimed_segments" node shows.
+ Refer to the description of the modes in "gc_reclaimed_segments".
+
+What: /sys/fs/f2fs/<disk>/seq_file_ra_mul
+Date: July 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: You can control the multiplier value of bdi device readahead window size
+ between 2 (default) and 256 for POSIX_FADV_SEQUENTIAL advise option.
+
+What: /sys/fs/f2fs/<disk>/max_fragment_chunk
+Date: August 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: With "mode=fragment:block" mount options, we can scatter block allocation.
+ f2fs will allocate 1..<max_fragment_chunk> blocks in a chunk and make a hole
+ in the length of 1..<max_fragment_hole> by turns. This value can be set
+ between 1..512 and the default value is 4.
+
+What: /sys/fs/f2fs/<disk>/max_fragment_hole
+Date: August 2021
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: With "mode=fragment:block" mount options, we can scatter block allocation.
+ f2fs will allocate 1..<max_fragment_chunk> blocks in a chunk and make a hole
+ in the length of 1..<max_fragment_hole> by turns. This value can be set
+ between 1..512 and the default value is 4.
+
+What: /sys/fs/f2fs/<disk>/gc_remaining_trials
+Date: October 2022
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: You can set the trial count limit for GC urgent and idle mode with this value.
+ If GC thread gets to the limit, the mode will turn back to GC normal mode.
+ By default, the value is zero, which means there is no limit like before.
+
+What: /sys/fs/f2fs/<disk>/max_roll_forward_node_blocks
+Date: January 2022
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Controls max # of node block writes to be used for roll forward
+ recovery. This can limit the roll forward recovery time.
+
+What: /sys/fs/f2fs/<disk>/unusable_blocks_per_sec
+Date: June 2022
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: Shows the number of unusable blocks in a section which was defined by
+ the zone capacity reported by underlying zoned device.
+
+What: /sys/fs/f2fs/<disk>/max_open_zones
+Date: November 2025
+Contact: "Yongpeng Yang" <yangyongpeng@xiaomi.com>
+Description: Shows the max number of zones that F2FS can write concurrently when a zoned
+ device is mounted.
+
+What: /sys/fs/f2fs/<disk>/current_atomic_write
+Date: July 2022
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the total current atomic write block count, which is not committed yet.
+ This is a read-only entry.
+
+What: /sys/fs/f2fs/<disk>/peak_atomic_write
+Date: July 2022
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the peak value of total current atomic write block count after boot.
+ If you write "0" here, you can initialize to "0".
+
+What: /sys/fs/f2fs/<disk>/committed_atomic_block
+Date: July 2022
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the accumulated total committed atomic write block count after boot.
+ If you write "0" here, you can initialize to "0".
+
+What: /sys/fs/f2fs/<disk>/revoked_atomic_block
+Date: July 2022
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Show the accumulated total revoked atomic write block count after boot.
+ If you write "0" here, you can initialize to "0".
+
+What: /sys/fs/f2fs/<disk>/gc_mode
+Date: October 2022
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: Show the current gc_mode as a string.
+ This is a read-only entry.
+
+What: /sys/fs/f2fs/<disk>/discard_urgent_util
+Date: November 2022
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: When space utilization exceeds this, do background DISCARD aggressively.
+ Does DISCARD forcibly in a period of given min_discard_issue_time when the number
+ of discards is not 0 and set discard granularity to 1.
+ Default: 80
+
+What: /sys/fs/f2fs/<disk>/hot_data_age_threshold
+Date: November 2022
+Contact: "Ping Xiong" <xiongping1@xiaomi.com>
+Description: When DATA SEPARATION is on, it controls the age threshold to indicate
+ the data blocks as hot. By default it was initialized as 262144 blocks
+ (equals to 1GB).
+
+What: /sys/fs/f2fs/<disk>/warm_data_age_threshold
+Date: November 2022
+Contact: "Ping Xiong" <xiongping1@xiaomi.com>
+Description: When DATA SEPARATION is on, it controls the age threshold to indicate
+ the data blocks as warm. By default it was initialized as 2621440 blocks
+ (equals to 10GB).
+
+What: /sys/fs/f2fs/<disk>/fault_rate
+Date: May 2016
+Contact: "Sheng Yong" <shengyong@oppo.com>
+Contact: "Chao Yu" <chao@kernel.org>
+Description: Enable fault injection in all supported types with
+ specified injection rate.
+
+What: /sys/fs/f2fs/<disk>/fault_type
+Date: May 2016
+Contact: "Sheng Yong" <shengyong@oppo.com>
+Contact: "Chao Yu" <chao@kernel.org>
+Description: Support configuring fault injection type, should be
+ enabled with fault_injection option, fault type value
+ is shown below, it supports single or combined type.
+
+ =========================== ==========
+ Type_Name Type_Value
+ =========================== ==========
+ FAULT_KMALLOC 0x00000001
+ FAULT_KVMALLOC 0x00000002
+ FAULT_PAGE_ALLOC 0x00000004
+ FAULT_PAGE_GET 0x00000008
+ FAULT_ALLOC_BIO 0x00000010 (obsolete)
+ FAULT_ALLOC_NID 0x00000020
+ FAULT_ORPHAN 0x00000040
+ FAULT_BLOCK 0x00000080
+ FAULT_DIR_DEPTH 0x00000100
+ FAULT_EVICT_INODE 0x00000200
+ FAULT_TRUNCATE 0x00000400
+ FAULT_READ_IO 0x00000800
+ FAULT_CHECKPOINT 0x00001000
+ FAULT_DISCARD 0x00002000
+ FAULT_WRITE_IO 0x00004000
+ FAULT_SLAB_ALLOC 0x00008000
+ FAULT_DQUOT_INIT 0x00010000
+ FAULT_LOCK_OP 0x00020000
+ FAULT_BLKADDR_VALIDITY 0x00040000
+ FAULT_BLKADDR_CONSISTENCE 0x00080000
+ FAULT_NO_SEGMENT 0x00100000
+ FAULT_INCONSISTENT_FOOTER 0x00200000
+ FAULT_TIMEOUT 0x00400000 (1000ms)
+ FAULT_VMALLOC 0x00800000
+ =========================== ==========
+
+What: /sys/fs/f2fs/<disk>/discard_io_aware_gran
+Date: January 2023
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: Controls background discard granularity of inner discard thread
+ when is not in idle. Inner thread will not issue discards with size that
+ is smaller than granularity. The unit size is one block(4KB), now only
+ support configuring in range of [0, 512].
+ Default: 512
+
+What: /sys/fs/f2fs/<disk>/last_age_weight
+Date: January 2023
+Contact: "Ping Xiong" <xiongping1@xiaomi.com>
+Description: When DATA SEPARATION is on, it controls the weight of last data block age.
+
+What: /sys/fs/f2fs/<disk>/compress_watermark
+Date: February 2023
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: When compress cache is on, it controls free memory watermark
+ in order to limit caching compress page. If free memory is lower
+ than watermark, then deny caching compress page. The value should be in
+ range of (0, 100], by default it was initialized as 20(%).
+
+What: /sys/fs/f2fs/<disk>/compress_percent
+Date: February 2023
+Contact: "Yangtao Li" <frank.li@vivo.com>
+Description: When compress cache is on, it controls cached page
+ percent(compress pages / free_ram) in order to limit caching compress page.
+ If cached page percent exceed threshold, then deny caching compress page.
+ The value should be in range of (0, 100], by default it was initialized
+ as 20(%).
+
+What: /sys/fs/f2fs/<disk>/discard_io_aware
+Date: November 2023
+Contact: "Chao Yu" <chao@kernel.org>
+Description: It controls to enable/disable IO aware feature for background discard.
+ By default, the value is 1 which indicates IO aware is on.
+
+What: /sys/fs/f2fs/<disk>/blkzone_alloc_policy
+Date: July 2024
+Contact: "Yuanhong Liao" <liaoyuanhong@vivo.com>
+Description: The zone UFS we are currently using consists of two parts:
+ conventional zones and sequential zones. It can be used to control which part
+ to prioritize for writes, with a default value of 0.
+
+ ======================== =========================================
+ value description
+ blkzone_alloc_policy = 0 Prioritize writing to sequential zones
+ blkzone_alloc_policy = 1 Only allow writing to sequential zones
+ blkzone_alloc_policy = 2 Prioritize writing to conventional zones
+ ======================== =========================================
+
+What: /sys/fs/f2fs/<disk>/migration_window_granularity
+Date: September 2024
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Controls migration window granularity of garbage collection on large
+ section. it can control the scanning window granularity for GC migration
+ in a unit of segment, while migration_granularity controls the number
+ of segments which can be migrated at the same turn.
+
+What: /sys/fs/f2fs/<disk>/reserved_segments
+Date: September 2024
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: In order to fine tune GC behavior, we can control the number of
+ reserved segments.
+
+What: /sys/fs/f2fs/<disk>/gc_no_zoned_gc_percent
+Date: September 2024
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: If the percentage of free sections over total sections is above this
+ number, F2FS do not garbage collection for zoned devices through the
+ background GC thread. the default number is "60".
+
+What: /sys/fs/f2fs/<disk>/gc_boost_zoned_gc_percent
+Date: September 2024
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: If the percentage of free sections over total sections is under this
+ number, F2FS boosts garbage collection for zoned devices through the
+ background GC thread. the default number is "25".
+
+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 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
+Date: November 2024
+Contact: "Chao Yu" <chao@kernel.org>
+Description: It controls max read extent count for per-inode, the value of threshold
+ is 10240 by default.
+
+What: /sys/fs/f2fs/tuning/reclaim_caches_kb
+Date: February 2025
+Contact: "Jaegeuk Kim" <jaegeuk@kernel.org>
+Description: It reclaims the given KBs of file-backed pages registered by
+ ioctl(F2FS_IOC_DONATE_RANGE).
+ For example, writing N tries to drop N KBs spaces in LRU.
+
+What: /sys/fs/f2fs/<disk>/carve_out
+Date: March 2025
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: For several zoned storage devices, vendors will provide extra space which
+ was used for device level GC than specs and F2FS can use this space for
+ 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 subtracting reserved_blocks from total bytes.
+
+What: /sys/fs/f2fs/<disk>/encoding_flags
+Date: April 2025
+Contact: "Chao Yu" <chao@kernel.org>
+Description: This is a read-only entry to show the value of sb.s_encoding_flags, the
+ value is hexadecimal.
+
+ ============================ ==========
+ Flag_Name Flag_Value
+ ============================ ==========
+ SB_ENC_STRICT_MODE_FL 0x00000001
+ SB_ENC_NO_COMPAT_FALLBACK_FL 0x00000002
+ ============================ ==========
+
+What: /sys/fs/f2fs/<disk>/reserved_pin_section
+Date: June 2025
+Contact: "Chao Yu" <chao@kernel.org>
+Description: This threshold is used to control triggering garbage collection while
+ fallocating on pinned file, so, it can guarantee there is enough free
+ reserved section before preallocating on pinned file.
+ By default, the value is ovp_sections, especially, for zoned ufs, the
+ value is 1.
+
+What: /sys/fs/f2fs/<disk>/gc_boost_gc_multiple
+Date: June 2025
+Contact: "Daeho Jeong" <daehojeong@google.com>
+Description: Set a multiplier for the background GC migration window when F2FS GC is
+ boosted. The range should be from 1 to the segment count in a section.
+ Default: 5
+
+What: /sys/fs/f2fs/<disk>/gc_boost_gc_greedy
+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:
- Controls the trimming rate in batch mode.
+ 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/ABI/testing/sysfs-fs-ubifs b/Documentation/ABI/testing/sysfs-fs-ubifs
new file mode 100644
index 000000000000..af5afda30220
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-fs-ubifs
@@ -0,0 +1,35 @@
+What: /sys/fs/ubifsX_Y/error_magic
+Date: October 2021
+KernelVersion: 5.16
+Contact: linux-mtd@lists.infradead.org
+Description:
+ Exposes magic errors: every node starts with a magic number.
+
+ This counter keeps track of the number of accesses of nodes
+ with a corrupted magic number.
+
+ The counter is reset to 0 with a remount.
+
+What: /sys/fs/ubifsX_Y/error_node
+Date: October 2021
+KernelVersion: 5.16
+Contact: linux-mtd@lists.infradead.org
+Description:
+ Exposes node errors. Every node embeds its type.
+
+ This counter keeps track of the number of accesses of nodes
+ with a corrupted node type.
+
+ The counter is reset to 0 with a remount.
+
+What: /sys/fs/ubifsX_Y/error_crc
+Date: October 2021
+KernelVersion: 5.16
+Contact: linux-mtd@lists.infradead.org
+Description:
+ Exposes crc errors: every node embeds a crc checksum.
+
+ This counter keeps track of the number of accesses of nodes
+ with a bad crc checksum.
+
+ The counter is reset to 0 with a remount.
diff --git a/Documentation/ABI/testing/sysfs-fs-virtiofs b/Documentation/ABI/testing/sysfs-fs-virtiofs
new file mode 100644
index 000000000000..4839dbce997e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-fs-virtiofs
@@ -0,0 +1,11 @@
+What: /sys/fs/virtiofs/<n>/tag
+Date: Feb 2024
+Contact: virtio-fs@lists.linux.dev
+Description:
+ [RO] The mount "tag" that can be used to mount this filesystem.
+
+What: /sys/fs/virtiofs/<n>/device
+Date: Feb 2024
+Contact: virtio-fs@lists.linux.dev
+Description:
+ Symlink to the virtio device that exports this filesystem.
diff --git a/Documentation/ABI/testing/sysfs-fs-xfs b/Documentation/ABI/testing/sysfs-fs-xfs
index ea0cc8c42093..7da4de948b46 100644
--- a/Documentation/ABI/testing/sysfs-fs-xfs
+++ b/Documentation/ABI/testing/sysfs-fs-xfs
@@ -1,7 +1,7 @@
What: /sys/fs/xfs/<disk>/log/log_head_lsn
Date: July 2014
KernelVersion: 3.17
-Contact: xfs@oss.sgi.com
+Contact: linux-xfs@vger.kernel.org
Description:
The log sequence number (LSN) of the current head of the
log. The LSN is exported in "cycle:basic block" format.
@@ -10,30 +10,28 @@ Users: xfstests
What: /sys/fs/xfs/<disk>/log/log_tail_lsn
Date: July 2014
KernelVersion: 3.17
-Contact: xfs@oss.sgi.com
+Contact: linux-xfs@vger.kernel.org
Description:
The log sequence number (LSN) of the current tail of the
log. The LSN is exported in "cycle:basic block" format.
-What: /sys/fs/xfs/<disk>/log/reserve_grant_head
-Date: July 2014
-KernelVersion: 3.17
-Contact: xfs@oss.sgi.com
+What: /sys/fs/xfs/<disk>/log/reserve_grant_head_bytes
+Date: June 2024
+KernelVersion: 6.11
+Contact: linux-xfs@vger.kernel.org
Description:
The current state of the log reserve grant head. It
represents the total log reservation of all currently
- outstanding transactions. The grant head is exported in
- "cycle:bytes" format.
+ outstanding transactions in bytes.
Users: xfstests
-What: /sys/fs/xfs/<disk>/log/write_grant_head
-Date: July 2014
-KernelVersion: 3.17
-Contact: xfs@oss.sgi.com
+What: /sys/fs/xfs/<disk>/log/write_grant_head_bytes
+Date: June 2024
+KernelVersion: 6.11
+Contact: linux-xfs@vger.kernel.org
Description:
The current state of the log write grant head. It
represents the total log reservation of all currently
- oustanding transactions, including regrants due to
- rolling transactions. The grant head is exported in
- "cycle:bytes" format.
+ outstanding transactions, including regrants due to
+ rolling transactions in bytes.
Users: xfstests
diff --git a/Documentation/ABI/testing/sysfs-gpio b/Documentation/ABI/testing/sysfs-gpio
deleted file mode 100644
index 80f4c94c7bef..000000000000
--- a/Documentation/ABI/testing/sysfs-gpio
+++ /dev/null
@@ -1,27 +0,0 @@
-What: /sys/class/gpio/
-Date: July 2008
-KernelVersion: 2.6.27
-Contact: David Brownell <dbrownell@users.sourceforge.net>
-Description:
-
- As a Kconfig option, individual GPIO signals may be accessed from
- userspace. GPIOs are only made available to userspace by an explicit
- "export" operation. If a given GPIO is not claimed for use by
- kernel code, it may be exported by userspace (and unexported later).
- Kernel code may export it for complete or partial access.
-
- GPIOs are identified as they are inside the kernel, using integers in
- the range 0..INT_MAX. See Documentation/gpio.txt for more information.
-
- /sys/class/gpio
- /export ... asks the kernel to export a GPIO to userspace
- /unexport ... to return a GPIO to the kernel
- /gpioN ... for each exported GPIO #N
- /value ... always readable, writes fail for input GPIOs
- /direction ... r/w as: in, out (default low); write: high, low
- /edge ... r/w as: none, falling, rising, both
- /gpiochipN ... for each gpiochip; #N is its first GPIO
- /base ... (r/o) same as N
- /label ... (r/o) descriptive, not necessarily unique
- /ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1)
-
diff --git a/Documentation/ABI/testing/sysfs-hypervisor-xen b/Documentation/ABI/testing/sysfs-hypervisor-xen
new file mode 100644
index 000000000000..4dbe0c49b393
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-hypervisor-xen
@@ -0,0 +1,46 @@
+What: /sys/hypervisor/guest_type
+Date: June 2017
+KernelVersion: 4.13
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Type of guest:
+ "Xen": standard guest type on arm
+ "HVM": fully virtualized guest (x86)
+ "PV": paravirtualized guest (x86)
+ "PVH": fully virtualized guest without legacy emulation (x86)
+
+What: /sys/hypervisor/pmu/pmu_mode
+Date: August 2015
+KernelVersion: 4.3
+Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com>
+Description: If running under Xen:
+ Describes mode that Xen's performance-monitoring unit (PMU)
+ uses. Accepted values are:
+
+ ====== ============================================
+ "off" PMU is disabled
+ "self" The guest can profile itself
+ "hv" The guest can profile itself and, if it is
+ privileged (e.g. dom0), the hypervisor
+ "all" The guest can profile itself, the hypervisor
+ and all other guests. Only available to
+ privileged guests.
+ ====== ============================================
+
+What: /sys/hypervisor/pmu/pmu_features
+Date: August 2015
+KernelVersion: 4.3
+Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com>
+Description: If running under Xen:
+ Describes Xen PMU features (as an integer). A set bit indicates
+ that the corresponding feature is enabled. See
+ include/xen/interface/xenpmu.h for available features
+
+What: /sys/hypervisor/properties/buildid
+Date: June 2017
+KernelVersion: 4.13
+Contact: xen-devel@lists.xenproject.org
+Description: If running under Xen:
+ Build id of the hypervisor, needed for hypervisor live patching.
+ Might return "<denied>" in case of special security settings
+ in the hypervisor.
diff --git a/Documentation/ABI/testing/sysfs-i2c-bmp085 b/Documentation/ABI/testing/sysfs-i2c-bmp085
deleted file mode 100644
index 585962ad0465..000000000000
--- a/Documentation/ABI/testing/sysfs-i2c-bmp085
+++ /dev/null
@@ -1,31 +0,0 @@
-What: /sys/bus/i2c/devices/<busnum>-<devaddr>/pressure0_input
-Date: June 2010
-Contact: Christoph Mair <christoph.mair@gmail.com>
-Description: Start a pressure measurement and read the result. Values
- represent the ambient air pressure in pascal (0.01 millibar).
-
- Reading: returns the current air pressure.
-
-
-What: /sys/bus/i2c/devices/<busnum>-<devaddr>/temp0_input
-Date: June 2010
-Contact: Christoph Mair <christoph.mair@gmail.com>
-Description: Measure the ambient temperature. The returned value represents
- the ambient temperature in units of 0.1 degree celsius.
-
- Reading: returns the current temperature.
-
-
-What: /sys/bus/i2c/devices/<busnum>-<devaddr>/oversampling
-Date: June 2010
-Contact: Christoph Mair <christoph.mair@gmail.com>
-Description: Tell the bmp085 to use more samples to calculate a pressure
- value. When writing to this file the chip will use 2^x samples
- to calculate the next pressure value with x being the value
- written. Using this feature will decrease RMS noise and
- increase the measurement time.
-
- Reading: returns the current oversampling setting.
-
- Writing: sets a new oversampling setting.
- Accepted values: 0..3.
diff --git a/Documentation/ABI/testing/sysfs-ibft b/Documentation/ABI/testing/sysfs-ibft
index cac3930bdb04..7d6725fe6143 100644
--- a/Documentation/ABI/testing/sysfs-ibft
+++ b/Documentation/ABI/testing/sysfs-ibft
@@ -21,3 +21,13 @@ Contact: Konrad Rzeszutek <ketuzsezr@darnok.org>
Description: The /sys/firmware/ibft/ethernetX directory will contain
files that expose the iSCSI Boot Firmware Table NIC data.
Usually this contains the IP address, MAC, and gateway of the NIC.
+
+What: /sys/firmware/ibft/acpi_header
+Date: March 2016
+Contact: David Bond <dbond@suse.com>
+Description: The /sys/firmware/ibft/acpi_header directory will contain files
+ that expose the SIGNATURE, OEM_ID, and OEM_TABLE_ID fields of the
+ acpi table header of the iBFT structure. This will allow for
+ identification of the creator of the table which is useful in
+ determining quirks associated with some adapters when used in
+ hardware vs software iscsi initiator mode.
diff --git a/Documentation/ABI/testing/sysfs-kernel-address_bits b/Documentation/ABI/testing/sysfs-kernel-address_bits
new file mode 100644
index 000000000000..3b72e48086aa
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-address_bits
@@ -0,0 +1,10 @@
+What: /sys/kernel/address_bits
+Date: May 2023
+KernelVersion: 6.3
+Contact: Thomas Weißschuh <linux@weissschuh.net>
+Description:
+ The address size of the running kernel in bits.
+
+ Access: Read
+
+Users: util-linux
diff --git a/Documentation/ABI/testing/sysfs-kernel-boot_params b/Documentation/ABI/testing/sysfs-kernel-boot_params
index eca38ce2852d..7f9bda453c4d 100644
--- a/Documentation/ABI/testing/sysfs-kernel-boot_params
+++ b/Documentation/ABI/testing/sysfs-kernel-boot_params
@@ -23,16 +23,17 @@ Description: The /sys/kernel/boot_params directory contains two
representation of setup_data type. "data" file is the binary
representation of setup_data payload.
- The whole boot_params directory structure is like below:
- /sys/kernel/boot_params
- |__ data
- |__ setup_data
- | |__ 0
- | | |__ data
- | | |__ type
- | |__ 1
- | |__ data
- | |__ type
- |__ version
+ The whole boot_params directory structure is like below::
+
+ /sys/kernel/boot_params
+ |__ data
+ |__ setup_data
+ | |__ 0
+ | | |__ data
+ | | |__ type
+ | |__ 1
+ | |__ data
+ | |__ type
+ |__ version
Users: Kexec
diff --git a/Documentation/ABI/testing/sysfs-kernel-btf b/Documentation/ABI/testing/sysfs-kernel-btf
new file mode 100644
index 000000000000..fe96efdc9b6c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-btf
@@ -0,0 +1,25 @@
+What: /sys/kernel/btf
+Date: Aug 2019
+KernelVersion: 5.5
+Contact: bpf@vger.kernel.org
+Description:
+ Contains BTF type information and related data for kernel and
+ kernel modules.
+
+What: /sys/kernel/btf/vmlinux
+Date: Aug 2019
+KernelVersion: 5.5
+Contact: bpf@vger.kernel.org
+Description:
+ Read-only binary attribute exposing kernel's own BTF type
+ information with description of all internal kernel types. See
+ Documentation/bpf/btf.rst for detailed description of format
+ itself.
+
+What: /sys/kernel/btf/<module-name>
+Date: Nov 2020
+KernelVersion: 5.11
+Contact: bpf@vger.kernel.org
+Description:
+ Read-only binary attribute exposing kernel module's BTF type
+ information as an add-on to the kernel's BTF (/sys/kernel/btf/vmlinux).
diff --git a/Documentation/ABI/testing/sysfs-kernel-cpu_byteorder b/Documentation/ABI/testing/sysfs-kernel-cpu_byteorder
new file mode 100644
index 000000000000..f0e6ac1b5356
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-cpu_byteorder
@@ -0,0 +1,12 @@
+What: /sys/kernel/cpu_byteorder
+Date: February 2023
+KernelVersion: 6.2
+Contact: Thomas Weißschuh <linux@weissschuh.net>
+Description:
+ The endianness of the running kernel.
+
+ Access: Read
+
+ Valid values:
+ "little", "big"
+Users: util-linux
diff --git a/Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers b/Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers
new file mode 100644
index 000000000000..5d3bc997dc64
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-dmabuf-buffers
@@ -0,0 +1,24 @@
+What: /sys/kernel/dmabuf/buffers
+Date: May 2021
+KernelVersion: v5.13
+Contact: Hridya Valsaraju <hridya@google.com>
+Description: The /sys/kernel/dmabuf/buffers directory contains a
+ snapshot of the internal state of every DMA-BUF.
+ /sys/kernel/dmabuf/buffers/<inode_number> will contain the
+ statistics for the DMA-BUF with the unique inode number
+ <inode_number>
+Users: kernel memory tuning/debugging tools
+
+What: /sys/kernel/dmabuf/buffers/<inode_number>/exporter_name
+Date: May 2021
+KernelVersion: v5.13
+Contact: Hridya Valsaraju <hridya@google.com>
+Description: This file is read-only and contains the name of the exporter of
+ the DMA-BUF.
+
+What: /sys/kernel/dmabuf/buffers/<inode_number>/size
+Date: May 2021
+KernelVersion: v5.13
+Contact: Hridya Valsaraju <hridya@google.com>
+Description: This file is read-only and specifies the size of the DMA-BUF in
+ bytes.
diff --git a/Documentation/ABI/testing/sysfs-kernel-fadump b/Documentation/ABI/testing/sysfs-kernel-fadump
new file mode 100644
index 000000000000..b64b7622e6fc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-fadump
@@ -0,0 +1,59 @@
+What: /sys/kernel/fadump/*
+Date: Dec 2019
+Contact: linuxppc-dev@lists.ozlabs.org
+Description:
+ The /sys/kernel/fadump/* is a collection of FADump sysfs
+ file provide information about the configuration status
+ of Firmware Assisted Dump (FADump).
+
+What: /sys/kernel/fadump/enabled
+Date: Dec 2019
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Primarily used to identify whether the FADump is enabled in
+ the kernel or not.
+User: Kdump service
+
+What: /sys/kernel/fadump/registered
+Date: Dec 2019
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ Helps to control the dump collect feature from userspace.
+ Setting 1 to this file enables the system to collect the
+ dump and 0 to disable it.
+User: Kdump service
+
+What: /sys/kernel/fadump/release_mem
+Date: Dec 2019
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: write only
+ This is a special sysfs file and only available when
+ the system is booted to capture the vmcore using FADump.
+ It is used to release the memory reserved by FADump to
+ save the crash dump.
+
+What: /sys/kernel/fadump/mem_reserved
+Date: Dec 2019
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Provide information about the amount of memory reserved by
+ FADump to save the crash dump in bytes.
+
+What: /sys/kernel/fadump/hotplug_ready
+Date: Apr 2024
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read only
+ Kdump udev rule re-registers fadump on memory add/remove events,
+ primarily to update the elfcorehdr. This sysfs indicates the
+ kdump udev rule that fadump re-registration is not required on
+ memory add/remove events because elfcorehdr is now prepared in
+ the second/fadump kernel.
+User: kexec-tools
+
+What: /sys/kernel/fadump/bootargs_append
+Date: May 2024
+Contact: linuxppc-dev@lists.ozlabs.org
+Description: read/write
+ This is a special sysfs file available to setup additional
+ parameters to be passed to capture kernel. For HASH MMU it
+ is exported only if RMA size higher than 768MB.
diff --git a/Documentation/ABI/testing/sysfs-kernel-fscaps b/Documentation/ABI/testing/sysfs-kernel-fscaps
index 50a3033b5e15..bcff34665192 100644
--- a/Documentation/ABI/testing/sysfs-kernel-fscaps
+++ b/Documentation/ABI/testing/sysfs-kernel-fscaps
@@ -2,7 +2,7 @@ What: /sys/kernel/fscaps
Date: February 2011
KernelVersion: 2.6.38
Contact: Ludwig Nussel <ludwig.nussel@suse.de>
-Description
+Description:
Shows whether file system capabilities are honored
when executing a binary
diff --git a/Documentation/ABI/testing/sysfs-kernel-hardlockup_count b/Documentation/ABI/testing/sysfs-kernel-hardlockup_count
new file mode 100644
index 000000000000..dfdd4078b077
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-hardlockup_count
@@ -0,0 +1,7 @@
+What: /sys/kernel/hardlockup_count
+Date: May 2025
+KernelVersion: 6.16
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ Shows how many times the system has detected a hard lockup since last boot.
+ Available only if CONFIG_HARDLOCKUP_DETECTOR is enabled.
diff --git a/Documentation/ABI/testing/sysfs-kernel-iommu_groups b/Documentation/ABI/testing/sysfs-kernel-iommu_groups
index 9b31556cfdda..a42d4383d999 100644
--- a/Documentation/ABI/testing/sysfs-kernel-iommu_groups
+++ b/Documentation/ABI/testing/sysfs-kernel-iommu_groups
@@ -12,3 +12,53 @@ Description: /sys/kernel/iommu_groups/ contains a number of sub-
file if the IOMMU driver has chosen to register a more
common name for the group.
Users:
+
+What: /sys/kernel/iommu_groups/reserved_regions
+Date: January 2017
+KernelVersion: v4.11
+Contact: Eric Auger <eric.auger@redhat.com>
+Description: /sys/kernel/iommu_groups/reserved_regions list IOVA
+ regions that are reserved. Not necessarily all
+ reserved regions are listed. This is typically used to
+ output direct-mapped, MSI, non mappable regions. Each
+ region is described on a single line: the 1st field is
+ the base IOVA, the second is the end IOVA and the third
+ field describes the type of the region.
+
+ Since kernel 5.3, in case an RMRR is used only by graphics or
+ USB devices it is now exposed as "direct-relaxable" instead
+ of "direct". In device assignment use case, for instance,
+ those RMRR are considered to be relaxable and safe.
+
+What: /sys/kernel/iommu_groups/<grp_id>/type
+Date: November 2020
+KernelVersion: v5.11
+Contact: Sai Praneeth Prakhya <sai.praneeth.prakhya@intel.com>
+Description: /sys/kernel/iommu_groups/<grp_id>/type shows the type of default
+ domain in use by iommu for this group. See include/linux/iommu.h
+ for possible read values. A privileged user could request kernel to
+ change the group type by writing to this file. Valid write values:
+
+ ======== ======================================================
+ DMA All the DMA transactions from the device in this group
+ are translated by the iommu.
+ DMA-FQ As above, but using batched invalidation to lazily
+ remove translations after use. This may offer reduced
+ overhead at the cost of reduced memory protection.
+ identity All the DMA transactions from the device in this group
+ are not translated by the iommu. Maximum performance
+ but zero protection.
+ auto Change to the type the device was booted with.
+ ======== ======================================================
+
+ The default domain type of a group may be modified only when
+
+ - The device in the group is not bound to any device driver.
+ So, the users must unbind the appropriate driver before
+ changing the default domain type.
+
+ Unbinding a device driver will take away the driver's control
+ over the device and if done on devices that host root file
+ system could lead to catastrophic effects (the users might
+ need to reboot the machine to get it to normal state). So, it's
+ expected that the users understand what they're doing.
diff --git a/Documentation/ABI/testing/sysfs-kernel-irq b/Documentation/ABI/testing/sysfs-kernel-irq
new file mode 100644
index 000000000000..8910d0c4bcd8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-irq
@@ -0,0 +1,60 @@
+What: /sys/kernel/irq
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: Directory containing information about the system's IRQs.
+ Specifically, data from the associated struct irq_desc.
+ The information here is similar to that in /proc/interrupts
+ but in a more machine-friendly format. This directory contains
+ one subdirectory for each Linux IRQ number.
+
+What: /sys/kernel/irq/<irq>/actions
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: The IRQ action chain. A comma-separated list of zero or more
+ device names associated with this interrupt.
+
+What: /sys/kernel/irq/<irq>/chip_name
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: Human-readable chip name supplied by the associated device
+ driver.
+
+What: /sys/kernel/irq/<irq>/hwirq
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: When interrupt translation domains are used, this file contains
+ the underlying hardware IRQ number used for this Linux IRQ.
+
+What: /sys/kernel/irq/<irq>/name
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: Human-readable flow handler name as defined by the irq chip
+ driver.
+
+What: /sys/kernel/irq/<irq>/per_cpu_count
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: The number of times the interrupt has fired since boot. This
+ is a comma-separated list of counters; one per CPU in CPU id
+ order. NOTE: This file consistently shows counters for all
+ CPU ids. This differs from the behavior of /proc/interrupts
+ which only shows counters for online CPUs.
+
+What: /sys/kernel/irq/<irq>/type
+Date: September 2016
+KernelVersion: 4.9
+Contact: Craig Gallek <kraig@google.com>
+Description: The type of the interrupt. Either the string 'level' or 'edge'.
+
+What: /sys/kernel/irq/<irq>/wakeup
+Date: March 2018
+KernelVersion: 4.17
+Contact: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
+Description: The wakeup state of the interrupt. Either the string
+ 'enabled' or 'disabled'.
diff --git a/Documentation/ABI/testing/sysfs-kernel-kexec-kdump b/Documentation/ABI/testing/sysfs-kernel-kexec-kdump
new file mode 100644
index 000000000000..f59051b5d96d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-kexec-kdump
@@ -0,0 +1,61 @@
+What: /sys/kernel/kexec/*
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description:
+ The /sys/kernel/kexec/* directory contains sysfs files
+ that provide information about the configuration status
+ of kexec and kdump.
+
+What: /sys/kernel/kexec/loaded
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description: read only
+ Indicates whether a new kernel image has been loaded
+ into memory using the kexec system call. It shows 1 if
+ a kexec image is present and ready to boot, or 0 if none
+ is loaded.
+User: kexec tools, kdump service
+
+What: /sys/kernel/kexec/crash_loaded
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description: read only
+ Indicates whether a crash (kdump) kernel is currently
+ loaded into memory. It shows 1 if a crash kernel has been
+ successfully loaded for panic handling, or 0 if no crash
+ kernel is present.
+User: Kexec tools, Kdump service
+
+What: /sys/kernel/kexec/crash_size
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description: read/write
+ Shows the amount of memory reserved for loading the crash
+ (kdump) kernel. It reports the size, in bytes, of the
+ crash kernel area defined by the crashkernel= parameter.
+ This interface also allows reducing the crashkernel
+ reservation by writing a smaller value, and the reclaimed
+ space is added back to the system RAM.
+User: Kdump service
+
+What: /sys/kernel/kexec/crash_elfcorehdr_size
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description: read only
+ Indicates the preferred size of the memory buffer for the
+ ELF core header used by the crash (kdump) kernel. It defines
+ how much space is needed to hold metadata about the crashed
+ system, including CPU and memory information. This information
+ is used by the user space utility kexec to support updating the
+ in-kernel kdump image during hotplug operations.
+User: Kexec tools
+
+What: /sys/kernel/kexec/crash_cma_ranges
+Date: Nov 2025
+Contact: kexec@lists.infradead.org
+Description: read only
+ Provides information about the memory ranges reserved from
+ the Contiguous Memory Allocator (CMA) area that are allocated
+ to the crash (kdump) kernel. It lists the start and end physical
+ addresses of CMA regions assigned for crashkernel use.
+User: kdump service
diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch
index 5bf42a840b22..3c3f36b32b57 100644
--- a/Documentation/ABI/testing/sysfs-kernel-livepatch
+++ b/Documentation/ABI/testing/sysfs-kernel-livepatch
@@ -25,6 +25,45 @@ Description:
code is currently applied. Writing 0 will disable the patch
while writing 1 will re-enable the patch.
+What: /sys/kernel/livepatch/<patch>/transition
+Date: Feb 2017
+KernelVersion: 4.12.0
+Contact: live-patching@vger.kernel.org
+Description:
+ An attribute which indicates whether the patch is currently in
+ transition.
+
+What: /sys/kernel/livepatch/<patch>/force
+Date: Nov 2017
+KernelVersion: 4.15.0
+Contact: live-patching@vger.kernel.org
+Description:
+ A writable attribute that allows administrator to affect the
+ course of an existing transition. Writing 1 clears
+ TIF_PATCH_PENDING flag of all tasks and thus forces the tasks to
+ the patched or unpatched state. Administrator should not
+ use this feature without a clearance from a patch
+ distributor. Removal (rmmod) of patch modules is permanently
+ disabled when the feature is used. See
+ Documentation/livepatch/livepatch.rst for more information.
+
+What: /sys/kernel/livepatch/<patch>/replace
+Date: Jun 2024
+KernelVersion: 6.11.0
+Contact: live-patching@vger.kernel.org
+Description:
+ An attribute which indicates whether the patch supports
+ atomic-replace.
+
+What: /sys/kernel/livepatch/<patch>/stack_order
+Date: Jan 2025
+KernelVersion: 6.14.0
+Description:
+ This attribute specifies the sequence in which live patch modules
+ are applied to the system. If multiple live patches modify the same
+ function, the implementation with the biggest 'stack_order' number
+ is used, unless a transition is currently in progress.
+
What: /sys/kernel/livepatch/<patch>/<object>
Date: Nov 2014
KernelVersion: 3.19.0
@@ -33,7 +72,15 @@ Description:
The object directory contains subdirectories for each function
that is patched within the object.
-What: /sys/kernel/livepatch/<patch>/<object>/<function>
+What: /sys/kernel/livepatch/<patch>/<object>/patched
+Date: August 2022
+KernelVersion: 6.1.0
+Contact: live-patching@vger.kernel.org
+Description:
+ An attribute which indicates whether the object is currently
+ patched.
+
+What: /sys/kernel/livepatch/<patch>/<object>/<function,sympos>
Date: Nov 2014
KernelVersion: 3.19.0
Contact: live-patching@vger.kernel.org
@@ -41,4 +88,8 @@ Description:
The function directory contains attributes regarding the
properties and state of the patched function.
+ The directory name contains the patched function name and a
+ sympos number corresponding to the nth occurrence of the symbol
+ name in kallsyms for the patched object.
+
There are currently no such attributes.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-cma b/Documentation/ABI/testing/sysfs-kernel-mm-cma
new file mode 100644
index 000000000000..aaf2a5d8b13b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-cma
@@ -0,0 +1,44 @@
+What: /sys/kernel/mm/cma/
+Date: Feb 2021
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ /sys/kernel/mm/cma/ contains a subdirectory for each CMA
+ heap name (also sometimes called CMA areas).
+
+ Each CMA heap subdirectory (that is, each
+ /sys/kernel/mm/cma/<cma-heap-name> directory) contains the
+ following items:
+
+ alloc_pages_success
+ alloc_pages_fail
+
+What: /sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_success
+Date: Feb 2021
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ the number of pages CMA API succeeded to allocate
+
+What: /sys/kernel/mm/cma/<cma-heap-name>/alloc_pages_fail
+Date: Feb 2021
+Contact: Minchan Kim <minchan@kernel.org>
+Description:
+ the number of pages CMA API failed to allocate
+
+What: /sys/kernel/mm/cma/<cma-heap-name>/release_pages_success
+Date: Feb 2024
+Contact: Anshuman Khandual <anshuman.khandual@arm.com>
+Description:
+ the number of pages CMA API succeeded to release
+
+What: /sys/kernel/mm/cma/<cma-heap-name>/total_pages
+Date: Jun 2024
+Contact: Frank van der Linden <fvdl@google.com>
+Description:
+ The size of the CMA area in pages.
+
+What: /sys/kernel/mm/cma/<cma-heap-name>/available_pages
+Date: Jun 2024
+Contact: Frank van der Linden <fvdl@google.com>
+Description:
+ The number of pages in the CMA area that are still
+ available for CMA allocation.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon
new file mode 100644
index 000000000000..4fb8b7a6d625
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon
@@ -0,0 +1,559 @@
+what: /sys/kernel/mm/damon/
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Interface for Data Access MONitoring (DAMON). Contains files
+ for controlling DAMON. For more details on DAMON itself,
+ please refer to Documentation/admin-guide/mm/damon/index.rst.
+
+What: /sys/kernel/mm/damon/admin/
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Interface for privileged users of DAMON. Contains files for
+ controlling DAMON that aimed to be used by privileged users.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/nr_kdamonds
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for controlling each DAMON worker thread (kdamond)
+ named '0' to 'N-1' under the kdamonds/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/state
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing 'on' or 'off' to this file makes the kdamond starts or
+ stops, respectively. Reading the file returns the keywords
+ based on the current status. Writing 'commit' to this file
+ makes the kdamond reads the user inputs in the sysfs files
+ except 'state' again. Writing 'commit_schemes_quota_goals' to
+ this file makes the kdamond reads the quota goal files again.
+ Writing 'update_schemes_stats' to the file updates contents of
+ schemes stats files of the kdamond. Writing
+ 'update_schemes_tried_regions' to the file updates contents of
+ 'tried_regions' directory of every scheme directory of this
+ kdamond. Writing 'update_schemes_tried_bytes' to the file
+ updates only '.../tried_regions/total_bytes' files of this
+ kdamond. Writing 'clear_schemes_tried_regions' to the file
+ removes contents of the 'tried_regions' directory. Writing
+ 'update_schemes_effective_quotas' to the file updates
+ '.../quotas/effective_bytes' files of this kdamond.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/pid
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the pid of the kdamond if it is
+ running.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/refresh_ms
+Date: Jul 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the time interval for
+ automatic DAMON status file contents update. Writing '0'
+ disables the update. Reading this file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/nr_contexts
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for controlling each DAMON context named '0' to
+ 'N-1' under the contexts/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/avail_operations
+Date: Apr 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the available monitoring operations
+ sets on the currently running kernel.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/operations
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a keyword for a monitoring operations set ('vaddr' for
+ virtual address spaces monitoring, 'fvaddr' for fixed virtual
+ address ranges monitoring, and 'paddr' for the physical address
+ space monitoring) to this file makes the context to use the
+ operations set. Reading the file returns the keyword for the
+ operations set the context is set to use.
+
+ Note that only the operations sets that listed in
+ 'avail_operations' file are valid inputs.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/addr_unit
+Date: Aug 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing an integer to this file sets the 'address unit'
+ parameter of the given operations set of the context. Reading
+ the file returns the last-written 'address unit' value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/sample_us
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the sampling interval of the
+ DAMON context in microseconds as the value. Reading this file
+ returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/aggr_us
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the aggregation interval of
+ the DAMON context in microseconds as the value. Reading this
+ file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/update_us
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the update interval of the
+ DAMON context in microseconds as the value. Reading this file
+ returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/access_bp
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the monitoring intervals
+ auto-tuning target DAMON-observed access events ratio within
+ the given time interval (aggrs in same directory), in bp
+ (1/10,000). Reading this file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/aggrs
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the time interval to achieve
+ the monitoring intervals auto-tuning target DAMON-observed
+ access events ratio (access_bp in same directory) within.
+ Reading this file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/min_sample_us
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the minimum value of
+ auto-tuned sampling interval in microseconds. Reading this
+ file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/max_sample_us
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the maximum value of
+ auto-tuned sampling interval in microseconds. Reading this
+ file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min
+
+WDate: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the minimum number of
+ monitoring regions of the DAMON context as the value. Reading
+ this file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/max
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the maximum number of
+ monitoring regions of the DAMON context as the value. Reading
+ this file returns the value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/nr_targets
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for controlling each DAMON target of the context
+ named '0' to 'N-1' under the contexts/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/pid_target
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the pid of
+ the target process if the context is for virtual address spaces
+ monitoring, respectively.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/obsolete_target
+Date: Oct 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the
+ obsoleteness of the matching parameters commit destination
+ target.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/nr_regions
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for setting each DAMON target memory region of the
+ context named '0' to 'N-1' under the regions/ directory. In
+ case of the virtual address space monitoring, DAMON
+ automatically sets the target memory region based on the target
+ processes' mappings.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/start
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the start
+ address of the monitoring region.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/end
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the end
+ address of the monitoring region.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/nr_schemes
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for controlling each DAMON-based operation scheme
+ of the context named '0' to 'N-1' under the schemes/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/action
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the action
+ of the scheme.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/target_nid
+Date: Jun 2024
+Contact: SeongJae Park <sj@kernel.org>
+Description: Action's target NUMA node id. Supported by only relevant
+ actions.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/apply_interval_us
+Date: Sep 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a value to this file sets the action apply interval of
+ the scheme in microseconds. Reading this file returns the
+ value.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the minimum
+ size of the scheme's target regions in bytes.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the maximum
+ size of the scheme's target regions in bytes.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/min
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the manimum
+ 'nr_accesses' of the scheme's target regions.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/max
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the maximum
+ 'nr_accesses' of the scheme's target regions.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/min
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the minimum
+ 'age' of the scheme's target regions.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/max
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the maximum
+ 'age' of the scheme's target regions.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/ms
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the time
+ quota of the scheme in milliseconds.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/bytes
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the size
+ quota of the scheme in bytes.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/effective_bytes
+Date: Feb 2024
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading from this file gets the effective size quota of the
+ scheme in bytes, which adjusted for the time quota and goals.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/reset_interval_ms
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the quotas
+ charge reset interval of the scheme in milliseconds.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/nr_goals
+Date: Nov 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for setting automatic tuning of the scheme's
+ aggressiveness named '0' to 'N-1' under the goals/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/target_metric
+Date: Feb 2024
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the quota
+ auto-tuning goal metric.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/target_value
+Date: Nov 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the target
+ value of the goal metric.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/current_value
+Date: Nov 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the current
+ value of the goal metric.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/nid
+Date: Apr 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the nid
+ parameter of the goal.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/goals/<G>/path
+Date: Oct 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the path
+ parameter of the goal.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_permil
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the
+ under-quota limit regions prioritization weight for 'size' in
+ permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/nr_accesses_permil
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the
+ under-quota limit regions prioritization weight for
+ 'nr_accesses' in permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/age_permil
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the
+ under-quota limit regions prioritization weight for 'age' in
+ permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/metric
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the metric
+ of the watermarks for the scheme. The writable/readable
+ keywords for this file are 'none' for disabling the watermarks
+ feature, or 'free_mem_rate' for the system's global free memory
+ rate in permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/interval_us
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the metric
+ check interval of the watermarks for the scheme in
+ microseconds.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/high
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the high
+ watermark of the scheme in permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/mid
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the mid
+ watermark of the scheme in permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/low
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the low
+ watermark of the scheme in permil.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/nr_filters
+Date: Dec 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for setting filters of the scheme named '0' to
+ 'N-1' under the filters/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/type
+Date: Dec 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the type of
+ the memory of the interest. 'anon' for anonymous pages,
+ 'memcg' for specific memory cgroup, 'young' for young pages,
+ 'addr' for address range (an open-ended interval), or 'target'
+ for DAMON monitoring target can be written and read.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/memcg_path
+Date: Dec 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: If 'memcg' is written to the 'type' file, writing to and
+ reading from this file sets and gets the path to the memory
+ cgroup of the interest.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_start
+Date: Jul 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: If 'addr' is written to the 'type' file, writing to or reading
+ from this file sets or gets the start address of the address
+ range for the filter.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_end
+Date: Jul 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: If 'addr' is written to the 'type' file, writing to or reading
+ from this file sets or gets the end address of the address
+ range for the filter.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/min
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: If 'hugepage_size' is written to the 'type' file, writing to
+ or reading from this file sets or gets the minimum size of the
+ hugepage for the filter.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/max
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: If 'hugepage_size' is written to the 'type' file, writing to
+ or reading from this file sets or gets the maximum size of the
+ hugepage for the filter.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/target_idx
+Date: Dec 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: If 'target' is written to the 'type' file, writing to or
+ reading from this file sets or gets the index of the DAMON
+ monitoring target of the interest.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/matching
+Date: Dec 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing 'Y' or 'N' to this file sets whether the filter is for
+ the memory of the 'type', or all except the 'type'.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/allow
+Date: Jan 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing 'Y' or 'N' to this file sets whether to allow or reject
+ applying the scheme's action to the memory that satisfies the
+ 'type' and the 'matching' of the directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Directory for DAMON core layer-handled DAMOS filters. Files
+ under this directory works same to those of
+ /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/ops_filters
+Date: Feb 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Directory for DAMON operations set layer-handled DAMOS filters.
+ Files under this directory works same to those of
+ /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/dests/nr_dests
+Date: Jul 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing a number 'N' to this file creates the number of
+ directories for setting action destinations of the scheme named
+ '0' to 'N-1' under the dests/ directory.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/dests/<D>/id
+Date: Jul 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the id of
+ the DAMOS action destination. For DAMOS_MIGRATE_{HOT,COLD}
+ actions, the destination node's node id can be written and
+ read.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/dests/<D>/weight
+Date: Jul 2025
+Contact: SeongJae Park <sj@kernel.org>
+Description: Writing to and reading from this file sets and gets the weight
+ of the DAMOS action destination to select as the destination of
+ each action among the destinations.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the number of regions that the action
+ of the scheme has tried to be applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_tried
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the total size of regions that the
+ action of the scheme has tried to be applied in bytes.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_applied
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the number of regions that the action
+ of the scheme has successfully applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_applied
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the total size of regions that the
+ action of the scheme has successfully applied in bytes.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_ops_filter_passed
+Date: Dec 2024
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the total size of memory that passed
+ DAMON operations layer-handled filters of the scheme in bytes.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/qt_exceeds
+Date: Mar 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the number of the exceed events of
+ the scheme's quotas.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/total_bytes
+Date: Jul 2023
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the total amount of memory that
+ corresponding DAMON-based Operation Scheme's action has tried
+ to be applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/start
+Date: Oct 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the start address of a memory region
+ that corresponding DAMON-based Operation Scheme's action has
+ tried to be applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/end
+Date: Oct 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the end address of a memory region
+ that corresponding DAMON-based Operation Scheme's action has
+ tried to be applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/nr_accesses
+Date: Oct 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the 'nr_accesses' of a memory region
+ that corresponding DAMON-based Operation Scheme's action has
+ tried to be applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/age
+Date: Oct 2022
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the 'age' of a memory region that
+ corresponding DAMON-based Operation Scheme's action has tried
+ to be applied.
+
+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/sz_filter_passed
+Date: Dec 2024
+Contact: SeongJae Park <sj@kernel.org>
+Description: Reading this file returns the size of the memory in the region
+ that passed DAMON operations layer-handled filters of the
+ scheme in bytes.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
index e21c00571cf4..294387e2c7fb 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
@@ -7,9 +7,11 @@ Description:
of the hugepages supported by the kernel/CPU combination.
Under these directories are a number of files:
- nr_hugepages
- nr_overcommit_hugepages
- free_hugepages
- surplus_hugepages
- resv_hugepages
- See Documentation/vm/hugetlbpage.txt for details.
+
+ - nr_hugepages
+ - nr_overcommit_hugepages
+ - free_hugepages
+ - surplus_hugepages
+ - resv_hugepages
+
+ See Documentation/admin-guide/mm/hugetlbpage.rst for details.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-ksm b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
index 73e653ee2481..6041a025b65a 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-ksm
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
@@ -34,13 +34,14 @@ Description: Kernel Samepage Merging daemon sysfs interface
in a tree.
run: write 0 to disable ksm, read 0 while ksm is disabled.
- write 1 to run ksm, read 1 while ksm is running.
- write 2 to disable ksm and unmerge all its pages.
+
+ - write 1 to run ksm, read 1 while ksm is running.
+ - write 2 to disable ksm and unmerge all its pages.
sleep_millisecs: how many milliseconds ksm should sleep between
scans.
- See Documentation/vm/ksm.txt for more information.
+ See Documentation/mm/ksm.rst for more information.
What: /sys/kernel/mm/ksm/merge_across_nodes
Date: January 2013
@@ -50,3 +51,11 @@ Description: Control merging pages across different NUMA nodes.
When it is set to 0 only pages from the same node are merged,
otherwise pages from all nodes can be merged together (default).
+
+What: /sys/kernel/mm/ksm/general_profit
+Date: April 2023
+KernelVersion: 6.4
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Measure how effective KSM is.
+ general_profit: how effective is KSM. The formula for the
+ calculation is in Documentation/admin-guide/mm/ksm.rst.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-memory-tiers b/Documentation/ABI/testing/sysfs-kernel-mm-memory-tiers
new file mode 100644
index 000000000000..721a05b90109
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-memory-tiers
@@ -0,0 +1,25 @@
+What: /sys/devices/virtual/memory_tiering/
+Date: August 2022
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: A collection of all the memory tiers allocated.
+
+ Individual memory tier details are contained in subdirectories
+ named by the abstract distance of the memory tier.
+
+ /sys/devices/virtual/memory_tiering/memory_tierN/
+
+
+What: /sys/devices/virtual/memory_tiering/memory_tierN/
+ /sys/devices/virtual/memory_tiering/memory_tierN/nodelist
+Date: August 2022
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Directory with details of a specific memory tier
+
+ This is the directory containing information about a particular
+ memory tier, memtierN, where N is derived based on abstract distance.
+
+ A smaller value of N implies a higher (faster) memory tier in the
+ hierarchy.
+
+ nodelist: NUMA nodes that are part of this memory tier.
+
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy
new file mode 100644
index 000000000000..8ac327fd7fb6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy
@@ -0,0 +1,4 @@
+What: /sys/kernel/mm/mempolicy/
+Date: January 2024
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Interface for Mempolicy
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave
new file mode 100644
index 000000000000..649c0e9b895c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave
@@ -0,0 +1,54 @@
+What: /sys/kernel/mm/mempolicy/weighted_interleave/
+Date: January 2024
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Configuration Interface for the Weighted Interleave policy
+
+What: /sys/kernel/mm/mempolicy/weighted_interleave/nodeN
+Date: January 2024
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Weight configuration interface for nodeN
+
+ The interleave weight for a memory node (N). These weights are
+ utilized by tasks which have set their mempolicy to
+ MPOL_WEIGHTED_INTERLEAVE.
+
+ These weights only affect new allocations, and changes at runtime
+ will not cause migrations on already allocated pages.
+
+ The minimum weight for a node is always 1.
+
+ Minimum weight: 1
+ Maximum weight: 255
+
+ Writing invalid values (i.e. any values not in [1,255],
+ empty string, ...) will return -EINVAL.
+
+ Changing the weight to a valid value will automatically
+ switch the system to manual mode as well.
+
+What: /sys/kernel/mm/mempolicy/weighted_interleave/auto
+Date: May 2025
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Auto-weighting configuration interface
+
+ Configuration mode for weighted interleave. 'true' indicates
+ that the system is in auto mode, and a 'false' indicates that
+ the system is in manual mode.
+
+ In auto mode, all node weights are re-calculated and overwritten
+ (visible via the nodeN interfaces) whenever new bandwidth data
+ is made available during either boot or hotplug events.
+
+ In manual mode, node weights can only be updated by the user.
+ Note that nodes that are onlined with previously set weights
+ will reuse those weights. If they were not previously set or
+ are onlined with missing bandwidth data, the weights will use
+ a default weight of 1.
+
+ Writing any true value string (e.g. Y or 1) will enable auto
+ mode, while writing any false value string (e.g. N or 0) will
+ enable manual mode. All other strings are ignored and will
+ return -EINVAL.
+
+ Writing a new weight to a node directly via the nodeN interface
+ will also automatically switch the system to manual mode.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-numa b/Documentation/ABI/testing/sysfs-kernel-mm-numa
new file mode 100644
index 000000000000..90e375ff54cb
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-numa
@@ -0,0 +1,28 @@
+What: /sys/kernel/mm/numa/
+Date: June 2021
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Interface for NUMA
+
+What: /sys/kernel/mm/numa/demotion_enabled
+Date: June 2021
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Enable/disable demoting pages during reclaim
+
+ Page migration during reclaim is intended for systems
+ with tiered memory configurations. These systems have
+ multiple types of memory with varied performance
+ characteristics instead of plain NUMA systems where
+ the same kind of memory is found at varied distances.
+ Allowing page migration during reclaim enables these
+ systems to migrate pages from fast tiers to slow tiers
+ when the fast tier is under pressure. This migration
+ is performed before swap if an eligible numa node is
+ present in cpuset.mems for the cgroup (or if cpuset v1
+ is being used). If cpusets.mems changes at runtime, it
+ may move data to a NUMA node that does not fall into the
+ cpuset of the new cpusets.mems, which might be construed
+ to violate the guarantees of cpusets. Shared memory,
+ such as libraries, owned by another cgroup may still be
+ demoted and result in memory use on a node not present
+ in cpusets.mem. This should not be enabled on systems
+ which need strict cpuset location guarantees.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-swap b/Documentation/ABI/testing/sysfs-kernel-mm-swap
new file mode 100644
index 000000000000..94672016c268
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-swap
@@ -0,0 +1,16 @@
+What: /sys/kernel/mm/swap/
+Date: August 2017
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Interface for swapping
+
+What: /sys/kernel/mm/swap/vma_ra_enabled
+Date: August 2017
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description: Enable/disable VMA based swap readahead.
+
+ If set to true, the VMA based swap readahead algorithm
+ will be used for swappable anonymous pages mapped in a
+ VMA, and the global swap readahead algorithm will be
+ still used for tmpfs etc. other users. If set to
+ false, the global swap readahead algorithm will be
+ used for all swappable pages.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage b/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
new file mode 100644
index 000000000000..7bfbb9cc2c11
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
@@ -0,0 +1,18 @@
+What: /sys/kernel/mm/transparent_hugepage/
+Date: April 2024
+Contact: Linux memory management mailing list <linux-mm@kvack.org>
+Description:
+ /sys/kernel/mm/transparent_hugepage/ contains a number of files and
+ subdirectories,
+
+ - defrag
+ - enabled
+ - hpage_pmd_size
+ - khugepaged
+ - shmem_enabled
+ - use_zero_page
+ - subdirectories of the form hugepages-<size>kB, where <size>
+ is the page size of the hugepages supported by the kernel/CPU
+ combination.
+
+ See Documentation/admin-guide/mm/transhuge.rst for details.
diff --git a/Documentation/ABI/testing/sysfs-kernel-oops_count b/Documentation/ABI/testing/sysfs-kernel-oops_count
new file mode 100644
index 000000000000..156cca9dbc96
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-oops_count
@@ -0,0 +1,6 @@
+What: /sys/kernel/oops_count
+Date: November 2022
+KernelVersion: 6.2.0
+Contact: Linux Kernel Hardening List <linux-hardening@vger.kernel.org>
+Description:
+ Shows how many times the system has Oopsed since last boot.
diff --git a/Documentation/ABI/testing/sysfs-kernel-rcu_stall_count b/Documentation/ABI/testing/sysfs-kernel-rcu_stall_count
new file mode 100644
index 000000000000..a4a97a7f4a4d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-rcu_stall_count
@@ -0,0 +1,6 @@
+What: /sys/kernel/rcu_stall_count
+Date: May 2025
+KernelVersion: 6.16
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ Shows how many times the system has detected an RCU stall since last boot.
diff --git a/Documentation/ABI/testing/sysfs-kernel-reboot b/Documentation/ABI/testing/sysfs-kernel-reboot
new file mode 100644
index 000000000000..52571fd5ddba
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-reboot
@@ -0,0 +1,40 @@
+What: /sys/kernel/reboot
+Date: November 2020
+KernelVersion: 5.11
+Contact: Matteo Croce <teknoraver@meta.com>
+Description: Interface to set the kernel reboot behavior, similarly to
+ what can be done via the reboot= cmdline option.
+ (see Documentation/admin-guide/kernel-parameters.txt)
+
+What: /sys/kernel/reboot/mode
+Date: November 2020
+KernelVersion: 5.11
+Contact: Matteo Croce <teknoraver@meta.com>
+Description: Reboot mode. Valid values are: cold warm hard soft gpio
+
+What: /sys/kernel/reboot/type
+Date: November 2020
+KernelVersion: 5.11
+Contact: Matteo Croce <teknoraver@meta.com>
+Description: Reboot type. Valid values are: bios acpi kbd triple efi pci
+
+What: /sys/kernel/reboot/cpu
+Date: November 2020
+KernelVersion: 5.11
+Contact: Matteo Croce <teknoraver@meta.com>
+Description: CPU number to use to reboot.
+
+What: /sys/kernel/reboot/force
+Date: November 2020
+KernelVersion: 5.11
+Contact: Matteo Croce <teknoraver@meta.com>
+Description: Don't wait for any other CPUs on reboot and
+ avoid anything that could hang.
+
+What: /sys/kernel/reboot/hw_protection
+Date: April 2025
+KernelVersion: 6.15
+Contact: Ahmad Fatoum <a.fatoum@pengutronix.de>
+Description: Hardware protection action taken on critical events like
+ overtemperature or imminent voltage loss.
+ Valid values are: reboot shutdown
diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab
index 91bd6ca5440f..b26e4299f822 100644
--- a/Documentation/ABI/testing/sysfs-kernel-slab
+++ b/Documentation/ABI/testing/sysfs-kernel-slab
@@ -2,7 +2,7 @@ What: /sys/kernel/slab
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The /sys/kernel/slab directory contains a snapshot of the
internal state of the SLUB allocator for each cache. Certain
@@ -10,51 +10,52 @@ Description:
any cache it aliases, if any).
Users: kernel memory tuning tools
-What: /sys/kernel/slab/cache/aliases
+What: /sys/kernel/slab/<cache>/aliases
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The aliases file is read-only and specifies how many caches
have merged into this cache.
-What: /sys/kernel/slab/cache/align
+What: /sys/kernel/slab/<cache>/align
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The align file is read-only and specifies the cache's object
alignment in bytes.
-What: /sys/kernel/slab/cache/alloc_calls
+What: /sys/kernel/slab/<cache>/alloc_calls
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The alloc_calls file is read-only and lists the kernel code
locations from which allocations for this cache were performed.
The alloc_calls file only contains information if debugging is
- enabled for that cache (see Documentation/vm/slub.txt).
+ enabled for that cache (see
+ Documentation/admin-guide/mm/slab.rst).
-What: /sys/kernel/slab/cache/alloc_fastpath
+What: /sys/kernel/slab/<cache>/alloc_fastpath
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The alloc_fastpath file shows how many objects have been
allocated using the fast path. It can be written to clear the
current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/alloc_from_partial
+What: /sys/kernel/slab/<cache>/alloc_from_partial
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The alloc_from_partial file shows how many times a cpu slab has
been full and it has been refilled by using a slab from the list
@@ -62,33 +63,33 @@ Description:
count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/alloc_refill
+What: /sys/kernel/slab/<cache>/alloc_refill
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The alloc_refill file shows how many times the per-cpu freelist
was empty but there were objects available as the result of
remote cpu frees. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/alloc_slab
+What: /sys/kernel/slab/<cache>/alloc_slab
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The alloc_slab file is shows how many times a new slab had to
be allocated from the page allocator. It can be written to
clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/alloc_slowpath
+What: /sys/kernel/slab/<cache>/alloc_slowpath
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The alloc_slowpath file shows how many objects have been
allocated using the slow path because of a refill or
@@ -96,30 +97,30 @@ Description:
clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/cache_dma
+What: /sys/kernel/slab/<cache>/cache_dma
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The cache_dma file is read-only and specifies whether objects
are from ZONE_DMA.
Available when CONFIG_ZONE_DMA is enabled.
-What: /sys/kernel/slab/cache/cpu_slabs
+What: /sys/kernel/slab/<cache>/cpu_slabs
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The cpu_slabs file is read-only and displays how many cpu slabs
are active and their NUMA locality.
-What: /sys/kernel/slab/cache/cpuslab_flush
+What: /sys/kernel/slab/<cache>/cpuslab_flush
Date: April 2009
KernelVersion: 2.6.31
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The file cpuslab_flush shows how many times a cache's cpu slabs
have been flushed as the result of destroying or shrinking a
@@ -128,126 +129,126 @@ Description:
current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/ctor
+What: /sys/kernel/slab/<cache>/ctor
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The ctor file is read-only and specifies the cache's object
constructor function, which is invoked for each object when a
new slab is allocated.
-What: /sys/kernel/slab/cache/deactivate_empty
+What: /sys/kernel/slab/<cache>/deactivate_empty
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The deactivate_empty file shows how many times an empty cpu slab
was deactivated. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/deactivate_full
+What: /sys/kernel/slab/<cache>/deactivate_full
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The deactivate_full file shows how many times a full cpu slab
was deactivated. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/deactivate_remote_frees
+What: /sys/kernel/slab/<cache>/deactivate_remote_frees
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The deactivate_remote_frees file shows how many times a cpu slab
has been deactivated and contained free objects that were freed
remotely. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/deactivate_to_head
+What: /sys/kernel/slab/<cache>/deactivate_to_head
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The deactivate_to_head file shows how many times a partial cpu
slab was deactivated and added to the head of its node's partial
list. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/deactivate_to_tail
+What: /sys/kernel/slab/<cache>/deactivate_to_tail
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The deactivate_to_tail file shows how many times a partial cpu
slab was deactivated and added to the tail of its node's partial
list. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/destroy_by_rcu
+What: /sys/kernel/slab/<cache>/destroy_by_rcu
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The destroy_by_rcu file is read-only and specifies whether
slabs (not objects) are freed by rcu.
-What: /sys/kernel/slab/cache/free_add_partial
+What: /sys/kernel/slab/<cache>/free_add_partial
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_add_partial file shows how many times an object has
been freed in a full slab so that it had to added to its node's
partial list. It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/free_calls
+What: /sys/kernel/slab/<cache>/free_calls
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_calls file is read-only and lists the locations of
object frees if slab debugging is enabled (see
- Documentation/vm/slub.txt).
+ Documentation/admin-guide/mm/slab.rst).
-What: /sys/kernel/slab/cache/free_fastpath
+What: /sys/kernel/slab/<cache>/free_fastpath
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_fastpath file shows how many objects have been freed
using the fast path because it was an object from the cpu slab.
It can be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/free_frozen
+What: /sys/kernel/slab/<cache>/free_frozen
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_frozen file shows how many objects have been freed to
a frozen slab (i.e. a remote cpu slab). It can be written to
clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/free_remove_partial
+What: /sys/kernel/slab/<cache>/free_remove_partial
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_remove_partial file shows how many times an object has
been freed to a now-empty slab so that it had to be removed from
@@ -255,38 +256,38 @@ Description:
count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/free_slab
+What: /sys/kernel/slab/<cache>/free_slab
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_slab file shows how many times an empty slab has been
freed back to the page allocator. It can be written to clear
the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/free_slowpath
+What: /sys/kernel/slab/<cache>/free_slowpath
Date: February 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The free_slowpath file shows how many objects have been freed
using the slow path (i.e. to a full or partial slab). It can
be written to clear the current count.
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/hwcache_align
+What: /sys/kernel/slab/<cache>/hwcache_align
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The hwcache_align file is read-only and specifies whether
objects are aligned on cachelines.
-What: /sys/kernel/slab/cache/min_partial
+What: /sys/kernel/slab/<cache>/min_partial
Date: February 2009
KernelVersion: 2.6.30
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
@@ -297,194 +298,223 @@ Description:
allocating new slabs. Such slabs may be reclaimed by utilizing
the shrink file.
-What: /sys/kernel/slab/cache/object_size
+What: /sys/kernel/slab/<cache>/object_size
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The object_size file is read-only and specifies the cache's
object size.
-What: /sys/kernel/slab/cache/objects
+What: /sys/kernel/slab/<cache>/objects
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The objects file is read-only and displays how many objects are
active and from which nodes they are from.
-What: /sys/kernel/slab/cache/objects_partial
+What: /sys/kernel/slab/<cache>/objects_partial
Date: April 2008
KernelVersion: 2.6.26
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The objects_partial file is read-only and displays how many
objects are on partial slabs and from which nodes they are
from.
-What: /sys/kernel/slab/cache/objs_per_slab
+What: /sys/kernel/slab/<cache>/objs_per_slab
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The file objs_per_slab is read-only and specifies how many
objects may be allocated from a single slab of the order
- specified in /sys/kernel/slab/cache/order.
+ specified in /sys/kernel/slab/<cache>/order.
-What: /sys/kernel/slab/cache/order
+What: /sys/kernel/slab/<cache>/order
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The order file specifies the page order at which new slabs are
allocated. It is writable and can be changed to increase the
number of objects per slab. If a slab cannot be allocated
because of fragmentation, SLUB will retry with the minimum order
possible depending on its characteristics.
+
When debug_guardpage_minorder=N (N > 0) parameter is specified
- (see Documentation/kernel-parameters.txt), the minimum possible
+ (see Documentation/admin-guide/kernel-parameters.rst), the minimum possible
order is used and this sysfs entry can not be used to change
the order at run time.
-What: /sys/kernel/slab/cache/order_fallback
+What: /sys/kernel/slab/<cache>/order_fallback
Date: April 2008
KernelVersion: 2.6.26
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The order_fallback file shows how many times an allocation of a
new slab has not been possible at the cache's order and instead
fallen back to its minimum possible order. It can be written to
clear the current count.
+
Available when CONFIG_SLUB_STATS is enabled.
-What: /sys/kernel/slab/cache/partial
+What: /sys/kernel/slab/<cache>/partial
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The partial file is read-only and displays how long many
partial slabs there are and how long each node's list is.
-What: /sys/kernel/slab/cache/poison
+What: /sys/kernel/slab/<cache>/poison
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The poison file specifies whether objects should be poisoned
when a new slab is allocated.
-What: /sys/kernel/slab/cache/reclaim_account
+What: /sys/kernel/slab/<cache>/reclaim_account
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The reclaim_account file specifies whether the cache's objects
are reclaimable (and grouped by their mobility).
-What: /sys/kernel/slab/cache/red_zone
+What: /sys/kernel/slab/<cache>/red_zone
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The red_zone file specifies whether the cache's objects are red
zoned.
-What: /sys/kernel/slab/cache/remote_node_defrag_ratio
+What: /sys/kernel/slab/<cache>/remote_node_defrag_ratio
Date: January 2008
KernelVersion: 2.6.25
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The file remote_node_defrag_ratio specifies the percentage of
times SLUB will attempt to refill the cpu slab with a partial
slab from a remote node as opposed to allocating a new slab on
the local node. This reduces the amount of wasted memory over
the entire system but can be expensive.
+
Available when CONFIG_NUMA is enabled.
-What: /sys/kernel/slab/cache/sanity_checks
+What: /sys/kernel/slab/<cache>/sanity_checks
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The sanity_checks file specifies whether expensive checks
should be performed on free and, at minimum, enables double free
checks. Caches that enable sanity_checks cannot be merged with
caches that do not.
-What: /sys/kernel/slab/cache/shrink
+What: /sys/kernel/slab/<cache>/shrink
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
- The shrink file is written when memory should be reclaimed from
- a cache. Empty partial slabs are freed and the partial list is
- sorted so the slabs with the fewest available objects are used
- first.
+ The shrink file is used to reclaim unused slab cache
+ memory from a cache. Empty per-cpu or partial slabs
+ are freed and the partial list is sorted so the slabs
+ with the fewest available objects are used first.
+ It only accepts a value of "1" on write for shrinking
+ the cache. Other input values are considered invalid.
+ Shrinking slab caches might be expensive and can
+ adversely impact other running applications. So it
+ should be used with care.
-What: /sys/kernel/slab/cache/slab_size
+What: /sys/kernel/slab/<cache>/slab_size
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The slab_size file is read-only and specifies the object size
with metadata (debugging information and alignment) in bytes.
-What: /sys/kernel/slab/cache/slabs
+What: /sys/kernel/slab/<cache>/slabs
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The slabs file is read-only and displays how long many slabs
there are (both cpu and partial) and from which nodes they are
from.
-What: /sys/kernel/slab/cache/store_user
+What: /sys/kernel/slab/<cache>/store_user
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The store_user file specifies whether the location of
allocation or free should be tracked for a cache.
-What: /sys/kernel/slab/cache/total_objects
+What: /sys/kernel/slab/<cache>/total_objects
Date: April 2008
KernelVersion: 2.6.26
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The total_objects file is read-only and displays how many total
objects a cache has and from which nodes they are from.
-What: /sys/kernel/slab/cache/trace
+What: /sys/kernel/slab/<cache>/trace
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
The trace file specifies whether object allocations and frees
should be traced.
-What: /sys/kernel/slab/cache/validate
+What: /sys/kernel/slab/<cache>/validate
Date: May 2007
KernelVersion: 2.6.22
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
- Christoph Lameter <cl@linux-foundation.org>
+ Christoph Lameter <cl@gentwo.org>
Description:
Writing to the validate file causes SLUB to traverse all of its
cache's objects and check the validity of metadata.
+
+What: /sys/kernel/slab/<cache>/usersize
+Date: Jun 2017
+Contact: David Windsor <dave@nullcore.net>
+Description:
+ The usersize file is read-only and contains the usercopy
+ region size.
+
+What: /sys/kernel/slab/<cache>/slabs_cpu_partial
+Date: Aug 2011
+Contact: Christoph Lameter <cl@gentwo.org>
+Description:
+ This read-only file shows the number of partialli allocated
+ frozen slabs.
+
+What: /sys/kernel/slab/<cache>/cpu_partial
+Date: Aug 2011
+Contact: Christoph Lameter <cl@gentwo.org>
+Description:
+ This read-only file shows the number of per cpu partial
+ pages to keep around.
diff --git a/Documentation/ABI/testing/sysfs-kernel-softlockup_count b/Documentation/ABI/testing/sysfs-kernel-softlockup_count
new file mode 100644
index 000000000000..337ff5531b5f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-softlockup_count
@@ -0,0 +1,7 @@
+What: /sys/kernel/softlockup_count
+Date: May 2025
+KernelVersion: 6.16
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ Shows how many times the system has detected a soft lockup since last boot.
+ Available only if CONFIG_SOFTLOCKUP_DETECTOR is enabled.
diff --git a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
index 7bd81168e063..1f1087a5f075 100644
--- a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
+++ b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
@@ -4,7 +4,7 @@ KernelVersion: 2.6.24
Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
Kexec Mailing List <kexec@lists.infradead.org>
Vivek Goyal <vgoyal@redhat.com>
-Description
+Description:
Shows physical address and size of vmcoreinfo ELF note.
First value contains physical address of note in hex and
second value contains the size of note in hex. This ELF
diff --git a/Documentation/ABI/testing/sysfs-kernel-warn_count b/Documentation/ABI/testing/sysfs-kernel-warn_count
new file mode 100644
index 000000000000..90a029813717
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-kernel-warn_count
@@ -0,0 +1,6 @@
+What: /sys/kernel/warn_count
+Date: November 2022
+KernelVersion: 6.2.0
+Contact: Linux Kernel Hardening List <linux-hardening@vger.kernel.org>
+Description:
+ Shows how many times the system has Warned since last boot.
diff --git a/Documentation/ABI/testing/sysfs-mce b/Documentation/ABI/testing/sysfs-mce
new file mode 100644
index 000000000000..83172f50e27c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-mce
@@ -0,0 +1,97 @@
+What: /sys/devices/system/machinecheck/machinecheckX/
+Contact: Andi Kleen <ak@linux.intel.com>
+Date: Feb, 2007
+Description:
+ (X = CPU number)
+
+ Machine checks report internal hardware error conditions
+ detected by the CPU. Uncorrected errors typically cause a
+ machine check (often with panic), corrected ones cause a
+ machine check log entry.
+
+ For more details about the x86 machine check architecture
+ see the Intel and AMD architecture manuals from their
+ developer websites.
+
+ For more details about the architecture
+ see http://one.firstfloor.org/~andi/mce.pdf
+
+ Each CPU has its own directory.
+
+What: /sys/devices/system/machinecheck/machinecheckX/bank<Y>
+Contact: Andi Kleen <ak@linux.intel.com>
+Date: Feb, 2007
+Description:
+ (Y bank number)
+
+ 64bit Hex bitmask enabling/disabling specific subevents for
+ bank Y.
+
+ When a bit in the bitmask is zero then the respective
+ subevent will not be reported.
+
+ By default all events are enabled.
+
+ Note that BIOS maintain another mask to disable specific events
+ per bank. This is not visible here
+
+What: /sys/devices/system/machinecheck/machinecheckX/check_interval
+Contact: Andi Kleen <ak@linux.intel.com>
+Date: Feb, 2007
+Description:
+ The entries appear for each CPU, but they are truly shared
+ between all CPUs.
+
+ How often to poll for corrected machine check errors, in
+ seconds (Note output is hexadecimal). Default 5 minutes.
+ When the poller finds MCEs it triggers an exponential speedup
+ (poll more often) on the polling interval. When the poller
+ stops finding MCEs, it triggers an exponential backoff
+ (poll less often) on the polling interval. The check_interval
+ variable is both the initial and maximum polling interval.
+ 0 means no polling for corrected machine check errors
+ (but some corrected errors might be still reported
+ in other ways)
+
+What: /sys/devices/system/machinecheck/machinecheckX/trigger
+Contact: Andi Kleen <ak@linux.intel.com>
+Date: Feb, 2007
+Description:
+ The entries appear for each CPU, but they are truly shared
+ between all CPUs.
+
+ Program to run when a machine check event is detected.
+ This is an alternative to running mcelog regularly from cron
+ and allows to detect events faster.
+
+What: /sys/devices/system/machinecheck/machinecheckX/monarch_timeout
+Contact: Andi Kleen <ak@linux.intel.com>
+Date: Feb, 2007
+Description:
+ How long to wait for the other CPUs to machine check too on a
+ exception. 0 to disable waiting for other CPUs.
+
+ Unit: us
+
+What: /sys/devices/system/machinecheck/machinecheckX/ignore_ce
+Contact: Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com>
+Date: Jun 2009
+Description:
+ Disables polling and CMCI for corrected errors.
+ All corrected events are not cleared and kept in bank MSRs.
+
+What: /sys/devices/system/machinecheck/machinecheckX/dont_log_ce
+Contact: Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com>
+Date: Jun 2009
+Description:
+ Disables logging for corrected errors.
+ All reported corrected errors will be cleared silently.
+
+ This option will be useful if you never care about corrected
+ errors.
+
+What: /sys/devices/system/machinecheck/machinecheckX/cmci_disabled
+Contact: Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com>
+Date: Jun 2009
+Description:
+ Disables the CMCI feature.
diff --git a/Documentation/ABI/testing/sysfs-memory-page-offline b/Documentation/ABI/testing/sysfs-memory-page-offline
index e14703f12fdf..00f4e35f916f 100644
--- a/Documentation/ABI/testing/sysfs-memory-page-offline
+++ b/Documentation/ABI/testing/sysfs-memory-page-offline
@@ -10,7 +10,7 @@ Description:
dropping it if possible. The kernel will then be placed
on the bad page list and never be reused.
- The offlining is done in kernel specific granuality.
+ The offlining is done in kernel specific granularity.
Normally it's the base page size of the kernel, but
this might change.
@@ -35,7 +35,7 @@ Description:
to access this page assuming it's poisoned by the
hardware.
- The offlining is done in kernel specific granuality.
+ The offlining is done in kernel specific granularity.
Normally it's the base page size of the kernel, but
this might change.
diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module
index 0aac02e7fb0e..6bc9af6229f0 100644
--- a/Documentation/ABI/testing/sysfs-module
+++ b/Documentation/ABI/testing/sysfs-module
@@ -17,14 +17,15 @@ KernelVersion: 3.1
Contact: Kirill Smelkov <kirr@mns.spb.ru>
Description: Maximum time allowed for periodic transfers per microframe (μs)
- [ USB 2.0 sets maximum allowed time for periodic transfers per
+ Note:
+ USB 2.0 sets maximum allowed time for periodic transfers per
microframe to be 80%, that is 100 microseconds out of 125
microseconds (full microframe).
However there are cases, when 80% max isochronous bandwidth is
too limiting. For example two video streams could require 110
microseconds of isochronous bandwidth per microframe to work
- together. ]
+ together.
Through this setting it is possible to raise the limit so that
the host controller would allow allocating more than 100
@@ -36,17 +37,39 @@ Description: Maximum time allowed for periodic transfers per microframe (μs)
What: /sys/module/*/{coresize,initsize}
Date: Jan 2012
-KernelVersion:»·3.3
+KernelVersion: 3.3
Contact: Kay Sievers <kay.sievers@vrfy.org>
Description: Module size in bytes.
+What: /sys/module/*/initstate
+Date: Nov 2006
+KernelVersion: 2.6.19
+Contact: Kay Sievers <kay.sievers@vrfy.org>
+Description: Show the initialization state(live, coming, going) of
+ the module.
+
What: /sys/module/*/taint
Date: Jan 2012
-KernelVersion:»·3.3
+KernelVersion: 3.3
Contact: Kay Sievers <kay.sievers@vrfy.org>
Description: Module taint flags:
- P - proprietary module
- O - out-of-tree module
- F - force-loaded module
- C - staging driver module
- E - unsigned module
+ == =====================
+ P proprietary module
+ O out-of-tree module
+ F force-loaded module
+ C staging driver module
+ E unsigned module
+ K livepatch module
+ N in-kernel test module
+ == =====================
+
+What: /sys/module/grant_table/parameters/free_per_iteration
+Date: July 2023
+KernelVersion: 6.5 but backported to all supported stable branches
+Contact: Xen developer discussion <xen-devel@lists.xenproject.org>
+Description: Read and write number of grant entries to attempt to free per iteration.
+
+ Note: Future versions of Xen and Linux may provide a better
+ interface for controlling the rate of deferred grant reclaim
+ or may not need it at all.
+Users: Qubes OS (https://www.qubes-os.org)
diff --git a/Documentation/ABI/testing/sysfs-nvmem-cells b/Documentation/ABI/testing/sysfs-nvmem-cells
new file mode 100644
index 000000000000..c7c9444f92a8
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-nvmem-cells
@@ -0,0 +1,21 @@
+What: /sys/bus/nvmem/devices/.../cells/<cell-name>
+Date: May 2023
+KernelVersion: 6.5
+Contact: Miquel Raynal <miquel.raynal@bootlin.com>
+Description:
+ The "cells" folder contains one file per cell exposed by the
+ NVMEM device. The name of the file is: "<name>@<byte>,<bit>",
+ with <name> being the cell name and <where> its location in
+ the NVMEM device, in hexadecimal bytes and bits (without the
+ '0x' prefix, to mimic device tree node names). The length of
+ the file is the size of the cell (when known). The content of
+ the file is the binary content of the cell (may sometimes be
+ ASCII, likely without trailing character).
+ Note: This file is only present if CONFIG_NVMEM_SYSFS
+ is enabled.
+
+ Example::
+
+ hexdump -C /sys/bus/nvmem/devices/1-00563/cells/product-name@d,0
+ 00000000 54 4e 34 38 4d 2d 50 2d 44 4e |TN48M-P-DN|
+ 0000000a
diff --git a/Documentation/ABI/testing/sysfs-ocfs2 b/Documentation/ABI/testing/sysfs-ocfs2
index b7cc516a8a8a..494d7c1ac710 100644
--- a/Documentation/ABI/testing/sysfs-ocfs2
+++ b/Documentation/ABI/testing/sysfs-ocfs2
@@ -1,13 +1,13 @@
What: /sys/fs/ocfs2/
Date: April 2008
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description:
The /sys/fs/ocfs2 directory contains knobs used by the
ocfs2-tools to interact with the filesystem.
What: /sys/fs/ocfs2/max_locking_protocol
Date: April 2008
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description:
The /sys/fs/ocfs2/max_locking_protocol file displays version
of ocfs2 locking supported by the filesystem. This version
@@ -28,7 +28,7 @@ Description:
What: /sys/fs/ocfs2/loaded_cluster_plugins
Date: April 2008
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description:
The /sys/fs/ocfs2/loaded_cluster_plugins file describes
the available plugins to support ocfs2 cluster operation.
@@ -48,7 +48,7 @@ Description:
What: /sys/fs/ocfs2/active_cluster_plugin
Date: April 2008
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description:
The /sys/fs/ocfs2/active_cluster_plugin displays which
cluster plugin is currently in use by the filesystem.
@@ -65,7 +65,7 @@ Description:
What: /sys/fs/ocfs2/cluster_stack
Date: April 2008
-Contact: ocfs2-devel@oss.oracle.com
+Contact: ocfs2-devel@lists.linux.dev
Description:
The /sys/fs/ocfs2/cluster_stack file contains the name
of current ocfs2 cluster stack. This value is set by
@@ -86,4 +86,4 @@ Description:
stack return an error.
Users:
- ocfs2-tools <ocfs2-tools-devel@oss.oracle.com>
+ ocfs2-tools <ocfs2-tools-devel@lists.linux.dev>
diff --git a/Documentation/ABI/testing/sysfs-platform-alienware-wmi b/Documentation/ABI/testing/sysfs-platform-alienware-wmi
new file mode 100644
index 000000000000..4877b3745f4e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-alienware-wmi
@@ -0,0 +1,14 @@
+What: /sys/class/hwmon/hwmonX/fanY_boost
+Date: March 2025
+KernelVersion: 6.15
+Contact: Kurt Borja <kuurtb@gmail.com>
+Description:
+ This file exposes fan boost control for Dell gaming laptops with
+ the AWCC WMI interface.
+
+ See Documentation/admin-guide/laptops/alienware-wmi.rst for
+ details.
+
+ Integer value in the range 0 to 255
+
+ RW
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
index cd9d667c3da2..c78d358dbdbe 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -4,13 +4,16 @@ KernelVersion: 2.6.20
Contact: "Corentin Chary" <corentincj@iksaif.net>
Description:
This file allows display switching. The value
- is composed by 4 bits and defined as follow:
- 4321
- |||`- LCD
- ||`-- CRT
- |`--- TV
- `---- DVI
- Ex: - 0 (0000b) means no display
+ is composed by 4 bits and defined as follow::
+
+ 4321
+ |||`- LCD
+ ||`-- CRT
+ |`--- TV
+ `---- DVI
+
+ Ex:
+ - 0 (0000b) means no display
- 3 (0011b) CRT+LCD.
What: /sys/devices/platform/asus_laptop/gps
@@ -28,10 +31,12 @@ Contact: "Corentin Chary" <corentincj@iksaif.net>
Description:
Some models like the W1N have a LED display that can be
used to display several items of information.
- To control the LED display, use the following :
+ To control the LED display, use the following::
+
echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
+
where T control the 3 letters display, and DDD the 3 digits display.
- The DDD table can be found in Documentation/laptops/asus-laptop.txt
+ The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
What: /sys/devices/platform/asus_laptop/bluetooth
Date: January 2007
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi
index 019e1e29370e..89acb6638df8 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-wmi
+++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi
@@ -5,6 +5,7 @@ Contact: "Corentin Chary" <corentincj@iksaif.net>
Description:
Change CPU clock configuration (write-only).
There are three available clock configuration:
+
* 0 -> Super Performance Mode
* 1 -> High Performance Mode
* 2 -> Power Saving Mode
@@ -36,3 +37,195 @@ KernelVersion: 3.5
Contact: "AceLan Kao" <acelan.kao@canonical.com>
Description:
Resume on lid open. 1 means on, 0 means off.
+
+What: /sys/devices/platform/<platform>/fan_boost_mode
+Date: Sep 2019
+KernelVersion: 5.3
+Contact: "Yurii Pavlovskyi" <yurii.pavlovskyi@gmail.com>
+Description:
+ Fan boost mode:
+ * 0 - normal,
+ * 1 - overboost,
+ * 2 - silent
+
+What: /sys/devices/platform/<platform>/throttle_thermal_policy
+Date: Dec 2019
+KernelVersion: 5.6
+Contact: "Leonid Maksymchuk" <leonmaxx@gmail.com>
+Description:
+ Throttle thermal policy mode:
+ * 0 - default,
+ * 1 - overboost,
+ * 2 - silent
+
+What: /sys/devices/platform/<platform>/gpu_mux_mode
+Date: Aug 2022
+KernelVersion: 6.1
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Switch the GPU hardware MUX mode. Laptops with this feature can
+ can be toggled to boot with only the dGPU (discrete mode) or in
+ standard Optimus/Hybrid mode. On switch a reboot is required:
+
+ * 0 - Discrete GPU,
+ * 1 - Optimus/Hybrid,
+
+What: /sys/devices/platform/<platform>/dgpu_disable
+Date: Aug 2022
+KernelVersion: 5.17
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Disable discrete GPU:
+ * 0 - Enable dGPU,
+ * 1 - Disable dGPU
+
+What: /sys/devices/platform/<platform>/egpu_enable
+Date: Aug 2022
+KernelVersion: 5.17
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Enable the external GPU paired with ROG X-Flow laptops.
+ Toggling this setting will also trigger ACPI to disable the dGPU:
+
+ * 0 - Disable,
+ * 1 - Enable
+
+What: /sys/devices/platform/<platform>/panel_od
+Date: Aug 2022
+KernelVersion: 5.17
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Enable an LCD response-time boost to reduce or remove ghosting:
+ * 0 - Disable,
+ * 1 - Enable
+
+What: /sys/devices/platform/<platform>/charge_mode
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Get the current charging mode being used:
+ * 1 - Barrel connected charger,
+ * 2 - USB-C charging
+ * 3 - Both connected, barrel used for charging
+
+What: /sys/devices/platform/<platform>/egpu_connected
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Show if the egpu (XG Mobile) is correctly connected:
+ * 0 - False,
+ * 1 - True
+
+What: /sys/devices/platform/<platform>/mini_led_mode
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Change the mini-LED mode:
+ * 0 - Single-zone,
+ * 1 - Multi-zone
+ * 2 - Multi-zone strong (available on newer generation mini-led)
+
+What: /sys/devices/platform/<platform>/available_mini_led_mode
+Date: Apr 2024
+KernelVersion: 6.10
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ List the available mini-led modes.
+
+What: /sys/devices/platform/<platform>/ppt_pl1_spl
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the Package Power Target total of CPU: PL1 on Intel, SPL on AMD.
+ Shown on Intel+Nvidia or AMD+Nvidia based systems:
+
+ * min=5, max=250
+
+What: /sys/devices/platform/<platform>/ppt_pl2_sppt
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the Slow Package Power Tracking Limit of CPU: PL2 on Intel, SPPT,
+ on AMD. Shown on Intel+Nvidia or AMD+Nvidia based systems:
+
+ * min=5, max=250
+
+What: /sys/devices/platform/<platform>/ppt_fppt
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the Fast Package Power Tracking Limit of CPU. AMD+Nvidia only:
+ * min=5, max=250
+
+What: /sys/devices/platform/<platform>/ppt_apu_sppt
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the APU SPPT limit. Shown on full AMD systems only:
+ * min=5, max=130
+
+What: /sys/devices/platform/<platform>/ppt_platform_sppt
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the platform SPPT limit. Shown on full AMD systems only:
+ * min=5, max=130
+
+What: /sys/devices/platform/<platform>/nv_dynamic_boost
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the dynamic boost limit of the Nvidia dGPU:
+ * min=5, max=25
+
+What: /sys/devices/platform/<platform>/nv_temp_target
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set the target temperature limit of the Nvidia dGPU:
+ * min=75, max=87
+
+What: /sys/devices/platform/<platform>/boot_sound
+Date: Apr 2024
+KernelVersion: 6.10
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set if the BIOS POST sound is played on boot.
+ * 0 - False,
+ * 1 - True
+
+What: /sys/devices/platform/<platform>/mcu_powersave
+Date: Apr 2024
+KernelVersion: 6.10
+Contact: "Luke Jones" <luke@ljones.dev>
+Description:
+ DEPRECATED, WILL BE REMOVED SOON: please use asus-armoury
+ Set if the MCU can go in to low-power mode on system sleep
+ * 0 - False,
+ * 1 - True
diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91
index 4cc6a865ae66..b146be74b8e0 100644
--- a/Documentation/ABI/testing/sysfs-platform-at91
+++ b/Documentation/ABI/testing/sysfs-platform-at91
@@ -18,8 +18,10 @@ Description:
In order to use an extended can_id add the
CAN_EFF_FLAG (0x80000000U) to the can_id. Example:
- - standard id 0x7ff:
- echo 0x7ff > /sys/class/net/can0/mb0_id
+ - standard id 0x7ff::
- - extended id 0x1fffffff:
- echo 0x9fffffff > /sys/class/net/can0/mb0_id
+ echo 0x7ff > /sys/class/net/can0/mb0_id
+
+ - extended id 0x1fffffff::
+
+ echo 0x9fffffff > /sys/class/net/can0/mb0_id
diff --git a/Documentation/ABI/testing/sysfs-platform-ayaneo-ec b/Documentation/ABI/testing/sysfs-platform-ayaneo-ec
new file mode 100644
index 000000000000..4cffbf5fc7ca
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-ayaneo-ec
@@ -0,0 +1,19 @@
+What: /sys/devices/platform/ayaneo-ec/controller_power
+Date: Nov 2025
+KernelVersion: 6.19
+Contact: "Antheas Kapenekakis" <lkml@antheas.dev>
+Description:
+ Current controller power state. Allows turning on and off
+ the controller power (e.g. for power savings). Write 1 to
+ turn on, 0 to turn off. File is readable and writable.
+
+What: /sys/devices/platform/ayaneo-ec/controller_modules
+Date: Nov 2025
+KernelVersion: 6.19
+Contact: "Antheas Kapenekakis" <lkml@antheas.dev>
+Description:
+ Shows which controller modules are currently connected to
+ the device. Possible values are "left", "right" and "both".
+ File is read-only. The Windows software for this device
+ will only set controller power to 1 if both module sides
+ are connected (i.e. this file returns "both").
diff --git a/Documentation/ABI/testing/sysfs-platform-brcmstb-memc b/Documentation/ABI/testing/sysfs-platform-brcmstb-memc
new file mode 100644
index 000000000000..2f2b750ac2fd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-brcmstb-memc
@@ -0,0 +1,15 @@
+What: /sys/bus/platform/devices/*/srpd
+Date: July 2022
+KernelVersion: 5.21
+Contact: Florian Fainelli <f.fainelli@gmail.com>
+Description:
+ Self Refresh Power Down (SRPD) inactivity timeout counted in
+ internal DDR controller clock cycles. Possible values range
+ from 0 (disable inactivity timeout) to 65535 (0xffff).
+
+What: /sys/bus/platform/devices/*/frequency
+Date: July 2022
+KernelVersion: 5.21
+Contact: Florian Fainelli <f.fainelli@gmail.com>
+Description:
+ DDR PHY frequency in Hz.
diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
index 151c59578db4..f58cfb06b160 100644
--- a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
+++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
@@ -1,6 +1,6 @@
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Can be set and read.
Set a_bus_req(A-device bus request) input to be 1 if
@@ -17,7 +17,7 @@ Description:
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Can be set and read
The a_bus_drop(A-device bus drop) input is 1 when the
@@ -32,7 +32,7 @@ Description:
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Can be set and read.
The b_bus_req(B-device bus request) input is 1 during the time
@@ -47,7 +47,7 @@ Description:
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_clr_err
Date: Feb 2014
-Contact: Li Jun <b47624@freescale.com>
+Contact: Li Jun <jun.li@nxp.com>
Description:
Only can be set.
The a_clr_err(A-device Vbus error clear) input is used to clear
diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 b/Documentation/ABI/testing/sysfs-platform-chipidea-usb2
new file mode 100644
index 000000000000..b9f7d924f28a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb2
@@ -0,0 +1,9 @@
+What: /sys/bus/platform/devices/ci_hdrc.0/role
+Date: Mar 2017
+Contact: Peter Chen <peter.chen@nxp.com>
+Description:
+ When read, it returns string "gadget" or "host", indicating
+ the current controller role.
+
+ It will do role switch when "gadget" or "host" is written to it.
+ Only controller at dual-role configuration supports writing.
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-laptop b/Documentation/ABI/testing/sysfs-platform-dell-laptop
index 8c6a0b8e1131..701529653283 100644
--- a/Documentation/ABI/testing/sysfs-platform-dell-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-dell-laptop
@@ -2,7 +2,7 @@ What: /sys/class/leds/dell::kbd_backlight/als_enabled
Date: December 2014
KernelVersion: 3.19
Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>,
- Pali Rohár <pali.rohar@gmail.com>
+ Pali Rohár <pali@kernel.org>
Description:
This file allows to control the automatic keyboard
illumination mode on some systems that have an ambient
@@ -13,16 +13,16 @@ What: /sys/class/leds/dell::kbd_backlight/als_setting
Date: December 2014
KernelVersion: 3.19
Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>,
- Pali Rohár <pali.rohar@gmail.com>
+ Pali Rohár <pali@kernel.org>
Description:
- This file allows to specifiy the on/off threshold value,
+ This file allows to specify the on/off threshold value,
as reported by the ambient light sensor.
What: /sys/class/leds/dell::kbd_backlight/start_triggers
Date: December 2014
KernelVersion: 3.19
Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>,
- Pali Rohár <pali.rohar@gmail.com>
+ Pali Rohár <pali@kernel.org>
Description:
This file allows to control the input triggers that
turn on the keyboard backlight illumination that is
@@ -34,9 +34,12 @@ Description:
this file. To disable a trigger, write its name preceded
by '-' instead.
- For example, to enable the keyboard as trigger run:
+ For example, to enable the keyboard as trigger run::
+
echo +keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers
- To disable it:
+
+ To disable it::
+
echo -keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers
Note that not all the available triggers can be configured.
@@ -45,7 +48,7 @@ What: /sys/class/leds/dell::kbd_backlight/stop_timeout
Date: December 2014
KernelVersion: 3.19
Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>,
- Pali Rohár <pali.rohar@gmail.com>
+ Pali Rohár <pali@kernel.org>
Description:
This file allows to specify the interval after which the
keyboard illumination is disabled because of inactivity.
@@ -57,7 +60,8 @@ Description:
with any the above units. If no unit is specified, the value
is assumed to be expressed in seconds.
- For example, to set the timeout to 10 minutes run:
+ For example, to set the timeout to 10 minutes run::
+
echo 10m > /sys/class/leds/dell::kbd_backlight/stop_timeout
Note that when this file is read, the returned value might be
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-privacy-wmi b/Documentation/ABI/testing/sysfs-platform-dell-privacy-wmi
new file mode 100644
index 000000000000..b4da7b2ea0ca
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dell-privacy-wmi
@@ -0,0 +1,71 @@
+What: /sys/bus/wmi/devices/6932965F-1671-4CEB-B988-D3AB0A901919[-X]/dell_privacy_supported_type
+Date: Apr 2021
+KernelVersion: 5.13
+Contact: "<perry.yuan@dell.com>"
+Description:
+ Display which dell hardware level privacy devices are supported
+ “Dell Privacy” is a set of HW, FW, and SW features to enhance
+ Dell’s commitment to platform privacy for MIC, Camera, and
+ ePrivacy screens.
+ The supported hardware privacy devices are:
+
+ Attributes:
+ Microphone Mute:
+ Identifies the local microphone can be muted by hardware, no applications
+ is available to capture system mic sound
+
+ Camera Shutter:
+ Identifies camera shutter controlled by hardware, which is a micromechanical
+ shutter assembly that is built onto the camera module to block capturing images
+ from outside the laptop
+
+ Values:
+
+ supported:
+ The privacy device is supported by this system
+
+ unsupported:
+ The privacy device is not supported on this system
+
+ For example to check which privacy devices are supported::
+
+ # cat /sys/bus/wmi/drivers/dell-privacy/6932965F-1671-4CEB-B988-D3AB0A901919*/dell_privacy_supported_type
+ [Microphone Mute] [supported]
+ [Camera Shutter] [supported]
+ [ePrivacy Screen] [unsupported]
+
+What: /sys/bus/wmi/devices/6932965F-1671-4CEB-B988-D3AB0A901919[-X]/dell_privacy_current_state
+Date: Apr 2021
+KernelVersion: 5.13
+Contact: "<perry.yuan@dell.com>"
+Description:
+ Allow user space to check current dell privacy device state.
+ Describes the Device State class exposed by BIOS which can be
+ consumed by various applications interested in knowing the Privacy
+ feature capabilities
+
+ Attributes:
+ Microphone:
+ Identifies the local microphone can be muted by hardware, no applications
+ is available to capture system mic sound
+
+ Camera Shutter:
+ Identifies camera shutter controlled by hardware, which is a micromechanical
+ shutter assembly that is built onto the camera module to block capturing images
+ from outside the laptop
+
+ Values:
+ muted:
+ Identifies the privacy device is turned off
+ and cannot send stream to OS applications
+
+ unmuted:
+ Identifies the privacy device is turned on,
+ audio or camera driver can get stream from mic
+ and camera module to OS applications
+
+ For example to check all supported current privacy device states::
+
+ # cat /sys/bus/wmi/drivers/dell-privacy/6932965F-1671-4CEB-B988-D3AB0A901919*/dell_privacy_current_state
+ [Microphone] [unmuted]
+ [Camera Shutter] [unmuted]
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-smbios b/Documentation/ABI/testing/sysfs-platform-dell-smbios
new file mode 100644
index 000000000000..5583da581025
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dell-smbios
@@ -0,0 +1,21 @@
+What: /sys/devices/platform/<platform>/tokens/*
+Date: November 2017
+KernelVersion: 4.15
+Contact: Dell.Client.Kernel@dell.com
+Description:
+ A read-only description of Dell platform tokens
+ available on the machine.
+
+ Each token attribute is available as a pair of
+ sysfs attributes readable by a process with
+ CAP_SYS_ADMIN.
+
+ For example the token ID "5" would be available
+ as the following attributes:
+
+ - 0005_location
+ - 0005_value
+
+ Tokens will vary from machine to machine, and
+ only tokens available on that machine will be
+ displayed.
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv b/Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv
new file mode 100644
index 000000000000..a9d39d9e8865
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dell-wmi-ddv
@@ -0,0 +1,9 @@
+What: /sys/class/power_supply/<battery_name>/eppid
+Date: September 2022
+KernelVersion: 6.1
+Contact: Armin Wolf <W_Armin@gmx.de>
+Description:
+ Reports the Dell ePPID (electronic Piece Part Identification)
+ of the ACPI battery.
+
+ See Documentation/wmi/devices/dell-wmi-ddv.rst for details.
diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme
new file mode 100644
index 000000000000..2d5b78d2cf51
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
@@ -0,0 +1,246 @@
+What: /sys/bus/platform/devices/dfl-fme.0/ports_num
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. One DFL FPGA device may have more than 1
+ port/Accelerator Function Unit (AFU). It returns the
+ number of ports on the FPGA device when read it.
+
+What: /sys/bus/platform/devices/dfl-fme.0/bitstream_id
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns Bitstream (static FPGA region)
+ identifier number, which includes the detailed version
+ and other information of this static FPGA region.
+
+What: /sys/bus/platform/devices/dfl-fme.0/bitstream_metadata
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns Bitstream (static FPGA region) meta
+ data, which includes the synthesis date, seed and other
+ information of this static FPGA region.
+
+What: /sys/bus/platform/devices/dfl-fme.0/cache_size
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns cache size of this FPGA device.
+
+What: /sys/bus/platform/devices/dfl-fme.0/fabric_version
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns fabric version of this FPGA device.
+ Userspace applications need this information to select
+ best data channels per different fabric design.
+
+What: /sys/bus/platform/devices/dfl-fme.0/socket_id
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns socket_id to indicate which socket
+ this FPGA belongs to, only valid for integrated solution.
+ User only needs this information, in case standard numa node
+ can't provide correct information.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/pcie0_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file for errors detected on pcie0 link.
+ Write this file to clear errors logged in pcie0_errors. Write
+ fails with -EINVAL if input parsing fails or input error code
+ doesn't match.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/pcie1_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file for errors detected on pcie1 link.
+ Write this file to clear errors logged in pcie1_errors. Write
+ fails with -EINVAL if input parsing fails or input error code
+ doesn't match.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/nonfatal_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns non-fatal errors detected.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/catfatal_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns catastrophic and fatal errors detected.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/inject_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to check errors injected. Write this
+ file to inject errors for testing purpose. Write fails with
+ -EINVAL if input parsing fails or input inject error code isn't
+ supported.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/fme_errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to get errors detected on FME.
+ Write this file to clear errors logged in fme_errors. Write
+ fails with -EINVAL if input parsing fails or input error code
+ doesn't match.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/first_error
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the first error detected by
+ hardware.
+
+What: /sys/bus/platform/devices/dfl-fme.0/errors/next_error
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the second error detected by
+ hardware.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/name
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. Read this file to get the name of hwmon device, it
+ supports values:
+
+ ================= =========================
+ 'dfl_fme_thermal' thermal hwmon device name
+ 'dfl_fme_power' power hwmon device name
+ ================= =========================
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns FPGA device temperature in millidegrees
+ Celsius.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_max
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns hardware threshold1 temperature in
+ millidegrees Celsius. If temperature rises at or above this
+ threshold, hardware starts 50% or 90% throttling (see
+ 'temp1_max_policy').
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_crit
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns hardware threshold2 temperature in
+ millidegrees Celsius. If temperature rises at or above this
+ threshold, hardware starts 100% throttling.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_emergency
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns hardware trip threshold temperature in
+ millidegrees Celsius. If temperature rises at or above this
+ threshold, a fatal event will be triggered to board management
+ controller (BMC) to shutdown FPGA.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_max_alarm
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns 1 if temperature is currently at or above
+ hardware threshold1 (see 'temp1_max'), otherwise 0.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_crit_alarm
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns 1 if temperature is currently at or above
+ hardware threshold2 (see 'temp1_crit'), otherwise 0.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_max_policy
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. Read this file to get the policy of hardware threshold1
+ (see 'temp1_max'). It only supports two values (policies):
+
+ == ==========================
+ 0 AP2 state (90% throttling)
+ 1 AP1 state (50% throttling)
+ == ==========================
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns current FPGA power consumption in uW.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_max
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to get current hardware power
+ threshold1 in uW. If power consumption rises at or above
+ this threshold, hardware starts 50% throttling.
+ Write this file to set current hardware power threshold1 in uW.
+ As hardware only accepts values in Watts, so input value will
+ be round down per Watts (< 1 watts part will be discarded) and
+ clamped within the range from 0 to 127 Watts. Write fails with
+ -EINVAL if input parsing fails.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_crit
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to get current hardware power
+ threshold2 in uW. If power consumption rises at or above
+ this threshold, hardware starts 90% throttling.
+ Write this file to set current hardware power threshold2 in uW.
+ As hardware only accepts values in Watts, so input value will
+ be round down per Watts (< 1 watts part will be discarded) and
+ clamped within the range from 0 to 127 Watts. Write fails with
+ -EINVAL if input parsing fails.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_max_alarm
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns 1 if power consumption is currently at or
+ above hardware threshold1 (see 'power1_max'), otherwise 0.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_crit_alarm
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns 1 if power consumption is currently at or
+ above hardware threshold2 (see 'power1_crit'), otherwise 0.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_xeon_limit
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns power limit for XEON in uW.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_fpga_limit
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Only. It returns power limit for FPGA in uW.
+
+What: /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_ltr
+Date: October 2019
+KernelVersion: 5.5
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get current Latency Tolerance
+ Reporting (ltr) value. It returns 1 if all Accelerated
+ Function Units (AFUs) can tolerate latency >= 40us for memory
+ access or 0 if any AFU is latency sensitive (< 40us).
diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-port b/Documentation/ABI/testing/sysfs-platform-dfl-port
new file mode 100644
index 000000000000..65658267fcc0
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dfl-port
@@ -0,0 +1,101 @@
+What: /sys/bus/platform/devices/dfl-port.0/id
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It returns id of this port. One DFL FPGA device
+ may have more than one port. Userspace could use this id to
+ distinguish different ports under same FPGA device.
+
+What: /sys/bus/platform/devices/dfl-port.0/afu_id
+Date: June 2018
+KernelVersion: 4.19
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. User can program different PR bitstreams to FPGA
+ Accelerator Function Unit (AFU) for different functions. It
+ returns uuid which could be used to identify which PR bitstream
+ is programmed in this AFU.
+
+What: /sys/bus/platform/devices/dfl-port.0/power_state
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. It reports the APx (AFU Power) state, different APx
+ means different throttling level. When reading this file, it
+ returns "0" - Normal / "1" - AP1 / "2" - AP2 / "6" - AP6.
+
+What: /sys/bus/platform/devices/dfl-port.0/ap1_event
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-write. Read this file for AP1 (AFU Power State 1) event.
+ It's used to indicate transient AP1 state. Write 1 to this
+ file to clear AP1 event.
+
+What: /sys/bus/platform/devices/dfl-port.0/ap2_event
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-write. Read this file for AP2 (AFU Power State 2) event.
+ It's used to indicate transient AP2 state. Write 1 to this
+ file to clear AP2 event.
+
+What: /sys/bus/platform/devices/dfl-port.0/ltr
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-write. Read or set AFU latency tolerance reporting value.
+ Set ltr to 1 if the AFU can tolerate latency >= 40us or set it
+ to 0 if it is latency sensitive.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcmd
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Write-only. User writes command to this interface to set
+ userclock to AFU.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqsts
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the status of issued command
+ to userclck_freqcmd.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcntrcmd
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Write-only. User writes command to this interface to set
+ userclock counter.
+
+What: /sys/bus/platform/devices/dfl-port.0/userclk_freqcntrsts
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the status of issued command
+ to userclck_freqcntrcmd.
+
+What: /sys/bus/platform/devices/dfl-port.0/errors/errors
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-Write. Read this file to get errors detected on port and
+ Accelerated Function Unit (AFU). Write error code to this file
+ to clear errors. Write fails with -EINVAL if input parsing
+ fails or input error code doesn't match. Write fails with
+ -EBUSY or -ETIMEDOUT if error can't be cleared as hardware
+ in low power state (-EBUSY) or not respoding (-ETIMEDOUT).
+
+What: /sys/bus/platform/devices/dfl-port.0/errors/first_error
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the first error detected by
+ hardware.
+
+What: /sys/bus/platform/devices/dfl-port.0/errors/first_malformed_req
+Date: August 2019
+KernelVersion: 5.4
+Contact: Wu Hao <hao.wu@intel.com>
+Description: Read-only. Read this file to get the first malformed request
+ captured by hardware.
diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
new file mode 100644
index 000000000000..620fd20434a5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dptf
@@ -0,0 +1,157 @@
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/charger_type
+Date: Jul, 2016
+KernelVersion: v4.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The charger type - Traditional, Hybrid or NVDC.
+
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw
+Date: Jul, 2016
+KernelVersion: v4.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Adapter rating in milliwatts (the maximum Adapter power).
+ Must be 0 if no AC Adaptor is plugged in.
+
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw
+Date: Jul, 2016
+KernelVersion: v4.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Maximum platform power that can be supported by the battery
+ in milliwatts.
+
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source
+Date: Jul, 2016
+KernelVersion: v4.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Display the platform power source
+
+ ========= ============================
+ bits[3:0] Current power source
+ - 0x00 = DC
+ - 0x01 = AC
+ - 0x02 = USB
+ - 0x03 = Wireless Charger
+ bits[7:4] Power source sequence number
+ ========= ============================
+
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
+Date: Jul, 2016
+KernelVersion: v4.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The maximum sustained power for battery in milliwatts.
+
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/rest_of_platform_power_mw
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Shows the rest (outside of SoC) of worst-case platform power.
+
+What: /sys/bus/platform/devices/INT3407:00/dptf_power/prochot_confirm
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (WO) Confirm embedded controller about a prochot notification.
+
+What: /sys/bus/platform/devices/INT3532:00/dptf_battery/max_platform_power_mw
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The maximum platform power that can be supported by the battery in milli watts.
+
+What: /sys/bus/platform/devices/INT3532:00/dptf_battery/max_steady_state_power_mw
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The maximum sustained power for battery in milli watts.
+
+What: /sys/bus/platform/devices/INT3532:00/dptf_battery/high_freq_impedance_mohm
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The high frequency impedance value that can be obtained from battery
+ fuel gauge in milli Ohms.
+
+What: /sys/bus/platform/devices/INT3532:00/dptf_battery/no_load_voltage_mv
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The no-load voltage that can be obtained from battery fuel gauge in
+ milli volts.
+
+What: /sys/bus/platform/devices/INT3532:00/dptf_battery/current_discharge_capbility_ma
+Date: June, 2020
+KernelVersion: v5.8
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) The battery discharge current capability obtained from battery fuel gauge in
+ milli Amps.
+
+What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/freq_mhz_low_clock
+Date: November, 2020
+KernelVersion: v5.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RW) The PCH FIVR (Fully Integrated Voltage Regulator) switching frequency in MHz,
+ when FIVR clock is 19.2MHz or 24MHz.
+
+What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/freq_mhz_high_clock
+Date: November, 2020
+KernelVersion: v5.10
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RW) The PCH FIVR (Fully Integrated Voltage Regulator) switching frequency in MHz,
+ when FIVR clock is 38.4MHz.
+
+What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/fivr_switching_freq_mhz
+Date: September, 2021
+KernelVersion: v5.15
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Get the FIVR switching control frequency in MHz.
+
+What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/fivr_switching_fault_status
+Date: September, 2021
+KernelVersion: v5.15
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Read the FIVR switching frequency control fault status.
+
+What: /sys/bus/platform/devices/INTC1045:00/pch_fivr_switch_frequency/ssc_clock_info
+Date: September, 2021
+KernelVersion: v5.15
+Contact: linux-acpi@vger.kernel.org
+Description:
+ (RO) Presents SSC (spread spectrum clock) information for EMI
+ (Electro magnetic interference) control. This is a bit mask.
+
+ ======= ==========================================
+ Bits Description
+ ======= ==========================================
+ [7:0] Sets clock spectrum spread percentage:
+ 0x00=0.2% , 0x3F=10%
+ 1 LSB = 0.1% increase in spread (for
+ settings 0x01 thru 0x1C)
+ 1 LSB = 0.2% increase in spread (for
+ settings 0x1E thru 0x3F)
+ [8] When set to 1, enables spread
+ spectrum clock
+ [9] 0: Triangle mode. FFC frequency
+ walks around the Fcenter in a linear
+ fashion
+ 1: Random walk mode. FFC frequency
+ changes randomly within the SSC
+ (Spread spectrum clock) range
+ [10] 0: No white noise. 1: Add white noise
+ to spread waveform
+ [11] When 1, future writes are ignored.
+ ======= ==========================================
diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
index 5b026c69587a..70dbe0733cf6 100644
--- a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
@@ -4,9 +4,11 @@ KernelVersion: 2.6.26
Contact: "Corentin Chary" <corentincj@iksaif.net>
Description:
This file allows display switching.
+
- 1 = LCD
- 2 = CRT
- 3 = LCD+CRT
+
If you run X11, you should use xrandr instead.
What: /sys/devices/platform/eeepc/camera
@@ -30,16 +32,20 @@ Contact: "Corentin Chary" <corentincj@iksaif.net>
Description:
Change CPU clock configuration.
On the Eee PC 1000H there are three available clock configuration:
+
* 0 -> Super Performance Mode
* 1 -> High Performance Mode
* 2 -> Power Saving Mode
+
On Eee PC 701 there is only 2 available clock configurations.
Available configuration are listed in available_cpufv file.
Reading this file will show the raw hexadecimal value which
- is defined as follow:
- | 8 bit | 8 bit |
- | `---- Current mode
- `------------ Availables modes
+ is defined as follow::
+
+ | 8 bit | 8 bit |
+ | `---- Current mode
+ `------------ Availables modes
+
For example, 0x301 means: mode 1 selected, 3 available modes.
What: /sys/devices/platform/eeepc/available_cpufv
diff --git a/Documentation/ABI/testing/sysfs-platform-hidma b/Documentation/ABI/testing/sysfs-platform-hidma
new file mode 100644
index 000000000000..a80aeda85ef6
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-hidma
@@ -0,0 +1,9 @@
+What: /sys/devices/platform/hidma-*/chid
+ /sys/devices/platform/QCOM8061:*/chid
+Date: Dec 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains the ID of the channel within the HIDMA instance.
+ It is used to associate a given HIDMA channel with the
+ priority and weight calls in the management interface.
diff --git a/Documentation/ABI/testing/sysfs-platform-hidma-mgmt b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt
new file mode 100644
index 000000000000..0373745b4e18
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt
@@ -0,0 +1,97 @@
+What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/priority
+ /sys/devices/platform/QCOM8060:*/chanops/chan*/priority
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains either 0 or 1 and indicates if the DMA channel is a
+ low priority (0) or high priority (1) channel.
+
+What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/weight
+ /sys/devices/platform/QCOM8060:*/chanops/chan*/weight
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains 0..15 and indicates the weight of the channel among
+ equal priority channels during round robin scheduling.
+
+What: /sys/devices/platform/hidma-mgmt*/chreset_timeout_cycles
+ /sys/devices/platform/QCOM8060:*/chreset_timeout_cycles
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains the platform specific cycle value to wait after a
+ reset command is issued. If the value is chosen too short,
+ then the HW will issue a reset failure interrupt. The value
+ is platform specific and should not be changed without
+ consultance.
+
+What: /sys/devices/platform/hidma-mgmt*/dma_channels
+ /sys/devices/platform/QCOM8060:*/dma_channels
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains the number of dma channels supported by one instance
+ of HIDMA hardware. The value may change from chip to chip.
+
+What: /sys/devices/platform/hidma-mgmt*/hw_version_major
+ /sys/devices/platform/QCOM8060:*/hw_version_major
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Version number major for the hardware.
+
+What: /sys/devices/platform/hidma-mgmt*/hw_version_minor
+ /sys/devices/platform/QCOM8060:*/hw_version_minor
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Version number minor for the hardware.
+
+What: /sys/devices/platform/hidma-mgmt*/max_rd_xactions
+ /sys/devices/platform/QCOM8060:*/max_rd_xactions
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains a value between 0 and 31. Maximum number of
+ read transactions that can be issued back to back.
+ Choosing a higher number gives better performance but
+ can also cause performance reduction to other peripherals
+ sharing the same bus.
+
+What: /sys/devices/platform/hidma-mgmt*/max_read_request
+ /sys/devices/platform/QCOM8060:*/max_read_request
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Size of each read request. The value needs to be a power
+ of two and can be between 128 and 1024.
+
+What: /sys/devices/platform/hidma-mgmt*/max_wr_xactions
+ /sys/devices/platform/QCOM8060:*/max_wr_xactions
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Contains a value between 0 and 31. Maximum number of
+ write transactions that can be issued back to back.
+ Choosing a higher number gives better performance but
+ can also cause performance reduction to other peripherals
+ sharing the same bus.
+
+
+What: /sys/devices/platform/hidma-mgmt*/max_write_request
+ /sys/devices/platform/QCOM8060:*/max_write_request
+Date: Nov 2015
+KernelVersion: 4.4
+Contact: "Sinan Kaya <okaya@kernel.org>"
+Description:
+ Size of each write request. The value needs to be a power
+ of two and can be between 128 and 1024.
diff --git a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl
new file mode 100644
index 000000000000..b6a138b50d99
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl
@@ -0,0 +1,18 @@
+What: /sys/devices/platform/<i2c-demux-name>/available_masters
+Date: January 2016
+KernelVersion: 4.6
+Contact: Wolfram Sang <wsa+renesas@sang-engineering.com>
+Description:
+ Reading the file will give you a list of masters which can be
+ selected for a demultiplexed bus. The format is
+ "<index>:<name>". Example from a Renesas Lager board::
+
+ 0:/i2c@e6500000 1:/i2c@e6508000
+
+What: /sys/devices/platform/<i2c-demux-name>/current_master
+Date: January 2016
+KernelVersion: 4.6
+Contact: Wolfram Sang <wsa+renesas@sang-engineering.com>
+Description:
+ This file selects/shows the active I2C master for a demultiplexed
+ bus. It uses the <index> value from the file 'available_masters'.
diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
index b31e782bd985..5ec0dee9e707 100644
--- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
@@ -1,19 +1,52 @@
-What: /sys/devices/platform/ideapad/camera_power
+What: /sys/bus/platform/devices/VPC2004:*/camera_power
Date: Dec 2010
KernelVersion: 2.6.37
Contact: "Ike Panhc <ike.pan@canonical.com>"
Description:
Control the power of camera module. 1 means on, 0 means off.
-What: /sys/devices/platform/ideapad/fan_mode
+What: /sys/bus/platform/devices/VPC2004:*/fan_mode
Date: June 2012
KernelVersion: 3.6
Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>"
Description:
Change fan mode
There are four available modes:
+
* 0 -> Super Silent Mode
* 1 -> Standard Mode
* 2 -> Dust Cleaning
* 4 -> Efficient Thermal Dissipation Mode
+What: /sys/bus/platform/devices/VPC2004:*/touchpad
+Date: May 2017
+KernelVersion: 4.13
+Contact: "Ritesh Raj Sarraf <rrs@debian.org>"
+Description:
+ Control touchpad mode.
+ * 1 -> Switched On
+ * 0 -> Switched Off
+
+What: /sys/bus/platform/devices/VPC2004:*/fn_lock
+Date: May 2018
+KernelVersion: 4.18
+Contact: "Oleg Keri <ezhi99@gmail.com>"
+Description:
+ Control fn-lock mode.
+
+ * 1 -> Switched On
+ * 0 -> Switched Off
+
+ For example::
+
+ # echo "0" > \
+ /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
+
+What: /sys/bus/platform/devices/VPC2004:*/usb_charging
+Date: Feb 2021
+KernelVersion: 5.12
+Contact: platform-driver-x86@vger.kernel.org
+Description:
+ Controls whether the "always on USB charging" feature is
+ enabled or not. This feature enables charging USB devices
+ even if the computer is not turned on.
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-ifs b/Documentation/ABI/testing/sysfs-platform-intel-ifs
new file mode 100644
index 000000000000..41b4d5b1e21c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-intel-ifs
@@ -0,0 +1,52 @@
+Device instance to test mapping
+intel_ifs_0 -> Scan Test
+intel_ifs_1 -> Array BIST test
+
+What: /sys/devices/virtual/misc/intel_ifs_<N>/run_test
+Date: Nov 16 2022
+KernelVersion: 6.2
+Contact: "Jithu Joseph" <jithu.joseph@intel.com>
+Description: Write <cpu#> to trigger IFS test for one online core.
+ Note that the test is per core. The cpu# can be
+ for any thread on the core. Running on one thread
+ completes the test for the core containing that thread.
+ Example: to test the core containing cpu5: echo 5 >
+ /sys/devices/virtual/misc/intel_ifs_<N>/run_test
+Devices: all
+
+What: /sys/devices/virtual/misc/intel_ifs_<N>/status
+Date: Nov 16 2022
+KernelVersion: 6.2
+Contact: "Jithu Joseph" <jithu.joseph@intel.com>
+Description: The status of the last test. It can be one of "pass", "fail"
+ or "untested".
+Devices: all
+
+What: /sys/devices/virtual/misc/intel_ifs_<N>/details
+Date: Nov 16 2022
+KernelVersion: 6.2
+Contact: "Jithu Joseph" <jithu.joseph@intel.com>
+Description: Additional information regarding the last test. The details file reports
+ the hex value of the STATUS MSR for this test. Note that the error_code field
+ may contain driver defined software code not defined in the Intel SDM.
+Devices: all
+
+What: /sys/devices/virtual/misc/intel_ifs_<N>/image_version
+Date: Nov 16 2022
+KernelVersion: 6.2
+Contact: "Jithu Joseph" <jithu.joseph@intel.com>
+Description: Version (hexadecimal) of loaded IFS test image. If no test image
+ is loaded reports "none". Only present for device instances where a test image
+ is applicable.
+Devices: intel_ifs_0
+
+What: /sys/devices/virtual/misc/intel_ifs_<N>/current_batch
+Date: Nov 16 2022
+KernelVersion: 6.2
+Contact: "Jithu Joseph" <jithu.joseph@intel.com>
+Description: Write a number less than or equal to 0xff to load an IFS test image.
+ The number written treated as the 2 digit suffix in the following file name:
+ /lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.scan
+ Reading the file will provide the suffix of the currently loaded IFS test image.
+ This file is present only for device instances where a test image is applicable.
+Devices: intel_ifs_0
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-pmc b/Documentation/ABI/testing/sysfs-platform-intel-pmc
new file mode 100644
index 000000000000..f31d59b21f9b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-intel-pmc
@@ -0,0 +1,22 @@
+What: /sys/devices/platform/<platform>/etr3
+Date: Apr 2021
+KernelVersion: 5.13
+Contact: "Tomas Winkler" <tomas.winkler@intel.com>
+Description:
+ The file exposes "Extended Test Mode Register 3" global
+ reset bits. The bits are used during an Intel platform
+ manufacturing process to indicate that consequent reset
+ of the platform is a "global reset". This type of reset
+ is required in order for manufacturing configurations
+ to take effect.
+
+ Display global reset setting bits for PMC.
+
+ * bit 31 - global reset is locked
+ * bit 20 - global reset is set
+
+ Writing bit 20 value to the etr3 will induce
+ a platform "global reset" upon consequent platform reset,
+ in case the register is not locked.
+ The "global reset bit" should be locked on a production
+ system and the file is in read-only mode.
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
new file mode 100644
index 000000000000..7ffd1579b8f7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
@@ -0,0 +1,13 @@
+What: /sys/bus/wmi/devices/44FADEB1-B204-40F2-8581-394BBDC1B651[-X]/firmware_update_request
+Date: April 2020
+KernelVersion: 5.7
+Contact: "Jithu Joseph" <jithu.joseph@intel.com>
+Description:
+ Allow user space entities to trigger update of Slim
+ Bootloader (SBL). This attribute normally has a value
+ of 0 and userspace can signal SBL to update firmware,
+ on next reboot, by writing a value of 1.
+ There are two available states:
+
+ * 0 -> Skip firmware update while rebooting
+ * 1 -> Attempt firmware update on next reboot
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
new file mode 100644
index 000000000000..10ef1282c9d2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
@@ -0,0 +1,12 @@
+What: /sys/bus/wmi/devices/86CCFD48-205E-4A77-9C48-2021CBEDE341[-X]/force_power
+Date: September 2017
+KernelVersion: 4.15
+Contact: "Mario Limonciello" <mario.limonciello@outlook.com>
+Description:
+ Modify the platform force power state, influencing
+ Thunderbolt controllers to turn on or off when no
+ devices are connected (write-only)
+ There are two available states:
+
+ * 0 -> Force power disabled
+ * 1 -> Force power enabled
diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim
index c1653271872a..0a38caa62a32 100644
--- a/Documentation/ABI/testing/sysfs-platform-kim
+++ b/Documentation/ABI/testing/sysfs-platform-kim
@@ -5,10 +5,11 @@ Contact: "Pavan Savoy" <pavan_savoy@ti.com>
Description:
Name of the UART device at which the WL128x chip
is connected. example: "/dev/ttyS0".
+
The device name flows down to architecture specific board
- initialization file from the SFI/ATAGS bootloader
+ initialization file from the ATAGS bootloader
firmware. The name exposed is read from the user-space
- dameon and opens the device when install is requested.
+ daemon and opens the device when install is requested.
What: /sys/devices/platform/kim/baud_rate
Date: January 2010
diff --git a/Documentation/ABI/testing/sysfs-platform-lg-laptop b/Documentation/ABI/testing/sysfs-platform-lg-laptop
new file mode 100644
index 000000000000..0570cd524d0e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-lg-laptop
@@ -0,0 +1,36 @@
+What: /sys/devices/platform/lg-laptop/reader_mode
+Date: October 2018
+KernelVersion: 4.20
+Contact: "Matan Ziv-Av <matan@svgalib.org>
+Description:
+ Control reader mode. 1 means on, 0 means off.
+
+What: /sys/devices/platform/lg-laptop/fn_lock
+Date: October 2018
+KernelVersion: 4.20
+Contact: "Matan Ziv-Av <matan@svgalib.org>
+Description:
+ Control FN lock mode. 1 means on, 0 means off.
+
+What: /sys/devices/platform/lg-laptop/battery_care_limit
+Date: October 2018
+KernelVersion: 4.20
+Contact: "Matan Ziv-Av <matan@svgalib.org>
+Description:
+ Deprecated use /sys/class/power_supply/CMB0/charge_control_end_threshold
+ Maximal battery charge level. Accepted values are 80 or 100.
+
+What: /sys/devices/platform/lg-laptop/fan_mode
+Date: October 2018
+KernelVersion: 4.20
+Contact: "Matan Ziv-Av <matan@svgalib.org>
+Description:
+ Control fan mode. 1 for performance mode, 0 for silent mode.
+
+What: /sys/devices/platform/lg-laptop/usb_charge
+Date: October 2018
+KernelVersion: 4.20
+Contact: "Matan Ziv-Av <matan@svgalib.org>
+Description:
+ Control USB port charging when device is turned off.
+ 1 means on, 0 means off.
diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
new file mode 100644
index 000000000000..09f783fa0a53
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
@@ -0,0 +1,162 @@
+What: /sys/bus/platform/devices/MLNXBF04:00/lifecycle_state
+Date: Oct 2019
+KernelVersion: 5.5
+Contact: "Liming Sun <lsun@mellanox.com>"
+Description:
+ The Life-cycle state of the SoC, which could be one of the
+ following values.
+
+ ============== =============================================
+ Production Production state and can be updated to secure
+ GA Secured Secure chip and not able to change state
+ GA Non-Secured Non-Secure chip and not able to change state
+ RMA Return Merchandise Authorization
+ ============== =============================================
+
+What: /sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
+Date: Oct 2019
+KernelVersion: 5.5
+Contact: "Liming Sun <lsun@mellanox.com>"
+Description:
+ The watchdog setting in seconds for the next booting. It's used
+ to reboot the chip and recover it to the old state if the new
+ boot partition fails.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/reset_action
+Date: Oct 2019
+KernelVersion: 5.5
+Contact: "Liming Sun <lsun@mellanox.com>"
+Description:
+ The source of the boot stream for the next reset. It could be
+ one of the following values:
+
+ =========== ===============================================
+ external boot from external source (USB or PCIe)
+ emmc boot from the onchip eMMC
+ emmc_legacy boot from the onchip eMMC in legacy (slow) mode
+ =========== ===============================================
+
+What: /sys/bus/platform/devices/MLNXBF04:00/second_reset_action
+Date: Oct 2019
+KernelVersion: 5.5
+Contact: "Liming Sun <lsun@mellanox.com>"
+Description:
+ Update the source of the boot stream after next reset. It could
+ be one of the following values and will be applied after next
+ reset.
+
+ =========== ===============================================
+ external boot from external source (USB or PCIe)
+ emmc boot from the onchip eMMC
+ emmc_legacy boot from the onchip eMMC in legacy (slow) mode
+ swap_emmc swap the primary / secondary boot partition
+ none cancel the action
+ =========== ===============================================
+
+What: /sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
+Date: Oct 2019
+KernelVersion: 5.5
+Contact: "Liming Sun <lsun@mellanox.com>"
+Description:
+ The state of eFuse versions with the following values.
+
+ ======= ===============================================
+ InUse burnt, valid and currently in use
+ Used burnt and valid
+ Free not burnt and free to use
+ Skipped not burnt but not free (skipped)
+ Wasted burnt and invalid
+ Invalid not burnt but marked as valid (error state).
+ ======= ===============================================
+
+What: /sys/bus/platform/devices/MLNXBF04:00/bootfifo
+Date: Apr 2023
+KernelVersion: 6.4
+Contact: "Liming Sun <limings@nvidia.com>"
+Description:
+ The file used to access the BlueField boot fifo.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/rsh_log
+Date: May 2023
+KernelVersion: 6.4
+Contact: "Liming Sun <limings@nvidia.com>"
+Description:
+ The file used to write BlueField boot log with the format
+ "[INFO|WARN|ERR|ASSERT ]<msg>". Log level 'INFO' is used by
+ default if not specified.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/oob_mac
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "oob_mac" sysfs attribute holds the MAC address for
+ the out-of-band 1Gbps Ethernet port. This MAC address is
+ provided on a board-level label.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/opn
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "opn" sysfs attribute holds the board's part number.
+ This value is provided on a board-level label.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/sku
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "sku" sysfs attribute holds the board's SKU number.
+ This value is provided on a board-level label.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/modl
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "modl" sysfs attribute holds the board's model number.
+ This value is provided on a board-level label.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/sn
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "sn" sysfs attribute holds the board's serial number.
+ This value is provided on a board-level label.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/uuid
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "uuid" sysfs attribute holds the board's UUID.
+ This value is provided by the manufacturing team.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/rev
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "rev" sysfs attribute holds the board's revision.
+ This value is provided on a board-level label.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/mfg_lock
+Date: August 2023
+KernelVersion: 6.5
+Contact: "David Thompson <davthompson@nvidia.com>"
+Description:
+ The "mfg_lock" sysfs attribute is write-only.
+ A successful write to this attribute will latch the
+ board-level attributes into EEPROM, making them read-only.
+
+What: /sys/bus/platform/devices/MLNXBF04:00/rtc_battery
+Date: June 2025
+KernelVersion: 6.15
+Contact: "Xiangrong Li <xiangrongl@nvidia.com>"
+Description:
+ The "rtc_battery" sysfs attribute is read-only.
+ A successful read from this attribute returns the status of
+ the board's RTC battery. The RTC battery status register is
+ also cleared upon successful read operation.
diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-pmc b/Documentation/ABI/testing/sysfs-platform-mellanox-pmc
new file mode 100644
index 000000000000..29b3f9c58e00
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-mellanox-pmc
@@ -0,0 +1,64 @@
+HID Driver Description
+MLNXBFD0 mlxbf-pmc Performance counters (BlueField-1)
+MLNXBFD1 mlxbf-pmc Performance counters (BlueField-2)
+MLNXBFD2 mlxbf-pmc Performance counters (BlueField-3)
+
+What: /sys/bus/platform/devices/<HID>/hwmon/hwmonX/<block>/event_list
+Date: Dec 2020
+KernelVersion: 5.10
+Contact: "Shravan Kumar Ramani <shravankr@nvidia.com>"
+Description:
+ List of events supported by the counters in the specific block.
+ It is used to extract the event number or ID associated with
+ each event.
+
+What: /sys/bus/platform/devices/<HID>/hwmon/hwmonX/<block>/event<N>
+Date: Dec 2020
+KernelVersion: 5.10
+Contact: "Shravan Kumar Ramani <shravankr@nvidia.com>"
+Description:
+ Event monitored by corresponding counter. This is used to
+ program or read back the event that should be or is currently
+ being monitored by counter<N>.
+
+What: /sys/bus/platform/devices/<HID>/hwmon/hwmonX/<block>/counter<N>
+Date: Dec 2020
+KernelVersion: 5.10
+Contact: "Shravan Kumar Ramani <shravankr@nvidia.com>"
+Description:
+ Counter value of the event being monitored. This is used to
+ read the counter value of the event which was programmed using
+ event<N>. This is also used to clear or reset the counter value
+ by writing 0 to the counter sysfs.
+
+What: /sys/bus/platform/devices/<HID>/hwmon/hwmonX/<block>/enable
+Date: Dec 2020
+KernelVersion: 5.10
+Contact: "Shravan Kumar Ramani <shravankr@nvidia.com>"
+Description:
+ Start or stop counters. This is used to start the counters
+ for monitoring the programmed events and also to stop the
+ counters after the desired duration. Writing value 1 will
+ start all the counters in the block, and writing 0 will
+ stop all the counters together.
+
+What: /sys/bus/platform/devices/<HID>/hwmon/hwmonX/<block>/<reg>
+Date: Dec 2020
+KernelVersion: 5.10
+Contact: "Shravan Kumar Ramani <shravankr@nvidia.com>"
+Description:
+ Value of register. This is used to read or reset the registers
+ where various performance statistics are counted for each block.
+ Writing 0 to the sysfs will clear the counter, writing any other
+ value is not allowed.
+
+What: /sys/bus/platform/devices/<HID>/hwmon/hwmonX/<block>/count_clock
+Date: Mar 2025
+KernelVersion: 6.14
+Contact: "Shravan Kumar Ramani <shravankr@nvidia.com>"
+Description:
+ Use a counter for counting cycles. This is used to repurpose/dedicate
+ any of the counters in the block to counting cycles. Each counter is
+ represented by a bit (bit 0 for counter0, bit1 for counter1 and so on)
+ and setting the corresponding bit will reserve that specific counter
+ for counting cycles and override the event<N> setting.
diff --git a/Documentation/ABI/testing/sysfs-platform-oxp b/Documentation/ABI/testing/sysfs-platform-oxp
new file mode 100644
index 000000000000..b3f39fc21dfa
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-oxp
@@ -0,0 +1,25 @@
+What: /sys/devices/platform/<platform>/tt_toggle
+Date: Jun 2023
+KernelVersion: 6.5
+Contact: "Antheas Kapenekakis" <lkml@antheas.dev>
+Description:
+ Takeover TDP controls from the device. OneXPlayer devices have a
+ turbo button that can be used to switch between two TDP modes
+ (usually 15W and 25W). By setting this attribute to 1, this
+ functionality is disabled, handing TDP control over to (Windows)
+ userspace software and the Turbo button turns into a keyboard
+ shortcut over the AT keyboard of the device. In addition,
+ using this setting is a prerequisite for PWM control for most
+ newer models (otherwise it NOOPs).
+
+What: /sys/devices/platform/<platform>/tt_led
+Date: April 2025
+KernelVersion: 6.16
+Contact: "Antheas Kapenekakis" <lkml@antheas.dev>
+Description:
+ Some OneXPlayer devices (e.g., X1 series) feature a little LED
+ nested in the Turbo button. This LED is illuminated when the
+ device is in the higher TDP mode (e.g., 25W). Once tt_toggle
+ is engaged, this LED is left dangling to its last state. This
+ attribute allows userspace to control the LED state manually
+ (either with 1 or 0). Only a subset of devices contain this LED.
diff --git a/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
new file mode 100644
index 000000000000..bc510ccc37a7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
@@ -0,0 +1,17 @@
+What: /sys/devices/platform/<phy-name>/role
+Date: October 2016
+KernelVersion: 4.10
+Contact: Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
+Description:
+ This file can be read and write.
+ The file can show/change the phy mode for role swap of usb.
+
+ Write the following strings to change the mode:
+
+ - "host" - switching mode from peripheral to host.
+ - "peripheral" - switching mode from host to peripheral.
+
+ Read the file, then it shows the following strings:
+
+ - "host" - The mode is host now.
+ - "peripheral" - The mode is peripheral now.
diff --git a/Documentation/ABI/testing/sysfs-platform-power-on-reason b/Documentation/ABI/testing/sysfs-platform-power-on-reason
new file mode 100644
index 000000000000..c3b29dbc64bf
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-power-on-reason
@@ -0,0 +1,12 @@
+What: /sys/devices/platform/.../power_on_reason
+Date: June 2023
+KernelVersion: 6.5
+Contact: Kamel Bouhara <kamel.bouhara@bootlin.com>
+Description: Shows system power on reason. The following strings/reasons can
+ be read (the list can be extended):
+ "regular power-up", "RTC wakeup", "watchdog timeout",
+ "software reset", "reset button action", "CPU clock failure",
+ "crystal oscillator failure", "brown-out reset",
+ "unknown reason".
+
+ The file is read only.
diff --git a/Documentation/ABI/testing/sysfs-platform-renesas_usb3 b/Documentation/ABI/testing/sysfs-platform-renesas_usb3
new file mode 100644
index 000000000000..b08379e7fe37
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-renesas_usb3
@@ -0,0 +1,17 @@
+What: /sys/devices/platform/<renesas_usb3's name>/role
+Date: March 2017
+KernelVersion: 4.13
+Contact: Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>
+Description:
+ This file can be read and write.
+ The file can show/change the drd mode of usb.
+
+ Write the following string to change the mode:
+
+ - "host" - switching mode from peripheral to host.
+ - "peripheral" - switching mode from host to peripheral.
+
+ Read the file, then it shows the following strings:
+
+ - "host" - The mode is host now.
+ - "peripheral" - The mode is peripheral now.
diff --git a/Documentation/ABI/testing/sysfs-platform-silicom b/Documentation/ABI/testing/sysfs-platform-silicom
new file mode 100644
index 000000000000..4d1cc5bdbcc5
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-silicom
@@ -0,0 +1,30 @@
+What: /sys/devices/platform/silicom-platform/uc_version
+Date: November 2023
+KernelVersion: 6.7
+Contact: Henry Shi <henrys@silicom-usa.com>
+Description:
+ This file allows to read microcontroller firmware
+ version of current platform.
+
+What: /sys/devices/platform/silicom-platform/power_cycle
+Date: November 2023
+KernelVersion: 6.7
+Contact: Henry Shi <henrys@silicom-usa.com>
+Description:
+ This file allow user to power cycle the platform.
+ Default value is 0; when set to 1, it powers down
+ the platform, waits 5 seconds, then powers on the
+ device. It returns to default value after power cycle.
+
+ 0 - default value.
+
+What: /sys/devices/platform/silicom-platform/efuse_status
+Date: November 2023
+KernelVersion: 6.7
+Contact: Henry Shi <henrys@silicom-usa.com>
+Description:
+ This file is read only. It returns the current
+ OTP status:
+
+ 0 - not programmed.
+ 1 - programmed.
diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom
new file mode 100644
index 000000000000..4bb2e6135c2e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-sst-atom
@@ -0,0 +1,26 @@
+What: /sys/devices/platform/8086<x>:00/firmware_version
+Date: November 2016
+KernelVersion: 4.10
+Contact: "Sebastien Guiriec" <sebastien.guiriec@intel.com>
+Description:
+ LPE Firmware version for SST driver on all atom
+ platforms (BYT/CHT/Merrifield/BSW).
+ If the FW has never been loaded it will display::
+
+ "FW not yet loaded"
+
+ If FW has been loaded it will display::
+
+ "v01.aa.bb.cc"
+
+ aa: Major version is reflecting SoC version:
+
+ === =============
+ 0d: BYT FW
+ 0b: BSW FW
+ 07: Merrifield FW
+ === =============
+
+ bb: Minor version
+
+ cc: Build version
diff --git a/Documentation/ABI/testing/sysfs-platform-twl4030-usb b/Documentation/ABI/testing/sysfs-platform-twl4030-usb
new file mode 100644
index 000000000000..512c51be64ae
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-twl4030-usb
@@ -0,0 +1,8 @@
+What: /sys/bus/platform/devices/*twl4030-usb/vbus
+Description:
+ Read-only status reporting if VBUS (approx 5V)
+ is being supplied by the USB bus.
+
+ Possible values: "on", "off".
+
+ Changes are notified via select/poll.
diff --git a/Documentation/ABI/testing/sysfs-platform-usbip-vudc b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
new file mode 100644
index 000000000000..53622d3ba27c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
@@ -0,0 +1,38 @@
+What: /sys/devices/platform/usbip-vudc.%d/dev_desc
+Date: April 2016
+KernelVersion: 4.6
+Contact: Krzysztof Opasiak <k.opasiak@samsung.com>
+Description:
+ This file allows to read device descriptor of
+ gadget driver which is currently bound to this
+ controller. It is possible to read this file
+ only if gadget driver is bound, otherwise error
+ is returned.
+
+What: /sys/devices/platform/usbip-vudc.%d/usbip_status
+Date: April 2016
+KernelVersion: 4.6
+Contact: Krzysztof Opasiak <k.opasiak@samsung.com>
+Description:
+ Current status of the device.
+ Allowed values:
+
+ == ==========================================
+ 1 Device is available and can be exported
+ 2 Device is currently exported
+ 3 Fatal error occurred during communication
+ with peer
+ == ==========================================
+
+What: /sys/devices/platform/usbip-vudc.%d/usbip_sockfd
+Date: April 2016
+KernelVersion: 4.6
+Contact: Krzysztof Opasiak <k.opasiak@samsung.com>
+Description:
+ This file allows to export usb device to
+ connection peer. It is done by writing to this
+ file socket fd (as a string for example "8")
+ associated with a connection to remote peer who
+ would like to use this device. It is possible to
+ close the connection by writing -1 instead of
+ socked fd.
diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec b/Documentation/ABI/testing/sysfs-platform-wilco-ec
new file mode 100644
index 000000000000..4439d0644091
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
@@ -0,0 +1,58 @@
+What: /sys/bus/platform/devices/GOOG000C\:00/boot_on_ac
+Date: April 2019
+KernelVersion: 5.3
+Description:
+ Boot on AC is a policy which makes the device boot from S5
+ when AC power is connected. This is useful for users who
+ want to run their device headless or with a dock.
+
+ Input should be parseable by kstrtou8() to 0 or 1.
+
+What: /sys/bus/platform/devices/GOOG000C\:00/build_date
+Date: May 2019
+KernelVersion: 5.3
+Description:
+ Display Wilco Embedded Controller firmware build date.
+ Output will a MM/DD/YY string.
+
+What: /sys/bus/platform/devices/GOOG000C\:00/build_revision
+Date: May 2019
+KernelVersion: 5.3
+Description:
+ Display Wilco Embedded Controller build revision.
+ Output will a version string be similar to the example below:
+ d2592cae0
+
+What: /sys/bus/platform/devices/GOOG000C\:00/model_number
+Date: May 2019
+KernelVersion: 5.3
+Description:
+ Display Wilco Embedded Controller model number.
+ Output will a version string be similar to the example below:
+ 08B6
+
+What: /sys/bus/platform/devices/GOOG000C\:00/usb_charge
+Date: October 2019
+KernelVersion: 5.5
+Description:
+ Control the USB PowerShare Policy. USB PowerShare is a policy
+ which affects charging via the special USB PowerShare port
+ (marked with a small lightning bolt or battery icon) when in
+ low power states:
+
+ - In S0, the port will always provide power.
+ - In S0ix, if usb_charge is enabled, then power will be
+ supplied to the port when on AC or if battery is > 50%.
+ Else no power is supplied.
+ - In S5, if usb_charge is enabled, then power will be supplied
+ to the port when on AC. Else no power is supplied.
+
+ Input should be either "0" or "1".
+
+What: /sys/bus/platform/devices/GOOG000C\:00/version
+Date: May 2019
+KernelVersion: 5.3
+Description:
+ Display Wilco Embedded Controller firmware version.
+ The format of the string is x.y.z. Where x is major, y is minor
+ and z is the build number. For example: 95.00.06
diff --git a/Documentation/ABI/testing/sysfs-platform_profile b/Documentation/ABI/testing/sysfs-platform_profile
new file mode 100644
index 000000000000..125324ab53a9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform_profile
@@ -0,0 +1,40 @@
+What: /sys/firmware/acpi/platform_profile_choices
+Date: October 2020
+Contact: Hans de Goede <hdegoede@redhat.com>
+Description: This file contains a space-separated list of profiles supported for this device.
+
+ Drivers must use the following standard profile-names:
+
+ ==================== ========================================
+ low-power Low power consumption
+ cool Cooler operation
+ quiet Quieter operation
+ balanced Balance between low power consumption
+ and performance
+ balanced-performance Balance between performance and low
+ power consumption with a slight bias
+ towards performance
+ performance High performance operation
+ ==================== ========================================
+
+ Userspace may expect drivers to offer more than one of these
+ standard profile names.
+
+What: /sys/firmware/acpi/platform_profile
+Date: October 2020
+Contact: Hans de Goede <hdegoede@redhat.com>
+Description: Reading this file gives the current selected profile for this
+ device. Writing this file with one of the strings from
+ platform_profile_choices changes the profile to the new value.
+
+ This file can be monitored for changes by polling for POLLPRI,
+ POLLPRI will be signalled on any changes, independent of those
+ changes coming from a userspace write; or coming from another
+ source such as e.g. a hotkey triggered profile change handled
+ either directly by the embedded-controller or fully handled
+ inside the kernel.
+
+ This file may also emit the string 'custom' to indicate
+ that multiple platform profiles drivers are in use but
+ have different values. This string can not be written to
+ this interface and is solely for informational purposes.
diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power
index f4551816329e..d38da077905a 100644
--- a/Documentation/ABI/testing/sysfs-power
+++ b/Documentation/ABI/testing/sysfs-power
@@ -1,53 +1,64 @@
What: /sys/power/
Date: August 2006
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power directory will contain files that will
provide a unified interface to the power management
subsystem.
What: /sys/power/state
-Date: May 2014
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Date: November 2016
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/state file controls system sleep states.
Reading from this file returns the available sleep state
- labels, which may be "mem", "standby", "freeze" and "disk"
- (hibernation). The meanings of the first three labels depend on
- the relative_sleep_states command line argument as follows:
- 1) relative_sleep_states = 1
- "mem", "standby", "freeze" represent non-hibernation sleep
- states from the deepest ("mem", always present) to the
- shallowest ("freeze"). "standby" and "freeze" may or may
- not be present depending on the capabilities of the
- platform. "freeze" can only be present if "standby" is
- present.
- 2) relative_sleep_states = 0 (default)
- "mem" - "suspend-to-RAM", present if supported.
- "standby" - "power-on suspend", present if supported.
- "freeze" - "suspend-to-idle", always present.
-
- Writing to this file one of these strings causes the system to
- transition into the corresponding state, if available. See
- Documentation/power/states.txt for a description of what
- "suspend-to-RAM", "power-on suspend" and "suspend-to-idle" mean.
+ labels, which may be "mem" (suspend), "standby" (power-on
+ suspend), "freeze" (suspend-to-idle) and "disk" (hibernation).
+
+ Writing one of the above strings to this file causes the system
+ to transition into the corresponding state, if available.
+
+ See Documentation/admin-guide/pm/sleep-states.rst for more
+ information.
+
+What: /sys/power/mem_sleep
+Date: November 2016
+Contact: Rafael J. Wysocki <rafael@kernel.org>
+Description:
+ The /sys/power/mem_sleep file controls the operating mode of
+ system suspend. Reading from it returns the available modes
+ as "s2idle" (always present), "shallow" and "deep" (present if
+ supported). The mode that will be used on subsequent attempts
+ to suspend the system (by writing "mem" to the /sys/power/state
+ file described above) is enclosed in square brackets.
+
+ Writing one of the above strings to this file causes the mode
+ represented by it to be used on subsequent attempts to suspend
+ the system.
+
+ See Documentation/admin-guide/pm/sleep-states.rst for more
+ information.
What: /sys/power/disk
Date: September 2006
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/disk file controls the operating mode of the
suspend-to-disk mechanism. Reading from this file returns
the name of the method by which the system will be put to
sleep on the next suspend. There are four methods supported:
+
'firmware' - means that the memory image will be saved to disk
by some firmware, in which case we also assume that the
firmware will handle the system suspend.
+
'platform' - the memory image will be saved by the kernel and
the system will be put to sleep by the platform driver (e.g.
ACPI or other PM registers).
+
'shutdown' - the memory image will be saved by the kernel and
the system will be powered off.
+
'reboot' - the memory image will be saved by the kernel and
the system will be rebooted.
@@ -67,19 +78,19 @@ Description:
The suspend-to-disk method may be chosen by writing to this
file one of the accepted strings:
- 'firmware'
- 'platform'
- 'shutdown'
- 'reboot'
- 'testproc'
- 'test'
+ - 'firmware'
+ - 'platform'
+ - 'shutdown'
+ - 'reboot'
+ - 'testproc'
+ - 'test'
It will only change to 'firmware' or 'platform' if the system
supports that.
What: /sys/power/image_size
Date: August 2006
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/image_size file controls the size of the image
created by the suspend-to-disk mechanism. It can be written a
@@ -92,11 +103,11 @@ Description:
this file, the suspend image will be as small as possible.
Reading from this file will display the current image size
- limit, which is set to 500 MB by default.
+ limit, which is set to around 2/5 of available RAM by default.
What: /sys/power/pm_trace
Date: August 2006
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/pm_trace file controls the code which saves the
last PM event point in the RTC across reboots, so that you can
@@ -107,9 +118,9 @@ Description:
string representing a nonzero integer into it.
To use this debugging feature you should attempt to suspend
- the machine, then reboot it and run
+ the machine, then reboot it and run::
- dmesg -s 1000000 | grep 'hash matches'
+ dmesg -s 1000000 | grep 'hash matches'
If you do not get any matches (or they appear to be false
positives), it is possible that the last PM event point
@@ -120,9 +131,9 @@ Description:
CAUTION: Using it will cause your machine's real-time (CMOS)
clock to be set to a random invalid time after a resume.
-What; /sys/power/pm_trace_dev_match
+What: /sys/power/pm_trace_dev_match
Date: October 2010
-Contact: James Hogan <james@albanarts.com>
+Contact: James Hogan <jhogan@kernel.org>
Description:
The /sys/power/pm_trace_dev_match file contains the name of the
device associated with the last PM event point saved in the RTC
@@ -141,11 +152,11 @@ Description:
case further investigation is required to determine which
device is causing the problem. Note that genuine RTC clock
values (such as when pm_trace has not been used), can still
- match a device and output it's name here.
+ match a device and output its name here.
What: /sys/power/pm_async
Date: January 2009
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/pm_async file controls the switch allowing the
user space to enable or disable asynchronous suspend and resume
@@ -158,7 +169,7 @@ Description:
What: /sys/power/wakeup_count
Date: July 2010
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/wakeup_count file allows user space to put the
system into a sleep state while taking into account the
@@ -173,7 +184,7 @@ Description:
What: /sys/power/reserved_size
Date: May 2011
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/reserved_size file allows user space to control
the amount of memory reserved for allocations made by device
@@ -187,7 +198,7 @@ Description:
What: /sys/power/autosleep
Date: April 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/autosleep file can be written one of the strings
returned by reads from /sys/power/state. If that happens, a
@@ -204,7 +215,7 @@ Description:
What: /sys/power/wake_lock
Date: February 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/wake_lock file allows user space to create
wakeup source objects and activate them on demand (if one of
@@ -231,12 +242,13 @@ Description:
What: /sys/power/wake_unlock
Date: February 2012
-Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
+Contact: Rafael J. Wysocki <rafael@kernel.org>
Description:
The /sys/power/wake_unlock file allows user space to deactivate
wakeup sources created with the help of /sys/power/wake_lock.
When a string is written to /sys/power/wake_unlock, it will be
assumed to represent the name of a wakeup source to deactivate.
+
If a wakeup source object of that name exists and is active at
the moment, it will be deactivated.
@@ -256,3 +268,205 @@ Description:
Writing a "1" enables this printing while writing a "0"
disables it. The default value is "0". Reading from this file
will display the current value.
+
+What: /sys/power/pm_wakeup_irq
+Date: April 2015
+Contact: Alexandra Yates <alexandra.yates@linux.intel.org>
+Description:
+ The /sys/power/pm_wakeup_irq file reports to user space the IRQ
+ number of the first wakeup interrupt (that is, the first
+ interrupt from an IRQ line armed for system wakeup) seen by the
+ kernel during the most recent system suspend/resume cycle.
+
+ This output is useful for system wakeup diagnostics of spurious
+ wakeup interrupts.
+
+What: /sys/power/pm_debug_messages
+Date: July 2017
+Contact: Rafael J. Wysocki <rafael@kernel.org>
+Description:
+ The /sys/power/pm_debug_messages file controls the printing
+ of debug messages from the system suspend/hiberbation
+ infrastructure to the kernel log.
+
+ Writing a "1" to this file enables the debug messages and
+ writing a "0" (default) to it disables them. Reads from
+ this file return the current value.
+
+What: /sys/power/resume_offset
+Date: April 2018
+Contact: Mario Limonciello <mario.limonciello@outlook.com>
+Description:
+ This file is used for telling the kernel an offset into a disk
+ to use when hibernating the system such as with a swap file.
+
+ Reads from this file will display the current offset
+ the kernel will be using on the next hibernation
+ attempt.
+
+ Using this sysfs file will override any values that were
+ set using the kernel command line for disk offset.
+
+What: /sys/power/suspend_stats
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats directory contains suspend related
+ statistics.
+
+What: /sys/power/suspend_stats/success
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/success file contains the number
+ of times entering system sleep state succeeded.
+
+What: /sys/power/suspend_stats/fail
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/fail file contains the number
+ of times entering system sleep state failed.
+
+What: /sys/power/suspend_stats/failed_freeze
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_freeze file contains the
+ number of times freezing processes failed.
+
+What: /sys/power/suspend_stats/failed_prepare
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_prepare file contains the
+ number of times preparing all non-sysdev devices for
+ a system PM transition failed.
+
+What: /sys/power/suspend_stats/failed_resume
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_resume file contains the
+ number of times executing "resume" callbacks of
+ non-sysdev devices failed.
+
+What: /sys/power/suspend_stats/failed_resume_early
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_resume_early file contains
+ the number of times executing "early resume" callbacks
+ of devices failed.
+
+What: /sys/power/suspend_stats/failed_resume_noirq
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_resume_noirq file contains
+ the number of times executing "noirq resume" callbacks
+ of devices failed.
+
+What: /sys/power/suspend_stats/failed_suspend
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_suspend file contains
+ the number of times executing "suspend" callbacks
+ of all non-sysdev devices failed.
+
+What: /sys/power/suspend_stats/failed_suspend_late
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_suspend_late file contains
+ the number of times executing "late suspend" callbacks
+ of all devices failed.
+
+What: /sys/power/suspend_stats/failed_suspend_noirq
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/failed_suspend_noirq file contains
+ the number of times executing "noirq suspend" callbacks
+ of all devices failed.
+
+What: /sys/power/suspend_stats/last_failed_dev
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/last_failed_dev file contains
+ the last device for which a suspend/resume callback failed.
+
+What: /sys/power/suspend_stats/last_failed_errno
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/last_failed_errno file contains
+ the errno of the last failed attempt at entering
+ system sleep state.
+
+What: /sys/power/suspend_stats/last_failed_step
+Date: July 2019
+Contact: Kalesh Singh <kaleshsingh96@gmail.com>
+Description:
+ The /sys/power/suspend_stats/last_failed_step file contains
+ the last failed step in the suspend/resume path.
+
+What: /sys/power/suspend_stats/last_hw_sleep
+Date: June 2023
+Contact: Mario Limonciello <mario.limonciello@amd.com>
+Description:
+ The /sys/power/suspend_stats/last_hw_sleep file
+ contains the duration of time spent in a hardware sleep
+ state in the most recent system suspend-resume cycle.
+ This number is measured in microseconds.
+
+What: /sys/power/suspend_stats/total_hw_sleep
+Date: June 2023
+Contact: Mario Limonciello <mario.limonciello@amd.com>
+Description:
+ The /sys/power/suspend_stats/total_hw_sleep file
+ contains the aggregate of time spent in a hardware sleep
+ state since the kernel was booted. This number
+ is measured in microseconds.
+
+What: /sys/power/suspend_stats/max_hw_sleep
+Date: June 2023
+Contact: Mario Limonciello <mario.limonciello@amd.com>
+Description:
+ The /sys/power/suspend_stats/max_hw_sleep file
+ contains the maximum amount of time that the hardware can
+ report for time spent in a hardware sleep state. When sleep
+ cycles are longer than this time, the values for
+ 'total_hw_sleep' and 'last_hw_sleep' may not be accurate.
+ This number is measured in microseconds.
+
+What: /sys/power/sync_on_suspend
+Date: October 2019
+Contact: Jonas Meurer <jonas@freesources.org>
+Description:
+ This file controls whether or not the kernel will sync()
+ filesystems during system suspend (after freezing user space
+ and before suspending devices).
+
+ Writing a "1" to this file enables the sync() and writing a "0"
+ disables it. Reads from the file return the current value.
+ The default is "1" if the build-time "SUSPEND_SKIP_SYNC" config
+ flag is unset, or "0" otherwise.
+
+What: /sys/power/hibernate_compression_threads
+Date: October 2025
+Contact: <luoxueqin@kylinos.cn>
+Description:
+ Controls the number of threads used for compression
+ and decompression of hibernation images.
+
+ The value can be adjusted at runtime to balance
+ performance and CPU utilization.
+
+ The change takes effect on the next hibernation or
+ resume operation.
+
+ Minimum value: 1
+ Default value: 3
diff --git a/Documentation/ABI/testing/sysfs-pps-gen b/Documentation/ABI/testing/sysfs-pps-gen
new file mode 100644
index 000000000000..2519207b88fd
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-pps-gen
@@ -0,0 +1,43 @@
+What: /sys/class/pps-gen/
+Date: February 2025
+KernelVersion: 6.13
+Contact: Rodolfo Giometti <giometti@enneenne.com>
+Description:
+ The /sys/class/pps-gen/ directory contains files and
+ directories that provide a unified interface to the PPS
+ generators.
+
+What: /sys/class/pps-gen/pps-genX/
+Date: February 2025
+KernelVersion: 6.13
+Contact: Rodolfo Giometti <giometti@enneenne.com>
+Description:
+ The /sys/class/pps-gen/pps-genX/ directory is related to X-th
+ PPS generator in the system. Each directory contain files to
+ manage and control its PPS generator.
+
+What: /sys/class/pps-gen/pps-genX/enable
+Date: February 2025
+KernelVersion: 6.13
+Contact: Rodolfo Giometti <giometti@enneenne.com>
+Description:
+ This write-only file enables or disables generation of the
+ PPS signal.
+
+What: /sys/class/pps-gen/pps-genX/system
+Date: February 2025
+KernelVersion: 6.13
+Contact: Rodolfo Giometti <giometti@enneenne.com>
+Description:
+ This read-only file returns "1" if the generator takes the
+ timing from the system clock, while it returns "0" if not
+ (i.e. from a peripheral device clock).
+
+What: /sys/class/pps-gen/pps-genX/time
+Date: February 2025
+KernelVersion: 6.13
+Contact: Rodolfo Giometti <giometti@enneenne.com>
+Description:
+ This read-only file contains the current time stored into the
+ generator clock as two integers representing the current time
+ seconds and nanoseconds.
diff --git a/Documentation/ABI/testing/sysfs-pps-gen-tio b/Documentation/ABI/testing/sysfs-pps-gen-tio
new file mode 100644
index 000000000000..3c34ff17a335
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-pps-gen-tio
@@ -0,0 +1,6 @@
+What: /sys/class/pps-gen/pps-genx/enable
+Date: April 2025
+KernelVersion: 6.15
+Contact: Subramanian Mohan<subramanian.mohan@intel.com>
+Description:
+ Enable or disable PPS TIO generator output.
diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling
index 8a8e466eb2c0..e39dd3a0ceef 100644
--- a/Documentation/ABI/testing/sysfs-profiling
+++ b/Documentation/ABI/testing/sysfs-profiling
@@ -5,7 +5,7 @@ Description:
/sys/kernel/profiling is the runtime equivalent
of the boot-time profile= option.
- You can get the same effect running:
+ You can get the same effect running::
echo 2 > /sys/kernel/profiling
diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp
index 44806a678f12..9c317ac7c47a 100644
--- a/Documentation/ABI/testing/sysfs-ptp
+++ b/Documentation/ABI/testing/sysfs-ptp
@@ -6,7 +6,7 @@ Description:
providing a standardized interface to the ancillary
features of PTP hardware clocks.
-What: /sys/class/ptp/ptpN/
+What: /sys/class/ptp/ptp<N>/
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -14,7 +14,7 @@ Description:
hardware clock registered into the PTP class driver
subsystem.
-What: /sys/class/ptp/ptpN/clock_name
+What: /sys/class/ptp/ptp<N>/clock_name
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -25,7 +25,7 @@ Description:
MAC based ones. The string does not necessarily have
to be any kind of unique id.
-What: /sys/class/ptp/ptpN/max_adjustment
+What: /sys/class/ptp/ptp<N>/max_adjustment
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -33,35 +33,55 @@ Description:
frequency adjustment value (a positive integer) in
parts per billion.
-What: /sys/class/ptp/ptpN/n_alarms
+What: /sys/class/ptp/ptp<N>/max_vclocks
+Date: May 2021
+Contact: Yangbo Lu <yangbo.lu@nxp.com>
+Description:
+ This file contains the maximum number of ptp vclocks.
+ Write integer to re-configure it.
+
+What: /sys/class/ptp/ptp<N>/n_alarms
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
This file contains the number of periodic or one shot
alarms offer by the PTP hardware clock.
-What: /sys/class/ptp/ptpN/n_external_timestamps
+What: /sys/class/ptp/ptp<N>/n_external_timestamps
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
This file contains the number of external timestamp
channels offered by the PTP hardware clock.
-What: /sys/class/ptp/ptpN/n_periodic_outputs
+What: /sys/class/ptp/ptp<N>/n_periodic_outputs
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
This file contains the number of programmable periodic
output channels offered by the PTP hardware clock.
-What: /sys/class/ptp/ptpN/n_pins
+What: /sys/class/ptp/ptp<N>/n_pins
Date: March 2014
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
This file contains the number of programmable pins
offered by the PTP hardware clock.
-What: /sys/class/ptp/ptpN/pins
+What: /sys/class/ptp/ptp<N>/n_vclocks
+Date: May 2021
+Contact: Yangbo Lu <yangbo.lu@nxp.com>
+Description:
+ This file contains the number of virtual PTP clocks in
+ use. By default, the value is 0 meaning that only the
+ physical clock is in use. Setting the value creates
+ the corresponding number of virtual clocks and causes
+ the physical clock to become free running. Setting the
+ value back to 0 deletes the virtual clocks and
+ switches the physical clock back to normal, adjustable
+ operation.
+
+What: /sys/class/ptp/ptp<N>/pins
Date: March 2014
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -69,12 +89,12 @@ Description:
pin offered by the PTP hardware clock. The file name
is the hardware dependent pin name. Reading from this
file produces two numbers, the assigned function (see
- the PTP_PF_ enumeration values in linux/ptp_clock.h)
+ the `PTP_PF_` enumeration values in linux/ptp_clock.h)
and the channel number. The function and channel
assignment may be changed by two writing numbers into
the file.
-What: /sys/class/ptp/ptpN/pps_avaiable
+What: /sys/class/ptp/ptp<N>/pps_available
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -83,7 +103,7 @@ Description:
"1" means that the PPS is supported, while "0" means
not supported.
-What: /sys/class/ptp/ptpN/extts_enable
+What: /sys/class/ptp/ptp<N>/extts_enable
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -93,7 +113,7 @@ Description:
To disable external timestamps, write the channel
index followed by a "0" into the file.
-What: /sys/class/ptp/ptpN/fifo
+What: /sys/class/ptp/ptp<N>/fifo
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -101,7 +121,7 @@ Description:
the form of three integers: channel index, seconds,
and nanoseconds.
-What: /sys/class/ptp/ptpN/period
+What: /sys/class/ptp/ptp<N>/period
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
@@ -112,7 +132,7 @@ Description:
period nanoseconds. To disable a periodic output, set
all the seconds and nanoseconds values to zero.
-What: /sys/class/ptp/ptpN/pps_enable
+What: /sys/class/ptp/ptp<N>/pps_enable
Date: September 2010
Contact: Richard Cochran <richardcochran@gmail.com>
Description:
diff --git a/Documentation/ABI/testing/sysfs-secvar b/Documentation/ABI/testing/sysfs-secvar
new file mode 100644
index 000000000000..1016967a730f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-secvar
@@ -0,0 +1,130 @@
+What: /sys/firmware/secvar
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: This directory is created if the POWER firmware supports OS
+ secureboot, thereby secure variables. It exposes interface
+ for reading/writing the secure variables
+
+What: /sys/firmware/secvar/vars
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: This directory lists all the secure variables that are supported
+ by the firmware.
+
+What: /sys/firmware/secvar/format
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: A string indicating which backend is in use by the firmware.
+ This determines the format of the variable and the accepted
+ format of variable updates.
+
+ On powernv/OPAL, this value is provided by the OPAL firmware
+ and is expected to be "ibm,edk2-compat-v1".
+
+ On pseries/PLPKS, this is generated by the kernel based on the
+ version number in the SB_VERSION variable in the keystore. The
+ version numbering in the SB_VERSION variable starts from 1. The
+ format string takes the form "ibm,plpks-sb-v<version>" in the
+ case of dynamic key management mode. If the SB_VERSION variable
+ does not exist (or there is an error while reading it), it takes
+ the form "ibm,plpks-sb-v0", indicating that the key management
+ mode is static.
+
+What: /sys/firmware/secvar/vars/<variable name>
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Each secure variable is represented as a directory named as
+ <variable_name>. The variable name is unique and is in ASCII
+ representation. The data and size can be determined by reading
+ their respective attribute files.
+
+ Only secvars relevant to the key management mode are exposed.
+ Only in the dynamic key management mode should the user have
+ access (read and write) to the secure boot secvars db, dbx,
+ grubdb, grubdbx, and sbat. These secvars are not consumed in the
+ static key management mode. PK, trustedcadb and moduledb are the
+ secvars common to both static and dynamic key management modes.
+
+What: /sys/firmware/secvar/vars/<variable_name>/size
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: An integer representation of the size of the content of the
+ variable. In other words, it represents the size of the data.
+
+What: /sys/firmware/secvar/vars/<variable_name>/data
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: A read-only file containing the value of the variable. The size
+ of the file represents the maximum size of the variable data.
+
+What: /sys/firmware/secvar/vars/<variable_name>/update
+Date: August 2019
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: A write-only file that is used to submit the new value for the
+ variable. The size of the file represents the maximum size of
+ the variable data that can be written.
+
+What: /sys/firmware/secvar/config
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: This optional directory contains read-only config attributes as
+ defined by the secure variable implementation. All data is in
+ ASCII format. The directory is only created if the backing
+ implementation provides variables to populate it, which at
+ present is only PLPKS on the pseries platform.
+
+What: /sys/firmware/secvar/config/version
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Config version as reported by the hypervisor in ASCII decimal
+ format.
+
+ Currently only provided by PLPKS on the pseries platform.
+
+What: /sys/firmware/secvar/config/max_object_size
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Maximum allowed size of objects in the keystore in bytes,
+ represented in ASCII decimal format.
+
+ This is not necessarily the same as the max size that can be
+ written to an update file as writes can contain more than
+ object data, you should use the size of the update file for
+ that purpose.
+
+ Currently only provided by PLPKS on the pseries platform.
+
+What: /sys/firmware/secvar/config/total_size
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Total size of the PLPKS in bytes, represented in ASCII decimal
+ format.
+
+ Currently only provided by PLPKS on the pseries platform.
+
+What: /sys/firmware/secvar/config/used_space
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Current space consumed by the key store, in bytes, represented
+ in ASCII decimal format.
+
+ Currently only provided by PLPKS on the pseries platform.
+
+What: /sys/firmware/secvar/config/supported_policies
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Bitmask of supported policy flags by the hypervisor,
+ represented as an 8 byte hexadecimal ASCII string. Consult the
+ hypervisor documentation for what these flags are.
+
+ Currently only provided by PLPKS on the pseries platform.
+
+What: /sys/firmware/secvar/config/signed_update_algorithms
+Date: February 2023
+Contact: Nayna Jain <nayna@linux.ibm.com>
+Description: Bitmask of flags indicating which algorithms the hypervisor
+ supports for signed update of objects, represented as a 16 byte
+ hexadecimal ASCII string. Consult the hypervisor documentation
+ for what these flags mean.
+
+ Currently only provided by PLPKS on the pseries platform.
diff --git a/Documentation/ABI/testing/sysfs-timecard b/Documentation/ABI/testing/sysfs-timecard
new file mode 100644
index 000000000000..3ae41b7634ac
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-timecard
@@ -0,0 +1,293 @@
+What: /sys/class/timecard/
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: This directory contains files and directories
+ providing a standardized interface to the ancillary
+ features of the OpenCompute timecard.
+
+What: /sys/class/timecard/ocpN/
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: This directory contains the attributes of the Nth timecard
+ registered.
+
+What: /sys/class/timecard/ocpN/available_clock_sources
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) The list of available time sources that the PHC
+ uses for clock adjustments.
+
+ ==== =================================================
+ NONE no adjustments
+ PPS adjustments come from the PPS1 selector (default)
+ TOD adjustments from the GNSS/TOD module
+ IRIG adjustments from external IRIG-B signal
+ DCF adjustments from external DCF signal
+ ==== =================================================
+
+What: /sys/class/timecard/ocpN/available_sma_inputs
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Set of available destinations (sinks) for a SMA
+ input signal.
+
+ ===== ================================================
+ 10Mhz signal is used as the 10Mhz reference clock
+ PPS1 signal is sent to the PPS1 selector
+ PPS2 signal is sent to the PPS2 selector
+ TS1 signal is sent to timestamper 1
+ TS2 signal is sent to timestamper 2
+ TS3 signal is sent to timestamper 3
+ TS4 signal is sent to timestamper 4
+ IRIG signal is sent to the IRIG-B module
+ DCF signal is sent to the DCF module
+ FREQ1 signal is sent to frequency counter 1
+ FREQ2 signal is sent to frequency counter 2
+ FREQ3 signal is sent to frequency counter 3
+ FREQ4 signal is sent to frequency counter 4
+ None signal input is disabled
+ ===== ================================================
+
+What: /sys/class/timecard/ocpN/available_sma_outputs
+Date: May 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Set of available sources for a SMA output signal.
+
+ ===== ================================================
+ 10Mhz output is from the 10Mhz reference clock
+ PHC output PPS is from the PHC clock
+ MAC output PPS is from the Miniature Atomic Clock
+ GNSS1 output PPS is from the first GNSS module
+ GNSS2 output PPS is from the second GNSS module
+ IRIG output is from the PHC, in IRIG-B format
+ DCF output is from the PHC, in DCF format
+ GEN1 output is from frequency generator 1
+ GEN2 output is from frequency generator 2
+ GEN3 output is from frequency generator 3
+ GEN4 output is from frequency generator 4
+ GND output is GND
+ VCC output is VCC
+ ===== ================================================
+
+What: /sys/class/timecard/ocpN/clock_source
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) Contains the current synchronization source used by
+ the PHC. May be changed by writing one of the listed
+ values from the available_clock_sources attribute set.
+
+What: /sys/class/timecard/ocpN/clock_status_drift
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Contains the current drift value used by the firmware
+ for internal disciplining of the atomic clock.
+
+What: /sys/class/timecard/ocpN/clock_status_offset
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Contains the current offset value used by the firmware
+ for internal disciplining of the atomic clock.
+
+What: /sys/class/timecard/ocpN/freqX
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Optional directory containing the sysfs nodes for
+ frequency counter <X>.
+
+What: /sys/class/timecard/ocpN/freqX/frequency
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Contains the measured frequency over the specified
+ measurement period.
+
+What: /sys/class/timecard/ocpN/freqX/seconds
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) Specifies the number of seconds from 0-255 that the
+ frequency should be measured over. Write 0 to disable.
+
+What: /sys/class/timecard/ocpN/genX
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Optional directory containing the sysfs nodes for
+ frequency generator <X>.
+
+What: /sys/class/timecard/ocpN/genX/duty
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Specifies the signal duty cycle as a percentage from 1-99.
+
+What: /sys/class/timecard/ocpN/genX/period
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Specifies the signal period in nanoseconds.
+
+What: /sys/class/timecard/ocpN/genX/phase
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Specifies the signal phase offset in nanoseconds.
+
+What: /sys/class/timecard/ocpN/genX/polarity
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Specifies the signal polarity, either 1 or 0.
+
+What: /sys/class/timecard/ocpN/genX/running
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Either 0 or 1, showing if the signal generator is running.
+
+What: /sys/class/timecard/ocpN/genX/start
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Shows the time in <sec>.<nsec> that the signal generator
+ started running.
+
+What: /sys/class/timecard/ocpN/genX/signal
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) Used to start the signal generator, and summarize
+ the current status.
+
+ The signal generator may be started by writing the signal
+ period, followed by the optional signal values. If the
+ optional values are not provided, they default to the current
+ settings, which may be obtained from the other sysfs nodes.
+
+ period [duty [phase [polarity]]]
+
+ echo 500000000 > signal # 1/2 second period
+ echo 1000000 40 100 > signal
+ echo 0 > signal # turn off generator
+
+ Period and phase are specified in nanoseconds. Duty cycle is
+ a percentage from 1-99. Polarity is 1 or 0.
+
+ Reading this node will return:
+
+ period duty phase polarity start_time
+
+What: /sys/class/timecard/ocpN/gnss_sync
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Indicates whether a valid GNSS signal is received,
+ or when the signal was lost.
+
+What: /sys/class/timecard/ocpN/i2c
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: This optional attribute links to the associated i2c device.
+
+What: /sys/class/timecard/ocpN/irig_b_mode
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) An integer from 0-7 indicating the timecode format
+ of the IRIG-B output signal: B00<n>
+
+What: /sys/class/timecard/ocpN/pps
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: This optional attribute links to the associated PPS device.
+
+What: /sys/class/timecard/ocpN/ptp
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: This attribute links to the associated PTP device.
+
+What: /sys/class/timecard/ocpN/serialnum
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) Provides the serial number of the timecard.
+
+What: /sys/class/timecard/ocpN/sma1
+What: /sys/class/timecard/ocpN/sma2
+What: /sys/class/timecard/ocpN/sma3
+What: /sys/class/timecard/ocpN/sma4
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) These attributes specify the direction of the signal
+ on the associated SMA connectors, and also the signal sink
+ or source.
+
+ The display format of the attribute is a space separated
+ list of signals, prefixed by the input/output direction.
+
+ The signal direction may be changed (if supported) by
+ prefixing the signal list with either "in:" or "out:".
+ If neither prefix is present, then the direction is unchanged.
+
+ The output signal may be changed by writing one of the listed
+ values from the available_sma_outputs attribute set.
+
+ The input destinations may be changed by writing multiple
+ values from the available_sma_inputs attribute set,
+ separated by spaces. If there are duplicated input
+ destinations between connectors, the lowest numbered SMA
+ connector is given priority.
+
+ Note that not all input combinations may make sense.
+
+ The 10Mhz reference clock input is currently only valid
+ on SMA1 and may not be combined with other destination sinks.
+
+What: /sys/class/timecard/ocpN/tod_correction
+Date: March 2022
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) The incoming GNSS signal is in UTC time, and the NMEA
+ format messages do not provide a TAI offset. This sets the
+ correction value for the incoming time.
+
+ If UBX_LS is enabled, this should be 0, and the offset is
+ taken from the UBX-NAV-TIMELS message.
+
+What: /sys/class/timecard/ocpN/ts_window_adjust
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) When retrieving the PHC with the PTP SYS_OFFSET_EXTENDED
+ ioctl, a system timestamp is made before and after the PHC
+ time is retrieved. The midpoint between the two system
+ timestamps is usually taken to be the SYS time associated
+ with the PHC time. This estimate may be wrong, as it depends
+ on PCI latencies, and when the PHC time was latched
+
+ The attribute value reduces the end timestamp by the given
+ number of nanoseconds, so the computed midpoint matches the
+ retrieved PHC time.
+
+ The initial value is set based on measured PCI latency and
+ the estimated point where the FPGA latches the PHC time. This
+ value may be changed by writing an unsigned integer.
+
+What: /sys/class/timecard/ocpN/tty
+Date: August 2024
+Contact: Vadim Fedorenko <vadim.fedorenko@linux.dev>
+Description: (RO) Directory containing the sysfs nodes for TTY attributes
+
+What: /sys/class/timecard/ocpN/tty/ttyGNSS
+What: /sys/class/timecard/ocpN/tty/ttyGNSS2
+Date: August 2024
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) These optional attributes contain names of the TTY serial
+ ports associated with the GNSS devices.
+
+What: /sys/class/timecard/ocpN/tty/ttyMAC
+Date: August 2024
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) This optional attribute contains name of the TTY serial
+ port associated with the Miniature Atomic Clock.
+
+What: /sys/class/timecard/ocpN/tty/ttyNMEA
+Date: August 2024
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RO) This optional attribute contains name of the TTY serial
+ port which outputs the PHC time in NMEA ZDA format.
+
+What: /sys/class/timecard/ocpN/utc_tai_offset
+Date: September 2021
+Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
+Description: (RW) The DCF and IRIG output signals are in UTC, while the
+ TimeCard operates on TAI. This attribute allows setting the
+ offset in seconds, which is added to the TAI timebase for
+ these formats.
+
+ The offset may be changed by writing an unsigned integer.
diff --git a/Documentation/ABI/testing/sysfs-tty b/Documentation/ABI/testing/sysfs-tty
index 9eb3c2b6b040..895c47f05f6f 100644
--- a/Documentation/ABI/testing/sysfs-tty
+++ b/Documentation/ABI/testing/sysfs-tty
@@ -9,7 +9,7 @@ Description:
The file supports poll() to detect virtual
console switches.
-What: /sys/class/tty/tty0/active
+What: /sys/class/tty/tty<x>/active
Date: Nov 2010
Contact: Kay Sievers <kay.sievers@vrfy.org>
Description:
@@ -18,7 +18,7 @@ Description:
The file supports poll() to detect virtual
console switches.
-What: /sys/class/tty/ttyS0/uartclk
+What: /sys/class/tty/ttyS<x>/uartclk
Date: Sep 2012
Contact: Tomas Hlavacek <tmshlvck@gmail.com>
Description:
@@ -29,7 +29,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/type
+What: /sys/class/tty/ttyS<x>/type
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -38,7 +38,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/line
+What: /sys/class/tty/ttyS<x>/line
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -47,7 +47,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/port
+What: /sys/class/tty/ttyS<x>/port
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -56,7 +56,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/irq
+What: /sys/class/tty/ttyS<x>/irq
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -65,7 +65,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/flags
+What: /sys/class/tty/ttyS<x>/flags
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -74,7 +74,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/xmit_fifo_size
+What: /sys/class/tty/ttyS<x>/xmit_fifo_size
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -83,25 +83,28 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/close_delay
+What: /sys/class/tty/ttyS<x>/close_delay
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
- Show the closing delay time for this port in ms.
+ Show the closing delay time for this port in centiseconds.
- These sysfs values expose the TIOCGSERIAL interface via
- sysfs rather than via ioctls.
+ These sysfs values expose the TIOCGSERIAL interface via
+ sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/closing_wait
+What: /sys/class/tty/ttyS<x>/closing_wait
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
- Show the close wait time for this port in ms.
+ Show the close wait time for this port in centiseconds.
- These sysfs values expose the TIOCGSERIAL interface via
- sysfs rather than via ioctls.
+ Waiting forever is represented as 0. If waiting on close is
+ disabled then the value is 65535.
-What: /sys/class/tty/ttyS0/custom_divisor
+ These sysfs values expose the TIOCGSERIAL interface via
+ sysfs rather than via ioctls.
+
+What: /sys/class/tty/ttyS<x>/custom_divisor
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -110,7 +113,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/io_type
+What: /sys/class/tty/ttyS<x>/io_type
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -120,7 +123,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/iomem_base
+What: /sys/class/tty/ttyS<x>/iomem_base
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -129,7 +132,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/iomem_reg_shift
+What: /sys/class/tty/ttyS<x>/iomem_reg_shift
Date: October 2012
Contact: Alan Cox <alan@linux.intel.com>
Description:
@@ -139,7 +142,7 @@ Description:
These sysfs values expose the TIOCGSERIAL interface via
sysfs rather than via ioctls.
-What: /sys/class/tty/ttyS0/rx_trig_bytes
+What: /sys/class/tty/ttyS<x>/rx_trig_bytes
Date: May 2014
Contact: Yoshihiro YUNOMAE <yoshihiro.yunomae.ez@hitachi.com>
Description:
@@ -154,3 +157,10 @@ Description:
device specification. For example, when user sets 7bytes on
16550A, which has 1/4/8/14 bytes trigger, the RX trigger is
automatically changed to 4 bytes.
+
+What: /sys/class/tty/ttyS<x>/console
+Date: February 2020
+Contact: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
+Description:
+ Allows user to detach or attach back the given device as
+ kernel console. It shows and accepts a boolean variable.
diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
new file mode 100644
index 000000000000..0b6227706b35
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -0,0 +1,51 @@
+What: /sys/.../uevent
+Date: May 2017
+KernelVersion: 4.13
+Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+ Enable passing additional variables for synthetic uevents that
+ are generated by writing /sys/.../uevent file.
+
+ Recognized extended format is::
+
+ ACTION [UUID [KEY=VALUE ...]
+
+ The ACTION is compulsory - it is the name of the uevent
+ action (``add``, ``change``, ``remove``). There is no change
+ compared to previous functionality here. The rest of the
+ extended format is optional.
+
+ You need to pass UUID first before any KEY=VALUE pairs.
+ The UUID must be in ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
+ format where 'x' is a hex digit. The UUID is considered to be
+ a transaction identifier so it's possible to use the same UUID
+ value for one or more synthetic uevents in which case we
+ logically group these uevents together for any userspace
+ listeners. The UUID value appears in uevent as
+ ``SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` environment
+ variable.
+
+ If UUID is not passed in, the generated synthetic uevent gains
+ ``SYNTH_UUID=0`` environment variable automatically.
+
+ The KEY=VALUE pairs can contain alphanumeric characters only.
+
+ It's possible to define zero or more pairs - each pair is then
+ delimited by a space character ' '. Each pair appears in
+ synthetic uevent as ``SYNTH_ARG_KEY=VALUE``. That means the KEY
+ name gains ``SYNTH_ARG_`` prefix to avoid possible collisions
+ with existing variables.
+
+ Example of valid sequence written to the uevent file::
+
+ add fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed A=1 B=abc
+
+ This generates synthetic uevent including these variables::
+
+ ACTION=add
+ SYNTH_ARG_A=1
+ SYNTH_ARG_B=abc
+ SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed
+
+Users:
+ udev, userspace tools generating synthetic uevents
diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf
deleted file mode 100644
index a99c5f86a37a..000000000000
--- a/Documentation/ABI/testing/sysfs-wusb_cbaf
+++ /dev/null
@@ -1,100 +0,0 @@
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_*
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- Various files for managing Cable Based Association of
- (wireless) USB devices.
-
- The sequence of operations should be:
-
- 1. Device is plugged in.
-
- 2. The connection manager (CM) sees a device with CBA capability.
- (the wusb_chid etc. files in /sys/devices/blah/OURDEVICE).
-
- 3. The CM writes the host name, supported band groups,
- and the CHID (host ID) into the wusb_host_name,
- wusb_host_band_groups and wusb_chid files. These
- get sent to the device and the CDID (if any) for
- this host is requested.
-
- 4. The CM can verify that the device's supported band
- groups (wusb_device_band_groups) are compatible
- with the host.
-
- 5. The CM reads the wusb_cdid file.
-
- 6. The CM looks it up its database.
-
- - If it has a matching CHID,CDID entry, the device
- has been authorized before and nothing further
- needs to be done.
-
- - If the CDID is zero (or the CM doesn't find a
- matching CDID in its database), the device is
- assumed to be not known. The CM may associate
- the host with device by: writing a randomly
- generated CDID to wusb_cdid and then a random CK
- to wusb_ck (this uploads the new CC to the
- device).
-
- CMD may choose to prompt the user before
- associating with a new device.
-
- 7. Device is unplugged.
-
- References:
- [WUSB-AM] Association Models Supplement to the
- Certified Wireless Universal Serial Bus
- Specification, version 1.0.
-
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_chid
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The CHID of the host formatted as 16 space-separated
- hex octets.
-
- Writes fetches device's supported band groups and the
- the CDID for any existing association with this host.
-
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_name
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- A friendly name for the host as a UTF-8 encoded string.
-
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_band_groups
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The band groups supported by the host, in the format
- defined in [WUSB-AM].
-
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_device_band_groups
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The band groups supported by the device, in the format
- defined in [WUSB-AM].
-
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_cdid
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- The device's CDID formatted as 16 space-separated hex
- octets.
-
-What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_ck
-Date: August 2008
-KernelVersion: 2.6.27
-Contact: David Vrabel <david.vrabel@csr.com>
-Description:
- Write 16 space-separated random, hex octets to
- associate with the device.
diff --git a/Documentation/ABI/testing/usb-charger-uevent b/Documentation/ABI/testing/usb-charger-uevent
new file mode 100644
index 000000000000..1db89b0cf80f
--- /dev/null
+++ b/Documentation/ABI/testing/usb-charger-uevent
@@ -0,0 +1,54 @@
+What: Raise a uevent when a USB charger is inserted or removed
+Date: 2020-01-14
+KernelVersion: 5.6
+Contact: linux-usb@vger.kernel.org
+Description: There are two USB charger states:
+
+ - USB_CHARGER_ABSENT
+ - USB_CHARGER_PRESENT
+
+ There are five USB charger types:
+
+ ======================== ==========================
+ USB_CHARGER_UNKNOWN_TYPE Charger type is unknown
+ USB_CHARGER_SDP_TYPE Standard Downstream Port
+ USB_CHARGER_CDP_TYPE Charging Downstream Port
+ USB_CHARGER_DCP_TYPE Dedicated Charging Port
+ USB_CHARGER_ACA_TYPE Accessory Charging Adapter
+ ======================== ==========================
+
+ https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement
+
+ Here are two examples taken using ``udevadm monitor -p`` when
+ USB charger is online::
+
+ UDEV change /devices/soc0/usbphynop1 (platform)
+ ACTION=change
+ DEVPATH=/devices/soc0/usbphynop1
+ DRIVER=usb_phy_generic
+ MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
+ OF_COMPATIBLE_0=usb-nop-xceiv
+ OF_COMPATIBLE_N=1
+ OF_FULLNAME=/usbphynop1
+ OF_NAME=usbphynop1
+ SEQNUM=2493
+ SUBSYSTEM=platform
+ USB_CHARGER_STATE=USB_CHARGER_PRESENT
+ USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE
+ USEC_INITIALIZED=227422826
+
+ USB charger is offline::
+
+ KERNEL change /devices/soc0/usbphynop1 (platform)
+ ACTION=change
+ DEVPATH=/devices/soc0/usbphynop1
+ DRIVER=usb_phy_generic
+ MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
+ OF_COMPATIBLE_0=usb-nop-xceiv
+ OF_COMPATIBLE_N=1
+ OF_FULLNAME=/usbphynop1
+ OF_NAME=usbphynop1
+ SEQNUM=2494
+ SUBSYSTEM=platform
+ USB_CHARGER_STATE=USB_CHARGER_ABSENT
+ USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE
diff --git a/Documentation/ABI/testing/usb-uevent b/Documentation/ABI/testing/usb-uevent
new file mode 100644
index 000000000000..2b8eca4bf2b1
--- /dev/null
+++ b/Documentation/ABI/testing/usb-uevent
@@ -0,0 +1,27 @@
+What: Raise a uevent when a USB Host Controller has died
+Date: 2019-04-17
+KernelVersion: 5.2
+Contact: linux-usb@vger.kernel.org
+Description: When the USB Host Controller has entered a state where it is no
+ longer functional a uevent will be raised. The uevent will
+ contain ACTION=offline and ERROR=DEAD.
+
+ Here is an example taken using udevadm monitor -p::
+
+ KERNEL[130.428945] offline /devices/pci0000:00/0000:00:10.0/usb2 (usb)
+ ACTION=offline
+ BUSNUM=002
+ DEVNAME=/dev/bus/usb/002/001
+ DEVNUM=001
+ DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2
+ DEVTYPE=usb_device
+ DRIVER=usb
+ ERROR=DEAD
+ MAJOR=189
+ MINOR=128
+ PRODUCT=1d6b/2/414
+ SEQNUM=2168
+ SUBSYSTEM=usb
+ TYPE=9/0/1
+
+Users: chromium-os-dev@chromium.org
diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING
deleted file mode 100644
index 65022a87bf17..000000000000
--- a/Documentation/BUG-HUNTING
+++ /dev/null
@@ -1,246 +0,0 @@
-Table of contents
-=================
-
-Last updated: 20 December 2005
-
-Contents
-========
-
-- Introduction
-- Devices not appearing
-- Finding patch that caused a bug
--- Finding using git-bisect
--- Finding it the old way
-- Fixing the bug
-
-Introduction
-============
-
-Always try the latest kernel from kernel.org and build from source. If you are
-not confident in doing that please report the bug to your distribution vendor
-instead of to a kernel developer.
-
-Finding bugs is not always easy. Have a go though. If you can't find it don't
-give up. Report as much as you have found to the relevant maintainer. See
-MAINTAINERS for who that is for the subsystem you have worked on.
-
-Before you submit a bug report read REPORTING-BUGS.
-
-Devices not appearing
-=====================
-
-Often this is caused by udev. Check that first before blaming it on the
-kernel.
-
-Finding patch that caused a bug
-===============================
-
-
-
-Finding using git-bisect
-------------------------
-
-Using the provided tools with git makes finding bugs easy provided the bug is
-reproducible.
-
-Steps to do it:
-- start using git for the kernel source
-- read the man page for git-bisect
-- have fun
-
-Finding it the old way
-----------------------
-
-[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)]
-
-This is how to track down a bug if you know nothing about kernel hacking.
-It's a brute force approach but it works pretty well.
-
-You need:
-
- . A reproducible bug - it has to happen predictably (sorry)
- . All the kernel tar files from a revision that worked to the
- revision that doesn't
-
-You will then do:
-
- . Rebuild a revision that you believe works, install, and verify that.
- . Do a binary search over the kernels to figure out which one
- introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but
- you know that 1.3.69 does. Pick a kernel in the middle and build
- that, like 1.3.50. Build & test; if it works, pick the mid point
- between .50 and .69, else the mid point between .28 and .50.
- . You'll narrow it down to the kernel that introduced the bug. You
- can probably do better than this but it gets tricky.
-
- . Narrow it down to a subdirectory
-
- - Copy kernel that works into "test". Let's say that 3.62 works,
- but 3.63 doesn't. So you diff -r those two kernels and come
- up with a list of directories that changed. For each of those
- directories:
-
- Copy the non-working directory next to the working directory
- as "dir.63".
- One directory at time, try moving the working directory to
- "dir.62" and mv dir.63 dir"time, try
-
- mv dir dir.62
- mv dir.63 dir
- find dir -name '*.[oa]' -print | xargs rm -f
-
- And then rebuild and retest. Assuming that all related
- changes were contained in the sub directory, this should
- isolate the change to a directory.
-
- Problems: changes in header files may have occurred; I've
- found in my case that they were self explanatory - you may
- or may not want to give up when that happens.
-
- . Narrow it down to a file
-
- - You can apply the same technique to each file in the directory,
- hoping that the changes in that file are self contained.
-
- . Narrow it down to a routine
-
- - You can take the old file and the new file and manually create
- a merged file that has
-
- #ifdef VER62
- routine()
- {
- ...
- }
- #else
- routine()
- {
- ...
- }
- #endif
-
- And then walk through that file, one routine at a time and
- prefix it with
-
- #define VER62
- /* both routines here */
- #undef VER62
-
- Then recompile, retest, move the ifdefs until you find the one
- that makes the difference.
-
-Finally, you take all the info that you have, kernel revisions, bug
-description, the extent to which you have narrowed it down, and pass
-that off to whomever you believe is the maintainer of that section.
-A post to linux.dev.kernel isn't such a bad idea if you've done some
-work to narrow it down.
-
-If you get it down to a routine, you'll probably get a fix in 24 hours.
-
-My apologies to Linus and the other kernel hackers for describing this
-brute force approach, it's hardly what a kernel hacker would do. However,
-it does work and it lets non-hackers help fix bugs. And it is cool
-because Linux snapshots will let you do this - something that you can't
-do with vendor supplied releases.
-
-Fixing the bug
-==============
-
-Nobody is going to tell you how to fix bugs. Seriously. You need to work it
-out. But below are some hints on how to use the tools.
-
-To debug a kernel, use objdump and look for the hex offset from the crash
-output to find the valid line of code/assembler. Without debug symbols, you
-will see the assembler code for the routine shown, but if your kernel has
-debug symbols the C code will also be available. (Debug symbols can be enabled
-in the kernel hacking menu of the menu configuration.) For example:
-
- objdump -r -S -l --disassemble net/dccp/ipv4.o
-
-NB.: you need to be at the top level of the kernel tree for this to pick up
-your C files.
-
-If you don't have access to the code you can also debug on some crash dumps
-e.g. crash dump output as shown by Dave Miller.
-
-> EIP is at ip_queue_xmit+0x14/0x4c0
-> ...
-> Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
-> 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
-> <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
->
-> Put the bytes into a "foo.s" file like this:
->
-> .text
-> .globl foo
-> foo:
-> .byte .... /* bytes from Code: part of OOPS dump */
->
-> Compile it with "gcc -c -o foo.o foo.s" then look at the output of
-> "objdump --disassemble foo.o".
->
-> Output:
->
-> ip_queue_xmit:
-> push %ebp
-> push %edi
-> push %esi
-> push %ebx
-> sub $0xbc, %esp
-> mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
-> mov 0x8(%ebp), %ebx ! %ebx = skb->sk
-> mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
-
-In addition, you can use GDB to figure out the exact file and line
-number of the OOPS from the vmlinux file. If you have
-CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the
-OOPS:
-
- EIP: 0060:[<c021e50e>] Not tainted VLI
-
-And use GDB to translate that to human-readable form:
-
- gdb vmlinux
- (gdb) l *0xc021e50e
-
-If you don't have CONFIG_DEBUG_INFO enabled, you use the function
-offset from the OOPS:
-
- EIP is at vt_ioctl+0xda8/0x1482
-
-And recompile the kernel with CONFIG_DEBUG_INFO enabled:
-
- make vmlinux
- gdb vmlinux
- (gdb) p vt_ioctl
- (gdb) l *(0x<address of vt_ioctl> + 0xda8)
-or, as one command
- (gdb) l *(vt_ioctl + 0xda8)
-
-If you have a call trace, such as :-
->Call Trace:
-> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
-> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
-> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
-> ...
-this shows the problem in the :jbd: module. You can load that module in gdb
-and list the relevant code.
- gdb fs/jbd/jbd.ko
- (gdb) p log_wait_commit
- (gdb) l *(0x<address> + 0xa3)
-or
- (gdb) l *(log_wait_commit + 0xa3)
-
-
-Another very useful option of the Kernel Hacking section in menuconfig is
-Debug memory allocations. This will help you see whether data has been
-initialised and not set before use etc. To see the values that get assigned
-with this look at mm/slab.c and search for POISON_INUSE. When using this an
-Oops will often show the poisoned data instead of zero which is the default.
-
-Once you have worked out a fix please submit it upstream. After all open
-source is about sharing what you do and don't you want to be recognised for
-your genius?
-
-Please do read Documentation/SubmittingPatches though to help your code get
-accepted.
diff --git a/Documentation/Changes b/Documentation/Changes
index 646cdaa6e9d1..7564ae1682ba 100644..120000
--- a/Documentation/Changes
+++ b/Documentation/Changes
@@ -1,395 +1 @@
-Intro
-=====
-
-This document is designed to provide a list of the minimum levels of
-software necessary to run the 3.0 kernels.
-
-This document is originally based on my "Changes" file for 2.0.x kernels
-and therefore owes credit to the same people as that file (Jared Mauch,
-Axel Boldt, Alessandro Sigala, and countless other users all over the
-'net).
-
-Current Minimal Requirements
-============================
-
-Upgrade to at *least* these software revisions before thinking you've
-encountered a bug! If you're unsure what version you're currently
-running, the suggested command should tell you.
-
-Again, keep in mind that this list assumes you are already functionally
-running a Linux kernel. Also, not all tools are necessary on all
-systems; obviously, if you don't have any ISDN hardware, for example,
-you probably needn't concern yourself with isdn4k-utils.
-
-o GNU C 3.2 # gcc --version
-o GNU make 3.80 # make --version
-o binutils 2.12 # ld -v
-o util-linux 2.10o # fdformat --version
-o module-init-tools 0.9.10 # depmod -V
-o e2fsprogs 1.41.4 # e2fsck -V
-o jfsutils 1.1.3 # fsck.jfs -V
-o reiserfsprogs 3.6.3 # reiserfsck -V
-o xfsprogs 2.6.0 # xfs_db -V
-o squashfs-tools 4.0 # mksquashfs -version
-o btrfs-progs 0.18 # btrfsck
-o pcmciautils 004 # pccardctl -V
-o quota-tools 3.09 # quota -V
-o PPP 2.4.0 # pppd --version
-o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version
-o nfs-utils 1.0.5 # showmount --version
-o procps 3.2.0 # ps --version
-o oprofile 0.9 # oprofiled --version
-o udev 081 # udevd --version
-o grub 0.93 # grub --version || grub-install --version
-o mcelog 0.6 # mcelog --version
-o iptables 1.4.2 # iptables -V
-
-
-Kernel compilation
-==================
-
-GCC
----
-
-The gcc version requirements may vary depending on the type of CPU in your
-computer.
-
-Make
-----
-
-You will need GNU make 3.80 or later to build the kernel.
-
-Binutils
---------
-
-Linux on IA-32 has recently switched from using as86 to using gas for
-assembling the 16-bit boot code, removing the need for as86 to compile
-your kernel. This change does, however, mean that you need a recent
-release of binutils.
-
-Perl
-----
-
-You will need perl 5 and the following modules: Getopt::Long, Getopt::Std,
-File::Basename, and File::Find to build the kernel.
-
-BC
---
-
-You will need bc to build kernels 3.10 and higher
-
-
-System utilities
-================
-
-Architectural changes
----------------------
-
-DevFS has been obsoleted in favour of udev
-(http://www.kernel.org/pub/linux/utils/kernel/hotplug/)
-
-32-bit UID support is now in place. Have fun!
-
-Linux documentation for functions is transitioning to inline
-documentation via specially-formatted comments near their
-definitions in the source. These comments can be combined with the
-SGML templates in the Documentation/DocBook directory to make DocBook
-files, which can then be converted by DocBook stylesheets to PostScript,
-HTML, PDF files, and several other formats. In order to convert from
-DocBook format to a format of your choice, you'll need to install Jade as
-well as the desired DocBook stylesheets.
-
-Util-linux
-----------
-
-New versions of util-linux provide *fdisk support for larger disks,
-support new options to mount, recognize more supported partition
-types, have a fdformat which works with 2.4 kernels, and similar goodies.
-You'll probably want to upgrade.
-
-Ksymoops
---------
-
-If the unthinkable happens and your kernel oopses, you may need the
-ksymoops tool to decode it, but in most cases you don't.
-It is generally preferred to build the kernel with CONFIG_KALLSYMS so
-that it produces readable dumps that can be used as-is (this also
-produces better output than ksymoops). If for some reason your kernel
-is not build with CONFIG_KALLSYMS and you have no way to rebuild and
-reproduce the Oops with that option, then you can still decode that Oops
-with ksymoops.
-
-Module-Init-Tools
------------------
-
-A new module loader is now in the kernel that requires module-init-tools
-to use. It is backward compatible with the 2.4.x series kernels.
-
-Mkinitrd
---------
-
-These changes to the /lib/modules file tree layout also require that
-mkinitrd be upgraded.
-
-E2fsprogs
----------
-
-The latest version of e2fsprogs fixes several bugs in fsck and
-debugfs. Obviously, it's a good idea to upgrade.
-
-JFSutils
---------
-
-The jfsutils package contains the utilities for the file system.
-The following utilities are available:
-o fsck.jfs - initiate replay of the transaction log, and check
- and repair a JFS formatted partition.
-o mkfs.jfs - create a JFS formatted partition.
-o other file system utilities are also available in this package.
-
-Reiserfsprogs
--------------
-
-The reiserfsprogs package should be used for reiserfs-3.6.x
-(Linux kernels 2.4.x). It is a combined package and contains working
-versions of mkreiserfs, resize_reiserfs, debugreiserfs and
-reiserfsck. These utils work on both i386 and alpha platforms.
-
-Xfsprogs
---------
-
-The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the
-xfs_repair utilities, among others, for the XFS filesystem. It is
-architecture independent and any version from 2.0.0 onward should
-work correctly with this version of the XFS kernel code (2.6.0 or
-later is recommended, due to some significant improvements).
-
-PCMCIAutils
------------
-
-PCMCIAutils replaces pcmcia-cs. It properly sets up
-PCMCIA sockets at system startup and loads the appropriate modules
-for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
-subsystem is used.
-
-Quota-tools
------------
-
-Support for 32 bit uid's and gid's is required if you want to use
-the newer version 2 quota format. Quota-tools version 3.07 and
-newer has this support. Use the recommended version or newer
-from the table above.
-
-Intel IA32 microcode
---------------------
-
-A driver has been added to allow updating of Intel IA32 microcode,
-accessible as a normal (misc) character device. If you are not using
-udev you may need to:
-
-mkdir /dev/cpu
-mknod /dev/cpu/microcode c 10 184
-chmod 0644 /dev/cpu/microcode
-
-as root before you can use this. You'll probably also want to
-get the user-space microcode_ctl utility to use with this.
-
-udev
-----
-udev is a userspace application for populating /dev dynamically with
-only entries for devices actually present. udev replaces the basic
-functionality of devfs, while allowing persistent device naming for
-devices.
-
-FUSE
-----
-
-Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount
-options 'direct_io' and 'kernel_cache' won't work.
-
-Networking
-==========
-
-General changes
----------------
-
-If you have advanced network configuration needs, you should probably
-consider using the network tools from ip-route2.
-
-Packet Filter / NAT
--------------------
-The packet filtering and NAT code uses the same tools like the previous 2.4.x
-kernel series (iptables). It still includes backwards-compatibility modules
-for 2.2.x-style ipchains and 2.0.x-style ipfwadm.
-
-PPP
----
-
-The PPP driver has been restructured to support multilink and to
-enable it to operate over diverse media layers. If you use PPP,
-upgrade pppd to at least 2.4.0.
-
-If you are not using udev, you must have the device file /dev/ppp
-which can be made by:
-
-mknod /dev/ppp c 108 0
-
-as root.
-
-Isdn4k-utils
-------------
-
-Due to changes in the length of the phone number field, isdn4k-utils
-needs to be recompiled or (preferably) upgraded.
-
-NFS-utils
----------
-
-In ancient (2.4 and earlier) kernels, the nfs server needed to know
-about any client that expected to be able to access files via NFS. This
-information would be given to the kernel by "mountd" when the client
-mounted the filesystem, or by "exportfs" at system startup. exportfs
-would take information about active clients from /var/lib/nfs/rmtab.
-
-This approach is quite fragile as it depends on rmtab being correct
-which is not always easy, particularly when trying to implement
-fail-over. Even when the system is working well, rmtab suffers from
-getting lots of old entries that never get removed.
-
-With modern kernels we have the option of having the kernel tell mountd
-when it gets a request from an unknown host, and mountd can give
-appropriate export information to the kernel. This removes the
-dependency on rmtab and means that the kernel only needs to know about
-currently active clients.
-
-To enable this new functionality, you need to:
-
- mount -t nfsd nfsd /proc/fs/nfsd
-
-before running exportfs or mountd. It is recommended that all NFS
-services be protected from the internet-at-large by a firewall where
-that is possible.
-
-mcelog
-------
-
-On x86 kernels the mcelog utility is needed to process and log machine check
-events when CONFIG_X86_MCE is enabled. Machine check events are errors reported
-by the CPU. Processing them is strongly encouraged.
-
-Getting updated software
-========================
-
-Kernel compilation
-******************
-
-gcc
----
-o <ftp://ftp.gnu.org/gnu/gcc/>
-
-Make
-----
-o <ftp://ftp.gnu.org/gnu/make/>
-
-Binutils
---------
-o <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
-
-System utilities
-****************
-
-Util-linux
-----------
-o <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
-
-Ksymoops
---------
-o <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
-
-Module-Init-Tools
------------------
-o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
-
-Mkinitrd
---------
-o <https://code.launchpad.net/initrd-tools/main>
-
-E2fsprogs
----------
-o <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
-
-JFSutils
---------
-o <http://jfs.sourceforge.net/>
-
-Reiserfsprogs
--------------
-o <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
-
-Xfsprogs
---------
-o <ftp://oss.sgi.com/projects/xfs/>
-
-Pcmciautils
------------
-o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
-
-Quota-tools
-----------
-o <http://sourceforge.net/projects/linuxquota/>
-
-DocBook Stylesheets
--------------------
-o <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
-
-XMLTO XSLT Frontend
--------------------
-o <http://cyberelk.net/tim/xmlto/>
-
-Intel P6 microcode
-------------------
-o <https://downloadcenter.intel.com/>
-
-udev
-----
-o <http://www.freedesktop.org/software/systemd/man/udev.html>
-
-FUSE
-----
-o <http://sourceforge.net/projects/fuse>
-
-mcelog
-------
-o <http://www.mcelog.org/>
-
-Networking
-**********
-
-PPP
----
-o <ftp://ftp.samba.org/pub/ppp/>
-
-Isdn4k-utils
-------------
-o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
-
-NFS-utils
----------
-o <http://sourceforge.net/project/showfiles.php?group_id=14>
-
-Iptables
---------
-o <http://www.iptables.org/downloads.html>
-
-Ip-route2
----------
-o <https://www.kernel.org/pub/linux/utils/net/iproute2/>
-
-OProfile
---------
-o <http://oprofile.sf.net/download/>
-
-NFS-Utils
----------
-o <http://nfs.sourceforge.net/>
-
+process/changes.rst \ No newline at end of file
diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict
deleted file mode 100644
index 1684d0b4efa6..000000000000
--- a/Documentation/CodeOfConflict
+++ /dev/null
@@ -1,27 +0,0 @@
-Code of Conflict
-----------------
-
-The Linux kernel development effort is a very personal process compared
-to "traditional" ways of developing software. Your code and ideas
-behind it will be carefully reviewed, often resulting in critique and
-criticism. The review will almost always require improvements to the
-code before it can be included in the kernel. Know that this happens
-because everyone involved wants to see the best possible solution for
-the overall success of Linux. This development process has been proven
-to create the most robust operating system kernel ever, and we do not
-want to do anything to cause the quality of submission and eventual
-result to ever decrease.
-
-If however, anyone feels personally abused, threatened, or otherwise
-uncomfortable due to this process, that is not acceptable. If so,
-please contact the Linux Foundation's Technical Advisory Board at
-<tab@lists.linux-foundation.org>, or the individual members, and they
-will work to resolve the issue to the best of their ability. For more
-information on who is on the Technical Advisory Board and what their
-role is, please see:
- http://www.linuxfoundation.org/programs/advisory-councils/tab
-
-As a reviewer of code, please strive to keep things civil and focused on
-the technical issues involved. We are all humans, and frustrations can
-be high on both sides of the process. Try to keep in mind the immortal
-words of Bill and Ted, "Be excellent to each other."
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index f4b78eafd92a..320983ca114e 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -1,948 +1 @@
-
- Linux kernel coding style
-
-This is a short document describing the preferred coding style for the
-linux kernel. Coding style is very personal, and I won't _force_ my
-views on anybody, but this is what goes for anything that I have to be
-able to maintain, and I'd prefer it for most other things too. Please
-at least consider the points made here.
-
-First off, I'd suggest printing out a copy of the GNU coding standards,
-and NOT read it. Burn them, it's a great symbolic gesture.
-
-Anyway, here goes:
-
-
- Chapter 1: Indentation
-
-Tabs are 8 characters, and thus indentations are also 8 characters.
-There are heretic movements that try to make indentations 4 (or even 2!)
-characters deep, and that is akin to trying to define the value of PI to
-be 3.
-
-Rationale: The whole idea behind indentation is to clearly define where
-a block of control starts and ends. Especially when you've been looking
-at your screen for 20 straight hours, you'll find it a lot easier to see
-how the indentation works if you have large indentations.
-
-Now, some people will claim that having 8-character indentations makes
-the code move too far to the right, and makes it hard to read on a
-80-character terminal screen. The answer to that is that if you need
-more than 3 levels of indentation, you're screwed anyway, and should fix
-your program.
-
-In short, 8-char indents make things easier to read, and have the added
-benefit of warning you when you're nesting your functions too deep.
-Heed that warning.
-
-The preferred way to ease multiple indentation levels in a switch statement is
-to align the "switch" and its subordinate "case" labels in the same column
-instead of "double-indenting" the "case" labels. E.g.:
-
- switch (suffix) {
- case 'G':
- case 'g':
- mem <<= 30;
- break;
- case 'M':
- case 'm':
- mem <<= 20;
- break;
- case 'K':
- case 'k':
- mem <<= 10;
- /* fall through */
- default:
- break;
- }
-
-Don't put multiple statements on a single line unless you have
-something to hide:
-
- if (condition) do_this;
- do_something_everytime;
-
-Don't put multiple assignments on a single line either. Kernel coding style
-is super simple. Avoid tricky expressions.
-
-Outside of comments, documentation and except in Kconfig, spaces are never
-used for indentation, and the above example is deliberately broken.
-
-Get a decent editor and don't leave whitespace at the end of lines.
-
-
- Chapter 2: Breaking long lines and strings
-
-Coding style is all about readability and maintainability using commonly
-available tools.
-
-The limit on the length of lines is 80 columns and this is a strongly
-preferred limit.
-
-Statements longer than 80 columns will be broken into sensible chunks, unless
-exceeding 80 columns significantly increases readability and does not hide
-information. Descendants are always substantially shorter than the parent and
-are placed substantially to the right. The same applies to function headers
-with a long argument list. However, never break user-visible strings such as
-printk messages, because that breaks the ability to grep for them.
-
-
- Chapter 3: Placing Braces and Spaces
-
-The other issue that always comes up in C styling is the placement of
-braces. Unlike the indent size, there are few technical reasons to
-choose one placement strategy over the other, but the preferred way, as
-shown to us by the prophets Kernighan and Ritchie, is to put the opening
-brace last on the line, and put the closing brace first, thusly:
-
- if (x is true) {
- we do y
- }
-
-This applies to all non-function statement blocks (if, switch, for,
-while, do). E.g.:
-
- switch (action) {
- case KOBJ_ADD:
- return "add";
- case KOBJ_REMOVE:
- return "remove";
- case KOBJ_CHANGE:
- return "change";
- default:
- return NULL;
- }
-
-However, there is one special case, namely functions: they have the
-opening brace at the beginning of the next line, thus:
-
- int function(int x)
- {
- body of function
- }
-
-Heretic people all over the world have claimed that this inconsistency
-is ... well ... inconsistent, but all right-thinking people know that
-(a) K&R are _right_ and (b) K&R are right. Besides, functions are
-special anyway (you can't nest them in C).
-
-Note that the closing brace is empty on a line of its own, _except_ in
-the cases where it is followed by a continuation of the same statement,
-ie a "while" in a do-statement or an "else" in an if-statement, like
-this:
-
- do {
- body of do-loop
- } while (condition);
-
-and
-
- if (x == y) {
- ..
- } else if (x > y) {
- ...
- } else {
- ....
- }
-
-Rationale: K&R.
-
-Also, note that this brace-placement also minimizes the number of empty
-(or almost empty) lines, without any loss of readability. Thus, as the
-supply of new-lines on your screen is not a renewable resource (think
-25-line terminal screens here), you have more empty lines to put
-comments on.
-
-Do not unnecessarily use braces where a single statement will do.
-
- if (condition)
- action();
-
-and
-
- if (condition)
- do_this();
- else
- do_that();
-
-This does not apply if only one branch of a conditional statement is a single
-statement; in the latter case use braces in both branches:
-
- if (condition) {
- do_this();
- do_that();
- } else {
- otherwise();
- }
-
- 3.1: Spaces
-
-Linux kernel style for use of spaces depends (mostly) on
-function-versus-keyword usage. Use a space after (most) keywords. The
-notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
-somewhat like functions (and are usually used with parentheses in Linux,
-although they are not required in the language, as in: "sizeof info" after
-"struct fileinfo info;" is declared).
-
-So use a space after these keywords:
-
- if, switch, case, for, do, while
-
-but not with sizeof, typeof, alignof, or __attribute__. E.g.,
-
- s = sizeof(struct file);
-
-Do not add spaces around (inside) parenthesized expressions. This example is
-*bad*:
-
- s = sizeof( struct file );
-
-When declaring pointer data or a function that returns a pointer type, the
-preferred use of '*' is adjacent to the data name or function name and not
-adjacent to the type name. Examples:
-
- char *linux_banner;
- unsigned long long memparse(char *ptr, char **retptr);
- char *match_strdup(substring_t *s);
-
-Use one space around (on each side of) most binary and ternary operators,
-such as any of these:
-
- = + - < > * / % | & ^ <= >= == != ? :
-
-but no space after unary operators:
-
- & * + - ~ ! sizeof typeof alignof __attribute__ defined
-
-no space before the postfix increment & decrement unary operators:
-
- ++ --
-
-no space after the prefix increment & decrement unary operators:
-
- ++ --
-
-and no space around the '.' and "->" structure member operators.
-
-Do not leave trailing whitespace at the ends of lines. Some editors with
-"smart" indentation will insert whitespace at the beginning of new lines as
-appropriate, so you can start typing the next line of code right away.
-However, some such editors do not remove the whitespace if you end up not
-putting a line of code there, such as if you leave a blank line. As a result,
-you end up with lines containing trailing whitespace.
-
-Git will warn you about patches that introduce trailing whitespace, and can
-optionally strip the trailing whitespace for you; however, if applying a series
-of patches, this may make later patches in the series fail by changing their
-context lines.
-
-
- Chapter 4: Naming
-
-C is a Spartan language, and so should your naming be. Unlike Modula-2
-and Pascal programmers, C programmers do not use cute names like
-ThisVariableIsATemporaryCounter. A C programmer would call that
-variable "tmp", which is much easier to write, and not the least more
-difficult to understand.
-
-HOWEVER, while mixed-case names are frowned upon, descriptive names for
-global variables are a must. To call a global function "foo" is a
-shooting offense.
-
-GLOBAL variables (to be used only if you _really_ need them) need to
-have descriptive names, as do global functions. If you have a function
-that counts the number of active users, you should call that
-"count_active_users()" or similar, you should _not_ call it "cntusr()".
-
-Encoding the type of a function into the name (so-called Hungarian
-notation) is brain damaged - the compiler knows the types anyway and can
-check those, and it only confuses the programmer. No wonder MicroSoft
-makes buggy programs.
-
-LOCAL variable names should be short, and to the point. If you have
-some random integer loop counter, it should probably be called "i".
-Calling it "loop_counter" is non-productive, if there is no chance of it
-being mis-understood. Similarly, "tmp" can be just about any type of
-variable that is used to hold a temporary value.
-
-If you are afraid to mix up your local variable names, you have another
-problem, which is called the function-growth-hormone-imbalance syndrome.
-See chapter 6 (Functions).
-
-
- Chapter 5: Typedefs
-
-Please don't use things like "vps_t".
-It's a _mistake_ to use typedef for structures and pointers. When you see a
-
- vps_t a;
-
-in the source, what does it mean?
-In contrast, if it says
-
- struct virtual_container *a;
-
-you can actually tell what "a" is.
-
-Lots of people think that typedefs "help readability". Not so. They are
-useful only for:
-
- (a) totally opaque objects (where the typedef is actively used to _hide_
- what the object is).
-
- Example: "pte_t" etc. opaque objects that you can only access using
- the proper accessor functions.
-
- NOTE! Opaqueness and "accessor functions" are not good in themselves.
- The reason we have them for things like pte_t etc. is that there
- really is absolutely _zero_ portably accessible information there.
-
- (b) Clear integer types, where the abstraction _helps_ avoid confusion
- whether it is "int" or "long".
-
- u8/u16/u32 are perfectly fine typedefs, although they fit into
- category (d) better than here.
-
- NOTE! Again - there needs to be a _reason_ for this. If something is
- "unsigned long", then there's no reason to do
-
- typedef unsigned long myflags_t;
-
- but if there is a clear reason for why it under certain circumstances
- might be an "unsigned int" and under other configurations might be
- "unsigned long", then by all means go ahead and use a typedef.
-
- (c) when you use sparse to literally create a _new_ type for
- type-checking.
-
- (d) New types which are identical to standard C99 types, in certain
- exceptional circumstances.
-
- Although it would only take a short amount of time for the eyes and
- brain to become accustomed to the standard types like 'uint32_t',
- some people object to their use anyway.
-
- Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
- signed equivalents which are identical to standard types are
- permitted -- although they are not mandatory in new code of your
- own.
-
- When editing existing code which already uses one or the other set
- of types, you should conform to the existing choices in that code.
-
- (e) Types safe for use in userspace.
-
- In certain structures which are visible to userspace, we cannot
- require C99 types and cannot use the 'u32' form above. Thus, we
- use __u32 and similar types in all structures which are shared
- with userspace.
-
-Maybe there are other cases too, but the rule should basically be to NEVER
-EVER use a typedef unless you can clearly match one of those rules.
-
-In general, a pointer, or a struct that has elements that can reasonably
-be directly accessed should _never_ be a typedef.
-
-
- Chapter 6: Functions
-
-Functions should be short and sweet, and do just one thing. They should
-fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
-as we all know), and do one thing and do that well.
-
-The maximum length of a function is inversely proportional to the
-complexity and indentation level of that function. So, if you have a
-conceptually simple function that is just one long (but simple)
-case-statement, where you have to do lots of small things for a lot of
-different cases, it's OK to have a longer function.
-
-However, if you have a complex function, and you suspect that a
-less-than-gifted first-year high-school student might not even
-understand what the function is all about, you should adhere to the
-maximum limits all the more closely. Use helper functions with
-descriptive names (you can ask the compiler to in-line them if you think
-it's performance-critical, and it will probably do a better job of it
-than you would have done).
-
-Another measure of the function is the number of local variables. They
-shouldn't exceed 5-10, or you're doing something wrong. Re-think the
-function, and split it into smaller pieces. A human brain can
-generally easily keep track of about 7 different things, anything more
-and it gets confused. You know you're brilliant, but maybe you'd like
-to understand what you did 2 weeks from now.
-
-In source files, separate functions with one blank line. If the function is
-exported, the EXPORT* macro for it should follow immediately after the closing
-function brace line. E.g.:
-
- int system_is_up(void)
- {
- return system_state == SYSTEM_RUNNING;
- }
- EXPORT_SYMBOL(system_is_up);
-
-In function prototypes, include parameter names with their data types.
-Although this is not required by the C language, it is preferred in Linux
-because it is a simple way to add valuable information for the reader.
-
-
- Chapter 7: Centralized exiting of functions
-
-Albeit deprecated by some people, the equivalent of the goto statement is
-used frequently by compilers in form of the unconditional jump instruction.
-
-The goto statement comes in handy when a function exits from multiple
-locations and some common work such as cleanup has to be done. If there is no
-cleanup needed then just return directly.
-
-Choose label names which say what the goto does or why the goto exists. An
-example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid
-using GW-BASIC names like "err1:" and "err2:". Also don't name them after the
-goto location like "err_kmalloc_failed:"
-
-The rationale for using gotos is:
-
-- unconditional statements are easier to understand and follow
-- nesting is reduced
-- errors by not updating individual exit points when making
- modifications are prevented
-- saves the compiler work to optimize redundant code away ;)
-
- int fun(int a)
- {
- int result = 0;
- char *buffer;
-
- buffer = kmalloc(SIZE, GFP_KERNEL);
- if (!buffer)
- return -ENOMEM;
-
- if (condition1) {
- while (loop1) {
- ...
- }
- result = 1;
- goto out_buffer;
- }
- ...
- out_buffer:
- kfree(buffer);
- return result;
- }
-
-A common type of bug to be aware of it "one err bugs" which look like this:
-
- err:
- kfree(foo->bar);
- kfree(foo);
- return ret;
-
-The bug in this code is that on some exit paths "foo" is NULL. Normally the
-fix for this is to split it up into two error labels "err_bar:" and "err_foo:".
-
-
- Chapter 8: Commenting
-
-Comments are good, but there is also a danger of over-commenting. NEVER
-try to explain HOW your code works in a comment: it's much better to
-write the code so that the _working_ is obvious, and it's a waste of
-time to explain badly written code.
-
-Generally, you want your comments to tell WHAT your code does, not HOW.
-Also, try to avoid putting comments inside a function body: if the
-function is so complex that you need to separately comment parts of it,
-you should probably go back to chapter 6 for a while. You can make
-small comments to note or warn about something particularly clever (or
-ugly), but try to avoid excess. Instead, put the comments at the head
-of the function, telling people what it does, and possibly WHY it does
-it.
-
-When commenting the kernel API functions, please use the kernel-doc format.
-See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
-for details.
-
-Linux style for comments is the C89 "/* ... */" style.
-Don't use C99-style "// ..." comments.
-
-The preferred style for long (multi-line) comments is:
-
- /*
- * This is the preferred style for multi-line
- * comments in the Linux kernel source code.
- * Please use it consistently.
- *
- * Description: A column of asterisks on the left side,
- * with beginning and ending almost-blank lines.
- */
-
-For files in net/ and drivers/net/ the preferred style for long (multi-line)
-comments is a little different.
-
- /* The preferred comment style for files in net/ and drivers/net
- * looks like this.
- *
- * It is nearly the same as the generally preferred comment style,
- * but there is no initial almost-blank line.
- */
-
-It's also important to comment data, whether they are basic types or derived
-types. To this end, use just one data declaration per line (no commas for
-multiple data declarations). This leaves you room for a small comment on each
-item, explaining its use.
-
-
- Chapter 9: You've made a mess of it
-
-That's OK, we all do. You've probably been told by your long-time Unix
-user helper that "GNU emacs" automatically formats the C sources for
-you, and you've noticed that yes, it does do that, but the defaults it
-uses are less than desirable (in fact, they are worse than random
-typing - an infinite number of monkeys typing into GNU emacs would never
-make a good program).
-
-So, you can either get rid of GNU emacs, or change it to use saner
-values. To do the latter, you can stick the following in your .emacs file:
-
-(defun c-lineup-arglist-tabs-only (ignored)
- "Line up argument lists by tabs, not spaces"
- (let* ((anchor (c-langelem-pos c-syntactic-element))
- (column (c-langelem-2nd-pos c-syntactic-element))
- (offset (- (1+ column) anchor))
- (steps (floor offset c-basic-offset)))
- (* (max steps 1)
- c-basic-offset)))
-
-(add-hook 'c-mode-common-hook
- (lambda ()
- ;; Add kernel style
- (c-add-style
- "linux-tabs-only"
- '("linux" (c-offsets-alist
- (arglist-cont-nonempty
- c-lineup-gcc-asm-reg
- c-lineup-arglist-tabs-only))))))
-
-(add-hook 'c-mode-hook
- (lambda ()
- (let ((filename (buffer-file-name)))
- ;; Enable kernel mode for the appropriate files
- (when (and filename
- (string-match (expand-file-name "~/src/linux-trees")
- filename))
- (setq indent-tabs-mode t)
- (setq show-trailing-whitespace t)
- (c-set-style "linux-tabs-only")))))
-
-This will make emacs go better with the kernel coding style for C
-files below ~/src/linux-trees.
-
-But even if you fail in getting emacs to do sane formatting, not
-everything is lost: use "indent".
-
-Now, again, GNU indent has the same brain-dead settings that GNU emacs
-has, which is why you need to give it a few command line options.
-However, that's not too bad, because even the makers of GNU indent
-recognize the authority of K&R (the GNU people aren't evil, they are
-just severely misguided in this matter), so you just give indent the
-options "-kr -i8" (stands for "K&R, 8 character indents"), or use
-"scripts/Lindent", which indents in the latest style.
-
-"indent" has a lot of options, and especially when it comes to comment
-re-formatting you may want to take a look at the man page. But
-remember: "indent" is not a fix for bad programming.
-
-
- Chapter 10: Kconfig configuration files
-
-For all of the Kconfig* configuration files throughout the source tree,
-the indentation is somewhat different. Lines under a "config" definition
-are indented with one tab, while help text is indented an additional two
-spaces. Example:
-
-config AUDIT
- bool "Auditing support"
- depends on NET
- help
- Enable auditing infrastructure that can be used with another
- kernel subsystem, such as SELinux (which requires this for
- logging of avc messages output). Does not do system-call
- auditing without CONFIG_AUDITSYSCALL.
-
-Seriously dangerous features (such as write support for certain
-filesystems) should advertise this prominently in their prompt string:
-
-config ADFS_FS_RW
- bool "ADFS write support (DANGEROUS)"
- depends on ADFS_FS
- ...
-
-For full documentation on the configuration files, see the file
-Documentation/kbuild/kconfig-language.txt.
-
-
- Chapter 11: Data structures
-
-Data structures that have visibility outside the single-threaded
-environment they are created and destroyed in should always have
-reference counts. In the kernel, garbage collection doesn't exist (and
-outside the kernel garbage collection is slow and inefficient), which
-means that you absolutely _have_ to reference count all your uses.
-
-Reference counting means that you can avoid locking, and allows multiple
-users to have access to the data structure in parallel - and not having
-to worry about the structure suddenly going away from under them just
-because they slept or did something else for a while.
-
-Note that locking is _not_ a replacement for reference counting.
-Locking is used to keep data structures coherent, while reference
-counting is a memory management technique. Usually both are needed, and
-they are not to be confused with each other.
-
-Many data structures can indeed have two levels of reference counting,
-when there are users of different "classes". The subclass count counts
-the number of subclass users, and decrements the global count just once
-when the subclass count goes to zero.
-
-Examples of this kind of "multi-level-reference-counting" can be found in
-memory management ("struct mm_struct": mm_users and mm_count), and in
-filesystem code ("struct super_block": s_count and s_active).
-
-Remember: if another thread can find your data structure, and you don't
-have a reference count on it, you almost certainly have a bug.
-
-
- Chapter 12: Macros, Enums and RTL
-
-Names of macros defining constants and labels in enums are capitalized.
-
- #define CONSTANT 0x12345
-
-Enums are preferred when defining several related constants.
-
-CAPITALIZED macro names are appreciated but macros resembling functions
-may be named in lower case.
-
-Generally, inline functions are preferable to macros resembling functions.
-
-Macros with multiple statements should be enclosed in a do - while block:
-
- #define macrofun(a, b, c) \
- do { \
- if (a == 5) \
- do_this(b, c); \
- } while (0)
-
-Things to avoid when using macros:
-
-1) macros that affect control flow:
-
- #define FOO(x) \
- do { \
- if (blah(x) < 0) \
- return -EBUGGERED; \
- } while(0)
-
-is a _very_ bad idea. It looks like a function call but exits the "calling"
-function; don't break the internal parsers of those who will read the code.
-
-2) macros that depend on having a local variable with a magic name:
-
- #define FOO(val) bar(index, val)
-
-might look like a good thing, but it's confusing as hell when one reads the
-code and it's prone to breakage from seemingly innocent changes.
-
-3) macros with arguments that are used as l-values: FOO(x) = y; will
-bite you if somebody e.g. turns FOO into an inline function.
-
-4) forgetting about precedence: macros defining constants using expressions
-must enclose the expression in parentheses. Beware of similar issues with
-macros using parameters.
-
- #define CONSTANT 0x4000
- #define CONSTEXP (CONSTANT | 3)
-
-5) namespace collisions when defining local variables in macros resembling
-functions:
-
-#define FOO(x) \
-({ \
- typeof(x) ret; \
- ret = calc_ret(x); \
- (ret); \
-)}
-
-ret is a common name for a local variable - __foo_ret is less likely
-to collide with an existing variable.
-
-The cpp manual deals with macros exhaustively. The gcc internals manual also
-covers RTL which is used frequently with assembly language in the kernel.
-
-
- Chapter 13: Printing kernel messages
-
-Kernel developers like to be seen as literate. Do mind the spelling
-of kernel messages to make a good impression. Do not use crippled
-words like "dont"; use "do not" or "don't" instead. Make the messages
-concise, clear, and unambiguous.
-
-Kernel messages do not have to be terminated with a period.
-
-Printing numbers in parentheses (%d) adds no value and should be avoided.
-
-There are a number of driver model diagnostic macros in <linux/device.h>
-which you should use to make sure messages are matched to the right device
-and driver, and are tagged with the right level: dev_err(), dev_warn(),
-dev_info(), and so forth. For messages that aren't associated with a
-particular device, <linux/printk.h> defines pr_notice(), pr_info(),
-pr_warn(), pr_err(), etc.
-
-Coming up with good debugging messages can be quite a challenge; and once
-you have them, they can be a huge help for remote troubleshooting. However
-debug message printing is handled differently than printing other non-debug
-messages. While the other pr_XXX() functions print unconditionally,
-pr_debug() does not; it is compiled out by default, unless either DEBUG is
-defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also,
-and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to
-the ones already enabled by DEBUG.
-
-Many subsystems have Kconfig debug options to turn on -DDEBUG in the
-corresponding Makefile; in other cases specific files #define DEBUG. And
-when a debug message should be unconditionally printed, such as if it is
-already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
-used.
-
-
- Chapter 14: Allocating memory
-
-The kernel provides the following general purpose memory allocators:
-kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
-vzalloc(). Please refer to the API documentation for further information
-about them.
-
-The preferred form for passing a size of a struct is the following:
-
- p = kmalloc(sizeof(*p), ...);
-
-The alternative form where struct name is spelled out hurts readability and
-introduces an opportunity for a bug when the pointer variable type is changed
-but the corresponding sizeof that is passed to a memory allocator is not.
-
-Casting the return value which is a void pointer is redundant. The conversion
-from void pointer to any other pointer type is guaranteed by the C programming
-language.
-
-The preferred form for allocating an array is the following:
-
- p = kmalloc_array(n, sizeof(...), ...);
-
-The preferred form for allocating a zeroed array is the following:
-
- p = kcalloc(n, sizeof(...), ...);
-
-Both forms check for overflow on the allocation size n * sizeof(...),
-and return NULL if that occurred.
-
-
- Chapter 15: The inline disease
-
-There appears to be a common misperception that gcc has a magic "make me
-faster" speedup option called "inline". While the use of inlines can be
-appropriate (for example as a means of replacing macros, see Chapter 12), it
-very often is not. Abundant use of the inline keyword leads to a much bigger
-kernel, which in turn slows the system as a whole down, due to a bigger
-icache footprint for the CPU and simply because there is less memory
-available for the pagecache. Just think about it; a pagecache miss causes a
-disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
-that can go into these 5 milliseconds.
-
-A reasonable rule of thumb is to not put inline at functions that have more
-than 3 lines of code in them. An exception to this rule are the cases where
-a parameter is known to be a compiletime constant, and as a result of this
-constantness you *know* the compiler will be able to optimize most of your
-function away at compile time. For a good example of this later case, see
-the kmalloc() inline function.
-
-Often people argue that adding inline to functions that are static and used
-only once is always a win since there is no space tradeoff. While this is
-technically correct, gcc is capable of inlining these automatically without
-help, and the maintenance issue of removing the inline when a second user
-appears outweighs the potential value of the hint that tells gcc to do
-something it would have done anyway.
-
-
- Chapter 16: Function return values and names
-
-Functions can return values of many different kinds, and one of the
-most common is a value indicating whether the function succeeded or
-failed. Such a value can be represented as an error-code integer
-(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
-non-zero = success).
-
-Mixing up these two sorts of representations is a fertile source of
-difficult-to-find bugs. If the C language included a strong distinction
-between integers and booleans then the compiler would find these mistakes
-for us... but it doesn't. To help prevent such bugs, always follow this
-convention:
-
- If the name of a function is an action or an imperative command,
- the function should return an error-code integer. If the name
- is a predicate, the function should return a "succeeded" boolean.
-
-For example, "add work" is a command, and the add_work() function returns 0
-for success or -EBUSY for failure. In the same way, "PCI device present" is
-a predicate, and the pci_dev_present() function returns 1 if it succeeds in
-finding a matching device or 0 if it doesn't.
-
-All EXPORTed functions must respect this convention, and so should all
-public functions. Private (static) functions need not, but it is
-recommended that they do.
-
-Functions whose return value is the actual result of a computation, rather
-than an indication of whether the computation succeeded, are not subject to
-this rule. Generally they indicate failure by returning some out-of-range
-result. Typical examples would be functions that return pointers; they use
-NULL or the ERR_PTR mechanism to report failure.
-
-
- Chapter 17: Don't re-invent the kernel macros
-
-The header file include/linux/kernel.h contains a number of macros that
-you should use, rather than explicitly coding some variant of them yourself.
-For example, if you need to calculate the length of an array, take advantage
-of the macro
-
- #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
-
-Similarly, if you need to calculate the size of some structure member, use
-
- #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
-
-There are also min() and max() macros that do strict type checking if you
-need them. Feel free to peruse that header file to see what else is already
-defined that you shouldn't reproduce in your code.
-
-
- Chapter 18: Editor modelines and other cruft
-
-Some editors can interpret configuration information embedded in source files,
-indicated with special markers. For example, emacs interprets lines marked
-like this:
-
- -*- mode: c -*-
-
-Or like this:
-
- /*
- Local Variables:
- compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
- End:
- */
-
-Vim interprets markers that look like this:
-
- /* vim:set sw=8 noet */
-
-Do not include any of these in source files. People have their own personal
-editor configurations, and your source files should not override them. This
-includes markers for indentation and mode configuration. People may use their
-own custom mode, or may have some other magic method for making indentation
-work correctly.
-
-
- Chapter 19: Inline assembly
-
-In architecture-specific code, you may need to use inline assembly to interface
-with CPU or platform functionality. Don't hesitate to do so when necessary.
-However, don't use inline assembly gratuitously when C can do the job. You can
-and should poke hardware from C when possible.
-
-Consider writing simple helper functions that wrap common bits of inline
-assembly, rather than repeatedly writing them with slight variations. Remember
-that inline assembly can use C parameters.
-
-Large, non-trivial assembly functions should go in .S files, with corresponding
-C prototypes defined in C header files. The C prototypes for assembly
-functions should use "asmlinkage".
-
-You may need to mark your asm statement as volatile, to prevent GCC from
-removing it if GCC doesn't notice any side effects. You don't always need to
-do so, though, and doing so unnecessarily can limit optimization.
-
-When writing a single inline assembly statement containing multiple
-instructions, put each instruction on a separate line in a separate quoted
-string, and end each string except the last with \n\t to properly indent the
-next instruction in the assembly output:
-
- asm ("magic %reg1, #42\n\t"
- "more_magic %reg2, %reg3"
- : /* outputs */ : /* inputs */ : /* clobbers */);
-
-
- Chapter 20: Conditional Compilation
-
-Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
-files; doing so makes code harder to read and logic harder to follow. Instead,
-use such conditionals in a header file defining functions for use in those .c
-files, providing no-op stub versions in the #else case, and then call those
-functions unconditionally from .c files. The compiler will avoid generating
-any code for the stub calls, producing identical results, but the logic will
-remain easy to follow.
-
-Prefer to compile out entire functions, rather than portions of functions or
-portions of expressions. Rather than putting an ifdef in an expression, factor
-out part or all of the expression into a separate helper function and apply the
-conditional to that function.
-
-If you have a function or variable which may potentially go unused in a
-particular configuration, and the compiler would warn about its definition
-going unused, mark the definition as __maybe_unused rather than wrapping it in
-a preprocessor conditional. (However, if a function or variable *always* goes
-unused, delete it.)
-
-Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
-symbol into a C boolean expression, and use it in a normal C conditional:
-
- if (IS_ENABLED(CONFIG_SOMETHING)) {
- ...
- }
-
-The compiler will constant-fold the conditional away, and include or exclude
-the block of code just as with an #ifdef, so this will not add any runtime
-overhead. However, this approach still allows the C compiler to see the code
-inside the block, and check it for correctness (syntax, types, symbol
-references, etc). Thus, you still have to use an #ifdef if the code inside the
-block references symbols that will not exist if the condition is not met.
-
-At the end of any non-trivial #if or #ifdef block (more than a few lines),
-place a comment after the #endif on the same line, noting the conditional
-expression used. For instance:
-
- #ifdef CONFIG_SOMETHING
- ...
- #endif /* CONFIG_SOMETHING */
-
-
- Appendix I: References
-
-The C Programming Language, Second Edition
-by Brian W. Kernighan and Dennis M. Ritchie.
-Prentice Hall, Inc., 1988.
-ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
-URL: http://cm.bell-labs.com/cm/cs/cbook/
-
-The Practice of Programming
-by Brian W. Kernighan and Rob Pike.
-Addison-Wesley, Inc., 1999.
-ISBN 0-201-61586-X.
-URL: http://cm.bell-labs.com/cm/cs/tpop/
-
-GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
-gcc internals and indent, all available from http://www.gnu.org/manual/
-
-WG14 is the international standardization working group for the programming
-language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
-
-Kernel CodingStyle, by greg@kroah.com at OLS 2002:
-http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
-
+This file has moved to process/coding-style.rst
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
deleted file mode 100644
index 0f7afb2bb442..000000000000
--- a/Documentation/DMA-API-HOWTO.txt
+++ /dev/null
@@ -1,969 +0,0 @@
- Dynamic DMA mapping Guide
- =========================
-
- David S. Miller <davem@redhat.com>
- Richard Henderson <rth@cygnus.com>
- Jakub Jelinek <jakub@redhat.com>
-
-This is a guide to device driver writers on how to use the DMA API
-with example pseudo-code. For a concise description of the API, see
-DMA-API.txt.
-
- CPU and DMA addresses
-
-There are several kinds of addresses involved in the DMA API, and it's
-important to understand the differences.
-
-The kernel normally uses virtual addresses. Any address returned by
-kmalloc(), vmalloc(), and similar interfaces is a virtual address and can
-be stored in a "void *".
-
-The virtual memory system (TLB, page tables, etc.) translates virtual
-addresses to CPU physical addresses, which are stored as "phys_addr_t" or
-"resource_size_t". The kernel manages device resources like registers as
-physical addresses. These are the addresses in /proc/iomem. The physical
-address is not directly useful to a driver; it must use ioremap() to map
-the space and produce a virtual address.
-
-I/O devices use a third kind of address: a "bus address" or "DMA address".
-If a device has registers at an MMIO address, or if it performs DMA to read
-or write system memory, the addresses used by the device are bus addresses.
-In some systems, bus addresses are identical to CPU physical addresses, but
-in general they are not. IOMMUs and host bridges can produce arbitrary
-mappings between physical and bus addresses.
-
-Here's a picture and some examples:
-
- CPU CPU Bus
- Virtual Physical Address
- Address Address Space
- Space Space
-
- +-------+ +------+ +------+
- | | |MMIO | Offset | |
- | | Virtual |Space | applied | |
- C +-------+ --------> B +------+ ----------> +------+ A
- | | mapping | | by host | |
- +-----+ | | | | bridge | | +--------+
- | | | | +------+ | | | |
- | CPU | | | | RAM | | | | Device |
- | | | | | | | | | |
- +-----+ +-------+ +------+ +------+ +--------+
- | | Virtual |Buffer| Mapping | |
- X +-------+ --------> Y +------+ <---------- +------+ Z
- | | mapping | RAM | by IOMMU
- | | | |
- | | | |
- +-------+ +------+
-
-During the enumeration process, the kernel learns about I/O devices and
-their MMIO space and the host bridges that connect them to the system. For
-example, if a PCI device has a BAR, the kernel reads the bus address (A)
-from the BAR and converts it to a CPU physical address (B). The address B
-is stored in a struct resource and usually exposed via /proc/iomem. When a
-driver claims a device, it typically uses ioremap() to map physical address
-B at a virtual address (C). It can then use, e.g., ioread32(C), to access
-the device registers at bus address A.
-
-If the device supports DMA, the driver sets up a buffer using kmalloc() or
-a similar interface, which returns a virtual address (X). The virtual
-memory system maps X to a physical address (Y) in system RAM. The driver
-can use virtual address X to access the buffer, but the device itself
-cannot because DMA doesn't go through the CPU virtual memory system.
-
-In some simple systems, the device can do DMA directly to physical address
-Y. But in many others, there is IOMMU hardware that translates bus
-addresses to physical addresses, e.g., it translates Z to Y. This is part
-of the reason for the DMA API: the driver can give a virtual address X to
-an interface like dma_map_single(), which sets up any required IOMMU
-mapping and returns the bus address Z. The driver then tells the device to
-do DMA to Z, and the IOMMU maps it to the buffer at address Y in system
-RAM.
-
-So that Linux can use the dynamic DMA mapping, it needs some help from the
-drivers, namely it has to take into account that DMA addresses should be
-mapped only for the time they are actually used and unmapped after the DMA
-transfer.
-
-The following API will work of course even on platforms where no such
-hardware exists.
-
-Note that the DMA API works with any bus independent of the underlying
-microprocessor architecture. You should use the DMA API rather than the
-bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the
-pci_map_*() interfaces.
-
-First of all, you should make sure
-
-#include <linux/dma-mapping.h>
-
-is in your driver, which provides the definition of dma_addr_t. This type
-can hold any valid DMA or bus address for the platform and should be used
-everywhere you hold a DMA address returned from the DMA mapping functions.
-
- What memory is DMA'able?
-
-The first piece of information you must know is what kernel memory can
-be used with the DMA mapping facilities. There has been an unwritten
-set of rules regarding this, and this text is an attempt to finally
-write them down.
-
-If you acquired your memory via the page allocator
-(i.e. __get_free_page*()) or the generic memory allocators
-(i.e. kmalloc() or kmem_cache_alloc()) then you may DMA to/from
-that memory using the addresses returned from those routines.
-
-This means specifically that you may _not_ use the memory/addresses
-returned from vmalloc() for DMA. It is possible to DMA to the
-_underlying_ memory mapped into a vmalloc() area, but this requires
-walking page tables to get the physical addresses, and then
-translating each of those pages back to a kernel address using
-something like __va(). [ EDIT: Update this when we integrate
-Gerd Knorr's generic code which does this. ]
-
-This rule also means that you may use neither kernel image addresses
-(items in data/text/bss segments), nor module image addresses, nor
-stack addresses for DMA. These could all be mapped somewhere entirely
-different than the rest of physical memory. Even if those classes of
-memory could physically work with DMA, you'd need to ensure the I/O
-buffers were cacheline-aligned. Without that, you'd see cacheline
-sharing problems (data corruption) on CPUs with DMA-incoherent caches.
-(The CPU could write to one word, DMA would write to a different one
-in the same cache line, and one of them could be overwritten.)
-
-Also, this means that you cannot take the return of a kmap()
-call and DMA to/from that. This is similar to vmalloc().
-
-What about block I/O and networking buffers? The block I/O and
-networking subsystems make sure that the buffers they use are valid
-for you to DMA from/to.
-
- DMA addressing limitations
-
-Does your device have any DMA addressing limitations? For example, is
-your device only capable of driving the low order 24-bits of address?
-If so, you need to inform the kernel of this fact.
-
-By default, the kernel assumes that your device can address the full
-32-bits. For a 64-bit capable device, this needs to be increased.
-And for a device with limitations, as discussed in the previous
-paragraph, it needs to be decreased.
-
-Special note about PCI: PCI-X specification requires PCI-X devices to
-support 64-bit addressing (DAC) for all transactions. And at least
-one platform (SGI SN2) requires 64-bit consistent allocations to
-operate correctly when the IO bus is in PCI-X mode.
-
-For correct operation, you must interrogate the kernel in your device
-probe routine to see if the DMA controller on the machine can properly
-support the DMA addressing limitation your device has. It is good
-style to do this even if your device holds the default setting,
-because this shows that you did think about these issues wrt. your
-device.
-
-The query is performed via a call to dma_set_mask_and_coherent():
-
- int dma_set_mask_and_coherent(struct device *dev, u64 mask);
-
-which will query the mask for both streaming and coherent APIs together.
-If you have some special requirements, then the following two separate
-queries can be used instead:
-
- The query for streaming mappings is performed via a call to
- dma_set_mask():
-
- int dma_set_mask(struct device *dev, u64 mask);
-
- The query for consistent allocations is performed via a call
- to dma_set_coherent_mask():
-
- int dma_set_coherent_mask(struct device *dev, u64 mask);
-
-Here, dev is a pointer to the device struct of your device, and mask
-is a bit mask describing which bits of an address your device
-supports. It returns zero if your card can perform DMA properly on
-the machine given the address mask you provided. In general, the
-device struct of your device is embedded in the bus-specific device
-struct of your device. For example, &pdev->dev is a pointer to the
-device struct of a PCI device (pdev is a pointer to the PCI device
-struct of your device).
-
-If it returns non-zero, your device cannot perform DMA properly on
-this platform, and attempting to do so will result in undefined
-behavior. You must either use a different mask, or not use DMA.
-
-This means that in the failure case, you have three options:
-
-1) Use another DMA mask, if possible (see below).
-2) Use some non-DMA mode for data transfer, if possible.
-3) Ignore this device and do not initialize it.
-
-It is recommended that your driver print a kernel KERN_WARNING message
-when you end up performing either #2 or #3. In this manner, if a user
-of your driver reports that performance is bad or that the device is not
-even detected, you can ask them for the kernel messages to find out
-exactly why.
-
-The standard 32-bit addressing device would do something like this:
-
- if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) {
- dev_warn(dev, "mydev: No suitable DMA available\n");
- goto ignore_this_device;
- }
-
-Another common scenario is a 64-bit capable device. The approach here
-is to try for 64-bit addressing, but back down to a 32-bit mask that
-should not fail. The kernel may fail the 64-bit mask not because the
-platform is not capable of 64-bit addressing. Rather, it may fail in
-this case simply because 32-bit addressing is done more efficiently
-than 64-bit addressing. For example, Sparc64 PCI SAC addressing is
-more efficient than DAC addressing.
-
-Here is how you would handle a 64-bit capable device which can drive
-all 64-bits when accessing streaming DMA:
-
- int using_dac;
-
- if (!dma_set_mask(dev, DMA_BIT_MASK(64))) {
- using_dac = 1;
- } else if (!dma_set_mask(dev, DMA_BIT_MASK(32))) {
- using_dac = 0;
- } else {
- dev_warn(dev, "mydev: No suitable DMA available\n");
- goto ignore_this_device;
- }
-
-If a card is capable of using 64-bit consistent allocations as well,
-the case would look like this:
-
- int using_dac, consistent_using_dac;
-
- if (!dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) {
- using_dac = 1;
- consistent_using_dac = 1;
- } else if (!dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) {
- using_dac = 0;
- consistent_using_dac = 0;
- } else {
- dev_warn(dev, "mydev: No suitable DMA available\n");
- goto ignore_this_device;
- }
-
-The coherent mask will always be able to set the same or a smaller mask as
-the streaming mask. However for the rare case that a device driver only
-uses consistent allocations, one would have to check the return value from
-dma_set_coherent_mask().
-
-Finally, if your device can only drive the low 24-bits of
-address you might do something like:
-
- if (dma_set_mask(dev, DMA_BIT_MASK(24))) {
- dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");
- goto ignore_this_device;
- }
-
-When dma_set_mask() or dma_set_mask_and_coherent() is successful, and
-returns zero, the kernel saves away this mask you have provided. The
-kernel will use this information later when you make DMA mappings.
-
-There is a case which we are aware of at this time, which is worth
-mentioning in this documentation. If your device supports multiple
-functions (for example a sound card provides playback and record
-functions) and the various different functions have _different_
-DMA addressing limitations, you may wish to probe each mask and
-only provide the functionality which the machine can handle. It
-is important that the last call to dma_set_mask() be for the
-most specific mask.
-
-Here is pseudo-code showing how this might be done:
-
- #define PLAYBACK_ADDRESS_BITS DMA_BIT_MASK(32)
- #define RECORD_ADDRESS_BITS DMA_BIT_MASK(24)
-
- struct my_sound_card *card;
- struct device *dev;
-
- ...
- if (!dma_set_mask(dev, PLAYBACK_ADDRESS_BITS)) {
- card->playback_enabled = 1;
- } else {
- card->playback_enabled = 0;
- dev_warn(dev, "%s: Playback disabled due to DMA limitations\n",
- card->name);
- }
- if (!dma_set_mask(dev, RECORD_ADDRESS_BITS)) {
- card->record_enabled = 1;
- } else {
- card->record_enabled = 0;
- dev_warn(dev, "%s: Record disabled due to DMA limitations\n",
- card->name);
- }
-
-A sound card was used as an example here because this genre of PCI
-devices seems to be littered with ISA chips given a PCI front end,
-and thus retaining the 16MB DMA addressing limitations of ISA.
-
- Types of DMA mappings
-
-There are two types of DMA mappings:
-
-- Consistent DMA mappings which are usually mapped at driver
- initialization, unmapped at the end and for which the hardware should
- guarantee that the device and the CPU can access the data
- in parallel and will see updates made by each other without any
- explicit software flushing.
-
- Think of "consistent" as "synchronous" or "coherent".
-
- The current default is to return consistent memory in the low 32
- bits of the bus space. However, for future compatibility you should
- set the consistent mask even if this default is fine for your
- driver.
-
- Good examples of what to use consistent mappings for are:
-
- - Network card DMA ring descriptors.
- - SCSI adapter mailbox command data structures.
- - Device firmware microcode executed out of
- main memory.
-
- The invariant these examples all require is that any CPU store
- to memory is immediately visible to the device, and vice
- versa. Consistent mappings guarantee this.
-
- IMPORTANT: Consistent DMA memory does not preclude the usage of
- proper memory barriers. The CPU may reorder stores to
- consistent memory just as it may normal memory. Example:
- if it is important for the device to see the first word
- of a descriptor updated before the second, you must do
- something like:
-
- desc->word0 = address;
- wmb();
- desc->word1 = DESC_VALID;
-
- in order to get correct behavior on all platforms.
-
- Also, on some platforms your driver may need to flush CPU write
- buffers in much the same way as it needs to flush write buffers
- found in PCI bridges (such as by reading a register's value
- after writing it).
-
-- Streaming DMA mappings which are usually mapped for one DMA
- transfer, unmapped right after it (unless you use dma_sync_* below)
- and for which hardware can optimize for sequential accesses.
-
- This of "streaming" as "asynchronous" or "outside the coherency
- domain".
-
- Good examples of what to use streaming mappings for are:
-
- - Networking buffers transmitted/received by a device.
- - Filesystem buffers written/read by a SCSI device.
-
- The interfaces for using this type of mapping were designed in
- such a way that an implementation can make whatever performance
- optimizations the hardware allows. To this end, when using
- such mappings you must be explicit about what you want to happen.
-
-Neither type of DMA mapping has alignment restrictions that come from
-the underlying bus, although some devices may have such restrictions.
-Also, systems with caches that aren't DMA-coherent will work better
-when the underlying buffers don't share cache lines with other data.
-
-
- Using Consistent DMA mappings.
-
-To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
-you should do:
-
- dma_addr_t dma_handle;
-
- cpu_addr = dma_alloc_coherent(dev, size, &dma_handle, gfp);
-
-where device is a struct device *. This may be called in interrupt
-context with the GFP_ATOMIC flag.
-
-Size is the length of the region you want to allocate, in bytes.
-
-This routine will allocate RAM for that region, so it acts similarly to
-__get_free_pages() (but takes size instead of a page order). If your
-driver needs regions sized smaller than a page, you may prefer using
-the dma_pool interface, described below.
-
-The consistent DMA mapping interfaces, for non-NULL dev, will by
-default return a DMA address which is 32-bit addressable. Even if the
-device indicates (via DMA mask) that it may address the upper 32-bits,
-consistent allocation will only return > 32-bit addresses for DMA if
-the consistent DMA mask has been explicitly changed via
-dma_set_coherent_mask(). This is true of the dma_pool interface as
-well.
-
-dma_alloc_coherent() returns two values: the virtual address which you
-can use to access it from the CPU and dma_handle which you pass to the
-card.
-
-The CPU virtual address and the DMA bus address are both
-guaranteed to be aligned to the smallest PAGE_SIZE order which
-is greater than or equal to the requested size. This invariant
-exists (for example) to guarantee that if you allocate a chunk
-which is smaller than or equal to 64 kilobytes, the extent of the
-buffer you receive will not cross a 64K boundary.
-
-To unmap and free such a DMA region, you call:
-
- dma_free_coherent(dev, size, cpu_addr, dma_handle);
-
-where dev, size are the same as in the above call and cpu_addr and
-dma_handle are the values dma_alloc_coherent() returned to you.
-This function may not be called in interrupt context.
-
-If your driver needs lots of smaller memory regions, you can write
-custom code to subdivide pages returned by dma_alloc_coherent(),
-or you can use the dma_pool API to do that. A dma_pool is like
-a kmem_cache, but it uses dma_alloc_coherent(), not __get_free_pages().
-Also, it understands common hardware constraints for alignment,
-like queue heads needing to be aligned on N byte boundaries.
-
-Create a dma_pool like this:
-
- struct dma_pool *pool;
-
- pool = dma_pool_create(name, dev, size, align, boundary);
-
-The "name" is for diagnostics (like a kmem_cache name); dev and size
-are as above. The device's hardware alignment requirement for this
-type of data is "align" (which is expressed in bytes, and must be a
-power of two). If your device has no boundary crossing restrictions,
-pass 0 for boundary; passing 4096 says memory allocated from this pool
-must not cross 4KByte boundaries (but at that time it may be better to
-use dma_alloc_coherent() directly instead).
-
-Allocate memory from a DMA pool like this:
-
- cpu_addr = dma_pool_alloc(pool, flags, &dma_handle);
-
-flags are GFP_KERNEL if blocking is permitted (not in_interrupt nor
-holding SMP locks), GFP_ATOMIC otherwise. Like dma_alloc_coherent(),
-this returns two values, cpu_addr and dma_handle.
-
-Free memory that was allocated from a dma_pool like this:
-
- dma_pool_free(pool, cpu_addr, dma_handle);
-
-where pool is what you passed to dma_pool_alloc(), and cpu_addr and
-dma_handle are the values dma_pool_alloc() returned. This function
-may be called in interrupt context.
-
-Destroy a dma_pool by calling:
-
- dma_pool_destroy(pool);
-
-Make sure you've called dma_pool_free() for all memory allocated
-from a pool before you destroy the pool. This function may not
-be called in interrupt context.
-
- DMA Direction
-
-The interfaces described in subsequent portions of this document
-take a DMA direction argument, which is an integer and takes on
-one of the following values:
-
- DMA_BIDIRECTIONAL
- DMA_TO_DEVICE
- DMA_FROM_DEVICE
- DMA_NONE
-
-You should provide the exact DMA direction if you know it.
-
-DMA_TO_DEVICE means "from main memory to the device"
-DMA_FROM_DEVICE means "from the device to main memory"
-It is the direction in which the data moves during the DMA
-transfer.
-
-You are _strongly_ encouraged to specify this as precisely
-as you possibly can.
-
-If you absolutely cannot know the direction of the DMA transfer,
-specify DMA_BIDIRECTIONAL. It means that the DMA can go in
-either direction. The platform guarantees that you may legally
-specify this, and that it will work, but this may be at the
-cost of performance for example.
-
-The value DMA_NONE is to be used for debugging. One can
-hold this in a data structure before you come to know the
-precise direction, and this will help catch cases where your
-direction tracking logic has failed to set things up properly.
-
-Another advantage of specifying this value precisely (outside of
-potential platform-specific optimizations of such) is for debugging.
-Some platforms actually have a write permission boolean which DMA
-mappings can be marked with, much like page protections in the user
-program address space. Such platforms can and do report errors in the
-kernel logs when the DMA controller hardware detects violation of the
-permission setting.
-
-Only streaming mappings specify a direction, consistent mappings
-implicitly have a direction attribute setting of
-DMA_BIDIRECTIONAL.
-
-The SCSI subsystem tells you the direction to use in the
-'sc_data_direction' member of the SCSI command your driver is
-working on.
-
-For Networking drivers, it's a rather simple affair. For transmit
-packets, map/unmap them with the DMA_TO_DEVICE direction
-specifier. For receive packets, just the opposite, map/unmap them
-with the DMA_FROM_DEVICE direction specifier.
-
- Using Streaming DMA mappings
-
-The streaming DMA mapping routines can be called from interrupt
-context. There are two versions of each map/unmap, one which will
-map/unmap a single memory region, and one which will map/unmap a
-scatterlist.
-
-To map a single region, you do:
-
- struct device *dev = &my_dev->dev;
- dma_addr_t dma_handle;
- void *addr = buffer->ptr;
- size_t size = buffer->len;
-
- dma_handle = dma_map_single(dev, addr, size, direction);
- if (dma_mapping_error(dev, dma_handle)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling;
- }
-
-and to unmap it:
-
- dma_unmap_single(dev, dma_handle, size, direction);
-
-You should call dma_mapping_error() as dma_map_single() could fail and return
-error. Not all DMA implementations support the dma_mapping_error() interface.
-However, it is a good practice to call dma_mapping_error() interface, which
-will invoke the generic mapping error check interface. Doing so will ensure
-that the mapping code will work correctly on all DMA implementations without
-any dependency on the specifics of the underlying implementation. Using the
-returned address without checking for errors could result in failures ranging
-from panics to silent data corruption. A couple of examples of incorrect ways
-to check for errors that make assumptions about the underlying DMA
-implementation are as follows and these are applicable to dma_map_page() as
-well.
-
-Incorrect example 1:
- dma_addr_t dma_handle;
-
- dma_handle = dma_map_single(dev, addr, size, direction);
- if ((dma_handle & 0xffff != 0) || (dma_handle >= 0x1000000)) {
- goto map_error;
- }
-
-Incorrect example 2:
- dma_addr_t dma_handle;
-
- dma_handle = dma_map_single(dev, addr, size, direction);
- if (dma_handle == DMA_ERROR_CODE) {
- goto map_error;
- }
-
-You should call dma_unmap_single() when the DMA activity is finished, e.g.,
-from the interrupt which told you that the DMA transfer is done.
-
-Using CPU pointers like this for single mappings has a disadvantage:
-you cannot reference HIGHMEM memory in this way. Thus, there is a
-map/unmap interface pair akin to dma_{map,unmap}_single(). These
-interfaces deal with page/offset pairs instead of CPU pointers.
-Specifically:
-
- struct device *dev = &my_dev->dev;
- dma_addr_t dma_handle;
- struct page *page = buffer->page;
- unsigned long offset = buffer->offset;
- size_t size = buffer->len;
-
- dma_handle = dma_map_page(dev, page, offset, size, direction);
- if (dma_mapping_error(dev, dma_handle)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling;
- }
-
- ...
-
- dma_unmap_page(dev, dma_handle, size, direction);
-
-Here, "offset" means byte offset within the given page.
-
-You should call dma_mapping_error() as dma_map_page() could fail and return
-error as outlined under the dma_map_single() discussion.
-
-You should call dma_unmap_page() when the DMA activity is finished, e.g.,
-from the interrupt which told you that the DMA transfer is done.
-
-With scatterlists, you map a region gathered from several regions by:
-
- int i, count = dma_map_sg(dev, sglist, nents, direction);
- struct scatterlist *sg;
-
- for_each_sg(sglist, sg, count, i) {
- hw_address[i] = sg_dma_address(sg);
- hw_len[i] = sg_dma_len(sg);
- }
-
-where nents is the number of entries in the sglist.
-
-The implementation is free to merge several consecutive sglist entries
-into one (e.g. if DMA mapping is done with PAGE_SIZE granularity, any
-consecutive sglist entries can be merged into one provided the first one
-ends and the second one starts on a page boundary - in fact this is a huge
-advantage for cards which either cannot do scatter-gather or have very
-limited number of scatter-gather entries) and returns the actual number
-of sg entries it mapped them to. On failure 0 is returned.
-
-Then you should loop count times (note: this can be less than nents times)
-and use sg_dma_address() and sg_dma_len() macros where you previously
-accessed sg->address and sg->length as shown above.
-
-To unmap a scatterlist, just call:
-
- dma_unmap_sg(dev, sglist, nents, direction);
-
-Again, make sure DMA activity has already finished.
-
-PLEASE NOTE: The 'nents' argument to the dma_unmap_sg call must be
- the _same_ one you passed into the dma_map_sg call,
- it should _NOT_ be the 'count' value _returned_ from the
- dma_map_sg call.
-
-Every dma_map_{single,sg}() call should have its dma_unmap_{single,sg}()
-counterpart, because the bus address space is a shared resource and
-you could render the machine unusable by consuming all bus addresses.
-
-If you need to use the same streaming DMA region multiple times and touch
-the data in between the DMA transfers, the buffer needs to be synced
-properly in order for the CPU and device to see the most up-to-date and
-correct copy of the DMA buffer.
-
-So, firstly, just map it with dma_map_{single,sg}(), and after each DMA
-transfer call either:
-
- dma_sync_single_for_cpu(dev, dma_handle, size, direction);
-
-or:
-
- dma_sync_sg_for_cpu(dev, sglist, nents, direction);
-
-as appropriate.
-
-Then, if you wish to let the device get at the DMA area again,
-finish accessing the data with the CPU, and then before actually
-giving the buffer to the hardware call either:
-
- dma_sync_single_for_device(dev, dma_handle, size, direction);
-
-or:
-
- dma_sync_sg_for_device(dev, sglist, nents, direction);
-
-as appropriate.
-
-After the last DMA transfer call one of the DMA unmap routines
-dma_unmap_{single,sg}(). If you don't touch the data from the first
-dma_map_*() call till dma_unmap_*(), then you don't have to call the
-dma_sync_*() routines at all.
-
-Here is pseudo code which shows a situation in which you would need
-to use the dma_sync_*() interfaces.
-
- my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)
- {
- dma_addr_t mapping;
-
- mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE);
- if (dma_mapping_error(cp->dev, dma_handle)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling;
- }
-
- cp->rx_buf = buffer;
- cp->rx_len = len;
- cp->rx_dma = mapping;
-
- give_rx_buf_to_card(cp);
- }
-
- ...
-
- my_card_interrupt_handler(int irq, void *devid, struct pt_regs *regs)
- {
- struct my_card *cp = devid;
-
- ...
- if (read_card_status(cp) == RX_BUF_TRANSFERRED) {
- struct my_card_header *hp;
-
- /* Examine the header to see if we wish
- * to accept the data. But synchronize
- * the DMA transfer with the CPU first
- * so that we see updated contents.
- */
- dma_sync_single_for_cpu(&cp->dev, cp->rx_dma,
- cp->rx_len,
- DMA_FROM_DEVICE);
-
- /* Now it is safe to examine the buffer. */
- hp = (struct my_card_header *) cp->rx_buf;
- if (header_is_ok(hp)) {
- dma_unmap_single(&cp->dev, cp->rx_dma, cp->rx_len,
- DMA_FROM_DEVICE);
- pass_to_upper_layers(cp->rx_buf);
- make_and_setup_new_rx_buf(cp);
- } else {
- /* CPU should not write to
- * DMA_FROM_DEVICE-mapped area,
- * so dma_sync_single_for_device() is
- * not needed here. It would be required
- * for DMA_BIDIRECTIONAL mapping if
- * the memory was modified.
- */
- give_rx_buf_to_card(cp);
- }
- }
- }
-
-Drivers converted fully to this interface should not use virt_to_bus() any
-longer, nor should they use bus_to_virt(). Some drivers have to be changed a
-little bit, because there is no longer an equivalent to bus_to_virt() in the
-dynamic DMA mapping scheme - you have to always store the DMA addresses
-returned by the dma_alloc_coherent(), dma_pool_alloc(), and dma_map_single()
-calls (dma_map_sg() stores them in the scatterlist itself if the platform
-supports dynamic DMA mapping in hardware) in your driver structures and/or
-in the card registers.
-
-All drivers should be using these interfaces with no exceptions. It
-is planned to completely remove virt_to_bus() and bus_to_virt() as
-they are entirely deprecated. Some ports already do not provide these
-as it is impossible to correctly support them.
-
- Handling Errors
-
-DMA address space is limited on some architectures and an allocation
-failure can be determined by:
-
-- checking if dma_alloc_coherent() returns NULL or dma_map_sg returns 0
-
-- checking the dma_addr_t returned from dma_map_single() and dma_map_page()
- by using dma_mapping_error():
-
- dma_addr_t dma_handle;
-
- dma_handle = dma_map_single(dev, addr, size, direction);
- if (dma_mapping_error(dev, dma_handle)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling;
- }
-
-- unmap pages that are already mapped, when mapping error occurs in the middle
- of a multiple page mapping attempt. These example are applicable to
- dma_map_page() as well.
-
-Example 1:
- dma_addr_t dma_handle1;
- dma_addr_t dma_handle2;
-
- dma_handle1 = dma_map_single(dev, addr, size, direction);
- if (dma_mapping_error(dev, dma_handle1)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling1;
- }
- dma_handle2 = dma_map_single(dev, addr, size, direction);
- if (dma_mapping_error(dev, dma_handle2)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling2;
- }
-
- ...
-
- map_error_handling2:
- dma_unmap_single(dma_handle1);
- map_error_handling1:
-
-Example 2: (if buffers are allocated in a loop, unmap all mapped buffers when
- mapping error is detected in the middle)
-
- dma_addr_t dma_addr;
- dma_addr_t array[DMA_BUFFERS];
- int save_index = 0;
-
- for (i = 0; i < DMA_BUFFERS; i++) {
-
- ...
-
- dma_addr = dma_map_single(dev, addr, size, direction);
- if (dma_mapping_error(dev, dma_addr)) {
- /*
- * reduce current DMA mapping usage,
- * delay and try again later or
- * reset driver.
- */
- goto map_error_handling;
- }
- array[i].dma_addr = dma_addr;
- save_index++;
- }
-
- ...
-
- map_error_handling:
-
- for (i = 0; i < save_index; i++) {
-
- ...
-
- dma_unmap_single(array[i].dma_addr);
- }
-
-Networking drivers must call dev_kfree_skb() to free the socket buffer
-and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook
-(ndo_start_xmit). This means that the socket buffer is just dropped in
-the failure case.
-
-SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping
-fails in the queuecommand hook. This means that the SCSI subsystem
-passes the command to the driver again later.
-
- Optimizing Unmap State Space Consumption
-
-On many platforms, dma_unmap_{single,page}() is simply a nop.
-Therefore, keeping track of the mapping address and length is a waste
-of space. Instead of filling your drivers up with ifdefs and the like
-to "work around" this (which would defeat the whole purpose of a
-portable API) the following facilities are provided.
-
-Actually, instead of describing the macros one by one, we'll
-transform some example code.
-
-1) Use DEFINE_DMA_UNMAP_{ADDR,LEN} in state saving structures.
- Example, before:
-
- struct ring_state {
- struct sk_buff *skb;
- dma_addr_t mapping;
- __u32 len;
- };
-
- after:
-
- struct ring_state {
- struct sk_buff *skb;
- DEFINE_DMA_UNMAP_ADDR(mapping);
- DEFINE_DMA_UNMAP_LEN(len);
- };
-
-2) Use dma_unmap_{addr,len}_set() to set these values.
- Example, before:
-
- ringp->mapping = FOO;
- ringp->len = BAR;
-
- after:
-
- dma_unmap_addr_set(ringp, mapping, FOO);
- dma_unmap_len_set(ringp, len, BAR);
-
-3) Use dma_unmap_{addr,len}() to access these values.
- Example, before:
-
- dma_unmap_single(dev, ringp->mapping, ringp->len,
- DMA_FROM_DEVICE);
-
- after:
-
- dma_unmap_single(dev,
- dma_unmap_addr(ringp, mapping),
- dma_unmap_len(ringp, len),
- DMA_FROM_DEVICE);
-
-It really should be self-explanatory. We treat the ADDR and LEN
-separately, because it is possible for an implementation to only
-need the address in order to perform the unmap operation.
-
- Platform Issues
-
-If you are just writing drivers for Linux and do not maintain
-an architecture port for the kernel, you can safely skip down
-to "Closing".
-
-1) Struct scatterlist requirements.
-
- Don't invent the architecture specific struct scatterlist; just use
- <asm-generic/scatterlist.h>. You need to enable
- CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs
- (including software IOMMU).
-
-2) ARCH_DMA_MINALIGN
-
- Architectures must ensure that kmalloc'ed buffer is
- DMA-safe. Drivers and subsystems depend on it. If an architecture
- isn't fully DMA-coherent (i.e. hardware doesn't ensure that data in
- the CPU cache is identical to data in main memory),
- ARCH_DMA_MINALIGN must be set so that the memory allocator
- makes sure that kmalloc'ed buffer doesn't share a cache line with
- the others. See arch/arm/include/asm/cache.h as an example.
-
- Note that ARCH_DMA_MINALIGN is about DMA memory alignment
- constraints. You don't need to worry about the architecture data
- alignment constraints (e.g. the alignment constraints about 64-bit
- objects).
-
-3) Supporting multiple types of IOMMUs
-
- If your architecture needs to support multiple types of IOMMUs, you
- can use include/linux/asm-generic/dma-mapping-common.h. It's a
- library to support the DMA API with multiple types of IOMMUs. Lots
- of architectures (x86, powerpc, sh, alpha, ia64, microblaze and
- sparc) use it. Choose one to see how it can be used. If you need to
- support multiple types of IOMMUs in a single system, the example of
- x86 or powerpc helps.
-
- Closing
-
-This document, and the API itself, would not be in its current
-form without the feedback and suggestions from numerous individuals.
-We would like to specifically mention, in no particular order, the
-following people:
-
- Russell King <rmk@arm.linux.org.uk>
- Leo Dagum <dagum@barrel.engr.sgi.com>
- Ralf Baechle <ralf@oss.sgi.com>
- Grant Grundler <grundler@cup.hp.com>
- Jay Estabrook <Jay.Estabrook@compaq.com>
- Thomas Sailer <sailer@ife.ee.ethz.ch>
- Andrea Arcangeli <andrea@suse.de>
- Jens Axboe <jens.axboe@oracle.com>
- David Mosberger-Tang <davidm@hpl.hp.com>
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
deleted file mode 100644
index 52088408668a..000000000000
--- a/Documentation/DMA-API.txt
+++ /dev/null
@@ -1,704 +0,0 @@
- Dynamic DMA mapping using the generic device
- ============================================
-
- James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
-
-This document describes the DMA API. For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
-
-This API is split into two pieces. Part I describes the basic API.
-Part II describes extensions for supporting non-consistent memory
-machines. Unless you know that your driver absolutely has to support
-non-consistent platforms (this is usually only legacy platforms) you
-should only use the API described in part I.
-
-Part I - dma_ API
--------------------------------------
-
-To get the dma_ API, you must #include <linux/dma-mapping.h>. This
-provides dma_addr_t and the interfaces described below.
-
-A dma_addr_t can hold any valid DMA or bus address for the platform. It
-can be given to a device to use as a DMA source or target. A CPU cannot
-reference a dma_addr_t directly because there may be translation between
-its physical address space and the bus address space.
-
-Part Ia - Using large DMA-coherent buffers
-------------------------------------------
-
-void *
-dma_alloc_coherent(struct device *dev, size_t size,
- dma_addr_t *dma_handle, gfp_t flag)
-
-Consistent memory is memory for which a write by either the device or
-the processor can immediately be read by the processor or device
-without having to worry about caching effects. (You may however need
-to make sure to flush the processor's write buffers before telling
-devices to read that memory.)
-
-This routine allocates a region of <size> bytes of consistent memory.
-
-It returns a pointer to the allocated region (in the processor's virtual
-address space) or NULL if the allocation failed.
-
-It also returns a <dma_handle> which may be cast to an unsigned integer the
-same width as the bus and given to the device as the bus address base of
-the region.
-
-Note: consistent memory can be expensive on some platforms, and the
-minimum allocation length may be as big as a page, so you should
-consolidate your requests for consistent memory as much as possible.
-The simplest way to do that is to use the dma_pool calls (see below).
-
-The flag parameter (dma_alloc_coherent() only) allows the caller to
-specify the GFP_ flags (see kmalloc()) for the allocation (the
-implementation may choose to ignore flags that affect the location of
-the returned memory, like GFP_DMA).
-
-void *
-dma_zalloc_coherent(struct device *dev, size_t size,
- dma_addr_t *dma_handle, gfp_t flag)
-
-Wraps dma_alloc_coherent() and also zeroes the returned memory if the
-allocation attempt succeeded.
-
-void
-dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
- dma_addr_t dma_handle)
-
-Free a region of consistent memory you previously allocated. dev,
-size and dma_handle must all be the same as those passed into
-dma_alloc_coherent(). cpu_addr must be the virtual address returned by
-the dma_alloc_coherent().
-
-Note that unlike their sibling allocation calls, these routines
-may only be called with IRQs enabled.
-
-
-Part Ib - Using small DMA-coherent buffers
-------------------------------------------
-
-To get this part of the dma_ API, you must #include <linux/dmapool.h>
-
-Many drivers need lots of small DMA-coherent memory regions for DMA
-descriptors or I/O buffers. Rather than allocating in units of a page
-or more using dma_alloc_coherent(), you can use DMA pools. These work
-much like a struct kmem_cache, except that they use the DMA-coherent allocator,
-not __get_free_pages(). Also, they understand common hardware constraints
-for alignment, like queue heads needing to be aligned on N-byte boundaries.
-
-
- struct dma_pool *
- dma_pool_create(const char *name, struct device *dev,
- size_t size, size_t align, size_t alloc);
-
-dma_pool_create() initializes a pool of DMA-coherent buffers
-for use with a given device. It must be called in a context which
-can sleep.
-
-The "name" is for diagnostics (like a struct kmem_cache name); dev and size
-are like what you'd pass to dma_alloc_coherent(). The device's hardware
-alignment requirement for this type of data is "align" (which is expressed
-in bytes, and must be a power of two). If your device has no boundary
-crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
-from this pool must not cross 4KByte boundaries.
-
-
- void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
- dma_addr_t *dma_handle);
-
-This allocates memory from the pool; the returned memory will meet the
-size and alignment requirements specified at creation time. Pass
-GFP_ATOMIC to prevent blocking, or if it's permitted (not
-in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow
-blocking. Like dma_alloc_coherent(), this returns two values: an
-address usable by the CPU, and the DMA address usable by the pool's
-device.
-
-
- void dma_pool_free(struct dma_pool *pool, void *vaddr,
- dma_addr_t addr);
-
-This puts memory back into the pool. The pool is what was passed to
-dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
-were returned when that routine allocated the memory being freed.
-
-
- void dma_pool_destroy(struct dma_pool *pool);
-
-dma_pool_destroy() frees the resources of the pool. It must be
-called in a context which can sleep. Make sure you've freed all allocated
-memory back to the pool before you destroy it.
-
-
-Part Ic - DMA addressing limitations
-------------------------------------
-
-int
-dma_supported(struct device *dev, u64 mask)
-
-Checks to see if the device can support DMA to the memory described by
-mask.
-
-Returns: 1 if it can and 0 if it can't.
-
-Notes: This routine merely tests to see if the mask is possible. It
-won't change the current mask settings. It is more intended as an
-internal API for use by the platform than an external API for use by
-driver writers.
-
-int
-dma_set_mask_and_coherent(struct device *dev, u64 mask)
-
-Checks to see if the mask is possible and updates the device
-streaming and coherent DMA mask parameters if it is.
-
-Returns: 0 if successful and a negative error if not.
-
-int
-dma_set_mask(struct device *dev, u64 mask)
-
-Checks to see if the mask is possible and updates the device
-parameters if it is.
-
-Returns: 0 if successful and a negative error if not.
-
-int
-dma_set_coherent_mask(struct device *dev, u64 mask)
-
-Checks to see if the mask is possible and updates the device
-parameters if it is.
-
-Returns: 0 if successful and a negative error if not.
-
-u64
-dma_get_required_mask(struct device *dev)
-
-This API returns the mask that the platform requires to
-operate efficiently. Usually this means the returned mask
-is the minimum required to cover all of memory. Examining the
-required mask gives drivers with variable descriptor sizes the
-opportunity to use smaller descriptors as necessary.
-
-Requesting the required mask does not alter the current mask. If you
-wish to take advantage of it, you should issue a dma_set_mask()
-call to set the mask to the value returned.
-
-
-Part Id - Streaming DMA mappings
---------------------------------
-
-dma_addr_t
-dma_map_single(struct device *dev, void *cpu_addr, size_t size,
- enum dma_data_direction direction)
-
-Maps a piece of processor virtual memory so it can be accessed by the
-device and returns the bus address of the memory.
-
-The direction for both APIs may be converted freely by casting.
-However the dma_ API uses a strongly typed enumerator for its
-direction:
-
-DMA_NONE no direction (used for debugging)
-DMA_TO_DEVICE data is going from the memory to the device
-DMA_FROM_DEVICE data is coming from the device to the memory
-DMA_BIDIRECTIONAL direction isn't known
-
-Notes: Not all memory regions in a machine can be mapped by this API.
-Further, contiguous kernel virtual space may not be contiguous as
-physical memory. Since this API does not provide any scatter/gather
-capability, it will fail if the user tries to map a non-physically
-contiguous piece of memory. For this reason, memory to be mapped by
-this API should be obtained from sources which guarantee it to be
-physically contiguous (like kmalloc).
-
-Further, the bus address of the memory must be within the
-dma_mask of the device (the dma_mask is a bit mask of the
-addressable region for the device, i.e., if the bus address of
-the memory ANDed with the dma_mask is still equal to the bus
-address, then the device can perform DMA to the memory). To
-ensure that the memory allocated by kmalloc is within the dma_mask,
-the driver may specify various platform-dependent flags to restrict
-the bus address range of the allocation (e.g., on x86, GFP_DMA
-guarantees to be within the first 16MB of available bus addresses,
-as required by ISA devices).
-
-Note also that the above constraints on physical contiguity and
-dma_mask may not apply if the platform has an IOMMU (a device which
-maps an I/O bus address to a physical memory address). However, to be
-portable, device driver writers may *not* assume that such an IOMMU
-exists.
-
-Warnings: Memory coherency operates at a granularity called the cache
-line width. In order for memory mapped by this API to operate
-correctly, the mapped region must begin exactly on a cache line
-boundary and end exactly on one (to prevent two separately mapped
-regions from sharing a single cache line). Since the cache line size
-may not be known at compile time, the API will not enforce this
-requirement. Therefore, it is recommended that driver writers who
-don't take special care to determine the cache line size at run time
-only map virtual regions that begin and end on page boundaries (which
-are guaranteed also to be cache line boundaries).
-
-DMA_TO_DEVICE synchronisation must be done after the last modification
-of the memory region by the software and before it is handed off to
-the driver. Once this primitive is used, memory covered by this
-primitive should be treated as read-only by the device. If the device
-may write to it at any point, it should be DMA_BIDIRECTIONAL (see
-below).
-
-DMA_FROM_DEVICE synchronisation must be done before the driver
-accesses data that may be changed by the device. This memory should
-be treated as read-only by the driver. If the driver needs to write
-to it at any point, it should be DMA_BIDIRECTIONAL (see below).
-
-DMA_BIDIRECTIONAL requires special handling: it means that the driver
-isn't sure if the memory was modified before being handed off to the
-device and also isn't sure if the device will also modify it. Thus,
-you must always sync bidirectional memory twice: once before the
-memory is handed off to the device (to make sure all memory changes
-are flushed from the processor) and once before the data may be
-accessed after being used by the device (to make sure any processor
-cache lines are updated with data that the device may have changed).
-
-void
-dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
- enum dma_data_direction direction)
-
-Unmaps the region previously mapped. All the parameters passed in
-must be identical to those passed in (and returned) by the mapping
-API.
-
-dma_addr_t
-dma_map_page(struct device *dev, struct page *page,
- unsigned long offset, size_t size,
- enum dma_data_direction direction)
-void
-dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
- enum dma_data_direction direction)
-
-API for mapping and unmapping for pages. All the notes and warnings
-for the other mapping APIs apply here. Also, although the <offset>
-and <size> parameters are provided to do partial page mapping, it is
-recommended that you never use these unless you really know what the
-cache width is.
-
-int
-dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
-
-In some circumstances dma_map_single() and dma_map_page() will fail to create
-a mapping. A driver can check for these errors by testing the returned
-DMA address with dma_mapping_error(). A non-zero return value means the mapping
-could not be created and the driver should take appropriate action (e.g.
-reduce current DMA mapping usage or delay and try again later).
-
- int
- dma_map_sg(struct device *dev, struct scatterlist *sg,
- int nents, enum dma_data_direction direction)
-
-Returns: the number of bus address segments mapped (this may be shorter
-than <nents> passed in if some elements of the scatter/gather list are
-physically or virtually adjacent and an IOMMU maps them with a single
-entry).
-
-Please note that the sg cannot be mapped again if it has been mapped once.
-The mapping process is allowed to destroy information in the sg.
-
-As with the other mapping interfaces, dma_map_sg() can fail. When it
-does, 0 is returned and a driver must take appropriate action. It is
-critical that the driver do something, in the case of a block driver
-aborting the request or even oopsing is better than doing nothing and
-corrupting the filesystem.
-
-With scatterlists, you use the resulting mapping like this:
-
- int i, count = dma_map_sg(dev, sglist, nents, direction);
- struct scatterlist *sg;
-
- for_each_sg(sglist, sg, count, i) {
- hw_address[i] = sg_dma_address(sg);
- hw_len[i] = sg_dma_len(sg);
- }
-
-where nents is the number of entries in the sglist.
-
-The implementation is free to merge several consecutive sglist entries
-into one (e.g. with an IOMMU, or if several pages just happen to be
-physically contiguous) and returns the actual number of sg entries it
-mapped them to. On failure 0, is returned.
-
-Then you should loop count times (note: this can be less than nents times)
-and use sg_dma_address() and sg_dma_len() macros where you previously
-accessed sg->address and sg->length as shown above.
-
- void
- dma_unmap_sg(struct device *dev, struct scatterlist *sg,
- int nhwentries, enum dma_data_direction direction)
-
-Unmap the previously mapped scatter/gather list. All the parameters
-must be the same as those and passed in to the scatter/gather mapping
-API.
-
-Note: <nents> must be the number you passed in, *not* the number of
-bus address entries returned.
-
-void
-dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
- enum dma_data_direction direction)
-void
-dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size,
- enum dma_data_direction direction)
-void
-dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems,
- enum dma_data_direction direction)
-void
-dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems,
- enum dma_data_direction direction)
-
-Synchronise a single contiguous or scatter/gather mapping for the CPU
-and device. With the sync_sg API, all the parameters must be the same
-as those passed into the single mapping API. With the sync_single API,
-you can use dma_handle and size parameters that aren't identical to
-those passed into the single mapping API to do a partial sync.
-
-Notes: You must do this:
-
-- Before reading values that have been written by DMA from the device
- (use the DMA_FROM_DEVICE direction)
-- After writing values that will be written to the device using DMA
- (use the DMA_TO_DEVICE) direction
-- before *and* after handing memory to the device if the memory is
- DMA_BIDIRECTIONAL
-
-See also dma_map_single().
-
-dma_addr_t
-dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
- enum dma_data_direction dir,
- struct dma_attrs *attrs)
-
-void
-dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
- size_t size, enum dma_data_direction dir,
- struct dma_attrs *attrs)
-
-int
-dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
- int nents, enum dma_data_direction dir,
- struct dma_attrs *attrs)
-
-void
-dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
- int nents, enum dma_data_direction dir,
- struct dma_attrs *attrs)
-
-The four functions above are just like the counterpart functions
-without the _attrs suffixes, except that they pass an optional
-struct dma_attrs*.
-
-struct dma_attrs encapsulates a set of "DMA attributes". For the
-definition of struct dma_attrs see linux/dma-attrs.h.
-
-The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.txt.
-
-If struct dma_attrs* is NULL, the semantics of each of these
-functions is identical to those of the corresponding function
-without the _attrs suffix. As a result dma_map_single_attrs()
-can generally replace dma_map_single(), etc.
-
-As an example of the use of the *_attrs functions, here's how
-you could pass an attribute DMA_ATTR_FOO when mapping memory
-for DMA:
-
-#include <linux/dma-attrs.h>
-/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and
- * documented in Documentation/DMA-attributes.txt */
-...
-
- DEFINE_DMA_ATTRS(attrs);
- dma_set_attr(DMA_ATTR_FOO, &attrs);
- ....
- n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
- ....
-
-Architectures that care about DMA_ATTR_FOO would check for its
-presence in their implementations of the mapping and unmapping
-routines, e.g.:
-
-void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
- size_t size, enum dma_data_direction dir,
- struct dma_attrs *attrs)
-{
- ....
- int foo = dma_get_attr(DMA_ATTR_FOO, attrs);
- ....
- if (foo)
- /* twizzle the frobnozzle */
- ....
-
-
-Part II - Advanced dma_ usage
------------------------------
-
-Warning: These pieces of the DMA API should not be used in the
-majority of cases, since they cater for unlikely corner cases that
-don't belong in usual drivers.
-
-If you don't understand how cache line coherency works between a
-processor and an I/O device, you should not be using this part of the
-API at all.
-
-void *
-dma_alloc_noncoherent(struct device *dev, size_t size,
- dma_addr_t *dma_handle, gfp_t flag)
-
-Identical to dma_alloc_coherent() except that the platform will
-choose to return either consistent or non-consistent memory as it sees
-fit. By using this API, you are guaranteeing to the platform that you
-have all the correct and necessary sync points for this memory in the
-driver should it choose to return non-consistent memory.
-
-Note: where the platform can return consistent memory, it will
-guarantee that the sync points become nops.
-
-Warning: Handling non-consistent memory is a real pain. You should
-only use this API if you positively know your driver will be
-required to work on one of the rare (usually non-PCI) architectures
-that simply cannot make consistent memory.
-
-void
-dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
- dma_addr_t dma_handle)
-
-Free memory allocated by the nonconsistent API. All parameters must
-be identical to those passed in (and returned by
-dma_alloc_noncoherent()).
-
-int
-dma_get_cache_alignment(void)
-
-Returns the processor cache alignment. This is the absolute minimum
-alignment *and* width that you must observe when either mapping
-memory or doing partial flushes.
-
-Notes: This API may return a number *larger* than the actual cache
-line, but it will guarantee that one or more cache lines fit exactly
-into the width returned by this call. It will also always be a power
-of two for easy alignment.
-
-void
-dma_cache_sync(struct device *dev, void *vaddr, size_t size,
- enum dma_data_direction direction)
-
-Do a partial sync of memory that was allocated by
-dma_alloc_noncoherent(), starting at virtual address vaddr and
-continuing on for size. Again, you *must* observe the cache line
-boundaries when doing this.
-
-int
-dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
- dma_addr_t device_addr, size_t size, int
- flags)
-
-Declare region of memory to be handed out by dma_alloc_coherent() when
-it's asked for coherent memory for this device.
-
-phys_addr is the CPU physical address to which the memory is currently
-assigned (this will be ioremapped so the CPU can access the region).
-
-device_addr is the bus address the device needs to be programmed
-with to actually address this memory (this will be handed out as the
-dma_addr_t in dma_alloc_coherent()).
-
-size is the size of the area (must be multiples of PAGE_SIZE).
-
-flags can be ORed together and are:
-
-DMA_MEMORY_MAP - request that the memory returned from
-dma_alloc_coherent() be directly writable.
-
-DMA_MEMORY_IO - request that the memory returned from
-dma_alloc_coherent() be addressable using read()/write()/memcpy_toio() etc.
-
-One or both of these flags must be present.
-
-DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
-dma_alloc_coherent of any child devices of this one (for memory residing
-on a bridge).
-
-DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
-Do not allow dma_alloc_coherent() to fall back to system memory when
-it's out of memory in the declared region.
-
-The return value will be either DMA_MEMORY_MAP or DMA_MEMORY_IO and
-must correspond to a passed in flag (i.e. no returning DMA_MEMORY_IO
-if only DMA_MEMORY_MAP were passed in) for success or zero for
-failure.
-
-Note, for DMA_MEMORY_IO returns, all subsequent memory returned by
-dma_alloc_coherent() may no longer be accessed directly, but instead
-must be accessed using the correct bus functions. If your driver
-isn't prepared to handle this contingency, it should not specify
-DMA_MEMORY_IO in the input flags.
-
-As a simplification for the platforms, only *one* such region of
-memory may be declared per device.
-
-For reasons of efficiency, most platforms choose to track the declared
-region only at the granularity of a page. For smaller allocations,
-you should use the dma_pool() API.
-
-void
-dma_release_declared_memory(struct device *dev)
-
-Remove the memory region previously declared from the system. This
-API performs *no* in-use checking for this region and will return
-unconditionally having removed all the required structures. It is the
-driver's job to ensure that no parts of this memory region are
-currently in use.
-
-void *
-dma_mark_declared_memory_occupied(struct device *dev,
- dma_addr_t device_addr, size_t size)
-
-This is used to occupy specific regions of the declared space
-(dma_alloc_coherent() will hand out the first free region it finds).
-
-device_addr is the *device* address of the region requested.
-
-size is the size (and should be a page-sized multiple).
-
-The return value will be either a pointer to the processor virtual
-address of the memory, or an error (via PTR_ERR()) if any part of the
-region is occupied.
-
-Part III - Debug drivers use of the DMA-API
--------------------------------------------
-
-The DMA-API as described above has some constraints. DMA addresses must be
-released with the corresponding function with the same size for example. With
-the advent of hardware IOMMUs it becomes more and more important that drivers
-do not violate those constraints. In the worst case such a violation can
-result in data corruption up to destroyed filesystems.
-
-To debug drivers and find bugs in the usage of the DMA-API checking code can
-be compiled into the kernel which will tell the developer about those
-violations. If your architecture supports it you can select the "Enable
-debugging of DMA-API usage" option in your kernel configuration. Enabling this
-option has a performance impact. Do not enable it in production kernels.
-
-If you boot the resulting kernel will contain code which does some bookkeeping
-about what DMA memory was allocated for which device. If this code detects an
-error it prints a warning message with some details into your kernel log. An
-example warning message may look like this:
-
-------------[ cut here ]------------
-WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
- check_unmap+0x203/0x490()
-Hardware name:
-forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
- function [device address=0x00000000640444be] [size=66 bytes] [mapped as
-single] [unmapped as page]
-Modules linked in: nfsd exportfs bridge stp llc r8169
-Pid: 0, comm: swapper Tainted: G W 2.6.28-dmatest-09289-g8bb99c0 #1
-Call Trace:
- <IRQ> [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
- [<ffffffff80647b70>] _spin_unlock+0x10/0x30
- [<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
- [<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
- [<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
- [<ffffffff80252f96>] queue_work+0x56/0x60
- [<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
- [<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
- [<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
- [<ffffffff80235177>] find_busiest_group+0x207/0x8a0
- [<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
- [<ffffffff803c7ea3>] check_unmap+0x203/0x490
- [<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
- [<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
- [<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
- [<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
- [<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
- [<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
- [<ffffffff8020c093>] ret_from_intr+0x0/0xa
- <EOI> <4>---[ end trace f6435a98e2a38c0e ]---
-
-The driver developer can find the driver and the device including a stacktrace
-of the DMA-API call which caused this warning.
-
-Per default only the first error will result in a warning message. All other
-errors will only silently counted. This limitation exist to prevent the code
-from flooding your kernel log. To support debugging a device driver this can
-be disabled via debugfs. See the debugfs interface documentation below for
-details.
-
-The debugfs directory for the DMA-API debugging code is called dma-api/. In
-this directory the following files can currently be found:
-
- dma-api/all_errors This file contains a numeric value. If this
- value is not equal to zero the debugging code
- will print a warning for every error it finds
- into the kernel log. Be careful with this
- option, as it can easily flood your logs.
-
- dma-api/disabled This read-only file contains the character 'Y'
- if the debugging code is disabled. This can
- happen when it runs out of memory or if it was
- disabled at boot time
-
- dma-api/error_count This file is read-only and shows the total
- numbers of errors found.
-
- dma-api/num_errors The number in this file shows how many
- warnings will be printed to the kernel log
- before it stops. This number is initialized to
- one at system boot and be set by writing into
- this file
-
- dma-api/min_free_entries
- This read-only file can be read to get the
- minimum number of free dma_debug_entries the
- allocator has ever seen. If this value goes
- down to zero the code will disable itself
- because it is not longer reliable.
-
- dma-api/num_free_entries
- The current number of free dma_debug_entries
- in the allocator.
-
- dma-api/driver-filter
- You can write a name of a driver into this file
- to limit the debug output to requests from that
- particular driver. Write an empty string to
- that file to disable the filter and see
- all errors again.
-
-If you have this code compiled into your kernel it will be enabled by default.
-If you want to boot without the bookkeeping anyway you can provide
-'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
-Notice that you can not enable it again at runtime. You have to reboot to do
-so.
-
-If you want to see debug messages only for a special device driver you can
-specify the dma_debug_driver=<drivername> parameter. This will enable the
-driver filter at boot time. The debug code will only print errors for that
-driver afterwards. This filter can be disabled or changed later using debugfs.
-
-When the code disables itself at runtime this is most likely because it ran
-out of dma_debug_entries. These entries are preallocated at boot. The number
-of preallocated entries is defined per architecture. If it is too low for you
-boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
-architectural default.
-
-void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
-
-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
-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()
-routines to enable DMA mapping error check debugging.
-
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.txt
deleted file mode 100644
index b1a19835e907..000000000000
--- a/Documentation/DMA-ISA-LPC.txt
+++ /dev/null
@@ -1,151 +0,0 @@
- DMA with ISA and LPC devices
- ============================
-
- Pierre Ossman <drzeus@drzeus.cx>
-
-This document describes how to do DMA transfers using the old ISA DMA
-controller. Even though ISA is more or less dead today the LPC bus
-uses the same DMA system so it will be around for quite some time.
-
-Part I - Headers and dependencies
----------------------------------
-
-To do ISA style DMA you need to include two headers:
-
-#include <linux/dma-mapping.h>
-#include <asm/dma.h>
-
-The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.txt for details).
-
-The second contains the routines specific to ISA DMA transfers. Since
-this is not present on all platforms make sure you construct your
-Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
-to build your driver on unsupported platforms.
-
-Part II - Buffer allocation
----------------------------
-
-The ISA DMA controller has some very strict requirements on which
-memory it can access so extra care must be taken when allocating
-buffers.
-
-(You usually need a special buffer for DMA transfers instead of
-transferring directly to and from your normal data structures.)
-
-The DMA-able address space is the lowest 16 MB of _physical_ memory.
-Also the transfer block may not cross page boundaries (which are 64
-or 128 KiB depending on which channel you use).
-
-In order to allocate a piece of memory that satisfies all these
-requirements you pass the flag GFP_DMA to kmalloc.
-
-Unfortunately the memory available for ISA DMA is scarce so unless you
-allocate the memory during boot-up it's a good idea to also pass
-__GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder.
-
-(This scarcity also means that you should allocate the buffer as
-early as possible and not release it until the driver is unloaded.)
-
-Part III - Address translation
-------------------------------
-
-To translate the virtual address to a bus address, use the normal DMA
-API. Do _not_ use isa_virt_to_phys() even though it does the same
-thing. The reason for this is that the function isa_virt_to_phys()
-will require a Kconfig dependency to ISA, not just ISA_DMA_API which
-is really all you need. Remember that even though the DMA controller
-has its origins in ISA it is used elsewhere.
-
-Note: x86_64 had a broken DMA API when it came to ISA but has since
-been fixed. If your arch has problems then fix the DMA API instead of
-reverting to the ISA functions.
-
-Part IV - Channels
-------------------
-
-A normal ISA DMA controller has 8 channels. The lower four are for
-8-bit transfers and the upper four are for 16-bit transfers.
-
-(Actually the DMA controller is really two separate controllers where
-channel 4 is used to give DMA access for the second controller (0-3).
-This means that of the four 16-bits channels only three are usable.)
-
-You allocate these in a similar fashion as all basic resources:
-
-extern int request_dma(unsigned int dmanr, const char * device_id);
-extern void free_dma(unsigned int dmanr);
-
-The ability to use 16-bit or 8-bit transfers is _not_ up to you as a
-driver author but depends on what the hardware supports. Check your
-specs or test different channels.
-
-Part V - Transfer data
-----------------------
-
-Now for the good stuff, the actual DMA transfer. :)
-
-Before you use any ISA DMA routines you need to claim the DMA lock
-using claim_dma_lock(). The reason is that some DMA operations are
-not atomic so only one driver may fiddle with the registers at a
-time.
-
-The first time you use the DMA controller you should call
-clear_dma_ff(). This clears an internal register in the DMA
-controller that is used for the non-atomic operations. As long as you
-(and everyone else) uses the locking functions then you only need to
-reset this once.
-
-Next, you tell the controller in which direction you intend to do the
-transfer using set_dma_mode(). Currently you have the options
-DMA_MODE_READ and DMA_MODE_WRITE.
-
-Set the address from where the transfer should start (this needs to
-be 16-bit aligned for 16-bit transfers) and how many bytes to
-transfer. Note that it's _bytes_. The DMA routines will do all the
-required translation to values that the DMA controller understands.
-
-The final step is enabling the DMA channel and releasing the DMA
-lock.
-
-Once the DMA transfer is finished (or timed out) you should disable
-the channel again. You should also check get_dma_residue() to make
-sure that all data has been transferred.
-
-Example:
-
-int flags, residue;
-
-flags = claim_dma_lock();
-
-clear_dma_ff();
-
-set_dma_mode(channel, DMA_MODE_WRITE);
-set_dma_addr(channel, phys_addr);
-set_dma_count(channel, num_bytes);
-
-dma_enable(channel);
-
-release_dma_lock(flags);
-
-while (!device_done());
-
-flags = claim_dma_lock();
-
-dma_disable(channel);
-
-residue = dma_get_residue(channel);
-if (residue != 0)
- printk(KERN_ERR "driver: Incomplete DMA transfer!"
- " %d bytes left!\n", residue);
-
-release_dma_lock(flags);
-
-Part VI - Suspend/resume
-------------------------
-
-It is the driver's responsibility to make sure that the machine isn't
-suspended while a DMA transfer is in progress. Also, all DMA settings
-are lost when the system suspends so if your driver relies on the DMA
-controller being in a certain state then you have to restore these
-registers upon resume.
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt
deleted file mode 100644
index 18dc52c4f2a0..000000000000
--- a/Documentation/DMA-attributes.txt
+++ /dev/null
@@ -1,102 +0,0 @@
- DMA attributes
- ==============
-
-This document describes the semantics of the DMA attributes that are
-defined in linux/dma-attrs.h.
-
-DMA_ATTR_WRITE_BARRIER
-----------------------
-
-DMA_ATTR_WRITE_BARRIER is a (write) barrier attribute for DMA. DMA
-to a memory region with the DMA_ATTR_WRITE_BARRIER attribute forces
-all pending DMA writes to complete, and thus provides a mechanism to
-strictly order DMA from a device across all intervening busses and
-bridges. This barrier is not specific to a particular type of
-interconnect, it applies to the system as a whole, and so its
-implementation must account for the idiosyncrasies of the system all
-the way from the DMA device to memory.
-
-As an example of a situation where DMA_ATTR_WRITE_BARRIER would be
-useful, suppose that a device does a DMA write to indicate that data is
-ready and available in memory. The DMA of the "completion indication"
-could race with data DMA. Mapping the memory used for completion
-indications with DMA_ATTR_WRITE_BARRIER would prevent the race.
-
-DMA_ATTR_WEAK_ORDERING
-----------------------
-
-DMA_ATTR_WEAK_ORDERING specifies that reads and writes to the mapping
-may be weakly ordered, that is that reads and writes may pass each other.
-
-Since it is optional for platforms to implement DMA_ATTR_WEAK_ORDERING,
-those that do not will simply ignore the attribute and exhibit default
-behavior.
-
-DMA_ATTR_WRITE_COMBINE
-----------------------
-
-DMA_ATTR_WRITE_COMBINE specifies that writes to the mapping may be
-buffered to improve performance.
-
-Since it is optional for platforms to implement DMA_ATTR_WRITE_COMBINE,
-those that do not will simply ignore the attribute and exhibit default
-behavior.
-
-DMA_ATTR_NON_CONSISTENT
------------------------
-
-DMA_ATTR_NON_CONSISTENT lets the platform to choose to return either
-consistent or non-consistent memory as it sees fit. By using this API,
-you are guaranteeing to the platform that you have all the correct and
-necessary sync points for this memory in the driver.
-
-DMA_ATTR_NO_KERNEL_MAPPING
---------------------------
-
-DMA_ATTR_NO_KERNEL_MAPPING lets the platform to avoid creating a kernel
-virtual mapping for the allocated buffer. On some architectures creating
-such mapping is non-trivial task and consumes very limited resources
-(like kernel virtual address space or dma consistent address space).
-Buffers allocated with this attribute can be only passed to user space
-by calling dma_mmap_attrs(). By using this API, you are guaranteeing
-that you won't dereference the pointer returned by dma_alloc_attr(). You
-can treat it as a cookie that must be passed to dma_mmap_attrs() and
-dma_free_attrs(). Make sure that both of these also get this attribute
-set on each call.
-
-Since it is optional for platforms to implement
-DMA_ATTR_NO_KERNEL_MAPPING, those that do not will simply ignore the
-attribute and exhibit default behavior.
-
-DMA_ATTR_SKIP_CPU_SYNC
-----------------------
-
-By default dma_map_{single,page,sg} functions family transfer a given
-buffer from CPU domain to device domain. Some advanced use cases might
-require sharing a buffer between more than one device. This requires
-having a mapping created separately for each device and is usually
-performed by calling dma_map_{single,page,sg} function more than once
-for the given buffer with device pointer to each device taking part in
-the buffer sharing. The first call transfers a buffer from 'CPU' domain
-to 'device' domain, what synchronizes CPU caches for the given region
-(usually it means that the cache has been flushed or invalidated
-depending on the dma direction). However, next calls to
-dma_map_{single,page,sg}() for other devices will perform exactly the
-same synchronization operation on the CPU cache. CPU cache synchronization
-might be a time consuming operation, especially if the buffers are
-large, so it is highly recommended to avoid it if possible.
-DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchronization of
-the CPU cache for the given buffer assuming that it has been already
-transferred to 'device' domain. This attribute can be also used for
-dma_unmap_{single,page,sg} functions family to force buffer to stay in
-device domain after releasing a mapping for it. Use this attribute with
-care!
-
-DMA_ATTR_FORCE_CONTIGUOUS
--------------------------
-
-By default DMA-mapping subsystem is allowed to assemble the buffer
-allocated by dma_alloc_attrs() function from individual pages if it can
-be mapped as contiguous chunk into device dma address space. By
-specifying this attribute the allocated buffer is forced to be contiguous
-also in physical memory.
diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore
deleted file mode 100644
index 7ebd5465d927..000000000000
--- a/Documentation/DocBook/.gitignore
+++ /dev/null
@@ -1,15 +0,0 @@
-*.xml
-*.ps
-*.pdf
-*.html
-*.9.gz
-*.9
-*.aux
-*.dvi
-*.log
-*.out
-*.png
-*.gif
-*.svg
-media-indices.tmpl
-media-entities.tmpl
diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl
deleted file mode 100644
index aac9357d4866..000000000000
--- a/Documentation/DocBook/80211.tmpl
+++ /dev/null
@@ -1,582 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-<set>
- <setinfo>
- <title>The 802.11 subsystems &ndash; for kernel developers</title>
- <subtitle>
- Explaining wireless 802.11 networking in the Linux kernel
- </subtitle>
-
- <copyright>
- <year>2007-2009</year>
- <holder>Johannes Berg</holder>
- </copyright>
-
- <authorgroup>
- <author>
- <firstname>Johannes</firstname>
- <surname>Berg</surname>
- <affiliation>
- <address><email>johannes@sipsolutions.net</email></address>
- </affiliation>
- </author>
- </authorgroup>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
- <para>
- This documentation is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
- <para>
- You should have received a copy of the GNU General Public
- License along with this documentation; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
-
- <abstract>
- <para>
- These books attempt to give a description of the
- various subsystems that play a role in 802.11 wireless
- networking in Linux. Since these books are for kernel
- developers they attempts to document the structures
- and functions used in the kernel as well as giving a
- higher-level overview.
- </para>
- <para>
- The reader is expected to be familiar with the 802.11
- standard as published by the IEEE in 802.11-2007 (or
- possibly later versions). References to this standard
- will be given as "802.11-2007 8.1.5".
- </para>
- </abstract>
- </setinfo>
- <book id="cfg80211-developers-guide">
- <bookinfo>
- <title>The cfg80211 subsystem</title>
-
- <abstract>
-!Pinclude/net/cfg80211.h Introduction
- </abstract>
- </bookinfo>
- <chapter>
- <title>Device registration</title>
-!Pinclude/net/cfg80211.h Device registration
-!Finclude/net/cfg80211.h ieee80211_band
-!Finclude/net/cfg80211.h ieee80211_channel_flags
-!Finclude/net/cfg80211.h ieee80211_channel
-!Finclude/net/cfg80211.h ieee80211_rate_flags
-!Finclude/net/cfg80211.h ieee80211_rate
-!Finclude/net/cfg80211.h ieee80211_sta_ht_cap
-!Finclude/net/cfg80211.h ieee80211_supported_band
-!Finclude/net/cfg80211.h cfg80211_signal_type
-!Finclude/net/cfg80211.h wiphy_params_flags
-!Finclude/net/cfg80211.h wiphy_flags
-!Finclude/net/cfg80211.h wiphy
-!Finclude/net/cfg80211.h wireless_dev
-!Finclude/net/cfg80211.h wiphy_new
-!Finclude/net/cfg80211.h wiphy_register
-!Finclude/net/cfg80211.h wiphy_unregister
-!Finclude/net/cfg80211.h wiphy_free
-
-!Finclude/net/cfg80211.h wiphy_name
-!Finclude/net/cfg80211.h wiphy_dev
-!Finclude/net/cfg80211.h wiphy_priv
-!Finclude/net/cfg80211.h priv_to_wiphy
-!Finclude/net/cfg80211.h set_wiphy_dev
-!Finclude/net/cfg80211.h wdev_priv
-!Finclude/net/cfg80211.h ieee80211_iface_limit
-!Finclude/net/cfg80211.h ieee80211_iface_combination
-!Finclude/net/cfg80211.h cfg80211_check_combinations
- </chapter>
- <chapter>
- <title>Actions and configuration</title>
-!Pinclude/net/cfg80211.h Actions and configuration
-!Finclude/net/cfg80211.h cfg80211_ops
-!Finclude/net/cfg80211.h vif_params
-!Finclude/net/cfg80211.h key_params
-!Finclude/net/cfg80211.h survey_info_flags
-!Finclude/net/cfg80211.h survey_info
-!Finclude/net/cfg80211.h cfg80211_beacon_data
-!Finclude/net/cfg80211.h cfg80211_ap_settings
-!Finclude/net/cfg80211.h station_parameters
-!Finclude/net/cfg80211.h rate_info_flags
-!Finclude/net/cfg80211.h rate_info
-!Finclude/net/cfg80211.h station_info
-!Finclude/net/cfg80211.h monitor_flags
-!Finclude/net/cfg80211.h mpath_info_flags
-!Finclude/net/cfg80211.h mpath_info
-!Finclude/net/cfg80211.h bss_parameters
-!Finclude/net/cfg80211.h ieee80211_txq_params
-!Finclude/net/cfg80211.h cfg80211_crypto_settings
-!Finclude/net/cfg80211.h cfg80211_auth_request
-!Finclude/net/cfg80211.h cfg80211_assoc_request
-!Finclude/net/cfg80211.h cfg80211_deauth_request
-!Finclude/net/cfg80211.h cfg80211_disassoc_request
-!Finclude/net/cfg80211.h cfg80211_ibss_params
-!Finclude/net/cfg80211.h cfg80211_connect_params
-!Finclude/net/cfg80211.h cfg80211_pmksa
-!Finclude/net/cfg80211.h cfg80211_rx_mlme_mgmt
-!Finclude/net/cfg80211.h cfg80211_auth_timeout
-!Finclude/net/cfg80211.h cfg80211_rx_assoc_resp
-!Finclude/net/cfg80211.h cfg80211_assoc_timeout
-!Finclude/net/cfg80211.h cfg80211_tx_mlme_mgmt
-!Finclude/net/cfg80211.h cfg80211_ibss_joined
-!Finclude/net/cfg80211.h cfg80211_connect_result
-!Finclude/net/cfg80211.h cfg80211_roamed
-!Finclude/net/cfg80211.h cfg80211_disconnected
-!Finclude/net/cfg80211.h cfg80211_ready_on_channel
-!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired
-!Finclude/net/cfg80211.h cfg80211_new_sta
-!Finclude/net/cfg80211.h cfg80211_rx_mgmt
-!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status
-!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify
-!Finclude/net/cfg80211.h cfg80211_cqm_pktloss_notify
-!Finclude/net/cfg80211.h cfg80211_michael_mic_failure
- </chapter>
- <chapter>
- <title>Scanning and BSS list handling</title>
-!Pinclude/net/cfg80211.h Scanning and BSS list handling
-!Finclude/net/cfg80211.h cfg80211_ssid
-!Finclude/net/cfg80211.h cfg80211_scan_request
-!Finclude/net/cfg80211.h cfg80211_scan_done
-!Finclude/net/cfg80211.h cfg80211_bss
-!Finclude/net/cfg80211.h cfg80211_inform_bss_width_frame
-!Finclude/net/cfg80211.h cfg80211_inform_bss_width
-!Finclude/net/cfg80211.h cfg80211_unlink_bss
-!Finclude/net/cfg80211.h cfg80211_find_ie
-!Finclude/net/cfg80211.h ieee80211_bss_get_ie
- </chapter>
- <chapter>
- <title>Utility functions</title>
-!Pinclude/net/cfg80211.h Utility functions
-!Finclude/net/cfg80211.h ieee80211_channel_to_frequency
-!Finclude/net/cfg80211.h ieee80211_frequency_to_channel
-!Finclude/net/cfg80211.h ieee80211_get_channel
-!Finclude/net/cfg80211.h ieee80211_get_response_rate
-!Finclude/net/cfg80211.h ieee80211_hdrlen
-!Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb
-!Finclude/net/cfg80211.h ieee80211_radiotap_iterator
- </chapter>
- <chapter>
- <title>Data path helpers</title>
-!Pinclude/net/cfg80211.h Data path helpers
-!Finclude/net/cfg80211.h ieee80211_data_to_8023
-!Finclude/net/cfg80211.h ieee80211_data_from_8023
-!Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s
-!Finclude/net/cfg80211.h cfg80211_classify8021d
- </chapter>
- <chapter>
- <title>Regulatory enforcement infrastructure</title>
-!Pinclude/net/cfg80211.h Regulatory enforcement infrastructure
-!Finclude/net/cfg80211.h regulatory_hint
-!Finclude/net/cfg80211.h wiphy_apply_custom_regulatory
-!Finclude/net/cfg80211.h freq_reg_info
- </chapter>
- <chapter>
- <title>RFkill integration</title>
-!Pinclude/net/cfg80211.h RFkill integration
-!Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state
-!Finclude/net/cfg80211.h wiphy_rfkill_start_polling
-!Finclude/net/cfg80211.h wiphy_rfkill_stop_polling
- </chapter>
- <chapter>
- <title>Test mode</title>
-!Pinclude/net/cfg80211.h Test mode
-!Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb
-!Finclude/net/cfg80211.h cfg80211_testmode_reply
-!Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb
-!Finclude/net/cfg80211.h cfg80211_testmode_event
- </chapter>
- </book>
- <book id="mac80211-developers-guide">
- <bookinfo>
- <title>The mac80211 subsystem</title>
- <abstract>
-!Pinclude/net/mac80211.h Introduction
-!Pinclude/net/mac80211.h Warning
- </abstract>
- </bookinfo>
-
- <toc></toc>
-
- <!--
- Generally, this document shall be ordered by increasing complexity.
- It is important to note that readers should be able to read only
- the first few sections to get a working driver and only advanced
- usage should require reading the full document.
- -->
-
- <part>
- <title>The basic mac80211 driver interface</title>
- <partintro>
- <para>
- You should read and understand the information contained
- within this part of the book while implementing a driver.
- In some chapters, advanced usage is noted, that may be
- skipped at first.
- </para>
- <para>
- This part of the book only covers station and monitor mode
- functionality, additional information required to implement
- the other modes is covered in the second part of the book.
- </para>
- </partintro>
-
- <chapter id="basics">
- <title>Basic hardware handling</title>
- <para>TBD</para>
- <para>
- This chapter shall contain information on getting a hw
- struct allocated and registered with mac80211.
- </para>
- <para>
- Since it is required to allocate rates/modes before registering
- a hw struct, this chapter shall also contain information on setting
- up the rate/mode structs.
- </para>
- <para>
- Additionally, some discussion about the callbacks and
- the general programming model should be in here, including
- the definition of ieee80211_ops which will be referred to
- a lot.
- </para>
- <para>
- Finally, a discussion of hardware capabilities should be done
- with references to other parts of the book.
- </para>
- <!-- intentionally multiple !F lines to get proper order -->
-!Finclude/net/mac80211.h ieee80211_hw
-!Finclude/net/mac80211.h ieee80211_hw_flags
-!Finclude/net/mac80211.h SET_IEEE80211_DEV
-!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
-!Finclude/net/mac80211.h ieee80211_ops
-!Finclude/net/mac80211.h ieee80211_alloc_hw
-!Finclude/net/mac80211.h ieee80211_register_hw
-!Finclude/net/mac80211.h ieee80211_unregister_hw
-!Finclude/net/mac80211.h ieee80211_free_hw
- </chapter>
-
- <chapter id="phy-handling">
- <title>PHY configuration</title>
- <para>TBD</para>
- <para>
- This chapter should describe PHY handling including
- start/stop callbacks and the various structures used.
- </para>
-!Finclude/net/mac80211.h ieee80211_conf
-!Finclude/net/mac80211.h ieee80211_conf_flags
- </chapter>
-
- <chapter id="iface-handling">
- <title>Virtual interfaces</title>
- <para>TBD</para>
- <para>
- This chapter should describe virtual interface basics
- that are relevant to the driver (VLANs, MGMT etc are not.)
- It should explain the use of the add_iface/remove_iface
- callbacks as well as the interface configuration callbacks.
- </para>
- <para>Things related to AP mode should be discussed there.</para>
- <para>
- Things related to supporting multiple interfaces should be
- in the appropriate chapter, a BIG FAT note should be here about
- this though and the recommendation to allow only a single
- interface in STA mode at first!
- </para>
-!Finclude/net/mac80211.h ieee80211_vif
- </chapter>
-
- <chapter id="rx-tx">
- <title>Receive and transmit processing</title>
- <sect1>
- <title>what should be here</title>
- <para>TBD</para>
- <para>
- This should describe the receive and transmit
- paths in mac80211/the drivers as well as
- transmit status handling.
- </para>
- </sect1>
- <sect1>
- <title>Frame format</title>
-!Pinclude/net/mac80211.h Frame format
- </sect1>
- <sect1>
- <title>Packet alignment</title>
-!Pnet/mac80211/rx.c Packet alignment
- </sect1>
- <sect1>
- <title>Calling into mac80211 from interrupts</title>
-!Pinclude/net/mac80211.h Calling mac80211 from interrupts
- </sect1>
- <sect1>
- <title>functions/definitions</title>
-!Finclude/net/mac80211.h ieee80211_rx_status
-!Finclude/net/mac80211.h mac80211_rx_flags
-!Finclude/net/mac80211.h mac80211_tx_info_flags
-!Finclude/net/mac80211.h mac80211_tx_control_flags
-!Finclude/net/mac80211.h mac80211_rate_control_flags
-!Finclude/net/mac80211.h ieee80211_tx_rate
-!Finclude/net/mac80211.h ieee80211_tx_info
-!Finclude/net/mac80211.h ieee80211_tx_info_clear_status
-!Finclude/net/mac80211.h ieee80211_rx
-!Finclude/net/mac80211.h ieee80211_rx_ni
-!Finclude/net/mac80211.h ieee80211_rx_irqsafe
-!Finclude/net/mac80211.h ieee80211_tx_status
-!Finclude/net/mac80211.h ieee80211_tx_status_ni
-!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
-!Finclude/net/mac80211.h ieee80211_rts_get
-!Finclude/net/mac80211.h ieee80211_rts_duration
-!Finclude/net/mac80211.h ieee80211_ctstoself_get
-!Finclude/net/mac80211.h ieee80211_ctstoself_duration
-!Finclude/net/mac80211.h ieee80211_generic_frame_duration
-!Finclude/net/mac80211.h ieee80211_wake_queue
-!Finclude/net/mac80211.h ieee80211_stop_queue
-!Finclude/net/mac80211.h ieee80211_wake_queues
-!Finclude/net/mac80211.h ieee80211_stop_queues
-!Finclude/net/mac80211.h ieee80211_queue_stopped
- </sect1>
- </chapter>
-
- <chapter id="filters">
- <title>Frame filtering</title>
-!Pinclude/net/mac80211.h Frame filtering
-!Finclude/net/mac80211.h ieee80211_filter_flags
- </chapter>
-
- <chapter id="workqueue">
- <title>The mac80211 workqueue</title>
-!Pinclude/net/mac80211.h mac80211 workqueue
-!Finclude/net/mac80211.h ieee80211_queue_work
-!Finclude/net/mac80211.h ieee80211_queue_delayed_work
- </chapter>
- </part>
-
- <part id="advanced">
- <title>Advanced driver interface</title>
- <partintro>
- <para>
- Information contained within this part of the book is
- of interest only for advanced interaction of mac80211
- with drivers to exploit more hardware capabilities and
- improve performance.
- </para>
- </partintro>
-
- <chapter id="led-support">
- <title>LED support</title>
- <para>
- Mac80211 supports various ways of blinking LEDs. Wherever possible,
- device LEDs should be exposed as LED class devices and hooked up to
- the appropriate trigger, which will then be triggered appropriately
- by mac80211.
- </para>
-!Finclude/net/mac80211.h ieee80211_get_tx_led_name
-!Finclude/net/mac80211.h ieee80211_get_rx_led_name
-!Finclude/net/mac80211.h ieee80211_get_assoc_led_name
-!Finclude/net/mac80211.h ieee80211_get_radio_led_name
-!Finclude/net/mac80211.h ieee80211_tpt_blink
-!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags
-!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger
- </chapter>
-
- <chapter id="hardware-crypto-offload">
- <title>Hardware crypto acceleration</title>
-!Pinclude/net/mac80211.h Hardware crypto acceleration
- <!-- intentionally multiple !F lines to get proper order -->
-!Finclude/net/mac80211.h set_key_cmd
-!Finclude/net/mac80211.h ieee80211_key_conf
-!Finclude/net/mac80211.h ieee80211_key_flags
-!Finclude/net/mac80211.h ieee80211_get_tkip_p1k
-!Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv
-!Finclude/net/mac80211.h ieee80211_get_tkip_p2k
- </chapter>
-
- <chapter id="powersave">
- <title>Powersave support</title>
-!Pinclude/net/mac80211.h Powersave support
- </chapter>
-
- <chapter id="beacon-filter">
- <title>Beacon filter support</title>
-!Pinclude/net/mac80211.h Beacon filter support
-!Finclude/net/mac80211.h ieee80211_beacon_loss
- </chapter>
-
- <chapter id="qos">
- <title>Multiple queues and QoS support</title>
- <para>TBD</para>
-!Finclude/net/mac80211.h ieee80211_tx_queue_params
- </chapter>
-
- <chapter id="AP">
- <title>Access point mode support</title>
- <para>TBD</para>
- <para>Some parts of the if_conf should be discussed here instead</para>
- <para>
- Insert notes about VLAN interfaces with hw crypto here or
- in the hw crypto chapter.
- </para>
- <section id="ps-client">
- <title>support for powersaving clients</title>
-!Pinclude/net/mac80211.h AP support for powersaving clients
-!Finclude/net/mac80211.h ieee80211_get_buffered_bc
-!Finclude/net/mac80211.h ieee80211_beacon_get
-!Finclude/net/mac80211.h ieee80211_sta_eosp
-!Finclude/net/mac80211.h ieee80211_frame_release_type
-!Finclude/net/mac80211.h ieee80211_sta_ps_transition
-!Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni
-!Finclude/net/mac80211.h ieee80211_sta_set_buffered
-!Finclude/net/mac80211.h ieee80211_sta_block_awake
- </section>
- </chapter>
-
- <chapter id="multi-iface">
- <title>Supporting multiple virtual interfaces</title>
- <para>TBD</para>
- <para>
- Note: WDS with identical MAC address should almost always be OK
- </para>
- <para>
- Insert notes about having multiple virtual interfaces with
- different MAC addresses here, note which configurations are
- supported by mac80211, add notes about supporting hw crypto
- with it.
- </para>
-!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces
-!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic
- </chapter>
-
- <chapter id="station-handling">
- <title>Station handling</title>
- <para>TODO</para>
-!Finclude/net/mac80211.h ieee80211_sta
-!Finclude/net/mac80211.h sta_notify_cmd
-!Finclude/net/mac80211.h ieee80211_find_sta
-!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr
- </chapter>
-
- <chapter id="hardware-scan-offload">
- <title>Hardware scan offload</title>
- <para>TBD</para>
-!Finclude/net/mac80211.h ieee80211_scan_completed
- </chapter>
-
- <chapter id="aggregation">
- <title>Aggregation</title>
- <sect1>
- <title>TX A-MPDU aggregation</title>
-!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation
-!Cnet/mac80211/agg-tx.c
- </sect1>
- <sect1>
- <title>RX A-MPDU aggregation</title>
-!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation
-!Cnet/mac80211/agg-rx.c
-!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action
- </sect1>
- </chapter>
-
- <chapter id="smps">
- <title>Spatial Multiplexing Powersave (SMPS)</title>
-!Pinclude/net/mac80211.h Spatial multiplexing power save
-!Finclude/net/mac80211.h ieee80211_request_smps
-!Finclude/net/mac80211.h ieee80211_smps_mode
- </chapter>
- </part>
-
- <part id="rate-control">
- <title>Rate control interface</title>
- <partintro>
- <para>TBD</para>
- <para>
- This part of the book describes the rate control algorithm
- interface and how it relates to mac80211 and drivers.
- </para>
- </partintro>
- <chapter id="ratecontrol-api">
- <title>Rate Control API</title>
- <para>TBD</para>
-!Finclude/net/mac80211.h ieee80211_start_tx_ba_session
-!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe
-!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session
-!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe
-!Finclude/net/mac80211.h ieee80211_rate_control_changed
-!Finclude/net/mac80211.h ieee80211_tx_rate_control
-!Finclude/net/mac80211.h rate_control_send_low
- </chapter>
- </part>
-
- <part id="internal">
- <title>Internals</title>
- <partintro>
- <para>TBD</para>
- <para>
- This part of the book describes mac80211 internals.
- </para>
- </partintro>
-
- <chapter id="key-handling">
- <title>Key handling</title>
- <sect1>
- <title>Key handling basics</title>
-!Pnet/mac80211/key.c Key handling basics
- </sect1>
- <sect1>
- <title>MORE TBD</title>
- <para>TBD</para>
- </sect1>
- </chapter>
-
- <chapter id="rx-processing">
- <title>Receive processing</title>
- <para>TBD</para>
- </chapter>
-
- <chapter id="tx-processing">
- <title>Transmit processing</title>
- <para>TBD</para>
- </chapter>
-
- <chapter id="sta-info">
- <title>Station info handling</title>
- <sect1>
- <title>Programming information</title>
-!Fnet/mac80211/sta_info.h sta_info
-!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
- </sect1>
- <sect1>
- <title>STA information lifetime rules</title>
-!Pnet/mac80211/sta_info.c STA information lifetime rules
- </sect1>
- </chapter>
-
- <chapter id="aggregation-internals">
- <title>Aggregation</title>
-!Fnet/mac80211/sta_info.h sta_ampdu_mlme
-!Fnet/mac80211/sta_info.h tid_ampdu_tx
-!Fnet/mac80211/sta_info.h tid_ampdu_rx
- </chapter>
-
- <chapter id="synchronisation">
- <title>Synchronisation</title>
- <para>TBD</para>
- <para>Locking, lots of RCU</para>
- </chapter>
- </part>
- </book>
-</set>
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
deleted file mode 100644
index b6a6a2e0dd3b..000000000000
--- a/Documentation/DocBook/Makefile
+++ /dev/null
@@ -1,232 +0,0 @@
-###
-# This makefile is used to generate the kernel documentation,
-# primarily based on in-line comments in various source files.
-# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
-# to document the SRC - and how to read it.
-# To add a new book the only step required is to add the book to the
-# list of DOCBOOKS.
-
-DOCBOOKS := z8530book.xml device-drivers.xml \
- kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
- writing_usb_driver.xml networking.xml \
- kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
- gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
- genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
- 80211.xml debugobjects.xml sh.xml regulator.xml \
- alsa-driver-api.xml writing-an-alsa-driver.xml \
- tracepoint.xml drm.xml media_api.xml w1.xml \
- writing_musb_glue_layer.xml crypto-API.xml
-
-include Documentation/DocBook/media/Makefile
-
-###
-# The build process is as follows (targets):
-# (xmldocs) [by docproc]
-# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
-# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
-# +--> DIR=file (htmldocs) [by xmlto]
-# +--> man/ (mandocs) [by xmlto]
-
-
-# for PDF and PS output you can choose between xmlto and docbook-utils tools
-PDF_METHOD = $(prefer-db2x)
-PS_METHOD = $(prefer-db2x)
-
-
-###
-# The targets that may be used.
-PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
-
-targets += $(DOCBOOKS)
-BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
-xmldocs: $(BOOKS)
-sgmldocs: xmldocs
-
-PS := $(patsubst %.xml, %.ps, $(BOOKS))
-psdocs: $(PS)
-
-PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
-pdfdocs: $(PDF)
-
-HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
-htmldocs: $(HTML)
- $(call build_main_index)
- $(call build_images)
- $(call install_media_images)
-
-MAN := $(patsubst %.xml, %.9, $(BOOKS))
-mandocs: $(MAN)
- find $(obj)/man -name '*.9' | xargs gzip -f
-
-installmandocs: mandocs
- mkdir -p /usr/local/man/man9/
- install $(obj)/man/*.9.gz /usr/local/man/man9/
-
-###
-#External programs used
-KERNELDOC = $(srctree)/scripts/kernel-doc
-DOCPROC = $(objtree)/scripts/docproc
-
-XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
-XMLTOFLAGS += --skip-validation
-
-###
-# DOCPROC is used for two purposes:
-# 1) To generate a dependency list for a .tmpl file
-# 2) To preprocess a .tmpl file and call kernel-doc with
-# appropriate parameters.
-# The following rules are used to generate the .xml documentation
-# required to generate the final targets. (ps, pdf, html).
-quiet_cmd_docproc = DOCPROC $@
- cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
-define rule_docproc
- set -e; \
- $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
- $(cmd_$(1)); \
- ( \
- echo 'cmd_$@ := $(cmd_$(1))'; \
- echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
- ) > $(dir $@).$(notdir $@).cmd
-endef
-
-%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
- $(call if_changed_rule,docproc)
-
-# Tell kbuild to always build the programs
-always := $(hostprogs-y)
-
-notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
- exit 1
-db2xtemplate = db2TYPE -o $(dir $@) $<
-xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
-
-# determine which methods are available
-ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
- use-db2x = db2x
- prefer-db2x = db2x
-else
- use-db2x = notfound
- prefer-db2x = $(use-xmlto)
-endif
-ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
- use-xmlto = xmlto
- prefer-xmlto = xmlto
-else
- use-xmlto = notfound
- prefer-xmlto = $(use-db2x)
-endif
-
-# the commands, generated from the chosen template
-quiet_cmd_db2ps = PS $@
- cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
-%.ps : %.xml
- $(call cmd,db2ps)
-
-quiet_cmd_db2pdf = PDF $@
- cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
-%.pdf : %.xml
- $(call cmd,db2pdf)
-
-
-index = index.html
-main_idx = $(obj)/$(index)
-build_main_index = rm -rf $(main_idx); \
- echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
- echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
- cat $(HTML) >> $(main_idx)
-
-quiet_cmd_db2html = HTML $@
- cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
- echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
- $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
-
-%.html: %.xml
- @(which xmlto > /dev/null 2>&1) || \
- (echo "*** You need to install xmlto ***"; \
- exit 1)
- @rm -rf $@ $(patsubst %.html,%,$@)
- $(call cmd,db2html)
- @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
- cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
-
-quiet_cmd_db2man = MAN $@
- cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi
-%.9 : %.xml
- @(which xmlto > /dev/null 2>&1) || \
- (echo "*** You need to install xmlto ***"; \
- exit 1)
- $(Q)mkdir -p $(obj)/man
- $(call cmd,db2man)
- @touch $@
-
-###
-# Rules to generate postscripts and PNG images from .fig format files
-quiet_cmd_fig2eps = FIG2EPS $@
- cmd_fig2eps = fig2dev -Leps $< $@
-
-%.eps: %.fig
- @(which fig2dev > /dev/null 2>&1) || \
- (echo "*** You need to install transfig ***"; \
- exit 1)
- $(call cmd,fig2eps)
-
-quiet_cmd_fig2png = FIG2PNG $@
- cmd_fig2png = fig2dev -Lpng $< $@
-
-%.png: %.fig
- @(which fig2dev > /dev/null 2>&1) || \
- (echo "*** You need to install transfig ***"; \
- exit 1)
- $(call cmd,fig2png)
-
-###
-# Rule to convert a .c file to inline XML documentation
- gen_xml = :
- quiet_gen_xml = echo ' GEN $@'
-silent_gen_xml = :
-%.xml: %.c
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>"; \
- expand --tabs=8 < $< | \
- sed -e "s/&/\\&amp;/g" \
- -e "s/</\\&lt;/g" \
- -e "s/>/\\&gt;/g"; \
- echo "</programlisting>") > $@
-
-###
-# Help targets as used by the top-level makefile
-dochelp:
- @echo ' Linux kernel internal documentation in different formats:'
- @echo ' htmldocs - HTML'
- @echo ' pdfdocs - PDF'
- @echo ' psdocs - Postscript'
- @echo ' xmldocs - XML DocBook'
- @echo ' mandocs - man pages'
- @echo ' installmandocs - install man pages generated by mandocs'
- @echo ' cleandocs - clean all generated DocBook files'
-
-###
-# Temporary files left by various tools
-clean-files := $(DOCBOOKS) \
- $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
- $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
- $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
- $(patsubst %.xml, %.log, $(DOCBOOKS)) \
- $(patsubst %.xml, %.out, $(DOCBOOKS)) \
- $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
- $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
- $(patsubst %.xml, %.html, $(DOCBOOKS)) \
- $(patsubst %.xml, %.9, $(DOCBOOKS)) \
- $(index)
-
-clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
-
-cleandocs: cleanmediadocs
- $(Q)rm -f $(call objectify, $(clean-files))
- $(Q)rm -rf $(call objectify, $(clean-dirs))
-
-# Declare the contents of the .PHONY variable as phony. We keep that
-# information in a variable se we can use it in if_changed and friends.
-
-.PHONY: $(PHONY)
diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl
deleted file mode 100644
index 71f9246127ec..000000000000
--- a/Documentation/DocBook/alsa-driver-api.tmpl
+++ /dev/null
@@ -1,140 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<!-- ****************************************************** -->
-<!-- Header -->
-<!-- ****************************************************** -->
-<book id="ALSA-Driver-API">
- <bookinfo>
- <title>The ALSA Driver API</title>
-
- <legalnotice>
- <para>
- This document is free; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
- </para>
-
- <para>
- This document is distributed in the hope that it will be useful,
- but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
- implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
- PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
- for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
- </legalnotice>
-
- </bookinfo>
-
-<toc></toc>
-
- <chapter><title>Management of Cards and Devices</title>
- <sect1><title>Card Management</title>
-!Esound/core/init.c
- </sect1>
- <sect1><title>Device Components</title>
-!Esound/core/device.c
- </sect1>
- <sect1><title>Module requests and Device File Entries</title>
-!Esound/core/sound.c
- </sect1>
- <sect1><title>Memory Management Helpers</title>
-!Esound/core/memory.c
-!Esound/core/memalloc.c
- </sect1>
- </chapter>
- <chapter><title>PCM API</title>
- <sect1><title>PCM Core</title>
-!Esound/core/pcm.c
-!Esound/core/pcm_lib.c
-!Esound/core/pcm_native.c
-!Iinclude/sound/pcm.h
- </sect1>
- <sect1><title>PCM Format Helpers</title>
-!Esound/core/pcm_misc.c
- </sect1>
- <sect1><title>PCM Memory Management</title>
-!Esound/core/pcm_memory.c
- </sect1>
- <sect1><title>PCM DMA Engine API</title>
-!Esound/core/pcm_dmaengine.c
-!Iinclude/sound/dmaengine_pcm.h
- </sect1>
- </chapter>
- <chapter><title>Control/Mixer API</title>
- <sect1><title>General Control Interface</title>
-!Esound/core/control.c
- </sect1>
- <sect1><title>AC97 Codec API</title>
-!Esound/pci/ac97/ac97_codec.c
-!Esound/pci/ac97/ac97_pcm.c
- </sect1>
- <sect1><title>Virtual Master Control API</title>
-!Esound/core/vmaster.c
-!Iinclude/sound/control.h
- </sect1>
- </chapter>
- <chapter><title>MIDI API</title>
- <sect1><title>Raw MIDI API</title>
-!Esound/core/rawmidi.c
- </sect1>
- <sect1><title>MPU401-UART API</title>
-!Esound/drivers/mpu401/mpu401_uart.c
- </sect1>
- </chapter>
- <chapter><title>Proc Info API</title>
- <sect1><title>Proc Info Interface</title>
-!Esound/core/info.c
- </sect1>
- </chapter>
- <chapter><title>Compress Offload</title>
- <sect1><title>Compress Offload API</title>
-!Esound/core/compress_offload.c
-!Iinclude/uapi/sound/compress_offload.h
-!Iinclude/uapi/sound/compress_params.h
-!Iinclude/sound/compress_driver.h
- </sect1>
- </chapter>
- <chapter><title>ASoC</title>
- <sect1><title>ASoC Core API</title>
-!Iinclude/sound/soc.h
-!Esound/soc/soc-core.c
-!Esound/soc/soc-cache.c
-!Esound/soc/soc-devres.c
-!Esound/soc/soc-io.c
-!Esound/soc/soc-pcm.c
- </sect1>
- <sect1><title>ASoC DAPM API</title>
-!Esound/soc/soc-dapm.c
- </sect1>
- <sect1><title>ASoC DMA Engine API</title>
-!Esound/soc/soc-generic-dmaengine-pcm.c
- </sect1>
- </chapter>
- <chapter><title>Miscellaneous Functions</title>
- <sect1><title>Hardware-Dependent Devices API</title>
-!Esound/core/hwdep.c
- </sect1>
- <sect1><title>Jack Abstraction Layer API</title>
-!Iinclude/sound/jack.h
-!Esound/core/jack.c
-!Esound/soc/soc-jack.c
- </sect1>
- <sect1><title>ISA DMA Helpers</title>
-!Esound/core/isadma.c
- </sect1>
- <sect1><title>Other Helper Macros</title>
-!Iinclude/sound/core.h
- </sect1>
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl
deleted file mode 100644
index efc8d90a9a3f..000000000000
--- a/Documentation/DocBook/crypto-API.tmpl
+++ /dev/null
@@ -1,2113 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="KernelCryptoAPI">
- <bookinfo>
- <title>Linux Kernel Crypto API</title>
-
- <authorgroup>
- <author>
- <firstname>Stephan</firstname>
- <surname>Mueller</surname>
- <affiliation>
- <address>
- <email>smueller@chronox.de</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Marek</firstname>
- <surname>Vasut</surname>
- <affiliation>
- <address>
- <email>marek@denx.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2014</year>
- <holder>Stephan Mueller</holder>
- </copyright>
-
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
-
- <chapter id="Intro">
- <title>Kernel Crypto API Interface Specification</title>
-
- <sect1><title>Introduction</title>
-
- <para>
- The kernel crypto API offers a rich set of cryptographic ciphers as
- well as other data transformation mechanisms and methods to invoke
- these. This document contains a description of the API and provides
- example code.
- </para>
-
- <para>
- To understand and properly use the kernel crypto API a brief
- explanation of its structure is given. Based on the architecture,
- the API can be separated into different components. Following the
- architecture specification, hints to developers of ciphers are
- provided. Pointers to the API function call documentation are
- given at the end.
- </para>
-
- <para>
- The kernel crypto API refers to all algorithms as "transformations".
- Therefore, a cipher handle variable usually has the name "tfm".
- Besides cryptographic operations, the kernel crypto API also knows
- compression transformations and handles them the same way as ciphers.
- </para>
-
- <para>
- The kernel crypto API serves the following entity types:
-
- <itemizedlist>
- <listitem>
- <para>consumers requesting cryptographic services</para>
- </listitem>
- <listitem>
- <para>data transformation implementations (typically ciphers)
- that can be called by consumers using the kernel crypto
- API</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- This specification is intended for consumers of the kernel crypto
- API as well as for developers implementing ciphers. This API
- specification, however, does not discuss all API calls available
- to data transformation implementations (i.e. implementations of
- ciphers and other transformations (such as CRC or even compression
- algorithms) that can register with the kernel crypto API).
- </para>
-
- <para>
- Note: The terms "transformation" and cipher algorithm are used
- interchangably.
- </para>
- </sect1>
-
- <sect1><title>Terminology</title>
- <para>
- The transformation implementation is an actual code or interface
- to hardware which implements a certain transformation with precisely
- defined behavior.
- </para>
-
- <para>
- The transformation object (TFM) is an instance of a transformation
- implementation. There can be multiple transformation objects
- associated with a single transformation implementation. Each of
- those transformation objects is held by a crypto API consumer or
- another transformation. Transformation object is allocated when a
- crypto API consumer requests a transformation implementation.
- The consumer is then provided with a structure, which contains
- a transformation object (TFM).
- </para>
-
- <para>
- The structure that contains transformation objects may also be
- referred to as a "cipher handle". Such a cipher handle is always
- subject to the following phases that are reflected in the API calls
- applicable to such a cipher handle:
- </para>
-
- <orderedlist>
- <listitem>
- <para>Initialization of a cipher handle.</para>
- </listitem>
- <listitem>
- <para>Execution of all intended cipher operations applicable
- for the handle where the cipher handle must be furnished to
- every API call.</para>
- </listitem>
- <listitem>
- <para>Destruction of a cipher handle.</para>
- </listitem>
- </orderedlist>
-
- <para>
- When using the initialization API calls, a cipher handle is
- created and returned to the consumer. Therefore, please refer
- to all initialization API calls that refer to the data
- structure type a consumer is expected to receive and subsequently
- to use. The initialization API calls have all the same naming
- conventions of crypto_alloc_*.
- </para>
-
- <para>
- The transformation context is private data associated with
- the transformation object.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="Architecture"><title>Kernel Crypto API Architecture</title>
- <sect1><title>Cipher algorithm types</title>
- <para>
- The kernel crypto API provides different API calls for the
- following cipher types:
-
- <itemizedlist>
- <listitem><para>Symmetric ciphers</para></listitem>
- <listitem><para>AEAD ciphers</para></listitem>
- <listitem><para>Message digest, including keyed message digest</para></listitem>
- <listitem><para>Random number generation</para></listitem>
- <listitem><para>User space interface</para></listitem>
- </itemizedlist>
- </para>
- </sect1>
-
- <sect1><title>Ciphers And Templates</title>
- <para>
- The kernel crypto API provides implementations of single block
- ciphers and message digests. In addition, the kernel crypto API
- provides numerous "templates" that can be used in conjunction
- with the single block ciphers and message digests. Templates
- include all types of block chaining mode, the HMAC mechanism, etc.
- </para>
-
- <para>
- Single block ciphers and message digests can either be directly
- used by a caller or invoked together with a template to form
- multi-block ciphers or keyed message digests.
- </para>
-
- <para>
- A single block cipher may even be called with multiple templates.
- However, templates cannot be used without a single cipher.
- </para>
-
- <para>
- See /proc/crypto and search for "name". For example:
-
- <itemizedlist>
- <listitem><para>aes</para></listitem>
- <listitem><para>ecb(aes)</para></listitem>
- <listitem><para>cmac(aes)</para></listitem>
- <listitem><para>ccm(aes)</para></listitem>
- <listitem><para>rfc4106(gcm(aes))</para></listitem>
- <listitem><para>sha1</para></listitem>
- <listitem><para>hmac(sha1)</para></listitem>
- <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- In these examples, "aes" and "sha1" are the ciphers and all
- others are the templates.
- </para>
- </sect1>
-
- <sect1><title>Synchronous And Asynchronous Operation</title>
- <para>
- The kernel crypto API provides synchronous and asynchronous
- API operations.
- </para>
-
- <para>
- When using the synchronous API operation, the caller invokes
- a cipher operation which is performed synchronously by the
- kernel crypto API. That means, the caller waits until the
- cipher operation completes. Therefore, the kernel crypto API
- calls work like regular function calls. For synchronous
- operation, the set of API calls is small and conceptually
- similar to any other crypto library.
- </para>
-
- <para>
- Asynchronous operation is provided by the kernel crypto API
- which implies that the invocation of a cipher operation will
- complete almost instantly. That invocation triggers the
- cipher operation but it does not signal its completion. Before
- invoking a cipher operation, the caller must provide a callback
- function the kernel crypto API can invoke to signal the
- completion of the cipher operation. Furthermore, the caller
- must ensure it can handle such asynchronous events by applying
- appropriate locking around its data. The kernel crypto API
- does not perform any special serialization operation to protect
- the caller's data integrity.
- </para>
- </sect1>
-
- <sect1><title>Crypto API Cipher References And Priority</title>
- <para>
- A cipher is referenced by the caller with a string. That string
- has the following semantics:
-
- <programlisting>
- template(single block cipher)
- </programlisting>
-
- where "template" and "single block cipher" is the aforementioned
- template and single block cipher, respectively. If applicable,
- additional templates may enclose other templates, such as
-
- <programlisting>
- template1(template2(single block cipher)))
- </programlisting>
- </para>
-
- <para>
- The kernel crypto API may provide multiple implementations of a
- template or a single block cipher. For example, AES on newer
- Intel hardware has the following implementations: AES-NI,
- assembler implementation, or straight C. Now, when using the
- string "aes" with the kernel crypto API, which cipher
- implementation is used? The answer to that question is the
- priority number assigned to each cipher implementation by the
- kernel crypto API. When a caller uses the string to refer to a
- cipher during initialization of a cipher handle, the kernel
- crypto API looks up all implementations providing an
- implementation with that name and selects the implementation
- with the highest priority.
- </para>
-
- <para>
- Now, a caller may have the need to refer to a specific cipher
- implementation and thus does not want to rely on the
- priority-based selection. To accommodate this scenario, the
- kernel crypto API allows the cipher implementation to register
- a unique name in addition to common names. When using that
- unique name, a caller is therefore always sure to refer to
- the intended cipher implementation.
- </para>
-
- <para>
- The list of available ciphers is given in /proc/crypto. However,
- that list does not specify all possible permutations of
- templates and ciphers. Each block listed in /proc/crypto may
- contain the following information -- if one of the components
- listed as follows are not applicable to a cipher, it is not
- displayed:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>name: the generic name of the cipher that is subject
- to the priority-based selection -- this name can be used by
- the cipher allocation API calls (all names listed above are
- examples for such generic names)</para>
- </listitem>
- <listitem>
- <para>driver: the unique name of the cipher -- this name can
- be used by the cipher allocation API calls</para>
- </listitem>
- <listitem>
- <para>module: the kernel module providing the cipher
- implementation (or "kernel" for statically linked ciphers)</para>
- </listitem>
- <listitem>
- <para>priority: the priority value of the cipher implementation</para>
- </listitem>
- <listitem>
- <para>refcnt: the reference count of the respective cipher
- (i.e. the number of current consumers of this cipher)</para>
- </listitem>
- <listitem>
- <para>selftest: specification whether the self test for the
- cipher passed</para>
- </listitem>
- <listitem>
- <para>type:
- <itemizedlist>
- <listitem>
- <para>blkcipher for synchronous block ciphers</para>
- </listitem>
- <listitem>
- <para>ablkcipher for asynchronous block ciphers</para>
- </listitem>
- <listitem>
- <para>cipher for single block ciphers that may be used with
- an additional template</para>
- </listitem>
- <listitem>
- <para>shash for synchronous message digest</para>
- </listitem>
- <listitem>
- <para>ahash for asynchronous message digest</para>
- </listitem>
- <listitem>
- <para>aead for AEAD cipher type</para>
- </listitem>
- <listitem>
- <para>compression for compression type transformations</para>
- </listitem>
- <listitem>
- <para>rng for random number generator</para>
- </listitem>
- <listitem>
- <para>givcipher for cipher with associated IV generator
- (see the geniv entry below for the specification of the
- IV generator type used by the cipher implementation)</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>blocksize: blocksize of cipher in bytes</para>
- </listitem>
- <listitem>
- <para>keysize: key size in bytes</para>
- </listitem>
- <listitem>
- <para>ivsize: IV size in bytes</para>
- </listitem>
- <listitem>
- <para>seedsize: required size of seed data for random number
- generator</para>
- </listitem>
- <listitem>
- <para>digestsize: output size of the message digest</para>
- </listitem>
- <listitem>
- <para>geniv: IV generation type:
- <itemizedlist>
- <listitem>
- <para>eseqiv for encrypted sequence number based IV
- generation</para>
- </listitem>
- <listitem>
- <para>seqiv for sequence number based IV generation</para>
- </listitem>
- <listitem>
- <para>chainiv for chain iv generation</para>
- </listitem>
- <listitem>
- <para>&lt;builtin&gt; is a marker that the cipher implements
- IV generation and handling as it is specific to the given
- cipher</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1><title>Key Sizes</title>
- <para>
- When allocating a cipher handle, the caller only specifies the
- cipher type. Symmetric ciphers, however, typically support
- multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256).
- These key sizes are determined with the length of the provided
- key. Thus, the kernel crypto API does not provide a separate
- way to select the particular symmetric cipher key size.
- </para>
- </sect1>
-
- <sect1><title>Cipher Allocation Type And Masks</title>
- <para>
- The different cipher handle allocation functions allow the
- specification of a type and mask flag. Both parameters have
- the following meaning (and are therefore not covered in the
- subsequent sections).
- </para>
-
- <para>
- The type flag specifies the type of the cipher algorithm.
- The caller usually provides a 0 when the caller wants the
- default handling. Otherwise, the caller may provide the
- following selections which match the the aforementioned
- cipher types:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with
- Associated Data (MAC)</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block
- cipher packed together with an IV generator (see geniv field
- in the /proc/crypto listing for the known IV generators)</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para>
- </listitem>
- <listitem>
- <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
- CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
- decompression instead of performing the operation on one
- segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
- CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para>
- </listitem>
- </itemizedlist>
-
- <para>
- The mask flag restricts the type of cipher. The only allowed
- flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function
- to asynchronous ciphers. Usually, a caller provides a 0 for the
- mask flag.
- </para>
-
- <para>
- When the caller provides a mask and type specification, the
- caller limits the search the kernel crypto API can perform for
- a suitable cipher implementation for the given cipher name.
- That means, even when a caller uses a cipher name that exists
- during its initialization call, the kernel crypto API may not
- select it due to the used type and mask field.
- </para>
- </sect1>
-
- <sect1><title>Internal Structure of Kernel Crypto API</title>
-
- <para>
- The kernel crypto API has an internal structure where a cipher
- implementation may use many layers and indirections. This section
- shall help to clarify how the kernel crypto API uses
- various components to implement the complete cipher.
- </para>
-
- <para>
- The following subsections explain the internal structure based
- on existing cipher implementations. The first section addresses
- the most complex scenario where all other scenarios form a logical
- subset.
- </para>
-
- <sect2><title>Generic AEAD Cipher Structure</title>
-
- <para>
- The following ASCII art decomposes the kernel crypto API layers
- when using the AEAD cipher with the automated IV generation. The
- shown example is used by the IPSEC layer.
- </para>
-
- <para>
- For other use cases of AEAD ciphers, the ASCII art applies as
- well, but the caller may not use the GIVCIPHER interface. In
- this case, the caller must generate the IV.
- </para>
-
- <para>
- The depicted example decomposes the AEAD cipher of GCM(AES) based
- on the generic C implementations (gcm.c, aes-generic.c, ctr.c,
- ghash-generic.c, seqiv.c). The generic implementation serves as an
- example showing the complete logic of the kernel crypto API.
- </para>
-
- <para>
- It is possible that some streamlined cipher implementations (like
- AES-NI) provide implementations merging aspects which in the view
- of the kernel crypto API cannot be decomposed into layers any more.
- In case of the AES-NI implementation, the CTR mode, the GHASH
- implementation and the AES cipher are all merged into one cipher
- implementation registered with the kernel crypto API. In this case,
- the concept described by the following ASCII art applies too. However,
- the decomposition of GCM into the individual sub-components
- by the kernel crypto API is not done any more.
- </para>
-
- <para>
- Each block in the following ASCII art is an independent cipher
- instance obtained from the kernel crypto API. Each block
- is accessed by the caller or by other blocks using the API functions
- defined by the kernel crypto API for the cipher implementation type.
- </para>
-
- <para>
- The blocks below indicate the cipher type as well as the specific
- logic implemented in the cipher.
- </para>
-
- <para>
- The ASCII art picture also indicates the call structure, i.e. who
- calls which component. The arrows point to the invoked block
- where the caller uses the API applicable to the cipher type
- specified for the block.
- </para>
-
- <programlisting>
-<![CDATA[
-kernel crypto API | IPSEC Layer
- |
-+-----------+ |
-| | (1)
-| givcipher | <----------------------------------- esp_output
-| (seqiv) | ---+
-+-----------+ |
- | (2)
-+-----------+ |
-| | <--+ (2)
-| aead | <----------------------------------- esp_input
-| (gcm) | ------------+
-+-----------+ |
- | (3) | (5)
- v v
-+-----------+ +-----------+
-| | | |
-| ablkcipher| | ahash |
-| (ctr) | ---+ | (ghash) |
-+-----------+ | +-----------+
- |
-+-----------+ | (4)
-| | <--+
-| cipher |
-| (aes) |
-+-----------+
-]]>
- </programlisting>
-
- <para>
- The following call sequence is applicable when the IPSEC layer
- triggers an encryption operation with the esp_output function. During
- configuration, the administrator set up the use of rfc4106(gcm(aes)) as
- the cipher for ESP. The following call sequence is now depicted in the
- ASCII art above:
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- esp_output() invokes crypto_aead_givencrypt() to trigger an encryption
- operation of the GIVCIPHER implementation.
- </para>
-
- <para>
- In case of GCM, the SEQIV implementation is registered as GIVCIPHER
- in crypto_rfc4106_alloc().
- </para>
-
- <para>
- The SEQIV performs its operation to generate an IV where the core
- function is seqiv_geniv().
- </para>
- </listitem>
-
- <listitem>
- <para>
- Now, SEQIV uses the AEAD API function calls to invoke the associated
- AEAD cipher. In our case, during the instantiation of SEQIV, the
- cipher handle for GCM is provided to SEQIV. This means that SEQIV
- invokes AEAD cipher operations with the GCM cipher handle.
- </para>
-
- <para>
- During instantiation of the GCM handle, the CTR(AES) and GHASH
- ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
- are retained for later use.
- </para>
-
- <para>
- The GCM implementation is responsible to invoke the CTR mode AES and
- the GHASH cipher in the right manner to implement the GCM
- specification.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API
- with the instantiated CTR(AES) cipher handle.
- </para>
-
- <para>
- During instantiation of the CTR(AES) cipher, the CIPHER type
- implementation of AES is instantiated. The cipher handle for AES is
- retained.
- </para>
-
- <para>
- That means that the ABLKCIPHER implementation of CTR(AES) only
- implements the CTR block chaining mode. After performing the block
- chaining operation, the CIPHER implementation of AES is invoked.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
- cipher handle to encrypt one block.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The GCM AEAD implementation also invokes the GHASH cipher
- implementation via the AHASH API.
- </para>
- </listitem>
- </orderedlist>
-
- <para>
- When the IPSEC layer triggers the esp_input() function, the same call
- sequence is followed with the only difference that the operation starts
- with step (2).
- </para>
- </sect2>
-
- <sect2><title>Generic Block Cipher Structure</title>
- <para>
- Generic block ciphers follow the same concept as depicted with the ASCII
- art picture above.
- </para>
-
- <para>
- For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The
- ASCII art picture above applies as well with the difference that only
- step (4) is used and the ABLKCIPHER block chaining mode is CBC.
- </para>
- </sect2>
-
- <sect2><title>Generic Keyed Message Digest Structure</title>
- <para>
- Keyed message digest implementations again follow the same concept as
- depicted in the ASCII art picture above.
- </para>
-
- <para>
- For example, HMAC(SHA256) is implemented with hmac.c and
- sha256_generic.c. The following ASCII art illustrates the
- implementation:
- </para>
-
- <programlisting>
-<![CDATA[
-kernel crypto API | Caller
- |
-+-----------+ (1) |
-| | <------------------ some_function
-| ahash |
-| (hmac) | ---+
-+-----------+ |
- | (2)
-+-----------+ |
-| | <--+
-| shash |
-| (sha256) |
-+-----------+
-]]>
- </programlisting>
-
- <para>
- The following call sequence is applicable when a caller triggers
- an HMAC operation:
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- The AHASH API functions are invoked by the caller. The HMAC
- implementation performs its operation as needed.
- </para>
-
- <para>
- During initialization of the HMAC cipher, the SHASH cipher type of
- SHA256 is instantiated. The cipher handle for the SHA256 instance is
- retained.
- </para>
-
- <para>
- At one time, the HMAC implementation requires a SHA256 operation
- where the SHA256 cipher handle is used.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The HMAC instance now invokes the SHASH API with the SHA256
- cipher handle to calculate the message digest.
- </para>
- </listitem>
- </orderedlist>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="Development"><title>Developing Cipher Algorithms</title>
- <sect1><title>Registering And Unregistering Transformation</title>
- <para>
- There are three distinct types of registration functions in
- the Crypto API. One is used to register a generic cryptographic
- transformation, while the other two are specific to HASH
- transformations and COMPRESSion. We will discuss the latter
- two in a separate chapter, here we will only look at the
- generic ones.
- </para>
-
- <para>
- Before discussing the register functions, the data structure
- to be filled with each, struct crypto_alg, must be considered
- -- see below for a description of this data structure.
- </para>
-
- <para>
- The generic registration functions can be found in
- include/linux/crypto.h and their definition can be seen below.
- The former function registers a single transformation, while
- the latter works on an array of transformation descriptions.
- The latter is useful when registering transformations in bulk.
- </para>
-
- <programlisting>
- int crypto_register_alg(struct crypto_alg *alg);
- int crypto_register_algs(struct crypto_alg *algs, int count);
- </programlisting>
-
- <para>
- The counterparts to those functions are listed below.
- </para>
-
- <programlisting>
- int crypto_unregister_alg(struct crypto_alg *alg);
- int crypto_unregister_algs(struct crypto_alg *algs, int count);
- </programlisting>
-
- <para>
- Notice that both registration and unregistration functions
- do return a value, so make sure to handle errors. A return
- code of zero implies success. Any return code &lt; 0 implies
- an error.
- </para>
-
- <para>
- The bulk registration / unregistration functions require
- that struct crypto_alg is an array of count size. These
- functions simply loop over that array and register /
- unregister each individual algorithm. If an error occurs,
- the loop is terminated at the offending algorithm definition.
- That means, the algorithms prior to the offending algorithm
- are successfully registered. Note, the caller has no way of
- knowing which cipher implementations have successfully
- registered. If this is important to know, the caller should
- loop through the different implementations using the single
- instance *_alg functions for each individual implementation.
- </para>
- </sect1>
-
- <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title>
- <para>
- Example of transformations: aes, arc4, ...
- </para>
-
- <para>
- This section describes the simplest of all transformation
- implementations, that being the CIPHER type used for symmetric
- ciphers. The CIPHER type is used for transformations which
- operate on exactly one block at a time and there are no
- dependencies between blocks at all.
- </para>
-
- <sect2><title>Registration specifics</title>
- <para>
- The registration of [CIPHER] algorithm is specific in that
- struct crypto_alg field .cra_type is empty. The .cra_u.cipher
- has to be filled in with proper callbacks to implement this
- transformation.
- </para>
-
- <para>
- See struct cipher_alg below.
- </para>
- </sect2>
-
- <sect2><title>Cipher Definition With struct cipher_alg</title>
- <para>
- Struct cipher_alg defines a single block cipher.
- </para>
-
- <para>
- Here are schematics of how these functions are called when
- operated from other part of the kernel. Note that the
- .cia_setkey() call might happen before or after any of these
- schematics happen, but must not happen during any of these
- are in-flight.
- </para>
-
- <para>
- <programlisting>
- KEY ---. PLAINTEXT ---.
- v v
- .cia_setkey() -&gt; .cia_encrypt()
- |
- '-----&gt; CIPHERTEXT
- </programlisting>
- </para>
-
- <para>
- Please note that a pattern where .cia_setkey() is called
- multiple times is also valid:
- </para>
-
- <para>
- <programlisting>
-
- KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --.
- v v v v
- .cia_setkey() -&gt; .cia_encrypt() -&gt; .cia_setkey() -&gt; .cia_encrypt()
- | |
- '---&gt; CIPHERTEXT1 '---&gt; CIPHERTEXT2
- </programlisting>
- </para>
-
- </sect2>
- </sect1>
-
- <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title>
- <para>
- Example of transformations: cbc(aes), ecb(arc4), ...
- </para>
-
- <para>
- This section describes the multi-block cipher transformation
- implementations for both synchronous [BLKCIPHER] and
- asynchronous [ABLKCIPHER] case. The multi-block ciphers are
- used for transformations which operate on scatterlists of
- data supplied to the transformation functions. They output
- the result into a scatterlist of data as well.
- </para>
-
- <sect2><title>Registration Specifics</title>
-
- <para>
- The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms
- is one of the most standard procedures throughout the crypto API.
- </para>
-
- <para>
- Note, if a cipher implementation requires a proper alignment
- of data, the caller should use the functions of
- crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask()
- respectively to identify a memory alignment mask. The kernel
- crypto API is able to process requests that are unaligned.
- This implies, however, additional overhead as the kernel
- crypto API needs to perform the realignment of the data which
- may imply moving of data.
- </para>
- </sect2>
-
- <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title>
- <para>
- Struct blkcipher_alg defines a synchronous block cipher whereas
- struct ablkcipher_alg defines an asynchronous block cipher.
- </para>
-
- <para>
- Please refer to the single block cipher description for schematics
- of the block cipher usage. The usage patterns are exactly the same
- for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER].
- </para>
- </sect2>
-
- <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title>
- <para>
- There are a couple of specifics to the [ABLKCIPHER] interface.
- </para>
-
- <para>
- First of all, some of the drivers will want to use the
- Generic ScatterWalk in case the hardware needs to be fed
- separate chunks of the scatterlist which contains the
- plaintext and will contain the ciphertext. Please refer
- to the ScatterWalk interface offered by the Linux kernel
- scatter / gather list implementation.
- </para>
- </sect2>
- </sect1>
-
- <sect1><title>Hashing [HASH]</title>
-
- <para>
- Example of transformations: crc32, md5, sha1, sha256,...
- </para>
-
- <sect2><title>Registering And Unregistering The Transformation</title>
-
- <para>
- There are multiple ways to register a HASH transformation,
- depending on whether the transformation is synchronous [SHASH]
- or asynchronous [AHASH] and the amount of HASH transformations
- we are registering. You can find the prototypes defined in
- include/crypto/internal/hash.h:
- </para>
-
- <programlisting>
- int crypto_register_ahash(struct ahash_alg *alg);
-
- int crypto_register_shash(struct shash_alg *alg);
- int crypto_register_shashes(struct shash_alg *algs, int count);
- </programlisting>
-
- <para>
- The respective counterparts for unregistering the HASH
- transformation are as follows:
- </para>
-
- <programlisting>
- int crypto_unregister_ahash(struct ahash_alg *alg);
-
- int crypto_unregister_shash(struct shash_alg *alg);
- int crypto_unregister_shashes(struct shash_alg *algs, int count);
- </programlisting>
- </sect2>
-
- <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title>
- <para>
- Here are schematics of how these functions are called when
- operated from other part of the kernel. Note that the .setkey()
- call might happen before or after any of these schematics happen,
- but must not happen during any of these are in-flight. Please note
- that calling .init() followed immediately by .finish() is also a
- perfectly valid transformation.
- </para>
-
- <programlisting>
- I) DATA -----------.
- v
- .init() -&gt; .update() -&gt; .final() ! .update() might not be called
- ^ | | at all in this scenario.
- '----' '---&gt; HASH
-
- II) DATA -----------.-----------.
- v v
- .init() -&gt; .update() -&gt; .finup() ! .update() may not be called
- ^ | | at all in this scenario.
- '----' '---&gt; HASH
-
- III) DATA -----------.
- v
- .digest() ! The entire process is handled
- | by the .digest() call.
- '---------------&gt; HASH
- </programlisting>
-
- <para>
- Here is a schematic of how the .export()/.import() functions are
- called when used from another part of the kernel.
- </para>
-
- <programlisting>
- KEY--. DATA--.
- v v ! .update() may not be called
- .setkey() -&gt; .init() -&gt; .update() -&gt; .export() at all in this scenario.
- ^ | |
- '-----' '--&gt; PARTIAL_HASH
-
- ----------- other transformations happen here -----------
-
- PARTIAL_HASH--. DATA1--.
- v v
- .import -&gt; .update() -&gt; .final() ! .update() may not be called
- ^ | | at all in this scenario.
- '----' '--&gt; HASH1
-
- PARTIAL_HASH--. DATA2-.
- v v
- .import -&gt; .finup()
- |
- '---------------&gt; HASH2
- </programlisting>
- </sect2>
-
- <sect2><title>Specifics Of Asynchronous HASH Transformation</title>
- <para>
- Some of the drivers will want to use the Generic ScatterWalk
- in case the implementation needs to be fed separate chunks of the
- scatterlist which contains the input data. The buffer containing
- the resulting hash will always be properly aligned to
- .cra_alignmask so there is no need to worry about this.
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="User"><title>User Space Interface</title>
- <sect1><title>Introduction</title>
- <para>
- The concepts of the kernel crypto API visible to kernel space is fully
- applicable to the user space interface as well. Therefore, the kernel
- crypto API high level discussion for the in-kernel use cases applies
- here as well.
- </para>
-
- <para>
- The major difference, however, is that user space can only act as a
- consumer and never as a provider of a transformation or cipher algorithm.
- </para>
-
- <para>
- The following covers the user space interface exported by the kernel
- crypto API. A working example of this description is libkcapi that
- can be obtained from [1]. That library can be used by user space
- applications that require cryptographic services from the kernel.
- </para>
-
- <para>
- Some details of the in-kernel kernel crypto API aspects do not
- apply to user space, however. This includes the difference between
- synchronous and asynchronous invocations. The user space API call
- is fully synchronous.
- </para>
-
- <para>
- [1] http://www.chronox.de/libkcapi.html
- </para>
-
- </sect1>
-
- <sect1><title>User Space API General Remarks</title>
- <para>
- The kernel crypto API is accessible from user space. Currently,
- the following ciphers are accessible:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Message digest including keyed message digest (HMAC, CMAC)</para>
- </listitem>
-
- <listitem>
- <para>Symmetric ciphers</para>
- </listitem>
-
- <listitem>
- <para>AEAD ciphers</para>
- </listitem>
-
- <listitem>
- <para>Random Number Generators</para>
- </listitem>
- </itemizedlist>
-
- <para>
- The interface is provided via socket type using the type AF_ALG.
- In addition, the setsockopt option type is SOL_ALG. In case the
- user space header files do not export these flags yet, use the
- following macros:
- </para>
-
- <programlisting>
-#ifndef AF_ALG
-#define AF_ALG 38
-#endif
-#ifndef SOL_ALG
-#define SOL_ALG 279
-#endif
- </programlisting>
-
- <para>
- A cipher is accessed with the same name as done for the in-kernel
- API calls. This includes the generic vs. unique naming schema for
- ciphers as well as the enforcement of priorities for generic names.
- </para>
-
- <para>
- To interact with the kernel crypto API, a socket must be
- created by the user space application. User space invokes the cipher
- operation with the send()/write() system call family. The result of the
- cipher operation is obtained with the read()/recv() system call family.
- </para>
-
- <para>
- The following API calls assume that the socket descriptor
- is already opened by the user space application and discusses only
- the kernel crypto API specific invocations.
- </para>
-
- <para>
- To initialize the socket interface, the following sequence has to
- be performed by the consumer:
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- Create a socket of type AF_ALG with the struct sockaddr_alg
- parameter specified below for the different cipher types.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Invoke bind with the socket descriptor
- </para>
- </listitem>
-
- <listitem>
- <para>
- Invoke accept with the socket descriptor. The accept system call
- returns a new file descriptor that is to be used to interact with
- the particular cipher instance. When invoking send/write or recv/read
- system calls to send data to the kernel or obtain data from the
- kernel, the file descriptor returned by accept must be used.
- </para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1><title>In-place Cipher operation</title>
- <para>
- Just like the in-kernel operation of the kernel crypto API, the user
- space interface allows the cipher operation in-place. That means that
- the input buffer used for the send/write system call and the output
- buffer used by the read/recv system call may be one and the same.
- This is of particular interest for symmetric cipher operations where a
- copying of the output data to its final destination can be avoided.
- </para>
-
- <para>
- If a consumer on the other hand wants to maintain the plaintext and
- the ciphertext in different memory locations, all a consumer needs
- to do is to provide different memory pointers for the encryption and
- decryption operation.
- </para>
- </sect1>
-
- <sect1><title>Message Digest API</title>
- <para>
- The message digest type to be used for the cipher operation is
- selected when invoking the bind syscall. bind requires the caller
- to provide a filled struct sockaddr data structure. This data
- structure must be filled as follows:
- </para>
-
- <programlisting>
-struct sockaddr_alg sa = {
- .salg_family = AF_ALG,
- .salg_type = "hash", /* this selects the hash logic in the kernel */
- .salg_name = "sha1" /* this is the cipher name */
-};
- </programlisting>
-
- <para>
- The salg_type value "hash" applies to message digests and keyed
- message digests. Though, a keyed message digest is referenced by
- the appropriate salg_name. Please see below for the setsockopt
- interface that explains how the key can be set for a keyed message
- digest.
- </para>
-
- <para>
- Using the send() system call, the application provides the data that
- should be processed with the message digest. The send system call
- allows the following flags to be specified:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- MSG_MORE: If this flag is set, the send system call acts like a
- message digest update function where the final hash is not
- yet calculated. If the flag is not set, the send system call
- calculates the final message digest immediately.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- With the recv() system call, the application can read the message
- digest from the kernel crypto API. If the buffer is too small for the
- message digest, the flag MSG_TRUNC is set by the kernel.
- </para>
-
- <para>
- In order to set a message digest key, the calling application must use
- the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC
- operation is performed without the initial HMAC state change caused by
- the key.
- </para>
- </sect1>
-
- <sect1><title>Symmetric Cipher API</title>
- <para>
- The operation is very similar to the message digest discussion.
- During initialization, the struct sockaddr data structure must be
- filled as follows:
- </para>
-
- <programlisting>
-struct sockaddr_alg sa = {
- .salg_family = AF_ALG,
- .salg_type = "skcipher", /* this selects the symmetric cipher */
- .salg_name = "cbc(aes)" /* this is the cipher name */
-};
- </programlisting>
-
- <para>
- Before data can be sent to the kernel using the write/send system
- call family, the consumer must set the key. The key setting is
- described with the setsockopt invocation below.
- </para>
-
- <para>
- Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is
- specified with the data structure provided by the sendmsg() system call.
- </para>
-
- <para>
- The sendmsg system call parameter of struct msghdr is embedded into the
- struct cmsghdr data structure. See recv(2) and cmsg(3) for more
- information on how the cmsghdr data structure is used together with the
- send/recv system call family. That cmsghdr data structure holds the
- following information specified with a separate header instances:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- specification of the cipher operation type with one of these flags:
- </para>
- <itemizedlist>
- <listitem>
- <para>ALG_OP_ENCRYPT - encryption of data</para>
- </listitem>
- <listitem>
- <para>ALG_OP_DECRYPT - decryption of data</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- specification of the IV information marked with the flag ALG_SET_IV
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The send system call family allows the following flag to be specified:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- MSG_MORE: If this flag is set, the send system call acts like a
- cipher update function where more input data is expected
- with a subsequent invocation of the send system call.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Note: The kernel reports -EINVAL for any unexpected data. The caller
- must make sure that all data matches the constraints given in
- /proc/crypto for the selected cipher.
- </para>
-
- <para>
- With the recv() system call, the application can read the result of
- the cipher operation from the kernel crypto API. The output buffer
- must be at least as large as to hold all blocks of the encrypted or
- decrypted data. If the output data size is smaller, only as many
- blocks are returned that fit into that output buffer size.
- </para>
- </sect1>
-
- <sect1><title>AEAD Cipher API</title>
- <para>
- The operation is very similar to the symmetric cipher discussion.
- During initialization, the struct sockaddr data structure must be
- filled as follows:
- </para>
-
- <programlisting>
-struct sockaddr_alg sa = {
- .salg_family = AF_ALG,
- .salg_type = "aead", /* this selects the symmetric cipher */
- .salg_name = "gcm(aes)" /* this is the cipher name */
-};
- </programlisting>
-
- <para>
- Before data can be sent to the kernel using the write/send system
- call family, the consumer must set the key. The key setting is
- described with the setsockopt invocation below.
- </para>
-
- <para>
- In addition, before data can be sent to the kernel using the
- write/send system call family, the consumer must set the authentication
- tag size. To set the authentication tag size, the caller must use the
- setsockopt invocation described below.
- </para>
-
- <para>
- Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is
- specified with the data structure provided by the sendmsg() system call.
- </para>
-
- <para>
- The sendmsg system call parameter of struct msghdr is embedded into the
- struct cmsghdr data structure. See recv(2) and cmsg(3) for more
- information on how the cmsghdr data structure is used together with the
- send/recv system call family. That cmsghdr data structure holds the
- following information specified with a separate header instances:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- specification of the cipher operation type with one of these flags:
- </para>
- <itemizedlist>
- <listitem>
- <para>ALG_OP_ENCRYPT - encryption of data</para>
- </listitem>
- <listitem>
- <para>ALG_OP_DECRYPT - decryption of data</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- specification of the IV information marked with the flag ALG_SET_IV
- </para>
- </listitem>
-
- <listitem>
- <para>
- specification of the associated authentication data (AAD) with the
- flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together
- with the plaintext / ciphertext. See below for the memory structure.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The send system call family allows the following flag to be specified:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- MSG_MORE: If this flag is set, the send system call acts like a
- cipher update function where more input data is expected
- with a subsequent invocation of the send system call.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Note: The kernel reports -EINVAL for any unexpected data. The caller
- must make sure that all data matches the constraints given in
- /proc/crypto for the selected cipher.
- </para>
-
- <para>
- With the recv() system call, the application can read the result of
- the cipher operation from the kernel crypto API. The output buffer
- must be at least as large as defined with the memory structure below.
- If the output data size is smaller, the cipher operation is not performed.
- </para>
-
- <para>
- The authenticated decryption operation may indicate an integrity error.
- Such breach in integrity is marked with the -EBADMSG error code.
- </para>
-
- <sect2><title>AEAD Memory Structure</title>
- <para>
- The AEAD cipher operates with the following information that
- is communicated between user and kernel space as one data stream:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>plaintext or ciphertext</para>
- </listitem>
-
- <listitem>
- <para>associated authentication data (AAD)</para>
- </listitem>
-
- <listitem>
- <para>authentication tag</para>
- </listitem>
- </itemizedlist>
-
- <para>
- The sizes of the AAD and the authentication tag are provided with
- the sendmsg and setsockopt calls (see there). As the kernel knows
- the size of the entire data stream, the kernel is now able to
- calculate the right offsets of the data components in the data
- stream.
- </para>
-
- <para>
- The user space caller must arrange the aforementioned information
- in the following order:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- AEAD encryption input: AAD || plaintext
- </para>
- </listitem>
-
- <listitem>
- <para>
- AEAD decryption input: AAD || ciphertext || authentication tag
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The output buffer the user space caller provides must be at least as
- large to hold the following data:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- AEAD encryption output: ciphertext || authentication tag
- </para>
- </listitem>
-
- <listitem>
- <para>
- AEAD decryption output: plaintext
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <sect1><title>Random Number Generator API</title>
- <para>
- Again, the operation is very similar to the other APIs.
- During initialization, the struct sockaddr data structure must be
- filled as follows:
- </para>
-
- <programlisting>
-struct sockaddr_alg sa = {
- .salg_family = AF_ALG,
- .salg_type = "rng", /* this selects the symmetric cipher */
- .salg_name = "drbg_nopr_sha256" /* this is the cipher name */
-};
- </programlisting>
-
- <para>
- Depending on the RNG type, the RNG must be seeded. The seed is provided
- using the setsockopt interface to set the key. For example, the
- ansi_cprng requires a seed. The DRBGs do not require a seed, but
- may be seeded.
- </para>
-
- <para>
- Using the read()/recvmsg() system calls, random numbers can be obtained.
- The kernel generates at most 128 bytes in one call. If user space
- requires more data, multiple calls to read()/recvmsg() must be made.
- </para>
-
- <para>
- WARNING: The user space caller may invoke the initially mentioned
- accept system call multiple times. In this case, the returned file
- descriptors have the same state.
- </para>
-
- </sect1>
-
- <sect1><title>Zero-Copy Interface</title>
- <para>
- In addition to the send/write/read/recv system call familty, the AF_ALG
- interface can be accessed with the zero-copy interface of splice/vmsplice.
- As the name indicates, the kernel tries to avoid a copy operation into
- kernel space.
- </para>
-
- <para>
- The zero-copy operation requires data to be aligned at the page boundary.
- Non-aligned data can be used as well, but may require more operations of
- the kernel which would defeat the speed gains obtained from the zero-copy
- interface.
- </para>
-
- <para>
- The system-interent limit for the size of one zero-copy operation is
- 16 pages. If more data is to be sent to AF_ALG, user space must slice
- the input into segments with a maximum size of 16 pages.
- </para>
-
- <para>
- Zero-copy can be used with the following code example (a complete working
- example is provided with libkcapi):
- </para>
-
- <programlisting>
-int pipes[2];
-
-pipe(pipes);
-/* input data in iov */
-vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
-/* opfd is the file descriptor returned from accept() system call */
-splice(pipes[0], NULL, opfd, NULL, ret, 0);
-read(opfd, out, outlen);
- </programlisting>
-
- </sect1>
-
- <sect1><title>Setsockopt Interface</title>
- <para>
- In addition to the read/recv and send/write system call handling
- to send and retrieve data subject to the cipher operation, a consumer
- also needs to set the additional information for the cipher operation.
- This additional information is set using the setsockopt system call
- that must be invoked with the file descriptor of the open cipher
- (i.e. the file descriptor returned by the accept system call).
- </para>
-
- <para>
- Each setsockopt invocation must use the level SOL_ALG.
- </para>
-
- <para>
- The setsockopt interface allows setting the following data using
- the mentioned optname:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- ALG_SET_KEY -- Setting the key. Key setting is applicable to:
- </para>
- <itemizedlist>
- <listitem>
- <para>the skcipher cipher type (symmetric ciphers)</para>
- </listitem>
- <listitem>
- <para>the hash cipher type (keyed message digests)</para>
- </listitem>
- <listitem>
- <para>the AEAD cipher type</para>
- </listitem>
- <listitem>
- <para>the RNG cipher type to provide the seed</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size
- for AEAD ciphers. For a encryption operation, the authentication
- tag of the given size will be generated. For a decryption operation,
- the provided ciphertext is assumed to contain an authentication tag
- of the given size (see section about AEAD memory layout below).
- </para>
- </listitem>
- </itemizedlist>
-
- </sect1>
-
- <sect1><title>User space API example</title>
- <para>
- Please see [1] for libkcapi which provides an easy-to-use wrapper
- around the aforementioned Netlink kernel interface. [1] also contains
- a test application that invokes all libkcapi API calls.
- </para>
-
- <para>
- [1] http://www.chronox.de/libkcapi.html
- </para>
-
- </sect1>
-
- </chapter>
-
- <chapter id="API"><title>Programming Interface</title>
- <sect1><title>Block Cipher Context Data Structures</title>
-!Pinclude/linux/crypto.h Block Cipher Context Data Structures
-!Finclude/linux/crypto.h aead_request
- </sect1>
- <sect1><title>Block Cipher Algorithm Definitions</title>
-!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions
-!Finclude/linux/crypto.h crypto_alg
-!Finclude/linux/crypto.h ablkcipher_alg
-!Finclude/linux/crypto.h aead_alg
-!Finclude/linux/crypto.h blkcipher_alg
-!Finclude/linux/crypto.h cipher_alg
-!Finclude/linux/crypto.h rng_alg
- </sect1>
- <sect1><title>Asynchronous Block Cipher API</title>
-!Pinclude/linux/crypto.h Asynchronous Block Cipher API
-!Finclude/linux/crypto.h crypto_alloc_ablkcipher
-!Finclude/linux/crypto.h crypto_free_ablkcipher
-!Finclude/linux/crypto.h crypto_has_ablkcipher
-!Finclude/linux/crypto.h crypto_ablkcipher_ivsize
-!Finclude/linux/crypto.h crypto_ablkcipher_blocksize
-!Finclude/linux/crypto.h crypto_ablkcipher_setkey
-!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm
-!Finclude/linux/crypto.h crypto_ablkcipher_encrypt
-!Finclude/linux/crypto.h crypto_ablkcipher_decrypt
- </sect1>
- <sect1><title>Asynchronous Cipher Request Handle</title>
-!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle
-!Finclude/linux/crypto.h crypto_ablkcipher_reqsize
-!Finclude/linux/crypto.h ablkcipher_request_set_tfm
-!Finclude/linux/crypto.h ablkcipher_request_alloc
-!Finclude/linux/crypto.h ablkcipher_request_free
-!Finclude/linux/crypto.h ablkcipher_request_set_callback
-!Finclude/linux/crypto.h ablkcipher_request_set_crypt
- </sect1>
- <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title>
-!Pinclude/linux/crypto.h Authenticated Encryption With Associated Data (AEAD) Cipher API
-!Finclude/linux/crypto.h crypto_alloc_aead
-!Finclude/linux/crypto.h crypto_free_aead
-!Finclude/linux/crypto.h crypto_aead_ivsize
-!Finclude/linux/crypto.h crypto_aead_authsize
-!Finclude/linux/crypto.h crypto_aead_blocksize
-!Finclude/linux/crypto.h crypto_aead_setkey
-!Finclude/linux/crypto.h crypto_aead_setauthsize
-!Finclude/linux/crypto.h crypto_aead_encrypt
-!Finclude/linux/crypto.h crypto_aead_decrypt
- </sect1>
- <sect1><title>Asynchronous AEAD Request Handle</title>
-!Pinclude/linux/crypto.h Asynchronous AEAD Request Handle
-!Finclude/linux/crypto.h crypto_aead_reqsize
-!Finclude/linux/crypto.h aead_request_set_tfm
-!Finclude/linux/crypto.h aead_request_alloc
-!Finclude/linux/crypto.h aead_request_free
-!Finclude/linux/crypto.h aead_request_set_callback
-!Finclude/linux/crypto.h aead_request_set_crypt
-!Finclude/linux/crypto.h aead_request_set_assoc
- </sect1>
- <sect1><title>Synchronous Block Cipher API</title>
-!Pinclude/linux/crypto.h Synchronous Block Cipher API
-!Finclude/linux/crypto.h crypto_alloc_blkcipher
-!Finclude/linux/crypto.h crypto_free_blkcipher
-!Finclude/linux/crypto.h crypto_has_blkcipher
-!Finclude/linux/crypto.h crypto_blkcipher_name
-!Finclude/linux/crypto.h crypto_blkcipher_ivsize
-!Finclude/linux/crypto.h crypto_blkcipher_blocksize
-!Finclude/linux/crypto.h crypto_blkcipher_setkey
-!Finclude/linux/crypto.h crypto_blkcipher_encrypt
-!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv
-!Finclude/linux/crypto.h crypto_blkcipher_decrypt
-!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv
-!Finclude/linux/crypto.h crypto_blkcipher_set_iv
-!Finclude/linux/crypto.h crypto_blkcipher_get_iv
- </sect1>
- <sect1><title>Single Block Cipher API</title>
-!Pinclude/linux/crypto.h Single Block Cipher API
-!Finclude/linux/crypto.h crypto_alloc_cipher
-!Finclude/linux/crypto.h crypto_free_cipher
-!Finclude/linux/crypto.h crypto_has_cipher
-!Finclude/linux/crypto.h crypto_cipher_blocksize
-!Finclude/linux/crypto.h crypto_cipher_setkey
-!Finclude/linux/crypto.h crypto_cipher_encrypt_one
-!Finclude/linux/crypto.h crypto_cipher_decrypt_one
- </sect1>
- <sect1><title>Synchronous Message Digest API</title>
-!Pinclude/linux/crypto.h Synchronous Message Digest API
-!Finclude/linux/crypto.h crypto_alloc_hash
-!Finclude/linux/crypto.h crypto_free_hash
-!Finclude/linux/crypto.h crypto_has_hash
-!Finclude/linux/crypto.h crypto_hash_blocksize
-!Finclude/linux/crypto.h crypto_hash_digestsize
-!Finclude/linux/crypto.h crypto_hash_init
-!Finclude/linux/crypto.h crypto_hash_update
-!Finclude/linux/crypto.h crypto_hash_final
-!Finclude/linux/crypto.h crypto_hash_digest
-!Finclude/linux/crypto.h crypto_hash_setkey
- </sect1>
- <sect1><title>Message Digest Algorithm Definitions</title>
-!Pinclude/crypto/hash.h Message Digest Algorithm Definitions
-!Finclude/crypto/hash.h hash_alg_common
-!Finclude/crypto/hash.h ahash_alg
-!Finclude/crypto/hash.h shash_alg
- </sect1>
- <sect1><title>Asynchronous Message Digest API</title>
-!Pinclude/crypto/hash.h Asynchronous Message Digest API
-!Finclude/crypto/hash.h crypto_alloc_ahash
-!Finclude/crypto/hash.h crypto_free_ahash
-!Finclude/crypto/hash.h crypto_ahash_init
-!Finclude/crypto/hash.h crypto_ahash_digestsize
-!Finclude/crypto/hash.h crypto_ahash_reqtfm
-!Finclude/crypto/hash.h crypto_ahash_reqsize
-!Finclude/crypto/hash.h crypto_ahash_setkey
-!Finclude/crypto/hash.h crypto_ahash_finup
-!Finclude/crypto/hash.h crypto_ahash_final
-!Finclude/crypto/hash.h crypto_ahash_digest
-!Finclude/crypto/hash.h crypto_ahash_export
-!Finclude/crypto/hash.h crypto_ahash_import
- </sect1>
- <sect1><title>Asynchronous Hash Request Handle</title>
-!Pinclude/crypto/hash.h Asynchronous Hash Request Handle
-!Finclude/crypto/hash.h ahash_request_set_tfm
-!Finclude/crypto/hash.h ahash_request_alloc
-!Finclude/crypto/hash.h ahash_request_free
-!Finclude/crypto/hash.h ahash_request_set_callback
-!Finclude/crypto/hash.h ahash_request_set_crypt
- </sect1>
- <sect1><title>Synchronous Message Digest API</title>
-!Pinclude/crypto/hash.h Synchronous Message Digest API
-!Finclude/crypto/hash.h crypto_alloc_shash
-!Finclude/crypto/hash.h crypto_free_shash
-!Finclude/crypto/hash.h crypto_shash_blocksize
-!Finclude/crypto/hash.h crypto_shash_digestsize
-!Finclude/crypto/hash.h crypto_shash_descsize
-!Finclude/crypto/hash.h crypto_shash_setkey
-!Finclude/crypto/hash.h crypto_shash_digest
-!Finclude/crypto/hash.h crypto_shash_export
-!Finclude/crypto/hash.h crypto_shash_import
-!Finclude/crypto/hash.h crypto_shash_init
-!Finclude/crypto/hash.h crypto_shash_update
-!Finclude/crypto/hash.h crypto_shash_final
-!Finclude/crypto/hash.h crypto_shash_finup
- </sect1>
- <sect1><title>Crypto API Random Number API</title>
-!Pinclude/crypto/rng.h Random number generator API
-!Finclude/crypto/rng.h crypto_alloc_rng
-!Finclude/crypto/rng.h crypto_rng_alg
-!Finclude/crypto/rng.h crypto_free_rng
-!Finclude/crypto/rng.h crypto_rng_get_bytes
-!Finclude/crypto/rng.h crypto_rng_reset
-!Finclude/crypto/rng.h crypto_rng_seedsize
-!Cinclude/crypto/rng.h
- </sect1>
- </chapter>
-
- <chapter id="Code"><title>Code Examples</title>
- <sect1><title>Code Example For Asynchronous Block Cipher Operation</title>
- <programlisting>
-
-struct tcrypt_result {
- struct completion completion;
- int err;
-};
-
-/* tie all data structures together */
-struct ablkcipher_def {
- struct scatterlist sg;
- struct crypto_ablkcipher *tfm;
- struct ablkcipher_request *req;
- struct tcrypt_result result;
-};
-
-/* Callback function */
-static void test_ablkcipher_cb(struct crypto_async_request *req, int error)
-{
- struct tcrypt_result *result = req-&gt;data;
-
- if (error == -EINPROGRESS)
- return;
- result-&gt;err = error;
- complete(&amp;result-&gt;completion);
- pr_info("Encryption finished successfully\n");
-}
-
-/* Perform cipher operation */
-static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk,
- int enc)
-{
- int rc = 0;
-
- if (enc)
- rc = crypto_ablkcipher_encrypt(ablk-&gt;req);
- else
- rc = crypto_ablkcipher_decrypt(ablk-&gt;req);
-
- switch (rc) {
- case 0:
- break;
- case -EINPROGRESS:
- case -EBUSY:
- rc = wait_for_completion_interruptible(
- &amp;ablk-&gt;result.completion);
- if (!rc &amp;&amp; !ablk-&gt;result.err) {
- reinit_completion(&amp;ablk-&gt;result.completion);
- break;
- }
- default:
- pr_info("ablkcipher encrypt returned with %d result %d\n",
- rc, ablk-&gt;result.err);
- break;
- }
- init_completion(&amp;ablk-&gt;result.completion);
-
- return rc;
-}
-
-/* Initialize and trigger cipher operation */
-static int test_ablkcipher(void)
-{
- struct ablkcipher_def ablk;
- struct crypto_ablkcipher *ablkcipher = NULL;
- struct ablkcipher_request *req = NULL;
- char *scratchpad = NULL;
- char *ivdata = NULL;
- unsigned char key[32];
- int ret = -EFAULT;
-
- ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0);
- if (IS_ERR(ablkcipher)) {
- pr_info("could not allocate ablkcipher handle\n");
- return PTR_ERR(ablkcipher);
- }
-
- req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL);
- if (IS_ERR(req)) {
- pr_info("could not allocate request queue\n");
- ret = PTR_ERR(req);
- goto out;
- }
-
- ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
- test_ablkcipher_cb,
- &amp;ablk.result);
-
- /* AES 256 with random key */
- get_random_bytes(&amp;key, 32);
- if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) {
- pr_info("key could not be set\n");
- ret = -EAGAIN;
- goto out;
- }
-
- /* IV will be random */
- ivdata = kmalloc(16, GFP_KERNEL);
- if (!ivdata) {
- pr_info("could not allocate ivdata\n");
- goto out;
- }
- get_random_bytes(ivdata, 16);
-
- /* Input data will be random */
- scratchpad = kmalloc(16, GFP_KERNEL);
- if (!scratchpad) {
- pr_info("could not allocate scratchpad\n");
- goto out;
- }
- get_random_bytes(scratchpad, 16);
-
- ablk.tfm = ablkcipher;
- ablk.req = req;
-
- /* We encrypt one block */
- sg_init_one(&amp;ablk.sg, scratchpad, 16);
- ablkcipher_request_set_crypt(req, &amp;ablk.sg, &amp;ablk.sg, 16, ivdata);
- init_completion(&amp;ablk.result.completion);
-
- /* encrypt data */
- ret = test_ablkcipher_encdec(&amp;ablk, 1);
- if (ret)
- goto out;
-
- pr_info("Encryption triggered successfully\n");
-
-out:
- if (ablkcipher)
- crypto_free_ablkcipher(ablkcipher);
- if (req)
- ablkcipher_request_free(req);
- if (ivdata)
- kfree(ivdata);
- if (scratchpad)
- kfree(scratchpad);
- return ret;
-}
- </programlisting>
- </sect1>
-
- <sect1><title>Code Example For Synchronous Block Cipher Operation</title>
- <programlisting>
-
-static int test_blkcipher(void)
-{
- struct crypto_blkcipher *blkcipher = NULL;
- char *cipher = "cbc(aes)";
- // AES 128
- charkey =
-"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";
- chariv =
-"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";
- unsigned int ivsize = 0;
- char *scratchpad = NULL; // holds plaintext and ciphertext
- struct scatterlist sg;
- struct blkcipher_desc desc;
- int ret = -EFAULT;
-
- blkcipher = crypto_alloc_blkcipher(cipher, 0, 0);
- if (IS_ERR(blkcipher)) {
- printk("could not allocate blkcipher handle for %s\n", cipher);
- return -PTR_ERR(blkcipher);
- }
-
- if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) {
- printk("key could not be set\n");
- ret = -EAGAIN;
- goto out;
- }
-
- ivsize = crypto_blkcipher_ivsize(blkcipher);
- if (ivsize) {
- if (ivsize != strlen(iv))
- printk("IV length differs from expected length\n");
- crypto_blkcipher_set_iv(blkcipher, iv, ivsize);
- }
-
- scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL);
- if (!scratchpad) {
- printk("could not allocate scratchpad for %s\n", cipher);
- goto out;
- }
- /* get some random data that we want to encrypt */
- get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher));
-
- desc.flags = 0;
- desc.tfm = blkcipher;
- sg_init_one(&amp;sg, scratchpad, crypto_blkcipher_blocksize(blkcipher));
-
- /* encrypt data in place */
- crypto_blkcipher_encrypt(&amp;desc, &amp;sg, &amp;sg,
- crypto_blkcipher_blocksize(blkcipher));
-
- /* decrypt data in place
- * crypto_blkcipher_decrypt(&amp;desc, &amp;sg, &amp;sg,
- */ crypto_blkcipher_blocksize(blkcipher));
-
-
- printk("Cipher operation completed\n");
- return 0;
-
-out:
- if (blkcipher)
- crypto_free_blkcipher(blkcipher);
- if (scratchpad)
- kzfree(scratchpad);
- return ret;
-}
- </programlisting>
- </sect1>
-
- <sect1><title>Code Example For Use of Operational State Memory With SHASH</title>
- <programlisting>
-
-struct sdesc {
- struct shash_desc shash;
- char ctx[];
-};
-
-static struct sdescinit_sdesc(struct crypto_shash *alg)
-{
- struct sdescsdesc;
- int size;
-
- size = sizeof(struct shash_desc) + crypto_shash_descsize(alg);
- sdesc = kmalloc(size, GFP_KERNEL);
- if (!sdesc)
- return ERR_PTR(-ENOMEM);
- sdesc-&gt;shash.tfm = alg;
- sdesc-&gt;shash.flags = 0x0;
- return sdesc;
-}
-
-static int calc_hash(struct crypto_shashalg,
- const unsigned chardata, unsigned int datalen,
- unsigned chardigest) {
- struct sdescsdesc;
- int ret;
-
- sdesc = init_sdesc(alg);
- if (IS_ERR(sdesc)) {
- pr_info("trusted_key: can't alloc %s\n", hash_alg);
- return PTR_ERR(sdesc);
- }
-
- ret = crypto_shash_digest(&amp;sdesc-&gt;shash, data, datalen, digest);
- kfree(sdesc);
- return ret;
-}
- </programlisting>
- </sect1>
-
- <sect1><title>Code Example For Random Number Generator Usage</title>
- <programlisting>
-
-static int get_random_numbers(u8 *buf, unsigned int len)
-{
- struct crypto_rngrng = NULL;
- chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */
- int ret;
-
- if (!buf || !len) {
- pr_debug("No output buffer provided\n");
- return -EINVAL;
- }
-
- rng = crypto_alloc_rng(drbg, 0, 0);
- if (IS_ERR(rng)) {
- pr_debug("could not allocate RNG handle for %s\n", drbg);
- return -PTR_ERR(rng);
- }
-
- ret = crypto_rng_get_bytes(rng, buf, len);
- if (ret &lt; 0)
- pr_debug("generation of random numbers failed\n");
- else if (ret == 0)
- pr_debug("RNG returned no data");
- else
- pr_debug("RNG returned %d bytes of data\n", ret);
-
-out:
- crypto_free_rng(rng);
- return ret;
-}
- </programlisting>
- </sect1>
- </chapter>
- </book>
diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl
deleted file mode 100644
index 24979f691e3e..000000000000
--- a/Documentation/DocBook/debugobjects.tmpl
+++ /dev/null
@@ -1,441 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="debug-objects-guide">
- <bookinfo>
- <title>Debug objects life time</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2008</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- debugobjects is a generic infrastructure to track the life time
- of kernel objects and validate the operations on those.
- </para>
- <para>
- debugobjects is useful to check for the following error patterns:
- <itemizedlist>
- <listitem><para>Activation of uninitialized objects</para></listitem>
- <listitem><para>Initialization of active objects</para></listitem>
- <listitem><para>Usage of freed/destroyed objects</para></listitem>
- </itemizedlist>
- </para>
- <para>
- debugobjects is not changing the data structure of the real
- object so it can be compiled in with a minimal runtime impact
- and enabled on demand with a kernel command line option.
- </para>
- </chapter>
-
- <chapter id="howto">
- <title>Howto use debugobjects</title>
- <para>
- A kernel subsystem needs to provide a data structure which
- describes the object type and add calls into the debug code at
- appropriate places. The data structure to describe the object
- type needs at minimum the name of the object type. Optional
- functions can and should be provided to fixup detected problems
- so the kernel can continue to work and the debug information can
- be retrieved from a live system instead of hard core debugging
- with serial consoles and stack trace transcripts from the
- monitor.
- </para>
- <para>
- The debug calls provided by debugobjects are:
- <itemizedlist>
- <listitem><para>debug_object_init</para></listitem>
- <listitem><para>debug_object_init_on_stack</para></listitem>
- <listitem><para>debug_object_activate</para></listitem>
- <listitem><para>debug_object_deactivate</para></listitem>
- <listitem><para>debug_object_destroy</para></listitem>
- <listitem><para>debug_object_free</para></listitem>
- <listitem><para>debug_object_assert_init</para></listitem>
- </itemizedlist>
- Each of these functions takes the address of the real object and
- a pointer to the object type specific debug description
- structure.
- </para>
- <para>
- Each detected error is reported in the statistics and a limited
- number of errors are printk'ed including a full stack trace.
- </para>
- <para>
- The statistics are available via /sys/kernel/debug/debug_objects/stats.
- They provide information about the number of warnings and the
- number of successful fixups along with information about the
- usage of the internal tracking objects and the state of the
- internal tracking objects pool.
- </para>
- </chapter>
- <chapter id="debugfunctions">
- <title>Debug functions</title>
- <sect1 id="prototypes">
- <title>Debug object function reference</title>
-!Elib/debugobjects.c
- </sect1>
- <sect1 id="debug_object_init">
- <title>debug_object_init</title>
- <para>
- This function is called whenever the initialization function
- of a real object is called.
- </para>
- <para>
- When the real object is already tracked by debugobjects it is
- checked, whether the object can be initialized. Initializing
- is not allowed for active and destroyed objects. When
- debugobjects detects an error, then it calls the fixup_init
- function of the object type description structure if provided
- by the caller. The fixup function can correct the problem
- before the real initialization of the object happens. E.g. it
- can deactivate an active object in order to prevent damage to
- the subsystem.
- </para>
- <para>
- When the real object is not yet tracked by debugobjects,
- debugobjects allocates a tracker object for the real object
- and sets the tracker object state to ODEBUG_STATE_INIT. It
- verifies that the object is not on the callers stack. If it is
- on the callers stack then a limited number of warnings
- including a full stack trace is printk'ed. The calling code
- must use debug_object_init_on_stack() and remove the object
- before leaving the function which allocated it. See next
- section.
- </para>
- </sect1>
-
- <sect1 id="debug_object_init_on_stack">
- <title>debug_object_init_on_stack</title>
- <para>
- This function is called whenever the initialization function
- of a real object which resides on the stack is called.
- </para>
- <para>
- When the real object is already tracked by debugobjects it is
- checked, whether the object can be initialized. Initializing
- is not allowed for active and destroyed objects. When
- debugobjects detects an error, then it calls the fixup_init
- function of the object type description structure if provided
- by the caller. The fixup function can correct the problem
- before the real initialization of the object happens. E.g. it
- can deactivate an active object in order to prevent damage to
- the subsystem.
- </para>
- <para>
- When the real object is not yet tracked by debugobjects
- debugobjects allocates a tracker object for the real object
- and sets the tracker object state to ODEBUG_STATE_INIT. It
- verifies that the object is on the callers stack.
- </para>
- <para>
- An object which is on the stack must be removed from the
- tracker by calling debug_object_free() before the function
- which allocates the object returns. Otherwise we keep track of
- stale objects.
- </para>
- </sect1>
-
- <sect1 id="debug_object_activate">
- <title>debug_object_activate</title>
- <para>
- This function is called whenever the activation function of a
- real object is called.
- </para>
- <para>
- When the real object is already tracked by debugobjects it is
- checked, whether the object can be activated. Activating is
- not allowed for active and destroyed objects. When
- debugobjects detects an error, then it calls the
- fixup_activate function of the object type description
- structure if provided by the caller. The fixup function can
- correct the problem before the real activation of the object
- happens. E.g. it can deactivate an active object in order to
- prevent damage to the subsystem.
- </para>
- <para>
- When the real object is not yet tracked by debugobjects then
- the fixup_activate function is called if available. This is
- necessary to allow the legitimate activation of statically
- allocated and initialized objects. The fixup function checks
- whether the object is valid and calls the debug_objects_init()
- function to initialize the tracking of this object.
- </para>
- <para>
- When the activation is legitimate, then the state of the
- associated tracker object is set to ODEBUG_STATE_ACTIVE.
- </para>
- </sect1>
-
- <sect1 id="debug_object_deactivate">
- <title>debug_object_deactivate</title>
- <para>
- This function is called whenever the deactivation function of
- a real object is called.
- </para>
- <para>
- When the real object is tracked by debugobjects it is checked,
- whether the object can be deactivated. Deactivating is not
- allowed for untracked or destroyed objects.
- </para>
- <para>
- When the deactivation is legitimate, then the state of the
- associated tracker object is set to ODEBUG_STATE_INACTIVE.
- </para>
- </sect1>
-
- <sect1 id="debug_object_destroy">
- <title>debug_object_destroy</title>
- <para>
- This function is called to mark an object destroyed. This is
- useful to prevent the usage of invalid objects, which are
- still available in memory: either statically allocated objects
- or objects which are freed later.
- </para>
- <para>
- When the real object is tracked by debugobjects it is checked,
- whether the object can be destroyed. Destruction is not
- allowed for active and destroyed objects. When debugobjects
- detects an error, then it calls the fixup_destroy function of
- the object type description structure if provided by the
- caller. The fixup function can correct the problem before the
- real destruction of the object happens. E.g. it can deactivate
- an active object in order to prevent damage to the subsystem.
- </para>
- <para>
- When the destruction is legitimate, then the state of the
- associated tracker object is set to ODEBUG_STATE_DESTROYED.
- </para>
- </sect1>
-
- <sect1 id="debug_object_free">
- <title>debug_object_free</title>
- <para>
- This function is called before an object is freed.
- </para>
- <para>
- When the real object is tracked by debugobjects it is checked,
- whether the object can be freed. Free is not allowed for
- active objects. When debugobjects detects an error, then it
- calls the fixup_free function of the object type description
- structure if provided by the caller. The fixup function can
- correct the problem before the real free of the object
- happens. E.g. it can deactivate an active object in order to
- prevent damage to the subsystem.
- </para>
- <para>
- Note that debug_object_free removes the object from the
- tracker. Later usage of the object is detected by the other
- debug checks.
- </para>
- </sect1>
-
- <sect1 id="debug_object_assert_init">
- <title>debug_object_assert_init</title>
- <para>
- This function is called to assert that an object has been
- initialized.
- </para>
- <para>
- When the real object is not tracked by debugobjects, it calls
- fixup_assert_init of the object type description structure
- provided by the caller, with the hardcoded object state
- ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem
- by calling debug_object_init and other specific initializing
- functions.
- </para>
- <para>
- When the real object is already tracked by debugobjects it is
- ignored.
- </para>
- </sect1>
- </chapter>
- <chapter id="fixupfunctions">
- <title>Fixup functions</title>
- <sect1 id="debug_obj_descr">
- <title>Debug object type description structure</title>
-!Iinclude/linux/debugobjects.h
- </sect1>
- <sect1 id="fixup_init">
- <title>fixup_init</title>
- <para>
- This function is called from the debug code whenever a problem
- in debug_object_init is detected. The function takes the
- address of the object and the state which is currently
- recorded in the tracker.
- </para>
- <para>
- Called from debug_object_init when the object state is:
- <itemizedlist>
- <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
- </itemizedlist>
- </para>
- <para>
- The function returns 1 when the fixup was successful,
- otherwise 0. The return value is used to update the
- statistics.
- </para>
- <para>
- Note, that the function needs to call the debug_object_init()
- function again, after the damage has been repaired in order to
- keep the state consistent.
- </para>
- </sect1>
-
- <sect1 id="fixup_activate">
- <title>fixup_activate</title>
- <para>
- This function is called from the debug code whenever a problem
- in debug_object_activate is detected.
- </para>
- <para>
- Called from debug_object_activate when the object state is:
- <itemizedlist>
- <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem>
- <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
- </itemizedlist>
- </para>
- <para>
- The function returns 1 when the fixup was successful,
- otherwise 0. The return value is used to update the
- statistics.
- </para>
- <para>
- Note that the function needs to call the debug_object_activate()
- function again after the damage has been repaired in order to
- keep the state consistent.
- </para>
- <para>
- The activation of statically initialized objects is a special
- case. When debug_object_activate() has no tracked object for
- this object address then fixup_activate() is called with
- object state ODEBUG_STATE_NOTAVAILABLE. The fixup function
- needs to check whether this is a legitimate case of a
- statically initialized object or not. In case it is it calls
- debug_object_init() and debug_object_activate() to make the
- object known to the tracker and marked active. In this case
- the function should return 0 because this is not a real fixup.
- </para>
- </sect1>
-
- <sect1 id="fixup_destroy">
- <title>fixup_destroy</title>
- <para>
- This function is called from the debug code whenever a problem
- in debug_object_destroy is detected.
- </para>
- <para>
- Called from debug_object_destroy when the object state is:
- <itemizedlist>
- <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
- </itemizedlist>
- </para>
- <para>
- The function returns 1 when the fixup was successful,
- otherwise 0. The return value is used to update the
- statistics.
- </para>
- </sect1>
- <sect1 id="fixup_free">
- <title>fixup_free</title>
- <para>
- This function is called from the debug code whenever a problem
- in debug_object_free is detected. Further it can be called
- from the debug checks in kfree/vfree, when an active object is
- detected from the debug_check_no_obj_freed() sanity checks.
- </para>
- <para>
- Called from debug_object_free() or debug_check_no_obj_freed()
- when the object state is:
- <itemizedlist>
- <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
- </itemizedlist>
- </para>
- <para>
- The function returns 1 when the fixup was successful,
- otherwise 0. The return value is used to update the
- statistics.
- </para>
- </sect1>
- <sect1 id="fixup_assert_init">
- <title>fixup_assert_init</title>
- <para>
- This function is called from the debug code whenever a problem
- in debug_object_assert_init is detected.
- </para>
- <para>
- Called from debug_object_assert_init() with a hardcoded state
- ODEBUG_STATE_NOTAVAILABLE when the object is not found in the
- debug bucket.
- </para>
- <para>
- The function returns 1 when the fixup was successful,
- otherwise 0. The return value is used to update the
- statistics.
- </para>
- <para>
- Note, this function should make sure debug_object_init() is
- called before returning.
- </para>
- <para>
- The handling of statically initialized objects is a special
- case. The fixup function should check if this is a legitimate
- case of a statically initialized object or not. In this case only
- debug_object_init() should be called to make the object known to
- the tracker. Then the function should return 0 because this is not
- a real fixup.
- </para>
- </sect1>
- </chapter>
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None (knock on wood).
- </para>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
deleted file mode 100644
index faf09d4a0ea8..000000000000
--- a/Documentation/DocBook/device-drivers.tmpl
+++ /dev/null
@@ -1,458 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="LinuxDriversAPI">
- <bookinfo>
- <title>Linux Device Drivers</title>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="Basics">
- <title>Driver Basics</title>
- <sect1><title>Driver Entry and Exit points</title>
-!Iinclude/linux/init.h
- </sect1>
-
- <sect1><title>Atomic and pointer manipulation</title>
-!Iarch/x86/include/asm/atomic.h
- </sect1>
-
- <sect1><title>Delaying, scheduling, and timer routines</title>
-!Iinclude/linux/sched.h
-!Ekernel/sched/core.c
-!Ikernel/sched/cpupri.c
-!Ikernel/sched/fair.c
-!Iinclude/linux/completion.h
-!Ekernel/time/timer.c
- </sect1>
- <sect1><title>Wait queues and Wake events</title>
-!Iinclude/linux/wait.h
-!Ekernel/sched/wait.c
- </sect1>
- <sect1><title>High-resolution timers</title>
-!Iinclude/linux/ktime.h
-!Iinclude/linux/hrtimer.h
-!Ekernel/time/hrtimer.c
- </sect1>
- <sect1><title>Workqueues and Kevents</title>
-!Ekernel/workqueue.c
- </sect1>
- <sect1><title>Internal Functions</title>
-!Ikernel/exit.c
-!Ikernel/signal.c
-!Iinclude/linux/kthread.h
-!Ekernel/kthread.c
- </sect1>
-
- <sect1><title>Kernel objects manipulation</title>
-<!--
-X!Iinclude/linux/kobject.h
--->
-!Elib/kobject.c
- </sect1>
-
- <sect1><title>Kernel utility functions</title>
-!Iinclude/linux/kernel.h
-!Ekernel/printk/printk.c
-!Ekernel/panic.c
-!Ekernel/sys.c
-!Ekernel/rcu/srcu.c
-!Ekernel/rcu/tree.c
-!Ekernel/rcu/tree_plugin.h
-!Ekernel/rcu/update.c
- </sect1>
-
- <sect1><title>Device Resource Management</title>
-!Edrivers/base/devres.c
- </sect1>
-
- </chapter>
-
- <chapter id="devdrivers">
- <title>Device drivers infrastructure</title>
- <sect1><title>The Basic Device Driver-Model Structures </title>
-!Iinclude/linux/device.h
- </sect1>
- <sect1><title>Device Drivers Base</title>
-!Idrivers/base/init.c
-!Edrivers/base/driver.c
-!Edrivers/base/core.c
-!Edrivers/base/syscore.c
-!Edrivers/base/class.c
-!Idrivers/base/node.c
-!Edrivers/base/firmware_class.c
-!Edrivers/base/transport_class.c
-<!-- Cannot be included, because
- attribute_container_add_class_device_adapter
- and attribute_container_classdev_to_container
- exceed allowed 44 characters maximum
-X!Edrivers/base/attribute_container.c
--->
-!Edrivers/base/dd.c
-<!--
-X!Edrivers/base/interface.c
--->
-!Iinclude/linux/platform_device.h
-!Edrivers/base/platform.c
-!Edrivers/base/bus.c
- </sect1>
- <sect1><title>Device Drivers DMA Management</title>
-!Edrivers/dma-buf/dma-buf.c
-!Edrivers/dma-buf/fence.c
-!Edrivers/dma-buf/seqno-fence.c
-!Iinclude/linux/fence.h
-!Iinclude/linux/seqno-fence.h
-!Edrivers/dma-buf/reservation.c
-!Iinclude/linux/reservation.h
-!Edrivers/base/dma-coherent.c
-!Edrivers/base/dma-mapping.c
- </sect1>
- <sect1><title>Device Drivers Power Management</title>
-!Edrivers/base/power/main.c
- </sect1>
- <sect1><title>Device Drivers ACPI Support</title>
-<!-- Internal functions only
-X!Edrivers/acpi/sleep/main.c
-X!Edrivers/acpi/sleep/wakeup.c
-X!Edrivers/acpi/motherboard.c
-X!Edrivers/acpi/bus.c
--->
-!Edrivers/acpi/scan.c
-!Idrivers/acpi/scan.c
-<!-- No correct structured comments
-X!Edrivers/acpi/pci_bind.c
--->
- </sect1>
- <sect1><title>Device drivers PnP support</title>
-!Idrivers/pnp/core.c
-<!-- No correct structured comments
-X!Edrivers/pnp/system.c
- -->
-!Edrivers/pnp/card.c
-!Idrivers/pnp/driver.c
-!Edrivers/pnp/manager.c
-!Edrivers/pnp/support.c
- </sect1>
- <sect1><title>Userspace IO devices</title>
-!Edrivers/uio/uio.c
-!Iinclude/linux/uio_driver.h
- </sect1>
- </chapter>
-
- <chapter id="parportdev">
- <title>Parallel Port Devices</title>
-!Iinclude/linux/parport.h
-!Edrivers/parport/ieee1284.c
-!Edrivers/parport/share.c
-!Idrivers/parport/daisy.c
- </chapter>
-
- <chapter id="message_devices">
- <title>Message-based devices</title>
- <sect1><title>Fusion message devices</title>
-!Edrivers/message/fusion/mptbase.c
-!Idrivers/message/fusion/mptbase.c
-!Edrivers/message/fusion/mptscsih.c
-!Idrivers/message/fusion/mptscsih.c
-!Idrivers/message/fusion/mptctl.c
-!Idrivers/message/fusion/mptspi.c
-!Idrivers/message/fusion/mptfc.c
-!Idrivers/message/fusion/mptlan.c
- </sect1>
- </chapter>
-
- <chapter id="snddev">
- <title>Sound Devices</title>
-!Iinclude/sound/core.h
-!Esound/sound_core.c
-!Iinclude/sound/pcm.h
-!Esound/core/pcm.c
-!Esound/core/device.c
-!Esound/core/info.c
-!Esound/core/rawmidi.c
-!Esound/core/sound.c
-!Esound/core/memory.c
-!Esound/core/pcm_memory.c
-!Esound/core/init.c
-!Esound/core/isadma.c
-!Esound/core/control.c
-!Esound/core/pcm_lib.c
-!Esound/core/hwdep.c
-!Esound/core/pcm_native.c
-!Esound/core/memalloc.c
-<!-- FIXME: Removed for now since no structured comments in source
-X!Isound/sound_firmware.c
--->
- </chapter>
-
- <chapter id="uart16x50">
- <title>16x50 UART Driver</title>
-!Edrivers/tty/serial/serial_core.c
-!Edrivers/tty/serial/8250/8250_core.c
- </chapter>
-
- <chapter id="fbdev">
- <title>Frame Buffer Library</title>
-
- <para>
- The frame buffer drivers depend heavily on four data structures.
- These structures are declared in include/linux/fb.h. They are
- fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
- The last three can be made available to and from userland.
- </para>
-
- <para>
- fb_info defines the current state of a particular video card.
- Inside fb_info, there exists a fb_ops structure which is a
- collection of needed functions to make fbdev and fbcon work.
- fb_info is only visible to the kernel.
- </para>
-
- <para>
- fb_var_screeninfo is used to describe the features of a video card
- that are user defined. With fb_var_screeninfo, things such as
- depth and the resolution may be defined.
- </para>
-
- <para>
- The next structure is fb_fix_screeninfo. This defines the
- properties of a card that are created when a mode is set and can't
- be changed otherwise. A good example of this is the start of the
- frame buffer memory. This "locks" the address of the frame buffer
- memory, so that it cannot be changed or moved.
- </para>
-
- <para>
- The last structure is fb_monospecs. In the old API, there was
- little importance for fb_monospecs. This allowed for forbidden things
- such as setting a mode of 800x600 on a fix frequency monitor. With
- the new API, fb_monospecs prevents such things, and if used
- correctly, can prevent a monitor from being cooked. fb_monospecs
- will not be useful until kernels 2.5.x.
- </para>
-
- <sect1><title>Frame Buffer Memory</title>
-!Edrivers/video/fbdev/core/fbmem.c
- </sect1>
-<!--
- <sect1><title>Frame Buffer Console</title>
-X!Edrivers/video/console/fbcon.c
- </sect1>
--->
- <sect1><title>Frame Buffer Colormap</title>
-!Edrivers/video/fbdev/core/fbcmap.c
- </sect1>
-<!-- FIXME:
- drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
- out until somebody adds docs. KAO
- <sect1><title>Frame Buffer Generic Functions</title>
-X!Idrivers/video/fbgen.c
- </sect1>
-KAO -->
- <sect1><title>Frame Buffer Video Mode Database</title>
-!Idrivers/video/fbdev/core/modedb.c
-!Edrivers/video/fbdev/core/modedb.c
- </sect1>
- <sect1><title>Frame Buffer Macintosh Video Mode Database</title>
-!Edrivers/video/fbdev/macmodes.c
- </sect1>
- <sect1><title>Frame Buffer Fonts</title>
- <para>
- Refer to the file lib/fonts/fonts.c for more information.
- </para>
-<!-- FIXME: Removed for now since no structured comments in source
-X!Ilib/fonts/fonts.c
--->
- </sect1>
- </chapter>
-
- <chapter id="input_subsystem">
- <title>Input Subsystem</title>
- <sect1><title>Input core</title>
-!Iinclude/linux/input.h
-!Edrivers/input/input.c
-!Edrivers/input/ff-core.c
-!Edrivers/input/ff-memless.c
- </sect1>
- <sect1><title>Multitouch Library</title>
-!Iinclude/linux/input/mt.h
-!Edrivers/input/input-mt.c
- </sect1>
- <sect1><title>Polled input devices</title>
-!Iinclude/linux/input-polldev.h
-!Edrivers/input/input-polldev.c
- </sect1>
- <sect1><title>Matrix keyboars/keypads</title>
-!Iinclude/linux/input/matrix_keypad.h
- </sect1>
- <sect1><title>Sparse keymap support</title>
-!Iinclude/linux/input/sparse-keymap.h
-!Edrivers/input/sparse-keymap.c
- </sect1>
- </chapter>
-
- <chapter id="spi">
- <title>Serial Peripheral Interface (SPI)</title>
- <para>
- SPI is the "Serial Peripheral Interface", widely used with
- embedded systems because it is a simple and efficient
- interface: basically a multiplexed shift register.
- Its three signal wires hold a clock (SCK, often in the range
- of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
- a "Master In, Slave Out" (MISO) data line.
- SPI is a full duplex protocol; for each bit shifted out the
- MOSI line (one per clock) another is shifted in on the MISO line.
- Those bits are assembled into words of various sizes on the
- way to and from system memory.
- An additional chipselect line is usually active-low (nCS);
- four signals are normally used for each peripheral, plus
- sometimes an interrupt.
- </para>
- <para>
- The SPI bus facilities listed here provide a generalized
- interface to declare SPI busses 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 to support implementing SPI slaves would
- necessarily look different.)
- </para>
- <para>
- The programming interface is structured around two kinds of driver,
- and two kinds of device.
- A "Controller Driver" abstracts the controller hardware, which may
- be as simple as a set of GPIO pins or as complex as a pair of FIFOs
- connected to dual DMA engines on the other side of the SPI shift
- register (maximizing throughput). Such drivers bridge between
- whatever bus they sit on (often the platform bus) and SPI, and
- expose the SPI side of their device as a
- <structname>struct spi_master</structname>.
- SPI devices are children of that master, represented as a
- <structname>struct spi_device</structname> and manufactured from
- <structname>struct spi_board_info</structname> descriptors which
- are usually provided by board-specific initialization code.
- A <structname>struct spi_driver</structname> is called a
- "Protocol Driver", and is bound to a spi_device using normal
- driver model calls.
- </para>
- <para>
- The I/O model is a set of queued messages. Protocol drivers
- submit one or more <structname>struct spi_message</structname>
- objects, which are processed and completed asynchronously.
- (There are synchronous wrappers, however.) Messages are
- built from one or more <structname>struct spi_transfer</structname>
- objects, each of which wraps a full duplex SPI transfer.
- A variety of protocol tweaking options are needed, because
- different chips adopt very different policies for how they
- use the bits transferred with SPI.
- </para>
-!Iinclude/linux/spi/spi.h
-!Fdrivers/spi/spi.c spi_register_board_info
-!Edrivers/spi/spi.c
- </chapter>
-
- <chapter id="i2c">
- <title>I<superscript>2</superscript>C and SMBus Subsystem</title>
-
- <para>
- I<superscript>2</superscript>C (or without fancy typography, "I2C")
- is an acronym for the "Inter-IC" bus, a simple bus protocol which is
- widely used where low data rate communications suffice.
- Since it's also a licensed trademark, some vendors use another
- name (such as "Two-Wire Interface", TWI) for the same bus.
- I2C only needs two signals (SCL for clock, SDA for data), conserving
- board real estate and minimizing signal quality issues.
- Most I2C devices use seven bit addresses, and bus speeds of up
- to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
- found wide use.
- I2C is a multi-master bus; open drain signaling is used to
- arbitrate between masters, as well as to handshake and to
- synchronize clocks from slower clients.
- </para>
-
- <para>
- The Linux I2C programming interfaces support only the master
- side of bus interactions, not the slave side.
- The programming interface is structured around two kinds of driver,
- and two kinds of device.
- An I2C "Adapter Driver" abstracts the controller hardware; it binds
- to a physical device (perhaps a PCI device or platform_device) and
- exposes a <structname>struct i2c_adapter</structname> representing
- each I2C bus segment it manages.
- On each I2C bus segment will be I2C devices represented by a
- <structname>struct i2c_client</structname>. Those devices will
- be bound to a <structname>struct i2c_driver</structname>,
- which should follow the standard Linux driver model.
- (At this writing, a legacy model is more widely used.)
- There are functions to perform various I2C protocol operations; at
- this writing all such functions are usable only from task context.
- </para>
-
- <para>
- The System Management Bus (SMBus) is a sibling protocol. Most SMBus
- systems are also I2C conformant. The electrical constraints are
- tighter for SMBus, and it standardizes particular protocol messages
- and idioms. Controllers that support I2C can also support most
- SMBus operations, but SMBus controllers don't support all the protocol
- options that an I2C controller will.
- There are functions to perform various SMBus protocol operations,
- either using I2C primitives or by issuing SMBus commands to
- i2c_adapter devices which don't support those I2C operations.
- </para>
-
-!Iinclude/linux/i2c.h
-!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
-!Edrivers/i2c/i2c-core.c
- </chapter>
-
- <chapter id="hsi">
- <title>High Speed Synchronous Serial Interface (HSI)</title>
-
- <para>
- High Speed Synchronous Serial Interface (HSI) is a
- serial interface mainly used for connecting application
- engines (APE) with cellular modem engines (CMT) in cellular
- handsets.
-
- HSI provides multiplexing for up to 16 logical channels,
- low-latency and full duplex communication.
- </para>
-
-!Iinclude/linux/hsi/hsi.h
-!Edrivers/hsi/hsi.c
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl
deleted file mode 100644
index 54199a0dcf9a..000000000000
--- a/Documentation/DocBook/deviceiobook.tmpl
+++ /dev/null
@@ -1,323 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="DoingIO">
- <bookinfo>
- <title>Bus-Independent Device Accesses</title>
-
- <authorgroup>
- <author>
- <firstname>Matthew</firstname>
- <surname>Wilcox</surname>
- <affiliation>
- <address>
- <email>matthew@wil.cx</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <authorgroup>
- <author>
- <firstname>Alan</firstname>
- <surname>Cox</surname>
- <affiliation>
- <address>
- <email>alan@lxorguk.ukuu.org.uk</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2001</year>
- <holder>Matthew Wilcox</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- Linux provides an API which abstracts performing IO across all busses
- and devices, allowing device drivers to be written independently of
- bus type.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None.
- </para>
- </chapter>
-
- <chapter id="mmio">
- <title>Memory Mapped IO</title>
- <sect1 id="getting_access_to_the_device">
- <title>Getting Access to the Device</title>
- <para>
- The most widely supported form of IO is memory mapped IO.
- That is, a part of the CPU's address space is interpreted
- not as accesses to memory, but as accesses to a device. Some
- architectures define devices to be at a fixed address, but most
- have some method of discovering devices. The PCI bus walk is a
- good example of such a scheme. This document does not cover how
- to receive such an address, but assumes you are starting with one.
- Physical addresses are of type unsigned long.
- </para>
-
- <para>
- This address should not be used directly. Instead, to get an
- address suitable for passing to the accessor functions described
- below, you should call <function>ioremap</function>.
- An address suitable for accessing the device will be returned to you.
- </para>
-
- <para>
- After you've finished using the device (say, in your module's
- exit routine), call <function>iounmap</function> in order to return
- the address space to the kernel. Most architectures allocate new
- address space each time you call <function>ioremap</function>, and
- they can run out unless you call <function>iounmap</function>.
- </para>
- </sect1>
-
- <sect1 id="accessing_the_device">
- <title>Accessing the device</title>
- <para>
- The part of the interface most used by drivers is reading and
- writing memory-mapped registers on the device. Linux provides
- interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit
- quantities. Due to a historical accident, these are named byte,
- word, long and quad accesses. Both read and write accesses are
- supported; there is no prefetch support at this time.
- </para>
-
- <para>
- The functions are named <function>readb</function>,
- <function>readw</function>, <function>readl</function>,
- <function>readq</function>, <function>readb_relaxed</function>,
- <function>readw_relaxed</function>, <function>readl_relaxed</function>,
- <function>readq_relaxed</function>, <function>writeb</function>,
- <function>writew</function>, <function>writel</function> and
- <function>writeq</function>.
- </para>
-
- <para>
- Some devices (such as framebuffers) would like to use larger
- transfers than 8 bytes at a time. For these devices, the
- <function>memcpy_toio</function>, <function>memcpy_fromio</function>
- and <function>memset_io</function> functions are provided.
- Do not use memset or memcpy on IO addresses; they
- are not guaranteed to copy data in order.
- </para>
-
- <para>
- The read and write functions are defined to be ordered. That is the
- compiler is not permitted to reorder the I/O sequence. When the
- ordering can be compiler optimised, you can use <function>
- __readb</function> and friends to indicate the relaxed ordering. Use
- this with care.
- </para>
-
- <para>
- 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 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 writes have occurred in the specific cases the
- author cares. This kind of property cannot be hidden from driver
- writers in the API. In some cases, the read used to flush the device
- may be expected to fail (if the card is resetting, for example). In
- that case, the read should be done from config space, which is
- guaranteed to soft-fail if the card doesn't respond.
- </para>
-
- <para>
- The following is an example of flushing a write to a device when
- the driver would like to ensure the write's effects are visible prior
- to continuing execution.
- </para>
-
-<programlisting>
-static inline void
-qla1280_disable_intrs(struct scsi_qla_host *ha)
-{
- struct device_reg *reg;
-
- reg = ha->iobase;
- /* disable risc and host interrupts */
- WRT_REG_WORD(&amp;reg->ictrl, 0);
- /*
- * The following read will ensure that the above write
- * has been received by the device before we return from this
- * function.
- */
- RD_REG_WORD(&amp;reg->ictrl);
- ha->flags.ints_enabled = 0;
-}
-</programlisting>
-
- <para>
- In addition to write posting, on some large multiprocessing systems
- (e.g. SGI Challenge, Origin and Altix machines) posted writes won't
- be strongly ordered coming from different CPUs. Thus it's important
- to properly protect parts of your driver that do memory-mapped writes
- with locks and use the <function>mmiowb</function> to make sure they
- arrive in the order intended. Issuing a regular <function>readX
- </function> will also ensure write ordering, but should only be used
- when the driver has to be sure that the write has actually arrived
- at the device (not that it's simply ordered with respect to other
- writes), since a full <function>readX</function> is a relatively
- expensive operation.
- </para>
-
- <para>
- Generally, one should use <function>mmiowb</function> prior to
- releasing a spinlock that protects regions using <function>writeb
- </function> or similar functions that aren't surrounded by <function>
- readb</function> calls, which will ensure ordering and flushing. The
- following pseudocode illustrates what might occur if write ordering
- isn't guaranteed via <function>mmiowb</function> or one of the
- <function>readX</function> functions.
- </para>
-
-<programlisting>
-CPU A: spin_lock_irqsave(&amp;dev_lock, flags)
-CPU A: ...
-CPU A: writel(newval, ring_ptr);
-CPU A: spin_unlock_irqrestore(&amp;dev_lock, flags)
- ...
-CPU B: spin_lock_irqsave(&amp;dev_lock, flags)
-CPU B: writel(newval2, ring_ptr);
-CPU B: ...
-CPU B: spin_unlock_irqrestore(&amp;dev_lock, flags)
-</programlisting>
-
- <para>
- In the case above, newval2 could be written to ring_ptr before
- newval. Fixing it is easy though:
- </para>
-
-<programlisting>
-CPU A: spin_lock_irqsave(&amp;dev_lock, flags)
-CPU A: ...
-CPU A: writel(newval, ring_ptr);
-CPU A: mmiowb(); /* ensure no other writes beat us to the device */
-CPU A: spin_unlock_irqrestore(&amp;dev_lock, flags)
- ...
-CPU B: spin_lock_irqsave(&amp;dev_lock, flags)
-CPU B: writel(newval2, ring_ptr);
-CPU B: ...
-CPU B: mmiowb();
-CPU B: spin_unlock_irqrestore(&amp;dev_lock, flags)
-</programlisting>
-
- <para>
- See tg3.c for a real world example of how to use <function>mmiowb
- </function>
- </para>
-
- <para>
- PCI ordering rules also guarantee that PIO read responses arrive
- after any outstanding DMA writes from that bus, since for some devices
- the result of a <function>readb</function> call may signal to the
- driver that a DMA transaction is complete. In many cases, however,
- the driver may want to indicate that the next
- <function>readb</function> call has no relation to any previous DMA
- writes performed by the device. The driver can use
- <function>readb_relaxed</function> for these cases, although only
- some platforms will honor the relaxed semantics. Using the relaxed
- read functions will provide significant performance benefits on
- platforms that support it. The qla2xxx driver provides examples
- of how to use <function>readX_relaxed</function>. In many cases,
- a majority of the driver's <function>readX</function> calls can
- safely be converted to <function>readX_relaxed</function> calls, since
- only a few will indicate or depend on DMA completion.
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="port_space_accesses">
- <title>Port Space Accesses</title>
- <sect1 id="port_space_explained">
- <title>Port Space Explained</title>
-
- <para>
- Another form of IO commonly supported is Port Space. This is a
- range of addresses separate to the normal memory address space.
- Access to these addresses is generally not as fast as accesses
- to the memory mapped addresses, and it also has a potentially
- smaller address space.
- </para>
-
- <para>
- Unlike memory mapped IO, no preparation is required
- to access port space.
- </para>
-
- </sect1>
- <sect1 id="accessing_port_space">
- <title>Accessing Port Space</title>
- <para>
- Accesses to this space are provided through a set of functions
- which allow 8-bit, 16-bit and 32-bit accesses; also
- known as byte, word and long. These functions are
- <function>inb</function>, <function>inw</function>,
- <function>inl</function>, <function>outb</function>,
- <function>outw</function> and <function>outl</function>.
- </para>
-
- <para>
- Some variants are provided for these functions. Some devices
- require that accesses to their ports are slowed down. This
- functionality is provided by appending a <function>_p</function>
- to the end of the function. There are also equivalents to memcpy.
- The <function>ins</function> and <function>outs</function>
- functions copy bytes, words or longs to the given port.
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
-!Iarch/x86/include/asm/io.h
-!Elib/pci_iomap.c
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
deleted file mode 100644
index 9765a4c0829d..000000000000
--- a/Documentation/DocBook/drm.tmpl
+++ /dev/null
@@ -1,4231 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="drmDevelopersGuide">
- <bookinfo>
- <title>Linux DRM Developer's Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Jesse</firstname>
- <surname>Barnes</surname>
- <contrib>Initial version</contrib>
- <affiliation>
- <orgname>Intel Corporation</orgname>
- <address>
- <email>jesse.barnes@intel.com</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Laurent</firstname>
- <surname>Pinchart</surname>
- <contrib>Driver internals</contrib>
- <affiliation>
- <orgname>Ideas on board SPRL</orgname>
- <address>
- <email>laurent.pinchart@ideasonboard.com</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Daniel</firstname>
- <surname>Vetter</surname>
- <contrib>Contributions all over the place</contrib>
- <affiliation>
- <orgname>Intel Corporation</orgname>
- <address>
- <email>daniel.vetter@ffwll.ch</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2008-2009</year>
- <year>2013-2014</year>
- <holder>Intel Corporation</holder>
- </copyright>
- <copyright>
- <year>2012</year>
- <holder>Laurent Pinchart</holder>
- </copyright>
-
- <legalnotice>
- <para>
- The contents of this file may be used under the terms of the GNU
- General Public License version 2 (the "GPL") as distributed in
- the kernel source COPYING file.
- </para>
- </legalnotice>
-
- <revhistory>
- <!-- Put document revisions here, newest first. -->
- <revision>
- <revnumber>1.0</revnumber>
- <date>2012-07-13</date>
- <authorinitials>LP</authorinitials>
- <revremark>Added extensive documentation about driver internals.
- </revremark>
- </revision>
- </revhistory>
- </bookinfo>
-
-<toc></toc>
-
-<part id="drmCore">
- <title>DRM Core</title>
- <partintro>
- <para>
- This first part of the DRM Developer's Guide documents core DRM code,
- helper libraries for writing drivers and generic userspace interfaces
- exposed by DRM drivers.
- </para>
- </partintro>
-
- <chapter id="drmIntroduction">
- <title>Introduction</title>
- <para>
- The Linux DRM layer contains code intended to support the needs
- of complex graphics devices, usually containing programmable
- pipelines well suited to 3D graphics acceleration. Graphics
- drivers in the kernel may make use of DRM functions to make
- tasks like memory management, interrupt handling and DMA easier,
- and provide a uniform interface to applications.
- </para>
- <para>
- A note on versions: this guide covers features found in the DRM
- tree, including the TTM memory manager, output configuration and
- mode setting, and the new vblank internals, in addition to all
- the regular features found in current kernels.
- </para>
- <para>
- [Insert diagram of typical DRM stack here]
- </para>
- </chapter>
-
- <!-- Internals -->
-
- <chapter id="drmInternals">
- <title>DRM Internals</title>
- <para>
- This chapter documents DRM internals relevant to driver authors
- and developers working to add support for the latest features to
- existing drivers.
- </para>
- <para>
- First, we go over some typical driver initialization
- requirements, like setting up command buffers, creating an
- initial output configuration, and initializing core services.
- Subsequent sections cover core internals in more detail,
- providing implementation notes and examples.
- </para>
- <para>
- The DRM layer provides several services to graphics drivers,
- many of them driven by the application interfaces it provides
- through libdrm, the library that wraps most of the DRM ioctls.
- These include vblank event handling, memory
- management, output management, framebuffer management, command
- submission &amp; fencing, suspend/resume support, and DMA
- services.
- </para>
-
- <!-- Internals: driver init -->
-
- <sect1>
- <title>Driver Initialization</title>
- <para>
- At the core of every DRM driver is a <structname>drm_driver</structname>
- structure. Drivers typically statically initialize a drm_driver structure,
- and then pass it to one of the <function>drm_*_init()</function> functions
- to register it with the DRM subsystem.
- </para>
- <para>
- Newer drivers that no longer require a <structname>drm_bus</structname>
- structure can alternatively use the low-level device initialization and
- registration functions such as <function>drm_dev_alloc()</function> and
- <function>drm_dev_register()</function> directly.
- </para>
- <para>
- The <structname>drm_driver</structname> structure contains static
- information that describes the driver and features it supports, and
- pointers to methods that the DRM core will call to implement the DRM API.
- We will first go through the <structname>drm_driver</structname> static
- information fields, and will then describe individual operations in
- details as they get used in later sections.
- </para>
- <sect2>
- <title>Driver Information</title>
- <sect3>
- <title>Driver Features</title>
- <para>
- Drivers inform the DRM core about their requirements and supported
- features by setting appropriate flags in the
- <structfield>driver_features</structfield> field. Since those flags
- influence the DRM core behaviour since registration time, most of them
- must be set to registering the <structname>drm_driver</structname>
- instance.
- </para>
- <synopsis>u32 driver_features;</synopsis>
- <variablelist>
- <title>Driver Feature Flags</title>
- <varlistentry>
- <term>DRIVER_USE_AGP</term>
- <listitem><para>
- Driver uses AGP interface, the DRM core will manage AGP resources.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_REQUIRE_AGP</term>
- <listitem><para>
- Driver needs AGP interface to function. AGP initialization failure
- will become a fatal error.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_PCI_DMA</term>
- <listitem><para>
- Driver is capable of PCI DMA, mapping of PCI DMA buffers to
- userspace will be enabled. Deprecated.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_SG</term>
- <listitem><para>
- Driver can perform scatter/gather DMA, allocation and mapping of
- scatter/gather buffers will be enabled. Deprecated.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_HAVE_DMA</term>
- <listitem><para>
- Driver supports DMA, the userspace DMA API will be supported.
- Deprecated.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
- <listitem><para>
- DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler
- managed by the DRM Core. The core will support simple IRQ handler
- installation when the flag is set. The installation process is
- described in <xref linkend="drm-irq-registration"/>.</para>
- <para>DRIVER_IRQ_SHARED indicates whether the device &amp; handler
- support shared IRQs (note that this is required of PCI drivers).
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_GEM</term>
- <listitem><para>
- Driver use the GEM memory manager.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_MODESET</term>
- <listitem><para>
- Driver supports mode setting interfaces (KMS).
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_PRIME</term>
- <listitem><para>
- Driver implements DRM PRIME buffer sharing.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_RENDER</term>
- <listitem><para>
- Driver supports dedicated render nodes.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRIVER_ATOMIC</term>
- <listitem><para>
- Driver supports atomic properties. In this case the driver
- must implement appropriate obj->atomic_get_property() vfuncs
- for any modeset objects with driver specific properties.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- <sect3>
- <title>Major, Minor and Patchlevel</title>
- <synopsis>int major;
-int minor;
-int patchlevel;</synopsis>
- <para>
- The DRM core identifies driver versions by a major, minor and patch
- level triplet. The information is printed to the kernel log at
- initialization time and passed to userspace through the
- DRM_IOCTL_VERSION ioctl.
- </para>
- <para>
- The major and minor numbers are also used to verify the requested driver
- API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes
- between minor versions, applications can call DRM_IOCTL_SET_VERSION to
- select a specific version of the API. If the requested major isn't equal
- to the driver major, or the requested minor is larger than the driver
- minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise
- the driver's set_version() method will be called with the requested
- version.
- </para>
- </sect3>
- <sect3>
- <title>Name, Description and Date</title>
- <synopsis>char *name;
-char *desc;
-char *date;</synopsis>
- <para>
- The driver name is printed to the kernel log at initialization time,
- used for IRQ registration and passed to userspace through
- DRM_IOCTL_VERSION.
- </para>
- <para>
- The driver description is a purely informative string passed to
- userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
- the kernel.
- </para>
- <para>
- The driver date, formatted as YYYYMMDD, is meant to identify the date of
- the latest modification to the driver. However, as most drivers fail to
- update it, its value is mostly useless. The DRM core prints it to the
- kernel log at initialization time and passes it to userspace through the
- DRM_IOCTL_VERSION ioctl.
- </para>
- </sect3>
- </sect2>
- <sect2>
- <title>Device Registration</title>
- <para>
- A number of functions are provided to help with device registration.
- The functions deal with PCI and platform devices, respectively.
- </para>
-!Edrivers/gpu/drm/drm_pci.c
-!Edrivers/gpu/drm/drm_platform.c
- <para>
- New drivers that no longer rely on the services provided by the
- <structname>drm_bus</structname> structure can call the low-level
- device registration functions directly. The
- <function>drm_dev_alloc()</function> function can be used to allocate
- and initialize a new <structname>drm_device</structname> structure.
- Drivers will typically want to perform some additional setup on this
- structure, such as allocating driver-specific data and storing a
- pointer to it in the DRM device's <structfield>dev_private</structfield>
- field. Drivers should also set the device's unique name using the
- <function>drm_dev_set_unique()</function> function. After it has been
- set up a device can be registered with the DRM subsystem by calling
- <function>drm_dev_register()</function>. This will cause the device to
- be exposed to userspace and will call the driver's
- <structfield>.load()</structfield> implementation. When a device is
- removed, the DRM device can safely be unregistered and freed by calling
- <function>drm_dev_unregister()</function> followed by a call to
- <function>drm_dev_unref()</function>.
- </para>
-!Edrivers/gpu/drm/drm_drv.c
- </sect2>
- <sect2>
- <title>Driver Load</title>
- <para>
- The <methodname>load</methodname> method is the driver and device
- initialization entry point. The method is responsible for allocating and
- initializing driver private data, performing resource allocation and
- mapping (e.g. acquiring
- clocks, mapping registers or allocating command buffers), initializing
- the memory manager (<xref linkend="drm-memory-management"/>), installing
- the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up
- vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode
- setting (<xref linkend="drm-mode-setting"/>) and initial output
- configuration (<xref linkend="drm-kms-init"/>).
- </para>
- <note><para>
- If compatibility is a concern (e.g. with drivers converted over from
- User Mode Setting to Kernel Mode Setting), care must be taken to prevent
- device initialization and control that is incompatible with currently
- active userspace drivers. For instance, if user level mode setting
- drivers are in use, it would be problematic to perform output discovery
- &amp; configuration at load time. Likewise, if user-level drivers
- unaware of memory management are in use, memory management and command
- buffer setup may need to be omitted. These requirements are
- driver-specific, and care needs to be taken to keep both old and new
- applications and libraries working.
- </para></note>
- <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis>
- <para>
- The method takes two arguments, a pointer to the newly created
- <structname>drm_device</structname> and flags. The flags are used to
- pass the <structfield>driver_data</structfield> field of the device id
- corresponding to the device passed to <function>drm_*_init()</function>.
- Only PCI devices currently use this, USB and platform DRM drivers have
- their <methodname>load</methodname> method called with flags to 0.
- </para>
- <sect3>
- <title>Driver Private Data</title>
- <para>
- The driver private hangs off the main
- <structname>drm_device</structname> structure and can be used for
- tracking various device-specific bits of information, like register
- offsets, command buffer status, register state for suspend/resume, etc.
- At load time, a driver may simply allocate one and set
- <structname>drm_device</structname>.<structfield>dev_priv</structfield>
- appropriately; it should be freed and
- <structname>drm_device</structname>.<structfield>dev_priv</structfield>
- set to NULL when the driver is unloaded.
- </para>
- </sect3>
- <sect3 id="drm-irq-registration">
- <title>IRQ Registration</title>
- <para>
- The DRM core tries to facilitate IRQ handler registration and
- unregistration by providing <function>drm_irq_install</function> and
- <function>drm_irq_uninstall</function> functions. Those functions only
- support a single interrupt per device, devices that use more than one
- IRQs need to be handled manually.
- </para>
- <sect4>
- <title>Managed IRQ Registration</title>
- <para>
- <function>drm_irq_install</function> starts by calling the
- <methodname>irq_preinstall</methodname> driver operation. The operation
- is optional and must make sure that the interrupt will not get fired by
- clearing all pending interrupt flags or disabling the interrupt.
- </para>
- <para>
- The passed-in IRQ will then be requested by a call to
- <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
- feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
- requested.
- </para>
- <para>
- The IRQ handler function must be provided as the mandatory irq_handler
- driver operation. It will get passed directly to
- <function>request_irq</function> and thus has the same prototype as all
- IRQ handlers. It will get called with a pointer to the DRM device as the
- second argument.
- </para>
- <para>
- Finally the function calls the optional
- <methodname>irq_postinstall</methodname> driver operation. The operation
- usually enables interrupts (excluding the vblank interrupt, which is
- enabled separately), but drivers may choose to enable/disable interrupts
- at a different time.
- </para>
- <para>
- <function>drm_irq_uninstall</function> is similarly used to uninstall an
- IRQ handler. It starts by waking up all processes waiting on a vblank
- interrupt to make sure they don't hang, and then calls the optional
- <methodname>irq_uninstall</methodname> driver operation. The operation
- must disable all hardware interrupts. Finally the function frees the IRQ
- by calling <function>free_irq</function>.
- </para>
- </sect4>
- <sect4>
- <title>Manual IRQ Registration</title>
- <para>
- Drivers that require multiple interrupt handlers can't use the managed
- IRQ registration functions. In that case IRQs must be registered and
- unregistered manually (usually with the <function>request_irq</function>
- and <function>free_irq</function> functions, or their devm_* equivalent).
- </para>
- <para>
- When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ
- driver feature flag, and must not provide the
- <methodname>irq_handler</methodname> driver operation. They must set the
- <structname>drm_device</structname> <structfield>irq_enabled</structfield>
- field to 1 upon registration of the IRQs, and clear it to 0 after
- unregistering the IRQs.
- </para>
- </sect4>
- </sect3>
- <sect3>
- <title>Memory Manager Initialization</title>
- <para>
- Every DRM driver requires a memory manager which must be initialized at
- load time. DRM currently contains two memory managers, the Translation
- Table Manager (TTM) and the Graphics Execution Manager (GEM).
- This document describes the use of the GEM memory manager only. See
- <xref linkend="drm-memory-management"/> for details.
- </para>
- </sect3>
- <sect3>
- <title>Miscellaneous Device Configuration</title>
- <para>
- Another task that may be necessary for PCI devices during configuration
- is mapping the video BIOS. On many devices, the VBIOS describes device
- configuration, LCD panel timings (if any), and contains flags indicating
- device state. Mapping the BIOS can be done using the pci_map_rom() call,
- a convenience function that takes care of mapping the actual ROM,
- whether it has been shadowed into memory (typically at address 0xc0000)
- or exists on the PCI device in the ROM BAR. Note that after the ROM has
- been mapped and any necessary information has been extracted, it should
- be unmapped; on many devices, the ROM address decoder is shared with
- other BARs, so leaving it mapped could cause undesired behaviour like
- hangs or memory corruption.
- <!--!Fdrivers/pci/rom.c pci_map_rom-->
- </para>
- </sect3>
- </sect2>
- </sect1>
-
- <!-- Internals: memory management -->
-
- <sect1 id="drm-memory-management">
- <title>Memory management</title>
- <para>
- Modern Linux systems require large amount of graphics memory to store
- frame buffers, textures, vertices and other graphics-related data. Given
- the very dynamic nature of many of that data, managing graphics memory
- efficiently is thus crucial for the graphics stack and plays a central
- role in the DRM infrastructure.
- </para>
- <para>
- The DRM core includes two memory managers, namely Translation Table Maps
- (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory
- manager to be developed and tried to be a one-size-fits-them all
- solution. It provides a single userspace API to accommodate the need of
- all hardware, supporting both Unified Memory Architecture (UMA) devices
- and devices with dedicated video RAM (i.e. most discrete video cards).
- This resulted in a large, complex piece of code that turned out to be
- hard to use for driver development.
- </para>
- <para>
- GEM started as an Intel-sponsored project in reaction to TTM's
- complexity. Its design philosophy is completely different: instead of
- providing a solution to every graphics memory-related problems, GEM
- identified common code between drivers and created a support library to
- share it. GEM has simpler initialization and execution requirements than
- TTM, but has no video RAM management capabilities and is thus limited to
- UMA devices.
- </para>
- <sect2>
- <title>The Translation Table Manager (TTM)</title>
- <para>
- TTM design background and information belongs here.
- </para>
- <sect3>
- <title>TTM initialization</title>
- <warning><para>This section is outdated.</para></warning>
- <para>
- Drivers wishing to support TTM must fill out a drm_bo_driver
- structure. The structure contains several fields with function
- pointers for initializing the TTM, allocating and freeing memory,
- waiting for command completion and fence synchronization, and memory
- migration. See the radeon_ttm.c file for an example of usage.
- </para>
- <para>
- The ttm_global_reference structure is made up of several fields:
- </para>
- <programlisting>
- struct ttm_global_reference {
- enum ttm_global_types global_type;
- size_t size;
- void *object;
- int (*init) (struct ttm_global_reference *);
- void (*release) (struct ttm_global_reference *);
- };
- </programlisting>
- <para>
- There should be one global reference structure for your memory
- manager as a whole, and there will be others for each object
- created by the memory manager at runtime. Your global TTM should
- have a type of TTM_GLOBAL_TTM_MEM. The size field for the global
- object should be sizeof(struct ttm_mem_global), and the init and
- release hooks should point at your driver-specific init and
- release routines, which probably eventually call
- ttm_mem_global_init and ttm_mem_global_release, respectively.
- </para>
- <para>
- Once your global TTM accounting structure is set up and initialized
- by calling ttm_global_item_ref() on it,
- you need to create a buffer object TTM to
- provide a pool for buffer object allocation by clients and the
- kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO,
- and its size should be sizeof(struct ttm_bo_global). Again,
- driver-specific init and release functions may be provided,
- likely eventually calling ttm_bo_global_init() and
- ttm_bo_global_release(), respectively. Also, like the previous
- object, ttm_global_item_ref() is used to create an initial reference
- count for the TTM, which will call your initialization function.
- </para>
- </sect3>
- </sect2>
- <sect2 id="drm-gem">
- <title>The Graphics Execution Manager (GEM)</title>
- <para>
- The GEM design approach has resulted in a memory manager that doesn't
- provide full coverage of all (or even all common) use cases in its
- userspace or kernel API. GEM exposes a set of standard memory-related
- operations to userspace and a set of helper functions to drivers, and let
- drivers implement hardware-specific operations with their own private API.
- </para>
- <para>
- The GEM userspace API is described in the
- <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics
- Execution Manager</citetitle></ulink> article on LWN. While slightly
- outdated, the document provides a good overview of the GEM API principles.
- Buffer allocation and read and write operations, described as part of the
- common GEM API, are currently implemented using driver-specific ioctls.
- </para>
- <para>
- GEM is data-agnostic. It manages abstract buffer objects without knowing
- what individual buffers contain. APIs that require knowledge of buffer
- contents or purpose, such as buffer allocation or synchronization
- primitives, are thus outside of the scope of GEM and must be implemented
- using driver-specific ioctls.
- </para>
- <para>
- On a fundamental level, GEM involves several operations:
- <itemizedlist>
- <listitem>Memory allocation and freeing</listitem>
- <listitem>Command execution</listitem>
- <listitem>Aperture management at command execution time</listitem>
- </itemizedlist>
- Buffer object allocation is relatively straightforward and largely
- provided by Linux's shmem layer, which provides memory to back each
- object.
- </para>
- <para>
- Device-specific operations, such as command execution, pinning, buffer
- read &amp; write, mapping, and domain ownership transfers are left to
- driver-specific ioctls.
- </para>
- <sect3>
- <title>GEM Initialization</title>
- <para>
- Drivers that use GEM must set the DRIVER_GEM bit in the struct
- <structname>drm_driver</structname>
- <structfield>driver_features</structfield> field. The DRM core will
- then automatically initialize the GEM core before calling the
- <methodname>load</methodname> operation. Behind the scene, this will
- create a DRM Memory Manager object which provides an address space
- pool for object allocation.
- </para>
- <para>
- In a KMS configuration, drivers need to allocate and initialize a
- command ring buffer following core GEM initialization if required by
- the hardware. UMA devices usually have what is called a "stolen"
- memory region, which provides space for the initial framebuffer and
- large, contiguous memory regions required by the device. This space is
- typically not managed by GEM, and must be initialized separately into
- its own DRM MM object.
- </para>
- </sect3>
- <sect3>
- <title>GEM Objects Creation</title>
- <para>
- GEM splits creation of GEM objects and allocation of the memory that
- backs them in two distinct operations.
- </para>
- <para>
- GEM objects are represented by an instance of struct
- <structname>drm_gem_object</structname>. Drivers usually need to extend
- GEM objects with private information and thus create a driver-specific
- GEM object structure type that embeds an instance of struct
- <structname>drm_gem_object</structname>.
- </para>
- <para>
- To create a GEM object, a driver allocates memory for an instance of its
- specific GEM object type and initializes the embedded struct
- <structname>drm_gem_object</structname> with a call to
- <function>drm_gem_object_init</function>. The function takes a pointer to
- the DRM device, a pointer to the GEM object and the buffer object size
- in bytes.
- </para>
- <para>
- GEM uses shmem to allocate anonymous pageable memory.
- <function>drm_gem_object_init</function> will create an shmfs file of
- the requested size and store it into the struct
- <structname>drm_gem_object</structname> <structfield>filp</structfield>
- field. The memory is used as either main storage for the object when the
- graphics hardware uses system memory directly or as a backing store
- otherwise.
- </para>
- <para>
- Drivers are responsible for the actual physical pages allocation by
- calling <function>shmem_read_mapping_page_gfp</function> for each page.
- Note that they can decide to allocate pages when initializing the GEM
- object, or to delay allocation until the memory is needed (for instance
- when a page fault occurs as a result of a userspace memory access or
- when the driver needs to start a DMA transfer involving the memory).
- </para>
- <para>
- Anonymous pageable memory allocation is not always desired, for instance
- when the hardware requires physically contiguous system memory as is
- often the case in embedded devices. Drivers can create GEM objects with
- no shmfs backing (called private GEM objects) by initializing them with
- a call to <function>drm_gem_private_object_init</function> instead of
- <function>drm_gem_object_init</function>. Storage for private GEM
- objects must be managed by drivers.
- </para>
- <para>
- Drivers that do not need to extend GEM objects with private information
- can call the <function>drm_gem_object_alloc</function> function to
- allocate and initialize a struct <structname>drm_gem_object</structname>
- instance. The GEM core will call the optional driver
- <methodname>gem_init_object</methodname> operation after initializing
- the GEM object with <function>drm_gem_object_init</function>.
- <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis>
- </para>
- <para>
- No alloc-and-init function exists for private GEM objects.
- </para>
- </sect3>
- <sect3>
- <title>GEM Objects Lifetime</title>
- <para>
- All GEM objects are reference-counted by the GEM core. References can be
- acquired and release by <function>calling drm_gem_object_reference</function>
- and <function>drm_gem_object_unreference</function> respectively. The
- caller must hold the <structname>drm_device</structname>
- <structfield>struct_mutex</structfield> lock. As a convenience, GEM
- provides the <function>drm_gem_object_reference_unlocked</function> and
- <function>drm_gem_object_unreference_unlocked</function> functions that
- can be called without holding the lock.
- </para>
- <para>
- When the last reference to a GEM object is released the GEM core calls
- the <structname>drm_driver</structname>
- <methodname>gem_free_object</methodname> operation. That operation is
- mandatory for GEM-enabled drivers and must free the GEM object and all
- associated resources.
- </para>
- <para>
- <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis>
- Drivers are responsible for freeing all GEM object resources, including
- the resources created by the GEM core. If an mmap offset has been
- created for the object (in which case
- <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield>
- is not NULL) it must be freed by a call to
- <function>drm_gem_free_mmap_offset</function>. The shmfs backing store
- must be released by calling <function>drm_gem_object_release</function>
- (that function can safely be called if no shmfs backing store has been
- created).
- </para>
- </sect3>
- <sect3>
- <title>GEM Objects Naming</title>
- <para>
- Communication between userspace and the kernel refers to GEM objects
- using local handles, global names or, more recently, file descriptors.
- All of those are 32-bit integer values; the usual Linux kernel limits
- apply to the file descriptors.
- </para>
- <para>
- GEM handles are local to a DRM file. Applications get a handle to a GEM
- object through a driver-specific ioctl, and can use that handle to refer
- to the GEM object in other standard or driver-specific ioctls. Closing a
- DRM file handle frees all its GEM handles and dereferences the
- associated GEM objects.
- </para>
- <para>
- To create a handle for a GEM object drivers call
- <function>drm_gem_handle_create</function>. The function takes a pointer
- to the DRM file and the GEM object and returns a locally unique handle.
- When the handle is no longer needed drivers delete it with a call to
- <function>drm_gem_handle_delete</function>. Finally the GEM object
- associated with a handle can be retrieved by a call to
- <function>drm_gem_object_lookup</function>.
- </para>
- <para>
- Handles don't take ownership of GEM objects, they only take a reference
- to the object that will be dropped when the handle is destroyed. To
- avoid leaking GEM objects, drivers must make sure they drop the
- reference(s) they own (such as the initial reference taken at object
- creation time) as appropriate, without any special consideration for the
- handle. For example, in the particular case of combined GEM object and
- handle creation in the implementation of the
- <methodname>dumb_create</methodname> operation, drivers must drop the
- initial reference to the GEM object before returning the handle.
- </para>
- <para>
- GEM names are similar in purpose to handles but are not local to DRM
- files. They can be passed between processes to reference a GEM object
- globally. Names can't be used directly to refer to objects in the DRM
- API, applications must convert handles to names and names to handles
- using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls
- respectively. The conversion is handled by the DRM core without any
- driver-specific support.
- </para>
- <para>
- GEM also supports buffer sharing with dma-buf file descriptors through
- PRIME. GEM-based drivers must use the provided helpers functions to
- implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />.
- Since sharing file descriptors is inherently more secure than the
- easily guessable and global GEM names it is the preferred buffer
- sharing mechanism. Sharing buffers through GEM names is only supported
- for legacy userspace. Furthermore PRIME also allows cross-device
- buffer sharing since it is based on dma-bufs.
- </para>
- </sect3>
- <sect3 id="drm-gem-objects-mapping">
- <title>GEM Objects Mapping</title>
- <para>
- Because mapping operations are fairly heavyweight GEM favours
- read/write-like access to buffers, implemented through driver-specific
- ioctls, over mapping buffers to userspace. However, when random access
- to the buffer is needed (to perform software rendering for instance),
- direct access to the object can be more efficient.
- </para>
- <para>
- The mmap system call can't be used directly to map GEM objects, as they
- don't have their own file handle. Two alternative methods currently
- co-exist to map GEM objects to userspace. The first method uses a
- driver-specific ioctl to perform the mapping operation, calling
- <function>do_mmap</function> under the hood. This is often considered
- dubious, seems to be discouraged for new GEM-enabled drivers, and will
- thus not be described here.
- </para>
- <para>
- The second method uses the mmap system call on the DRM file handle.
- <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd,
- off_t offset);</synopsis>
- DRM identifies the GEM object to be mapped by a fake offset passed
- through the mmap offset argument. Prior to being mapped, a GEM object
- must thus be associated with a fake offset. To do so, drivers must call
- <function>drm_gem_create_mmap_offset</function> on the object. The
- function allocates a fake offset range from a pool and stores the
- offset divided by PAGE_SIZE in
- <literal>obj-&gt;map_list.hash.key</literal>. Care must be taken not to
- call <function>drm_gem_create_mmap_offset</function> if a fake offset
- has already been allocated for the object. This can be tested by
- <literal>obj-&gt;map_list.map</literal> being non-NULL.
- </para>
- <para>
- Once allocated, the fake offset value
- (<literal>obj-&gt;map_list.hash.key &lt;&lt; PAGE_SHIFT</literal>)
- must be passed to the application in a driver-specific way and can then
- be used as the mmap offset argument.
- </para>
- <para>
- The GEM core provides a helper method <function>drm_gem_mmap</function>
- to handle object mapping. The method can be set directly as the mmap
- file operation handler. It will look up the GEM object based on the
- offset value and set the VMA operations to the
- <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
- field. Note that <function>drm_gem_mmap</function> doesn't map memory to
- userspace, but relies on the driver-provided fault handler to map pages
- individually.
- </para>
- <para>
- To use <function>drm_gem_mmap</function>, drivers must fill the struct
- <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
- field with a pointer to VM operations.
- </para>
- <para>
- <synopsis>struct vm_operations_struct *gem_vm_ops
-
- struct vm_operations_struct {
- void (*open)(struct vm_area_struct * area);
- void (*close)(struct vm_area_struct * area);
- int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf);
- };</synopsis>
- </para>
- <para>
- The <methodname>open</methodname> and <methodname>close</methodname>
- operations must update the GEM object reference count. Drivers can use
- the <function>drm_gem_vm_open</function> and
- <function>drm_gem_vm_close</function> helper functions directly as open
- and close handlers.
- </para>
- <para>
- The fault operation handler is responsible for mapping individual pages
- to userspace when a page fault occurs. Depending on the memory
- allocation scheme, drivers can allocate pages at fault time, or can
- decide to allocate memory for the GEM object at the time the object is
- created.
- </para>
- <para>
- Drivers that want to map the GEM object upfront instead of handling page
- faults can implement their own mmap file operation handler.
- </para>
- </sect3>
- <sect3>
- <title>Memory Coherency</title>
- <para>
- When mapped to the device or used in a command buffer, backing pages
- for an object are flushed to memory and marked write combined so as to
- be coherent with the GPU. Likewise, if the CPU accesses an object
- after the GPU has finished rendering to the object, then the object
- must be made coherent with the CPU's view of memory, usually involving
- GPU cache flushing of various kinds. This core CPU&lt;-&gt;GPU
- coherency management is provided by a device-specific ioctl, which
- evaluates an object's current domain and performs any necessary
- flushing or synchronization to put the object into the desired
- coherency domain (note that the object may be busy, i.e. an active
- render target; in that case, setting the domain blocks the client and
- waits for rendering to complete before performing any necessary
- flushing operations).
- </para>
- </sect3>
- <sect3>
- <title>Command Execution</title>
- <para>
- Perhaps the most important GEM function for GPU devices is providing a
- command execution interface to clients. Client programs construct
- command buffers containing references to previously allocated memory
- objects, and then submit them to GEM. At that point, GEM takes care to
- bind all the objects into the GTT, execute the buffer, and provide
- necessary synchronization between clients accessing the same buffers.
- This often involves evicting some objects from the GTT and re-binding
- others (a fairly expensive operation), and providing relocation
- support which hides fixed GTT offsets from clients. Clients must take
- care not to submit command buffers that reference more objects than
- can fit in the GTT; otherwise, GEM will reject them and no rendering
- will occur. Similarly, if several objects in the buffer require fence
- registers to be allocated for correct rendering (e.g. 2D blits on
- pre-965 chips), care must be taken not to require more fence registers
- than are available to the client. Such resource management should be
- abstracted from the client in libdrm.
- </para>
- </sect3>
- <sect3>
- <title>GEM Function Reference</title>
-!Edrivers/gpu/drm/drm_gem.c
- </sect3>
- </sect2>
- <sect2>
- <title>VMA Offset Manager</title>
-!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager
-!Edrivers/gpu/drm/drm_vma_manager.c
-!Iinclude/drm/drm_vma_manager.h
- </sect2>
- <sect2 id="drm-prime-support">
- <title>PRIME Buffer Sharing</title>
- <para>
- PRIME is the cross device buffer sharing framework in drm, originally
- created for the OPTIMUS range of multi-gpu platforms. To userspace
- PRIME buffers are dma-buf based file descriptors.
- </para>
- <sect3>
- <title>Overview and Driver Interface</title>
- <para>
- Similar to GEM global names, PRIME file descriptors are
- also used to share buffer objects across processes. They offer
- additional security: as file descriptors must be explicitly sent over
- UNIX domain sockets to be shared between applications, they can't be
- guessed like the globally unique GEM names.
- </para>
- <para>
- Drivers that support the PRIME
- API must set the DRIVER_PRIME bit in the struct
- <structname>drm_driver</structname>
- <structfield>driver_features</structfield> field, and implement the
- <methodname>prime_handle_to_fd</methodname> and
- <methodname>prime_fd_to_handle</methodname> operations.
- </para>
- <para>
- <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,
- struct drm_file *file_priv, uint32_t handle,
- uint32_t flags, int *prime_fd);
-int (*prime_fd_to_handle)(struct drm_device *dev,
- struct drm_file *file_priv, int prime_fd,
- uint32_t *handle);</synopsis>
- Those two operations convert a handle to a PRIME file descriptor and
- vice versa. Drivers must use the kernel dma-buf buffer sharing framework
- to manage the PRIME file descriptors. Similar to the mode setting
- API PRIME is agnostic to the underlying buffer object manager, as
- long as handles are 32bit unsigned integers.
- </para>
- <para>
- While non-GEM drivers must implement the operations themselves, GEM
- drivers must use the <function>drm_gem_prime_handle_to_fd</function>
- and <function>drm_gem_prime_fd_to_handle</function> helper functions.
- Those helpers rely on the driver
- <methodname>gem_prime_export</methodname> and
- <methodname>gem_prime_import</methodname> operations to create a dma-buf
- instance from a GEM object (dma-buf exporter role) and to create a GEM
- object from a dma-buf instance (dma-buf importer role).
- </para>
- <para>
- <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
- struct drm_gem_object *obj,
- int flags);
-struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
- struct dma_buf *dma_buf);</synopsis>
- These two operations are mandatory for GEM drivers that support
- PRIME.
- </para>
- </sect3>
- <sect3>
- <title>PRIME Helper Functions</title>
-!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers
- </sect3>
- </sect2>
- <sect2>
- <title>PRIME Function References</title>
-!Edrivers/gpu/drm/drm_prime.c
- </sect2>
- <sect2>
- <title>DRM MM Range Allocator</title>
- <sect3>
- <title>Overview</title>
-!Pdrivers/gpu/drm/drm_mm.c Overview
- </sect3>
- <sect3>
- <title>LRU Scan/Eviction Support</title>
-!Pdrivers/gpu/drm/drm_mm.c lru scan roaster
- </sect3>
- </sect2>
- <sect2>
- <title>DRM MM Range Allocator Function References</title>
-!Edrivers/gpu/drm/drm_mm.c
-!Iinclude/drm/drm_mm.h
- </sect2>
- <sect2>
- <title>CMA Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_gem_cma_helper.c cma helpers
-!Edrivers/gpu/drm/drm_gem_cma_helper.c
-!Iinclude/drm/drm_gem_cma_helper.h
- </sect2>
- </sect1>
-
- <!-- Internals: mode setting -->
-
- <sect1 id="drm-mode-setting">
- <title>Mode Setting</title>
- <para>
- Drivers must initialize the mode setting core by calling
- <function>drm_mode_config_init</function> on the DRM device. The function
- initializes the <structname>drm_device</structname>
- <structfield>mode_config</structfield> field and never fails. Once done,
- mode configuration must be setup by initializing the following fields.
- </para>
- <itemizedlist>
- <listitem>
- <synopsis>int min_width, min_height;
-int max_width, max_height;</synopsis>
- <para>
- Minimum and maximum width and height of the frame buffers in pixel
- units.
- </para>
- </listitem>
- <listitem>
- <synopsis>struct drm_mode_config_funcs *funcs;</synopsis>
- <para>Mode setting functions.</para>
- </listitem>
- </itemizedlist>
- <sect2>
- <title>Display Modes Function Reference</title>
-!Iinclude/drm/drm_modes.h
-!Edrivers/gpu/drm/drm_modes.c
- </sect2>
- <sect2>
- <title>Atomic Mode Setting Function Reference</title>
-!Edrivers/gpu/drm/drm_atomic.c
- </sect2>
- <sect2>
- <title>Frame Buffer Creation</title>
- <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
- struct drm_file *file_priv,
- struct drm_mode_fb_cmd2 *mode_cmd);</synopsis>
- <para>
- Frame buffers are abstract memory objects that provide a source of
- pixels to scanout to a CRTC. Applications explicitly request the
- creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and
- receive an opaque handle that can be passed to the KMS CRTC control,
- plane configuration and page flip functions.
- </para>
- <para>
- Frame buffers rely on the underneath memory manager for low-level memory
- operations. When creating a frame buffer applications pass a memory
- handle (or a list of memory handles for multi-planar formats) through
- the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using
- GEM as their userspace buffer management interface this would be a GEM
- handle. Drivers are however free to use their own backing storage object
- handles, e.g. vmwgfx directly exposes special TTM handles to userspace
- and so expects TTM handles in the create ioctl and not GEM handles.
- </para>
- <para>
- Drivers must first validate the requested frame buffer parameters passed
- through the mode_cmd argument. In particular this is where invalid
- sizes, pixel formats or pitches can be caught.
- </para>
- <para>
- If the parameters are deemed valid, drivers then create, initialize and
- return an instance of struct <structname>drm_framebuffer</structname>.
- If desired the instance can be embedded in a larger driver-specific
- structure. Drivers must fill its <structfield>width</structfield>,
- <structfield>height</structfield>, <structfield>pitches</structfield>,
- <structfield>offsets</structfield>, <structfield>depth</structfield>,
- <structfield>bits_per_pixel</structfield> and
- <structfield>pixel_format</structfield> fields from the values passed
- through the <parameter>drm_mode_fb_cmd2</parameter> argument. They
- should call the <function>drm_helper_mode_fill_fb_struct</function>
- helper function to do so.
- </para>
-
- <para>
- The initialization of the new framebuffer instance is finalized with a
- call to <function>drm_framebuffer_init</function> which takes a pointer
- to DRM frame buffer operations (struct
- <structname>drm_framebuffer_funcs</structname>). Note that this function
- publishes the framebuffer and so from this point on it can be accessed
- concurrently from other threads. Hence it must be the last step in the
- driver's framebuffer initialization sequence. Frame buffer operations
- are
- <itemizedlist>
- <listitem>
- <synopsis>int (*create_handle)(struct drm_framebuffer *fb,
- struct drm_file *file_priv, unsigned int *handle);</synopsis>
- <para>
- Create a handle to the frame buffer underlying memory object. If
- the frame buffer uses a multi-plane format, the handle will
- reference the memory object associated with the first plane.
- </para>
- <para>
- Drivers call <function>drm_gem_handle_create</function> to create
- the handle.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis>
- <para>
- Destroy the frame buffer object and frees all associated
- resources. Drivers must call
- <function>drm_framebuffer_cleanup</function> to free resources
- allocated by the DRM core for the frame buffer object, and must
- make sure to unreference all memory objects associated with the
- frame buffer. Handles created by the
- <methodname>create_handle</methodname> operation are released by
- the DRM core.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer,
- struct drm_file *file_priv, unsigned flags, unsigned color,
- struct drm_clip_rect *clips, unsigned num_clips);</synopsis>
- <para>
- This optional operation notifies the driver that a region of the
- frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB
- ioctl call.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The lifetime of a drm framebuffer is controlled with a reference count,
- drivers can grab additional references with
- <function>drm_framebuffer_reference</function>and drop them
- again with <function>drm_framebuffer_unreference</function>. For
- driver-private framebuffers for which the last reference is never
- dropped (e.g. for the fbdev framebuffer when the struct
- <structname>drm_framebuffer</structname> is embedded into the fbdev
- helper struct) drivers can manually clean up a framebuffer at module
- unload time with
- <function>drm_framebuffer_unregister_private</function>.
- </para>
- </sect2>
- <sect2>
- <title>Dumb Buffer Objects</title>
- <para>
- The KMS API doesn't standardize backing storage object creation and
- leaves it to driver-specific ioctls. Furthermore actually creating a
- buffer object even for GEM-based drivers is done through a
- driver-specific ioctl - GEM only has a common userspace interface for
- sharing and destroying objects. While not an issue for full-fledged
- graphics stacks that include device-specific userspace components (in
- libdrm for instance), this limit makes DRM-based early boot graphics
- unnecessarily complex.
- </para>
- <para>
- Dumb objects partly alleviate the problem by providing a standard
- API to create dumb buffers suitable for scanout, which can then be used
- to create KMS frame buffers.
- </para>
- <para>
- To support dumb objects drivers must implement the
- <methodname>dumb_create</methodname>,
- <methodname>dumb_destroy</methodname> and
- <methodname>dumb_map_offset</methodname> operations.
- </para>
- <itemizedlist>
- <listitem>
- <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev,
- struct drm_mode_create_dumb *args);</synopsis>
- <para>
- The <methodname>dumb_create</methodname> operation creates a driver
- object (GEM or TTM handle) suitable for scanout based on the
- width, height and depth from the struct
- <structname>drm_mode_create_dumb</structname> argument. It fills the
- argument's <structfield>handle</structfield>,
- <structfield>pitch</structfield> and <structfield>size</structfield>
- fields with a handle for the newly created object and its line
- pitch and size in bytes.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev,
- uint32_t handle);</synopsis>
- <para>
- The <methodname>dumb_destroy</methodname> operation destroys a dumb
- object created by <methodname>dumb_create</methodname>.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev,
- uint32_t handle, uint64_t *offset);</synopsis>
- <para>
- The <methodname>dumb_map_offset</methodname> operation associates an
- mmap fake offset with the object given by the handle and returns
- it. Drivers must use the
- <function>drm_gem_create_mmap_offset</function> function to
- associate the fake offset as described in
- <xref linkend="drm-gem-objects-mapping"/>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Note that dumb objects may not be used for gpu acceleration, as has been
- attempted on some ARM embedded platforms. Such drivers really must have
- a hardware-specific ioctl to allocate suitable buffer objects.
- </para>
- </sect2>
- <sect2>
- <title>Output Polling</title>
- <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis>
- <para>
- This operation notifies the driver that the status of one or more
- connectors has changed. Drivers that use the fb helper can just call the
- <function>drm_fb_helper_hotplug_event</function> function to handle this
- operation.
- </para>
- </sect2>
- <sect2>
- <title>Locking</title>
- <para>
- Beside some lookup structures with their own locking (which is hidden
- behind the interface functions) most of the modeset state is protected
- by the <code>dev-&lt;mode_config.lock</code> mutex and additionally
- per-crtc locks to allow cursor updates, pageflips and similar operations
- to occur concurrently with background tasks like output detection.
- Operations which cross domains like a full modeset always grab all
- locks. Drivers there need to protect resources shared between crtcs with
- additional locking. They also need to be careful to always grab the
- relevant crtc locks if a modset functions touches crtc state, e.g. for
- load detection (which does only grab the <code>mode_config.lock</code>
- to allow concurrent screen updates on live crtcs).
- </para>
- </sect2>
- </sect1>
-
- <!-- Internals: kms initialization and cleanup -->
-
- <sect1 id="drm-kms-init">
- <title>KMS Initialization and Cleanup</title>
- <para>
- A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders
- and connectors. KMS drivers must thus create and initialize all those
- objects at load time after initializing mode setting.
- </para>
- <sect2>
- <title>CRTCs (struct <structname>drm_crtc</structname>)</title>
- <para>
- A CRTC is an abstraction representing a part of the chip that contains a
- pointer to a scanout buffer. Therefore, the number of CRTCs available
- determines how many independent scanout buffers can be active at any
- given time. The CRTC structure contains several fields to support this:
- a pointer to some video memory (abstracted as a frame buffer object), a
- display mode, and an (x, y) offset into the video memory to support
- panning or configurations where one piece of video memory spans multiple
- CRTCs.
- </para>
- <sect3>
- <title>CRTC Initialization</title>
- <para>
- A KMS device must create and register at least one struct
- <structname>drm_crtc</structname> instance. The instance is allocated
- and zeroed by the driver, possibly as part of a larger structure, and
- registered with a call to <function>drm_crtc_init</function> with a
- pointer to CRTC functions.
- </para>
- </sect3>
- <sect3 id="drm-kms-crtcops">
- <title>CRTC Operations</title>
- <sect4>
- <title>Set Configuration</title>
- <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis>
- <para>
- Apply a new CRTC configuration to the device. The configuration
- specifies a CRTC, a frame buffer to scan out from, a (x,y) position in
- the frame buffer, a display mode and an array of connectors to drive
- with the CRTC if possible.
- </para>
- <para>
- If the frame buffer specified in the configuration is NULL, the driver
- must detach all encoders connected to the CRTC and all connectors
- attached to those encoders and disable them.
- </para>
- <para>
- This operation is called with the mode config lock held.
- </para>
- <note><para>
- Note that the drm core has no notion of restoring the mode setting
- state after resume, since all resume handling is in the full
- responsibility of the driver. The common mode setting helper library
- though provides a helper which can be used for this:
- <function>drm_helper_resume_force_mode</function>.
- </para></note>
- </sect4>
- <sect4>
- <title>Page Flipping</title>
- <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb,
- struct drm_pending_vblank_event *event);</synopsis>
- <para>
- Schedule a page flip to the given frame buffer for the CRTC. This
- operation is called with the mode config mutex held.
- </para>
- <para>
- Page flipping is a synchronization mechanism that replaces the frame
- buffer being scanned out by the CRTC with a new frame buffer during
- vertical blanking, avoiding tearing. When an application requests a page
- flip the DRM core verifies that the new frame buffer is large enough to
- be scanned out by the CRTC in the currently configured mode and then
- calls the CRTC <methodname>page_flip</methodname> operation with a
- pointer to the new frame buffer.
- </para>
- <para>
- The <methodname>page_flip</methodname> operation schedules a page flip.
- Once any pending rendering targeting the new frame buffer has
- completed, the CRTC will be reprogrammed to display that frame buffer
- after the next vertical refresh. The operation must return immediately
- without waiting for rendering or page flip to complete and must block
- any new rendering to the frame buffer until the page flip completes.
- </para>
- <para>
- If a page flip can be successfully scheduled the driver must set the
- <code>drm_crtc-&gt;fb</code> field to the new framebuffer pointed to
- by <code>fb</code>. This is important so that the reference counting
- on framebuffers stays balanced.
- </para>
- <para>
- If a page flip is already pending, the
- <methodname>page_flip</methodname> operation must return
- -<errorname>EBUSY</errorname>.
- </para>
- <para>
- To synchronize page flip to vertical blanking the driver will likely
- need to enable vertical blanking interrupts. It should call
- <function>drm_vblank_get</function> for that purpose, and call
- <function>drm_vblank_put</function> after the page flip completes.
- </para>
- <para>
- If the application has requested to be notified when page flip completes
- the <methodname>page_flip</methodname> operation will be called with a
- non-NULL <parameter>event</parameter> argument pointing to a
- <structname>drm_pending_vblank_event</structname> instance. Upon page
- flip completion the driver must call <methodname>drm_send_vblank_event</methodname>
- to fill in the event and send to wake up any waiting processes.
- This can be performed with
- <programlisting><![CDATA[
- spin_lock_irqsave(&dev->event_lock, flags);
- ...
- drm_send_vblank_event(dev, pipe, event);
- spin_unlock_irqrestore(&dev->event_lock, flags);
- ]]></programlisting>
- </para>
- <note><para>
- FIXME: Could drivers that don't need to wait for rendering to complete
- just add the event to <literal>dev-&gt;vblank_event_list</literal> and
- let the DRM core handle everything, as for "normal" vertical blanking
- events?
- </para></note>
- <para>
- While waiting for the page flip to complete, the
- <literal>event-&gt;base.link</literal> list head can be used freely by
- the driver to store the pending event in a driver-specific list.
- </para>
- <para>
- If the file handle is closed before the event is signaled, drivers must
- take care to destroy the event in their
- <methodname>preclose</methodname> operation (and, if needed, call
- <function>drm_vblank_put</function>).
- </para>
- </sect4>
- <sect4>
- <title>Miscellaneous</title>
- <itemizedlist>
- <listitem>
- <synopsis>void (*set_property)(struct drm_crtc *crtc,
- struct drm_property *property, uint64_t value);</synopsis>
- <para>
- Set the value of the given CRTC property to
- <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
- for more information about properties.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
- uint32_t start, uint32_t size);</synopsis>
- <para>
- Apply a gamma table to the device. The operation is optional.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis>
- <para>
- Destroy the CRTC when not needed anymore. See
- <xref linkend="drm-kms-init"/>.
- </para>
- </listitem>
- </itemizedlist>
- </sect4>
- </sect3>
- </sect2>
- <sect2>
- <title>Planes (struct <structname>drm_plane</structname>)</title>
- <para>
- A plane represents an image source that can be blended with or overlayed
- on top of a CRTC during the scanout process. Planes are associated with
- a frame buffer to crop a portion of the image memory (source) and
- optionally scale it to a destination size. The result is then blended
- with or overlayed on top of a CRTC.
- </para>
- <para>
- The DRM core recognizes three types of planes:
- <itemizedlist>
- <listitem>
- DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary
- planes are the planes operated upon by CRTC modesetting and flipping
- operations described in <xref linkend="drm-kms-crtcops"/>.
- </listitem>
- <listitem>
- DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor
- planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and
- DRM_IOCTL_MODE_CURSOR2 ioctls.
- </listitem>
- <listitem>
- DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes.
- Some drivers refer to these types of planes as "sprites" internally.
- </listitem>
- </itemizedlist>
- For compatibility with legacy userspace, only overlay planes are made
- available to userspace by default. Userspace clients may set the
- DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that
- they wish to receive a universal plane list containing all plane types.
- </para>
- <sect3>
- <title>Plane Initialization</title>
- <para>
- To create a plane, a KMS drivers allocates and
- zeroes an instances of struct <structname>drm_plane</structname>
- (possibly as part of a larger structure) and registers it with a call
- to <function>drm_universal_plane_init</function>. The function takes a bitmask
- of the CRTCs that can be associated with the plane, a pointer to the
- plane functions, a list of format supported formats, and the type of
- plane (primary, cursor, or overlay) being initialized.
- </para>
- <para>
- Cursor and overlay planes are optional. All drivers should provide
- one primary plane per CRTC (although this requirement may change in
- the future); drivers that do not wish to provide special handling for
- primary planes may make use of the helper functions described in
- <xref linkend="drm-kms-planehelpers"/> to create and register a
- primary plane with standard capabilities.
- </para>
- </sect3>
- <sect3>
- <title>Plane Operations</title>
- <itemizedlist>
- <listitem>
- <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc,
- struct drm_framebuffer *fb, int crtc_x, int crtc_y,
- unsigned int crtc_w, unsigned int crtc_h,
- uint32_t src_x, uint32_t src_y,
- uint32_t src_w, uint32_t src_h);</synopsis>
- <para>
- Enable and configure the plane to use the given CRTC and frame buffer.
- </para>
- <para>
- The source rectangle in frame buffer memory coordinates is given by
- the <parameter>src_x</parameter>, <parameter>src_y</parameter>,
- <parameter>src_w</parameter> and <parameter>src_h</parameter>
- parameters (as 16.16 fixed point values). Devices that don't support
- subpixel plane coordinates can ignore the fractional part.
- </para>
- <para>
- The destination rectangle in CRTC coordinates is given by the
- <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>,
- <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter>
- parameters (as integer values). Devices scale the source rectangle to
- the destination rectangle. If scaling is not supported, and the source
- rectangle size doesn't match the destination rectangle size, the
- driver must return a -<errorname>EINVAL</errorname> error.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis>
- <para>
- Disable the plane. The DRM core calls this method in response to a
- DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0.
- Disabled planes must not be processed by the CRTC.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis>
- <para>
- Destroy the plane when not needed anymore. See
- <xref linkend="drm-kms-init"/>.
- </para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
- <sect2>
- <title>Encoders (struct <structname>drm_encoder</structname>)</title>
- <para>
- An encoder takes pixel data from a CRTC and converts it to a format
- suitable for any attached connectors. On some devices, it may be
- possible to have a CRTC send data to more than one encoder. In that
- case, both encoders would receive data from the same scanout buffer,
- resulting in a "cloned" display configuration across the connectors
- attached to each encoder.
- </para>
- <sect3>
- <title>Encoder Initialization</title>
- <para>
- As for CRTCs, a KMS driver must create, initialize and register at
- least one struct <structname>drm_encoder</structname> instance. The
- instance is allocated and zeroed by the driver, possibly as part of a
- larger structure.
- </para>
- <para>
- Drivers must initialize the struct <structname>drm_encoder</structname>
- <structfield>possible_crtcs</structfield> and
- <structfield>possible_clones</structfield> fields before registering the
- encoder. Both fields are bitmasks of respectively the CRTCs that the
- encoder can be connected to, and sibling encoders candidate for cloning.
- </para>
- <para>
- After being initialized, the encoder must be registered with a call to
- <function>drm_encoder_init</function>. The function takes a pointer to
- the encoder functions and an encoder type. Supported types are
- <itemizedlist>
- <listitem>
- DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A
- </listitem>
- <listitem>
- DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort
- </listitem>
- <listitem>
- DRM_MODE_ENCODER_LVDS for display panels
- </listitem>
- <listitem>
- DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component,
- SCART)
- </listitem>
- <listitem>
- DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Encoders must be attached to a CRTC to be used. DRM drivers leave
- encoders unattached at initialization time. Applications (or the fbdev
- compatibility layer when implemented) are responsible for attaching the
- encoders they want to use to a CRTC.
- </para>
- </sect3>
- <sect3>
- <title>Encoder Operations</title>
- <itemizedlist>
- <listitem>
- <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis>
- <para>
- Called to destroy the encoder when not needed anymore. See
- <xref linkend="drm-kms-init"/>.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*set_property)(struct drm_plane *plane,
- struct drm_property *property, uint64_t value);</synopsis>
- <para>
- Set the value of the given plane property to
- <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
- for more information about properties.
- </para>
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
- <sect2>
- <title>Connectors (struct <structname>drm_connector</structname>)</title>
- <para>
- A connector is the final destination for pixel data on a device, and
- usually connects directly to an external display device like a monitor
- or laptop panel. A connector can only be attached to one encoder at a
- time. The connector is also the structure where information about the
- attached display is kept, so it contains fields for display data, EDID
- data, DPMS &amp; connection status, and information about modes
- supported on the attached displays.
- </para>
- <sect3>
- <title>Connector Initialization</title>
- <para>
- Finally a KMS driver must create, initialize, register and attach at
- least one struct <structname>drm_connector</structname> instance. The
- instance is created as other KMS objects and initialized by setting the
- following fields.
- </para>
- <variablelist>
- <varlistentry>
- <term><structfield>interlace_allowed</structfield></term>
- <listitem><para>
- Whether the connector can handle interlaced modes.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><structfield>doublescan_allowed</structfield></term>
- <listitem><para>
- Whether the connector can handle doublescan.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><structfield>display_info
- </structfield></term>
- <listitem><para>
- Display information is filled from EDID information when a display
- is detected. For non hot-pluggable displays such as flat panels in
- embedded systems, the driver should initialize the
- <structfield>display_info</structfield>.<structfield>width_mm</structfield>
- and
- <structfield>display_info</structfield>.<structfield>height_mm</structfield>
- fields with the physical size of the display.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term id="drm-kms-connector-polled"><structfield>polled</structfield></term>
- <listitem><para>
- Connector polling mode, a combination of
- <variablelist>
- <varlistentry>
- <term>DRM_CONNECTOR_POLL_HPD</term>
- <listitem><para>
- The connector generates hotplug events and doesn't need to be
- periodically polled. The CONNECT and DISCONNECT flags must not
- be set together with the HPD flag.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_CONNECTOR_POLL_CONNECT</term>
- <listitem><para>
- Periodically poll the connector for connection.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_CONNECTOR_POLL_DISCONNECT</term>
- <listitem><para>
- Periodically poll the connector for disconnection.
- </para></listitem>
- </varlistentry>
- </variablelist>
- Set to 0 for connectors that don't support connection status
- discovery.
- </para></listitem>
- </varlistentry>
- </variablelist>
- <para>
- The connector is then registered with a call to
- <function>drm_connector_init</function> with a pointer to the connector
- functions and a connector type, and exposed through sysfs with a call to
- <function>drm_connector_register</function>.
- </para>
- <para>
- Supported connector types are
- <itemizedlist>
- <listitem>DRM_MODE_CONNECTOR_VGA</listitem>
- <listitem>DRM_MODE_CONNECTOR_DVII</listitem>
- <listitem>DRM_MODE_CONNECTOR_DVID</listitem>
- <listitem>DRM_MODE_CONNECTOR_DVIA</listitem>
- <listitem>DRM_MODE_CONNECTOR_Composite</listitem>
- <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem>
- <listitem>DRM_MODE_CONNECTOR_LVDS</listitem>
- <listitem>DRM_MODE_CONNECTOR_Component</listitem>
- <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem>
- <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem>
- <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem>
- <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem>
- <listitem>DRM_MODE_CONNECTOR_TV</listitem>
- <listitem>DRM_MODE_CONNECTOR_eDP</listitem>
- <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem>
- </itemizedlist>
- </para>
- <para>
- Connectors must be attached to an encoder to be used. For devices that
- map connectors to encoders 1:1, the connector should be attached at
- initialization time with a call to
- <function>drm_mode_connector_attach_encoder</function>. The driver must
- also set the <structname>drm_connector</structname>
- <structfield>encoder</structfield> field to point to the attached
- encoder.
- </para>
- <para>
- Finally, drivers must initialize the connectors state change detection
- with a call to <function>drm_kms_helper_poll_init</function>. If at
- least one connector is pollable but can't generate hotplug interrupts
- (indicated by the DRM_CONNECTOR_POLL_CONNECT and
- DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
- automatically be queued to periodically poll for changes. Connectors
- that can generate hotplug interrupts must be marked with the
- DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must
- call <function>drm_helper_hpd_irq_event</function>. The function will
- queue a delayed work to check the state of all connectors, but no
- periodic polling will be done.
- </para>
- </sect3>
- <sect3>
- <title>Connector Operations</title>
- <note><para>
- Unless otherwise state, all operations are mandatory.
- </para></note>
- <sect4>
- <title>DPMS</title>
- <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis>
- <para>
- The DPMS operation sets the power state of a connector. The mode
- argument is one of
- <itemizedlist>
- <listitem><para>DRM_MODE_DPMS_ON</para></listitem>
- <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem>
- <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem>
- <listitem><para>DRM_MODE_DPMS_OFF</para></listitem>
- </itemizedlist>
- </para>
- <para>
- In all but DPMS_ON mode the encoder to which the connector is attached
- should put the display in low-power mode by driving its signals
- appropriately. If more than one connector is attached to the encoder
- care should be taken not to change the power state of other displays as
- a side effect. Low-power mode should be propagated to the encoders and
- CRTCs when all related connectors are put in low-power mode.
- </para>
- </sect4>
- <sect4>
- <title>Modes</title>
- <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width,
- uint32_t max_height);</synopsis>
- <para>
- Fill the mode list with all supported modes for the connector. If the
- <parameter>max_width</parameter> and <parameter>max_height</parameter>
- arguments are non-zero, the implementation must ignore all modes wider
- than <parameter>max_width</parameter> or higher than
- <parameter>max_height</parameter>.
- </para>
- <para>
- The connector must also fill in this operation its
- <structfield>display_info</structfield>
- <structfield>width_mm</structfield> and
- <structfield>height_mm</structfield> fields with the connected display
- physical size in millimeters. The fields should be set to 0 if the value
- isn't known or is not applicable (for instance for projector devices).
- </para>
- </sect4>
- <sect4>
- <title>Connection Status</title>
- <para>
- The connection status is updated through polling or hotplug events when
- supported (see <xref linkend="drm-kms-connector-polled"/>). The status
- value is reported to userspace through ioctls and must not be used
- inside the driver, as it only gets initialized by a call to
- <function>drm_mode_getconnector</function> from userspace.
- </para>
- <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector,
- bool force);</synopsis>
- <para>
- Check to see if anything is attached to the connector. The
- <parameter>force</parameter> parameter is set to false whilst polling or
- to true when checking the connector due to user request.
- <parameter>force</parameter> can be used by the driver to avoid
- expensive, destructive operations during automated probing.
- </para>
- <para>
- Return connector_status_connected if something is connected to the
- connector, connector_status_disconnected if nothing is connected and
- connector_status_unknown if the connection state isn't known.
- </para>
- <para>
- Drivers should only return connector_status_connected if the connection
- status has really been probed as connected. Connectors that can't detect
- the connection status, or failed connection status probes, should return
- connector_status_unknown.
- </para>
- </sect4>
- <sect4>
- <title>Miscellaneous</title>
- <itemizedlist>
- <listitem>
- <synopsis>void (*set_property)(struct drm_connector *connector,
- struct drm_property *property, uint64_t value);</synopsis>
- <para>
- Set the value of the given connector property to
- <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
- for more information about properties.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
- <para>
- Destroy the connector when not needed anymore. See
- <xref linkend="drm-kms-init"/>.
- </para>
- </listitem>
- </itemizedlist>
- </sect4>
- </sect3>
- </sect2>
- <sect2>
- <title>Cleanup</title>
- <para>
- The DRM core manages its objects' lifetime. When an object is not needed
- anymore the core calls its destroy function, which must clean up and
- free every resource allocated for the object. Every
- <function>drm_*_init</function> call must be matched with a
- corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs
- (<function>drm_crtc_cleanup</function>), planes
- (<function>drm_plane_cleanup</function>), encoders
- (<function>drm_encoder_cleanup</function>) and connectors
- (<function>drm_connector_cleanup</function>). Furthermore, connectors
- that have been added to sysfs must be removed by a call to
- <function>drm_connector_unregister</function> before calling
- <function>drm_connector_cleanup</function>.
- </para>
- <para>
- Connectors state change detection must be cleanup up with a call to
- <function>drm_kms_helper_poll_fini</function>.
- </para>
- </sect2>
- <sect2>
- <title>Output discovery and initialization example</title>
- <programlisting><![CDATA[
-void intel_crt_init(struct drm_device *dev)
-{
- struct drm_connector *connector;
- struct intel_output *intel_output;
-
- intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
- if (!intel_output)
- return;
-
- connector = &intel_output->base;
- drm_connector_init(dev, &intel_output->base,
- &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
-
- drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
- DRM_MODE_ENCODER_DAC);
-
- drm_mode_connector_attach_encoder(&intel_output->base,
- &intel_output->enc);
-
- /* Set up the DDC bus. */
- intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
- if (!intel_output->ddc_bus) {
- dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
- "failed.\n");
- return;
- }
-
- intel_output->type = INTEL_OUTPUT_ANALOG;
- connector->interlace_allowed = 0;
- connector->doublescan_allowed = 0;
-
- drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
- drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
-
- drm_connector_register(connector);
-}]]></programlisting>
- <para>
- In the example above (taken from the i915 driver), a CRTC, connector and
- encoder combination is created. A device-specific i2c bus is also
- created for fetching EDID data and performing monitor detection. Once
- the process is complete, the new connector is registered with sysfs to
- make its properties available to applications.
- </para>
- </sect2>
- <sect2>
- <title>KMS API Functions</title>
-!Edrivers/gpu/drm/drm_crtc.c
- </sect2>
- <sect2>
- <title>KMS Data Structures</title>
-!Iinclude/drm/drm_crtc.h
- </sect2>
- <sect2>
- <title>KMS Locking</title>
-!Pdrivers/gpu/drm/drm_modeset_lock.c kms locking
-!Iinclude/drm/drm_modeset_lock.h
-!Edrivers/gpu/drm/drm_modeset_lock.c
- </sect2>
- </sect1>
-
- <!-- Internals: kms helper functions -->
-
- <sect1>
- <title>Mode Setting Helper Functions</title>
- <para>
- The plane, CRTC, encoder and connector functions provided by the drivers
- implement the DRM API. They're called by the DRM core and ioctl handlers
- to handle device state changes and configuration request. As implementing
- those functions often requires logic not specific to drivers, mid-layer
- helper functions are available to avoid duplicating boilerplate code.
- </para>
- <para>
- The DRM core contains one mid-layer implementation. The mid-layer provides
- implementations of several plane, CRTC, encoder and connector functions
- (called from the top of the mid-layer) that pre-process requests and call
- lower-level functions provided by the driver (at the bottom of the
- mid-layer). For instance, the
- <function>drm_crtc_helper_set_config</function> function can be used to
- fill the struct <structname>drm_crtc_funcs</structname>
- <structfield>set_config</structfield> field. When called, it will split
- the <methodname>set_config</methodname> operation in smaller, simpler
- operations and call the driver to handle them.
- </para>
- <para>
- To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>,
- <function>drm_encoder_helper_add</function> and
- <function>drm_connector_helper_add</function> functions to install their
- mid-layer bottom operations handlers, and fill the
- <structname>drm_crtc_funcs</structname>,
- <structname>drm_encoder_funcs</structname> and
- <structname>drm_connector_funcs</structname> structures with pointers to
- the mid-layer top API functions. Installing the mid-layer bottom operation
- handlers is best done right after registering the corresponding KMS object.
- </para>
- <para>
- The mid-layer is not split between CRTC, encoder and connector operations.
- To use it, a driver must provide bottom functions for all of the three KMS
- entities.
- </para>
- <sect2>
- <title>Helper Functions</title>
- <itemizedlist>
- <listitem>
- <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis>
- <para>
- The <function>drm_crtc_helper_set_config</function> helper function
- is a CRTC <methodname>set_config</methodname> implementation. It
- first tries to locate the best encoder for each connector by calling
- the connector <methodname>best_encoder</methodname> helper
- operation.
- </para>
- <para>
- After locating the appropriate encoders, the helper function will
- call the <methodname>mode_fixup</methodname> encoder and CRTC helper
- operations to adjust the requested mode, or reject it completely in
- which case an error will be returned to the application. If the new
- configuration after mode adjustment is identical to the current
- configuration the helper function will return without performing any
- other operation.
- </para>
- <para>
- If the adjusted mode is identical to the current mode but changes to
- the frame buffer need to be applied, the
- <function>drm_crtc_helper_set_config</function> function will call
- the CRTC <methodname>mode_set_base</methodname> helper operation. If
- the adjusted mode differs from the current mode, or if the
- <methodname>mode_set_base</methodname> helper operation is not
- provided, the helper function performs a full mode set sequence by
- calling the <methodname>prepare</methodname>,
- <methodname>mode_set</methodname> and
- <methodname>commit</methodname> CRTC and encoder helper operations,
- in that order.
- </para>
- </listitem>
- <listitem>
- <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis>
- <para>
- The <function>drm_helper_connector_dpms</function> helper function
- is a connector <methodname>dpms</methodname> implementation that
- tracks power state of connectors. To use the function, drivers must
- provide <methodname>dpms</methodname> helper operations for CRTCs
- and encoders to apply the DPMS state to the device.
- </para>
- <para>
- The mid-layer doesn't track the power state of CRTCs and encoders.
- The <methodname>dpms</methodname> helper operations can thus be
- called with a mode identical to the currently active mode.
- </para>
- </listitem>
- <listitem>
- <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector,
- uint32_t maxX, uint32_t maxY);</synopsis>
- <para>
- The <function>drm_helper_probe_single_connector_modes</function> helper
- function is a connector <methodname>fill_modes</methodname>
- implementation that updates the connection status for the connector
- and then retrieves a list of modes by calling the connector
- <methodname>get_modes</methodname> helper operation.
- </para>
- <para>
- If the helper operation returns no mode, and if the connector status
- is connector_status_connected, standard VESA DMT modes up to
- 1024x768 are automatically added to the modes list by a call to
- <function>drm_add_modes_noedid</function>.
- </para>
- <para>
- The function then filters out modes larger than
- <parameter>max_width</parameter> and <parameter>max_height</parameter>
- if specified. It finally calls the optional connector
- <methodname>mode_valid</methodname> helper operation for each mode in
- the probed list to check whether the mode is valid for the connector.
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>CRTC Helper Operations</title>
- <itemizedlist>
- <listitem id="drm-helper-crtc-mode-fixup">
- <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc,
- const struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode);</synopsis>
- <para>
- Let CRTCs adjust the requested mode or reject it completely. This
- operation returns true if the mode is accepted (possibly after being
- adjusted) or false if it is rejected.
- </para>
- <para>
- The <methodname>mode_fixup</methodname> operation should reject the
- mode if it can't reasonably use it. The definition of "reasonable"
- is currently fuzzy in this context. One possible behaviour would be
- to set the adjusted mode to the panel timings when a fixed-mode
- panel is used with hardware capable of scaling. Another behaviour
- would be to accept any input mode and adjust it to the closest mode
- supported by the hardware (FIXME: This needs to be clarified).
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
- struct drm_framebuffer *old_fb)</synopsis>
- <para>
- Move the CRTC on the current frame buffer (stored in
- <literal>crtc-&gt;fb</literal>) to position (x,y). Any of the frame
- buffer, x position or y position may have been modified.
- </para>
- <para>
- This helper operation is optional. If not provided, the
- <function>drm_crtc_helper_set_config</function> function will fall
- back to the <methodname>mode_set</methodname> helper operation.
- </para>
- <note><para>
- FIXME: Why are x and y passed as arguments, as they can be accessed
- through <literal>crtc-&gt;x</literal> and
- <literal>crtc-&gt;y</literal>?
- </para></note>
- </listitem>
- <listitem>
- <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis>
- <para>
- Prepare the CRTC for mode setting. This operation is called after
- validating the requested mode. Drivers use it to perform
- device-specific operations required before setting the new mode.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode, int x, int y,
- struct drm_framebuffer *old_fb);</synopsis>
- <para>
- Set a new mode, position and frame buffer. Depending on the device
- requirements, the mode can be stored internally by the driver and
- applied in the <methodname>commit</methodname> operation, or
- programmed to the hardware immediately.
- </para>
- <para>
- The <methodname>mode_set</methodname> operation returns 0 on success
- or a negative error code if an error occurs.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis>
- <para>
- Commit a mode. This operation is called after setting the new mode.
- Upon return the device must use the new mode and be fully
- operational.
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>Encoder Helper Operations</title>
- <itemizedlist>
- <listitem>
- <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder,
- const struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode);</synopsis>
- <para>
- Let encoders adjust the requested mode or reject it completely. This
- operation returns true if the mode is accepted (possibly after being
- adjusted) or false if it is rejected. See the
- <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper
- operation</link> for an explanation of the allowed adjustments.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis>
- <para>
- Prepare the encoder for mode setting. This operation is called after
- validating the requested mode. Drivers use it to perform
- device-specific operations required before setting the new mode.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*mode_set)(struct drm_encoder *encoder,
- struct drm_display_mode *mode,
- struct drm_display_mode *adjusted_mode);</synopsis>
- <para>
- Set a new mode. Depending on the device requirements, the mode can
- be stored internally by the driver and applied in the
- <methodname>commit</methodname> operation, or programmed to the
- hardware immediately.
- </para>
- </listitem>
- <listitem>
- <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis>
- <para>
- Commit a mode. This operation is called after setting the new mode.
- Upon return the device must use the new mode and be fully
- operational.
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>Connector Helper Operations</title>
- <itemizedlist>
- <listitem>
- <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis>
- <para>
- Return a pointer to the best encoder for the connecter. Device that
- map connectors to encoders 1:1 simply return the pointer to the
- associated encoder. This operation is mandatory.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis>
- <para>
- Fill the connector's <structfield>probed_modes</structfield> list
- by parsing EDID data with <function>drm_add_edid_modes</function>,
- adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>,
- or calling <function>drm_mode_probed_add</function> directly for every
- supported mode and return the number of modes it has detected. This
- operation is mandatory.
- </para>
- <para>
- Note that the caller function will automatically add standard VESA
- DMT modes up to 1024x768 if the <methodname>get_modes</methodname>
- helper operation returns no mode and if the connector status is
- connector_status_connected. There is no need to call
- <function>drm_add_edid_modes</function> manually in that case.
- </para>
- <para>
- When adding modes manually the driver creates each mode with a call to
- <function>drm_mode_create</function> and must fill the following fields.
- <itemizedlist>
- <listitem>
- <synopsis>__u32 type;</synopsis>
- <para>
- Mode type bitmask, a combination of
- <variablelist>
- <varlistentry>
- <term>DRM_MODE_TYPE_BUILTIN</term>
- <listitem><para>not used?</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_TYPE_CLOCK_C</term>
- <listitem><para>not used?</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_TYPE_CRTC_C</term>
- <listitem><para>not used?</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>
- DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector
- </term>
- <listitem>
- <para>not used?</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_TYPE_DEFAULT</term>
- <listitem><para>not used?</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_TYPE_USERDEF</term>
- <listitem><para>not used?</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_TYPE_DRIVER</term>
- <listitem>
- <para>
- The mode has been created by the driver (as opposed to
- to user-created modes).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they
- create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred
- mode.
- </para>
- </listitem>
- <listitem>
- <synopsis>__u32 clock;</synopsis>
- <para>Pixel clock frequency in kHz unit</para>
- </listitem>
- <listitem>
- <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal;
- __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis>
- <para>Horizontal and vertical timing information</para>
- <screen><![CDATA[
- Active Front Sync Back
- Region Porch Porch
- <-----------------------><----------------><-------------><-------------->
-
- //////////////////////|
- ////////////////////// |
- ////////////////////// |.................. ................
- _______________
-
- <----- [hv]display ----->
- <------------- [hv]sync_start ------------>
- <--------------------- [hv]sync_end --------------------->
- <-------------------------------- [hv]total ----------------------------->
-]]></screen>
- </listitem>
- <listitem>
- <synopsis>__u16 hskew;
- __u16 vscan;</synopsis>
- <para>Unknown</para>
- </listitem>
- <listitem>
- <synopsis>__u32 flags;</synopsis>
- <para>
- Mode flags, a combination of
- <variablelist>
- <varlistentry>
- <term>DRM_MODE_FLAG_PHSYNC</term>
- <listitem><para>
- Horizontal sync is active high
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_NHSYNC</term>
- <listitem><para>
- Horizontal sync is active low
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_PVSYNC</term>
- <listitem><para>
- Vertical sync is active high
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_NVSYNC</term>
- <listitem><para>
- Vertical sync is active low
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_INTERLACE</term>
- <listitem><para>
- Mode is interlaced
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_DBLSCAN</term>
- <listitem><para>
- Mode uses doublescan
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_CSYNC</term>
- <listitem><para>
- Mode uses composite sync
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_PCSYNC</term>
- <listitem><para>
- Composite sync is active high
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_NCSYNC</term>
- <listitem><para>
- Composite sync is active low
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_HSKEW</term>
- <listitem><para>
- hskew provided (not used?)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_BCAST</term>
- <listitem><para>
- not used?
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_PIXMUX</term>
- <listitem><para>
- not used?
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_DBLCLK</term>
- <listitem><para>
- not used?
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_FLAG_CLKDIV2</term>
- <listitem><para>
- ?
- </para></listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- Note that modes marked with the INTERLACE or DBLSCAN flags will be
- filtered out by
- <function>drm_helper_probe_single_connector_modes</function> if
- the connector's <structfield>interlace_allowed</structfield> or
- <structfield>doublescan_allowed</structfield> field is set to 0.
- </para>
- </listitem>
- <listitem>
- <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis>
- <para>
- Mode name. The driver must call
- <function>drm_mode_set_name</function> to fill the mode name from
- <structfield>hdisplay</structfield>,
- <structfield>vdisplay</structfield> and interlace flag after
- filling the corresponding fields.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The <structfield>vrefresh</structfield> value is computed by
- <function>drm_helper_probe_single_connector_modes</function>.
- </para>
- <para>
- When parsing EDID data, <function>drm_add_edid_modes</function> fills the
- connector <structfield>display_info</structfield>
- <structfield>width_mm</structfield> and
- <structfield>height_mm</structfield> fields. When creating modes
- manually the <methodname>get_modes</methodname> helper operation must
- set the <structfield>display_info</structfield>
- <structfield>width_mm</structfield> and
- <structfield>height_mm</structfield> fields if they haven't been set
- already (for instance at initialization time when a fixed-size panel is
- attached to the connector). The mode <structfield>width_mm</structfield>
- and <structfield>height_mm</structfield> fields are only used internally
- during EDID parsing and should not be set when creating modes manually.
- </para>
- </listitem>
- <listitem>
- <synopsis>int (*mode_valid)(struct drm_connector *connector,
- struct drm_display_mode *mode);</synopsis>
- <para>
- Verify whether a mode is valid for the connector. Return MODE_OK for
- supported modes and one of the enum drm_mode_status values (MODE_*)
- for unsupported modes. This operation is optional.
- </para>
- <para>
- As the mode rejection reason is currently not used beside for
- immediately removing the unsupported mode, an implementation can
- return MODE_BAD regardless of the exact reason why the mode is not
- valid.
- </para>
- <note><para>
- Note that the <methodname>mode_valid</methodname> helper operation is
- only called for modes detected by the device, and
- <emphasis>not</emphasis> for modes set by the user through the CRTC
- <methodname>set_config</methodname> operation.
- </para></note>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>Atomic Modeset Helper Functions Reference</title>
- <sect3>
- <title>Overview</title>
-!Pdrivers/gpu/drm/drm_atomic_helper.c overview
- </sect3>
- <sect3>
- <title>Implementing Asynchronous Atomic Commit</title>
-!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit
- </sect3>
- <sect3>
- <title>Atomic State Reset and Initialization</title>
-!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization
- </sect3>
-!Iinclude/drm/drm_atomic_helper.h
-!Edrivers/gpu/drm/drm_atomic_helper.c
- </sect2>
- <sect2>
- <title>Modeset Helper Functions Reference</title>
-!Iinclude/drm/drm_crtc_helper.h
-!Edrivers/gpu/drm/drm_crtc_helper.c
-!Pdrivers/gpu/drm/drm_crtc_helper.c overview
- </sect2>
- <sect2>
- <title>Output Probing Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_probe_helper.c output probing helper overview
-!Edrivers/gpu/drm/drm_probe_helper.c
- </sect2>
- <sect2>
- <title>fbdev Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers
-!Edrivers/gpu/drm/drm_fb_helper.c
-!Iinclude/drm/drm_fb_helper.h
- </sect2>
- <sect2>
- <title>Display Port Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_dp_helper.c dp helpers
-!Iinclude/drm/drm_dp_helper.h
-!Edrivers/gpu/drm/drm_dp_helper.c
- </sect2>
- <sect2>
- <title>Display Port MST Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_dp_mst_topology.c dp mst helper
-!Iinclude/drm/drm_dp_mst_helper.h
-!Edrivers/gpu/drm/drm_dp_mst_topology.c
- </sect2>
- <sect2>
- <title>MIPI DSI Helper Functions Reference</title>
-!Pdrivers/gpu/drm/drm_mipi_dsi.c dsi helpers
-!Iinclude/drm/drm_mipi_dsi.h
-!Edrivers/gpu/drm/drm_mipi_dsi.c
- </sect2>
- <sect2>
- <title>EDID Helper Functions Reference</title>
-!Edrivers/gpu/drm/drm_edid.c
- </sect2>
- <sect2>
- <title>Rectangle Utilities Reference</title>
-!Pinclude/drm/drm_rect.h rect utils
-!Iinclude/drm/drm_rect.h
-!Edrivers/gpu/drm/drm_rect.c
- </sect2>
- <sect2>
- <title>Flip-work Helper Reference</title>
-!Pinclude/drm/drm_flip_work.h flip utils
-!Iinclude/drm/drm_flip_work.h
-!Edrivers/gpu/drm/drm_flip_work.c
- </sect2>
- <sect2>
- <title>HDMI Infoframes Helper Reference</title>
- <para>
- Strictly speaking this is not a DRM helper library but generally useable
- by any driver interfacing with HDMI outputs like v4l or alsa drivers.
- But it nicely fits into the overall topic of mode setting helper
- libraries and hence is also included here.
- </para>
-!Iinclude/linux/hdmi.h
-!Edrivers/video/hdmi.c
- </sect2>
- <sect2>
- <title id="drm-kms-planehelpers">Plane Helper Reference</title>
-!Edrivers/gpu/drm/drm_plane_helper.c
-!Pdrivers/gpu/drm/drm_plane_helper.c overview
- </sect2>
- <sect2>
- <title>Tile group</title>
-!Pdrivers/gpu/drm/drm_crtc.c Tile group
- </sect2>
- </sect1>
-
- <!-- Internals: kms properties -->
-
- <sect1 id="drm-kms-properties">
- <title>KMS Properties</title>
- <para>
- Drivers may need to expose additional parameters to applications than
- those described in the previous sections. KMS supports attaching
- properties to CRTCs, connectors and planes and offers a userspace API to
- list, get and set the property values.
- </para>
- <para>
- Properties are identified by a name that uniquely defines the property
- purpose, and store an associated value. For all property types except blob
- properties the value is a 64-bit unsigned integer.
- </para>
- <para>
- KMS differentiates between properties and property instances. Drivers
- first create properties and then create and associate individual instances
- of those properties to objects. A property can be instantiated multiple
- times and associated with different objects. Values are stored in property
- instances, and all other property information are stored in the property
- and shared between all instances of the property.
- </para>
- <para>
- Every property is created with a type that influences how the KMS core
- handles the property. Supported property types are
- <variablelist>
- <varlistentry>
- <term>DRM_MODE_PROP_RANGE</term>
- <listitem><para>Range properties report their minimum and maximum
- admissible values. The KMS core verifies that values set by
- application fit in that range.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_PROP_ENUM</term>
- <listitem><para>Enumerated properties take a numerical value that
- ranges from 0 to the number of enumerated values defined by the
- property minus one, and associate a free-formed string name to each
- value. Applications can retrieve the list of defined value-name pairs
- and use the numerical value to get and set property instance values.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_PROP_BITMASK</term>
- <listitem><para>Bitmask properties are enumeration properties that
- additionally restrict all enumerated values to the 0..63 range.
- Bitmask property instance values combine one or more of the
- enumerated bits defined by the property.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_MODE_PROP_BLOB</term>
- <listitem><para>Blob properties store a binary blob without any format
- restriction. The binary blobs are created as KMS standalone objects,
- and blob property instance values store the ID of their associated
- blob object.</para>
- <para>Blob properties are only used for the connector EDID property
- and cannot be created by drivers.</para></listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- To create a property drivers call one of the following functions depending
- on the property type. All property creation functions take property flags
- and name, as well as type-specific arguments.
- <itemizedlist>
- <listitem>
- <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
- const char *name,
- uint64_t min, uint64_t max);</synopsis>
- <para>Create a range property with the given minimum and maximum
- values.</para>
- </listitem>
- <listitem>
- <synopsis>struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
- const char *name,
- const struct drm_prop_enum_list *props,
- int num_values);</synopsis>
- <para>Create an enumerated property. The <parameter>props</parameter>
- argument points to an array of <parameter>num_values</parameter>
- value-name pairs.</para>
- </listitem>
- <listitem>
- <synopsis>struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
- int flags, const char *name,
- const struct drm_prop_enum_list *props,
- int num_values);</synopsis>
- <para>Create a bitmask property. The <parameter>props</parameter>
- argument points to an array of <parameter>num_values</parameter>
- value-name pairs.</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Properties can additionally be created as immutable, in which case they
- will be read-only for applications but can be modified by the driver. To
- create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE
- flag at property creation time.
- </para>
- <para>
- When no array of value-name pairs is readily available at property
- creation time for enumerated or range properties, drivers can create
- the property using the <function>drm_property_create</function> function
- and manually add enumeration value-name pairs by calling the
- <function>drm_property_add_enum</function> function. Care must be taken to
- properly specify the property type through the <parameter>flags</parameter>
- argument.
- </para>
- <para>
- After creating properties drivers can attach property instances to CRTC,
- connector and plane objects by calling the
- <function>drm_object_attach_property</function>. The function takes a
- pointer to the target object, a pointer to the previously created property
- and an initial instance value.
- </para>
- <sect2>
- <title>Existing KMS Properties</title>
- <para>
- The following table gives description of drm properties exposed by various
- modules/drivers.
- </para>
- <table border="1" cellpadding="0" cellspacing="0">
- <tbody>
- <tr style="font-weight: bold;">
- <td valign="top" >Owner Module/Drivers</td>
- <td valign="top" >Group</td>
- <td valign="top" >Property Name</td>
- <td valign="top" >Type</td>
- <td valign="top" >Property Values</td>
- <td valign="top" >Object attached</td>
- <td valign="top" >Description/Restrictions</td>
- </tr>
- <tr>
- <td rowspan="36" valign="top" >DRM</td>
- <td rowspan="5" valign="top" >Connector</td>
- <td valign="top" >“EDID”</td>
- <td valign="top" >BLOB | IMMUTABLE</td>
- <td valign="top" >0</td>
- <td valign="top" >Connector</td>
- <td valign="top" >Contains id of edid blob ptr object.</td>
- </tr>
- <tr>
- <td valign="top" >“DPMS”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >Contains DPMS operation mode value.</td>
- </tr>
- <tr>
- <td valign="top" >“PATH”</td>
- <td valign="top" >BLOB | IMMUTABLE</td>
- <td valign="top" >0</td>
- <td valign="top" >Connector</td>
- <td valign="top" >Contains topology path to a connector.</td>
- </tr>
- <tr>
- <td valign="top" >“TILE”</td>
- <td valign="top" >BLOB | IMMUTABLE</td>
- <td valign="top" >0</td>
- <td valign="top" >Connector</td>
- <td valign="top" >Contains tiling information for a connector.</td>
- </tr>
- <tr>
- <td valign="top" >“CRTC_ID”</td>
- <td valign="top" >OBJECT</td>
- <td valign="top" >DRM_MODE_OBJECT_CRTC</td>
- <td valign="top" >Connector</td>
- <td valign="top" >CRTC that connector is attached to (atomic)</td>
- </tr>
- <tr>
- <td rowspan="11" valign="top" >Plane</td>
- <td valign="top" >“type”</td>
- <td valign="top" >ENUM | IMMUTABLE</td>
- <td valign="top" >{ "Overlay", "Primary", "Cursor" }</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Plane type</td>
- </tr>
- <tr>
- <td valign="top" >“SRC_X”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=UINT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“SRC_Y”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=UINT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“SRC_W”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=UINT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“SRC_H”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=UINT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“CRTC_X”</td>
- <td valign="top" >SIGNED_RANGE</td>
- <td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“CRTC_Y”</td>
- <td valign="top" >SIGNED_RANGE</td>
- <td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“CRTC_W”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=UINT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout CRTC (destination) width (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“CRTC_H”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=UINT_MAX</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout CRTC (destination) height (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“FB_ID”</td>
- <td valign="top" >OBJECT</td>
- <td valign="top" >DRM_MODE_OBJECT_FB</td>
- <td valign="top" >Plane</td>
- <td valign="top" >Scanout framebuffer (atomic)</td>
- </tr>
- <tr>
- <td valign="top" >“CRTC_ID”</td>
- <td valign="top" >OBJECT</td>
- <td valign="top" >DRM_MODE_OBJECT_CRTC</td>
- <td valign="top" >Plane</td>
- <td valign="top" >CRTC that plane is attached to (atomic)</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >DVI-I</td>
- <td valign="top" >“subconnector”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“select subconnector”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="13" valign="top" >TV</td>
- <td valign="top" >“subconnector”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“select subconnector”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“left margin”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“right margin”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“top margin”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“bottom margin”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“brightness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“contrast”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker reduction”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“overscan”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“saturation”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“hue”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >Virtual GPU</td>
- <td valign="top" >“suggested X”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffffff</td>
- <td valign="top" >Connector</td>
- <td valign="top" >property to suggest an X offset for a connector</td>
- </tr>
- <tr>
- <td valign="top" >“suggested Y”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffffff</td>
- <td valign="top" >Connector</td>
- <td valign="top" >property to suggest an Y offset for a connector</td>
- </tr>
- <tr>
- <td rowspan="3" valign="top" >Optional</td>
- <td valign="top" >“scaling mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"aspect ratio"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "None", "4:3", "16:9" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >DRM property to set aspect ratio from user space app.
- This enum is made generic to allow addition of custom aspect
- ratios.</td>
- </tr>
- <tr>
- <td valign="top" >“dirty”</td>
- <td valign="top" >ENUM | IMMUTABLE</td>
- <td valign="top" >{ "Off", "On", "Annotate" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="21" valign="top" >i915</td>
- <td rowspan="2" valign="top" >Generic</td>
- <td valign="top" >"Broadcast RGB"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“audio”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "force-dvi", "off", "auto", "on" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="1" valign="top" >Plane</td>
- <td valign="top" >“rotation”</td>
- <td valign="top" >BITMASK</td>
- <td valign="top" >{ 0, "rotate-0" }, { 2, "rotate-180" }</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="17" valign="top" >SDVO-TV</td>
- <td valign="top" >“mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"left_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"right_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"top_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"bottom_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“hpos”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“vpos”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“contrast”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“saturation”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“hue”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“sharpness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker_filter”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker_filter_adaptive”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker_filter_2d”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“tv_chroma_filter”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“tv_luma_filter”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“dot_crawl”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >SDVO-TV/LVDS</td>
- <td valign="top" >“brightness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >CDV gma-500</td>
- <td rowspan="2" valign="top" >Generic</td>
- <td valign="top" >"Broadcast RGB"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ “Full”, “Limited 16:235” }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"Broadcast RGB"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ “off”, “auto”, “on” }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="19" valign="top" >Poulsbo</td>
- <td rowspan="1" valign="top" >Generic</td>
- <td valign="top" >“backlight”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=100</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="17" valign="top" >SDVO-TV</td>
- <td valign="top" >“mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"left_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"right_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"top_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"bottom_margin"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“hpos”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“vpos”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“contrast”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“saturation”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“hue”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“sharpness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker_filter”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker_filter_adaptive”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“flicker_filter_2d”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“tv_chroma_filter”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“tv_luma_filter”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“dot_crawl”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >SDVO-TV/LVDS</td>
- <td valign="top" >“brightness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max= SDVO dependent</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="11" valign="top" >armada</td>
- <td rowspan="2" valign="top" >CRTC</td>
- <td valign="top" >"CSC_YUV"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td>
- <td valign="top" >CRTC</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"CSC_RGB"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "Auto", "Computer system", "Studio" }</td>
- <td valign="top" >CRTC</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="9" valign="top" >Overlay</td>
- <td valign="top" >"colorkey"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"colorkey_min"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"colorkey_max"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"colorkey_val"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"colorkey_alpha"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0xffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"colorkey_mode"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "disabled", "Y component", "U component"
- , "V component", "RGB", “R component", "G component", "B component" }</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"brightness"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=256 + 255</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"contrast"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0x7fff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"saturation"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0x7fff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >exynos</td>
- <td valign="top" >CRTC</td>
- <td valign="top" >“mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "normal", "blank" }</td>
- <td valign="top" >CRTC</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >Overlay</td>
- <td valign="top" >“zpos”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=MAX_PLANE-1</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >i2c/ch7006_drv</td>
- <td valign="top" >Generic</td>
- <td valign="top" >“scale”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=2</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="1" valign="top" >TV</td>
- <td valign="top" >“mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc"
- , "PAL-60", "NTSC-M", "NTSC-J" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="15" valign="top" >nouveau</td>
- <td rowspan="6" valign="top" >NV10 Overlay</td>
- <td valign="top" >"colorkey"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0x01ffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“contrast”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=8192-1</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“brightness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1024</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“hue”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=359</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“saturation”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=8192-1</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“iturbt_709”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >Nv04 Overlay</td>
- <td valign="top" >“colorkey”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0x01ffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“brightness”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1024</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="7" valign="top" >Display</td>
- <td valign="top" >“dithering mode”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "auto", "off", "on" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“dithering depth”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“underscan”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“underscan hborder”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=128</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“underscan vborder”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=128</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“vibrant hue”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=180</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“color vibrance”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=200</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="2" valign="top" >omap</td>
- <td rowspan="2" valign="top" >Generic</td>
- <td valign="top" >“rotation”</td>
- <td valign="top" >BITMASK</td>
- <td valign="top" >{ 0, "rotate-0" },
- { 1, "rotate-90" },
- { 2, "rotate-180" },
- { 3, "rotate-270" },
- { 4, "reflect-x" },
- { 5, "reflect-y" }</td>
- <td valign="top" >CRTC, Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >“zorder”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=3</td>
- <td valign="top" >CRTC, Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >qxl</td>
- <td valign="top" >Generic</td>
- <td valign="top" >“hotplug_mode_update"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="9" valign="top" >radeon</td>
- <td valign="top" >DVI-I</td>
- <td valign="top" >“coherent”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >DAC enable load detect</td>
- <td valign="top" >“load detection”</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=1</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >TV Standard</td>
- <td valign="top" >"tv standard"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j"
- , "scart-pal", "pal-cn", "secam" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >legacy TMDS PLL detect</td>
- <td valign="top" >"tmds_pll"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "driver", "bios" }</td>
- <td valign="top" >-</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="3" valign="top" >Underscan</td>
- <td valign="top" >"underscan"</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "off", "on", "auto" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"underscan hborder"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=128</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"underscan vborder"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=128</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >Audio</td>
- <td valign="top" >“audio”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "off", "on", "auto" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >FMT Dithering</td>
- <td valign="top" >“dither”</td>
- <td valign="top" >ENUM</td>
- <td valign="top" >{ "off", "on" }</td>
- <td valign="top" >Connector</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td rowspan="3" valign="top" >rcar-du</td>
- <td rowspan="3" valign="top" >Generic</td>
- <td valign="top" >"alpha"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=255</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"colorkey"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=0, Max=0x01ffffff</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- <tr>
- <td valign="top" >"zpos"</td>
- <td valign="top" >RANGE</td>
- <td valign="top" >Min=1, Max=7</td>
- <td valign="top" >Plane</td>
- <td valign="top" >TBD</td>
- </tr>
- </tbody>
- </table>
- </sect2>
- </sect1>
-
- <!-- Internals: vertical blanking -->
-
- <sect1 id="drm-vertical-blank">
- <title>Vertical Blanking</title>
- <para>
- Vertical blanking plays a major role in graphics rendering. To achieve
- tear-free display, users must synchronize page flips and/or rendering to
- vertical blanking. The DRM API offers ioctls to perform page flips
- synchronized to vertical blanking and wait for vertical blanking.
- </para>
- <para>
- The DRM core handles most of the vertical blanking management logic, which
- involves filtering out spurious interrupts, keeping race-free blanking
- counters, coping with counter wrap-around and resets and keeping use
- counts. It relies on the driver to generate vertical blanking interrupts
- and optionally provide a hardware vertical blanking counter. Drivers must
- implement the following operations.
- </para>
- <itemizedlist>
- <listitem>
- <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc);
-void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis>
- <para>
- Enable or disable vertical blanking interrupts for the given CRTC.
- </para>
- </listitem>
- <listitem>
- <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis>
- <para>
- Retrieve the value of the vertical blanking counter for the given
- CRTC. If the hardware maintains a vertical blanking counter its value
- should be returned. Otherwise drivers can use the
- <function>drm_vblank_count</function> helper function to handle this
- operation.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Drivers must initialize the vertical blanking handling core with a call to
- <function>drm_vblank_init</function> in their
- <methodname>load</methodname> operation. The function will set the struct
- <structname>drm_device</structname>
- <structfield>vblank_disable_allowed</structfield> field to 0. This will
- keep vertical blanking interrupts enabled permanently until the first mode
- set operation, where <structfield>vblank_disable_allowed</structfield> is
- set to 1. The reason behind this is not clear. Drivers can set the field
- to 1 after <function>calling drm_vblank_init</function> to make vertical
- blanking interrupts dynamically managed from the beginning.
- </para>
- <para>
- Vertical blanking interrupts can be enabled by the DRM core or by drivers
- themselves (for instance to handle page flipping operations). The DRM core
- maintains a vertical blanking use count to ensure that the interrupts are
- not disabled while a user still needs them. To increment the use count,
- drivers call <function>drm_vblank_get</function>. Upon return vertical
- blanking interrupts are guaranteed to be enabled.
- </para>
- <para>
- To decrement the use count drivers call
- <function>drm_vblank_put</function>. Only when the use count drops to zero
- will the DRM core disable the vertical blanking interrupts after a delay
- by scheduling a timer. The delay is accessible through the vblankoffdelay
- module parameter or the <varname>drm_vblank_offdelay</varname> global
- variable and expressed in milliseconds. Its default value is 5000 ms.
- Zero means never disable, and a negative value means disable immediately.
- Drivers may override the behaviour by setting the
- <structname>drm_device</structname>
- <structfield>vblank_disable_immediate</structfield> flag, which when set
- causes vblank interrupts to be disabled immediately regardless of the
- drm_vblank_offdelay value. The flag should only be set if there's a
- properly working hardware vblank counter present.
- </para>
- <para>
- When a vertical blanking interrupt occurs drivers only need to call the
- <function>drm_handle_vblank</function> function to account for the
- interrupt.
- </para>
- <para>
- Resources allocated by <function>drm_vblank_init</function> must be freed
- with a call to <function>drm_vblank_cleanup</function> in the driver
- <methodname>unload</methodname> operation handler.
- </para>
- <sect2>
- <title>Vertical Blanking and Interrupt Handling Functions Reference</title>
-!Edrivers/gpu/drm/drm_irq.c
-!Finclude/drm/drmP.h drm_crtc_vblank_waitqueue
- </sect2>
- </sect1>
-
- <!-- Internals: open/close, file operations and ioctls -->
-
- <sect1>
- <title>Open/Close, File Operations and IOCTLs</title>
- <sect2>
- <title>Open and Close</title>
- <synopsis>int (*firstopen) (struct drm_device *);
-void (*lastclose) (struct drm_device *);
-int (*open) (struct drm_device *, struct drm_file *);
-void (*preclose) (struct drm_device *, struct drm_file *);
-void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
- <abstract>Open and close handlers. None of those methods are mandatory.
- </abstract>
- <para>
- The <methodname>firstopen</methodname> method is called by the DRM core
- for legacy UMS (User Mode Setting) drivers only when an application
- opens a device that has no other opened file handle. UMS drivers can
- implement it to acquire device resources. KMS drivers can't use the
- method and must acquire resources in the <methodname>load</methodname>
- method instead.
- </para>
- <para>
- Similarly the <methodname>lastclose</methodname> method is called when
- the last application holding a file handle opened on the device closes
- it, for both UMS and KMS drivers. Additionally, the method is also
- called at module unload time or, for hot-pluggable devices, when the
- device is unplugged. The <methodname>firstopen</methodname> and
- <methodname>lastclose</methodname> calls can thus be unbalanced.
- </para>
- <para>
- The <methodname>open</methodname> method is called every time the device
- is opened by an application. Drivers can allocate per-file private data
- in this method and store them in the struct
- <structname>drm_file</structname> <structfield>driver_priv</structfield>
- field. Note that the <methodname>open</methodname> method is called
- before <methodname>firstopen</methodname>.
- </para>
- <para>
- The close operation is split into <methodname>preclose</methodname> and
- <methodname>postclose</methodname> methods. Drivers must stop and
- cleanup all per-file operations in the <methodname>preclose</methodname>
- method. For instance pending vertical blanking and page flip events must
- be cancelled. No per-file operation is allowed on the file handle after
- returning from the <methodname>preclose</methodname> method.
- </para>
- <para>
- Finally the <methodname>postclose</methodname> method is called as the
- last step of the close operation, right before calling the
- <methodname>lastclose</methodname> method if no other open file handle
- exists for the device. Drivers that have allocated per-file private data
- in the <methodname>open</methodname> method should free it here.
- </para>
- <para>
- The <methodname>lastclose</methodname> method should restore CRTC and
- plane properties to default value, so that a subsequent open of the
- device will not inherit state from the previous user. It can also be
- used to execute delayed power switching state changes, e.g. in
- conjunction with the vga-switcheroo infrastructure. Beyond that KMS
- drivers should not do any further cleanup. Only legacy UMS drivers might
- need to clean up device state so that the vga console or an independent
- fbdev driver could take over.
- </para>
- </sect2>
- <sect2>
- <title>File Operations</title>
- <synopsis>const struct file_operations *fops</synopsis>
- <abstract>File operations for the DRM device node.</abstract>
- <para>
- Drivers must define the file operations structure that forms the DRM
- userspace API entry point, even though most of those operations are
- implemented in the DRM core. The <methodname>open</methodname>,
- <methodname>release</methodname> and <methodname>ioctl</methodname>
- operations are handled by
- <programlisting>
- .owner = THIS_MODULE,
- .open = drm_open,
- .release = drm_release,
- .unlocked_ioctl = drm_ioctl,
- #ifdef CONFIG_COMPAT
- .compat_ioctl = drm_compat_ioctl,
- #endif
- </programlisting>
- </para>
- <para>
- Drivers that implement private ioctls that requires 32/64bit
- compatibility support must provide their own
- <methodname>compat_ioctl</methodname> handler that processes private
- ioctls and calls <function>drm_compat_ioctl</function> for core ioctls.
- </para>
- <para>
- The <methodname>read</methodname> and <methodname>poll</methodname>
- operations provide support for reading DRM events and polling them. They
- are implemented by
- <programlisting>
- .poll = drm_poll,
- .read = drm_read,
- .llseek = no_llseek,
- </programlisting>
- </para>
- <para>
- The memory mapping implementation varies depending on how the driver
- manages memory. Pre-GEM drivers will use <function>drm_mmap</function>,
- while GEM-aware drivers will use <function>drm_gem_mmap</function>. See
- <xref linkend="drm-gem"/>.
- <programlisting>
- .mmap = drm_gem_mmap,
- </programlisting>
- </para>
- <para>
- No other file operation is supported by the DRM API.
- </para>
- </sect2>
- <sect2>
- <title>IOCTLs</title>
- <synopsis>struct drm_ioctl_desc *ioctls;
-int num_ioctls;</synopsis>
- <abstract>Driver-specific ioctls descriptors table.</abstract>
- <para>
- Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls
- descriptors table is indexed by the ioctl number offset from the base
- value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the
- table entries.
- </para>
- <para>
- <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting>
- <para>
- <parameter>ioctl</parameter> is the ioctl name. Drivers must define
- the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number
- offset from DRM_COMMAND_BASE and the ioctl number respectively. The
- first macro is private to the device while the second must be exposed
- to userspace in a public header.
- </para>
- <para>
- <parameter>func</parameter> is a pointer to the ioctl handler function
- compatible with the <type>drm_ioctl_t</type> type.
- <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data,
- struct drm_file *file_priv);</programlisting>
- </para>
- <para>
- <parameter>flags</parameter> is a bitmask combination of the following
- values. It restricts how the ioctl is allowed to be called.
- <itemizedlist>
- <listitem><para>
- DRM_AUTH - Only authenticated callers allowed
- </para></listitem>
- <listitem><para>
- DRM_MASTER - The ioctl can only be called on the master file
- handle
- </para></listitem>
- <listitem><para>
- DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed
- </para></listitem>
- <listitem><para>
- DRM_CONTROL_ALLOW - The ioctl can only be called on a control
- device
- </para></listitem>
- <listitem><para>
- DRM_UNLOCKED - The ioctl handler will be called without locking
- the DRM global mutex
- </para></listitem>
- </itemizedlist>
- </para>
- </para>
- </sect2>
- </sect1>
- <sect1>
- <title>Legacy Support Code</title>
- <para>
- The section very briefly covers some of the old legacy support code which
- is only used by old DRM drivers which have done a so-called shadow-attach
- to the underlying device instead of registering as a real driver. This
- also includes some of the old generic buffer management and command
- submission code. Do not use any of this in new and modern drivers.
- </para>
-
- <sect2>
- <title>Legacy Suspend/Resume</title>
- <para>
- The DRM core provides some suspend/resume code, but drivers wanting full
- suspend/resume support should provide save() and restore() functions.
- These are called at suspend, hibernate, or resume time, and should perform
- any state save or restore required by your device across suspend or
- hibernate states.
- </para>
- <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);
- int (*resume) (struct drm_device *);</synopsis>
- <para>
- Those are legacy suspend and resume methods which
- <emphasis>only</emphasis> work with the legacy shadow-attach driver
- registration functions. New driver should use the power management
- interface provided by their bus type (usually through
- the struct <structname>device_driver</structname> dev_pm_ops) and set
- these methods to NULL.
- </para>
- </sect2>
-
- <sect2>
- <title>Legacy DMA Services</title>
- <para>
- This should cover how DMA mapping etc. is supported by the core.
- These functions are deprecated and should not be used.
- </para>
- </sect2>
- </sect1>
- </chapter>
-
-<!-- TODO
-
-- Add a glossary
-- Document the struct_mutex catch-all lock
-- Document connector properties
-
-- Why is the load method optional?
-- What are drivers supposed to set the initial display state to, and how?
- Connector's DPMS states are not initialized and are thus equal to
- DRM_MODE_DPMS_ON. The fbcon compatibility layer calls
- drm_helper_disable_unused_functions(), which disables unused encoders and
- CRTCs, but doesn't touch the connectors' DPMS state, and
- drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers
- that don't implement (or just don't use) fbcon compatibility need to call
- those functions themselves?
-- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset()
- around mode setting. Should this be done in the DRM core?
-- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset()
- call and never set back to 0. It seems to be safe to permanently set it to 1
- in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as
- well. This should be investigated.
-- crtc and connector .save and .restore operations are only used internally in
- drivers, should they be removed from the core?
-- encoder mid-layer .save and .restore operations are only used internally in
- drivers, should they be removed from the core?
-- encoder mid-layer .detect operation is only used internally in drivers,
- should it be removed from the core?
--->
-
- <!-- External interfaces -->
-
- <chapter id="drmExternals">
- <title>Userland interfaces</title>
- <para>
- The DRM core exports several interfaces to applications,
- generally intended to be used through corresponding libdrm
- wrapper functions. In addition, drivers export device-specific
- interfaces for use by userspace drivers &amp; device-aware
- applications through ioctls and sysfs files.
- </para>
- <para>
- External interfaces include: memory mapping, context management,
- DMA operations, AGP management, vblank control, fence
- management, memory management, and output management.
- </para>
- <para>
- Cover generic ioctls and sysfs layout here. We only need high-level
- info, since man pages should cover the rest.
- </para>
-
- <!-- External: render nodes -->
-
- <sect1>
- <title>Render nodes</title>
- <para>
- DRM core provides multiple character-devices for user-space to use.
- Depending on which device is opened, user-space can perform a different
- set of operations (mainly ioctls). The primary node is always created
- and called card&lt;num&gt;. Additionally, a currently
- unused control node, called controlD&lt;num&gt; is also
- created. The primary node provides all legacy operations and
- historically was the only interface used by userspace. With KMS, the
- control node was introduced. However, the planned KMS control interface
- has never been written and so the control node stays unused to date.
- </para>
- <para>
- With the increased use of offscreen renderers and GPGPU applications,
- clients no longer require running compositors or graphics servers to
- make use of a GPU. But the DRM API required unprivileged clients to
- authenticate to a DRM-Master prior to getting GPU access. To avoid this
- step and to grant clients GPU access without authenticating, render
- nodes were introduced. Render nodes solely serve render clients, that
- is, no modesetting or privileged ioctls can be issued on render nodes.
- Only non-global rendering commands are allowed. If a driver supports
- render nodes, it must advertise it via the DRIVER_RENDER
- DRM driver capability. If not supported, the primary node must be used
- for render clients together with the legacy drmAuth authentication
- procedure.
- </para>
- <para>
- If a driver advertises render node support, DRM core will create a
- separate render node called renderD&lt;num&gt;. There will
- be one render node per device. No ioctls except PRIME-related ioctls
- will be allowed on this node. Especially GEM_OPEN will be
- explicitly prohibited. Render nodes are designed to avoid the
- buffer-leaks, which occur if clients guess the flink names or mmap
- offsets on the legacy interface. Additionally to this basic interface,
- drivers must mark their driver-dependent render-only ioctls as
- DRM_RENDER_ALLOW so render clients can use them. Driver
- authors must be careful not to allow any privileged ioctls on render
- nodes.
- </para>
- <para>
- With render nodes, user-space can now control access to the render node
- via basic file-system access-modes. A running graphics server which
- authenticates clients on the privileged primary/legacy node is no longer
- required. Instead, a client can open the render node and is immediately
- granted GPU access. Communication between clients (or servers) is done
- via PRIME. FLINK from render node to legacy node is not supported. New
- clients must not use the insecure FLINK interface.
- </para>
- <para>
- Besides dropping all modeset/global ioctls, render nodes also drop the
- DRM-Master concept. There is no reason to associate render clients with
- a DRM-Master as they are independent of any graphics server. Besides,
- they must work without any running master, anyway.
- Drivers must be able to run without a master object if they support
- render nodes. If, on the other hand, a driver requires shared state
- between clients which is visible to user-space and accessible beyond
- open-file boundaries, they cannot support render nodes.
- </para>
- </sect1>
-
- <!-- External: vblank handling -->
-
- <sect1>
- <title>VBlank event handling</title>
- <para>
- The DRM core exposes two vertical blank related ioctls:
- <variablelist>
- <varlistentry>
- <term>DRM_IOCTL_WAIT_VBLANK</term>
- <listitem>
- <para>
- This takes a struct drm_wait_vblank structure as its argument,
- and it is used to block or request a signal when a specified
- vblank event occurs.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DRM_IOCTL_MODESET_CTL</term>
- <listitem>
- <para>
- This was only used for user-mode-settind drivers around
- modesetting changes to allow the kernel to update the vblank
- interrupt after mode setting, since on many devices the vertical
- blank counter is reset to 0 at some point during modeset. Modern
- drivers should not call this any more since with kernel mode
- setting it is a no-op.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </sect1>
-
- </chapter>
-</part>
-<part id="drmDrivers">
- <title>DRM Drivers</title>
-
- <partintro>
- <para>
- This second part of the DRM Developer's Guide documents driver code,
- implementation details and also all the driver-specific userspace
- interfaces. Especially since all hardware-acceleration interfaces to
- userspace are driver specific for efficiency and other reasons these
- interfaces can be rather substantial. Hence every driver has its own
- chapter.
- </para>
- </partintro>
-
- <chapter id="drmI915">
- <title>drm/i915 Intel GFX Driver</title>
- <para>
- The drm/i915 driver supports all (with the exception of some very early
- models) integrated GFX chipsets with both Intel display and rendering
- blocks. This excludes a set of SoC platforms with an SGX rendering unit,
- those have basic support through the gma500 drm driver.
- </para>
- <sect1>
- <title>Core Driver Infrastructure</title>
- <para>
- This section covers core driver infrastructure used by both the display
- and the GEM parts of the driver.
- </para>
- <sect2>
- <title>Runtime Power Management</title>
-!Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm
-!Idrivers/gpu/drm/i915/intel_runtime_pm.c
-!Idrivers/gpu/drm/i915/intel_uncore.c
- </sect2>
- <sect2>
- <title>Interrupt Handling</title>
-!Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling
-!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init
-!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_fini
-!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts
-!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts
- </sect2>
- <sect2>
- <title>Intel GVT-g Guest Support(vGPU)</title>
-!Pdrivers/gpu/drm/i915/i915_vgpu.c Intel GVT-g guest support
-!Idrivers/gpu/drm/i915/i915_vgpu.c
- </sect2>
- </sect1>
- <sect1>
- <title>Display Hardware Handling</title>
- <para>
- This section covers everything related to the display hardware including
- the mode setting infrastructure, plane, sprite and cursor handling and
- display, output probing and related topics.
- </para>
- <sect2>
- <title>Mode Setting Infrastructure</title>
- <para>
- The i915 driver is thus far the only DRM driver which doesn't use the
- common DRM helper code to implement mode setting sequences. Thus it
- has its own tailor-made infrastructure for executing a display
- configuration change.
- </para>
- </sect2>
- <sect2>
- <title>Frontbuffer Tracking</title>
-!Pdrivers/gpu/drm/i915/intel_frontbuffer.c frontbuffer tracking
-!Idrivers/gpu/drm/i915/intel_frontbuffer.c
-!Fdrivers/gpu/drm/i915/intel_drv.h intel_frontbuffer_flip
-!Fdrivers/gpu/drm/i915/i915_gem.c i915_gem_track_fb
- </sect2>
- <sect2>
- <title>Display FIFO Underrun Reporting</title>
-!Pdrivers/gpu/drm/i915/intel_fifo_underrun.c fifo underrun handling
-!Idrivers/gpu/drm/i915/intel_fifo_underrun.c
- </sect2>
- <sect2>
- <title>Plane Configuration</title>
- <para>
- This section covers plane configuration and composition with the
- primary plane, sprites, cursors and overlays. This includes the
- infrastructure to do atomic vsync'ed updates of all this state and
- also tightly coupled topics like watermark setup and computation,
- framebuffer compression and panel self refresh.
- </para>
- </sect2>
- <sect2>
- <title>Atomic Plane Helpers</title>
-!Pdrivers/gpu/drm/i915/intel_atomic_plane.c atomic plane helpers
-!Idrivers/gpu/drm/i915/intel_atomic_plane.c
- </sect2>
- <sect2>
- <title>Output Probing</title>
- <para>
- This section covers output probing and related infrastructure like the
- hotplug interrupt storm detection and mitigation code. Note that the
- i915 driver still uses most of the common DRM helper code for output
- probing, so those sections fully apply.
- </para>
- </sect2>
- <sect2>
- <title>High Definition Audio</title>
-!Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port
-!Idrivers/gpu/drm/i915/intel_audio.c
- </sect2>
- <sect2>
- <title>Panel Self Refresh PSR (PSR/SRD)</title>
-!Pdrivers/gpu/drm/i915/intel_psr.c Panel Self Refresh (PSR/SRD)
-!Idrivers/gpu/drm/i915/intel_psr.c
- </sect2>
- <sect2>
- <title>Frame Buffer Compression (FBC)</title>
-!Pdrivers/gpu/drm/i915/intel_fbc.c Frame Buffer Compression (FBC)
-!Idrivers/gpu/drm/i915/intel_fbc.c
- </sect2>
- <sect2>
- <title>Display Refresh Rate Switching (DRRS)</title>
-!Pdrivers/gpu/drm/i915/intel_dp.c Display Refresh Rate Switching (DRRS)
-!Fdrivers/gpu/drm/i915/intel_dp.c intel_dp_set_drrs_state
-!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_enable
-!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_disable
-!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_invalidate
-!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_flush
-!Fdrivers/gpu/drm/i915/intel_dp.c intel_dp_drrs_init
-
- </sect2>
- <sect2>
- <title>DPIO</title>
-!Pdrivers/gpu/drm/i915/i915_reg.h DPIO
- <table id="dpiox2">
- <title>Dual channel PHY (VLV/CHV)</title>
- <tgroup cols="8">
- <colspec colname="c0" />
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <colspec colname="c5" />
- <colspec colname="c6" />
- <colspec colname="c7" />
- <spanspec spanname="ch0" namest="c0" nameend="c3" />
- <spanspec spanname="ch1" namest="c4" nameend="c7" />
- <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" />
- <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" />
- <spanspec spanname="ch1pcs01" namest="c4" nameend="c5" />
- <spanspec spanname="ch1pcs23" namest="c6" nameend="c7" />
- <thead>
- <row>
- <entry spanname="ch0">CH0</entry>
- <entry spanname="ch1">CH1</entry>
- </row>
- </thead>
- <tbody valign="top" align="center">
- <row>
- <entry spanname="ch0">CMN/PLL/REF</entry>
- <entry spanname="ch1">CMN/PLL/REF</entry>
- </row>
- <row>
- <entry spanname="ch0pcs01">PCS01</entry>
- <entry spanname="ch0pcs23">PCS23</entry>
- <entry spanname="ch1pcs01">PCS01</entry>
- <entry spanname="ch1pcs23">PCS23</entry>
- </row>
- <row>
- <entry>TX0</entry>
- <entry>TX1</entry>
- <entry>TX2</entry>
- <entry>TX3</entry>
- <entry>TX0</entry>
- <entry>TX1</entry>
- <entry>TX2</entry>
- <entry>TX3</entry>
- </row>
- <row>
- <entry spanname="ch0">DDI0</entry>
- <entry spanname="ch1">DDI1</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table id="dpiox1">
- <title>Single channel PHY (CHV)</title>
- <tgroup cols="4">
- <colspec colname="c0" />
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <spanspec spanname="ch0" namest="c0" nameend="c3" />
- <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" />
- <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" />
- <thead>
- <row>
- <entry spanname="ch0">CH0</entry>
- </row>
- </thead>
- <tbody valign="top" align="center">
- <row>
- <entry spanname="ch0">CMN/PLL/REF</entry>
- </row>
- <row>
- <entry spanname="ch0pcs01">PCS01</entry>
- <entry spanname="ch0pcs23">PCS23</entry>
- </row>
- <row>
- <entry>TX0</entry>
- <entry>TX1</entry>
- <entry>TX2</entry>
- <entry>TX3</entry>
- </row>
- <row>
- <entry spanname="ch0">DDI2</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Memory Management and Command Submission</title>
- <para>
- This sections covers all things related to the GEM implementation in the
- i915 driver.
- </para>
- <sect2>
- <title>Batchbuffer Parsing</title>
-!Pdrivers/gpu/drm/i915/i915_cmd_parser.c batch buffer command parser
-!Idrivers/gpu/drm/i915/i915_cmd_parser.c
- </sect2>
- <sect2>
- <title>Batchbuffer Pools</title>
-!Pdrivers/gpu/drm/i915/i915_gem_batch_pool.c batch pool
-!Idrivers/gpu/drm/i915/i915_gem_batch_pool.c
- </sect2>
- <sect2>
- <title>Logical Rings, Logical Ring Contexts and Execlists</title>
-!Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists
-!Idrivers/gpu/drm/i915/intel_lrc.c
- </sect2>
- <sect2>
- <title>Global GTT views</title>
-!Pdrivers/gpu/drm/i915/i915_gem_gtt.c Global GTT views
-!Idrivers/gpu/drm/i915/i915_gem_gtt.c
- </sect2>
- <sect2>
- <title>Buffer Object Eviction</title>
- <para>
- This section documents the interface functions for evicting buffer
- objects to make space available in the virtual gpu address spaces.
- Note that this is mostly orthogonal to shrinking buffer objects
- caches, which has the goal to make main memory (shared with the gpu
- through the unified memory architecture) available.
- </para>
-!Idrivers/gpu/drm/i915/i915_gem_evict.c
- </sect2>
- <sect2>
- <title>Buffer Object Memory Shrinking</title>
- <para>
- This section documents the interface function for shrinking memory
- usage of buffer object caches. Shrinking is used to make main memory
- available. Note that this is mostly orthogonal to evicting buffer
- objects, which has the goal to make space in gpu virtual address
- spaces.
- </para>
-!Idrivers/gpu/drm/i915/i915_gem_shrinker.c
- </sect2>
- </sect1>
-
- <sect1>
- <title> Tracing </title>
- <para>
- This sections covers all things related to the tracepoints implemented in
- the i915 driver.
- </para>
- <sect2>
- <title> i915_ppgtt_create and i915_ppgtt_release </title>
-!Pdrivers/gpu/drm/i915/i915_trace.h i915_ppgtt_create and i915_ppgtt_release tracepoints
- </sect2>
- <sect2>
- <title> i915_context_create and i915_context_free </title>
-!Pdrivers/gpu/drm/i915/i915_trace.h i915_context_create and i915_context_free tracepoints
- </sect2>
- <sect2>
- <title> switch_mm </title>
-!Pdrivers/gpu/drm/i915/i915_trace.h switch_mm tracepoint
- </sect2>
- </sect1>
-
- </chapter>
-!Cdrivers/gpu/drm/i915/i915_irq.c
-</part>
-</book>
diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl
deleted file mode 100644
index bcdfdb9a9277..000000000000
--- a/Documentation/DocBook/filesystems.tmpl
+++ /dev/null
@@ -1,425 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Linux-filesystems-API">
- <bookinfo>
- <title>Linux Filesystems API</title>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="vfs">
- <title>The Linux VFS</title>
- <sect1 id="the_filesystem_types"><title>The Filesystem types</title>
-!Iinclude/linux/fs.h
- </sect1>
- <sect1 id="the_directory_cache"><title>The Directory Cache</title>
-!Efs/dcache.c
-!Iinclude/linux/dcache.h
- </sect1>
- <sect1 id="inode_handling"><title>Inode Handling</title>
-!Efs/inode.c
-!Efs/bad_inode.c
- </sect1>
- <sect1 id="registration_and_superblocks"><title>Registration and Superblocks</title>
-!Efs/super.c
- </sect1>
- <sect1 id="file_locks"><title>File Locks</title>
-!Efs/locks.c
-!Ifs/locks.c
- </sect1>
- <sect1 id="other_functions"><title>Other Functions</title>
-!Efs/mpage.c
-!Efs/namei.c
-!Efs/buffer.c
-!Eblock/bio.c
-!Efs/seq_file.c
-!Efs/filesystems.c
-!Efs/fs-writeback.c
-!Efs/block_dev.c
- </sect1>
- </chapter>
-
- <chapter id="proc">
- <title>The proc filesystem</title>
-
- <sect1 id="sysctl_interface"><title>sysctl interface</title>
-!Ekernel/sysctl.c
- </sect1>
-
- <sect1 id="proc_filesystem_interface"><title>proc filesystem interface</title>
-!Ifs/proc/base.c
- </sect1>
- </chapter>
-
- <chapter id="fs_events">
- <title>Events based on file descriptors</title>
-!Efs/eventfd.c
- </chapter>
-
- <chapter id="sysfs">
- <title>The Filesystem for Exporting Kernel Objects</title>
-!Efs/sysfs/file.c
-!Efs/sysfs/symlink.c
- </chapter>
-
- <chapter id="debugfs">
- <title>The debugfs filesystem</title>
-
- <sect1 id="debugfs_interface"><title>debugfs interface</title>
-!Efs/debugfs/inode.c
-!Efs/debugfs/file.c
- </sect1>
- </chapter>
-
- <chapter id="LinuxJDBAPI">
- <chapterinfo>
- <title>The Linux Journalling API</title>
-
- <authorgroup>
- <author>
- <firstname>Roger</firstname>
- <surname>Gammans</surname>
- <affiliation>
- <address>
- <email>rgammans@computer-surgery.co.uk</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <authorgroup>
- <author>
- <firstname>Stephen</firstname>
- <surname>Tweedie</surname>
- <affiliation>
- <address>
- <email>sct@redhat.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2002</year>
- <holder>Roger Gammans</holder>
- </copyright>
- </chapterinfo>
-
- <title>The Linux Journalling API</title>
-
- <sect1 id="journaling_overview">
- <title>Overview</title>
- <sect2 id="journaling_details">
- <title>Details</title>
-<para>
-The journalling layer is easy to use. You need to
-first of all create a journal_t data structure. There are
-two calls to do this dependent on how you decide to allocate the physical
-media on which the journal resides. The journal_init_inode() call
-is for journals stored in filesystem inodes, or the journal_init_dev()
-call can be use for journal stored on a raw device (in a continuous range
-of blocks). A journal_t is a typedef for a struct pointer, so when
-you are finally finished make sure you call journal_destroy() on it
-to free up any used kernel memory.
-</para>
-
-<para>
-Once you have got your journal_t object you need to 'mount' or load the journal
-file, unless of course you haven't initialised it yet - in which case you
-need to call journal_create().
-</para>
-
-<para>
-Most of the time however your journal file will already have been created, but
-before you load it you must call journal_wipe() to empty the journal file.
-Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the
-job of the client file system to detect this and skip the call to journal_wipe().
-</para>
-
-<para>
-In either case the next call should be to journal_load() which prepares the
-journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery()
-for you if it detects any outstanding transactions in the journal and similarly
-journal_load() will call journal_recover() if necessary.
-I would advise reading fs/ext3/super.c for examples on this stage.
-[RGG: Why is the journal_wipe() call necessary - doesn't this needlessly
-complicate the API. Or isn't a good idea for the journal layer to hide
-dirty mounts from the client fs]
-</para>
-
-<para>
-Now you can go ahead and start modifying the underlying
-filesystem. Almost.
-</para>
-
-<para>
-
-You still need to actually journal your filesystem changes, this
-is done by wrapping them into transactions. Additionally you
-also need to wrap the modification of each of the buffers
-with calls to the journal layer, so it knows what the modifications
-you are actually making are. To do this use journal_start() which
-returns a transaction handle.
-</para>
-
-<para>
-journal_start()
-and its counterpart journal_stop(), which indicates the end of a transaction
-are nestable calls, so you can reenter a transaction if necessary,
-but remember you must call journal_stop() the same number of times as
-journal_start() before the transaction is completed (or more accurately
-leaves the update phase). Ext3/VFS makes use of this feature to simplify
-quota support.
-</para>
-
-<para>
-Inside each transaction you need to wrap the modifications to the
-individual buffers (blocks). Before you start to modify a buffer you
-need to call journal_get_{create,write,undo}_access() as appropriate,
-this allows the journalling layer to copy the unmodified data if it
-needs to. After all the buffer may be part of a previously uncommitted
-transaction.
-At this point you are at last ready to modify a buffer, and once
-you are have done so you need to call journal_dirty_{meta,}data().
-Or if you've asked for access to a buffer you now know is now longer
-required to be pushed back on the device you can call journal_forget()
-in much the same way as you might have used bforget() in the past.
-</para>
-
-<para>
-A journal_flush() may be called at any time to commit and checkpoint
-all your transactions.
-</para>
-
-<para>
-Then at umount time , in your put_super() you can then call journal_destroy()
-to clean up your in-core journal object.
-</para>
-
-<para>
-Unfortunately there a couple of ways the journal layer can cause a deadlock.
-The first thing to note is that each task can only have
-a single outstanding transaction at any one time, remember nothing
-commits until the outermost journal_stop(). This means
-you must complete the transaction at the end of each file/inode/address
-etc. operation you perform, so that the journalling system isn't re-entered
-on another journal. Since transactions can't be nested/batched
-across differing journals, and another filesystem other than
-yours (say ext3) may be modified in a later syscall.
-</para>
-
-<para>
-The second case to bear in mind is that journal_start() can
-block if there isn't enough space in the journal for your transaction
-(based on the passed nblocks param) - when it blocks it merely(!) needs to
-wait for transactions to complete and be committed from other tasks,
-so essentially we are waiting for journal_stop(). So to avoid
-deadlocks you must treat journal_start/stop() as if they
-were semaphores and include them in your semaphore ordering rules to prevent
-deadlocks. Note that journal_extend() has similar blocking behaviour to
-journal_start() so you can deadlock here just as easily as on journal_start().
-</para>
-
-<para>
-Try to reserve the right number of blocks the first time. ;-). This will
-be the maximum number of blocks you are going to touch in this transaction.
-I advise having a look at at least ext3_jbd.h to see the basis on which
-ext3 uses to make these decisions.
-</para>
-
-<para>
-Another wriggle to watch out for is your on-disk block allocation strategy.
-why? Because, if you undo a delete, you need to ensure you haven't reused any
-of the freed blocks in a later transaction. One simple way of doing this
-is make sure any blocks you allocate only have checkpointed transactions
-listed against them. Ext3 does this in ext3_test_allocatable().
-</para>
-
-<para>
-Lock is also providing through journal_{un,}lock_updates(),
-ext3 uses this when it wants a window with a clean and stable fs for a moment.
-eg.
-</para>
-
-<programlisting>
-
- journal_lock_updates() //stop new stuff happening..
- journal_flush() // checkpoint everything.
- ..do stuff on stable fs
- journal_unlock_updates() // carry on with filesystem use.
-</programlisting>
-
-<para>
-The opportunities for abuse and DOS attacks with this should be obvious,
-if you allow unprivileged userspace to trigger codepaths containing these
-calls.
-</para>
-
-<para>
-A new feature of jbd since 2.5.25 is commit callbacks with the new
-journal_callback_set() function you can now ask the journalling layer
-to call you back when the transaction is finally committed to disk, so that
-you can do some of your own management. The key to this is the journal_callback
-struct, this maintains the internal callback information but you can
-extend it like this:-
-</para>
-<programlisting>
- struct myfs_callback_s {
- //Data structure element required by jbd..
- struct journal_callback for_jbd;
- // Stuff for myfs allocated together.
- myfs_inode* i_commited;
-
- }
-</programlisting>
-
-<para>
-this would be useful if you needed to know when data was committed to a
-particular inode.
-</para>
-
- </sect2>
-
- <sect2 id="jbd_summary">
- <title>Summary</title>
-<para>
-Using the journal is a matter of wrapping the different context changes,
-being each mount, each modification (transaction) and each changed buffer
-to tell the journalling layer about them.
-</para>
-
-<para>
-Here is a some pseudo code to give you an idea of how it works, as
-an example.
-</para>
-
-<programlisting>
- journal_t* my_jnrl = journal_create();
- journal_init_{dev,inode}(jnrl,...)
- if (clean) journal_wipe();
- journal_load();
-
- foreach(transaction) { /*transactions must be
- completed before
- a syscall returns to
- userspace*/
-
- handle_t * xct=journal_start(my_jnrl);
- foreach(bh) {
- journal_get_{create,write,undo}_access(xact,bh);
- if ( myfs_modify(bh) ) { /* returns true
- if makes changes */
- journal_dirty_{meta,}data(xact,bh);
- } else {
- journal_forget(bh);
- }
- }
- journal_stop(xct);
- }
- journal_destroy(my_jrnl);
-</programlisting>
- </sect2>
-
- </sect1>
-
- <sect1 id="data_types">
- <title>Data Types</title>
- <para>
- The journalling layer uses typedefs to 'hide' the concrete definitions
- of the structures used. As a client of the JBD layer you can
- just rely on the using the pointer as a magic cookie of some sort.
-
- Obviously the hiding is not enforced as this is 'C'.
- </para>
- <sect2 id="structures"><title>Structures</title>
-!Iinclude/linux/jbd.h
- </sect2>
- </sect1>
-
- <sect1 id="functions">
- <title>Functions</title>
- <para>
- The functions here are split into two groups those that
- affect a journal as a whole, and those which are used to
- manage transactions
- </para>
- <sect2 id="journal_level"><title>Journal Level</title>
-!Efs/jbd/journal.c
-!Ifs/jbd/recovery.c
- </sect2>
- <sect2 id="transaction_level"><title>Transasction Level</title>
-!Efs/jbd/transaction.c
- </sect2>
- </sect1>
- <sect1 id="see_also">
- <title>See also</title>
- <para>
- <citation>
- <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz">
- Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie
- </ulink>
- </citation>
- </para>
- <para>
- <citation>
- <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html">
- Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie
- </ulink>
- </citation>
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="splice">
- <title>splice API</title>
- <para>
- splice is a method for moving blocks of data around inside the
- kernel, without continually transferring them between the kernel
- and user space.
- </para>
-!Ffs/splice.c
- </chapter>
-
- <chapter id="pipes">
- <title>pipes API</title>
- <para>
- Pipe interfaces are all for in-kernel (builtin image) use.
- They are not exported for use by modules.
- </para>
-!Iinclude/linux/pipe_fs_i.h
-!Ffs/pipe.c
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
deleted file mode 100644
index 641629221176..000000000000
--- a/Documentation/DocBook/gadget.tmpl
+++ /dev/null
@@ -1,793 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="USB-Gadget-API">
- <bookinfo>
- <title>USB Gadget API for Linux</title>
- <date>20 August 2004</date>
- <edition>20 August 2004</edition>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- <copyright>
- <year>2003-2004</year>
- <holder>David Brownell</holder>
- </copyright>
-
- <author>
- <firstname>David</firstname>
- <surname>Brownell</surname>
- <affiliation>
- <address><email>dbrownell@users.sourceforge.net</email></address>
- </affiliation>
- </author>
- </bookinfo>
-
-<toc></toc>
-
-<chapter id="intro"><title>Introduction</title>
-
-<para>This document presents a Linux-USB "Gadget"
-kernel mode
-API, for use within peripherals and other USB devices
-that embed Linux.
-It provides an overview of the API structure,
-and shows how that fits into a system development project.
-This is the first such API released on Linux to address
-a number of important problems, including: </para>
-
-<itemizedlist>
- <listitem><para>Supports USB 2.0, for high speed devices which
- can stream data at several dozen megabytes per second.
- </para></listitem>
- <listitem><para>Handles devices with dozens of endpoints just as
- well as ones with just two fixed-function ones. Gadget drivers
- can be written so they're easy to port to new hardware.
- </para></listitem>
- <listitem><para>Flexible enough to expose more complex USB device
- capabilities such as multiple configurations, multiple interfaces,
- composite devices,
- and alternate interface settings.
- </para></listitem>
- <listitem><para>USB "On-The-Go" (OTG) support, in conjunction
- with updates to the Linux-USB host side.
- </para></listitem>
- <listitem><para>Sharing data structures and API models with the
- Linux-USB host side API. This helps the OTG support, and
- looks forward to more-symmetric frameworks (where the same
- I/O model is used by both host and device side drivers).
- </para></listitem>
- <listitem><para>Minimalist, so it's easier to support new device
- controller hardware. I/O processing doesn't imply large
- demands for memory or CPU resources.
- </para></listitem>
-</itemizedlist>
-
-
-<para>Most Linux developers will not be able to use this API, since they
-have USB "host" hardware in a PC, workstation, or server.
-Linux users with embedded systems are more likely to
-have USB peripheral hardware.
-To distinguish drivers running inside such hardware from the
-more familiar Linux "USB device drivers",
-which are host side proxies for the real USB devices,
-a different term is used:
-the drivers inside the peripherals are "USB gadget drivers".
-In USB protocol interactions, the device driver is the master
-(or "client driver")
-and the gadget driver is the slave (or "function driver").
-</para>
-
-<para>The gadget API resembles the host side Linux-USB API in that both
-use queues of request objects to package I/O buffers, and those requests
-may be submitted or canceled.
-They share common definitions for the standard USB
-<emphasis>Chapter 9</emphasis> messages, structures, and constants.
-Also, both APIs bind and unbind drivers to devices.
-The APIs differ in detail, since the host side's current
-URB framework exposes a number of implementation details
-and assumptions that are inappropriate for a gadget API.
-While the model for control transfers and configuration
-management is necessarily different (one side is a hardware-neutral master,
-the other is a hardware-aware slave), the endpoint I/0 API used here
-should also be usable for an overhead-reduced host side API.
-</para>
-
-</chapter>
-
-<chapter id="structure"><title>Structure of Gadget Drivers</title>
-
-<para>A system running inside a USB peripheral
-normally has at least three layers inside the kernel to handle
-USB protocol processing, and may have additional layers in
-user space code.
-The "gadget" API is used by the middle layer to interact
-with the lowest level (which directly handles hardware).
-</para>
-
-<para>In Linux, from the bottom up, these layers are:
-</para>
-
-<variablelist>
-
- <varlistentry>
- <term><emphasis>USB Controller Driver</emphasis></term>
-
- <listitem>
- <para>This is the lowest software level.
- It is the only layer that talks to hardware,
- through registers, fifos, dma, irqs, and the like.
- The <filename>&lt;linux/usb/gadget.h&gt;</filename> API abstracts
- the peripheral controller endpoint hardware.
- That hardware is exposed through endpoint objects, which accept
- streams of IN/OUT buffers, and through callbacks that interact
- with gadget drivers.
- Since normal USB devices only have one upstream
- port, they only have one of these drivers.
- The controller driver can support any number of different
- gadget drivers, but only one of them can be used at a time.
- </para>
-
- <para>Examples of such controller hardware include
- the PCI-based NetChip 2280 USB 2.0 high speed controller,
- the SA-11x0 or PXA-25x UDC (found within many PDAs),
- and a variety of other products.
- </para>
-
- </listitem></varlistentry>
-
- <varlistentry>
- <term><emphasis>Gadget Driver</emphasis></term>
-
- <listitem>
- <para>The lower boundary of this driver implements hardware-neutral
- USB functions, using calls to the controller driver.
- Because such hardware varies widely in capabilities and restrictions,
- and is used in embedded environments where space is at a premium,
- the gadget driver is often configured at compile time
- to work with endpoints supported by one particular controller.
- Gadget drivers may be portable to several different controllers,
- using conditional compilation.
- (Recent kernels substantially simplify the work involved in
- supporting new hardware, by <emphasis>autoconfiguring</emphasis>
- endpoints automatically for many bulk-oriented drivers.)
- Gadget driver responsibilities include:
- </para>
- <itemizedlist>
- <listitem><para>handling setup requests (ep0 protocol responses)
- possibly including class-specific functionality
- </para></listitem>
- <listitem><para>returning configuration and string descriptors
- </para></listitem>
- <listitem><para>(re)setting configurations and interface
- altsettings, including enabling and configuring endpoints
- </para></listitem>
- <listitem><para>handling life cycle events, such as managing
- bindings to hardware,
- USB suspend/resume, remote wakeup,
- and disconnection from the USB host.
- </para></listitem>
- <listitem><para>managing IN and OUT transfers on all currently
- enabled endpoints
- </para></listitem>
- </itemizedlist>
-
- <para>
- Such drivers may be modules of proprietary code, although
- that approach is discouraged in the Linux community.
- </para>
- </listitem></varlistentry>
-
- <varlistentry>
- <term><emphasis>Upper Level</emphasis></term>
-
- <listitem>
- <para>Most gadget drivers have an upper boundary that connects
- to some Linux driver or framework in Linux.
- Through that boundary flows the data which the gadget driver
- produces and/or consumes through protocol transfers over USB.
- Examples include:
- </para>
- <itemizedlist>
- <listitem><para>user mode code, using generic (gadgetfs)
- or application specific files in
- <filename>/dev</filename>
- </para></listitem>
- <listitem><para>networking subsystem (for network gadgets,
- like the CDC Ethernet Model gadget driver)
- </para></listitem>
- <listitem><para>data capture drivers, perhaps video4Linux or
- a scanner driver; or test and measurement hardware.
- </para></listitem>
- <listitem><para>input subsystem (for HID gadgets)
- </para></listitem>
- <listitem><para>sound subsystem (for audio gadgets)
- </para></listitem>
- <listitem><para>file system (for PTP gadgets)
- </para></listitem>
- <listitem><para>block i/o subsystem (for usb-storage gadgets)
- </para></listitem>
- <listitem><para>... and more </para></listitem>
- </itemizedlist>
- </listitem></varlistentry>
-
- <varlistentry>
- <term><emphasis>Additional Layers</emphasis></term>
-
- <listitem>
- <para>Other layers may exist.
- These could include kernel layers, such as network protocol stacks,
- as well as user mode applications building on standard POSIX
- system call APIs such as
- <emphasis>open()</emphasis>, <emphasis>close()</emphasis>,
- <emphasis>read()</emphasis> and <emphasis>write()</emphasis>.
- On newer systems, POSIX Async I/O calls may be an option.
- Such user mode code will not necessarily be subject to
- the GNU General Public License (GPL).
- </para>
- </listitem></varlistentry>
-
-
-</variablelist>
-
-<para>OTG-capable systems will also need to include a standard Linux-USB
-host side stack,
-with <emphasis>usbcore</emphasis>,
-one or more <emphasis>Host Controller Drivers</emphasis> (HCDs),
-<emphasis>USB Device Drivers</emphasis> to support
-the OTG "Targeted Peripheral List",
-and so forth.
-There will also be an <emphasis>OTG Controller Driver</emphasis>,
-which is visible to gadget and device driver developers only indirectly.
-That helps the host and device side USB controllers implement the
-two new OTG protocols (HNP and SRP).
-Roles switch (host to peripheral, or vice versa) using HNP
-during USB suspend processing, and SRP can be viewed as a
-more battery-friendly kind of device wakeup protocol.
-</para>
-
-<para>Over time, reusable utilities are evolving to help make some
-gadget driver tasks simpler.
-For example, building configuration descriptors from vectors of
-descriptors for the configurations interfaces and endpoints is
-now automated, and many drivers now use autoconfiguration to
-choose hardware endpoints and initialize their descriptors.
-
-A potential example of particular interest
-is code implementing standard USB-IF protocols for
-HID, networking, storage, or audio classes.
-Some developers are interested in KDB or KGDB hooks, to let
-target hardware be remotely debugged.
-Most such USB protocol code doesn't need to be hardware-specific,
-any more than network protocols like X11, HTTP, or NFS are.
-Such gadget-side interface drivers should eventually be combined,
-to implement composite devices.
-</para>
-
-</chapter>
-
-
-<chapter id="api"><title>Kernel Mode Gadget API</title>
-
-<para>Gadget drivers declare themselves through a
-<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for
-most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>.
-The response to a set_configuration usually involves
-enabling one or more of the <emphasis>struct usb_ep</emphasis> objects
-exposed by the gadget, and submitting one or more
-<emphasis>struct usb_request</emphasis> buffers to transfer data.
-Understand those four data types, and their operations, and
-you will understand how this API works.
-</para>
-
-<note><title>Incomplete Data Type Descriptions</title>
-
-<para>This documentation was prepared using the standard Linux
-kernel <filename>docproc</filename> tool, which turns text
-and in-code comments into SGML DocBook and then into usable
-formats such as HTML or PDF.
-Other than the "Chapter 9" data types, most of the significant
-data types and functions are described here.
-</para>
-
-<para>However, docproc does not understand all the C constructs
-that are used, so some relevant information is likely omitted from
-what you are reading.
-One example of such information is endpoint autoconfiguration.
-You'll have to read the header file, and use example source
-code (such as that for "Gadget Zero"), to fully understand the API.
-</para>
-
-<para>The part of the API implementing some basic
-driver capabilities is specific to the version of the
-Linux kernel that's in use.
-The 2.6 kernel includes a <emphasis>driver model</emphasis>
-framework that has no analogue on earlier kernels;
-so those parts of the gadget API are not fully portable.
-(They are implemented on 2.4 kernels, but in a different way.)
-The driver model state is another part of this API that is
-ignored by the kerneldoc tools.
-</para>
-</note>
-
-<para>The core API does not expose
-every possible hardware feature, only the most widely available ones.
-There are significant hardware features, such as device-to-device DMA
-(without temporary storage in a memory buffer)
-that would be added using hardware-specific APIs.
-</para>
-
-<para>This API allows drivers to use conditional compilation to handle
-endpoint capabilities of different hardware, but doesn't require that.
-Hardware tends to have arbitrary restrictions, relating to
-transfer types, addressing, packet sizes, buffering, and availability.
-As a rule, such differences only matter for "endpoint zero" logic
-that handles device configuration and management.
-The API supports limited run-time
-detection of capabilities, through naming conventions for endpoints.
-Many drivers will be able to at least partially autoconfigure
-themselves.
-In particular, driver init sections will often have endpoint
-autoconfiguration logic that scans the hardware's list of endpoints
-to find ones matching the driver requirements
-(relying on those conventions), to eliminate some of the most
-common reasons for conditional compilation.
-</para>
-
-<para>Like the Linux-USB host side API, this API exposes
-the "chunky" nature of USB messages: I/O requests are in terms
-of one or more "packets", and packet boundaries are visible to drivers.
-Compared to RS-232 serial protocols, USB resembles
-synchronous protocols like HDLC
-(N bytes per frame, multipoint addressing, host as the primary
-station and devices as secondary stations)
-more than asynchronous ones
-(tty style: 8 data bits per frame, no parity, one stop bit).
-So for example the controller drivers won't buffer
-two single byte writes into a single two-byte USB IN packet,
-although gadget drivers may do so when they implement
-protocols where packet boundaries (and "short packets")
-are not significant.
-</para>
-
-<sect1 id="lifecycle"><title>Driver Life Cycle</title>
-
-<para>Gadget drivers make endpoint I/O requests to hardware without
-needing to know many details of the hardware, but driver
-setup/configuration code needs to handle some differences.
-Use the API like this:
-</para>
-
-<orderedlist numeration='arabic'>
-
-<listitem><para>Register a driver for the particular device side
-usb controller hardware,
-such as the net2280 on PCI (USB 2.0),
-sa11x0 or pxa25x as found in Linux PDAs,
-and so on.
-At this point the device is logically in the USB ch9 initial state
-("attached"), drawing no power and not usable
-(since it does not yet support enumeration).
-Any host should not see the device, since it's not
-activated the data line pullup used by the host to
-detect a device, even if VBUS power is available.
-</para></listitem>
-
-<listitem><para>Register a gadget driver that implements some higher level
-device function. That will then bind() to a usb_gadget, which
-activates the data line pullup sometime after detecting VBUS.
-</para></listitem>
-
-<listitem><para>The hardware driver can now start enumerating.
-The steps it handles are to accept USB power and set_address requests.
-Other steps are handled by the gadget driver.
-If the gadget driver module is unloaded before the host starts to
-enumerate, steps before step 7 are skipped.
-</para></listitem>
-
-<listitem><para>The gadget driver's setup() call returns usb descriptors,
-based both on what the bus interface hardware provides and on the
-functionality being implemented.
-That can involve alternate settings or configurations,
-unless the hardware prevents such operation.
-For OTG devices, each configuration descriptor includes
-an OTG descriptor.
-</para></listitem>
-
-<listitem><para>The gadget driver handles the last step of enumeration,
-when the USB host issues a set_configuration call.
-It enables all endpoints used in that configuration,
-with all interfaces in their default settings.
-That involves using a list of the hardware's endpoints, enabling each
-endpoint according to its descriptor.
-It may also involve using <function>usb_gadget_vbus_draw</function>
-to let more power be drawn from VBUS, as allowed by that configuration.
-For OTG devices, setting a configuration may also involve reporting
-HNP capabilities through a user interface.
-</para></listitem>
-
-<listitem><para>Do real work and perform data transfers, possibly involving
-changes to interface settings or switching to new configurations, until the
-device is disconnect()ed from the host.
-Queue any number of transfer requests to each endpoint.
-It may be suspended and resumed several times before being disconnected.
-On disconnect, the drivers go back to step 3 (above).
-</para></listitem>
-
-<listitem><para>When the gadget driver module is being unloaded,
-the driver unbind() callback is issued. That lets the controller
-driver be unloaded.
-</para></listitem>
-
-</orderedlist>
-
-<para>Drivers will normally be arranged so that just loading the
-gadget driver module (or statically linking it into a Linux kernel)
-allows the peripheral device to be enumerated, but some drivers
-will defer enumeration until some higher level component (like
-a user mode daemon) enables it.
-Note that at this lowest level there are no policies about how
-ep0 configuration logic is implemented,
-except that it should obey USB specifications.
-Such issues are in the domain of gadget drivers,
-including knowing about implementation constraints
-imposed by some USB controllers
-or understanding that composite devices might happen to
-be built by integrating reusable components.
-</para>
-
-<para>Note that the lifecycle above can be slightly different
-for OTG devices.
-Other than providing an additional OTG descriptor in each
-configuration, only the HNP-related differences are particularly
-visible to driver code.
-They involve reporting requirements during the SET_CONFIGURATION
-request, and the option to invoke HNP during some suspend callbacks.
-Also, SRP changes the semantics of
-<function>usb_gadget_wakeup</function>
-slightly.
-</para>
-
-</sect1>
-
-<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title>
-
-<para>Gadget drivers
-rely on common USB structures and constants
-defined in the
-<filename>&lt;linux/usb/ch9.h&gt;</filename>
-header file, which is standard in Linux 2.6 kernels.
-These are the same types and constants used by host
-side drivers (and usbcore).
-</para>
-
-!Iinclude/linux/usb/ch9.h
-</sect1>
-
-<sect1 id="core"><title>Core Objects and Methods</title>
-
-<para>These are declared in
-<filename>&lt;linux/usb/gadget.h&gt;</filename>,
-and are used by gadget drivers to interact with
-USB peripheral controller drivers.
-</para>
-
- <!-- yeech, this is ugly in nsgmls PDF output.
-
- the PDF bookmark and refentry output nesting is wrong,
- and the member/argument documentation indents ugly.
-
- plus something (docproc?) adds whitespace before the
- descriptive paragraph text, so it can't line up right
- unless the explanations are trivial.
- -->
-
-!Iinclude/linux/usb/gadget.h
-</sect1>
-
-<sect1 id="utils"><title>Optional Utilities</title>
-
-<para>The core API is sufficient for writing a USB Gadget Driver,
-but some optional utilities are provided to simplify common tasks.
-These utilities include endpoint autoconfiguration.
-</para>
-
-!Edrivers/usb/gadget/usbstring.c
-!Edrivers/usb/gadget/config.c
-<!-- !Edrivers/usb/gadget/epautoconf.c -->
-</sect1>
-
-<sect1 id="composite"><title>Composite Device Framework</title>
-
-<para>The core API is sufficient for writing drivers for composite
-USB devices (with more than one function in a given configuration),
-and also multi-configuration devices (also more than one function,
-but not necessarily sharing a given configuration).
-There is however an optional framework which makes it easier to
-reuse and combine functions.
-</para>
-
-<para>Devices using this framework provide a <emphasis>struct
-usb_composite_driver</emphasis>, which in turn provides one or
-more <emphasis>struct usb_configuration</emphasis> instances.
-Each such configuration includes at least one
-<emphasis>struct usb_function</emphasis>, which packages a user
-visible role such as "network link" or "mass storage device".
-Management functions may also exist, such as "Device Firmware
-Upgrade".
-</para>
-
-!Iinclude/linux/usb/composite.h
-!Edrivers/usb/gadget/composite.c
-
-</sect1>
-
-<sect1 id="functions"><title>Composite Device Functions</title>
-
-<para>At this writing, a few of the current gadget drivers have
-been converted to this framework.
-Near-term plans include converting all of them, except for "gadgetfs".
-</para>
-
-!Edrivers/usb/gadget/function/f_acm.c
-!Edrivers/usb/gadget/function/f_ecm.c
-!Edrivers/usb/gadget/function/f_subset.c
-!Edrivers/usb/gadget/function/f_obex.c
-!Edrivers/usb/gadget/function/f_serial.c
-
-</sect1>
-
-
-</chapter>
-
-<chapter id="controllers"><title>Peripheral Controller Drivers</title>
-
-<para>The first hardware supporting this API was the NetChip 2280
-controller, which supports USB 2.0 high speed and is based on PCI.
-This is the <filename>net2280</filename> driver module.
-The driver supports Linux kernel versions 2.4 and 2.6;
-contact NetChip Technologies for development boards and product
-information.
-</para>
-
-<para>Other hardware working in the "gadget" framework includes:
-Intel's PXA 25x and IXP42x series processors
-(<filename>pxa2xx_udc</filename>),
-Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>),
-Renesas SH7705/7727 (<filename>sh_udc</filename>),
-MediaQ 11xx (<filename>mq11xx_udc</filename>),
-Hynix HMS30C7202 (<filename>h7202_udc</filename>),
-National 9303/4 (<filename>n9604_udc</filename>),
-Texas Instruments OMAP (<filename>omap_udc</filename>),
-Sharp LH7A40x (<filename>lh7a40x_udc</filename>),
-and more.
-Most of those are full speed controllers.
-</para>
-
-<para>At this writing, there are people at work on drivers in
-this framework for several other USB device controllers,
-with plans to make many of them be widely available.
-</para>
-
-<!-- !Edrivers/usb/gadget/net2280.c -->
-
-<para>A partial USB simulator,
-the <filename>dummy_hcd</filename> driver, is available.
-It can act like a net2280, a pxa25x, or an sa11x0 in terms
-of available endpoints and device speeds; and it simulates
-control, bulk, and to some extent interrupt transfers.
-That lets you develop some parts of a gadget driver on a normal PC,
-without any special hardware, and perhaps with the assistance
-of tools such as GDB running with User Mode Linux.
-At least one person has expressed interest in adapting that
-approach, hooking it up to a simulator for a microcontroller.
-Such simulators can help debug subsystems where the runtime hardware
-is unfriendly to software development, or is not yet available.
-</para>
-
-<para>Support for other controllers is expected to be developed
-and contributed
-over time, as this driver framework evolves.
-</para>
-
-</chapter>
-
-<chapter id="gadget"><title>Gadget Drivers</title>
-
-<para>In addition to <emphasis>Gadget Zero</emphasis>
-(used primarily for testing and development with drivers
-for usb controller hardware), other gadget drivers exist.
-</para>
-
-<para>There's an <emphasis>ethernet</emphasis> gadget
-driver, which implements one of the most useful
-<emphasis>Communications Device Class</emphasis> (CDC) models.
-One of the standards for cable modem interoperability even
-specifies the use of this ethernet model as one of two
-mandatory options.
-Gadgets using this code look to a USB host as if they're
-an Ethernet adapter.
-It provides access to a network where the gadget's CPU is one host,
-which could easily be bridging, routing, or firewalling
-access to other networks.
-Since some hardware can't fully implement the CDC Ethernet
-requirements, this driver also implements a "good parts only"
-subset of CDC Ethernet.
-(That subset doesn't advertise itself as CDC Ethernet,
-to avoid creating problems.)
-</para>
-
-<para>Support for Microsoft's <emphasis>RNDIS</emphasis>
-protocol has been contributed by Pengutronix and Auerswald GmbH.
-This is like CDC Ethernet, but it runs on more slightly USB hardware
-(but less than the CDC subset).
-However, its main claim to fame is being able to connect directly to
-recent versions of Windows, using drivers that Microsoft bundles
-and supports, making it much simpler to network with Windows.
-</para>
-
-<para>There is also support for user mode gadget drivers,
-using <emphasis>gadgetfs</emphasis>.
-This provides a <emphasis>User Mode API</emphasis> that presents
-each endpoint as a single file descriptor. I/O is done using
-normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls.
-Familiar tools like GDB and pthreads can be used to
-develop and debug user mode drivers, so that once a robust
-controller driver is available many applications for it
-won't require new kernel mode software.
-Linux 2.6 <emphasis>Async I/O (AIO)</emphasis>
-support is available, so that user mode software
-can stream data with only slightly more overhead
-than a kernel driver.
-</para>
-
-<para>There's a USB Mass Storage class driver, which provides
-a different solution for interoperability with systems such
-as MS-Windows and MacOS.
-That <emphasis>Mass Storage</emphasis> driver uses a
-file or block device as backing store for a drive,
-like the <filename>loop</filename> driver.
-The USB host uses the BBB, CB, or CBI versions of the mass
-storage class specification, using transparent SCSI commands
-to access the data from the backing store.
-</para>
-
-<para>There's a "serial line" driver, useful for TTY style
-operation over USB.
-The latest version of that driver supports CDC ACM style
-operation, like a USB modem, and so on most hardware it can
-interoperate easily with MS-Windows.
-One interesting use of that driver is in boot firmware (like a BIOS),
-which can sometimes use that model with very small systems without
-real serial lines.
-</para>
-
-<para>Support for other kinds of gadget is expected to
-be developed and contributed
-over time, as this driver framework evolves.
-</para>
-
-</chapter>
-
-<chapter id="otg"><title>USB On-The-GO (OTG)</title>
-
-<para>USB OTG support on Linux 2.6 was initially developed
-by Texas Instruments for
-<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx
-series processors.
-Other OTG systems should work in similar ways, but the
-hardware level details could be very different.
-</para>
-
-<para>Systems need specialized hardware support to implement OTG,
-notably including a special <emphasis>Mini-AB</emphasis> jack
-and associated transceiver to support <emphasis>Dual-Role</emphasis>
-operation:
-they can act either as a host, using the standard
-Linux-USB host side driver stack,
-or as a peripheral, using this "gadget" framework.
-To do that, the system software relies on small additions
-to those programming interfaces,
-and on a new internal component (here called an "OTG Controller")
-affecting which driver stack connects to the OTG port.
-In each role, the system can re-use the existing pool of
-hardware-neutral drivers, layered on top of the controller
-driver interfaces (<emphasis>usb_bus</emphasis> or
-<emphasis>usb_gadget</emphasis>).
-Such drivers need at most minor changes, and most of the calls
-added to support OTG can also benefit non-OTG products.
-</para>
-
-<itemizedlist>
- <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis>
- flag, and use it to determine whether or not to include
- an OTG descriptor in each of their configurations.
- </para></listitem>
- <listitem><para>Gadget drivers may need changes to support the
- two new OTG protocols, exposed in new gadget attributes
- such as <emphasis>b_hnp_enable</emphasis> flag.
- HNP support should be reported through a user interface
- (two LEDs could suffice), and is triggered in some cases
- when the host suspends the peripheral.
- SRP support can be user-initiated just like remote wakeup,
- probably by pressing the same button.
- </para></listitem>
- <listitem><para>On the host side, USB device drivers need
- to be taught to trigger HNP at appropriate moments, using
- <function>usb_suspend_device()</function>.
- That also conserves battery power, which is useful even
- for non-OTG configurations.
- </para></listitem>
- <listitem><para>Also on the host side, a driver must support the
- OTG "Targeted Peripheral List". That's just a whitelist,
- used to reject peripherals not supported with a given
- Linux OTG host.
- <emphasis>This whitelist is product-specific;
- each product must modify <filename>otg_whitelist.h</filename>
- to match its interoperability specification.
- </emphasis>
- </para>
- <para>Non-OTG Linux hosts, like PCs and workstations,
- normally have some solution for adding drivers, so that
- peripherals that aren't recognized can eventually be supported.
- That approach is unreasonable for consumer products that may
- never have their firmware upgraded, and where it's usually
- unrealistic to expect traditional PC/workstation/server kinds
- of support model to work.
- For example, it's often impractical to change device firmware
- once the product has been distributed, so driver bugs can't
- normally be fixed if they're found after shipment.
- </para></listitem>
-</itemizedlist>
-
-<para>
-Additional changes are needed below those hardware-neutral
-<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis>
-driver interfaces; those aren't discussed here in any detail.
-Those affect the hardware-specific code for each USB Host or Peripheral
-controller, and how the HCD initializes (since OTG can be active only
-on a single port).
-They also involve what may be called an <emphasis>OTG Controller
-Driver</emphasis>, managing the OTG transceiver and the OTG state
-machine logic as well as much of the root hub behavior for the
-OTG port.
-The OTG controller driver needs to activate and deactivate USB
-controllers depending on the relevant device role.
-Some related changes were needed inside usbcore, so that it
-can identify OTG-capable devices and respond appropriately
-to HNP or SRP protocols.
-</para>
-
-</chapter>
-
-</book>
-<!--
- vim:syntax=sgml:sw=4
--->
diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl
deleted file mode 100644
index 59fb5c077541..000000000000
--- a/Documentation/DocBook/genericirq.tmpl
+++ /dev/null
@@ -1,520 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Generic-IRQ-Guide">
- <bookinfo>
- <title>Linux generic IRQ handling</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Ingo</firstname>
- <surname>Molnar</surname>
- <affiliation>
- <address>
- <email>mingo@elte.hu</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2005-2010</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
- <copyright>
- <year>2005-2006</year>
- <holder>Ingo Molnar</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The generic interrupt handling layer is designed to provide a
- complete abstraction of interrupt handling for device drivers.
- It is able to handle all the different types of interrupt controller
- hardware. Device drivers use generic API functions to request, enable,
- disable and free interrupts. The drivers do not have to know anything
- about interrupt hardware details, so they can be used on different
- platforms without code changes.
- </para>
- <para>
- This documentation is provided to developers who want to implement
- an interrupt subsystem based for their architecture, with the help
- of the generic IRQ handling layer.
- </para>
- </chapter>
-
- <chapter id="rationale">
- <title>Rationale</title>
- <para>
- The original implementation of interrupt handling in Linux uses
- the __do_IRQ() super-handler, which is able to deal with every
- type of interrupt logic.
- </para>
- <para>
- Originally, Russell King identified different types of handlers to
- build a quite universal set for the ARM interrupt handler
- implementation in Linux 2.5/2.6. He distinguished between:
- <itemizedlist>
- <listitem><para>Level type</para></listitem>
- <listitem><para>Edge type</para></listitem>
- <listitem><para>Simple type</para></listitem>
- </itemizedlist>
- During the implementation we identified another type:
- <itemizedlist>
- <listitem><para>Fast EOI type</para></listitem>
- </itemizedlist>
- In the SMP world of the __do_IRQ() super-handler another type
- was identified:
- <itemizedlist>
- <listitem><para>Per CPU type</para></listitem>
- </itemizedlist>
- </para>
- <para>
- This split implementation of high-level IRQ handlers allows us to
- optimize the flow of the interrupt handling for each specific
- interrupt type. This reduces complexity in that particular code path
- and allows the optimized handling of a given type.
- </para>
- <para>
- The original general IRQ implementation used hw_interrupt_type
- structures and their ->ack(), ->end() [etc.] callbacks to
- differentiate the flow control in the super-handler. This leads to
- a mix of flow logic and low-level hardware logic, and it also leads
- to unnecessary code duplication: for example in i386, there is an
- ioapic_level_irq and an ioapic_edge_irq IRQ-type which share many
- of the low-level details but have different flow handling.
- </para>
- <para>
- A more natural abstraction is the clean separation of the
- 'irq flow' and the 'chip details'.
- </para>
- <para>
- Analysing a couple of architecture's IRQ subsystem implementations
- reveals that most of them can use a generic set of 'irq flow'
- methods and only need to add the chip-level specific code.
- The separation is also valuable for (sub)architectures
- which need specific quirks in the IRQ flow itself but not in the
- chip details - and thus provides a more transparent IRQ subsystem
- design.
- </para>
- <para>
- Each interrupt descriptor is assigned its own high-level flow
- handler, which is normally one of the generic
- implementations. (This high-level flow handler implementation also
- makes it simple to provide demultiplexing handlers which can be
- found in embedded platforms on various architectures.)
- </para>
- <para>
- The separation makes the generic interrupt handling layer more
- flexible and extensible. For example, an (sub)architecture can
- use a generic IRQ-flow implementation for 'level type' interrupts
- and add a (sub)architecture specific 'edge type' implementation.
- </para>
- <para>
- To make the transition to the new model easier and prevent the
- breakage of existing implementations, the __do_IRQ() super-handler
- is still available. This leads to a kind of duality for the time
- being. Over time the new model should be used in more and more
- architectures, as it enables smaller and cleaner IRQ subsystems.
- It's deprecated for three years now and about to be removed.
- </para>
- </chapter>
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None (knock on wood).
- </para>
- </chapter>
-
- <chapter id="Abstraction">
- <title>Abstraction layers</title>
- <para>
- There are three main levels of abstraction in the interrupt code:
- <orderedlist>
- <listitem><para>High-level driver API</para></listitem>
- <listitem><para>High-level IRQ flow handlers</para></listitem>
- <listitem><para>Chip-level hardware encapsulation</para></listitem>
- </orderedlist>
- </para>
- <sect1 id="Interrupt_control_flow">
- <title>Interrupt control flow</title>
- <para>
- Each interrupt is described by an interrupt descriptor structure
- irq_desc. The interrupt is referenced by an 'unsigned int' numeric
- value which selects the corresponding interrupt description structure
- in the descriptor structures array.
- The descriptor structure contains status information and pointers
- to the interrupt flow method and the interrupt chip structure
- which are assigned to this interrupt.
- </para>
- <para>
- Whenever an interrupt triggers, the low-level architecture code calls
- into the generic interrupt code by calling desc->handle_irq().
- This high-level IRQ handling function only uses desc->irq_data.chip
- primitives referenced by the assigned chip descriptor structure.
- </para>
- </sect1>
- <sect1 id="Highlevel_Driver_API">
- <title>High-level Driver API</title>
- <para>
- The high-level Driver API consists of following functions:
- <itemizedlist>
- <listitem><para>request_irq()</para></listitem>
- <listitem><para>free_irq()</para></listitem>
- <listitem><para>disable_irq()</para></listitem>
- <listitem><para>enable_irq()</para></listitem>
- <listitem><para>disable_irq_nosync() (SMP only)</para></listitem>
- <listitem><para>synchronize_irq() (SMP only)</para></listitem>
- <listitem><para>irq_set_irq_type()</para></listitem>
- <listitem><para>irq_set_irq_wake()</para></listitem>
- <listitem><para>irq_set_handler_data()</para></listitem>
- <listitem><para>irq_set_chip()</para></listitem>
- <listitem><para>irq_set_chip_data()</para></listitem>
- </itemizedlist>
- See the autogenerated function documentation for details.
- </para>
- </sect1>
- <sect1 id="Highlevel_IRQ_flow_handlers">
- <title>High-level IRQ flow handlers</title>
- <para>
- The generic layer provides a set of pre-defined irq-flow methods:
- <itemizedlist>
- <listitem><para>handle_level_irq</para></listitem>
- <listitem><para>handle_edge_irq</para></listitem>
- <listitem><para>handle_fasteoi_irq</para></listitem>
- <listitem><para>handle_simple_irq</para></listitem>
- <listitem><para>handle_percpu_irq</para></listitem>
- <listitem><para>handle_edge_eoi_irq</para></listitem>
- <listitem><para>handle_bad_irq</para></listitem>
- </itemizedlist>
- The interrupt flow handlers (either pre-defined or architecture
- specific) are assigned to specific interrupts by the architecture
- either during bootup or during device initialization.
- </para>
- <sect2 id="Default_flow_implementations">
- <title>Default flow implementations</title>
- <sect3 id="Helper_functions">
- <title>Helper functions</title>
- <para>
- The helper functions call the chip primitives and
- are used by the default flow implementations.
- The following helper functions are implemented (simplified excerpt):
- <programlisting>
-default_enable(struct irq_data *data)
-{
- desc->irq_data.chip->irq_unmask(data);
-}
-
-default_disable(struct irq_data *data)
-{
- if (!delay_disable(data))
- desc->irq_data.chip->irq_mask(data);
-}
-
-default_ack(struct irq_data *data)
-{
- chip->irq_ack(data);
-}
-
-default_mask_ack(struct irq_data *data)
-{
- if (chip->irq_mask_ack) {
- chip->irq_mask_ack(data);
- } else {
- chip->irq_mask(data);
- chip->irq_ack(data);
- }
-}
-
-noop(struct irq_data *data))
-{
-}
-
- </programlisting>
- </para>
- </sect3>
- </sect2>
- <sect2 id="Default_flow_handler_implementations">
- <title>Default flow handler implementations</title>
- <sect3 id="Default_Level_IRQ_flow_handler">
- <title>Default Level IRQ flow handler</title>
- <para>
- handle_level_irq provides a generic implementation
- for level-triggered interrupts.
- </para>
- <para>
- The following control flow is implemented (simplified excerpt):
- <programlisting>
-desc->irq_data.chip->irq_mask_ack();
-handle_irq_event(desc->action);
-desc->irq_data.chip->irq_unmask();
- </programlisting>
- </para>
- </sect3>
- <sect3 id="Default_FASTEOI_IRQ_flow_handler">
- <title>Default Fast EOI IRQ flow handler</title>
- <para>
- handle_fasteoi_irq provides a generic implementation
- for interrupts, which only need an EOI at the end of
- the handler.
- </para>
- <para>
- The following control flow is implemented (simplified excerpt):
- <programlisting>
-handle_irq_event(desc->action);
-desc->irq_data.chip->irq_eoi();
- </programlisting>
- </para>
- </sect3>
- <sect3 id="Default_Edge_IRQ_flow_handler">
- <title>Default Edge IRQ flow handler</title>
- <para>
- handle_edge_irq provides a generic implementation
- for edge-triggered interrupts.
- </para>
- <para>
- The following control flow is implemented (simplified excerpt):
- <programlisting>
-if (desc->status &amp; running) {
- desc->irq_data.chip->irq_mask_ack();
- desc->status |= pending | masked;
- return;
-}
-desc->irq_data.chip->irq_ack();
-desc->status |= running;
-do {
- if (desc->status &amp; masked)
- desc->irq_data.chip->irq_unmask();
- desc->status &amp;= ~pending;
- handle_irq_event(desc->action);
-} while (status &amp; pending);
-desc->status &amp;= ~running;
- </programlisting>
- </para>
- </sect3>
- <sect3 id="Default_simple_IRQ_flow_handler">
- <title>Default simple IRQ flow handler</title>
- <para>
- handle_simple_irq provides a generic implementation
- for simple interrupts.
- </para>
- <para>
- Note: The simple flow handler does not call any
- handler/chip primitives.
- </para>
- <para>
- The following control flow is implemented (simplified excerpt):
- <programlisting>
-handle_irq_event(desc->action);
- </programlisting>
- </para>
- </sect3>
- <sect3 id="Default_per_CPU_flow_handler">
- <title>Default per CPU flow handler</title>
- <para>
- handle_percpu_irq provides a generic implementation
- for per CPU interrupts.
- </para>
- <para>
- Per CPU interrupts are only available on SMP and
- the handler provides a simplified version without
- locking.
- </para>
- <para>
- The following control flow is implemented (simplified excerpt):
- <programlisting>
-if (desc->irq_data.chip->irq_ack)
- desc->irq_data.chip->irq_ack();
-handle_irq_event(desc->action);
-if (desc->irq_data.chip->irq_eoi)
- desc->irq_data.chip->irq_eoi();
- </programlisting>
- </para>
- </sect3>
- <sect3 id="EOI_Edge_IRQ_flow_handler">
- <title>EOI Edge IRQ flow handler</title>
- <para>
- handle_edge_eoi_irq provides an abnomination of the edge
- handler which is solely used to tame a badly wreckaged
- irq controller on powerpc/cell.
- </para>
- </sect3>
- <sect3 id="BAD_IRQ_flow_handler">
- <title>Bad IRQ flow handler</title>
- <para>
- handle_bad_irq is used for spurious interrupts which
- have no real handler assigned..
- </para>
- </sect3>
- </sect2>
- <sect2 id="Quirks_and_optimizations">
- <title>Quirks and optimizations</title>
- <para>
- The generic functions are intended for 'clean' architectures and chips,
- which have no platform-specific IRQ handling quirks. If an architecture
- needs to implement quirks on the 'flow' level then it can do so by
- overriding the high-level irq-flow handler.
- </para>
- </sect2>
- <sect2 id="Delayed_interrupt_disable">
- <title>Delayed interrupt disable</title>
- <para>
- This per interrupt selectable feature, which was introduced by Russell
- King in the ARM interrupt implementation, does not mask an interrupt
- at the hardware level when disable_irq() is called. The interrupt is
- kept enabled and is masked in the flow handler when an interrupt event
- happens. This prevents losing edge interrupts on hardware which does
- not store an edge interrupt event while the interrupt is disabled at
- the hardware level. When an interrupt arrives while the IRQ_DISABLED
- flag is set, then the interrupt is masked at the hardware level and
- the IRQ_PENDING bit is set. When the interrupt is re-enabled by
- enable_irq() the pending bit is checked and if it is set, the
- interrupt is resent either via hardware or by a software resend
- mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when
- you want to use the delayed interrupt disable feature and your
- hardware is not capable of retriggering an interrupt.)
- The delayed interrupt disable is not configurable.
- </para>
- </sect2>
- </sect1>
- <sect1 id="Chiplevel_hardware_encapsulation">
- <title>Chip-level hardware encapsulation</title>
- <para>
- The chip-level hardware descriptor structure irq_chip
- contains all the direct chip relevant functions, which
- can be utilized by the irq flow implementations.
- <itemizedlist>
- <listitem><para>irq_ack()</para></listitem>
- <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem>
- <listitem><para>irq_mask()</para></listitem>
- <listitem><para>irq_unmask()</para></listitem>
- <listitem><para>irq_eoi() - Optional, required for EOI flow handlers</para></listitem>
- <listitem><para>irq_retrigger() - Optional</para></listitem>
- <listitem><para>irq_set_type() - Optional</para></listitem>
- <listitem><para>irq_set_wake() - Optional</para></listitem>
- </itemizedlist>
- These primitives are strictly intended to mean what they say: ack means
- ACK, masking means masking of an IRQ line, etc. It is up to the flow
- handler(s) to use these basic units of low-level functionality.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="doirq">
- <title>__do_IRQ entry point</title>
- <para>
- The original implementation __do_IRQ() was an alternative entry
- point for all types of interrupts. It no longer exists.
- </para>
- <para>
- This handler turned out to be not suitable for all
- interrupt hardware and was therefore reimplemented with split
- functionality for edge/level/simple/percpu interrupts. This is not
- only a functional optimization. It also shortens code paths for
- interrupts.
- </para>
- </chapter>
-
- <chapter id="locking">
- <title>Locking on SMP</title>
- <para>
- The locking of chip registers is up to the architecture that
- defines the chip primitives. The per-irq structure is
- protected via desc->lock, by the generic layer.
- </para>
- </chapter>
-
- <chapter id="genericchip">
- <title>Generic interrupt chip</title>
- <para>
- To avoid copies of identical implementations of IRQ chips the
- core provides a configurable generic interrupt chip
- implementation. Developers should check carefully whether the
- generic chip fits their needs before implementing the same
- functionality slightly differently themselves.
- </para>
-!Ekernel/irq/generic-chip.c
- </chapter>
-
- <chapter id="structs">
- <title>Structures</title>
- <para>
- This chapter contains the autogenerated documentation of the structures which are
- used in the generic IRQ layer.
- </para>
-!Iinclude/linux/irq.h
-!Iinclude/linux/interrupt.h
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the kernel API functions
- which are exported.
- </para>
-!Ekernel/irq/manage.c
-!Ekernel/irq/chip.c
- </chapter>
-
- <chapter id="intfunctions">
- <title>Internal Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the internal functions.
- </para>
-!Ikernel/irq/irqdesc.c
-!Ikernel/irq/handle.c
-!Ikernel/irq/chip.c
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The following people have contributed to this document:
- <orderedlist>
- <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
- <listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem>
- </orderedlist>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
deleted file mode 100644
index ecfd0ea40661..000000000000
--- a/Documentation/DocBook/kernel-api.tmpl
+++ /dev/null
@@ -1,331 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="LinuxKernelAPI">
- <bookinfo>
- <title>The Linux Kernel API</title>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="adt">
- <title>Data Types</title>
- <sect1><title>Doubly Linked Lists</title>
-!Iinclude/linux/list.h
- </sect1>
- </chapter>
-
- <chapter id="libc">
- <title>Basic C Library Functions</title>
-
- <para>
- When writing drivers, you cannot in general use routines which are
- from the C Library. Some of the functions have been found generally
- useful and they are listed below. The behaviour of these functions
- may vary slightly from those defined by ANSI, and these deviations
- are noted in the text.
- </para>
-
- <sect1><title>String Conversions</title>
-!Elib/vsprintf.c
-!Finclude/linux/kernel.h kstrtol
-!Finclude/linux/kernel.h kstrtoul
-!Elib/kstrtox.c
- </sect1>
- <sect1><title>String Manipulation</title>
-<!-- All functions are exported at now
-X!Ilib/string.c
- -->
-!Elib/string.c
- </sect1>
- <sect1><title>Bit Operations</title>
-!Iarch/x86/include/asm/bitops.h
- </sect1>
- </chapter>
-
- <chapter id="kernel-lib">
- <title>Basic Kernel Library Functions</title>
-
- <para>
- The Linux kernel provides more basic utility functions.
- </para>
-
- <sect1><title>Bitmap Operations</title>
-!Elib/bitmap.c
-!Ilib/bitmap.c
- </sect1>
-
- <sect1><title>Command-line Parsing</title>
-!Elib/cmdline.c
- </sect1>
-
- <sect1 id="crc"><title>CRC Functions</title>
-!Elib/crc7.c
-!Elib/crc16.c
-!Elib/crc-itu-t.c
-!Elib/crc32.c
-!Elib/crc-ccitt.c
- </sect1>
-
- <sect1 id="idr"><title>idr/ida Functions</title>
-!Pinclude/linux/idr.h idr sync
-!Plib/idr.c IDA description
-!Elib/idr.c
- </sect1>
- </chapter>
-
- <chapter id="mm">
- <title>Memory Management in Linux</title>
- <sect1><title>The Slab Cache</title>
-!Iinclude/linux/slab.h
-!Emm/slab.c
-!Emm/util.c
- </sect1>
- <sect1><title>User Space Memory Access</title>
-!Iarch/x86/include/asm/uaccess_32.h
-!Earch/x86/lib/usercopy_32.c
- </sect1>
- <sect1><title>More Memory Management Functions</title>
-!Emm/readahead.c
-!Emm/filemap.c
-!Emm/memory.c
-!Emm/vmalloc.c
-!Imm/page_alloc.c
-!Emm/mempool.c
-!Emm/dmapool.c
-!Emm/page-writeback.c
-!Emm/truncate.c
- </sect1>
- </chapter>
-
-
- <chapter id="ipc">
- <title>Kernel IPC facilities</title>
-
- <sect1><title>IPC utilities</title>
-!Iipc/util.c
- </sect1>
- </chapter>
-
- <chapter id="kfifo">
- <title>FIFO Buffer</title>
- <sect1><title>kfifo interface</title>
-!Iinclude/linux/kfifo.h
- </sect1>
- </chapter>
-
- <chapter id="relayfs">
- <title>relay interface support</title>
-
- <para>
- Relay interface support
- is designed to provide an efficient mechanism for tools and
- facilities to relay large amounts of data from kernel space to
- user space.
- </para>
-
- <sect1><title>relay interface</title>
-!Ekernel/relay.c
-!Ikernel/relay.c
- </sect1>
- </chapter>
-
- <chapter id="modload">
- <title>Module Support</title>
- <sect1><title>Module Loading</title>
-!Ekernel/kmod.c
- </sect1>
- <sect1><title>Inter Module support</title>
- <para>
- Refer to the file kernel/module.c for more information.
- </para>
-<!-- FIXME: Removed for now since no structured comments in source
-X!Ekernel/module.c
--->
- </sect1>
- </chapter>
-
- <chapter id="hardware">
- <title>Hardware Interfaces</title>
- <sect1><title>Interrupt Handling</title>
-!Ekernel/irq/manage.c
- </sect1>
-
- <sect1><title>DMA Channels</title>
-!Ekernel/dma.c
- </sect1>
-
- <sect1><title>Resources Management</title>
-!Ikernel/resource.c
-!Ekernel/resource.c
- </sect1>
-
- <sect1><title>MTRR Handling</title>
-!Earch/x86/kernel/cpu/mtrr/main.c
- </sect1>
-
- <sect1><title>PCI Support Library</title>
-!Edrivers/pci/pci.c
-!Edrivers/pci/pci-driver.c
-!Edrivers/pci/remove.c
-!Edrivers/pci/search.c
-!Edrivers/pci/msi.c
-!Edrivers/pci/bus.c
-!Edrivers/pci/access.c
-!Edrivers/pci/irq.c
-!Edrivers/pci/htirq.c
-<!-- FIXME: Removed for now since no structured comments in source
-X!Edrivers/pci/hotplug.c
--->
-!Edrivers/pci/probe.c
-!Edrivers/pci/slot.c
-!Edrivers/pci/rom.c
-!Edrivers/pci/iov.c
-!Idrivers/pci/pci-sysfs.c
- </sect1>
- <sect1><title>PCI Hotplug Support Library</title>
-!Edrivers/pci/hotplug/pci_hotplug_core.c
- </sect1>
- </chapter>
-
- <chapter id="firmware">
- <title>Firmware Interfaces</title>
- <sect1><title>DMI Interfaces</title>
-!Edrivers/firmware/dmi_scan.c
- </sect1>
- <sect1><title>EDD Interfaces</title>
-!Idrivers/firmware/edd.c
- </sect1>
- </chapter>
-
- <chapter id="security">
- <title>Security Framework</title>
-!Isecurity/security.c
-!Esecurity/inode.c
- </chapter>
-
- <chapter id="audit">
- <title>Audit Interfaces</title>
-!Ekernel/audit.c
-!Ikernel/auditsc.c
-!Ikernel/auditfilter.c
- </chapter>
-
- <chapter id="accounting">
- <title>Accounting Framework</title>
-!Ikernel/acct.c
- </chapter>
-
- <chapter id="blkdev">
- <title>Block Devices</title>
-!Eblock/blk-core.c
-!Iblock/blk-core.c
-!Eblock/blk-map.c
-!Iblock/blk-sysfs.c
-!Eblock/blk-settings.c
-!Eblock/blk-exec.c
-!Eblock/blk-flush.c
-!Eblock/blk-lib.c
-!Eblock/blk-tag.c
-!Iblock/blk-tag.c
-!Eblock/blk-integrity.c
-!Ikernel/trace/blktrace.c
-!Iblock/genhd.c
-!Eblock/genhd.c
- </chapter>
-
- <chapter id="chrdev">
- <title>Char devices</title>
-!Efs/char_dev.c
- </chapter>
-
- <chapter id="miscdev">
- <title>Miscellaneous Devices</title>
-!Edrivers/char/misc.c
- </chapter>
-
- <chapter id="clk">
- <title>Clock Framework</title>
-
- <para>
- The clock framework defines programming interfaces to support
- software management of the system clock tree.
- This framework is widely used with System-On-Chip (SOC) platforms
- to support power management and various devices which may need
- custom clock rates.
- Note that these "clocks" don't relate to timekeeping or real
- time clocks (RTCs), each of which have separate frameworks.
- These <structname>struct clk</structname> instances may be used
- to manage for example a 96 MHz signal that is used to shift bits
- into and out of peripherals or busses, or otherwise trigger
- synchronous state machine transitions in system hardware.
- </para>
-
- <para>
- Power management is supported by explicit software clock gating:
- unused clocks are disabled, so the system doesn't waste power
- changing the state of transistors that aren't in active use.
- On some systems this may be backed by hardware clock gating,
- where clocks are gated without being disabled in software.
- Sections of chips that are powered but not clocked may be able
- to retain their last state.
- This low power state is often called a <emphasis>retention
- mode</emphasis>.
- This mode still incurs leakage currents, especially with finer
- circuit geometries, but for CMOS circuits power is mostly used
- by clocked state changes.
- </para>
-
- <para>
- Power-aware drivers only enable their clocks when the device
- they manage is in active use. Also, system sleep states often
- differ according to which clock domains are active: while a
- "standby" state may allow wakeup from several active domains, a
- "mem" (suspend-to-RAM) state may require a more wholesale shutdown
- of clocks derived from higher speed PLLs and oscillators, limiting
- the number of possible wakeup event sources. A driver's suspend
- method may need to be aware of system-specific clock constraints
- on the target sleep state.
- </para>
-
- <para>
- Some platforms support programmable clock generators. These
- can be used by external chips of various kinds, such as other
- CPUs, multimedia codecs, and devices with strict requirements
- for interface clocking.
- </para>
-
-!Iinclude/linux/clk.h
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
deleted file mode 100644
index e84f09467cd7..000000000000
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ /dev/null
@@ -1,1310 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="lk-hacking-guide">
- <bookinfo>
- <title>Unreliable Guide To Hacking The Linux Kernel</title>
-
- <authorgroup>
- <author>
- <firstname>Rusty</firstname>
- <surname>Russell</surname>
- <affiliation>
- <address>
- <email>rusty@rustcorp.com.au</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2005</year>
- <holder>Rusty Russell</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
-
- <releaseinfo>
- This is the first release of this document as part of the kernel tarball.
- </releaseinfo>
-
- </bookinfo>
-
- <toc></toc>
-
- <chapter id="introduction">
- <title>Introduction</title>
- <para>
- Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux
- Kernel Hacking. This document describes the common routines and
- general requirements for kernel code: its goal is to serve as a
- primer for Linux kernel development for experienced C
- programmers. I avoid implementation details: that's what the
- code is for, and I ignore whole tracts of useful routines.
- </para>
- <para>
- Before you read this, please understand that I never wanted to
- write this document, being grossly under-qualified, but I always
- wanted to read it, and this was the only way. I hope it will
- grow into a compendium of best practice, common starting points
- and random information.
- </para>
- </chapter>
-
- <chapter id="basic-players">
- <title>The Players</title>
-
- <para>
- At any time each of the CPUs in a system can be:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- not associated with any process, serving a hardware interrupt;
- </para>
- </listitem>
-
- <listitem>
- <para>
- not associated with any process, serving a softirq or tasklet;
- </para>
- </listitem>
-
- <listitem>
- <para>
- running in kernel space, associated with a process (user context);
- </para>
- </listitem>
-
- <listitem>
- <para>
- running a process in user space.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- There is an ordering between these. The bottom two can preempt
- each other, but above that is a strict hierarchy: each can only be
- preempted by the ones above it. For example, while a softirq is
- running on a CPU, no other softirq will preempt it, but a hardware
- interrupt can. However, any other CPUs in the system execute
- independently.
- </para>
-
- <para>
- We'll see a number of ways that the user context can block
- interrupts, to become truly non-preemptable.
- </para>
-
- <sect1 id="basics-usercontext">
- <title>User Context</title>
-
- <para>
- User context is when you are coming in from a system call or other
- trap: like userspace, you can be preempted by more important tasks
- and by interrupts. You can sleep, by calling
- <function>schedule()</function>.
- </para>
-
- <note>
- <para>
- You are always in user context on module load and unload,
- and on operations on the block device layer.
- </para>
- </note>
-
- <para>
- In user context, the <varname>current</varname> pointer (indicating
- the task we are currently executing) is valid, and
- <function>in_interrupt()</function>
- (<filename>include/linux/interrupt.h</filename>) is <returnvalue>false
- </returnvalue>.
- </para>
-
- <caution>
- <para>
- Beware that if you have preemption or softirqs disabled
- (see below), <function>in_interrupt()</function> will return a
- false positive.
- </para>
- </caution>
- </sect1>
-
- <sect1 id="basics-hardirqs">
- <title>Hardware Interrupts (Hard IRQs)</title>
-
- <para>
- Timer ticks, <hardware>network cards</hardware> and
- <hardware>keyboard</hardware> are examples of real
- hardware which produce interrupts at any time. The kernel runs
- interrupt handlers, which services the hardware. The kernel
- guarantees that this handler is never re-entered: if the same
- interrupt arrives, it is queued (or dropped). Because it
- disables interrupts, this handler has to be fast: frequently it
- simply acknowledges the interrupt, marks a 'software interrupt'
- for execution and exits.
- </para>
-
- <para>
- You can tell you are in a hardware interrupt, because
- <function>in_irq()</function> returns <returnvalue>true</returnvalue>.
- </para>
- <caution>
- <para>
- Beware that this will return a false positive if interrupts are disabled
- (see below).
- </para>
- </caution>
- </sect1>
-
- <sect1 id="basics-softirqs">
- <title>Software Interrupt Context: Softirqs and Tasklets</title>
-
- <para>
- Whenever a system call is about to return to userspace, or a
- hardware interrupt handler exits, any 'software interrupts'
- which are marked pending (usually by hardware interrupts) are
- run (<filename>kernel/softirq.c</filename>).
- </para>
-
- <para>
- Much of the real interrupt handling work is done here. Early in
- the transition to <acronym>SMP</acronym>, there were only 'bottom
- halves' (BHs), which didn't take advantage of multiple CPUs. Shortly
- after we switched from wind-up computers made of match-sticks and snot,
- we abandoned this limitation and switched to 'softirqs'.
- </para>
-
- <para>
- <filename class="headerfile">include/linux/interrupt.h</filename> lists the
- different softirqs. A very important softirq is the
- timer softirq (<filename
- class="headerfile">include/linux/timer.h</filename>): you can
- register to have it call functions for you in a given length of
- time.
- </para>
-
- <para>
- Softirqs are often a pain to deal with, since the same softirq
- will run simultaneously on more than one CPU. For this reason,
- tasklets (<filename
- class="headerfile">include/linux/interrupt.h</filename>) are more
- often used: they are dynamically-registrable (meaning you can have
- as many as you want), and they also guarantee that any tasklet
- will only run on one CPU at any time, although different tasklets
- can run simultaneously.
- </para>
- <caution>
- <para>
- The name 'tasklet' is misleading: they have nothing to do with 'tasks',
- and probably more to do with some bad vodka Alexey Kuznetsov had at the
- time.
- </para>
- </caution>
-
- <para>
- You can tell you are in a softirq (or tasklet)
- using the <function>in_softirq()</function> macro
- (<filename class="headerfile">include/linux/interrupt.h</filename>).
- </para>
- <caution>
- <para>
- Beware that this will return a false positive if a bh lock (see below)
- is held.
- </para>
- </caution>
- </sect1>
- </chapter>
-
- <chapter id="basic-rules">
- <title>Some Basic Rules</title>
-
- <variablelist>
- <varlistentry>
- <term>No memory protection</term>
- <listitem>
- <para>
- If you corrupt memory, whether in user context or
- interrupt context, the whole machine will crash. Are you
- sure you can't do what you want in userspace?
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>No floating point or <acronym>MMX</acronym></term>
- <listitem>
- <para>
- The <acronym>FPU</acronym> context is not saved; even in user
- context the <acronym>FPU</acronym> state probably won't
- correspond with the current process: you would mess with some
- user process' <acronym>FPU</acronym> state. If you really want
- to do this, you would have to explicitly save/restore the full
- <acronym>FPU</acronym> state (and avoid context switches). It
- is generally a bad idea; use fixed point arithmetic first.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A rigid stack limit</term>
- <listitem>
- <para>
- Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's
- about 14K on most 64-bit archs, and often shared with interrupts
- so you can't use it all. Avoid deep recursion and huge local
- arrays on the stack (allocate them dynamically instead).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>The Linux kernel is portable</term>
- <listitem>
- <para>
- Let's keep it that way. Your code should be 64-bit clean,
- and endian-independent. You should also minimize CPU
- specific stuff, e.g. inline assembly should be cleanly
- encapsulated and minimized to ease porting. Generally it
- should be restricted to the architecture-dependent part of
- the kernel tree.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </chapter>
-
- <chapter id="ioctls">
- <title>ioctls: Not writing a new system call</title>
-
- <para>
- A system call generally looks like this
- </para>
-
- <programlisting>
-asmlinkage long sys_mycall(int arg)
-{
- return 0;
-}
- </programlisting>
-
- <para>
- First, in most cases you don't want to create a new system call.
- You create a character device and implement an appropriate ioctl
- for it. This is much more flexible than system calls, doesn't have
- to be entered in every architecture's
- <filename class="headerfile">include/asm/unistd.h</filename> and
- <filename>arch/kernel/entry.S</filename> file, and is much more
- likely to be accepted by Linus.
- </para>
-
- <para>
- If all your routine does is read or write some parameter, consider
- implementing a <function>sysfs</function> interface instead.
- </para>
-
- <para>
- Inside the ioctl you're in user context to a process. When a
- error occurs you return a negated errno (see
- <filename class="headerfile">include/linux/errno.h</filename>),
- otherwise you return <returnvalue>0</returnvalue>.
- </para>
-
- <para>
- After you slept you should check if a signal occurred: the
- Unix/Linux way of handling signals is to temporarily exit the
- system call with the <constant>-ERESTARTSYS</constant> error. The
- system call entry code will switch back to user context, process
- the signal handler and then your system call will be restarted
- (unless the user disabled that). So you should be prepared to
- process the restart, e.g. if you're in the middle of manipulating
- some data structure.
- </para>
-
- <programlisting>
-if (signal_pending(current))
- return -ERESTARTSYS;
- </programlisting>
-
- <para>
- If you're doing longer computations: first think userspace. If you
- <emphasis>really</emphasis> want to do it in kernel you should
- regularly check if you need to give up the CPU (remember there is
- cooperative multitasking per CPU). Idiom:
- </para>
-
- <programlisting>
-cond_resched(); /* Will sleep */
- </programlisting>
-
- <para>
- A short note on interface design: the UNIX system call motto is
- "Provide mechanism not policy".
- </para>
- </chapter>
-
- <chapter id="deadlock-recipes">
- <title>Recipes for Deadlock</title>
-
- <para>
- You cannot call any routines which may sleep, unless:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- You are in user context.
- </para>
- </listitem>
-
- <listitem>
- <para>
- You do not own any spinlocks.
- </para>
- </listitem>
-
- <listitem>
- <para>
- You have interrupts enabled (actually, Andi Kleen says
- that the scheduling code will enable them for you, but
- that's probably not what you wanted).
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Note that some functions may sleep implicitly: common ones are
- the user space access functions (*_user) and memory allocation
- functions without <symbol>GFP_ATOMIC</symbol>.
- </para>
-
- <para>
- You should always compile your kernel
- <symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn
- you if you break these rules. If you <emphasis>do</emphasis> break
- the rules, you will eventually lock up your box.
- </para>
-
- <para>
- Really.
- </para>
- </chapter>
-
- <chapter id="common-routines">
- <title>Common Routines</title>
-
- <sect1 id="routines-printk">
- <title>
- <function>printk()</function>
- <filename class="headerfile">include/linux/kernel.h</filename>
- </title>
-
- <para>
- <function>printk()</function> feeds kernel messages to the
- console, dmesg, and the syslog daemon. It is useful for debugging
- and reporting errors, and can be used inside interrupt context,
- but use with caution: a machine which has its console flooded with
- printk messages is unusable. It uses a format string mostly
- compatible with ANSI C printf, and C string concatenation to give
- it a first "priority" argument:
- </para>
-
- <programlisting>
-printk(KERN_INFO "i = %u\n", i);
- </programlisting>
-
- <para>
- See <filename class="headerfile">include/linux/kernel.h</filename>;
- for other KERN_ values; these are interpreted by syslog as the
- level. Special case: for printing an IP address use
- </para>
-
- <programlisting>
-__be32 ipaddress;
-printk(KERN_INFO "my ip: %pI4\n", &amp;ipaddress);
- </programlisting>
-
- <para>
- <function>printk()</function> internally uses a 1K buffer and does
- not catch overruns. Make sure that will be enough.
- </para>
-
- <note>
- <para>
- You will know when you are a real kernel hacker
- when you start typoing printf as printk in your user programs :)
- </para>
- </note>
-
- <!--- From the Lions book reader department -->
-
- <note>
- <para>
- Another sidenote: the original Unix Version 6 sources had a
- comment on top of its printf function: "Printf should not be
- used for chit-chat". You should follow that advice.
- </para>
- </note>
- </sect1>
-
- <sect1 id="routines-copy">
- <title>
- <function>copy_[to/from]_user()</function>
- /
- <function>get_user()</function>
- /
- <function>put_user()</function>
- <filename class="headerfile">include/asm/uaccess.h</filename>
- </title>
-
- <para>
- <emphasis>[SLEEPS]</emphasis>
- </para>
-
- <para>
- <function>put_user()</function> and <function>get_user()</function>
- are used to get and put single values (such as an int, char, or
- long) from and to userspace. A pointer into userspace should
- never be simply dereferenced: data should be copied using these
- routines. Both return <constant>-EFAULT</constant> or 0.
- </para>
- <para>
- <function>copy_to_user()</function> and
- <function>copy_from_user()</function> are more general: they copy
- an arbitrary amount of data to and from userspace.
- <caution>
- <para>
- Unlike <function>put_user()</function> and
- <function>get_user()</function>, they return the amount of
- uncopied data (ie. <returnvalue>0</returnvalue> still means
- success).
- </para>
- </caution>
- [Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.]
- </para>
- <para>
- The functions may sleep implicitly. This should never be called
- outside user context (it makes no sense), with interrupts
- disabled, or a spinlock held.
- </para>
- </sect1>
-
- <sect1 id="routines-kmalloc">
- <title><function>kmalloc()</function>/<function>kfree()</function>
- <filename class="headerfile">include/linux/slab.h</filename></title>
-
- <para>
- <emphasis>[MAY SLEEP: SEE BELOW]</emphasis>
- </para>
-
- <para>
- These routines are used to dynamically request pointer-aligned
- chunks of memory, like malloc and free do in userspace, but
- <function>kmalloc()</function> takes an extra flag word.
- Important values:
- </para>
-
- <variablelist>
- <varlistentry>
- <term>
- <constant>
- GFP_KERNEL
- </constant>
- </term>
- <listitem>
- <para>
- May sleep and swap to free memory. Only allowed in user
- context, but is the most reliable way to allocate memory.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>
- GFP_ATOMIC
- </constant>
- </term>
- <listitem>
- <para>
- Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>,
- but may be called from interrupt context. You should
- <emphasis>really</emphasis> have a good out-of-memory
- error-handling strategy.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <constant>
- GFP_DMA
- </constant>
- </term>
- <listitem>
- <para>
- Allocate ISA DMA lower than 16MB. If you don't know what that
- is you don't need it. Very unreliable.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- If you see a <errorname>sleeping function called from invalid
- context</errorname> warning message, then maybe you called a
- sleeping allocation function from interrupt context without
- <constant>GFP_ATOMIC</constant>. You should really fix that.
- Run, don't walk.
- </para>
-
- <para>
- If you are allocating at least <constant>PAGE_SIZE</constant>
- (<filename class="headerfile">include/asm/page.h</filename>) bytes,
- consider using <function>__get_free_pages()</function>
-
- (<filename class="headerfile">include/linux/mm.h</filename>). It
- takes an order argument (0 for page sized, 1 for double page, 2
- for four pages etc.) and the same memory priority flag word as
- above.
- </para>
-
- <para>
- If you are allocating more than a page worth of bytes you can use
- <function>vmalloc()</function>. It'll allocate virtual memory in
- the kernel map. This block is not contiguous in physical memory,
- but the <acronym>MMU</acronym> makes it look like it is for you
- (so it'll only look contiguous to the CPUs, not to external device
- drivers). If you really need large physically contiguous memory
- for some weird device, you have a problem: it is poorly supported
- in Linux because after some time memory fragmentation in a running
- kernel makes it hard. The best way is to allocate the block early
- in the boot process via the <function>alloc_bootmem()</function>
- routine.
- </para>
-
- <para>
- Before inventing your own cache of often-used objects consider
- using a slab cache in
- <filename class="headerfile">include/linux/slab.h</filename>
- </para>
- </sect1>
-
- <sect1 id="routines-current">
- <title><function>current</function>
- <filename class="headerfile">include/asm/current.h</filename></title>
-
- <para>
- This global variable (really a macro) contains a pointer to
- the current task structure, so is only valid in user context.
- For example, when a process makes a system call, this will
- point to the task structure of the calling process. It is
- <emphasis>not NULL</emphasis> in interrupt context.
- </para>
- </sect1>
-
- <sect1 id="routines-udelay">
- <title><function>mdelay()</function>/<function>udelay()</function>
- <filename class="headerfile">include/asm/delay.h</filename>
- <filename class="headerfile">include/linux/delay.h</filename>
- </title>
-
- <para>
- The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses.
- Do not use large values with them as you risk
- overflow - the helper function <function>mdelay()</function> is useful
- here, or consider <function>msleep()</function>.
- </para>
- </sect1>
-
- <sect1 id="routines-endian">
- <title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function>
- <filename class="headerfile">include/asm/byteorder.h</filename>
- </title>
-
- <para>
- The <function>cpu_to_be32()</function> family (where the "32" can
- be replaced by 64 or 16, and the "be" can be replaced by "le") are
- the general way to do endian conversions in the kernel: they
- return the converted value. All variations supply the reverse as
- well: <function>be32_to_cpu()</function>, etc.
- </para>
-
- <para>
- There are two major variations of these functions: the pointer
- variation, such as <function>cpu_to_be32p()</function>, which take
- a pointer to the given type, and return the converted value. The
- other variation is the "in-situ" family, such as
- <function>cpu_to_be32s()</function>, which convert value referred
- to by the pointer, and return void.
- </para>
- </sect1>
-
- <sect1 id="routines-local-irqs">
- <title><function>local_irq_save()</function>/<function>local_irq_restore()</function>
- <filename class="headerfile">include/linux/irqflags.h</filename>
- </title>
-
- <para>
- These routines disable hard interrupts on the local CPU, and
- restore them. They are reentrant; saving the previous state in
- their one <varname>unsigned long flags</varname> argument. If you
- know that interrupts are enabled, you can simply use
- <function>local_irq_disable()</function> and
- <function>local_irq_enable()</function>.
- </para>
- </sect1>
-
- <sect1 id="routines-softirqs">
- <title><function>local_bh_disable()</function>/<function>local_bh_enable()</function>
- <filename class="headerfile">include/linux/interrupt.h</filename></title>
-
- <para>
- These routines disable soft interrupts on the local CPU, and
- restore them. They are reentrant; if soft interrupts were
- disabled before, they will still be disabled after this pair
- of functions has been called. They prevent softirqs and tasklets
- from running on the current CPU.
- </para>
- </sect1>
-
- <sect1 id="routines-processorids">
- <title><function>smp_processor_id</function>()
- <filename class="headerfile">include/asm/smp.h</filename></title>
-
- <para>
- <function>get_cpu()</function> disables preemption (so you won't
- suddenly get moved to another CPU) and returns the current
- processor number, between 0 and <symbol>NR_CPUS</symbol>. Note
- that the CPU numbers are not necessarily continuous. You return
- it again with <function>put_cpu()</function> when you are done.
- </para>
- <para>
- If you know you cannot be preempted by another task (ie. you are
- in interrupt context, or have preemption disabled) you can use
- smp_processor_id().
- </para>
- </sect1>
-
- <sect1 id="routines-init">
- <title><type>__init</type>/<type>__exit</type>/<type>__initdata</type>
- <filename class="headerfile">include/linux/init.h</filename></title>
-
- <para>
- After boot, the kernel frees up a special section; functions
- marked with <type>__init</type> and data structures marked with
- <type>__initdata</type> are dropped after boot is complete: similarly
- modules discard this memory after initialization. <type>__exit</type>
- is used to declare a function which is only required on exit: the
- function will be dropped if this file is not compiled as a module.
- See the header file for use. Note that it makes no sense for a function
- marked with <type>__init</type> to be exported to modules with
- <function>EXPORT_SYMBOL()</function> - this will break.
- </para>
-
- </sect1>
-
- <sect1 id="routines-init-again">
- <title><function>__initcall()</function>/<function>module_init()</function>
- <filename class="headerfile">include/linux/init.h</filename></title>
- <para>
- Many parts of the kernel are well served as a module
- (dynamically-loadable parts of the kernel). Using the
- <function>module_init()</function> and
- <function>module_exit()</function> macros it is easy to write code
- without #ifdefs which can operate both as a module or built into
- the kernel.
- </para>
-
- <para>
- The <function>module_init()</function> macro defines which
- function is to be called at module insertion time (if the file is
- compiled as a module), or at boot time: if the file is not
- compiled as a module the <function>module_init()</function> macro
- becomes equivalent to <function>__initcall()</function>, which
- through linker magic ensures that the function is called on boot.
- </para>
-
- <para>
- The function can return a negative error number to cause
- module loading to fail (unfortunately, this has no effect if
- the module is compiled into the kernel). This function is
- called in user context with interrupts enabled, so it can sleep.
- </para>
- </sect1>
-
- <sect1 id="routines-moduleexit">
- <title> <function>module_exit()</function>
- <filename class="headerfile">include/linux/init.h</filename> </title>
-
- <para>
- This macro defines the function to be called at module removal
- time (or never, in the case of the file compiled into the
- kernel). It will only be called if the module usage count has
- reached zero. This function can also sleep, but cannot fail:
- everything must be cleaned up by the time it returns.
- </para>
-
- <para>
- Note that this macro is optional: if it is not present, your
- module will not be removable (except for 'rmmod -f').
- </para>
- </sect1>
-
- <sect1 id="routines-module-use-counters">
- <title> <function>try_module_get()</function>/<function>module_put()</function>
- <filename class="headerfile">include/linux/module.h</filename></title>
-
- <para>
- These manipulate the module usage count, to protect against
- removal (a module also can't be removed if another module uses one
- of its exported symbols: see below). Before calling into module
- code, you should call <function>try_module_get()</function> on
- that module: if it fails, then the module is being removed and you
- should act as if it wasn't there. Otherwise, you can safely enter
- the module, and call <function>module_put()</function> when you're
- finished.
- </para>
-
- <para>
- Most registerable structures have an
- <structfield>owner</structfield> field, such as in the
- <structname>file_operations</structname> structure. Set this field
- to the macro <symbol>THIS_MODULE</symbol>.
- </para>
- </sect1>
-
- <!-- add info on new-style module refcounting here -->
- </chapter>
-
- <chapter id="queues">
- <title>Wait Queues
- <filename class="headerfile">include/linux/wait.h</filename>
- </title>
- <para>
- <emphasis>[SLEEPS]</emphasis>
- </para>
-
- <para>
- A wait queue is used to wait for someone to wake you up when a
- certain condition is true. They must be used carefully to ensure
- there is no race condition. You declare a
- <type>wait_queue_head_t</type>, and then processes which want to
- wait for that condition declare a <type>wait_queue_t</type>
- referring to themselves, and place that in the queue.
- </para>
-
- <sect1 id="queue-declaring">
- <title>Declaring</title>
-
- <para>
- You declare a <type>wait_queue_head_t</type> using the
- <function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the
- <function>init_waitqueue_head()</function> routine in your
- initialization code.
- </para>
- </sect1>
-
- <sect1 id="queue-waitqueue">
- <title>Queuing</title>
-
- <para>
- Placing yourself in the waitqueue is fairly complex, because you
- must put yourself in the queue before checking the condition.
- There is a macro to do this:
- <function>wait_event_interruptible()</function>
-
- <filename class="headerfile">include/linux/wait.h</filename> The
- first argument is the wait queue head, and the second is an
- expression which is evaluated; the macro returns
- <returnvalue>0</returnvalue> when this expression is true, or
- <returnvalue>-ERESTARTSYS</returnvalue> if a signal is received.
- The <function>wait_event()</function> version ignores signals.
- </para>
-
- </sect1>
-
- <sect1 id="queue-waking">
- <title>Waking Up Queued Tasks</title>
-
- <para>
- Call <function>wake_up()</function>
-
- <filename class="headerfile">include/linux/wait.h</filename>;,
- which will wake up every process in the queue. The exception is
- if one has <constant>TASK_EXCLUSIVE</constant> set, in which case
- the remainder of the queue will not be woken. There are other variants
- of this basic function available in the same header.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="atomic-ops">
- <title>Atomic Operations</title>
-
- <para>
- Certain operations are guaranteed atomic on all platforms. The
- first class of operations work on <type>atomic_t</type>
-
- <filename class="headerfile">include/asm/atomic.h</filename>; this
- contains a signed integer (at least 32 bits long), and you must use
- these functions to manipulate or read atomic_t variables.
- <function>atomic_read()</function> and
- <function>atomic_set()</function> get and set the counter,
- <function>atomic_add()</function>,
- <function>atomic_sub()</function>,
- <function>atomic_inc()</function>,
- <function>atomic_dec()</function>, and
- <function>atomic_dec_and_test()</function> (returns
- <returnvalue>true</returnvalue> if it was decremented to zero).
- </para>
-
- <para>
- Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the
- atomic variable is zero.
- </para>
-
- <para>
- Note that these functions are slower than normal arithmetic, and
- so should not be used unnecessarily.
- </para>
-
- <para>
- The second class of atomic operations is atomic bit operations on an
- <type>unsigned long</type>, defined in
-
- <filename class="headerfile">include/linux/bitops.h</filename>. These
- operations generally take a pointer to the bit pattern, and a bit
- number: 0 is the least significant bit.
- <function>set_bit()</function>, <function>clear_bit()</function>
- and <function>change_bit()</function> set, clear, and flip the
- given bit. <function>test_and_set_bit()</function>,
- <function>test_and_clear_bit()</function> and
- <function>test_and_change_bit()</function> do the same thing,
- except return true if the bit was previously set; these are
- particularly useful for atomically setting flags.
- </para>
-
- <para>
- It is possible to call these operations with bit indices greater
- than BITS_PER_LONG. The resulting behavior is strange on big-endian
- platforms though so it is a good idea not to do this.
- </para>
- </chapter>
-
- <chapter id="symbols">
- <title>Symbols</title>
-
- <para>
- Within the kernel proper, the normal linking rules apply
- (ie. unless a symbol is declared to be file scope with the
- <type>static</type> keyword, it can be used anywhere in the
- kernel). However, for modules, a special exported symbol table is
- kept which limits the entry points to the kernel proper. Modules
- can also export symbols.
- </para>
-
- <sect1 id="sym-exportsymbols">
- <title><function>EXPORT_SYMBOL()</function>
- <filename class="headerfile">include/linux/export.h</filename></title>
-
- <para>
- This is the classic method of exporting a symbol: dynamically
- loaded modules will be able to use the symbol as normal.
- </para>
- </sect1>
-
- <sect1 id="sym-exportsymbols-gpl">
- <title><function>EXPORT_SYMBOL_GPL()</function>
- <filename class="headerfile">include/linux/export.h</filename></title>
-
- <para>
- Similar to <function>EXPORT_SYMBOL()</function> except that the
- symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can
- only be seen by modules with a
- <function>MODULE_LICENSE()</function> that specifies a GPL
- compatible license. It implies that the function is considered
- an internal implementation issue, and not really an interface.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="conventions">
- <title>Routines and Conventions</title>
-
- <sect1 id="conventions-doublelinkedlist">
- <title>Double-linked lists
- <filename class="headerfile">include/linux/list.h</filename></title>
-
- <para>
- There used to be three sets of linked-list routines in the kernel
- headers, but this one is the winner. If you don't have some
- particular pressing need for a single list, it's a good choice.
- </para>
-
- <para>
- In particular, <function>list_for_each_entry</function> is useful.
- </para>
- </sect1>
-
- <sect1 id="convention-returns">
- <title>Return Conventions</title>
-
- <para>
- For code called in user context, it's very common to defy C
- convention, and return <returnvalue>0</returnvalue> for success,
- and a negative error number
- (eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be
- unintuitive at first, but it's fairly widespread in the kernel.
- </para>
-
- <para>
- Using <function>ERR_PTR()</function>
-
- <filename class="headerfile">include/linux/err.h</filename>; to
- encode a negative error number into a pointer, and
- <function>IS_ERR()</function> and <function>PTR_ERR()</function>
- to get it back out again: avoids a separate pointer parameter for
- the error number. Icky, but in a good way.
- </para>
- </sect1>
-
- <sect1 id="conventions-borkedcompile">
- <title>Breaking Compilation</title>
-
- <para>
- Linus and the other developers sometimes change function or
- structure names in development kernels; this is not done just to
- keep everyone on their toes: it reflects a fundamental change
- (eg. can no longer be called with interrupts on, or does extra
- checks, or doesn't do checks which were caught before). Usually
- this is accompanied by a fairly complete note to the linux-kernel
- mailing list; search the archive. Simply doing a global replace
- on the file usually makes things <emphasis>worse</emphasis>.
- </para>
- </sect1>
-
- <sect1 id="conventions-initialising">
- <title>Initializing structure members</title>
-
- <para>
- The preferred method of initializing structures is to use
- designated initialisers, as defined by ISO C99, eg:
- </para>
- <programlisting>
-static struct block_device_operations opt_fops = {
- .open = opt_open,
- .release = opt_release,
- .ioctl = opt_ioctl,
- .check_media_change = opt_media_change,
-};
- </programlisting>
- <para>
- This makes it easy to grep for, and makes it clear which
- structure fields are set. You should do this because it looks
- cool.
- </para>
- </sect1>
-
- <sect1 id="conventions-gnu-extns">
- <title>GNU Extensions</title>
-
- <para>
- GNU Extensions are explicitly allowed in the Linux kernel.
- Note that some of the more complex ones are not very well
- supported, due to lack of general use, but the following are
- considered standard (see the GCC info page section "C
- Extensions" for more details - Yes, really the info page, the
- man page is only a short summary of the stuff in info).
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Inline functions
- </para>
- </listitem>
- <listitem>
- <para>
- Statement expressions (ie. the ({ and }) constructs).
- </para>
- </listitem>
- <listitem>
- <para>
- Declaring attributes of a function / variable / type
- (__attribute__)
- </para>
- </listitem>
- <listitem>
- <para>
- typeof
- </para>
- </listitem>
- <listitem>
- <para>
- Zero length arrays
- </para>
- </listitem>
- <listitem>
- <para>
- Macro varargs
- </para>
- </listitem>
- <listitem>
- <para>
- Arithmetic on void pointers
- </para>
- </listitem>
- <listitem>
- <para>
- Non-Constant initializers
- </para>
- </listitem>
- <listitem>
- <para>
- Assembler Instructions (not outside arch/ and include/asm/)
- </para>
- </listitem>
- <listitem>
- <para>
- Function names as strings (__func__).
- </para>
- </listitem>
- <listitem>
- <para>
- __builtin_constant_p()
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Be wary when using long long in the kernel, the code gcc generates for
- it is horrible and worse: division and multiplication does not work
- on i386 because the GCC runtime functions for it are missing from
- the kernel environment.
- </para>
-
- <!-- FIXME: add a note about ANSI aliasing cleanness -->
- </sect1>
-
- <sect1 id="conventions-cplusplus">
- <title>C++</title>
-
- <para>
- Using C++ in the kernel is usually a bad idea, because the
- kernel does not provide the necessary runtime environment
- and the include files are not tested for it. It is still
- possible, but not recommended. If you really want to do
- this, forget about exceptions at least.
- </para>
- </sect1>
-
- <sect1 id="conventions-ifdef">
- <title>&num;if</title>
-
- <para>
- It is generally considered cleaner to use macros in header files
- (or at the top of .c files) to abstract away functions rather than
- using `#if' pre-processor statements throughout the source code.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="submitting">
- <title>Putting Your Stuff in the Kernel</title>
-
- <para>
- In order to get your stuff into shape for official inclusion, or
- even to make a neat patch, there's administrative work to be
- done:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Figure out whose pond you've been pissing in. Look at the top of
- the source files, inside the <filename>MAINTAINERS</filename>
- file, and last of all in the <filename>CREDITS</filename> file.
- You should coordinate with this person to make sure you're not
- duplicating effort, or trying something that's already been
- rejected.
- </para>
-
- <para>
- Make sure you put your name and EMail address at the top of
- any files you create or mangle significantly. This is the
- first place people will look when they find a bug, or when
- <emphasis>they</emphasis> want to make a change.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Usually you want a configuration option for your kernel hack.
- Edit <filename>Kconfig</filename> in the appropriate directory.
- The Config language is simple to use by cut and paste, and there's
- complete documentation in
- <filename>Documentation/kbuild/kconfig-language.txt</filename>.
- </para>
-
- <para>
- In your description of the option, make sure you address both the
- expert user and the user who knows nothing about your feature. Mention
- incompatibilities and issues here. <emphasis> Definitely
- </emphasis> end your description with <quote> if in doubt, say N
- </quote> (or, occasionally, `Y'); this is for people who have no
- idea what you are talking about.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Edit the <filename>Makefile</filename>: the CONFIG variables are
- exported here so you can usually just add a "obj-$(CONFIG_xxx) +=
- xxx.o" line. The syntax is documented in
- <filename>Documentation/kbuild/makefiles.txt</filename>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Put yourself in <filename>CREDITS</filename> if you've done
- something noteworthy, usually beyond a single file (your name
- should be at the top of the source files anyway).
- <filename>MAINTAINERS</filename> means you want to be consulted
- when changes are made to a subsystem, and hear about bugs; it
- implies a more-than-passing commitment to some part of the code.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
- and possibly <filename>Documentation/SubmittingDrivers</filename>.
- </para>
- </listitem>
- </itemizedlist>
- </chapter>
-
- <chapter id="cantrips">
- <title>Kernel Cantrips</title>
-
- <para>
- Some favorites from browsing the source. Feel free to add to this
- list.
- </para>
-
- <para>
- <filename>arch/x86/include/asm/delay.h:</filename>
- </para>
- <programlisting>
-#define ndelay(n) (__builtin_constant_p(n) ? \
- ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
- __ndelay(n))
- </programlisting>
-
- <para>
- <filename>include/linux/fs.h</filename>:
- </para>
- <programlisting>
-/*
- * Kernel pointers have redundant information, so we can use a
- * scheme where we can return either an error code or a dentry
- * pointer with the same return value.
- *
- * This should be a per-architecture thing, to allow different
- * error and pointer decisions.
- */
- #define ERR_PTR(err) ((void *)((long)(err)))
- #define PTR_ERR(ptr) ((long)(ptr))
- #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
-</programlisting>
-
- <para>
- <filename>arch/x86/include/asm/uaccess_32.h:</filename>
- </para>
-
- <programlisting>
-#define copy_to_user(to,from,n) \
- (__builtin_constant_p(n) ? \
- __constant_copy_to_user((to),(from),(n)) : \
- __generic_copy_to_user((to),(from),(n)))
- </programlisting>
-
- <para>
- <filename>arch/sparc/kernel/head.S:</filename>
- </para>
-
- <programlisting>
-/*
- * Sun people can't spell worth damn. "compatability" indeed.
- * At least we *know* we can't spell, and use a spell-checker.
- */
-
-/* Uh, actually Linus it is I who cannot spell. Too much murky
- * Sparc assembly will do this to ya.
- */
-C_LABEL(cputypvar):
- .asciz "compatibility"
-
-/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
- .align 4
-C_LABEL(cputypvar_sun4m):
- .asciz "compatible"
- </programlisting>
-
- <para>
- <filename>arch/sparc/lib/checksum.S:</filename>
- </para>
-
- <programlisting>
- /* Sun, you just can't beat me, you just can't. Stop trying,
- * give up. I'm serious, I am going to kick the living shit
- * out of you, game over, lights out.
- */
- </programlisting>
- </chapter>
-
- <chapter id="credits">
- <title>Thanks</title>
-
- <para>
- Thanks to Andi Kleen for the idea, answering my questions, fixing
- my mistakes, filling content, etc. Philipp Rumpf for more spelling
- and clarity fixes, and some excellent non-obvious points. Werner
- Almesberger for giving me a great summary of
- <function>disable_irq()</function>, and Jes Sorensen and Andrea
- Arcangeli added caveats. Michael Elizabeth Chastain for checking
- and adding to the Configure section. <!-- Rusty insisted on this
- bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook.
- </para>
- </chapter>
-</book>
-
diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl
deleted file mode 100644
index 7c9cc4846cb6..000000000000
--- a/Documentation/DocBook/kernel-locking.tmpl
+++ /dev/null
@@ -1,2151 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="LKLockingGuide">
- <bookinfo>
- <title>Unreliable Guide To Locking</title>
-
- <authorgroup>
- <author>
- <firstname>Rusty</firstname>
- <surname>Russell</surname>
- <affiliation>
- <address>
- <email>rusty@rustcorp.com.au</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2003</year>
- <holder>Rusty Russell</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- Welcome, to Rusty's Remarkably Unreliable Guide to Kernel
- Locking issues. This document describes the locking systems in
- the Linux Kernel in 2.6.
- </para>
- <para>
- With the wide availability of HyperThreading, and <firstterm
- linkend="gloss-preemption">preemption </firstterm> in the Linux
- Kernel, everyone hacking on the kernel needs to know the
- fundamentals of concurrency and locking for
- <firstterm linkend="gloss-smp"><acronym>SMP</acronym></firstterm>.
- </para>
- </chapter>
-
- <chapter id="races">
- <title>The Problem With Concurrency</title>
- <para>
- (Skip this if you know what a Race Condition is).
- </para>
- <para>
- In a normal program, you can increment a counter like so:
- </para>
- <programlisting>
- very_important_count++;
- </programlisting>
-
- <para>
- This is what they would expect to happen:
- </para>
-
- <table>
- <title>Expected Results</title>
-
- <tgroup cols="2" align="left">
-
- <thead>
- <row>
- <entry>Instance 1</entry>
- <entry>Instance 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>read very_important_count (5)</entry>
- <entry></entry>
- </row>
- <row>
- <entry>add 1 (6)</entry>
- <entry></entry>
- </row>
- <row>
- <entry>write very_important_count (6)</entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>read very_important_count (6)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>add 1 (7)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>write very_important_count (7)</entry>
- </row>
- </tbody>
-
- </tgroup>
- </table>
-
- <para>
- This is what might happen:
- </para>
-
- <table>
- <title>Possible Results</title>
-
- <tgroup cols="2" align="left">
- <thead>
- <row>
- <entry>Instance 1</entry>
- <entry>Instance 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>read very_important_count (5)</entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>read very_important_count (5)</entry>
- </row>
- <row>
- <entry>add 1 (6)</entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>add 1 (6)</entry>
- </row>
- <row>
- <entry>write very_important_count (6)</entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>write very_important_count (6)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <sect1 id="race-condition">
- <title>Race Conditions and Critical Regions</title>
- <para>
- This overlap, where the result depends on the
- relative timing of multiple tasks, is called a <firstterm>race condition</firstterm>.
- The piece of code containing the concurrency issue is called a
- <firstterm>critical region</firstterm>. And especially since Linux starting running
- on SMP machines, they became one of the major issues in kernel
- design and implementation.
- </para>
- <para>
- Preemption can have the same effect, even if there is only one
- CPU: by preempting one task during the critical region, we have
- exactly the same race condition. In this case the thread which
- preempts might run the critical region itself.
- </para>
- <para>
- The solution is to recognize when these simultaneous accesses
- occur, and use locks to make sure that only one instance can
- enter the critical region at any time. There are many
- friendly primitives in the Linux kernel to help you do this.
- And then there are the unfriendly primitives, but I'll pretend
- they don't exist.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="locks">
- <title>Locking in the Linux Kernel</title>
-
- <para>
- If I could give you one piece of advice: never sleep with anyone
- crazier than yourself. But if I had to give you advice on
- locking: <emphasis>keep it simple</emphasis>.
- </para>
-
- <para>
- Be reluctant to introduce new locks.
- </para>
-
- <para>
- Strangely enough, this last one is the exact reverse of my advice when
- you <emphasis>have</emphasis> slept with someone crazier than yourself.
- And you should think about getting a big dog.
- </para>
-
- <sect1 id="lock-intro">
- <title>Two Main Types of Kernel Locks: Spinlocks and Mutexes</title>
-
- <para>
- There are two main types of kernel locks. The fundamental type
- is the spinlock
- (<filename class="headerfile">include/asm/spinlock.h</filename>),
- which is a very simple single-holder lock: if you can't get the
- spinlock, you keep trying (spinning) until you can. Spinlocks are
- very small and fast, and can be used anywhere.
- </para>
- <para>
- The second type is a mutex
- (<filename class="headerfile">include/linux/mutex.h</filename>): it
- is like a spinlock, but you may block holding a mutex.
- If you can't lock a mutex, your task will suspend itself, and be woken
- up when the mutex is released. This means the CPU can do something
- else while you are waiting. There are many cases when you simply
- can't sleep (see <xref linkend="sleeping-things"/>), and so have to
- use a spinlock instead.
- </para>
- <para>
- Neither type of lock is recursive: see
- <xref linkend="deadlock"/>.
- </para>
- </sect1>
-
- <sect1 id="uniprocessor">
- <title>Locks and Uniprocessor Kernels</title>
-
- <para>
- For kernels compiled without <symbol>CONFIG_SMP</symbol>, and
- without <symbol>CONFIG_PREEMPT</symbol> spinlocks do not exist at
- all. This is an excellent design decision: when no-one else can
- run at the same time, there is no reason to have a lock.
- </para>
-
- <para>
- If the kernel is compiled without <symbol>CONFIG_SMP</symbol>,
- but <symbol>CONFIG_PREEMPT</symbol> is set, then spinlocks
- simply disable preemption, which is sufficient to prevent any
- races. For most purposes, we can think of preemption as
- equivalent to SMP, and not worry about it separately.
- </para>
-
- <para>
- You should always test your locking code with <symbol>CONFIG_SMP</symbol>
- and <symbol>CONFIG_PREEMPT</symbol> enabled, even if you don't have an SMP test box, because it
- will still catch some kinds of locking bugs.
- </para>
-
- <para>
- Mutexes still exist, because they are required for
- synchronization between <firstterm linkend="gloss-usercontext">user
- contexts</firstterm>, as we will see below.
- </para>
- </sect1>
-
- <sect1 id="usercontextlocking">
- <title>Locking Only In User Context</title>
-
- <para>
- If you have a data structure which is only ever accessed from
- user context, then you can use a simple mutex
- (<filename>include/linux/mutex.h</filename>) to protect it. This
- is the most trivial case: you initialize the mutex. Then you can
- call <function>mutex_lock_interruptible()</function> to grab the mutex,
- and <function>mutex_unlock()</function> to release it. There is also a
- <function>mutex_lock()</function>, which should be avoided, because it
- will not return if a signal is received.
- </para>
-
- <para>
- Example: <filename>net/netfilter/nf_sockopt.c</filename> allows
- registration of new <function>setsockopt()</function> and
- <function>getsockopt()</function> calls, with
- <function>nf_register_sockopt()</function>. Registration and
- de-registration are only done on module load and unload (and boot
- time, where there is no concurrency), and the list of registrations
- is only consulted for an unknown <function>setsockopt()</function>
- or <function>getsockopt()</function> system call. The
- <varname>nf_sockopt_mutex</varname> is perfect to protect this,
- especially since the setsockopt and getsockopt calls may well
- sleep.
- </para>
- </sect1>
-
- <sect1 id="lock-user-bh">
- <title>Locking Between User Context and Softirqs</title>
-
- <para>
- If a <firstterm linkend="gloss-softirq">softirq</firstterm> shares
- data with user context, you have two problems. Firstly, the current
- user context can be interrupted by a softirq, and secondly, the
- critical region could be entered from another CPU. This is where
- <function>spin_lock_bh()</function>
- (<filename class="headerfile">include/linux/spinlock.h</filename>) is
- used. It disables softirqs on that CPU, then grabs the lock.
- <function>spin_unlock_bh()</function> does the reverse. (The
- '_bh' suffix is a historical reference to "Bottom Halves", the
- old name for software interrupts. It should really be
- called spin_lock_softirq()' in a perfect world).
- </para>
-
- <para>
- Note that you can also use <function>spin_lock_irq()</function>
- or <function>spin_lock_irqsave()</function> here, which stop
- hardware interrupts as well: see <xref linkend="hardirq-context"/>.
- </para>
-
- <para>
- This works perfectly for <firstterm linkend="gloss-up"><acronym>UP
- </acronym></firstterm> as well: the spin lock vanishes, and this macro
- simply becomes <function>local_bh_disable()</function>
- (<filename class="headerfile">include/linux/interrupt.h</filename>), which
- protects you from the softirq being run.
- </para>
- </sect1>
-
- <sect1 id="lock-user-tasklet">
- <title>Locking Between User Context and Tasklets</title>
-
- <para>
- This is exactly the same as above, because <firstterm
- linkend="gloss-tasklet">tasklets</firstterm> are actually run
- from a softirq.
- </para>
- </sect1>
-
- <sect1 id="lock-user-timers">
- <title>Locking Between User Context and Timers</title>
-
- <para>
- This, too, is exactly the same as above, because <firstterm
- linkend="gloss-timers">timers</firstterm> are actually run from
- a softirq. From a locking point of view, tasklets and timers
- are identical.
- </para>
- </sect1>
-
- <sect1 id="lock-tasklets">
- <title>Locking Between Tasklets/Timers</title>
-
- <para>
- Sometimes a tasklet or timer might want to share data with
- another tasklet or timer.
- </para>
-
- <sect2 id="lock-tasklets-same">
- <title>The Same Tasklet/Timer</title>
- <para>
- Since a tasklet is never run on two CPUs at once, you don't
- need to worry about your tasklet being reentrant (running
- twice at once), even on SMP.
- </para>
- </sect2>
-
- <sect2 id="lock-tasklets-different">
- <title>Different Tasklets/Timers</title>
- <para>
- If another tasklet/timer wants
- to share data with your tasklet or timer , you will both need to use
- <function>spin_lock()</function> and
- <function>spin_unlock()</function> calls.
- <function>spin_lock_bh()</function> is
- unnecessary here, as you are already in a tasklet, and
- none will be run on the same CPU.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="lock-softirqs">
- <title>Locking Between Softirqs</title>
-
- <para>
- Often a softirq might
- want to share data with itself or a tasklet/timer.
- </para>
-
- <sect2 id="lock-softirqs-same">
- <title>The Same Softirq</title>
-
- <para>
- The same softirq can run on the other CPUs: you can use a
- per-CPU array (see <xref linkend="per-cpu"/>) for better
- performance. If you're going so far as to use a softirq,
- you probably care about scalable performance enough
- to justify the extra complexity.
- </para>
-
- <para>
- You'll need to use <function>spin_lock()</function> and
- <function>spin_unlock()</function> for shared data.
- </para>
- </sect2>
-
- <sect2 id="lock-softirqs-different">
- <title>Different Softirqs</title>
-
- <para>
- You'll need to use <function>spin_lock()</function> and
- <function>spin_unlock()</function> for shared data, whether it
- be a timer, tasklet, different softirq or the same or another
- softirq: any of them could be running on a different CPU.
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="hardirq-context">
- <title>Hard IRQ Context</title>
-
- <para>
- Hardware interrupts usually communicate with a
- tasklet or softirq. Frequently this involves putting work in a
- queue, which the softirq will take out.
- </para>
-
- <sect1 id="hardirq-softirq">
- <title>Locking Between Hard IRQ and Softirqs/Tasklets</title>
-
- <para>
- If a hardware irq handler shares data with a softirq, you have
- two concerns. Firstly, the softirq processing can be
- interrupted by a hardware interrupt, and secondly, the
- critical region could be entered by a hardware interrupt on
- another CPU. This is where <function>spin_lock_irq()</function> is
- used. It is defined to disable interrupts on that cpu, then grab
- the lock. <function>spin_unlock_irq()</function> does the reverse.
- </para>
-
- <para>
- The irq handler does not to use
- <function>spin_lock_irq()</function>, because the softirq cannot
- run while the irq handler is running: it can use
- <function>spin_lock()</function>, which is slightly faster. The
- only exception would be if a different hardware irq handler uses
- the same lock: <function>spin_lock_irq()</function> will stop
- that from interrupting us.
- </para>
-
- <para>
- This works perfectly for UP as well: the spin lock vanishes,
- and this macro simply becomes <function>local_irq_disable()</function>
- (<filename class="headerfile">include/asm/smp.h</filename>), which
- protects you from the softirq/tasklet/BH being run.
- </para>
-
- <para>
- <function>spin_lock_irqsave()</function>
- (<filename>include/linux/spinlock.h</filename>) is a variant
- which saves whether interrupts were on or off in a flags word,
- which is passed to <function>spin_unlock_irqrestore()</function>. This
- means that the same code can be used inside an hard irq handler (where
- interrupts are already off) and in softirqs (where the irq
- disabling is required).
- </para>
-
- <para>
- Note that softirqs (and hence tasklets and timers) are run on
- return from hardware interrupts, so
- <function>spin_lock_irq()</function> also stops these. In that
- sense, <function>spin_lock_irqsave()</function> is the most
- general and powerful locking function.
- </para>
-
- </sect1>
- <sect1 id="hardirq-hardirq">
- <title>Locking Between Two Hard IRQ Handlers</title>
- <para>
- It is rare to have to share data between two IRQ handlers, but
- if you do, <function>spin_lock_irqsave()</function> should be
- used: it is architecture-specific whether all interrupts are
- disabled inside irq handlers themselves.
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="cheatsheet">
- <title>Cheat Sheet For Locking</title>
- <para>
- Pete Zaitcev gives the following summary:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- If you are in a process context (any syscall) and want to
- lock other process out, use a mutex. You can take a mutex
- and sleep (<function>copy_from_user*(</function> or
- <function>kmalloc(x,GFP_KERNEL)</function>).
- </para>
- </listitem>
- <listitem>
- <para>
- Otherwise (== data can be touched in an interrupt), use
- <function>spin_lock_irqsave()</function> and
- <function>spin_unlock_irqrestore()</function>.
- </para>
- </listitem>
- <listitem>
- <para>
- Avoid holding spinlock for more than 5 lines of code and
- across any function call (except accessors like
- <function>readb</function>).
- </para>
- </listitem>
- </itemizedlist>
-
- <sect1 id="minimum-lock-reqirements">
- <title>Table of Minimum Requirements</title>
-
- <para> The following table lists the <emphasis>minimum</emphasis>
- locking requirements between various contexts. In some cases,
- the same context can only be running on one CPU at a time, so
- no locking is required for that context (eg. a particular
- thread can only run on one CPU at a time, but if it needs
- shares data with another thread, locking is required).
- </para>
- <para>
- Remember the advice above: you can always use
- <function>spin_lock_irqsave()</function>, which is a superset
- of all other spinlock primitives.
- </para>
-
- <table>
-<title>Table of Locking Requirements</title>
-<tgroup cols="11">
-<tbody>
-
-<row>
-<entry></entry>
-<entry>IRQ Handler A</entry>
-<entry>IRQ Handler B</entry>
-<entry>Softirq A</entry>
-<entry>Softirq B</entry>
-<entry>Tasklet A</entry>
-<entry>Tasklet B</entry>
-<entry>Timer A</entry>
-<entry>Timer B</entry>
-<entry>User Context A</entry>
-<entry>User Context B</entry>
-</row>
-
-<row>
-<entry>IRQ Handler A</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>IRQ Handler B</entry>
-<entry>SLIS</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>Softirq A</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SL</entry>
-</row>
-
-<row>
-<entry>Softirq B</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-</row>
-
-<row>
-<entry>Tasklet A</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>Tasklet B</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>Timer A</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>Timer B</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>SL</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>User Context A</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>None</entry>
-</row>
-
-<row>
-<entry>User Context B</entry>
-<entry>SLI</entry>
-<entry>SLI</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>SLBH</entry>
-<entry>MLI</entry>
-<entry>None</entry>
-</row>
-
-</tbody>
-</tgroup>
-</table>
-
- <table>
-<title>Legend for Locking Requirements Table</title>
-<tgroup cols="2">
-<tbody>
-
-<row>
-<entry>SLIS</entry>
-<entry>spin_lock_irqsave</entry>
-</row>
-<row>
-<entry>SLI</entry>
-<entry>spin_lock_irq</entry>
-</row>
-<row>
-<entry>SL</entry>
-<entry>spin_lock</entry>
-</row>
-<row>
-<entry>SLBH</entry>
-<entry>spin_lock_bh</entry>
-</row>
-<row>
-<entry>MLI</entry>
-<entry>mutex_lock_interruptible</entry>
-</row>
-
-</tbody>
-</tgroup>
-</table>
-
-</sect1>
-</chapter>
-
-<chapter id="trylock-functions">
- <title>The trylock Functions</title>
- <para>
- There are functions that try to acquire a lock only once and immediately
- return a value telling about success or failure to acquire the lock.
- They can be used if you need no access to the data protected with the lock
- when some other thread is holding the lock. You should acquire the lock
- later if you then need access to the data protected with the lock.
- </para>
-
- <para>
- <function>spin_trylock()</function> does not spin but returns non-zero if
- it acquires the spinlock on the first try or 0 if not. This function can
- be used in all contexts like <function>spin_lock</function>: you must have
- disabled the contexts that might interrupt you and acquire the spin lock.
- </para>
-
- <para>
- <function>mutex_trylock()</function> does not suspend your task
- but returns non-zero if it could lock the mutex on the first try
- or 0 if not. This function cannot be safely used in hardware or software
- interrupt contexts despite not sleeping.
- </para>
-</chapter>
-
- <chapter id="Examples">
- <title>Common Examples</title>
- <para>
-Let's step through a simple example: a cache of number to name
-mappings. The cache keeps a count of how often each of the objects is
-used, and when it gets full, throws out the least used one.
-
- </para>
-
- <sect1 id="examples-usercontext">
- <title>All In User Context</title>
- <para>
-For our first example, we assume that all operations are in user
-context (ie. from system calls), so we can sleep. This means we can
-use a mutex to protect the cache and all the objects within
-it. Here's the code:
- </para>
-
- <programlisting>
-#include &lt;linux/list.h&gt;
-#include &lt;linux/slab.h&gt;
-#include &lt;linux/string.h&gt;
-#include &lt;linux/mutex.h&gt;
-#include &lt;asm/errno.h&gt;
-
-struct object
-{
- struct list_head list;
- int id;
- char name[32];
- int popularity;
-};
-
-/* Protects the cache, cache_num, and the objects within it */
-static DEFINE_MUTEX(cache_lock);
-static LIST_HEAD(cache);
-static unsigned int cache_num = 0;
-#define MAX_CACHE_SIZE 10
-
-/* Must be holding cache_lock */
-static struct object *__cache_find(int id)
-{
- struct object *i;
-
- list_for_each_entry(i, &amp;cache, list)
- if (i-&gt;id == id) {
- i-&gt;popularity++;
- return i;
- }
- return NULL;
-}
-
-/* Must be holding cache_lock */
-static void __cache_delete(struct object *obj)
-{
- BUG_ON(!obj);
- list_del(&amp;obj-&gt;list);
- kfree(obj);
- cache_num--;
-}
-
-/* Must be holding cache_lock */
-static void __cache_add(struct object *obj)
-{
- list_add(&amp;obj-&gt;list, &amp;cache);
- if (++cache_num > MAX_CACHE_SIZE) {
- struct object *i, *outcast = NULL;
- list_for_each_entry(i, &amp;cache, list) {
- if (!outcast || i-&gt;popularity &lt; outcast-&gt;popularity)
- outcast = i;
- }
- __cache_delete(outcast);
- }
-}
-
-int cache_add(int id, const char *name)
-{
- struct object *obj;
-
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
- return -ENOMEM;
-
- strlcpy(obj-&gt;name, name, sizeof(obj-&gt;name));
- obj-&gt;id = id;
- obj-&gt;popularity = 0;
-
- mutex_lock(&amp;cache_lock);
- __cache_add(obj);
- mutex_unlock(&amp;cache_lock);
- return 0;
-}
-
-void cache_delete(int id)
-{
- mutex_lock(&amp;cache_lock);
- __cache_delete(__cache_find(id));
- mutex_unlock(&amp;cache_lock);
-}
-
-int cache_find(int id, char *name)
-{
- struct object *obj;
- int ret = -ENOENT;
-
- mutex_lock(&amp;cache_lock);
- obj = __cache_find(id);
- if (obj) {
- ret = 0;
- strcpy(name, obj-&gt;name);
- }
- mutex_unlock(&amp;cache_lock);
- return ret;
-}
-</programlisting>
-
- <para>
-Note that we always make sure we have the cache_lock when we add,
-delete, or look up the cache: both the cache infrastructure itself and
-the contents of the objects are protected by the lock. In this case
-it's easy, since we copy the data for the user, and never let them
-access the objects directly.
- </para>
- <para>
-There is a slight (and common) optimization here: in
-<function>cache_add</function> we set up the fields of the object
-before grabbing the lock. This is safe, as no-one else can access it
-until we put it in cache.
- </para>
- </sect1>
-
- <sect1 id="examples-interrupt">
- <title>Accessing From Interrupt Context</title>
- <para>
-Now consider the case where <function>cache_find</function> can be
-called from interrupt context: either a hardware interrupt or a
-softirq. An example would be a timer which deletes object from the
-cache.
- </para>
- <para>
-The change is shown below, in standard patch format: the
-<symbol>-</symbol> are lines which are taken away, and the
-<symbol>+</symbol> are lines which are added.
- </para>
-<programlisting>
---- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100
-+++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100
-@@ -12,7 +12,7 @@
- int popularity;
- };
-
--static DEFINE_MUTEX(cache_lock);
-+static DEFINE_SPINLOCK(cache_lock);
- static LIST_HEAD(cache);
- static unsigned int cache_num = 0;
- #define MAX_CACHE_SIZE 10
-@@ -55,6 +55,7 @@
- int cache_add(int id, const char *name)
- {
- struct object *obj;
-+ unsigned long flags;
-
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
- return -ENOMEM;
-@@ -63,30 +64,33 @@
- obj-&gt;id = id;
- obj-&gt;popularity = 0;
-
-- mutex_lock(&amp;cache_lock);
-+ spin_lock_irqsave(&amp;cache_lock, flags);
- __cache_add(obj);
-- mutex_unlock(&amp;cache_lock);
-+ spin_unlock_irqrestore(&amp;cache_lock, flags);
- return 0;
- }
-
- void cache_delete(int id)
- {
-- mutex_lock(&amp;cache_lock);
-+ unsigned long flags;
-+
-+ spin_lock_irqsave(&amp;cache_lock, flags);
- __cache_delete(__cache_find(id));
-- mutex_unlock(&amp;cache_lock);
-+ spin_unlock_irqrestore(&amp;cache_lock, flags);
- }
-
- int cache_find(int id, char *name)
- {
- struct object *obj;
- int ret = -ENOENT;
-+ unsigned long flags;
-
-- mutex_lock(&amp;cache_lock);
-+ spin_lock_irqsave(&amp;cache_lock, flags);
- obj = __cache_find(id);
- if (obj) {
- ret = 0;
- strcpy(name, obj-&gt;name);
- }
-- mutex_unlock(&amp;cache_lock);
-+ spin_unlock_irqrestore(&amp;cache_lock, flags);
- return ret;
- }
-</programlisting>
-
- <para>
-Note that the <function>spin_lock_irqsave</function> will turn off
-interrupts if they are on, otherwise does nothing (if we are already
-in an interrupt handler), hence these functions are safe to call from
-any context.
- </para>
- <para>
-Unfortunately, <function>cache_add</function> calls
-<function>kmalloc</function> with the <symbol>GFP_KERNEL</symbol>
-flag, which is only legal in user context. I have assumed that
-<function>cache_add</function> is still only called in user context,
-otherwise this should become a parameter to
-<function>cache_add</function>.
- </para>
- </sect1>
- <sect1 id="examples-refcnt">
- <title>Exposing Objects Outside This File</title>
- <para>
-If our objects contained more information, it might not be sufficient
-to copy the information in and out: other parts of the code might want
-to keep pointers to these objects, for example, rather than looking up
-the id every time. This produces two problems.
- </para>
- <para>
-The first problem is that we use the <symbol>cache_lock</symbol> to
-protect objects: we'd need to make this non-static so the rest of the
-code can use it. This makes locking trickier, as it is no longer all
-in one place.
- </para>
- <para>
-The second problem is the lifetime problem: if another structure keeps
-a pointer to an object, it presumably expects that pointer to remain
-valid. Unfortunately, this is only guaranteed while you hold the
-lock, otherwise someone might call <function>cache_delete</function>
-and even worse, add another object, re-using the same address.
- </para>
- <para>
-As there is only one lock, you can't hold it forever: no-one else would
-get any work done.
- </para>
- <para>
-The solution to this problem is to use a reference count: everyone who
-has a pointer to the object increases it when they first get the
-object, and drops the reference count when they're finished with it.
-Whoever drops it to zero knows it is unused, and can actually delete it.
- </para>
- <para>
-Here is the code:
- </para>
-
-<programlisting>
---- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100
-+++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100
-@@ -7,6 +7,7 @@
- struct object
- {
- struct list_head list;
-+ unsigned int refcnt;
- int id;
- char name[32];
- int popularity;
-@@ -17,6 +18,35 @@
- static unsigned int cache_num = 0;
- #define MAX_CACHE_SIZE 10
-
-+static void __object_put(struct object *obj)
-+{
-+ if (--obj-&gt;refcnt == 0)
-+ kfree(obj);
-+}
-+
-+static void __object_get(struct object *obj)
-+{
-+ obj-&gt;refcnt++;
-+}
-+
-+void object_put(struct object *obj)
-+{
-+ unsigned long flags;
-+
-+ spin_lock_irqsave(&amp;cache_lock, flags);
-+ __object_put(obj);
-+ spin_unlock_irqrestore(&amp;cache_lock, flags);
-+}
-+
-+void object_get(struct object *obj)
-+{
-+ unsigned long flags;
-+
-+ spin_lock_irqsave(&amp;cache_lock, flags);
-+ __object_get(obj);
-+ spin_unlock_irqrestore(&amp;cache_lock, flags);
-+}
-+
- /* Must be holding cache_lock */
- static struct object *__cache_find(int id)
- {
-@@ -35,6 +65,7 @@
- {
- BUG_ON(!obj);
- list_del(&amp;obj-&gt;list);
-+ __object_put(obj);
- cache_num--;
- }
-
-@@ -63,6 +94,7 @@
- strlcpy(obj-&gt;name, name, sizeof(obj-&gt;name));
- obj-&gt;id = id;
- obj-&gt;popularity = 0;
-+ obj-&gt;refcnt = 1; /* The cache holds a reference */
-
- spin_lock_irqsave(&amp;cache_lock, flags);
- __cache_add(obj);
-@@ -79,18 +111,15 @@
- spin_unlock_irqrestore(&amp;cache_lock, flags);
- }
-
--int cache_find(int id, char *name)
-+struct object *cache_find(int id)
- {
- struct object *obj;
-- int ret = -ENOENT;
- unsigned long flags;
-
- spin_lock_irqsave(&amp;cache_lock, flags);
- obj = __cache_find(id);
-- if (obj) {
-- ret = 0;
-- strcpy(name, obj-&gt;name);
-- }
-+ if (obj)
-+ __object_get(obj);
- spin_unlock_irqrestore(&amp;cache_lock, flags);
-- return ret;
-+ return obj;
- }
-</programlisting>
-
-<para>
-We encapsulate the reference counting in the standard 'get' and 'put'
-functions. Now we can return the object itself from
-<function>cache_find</function> which has the advantage that the user
-can now sleep holding the object (eg. to
-<function>copy_to_user</function> to name to userspace).
-</para>
-<para>
-The other point to note is that I said a reference should be held for
-every pointer to the object: thus the reference count is 1 when first
-inserted into the cache. In some versions the framework does not hold
-a reference count, but they are more complicated.
-</para>
-
- <sect2 id="examples-refcnt-atomic">
- <title>Using Atomic Operations For The Reference Count</title>
-<para>
-In practice, <type>atomic_t</type> would usually be used for
-<structfield>refcnt</structfield>. There are a number of atomic
-operations defined in
-
-<filename class="headerfile">include/asm/atomic.h</filename>: these are
-guaranteed to be seen atomically from all CPUs in the system, so no
-lock is required. In this case, it is simpler than using spinlocks,
-although for anything non-trivial using spinlocks is clearer. The
-<function>atomic_inc</function> and
-<function>atomic_dec_and_test</function> are used instead of the
-standard increment and decrement operators, and the lock is no longer
-used to protect the reference count itself.
-</para>
-
-<programlisting>
---- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100
-+++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100
-@@ -7,7 +7,7 @@
- struct object
- {
- struct list_head list;
-- unsigned int refcnt;
-+ atomic_t refcnt;
- int id;
- char name[32];
- int popularity;
-@@ -18,33 +18,15 @@
- static unsigned int cache_num = 0;
- #define MAX_CACHE_SIZE 10
-
--static void __object_put(struct object *obj)
--{
-- if (--obj-&gt;refcnt == 0)
-- kfree(obj);
--}
--
--static void __object_get(struct object *obj)
--{
-- obj-&gt;refcnt++;
--}
--
- void object_put(struct object *obj)
- {
-- unsigned long flags;
--
-- spin_lock_irqsave(&amp;cache_lock, flags);
-- __object_put(obj);
-- spin_unlock_irqrestore(&amp;cache_lock, flags);
-+ if (atomic_dec_and_test(&amp;obj-&gt;refcnt))
-+ kfree(obj);
- }
-
- void object_get(struct object *obj)
- {
-- unsigned long flags;
--
-- spin_lock_irqsave(&amp;cache_lock, flags);
-- __object_get(obj);
-- spin_unlock_irqrestore(&amp;cache_lock, flags);
-+ atomic_inc(&amp;obj-&gt;refcnt);
- }
-
- /* Must be holding cache_lock */
-@@ -65,7 +47,7 @@
- {
- BUG_ON(!obj);
- list_del(&amp;obj-&gt;list);
-- __object_put(obj);
-+ object_put(obj);
- cache_num--;
- }
-
-@@ -94,7 +76,7 @@
- strlcpy(obj-&gt;name, name, sizeof(obj-&gt;name));
- obj-&gt;id = id;
- obj-&gt;popularity = 0;
-- obj-&gt;refcnt = 1; /* The cache holds a reference */
-+ atomic_set(&amp;obj-&gt;refcnt, 1); /* The cache holds a reference */
-
- spin_lock_irqsave(&amp;cache_lock, flags);
- __cache_add(obj);
-@@ -119,7 +101,7 @@
- spin_lock_irqsave(&amp;cache_lock, flags);
- obj = __cache_find(id);
- if (obj)
-- __object_get(obj);
-+ object_get(obj);
- spin_unlock_irqrestore(&amp;cache_lock, flags);
- return obj;
- }
-</programlisting>
-</sect2>
-</sect1>
-
- <sect1 id="examples-lock-per-obj">
- <title>Protecting The Objects Themselves</title>
- <para>
-In these examples, we assumed that the objects (except the reference
-counts) never changed once they are created. If we wanted to allow
-the name to change, there are three possibilities:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-You can make <symbol>cache_lock</symbol> non-static, and tell people
-to grab that lock before changing the name in any object.
- </para>
- </listitem>
- <listitem>
- <para>
-You can provide a <function>cache_obj_rename</function> which grabs
-this lock and changes the name for the caller, and tell everyone to
-use that function.
- </para>
- </listitem>
- <listitem>
- <para>
-You can make the <symbol>cache_lock</symbol> protect only the cache
-itself, and use another lock to protect the name.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
-Theoretically, you can make the locks as fine-grained as one lock for
-every field, for every object. In practice, the most common variants
-are:
-</para>
- <itemizedlist>
- <listitem>
- <para>
-One lock which protects the infrastructure (the <symbol>cache</symbol>
-list in this example) and all the objects. This is what we have done
-so far.
- </para>
- </listitem>
- <listitem>
- <para>
-One lock which protects the infrastructure (including the list
-pointers inside the objects), and one lock inside the object which
-protects the rest of that object.
- </para>
- </listitem>
- <listitem>
- <para>
-Multiple locks to protect the infrastructure (eg. one lock per hash
-chain), possibly with a separate per-object lock.
- </para>
- </listitem>
- </itemizedlist>
-
-<para>
-Here is the "lock-per-object" implementation:
-</para>
-<programlisting>
---- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100
-+++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100
-@@ -6,11 +6,17 @@
-
- struct object
- {
-+ /* These two protected by cache_lock. */
- struct list_head list;
-+ int popularity;
-+
- atomic_t refcnt;
-+
-+ /* Doesn't change once created. */
- int id;
-+
-+ spinlock_t lock; /* Protects the name */
- char name[32];
-- int popularity;
- };
-
- static DEFINE_SPINLOCK(cache_lock);
-@@ -77,6 +84,7 @@
- obj-&gt;id = id;
- obj-&gt;popularity = 0;
- atomic_set(&amp;obj-&gt;refcnt, 1); /* The cache holds a reference */
-+ spin_lock_init(&amp;obj-&gt;lock);
-
- spin_lock_irqsave(&amp;cache_lock, flags);
- __cache_add(obj);
-</programlisting>
-
-<para>
-Note that I decide that the <structfield>popularity</structfield>
-count should be protected by the <symbol>cache_lock</symbol> rather
-than the per-object lock: this is because it (like the
-<structname>struct list_head</structname> inside the object) is
-logically part of the infrastructure. This way, I don't need to grab
-the lock of every object in <function>__cache_add</function> when
-seeking the least popular.
-</para>
-
-<para>
-I also decided that the <structfield>id</structfield> member is
-unchangeable, so I don't need to grab each object lock in
-<function>__cache_find()</function> to examine the
-<structfield>id</structfield>: the object lock is only used by a
-caller who wants to read or write the <structfield>name</structfield>
-field.
-</para>
-
-<para>
-Note also that I added a comment describing what data was protected by
-which locks. This is extremely important, as it describes the runtime
-behavior of the code, and can be hard to gain from just reading. And
-as Alan Cox says, <quote>Lock data, not code</quote>.
-</para>
-</sect1>
-</chapter>
-
- <chapter id="common-problems">
- <title>Common Problems</title>
- <sect1 id="deadlock">
- <title>Deadlock: Simple and Advanced</title>
-
- <para>
- There is a coding bug where a piece of code tries to grab a
- spinlock twice: it will spin forever, waiting for the lock to
- be released (spinlocks, rwlocks and mutexes are not
- recursive in Linux). This is trivial to diagnose: not a
- stay-up-five-nights-talk-to-fluffy-code-bunnies kind of
- problem.
- </para>
-
- <para>
- For a slightly more complex case, imagine you have a region
- shared by a softirq and user context. If you use a
- <function>spin_lock()</function> call to protect it, it is
- possible that the user context will be interrupted by the softirq
- while it holds the lock, and the softirq will then spin
- forever trying to get the same lock.
- </para>
-
- <para>
- Both of these are called deadlock, and as shown above, it can
- occur even with a single CPU (although not on UP compiles,
- since spinlocks vanish on kernel compiles with
- <symbol>CONFIG_SMP</symbol>=n. You'll still get data corruption
- in the second example).
- </para>
-
- <para>
- This complete lockup is easy to diagnose: on SMP boxes the
- watchdog timer or compiling with <symbol>DEBUG_SPINLOCK</symbol> set
- (<filename>include/linux/spinlock.h</filename>) will show this up
- immediately when it happens.
- </para>
-
- <para>
- A more complex problem is the so-called 'deadly embrace',
- involving two or more locks. Say you have a hash table: each
- entry in the table is a spinlock, and a chain of hashed
- objects. Inside a softirq handler, you sometimes want to
- alter an object from one place in the hash to another: you
- grab the spinlock of the old hash chain and the spinlock of
- the new hash chain, and delete the object from the old one,
- and insert it in the new one.
- </para>
-
- <para>
- There are two problems here. First, if your code ever
- tries to move the object to the same chain, it will deadlock
- with itself as it tries to lock it twice. Secondly, if the
- same softirq on another CPU is trying to move another object
- in the reverse direction, the following could happen:
- </para>
-
- <table>
- <title>Consequences</title>
-
- <tgroup cols="2" align="left">
-
- <thead>
- <row>
- <entry>CPU 1</entry>
- <entry>CPU 2</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Grab lock A -&gt; OK</entry>
- <entry>Grab lock B -&gt; OK</entry>
- </row>
- <row>
- <entry>Grab lock B -&gt; spin</entry>
- <entry>Grab lock A -&gt; spin</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- The two CPUs will spin forever, waiting for the other to give up
- their lock. It will look, smell, and feel like a crash.
- </para>
- </sect1>
-
- <sect1 id="techs-deadlock-prevent">
- <title>Preventing Deadlock</title>
-
- <para>
- Textbooks will tell you that if you always lock in the same
- order, you will never get this kind of deadlock. Practice
- will tell you that this approach doesn't scale: when I
- create a new lock, I don't understand enough of the kernel
- to figure out where in the 5000 lock hierarchy it will fit.
- </para>
-
- <para>
- The best locks are encapsulated: they never get exposed in
- headers, and are never held around calls to non-trivial
- functions outside the same file. You can read through this
- code and see that it will never deadlock, because it never
- tries to grab another lock while it has that one. People
- using your code don't even need to know you are using a
- lock.
- </para>
-
- <para>
- A classic problem here is when you provide callbacks or
- hooks: if you call these with the lock held, you risk simple
- deadlock, or a deadly embrace (who knows what the callback
- will do?). Remember, the other programmers are out to get
- you, so don't do this.
- </para>
-
- <sect2 id="techs-deadlock-overprevent">
- <title>Overzealous Prevention Of Deadlocks</title>
-
- <para>
- Deadlocks are problematic, but not as bad as data
- corruption. Code which grabs a read lock, searches a list,
- fails to find what it wants, drops the read lock, grabs a
- write lock and inserts the object has a race condition.
- </para>
-
- <para>
- If you don't see why, please stay the fuck away from my code.
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="racing-timers">
- <title>Racing Timers: A Kernel Pastime</title>
-
- <para>
- Timers can produce their own special problems with races.
- Consider a collection of objects (list, hash, etc) where each
- object has a timer which is due to destroy it.
- </para>
-
- <para>
- If you want to destroy the entire collection (say on module
- removal), you might do the following:
- </para>
-
- <programlisting>
- /* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE
- HUNGARIAN NOTATION */
- spin_lock_bh(&amp;list_lock);
-
- while (list) {
- struct foo *next = list-&gt;next;
- del_timer(&amp;list-&gt;timer);
- kfree(list);
- list = next;
- }
-
- spin_unlock_bh(&amp;list_lock);
- </programlisting>
-
- <para>
- Sooner or later, this will crash on SMP, because a timer can
- have just gone off before the <function>spin_lock_bh()</function>,
- and it will only get the lock after we
- <function>spin_unlock_bh()</function>, and then try to free
- the element (which has already been freed!).
- </para>
-
- <para>
- This can be avoided by checking the result of
- <function>del_timer()</function>: if it returns
- <returnvalue>1</returnvalue>, the timer has been deleted.
- If <returnvalue>0</returnvalue>, it means (in this
- case) that it is currently running, so we can do:
- </para>
-
- <programlisting>
- retry:
- spin_lock_bh(&amp;list_lock);
-
- while (list) {
- struct foo *next = list-&gt;next;
- if (!del_timer(&amp;list-&gt;timer)) {
- /* Give timer a chance to delete this */
- spin_unlock_bh(&amp;list_lock);
- goto retry;
- }
- kfree(list);
- list = next;
- }
-
- spin_unlock_bh(&amp;list_lock);
- </programlisting>
-
- <para>
- Another common problem is deleting timers which restart
- themselves (by calling <function>add_timer()</function> at the end
- of their timer function). Because this is a fairly common case
- which is prone to races, you should use <function>del_timer_sync()</function>
- (<filename class="headerfile">include/linux/timer.h</filename>)
- to handle this case. It returns the number of times the timer
- had to be deleted before we finally stopped it from adding itself back
- in.
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="Efficiency">
- <title>Locking Speed</title>
-
- <para>
-There are three main things to worry about when considering speed of
-some code which does locking. First is concurrency: how many things
-are going to be waiting while someone else is holding a lock. Second
-is the time taken to actually acquire and release an uncontended lock.
-Third is using fewer, or smarter locks. I'm assuming that the lock is
-used fairly often: otherwise, you wouldn't be concerned about
-efficiency.
-</para>
- <para>
-Concurrency depends on how long the lock is usually held: you should
-hold the lock for as long as needed, but no longer. In the cache
-example, we always create the object without the lock held, and then
-grab the lock only when we are ready to insert it in the list.
-</para>
- <para>
-Acquisition times depend on how much damage the lock operations do to
-the pipeline (pipeline stalls) and how likely it is that this CPU was
-the last one to grab the lock (ie. is the lock cache-hot for this
-CPU): on a machine with more CPUs, this likelihood drops fast.
-Consider a 700MHz Intel Pentium III: an instruction takes about 0.7ns,
-an atomic increment takes about 58ns, a lock which is cache-hot on
-this CPU takes 160ns, and a cacheline transfer from another CPU takes
-an additional 170 to 360ns. (These figures from Paul McKenney's
-<ulink url="http://www.linuxjournal.com/article.php?sid=6993"> Linux
-Journal RCU article</ulink>).
-</para>
- <para>
-These two aims conflict: holding a lock for a short time might be done
-by splitting locks into parts (such as in our final per-object-lock
-example), but this increases the number of lock acquisitions, and the
-results are often slower than having a single lock. This is another
-reason to advocate locking simplicity.
-</para>
- <para>
-The third concern is addressed below: there are some methods to reduce
-the amount of locking which needs to be done.
-</para>
-
- <sect1 id="efficiency-rwlocks">
- <title>Read/Write Lock Variants</title>
-
- <para>
- Both spinlocks and mutexes have read/write variants:
- <type>rwlock_t</type> and <structname>struct rw_semaphore</structname>.
- These divide users into two classes: the readers and the writers. If
- you are only reading the data, you can get a read lock, but to write to
- the data you need the write lock. Many people can hold a read lock,
- but a writer must be sole holder.
- </para>
-
- <para>
- If your code divides neatly along reader/writer lines (as our
- cache code does), and the lock is held by readers for
- significant lengths of time, using these locks can help. They
- are slightly slower than the normal locks though, so in practice
- <type>rwlock_t</type> is not usually worthwhile.
- </para>
- </sect1>
-
- <sect1 id="efficiency-read-copy-update">
- <title>Avoiding Locks: Read Copy Update</title>
-
- <para>
- There is a special method of read/write locking called Read Copy
- Update. Using RCU, the readers can avoid taking a lock
- altogether: as we expect our cache to be read more often than
- updated (otherwise the cache is a waste of time), it is a
- candidate for this optimization.
- </para>
-
- <para>
- How do we get rid of read locks? Getting rid of read locks
- means that writers may be changing the list underneath the
- readers. That is actually quite simple: we can read a linked
- list while an element is being added if the writer adds the
- element very carefully. For example, adding
- <symbol>new</symbol> to a single linked list called
- <symbol>list</symbol>:
- </para>
-
- <programlisting>
- new-&gt;next = list-&gt;next;
- wmb();
- list-&gt;next = new;
- </programlisting>
-
- <para>
- The <function>wmb()</function> is a write memory barrier. It
- ensures that the first operation (setting the new element's
- <symbol>next</symbol> pointer) is complete and will be seen by
- all CPUs, before the second operation is (putting the new
- element into the list). This is important, since modern
- compilers and modern CPUs can both reorder instructions unless
- told otherwise: we want a reader to either not see the new
- element at all, or see the new element with the
- <symbol>next</symbol> pointer correctly pointing at the rest of
- the list.
- </para>
- <para>
- Fortunately, there is a function to do this for standard
- <structname>struct list_head</structname> lists:
- <function>list_add_rcu()</function>
- (<filename>include/linux/list.h</filename>).
- </para>
- <para>
- Removing an element from the list is even simpler: we replace
- the pointer to the old element with a pointer to its successor,
- and readers will either see it, or skip over it.
- </para>
- <programlisting>
- list-&gt;next = old-&gt;next;
- </programlisting>
- <para>
- There is <function>list_del_rcu()</function>
- (<filename>include/linux/list.h</filename>) which does this (the
- normal version poisons the old object, which we don't want).
- </para>
- <para>
- The reader must also be careful: some CPUs can look through the
- <symbol>next</symbol> pointer to start reading the contents of
- the next element early, but don't realize that the pre-fetched
- contents is wrong when the <symbol>next</symbol> pointer changes
- underneath them. Once again, there is a
- <function>list_for_each_entry_rcu()</function>
- (<filename>include/linux/list.h</filename>) to help you. Of
- course, writers can just use
- <function>list_for_each_entry()</function>, since there cannot
- be two simultaneous writers.
- </para>
- <para>
- Our final dilemma is this: when can we actually destroy the
- removed element? Remember, a reader might be stepping through
- this element in the list right now: if we free this element and
- the <symbol>next</symbol> pointer changes, the reader will jump
- off into garbage and crash. We need to wait until we know that
- all the readers who were traversing the list when we deleted the
- element are finished. We use <function>call_rcu()</function> to
- register a callback which will actually destroy the object once
- all pre-existing readers are finished. Alternatively,
- <function>synchronize_rcu()</function> may be used to block until
- all pre-existing are finished.
- </para>
- <para>
- But how does Read Copy Update know when the readers are
- finished? The method is this: firstly, the readers always
- traverse the list inside
- <function>rcu_read_lock()</function>/<function>rcu_read_unlock()</function>
- pairs: these simply disable preemption so the reader won't go to
- sleep while reading the list.
- </para>
- <para>
- RCU then waits until every other CPU has slept at least once:
- since readers cannot sleep, we know that any readers which were
- traversing the list during the deletion are finished, and the
- callback is triggered. The real Read Copy Update code is a
- little more optimized than this, but this is the fundamental
- idea.
- </para>
-
-<programlisting>
---- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100
-+++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100
-@@ -1,15 +1,18 @@
- #include &lt;linux/list.h&gt;
- #include &lt;linux/slab.h&gt;
- #include &lt;linux/string.h&gt;
-+#include &lt;linux/rcupdate.h&gt;
- #include &lt;linux/mutex.h&gt;
- #include &lt;asm/errno.h&gt;
-
- struct object
- {
-- /* These two protected by cache_lock. */
-+ /* This is protected by RCU */
- struct list_head list;
- int popularity;
-
-+ struct rcu_head rcu;
-+
- atomic_t refcnt;
-
- /* Doesn't change once created. */
-@@ -40,7 +43,7 @@
- {
- struct object *i;
-
-- list_for_each_entry(i, &amp;cache, list) {
-+ list_for_each_entry_rcu(i, &amp;cache, list) {
- if (i-&gt;id == id) {
- i-&gt;popularity++;
- return i;
-@@ -49,19 +52,25 @@
- return NULL;
- }
-
-+/* Final discard done once we know no readers are looking. */
-+static void cache_delete_rcu(void *arg)
-+{
-+ object_put(arg);
-+}
-+
- /* Must be holding cache_lock */
- static void __cache_delete(struct object *obj)
- {
- BUG_ON(!obj);
-- list_del(&amp;obj-&gt;list);
-- object_put(obj);
-+ list_del_rcu(&amp;obj-&gt;list);
- cache_num--;
-+ call_rcu(&amp;obj-&gt;rcu, cache_delete_rcu);
- }
-
- /* Must be holding cache_lock */
- static void __cache_add(struct object *obj)
- {
-- list_add(&amp;obj-&gt;list, &amp;cache);
-+ list_add_rcu(&amp;obj-&gt;list, &amp;cache);
- if (++cache_num > MAX_CACHE_SIZE) {
- struct object *i, *outcast = NULL;
- list_for_each_entry(i, &amp;cache, list) {
-@@ -104,12 +114,11 @@
- struct object *cache_find(int id)
- {
- struct object *obj;
-- unsigned long flags;
-
-- spin_lock_irqsave(&amp;cache_lock, flags);
-+ rcu_read_lock();
- obj = __cache_find(id);
- if (obj)
- object_get(obj);
-- spin_unlock_irqrestore(&amp;cache_lock, flags);
-+ rcu_read_unlock();
- return obj;
- }
-</programlisting>
-
-<para>
-Note that the reader will alter the
-<structfield>popularity</structfield> member in
-<function>__cache_find()</function>, and now it doesn't hold a lock.
-One solution would be to make it an <type>atomic_t</type>, but for
-this usage, we don't really care about races: an approximate result is
-good enough, so I didn't change it.
-</para>
-
-<para>
-The result is that <function>cache_find()</function> requires no
-synchronization with any other functions, so is almost as fast on SMP
-as it would be on UP.
-</para>
-
-<para>
-There is a further optimization possible here: remember our original
-cache code, where there were no reference counts and the caller simply
-held the lock whenever using the object? This is still possible: if
-you hold the lock, no one can delete the object, so you don't need to
-get and put the reference count.
-</para>
-
-<para>
-Now, because the 'read lock' in RCU is simply disabling preemption, a
-caller which always has preemption disabled between calling
-<function>cache_find()</function> and
-<function>object_put()</function> does not need to actually get and
-put the reference count: we could expose
-<function>__cache_find()</function> by making it non-static, and
-such callers could simply call that.
-</para>
-<para>
-The benefit here is that the reference count is not written to: the
-object is not altered in any way, which is much faster on SMP
-machines due to caching.
-</para>
- </sect1>
-
- <sect1 id="per-cpu">
- <title>Per-CPU Data</title>
-
- <para>
- Another technique for avoiding locking which is used fairly
- widely is to duplicate information for each CPU. For example,
- if you wanted to keep a count of a common condition, you could
- use a spin lock and a single counter. Nice and simple.
- </para>
-
- <para>
- If that was too slow (it's usually not, but if you've got a
- really big machine to test on and can show that it is), you
- could instead use a counter for each CPU, then none of them need
- an exclusive lock. See <function>DEFINE_PER_CPU()</function>,
- <function>get_cpu_var()</function> and
- <function>put_cpu_var()</function>
- (<filename class="headerfile">include/linux/percpu.h</filename>).
- </para>
-
- <para>
- Of particular use for simple per-cpu counters is the
- <type>local_t</type> type, and the
- <function>cpu_local_inc()</function> and related functions,
- which are more efficient than simple code on some architectures
- (<filename class="headerfile">include/asm/local.h</filename>).
- </para>
-
- <para>
- Note that there is no simple, reliable way of getting an exact
- value of such a counter, without introducing more locks. This
- is not a problem for some uses.
- </para>
- </sect1>
-
- <sect1 id="mostly-hardirq">
- <title>Data Which Mostly Used By An IRQ Handler</title>
-
- <para>
- If data is always accessed from within the same IRQ handler, you
- don't need a lock at all: the kernel already guarantees that the
- irq handler will not run simultaneously on multiple CPUs.
- </para>
- <para>
- Manfred Spraul points out that you can still do this, even if
- the data is very occasionally accessed in user context or
- softirqs/tasklets. The irq handler doesn't use a lock, and
- all other accesses are done as so:
- </para>
-
-<programlisting>
- spin_lock(&amp;lock);
- disable_irq(irq);
- ...
- enable_irq(irq);
- spin_unlock(&amp;lock);
-</programlisting>
- <para>
- The <function>disable_irq()</function> prevents the irq handler
- from running (and waits for it to finish if it's currently
- running on other CPUs). The spinlock prevents any other
- accesses happening at the same time. Naturally, this is slower
- than just a <function>spin_lock_irq()</function> call, so it
- only makes sense if this type of access happens extremely
- rarely.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="sleeping-things">
- <title>What Functions Are Safe To Call From Interrupts?</title>
-
- <para>
- Many functions in the kernel sleep (ie. call schedule())
- directly or indirectly: you can never call them while holding a
- spinlock, or with preemption disabled. This also means you need
- to be in user context: calling them from an interrupt is illegal.
- </para>
-
- <sect1 id="sleeping">
- <title>Some Functions Which Sleep</title>
-
- <para>
- The most common ones are listed below, but you usually have to
- read the code to find out if other calls are safe. If everyone
- else who calls it can sleep, you probably need to be able to
- sleep, too. In particular, registration and deregistration
- functions usually expect to be called from user context, and can
- sleep.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Accesses to
- <firstterm linkend="gloss-userspace">userspace</firstterm>:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <function>copy_from_user()</function>
- </para>
- </listitem>
- <listitem>
- <para>
- <function>copy_to_user()</function>
- </para>
- </listitem>
- <listitem>
- <para>
- <function>get_user()</function>
- </para>
- </listitem>
- <listitem>
- <para>
- <function>put_user()</function>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- <function>kmalloc(GFP_KERNEL)</function>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <function>mutex_lock_interruptible()</function> and
- <function>mutex_lock()</function>
- </para>
- <para>
- There is a <function>mutex_trylock()</function> which does not
- sleep. Still, it must not be used inside interrupt context since
- its implementation is not safe for that.
- <function>mutex_unlock()</function> will also never sleep.
- It cannot be used in interrupt context either since a mutex
- must be released by the same task that acquired it.
- </para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 id="dont-sleep">
- <title>Some Functions Which Don't Sleep</title>
-
- <para>
- Some functions are safe to call from any context, or holding
- almost any lock.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <function>printk()</function>
- </para>
- </listitem>
- <listitem>
- <para>
- <function>kfree()</function>
- </para>
- </listitem>
- <listitem>
- <para>
- <function>add_timer()</function> and <function>del_timer()</function>
- </para>
- </listitem>
- </itemizedlist>
- </sect1>
- </chapter>
-
- <chapter id="apiref-mutex">
- <title>Mutex API reference</title>
-!Iinclude/linux/mutex.h
-!Ekernel/locking/mutex.c
- </chapter>
-
- <chapter id="apiref-futex">
- <title>Futex API reference</title>
-!Ikernel/futex.c
- </chapter>
-
- <chapter id="references">
- <title>Further reading</title>
-
- <itemizedlist>
- <listitem>
- <para>
- <filename>Documentation/locking/spinlocks.txt</filename>:
- Linus Torvalds' spinlocking tutorial in the kernel sources.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Unix Systems for Modern Architectures: Symmetric
- Multiprocessing and Caching for Kernel Programmers:
- </para>
-
- <para>
- Curt Schimmel's very good introduction to kernel level
- locking (not written for Linux, but nearly everything
- applies). The book is expensive, but really worth every
- penny to understand SMP locking. [ISBN: 0201633388]
- </para>
- </listitem>
- </itemizedlist>
- </chapter>
-
- <chapter id="thanks">
- <title>Thanks</title>
-
- <para>
- Thanks to Telsa Gwynne for DocBooking, neatening and adding
- style.
- </para>
-
- <para>
- Thanks to Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul
- Mackerras, Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim
- Waugh, Pete Zaitcev, James Morris, Robert Love, Paul McKenney,
- John Ashby for proofreading, correcting, flaming, commenting.
- </para>
-
- <para>
- Thanks to the cabal for having no influence on this document.
- </para>
- </chapter>
-
- <glossary id="glossary">
- <title>Glossary</title>
-
- <glossentry id="gloss-preemption">
- <glossterm>preemption</glossterm>
- <glossdef>
- <para>
- Prior to 2.5, or when <symbol>CONFIG_PREEMPT</symbol> is
- unset, processes in user context inside the kernel would not
- preempt each other (ie. you had that CPU until you gave it up,
- except for interrupts). With the addition of
- <symbol>CONFIG_PREEMPT</symbol> in 2.5.4, this changed: when
- in user context, higher priority tasks can "cut in": spinlocks
- were changed to disable preemption, even on UP.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-bh">
- <glossterm>bh</glossterm>
- <glossdef>
- <para>
- Bottom Half: for historical reasons, functions with
- '_bh' in them often now refer to any software interrupt, e.g.
- <function>spin_lock_bh()</function> blocks any software interrupt
- on the current CPU. Bottom halves are deprecated, and will
- eventually be replaced by tasklets. Only one bottom half will be
- running at any time.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-hwinterrupt">
- <glossterm>Hardware Interrupt / Hardware IRQ</glossterm>
- <glossdef>
- <para>
- Hardware interrupt request. <function>in_irq()</function> returns
- <returnvalue>true</returnvalue> in a hardware interrupt handler.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-interruptcontext">
- <glossterm>Interrupt Context</glossterm>
- <glossdef>
- <para>
- Not user context: processing a hardware irq or software irq.
- Indicated by the <function>in_interrupt()</function> macro
- returning <returnvalue>true</returnvalue>.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-smp">
- <glossterm><acronym>SMP</acronym></glossterm>
- <glossdef>
- <para>
- Symmetric Multi-Processor: kernels compiled for multiple-CPU
- machines. (CONFIG_SMP=y).
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-softirq">
- <glossterm>Software Interrupt / softirq</glossterm>
- <glossdef>
- <para>
- Software interrupt handler. <function>in_irq()</function> returns
- <returnvalue>false</returnvalue>; <function>in_softirq()</function>
- returns <returnvalue>true</returnvalue>. Tasklets and softirqs
- both fall into the category of 'software interrupts'.
- </para>
- <para>
- Strictly speaking a softirq is one of up to 32 enumerated software
- interrupts which can run on multiple CPUs at once.
- Sometimes used to refer to tasklets as
- well (ie. all software interrupts).
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-tasklet">
- <glossterm>tasklet</glossterm>
- <glossdef>
- <para>
- A dynamically-registrable software interrupt,
- which is guaranteed to only run on one CPU at a time.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-timers">
- <glossterm>timer</glossterm>
- <glossdef>
- <para>
- A dynamically-registrable software interrupt, which is run at
- (or close to) a given time. When running, it is just like a
- tasklet (in fact, they are called from the TIMER_SOFTIRQ).
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-up">
- <glossterm><acronym>UP</acronym></glossterm>
- <glossdef>
- <para>
- Uni-Processor: Non-SMP. (CONFIG_SMP=n).
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-usercontext">
- <glossterm>User Context</glossterm>
- <glossdef>
- <para>
- The kernel executing on behalf of a particular process (ie. a
- system call or trap) or kernel thread. You can tell which
- process with the <symbol>current</symbol> macro.) Not to
- be confused with userspace. Can be interrupted by software or
- hardware interrupts.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry id="gloss-userspace">
- <glossterm>Userspace</glossterm>
- <glossdef>
- <para>
- A process executing its own code outside the kernel.
- </para>
- </glossdef>
- </glossentry>
-
- </glossary>
-</book>
-
diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl
deleted file mode 100644
index f3abca7ec53d..000000000000
--- a/Documentation/DocBook/kgdb.tmpl
+++ /dev/null
@@ -1,918 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="kgdbOnLinux">
- <bookinfo>
- <title>Using kgdb, kdb and the kernel debugger internals</title>
-
- <authorgroup>
- <author>
- <firstname>Jason</firstname>
- <surname>Wessel</surname>
- <affiliation>
- <address>
- <email>jason.wessel@windriver.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
- <copyright>
- <year>2008,2010</year>
- <holder>Wind River Systems, Inc.</holder>
- </copyright>
- <copyright>
- <year>2004-2005</year>
- <holder>MontaVista Software, Inc.</holder>
- </copyright>
- <copyright>
- <year>2004</year>
- <holder>Amit S. Kale</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This file is licensed under the terms of the GNU General Public License
- version 2. This program is licensed "as is" without any warranty of any
- kind, whether express or implied.
- </para>
-
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
- <chapter id="Introduction">
- <title>Introduction</title>
- <para>
- The kernel has two different debugger front ends (kdb and kgdb)
- which interface to the debug core. It is possible to use either
- of the debugger front ends and dynamically transition between them
- if you configure the kernel properly at compile and runtime.
- </para>
- <para>
- Kdb is simplistic shell-style interface which you can use on a
- system console with a keyboard or serial console. You can use it
- to inspect memory, registers, process lists, dmesg, and even set
- breakpoints to stop in a certain location. Kdb is not a source
- level debugger, although you can set breakpoints and execute some
- basic kernel run control. Kdb is mainly aimed at doing some
- analysis to aid in development or diagnosing kernel problems. You
- can access some symbols by name in kernel built-ins or in kernel
- modules if the code was built
- with <symbol>CONFIG_KALLSYMS</symbol>.
- </para>
- <para>
- Kgdb is intended to be used as a source level debugger for the
- Linux kernel. It is used along with gdb to debug a Linux kernel.
- The expectation is that gdb can be used to "break in" to the
- kernel to inspect memory, variables and look through call stack
- information similar to the way an application developer would use
- gdb to debug an application. It is possible to place breakpoints
- in kernel code and perform some limited execution stepping.
- </para>
- <para>
- Two machines are required for using kgdb. One of these machines is
- a development machine and the other is the target machine. The
- kernel to be debugged runs on the target machine. The development
- machine runs an instance of gdb against the vmlinux file which
- contains the symbols (not a boot image such as bzImage, zImage,
- uImage...). In gdb the developer specifies the connection
- parameters and connects to kgdb. The type of connection a
- developer makes with gdb depends on the availability of kgdb I/O
- modules compiled as built-ins or loadable kernel modules in the test
- machine's kernel.
- </para>
- </chapter>
- <chapter id="CompilingAKernel">
- <title>Compiling a kernel</title>
- <para>
- <itemizedlist>
- <listitem><para>In order to enable compilation of kdb, you must first enable kgdb.</para></listitem>
- <listitem><para>The kgdb test compile options are described in the kgdb test suite chapter.</para></listitem>
- </itemizedlist>
- </para>
- <sect1 id="CompileKGDB">
- <title>Kernel config options for kgdb</title>
- <para>
- To enable <symbol>CONFIG_KGDB</symbol> you should look under
- "Kernel hacking" / "Kernel debugging" and select "KGDB: kernel debugger".
- </para>
- <para>
- While it is not a hard requirement that you have symbols in your
- vmlinux file, gdb tends not to be very useful without the symbolic
- data, so you will want to turn
- on <symbol>CONFIG_DEBUG_INFO</symbol> which is called "Compile the
- kernel with debug info" in the config menu.
- </para>
- <para>
- It is advised, but not required, that you turn on the
- <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the
- kernel with frame pointers" in the config menu. This option
- inserts code to into the compiled executable which saves the frame
- information in registers or on the stack at different points which
- allows a debugger such as gdb to more accurately construct
- stack back traces while debugging the kernel.
- </para>
- <para>
- If the architecture that you are using supports the kernel option
- CONFIG_DEBUG_RODATA, you should consider turning it off. This
- option will prevent the use of software breakpoints because it
- marks certain regions of the kernel's memory space as read-only.
- If kgdb supports it for the architecture you are using, you can
- use hardware breakpoints if you desire to run with the
- CONFIG_DEBUG_RODATA option turned on, else you need to turn off
- this option.
- </para>
- <para>
- Next you should choose one of more I/O drivers to interconnect
- debugging host and debugged target. Early boot debugging requires
- a KGDB I/O driver that supports early debugging and the driver
- must be built into the kernel directly. Kgdb I/O driver
- configuration takes place via kernel or module parameters which
- you can learn more about in the in the section that describes the
- parameter "kgdboc".
- </para>
- <para>Here is an example set of .config symbols to enable or
- disable for kgdb:
- <itemizedlist>
- <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem>
- <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem>
- <listitem><para>CONFIG_KGDB=y</para></listitem>
- <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem>
- </itemizedlist>
- </para>
- </sect1>
- <sect1 id="CompileKDB">
- <title>Kernel config options for kdb</title>
- <para>Kdb is quite a bit more complex than the simple gdbstub
- sitting on top of the kernel's debug core. Kdb must implement a
- shell, and also adds some helper functions in other parts of the
- kernel, responsible for printing out interesting data such as what
- you would see if you ran "lsmod", or "ps". In order to build kdb
- into the kernel you follow the same steps as you would for kgdb.
- </para>
- <para>The main config option for kdb
- is <symbol>CONFIG_KGDB_KDB</symbol> which is called "KGDB_KDB:
- include kdb frontend for kgdb" in the config menu. In theory you
- would have already also selected an I/O driver such as the
- CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a
- serial port, when you were configuring kgdb.
- </para>
- <para>If you want to use a PS/2-style keyboard with kdb, you would
- select CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as
- input device" in the config menu. The CONFIG_KDB_KEYBOARD option
- is not used for anything in the gdb interface to kgdb. The
- CONFIG_KDB_KEYBOARD option only works with kdb.
- </para>
- <para>Here is an example set of .config symbols to enable/disable kdb:
- <itemizedlist>
- <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem>
- <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem>
- <listitem><para>CONFIG_KGDB=y</para></listitem>
- <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem>
- <listitem><para>CONFIG_KGDB_KDB=y</para></listitem>
- <listitem><para>CONFIG_KDB_KEYBOARD=y</para></listitem>
- </itemizedlist>
- </para>
- </sect1>
- </chapter>
- <chapter id="kgdbKernelArgs">
- <title>Kernel Debugger Boot Arguments</title>
- <para>This section describes the various runtime kernel
- parameters that affect the configuration of the kernel debugger.
- The following chapter covers using kdb and kgdb as well as
- providing some examples of the configuration parameters.</para>
- <sect1 id="kgdboc">
- <title>Kernel parameter: kgdboc</title>
- <para>The kgdboc driver was originally an abbreviation meant to
- stand for "kgdb over console". Today it is the primary mechanism
- to configure how to communicate from gdb to kgdb as well as the
- devices you want to use to interact with the kdb shell.
- </para>
- <para>For kgdb/gdb, kgdboc is designed to work with a single serial
- port. It is intended to cover the circumstance where you want to
- use a serial console as your primary console as well as using it to
- perform kernel debugging. It is also possible to use kgdb on a
- serial port which is not designated as a system console. Kgdboc
- may be configured as a kernel built-in or a kernel loadable module.
- You can only make use of <constant>kgdbwait</constant> and early
- debugging if you build kgdboc into the kernel as a built-in.
- </para>
- <para>Optionally you can elect to activate kms (Kernel Mode
- Setting) integration. When you use kms with kgdboc and you have a
- video driver that has atomic mode setting hooks, it is possible to
- enter the debugger on the graphics console. When the kernel
- execution is resumed, the previous graphics mode will be restored.
- This integration can serve as a useful tool to aid in diagnosing
- crashes or doing analysis of memory with kdb while allowing the
- full graphics console applications to run.
- </para>
- <sect2 id="kgdbocArgs">
- <title>kgdboc arguments</title>
- <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para>
- <para>The order listed above must be observed if you use any of the
- optional configurations together.
- </para>
- <para>Abbreviations:
- <itemizedlist>
- <listitem><para>kms = Kernel Mode Setting</para></listitem>
- <listitem><para>kbd = Keyboard</para></listitem>
- </itemizedlist>
- </para>
- <para>You can configure kgdboc to use the keyboard, and/or a serial
- device depending on if you are using kdb and/or kgdb, in one of the
- following scenarios. The order listed above must be observed if
- you use any of the optional configurations together. Using kms +
- only gdb is generally not a useful combination.</para>
- <sect3 id="kgdbocArgs1">
- <title>Using loadable module or built-in</title>
- <para>
- <orderedlist>
- <listitem><para>As a kernel built-in:</para>
- <para>Use the kernel boot argument: <constant>kgdboc=&lt;tty-device&gt;,[baud]</constant></para></listitem>
- <listitem>
- <para>As a kernel loadable module:</para>
- <para>Use the command: <constant>modprobe kgdboc kgdboc=&lt;tty-device&gt;,[baud]</constant></para>
- <para>Here are two examples of how you might format the kgdboc
- string. The first is for an x86 target using the first serial port.
- The second example is for the ARM Versatile AB using the second
- serial port.
- <orderedlist>
- <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem>
- <listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem>
- </orderedlist>
- </para>
- </listitem>
- </orderedlist></para>
- </sect3>
- <sect3 id="kgdbocArgs2">
- <title>Configure kgdboc at runtime with sysfs</title>
- <para>At run time you can enable or disable kgdboc by echoing a
- parameters into the sysfs. Here are two examples:</para>
- <orderedlist>
- <listitem><para>Enable kgdboc on ttyS0</para>
- <para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- <listitem><para>Disable kgdboc</para>
- <para><constant>echo "" &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- </orderedlist>
- <para>NOTE: You do not need to specify the baud if you are
- configuring the console on tty which is already configured or
- open.</para>
- </sect3>
- <sect3 id="kgdbocArgs3">
- <title>More examples</title>
- <para>You can configure kgdboc to use the keyboard, and/or a serial device
- depending on if you are using kdb and/or kgdb, in one of the
- following scenarios.
- <orderedlist>
- <listitem><para>kdb and kgdb over only a serial port</para>
- <para><constant>kgdboc=&lt;serial_device&gt;[,baud]</constant></para>
- <para>Example: <constant>kgdboc=ttyS0,115200</constant></para>
- </listitem>
- <listitem><para>kdb and kgdb with keyboard and a serial port</para>
- <para><constant>kgdboc=kbd,&lt;serial_device&gt;[,baud]</constant></para>
- <para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para>
- </listitem>
- <listitem><para>kdb with a keyboard</para>
- <para><constant>kgdboc=kbd</constant></para>
- </listitem>
- <listitem><para>kdb with kernel mode setting</para>
- <para><constant>kgdboc=kms,kbd</constant></para>
- </listitem>
- <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para>
- <para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para>
- </listitem>
- </orderedlist>
- </para>
- <para>NOTE: Kgdboc does not support interrupting the target via the
- gdb remote protocol. You must manually send a sysrq-g unless you
- have a proxy that splits console output to a terminal program.
- A console proxy has a separate TCP port for the debugger and a separate
- TCP port for the "human" console. The proxy can take care of sending
- the sysrq-g for you.
- </para>
- <para>When using kgdboc with no debugger proxy, you can end up
- connecting the debugger at one of two entry points. If an
- exception occurs after you have loaded kgdboc, a message should
- print on the console stating it is waiting for the debugger. In
- this case you disconnect your terminal program and then connect the
- debugger in its place. If you want to interrupt the target system
- and forcibly enter a debug session you have to issue a Sysrq
- sequence and then type the letter <constant>g</constant>. Then
- you disconnect the terminal session and connect gdb. Your options
- if you don't like this are to hack gdb to send the sysrq-g for you
- as well as on the initial connect, or to use a debugger proxy that
- allows an unmodified gdb to do the debugging.
- </para>
- </sect3>
- </sect2>
- </sect1>
- <sect1 id="kgdbwait">
- <title>Kernel parameter: kgdbwait</title>
- <para>
- The Kernel command line option <constant>kgdbwait</constant> makes
- kgdb wait for a debugger connection during booting of a kernel. You
- can only use this option if you compiled a kgdb I/O driver into the
- kernel and you specified the I/O driver configuration as a kernel
- command line option. The kgdbwait parameter should always follow the
- configuration parameter for the kgdb I/O driver in the kernel
- command line else the I/O driver will not be configured prior to
- asking the kernel to use it to wait.
- </para>
- <para>
- The kernel will stop and wait as early as the I/O driver and
- architecture allows when you use this option. If you build the
- kgdb I/O driver as a loadable kernel module kgdbwait will not do
- anything.
- </para>
- </sect1>
- <sect1 id="kgdbcon">
- <title>Kernel parameter: kgdbcon</title>
- <para> The kgdbcon feature allows you to see printk() messages
- inside gdb while gdb is connected to the kernel. Kdb does not make
- use of the kgdbcon feature.
- </para>
- <para>Kgdb supports using the gdb serial protocol to send console
- messages to the debugger when the debugger is connected and running.
- There are two ways to activate this feature.
- <orderedlist>
- <listitem><para>Activate with the kernel command line option:</para>
- <para><constant>kgdbcon</constant></para>
- </listitem>
- <listitem><para>Use sysfs before configuring an I/O driver</para>
- <para>
- <constant>echo 1 &gt; /sys/module/kgdb/parameters/kgdb_use_con</constant>
- </para>
- <para>
- NOTE: If you do this after you configure the kgdb I/O driver, the
- setting will not take effect until the next point the I/O is
- reconfigured.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
- active system console. An example of incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant>
- </para>
- <para>It is possible to use this option with kgdboc on a tty that is not a system console.
- </para>
- </sect1>
- <sect1 id="kgdbreboot">
- <title>Run time parameter: kgdbreboot</title>
- <para> The kgdbreboot feature allows you to change how the debugger
- deals with the reboot notification. You have 3 choices for the
- behavior. The default behavior is always set to 0.</para>
- <orderedlist>
- <listitem><para>echo -1 > /sys/module/debug_core/parameters/kgdbreboot</para>
- <para>Ignore the reboot notification entirely.</para>
- </listitem>
- <listitem><para>echo 0 > /sys/module/debug_core/parameters/kgdbreboot</para>
- <para>Send the detach message to any attached debugger client.</para>
- </listitem>
- <listitem><para>echo 1 > /sys/module/debug_core/parameters/kgdbreboot</para>
- <para>Enter the debugger on reboot notify.</para>
- </listitem>
- </orderedlist>
- </sect1>
- </chapter>
- <chapter id="usingKDB">
- <title>Using kdb</title>
- <para>
- </para>
- <sect1 id="quickKDBserial">
- <title>Quick start for kdb on a serial port</title>
- <para>This is a quick example of how to use kdb.</para>
- <para><orderedlist>
- <listitem><para>Configure kgdboc at boot using kernel parameters:
- <itemizedlist>
- <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem>
- </itemizedlist></para>
- <para>OR</para>
- <para>Configure kgdboc after the kernel has booted; assuming you are using a serial port console:
- <itemizedlist>
- <listitem><para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para>
- <itemizedlist>
- <listitem><para>When logged in as root or with a super user session you can run:</para>
- <para><constant>echo g &gt; /proc/sysrq-trigger</constant></para></listitem>
- <listitem><para>Example using minicom 2.2</para>
- <para>Press: <constant>Control-a</constant></para>
- <para>Press: <constant>f</constant></para>
- <para>Press: <constant>g</constant></para>
- </listitem>
- <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para>
- <para>Press: <constant>Control-]</constant></para>
- <para>Type in:<constant>send break</constant></para>
- <para>Press: <constant>Enter</constant></para>
- <para>Press: <constant>g</constant></para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para>
- <para>Some useful commands in kdb include:
- <itemizedlist>
- <listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem>
- <listitem><para>ps -- Displays only the active processes</para></listitem>
- <listitem><para>ps A -- Shows all the processes</para></listitem>
- <listitem><para>summary -- Shows kernel version info and memory usage</para></listitem>
- <listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem>
- <listitem><para>dmesg -- View the kernel syslog buffer</para></listitem>
- <listitem><para>go -- Continue the system</para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>When you are done using kdb you need to consider rebooting the
- system or using the "go" command to resuming normal kernel
- execution. If you have paused the kernel for a lengthy period of
- time, applications that rely on timely networking or anything to do
- with real wall clock time could be adversely affected, so you
- should take this into consideration when using the kernel
- debugger.</para>
- </listitem>
- </orderedlist></para>
- </sect1>
- <sect1 id="quickKDBkeyboard">
- <title>Quick start for kdb using a keyboard connected console</title>
- <para>This is a quick example of how to use kdb with a keyboard.</para>
- <para><orderedlist>
- <listitem><para>Configure kgdboc at boot using kernel parameters:
- <itemizedlist>
- <listitem><para><constant>kgdboc=kbd</constant></para></listitem>
- </itemizedlist></para>
- <para>OR</para>
- <para>Configure kgdboc after the kernel has booted:
- <itemizedlist>
- <listitem><para><constant>echo kbd &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para>
- <itemizedlist>
- <listitem><para>When logged in as root or with a super user session you can run:</para>
- <para><constant>echo g &gt; /proc/sysrq-trigger</constant></para></listitem>
- <listitem><para>Example using a laptop keyboard</para>
- <para>Press and hold down: <constant>Alt</constant></para>
- <para>Press and hold down: <constant>Fn</constant></para>
- <para>Press and release the key with the label: <constant>SysRq</constant></para>
- <para>Release: <constant>Fn</constant></para>
- <para>Press and release: <constant>g</constant></para>
- <para>Release: <constant>Alt</constant></para>
- </listitem>
- <listitem><para>Example using a PS/2 101-key keyboard</para>
- <para>Press and hold down: <constant>Alt</constant></para>
- <para>Press and release the key with the label: <constant>SysRq</constant></para>
- <para>Press and release: <constant>g</constant></para>
- <para>Release: <constant>Alt</constant></para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para>
- </listitem>
- </orderedlist></para>
- </sect1>
- </chapter>
- <chapter id="EnableKGDB">
- <title>Using kgdb / gdb</title>
- <para>In order to use kgdb you must activate it by passing
- configuration information to one of the kgdb I/O drivers. If you
- do not pass any configuration information kgdb will not do anything
- at all. Kgdb will only actively hook up to the kernel trap hooks
- if a kgdb I/O driver is loaded and configured. If you unconfigure
- a kgdb I/O driver, kgdb will unregister all the kernel hook points.
- </para>
- <para> All kgdb I/O drivers can be reconfigured at run time, if
- <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol>
- are enabled, by echo'ing a new config string to
- <constant>/sys/module/&lt;driver&gt;/parameter/&lt;option&gt;</constant>.
- The driver can be unconfigured by passing an empty string. You cannot
- change the configuration while the debugger is attached. Make sure
- to detach the debugger with the <constant>detach</constant> command
- prior to trying to unconfigure a kgdb I/O driver.
- </para>
- <sect1 id="ConnectingGDB">
- <title>Connecting with gdb to a serial port</title>
- <orderedlist>
- <listitem><para>Configure kgdboc</para>
- <para>Configure kgdboc at boot using kernel parameters:
- <itemizedlist>
- <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem>
- </itemizedlist></para>
- <para>OR</para>
- <para>Configure kgdboc after the kernel has booted:
- <itemizedlist>
- <listitem><para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
- </itemizedlist></para>
- </listitem>
- <listitem>
- <para>Stop kernel execution (break into the debugger)</para>
- <para>In order to connect to gdb via kgdboc, the kernel must
- first be stopped. There are several ways to stop the kernel which
- include using kgdbwait as a boot argument, via a sysrq-g, or running
- the kernel until it takes an exception where it waits for the
- debugger to attach.
- <itemizedlist>
- <listitem><para>When logged in as root or with a super user session you can run:</para>
- <para><constant>echo g &gt; /proc/sysrq-trigger</constant></para></listitem>
- <listitem><para>Example using minicom 2.2</para>
- <para>Press: <constant>Control-a</constant></para>
- <para>Press: <constant>f</constant></para>
- <para>Press: <constant>g</constant></para>
- </listitem>
- <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para>
- <para>Press: <constant>Control-]</constant></para>
- <para>Type in:<constant>send break</constant></para>
- <para>Press: <constant>Enter</constant></para>
- <para>Press: <constant>g</constant></para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>Connect from gdb</para>
- <para>
- Example (using a directly connected port):
- </para>
- <programlisting>
- % gdb ./vmlinux
- (gdb) set remotebaud 115200
- (gdb) target remote /dev/ttyS0
- </programlisting>
- <para>
- Example (kgdb to a terminal server on TCP port 2012):
- </para>
- <programlisting>
- % gdb ./vmlinux
- (gdb) target remote 192.168.2.2:2012
- </programlisting>
- <para>
- Once connected, you can debug a kernel the way you would debug an
- application program.
- </para>
- <para>
- If you are having problems connecting or something is going
- seriously wrong while debugging, it will most often be the case
- that you want to enable gdb to be verbose about its target
- communications. You do this prior to issuing the <constant>target
- remote</constant> command by typing in: <constant>set debug remote 1</constant>
- </para>
- </listitem>
- </orderedlist>
- <para>Remember if you continue in gdb, and need to "break in" again,
- you need to issue an other sysrq-g. It is easy to create a simple
- entry point by putting a breakpoint at <constant>sys_sync</constant>
- and then you can run "sync" from a shell or script to break into the
- debugger.</para>
- </sect1>
- </chapter>
- <chapter id="switchKdbKgdb">
- <title>kgdb and kdb interoperability</title>
- <para>It is possible to transition between kdb and kgdb dynamically.
- The debug core will remember which you used the last time and
- automatically start in the same mode.</para>
- <sect1>
- <title>Switching between kdb and kgdb</title>
- <sect2>
- <title>Switching from kgdb to kdb</title>
- <para>
- There are two ways to switch from kgdb to kdb: you can use gdb to
- issue a maintenance packet, or you can blindly type the command $3#33.
- Whenever the kernel debugger stops in kgdb mode it will print the
- message <constant>KGDB or $3#33 for KDB</constant>. It is important
- to note that you have to type the sequence correctly in one pass.
- You cannot type a backspace or delete because kgdb will interpret
- that as part of the debug stream.
- <orderedlist>
- <listitem><para>Change from kgdb to kdb by blindly typing:</para>
- <para><constant>$3#33</constant></para></listitem>
- <listitem><para>Change from kgdb to kdb with gdb</para>
- <para><constant>maintenance packet 3</constant></para>
- <para>NOTE: Now you must kill gdb. Typically you press control-z and
- issue the command: kill -9 %</para></listitem>
- </orderedlist>
- </para>
- </sect2>
- <sect2>
- <title>Change from kdb to kgdb</title>
- <para>There are two ways you can change from kdb to kgdb. You can
- manually enter kgdb mode by issuing the kgdb command from the kdb
- shell prompt, or you can connect gdb while the kdb shell prompt is
- active. The kdb shell looks for the typical first commands that gdb
- would issue with the gdb remote protocol and if it sees one of those
- commands it automatically changes into kgdb mode.</para>
- <orderedlist>
- <listitem><para>From kdb issue the command:</para>
- <para><constant>kgdb</constant></para>
- <para>Now disconnect your terminal program and connect gdb in its place</para></listitem>
- <listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem>
- </orderedlist>
- </sect2>
- </sect1>
- <sect1>
- <title>Running kdb commands from gdb</title>
- <para>It is possible to run a limited set of kdb commands from gdb,
- using the gdb monitor command. You don't want to execute any of the
- run control or breakpoint operations, because it can disrupt the
- state of the kernel debugger. You should be using gdb for
- breakpoints and run control operations if you have gdb connected.
- The more useful commands to run are things like lsmod, dmesg, ps or
- possibly some of the memory information commands. To see all the kdb
- commands you can run <constant>monitor help</constant>.</para>
- <para>Example:
- <informalexample><programlisting>
-(gdb) monitor ps
-1 idle process (state I) and
-27 sleeping system daemon (state M) processes suppressed,
-use 'ps A' to see all.
-Task Addr Pid Parent [*] cpu State Thread Command
-
-0xc78291d0 1 0 0 0 S 0xc7829404 init
-0xc7954150 942 1 0 0 S 0xc7954384 dropbear
-0xc78789c0 944 1 0 0 S 0xc7878bf4 sh
-(gdb)
- </programlisting></informalexample>
- </para>
- </sect1>
- </chapter>
- <chapter id="KGDBTestSuite">
- <title>kgdb Test Suite</title>
- <para>
- When kgdb is enabled in the kernel config you can also elect to
- enable the config parameter KGDB_TESTS. Turning this on will
- enable a special kgdb I/O module which is designed to test the
- kgdb internal functions.
- </para>
- <para>
- The kgdb tests are mainly intended for developers to test the kgdb
- internals as well as a tool for developing a new kgdb architecture
- specific implementation. These tests are not really for end users
- of the Linux kernel. The primary source of documentation would be
- to look in the drivers/misc/kgdbts.c file.
- </para>
- <para>
- The kgdb test suite can also be configured at compile time to run
- the core set of tests by setting the kernel config parameter
- KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
- regression testing and does not require modifying the kernel boot
- config arguments. If this is turned on, the kgdb test suite can
- be disabled by specifying "kgdbts=" as a kernel boot argument.
- </para>
- </chapter>
- <chapter id="CommonBackEndReq">
- <title>Kernel Debugger Internals</title>
- <sect1 id="kgdbArchitecture">
- <title>Architecture Specifics</title>
- <para>
- The kernel debugger is organized into a number of components:
- <orderedlist>
- <listitem><para>The debug core</para>
- <para>
- The debug core is found in kernel/debugger/debug_core.c. It contains:
- <itemizedlist>
- <listitem><para>A generic OS exception handler which includes
- sync'ing the processors into a stopped state on an multi-CPU
- system.</para></listitem>
- <listitem><para>The API to talk to the kgdb I/O drivers</para></listitem>
- <listitem><para>The API to make calls to the arch-specific kgdb implementation</para></listitem>
- <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>
- <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>
- <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem>
- <listitem><para>The structures and callback API for atomic kernel mode setting.</para>
- <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>kgdb arch-specific implementation</para>
- <para>
- This implementation is generally found in arch/*/kernel/kgdb.c.
- As an example, arch/x86/kernel/kgdb.c contains the specifics to
- implement HW breakpoint as well as the initialization to
- dynamically register and unregister for the trap handlers on
- this architecture. The arch-specific portion implements:
- <itemizedlist>
- <listitem><para>contains an arch-specific trap catcher which
- invokes kgdb_handle_exception() to start kgdb about doing its
- work</para></listitem>
- <listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem>
- <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem>
- <listitem><para>Any special exception handling and cleanup</para></listitem>
- <listitem><para>NMI exception handling and cleanup</para></listitem>
- <listitem><para>(optional) HW breakpoints</para></listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem><para>gdbstub frontend (aka kgdb)</para>
- <para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para>
- <itemizedlist>
- <listitem><para>All the logic to implement the gdb serial protocol</para></listitem>
- </itemizedlist>
- </listitem>
- <listitem><para>kdb frontend</para>
- <para>The kdb debugger shell is broken down into a number of
- components. The kdb core is located in kernel/debug/kdb. There
- are a number of helper functions in some of the other kernel
- components to make it possible for kdb to examine and report
- information about the kernel without taking locks that could
- cause a kernel deadlock. The kdb core contains implements the following functionality.</para>
- <itemizedlist>
- <listitem><para>A simple shell</para></listitem>
- <listitem><para>The kdb core command set</para></listitem>
- <listitem><para>A registration API to register additional kdb shell commands.</para>
- <itemizedlist>
- <listitem><para>A good example of a self-contained kdb module
- is the "ftdump" command for dumping the ftrace buffer. See:
- kernel/trace/trace_kdb.c</para></listitem>
- <listitem><para>For an example of how to dynamically register
- a new kdb command you can build the kdb_hello.ko kernel module
- from samples/kdb/kdb_hello.c. To build this example you can
- set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
- config. Later run "modprobe kdb_hello" and the next time you
- enter the kdb shell, you can run the "hello"
- command.</para></listitem>
- </itemizedlist></listitem>
- <listitem><para>The implementation for kdb_printf() which
- emits messages directly to I/O drivers, bypassing the kernel
- log.</para></listitem>
- <listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem>
- </itemizedlist>
- </listitem>
- <listitem><para>kgdb I/O driver</para>
- <para>
- Each kgdb I/O driver has to provide an implementation for the following:
- <itemizedlist>
- <listitem><para>configuration via built-in or module</para></listitem>
- <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>
- <listitem><para>read and write character interface</para></listitem>
- <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>
- <listitem><para>(optional) Early debug methodology</para></listitem>
- </itemizedlist>
- Any given kgdb I/O driver has to operate very closely with the
- hardware and must do it in such a way that does not enable
- interrupts or change other parts of the system context without
- completely restoring them. The kgdb core will repeatedly "poll"
- a kgdb I/O driver for characters when it needs input. The I/O
- driver is expected to return immediately if there is no data
- available. Doing so allows for the future possibility to touch
- watchdog hardware in such a way as to have a target system not
- reset when these are enabled.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- If you are intent on adding kgdb architecture specific support
- for a new architecture, the architecture should define
- <constant>HAVE_ARCH_KGDB</constant> in the architecture specific
- Kconfig file. This will enable kgdb for the architecture, and
- at that point you must create an architecture specific kgdb
- implementation.
- </para>
- <para>
- There are a few flags which must be set on every architecture in
- their &lt;asm/kgdb.h&gt; file. These are:
- <itemizedlist>
- <listitem>
- <para>
- NUMREGBYTES: The size in bytes of all of the registers, so
- that we can ensure they will all fit into a packet.
- </para>
- </listitem>
- <listitem>
- <para>
- BUFMAX: The size in bytes of the buffer GDB will read into.
- This must be larger than NUMREGBYTES.
- </para>
- </listitem>
- <listitem>
- <para>
- CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
- flush_cache_range or flush_icache_range. On some architectures,
- these functions may not be safe to call on SMP since we keep other
- CPUs in a holding pattern.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- There are also the following functions for the common backend,
- found in kernel/kgdb.c, that must be supplied by the
- architecture-specific backend unless marked as (optional), in
- which case a default function maybe used if the architecture
- does not need to provide a specific implementation.
- </para>
-!Iinclude/linux/kgdb.h
- </sect1>
- <sect1 id="kgdbocDesign">
- <title>kgdboc internals</title>
- <sect2>
- <title>kgdboc and uarts</title>
- <para>
- The kgdboc driver is actually a very thin driver that relies on the
- underlying low level to the hardware driver having "polling hooks"
- to which the tty driver is attached. In the initial
- implementation of kgdboc the serial_core was changed to expose a
- low level UART hook for doing polled mode reading and writing of a
- single character while in an atomic context. When kgdb makes an I/O
- request to the debugger, kgdboc invokes a callback in the serial
- core which in turn uses the callback in the UART driver.</para>
- <para>
- When using kgdboc with a UART, the UART driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>
-#ifdef CONFIG_CONSOLE_POLL
- .poll_get_char = serial8250_get_poll_char,
- .poll_put_char = serial8250_put_poll_char,
-#endif
- </programlisting>
- Any implementation specifics around creating a polling driver use the
- <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
- Keep in mind that polling hooks have to be implemented in such a way
- that they can be called from an atomic context and have to restore
- the state of the UART chip on return such that the system can return
- to normal when the debugger detaches. You need to be very careful
- with any kind of lock you consider, because failing here is most likely
- going to mean pressing the reset button.
- </para>
- </sect2>
- <sect2 id="kgdbocKbd">
- <title>kgdboc and keyboards</title>
- <para>The kgdboc driver contains logic to configure communications
- with an attached keyboard. The keyboard infrastructure is only
- compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the
- kernel configuration.</para>
- <para>The core polled keyboard driver driver for PS/2 type keyboards
- is in drivers/char/kdb_keyboard.c. This driver is hooked into the
- debug core when kgdboc populates the callback in the array
- called <constant>kdb_poll_funcs[]</constant>. The
- kdb_get_kbd_char() is the top-level function which polls hardware
- for single character input.
- </para>
- </sect2>
- <sect2 id="kgdbocKms">
- <title>kgdboc and kms</title>
- <para>The kgdboc driver contains logic to request the graphics
- display to switch to a text context when you are using
- "kgdboc=kms,kbd", provided that you have a video driver which has a
- frame buffer console and atomic kernel mode setting support.</para>
- <para>
- Every time the kernel
- debugger is entered it calls kgdboc_pre_exp_handler() which in turn
- calls con_debug_enter() in the virtual console layer. On resuming kernel
- execution, the kernel debugger calls kgdboc_post_exp_handler() which
- in turn calls con_debug_leave().</para>
- <para>Any video driver that wants to be compatible with the kernel
- debugger and the atomic kms callbacks must implement the
- mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations.
- For the fb_debug_enter and fb_debug_leave the option exists to use
- the generic drm fb helper functions or implement something custom for
- the hardware. The following example shows the initialization of the
- .mode_set_base_atomic operation in
- drivers/gpu/drm/i915/intel_display.c:
- <informalexample>
- <programlisting>
-static const struct drm_crtc_helper_funcs intel_helper_funcs = {
-[...]
- .mode_set_base_atomic = intel_pipe_set_base_atomic,
-[...]
-};
- </programlisting>
- </informalexample>
- </para>
- <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in
- drivers/gpu/drm/i915/intel_fb.c:
- <informalexample>
- <programlisting>
-static struct fb_ops intelfb_ops = {
-[...]
- .fb_debug_enter = drm_fb_helper_debug_enter,
- .fb_debug_leave = drm_fb_helper_debug_leave,
-[...]
-};
- </programlisting>
- </informalexample>
- </para>
- </sect2>
- </sect1>
- </chapter>
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The following people have contributed to this document:
- <orderedlist>
- <listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>
- <listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>
- </orderedlist>
- In March 2008 this document was completely rewritten by:
- <itemizedlist>
- <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
- </itemizedlist>
- In Jan 2010 this document was updated to include kdb.
- <itemizedlist>
- <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
- </itemizedlist>
- </para>
- </chapter>
-</book>
-
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl
deleted file mode 100644
index d7fcdc5a4379..000000000000
--- a/Documentation/DocBook/libata.tmpl
+++ /dev/null
@@ -1,1625 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="libataDevGuide">
- <bookinfo>
- <title>libATA Developer's Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Jeff</firstname>
- <surname>Garzik</surname>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2003-2006</year>
- <holder>Jeff Garzik</holder>
- </copyright>
-
- <legalnotice>
- <para>
- The contents of this file are subject to the Open
- Software License version 1.1 that can be found at
- <ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink>
- and is included herein by reference.
- </para>
-
- <para>
- Alternatively, the contents of this file may be used under the terms
- of the GNU General Public License version 2 (the "GPL") as distributed
- in the kernel source COPYING file, in which case the provisions of
- the GPL are applicable instead of the above. If you wish to allow
- the use of your version of this file only under the terms of the
- GPL and not to allow others to use your version of this file under
- the OSL, indicate your decision by deleting the provisions above and
- replace them with the notice and other provisions required by the GPL.
- If you do not delete the provisions above, a recipient may use your
- version of this file under either the OSL or the GPL.
- </para>
-
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="libataIntroduction">
- <title>Introduction</title>
- <para>
- libATA is a library used inside the Linux kernel to support ATA host
- controllers and devices. libATA provides an ATA driver API, class
- transports for ATA and ATAPI devices, and SCSI&lt;-&gt;ATA translation
- for ATA devices according to the T10 SAT specification.
- </para>
- <para>
- This Guide documents the libATA driver API, library functions, library
- internals, and a couple sample ATA low-level drivers.
- </para>
- </chapter>
-
- <chapter id="libataDriverApi">
- <title>libata Driver API</title>
- <para>
- struct ata_port_operations is defined for every low-level libata
- hardware driver, and it controls how the low-level driver
- interfaces with the ATA and SCSI layers.
- </para>
- <para>
- FIS-based drivers will hook into the system with ->qc_prep() and
- ->qc_issue() high-level hooks. Hardware which behaves in a manner
- similar to PCI IDE hardware may utilize several generic helpers,
- defining at a bare minimum the bus I/O addresses of the ATA shadow
- register blocks.
- </para>
- <sect1>
- <title>struct ata_port_operations</title>
-
- <sect2><title>Disable ATA port</title>
- <programlisting>
-void (*port_disable) (struct ata_port *);
- </programlisting>
-
- <para>
- Called from ata_bus_probe() error path, as well as when
- unregistering from the SCSI module (rmmod, hot unplug).
- This function should do whatever needs to be done to take the
- port out of use. In most cases, ata_port_disable() can be used
- as this hook.
- </para>
- <para>
- Called from ata_bus_probe() on a failed probe.
- Called from ata_scsi_release().
- </para>
-
- </sect2>
-
- <sect2><title>Post-IDENTIFY device configuration</title>
- <programlisting>
-void (*dev_config) (struct ata_port *, struct ata_device *);
- </programlisting>
-
- <para>
- Called after IDENTIFY [PACKET] DEVICE is issued to each device
- found. Typically used to apply device-specific fixups prior to
- issue of SET FEATURES - XFER MODE, and prior to operation.
- </para>
- <para>
- This entry may be specified as NULL in ata_port_operations.
- </para>
-
- </sect2>
-
- <sect2><title>Set PIO/DMA mode</title>
- <programlisting>
-void (*set_piomode) (struct ata_port *, struct ata_device *);
-void (*set_dmamode) (struct ata_port *, struct ata_device *);
-void (*post_set_mode) (struct ata_port *);
-unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);
- </programlisting>
-
- <para>
- Hooks called prior to the issue of SET FEATURES - XFER MODE
- command. The optional ->mode_filter() hook is called when libata
- has built a mask of the possible modes. This is passed to the
- ->mode_filter() function which should return a mask of valid modes
- after filtering those unsuitable due to hardware limits. It is not
- valid to use this interface to add modes.
- </para>
- <para>
- dev->pio_mode and dev->dma_mode are guaranteed to be valid when
- ->set_piomode() and when ->set_dmamode() is called. The timings for
- any other drive sharing the cable will also be valid at this point.
- That is the library records the decisions for the modes of each
- drive on a channel before it attempts to set any of them.
- </para>
- <para>
- ->post_set_mode() is
- called unconditionally, after the SET FEATURES - XFER MODE
- command completes successfully.
- </para>
-
- <para>
- ->set_piomode() is always called (if present), but
- ->set_dma_mode() is only called if DMA is possible.
- </para>
-
- </sect2>
-
- <sect2><title>Taskfile read/write</title>
- <programlisting>
-void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf);
-void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
- </programlisting>
-
- <para>
- ->tf_load() is called to load the given taskfile into hardware
- registers / DMA buffers. ->tf_read() is called to read the
- hardware registers / DMA buffers, to obtain the current set of
- taskfile register values.
- Most drivers for taskfile-based hardware (PIO or MMIO) use
- ata_sff_tf_load() and ata_sff_tf_read() for these hooks.
- </para>
-
- </sect2>
-
- <sect2><title>PIO data read/write</title>
- <programlisting>
-void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);
- </programlisting>
-
- <para>
-All bmdma-style drivers must implement this hook. This is the low-level
-operation that actually copies the data bytes during a PIO data
-transfer.
-Typically the driver will choose one of ata_sff_data_xfer_noirq(),
-ata_sff_data_xfer(), or ata_sff_data_xfer32().
- </para>
-
- </sect2>
-
- <sect2><title>ATA command execute</title>
- <programlisting>
-void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
- </programlisting>
-
- <para>
- causes an ATA command, previously loaded with
- ->tf_load(), to be initiated in hardware.
- Most drivers for taskfile-based hardware use ata_sff_exec_command()
- for this hook.
- </para>
-
- </sect2>
-
- <sect2><title>Per-cmd ATAPI DMA capabilities filter</title>
- <programlisting>
-int (*check_atapi_dma) (struct ata_queued_cmd *qc);
- </programlisting>
-
- <para>
-Allow low-level driver to filter ATA PACKET commands, returning a status
-indicating whether or not it is OK to use DMA for the supplied PACKET
-command.
- </para>
- <para>
- This hook may be specified as NULL, in which case libata will
- assume that atapi dma can be supported.
- </para>
-
- </sect2>
-
- <sect2><title>Read specific ATA shadow registers</title>
- <programlisting>
-u8 (*sff_check_status)(struct ata_port *ap);
-u8 (*sff_check_altstatus)(struct ata_port *ap);
- </programlisting>
-
- <para>
- Reads the Status/AltStatus ATA shadow register from
- hardware. On some hardware, reading the Status register has
- the side effect of clearing the interrupt condition.
- Most drivers for taskfile-based hardware use
- ata_sff_check_status() for this hook.
- </para>
-
- </sect2>
-
- <sect2><title>Write specific ATA shadow register</title>
- <programlisting>
-void (*sff_set_devctl)(struct ata_port *ap, u8 ctl);
- </programlisting>
-
- <para>
- Write the device control ATA shadow register to the hardware.
- Most drivers don't need to define this.
- </para>
-
- </sect2>
-
- <sect2><title>Select ATA device on bus</title>
- <programlisting>
-void (*sff_dev_select)(struct ata_port *ap, unsigned int device);
- </programlisting>
-
- <para>
- Issues the low-level hardware command(s) that causes one of N
- hardware devices to be considered 'selected' (active and
- available for use) on the ATA bus. This generally has no
- meaning on FIS-based devices.
- </para>
- <para>
- Most drivers for taskfile-based hardware use
- ata_sff_dev_select() for this hook.
- </para>
-
- </sect2>
-
- <sect2><title>Private tuning method</title>
- <programlisting>
-void (*set_mode) (struct ata_port *ap);
- </programlisting>
-
- <para>
- By default libata performs drive and controller tuning in
- accordance with the ATA timing rules and also applies blacklists
- and cable limits. Some controllers need special handling and have
- custom tuning rules, typically raid controllers that use ATA
- commands but do not actually do drive timing.
- </para>
-
- <warning>
- <para>
- This hook should not be used to replace the standard controller
- tuning logic when a controller has quirks. Replacing the default
- tuning logic in that case would bypass handling for drive and
- bridge quirks that may be important to data reliability. If a
- controller needs to filter the mode selection it should use the
- mode_filter hook instead.
- </para>
- </warning>
-
- </sect2>
-
- <sect2><title>Control PCI IDE BMDMA engine</title>
- <programlisting>
-void (*bmdma_setup) (struct ata_queued_cmd *qc);
-void (*bmdma_start) (struct ata_queued_cmd *qc);
-void (*bmdma_stop) (struct ata_port *ap);
-u8 (*bmdma_status) (struct ata_port *ap);
- </programlisting>
-
- <para>
-When setting up an IDE BMDMA transaction, these hooks arm
-(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
-the hardware's DMA engine. ->bmdma_status is used to read the standard
-PCI IDE DMA Status register.
- </para>
-
- <para>
-These hooks are typically either no-ops, or simply not implemented, in
-FIS-based drivers.
- </para>
- <para>
-Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
-hook. ata_bmdma_setup() will write the pointer to the PRD table to
-the IDE PRD Table Address register, enable DMA in the DMA Command
-register, and call exec_command() to begin the transfer.
- </para>
- <para>
-Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
-hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
-Command register.
- </para>
- <para>
-Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
-hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
-command register.
- </para>
- <para>
-Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.
- </para>
-
- </sect2>
-
- <sect2><title>High-level taskfile hooks</title>
- <programlisting>
-void (*qc_prep) (struct ata_queued_cmd *qc);
-int (*qc_issue) (struct ata_queued_cmd *qc);
- </programlisting>
-
- <para>
- Higher-level hooks, these two hooks can potentially supercede
- several of the above taskfile/DMA engine hooks. ->qc_prep is
- called after the buffers have been DMA-mapped, and is typically
- used to populate the hardware's DMA scatter-gather table.
- Most drivers use the standard ata_qc_prep() helper function, but
- more advanced drivers roll their own.
- </para>
- <para>
- ->qc_issue is used to make a command active, once the hardware
- and S/G tables have been prepared. IDE BMDMA drivers use the
- helper function ata_qc_issue_prot() for taskfile protocol-based
- dispatch. More advanced drivers implement their own ->qc_issue.
- </para>
- <para>
- ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
- ->bmdma_start() as necessary to initiate a transfer.
- </para>
-
- </sect2>
-
- <sect2><title>Exception and probe handling (EH)</title>
- <programlisting>
-void (*eng_timeout) (struct ata_port *ap);
-void (*phy_reset) (struct ata_port *ap);
- </programlisting>
-
- <para>
-Deprecated. Use ->error_handler() instead.
- </para>
-
- <programlisting>
-void (*freeze) (struct ata_port *ap);
-void (*thaw) (struct ata_port *ap);
- </programlisting>
-
- <para>
-ata_port_freeze() is called when HSM violations or some other
-condition disrupts normal operation of the port. A frozen port
-is not allowed to perform any operation until the port is
-thawed, which usually follows a successful reset.
- </para>
-
- <para>
-The optional ->freeze() callback can be used for freezing the port
-hardware-wise (e.g. mask interrupt and stop DMA engine). If a
-port cannot be frozen hardware-wise, the interrupt handler
-must ack and clear interrupts unconditionally while the port
-is frozen.
- </para>
- <para>
-The optional ->thaw() callback is called to perform the opposite of ->freeze():
-prepare the port for normal operation once again. Unmask interrupts,
-start DMA engine, etc.
- </para>
-
- <programlisting>
-void (*error_handler) (struct ata_port *ap);
- </programlisting>
-
- <para>
-->error_handler() is a driver's hook into probe, hotplug, and recovery
-and other exceptional conditions. The primary responsibility of an
-implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set
-of EH hooks as arguments:
- </para>
-
- <para>
-'prereset' hook (may be NULL) is called during an EH reset, before any other actions
-are taken.
- </para>
-
- <para>
-'postreset' hook (may be NULL) is called after the EH reset is performed. Based on
-existing conditions, severity of the problem, and hardware capabilities,
- </para>
-
- <para>
-Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
-called to perform the low-level EH reset.
- </para>
-
- <programlisting>
-void (*post_internal_cmd) (struct ata_queued_cmd *qc);
- </programlisting>
-
- <para>
-Perform any hardware-specific actions necessary to finish processing
-after executing a probe-time or EH-time command via ata_exec_internal().
- </para>
-
- </sect2>
-
- <sect2><title>Hardware interrupt handling</title>
- <programlisting>
-irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);
-void (*irq_clear) (struct ata_port *);
- </programlisting>
-
- <para>
- ->irq_handler is the interrupt handling routine registered with
- the system, by libata. ->irq_clear is called during probe just
- before the interrupt handler is registered, to be sure hardware
- is quiet.
- </para>
- <para>
- The second argument, dev_instance, should be cast to a pointer
- to struct ata_host_set.
- </para>
- <para>
- Most legacy IDE drivers use ata_sff_interrupt() for the
- irq_handler hook, which scans all ports in the host_set,
- determines which queued command was active (if any), and calls
- ata_sff_host_intr(ap,qc).
- </para>
- <para>
- Most legacy IDE drivers use ata_sff_irq_clear() for the
- irq_clear() hook, which simply clears the interrupt and error
- flags in the DMA status register.
- </para>
-
- </sect2>
-
- <sect2><title>SATA phy read/write</title>
- <programlisting>
-int (*scr_read) (struct ata_port *ap, unsigned int sc_reg,
- u32 *val);
-int (*scr_write) (struct ata_port *ap, unsigned int sc_reg,
- u32 val);
- </programlisting>
-
- <para>
- Read and write standard SATA phy registers. Currently only used
- if ->phy_reset hook called the sata_phy_reset() helper function.
- sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
- </para>
-
- </sect2>
-
- <sect2><title>Init and shutdown</title>
- <programlisting>
-int (*port_start) (struct ata_port *ap);
-void (*port_stop) (struct ata_port *ap);
-void (*host_stop) (struct ata_host_set *host_set);
- </programlisting>
-
- <para>
- ->port_start() is called just after the data structures for each
- port are initialized. Typically this is used to alloc per-port
- DMA buffers / tables / rings, enable DMA engines, and similar
- tasks. Some drivers also use this entry point as a chance to
- allocate driver-private memory for ap->private_data.
- </para>
- <para>
- Many drivers use ata_port_start() as this hook or call
- it from their own port_start() hooks. ata_port_start()
- allocates space for a legacy IDE PRD table and returns.
- </para>
- <para>
- ->port_stop() is called after ->host_stop(). Its sole function
- is to release DMA/memory resources, now that they are no longer
- actively being used. Many drivers also free driver-private
- data from port at this time.
- </para>
- <para>
- ->host_stop() is called after all ->port_stop() calls
-have completed. The hook must finalize hardware shutdown, release DMA
-and other resources, etc.
- This hook may be specified as NULL, in which case it is not called.
- </para>
-
- </sect2>
-
- </sect1>
- </chapter>
-
- <chapter id="libataEH">
- <title>Error handling</title>
-
- <para>
- This chapter describes how errors are handled under libata.
- Readers are advised to read SCSI EH
- (Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first.
- </para>
-
- <sect1><title>Origins of commands</title>
- <para>
- In libata, a command is represented with struct ata_queued_cmd
- or qc. qc's are preallocated during port initialization and
- repetitively used for command executions. Currently only one
- qc is allocated per port but yet-to-be-merged NCQ branch
- allocates one for each tag and maps each qc to NCQ tag 1-to-1.
- </para>
- <para>
- libata commands can originate from two sources - libata itself
- and SCSI midlayer. libata internal commands are used for
- initialization and error handling. All normal blk requests
- and commands for SCSI emulation are passed as SCSI commands
- through queuecommand callback of SCSI host template.
- </para>
- </sect1>
-
- <sect1><title>How commands are issued</title>
-
- <variablelist>
-
- <varlistentry><term>Internal commands</term>
- <listitem>
- <para>
- First, qc is allocated and initialized using
- ata_qc_new_init(). Although ata_qc_new_init() doesn't
- implement any wait or retry mechanism when qc is not
- available, internal commands are currently issued only during
- initialization and error recovery, so no other command is
- active and allocation is guaranteed to succeed.
- </para>
- <para>
- Once allocated qc's taskfile is initialized for the command to
- be executed. qc currently has two mechanisms to notify
- completion. One is via qc->complete_fn() callback and the
- other is completion qc->waiting. qc->complete_fn() callback
- is the asynchronous path used by normal SCSI translated
- commands and qc->waiting is the synchronous (issuer sleeps in
- process context) path used by internal commands.
- </para>
- <para>
- Once initialization is complete, host_set lock is acquired
- and the qc is issued.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>SCSI commands</term>
- <listitem>
- <para>
- All libata drivers use ata_scsi_queuecmd() as
- hostt->queuecommand callback. scmds can either be simulated
- or translated. No qc is involved in processing a simulated
- scmd. The result is computed right away and the scmd is
- completed.
- </para>
- <para>
- For a translated scmd, ata_qc_new_init() is invoked to
- allocate a qc and the scmd is translated into the qc. SCSI
- midlayer's completion notification function pointer is stored
- into qc->scsidone.
- </para>
- <para>
- qc->complete_fn() callback is used for completion
- notification. ATA commands use ata_scsi_qc_complete() while
- ATAPI commands use atapi_qc_complete(). Both functions end up
- calling qc->scsidone to notify upper layer when the qc is
- finished. After translation is completed, the qc is issued
- with ata_qc_issue().
- </para>
- <para>
- Note that SCSI midlayer invokes hostt->queuecommand while
- holding host_set lock, so all above occur while holding
- host_set lock.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect1>
-
- <sect1><title>How commands are processed</title>
- <para>
- Depending on which protocol and which controller are used,
- commands are processed differently. For the purpose of
- discussion, a controller which uses taskfile interface and all
- standard callbacks is assumed.
- </para>
- <para>
- Currently 6 ATA command protocols are used. They can be
- sorted into the following four categories according to how
- they are processed.
- </para>
-
- <variablelist>
- <varlistentry><term>ATA NO DATA or DMA</term>
- <listitem>
- <para>
- ATA_PROT_NODATA and ATA_PROT_DMA fall into this category.
- These types of commands don't require any software
- intervention once issued. Device will raise interrupt on
- completion.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>ATA PIO</term>
- <listitem>
- <para>
- ATA_PROT_PIO is in this category. libata currently
- implements PIO with polling. ATA_NIEN bit is set to turn
- off interrupt and pio_task on ata_wq performs polling and
- IO.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>ATAPI NODATA or DMA</term>
- <listitem>
- <para>
- ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this
- category. packet_task is used to poll BSY bit after
- issuing PACKET command. Once BSY is turned off by the
- device, packet_task transfers CDB and hands off processing
- to interrupt handler.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>ATAPI PIO</term>
- <listitem>
- <para>
- ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set
- and, as in ATAPI NODATA or DMA, packet_task submits cdb.
- However, after submitting cdb, further processing (data
- transfer) is handed off to pio_task.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
- <sect1><title>How commands are completed</title>
- <para>
- Once issued, all qc's are either completed with
- ata_qc_complete() or time out. For commands which are handled
- by interrupts, ata_host_intr() invokes ata_qc_complete(), and,
- for PIO tasks, pio_task invokes ata_qc_complete(). In error
- cases, packet_task may also complete commands.
- </para>
- <para>
- ata_qc_complete() does the following.
- </para>
-
- <orderedlist>
-
- <listitem>
- <para>
- DMA memory is unmapped.
- </para>
- </listitem>
-
- <listitem>
- <para>
- ATA_QCFLAG_ACTIVE is cleared from qc->flags.
- </para>
- </listitem>
-
- <listitem>
- <para>
- qc->complete_fn() callback is invoked. If the return value of
- the callback is not zero. Completion is short circuited and
- ata_qc_complete() returns.
- </para>
- </listitem>
-
- <listitem>
- <para>
- __ata_qc_complete() is called, which does
- <orderedlist>
-
- <listitem>
- <para>
- qc->flags is cleared to zero.
- </para>
- </listitem>
-
- <listitem>
- <para>
- ap->active_tag and qc->tag are poisoned.
- </para>
- </listitem>
-
- <listitem>
- <para>
- qc->waiting is cleared &amp; completed (in that order).
- </para>
- </listitem>
-
- <listitem>
- <para>
- qc is deallocated by clearing appropriate bit in ap->qactive.
- </para>
- </listitem>
-
- </orderedlist>
- </para>
- </listitem>
-
- </orderedlist>
-
- <para>
- So, it basically notifies upper layer and deallocates qc. One
- exception is short-circuit path in #3 which is used by
- atapi_qc_complete().
- </para>
- <para>
- For all non-ATAPI commands, whether it fails or not, almost
- the same code path is taken and very little error handling
- takes place. A qc is completed with success status if it
- succeeded, with failed status otherwise.
- </para>
- <para>
- However, failed ATAPI commands require more handling as
- REQUEST SENSE is needed to acquire sense data. If an ATAPI
- command fails, ata_qc_complete() is invoked with error status,
- which in turn invokes atapi_qc_complete() via
- qc->complete_fn() callback.
- </para>
- <para>
- This makes atapi_qc_complete() set scmd->result to
- SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As
- the sense data is empty but scmd->result is CHECK CONDITION,
- SCSI midlayer will invoke EH for the scmd, and returning 1
- makes ata_qc_complete() to return without deallocating the qc.
- This leads us to ata_scsi_error() with partially completed qc.
- </para>
-
- </sect1>
-
- <sect1><title>ata_scsi_error()</title>
- <para>
- ata_scsi_error() is the current transportt->eh_strategy_handler()
- for libata. As discussed above, this will be entered in two
- cases - timeout and ATAPI error completion. This function
- calls low level libata driver's eng_timeout() callback, the
- standard callback for which is ata_eng_timeout(). It checks
- if a qc is active and calls ata_qc_timeout() on the qc if so.
- Actual error handling occurs in ata_qc_timeout().
- </para>
- <para>
- If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and
- completes the qc. Note that as we're currently in EH, we
- cannot call scsi_done. As described in SCSI EH doc, a
- recovered scmd should be either retried with
- scsi_queue_insert() or finished with scsi_finish_command().
- Here, we override qc->scsidone with scsi_finish_command() and
- calls ata_qc_complete().
- </para>
- <para>
- If EH is invoked due to a failed ATAPI qc, the qc here is
- completed but not deallocated. The purpose of this
- half-completion is to use the qc as place holder to make EH
- code reach this place. This is a bit hackish, but it works.
- </para>
- <para>
- Once control reaches here, the qc is deallocated by invoking
- __ata_qc_complete() explicitly. Then, internal qc for REQUEST
- SENSE is issued. Once sense data is acquired, scmd is
- finished by directly invoking scsi_finish_command() on the
- scmd. Note that as we already have completed and deallocated
- the qc which was associated with the scmd, we don't need
- to/cannot call ata_qc_complete() again.
- </para>
-
- </sect1>
-
- <sect1><title>Problems with the current EH</title>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Error representation is too crude. Currently any and all
- error conditions are represented with ATA STATUS and ERROR
- registers. Errors which aren't ATA device errors are treated
- as ATA device errors by setting ATA_ERR bit. Better error
- descriptor which can properly represent ATA and other
- errors/exceptions is needed.
- </para>
- </listitem>
-
- <listitem>
- <para>
- When handling timeouts, no action is taken to make device
- forget about the timed out command and ready for new commands.
- </para>
- </listitem>
-
- <listitem>
- <para>
- EH handling via ata_scsi_error() is not properly protected
- from usual command processing. On EH entrance, the device is
- not in quiescent state. Timed out commands may succeed or
- fail any time. pio_task and atapi_task may still be running.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Too weak error recovery. Devices / controllers causing HSM
- mismatch errors and other errors quite often require reset to
- return to known state. Also, advanced error handling is
- necessary to support features like NCQ and hotplug.
- </para>
- </listitem>
-
- <listitem>
- <para>
- ATA errors are directly handled in the interrupt handler and
- PIO errors in pio_task. This is problematic for advanced
- error handling for the following reasons.
- </para>
- <para>
- First, advanced error handling often requires context and
- internal qc execution.
- </para>
- <para>
- Second, even a simple failure (say, CRC error) needs
- information gathering and could trigger complex error handling
- (say, resetting &amp; reconfiguring). Having multiple code
- paths to gather information, enter EH and trigger actions
- makes life painful.
- </para>
- <para>
- Third, scattered EH code makes implementing low level drivers
- difficult. Low level drivers override libata callbacks. If
- EH is scattered over several places, each affected callbacks
- should perform its part of error handling. This can be error
- prone and painful.
- </para>
- </listitem>
-
- </itemizedlist>
- </sect1>
- </chapter>
-
- <chapter id="libataExt">
- <title>libata Library</title>
-!Edrivers/ata/libata-core.c
- </chapter>
-
- <chapter id="libataInt">
- <title>libata Core Internals</title>
-!Idrivers/ata/libata-core.c
- </chapter>
-
- <chapter id="libataScsiInt">
- <title>libata SCSI translation/emulation</title>
-!Edrivers/ata/libata-scsi.c
-!Idrivers/ata/libata-scsi.c
- </chapter>
-
- <chapter id="ataExceptions">
- <title>ATA errors and exceptions</title>
-
- <para>
- This chapter tries to identify what error/exception conditions exist
- for ATA/ATAPI devices and describe how they should be handled in
- implementation-neutral way.
- </para>
-
- <para>
- The term 'error' is used to describe conditions where either an
- explicit error condition is reported from device or a command has
- timed out.
- </para>
-
- <para>
- The term 'exception' is either used to describe exceptional
- conditions which are not errors (say, power or hotplug events), or
- to describe both errors and non-error exceptional conditions. Where
- explicit distinction between error and exception is necessary, the
- term 'non-error exception' is used.
- </para>
-
- <sect1 id="excat">
- <title>Exception categories</title>
- <para>
- Exceptions are described primarily with respect to legacy
- taskfile + bus master IDE interface. If a controller provides
- other better mechanism for error reporting, mapping those into
- categories described below shouldn't be difficult.
- </para>
-
- <para>
- In the following sections, two recovery actions - reset and
- reconfiguring transport - are mentioned. These are described
- further in <xref linkend="exrec"/>.
- </para>
-
- <sect2 id="excatHSMviolation">
- <title>HSM violation</title>
- <para>
- This error is indicated when STATUS value doesn't match HSM
- requirement during issuing or execution any ATA/ATAPI command.
- </para>
-
- <itemizedlist>
- <title>Examples</title>
-
- <listitem>
- <para>
- ATA_STATUS doesn't contain !BSY &amp;&amp; DRDY &amp;&amp; !DRQ while trying
- to issue a command.
- </para>
- </listitem>
-
- <listitem>
- <para>
- !BSY &amp;&amp; !DRQ during PIO data transfer.
- </para>
- </listitem>
-
- <listitem>
- <para>
- DRQ on command completion.
- </para>
- </listitem>
-
- <listitem>
- <para>
- !BSY &amp;&amp; ERR after CDB transfer starts but before the
- last byte of CDB is transferred. ATA/ATAPI standard states
- that &quot;The device shall not terminate the PACKET command
- with an error before the last byte of the command packet has
- been written&quot; in the error outputs description of PACKET
- command and the state diagram doesn't include such
- transitions.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- In these cases, HSM is violated and not much information
- regarding the error can be acquired from STATUS or ERROR
- register. IOW, this error can be anything - driver bug,
- faulty device, controller and/or cable.
- </para>
-
- <para>
- As HSM is violated, reset is necessary to restore known state.
- Reconfiguring transport for lower speed might be helpful too
- as transmission errors sometimes cause this kind of errors.
- </para>
- </sect2>
-
- <sect2 id="excatDevErr">
- <title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title>
-
- <para>
- These are errors detected and reported by ATA/ATAPI devices
- indicating device problems. For this type of errors, STATUS
- and ERROR register values are valid and describe error
- condition. Note that some of ATA bus errors are detected by
- ATA/ATAPI devices and reported using the same mechanism as
- device errors. Those cases are described later in this
- section.
- </para>
-
- <para>
- For ATA commands, this type of errors are indicated by !BSY
- &amp;&amp; ERR during command execution and on completion.
- </para>
-
- <para>For ATAPI commands,</para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- !BSY &amp;&amp; ERR &amp;&amp; ABRT right after issuing PACKET
- indicates that PACKET command is not supported and falls in
- this category.
- </para>
- </listitem>
-
- <listitem>
- <para>
- !BSY &amp;&amp; ERR(==CHK) &amp;&amp; !ABRT after the last
- byte of CDB is transferred indicates CHECK CONDITION and
- doesn't fall in this category.
- </para>
- </listitem>
-
- <listitem>
- <para>
- !BSY &amp;&amp; ERR(==CHK) &amp;&amp; ABRT after the last byte
- of CDB is transferred *probably* indicates CHECK CONDITION and
- doesn't fall in this category.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Of errors detected as above, the followings are not ATA/ATAPI
- device errors but ATA bus errors and should be handled
- according to <xref linkend="excatATAbusErr"/>.
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term>CRC error during data transfer</term>
- <listitem>
- <para>
- This is indicated by ICRC bit in the ERROR register and
- means that corruption occurred during data transfer. Up to
- ATA/ATAPI-7, the standard specifies that this bit is only
- applicable to UDMA transfers but ATA/ATAPI-8 draft revision
- 1f says that the bit may be applicable to multiword DMA and
- PIO.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ABRT error during data transfer or on completion</term>
- <listitem>
- <para>
- Up to ATA/ATAPI-7, the standard specifies that ABRT could be
- set on ICRC errors and on cases where a device is not able
- to complete a command. Combined with the fact that MWDMA
- and PIO transfer errors aren't allowed to use ICRC bit up to
- ATA/ATAPI-7, it seems to imply that ABRT bit alone could
- indicate transfer errors.
- </para>
- <para>
- However, ATA/ATAPI-8 draft revision 1f removes the part
- that ICRC errors can turn on ABRT. So, this is kind of
- gray area. Some heuristics are needed here.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- ATA/ATAPI device errors can be further categorized as follows.
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term>Media errors</term>
- <listitem>
- <para>
- This is indicated by UNC bit in the ERROR register. ATA
- devices reports UNC error only after certain number of
- retries cannot recover the data, so there's nothing much
- else to do other than notifying upper layer.
- </para>
- <para>
- READ and WRITE commands report CHS or LBA of the first
- failed sector but ATA/ATAPI standard specifies that the
- amount of transferred data on error completion is
- indeterminate, so we cannot assume that sectors preceding
- the failed sector have been transferred and thus cannot
- complete those sectors successfully as SCSI does.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Media changed / media change requested error</term>
- <listitem>
- <para>
- &lt;&lt;TODO: fill here&gt;&gt;
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>Address error</term>
- <listitem>
- <para>
- This is indicated by IDNF bit in the ERROR register.
- Report to upper layer.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>Other errors</term>
- <listitem>
- <para>
- This can be invalid command or parameter indicated by ABRT
- ERROR bit or some other error condition. Note that ABRT
- bit can indicate a lot of things including ICRC and Address
- errors. Heuristics needed.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- Depending on commands, not all STATUS/ERROR bits are
- applicable. These non-applicable bits are marked with
- &quot;na&quot; in the output descriptions but up to ATA/ATAPI-7
- no definition of &quot;na&quot; can be found. However,
- ATA/ATAPI-8 draft revision 1f describes &quot;N/A&quot; as
- follows.
- </para>
-
- <blockquote>
- <variablelist>
- <varlistentry><term>3.2.3.3a N/A</term>
- <listitem>
- <para>
- A keyword the indicates a field has no defined value in
- this standard and should not be checked by the host or
- device. N/A fields should be cleared to zero.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </blockquote>
-
- <para>
- So, it seems reasonable to assume that &quot;na&quot; bits are
- cleared to zero by devices and thus need no explicit masking.
- </para>
-
- </sect2>
-
- <sect2 id="excatATAPIcc">
- <title>ATAPI device CHECK CONDITION</title>
-
- <para>
- ATAPI device CHECK CONDITION error is indicated by set CHK bit
- (ERR bit) in the STATUS register after the last byte of CDB is
- transferred for a PACKET command. For this kind of errors,
- sense data should be acquired to gather information regarding
- the errors. REQUEST SENSE packet command should be used to
- acquire sense data.
- </para>
-
- <para>
- Once sense data is acquired, this type of errors can be
- handled similarly to other SCSI errors. Note that sense data
- may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR
- &amp;&amp; ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such
- cases, the error should be considered as an ATA bus error and
- handled according to <xref linkend="excatATAbusErr"/>.
- </para>
-
- </sect2>
-
- <sect2 id="excatNCQerr">
- <title>ATA device error (NCQ)</title>
-
- <para>
- NCQ command error is indicated by cleared BSY and set ERR bit
- during NCQ command phase (one or more NCQ commands
- outstanding). Although STATUS and ERROR registers will
- contain valid values describing the error, READ LOG EXT is
- required to clear the error condition, determine which command
- has failed and acquire more information.
- </para>
-
- <para>
- READ LOG EXT Log Page 10h reports which tag has failed and
- taskfile register values describing the error. With this
- information the failed command can be handled as a normal ATA
- command error as in <xref linkend="excatDevErr"/> and all
- other in-flight commands must be retried. Note that this
- retry should not be counted - it's likely that commands
- retried this way would have completed normally if it were not
- for the failed command.
- </para>
-
- <para>
- Note that ATA bus errors can be reported as ATA device NCQ
- errors. This should be handled as described in <xref
- linkend="excatATAbusErr"/>.
- </para>
-
- <para>
- If READ LOG EXT Log Page 10h fails or reports NQ, we're
- thoroughly screwed. This condition should be treated
- according to <xref linkend="excatHSMviolation"/>.
- </para>
-
- </sect2>
-
- <sect2 id="excatATAbusErr">
- <title>ATA bus error</title>
-
- <para>
- ATA bus error means that data corruption occurred during
- transmission over ATA bus (SATA or PATA). This type of errors
- can be indicated by
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- ICRC or ABRT error as described in <xref linkend="excatDevErr"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Controller-specific error completion with error information
- indicating transmission error.
- </para>
- </listitem>
-
- <listitem>
- <para>
- On some controllers, command timeout. In this case, there may
- be a mechanism to determine that the timeout is due to
- transmission error.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Unknown/random errors, timeouts and all sorts of weirdities.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- As described above, transmission errors can cause wide variety
- of symptoms ranging from device ICRC error to random device
- lockup, and, for many cases, there is no way to tell if an
- error condition is due to transmission error or not;
- therefore, it's necessary to employ some kind of heuristic
- when dealing with errors and timeouts. For example,
- encountering repetitive ABRT errors for known supported
- command is likely to indicate ATA bus error.
- </para>
-
- <para>
- Once it's determined that ATA bus errors have possibly
- occurred, lowering ATA bus transmission speed is one of
- actions which may alleviate the problem. See <xref
- linkend="exrecReconf"/> for more information.
- </para>
-
- </sect2>
-
- <sect2 id="excatPCIbusErr">
- <title>PCI bus error</title>
-
- <para>
- Data corruption or other failures during transmission over PCI
- (or other system bus). For standard BMDMA, this is indicated
- by Error bit in the BMDMA Status register. This type of
- errors must be logged as it indicates something is very wrong
- with the system. Resetting host controller is recommended.
- </para>
-
- </sect2>
-
- <sect2 id="excatLateCompletion">
- <title>Late completion</title>
-
- <para>
- This occurs when timeout occurs and the timeout handler finds
- out that the timed out command has completed successfully or
- with error. This is usually caused by lost interrupts. This
- type of errors must be logged. Resetting host controller is
- recommended.
- </para>
-
- </sect2>
-
- <sect2 id="excatUnknown">
- <title>Unknown error (timeout)</title>
-
- <para>
- This is when timeout occurs and the command is still
- processing or the host and device are in unknown state. When
- this occurs, HSM could be in any valid or invalid state. To
- bring the device to known state and make it forget about the
- timed out command, resetting is necessary. The timed out
- command may be retried.
- </para>
-
- <para>
- Timeouts can also be caused by transmission errors. Refer to
- <xref linkend="excatATAbusErr"/> for more details.
- </para>
-
- </sect2>
-
- <sect2 id="excatHoplugPM">
- <title>Hotplug and power management exceptions</title>
-
- <para>
- &lt;&lt;TODO: fill here&gt;&gt;
- </para>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="exrec">
- <title>EH recovery actions</title>
-
- <para>
- This section discusses several important recovery actions.
- </para>
-
- <sect2 id="exrecClr">
- <title>Clearing error condition</title>
-
- <para>
- Many controllers require its error registers to be cleared by
- error handler. Different controllers may have different
- requirements.
- </para>
-
- <para>
- For SATA, it's strongly recommended to clear at least SError
- register during error handling.
- </para>
- </sect2>
-
- <sect2 id="exrecRst">
- <title>Reset</title>
-
- <para>
- During EH, resetting is necessary in the following cases.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- HSM is in unknown or invalid state
- </para>
- </listitem>
-
- <listitem>
- <para>
- HBA is in unknown or invalid state
- </para>
- </listitem>
-
- <listitem>
- <para>
- EH needs to make HBA/device forget about in-flight commands
- </para>
- </listitem>
-
- <listitem>
- <para>
- HBA/device behaves weirdly
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Resetting during EH might be a good idea regardless of error
- condition to improve EH robustness. Whether to reset both or
- either one of HBA and device depends on situation but the
- following scheme is recommended.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- When it's known that HBA is in ready state but ATA/ATAPI
- device is in unknown state, reset only device.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If HBA is in unknown state, reset both HBA and device.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- HBA resetting is implementation specific. For a controller
- complying to taskfile/BMDMA PCI IDE, stopping active DMA
- transaction may be sufficient iff BMDMA state is the only HBA
- context. But even mostly taskfile/BMDMA PCI IDE complying
- controllers may have implementation specific requirements and
- mechanism to reset themselves. This must be addressed by
- specific drivers.
- </para>
-
- <para>
- OTOH, ATA/ATAPI standard describes in detail ways to reset
- ATA/ATAPI devices.
- </para>
-
- <variablelist>
-
- <varlistentry><term>PATA hardware reset</term>
- <listitem>
- <para>
- This is hardware initiated device reset signalled with
- asserted PATA RESET- signal. There is no standard way to
- initiate hardware reset from software although some
- hardware provides registers that allow driver to directly
- tweak the RESET- signal.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>Software reset</term>
- <listitem>
- <para>
- This is achieved by turning CONTROL SRST bit on for at
- least 5us. Both PATA and SATA support it but, in case of
- SATA, this may require controller-specific support as the
- second Register FIS to clear SRST should be transmitted
- while BSY bit is still set. Note that on PATA, this resets
- both master and slave devices on a channel.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term>
- <listitem>
- <para>
- Although ATA/ATAPI standard doesn't describe exactly, EDD
- implies some level of resetting, possibly similar level
- with software reset. Host-side EDD protocol can be handled
- with normal command processing and most SATA controllers
- should be able to handle EDD's just like other commands.
- As in software reset, EDD affects both devices on a PATA
- bus.
- </para>
- <para>
- Although EDD does reset devices, this doesn't suit error
- handling as EDD cannot be issued while BSY is set and it's
- unclear how it will act when device is in unknown/weird
- state.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>ATAPI DEVICE RESET command</term>
- <listitem>
- <para>
- This is very similar to software reset except that reset
- can be restricted to the selected device without affecting
- the other device sharing the cable.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>SATA phy reset</term>
- <listitem>
- <para>
- This is the preferred way of resetting a SATA device. In
- effect, it's identical to PATA hardware reset. Note that
- this can be done with the standard SCR Control register.
- As such, it's usually easier to implement than software
- reset.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- One more thing to consider when resetting devices is that
- resetting clears certain configuration parameters and they
- need to be set to their previous or newly adjusted values
- after reset.
- </para>
-
- <para>
- Parameters affected are.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
- </para>
- </listitem>
-
- <listitem>
- <para>
- Parameters set with SET FEATURES including transfer mode setting
- </para>
- </listitem>
-
- <listitem>
- <para>
- Block count set with SET MULTIPLE MODE
- </para>
- </listitem>
-
- <listitem>
- <para>
- Other parameters (SET MAX, MEDIA LOCK...)
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- ATA/ATAPI standard specifies that some parameters must be
- maintained across hardware or software reset, but doesn't
- strictly specify all of them. Always reconfiguring needed
- parameters after reset is required for robustness. Note that
- this also applies when resuming from deep sleep (power-off).
- </para>
-
- <para>
- Also, ATA/ATAPI standard requires that IDENTIFY DEVICE /
- IDENTIFY PACKET DEVICE is issued after any configuration
- parameter is updated or a hardware reset and the result used
- for further operation. OS driver is required to implement
- revalidation mechanism to support this.
- </para>
-
- </sect2>
-
- <sect2 id="exrecReconf">
- <title>Reconfigure transport</title>
-
- <para>
- For both PATA and SATA, a lot of corners are cut for cheap
- connectors, cables or controllers and it's quite common to see
- high transmission error rate. This can be mitigated by
- lowering transmission speed.
- </para>
-
- <para>
- The following is a possible scheme Jeff Garzik suggested.
- </para>
-
- <blockquote>
- <para>
- If more than $N (3?) transmission errors happen in 15 minutes,
- </para>
- <itemizedlist>
- <listitem>
- <para>
- if SATA, decrease SATA PHY speed. if speed cannot be decreased,
- </para>
- </listitem>
- <listitem>
- <para>
- decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
- </para>
- </listitem>
- <listitem>
- <para>
- decrease PIO xfer speed. if at PIO3, complain, but continue
- </para>
- </listitem>
- </itemizedlist>
- </blockquote>
-
- </sect2>
-
- </sect1>
-
- </chapter>
-
- <chapter id="PiixInt">
- <title>ata_piix Internals</title>
-!Idrivers/ata/ata_piix.c
- </chapter>
-
- <chapter id="SILInt">
- <title>sata_sil Internals</title>
-!Idrivers/ata/sata_sil.c
- </chapter>
-
- <chapter id="libataThanks">
- <title>Thanks</title>
- <para>
- The bulk of the ATA knowledge comes thanks to long conversations with
- Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
- and SCSI specifications.
- </para>
- <para>
- Thanks to Alan Cox for pointing out similarities
- between SATA and SCSI, and in general for motivation to hack on
- libata.
- </para>
- <para>
- libata's device detection
- method, ata_pio_devchk, and in general all the early probing was
- based on extensive study of Hale Landis's probe/reset code in his
- ATADRVR driver (www.ata-atapi.com).
- </para>
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl
deleted file mode 100644
index 94f21361e0ed..000000000000
--- a/Documentation/DocBook/librs.tmpl
+++ /dev/null
@@ -1,289 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Reed-Solomon-Library-Guide">
- <bookinfo>
- <title>Reed-Solomon Library Programming Interface</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2004</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The generic Reed-Solomon Library provides encoding, decoding
- and error correction functions.
- </para>
- <para>
- Reed-Solomon codes are used in communication and storage
- applications to ensure data integrity.
- </para>
- <para>
- This documentation is provided for developers who want to utilize
- the functions provided by the library.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None.
- </para>
- </chapter>
-
- <chapter id="usage">
- <title>Usage</title>
- <para>
- This chapter provides examples of how to use the library.
- </para>
- <sect1>
- <title>Initializing</title>
- <para>
- The init function init_rs returns a pointer to an
- rs decoder structure, which holds the necessary
- information for encoding, decoding and error correction
- with the given polynomial. It either uses an existing
- matching decoder or creates a new one. On creation all
- the lookup tables for fast en/decoding are created.
- The function may take a while, so make sure not to
- call it in critical code paths.
- </para>
- <programlisting>
-/* the Reed Solomon control structure */
-static struct rs_control *rs_decoder;
-
-/* Symbolsize is 10 (bits)
- * Primitive polynomial is x^10+x^3+1
- * first consecutive root is 0
- * primitive element to generate roots = 1
- * generator polynomial degree (number of roots) = 6
- */
-rs_decoder = init_rs (10, 0x409, 0, 1, 6);
- </programlisting>
- </sect1>
- <sect1>
- <title>Encoding</title>
- <para>
- The encoder calculates the Reed-Solomon code over
- the given data length and stores the result in
- the parity buffer. Note that the parity buffer must
- be initialized before calling the encoder.
- </para>
- <para>
- The expanded data can be inverted on the fly by
- providing a non-zero inversion mask. The expanded data is
- XOR'ed with the mask. This is used e.g. for FLASH
- ECC, where the all 0xFF is inverted to an all 0x00.
- The Reed-Solomon code for all 0x00 is all 0x00. The
- code is inverted before storing to FLASH so it is 0xFF
- too. This prevents that reading from an erased FLASH
- results in ECC errors.
- </para>
- <para>
- The databytes are expanded to the given symbol size
- on the fly. There is no support for encoding continuous
- bitstreams with a symbol size != 8 at the moment. If
- it is necessary it should be not a big deal to implement
- such functionality.
- </para>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6];
-/* Initialize the parity buffer */
-memset(par, 0, sizeof(par));
-/* Encode 512 byte in data8. Store parity in buffer par */
-encode_rs8 (rs_decoder, data8, 512, par, 0);
- </programlisting>
- </sect1>
- <sect1>
- <title>Decoding</title>
- <para>
- The decoder calculates the syndrome over
- the given data length and the received parity symbols
- and corrects errors in the data.
- </para>
- <para>
- If a syndrome is available from a hardware decoder
- then the syndrome calculation is skipped.
- </para>
- <para>
- The correction of the data buffer can be suppressed
- by providing a correction pattern buffer and an error
- location buffer to the decoder. The decoder stores the
- calculated error location and the correction bitmask
- in the given buffers. This is useful for hardware
- decoders which use a weird bit ordering scheme.
- </para>
- <para>
- The databytes are expanded to the given symbol size
- on the fly. There is no support for decoding continuous
- bitstreams with a symbolsize != 8 at the moment. If
- it is necessary it should be not a big deal to implement
- such functionality.
- </para>
-
- <sect2>
- <title>
- Decoding with syndrome calculation, direct data correction
- </title>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6];
-uint8_t data[512];
-int numerr;
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
- </programlisting>
- </sect2>
-
- <sect2>
- <title>
- Decoding with syndrome given by hardware decoder, direct data correction
- </title>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6], syn[6];
-uint8_t data[512];
-int numerr;
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Get syndrome from hardware decoder */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
- </programlisting>
- </sect2>
-
- <sect2>
- <title>
- Decoding with syndrome given by hardware decoder, no direct data correction.
- </title>
- <para>
- Note: It's not necessary to give data and received parity to the decoder.
- </para>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6], syn[6], corr[8];
-uint8_t data[512];
-int numerr, errpos[8];
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Get syndrome from hardware decoder */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
-for (i = 0; i &lt; numerr; i++) {
- do_error_correction_in_your_buffer(errpos[i], corr[i]);
-}
- </programlisting>
- </sect2>
- </sect1>
- <sect1>
- <title>Cleanup</title>
- <para>
- The function free_rs frees the allocated resources,
- if the caller is the last user of the decoder.
- </para>
- <programlisting>
-/* Release resources */
-free_rs(rs_decoder);
- </programlisting>
- </sect1>
-
- </chapter>
-
- <chapter id="structs">
- <title>Structures</title>
- <para>
- This chapter contains the autogenerated documentation of the structures which are
- used in the Reed-Solomon Library and are relevant for a developer.
- </para>
-!Iinclude/linux/rslib.h
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the Reed-Solomon functions
- which are exported.
- </para>
-!Elib/reed_solomon/reed_solomon.c
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The library code for encoding and decoding was written by Phil Karn.
- </para>
- <programlisting>
- Copyright 2002, Phil Karn, KA9Q
- May be used under the terms of the GNU General Public License (GPL)
- </programlisting>
- <para>
- The wrapper functions and interfaces are written by Thomas Gleixner.
- </para>
- <para>
- Many users have provided bugfixes, improvements and helping hands for testing.
- Thanks a lot.
- </para>
- <para>
- The following people have contributed to this document:
- </para>
- <para>
- Thomas Gleixner<email>tglx@linutronix.de</email>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/lsm.tmpl b/Documentation/DocBook/lsm.tmpl
deleted file mode 100644
index fe7664ce9667..000000000000
--- a/Documentation/DocBook/lsm.tmpl
+++ /dev/null
@@ -1,265 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<article class="whitepaper" id="LinuxSecurityModule" lang="en">
- <articleinfo>
- <title>Linux Security Modules: General Security Hooks for Linux</title>
- <authorgroup>
- <author>
- <firstname>Stephen</firstname>
- <surname>Smalley</surname>
- <affiliation>
- <orgname>NAI Labs</orgname>
- <address><email>ssmalley@nai.com</email></address>
- </affiliation>
- </author>
- <author>
- <firstname>Timothy</firstname>
- <surname>Fraser</surname>
- <affiliation>
- <orgname>NAI Labs</orgname>
- <address><email>tfraser@nai.com</email></address>
- </affiliation>
- </author>
- <author>
- <firstname>Chris</firstname>
- <surname>Vance</surname>
- <affiliation>
- <orgname>NAI Labs</orgname>
- <address><email>cvance@nai.com</email></address>
- </affiliation>
- </author>
- </authorgroup>
- </articleinfo>
-
-<sect1 id="Introduction"><title>Introduction</title>
-
-<para>
-In March 2001, the National Security Agency (NSA) gave a presentation
-about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel
-Summit. SELinux is an implementation of flexible and fine-grained
-nondiscretionary access controls in the Linux kernel, originally
-implemented as its own particular kernel patch. Several other
-security projects (e.g. RSBAC, Medusa) have also developed flexible
-access control architectures for the Linux kernel, and various
-projects have developed particular access control models for Linux
-(e.g. LIDS, DTE, SubDomain). Each project has developed and
-maintained its own kernel patch to support its security needs.
-</para>
-
-<para>
-In response to the NSA presentation, Linus Torvalds made a set of
-remarks that described a security framework he would be willing to
-consider for inclusion in the mainstream Linux kernel. He described a
-general framework that would provide a set of security hooks to
-control operations on kernel objects and a set of opaque security
-fields in kernel data structures for maintaining security attributes.
-This framework could then be used by loadable kernel modules to
-implement any desired model of security. Linus also suggested the
-possibility of migrating the Linux capabilities code into such a
-module.
-</para>
-
-<para>
-The Linux Security Modules (LSM) project was started by WireX to
-develop such a framework. LSM is a joint development effort by
-several security projects, including Immunix, SELinux, SGI and Janus,
-and several individuals, including Greg Kroah-Hartman and James
-Morris, to develop a Linux kernel patch that implements this
-framework. The patch is currently tracking the 2.4 series and is
-targeted for integration into the 2.5 development series. This
-technical report provides an overview of the framework and the example
-capabilities security module provided by the LSM kernel patch.
-</para>
-
-</sect1>
-
-<sect1 id="framework"><title>LSM Framework</title>
-
-<para>
-The LSM kernel patch provides a general kernel framework to support
-security modules. In particular, the LSM framework is primarily
-focused on supporting access control modules, although future
-development is likely to address other security needs such as
-auditing. By itself, the framework does not provide any additional
-security; it merely provides the infrastructure to support security
-modules. The LSM kernel patch also moves most of the capabilities
-logic into an optional security module, with the system defaulting
-to the traditional superuser logic. This capabilities module
-is discussed further in <xref linkend="cap"/>.
-</para>
-
-<para>
-The LSM kernel patch adds security fields to kernel data structures
-and inserts calls to hook functions at critical points in the kernel
-code to manage the security fields and to perform access control. It
-also adds functions for registering and unregistering security
-modules, and adds a general <function>security</function> system call
-to support new system calls for security-aware applications.
-</para>
-
-<para>
-The LSM security fields are simply <type>void*</type> pointers. For
-process and program execution security information, security fields
-were added to <structname>struct task_struct</structname> and
-<structname>struct linux_binprm</structname>. For filesystem security
-information, a security field was added to
-<structname>struct super_block</structname>. For pipe, file, and socket
-security information, security fields were added to
-<structname>struct inode</structname> and
-<structname>struct file</structname>. For packet and network device security
-information, security fields were added to
-<structname>struct sk_buff</structname> and
-<structname>struct net_device</structname>. For System V IPC security
-information, security fields were added to
-<structname>struct kern_ipc_perm</structname> and
-<structname>struct msg_msg</structname>; additionally, the definitions
-for <structname>struct msg_msg</structname>, <structname>struct
-msg_queue</structname>, and <structname>struct
-shmid_kernel</structname> were moved to header files
-(<filename>include/linux/msg.h</filename> and
-<filename>include/linux/shm.h</filename> as appropriate) to allow
-the security modules to use these definitions.
-</para>
-
-<para>
-Each LSM hook is a function pointer in a global table,
-security_ops. This table is a
-<structname>security_operations</structname> structure as defined by
-<filename>include/linux/security.h</filename>. Detailed documentation
-for each hook is included in this header file. At present, this
-structure consists of a collection of substructures that group related
-hooks based on the kernel object (e.g. task, inode, file, sk_buff,
-etc) as well as some top-level hook function pointers for system
-operations. This structure is likely to be flattened in the future
-for performance. The placement of the hook calls in the kernel code
-is described by the "called:" lines in the per-hook documentation in
-the header file. The hook calls can also be easily found in the
-kernel code by looking for the string "security_ops->".
-
-</para>
-
-<para>
-Linus mentioned per-process security hooks in his original remarks as a
-possible alternative to global security hooks. However, if LSM were
-to start from the perspective of per-process hooks, then the base
-framework would have to deal with how to handle operations that
-involve multiple processes (e.g. kill), since each process might have
-its own hook for controlling the operation. This would require a
-general mechanism for composing hooks in the base framework.
-Additionally, LSM would still need global hooks for operations that
-have no process context (e.g. network input operations).
-Consequently, LSM provides global security hooks, but a security
-module is free to implement per-process hooks (where that makes sense)
-by storing a security_ops table in each process' security field and
-then invoking these per-process hooks from the global hooks.
-The problem of composition is thus deferred to the module.
-</para>
-
-<para>
-The global security_ops table is initialized to a set of hook
-functions provided by a dummy security module that provides
-traditional superuser logic. A <function>register_security</function>
-function (in <filename>security/security.c</filename>) is provided to
-allow a security module to set security_ops to refer to its own hook
-functions, and an <function>unregister_security</function> function is
-provided to revert security_ops to the dummy module hooks. This
-mechanism is used to set the primary security module, which is
-responsible for making the final decision for each hook.
-</para>
-
-<para>
-LSM also provides a simple mechanism for stacking additional security
-modules with the primary security module. It defines
-<function>register_security</function> and
-<function>unregister_security</function> hooks in the
-<structname>security_operations</structname> structure and provides
-<function>mod_reg_security</function> and
-<function>mod_unreg_security</function> functions that invoke these
-hooks after performing some sanity checking. A security module can
-call these functions in order to stack with other modules. However,
-the actual details of how this stacking is handled are deferred to the
-module, which can implement these hooks in any way it wishes
-(including always returning an error if it does not wish to support
-stacking). In this manner, LSM again defers the problem of
-composition to the module.
-</para>
-
-<para>
-Although the LSM hooks are organized into substructures based on
-kernel object, all of the hooks can be viewed as falling into two
-major categories: hooks that are used to manage the security fields
-and hooks that are used to perform access control. Examples of the
-first category of hooks include the
-<function>alloc_security</function> and
-<function>free_security</function> hooks defined for each kernel data
-structure that has a security field. These hooks are used to allocate
-and free security structures for kernel objects. The first category
-of hooks also includes hooks that set information in the security
-field after allocation, such as the <function>post_lookup</function>
-hook in <structname>struct inode_security_ops</structname>. This hook
-is used to set security information for inodes after successful lookup
-operations. An example of the second category of hooks is the
-<function>permission</function> hook in
-<structname>struct inode_security_ops</structname>. This hook checks
-permission when accessing an inode.
-</para>
-
-</sect1>
-
-<sect1 id="cap"><title>LSM Capabilities Module</title>
-
-<para>
-The LSM kernel patch moves most of the existing POSIX.1e capabilities
-logic into an optional security module stored in the file
-<filename>security/capability.c</filename>. This change allows
-users who do not want to use capabilities to omit this code entirely
-from their kernel, instead using the dummy module for traditional
-superuser logic or any other module that they desire. This change
-also allows the developers of the capabilities logic to maintain and
-enhance their code more freely, without needing to integrate patches
-back into the base kernel.
-</para>
-
-<para>
-In addition to moving the capabilities logic, the LSM kernel patch
-could move the capability-related fields from the kernel data
-structures into the new security fields managed by the security
-modules. However, at present, the LSM kernel patch leaves the
-capability fields in the kernel data structures. In his original
-remarks, Linus suggested that this might be preferable so that other
-security modules can be easily stacked with the capabilities module
-without needing to chain multiple security structures on the security field.
-It also avoids imposing extra overhead on the capabilities module
-to manage the security fields. However, the LSM framework could
-certainly support such a move if it is determined to be desirable,
-with only a few additional changes described below.
-</para>
-
-<para>
-At present, the capabilities logic for computing process capabilities
-on <function>execve</function> and <function>set*uid</function>,
-checking capabilities for a particular process, saving and checking
-capabilities for netlink messages, and handling the
-<function>capget</function> and <function>capset</function> system
-calls have been moved into the capabilities module. There are still a
-few locations in the base kernel where capability-related fields are
-directly examined or modified, but the current version of the LSM
-patch does allow a security module to completely replace the
-assignment and testing of capabilities. These few locations would
-need to be changed if the capability-related fields were moved into
-the security field. The following is a list of known locations that
-still perform such direct examination or modification of
-capability-related fields:
-<itemizedlist>
-<listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem>
-<listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem>
-<listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem>
-<listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem>
-</itemizedlist>
-</para>
-
-</sect1>
-
-</article>
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
deleted file mode 100644
index 8bf7c6191296..000000000000
--- a/Documentation/DocBook/media/Makefile
+++ /dev/null
@@ -1,388 +0,0 @@
-###
-# Media build rules - Auto-generates media contents/indexes and *.h xml's
-#
-
-SHELL=/bin/bash
-
-MEDIA_OBJ_DIR=$(objtree)/Documentation/DocBook/
-MEDIA_SRC_DIR=$(srctree)/Documentation/DocBook/media
-
-MEDIA_TEMP = media-entities.tmpl \
- media-indices.tmpl \
- videodev2.h.xml \
- v4l2.xml \
- audio.h.xml \
- ca.h.xml \
- dmx.h.xml \
- frontend.h.xml \
- net.h.xml \
- video.h.xml \
-
-IMGFILES := $(patsubst %.b64,%, $(notdir $(shell ls $(MEDIA_SRC_DIR)/*.b64)))
-OBJIMGFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(IMGFILES))
-GENFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(MEDIA_TEMP))
-
-PHONY += cleanmediadocs
-
-cleanmediadocs:
- -@rm -f `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(OBJIMGFILES) 2>/dev/null
-
-$(obj)/media_api.xml: $(GENFILES) FORCE
-
-#$(MEDIA_OBJ_DIR)/media_api.html: $(MEDIA_OBJ_DIR)/media_api.xml
-#$(MEDIA_OBJ_DIR)/media_api.pdf: $(MEDIA_OBJ_DIR)/media_api.xml
-#$(MEDIA_OBJ_DIR)/media_api.ps: $(MEDIA_OBJ_DIR)/media_api.xml
-
-V4L_SGMLS = \
- $(shell ls $(MEDIA_SRC_DIR)/v4l/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)') \
- capture.c.xml \
- keytable.c.xml \
- v4l2grab.c.xml
-
-DVB_SGMLS = \
- $(shell ls $(MEDIA_SRC_DIR)/dvb/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)')
-
-MEDIA_SGMLS = $(addprefix ./,$(V4L_SGMLS)) $(addprefix ./,$(DVB_SGMLS)) $(addprefix ./,$(MEDIA_TEMP))
-
-FUNCS = \
- close \
- ioctl \
- mmap \
- munmap \
- open \
- poll \
- read \
- select \
- write \
-
-IOCTLS = \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/videodev2.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/audio.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/ca.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/dmx.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/frontend.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \
- $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
- VIDIOC_SUBDEV_G_FRAME_INTERVAL \
- VIDIOC_SUBDEV_S_FRAME_INTERVAL \
- VIDIOC_SUBDEV_ENUM_MBUS_CODE \
- VIDIOC_SUBDEV_ENUM_FRAME_SIZE \
- VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \
- VIDIOC_SUBDEV_G_SELECTION \
- VIDIOC_SUBDEV_S_SELECTION \
-
-TYPES = \
- $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/uapi/linux/videodev2.h) \
- $(shell perl -ne 'print "$$1 " if /^}\s+([a-z0-9_]+_t)/' $(srctree)/include/uapi/linux/dvb/frontend.h)
-
-ENUMS = \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/audio.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/ca.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/dmx.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/frontend.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/net.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/video.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) \
- $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h)
-
-STRUCTS = \
- $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \
- $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s\{]+)\s*/)' $(srctree)/include/uapi/linux/dvb/audio.h) \
- $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \
- $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \
- $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \
- $(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/net.h) \
- $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \
- $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \
- $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
- $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h)
-
-ERRORS = \
- E2BIG \
- EACCES \
- EAGAIN \
- EBADF \
- EBADFD \
- EBADR \
- EBADRQC \
- EBUSY \
- ECHILD \
- ECONNRESET \
- EDEADLK \
- EDOM \
- EEXIST \
- EFAULT \
- EFBIG \
- EILSEQ \
- EINIT \
- EINPROGRESS \
- EINTR \
- EINVAL \
- EIO \
- EMFILE \
- ENFILE \
- ENOBUFS \
- ENODATA \
- ENODEV \
- ENOENT \
- ENOIOCTLCMD \
- ENOMEM \
- ENOSPC \
- ENOSR \
- ENOSYS \
- ENOTSUP \
- ENOTSUPP \
- ENOTTY \
- ENXIO \
- EOPNOTSUPP \
- EOVERFLOW \
- EPERM \
- EPIPE \
- EPROTO \
- ERANGE \
- EREMOTE \
- EREMOTEIO \
- ERESTART \
- ERESTARTSYS \
- ESHUTDOWN \
- ESPIPE \
- ETIME \
- ETIMEDOUT \
- EUSERS \
- EWOULDBLOCK \
- EXDEV \
-
-ESCAPE = \
- -e "s/&/\\&amp;/g" \
- -e "s/</\\&lt;/g" \
- -e "s/>/\\&gt;/g"
-
-FILENAME = \
- -e s,"^[^\/]*/",, \
- -e s/"\\.xml"// \
- -e s/"\\.tmpl"// \
- -e s/\\\./-/g \
- -e s/"^func-"// \
- -e s/"^pixfmt-"// \
- -e s/"^vidioc-"//
-
-# Generate references to these structs in videodev2.h.xml.
-DOCUMENTED = \
- -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
- -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
- -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\)\(\s\+v4l2_fourcc\)/<link linkend=\"\1\">\1<\/link>\2/g" \
- -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
- -e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g"
-
-DVB_DOCUMENTED = \
- -e "s/\(linkend\=\"\)FE_SET_PROPERTY/\1FE_GET_PROPERTY/g" \
- -e "s,\(struct\s\+\)\([a-z0-9_]\+\)\(\s\+{\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \
- -e "s,\(}\s\+\)\([a-z0-9_]\+_t\+\),\1\<link linkend=\"\2\">\2\<\/link\>,g" \
- -e "s,\(define\s\+\)\(DTV_[A-Z0-9_]\+\)\(\s\+[0-9]\+\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \
- -e "s,<link\s\+linkend=\".*\">\(DTV_IOCTL_MAX_MSGS\|dtv_cmds_h\|__.*_old\)<\/link>,\1,g" \
- -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
- -e "s,\(audio-mixer\|audio-karaoke\|audio-status\|ca-slot-info\|ca-descr-info\|ca-caps\|ca-msg\|ca-descr\|ca-pid\|dmx-filter\|dmx-caps\|video-system\|video-highlight\|video-spu\|video-spu-palette\|video-navi-pack\)-t,\1,g" \
- -e "s,DTV-ISDBT-LAYER[A-C],DTV-ISDBT-LAYER,g" \
- -e "s,\(define\s\+\)\([A-Z0-9_]\+\)\(\s\+_IO\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \
- -e "s,<link\s\+linkend=\".*\">\(__.*_OLD\)<\/link>,\1,g" \
-
-#
-# Media targets and dependencies
-#
-
-install_media_images = \
- $(Q)-cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api
-
-$(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64
- $(Q)base64 -d $< >$@
-
-$(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES)
- @$($(quiet)gen_xml)
- @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/v4l/*xml $(MEDIA_OBJ_DIR)/)
- @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/dvb/*xml $(MEDIA_OBJ_DIR)/)
-
-$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/uapi/linux/dvb/audio.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DVB_DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/uapi/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DVB_DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/uapi/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DVB_DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/uapi/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DVB_DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/uapi/linux/dvb/net.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DVB_DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/video.h.xml: $(srctree)/include/uapi/linux/dvb/video.h $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<programlisting>") > $@
- @( \
- expand --tabs=8 < $< | \
- sed $(ESCAPE) $(DVB_DOCUMENTED) | \
- sed 's/i\.e\./&ie;/') >> $@
- @( \
- echo "</programlisting>") >> $@
-
-$(MEDIA_OBJ_DIR)/media-entities.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<!-- Generated file! Do not edit. -->") >$@
- @( \
- echo -e "\n<!-- Functions -->") >>$@
- @( \
- for ident in $(FUNCS) ; do \
- entity=`echo $$ident | tr _ -` ; \
- echo "<!ENTITY func-$$entity \"<link" \
- "linkend='func-$$entity'><function>$$ident()</function></link>\">" \
- >>$@ ; \
- done)
- @( \
- echo -e "\n<!-- Ioctls -->") >>$@
- @( \
- for ident in $(IOCTLS) ; do \
- entity=`echo $$ident | tr _ -` ; \
- id=`grep "<refname>$$ident" $(MEDIA_OBJ_DIR)/vidioc-*.xml $(MEDIA_OBJ_DIR)/media-ioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \
- echo "<!ENTITY $$entity \"<link" \
- "linkend='$$id'><constant>$$ident</constant></link>\">" \
- >>$@ ; \
- done)
- @( \
- echo -e "\n<!-- Types -->") >>$@
- @( \
- for ident in $(TYPES) ; do \
- entity=`echo $$ident | tr _ -` ; \
- echo "<!ENTITY $$entity \"<link" \
- "linkend='$$entity'>$$ident</link>\">" >>$@ ; \
- done)
- @( \
- echo -e "\n<!-- Enums -->") >>$@
- @( \
- for ident in $(ENUMS) ; do \
- entity=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -` ; \
- echo "<!ENTITY $$entity \"enum&nbsp;<link" \
- "linkend='$$entity'>$$ident</link>\">" >>$@ ; \
- done)
- @( \
- echo -e "\n<!-- Structures -->") >>$@
- @( \
- for ident in $(STRUCTS) ; do \
- entity=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \
- echo "<!ENTITY $$entity \"struct&nbsp;<link" \
- "linkend='$$entity'>$$ident</link>\">" >>$@ ; \
- done)
- @( \
- echo -e "\n<!-- Error Codes -->") >>$@
- @( \
- for ident in $(ERRORS) ; do \
- echo "<!ENTITY $$ident \"<errorcode>$$ident</errorcode>" \
- "error code\">" >>$@ ; \
- done)
- @( \
- echo -e "\n<!-- Subsections -->") >>$@
- @( \
- for file in $(MEDIA_SGMLS) ; do \
- entity=`echo "$$file" | sed $(FILENAME) -e s/"^([^-]*)"/sub\1/` ; \
- if ! echo "$$file" | \
- grep -q -E -e '^(func|vidioc|pixfmt)-' ; then \
- echo "<!ENTITY sub-$$entity SYSTEM \"$$file\">" >>$@ ; \
- fi ; \
- done)
- @( \
- echo -e "\n<!-- Function Reference -->") >>$@
- @( \
- for file in $(MEDIA_SGMLS) ; do \
- if echo "$$file" | \
- grep -q -E -e '(func|vidioc|pixfmt)-' ; then \
- entity=`echo "$$file" |sed $(FILENAME)` ; \
- echo "<!ENTITY $$entity SYSTEM \"$$file\">" >>$@ ; \
- fi ; \
- done)
-
-# Jade can auto-generate a list-of-tables, which includes all structs,
-# but we only want data types, all types, and sorted please.
-$(MEDIA_OBJ_DIR)/media-indices.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml
- @$($(quiet)gen_xml)
- @( \
- echo "<!-- Generated file! Do not edit. -->") >$@
- @( \
- echo -e "\n<index><title>List of Types</title>") >>$@
- @( \
- for ident in $(TYPES) ; do \
- id=`echo $$ident | tr _ -` ; \
- echo "<indexentry><primaryie><link" \
- "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
- done)
- @( \
- for ident in $(ENUMS) ; do \
- id=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -`; \
- echo "<indexentry><primaryie>enum&nbsp;<link" \
- "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
- done)
- @( \
- for ident in $(STRUCTS) ; do \
- id=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \
- echo "<indexentry><primaryie>struct&nbsp;<link" \
- "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
- done)
- @( \
- echo "</index>") >>$@
-
diff --git a/Documentation/DocBook/media/bayer.png.b64 b/Documentation/DocBook/media/bayer.png.b64
deleted file mode 100644
index ccdf2bcda95c..000000000000
--- a/Documentation/DocBook/media/bayer.png.b64
+++ /dev/null
@@ -1,171 +0,0 @@
-iVBORw0KGgoAAAANSUhEUgAAAlgAAACqCAMAAABGfcHVAAAAAXNSR0IArs4c6QAAAwBQTFRFAAIA
-CAICAAQVEQEBAgsAJgECAAogAwsTAQopHQYBNAEAAAxNARQAERIQAhoDABwAABZEHRQKGRYKQw0F
-ACMBACUAERwpHR4cVRAFBR5rZhADACR2JiIhBDAGAiWGgQ4AcxQABDYACSeQMSYlJykmESxYlQ4A
-PSYZIS05OSsJHS5JOC8kAEMDUC8SADXLNDUzADbEAEsAADX/2RABCFIAAD/qxB0AAD//BFgAK0Vp
-WT4r3hwA3RsTRERAAEf/5CIA2iYCCUv+WUgz7iIAOk5g3CgVSU5SiD8uB2sABm8AE1X/U1RQOFyL
-4jkfIlz/RV98M1j+G2H/fVk23jtD4T0pXl9ieFtGcV894UIiYWJfAIwA50gOV2p+4kssO2j+dGZx
-bG1qVmj/OHH/aHJzfnBX5lQ7B50AZnahdXd0AKUG5V1ARnz/6mErCqgAAKsAent46GBIW4GhAK0A
-AK8B42FtALIOin9/ALUAiIOBALkAVIf/6WxWg4eBi4SKJrEAmoVtdY2geoP/rYVXhoyOqYVuJbUh
-IrgWX5D/jo6J7nszP7gAsI9S63xnN70zZqO/fZzCOb4+cZr+64dy8otYnJ6b7ImDRcM56IqcWMEo
-oJb/N8ZoTMRL7Y9/QchcsaOTo6eohaj/7ZqKXspXj6v9xal+oK+7d7vTUM+Afco5r7CumLTVStKV
-bs9ukbb/9qx/9q9l8queoLv/e9R66beG7rDImNRhi9aDwsPAs8bWzcK2cd67jtqP5MWUodyB8b+1
-tMr/z8L/j9+kbOXWnN2ZstD7yc7Rzs7Ly9xb183UwdD/+si/qeOmvuKIx9fj4tPCtuWiqOrL+tS2
-y9v++NPK2dvZt+m0ueq80+Wo3OeSwuy/yezG+d7f/eS/z/DS3uf/6Ono4PC71O39xPb02vPZ/+nR
-+Ori6e399+vt+PGz+ur65fL55/Xb4vbh7ffX/PPY8vP9+vLy6Pf36fjr/PfM8vjr//f+/vn48P36
-9vv+/vzf+fv4/fvu//z7+v7//P/7/v/8//QpxAAAAAFiS0dEAIgFHUgAAAAJcEhZcwAAFY8AABWW
-AQ2TT8cAAAAHdElNRQfaCRQXGSltwbPRAAAgAElEQVR42u2dDXwU1bXAZwEJtEaNH1nbh68fpoWK
-iE1ao2Bgo9RqIrEg+BIFmqLYLOlMcHHlU6DiQmrJM2jKo0QIBHgUjD5ETcQIlKq0gKDmA+UjiRAT
-BCOBkGzC5re/++6987Ezszszdzc7s9jfPa2wO+zMPefc/5575t67Z5hB/0Ek/W668xckcmVmQZ5S
-CvLmgshl4QCiZu+8ntCOgWlzVfrl5ZZFrl6T/VYSv9x5K3Pj9wnkh9fFFxQE6VcVqXY+8PjgH5K0
-+/0bBxDaYcsN0i+vLlTbzH9kjEknkEF3zptjLPPmXL2VwGC/nxysm+YRyc+/S2bHNYUgmtJkf5RI
-vScH3HEvifz05mhqB8G68d6xJO3ecSWhHXYfYdvM99LHGEv6mEF3zmFJ5Gr49e9qVUh7O/wP/w/9
-gf4EXnKwbpjNGQs779bvktlxzULg7TCQzvDAItBvzqMD7hjrMJaxPx0Cv3OdBvqFBRZJs46xCCwi
-O+xNwNfSclom6F2L4j1A/UsG1hgI1jyWUzLEKf/gX0CwevIzsvSlJoyh8IY5LmPhEFhEhsCI9b7L
-oy/uI2GBRaDfPATWaGO596dDADhioJ+7PKyI5SBoF4NFZAcEa6ZjvL7MOg9MAWtPxv4aHdlfM315
-TMHy7Gg4pifN5cUxBMsPisub9dRrqHc1xBCsC7vHH6jVlQOO3eGBhccc9B+rGIWkP/ALBNYEA3uX
-xxasooMGbVaWxhSs0kr9Njs8zbEE60C2UbOTTAOrR6/ZHjB/ZWzBet+gzR0xBmuHfpttsQbLIEP2
-ZpsGVrsBWMspWBQsGrEoWFEAK1UUDbBkQEkJu+Ko+WDxDRmApWmH+WCF0u/bCFYIMyIHK30CL1kZ
-Y1J17wo51snhW1/4d9BdoZlgcZx7mcezzM1yemBp22E2WBzL66fsExVYjmxBxsNed1gHVra8XX2w
-WBc2A/4dDbCSp4v/2PrGb1L1hkKnZ8sRNFH39cel6K1lQyFbvLcZXf3YrmWsNlg6dpgMFltc3dAN
-j3+zazWrCVbKBun8ltcfS3FYBpb0D721L+uCxXoqxO5VfEMiBmsa6BL/+UxWqhZYMFytPSVd5yMU
-qKxJ3jlub7f4D5f+xmqDpW2HuWCxr0r69b7N6oAV6JsTj6VYBpaciP9L0QaLVXQv13ewUqeBdjyS
-ZM0/Cf6uBRbkak03uLSraBHnWfsJAJ/LEi2TIxZs7bPyZS6XZwu0XEaWCiwdO0wFi3sXgC/K4QDi
-qfhEoV8QWNtT8FLK+L90gddHWwjWjNGw1dG/mgW7/jFNsFjYvd/sKnK73Kh7P4oSWHw3JOcDkJGq
-BVbxBfD5IidKqpzOV/3gb05rwGJfRXEAfYM41nMKfMXpgaVhh5lgsVsAeJvj9YOMXVrE6YAlvHwa
-XJSFLJPBOg8m8W2lpLwFQ5YjNFgc6t45OFCx0OVgNRu1iIVEByznu+ArIUixnPMfKGRZARaCSRpf
-ENx/4wwiVgg7TASLc52CA4f4BiobCFmaYDlSusBUC8GaGgC6VgssFnavS3QtC7uXiyJYMP09o5m8
-O2GfOsW8il1TudoisF4FX8hGvy3lc1yGYAXZYSZYa+RBitvy9hyXIVij744RWP+jDRb8ygaCFLdm
-x7KoJO/tyWj2Jz3/JPhjssY8lnNL91cvsNL8KOtk1fNY5iTv3D/AP2UJMaubvGvZYSJY8Jv+T04+
-8eAyBCsFdvBXVg6F2UK7k85oDoUs7N5FsiwjSsk7v5cKkqHsD3nEcm4BnznxHINTENaaCVJpcBGn
-zXQilpYdZoL1iThSB+kXBNbu8VOhzFhwAICXrUzeF2RPnTpp6qy/nAG9YzWSd5gpfqZhRl/AkpjY
-P0HrrtBZDQ468ZuKHVgqXdYk793Ag4zkllXyDZfq5FhadpgJVjMoxZ3g3sHrV84ZzmMB8LpjdCym
-G3r/oDXdwFaD97EZHG9FxQ53VHKsadOh5K8/q51jYbDwC/FSiywFixX7/Sirk2Np2GEmWA2gHOvn
-Efe3aCfvXiTA27J9lpVLOl7cLvyH2g2PaU6QSmCx4mXcXDTASkaSmpxxEvw1VXsofBLPt79/9AgU
-2DJr5VDIFh2rh9IM6vXA0rDDgqGQW4b1awAN+neFvzoDvpTPjlqVvD8Nw+ToFG2wxKGQO3gUmnEk
-GmAlS/M/Y5KXg5pkLbD45F3IsdhgsExO3vHS5JMV2mDp2GFJ8o71KzYCK+VhSJYjxXKw4A0DeF0P
-LDF5xxOVXLQiltg384PAktaanxSmG+D9AkrtEFhWLEKzr4Jv+FsUNOizO/QjloYd5k439C6SVIID
-doPRPNbTXeA96yPW6JS3AFCkWMrpBg/qXmmYcEcbLO2IxTrfBRdfcAqYOZ1WDYVozvGf0s2vkxAs
-6yIWGqs/l9ZsnWtBsxFYKHa8bOEitDiPBQfhc49prhWyqHuliWhX1HIsvI1JL8eCMJ0CF1ezeBxk
-iz+xLMdCSyYfzRZugbd0gCO6OVZoO0xd0lnTDT57QdiktqYDtBnOvMPYcc7CRWhpghSmWW9qgoVW
-EC6u5uMGh7s3KmBNQzJ9+UnQpTnzzjmLTwHwRUVxcemWBnjnusuqRWi0ctX5cXlR8dq9HQB8s1pv
-SUfDDlMjFkxPQO/H5auKy/e2of0XhmuFKQ93gTctHwpHO1ColA+GqkVovntXFQndG5WZd0m6fqe9
-bYZzej6RPvjZ6qAJUtP2vLNrpP0c53bNYXVm3rXsMHnbzFrJL727XtCbIA0srYA/pVg33SAu6dx9
-BpyQ3Teot80oujc6E6TtWBpr1mfobPRDUrzlSEfH10d3FcEbBws3+rnX7m3o6Pjm43K9jX46dpi8
-0Y9zFe891tHZ/HHFMo5zEawV/uo4+HKsVWCdli1C+2F2p7nRj+OK+O7dUeRio7vnPdVoazIr3/Ru
-4dZkce2bI9vznmr51mRh2wd72e95T9HdmhzKDEt+paP4MQX9+Rf9lU60wKI//6JgUbAoWJczWMRF
-QehQSMEyJWJNM7B3eYwj1re8KEhnjMGaZNSsaUVB0tcrZaPqbVaMyxiVVlcqRP22KLZljEqLlApV
-q97uiG0ZowOOVzboyitmlTECK6fly2V6fr7qfXtMwTpaVKyUUtX74uYYggVAs1o9lX5F1SCGYDWB
-l2bMVMos5dsZL4HwwTIQFwYrmmICWNEUM8CKnpgDFpmEAVZQM263+shsl1ZxWz/6H/oD/ukPC6x5
-s42L6s4mrEFqClgkRX8hWPeONRYzwBpN0i4Ci8iOkGB5Q7xjbP2CZGDwoX62K29Qy/U33RB8bEDS
-SLUkpfUlYjE3EMmVIewIJTZ7sH4FfQHrqhuuV8tNQUduuJrpTyQ228hg/UoiByuXsN3+A64OtiPE
-kauYEP0bslw4c9MD9xPIA9d/5wc/JJH+uWUlaunL6Di3P1GzPxhMaMfV920N0q8qcvVO27/34/80
-lh9/b8D9D5DIz+3B7ivZFzlYv73+AaKG7x9AaEd8YbB+IUdH5hdkddR/9H2iOuX3XrE1ujnW3O+Q
-tXsdqR3PRnko/GUGQXX5jNsYjki9B5JIWvWSg3UrmVtY5jYSO9J/SV7n/efzOJKsDYI1mkSugOGp
-7ai+HAsLrLEE2afj3uvI7JhzEwTrgJGEA9ZtRPXlbx/wJMlNCA/WfgNpB/4wwCJyy5PM7UQ56u0w
-x2o7YtC/bSaB1eZx6xcqd9XHFKyXpLpnGuLYQBwTog+WF7wmlo3TkIzp7SB2YJ027F63p80csOoX
-dXR3aksHKC2PKVjZG8BpPQEvzYgpWPkrhd1koaWnJqMmhmCdqXd3dOpJd4e73hywjngM7C2viClY
-M7YbtPnKrFiDpSutWY0xBcuoe4HHNLC6KVgmgtUYa7AM8ncfBYuCRcGiYH3rwRJ+UKYLVookVoLl
-0Gw3FFgh7TAZrNRkQVKNwVKXCLIIrNBuUYKlZUZfwOJYd3FpeemqZawOWI4VCwSZ6bAyYk0V2501
-VVnzIBgsDTvMBSt1+vL5WPKVtZNCgMW6iqB6pcs41lKwtNyiACt1gmjGNHWZ/IjBYj17+T0jX+9a
-xGqCNT5wlZbXrQMrJUBEb+0f5D9NDwJLyw5zwUreLx4/80Z6qg5YrGvLMeykznplPXiTwZLc8o3K
-LQqwkqX9cl5VdbGIwWLXXIDGNjc0dwBwSfFLRWXEAoB/NN3xLgBetw6sDeC00C5UT/5LXjVYmnaY
-DNYe0IoeydgIe75GBywO/SC0t62hARXpV5S7NhcsdouWW9RgdfFm+EGXskx+hGCxW/yoTjnHch6o
-wsUXdMDi053Rk94CQFFewmSwtgsp1oIz4M2xmmBp22E6WCtxapK+shv8MVUTLM8p0LurCFVRXauq
-B28qWKj2hcwti3TAqklORRlWvrpMfoRgeU6Cz4VfvqLyDB+x2mA5UCV62OV3v6V8xoHpYOHC+6ic
-9CUZ0CqwtO0wHaz1yWPSUfb7GngjWQss9l0UL4QSVKgevEVgofrtvFtw9Y1drA5YqenIjuT5UqGx
-voCFCnzPFltzvgo+l1XADwZL6Oy/SHUIrAFLfH0azNACS8cOK8DCr1aCPVpgscXdgSjFek71yoqH
-mAkWrt+u4ZbgiKWuYNcXsIrlNe9dntJlLpcxWG8pC+JYBdbDivroSrB07LAALFw9acwH2kMh7ODP
-ZflN6arZ1kQsPbeEAAvbsTIaQyG79pQ8HXEpCnyHzrFSUHGJP8Ugx4Ij8InHNHIsPTtMB2vjmIyM
-jKzpe5QdohwK/6GsB29R8q7rliCwxmRBM6at7z7zm2iABb7RLPCtBmsFlld2A/CplXeFtQtwuxvO
-AHmxFDVY2naYDpbU+2O0wTolPPmBcwbVgzcVLB23aEw3gK7fJfd9uoEtB8f4Osw7ULnc+vpjHlYL
-rIDjP1UW/jUZrIC8PFoTLB07LAML7E/XBMsnlBUv4tU7uoO1BKwK0S2VQrsezhAs0Pi71KiB5XaK
-v6srZnXnsbygd/tMVWFnk8FqOYAnsb58KVt75l3PDvNzrFS0E3nCym7FWKgEqxsUadSrNxUsyS1t
-wW4JcVcIBT2VrysKEWut/yIfossr0SMJOsEqVjfHelo9O2pRjvUW+FJZ9Fc9FGrbYdFdYWry/G4g
-G0XUQyFOojkPUq/iiKxIr7lDodotRazBXWFqctZJ8NfkKCTvwnQsXw65Qw8sNI/FFwxPsRYs9BzH
-46D3MZ2IpWOHVdMNY1JrwHwNsHTq1ZsJFgfd8oLCLYZgwZfrFfNxkc5jfSKfS2QNwBIKhv/J4oiF
-XkxCFTS1F6F17LAMrGRtsFhUDz6g7A6LwFK5hbMQLG4NWl/gxJKMHXo5Ft+vdx9XFQy3BCx+ENZe
-hNaxwyqwUtNPakcszyk0A87x6jmrZWXFzQULAh1wC8z0VhmClZr6RjTAQlN34O1l+HET7jUNQIa0
-BlgpDwNFOWmrJkhhqOzVWYTWtsOatcLk5DGvgTOy/Q2qJZ21F8AXq92ouoq7aK8ffMxatFao7ZZg
-sPj9WMv9QHFbGCFYnAs23ftxZcWOgx3oOezGM+9BT8+waOYdDoafai9Ca9thOlh7lq+Esr4GKJJe
-1SI03nzxBVSvGpW9/uwFa5Z0VG659LbOPFYjNmPlHgD+nhyV/VicVEi996NlrM5+LLG3YQ9flG+6
-Mxms3YFnGsufIBm0H0vLDqv2YwGwUXc/VvFe8XNflLo4y/ZjabpFcx5rf3qUdpCyruLqg0cOVpe7
-We2Nfo7aA9Ja4YLa2plWgbXi+EvSIvT22t1jdXaQathhMljra/BPlfe8sVK5jSloBynLeir2HqlH
-5eBZ6/ZjSW6pVLtFCVa+YMaejdNTo73nnTXY8x76tfl73h2ybfcke97Z2Ox5Tybd887FZs87S7bn
-PWjTu9m/0nE4ZC8dlu15d2i1e9n8SkeonfFt/5VOuoYd9Odf9OdffQKL/q6QgkXBomBRsPoKlo+C
-9e8MllGzZoFV7+4EPm3pBqWxBSt7A/DqyWVQxqirpwv+H/6BRfybF9AY4zJGHt3u9YFOs8BqVlfi
-KlIXXjsYU7BWOCYpC61NUr6f5NhArJ4ZYK1Pn6astKZ6mzWtNYZgnf7aYyjNPFizSeowQ7DGkgiq
-QdpWf0QhR5Vv64+CcMAiaheBRWZHqFKRu1UCog7WbQOcROWucanID5RSs3+PUlrDKhVJ5BYnQ2iH
-vQl8repetdTj/ZXMreyTBML+6EbHHSRyRYmv6fQZlYDI5ZnvELU7+joyO5w3PXO+6YJKuiNXr8l+
-+5hfGkv67cyjThI3329vamrqVYu61TCK2/6IzC2PwohFYAeMWB8Gd29IdZgBVwbJVVcFHxtgG0wk
-tiH2IBnZB7BKCNu9NpQdwYeuZOKD1IvP7QNYSf0GBsmg4EP9mBC6XB3iWLB69viIn3ngA8+GajeU
-MKR2BOtnD13nPbNuH4HUjcwl+ty+pMLgz9X1BayRZPpl9sGOPujXNKSs7kNjqSuzV5HoV1eYFOJo
-U+Rg5RK6pcreBztCTgIwhF/XtKVkn0siqfPeRe6bQsLHWuROJrRjIYimNNnJqKyznyf63NakaGrn
-Azk5ZJ/sIraDpM67VwCrcf1GXVnfDjtkLgANldX6gsAqA2C//vXWv0acJPBgvW/QbmUbADkQrI0b
-CewoAJ1GZlSHAxYcB+r1L1gJ7773oWfQbDd4HNsBASwD7SobwgLLf3yDgWzn7TDqXtGOAxsM7fBi
-sHqmTcifriP5WfkYrA6P+nlsKnFVYLBqMqZN15X0jWFFrGqXfrPFniIfAmtlhq4Zgh3PglJ3qbEd
-YYBVb6Sfqx53yAbHzBm64qiFYPlAhUtfvyJPWzhgeWdkz9JtdqZjA7TjX4bdy9txoXb8jBmGdmCw
-2rMMJtzemIDBanYbGFRZjMHak2VgbziP7oVgVRg98PSYuwOBZTRjzdvxLPAYPmG1OCywqosMPlRU
-jcFascDgc9m7MVhGj+7tcDeEA9bp8bUGH1uwAoH1tbuDxI4LB7KBsR08WBP2AP6Rb/5QAjtkGg+W
-0SNj0bOUk/hnQoe8EN9GTwRg6Q/sxzydAlh+YzuejfIzoavA+0ZgreLBemmBfgrgJQQrnGdCQ7DO
-Zx8wSIh4sNoMA+EqASyyZ0IjsPYbfNPDBSuKT7EnilgSWAR2ULAoWBQsChYFi4JFwaJgfVvBajcA
-azkFi4JFIxYFi4JFwaJgUbAoWBQsChZN3ilYNGJRsChYFCwKVphg5RCCVUAG1pCS6A6Fc0eSgNUB
-cu4jBKsgumDFE4IVTwZWmT3KYGWC00RgxROCFU8MViEZWLklZGDlVEU3YpXlkkWswgIysKAdUQUr
-s44IrLpMMrCqMkFUwVo4lzBiZf7raxKw6jK7ScECRGChaxGBBSWqYEEhAgsKCVjQDm80wUJCAhYS
-ErCQRA8sLERg4e5tI7Jjd1TBQjuiiMDygegOhfCCZGD1kEUsnzeqEQvZSwSWjxAsX5TB8hGC5SME
-yxdtsC77iOUnAwsKjViXU8QKC6xoRiwKFgWLRiwKFgWLgkXBomBRsChYFCwKFgWL3hVSsChYNGJR
-sChYFCwKFgWLgkXBomBhsGoIwTIoR1IpgmWg4PIwk/dygw80IMUgWOsJwTKsNhNlsIolsPRlkgBW
-pf7HOsIFy6jazIoVRN0r2LHbsNrMJBGsjNcaa3SkcT1fl6jBVd/coCNtFXz5nz0ZNcrrqa7emB8m
-WMVtDbrtHnR1oC9e/nxdMyQ7PJUG16soDku/ao+uWxqaPTwpK2Ycr9WV8TxYxeW6+jUfcTWEo97p
-8dv12z0+cwXfvUeI7Ng9vraWwA4IFliZkaWQaRMUbydk8KHAV+7WL+8t1G9vn66+nvJtFnEBfGGk
-W2RQVhwXSvNDoLN0RbSj0uUhsoNUDOvaCxGmdrxKpirfOma04M/VG+jnLveFpd8Kh7Kd7Gy1IgeI
-ulewo2WG6nrjs0PZwaCa4Y2tja2tjY3wL/g3fo3+j9/gF9LorpQO1Xt+jPaDdnxuo3AJ8bKyNkjr
-lIuxv81AhM81tirsaNWyo43wepHqp37fKeQyLcdb9OT4eSEHazO4XpjqAf1moVZ8uz4jt3TyZpw3
-uh62gyFSzQ8uf/H/m9jxbyIMdQEVChYVChYVChYVKhQsKhQsKhQsKlQoWFQoWFQoWCD0g0V8fvUL
-2SdDbKDwmqqu1xtQQd1SqCNBp/WYrKDkpR5/kEt9BKf5zFscUDTfE/zSq+llXwTdq4hYWwvmIlla
-8o786M6SwmeXbj6ruOjhrYVzl5YdEo41FSycK5z5odnfhJadJagZ6XG7hULLSBm0ZFNXoDgiSi86
-benmdtO/qYGGsGuqeJfOXbi0rJVfUtonOHnp5h6VlxeqvRxlrsokXTa3KjpzHWq6Sd408vKzopel
-M5eWHIpsKExjBIkfd1LEc93wBHxo2JRuiebD9wyxoWOJ4w7hz9QxktinmNp3LYtvxi3HD1si+EFs
-2JY4hf9yyHXhu9ILehcPF0/zmxey4IV7BXfFDVvSjRvKlanzIj5SKB0Y9g7Q8rIpYKUxoZremZYg
-eOuk6JqAlzerzhTACBesTGZkDpTJsKlbeANbHoH43Dc5J3M4w9wiXvP5BCYOHUuzMQO3ocel1jHx
-OVgyYf89ZOJ37vBQ6JP7YDsJjO0hXsN4JlNs+SkcIhi7qAsDj3Sh074cJZ3G3GVaz6H9C7Ahu+Cu
-u86iYwVMkqBOAtNvG3JNCX9kMjww6JD8tEzey2dN857QvTk5sH8HviN00xM2Ji5tMvZfIj7mlbyc
-hrzs589ME8Eg9Z8KrBL+xbqh/V7EcX0iE7fkEPrWt6yTrvmcjZnyYQ+Ol6OYQTU4YsVLEaV/3Aem
-9dyXI5jEzdjxdYttzO9xOLIzTfwQ9Hx/rEsVIz7bvOURW2KNeNqSJv60BHiaecPgKNjQId4PCcyD
-PFjis5EPj7Jh1kqYTOHACPgRv+RlIHj5Qb95YJWIugy1Pci/eo6JEzpz3XAhdEB3DdvcJHr5KcWZ
-6wbzYIQNlvjA9CeY3yKbN6GQJMh7gxkcGE8k2J4Sj50bxUzhwRLzu97/Mq/n4LWlqAnxjsOv7cw+
-4V+HM1sxWElisnnpZ7YXkRXPMbdIucEm4bToC24oUcpON/W3HVKABb66FkeoEiYNKojo2cQMA7yX
-A6dBL79jHliFUjPMNThlec8WJ4FyYiizJNjLiScVSCIwIgfLDxZiPHqHMjI+JyIdusAjzDi/6Enw
-pu2hs3Kw/HJPRrvjDg+OCzj93IjEDySwvH6o2HDbZgVYXYI9h69gtgXgHJG4zaxtWS3XMbJrTxy4
-TeUO/jvAg4XzdeYWrNJ1zIuB9GFi3IsWgNXL2M6jUW8UzFykf3+OeQpqj73slcYI6OUAWH6QRxo3
-QkescyP6ob54b8A1rYF/PXcIJiz+iz/jUwW+oUsfnvdaFrH+zPwk0AG9hw95gWwohN91/EWTR6x7
-bEuE0wLSiawwR95kftKtcpccrBPX9jskHwrBRD4rhNHjrPo08yPWoPNYpUEBiADsTOyuu4CkQm8n
-9LIsYn05ot8HEYGVu68KyrpRcLSDt3+/tj0l3HBCEW6Ot18x7JR0DM+6+GU5Vi/MsfaY1XG/Zv4X
-KNThc6wSrPPihMRtQJFj9T5iG/gBPu2/g08zI3VXNCT0TagcKw0rvPUe20N4UgJ62a/2sgU5Fmpz
-Q/9xFwKdqeVldGYeD8bQuCWE92YqsEQZ181rsjTohHXMfUGXhmAVYMk19a5wKBNiGiU+XtSZn26o
-YobMRark5eK7Qi867R1ggfjguLI56GgBM5JXJwfeSgt3haLGiYcwj6G8bBJYabwu8IZ0IJ4oeoZ5
-POj7EexlnwqMSMCyJyEZYkP5G5q+4BH3jeQlTYjkXlxCPAkfS6rDYEkTHQ+1muYaO1OHo03VEL7l
-PB6sJEFnfGsMwZJ0ieMjwRCmisdfUDgH+MzpuJH47gGAJqGhTHisIDB3lMinEBAsXuEEG8zZ/TIv
-JwW8bBJY4pyfeLeQJ8bTNEFlH/DFq7xcgM+UgxF5jtWybiiDponE75JPpAb75T4erCTh4D4MVi6U
-oTbhZtskuVn4LolzoJkibcJEBx6Jqhg7VCUnIT5xyVnxtHeEWMZLmllgpQkRS5wvTsJgjczLzc0c
-HD9MnPUXcyzv4XuYRMXXV+ZlsyIWdE1mf2bcZiHuSBFLRA7mqwlBXg4Moi3rbmYe8kcOFkzuEq75
-AA23S7AGvq1QqgqZIfD17sHj+ByrCh3cahfAQkc+HYxaNW+x60Zh9G/C6uSIYO0Tb/ZtP+mRcqxN
-trglqtSMPy3XLLACORbvLogUBiuXny5KFO9MA3eFJ0b0ezHotELIo6k5Vu9E5hYxY39ezLFwZ5bF
-I7DUXs5RpP0QjJo+gNUDhjNl6DZHfldYh8E68bNB2xTD077AXeGmBHT3ahpZf2YelC2eFirAQvdT
-TL/zgbvC51CGhXVR3hVuNQss3JDM9io5WLA3+21TgyVMCilvJveZCVYh8si5UWjePYBJICXGEes5
-6OUumZdz5Gm/X5gtjBSsLhif4fmXZPNYfvAhAgvNYz0kW65UgAWet9leNAsrPzjcP64m8G6pGqxe
-xtYjm26YaBO6Ep4mZu9ePygzD6xzV0jzWLChrXKwwLkRaNxTgCVOcp2TzbMhL5sLFpozGMrccoEP
-sqOYpwJN92CwdvZPVHhZAVaXlEhGOBQKcUk+lQzvB6/FlPfv91RgkeVaOVj+XvhlOGkWWTiIB67+
-hHoofNP23XYZWOew+/zq0xabB5Ziih+6Sw4WzhOE5F1U4NJE2+9BsJeHmD6Ptckm8iRfWgGH8awp
-dNddSi+LYHl5MPZHApYAZssjDB58YSOJwlrhzidsaAUCyNYKfXWLb7bZ6gJgecGJwba7zNs+EFjF
-atl5j42ZrJggPTwUeyswQWjMGXEAAAJqSURBVPpef366gV8rPCuddp9pYPGLkry7HrEx4+RgoTUo
-YbohU5zzs/FBLMjLfpPBgtFcXISeKK4Vnt+3OMEWh159qvTy44oJ0ntIJxxUYKUVoNu7nOEMjs5e
-YXcDOmJjmHHC1/F5G9rdkItWv6EKfsXM+3MMs80srsR1d3hnAxWMm9LKg5WTh3TOTGDUM++PMGgM
-9PrA4VH8adiKKa3m6Ye2UUjuwhMvAbBganNLK45YSdjJuXg/hh97+Z4QXjYTLDgY3iXQ/QQT6Mxx
-7wS8PFn08ln+fhI7OedmJo5wUjD0fixmmLRss244nhey2ccJW3jwfqwEfr/OyCU9wv21CNalEcwg
-8wZDaacQY59yiE/NmcBWITznt5Wxi2DBACJsQhH3Y/GnmSi968SGkLu8aD9WjrSM0h9veAjsx7Lz
-82z8Nq74wGlmgZXGzBW/AZsYKbkS92PF4xiBs4qWxUPkXvaFBCMcsEpy87Aod1ruLJlbwG/HlO0w
-hMcKln4oZDdNuXmBT+dONm8XKcqYdhbCljdLq2sFvMoFS/mOBHU5c6UAsi53ssiR+jTzBDaUt7Ss
-SbwJzSmTdH8+93GYX1TlCE4uUygDvZyn9nKUwSrJqZLePZO7tNsrtHUYdTDuTG9IL/tkYBAvORnu
-eff6Zb0qSo/OcADM3Pfu1VHWq3fAr2djlNlXudQXdCTYjV4L6uCodfEG97RwSL7nXa2zPwKwqFCJ
-mlCwqFCwqFCwqFCwqFChYFGhYFGhYFGhQsGiQsGiQsGiQoWCRYWCRYWCRYUKBYsKBYsKBYsKFQoW
-FQoWFQoWFSoULCqXq/w/gbudjI6bMwYAAAAASUVORK5CYII=
diff --git a/Documentation/DocBook/media/constraints.png.b64 b/Documentation/DocBook/media/constraints.png.b64
deleted file mode 100644
index 125b4a94962c..000000000000
--- a/Documentation/DocBook/media/constraints.png.b64
+++ /dev/null
@@ -1,59 +0,0 @@
-iVBORw0KGgoAAAANSUhEUgAAAlQAAAFYCAYAAACVsmLPAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A
-/wD/oL2nkwAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAAd0SU1FB9sLCBIAKVtZsMAAAAxxSURBVHja
-7d3ZbqvIAkDRLsv//8v0QytXvpYZap7Wko56OAnE2AXbBSbhOI7jHwAAkr1sAgAAQQUAIKgAAAQV
-AICgAgBAUAEACCoAAEEFACCoAAAQVAAAzb2jvyMEWw0AmFvh37xnhgoAQFABAPT1zvruwtNlAADV
-VLxsyQwVAICgAgAQVAAAggoAQFABACCoYEohuFkugKACsmLq178DIKiAyJgSVQCCCigQU6IKQFAB
-BWJKVAEIKqBgKIkqAEEFFAgkUQUgqIACYSSqAAQViKkwxjIAEFSwbUyJKgBBBWJq8GUCIKhgm5gS
-VQCCCsSUqAIQVMBYoSOqAAQVLOk41lwXAIIKhoqqJyFUYhkACCpYMqpiQqjEMgAQVLBUVKWEUIll
-ACCoYImoygmhEssAQFDBElHVexkACCoAAEEFACCoAAAQVAAAggoAQFABAAgqAAAEFQCAoAIAEFQA
-AIIKAABBBQAgqAAABBUAgKACAOA/b5sAGjsO2wBgMWaoAAAEFQCAoAIAEFQAADtzUXohIQQbAYDi
-Dh9kmYIZKgAAQQUAIKgAAAQVAICgAgAgmU/5VeSTGQDE8InxeZmhAgAQVAAAggoAQFABAAgqAAAE
-FQCAoAIAEFQAAHtyY0/o4O7efe4JCzAXM1QAAIIKAEBQAQAIKgAAQQUAgKACABBUAACCCgBAUAEA
-IKgAAAQVAICgAgAQVAAACCoAAEEFACCoAAAEFVBICGMsAwBBBVPHVE4QlVgGAIIKpo6ps/9utQwA
-BBUsEVMpQVRiGQAIKlgqpmKCqMQyABBUsGRMzbouAAQVNHMca64LAEEFy0WVmAIQVCCqxBSAoAL6
-hI+YAhBUIKrEFICgAvqEkJgCEFQgqo4+3wuAoILto0pMAQgqICOQxBSAoAIyQklMAQgqICOYxBSA
-oAIyokpMAQgqICOqxBTAvN42AYwTVQDMyQwVAICgAgAQVAAAggoAQFABAJDMp/y4FIJtwJx8ehJo
-yQwVAICgAgDoyyk/HnMKhdE5RQ30YoYKAEBQAQAIKgAAQQUAIKgAABBUAACCCgBAUAEACCoAAAQV
-AICgAgAQVAAAggoAAEEFACCoAAAEFQCAoAIAQFABAAgqAABBBQAgqAAAEFQAAIIKAEBQAQAIKgAA
-BBUAgKACABBUAACCCgAAQQUAIKgAAAQVAICgAgBAUAEACCoAAEEFACCoAAAQVAAAggoAQFABAAgq
-AACGCKoQPAs2JQAIquwCUAI2JQAIqowCOPtvbEoAEFQRBaAEbEoAEFQFCkAJ2JQAIKgKFIASsClh
-szEKrDGoXkNuiOPwwim4iezYoc9+39iDfQbVq+mGEFOiCjZ7E23swR6D6tV8Q4gpUQWb7PeNPdhn
-UL26bAgxJapgk/2+sQd7DKr3EDE1y96mUPT1fqgh6Ffosbsz9mDdQfXquiEY/rUKlBtLYgoqDJZB
-Dmjlg8qRWlSBMSSmYLOoKhtUjtCiCowdMQUbRtXLswUgpkBU5XkXf9CmPJZ9nQJrft6Gife9XmC/
-t0mHg9tr3FcJYgrmjilgn8Fa55SfI7WYAvtnYKNBW+8+VLGn/zY6wtd4qDY1iCngx+BtdNCre1G6
-W3gPt7MXUwAwW1CJKjEFCzB2wODtH1SiSkyB/TKw+KB9DfnARJWYAvtnYKLB+m7+AJ+UgL2WTQmT
-jz1jEJVf0ASD7jXck2/vY1PCQscwE+6wfkz1CaqrB6wAbEoQVcBkMdUvqH49cAVgU4KoAiaMqb5B
-9bkBFIBNCaIKmDSm+geVArApYaOxZ4zCuoPq5VkDqL//F1Ow9qASVACV9/9iCtYfVIIKoOL+X0zB
-HoNKUAFU2v+LKdhnUAkqgAZvqoG1B5WgAgAQVAAAggoAQFABAAgqAAAEFQCAoAIAEFQAAIIKAABB
-BQAgqAAABBUAgKACAEBQAQAIKgAAQQUAIKgAABBUAACCCgBAUAEACCoAAAQVAICgAgAY3NsmIEYI
-//3zONK/7u/v/nx+zdPl/1rO0++LWd6vZZ59Xe7jSfnZSq3z6jnJ2ValX09PHj9AD2aoiPJ34Lo6
-wJWKiJQD7N2BN/WAzbNtZTsCuzJDRZeD8XHkH3zPZo5CSJudeTKbdrX+lkE7QkzFbq8VHj/AGTNU
-dDkY1ziw1jjY7nAA/wzKqxnIu5gSPICggoTIuDroXh1YRz3ohuCUlcgESOOUH81iZdR1fJ9+zL1Q
-use1Y6nrvLsearR46rHNAQQVw6l14HtyOurJz5USVqs9LynXt8V+ShBAUMHHQfdzFuMsQGqHSW5M
-PQmrVtdsjRCkOwY5gKBiGne3Okg5WJaMqbuw2uX5+P6aX4H8/f922F4AgorlgyD3hp47z3ycPfZf
-p/FSb00BIKjg4kD8/cm4mFNjKfd/OpsJyb2GJ+V+UzEXSK9wAfuvqGr9s7ooHRiV2yYgDCe8xUOp
-gHny2GNjVdwAOzJDRbUYSfnep8srfdCOWV6tr225ztzt3PpxiTRgdGaoAAAEFQBAX075sbS7C6dH
-OJU0w8/ocQEIKjY2w0F71bAQTMBOnPIDABBUAAB9OeXHY36tCAD8ZoYKAEBQAQD05ZQfl3xSCwDu
-maECABBUAACCCgBAUAEACCqgiRDczwtAUAFZMfXr3wEQVEBkTIkqAEEFFIgpUQUgqIACMSWqAAQV
-UDCURBWAoAIKBJKoAhBUQIEwElUAggrEVBhjGQAIKtg2pkQVgKACMTX4MgEQVLBNTIkqAEEFYkpU
-AQgqYKzQEVUAggqWdBxrrgsAQQVDRdWTECqxDAAEFSwZVTEhVGIZAAgqWCqqUkKoxDIAEFSwRFTl
-hFCJZQAgqGCJqOq9DAAEFQCAoAIAEFQAAAgqAABBBQAwibdNAECqcPKLJo8fH1cNN7+U8up7jpOP
-v6as//PvPr+/xPpTlsEazFABUDSmnsRTie/pvX74ZIYKgKz4+J55+fu7EMLPWZmU2auY9YsjejBD
-BUDRmDk7pdZq/Vf/P2bZT7/2OI7/rU/ICSoAiHIVLS2uFyq5Dtc3kcspPwCairmQvHUghhBOT1U+
-eQx/fyfQBBUALBNrtcPmc/l/QYagAoDqYi9ib/2zPZ2l+hVw7Ms1VAAkKXXbgpIXkH9eIF7r8T15
-bEJLUAHA4wD6FQ5PPoVXc/0ll3/3db/+sCen/ABIio7PU3U5YfIdY0++78n6RzPqxfiUYYYKqh94
-rv/AzFGV8nelouLue3JC5e5XzTx57E777SUcsa+4zxeIo8HlOw/vOgBwLBlqA1drGDNUAACCCgBA
-UAEATM2n/CpyQSIA7MEMFQCAoAIAEFQAAIIKAGBnLkovxI3XAGBfZqgAAAQVAEBfTvlBbXf3I3O6
-GGB6ZqgAAAQVAICgAgAQVAAAggoAAEEFACCoAAAEFQCAoAIAQFABAAgqAABBBQAgqAAAEFQAAIIK
-AEBQAQAIKiBFCGMsAwBBBVPHVE4QlVgGAM29bQIoGFOf/30c7ZcBrV/zd6/Rq6/7fs1/fs3T5Z+9
-AckZO2dvaL6XeffGJ/XxpPxspdZ59ZzkbKve278BM1RQOqaeDvbSy4CW/g5WV6/RUhHRcuwYc2W2
-VY3tP/hzY4YKar5bfLIDeLIMM1WsOnaOI/9AeTZzETt2YmbTrtbfMmhH2PfFbq/Syxxk/2iGCmrF
-1Kzrgplez78OpjUOsDu8qfkMyqsZyLvwSdleNZYpqGASLQe3GSpGHgNXB92r1+6or+sQvInptV+a
-eF/nlB/kDv7aO14xxUpahErqOr7Hc+yF9y3Hbul13l27NPJ+aJBTgYIKRo4qMcXK46b2wTVlHb9m
-3VpcXD/i85Kyb4v9lGCvZQoq2CiqxBQzvfY/ZzHOAqR2mOTG1JOwanXN1ghBunucR3INFYw4qMUU
-K/sLsO9rlXKuXSoZU99jcfXxmPpp5LP7f5W+B9Ukz4GggtGiSkxBn5ja/UL0v3D5/nO1jyq1zWos
-szGn/KDGTinnoliY9TV/FzZnr++U+z+dfcIw93qblPtNxVwUvcIF7N/7uZJRlbLMQS5KN0MFtQ4w
-YgrWGberjs+Y21vExmqN/eDAz0M4jsifrtZ5alh5ZyWmAMbaJxfe75qhgl7veMUUwDIEFfSMKjEF
-sAQXpUOrqJrk5nSwpLvT7yOMxxl+Ro9LUMFQUSWmoP348zN6XIIK7FgAWDWo/DZuAAAXpQMACCoA
-gM7iT/m5BgQA4P+YoQIAEFQAAIIKAEBQAQAIKgAABBUAgKACABBUAAB7+hfHbDX87cMFJQAAAABJ
-RU5ErkJggg==
diff --git a/Documentation/DocBook/media/crop.gif.b64 b/Documentation/DocBook/media/crop.gif.b64
deleted file mode 100644
index 11d936ae72e8..000000000000
--- a/Documentation/DocBook/media/crop.gif.b64
+++ /dev/null
@@ -1,105 +0,0 @@
-R0lGODlhuQJGAeMAAAAAAH9/fwCvAP8AANEA0dEAAK8Ar////wCOAAAA0QAA////////////////
-/////ywAAAAAuQJGAQAE/vDISau9OOvNu/9gKI5kaZ5oqq5s675wLM90bd94ru987//AoHBILBqP
-yKRyyWw6n9CodEqtWq/YrHbL7Xq/4LB4TC6bz+i0es1uu9/wuHxOr9vv+Lx+z+/7/4CBgoOEhYaH
-iImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6gQC9vr/A
-wcLDxMXGx8jJysvMzc7P0NHS09TV1tfYxbth2d3e3+DRAePk5ebn6Onl4ezt7u3q8fLqANtg7/j5
-+s/z/f4B+wIKHAjsn8F09ex5IciwobuDEM1Bi0ixosWLGDNqrJhQIZdk/htDihxJsiTJiSZTqlzJ
-MmNHj1q+tRznsKbNmzhzDoz3EiYWmTN7+vQJgOfQmN5mAjzKtCg9pj+TBoU61ClCqlaAthSKVZdV
-dFy7NtHKMqxYW1/PmT2bhOzKtWxlpZUYF4pblXDrvpq7Tq+Tu+UGCB5MuLDhw4gTK17MuLHjx5Aj
-S55MubLly5gza95MmVxev0EAkxsg8jNoVXNJ0zy9RPQ41RtNsz6V2vPstlLTwdYo+zap2qt9G3Ed
-YLdL4bGAL0VOhLhxjL2Zf1IeXboM56Wtt6KuPXRudM8vVu+eiTt5H9hDjj9vyfyIXrTW80gfO4OC
-+/jz69/Pv7///wAG/ijggAQWaOCBCCao4IIMNujggRe4J4IwBxBg4YUYZqjhhhx26OGHIIYo4ogk
-loihMBbi1k084VlklgLsWQKjBRJqgIwEBJRyY4UqZsNidhjMGOMkQlLgnjERwkdBjuVpk2QFTB5B
-H2/2DUlJkRNYhWQKUTKyJQpdFjHlcUFaSaQxo9nGQph/fCkDm0OMCV2VZh7iZpbnwCYfBnDKcecO
-fXq3ojotckRnnXr8SQGWEtQIphuKEhEoEHKKdygHCUiQ6QEJdDrEphWA2oGo3UXaAaMHOHrCpFmY
-2gSr6H2XJ5AXoHqBp5xyuimpPfCa6we+6uWqCaiqagKsTAxrBbLz/slqTqEUvWgBqLviSqqvnXpq
-rbbZTpDtt9ziSsG3unKraabkltutWMq+UOyswa3A7A/tfjGvDpW6eKm3v+a667i38vvvuQLzW7Cm
-AJ878L/W9ouuR/Xi8O6zasorRMRo3JtDvoaWOe2v4IIc7LUIE4zwtd1Sm7C6KZ8MLsmzYBzExIFV
-rILGJsgcB843cBztvgqHWnKwup5s8rroVivwwEc3DHLR/jKcis5K0JxmvDezQLUePNvgc0TSBix0
-1OuG6nS56nob7ssqp132wuIi7cnWU1j9ms1chkD3IF3X8DVEYe9AtNi37M2F3cXh/WgFhjPSNw1/
-HxS4CS97MPjH/ts5uQfieqbQuCWPzxC5QZPncPnYoXz+BueKY+Bm6J3AHsPo/5TOmup5sB5vxLJv
-0vsLtPtjO1W4D0Kz6r9nknwLwfczvFeam6IAmndjnfcsy2vtbM3qAT2KkhkULwj4SRITIbzLWYx9
-j9j82L3HvyljivzeG1tC9qCzf4379cEPigACCAYAB0jAAhrwgAhMoAIXyMAGOvCBEIygAVMVDBLo
-Ln1ZWx8SmjeP521CAEYiXypAGML1XHBPF8BfJVToue1drX+1GgUJZTHDFJywBSycRA5PwEF5eFAT
-NYRFEE9wwzXRYoc5c2H1YGgBW32QFkMk1vkoZr3FyQKJJeih/lH894kotsKLFpwi9zB4vSvqzxr8
-oxIXPQHGVbRRBEVUnxk3qMTEvS+GonjjBBCwxwMg4I+d0CMI4pjBOUqpjtACm/c4IUhASuCPfPQj
-I1lAyDLGAosk0OJT1hhIC0RSkpDsoyg9GUpAhtKPp6QAJD9pB0F+oJJWvOQZq5FGMuExFFHkYyR1
-OUpWqrKPvHykJIXZyzy40gOwXNURZ0mNWs6Jk5P0JChXKUxHXsCXwQTlKIe5h2OeSowvRKEFMOkI
-ck4IkbRqogyvaU1uZpOd1URlNXepSnriwZscSOaxlknHQekmnRVwIhAxgM09rtKXBrXnKalJzFTe
-AZ8b0Of9/vh5SH+CB6CLWicPEAoIiGpAoiQwp+OYOQ1nWgqaT0TBQTl6TUN4tH7oEyeUKDocdN5R
-nXnsAUv98FJO2i+kNBWTTZkYUI3SkJLgXKJMlxTU5gxVjbf8HxSRSqOY4rCpcXqqLXGKy6muAKQj
-EOkixPoBTV4FpQOdRU+jiicqkjGWsCCrB8wKlkWm9KhfTaod36pMDVbUR4TC6AQEmom1spGqjLOq
-Ef1aU4uiD6pclapaEWskxcpRlv0E7D9vWtScTjavVXXrUicgV0SUlgN0VYtd04pXFYBVBKc1RGxt
-pNVnsvWwn3WtXju3WEM2VrMX5WxGPdtaG+62dftkrFAd/utWyHa2q7k1bmjHOFocYfVitT3pbTsZ
-XRS8NgSzJUR4XZddfaG1sF7V7XTDeVXlOpW5Y3TucKFbXO8et4p99e1ygfvYrT5XsvUl4n35mlz9
-vpe/zfXvfAEcC8P+t63Uba+BswrfF8p3sEZtMGUhzN7eYvav7QuscDFMXA2DNrGilfCHfxvizRJ1
-wV1Mr3RRHGEPx5Wk0jCpebcbzQBLcb1KVfGNM9vi4L6YxPQ1sXpp3OHLDhnE+xPxkSVAWEw4uMcz
-rmyKbfyK8ZYPwfFVMJIZLMQNN8qyhVzxfovcX9tGNsbdFTCQ91pdHrmXwmC2sJipnOEyn1jLNXZy
-l3Es/g4pX5jPJfbzkgHd5DQ/mcVRdvGhD1DlS1z5rlnmcJC57Aov06i8HeMxphWd6TNvWdCdJjRK
-JL1nSvf5FZdGNJM3jepWeJpxoP7Zea0sY/vOmbe1ZsWtS5jnJU660paINXr/rGk6C3nQRI60kY/9
-alco+7sgGLYftN2oXCty15butZxn7WxO21rV/DB0q5FdCWXzmtmmDrSjoQ1lNKrbzQ/GrY9LgO0P
-cJsP/04tXcCdbHH/mNzAnneqo21vVuMbxvpWcqlThWZLPnrN0m6zdt8ccVL7GuHIneidsVthY6+7
-2l80M8VPrfBzM5yW9954vrm77zD+OuRAHbmgir1X/monGtYq/2lYr7tzNif44WOGc81H0G8P/HsP
-Afc24Fa77KXDccB1fjrX0O0MHYea4zSX+McZTeuWC5vrzfC6rkXNWrGPm+zlDvYqol7ynp/859YO
-esXhSm9IN3zad0+yx9/e7IRbvO8Y/7vGdwx2LA/+4HA3PN8XXm+YO1zmEA/74/mN9WdT3u+WBzzS
-ZU1moMN75fI+/OcTH/rFf33mjjf9oguP86HrnFJSlxzV3231EDS9A1rPA915nsipE7zdBuf8zfFb
-YDUf2OhhHr2r8Z7y0wsdtkTHfd2Lr/vjU8Ld4bb+3vPrfDxDX8/SZ/f3k29zkDNf5BMmOfEFS3ql
-/rsd8rR/f87jX/SMHx3zSddxsjdx1wde2UcvuUc6uxd+vTdInWduZ/dyzRRzjAd7ozaAY5d/BAZ/
-5Sd/52dy6YdyrHBtDyh3qjB8H2h3IUh9I6h3LKd6Lld5E3h5FZh5sZd34veCkxeDoDeDogeA9SeA
-ODh78dZoMBiBMlhSFPh6NniBQ0iA49d8F/d8/hd9QDh9goeBhFeEZXeEc4d2zKB238Z2VXd/yud+
-G7h/Hdh/ivd/NRiAmqeF+MeFcWd2XyiBSkiDTAiHN1h9RIh6RriDSNiDefiDbxiEcfiEGUiHkkd+
-U2h+VYh+V6h+kyBBlniJmJiJmriJluiCqSeI/neYhDm2hGvXeJzgCzEjQkxXgnZ4gmC4DGJofGS4
-CcAAC7XYfpFXe9h3ewi4ffSHhfGjiqvwC2eYi/pne/ynffM3YoiYOqhoi894dcuXhsi4hsqYgtyn
-gN5XHt1mi93oe6zoha6Ih6Ooh6VogTpSZ+3RG7/HAcGHBygYiSA4idCYisgUjqA4jqJYaOY4hqY4
-NepYCcI4cwWYbQcYK77IjMBYj3KxFu24Ae94B/HYhlZ4iAuZHAFJCQP5kBoQkXYwka3nhnvYjAyJ
-kWBXkP52kD0gcH2xjQBpj3CIkk6nks2SkFN2kWiRkZOgJByZAR5ZByDpg653jk1YCwM5jADQ/pN8
-QpM7wJIhR4l7oZOSoIoyCXxMiS8JWDsLaJRS+QgwQj5V6Y5XuTFZKTxbmZOvICRKEpYQOZY44JTv
-B5Xx0ZWKgCW+EIUc+IgeKI8qSI9YcZSiUCxp0YhSiHhUSJGSaJFyWTh0WQjv0guB6IiGCYmIOY+K
-GReA2QnHUxSEmZeTuZeV2ZeXWReZqQl2A5nHuIvJ2IvLeJOLuQ2leQmcA5lZ55Y9U5bOc5ZHEZtX
-cl+8mZK8iJCt6XO305h6cEK/KZbBuZK42UG6STzGeQdFlJw+aZte05w+9Jx/GZ10QEjUOU7W6TfY
-uUWzKCzcGQew9J2kFZ6QM56bVJ5+oZ6E/qBP6vmTdBCUhTiU/oiOtyGfgQBS1Gmfc4Cf5WiII4mT
-0uGffvBavymgckCg/GigRMmH1qGgm4OP5GWVy1mTwxl4Q2KheNB0memgO/OKyhCL3QefzAGiddCO
-R0micAChqyah+1mU58GicsCRwgijbyCj6daPsviPMYKjq4OhZdUTPOoGPtp1pFijFGomRMoGSvmN
-draawomNv/iaCXqeh2Ok51Sl1siaWKqQWlqhXJoFU4pr7Ck67nlWKgqlZ2oFaQolUZo/5Bih+hmk
-/IkoIfQHc8pUFKSXbBiSFXmgZcoedQoGf7qeWRKngrCkadekemqjfPokx+mlakilqQCp/mEoqSkq
-pJWaoSGKqdXYp5tqoiDhqdr4pqFqqi1KqqppqabAqbCoqlrpkq3aqK86jbW5AYlqWqiKDCi6qqCa
-q7Q1B4tqXR3wq4VAqydqq2aJq8bqqm6QrGCKWo4KlMF6DMN6q6w6rbIqpbBqgHqTrQ+6rdQDpJ+6
-p+C6rObqA9baNcy6behaDN0ard/arqKaBvGaRJzgrKmqrsTKrvo6V++aA/3KQwebBgArrNCam9Ja
-sPtKBgmLAvMqkfVKDPcKsfkqscdKseNqkCtwsfeZscOwsc4ZsR4bPgsbAxU7si0bBg3LrQ+bsh27
-sr4asy3wstojCTObrjQ6qU+Ks/7q/gU8yzw6uwU/a681m50qS7Q52wVH6wIkuwZLq7FNS57FCrVZ
-lLTFqIG92p4jdaczmqfrSqlcq7BoGrLAeZ2KcLUnm7XvubVpW7RVMLVsCqxk+6NBe7ZDW7cqULUu
-y7Yz2ZRe+wRwKwwo67Q3C7jlWjeEq6HNIl4mq7hy66Z067gWe7gwpYOSiZWPWrnBsLhaS7CaG7ic
-e5J4manMCQiJO7qXW1dPe7pfygR4O7l98LoFEbuqNbu0W7tJcLutC3Wiu7sC662Z+7swG7yRq5w1
-tXV7y6THi6/Jq7zLawTCi3vwWLy/QLpza7rWS7U6m73e8ZHce5e8O3CNG76bOwTk/otdJRu9kTq9
-HFu97Iu0M9O8bfkEgvsq54ua9Guz9nu/+Auv+tuRUtC/SqC73Zu+Lbm+BIy6PfC+h6Sk/8sXiWmo
-EQy/OkDBdMQGDIy+Acy4A7zBwHOeHowbahDCANy3A4u2JnybN5DCSqDAQcDCGGyZGhzDTlUDNNwa
-qQuB18iX2Yi84MvDbisDP5wsQSyOV0rEWYrEFQwDSzwWTVyYlEmoGTyhJCnFCOguB1yd3HDFpXqY
-WqzDXIygXly+nhiZWNwFNmwDOOy9mHvEa0yWOfiJn/sFcTwDc+zAT3nHQAyFnvvG90DGzkuIBWq2
-L/y3gqy9cwiIXZiPfIzIYryP/mUrkml8qI8snl/LiLpIrmrQx0IsplBMpp38F+NRxUhBBX88wqUL
-w6nMxq8Uxkv5BqS8x4MqlJrspF08y897j7zqeWuQy6ybxbxcqJsMzFEQm6xcyU7wyi5sxLLMzFkV
-UbacQnZgzG2ryHjay0L7y9b8wT61umXsJ6krzYxMzY48zlNMkOYcq9t8uOoMzn4rzu6swpnHlgi8
-B9x8y5jMt+tMvXaczz2MiPx8yf4cs/WszL6sxgatyjiZ0ADdB//MqAEtvdNM0NUc0eSMhmHbJu/a
-0Fv80Jzs0T8wPT1B0do8CNxM0mhs0ih9BTMCPiwNnoWQyzAtmjs801RQJPBx/tMzZSdcutNFzNHt
-7NNHwCgtPMm6zAvcadRRrNSQ+2lf0ZnHnNPGKdWoTNVSMDGoidXnTNQ0wNWu6dVfDU69INbyvAgX
-a9bEidZOgDioGdKOwKxw7aFybbvHFY2tmAiJmtcruNdNgJyl7NbVJdh+Sdh8Pcw4yiwGMAGRbQCU
-jQGRnQKXvQWPfcF0LLsQzNg+XIIgiiyVLQGUfdmZTQGpbQKr3cpPbcqhedT1W9CgjbDhqKBsktmT
-XdoHkNqtXdqnLdm7fdqVTdy7PcaGPMSxPdW1zbzD/GnHPNmm3duSXd0XIN3TTd3ajdoVwN1iIJ+K
-PZrNjQQS9Z1wIt3GPd28/m0B2L3d2e3dxJ3dY2DenA3IcTnezg3SUdvNwu3b1d3aqt3b8P3e6m3d
-AH7IIpvR87vRs93R+D3D48qbfbLaup3e7G3avD3g1G3c7W0GEl7fsPy9Dv7gof3c7prIolCa4d3T
-JO6+kQuYssPhgL0WK77MLU4ED7mWQ40KOg6oCt6pIV7HI37jg2vi50Q+SVoGxIjR3pzJDh3OEE3k
-tm3kR94RSa7k0VjjMi3l+Uvl5fqMV04GFaTlUH7SXL6FklyH/hrmZ+ALZH7PUX7mJa7fa2Iidn7n
-eJ7ner7nJgLiDC7AtC3neezG9wuXG2jmgr6KXh7Bhv5DiT4D1qqvja6d/o/+h0K9spPuu5UujXTO
-w5n+2ZsOjotOwJ9ewqGOi2ArxaUe6Keu6J0ew6s+5K3u6sZIjdYb60k962h+6R6L6/is64uY5myt
-vL4e58Ae7LwuscWO6Me+XclesMve7EqczUQb7dJOxdSOs9Z+7S4Q6e267dzexk5N6m3q2aYe7uVc
-yIVe7r0L6ugek/FM7OyuvudurAUgAfd+AAWw7z+Q7yfg79806utuk3F9uvyu7/qe7wCvAwtPAg3/
-UdmO6fP+wPVuJf5+7/uu8BXw8BmP8QrP7x0/AR0/8gl/8CKf8fhu8hpf8h4P8iHfuXpM7gAw8wBQ
-8zZ/8zif8zrf2e1e/vEWj/AIv/L4fgEXD/QXX/RFL/JAv/RLr/JDb/Qpr/QmD/ECz746f/VYj/U8
-T++sjigYz/Jfn/AYsPBC7/Rkj/JJ//Ri//Qr//FKz/JU/+omnPV0X/dbT/FdXyco//ZCbwEHH/Z/
-//drb/Z9H/htz/Ypr/Fp7+zx/rt1//hXf/eB7LhkP/Qk7/eCn/hwr/kjf/lBv/d7v/mKj/ahn+4x
-P/CQn/o5zNM2jtIPnwGvvwPeDq6qX/uSf99I3PkeEPtE7+JVH761r/q3f+g+zft+7/tyv8HBn/rD
-7+jvLurJz+jL//jNT+nPb/qEbvXTb/f2fegP8v3gH/7iP/7kX/7m/n/+6D/707r93K8bnPH+8B//
-8j//9F//9n//+E//oez47J/1SmHJEHDkpNVenPXm3X8wFEeyNM8RCFa2BVA4lme6tm8g13e+9/lW
-UDgkFgOvW1K5ZDadT6hSVURGrVdsdvnjdntGcHhY1ZbNZ3Ra3ZkSyWt4XF7z1rtivNi+5/f9f8BA
-wUHCQsNDxETFHaO3uUfISDa7vErLS8xMzU3OTr1Az1DRUdJS0yBHSdXVyL3TV9hY2dmjRdtb3NxB
-2iNW3985XeFh4mLjY+Rk5WUeYOdn6Gjpaepq62vsbO1t7m7vb/Bw8XHycvNz9HT1dfZ293f4ePl5
-+nr7e/x8/X3+G37/f4ABBQ4kWNDgQYQJFS5k2NDhQ4gRJdKLAAA7
diff --git a/Documentation/DocBook/media/dvb/.gitignore b/Documentation/DocBook/media/dvb/.gitignore
deleted file mode 100644
index d7ec32eafac9..000000000000
--- a/Documentation/DocBook/media/dvb/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!*.xml
diff --git a/Documentation/DocBook/media/dvb/audio.xml b/Documentation/DocBook/media/dvb/audio.xml
deleted file mode 100644
index a7ea56c71a27..000000000000
--- a/Documentation/DocBook/media/dvb/audio.xml
+++ /dev/null
@@ -1,1314 +0,0 @@
-<title>DVB Audio Device</title>
-<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It
-can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and
-ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/audio.h</emphasis> in your
-application.
-</para>
-<para>Please note that some DVB cards don&#8217;t have their own MPEG decoder, which results in
-the omission of the audio and video device.
-</para>
-<para>
-These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use
-of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls
-have been created to replace that functionality.</para>
-
-<section id="audio_data_types">
-<title>Audio Data Types</title>
-<para>This section describes the structures, data types and defines used when talking to the
-audio device.
-</para>
-
-<section id="audio-stream-source-t">
-<title>audio_stream_source_t</title>
-<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take
-the following values, depending on whether we are replaying from an internal (demux) or
-external (user write) source.
-</para>
-<programlisting>
-typedef enum {
- AUDIO_SOURCE_DEMUX,
- AUDIO_SOURCE_MEMORY
-} audio_stream_source_t;
-</programlisting>
-<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
-DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
-is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
-call.
-</para>
-
-</section>
-<section id="audio-play-state-t">
-<title>audio_play_state_t</title>
-<para>The following values can be returned by the AUDIO_GET_STATUS call representing the
-state of audio playback.
-</para>
-<programlisting>
-typedef enum {
- AUDIO_STOPPED,
- AUDIO_PLAYING,
- AUDIO_PAUSED
-} audio_play_state_t;
-</programlisting>
-
-</section>
-<section id="audio-channel-select-t">
-<title>audio_channel_select_t</title>
-<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the
-following values.
-</para>
-<programlisting>
-typedef enum {
- AUDIO_STEREO,
- AUDIO_MONO_LEFT,
- AUDIO_MONO_RIGHT,
- AUDIO_MONO,
- AUDIO_STEREO_SWAPPED
-} audio_channel_select_t;
-</programlisting>
-
-</section>
-<section id="audio-status">
-<title>struct audio_status</title>
-<para>The AUDIO_GET_STATUS call returns the following structure informing about various
-states of the playback operation.
-</para>
-<programlisting>
-typedef struct audio_status {
- boolean AV_sync_state;
- boolean mute_state;
- audio_play_state_t play_state;
- audio_stream_source_t stream_source;
- audio_channel_select_t channel_select;
- boolean bypass_mode;
- audio_mixer_t mixer_state;
-} audio_status_t;
-</programlisting>
-
-</section>
-<section id="audio-mixer">
-<title>struct audio_mixer</title>
-<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio
-volume.
-</para>
-<programlisting>
-typedef struct audio_mixer {
- unsigned int volume_left;
- unsigned int volume_right;
-} audio_mixer_t;
-</programlisting>
-
-</section>
-<section id="audio_encodings">
-<title>audio encodings</title>
-<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following
-bits set according to the hardwares capabilities.
-</para>
-<programlisting>
- #define AUDIO_CAP_DTS 1
- #define AUDIO_CAP_LPCM 2
- #define AUDIO_CAP_MP1 4
- #define AUDIO_CAP_MP2 8
- #define AUDIO_CAP_MP3 16
- #define AUDIO_CAP_AAC 32
- #define AUDIO_CAP_OGG 64
- #define AUDIO_CAP_SDDS 128
- #define AUDIO_CAP_AC3 256
-</programlisting>
-
-</section>
-<section id="audio-karaoke">
-<title>struct audio_karaoke</title>
-<para>The ioctl AUDIO_SET_KARAOKE uses the following format:
-</para>
-<programlisting>
-typedef
-struct audio_karaoke {
- int vocal1;
- int vocal2;
- int melody;
-} audio_karaoke_t;
-</programlisting>
-<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both,
-Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the
-right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left
-and right.
-</para>
-
-</section>
-<section id="audio-attributes-t">
-<title>audio attributes</title>
-<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
-</para>
-<programlisting>
- typedef uint16_t audio_attributes_t;
- /&#x22C6; bits: descr. &#x22C6;/
- /&#x22C6; 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, &#x22C6;/
- /&#x22C6; 12 multichannel extension &#x22C6;/
- /&#x22C6; 11-10 audio type (0=not spec, 1=language included) &#x22C6;/
- /&#x22C6; 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) &#x22C6;/
- /&#x22C6; 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, &#x22C6;/
- /&#x22C6; 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) &#x22C6;/
- /&#x22C6; 2- 0 number of audio channels (n+1 channels) &#x22C6;/
-</programlisting>
- </section></section>
-<section id="audio_function_calls">
-<title>Audio Function Calls</title>
-
-
-<section id="audio_fopen">
-<title>open()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0)
- for subsequent use. When an open() call has succeeded, the device will be ready
- for use. The significance of blocking or non-blocking mode is described in the
- documentation for functions where there is a difference. It does not affect the
- semantics of the open() call itself. A device opened in blocking mode can later
- be put into non-blocking mode (and vice versa) using the F_SETFL command
- of the fcntl system call. This is a standard system call, documented in the Linux
- manual page for fcntl. Only one user can open the Audio Device in O_RDWR
- mode. All other attempts to open the device in this mode will fail, and an error
- code will be returned. If the Audio Device is opened in O_RDONLY mode, the
- only ioctl call that can be used is AUDIO_GET_STATUS. All other call will
- return with an error code.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open(const char &#x22C6;deviceName, int flags);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>const char
- *deviceName</para>
-</entry><entry
- align="char">
-<para>Name of specific audio device.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int flags</para>
-</entry><entry
- align="char">
-<para>A bit-wise OR of the following flags:</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDONLY read-only access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDWR read/write access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_NONBLOCK open in non-blocking mode</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>(blocking mode is the default)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>Device driver not loaded/available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>Device or resource busy.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid argument.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="audio_fclose">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call closes a previously opened audio device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(int fd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="audio_fwrite">
-<title>write()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected
- in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
- PES format. If O_NONBLOCK is not specified the function will block until
- buffer space is available. The amount of data to be transferred is implied by
- count.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>void *buf</para>
-</entry><entry
- align="char">
-<para>Pointer to the buffer containing the PES data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t count</para>
-</entry><entry
- align="char">
-<para>Size of buf.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EPERM</para>
-</entry><entry
- align="char">
-<para>Mode AUDIO_SOURCE_MEMORY not selected.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ENOMEM</para>
-</entry><entry
- align="char">
-<para>Attempted to write more data than the internal buffer can
- hold.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="AUDIO_STOP"
-role="subsection"><title>AUDIO_STOP</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to stop playing the current stream.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_STOP);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_STOP for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_PLAY"
-role="subsection"><title>AUDIO_PLAY</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to start playing an audio stream from the
- selected source.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_PLAY);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_PLAY for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_PAUSE"
-role="subsection"><title>AUDIO_PAUSE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call suspends the audio stream being played. Decoding and playing
- are paused. It is then possible to restart again decoding and playing process of
- the audio stream using AUDIO_CONTINUE command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call
- AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume)
- any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is
- performed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_PAUSE for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_CONTINUE"
-role="subsection"><title>AUDIO_CONTINUE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl restarts the decoding and playing process previously paused
-with AUDIO_PAUSE command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>It only works if the stream were previously stopped with AUDIO_PAUSE</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_CONTINUE);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_CONTINUE for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SELECT_SOURCE"
-role="subsection"><title>AUDIO_SELECT_SOURCE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call informs the audio device which source shall be used
- for the input data. The possible sources are demux or memory. If
- AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
- through the write command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
- audio_stream_source_t source);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SELECT_SOURCE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>audio_stream_source_t
- source</para>
-</entry><entry
- align="char">
-<para>Indicates the source that shall be used for the Audio
- stream.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SET_MUTE"
-role="subsection"><title>AUDIO_SET_MUTE</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
-&VIDIOC-DECODER-CMD; with the <constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant> flag instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the audio device to mute the stream that is currently being
- played.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_SET_MUTE,
- boolean state);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_MUTE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>boolean state</para>
-</entry><entry
- align="char">
-<para>Indicates if audio device shall mute or not.</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>TRUE Audio Mute</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>FALSE Audio Un-mute</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SET_AV_SYNC"
-role="subsection"><title>AUDIO_SET_AV_SYNC</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC,
- boolean state);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_AV_SYNC for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>boolean state</para>
-</entry><entry
- align="char">
-<para>Tells the DVB subsystem if A/V synchronization shall be
- ON or OFF.</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>TRUE AV-sync ON</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>FALSE AV-sync OFF</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SET_BYPASS_MODE"
-role="subsection"><title>AUDIO_SET_BYPASS_MODE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward
- the stream without decoding. This mode shall be used if streams that can&#8217;t be
- handled by the DVB system shall be decoded. Dolby DigitalTM streams are
- automatically forwarded by the DVB subsystem if the hardware can handle it.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- AUDIO_SET_BYPASS_MODE, boolean mode);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_BYPASS_MODE for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>boolean mode</para>
-</entry><entry
- align="char">
-<para>Enables or disables the decoding of the current Audio
- stream in the DVB subsystem.</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>TRUE Bypass is disabled</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>FALSE Bypass is enabled</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_CHANNEL_SELECT"
-role="subsection"><title>AUDIO_CHANNEL_SELECT</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
-<constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> control instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_CHANNEL_SELECT for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>audio_channel_select_t
- ch</para>
-</entry><entry
- align="char">
-<para>Select the output format of the audio (mono left/right,
- stereo).</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_BILINGUAL_CHANNEL_SELECT"
-role="subsection"><title>AUDIO_BILINGUAL_CHANNEL_SELECT</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is obsolete. Do not use in new drivers. It has been replaced by
-the V4L2 <constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> control
-for MPEG decoders controlled through V4L2.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to select the requested channel for bilingual streams if possible.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>audio_channel_select_t
-ch</para>
-</entry><entry
- align="char">
-<para>Select the output format of the audio (mono left/right,
- stereo).</para>
-</entry>
- </row>
-</tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_GET_PTS"
-role="subsection"><title>AUDIO_GET_PTS</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is obsolete. Do not use in new drivers. If you need this functionality,
-then please contact the linux-media mailing list (&v4l-ml;).</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to return the current PTS timestamp.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- AUDIO_GET_PTS, __u64 *pts);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_GET_PTS for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u64 *pts
-</para>
-</entry><entry
- align="char">
-<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
-</para>
-<para>
-The PTS should belong to the currently played
-frame if possible, but may also be a value close to it
-like the PTS of the last decoded frame or the last PTS
-extracted by the PES parser.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_GET_STATUS"
-role="subsection"><title>AUDIO_GET_STATUS</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to return the current state of the Audio
- Device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_GET_STATUS,
- struct audio_status &#x22C6;status);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_GET_STATUS for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct audio_status
- *status</para>
-</entry><entry
- align="char">
-<para>Returns the current state of Audio Device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_GET_CAPABILITIES"
-role="subsection"><title>AUDIO_GET_CAPABILITIES</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities
- of the audio hardware.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- AUDIO_GET_CAPABILITIES, unsigned int &#x22C6;cap);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_GET_CAPABILITIES for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>unsigned int *cap</para>
-</entry><entry
- align="char">
-<para>Returns a bit array of supported sound formats.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_CLEAR_BUFFER"
-role="subsection"><title>AUDIO_CLEAR_BUFFER</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Audio Device to clear all software and hardware buffers
- of the audio decoder device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_CLEAR_BUFFER for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SET_ID"
-role="subsection"><title>AUDIO_SET_ID</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl selects which sub-stream is to be decoded if a program or system
- stream is sent to the video device. If no audio stream type is set the id has to be
- in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7]
- for LPCM. More specifications may follow for other stream types. If the stream
- type is set the id just specifies the substream id of the audio stream and only
- the first 5 bits are recognized.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_SET_ID, int
- id);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_ID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int id</para>
-</entry><entry
- align="char">
-<para>audio sub-stream id</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SET_MIXER"
-role="subsection"><title>AUDIO_SET_MIXER</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = AUDIO_SET_MIXER,
- audio_mixer_t &#x22C6;mix);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_ID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>audio_mixer_t *mix</para>
-</entry><entry
- align="char">
-<para>mixer settings.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="AUDIO_SET_STREAMTYPE"
-role="subsection"><title>AUDIO_SET_STREAMTYPE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl tells the driver which kind of audio stream to expect. This is useful
- if the stream offers several audio sub-streams like LPCM and AC3.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE,
- int type);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_STREAMTYPE for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int type</para>
-</entry><entry
- align="char">
-<para>stream type</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>type is not a valid or supported stream type.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="AUDIO_SET_EXT_ID"
-role="subsection"><title>AUDIO_SET_EXT_ID</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl can be used to set the extension id for MPEG streams in DVD
- playback. Only the first 3 bits are recognized.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int
- id);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_EXT_ID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int id</para>
-</entry><entry
- align="char">
-<para>audio sub_stream_id</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>id is not a valid id.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="AUDIO_SET_ATTRIBUTES"
-role="subsection"><title>AUDIO_SET_ATTRIBUTES</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is intended for DVD playback and allows you to set certain
- information about the audio stream.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES,
- audio_attributes_t attr );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>audio_attributes_t
- attr</para>
-</entry><entry
- align="char">
-<para>audio attributes according to section ??</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>attr is not a valid or supported attribute setting.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="AUDIO_SET_KARAOKE"
-role="subsection"><title>AUDIO_SET_KARAOKE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = AUDIO_SET_KARAOKE,
- audio_karaoke_t &#x22C6;karaoke);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals AUDIO_SET_KARAOKE for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>audio_karaoke_t
- *karaoke</para>
-</entry><entry
- align="char">
-<para>karaoke settings according to section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>karaoke is not a valid or supported karaoke setting.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section>
-</section>
diff --git a/Documentation/DocBook/media/dvb/ca.xml b/Documentation/DocBook/media/dvb/ca.xml
deleted file mode 100644
index 85eaf4fe2931..000000000000
--- a/Documentation/DocBook/media/dvb/ca.xml
+++ /dev/null
@@ -1,582 +0,0 @@
-<title>DVB CA Device</title>
-<para>The DVB CA device controls the conditional access hardware. It can be accessed through
-<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
-including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
-</para>
-
-<section id="ca_data_types">
-<title>CA Data Types</title>
-
-
-<section id="ca-slot-info">
-<title>ca_slot_info_t</title>
- <programlisting>
-typedef struct ca_slot_info {
- int num; /&#x22C6; slot number &#x22C6;/
-
- int type; /&#x22C6; CA interface this slot supports &#x22C6;/
-#define CA_CI 1 /&#x22C6; CI high level interface &#x22C6;/
-#define CA_CI_LINK 2 /&#x22C6; CI link layer level interface &#x22C6;/
-#define CA_CI_PHYS 4 /&#x22C6; CI physical layer level interface &#x22C6;/
-#define CA_DESCR 8 /&#x22C6; built-in descrambler &#x22C6;/
-#define CA_SC 128 /&#x22C6; simple smart card interface &#x22C6;/
-
- unsigned int flags;
-#define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
-#define CA_CI_MODULE_READY 2
-} ca_slot_info_t;
-</programlisting>
-
-</section>
-<section id="ca-descr-info">
-<title>ca_descr_info_t</title>
-<programlisting>
-typedef struct ca_descr_info {
- unsigned int num; /&#x22C6; number of available descramblers (keys) &#x22C6;/
- unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
-#define CA_ECD 1
-#define CA_NDS 2
-#define CA_DSS 4
-} ca_descr_info_t;
-</programlisting>
-
-</section>
-<section id="ca-caps">
-<title>ca_caps_t</title>
-<programlisting>
-typedef struct ca_caps {
- unsigned int slot_num; /&#x22C6; total number of CA card and module slots &#x22C6;/
- unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
- unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
- unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
- } ca_cap_t;
-</programlisting>
-
-</section>
-<section id="ca-msg">
-<title>ca_msg_t</title>
-<programlisting>
-/&#x22C6; a message to/from a CI-CAM &#x22C6;/
-typedef struct ca_msg {
- unsigned int index;
- unsigned int type;
- unsigned int length;
- unsigned char msg[256];
-} ca_msg_t;
-</programlisting>
-
-</section>
-<section id="ca-descr">
-<title>ca_descr_t</title>
-<programlisting>
-typedef struct ca_descr {
- unsigned int index;
- unsigned int parity;
- unsigned char cw[8];
-} ca_descr_t;
-</programlisting>
-</section>
-
-<section id="ca-pid">
-<title>ca-pid</title>
-<programlisting>
-typedef struct ca_pid {
- unsigned int pid;
- int index; /&#x22C6; -1 == disable&#x22C6;/
-} ca_pid_t;
-</programlisting>
-</section></section>
-
-<section id="ca_function_calls">
-<title>CA Function Calls</title>
-
-
-<section id="ca_fopen">
-<title>open()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
-<para>When an open() call has succeeded, the device will be ready for use.
- The significance of blocking or non-blocking mode is described in the
- documentation for functions where there is a difference. It does not affect the
- semantics of the open() call itself. A device opened in blocking mode can later
- be put into non-blocking mode (and vice versa) using the F_SETFL command
- of the fcntl system call. This is a standard system call, documented in the Linux
- manual page for fcntl. Only one user can open the CA Device in O_RDWR
- mode. All other attempts to open the device in this mode will fail, and an error
- code will be returned.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open(const char &#x22C6;deviceName, int flags);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>const char
- *deviceName</para>
-</entry><entry
- align="char">
-<para>Name of specific video device.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int flags</para>
-</entry><entry
- align="char">
-<para>A bit-wise OR of the following flags:</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDONLY read-only access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDWR read/write access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_NONBLOCK open in non-blocking mode</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>(blocking mode is the default)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>Device driver not loaded/available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINTERNAL</para>
-</entry><entry
- align="char">
-<para>Internal error.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>Device or resource busy.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid argument.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="ca_fclose">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call closes a previously opened audio device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(int fd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section>
-
-<section id="CA_RESET"
-role="subsection"><title>CA_RESET</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_RESET);
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_RESET for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_GET_CAP"
-role="subsection"><title>CA_GET_CAP</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_GET_CAP,
- ca_caps_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_GET_CAP for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_caps_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_GET_SLOT_INFO"
-role="subsection"><title>CA_GET_SLOT_INFO</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_GET_SLOT_INFO,
- ca_slot_info_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_GET_SLOT_INFO for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_slot_info_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_GET_DESCR_INFO"
-role="subsection"><title>CA_GET_DESCR_INFO</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_GET_DESCR_INFO,
- ca_descr_info_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_GET_DESCR_INFO for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_descr_info_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_GET_MSG"
-role="subsection"><title>CA_GET_MSG</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_GET_MSG,
- ca_msg_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_GET_MSG for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_msg_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_SEND_MSG"
-role="subsection"><title>CA_SEND_MSG</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_SEND_MSG,
- ca_msg_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_SEND_MSG for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_msg_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_SET_DESCR"
-role="subsection"><title>CA_SET_DESCR</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_SET_DESCR,
- ca_descr_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_SET_DESCR for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_descr_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="CA_SET_PID"
-role="subsection"><title>CA_SET_PID</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = CA_SET_PID,
- ca_pid_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals CA_SET_PID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ca_pid_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-</section>
diff --git a/Documentation/DocBook/media/dvb/demux.xml b/Documentation/DocBook/media/dvb/demux.xml
deleted file mode 100644
index c8683d66f059..000000000000
--- a/Documentation/DocBook/media/dvb/demux.xml
+++ /dev/null
@@ -1,1145 +0,0 @@
-<title>DVB Demux Device</title>
-
-<para>The DVB demux device controls the filters of the DVB hardware/software. It can be
-accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
-accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application.
-</para>
-<section id="dmx_types">
-<title>Demux Data Types</title>
-
-<section id="dmx-output-t">
-<title>dmx_output_t</title>
-<programlisting>
-typedef enum
-{
- DMX_OUT_DECODER, /&#x22C6; Streaming directly to decoder. &#x22C6;/
- DMX_OUT_TAP, /&#x22C6; Output going to a memory buffer &#x22C6;/
- /&#x22C6; (to be retrieved via the read command).&#x22C6;/
- DMX_OUT_TS_TAP, /&#x22C6; Output multiplexed into a new TS &#x22C6;/
- /&#x22C6; (to be retrieved by reading from the &#x22C6;/
- /&#x22C6; logical DVR device). &#x22C6;/
- DMX_OUT_TSDEMUX_TAP /&#x22C6; Like TS_TAP but retrieved from the DMX device &#x22C6;/
-} dmx_output_t;
-</programlisting>
-<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is
-called.
-</para>
-<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>,
-which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
-specified.
-</para>
-</section>
-
-<section id="dmx-input-t">
-<title>dmx_input_t</title>
-<programlisting>
-typedef enum
-{
- DMX_IN_FRONTEND, /&#x22C6; Input from a front-end device. &#x22C6;/
- DMX_IN_DVR /&#x22C6; Input from the logical DVR device. &#x22C6;/
-} dmx_input_t;
-</programlisting>
-</section>
-
-<section id="dmx-pes-type-t">
-<title>dmx_pes_type_t</title>
-<programlisting>
-typedef enum
-{
- DMX_PES_AUDIO0,
- DMX_PES_VIDEO0,
- DMX_PES_TELETEXT0,
- DMX_PES_SUBTITLE0,
- DMX_PES_PCR0,
-
- DMX_PES_AUDIO1,
- DMX_PES_VIDEO1,
- DMX_PES_TELETEXT1,
- DMX_PES_SUBTITLE1,
- DMX_PES_PCR1,
-
- DMX_PES_AUDIO2,
- DMX_PES_VIDEO2,
- DMX_PES_TELETEXT2,
- DMX_PES_SUBTITLE2,
- DMX_PES_PCR2,
-
- DMX_PES_AUDIO3,
- DMX_PES_VIDEO3,
- DMX_PES_TELETEXT3,
- DMX_PES_SUBTITLE3,
- DMX_PES_PCR3,
-
- DMX_PES_OTHER
-} dmx_pes_type_t;
-</programlisting>
-</section>
-
-<section id="dmx-filter">
-<title>struct dmx_filter</title>
- <programlisting>
- typedef struct dmx_filter
-{
- __u8 filter[DMX_FILTER_SIZE];
- __u8 mask[DMX_FILTER_SIZE];
- __u8 mode[DMX_FILTER_SIZE];
-} dmx_filter_t;
-</programlisting>
-</section>
-
-<section id="dmx-sct-filter-params">
-<title>struct dmx_sct_filter_params</title>
-<programlisting>
-struct dmx_sct_filter_params
-{
- __u16 pid;
- dmx_filter_t filter;
- __u32 timeout;
- __u32 flags;
-#define DMX_CHECK_CRC 1
-#define DMX_ONESHOT 2
-#define DMX_IMMEDIATE_START 4
-#define DMX_KERNEL_CLIENT 0x8000
-};
-</programlisting>
-</section>
-
-<section id="dmx-pes-filter-params">
-<title>struct dmx_pes_filter_params</title>
-<programlisting>
-struct dmx_pes_filter_params
-{
- __u16 pid;
- dmx_input_t input;
- dmx_output_t output;
- dmx_pes_type_t pes_type;
- __u32 flags;
-};
-</programlisting>
-</section>
-
-<section id="dmx-event">
-<title>struct dmx_event</title>
- <programlisting>
- struct dmx_event
- {
- dmx_event_t event;
- time_t timeStamp;
- union
- {
- dmx_scrambling_status_t scrambling;
- } u;
- };
-</programlisting>
-</section>
-
-<section id="dmx-stc">
-<title>struct dmx_stc</title>
-<programlisting>
-struct dmx_stc {
- unsigned int num; /&#x22C6; input : which STC? 0..N &#x22C6;/
- unsigned int base; /&#x22C6; output: divisor for stc to get 90 kHz clock &#x22C6;/
- __u64 stc; /&#x22C6; output: stc in 'base'&#x22C6;90 kHz units &#x22C6;/
-};
-</programlisting>
-</section>
-
-<section id="dmx-caps">
-<title>struct dmx_caps</title>
-<programlisting>
- typedef struct dmx_caps {
- __u32 caps;
- int num_decoders;
-} dmx_caps_t;
-</programlisting>
-</section>
-
-<section id="dmx-source-t">
-<title>enum dmx_source_t</title>
-<programlisting>
-typedef enum {
- DMX_SOURCE_FRONT0 = 0,
- DMX_SOURCE_FRONT1,
- DMX_SOURCE_FRONT2,
- DMX_SOURCE_FRONT3,
- DMX_SOURCE_DVR0 = 16,
- DMX_SOURCE_DVR1,
- DMX_SOURCE_DVR2,
- DMX_SOURCE_DVR3
-} dmx_source_t;
-</programlisting>
-</section>
-
-</section>
-<section id="dmx_fcalls">
-<title>Demux Function Calls</title>
-
-<section id="dmx_fopen">
-<title>open()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call, used with a device name of /dev/dvb/adapter0/demux0,
- allocates a new filter and returns a handle which can be used for subsequent
- control of that filter. This call has to be made for each filter to be used, i.e. every
- returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0
- is a logical device to be used for retrieving Transport Streams for digital
- video recording. When reading from this device a transport stream containing
- the packets from all PES filters set in the corresponding demux device
- (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
- recorded Transport Stream is replayed by writing to this device. </para>
-<para>The significance of blocking or non-blocking mode is described in the
- documentation for functions where there is a difference. It does not affect the
- semantics of the open() call itself. A device opened in blocking mode can later
- be put into non-blocking mode (and vice versa) using the F_SETFL command
- of the fcntl system call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open(const char &#x22C6;deviceName, int flags);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>const char
- *deviceName</para>
-</entry><entry
- align="char">
-<para>Name of demux device.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int flags</para>
-</entry><entry
- align="char">
-<para>A bit-wise OR of the following flags:</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDWR read/write access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_NONBLOCK open in non-blocking mode</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>(blocking mode is the default)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>Device driver not loaded/available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid argument.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EMFILE</para>
-</entry><entry
- align="char">
-<para>&#8220;Too many open files&#8221;, i.e. no more filters available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ENOMEM</para>
-</entry><entry
- align="char">
-<para>The driver failed to allocate enough memory.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="dmx_fclose">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call deactivates and deallocates a filter that was previously
- allocated via the open() call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(int fd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="dmx_fread">
-<title>read()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call returns filtered data, which might be section or PES data. The
- filtered data is transferred from the driver&#8217;s internal circular buffer to buf. The
- maximum amount of data to be transferred is implied by count.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>When returning section data the driver always tries to return a complete single
- section (even though buf would provide buffer space for more data). If the size
- of the buffer is smaller than the section as much as possible will be returned,
- and the remaining data will be provided in subsequent calls.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
- sized sections) by default. The size of this buffer may be changed by using the
- DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if
- the read operations are not performed fast enough, this may result in a buffer
- overflow error. In this case EOVERFLOW will be returned, and the circular
- buffer will be emptied. This call is blocking if there is no data to return, i.e. the
- process will be put to sleep waiting for data, unless the O_NONBLOCK flag
- is specified.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>Note that in order to be able to read, the filtering process has to be started
- by defining either a section or a PES filter by means of the ioctl functions,
- and then starting the filtering process via the DMX_START ioctl function
- or by setting the DMX_IMMEDIATE_START flag. If the reading is done
- from a logical DVR demux device, the data will constitute a Transport Stream
- including the packets from all PES filters in the corresponding demux device
- /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>size_t read(int fd, void &#x22C6;buf, size_t count);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>void *buf</para>
-</entry><entry
- align="char">
-<para>Pointer to the buffer to be used for returned filtered data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t count</para>
-</entry><entry
- align="char">
-<para>Size of buf.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EWOULDBLOCK</para>
-</entry><entry
- align="char">
-<para>No data to return and O_NONBLOCK was specified.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ECRC</para>
-</entry><entry
- align="char">
-<para>Last section had a CRC error - no data returned. The
- buffer is flushed.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EOVERFLOW</para>
-</entry><entry
- align="char">
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>The filtered data was not read from the buffer in due
- time, resulting in non-read data being lost. The buffer is
- flushed.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ETIMEDOUT</para>
-</entry><entry
- align="char">
-<para>The section was not loaded within the stated timeout
- period. See ioctl DMX_SET_FILTER for how to set a
- timeout.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EFAULT</para>
-</entry><entry
- align="char">
-<para>The driver failed to write to the callers buffer due to an
- invalid *buf pointer.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="dmx_fwrite">
-<title>write()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0,
- associated with the physical demux device that provides the actual DVR
- functionality. It is used for replay of a digitally recorded Transport Stream.
- Matching filters have to be defined in the corresponding physical demux
- device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is
- implied by count.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>ssize_t write(int fd, const void &#x22C6;buf, size_t
- count);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>void *buf</para>
-</entry><entry
- align="char">
-<para>Pointer to the buffer containing the Transport Stream.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t count</para>
-</entry><entry
- align="char">
-<para>Size of buf.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EWOULDBLOCK</para>
-</entry><entry
- align="char">
-<para>No data was written. This
- might happen if O_NONBLOCK was specified and there
- is no more buffer space available (if O_NONBLOCK is
- not specified the function will block until buffer space is
- available).</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>This error code indicates that there are conflicting
- requests. The corresponding demux device is setup to
- receive data from the front- end. Make sure that these
- filters are stopped and that the filters with input set to
- DMX_IN_DVR are started.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="DMX_START">
-<title>DMX_START</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call is used to start the actual filtering operation defined via the ioctl
- calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request = DMX_START);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_START for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid argument, i.e. no filtering parameters provided via
- the DMX_SET_FILTER or DMX_SET_PES_FILTER
- functions.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>This error code indicates that there are conflicting
- requests. There are active filters filtering data from
- another input source. Make sure that these filters are
- stopped before starting this filter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="DMX_STOP">
-<title>DMX_STOP</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call is used to stop the actual filtering operation defined via the
- ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
- the DMX_START command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request = DMX_STOP);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_STOP for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_SET_FILTER">
-<title>DMX_SET_FILTER</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call sets up a filter according to the filter and mask parameters
- provided. A timeout may be defined stating number of seconds to wait for a
- section to be loaded. A value of 0 means that no timeout should be applied.
- Finally there is a flag field where it is possible to state whether a section should
- be CRC-checked, whether the filter should be a &#8221;one-shot&#8221; filter, i.e. if the
- filtering operation should be stopped after the first section is received, and
- whether the filtering operation should be started immediately (without waiting
- for a DMX_START ioctl call). If a filter was previously set-up, this filter will
- be canceled, and the receive buffer will be flushed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request = DMX_SET_FILTER,
- struct dmx_sct_filter_params &#x22C6;params);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_SET_FILTER for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dmx_sct_filter_params
- *params</para>
-</entry><entry
- align="char">
-<para>Pointer to structure containing filter parameters.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_SET_PES_FILTER">
-<title>DMX_SET_PES_FILTER</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call sets up a PES filter according to the parameters provided. By a
- PES filter is meant a filter that is based just on the packet identifier (PID), i.e.
- no PES header or payload filtering capability is supported.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The transport stream destination for the filtered output may be set. Also the
- PES type may be stated in order to be able to e.g. direct a video stream directly
- to the video decoder. Finally there is a flag field where it is possible to state
- whether the filtering operation should be started immediately (without waiting
- for a DMX_START ioctl call). If a filter was previously set-up, this filter will
- be cancelled, and the receive buffer will be flushed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER,
- struct dmx_pes_filter_params &#x22C6;params);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_SET_PES_FILTER for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dmx_pes_filter_params
- *params</para>
-</entry><entry
- align="char">
-<para>Pointer to structure containing filter parameters.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>This error code indicates that there are conflicting
- requests. There are active filters filtering data from
- another input source. Make sure that these filters are
- stopped before starting this filter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="DMX_SET_BUFFER_SIZE">
-<title>DMX_SET_BUFFER_SIZE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call is used to set the size of the circular buffer used for filtered data.
- The default size is two maximum sized sections, i.e. if this function is not called
- a buffer size of 2 * 4096 bytes will be used.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request =
- DMX_SET_BUFFER_SIZE, unsigned long size);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_SET_BUFFER_SIZE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>unsigned long size</para>
-</entry><entry
- align="char">
-<para>Size of circular buffer.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_GET_EVENT">
-<title>DMX_GET_EVENT</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns an event if available. If an event is not available,
- the behavior depends on whether the device is in blocking or non-blocking
- mode. In the latter case, the call fails immediately with errno set to
- EWOULDBLOCK. In the former case, the call blocks until an event becomes
- available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The standard Linux poll() and/or select() system calls can be used with the
- device file descriptor to watch for new events. For select(), the file descriptor
- should be included in the exceptfds argument, and for poll(), POLLPRI should
- be specified as the wake-up condition. Only the latest event for each filter is
- saved.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request = DMX_GET_EVENT,
- struct dmx_event &#x22C6;ev);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_GET_EVENT for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct dmx_event *ev</para>
-</entry><entry
- align="char">
-<para>Pointer to the location where the event is to be stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EWOULDBLOCK</para>
-</entry><entry
- align="char">
-<para>There is no event pending, and the device is in
- non-blocking mode.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="DMX_GET_STC">
-<title>DMX_GET_STC</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns the current value of the system time counter (which is driven
- by a PES filter of type DMX_PES_PCR). Some hardware supports more than one
- STC, so you must specify which one by setting the num field of stc before the ioctl
- (range 0...n). The result is returned in form of a ratio with a 64 bit numerator
- and a 32 bit denominator, so the real 90kHz STC value is stc-&#x003E;stc /
- stc-&#x003E;base
- .</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request = DMX_GET_STC, struct
- dmx_stc &#x22C6;stc);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_GET_STC for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct dmx_stc *stc</para>
-</entry><entry
- align="char">
-<para>Pointer to the location where the stc is to be stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid stc number.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section>
-
-<section id="DMX_GET_PES_PIDS"
-role="subsection"><title>DMX_GET_PES_PIDS</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = DMX_GET_PES_PIDS,
- __u16[5]);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_GET_PES_PIDS for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16[5]
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_GET_CAPS"
-role="subsection"><title>DMX_GET_CAPS</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = DMX_GET_CAPS,
- dmx_caps_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_GET_CAPS for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_caps_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_SET_SOURCE"
-role="subsection"><title>DMX_SET_SOURCE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = DMX_SET_SOURCE,
- dmx_source_t *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_SET_SOURCE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_source_t *
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_ADD_PID"
-role="subsection"><title>DMX_ADD_PID</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call allows to add multiple PIDs to a transport stream filter
-previously set up with DMX_SET_PES_FILTER and output equal to DMX_OUT_TSDEMUX_TAP.
-</para></entry></row><row><entry align="char"><para>
-It is used by readers of /dev/dvb/adapterX/demuxY.
-</para></entry></row><row><entry align="char"><para>
-It may be called at any time, i.e. before or after the first filter on the
-shared file descriptor was started. It makes it possible to record multiple
-services without the need to de-multiplex or re-multiplex TS packets.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = DMX_ADD_PID,
- __u16 *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_ADD_PID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 *
-</para>
-</entry><entry
- align="char">
-<para>PID number to be filtered.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="DMX_REMOVE_PID"
-role="subsection"><title>DMX_REMOVE_PID</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call allows to remove a PID when multiple PIDs are set on a
-transport stream filter, e. g. a filter previously set up with output equal to
-DMX_OUT_TSDEMUX_TAP, created via either DMX_SET_PES_FILTER or DMX_ADD_PID.
-</para></entry></row><row><entry align="char"><para>
-It is used by readers of /dev/dvb/adapterX/demuxY.
-</para></entry></row><row><entry align="char"><para>
-It may be called at any time, i.e. before or after the first filter on the
-shared file descriptor was started. It makes it possible to record multiple
-services without the need to de-multiplex or re-multiplex TS packets.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = DMX_REMOVE_PID,
- __u16 *);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals DMX_REMOVE_PID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 *
-</para>
-</entry><entry
- align="char">
-<para>PID of the PES filter to be removed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-
-</section>
diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
deleted file mode 100644
index 4c15396c67e5..000000000000
--- a/Documentation/DocBook/media/dvb/dvbapi.xml
+++ /dev/null
@@ -1,141 +0,0 @@
-<partinfo>
-<authorgroup>
-<author>
-<firstname>Ralph</firstname>
-<surname>Metzler</surname>
-<othername role="mi">J. K.</othername>
-<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
-</author>
-<author>
-<firstname>Marcus</firstname>
-<surname>Metzler</surname>
-<othername role="mi">O. C.</othername>
-<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
-</author>
-</authorgroup>
-<authorgroup>
-<author>
-<firstname>Mauro</firstname>
-<othername role="mi">Carvalho</othername>
-<surname>Chehab</surname>
-<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
-<contrib>Ported document to Docbook XML.</contrib>
-</author>
-</authorgroup>
-<copyright>
- <year>2002</year>
- <year>2003</year>
- <holder>Convergence GmbH</holder>
-</copyright>
-<copyright>
- <year>2009-2014</year>
- <holder>Mauro Carvalho Chehab</holder>
-</copyright>
-
-<revhistory>
-<!-- Put document revisions here, newest first. -->
-<revision>
- <revnumber>2.0.4</revnumber>
- <date>2011-05-06</date>
- <authorinitials>mcc</authorinitials>
- <revremark>
- Add more information about DVB APIv5, better describing the frontend GET/SET props ioctl's.
- </revremark>
-</revision>
-<revision>
- <revnumber>2.0.3</revnumber>
- <date>2010-07-03</date>
- <authorinitials>mcc</authorinitials>
- <revremark>
- Add some frontend capabilities flags, present on kernel, but missing at the specs.
- </revremark>
-</revision>
-<revision>
- <revnumber>2.0.2</revnumber>
- <date>2009-10-25</date>
- <authorinitials>mcc</authorinitials>
- <revremark>
- documents FE_SET_FRONTEND_TUNE_MODE and FE_DISHETWORK_SEND_LEGACY_CMD ioctls.
- </revremark>
-</revision>
-<revision>
-<revnumber>2.0.1</revnumber>
-<date>2009-09-16</date>
-<authorinitials>mcc</authorinitials>
-<revremark>
-Added ISDB-T test originally written by Patrick Boettcher
-</revremark>
-</revision>
-<revision>
-<revnumber>2.0.0</revnumber>
-<date>2009-09-06</date>
-<authorinitials>mcc</authorinitials>
-<revremark>Conversion from LaTex to DocBook XML. The
- contents is the same as the original LaTex version.</revremark>
-</revision>
-<revision>
-<revnumber>1.0.0</revnumber>
-<date>2003-07-24</date>
-<authorinitials>rjkm</authorinitials>
-<revremark>Initial revision on LaTEX.</revremark>
-</revision>
-</revhistory>
-</partinfo>
-
-
-<title>LINUX DVB API</title>
-<subtitle>Version 5.10</subtitle>
-<!-- ADD THE CHAPTERS HERE -->
- <chapter id="dvb_introdution">
- &sub-intro;
- </chapter>
- <chapter id="dvb_frontend">
- &sub-frontend;
- </chapter>
- <chapter id="dvb_demux">
- &sub-demux;
- </chapter>
- <chapter id="dvb_video">
- &sub-video;
- </chapter>
- <chapter id="dvb_audio">
- &sub-audio;
- </chapter>
- <chapter id="dvb_ca">
- &sub-ca;
- </chapter>
- <chapter id="dvb_net">
- &sub-net;
- </chapter>
- <chapter id="dvb_kdapi">
- &sub-kdapi;
- </chapter>
- <chapter id="dvb_examples">
- &sub-examples;
- </chapter>
-<!-- END OF CHAPTERS -->
- <appendix id="audio_h">
- <title>DVB Audio Header File</title>
- &sub-audio-h;
- </appendix>
- <appendix id="ca_h">
- <title>DVB Conditional Access Header File</title>
- &sub-ca-h;
- </appendix>
- <appendix id="dmx_h">
- <title>DVB Demux Header File</title>
- &sub-dmx-h;
- </appendix>
- <appendix id="frontend_h">
- <title>DVB Frontend Header File</title>
- &sub-frontend-h;
- </appendix>
- <appendix id="net_h">
- <title>DVB Network Header File</title>
- &sub-net-h;
- </appendix>
- <appendix id="video_h">
- <title>DVB Video Header File</title>
- &sub-video-h;
- </appendix>
-
diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml
deleted file mode 100644
index 3018564ddfd9..000000000000
--- a/Documentation/DocBook/media/dvb/dvbproperty.xml
+++ /dev/null
@@ -1,1317 +0,0 @@
-<section id="FE_GET_SET_PROPERTY">
-<title><constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></title>
-<para>This section describes the DVB version 5 extension of the DVB-API, also
-called "S2API", as this API were added to provide support for DVB-S2. It was
-designed to be able to replace the old frontend API. Yet, the DISEQC and
-the capability ioctls weren't implemented yet via the new way.</para>
-<para>The typical usage for the <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant>
-API is to replace the ioctl's were the <link linkend="dvb-frontend-parameters">
-struct <constant>dvb_frontend_parameters</constant></link> were used.</para>
-<section id="dtv-stats">
-<title>DTV stats type</title>
-<programlisting>
-struct dtv_stats {
- __u8 scale; /* enum fecap_scale_params type */
- union {
- __u64 uvalue; /* for counters and relative scales */
- __s64 svalue; /* for 1/1000 dB measures */
- };
-} __packed;
-</programlisting>
-</section>
-<section id="dtv-fe-stats">
-<title>DTV stats type</title>
-<programlisting>
-#define MAX_DTV_STATS 4
-
-struct dtv_fe_stats {
- __u8 len;
- struct dtv_stats stat[MAX_DTV_STATS];
-} __packed;
-</programlisting>
-</section>
-
-<section id="dtv-property">
-<title>DTV property type</title>
-<programlisting>
-/* Reserved fields should be set to 0 */
-
-struct dtv_property {
- __u32 cmd;
- __u32 reserved[3];
- union {
- __u32 data;
- struct dtv_fe_stats st;
- struct {
- __u8 data[32];
- __u32 len;
- __u32 reserved1[3];
- void *reserved2;
- } buffer;
- } u;
- int result;
-} __attribute__ ((packed));
-
-/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
-#define DTV_IOCTL_MAX_MSGS 64
-</programlisting>
-</section>
-<section id="dtv-properties">
-<title>DTV properties type</title>
-<programlisting>
-struct dtv_properties {
- __u32 num;
- struct dtv_property *props;
-};
-</programlisting>
-</section>
-
-<section id="FE_GET_PROPERTY">
-<title>FE_GET_PROPERTY</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns one or more frontend properties. This call only
- requires read-only access to the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>,
- dtv_properties &#x22C6;props);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int num</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct dtv_property *props</para>
-</entry><entry
- align="char">
-<para>Points to the location where the front-end property commands are stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row>
- <entry align="char"><para>EOPNOTSUPP</para></entry>
- <entry align="char"><para>Property type not supported.</para></entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="FE_SET_PROPERTY">
-<title>FE_SET_PROPERTY</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call sets one or more frontend properties. This call
- requires read/write access to the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
- dtv_properties &#x22C6;props);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int num</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct dtv_property *props</para>
-</entry><entry
- align="char">
-<para>Points to the location where the front-end property commands are stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row>
- <entry align="char"><para>EOPNOTSUPP</para></entry>
- <entry align="char"><para>Property type not supported.</para></entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section>
- <title>Property types</title>
-<para>
-On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
-the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to
-get/set up to 64 properties. The actual meaning of each property is described on the next sections.
-</para>
-
-<para>The available frontend property types are shown on the next section.</para>
-</section>
-
-<section id="fe_property_parameters">
- <title>Digital TV property parameters</title>
- <section id="DTV-UNDEFINED">
- <title><constant>DTV_UNDEFINED</constant></title>
- <para>Used internally. A GET/SET operation for it won't change or return anything.</para>
- </section>
- <section id="DTV-TUNE">
- <title><constant>DTV_TUNE</constant></title>
- <para>Interpret the cache of data, build either a traditional frontend tunerequest so we can pass validation in the <constant>FE_SET_FRONTEND</constant> ioctl.</para>
- </section>
- <section id="DTV-CLEAR">
- <title><constant>DTV_CLEAR</constant></title>
- <para>Reset a cache of data specific to the frontend here. This does not effect hardware.</para>
- </section>
- <section id="DTV-FREQUENCY">
- <title><constant>DTV_FREQUENCY</constant></title>
-
- <para>Central frequency of the channel.</para>
-
- <para>Notes:</para>
- <para>1)For satellital delivery systems, it is measured in kHz.
- For the other ones, it is measured in Hz.</para>
- <para>2)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
- E.g. a valid frequency could be 474143 kHz. The stepping is bound to the bandwidth of
- the channel which is 6MHz.</para>
-
- <para>3)As in ISDB-Tsb the channel consists of only one or three segments the
- frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
- central frequency of the channel is expected.</para>
- </section>
- <section id="DTV-MODULATION">
- <title><constant>DTV_MODULATION</constant></title>
-<para>Specifies the frontend modulation type for cable and satellite types. The modulation can be one of the types bellow:</para>
-<programlisting>
- typedef enum fe_modulation {
- QPSK,
- QAM_16,
- QAM_32,
- QAM_64,
- QAM_128,
- QAM_256,
- QAM_AUTO,
- VSB_8,
- VSB_16,
- PSK_8,
- APSK_16,
- APSK_32,
- DQPSK,
- QAM_4_NR,
- } fe_modulation_t;
-</programlisting>
- </section>
- <section id="DTV-BANDWIDTH-HZ">
- <title><constant>DTV_BANDWIDTH_HZ</constant></title>
-
- <para>Bandwidth for the channel, in HZ.</para>
-
- <para>Possible values:
- <constant>1712000</constant>,
- <constant>5000000</constant>,
- <constant>6000000</constant>,
- <constant>7000000</constant>,
- <constant>8000000</constant>,
- <constant>10000000</constant>.
- </para>
-
- <para>Notes:</para>
-
- <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para>
- <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para>
- <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth
- for DVB-C depends on the symbol rate</para>
- <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
- other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
- DTV_ISDBT_SB_SEGMENT_COUNT).</para>
- <para>5) DVB-T supports 6, 7 and 8MHz.</para>
- <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para>
- </section>
- <section id="DTV-INVERSION">
- <title><constant>DTV_INVERSION</constant></title>
- <para>The Inversion field can take one of these values:
- </para>
- <programlisting>
- typedef enum fe_spectral_inversion {
- INVERSION_OFF,
- INVERSION_ON,
- INVERSION_AUTO
- } fe_spectral_inversion_t;
- </programlisting>
- <para>It indicates if spectral inversion should be presumed or not. In the automatic setting
- (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
- itself.
- </para>
- </section>
- <section id="DTV-DISEQC-MASTER">
- <title><constant>DTV_DISEQC_MASTER</constant></title>
- <para>Currently not implemented.</para>
- </section>
- <section id="DTV-SYMBOL-RATE">
- <title><constant>DTV_SYMBOL_RATE</constant></title>
- <para>Digital TV symbol rate, in bauds (symbols/second). Used on cable standards.</para>
- </section>
- <section id="DTV-INNER-FEC">
- <title><constant>DTV_INNER_FEC</constant></title>
- <para>Used cable/satellite transmissions. The acceptable values are:
- </para>
- <programlisting>
-typedef enum fe_code_rate {
- FEC_NONE = 0,
- FEC_1_2,
- FEC_2_3,
- FEC_3_4,
- FEC_4_5,
- FEC_5_6,
- FEC_6_7,
- FEC_7_8,
- FEC_8_9,
- FEC_AUTO,
- FEC_3_5,
- FEC_9_10,
- FEC_2_5,
-} fe_code_rate_t;
- </programlisting>
- <para>which correspond to error correction rates of 1/2, 2/3, etc.,
- no error correction or auto detection.</para>
- </section>
- <section id="DTV-VOLTAGE">
- <title><constant>DTV_VOLTAGE</constant></title>
- <para>The voltage is usually used with non-DiSEqC capable LNBs to switch
- the polarzation (horizontal/vertical). When using DiSEqC epuipment this
- voltage has to be switched consistently to the DiSEqC commands as
- described in the DiSEqC spec.</para>
- <programlisting>
- typedef enum fe_sec_voltage {
- SEC_VOLTAGE_13,
- SEC_VOLTAGE_18
- } fe_sec_voltage_t;
- </programlisting>
- </section>
- <section id="DTV-TONE">
- <title><constant>DTV_TONE</constant></title>
- <para>Currently not used.</para>
- </section>
- <section id="DTV-PILOT">
- <title><constant>DTV_PILOT</constant></title>
- <para>Sets DVB-S2 pilot</para>
- <section id="fe-pilot-t">
- <title>fe_pilot type</title>
- <programlisting>
-typedef enum fe_pilot {
- PILOT_ON,
- PILOT_OFF,
- PILOT_AUTO,
-} fe_pilot_t;
- </programlisting>
- </section>
- </section>
- <section id="DTV-ROLLOFF">
- <title><constant>DTV_ROLLOFF</constant></title>
- <para>Sets DVB-S2 rolloff</para>
-
- <section id="fe-rolloff-t">
- <title>fe_rolloff type</title>
- <programlisting>
-typedef enum fe_rolloff {
- ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
- ROLLOFF_20,
- ROLLOFF_25,
- ROLLOFF_AUTO,
-} fe_rolloff_t;
- </programlisting>
- </section>
- </section>
- <section id="DTV-DISEQC-SLAVE-REPLY">
- <title><constant>DTV_DISEQC_SLAVE_REPLY</constant></title>
- <para>Currently not implemented.</para>
- </section>
- <section id="DTV-FE-CAPABILITY-COUNT">
- <title><constant>DTV_FE_CAPABILITY_COUNT</constant></title>
- <para>Currently not implemented.</para>
- </section>
- <section id="DTV-FE-CAPABILITY">
- <title><constant>DTV_FE_CAPABILITY</constant></title>
- <para>Currently not implemented.</para>
- </section>
- <section id="DTV-DELIVERY-SYSTEM">
- <title><constant>DTV_DELIVERY_SYSTEM</constant></title>
- <para>Specifies the type of Delivery system</para>
- <section id="fe-delivery-system-t">
- <title>fe_delivery_system type</title>
- <para>Possible values: </para>
-<programlisting>
-
-typedef enum fe_delivery_system {
- SYS_UNDEFINED,
- SYS_DVBC_ANNEX_A,
- SYS_DVBC_ANNEX_B,
- SYS_DVBT,
- SYS_DSS,
- SYS_DVBS,
- SYS_DVBS2,
- SYS_DVBH,
- SYS_ISDBT,
- SYS_ISDBS,
- SYS_ISDBC,
- SYS_ATSC,
- SYS_ATSCMH,
- SYS_DTMB,
- SYS_CMMB,
- SYS_DAB,
- SYS_DVBT2,
- SYS_TURBO,
- SYS_DVBC_ANNEX_C,
-} fe_delivery_system_t;
-</programlisting>
- </section>
- </section>
- <section id="DTV-ISDBT-PARTIAL-RECEPTION">
- <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title>
-
- <para>If <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether
- the channel is in partial reception mode or not.</para>
-
- <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and
- <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para>
-
- <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'
- <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel
- is consisting of one segment and layer or three segments and two layers.</para>
-
- <para>Possible values: 0, 1, -1 (AUTO)</para>
- </section>
- <section id="DTV-ISDBT-SOUND-BROADCASTING">
- <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title>
-
- <para>This field represents whether the other DTV_ISDBT_*-parameters are
- referring to an ISDB-T and an ISDB-Tsb channel. (See also
- <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para>
-
- <para>Possible values: 0, 1, -1 (AUTO)</para>
- </section>
- <section id="DTV-ISDBT-SB-SUBCHANNEL-ID">
- <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title>
-
- <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
-
- <para>(Note of the author: This might not be the correct description of the
- <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical
- background needed to program a device)</para>
-
- <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
- set of connected ISDB-Tsb channels. In this set of channels every
- channel can be received independently. The number of connected
- ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum
- bandwidth available.</para>
-
- <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
- broadcaster has several possibilities to put those channels in the
- air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8
- segments from position 1-8 to 5-13 or anything in between.</para>
-
- <para>The underlying layer of segments are subchannels: each segment is
- consisting of several subchannels with a predefined IDs. A sub-channel
- is used to help the demodulator to synchronize on the channel.</para>
-
- <para>An ISDB-T channel is always centered over all sub-channels. As for
- the example above, in ISDB-Tsb it is no longer as simple as that.</para>
-
- <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the
- sub-channel ID of the segment to be demodulated.</para>
-
- <para>Possible values: 0 .. 41, -1 (AUTO)</para>
- </section>
- <section id="DTV-ISDBT-SB-SEGMENT-IDX">
- <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title>
- <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
- <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be
- demodulated for an ISDB-Tsb channel where several of them are
- transmitted in the connected manner.</para>
- <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para>
- <para>Note: This value cannot be determined by an automatic channel search.</para>
- </section>
- <section id="DTV-ISDBT-SB-SEGMENT-COUNT">
- <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title>
- <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
- <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb
- channels.</para>
- <para>Possible values: 1 .. 13</para>
- <para>Note: This value cannot be determined by an automatic channel search.</para>
- </section>
- <section id="isdb-hierq-layers">
- <title><constant>DTV-ISDBT-LAYER*</constant> parameters</title>
- <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
- ISDB-T hierarchical layers can be decoded simultaneously. For that
- reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.</para>
- <para>ISDB-T has 3 hierarchical layers which each can use a part of the
- available segments. The total number of segments over all layers has
- to 13 in ISDB-T.</para>
- <para>There are 3 parameter sets, for Layers A, B and C.</para>
- <section id="DTV-ISDBT-LAYER-ENABLED">
- <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title>
- <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling
- layers in the decoding process. Setting all bits of
- <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be
- demodulated. This is the default.</para>
- <para>If the channel is in the partial reception mode
- (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded
- independently of the other 12 segments. In that mode layer A has to
- have a <constant>SEGMENT_COUNT</constant> of 1.</para>
- <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb
- according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled
- accordingly.</para>
- <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para>
- <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para>
- <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para>
- <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para>
- <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para>
- </section>
- <section id="DTV-ISDBT-LAYER-FEC">
- <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title>
- <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para>
- </section>
- <section id="DTV-ISDBT-LAYER-MODULATION">
- <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title>
- <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para>
- <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant>
- and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para>
- </section>
- <section id="DTV-ISDBT-LAYER-SEGMENT-COUNT">
- <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title>
- <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para>
- <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and
- <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para>
- <informaltable id="isdbt-layer_seg-cnt-table">
- <tgroup cols="6">
- <tbody>
- <row>
- <entry>PR</entry>
- <entry>SB</entry>
- <entry>Layer A width</entry>
- <entry>Layer B width</entry>
- <entry>Layer C width</entry>
- <entry>total width</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>0</entry>
- <entry>1 .. 13</entry>
- <entry>1 .. 13</entry>
- <entry>1 .. 13</entry>
- <entry>13</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>0</entry>
- <entry>1</entry>
- <entry>1 .. 13</entry>
- <entry>1 .. 13</entry>
- <entry>13</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>1</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>1</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>1</entry>
- <entry>1</entry>
- <entry>2</entry>
- <entry>0</entry>
- <entry>13</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING">
- <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
- <para>Valid values: 0, 1, 2, 4, -1 (AUTO)</para>
- <para>when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.</para>
- <para>Note: The real time interleaving length depends on the mode (fft-size). The values
- here are referring to what can be found in the TMCC-structure, as shown in the table below.</para>
- <informaltable id="isdbt-layer-interleaving-table">
- <tgroup cols="4" align="center">
- <tbody>
- <row>
- <entry>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</entry>
- <entry>Mode 1 (2K FFT)</entry>
- <entry>Mode 2 (4K FFT)</entry>
- <entry>Mode 3 (8K FFT)</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>4</entry>
- <entry>2</entry>
- <entry>1</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>8</entry>
- <entry>4</entry>
- <entry>2</entry>
- </row>
- <row>
- <entry>4</entry>
- <entry>16</entry>
- <entry>8</entry>
- <entry>4</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="DTV-ATSCMH-FIC-VER">
- <title><constant>DTV_ATSCMH_FIC_VER</constant></title>
- <para>Version number of the FIC (Fast Information Channel) signaling data.</para>
- <para>FIC is used for relaying information to allow rapid service acquisition by the receiver.</para>
- <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para>
- </section>
- <section id="DTV-ATSCMH-PARADE-ID">
- <title><constant>DTV_ATSCMH_PARADE_ID</constant></title>
- <para>Parade identification number</para>
- <para>A parade is a collection of up to eight MH groups, conveying one or two ensembles.</para>
- <para>Possible values: 0, 1, 2, 3, ..., 126, 127</para>
- </section>
- <section id="DTV-ATSCMH-NOG">
- <title><constant>DTV_ATSCMH_NOG</constant></title>
- <para>Number of MH groups per MH subframe for a designated parade.</para>
- <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para>
- </section>
- <section id="DTV-ATSCMH-TNOG">
- <title><constant>DTV_ATSCMH_TNOG</constant></title>
- <para>Total number of MH groups including all MH groups belonging to all MH parades in one MH subframe.</para>
- <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para>
- </section>
- <section id="DTV-ATSCMH-SGN">
- <title><constant>DTV_ATSCMH_SGN</constant></title>
- <para>Start group number.</para>
- <para>Possible values: 0, 1, 2, 3, ..., 14, 15</para>
- </section>
- <section id="DTV-ATSCMH-PRC">
- <title><constant>DTV_ATSCMH_PRC</constant></title>
- <para>Parade repetition cycle.</para>
- <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para>
- </section>
- <section id="DTV-ATSCMH-RS-FRAME-MODE">
- <title><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></title>
- <para>RS frame mode.</para>
- <para>Possible values are:</para>
- <para id="atscmh-rs-frame-mode">
-<programlisting>
-typedef enum atscmh_rs_frame_mode {
- ATSCMH_RSFRAME_PRI_ONLY = 0,
- ATSCMH_RSFRAME_PRI_SEC = 1,
-} atscmh_rs_frame_mode_t;
-</programlisting>
- </para>
- </section>
- <section id="DTV-ATSCMH-RS-FRAME-ENSEMBLE">
- <title><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></title>
- <para>RS frame ensemble.</para>
- <para>Possible values are:</para>
- <para id="atscmh-rs-frame-ensemble">
-<programlisting>
-typedef enum atscmh_rs_frame_ensemble {
- ATSCMH_RSFRAME_ENS_PRI = 0,
- ATSCMH_RSFRAME_ENS_SEC = 1,
-} atscmh_rs_frame_ensemble_t;
-</programlisting>
- </para>
- </section>
- <section id="DTV-ATSCMH-RS-CODE-MODE-PRI">
- <title><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></title>
- <para>RS code mode (primary).</para>
- <para>Possible values are:</para>
- <para id="atscmh-rs-code-mode">
-<programlisting>
-typedef enum atscmh_rs_code_mode {
- ATSCMH_RSCODE_211_187 = 0,
- ATSCMH_RSCODE_223_187 = 1,
- ATSCMH_RSCODE_235_187 = 2,
-} atscmh_rs_code_mode_t;
-</programlisting>
- </para>
- </section>
- <section id="DTV-ATSCMH-RS-CODE-MODE-SEC">
- <title><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></title>
- <para>RS code mode (secondary).</para>
- <para>Possible values are:</para>
-<programlisting>
-typedef enum atscmh_rs_code_mode {
- ATSCMH_RSCODE_211_187 = 0,
- ATSCMH_RSCODE_223_187 = 1,
- ATSCMH_RSCODE_235_187 = 2,
-} atscmh_rs_code_mode_t;
-</programlisting>
- </section>
- <section id="DTV-ATSCMH-SCCC-BLOCK-MODE">
- <title><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></title>
- <para>Series Concatenated Convolutional Code Block Mode.</para>
- <para>Possible values are:</para>
- <para id="atscmh-sccc-block-mode">
-<programlisting>
-typedef enum atscmh_sccc_block_mode {
- ATSCMH_SCCC_BLK_SEP = 0,
- ATSCMH_SCCC_BLK_COMB = 1,
-} atscmh_sccc_block_mode_t;
-</programlisting>
- </para>
- </section>
- <section id="DTV-ATSCMH-SCCC-CODE-MODE-A">
- <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></title>
- <para>Series Concatenated Convolutional Code Rate.</para>
- <para>Possible values are:</para>
- <para id="atscmh-sccc-code-mode">
-<programlisting>
-typedef enum atscmh_sccc_code_mode {
- ATSCMH_SCCC_CODE_HLF = 0,
- ATSCMH_SCCC_CODE_QTR = 1,
-} atscmh_sccc_code_mode_t;
-</programlisting>
- </para>
- </section>
- <section id="DTV-ATSCMH-SCCC-CODE-MODE-B">
- <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></title>
- <para>Series Concatenated Convolutional Code Rate.</para>
- <para>Possible values are:</para>
-<programlisting>
-typedef enum atscmh_sccc_code_mode {
- ATSCMH_SCCC_CODE_HLF = 0,
- ATSCMH_SCCC_CODE_QTR = 1,
-} atscmh_sccc_code_mode_t;
-</programlisting>
- </section>
- <section id="DTV-ATSCMH-SCCC-CODE-MODE-C">
- <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></title>
- <para>Series Concatenated Convolutional Code Rate.</para>
- <para>Possible values are:</para>
-<programlisting>
-typedef enum atscmh_sccc_code_mode {
- ATSCMH_SCCC_CODE_HLF = 0,
- ATSCMH_SCCC_CODE_QTR = 1,
-} atscmh_sccc_code_mode_t;
-</programlisting>
- </section>
- <section id="DTV-ATSCMH-SCCC-CODE-MODE-D">
- <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></title>
- <para>Series Concatenated Convolutional Code Rate.</para>
- <para>Possible values are:</para>
-<programlisting>
-typedef enum atscmh_sccc_code_mode {
- ATSCMH_SCCC_CODE_HLF = 0,
- ATSCMH_SCCC_CODE_QTR = 1,
-} atscmh_sccc_code_mode_t;
-</programlisting>
- </section>
- </section>
- <section id="DTV-API-VERSION">
- <title><constant>DTV_API_VERSION</constant></title>
- <para>Returns the major/minor version of the DVB API</para>
- </section>
- <section id="DTV-CODE-RATE-HP">
- <title><constant>DTV_CODE_RATE_HP</constant></title>
- <para>Used on terrestrial transmissions. The acceptable values are:
- </para>
- <programlisting>
-typedef enum fe_code_rate {
- FEC_NONE = 0,
- FEC_1_2,
- FEC_2_3,
- FEC_3_4,
- FEC_4_5,
- FEC_5_6,
- FEC_6_7,
- FEC_7_8,
- FEC_8_9,
- FEC_AUTO,
- FEC_3_5,
- FEC_9_10,
-} fe_code_rate_t;
- </programlisting>
- </section>
- <section id="DTV-CODE-RATE-LP">
- <title><constant>DTV_CODE_RATE_LP</constant></title>
- <para>Used on terrestrial transmissions. The acceptable values are:
- </para>
- <programlisting>
-typedef enum fe_code_rate {
- FEC_NONE = 0,
- FEC_1_2,
- FEC_2_3,
- FEC_3_4,
- FEC_4_5,
- FEC_5_6,
- FEC_6_7,
- FEC_7_8,
- FEC_8_9,
- FEC_AUTO,
- FEC_3_5,
- FEC_9_10,
-} fe_code_rate_t;
- </programlisting>
- </section>
- <section id="DTV-GUARD-INTERVAL">
- <title><constant>DTV_GUARD_INTERVAL</constant></title>
-
- <para>Possible values are:</para>
-<programlisting>
-typedef enum fe_guard_interval {
- GUARD_INTERVAL_1_32,
- GUARD_INTERVAL_1_16,
- GUARD_INTERVAL_1_8,
- GUARD_INTERVAL_1_4,
- GUARD_INTERVAL_AUTO,
- GUARD_INTERVAL_1_128,
- GUARD_INTERVAL_19_128,
- GUARD_INTERVAL_19_256,
- GUARD_INTERVAL_PN420,
- GUARD_INTERVAL_PN595,
- GUARD_INTERVAL_PN945,
-} fe_guard_interval_t;
-</programlisting>
-
- <para>Notes:</para>
- <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
- try to find the correct guard interval (if capable) and will use TMCC to fill
- in the missing parameters.</para>
- <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para>
- <para>3) DTMB specifies PN420, PN595 and PN945.</para>
- </section>
- <section id="DTV-TRANSMISSION-MODE">
- <title><constant>DTV_TRANSMISSION_MODE</constant></title>
-
- <para>Specifies the number of carriers used by the standard</para>
-
- <para>Possible values are:</para>
-<programlisting>
-typedef enum fe_transmit_mode {
- TRANSMISSION_MODE_2K,
- TRANSMISSION_MODE_8K,
- TRANSMISSION_MODE_AUTO,
- TRANSMISSION_MODE_4K,
- TRANSMISSION_MODE_1K,
- TRANSMISSION_MODE_16K,
- TRANSMISSION_MODE_32K,
- TRANSMISSION_MODE_C1,
- TRANSMISSION_MODE_C3780,
-} fe_transmit_mode_t;
-</programlisting>
- <para>Notes:</para>
- <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
- 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
-
- <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
- hardware will try to find the correct FFT-size (if capable) and will
- use TMCC to fill in the missing parameters.</para>
- <para>3) DVB-T specifies 2K and 8K as valid sizes.</para>
- <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para>
- <para>5) DTMB specifies C1 and C3780.</para>
- </section>
- <section id="DTV-HIERARCHY">
- <title><constant>DTV_HIERARCHY</constant></title>
- <para>Frontend hierarchy</para>
- <programlisting>
-typedef enum fe_hierarchy {
- HIERARCHY_NONE,
- HIERARCHY_1,
- HIERARCHY_2,
- HIERARCHY_4,
- HIERARCHY_AUTO
- } fe_hierarchy_t;
- </programlisting>
- </section>
- <section id="DTV-STREAM-ID">
- <title><constant>DTV_STREAM_ID</constant></title>
- <para>DVB-S2, DVB-T2 and ISDB-S support the transmission of several
- streams on a single transport stream.
- This property enables the DVB driver to handle substream filtering,
- when supported by the hardware.
- By default, substream filtering is disabled.
- </para><para>
- For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255.
- </para><para>
- For ISDB, the valid substream id range is from 1 to 65535.
- </para><para>
- To disable it, you should use the special macro NO_STREAM_ID_FILTER.
- </para><para>
- Note: any value outside the id range also disables filtering.
- </para>
- </section>
- <section id="DTV-DVBT2-PLP-ID-LEGACY">
- <title><constant>DTV_DVBT2_PLP_ID_LEGACY</constant></title>
- <para>Obsolete, replaced with DTV_STREAM_ID.</para>
- </section>
- <section id="DTV-ENUM-DELSYS">
- <title><constant>DTV_ENUM_DELSYS</constant></title>
- <para>A Multi standard frontend needs to advertise the delivery systems provided.
- Applications need to enumerate the provided delivery systems, before using
- any other operation with the frontend. Prior to it's introduction,
- FE_GET_INFO was used to determine a frontend type. A frontend which
- provides more than a single delivery system, FE_GET_INFO doesn't help much.
- Applications which intends to use a multistandard frontend must enumerate
- the delivery systems associated with it, rather than trying to use
- FE_GET_INFO. In the case of a legacy frontend, the result is just the same
- as with FE_GET_INFO, but in a more structured format </para>
- </section>
- <section id="DTV-INTERLEAVING">
- <title><constant>DTV_INTERLEAVING</constant></title>
- <para id="fe-interleaving">Interleaving mode</para>
- <programlisting>
-enum fe_interleaving {
- INTERLEAVING_NONE,
- INTERLEAVING_AUTO,
- INTERLEAVING_240,
- INTERLEAVING_720,
-};
- </programlisting>
- </section>
- <section id="DTV-LNA">
- <title><constant>DTV_LNA</constant></title>
- <para>Low-noise amplifier.</para>
- <para>Hardware might offer controllable LNA which can be set manually
- using that parameter. Usually LNA could be found only from
- terrestrial devices if at all.</para>
- <para>Possible values: 0, 1, LNA_AUTO</para>
- <para>0, LNA off</para>
- <para>1, LNA on</para>
- <para>use the special macro LNA_AUTO to set LNA auto</para>
- </section>
-</section>
-
- <section id="frontend-stat-properties">
- <title>Frontend statistics indicators</title>
- <para>The values are returned via <constant>dtv_property.stat</constant>.
- If the property is supported, <constant>dtv_property.stat.len</constant> is bigger than zero.</para>
- <para>For most delivery systems, <constant>dtv_property.stat.len</constant>
- will be 1 if the stats is supported, and the properties will
- return a single value for each parameter.</para>
- <para>It should be noticed, however, that new OFDM delivery systems
- like ISDB can use different modulation types for each group of
- carriers. On such standards, up to 3 groups of statistics can be
- provided, and <constant>dtv_property.stat.len</constant> is updated
- to reflect the "global" metrics, plus one metric per each carrier
- group (called "layer" on ISDB).</para>
- <para>So, in order to be consistent with other delivery systems, the first
- value at <link linkend="dtv-stats"><constant>dtv_property.stat.dtv_stats</constant></link>
- array refers to the global metric. The other elements of the array
- represent each layer, starting from layer A(index 1),
- layer B (index 2) and so on.</para>
- <para>The number of filled elements are stored at <constant>dtv_property.stat.len</constant>.</para>
- <para>Each element of the <constant>dtv_property.stat.dtv_stats</constant> array consists on two elements:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><constant>svalue</constant> or <constant>uvalue</constant>, where
- <constant>svalue</constant> is for signed values of the measure (dB measures)
- and <constant>uvalue</constant> is for unsigned values (counters, relative scale)</para></listitem>
- <listitem><para><constant>scale</constant> - Scale for the value. It can be:</para>
- <itemizedlist mark='bullet' id="fecap-scale-params">
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)</para></listitem>
- <listitem><para><constant>FE_SCALE_DECIBEL</constant> - parameter is a signed value, measured in 1/1000 dB</para></listitem>
- <listitem><para><constant>FE_SCALE_RELATIVE</constant> - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.</para></listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <section id="DTV-STAT-SIGNAL-STRENGTH">
- <title><constant>DTV_STAT_SIGNAL_STRENGTH</constant></title>
- <para>Indicates the signal strength level at the analog part of the tuner or of the demod.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_DECIBEL</constant> - signal strength is in 0.0001 dBm units, power measured in miliwatts. This value is generally negative.</para></listitem>
- <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for power (actually, 0 to 65535).</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-CNR">
- <title><constant>DTV_STAT_CNR</constant></title>
- <para>Indicates the Signal to Noise ratio for the main carrier.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_DECIBEL</constant> - Signal/Noise ratio is in 0.0001 dB units.</para></listitem>
- <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for Signal/Noise (actually, 0 to 65535).</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-PRE-ERROR-BIT-COUNT">
- <title><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></title>
- <para>Measures the number of bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code).</para>
- <para>This measure is taken during the same interval as <constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant>.</para>
- <para>In order to get the BER (Bit Error Rate) measurement, it should be divided by
- <link linkend="DTV-STAT-PRE-TOTAL-BIT-COUNT"><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></link>.</para>
- <para>This measurement is monotonically increased, as the frontend gets more bit count measurements.
- The frontend may reset it when a channel/transponder is tuned.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error bits counted before the inner coding.</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-PRE-TOTAL-BIT-COUNT">
- <title><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></title>
- <para>Measures the amount of bits received before the inner code block, during the same period as
- <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link> measurement was taken.</para>
- <para>It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream,
- as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para>
- <para>This measurement is monotonically increased, as the frontend gets more bit count measurements.
- The frontend may reset it when a channel/transponder is tuned.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of bits counted while measuring
- <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link>.</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-POST-ERROR-BIT-COUNT">
- <title><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></title>
- <para>Measures the number of bit errors after the forward error correction (FEC) done by inner code block (after Viterbi, LDPC or other inner code).</para>
- <para>This measure is taken during the same interval as <constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant>.</para>
- <para>In order to get the BER (Bit Error Rate) measurement, it should be divided by
- <link linkend="DTV-STAT-POST-TOTAL-BIT-COUNT"><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></link>.</para>
- <para>This measurement is monotonically increased, as the frontend gets more bit count measurements.
- The frontend may reset it when a channel/transponder is tuned.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error bits counted after the inner coding.</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-POST-TOTAL-BIT-COUNT">
- <title><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></title>
- <para>Measures the amount of bits received after the inner coding, during the same period as
- <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link> measurement was taken.</para>
- <para>It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream,
- as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para>
- <para>This measurement is monotonically increased, as the frontend gets more bit count measurements.
- The frontend may reset it when a channel/transponder is tuned.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of bits counted while measuring
- <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link>.</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-ERROR-BLOCK-COUNT">
- <title><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></title>
- <para>Measures the number of block errors after the outer forward error correction coding (after Reed-Solomon or other outer code).</para>
- <para>This measurement is monotonically increased, as the frontend gets more bit count measurements.
- The frontend may reset it when a channel/transponder is tuned.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error blocks counted after the outer coding.</para></listitem>
- </itemizedlist>
- </section>
- <section id="DTV-STAT-TOTAL-BLOCK-COUNT">
- <title><constant>DTV-STAT_TOTAL_BLOCK_COUNT</constant></title>
- <para>Measures the total number of blocks received during the same period as
- <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link> measurement was taken.</para>
- <para>It can be used to calculate the PER indicator, by dividing
- <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link>
- by <link linkend="DTV-STAT-TOTAL-BLOCK-COUNT"><constant>DTV-STAT-TOTAL-BLOCK-COUNT</constant></link>.</para>
- <para>Possible scales for this metric are:</para>
- <itemizedlist mark='bullet'>
- <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem>
- <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of blocks counted while measuring
- <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link>.</para></listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section id="frontend-property-terrestrial-systems">
- <title>Properties used on terrestrial delivery systems</title>
- <section id="dvbt-params">
- <title>DVB-T delivery system</title>
- <para>The following parameters are valid for DVB-T:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="dvbt2-params">
- <title>DVB-T2 delivery system</title>
- <para>DVB-T2 support is currently in the early stages
- of development, so expect that this section maygrow and become
- more detailed with time.</para>
- <para>The following parameters are valid for DVB-T2:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="isdbt">
- <title>ISDB-T delivery system</title>
- <para>This ISDB-T/ISDB-Tsb API extension should reflect all information
- needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible
- that some very sophisticated devices won't need certain parameters to
- tune.</para>
- <para>The information given here should help application writers to know how
- to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para>
- <para>The details given here about ISDB-T and ISDB-Tsb are just enough to
- basically show the dependencies between the needed parameter values,
- but surely some information is left out. For more detailed information
- see the following documents:</para>
- <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial
- Television Broadcasting" and</para>
- <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial
- Television Broadcasting".</para>
- <para>In order to understand the ISDB specific parameters,
- one has to have some knowledge the channel structure in
- ISDB-T and ISDB-Tsb. I.e. it has to be known to
- the reader that an ISDB-T channel consists of 13 segments,
- that it can have up to 3 layer sharing those segments,
- and things like that.</para>
- <para>The following parameters are valid for ISDB-T:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-ENABLED"><constant>DTV_ISDBT_LAYER_ENABLED</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-PARTIAL-RECEPTION"><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-SOUND-BROADCASTING"><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-SB-SUBCHANNEL-ID"><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-IDX"><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-COUNT"><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERA_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERA_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERA_TIME_INTERLEAVING</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERB_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERB_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERB_SEGMENT_COUNT</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERB_TIME_INTERLEAVING</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERC_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERC_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERC_SEGMENT_COUNT</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERC_TIME_INTERLEAVING</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="atsc-params">
- <title>ATSC delivery system</title>
- <para>The following parameters are valid for ATSC:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="atscmh-params">
- <title>ATSC-MH delivery system</title>
- <para>The following parameters are valid for ATSC-MH:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-FIC-VER"><constant>DTV_ATSCMH_FIC_VER</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-PARADE-ID"><constant>DTV_ATSCMH_PARADE_ID</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-NOG"><constant>DTV_ATSCMH_NOG</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-TNOG"><constant>DTV_ATSCMH_TNOG</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-SGN"><constant>DTV_ATSCMH_SGN</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-PRC"><constant>DTV_ATSCMH_PRC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-MODE"><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-ENSEMBLE"><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-PRI"><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-SEC"><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-SCCC-BLOCK-MODE"><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-A"><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-B"><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-C"><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-D"><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="dtmb-params">
- <title>DTMB delivery system</title>
- <para>The following parameters are valid for DTMB:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INTERLEAVING"><constant>DTV_INTERLEAVING</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- </section>
- <section id="frontend-property-cable-systems">
- <title>Properties used on cable delivery systems</title>
- <section id="dvbc-params">
- <title>DVB-C delivery system</title>
- <para>The DVB-C Annex-A is the widely used cable standard. Transmission uses QAM modulation.</para>
- <para>The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It supports a subset of the Annex A modulation types, and a roll-off of 0.13, instead of 0.15</para>
- <para>The following parameters are valid for DVB-C Annex A/C:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="dvbc-annex-b-params">
- <title>DVB-C Annex B delivery system</title>
- <para>The DVB-C Annex-B is only used on a few Countries like the United States.</para>
- <para>The following parameters are valid for DVB-C Annex B:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- </section>
- <section id="frontend-property-satellital-systems">
- <title>Properties used on satellital delivery systems</title>
- <section id="dvbs-params">
- <title>DVB-S delivery system</title>
- <para>The following parameters are valid for DVB-S:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TONE"><constant>DTV_TONE</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- <para>Future implementations might add those two missing parameters:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-DISEQC-MASTER"><constant>DTV_DISEQC_MASTER</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DISEQC-SLAVE-REPLY"><constant>DTV_DISEQC_SLAVE_REPLY</constant></link></para></listitem>
- </itemizedlist>
- </section>
- <section id="dvbs2-params">
- <title>DVB-S2 delivery system</title>
- <para>In addition to all parameters valid for DVB-S, DVB-S2 supports the following parameters:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-PILOT"><constant>DTV_PILOT</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-ROLLOFF"><constant>DTV_ROLLOFF</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem>
- </itemizedlist>
- <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para>
- </section>
- <section id="turbo-params">
- <title>Turbo code delivery system</title>
- <para>In addition to all parameters valid for DVB-S, turbo code supports the following parameters:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
- </itemizedlist>
- </section>
- <section id="isdbs-params">
- <title>ISDB-S delivery system</title>
- <para>The following parameters are valid for ISDB-S:</para>
- <itemizedlist mark='opencircle'>
- <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem>
- <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem>
- </itemizedlist>
- </section>
- </section>
-</section>
diff --git a/Documentation/DocBook/media/dvb/dvbstb.pdf b/Documentation/DocBook/media/dvb/dvbstb.pdf
deleted file mode 100644
index 0fa75d90c3eb..000000000000
--- a/Documentation/DocBook/media/dvb/dvbstb.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/dvb/examples.xml b/Documentation/DocBook/media/dvb/examples.xml
deleted file mode 100644
index f037e568eb6e..000000000000
--- a/Documentation/DocBook/media/dvb/examples.xml
+++ /dev/null
@@ -1,365 +0,0 @@
-<title>Examples</title>
-<para>In this section we would like to present some examples for using the DVB API.
-</para>
-<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged
-with the driver distribution from <ulink url="http://linuxtv.org/hg/dvb-apps" />.
-</para>
-
-<section id="tuning">
-<title>Tuning</title>
-<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as
-the demux devices. The example is given for QPSK tuners, but can easily be adjusted for
-QAM.
-</para>
-<programlisting>
- #include &#x003C;sys/ioctl.h&#x003E;
- #include &#x003C;stdio.h&#x003E;
- #include &#x003C;stdint.h&#x003E;
- #include &#x003C;sys/types.h&#x003E;
- #include &#x003C;sys/stat.h&#x003E;
- #include &#x003C;fcntl.h&#x003E;
- #include &#x003C;time.h&#x003E;
- #include &#x003C;unistd.h&#x003E;
-
- #include &#x003C;linux/dvb/dmx.h&#x003E;
- #include &#x003C;linux/dvb/frontend.h&#x003E;
- #include &#x003C;linux/dvb/sec.h&#x003E;
- #include &#x003C;sys/poll.h&#x003E;
-
- #define DMX "/dev/dvb/adapter0/demux1"
- #define FRONT "/dev/dvb/adapter0/frontend1"
- #define SEC "/dev/dvb/adapter0/sec1"
-
- /&#x22C6; routine for checking if we have a signal and other status information&#x22C6;/
- int FEReadStatus(int fd, fe_status_t &#x22C6;stat)
- {
- int ans;
-
- if ( (ans = ioctl(fd,FE_READ_STATUS,stat) &#x003C; 0)){
- perror("FE READ STATUS: ");
- return -1;
- }
-
- if (&#x22C6;stat &amp; FE_HAS_POWER)
- printf("FE HAS POWER\n");
-
- if (&#x22C6;stat &amp; FE_HAS_SIGNAL)
- printf("FE HAS SIGNAL\n");
-
- if (&#x22C6;stat &amp; FE_SPECTRUM_INV)
- printf("SPEKTRUM INV\n");
-
- return 0;
- }
-
-
- /&#x22C6; tune qpsk &#x22C6;/
- /&#x22C6; freq: frequency of transponder &#x22C6;/
- /&#x22C6; vpid, apid, tpid: PIDs of video, audio and teletext TS packets &#x22C6;/
- /&#x22C6; diseqc: DiSEqC address of the used LNB &#x22C6;/
- /&#x22C6; pol: Polarisation &#x22C6;/
- /&#x22C6; srate: Symbol Rate &#x22C6;/
- /&#x22C6; fec. FEC &#x22C6;/
- /&#x22C6; lnb_lof1: local frequency of lower LNB band &#x22C6;/
- /&#x22C6; lnb_lof2: local frequency of upper LNB band &#x22C6;/
- /&#x22C6; lnb_slof: switch frequency of LNB &#x22C6;/
-
- int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
- int diseqc, int pol, int srate, int fec, int lnb_lof1,
- int lnb_lof2, int lnb_slof)
- {
- struct secCommand scmd;
- struct secCmdSequence scmds;
- struct dmx_pes_filter_params pesFilterParams;
- FrontendParameters frp;
- struct pollfd pfd[1];
- FrontendEvent event;
- int demux1, demux2, demux3, front;
-
- frequency = (uint32_t) freq;
- symbolrate = (uint32_t) srate;
-
- if((front = open(FRONT,O_RDWR)) &#x003C; 0){
- perror("FRONTEND DEVICE: ");
- return -1;
- }
-
- if((sec = open(SEC,O_RDWR)) &#x003C; 0){
- perror("SEC DEVICE: ");
- return -1;
- }
-
- if (demux1 &#x003C; 0){
- if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
- &#x003C; 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (demux2 &#x003C; 0){
- if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
- &#x003C; 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (demux3 &#x003C; 0){
- if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
- &#x003C; 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (freq &#x003C; lnb_slof) {
- frp.Frequency = (freq - lnb_lof1);
- scmds.continuousTone = SEC_TONE_OFF;
- } else {
- frp.Frequency = (freq - lnb_lof2);
- scmds.continuousTone = SEC_TONE_ON;
- }
- frp.Inversion = INVERSION_AUTO;
- if (pol) scmds.voltage = SEC_VOLTAGE_18;
- else scmds.voltage = SEC_VOLTAGE_13;
-
- scmd.type=0;
- scmd.u.diseqc.addr=0x10;
- scmd.u.diseqc.cmd=0x38;
- scmd.u.diseqc.numParams=1;
- scmd.u.diseqc.params[0] = 0xF0 | ((diseqc &#x22C6; 4) &amp; 0x0F) |
- (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
- (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
-
- scmds.miniCommand=SEC_MINI_NONE;
- scmds.numCommands=1;
- scmds.commands=&amp;scmd;
- if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
- perror("SEC SEND: ");
- return -1;
- }
-
- if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
- perror("SEC SEND: ");
- return -1;
- }
-
- frp.u.qpsk.SymbolRate = srate;
- frp.u.qpsk.FEC_inner = fec;
-
- if (ioctl(front, FE_SET_FRONTEND, &amp;frp) &#x003C; 0){
- perror("QPSK TUNE: ");
- return -1;
- }
-
- pfd[0].fd = front;
- pfd[0].events = POLLIN;
-
- if (poll(pfd,1,3000)){
- if (pfd[0].revents &amp; POLLIN){
- printf("Getting QPSK event\n");
- if ( ioctl(front, FE_GET_EVENT, &amp;event)
-
- == -EOVERFLOW){
- perror("qpsk get event");
- return -1;
- }
- printf("Received ");
- switch(event.type){
- case FE_UNEXPECTED_EV:
- printf("unexpected event\n");
- return -1;
- case FE_FAILURE_EV:
- printf("failure event\n");
- return -1;
-
- case FE_COMPLETION_EV:
- printf("completion event\n");
- }
- }
- }
-
-
- pesFilterParams.pid = vpid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_DECODER;
- pesFilterParams.pes_type = DMX_PES_VIDEO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
- perror("set_vpid");
- return -1;
- }
-
- pesFilterParams.pid = apid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_DECODER;
- pesFilterParams.pes_type = DMX_PES_AUDIO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
- perror("set_apid");
- return -1;
- }
-
- pesFilterParams.pid = tpid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_DECODER;
- pesFilterParams.pes_type = DMX_PES_TELETEXT;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux3, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
- perror("set_tpid");
- return -1;
- }
-
- return has_signal(fds);
- }
-
-</programlisting>
-<para>The program assumes that you are using a universal LNB and a standard DiSEqC
-switch with up to 4 addresses. Of course, you could build in some more checking if
-tuning was successful and maybe try to repeat the tuning process. Depending on the
-external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be
-necessary.
-</para>
-</section>
-
-<section id="the_dvr_device">
-<title>The DVR device</title>
-<para>The following program code shows how to use the DVR device for recording.
-</para>
-<programlisting>
- #include &#x003C;sys/ioctl.h&#x003E;
- #include &#x003C;stdio.h&#x003E;
- #include &#x003C;stdint.h&#x003E;
- #include &#x003C;sys/types.h&#x003E;
- #include &#x003C;sys/stat.h&#x003E;
- #include &#x003C;fcntl.h&#x003E;
- #include &#x003C;time.h&#x003E;
- #include &#x003C;unistd.h&#x003E;
-
- #include &#x003C;linux/dvb/dmx.h&#x003E;
- #include &#x003C;linux/dvb/video.h&#x003E;
- #include &#x003C;sys/poll.h&#x003E;
- #define DVR "/dev/dvb/adapter0/dvr1"
- #define AUDIO "/dev/dvb/adapter0/audio1"
- #define VIDEO "/dev/dvb/adapter0/video1"
-
- #define BUFFY (188&#x22C6;20)
- #define MAX_LENGTH (1024&#x22C6;1024&#x22C6;5) /&#x22C6; record 5MB &#x22C6;/
-
-
- /&#x22C6; switch the demuxes to recording, assuming the transponder is tuned &#x22C6;/
-
- /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
- /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
-
- int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
- {
- struct dmx_pes_filter_params pesFilterParams;
-
- if (demux1 &#x003C; 0){
- if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
- &#x003C; 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (demux2 &#x003C; 0){
- if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
- &#x003C; 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- pesFilterParams.pid = vpid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_TS_TAP;
- pesFilterParams.pes_type = DMX_PES_VIDEO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
- perror("DEMUX DEVICE");
- return -1;
- }
- pesFilterParams.pid = apid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_TS_TAP;
- pesFilterParams.pes_type = DMX_PES_AUDIO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
- perror("DEMUX DEVICE");
- return -1;
- }
- return 0;
- }
-
- /&#x22C6; start recording MAX_LENGTH , assuming the transponder is tuned &#x22C6;/
-
- /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
- /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
- int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
- {
- int i;
- int len;
- int written;
- uint8_t buf[BUFFY];
- uint64_t length;
- struct pollfd pfd[1];
- int dvr, dvr_out;
-
- /&#x22C6; open dvr device &#x22C6;/
- if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) &#x003C; 0){
- perror("DVR DEVICE");
- return -1;
- }
-
- /&#x22C6; switch video and audio demuxes to dvr &#x22C6;/
- printf ("Switching dvr on\n");
- i = switch_to_record(demux1, demux2, vpid, apid);
- printf("finished: ");
-
- printf("Recording %2.0f MB of test file in TS format\n",
- MAX_LENGTH/(1024.0&#x22C6;1024.0));
- length = 0;
-
- /&#x22C6; open output file &#x22C6;/
- if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
- |O_TRUNC, S_IRUSR|S_IWUSR
- |S_IRGRP|S_IWGRP|S_IROTH|
- S_IWOTH)) &#x003C; 0){
- perror("Can't open file for dvr test");
- return -1;
- }
-
- pfd[0].fd = dvr;
- pfd[0].events = POLLIN;
-
- /&#x22C6; poll for dvr data and write to file &#x22C6;/
- while (length &#x003C; MAX_LENGTH ) {
- if (poll(pfd,1,1)){
- if (pfd[0].revents &amp; POLLIN){
- len = read(dvr, buf, BUFFY);
- if (len &#x003C; 0){
- perror("recording");
- return -1;
- }
- if (len &#x003E; 0){
- written = 0;
- while (written &#x003C; len)
- written +=
- write (dvr_out,
- buf, len);
- length += len;
- printf("written %2.0f MB\r",
- length/1024./1024.);
- }
- }
- }
- }
- return 0;
- }
-
-</programlisting>
-
-</section>
diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml
deleted file mode 100644
index 8a6a6ff27af5..000000000000
--- a/Documentation/DocBook/media/dvb/frontend.xml
+++ /dev/null
@@ -1,1548 +0,0 @@
-<title>DVB Frontend API</title>
-
-<para>The DVB frontend device controls the tuner and DVB demodulator
-hardware. It can be accessed through <emphasis
-role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and
-ioctl definitions can be accessed by including <emphasis
-role="tt">linux/dvb/frontend.h</emphasis> in your application.</para>
-
-<para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C
-(cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP)
-is not yet handled by this API but a future extension is possible. For
-DVB-S the frontend device also supports satellite equipment control
-(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC)
-specification is available from
-<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para>
-
-<para>Note that the DVB API may also be used for MPEG decoder-only PCI
-cards, in which case there exists no frontend device.</para>
-
-<section id="frontend_types">
-<title>Frontend Data Types</title>
-
-<section id="fe-type-t">
-<title>Frontend type</title>
-
-<para>For historical reasons, frontend types are named by the type of modulation used in
-transmission. The fontend types are given by fe_type_t type, defined as:</para>
-
-<table pgwide="1" frame="none" id="fe-type">
-<title>Frontend types</title>
-<tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry>fe_type</entry>
- <entry>Description</entry>
- <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry id="FE_QPSK"><constant>FE_QPSK</constant></entry>
- <entry>For DVB-S standard</entry>
- <entry><constant>SYS_DVBS</constant></entry>
- </row>
- <row>
- <entry id="FE_QAM"><constant>FE_QAM</constant></entry>
- <entry>For DVB-C annex A standard</entry>
- <entry><constant>SYS_DVBC_ANNEX_A</constant></entry>
- </row>
- <row>
- <entry id="FE_OFDM"><constant>FE_OFDM</constant></entry>
- <entry>For DVB-T standard</entry>
- <entry><constant>SYS_DVBT</constant></entry>
- </row>
- <row>
- <entry id="FE_ATSC"><constant>FE_ATSC</constant></entry>
- <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry>
- <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry>
- </row>
-</tbody></tgroup></table>
-
-<para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're
-supported via the new <link linkend="FE_GET_SET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter.
-</para>
-
-<para>The usage of this field is deprecated, as it doesn't report all supported standards, and
-will provide an incomplete information for frontends that support multiple delivery systems.
-Please use <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead.</para>
-</section>
-
-<section id="fe-caps-t">
-<title>frontend capabilities</title>
-
-<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for
-a specific frontend type.</para>
-<programlisting>
- typedef enum fe_caps {
- FE_IS_STUPID = 0,
- FE_CAN_INVERSION_AUTO = 0x1,
- FE_CAN_FEC_1_2 = 0x2,
- FE_CAN_FEC_2_3 = 0x4,
- FE_CAN_FEC_3_4 = 0x8,
- FE_CAN_FEC_4_5 = 0x10,
- FE_CAN_FEC_5_6 = 0x20,
- FE_CAN_FEC_6_7 = 0x40,
- FE_CAN_FEC_7_8 = 0x80,
- FE_CAN_FEC_8_9 = 0x100,
- FE_CAN_FEC_AUTO = 0x200,
- FE_CAN_QPSK = 0x400,
- FE_CAN_QAM_16 = 0x800,
- FE_CAN_QAM_32 = 0x1000,
- FE_CAN_QAM_64 = 0x2000,
- FE_CAN_QAM_128 = 0x4000,
- FE_CAN_QAM_256 = 0x8000,
- FE_CAN_QAM_AUTO = 0x10000,
- FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
- FE_CAN_BANDWIDTH_AUTO = 0x40000,
- FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
- FE_CAN_HIERARCHY_AUTO = 0x100000,
- FE_CAN_8VSB = 0x200000,
- FE_CAN_16VSB = 0x400000,
- FE_HAS_EXTENDED_CAPS = 0x800000,
- FE_CAN_MULTISTREAM = 0x4000000,
- FE_CAN_TURBO_FEC = 0x8000000,
- FE_CAN_2G_MODULATION = 0x10000000,
- FE_NEEDS_BENDING = 0x20000000,
- FE_CAN_RECOVER = 0x40000000,
- FE_CAN_MUTE_TS = 0x80000000
- } fe_caps_t;
-</programlisting>
-</section>
-
-<section id="dvb-frontend-info">
-<title>frontend information</title>
-
-<para>Information about the frontend ca be queried with
- <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
-
-<programlisting>
- struct dvb_frontend_info {
- char name[128];
- fe_type_t type;
- uint32_t frequency_min;
- uint32_t frequency_max;
- uint32_t frequency_stepsize;
- uint32_t frequency_tolerance;
- uint32_t symbol_rate_min;
- uint32_t symbol_rate_max;
- uint32_t symbol_rate_tolerance; /&#x22C6; ppm &#x22C6;/
- uint32_t notifier_delay; /&#x22C6; ms &#x22C6;/
- fe_caps_t caps;
- };
-</programlisting>
-</section>
-
-<section id="dvb-diseqc-master-cmd">
-<title>diseqc master command</title>
-
-<para>A message sent from the frontend to DiSEqC capable equipment.</para>
-<programlisting>
- struct dvb_diseqc_master_cmd {
- uint8_t msg [6]; /&#x22C6; { framing, address, command, data[3] } &#x22C6;/
- uint8_t msg_len; /&#x22C6; valid values are 3...6 &#x22C6;/
- };
-</programlisting>
-</section>
-<section role="subsection" id="dvb-diseqc-slave-reply">
-<title>diseqc slave reply</title>
-
-<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para>
-<programlisting>
- struct dvb_diseqc_slave_reply {
- uint8_t msg [4]; /&#x22C6; { framing, data [3] } &#x22C6;/
- uint8_t msg_len; /&#x22C6; valid values are 0...4, 0 means no msg &#x22C6;/
- int timeout; /&#x22C6; return from ioctl after timeout ms with &#x22C6;/
- }; /&#x22C6; errorcode when no message was received &#x22C6;/
-</programlisting>
-</section>
-
-<section id="fe-sec-voltage-t">
-<title>diseqc slave reply</title>
-<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation
-(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched
-consistently to the DiSEqC commands as described in the DiSEqC spec.</para>
-<programlisting>
- typedef enum fe_sec_voltage {
- SEC_VOLTAGE_13,
- SEC_VOLTAGE_18
- } fe_sec_voltage_t;
-</programlisting>
-</section>
-
-<section id="fe-sec-tone-mode-t">
-<title>SEC continuous tone</title>
-
-<para>The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the
-high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to
-be switched consistently to the DiSEqC commands as described in the DiSEqC
-spec.</para>
-<programlisting>
- typedef enum fe_sec_tone_mode {
- SEC_TONE_ON,
- SEC_TONE_OFF
- } fe_sec_tone_mode_t;
-</programlisting>
-</section>
-
-<section id="fe-sec-mini-cmd-t">
-<title>SEC tone burst</title>
-
-<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select
-between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to
-be switched consistently to the DiSEqC commands as described in the DiSEqC
-spec.</para>
-<programlisting>
- typedef enum fe_sec_mini_cmd {
- SEC_MINI_A,
- SEC_MINI_B
- } fe_sec_mini_cmd_t;
-</programlisting>
-
-<para></para>
-</section>
-
-<section id="fe-status-t">
-<title>frontend status</title>
-<para>Several functions of the frontend device use the fe_status data type defined
-by</para>
-<programlisting>
-typedef enum fe_status {
- FE_HAS_SIGNAL = 0x01,
- FE_HAS_CARRIER = 0x02,
- FE_HAS_VITERBI = 0x04,
- FE_HAS_SYNC = 0x08,
- FE_HAS_LOCK = 0x10,
- FE_TIMEDOUT = 0x20,
- FE_REINIT = 0x40,
-} fe_status_t;
-</programlisting>
-<para>to indicate the current state and/or state changes of the frontend hardware:
-</para>
-
-<informaltable><tgroup cols="2"><tbody>
-<row>
-<entry align="char">FE_HAS_SIGNAL</entry>
-<entry align="char">The frontend has found something above the noise level</entry>
-</row><row>
-<entry align="char">FE_HAS_CARRIER</entry>
-<entry align="char">The frontend has found a DVB signal</entry>
-</row><row>
-<entry align="char">FE_HAS_VITERBI</entry>
-<entry align="char">The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable</entry>
-</row><row>
-<entry align="char">FE_HAS_SYNC</entry>
-<entry align="char">Synchronization bytes was found</entry>
-</row><row>
-<entry align="char">FE_HAS_LOCK</entry>
-<entry align="char">The DVB were locked and everything is working</entry>
-</row><row>
-<entry align="char">FE_TIMEDOUT</entry>
-<entry align="char">no lock within the last about 2 seconds</entry>
-</row><row>
-<entry align="char">FE_REINIT</entry>
-<entry align="char">The frontend was reinitialized, application is
-recommended to reset DiSEqC, tone and parameters</entry>
-</row>
-</tbody></tgroup></informaltable>
-
-</section>
-
-<section id="dvb-frontend-parameters">
-<title>frontend parameters</title>
-<para>The kind of parameters passed to the frontend device for tuning depend on
-the kind of hardware you are using.</para>
-<para>The struct <constant>dvb_frontend_parameters</constant> uses an
-union with specific per-system parameters. However, as newer delivery systems
-required more data, the structure size weren't enough to fit, and just
-extending its size would break the existing applications. So, those parameters
-were replaced by the usage of <link linkend="FE_GET_SET_PROPERTY">
-<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The
-new API is flexible enough to add new parameters to existing delivery systems,
-and to add newer delivery systems.</para>
-<para>So, newer applications should use <link linkend="FE_GET_SET_PROPERTY">
-<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in
-order to be able to support the newer System Delivery like DVB-S2, DVB-T2,
-DVB-C2, ISDB, etc.</para>
-<para>All kinds of parameters are combined as an union in the FrontendParameters structure:
-<programlisting>
-struct dvb_frontend_parameters {
- uint32_t frequency; /&#x22C6; (absolute) frequency in Hz for QAM/OFDM &#x22C6;/
- /&#x22C6; intermediate frequency in kHz for QPSK &#x22C6;/
- fe_spectral_inversion_t inversion;
- union {
- struct dvb_qpsk_parameters qpsk;
- struct dvb_qam_parameters qam;
- struct dvb_ofdm_parameters ofdm;
- struct dvb_vsb_parameters vsb;
- } u;
-};
-</programlisting></para>
-<para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate
-frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
-the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
-OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz.
-</para>
-
-<section id="dvb-qpsk-parameters">
-<title>QPSK parameters</title>
-<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para>
-<programlisting>
- struct dvb_qpsk_parameters {
- uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
- fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
- };
-</programlisting>
-</section>
-<section id="dvb-qam-parameters">
-<title>QAM parameters</title>
-<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</constant> structure:</para>
-<programlisting>
- struct dvb_qam_parameters {
- uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
- fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
- fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
- };
-</programlisting>
-</section>
-<section id="dvb-vsb-parameters">
-<title>VSB parameters</title>
-<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para>
-<programlisting>
-struct dvb_vsb_parameters {
- fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
-};
-</programlisting>
-</section>
-<section id="dvb-ofdm-parameters">
-<title>OFDM parameters</title>
-<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</constant> structure:</para>
-<programlisting>
- struct dvb_ofdm_parameters {
- fe_bandwidth_t bandwidth;
- fe_code_rate_t code_rate_HP; /&#x22C6; high priority stream code rate &#x22C6;/
- fe_code_rate_t code_rate_LP; /&#x22C6; low priority stream code rate &#x22C6;/
- fe_modulation_t constellation; /&#x22C6; modulation type (see above) &#x22C6;/
- fe_transmit_mode_t transmission_mode;
- fe_guard_interval_t guard_interval;
- fe_hierarchy_t hierarchy_information;
- };
-</programlisting>
-</section>
-<section id="fe-spectral-inversion-t">
-<title>frontend spectral inversion</title>
-<para>The Inversion field can take one of these values:
-</para>
-<programlisting>
-typedef enum fe_spectral_inversion {
- INVERSION_OFF,
- INVERSION_ON,
- INVERSION_AUTO
-} fe_spectral_inversion_t;
-</programlisting>
-<para>It indicates if spectral inversion should be presumed or not. In the automatic setting
-(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
-itself.
-</para>
-</section>
-<section id="fe-code-rate-t">
-<title>frontend code rate</title>
-<para>The possible values for the <constant>fec_inner</constant> field used on
-<link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and
-<link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are:
-</para>
-<programlisting>
-typedef enum fe_code_rate {
- FEC_NONE = 0,
- FEC_1_2,
- FEC_2_3,
- FEC_3_4,
- FEC_4_5,
- FEC_5_6,
- FEC_6_7,
- FEC_7_8,
- FEC_8_9,
- FEC_AUTO,
- FEC_3_5,
- FEC_9_10,
-} fe_code_rate_t;
-</programlisting>
-<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
-detection.
-</para>
-</section>
-<section id="fe-modulation-t">
-<title>frontend modulation type for QAM, OFDM and VSB</title>
-<para>For cable and terrestrial frontends, e. g. for
-<link linkend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>,
-<link linkend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and
-<link linkend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>,
-it needs to specify the quadrature modulation mode which can be one of the following:
-</para>
-<programlisting>
- typedef enum fe_modulation {
- QPSK,
- QAM_16,
- QAM_32,
- QAM_64,
- QAM_128,
- QAM_256,
- QAM_AUTO,
- VSB_8,
- VSB_16,
- PSK_8,
- APSK_16,
- APSK_32,
- DQPSK,
- } fe_modulation_t;
-</programlisting>
-</section>
-<section>
-<title>More OFDM parameters</title>
-<section id="fe-transmit-mode-t">
-<title>Number of carriers per channel</title>
-<programlisting>
-typedef enum fe_transmit_mode {
- TRANSMISSION_MODE_2K,
- TRANSMISSION_MODE_8K,
- TRANSMISSION_MODE_AUTO,
- TRANSMISSION_MODE_4K,
- TRANSMISSION_MODE_1K,
- TRANSMISSION_MODE_16K,
- TRANSMISSION_MODE_32K,
- } fe_transmit_mode_t;
-</programlisting>
-</section>
-<section id="fe-bandwidth-t">
-<title>frontend bandwidth</title>
-<programlisting>
-typedef enum fe_bandwidth {
- BANDWIDTH_8_MHZ,
- BANDWIDTH_7_MHZ,
- BANDWIDTH_6_MHZ,
- BANDWIDTH_AUTO,
- BANDWIDTH_5_MHZ,
- BANDWIDTH_10_MHZ,
- BANDWIDTH_1_712_MHZ,
-} fe_bandwidth_t;
-</programlisting>
-</section>
-<section id="fe-guard-interval-t">
-<title>frontend guard inverval</title>
-<programlisting>
-typedef enum fe_guard_interval {
- GUARD_INTERVAL_1_32,
- GUARD_INTERVAL_1_16,
- GUARD_INTERVAL_1_8,
- GUARD_INTERVAL_1_4,
- GUARD_INTERVAL_AUTO,
- GUARD_INTERVAL_1_128,
- GUARD_INTERVAL_19_128,
- GUARD_INTERVAL_19_256,
-} fe_guard_interval_t;
-</programlisting>
-</section>
-<section id="fe-hierarchy-t">
-<title>frontend hierarchy</title>
-<programlisting>
-typedef enum fe_hierarchy {
- HIERARCHY_NONE,
- HIERARCHY_1,
- HIERARCHY_2,
- HIERARCHY_4,
- HIERARCHY_AUTO
- } fe_hierarchy_t;
-</programlisting>
-</section>
-</section>
-
-</section>
-
-<section id="dvb-frontend-event">
-<title>frontend events</title>
- <programlisting>
- struct dvb_frontend_event {
- fe_status_t status;
- struct dvb_frontend_parameters parameters;
- };
-</programlisting>
- </section>
-</section>
-
-
-<section id="frontend_fcalls">
-<title>Frontend Function Calls</title>
-
-<section id="frontend_f_open">
-<title>open()</title>
-<para>DESCRIPTION</para>
-<informaltable><tgroup cols="1"><tbody><row>
-<entry align="char">
-<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
- for subsequent use. Usually the first thing to do after a successful open is to
- find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
-<para>The device can be opened in read-only mode, which only allows monitoring of
- device status and statistics, or read/write mode, which allows any kind of use
- (e.g. performing tuning operations.)
-</para>
-<para>In a system with multiple front-ends, it is usually the case that multiple devices
- cannot be open in read/write mode simultaneously. As long as a front-end
- device is opened in read/write mode, other open() calls in read/write mode will
- either fail or block, depending on whether non-blocking or blocking mode was
- specified. A front-end device opened in blocking mode can later be put into
- non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
- system call. This is a standard system call, documented in the Linux manual
- page for fcntl. When an open() call has succeeded, the device will be ready
- for use in the specified mode. This implies that the corresponding hardware is
- powered up, and that other front-ends may have been powered down to make
- that possible.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open(const char &#x22C6;deviceName, int flags);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>const char
- *deviceName</para>
-</entry><entry
- align="char">
-<para>Name of specific video device.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int flags</para>
-</entry><entry
- align="char">
-<para>A bit-wise OR of the following flags:</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDONLY read-only access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDWR read/write access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_NONBLOCK open in non-blocking mode</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>(blocking mode is the default)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>Device driver not loaded/available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINTERNAL</para>
-</entry><entry
- align="char">
-<para>Internal error.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>Device or resource busy.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid argument.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="frontend_f_close">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call closes a previously opened front-end device. After closing
- a front-end device, its corresponding hardware might be powered down
- automatically.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(int fd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="FE_READ_STATUS">
-<title>FE_READ_STATUS</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns status information about the front-end. This call only
- requires read-only access to the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>,
- fe_status_t &#x22C6;status);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_READ_STATUS">FE_READ_STATUS</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct fe_status_t
- *status</para>
-</entry><entry
- align="char">
-<para>Points to the location where the front-end status word is
- to be stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EFAULT</para>
-</entry><entry
- align="char">
-<para>status points to invalid address.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-</section>
-
-<section id="FE_READ_BER">
-<title>FE_READ_BER</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns the bit error rate for the signal currently
- received/demodulated by the front-end. For this command, read-only access to
- the device is sufficient.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_READ_BER">FE_READ_BER</link>,
- uint32_t &#x22C6;ber);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_READ_BER">FE_READ_BER</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>uint32_t *ber</para>
-</entry><entry
- align="char">
-<para>The bit error rate is stored into *ber.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_READ_SNR">
-<title>FE_READ_SNR</title>
-
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns the signal-to-noise ratio for the signal currently received
- by the front-end. For this command, read-only access to the device is sufficient.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_t
- &#x22C6;snr);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>uint16_t *snr</para>
-</entry><entry
- align="char">
-<para>The signal-to-noise ratio is stored into *snr.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_READ_SIGNAL_STRENGTH">
-<title>FE_READ_SIGNAL_STRENGTH</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns the signal strength value for the signal currently received
- by the front-end. For this command, read-only access to the device is sufficient.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request =
- <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_t &#x22C6;strength);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>uint16_t *strength</para>
-</entry><entry
- align="char">
-<para>The signal strength value is stored into *strength.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_READ_UNCORRECTED_BLOCKS">
-<title>FE_READ_UNCORRECTED_BLOCKS</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns the number of uncorrected blocks detected by the device
- driver during its lifetime. For meaningful measurements, the increment in block
- count during a specific time interval should be calculated. For this command,
- read-only access to the device is sufficient.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>Note that the counter will wrap to zero after its maximum count has been
- reached.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl( int fd, int request =
- <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t &#x22C6;ublocks);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>uint32_t *ublocks</para>
-</entry><entry
- align="char">
-<para>The total number of uncorrected blocks seen by the driver
- so far.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_SET_FRONTEND">
-<title>FE_SET_FRONTEND</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call starts a tuning operation using specified parameters. The result
- of this call will be successful if the parameters were valid and the tuning could
- be initiated. The result of the tuning operation in itself, however, will arrive
- asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and
- FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before
- the previous one was completed, the previous operation will be aborted in favor
- of the new one. This command requires read/write access to the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>,
- struct dvb_frontend_parameters &#x22C6;p);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dvb_frontend_parameters
- *p</para>
-</entry><entry
- align="char">
-<para>Points to parameters for tuning operation.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Maximum supported symbol rate reached.</para>
-</entry>
-</row></tbody></tgroup></informaltable>
-</section>
-
-<section id="FE_GET_FRONTEND">
-<title>FE_GET_FRONTEND</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call queries the currently effective frontend parameters. For this
- command, read-only access to the device is sufficient.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>,
- struct dvb_frontend_parameters &#x22C6;p);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dvb_frontend_parameters
- *p</para>
-</entry><entry
- align="char">
-<para>Points to parameters for tuning operation.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Maximum supported symbol rate reached.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-
-<section id="FE_GET_EVENT">
-<title>FE_GET_EVENT</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns a frontend event if available. If an event is not
- available, the behavior depends on whether the device is in blocking or
- non-blocking mode. In the latter case, the call fails immediately with errno
- set to EWOULDBLOCK. In the former case, the call blocks until an event
- becomes available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The standard Linux poll() and/or select() system calls can be used with the
- device file descriptor to watch for new events. For select(), the file descriptor
- should be included in the exceptfds argument, and for poll(), POLLPRI should
- be specified as the wake-up condition. Since the event queue allocated is
- rather small (room for 8 events), the queue must be serviced regularly to avoid
- overflow. If an overflow happens, the oldest event is discarded from the queue,
- and an error (EOVERFLOW) occurs the next time the queue is read. After
- reporting the error condition in this fashion, subsequent
- <link linkend="FE_GET_EVENT">FE_GET_EVENT</link>
- calls will return events from the queue as usual.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>For the sake of implementation simplicity, this command requires read/write
- access to the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = QPSK_GET_EVENT,
- struct dvb_frontend_event &#x22C6;ev);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dvb_frontend_event
- *ev</para>
-</entry><entry
- align="char">
-<para>Points to the location where the event,</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>if any, is to be stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EWOULDBLOCK</para>
-</entry><entry
- align="char">
-<para>There is no event pending, and the device is in
- non-blocking mode.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EOVERFLOW</para>
-</entry><entry
- align="char">
-<para>Overflow in event queue - one or more events were lost.</para>
-</entry>
-</row></tbody></tgroup></informaltable>
-</section>
-
-<section id="FE_GET_INFO">
-<title>FE_GET_INFO</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns information about the front-end. This call only requires
- read-only access to the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(int fd, int request = <link linkend="FE_GET_INFO">FE_GET_INFO</link>, struct
- dvb_frontend_info &#x22C6;info);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_GET_INFO">FE_GET_INFO</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dvb_frontend_info
- *info</para>
-</entry><entry
- align="char">
-<para>Points to the location where the front-end information is
- to be stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="FE_DISEQC_RESET_OVERLOAD">
-<title>FE_DISEQC_RESET_OVERLOAD</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>If the bus has been automatically powered off due to power overload, this ioctl
- call restores the power to the bus. The call requires read/write access to the
- device. This call has no effect if the device is manually powered off. Not all
- DVB adapters support this ioctl.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link>);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link> for this
- command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_DISEQC_SEND_MASTER_CMD">
-<title>FE_DISEQC_SEND_MASTER_CMD</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call is used to send a a DiSEqC command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link>, struct
- dvb_diseqc_master_cmd &#x22C6;cmd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link> for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dvb_diseqc_master_cmd
- *cmd</para>
-</entry><entry
- align="char">
-<para>Pointer to the command to be transmitted.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_DISEQC_RECV_SLAVE_REPLY">
-<title>FE_DISEQC_RECV_SLAVE_REPLY</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link>, struct
- dvb_diseqc_slave_reply &#x22C6;reply);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link> for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- dvb_diseqc_slave_reply
- *reply</para>
-</entry><entry
- align="char">
-<para>Pointer to the command to be received.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="FE_DISEQC_SEND_BURST">
-<title>FE_DISEQC_SEND_BURST</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call is used to send a 22KHz tone burst.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link>, fe_sec_mini_cmd_t burst);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>fe_sec_mini_cmd_t
- burst</para>
-</entry><entry
- align="char">
-<para>burst A or B.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_SET_TONE">
-<title>FE_SET_TONE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This call is used to set the generation of the continuous 22kHz tone. This call
- requires read/write permissions.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_SET_TONE">FE_SET_TONE</link>,
- fe_sec_tone_mode_t tone);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_SET_TONE">FE_SET_TONE</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>fe_sec_tone_mode_t
- tone</para>
-</entry><entry
- align="char">
-<para>The requested tone generation mode (on/off).</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="FE_SET_VOLTAGE">
-<title>FE_SET_VOLTAGE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This call is used to set the bus voltage. This call requires read/write
- permissions.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link>,
- fe_sec_voltage_t voltage);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>fe_sec_voltage_t
- voltage</para>
-</entry><entry
- align="char">
-<para>The requested bus voltage.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_ENABLE_HIGH_LNB_VOLTAGE">
-<title>FE_ENABLE_HIGH_LNB_VOLTAGE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate
- for long cables). This call requires read/write permissions. Not all DVB
- adapters support this ioctl.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- <link linkend="FE_ENABLE_HIGH_LNB_VOLTAGE">FE_ENABLE_HIGH_LNB_VOLTAGE</link>, int high);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int high</para>
-</entry><entry
- align="char">
-<para>The requested bus voltage.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_SET_FRONTEND_TUNE_MODE">
-<title>FE_SET_FRONTEND_TUNE_MODE</title>
-<para>DESCRIPTION</para>
-<informaltable><tgroup cols="1"><tbody><row>
-<entry align="char">
-<para>Allow setting tuner mode flags to the frontend.</para>
-</entry>
-</row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS</para>
-<informaltable><tgroup cols="1"><tbody><row>
-<entry align="char">
-<para>int ioctl(int fd, int request =
-<link linkend="FE_SET_FRONTEND_TUNE_MODE">FE_SET_FRONTEND_TUNE_MODE</link>, unsigned int flags);</para>
-</entry>
-</row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS</para>
-<informaltable><tgroup cols="2"><tbody><row>
-<entry align="char">
- <para>unsigned int flags</para>
-</entry>
-<entry align="char">
-<para>
-FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "normal" tuning behaviour. Additionally, there will be no automatic monitoring of the lock status, and hence no frontend events will be generated. If a frontend device is closed, this flag will be automatically turned off when the device is reopened read-write.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-<section id="FE_DISHNETWORK_SEND_LEGACY_CMD">
- <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title>
-<para>DESCRIPTION</para>
-<informaltable><tgroup cols="1"><tbody><row>
-<entry align="char">
-<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para>
-<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para>
-<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</para>
-</entry>
-</row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS</para>
-<informaltable><tgroup cols="1"><tbody><row>
-<entry align="char">
-<para>int ioctl(int fd, int request =
- <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para>
-</entry>
-</row></tbody></tgroup></informaltable>
-
-<para>PARAMETERS</para>
-<informaltable><tgroup cols="2"><tbody><row>
-<entry align="char">
- <para>unsigned long cmd</para>
-</entry>
-<entry align="char">
-<para>
-sends the specified raw cmd to the dish via DISEqC.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-&return-value-dvb;
-</section>
-
-</section>
-
-&sub-dvbproperty;
diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml
deleted file mode 100644
index 2048b53d19b9..000000000000
--- a/Documentation/DocBook/media/dvb/intro.xml
+++ /dev/null
@@ -1,212 +0,0 @@
-<title>Introduction</title>
-
-<section id="requisites">
-<title>What you need to know</title>
-
-<para>The reader of this document is required to have some knowledge in
-the area of digital video broadcasting (DVB) and should be familiar with
-part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
-you should know what a program/transport stream (PS/TS) is and what is
-meant by a packetized elementary stream (PES) or an I-frame.</para>
-
-<para>Various DVB standards documents are available from
-<ulink url="http://www.dvb.org" /> and/or
-<ulink url="http://www.etsi.org" />.</para>
-
-<para>It is also necessary to know how to access unix/linux devices and
-how to use ioctl calls. This also includes the knowledge of C or C++.
-</para>
-</section>
-
-<section id="history">
-<title>History</title>
-
-<para>The first API for DVB cards we used at Convergence in late 1999
-was an extension of the Video4Linux API which was primarily developed
-for frame grabber cards. As such it was not really well suited to be
-used for DVB cards and their new features like recording MPEG streams
-and filtering several section and PES data streams at the same time.
-</para>
-
-<para>In early 2000, we were approached by Nokia with a proposal for a
-new standard Linux DVB API. As a commitment to the development of
-terminals based on open standards, Nokia and Convergence made it
-available to all Linux developers and published it on
-<ulink url="http://www.linuxtv.org/" /> in September 2000.
-Convergence is the maintainer of the Linux DVB API. Together with the
-LinuxTV community (i.e. you, the reader of this document), the Linux DVB
-API will be constantly reviewed and improved. With the Linux driver for
-the Siemens/Hauppauge DVB PCI card Convergence provides a first
-implementation of the Linux DVB API.</para>
-</section>
-
-<section id="overview">
-<title>Overview</title>
-
-<figure id="stb_components">
-<title>Components of a DVB card/STB</title>
-<mediaobject>
-<imageobject>
-<imagedata fileref="dvbstb.pdf" format="PS" />
-</imageobject>
-<imageobject>
-<imagedata fileref="dvbstb.png" format="PNG" />
-</imageobject>
-</mediaobject>
-</figure>
-
-<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the
-following main hardware components: </para>
-
-<itemizedlist>
- <listitem>
-
-<para>Frontend consisting of tuner and DVB demodulator</para>
-
-<para>Here the raw signal reaches the DVB hardware from a satellite dish
-or antenna or directly from cable. The frontend down-converts and
-demodulates this signal into an MPEG transport stream (TS). In case of a
-satellite frontend, this includes a facility for satellite equipment
-control (SEC), which allows control of LNB polarization, multi feed
-switches or dish rotors.</para>
-
-</listitem>
- <listitem>
-
-<para>Conditional Access (CA) hardware like CI adapters and smartcard slots
-</para>
-
-<para>The complete TS is passed through the CA hardware. Programs to
-which the user has access (controlled by the smart card) are decoded in
-real time and re-inserted into the TS.</para>
-
-</listitem>
- <listitem>
- <para>Demultiplexer which filters the incoming DVB stream</para>
-
-<para>The demultiplexer splits the TS into its components like audio and
-video streams. Besides usually several of such audio and video streams
-it also contains data streams with information about the programs
-offered in this or other streams of the same provider.</para>
-
-</listitem>
-<listitem>
-
-<para>MPEG2 audio and video decoder</para>
-
-<para>The main targets of the demultiplexer are the MPEG2 audio and
-video decoders. After decoding they pass on the uncompressed audio and
-video to the computer screen or (through a PAL/NTSC encoder) to a TV
-set.</para>
-
-
-</listitem>
-</itemizedlist>
-
-<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
-between those components.</para>
-
-<para>On a DVB PCI card not all of these have to be present since some
-functionality can be provided by the main CPU of the PC (e.g. MPEG
-picture and sound decoding) or is not needed (e.g. for data-only uses
-like &#8220;internet over satellite&#8221;). Also not every card or STB
-provides conditional access hardware.</para>
-
-</section>
-
-<section id="dvb_devices">
-<title>Linux DVB Devices</title>
-
-<para>The Linux DVB API lets you control these hardware components
-through currently six Unix-style character devices for video, audio,
-frontend, demux, CA and IP-over-DVB networking. The video and audio
-devices control the MPEG2 decoder hardware, the frontend device the
-tuner and the DVB demodulator. The demux device gives you control over
-the PES and section filters of the hardware. If the hardware does not
-support filtering these filters can be implemented in software. Finally,
-the CA device controls all the conditional access capabilities of the
-hardware. It can depend on the individual security requirements of the
-platform, if and how many of the CA functions are made available to the
-application through this device.</para>
-
-<para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
-tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
-are called:</para>
-
-<itemizedlist>
-<listitem>
-
-<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para>
-</listitem>
-<listitem>
-<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para>
-</listitem>
-<listitem>
-<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para>
-</listitem>
- <listitem>
-
-<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para>
-</listitem>
- <listitem>
-
-<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para>
-</listitem>
- <listitem>
-
-<para><emphasis role="tt">/dev/dvb/adapterN/dvrM</emphasis>,</para>
-</listitem>
- <listitem>
-
-<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist>
-
-<para>where N enumerates the DVB PCI cards in a system starting
-from&#x00A0;0, and M enumerates the devices of each type within each
-adapter, starting from&#x00A0;0, too. We will omit the &#8220;<emphasis
-role="tt">/dev/dvb/adapterN/</emphasis>&#8221; in the further dicussion
-of these devices. The naming scheme for the devices is the same wheter
-devfs is used or not.</para>
-
-<para>More details about the data structures and function calls of all
-the devices are described in the following chapters.</para>
-
-</section>
-
-<section id="include_files">
-<title>API include files</title>
-
-<para>For each of the DVB devices a corresponding include file exists.
-The DVB API include files should be included in application sources with
-a partial path like:</para>
-
-<programlisting>
- #include &#x003C;linux/dvb/audio.h&#x003E;
-</programlisting>
-<programlisting>
- #include &#x003C;linux/dvb/ca.h&#x003E;
-</programlisting>
-<programlisting>
- #include &#x003C;linux/dvb/dmx.h&#x003E;
-</programlisting>
-<programlisting>
- #include &#x003C;linux/dvb/frontend.h&#x003E;
-</programlisting>
-<programlisting>
- #include &#x003C;linux/dvb/net.h&#x003E;
-</programlisting>
-<programlisting>
- #include &#x003C;linux/dvb/osd.h&#x003E;
-</programlisting>
-<programlisting>
- #include &#x003C;linux/dvb/video.h&#x003E;
-</programlisting>
-
-<para>To enable applications to support different API version, an
-additional include file <emphasis
-role="tt">linux/dvb/version.h</emphasis> exists, which defines the
-constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
-describes <emphasis role="tt">DVB_API_VERSION 5.8</emphasis>.
-</para>
-
-</section>
-
diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
deleted file mode 100644
index 6c11ec52cbee..000000000000
--- a/Documentation/DocBook/media/dvb/kdapi.xml
+++ /dev/null
@@ -1,2309 +0,0 @@
-<title>Kernel Demux API</title>
-<para>The kernel demux API defines a driver-internal interface for registering low-level,
-hardware specific driver to a hardware independent demux layer. It is only of interest for
-DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in
-<emphasis role="tt">drivers/media/dvb-core</emphasis>.
-</para>
-<para>Maintainer note: This section must be reviewed. It is probably out of date.
-</para>
-
-<section id="kernel_demux_data_types">
-<title>Kernel Demux Data Types</title>
-
-
-<section id="dmx_success_t">
-<title>dmx_success_t</title>
- <programlisting>
- typedef enum {
- DMX_OK = 0, /&#x22C6; Received Ok &#x22C6;/
- DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
- DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
- DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
- DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
- DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
- DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
- } dmx_success_t;
-</programlisting>
-
-</section>
-<section id="ts_filter_types">
-<title>TS filter types</title>
- <programlisting>
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; TS packet reception &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- /&#x22C6; TS filter type for set_type() &#x22C6;/
-
- #define TS_PACKET 1 /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
- #define TS_PAYLOAD_ONLY 2 /&#x22C6; in case TS_PACKET is set, only send the TS
- payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
- #define TS_DECODER 4 /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
-</programlisting>
-
-</section>
-<section id="dmx_ts_pes_t">
-<title>dmx_ts_pes_t</title>
-<para>The structure
-</para>
-<programlisting>
- typedef enum
- {
- DMX_TS_PES_AUDIO, /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
- DMX_TS_PES_VIDEO, /&#x22C6; ... &#x22C6;/
- DMX_TS_PES_TELETEXT,
- DMX_TS_PES_SUBTITLE,
- DMX_TS_PES_PCR,
- DMX_TS_PES_OTHER,
- } dmx_ts_pes_t;
-</programlisting>
-<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
-should be kept identical) to the types in the demux device.
-</para>
-<programlisting>
- struct dmx_ts_feed_s {
- int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
- struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
- __u16 pid,
- size_t callback_length,
- size_t circular_buffer_size,
- int descramble,
- struct timespec timeout);
- int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
- int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
- int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; feed,
- int type,
- dmx_ts_pes_t pes_type);
- };
-
- typedef struct dmx_ts_feed_s dmx_ts_feed_t;
-</programlisting>
- <programlisting>
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- typedef struct dmx_pes_filter_s {
- struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- } dmx_pes_filter_t;
-</programlisting>
- <programlisting>
- typedef struct dmx_pes_feed_s {
- int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
- struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
- __u16 pid,
- size_t circular_buffer_size,
- int descramble,
- struct timespec timeout);
- int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
- int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
- int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
- dmx_pes_filter_t&#x22C6;&#x22C6; filter);
- int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
- dmx_pes_filter_t&#x22C6; filter);
- } dmx_pes_feed_t;
-</programlisting>
- <programlisting>
- typedef struct {
- __u8 filter_value [DMX_MAX_FILTER_SIZE];
- __u8 filter_mask [DMX_MAX_FILTER_SIZE];
- struct dmx_section_feed_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- } dmx_section_filter_t;
-</programlisting>
- <programlisting>
- struct dmx_section_feed_s {
- int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
- struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
- __u16 pid,
- size_t circular_buffer_size,
- int descramble,
- int check_crc);
- int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
- dmx_section_filter_t&#x22C6;&#x22C6; filter);
- int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
- dmx_section_filter_t&#x22C6; filter);
- int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
- int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
- };
- typedef struct dmx_section_feed_s dmx_section_feed_t;
-
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; Callback functions &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
- size_t buffer1_length,
- __u8 &#x22C6; buffer2,
- size_t buffer2_length,
- dmx_ts_feed_t&#x22C6; source,
- dmx_success_t success);
-
- typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
- size_t buffer1_len,
- __u8 &#x22C6; buffer2,
- size_t buffer2_len,
- dmx_section_filter_t &#x22C6; source,
- dmx_success_t success);
-
- typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
- size_t buffer1_len,
- __u8 &#x22C6; buffer2,
- size_t buffer2_len,
- dmx_pes_filter_t&#x22C6; source,
- dmx_success_t success);
-
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; DVB Front-End &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- typedef enum {
- DMX_OTHER_FE = 0,
- DMX_SATELLITE_FE,
- DMX_CABLE_FE,
- DMX_TERRESTRIAL_FE,
- DMX_LVDS_FE,
- DMX_ASI_FE, /&#x22C6; DVB-ASI interface &#x22C6;/
- DMX_MEMORY_FE
- } dmx_frontend_source_t;
-
- typedef struct {
- /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
- char&#x22C6; id; /&#x22C6; Unique front-end identifier &#x22C6;/
- char&#x22C6; vendor; /&#x22C6; Name of the front-end vendor &#x22C6;/
- char&#x22C6; model; /&#x22C6; Name of the front-end model &#x22C6;/
- struct list_head connectivity_list; /&#x22C6; List of front-ends that can
- be connected to a particular
- demux &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- dmx_frontend_source_t source;
- } dmx_frontend_t;
-
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; MPEG-2 TS Demux &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- /&#x22C6;
- &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
- &#x22C6;/
-
- #define DMX_TS_FILTERING 1
- #define DMX_PES_FILTERING 2
- #define DMX_SECTION_FILTERING 4
- #define DMX_MEMORY_BASED_FILTERING 8 /&#x22C6; write() available &#x22C6;/
- #define DMX_CRC_CHECKING 16
- #define DMX_TS_DESCRAMBLING 32
- #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64
- #define DMX_MAC_ADDRESS_DESCRAMBLING 128
-</programlisting>
-
-</section>
-<section id="demux_demux_t">
-<title>demux_demux_t</title>
- <programlisting>
- /&#x22C6;
- &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
- &#x22C6; front-ends from the generic type struct list_head
- &#x22C6; to the type &#x22C6; dmx_frontend_t
- &#x22C6;.
- &#x22C6;/
-
- #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)
-
- struct dmx_demux_s {
- /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
- char&#x22C6; id; /&#x22C6; Unique demux identifier &#x22C6;/
- char&#x22C6; vendor; /&#x22C6; Name of the demux vendor &#x22C6;/
- char&#x22C6; model; /&#x22C6; Name of the demux model &#x22C6;/
- __u32 capabilities; /&#x22C6; Bitfield of capability flags &#x22C6;/
- dmx_frontend_t&#x22C6; frontend; /&#x22C6; Front-end connected to the demux &#x22C6;/
- struct list_head reg_list; /&#x22C6; List of registered demuxes &#x22C6;/
- void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- int users; /&#x22C6; Number of users &#x22C6;/
- int (&#x22C6;open) (struct dmx_demux_s&#x22C6; demux);
- int (&#x22C6;close) (struct dmx_demux_s&#x22C6; demux);
- int (&#x22C6;write) (struct dmx_demux_s&#x22C6; demux, const char&#x22C6; buf, size_t count);
- int (&#x22C6;allocate_ts_feed) (struct dmx_demux_s&#x22C6; demux,
- dmx_ts_feed_t&#x22C6;&#x22C6; feed,
- dmx_ts_cb callback);
- int (&#x22C6;release_ts_feed) (struct dmx_demux_s&#x22C6; demux,
- dmx_ts_feed_t&#x22C6; feed);
- int (&#x22C6;allocate_pes_feed) (struct dmx_demux_s&#x22C6; demux,
- dmx_pes_feed_t&#x22C6;&#x22C6; feed,
- dmx_pes_cb callback);
- int (&#x22C6;release_pes_feed) (struct dmx_demux_s&#x22C6; demux,
- dmx_pes_feed_t&#x22C6; feed);
- int (&#x22C6;allocate_section_feed) (struct dmx_demux_s&#x22C6; demux,
- dmx_section_feed_t&#x22C6;&#x22C6; feed,
- dmx_section_cb callback);
- int (&#x22C6;release_section_feed) (struct dmx_demux_s&#x22C6; demux,
- dmx_section_feed_t&#x22C6; feed);
- int (&#x22C6;descramble_mac_address) (struct dmx_demux_s&#x22C6; demux,
- __u8&#x22C6; buffer1,
- size_t buffer1_length,
- __u8&#x22C6; buffer2,
- size_t buffer2_length,
- __u16 pid);
- int (&#x22C6;descramble_section_payload) (struct dmx_demux_s&#x22C6; demux,
- __u8&#x22C6; buffer1,
- size_t buffer1_length,
- __u8&#x22C6; buffer2, size_t buffer2_length,
- __u16 pid);
- int (&#x22C6;add_frontend) (struct dmx_demux_s&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);
- int (&#x22C6;remove_frontend) (struct dmx_demux_s&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);
- struct list_head&#x22C6; (&#x22C6;get_frontends) (struct dmx_demux_s&#x22C6; demux);
- int (&#x22C6;connect_frontend) (struct dmx_demux_s&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);
- int (&#x22C6;disconnect_frontend) (struct dmx_demux_s&#x22C6; demux);
-
-
- /&#x22C6; added because js cannot keep track of these himself &#x22C6;/
- int (&#x22C6;get_pes_pids) (struct dmx_demux_s&#x22C6; demux, __u16 &#x22C6;pids);
- };
- typedef struct dmx_demux_s dmx_demux_t;
-</programlisting>
-
-</section>
-<section id="demux_directory">
-<title>Demux directory</title>
- <programlisting>
- /&#x22C6;
- &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
- &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
- &#x22C6;.
- &#x22C6;/
-
- #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
-
- int dmx_register_demux (dmx_demux_t&#x22C6; demux);
- int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
- struct list_head&#x22C6; dmx_get_demuxes (void);
-</programlisting>
- </section></section>
-<section id="demux_directory_api">
-<title>Demux Directory API</title>
-<para>The demux directory is a Linux kernel-wide facility for registering and accessing the
-MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
-is possible using this API.
-</para>
-<para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
-</para>
-
-<section
-role="subsection"><title>dmx_register_demux()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function makes a demux driver interface available to the Linux kernel. It is
- usually called by the init_module() function of the kernel module that contains
- the demux driver. The caller of this function is responsible for allocating
- dynamic or static memory for the demux structure and for initializing its fields
- before calling this function. The memory allocated for the demux structure
- must not be freed before calling dmx_unregister_demux(),</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_register_demux ( dmx_demux_t &#x22C6;demux )</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux structure.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EEXIST</para>
-</entry><entry
- align="char">
-<para>A demux with the same value of the id field already stored
- in the directory.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSPC</para>
-</entry><entry
- align="char">
-<para>No space left in the directory.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>dmx_unregister_demux()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function is called to indicate that the given demux interface is no
- longer available. The caller of this function is responsible for freeing the
- memory of the demux structure, if it was dynamically allocated before calling
- dmx_register_demux(). The cleanup_module() function of the kernel module
- that contains the demux driver should call this function. Note that this function
- fails if the demux is currently in use, i.e., release_demux() has not been called
- for the interface.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_unregister_demux ( dmx_demux_t &#x22C6;demux )</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux structure which is to be
- unregistered.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>The specified demux is not registered in the demux
- directory.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>The specified demux is currently in use.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>dmx_get_demuxes()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Provides the caller with the list of registered demux interfaces, using the
- standard list structure defined in the include file linux/list.h. The include file
- demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
- the generic type struct list_head* to the type dmx_demux_t*. The caller must
- not free the memory of any of the elements obtained via this function call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>struct list_head &#x22C6;dmx_get_demuxes ()</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>none</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>struct list_head *</para>
-</entry><entry
- align="char">
-<para>A list of demux interfaces, or NULL in the case of an
- empty list.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="demux_api">
-<title>Demux API</title>
-<para>The demux API should be implemented for each demux in the system. It is used to select
-the TS source of a demux and to manage the demux resources. When the demux
-client allocates a resource via the demux API, it receives a pointer to the API of that
-resource.
-</para>
-<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
-demux API. In a system with more than one front-end, the API can be used to select one of
-the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
-demux API only controls front-ends regarding their connections with demuxes; the APIs
-used to set the other front-end parameters, such as tuning, are not defined in this
-document.
-</para>
-<para>The functions that implement the abstract interface demux should be defined static or
-module private and registered to the Demux Directory for external access. It is not necessary
-to implement every function in the demux_t struct, however (for example, a demux interface
-might support Section filtering, but not TS or PES filtering). The API client is expected to
-check the value of any function pointer before calling the function: the value of NULL means
-&#8220;function not available&#8221;.
-</para>
-<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
-update and race condition problems should be addressed, e.g. by protecting parts of code with
-mutexes. This is especially important on multi-processor hosts.
-</para>
-<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
-kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
-swapping is needed. For example, the Linux kernel calls the functions of a network device
-interface from a bottom half context. Thus, if a demux API function is called from network
-device code, the function must not sleep.
-</para>
-
-
-<section id="kdapi_fopen">
-<title>open()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function reserves the demux for use by the caller and, if necessary,
- initializes the demux. When the demux is no longer needed, the function close()
- should be called. It should be possible for multiple clients to access the demux
- at the same time. Thus, the function implementation should increment the
- demux usage count when open() is called and decrement it when close() is
- called.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open ( demux_t&#x22C6; demux );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EUSERS</para>
-</entry><entry
- align="char">
-<para>Maximum usage count reached.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="kdapi_fclose">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function reserves the demux for use by the caller and, if necessary,
- initializes the demux. When the demux is no longer needed, the function close()
- should be called. It should be possible for multiple clients to access the demux
- at the same time. Thus, the function implementation should increment the
- demux usage count when open() is called and decrement it when close() is
- called.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(demux_t&#x22C6; demux);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENODEV</para>
-</entry><entry
- align="char">
-<para>The demux was not in use.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="kdapi_fwrite">
-<title>write()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function provides the demux driver with a memory buffer containing TS
- packets. Instead of receiving TS packets from the DVB front-end, the demux
- driver software will read packets from memory. Any clients of this demux
- with active TS, PES or Section filters will receive filtered data via the Demux
- callback API (see 0). The function returns when all the data in the buffer has
- been consumed by the demux. Demux hardware typically cannot read TS from
- memory. If this is the case, memory-based filtering has to be implemented
- entirely in software.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int write(demux_t&#x22C6; demux, const char&#x22C6; buf, size_t
- count);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>const char* buf</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS data in kernel-space memory.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t length</para>
-</entry><entry
- align="char">
-<para>Length of the TS data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>The command is not implemented.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>allocate_ts_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Allocates a new TS feed, which is used to filter the TS packets carrying a
- certain PID. The TS feed normally corresponds to a hardware PID filter on the
- demux chip.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int allocate_ts_feed(dmx_demux_t&#x22C6; demux,
- dmx_ts_feed_t&#x22C6;&#x22C6; feed, dmx_ts_cb callback);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_feed_t**
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_cb callback</para>
-</entry><entry
- align="char">
-<para>Pointer to the callback function for passing received TS
- packet</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>No more TS feeds available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>The command is not implemented.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>release_ts_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in
- progress on the TS feed should be stopped before calling this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int release_ts_feed(dmx_demux_t&#x22C6; demux,
- dmx_ts_feed_t&#x22C6; feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>allocate_section_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving
- sections. On platforms with hardware support for section filtering, a section
- feed is directly mapped to the demux HW. On other platforms, TS packets are
- first PID filtered in hardware and a hardware section filter then emulated in
- software. The caller obtains an API pointer of type dmx_section_feed_t as an
- out parameter. Using this API the caller can set filtering parameters and start
- receiving sections.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int allocate_section_feed(dmx_demux_t&#x22C6; demux,
- dmx_section_feed_t &#x22C6;&#x22C6;feed, dmx_section_cb callback);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_feed_t
- **feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_cb
- callback</para>
-</entry><entry
- align="char">
-<para>Pointer to the callback function for passing received
- sections.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>No more section feeds available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>The command is not implemented.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>release_section_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Releases the resources allocated with allocate_section_feed(), including
- allocated filters. Any filtering in progress on the section feed should be stopped
- before calling this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int release_section_feed(dmx_demux_t&#x22C6; demux,
- dmx_section_feed_t &#x22C6;feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_feed_t
- *feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>descramble_mac_address()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function runs a descrambling algorithm on the destination MAC
- address field of a DVB Datagram Section, replacing the original address
- with its un-encrypted version. Otherwise, the description on the function
- descramble_section_payload() applies also to this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int descramble_mac_address(dmx_demux_t&#x22C6; demux, __u8
- &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
- size_t buffer2_length, __u16 pid);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t
- *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8 *buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the first byte of the section.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer1.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8* buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the section data, or NULL. The
- pointer has a non-NULL value if the section wraps past
- the end of a circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer2.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>The PID on which the section was received. Useful
- for obtaining the descrambling key, e.g. from a DVB
- Common Access facility.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>descramble_section_payload()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function runs a descrambling algorithm on the payload of a DVB
- Datagram Section, replacing the original payload with its un-encrypted
- version. The function will be called from the demux API implementation;
- the API client need not call this function directly. Section-level scrambling
- algorithms are currently standardized only for DVB-RCC (return channel
- over 2-directional cable TV network) systems. For all other DVB networks,
- encryption schemes are likely to be proprietary to each data broadcaster. Thus,
- it is expected that this function pointer will have the value of NULL (i.e.,
- function not available) in most demux API implementations. Nevertheless, it
- should be possible to use the function pointer as a hook for dynamically adding
- a &#8220;plug-in&#8221; descrambling facility to a demux driver.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>While this function is not needed with hardware-based section descrambling,
- the descramble_section_payload function pointer can be used to override the
- default hardware-based descrambling algorithm: if the function pointer has a
- non-NULL value, the corresponding function should be used instead of any
- descrambling hardware.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int descramble_section_payload(dmx_demux_t&#x22C6; demux,
- __u8 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
- size_t buffer2_length, __u16 pid);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t
- *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8 *buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the first byte of the section.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer1.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8 *buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the section data, or NULL. The
- pointer has a non-NULL value if the section wraps past
- the end of a circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer2.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>The PID on which the section was received. Useful
- for obtaining the descrambling key, e.g. from a DVB
- Common Access facility.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>add_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Registers a connectivity between a demux and a front-end, i.e., indicates that
- the demux can be connected via a call to connect_frontend() to use the given
- front-end as a TS source. The client of this function has to allocate dynamic or
- static memory for the frontend structure and initialize its fields before calling
- this function. This function is normally called during the driver initialization.
- The caller must not free the memory of the frontend struct before successfully
- calling remove_frontend().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int add_frontend(dmx_demux_t &#x22C6;demux, dmx_frontend_t
- &#x22C6;frontend);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_frontend_t*
- frontend</para>
-</entry><entry
- align="char">
-<para>Pointer to the front-end instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EEXIST</para>
-</entry><entry
- align="char">
-<para>A front-end with the same value of the id field already
- registered.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINUSE</para>
-</entry><entry
- align="char">
-<para>The demux is in use.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOMEM</para>
-</entry><entry
- align="char">
-<para>No more front-ends can be added.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>remove_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Indicates that the given front-end, registered by a call to add_frontend(), can
- no longer be connected as a TS source by this demux. The function should be
- called when a front-end driver or a demux driver is removed from the system.
- If the front-end is in use, the function fails with the return value of -EBUSY.
- After successfully calling this function, the caller can free the memory of
- the frontend struct if it was dynamically allocated before the add_frontend()
- operation.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int remove_frontend(dmx_demux_t&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_frontend_t*
- frontend</para>
-</entry><entry
- align="char">
-<para>Pointer to the front-end instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>The front-end is in use, i.e. a call to connect_frontend()
- has not been followed by a call to disconnect_frontend().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>get_frontends()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Provides the APIs of the front-ends that have been registered for this demux.
- Any of the front-ends obtained with this call can be used as a parameter for
- connect_frontend().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The include file demux.h contains the macro DMX_FE_ENTRY() for
- converting an element of the generic type struct list_head* to the type
- dmx_frontend_t*. The caller must not free the memory of any of the elements
- obtained via this function call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>struct list_head&#x22C6; get_frontends(dmx_demux_t&#x22C6; demux);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*</para>
-</entry><entry
- align="char">
-<para>A list of front-end interfaces, or NULL in the case of an
- empty list.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>connect_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Connects the TS output of the front-end to the input of the demux. A demux
- can only be connected to a front-end registered to the demux with the function
- add_frontend().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>It may or may not be possible to connect multiple demuxes to the same
- front-end, depending on the capabilities of the HW platform. When not used,
- the front-end should be released by calling disconnect_frontend().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int connect_frontend(dmx_demux_t&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_frontend_t*
- frontend</para>
-</entry><entry
- align="char">
-<para>Pointer to the front-end instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>The front-end is in use.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>disconnect_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Disconnects the demux and a front-end previously connected by a
- connect_frontend() call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int disconnect_frontend(dmx_demux_t&#x22C6; demux);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="demux_callback_api">
-<title>Demux Callback API</title>
-<para>This kernel-space API comprises the callback functions that deliver filtered data to the
-demux client. Unlike the other APIs, these API functions are provided by the client and called
-from the demux code.
-</para>
-<para>The function pointers of this abstract interface are not packed into a structure as in the
-other demux APIs, because the callback functions are registered and used independent
-of each other. As an example, it is possible for the API client to provide several
-callback functions for receiving TS packets and no callbacks for PES packets or
-sections.
-</para>
-<para>The functions that implement the callback API need not be re-entrant: when a demux
-driver calls one of these functions, the driver is not allowed to call the function again before
-the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
-to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
-function call directly from a hardware interrupt.
-</para>
-
-<section
-role="subsection"><title>dmx_ts_cb()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function, provided by the client of the demux API, is called from the
- demux code. The function is only called when filtering on this TS feed has
- been enabled using the start_filtering() function.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>Any TS packets that match the filter settings are copied to a circular buffer. The
- filtered TS packets are delivered to the client using this callback function. The
- size of the circular buffer is controlled by the circular_buffer_size parameter
- of the set() function in the TS Feed API. It is expected that the buffer1 and
- buffer2 callback parameters point to addresses within the circular buffer, but
- other implementations are also possible. Note that the called party should not
- try to free the memory the buffer1 and buffer2 parameters point to.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>When this function is called, the buffer1 parameter typically points to the
- start of the first undelivered TS packet within a circular buffer. The buffer2
- buffer parameter is normally NULL, except when the received TS packets have
- crossed the last address of the circular buffer and &#8221;wrapped&#8221; to the beginning
- of the buffer. In the latter case the buffer1 parameter would contain an address
- within the circular buffer, while the buffer2 parameter would contain the first
- address of the circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The number of bytes delivered with this function (i.e. buffer1_length +
- buffer2_length) is usually equal to the value of callback_length parameter
- given in the set() function, with one exception: if a timeout occurs before
- receiving callback_length bytes of TS data, any undelivered packets are
- immediately delivered to the client by calling this function. The timeout
- duration is controlled by the set() function in the TS Feed API.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>If a TS packet is received with errors that could not be fixed by the TS-level
- forward error correction (FEC), the Transport_error_indicator flag of the TS
- packet header should be set. The TS packet should not be discarded, as
- the error can possibly be corrected by a higher layer protocol. If the called
- party is slow in processing the callback, it is possible that the circular buffer
- eventually fills up. If this happens, the demux driver should discard any TS
- packets received while the buffer is full. The error should be indicated to the
- client on the next callback by setting the success parameter to the value of
- DMX_OVERRUN_ERROR.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The type of data returned to the callback can be selected by the new
- function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
- pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
- include file ost/demux.h) The type parameter decides if the raw TS packet
- (TS_PACKET) or just the payload (TS_PACKET&#8212;TS_PAYLOAD_ONLY)
- should be returned. If additionally the TS_DECODER bit is set the stream
- will also be sent to the hardware MPEG decoder. In this case, the second
- flag decides as what kind of data the stream should be interpreted. The
- possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
- DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
- DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
- __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
- source, dmx_success_t success);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>__u8* buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the start of the filtered TS packets.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the TS data in buffer1.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8* buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the filtered TS packets, or NULL.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the TS data in buffer2.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_feed_t*
- source</para>
-</entry><entry
- align="char">
-<para>Indicates which TS feed is the source of the callback.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_success_t
- success</para>
-</entry><entry
- align="char">
-<para>Indicates if there was an error in TS reception.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>Continue filtering.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-1</para>
-</entry><entry
- align="char">
-<para>Stop filtering - has the same effect as a call to
- stop_filtering() on the TS Feed API.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>dmx_section_cb()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function, provided by the client of the demux API, is called from the
- demux code. The function is only called when filtering of sections has been
- enabled using the function start_filtering() of the section feed API. When the
- demux driver has received a complete section that matches at least one section
- filter, the client is notified via this callback function. Normally this function is
- called for each received section; however, it is also possible to deliver multiple
- sections with one callback, for example when the system load is high. If an
- error occurs while receiving a section, this function should be called with
- the corresponding error type set in the success field, whether or not there is
- data to deliver. The Section Feed implementation should maintain a circular
- buffer for received sections. However, this is not necessary if the Section Feed
- API is implemented as a client of the TS Feed API, because the TS Feed
- implementation then buffers the received data. The size of the circular buffer
- can be configured using the set() function in the Section Feed API. If there
- is no room in the circular buffer when a new section is received, the section
- must be discarded. If this happens, the value of the success parameter should
- be DMX_OVERRUN_ERROR on the next callback.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
- buffer1_length, __u8&#x22C6; buffer2, size_t
- buffer2_length, dmx_section_filter_t&#x22C6; source,
- dmx_success_t success);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>__u8* buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the start of the filtered section, e.g. within the
- circular buffer of the demux driver.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the filtered section data in buffer1, including
- headers and CRC.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8* buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the filtered section data, or NULL.
- Useful to handle the wrapping of a circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the filtered section data in buffer2, including
- headers and CRC.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_filter_t*
- filter</para>
-</entry><entry
- align="char">
-<para>Indicates the filter that triggered the callback.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_success_t
- success</para>
-</entry><entry
- align="char">
-<para>Indicates if there was an error in section reception.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>Continue filtering.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-1</para>
-</entry><entry
- align="char">
-<para>Stop filtering - has the same effect as a call to
- stop_filtering() on the Section Feed API.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="ts_feed_api">
-<title>TS Feed API</title>
-<para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
-Using this API, the client can set the filtering properties to start/stop filtering TS
-packets on a particular TS feed. The API is defined as an abstract interface of the type
-dmx_ts_feed_t.
-</para>
-<para>The functions that implement the interface should be defined static or module private. The
-client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
-demux API.
-</para>
-
-<section
-role="subsection"><title>set()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function sets the parameters of a TS feed. Any filtering in progress on the
- TS feed must be stopped before calling this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int set ( dmx_ts_feed_t&#x22C6; feed, __u16 pid, size_t
- callback_length, size_t circular_buffer_size, int
- descramble, struct timespec timeout);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>PID value to filter. Only the TS packets carrying the
- specified PID will be passed to the API client.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t
- callback_length</para>
-</entry><entry
- align="char">
-<para>Number of bytes to deliver with each call to the
- dmx_ts_cb() callback function. The value of this
- parameter should be a multiple of 188.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t
- circular_buffer_size</para>
-</entry><entry
- align="char">
-<para>Size of the circular buffer for the filtered TS packets.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int descramble</para>
-</entry><entry
- align="char">
-<para>If non-zero, descramble the filtered TS packets.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct timespec
- timeout</para>
-</entry><entry
- align="char">
-<para>Maximum time to wait before delivering received TS
- packets to the client.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOMEM</para>
-</entry><entry
- align="char">
-<para>Not enough memory for the requested buffer size.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available for TS.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>start_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Starts filtering TS packets on this TS feed, according to its settings. The PID
- value to filter can be set by the API client. All matching TS packets are
- delivered asynchronously to the client, using the callback function registered
- with allocate_ts_feed().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int start_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>stop_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Stops filtering TS packets on this TS feed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int stop_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="section_feed_api">
-<title>Section Feed API</title>
-<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
-API, the client can set the properties of a section feed and to start/stop filtering. The API is
-defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
-the interface should be defined static or module private. The client can get the handle of
-a section feed API by calling the function allocate_section_feed() in the demux
-API.
-</para>
-<para>On demux platforms that provide section filtering in hardware, the Section Feed API
-implementation provides a software wrapper for the demux hardware. Other platforms may
-support only PID filtering in hardware, requiring that TS packets are converted to sections in
-software. In the latter case the Section Feed API implementation can be a client of the TS
-Feed API.
-</para>
-
-</section>
-<section id="kdapi_set">
-<title>set()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function sets the parameters of a section feed. Any filtering in progress on
- the section feed must be stopped before calling this function. If descrambling
- is enabled, the payload_scrambling_control and address_scrambling_control
- fields of received DVB datagram sections should be observed. If either one is
- non-zero, the section should be descrambled either in hardware or using the
- functions descramble_mac_address() and descramble_section_payload() of the
- demux API. Note that according to the MPEG-2 Systems specification, only
- the payloads of private sections can be scrambled while the rest of the section
- data must be sent in the clear.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int set(dmx_section_feed_t&#x22C6; feed, __u16 pid, size_t
- circular_buffer_size, int descramble, int
- check_crc);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>PID value to filter; only the TS packets carrying the
- specified PID will be accepted.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t
- circular_buffer_size</para>
-</entry><entry
- align="char">
-<para>Size of the circular buffer for filtered sections.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int descramble</para>
-</entry><entry
- align="char">
-<para>If non-zero, descramble any sections that are scrambled.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int check_crc</para>
-</entry><entry
- align="char">
-<para>If non-zero, check the CRC values of filtered sections.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOMEM</para>
-</entry><entry
- align="char">
-<para>Not enough memory for the requested buffer size.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available for sections.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameters.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>allocate_filter()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function is used to allocate a section filter on the demux. It should only be
- called when no filtering is in progress on this section feed. If a filter cannot be
- allocated, the function fails with -ENOSPC. See in section ?? for the format of
- the section filter.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The bitfields filter_mask and filter_value should only be modified when no
- filtering is in progress on this section feed. filter_mask controls which bits of
- filter_value are compared with the section headers/payload. On a binary value
- of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
- sections that are equal to filter_value in all the tested bit positions. Any changes
- to the values of filter_mask and filter_value are guaranteed to take effect only
- when the start_filtering() function is called next time. The parent pointer in
- the struct is initialized by the API implementation to the value of the feed
- parameter. The priv pointer is not used by the API implementation, and can
- thus be freely utilized by the caller of this function. Any data pointed to by the
- priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
- currently set at 16 bytes, hardware filters of that size are not available on all
- platforms. Therefore, section filtering will often take place first in hardware,
- followed by filtering in software for the header bytes that were not covered
- by a hardware filter. The filter_mask field can be checked to determine how
- many bytes of the section filter are actually used, and if the hardware filter will
- suffice. Additionally, software-only section filters can optionally be allocated
- to clients when all hardware section filters are in use. Note that on most demux
- hardware it is not possible to filter on the section_length field of the section
- header &#8211; thus this field is ignored, even though it is included in filter_value and
- filter_mask fields.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int allocate_filter(dmx_section_feed_t&#x22C6; feed,
- dmx_section_filter_t&#x22C6;&#x22C6; filter);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_filter_t**
- filter</para>
-</entry><entry
- align="char">
-<para>Pointer to the allocated filter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSPC</para>
-</entry><entry
- align="char">
-<para>No filters of given type and length available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameters.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>release_filter()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function releases all the resources of a previously allocated section filter.
- The function should not be called while filtering is in progress on this section
- feed. After calling this function, the caller should not try to dereference the
- filter pointer.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int release_filter ( dmx_section_feed_t&#x22C6; feed,
- dmx_section_filter_t&#x22C6; filter);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_filter_t*
- filter</para>
-</entry><entry
- align="char">
-<para>I/O Pointer to the instance data of a section filter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENODEV</para>
-</entry><entry
- align="char">
-<para>No such filter allocated.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>start_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Starts filtering sections on this section feed, according to its settings. Sections
- are first filtered based on their PID and then matched with the section
- filters allocated for this feed. If the section matches the PID filter and
- at least one section filter, it is delivered to the API client. The section
- is delivered asynchronously using the callback function registered with
- allocate_section_feed().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int start_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>stop_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Stops filtering sections on this section feed. Note that any changes to the
- filtering parameters (filter_value, filter_mask, etc.) should only be made when
- filtering is stopped.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int stop_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
diff --git a/Documentation/DocBook/media/dvb/net.xml b/Documentation/DocBook/media/dvb/net.xml
deleted file mode 100644
index a193e86941b5..000000000000
--- a/Documentation/DocBook/media/dvb/net.xml
+++ /dev/null
@@ -1,156 +0,0 @@
-<title>DVB Network API</title>
-<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets
-received via DVB into the Linux network protocol stack, e.g. for internet via satellite
-applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and
-and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your
-application.
-</para>
-<section id="dvb_net_types">
-<title>DVB Net Data Types</title>
-
-<section id="dvb-net-if">
-<title>struct dvb_net_if</title>
-<programlisting>
-struct dvb_net_if {
- __u16 pid;
- __u16 if_num;
- __u8 feedtype;
-#define DVB_NET_FEEDTYPE_MPE 0 /&#x22C6; multi protocol encapsulation &#x22C6;/
-#define DVB_NET_FEEDTYPE_ULE 1 /&#x22C6; ultra lightweight encapsulation &#x22C6;/
-};
-</programlisting>
-</section>
-
-</section>
-<section id="net_fcalls">
-<title>DVB net Function Calls</title>
-<para>To be written&#x2026;
-</para>
-
-<section id="NET_ADD_IF"
-role="subsection"><title>NET_ADD_IF</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = NET_ADD_IF,
- struct dvb_net_if *if);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals NET_ADD_IF for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct dvb_net_if *if
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="NET_REMOVE_IF"
-role="subsection"><title>NET_REMOVE_IF</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = NET_REMOVE_IF);
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals NET_REMOVE_IF for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-
-<section id="NET_GET_IF"
-role="subsection"><title>NET_GET_IF</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is undocumented. Documentation is welcome.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = NET_GET_IF,
- struct dvb_net_if *if);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals NET_GET_IF for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct dvb_net_if *if
-</para>
-</entry><entry
- align="char">
-<para>Undocumented.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-</section>
-</section>
diff --git a/Documentation/DocBook/media/dvb/video.xml b/Documentation/DocBook/media/dvb/video.xml
deleted file mode 100644
index 3ea1ca7e785e..000000000000
--- a/Documentation/DocBook/media/dvb/video.xml
+++ /dev/null
@@ -1,1968 +0,0 @@
-<title>DVB Video Device</title>
-<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It
-can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and
-ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
-application.
-</para>
-<para>Note that the DVB video device only controls decoding of the MPEG video stream, not
-its presentation on the TV or computer screen. On PCs this is typically handled by an
-associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output
-windows.
-</para>
-<para>Some DVB cards don&#8217;t have their own MPEG decoder, which results in the omission of
-the audio and video device as well as the video4linux device.
-</para>
-<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only
-supported on some MPEG decoders made for DVD playback.
-</para>
-<para>
-These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use
-of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls
-have been created to replace that functionality.</para>
-<section id="video_types">
-<title>Video Data Types</title>
-
-<section id="video-format-t">
-<title>video_format_t</title>
-<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by
-</para>
-<programlisting>
-typedef enum {
- VIDEO_FORMAT_4_3, /&#x22C6; Select 4:3 format &#x22C6;/
- VIDEO_FORMAT_16_9, /&#x22C6; Select 16:9 format. &#x22C6;/
- VIDEO_FORMAT_221_1 /&#x22C6; 2.21:1 &#x22C6;/
-} video_format_t;
-</programlisting>
-<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio
-the output hardware (e.g. TV) has. It is also used in the data structures video_status
-(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by
-VIDEO_GET_EVENT (??) which report about the display format of the current video
-stream.
-</para>
-</section>
-
-<section id="video-displayformat-t">
-<title>video_displayformat_t</title>
-<para>In case the display format of the video stream and of the display hardware differ the
-application has to specify how to handle the cropping of the picture. This can be done using
-the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
-</para>
-<programlisting>
-typedef enum {
- VIDEO_PAN_SCAN, /&#x22C6; use pan and scan format &#x22C6;/
- VIDEO_LETTER_BOX, /&#x22C6; use letterbox format &#x22C6;/
- VIDEO_CENTER_CUT_OUT /&#x22C6; use center cut out format &#x22C6;/
-} video_displayformat_t;
-</programlisting>
-<para>as argument.
-</para>
-</section>
-
-<section id="video-stream-source-t">
-<title>video_stream_source_t</title>
-<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take
-the following values, depending on whether we are replaying from an internal (demuxer) or
-external (user write) source.
-</para>
-<programlisting>
-typedef enum {
- VIDEO_SOURCE_DEMUX, /&#x22C6; Select the demux as the main source &#x22C6;/
- VIDEO_SOURCE_MEMORY /&#x22C6; If this source is selected, the stream
- comes from the user through the write
- system call &#x22C6;/
-} video_stream_source_t;
-</programlisting>
-<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
-DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY
-is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
-call.
-</para>
-</section>
-
-<section id="video-play-state-t">
-<title>video_play_state_t</title>
-<para>The following values can be returned by the VIDEO_GET_STATUS call representing the
-state of video playback.
-</para>
-<programlisting>
-typedef enum {
- VIDEO_STOPPED, /&#x22C6; Video is stopped &#x22C6;/
- VIDEO_PLAYING, /&#x22C6; Video is currently playing &#x22C6;/
- VIDEO_FREEZED /&#x22C6; Video is freezed &#x22C6;/
-} video_play_state_t;
-</programlisting>
-</section>
-
-<section id="video-command">
-<title>struct video_command</title>
-<para>The structure must be zeroed before use by the application
-This ensures it can be extended safely in the future.</para>
-<programlisting>
-struct video_command {
- __u32 cmd;
- __u32 flags;
- union {
- struct {
- __u64 pts;
- } stop;
-
- struct {
- /&#x22C6; 0 or 1000 specifies normal speed,
- 1 specifies forward single stepping,
- -1 specifies backward single stepping,
- &gt;>1: playback at speed/1000 of the normal speed,
- &lt;-1: reverse playback at (-speed/1000) of the normal speed. &#x22C6;/
- __s32 speed;
- __u32 format;
- } play;
-
- struct {
- __u32 data[16];
- } raw;
- };
-};
-</programlisting>
-</section>
-
-<section id="video-size-t">
-<title>video_size_t</title>
-<programlisting>
-typedef struct {
- int w;
- int h;
- video_format_t aspect_ratio;
-} video_size_t;
-</programlisting>
-</section>
-
-
-<section id="video-event">
-<title>struct video_event</title>
-<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT
-call.
-</para>
-<programlisting>
-struct video_event {
- __s32 type;
-#define VIDEO_EVENT_SIZE_CHANGED 1
-#define VIDEO_EVENT_FRAME_RATE_CHANGED 2
-#define VIDEO_EVENT_DECODER_STOPPED 3
-#define VIDEO_EVENT_VSYNC 4
- __kernel_time_t timestamp;
- union {
- video_size_t size;
- unsigned int frame_rate; /&#x22C6; in frames per 1000sec &#x22C6;/
- unsigned char vsync_field; /&#x22C6; unknown/odd/even/progressive &#x22C6;/
- } u;
-};
-</programlisting>
-</section>
-
-<section id="video-status">
-<title>struct video_status</title>
-<para>The VIDEO_GET_STATUS call returns the following structure informing about various
-states of the playback operation.
-</para>
-<programlisting>
-struct video_status {
- int video_blank; /&#x22C6; blank video on freeze? &#x22C6;/
- video_play_state_t play_state; /&#x22C6; current state of playback &#x22C6;/
- video_stream_source_t stream_source; /&#x22C6; current source (demux/memory) &#x22C6;/
- video_format_t video_format; /&#x22C6; current aspect ratio of stream &#x22C6;/
- video_displayformat_t display_format;/&#x22C6; selected cropping mode &#x22C6;/
-};
-</programlisting>
-<para>If video_blank is set video will be blanked out if the channel is changed or if playback is
-stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is
-currently frozen, stopped, or being played back. The stream_source corresponds to the seleted
-source for the video stream. It can come either from the demultiplexer or from memory.
-The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently
-played video stream. Finally, display_format corresponds to the selected cropping
-mode in case the source video format is not the same as the format of the output
-device.
-</para>
-</section>
-
-<section id="video-still-picture">
-<title>struct video_still_picture</title>
-<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the
-following structure.
-</para>
-<programlisting>
-/&#x22C6; pointer to and size of a single iframe in memory &#x22C6;/
-struct video_still_picture {
- char &#x22C6;iFrame; /&#x22C6; pointer to a single iframe in memory &#x22C6;/
- int32_t size;
-};
-</programlisting>
-</section>
-
-<section id="video_caps">
-<title>video capabilities</title>
-<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following
-bits set according to the hardwares capabilities.
-</para>
-<programlisting>
- /&#x22C6; bit definitions for capabilities: &#x22C6;/
- /&#x22C6; can the hardware decode MPEG1 and/or MPEG2? &#x22C6;/
- #define VIDEO_CAP_MPEG1 1
- #define VIDEO_CAP_MPEG2 2
- /&#x22C6; can you send a system and/or program stream to video device?
- (you still have to open the video and the audio device but only
- send the stream to the video device) &#x22C6;/
- #define VIDEO_CAP_SYS 4
- #define VIDEO_CAP_PROG 8
- /&#x22C6; can the driver also handle SPU, NAVI and CSS encoded data?
- (CSS API is not present yet) &#x22C6;/
- #define VIDEO_CAP_SPU 16
- #define VIDEO_CAP_NAVI 32
- #define VIDEO_CAP_CSS 64
-</programlisting>
-</section>
-
-<section id="video-system">
-<title>video_system_t</title>
-<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The
-following system types can be set:
-</para>
-<programlisting>
-typedef enum {
- VIDEO_SYSTEM_PAL,
- VIDEO_SYSTEM_NTSC,
- VIDEO_SYSTEM_PALN,
- VIDEO_SYSTEM_PALNc,
- VIDEO_SYSTEM_PALM,
- VIDEO_SYSTEM_NTSC60,
- VIDEO_SYSTEM_PAL60,
- VIDEO_SYSTEM_PALM60
-} video_system_t;
-</programlisting>
-</section>
-
-<section id="video-highlight">
-<title>struct video_highlight</title>
-<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The
-call expects the following format for that information:
-</para>
-<programlisting>
- typedef
- struct video_highlight {
- boolean active; /&#x22C6; 1=show highlight, 0=hide highlight &#x22C6;/
- uint8_t contrast1; /&#x22C6; 7- 4 Pattern pixel contrast &#x22C6;/
- /&#x22C6; 3- 0 Background pixel contrast &#x22C6;/
- uint8_t contrast2; /&#x22C6; 7- 4 Emphasis pixel-2 contrast &#x22C6;/
- /&#x22C6; 3- 0 Emphasis pixel-1 contrast &#x22C6;/
- uint8_t color1; /&#x22C6; 7- 4 Pattern pixel color &#x22C6;/
- /&#x22C6; 3- 0 Background pixel color &#x22C6;/
- uint8_t color2; /&#x22C6; 7- 4 Emphasis pixel-2 color &#x22C6;/
- /&#x22C6; 3- 0 Emphasis pixel-1 color &#x22C6;/
- uint32_t ypos; /&#x22C6; 23-22 auto action mode &#x22C6;/
- /&#x22C6; 21-12 start y &#x22C6;/
- /&#x22C6; 9- 0 end y &#x22C6;/
- uint32_t xpos; /&#x22C6; 23-22 button color number &#x22C6;/
- /&#x22C6; 21-12 start x &#x22C6;/
- /&#x22C6; 9- 0 end x &#x22C6;/
- } video_highlight_t;
-</programlisting>
-
-</section>
-<section id="video-spu">
-<title>struct video_spu</title>
-<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the
-following format:
-</para>
-<programlisting>
- typedef
- struct video_spu {
- boolean active;
- int stream_id;
- } video_spu_t;
-</programlisting>
-
-</section>
-<section id="video-spu-palette">
-<title>struct video_spu_palette</title>
-<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE:
-</para>
-<programlisting>
- typedef
- struct video_spu_palette {
- int length;
- uint8_t &#x22C6;palette;
- } video_spu_palette_t;
-</programlisting>
-
-</section>
-<section id="video-navi-pack">
-<title>struct video_navi_pack</title>
-<para>In order to get the navigational data the following structure has to be passed to the ioctl
-VIDEO_GET_NAVI:
-</para>
-<programlisting>
- typedef
- struct video_navi_pack {
- int length; /&#x22C6; 0 ... 1024 &#x22C6;/
- uint8_t data[1024];
- } video_navi_pack_t;
-</programlisting>
-</section>
-
-
-<section id="video-attributes-t">
-<title>video_attributes_t</title>
-<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
-</para>
-<programlisting>
- typedef uint16_t video_attributes_t;
- /&#x22C6; bits: descr. &#x22C6;/
- /&#x22C6; 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) &#x22C6;/
- /&#x22C6; 13-12 TV system (0=525/60, 1=625/50) &#x22C6;/
- /&#x22C6; 11-10 Aspect ratio (0=4:3, 3=16:9) &#x22C6;/
- /&#x22C6; 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca &#x22C6;/
- /&#x22C6; 7 line 21-1 data present in GOP (1=yes, 0=no) &#x22C6;/
- /&#x22C6; 6 line 21-2 data present in GOP (1=yes, 0=no) &#x22C6;/
- /&#x22C6; 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 &#x22C6;/
- /&#x22C6; 2 source letterboxed (1=yes, 0=no) &#x22C6;/
- /&#x22C6; 0 film/camera mode (0=camera, 1=film (625/50 only)) &#x22C6;/
-</programlisting>
-</section></section>
-
-
-<section id="video_function_calls">
-<title>Video Function Calls</title>
-
-
-<section id="video_fopen">
-<title>open()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0)
- for subsequent use.</para>
-<para>When an open() call has succeeded, the device will be ready for use.
- The significance of blocking or non-blocking mode is described in the
- documentation for functions where there is a difference. It does not affect the
- semantics of the open() call itself. A device opened in blocking mode can later
- be put into non-blocking mode (and vice versa) using the F_SETFL command
- of the fcntl system call. This is a standard system call, documented in the Linux
- manual page for fcntl. Only one user can open the Video Device in O_RDWR
- mode. All other attempts to open the device in this mode will fail, and an
- error-code will be returned. If the Video Device is opened in O_RDONLY
- mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other
- call will return an error code.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open(const char &#x22C6;deviceName, int flags);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>const char
- *deviceName</para>
-</entry><entry
- align="char">
-<para>Name of specific video device.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int flags</para>
-</entry><entry
- align="char">
-<para>A bit-wise OR of the following flags:</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDONLY read-only access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_RDWR read/write access</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>O_NONBLOCK open in non-blocking mode</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>(blocking mode is the default)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>Device driver not loaded/available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINTERNAL</para>
-</entry><entry
- align="char">
-<para>Internal error.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>Device or resource busy.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid argument.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="video_fclose">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call closes a previously opened video device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(int fd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="video_fwrite">
-<title>write()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected
- in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
- PES format, unless the capability allows other formats. If O_NONBLOCK is
- not specified the function will block until buffer space is available. The amount
- of data to be transferred is implied by count.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>void *buf</para>
-</entry><entry
- align="char">
-<para>Pointer to the buffer containing the PES data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t count</para>
-</entry><entry
- align="char">
-<para>Size of buf.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURN VALUE</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EPERM</para>
-</entry><entry
- align="char">
-<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ENOMEM</para>
-</entry><entry
- align="char">
-<para>Attempted to write more data than the internal buffer can
- hold.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBADF</para>
-</entry><entry
- align="char">
-<para>fd is not a valid open file descriptor.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_STOP"
-role="subsection"><title>VIDEO_STOP</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
-&VIDIOC-DECODER-CMD; instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to stop playing the current stream.
- Depending on the input parameter, the screen can be blanked out or displaying
- the last decoded frame.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_STOP, boolean
- mode);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_STOP for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>Boolean mode</para>
-</entry><entry
- align="char">
-<para>Indicates how the screen shall be handled.</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>TRUE: Blank screen when stop.</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>FALSE: Show last decoded frame.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_PLAY"
-role="subsection"><title>VIDEO_PLAY</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
-&VIDIOC-DECODER-CMD; instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to start playing a video stream from the
- selected source.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_PLAY);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_PLAY for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_FREEZE"
-role="subsection"><title>VIDEO_FREEZE</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
-&VIDIOC-DECODER-CMD; instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call suspends the live video stream being played. Decoding
- and playing are frozen. It is then possible to restart the decoding
- and playing process of the video stream using the VIDEO_CONTINUE
- command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call
- VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more
- data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_FREEZE);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_FREEZE for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_CONTINUE"
-role="subsection"><title>VIDEO_CONTINUE</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
-&VIDIOC-DECODER-CMD; instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call restarts decoding and playing processes of the video stream
- which was played before a call to VIDEO_FREEZE was made.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_CONTINUE for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SELECT_SOURCE"
-role="subsection"><title>VIDEO_SELECT_SOURCE</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. This ioctl was also supported by the
-V4L2 ivtv driver, but that has been replaced by the ivtv-specific
-<constant>IVTV_IOC_PASSTHROUGH_MODE</constant> ioctl.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call informs the video device which source shall be used for the input
- data. The possible sources are demux or memory. If memory is selected, the
- data is fed to the video device through the write command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE,
- video_stream_source_t source);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SELECT_SOURCE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_stream_source_t
- source</para>
-</entry><entry
- align="char">
-<para>Indicates which source shall be used for the Video stream.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SET_BLANK"
-role="subsection"><title>VIDEO_SET_BLANK</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to blank out the picture.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean
- mode);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_BLANK for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>boolean mode</para>
-</entry><entry
- align="char">
-<para>TRUE: Blank screen when stop.</para>
-</entry>
- </row><row><entry
- align="char">
-</entry><entry
- align="char">
-<para>FALSE: Show last decoded frame.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_GET_STATUS"
-role="subsection"><title>VIDEO_GET_STATUS</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to return the current status of the device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct
- video_status &#x22C6;status);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_STATUS for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct video_status
- *status</para>
-</entry><entry
- align="char">
-<para>Returns the current status of the Video Device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_GET_FRAME_COUNT"
-role="subsection"><title>VIDEO_GET_FRAME_COUNT</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
-ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> control.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to return the number of displayed frames
-since the decoder was started.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- VIDEO_GET_FRAME_COUNT, __u64 *pts);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_FRAME_COUNT for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u64 *pts
-</para>
-</entry><entry
- align="char">
-<para>Returns the number of frames displayed since the decoder was started.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_GET_PTS"
-role="subsection"><title>VIDEO_GET_PTS</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
-ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> control.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to return the current PTS timestamp.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- VIDEO_GET_PTS, __u64 *pts);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_PTS for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u64 *pts
-</para>
-</entry><entry
- align="char">
-<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
-</para>
-<para>
-The PTS should belong to the currently played
-frame if possible, but may also be a value close to it
-like the PTS of the last decoded frame or the last PTS
-extracted by the PES parser.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_GET_FRAME_RATE"
-role="subsection"><title>VIDEO_GET_FRAME_RATE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to return the current framerate.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- VIDEO_GET_FRAME_RATE, unsigned int *rate);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_FRAME_RATE for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>unsigned int *rate
-</para>
-</entry><entry
- align="char">
-<para>Returns the framerate in number of frames per 1000 seconds.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_GET_EVENT"
-role="subsection"><title>VIDEO_GET_EVENT</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is for DVB devices only. To get events from a V4L2 decoder use the V4L2
-&VIDIOC-DQEVENT; ioctl instead.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call returns an event of type video_event if available. If an event is
- not available, the behavior depends on whether the device is in blocking or
- non-blocking mode. In the latter case, the call fails immediately with errno
- set to EWOULDBLOCK. In the former case, the call blocks until an event
- becomes available. The standard Linux poll() and/or select() system calls can
- be used with the device file descriptor to watch for new events. For select(),
- the file descriptor should be included in the exceptfds argument, and for
- poll(), POLLPRI should be specified as the wake-up condition. Read-only
- permissions are sufficient for this ioctl call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct
- video_event &#x22C6;ev);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_EVENT for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct video_event
- *ev</para>
-</entry><entry
- align="char">
-<para>Points to the location where the event, if any, is to be
- stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EWOULDBLOCK</para>
-</entry><entry
- align="char">
-<para>There is no event pending, and the device is in
- non-blocking mode.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EOVERFLOW</para>
-</entry><entry
- align="char">
-<para>Overflow in event queue - one or more events were lost.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_COMMAND"
-role="subsection"><title>VIDEO_COMMAND</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
-ioctl has been replaced by the &VIDIOC-DECODER-CMD; ioctl.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl commands the decoder. The <constant>video_command</constant> struct
-is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the
-&VIDIOC-DECODER-CMD; documentation for more information.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- VIDEO_COMMAND, struct video_command *cmd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_COMMAND for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct video_command *cmd
-</para>
-</entry><entry
- align="char">
-<para>Commands the decoder.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_TRY_COMMAND"
-role="subsection"><title>VIDEO_TRY_COMMAND</title>
-<para>DESCRIPTION
-</para>
-<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
-ioctl has been replaced by the &VIDIOC-TRY-DECODER-CMD; ioctl.</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl tries a decoder command. The <constant>video_command</constant> struct
-is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the
-&VIDIOC-TRY-DECODER-CMD; documentation for more information.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- VIDEO_TRY_COMMAND, struct video_command *cmd);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_TRY_COMMAND for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct video_command *cmd
-</para>
-</entry><entry
- align="char">
-<para>Try a decoder command.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_GET_SIZE"
-role="subsection"><title>VIDEO_GET_SIZE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl returns the size and aspect ratio.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request =
- VIDEO_GET_SIZE, video_size_t *size);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_SIZE for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_size_t *size
-</para>
-</entry><entry
- align="char">
-<para>Returns the size and aspect ratio.
-</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SET_DISPLAY_FORMAT"
-role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to select the video format to be applied
- by the MPEG chip on the video.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request =
- VIDEO_SET_DISPLAY_FORMAT, video_display_format_t
- format);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_DISPLAY_FORMAT for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_display_format_t
- format</para>
-</entry><entry
- align="char">
-<para>Selects the video format to be used.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_STILLPICTURE"
-role="subsection"><title>VIDEO_STILLPICTURE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to display a still picture (I-frame). The
- input data shall contain an I-frame. If the pointer is NULL, then the current
- displayed still picture is blanked.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_STILLPICTURE,
- struct video_still_picture &#x22C6;sp);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_STILLPICTURE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct
- video_still_picture
- *sp</para>
-</entry><entry
- align="char">
-<para>Pointer to a location where an I-frame and size is stored.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_FAST_FORWARD"
-role="subsection"><title>VIDEO_FAST_FORWARD</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the Video Device to skip decoding of N number of I-frames.
- This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int
- nFrames);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_FAST_FORWARD for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int nFrames</para>
-</entry><entry
- align="char">
-<para>The number of frames to skip.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EPERM</para>
-</entry><entry
- align="char">
-<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_SLOWMOTION"
-role="subsection"><title>VIDEO_SLOWMOTION</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the video device to repeat decoding frames N number of
- times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int
- nFrames);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SLOWMOTION for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int nFrames</para>
-</entry><entry
- align="char">
-<para>The number of times to repeat each frame.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EPERM</para>
-</entry><entry
- align="char">
-<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_GET_CAPABILITIES"
-role="subsection"><title>VIDEO_GET_CAPABILITIES</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call asks the video device about its decoding capabilities. On success
- it returns and integer which has bits set according to the defines in section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES,
- unsigned int &#x22C6;cap);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_CAPABILITIES for this
- command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>unsigned int *cap</para>
-</entry><entry
- align="char">
-<para>Pointer to a location where to store the capability
- information.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SET_ID"
-role="subsection"><title>VIDEO_SET_ID</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl selects which sub-stream is to be decoded if a program or system
- stream is sent to the video device.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(int fd, int request = VIDEO_SET_ID, int
- id);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_ID for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int id</para>
-</entry><entry
- align="char">
-<para>video sub-stream id</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>Invalid sub-stream id.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_CLEAR_BUFFER"
-role="subsection"><title>VIDEO_CLEAR_BUFFER</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_CLEAR_BUFFER for this command.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SET_STREAMTYPE"
-role="subsection"><title>VIDEO_SET_STREAMTYPE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl tells the driver which kind of stream to expect being written to it. If
- this call is not used the default of video PES is used. Some drivers might not
- support this call and always expect PES.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE,
- int type);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_STREAMTYPE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int type</para>
-</entry><entry
- align="char">
-<para>stream type</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SET_FORMAT"
-role="subsection"><title>VIDEO_SET_FORMAT</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl sets the screen format (aspect ratio) of the connected output device
- (TV) so that the output of the decoder can be adjusted accordingly.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_SET_FORMAT,
- video_format_t format);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_FORMAT for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_format_t
- format</para>
-</entry><entry
- align="char">
-<para>video format of TV as defined in section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>format is not a valid video format.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_SET_SYSTEM"
-role="subsection"><title>VIDEO_SET_SYSTEM</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl sets the television output format. The format (see section ??) may
- vary from the color format of the displayed MPEG stream. If the hardware is
- not able to display the requested format the call will return an error.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM ,
- video_system_t system);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_FORMAT for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_system_t
- system</para>
-</entry><entry
- align="char">
-<para>video system of TV output.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>system is not a valid or supported video system.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_SET_HIGHLIGHT"
-role="subsection"><title>VIDEO_SET_HIGHLIGHT</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT
- ,video_highlight_t &#x22C6;vhilite)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_highlight_t
- *vhilite</para>
-</entry><entry
- align="char">
-<para>SPU Highlight information according to section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-
-</section><section id="VIDEO_SET_SPU"
-role="subsection"><title>VIDEO_SET_SPU</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can
- only be used, if the driver is able to handle a DVD stream.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_SET_SPU ,
- video_spu_t &#x22C6;spu)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_SPU for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_spu_t *spu</para>
-</entry><entry
- align="char">
-<para>SPU decoding (de)activation and subid setting according
- to section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>input is not a valid spu setting or driver cannot handle
- SPU.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_SET_SPU_PALETTE"
-role="subsection"><title>VIDEO_SET_SPU_PALETTE</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl sets the SPU color palette.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE
- ,video_spu_palette_t &#x22C6;palette )</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_spu_palette_t
- *palette</para>
-</entry><entry
- align="char">
-<para>SPU palette according to section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>input is not a valid palette or driver doesn&#8217;t handle SPU.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_GET_NAVI"
-role="subsection"><title>VIDEO_GET_NAVI</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl returns navigational information from the DVD stream. This is
- especially needed if an encoded stream has to be decoded by the hardware.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_GET_NAVI ,
- video_navi_pack_t &#x22C6;navipack)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_GET_NAVI for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_navi_pack_t
- *navipack</para>
-</entry><entry
- align="char">
-<para>PCI or DSI pack (private stream 2) according to section
- ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EFAULT</para>
-</entry><entry
- align="char">
-<para>driver is not able to return navigational information</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section id="VIDEO_SET_ATTRIBUTES"
-role="subsection"><title>VIDEO_SET_ATTRIBUTES</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This ioctl is intended for DVD playback and allows you to set certain
- information about the stream. Some hardware may not need this information,
- but the call also tells the hardware to prepare for DVD playback.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE
- ,video_attributes_t vattr)</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>int fd</para>
-</entry><entry
- align="char">
-<para>File descriptor returned by a previous call to open().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int request</para>
-</entry><entry
- align="char">
-<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>video_attributes_t
- vattr</para>
-</entry><entry
- align="char">
-<para>video attributes according to section ??.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-&return-value-dvb;
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>EINVAL</para>
-</entry><entry
- align="char">
-<para>input is not a valid attribute setting.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
diff --git a/Documentation/DocBook/media/dvbstb.png.b64 b/Documentation/DocBook/media/dvbstb.png.b64
deleted file mode 100644
index e8b52fde3d11..000000000000
--- a/Documentation/DocBook/media/dvbstb.png.b64
+++ /dev/null
@@ -1,398 +0,0 @@
-iVBORw0KGgoAAAANSUhEUgAAAzMAAAGaCAYAAAA7Jx25AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBI
-WXMAAA3XAAANiQFmEOuiAAAgAElEQVR42uzdd1RU18I28GdgKFZUBE0saFA0KoqFFkEhKhbAQmxJ
-bIkNNEpMEUwsMZarJMZrw4KxRExQczUqil0jRBA1GAjGQqLYC4TemdnfH76cj3HodYDntxaLmTll
-zuw57Zmz9z4yIYQAkYZzcnJCSkoKGjZsyMIgIiIiquPS09PRoEEDyBhmqCaQyWRo06YN3nvvPRYG
-ERERUR137Ngx/Pnnn5CzKKgmMDAwwKpVqxhmiIiIiAj29vZ4//33ocWiICIiIiKimohhhoiIiIiI
-GGaIiIiIiIgYZoiIiIiIiBhmiIiIiIiIYYaIiIiIiIhhhoiIiIiIiGGGiIiIiIgYZoiIiIiIiBhm
-iIiIiIiIGGaIiIiIiIgYZoiIiIiIiGGGiIiIiIiIYYaIiIiIiIhhhoiIiIiIGGaIiIiIiIgYZoiI
-iIiIiBhmiIiIiIiIYYaIiIiIiIhhhoiIiIiIqFLIWQRElSMsLAy2trZo1KgR5HJualTxEhIS8P33
-3+PDDz+sM5+5bdu2ePDgAZo2bcoVgCplm3J0dMS5c+fqzGf++uuvsWTJEm5TVClSU1ORk5ODBw8e
-oHXr1gwzRDVJbm4uAGDRokUwMDBggVCFmzlzJrKysurUZ3727BksLCzg4eHBFYAq3IIFC5CQkFCn
-PnNGRgYAYNWqVVwBqMJFRUVh48aNUCqVlfYeDDNElWzGjBkMM1QpNm7cWOc+c8uWLTFjxgzMmDGD
-KwBVuLt37yIkJKTOfW5nZ2duU1SpYaYysc0MERERERHVSAwzRERERETEMENERERERMQwQ0RERERE
-xDBDREREREQMM0RERERERAwzREREREREDDNERERERMQwQ0RERERExDBDRERERETEMENERERERMQw
-Q0REREREDDNEREREREQMM0RERERERAwzRERERETEMENERERERMQwQ0RERERExDBDREREREQMM0RE
-RERERAwzREREREREDDNEREREREQMM0RERERExDBDRERERETEMENERERERMQwQ0REREREDDNERERE
-REQMM0RERERERAwzRERERETEMENERERERMQwQ0REREREVGnkLAKimunBgwdISkoq8/SGhoZ47bXX
-WJCV6NmzZwgMDMS5c+ewd+9eFgiVSVZWFkJCQnD16lU8evQICoUChoaG6NChA2xsbNCxY0fIZDI8
-efIEp06dwuTJk0s876CgIJiYmKBLly4saKq2Y5Wuri6aNm0KQ0NDaGnxd3ZimCGqE/78808EBgbi
-p59+QkJCgsowLS0tyGQy6blSqYQQQmWcjz/+GGvXrmVBVoKtW7di+/btuHbtGoQQMDQ0ZKFQqf37
-77/w8fHBtm3bkJCQgCZNmsDS0hLGxsZ48OABtm/fjidPnsDU1BR2dnYICwtDz549SxxmlEol5s6d
-CxsbG+zZs4cFTpV2rDpx4gQOHDiAJ0+eqAzT09ODUqlETk4OAEBfXx/dunWDvb093Nzc0LdvX5Vj
-GVFBGH+JaqihQ4di06ZNOHr0qMrrly5dgkKhQG5urvSnVCqRlZWF27dvY8mSJQCA7OxsFmIlmTFj
-Bs6ePctfu6nMTp48iTfffBOrV6+Gnp4e9uzZg+fPn+PUqVPw9/fHkSNH8PDhQxw9ehRCCOzevRu3
-bt1CWlpaqd4jJiYG+/btw+PHj1noVGnHqnXr1uHcuXMqr+/fvx8ZGRnIzs5GSkoKIiIi8M0330BH
-Rwdr166Fvb09evXqhdOnT7MQiWGGqDazsrJSeV5Y1TFdXV107NgRX331FSZPniz9ElbTnDp1SuOX
-USaToXHjxujevTtXUCq1H3/8EcOGDcPz58/RtWtXREREYMKECdDR0VE9gGtpwcXFBdeuXYONjQ0A
-ID09vcTvs2HDBgBATk4OfH19WfBUqTp16gS5/P9XCDI3N5euujRs2BAWFhb46KOP8Ntvv+HIkSNo
-3rw5rl+/DicnJ3z66adQKpUsRGKYIaqNdHR0Sl3HeNy4cTXyysyBAwdq1EkX635TaV29ehVTpkyB
-UqlEw4YNcfToUbRs2bLIaZo0aYIjR47AyMioxFdm7ty5g6CgIGhrawMAtmzZgoyMDH4BVGlkMhl0
-dXVLNJ6rqyvCwsLQqlUrAMB3332Hjz/+mIVIDDNEtfkgURqOjo5YunRpjfqMd+7cwfTp0/llU62l
-VCoxY8YM6arp/Pnz0b59+xJNa2RkBC8vrxJfmfH19YWVlRUmTJgAAIiPj2cnFaRRxypTU1McOnRI
-CtwbNmzA4cOHWYjEMENUl+Xm5iIhIQH6+vowMTEpcJz8HQUIIdQ6DijoBKy0CppnUfN59uwZnJ2d
-S9V7mxCiVMtW2mWqiPckyu/EiROIiIgAAGhra8Pd3b1U00+aNAlZWVnFjpeamoqdO3di9uzZmD17
-tvT6f//732K3d6KqZGlpiRkzZkjPvby8it3HlmY/XNh+v6jtoCTHRU1RlmNSac8BGGaIqEpduXIF
-CxYsUHs9MTERfn5+sLa2xrVr15CSkoJJkyZBX18fbdq0QWRkpMrOLTAwEMOHD4epqSnat2+Pxo0b
-o3///vDz8yu0LU5ubi7Onz8PDw8PmJubS+87d+5cGBoaQi6Xw8LCQq2x5+XLl2Fra4s7d+4AAEJD
-Q+Hi4gIXFxfMnz9fZdzs7Gz4+vrC2toa+vr60NHRQdeuXeHj41PgSV5Zl+lVx44dw8CBA/Haa6+h
-Q4cO6NmzJw4cOFBn17OgoCC1XouoeD/++KP02NbWFkZGRqWa3sjICDt37ix2PH9/f8jlcowdOxaW
-lpawtrYGAERHR+Ps2bP8IjRQaGgooqKi6mTYnDNnjvT41q1buHTpkto4pdn3CyFw7do1eHt7o127
-dkhMTIQQAv7+/rCwsIBcLkfTpk3x8ccfS9Wxc3NzsXnzZvTu3Ru6urqoX78+3n33XbWeRPfv34/x
-48dLx6jFixdLw5KSkjB37lwMHz5cGp6/hkRsbCzmz58vDcv7++KLL5Cbm4vDhw9j7Nix0utz587F
-s2fPylUWZTkH0NTURqTxDAwMxN69e2vUMgcHBwsAIjExsdLfS1tbWwAQAMTdu3cLHW/hwoVi5syZ
-0vMrV66IESNGCF1dXWn63377TfTv31/o6+tLry1YsEAIIUR6eroYPXq00NPTE7t37xY5OTlCCCFu
-374t+vbtKwCIHj16iNjYWJX3PXXqlHBycpLm16JFCxEdHS06duwoHB0dhYuLi6hfv74AIHR0dMQf
-f/whTfvXX3+J06dPC2NjYwFA2NraitOnT4vTp0+L8PBwabynT5+KPn36iOnTp4vIyEjx6NEjcejQ
-IdGiRQsBQPTt21ekpaVVyDLlUSgUYvbs2UIul4stW7aI7OxsIYQQ0dHRwsLCQjRq1EgAEIaGhpXy
-vZubmwtfX1+NW/fzyrRdu3Zi5syZIiAgQDx58qRC5t22bVuN/MwVoVWrVlLZeXp6Vsp7KJVK0bVr
-V+Hl5SW95u/vL72vs7NznT7WeHt7Czs7O41brmnTpgkAwsDAQIwYMUKsX79eREZGCqVSWSGfuaq+
-9wYNGkjr2l9//VXi6dq3by9Nt3jxYpVhpdn3X7p0SYwePVrI5XKV5Rg8eLCwsrIS7u7u4u2335aG
-ff755+LJkyfirbfeEo6OjmLWrFli1KhRQktLSwAQrq6uast67949af6DBw9WGx4dHS0ds18td6VS
-KZYtWya9f+/evVWGr1y5Uujq6oqAgIACv/vSHgdLew5QFpGRkQKA2nlBRQgMDBQGBgaCYYYYZmpZ
-mDl48KAIDQ2V/i5duiTOnj0rvv76a6Grq6sSZtLS0kR2drZ0oAQgnJycxKFDh0RqaqqYOHGiaNKk
-iTh9+rRQKpVi7NixAkCBJ5MpKSmic+fOAoDo1KmTSElJURtn6NChAoDQ19cXlpaWIiIiQhr2xx9/
-SJ9jypQpatOamJgIAGLEiBFqw7Kzs0WfPn3EqFGj1Hbw+/fvlz6bt7d3hS7TokWLBACxZs0atWGP
-Hz+WDtx1Lcw0a9ZMKnMdHR3pwF4R4aa2hpnk5GSpzApbpyrC2bNnhUwmU/nRIzMzU/qxAIC4efMm
-w4yG8fDwkE6gtbS0hJ6eXoWFm5oQZkaOHClNN3r06HLv+xcsWCANs7GxUflhTKlUSu/XoEEDYWlp
-KS5cuKAy/erVq6XpY2Ji1JbX1NS00DCT/3hWULkrlUoxZMgQ6bvOK6f09HTRsWNH8d133xU4z7KU
-RWnOARhmiBhmqizMFPeXP8zk+eGHH6ThX331VYHvcezYMQFANG3aVGRlZRU4zpEjR6T5fPHFF2rD
-P/roI2n4s2fP1Ib369dPCkOlCTNbt24VAMS5c+fUhmVmZkq/MDVt2lS6mlTeZbpx44bQ1tYWhoaG
-hZbH8OHD62SYMTIyKnT9K2+4qa1h5p9//lEpp61bt1bK+4waNarAX5PzgjkAMWvWLIYZDQwz+a8m
-5P8rb7ipCWFmxowZ0nSOjo7l3vdv375dml9YWJjatPv27ZOGb9q0SW34zZs3peG7du1SG96pU6ci
-w0xe2Cms3O/fvy9d2XdychJKpVJMmzZNODg4CIVCUeA05TkOluQcQJPDjJw1UYlql5s3b6o07hdC
-IC0tDZcuXcKHH35Y4DT5718xZMiQAsfJ6xLZysqq0O41hw0bBmNjYzx//hxbt27F0qVLVe4rkNcr
-DQAYGxurTZ/XDWd8fHypPrOfnx8AIDw8HNHR0WrDmzVrhsePHyMhIQE3btxQuf9LWZdp3bp1UCgU
-GDhwYKHl0ahRI66Qr8jfpurevXvYsWMHvv/+e+Tm5qJdu3YYPHgwHB0d0b9//2K7JK7NFApFhc8z
-NjYWhw8fxvHjx9WGzZw5EytXroRCocCuXbuwfPlyNG3alCtsDZB3U+S8dhlHjx7FiRMnkJWVBQMD
-Azg4OGDAgAFwcHBAt27dSt37pSbIv8z5j1dl3ffn3+83aNCg0P1+3jxe1aJFC+nxw4cPK/zztmnT
-Bt988w3c3d1x6tQpTJo0CYcPH0ZUVFShXf6X5zhYknMATcYwQ1TL6OnpQV9fX+W1evXqYfjw4Viw
-YIHUkL4w+Xfy+Q+WFy5cAAA0b968yGn79++PAwcOID4+HtHR0ejRo0eJlz1vJy1K0cg1OTkZ165d
-g7a2dqGNzseMGaP2HuVZJiGE1EVo586dq/Uk5v79+7h27ZpGrYO5ubllDjfff/89tm/fDoVCIYWb
-3r17w9XVtVaHm1eDQ1xcXIW/x5YtW/DGG29g0KBBBZ68ubm54cCBA0hPT8f27dvx+eef18l9aFpa
-msZtUy9evChzuDly5AiCgoKQnZ2Nxo0bw9HREf369YO9vT369OlTI76Tf//9V3r8+uuvV/q+v6Dj
-oMrJc74f6Srr/kzTp0/Hvn37cP78efj7+2Pjxo2F9kJakWVR3GdnmCGqQ4QG9jrz9ttv4+7du6We
-Lj4+XroZX3Enqp06dZIeP3z4sFRhpizu3r0rdT+5Zs2aKtkRv3jxAk+fPgVQvVdfsrOzsWrVKqxa
-tarWbDf516979+5h69atUkifOnVqpVyx0ARNmjSRrmoCQExMTIXOPyMjA35+flAoFCq/yL66nefZ
-sGED5s2bp3LSVlfcuHGjxpzkl/RYlNcrV3JyMg4fPiz9GOPo6CiFA01269Yt6XHv3r2rbd9flbS0
-tODn5wdzc3NkZGTg1KlTmDVrVoFX1mp7WTDMEFWDFy9eYPny5Rq3XD179sTGjRtLPV3+E8i8k/jC
-GBoaSo+rYoeaF7KEELh//36JbzJYHvl/Nc/MzKy271NPTw/ffvttodUHq4uZmVmZryzo6ekhKysL
-enp6sLS0hJOTE/r37w8bGxvo6uoiMDCw1u437OzscPDgQQAvu+KtSAEBAUhNTYWPj0+Rv8quWLEC
-T58+xYMHD3Do0CGVX3Prip49exZYFa86ffbZZ/jhhx9KddUzj46ODpRKJZRKJTp06IChQ4fCwcEB
-ffv2hbGxMRYsWIDExESNPp5GRUVJz11cXKpt31/V0tLSpOPvkSNHsG/fPowfP14jjoMMM0S12Llz
-5zBgwABMnTq11nym5s2bQ0dHBzk5OYiOjoYQotB61/lv0PXGG29U+rLVr19fehwSElIlO3E9PT3p
-8d9//11t34tMJkP9+vU1rm1Daerk6+vrIzMzUyW8ODo6Ftk2q7YaO3asFGbu3LmDqKgo6f5H5SGE
-wIYNGzBmzBjMnTu3yHHj4+Px1VdfAXh5E826GGby7jOiSfLvc4qjq6sLhUIBpVKJjh07YsiQIXBw
-cIC9vX2R1YQ11c6dO6WaDi4uLmjXrl217furUlZWFiZMmIClS5di48aNePToEebMmYMBAwao3YOq
-tpdFcXjTTKIKolQqsXz5cgwYMAAAMHz48Fp1cM+7sV5cXBxu3LhR6Lh59XVbtWqFjh07VvqymZqa
-SifPfn5+RVbvS01NxcyZM8v9nq1bt5YaTF64cIF3TS+FvPZcenp6sLOzwxdffIHg4GAkJycjODgY
-ixYtgp2dXZ0LMgDg5uamchLy3XffVch8L168iIiICEyfPr3YcWfOnCmt25cuXUJ4eDhXWg2nq6sL
-bW1tyGQymJmZwd3dHQcOHMCLFy9w69YtrFu3DqNGjaqRQebx48dSNVpdXV2sXr26Wvf9FaUkx4yF
-CxeicePGmD9/PjZv3iwdfz09PTXiOMgwQ1TLvHjxAoMGDcKSJUsAvLxjcUE9oFTWTjH/1ZDKOrH+
-4IMPpMcBAQGFjpd38uPu7l7qXnOKWva8eeXV/c7TqFEjKWgFBwdjz549BU6fm5uLKVOmwMnJqdzL
-pKenh/79+wN4WVc5KCioyGnrWtjJq/Lwanixt7dneCmCjo4ONm3aJD3ftWsXTp8+XeLpExMT4erq
-qnZX8NWrV8PMzAz29vbFzqNly5YYPXq09Hzt2rXcwWsApVIpVTcqaXjJX+W3Jp3E50lISMDIkSOR
-kJAAANi0aRO6dOlSZfv+8sirYp2enl5gGaSkpBQ5/a+//oqNGzfCz88PWlpacHV1xbvvvgsA+Omn
-n3D06NEqPQ4yzBDVcufPn0fXrl1x8eJFKJVKaGlp4bPPPquy909PT1c5QJSlZ5X8YaiwOtmTJk2C
-paUlAGDz5s0F1rG+ffs2goODYWZmhnnz5qkNL67xdl7PVgUd8PKqfdy+fVsanp2djcePH6v8UjVt
-2jSsX79e6s0HeFllx8XFBdnZ2XBzc6uQZcr/+Tw8PNS650xMTERISAiAl41uU1NT68w2kXcAfzW8
-XLx4keGlGEOHDsWaNWuk525ubiVqJxQaGgpLS0v069dPpdvYK1euICgoCGPGjCnxjwvvvfee9PjA
-gQPVWpWS/v8JsBCixoWXV/e1+dsYFhZshBA4deoU+vTpgytXrkBXVxfbtm3DtGnT1MYt674//zGv
-LMfE4n5AzLvCevnyZdy+fVulDFasWCHtIwu6DUFycjImT56MBQsW4M0335ReX7dunfQdu7u7qx2D
-y3McLMk5AMMMUS2kVCrx9ddfY+DAgYiPj0dubi7kcjnGjx+Ptm3bVtlynDx5UuV5YVcJipK/u+bf
-f/+9wHHkcjkOHTqETp06IT4+HhMmTFD5BT4hIQETJ05EmzZtEBgYWGDf/flPivJ6bcp/QPjzzz8B
-vOxONDk5WWW4ra2tNI/58+fj4MGDeOedd/Dvv/9i3LhxGDdunBQ+PD090bx5c/To0QOmpqYwMzND
-UlIS/P391U7oyrpMw4YNg4eHBwDg/v376NWrF1asWIHAwEBs27YNjo6OMDAwkA4O3bt3r3WX9gtz
-7do1ZGVlMbyU0SeffIJ9+/ahWbNmSE1NhaurK9zc3HDy5EmVX3pTU1MRFBSEd955By4uLli2bJlK
-d8qZmZmYNWuWtP2WVF6bhLyTr3nz5hV78keVa968eYiLi6tR4eVV58+fV1mP9u3bh5iYGPz999/4
-/fffcfjwYSxatAg9evTA4MGDce/ePbi5ueH69euFVpEs674/f2+BBQWK2NhY6XFB1aofPHggPX78
-+LHa8LyaDNnZ2bCzs4OXlxe8vb1hbm4OIQQcHBwAAGFhYXj//fdx7Ngx6bxi2rRpUCqV8PLyUpmn
-kZGRVPvj8ePHmDJlikrwKM9xsCTnAJqe9ok0noGBgdi7d6/GLM+TJ0+Eg4OD2h2ZZTKZiIyMFEII
-ERwcLACIxMTESlkGPz8/MWjQoALvCm1nZyc+/fTTYudx5swZ4erqKrS0tKRp9fT0xKRJk8T27dsL
-nCYpKUnMmzdPNGrUSLz++utixowZ4sMPPxQmJibC3d1dxMXFqU0TGhoqxo8fr7KMXbp0EV9++aUQ
-QoiTJ08KJycnleE9e/YU27Ztk+YRGxsrWrduLQ1//fXXxfnz56XhOTk5YsmSJdJdk/P+DAwMxMKF
-C0VGRkaFL5NCoRDffPONaNq0qcp4JiYm4ty5c+L9998XhoaGwsPDQwQHBxd65+ayMjc3F76+vnVq
-X9C2bds685nj4uLEkiVLRNu2bVX2MYaGhqJZs2YCgGjTpo1YtGiR2na3f/9+0blzZ2k6uVwuRo0a
-JY4fP17o+/31119i8uTJol27dmr7lN69e4tffvml1pe5t7e3sLOzq1PblLe3d6F3oq+oY5WTk5PQ
-1dVVW6/y/zVu3Fh06dJFjB07VmzatEk8fPiwRPMvzb7/119/FbNmzRJ6enoq+2tvb28RGxsr/v77
-bzFv3jzRvHlzabiurq7w8PAQFy5cEBkZGeLzzz8X7du3V9m23N3dRWBgoPQ+SqVSLF26VOX43KxZ
-M+n44ezsLNq3by+8vb1FaGioyM3NFcHBweLtt98WAISRkZHw8fFR+Zznzp0TDg4OKp/R1tZWZZsu
-7XGwLOcApRUZGSkAiNjY2ApftwIDA4WBgYGQCbZcpRqgSZMm8PX1Van+UJ2/Lo0ZMwYpKSkq7Tfk
-cjkcHR1x6tQpAC97FLG3t0diYqL0C31tkpWVhT/++ANxcXFo2rQpevToodKjSmVIS0tDWFiY1PNV
-QT38ZGRk4Pr160hISICRkRG6d+9eqp6AyloW169fR1xcHIyNjdGzZ0/I5XLExMTAxMRE5e7KFal7
-9+7w8PCQrhDVBSYmJvD29q5Tn1kIgdu3b+PPP/9EXFwclEoljI2N0bVrV3Tq1KlG3tFdUy1YsAAh
-ISEIDg6uU585Kiqqxnd7Xh37/uK8ePEC169fR7169dCnTx+pDeE///yDdu3alfomzjWxLKKiotC9
-e3fExsZWeK2VY8eO4f3332fXzEQlpVAosGzZMixbtky6HPzq8C+++KLOlIeenh6srKyq9D0bNGgg
-9RZXmHr16klV0qqyLPIaX+bXoUMHbjhUbjKZDJ06dVK5IS0RVf++vzhGRkYYNGiQ2uuVfdsCTSyL
-ysQwQ1QCT58+xZgxYxAWFlZg3XEtLS1YWFhI9WCJiIiIqPKxAwCiYpw5cwbdunVDeHh4kb18LFy4
-kIVFRERExDBDVP0UCgUWL14MJycnJCQkqN3fJI9MJoOJiQlGjBjBQiMiIiKqQqxmRlSAR48eYfz4
-8QgLC5P69y+MtrY2vvjii0pryEdEREREDDNEJXLq1CkMHjwYurq6Jbp5lIGBASZNmsSCIyIiIqpi
-/CmZKB8hBPbv3w8AhVYry09XVxdeXl68ISARERERwwxR9ZLJZNi+fTvWr18PLS2tYquO6ejoYMaM
-GSw4IiIiIoYZIs0wZ84cnDlzBo0aNSr0hoe6urr46KOPauUNMYmIiIgYZohqMEdHR4SGhkJbW7vA
-O2wrlUp4enqyoIiIiIgYZog0z6pVq9CsWTO4uLhAW1tbel1XVxeTJ0/Ga6+9xkIiIiIiYpgh0izr
-1q1DQEAA/ve//+Hw4cNYvnw5tLS0IJPJkJ2dDS8vLxYSEREREcMMkWa5cOECPvvsM/j6+sLGxgYy
-mQze3t4IDAyEEAI2Njbo2LEjC4qIiIioGvE+M0SvuH//PsaOHYtp06Zh6tSpKsOGDh2KW7duISsr
-iwVFRERExDBDpDnS09Ph5uYGMzMzrFu3rsBxzMzMWFBEREREDDNEmsXDwwNPnz7F1atXeSNMIiIi
-IoYZopohr8H/r7/+ipYtW7JAiIiIiBhmiDRfXoP/LVu2wMbGhgVCREREVAOwNzOq84pq8E9ERERE
-DDNEGqkkDf6JiIiISDOxmhnVaWzwT0RERFQLwsz333+P77//Hg0aNGCpUIVTKBTIycnB//73Pxgb
-G2vEMrHBPxEREVEtCTMxMTEIDQ2Fl5cXS4UqXFRUFM6fP4/MzEyNWB42+CciIiKqRWEGAJydnbFq
-1SqWClVKmDl+/LhGLAsb/BMRERHVDuwAgOoUNvgnIiIiqj3YAQDVKWzwT0RERMQwQ1TjsME/ERER
-EcMMUY3DBv9EREREtQ/bzFCtxwb/RERERAwzRDUOG/wTERER1V6sZka1Ghv8ExERETHMENU4bPBP
-RERExDBDVOOwwT8RERFR7cc2M1TrsME/EREREcMMUY3DBv9EREREdQermVGtwgb/RERERAwzRDWO
-pjb4X716NQwMDPgFUYWLioqqc5/54cOHWL16NZKTk7kCUKXsr83Nzevc5z527BhWr17NFaAYycnJ
-uH//Ptq1a4eGDRuyQDTkOMUwQ7WCJjb4b9iwIUxMTHDixAloabFGJ1W8Nm3awMjIqE59ZkdHR9y/
-fx8HDhzgCkAVrl27dujZs2ed+sytWrVCmzZtuE29QqlUIi0tTeUvJycHMpkM+vr66NKlCwupBLKz
-s2FqalqptWUYZqjG09QG/xYWFrh37x6/IKIKdObMGRYCUQX66KOP8NFHH9XpMlAoFIiOjkZ4eDgu
-X76My5cv48aNGxBCoHPnznBycoKVlRVsbGwQFRWFhQsX4urVq1x5NATDDNVobPBPREREpfHo0SMp
-tFy+fBnXrhOJlUQAACAASURBVF1DamoqWrZsCWtra4wfPx42Njbo06cPGjdurDLtjRs3WIAMM0QV
-hw3+iYiIqDCpqam4evUqwsPDERYWhvDwcDx69Aj169dH7969YWVlhdmzZ8Pa2hpt27ZlgTHMEFUd
-TW3wT0RERFWvuOpi1tbWWLhwIWxsbNCtWzfI5TwNZpghqiaa2OCfiIiIqk55qosRwwxRtdHUBv9E
-RERUOVhdjBhmqFZgg38iIqLajdXFiGGGai02+CciIqpdWF2MGGaoTjhx4gT27dvHBv9EREQ1FKuL
-EcMM1Um5ubn48ccfsXXrVjb4JyIiqgFYXYwYZojwssF/eno63n77bTb4JyIi0lCsLkYMM0SvyGvw
-r6WlhUmTJrFAiIiINACrixHDDFEJeHh44NmzZ2jQoAEvPxMREVUDVhcjhhmiMli3bh0CAgLw66+/
-YsiQISwQIiKiKlCS6mLW1tawtLRkdTFimCEqyIULF/DZZ59hy5YtbPBPRERUSVhdjBhmiCrY/fv3
-MXbsWEybNo0N/omIiCoIq4sRw0wVCAoKgomJCbp06cJvpw7Ka/BvZmaGdevWsUCIiIjKiNXFiGGm
-iimVSsydOxc2NjbYs2cPv506KK/B/5UrV6Crq8sCISIiKgFWFyOGGQ1w8uRJxMTEIDY2FqtXr8br
-r7/Ob6gOyd/gv2XLliwQIiKiAigUCty4cUPlqgurixHDjAbYsGEDACAnJwe+vr5Yvnx5lb7/qVOn
-4OTkxLWiGrDBPxERUcFYXYyoBoSZO3fuICgoCNra2lAoFNiyZQu+/PJL1KtXr0re/8CBA9i7dy/D
-TDVgg38iIqKXWF2MqIaGGV9fX1hZWeHNN9/E7t27ER8fj71792LatGlVEqSmT58OBwcHrhFVjA3+
-iYiormJ1Mc329OlThISEYPTo0UWOFxMTg3/++Yc/iNflMJOamoqdO3di/fr1UpgBgP/+97+YOnUq
-ZDJZieclhFAbX6lUQktLq8Dxnz17BmdnZyQlJZVqmYUQEEIUOt/yLFNFTfvqfACUqiyrAhv8ExFR
-XcHqYjXLzZs3MW7cOMTFxaFp06aFjrdnzx4cPXqUYaaaaGnCQvj7+0Mul2Ps2LGwtLSEtbU1ACA6
-Ohpnz54tdvrc3FycP38eHh4eMDc3BwAkJiZi7ty5MDQ0hFwuh4WFBU6fPq0y3eXLl2Fra4s7d+4A
-AEJDQ+Hi4gIXFxfMnz9f7X2ys7Ph6+sLa2tr6OvrQ0dHB127doWPjw+ysrIqZJnKO21+V69excSJ
-E2Fvb4/Bgwejbdu26N27N3bs2CGFm+qU1+D/wIEDbPBPRES1SmpqKi5cuAAfHx+4ubmhdevWaN26
-NSZOnIjQ0FD06dMHO3bsQGxsLJ48eYJffvkFX3zxBQYMGMAgoyFsbGygq6uLkJCQIse7cOECHB0d
-WWDVRfwfb29v4ezsLKqaUqkUXbt2FV5eXtJr/v7+AoAAUOwynTp1Sjg5OUnjt2jRQkRHR4uOHTsK
-R0dH4eLiIurXry8ACB0dHfHHH39I0/7111/i9OnTwtjYWAAQtra24vTp0+L06dMiPDxc5X2ePn0q
-+vTpI6ZPny4iIyPFo0ePxKFDh0SLFi0EANG3b1+RlpZW7mUqz7T5bdq0SchkMuHp6SkUCoUQQoi0
-tDRhZ2cnAIgVK1ZU6fccGRkpAIjY2FghhBDnz58XcrlcbN++vUTTGxgYiL179woiIiJNk5ubKyIj
-I4Wfn5+YNm2aMDc3F9ra2kJLS0t06dJFfPDBB2Lz5s0iIiJC5OTksMBqkH79+olPPvlEer53717R
-tm1b6Xl6errQ09MTR44cYWFVscDAQGFgYCCqPcycPXtWyGQycffuXem1zMxMKWAAEDdv3ix2PkOH
-DhUAhL6+vrC0tBQRERHSsD/++ENoa2sLAGLKlClq05qYmAgAYsSIEQXOOzs7W/Tp00eMGjVKKJVK
-lWH79++XltPb27vClqk80z548EAafurUKZVhAQEBAoBo1KiRyMrKqpYwExsbK4yMjIS7u3uJp2eY
-ISIiTfHw4UPxv//9T8yfP1/0799fNGzYUAAQLVu2FCNGjBArVqwQZ86cEUlJSSysGm7x4sWiZ8+e
-hYaZ8+fPC21tbZGQkMDCqqYwU+3VzDZu3AgXFxe0a9dOek1PTw8zZ86Unq9fv77Y+ZiamgIAMjMz
-ERgYCAsLC2lY9+7d0bdvX6kqWWnt3LkTV69exZw5c9TanAwfPhz6+voAgK1btyI3N7dClqk8096+
-fRsKhQIAEBcXpzLM2NgYAJCSkoK7d+9W+fedkZHBBv9ERMTqYlQjODo64o8//kBCQkKBw8+fP4/u
-3bujSZMmLKxqUq0dAMTGxuLw4cM4fvy42rCZM2di5cqVUCgU2LVrF5YvX15k4yttbW21E/b8WrVq
-BQCIj48v9XL6+fkBAMLDwxEdHa02vFmzZnj8+DESEhJw48YNdO/evdzLVJ5p+/Xrh08//RRZWVkY
-OXKkyrD8Yay0nR5UhC+//JIN/omISCOxdzF6lY2NDXR0dBASEgJXV1e14WwvU8fDzJYtW/DGG29g
-0KBBBZ6su7m54cCBA0hPT8f27dvx+eefl/m98nr/EqVs+J6cnIxr165BW1sbT548KXCcMWPGqL1P
-ZS5TcdPK5XJ8++23Kq+lp6cjICAAO3bskF5TKpVV/p0fOXIEFy9eZIN/IiKqduxdjIqjr68Pa2tr
-XLhwQS3MZGRk4PLly/jss89YUHUxzGRkZMDPzw8KhUK6kvGq/FcdNmzYgHnz5lX5ryB3796FEAJK
-pRJr1qxRuWJSE9y7dw/r16/HrVu3MHXqVCxZsqRauw5csWIFbGxsuOUREVGV4s0oqawcHBxw9OhR
-tdcvX76M3Nxc2Nvbs5DqYpgJCAhAamoqfHx8iryasWLFCjx9+hQPHjzAoUOHVK6CVIW0tDQAL6+A
-3L9/H+3bt68RX2xaWhoWLFgAf39/+Pr6Ys2aNZDJZLhw4UK1Ltft27dx//59HiiIiKjSsLoYVSRH
-R0csX74ciYmJKq+zvUwdDjNCCGzYsAFjxozB3Llzixw3Pj4eX331FYCXN9Gs6jBTv3596XFISEiN
-CDNJSUlwdHREREQEgoKCMGTIEI1Ztl69esHExASTJk2Cn58f280QEVG5sboYVaa8djPBwcEqr7O9
-jGaolt7MLl68iIiICEyfPr3YcWfOnAkdHR0AwKVLlxAeHl6ly2pqaio1mvfz8yuyfUtqaqpKL2zV
-ZeXKlYiIiICJiYlGBRkAcHZ2BgD88MMPePPNN3HixAluhUREVGLsXYyqWv52M3ny2ss4ODiwgOpi
-mFm9ejXMzMxKVMewZcuWGD16tPR87dq1ZXrPokJIXljJzs5WG9aoUSNYW1sDAIKDg7Fnz54C55Gb
-m4spU6aUqj1KWRr+l2TavN7h9PT01Ibl5ORU+0oXFRUF4GV7JGdnZ4wcORL//PMPt0YiIlKhUCgQ
-FRWF7du3Y/r06VKVngEDBmD37t1o0qQJFi5ciIiICCQlJeHixYv49ttvMWbMGFZnpgrl4OCA8+fP
-S8/DwsLYXqauhpkrV64gKCgIY8aMUbtnS2Hee+896fGBAwfw999/F7jDK0reSXxBISCvy+fbt29L
-w7Ozs/H48WMAgKenpzTutGnTsH79emRlZUmv3blzBy4uLsjOzoabm1uFLFN5ps3rpezOnTv4888/
-pdczMzOxe/dulV8VyhuqyqJbt2745JNPYGBgAF1dXcTExKBbt2746quvpGUiIiLNdP36ddy5c6dS
-5v3o0SMcPHgQXl5ecHBwQJMmTdC9e3csWrQIL168wPjx43Hy5EkkJCQgOjoaO3bsgLu7OywsLNju
-hSpV3v1m0tPTAbysYtajRw+2l6lrYSYzMxOzZs0CgFLtdPLfUFOhUGDevHlq3QrnDzjPnz9XGSaE
-kE7qk5KSkJycrDLc1tZWmsf8+fNx8OBBvPPOO/j3338BAOPGjcO4ceOkEOHp6YnmzZujR48eMDU1
-hZmZGZKSkuDv768S0MqzTOWZNu/qkBACgwYNwsKFCzF79mz06NEDXbt2lcZbtWoVlixZgh9++KHK
-V7wlS5ZAX18fPXr0wN27dzFr1ixs3rwZXbp0waFDh7hlEhFpmN9//x0jR45Er169EBAQUO75sboY
-1SR57WZu3rwphRlWMdMQ4v94e3sLZ2dnUVn2798vOnfuLAAIAEIul4tRo0aJ48ePFzrNX3/9JSZP
-nizatWsnTZf317t3b/HLL7+I0NBQMX78eJVhXbp0EV9++aUQQoiTJ08KJycnleE9e/YU27Ztk94n
-NjZWtG7dWhr++uuvi/Pnz6ssS05OjliyZIlo1KiRyrwMDAzEwoULRUZGhjRueZapIj5PUlKScHBw
-UBnH2dlZxMTECIVCIczNzaXXR40aJdLT00Vli4yMFABEbGys9NquXbuEvr6+mDx5sqhfv744dOiQ
-mDt3rpDL5WLIkCHi1q1b0rgGBgZi7969goiIqtaVK1eEq6urkMlkwsnJSYSEhJR6Hrm5uSIyMlL4
-+fmJadOmCXNzc6GtrS20tLREly5dxAcffCA2b94sIiIiRE5ODgudNFK/fv3EsGHDRJs2bYSenp44
-cuQIC6UaBQYGCgMDAyET/1fHaMGCBYiKikJgYGCdDHVpaWkICwuDnp4eLC0tC2xvArysmnX9+nUk
-JCTAyMgI3bt3L3Tcag6piIyMxJMnT/Dmm2/CxMREGpaSkoLQ0FA0b94cPXv2LHF1v/KIiopC9+7d
-ERsbK9VjFkLA3t4eTZo0QYcOHeDn54fDhw+jRYsWmDNnDkJDQ/HJJ5/gyy+/ROvWreHr66tS5ZCI
-iCpPeHg4vv76axw7dgxDhgzB4sWLpZoMxSmudzErKyv2LkY1zpIlS+Dv74/U1FTEx8cjLi6O1cyq
-0bFjx/D++++DFUz/T4MGDTBgwIBix6tXr16Jd+bVSSaToUePHujRo4fasEaNGlXrjTPzL+PGjRvR
-p08f/PLLLwCAESNG4PDhwzh//jwCAgLw6aefwt/fXyM6LiAiqgvCwsLw9ddfIygoCMOGDUNYWJjU
-EU5BeDNKqivy7jfToEEDtpfRIAwzVK0sLCwwY8YMzJs3D5GRkSqB5t1334Wrqyu+/vprfPPNN1i+
-fLlaux8iIqoYv/32G77++mucPn0azs7OCA8Ph6Wlpco4vBkl1WXW1taQy+VISUlhexmGGaL/b9my
-Zfj555/x7bffSl1v5wWagQMHwsfHB1u2bIFcLoeFhQXmzJmDxYsX8xcRIqIKEBwcjKVLl+LcuXNw
-dXXFlStX0Lt3bwBFVxezsrLizSipTqlXrx7Mzc1x7do1hhmGGaL/z9DQECtXroSnpycmT55cYKDR
-0tKCt7c39PX1MW/ePAQEBGD9+vUq9yAiIqKS+/XXX7F06VJcuHABI0eOREhICLKzs3H27FmsWLGC
-1cWICtC8eXMA4P1lGGaIVH344YfYunUrPv30Uxw4cEAt0ORxc3PD0KFDsXLlSrXuuYmIqHjnz5/H
-0qVLERwcjF69emHUqFG4c+cO+vXrx+piRMXw9vbGixcvWDuEYYZIlZaWFjZs2IC+ffvi1KlTcHJy
-Ugk0+Xtcq1evHpYtW8ZCIyIqhb1792LChAkAAG1tbSiVSsTGxsLIyAgjR47E2rVrWV2MqBjW1tYY
-PHgwC4JhhkidjY0NPvzwQ3h6eiIyMhI6OjpSoFm/fr10o9Ca4s8//8TEiRPRrFkzaGlp8QumCvf8
-+XMsX74crq6udeYzv/POO3j48CFPuEshOTkZMTEx0o2ggZcN+QHgxYsXCAoKQlBQEJYtWwaZTCZd
-hcn7r6Ojo/JcLpdDJpNBW1sbLVq0gKGhYa0pq3///RdvvfUWNmzYUGfWj++//x7r16+HsbExN5YS
-ysrKwqBBg1gQJZCdnY309HQcO3as0tYxhhnSKCtXroSZmRnWrVuHzz77DDKZDGvXrsWWLVuwZs0a
-vP322xg4cGCN+CyJiYm4fv063N3dYWBgwC+XKtzq1avx8OHDOvWZDx48iMaNG8PDw4MrQCk4OjpK
-ISYnJ0f6r1QqkZ2drfZfCIGsrCzpf94JHABkZmZK/9u3b4+OHTvWqm0qOzu7Tq0bMTExiIyMhJeX
-FzcUqnBRUVG4ePGitN9gmKFaz8jICEuXLsWXX36Jd999F61atYJMJoO+vj5sbW1VOgWoKVatWsUw
-Q5Xi+PHjde4zt23bFt7e3gwzVClkMhlCQkLq3Od2dnbGqlWruAJQpYSZyj5Wse4LaZzZs2ejQ4cO
-mD9/vsrrEyZMwPTp0zFixAicOXOGBUVERERUxzHMkMbR1tbG+vXrERAQgODgYOn1vCpnDDRERERE
-BLCaGWkoe3t7zJw5E8+ePVN5PS/QAKiRVc6IiIiIiGGG6gBfX98CX2egISIiIiKGGaqxGGiIiIiI
-iGGGGGiIiIiIiGGGiIGGiIiIiBhmiBhoiIiIiIhhhhhoiIiIiIhhhoiBhoiIiIgYZogYaIiIiIiI
-YYaIgYaIiIiIYYaIgYaIiIiIGGaIGGiIiIiIiGGGiIGGiIiIiBhmiIGGiIiIiBhmiBhoiIiIiIhh
-hoiBhoiIiIgYZogYaIiIiIgYZogYaIiIiIiIYYaIgYaIiIiIGGaIGGiIiIiIGGaIGGiIiIiIiGGG
-iIGGiIiIiBhmiBhoiIiIiIhhhoiBhoiIiIhhhoiBhoiIiIiqNcxcuHABZ86cYalQhYuKimKgISIi
-IqLKCzNpaWkYNGgQS4XqPAYaIiIiohoUZv7zn//gP//5D0uEiIGGiIiIqGaFGSJioCmMEALh4eE4
-ceIEnj17BmNjY1haWuLtt99GvXr1kJiYiJ9//hnTpk2Tpnnw4AGSkpLK/J6GhoZ47bXXih0vKysL
-ISEhuHr1Kh49egSFQgFDQ0N06NABNjY26NixI2QyGZ48eYJTp05h8uTJXLGpWgUFBcHExARdunTR
-mGV69uwZAgMDce7cOezdu1dl2L179+Dh4QEDAwNs3boVBgYG/BKpytbLFy9eFDq8adOmaNWqVYHH
-rOjo6AKnad++PRo0aFBh63ZR2w4xzBAx0GiAFy9eYNKkSThx4gSaN28OW1tb3L9/H76+vsjKyoKL
-iwsePnwIuVyuEmb+/PNPBAYG4qeffkJCQoLKPLW0tCCTyaTnSqUSQgiVcT7++GOp3Avy77//wsfH
-B9u2bUNCQgKaNGkCS0tLGBsb48GDB9i+fTuePHkCU1NT2NnZISwsDD179mSYoWqlVCoxd+5c2NjY
-YM+ePdW+PFu3bsX27dtx7do1CCFgaGioNs6aNWtw4sQJAICtrS08PT35RVKV+Oeff+Dn54ddu3ap
-HCM6deqE8ePHo1+/foWGmaCgIPz22284fPgwAMDAwACzZs3CRx99JIWZ8qzbJdl2qIoIohrAwMBA
-7N27t1qXQalUCk9PT1G/fn1x+vTpYscPDg4WAERiYmKNLfeMjAxhYWEhAIjJkyeLjIwMaVh2drbY
-vHmzqFevngAgOnfuXOA8QkJCBADpLyQkpMDxsrKyxO3bt8WSJUsEADFr1qxCl+vEiRPC2NhYABAt
-W7YUe/bsEdnZ2SrjKBQKcfToUfHGG29I7+3q6lqrtgtzc3Ph6+tbp/YFbdu2rdGf+fjx4wKA0NHR
-EY8ePar25VEqlSIpKUl07dpVABCGhoZq42zbtk0AEDKZTJw9e7ZWr1/e3t7Czs6uTm1T3t7ewtnZ
-WaOX0cfHR+U48tNPP5V42i5duggA4sSJExW6bpdk2yEhIiMjBQARGxtb4fMODAwUBgYGQotxjqh0
-V2imT5+OESNG1Ime/7Zt24br16+jSZMm2Lx5M/T19aVhOjo6cHd3x5kzZ1CvXj08evSowHlYWVmp
-PC/oVzQA0NXVRceOHfHVV19h8uTJyMnJKXC8H3/8EcOGDcPz58/RtWtXREREYMKECdDR0VG7+uPi
-4oJr167BxsYGAJCens4VmarVhg0bAAA5OTnw9fXViP1a48aN0b1790LHmT59Oi5fvoyoqCi8/fbb
-/BKpys2bNw9vvvmm9DwkJKSkP9gjLi4OdnZ2GDx4cIWu2yXZdqhqMMwQMdAU6siRIwAAU1NT1KtX
-r8Bx3nrrLXzzzTdISUlBSkqK2nAdHR1oaZVuVzNu3DhkZ2ervX716lVMmTIFSqUSDRs2xNGjR9Gy
-Zcsi59WkSRMcOXIERkZGSEtL40pM1ebOnTsICgqCtrY2AGDLli3IyMjQjJOBYrZRKysrdO3alV8i
-VQu5XI7FixdLz/39/Uu0Pw8PD8fz58/x0UcfVdq6XdrjGzHMEDHQVKHHjx9LJ2FFXdWYPn06WrRo
-IY1fUJmVhqOjI5YuXarymlKpxIwZM6QrNvPnz0f79u1LND8jIyN4eXnxygxVK19fX1hZWWHChAkA
-gPj4eDYYJiqh0aNHw8TEBACQlJSEHTt2FDvN999/j+bNm2PkyJEsQIYZIqqLgaZJkyYAgOTkZCxY
-sKDQ8XR1dTFp0iT8+++/5X7PFy9eQF9fXzpo5Tlx4gQiIiIAANra2nB3dy/VfCdNmoSsrCyuvFQt
-UlNTsXPnTsyePRuzZ8+WXv/vf/+r1vlFVRBCQKlUlmm6kirL/IkKI5fL8fHHH0vP165dC4VCUej4
-KSkp+PHHHzF58mTo6elV2Lpd1m2nPNNyW2KYIWKgKaP8N9Fdv349Pv744wKrfwGAj48PbG1ty/V+
-SqWy0J7ifvzxR+mxra0tjIyMSjVvIyMj7Ny5kysuVQt/f3/I5XKMHTsWlpaWsLa2BgBER0fj7Nmz
-RU67f/9+jB8/Hi4uLnBxcVGpbpOUlIS5c+di+PDh0vBXr2rmd+zYMQwcOBCvvfYaOnTogJ49e+LA
-gQNFvn9KSgp++OEHDB48GOvWrSvyRC0wMBDDhw+Hqakp2rdvj8aNG6N///7w8/MrtB0cUUlNnTpV
-6j757t27Uk9lhR0z0tLSMH369HKv22XddgAgOzsbvr6+sLa2hr6+PnR0dNC1a1f4+PgU+gMbt6XS
-p0Qi9mZWCb2c1YbezOLi4sRrr72m0ouMhYWFCA8PL9V8tLW1penv3r1b6HghISHCxMSkwGGtWrWS
-5uHp6cmNgr2Z1RhKpVJ07dpVeHl5Sa/5+/tL63NJepK6d++ekMvlAoAYPHiw2vDo6GhpOytofgqF
-QsyePVvI5XKxZcsWqfe/6OhoYWFhIRo1aqTWI1N0dLQYO3as0NfXl5b1m2++KXD50tPTxejRo4We
-np7YvXu3yMnJEUIIcfv2bdG3b18BQPTo0aNSejRib2a1vzez/D7//HNpfezbt2+h21zPnj1Fv379
-ChxemnW7LNtOnqdPn4o+ffqI6dOni8jISPHo0SNx6NAh0aJFC2n509LSauW2VJW9mTHMEMNMJQWa
-2hBmhBDi999/F82bN1cJNADExIkTxcOHD0sdZg4ePChCQ0NV/n799VexZcsW0a5duwLDTHJyssp7
-r1mzhhsFw0yNcfbsWSGTyVSCfGZmptS9OABx8+bNYudjampaaJgRQggTE5NCw8yiRYsK3XYeP34s
-GjRooHZClpqaKjIzM8Xu3buLPOFTKpVi7NixAkCB301KSoro3LmzACA6deokUlJSGGYYZsrswYMH
-UrAHIMLCwtTGuXLligAg/P39C5xHSdftsm47Qry8fUGfPn3EqFGjhFKpVBm2f/9+6X29vb1r5bZU
-lWGG1cyIWOWsSD179sS1a9fUuq3cs2cPOnfujG3btpWqHr2bmxtsbW1V/vr37w93d3fcu3evwGni
-4uJUnjds2JArHdUYGzduhIuLC9q1aye9pqenh5kzZ6pU4yyOXC4v0/C//voLK1euhKGhYYG9Or32
-2msYMGCA2usNGjSAnp4e7O3ti3zfoKAg7N+/H02bNsXUqVPVhjds2BA+Pj4AgFu3buE///kPVwoq
-s9atW2PcuHHS8++++05tnK1bt6Jp06Z45513CpxHSdftsm47ALBz505cvXoVc+bMUesEZ/jw4dKt
-DrZu3Yrc3FxuS+XAMENUSYHm6tWrteaztW3bFmfOnMG+ffvwxhtvSK+npqZi5syZRd4X5lU3b95E
-RkaG9Jeeno6kpCRcvXoVffv2LdE8imr0SaRJYmNjcfjwYZVG/3lmzpwpddO8a9cuJCQkVMoyrFu3
-DgqFAgMHDoSurm6B4zRq1KjQ6V+9h9Or8u6XY2VlVej8hw0bBmNjY7WTN6Ky+OSTT6THP//8M2Jj
-Y6XnycnJ+OmnnzBx4kSVe6OVZd0uz7bj5+cH4GX30Bs3blT58/PzQ7NmzQAACQkJuHHjBrclhhki
-zQs0RfX+VVM/29ixY3Hjxg0sXbpU5VfgPXv2YPLkySW6QqOnpwd9fX3pr169emjcuDF69+6NzZs3
-FzhN06ZNVZ6/eqWGSFNt2bIFb7zxhkpnGnlatWoFNzc3AC9v6Lp9+/YKf38hhNRIunPnzhU+f6VS
-iQsXLgAAmjdvXuh42tra6N+/P4CXXVJHR0dz5aAy69WrFxwcHKR1MP+VzZI0/K/sbSc5ORnXrl2D
-trY2njx5gpiYGLW/MWPGwNPTE56entDS0uK2VA5ybhJElRNoHj9+XKKeTmoaPT09LF68GEOGDMGI
-ESPw9OlTAMBPP/2EUaNGYcyYMWWed7du3dCqVSu115s0aQJjY2M8f/4cABATE8MVjTReRkYG/Pz8
-oFAoCr1LeHx8vPR4w4YNmDdvXrHVyUrjxYsX0jZa1NWXsoqPj5duXljcL8SdOnWSHj98+BA9evTg
-SkJl9umnn0on/35+fliyZAkaNWqErVu3wtbWFt26dau2befu3btSN8xr1qyRrsAW937clhhmiDQq
-0MyZM6dGh5nU1FQ0aNCg0BteWllZITg4GLa2ttKVEl9f33KFGZlMht9++63AYXZ2djh48CAAIDQ0
-lCsZDE9QJwAAGAdJREFUabyAgACkpqbCx8enyLuEr1ixAk+fPsWDBw9w6NChcm1Dr8p/FTMzM7PC
-P2P+Kp95J36FMTQ0lB6X5OSOqCjDhg1Dp06dcOvWLaSkpGD79u2wt7fH9evXK6Qb/vJsO3mhRAiB
-+/fvl+gGz9yWGGaINDLQ1GTu7u6YNWsW3nrrrULH6dChA3x8fPDhhx8CAP74448KXYaHDx/CyMgI
-enp6GDt2rBRm7ty5g6ioKJibm3NFI40khMCGDRswZswYzJ07t8hx4+Pj8dVXXwF4eRPNigwz+W8W
-+Pfff1f452zevDl0dHSQk5OD6OhoCCEK3fflv/Ff/rZ3RGWhpaWFTz75ROpIY926dYiMjETjxo0r
-ZBsqz7ZTv3596XFISEiJwgy3pXKsC9wciKiwoLJ8+fJix8t/o8yS3GW5pJKSkmBpaSldbndzc1M5
-IBTUgw2Rprh48SIiIiJKVG9/5syZUkPkS5cuITw8vMwB6lWtW7eW5n3hwoVS9TxYEnK5XLoBaFxc
-nNSQuSBPnjwB8LKtUMeOHbmSULlNnDhRal9y//597N69GxMmTECDBg3KPe/ybDumpqZSEPHz8yty
-2ryOdLgtMcwQUSWEmaCgoCLvsAy8bBeQx8bGpsQnWcVZtGgROnfuLB2UdHR0sGnTJmn4rl27cPr0
-6RLPLzExEa6urnj27Bm/XKp0q1evhpmZWbFdvwJAy5YtMXr0aOn52rVrCxwvrzpJenp6gdtYSkqK
-2ut6enpSY+G7d+8iKCioyG20oG21uO33gw8+kB4HBAQUOl5eSHN3d6/xV65JM9SrVw+zZs1Sea00
-Df+LWrfLs+00atRICibBwcHYs2dPgdPm5uZiypQpcHJy4rbEMENElRFm8nauRf1ClL9dUP7uMvNk
-ZmaqXBIv7sQor3rOhg0b1HqAGjp0KNasWSM9d3NzQ2BgYLGfJTQ0FJaWlujXrx9atGjBL5cq1ZUr
-VxAUFIQxY8aU+ETjvffeU9mmCqrWkndl8vLly7h9+7b0ukKhwIoVK6SQk79TAQCYN2+e9NjDwwMP
-Hz5UC/ohISEAXvbClJqaqjI8f7frBTVMnjRpEiwtLQEAmzdvRmJioto4t2/fRnBwMMzMzFSWh6i8
-Zs2aJdUK6NOnDywsLEo8bXHrdnm2HU9PT+nxtGnTsH79emRlZUmv3blzBy4uLsjOzpZ6NeS2xDBD
-RJUQZhISEmBnZ4effvpJpYGiUqnEjh07pBt4LV++vMBfoV8NGzt27EBYWBhiYmJw79493L17Fzdv
-3sTFixexadMm2NvbS20MBg4cqDa/Tz75BPv27UOzZs2QmpoKV1dXuLm54eTJkyq/WKempiIoKAjv
-vPMOXFxcsGzZMnz++ef8YqlSZWZmSr8Ul6ZXsvw31FQoFJg3b57KjwB5PywAQHZ2Nuzs7ODl5QVv
-b2+Ym5tDCCF1VRsWFob3338fx44dA/CyobSHhweAl1VxevXqhRUrViAwMBDbtm2Do6MjDAwMpBO6
-7t27q9zQM/+PGbdu3VJbdrlcjkOHDqFTp06Ij4/HhAkTpAbQefuQiRMnok2bNggMDKyQKkBEeVq0
-aIGJEycCAGbMmFGqaYtbt8uz7YwbN066uWdOTg48PT3RvHlz9OjRA6ampjAzM0NSUhL8/f2lHz24
-LZWRIKoBDAwMxN69e2vUMgcHBwsAIjExsUaWuVKpFAYGBmLJkiXCy8tLmJmZiRYtWoghQ4YIV1dX
-0bZtWwFAmJqaip9//lltej8/PzFgwAChra0tAJT6z8DAQOTm5ha6fHFxcWLJkiXScgAQMplMGBoa
-imbNmgkAok2bNmLRokUiLi6uVm4X5ubmwtfXt07tC9q2bauxn3n//v2ic+fO0vool8vFqFGjxPHj
-xwud5q+//hKTJ08W7dq1U9sGevfuLX755ReVbXLp0qVCLpdL4zRr1kxs27ZNCCGEs7OzaN++vfD2
-9hahoaEq249CoRDffPONaNq0qcp7mJiYiHPnzon33/9/7d1/dNV1/cDxF9vdxgZzTn4VET/q2DIC
-A9EgEaxOBxI9kOmRUA6dOqEQET+UMDrQOXKC6mQHS4qAlHM8mgdPHTMMzBN4GHFU1CUJyVkonFJ+
-jDMYsrGN7dMfftnXxa8pG9y7PR5/7W73fnbv+3Mv7LnPfX12e9KtW7dk2rRpyebNm5OGhoZk06ZN
-yYwZM5Lu3bs3e41NnDgxeeyxx055LEeOHElmz56dFBYWJr17906mTp2afOMb30j69euX3HXXXRnx
-Opw/f34ycuTIDvWamj9/fjJu3LiMfgw7duxICgsLk6qqqhZd//08tz/Ia+ek+vr6ZNGiRUlhYeEp
-/7/94Ac/SGpqak57/9rDa+mkV199NYmIZM+ePa2+7T/96U9JUVFR0ilp7WlAaAOXXnppLF++vNlb
-MdJdaWlpXHfddXH48OGm39xkmqeffjpuuOGGk7/4iF27dkVZWVkcOnQo8vPzY9CgQTF06NCznnb2
-AvxCJnbt2hX/+Mc/oqKiIhobG6Nnz54xcODAKCkpadfvJx48eHBMmzat6TeHHUG/fv1i/vz5Heox
-/6+DBw9GWVlZ5Ofnx7Bhw5r+yvnu3bujf//+Z3091tbWRllZWVRUVETPnj1jyJAhkUqlory8PPr1
-63fOv4jeErW1tfH3v/89Kioqori4OK688spmZ3dKZ/fee2+UlpbG5s2bO8zz6d57743t27e36C27
-6ezll1+OoUOHttn2z+e1U1NTE2VlZVFZWRk9evSIwYMHt+iEOZn8Wjpp+/btMXjw4NizZ0/07du3
-Vbe9bt26uP32252aGTizkyET8e6ppktKSpr9sa50kK73C9pKjx49Tpkni2jZKVrz8vKaBpPf6+Tb
-SltDXl5eXHPNNXYUF1Rbhsz5vnby8/ObnfnTa6l1mZkBAADEDAAAgJgBAAAQMwAAgJgBAAAQMwAA
-AGIGAAAQMwAAAGIGAABAzAAAAIgZAABAzAAAAIgZAAAAMQMAAIgZAAAAMQMAACBmAAAAMQMAACBm
-AAAAxAwAAICYAQAAxAwAAICYAQAAEDMAAICYAQAAEDMAAABiBgAAEDMAAABiBgAAQMwAAACIGQAA
-QMwAAACIGQAAADEDAACIGQAAgDSTsgTQttauXRtFRUUWgla3ffv2DveYKyoqYu3atdG9e/cO85gb
-Ghri+PHj0aVLF096/163iXXr1sXatWs9AVqguro68vPzo1OnThYjTf6fEjPQVi+u1Lsvr9mzZ0dO
-To4FoU3k5eV1qMdbVFQUGzdujLKysg7zmOvq6qK6ujry8vKic+fOfohqQ5WVlTF69OgO9Zjz8/Mj
-IuLOO+/0BDiH2traqKmpiYKCgsjNzbUgLXDkyJGIiMjKars3g4kZaCPDhw+PJEksBLSit956q8M9
-5rq6uli1alUsXbo0qqqqYubMmTFr1qwoLi72hOC8LVy4MBYuXGghzmL9+vUxd+7c2Lt3b9x3330x
-Z86cpgjk4jMzAwBpLDc3N6ZPnx7l5eXxox/9KB566KEYMGBALFq0KCorKy0QtJHy8vIYP358jBs3
-LoYPHx67du2KBQsWCBkxAwCIGkhPhw8fjrvvvjsGDhwYVVVVsW3btli9enV8+MMftjhiBgAQNZB+
-Tpw4EcuXL4/LL7881q5dG2vWrImNGzfGkCFDLI6YAQBEDaSn9evXx5VXXhnf+973YtasWfHPf/4z
-Jk6caGHEDAAgaiA9mYsRMwCAqIGMYi5GzAAAogYyirkYMQMAiBrIOOZixAwAIGogo5iLETMAQDuN
-moULF4oa2iVzMWIGAGjnUfPwww+LGtoVczFiBgAQNZBxzMWIGQBA1IgaMkp5eXlMmDDBXIyYAQBE
-jaghM7x3LubIkSPmYsQMACBqRA3pzVwMYgYAEDVkHHMxiBkAQNSQUczFIGYAAFFDRjEXg5gBAFo9
-apYsWSJqaDPmYhAzAECbRc20adNEDW3CXAwt1SlJksQykPZP1E6dYvDgwTFp0iSLAZCGGhoa4sUX
-X4yNGzdGbW1tXHvttTFy5EjzDLwvhw4dinXr1sXOnTvjqquuijFjxkRhYaGF4RTr1q2LzZs3ixky
-wzXXXBNVVVXRtWtXiwGQxpIkiYqKiti3b180NDREz549o1evXpGdnW1xOGsMv/3223HgwIHo2rVr
-9OnTJwoKCiwMZ1RdXR1du3YVMwBA66urq4vVq1fHkiVLoqqqKmbOnBmzZ8+O4uJii0OTEydOxG9+
-85tYtGhRFBQUxI9//GNvJ+N9ETMAgKjhglu/fn3MnTs39u7dG/Pnz485c+Z4WyJiBgAQNaSv8vLy
-uPvuu+Opp56Kr3/967F48WKnWeYDczYzAKDNOfsZ/l4MbcGRGQDggnOkpuMwF4OYAQBEDRnHXAxi
-BgAQNWQUczFcKGZmAICLzkxN+2AuhgvNkRkAIO04UpNZzMUgZgAARE3GMReDmAEAEDUZxVwM6cDM
-DACQ9szUpA9zMaQTR2YAgIzjSM2FZy4GMQMAIGoyjrkYxAwAgKjJKOZiSHdmZgCAjGempnWZiyFT
-ODIDALQ7jtR8MP87F7N06dL42te+ZmEQMwAAoiZ9mYtBzAAAiJqMYi6GTGZmBgBo98zUnMpcDO2B
-IzMAQIfTHo/UvPnmm/Hmm2/G9ddff9brmYtBzAAAdPCoOXbsWDz77LMxfvz4i/44du3aFSUlJU2P
-KScn57TXMxdDe+NtZgBAh3U+bz/75S9/GRMmTIilS5de1Mewc+fOuPbaayM7OzuysrLigQceOOU6
-5eXlMWHChBg3blwMHz48du3aFQsWLBAyZDxHZgAA/k9Lj9QcO3YsPvrRj0ZlZWVkZ2fHlClTYsWK
-FZFKpS7o/S0rK4svfOELcfTo0Thx4kRERHTp0iXeeOON6NGjRxw+fDgWL14cv/jFL+Jzn/tc3H//
-/TFkyBA7GjEDANBRo+anP/1pLFiwIOrr6yMiIicnJ0aOHBl/+MMfoqio6ILcx5deeik+//nPR3V1
-dTQ0NDR9Pjc3NyZNmhRXX321uRjEDACAqPn/qLnzzjtj0KBBp7wNLTc3NwYMGBDPPPNM9O3bt03v
-15YtW2LMmDFx/PjxZiHzXgUFBfH973/fXAxiBgBA1LwbNQcPHoz6+vrTRkROTk5ccsklsWHDhrjq
-qqva5L5s2rQpvvzlL0ddXV00Njae9jpZWVkxZMiQ2LZtm52HmAEAIKKysjL69OkT1dXVZ7xOdnZ2
-pFKpePzxx1v9TGcbNmyI8ePHR319/RlD5r1B87vf/S5uvfVWO452y9nMAABaaNWqVU1zMmfS0NAQ
-dXV1cfPNN8eyZcta7Xs/9dRTceONN571iMx7JUkS3/3ud+P48eN2HGIGAKAjO3bsWCxZsuScMXMy
-JBobG2POnDnx7W9/+4xzLS31xBNPxM033xwnTpyIlr6pJkmSePvtty/6qaNBzAAAXGTLli2Lo0eP
-vq/bNDY2xsqVK+Omm26Kd9555wN930ceeSRuu+229xVEeXl50alTp4iIeO2118JUAe2VmRkAgHOo
-qamJgoKCiHj3rGV1dXXv6/a5ubnxiU98IjZs2BC9e/du8e1Wr14dU6dObdF8TCqVirq6uhgwYEBM
-mDAhxo4dG6NGjYrOnTvbgYgZAICObN++fbF169bYunVrPPfcc1FWVhZ1dXWRl5fXooH8nJycKC4u
-jmeffTYGDRp0zu/34IMPxne+850zHlXJy8uLurq6yM3NjS9+8Ytx0003xdixY6N///52FmIGAIAz
-q6+vj5dffjmef/75+Nvf/habNm2K/fv3RyqViuzs7KitrT3lNllZWZGXlxe///3vY+zYsWfc9s9+
-9rOYN29es0By9AXEDABAm/nPf/4TL7zwQmzZsiU2bdoUr776atTX10fnzp2jtra22VGWX/3qV3HX
-XXedso377rsvFi5cGBHvnua5sbHR0RcQMwAAF1ZdXV288sorsXXr1ti8eXOUlpbGgQMHmr7+pS99
-KdavXx9ZWe+ek2natGnx61//OiIi+vfvH1/5ylccfQExAwBcKPv27Ys//vGPFuIMDh8+HP/617/i
-6aefjoaGhujbt2/ccccdsX79+vj3v/8dH/rQh2L06NHRrVs3i3UWI0eOjE996lMWQsyIGQCg9ZSW
-lsZ1110XvXr1ii5duliQczj5N2mysrKaTqfM2e3evTuWL18e06ZNsxgdXMoSAABt4fXXX4+ioiIL
-QasbPHiwRSAi/NFMAABAzAAAAIgZAAAAMQMAAIgZAAAAMQMAACBmAAAAMQMAACBmAAAAxAwAAICY
-AQAAxAwAAICYAQAAEDMAAICYAQAAEDMAAABiBgAAEDMAAABiBgAAQMwAAACIGQAAQMwAAACIGQAA
-ADEDAACIGQAAADEDAAAgZgAAADEDAAAgZgAAAMQMAACAmAEAANqBlCUAADh/VVVVsXfv3vP7wSyV
-ik9+8pOxf//+OHjw4BmvV1xcHB/5yEdO+XySJPHaa6+d9jYDBgyILl262FGIGQAAmvvLX/4St9xy
-y3lto2fPnrF///7YvXt3rFy5Mh5++OFIkqTp6yUlJTFx4sQYNWrUGWPmz3/+c2zZsiWefPLJiIgo
-KiqK6dOnx4wZM8QMYgYAgFPV1NRERETv3r1jwYIF8dnPfjYuu+yySKVSUVpaGpMmTYqIiI997GPx
-3HPPRZIkcfz48XjrrbfiySefjGXLljVtY8SIETFixIi44oorYt68eU3f44c//GFMnDjxjPchKysr
-7rnnnrjnnnti4MCBsWPHjnj88cdjzJgxdhBiBgCA06uuro6cnJz461//GiUlJc2+1qNHj6aPc3Jy
-ok+fPk2XL7/88hg9enRceumlsXjx4ma3mz17djz00EOxc+fOiIgoLS09a8yclCRJVFRUxMiRI4UM
-7ZoTAAAAtIKampoYP378KSHTUjNmzIjGxsZoaGho+lwqlYqFCxc2XX7kkUfi2LFj59zWCy+8EAcO
-HIgZM2bYMYgZAADOHTPjxo37wLe/7LLLYtiwYXH8+PFmn7/llluiX79+ERFx5MiR+O1vf3vOba1e
-vTq6d+8eEyZMsGMQMwAAnN28efNiypQp57WNLVu2REFBQbPPpVKpmDVrVtPln//8582O3vyvo0eP
-xqOPPhpTpkyJvLw8OwYxAwDAOX6oysqKTp06ndc2srOzT7uNb37zm1FUVBQREW+88UbTmcpO59FH
-H41jx47Ft771LTsFMQMAwMVVWFgYU6dObbp8//33n/Z6SZLEihUrYtSoUR94dgfEDAAArWrmzJmR
-Sr17ItotW7bE888/f8p1XnrppXjllVeahQ+IGQAALqo+ffrEbbfd1nT5dEdnVqxYEcXFxfHVr37V
-giFmAABIH3PmzGn6+Iknnog9e/Y0Xa6qqorHHnssJk+eHJ07d7ZYiBkAANLH0KFD4/rrr4+IiMbG
-xnjggQeavmbwHzEDAEBamzt3btPHK1eujKqqqqbB/xEjRsSnP/1pi4SYAQAg/dxwww1NZyo7evRo
-rFq1KrZt2xZlZWUG/xEzAACk8Q9vWVnNZmeWLVsWDz74YFxyySVx6623WiDEDAAA6Wvy5MnRvXv3
-iIjYu3dvrFmzJu64447o0qWLxUHMAADQehobG1t1e/n5+TF9+vRmnzP4j5gBAKDVvfPOO00f19TU
-tMo2p0+fHnl5eRERMWzYsPjMZz5joREzAAC0rmeeeabp471798aOHTvOe5u9evWKyZMnR0QY/EfM
-AADQeg4dOhRTpkyJIUOGxIoVK5p97eqrr44bb7wxfvKTn5zX95gzZ04UFhbGxIkTLTgdUsoSAAC0
-vm7dusWaNWva9HtcccUVsWnTpigsLLTgdEiOzAAAZLChQ4daBMQMAACAmAEAABAzAAAAYgYAABAz
-AAAAYgYAAEDMAAAAYgYAAEDMAAAAiBkAAEDMAAAAiBkAAAAxAwAAIGYAAAAxAwAAIGYAAADEDAAA
-IGYAAADEDAAAgJgBAADEjCUAAADEDAAAgJgBAAAQMwAAgJgBAAAQMwAAAGIGAAAQMwAAAGIGAABA
-zAAAAIgZAABAzAAAAIgZAAAAMQMAAIgZAACA9JCyBABAW+jVq1cUFBRYCFpdZWWlRSAiIjolSZJY
-BgCgtVRUVMTGjRstBG1q6NCh8fGPf9xCiBkxAwAAZB4zMwAAQEZKvb79xaYLJYOutiIAAEBGcGQG
-AADISP8FpxZnWS0U37cAAAAASUVORK5CYII=
diff --git a/Documentation/DocBook/media/fieldseq_bt.gif.b64 b/Documentation/DocBook/media/fieldseq_bt.gif.b64
deleted file mode 100644
index b5b557b88158..000000000000
--- a/Documentation/DocBook/media/fieldseq_bt.gif.b64
+++ /dev/null
@@ -1,447 +0,0 @@
-R0lGODlhcwKfAucAAAAAAElJDK+vr0gSElYMDC8kDV5bEBcHOwYGSEQODmEaGgoKOBkTVC0tVyAg
-aDcJC6Ojoys8DAAYGqSkxV9fFFtdEJmZmUA4EF0wMAAAcAoTHTZHJ0gYGAcMTwcSO29ISFUHB2AV
-FXd3YAcHMRUVQiIAGg4HT3t7eywOJ3d3dwcHSEEgABMuDnd3OGpkSQAAYlZGBzEEBGJlDCstCxwc
-WQcHSzkRGWBtYC0AACA3ABAKNhAQTTMwDA0VQD4AAEYVFVVVVSQMJQULOB8fQScnYBgYRD5VPmZm
-DEZRB2ZiDAoKSgAAVAwQOH5+lBwcS+7u7hoaST4+X3d3WACPADMzMyBRIDgAAGBgc0JCEHEAAEwN
-DRkwDAoKOR8kPZR7eyA1IABpABgNQBA9EABVAAsLRww/DAwMPgBNAENDCgc9B8zMzAUFQQBDAD4M
-DAwOKgAAcQA5AEtLFYqKAA0NTC8HBxEREQgfCAArAAApACIqMkkGBhoqKnwAAAsGQ6qqqkoKCg4O
-MlkcHAoZJCcrW6SkpFQAAAAAOBAOSwAVGh0ROgMPHWZmB00QEGUAAFQaGjEyC2w4OLe3n4qKioiI
-iBAVMC4uXhkZUGIAAHJYWHd3AAAAPhAQUQUGL0BAIGggIBgAGkIVFV9fEAwcJR8KJA8MU9EAAAcH
-VRoaYWhoaDcAALu7AGZmZnAAAGRkZGQVFVhqWD4KCgwOUzMzDAAAmgklBzEHBzExClhYWBMTPAYJ
-Qy8fCFpaB///////ACISRExUDUQrDAwMVhISSEYYGHd3IDhcOERERElJAAkPNTsHF1hYckgGBj05
-CFYAADg4OCAVO0hCDDAwMLu7ilpaDR8qCDg+EBxGHN3d3REGNjo9CDQ8DBwYRGZmHFMAABQ+FBE+
-ESIiIhs+BxU0FWVeBw04DYqKsxAsEB8hQAwuDAc2BwwqDAoqCgcIL1dMDQAA0Q0iDQwiDAckBxAQ
-EDwAAAAAU0JCDAkJPru7u5oAADg4bAAAAAAAAAAAAAAAAAAAAAAAACH5BAEAALwALAAAAABzAp8C
-AAj+AHkJHEiwoMGDCBMqXMiwocOHECNKnEixosWLGDNq3Mixo8ePIEOKHEmypMmTKFOqXMmypcuX
-MGPKnEmzps2bOHPq3Mkz5z0AQIMCSNHyZ0WjE5GqNAZAqcGmT+8VZMoL6k6rEp0KfEJl489VBcEB
-GGjBwk8LBJsyFQqU15MUdQDUWfVk4JNVccER5ZXCT8+/gAN/xFp0LEWtDxEfRKo44s8n1/YeJCyQ
-8GO+1xhSbvwxRWaklBEiXoVW4886BNW0FQjkyem6laUKdLqKSuZrQIxtpbLqc51JbsHBFkw8pYUT
-w4uHDK2SM0PnCqHPNiz9uWGFoS1fb7h5u0nQshf+ar2G2isAKn4FpqByHQivn8YkY3WK9RoANXx1
-kwUncBVw5QCSdAsA8jiDXIAeEQYXAMbgp0YKKQAFYVxEPbjgXm/FBURmD1pQxz1qsDfUdAVlCMCG
-vFg4lhpMgbOKYX6IBY5fHX642FBx0cULbnKlUFdQkgS1IxA91mWMBWJRYQF7dZQ2HVBIsdhjbG4R
-WUeE4f3UFlQN6hUiUK1puV1Q93Sp24LglNYlAGmmKGJrvBxJ4YWxiUkmLzGymZ6ULnqXAlgC5Tmj
-QRE2qd+NkwDKCziTwAjcT6rhV1WW28013D11UfHfVrItieCnHw0YVIEHgnoRVutllgJ/X+F54hP+
-fjT1FWR68WXbXV3dU4cxmBoDnGpSaZUqru/NJRUVrV3DXrHBAnCNrrwmN9Cs17jIC2+QUUEUY4Zh
-qyxR52X2IlFwFWSUUU/8tmObXBrzxBNEhveeYVCd5wd5RD1Ra3eVzajGPeCoSq8x4qJ2ZXDghvlq
-rFJBBR6z82aGbLbe+TqbjT9lNtCq4npHUMblqQEOUr3Nmx+VJJIVl7aSToqQan/ZydbMNNds8804
-56zzzjzXbGpFWA0q0IdKWSWrswIhyUuTAtn3L9IE2ddsQUzveF/GKUJtwVirSAZECliLpnUdqmns
-ockml500agCkx625YxnlqUCT6NaU2lbL+zD+AKXNpTHK09Lr5MaCk+h3WrIZ3fDULnc90Nd4b12Q
-VY6zJtmiTnoc+LV+QYiUfuiyS6lB96wHAKDMAa5TZBC27vrrsMcu++y012777bjDHg3N4Dgj7c8P
-YTXzPUUnTvx1Rgl/PFlUgBMv2gMp/zaJawUFtuabT6fUudTFjfxYVk2/uVERCmX38tHrTe/iTa8C
-Th1A4MevyykCsStV9Bt1jfvwy288lQ5bX5zYcr3spU8g1ZMQ4gbCH7HxIlGLetp7/sOYOjxhPthz
-FX40VRDPqA54IISIqAhkoN+F0CFBkxf0FBe2s1XNaVG6D5W08sKrGcY+ZuPa5aB3I7OBI3L+qHkb
-EPPXPbiZzAKHSh8Om6YdAKowQ/TLnlUOhrbwbQeKinNiFaVSuYEskReSI4iNeNFFg1StKgnRH9lY
-NZYUSEopX8NgWpIDlVURJFawSd0J92iQW5DKhHzkTnhS9UALFq9Op6MVuW5VG7RF6oFt46GtrkEs
-pRgjWcvSVbCIhrwdUqtW3tLWvOqClFCCSzbiIxG61PUtlxnDXfBqosusAgQ42TGSHwPAj2TDSqbs
-kkS1rMst/zdLxjkMYza6JMWmshdNQqx0fAkYGanjyW6J0iiHUkq65DiQV2aGWMFB0T1EmbVAmjMh
-lDwnRRS0MvwcclI/WZCOTAQnpSwoPgD+mIRW6EnK6zyBKYZKmozQYk/vqIiKPEKoWNRAHtQkdC9W
-TNn4DPMlKkIllldyYy61mKK1UAE/AI3aQq2CJDbBhW2oXJFH/YeyekmlodeSYUnb5BaAIrEgk3CP
-QNlUmgi55UVNMoxPNwpJd95HMk5p1Ojsghe5lGwrTa1V0nSqzqpadSXVmckOr7rHdAEyNbDRVU+A
-MDiumvWsHclqTO6xKbSeMAVlPcgqWgMvReWkWm7Nq14tota9+vUjb2FILF/FE7P89bCITaxiF8vY
-xjr2sZCNrGQnS9nKWvaymM2sZjfL2c569rOgDa1oR1uSfxHvtKhNrWpXy9rWuva1sI3+7WkBaVrZ
-2va2uM0tbNOo29769re7FQ1wh0vc3/K2uMhNbnAN4hrlOve5p21ZQvIxi+pa97rYza52t8vd7nr3
-u+CtbgZUOBBP4OO86E2vetfL3va6973wja98z1uIhHBDFfjNr373y9/++ve/AA6wgAeMX24kxBpg
-SLCCF8zgBjv4wRCOsIQnTOEEWyMhSwivhjfM4Q6DlwaiYcV8R0ziEptYvp5gSD7cweIWu/jFMI6x
-jGdM4xrb+MYsngV5BeKJUvj4x0AOspCHTOQiG/nISE6yjy+REGL04slQjrKUp0zlKlv5yljOspaf
-TIyEVGEKYA6zmMdM5jKb+cxoTrP+mtcM5iok5AU4jrOc50znGztANPhQsp73zOc+JznFC1lxnQdN
-6ELTWMcI6bGfF83oRhuZyQhx8pYnTelKWzrLXUbIl9nM6U57+tNqdjNC4GzoUpt60HdeTJ4dzepW
-LxrQChH0qWdN60PvmBeKdrWud/3oJl/618AONpYzfZBNg/rYyE72mUV9EFLX+tnQdkeqSbdqXlv7
-2qWAdULOYYZue/vb4A63uMdN7nKb+9zo7jYXIIAQDhDg3fCOt7znTe962/ve+M63vt9di4TI4ggA
-D7jAB07wghv84AhPuMIXDnBZJOQd6Ii4xCdO8Ypb/OIYz7jGN87xiL8jIexIt8j+R07ykqPbDQiB
-wB/2zfKWu/zl+uaAiqNNc1oj+iC5xrbOWw3pg0ha2EAP+qWJbRBjK/voSP80sw3i7Jo7ndDTNle1
-d051RmsbIbJ+utbnfHOD5LzqYN9zzw3yc6Gb/exWJnpBjJ70trvdzEsvSNO3TncbR/1jUw+73pF8
-9YNkve6Al3HXC/L1vRt+yGMvSNnRznjGq50gbH+75N8ed4LMPfCYb/Hdp5X3w3v+x303yN8zn/nB
-E6Twn/d84gmy+Ma7PuiPH0jkJ0/7o1d+IJcnfeA3P5vOp/7woS/IEOZA/OIb//jIT77yl8/85jv/
-+cUnBEJ+oIXqW//62M++9rf+z/3ue//74K8+LBKChWmY//zoT7/618/+9rv//fCPv/mxkBBzkOP+
-+M+//vfP//77//8AGIACeH/mkBD2AH0ImIAKuIDPxwQIQQjhF4ESOIEUGH4/MHO6p3umV16/14Gr
-NxCt93oi+GuxJxCzV3soCGq3JxC5l4F0x3vv4XsdqHfBRxCj54J0t4E8NoOp94ECEYIjGISTVoK8
-cIIpeIRstoK80II4+HQweA8yyINVV4MDcYNN+HQ6iGtSqHq+JoReWGlEaIRIOIbL9mZXuHt4toXA
-h4FnmIO3hnpquHM+yAtA+IV2OGVhSIZ6mIRm2IYvmIZxSIMMAQUvUIiGeIj+iJiIiriIjNiIjviI
-kFiIS8BuB5EA83CJmJiJmriJnNiJnviJoBiKoniJOJAQ2ZAJqJiKqriKrNiKrviKsBiLsjiLqJgN
-CREPbJCLuriLvNiLvviLwBiMwjiMxJiL8ZAQhhCJyriMzNiMkDgCKZcKoziN1FiN1iiKCcCGfoiF
-bxiIejeHdXiH4tgLebiH5liGo7aNW/eEUeiNvEaFAmGF6lhrWQiH7shr4DiO+oiHXnaO/khmSsiE
-8zhr7HiPU6iNAwlt9WiQVJeP+/iQ5NiP/ziRUxCQCVlzBcmQOgePvEAEHvaRIBmS3pUBAoAQrsAH
-KJmSKrmSLNmSLvmSMBn+kzI5kyjZDAkRCgSWkzq5kzw5YKGQEGJQYUI5lERZlBQmBhgmkkq5lCC5
-CQghAI1Ak1I5lVRZlTPpCgzRAG+wlVzZlV75lWAZlmI5lmRZlma5lfRQkgehACfWlm75lvBVXwgR
-B3JQl3Z5l3iZl3q5l3zZl375l4BZl3GQEOJwBoZ5mIiZmIq5mIzZmI75mJAZmYYpDgmhCWd5mZiZ
-mZppliTwlCIGl6AZmm2pAAh5kTbXjRqJbQ4JkfpYjhTpjxZpmtCWkalpbRwpj7JZaAtZm9a2mqwp
-jq75muYYm7lJa7TJm7p2m8VJj6iJnLrmm79ph8EpnHpInMtpasfpnKz+xpFOUAPe+Z3gGZ7iOZ7k
-WZ7meZ7omZ7eqQKUaBADAALwGZ/yOZ/0WZ/2eZ/4mZ/6uZ/wGQMJgQa7EKACOqAEWqAGeqAImqAK
-uqAMGqBokBDrkA4SOqEUWqEWeqEYmqEauqEc2qESug4JsQbqOaIkWqImmp4LkHJ6wJ8s2qIu+qL7
-OQCleZ2EtpvayXNdGJ13OJ3UOYbWSaOFlp03anUzCqR0ZqND2mjQqaNCyKM9eoQ/aqR1JqRJ2mfK
-KaW62ZxVumhLyqQj6KRPioJRiqVyRqVbqmdXSqZ1hqRnymdd6qWvB6ZhSntjqqZ2BohtaqUM0Z0n
-2qd++qfmyZ4I8Z7+MFqohnqo+OmfCAGgDdqojvqokLqgD4oQEeqhlnqpmJqpHAqiCCGigPqpoNqn
-KXoQELCiiHqqqFqoMhpodrqmWpqnevamcNp4cjqnklenrUpjZgqrRpamuYpjbMqrSCars4p2tWqr
-boervxpjuyqsQ+ary1pjweqsRUasxWp2x4qsSaes0epizUqtQMaRWrmZ5Fqu5jqWaYkQbCma7Nqu
-cZkQdBmY8jqv9FqvfzmYCFGYkrmv/Nqv/gqZlIkQlnmuBFuw5NqZByEAn+muDNuw+ECaC+GRTDmx
-FDuSamkQJ2mVGruxHAuTNokQONmTIjuyJAtgP4kQQWmUKruyLBv+YUiJEBlWsTI7s9XllAkblR2b
-szqrsVjJqt1qY9MKrkJmrdcKexKprWLahz+rq3gqtEUGrUsLY0HrtD9GtEUrbNmKtMrGrUv7rU4L
-tVHrYlNLtaVgtVcLbFmrtcjGtT/rtULLkVHgAHI7t3Rbt3Z7t3ibt3q7t3zbt3JLA7eGAZ4wuIRb
-uIZ7uIibuIq7uIzbuI47uKCQEJ1ADJRbuZZ7uZibuZq7uZzbuZ77uZTbCQnxBVVQuqZ7uqibuqq7
-uqzbuq77urBbul+QELjgt7Z7u7ibu317DqIRCI/7u8AbvMLruBhAWsZ7vMibvMq7vMzbvM77vNAb
-vdI7vdRbvdb+e73Ym73au73c273e+73gG77iO77kW77me77om77qy1VnBEblsRXNlEGawRa6ARr0
-K0nzEhRCcxDlwxZScRdxYSnRIxRwsr4GfMAPkQJUxQtAYFdDhRhqQCSEhRCh8TBGdMHumx5ptB3k
-gSK4UQcaYxXKssAIXMImPBCqARsXpMF+EBcSxUB0wRVJNDnkZcFEdcPRJB7bcUkFUUuAEysnHMRB
-TFMt7EVpUkRTEVYZVMEChMEGZDV/cyN2IUOpoUtRBMRCnMUHrMD9IRm+kkqE0kCTUcNNjMMvHEVS
-fMYcNcJa3Mbqm8JLIylcDMZ2ARe3VhVskTIzsy0eoxV6BD3+ilEv5vNVblzI3qskMXIx/aTGhUQw
-2EHGH4S/TvFFDrQVVIzCVvzHhrzJ3ptTldO/ZIIYq3LHB3TBTEw622FH0bHDJOzDaMzJsAy+9vFD
-qHzGFyRdCXHKryzJ1+EhGlzJTQM/t2E/IUzKsXzM19s8aSwzvDIzuQzJeJzHzJy/QLG/G1wiTXU4
-kYzM3NzN3vzN4BzO4jzOZpUCr3TOr4TLH4FE6PxKcUXO8BzP8jzP9FzP9nzP+JzP+rzP/NzP/vzP
-AP1YuTPQBF3QBn3QUexXrHPQDN3QDk3QCb1XpfPQFF3RFg0hjtUzGr3RHN3RPGPMZiUzHj3SJF3S
-NwPSXAX+yia90ixN0hm9VXr1Eyh9VTKdWDWNWEOF0/K7VyOCWDd9WD/9V0HtVzl9WEWtWD0N1Joc
-0kvNVUO9V0dN1DutV0ntBZhw1Vid1Vq91Vzd1V791WAd1mKN1YEz01b10zfwCmq91mzd1m791nAd
-13I913Rd12p9A2WdWDl9DWPd137914A91l5AOC/NgWRLZD331DGNFWKotlub1zrNeYdNZLAW1YiV
-1PZItond1DTN2I5Np5Bt1MjTjlRb2VOdV5g92YgX2kLt2Z99q6wt1ZKt2kFm2oW9g7QNZJtt1lX1
-04392ioY21A92rkdroTdWEnNCKm63Mytn8sg3IsdHur+oKnUXd3WvaHqAN15ldOE0Nze/d3yyQjH
-zVipXdxLpt1u5dvATXnojVY5DYXm7WO2jdySkdlUu9s27drrva3tfVbvTdpfO96LVd7mjd8+rd/7
-bXv9Xc7EHd/zTd71Hd9lu+BOjeAJnmzMptjb3eDm/eADLhmECt4inqqKOi+8rU4/XanXveIsrqmc
-auJ6fR2lOuI0fqqryhen7VYEXtwGrtTh8dsXvmYZztlW9d8S7uFIHeHx3eOt/eNBruDaE+Oz3eEC
-nuSGXeAU3tlO/uQYnuVFzuHFjeSJldTr6rBmLppyCeMHHh76+q9u/uZw3pgBq+aiPRAKe+Z4DpoQ
-i+P+t80LjpAFgB7ogj7ohF7ohn7oiJ7oir7ogO4DXt7bWOENLTvplL6y3vDo6pTTAtANjN7pnv7p
-oL7ojlDlY67kWB7lay57XN7lqF7nvXfkpH7Zps7jmH5O6r3qxzbkJ35ORu7gsX5YO57bTO5Xt47r
-Slfr5tTrVK4eOY5WST0MbRDt0j7t1F7t1n7t2J7t2r7t3B7tdIDsgfTT8FAG5F7u5n7u6J7u6r7u
-7N7u7v7u5A4P4M5HOQ0BD9Dt+J7v+r7v3D4Mv/5XwU7bwy7RFm7sfNjqf6XsYf7vfhXwqj3w0a3q
-Bu9pui7lr+7rzN7n9u20EJ9XxT7xB0/nCQ/muS3+5rJ+5bSO8MRe8CCPZhUf2Re/7HxO3wNBfRV4
-8zif8903fipP8OFhfwMY9EI/9EQfgAXY83rF3Tq/9Eyf8xeY8TSP26cu8iu/5S0v5PO+Rwpf8gzP
-07Mu7Fl/Qh9/9S4f9iG09bRt8sD+9QJv9iA09mQPd24PPGiv2moP8Gz/8HP/M3Af9wC596ZS95N9
-9w0vGe4Gc4if+Ip/b/2G9B6PFRDXcZI/+ZRf+Rv3cY7vVvW+covf+Z6P+DIH9RCO8mCf+WjV934v
-Zi/v6jEI66L/4aTf9qZ/Vqif+m0G+KAi+IdN+F4f+3o/+0xt9bb/98Cf0iSf9l1P1ZIRAnne/G3+
-meYant5Y8Q1jUP3Wf/3Yn/3av/3c3/3e//3gX/3fgPufoukL6/zoL18hkPyoLRl/HurwH//yj+iO
-XvxaPhCSXun6v/8Sdun2/+UAwUuggG5ZDB5EmFDhQoYNHT6EGNGgI4G8UgComFHjRo4dPX4EGVLk
-yIwAUlT0VErlSpYtXb6EGVPmTJo1VV6qeA/APZI9ff4E2lMnT4FVphxFmlTpUqZNnT6FGlXq0So5
-dwbFmlUryYs58dkEG1bs2JqeKnbdmlbt2oomUZKFG1fuTJwCh7LFm3fk3aJT/f4FHFhqVbtX9R5G
-nBEtr3tf5z6GDNeswMWJLSd2KzBlZM6d6Vr+JXpZtFq+vIwKRp1a9VPCjA2Php11cWPPtW2vnGwR
-Y2zeWzPzwuBJ+HDixY0fR55c+XLmzYWDAt1butDXX6pcx55d+3bu3b1/Bx9e/PUv0aefBzk7kHP2
-7d2/b47h7G709UH+tp/fdWj99kv3r+8/AM+rbEAC6TMwP/wS7E1ABmNz8MHRIpTwsgIrHO1CDGNb
-cEPLKPRQLxBDxGtEEtfS8MS8UlTxMABWuSdGGWeksUYbb8QxRx135DHHSV5rUUQAJumxSCOPRDLJ
-GH/kL0i8LlIySimnNHIVBJ1EDAAtt+SySy+/BDNMMccks0wzm8SSNDPXZLNNN9/0Es00t7r+CE47
-78TTzTkTo7JPP/+U8Yk92XoCUEMPRVLQQdW6BlFHH8VxUUknpbRSSy/FNFNNN+W0U08/BTVUUUcl
-tVRTT0U1VVVXZbVVV1+FNVZZZ6W1VltvxTVXXXfltdfD6rAgIwvqyOiJk1zDyktjkOVFWWYz0mlL
-cPz4qEsqQrtmlToAACcFQaPt8pYvj7WACi2pCFYgbjWyUk5f34V31xSAyAiIVRTbTaeN1ABCSyAU
-5QjIwtRFU1+NDOZlWGo7MuwJbQW9po5VruFFDSqo0EjgZvlbhYqF/aDi3mYBUCOjbd2NN2WVY1UD
-AEWfAGBhXvzYdmCNwFnliSeoWJbhgnf+0xhhqxQDx6PXYObJGHoreqLbktB8zQJwAOblCWCbpeLY
-mc1FeWWvv0YVnHRprugasfO9khdjFBU6458J3qjtZ3m5BgCKAw7Nap1J1mgSjNuCOjQqJtkoBYyH
-LFqgVZgEu3HHUZ1Xca2NIRLtj1JIHO+4gX774Cs1hrvqVaiVW2iNXwsao53AKZmXOuru+nHZZ6+0
-ZUHraD1yg+UWyNg6UPbSZi9PKv1zd50t/umNUH97pxROAnlj2qen/lJ0/Uj8njq+tXyjSeow5m6f
-Nw8d2rSFrlt8tyv6UQ2YW2f/7/IBr2hw7w+/R42iF5e+ev//T9Mk7HWsOnEpRmnDXOz++me++dmM
-gWfJ3PL4cxWlFctp9FufQIZFNasF6yqse90CAThCEmKobqwj39yqxreQpK6BKnyWwowWmu8JJGIT
-q9jFMqi8inTsYyGDm+H+BroSFtGI9qFCBIfmGi4ZA1xbmmEKv8TELS3ridOqFpeoAL9sbatbVBNh
-A8t1LsLBrWVlJOIR1bhGNrbRjW+EYxzlOMdQpcAYd8SjMeCHGAvkEY/pomMgBTlIQhbSkIdEZCIV
-uUhGNtKRj4RkJCU5SUpW0pKXxGR98rRJTnZyS1pD1RM9OUpSnmlVoixlKlXJJVgBwBjPg2UsZTlL
-WtbSlrfEZS51mcsOlUonq9hlMIX+OUxiFvN57Trli4y5TGY2M5jGSJuqelmqaY7KRKC65qey6SkW
-naqao/pmqLbZqXFyqpyb6qapwhmqdWozjaI6p6bimal0UlNryshHPvW5T37205//BGhABTpQguoT
-fu30VGlc0AKGNtShD4VoRCU6UYpW1KIXZagLzJOq0lSioB8FaUhFStAozKeVWsuHO1S6Upa21KUv
-hWlMZTpTmtZUpbMIDULJ+Rpi9MKnPwVqUIU6VKIW1ahHRWpSfUqMjYbyNS+waVSlOlWq1tQBJn3V
-b1JaVa521asyxWlbQHmq0vRUqWdFa1rVilSmFkaB7gwNVL86V7py9aqUiWaqtFr+V772laZhVddY
-TVXWtRbWsIc9alv3k8y4+tWxj13pXXVz0opsFbKXrStgmyVYX/IUsZ8FrWEVO09MlUaumEWtVyVb
-T1L9BgovgG1sZTtb2tbWtrfFbW51u1vYLgECYmVsRWxxDOIW17jHRW5ylbtc5jbXuc8lri2aStbX
-GIK318VudrW72xFg1VV7TW14q6pZnZrTs6FFb3oTO93BPlW875XqavOKKvDC175gzSlnSUVY9fbX
-v0tlb2cbe18Cv1S+lBWIZQu8YHeQV7/WPO9/JRza0b5TnO5lMIMPnFWtEWEWHwZxiEU8YhKX2MQn
-RnGKVfzhDAgAuKoqTShUMWP+GtfYxjfGcY51vGMe99jHMw5FgPf7miWs2MhHRnKSVbwJ77bqNw14
-Q5SlPGUqV9nKV8ZylrW8ZS5HmR4uDmxwBRIHOZTZzGdGc5rVvGY2t9nNb4ZzmeMgZAiHRhNdxnOe
-9bxnLpOgyayqb4YJ7GAx88KsE0b0YSv81oRiWNAE3vB3UfroAhMaxhFOdKbTuuhCn5bS8I20kyf9
-aftamqOY1nSq2UpneDqa1OINNaC15oQa1NrWt8Z1rnW9a1732te/BnatVfDbMF86NGjYRbKVvWxm
-N9vZz4Z2tKU9bWonGw2svnBo1hBsbnfb298G9gL+vKpAvzq1pnZqaA6tanb+F5XTxq6Ip82N2liT
-e9TzPnd+C73udvcbqO8+9YDxTe9xS/PeA78suqmrbn83/N/YxqarEf7Yehu8shPHrMLby3CHOxzg
-6Y43xi9bcb3OGtwnR3nKfT3sFwe8IsiudsxlPnOaT/vabi30tlW+c56fXNx4RTAvFCzyvmpcwBXh
-d8fZ/fGFh5zojiU5fQ/+9MzqG94CSbrSU830jTud6nyNujen/vWvGn3IHNd6u7l+dIHIm+yqLXjJ
-KwJlPtfd7nfP8pdbDvIxx9nvfwd84OE8Z5xfnRd3xnviFV93PwOdwxXxsJIlP3nKn7jFe2+6QGT8
-Y8533vOf73GQC+9ygRT+ufKnR73kmex4SV/87XQ1e52RnvZ+r/3sXn893Fkvatfn3quxbzXaab91
-iMMV976vatjVOXbkSxX42Z798FVte9m3vfldVb49KzKEYHTf+98Hf/jFP37yl9/850d/95VA7M0W
-WhZHgH/85T9/+tff/vfHf/71v3/4y6L4jQ6NEUi/ASTAAjRA9HODuJO63ru+qXq+iBM+6Us06gu+
-42tAm8q+1mK+C5ypBzQ+rJNA4hs9vuMFt+PAmcpAcNrAE4QpDwTA6AvBCfy/nRI4FqSpFBSVcrPB
-mHJBGoTBGJwwCoQ+69vBG1RAsdu+OVDCJWTCJnTCJ4TCKJTCKaTCKlz+QkLAvK4TCCyYhi70wi8E
-wzAUwzEkwzI0wzNEwy7Eghk0r9CwByuEwziUwzmsQiY4wuVjwCJsQasjPUMDQhkcwcwrQT1EwTvU
-vgQjRPzKQrbzwz8MQjbcFNNKxJjCQXZawUTswTb8QUfsLyGEQAucRJWqRFDRwVBsMD4kwazjRAqD
-RHmSOFN0h1H8lN9oAmWwxVvExVzUxV3kxV70xV8ExmC8RfEpr0h8DRGQgmRUxmVkxmZ0xmeExmiU
-xmmkxmQUgVbMlNIQxm3kxm70RmG8AkPUQFkrNBI0x1NhLRUkR8M7Ry1MlXTMwQdTR3YUxHYsFXhk
-J3Dwo33kx370x3/+BMiAFMiB5MdidEWeIciEVMiFZEiC5JpkQsiGlMiJpEiBBIf5OpWK1MiN5Mg/
-WhU16MiQFMmF3KNTAcmRRMmU7MdMYsmWdMmXhMmYlMmZpMmatMmbxMmc1Mmd5Mme9MmfBMqgFMqh
-JMrzuJqKGJZiORbeGQnkAZousaLz4RIsAomWWZr5QSWTQCXisZaFcaUHEoh+OShncZaiNEv0iJyK
-sBd8caCK4Bd/ASMeeiAX8hykrAOZ6Yg6ARgieg3eEZoU2J6RKaNngZkOARILO8vEFA3b6Z2YqQia
-6Z6MwBmd4ZkoqsswgqG/VKKNAJajxMzy8UvjaRZjCMxnmQRwOE3+CZJLxWTN3hAbgSAbGzqbthSI
-taHN1RSezgFLurEbj/ADl1mFq+TL0AjNjKGYnaCCpUGYrKmbkjxMRmvN6ESRpQGmiqCc3cFIzLHM
-udTNJcIgjgjOmXGZFwLNaPpLNMofxzSY5uSFrNmhz5TO+MwLxsQdyqAX7OwI3wGeLhGeLuHKFPpO
-zlyYOkDP8SmMLuEJUTrKqwDMQtkNvxGIGlrN4ZHPCsWL68mewMRP7wEf9VHNy6TL3UyfjvhNLSLP
-BSrOHkocwwgZgzEXLsHL57TQGc0LAapO3UBQuUmgFuqcEPVOi9jMHhIZ8TzO4yFO80QQgzGMlumK
-ERUIIApQxKT+0SkdiRMqSWZpm/cRCbr0UQeSIY6wGrwkUPjsSyTlzvnACMPJCAmdHyml0jf9iCTi
-COxsIlTaziWaIlGKSmnBS41IyozomJFhpe9EpajMiLqhFiAxF15AzUN1zDYNHjiV1Eml1Eq11Ev1
-HzvaxyvNiz7aR0DC1FAV1VEl1VI11VNF1VRV1VVl1VZ1VQNxpliV1Vl9Hme4BVrF1VzdJVRwBlTQ
-1V8FVlniVV8N1mLV1WE11mSl1VtwBmV11llVl1WS1mml1mq11mvF1mzV1m3l1m711m8Nk2KTJmdY
-FUkAAEko13NNV3RVFWfASFFBC4PUFAAgV1UxV3ZNlXtd11X+cVdWiVd5zMF6zVd1tVeCHVh8RZV+
-XZV/dUtIcdg+2UuBVYOHpdgoqQh9tYuK1dgjuViD3diP7ZGOxVeQJdkcqQiFrZqSVVkagR+GTbDU
-g9mYTbEMyCmB9QR8wNmc1dmd5dme9dmfBdqgFdqhxdlCENmK4AbQU9qlZVoe44ajFQhrAIOppdqq
-tdqrxdqs1dqt5dqu9dqptQao5QXTk9myNdtZoIGTpY97YAWiddu3hdu4HdrccFmhg8WWIi+bvY29
-7Yy64AWMbcRV7ESxPY3VMNzDFYzWAFwTDEXJQlna4NvInQu6BZpLJMS8fQvJ1Vyy8FvAVUXBRSzF
-AtzCRdz+0jVdp1Bcg2XcSXTctXWMzYVdm6BccR06WMRczYjd3KWJzjXYzwVd0SLc0xXe4UWK1MXX
-1U3E1vUK3WVemJjd9hOIczCD6aXe6rXe68Xe7NXe7eXe7vXe6eUC9qPXiuAAAjDf80Xf9FXf9WXf
-9nXf94Xf+DXfWhDb9+O/+8Xf/NVf/fM/gQDcd0CHABbgASbgAjbgA0bgBFbgBWbgAH4HsWWH75Xg
-CabgCvbeBBQIlIWAP5DfDvbgDwbh+OUArCrFULxdXtiM5lXhmxBb3/3dtRJdgyVd4qVhwzVeUGxc
-tV3eFV7h5y3hSTzhFOZh5uVdfHXhF9604K3hJV6NGyb+wrsVRR22i9cdYt31YcvVwyCu4uYt4k1E
-YkVTYiYW48Bw4kGE4ijOYNfdYua94jy03ZrN3DWO3S4GwS8GrRjG1xke4z2GijJGXkJU3imW49xt
-Y4EYAjpE5ERWZCrEQnUR2B/QgkiW5Emm5Eq25EvG5EzW5E3m5EiGBbHlwjQU5VEm5VI+wzX0X4M1
-B3Jg5VZ25VeG5ViW5Vmm5Vq25VtmZXMQ2zdc5F72ZUS2wzSuCELo5GI25mNG5k7+ARLG4iLU4kGG
-XToOXDsG41TOYz7G5qjw4zNGY154XCqG5sgtZLvl5mcOZ8mV5iOm5lWz5orQ42yGZ6oQ2z/Ww0Bm
-DHD+PufbGOfaNUVzzue9Ted1Dt0wjueCnoJt5mZ7htx/3tt95uZTbAu9ZWiAbmGBrua/lWGD1miE
-PmOFxueJ5oxx5r4DJOmSNunyW7+IrohhaIOWdumXhumYlumZpumatumbxumWpoP63d+e9umfzr/+
-xWh8hYcyMOqjRuqkVuqlZuqmduqnhuqoNmp4EFsBPOmrxmqSxmBvpg8IeICcBuuwFuuxxulhYGY3
-7mc4xl2Qto2AtujCwmN31miD5mgo9mi2tg2HLme1RmG8rg23fmu1iuu+mOt4ruu7vWu/7gy9PmN/
-VuzHAOzARqvBNo3CNux5fujEfmzIGOfIO9vPTr3+y3PkinAFPjDt00bt1Fbt1Wbt1nbt14bt2Dbt
-ZhDbzWva28Zt0BO9oa4IMfja3wbu4BZurxUDsSVb0EbuyVs9rq4IAWgE2Ybu6Jbu6Y5tVzhrgaC7
-xdPu7c47MGsWgVUAuRXv8SbvoDXadu47wVPv9WbvNiM83hYIcTiD+abv+rbv+8bv/Nbv/ebv/vbv
-+RYHsUU87ibwAn+DxmPugWjb8mbwBhdvBbhucm5svhbizZaLyJZspaLsd7ZsJj5sWNRsC5cLxoZi
-xxZxzq3oDJ9sgu7wMf5wUwzxEycLEr9bE5fxsMBwFV8v9K7sFufjF89hYRbkG5eMCKe1nkPyJF/+
-OfEV2AEAgSeH8iiX8imn8iq38ivH8izX8iePAbGFuZoD8zAXc2i7OfjmhXVIhzRX8zVn8zZ38zeH
-8ziX8zmn8zRfB7HVOSXX8z2vgZ9LcF6AAD3Y8kEn9EI3dC0fgAjnZxOmcCKHixzXcXdjcR9fYiBn
-XSm+Z0efcUV/aBvX9M/gcXWO9F7YcErfY0tPXkxf6E+XXU7fa5Vea1a3CUgfdaEqdVMXY1QHZFX/
-aFl3XlefcFjva1+vCVqv9YfjcQ7H9dPV9XrmdWIviwgvAj6ndiVv5O+uCEY49G3n9m7H8mUQ23oY
-83En9zCvB7FVhzpX93Vn93anc3XA82qX953+83OUJQRvx/d873ZGAPYSb3RoB3UzF/VIv/Vlr+Fm
-L8IYB3iXoPE3FvYKX/iWMPZjB7BkN/hKx+yEfvaI/3XH+2FM/HeOd4mJp/iCv/jhRfgdVHiRL4Vx
-zm4Dh3nF07vRFojwdvCbx3nzFlsya++e93n1fm/Ale//JvqiN/qj7+8A5/EBj/mmtzsER1kBWPCc
-p/qqxwcI9/gOS+6tlzzRxnaBKG3qFvuxJ3vXpm0et+3cVvu117HdBlzfHu64l/u539ri5vHj5vq8
-T7HljvrnLvu/B3yxt+6sR2tGf3iWH/kUp3iiMvmTZ/aM7+iNR3zc6PcaD/nJLwWSP/bGd/z+0k15
-G1x5kW/4tD58zGfhUF98Sbf4zhfez2fB0Of4ca6E7aL92rf93FoCvg6ES+D93vf93wf+4Bf+4Sf+
-4jf+4+d9KwDlTGD+5nf+54f+6Jf+6af+6rf+62d+VDZzFmCD7vf+7wf/8Bf/8Sf/8jf/80f/7mcB
-sbWu23f/96d9XFD1QkD++rf/+8f/4w+ECNcrgUUVwAUIXgIHEixo8CDChAoXMmx4UBIASQ4nUqxo
-8aJAiBIxcuzo0aEzAB9HkiyZQiQvAClKsmxpEYAzlzJnItRI8+ZNmzh3ttTJ8+fHkECHejwpUCXR
-pBdhKm3q0KfTqA8jSq1qEKrVqkKzcjX+mnLVvbBix5Ita/Ys2rRq17JVCyBa27hy59KtG7YVgFZ2
-9/LtGxevXr+CBwsGTPgw4rnRACRu7BjtKpQAJlOubPky5syaN3Pu7Pkz6NCiR5Mubfo06tSqV7Nu
-7fo17NiyZ78W+Pg27rCSIOTufViAJAG+h/sFLpw48rrGkzOXC0FS8+hxuVKvbv069uzat3Pv7v07
-+PDix5Mvb/48+vTq17Nv7/49/Pjy59Ovb/8+/vz69/Pv7/8/gAEKOCCBBRp4IIIJKrgggw06+CCE
-EUo4IYUVWnghhhlq2N0TFvBizEIgJmSMMSlQoUaIaohI0IofbvgijDGilwKIIF5DhTH+JxbUokE1
-NsTjQC0CKSORRRqp1CQe+rHSkj5a4Acv1/BYIonXuPjhNeCkoOU1JuqYQgoe8rJll7xYQAUVHoLo
-B47gCDTkkXHKOadH1wDByyrXPOFji0vueA8v96xyJZ+8qHHnjR+iGKSLVDzBCzh78uLoE3XQeSmm
-mVrkIxBW+mgoECvtyKiIhVpQolFTYqnllvd8Cqemscp66SSrqEliHacGusqjPQIq6KSGFqrGSh1e
-SeqVkzT6RKWzOvssndcA0OubLq6CY4kFgUnio9eC6aKIXkJZarUgnknFSmvieOex0Lr7Lrzxyjsv
-vQx1CSaYVta7L7/9+vsvwAELPDD+wQUbfDDCCSu8MMMNO/wwxBFLPHF1VOhrgbK8GNuuQiSSqOaH
-HqfLIonoHlRHyYt6uZKKxqBM5ctK4kjFuIMKtAqsCIUpkJ0DiZkzySSOzMvLxqhYUNHUBukyiSiu
-/GbJYlL0hJs3L2os0AQVjWKNIrfrsckGvazjmGiudCrT28ZcdtjG2Ixn1tqK2bNAPzvkcbZde/x1
-yaIS1PLLvLCZI5Qh57jo1FXjuWjhcQu0tYhFgzxQ0ifnKOrgNJuJK5VMG822qG4PhHNFFtedsZnV
-/ugxyHh/CvXlBqGNMpMzFz424hdNknGnAtGoepQz5w58uaMyerPUx0u6s5l+Czn+0D1APPoEEK4q
-Do7jAx0qUJK2odSil8kTTyiLxgN70IrMWzB0sBYBsSgVA/3e4o2H9ziqqsfjKf6Vy4u5vv6Opb50
-XS97AtkeL7o3JnINBAho4p+q8gc8WyFERNGbXvWuRLeKvE8g8TPU9whyD+Hd73gSvNL5jBe/C2os
-g8RL3/8IOBDsVWR3AundAoFXP7KVr3wnXBEF0Wcb6bUQUCLa4EUSRTWBNAl4T4oSkCJoPB2yq4dP
-YN+xnnczfUUJZ6uAkh9IV5FITcpK1GPgzTxYQhP2UH9wWtHzVvTBigAwjEycH0GeKKU1Fq+Nx0Ki
-6q74tQDC0YdfFJwYKUJG0xH+C43EEojiAgiuKf6xisbL00CuMagjWnIidbSZGMGHIkAOkmNa5Jjq
-QIRJnr3tlHE8ZBgNGDyNVa2RToTSHik5ST+uiJSqW2UXNdhJi1jMT5JC40D8tKO9gYt1pRwf0XBl
-xDa6cplqGBRYZDkmCzzhgyk4GioltcymXaloppSkG30YtYssMQVQOiYqBec3ygmtXM48JSpfVodp
-prOf5bomnlxlkTB184biBBIp8cY1w+WNlxUcn97AMTyHtBNKk/ADMpM5z8fVM3IeW6g/tZYjcOQy
-pIUkFUCzScxrKFN6GZVnj5ipt4YS8qHnxJ1HdrcKFPUOmYfaKETPqb+ECqT+oNXUHzA1CaL4xU+b
-h8JYoIbWoiumQGlBfSbw3lhTbRrkfR/sKcd+KkQfUrKXwxSRUampVmQxNZ4LeaqyUsDPqa6CV3zc
-ZU15NsxfclGTbqWIV1tIPhGuAqil/CE6r3SopLZyrcVrqzZ16rS5/i1UY0WWQ/VqU8b+1SJ2+qDH
-cnUsQVlVkq974eggyKgB5jVQRKSeQFNQ2M4mhAq9m91pO3jZVPoRhW+bImu5WhAL1BV2uWoRaW2K
-2dYGUa2sRa3vYugi2WJxIra1Eo1cxr49cVGXp31mc8332gwKN4/FBZzRWgRA5Q42rym0YvXGCyjo
-brNuI6MubQ/yWd/hin3+yd0tXukb3h6yELb5BexGPUqia9XTuwxNF+vAZljJ+c5smWWi7VwkLU/p
-bo6qK5oAzOngaDYNbyup3G6fdmCG1KFwpBIZg7PlYBOTOL19s9zHKhw2+oKuWhtecUEm4eFyeuwE
-2CPRXWc60+zGTrmZa9xIWtxDEx9Zxpml8NZQjLSPCi7Dre2xhgHAYfclmKMLxhZQI4g3hqKtyZd9
-MjQpJuc5y+he+OouR/AFpvmqZ3344t9F/AwmQGfFzvn6iKFTgOfz6FmuIxE0865zj0aPJNGLNk+j
-+dyRTNO5057+NKhDLepRk7rUpj41qlOt6lWzutWufjWsY91q0frMUgP+EWSgULIUy4DoHpLhda4N
-4mvKgMPFB/F1rpPHmGFbZiWX6bVlNJcSTWvN1rdeRR0AUIeqHuUy3aYMDvkIhN9KK3d+YwxGmE2Z
-YKfE29MuiLqLrRBkpwS5IsEMiDDz7cnIm91dBcDwXDUZ3ap7Mr+qTL8REm1AneQy1JZ1VFJgyXET
-xCv0ruzASzsQdMNbMg+/OPR0bQEpIwTZvq4DtTh+FE2rPOQVR/m7DeKHybi4m71Tg21XfhCOPwHb
-pX1kMq2dwEh6JebXzjYPha1rlxudIC3398iN3fFuow7kLX+6zn0Hc5DfejLzVAMAlHXFrS+d6WYi
-+c7n23OYew/i1gH+e6+eAAAX+yHbbS8IOHjVTVhhnd59L7u/xxTJqfvayldn+cfLjm6s82LcFPdd
-JMFuJca33MoDmQS10b7je9g966Mznc9LDni/P7zpgd9SQvzusl5ZHfFpd/rBDzIJcMyeRfNMU+DN
-LviEqFzufOa6260CDjHVPZPDRwnwjcF6wG888Z7X/d15JmbR5xrsizo87JVekOljXe5+GPlAqIA6
-2zyK8pq2wOBRWVyNAbyotNf10x39fBGO3uOvpz9Bfnxsj+c88Ng3yNWhCPBNiqK1H/vljhpYyQCC
-nP4BIJ9VCrUMYPBFHLvM1ptgHvIxn/ykX/Npn+nlXu4xXrAh2+/+NN3/4Z/8ZAzWgZ/3zV8HOiAK
-ZtJvMZGtnYn8yBX8lZ73XBoIkt79QZ8Ikh7YQUnrZR8M+o7NAF+5EWD0TZ0HvuAR9pyxSeAENgXc
-EY3K3Am9SeDY6WC7VcbdXcZKAB/XBaFIIBvVeMgJfiFljKFl0BrWWVbjsYsIPtvzcd1FnQyUAEHG
-jJC/ieDIjV/HVUbsseFkiMjTlaEO+mAKoFwRbhywGSJSgKCQcY+tSWDBZeD26aAdQl8VSkWa+EHV
-cN6jbCHzTQLK8KAL+qATxmCUTN/+sRspruHfEcQqVM3TyZ1lPIr4DRegmF8eDd5ejQmvTF+lFOIH
-3gM4gIMX9qD+/R2h7jWgE3IcFYDF0q0hFFrA9AEfFVgGLhmgbXjIAi6dNBphAoEjFX5iUkzCuIlK
-wxEi8LUKQ9RiMtZfxXFg211cqNCi8zHd06Ff13kI6nUdlABjkMwT9SCEGuTKB2Wis1Eb5wliLE5j
-6SXi0g3kRHIc2BWdCVak63FdA1bjm8yTZY3jPfKe6zWhOkaFtEiUB3Kd3E3UD/pjP8Zg1KXeGepa
-pfDjE7Lb01keENyJzVnJjXyQQa6d0lgAoUEK7T3h0/UiQ5DhM25iK94k9Rldw5njB3Zk7pkIQaCi
-90zCo6CiAjLfxVnlD4KlJ65kU1ABB5piZRhDJqKkB+pbwUH+G7FJHeEt3STQorcx4NxJIgSAo5lM
-i8Zgm7bZlSQuXmWEm0ElxEks2sV5m8NdJQpixi9aRq7l5bxN5aRcI8tVZstpyWa2YVNmUmAGSjcC
-AMGJYWkCQMLtXGUkXTqypW3eJm7mpm7uZp65DjnhRJvhzVJSSHA6E060jOsYFnsUZ47xpnM+J3RG
-p3ROJ3VWp3VeJ3Zmp3Zu54D4pnd+J3iGp3iOJ3mWp3nKpH8gp3muJ3u2p3uyJ3r2B3O+J33Wp32S
-p4LA5n3uJ3/yZzc24374Grb0J4EWqHn+Z4GchIEuKIOCJzhooIBM4oD4GoDqB4UWyIUSCEcKyIYW
-iIQKSIb+TqgI9keIciiE9keHEsiHBkiJsuiI8keLAkiK/seMRqjfeAEm5KiO7iiP9qiP/iiQBqmQ
-DimR6mjIVWh+hOgNvAKTNqmTPimURqmUTimVVqmVXimT3sCRJqiuXUORfimYhqmYFqkXyM+JAoiE
-ekIprCmbtqmbvimcxqmczimd1qmdruklbCmBhGgVTIGf/imgBqqgDiqhFqqhHiqiJqqfVoGeDkjR
-3QM+3KmkTiqlVqqdeoKZ5qffqKmldqqnfuqc5qn3ICl+8KminiqqpqqqJiqjjiqXQk+kgqqszmqn
-YqrvnOl/pCmt7iqv1qmo5hqp3oepriqxFquxGmqrAuv+q9pGrPaqsz5rKdjqmOCqf+gqtF7rrv5q
-jP7HsB6rt37rqibrtvrHozYrtp6rp0prjQaIhNpAMrwrvMarvM4rvdarvd4rvuarvr7rAzQqiKrc
-FoSDwA4swRaswR4swiaswi4swzaswG6BvwZI0RHCvlasxV4sxu6rDWRqgkioA7gDyIasyI4syZas
-yZ4syqasyq4syL5AxAJIiBJDL8wszdaszd4szuaszu4sz/asz84sMbwsjeraPcwCyx4t0iat0q6s
-A3Asgnjs0kat1E5tyrqsq+6pysnsz24t13at1/Zs0F6toxKt0VKt2Z5t1DbtrWrqQHws2r4t3Fat
-0Pr+R8x+rd3eLd7ybNgqq4aSbdz+LeCGrNpOK9sKhNsGLuKirdXyrYjymdbmLeRG7tfu7biiqN8m
-LuZS7eCuK5r6DQqUAOiGruiOLumWrumeLuqmruquLuh+wtySqMrRAhvMLu3Wru3eLu7mru7uLu/2
-ru/OLi28Ln8UHQSwrvEeL/ImL+uigNMeiLWiK/RWqra+aICqXJ+CK/Zm76GKK/XqR7lGL/hOqrpS
-a388b/ier5xOb7DaR7dqr/u+L/eub318L/rWL5yOb+HyAqfaL//iqfBWL59d7/sOcPbG77IGirn2
-b/3ib8d6rvI+MARHcOq6rtj+K59RQw5ksAZvMAf+d7AHfzAIh7AIjzAJZzA1/K/36lrxSjALtzAE
-M+/aNnDbZi4NR+3iVi6MZq3k7jAPgy0K58ejlm0NDzHLbi758gfUErESy20Fu6jj9jAURzHNUm73
-AvHlLjEWk6wR5+/hZrEXu8MNV3Gp6rAUl/EOU7H80kcQfzEbb7EMGy4bf3EYp/F81K0Z33HeovEB
-F20ce7EbP63fhIEJDDIhF7IhHzIiJ7IiLzIjN7IjD3If/PAY81nAOqwlXzImZzLDQmwTy6iuEcIj
-h7IojzIpP3IYNK+BmK8Co6/6Yqj1EjAsg6sB9y2srjL/MjAgD8T+2vL5tjLWBnAsB7OxzvLY1jL+
-L6MvLjvvph4zK0uysL6yMEdzqhKziRozM4NvMqfyMl8z+Ppy4w6EAEuzOG+vM9sH/XIz9Gazh/rN
-NpCCO78zPMezPM8zPdezPd8zPuezO7NDOddHiD6CDAS0QA80QRe0QR80Qie0Qi80Qwf0I/SzGqsw
-GegzRVe0RV90Pm8DKq/zDPcxFs+xKz8xHo/05EL0fKyxRy/xHytzR6c0EYP0Lw/E45I0TfusHtOy
-bQixS9fwSmtzS+80DcP0NwvETNe0UefsTRdzTgP1EPc0RwvEKcyCVE81VVe1VV81Vme1Vm81V3e1
-VC+BSctHiFKAKpS1WZ81Wqe1Wq81W7e1W7/+NVyXNQWEdXwUnQBkgFfntV7vNV939SlstIr6jSNk
-AWEXtmEfNmIntmIvNmM3tmM/NmH7AF3DR4iKwxlcNmZntmZvNmd3tmd/NmiHtmhftjhM9nvYdTdA
-tmqvNmu39mM7AmAPiCqj87V6swWD8zjnNrKatnucM21jqzoHti7/NrrathPjtm4nd6BSs8QSbQIT
-t7MGt2xvM3RDq3HDLDQrt3Yztydbc3VHd2zb6ECgQBCUt3mfN3qnt3qvN3u3t3u/N3yXNwUz7m0L
-xAxEAH7nt37vN3/3t3//N4AHuIAPOH7PAG+3B/GOQnwvOIM3uIPDNwwT7hvzQhczdeIKdX3+80JR
-HzWHT/GBswdKWzjmOrVww7GIYy6GHzdRdziL12xSV/NSn3jikvh0/7SM/22KY7dItziLv3hzQ49O
-33jc0rh4m7iQ4/iHr4cd83iH+3h3x/iRD3l4s6vfPEMYXDmWZ7mWbzmXd7mXfzmYh7mYX7kOJLl6
-hGg1/IKarzmbt7mbvzmcx7mczzmd17maV4OZp8fEjjmf97mf//mYP8OUd+5wf/ezXje3Zrd2Jzd3
-D613G/quSneR6y+kOyui062iL3puNzq5Onel96qkU3mhfzqtXjrsArOmM3qez4inkzqthjqhC8Qu
-u/qnmnoOo3qqb/qqM1qr0zqownqusjP+Rg87sRf7PfNzJyc6nwF0Qze7sz87tC/0Qyd7pw8EBEy0
-sWe7tg+7RsdwLht5lL9tjiu7TDN5j+86pl1xuKMtkYs6uK+72Y47pu+4uRu1kzs6lMO72bZ7rFO4
-visuupfHktd7Td97tef7v0stvwf7QER1Xz88xEe8VoM1tZ/6QFRAXGe8xm88x8N1BQQ8edg1Xks8
-yZf8w/+1t7O0QAy2a7e8y788Y0t2xd/6QFj2aN88zue8zod2ac/8fqA2zAe90Ls8bKe8T8u6r8uq
-rQMwcuf6OHO65T560lcqsFcrdU+9pS69hWa60wsz1A9vr2M91Q86wyO92Gc9yI9H+3b+vdenvXj4
-9tlLatWXr9/4wgHcPd7nvd7vPd/3vd//PeAHvuDfPTa4fXiEaDYggeIvPuM3vuM/PuRHvuRPPuVX
-vuJng+GDB/EOPud3vud//uD7AtlbvY0n/NLKu8WvOMHbe+Z/R4ibftqOPt2XPuwjLerTvOqvPk0b
-fNQjfO0j7cKT/rv//tHePtPnvu6PNO+DPZAT/9IG/+wPv/OrrPFvPb0n/x0v/8+r+/Qzrewjsd8k
-AuiPP/mXP+AXvs9b/0Bog+W3v/u/P/xXvja0vndMrPnfP/6XfyJ8/37Mdtz7KkDwEngPwD2BBxEm
-VLiQYUOHDyFGfEjQoMAqUzBm1Lj+kWNHjx9BhhQ5EmOVgxQlplS5kmVLgSkAnMRXimZNmzdx5tS5
-k2dPnz9pejoI02VRo0ddAkhx0BNQp0+hRv156WRBpFexYkVpkWRXr1/BjjQ50GpWs2dVEh04U2pb
-t295Cn0ZE21duxCVMoW7l69bqmQr3hVsdyuvi2ERJ1YMciyvwoMhZ1XrmG1fy5fjDqUbmfPZvAId
-ZRE9mnRp06dRp1a9mnVr0T6qBu48u2VhcWdw59a9m3dv37+BBxc+HLe42LSRs5wsoJtr58+hR2/t
-SHNy6y0/8zo1i3t379/Bhxc/nnx58+e5Lzl+nX3DwhVUxZc/n359+/fx59e/n3/+/Arr2wsQoeUy
-QM/AAxFM8LxTqhPQQYWyc8CdCSms0MILMcxQww057NDDCV8A8MH2CiOmlxNRTFHFFVls0cUXYYxR
-xhOJEXHE6ya7Z5YPeezRxx89dKDBGx+MEMgjkUySwxABI5LEsngxccYpqazSyhhrbNJJHDfTUckv
-wURSyLm2dNDIMNFMc0kby+ysxCvhjFNOGLN0DMo2Z8txRzX57HPCMXmZDE/rsjvkhUMRTVTRRRlt
-1NFHIY1U0kMNYXPQwQrLJpNNOe3U009BDVXUUUkt1dRNs7H00rsmg2CJSWGNVdZZJT1kyFVpy64p
-zHjtlaa/7JQNV8EKO2yxY5H+Dauxx4ZltcvKfI2WL7kC3axZznSVVtu9gGX2WrSKTVbccUVa9s5v
-0coR2m3ZfYpaQdEVLNt26XWq23PjzSpccvnttyRV8z1K3XoJ9uldawOua96CGcbpXmETRmpffylO
-1lyIIzZq4IY5rungjO3K7pkwSC7Z5JNRTlnllVlu2eWXSdYBYJBXKqyaX3DOWeedee7Z55+BDlro
-oXGuZmaaU5qMEJiZbtrpp2F+5lakrzrTz6vDZDJYqo96c86vwYazTm+5TqvLPbFOO0lA4S27KKvV
-jttHrcl2OyKvw85b7xfHxtfuiPSUW/Ae2Ub4b5bgHlzxDOn2+3CH8N5b8sn++8b48YYCX1xzDAu/
-PKmlBJJw89EpbNxyzxWKfPLVw64cdcDPJl32zl9XKbsmlMld9915793334EPXvjhidf96NoLE0GK
-5Zlv3vnnoY9e+umpr9765UU4/vXJrine++/BD7/4Jqau/aHszF+o7vS3Zl99x9lv230y53cI/frb
-x19L/fPXX/75/6e/+9VvfekroPkOWLsAxs9w/OMFAMBhDAlOkIIVtOAFMZhBDW6Qgx3UIBXgZ0AA
-UMGDJTThCVGYQgmC8HTpg4kKYRhDGZoQHA3k3wxxmEMdTlANDuSFGnYYRCGisIcOtMAQkZjEDPqQ
-iU104hOhGEUpTpGKVbT+4hWxmEUtbpGLXfTiF8EYRjGOkYxlNOMZ0ZhGNa6RjW104xvhGEc5zpGO
-dbTjHfGYRz3ukY999OMfARlIQQ6SkIU05CERyQsgrAIh1wBAEV9ykBBCDgCVtKSdBGJJTWZSWASx
-JDj8QMlMGgMhBHmgJitJSlRWMpOaBCVZGAKERybkHsaoJBCK6ElNGkSXEAwlQ2Cyynv08pUKUQMj
-z9fChFhlkispyBOM8YRETvMufqgDQiYBjgFt5lxPWEUdRgjJ1BnOlA/E2LnKyQsL1OGX72vlJKqC
-kDv5DUopqIM004mQJ1QSdAJRAwDg+QR74rOB6VxnOxmSz3TCRJoJMYb+OIF5jZRYJQUSzYpVLIBM
-am7ULOw8CBX6eQ9wSlJYq6CCRL/Z0HGu1JwLQae1UqDNhNIFAMa4JyxJKs9zysYq+TxINrOJEGP0
-kxdUsAAmWfoSmbrHWvk8lxqWelFlJsUgT6iDRTma1aOsApn7LOITwDEJbgorBYFxnE+RSs9OWsuR
-WKUlTe9BBSDglJM6dSlPe4jWolZ0lrzwKkLUIFG95rOtooynJN0aKNAZwwI1NCoI63BUq6gBsqCj
-LD/rapUnyDKypFRDCuz5GW9WchXSHG0dYFKRVcBTq611iTUFYgEqDKWsY2VqYg9bSrje9a3LtFw5
-C/LPUDqVpzsdCjL+0erIHoKUrr1Nal2ZqlvaKsQYrB0hSvNiz5ailhfXqINBqvtDZhrEKsYAwhOe
-AELH1IGRfpilMUq7WUbG9BqjrcgkSOla/a7Eo0BgbVyR2tKFrJO179tlWlGZ35f6dqZ1HShx5Zng
-VmoSdGidxGx5MYlrBvitqGyugBtcFVQe1a4P/GU5TWkV9uK2u+M1Z2ExSZCGFsSRDf0nLyIrEEdW
-RK/79fFCUlBaAEjUqry0LS3BAY4WohW4xpXuQWDM0rJQYRUQzimEAmOBIXNYICDUZCiVW8qjDpat
-W45ubr254SuXBcUxsco1VgGOOuBSnVQAhyzJm+d0OjLABeklK6H+xGYb/pjQ/owshv+cF3TWocBn
-frJanavUM5fln4Kap5Pr6tMoU1kgQ0UIEJZC5gFF1Z255XJZBA3LOwm0Dv8soouDa2ZTppPGhgMH
-iXc8EDUXmtcISXKj6XouKgA7xI/GNF0POunABLPE0GVwTn2aAgwLRMNkmYQ0NSzYgm4m2Yalqzfn
-KlTr8pguKTYIdwMFDldnGAChdLF50ateWoM3vqsgJX3t+5L89prf1cItrT0szGIfdpXM9DAxESpl
-2aj3yhM+8J3AEWpUxrTRjjyxl+lsp4lrvJLF9DbHb6nSlyAz1Zi0ih8w3sPQDhWgLoYmBFcRk3n7
-VZYAOO9clJL+giL6t98997lDrkHqutyjoSJFilVF/nOl/7zKg4k4zTVaFNAuneorOaIFSSwYIFqQ
-qFy7egWz3pJrdB0tQCRt0lsS9aqvne1td/vb4R53uc+d7nW3+93xnne9F1KJffd72PG3db8PXogQ
-rZ/gCZ94HEIRgop3PAwHOD+CkPDxlS8hC304ectvnoM1ZDzZ6xd59yXwdaRHnek9t8DQg35+omcf
-6i8H+8fJ/nCqbz3r3ed6EU619M3sPe9RZ/vc91MSrzD+8ZGffOUvn/nNd/7zoR/942NV9wiEEiaw
-n33tb5/73ff+98EffvGPX/vaOz2UpJ9+9a+f/dK/QfkcmJ3+YlSM/scCg1lxv3u9dKxj1KL93wqD
-DepvABGjMYSPfeSPABXQK+5PkvLP+gJjV/ivYfzP984vMARwATUwJAxw0PAnATcwBDuiATPpAZEH
-SiRwAgumAoHPcwJQBGFQIzrw8w5i/mIwBknwgUzw9/ZPBVfQ/FwQSjLwBkVwBp8oO7qgB5RwCZmw
-CZ3wCaEwCqVwCqmwCpeQEBww86DkAtqhC73wC8EwDMVwDMmwDM3wDNGwCy8ACGMPSpDBCuEwDuVw
-DquQEuCPf7IjH2SHdGYB/7QwMKSEdQTxa1zHgQrjBfZwdGjHifIwETenD7PQEKEkEAexEq+kEPnn
-EB1Rcxb+sYkacRMVBxJL8A8PghIt8RRnBBP1RxNBcXA6kYk+sRXlRhR1kBQFwhRRMRddRBXxhxVl
-MW5e0YeyIw9EoRiN8RiRMRmVcRmZsRmd8RmhsRgFAQIiMROhpACAIRu1cRu5sRu98RvBMRzFcRzJ
-MRsLgA1nD0o0IBrZsR3d8R2hUQPuUID6yQaJMARzsPpOMAJ9kGFY0BZ5YQjvUQONkBHrcSDx0Q8l
-kR/7kWD+cSEPQiARkgAL0hMPciIXMB938AJ7sCHb5SGtEQMxcgErEhb7aQOIIyVVciVZcjjgQACq
-cRWhBBSkoyZt8iZXAxTQ8XAK4w5a8ieBMiiDwzjoxyD+D6ISFCQplXIpyyMDYHIUIVIgKKA/qLIq
-rfIq+YMCdhIAoWQJmPIrwVIpGWAeP7Cf9PAX44YW9ZEHb1EX3ZJvttJufBEtsSYY488s6VJt1HIj
-gxAQ3/IvV4QXCQhKEDEv65IsV+8gztIw/WQvARIXAdMtBVPyCJMxr8Yu8bCfuqADOLMzPfMzQTM0
-RXM0SbM0TfM0OTMXqBEqQ/IgeGAcYDM2ZXM2abM2bfM2cTM3dXM3YZMH4tJtCoMTUHM4ibM4jfM0
-3QAxb68GR1IBNRIgU9AjtwUkZVIkm3MAS1IYL/I66e85o5IXolM6pYU6e1EIubP+svMumfM8K8Y7
-W1P+IMJTPH2FPAfTOtnTX9IzM9fzPvvFPauzI+UzWuiTMu2TP8klP+nxIIbgOBm0QR3UNLGQNf9T
-IKCBNy30QjE0Q3cTGn6zbAojFx40REW0QZlAOYdPMS2zMRXyPaMkMl10MkevMlOUTzAzQQViMWcU
-TRzzOyHTRVERRl9PRnMUTWq0LFF0SHV0RSe0RX30L4FU/wSiMJEUTIo0MW90SsNkR1m0R5u0Ep8U
-Ag9CSrF0bUwUAftpDyQgTdV0Tdm0Td30TeE0TuV0Tuk0TRFhNWvxO3VhBfi0T/30TwE1UAV1UAm1
-UA31UPlUFzqUawpDEer0USE1UiWVTuWxKC1yPw3+dFz8szwZMkDHc1Gp5gUz9UDLNH1AcFTFZVPr
-E0A9lVcGNEYLFFWPBUGNVCDsUVbtT0k5lVVb9TJeNUhjFVcTg1atlBfQdFKRNVmVNU7vNCZ3VSD2
-FFGldVqptVoNVVH3Z0kddVm5tVuRtVKrhQavdEyVREuXlEu7VBC/dB/DlFyVpEqXc1zd9UjM9VmZ
-NF1zcV3ZkhfEdF59BF5PVF791UfqdVXbEl/zFVSRZi4HlkcA1kyPtGF7pGAJtBQRNmGz1V77VWI7
-5GFNtZ8WdERFdmQh1FkNlhcqVENVdmVZFjc5NGNPFkRJdmZpljNL1FJNElOFNTFUtWLhs1cFVGH+
-aUZUd1YxiDVeeeFWizYsehZWeRVop0VoQYZol1ZZStV8TrVqwaJpgfVpoRYufhVKA1JrC/Bqaydr
-ybYruFZs4/NrwVZqM4Zq05YkjjZgeeEcYiFv9XZv+bZv/fZvATdwBXdwCTdvyQBP15IjBYIHkqBx
-HfdxITdyJXdyKbdyLfdyMbdxfRNmfZYX2KFwQTd0RXd0CTc5cVY7I5ZjPYRinfZgL9YS9VVx+VV1
-HdZsXycWaZdDWLdrXfd1BzF2+7Jdc7djbRd1cHd4M2R3xRZdfTdvgLcNA2NjkddCPBZr+wkpwzJ7
-tbcpnzJPWXQqsTJ8xXd880MrObd1ecErt3f+fdmXO8bydNVTIFBSKOm3fn/yJU22c2kSJ/m3f2tS
-J8+Xd3nBJ+23gA14KIvXc9B2bkVibcH0Z93WV+E2YuSWgTkwgS9ngS34IxyYXSE4gvsibB94bDdY
-LDD4cTS4hDmig/e1bUFYKkTYg0lYhRnjhA9nGOExh3V4h51xGvMXfbGxHIV4iIm4iMfxHANYbNeR
-h5m4iXMYXA/wY1N3ei9EeUeYeZsXbJ43HaOXijWkes8WL70YQ6xYhrE4i+dki3lSSMe4QsD4dsW4
-jSukjPf1jNE4TtSYK7tYjt3Yhv/meOWYjmXXju/4Eic4YRhWjt/YeDWTDh35kSGZCiPUe5f+lAvT
-8JIxOZM1+QzXMIlH+A0jOZRF2ZHtEH7101ZpOCRYWHZd+IWhIob3VSJTeSPqFmJReZY9YpWD94Nd
-+S1gWXZlGZf/xZRtNGmFeQR19WRbuZeB4pd3eYaPOSNqWYpvOZozQpeh12uZuZkPOWAq+Jin2XoP
-Am9Jt5zN+ZwD93B/WIAZN3Pd+Z3hOZ4vd3P7x14/F53xOZ/L2XTD9QjjmI/dQZCfmZALuUryWC7Z
-mI8XWYH/mY8FOpt7t6Cdt5vzJZHbeKEzuKEDOZk7l6AlOhUpOl4seowxGoX7aRDaN6W11ynXWWwN
-gHxhOqbF1wBCGl0KQ31VOqeXcgf82G7+smN+DziohfoM8FdC7XV//TeplVo1ALieT5aAhzqq7Zco
-+9koq9mapwCbuVibt9lgavpbvlmYwzmMdTaatXqNO7Wro8KZIRqarXms4bisj/ms9Zir1Xon2Hqr
-BSKYxbqn3QYJPSCwBXuwCbuwDfuwETuxFXuxGVuwEZcv25oZYGCyKbuyLfuyMTuzNXuzObuzPXuy
-meGrr6UwhKCxTfu0UTu1GRsQ/LpsALmNH1qv7/WjW0e0m2Wkvbikb1ijYZuj0dejaZtObHtYcJuK
-dfuPeXuMYxutLTa4a9uTZVh6Sbq1uea1ldu3BRi4nbtFDho4E1qRqZtqskMZ8qG8zfv+vNE7vdV7
-vdm7vd37veHbvCEpcZ/ZBVrgvvE7v/V7v/m7v/37vwE8wAX8vl1guHGlMCohvhV8wRm8weE7CsIb
-aeiboQFySS0cf6JYnFH3Oy/8ZP3HA4v1lFm0wzv3wxkvgjgvxTFowtOR8lT8xVfIAoPQxWFcxT3v
-iWo8xyUI8A5Px3Pc8OYH8Xw8xfeuyI38yJE8yZV8yZm8yZ38yaE8yqV8yqm8yq38yrE8y7V8y7m8
-y738y8E8zMV8zMm8zM38zNEcInLsINZJnyoMxO1HwoBLzsnJlRIuIVgNANhrxlYJyr4JglIA7UTM
-koDgGhKNxdP8y1Mg3ARikbbpw37+qOZujiHwpcmeC9k8iiFMSqKuAQgUDGO8axUkirKmLamugYSa
-LdFVHbAAoKH2qZ2sqdxsLb5QndIhxtIjzdRiqiGgJMz8xrz0KawGzr1SfdWN/dYEArZ07NZknbqK
-btAqfbdyvbmiLCH2/CSkCV/+CptK/cmSfd9AzNiNfdEFYhX6qbrazCF23dYV7tJPzXLWaYR0ruFM
-DdLpauxETsbFHcz/SZpa7SXmKt0XgtVOp88RjMK47N0hR9oAgOTo3N3JYsSKfd8T3aj8QKZEiqDs
-XcOMgcXoHaei/bmqvSHcq4e0va9+Sui+7ZsmnuLRfBIWCXSCaZfQKqamKuTDHdL+82ndXSrf82wh
-gL3T7uHpSq259N3lu9yR1I2lfGrbk6ndpz3Aug3oO96vTMrZGmnF2O2mih7cWh7pzdzOSu3PjCHR
-eP3WaarPyR7kPG7g/1zrTwmVKgLOwKmmkN3ACN3nwX7v9UcNiI3vAT/wBf+OUuCCgPwsvo6CeLwo
-MGjwHf/xIT/yJX/yKb/yLf/yMT/zNZ8zQKvzPf/zQT/0RX/0Sb/0Tf/0Ub+ifGjsUr/1Xf/1YR/2
-Pf71Yr/2bf/2YZ/xCm73eb/3ff/3gT/4hV/utXD4jf/4kT/5g78FL2fmlf/5oT/6f19cR9xeSdx9
-Mrz54dxur1+Au9+Ftn97wp/+mqvfw60fw8c/9dKfrAViAsrh/eE//uV//um//u3//vE///Uf/g18
-VQojEgBCmsCBBAsaPIgwocKFDBsKjMQr4j0A9yJavIgxo8aNHDt6/AjSYwoAFp+UO4kypcqVLFu6
-fAkzpkyUEyyODIkzp86dPDUCSGHRwayhRIsaPYo0qdKlTJs6HbrE4sSKPatavRpyqkVuqrp6/Qo2
-rNixZMuaPYu2KzepFLG6ffv2psQMT+vavYvXqQObJOH6/Vv1Z1B3hAsbPow4seLFjBs7fkz4BVuq
-gCtbzqg1IrFenDt7/gw6tOjRpEubPs2Z2OTLrFnL5XVvFuTZtGvbfrw34uv+1rwtC47o4Lbw4cQb
-S5bYtrdyt5l5bUYNPbr06aZVI6e8PDvP17GLe/8+PDev3drL8/zNKzj49eyNrzYPH2Tz59Tr278/
-2jrs5PH7b+QuW3sCDkiYeOT5h2BG6O1gSoMOPghhhBJOSGGFFl6IYYMIvJdgh83Vs0uIIo5IYokm
-nohiiiquyGKI9XDYIYKvEZJhjTbeiGOGO/AVY48WoacegUKCd9x+2PkI33z4Lcmkffo1hyR8AA5J
-pXcG9hVlgkBWyaVwRUKZpXZKNklmmaU9yV+Y2k3ZZZuzXakmglu6Sad718VZ3phm7slnL2geiSdv
-bNZJKGJwBgrfnIUuGhn+jIi2pmefkjL556PKDcpooYdamh16wuQIaqiiWsiJo5xW1pwsi6zKaquu
-vgprrLLOSmuttq4qi6mn/vUaBAiMCmywoQrD467KKZopoV+maexfkU4KbX2VNlsZpsnSuSm1lyF7
-rZvLAqotVs9GSy5004YLl7Xddpktun9xuy6X37oL17jl3kvaufRepW68VLa7r1vonZJXwQYfzFRU
-dwZ8VXNxyAFxxBJPTHHFFl+MccYabwxxHLoynNNrAtCFcMkmF3xKsSALDFRElrwBc8wyz0xzzTbf
-jHPOOu8MsyYfrywffxSkRXTRRh+NFgU/Ay0SlgLQw3PUUk9N9c6WqMz+dGAtp+evt0tnvZG9+I79
-mb5gg9Rv1wQCfDZO8KpN4LxtZ8UffWTfXfbXc6vcHdxVsr23R2/73Z7cgXckNt5jm314RmkTvh7g
-jfu0dRFmXI555ppvznnnnn8OeuiiX86O3oE390gAqq/Oeuuuvw577LLPTnvtqj9i+t69cjF6777/
-DrzoRWA9eUeDQ05k7nMnrvi9jBevG5Z9Iz+g5ND/uHWQ1BeufNvMN0/u89A/vj1x1l/Py/HlD2c4
-+gs7B37z4hdP/vq3nX+9+vbb1r7738c/qflNrn77ow3+oIceEsxhgQxsoAMfCMEISnCCFKygBRdo
-j+6drTlYmIYHPwj+whCKcIQkLKEJT4jCFHoQCxoE24wuCMMYynCGFyQB8dx3Ef0VcDb9Q9//ANgn
-ATaOgDvEzQ1xGBEdFtExPbzeD4G4JyEejohLZMwBi6fEKi6midB7IhTLJMXAUVGLibni5LJIRsRw
-sXhe/GKTwqg76QUojbUxY+PQA4Vg6HGPfOyjH/8IyEAKcpCELKQeR9DCrKXqCIxspCMfCclISnKS
-lKykJS/JyFy9D4e9UoIhPwnKUIqykFA4IhLRSMfCrHFybXTjkuA4tzGmskCmxCEqZ7nKxrXSlfeB
-ZdtkOUs7Hu6Wqczl4XbJS2klkmnATKUwAzewk0lzmk1RmJGQ+L7+h3Fsm9zspjc15rFNuk9kJKOm
-Oc85i5RFD5sK2trLqgbPeMoTZz4Tpw+FhrR86nOfZlGaPa8nMqjNc6AEhefV1snOHGZvlrQx5unq
-lszwLRNozaTjM/dGTDo6dG/IjKh0fHm2iqbxonPLaBo3ujyIejSAE12ZSMlI0rahJxEmqKlNb4rT
-nOp0pzztqU9/CtSaluqfXeQPC8KB1KQqdalMbapTnwrVqEp1qkhlQUtB1qs+BHWrXO2qV4GaiFq6
-Dz2eKIVZz4rWtKp1rWxtq1vfCte4mvUSV2VYc6owhbzqda987atf/wrYwAp2sITNaxXqGjDu4EOu
-jG2sYx8bV0/+iBV9ZIWsZS+L2bfSlahs5A9eCwva0Ip2tIM9LGcHKL3FZna1rLWsZBGa0CRurayt
-ra1tNYvYfd2VtLztrW8Fa9prYlOxty2ucc/62vFgKbaVPa5za7tZ4SJxt7+trnV5G1wwoY+4z+1u
-ZpN7IGyihxEgKK95z4ve9Kp3vextr3vfC9/yLiO39GqOOtKB3/zqd7/87a9//wvgAAt4wPhVB33d
-NaP4KnjBDG5wfBkx2fzN1rsUtmx0tetEz153wxwu7YHRxd0Ki1iu4F1uQps74hS79cLMuidlPtvh
-GMt4CtltMUBTq+Ics7XEscWeRWir4yDP9cPhou6Mj3zdGoP+a3w4FrKQedzj9E3YyUFm8ZI7+2Ik
-a7m6SmZniKmsYij3GD0JmIeZz4zmNKt5zWxus5vfDOc4mxkHRNZWc+yAhzzrec987rOf/wzoQAt6
-0ITOsx3qTK1epULOjG60ox8d5wREGIFTBrOKrcxOI29506Lt8nCbbOkUi5m5lQ61iDGNTU1zetUe
-Pu0QQW3qCo/6xKWOtXdRPV0Ns3rXwEV0s75s6+7Omp1khrSxj43sN9PZ1cfkTzzYAO1oS3va1K62
-ta+N7Wxre9vQjoevjaXoZIt73MeWNGxJ/eNgVxjXOFQ1r9+tV08jEdjqPu6wxVvrehuX3f7TNbz/
-bdhv74r+3vq+7b1Pme+C25bfLrYIjAEOb3lzEtYKN/iksZjwirOW4RnOMsT/LfFxUlzjrT24LbdG
-XgerfOUsb+98mf1QyqAjDTSvuc1vjvOc63znPO+5z39Oc3QI/FQJbrnRj75yCJ+b1ukm+W05XlSP
-f/zdId/uyJ3+3YufMeNYt/DQOeXuqXO66jeWimq7zlqTj5XraHcs1LHscLFT/euWInjbH6t2yrL9
-7nJ9Oyv9LfdVk53JZud71pdO7K1xgACMb7zjHw/5yEt+8pSvvOUvz/ha0P1RzXkHOj4P+tCLfvSk
-L73pT4/61Kv+8+/YPKJ69QfMy372tK/95Tmg9Tvu3fD+uIU5RwEf+E0Pnn5X5z2Jcz/M3RufrX7X
-JfCDr+Xho7bwy8c78qGp/OqntfnNljr0tyz9V1Nf+4zNu4QtogB8qH/97G+/+98P//jLf/70r7/6
-C+H6QDXHG2Dov///D4ABKIADSIAFaIAHiID95w35hyciwwr2B4ERKIETWH8KcH0YtTWOkAUbyIEd
-6IEfCIIhKIIjSIIlaIIb6AMMGCfNIQ5n4IIvCIMxKIMzSIM1aIM3iIM56ILioIJqIjLdcIJBKIRD
-SIQm6AgXWFLZR35D5nsp5X3fh2ThN0XFt4RrZX6U1nRVCFfcF3NxB4Xg14NhYndamFZXiHFZSIZt
-xYX+v/eEXyhjUihGVJiGZmWGW2cRw9AGeaiHe8iHfeiHfwiIgSiIg0iIeUgHYZglzQEPZcCIjeiI
-jwiJkSiJk0iJlWiJl8iI8ICIUdIrD1CInwiKoSiKhDgMSChTSriEa+iEXuiGRwaHcTR+c2iFpng2
-KCaLaqWK3vN8rchhrxhLcjiHdah7aHiLaJWLG7SLvJhkm4gkYyiLwph8xFiMTChd7ZaMyshlzOgj
-zhiMtAg26PEBkCCO40iO5WiO54iO6aiO68iO7SiOGKCNPdIcRlAM9WiP94iP+aiP+8iP/eiP/wiQ
-9WgE8Rgjr6EG7oiQCamQC+mOH+CNWYMe1nhlfzeTkc5XkVOYUOGFcJlmY1HHkRcZhxlpYon3kSWZ
-ah1JfCIZZeljDCngki8JkzEpkzNJkzVpkzeJkzlpk6uAkn+3CjoJlEEplENJlC7JkyAZR0WplEvJ
-lEFpDCMpXgAglVNJlVVplVeJlVmplVvJlV3ZlUiZUl4plmNJlmVpllUJlr90lmvJlm1plisJl3Ep
-l3O5NwEBADs=
diff --git a/Documentation/DocBook/media/fieldseq_tb.gif.b64 b/Documentation/DocBook/media/fieldseq_tb.gif.b64
deleted file mode 100644
index 7b4c1766b407..000000000000
--- a/Documentation/DocBook/media/fieldseq_tb.gif.b64
+++ /dev/null
@@ -1,445 +0,0 @@
-R0lGODlhdQKaAucAAAAAAElJDK+vr1YMDBUVZC8kDQAAVkYQEBcHOwYGSCEJHSAgaKOjoys8DDMz
-CgAYGp+fn19fFJmZmQoKO10wMA0VIAAAcDsICCsMDAcMT1MMD2ZmAAcSO29ISFUHByIAGoiIAA4H
-T0pKDJaFhXd3d0EgABoaVGYyAC4AKXd3ODs7BwAAN1MAKQAAYlZGB2JlDBwcWWBtYCA3ABAQTQAA
-ZQ0VQD4AAFVVVUhjSCQMJQAAfBMHMkQgIEtLSzAyDD5VPmZmDEZRB2FhEWZiDFo2ETkdCwAAVEUt
-Gu7u7js7Ozc3N3d3WACPADU1NTMzMyBRIDgAAEJCEHEAAEwNDZeXAABpAEQFBSMjIxgNQDooCBA9
-EEhIbwBVAAw/DAwMPgBNAENDCgc9B8zMzABDAD4MDAwOKjwKCkQWKUscHAAAcUtLFRMTEwohCoqK
-AA0NTBEREQgfCBUqIgApADIAAA4ULzg+DEEfH3wAAAcHSaqqqlkcHDgMDKSkpFQAABUVRjEwCGZm
-B00QEDAwXSUMJGUAAJaWlhQUUnx8jVQaGgcGLggSGy8GBmw4OGNAL4qKioiIiGIAAEsHB3JYWHd3
-AAAAPlctLYQyAGggIBgAGkIVFQwcJRgYSA8MU9EAAAcHVQAALRoaYbu7AEY1H2ZmZlxdEHAAAD82
-DlhqWExGHgwOUzMzDAAAmgA5KTEHB2ZmPlpaB///////ACISRExUDTJPJUQrDAwMVhISSEhISHd3
-IC4xCjhcOA4ORERERBkVXElJAG5gYFhYcnt1ZkgGBlYAAAUFMTg4ODo3BTJrAFESEmZmMF5jBwoG
-Q1paDUkKChxGHN3d3RwYRGZmHCgoKFMAACYmJi4YLhQ+FCIiIhU0FT0AKR4eHmVeBw04DRAsEAwu
-DAc2BwoqCgAAPFdMDQAA0WAqKgwiDEgZGRkQRAckBxsTPDEwDBAQEDwAAEJGDAAAU0FBQEJCDLu7
-u2IYGJoAABgYRjg4bAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAEAALAALAAAAAB1ApoC
-AAj+AGEJHEiwoMGDCBMqXMiwocOHECNKnEixosWLGDNq3Mixo8ePIEOKHEmypMmTKFOqXMmypcuX
-MGOelAegpk0AJFrSrLhTpYQ3AHoeDFpQqMCfQQHIXEh0olGBYkZtpGkTW56B0EYBfTMKCUEJEqja
-7DpQDIAbBJsOJHF1qdu3cOOqVKtTKcWnEOnmlQALWk6Eep8C4Ou3YWC7JUlAg9VUL0K8vcRMRUwC
-gFdoXBdD6+WE4A0kQqE5kSqwsuWBepFg8yq3tevXsPPKg4n3YW2HjnHPZrp7oODehoHDui2ysfDH
-iKFi42iU6A20A5G84SsQrdE8iKdPR3181KPY4MP+NySBC4L4lHRJAI0MSwwJ0++B5nSvHqdAJPVv
-LHb/U54YJzX99RR+QOnX3ntKidELANiMYlce2DB4FX9vHMdYTfIQeNZ+8dlHkFg9QSihQEQpyKCD
-H9q0E4X+AfhGTir6ZhMskWGTU33Y8EWffFC5OB+CONX3V1BixVgfe7DgWFlB7621nmRMAjBdLwk1
-Bw0SAEBZ1mKw5PHddQ9aNgp0jB0nQWfnpanmDTVNU56aI6lFghOLkbAcTVJh9xl28uCJBDQ2Jkkn
-EqN0Js8bvWTYy3dmzfbUnFcWOhxXsznxmWhKHeooANAcmihrBhEFKaGGAtAVoH9xN1ymFa66GFH+
-lv4JYEFE7eRphi/21ephJDqRR6fY1MlqnlnCkitmfZra5VlI8Fnms89CmuRy6jkKVEGLlkbntEwG
-CwuKyK2VE3HfLhaapQKNuSxrjpkF50Sg9SnvvPTWa++9+Oar77789lsvPDcBsE0Tqb67kVpWDVSh
-UMbRxKUEy23XV5YOFwRNrckZS93FYlRs1sNKjZLqDSRUnBBREnNsMsS0bvrtyDD6x+lRGWPsqkCZ
-pSVcT4MZtCRN7M6Ws0AM70bU0UbPljDO8uQ4kAQ177a0scA5TWKVAQ8mVJECUbnqTZ/h3NYb30Hb
-ssEQFZn12my37fbbcMct99xxo62RWlknq2r+mVsrhbfeRzmBDZsu68xdT33TGHDJGYc629+JG77T
-gjfFHLmqtiKWFTZv3CAZr9CKcQOiC66q6uadd4yYcc+ynrdav5EYMHAIYx2dVljunGnZtWF3E5q5
-5Wb3QfH6a/zxyCev/LwAB3xFEoUMnxHCuu9N5Myw/KSxQCrbZRaUNhOUMsV2XQzyy0U1fvb4qj/8
-xtk7iey4+TTDn2njBJpNtF1N5Wp60QQhEABb97ikwQIbwrFa9qImEAQmRGKMsZ2MaESmdCmFBFCq
-zShIs6xXWUh40gthStgEAHZYSksitIictvWIN4BmdUnzE6oEFalSQaVYjwDAVR41KEkJpRf+l5qV
-piYFuOEUjESzGZUPTfWnQEmOVdYqIAVlxcDMKewvdtKf6aBFtr4s6IWq8p+dBog0xrRFVCx0YbWG
-EyFslU1aLfRKyaa1GHDNMUW3QwtmDOSXa3ltiwF8Q1tw9p12qS+FiCxJoTyXyOkBpz5OkAwZk1Uf
-smgobEI5UmUeMaD8eEUoSFjQlI4SIadlsnEAEsMlP4kToJDliaRkEHWIEkopSeCPSPwfYvIAoLNI
-JpUEwcz7mgIxBqmnQjDsUi89N8lniRIWwIQklKSJyyRxUJokygmhbMm/I6otbH3RijFp5J4JFkR7
-BJFU3rJXwUa6UySgemddxHPEhZBLnij+AVRDVEm097XmBtTBp0AHOrx7ukUeZXOIQQk6klFYqCBj
-QgISbsBBuOiToRjNaHgWCieOarQjhVnIRGsCzriE5aMoTalKV8rSlrr0pTCNqUxnStOa2vSmOM2p
-TnfK05769KdADapQh0rUohr1qEhNqlKXipARSOKpUI2qVKdK1apa9apYzapWocolgxwiGGANq1jH
-StaymvWsaE2rWtca1oTE4BRwjatc50rXutr1rnjNq173CtcYJEQYSwisYAdL2MIa9rCITaxiF8vY
-wAojIVuNrGQnS9mtAgMh0GCrZjfL2c6y9RAOYUQnRkva0pr2tKhNrWpXy9rWuna09Hj+6ALIQdva
-2va2uM2tbnfL29769re0bUFCnsCE4hr3uMhNrnKXy9zmOve50C3uExKSi1hY97rYza52t8vd7nr3
-u+ANr3VzkRBIvPa86E2vel17icesArjwja985/vbBYR2vfjNr35ZG1uEzJa+AA6wgHkrXIQQN7oI
-TrCCF/zc6SKkuuKNsIQnTGHwkhch5t2vhjeM3/YeRB7vHbCIRwxg+zZEtBxOsYr5K1sSu/jFvi3w
-QQ7M4Brb+MbMdfBBIFzhHvv4x9298EEyvOIiG7kTHjYIiGHM5CbX1sQMQfGRp8zh/h7kv07OMoll
-bBAa4/jLYF6wjg3CYyCb+cwUFrL+QYhM5TbnN8lFCbGW5yxgKC/EDlPIs573zOc++/nPgA60oAdN
-aD3zASF+cIOiF83oRjv60ZCOtKQnTelKK9oLCfFGNzbN6U57+tOgDrWoR03qUpt6095ISBSawepW
-u/rVsI61rGdN61rb+tasjkJCzFDoXvv618Am9B4QwgdLG/vYyE62pf1wXzc7e71WNgiW6Uxt+XK5
-IF4Os7a3vdwxF6TMaA63uLmr5oKw+dnobi2cPyTnaru7vs1Ot7xXG+2CTPvd+NbttQmSbW77m9ve
-Jgi4x03wcZebIOeet8JJu27ftDvfELetnRUi5YVbvBP1Jsi9Ix7xfQ+k3/8O+Zf+Az6QgRf85GY+
-+EASfnF5N5xoD+c4xCeekIq3fN4ZH8jGZY5vjwsE5CIPOoNJLhCTo/zoFVa5QFh+82e/fDgx5/m7
-aY4QHgzg6ljPuta3zvWue/3rYA+72K/uDAYgpB5eSLva1872trv97XCPu9znTve0JyIh5uiC3vfO
-9777/e+AD7zgB0/4wuvdHAlRBRAWz/jGO/7xkI+85CdP+cpbfvGqSEgrxs75znv+82LHAEIYMIG6
-m/70qE893esR76bLO+cC2bnUq+1zWABd6LiPLtFhYXSk+168SocF013f5qcvefYzbz3xnw17WMge
-+XOu/e1zT/0cU/f32E9zeZf+73L3Qj/fVD+Izbnf5uY///tOln7116/762f//eEN/vDJX2TjRx39
-WQ6/QcpBj/77//8AGIACOIAEWIAGeIAI2H+lIAAIYQJp8IAQGIESOIEUWIEWeIEYmIEa+ICUkBDZ
-8AUgGIIiOIIkWIImeIIomIIquIIgmA0JoQZtEIMyOIM0WIM2eIM4mIM6uIM8GINqkBB9kIBCOIRE
-WIQImAwIIQDvsIFM2IRO+IQaaAIOUQlSUIVWeIVYmIVauIVc2IVe+IVgWIXUwIAHAQqrcIZomIZq
-uIZs2IZu+IZwGIdyeIZGkBDXUAV4mId6uId82Id++IeAGIiCOIh4eA0JEQH+oZCIiriIjNiIjviI
-kBiJkjiJlJiIEZAQNhCGmriJnNiJYJgJSWgBcziKpFiKpiiHoKB89Ddl5od/7qZ+7BeL1vdg8FeL
-3iV/q+hs9ueK1aZ/BTF+uVhkrciLdAaLsniMx7V7vWeL8IeLwUhlu0iMc+aLBAGMz5hiwyiNWWaM
-yIiMysiM4IhdzniNRhaN2uhk1DgQaBAJ7NiO7viO8BiP8jiP9FiP9niP7DgMZncQt+AJ/viPABmQ
-AjmQBFmQBnmQCJmQ/lgMCREO4PCQEBmREjmRFFmRFnmRGJmRGvmQ4ZAQYPAKIBmSIjmSJFmSJnmS
-KJmSKrmSIAkGCWEF+Bj+kzI5kzR5j8N2EAyQAAq5kzzZkz6ZkLegiuRYZS12juk3XN2YlN8YjuE4
-jkOpYuZolDCWjgJhjU+pX9kolS/GjUkZi0vJlMzolFe5YVGplSRGlbBglWMJbUVpli7GlV25fl8J
-lrUolmupX2XplgOGlmp5l+iVlXo5YHAZl9Q3l3T5fnbpl+uVl4FZYg6RCTUZmZI5mfZ4aAcxAz+Z
-mZq5mQeZAAnxDWEQmqI5mqRZmqZ5mqiZmqq5mqwZmt+QECIACLI5m7RZm7Z5m7iZm7q5m7zZm7Ip
-AglxAZQ5nMQpmTdpEHzAmcq5nJs5A0KpmOkFmI0JYINJmLhnmIeJfYn+CZ3oxZjTKV98yZ1Y2Zbf
-SZ1IaZ3sh53Z6XvbKZ7s5X3lGWDh6Z5s6V/xGWDViZ4ip57reXTtSZ+r5Z336VvzCaB/SZ4DCl/5
-qZ//xp/9eXL/aaCoJaAJultoeQ6QkKEauqEc2qEe+qEgGqIiOqIkmqF9sI8GwQvisKIs2qIu+qIw
-GqMyOqM0WqM2uqKfkBDpMAY82qM++qNAGqRCOqREWqRGeqQ8mg4JoQKT0KRO+qRQGqVSOqVUWqVW
-eqVY2qQqkBBQUKJe+qVgGqYk2gqjtwI3eqZomqZqaqO88JwSmlrSWaG9taAMCnDu96C/F6FvWloU
-Kqe4VaB7ymL26af+wEWndaptDoqnBrd9gapu8EmoBOqmjUpacQqpuGWohwpmiaqo4aanjdqnlkoO
-FyqmpFqqpiqiJ4oQKrqmrNqqrjqjOYoQcCAHtFqrtnqruJqrurqrvNqrvvqrtAoHCfEHv1Csxnqs
-yJqsyrqszNqszvqs0Fqsf8Clp1qt1lqqZIqTZvqq3NqtrNqmJzapgnploTqn55mpQbepnHpmnhqo
-oGqpgCqup1Wp5Rpc54quIaeu6wpk7bqn7wqp8SqvpUWv9Yqp+Gpj+rqvPtavb/qvhBqwAgtbCFqv
-tmWwBzt0d6qwBMewEuqwfoqWHXAJIjuyJFuyJnuyKJuyKruyLNv+siOLQgRhDwswszRbszZ7szib
-szq7szzbsz47szCQELTwBERbtEZ7tEibtEq7tEzbtE77tERLCwmhDLlQtVZ7tVibtVq7tVzbtV77
-tWBbtcqQEHrgsmZ7tmibti1LAQghBj/7tnAbt3L7s/bAVHZ7t3ibt3q7t3zbt377t4AbuII7uIRb
-uIZ7uIibuIq7uIzbuI77uJAbuZI7uZRbuZb7UhCUPf50HwJySIYRMFTCM6ALSDJSFYPkM2szG4Sy
-Fa90ITZRUpcbu7KLESRQQRRFEEtCulBBQrB7NumTS78bvJp7uh+WHHukGaPDJU0hGu00u877vPt0
-GrCAJYOUB9f+orsH1BVI4ATVZDjB6xh4YRRZpBBGAUQF8RzAuyzQu77sqxBWY71YkSN2ARmsQRzg
-yz/HEb7Giz3hch/FQhBm4RVqgR3tW8AGnCTQIT9dw0nz67ncAhj5i79K1jixI0HYS0Dcgy4HvMHP
-G8DGMk3W0cAIIUAnEzD7IzuVg70V3L8XfDQ30QvxxMEybLlOIAEQ0k+sdMIG0UK90FVDEcHpa054
-hBX8W7zR8b9lcRogNMNMLLmPQFFYlDd4MUYMcb9BrMNDXBrLQb7JYb6eAR1L3MRi3LgXgw0wu0UD
-gsQKYcVapMKI8RPEO8HB1DnI+wbK+1BjnMeMKzhG/DU2kSj+WXMyQOy6N+HHNRG6NzE1Fnwf4jQ0
-bazHkBzJkjzJlFzJlnzJNEUCvbDJnIwkInFLnbzJAYXJpFzKpnzKqJzKqrzKrNzKrvzKsBzLsjzL
-tFzLtnzLGhHKurzLvNzLvvzLwBzMwuzLo8xSCjLMyJzMyrzMy3zGKnXMzBzN0jzNyXxTDELN2JzN
-2uwhLkUT3KvN4BzOyAwgePxR3izO6JzOvNxGNsXNLuXOLEUT5axR8gxT9fxSuVtT8MxS+6xS99zN
-YZxR/9xS+UxT/axSB41SAx3PAY1RC71SBT1T3CwMjFDRFn3RGJ3RGr3RHN3RHv3RIG3RXZXQ5qwW
-OLALKJ3+0iq90izd0i790jAd0zI90yiNAzIyzwKtFiG90zzd0z4d0h2wFg7cUtzcl5MabSRNz2ox
-fRd7Yzr20P6sFvMnrkkW0TJV1BGLWkhdT1HdG0zd1DX21A3NUP881ZNa1UPNz6li1I261fa81GDt
-b2KN0w4t1Vl9WmhtzWt916bl1i/1z18d1wo212/dG2b9qUKt1+pYnIzd2Paoj6jB1Sn1z2zQmpZ9
-2Zid2azJBjdd2AMBk44d2qLNjsdp1TGF1XxNqb2R1Dnt1YK9bYT913ad2qOV1+2817SNcast2QoN
-168dZrEN0Iad20iW2Lc9EGwdqH4t3B/328Dd2bI93Ln+bdv6nCpU6InYnd3a3YVjGNmeLRAfyILi
-Pd7kXd4q6IL7Q9dkrRaZuN3u/d7YDYqlkdYrxc38Z4T4nd/6XYAL6N3RPRBaQIgCPuAEXuCDqAXQ
-zdwCEYT73eAOjt9ION+KXZXEvdwtBdjOrakJfuGzTdvUbdC4TdsWztCuneE4FtwcLt0ebtzVjdwV
-vtvfbXsmfuIbTuIrR9wfLtGpgqHX2uM+jqooytp13RuzCqxGfuRInuS+KqzpHeNd+uNQHuUZmq1J
-Qt8IHeKpPeIrheEzjrA1vuUdnto5ftVYztda3tXN3eVh/eVovnQ4zuIg7uK5feaT7dtqLmZsXucq
-Lub+cK7jci7iMP7fP3fnGNvkgi58by7hxy0QeBZsjv7okC5olskYvF3SvaFpp5bpmr7pnF5qqWbo
-Cg4LvBbppF7qjl7aVp5SqA3o/h3qgU3oyIXiNu7m093nZP7nWR7org7rg53nvb3nfD3mp13md03n
-v57mvN5+oJ7iN17rit7iFD7nus7sg57syr4q6k1QZZ3oVT7hsMADZBDu4j7u5F7u5n7u6J7u6r7u
-7B7uZhDkla7UvZF3hlfv9n7v+E54iLfssw4Li9DuAB/wAj/w7C56zx7n0c7q2RTjr27tsg7mwH7X
-wg5Tq57rrU7tMm7t0PXwbY7ozt7ti56WL37x/d7+8MnO8Xre7Ct+8H4uENcN3zAf89xNhpQe4+Ft
-3jif8zp/guiN7THe3jIf9EIvBfIN8tAOC/f94Eq/9PxN80K+3r1xhwY+9VRf9YBoiPwO8QPB4Ezf
-9V5PDxFu9Agv8tJO8lpf7RrvXCh/7LS+8mLf8mSv8DV/6CbP62tv6SrP5yx/6wlv8QtP92nfYL6O
-922v92/P998Oeoq/+IwPdmVn9h1vDt8w+ZRf+ZZ/+Zif+Zq/+Zzf+Z4/+fvu84e+eY1f+qav+AZ/
-+MOO62Y+7SUf+Go/+PKe98Fu66vf960P+SmP9rCvXHc/+4Vf+3t/+3Hv93O/673fbbLf2rQv8bb+
-T/HEntXGTvgZn/zJ9fvMH/zOP/zQPxCS8NPgH/7i/9Fa8vTarhY/QNPqv/7s3/4z/QPLP+QDQQHj
-X//2L/7P/1LmT1D7L1BQvfsAAUvgQIIFDR5EmFDhQoYNEcoDIM/hRIoVLV4USAIARo4dPXYEQOLj
-SJIlQ5ZEmbIiRIkqXb48yBLmzJkyad5MqRHnTpgnef4EKRLo0JURiR51aBPp0odGmT4tqBPqVIQA
-epHAmlXrVq5dvX4FG1bs2LA+qT6FOIrsWrZt3b7FOsrpWaZp4d7Fm3dtr410/QIAHFjwYMKFDR9G
-nFjxYsZC/SKFyFjyZMqVLQ9u+fho5MudPX/+pqxZ9GjSpU2fRp1a9WrWrV2/hh1b9mzatW3fxp1b
-927evX3/Bh5c+HDixY0fR55c+XLmzZ0/hx5d+nTq1a1fx55d+3buFN9IICjhDUEkQiFyJNwL1nlY
-6df3JcgZALY8Cgc7yQxt1Jv5JJC8J+yGwoSSwAnAnABPoPkKkiuz7h6EMEKKSLiBoBtGIUgq9ggS
-Q0AAbvivKgcFYm+ugTY8ET7x6hNRICT2+w+aN0aBBhYxnHCiIBMVdHAUJ1jMwwkM2wNADIL4G1FC
-JZdUUgwAQkQCABZhyYM/EuEbCJtRkEDCCfVaLKjEJFG8MkNsEporSol6qXAgJLBxrL0k55L+AJsQ
-XfyuPSccC3JHJv8EVDtsEqxyIGgG7YtMWHoJUdGB/BTTIEVRhAaAGg9K8w0uiyzokRwfnTMzJx4x
-iIQcAXjkTIFGecTPQF+FFToKV3Wsl0fYc3QgElTFdMy+IMWyTIJcldPFUeqbFEs/5wJWTmyMhOWN
-SpOMtVprj3PyvzegnRXXYN0k4Q1qFRxMWMJESlbHcd1LF1SDmPVVTqyoPHXca+/FtzcE81BVHk3f
-E7bTN3q5FMz4fo03TCwrLVjdgVoVI0poH/6Ux3dFJbXTesU4k9Vi8wU55N0euVAojTBTdFd73VXY
-4pZfzojXi4dds00X4aR5ZoHEuxMWJPL+NOpZaT8WuWijY6v0WUkTDVbihpolOsWlB1oRzcweGQ8W
-GWm0EUeHv171R4GCHNIoUz8l9mi11x7NCZmlBjCwXuQDzOqpiSyXbvXko88+wZyYWD/+4Ow5apep
-NhCAUd11MuO02YY8csknp7xyyy/HPPNYSeilc897mRgmCT73PEHNT0c9ddVXZ71111+HPXbZZ6e9
-dttvxz133XeHXB7ffwc+eOGHJ754449HPnnlC08OCeWfhz566acXnnnkoKE+e+23n7460L4HP/zA
-ViaObvHPR38x8oc7OX333y/M+1G4p7/++ltdXziIbrW/f/+hx59zNPI/AhaweHLxXpz+lKOU5TBw
-gY8jjlSaI0HpmKWBEByOA5OjQeRQcDkehI4FH5i/4HDwOCY0DgiTo0LnmEUQC4BhDGU4QxrW0IY3
-xGEOdbhDGNYgRSQEjlJQkQsiFtGIR0RiEpW4RCY20YlPJCIqfihA+MgDBjzEYha1uMUdCkJX33qO
-WRZADjKW0YxnRGMa1bhGNrbRjW8kYwum2Byl5CIWd8RjHvW4Rz720Y9/BGQgBXnHXMyRORKUxyrg
-uEhGNtKRb1zAFxM4kDE+0pKXxCQb5XglIP6mjoMEZShFOUpBFpKTVDyRIjO5SlZaMpIZAWMLHVPJ
-VtbSlpo05AUzY0dS9tKXv/yjKd/+00nfIFKVt0RmMsnxSliwsDlmMUEapDlNalbTmtfEZja1uU1u
-dlOalMjlCAeihjaU05znRGc61blOdrbTne+EZznVEM4VwkcA7/BmPvW5T3520wSSpI5ZQLEKghbU
-oAdFaEIVulCGNtShDyWoEeiJHKVEIBQXxWhGNbpRjnbUox8FaUhFetEITPQ4EhSABSC6Upa21KUP
-BQVApyNGZdbUlpscpnM+CUye9rSXwkRhcYxpU6KukpnOZA5Ni7rUR+I0qOWbCy99OlWqBtOkKazi
-MZm6VUjKtIKz5GpY3ehUDOovqlVFa1rxCNSyBmeoYoVrGo8ay2c65haewGte9br+V7721a9/BWxg
-BTtYvBbjqsVRChhesVjGNtaxj4VsZCU7WcpW1rKLBcNhIwgfBiSAsJ8FbWhFO9hbeDU6So1rauOo
-2QyeVa2vnSpbidmbt6o2tXOdpEBoaVu4knW2vNkpbIX7S9mikkRa5W1YcRtQsCa3t6w16y6HO92f
-QtetWXUuXJc70+Zml6u+1alrqTveQRZ3gtj1Lle3+9WBzGC074VvfAObAOsGcS4iAER+9btf/vbX
-v/8FcIAFPGAC51cE9f2NBPkgXwY3OL4zMG0Iu5vepYKXjuIlb4b9aN5DopfCS13vaSf8YZtamDnB
-1XCK9cjhD3qYxDYNsYQp+eL+oppYlwORqop1HAsWK6e2NFZmjMM4YiDf0sbiFEiOd5ziHtczlUWu
-qZBlORBeiMPKV8ZylrW8ZS532ctfBnOYrfwJBPtGKSqYRJrVvGY2t9nNb4ZznOU8ZzqnWQVlpi1n
-VyBmPvfZz38OMy8iPOQZQzmZR94ghpes4SZ30MWGrqWU61poSN8Uz8BV9KLJ2+iTPrrSRh30lHX7
-aUuf8sLS1TSTL72bH5M6k5JOqmOqDGha19rWXiazqU88lz/8wte/BnawhT1sYhfb2MdGdrJ9/YdV
-60aCDNjzraU9bVoLGpa5hcVuXY1JRFM006meLqex+uRtg/razKV0uS/Z7RP+fhvcwhW3UD2t7kbC
-ejmopXdTm50bFL873PvGTavzzUh7KwffA2cku43Tb3/DG+C3ETjCu3pu7rbXwRfHuGDpq+sbCyQe
-lwV5yEU+csvG4+G2UXDGVb5yvUKY4uwdtcQbqXDEurvhaY33Zskt80UWPDkH53kbaQ5VVN98uDln
-37yDrkafIwfoS1fj0FtbdKPDFunCiTjU0dj04zxd62eUenRxXPWjn7w2Wf96GbluHLNswhZvh3vc
-5T53utfd7nfHe971/nbDchzJsFAFEAQ/eMIX3vCHR3ziFb94xjde8KowO22ejYe9V97yl8e83jcR
-6knHPO1Rj/xsGE72ql7+/bo7//zWOR/rdKfejGEvoc1J31PTAwftn197cbyeetjbl+qzL33oZXP7
-tOeeOGJ8afKVv/yGStTvic6MNEY6fepX3/oilYbwY4NIlTLf+99PvvGHYxYxGND89tM+bJRyfvZz
-L/2vkaDz2j9/6U0MqfdWIPTD+9vdPDXpz7k/g8s/b+M/3fA/sTsvAKQr1ju1/XPABDSumYKfCZzA
-AuQ3CsRA97HAgMvADhSf6tCLEBTBEcyKhlEOaCDBFFRBtzDBDVrBF4TBr+CdGaTBGrTBG8TBHNTB
-HeTBHvTBHwTCIBTCISTCIjTCI0TCJFTCJeSOPKGarHER81jAhWCXXxn+jL35Fr6ZkoRwEpuJGvMJ
-CfNBl/tgEas4GAvhFHK5QryRGyZ0Q9OYlYG4kAxhGoPoEMAAEbt5Gag5w515gy08iJO5E2KZC0dB
-kXD5D8DIGIBxEcDIPxNpqzeUxKfIlkackiqpw4LQEi7xEj3sQz6Em5hZiO9wQsNhGUaEGYuxin9B
-xVRJFZ05nEmURc0YlLGBwkORgEwkCEYJGFiEG1DsRYZJiDx4klGwGULMDEMMFkuREydokw3Zk0oJ
-naiJxFm0xp+IQ7UYCFvxFoXYFU/8xYTpw1M0CGOkkieJxZzpxVBsJseRBydBlr6QRljYE7AxxWvE
-R6SoxG3JiArpxoP+KA9xQZNyYcRzQUV2vEeB+EOFdEeDMR+JoBsnNBtNYQ9PEQissUeDzMeNHIp9
-6Zd/+UeBIRj7SBhgPEhhPAhi/Jt0PEVlJIhRUBWnEBL2SJzA2EJI3ECO1EmOIBltbCbC8J1vURmG
-gBqTPMS3eckhOccaQUaE7MVIsZGQ2AiUpEelpMac3MmspIikmUZGJBOnIcqSFMdQrBqAXMiBeANS
-acp1fEqE+aKNMBWCwEhyrEattEuOcJuYYBrBmBvCAEdz8Uu9iZv5AMTwgMKwYcO6ackqJIhKqQ8T
-MRBYwIZF1BopoUu/vMvM1MzN5MzO9Ewe5BzSAZ2bGB3RNJ3PRM3+1FTN1WTN1nTN14TN2JTN2aTN
-2jwd0cTN3NTN3eTN3vTN3/zNNZgG4CTO4jTO4yROJVgDJUDO5nTO5wRO5WRO6KTO6qRO6bTO7NTO
-4pyGNdjO7wRP3hwWbAjP8jRPAGAH81TP7awGAKiG9YTP6mzP94zP+mzO+bTP/DROdrAK/fTP38QG
-ZRlApzMG53AEAHAEA0VQBU3Q5jCGKdS5RxnQrivQ5jjQBmWOC2VQ53hQBRyWCWW7Cs3QBbVQEh1R
-DF2ODo3A9nCMEZCEF4XRGJXRGaXRGrXRG8XRHNVRGC0YABDRQwiGIBXSISXSIjXSI0XSJFXSJWVS
-IR0IDRWIGDj+hSml0iq10ivF0izV0i3l0i710imNgSc1UWFYgjI10zNF0zRV0zVl0zZ10zeF0zIV
-BjHF0B210zvF0zzdUWAYCBXVmiYF1EAV1EFt0kPwKrNghE5Q1EVl1EZ11EeF1EiV1Eml1EpVVHrI
-DB9tPddbLYGAUlh4AiYQ1VEl1VI11VNF1VRV1VVl1VYV1Seg07EDPpyLVYGABEvF1VzV1V2t1Evo
-U6VLvfVCVF4l1mI11knF1EcRUW3jVHLAqU8NVVeV1mml1mplVVj1VBNVsln1KWH61Fs91nAVV2L1
-VYHw00Rq1jMSVsdI1HF113dF1kxd1nR9vVoFVWvF13zV11X+xVZY+NRt5Vae8lYTBVd4NdiD7YRy
-hYVzRa5mXdeBaFeEldhxTVYFmVd67VR/NdFo3deO9Vhr7dd/Ddjgy1YMLdiJRdliVViGxVgyeliB
-sIMpkNmZpdmatdmbxdmc1dmd5dmenVk+UNaB8AM3INqiNdqjRdqkVdqlZdqmddqnJVovsFdv6Iaq
-tdqrxdqs1dqt5dqu9dqvBduq9QZ7jYJmMNuzRdu0Vdu1Zdu2ddu3hdu4NdsosFcz8Nm7xdu81due
-3YNfHQg+gNrAFdzBJVyo9YNDZdeUVVxirdj2uFiMfdaN/djJpdxrtVeAHVlfGliTXdzOzdWVBVbc
-Q1yI9dz+0qXUxtVUz6PXyMVQjq3c14XdkNXWzI0tez1Z08VdRgVd1EvXl4WFiM3d4O0E1H3c1bVX
-14Xd5P1Y2cVQzKXdUdrcgbhd4TXd3T2ull2m0RUI4KVe0yXeTeVU1h0I5FXe8s1X5pXV5wWm6LXV
-7g1e612PhuVU3+WBAbDf+8Xf/NXf/eXf/vXf/wXgALZfZ2CAoBWIevCCBFbgBWbgBnbgB4bgCJbg
-CabgBE4EezWHLtDgDebgDvbgDwbhEBbhESbhEtZgc7DXwHO8FWbhFnZhxoO8kh2IVhDgGrbhG8bh
-AMYAvxUIBpiACgbiIBbiIabgetDe33Xf3P1e1U1X8RX+CPI13yieVvRNMvUVWNtNYtyFX3RtWd/l
-3ixW3CXONux14nuV4jOmViqGBee14vLCYjD23C2WX9fzYjj2XDFm1vA9XjTmY1dVYzZu40BiX1iY
-XjuWWDnGXt8tB3pg5EZ25EeG5EiW5Emm5Eq25Etm5FIQAAOGhWjqp08G5VDWJnCSYYHIhi9A5VRW
-5VVm5VZ25VeG5ViW5VlG5WywV3KKp1zW5V3m5Xeap1KGhT7A5GEm5mI25ktOBh6GhXsS5WZ2ZlD+
-p5czi0qQgmq25mvG5mzW5m3m5m725m8G52qmhk222IEYKPBD53RuPnu9hipw53eG53iW53mm53q2
-53v+xud8dudrsFeLur5/BuiA/qiSAmYbCOeDRuiEVmhwzgRlTil1huiILqiYkubENeQwllfwdb0y
-huI+9uhR/eNA1tw3vmiUReQuPuIvLmmDxWMy3uOPhulSDWmRJqVBLuSVfteTxtg6xmmJbemW5eiY
-FupXvVyarmmS7mmD1Wl6pV8ycOqnhuqoluqppuqqtuqrxuqsdmozKOByFgi3y7ywFuuxvru+01gM
-NYdvUOu1Zuu2duu3huu4luu5puu6VmsUBuZ1CIC95uu+9uu/BuzAFuzBJuzCNuy9Xgd7XQStZuzG
-duzHzuodNlfOojyytuzLDuvNq2jSTeqD/WnIfen+oYbpmTbqULLpzj7Ype7dlEZtls5oJm7WoBbt
-0S7q0jZtpG5tcVVth2Xt3HbXzzZeYO7o2Y5i0rbtUsJt3zbW3Z7f3lbucAXuJg5t4uZj4z5uQDrt
-5w5X5qbjI86ESADv8Bbv8Sbv8jbv80bv9Fbv9Q5voPVqWHAvlpPvi9u4sx6IbwiD/Nbv/ebv/vbv
-/wbwABfwASfw/P4Ge8WvAlPwBWfwBh+wAwPmC2DvCafwCrfw9e7byf7b+ebwBnO5n/xQztZuY43u
-2J5u6j5j677uDUvuEddV7g5W53ZxXi1xPRZuFO9jFV9xPsruGedVGBfdzd5eH2fc1x5joD5xHDf+
-Xx3f8RVrcSKnVCAvPhmHckut8Y1OciVXXiZv8rV68iqPVCn/Ot89B0gw8zNH8zRX8zVn8zZ38zeH
-8zg38z7oaselMmrD8zwHs1yzb4FIhzEA9EAX9EEn9EI39ENH9ERX9EUH9HSwVzSrs0iX9Emn9Dm7
-M2CGAjnX9E3n9E6P81ZQZmjT81En9SuzNhCXUBEH80q9ct7Lci2P3dru8j7q8VWPcmXm4p2mcluP
-1Fb/PNmG9SWX9Vnfo1rn9TDH9TmOcSFH4mOPV07OYyy/8WAXdmAG5CY3dmd3VDHXOkU+5m8H93Cv
-ZE3mZALQgXNH93RX93Vn93Z393eH93iX93P+NwB71QIuwPd81/d95/d+9/d/B/iAF/iBx3ctsFch
-oIKEV/iFZ/iGd/iHh/iIl/iJp/iEFwJ7FWZx1/iN//Zk1nCBEAAamPeRJ/mSN3l5J4AjpuaFZvmW
-d/luHmdOPmeJpnnwc74+h4V21ued5/me93l85mdg9meBJvqivz6CxnmDfvmlZ3qWb+iPX+buq/mp
-Xz6KRnUFsWhth1RfTztgp/bk5fJZz3atX1RuhzqeJntH5fqv8/qvf92w7/KxT3uzXzq0T3tGXXut
-a3u3p1y4x/Yv13q6Dzrf7YBLMPzDR/zEV/zFZ/zGd/zHh/zIP/yJSV1YsAcuwvzM1/wcggH+e6WF
-JwD90Bf90Sf90jf900f91Ff91Qd9WrBXZYCi2Jf92af9J1IGe9UDydf93ef93o98ClBmMdj84Sd+
-zbeHI04qEV2OT11+E21+FFUOP+2wEG8h5VcO5r9+589+6E8O6W8x6n8m608O7B9/7S9/7kcO7/cx
-ZbmKGHT/F+yP95f/EewBAOiB+cd/vaj/+8///n+L/QcIEgIHEixo8CDChAoXMmyoEBsAhxInUqxo
-cWAvALA2wgLg8SPIkCJHkixp8iTKlCpXsmzp8iXMmDJn0qxp8ybOnDp38uzpUyfHoEKHEi1q9CjS
-pEqXMm3q9CnUqFKnUq1q9SrWrFq3cu3+6vUr2LBix5Ita/Ys2rRq17Jt6/Yt3Lhy59Kta/cu3rx6
-9/Lt6/cv4MCCBxMubPgw4sSKFzNu7Pgx5MiSJ1OubPky5syaN3Pu7Pkz6NCiR5Mubfo06tSqV7Nu
-7fo17NiyyyKRAKsXUtxGe/Ui4URMbjG6gw6/Pfs48uSbSeDGDc1Jr99Ciw9trpQ6x+LYlXPv7t3v
-I9t5SMAab11CHljQqPfmDc34bWjYSMyH5lu6QNuw6NuHJcGJE7bhlgd02Gy03XcJKrigWtDcAMso
-0CBhXXHjTScPLPKMAh+FsIjx4HO3AZedcU4gAQs2E8JiIhJvMPgijDGWZd0N71nn4Q3+5E1Hom4d
-StAbCRqxF9989MlzI4IyKrkkk009MoqAvL3xY4ajnFgdhhqu6GGHYpBXG3w8wvdIiUi02CSaaapZ
-FDQAXHmgcaNA15tQAvF2opwCGafbfen1CCdu/zlB3oDQPRjmmokquiijjTr6aFn2EfQepJVaeimm
-mWq6KaedevopqKGKOiqppZp6KqqpqspWHhtu5ARH+iU51Bu83Vgrb8AVh2svb2bXC67A3aejrQFC
-5QSlEpAJC5izTmergLfZSihxvA1KFK7S7QcgecIByxtzuIoHnRN+ugqhs0ORoJ+DscJ53bTw8Spc
-tdHpGJS3uG407IHWjtgUEgZuNMr+iOkhitS8Pca7q62+clTrtfty65+UQH7bi2383nbuKOnWye6h
-/r2blK0Y71kyosXey1G+vJVHrsHF/stUqxzBulHMTPEqL7SI8urwRhDrSGB06f34LXMXCzvxxhx1
-TJXAYrgqj0aI3qffjiQerN1GWhI13LobSUDtq1A9smyN+9640XPRzTwyoFmPDGV1G6kYtn/3ct31
-DSciccORAqPoMb6Hhtd11cXdACDWWmu999yNE8cR3mPD1+5TN4x4sxiJByUPuW+nDPfoVX5d9n76
-WQ432KoTKjg2hLNsuH7Mwb24sXLHPbnjdJ+eYd/MAn55yE1F7WrncIPudt2P667+m9dZwypP8H9j
-yDrlrt8Gu+xFjZJe2H//6TTqz5MOOYLDcT3czU6FGDDOtheHnnrYDTmk45jzjgTZI0MeIUeg0bHv
-ledpTknRit4jvpF5aSOCc9y7IBcm/cltfWwrHlMsVzN0wY0EwKEg9rbGu4NFMISlG10vCNiq7jnw
-RMjykO3C1EAUNU9MI5wgBrUGQLZtSDcgXAoB8WbA4nhQPTncG/789zvc7FA950Lf5FKYnhVSpWYm
-2g+9SKgiWvEmWrDY2QnTB8HmWEtyTEGWhVS0tqBY6FkuO1kXT0hCXL0BQ1B0HHt6ITUIHekp60LC
-zTw4vqD8sGS6Cpqt5ChG7Nn+ChuiUwr8SJCeR+RhkGxcGSLppLA43lEoEMOGjUbYyT3tcRR9dMof
-b9Y3S16wOomEoyZvuMj78caRULHiiSjJyvhx0WS6mVcYsRUdUCZxlM0p5SmnAsoHyYNsxeEfCYBW
-uiSGaZEorMrZCAaLtK0RR5g8nwjzd0S7wcqYTqOUE3EDq3I+5UPKypAzg4KEUViphiUcYwBzqEQb
-TkVzsPobh4SioW9O03yke9eHgonHKG6JnU5xJ5lIYEe4zbOeutuTQY1YFN00UYAkfMoyhRfQz42C
-oEjM6HZ086GOPlGUDF3nR51CT9scrVaI0txueEdN6J1LbpXrn1QcdDNbTan+OBqSpgh36jQzqi91
-YtPbCKnnN8DhhgQljSlSnJC2mq5tQui8qCX/Z8aR/RSrGaQnl76Vxafm1Hmy7FpPtQbQspqwrFW9
-KgtflbakvaF/Xt3ojpQ6sLHCR6rCmyhVZprWWq01b229Jz5N1zzrVW94ddXeXYEalc75apO9eAQY
-DQrMnf0MsJRjWl6JkqPATktO4LInLAkFLZUJM47bipgJX1Y047QplE95RPvexSv6vPKGPMtVyZJm
-r8fellhWeYPBIjit2L3WoMn9oq3EUNpe6lFiuJWjxpwDAN86BbhZ45UEqGs/1iYyubQ1rW7LddB2
-ukmn0FLvN/eGXuy6bLv+nsxufKMLXtSqZ7xmXRWCE5ymsQ2EsE5pJkHsIqmBfDUqExZIhQnD4PxY
-ZcN4o8uFSZDhp4R4xIIpyPWogmK7QHggVmmxnhQs4xnTuMY2vjGOc6zjHfO4xz7+MZCDLOQhE7nI
-Rj4yp6YUFAm4iCP8Q5xURIIbqm1Eyhmq2udAgg0BD4XKVGscAORBNZGQx8pj/oh8O5JiTzbZyaN4
-AwD6eqWRVBkkafvdRm7Q0zbN7F5hjsqZP3LlOoekymu+8ke2fBQqd8SoGhkJbujcES0bjNFDuQEA
-3nYkj+AU0SDJEqWNEiSRiDnUSMYLCYqn56AECcpC+RCnkarmLlftzwL+xTJHLM1kLmf5ym94k60N
-HZRg5xrXJPj1rIeSB49EF5BpE4NWhT0UW88T2a9eWR7aDItHPLDV0nYznLVFFEsX+9vDPrSuoWsU
-RntkWYPmCLGJDe8UH/tE5HayR1bWOTLxD9n3drV/1L1oXFs6SLI+tVs4azcARDfbVfs3NqwEyCTJ
-+90V/ze56bNujVCNTuaO96HfPe9kC0XPq97XAzv3noqT/DbffMShBb6ie8kDziMPipze82akYrzW
-IW+5yPfzwFtXGVhXIjfIiZL0f28bG9wmzsqMxfSMD53Wvb45wuuCDf1kO4BbfziuD3T0sJ/b6kAP
-OsALbGIvZzrTH1/+88XDbuCKI4HhTLaZu7t2IpYTO72whZCr6j6igD0Cy/KWKNaJrni+oxvXvS0K
-u0F3KKTD/efxBg7TB8Xnhc9MDO+ZuuMNvPGrV9nEWXdLqgemN5iD/SgaL0rczZ322bN80FSOYdIT
-n3YSLKvid6+7wWrPeNLzUNlN/g/lJGr4nyNu7WSPvNIbL5TaR75z6aF82adN76mRffMRYzraac/8
-tBecoKd/i8LfMKLUMxr8/R6/SFxN5vDfm/oc10jAbJN7Qn+EPIGOs35U3Gpt06EIX0joBrHdGyVh
-S3rcwLKAjsjVHpPl3a19msUdoOzVH/NBX71hH7xh4KSBhI78m3n+bVuTgd//tV72QR7BiYSDnR9b
-BEgeCEzN2ZsKCgVo9YLpnR30KR7xPd643V/X/Nr+8SCujYLAyFvdhYQLUaAEYMjwxcrQ6dN+WImB
-tQio6V6GYAM2jB/9+Vz0+aDasaC0OYEp4VoRYp0EGNi/OUFIpMfm5ZptgB4hiR4ZlpvdvBkM0sUj
-6JmOjNqn/ZuRJEXsGaHZodzoWVqOFGEhyt+h+d3CZcwDAd/ZtZzH2Q0VahfyeVr/AV3NUWAQml0U
-4iEi3qGtdY63vV0Yjty9AeGKuMolbpP/kV3Qvd7okWL47WFbtIktKd69CZ5SFGIjkuKuJSKWtQgj
-hhy59WB2rMz+DTyIs73Hc9xMFFabr0iAg3EhKFqavDkBKIbi4lme9ImNzIkivXnEClbi0oWdbwQF
-aCHOI+TSG3weLaYbr4mhpc0TFeriWjhB1b3b//VCChqFMMZfQHKiohmjOzKiQYZeeogEA7hdrNRX
-tcWZRY0EFNpZhQVPUQRJhnFjoZHaHV4dRoagoAVaQprimrlhOpYksc0HJ0aE09VhpbkhAHRaCs5i
-ot0jPoYER/IjUAalUA4lURYlYCiXIYXF0ZSMyXTHUpbMC16FtzCl+SHGU/aMUWalVm4lV3alV34l
-WIalWI4lWZalWZ4lWqalcvwEW/qEF2JGCralXNLEW14GIM7+JV7ORGoAAJBchF/+JWA2xCjUnmZQ
-TUkFJmImJmIOZl1aRpAoJmRGZkVkxF5WZWZQTWNWBmaKxmaGRiqCxmeWRkRwJmFeZmnC5WnaJS1y
-RmiSxmiGRmeCRmx+xmx6Rmt2xm2KxmvCQgcwgm/+JnAGp3AOJ3EWp3EeJ3Imp29SQLFlJmXE5g/s
-gnROJ3VWp3VeJ3Zmp3ZuJ3d2p3T+QHOKRiqKgXKWp3meJ3oqZwdQzmqGxm5eQifEp3zOJ33Wp33e
-J37mp37uJ3/GJySEJ2wG2xMwAYEWqIEeKIImqIIuKIM2qIM+KIE+AYCCJpbJAz30J4ZmqIZuKH9e
-AntWJkf+wCeHjiiJlmh+/ifiOOdkxOaAQqiLviiMxqiDSmiKimeFXqiJ5qiOjqiH7kt7gsZ77qiQ
-Dul+ouiVqahksKiMLimTNmmD0uiR2miu4SiRVqmVdkKP7sePfkaQXqmXCqmR1mZnKKmTlqmZLimU
-iilr3uiXtmmOZmluuue9WMMg1Kmd3ime5qme7imf9qmf/img1qkCTChtBpsPvACiJqqiLiqjNqqj
-PiqkRqqkTiqi+gCh2iaWMYACBCqndqqnfiqgWsOHosZuLgA5nCqqpqqqriqrtqqrviqsxqqsnmoL
-XOqYBlsuxIKu7iqv9qqv/iqwBquwDiuxFquu5oKtrmn+rq3CrDarsz4rtMrqAozqaZRqtF4rtmYr
-rNZqjQZoiuWqsYaruI4ruRIrsnYrhS6rtq4ru2LrtPooiG6EqbYrvdbrtibrZsQmuJYrv/arvwbr
-uUapZ1Yos9qrwR7sqb6rlsYrLPjCKjwsxEasxE4sxVasxV4sxmasxj6sEeBrYQYbKYSCyI4syZas
-yZ4syqasyq4sy7asyJKCx2ZGKgqABWyszd4szuasxvoCtZrGbiKCFASt0A4t0Rat0R4t0iat0i4t
-0watDcQsaqZYNnwB1Vat1V4t1mat1m4t13at134t1WYD1KomRwgANTQt2qat2q4t0yJCz4rmvYio
-m87+7YaGaWpaBpmeqd7uLYOm6d1WRipaKN0ObobC6ZZ6RpcSruKe6NjirYDyLeRGboH6LZJGRuBS
-6eJmLn0aLsPKreZ+bifYbeVCRt5KrumaKeVKaddgLuhmLueS6r3IAgLMLu3Wru3eLu7mru7uLu/2
-ru/O7gQ0rmYGWx0EgfEeL/Imr/IuL/M2r/M+L/RGr/HWgfBSRioywO9mr/ZuL/f+riy8rWvey7wi
-LPm2K7cKrGzi6r+uL/v2a8Cq6XIQbPnO77oqbJwCqfjSr/5e6/nC78d+a/sGsACba/VORuAW7P4m
-8Kza7+F2hrUqMATfK7oWKgAPsAVf8LEWsGQccAT+d3CrMjDDjq8HjzA59O/fPqf6YrAKB/D7nrAB
-yy8JkzAIwy5HyG733jAO5/DuBu8Ee0ZsFq/0BrEQDzERQy/19jBuZqoOLzET5/D3wisNb4Tntu7i
-ii5ppliLnq4WN2nqDuyUUvHnvm61xi0Ya64VeytHZPEWrzGMdnG6rm4Zuy74jkbixvHgnnH6YjEb
-7/GLuvFnXK4dK64Y++y9AC3bHjIiJ3LSPi0Sc0ZsTi3YRrIkTzIle63YNnL8lu3ZKjInd/Ihuy0U
-jzFHOKzOlrIpn/LFdiwm/y9HhKzLvjIsx7IssyzMrrLMYhnNorIu77Ip82woEzJHiHAMR7AJj+7+
-Y+jrCifz+rawMTsGBw+zB8+wKMsrNHtwMV8xR+yrMm/zuDKz6mYIAlezAkszMFOzOEPwNaPxRmgz
-N7czAdsyZjzzOScwOcMtR0QDJ+SzPu8zP/ezP/8zQAe0QA80QedzImhwZMTmoVIqQze0Qz+0pFoq
-PJPtRjAALxQ0Rme0Rm80QUfDHOsmGQfyHSM06T4uH5/0k5L0YwCySNPtINuzFLc03eIxBacxSt+0
-gvoxpn6xTLvpS4dviPa0m9K0D5s0Th91hKq0M7OpUH/pT9NxSDf1lRL1reoxUiO1TicxT0u1lT41
-SHOEOmCBWI81WZe1WZ81Wqe1Wq81W7e1WO/+gFI3xg/PAl3XtV3fNV7ntV7vNV/3tV//NV0fMfr+
-MZbxgVsfNmIntmK7tTp8tJwG8zwrcDrncTa7s2W/82DvdNeEc2TPbz0DtTl3Nv1Odk2v82WfNrB6
-sxdvtmjr72dDNWS39vySdlFXMGrfdgZPtGPCsGyT72t/dWj39sHSdlVXNm7jtmq/MTgLt287Nv5y
-hDXkgHRPN3VXt3VfN3Znt3ZvN3d3t3RjQlwzRmzqQgOUt3mfN3qnt3qvN3u3t3u/N3yXty6E92Jc
-r3ffN37nt357t6j+MkzDwhRzNZjSt2KU7lWjdFYrKxwLeJV69WPHNIMTKVU7slEfOIITeGL+sHSE
-C6mDPzeEb/iOTni+VriF83GCZ/KCg7iOdjiXFrInvziMLy0jZ3ZxbwQkVzKO57iOb+0l07iCw4LZ
-xriQD7nQgvLCRjEsgAIvLzmTZ6wq+/iIp1gEzDKVV7mVr2wEYDhizGzNNrmXf/nDgoJzt3hsM7fB
-EjeF2/Zxn3ZyE7a6mrnB/vaDw4Iwwzm7onmUG/eas7mWH4Y823m7yrmH0zmg1yues7Jp7zmf6zbg
-8nah1++YI+694DNHV7qlX3pAHzSjo3CKLTREfzqoh/qjSjSUa8b1XjSmp7qqV7pH+zdoA7iKh3if
-G4aBlzgbn7ipM3WsmyiLS3pQ77qJijj+osOCGtv6rc96YWg4sPNopDtwVC87hwq7aVq1se8xrt/y
-VkP7hva6s/+6ttctshNGrVf76V57POv6txdus3PGbqJDCLw7vMe7vM87vde7vd87vue7vr87M4T7
-YMSmOyyDwA88wRe8wR88wie8wi88wze8wLuDv59YYe87xVe8xV/8vqPDum/GAz/6uh76tOu5ortz
-m2v2cns8pLs6bAc3yvNvxAcGMo+8ZZe8VrN2y2eroJM5y9/8s4J81Iq8zG8zzf+4PHA2zztrzvv6
-zh/9rPr8ZcR80HPz0KP4yTP9syZ9t2/EIHwA13e913892Ie92I892Ze92Z8914P3pq/+aLDJgNu/
-PdzHvdzPPd3Xvd3fPd7nPdy//FFmKtr/PeAHvuCj/SBsvGbUcbr3p7T//EYUO7mXO9//hbInfoca
-fmYgPuXr5+I/PYk/vumaO0VnCOtmfn5yO7s/O+kz7tonaed7fuSC/m5ne+rjp+lz/L2cAQvkvu7v
-Pu/3vu//PvAHv/APP/HnPgpEvl8APDIsP/M3v/M/P/RHv/RPP/VXv/UvP8SvvuXisjYUv/d/P/iH
-P/GfgeVjxm4qOZin/5I/uf+G/EZM+ZXHv/xTeZZrP2Rwufrnvy6LucoDN6FbPUCQEziQYEGBLWAl
-lAdAXkKHDyFGlDiRYkWLFzFaXNj+MGGuWB9BhhQ5kmRJkydRplT5MZfDjRlhxpQ5k2ZCEgBcrjK4
-k2dPnz+BBhU6cIHDmzWRJlWaFAAJhwuGRpU6lSpPhAoZLtW6devLjivBhhU7VmVLrBy5plUL86hC
-nVXhxpVrsKhNnGvx5s3Y9Olcv3+nXoXlVW/hvIQ9klW8mPFJs4OzGpastu3gt4AxZ95ZF1blyZ/X
-8k2ILkRp06dRp1a9mnVr169hl2bmMjJo2zUJu1u2m3dv37+BBxc+nHhx47vd0UZ7mznbu7D4xJY+
-nXr12OiMPm++faZoWJc6hRc/nnx58+fRp1e/nn14SMq5x69I+AkT+/fx59e/n3/+f///AQzQvifg
-k89AiCqTh572GGzQwQfZuyS7AymkyDvwIMxQww3Te++sCimkT8ARSSzRxAAJ/BBEAxNckMMXYcxQ
-QrtWrBGWC2PMUcf1PIRsORuZE/HEIYks0r8UfQSSuxZ3bNJJ8WbsTDsl5cPxyStz7JEwKm0T0sgv
-wTwRyS25/IxJLNHkMErPytzOO3Wsi1POOV1LpMA2PyNMl+P47NPPP43T5U48JauMAWboTFRROdWZ
-kFA3nUoIKs0opVQwMh89rLbEGuvUU7IewzTTtRK8rNJT/eKMzVEn825SVGGN69LaWMULsU9xzTWl
-UGmtlbLn5DE11mGjUnVKXwv+c5XYZaOa9Udku9pU12mpBYnXZ6FdqlRmuQXK2Gwlc3WVcckt19xz
-0U1X3XXZbdfdcY0YFNylCJMmlHvxzVffffnt199/AQ5Y4HulkXfepBK04N2FGW7YYXe/PTgv78SQ
-x+KLMc5Y44057tjjj0EO+WKDJaaJMJFRTlnllVEmuWSZKkOC5ZlprhlkMRx9OS3vdDa5155jEhVo
-jIQe2qJVjcYI6aRl4pnpi4p+OqKopX6I6qppxPqipbWuyOmuIboaa7GrJltqrsGWMm2YAGjb7bfh
-jlvuuemu2+678c4b27UXytvvvwEPXHC49077psERT1zxwNfOiITHIY9c8sn+Ka/c8ssxz1zzzaFp
-PCJoNg9d9NFJL33yzj232vTVWW+99NRhj1322Wmv3fbbcc9d9915793334EPXvjhiS/e+OORT175
-5Zlv3vnnoY9e+umpr97667HvXQwAUE9olBseygP1hZCK26ms+n7bKfIhgvuG7iVCHwAJHmLocMLT
-d7uh/AHoBecbsbU98D0ECaN4AwCwEakbwa0XCXEf/ML2QP61TYFGgeDUjkUR8rEvWrB4X/ZAmDQn
-POIhb6BfQrbHEQ46JA9OaNsokGChZ8lPIit0IEcK+IYYTkR+OnRIbVZoQ6w4BAk3aCAAJXK4HcIC
-CU4YRefk8QYSIjEikcn+4RIj6BBoOOGIN5zIFi8COpiQT4xc2WAXQ5jGkj3CCSwEwBJ7ERkbQkOK
-sNgiGts3w/1lUIi06kUF8wiZP/4QLUHko3bY9zNYmNCERkGjBLDhxSouZ5A11E4etKPIzgCSXhns
-ZEKw8T81jhJc0OCeTQbYmUfIcUpi6KIQCTlJyFhSlg6BpAwhs73/ARGRh7RaJKkYvjd+zyEjJCBH
-FEmrW9KShWjUJDYaIobHUZAEB1zfXaqJwP9lExv02+BdHoENBOahgf4TZzcTkodz5gGFccTGKO4y
-Ck6Skp6jMiYssMFOWIghkqysCAmAGT89zhKDtRwiD/fYmSPy0mq+TEj+AZH5LGJicoeaTOZyYElQ
-O5IAi4pEwikXMgpYYPIGSMCkxXCSQlg8ooHywEbnjvLNlb50pW27US86Z8DBvGGPnXNCSbcITjzW
-k6iEYuM+31DMhvhTIjkUZRXfttA9Ek6jsaQNLsmHBHQylDZww8rbQinJEuqzjsFsH9wiRauMTvCE
-Ym3oQanIEPJt7xFYnJBM0ZkQF97ohOSTp0NuQILtoU4Cd8loURELpI+CTqSdGSBTEfSGJ3ptoLDs
-43KWKVCCRvGjhewlM5l4g8b2CpNvayMs7mlBs1o1IZnN4kN1ytq3ajQycr0LOQHgBHaK4QZv6EUc
-Z0m+2sCTiuSLo/r+OMi+wyaWuSC6QTj1edy3VTUhN3DCUxEqS8sey4/z9CIHA8tVuM7WJlKFyCga
-O9JTAlSYMbzoQypZ0KvKdr4crC1KIYJJMbwhUjIlX15hAVx//vUhpiSsYT3ZXAUfCJJJraUN8+DD
-i/yMhvKtHw4NaNcLaxQJB/QseUFMAvMS8Q36TEgdtfpBeTghrdiyYoYnwsECpnK1P8SZfSNKvnBC
-kXt1hEYcZYYT8gG0c6vEiT+juD+eBhioe13pUBccZfl8NL0bhoz67uc2XAZygi1F6wLd9kGsameV
-H+6q+qoaxc7FTQIOdsgoTptDBCpQbg58m5gteeeO7k23tM0xTgr+2DZ0QnLOb+CpkLEpThYfWYV3
-IXRekRBHEx5xFFOU8qUxbbRHeJcrYuhem5fyhgtmmtSlRlYTDUNkO7JYKRKosqlhjaffznrWkxEx
-rX+L3ZfhutZJecSouYKEbPJXwzArdqyRnWxlL5vZzXb2s6EdbWlPm9rVtva1sZ1tbfOa29329rfB
-HW5xj5vcbYWdK8mdbnWvm93s1nXj0N1uec+b3urWHQLrnW997/trjVsIF/cdcIGn24WFA9u/B55w
-hXdbnPfmdNr6zTdNps1sT6s409AGu4ivbeMHn7jHDd61iyct46nrONhOrrWRG23lQ2s50EruOe+M
-QBI1t/nNcZ7+c53vnOc99/nPgW7z7qV8bLWJwSmQnnSlL53pTXf606EedalPHekxcBnFaxN0rW+d
-610POjBydjvvMCJNZc8QPdBC9LLVpj5hcvvb/zOmj4u8NpAw+90btKYEx27sePf7etD+w4fTHS1t
-h/vhEc8EuYdc5XX/++PPo3eHO4TskLe8eALvwME3vvCJ9/zbFz87wtj98peXfO76XnrLZ/5Gmy96
-5z8feyOFXnajV73lT48774jCBb33/e+BH3zhD5/4xTf+8ZHvez4IXvS1oQMHoB996U+f+tW3/vWx
-n33tbx/6dLg6yB0ChuSPn/zlNz/yTRF223knBdVyf65CkXb+168dLa/q1v0LwpmX94wwk3j//zvl
-MWKucdgPAA1QMeKP+WqvNuwP/xxQ/+aO8xzC/w6wAsFCAPdO4xSo/SywA1EiATWv+erPAUlQICCQ
-8V5vAj1wBUsCAycvITiQBWXwI0Cw9USwL0rwAb+P8FRwBmfQBVFPgUShFoiwCI3wCJEwCZVwCZmw
-CZ3wCYuQARQwdgijAjThCrEwC7VwC7mwC73wC8EwDMXwCitgByUwIbIACtVwDdmwDZ+wANSvdlLv
-9v6O9dROarxE9vSwRGiPCh2PDv8u98ROgSoPEPHODucPD9luDxmRRPoQdmzPEPFOENePECXxEOXv
-BhPC8Br+sRP74xFTJxIvsewoUQ4VqBKkIBVVcRVZsRVd8RVhMRZlcRZpMRWpQQCmEBJrIxu+oBd9
-8ReBMRiFcRiJsRiN8RiRsRezwQxTMCFsoBahMRqlcRppMRPikHa8QxkGZhu5sRu9UWBAABdDcAHR
-whAe5hzRMR3ZxRCYkf4cYgO+MR7lcR4BJgKucXYK0AdlsAbv0OIYMAd1UEX8EC0oUB9XEAh1bwMN
-kgX5MRH9cQQB8v5OUBNhoSAX0gIRchAdIgYvsgIbkiIbMCKJZSLJsQc7sgIzshIdAhWGoCVd8iVh
-MiZlciZpsiZt8iZxsiVfQQrHcSAdogxSISiFciiJsij+jfIokTIplXIpmTIoy6AdFREtjiEnqbIq
-rfIqcXId7lF25nAU0QQRKZITPXEs8QMUPUcUvRJLShEbLTEtvzITS3ITyXIuyxIqH9IhSM8tr2Qt
-8bEt9fJJwDIuYUEs6dITzdLf/vAvnYQvudIvFXNHAtMn5bIw5/IwJQ4t8vIxdYQx+U4Ix+EzQTM0
-RXM0SbM0TfM0UTM1VRM0l68ndREt6KAGZHM2abM2bfM2cTM3dXM3ebM3ZdP7BPI1w281ibM4jfM4
-VTP9siYhN/IkLfAjBTMkRTJWSFIyK9I5UXIrO7M5sdMAodM6pXM6UaU6hTMhLLI73S8lTZE70fP9
-vrP+PGEhPMWzUsgzFGvjPNtzWtSTLdkzP6nlPe0TIudzWOrzLO/TP9NTOzXQIY6gBBz0QSE0QiV0
-Qim0Qi30QjE0Qx+UJ21QMBXhAUA0REV0REm0RE30RFE0RVV0RUFUEeySaQijCDR0Rmm0Rm00Q+Fw
-OTUyIQpRM3MkMuGTMCmTES0T6zDTR3eEMxeUR5FUR4A0QB1CSIdUD4sU/BIiM5tUTRTU5BwzSzfk
-SQ0U9qa0E6uUB6/US2FESbnUIRrBEtz0TeE0TuV0Tum0Tu30TvE0T930BMSxQ60zDlghUAV1UAm1
-UA31UBE1URV1URk1UOPgRZOGME5ATym1Ui31UvP+lAi2VOYUSBvp8VNBNR7DMRehNCHMUR1RNVXP
-kR2Ds1RhAR5DNVZltR43lQAVEkH/Ey7Bc0BHElJZ7kBxVT9rleNuNVjhT1fhUz55FTMKFDEJ0lh1
-ZT/7sj+htVMANExxcFnH01ddDlir1VOktTFXkhvItVzN9VzRNV3VdV3ZtV3d9V3JdRw4tB9htDbK
-IAPwNV/1dV/5tV/99V8BNmAFdmDx9SlbFVsT4hjgdWEZtmEd9l3/YFghrkvRFELA1FmjdEwNk1uB
-Bi0rFkLUlFMp72O/FFldVUo11vPK9AxhAUtJNu8kFuUo9mXb42IvM2NTlkg5lv8Sk2ZhVkdVkkn+
-fdZBbNZIcTZnqXRndcZjh3Y9QtZWx/VhpXZqqZZd5ZVUERYW7pVgubZrvfZrBdZgk0QwFbZqzfZs
-pTZigXY9YfBbP+VaMVZStBVWmvVmzdNtwTVmuyYf8ZYx4NZu43Nut/Vg4/Y6+5YxwnU72/ZwF+Nv
-jVZuBZc+lfZl+o9xFyNxlxQWPHVWObdzQ2FUXdNVT1VVSbd014VVx9Y6YdVzWTdU7XFt+TMh2hRT
-abd2bddO+RRrCxdQG7V3ffd3gXdRH5VwAXdSb/d4kZd2NRV2p1Vom7ZmTTZrURZp4W5lm7Fln5dB
-npZYRzZ72aNorXQwqTdpifdxsdd7nVZvtab+K9H3PMDXTMV3fGPPet3xTNs3PbZ3Yh1iCN2wf/33
-f5twXh2yXtHCCsfwgBE4gRU4DMuwfMM3DQE4giW4f3NUbYKQWi0XLBw3fJU1cuOibs0XPzO4LNQX
-a/h2hDU4egu3gz24KkA4fEUYhR2jhKvmhGU4JTYYflm4hafiheE3hm+YJDB3TRc3iHFYhQF3h3m4
-WCa3ZCrXiHeFhqVm95Cziq34ilOzNf0UPmPTN734i8E4jHkTOFMXPsEAi9E4ja1YOS2YOZ33fs3j
-fVl2euUXTOg3KvESjtEjf2W2e/W4POT4eum4jmeviSWGaf+4E/h4b2f2jwO5fuOXkBHvju/+0n4T
-eTwWeX0bWY8fGY8nU5IPj5IJOI8vGZOl+Gm8gyWxcpVZuZVrcid1F3CBsilpuZZt+ZaXUmz3b2lr
-Yypd+ZeBeZW1knnFtYih2CRymGWVeImFwodZFoiPmSVOmWlsOJpFIpmvd5mZ2VsM+WCe2JqFeJqT
-pprBmQaR2Hy1eZt9wpmvF5qjeYhFNiE2t3XpWR5Bd4tF13T1eZ/JBXV3mXJrY3XreaC78XXbeEdh
-ARWpcaEZuqFj8RZj2Xx5MRkpuqIt+qKPcRkdGH6f0aE9+qMX2hqJWXFhoUdLuZMrOZJBGfS6eV4Q
-+Y8z2YQ3GY5RepQ/eaXdTpQjtWdLOab+a3im77emd1pMcTpMdPpXj7SUoUScjWb3JvipofoJBZgi
-DXiBrfqqsdoLG7iMXRWCo/qrwboWKngAudeYyxkksBmS01mdeYKdIdmdjxmeodaszzoW0tqTA5et
-5cKt8RquoViuyxoWOLKu7fqcOViv97qlweWbCTsWAFt/6fqs7zql1xqxCYKvU9qvjfix+zghliAF
-QDu0RXu0Sbu0Tfu0UTu1VXu1Q1uU6HWoHcIeZHu2abu2bfu2cTu3dXu3ebu3aVuxs4UwlIG1ibu4
-jfu4V9sVmHpoXnucBxi2BRM+YYesIbuYrVO6XXW6M5CIrRu7s9a7G4e6Ue6PXKe8zdv+vJu7W+Xp
-vNm7vUUHnlBw7dbbvem7vicHuFBvcfR7v/mbgpqvvwE8wAEnvhVRwA38wOdG2xR8wRm8wR38wSE8
-wiV8wim8wi38wjE8wzV8wzm8wz38w0E8xEV8xEm8xE38xFE8xVV8xVm8xV38xWE8sRrJltyMifpr
-uy2EgQgqbrwMg9wmnypC2A5IsioqbrTIgObs2MAsqvgHz2L8yZmDBGhMtB6iLYSIt9qmpLZstn5G
-iDiozUwsIuCsc6DBiNxKiySrc8TACU6LsuZr1aAMyuW8MLZnhz7KxCIMwSLinZCgieK8xhLpWbxc
-O9gruxLClHBGkXqBxrTK0gy9qjD+ac4l/TPyKsK0qJv0HCJ6YYcOq8vvwtMtzI5OSSKI3CXc61k+
-CruOys3Hi5wm/dULQ8q9R4F64RGUa+8KXbNeC9Rfi75oPLcEy9cH3SLEC3SUHNaRHSnqfJG2CXxu
-fSKEvHCMfMe/bNitLMZIwIVGS8etfcvZKtnBnSucQALUSSF86Nkj4hF8C9jOfMcF/VhWyMAwQr9q
-LNUhIpyI3cyYKLbCvd+R4hFEK1KyrG3wC0GgacLevd27vTMCqor2rMaYzCF6waUGT7yoy98xPiNM
-Kaxey4bsHeHli9fJC8wp4rc6p4BOS5HoaLJWScK8/TlmLONlPiacoOHri4EmaMv+56vO+MfLfjzM
-I0LO0tzOqMqOkLx/AOzRm/zYZ77pdUcMHN3ppX7qqR7Cbw3X3k0tJIDbzE0puq3qwT7sxX7syb7s
-zf7s0T7t1X7t2f7B7fvt4R5y2B1sQCfu7Z6+517k7n7v2fveEPzv/57A/RHwCV/ABR/jCj/x+/sF
-rzu7Hd9zxBvxGR+8AZfyDQfHsSbyNZkiLT98tZt2NF+mHaJibKb0TZ9mgBtaTub0Wb/1Qyb1kSVm
-XH/2aR9jRCn0f9ohLoEeeL/3ff/3gT/4hX/4ib/4jf/4eb8PYN9XCOMZquD5oT/6pX/6qb/6rf/6
-sT/7tf/5n2H5ayVBSgH5xX/+/Mm//I/fp6dYgTBEqTtBSyJQkIuapTdaa86E/dEfldWf/d3D+1kl
-D+O/kAECFix5AOQJPIgwocKFDBs6fAgx4kMSAA7Ko9cpo8aNHDt6/AgypMiRJDNeOkhRosqVLFu6
-bAiAxMFLJWvavImTJCSLBV/6/AlUJUGDAp8wOYo0qdKlTJs6fQo1qtSjT3gSDYo1a9CUAi/m/Ao2
-rMiTArlqPYv2Z8yDBzy4fQs3rty5dOvavYs3r9tFVtP6/ctw6MFw4AobPow4seLFjBs7fgy5cLi+
-gCsDNstgmN7NnDt7znsAZUXLpEmvFUhTrOrVX3d27Vk6NlbBRafavo07t9T+qq+vyv7t0qxX1sSL
-jxUNPDnW07BSG38OvZPrgbCVW4dIG5ZR3dy7e3/Km7rv6+QVCscYPT1xsrDMln/vkLlz9fTBTs8O
-H3727d/7+9cdHn75lXdefQZ+xZ57Ay4Ii3wHPmjTfdUxeN1+/12IYVQBTkihcgVCCOJxZY3W4YDM
-BfJZiiqueNcwlJWoXHbfhEFjjTbeiGOOOu7IY48+/kjjNy/CCJxZfLCIZJIrBoIckfA5GGKUHkk4
-npOlWZhhllpSNaSVpX0oZZgmNenldVCKGSaVZcqG5ZZu/rdhlWv+BSaaUSZI4pzAnWlniGrqaVmb
-bw7aXZyAWlZnnxDieej+njIJNA89kk5KaaWWXopppppuymmnkvbRZaNnZZfNF6aeimqqqq7Kaquu
-vgprrKZmE6qoWZklQCme7sprr752Og+ZtlrG3Dx3HItsssouy2yzzj4LbbTSHktMrcMClZ0WVWzL
-bbfefgtuuOKOS2655m6rhbXX+oQrIdO+C2+88kob7IjrEvtoc4pG+ee9s1XHH6EC42aov1gluq+B
-jBrsF58JG9gvwz4JOnDFGqorsUQIP6zewhlr5TDH6kX8MUsUW4wyUwWX3NLGIkPnMctAMXdAOzbf
-jHPOOu/Mc88+/wx00DbPgbHMgVUHhxxKL810004/DXXUUk9NddVKw1H+tNHmkcgAFEJ/DXbYYgcd
-mr1aq5XvfC+nR/LZDp2cctxc9ua2xiQOt3bHwta9Ush5G9c23wrBLXfKKwvOkMt/sxYz4hH5vThr
-gTtOd22FX87E4ZQjpHjkYjW+OUxpew7d5JQTjvnAmofe3t3okV4c6KwrdKKStt+Ol4uVz747YZH9
-Dnzwwj822e68G4l78srDxaTZvDMEOez2Zc036qkTunronUuPk+zPCxQ99ziZ7rj117+Z/ebbi1+T
-99+Hz35N5CNu/vlbpk/5+vGP5P7z8O8/kvkJrn72yxL+HKc/AIKkf7xjzjkGAMEISnCCFKygBS+I
-wQxqcIMQbAX16pb+HXN0YYQkLKEJT4jCFKpwhSxsoQtHaI4Pug0zzuCgDW+Iwxxu8Bx7+95B/qdA
-kAiwegArIMoOiLgEBrEjDJwdEJfYkSGCsIhGrBgSBadEKGqkiax7ohY1IkW3EbCKcJLh2bL4RS6G
-rli/aqMb37gpUBlvdqSSlR3viMc8xopWc2QdrnQFx0AKso31ap0PF8IcREhhkYxspCMfCclISnKS
-lKykJRdpAzNqLTvXOJcnPwnKUJrrGpo0Gq6occlUqnKVrLQkInp4SC9+UTqllNkYydifK/INjVpU
-4+Zk+cUwnu2WuPSOLuvGSyj6knLA1KIwN0nFYqKvlixL5hKX6Tj+B2pgm9zspje/Cc5winOc5Cyn
-ObfpwT6GLju6aIA73wnPeMpznvSspz3vic98ulMX1CwZDc8J0IAKdKDm5KHzDvnDfC2AHAxtqEMf
-CtGISnSiFK2oRS/K0Bb082PZyUUsPgrSkIp0pCQtqUlPitKUqvSjudhoxoSzCozKdKY0relFFwBL
-HzJnoTbtqU9/SlGNqnNzHV2pUY+K1KSqtKVDzd/dYgrUqEq1pzg9KEIbpNCpanWrFhWqeHxYVKWK
-daxkPSlTv/o9mHJ1rWxtaFUNedWEHoSnba3rVL0qINaFtax87atSz5pX7T3VroSN6lsVhFDm+MEN
-jG2sYx8L2cj+SnaylK2sZS/LWC+4VGLZiUIzPgva0Ip2tKQtrWlPi9rUqvazUdgsw4yE2djKdra0
-xawfcvq+rBZ2tzbFK4f0Wh2P+nW4xEUpYH8rWItAlbfMxehh83TVnTZ3ul11rcH2Wtzsave4clLf
-YKkL3og+N65yFQhdw4tecvi2u6cLrnbfm13u+lCt6U3veMmL1bnWN73rBat74Qvgvso3rd/dL3jv
-S17m8EIcDG6wgx8M4QhLeMIUrrCFL8zgT1jXX9lRwSQ+DOIQi3jEJC6xiU+M4hSr+MMq2PC9MLMC
-DMt4xjSu8YV5gVv/6dbA1O3v97Ab4CAndcDPoy+Pp4vguEr+98jT9fHzgCzkKC/VxesyMpN5m+To
-7vjKu3Uy76As5TCXlMjHKzCXC5vlxOaLADpos5vfDOc4y3nOdK6zne+M5zYbgMrXyo4QqADoQAt6
-0IQutKEPjehEK3rRgBYCn4eFKxrkedKUrrSl8UyAHDcwX6BYhac/DepQi3rUpC61qU+N6lR72giP
-tlV2IhCKWMt61rSuta1vjetc63rXvI51BFotKlxZQNXELraxj51qUGjaiVs+s129TMf/innaYwZ2
-o6zs7LqmOZbNzjZboQ3cqwiX2uQOKZlnh21vr3XbOu22urcK7nVKu9zlPrcfzfxurrI7twe5hSf+
-DfCAC3z+4AQvuMEPjvCEK/zfxbD2obIDhldIfOIUr7jFL47xjGt84xzvuMTB4HBAYSYBCy+5yU+O
-coXfYtlddHe+pRpvos6b3tS2d3K7styXb3XfOtavzrka8/aKm+b0trl3lftzfbN8jS5Pek+DXr6Z
-Ez3MRncq0p0+VZ5v2udYjyrU6Sf1qUe56gjEd9epuvRf5svfKW+7299+8IY3NepXcQAg7o73vOt9
-73zvu9//DvjAC/7uDgi5nkYO98Qr3u0rt6qauX52n359gGEXe5DJnkSzR56mWmc25Ddf08kTceiW
-FzPmsah50Ds37cxsuuorKvopkr70Uj79LlP/+op2vuX+B+k0sn8P/OCbmtVzB/tV1NCG5Ct/+cxv
-vvOfD/3oS3/61E++Ggw/J2ELf/vcB76yHc/tg7D50uQvv/nrvOfiU/4qQui1+98P//jz2tHqv/1B
-BCDp8+t//+TPNPjb/Xm5d1GxJ0aVR3vvZXvIhHsCKFG7x3QByIBBhX1rAmYHiIATWCbpFoET5YBq
-B4EbGFEEOEwGaIHFlYAztIAg6Fasl035Ug9eAIMxKIMzSIM1aIM3iIM5qIM7CIOJgIFekh3rEABD
-SIRFaIRHiIRJqIRLyIRN6IRDuA4/aCWYMQE8aIVXiIVZuIP1wIKIs2QqKIH1J3sHMW4lCGAneEYp
-CIb+Hdh6HwiGDSWC0DR7ZghfaKg1GviGK/h//GZeeThRcWg0FUiHw2WHpqSGKsiGLeiGeQiItkSC
-g8hXhSgzeOiHieiF+bIF9qCJm8iJneiJnwiKoSiKo0iKpaiJgiCFTpIdrpACreiKrwiLsSiLs0iL
-tWiLt4iLregKqUgkZiEGpgiMwSiMw2iKW9CFgsMcX4ZcMsdedDdf0IVu0Bh+P7aMQudfzZh5h4RY
-0/hk1eiM1IiNqKeN0qhTvUAC54iO6aiO68iO7eiO7wiP8SiP7zgK3gh2ozCP+aiP+8iP/XiO9RiO
-t+ePA0mQBamPvUCO7wMAC8mQDemQDwmRESmRE0kokRVpkRYZkFN0kRvJkR3pkR/pkBmJgiBJkiVp
-kh6JXympkivJkm4TEAA7
diff --git a/Documentation/DocBook/media/nv12mt.gif.b64 b/Documentation/DocBook/media/nv12mt.gif.b64
deleted file mode 100644
index 083a7c85d107..000000000000
--- a/Documentation/DocBook/media/nv12mt.gif.b64
+++ /dev/null
@@ -1,37 +0,0 @@
-R0lGODlhFgFnAMZnAAAAAAYCAgAASAwFBQAAdEgAACQODkgASCoQEEgAdHQAADATEjUVFHQASDsX
-F3QAdE0eHVMhIABISABInEhIAIM0Mok2NI84Nk9PT5o9O5xIAHRInFlZWaxEQbhJRgB0v75LSLhQ
-TbRTUcBRTrBXVatcWsJWVKdfXW9vb6VhX0h0v8RcWZhpaJJubpBwb8ZiX8ZiYI5zc4t1dYd4eMhn
-Zb90AIN8fH9/f8pracpta8ttasxzcM51dM52dM53dc94dkic39F+fNOEgpmZmdWJh9ePjdiTkt+c
-SNuamd2gnt6lo3S//5y/nOCqqeKwr+S1tOa7uv+/dOjBwOrGxuzKye3KyuzMy5zf/7/fnO/S0fHX
-1//fnPPd3fTe3vXj4vfo6Pnu7r////v09N////35+f//v///3///////////////////////////
-/////////////////////////////////////////////////////////////////////////yH+
-FE5WMTJNVCBtZW1vcnkgbGF5b3V0ACwAAAAAFgFnAAAH/oBngoOEhYaHiImKi4yNjo+QkZKTlJWW
-l5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6u7y9vr/AwcLDxMXGmkM3ysvMzc7P
-0NHS0CjT1tfY19XZ3N3Y297h4sxDlQDj6OLn6ezZ6+3w0u/x9M0A5r/3vvq9/Lz+kQDqEpiLIC6D
-txAyUliLIS2HsyDKkniIIiyLrzC60tiKoyCPq0CqEpmKJCqQJk+lNLWyVEtSKPPJ3Ddz0stRN0Xl
-DLUTVEyaQPvVlNTzU1FPRzsl5fRTaNB/QwNGHTi1IL6nu5Zu0qqpKVSsVME+4pqJLCazl9Ba8oqp
-jAIA/gTCIOXkVsAVo52OAABgV6kmMxr2Cgbil9LLGh/OIJ6r6QgBLAfuMm48YYzPT1siF7a5qUyD
-u1HibtaUWfLoS55NT+a0+DSklqXPxK5EJkuhm7NdV8pMYW9i3YJsT8q99Wqm2MQn/cihZRBuzasv
-RenrdgnwM8uFQzpSOfrrTcihW5KyogiYM89VF9cUWq7i3+sRTVlB5Lyj6ngNd/58pn0mMUmY4ER6
-+R2nGWCEMbUIGQE2QUYj3Fnm3VibIPgeJ178kEFz4Imn4F8aEJbcWY18EcQLViziVoITOvLSFgXA
-5R4iVvxg44045oijByAU0QMIQAYppJAwPHhIFILx/qUeieDFCIB1igjBg45U4nhBlVSaAEIQYiTi
-2IzXLbTKF1mUaeaZaJr5RAc5aKeIFStw0RErVehARZp4mrlAnmlCscILU8yp3y5iILECBI7AKaeg
-q3DxQ5cuMgLgCg5uZBwuTpiAhBgQKZqRK45CKqYiftZ30aW1WEFDEF58xIinn4L6aCMIabHDDhye
-OqgtYgSRonOLwBqrrKImglAQUjyEalg0xjlRLKEuotayFIoliLC6whKtsVVFai222Wo7KyLT7kpU
-VeCGK26xhJTLmblZGZKuuutW1C2tUc1Lb7233TuqU9c6m9At2wJrLb68JEEGP/rG4u4iBaPnr7S8
-/ohhgsRnNOxwLgU/LJVh9YR8Qwsl3HCOCyHIIDI986yMjgwkzKBMyy63g1LN8JzAgskoq4wzOzT/
-3E0MIIiQggM2CG0ztbW88MUZDAgc7y5aFlHBCDsk4ebA8NryxQsZd7DoV7oIQcQKBpyhRRM/jOCE
-VV3X8kQRcKYtCBnsNsQLFHSLPQjecL+bi9lxApCFEjuM0ASzuXwNtdSMf5yLlkQEAcIOSmzN9S5O
-A6Dxs3HPogUIOSBhRQATy1LEE/d8vq+3t5BhhH0YA6zLFELo47qlocNChhC/unowLRYzDLnevbvy
-e/DC265LEqgPsntITCsPvCEef4fV9CVVz8ry/vYOjzwh3KvkvSrgh+985AGPDbrgvl9PbuoRNev+
-6wjHzzz29L8v7/G8g18r0sct8SkrEeXTyfkigaS9sIgRBCwge/bSlzBNAjAV/BACAXgIGAmmOxo8
-lybK8AC5TGdJh4igBAuhOUaUYQOWqQEIMVGb2jVGAh6iRA0N9iYOFmJE8RFhJ/CzIPn9qxDZoYR/
-NLEcBNClAUzIISWWw6FO+XAQQOzKAocjxUKoUBEImY+pIAEY+GhCCh0wT2OAkEVJkMc8EtGYB/cC
-pRBKjjVmTKER85fCBhlpEQ2c4SYGEKC3XWILCQhDGyUBIBNE4BG7O0IGtZg8SkRIEV+k2CJM/oSi
-R0gShWs5Q4aYY4kaiKiLlvDCBUjZCNcRMYh3zMSXFuEDHGAJS1e65Y20xKVGvPJNurTSjUbQox8N
-6ZhAosEf3ZIkADxQXsHU0QWI6SNkIrNIKlJAHSkpwEvIUEKK6AKfxrmncZbJT4BSxBZUIIgTlsic
-ZyrnE1bQJkws8gxkgieaIEDPFkaiBlCapR21dxwn7UWQTErEpCqlCMBQEJRrKdQKnkAaVFKiUB2g
-aEEPCk5YEpRshygV7VwRAU3lbRaZQsIA+qc+kBLCVriKhaos0CpcqIpVNpxaNwNXCGTJoldWyJ5C
-fcVDl35Up0blKVJjyT6lNvUgW/TfUp+6jzkhJhWqBqxfJQ+4Pqd6FXZXrepUv8rHsWK1q2e1qlnF
-SlVbsKWt4wurW6O6saxKFa5gZCn+5mrXiijNZn8FWmDTEbTBuqMSHDDsODCgWHEwtrHeeCxkucGB
-Y1j2spjNrGY3y9nOevazoA2taEdL2tKa9rSoTa1qV8va1rr2tbCNrWxnS9va2va2uM3tLQIBADs=
diff --git a/Documentation/DocBook/media/nv12mt_example.gif.b64 b/Documentation/DocBook/media/nv12mt_example.gif.b64
deleted file mode 100644
index a512078c7f24..000000000000
--- a/Documentation/DocBook/media/nv12mt_example.gif.b64
+++ /dev/null
@@ -1,121 +0,0 @@
-R0lGODlhoAHkAOe1AAAAAAAASAAAdEgAAEgASEgAdBgYGHQAABoaGnQASHQAdC0eHigoKEIlJEYm
-JS4uLlssKzY2NgBISFIyMQBInEBAQEhBQUhIAFBBQVhCQkhISF5DQ2NDQmdDQ3NEQ05OToNGRHhJ
-SJxIAItHRY9HRXRInJdIRlpaWppLSaJJRqpJR7BIRa5KR2NfX7JKR2BgYGxdXWleXmZfX31ZWXJc
-XHpaWQB0v29dXLZKSHhbWolXVpVUU5JVU55SUJhUUqdQTrpLSK9OTKRRT6FSULRNS7hMSrVNSr5L
-SL9MSr1OS7xQTsBRTrtTUL5WU7lYVsJWVEh0v7deW4pqab5dW8RcWbdgXrZjYcZgXnd3d8ZiX8Zi
-YL9lY7RoZshnZb90ALJubLFwb8prabBzccpta79wbsttaqx6ecxzcKt8e4aGhr93dc10cs51dM52
-dImJib97ec53dc94dqiEhKeHhkic39F+fKeKiaWPj9OEgqSSkb6PjtWJh5qamqGamqCcnNePjZ+f
-n9iTkr6amtiUktmVk9+cSL6enduamb+jo92gnr+pqd6lo7Ozs7+wsHS//7W1tZy/nOCqqbm5ub+4
-uOKwr+S1tL+/v9+/dOa7uv+/dOjBwOrGxuzKye3KyuzMy5zf/7/fnO/S0d/fnPHX1+Dg4P/fnPPd
-3fTe3vXj4vfo6L//v+/v7/nu7r///9//v/v09N//39////35+f//v///3///////////////////
-////////////////////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////////////////////
-/////////////////////////////////////////////////////yH+EUNyZWF0ZWQgd2l0aCBH
-SU1QACwAAAAAoAHkAAAI/gBrCRxIsKDBgwgTKlzIsKHDhxAjSpxIsaLFixgzatzIsaPHjyBDihxJ
-sqTJkyhTqlzJsqXLlzBjypxJs6bNmzhz6tzJs6fPn0CDCh1KtKjRo0iTKl3KtKnTp1CjSp1KtapV
-h6QkWdrKtavXr2DDih0rlpFWsmjTqkVrdq3bt27bwp1L16vcunjn3s3LNy2jVRU/MKhAuLDhw4gT
-K17MeDGCwY0jS54c+THly5gvW87MufPhzZ5DcwYturRkBGkqvgAEdPVP169Z+4Q9W3ZP2hJx89St
-k3dv27uBB4+tWvhO3ziRJzeeU/lN5zWhK5ROk7pM69eZL2+t/Xl3hthj/oZ/OZ789+jn0ROnWN5l
-e5bv4aefGX9l/ZTx7+Ofn537+tr/5cZffwAGeNyA4iFoXnH+FejgcAb+xmCEzSm44IMQ3mbhQPqh
-1KFJH4K4oXwNajghhhJSuJ2K3p1oIoopvgjjihOFWJKNI+GY44j28dgji+D5qJKOIRFZpJAeIpkk
-kAvZOMsBAAjQykdOHhDAJ1QqSVAhAABwpUcf0iJCl2TS0ZGNmZDpSJYcpekllmfyaKMXNtRCZ0av
-jEJQiIUIAAoBcMbJUSEUxHJkQa+wglEpgGKUJ4da1vLkmn1OiZEsoUC6USkDrJmJlIKyF+ksCWD5
-qaUWydJFHagIhCOj/oFyFCKpsYIp3CZPRCKLRXdeumqrs5Zay6kaxTGGniESS2uoNUYKay3PZhQJ
-FYnI8mqjtm5KwAVd1pltQangkYUnFEUrLbUtRGqnAKocsOZGmlDxRwyRZvLlpMwKqC2W5mLEyh5U
-zKAutNjme5G9WOJr8ECerJqKRIQautG/RsjRkRcAFNrRK4kUYQZHGHt5wbsb5edso/1mFEoQVrS6
-L5saEWunt7J+N221DyncUQ5OsJrRk2Z6AWpHN1RxbEc6a2TyRsvKjJAncUQt9dRUT/3DEUgcofXW
-XHc9CEMpK30ylmKaaRAebFSt9to/VLG21F0cQYUmDkXMENRvs13F/hFLXNH131wvgpCy7t6dt9pt
-L3HEH20ADrgWuyrktNguXlT2zAulEsrmnHfueec6KNEFuQt5QoUpYBdc80aXh11LJ2Vw8vnss+dg
-B+2cH3IEHg8zBHRDmuNOew5mPDE6RggTXOtBwQvveQ5oUDFGpnefvtCTNJcsp7qcRomqRq8Q4nFD
-pqMuOZlvLmxR9wCQbJApcbzSbEKoGEt9Q5V+9IoPSlCyEZddch/4dsCESjikfAl5UrdgNj+eUOIJ
-h5BBehB4oZTAT34R8c0rDvEEA8bkgTvog09AKELyWa8lS9NJw3wGHQpW0ILxy6BxHngIDL5khagw
-EkdwSB0XkkhU/jpBxRhIVwvn+NA9A4PIBSGiG0z4LCZCJJ0OwVcHKU7whEis3IEScsQstmSJDpmi
-+ipUOix6sYEz6uIZWQLGIDFJPVw04xplWCKCqHGOK2njdJJ4KBbd8UdAjNAfUchHiegRIWJcnYoG
-OaTt1bEWjPwhTA5pkERq75ECieR+tBgjSMqRPoWcCCX3FMpvoUiTmwykg1AJSJmM0lWlHCONMvnJ
-BHHyJtWCDStb6coYHsSSlPsJD/xgx1raUpU6ecUTisiaXfKylzYk5Rtn8ooi2MaZS0JmTjaBB2Zi
-s5E3McUaeifNGd1kE0OQzTdPEp8TYKEv8ByLGvRgCQ1IoQmK/oinPr+igXfuE56IOMIU3iCISWyl
-n/9M6EH9qdB9qiEE7zQEPhsKTw3woSIagIxpNqoYFmCgAg5YQQY4StLEGECjJTUNDo5AAhMAIQUg
-aABKU1rSk9L0pixYAAM44IKR3pSjBkiNNm+SiixA0gh3mCZL8AAw1I0iEj9Igv9ktJOivmAOxoQj
-GnNSiT+YjgaykUU0W4QTTHj1hC/ww1jJ2JOu1oAJ5quFWNm6VZww9XQvsMMizrCESGwRJ0X1JOqA
-mRHCXoSpSK1FKPbaV7rqaydPOMIe6nCEKCzifp20SRYeVj7DXsSzFYlsD6xwhDNc9q91tckojjCG
-Q3giXUpl/skfPPjVWCpyJ6sdww7mELkMPRYnsgiEomAZ25Vwk2GJNedMgqso0N6yIc51iCzwQERm
-FlclyiTIW+OKWuBSl7jKbZJtKTLd6lo3vDDBmauwyl3H2qS8mkJvQqK7EPgWhL6/1dA6s3kT+4KX
-qnSsiX/LCeAt7ldE3jUvfgOc2pcMmMC+hdCBSbJghDz4vAV+SIUJcuH4ZpiuExbJhgvS4RFD15Ey
-6bCHI9zdEIPExAJRMYzF+9yUqHjF3Y2wi00ZkxvPeI81PsmNcZzZHAvWJiYe8o/ni+KYlekhQyay
-QBIlETd9CXzIGpiYrkyRR1WSOc5kX8YkdkmMPInLChxa/n2/C2SEYPZ6VgrUmZcX5Db/TAFTSh5D
-oizlWuBKVzkrgaG8oLGMqKoONxhYISSgOokc2mV93qXrgmmRPv0pUHfqlUL4rBz7McTS2AI1nYeq
-YT4mzcJsPnFCwjWuKqtZWkYQQ2/NnABINHoiN+utclg56cJqKVpNe7VB+Izhg2yCCnsYrkL61ev8
-MpgjzZZrqlWtkBWSkyFiyp5GYsAFKmxCI4WgQ7Qd8i9v//cgqBSzAH2tkWg9q9fELvZBZJGIXM3a
-IMy+dZ2Z/BFNo9q8bmRIrhfipkLXLBS/ukgpCtCKcT8E4axqYVYRUgguU1rh2Hq3vqUNcH4zJBV1
-aDVC/vI96gaHMYl2UwgcwnA4xLmt5XGI29zwZ/GnwVxqbYsa1hwHOMEZxAtmmjTebj41vhGB53/z
-uUNOjZEPuRtlG1850eOQ85tHtg5rVR5BHH7yfUMkfws5hfOGd7uxh0J3vGsI0w3SPLPbLhQPPB5F
-FIg+s4HL7J+Lew1MXbjbYhxOwf4eQcSO98293eyYoEIWvn0QkpfZ5BQhNJl5jJD6TW8hpYCCQPRc
-sj4Q4glTzQjXGRI+0MubV+8C++P/LpDL+fuz6eEYFQA9ctWNPuCQl4iYxyzLWmywgw0RU5dqnpHQ
-1RDaG48IDTEYIvYZfPUUcdPw+TUA70HfIIlPdkKk/v8m7hM/9zRm0fJh0jAh5AEnOISwkYs8kFGc
-4Qx6Oib4tVoQJ0LaJVFcchS/fN0XFqQOdANKXkcgHzZL6+de7Nd1/UdImISACUhW81cd43VxLOaA
-FgiBznaAGFiBBqiBSNZkBfiBDdiBDyiCpHaBJihfBBiC9PdsHLiBHtiCMSiBAyh/LwiDKJiCNxh+
-KmiDO0iDCyhJGViCMkiEQNiDMJFCSOh/MyiAQfhMTDSBFGiER/iDVdiECOFOFPVPCLWF8dSFXlhR
-DBWGeQGGZFiGY3iGdGFRGDVTP7VRNvWGJBWHcghUbliHnkGHeFgaeriHeShUEeiELFiEJJiDVxiF
-/iOIg4YoiIPIiC6IhT4IiUkohey2hOoniUxIhStohZuIiE8ITp+YSpbIgCdYiIpoijrIiZFYaomY
-ipiIR5q4igo4ikKoipPYioRIbbQIhbF4i6HIX0O4iJ3Yi5kojLKoi404jMboi7sIioGojKcYjbko
-jYfIir/ITpTYdNloEUvmccn4S9vIjeFYitToiK9Iis94jK5IjLC4jMWIjLb4juUIjfOojjxoEXM2
-ENJnd9r4M3Gmj9M3hRORj5unJtc3kP9YkOlTiQfzZJICJcImjhmxjwJBkAwZjF/nJ9gyC3g2LN+X
-jhSnkYAnaHbyfDUYkpdWkYWjerCHEaImEJzi/ikRCZIHwZF59iWZpm0SeRE26ZGf8JICOYusVxBr
-R5O1tzyTc5IJAWzCkpRKeZSbByrL0o9M4y6BF5Rz13e3d4+PWC63tpXeOJQDkW1YGRHmIjTtsm5P
-2XjYkjxF2ZUVASsaV3Jw6ZVwApZhWZdmeWuvBxFedm7rUzAFN3k7uSiqgzEmWZhTpmwQcZbDNzJd
-Fn+nxyt1MpcVgSl9Fnk0g5eIBIKBWSspNxGPBphxeWsVR5fWaJiAdwBBM5N19Wf3ljrL85b1lXB8
-ojGWWRHGkmX/Y3CcCY5riW+qw5IUkWtOd2u0mZpDSThqmVqs1nFLeWtOCRE3A1sZAXZXaRHx/jIv
-WsKSv8l/5NiYBSN5GlFuAtNuGad5PnmRn7l5X/Kdl5hJDuMQKYM9/rIHFZMR5Nl6IhA0OjkRHDM+
-GLGfAwGf8SmU0Yc+V7J7iSkRK9MyDUkmVyJ8C0mVFuF9WAJA7XOQAzFw26egn0B3/0kRPPNE5VJ9
-ZFIo3eOaE1E0RxOXKNolFHAJIMqenqgSQzd1V5M1SMc1X4OOJoE2U0c1Vfc2MheAG5GjN9c2fOM3
-Pbo1SocRStpyibM4jfOkRwA5vIigJ9F2hRc6cldtE0dh2Qg7slN4nXN4uIN215YRXup2xROmKPGm
-zgM90vNmTzOmfWSUKxE+AlpG7eWMJ/FK/lxJEJaHp33KP6G3E69AQB5UPYGKjcGJEjQkQZDKjChB
-qHk5ZRz0qC9BQiP0BCF0QHoqYp5pE+kncZEqqJnqS8opEONHfr/SjXY0q/OxY8FJq7Wwf6RZTKvK
-qq2adXlpfzLBq7rqe1XUqwWBq7k6jqXIrC35Ra6Ke/Eoj0eGqXq5jtdKjyWhqQdaj+oIrc3agOIa
-rS7hrcoKrtjqq+b4qkZWruZ6rtPamdcoqehWqvbKp7UIr/Eqr8KamdpKgvwannZGVQOrmC+hqcf6
-rTB4sPq6sATmsJPqEYQKsem6gRKLkdSqE7mkTvhai5M0rwA7jTYxTOyqrgxLTcvkGhk7/rEfMUoW
-O5k4UU3X9LHA+hBaqIZ0IQhkUE9YIFH5pLNwYYZCKxaKsAWNwE9pWLRrQbRMqxaCgAL+BLRPmxZs
-SBEZ5YehQQIeUAEGMAE9pbV5eIdiqxgbcAQqMAIdYAGE0Ydlexlu+7aTQQIQMBg85VNyKxlB5bIl
-sVm1sF3NOBKR9Qd4sARnkAg54KwaWxNZAAOA0LLjWlVG5QnJ9Y0qcVdOBVVSFbhdmgVXZbNAmq0x
-0VW1FWP/yq0uYVYUlFanW4034VZwNRBzhYqFahOYm1eM5Vfs2LlHFrMWi1hJtVh8pbsoO7IxEVmT
-VVmnVa0o4bedpbiiKxOiRVqmhaiu/guPqsVarmWdlqsSs0VLYFWvI5FbuxWbtFuw7yVcxtuuM3Fc
-mVS5zGtj6uu7p7pc00a/ybRMAwG43asS9oW/BMsSDwbAOaFeRcRe/YsS/kXAiyvA03axJIsekBvA
-DlxdDBy9NvbAEHy9LTLBDVzB9wW9N/rBCqzBG8y+K+LBI2y/AHfBK+xgJnzCqHuEKsylMFFiIuyu
-OgzCm+qOL1TDG3vDMezCO+y/Mby+M+yIQIy+MAydMlu8MjwSnJbDNoyAS0yvKXbETxywQYyQFrdl
-qElsyEFlS5eQYtagD/EoHWKRtQBAH5kQfxmfrJSPFOqQ/ZqgXWI2FLlnWvzE1nsQ/ntsZahZxF0c
-EUApEIuWfBxXxbD5aSIJk4oMEYeWaC75yIiMxnuWcAeqSYdcoJFcxRDRkwgjym8cY338xJ52PR05
-yiRJoAj7wnY5EKRiayUXb0/8nA3xdINMnbFmvrq3kcJiER76xOnGlyNKwmXsPrQpxt9xbNqndn0X
-lYJHwcApegUTbpNmy1sMSfO5bBkXo80pEdxmbkPJKNwCAMfMEOXGeEZUqiljoFGcy7aXfPEGHfRm
-b7I5liKQzrAMynt5lwznOtq8zQIxzMK5PKfpaxB3f78MJ24ZzROx0Kqaz1uCyRjsEK/Xl7J7yusL
-ciKXEL0ymGVZuxMRLUCndQYh/nVDWqSHc6RQSZQQbUc6+nI7h6VHEKWQ7NBDo2lTenNGZ9M3jXmq
-k5z9PBGh2caYrNJL+nIwd3XCetRtXMqETNIN/ZDoAwD8KBCEh6ahoKbOw6YvTRBFSae483Zx58QU
-/SyXIxBk7Tx692vDadEXvRAsSZwFsdV459XCk3iLF5LTTNTYO9UP8c6fLNiH6s1w4gWpx6JM5Hmm
-15610DqFjRCl5z/HKWes6XcV4cqubKMGIXu093O+qZ6c98qCzRAY6sm77M+/56kGgaHOR5gVYXyt
-S3A1yj7hzBCxqh+pbdembZYxmjGiENxy7c+1kH2MWRAMCgtjUqF3fNooHKsu/lF+53cT6YfE9piL
-7gd/SVzNM0KsMJF/VFwQvJqyHBywAHjeTLy7IMveW3q+KFzI8N3d2R3fXBzBPezDoXuO7a3f/R3Y
-/v3eUCzg963e+T3f9W3fBq7gDI7FnJuvCfzfA36zxo3f9L2uAU7gC+7dEa7hG47hGS6KyJzgJF7i
-1mrhJm7eH37iK96OCA7iAP7iLN7gKe7iBX7gEy7i8evhNA7j8p3jwLjjFC7jNr4QOVu1buG0SD4W
-Sr7kYtHkTq60Ua4WUD7lXHG1E5G1eZsZcbvljNHlXr4YYB7miDHmZH4YZn7mbQuII+7jKF7jEn7j
-F67iPT7jc77f7j3kPy7n/nAe5y1e5H8ez24e6H5e53Y+6DjO54hu6Hge4kFe1EAO4UKu4/zN4xw+
-6Y+e55Su6Zle4YSu54p+6Ive5zFL0Ize6JEu6e5d6kTs6KrO6a/u6adu6X0O6m8u6nR+54U+67b+
-6Zsu67pO66M+7MQO6Il+68bO679O5Ki+58je7KGe7MHe6w5+E3F8rF62ZHGM3dglmab+Etk+3s5+
-7A2xx5EtAlK9aZrcIRR5xrINZbY6kXbsxqstu5rM7R+ax3Wcx6K57koSyAaZKvGOPA4pyCO93hFB
-ynCSyPWOEMaJJAoPzwVNBSbLk6v8JVAdEcOsHwq/dZN9EA9vZhcfoivJ/tgOMS0Vj48jH5PDYvLA
-Dp4agS+z/PEJYZ7qMikSLxCs0ANMwHj+6AhTaRHrLOhw5j4aDRE2zxGTkp0XsfM9X5WOoCzB/Nwv
-n8/YTPMK8aAM/ZnqpjR2cO9cvy0LZBESzT0FA89a/zJoGdPc+PUm+pkPndvQfekXcScL13D61tNU
-WtNYitM/p20JbRB6/zY516RA7fcCcSdxzzBDKjU/bdOI//cVLduDnzdX0zeHrxCahpjvnkkr7TaG
-D/kI0SshEwCQaaFtrhB2c9Ku09bCA6Zo/RBQvXauXzt2cNYXYTcyo2m1Tztv3ZtkRvtcvTmwf50a
-8ztCM81szdW2g/uV/maSgD3u1V5pUgkldeco4vMx1xmR0b8QMvAFj039lqLW/VkRlf3tjvw9GQ+g
-2Q9uQ8OcGvH94V8Rdj2dqY/vo5+YBlqpSkKgio3IACGgVS2CBQ0eRFiQUhEwrxI+hOiFQqyCtETQ
-qVWKwCeIHWtRenLIYa0XgDyeJCiRYsFZBzCi9AjykAyTMDuqLJgpAEeNHG1CXNjw50OcB1vaGAqx
-ZNKCS5kaLDUAwFQAEwn2fErQU5c6qEjWzJpRKlUKosZaDbu1zg2wWaNSrRrrLQBHTNV6bdr26dyp
-EwsJDFvr7tfAYuH6pVo3sFq2hflWdXVgKtLCBJ0yvVxZs0FUYzzl/t0cmrNnwqIrd/58MLPpwKhB
-sw7tejVszbNt2qZdGHfurLt5P/X9e2hw4T+JF0d5/KFy5B6ZN1+uF3rS59NVS7d+G3v2k9UNeude
-Orz28cO3l08Inrt66+zZtz+P/rp8mO+h278fn75l/R3xN/+vuAAF7I++AYU7kDf3CjSQQfQSVNDB
-8iDMjULYFtyvOwnHs/DCDcPrkLUQRcMwQ/8+XA/FFE1USsXsRgytRBbTc3E6GGOsMb8Zo9sRIRl7
-fA1I/oT8LkcAjTySyCGBQxK5G2trkkAlxSPyycp+FNJK3aJEkMsIp6QSSCzF9LLCMs2cUsst03RR
-zcDc7O1M2uBksRJMOjFz8QQsLOGzTz//BDRQQQcldFAN9iw0UUUXTfRQRh+F9FFHI6W00j8ntTRT
-SjHVtFNFNeAjKzciqKBUU09FNVVVV2W1VVYfINVVWWelVVZYa8U1V1xv1bVXX1Hl9Vdhew12WGNn
-feARMJdltllnn4U2WmmnpbZaa6/FNlttt+W2W2+/BTdcccclt1xzz0U3XXXXZbddd9+FN15556W3
-XnvvxTdfffflt19//+03IAA7
diff --git a/Documentation/DocBook/media/pipeline.png.b64 b/Documentation/DocBook/media/pipeline.png.b64
deleted file mode 100644
index 97d9ac007473..000000000000
--- a/Documentation/DocBook/media/pipeline.png.b64
+++ /dev/null
@@ -1,213 +0,0 @@
-iVBORw0KGgoAAAANSUhEUgAAAlgAAAEcCAMAAAAsmToJAAAAAXNSR0IArs4c6QAAAwBQTFRFAAEA
-EAEBAwUBCgMBCAUKAgkMHQIDCwYXFQYDBgkVDwgFCAsHChASJwkDFA4NEg4TDhANHgwHDg8aExAG
-DBEjBBUZERMQCBNRDxU0ExcZFRgVFRcgCRkzHBcUDRdCNRELIxYTAx4mLBUMEBwcEhsiDxwhExsu
-Dh8XJRkQByAtDCMUHx4bACk0DSsiGScsFCRcJSUiGSZCDiwqGCg1LyQbIycpVhsPDy0wNyQVECxA
-PSIfCS84ADJCEStWRiIULSwpADdHCDkgEy1/BjorEjhADDhXCzZvITNPUysQDzs8MjIvCj04BT1O
-PDEoQjEhMDU3LzY9KTdFTTMYNzk2GD6PAEpfEUVjBExFCEpPB1ArK0FjKEVZYTscdDYXG0d5SkA5
-FEiJQUNAOURPAFhCA1RpP0ZJVEMvYUAyBFtRWkYnDlR+QEleAF1jkTojHlV1AGB4PlN5YU87cUws
-SVRXAGaBWVJKUlRRRVZlAG1PWFNSBGt5AmqVAG+NAHNpK17BWl9ifFs9KWmnSGZ0YGFfp1IuCnWj
-AHuKbWBXoVNAdGBPDniWAHujTWmLk14rAH+ch19XX2aRX2t8AIeLiWgvAIeeAIaqa21rOnehdW1m
-AImspWJYj2tLW3C0AIyvWXaNAo6xb3Z5dXZzent4WIKiQojAen+CkX1pcoSWcYDOoH9fp4E+Y4ur
-hoWCXIvGb4mut3xpqYNYnYdUO5rDyXxdjY6LYJqk0IRGb5azXZnMjJGUgJWqpJB8l5aUyJN4kKK1
-rZ6IYqzge6Xho6GdnaWpgqy6yZ9zvaR0hqzMk6rN5Jxxw6mF26lbq7C2pLTGwrCbs7Owvb+8zcGc
-8rp42L2xsMbY3L+jtMfsz8W2nM/yx8jH0MfA7MWU78h/3crIyNTo4NLD6dK1z9bc1dbT3NXOv9vr
-/OKSwur8++Gw4uTh0ef78uPU+OPL3Ojz++bGyfH36evo/+3b6vT88vPw/feu1/v+//bb//nK/PnW
-5f/+//ro+fv49/7///37//71//3//v/8sZeTnQAAAAFiS0dEAIgFHUgAAAAJcEhZcwAAFY4AABWO
-AUTUBDsAAAAHdElNRQfaCRQPAiJBEFMLAAAgAElEQVR42u2dD3wU5bX300nWws50shA4lyTGikRE
-Qy0aUChKvJZqTQGBFNurVo0FWq2VqhAq0hc0t1rAxtLLpu61cUl6gWtNe3vb7Z9IKm+Xqn2tkFih
-GmwFA9Xwpw1s/UOyCc97zvPM7L/sbjabXTLZPL/PhzA7O7M7s893zjnPmec5k8WkpNKgLPkTSEmw
-pCRYVlSjp5n/3+3xGGsONHt2vx1t04PNTbtP8aUujxAuHvN6XjHe721pbmqLsp/H021+crP5wce8
-Ta8Evi+wKMHKHKkwjf/vA+D/77SrAKDeeTRiO3/vcnzDoTzXgy/+CEKMbVdw5dh9tMGubAfuuMjf
-E7HnfgAf/X9yJn6Aupqv206fNfYdXHr/Aloc944EK7PBWg9QurVxlQ3s70Vs+FmAdQ0LAP6By1cA
-KCT2AsBqXKme7mEfajBr25MaTIjkSjPA0mHsVnz/G8jgzyBna4MGH/UzdgHYt9ZrMNovwcpksN4E
-eJpeHbLB5PDtelT4L/wP4Fr+95NirQa34d85cB1jX3eAsGVhiPRuR644WPjOafxgHXw9uD8axL/k
-3+gj3P4vLgJ0SrAyGaxzoFCsfpObJh8aJVMtzUSMA3JZTw/Ab8RKYcD+Rvu2ehsJJIBu9llFwdW3
-0l8N1B0CrDlgpz1K4OfIkRqgT4cOjNkkWBkLFiM4ejT4nXjVrcH/wb9G4BUUwOcZ+xCgtkh74Ci9
-9Iu1Jig/BjhDhmzCGUTzccaKNx9lAqwSUAVY17Kvw7U7S2wLn6fXRXCzn90P2dIVZhxYIlxSiCE0
-W+8F1l+GYDU0hG99P9/gVxiEKxiGvYPMoCMjT2a8fxyRQkQw9HpJg3EBGAmsr4PDz8Eaxz4F+UBf
-+DjtMZ0WJ/9ZBu8ZDlZwfX7fjTG0x9ibPTF93D52UEdELgD9LXYw19zteA7onMwLAHuI74SB9QGG
-b372DKAvLQF4xN/7FPlR/17gjD3H/BKszHWFYRbr6siEA7sL4Jbga4zG2Yd2sCuqaoC1H63YS3wJ
-nSW3RyFgsQ0coQLsNn4KdD/3gtcauG0HOCItVgYH78EYq4fHWOFaDLA6tMNHe3St0m0L3+Ixln+/
-BqP3ib0xGue2LRQstmu+vXjz13mMZYRbubhoFw7yXyRYmdwrHMN7hR/fgVGSdrovVzvEUpuXYPhn
-wG9+wJcOaTDZ3GcOpU/fiACLmb3CP5o0ncemCcamQY4EK+PzWD3zYayNYvcwYUj0UiCldTf+9yXQ
-2RNlKl+6Aw2YLRCtU/D+uBZgxQDr9iIkrauIeo067OOu8Cfs38Fxgi9+XoKVyWCx+wBKG5t1tDfU
-9ME81hlybtki3U59w9XNuOVL/r+IJbu/58yXwOgGdPd0aXAuwXU384eAdT7YtzXqPPO+HuybPRdA
-9hnW5YDR2zz41ntnJFiZDBbbbnfQvUI7OBaF5bF+ZdwehALCj+4n2n9qLDkK/8zxMdSNjlA/3UP4
-vRFqsf4+xhG4V8h3G0sB+/4ptJjzB5luyDDV1otUVXd9vbGmpXFr09td96mXha5kT9Yb4psfbKxv
-EgMdDjZuE2MTzPfru/9eX/8HsabWeMcY3eBtaHrL+LiDjVt3B75v224/k2CNFL3+D/kbSLCkJFhS
-EiwpKQmWlARLSoIlJSXBkpJgSUmwpKQkWFISLCkJlpSUBEtKgiUlwZKSkmBJSbCkJFhSUhIsKQmW
-leRP28f50/H5EizLSlHEDC9jCuGxJ6crtoU7TkVjxJxkuGu+XVvNp9t0bS9SFu4Ra1+/PTt/c+R+
-uFLbfMJYtNvMbRk7nq34JFiZrPB5hYdsoKqqA9Sjfbm61ZhkOAdwG1D3IVd2WhJFGp4CB+6Xw8Iq
-kD6j0QbZR3D3F/he8CPjHT1s3r0EK8PB6rHBLARmby7kRm538i4QYP2Jag4dmwkOKkU69gjbqcEb
-rOddgD1sL8DDofu8D/C4/9gCyPHTrNVZp3oXixpZjCCVYI0gsHy8Tihjf1Rt+Le7pSWw2U4bjBZg
-faUEkRJ1QETZte8ShefDT3CxtukV1tXSQm6yBXf+d7Nc0T9o2/d4SUjCyf8iTJZgjTCwng2+FVKG
-janqMn9o3UgDLOKmy1g83NrKQ6zzwc493+/YFFFKpoAqIuk03/5dmoCP1g/00xKsjAerpIWLYzMK
-oDTw9ACfqgY2w7A8rCDpHEETzZb+kPgCeIpqAz7HOD0PI2yXMfYpUcS2gGosLwf7bq8G1zNuwn7D
-JFgZD1ZAFBWdTxVBcjZHezJFKFhPAfyQwLqDu0LOGCysmi8qHS0G+Dg6wR4qJHKCVy4ajWtn0lec
-SzvfDzczCVbmg1VQxWVgs2E6oaY/HgcsP3FVKvB6pGUDCLCu53aMB+eE0E9E3y9ntxet4Gh6a/QD
-q3Qi62UYyyRYIyzdwPt/O2/Xg+X4+oJF1bNhEV/k1YgWCVdIXvGfIupCS6Xz9/8+xQGQOwddoXh8
-ABqv/8JNf9/a2goQ0jWQYGU2WH7W0cbJ6dL6lLYNsVi3AnzNWHfwyXV7WDCOZyI4p7ptRvW/XdVb
-T8/B4P1TZtnRccFCWqoEa6RYrCvUfHPt5JhgfTeQ5uxobz1DVd7HElH0rIq/cb5wAx3yCLTDbf4z
-It1gxPElMAE7mCQqFS/BGilgIRiXdeDyTkoWsO7W1ihgvYkheCuJPz7nBDumUTbrV5D3NvOdT2VI
-j2O8hRudxz/8YT97EXL9fnSFz/nZq4FnpbA+z7yQYGVyjLXcAXb+MIFFEXmsIFi5gU6kv0tFs6OK
-eGsBf1iF9g9yhLnMz0vh+u/npd3VN/j7/EEBpWcCYMngPaOlqCWhSatd84tUteDGHZF5LAKLv+xR
-TeGLQ/N1dcZm8faGEjV/4VF0hCoHaaaqnOIrtYXivuP2MlBnBOvEq6oESyq+QobC9ER7vydyq5Eq
-CZaUBEtKgiUlwZJKnyqmlXRLsKRSrhJlBI5KlmClX+USLKl0qFKCJZUO1UqwpNKhZkVtl2BJpVzt
-qtIswZJKvRSlUoIllQ6wFAmWVOqlKkq3BEsq5apWyzokWFIpV4eiVEiwpNISZHVLsKRSrlpFaZBg
-SaVeoCidEiyplKthZGYcJFhpV4FSPgIHZUmw0q8KtFkdEiypVKsbwVIafBIsqVSrhNCq7ZBgSaU8
-gie2ytq6JVhSqVWVSlZLbeiUYEmlVp4ChexWebsESyq16qzgZmtahwRLKg1mSylvlGBJpVotQLGW
-T4IllXKrpYyAjKkEaygEmU+WBGtINE3J9AmHEqwhIwskWFKpV4mi1EuwpFIvJbMHAEqwhkrNme0M
-+4Dl6+w4++rs7EnT+Q3R6SRysxm7hu3D5HQGC1Z3x7Kc8RNnX2XIds1VadXU8ebS7Ik2W+pHlfja
-Z+RMnBg4CVt6z+YqW+CHmzrRNr6x39PpUJQBPQjF10anY37HNek+nYkXm42Dp6N5O5MHy9eQs8Lt
-CqpufOirNGjtNaGv3POyWlOJVWeVbW3YCUysS+/pTHWGnc5VOYf7OcKCgSSzOm8cXxN6Au7x6T0b
-15IVoSy4LtYOJwlWs80Z/slnGSxaYUuZ1equ7XP0Zxcs1NJ+TqdNUaoSPZ2qyKM/u2DxCz/flwRY
-3fkrIz/57IPlqrumKjVcdUReJUMBlqtuam3co0y4sENn39M562DRV3oHDFZ7Tl+IhgAsl6smPxWD
-LFuiQXT2wXK5NtrinU5VGbQlcjreiX0/eQjAQhtcNUCwWi+OwtCQgOVy2gbPlWdetK8bCrBc7nh3
-broVpTyB09m6xGURsFxrywcE1oGov/nQgOVyOgadIVrisgxYSFb3IH1h41KXZcBybawcAFi+0VEJ
-GiKwXM6iwXHVNs9lIbCQrNiHWpFA9r09+q80RGC5VtYmDlZBdICGCizX2nWDSjPE+sWHCCyXszrm
-sbYqiqe/89FclgLLNa8lUbDqV7qsBZZr9mACeJvbYmC55nbEuWFY0s/pFNVYDCy3LUGwfBe7rAaW
-syR5rg6sdFkNLFdsZ+io6KesQ3uM5h06sFw1tYmB9aDTcmC5ViQ9Rao7x2U9sNYeiHW40/ob76e7
-LAeW62JfQmDFMlhDCZZzWrJgHV5pQbBim6zGfu7qdC+1IFg1iUwyyvKstCBYrquSBSvfZUWwlsS6
-xtv7id5vrLEgWHUTEwGr3G1FsNY2JTmgYbwlwaqrjToEprMdu4UFFQWxx89oLguC5Zp3IAGwprqs
-CFZNeXJgdaywJFiurOiDkwOKZdGWWBKstZ4EwFpiSbBcSSZJm93WBCvaLcP2ELBi5bnWWhIs94PD
-F6z85MCqqrMmWBdGM0mOAFexplU0bLQmWAn4k6yl1gRrYnJgLbMoWHN90buEhmL1DGstCtalIw6s
-iuEEFus3xFpnUbAulGBZGqwyg6uY4zkkWBKsZMDqNMDySLAkWKkEixcHiTdxVYIlwUoKrGYBVrcE
-S4KVUrBE+B77xqgES4KVHFj00ArFK8GSYKUYLF/cEEuCJcFKEiwevndLsCRYqQbLqyhx5r1IsCRY
-SYKF4XurBEuClXqwKuONTZZgSbCSBYvFe/yqBEuClTRYtRIsCVY6wGISLAmWBEuCJcGSYEmwMhGs
-JRIslFM3phzrOsQ54keHCViz9VFiI11fGe901kiLlW6wwOBJh/zYW10EwwUs0A2wIA5Yn4AVEixL
-gAUZBRa+KcE662A5UeZ7xrITN3I6hydYEafD/yewnBKsswqW8xOA0jfRms/RItxM9oo0HMF6lB95
-qVO4c+PM5vKVKyRYaQeLWyYOVo0uIIK7Xa5vGosPDTew6GwEWF8Vp6MjTuKK4WRJsM4SWKYQrEkA
-ZKwuIYwESxcu2TS8YqyAVrrcAJNx3RaACUZc9f1S8oEyxjrbYNUA3GEE658nyAqXOodd8B4C1hf0
-vG/Tyq/i/25yiStl8D40MVbIi0K60Emzhm+vcK7xoo5e3CA84b0SrKEBy2m8GId/vxgIroY3WFt4
-wPXo5fxs7pVgnX2wTFdYQ66Qa+MlwxgsdIWbTFco3l5TALl11gJr49xJ+Zfem+nphgIRvF9EXUWA
-q3HxWwZYzmEIVmjwjl1BKrl1OYyzFliXGB3Xh1IOVs0NULppoGD54oK1ZlL+TcmBZYby+sO8a8g1
-ziUyWYmCNQlqBgpWd1ywHr08/xpnUnksI91AOQZ3gVii1RTI5z2UIFg3wNI0gvUFgM9sqrkHD6wu
-xWBR5kindhwQWNOUKl9MsP7VyB0klXkX6Z6QBOksc22CYH0ZBg4WKNXdMcH6ajBlO/AEKcdpFh3f
-lot0I8Ry8UB+ZWJg3aOnE6y6POCPqXlUh9tSDNZFUOz8NBS6BwoWKoytIFiI6t14oNclBlYqFAoW
-IZgEWKgwtoJgoXn5TE0BfDIxsFKhULC+gDSmEyxdXLimq9ENr1in67xTXhxYC6V1Bueom/iuOl5y
-t8UC69FR8DDyqn87CbDC2AqC9W90OP8Gk4YELPScyYIVxlYQrG9SBP5lXXcOAVho9wrTChZ6F714
-ZRhXSNbdBJzQVdyaBVzHp43VpS6xSaQDDYK1ln6xLaH2ZUBgBdkKgnURXEgxd27dkIB1t2sQYAXZ
-CoJ1Azm37+uwaUjA+ow7ra6Qmp74mOcMmq8vQK4bF9H5110CY92uFaDjXl+dh32PFWi9hdm6jbbW
-H6qJ6QrX8r1CDeLEhgQU0hIGW0GwdAKrJhTmszuCNBys2fUJnI4adjrEVhCsKwks/BU3DokrdKUZ
-LIxkddMerRFm+fuj4A4836uIIKIDadJu4ZcVgja5Tti5c4m90jgxlgnW7CAFSjKq6gMWWAOsS5M6
-neogWJcSWO7MBQvbiiei5xFBhm5Caua6XIaxKuC92eJNLmMtIiiM2uwEwJo1OLCmtVvVYiUFVmXn
-yLFYwiNehE5vBeUHuOaGgeW6h/dt9W8PEKw+MVZ3vwqNsYgq68RYfcCa60vgdCCcKtbHFQ5RjJV2
-sJaCkWnCBfeaYA8lHCye7dRhXogrnFwXoCxGr1AfVK/QoCpar7DYZRGwBhS8V3b27RXqQ9Yr7B+s
-jsGB9X262y9uDlxWh/ZlFrbUo6VLnSFg1WFHG/faMgrj9jV83GUgeI8Hlisv+TxWkKrwPBbEymPp
-ISOv+tOWgn43ASMZmTKwKjti5rH08/rJY9WJzO7Fse8uzU00uz0QsMpaB515N8YifttMUgHkhoIV
-SEKQC7oE9JB0Q1ywRJbiNtfAwZrW3h098/7pWJl33XTi/YPljH/bmSs/pWBVdsTIvFOO0ribHBus
-uov4uYWl6Psm5VMPVr3SOLgYy8CmeFPwRbEz3BWKtYWbAglS/SZX/2Ald69wWjhVCd4r1EOzpmkD
-S9cHDJajsiPuvUK4qr97hV8QRIVb6tSApccDq7Vv+biBBu/OkPkewQkf5n9ha8OWnVHmtwx6dEN3
-UqMbQsCqyZ90zyTRFf3ipPzZnGy0clvmTip9iC+izSO79uiVBcaYjnxw3TPpwltMdC9cEgusCAd0
-dkY3mPcIL9dzuSOnkxK3mddcWZA/9aEgWFvmFly4xEDm0UmznP3dhA7/7gv7lo9THN0jfTxWKFim
-uzScfDF/W7y42ozGzFvSfMyMGZ/R3gVmZGAZsG7g8z8CSUdxeDRmRozug3NNsIzzXcvBmgR5mwYJ
-VjkFh+0SrFCw9E/y4VaFaylDV8xpKtxIMR+a2Ro+k/DLGDg715iDSOGmGgzfruW4Xc9XWwesOqLl
-QmO83Fd1KN1Y8zli7Vu6fq9z4yQaJcPBwrdmbdp4ER9IQxHZeXWDBKuWdzuaRzpYgU4hgkPjBWqM
-7u73aaSMDvS83G9yjJwGTNfxZbrhLpb58CyA8wSb1gHLmEEIGh6p8xJ+fM4r521y1XzxXpcxNpnA
-cn6Cj17EUP9eAuu8/mOs/sBqNe58jHSwzE5hjRhz5TSGXrnoRxYjsraEgeUU/bxP0p9NZorB2MlS
-YGEwdZHRwXZHDrZaczkYYLmN+YRz4bw6BOvewYNlPiGvRLpC0xWGdf4IKmMudBhYhgpNyAywnBYE
-ixz4F3XI+3ZY3Qa6HUJpCAOsQCpvVF3MAcoDA8t8Ql7gaQgSrOgWKxwspyFzPoVVLdaauWvNVPZa
-d8g0588BxlhiXrRpscwzShFYtYG7Bi0SrABYGGNNDomx+oJ1XUjeMwSsqy0GlrsAxvKFbyFYGGNN
-EIHUBMMrfisQY10iDt1IfaYCrNbgXc5aCZYJFvX7Jm+iXmGhKxKsux+l0fPXO7d8EfKvDgPrX83O
-oqXSDYUr+QCUUS7R9auhwArByuWnhwwFe4Wue4KT7gcNFgu5f14uwTLBMge7FrrCweKBvlGhxZyo
-E7RSYvVtVoqxPgGBCTmBPNb15tLkAozTRR7LeCt3U8rAKguC1T5SwQreJKwxK0TiVT5J55lpfJvW
-GbUjt1yuz+aZd9BmG+8Gt3GtmaSXbnLpVgret+B55M9+SBzKlhsgV9xOoCNd6/qEPoGqSNaJt/RL
-HxKZ95SAVRvuCeVM6NRpZBe3NYMsn5xiL8FKJVgs1A9KsCRYKQMLg6xpXkWpl2BJsFIKVi09H09R
-CiRYEqyUgtVBw2YqFaVj2IJVKcFyWfXJFM2K4hmuYHWoEizLguUz0qPDEawyRYJlWbBoGkL38ASr
-Q1HaJFiWBavBvAs97MAqD/ZoJVjWA6tNUaqHJVgdNONLgmXdx8opijoswaJR+yDBsi5YZsJhmIHV
-wW8bSLCsC5bHmFMxzMCqCBv+KsGyHljtxpSK4QWWMFhh04wkWNYCywyyhhdYFUbZDAmWdcEygqxh
-BVZnn0lGEizLgYVBlne4gWUYLEWVYFkXrHaRyRpOYHUGRlVLsKwLFgZZZRYGa3x0722oNdZJLbMo
-WLMzC6wZ/VQtI7CWWBOs/HgGyxyw31cPuq0J1vjkwGq0KFjl8Q66mo9PzppnTbCmxzNYsW/qtFnU
-YuUkN26xc601waqPd9Beng/Kml1nRbBqlvWtsuapClTYj3lTp3OpNcGakRxY7BpLgrXCy/qN3rNi
-O4+hBGtljKExtXjQVY7Y0Xu3zZpgtSQJlm5JsK7qZPGj9woEy7vUimCNj8GN6BF2x45YKtxWBGui
-L0mwqjZaECx3fvyDBsoHZbHxddYDa2NF9ENuDYx8jTkOcK4FwaorYMlqqgXBWtEc/5gr6erPYo0r
-rAfW1JhGVunv2tfc1gNrbmfSYE2rsRxYbls/x1xL3cIsxmLxM3RgbVwW02CV9NuRutJyYLnLWfKa
-aDmwlnr7OeRmuqmDYLXMsxpYWuwIq/9rv95pNbBs3YMAq3ajxcByl/V3yHj9NxBYrHqltcC6qj2G
-7y5XKhJoCsVtLbDmtrPBSK+xFFju/i8Tnm/I4jOqaqwE1opt0Y+3Je6g5JC5bTluK4G1opENTjZL
-gTW1td8D7qZ8AweL5TutA9bKZTGvg3gTv0J7hqPd1gFrRfUguWL+8RYC65rdifgMDIUFWKxko1XA
-WrouNleJtlFnVG84JGDNa2CDls9mFbDcF7+SyAFTIivLzMQtsQRYdeO9MQNCpXIATbHWEmC5x7ey
-FMinbbQEWHVKYuFiuaIEwGItORYAa60tRpqqakBcoZr6HvzZB2tFTgdLjWonuoccLPe8GxPs3lYq
-SndW8LJYN945pGDVrc2KYa7aoCDOUJkY7vDGqe4hBcu9IquNpUydkyJGC5xtsNxLshLu3aIZ6MwK
-Pfgm29SN7qDG/9ydVm28JuTFivHj26JfEB0l2B1UBu5TOmpzZteEfMPE9J6Ne6or5MXS8eMPs5Sq
-Y5ntGudZPJ0lK4LLdUtslw4gaVKtKB1ZEUd/eOvCS01pl6ZZ+ebC3GVN7TFSn94CGidTltxd3I7D
-62688mydTsjnL/O2d7LUq+PAA5eetdaZdKG5dOMDLe0DyvHSPZ0sZmV5y8IrpkoNC9VbGqz2anSB
-NLSvoE021fBSg6K0WROs1uoCY6xoWUOHbCgJVirUVlUgLBWG7M2SquEoC8ZYLWXGuPYSpT4t8a/U
-WVCUXuHQqkpV+FOrobHdJ5tnWIPVaSGwqvjseaVaQjXchS3pswxYbdwH1sugKgNUEXqvcIjlAap7
-JW1VRqjEOmB5MFwvl1hliGiqujXAokExHtkgmQNWpTXA6lQKlGbZHpmijsCYdwsEe9WyPTJGLYrS
-aAmwOhKcJSE1PNRIjz2xAlhV5YpXNkfmqIrK21oALF/ch5hIDTuBqN1ghS6hjLAySD5RxmjoD6Q2
-8LhXqUyQl2J3K4BVEO/hOFLDTtV8YvHQg9WtqOWyNTJIojje0IPV2W8xNanhpLYy/pSmoQfLfFyU
-VMZ4whargFUrmyPTPKEFwGqjMl1SGdQnrLYGWL7WVpltyByVG7NAs+RPIZVa/yNuo0iwpFKpShG6
-JwCWP4FPC27TM9AD6Ym+m182UUp0tn9HNFhGTftIsDyqkQZXVPEknu3zdVWbsbnvIR+7vUjVFu4j
-Jj7MUkm054YiNX/ZUbFnma6WrO6740Gb+IpD+MkzdoiVG0rU/DtPibWAn3B6xCNRFmwIUbniNfy9
-HTOWnYqGz1Pmxo9NdzhmPE1LO8t0rWQ1geXfH/JDB/puqiGyLxum68Ze2BB2beGJnqSP2jRYfcEC
-83yA+mpd04FmOQAUHo3Y8KAOqmID/Q90zhqQVNY7Exy4tUYb36/hnhpcH/ndvVOAPyH1VTtk4/tf
-o1XT+WcVcupwUaPFkR4Emw3hAA7WBgf+MPjL5L7Ul6tDYGy8gFoL4BvM/4wDf13gv/5+vuj4Qdg+
-KhhCDhabezF2K7afTbRfMmpWppkDVfoBaw7kPO9jPXtzYHLEht+FcSeYbw5chsu7wNbWimIvQu4R
-5ltM53PcBt/zs72a43fh++2fAhysro/Aom6210bv/xhmdLL9NvWHjH0JinFRgx9KsMLAegbgEew8
-Hz4f7H3syU4wwPp/GjzP2FOQd5RdADf72c+0vLcYmwn3+tkL2qi3Qvdp5VoOE/zsTQ2ew720vD/j
-Vnl7mG8B3JZkBz+kMFB8sF7TdHGBYFP/lEKzqsDQ9NunP0BZC8jhkF0mVl4BtPLvNvt77ECFfhoN
-cRasY69WVf2ZsWMPVG1lbL4KYzlYf9X0dxgxtYx15ehv0Lm+3clYNizjX75MghUG1vlGY6O9vxr/
-q68KFs6cDo5csfH2+dl+P+tVoY3RP8b//tNGdCFev2QfPFBFrbihqlLEXm/qo470sGa+F277CrsL
-rsPVv9Wy30s21RAYABUfrP+A85iJzE18ZUSS/H9hHP49Bx7Y+WATIyyqxb7/bYTk7+fA91jvR8je
-fRZGY3ygaM+3cbBahUNshQlo3EazXdVbT9DrL0EpWjObtFjhYP0JHCeE2/sOjMKlSgiOCFFK9wVf
-4m/+Tw3eRouFru9Nsli/EJgsh2sZ+wrkveV/hlsoxmF7OriXDfagg/olo0U0XkmoUVEcLDZYjuoq
-VLWDwPo4PBIgaAKdQ8SQvJOj4BbGPrBxb134FvsYt1hdWfC4scHPwP4Gt3dPvyhsXpvfQOqvoNP5
-vgpj0XgVLnAAOOgsj+fAwqrpUCxjLHBU8YYAAus7kG108Dg2vC6xqbfDOUN6sk+xF2z6sgd53PSE
-2HUVNWDXGDj3Q53bPGGZToXu9Q4bA1TGvZeM18DVGlYhry9YATWQBdpqrBc+L0IY2tuPoMO0QfHu
-XWSW/gPGYn/uZQ0M/l6wwSLGY8J8HS41D4CDhTHYN/hFo7EDALk7WpaDg8h7ir46SoQ68sAKCFur
-IkiOg8CKzB6FgLUe4EcijgcYi+A8KN6rogb0v4DRP2QbUdocvqHQUxpZL7sgKimwOsLnhvYFS21t
-QbUqkWCN7vNRJ6eA/izFbIep8uwhjNNP5kBh1e06YGBF9vUZJI5fEyfRpuW+EwYWGjO0TWXAwdJ/
-YnrB+0Hb0XKfpv9UgmU0BJbt7hUAAAvPSURBVAfr9gTB6mH3YVfQTxfs2N0tMyHnRBhYgrdfi23f
-tI06Yu613gGz/ATW7mTBosA9dJRK/BjrioAr/HEg2gro2BSw/zokjZAFm9mhMQ5wzLoCAys8WrwK
-ik+ZfUhhukLAIuwge7M2Dl2h6udeMZcds+m/YRTbTZZghcZYQVf4N97TiwFWD4ZScIuf+of2oxyj
-O4KukDfgnzQ0WGKn++BfTK7uEnsZrrCLwq2BclUWMayuv+D9XAqH9jGMnh6J5KoIcvaF5dyA0qgH
-WtrYKP13wrpeb/wax5AhnvEKBYsda209cQBmoVfkYB1AsA6I9w6AJsEKBetvGFmh/3qeneERVEyL
-tRx0Ho+vMs2UzQze74LPi3hdJKy4J/ylsTty9XjIqn/mDDh471SVaeGPkowP1n4bueHP2m/ZzoPw
-sPhqCow10J9TcgsPmvTfdXqf9NNSDv7FaP0b5hUxEwp1yPf7Q8HyNnq4Kfsa682B33CjeC6F9PQ9
-f8SQXoIVmm6YQhmdX6jFe3X4AYsJ1nrIEx2+JwR+y9FMYdeKTNwF8HsRwY4FnduDDwJ9P1z5U9OI
-kVn7Hy17gLeC2qgGY/cAwMIj1Vef6L0PIz5+U6eq2hsSIy6sRlVRj1HfwY4tQPd1yIbo49LX0Bzl
-QC69X+2hcEr/DfYMbw6zWN+F/CNsly33HT++n7+H4U/2DdaVQ51LXFwowQoD600NFu5hL4MOY6nR
-G6qrooCFG43lv3n7u7nwtVNsu07x1AIoPYHNRR7wXR1uRotAeR/yliLqfTPX2KsNwy7HDnZwSqBT
-n3DCXVGmRVSC7wcsdp8GqupA+5m/2R+ax3rfZnRZcPNetK+qCqOPUOxNS6V+sj+GqsgRLqLrwnCG
-Aiw/kqerDpVHaYtpEQr93EbS92knJFjht3RetuMPw2/E3HkkIr8QeLnA/M3bKIClrSkWOa7TIv+h
-MZo/RVc/XeL/CdmnTUcYuLuznpobxp0a0KFWRnvQUVbfJJcBliJuQr/+WJGiPdAyBfLeCM1jeRVT
-9GpXmZK/mTqxPTunKzOa6Jo6x3y/qmuMMprWzFFs7xn5DhFi3We33WkEorumK8U7uP099mQRLp4a
-6VyxacGGEMmhY9vLsm0Ln7/LQb6wPHzKXIV4+RHzN8de+sFVevaM53lO9dgG3XYnub/1ikJ5nKcU
-Bd3ig+ZHBPYib7R3fnb+5u6B3IRudSjRxgAnPGxm552Jf5c/ua3kWJlE9PpMS111vHJslEc8yIF+
-UoNQgwLoBqOVYpRgSSWtRipIDC1R35NgSSWn7lpR5zpG5VgJllQyaq0UPbOYTw+RYEkNWG314sE0
-1XHm7UmwpAYkX3MlUkUpBk/c8ukSLKmE1d5YaT7ur7q/h0hKsKT6V2erp7qiIJATr27t/0m+Eiyp
-aGrxNjd7GmurqyrLSxziOX9Clc2JPUdZgiUVTaBECFeU17Yk/nBuCZZUNBWEMFVQUe1paRvgY0kl
-WFJRXSEfFt3W3pHsY24lWFJpkQRLSoIlJcGSkmBJSUmwpCRYUhIsKak0g9Vab0zwqq3nQ057vQ1b
-m96OuuvL9XySoZ+1NG7b7RcTO7z1TebErdcbt/WtAHAwuPJg49am4LQA39Z62RgRqq8X2UmP0SYH
-Guu3RS+q8O5WsQW2RQNuwtuCWiV2U9TWG2o3WlDs5e/11jeeSAdYEfMKt9tpTqFaGuW7juXwSYb+
-Y9NVAIe2B49rfx5ubeNzvHuX22i/8FqiYmXhW+Yi2AKVMReb8+6lAnKAGEgnSs3sn0KzCtXRf4iy
-5QLRav69OpWDKj7Rw96fSa0yms95vs/GV4btEVIq0r+3iO91BFvwNWpB5fG0g/WyBouamh+zw8V9
-djw5EzhYvRdA/jbPdBj9Hk1MLW3aYHM820OgFDY9aaPqWSFaD7lbPTMh30+Tox2rmxeICfWMV0KU
-YMUF630dxm1tbiwC+9tnIjdcr4lWw20ubmoEGOdH1OybPUU0PxV/dftWXDw3bHaduAuoQd4+KpqF
-exXBuNO0iC2oOX6fbrCuAF71+GUtL6KSKNuZBwKs12xU1eGkDb7HvstrxPyWivy9puHJsf+dsSh0
-n+M2eBZJ/Bh87wz7GE2O7rIZ5R0O2SRY/YD1HbATGb1TqDJfmF6badYg/Y5qP2HU8RtFk+vf1ahg
-5Bh4iTO3L5qlQ+P0Pzaaa/+uLW8PewJoavEGXmQvrWBlGzVmmprbOOWBQpFesD+icrA6W71i82qE
-ZR1dNlRR9Me8tB93f3OU0afRrimj/X8FlVzji8TUOXyDLF40mfk+kvusBCs+WBVGISNvM9XkDJ0J
-rUDpjaLV2luahZtrYzq0MlGN9C/aqKN+ciE/YF15Ctqt9/lf0lNU25YdNveiGqQPMdbzF9uod9IM
-1q2Qu/lEyBkEAuzdq98KK0iKJucniOE6sdkP0dT98LEi28I96PePU6mAn4H+UmjZUVxRfITt0kQN
-m8Xw+AEJVhSwOoNg/QrgzmAEHlq7YeHz4aUcXgC0WAvgslOiEsh/CiKpGhYV9HuWikKKNv1wlB60
-Yi9Q1eSP8zJGH+bk/SENYBlDvHipyIPZ6KJmrDNOyNPcGuamg2D1ziS/fgUPqdArbkbzS1Xewf4c
-vy7053gditc0HlL9GHLxstgAdkXTnhMBVilrk2BFActsCsJmOjaFtszoSHubPaFbhoJ1vIjs0MkF
-oCowDsF5DLJp9SpeknEBZG/XzKJF60OK6Z2cQnvpyVf0GxhY7OAC6rw5tOei7BoEqxej8F9TKObY
-wU4uB/SK2aA/z3z3UUjPus7BjyhGJ9h7Dsw4wfbmIEPYl8TvUeFOvx+tXf5pCVa/YPVu4D05ZXWU
-EhchYCFXo45QTw93duAl7g+UiqSm/ruOH2E4wt4xwcJ9yNWofURUiwBrd7rTDeiBPbdnO0B9Lg5Y
-vpmgPm3UKcSzKcLTGWUaLyqrvV8Dx0uUJTmETClU8IhgW3SKvf4R3OzkmFw8pXYJVnxXSL+z97E8
-ozRRTLAO6ZCNsfoHOmz2U52xl9BiKUGLRUXW7EdEzvG3WraZDTpWJKp+ptVihYPFj2Hv+dH6CSZY
-vinC5VFfcboyY88V8N/oFY2C7xR1vaoB/Jp/0LFVDu2BV7QJ9PiAf/A4fhzaKsgm4wVKhWQpTh5L
-6PBiyDsRGyzkitfvNAKr5RhYhcRYIq+jG2DdBXeYNOZBDjdeIsb6IMk674mDdWDVFNE92AW2mGCh
-FdVCe7JdOXazV9ibRVVuu8ag+R0d7Ge8CnMpjqezfR00AstQpWQpNliPlf1cOLB4VZOP6/QgGhao
-wb0Kctifgr1CwxUaddXGmHYJvee4I0aamnqFf7LZ09wrxL7encYXxrZYiyHXeKbPX8vz3qFIazLF
-6WOPUoVu9Q1ebnKHqPf+lRL6Owc7kGixqMb4rTCZdXhI9eBo9kqWYoM1nUprM+pOx7FYRfBR4Sd/
-oelHeMD/eQLo14E8lgjeeWb9bwG7NF2Un2QskMc6L915rPsBCmsbn5wOKsVIEU8F52Cd2asZ4X41
-FRDN3/aY3f4Sz7xrW58cBbPQQFEW9Ble1f5F0Fc3zOePnVhMi7drjh8ZaWQZvPcD1ssOyFm3rWG5
-g9d5jKjoJ8A6Qw9fEBX9eqfg1g0XYBx/hjLv6xpE5v1n1CP8iqhua1RTZmeeMffyknOZsW2VI/2Z
-994N2fxeofZ8RB4raLG+ZDoyDKr2Z9P9Px5v9S7HqEmddYr6HsXcNo0+KlbaZ5GB66EbWJD9tPlh
-Eqz+YqxdOvUKHaJXGL0G6cxgDdJj/F5hDm+39XRfgyruoyO8mSfvP3oq8CgU8iDB24YH6bah8jRL
-PVhtnkax0OjhSavelmZPc1vYKlONnhb+1xC96PV6dpsjFl5vbqL9Xvd46Kazr8lDHY4DYiXpIG4b
-NOroECVJkRe5R/QKvUabHPB6ml45FbbKkPHSbApPB/+pPa8YHu5gcxMfvOD1eGj31zweDNNagi1t
-iM9GbfE0p2V0g5QUk2BJSbCkJFhSUoPW/wfr5tj8wgE+HwAAAABJRU5ErkJggg==
diff --git a/Documentation/DocBook/media/selection.png.b64 b/Documentation/DocBook/media/selection.png.b64
deleted file mode 100644
index 416186558cb2..000000000000
--- a/Documentation/DocBook/media/selection.png.b64
+++ /dev/null
@@ -1,206 +0,0 @@
-iVBORw0KGgoAAAANSUhEUgAABIsAAAHpCAYAAAACi7yYAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A
-/wD/oL2nkwAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAAd0SU1FB9sLCBAiCLMGMtAAACAASURBVHja
-7d3rkds4FgZQaMohTBY7ObRCV+fgyWJy4P6wJavVIgmSAIjHOVWu3bElPkBSAj5dgpdpmqYAAAAA
-ACGEvzQBAAAAAHfCIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMDDD00A
-21wul9XXTNN0aHnP749Z39o2rK0jRzssLX/pvVve9+61S69Jdey2bn/sMTx6TAAA/cIW+oVb+2tb
-3p+izwioLIJsHYe9X+a979vae89ut6Pb1+txBwD0C3vZN0ERrFNZBAct/ZJxuVx2Vdg8v+/oLyEx
-69j7xbq2/1u2e0u75Th2Mevf8ytVzDkDAOgXjtYv3LquVP0nQRHEUVkEBTsJve/r0hfu2hdz7e0W
-27HQ4QAA9Avr7BcJiiCesAhO+GKK/YIt8SV+RscoNmippUPl1jIAQL/w3PUc7Y8JimAbYRGc9KVY
-Yu6b3OsYNUTRuQAA9AvL9AtT9LsERbCdOYsAX74ZOiVbO1M6LQCAfmH7/TzohcoiqOhLK+eXV4p1
-xP4y1krF0X1bn7dXBwIA0C+ss19oagAoR1gEJ4j9osv5iPq965imKUk59eidwNc/AIB+oX7h/HpK
-tzeMzm1oQJIv7Ra/eO/7sOWxtgAAtN0v1N+DdcIiyPQFlPP1JbZpTyehl19q1joQOhgAgH7hOf3C
-Pct9tz36c7DMbWhQwPMXUYkOQ6517P3Sj/216axJEdfWoyMBAOgXpukX5uqv7Xm/W9JgnsoiSGxr
-4FHiiyvlOu7v21pu/PqLzuuvOTHtlmIZW/bz+f1r6177ewBAv1C/8FwqjCCesAgSdwK2dAh63e+5
-fX8XuBxtt1SdkZhy6djt37vNOioAoF84Sr8wV39tzzIERvCd29Agg7knQ8T+unTk15mc64j5El17
-KsbRW75inrqR6glj79rELWsAgH5hmn7hmcckpt8HI7tMRjYAAAAA/KayCAAAAIAHYREAAAAAD8Ii
-AAAAAB6ERQAAAAA8CIsAAAAAeBAWAQAAAPAgLAIAAADgQVgEAAAAwIOwCAAAAIAHYREAAAAADz80
-AQAAqVwuF40AABWbpmn1NbvDIh0BAKDGzg3n0T8EgD7sCot0BAAAmDNNUwj6iwBQlS3fzIduQ7vd
-blobAMjuer1qhKZ6o4IiAGiZOYsAAMji0w+LAHC6jx0/unkaGgAAAAAPwiIAAAAAHoRFAAAAADwI
-iwAAAAB4EBYBAAAA8OBpaAAAFDf3ZJa5J6htef3za5eeyDb3urWnxsQuM/V7jmxX7Dr3HIMUbfj6
-+qXjurZ977Zja1vuaVOAnqgsAgCgqKWB+rt/2/r6s7Z/z3aesf0x+1fjdgFQjsoiALpyfRng3J5+
-Fb7/2+3NL8Xv/m1pWa/veX7t/XXXN4OtuWXs+fe59c/t45H2erd/Mdu/9XX0b63q5zWkWHr9/d8+
-rtfFapOY9byz9L7X5e7ZzqVKmT2VP3ts2cc966+1MmfuGKkkAvhFZREA3XgON94FNnMhzlJQNLes
-1/ffX/f62ue/fw1d3r3m9d/nlhu7/rX22rv8LW20d/voT8ztYbEBzNJrS4YMubbzzNCidLs+BzX3
-datsAjiXsAiALrwLfPYGE1uXtaVK5l2YNLes2OXurdI5svwtbaSKiFdbg5Cl18f821y1UupAZu92
-1njblwobgLG5DQ0AZqSofjkSnOSuvsmxf2fsB5SUMtT5vN2+LC82xNoziXaJNthyO11MBdHS7YUA
-5CUsAmAo91u97rdGLc1jdKQi5t08QiH8uSVrTcwcSkekWv7avuTeD1hzD2TuwcOWqqIS8wa9C01G
-nD/neV9fQzQAyhMWAUAma5NVA23KEeLMhUZHJ5g+e/9jXyscAqiLOYsA6MK7+XLW5gWK/fdnsYHP
-2uvWJtveu969ti5/bxsJzNgTDOx5JP2z1yAmNsC4T7j8+ifXdj6vs7VjlGsdQiSAc6gsAqAbz7eY
-Pf9dqmVtWd7cbWivE0LPbe/rv80tL1Vb7Vl+TBvl3g/a8nx70dIj7e9/v/b6mKer1bBfc9tZ65w8
-pdt1bh1zQdFaGwNw3GWapmnzmy6XQx1wAIAt7gHTjm4LJTuWv/uI084QYC482Pv6LfMSvXtc/Nag
-pNR+xb7+yLYeXX9MG669ZunYpN7mEeeJAsZx/4y7/P7vmP6U29AAAChq6yPm9z6S3n7t34/c648J
-Z97N49TKuQDQOpVFAED1VBY10rGMrCwCAMpRWQQAAADAIcIiAAAAAB48DQ0AADqSciJsAMYkLAIA
-gI4IgwA4SlgEAADAZh9/X9/+/ed/t8Ovf37t3PKWXje3rq3LTP2eI9sVs961969t59r2LbX16zJi
-t+Xzv1vyduE4YVHpD9SZsuDnX4COlA7HLD/Ferase2lZW7Zh6/a+vn6pDda27912rK0vVbsCAEB1
-45qFwf3H39dNIcm715fY/rWQKsV7Wj5me93Dn6VlxgZKnEdYVPLiXAgTPq7X6BBh7rWpln/kPWv7
-LigBAIDGxzUrVT+vocTS6+//thYs7A1plt73utw927kUeixt3xnhWEybzO13qe0VHtVDWFTq4nwK
-cmKDni2B0NLy7/82F/4srWdPYLRneVvWUWvgNNfuAjIAALoZ10TcHhYbwNz/LiYwStpvf3PbU47t
-zL0v727/WqvqijlmEEIIf2mCAh+oK0HR0UBhbflbbuVKsT1ry4vdhhRt/nm7PdZdYr0AADCCreHC
-0utj/m0u3EkdcuzdzntQ09MxS7Gud23iFrQ2qCwqeXFmrjBZWv7n7XZ6WFLDNgAAAGNLGeq8Vilt
-ndz53fKO7sMZc0DlPjaCpfKERTVfKBsmqy617hr2de21qeduAgAAzvM6YfKWypQS8wa9q6IpVT3z
-vPyYp4pBLGERu55i1sSXytO2q2oCAAAe44MMIc5caDQ3B1KSsVzF4dC7p6KthWgqiOohLKr5A2zj
-RNW511/LurY8NQ4AAEhv661OMY9RXxwDPAUP9/+OGjtsDB+ObufzOnMFOTHLnZvoWhhDLBNcl/xA
-PRherIUka7dfLS333Z/a9j/VOoRIAACwc0wy86SzL/3tmadvLU12/Pra2vZryz6V3OZ3f44eMwhB
-ZVGZi/jpFqi5qqAj1UJry495Gltupbdhbh1zQdFauwEAAL/72i+PkU/x+hoeRb93O/fMi1R6Iuet
-xyz1emNDQRNc10NYVOoieQl0jnoNN2KWXyoo2jMH0lnbfKTdzm5nAAA4bXyzMJnyXHVLC0FA7fsV
-cxveu7mCWjoG1EFYVPKDZ2GS5diAYW0ZtQYYJZ/gtrSuexs9h201txsAAFQ7vtkYMGx5/dHXHgk/
-atmvI+9PNYF0ioqvGqrG2O4yTdO0+U2XSwghhJuBNABQwPV3qL+j20LJjuXvPuL9KPnRBWCbtVvE
-hCrsOq9+96Muv/87pj+lsggAAKDFAeBLsCBIaJ9jSC2ERQAAAB0QHgGpCIuI++JZmZRbmTkAAFTW
-h98QHn1cPzQYFPR5+6x6+4RFRJ7IN40AAAA19dGfwp+Yx6HHPr4cQFgEAADQuNfwZy08inkEOzAu
-YREAAECjYiqKdvl50bg04Ujg+Xr7Ze5bw1q63VNYlPzgXzUCAP13zNyeDJB/bJErCAKKB0WtERYB
-AACcNWA9IRBy6xnDX3eColXCoowUbgLQk0kTAMQPRguFQItPOHuzDXuCoss/jieV9Ul+Hrg2TwqK
-WnvioLAIAABgy6CvgiBoz/apKGL4a1dQFE1YBAAA8DywK3hrWOoAJ1U1EXR3XQuKNhEWAQAAYwwW
-Gw6B9u6foAgERXsIiwAAgLYHgoUnia4tgBESwcL1UUlQ9Hn7bCo8EhYBAAB1DvJOenR860GLoAh+
-f4ZUFBS1RlgEAACUH8R5ZLx9hJyfMYKiQ4RFAABAuoGSEMj+w9mfQ4Kiw4RFAADA+iBICAS08Fkl
-KEpCWAQAACMPrMwLBPTyeSYoSkZYBAAAPQ6ahEDASJ95gqKkhEUAANDaoMgtYQB/PhMFRckJiwAA
-oJYBjxAIYNvnpqAoC2ERAADkHlQIgQDyf+4JipIRFgEAwN4Bg3mBAKogKEpLWAQAAK+DASEQQDME
-RekJiwAAGIpbwgD6ISjKQ1gEAEAXhEAAZPl+GSwoCkFYBABA7Z10IRAAZ30HDRgUhSAsAgDgrA64
-eYEAqPl7atCgKARhEQAAR/17CSGEMP186WSHa9HNEAIB70zTNMy+Xi4XBzyRkYOiEIRFAAAs+ff8
-gYcQCICSRg+KQhAWAQCMSQgE0J25KioVR/EERb8IiwAAenJGCPS/6ctgZHp0sG+OB0AFXkMk4dF7
-gqI/hEUAAC04qxLof5O2B6B7gqKvhEUAAGcSAgFQ2HOlkSojQdE7wiIAgFxOvCUMAFgnKHpPWAQA
-sJUQCIBOjFxlJCiaJywCALgTAgHAEARFy4RFAED/zAsEAKvuVUa9VxgJitYJi6DmD+uf7//+8s/6
-a969ds/yU6xn636uLWttu9e2dakdX5cRuy2Xf/K2ETBDCAQAbHBWUPS63toJi6BSS8HD9DM+eJh7
-barlH3nPme2y5h7+LC0zNlACdnaq/r5+v/Zzh0NCIADotsJIUBRPWAQ1fjg/BSKxQc+WQGhp+fd/
-mwtJltaTOzCKbZe5fSoV6giPYKXD9BQCFSMEAoCx+x+Cok2ERVCZtUBk6e9TLP/5dqrY8CfmFqy1
-7Xm+/evdenO3C5CgMyQEAoC+xibT1EV1kaBoO2ERVCp38LG0/CPhT+vt8q4dlsIrARVDdBTffB58
-hGv29X7+d3v8/+v1+ui0AgDEqiUo+rx9NhUeCYug48FcCOfPI7T3faXmQOrtWECJa/eo5xAIAKi8
-v9Dw/EU1BUWtERYByQaXe8OQ5/fVXNUEvVyruQiBAIBaCIqOERZBJ7ZOVJ17/bUParfs1+utaGu3
-oKkgIqczrpfHuf+l43NzMABgpD5IQ/MXCYqOExZBxQPCI6HDWoVOzCPhlwaNJQa8c3MFCWPo9Zov
-zbUEAPRGUJSGsAgqE/M0siOBydryY546VmKw+jpwzt0ukMtZlXOuBQAgeb+m8uoiQVE6wiKo0Gsw
-kmKwOjcvUEuTMadul63rjQ3STHA9SGdJCAQAUA1BUVrCIqjU0m1ksYPFtWWcFWrEPHZ+7rH1Z243
-43BLGADATD+pwuoiQVF6wiKoWMzgce01a4HMGQPZLWFXim3J3Y4G+w11boRAAABdERTlISwCoHlC
-IACAgn2v6dczUmurMBIUpSMsAqDejoh5gQAAiCAoSktYBBQf4BuIIwQCACAVQVF6wiLAgJyk3BIG
-AEApgqI8hEUARBECAQDwpX9Y4ZPRchgtKApBWATgS14IBAAAb40YFIUgLALolnmBAADI3ufsuLpo
-1KAoBGERQHtfyEIgAADIauSgKARhEUBV3BIGAEBzfdjOqotGD4pCEBYBlPkCFQIBAED1BEW/CIsA
-DhACAQCMpbYKmmmaqtmO1quLBEV/CIsA3n3ZmRcIAACGISj6SlgEDEUIBABAT16reWqpNGqJoOg7
-YRHQDbeEAQAAWwiK3hMWAdUTAgEAQGQ/9qnSqHSVUWvzFgmK5gmLgNMIgQAAgDMIipYJi4DkzAsE
-AADnu1f5mMfoK0HROmEREE0IBAAAtOysoOh1vbUTFgEhBLeEAQBAr0pWGNU8b5GgKJ6wCDonBAIA
-AEYnKNpGWASNEgIBAACb+vODzmEkKNpOWASVMS8QAABAGrUERZ+3z6bCI2ERFCIEAgAAanC5XLJW
-F9Uyb1FNQVFrhEWQ+oOxUCgkBAIAAHaPJzIHRmcTFB0jLILaPrSFQAAAALsJio4TFkEhQiAAAKCq
-MUqH1UWCojSERZD6A1coBAAAUJygKJ2/nE4AAABASqUrlgRFaaksghQfhD+1Af1QHQcAQEsERemp
-LAIAAIBB1fCI+yMERXkIiwAAAIDmCYrScRsaJOYWHlrkVkoAgIHHMB08FU1QlJbKIgAAAKBZgqL0
-hEUAAABAkwRFeQiLAAAAAGaMFhSFICwCAAAAeGvEoCgEYREAAADAN6MGRSEIiwAAAGB4l8sl+TJb
-fsLayEFRCCH8cEkAQJkOTo5OGAAAaY0eFIUgLAJgcCV/8VpalyAJAOB8gqJfhEUADKPmUuh32yZA
-AgAoR1D0h7CIrgduBlp9DqqdM4xyHj9vv3MTACAfQdFXwiKAmcH5K4P19o9hT/vlfAQASENQ9J2w
-iO4HjQZUGKyPeXxG2V/nIQCQyuVyGa5PJSh6T1iEgR0kOIcN2H2OOA8BANoiKJonLAIwYG+6vfne
-Ls5BAIBlgqJlf2kCeh/oGVRyxvntvNO22gkAoE6ConUqiwAyDthDUOWRsi1xDgIAHHFWUPS63tqp
-LAIoMGAXdhxrP5yDAABHCYriCYsYYuBnkIQBu/ZCmwIA4xIUbSMsAjhhwI42Ort9tTEAMApB0XbC
-IoYZABoY4Vpoo120jfMQACCVWoKi1ibRFhYBGKhrD+0OANAdQdF+wiKAkwfqBusCCwAA0hIUHSMs
-YqjBoAEp1Pe54LoEACAlQdFxP5xGAOebpilcLpfh9rkVKY6NUAwAID9BURrCIoBKjBQY1Rqc5Gz/
-uWULkQAA0hAUpSMsYriB4YgVHLR1rfR+ftb0eVBDW79ug/AIAGA7QVFawiJgqIH5O7UNznsOjGpo
-69rb9nn7BEcAAOsERekJixhuIN77YJxjg3OD9D4/C1q93gVHAADLBEV5CIsAKhyk9xZonhV09NSG
-giMAgGWConSERQCRg3QD9PaOmXMSAGAMgqJkHc0Qpin85ZQip5oHMgZZ7BmglwwhejlHS+/HSLeY
-lj4nAQBqJChK2nkPIQRhEW0NisAAvbXvmslxse8AgDFcNoKiPIRFGMhCxV9+LZ+jpYMitAMAQA6j
-BUUhCItoZKB4HwAZCGFwPt71v9b+joE2AQDa6sO1ZMSgKARhEUCSwTnaXfsAAPRl1KAoBGERmbSU
-SEvPcY62t72CkPh20lYAANuNHBSFICyikcGOQSKtnaejEhQ5PwEAWjd6UBSCsAjAgFwbD9N22g8A
-YJmg6BdhEcnlmNi6pW0G134egg7tCACQk6DoD2ERBjuAa157AgAMTVD0lbCIpFqu0FFdRM2D8NrP
-z5zbJ9jQrgBAe/25lvoagqLvhEU0O5Ax0IE+OxbU8zkLANA7QdF7wiIAqiXM0MYAALkIiuYJi0im
-xYmtc+4DBt+ue+0IAECdBEXLhEUYlAMAAAxstB/NBUXrhEUAVNepEAQDAJDDWUHR63prJyyiukHj
-1kFi6kGlW9HgXIIiAAD9uRwERfGERQAAAEDXBEXbCIs4rMdKHNVFcM41oqoIAMDYJzVB0XbCIqqy
-d6BogAkAAMCrWoKi1ibRFhYBsImqIgAA/boW+nSCov2ERVTz4VLbQNGtaAAAAG0SFB0jLKIbqhLA
-9QsAQJyefxwXFB0nLIJBP0BpSy1himsCAICaCYrSEBZRxaAx1UBYdQK9XRsAANBKf/Xs8ZigKB1h
-EQCnEvICAHCUoCgtYRG79Dyxdc59Bdc9AABn9ud67NMJitITFtEdVQoAAABjEBTl8cOpBZBOjl9q
-eg5AhbsAAG32UWvs1wmK0lFZxKkfNLk+UFIv1+03AAAA9RIUpaWyCCCRnkNFgSkAgD7cnLOrigRF
-6akswoDRvlMxt2kBAMA8QVEeKovodhB8uVwEPBTjXKvvMwAAQL9Uny6F0YKiEFQWAVT7hSxMAQCA
-c40YFIWgsoiTBsSlBsGpq4umaTKAJ9t1AQAALfVHex8bjRoUhaCyCKDKL+aavngFYgAAjGbkoCgE
-lUUAmwlPjlOhBwDoC+rP1Wr0oCgElUWc8IFY+kMl9fp8OYx9HZQ4/oIUAAA4h6DoF5VFACtKBoSC
-IgAAatdrn1VQ9IewiKID5V4+VEx07bz3pQsAAP0QFH0lLGIIqZ+KRl9qODcERQAAtDK26o2g6Dth
-EVCMwG6cL1wAAGiBoOg9E1xTbHB/9oDYRNfUSFAEAEAr/dbe+q6ConnCIoATv3BrJxQFAKBHgqJl
-bkMDKGz0aiLVVAAA+m5nEhStU1nErB6fguZWNM4+/wQlAABwnrOCotf11k5lEUBmAiIAAPRjzyco
-iqeyiLd6rCrKtT2qi5g7z1QSAQBAHQRF26gsAjhIIAQAgL5tvQRF26ksAjhomqYvfwAAgDrUEhS1
-Nom2yiLeDnxTqTWVvlwuBvUUuYZUHQEAUKve+6qCov2ERQAZCY4AAGihr9pbf1VQdIzb0Fj8sDjC
-wBi+X18q2gAAIC9B0XHCIoYlzOIsQiMAAGrup7bcVxUUpSEsAjjxyxgAAEhDUJSOsIgsA9dWqnZU
-F1HDdSc0AgBAP/UYQVFawiKASr6MAQCA7QRF6QmLACohMAIAoMY+as39VEFRHj+c+qQepLZ2a9fl
-ckm6/9M0ub2t4XPj7C9C5w8AAOwjKEpHWATw5F1QUzpAEhgBAFCbe5+41n6qoCgtt6ExdFVRru12
-O1FfLpfL40+L1yUAAPRMUJSesAhgg5LBkcAIAIDa1NZHFRTlISwC2KlEaCQwAgCAc40WFIUgLBqe
-W9Dybb9B/jgERgAAjDaOHKWPOmJQFIKwCCCJ0nMaAQAAeY0aFIUgLCLhQBnIdy2oLgIAoDY991FH
-DopCEBa5sMk60NfGzqPWz6cc++K6AACgZqMHRSEIiwCyUG0HAMAIevshUFD0i7DIBW1QnHl/VFHg
-fAIAgPoJiv744XQAyONyuQh3AIDmTdOkavqlj1fzsXKO7CMo+kplEUBjnQkBFAAApCMo+k5YNCC3
-oJXfL4N7AACgxDjm+U+r48ySBEXvCYsACnxp+zIGAIC6CIrmCYsGo6rovP0zuAfXAwD47qb0mKZk
-lVFL54mgaJkJrvGFAax2MlzvAAD0QlC0TmURQAGeIAIAwNn90RJVRrX/yHhWUPS63toJiwaiMsAx
-wPkEAACjEhTFExYBcAphFwDAOXJXGNXYzxMUbSMsAgAAALolKNpOWDQIv+A7Fpyv5XmLzLkEAOjH
-6p+2eL7UEhS1Nom2sAgAAADojqBoP2HRAPwC4JjgXLL9AAC8U+IJaWcQFB0jLAIAAAC6ISg6TlgE
-QBTzFgEA6OttcUYVuaAoDWFR59zi4diAawEAgBEIitIRFgEAABDFjzx9a7m6SFCUlrAIgFM7EAAA
-cISgKD1hUcek/o4RuBYAANiitR8HBUV5CIsAAACA5gmK0hEWdcqv9I4V5JLr1ybXAgDov+Kc2UtQ
-lJawCAAAAGiWoCi9H04rYpjU9iu/puAz4ZLlOpimyecNAECnfb0cBEV5qCzqkCDDMcNxBgAA0hgt
-KApBWEQEv/IDJQnVAACMA2sxYlAUgrDIIItqPjgdO1wHrgcAMO6AeowaFIUgLAJoml98AAAgvZGD
-ohCERRiIahuK6PXXN9VFAAD01rcbPSgKQVjk4sMxBNeENgYAIIQgKLoTFjFL5Qzgs6JvgiIAfI/A
-H4KiP4RFYJCMjpT2064AAEMTFH0lLNLpx7GkUTWFlbm3xXWhPQEAchEUfScsovpBKBiU+9wYrS21
-IwBAGYKi94RFOv5UOEB2TF2baNMcbaf9AICzxzo1ERTNExYB+OJuarsEHtoMAOAoQdEyYRHNDELB
-4NxniPbVVgD4nsH5cpSgaJ2wyMWGY4tjp507bR9tBADw1VlB0et6aycsAkg8QM+theq/UtsoENEm
-AACxBEXxhEU0NwgFA3SfJ+/aH+0AADBHULSNsMigAMeYho5Ta4Fu6cBo1GtGWAkAME9QtJ2wiGYH
-oWCA7rNl7rg4BwEACKGeoKi1SbSFRQ0PEHCsOW9wfsZxEehuP072DwD0Vxm3Dyoo2u+HUx+g/g5Q
-60HR5XI5pR3v6+whaNMRBwCIJyg6RlhENwMpMCCv/3PmrPZ9Xm9rn3fOSQCAbQRFxwmLDGZpYEA8
-TZPKiMHPKddHnvOwxrZ1nQAA7CcoSkNYBFCxHqv+agiM7l6344z2Fg4B0INeftyk7XNFUJSOsAgf
-6uDaPGXfagxJ5rYpxbEQCgEA5CMoSktY1BiDjXEHwn6tGe8ccp347AUAYJ2gKL2/nFYGpIDr8sx9
-9TkEAMBegqI8hEUN8cu2Ab9zwHljv9H2AADvCYrSERYBGLTbf20OANA0QVFa5iwySABci1W1hQo6
-5xwAwBaCovRUFjXC4MmAzLngHBmpTbSLcw4AIIagKA+VRQAG7FW3kYDUOQcAcKbRgqIQVBY1IcdA
-yaDBOcF5A3bXn88r5xwAQBtGDIpCUFkERQZqwh0M1tO0n2vJOQcAUMqoQVEIwiIAA/YG21No5JwD
-AMhp5KAoBLehVc8taAZvJc8N0h1vt/6UaWO0CQB9j13gDKMHRSGoLAJINlDn3HYfsYPqvAMASEtQ
-9IuwyMACcB11dVxGCI2cgwAA6QmK/hAWVUwZZ3+Du9THdJomg0aDcRaOXS+fo85HAIC8BEVfCYsM
-DnBMnX8Mc821FB65BgFokR8zaZGg6DthEaT+gvypDaBW7zqvNQRIOtUAAOcQFL0nLAJgaEtBTcog
-SSAEAFAXQdE8YREAzBDwAAD0SVC0TFgEKQaU//z637lb0O7/DgAAwLkEReuERVBAzDxGAiUAAIC8
-zgqKXtdbO2ERVGItUBImAQDQRL/WE9G6O569EBTFExZBQnOBToonpKlOAgAA2EdQtI2wCAqICXEE
-SgAAAOkJirYTFkEl1kKcFGFS7HIESgAAHOpzuhWNStQSFH3ePpsKj4RF0IhS1UkxyxEmAQAAtasp
-KGqNsAg64nY3AACg6jFLoYozQdExwiIY7cPZ7W4AAEDHBEXHCYuAL2q63S12ewAAgPSmaWpumwVF
-aQiLgM3MnwQAANRGUJSOsAjIwvxJAABj80Q0ShIUpSUsAk5j/iQA8i3Z/QAADThJREFUAOAoQVF6
-wiKgWm53AwAAlgiK8hAWAU1zuxsAABCCoCglYRHQPYESAAD0TVCUlrAIIJg/CQAAWiUoSk9YBBDB
-/EkAADv6NZ6IxnM/NsO5ICjKQ1gEkOrLz+1uAADQndGCohCERQBFCZQAAGjBNE0aIYwZFIUgLAKo
-jvmTAADgfKMGRSEIiwCaY/4kAKAl5i1q85iNbuSgKARhEUCX3O4GAAD7jB4UhSAsAhiW290AACjW
-92ykukxQ9IuwCID3X+gV3e4Wuz0AALCXoOgPYREAu5k/CQCgL6POVyQo+kpYBEBW5k8CAKBmgqLv
-hEUAnM78SQDQN09Ea+c4jUZQ9J6wCIDqmT8JAIDUBEXzhEUAdMH8SQAAB/o3g1UVCYqWCYsAGIb5
-kwAAEBStExYBwBPzJwEAI1FR9HnKemsnLAKADdzuBgDQJkFRPGERACTmdjcAePO95YloVR6TIn2j
-Co67oGgbYREAnECgBABQhqBoO2ERAFTK/EkAQA4jzVNUS1D0eftsKjwSFgFAo86cP+kjXL92gP67
-OSAAQFVqCopaIywCgI6VCpQ+/r6uvkagBIB5i85t+1P6Iicdb0HRMcIiABhcqdvdBEoAQAmCouOE
-RQDAonuYNH3p/Ny+do4igqCoTtbMch6B1b+XEP43OSgAEOHsuYnOqCoSFKUhLAIADoupCEoVKIV/
-VzqewiQAGJKgKB1hEQBQRLFA6d+IXzEFSgB0aKSnnH3rQwiKkhIWAQDVmAuUrtfrr05wovmTBEoA
-0A9BUXrCIgCgHTEBzr+J5kcQKAGEEH7NO5OyYqX1J6KNXL2z9bwpQVCUh7AIAOhLTYGSMAkAihEU
-pSMsAgDGUypQUp0EwIDOqBwTFKUlLAIAeGctxHG7GwBUQVCUnrAIAGAPt7sBwDelq4oERXkIiwAA
-cnG7G9BRAGCSa2LOkx6NFhSFICwCADiXQAkAqjViUBSCsAgAoH7mTwKgcj1WFY0aFIUgLAIAaF8l
-8ydNP0O4/ONwANC+kYOiEIRFAABjKBQoTT+fOtrhGvWez/9ujg80wLxFLJ0bPRk9KApBWAQAwF2p
-291eO+V/X1dfI1ACoARB0S/CIgAA4qyESZfL5UtlUdLOu0AJoEo9VRUJiv4QFgEAkG7Q8E8I06OT
-fYvrnEcEQSmWI0wCYPY7RFD0hbAIAIBTxYQ4KQIl1UkA6ago6puwCACA6q2FOKWqk2K2BYB2CIre
-ExYBANC8UtVJscsRKNErT0Tjfh70QFA0T1gEAMAQagqUhEkA5xIULRMWAQDAfbBg/iSAWSqKxiEs
-AgCADcyfBNCus4Ki1/XWTlgEAAAJud0NtjFvUf1UFKVdbwuERQAAUJjb3QDKEhRtIywCAIAKCZSo
-VeonolH3se6BoGg7YREAADTK/EkAK59flQRFn7fPpsIjYREAAHTK/EnAXj1UFdUUFLVGWAQAAANz
-uxvQI0HRMcIiAABgkUCJV6nnLfJEtHqOaw8ERccJiwAAgMPMnwTUQFCUhrAIAADIzvxJUKeeKroE
-RekIiwAAgCq43S3xAPZpPwVk9E5QlJawCAAAaEYNt7u1GLx8/H0VGNHtvFCCovSERQAAQDdKVCe1
-WpkkMKJHgqI8hEUAAMBQSlQn1TBv0ud/t2/bkTIw8kS0Oo3choKidIRFAAAAzwO/CsKkmO2I3Zec
-gRFUc90KipISFgEAAGwZlJ44b9KekCdnYNRCFYtqpQGuSUFRcsIiAACAlAPXjPMm7b29TYUR3V5v
-gqIshEUAAAClB7iZAqWt74kJjKafjhdjGy0oCkFYBAAAUKV3IU6qW9y+L3PS4PDu+hgwKApBWAQA
-ANCMUvMlAeMGRSEIiwAAALqR6va2PXMZnTWwtl7r7Wm9tRAWAQAADCBn1ZEgwXqtty/Coozc9QsA
-AJwt5glqHwb01mu9p663NsIiAACAzsQERAb01mu9day3RsIiAACATpQKiUYc0Fuv9Y5EWJTY5+2m
-EQAAgHrGKAkDolEH9NZrvaMRFgEAAHQoR0g04oDeeq13RMIiAACATuQKiEYd0Fuv9Y7qL00AAACA
-Ab31Wi93wiIAAAAM6K3XenkQFgEAAGBAb73WW3C9tRMWAQAAYEBvvdZbaL0tEBYBAABgQG+91ltg
-va0QFgEAAGBAb73Wm3m9LREWAQAAMEuQYL3W2856UxEWAQAA8JYBvfVabzvrTekyTdO0+U2XSwgh
-hNvt5tMTAMjuer2GEELY0W2hZMfydx9xenSO9RWhFS3fLgMtKhkgffzuR11+/3dMf0plEQAAAAAP
-wiIAAAAAHn5oAgAAgLG1OKcKkI/KIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwYIJrAAAAivq4
-frz9+7mJtre8/vm1SxN3z71ubl1bl5n6PUe2K3adW4/DWvsfPb5737PlmJrc/T2VRQAAABSzNHB/
-929bX3/W9u/ZzjO2/+gxOrrcrcve856alt8qlUUAAAAUsVb18zpoX3r9/d8+rh+L1Sdbq19itu91
-uXu28/73qapz9tiyjyWWneo9Z+xvb1QWAQAAkF3M7WGxAczSa3Pac9vbnu08M7RYu+3r8/b5eM3W
-dj/aFjmO8xnnUQuERQAAABSzNQhZen3Mv81VK6UOZPZu52i3Qe1p99zhmYqi79yGBgAAABFShjqf
-t88vy4sNsfZMon10H9fmYzozbMndHqMSFgEAANCleyBzDzS2VBWVmDfoXfVTrsqnFPv4/HevYRd9
-ERYBAABApBwhzlxodHRC59T7WGM4pIIoD2ERAAAAxWy9bWntaWdrnquL7v8dY2sIcXQ7n9d55oTd
-e7Z9yzHds2+520OF1HcmuAYAACC7mKdOzT1ZbG0enVqeHrZlO1sLKO5PQXv9s8WeY5b7ONdyHtVG
-ZREAAABFPM9zs6UqaOn1MQP8Ek/T2rOde+ZFamVC55T7lqo9SsxD1QuVRQAAABSz9RHzex9Jb7+O
-i7l1b8utc3uqkfa8p6blt+oyTdO0+U2XSwghhNvtpgUBgOyu12sIIYQd3RZKdix/9xGnRwdcXxEA
-zvbxux91+f3fMf0plUUAAAAAPJizCACA09yrxl7NVbBvef3za5cq4udeN7eurctM/Z4j2xW7ztT7
-eH/t2nGda//YZS7tz1q77DlmAL1SWQQAwCmWBvbv/m3r68/a/j3becb2x+5jDccixTLn9qXm9oc9
-Pq4fi38gRrHKopikvvQvG3vWs+fLxS8yfpEBAOb7DDH9taXX3//ter0u9pP29AvXtu91uXu2c6mP
-d6RftsWWdR89FiXsOWZ7zw+ojcmaSaFIZVGqXx5S/nqzd3v37r9fZAAA1sOGd3+/9votPz6msue2
-tz3bWWvgcsaxOLq81tof4EzZK4u2/mq05XVry1/7ZWPLLw4pvlBTbXcNHQS/yAAAOfoae19/u90W
-K5zvP3jN9V9S9lf2budaFXlpe6uacrRnquW11P4AZ8paWbT1V6PUy6/h1wO/yPjCBQD6kzNcWqrk
-fve61z9792duOTX05e7bkONHyL3tD9CzIreh5f6CWftlo9aORMntzn1Puy9XAKBmr2HDliqSEkHK
-7XYTWpx8fmh/gD9+1LhRZ06SfOQLodQEhEe+BN+VYKdc9mtbqCoCAHqVo5/zroJmy5QKqfclV9+x
-tr7snvYH6NmPkXe+9nCn1Q6T0AgAiO2LbekjrD3tLKav8lwtErvuPU/KPbKdc/2qVo5diW0+crtd
-D+0PkNtfNW7UvQz0tRz0zKdb7Nnu5+2v5YumxPbMlfECALz2tbY+DGTtCbO1PBxky3a21E86eiy2
-PiE4VT+9l/YHKKVIZdHR0s21JyDs/WWjhvmM/CIDAIzouX+3pSpo6fUxfbsSc2nu2c49fdaUUzds
-DWy27mOq45dif1K1P0DPslYWbf3VKPXya3uKQ6rt9osMANCDrQ/7qPmhJr3u17uK8b3bnGo/j94F
-0Op5BVDSZZqmafObLpdNH55rQcJrBcrWx83HLv/19ak+/Pc+Qn7rdqfc19flbA1+UuwLAGz9rt3R
-baFkx/J3H/F+lD59/wPA6T5+96Muv/87pj9VZM6iFGn93mXU8uQGv8gAAAAALShSWQQAcITKokY6
-liqLAKA6eyqLfmg2AADoj2kCANhLWAQAAB0SBgGwl7BohV9kAAAAgJEIi1YIgwAAAICRCIsAAMji
-Y6VCGwCo01+aAAAAAIA7lUUAACR10QQA0PZ3+TRN0+Y3XXQBAIDydnRbKNmx1EcEgC76UyqLAAAo
-1vkEAOq3KyzSEQAAAADokwmuAQAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMCDsAgAAACAB2ERAAAA
-AA/CIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMCDsAgAAACAB2ERAAAA
-AA/CIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMCDsAgAAACAB2ERAAAA
-AA/CIgAAAAAe/g/10lQlA3JSSwAAAABJRU5ErkJggg==
diff --git a/Documentation/DocBook/media/v4l/.gitignore b/Documentation/DocBook/media/v4l/.gitignore
deleted file mode 100644
index d7ec32eafac9..000000000000
--- a/Documentation/DocBook/media/v4l/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!*.xml
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
deleted file mode 100644
index fdee6b3f3eca..000000000000
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ /dev/null
@@ -1,353 +0,0 @@
- <bibliography>
- <title>References</title>
-
- <biblioentry id="cea608">
- <abbrev>CEA&nbsp;608-E</abbrev>
- <authorgroup>
- <corpauthor>Consumer Electronics Association (<ulink
-url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor>
- </authorgroup>
- <title>CEA-608-E R-2014 "Line 21 Data Services"</title>
- </biblioentry>
-
- <biblioentry id="en300294">
- <abbrev>EN&nbsp;300&nbsp;294</abbrev>
- <authorgroup>
- <corpauthor>European Telecommunication Standards Institute
-(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>EN 300 294 "625-line television Wide Screen Signalling
-(WSS)"</title>
- </biblioentry>
-
- <biblioentry id="ets300231">
- <abbrev>ETS&nbsp;300&nbsp;231</abbrev>
- <authorgroup>
- <corpauthor>European Telecommunication Standards Institute
-(<ulink
-url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>ETS 300 231 "Specification of the domestic video
-Programme Delivery Control system (PDC)"</title>
- </biblioentry>
-
- <biblioentry id="ets300706">
- <abbrev>ETS&nbsp;300&nbsp;706</abbrev>
- <authorgroup>
- <corpauthor>European Telecommunication Standards Institute
-(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>ETS 300 706 "Enhanced Teletext specification"</title>
- </biblioentry>
-
- <biblioentry id="mpeg2part1">
- <abbrev>ISO&nbsp;13818-1</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>), International
-Organisation for Standardisation (<ulink
-url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information
-technology &mdash; Generic coding of moving pictures and associated
-audio information: Systems"</title>
- </biblioentry>
-
- <biblioentry id="mpeg2part2">
- <abbrev>ISO&nbsp;13818-2</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>), International
-Organisation for Standardisation (<ulink
-url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information
-technology &mdash; Generic coding of moving pictures and associated
-audio information: Video"</title>
- </biblioentry>
-
- <biblioentry id="itu470">
- <abbrev>ITU&nbsp;BT.470</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.470-6 "Conventional Television
-Systems"</title>
- </biblioentry>
-
- <biblioentry id="itu601">
- <abbrev>ITU&nbsp;BT.601</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters
-of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect
-Ratios"</title>
- </biblioentry>
-
- <biblioentry id="itu653">
- <abbrev>ITU&nbsp;BT.653</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.653-3 "Teletext systems"</title>
- </biblioentry>
-
- <biblioentry id="itu709">
- <abbrev>ITU&nbsp;BT.709</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.709-5 "Parameter values for the
-HDTV standards for production and international programme
-exchange"</title>
- </biblioentry>
-
- <biblioentry id="itu1119">
- <abbrev>ITU&nbsp;BT.1119</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.1119 "625-line
-television Wide Screen Signalling (WSS)"</title>
- </biblioentry>
-
- <biblioentry id="jfif">
- <abbrev>JFIF</abbrev>
- <authorgroup>
- <corpauthor>Independent JPEG Group (<ulink
-url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor>
- </authorgroup>
- <title>JPEG File Interchange Format</title>
- <subtitle>Version 1.02</subtitle>
- </biblioentry>
-
- <biblioentry id="itu-t81">
- <abbrev>ITU-T.81</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union
-(<ulink url="http://www.itu.int">http://www.itu.int</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-T Recommendation T.81
-"Information Technology &mdash; Digital Compression and Coding of Continous-Tone
-Still Images &mdash; Requirements and Guidelines"</title>
- </biblioentry>
-
- <biblioentry id="w3c-jpeg-jfif">
- <abbrev>W3C JPEG JFIF</abbrev>
- <authorgroup>
- <corpauthor>The World Wide Web Consortium (<ulink
-url="http://www.w3.org/Graphics/JPEG">http://www.w3.org</ulink>)</corpauthor>
- </authorgroup>
- <title>JPEG JFIF</title>
- </biblioentry>
-
- <biblioentry id="smpte12m">
- <abbrev>SMPTE&nbsp;12M</abbrev>
- <authorgroup>
- <corpauthor>Society of Motion Picture and Television Engineers
-(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
- </authorgroup>
- <title>SMPTE 12M-1999 "Television, Audio and Film - Time and
-Control Code"</title>
- </biblioentry>
-
- <biblioentry id="smpte170m">
- <abbrev>SMPTE&nbsp;170M</abbrev>
- <authorgroup>
- <corpauthor>Society of Motion Picture and Television Engineers
-(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
- </authorgroup>
- <title>SMPTE 170M-1999 "Television - Composite Analog Video
-Signal - NTSC for Studio Applications"</title>
- </biblioentry>
-
- <biblioentry id="smpte240m">
- <abbrev>SMPTE&nbsp;240M</abbrev>
- <authorgroup>
- <corpauthor>Society of Motion Picture and Television Engineers
-(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
- </authorgroup>
- <title>SMPTE 240M-1999 "Television - Signal Parameters -
-1125-Line High-Definition Production"</title>
- </biblioentry>
-
- <biblioentry id="srgb">
- <abbrev>sRGB</abbrev>
- <authorgroup>
- <corpauthor>International Electrotechnical Commission
-(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement
-and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title>
- </biblioentry>
-
- <biblioentry id="sycc">
- <abbrev>sYCC</abbrev>
- <authorgroup>
- <corpauthor>International Electrotechnical Commission
-(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement
-and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title>
- </biblioentry>
-
- <biblioentry id="xvycc">
- <abbrev>xvYCC</abbrev>
- <authorgroup>
- <corpauthor>International Electrotechnical Commission
-(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement
-and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video
-applications - xvYCC"</title>
- </biblioentry>
-
- <biblioentry id="adobergb">
- <abbrev>AdobeRGB</abbrev>
- <authorgroup>
- <corpauthor>Adobe Systems Incorporated (<ulink url="http://www.adobe.com">http://www.adobe.com</ulink>)</corpauthor>
- </authorgroup>
- <title>Adobe&copy; RGB (1998) Color Image Encoding Version 2005-05</title>
- </biblioentry>
-
- <biblioentry id="oprgb">
- <abbrev>opRGB</abbrev>
- <authorgroup>
- <corpauthor>International Electrotechnical Commission
-(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement
-and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"</title>
- </biblioentry>
-
- <biblioentry id="itu2020">
- <abbrev>ITU&nbsp;BT.2020</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high
-definition television systems for production and international programme exchange"
-</title>
- </biblioentry>
-
- <biblioentry id="tech3213">
- <abbrev>EBU&nbsp;Tech&nbsp;3213</abbrev>
- <authorgroup>
- <corpauthor>European Broadcast Union (<ulink
-url="http://www.ebu.ch">http://www.ebu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"</title>
- </biblioentry>
-
- <biblioentry id="iec62106">
- <abbrev>IEC&nbsp;62106</abbrev>
- <authorgroup>
- <corpauthor>International Electrotechnical Commission
-(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting
-in the frequency range from 87,5 to 108,0 MHz</title>
- </biblioentry>
-
- <biblioentry id="nrsc4">
- <abbrev>NRSC-4-B</abbrev>
- <authorgroup>
- <corpauthor>National Radio Systems Committee
-(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor>
- </authorgroup>
- <title>NRSC-4-B: United States RBDS Standard</title>
- </biblioentry>
-
- <biblioentry id="iso12232">
- <abbrev>ISO&nbsp;12232:2006</abbrev>
- <authorgroup>
- <corpauthor>International Organization for Standardization
-(<ulink url="http://www.iso.org">http://www.iso.org</ulink>)</corpauthor>
- </authorgroup>
- <title>Photography &mdash; Digital still cameras &mdash; Determination
- of exposure index, ISO speed ratings, standard output sensitivity, and
- recommended exposure index</title>
- </biblioentry>
-
- <biblioentry id="cea861">
- <abbrev>CEA-861-E</abbrev>
- <authorgroup>
- <corpauthor>Consumer Electronics Association
-(<ulink url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor>
- </authorgroup>
- <title>A DTV Profile for Uncompressed High Speed Digital Interfaces</title>
- </biblioentry>
-
- <biblioentry id="vesadmt">
- <abbrev>VESA&nbsp;DMT</abbrev>
- <authorgroup>
- <corpauthor>Video Electronics Standards Association
-(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor>
- </authorgroup>
- <title>VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)</title>
- </biblioentry>
-
- <biblioentry id="vesaedid">
- <abbrev>EDID</abbrev>
- <authorgroup>
- <corpauthor>Video Electronics Standards Association
-(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor>
- </authorgroup>
- <title>VESA Enhanced Extended Display Identification Data Standard</title>
- <subtitle>Release A, Revision 2</subtitle>
- </biblioentry>
-
- <biblioentry id="hdcp">
- <abbrev>HDCP</abbrev>
- <authorgroup>
- <corpauthor>Digital Content Protection LLC
-(<ulink url="http://www.digital-cp.com">http://www.digital-cp.com</ulink>)</corpauthor>
- </authorgroup>
- <title>High-bandwidth Digital Content Protection System</title>
- <subtitle>Revision 1.3</subtitle>
- </biblioentry>
-
- <biblioentry id="hdmi">
- <abbrev>HDMI</abbrev>
- <authorgroup>
- <corpauthor>HDMI Licensing LLC
-(<ulink url="http://www.hdmi.org">http://www.hdmi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>High-Definition Multimedia Interface</title>
- <subtitle>Specification Version 1.4a</subtitle>
- </biblioentry>
-
- <biblioentry id="dp">
- <abbrev>DP</abbrev>
- <authorgroup>
- <corpauthor>Video Electronics Standards Association
-(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor>
- </authorgroup>
- <title>VESA DisplayPort Standard</title>
- <subtitle>Version 1, Revision 2</subtitle>
- </biblioentry>
-
- <biblioentry id="poynton">
- <abbrev>poynton</abbrev>
- <authorgroup>
- <corpauthor>Charles Poynton</corpauthor>
- </authorgroup>
- <title>Digital Video and HDTV, Algorithms and Interfaces</title>
- </biblioentry>
-
- <biblioentry id="colimg">
- <abbrev>colimg</abbrev>
- <authorgroup>
- <corpauthor>Erik Reinhard et al.</corpauthor>
- </authorgroup>
- <title>Color Imaging: Fundamentals and Applications</title>
- </biblioentry>
-
- </bibliography>
diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml
deleted file mode 100644
index 1c5c49a2de59..000000000000
--- a/Documentation/DocBook/media/v4l/capture.c.xml
+++ /dev/null
@@ -1,659 +0,0 @@
-<programlisting>
-/*
- * V4L2 video capture example
- *
- * This program can be used and distributed without restrictions.
- *
- * This program is provided with the V4L2 API
- * see http://linuxtv.org/docs.php for more information
- */
-
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-#include &lt;string.h&gt;
-#include &lt;assert.h&gt;
-
-#include &lt;getopt.h&gt; /* getopt_long() */
-
-#include &lt;fcntl.h&gt; /* low-level i/o */
-#include &lt;unistd.h&gt;
-#include &lt;errno.h&gt;
-#include &lt;sys/stat.h&gt;
-#include &lt;sys/types.h&gt;
-#include &lt;sys/time.h&gt;
-#include &lt;sys/mman.h&gt;
-#include &lt;sys/ioctl.h&gt;
-
-#include &lt;linux/videodev2.h&gt;
-
-#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
-
-enum io_method {
- IO_METHOD_READ,
- IO_METHOD_MMAP,
- IO_METHOD_USERPTR,
-};
-
-struct buffer {
- void *start;
- size_t length;
-};
-
-static char *dev_name;
-static enum io_method io = IO_METHOD_MMAP;
-static int fd = -1;
-struct buffer *buffers;
-static unsigned int n_buffers;
-static int out_buf;
-static int force_format;
-static int frame_count = 70;
-
-static void errno_exit(const char *s)
-{
- fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno));
- exit(EXIT_FAILURE);
-}
-
-static int xioctl(int fh, int request, void *arg)
-{
- int r;
-
- do {
- r = ioctl(fh, request, arg);
- } while (-1 == r &amp;&amp; EINTR == errno);
-
- return r;
-}
-
-static void process_image(const void *p, int size)
-{
- if (out_buf)
- fwrite(p, size, 1, stdout);
-
- fflush(stderr);
- fprintf(stderr, ".");
- fflush(stdout);
-}
-
-static int read_frame(void)
-{
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
- unsigned int i;
-
- switch (io) {
- case IO_METHOD_READ:
- if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("read");
- }
- }
-
- process_image(buffers[0].start, buffers[0].length);
- break;
-
- case IO_METHOD_MMAP:
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
-
- if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("VIDIOC_DQBUF");
- }
- }
-
- assert(buf.index &lt; n_buffers);
-
- process_image(buffers[buf.index].start, buf.bytesused);
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- break;
-
- case IO_METHOD_USERPTR:
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_USERPTR;
-
- if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("VIDIOC_DQBUF");
- }
- }
-
- for (i = 0; i &lt; n_buffers; ++i)
- if (buf.m.userptr == (unsigned long)buffers[i].start
- &amp;&amp; buf.length == buffers[i].length)
- break;
-
- assert(i &lt; n_buffers);
-
- process_image((void *)buf.m.userptr, buf.bytesused);
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- break;
- }
-
- return 1;
-}
-
-static void mainloop(void)
-{
- unsigned int count;
-
- count = frame_count;
-
- while (count-- &gt; 0) {
- for (;;) {
- fd_set fds;
- struct timeval tv;
- int r;
-
- FD_ZERO(&amp;fds);
- FD_SET(fd, &amp;fds);
-
- /* Timeout. */
- tv.tv_sec = 2;
- tv.tv_usec = 0;
-
- r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
-
- if (-1 == r) {
- if (EINTR == errno)
- continue;
- errno_exit("select");
- }
-
- if (0 == r) {
- fprintf(stderr, "select timeout\n");
- exit(EXIT_FAILURE);
- }
-
- if (read_frame())
- break;
- /* EAGAIN - continue select loop. */
- }
- }
-}
-
-static void stop_capturing(void)
-{
- enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
-
- switch (io) {
- case IO_METHOD_READ:
- /* Nothing to do. */
- break;
-
- case IO_METHOD_MMAP:
- case IO_METHOD_USERPTR:
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &amp;type))
- errno_exit("VIDIOC_STREAMOFF");
- break;
- }
-}
-
-static void start_capturing(void)
-{
- unsigned int i;
- enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
-
- switch (io) {
- case IO_METHOD_READ:
- /* Nothing to do. */
- break;
-
- case IO_METHOD_MMAP:
- for (i = 0; i &lt; n_buffers; ++i) {
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = i;
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
- errno_exit("VIDIOC_STREAMON");
- break;
-
- case IO_METHOD_USERPTR:
- for (i = 0; i &lt; n_buffers; ++i) {
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_USERPTR;
- buf.index = i;
- buf.m.userptr = (unsigned long)buffers[i].start;
- buf.length = buffers[i].length;
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
- errno_exit("VIDIOC_STREAMON");
- break;
- }
-}
-
-static void uninit_device(void)
-{
- unsigned int i;
-
- switch (io) {
- case IO_METHOD_READ:
- free(buffers[0].start);
- break;
-
- case IO_METHOD_MMAP:
- for (i = 0; i &lt; n_buffers; ++i)
- if (-1 == munmap(buffers[i].start, buffers[i].length))
- errno_exit("munmap");
- break;
-
- case IO_METHOD_USERPTR:
- for (i = 0; i &lt; n_buffers; ++i)
- free(buffers[i].start);
- break;
- }
-
- free(buffers);
-}
-
-static void init_read(unsigned int buffer_size)
-{
- buffers = calloc(1, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-
- buffers[0].length = buffer_size;
- buffers[0].start = malloc(buffer_size);
-
- if (!buffers[0].start) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-}
-
-static void init_mmap(void)
-{
- struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
-
- CLEAR(req);
-
- req.count = 4;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_MMAP;
-
- if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s does not support "
- "memory mapping\n", dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_REQBUFS");
- }
- }
-
- if (req.count &lt; 2) {
- fprintf(stderr, "Insufficient buffer memory on %s\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
-
- buffers = calloc(req.count, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-
- for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
-
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = n_buffers;
-
- if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &amp;buf))
- errno_exit("VIDIOC_QUERYBUF");
-
- buffers[n_buffers].length = buf.length;
- buffers[n_buffers].start =
- mmap(NULL /* start anywhere */,
- buf.length,
- PROT_READ | PROT_WRITE /* required */,
- MAP_SHARED /* recommended */,
- fd, buf.m.offset);
-
- if (MAP_FAILED == buffers[n_buffers].start)
- errno_exit("mmap");
- }
-}
-
-static void init_userp(unsigned int buffer_size)
-{
- struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
-
- CLEAR(req);
-
- req.count = 4;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_USERPTR;
-
- if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s does not support "
- "user pointer i/o\n", dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_REQBUFS");
- }
- }
-
- buffers = calloc(4, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-
- for (n_buffers = 0; n_buffers &lt; 4; ++n_buffers) {
- buffers[n_buffers].length = buffer_size;
- buffers[n_buffers].start = malloc(buffer_size);
-
- if (!buffers[n_buffers].start) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
- }
-}
-
-static void init_device(void)
-{
- struct <link linkend="v4l2-capability">v4l2_capability</link> cap;
- struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap;
- struct <link linkend="v4l2-crop">v4l2_crop</link> crop;
- struct <link linkend="v4l2-format">v4l2_format</link> fmt;
- unsigned int min;
-
- if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &amp;cap)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s is no V4L2 device\n",
- dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_QUERYCAP");
- }
- }
-
- if (!(cap.capabilities &amp; V4L2_CAP_VIDEO_CAPTURE)) {
- fprintf(stderr, "%s is no video capture device\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
-
- switch (io) {
- case IO_METHOD_READ:
- if (!(cap.capabilities &amp; V4L2_CAP_READWRITE)) {
- fprintf(stderr, "%s does not support read i/o\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
- break;
-
- case IO_METHOD_MMAP:
- case IO_METHOD_USERPTR:
- if (!(cap.capabilities &amp; V4L2_CAP_STREAMING)) {
- fprintf(stderr, "%s does not support streaming i/o\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
- break;
- }
-
-
- /* Select video input, video standard and tune here. */
-
-
- CLEAR(cropcap);
-
- cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (0 == xioctl(fd, VIDIOC_CROPCAP, &amp;cropcap)) {
- crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- crop.c = cropcap.defrect; /* reset to default */
-
- if (-1 == xioctl(fd, VIDIOC_S_CROP, &amp;crop)) {
- switch (errno) {
- case EINVAL:
- /* Cropping not supported. */
- break;
- default:
- /* Errors ignored. */
- break;
- }
- }
- } else {
- /* Errors ignored. */
- }
-
-
- CLEAR(fmt);
-
- fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (force_format) {
- fmt.fmt.pix.width = 640;
- fmt.fmt.pix.height = 480;
- fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
- fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
-
- if (-1 == xioctl(fd, VIDIOC_S_FMT, &amp;fmt))
- errno_exit("VIDIOC_S_FMT");
-
- /* Note VIDIOC_S_FMT may change width and height. */
- } else {
- /* Preserve original settings as set by v4l2-ctl for example */
- if (-1 == xioctl(fd, VIDIOC_G_FMT, &amp;fmt))
- errno_exit("VIDIOC_G_FMT");
- }
-
- /* Buggy driver paranoia. */
- min = fmt.fmt.pix.width * 2;
- if (fmt.fmt.pix.bytesperline &lt; min)
- fmt.fmt.pix.bytesperline = min;
- min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
- if (fmt.fmt.pix.sizeimage &lt; min)
- fmt.fmt.pix.sizeimage = min;
-
- switch (io) {
- case IO_METHOD_READ:
- init_read(fmt.fmt.pix.sizeimage);
- break;
-
- case IO_METHOD_MMAP:
- init_mmap();
- break;
-
- case IO_METHOD_USERPTR:
- init_userp(fmt.fmt.pix.sizeimage);
- break;
- }
-}
-
-static void close_device(void)
-{
- if (-1 == close(fd))
- errno_exit("close");
-
- fd = -1;
-}
-
-static void open_device(void)
-{
- struct stat st;
-
- if (-1 == stat(dev_name, &amp;st)) {
- fprintf(stderr, "Cannot identify '%s': %d, %s\n",
- dev_name, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-
- if (!S_ISCHR(st.st_mode)) {
- fprintf(stderr, "%s is no device\n", dev_name);
- exit(EXIT_FAILURE);
- }
-
- fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
-
- if (-1 == fd) {
- fprintf(stderr, "Cannot open '%s': %d, %s\n",
- dev_name, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-}
-
-static void usage(FILE *fp, int argc, char **argv)
-{
- fprintf(fp,
- "Usage: %s [options]\n\n"
- "Version 1.3\n"
- "Options:\n"
- "-d | --device name Video device name [%s]\n"
- "-h | --help Print this message\n"
- "-m | --mmap Use memory mapped buffers [default]\n"
- "-r | --read Use read() calls\n"
- "-u | --userp Use application allocated buffers\n"
- "-o | --output Outputs stream to stdout\n"
- "-f | --format Force format to 640x480 YUYV\n"
- "-c | --count Number of frames to grab [%i]\n"
- "",
- argv[0], dev_name, frame_count);
-}
-
-static const char short_options[] = "d:hmruofc:";
-
-static const struct option
-long_options[] = {
- { "device", required_argument, NULL, 'd' },
- { "help", no_argument, NULL, 'h' },
- { "mmap", no_argument, NULL, 'm' },
- { "read", no_argument, NULL, 'r' },
- { "userp", no_argument, NULL, 'u' },
- { "output", no_argument, NULL, 'o' },
- { "format", no_argument, NULL, 'f' },
- { "count", required_argument, NULL, 'c' },
- { 0, 0, 0, 0 }
-};
-
-int main(int argc, char **argv)
-{
- dev_name = "/dev/video0";
-
- for (;;) {
- int idx;
- int c;
-
- c = getopt_long(argc, argv,
- short_options, long_options, &amp;idx);
-
- if (-1 == c)
- break;
-
- switch (c) {
- case 0: /* getopt_long() flag */
- break;
-
- case 'd':
- dev_name = optarg;
- break;
-
- case 'h':
- usage(stdout, argc, argv);
- exit(EXIT_SUCCESS);
-
- case 'm':
- io = IO_METHOD_MMAP;
- break;
-
- case 'r':
- io = IO_METHOD_READ;
- break;
-
- case 'u':
- io = IO_METHOD_USERPTR;
- break;
-
- case 'o':
- out_buf++;
- break;
-
- case 'f':
- force_format++;
- break;
-
- case 'c':
- errno = 0;
- frame_count = strtol(optarg, NULL, 0);
- if (errno)
- errno_exit(optarg);
- break;
-
- default:
- usage(stderr, argc, argv);
- exit(EXIT_FAILURE);
- }
- }
-
- open_device();
- init_device();
- start_capturing();
- mainloop();
- stop_capturing();
- uninit_device();
- close_device();
- fprintf(stderr, "\n");
- return 0;
-}
-</programlisting>
diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
deleted file mode 100644
index 8b5e014224d6..000000000000
--- a/Documentation/DocBook/media/v4l/common.xml
+++ /dev/null
@@ -1,1102 +0,0 @@
- <title>Common API Elements</title>
-
- <para>Programming a V4L2 device consists of these
-steps:</para>
-
- <itemizedlist>
- <listitem>
- <para>Opening the device</para>
- </listitem>
- <listitem>
- <para>Changing device properties, selecting a video and audio
-input, video standard, picture brightness a.&nbsp;o.</para>
- </listitem>
- <listitem>
- <para>Negotiating a data format</para>
- </listitem>
- <listitem>
- <para>Negotiating an input/output method</para>
- </listitem>
- <listitem>
- <para>The actual input/output loop</para>
- </listitem>
- <listitem>
- <para>Closing the device</para>
- </listitem>
- </itemizedlist>
-
- <para>In practice most steps are optional and can be executed out of
-order. It depends on the V4L2 device type, you can read about the
-details in <xref linkend="devices" />. In this chapter we will discuss
-the basic concepts applicable to all devices.</para>
-
- <section id="open">
- <title>Opening and Closing Devices</title>
-
- <section>
- <title>Device Naming</title>
-
- <para>V4L2 drivers are implemented as kernel modules, loaded
-manually by the system administrator or automatically when a device is
-first discovered. The driver modules plug into the "videodev" kernel
-module. It provides helper functions and a common application
-interface specified in this document.</para>
-
- <para>Each driver thus loaded registers one or more device nodes
-with major number 81 and a minor number between 0 and 255. Minor numbers
-are allocated dynamically unless the kernel is compiled with the kernel
-option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
-allocated in ranges depending on the device node type (video, radio, etc.).</para>
-
- <para>Many drivers support "video_nr", "radio_nr" or "vbi_nr"
-module options to select specific video/radio/vbi node numbers. This allows
-the user to request that the device node is named e.g. /dev/video5 instead
-of leaving it to chance. When the driver supports multiple devices of the same
-type more than one device node number can be assigned, separated by commas:
- <informalexample>
- <screen>
-&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
- </informalexample></para>
-
- <para>In <filename>/etc/modules.conf</filename> this may be
-written as: <informalexample>
- <screen>
-options mydriver video_nr=0,1 radio_nr=0,1
- </screen>
- </informalexample> When no device node number is given as module
-option the driver supplies a default.</para>
-
- <para>Normally udev will create the device nodes in /dev automatically
-for you. If udev is not installed, then you need to enable the
-CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
-relate a minor number to a device node number. I.e., you need to be certain
-that minor number 5 maps to device node name video5. With this kernel option
-different device types have different minor number ranges. These ranges are
-listed in <xref linkend="devices" />.
-</para>
-
- <para>The creation of character special files (with
-<application>mknod</application>) is a privileged operation and
-devices cannot be opened by major and minor number. That means
-applications cannot <emphasis>reliable</emphasis> scan for loaded or
-installed drivers. The user must enter a device name, or the
-application can try the conventional device names.</para>
- </section>
-
- <section id="related">
- <title>Related Devices</title>
-
- <para>Devices can support several functions. For example
-video capturing, VBI capturing and radio support.</para>
-
- <para>The V4L2 API creates different nodes for each of these functions.</para>
-
- <para>The V4L2 API was designed with the idea that one device node could support
-all functions. However, in practice this never worked: this 'feature'
-was never used by applications and many drivers did not support it and if
-they did it was certainly never tested. In addition, switching a device
-node between different functions only works when using the streaming I/O
-API, not with the read()/write() API.</para>
-
- <para>Today each device node supports just one function.</para>
-
- <para>Besides video input or output the hardware may also
-support audio sampling or playback. If so, these functions are
-implemented as ALSA PCM devices with optional ALSA audio mixer
-devices.</para>
-
- <para>One problem with all these devices is that the V4L2 API
-makes no provisions to find these related devices. Some really
-complex devices use the Media Controller (see <xref linkend="media_controller" />)
-which can be used for this purpose. But most drivers do not use it,
-and while some code exists that uses sysfs to discover related devices
-(see libmedia_dev in the <ulink url="http://git.linuxtv.org/cgit.cgi/v4l-utils.git/">v4l-utils</ulink>
-git repository), there is no library yet that can provide a single API towards
-both Media Controller-based devices and devices that do not use the Media Controller.
-If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para>
- </section>
-
- <section>
- <title>Multiple Opens</title>
-
- <para>V4L2 devices can be opened more than once.<footnote><para>
-There are still some old and obscure drivers that have not been updated to
-allow for multiple opens. This implies that for such drivers &func-open; can
-return an &EBUSY; when the device is already in use.</para></footnote>
-When this is supported by the driver, users can for example start a
-"panel" application to change controls like brightness or audio
-volume, while another application captures video and audio. In other words, panel
-applications are comparable to an ALSA audio mixer application.
-Just opening a V4L2 device should not change the state of the device.<footnote>
-<para>Unfortunately, opening a radio device often switches the state of the
-device to radio mode in many drivers. This behavior should be fixed eventually
-as it violates the V4L2 specification.</para></footnote></para>
-
- <para>Once an application has allocated the memory buffers needed for
-streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls,
-or implicitly by calling the &func-read; or &func-write; functions) that
-application (filehandle) becomes the owner of the device. It is no longer
-allowed to make changes that would affect the buffer sizes (e.g. by calling
-the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate
-buffers or start or stop streaming. The &EBUSY; will be returned instead.</para>
-
- <para>Merely opening a V4L2 device does not grant exclusive
-access.<footnote>
- <para>Drivers could recognize the
-<constant>O_EXCL</constant> open flag. Presently this is not required,
-so applications cannot know if it really works.</para>
- </footnote> Initiating data exchange however assigns the right
-to read or write the requested type of data, and to change related
-properties, to this file descriptor. Applications can request
-additional access privileges using the priority mechanism described in
-<xref linkend="app-pri" />.</para>
- </section>
-
- <section>
- <title>Shared Data Streams</title>
-
- <para>V4L2 drivers should not support multiple applications
-reading or writing the same data stream on a device by copying
-buffers, time multiplexing or similar means. This is better handled by
-a proxy application in user space.</para>
- </section>
-
- <section>
- <title>Functions</title>
-
- <para>To open and close V4L2 devices applications use the
-&func-open; and &func-close; function, respectively. Devices are
-programmed using the &func-ioctl; function as explained in the
-following sections.</para>
- </section>
- </section>
-
- <section id="querycap">
- <title>Querying Capabilities</title>
-
- <para>Because V4L2 covers a wide variety of devices not all
-aspects of the API are equally applicable to all types of devices.
-Furthermore devices of the same type have different capabilities and
-this specification permits the omission of a few complicated and less
-important parts of the API.</para>
-
- <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
-device is compatible with this specification, and to query the <link
-linkend="devices">functions</link> and <link linkend="io">I/O
-methods</link> supported by the device.</para>
-
- <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
-V4L2 API version used by the driver, with generally matches the Kernel version.
-There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is
-supported, the V4L2 core now returns ENOTTY if a driver doesn't provide
-support for an ioctl.</para>
-
- <para>Other features can be queried
-by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
-to learn about the number, types and names of video connectors on the
-device. Although abstraction is a major objective of this API, the
-&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify
-the driver.</para>
-
- <para>All V4L2 drivers must support
-<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
-this ioctl after opening the device.</para>
- </section>
-
- <section id="app-pri">
- <title>Application Priority</title>
-
- <para>When multiple applications share a device it may be
-desirable to assign them different priorities. Contrary to the
-traditional "rm -rf /" school of thought a video recording application
-could for example block other applications from changing video
-controls or switching the current TV channel. Another objective is to
-permit low priority applications working in background, which can be
-preempted by user controlled applications and automatically regain
-control of the device at a later time.</para>
-
- <para>Since these features cannot be implemented entirely in user
-space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
-ioctls to request and query the access priority associate with a file
-descriptor. Opening a device assigns a medium priority, compatible
-with earlier versions of V4L2 and drivers not supporting these ioctls.
-Applications requiring a different priority will usually call
-<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
-the &VIDIOC-QUERYCAP; ioctl.</para>
-
- <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
-return an &EBUSY; after another application obtained higher priority.</para>
- </section>
-
- <section id="video">
- <title>Video Inputs and Outputs</title>
-
- <para>Video inputs and outputs are physical connectors of a
-device. These can be for example RF connectors (antenna/cable), CVBS
-a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI
-capture devices have inputs. Video and VBI output devices have outputs,
-at least one each. Radio devices have no video inputs or outputs.</para>
-
- <para>To learn about the number and attributes of the
-available inputs and outputs applications can enumerate them with the
-&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
-&v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
-ioctl also contains signal status information applicable when the
-current video input is queried.</para>
-
- <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the
-index of the current video input or output. To select a different
-input or output applications call the &VIDIOC-S-INPUT; and
-&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls
-when the device has one or more inputs, all the output ioctls when the
-device has one or more outputs.</para>
-
- <example>
- <title>Information about the current video input</title>
-
- <programlisting>
-&v4l2-input; input;
-int index;
-
-if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;index)) {
- perror("VIDIOC_G_INPUT");
- exit(EXIT_FAILURE);
-}
-
-memset(&amp;input, 0, sizeof(input));
-input.index = index;
-
-if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
- perror("VIDIOC_ENUMINPUT");
- exit(EXIT_FAILURE);
-}
-
-printf("Current input: %s\n", input.name);
- </programlisting>
- </example>
-
- <example>
- <title>Switching to the first video input</title>
-
- <programlisting>
-int index;
-
-index = 0;
-
-if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &amp;index)) {
- perror("VIDIOC_S_INPUT");
- exit(EXIT_FAILURE);
-}
- </programlisting>
- </example>
- </section>
-
- <section id="audio">
- <title>Audio Inputs and Outputs</title>
-
- <para>Audio inputs and outputs are physical connectors of a
-device. Video capture devices have inputs, output devices have
-outputs, zero or more each. Radio devices have no audio inputs or
-outputs. They have exactly one tuner which in fact
-<emphasis>is</emphasis> an audio source, but this API associates
-tuners with video inputs or outputs only, and radio devices have
-none of these.<footnote>
- <para>Actually &v4l2-audio; ought to have a
-<structfield>tuner</structfield> field like &v4l2-input;, not only
-making the API more consistent but also permitting radio devices with
-multiple tuners.</para>
- </footnote> A connector on a TV card to loop back the received
-audio signal to a sound card is not considered an audio output.</para>
-
- <para>Audio and video inputs and outputs are associated. Selecting
-a video source also selects an audio source. This is most evident when
-the video and audio source is a tuner. Further audio connectors can
-combine with more than one video input or output. Assumed two
-composite video inputs and two audio inputs exist, there may be up to
-four valid combinations. The relation of video and audio connectors
-is defined in the <structfield>audioset</structfield> field of the
-respective &v4l2-input; or &v4l2-output;, where each bit represents
-the index number, starting at zero, of one audio input or output.</para>
-
- <para>To learn about the number and attributes of the
-available inputs and outputs applications can enumerate them with the
-&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
-&v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
-also contains signal status information applicable when the current
-audio input is queried.</para>
-
- <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report
-the current audio input and output, respectively. Note that, unlike
-&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
-as <constant>VIDIOC_ENUMAUDIO</constant> and
-<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
-
- <para>To select an audio input and change its properties
-applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
-output (which presently has no changeable properties) applications
-call the &VIDIOC-S-AUDOUT; ioctl.</para>
-
- <para>Drivers must implement all audio input ioctls when the device
-has multiple selectable audio inputs, all audio output ioctls when the
-device has multiple selectable audio outputs. When the device has any
-audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant>
-flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
-
- <example>
- <title>Information about the current audio input</title>
-
- <programlisting>
-&v4l2-audio; audio;
-
-memset(&amp;audio, 0, sizeof(audio));
-
-if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
- perror("VIDIOC_G_AUDIO");
- exit(EXIT_FAILURE);
-}
-
-printf("Current input: %s\n", audio.name);
- </programlisting>
- </example>
-
- <example>
- <title>Switching to the first audio input</title>
-
- <programlisting>
-&v4l2-audio; audio;
-
-memset(&amp;audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
-
-audio.index = 0;
-
-if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
- perror("VIDIOC_S_AUDIO");
- exit(EXIT_FAILURE);
-}
- </programlisting>
- </example>
- </section>
-
- <section id="tuner">
- <title>Tuners and Modulators</title>
-
- <section>
- <title>Tuners</title>
-
- <para>Video input devices can have one or more tuners
-demodulating a RF signal. Each tuner is associated with one or more
-video inputs, depending on the number of RF connectors on the tuner.
-The <structfield>type</structfield> field of the respective
-&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
-<constant>V4L2_INPUT_TYPE_TUNER</constant> and its
-<structfield>tuner</structfield> field contains the index number of
-the tuner.</para>
-
- <para>Radio input devices have exactly one tuner with index zero, no
-video inputs.</para>
-
- <para>To query and change tuner properties applications use the
-&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The
-&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
-contains signal status information applicable when the tuner of the
-current video or radio input is queried. Note that
-<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
-when there is more than one at all. The tuner is solely determined by
-the current video input. Drivers must support both ioctls and set the
-<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
-more tuners.</para>
- </section>
-
- <section>
- <title>Modulators</title>
-
- <para>Video output devices can have one or more modulators, uh,
-modulating a video signal for radiation or connection to the antenna
-input of a TV set or video recorder. Each modulator is associated with
-one or more video outputs, depending on the number of RF connectors on
-the modulator. The <structfield>type</structfield> field of the
-respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
-set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
-<structfield>modulator</structfield> field contains the index number
-of the modulator.</para>
-
- <para>Radio output devices have exactly one modulator with index
-zero, no video outputs.</para>
-
- <para>A video or radio device cannot support both a tuner and a
-modulator. Two separate device nodes will have to be used for such
-hardware, one that supports the tuner functionality and one that supports
-the modulator functionality. The reason is a limitation with the
-&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency
-is for a tuner or a modulator.</para>
-
- <para>To query and change modulator properties applications use
-the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
-<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
-modulator, when there is more than one at all. The modulator is solely
-determined by the current video output. Drivers must support both
-ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
-the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
-device has one or more modulators.</para>
- </section>
-
- <section>
- <title>Radio Frequency</title>
-
- <para>To get and set the tuner or modulator radio frequency
-applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
-ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
-are used for TV and radio devices alike. Drivers must support both
-ioctls when the tuner or modulator ioctls are supported, or
-when the device is a radio device.</para>
- </section>
- </section>
-
- <section id="standard">
- <title>Video Standards</title>
-
- <para>Video devices typically support one or more different video
-standards or variations of standards. Each video input and output may
-support another set of standards. This set is reported by the
-<structfield>std</structfield> field of &v4l2-input; and
-&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
-&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para>
-
- <para>V4L2 defines one bit for each analog video standard
-currently in use worldwide, and sets aside bits for driver defined
-standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
-and vice versa. Applications can use the predefined bits to select a
-particular standard, although presenting the user a menu of supported
-standards is preferred. To enumerate and query the attributes of the
-supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
-
- <para>Many of the defined standards are actually just variations
-of a few major standards. The hardware may in fact not distinguish
-between them, or do so internal and switch automatically. Therefore
-enumerated standards also contain sets of one or more standard
-bits.</para>
-
- <para>Assume a hypothetic tuner capable of demodulating B/PAL,
-G/PAL and I/PAL signals. The first enumerated standard is a set of B
-and G/PAL, switched automatically depending on the selected radio
-frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
-choice. Similar a Composite input may collapse standards, enumerating
-"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
- <para>Some users are already confused by technical terms PAL,
-NTSC and SECAM. There is no point asking them to distinguish between
-B, G, D, or K when the software or hardware can do that
-automatically.</para>
- </footnote></para>
-
- <para>To query and select the standard used by the current video
-input or output applications call the &VIDIOC-G-STD; and
-&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
-standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the
-parameter of all these ioctls is a pointer to a &v4l2-std-id; type
-(a standard set), <emphasis>not</emphasis> an index into the standard
-enumeration. Drivers must implement all video standard ioctls
-when the device has one or more video inputs or outputs.</para>
-
- <para>Special rules apply to devices such as USB cameras where the notion of video
-standards makes little sense. More generally for any capture or output device
-which is: <itemizedlist>
- <listitem>
- <para>incapable of capturing fields or frames at the nominal
-rate of the video standard, or</para>
- </listitem>
- <listitem>
- <para>that does not support the video standard formats at all.</para>
- </listitem>
- </itemizedlist> Here the driver shall set the
-<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
-to zero and the <constant>VIDIOC_G_STD</constant>,
-<constant>VIDIOC_S_STD</constant>,
-<constant>VIDIOC_QUERYSTD</constant> and
-<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
-&ENOTTY; or the &EINVAL;.</para>
- <para>Applications can make use of the <xref linkend="input-capabilities" /> and
-<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls
-can be used with the given input or output.</para>
-
- <example>
- <title>Information about the current video standard</title>
-
- <programlisting>
-&v4l2-std-id; std_id;
-&v4l2-standard; standard;
-
-if (-1 == ioctl(fd, &VIDIOC-G-STD;, &amp;std_id)) {
- /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
- is no video device or it falls under the USB exception,
- and VIDIOC_G_STD returning ENOTTY is no error. */
-
- perror("VIDIOC_G_STD");
- exit(EXIT_FAILURE);
-}
-
-memset(&amp;standard, 0, sizeof(standard));
-standard.index = 0;
-
-while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
- if (standard.id &amp; std_id) {
- printf("Current video standard: %s\n", standard.name);
- exit(EXIT_SUCCESS);
- }
-
- standard.index++;
-}
-
-/* EINVAL indicates the end of the enumeration, which cannot be
- empty unless this device falls under the USB exception. */
-
-if (errno == EINVAL || standard.index == 0) {
- perror("VIDIOC_ENUMSTD");
- exit(EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <example>
- <title>Listing the video standards supported by the current
-input</title>
-
- <programlisting>
-&v4l2-input; input;
-&v4l2-standard; standard;
-
-memset(&amp;input, 0, sizeof(input));
-
-if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
- perror("VIDIOC_G_INPUT");
- exit(EXIT_FAILURE);
-}
-
-if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
- perror("VIDIOC_ENUM_INPUT");
- exit(EXIT_FAILURE);
-}
-
-printf("Current input %s supports:\n", input.name);
-
-memset(&amp;standard, 0, sizeof(standard));
-standard.index = 0;
-
-while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
- if (standard.id &amp; input.std)
- printf("%s\n", standard.name);
-
- standard.index++;
-}
-
-/* EINVAL indicates the end of the enumeration, which cannot be
- empty unless this device falls under the USB exception. */
-
-if (errno != EINVAL || standard.index == 0) {
- perror("VIDIOC_ENUMSTD");
- exit(EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <example>
- <title>Selecting a new video standard</title>
-
- <programlisting>
-&v4l2-input; input;
-&v4l2-std-id; std_id;
-
-memset(&amp;input, 0, sizeof(input));
-
-if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
- perror("VIDIOC_G_INPUT");
- exit(EXIT_FAILURE);
-}
-
-if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
- perror("VIDIOC_ENUM_INPUT");
- exit(EXIT_FAILURE);
-}
-
-if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
- fprintf(stderr, "Oops. B/G PAL is not supported.\n");
- exit(EXIT_FAILURE);
-}
-
-/* Note this is also supposed to work when only B
- <emphasis>or</emphasis> G/PAL is supported. */
-
-std_id = V4L2_STD_PAL_BG;
-
-if (-1 == ioctl(fd, &VIDIOC-S-STD;, &amp;std_id)) {
- perror("VIDIOC_S_STD");
- exit(EXIT_FAILURE);
-}
- </programlisting>
- </example>
- </section>
- <section id="dv-timings">
- <title>Digital Video (DV) Timings</title>
- <para>
- The video standards discussed so far have been dealing with Analog TV and the
-corresponding video timings. Today there are many more different hardware interfaces
-such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
-video signals and there is a need to extend the API to select the video timings
-for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
-the limited bits available, a new set of ioctls was added to set/get video timings at
-the input and output.</para>
-
- <para>These ioctls deal with the detailed digital video timings that define
-each video format. This includes parameters such as the active video width and height,
-signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename>
-header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
-<xref linkend="vesadmt" /> standards.
- </para>
-
- <para>To enumerate and query the attributes of the DV timings supported by a device
- applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
- To set DV timings for the device applications use the
-&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
-&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
-use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
- <para>Applications can make use of the <xref linkend="input-capabilities" /> and
-<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls
-can be used with the given input or output.</para>
- </section>
-
- &sub-controls;
-
- <section id="format">
- <title>Data Formats</title>
-
- <section>
- <title>Data Format Negotiation</title>
-
- <para>Different devices exchange different kinds of data with
-applications, for example video images, raw or sliced VBI data, RDS
-datagrams. Even within one kind many different formats are possible,
-in particular an abundance of image formats. Although drivers must
-provide a default and the selection persists across closing and
-reopening a device, applications should always negotiate a data format
-before engaging in data exchange. Negotiation means the application
-asks for a particular format and the driver selects and reports the
-best the hardware can do to satisfy the request. Of course
-applications can also just query the current selection.</para>
-
- <para>A single mechanism exists to negotiate all data formats
-using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
-&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
-used to examine what the hardware <emphasis>could</emphasis> do,
-without actually selecting a new data format. The data formats
-supported by the V4L2 API are covered in the respective device section
-in <xref linkend="devices" />. For a closer look at image formats see
-<xref linkend="pixfmt" />.</para>
-
- <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
-turning-point in the initialization sequence. Prior to this point
-multiple panel applications can access the same device concurrently to
-select the current input, change controls or modify other properties.
-The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
-(video data, VBI data etc.) exclusively to one file descriptor.</para>
-
- <para>Exclusive means no other application, more precisely no
-other file descriptor, can grab this stream or change device
-properties inconsistent with the negotiated parameters. A video
-standard change for example, when the new standard uses a different
-number of scan lines, can invalidate the selected image format.
-Therefore only the file descriptor owning the stream can make
-invalidating changes. Accordingly multiple file descriptors which
-grabbed different logical streams prevent each other from interfering
-with their settings. When for example video overlay is about to start
-or already in progress, simultaneous video capturing may be restricted
-to the same cropping and image size.</para>
-
- <para>When applications omit the
-<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
-implied by the next step, the selection of an I/O method with the
-&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
-&func-write; call.</para>
-
- <para>Generally only one logical stream can be assigned to a
-file descriptor, the exception being drivers permitting simultaneous
-video capturing and overlay using the same file descriptor for
-compatibility with V4L and earlier versions of V4L2. Switching the
-logical stream or returning into "panel mode" is possible by closing
-and reopening the device. Drivers <emphasis>may</emphasis> support a
-switch using <constant>VIDIOC_S_FMT</constant>.</para>
-
- <para>All drivers exchanging data with
-applications must support the <constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
-<constant>VIDIOC_TRY_FMT</constant> is highly recommended but
-optional.</para>
- </section>
-
- <section>
- <title>Image Format Enumeration</title>
-
- <para>Apart of the generic format negotiation functions
-a special ioctl to enumerate all image formats supported by video
-capture, overlay or output devices is available.<footnote>
- <para>Enumerating formats an application has no a-priori
-knowledge of (otherwise it could explicitly ask for them and need not
-enumerate) seems useless, but there are applications serving as proxy
-between drivers and the actual video applications for which this is
-useful.</para>
- </footnote></para>
-
- <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
-by all drivers exchanging image data with applications.</para>
-
- <important>
- <para>Drivers are not supposed to convert image formats in
-kernel space. They must enumerate only formats directly supported by
-the hardware. If necessary driver writers should publish an example
-conversion routine or library for integration into applications.</para>
- </important>
- </section>
- </section>
-
- &sub-planar-apis;
-
- <section id="crop">
- <title>Image Cropping, Insertion and Scaling</title>
-
- <para>Some video capture devices can sample a subsection of the
-picture and shrink or enlarge it to an image of arbitrary size. We
-call these abilities cropping and scaling. Some video output devices
-can scale an image up or down and insert it at an arbitrary scan line
-and horizontal offset into a video signal.</para>
-
- <para>Applications can use the following API to select an area in
-the video signal, query the default area and the hardware limits.
-<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
-and &VIDIOC-S-CROP; ioctls apply to input as well as output
-devices.</emphasis></para>
-
- <para>Scaling requires a source and a target. On a video capture
-or overlay device the source is the video signal, and the cropping
-ioctls determine the area actually sampled. The target are images
-read by the application or overlaid onto the graphics screen. Their
-size (and position for an overlay) is negotiated with the
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
-
- <para>On a video output device the source are the images passed in
-by the application, and their size is again negotiated with the
-<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
-compressed video stream. The target is the video signal, and the
-cropping ioctls determine the area where the images are
-inserted.</para>
-
- <para>Source and target rectangles are defined even if the device
-does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
-ioctls. Their size (and position where applicable) will be fixed in
-this case. <emphasis>All capture and output device must support the
-<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
-determine if scaling takes place.</emphasis></para>
-
- <section>
- <title>Cropping Structures</title>
-
- <figure id="crop-scale">
- <title>Image Cropping, Insertion and Scaling</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="crop.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="crop.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>The cropping, insertion and scaling process</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>For capture devices the coordinates of the top left
-corner, width and height of the area which can be sampled is given by
-the <structfield>bounds</structfield> substructure of the
-&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
-ioctl. To support a wide range of hardware this specification does not
-define an origin or units. However by convention drivers should
-horizontally count unscaled samples relative to 0H (the leading edge
-of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
-Vertically ITU-R line
-numbers of the first field (<xref linkend="vbi-525" />, <xref
-linkend="vbi-625" />), multiplied by two if the driver can capture both
-fields.</para>
-
- <para>The top left corner, width and height of the source
-rectangle, that is the area actually sampled, is given by &v4l2-crop;
-using the same coordinate system as &v4l2-cropcap;. Applications can
-use the <constant>VIDIOC_G_CROP</constant> and
-<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
-rectangle. It must lie completely within the capture boundaries and
-the driver may further adjust the requested size and/or position
-according to hardware limitations.</para>
-
- <para>Each capture device has a default source rectangle, given
-by the <structfield>defrect</structfield> substructure of
-&v4l2-cropcap;. The center of this rectangle shall align with the
-center of the active picture area of the video signal, and cover what
-the driver writer considers the complete picture. Drivers shall reset
-the source rectangle to the default when the driver is first loaded,
-but not later.</para>
-
- <para>For output devices these structures and ioctls are used
-accordingly, defining the <emphasis>target</emphasis> rectangle where
-the images will be inserted into the video signal.</para>
-
- </section>
-
- <section>
- <title>Scaling Adjustments</title>
-
- <para>Video hardware can have various cropping, insertion and
-scaling limitations. It may only scale up or down, support only
-discrete scaling factors, or have different scaling abilities in
-horizontal and vertical direction. Also it may not support scaling at
-all. At the same time the &v4l2-crop; rectangle may have to be
-aligned, and both the source and target rectangles may have arbitrary
-upper and lower size limits. In particular the maximum
-<structfield>width</structfield> and <structfield>height</structfield>
-in &v4l2-crop; may be smaller than the
-&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
-usual, drivers are expected to adjust the requested parameters and
-return the actual values selected.</para>
-
- <para>Applications can change the source or the target rectangle
-first, as they may prefer a particular image size or a certain area in
-the video signal. If the driver has to adjust both to satisfy hardware
-limitations, the last requested rectangle shall take priority, and the
-driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
-ioctl however shall not change the driver state and therefore only
-adjust the requested rectangle.</para>
-
- <para>Suppose scaling on a video capture device is restricted to
-a factor 1:1 or 2:1 in either direction and the target image size must
-be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
-rectangle is set to defaults, which are also the upper limit in this
-example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
-application requests an image size of 300&nbsp;&times;&nbsp;225
-pixels, assuming video will be scaled down from the "full picture"
-accordingly. The driver sets the image size to the closest possible
-values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
-closest to the requested size, that is 608&nbsp;&times;&nbsp;224
-(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
-0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
-rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
-application can easily propose another offset to center the cropping
-rectangle.</para>
-
- <para>Now the application may insist on covering an area using a
-picture aspect ratio closer to the original request, so it asks for a
-cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
-scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
-driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
-the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
-
- </section>
-
- <section>
- <title>Examples</title>
-
- <para>Source and target rectangles shall remain unchanged across
-closing and reopening a device, such that piping data into or out of a
-device will work without special preparations. More advanced
-applications should ensure the parameters are suitable before starting
-I/O.</para>
-
- <example>
- <title>Resetting the cropping parameters</title>
-
- <para>(A video capture device is assumed; change
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
-devices.)</para>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-crop; crop;
-
-memset (&amp;cropcap, 0, sizeof (cropcap));
-cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;crop, 0, sizeof (crop));
-crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-crop.c = cropcap.defrect;
-
-/* Ignore if cropping is not supported (EINVAL). */
-
-if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
- &amp;&amp; errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <example>
- <title>Simple downscaling</title>
-
- <para>(A video capture device is assumed.)</para>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-format; format;
-
-reset_cropping_parameters ();
-
-/* Scale down to 1/4 size of full picture. */
-
-memset (&amp;format, 0, sizeof (format)); /* defaults */
-
-format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
-format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
-format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
-
-if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
- perror ("VIDIOC_S_FORMAT");
- exit (EXIT_FAILURE);
-}
-
-/* We could check the actual image size now, the actual scaling factor
- or if the driver can scale at all. */
- </programlisting>
- </example>
-
- <example>
- <title>Selecting an output area</title>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-crop; crop;
-
-memset (&amp;cropcap, 0, sizeof (cropcap));
-cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
-
-if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;crop, 0, sizeof (crop));
-
-crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
-crop.c = cropcap.defrect;
-
-/* Scale the width and height to 50 % of their original size
- and center the output. */
-
-crop.c.width /= 2;
-crop.c.height /= 2;
-crop.c.left += crop.c.width / 2;
-crop.c.top += crop.c.height / 2;
-
-/* Ignore if cropping is not supported (EINVAL). */
-
-if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
- &amp;&amp; errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
-}
-</programlisting>
- </example>
-
- <example>
- <title>Current scaling factor and pixel aspect</title>
-
- <para>(A video capture device is assumed.)</para>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-crop; crop;
-&v4l2-format; format;
-double hscale, vscale;
-double aspect;
-int dwidth, dheight;
-
-memset (&amp;cropcap, 0, sizeof (cropcap));
-cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;crop, 0, sizeof (crop));
-crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
- if (errno != EINVAL) {
- perror ("VIDIOC_G_CROP");
- exit (EXIT_FAILURE);
- }
-
- /* Cropping not supported. */
- crop.c = cropcap.defrect;
-}
-
-memset (&amp;format, 0, sizeof (format));
-format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
- perror ("VIDIOC_G_FMT");
- exit (EXIT_FAILURE);
-}
-
-/* The scaling applied by the driver. */
-
-hscale = format.fmt.pix.width / (double) crop.c.width;
-vscale = format.fmt.pix.height / (double) crop.c.height;
-
-aspect = cropcap.pixelaspect.numerator /
- (double) cropcap.pixelaspect.denominator;
-aspect = aspect * hscale / vscale;
-
-/* Devices following ITU-R BT.601 do not capture
- square pixels. For playback on a computer monitor
- we should scale the images to this size. */
-
-dwidth = format.fmt.pix.width / aspect;
-dheight = format.fmt.pix.height;
- </programlisting>
- </example>
- </section>
- </section>
-
- &sub-selection-api;
-
- <section id="streaming-par">
- <title>Streaming Parameters</title>
-
- <para>Streaming parameters are intended to optimize the video
-capture process as well as I/O. Presently applications can request a
-high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
-
- <para>The current video standard determines a nominal number of
-frames per second. If less than this number of frames is to be
-captured or output, applications can request frame skipping or
-duplicating on the driver side. This is especially useful when using
-the &func-read; or &func-write;, which are not augmented by timestamps
-or sequence counters, and to avoid unnecessary data copying.</para>
-
- <para>Finally these ioctls can be used to determine the number of
-buffers used internally by a driver in read/write mode. For
-implications see the section discussing the &func-read;
-function.</para>
-
- <para>To get and set the streaming parameters applications call
-the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
-a pointer to a &v4l2-streamparm;, which contains a union holding
-separate parameters for input and output devices.</para>
-
- <para>These ioctls are optional, drivers need not implement
-them. If so, they return the &EINVAL;.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
deleted file mode 100644
index a0aef85d33c1..000000000000
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ /dev/null
@@ -1,2741 +0,0 @@
- <title>Changes</title>
-
- <para>The following chapters document the evolution of the V4L2 API,
-errata or extensions. They are also intended to help application and
-driver writers to port or update their code.</para>
-
- <section id="diff-v4l">
- <title>Differences between V4L and V4L2</title>
-
- <para>The Video For Linux API was first introduced in Linux 2.1 to
-unify and replace various TV and radio device related interfaces,
-developed independently by driver writers in prior years. Starting
-with Linux 2.5 the much improved V4L2 API replaces the V4L API.
-The support for the old V4L calls were removed from Kernel, but the
-library <xref linkend="libv4l" /> supports the conversion of a V4L
-API system call into a V4L2 one.</para>
-
- <section>
- <title>Opening and Closing Devices</title>
-
- <para>For compatibility reasons the character device file names
-recommended for V4L2 video capture, overlay, radio and raw
-vbi capture devices did not change from those used by V4L. They are
-listed in <xref linkend="devices" /> and below in <xref
- linkend="v4l-dev" />.</para>
-
- <para>The teletext devices (minor range 192-223) have been removed in
-V4L2 and no longer exist. There is no hardware available anymore for handling
-pure teletext. Instead raw or sliced VBI is used.</para>
-
- <para>The V4L <filename>videodev</filename> module automatically
-assigns minor numbers to drivers in load order, depending on the
-registered device type. We recommend that V4L2 drivers by default
-register devices with the same numbers, but the system administrator
-can assign arbitrary minor numbers using driver module options. The
-major device number remains 81.</para>
-
- <table id="v4l-dev">
- <title>V4L Device Types, Names and Numbers</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Device Type</entry>
- <entry>File Name</entry>
- <entry>Minor Numbers</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Video capture and overlay</entry>
- <entry><para><filename>/dev/video</filename> and
-<filename>/dev/bttv0</filename><footnote> <para>According to
-Documentation/devices.txt these should be symbolic links to
-<filename>/dev/video0</filename>. Note the original bttv interface is
-not compatible with V4L or V4L2.</para> </footnote>,
-<filename>/dev/video0</filename> to
-<filename>/dev/video63</filename></para></entry>
- <entry>0-63</entry>
- </row>
- <row>
- <entry>Radio receiver</entry>
- <entry><para><filename>/dev/radio</filename><footnote>
- <para>According to
-<filename>Documentation/devices.txt</filename> a symbolic link to
-<filename>/dev/radio0</filename>.</para>
- </footnote>, <filename>/dev/radio0</filename> to
-<filename>/dev/radio63</filename></para></entry>
- <entry>64-127</entry>
- </row>
- <row>
- <entry>Raw VBI capture</entry>
- <entry><para><filename>/dev/vbi</filename>,
-<filename>/dev/vbi0</filename> to
-<filename>/dev/vbi31</filename></para></entry>
- <entry>224-255</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>V4L prohibits (or used to prohibit) multiple opens of a
-device file. V4L2 drivers <emphasis>may</emphasis> support multiple
-opens, see <xref linkend="open" /> for details and consequences.</para>
-
- <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;.</para>
- </section>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is
-equivalent to V4L2's &VIDIOC-QUERYCAP;.</para>
-
- <para>The <structfield>name</structfield> field in struct
-<structname>video_capability</structname> became
-<structfield>card</structfield> in &v4l2-capability;,
-<structfield>type</structfield> was replaced by
-<structfield>capabilities</structfield>. Note V4L2 does not
-distinguish between device types like this, better think of basic
-video input, video output and radio devices supporting a set of
-related functions like video capturing, video overlay and VBI
-capturing. See <xref linkend="open" /> for an
-introduction.<informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>struct
-<structname>video_capability</structname>
-<structfield>type</structfield></entry>
- <entry>&v4l2-capability;
-<structfield>capabilities</structfield> flags</entry>
- <entry>Purpose</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>VID_TYPE_CAPTURE</constant></entry>
- <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
- <entry>The <link linkend="capture">video
-capture</link> interface is supported.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_TUNER</constant></entry>
- <entry><constant>V4L2_CAP_TUNER</constant></entry>
- <entry>The device has a <link linkend="tuner">tuner or
-modulator</link>.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_TELETEXT</constant></entry>
- <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
- <entry>The <link linkend="raw-vbi">raw VBI
-capture</link> interface is supported.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_OVERLAY</constant></entry>
- <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
- <entry>The <link linkend="overlay">video
-overlay</link> interface is supported.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_CHROMAKEY</constant></entry>
- <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in
-field <structfield>capability</structfield> of
-&v4l2-framebuffer;</entry>
- <entry>Whether chromakey overlay is supported. For
-more information on overlay see
-<xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_CLIPPING</constant></entry>
- <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant>
-and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field
-<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
- <entry>Whether clipping the overlaid image is
-supported, see <xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_FRAMERAM</constant></entry>
- <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
-<emphasis>not set</emphasis> in field
-<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
- <entry>Whether overlay overwrites frame buffer memory,
-see <xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_SCALES</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>This flag indicates if the hardware can scale
-images. The V4L2 API implies the scale factor by setting the cropping
-dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
-ioctl, respectively. The driver returns the closest sizes possible.
-For more information on cropping and scaling see <xref
- linkend="crop" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MONOCHROME</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>Applications can enumerate the supported image
-formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
-supports grey scale capturing only. For more information on image
-formats see <xref linkend="pixfmt" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>Applications can call the &VIDIOC-G-CROP; ioctl
-to determine if the device supports capturing a subsection of the full
-picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
-For more information on cropping and scaling see <xref
- linkend="crop" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>Applications can enumerate the supported image
-formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
-supports MPEG streams.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>See above.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>See above.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>See above.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>The <structfield>audios</structfield> field was replaced
-by <structfield>capabilities</structfield> flag
-<constant>V4L2_CAP_AUDIO</constant>, indicating
-<emphasis>if</emphasis> the device has any audio inputs or outputs. To
-determine their number applications can enumerate audio inputs with
-the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref
- linkend="audio" />.</para>
-
- <para>The <structfield>maxwidth</structfield>,
-<structfield>maxheight</structfield>,
-<structfield>minwidth</structfield> and
-<structfield>minheight</structfield> fields were removed. Calling the
-&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions
-returns the closest size possible, taking into account the current
-video standard, cropping and scaling limitations.</para>
- </section>
-
- <section>
- <title>Video Sources</title>
-
- <para>V4L provides the <constant>VIDIOCGCHAN</constant> and
-<constant>VIDIOCSCHAN</constant> ioctl using struct
-<structname>video_channel</structname> to enumerate
-the video inputs of a V4L device. The equivalent V4L2 ioctls
-are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
-using &v4l2-input; as discussed in <xref linkend="video" />.</para>
-
- <para>The <structfield>channel</structfield> field counting
-inputs was renamed to <structfield>index</structfield>, the video
-input types were renamed as follows: <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct <structname>video_channel</structname>
-<structfield>type</structfield></entry>
- <entry>&v4l2-input;
-<structfield>type</structfield></entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>VIDEO_TYPE_TV</constant></entry>
- <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
- </row>
- <row>
- <entry><constant>VIDEO_TYPE_CAMERA</constant></entry>
- <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>Unlike the <structfield>tuners</structfield> field
-expressing the number of tuners of this input, V4L2 assumes each video
-input is connected to at most one tuner. However a tuner can have more
-than one input, &ie; RF connectors, and a device can have multiple
-tuners. The index number of the tuner associated with the input, if
-any, is stored in field <structfield>tuner</structfield> of
-&v4l2-input;. Enumeration of tuners is discussed in <xref
- linkend="tuner" />.</para>
-
- <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was
-dropped. Video inputs associated with a tuner are of type
-<constant>V4L2_INPUT_TYPE_TUNER</constant>. The
-<constant>VIDEO_VC_AUDIO</constant> flag was replaced by the
-<structfield>audioset</structfield> field. V4L2 considers devices with
-up to 32 audio inputs. Each set bit in the
-<structfield>audioset</structfield> field represents one audio input
-this video input combines with. For information about audio inputs and
-how to switch between them see <xref linkend="audio" />.</para>
-
- <para>The <structfield>norm</structfield> field describing the
-supported video standards was replaced by
-<structfield>std</structfield>. The V4L specification mentions a flag
-<constant>VIDEO_VC_NORM</constant> indicating whether the standard can
-be changed. This flag was a later addition together with the
-<structfield>norm</structfield> field and has been removed in the
-meantime. V4L2 has a similar, albeit more comprehensive approach
-to video standards, see <xref linkend="standard" /> for more
-information.</para>
- </section>
-
- <section>
- <title>Tuning</title>
-
- <para>The V4L <constant>VIDIOCGTUNER</constant> and
-<constant>VIDIOCSTUNER</constant> ioctl and struct
-<structname>video_tuner</structname> can be used to enumerate the
-tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
-&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are
-covered in <xref linkend="tuner" />.</para>
-
- <para>The <structfield>tuner</structfield> field counting tuners
-was renamed to <structfield>index</structfield>. The fields
-<structfield>name</structfield>, <structfield>rangelow</structfield>
-and <structfield>rangehigh</structfield> remained unchanged.</para>
-
- <para>The <constant>VIDEO_TUNER_PAL</constant>,
-<constant>VIDEO_TUNER_NTSC</constant> and
-<constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported
-video standards were dropped. This information is now contained in the
-associated &v4l2-input;. No replacement exists for the
-<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
-video standard can be switched. The <structfield>mode</structfield>
-field to select a different video standard was replaced by a whole new
-set of ioctls and structures described in <xref linkend="standard" />.
-Due to its ubiquity it should be mentioned the BTTV driver supports
-several standards in addition to the regular
-<constant>VIDEO_MODE_PAL</constant> (0),
-<constant>VIDEO_MODE_NTSC</constant>,
-<constant>VIDEO_MODE_SECAM</constant> and
-<constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina,
-M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
-
- <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
-indicating stereo reception became
-<constant>V4L2_TUNER_SUB_STEREO</constant> in field
-<structfield>rxsubchans</structfield>. This field also permits the
-detection of monaural and bilingual audio, see the definition of
-&v4l2-tuner; for details. Presently no replacement exists for the
-<constant>VIDEO_TUNER_RDS_ON</constant> and
-<constant>VIDEO_TUNER_MBS_ON</constant> flags.</para>
-
- <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed
-to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner;
-<structfield>capability</structfield> field.</para>
-
- <para>The <constant>VIDIOCGFREQ</constant> and
-<constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency
-where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They
-take a pointer to a &v4l2-frequency; instead of an unsigned long
-integer.</para>
- </section>
-
- <section id="v4l-image-properties">
- <title>Image Properties</title>
-
- <para>V4L2 has no equivalent of the
-<constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant>
-ioctl and struct <structname>video_picture</structname>. The following
-fields where replaced by V4L2 controls accessible with the
-&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct <structname>video_picture</structname></entry>
- <entry>V4L2 Control ID</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><structfield>brightness</structfield></entry>
- <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
- </row>
- <row>
- <entry><structfield>hue</structfield></entry>
- <entry><constant>V4L2_CID_HUE</constant></entry>
- </row>
- <row>
- <entry><structfield>colour</structfield></entry>
- <entry><constant>V4L2_CID_SATURATION</constant></entry>
- </row>
- <row>
- <entry><structfield>contrast</structfield></entry>
- <entry><constant>V4L2_CID_CONTRAST</constant></entry>
- </row>
- <row>
- <entry><structfield>whiteness</structfield></entry>
- <entry><constant>V4L2_CID_WHITENESS</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>The V4L picture controls are assumed to range from 0 to
-65535 with no particular reset value. The V4L2 API permits arbitrary
-limits and defaults which can be queried with the &VIDIOC-QUERYCTRL;
-ioctl. For general information about controls see <xref
-linkend="control" />.</para>
-
- <para>The <structfield>depth</structfield> (average number of
-bits per pixel) of a video image is implied by the selected image
-format. V4L2 does not explicitly provide such information assuming
-applications recognizing the format are aware of the image depth and
-others need not know. The <structfield>palette</structfield> field
-moved into the &v4l2-pix-format;:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct <structname>video_picture</structname>
-<structfield>palette</structfield></entry>
- <entry>&v4l2-pix-format;
-<structfield>pixfmt</structfield></entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>VIDEO_PALETTE_GREY</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_HI240</constant></entry>
- <entry><para><link
-linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
- <para>This is a custom format used by the BTTV
-driver, not one of the V4L2 standard formats.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB565</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB555</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB24</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB32</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
- <para>Presumably all V4L RGB formats are
-little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue
-swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV422</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
- </row>
- <row>
- <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote>
- <para><constant>VIDEO_PALETTE_YUV422</constant>
-and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
-V4L drivers respond to one, some to the other.</para>
- </footnote></para></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_UYVY</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV420</constant></entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV411</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote>
- <para>Not to be confused with
-<constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar
-format.</para> </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RAW</constant></entry>
- <entry><para>None<footnote> <para>V4L explains this
-as: "RAW capture (BT848)"</para> </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote>
- <para>Not to be confused with
-<constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed
-format.</para> </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>V4L2 image formats are defined in <xref
-linkend="pixfmt" />. The image format can be selected with the
-&VIDIOC-S-FMT; ioctl.</para>
- </section>
-
- <section>
- <title>Audio</title>
-
- <para>The <constant>VIDIOCGAUDIO</constant> and
-<constant>VIDIOCSAUDIO</constant> ioctl and struct
-<structname>video_audio</structname> are used to enumerate the
-audio inputs of a V4L device. The equivalent V4L2 ioctls are
-&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
-discussed in <xref linkend="audio" />.</para>
-
- <para>The <structfield>audio</structfield> "channel number"
-field counting audio inputs was renamed to
-<structfield>index</structfield>.</para>
-
- <para>On <constant>VIDIOCSAUDIO</constant> the
-<structfield>mode</structfield> field selects <emphasis>one</emphasis>
-of the <constant>VIDEO_SOUND_MONO</constant>,
-<constant>VIDEO_SOUND_STEREO</constant>,
-<constant>VIDEO_SOUND_LANG1</constant> or
-<constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When
-the current audio standard is BTSC
-<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
-<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
-undocumented in the V4L specification, there is no way to query the
-selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
-the <emphasis>actually received</emphasis> audio programmes in this
-field. In the V4L2 API this information is stored in the &v4l2-tuner;
-<structfield>rxsubchans</structfield> and
-<structfield>audmode</structfield> fields, respectively. See <xref
-linkend="tuner" /> for more information on tuners. Related to audio
-modes &v4l2-audio; also reports if this is a mono or stereo
-input, regardless if the source is a tuner.</para>
-
- <para>The following fields where replaced by V4L2 controls
-accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and
-&VIDIOC-S-CTRL; ioctls:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct
-<structname>video_audio</structname></entry>
- <entry>V4L2 Control ID</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><structfield>volume</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
- </row>
- <row>
- <entry><structfield>bass</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
- </row>
- <row>
- <entry><structfield>treble</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
- </row>
- <row>
- <entry><structfield>balance</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>To determine which of these controls are supported by a
-driver V4L provides the <structfield>flags</structfield>
-<constant>VIDEO_AUDIO_VOLUME</constant>,
-<constant>VIDEO_AUDIO_BASS</constant>,
-<constant>VIDEO_AUDIO_TREBLE</constant> and
-<constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the
-&VIDIOC-QUERYCTRL; ioctl reports if the respective control is
-supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
-and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
-boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
-
- <para>All V4L2 controls have a <structfield>step</structfield>
-attribute replacing the struct <structname>video_audio</structname>
-<structfield>step</structfield> field. The V4L audio controls are
-assumed to range from 0 to 65535 with no particular reset value. The
-V4L2 API permits arbitrary limits and defaults which can be queried
-with the &VIDIOC-QUERYCTRL; ioctl. For general information about
-controls see <xref linkend="control" />.</para>
- </section>
-
- <section>
- <title>Frame Buffer Overlay</title>
-
- <para>The V4L2 ioctls equivalent to
-<constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant>
-are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
-<structfield>base</structfield> field of struct
-<structname>video_buffer</structname> remained unchanged, except V4L2
-defines a flag to indicate non-destructive overlays instead of a
-<constant>NULL</constant> pointer. All other fields moved into the
-&v4l2-pix-format; <structfield>fmt</structfield> substructure of
-&v4l2-framebuffer;. The <structfield>depth</structfield> field was
-replaced by <structfield>pixelformat</structfield>. See <xref
- linkend="pixfmt-rgb" /> for a list of RGB formats and their
-respective color depths.</para>
-
- <para>Instead of the special ioctls
-<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
-V4L2 uses the general-purpose data format negotiation ioctls
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
-&v4l2-format; as argument. Here the <structfield>win</structfield>
-member of the <structfield>fmt</structfield> union is used, a
-&v4l2-window;.</para>
-
- <para>The <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> fields of struct
-<structname>video_window</structname> moved into &v4l2-rect;
-substructure <structfield>w</structfield> of struct
-<structname>v4l2_window</structname>. The
-<structfield>chromakey</structfield>,
-<structfield>clips</structfield>, and
-<structfield>clipcount</structfield> fields remained unchanged. Struct
-<structname>video_clip</structname> was renamed to &v4l2-clip;, also
-containing a struct <structname>v4l2_rect</structname>, but the
-semantics are still the same.</para>
-
- <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
-dropped. Instead applications must set the
-<structfield>field</structfield> field to
-<constant>V4L2_FIELD_ANY</constant> or
-<constant>V4L2_FIELD_INTERLACED</constant>. The
-<constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into
-&v4l2-framebuffer;, under the new name
-<constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para>
-
- <para>In V4L, storing a bitmap pointer in
-<structfield>clips</structfield> and setting
-<structfield>clipcount</structfield> to
-<constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap
-clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
-<structname>v4l2_window</structname> has a separate
-<structfield>bitmap</structfield> pointer field for this purpose and
-the bitmap size is determined by <structfield>w.width</structfield> and
-<structfield>w.height</structfield>.</para>
-
- <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or
-disable overlay was renamed to &VIDIOC-OVERLAY;.</para>
- </section>
-
- <section>
- <title>Cropping</title>
-
- <para>To capture only a subsection of the full picture V4L
-defines the <constant>VIDIOCGCAPTURE</constant> and
-<constant>VIDIOCSCAPTURE</constant> ioctls using struct
-<structname>video_capture</structname>. The equivalent V4L2 ioctls are
-&VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related
-&VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see
-<xref linkend="crop" /> for details.</para>
-
- <para>The <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> fields moved into &v4l2-rect;
-substructure <structfield>c</structfield> of struct
-<structname>v4l2_crop</structname>. The
-<structfield>decimation</structfield> field was dropped. In the V4L2
-API the scaling factor is implied by the size of the cropping
-rectangle and the size of the captured or overlaid image.</para>
-
- <para>The <constant>VIDEO_CAPTURE_ODD</constant>
-and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
-odd or even field, respectively, were replaced by
-<constant>V4L2_FIELD_TOP</constant> and
-<constant>V4L2_FIELD_BOTTOM</constant> in the field named
-<structfield>field</structfield> of &v4l2-pix-format; and
-&v4l2-window;. These structures are used to select a capture or
-overlay format with the &VIDIOC-S-FMT; ioctl.</para>
- </section>
-
- <section>
- <title>Reading Images, Memory Mapping</title>
-
- <section>
- <title>Capturing using the read method</title>
-
- <para>There is no essential difference between reading images
-from a V4L or V4L2 device using the &func-read; function, however V4L2
-drivers are not required to support this I/O method. Applications can
-determine if the function is available with the &VIDIOC-QUERYCAP;
-ioctl. All V4L2 devices exchanging data with applications must support
-the &func-select; and &func-poll; functions.</para>
-
- <para>To select an image format and size, V4L provides the
-<constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant>
-ioctls. V4L2 uses the general-purpose data format negotiation ioctls
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
-&v4l2-format; as argument, here the &v4l2-pix-format; named
-<structfield>pix</structfield> of its <structfield>fmt</structfield>
-union is used.</para>
-
- <para>For more information about the V4L2 read interface see
-<xref linkend="rw" />.</para>
- </section>
- <section>
- <title>Capturing using memory mapping</title>
-
- <para>Applications can read from V4L devices by mapping
-buffers in device memory, or more often just buffers allocated in
-DMA-able system memory, into their address space. This avoids the data
-copying overhead of the read method. V4L2 supports memory mapping as
-well, with a few differences.</para>
-
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>V4L</entry>
- <entry>V4L2</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>The image format must be selected before
-buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
-is selected the driver may use the last, possibly by another
-application requested format.</entry>
- </row>
- <row>
- <entry><para>Applications cannot change the number of
-buffers. The it is built into the driver, unless it has a module
-option to change the number when the driver module is
-loaded.</para></entry>
- <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
-desired number of buffers, this is a required step in the initialization
-sequence.</para></entry>
- </row>
- <row>
- <entry><para>Drivers map all buffers as one contiguous
-range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is
-available to query the number of buffers, the offset of each buffer
-from the start of the virtual file, and the overall amount of memory
-used, which can be used as arguments for the &func-mmap;
-function.</para></entry>
- <entry><para>Buffers are individually mapped. The
-offset and size of each buffer can be determined with the
-&VIDIOC-QUERYBUF; ioctl.</para></entry>
- </row>
- <row>
- <entry><para>The <constant>VIDIOCMCAPTURE</constant>
-ioctl prepares a buffer for capturing. It also determines the image
-format for this buffer. The ioctl returns immediately, eventually with
-an &EAGAIN; if no video signal had been detected. When the driver
-supports more than one buffer applications can call the ioctl multiple
-times and thus have multiple outstanding capture
-requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
-suspends execution until a particular buffer has been
-filled.</para></entry>
- <entry><para>Drivers maintain an incoming and outgoing
-queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
-queue. Filled buffers are dequeued from the outgoing queue with the
-&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
-function, &func-select; or &func-poll; can be used. The
-&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
-more buffers to start capturing. Its counterpart
-&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
-queues. Applications can query the signal status, if known, with the
-&VIDIOC-ENUMINPUT; ioctl.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>For a more in-depth discussion of memory mapping and
-examples, see <xref linkend="mmap" />.</para>
- </section>
- </section>
-
- <section>
- <title>Reading Raw VBI Data</title>
-
- <para>Originally the V4L API did not specify a raw VBI capture
-interface, only the device file <filename>/dev/vbi</filename> was
-reserved for this purpose. The only driver supporting this interface
-was the BTTV driver, de-facto defining the V4L VBI interface. Reading
-from the device yields a raw VBI image with the following
-parameters:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>&v4l2-vbi-format;</entry>
- <entry>V4L, BTTV driver</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>sampling_rate</entry>
- <entry>28636363&nbsp;Hz NTSC (or any other 525-line
-standard); 35468950&nbsp;Hz PAL and SECAM (625-line standards)</entry>
- </row>
- <row>
- <entry>offset</entry>
- <entry>?</entry>
- </row>
- <row>
- <entry>samples_per_line</entry>
- <entry>2048</entry>
- </row>
- <row>
- <entry>sample_format</entry>
- <entry>V4L2_PIX_FMT_GREY. The last four bytes (a
-machine endianness integer) contain a frame counter.</entry>
- </row>
- <row>
- <entry>start[]</entry>
- <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry>
- </row>
- <row>
- <entry>count[]</entry>
- <entry><para>16, 16<footnote><para>Old driver
-versions used different values, eventually the custom
-<constant>BTTV_VBISIZE</constant> ioctl was added to query the
-correct values.</para></footnote></para></entry>
- </row>
- <row>
- <entry>flags</entry>
- <entry>0</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>Undocumented in the V4L specification, in Linux 2.3 the
-<constant>VIDIOCGVBIFMT</constant> and
-<constant>VIDIOCSVBIFMT</constant> ioctls using struct
-<structname>vbi_format</structname> were added to determine the VBI
-image parameters. These ioctls are only partially compatible with the
-V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
-
- <para>An <structfield>offset</structfield> field does not
-exist, <structfield>sample_format</structfield> is supposed to be
-<constant>VIDEO_PALETTE_RAW</constant>, equivalent to
-<constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are
-probably equivalent to &v4l2-vbi-format;.</para>
-
- <para>Apparently only the Zoran (ZR 36120) driver implements
-these ioctls. The semantics differ from those specified for V4L2 in two
-ways. The parameters are reset on &func-open; and
-<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
-parameters are invalid.</para>
- </section>
-
- <section>
- <title>Miscellaneous</title>
-
- <para>V4L2 has no equivalent of the
-<constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI
-device associated with a video capture device (or vice versa) by
-reopening the device and requesting VBI data. For details see
-<xref linkend="open" />.</para>
-
- <para>No replacement exists for <constant>VIDIOCKEY</constant>,
-and the V4L functions for microcode programming. A new interface for
-MPEG compression and playback devices is documented in <xref
- linkend="extended-controls" />.</para>
- </section>
-
- </section>
-
- <section id="hist-v4l2">
- <title>Changes of the V4L2 API</title>
-
- <para>Soon after the V4L API was added to the kernel it was
-criticised as too inflexible. In August 1998 Bill Dirks proposed a
-number of improvements and began to work on documentation, example
-drivers and applications. With the help of other volunteers this
-eventually became the V4L2 API, not just an extension but a
-replacement for the V4L API. However it took another four years and
-two stable kernel releases until the new API was finally accepted for
-inclusion into the kernel in its present form.</para>
-
- <section>
- <title>Early Versions</title>
- <para>1998-08-20: First version.</para>
-
- <para>1998-08-27: The &func-select; function was introduced.</para>
-
- <para>1998-09-10: New video standard interface.</para>
-
- <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl
-was replaced by the otherwise meaningless <constant>O_TRUNC</constant>
-&func-open; flag, and the aliases <constant>O_NONCAP</constant> and
-<constant>O_NOIO</constant> were defined. Applications can set this
-flag if they intend to access controls only, as opposed to capture
-applications which need exclusive access. The
-<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
-instead of flags, and the <function>video_std_construct()</function>
-helper function takes id and transmission arguments.</para>
-
- <para>1998-09-28: Revamped video standard. Made video controls
-individually enumerable.</para>
-
- <para>1998-10-02: The <structfield>id</structfield> field was
-removed from struct <structname>video_standard</structname> and the
-color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
-renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
-first draft of the Codec API was released.</para>
-
- <para>1998-11-08: Many minor changes. Most symbols have been
-renamed. Some material changes to &v4l2-capability;.</para>
-
- <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para>
-
- <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant>
-changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and
-<constant>V4L2_PIX_FMT_RGB32</constant> changed to
-<constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now
-accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
-names starting with <constant>V4L2_CID_AUDIO</constant>. The
-<constant>V4L2_MAJOR</constant> define was removed from
-<filename>videodev.h</filename> since it was only used once in the
-<filename>videodev</filename> kernel module. The
-<constant>YUV422</constant> and <constant>YUV411</constant> planar
-image formats were added.</para>
-
- <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
-video output devices were added.</para>
-
- <para>1999-01-14: A raw VBI capture interface was added.</para>
-
- <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl
- was removed.</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.16 1999-01-31</title>
- <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
-are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
-digital zoom (cropping) controls.</para>
- </section>
-
- <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill
- forgot to bump the version number or never released it. -->
-
- <section>
- <title>V4L2 Version 0.18 1999-03-16</title>
- <para>Added a v4l to V4L2 ioctl compatibility layer to
-videodev.c. Driver writers, this changes how you implement your ioctl
-handler. See the Driver Writer's Guide. Added some more control id
-codes.</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.19 1999-06-05</title>
- <para>1999-03-18: Fill in the category and catname fields of
-v4l2_queryctrl objects before passing them to the driver. Required a
-minor change to the VIDIOC_QUERYCTRL handlers in the sample
-drivers.</para>
- <para>1999-03-31: Better compatibility for v4l memory capture
-ioctls. Requires changes to drivers to fully support new compatibility
-features, see Driver Writer's Guide and v4l2cap.c. Added new control
-IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
-and _YUV411P to _YUV411P.</para>
- <para>1999-04-04: Added a few more control IDs.</para>
- <para>1999-04-07: Added the button control type.</para>
- <para>1999-05-02: Fixed a typo in videodev.h, and added the
-V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
- <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
-a malfunction of this ioctl.</para>
- <para>1999-06-05: Changed the value of
-V4L2_CID_WHITENESS.</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 (1999-09-10)</title>
-
- <para>Version 0.20 introduced a number of changes which were
-<emphasis>not backward compatible</emphasis> with 0.19 and earlier
-versions. Purpose of these changes was to simplify the API, while
-making it more extensible and following common Linux driver API
-conventions.</para>
-
- <orderedlist>
- <listitem>
- <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
-symbols were fixed. &v4l2-clip; was changed for compatibility with
-v4l. (1999-08-30)</para>
- </listitem>
-
- <listitem>
- <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added.
-(1999-09-05)</para>
- </listitem>
-
- <listitem>
- <para>All ioctl() commands that used an integer argument now
-take a pointer to an integer. Where it makes sense, ioctls will return
-the actual new value in the integer pointed to by the argument, a
-common convention in the V4L2 API. The affected ioctls are:
-VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
-VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
-<programlisting>
-err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
-</programlisting> becomes <programlisting>
-int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
-</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>All the different get- and set-format commands were
-swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
-and a type field selecting the union member as parameter. Purpose is to
-simplify the API by eliminating several ioctls and to allow new and
-driver private data streams without adding new ioctls.</para>
-
- <para>This change obsoletes the following ioctls:
-<constant>VIDIOC_S_INFMT</constant>,
-<constant>VIDIOC_G_INFMT</constant>,
-<constant>VIDIOC_S_OUTFMT</constant>,
-<constant>VIDIOC_G_OUTFMT</constant>,
-<constant>VIDIOC_S_VBIFMT</constant> and
-<constant>VIDIOC_G_VBIFMT</constant>. The image format structure
-<structname>v4l2_format</structname> was renamed to &v4l2-pix-format;,
-while &v4l2-format; is now the envelopping structure for all format
-negotiations.</para>
- </listitem>
-
- <listitem>
- <para>Similar to the changes above, the
-<constant>VIDIOC_G_PARM</constant> and
-<constant>VIDIOC_S_PARM</constant> ioctls were merged with
-<constant>VIDIOC_G_OUTPARM</constant> and
-<constant>VIDIOC_S_OUTPARM</constant>. A
-<structfield>type</structfield> field in the new &v4l2-streamparm;
-selects the respective union member.</para>
-
- <para>This change obsoletes the
-<constant>VIDIOC_G_OUTPARM</constant> and
-<constant>VIDIOC_S_OUTPARM</constant> ioctls.</para>
- </listitem>
-
- <listitem>
- <para>Control enumeration was simplified, and two new
-control flags were introduced and one dropped. The
-<structfield>catname</structfield> field was replaced by a
-<structfield>group</structfield> field.</para>
-
- <para>Drivers can now flag unsupported and temporarily
-unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
-and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
-<structfield>group</structfield> name indicates a possibly narrower
-classification than the <structfield>category</structfield>. In other
-words, there may be multiple groups within a category. Controls within
-a group would typically be drawn within a group box. Controls in
-different categories might have a greater separation, or may even
-appear in separate windows.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-buffer; <structfield>timestamp</structfield>
-was changed to a 64 bit integer, containing the sampling or output
-time of the frame in nanoseconds. Additionally timestamps will be in
-absolute system time, not starting from zero at the beginning of a
-stream. The data type name for timestamps is stamp_t, defined as a
-signed 64-bit integer. Output devices should not send a buffer out
-until the time in the timestamp field has arrived. I would like to
-follow SGI's lead, and adopt a multimedia timestamping system like
-their UST (Unadjusted System Time). See
-http://web.archive.org/web/*/http://reality.sgi.com
-/cpirazzi_engr/lg/time/intro.html.
-UST uses timestamps that are 64-bit signed integers
-(not struct timeval's) and given in nanosecond units. The UST clock
-starts at zero when the system is booted and runs continuously and
-uniformly. It takes a little over 292 years for UST to overflow. There
-is no way to set the UST clock. The regular Linux time-of-day clock
-can be changed periodically, which would cause errors if it were being
-used for timestamping a multimedia stream. A real UST style clock will
-require some support in the kernel that is not there yet. But in
-anticipation, I will change the timestamp field to a 64-bit integer,
-and I will change the v4l2_masterclock_gettime() function (used only
-by drivers) to return a 64-bit integer.</para>
- </listitem>
-
- <listitem>
- <para>A <structfield>sequence</structfield> field was added
-to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
-captured frames, it is ignored by output devices. When a capture
-driver drops a frame, the sequence number of that frame is
-skipped.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 incremental changes</title>
- <!-- Version number didn't change anymore, reason unknown. -->
-
- <para>1999-12-23: In &v4l2-vbi-format; the
-<structfield>reserved1</structfield> field became
-<structfield>offset</structfield>. Previously drivers were required to
-clear the <structfield>reserved1</structfield> field.</para>
-
- <para>2000-01-13: The
- <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para>
-
- <para>2000-07-31: The <filename>linux/poll.h</filename> header
-is now included by <filename>videodev.h</filename> for compatibility
-with the original <filename>videodev.h</filename> file.</para>
-
- <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and
-<constant>V4L2_PIX_FMT_Y41P</constant> were added.</para>
-
- <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was
-added.</para>
-
- <para>2000-12-04: A couple typos in symbol names were fixed.</para>
-
- <para>2001-01-18: To avoid namespace conflicts the
-<constant>fourcc</constant> macro defined in the
-<filename>videodev.h</filename> header file was renamed to
-<constant>v4l2_fourcc</constant>.</para>
-
- <para>2001-01-25: A possible driver-level compatibility problem
-between the <filename>videodev.h</filename> file in Linux 2.4.0 and
-the <filename>videodev.h</filename> file included in the
-<filename>videodevX</filename> patch was fixed. Users of an earlier
-version of <filename>videodevX</filename> on Linux 2.4.0 should
-recompile their V4L and V4L2 drivers.</para>
-
- <para>2001-01-26: A possible kernel-level incompatibility
-between the <filename>videodev.h</filename> file in the
-<filename>videodevX</filename> patch and the
-<filename>videodev.h</filename> file in Linux 2.2.x with devfs patches
-applied was fixed.</para>
-
- <para>2001-03-02: Certain V4L ioctls which pass data in both
-direction although they are defined with read-only parameter, did not
-work correctly through the backward compatibility layer.
-[Solution?]</para>
-
- <para>2001-04-13: Big endian 16-bit RGB formats were added.</para>
-
- <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and
-&VIDIOC-S-FREQUENCY; ioctls were added. (The old
-<constant>VIDIOC_G_FREQ</constant> and
-<constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners
-into account.)</para>
-
- <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
-added. This may <emphasis>break compatibility</emphasis> as the
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct
-<structname>v4l2_fmt</structname> <structfield>type</structfield>
-field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
-documentation of the &v4l2-vbi-format;
-<structfield>offset</structfield> field the ambiguous phrase "rising
-edge" was changed to "leading edge".</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 2000-11-23</title>
-
- <para>A number of changes were made to the raw VBI
-interface.</para>
-
- <orderedlist>
- <listitem>
- <para>Figures clarifying the line numbering scheme were
-added to the V4L2 API specification. The
-<structfield>start</structfield>[0] and
-<structfield>start</structfield>[1] fields no longer count line
-numbers beginning at zero. Rationale: a) The previous definition was
-unclear. b) The <structfield>start</structfield>[] values are ordinal
-numbers. c) There is no point in inventing a new line numbering
-scheme. We now use line number as defined by ITU-R, period.
-Compatibility: Add one to the start values. Applications depending on
-the previous semantics may not function correctly.</para>
- </listitem>
-
- <listitem>
- <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
-has been relaxed to "(count[0] + count[1]) &gt; 0". Rationale:
-Drivers may allocate resources at scan line granularity and some data
-services are transmitted only on the first field. The comment that
-both <structfield>count</structfield> values will usually be equal is
-misleading and pointless and has been removed. This change
-<emphasis>breaks compatibility</emphasis> with earlier versions:
-Drivers may return EINVAL, applications may not function
-correctly.</para>
- </listitem>
-
- <listitem>
- <para>Drivers are again permitted to return negative
-(unknown) start values as proposed earlier. Why this feature was
-dropped is unclear. This change may <emphasis>break
-compatibility</emphasis> with applications depending on the start
-values being positive. The use of <constant>EBUSY</constant> and
-<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
-was clarified. The &EBUSY; was finally documented, and the
-<structfield>reserved2</structfield> field which was previously
-mentioned only in the <filename>videodev.h</filename> header
-file.</para>
- </listitem>
-
- <listitem>
- <para>New buffer types
-<constant>V4L2_TYPE_VBI_INPUT</constant> and
-<constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an
-alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
-missing in the <filename>videodev.h</filename> file.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 2002-07-25</title>
- <para>Added sliced VBI interface proposal.</para>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.5.46, 2002-10</title>
-
- <para>Around October-November 2002, prior to an announced
-feature freeze of Linux 2.5, the API was revised, drawing from
-experience with V4L2 0.20. This unnamed version was finally merged
-into Linux 2.5.46.</para>
-
- <orderedlist>
- <listitem>
- <para>As specified in <xref linkend="related" />, drivers
-must make related device functions available under all minor device
-numbers.</para>
- </listitem>
-
- <listitem>
- <para>The &func-open; function requires access mode
-<constant>O_RDWR</constant> regardless of the device type. All V4L2
-drivers exchanging data with applications must support the
-<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
-flag, a V4L2 symbol which aliased the meaningless
-<constant>O_TRUNC</constant> to indicate accesses without data
-exchange (panel applications) was dropped. Drivers must stay in "panel
-mode" until the application attempts to initiate a data exchange, see
-<xref linkend="open" />.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-capability; changed dramatically. Note that
-also the size of the structure changed, which is encoded in the ioctl
-request code, thus older V4L2 devices will respond with an &EINVAL; to
-the new &VIDIOC-QUERYCAP; ioctl.</para>
-
- <para>There are new fields to identify the driver, a new RDS
-device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
-<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
-any audio connectors, another I/O capability
-<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
-these changes the <structfield>type</structfield> field became a bit
-set and was merged into the <structfield>flags</structfield> field.
-<constant>V4L2_FLAG_TUNER</constant> was renamed to
-<constant>V4L2_CAP_TUNER</constant>,
-<constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced
-<constant>V4L2_FLAG_PREVIEW</constant> and
-<constant>V4L2_CAP_VBI_CAPTURE</constant> and
-<constant>V4L2_CAP_VBI_OUTPUT</constant> replaced
-<constant>V4L2_FLAG_DATA_SERVICE</constant>.
-<constant>V4L2_FLAG_READ</constant> and
-<constant>V4L2_FLAG_WRITE</constant> were merged into
-<constant>V4L2_CAP_READWRITE</constant>.</para>
-
- <para>The redundant fields
-<structfield>inputs</structfield>, <structfield>outputs</structfield>
-and <structfield>audios</structfield> were removed. These properties
-can be determined as described in <xref linkend="video" /> and <xref
-linkend="audio" />.</para>
-
- <para>The somewhat volatile and therefore barely useful
-fields <structfield>maxwidth</structfield>,
-<structfield>maxheight</structfield>,
-<structfield>minwidth</structfield>,
-<structfield>minheight</structfield>,
-<structfield>maxframerate</structfield> were removed. This information
-is available as described in <xref linkend="format" /> and
-<xref linkend="standard" />.</para>
-
- <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
-believe the select() function is important enough to require support
-of it in all V4L2 drivers exchanging data with applications. The
-redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
-this information is available as described in <xref
- linkend="format" />.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-input; the
-<structfield>assoc_audio</structfield> field and the
-<structfield>capability</structfield> field and its only flag
-<constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new
-<structfield>audioset</structfield> field. Instead of linking one
-video input to one audio input this field reports all audio inputs
-this video input combines with.</para>
-
- <para>New fields are <structfield>tuner</structfield>
-(reversing the former link from tuners to video inputs),
-<structfield>std</structfield> and
-<structfield>status</structfield>.</para>
-
- <para>Accordingly &v4l2-output; lost its
-<structfield>capability</structfield> and
-<structfield>assoc_audio</structfield> fields.
-<structfield>audioset</structfield>,
-<structfield>modulator</structfield> and
-<structfield>std</structfield> where added instead.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-audio; field
-<structfield>audio</structfield> was renamed to
-<structfield>index</structfield>, for consistency with other
-structures. A new capability flag
-<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
-audio input in question supports stereo sound.
-<constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding
-<constant>V4L2_AUDMODE</constant> flags where removed. This can be
-easily implemented using controls. (However the same applies to AVL
-which is still there.)</para>
-
- <para>Again for consistency the &v4l2-audioout; field
-<structfield>audio</structfield> was renamed to
-<structfield>index</structfield>.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-tuner;
-<structfield>input</structfield> field was replaced by an
-<structfield>index</structfield> field, permitting devices with
-multiple tuners. The link between video inputs and tuners is now
-reversed, inputs point to their tuner. The
-<structfield>std</structfield> substructure became a
-simple set (more about this below) and moved into &v4l2-input;. A
-<structfield>type</structfield> field was added.</para>
-
- <para>Accordingly in &v4l2-modulator; the
-<structfield>output</structfield> was replaced by an
-<structfield>index</structfield> field.</para>
-
- <para>In &v4l2-frequency; the
-<structfield>port</structfield> field was replaced by a
-<structfield>tuner</structfield> field containing the respective tuner
-or modulator index number. A tuner <structfield>type</structfield>
-field was added and the <structfield>reserved</structfield> field
-became larger for future extensions (satellite tuners in
-particular).</para>
- </listitem>
-
- <listitem>
- <para>The idea of completely transparent video standards was
-dropped. Experience showed that applications must be able to work with
-video standards beyond presenting the user a menu. Instead of
-enumerating supported standards with an ioctl applications can now
-refer to standards by &v4l2-std-id; and symbols defined in the
-<filename>videodev2.h</filename> header file. For details see <xref
- linkend="standard" />. The &VIDIOC-G-STD; and
-&VIDIOC-S-STD; now take a pointer to this type as argument.
-&VIDIOC-QUERYSTD; was added to autodetect the received standard, if
-the hardware has this capability. In &v4l2-standard; an
-<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
-A &v4l2-std-id; field named <structfield>id</structfield> was added as
-machine readable identifier, also replacing the
-<structfield>transmission</structfield> field. The misleading
-<structfield>framerate</structfield> field was renamed
-to <structfield>frameperiod</structfield>. The now obsolete
-<structfield>colorstandard</structfield> information, originally
-needed to distguish between variations of standards, were
-removed.</para>
-
- <para>Struct <structname>v4l2_enumstd</structname> ceased to
-be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
-directly. The information which standards are supported by a
-particular video input or output moved into &v4l2-input; and
-&v4l2-output; fields named <structfield>std</structfield>,
-respectively.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-queryctrl; fields
-<structfield>category</structfield> and
-<structfield>group</structfield> did not catch on and/or were not
-implemented as expected and therefore removed.</para>
- </listitem>
-
- <listitem>
- <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
-formats as with &VIDIOC-S-FMT;, but without the overhead of
-programming the hardware and regardless of I/O in progress.</para>
-
- <para>In &v4l2-format; the <structfield>fmt</structfield>
-union was extended to contain &v4l2-window;. All image format
-negotiations are now possible with <constant>VIDIOC_G_FMT</constant>,
-<constant>VIDIOC_S_FMT</constant> and
-<constant>VIDIOC_TRY_FMT</constant>; ioctl. The
-<constant>VIDIOC_G_WIN</constant> and
-<constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video
-overlay were removed. The <structfield>type</structfield> field
-changed to type &v4l2-buf-type; and the buffer type names changed as
-follows.<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Old defines</entry>
- <entry>&v4l2-buf-type;</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant> (but this is deprecated)</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named
-<structfield>type</structfield> was added as in &v4l2-format;. The
-<constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and
-was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
-type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-pix-format; the
-<structfield>depth</structfield> field was removed, assuming
-applications which recognize the format by its four-character-code
-already know the color depth, and others do not care about it. The
-same rationale lead to the removal of the
-<constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The
-<constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed
-because drivers are not supposed to convert images in kernel space. A
-user library of conversion functions should be provided instead. The
-<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
-Applications can set the <structfield>bytesperline</structfield> field
-to zero to get a reasonable default. Since the remaining flags were
-replaced as well, the <structfield>flags</structfield> field itself
-was removed.</para>
- <para>The interlace flags were replaced by a &v4l2-field;
-value in a newly added <structfield>field</structfield>
-field.<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Old flag</entry>
- <entry>&v4l2-field;</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry>
- <entry>?</entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant>
-= <constant>V4L2_FMT_FLAG_COMBINED</constant></entry>
- <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant>
-= <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry>
- <entry><constant>V4L2_FIELD_TOP</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant>
-= <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry>
- <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>The color space flags were replaced by a
-&v4l2-colorspace; value in a newly added
-<structfield>colorspace</structfield> field, where one of
-<constant>V4L2_COLORSPACE_SMPTE170M</constant>,
-<constant>V4L2_COLORSPACE_BT878</constant>,
-<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or
-<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces
-<constant>V4L2_FMT_CS_601YUV</constant>.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-requestbuffers; the
-<structfield>type</structfield> field was properly defined as
-&v4l2-buf-type;. Buffer types changed as mentioned above. A new
-<structfield>memory</structfield> field of type &v4l2-memory; was
-added to distinguish between I/O methods using buffers allocated
-by the driver or the application. See <xref linkend="io" /> for
-details.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-buffer; the <structfield>type</structfield>
-field was properly defined as &v4l2-buf-type;. Buffer types changed as
-mentioned above. A <structfield>field</structfield> field of type
-&v4l2-field; was added to indicate if a buffer contains a top or
-bottom field. The old field flags were removed. Since no unadjusted
-system time clock was added to the kernel as planned, the
-<structfield>timestamp</structfield> field changed back from type
-stamp_t, an unsigned 64 bit integer expressing the sample time in
-nanoseconds, to struct <structname>timeval</structname>. With the
-addition of a second memory mapping method the
-<structfield>offset</structfield> field moved into union
-<structfield>m</structfield>, and a new
-<structfield>memory</structfield> field of type &v4l2-memory; was
-added to distinguish between I/O methods. See <xref linkend="io" />
-for details.</para>
-
- <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
-flag was used by the V4L compatibility layer, after changes to this
-code it was no longer needed. The
-<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
-the buffer was indeed allocated in device memory rather than DMA-able
-system memory. It was barely useful and so was removed.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-framebuffer; the
-<structfield>base[3]</structfield> array anticipating double- and
-triple-buffering in off-screen video memory, however without defining
-a synchronization mechanism, was replaced by a single pointer. The
-<constant>V4L2_FBUF_CAP_SCALEUP</constant> and
-<constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed.
-Applications can determine this capability more accurately using the
-new cropping and scaling interface. The
-<constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by
-<constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and
-<constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-clip; the <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> field moved into a
-<structfield>c</structfield> substructure of type &v4l2-rect;. The
-<structfield>x</structfield> and <structfield>y</structfield> fields
-were renamed to <structfield>left</structfield> and
-<structfield>top</structfield>, &ie; offsets to a context dependent
-origin.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-window; the <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> field moved into a
-<structfield>w</structfield> substructure as above. A
-<structfield>field</structfield> field of type %v4l2-field; was added
-to distinguish between field and frame (interlaced) overlay.</para>
- </listitem>
-
- <listitem>
- <para>The digital zoom interface, including struct
-<structname>v4l2_zoomcap</structname>, struct
-<structname>v4l2_zoom</structname>,
-<constant>V4L2_ZOOM_NONCAP</constant> and
-<constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new
-cropping and scaling interface. The previously unused struct
-<structname>v4l2_cropcap</structname> and
-<structname>v4l2_crop</structname> where redefined for this purpose.
-See <xref linkend="crop" /> for details.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-vbi-format; the
-<structfield>SAMPLE_FORMAT</structfield> field now contains a
-four-character-code as used to identify video image formats and
-<constant>V4L2_PIX_FMT_GREY</constant> replaces the
-<constant>V4L2_VBI_SF_UBYTE</constant> define. The
-<structfield>reserved</structfield> field was extended.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-captureparm; the type of the
-<structfield>timeperframe</structfield> field changed from unsigned
-long to &v4l2-fract;. This allows the accurate expression of multiples
-of the NTSC-M frame rate 30000 / 1001. A new field
-<structfield>readbuffers</structfield> was added to control the driver
-behaviour in read I/O mode.</para>
-
- <para>Similar changes were made to &v4l2-outputparm;.</para>
- </listitem>
-
- <listitem>
- <para>The struct <structname>v4l2_performance</structname>
-and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
-using the <link linkend="rw">read/write I/O method</link>, which is
-limited anyway, this information is already available to
-applications.</para>
- </listitem>
-
- <listitem>
- <para>The example transformation from RGB to YCbCr color
-space in the old V4L2 documentation was inaccurate, this has been
-corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
-0.587, and 127/112 != 255/224 --></para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 2003-06-19</title>
-
- <orderedlist>
- <listitem>
- <para>A new capability flag
-<constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior
-to this change radio devices would identify solely by having exactly one
-tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
- </listitem>
-
- <listitem>
- <para>An optional driver access priority mechanism was
-added, see <xref linkend="app-pri" /> for details.</para>
- </listitem>
-
- <listitem>
- <para>The audio input and output interface was found to be
-incomplete.</para>
- <para>Previously the &VIDIOC-G-AUDIO;
-ioctl would enumerate the available audio inputs. An ioctl to
-determine the current audio input, if more than one combines with the
-current video input, did not exist. So
-<constant>VIDIOC_G_AUDIO</constant> was renamed to
-<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on
-Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
-audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
-input.</para>
- <para>The same changes were made to &VIDIOC-G-AUDOUT; and
-&VIDIOC-ENUMAUDOUT;.</para>
- <para>Until further the "videodev" module will automatically
-translate between the old and new ioctls, but drivers and applications
-must be updated to successfully compile again.</para>
- </listitem>
-
- <listitem>
- <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
-write-read parameter. It was changed to write-only, while the write-read
-version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
-ioctl was removed on Kernel 2.6.39. Until further the "videodev"
-kernel module will automatically translate to the new version, so drivers
-must be recompiled, but not applications.</para>
- </listitem>
-
- <listitem>
- <para><xref linkend="overlay" /> incorrectly stated that
-clipping rectangles define regions where the video can be seen.
-Correct is that clipping rectangles define regions where
-<emphasis>no</emphasis> video shall be displayed and so the graphics
-surface can be seen.</para>
- </listitem>
-
- <listitem>
- <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
-defined with write-only parameter, inconsistent with other ioctls
-modifying their argument. They were changed to write-read, while a
-<constant>_OLD</constant> suffix was added to the write-only versions.
-The old ioctls were removed on Kernel 2.6.39. Drivers and
-applications assuming a constant parameter need an update.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 2003-11-05</title>
- <orderedlist>
- <listitem>
- <para>In <xref linkend="pixfmt-rgb" /> the following pixel
-formats were incorrectly transferred from Bill Dirks' V4L2
-specification. Descriptions below refer to bytes in memory, in
-ascending address order.<informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Symbol</entry>
- <entry>In this document prior to revision
-0.5</entry>
- <entry>Corrected</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
- <entry>B, G, R</entry>
- <entry>R, G, B</entry>
- </row>
- <row>
- <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
- <entry>R, G, B</entry>
- <entry>B, G, R</entry>
- </row>
- <row>
- <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
- <entry>B, G, R, X</entry>
- <entry>R, G, B, X</entry>
- </row>
- <row>
- <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
- <entry>R, G, B, X</entry>
- <entry>B, G, R, X</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable> The
-<constant>V4L2_PIX_FMT_BGR24</constant> example was always
-correct.</para>
- <para>In <xref linkend="v4l-image-properties" /> the mapping
-of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
-<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
-was accordingly corrected.</para>
- </listitem>
-
- <listitem>
- <para>Unrelated to the fixes above, drivers may still
-interpret some V4L2 RGB pixel formats differently. These issues have
-yet to be addressed, for details see <xref
- linkend="pixfmt-rgb" />.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.6, 2004-05-09</title>
- <orderedlist>
- <listitem>
- <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
-with read-only parameter. It is now defined as write-read ioctl, while
-the read-only version was renamed to
-<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed
-on Kernel 2.6.39.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.8</title>
- <orderedlist>
- <listitem>
- <para>A new field <structfield>input</structfield> (former
-<structfield>reserved[0]</structfield>) was added to the &v4l2-buffer;
-structure. Purpose of this field is to alternate between video inputs
-(&eg; cameras) in step with the video capturing process. This function
-must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
-flag. The <structfield>flags</structfield> field is no longer
-read-only.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2004-08-01</title>
-
- <orderedlist>
- <listitem>
- <para>The return value of the
-<xref linkend="func-open" /> function was incorrectly documented.</para>
- </listitem>
-
- <listitem>
- <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para>
- </listitem>
-
- <listitem>
- <para>In the Current Audio Input example the
-<constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong
-argument.</para>
- </listitem>
-
- <listitem>
- <para>The documentation of the &VIDIOC-QBUF; and
-&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer;
-<structfield>memory</structfield> field. It was also missing from
-examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
-was not documented.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.14</title>
- <orderedlist>
- <listitem>
- <para>A new sliced VBI interface was added. It is documented
-in <xref linkend="sliced" /> and replaces the interface first
-proposed in V4L2 specification 0.8.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.15</title>
- <orderedlist>
- <listitem>
- <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para>
- </listitem>
-
- <listitem>
- <para>New video standards
-<constant>V4L2_STD_NTSC_443</constant>,
-<constant>V4L2_STD_SECAM_LC</constant>,
-<constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1),
-and <constant>V4L2_STD_ATSC</constant> (a set of
-<constant>V4L2_STD_ATSC_8_VSB</constant> and
-<constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the
-<constant>V4L2_STD_525_60</constant> set now includes
-<constant>V4L2_STD_NTSC_443</constant>. See also <xref
- linkend="v4l2-std-id" />.</para>
- </listitem>
-
- <listitem>
- <para>The <constant>VIDIOC_G_COMP</constant> and
-<constant>VIDIOC_S_COMP</constant> ioctl were renamed to
-<constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument
-was replaced by a struct
-<structname>v4l2_mpeg_compression</structname> pointer. (The
-<constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux
-2.6.25.)</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2005-11-27</title>
- <para>The capture example in <xref linkend="capture-example" />
-called the &VIDIOC-S-CROP; ioctl without checking if cropping is
-supported. In the video standard selection example in
-<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
-argument type.</para>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-01-10</title>
- <orderedlist>
- <listitem>
- <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in
-&v4l2-input; not only indicates if the color killer is enabled, but
-also if it is active. (The color killer disables color decoding when
-it detects no color in the video signal to improve the image
-quality.)</para>
- </listitem>
-
- <listitem>
- <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
-stated on its reference page. The ioctl changed in 2003 as noted above.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-02-03</title>
- <orderedlist>
- <listitem>
- <para>In &v4l2-captureparm; and &v4l2-outputparm; the
-<structfield>timeperframe</structfield> field gives the time in
-seconds, not microseconds.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-02-04</title>
- <orderedlist>
- <listitem>
- <para>The <structfield>clips</structfield> field in
-&v4l2-window; must point to an array of &v4l2-clip;, not a linked
-list, because drivers ignore the struct
-<structname>v4l2_clip</structname>.<structfield>next</structfield>
-pointer.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.17</title>
- <orderedlist>
- <listitem>
- <para>New video standard macros were added:
-<constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the
-sets <constant>V4L2_STD_MN</constant>,
-<constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and
-<constant>V4L2_STD_DK</constant>. The
-<constant>V4L2_STD_NTSC</constant> and
-<constant>V4L2_STD_SECAM</constant> sets now include
-<constant>V4L2_STD_NTSC_M_KR</constant> and
-<constant>V4L2_STD_SECAM_LC</constant> respectively.</para>
- </listitem>
-
- <listitem>
- <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant>
-was defined to record both languages of a bilingual program. The
-use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
-is deprecated now. See the &VIDIOC-G-TUNER; section for
-details.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title>
- <orderedlist>
- <listitem>
- <para>In various places
-<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and
-<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI
-interface were not mentioned along with other buffer types.</para>
- </listitem>
-
- <listitem>
- <para>In <xref linkend="vidioc-g-audio" /> it was clarified
-that the &v4l2-audio; <structfield>mode</structfield> field is a flags
-field.</para>
- </listitem>
-
- <listitem>
- <para><xref linkend="vidioc-querycap" /> did not mention the
-sliced VBI and radio capability flags.</para>
- </listitem>
-
- <listitem>
- <para>In <xref linkend="vidioc-g-frequency" /> it was
-clarified that applications must initialize the tuner
-<structfield>type</structfield> field of &v4l2-frequency; before
-calling &VIDIOC-S-FREQUENCY;.</para>
- </listitem>
-
- <listitem>
- <para>The <structfield>reserved</structfield> array
-in &v4l2-requestbuffers; has 2 elements, not 32.</para>
- </listitem>
-
- <listitem>
- <para>In <xref linkend="output" /> and <xref
- linkend="raw-vbi" /> the device file names
-<filename>/dev/vout</filename> which never caught on were replaced
-by <filename>/dev/video</filename>.</para>
- </listitem>
-
- <listitem>
- <para>With Linux 2.6.15 the possible range for VBI device minor
-numbers was extended from 224-239 to 224-255. Accordingly device file names
-<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
-possible now.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.18</title>
- <orderedlist>
- <listitem>
- <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS;
-and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
-controls with &VIDIOC-QUERYCTRL;, new control types
-<constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
-<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref
- linkend="v4l2-ctrl-type" />), and new control flags
-<constant>V4L2_CTRL_FLAG_READ_ONLY</constant>,
-<constant>V4L2_CTRL_FLAG_UPDATE</constant>,
-<constant>V4L2_CTRL_FLAG_INACTIVE</constant> and
-<constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref
- linkend="control-flags" />). See <xref
- linkend="extended-controls" /> for details.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.19</title>
- <orderedlist>
- <listitem>
- <para>In &v4l2-sliced-vbi-cap; a buffer type field was added
-replacing a reserved field. Note on architectures where the size of
-enum types differs from int types the size of the structure changed.
-The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
-to write-read. Applications must initialize the type field and clear
-the reserved fields now. These changes may <emphasis>break the
-compatibility</emphasis> with older drivers and applications.</para>
- </listitem>
-
- <listitem>
- <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and
-&VIDIOC-ENUM-FRAMEINTERVALS; were added.</para>
- </listitem>
-
- <listitem>
- <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref
-linkend="rgb-formats" />) was added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title>
- <orderedlist>
- <listitem>
- <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref
-linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.21</title>
- <orderedlist>
- <listitem>
- <para>The <filename>videodev2.h</filename> header file is
-now dual licensed under GNU General Public License version two or
-later, and under a 3-clause BSD-style license.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.22</title>
- <orderedlist>
- <listitem>
- <para>Two new field orders
- <constant>V4L2_FIELD_INTERLACED_TB</constant> and
- <constant>V4L2_FIELD_INTERLACED_BT</constant> were
- added. See <xref linkend="v4l2-field" /> for details.</para>
- </listitem>
-
- <listitem>
- <para>Three new clipping/blending methods with a global or
-straight or inverted local alpha value were added to the video overlay
-interface. See the description of the &VIDIOC-G-FBUF; and
-&VIDIOC-S-FBUF; ioctls for details.</para>
- <para>A new <structfield>global_alpha</structfield> field
-was added to <link
-linkend="v4l2-window"><structname>v4l2_window</structname></link>,
-extending the structure. This may <emphasis>break
-compatibility</emphasis> with applications using a struct
-<structname>v4l2_window</structname> directly. However the <link
-linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
-pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
-structure with padding bytes at the end, are not affected.</para>
- </listitem>
-
- <listitem>
- <para>The format of the <structfield>chromakey</structfield>
-field in &v4l2-window; changed from "host order RGB32" to a pixel
-value in the same format as the framebuffer. This may <emphasis>break
-compatibility</emphasis> with existing applications. Drivers
-supporting the "host order RGB32" format are not known.</para>
- </listitem>
-
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.24</title>
- <orderedlist>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_PAL8</constant>,
-<constant>V4L2_PIX_FMT_YUV444</constant>,
-<constant>V4L2_PIX_FMT_YUV555</constant>,
-<constant>V4L2_PIX_FMT_YUV565</constant> and
-<constant>V4L2_PIX_FMT_YUV32</constant> were added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.25</title>
- <orderedlist>
- <listitem>
- <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16">
-<constant>V4L2_PIX_FMT_Y16</constant></link> and <link
-linkend="V4L2-PIX-FMT-SBGGR16">
-<constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para>
- </listitem>
- <listitem>
- <para>New <link linkend="control">controls</link>
-<constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>,
-<constant>V4L2_CID_HUE_AUTO</constant>,
-<constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>,
-<constant>V4L2_CID_SHARPNESS</constant> and
-<constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The
-controls <constant>V4L2_CID_BLACK_LEVEL</constant>,
-<constant>V4L2_CID_WHITENESS</constant>,
-<constant>V4L2_CID_HCENTER</constant> and
-<constant>V4L2_CID_VCENTER</constant> were deprecated.
-</para>
- </listitem>
- <listitem>
- <para>A <link linkend="camera-controls">Camera controls
-class</link> was added, with the new controls
-<constant>V4L2_CID_EXPOSURE_AUTO</constant>,
-<constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>,
-<constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>,
-<constant>V4L2_CID_PAN_RELATIVE</constant>,
-<constant>V4L2_CID_TILT_RELATIVE</constant>,
-<constant>V4L2_CID_PAN_RESET</constant>,
-<constant>V4L2_CID_TILT_RESET</constant>,
-<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
-<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
-<constant>V4L2_CID_FOCUS_ABSOLUTE</constant>,
-<constant>V4L2_CID_FOCUS_RELATIVE</constant> and
-<constant>V4L2_CID_FOCUS_AUTO</constant>.</para>
- </listitem>
- <listitem>
- <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded
-by the <link linkend="extended-controls">extended controls</link>
-interface in Linux 2.6.18, where finally removed from the
-<filename>videodev2.h</filename> header file.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.26</title>
- <orderedlist>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_Y16</constant> and
-<constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para>
- </listitem>
- <listitem>
- <para>Added user controls
-<constant>V4L2_CID_CHROMA_AGC</constant> and
-<constant>V4L2_CID_COLOR_KILLER</constant>.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.27</title>
- <orderedlist>
- <listitem>
- <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the
-<constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para>
- </listitem>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_YVYU</constant>,
-<constant>V4L2_PIX_FMT_PCA501</constant>,
-<constant>V4L2_PIX_FMT_PCA505</constant>,
-<constant>V4L2_PIX_FMT_PCA508</constant>,
-<constant>V4L2_PIX_FMT_PCA561</constant>,
-<constant>V4L2_PIX_FMT_SGBRG8</constant>,
-<constant>V4L2_PIX_FMT_PAC207</constant> and
-<constant>V4L2_PIX_FMT_PJPG</constant> were added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.28</title>
- <orderedlist>
- <listitem>
- <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and
-<constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para>
- </listitem>
- <listitem>
- <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG
-video encoding.</para>
- </listitem>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_SGRBG10</constant> and
-<constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.29</title>
- <orderedlist>
- <listitem>
- <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed
-to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and <constant>VIDIOC_DBG_G_CHIP_IDENT</constant>
-was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
-was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para>
- </listitem>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_VYUY</constant>,
-<constant>V4L2_PIX_FMT_NV16</constant> and
-<constant>V4L2_PIX_FMT_NV61</constant> were added.</para>
- </listitem>
- <listitem>
- <para>Added camera controls
-<constant>V4L2_CID_ZOOM_ABSOLUTE</constant>,
-<constant>V4L2_CID_ZOOM_RELATIVE</constant>,
-<constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and
-<constant>V4L2_CID_PRIVACY</constant>.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.30</title>
- <orderedlist>
- <listitem>
- <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para>
- </listitem>
- <listitem>
- <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.32</title>
- <orderedlist>
- <listitem>
- <para>In order to be easier to compare a V4L2 API and a kernel
-version, now V4L2 API is numbered using the Linux Kernel version numeration.</para>
- </listitem>
- <listitem>
- <para>Finalized the RDS capture API. See <xref linkend="rds" /> for
-more information.</para>
- </listitem>
- <listitem>
- <para>Added new capabilities for modulators and RDS encoders.</para>
- </listitem>
- <listitem>
- <para>Add description for libv4l API.</para>
- </listitem>
- <listitem>
- <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para>
- </listitem>
- <listitem>
- <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para>
- </listitem>
- <listitem>
- <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para>
- </listitem>
-<listitem>
- <para>Added FM Receiver (FM RX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_RX</constant> and their Control IDs.</para>
- </listitem>
- <listitem>
- <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.33</title>
- <orderedlist>
- <listitem>
- <para>Added support for Digital Video timings in order to support HDTV receivers and transmitters.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.34</title>
- <orderedlist>
- <listitem>
- <para>Added
-<constant>V4L2_CID_IRIS_ABSOLUTE</constant> and
-<constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the
- <link linkend="camera-controls">Camera controls class</link>.
- </para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.37</title>
- <orderedlist>
- <listitem>
- <para>Remove the vtx (videotext/teletext) API. This API was no longer
-used and no hardware exists to verify the API. Nor were any userspace applications found
-that used it. It was originally scheduled for removal in 2.6.35.
- </para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.39</title>
- <orderedlist>
- <listitem>
- <para>The old VIDIOC_*_OLD symbols and V4L1 support were removed.</para>
- </listitem>
- <listitem>
- <para>Multi-planar API added. Does not affect the compatibility of
- current drivers and applications. See
- <link linkend="planar-apis">multi-planar API</link>
- for details.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 3.1</title>
- <orderedlist>
- <listitem>
- <para>VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.</para>
- <para>Standardize an error code for invalid ioctl.</para>
- <para>Added V4L2_CTRL_TYPE_BITMASK.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 3.2</title>
- <orderedlist>
- <listitem>
- <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para>
- </listitem>
- <listitem>
- <para>Add selection API for extended control over cropping
- and composing. Does not affect the compatibility of current
- drivers and applications. See <link
- linkend="selection-api"> selection API </link> for
- details.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.3</title>
- <orderedlist>
- <listitem>
- <para>Added <constant>V4L2_CID_ALPHA_COMPONENT</constant> control
- to the <link linkend="control">User controls class</link>.
- </para>
- </listitem>
- <listitem>
- <para>Added the device_caps field to struct v4l2_capabilities and added the new
- V4L2_CAP_DEVICE_CAPS capability.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.4</title>
- <orderedlist>
- <listitem>
- <para>Added <link linkend="jpeg-controls">JPEG compression control
- class</link>.</para>
- </listitem>
- <listitem>
- <para>Extended the DV Timings API:
- &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
- &VIDIOC-DV-TIMINGS-CAP;.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.5</title>
- <orderedlist>
- <listitem>
- <para>Added integer menus, the new type will be
- V4L2_CTRL_TYPE_INTEGER_MENU.</para>
- </listitem>
- <listitem>
- <para>Added selection API for V4L2 subdev interface:
- &VIDIOC-SUBDEV-G-SELECTION; and
- &VIDIOC-SUBDEV-S-SELECTION;.</para>
- </listitem>
- <listitem>
- <para> Added <constant>V4L2_COLORFX_ANTIQUE</constant>,
- <constant>V4L2_COLORFX_ART_FREEZE</constant>,
- <constant>V4L2_COLORFX_AQUA</constant>,
- <constant>V4L2_COLORFX_SILHOUETTE</constant>,
- <constant>V4L2_COLORFX_SOLARIZATION</constant>,
- <constant>V4L2_COLORFX_VIVID</constant> and
- <constant>V4L2_COLORFX_ARBITRARY_CBCR</constant> menu items
- to the <constant>V4L2_CID_COLORFX</constant> control.</para>
- </listitem>
- <listitem>
- <para> Added <constant>V4L2_CID_COLORFX_CBCR</constant> control.</para>
- </listitem>
- <listitem>
- <para> Added camera controls <constant>V4L2_CID_AUTO_EXPOSURE_BIAS</constant>,
- <constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>,
- <constant>V4L2_CID_IMAGE_STABILIZATION</constant>,
- <constant>V4L2_CID_ISO_SENSITIVITY</constant>,
- <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>,
- <constant>V4L2_CID_EXPOSURE_METERING</constant>,
- <constant>V4L2_CID_SCENE_MODE</constant>,
- <constant>V4L2_CID_3A_LOCK</constant>,
- <constant>V4L2_CID_AUTO_FOCUS_START</constant>,
- <constant>V4L2_CID_AUTO_FOCUS_STOP</constant>,
- <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> and
- <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.6</title>
- <orderedlist>
- <listitem>
- <para>Replaced <structfield>input</structfield> in
- <structname>v4l2_buffer</structname> by
- <structfield>reserved2</structfield> and removed
- <constant>V4L2_BUF_FLAG_INPUT</constant>.</para>
- </listitem>
- <listitem>
- <para>Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities.</para>
- </listitem>
- <listitem>
- <para>Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.9</title>
- <orderedlist>
- <listitem>
- <para>Added timestamp types to
- <structfield>flags</structfield> field in
- <structname>v4l2_buffer</structname>. See <xref
- linkend="buffer-flags" />.</para>
- </listitem>
- <listitem>
- <para>Added <constant>V4L2_EVENT_CTRL_CH_RANGE</constant> control event
- changes flag. See <xref linkend="ctrl-changes-flags"/>.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.10</title>
- <orderedlist>
- <listitem>
- <para>Removed obsolete and unused DV_PRESET ioctls
- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
- VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability
- flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
- </para>
- </listitem>
- <listitem>
- <para>Added new debugging ioctl &VIDIOC-DBG-G-CHIP-INFO;.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.11</title>
- <orderedlist>
- <listitem>
- <para>Remove obsolete <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> ioctl.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.14</title>
- <orderedlist>
- <listitem>
- <para> In struct <structname>v4l2_rect</structname>, the type
-of <structfield>width</structfield> and <structfield>height</structfield>
-fields changed from _s32 to _u32.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.15</title>
- <orderedlist>
- <listitem>
- <para>Added Software Defined Radio (SDR) Interface.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.16</title>
- <orderedlist>
- <listitem>
- <para>Added event V4L2_EVENT_SOURCE_CHANGE.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.17</title>
- <orderedlist>
- <listitem>
- <para>Extended &v4l2-pix-format;. Added format flags.
- </para>
- </listitem>
- <listitem>
- <para>Added compound control types and &VIDIOC-QUERY-EXT-CTRL;.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.18</title>
- <orderedlist>
- <listitem>
- <para>Added <constant>V4L2_CID_PAN_SPEED</constant> and
- <constant>V4L2_CID_TILT_SPEED</constant> camera controls.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.19</title>
- <orderedlist>
- <listitem>
- <para>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding;
-and &v4l2-quantization; fields to &v4l2-pix-format;, &v4l2-pix-format-mplane;
-and &v4l2-mbus-framefmt;.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="other">
- <title>Relation of V4L2 to other Linux multimedia APIs</title>
-
- <section id="xvideo">
- <title>X Video Extension</title>
-
- <para>The X Video Extension (abbreviated XVideo or just Xv) is
-an extension of the X Window system, implemented for example by the
-XFree86 project. Its scope is similar to V4L2, an API to video capture
-and output devices for X clients. Xv allows applications to display
-live video in a window, send window contents to a TV output, and
-capture or output still images in XPixmaps<footnote>
- <para>This is not implemented in XFree86.</para>
- </footnote>. With their implementation XFree86 makes the
-extension available across many operating systems and
-architectures.</para>
-
- <para>Because the driver is embedded into the X server Xv has a
-number of advantages over the V4L2 <link linkend="overlay">video
-overlay interface</link>. The driver can easily determine the overlay
-target, &ie; visible graphics memory or off-screen buffers for a
-destructive overlay. It can program the RAMDAC for a non-destructive
-overlay, scaling or color-keying, or the clipping functions of the
-video capture hardware, always in sync with drawing operations or
-windows moving or changing their stacking order.</para>
-
- <para>To combine the advantages of Xv and V4L a special Xv
-driver exists in XFree86 and XOrg, just programming any overlay capable
-Video4Linux device it finds. To enable it
-<filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
- <para><screen>
-Section "Module"
- Load "v4l"
-EndSection</screen></para>
-
- <para>As of XFree86 4.2 this driver still supports only V4L
-ioctls, however it should work just fine with all V4L2 devices through
-the V4L2 backward-compatibility layer. Since V4L2 permits multiple
-opens it is possible (if supported by the V4L2 driver) to capture
-video while an X client requested video overlay. Restrictions of
-simultaneous capturing and overlay are discussed in <xref
- linkend="overlay" /> apply.</para>
-
- <para>Only marginally related to V4L2, XFree86 extended Xv to
-support hardware YUV to RGB conversion and scaling for faster video
-playback, and added an interface to MPEG-2 decoding hardware. This API
-is useful to display images captured with V4L2 devices.</para>
- </section>
-
- <section>
- <title>Digital Video</title>
-
- <para>V4L2 does not support digital terrestrial, cable or
-satellite broadcast. A separate project aiming at digital receivers
-exists. You can find its homepage at <ulink
-url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
-has no connection to the V4L2 API except that drivers for hybrid
-hardware may support both.</para>
- </section>
-
- <section>
- <title>Audio Interfaces</title>
-
- <para>[to do - OSS/ALSA]</para>
- </section>
- </section>
-
- <section id="experimental">
- <title>Experimental API Elements</title>
-
- <para>The following V4L2 API elements are currently experimental
-and may change in the future.</para>
-
- <itemizedlist>
- <listitem>
- <para>Video Output Overlay (OSD) Interface, <xref
- linkend="osd" />.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
-ioctls.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-DBG-G-CHIP-INFO; ioctl.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
- &VIDIOC-DV-TIMINGS-CAP; ioctls.</para>
- </listitem>
- <listitem>
- <para>Flash API. <xref linkend="flash-controls" /></para>
- </listitem>
- <listitem>
- <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para>
- </listitem>
- <listitem>
- <para>Selection API. <xref linkend="selection-api" /></para>
- </listitem>
- <listitem>
- <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION;
- and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para>
- </listitem>
- <listitem>
- <para>Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl.</para>
- </listitem>
- <listitem>
- <para>Vendor and device specific media bus pixel formats.
- <xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para>
- </listitem>
- <listitem>
- <para>Importing DMABUF file descriptors as a new IO method described
- in <xref linkend="dmabuf" />.</para>
- </listitem>
- <listitem>
- <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para>
- </listitem>
- <listitem>
- <para>Software Defined Radio (SDR) Interface, <xref linkend="sdr" />.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="obsolete">
- <title>Obsolete API Elements</title>
-
- <para>The following V4L2 API elements were superseded by new
-interfaces and should not be implemented in new drivers.</para>
-
- <itemizedlist>
- <listitem>
- <para><constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
-<xref linkend="extended-controls" />.</para>
- </listitem>
- <listitem>
- <para>VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_ENUM_DV_PRESETS and
- VIDIOC_QUERY_DV_PRESET ioctls. Use the DV Timings API (<xref linkend="dv-timings" />).</para>
- </listitem>
- <listitem>
- <para><constant>VIDIOC_SUBDEV_G_CROP</constant> and
- <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctls. Use
- <constant>VIDIOC_SUBDEV_G_SELECTION</constant> and
- <constant>VIDIOC_SUBDEV_S_SELECTION</constant>, <xref
- linkend="vidioc-subdev-g-selection" />.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml
deleted file mode 100644
index 4e9462f1ab4c..000000000000
--- a/Documentation/DocBook/media/v4l/controls.xml
+++ /dev/null
@@ -1,5464 +0,0 @@
- <section id="control">
- <title>User Controls</title>
-
- <para>Devices typically have a number of user-settable controls
-such as brightness, saturation and so on, which would be presented to
-the user on a graphical user interface. But, different devices
-will have different controls available, and furthermore, the range of
-possible values, and the default value will vary from device to
-device. The control ioctls provide the information and a mechanism to
-create a nice user interface for these controls that will work
-correctly with any device.</para>
-
- <para>All controls are accessed using an ID value. V4L2 defines
-several IDs for specific purposes. Drivers can also implement their
-own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
-<footnote><para>The use of <constant>V4L2_CID_PRIVATE_BASE</constant>
-is problematic because different drivers may use the same
-<constant>V4L2_CID_PRIVATE_BASE</constant> ID for different controls.
-This makes it hard to programatically set such controls since the meaning
-of the control with that ID is driver dependent. In order to resolve this
-drivers use unique IDs and the <constant>V4L2_CID_PRIVATE_BASE</constant>
-IDs are mapped to those unique IDs by the kernel. Consider these
-<constant>V4L2_CID_PRIVATE_BASE</constant> IDs as aliases to the real
-IDs.</para>
-<para>Many applications today still use the <constant>V4L2_CID_PRIVATE_BASE</constant>
-IDs instead of using &VIDIOC-QUERYCTRL; with the <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>
-flag to enumerate all IDs, so support for <constant>V4L2_CID_PRIVATE_BASE</constant>
-is still around.</para></footnote>
-and higher values. The pre-defined control IDs have the prefix
-<constant>V4L2_CID_</constant>, and are listed in <xref
-linkend="control-id" />. The ID is used when querying the attributes of
-a control, and when getting or setting the current value.</para>
-
- <para>Generally applications should present controls to the user
-without assumptions about their purpose. Each control comes with a
-name string the user is supposed to understand. When the purpose is
-non-intuitive the driver writer should provide a user manual, a user
-interface plug-in or a driver specific panel application. Predefined
-IDs were introduced to change a few controls programmatically, for
-example to mute a device during a channel switch.</para>
-
- <para>Drivers may enumerate different controls after switching
-the current video input or output, tuner or modulator, or audio input
-or output. Different in the sense of other bounds, another default and
-current value, step size or other menu items. A control with a certain
-<emphasis>custom</emphasis> ID can also change name and
-type.</para>
-
- <para>If a control is not applicable to the current configuration
-of the device (for example, it doesn't apply to the current video input)
-drivers set the <constant>V4L2_CTRL_FLAG_INACTIVE</constant> flag.</para>
-
- <para>Control values are stored globally, they do not
-change when switching except to stay within the reported bounds. They
-also do not change &eg; when the device is opened or closed, when the
-tuner radio frequency is changed or generally never without
-application request.</para>
-
- <para>V4L2 specifies an event mechanism to notify applications
-when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event
-<constant>V4L2_EVENT_CTRL</constant>), panel applications might want to make
-use of that in order to always reflect the correct control value.</para>
-
- <para>
- All controls use machine endianness.
- </para>
-
- <table pgwide="1" frame="none" id="control-id">
- <title>Control IDs</title>
- <tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry>ID</entry>
- <entry>Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_BASE</constant></entry>
- <entry></entry>
- <entry>First predefined ID, equal to
-<constant>V4L2_CID_BRIGHTNESS</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_USER_BASE</constant></entry>
- <entry></entry>
- <entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
- <entry>integer</entry>
- <entry>Picture brightness, or more precisely, the black
-level.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_CONTRAST</constant></entry>
- <entry>integer</entry>
- <entry>Picture contrast or luma gain.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_SATURATION</constant></entry>
- <entry>integer</entry>
- <entry>Picture color saturation or chroma gain.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HUE</constant></entry>
- <entry>integer</entry>
- <entry>Hue or color balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
- <entry>integer</entry>
- <entry>Overall audio volume. Note some drivers also
-provide an OSS or ALSA mixer interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
- <entry>integer</entry>
- <entry>Audio stereo balance. Minimum corresponds to all
-the way left, maximum to right.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
- <entry>integer</entry>
- <entry>Audio bass adjustment.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
- <entry>integer</entry>
- <entry>Audio treble adjustment.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry>
- <entry>boolean</entry>
- <entry>Mute audio, &ie; set the volume to zero, however
-without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like
-ALSA drivers, V4L2 drivers must mute at load time to avoid excessive
-noise. Actually the entire device should be reset to a low power
-consumption state.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry>
- <entry>boolean</entry>
- <entry>Loudness mode (bass boost).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry>
- <entry>integer</entry>
- <entry>Another name for brightness (not a synonym of
-<constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated
-and should not be used in new drivers and applications.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry>
- <entry>boolean</entry>
- <entry>Automatic white balance (cameras).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry>
- <entry>button</entry>
- <entry>This is an action control. When set (the value is
-ignored), the device will do a white balance and then hold the current
-setting. Contrast this with the boolean
-<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when
-activated, keeps adjusting the white balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_RED_BALANCE</constant></entry>
- <entry>integer</entry>
- <entry>Red chroma balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry>
- <entry>integer</entry>
- <entry>Blue chroma balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_GAMMA</constant></entry>
- <entry>integer</entry>
- <entry>Gamma adjust.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_WHITENESS</constant></entry>
- <entry>integer</entry>
- <entry>Whiteness for grey-scale devices. This is a synonym
-for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated
-and should not be used in new drivers and applications.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_EXPOSURE</constant></entry>
- <entry>integer</entry>
- <entry>Exposure (cameras). [Unit?]</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUTOGAIN</constant></entry>
- <entry>boolean</entry>
- <entry>Automatic gain/exposure control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_GAIN</constant></entry>
- <entry>integer</entry>
- <entry>Gain control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HFLIP</constant></entry>
- <entry>boolean</entry>
- <entry>Mirror the picture horizontally.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_VFLIP</constant></entry>
- <entry>boolean</entry>
- <entry>Mirror the picture vertically.</entry>
- </row>
- <row id="v4l2-power-line-frequency">
- <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry>
- <entry>enum</entry>
- <entry>Enables a power line frequency filter to avoid
-flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are:
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0),
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1),
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2) and
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_AUTO</constant> (3).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HUE_AUTO</constant></entry>
- <entry>boolean</entry>
- <entry>Enables automatic hue control by the device. The
-effect of setting <constant>V4L2_CID_HUE</constant> while automatic
-hue control is enabled is undefined, drivers should ignore such
-request.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry>
- <entry>integer</entry>
- <entry>This control specifies the white balance settings
-as a color temperature in Kelvin. A driver should have a minimum of
-2800 (incandescent) to 6500 (daylight). For more information about
-color temperature see <ulink
-url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_SHARPNESS</constant></entry>
- <entry>integer</entry>
- <entry>Adjusts the sharpness filters in a camera. The
-minimum value disables the filters, higher values give a sharper
-picture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry>
- <entry>integer</entry>
- <entry>Adjusts the backlight compensation in a camera. The
-minimum value disables backlight compensation.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_CHROMA_AGC</constant></entry>
- <entry>boolean</entry>
- <entry>Chroma automatic gain control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry>
- <entry>integer</entry>
- <entry>Adjusts the Chroma gain control (for use when chroma AGC
- is disabled).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry>
- <entry>boolean</entry>
- <entry>Enable the color killer (&ie; force a black &amp; white image in case of a weak video signal).</entry>
- </row>
- <row id="v4l2-colorfx">
- <entry><constant>V4L2_CID_COLORFX</constant></entry>
- <entry>enum</entry>
- <entry>Selects a color effect. The following values are defined:
- </entry>
- </row><row>
- <entry></entry>
- <entry></entry>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_COLORFX_NONE</constant>&nbsp;</entry>
- <entry>Color effect is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_ANTIQUE</constant>&nbsp;</entry>
- <entry>An aging (old photo) effect.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_ART_FREEZE</constant>&nbsp;</entry>
- <entry>Frost color effect.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_AQUA</constant>&nbsp;</entry>
- <entry>Water color, cool tone.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_BW</constant>&nbsp;</entry>
- <entry>Black and white.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_EMBOSS</constant>&nbsp;</entry>
- <entry>Emboss, the highlights and shadows replace light/dark boundaries
- and low contrast areas are set to a gray background.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_GRASS_GREEN</constant>&nbsp;</entry>
- <entry>Grass green.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_NEGATIVE</constant>&nbsp;</entry>
- <entry>Negative.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SEPIA</constant>&nbsp;</entry>
- <entry>Sepia tone.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SKETCH</constant>&nbsp;</entry>
- <entry>Sketch.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SKIN_WHITEN</constant>&nbsp;</entry>
- <entry>Skin whiten.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SKY_BLUE</constant>&nbsp;</entry>
- <entry>Sky blue.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SOLARIZATION</constant>&nbsp;</entry>
- <entry>Solarization, the image is partially reversed in tone,
- only color values above or below a certain threshold are inverted.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SILHOUETTE</constant>&nbsp;</entry>
- <entry>Silhouette (outline).</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_VIVID</constant>&nbsp;</entry>
- <entry>Vivid colors.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SET_CBCR</constant>&nbsp;</entry>
- <entry>The Cb and Cr chroma components are replaced by fixed
- coefficients determined by <constant>V4L2_CID_COLORFX_CBCR</constant>
- control.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry><constant>V4L2_CID_COLORFX_CBCR</constant></entry>
- <entry>integer</entry>
- <entry>Determines the Cb and Cr coefficients for <constant>V4L2_COLORFX_SET_CBCR</constant>
- color effect. Bits [7:0] of the supplied 32 bit value are interpreted as
- Cr component, bits [15:8] as Cb component and bits [31:16] must be zero.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUTOBRIGHTNESS</constant></entry>
- <entry>boolean</entry>
- <entry>Enable Automatic Brightness.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_ROTATE</constant></entry>
- <entry>integer</entry>
- <entry>Rotates the image by specified angle. Common angles are 90,
- 270 and 180. Rotating the image to 90 and 270 will reverse the height
- and width of the display window. It is necessary to set the new height and
- width of the picture using the &VIDIOC-S-FMT; ioctl according to
- the rotation angle selected.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BG_COLOR</constant></entry>
- <entry>integer</entry>
- <entry>Sets the background color on the current output device.
- Background color needs to be specified in the RGB24 format. The
- supplied 32 bit value is interpreted as bits 0-7 Red color information,
- bits 8-15 Green color information, bits 16-23 Blue color
- information and bits 24-31 must be zero.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_ILLUMINATORS_1</constant>
- <constant>V4L2_CID_ILLUMINATORS_2</constant></entry>
- <entry>boolean</entry>
- <entry>Switch on or off the illuminator 1 or 2 of the device
- (usually a microscope).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry>
- <entry>integer</entry>
- <entry>This is a read-only control that can be read by the application
-and used as a hint to determine the number of CAPTURE buffers to pass to REQBUFS.
-The value is the minimum number of CAPTURE buffers that is necessary for hardware
-to work.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_OUTPUT</constant></entry>
- <entry>integer</entry>
- <entry>This is a read-only control that can be read by the application
-and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS.
-The value is the minimum number of OUTPUT buffers that is necessary for hardware
-to work.</entry>
- </row>
- <row id="v4l2-alpha-component">
- <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry>
- <entry>integer</entry>
- <entry>Sets the alpha color component. When a capture device (or
- capture queue of a mem-to-mem device) produces a frame format that
- includes an alpha component
- (e.g. <link linkend="rgb-formats">packed RGB image formats</link>)
- and the alpha value is not defined by the device or the mem-to-mem
- input data this control lets you select the alpha component value of
- all pixels. When an output device (or output queue of a mem-to-mem
- device) consumes a frame format that doesn't include an alpha
- component and the device supports alpha channel processing this
- control lets you set the alpha component value of all pixels for
- further processing in the device.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_LASTP1</constant></entry>
- <entry></entry>
- <entry>End of the predefined control IDs (currently
- <constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry>
- <entry></entry>
- <entry>ID of the first custom (driver specific) control.
-Applications depending on particular custom controls should check the
-driver name and version, see <xref linkend="querycap" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Applications can enumerate the available controls with the
-&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a
-control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.
-Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
-<constant>VIDIOC_G_CTRL</constant> and
-<constant>VIDIOC_S_CTRL</constant> when the device has one or more
-controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
-more menu type controls.</para>
-
- <example id="enum_all_controls">
- <title>Enumerating all user controls</title>
-
- <programlisting>
-&v4l2-queryctrl; queryctrl;
-&v4l2-querymenu; querymenu;
-
-static void enumerate_menu(void)
-{
- printf(" Menu items:\n");
-
- memset(&amp;querymenu, 0, sizeof(querymenu));
- querymenu.id = queryctrl.id;
-
- for (querymenu.index = queryctrl.minimum;
- querymenu.index &lt;= queryctrl.maximum;
- querymenu.index++) {
- if (0 == ioctl(fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
- printf(" %s\n", querymenu.name);
- }
- }
-}
-
-memset(&amp;queryctrl, 0, sizeof(queryctrl));
-
-for (queryctrl.id = V4L2_CID_BASE;
- queryctrl.id &lt; V4L2_CID_LASTP1;
- queryctrl.id++) {
- if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf("Control %s\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu();
- } else {
- if (errno == EINVAL)
- continue;
-
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- }
-}
-
-for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
- queryctrl.id++) {
- if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf("Control %s\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu();
- } else {
- if (errno == EINVAL)
- break;
-
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- }
-}
-</programlisting>
- </example>
-
- <example>
- <title>Enumerating all user controls (alternative)</title>
- <programlisting>
-memset(&amp;queryctrl, 0, sizeof(queryctrl));
-
-queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
-while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
- break;
- if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf("Control %s\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu();
-
- queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
-}
-if (errno != EINVAL) {
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
-}
-</programlisting>
- </example>
-
- <example>
- <title>Changing controls</title>
-
- <programlisting>
-&v4l2-queryctrl; queryctrl;
-&v4l2-control; control;
-
-memset(&amp;queryctrl, 0, sizeof(queryctrl));
-queryctrl.id = V4L2_CID_BRIGHTNESS;
-
-if (-1 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (errno != EINVAL) {
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- } else {
- printf("V4L2_CID_BRIGHTNESS is not supported\n");
- }
-} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) {
- printf("V4L2_CID_BRIGHTNESS is not supported\n");
-} else {
- memset(&amp;control, 0, sizeof (control));
- control.id = V4L2_CID_BRIGHTNESS;
- control.value = queryctrl.default_value;
-
- if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &amp;control)) {
- perror("VIDIOC_S_CTRL");
- exit(EXIT_FAILURE);
- }
-}
-
-memset(&amp;control, 0, sizeof(control));
-control.id = V4L2_CID_CONTRAST;
-
-if (0 == ioctl(fd, &VIDIOC-G-CTRL;, &amp;control)) {
- control.value += 1;
-
- /* The driver may clamp the value or return ERANGE, ignored here */
-
- if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &amp;control)
- &amp;&amp; errno != ERANGE) {
- perror("VIDIOC_S_CTRL");
- exit(EXIT_FAILURE);
- }
-/* Ignore if V4L2_CID_CONTRAST is unsupported */
-} else if (errno != EINVAL) {
- perror("VIDIOC_G_CTRL");
- exit(EXIT_FAILURE);
-}
-
-control.id = V4L2_CID_AUDIO_MUTE;
-control.value = 1; /* silence */
-
-/* Errors ignored */
-ioctl(fd, VIDIOC_S_CTRL, &amp;control);
-</programlisting>
- </example>
- </section>
-
- <section id="extended-controls">
- <title>Extended Controls</title>
-
- <section>
- <title>Introduction</title>
-
- <para>The control mechanism as originally designed was meant
-to be used for user settings (brightness, saturation, etc). However,
-it turned out to be a very useful model for implementing more
-complicated driver APIs where each driver implements only a subset of
-a larger API.</para>
-
- <para>The MPEG encoding API was the driving force behind
-designing and implementing this extended control mechanism: the MPEG
-standard is quite large and the currently supported hardware MPEG
-encoders each only implement a subset of this standard. Further more,
-many parameters relating to how the video is encoded into an MPEG
-stream are specific to the MPEG encoding chip since the MPEG standard
-only defines the format of the resulting MPEG stream, not how the
-video is actually encoded into that format.</para>
-
- <para>Unfortunately, the original control API lacked some
-features needed for these new uses and so it was extended into the
-(not terribly originally named) extended control API.</para>
-
- <para>Even though the MPEG encoding API was the first effort
-to use the Extended Control API, nowadays there are also other classes
-of Extended Controls, such as Camera Controls and FM Transmitter Controls.
-The Extended Controls API as well as all Extended Controls classes are
-described in the following text.</para>
- </section>
-
- <section>
- <title>The Extended Control API</title>
-
- <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;,
-&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on
-arrays of controls (as opposed to the &VIDIOC-G-CTRL; and
-&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed
-since it is often required to atomically change several controls at
-once.</para>
-
- <para>Each of the new ioctls expects a pointer to a
-&v4l2-ext-controls;. This structure contains a pointer to the control
-array, a count of the number of controls in that array and a control
-class. Control classes are used to group similar controls into a
-single class. For example, control class
-<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls
-(&ie; all controls that can also be set using the old
-<constant>VIDIOC_S_CTRL</constant> ioctl). Control class
-<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls
-relating to MPEG encoding, etc.</para>
-
- <para>All controls in the control array must belong to the
-specified control class. An error is returned if this is not the
-case.</para>
-
- <para>It is also possible to use an empty control array (count
-== 0) to check whether the specified control class is
-supported.</para>
-
- <para>The control array is a &v4l2-ext-control; array. The
-<structname>v4l2_ext_control</structname> structure is very similar to
-&v4l2-control;, except for the fact that it also allows for 64-bit
-values and pointers to be passed.</para>
-
- <para>Since the &v4l2-ext-control; supports pointers it is now
-also possible to have controls with compound types such as N-dimensional arrays
-and/or structures. You need to specify the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
-when enumerating controls to actually be able to see such compound controls.
-In other words, these controls with compound types should only be used
-programmatically.</para>
-
- <para>Since such compound controls need to expose more information
-about themselves than is possible with &VIDIOC-QUERYCTRL; the
-&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives
-the dimensions of the N-dimensional array if this control consists of more than
-one element.</para>
-
- <para>It is important to realize that due to the flexibility of
-controls it is necessary to check whether the control you want to set
-actually is supported in the driver and what the valid range of values
-is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and
-&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible
-that some of the menu indices in a control of type
-<constant>V4L2_CTRL_TYPE_MENU</constant> may not be supported
-(<constant>VIDIOC_QUERYMENU</constant> will return an error). A good
-example is the list of supported MPEG audio bitrates. Some drivers only
-support one or two bitrates, others support a wider range.</para>
-
- <para>
- All controls use machine endianness.
- </para>
- </section>
-
- <section>
- <title>Enumerating Extended Controls</title>
-
- <para>The recommended way to enumerate over the extended
-controls is by using &VIDIOC-QUERYCTRL; in combination with the
-<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para>
-
- <informalexample>
- <programlisting>
-&v4l2-queryctrl; qctrl;
-
-qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
-while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
- /* ... */
- qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
-}
-</programlisting>
- </informalexample>
-
- <para>The initial control ID is set to 0 ORed with the
-<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The
-<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first
-control with a higher ID than the specified one. When no such controls
-are found an error is returned.</para>
-
- <para>If you want to get all controls within a specific control
-class, then you can set the initial
-<structfield>qctrl.id</structfield> value to the control class and add
-an extra check to break out of the loop when a control of another
-control class is found:</para>
-
- <informalexample>
- <programlisting>
-qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
-while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
- if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
- break;
- /* ... */
- qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
-}
-</programlisting>
- </informalexample>
-
- <para>The 32-bit <structfield>qctrl.id</structfield> value is
-subdivided into three bit ranges: the top 4 bits are reserved for
-flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not
-actually part of the ID. The remaining 28 bits form the control ID, of
-which the most significant 12 bits define the control class and the
-least significant 16 bits identify the control within the control
-class. It is guaranteed that these last 16 bits are always non-zero
-for controls. The range of 0x1000 and up are reserved for
-driver-specific controls. The macro
-<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class
-ID based on a control ID.</para>
-
- <para>If the driver does not support extended controls, then
-<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
-combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
-that case the old method of enumerating control should be used (see
-<xref linkend="enum_all_controls" />). But if it is supported, then it is guaranteed to enumerate over
-all controls, including driver-private controls.</para>
- </section>
-
- <section>
- <title>Creating Control Panels</title>
-
- <para>It is possible to create control panels for a graphical
-user interface where the user can select the various controls.
-Basically you will have to iterate over all controls using the method
-described above. Each control class starts with a control of type
-<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>.
-<constant>VIDIOC_QUERYCTRL</constant> will return the name of this
-control class which can be used as the title of a tab page within a
-control panel.</para>
-
- <para>The flags field of &v4l2-queryctrl; also contains hints on
-the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation
-for more details.</para>
- </section>
-
- <section id="mpeg-controls">
- <title>Codec Control Reference</title>
-
- <para>Below all controls within the Codec control class are
-described. First the generic controls, then controls specific for
-certain hardware.</para>
-
- <para>Note: These controls are applicable to all codecs and
-not just MPEG. The defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG
-as the controls were originally made for MPEG codecs and later
-extended to cover all encoding formats.</para>
-
- <section>
- <title>Generic Codec Controls</title>
-
- <table pgwide="1" frame="none" id="mpeg-control-id">
- <title>Codec Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The Codec class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class. This description can be used as the
-caption of a Tab page in a GUI, for example.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-stream-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_stream_type</entry>
- </row><row><entry spanname="descr">The MPEG-1, -2 or -4
-output stream type. One cannot assume anything here. Each hardware
-MPEG encoder tends to support different subsets of the available MPEG
-stream types. This control is specific to multiplexed MPEG streams.
-The currently defined stream types are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant>&nbsp;</entry>
- <entry>MPEG-2 program stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant>&nbsp;</entry>
- <entry>MPEG-2 transport stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant>&nbsp;</entry>
- <entry>MPEG-1 system stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant>&nbsp;</entry>
- <entry>MPEG-2 DVD-compatible stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant>&nbsp;</entry>
- <entry>MPEG-1 VCD-compatible stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant>&nbsp;</entry>
- <entry>MPEG-2 SVCD-compatible stream</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Program Map Table
-Packet ID for the MPEG transport stream (default 16)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Audio Packet ID for
-the MPEG transport stream (default 256)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Video Packet ID for
-the MPEG transport stream (default 260)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Packet ID for the
-MPEG transport stream carrying PCR fields (default 259)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Audio ID for MPEG
-PES</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Video ID for MPEG
-PES</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-stream-vbi-fmt">
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_stream_vbi_fmt</entry>
- </row><row><entry spanname="descr">Some cards can embed
-VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This
-control selects whether VBI data should be embedded, and if so, what
-embedding method should be used. The list of possible VBI formats
-depends on the driver. The currently defined VBI format types
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant>&nbsp;</entry>
- <entry>No VBI in the MPEG stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant>&nbsp;</entry>
- <entry>VBI in private packets, IVTV format (documented
-in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-sampling-freq">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_sampling_freq</entry>
- </row><row><entry spanname="descr">MPEG Audio sampling
-frequency. Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant>&nbsp;</entry>
- <entry>44.1 kHz</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant>&nbsp;</entry>
- <entry>48 kHz</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant>&nbsp;</entry>
- <entry>32 kHz</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-encoding">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_encoding</entry>
- </row><row><entry spanname="descr">MPEG Audio encoding.
-This control is specific to multiplexed MPEG streams.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant>&nbsp;</entry>
- <entry>MPEG-1/2 Layer I encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant>&nbsp;</entry>
- <entry>MPEG-1/2 Layer II encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant>&nbsp;</entry>
- <entry>MPEG-1/2 Layer III encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant>&nbsp;</entry>
- <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant>&nbsp;</entry>
- <entry>AC-3 aka ATSC A/52 encoding</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-l1-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_l1_bitrate</entry>
- </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry></row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant>&nbsp;</entry>
- <entry>288 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant>&nbsp;</entry>
- <entry>352 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant>&nbsp;</entry>
- <entry>384 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant>&nbsp;</entry>
- <entry>416 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant>&nbsp;</entry>
- <entry>448 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-l2-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_l2_bitrate</entry>
- </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant>&nbsp;</entry>
- <entry>48 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant>&nbsp;</entry>
- <entry>56 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant>&nbsp;</entry>
- <entry>80 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant>&nbsp;</entry>
- <entry>112 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant>&nbsp;</entry>
- <entry>384 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-l3-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_l3_bitrate</entry>
- </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant>&nbsp;</entry>
- <entry>40 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant>&nbsp;</entry>
- <entry>48 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant>&nbsp;</entry>
- <entry>56 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant>&nbsp;</entry>
- <entry>80 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant>&nbsp;</entry>
- <entry>112 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-ac3-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_ac3_bitrate</entry>
- </row><row><entry spanname="descr">AC-3 bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant>&nbsp;</entry>
- <entry>40 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant>&nbsp;</entry>
- <entry>48 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant>&nbsp;</entry>
- <entry>56 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant>&nbsp;</entry>
- <entry>80 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant>&nbsp;</entry>
- <entry>112 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant>&nbsp;</entry>
- <entry>384 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant>&nbsp;</entry>
- <entry>448 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant>&nbsp;</entry>
- <entry>512 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant>&nbsp;</entry>
- <entry>576 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant>&nbsp;</entry>
- <entry>640 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_mode</entry>
- </row><row><entry spanname="descr">MPEG Audio mode.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant>&nbsp;</entry>
- <entry>Stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant>&nbsp;</entry>
- <entry>Joint Stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant>&nbsp;</entry>
- <entry>Bilingual</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant>&nbsp;</entry>
- <entry>Mono</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-mode-extension">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_mode_extension</entry>
- </row><row><entry spanname="descr">Joint Stereo
-audio mode extension. In Layer I and II they indicate which subbands
-are in intensity stereo. All other subbands are coded in stereo. Layer
-III is not (yet) supported. Possible values
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant>&nbsp;</entry>
- <entry>Subbands 4-31 in intensity stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant>&nbsp;</entry>
- <entry>Subbands 8-31 in intensity stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant>&nbsp;</entry>
- <entry>Subbands 12-31 in intensity stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant>&nbsp;</entry>
- <entry>Subbands 16-31 in intensity stereo</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-emphasis">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_emphasis</entry>
- </row><row><entry spanname="descr">Audio Emphasis.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant>&nbsp;</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant>&nbsp;</entry>
- <entry>50/15 microsecond emphasis</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant>&nbsp;</entry>
- <entry>CCITT J.17</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-crc">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_crc</entry>
- </row><row><entry spanname="descr">CRC method. Possible
-values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant>&nbsp;</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant>&nbsp;</entry>
- <entry>16 bit parity check</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Mutes the audio when
-capturing. This is not done by muting audio hardware, which can still
-produce a slight hiss, but in the encoder itself, guaranteeing a fixed
-and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-dec-playback">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_dec_playback</entry>
- </row><row><entry spanname="descr">Determines how monolingual audio should be played back.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO</constant>&nbsp;</entry>
- <entry>Automatically determines the best playback mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO</constant>&nbsp;</entry>
- <entry>Stereo playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT</constant>&nbsp;</entry>
- <entry>Left channel playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT</constant>&nbsp;</entry>
- <entry>Right channel playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO</constant>&nbsp;</entry>
- <entry>Mono playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO</constant>&nbsp;</entry>
- <entry>Stereo playback with swapped left and right channels.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-dec-multilingual-playback">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_dec_playback</entry>
- </row><row><entry spanname="descr">Determines how multilingual audio should be played back.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-encoding">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_encoding</entry>
- </row><row><entry spanname="descr">MPEG Video encoding
-method. This control is specific to multiplexed MPEG streams.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant>&nbsp;</entry>
- <entry>MPEG-1 Video encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant>&nbsp;</entry>
- <entry>MPEG-2 Video encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant>&nbsp;</entry>
- <entry>MPEG-4 AVC (H.264) Video encoding</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-aspect">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_aspect</entry>
- </row><row><entry spanname="descr">Video aspect.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant>&nbsp;</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant>&nbsp;</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant>&nbsp;</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant>&nbsp;</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Number of B-Frames
-(default 2)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">GOP size (default
-12)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">GOP closure (default
-1)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enable 3:2 pulldown
-(default 0)</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-bitrate-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_bitrate_mode</entry>
- </row><row><entry spanname="descr">Video bitrate mode.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant>&nbsp;</entry>
- <entry>Variable bitrate</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant>&nbsp;</entry>
- <entry>Constant bitrate</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Video bitrate in bits
-per second.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Peak video bitrate in
-bits per second. Must be larger or equal to the average video bitrate.
-It is ignored if the video bitrate mode is set to constant
-bitrate.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">For every captured
-frame, skip this many subsequent frames (default 0).</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">"Mutes" the video to a
-fixed color when capturing. This is useful for testing, to produce a
-fixed video bitstream. 0 = unmuted, 1 = muted.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Sets the "mute" color
-of the video. The supplied 32-bit integer is interpreted as follows (bit
-0 = least significant bit):</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry>Bit 0:7</entry>
- <entry>V chrominance information</entry>
- </row>
- <row>
- <entry>Bit 8:15</entry>
- <entry>U chrominance information</entry>
- </row>
- <row>
- <entry>Bit 16:23</entry>
- <entry>Y luminance information</entry>
- </row>
- <row>
- <entry>Bit 24:31</entry>
- <entry>Must be zero.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-dec-pts">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant>&nbsp;</entry>
- <entry>integer64</entry>
- </row><row><entry spanname="descr">This read-only control returns the
-33-bit video Presentation Time Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of
-the currently displayed frame. This is the same PTS as is used in &VIDIOC-DECODER-CMD;.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-dec-frame">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant>&nbsp;</entry>
- <entry>integer64</entry>
- </row><row><entry spanname="descr">This read-only control returns the
-frame counter of the frame that is currently displayed (decoded). This value is reset to 0 whenever
-the decoder is started.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If enabled the decoder expects to receive a single slice per buffer, otherwise
-the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs.
-</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable writing sample aspect ratio in the Video Usability Information.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-vui-sar-idc">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_vui_sar_idc</entry>
- </row>
- <row><entry spanname="descr">VUI sample aspect ratio indicator for H.264 encoding. The value
-is defined in the table E-1 in the standard. Applicable to the H264 encoder.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
-
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED</constant>&nbsp;</entry>
- <entry>Unspecified</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1</constant>&nbsp;</entry>
- <entry>1x1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11</constant>&nbsp;</entry>
- <entry>12x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11</constant>&nbsp;</entry>
- <entry>10x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11</constant>&nbsp;</entry>
- <entry>16x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33</constant>&nbsp;</entry>
- <entry>40x33</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11</constant>&nbsp;</entry>
- <entry>24x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11</constant>&nbsp;</entry>
- <entry>20x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11</constant>&nbsp;</entry>
- <entry>32x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33</constant>&nbsp;</entry>
- <entry>80x33</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11</constant>&nbsp;</entry>
- <entry>18x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11</constant>&nbsp;</entry>
- <entry>15x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33</constant>&nbsp;</entry>
- <entry>64x33</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99</constant>&nbsp;</entry>
- <entry>160x99</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3</constant>&nbsp;</entry>
- <entry>4x3</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2</constant>&nbsp;</entry>
- <entry>3x2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1</constant>&nbsp;</entry>
- <entry>2x1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED</constant>&nbsp;</entry>
- <entry>Extended SAR</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Extended sample aspect ratio width for H.264 VUI encoding.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Extended sample aspect ratio height for H.264 VUI encoding.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-level">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LEVEL</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_level</entry>
- </row>
- <row><entry spanname="descr">The level information for the H264 video elementary stream.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_0</constant>&nbsp;</entry>
- <entry>Level 1.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1B</constant>&nbsp;</entry>
- <entry>Level 1B</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_1</constant>&nbsp;</entry>
- <entry>Level 1.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_2</constant>&nbsp;</entry>
- <entry>Level 1.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_3</constant>&nbsp;</entry>
- <entry>Level 1.3</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_0</constant>&nbsp;</entry>
- <entry>Level 2.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_1</constant>&nbsp;</entry>
- <entry>Level 2.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_2</constant>&nbsp;</entry>
- <entry>Level 2.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_0</constant>&nbsp;</entry>
- <entry>Level 3.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_1</constant>&nbsp;</entry>
- <entry>Level 3.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_2</constant>&nbsp;</entry>
- <entry>Level 3.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_0</constant>&nbsp;</entry>
- <entry>Level 4.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_1</constant>&nbsp;</entry>
- <entry>Level 4.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_2</constant>&nbsp;</entry>
- <entry>Level 4.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_0</constant>&nbsp;</entry>
- <entry>Level 5.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_1</constant>&nbsp;</entry>
- <entry>Level 5.1</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-mpeg4-level">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_mpeg4_level</entry>
- </row>
- <row><entry spanname="descr">The level information for the MPEG4 elementary stream.
-Applicable to the MPEG4 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_0</constant>&nbsp;</entry>
- <entry>Level 0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_0B</constant>&nbsp;</entry>
- <entry>Level 0b</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_1</constant>&nbsp;</entry>
- <entry>Level 1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_2</constant>&nbsp;</entry>
- <entry>Level 2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_3</constant>&nbsp;</entry>
- <entry>Level 3</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_3B</constant>&nbsp;</entry>
- <entry>Level 3b</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_4</constant>&nbsp;</entry>
- <entry>Level 4</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_5</constant>&nbsp;</entry>
- <entry>Level 5</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-profile">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_PROFILE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_profile</entry>
- </row>
- <row><entry spanname="descr">The profile information for H264.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE</constant>&nbsp;</entry>
- <entry>Baseline profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE</constant>&nbsp;</entry>
- <entry>Constrained Baseline profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MAIN</constant>&nbsp;</entry>
- <entry>Main profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED</constant>&nbsp;</entry>
- <entry>Extended profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH</constant>&nbsp;</entry>
- <entry>High profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10</constant>&nbsp;</entry>
- <entry>High 10 profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422</constant>&nbsp;</entry>
- <entry>High 422 profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE</constant>&nbsp;</entry>
- <entry>High 444 Predictive profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA</constant>&nbsp;</entry>
- <entry>High 10 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA</constant>&nbsp;</entry>
- <entry>High 422 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA</constant>&nbsp;</entry>
- <entry>High 444 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA</constant>&nbsp;</entry>
- <entry>CAVLC 444 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE</constant>&nbsp;</entry>
- <entry>Scalable Baseline profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH</constant>&nbsp;</entry>
- <entry>Scalable High profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA</constant>&nbsp;</entry>
- <entry>Scalable High Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH</constant>&nbsp;</entry>
- <entry>Stereo High profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH</constant>&nbsp;</entry>
- <entry>Multiview High profile</entry>
- </row>
-
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-mpeg4-profile">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_mpeg4_profile</entry>
- </row>
- <row><entry spanname="descr">The profile information for MPEG4.
-Applicable to the MPEG4 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE</constant>&nbsp;</entry>
- <entry>Simple profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE</constant>&nbsp;</entry>
- <entry>Advanced Simple profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_CORE</constant>&nbsp;</entry>
- <entry>Core profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE</constant>&nbsp;</entry>
- <entry>Simple Scalable profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY</constant>&nbsp;</entry>
- <entry></entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MAX_REF_PIC</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The maximum number of reference pictures used for encoding.
-Applicable to the encoder.
-</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-multi-slice-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_multi_slice_mode</entry>
- </row>
- <row><entry spanname="descr">Determines how the encoder should handle division of frame into slices.
-Applicable to the encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE</constant>&nbsp;</entry>
- <entry>Single slice per frame.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>&nbsp;</entry>
- <entry>Multiple slices with set maximum number of macroblocks per slice.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>&nbsp;</entry>
- <entry>Multiple slice with set maximum size in bytes per slice.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The maximum number of macroblocks in a slice. Used when
-<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>.
-Applicable to the encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The maximum size of a slice in bytes. Used when
-<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>.
-Applicable to the encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-loop-filter-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_loop_filter_mode</entry>
- </row>
- <row><entry spanname="descr">Loop filter mode for H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED</constant>&nbsp;</entry>
- <entry>Loop filter is enabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED</constant>&nbsp;</entry>
- <entry>Loop filter is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY</constant>&nbsp;</entry>
- <entry>Loop filter is disabled at the slice boundary.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Loop filter alpha coefficient, defined in the H264 standard.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Loop filter beta coefficient, defined in the H264 standard.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-entropy-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_entropy_mode</entry>
- </row>
- <row><entry spanname="descr">Entropy coding mode for H264 - CABAC/CAVALC.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC</constant>&nbsp;</entry>
- <entry>Use CAVLC entropy coding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC</constant>&nbsp;</entry>
- <entry>Use CABAC entropy coding.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable 8X8 transform for H264. Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Cyclic intra macroblock refresh. This is the number of continuous macroblocks
-refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from the
-top of the frame. Applicable to H264, H263 and MPEG4 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Frame level rate control enable.
-If this control is disabled then the quantization parameter for each frame type is constant and set with appropriate controls
-(e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>).
-If frame rate control is enabled then quantization parameter is adjusted to meet the chosen bitrate. Minimum and maximum value
-for the quantization parameter can be set with appropriate controls (e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>).
-Applicable to encoders.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Macroblock level rate control enable.
-Applicable to the MPEG4 and H264 encoders.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_QPEL</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MAX_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an P frame for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an B frame for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MIN_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MAX_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an P frame for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an B frame for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an P frame for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_SIZE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip.
-The VBV is defined in the standard as a mean to verify that the produced stream will be successfully decoded.
-The standard describes it as "Part of a hypothetical decoder that is conceptually connected to the
-output of the encoder. Its purpose is to provide a constraint on the variability of the data rate that an
-encoder or editing process may produce.".
-Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-vbv-delay">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_DELAY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Sets the initial delay in milliseconds for
-VBV buffer control.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-hor-search-range">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Horizontal search range defines maximum horizontal search area in pixels
-to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set
-horizontal search range for motion estimation module in video encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-vert-search-range">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Vertical search range defines maximum vertical search area in pixels
-to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set
-vertical search range for motion estimation module in video encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip.
-The CPB is defined in the H264 standard as a mean to verify that the produced stream will be successfully decoded.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_PERIOD</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Period between I-frames in the open GOP for H264. In case of an open GOP
-this is the period between two I-frames. The period between IDR (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE control.
-An IDR frame, which stands for Instantaneous Decoding Refresh is an I-frame after which no prior frames are
-referenced. This means that a stream can be restarted from an IDR frame without the need to store or decode any
-previous frames. Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-header-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_HEADER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_header_mode</entry>
- </row>
- <row><entry spanname="descr">Determines whether the header is returned as the first buffer or is
-it returned together with the first frame. Applicable to encoders.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE</constant>&nbsp;</entry>
- <entry>The stream header is returned separately in the first buffer.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME</constant>&nbsp;</entry>
- <entry>The stream header is returned together with the first encoded frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Repeat the video sequence headers. Repeating these
-headers makes random access to the video stream easier. Applicable to the MPEG1, 2 and 4 encoder.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enabled the deblocking post processing filter for MPEG4 decoder.
-Applicable to the MPEG4 decoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">vop_time_increment_resolution value for MPEG4. Applicable to the MPEG4 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable generation of frame packing supplemental enhancement information in the encoded bitstream.
-The frame packing SEI message contains the arrangement of L and R planes for 3D viewing. Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Sets current frame as frame0 in frame packing SEI.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-sei-fp-arrangement-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_sei_fp_arrangement_type</entry>
- </row>
- <row><entry spanname="descr">Frame packing arrangement type for H264 SEI.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD</constant>&nbsp;</entry>
- <entry>Pixels are alternatively from L and R.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN</constant>&nbsp;</entry>
- <entry>L and R are interlaced by column.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW</constant>&nbsp;</entry>
- <entry>L and R are interlaced by row.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE</constant>&nbsp;</entry>
- <entry>L is on the left, R on the right.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM</constant>&nbsp;</entry>
- <entry>L is on top, R on bottom.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL</constant>&nbsp;</entry>
- <entry>One view per frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables flexible macroblock ordering in the encoded bitstream. It is a technique
-used for restructuring the ordering of macroblocks in pictures. Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-fmo-map-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_fmo_map_type</entry>
- </row>
- <row><entry spanname="descr">When using FMO, the map type divides the image in different scan patterns of macroblocks.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES</constant>&nbsp;</entry>
- <entry>Slices are interleaved one after other with macroblocks in run length order.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES</constant>&nbsp;</entry>
- <entry>Scatters the macroblocks based on a mathematical function known to both encoder and decoder.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER</constant>&nbsp;</entry>
- <entry>Macroblocks arranged in rectangular areas or regions of interest.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT</constant>&nbsp;</entry>
- <entry>Slice groups grow in a cyclic way from centre to outwards.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN</constant>&nbsp;</entry>
- <entry>Slice groups grow in raster scan pattern from left to right.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN</constant>&nbsp;</entry>
- <entry>Slice groups grow in wipe scan pattern from top to bottom.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT</constant>&nbsp;</entry>
- <entry>User defined map type.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Number of slice groups in FMO.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-fmo-change-direction">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_fmo_change_dir</entry>
- </row>
- <row><entry spanname="descr">Specifies a direction of the slice group change for raster and wipe maps.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT</constant>&nbsp;</entry>
- <entry>Raster scan or wipe right.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT</constant>&nbsp;</entry>
- <entry>Reverse raster scan or wipe left.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Specifies the size of the first slice group for raster and wipe map.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Specifies the number of consecutive macroblocks for the interleaved map.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ASO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables arbitrary slice ordering in encoded bitstream.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Specifies the slice order in ASO. Applicable to the H264 encoder.
-The supplied 32-bit integer is interpreted as follows (bit
-0 = least significant bit):</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry>Bit 0:15</entry>
- <entry>Slice ID</entry>
- </row>
- <row>
- <entry>Bit 16:32</entry>
- <entry>Slice position or order</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables H264 hierarchical coding.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-hierarchical-coding-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_hierarchical_coding_type</entry>
- </row>
- <row><entry spanname="descr">Specifies the hierarchical coding type.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B</constant>&nbsp;</entry>
- <entry>Hierarchical B coding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P</constant>&nbsp;</entry>
- <entry>Hierarchical P coding.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Specifies the number of hierarchical coding layers.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Specifies a user defined QP for each layer. Applicable to the H264 encoder.
-The supplied 32-bit integer is interpreted as follows (bit
-0 = least significant bit):</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry>Bit 0:15</entry>
- <entry>QP value</entry>
- </row>
- <row>
- <entry>Bit 16:32</entry>
- <entry>Layer number</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>MFC 5.1 MPEG Controls</title>
-
- <para>The following MPEG class controls deal with MPEG
-decoding and encoding settings that are specific to the Multi Format Codec 5.1 device present
-in the S5P family of SoCs by Samsung.
-</para>
-
- <table pgwide="1" frame="none" id="mfc51-control-id">
- <title>MFC 5.1 Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">If the display delay is enabled then the decoder is forced to return a
-CAPTURE buffer (decoded frame) after processing a certain number of OUTPUT buffers. The delay can be set through
-<constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant>. This feature can be used for example
-for generating thumbnails of videos. Applicable to the H264 decoder.
- </entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Display delay value for H264 decoder.
-The decoder is forced to return a decoded frame after the set 'display delay' number of frames. If this number is
-low it may result in frames returned out of dispaly order, in addition the hardware may still be using the returned buffer
-as a reference picture for subsequent frames.
-</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">The number of reference pictures used for encoding a P picture.
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Padding enable in the encoder - use a color instead of repeating border pixels.
-Applicable to encoders.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Padding color in the encoder. Applicable to encoders. The supplied 32-bit integer is interpreted as follows (bit
-0 = least significant bit):</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry>Bit 0:7</entry>
- <entry>V chrominance information</entry>
- </row>
- <row>
- <entry>Bit 8:15</entry>
- <entry>U chrominance information</entry>
- </row>
- <row>
- <entry>Bit 16:23</entry>
- <entry>Y luminance information</entry>
- </row>
- <row>
- <entry>Bit 24:31</entry>
- <entry>Must be zero.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Reaction coefficient for MFC rate control. Applicable to encoders.
-<para>Note 1: Valid only when the frame level RC is enabled.</para>
-<para>Note 2: For tight CBR, this field must be small (ex. 2 ~ 10).
-For VBR, this field must be large (ex. 100 ~ 1000).</para>
-<para>Note 3: It is not recommended to use the greater number than FRAME_RATE * (10^9 / BIT_RATE).</para>
-</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for dark region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for smooth region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for static region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for activity region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-mfc51-video-frame-skip-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_mfc51_video_frame_skip_mode</entry>
- </row>
- <row><entry spanname="descr">
-Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then
-a chosen data limit then the frame will be skipped.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED</constant>&nbsp;</entry>
- <entry>Frame skip mode is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT</constant>&nbsp;</entry>
- <entry>Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT</constant>&nbsp;</entry>
- <entry>Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Enable rate-control with fixed target bit.
-If this setting is enabled, then the rate control logic of the encoder will calculate the average bitrate
-for a GOP and keep it below or equal the set bitrate target. Otherwise the rate control logic calculates the
-overall average bitrate for the stream and keeps it below or equal to the set bitrate. In the first case
-the average bitrate for the whole stream will be smaller then the set bitrate. This is caused because the
-average is calculated for smaller number of frames, on the other hand enabling this setting will ensure that
-the stream will meet tight bandwidth contraints. Applicable to encoders.
-</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-mfc51-video-force-frame-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_mfc51_video_force_frame_type</entry>
- </row>
- <row><entry spanname="descr">Force a frame type for the next queued buffer. Applicable to encoders.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED</constant>&nbsp;</entry>
- <entry>Forcing a specific frame type disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME</constant>&nbsp;</entry>
- <entry>Force an I-frame.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED</constant>&nbsp;</entry>
- <entry>Force a non-coded frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>CX2341x MPEG Controls</title>
-
- <para>The following MPEG class controls deal with MPEG
-encoding settings that are specific to the Conexant CX23415 and
-CX23416 MPEG encoding chips.</para>
-
- <table pgwide="1" frame="none" id="cx2341x-control-id">
- <title>CX2341x Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>
- </row><row><entry spanname="descr">Sets the Spatial
-Filter mode (default <constant>MANUAL</constant>). Possible values
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
- <entry>Choose the filter manually</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
- <entry>Choose the filter automatically</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-15)</entry>
- </row><row><entry spanname="descr">The setting for the
-Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry>
- </row>
- <row><entry></entry></row>
- <row id="luma-spatial-filter-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>
- </row><row><entry spanname="descr">Select the algorithm
-to use for the Luma Spatial Filter (default
-<constant>1D_HOR</constant>). Possible values:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
- <entry>No filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
- <entry>One-dimensional horizontal</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant>&nbsp;</entry>
- <entry>One-dimensional vertical</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant>&nbsp;</entry>
- <entry>Two-dimensional separable</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant>&nbsp;</entry>
- <entry>Two-dimensional symmetrical
-non-separable</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="chroma-spatial-filter-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>
- </row><row><entry spanname="descr">Select the algorithm
-for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
- <entry>No filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
- <entry>One-dimensional horizontal</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>
- </row><row><entry spanname="descr">Sets the Temporal
-Filter mode (default <constant>MANUAL</constant>). Possible values
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
- <entry>Choose the filter manually</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
- <entry>Choose the filter automatically</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-31)</entry>
- </row><row><entry spanname="descr">The setting for the
-Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale
-capturing and 0 for scaled capturing.)</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-cx2341x-video-median-filter-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_median_filter_type</entry>
- </row><row><entry spanname="descr">Median Filter Type
-(default <constant>OFF</constant>). Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant>&nbsp;</entry>
- <entry>No filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant>&nbsp;</entry>
- <entry>Horizontal filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant>&nbsp;</entry>
- <entry>Vertical filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant>&nbsp;</entry>
- <entry>Horizontal and vertical filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant>&nbsp;</entry>
- <entry>Diagonal filter</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold above which
-the luminance median filter is enabled (default 0)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold below which
-the luminance median filter is enabled (default 255)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold above which
-the chroma median filter is enabled (default 0)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold below which
-the chroma median filter is enabled (default 255)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">The CX2341X MPEG encoder
-can insert one empty MPEG-2 PES packet into the stream between every
-four video frames. The packet size is 2048 bytes, including the
-packet_start_code_prefix and stream_id fields. The stream_id is 0xBF
-(private stream 2). The payload consists of 0x00 bytes, to be filled
-in by the application. 0 = do not insert, 1 = insert packets.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>VPX Control Reference</title>
-
- <para>The VPX controls include controls for encoding parameters
- of VPx video codec.</para>
-
- <table pgwide="1" frame="none" id="vpx-control-id">
- <title>VPX Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
-
- <row><entry></entry></row>
- <row id="v4l2-vpx-num-partitions">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS</constant></entry>
- <entry>enum v4l2_vp8_num_partitions</entry>
- </row>
- <row><entry spanname="descr">The number of token partitions to use in VP8 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION</constant></entry>
- <entry>1 coefficient partition</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS</constant></entry>
- <entry>2 coefficient partitions</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS</constant></entry>
- <entry>4 coefficient partitions</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS</constant></entry>
- <entry>8 coefficient partitions</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4</constant></entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Setting this prevents intra 4x4 mode in the intra mode decision.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-vpx-num-ref-frames">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES</constant></entry>
- <entry>enum v4l2_vp8_num_ref_frames</entry>
- </row>
- <row><entry spanname="descr">The number of reference pictures for encoding P frames.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME</constant></entry>
- <entry>Last encoded frame will be searched</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME</constant></entry>
- <entry>Two frames will be searched among the last encoded frame, the golden frame
-and the alternate reference (altref) frame. The encoder implementation will decide which two are chosen.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME</constant></entry>
- <entry>The last encoded frame, the golden frame and the altref frame will be searched.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL</constant></entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Indicates the loop filter level. The adjustment of the loop
-filter level is done via a delta value against a baseline loop filter value.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS</constant></entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">This parameter affects the loop filter. Anything above
-zero weakens the deblocking effect on the loop filter.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD</constant></entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the refresh period for the golden frame. The period is defined
-in number of frames. For a value of 'n', every nth frame starting from the first key frame will be taken as a golden frame.
-For eg. for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden frame refresh period is set as 4, the frames
-0, 4, 8 etc will be taken as the golden frames as frame 0 is always a key frame.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-vpx-golden-frame-sel">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL</constant></entry>
- <entry>enum v4l2_vp8_golden_frame_sel</entry>
- </row>
- <row><entry spanname="descr">Selects the golden frame for encoding.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV</constant></entry>
- <entry>Use the (n-2)th frame as a golden frame, current frame index being 'n'.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD</constant></entry>
- <entry>Use the previous specific frame indicated by
-V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a golden frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_MIN_QP</constant></entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for VP8.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_MAX_QP</constant></entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for VP8.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for VP8.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for a P frame for VP8.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_PROFILE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Select the desired profile for VPx encoder.
-Acceptable values are 0, 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.</entry>
- </row>
-
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
- </section>
-
- <section id="camera-controls">
- <title>Camera Control Reference</title>
-
- <para>The Camera class includes controls for mechanical (or
-equivalent digital) features of a device such as controllable lenses
-or sensors.</para>
-
- <table pgwide="1" frame="none" id="camera-control-id">
- <title>Camera Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The Camera class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-exposure-auto-type">
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_exposure_auto_type</entry>
- </row><row><entry spanname="descr">Enables automatic
-adjustments of the exposure time and/or iris aperture. The effect of
-manual changes of the exposure time or iris aperture while these
-features are enabled is undefined, drivers should ignore such
-requests. Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EXPOSURE_AUTO</constant>&nbsp;</entry>
- <entry>Automatic exposure time, automatic iris
-aperture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_MANUAL</constant>&nbsp;</entry>
- <entry>Manual exposure time, manual iris.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant>&nbsp;</entry>
- <entry>Manual exposure time, auto iris.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant>&nbsp;</entry>
- <entry>Auto exposure time, manual iris.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Determines the exposure
-time of the camera sensor. The exposure time is limited by the frame
-interval. Drivers should interpret the values as 100 &micro;s units,
-where the value 1 stands for 1/10000th of a second, 10000 for 1 second
-and 100000 for 10 seconds.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">When
-<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to
-<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>,
-this control determines if the device may dynamically vary the frame
-rate. By default this feature is disabled (0) and the frame rate must
-remain constant.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_BIAS</constant>&nbsp;</entry>
- <entry>integer menu</entry>
- </row><row><entry spanname="descr"> Determines the automatic
-exposure compensation, it is effective only when <constant>V4L2_CID_EXPOSURE_AUTO</constant>
-control is set to <constant>AUTO</constant>, <constant>SHUTTER_PRIORITY </constant>
-or <constant>APERTURE_PRIORITY</constant>.
-It is expressed in terms of EV, drivers should interpret the values as 0.001 EV
-units, where the value 1000 stands for +1 EV.
-<para>Increasing the exposure compensation value is equivalent to decreasing
-the exposure value (EV) and will increase the amount of light at the image
-sensor. The camera performs the exposure compensation by adjusting absolute
-exposure time and/or aperture.</para></entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-exposure-metering">
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_METERING</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_exposure_metering</entry>
- </row><row><entry spanname="descr">Determines how the camera measures
-the amount of light available for the frame exposure. Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_AVERAGE</constant>&nbsp;</entry>
- <entry>Use the light information coming from the entire frame
-and average giving no weighting to any particular portion of the metered area.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_CENTER_WEIGHTED</constant>&nbsp;</entry>
- <entry>Average the light information coming from the entire frame
-giving priority to the center of the metered area.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_SPOT</constant>&nbsp;</entry>
- <entry>Measure only very small area at the center of the frame.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_MATRIX</constant>&nbsp;</entry>
- <entry>A multi-zone metering. The light intensity is measured
-in several points of the frame and the the results are combined. The
-algorithm of the zones selection and their significance in calculating the
-final value is device dependent.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control turns the
-camera horizontally by the specified amount. The unit is undefined. A
-positive value moves the camera to the right (clockwise when viewed
-from above), a negative value to the left. A value of zero does not
-cause motion. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control turns the
-camera vertically by the specified amount. The unit is undefined. A
-positive value moves the camera up, a negative value down. A value of
-zero does not cause motion. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">When this control is set,
-the camera moves horizontally to the default position.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">When this control is set,
-the camera moves vertically to the default position.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control
-turns the camera horizontally to the specified position. Positive
-values move the camera to the right (clockwise when viewed from above),
-negative values to the left. Drivers should interpret the values as arc
-seconds, with valid values between -180 * 3600 and +180 * 3600
-inclusive.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control
-turns the camera vertically to the specified position. Positive values
-move the camera up, negative values down. Drivers should interpret the
-values as arc seconds, with valid values between -180 * 3600 and +180
-* 3600 inclusive.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control sets the
-focal point of the camera to the specified position. The unit is
-undefined. Positive values set the focus closer to the camera,
-negative values towards infinity.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control moves the
-focal point of the camera by the specified amount. The unit is
-undefined. Positive values move the focus closer to the camera,
-negative values towards infinity. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enables continuous automatic
-focus adjustments. The effect of manual focus adjustments while this feature
-is enabled is undefined, drivers should ignore such requests.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_START</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">Starts single auto focus process.
-The effect of setting this control when <constant>V4L2_CID_FOCUS_AUTO</constant>
-is set to <constant>TRUE</constant> (1) is undefined, drivers should ignore
-such requests.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_STOP</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">Aborts automatic focusing
-started with <constant>V4L2_CID_AUTO_FOCUS_START</constant> control. It is
-effective only when the continuous autofocus is disabled, that is when
-<constant>V4L2_CID_FOCUS_AUTO</constant> control is set to <constant>FALSE
-</constant> (0).</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-auto-focus-status">
- <entry spanname="id">
- <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant>&nbsp;</entry>
- <entry>bitmask</entry>
- </row>
- <row><entry spanname="descr">The automatic focus status. This is a read-only
- control.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_IDLE</constant>&nbsp;</entry>
- <entry>Automatic focus is not active.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_BUSY</constant>&nbsp;</entry>
- <entry>Automatic focusing is in progress.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_REACHED</constant>&nbsp;</entry>
- <entry>Focus has been reached.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_FAILED</constant>&nbsp;</entry>
- <entry>Automatic focus has failed, the driver will not
- transition from this state until another action is
- performed by an application.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry spanname="descr">
-Setting <constant>V4L2_LOCK_FOCUS</constant> lock bit of the <constant>V4L2_CID_3A_LOCK
-</constant> control may stop updates of the <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant>
-control value.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-auto-focus-range">
- <entry spanname="id">
- <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_auto_focus_range</entry>
- </row>
- <row><entry spanname="descr">Determines auto focus distance range
-for which lens may be adjusted. </entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_AUTO</constant>&nbsp;</entry>
- <entry>The camera automatically selects the focus range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_NORMAL</constant>&nbsp;</entry>
- <entry>Normal distance range, limited for best automatic focus
-performance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_MACRO</constant>&nbsp;</entry>
- <entry>Macro (close-up) auto focus. The camera will
-use its minimum possible distance for auto focus.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_INFINITY</constant>&nbsp;</entry>
- <entry>The lens is set to focus on an object at infinite distance.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Specify the objective lens
-focal length as an absolute value. The zoom unit is driver-specific and its
-value should be a positive integer.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Specify the objective lens
-focal length relatively to the current value. Positive values move the zoom
-lens group towards the telephoto direction, negative values towards the
-wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Move the objective lens group
-at the specified speed until it reaches physical device limits or until an
-explicit request to stop the movement. A positive value moves the zoom lens
-group towards the telephoto direction. A value of zero stops the zoom lens
-group movement. A negative value moves the zoom lens group towards the
-wide-angle direction. The zoom speed unit is driver-specific.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control sets the
-camera's aperture to the specified value. The unit is undefined.
-Larger values open the iris wider, smaller values close it.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control modifies the
-camera's aperture by the specified amount. The unit is undefined.
-Positive values open the iris one step further, negative values close
-it one step further. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Prevent video from being acquired
-by the camera. When this control is set to <constant>TRUE</constant> (1), no
-image can be captured by the camera. Common means to enforce privacy are
-mechanical obturation of the sensor and firmware image processing, but the
-device is not restricted to these methods. Devices that implement the privacy
-control must support read access and may support write access.</entry>
- </row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Switch the band-stop filter of a
-camera sensor on or off, or specify its strength. Such band-stop filters can
-be used, for example, to filter out the fluorescent light component.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-auto-n-preset-white-balance">
- <entry spanname="id"><constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_auto_n_preset_white_balance</entry>
- </row><row><entry spanname="descr">Sets white balance to automatic,
-manual or a preset. The presets determine color temperature of the light as
-a hint to the camera for white balance adjustments resulting in most accurate
-color representation. The following white balance presets are listed in order
-of increasing color temperature.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_MANUAL</constant>&nbsp;</entry>
- <entry>Manual white balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_AUTO</constant>&nbsp;</entry>
- <entry>Automatic white balance adjustments.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_INCANDESCENT</constant>&nbsp;</entry>
- <entry>White balance setting for incandescent (tungsten) lighting.
-It generally cools down the colors and corresponds approximately to 2500...3500 K
-color temperature range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT</constant>&nbsp;</entry>
- <entry>White balance preset for fluorescent lighting.
-It corresponds approximately to 4000...5000 K color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT_H</constant>&nbsp;</entry>
- <entry>With this setting the camera will compensate for
-fluorescent H lighting.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_HORIZON</constant>&nbsp;</entry>
- <entry>White balance setting for horizon daylight.
-It corresponds approximately to 5000 K color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_DAYLIGHT</constant>&nbsp;</entry>
- <entry>White balance preset for daylight (with clear sky).
-It corresponds approximately to 5000...6500 K color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_FLASH</constant>&nbsp;</entry>
- <entry>With this setting the camera will compensate for the flash
-light. It slightly warms up the colors and corresponds roughly to 5000...5500 K
-color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_CLOUDY</constant>&nbsp;</entry>
- <entry>White balance preset for moderately overcast sky.
-This option corresponds approximately to 6500...8000 K color temperature
-range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_SHADE</constant>&nbsp;</entry>
- <entry>White balance preset for shade or heavily overcast
-sky. It corresponds approximately to 9000...10000 K color temperature.
-</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-wide-dynamic-range">
- <entry spanname="id"><constant>V4L2_CID_WIDE_DYNAMIC_RANGE</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables or disables the camera's wide dynamic
-range feature. This feature allows to obtain clear images in situations where
-intensity of the illumination varies significantly throughout the scene, i.e.
-there are simultaneously very dark and very bright areas. It is most commonly
-realized in cameras by combining two subsequent frames with different exposure
-times. <footnote id="ctypeconv"><para> This control may be changed to a menu
-control in the future, if more options are required.</para></footnote></entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-image-stabilization">
- <entry spanname="id"><constant>V4L2_CID_IMAGE_STABILIZATION</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables or disables image stabilization.
- <footnoteref linkend="ctypeconv"/></entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY</constant>&nbsp;</entry>
- <entry>integer menu</entry>
- </row><row><entry spanname="descr">Determines ISO equivalent of an
-image sensor indicating the sensor's sensitivity to light. The numbers are
-expressed in arithmetic scale, as per <xref linkend="iso12232" /> standard,
-where doubling the sensor sensitivity is represented by doubling the numerical
-ISO value. Applications should interpret the values as standard ISO values
-multiplied by 1000, e.g. control value 800 stands for ISO 0.8. Drivers will
-usually support only a subset of standard ISO values. The effect of setting
-this control while the <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>
-control is set to a value other than <constant>V4L2_CID_ISO_SENSITIVITY_MANUAL
-</constant> is undefined, drivers should ignore such requests.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-iso-sensitivity-auto-type">
- <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_iso_sensitivity_type</entry>
- </row><row><entry spanname="descr">Enables or disables automatic ISO
-sensitivity adjustments.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_ISO_SENSITIVITY_MANUAL</constant>&nbsp;</entry>
- <entry>Manual ISO sensitivity.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>&nbsp;</entry>
- <entry>Automatic ISO sensitivity adjustments.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-scene-mode">
- <entry spanname="id"><constant>V4L2_CID_SCENE_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_scene_mode</entry>
- </row><row><entry spanname="descr">This control allows to select
-scene programs as the camera automatic modes optimized for common shooting
-scenes. Within these modes the camera determines best exposure, aperture,
-focusing, light metering, white balance and equivalent sensitivity. The
-controls of those parameters are influenced by the scene mode control.
-An exact behavior in each mode is subject to the camera specification.
-
-<para>When the scene mode feature is not used, this control should be set to
-<constant>V4L2_SCENE_MODE_NONE</constant> to make sure the other possibly
-related controls are accessible. The following scene programs are defined:
-</para>
-</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SCENE_MODE_NONE</constant>&nbsp;</entry>
- <entry>The scene mode feature is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_BACKLIGHT</constant>&nbsp;</entry>
- <entry>Backlight. Compensates for dark shadows when light is
- coming from behind a subject, also by automatically turning
- on the flash.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_BEACH_SNOW</constant>&nbsp;</entry>
- <entry>Beach and snow. This mode compensates for all-white or
-bright scenes, which tend to look gray and low contrast, when camera's automatic
-exposure is based on an average scene brightness. To compensate, this mode
-automatically slightly overexposes the frames. The white balance may also be
-adjusted to compensate for the fact that reflected snow looks bluish rather
-than white.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_CANDLELIGHT</constant>&nbsp;</entry>
- <entry>Candle light. The camera generally raises the ISO
-sensitivity and lowers the shutter speed. This mode compensates for relatively
-close subject in the scene. The flash is disabled in order to preserve the
-ambiance of the light.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_DAWN_DUSK</constant>&nbsp;</entry>
- <entry>Dawn and dusk. Preserves the colors seen in low
-natural light before dusk and after down. The camera may turn off the flash,
-and automatically focus at infinity. It will usually boost saturation and
-lower the shutter speed.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_FALL_COLORS</constant>&nbsp;</entry>
- <entry>Fall colors. Increases saturation and adjusts white
-balance for color enhancement. Pictures of autumn leaves get saturated reds
-and yellows.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_FIREWORKS</constant>&nbsp;</entry>
- <entry>Fireworks. Long exposure times are used to capture
-the expanding burst of light from a firework. The camera may invoke image
-stabilization.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_LANDSCAPE</constant>&nbsp;</entry>
- <entry>Landscape. The camera may choose a small aperture to
-provide deep depth of field and long exposure duration to help capture detail
-in dim light conditions. The focus is fixed at infinity. Suitable for distant
-and wide scenery.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_NIGHT</constant>&nbsp;</entry>
- <entry>Night, also known as Night Landscape. Designed for low
-light conditions, it preserves detail in the dark areas without blowing out bright
-objects. The camera generally sets itself to a medium-to-high ISO sensitivity,
-with a relatively long exposure time, and turns flash off. As such, there will be
-increased image noise and the possibility of blurred image.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_PARTY_INDOOR</constant>&nbsp;</entry>
- <entry>Party and indoor. Designed to capture indoor scenes
-that are lit by indoor background lighting as well as the flash. The camera
-usually increases ISO sensitivity, and adjusts exposure for the low light
-conditions.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_PORTRAIT</constant>&nbsp;</entry>
- <entry>Portrait. The camera adjusts the aperture so that the
-depth of field is reduced, which helps to isolate the subject against a smooth
-background. Most cameras recognize the presence of faces in the scene and focus
-on them. The color hue is adjusted to enhance skin tones. The intensity of the
-flash is often reduced.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_SPORTS</constant>&nbsp;</entry>
- <entry>Sports. Significantly increases ISO and uses a fast
-shutter speed to freeze motion of rapidly-moving subjects. Increased image
-noise may be seen in this mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_SUNSET</constant>&nbsp;</entry>
- <entry>Sunset. Preserves deep hues seen in sunsets and
-sunrises. It bumps up the saturation.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_TEXT</constant>&nbsp;</entry>
- <entry>Text. It applies extra contrast and sharpness, it is
-typically a black-and-white mode optimized for readability. Automatic focus
-may be switched to close-up mode and this setting may also involve some
-lens-distortion correction.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_3A_LOCK</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">This control locks or unlocks the automatic
-focus, exposure and white balance. The automatic adjustments can be paused
-independently by setting the corresponding lock bit to 1. The camera then retains
-the settings until the lock bit is cleared. The following lock bits are defined:
-</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_LOCK_EXPOSURE</constant></entry>
- <entry>Automatic exposure adjustments lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_LOCK_WHITE_BALANCE</constant></entry>
- <entry>Automatic white balance adjustments lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_LOCK_FOCUS</constant></entry>
- <entry>Automatic focus lock.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry spanname="descr">
-When a given algorithm is not enabled, drivers should ignore requests
-to lock it and should return no error. An example might be an application
-setting bit <constant>V4L2_LOCK_WHITE_BALANCE</constant> when the
-<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant> control is set to
-<constant>FALSE</constant>. The value of this control may be changed
-by exposure, white balance or focus controls.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_SPEED</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control turns the
-camera horizontally at the specific speed. The unit is undefined. A
-positive value moves the camera to the right (clockwise when viewed
-from above), a negative value to the left. A value of zero stops the motion
-if one is in progress and has no effect otherwise.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_SPEED</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control turns the
-camera vertically at the specified speed. The unit is undefined. A
-positive value moves the camera up, a negative value down. A value of zero
-stops the motion if one is in progress and has no effect otherwise.</entry>
- </row>
- <row><entry></entry></row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="fm-tx-controls">
- <title>FM Transmitter Control Reference</title>
-
- <para>The FM Transmitter (FM_TX) class includes controls for common features of
-FM transmissions capable devices. Currently this class includes parameters for audio
-compression, pilot tone generation, audio deviation limiter, RDS transmission and
-tuning power features.</para>
-
- <table pgwide="1" frame="none" id="fm-tx-control-id">
- <title>FM_TX Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The FM_TX class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.
-The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the RDS Programme Identification field
-for transmission.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the RDS Programme Type field for transmission.
-This encodes up to 31 pre-defined programme types.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant>&nbsp;</entry>
- <entry>string</entry>
- </row>
- <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.
-It is intended for static display on a receiver. It is the primary aid to listeners in programme service
-identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification,
-there is a full description of the correct character encoding for Programme Service name strings.
-Also from RDS specification, PS is usually a single eight character text. However, it is also possible
-to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
-with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant>&nbsp;</entry>
- <entry>string</entry>
- </row>
- <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of
-what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
-programme-related information or any other text. In these cases, RadioText should be used in addition to
-<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
-in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being
-used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
-to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
-with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_MONO_STEREO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Sets the Mono/Stereo bit of the Decoder Identification code. If set,
-then the audio was recorded as stereo.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_ARTIFICIAL_HEAD</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Sets the
-<ulink url="http://en.wikipedia.org/wiki/Artificial_head">Artificial Head</ulink> bit of the Decoder
-Identification code. If set, then the audio was recorded using an artificial head.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_COMPRESSED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Sets the Compressed bit of the Decoder Identification code. If set,
-then the audio is compressed.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_DYNAMIC_PTY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Sets the Dynamic PTY bit of the Decoder Identification code. If set,
-then the PTY code is dynamically switched.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_PROGRAM</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_MUSIC_SPEECH</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it
-broadcasts speech. If the transmitter doesn't make this distinction, then it should be set.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then transmit alternate frequencies.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS</constant>&nbsp;</entry>
- <entry>__u32 array</entry>
- </row>
- <row><entry spanname="descr">The alternate frequencies in kHz units. The RDS standard allows
-for up to 25 frequencies to be defined. Drivers may support fewer frequencies so check
-the array size.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables or disables the audio deviation limiter feature.
-The limiter is useful when trying to maximize the audio volume, minimize receiver-generated
-distortion and prevent overmodulation.
-</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the audio deviation limiter feature release time.
-Unit is in useconds. Step and range are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures audio frequency deviation level in Hz.
-The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables or disables the audio compression feature.
-This feature amplifies signals below the threshold by a fixed gain and compresses audio
-signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the gain for audio compression feature. It is
-a dB value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the threshold level for audio compression freature.
-It is a dB value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the attack time for audio compression feature.
-It is a useconds value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the release time for audio compression feature.
-It is a useconds value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is
-in Hz. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures pilot tone frequency value. Unit is
-in Hz. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant>&nbsp;</entry>
- <entry>enum v4l2_preemphasis</entry>
- </row>
- <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.
-A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
-Depending on the region, a time constant of either 50 or 75 useconds is used. The enum&nbsp;v4l2_preemphasis
-defines possible values for pre-emphasis. Here they are:</entry>
- </row><row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant>&nbsp;</entry>
- <entry>No pre-emphasis is applied.</entry>
- </row>
- <row>
- <entry><constant>V4L2_PREEMPHASIS_50_uS</constant>&nbsp;</entry>
- <entry>A pre-emphasis of 50 uS is used.</entry>
- </row>
- <row>
- <entry><constant>V4L2_PREEMPHASIS_75_uS</constant>&nbsp;</entry>
- <entry>A pre-emphasis of 75 uS is used.</entry>
- </row>
- </tbody>
- </entrytbl>
-
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the output power level for signal transmission.
-Unit is in dBuV. Range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">This selects the value of antenna tuning capacitor
-manually or automatically if set to zero. Unit, range and step are driver-specific.</entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
-<para>For more details about RDS specification, refer to
-<xref linkend="iec62106" /> document, from CENELEC.</para>
- </section>
-
- <section id="flash-controls">
- <title>Flash Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link linkend="experimental">experimental</link>
-interface and may change in the future.</para>
- </note>
-
- <para>
- The V4L2 flash controls are intended to provide generic access
- to flash controller devices. Flash controller devices are
- typically used in digital cameras.
- </para>
-
- <para>
- The interface can support both LED and xenon flash devices. As
- of writing this, there is no xenon flash driver using this
- interface.
- </para>
-
- <section id="flash-controls-use-cases">
- <title>Supported use cases</title>
-
- <section>
- <title>Unsynchronised LED flash (software strobe)</title>
-
- <para>
- Unsynchronised LED flash is controlled directly by the
- host as the sensor. The flash must be enabled by the host
- before the exposure of the image starts and disabled once
- it ends. The host is fully responsible for the timing of
- the flash.
- </para>
-
- <para>Example of such device: Nokia N900.</para>
- </section>
-
- <section>
- <title>Synchronised LED flash (hardware strobe)</title>
-
- <para>
- The synchronised LED flash is pre-programmed by the host
- (power and timeout) but controlled by the sensor through a
- strobe signal from the sensor to the flash.
- </para>
-
- <para>
- The sensor controls the flash duration and timing. This
- information typically must be made available to the
- sensor.
- </para>
-
- </section>
-
- <section>
- <title>LED flash as torch</title>
-
- <para>
- LED flash may be used as torch in conjunction with another
- use case involving camera or individually.
- </para>
-
-
- <table pgwide="1" frame="none" id="flash-control-id">
- <title>Flash Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The FLASH class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-flash-led-mode">
- <entry spanname="descr">Defines the mode of the flash LED,
- the high-power white LED attached to the flash controller.
- Setting this control may not be possible in presence of
- some faults. See V4L2_CID_FLASH_FAULT.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry>
- <entry>Off.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry>
- <entry>Flash mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry>
- <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-flash-strobe-source"><entry
- spanname="descr">Defines the source of the flash LED
- strobe.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry>
- <entry>The flash strobe is triggered by using
- the V4L2_CID_FLASH_STROBE control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry>
- <entry>The flash strobe is triggered by an
- external source. Typically this is a sensor,
- which makes it possible to synchronises the
- flash strobe start to exposure start.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry>
- <entry>button</entry>
- </row>
- <row>
- <entry spanname="descr">Strobe flash. Valid when
- V4L2_CID_FLASH_LED_MODE is set to
- V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
- is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
- control may not be possible in presence of some faults.
- See V4L2_CID_FLASH_FAULT.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry>
- <entry>button</entry>
- </row>
- <row><entry spanname="descr">Stop flash strobe immediately.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Strobe status: whether the flash
- is strobing at the moment or not. This is a read-only
- control.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Hardware timeout for flash. The
- flash strobe is stopped after this period of time has
- passed from the start of the strobe.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Intensity of the flash strobe when
- the flash LED is in flash mode
- (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps
- (mA) if possible.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Intensity of the flash LED in
- torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be
- milliamps (mA) if possible. Setting this control may not
- be possible in presence of some faults. See
- V4L2_CID_FLASH_FAULT.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Intensity of the indicator LED.
- The indicator LED may be fully independent of the flash
- LED. The unit should be microamps (uA) if possible.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Faults related to the flash. The
- faults tell about specific problems in the flash chip
- itself or the LEDs attached to it. Faults may prevent
- further use of some of the flash controls. In particular,
- V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
- if the fault affects the flash LED. Exactly which faults
- have such an effect is chip dependent. Reading the faults
- resets the control and returns the chip to a usable state
- if possible.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry>
- <entry>Flash controller voltage to the flash LED
- has exceeded the limit specific to the flash
- controller.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry>
- <entry>The flash strobe was still on when
- the timeout set by the user ---
- V4L2_CID_FLASH_TIMEOUT control --- has expired.
- Not all flash controllers may set this in all
- such conditions.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry>
- <entry>The flash controller has overheated.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry>
- <entry>The short circuit protection of the flash
- controller has been triggered.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry>
- <entry>Current in the LED power supply has exceeded the limit
- specific to the flash controller.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry>
- <entry>The flash controller has detected a short or open
- circuit condition on the indicator LED.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_UNDER_VOLTAGE</constant></entry>
- <entry>Flash controller voltage to the flash LED
- has been below the minimum limit specific to the flash
- controller.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_INPUT_VOLTAGE</constant></entry>
- <entry>The input voltage of the flash controller is below
- the limit under which strobing the flash at full current
- will not be possible.The condition persists until this flag
- is no longer set.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE</constant></entry>
- <entry>The temperature of the LED has exceeded its
- allowed upper limit.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable or disable charging of the xenon
- flash capacitor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Is the flash ready to strobe?
- Xenon flashes require their capacitors charged before
- strobing. LED flashes often require a cooldown period
- after strobe during which another strobe will not be
- possible. This is a read-only control.</entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
- </section>
-
- <section id="jpeg-controls">
- <title>JPEG Control Reference</title>
- <para>The JPEG class includes controls for common features of JPEG
- encoders and decoders. Currently it includes features for codecs
- implementing progressive baseline DCT compression process with
- Huffman entrophy coding.</para>
- <table pgwide="1" frame="none" id="jpeg-control-id">
- <title>JPEG Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The JPEG class descriptor. Calling
- &VIDIOC-QUERYCTRL; for this control will return a description of this
- control class.
-
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-jpeg-chroma-subsampling">
- <entry spanname="descr">The chroma subsampling factors describe how
- each component of an input image is sampled, in respect to maximum
- sample rate in each spatial dimension. See <xref linkend="itu-t81"/>,
- clause A.1.1. for more details. The <constant>
- V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how
- Cb and Cr components are downsampled after coverting an input image
- from RGB to Y'CbCr color space.
- </entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant>
- </entry><entry>No chroma subsampling, each pixel has
- Y, Cr and Cb values.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant>
- </entry><entry>Horizontally subsample Cr, Cb components
- by a factor of 2.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant>
- </entry><entry>Subsample Cr, Cb components horizontally
- and vertically by 2.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant>
- </entry><entry>Horizontally subsample Cr, Cb components
- by a factor of 4.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant>
- </entry><entry>Subsample Cr, Cb components horizontally
- by 4 and vertically by 2.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant>
- </entry><entry>Use only luminance component.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant>
- </entry><entry>integer</entry>
- </row>
- <row><entry spanname="descr">
- The restart interval determines an interval of inserting RSTm
- markers (m = 0..7). The purpose of these markers is to additionally
- reinitialize the encoder process, in order to process blocks of
- an image independently.
- For the lossy compression processes the restart interval unit is
- MCU (Minimum Coded Unit) and its value is contained in DRI
- (Define Restart Interval) marker. If <constant>
- V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0,
- DRI and RSTm markers will not be inserted.
- </entry>
- </row>
- <row id="jpeg-quality-control">
- <entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">
- <constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control
- determines trade-off between image quality and size.
- It provides simpler method for applications to control image quality,
- without a need for direct reconfiguration of luminance and chrominance
- quantization tables.
-
- In cases where a driver uses quantization tables configured directly
- by an application, using interfaces defined elsewhere, <constant>
- V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control should be set
- by driver to 0.
-
- <para>The value range of this control is driver-specific. Only
- positive, non-zero values are meaningful. The recommended range
- is 1 - 100, where larger values correspond to better image quality.
- </para>
- </entry>
- </row>
- <row id="jpeg-active-marker-control">
- <entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Specify which JPEG markers are included
- in compressed stream. This control is valid only for encoders.
- </entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry>
- <entry>Application data segment APP<subscript>0</subscript>.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry>
- <entry>Application data segment APP<subscript>1</subscript>.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry>
- <entry>Comment segment.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry>
- <entry>Quantization tables segment.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry>
- <entry>Huffman tables segment.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
- <para>For more details about JPEG specification, refer
- to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>,
- <xref linkend="w3c-jpeg-jfif"/>.</para>
- </section>
-
- <section id="image-source-controls">
- <title>Image Source Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link
- linkend="experimental">experimental</link> interface and may
- change in the future.</para>
- </note>
-
- <para>
- The Image Source control class is intended for low-level
- control of image source devices such as image sensors. The
- devices feature an analogue to digital converter and a bus
- transmitter to transmit the image data out of the device.
- </para>
-
- <table pgwide="1" frame="none" id="image-source-control-id">
- <title>Image Source Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The IMAGE_SOURCE class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_VBLANK</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Vertical blanking. The idle period
- after every frame during which no image data is produced.
- The unit of vertical blanking is a line. Every line has
- length of the image width plus horizontal blanking at the
- pixel rate defined by
- <constant>V4L2_CID_PIXEL_RATE</constant> control in the
- same sub-device.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_HBLANK</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Horizontal blanking. The idle
- period after every line of image data during which no
- image data is produced. The unit of horizontal blanking is
- pixels.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_ANALOGUE_GAIN</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Analogue gain is gain affecting
- all colour components in the pixel matrix. The gain
- operation is performed in the analogue domain before A/D
- conversion.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_RED</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Test pattern red colour component.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_GREENR</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Test pattern green (next to red)
- colour component.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_BLUE</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Test pattern blue colour component.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_GREENB</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Test pattern green (next to blue)
- colour component.
- </entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="image-process-controls">
- <title>Image Process Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link
- linkend="experimental">experimental</link> interface and may
- change in the future.</para>
- </note>
-
- <para>
- The Image Source control class is intended for low-level control of
- image processing functions. Unlike
- <constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant>, the controls in
- this class affect processing the image, and do not control capturing
- of it.
- </para>
-
- <table pgwide="1" frame="none" id="image-process-control-id">
- <title>Image Source Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_IMAGE_PROC_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The IMAGE_PROC class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_LINK_FREQ</constant></entry>
- <entry>integer menu</entry>
- </row>
- <row>
- <entry spanname="descr">Data bus frequency. Together with the
- media bus pixel code, bus type (clock cycles per sample), the
- data bus frequency defines the pixel rate
- (<constant>V4L2_CID_PIXEL_RATE</constant>) in the
- pixel array (or possibly elsewhere, if the device is not an
- image sensor). The frame rate can be calculated from the pixel
- clock, image width and height and horizontal and vertical
- blanking. While the pixel rate control may be defined elsewhere
- than in the subdev containing the pixel array, the frame rate
- cannot be obtained from that information. This is because only
- on the pixel array it can be assumed that the vertical and
- horizontal blanking information is exact: no other blanking is
- allowed in the pixel array. The selection of frame rate is
- performed by selecting the desired horizontal and vertical
- blanking. The unit of this control is Hz. </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PIXEL_RATE</constant></entry>
- <entry>64-bit integer</entry>
- </row>
- <row>
- <entry spanname="descr">Pixel rate in the source pads of
- the subdev. This control is read-only and its unit is
- pixels / second.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-test-pattern">
- <entry spanname="descr"> Some capture/display/sensor devices have
- the capability to generate test pattern images. These hardware
- specific test patterns can be used to test if a device is working
- properly.</entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="dv-controls">
- <title>Digital Video Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link
- linkend="experimental">experimental</link> interface and may
- change in the future.</para>
- </note>
-
- <para>
- The Digital Video control class is intended to control receivers
- and transmitters for <ulink url="http://en.wikipedia.org/wiki/Vga">VGA</ulink>,
- <ulink url="http://en.wikipedia.org/wiki/Digital_Visual_Interface">DVI</ulink>
- (Digital Visual Interface), HDMI (<xref linkend="hdmi" />) and DisplayPort (<xref linkend="dp" />).
- These controls are generally expected to be private to the receiver or transmitter
- subdevice that implements them, so they are only exposed on the
- <filename>/dev/v4l-subdev*</filename> device node.
- </para>
-
- <para>Note that these devices can have multiple input or output pads which are
- hooked up to e.g. HDMI connectors. Even though the subdevice will receive or
- transmit video from/to only one of those pads, the other pads can still be
- active when it comes to EDID (Extended Display Identification Data,
- <xref linkend="vesaedid" />) and HDCP (High-bandwidth Digital Content
- Protection System, <xref linkend="hdcp" />) processing, allowing the device
- to do the fairly slow EDID/HDCP handling in advance. This allows for quick
- switching between connectors.</para>
-
- <para>These pads appear in several of the controls in this section as
- bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad 1,
- etc. The maximum value of the control is the set of valid pads.</para>
-
- <table pgwide="1" frame="none" id="dv-control-id">
- <title>Digital Video Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The Digital Video class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_TX_HOTPLUG</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Many connectors have a hotplug pin which is high
- if EDID information is available from the source. This control shows the
- state of the hotplug pin as seen by the transmitter.
- Each bit corresponds to an output pad on the transmitter. If an output pad
- does not have an associated hotplug pin, then the bit for that pad will be 0.
- This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_TX_RXSENSE</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Rx Sense is the detection of pull-ups on the TMDS
- clock lines. This normally means that the sink has left/entered standby (i.e.
- the transmitter can sense that the receiver is ready to receive video).
- Each bit corresponds to an output pad on the transmitter. If an output pad
- does not have an associated Rx Sense, then the bit for that pad will be 0.
- This read-only control is applicable to DVI-D and HDMI devices.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_TX_EDID_PRESENT</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">When the transmitter sees the hotplug signal from the
- receiver it will attempt to read the EDID. If set, then the transmitter has read
- at least the first block (= 128 bytes).
- Each bit corresponds to an output pad on the transmitter. If an output pad
- does not support EDIDs, then the bit for that pad will be 0.
- This read-only control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_TX_MODE</constant></entry>
- <entry id="v4l2-dv-tx-mode">enum v4l2_dv_tx_mode</entry>
- </row>
- <row>
- <entry spanname="descr">HDMI transmitters can transmit in DVI-D mode (just video)
- or in HDMI mode (video + audio + auxiliary data). This control selects which mode
- to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
- This control is applicable to HDMI connectors.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_TX_RGB_RANGE</constant></entry>
- <entry id="v4l2-dv-rgb-range">enum v4l2_dv_rgb_range</entry>
- </row>
- <row>
- <entry spanname="descr">Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
- follows the RGB quantization range specified in the standard for the video interface
- (ie. <xref linkend="cea861" /> for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard
- to be compatible with sinks that have not implemented the standard correctly
- (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be
- used whereas limited range sets the range to (16 &lt;&lt; (N-8)) - (235 &lt;&lt; (N-8))
- where N is the number of bits per component.
- This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_RX_POWER_PRESENT</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Detects whether the receiver receives power from the source
- (e.g. HDMI carries 5V on one of the pins). This is often used to power an eeprom
- which contains EDID information, such that the source can read the EDID even if
- the sink is in standby/power off.
- Each bit corresponds to an input pad on the transmitter. If an input pad
- cannot detect whether power is present, then the bit for that pad will be 0.
- This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors.
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DV_RX_RGB_RANGE</constant></entry>
- <entry>enum v4l2_dv_rgb_range</entry>
- </row>
- <row>
- <entry spanname="descr">Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
- follows the RGB quantization range specified in the standard for the video interface
- (ie. <xref linkend="cea861" /> for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard
- to be compatible with sources that have not implemented the standard correctly
- (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be
- used whereas limited range sets the range to (16 &lt;&lt; (N-8)) - (235 &lt;&lt; (N-8))
- where N is the number of bits per component.
- This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
- </entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="fm-rx-controls">
- <title>FM Receiver Control Reference</title>
-
- <para>The FM Receiver (FM_RX) class includes controls for common features of
- FM Reception capable devices.</para>
-
- <table pgwide="1" frame="none" id="fm-rx-control-id">
- <title>FM_RX Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FM_RX_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The FM_RX class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RECEPTION</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enables/disables RDS
- reception by the radio tuner</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RX_PTY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Gets RDS Programme Type field.
-This encodes up to 31 pre-defined programme types.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RX_PS_NAME</constant>&nbsp;</entry>
- <entry>string</entry>
- </row>
- <row><entry spanname="descr">Gets the Programme Service name (PS_NAME).
-It is intended for static display on a receiver. It is the primary aid to listeners in programme service
-identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification,
-there is a full description of the correct character encoding for Programme Service name strings.
-Also from RDS specification, PS is usually a single eight character text. However, it is also possible
-to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
-with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RX_RADIO_TEXT</constant>&nbsp;</entry>
- <entry>string</entry>
- </row>
- <row><entry spanname="descr">Gets the Radio Text info. It is a textual description of
-what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
-programme-related information or any other text. In these cases, RadioText can be used in addition to
-<constant>V4L2_CID_RDS_RX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
-in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being
-used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
-to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
-with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_PROGRAM</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_RX_MUSIC_SPEECH</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it
-broadcasts speech. If the transmitter doesn't make this distinction, then it will be set.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant>&nbsp;</entry>
- <entry>enum v4l2_deemphasis</entry>
- </row>
- <row id="v4l2-deemphasis"><entry spanname="descr">Configures the de-emphasis value for reception.
-A de-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
-Depending on the region, a time constant of either 50 or 75 useconds is used. The enum&nbsp;v4l2_deemphasis
-defines possible values for de-emphasis. Here they are:</entry>
- </row><row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_DEEMPHASIS_DISABLED</constant>&nbsp;</entry>
- <entry>No de-emphasis is applied.</entry>
- </row>
- <row>
- <entry><constant>V4L2_DEEMPHASIS_50_uS</constant>&nbsp;</entry>
- <entry>A de-emphasis of 50 uS is used.</entry>
- </row>
- <row>
- <entry><constant>V4L2_DEEMPHASIS_75_uS</constant>&nbsp;</entry>
- <entry>A de-emphasis of 75 uS is used.</entry>
- </row>
- </tbody>
- </entrytbl>
-
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="detect-controls">
- <title>Detect Control Reference</title>
-
- <para>The Detect class includes controls for common features of
- various motion or object detection capable devices.</para>
-
- <table pgwide="1" frame="none" id="detect-control-id">
- <title>Detect Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DETECT_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The Detect class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DETECT_MD_MODE</constant>&nbsp;</entry>
- <entry>menu</entry>
- </row><row><entry spanname="descr">Sets the motion detection mode.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_DETECT_MD_MODE_DISABLED</constant>
- </entry><entry>Disable motion detection.</entry>
- </row>
- <row>
- <entry><constant>V4L2_DETECT_MD_MODE_GLOBAL</constant>
- </entry><entry>Use a single motion detection threshold.</entry>
- </row>
- <row>
- <entry><constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant>
- </entry><entry>The image is divided into a grid, each cell with its own
- motion detection threshold. These thresholds are set through the
- <constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> matrix control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant>
- </entry><entry>The image is divided into a grid, each cell with its own
- region value that specifies which per-region motion detection thresholds
- should be used. Each region has its own thresholds. How these per-region
- thresholds are set up is driver-specific. The region values for the grid are set
- through the <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> matrix
- control.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the global motion detection threshold to be
- used with the <constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> motion detection mode.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant>&nbsp;</entry>
- <entry>__u16 matrix</entry>
- </row>
- <row><entry spanname="descr">Sets the motion detection thresholds for each cell in the grid.
- To be used with the <constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant>
- motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the
- grid.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_DETECT_MD_REGION_GRID</constant>&nbsp;</entry>
- <entry>__u8 matrix</entry>
- </row>
- <row><entry spanname="descr">Sets the motion detection region value for each cell in the grid.
- To be used with the <constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant>
- motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the
- grid.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="rf-tuner-controls">
- <title>RF Tuner Control Reference</title>
-
- <para>
-The RF Tuner (RF_TUNER) class includes controls for common features of devices
-having RF tuner.
- </para>
- <para>
-In this context, RF tuner is radio receiver circuit between antenna and
-demodulator. It receives radio frequency (RF) from the antenna and converts that
-received signal to lower intermediate frequency (IF) or baseband frequency (BB).
-Tuners that could do baseband output are often called Zero-IF tuners. Older
-tuners were typically simple PLL tuners inside a metal box, whilst newer ones
-are highly integrated chips without a metal box "silicon tuners". These controls
-are mostly applicable for new feature rich silicon tuners, just because older
-tuners does not have much adjustable features.
- </para>
- <para>
-For more information about RF tuners see
-<ulink url="http://en.wikipedia.org/wiki/Tuner_%28radio%29">Tuner (radio)</ulink>
-and
-<ulink url="http://en.wikipedia.org/wiki/RF_front_end">RF front end</ulink>
-from Wikipedia.
- </para>
-
- <table pgwide="1" frame="none" id="rf-tuner-control-id">
- <title>RF_TUNER Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row>
- <row rowsep="1">
- <entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The RF_TUNER class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH_AUTO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables/disables tuner radio channel
-bandwidth configuration. In automatic mode bandwidth configuration is performed
-by the driver.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Filter(s) on tuner signal path are used to
-filter signal according to receiving party needs. Driver configures filters to
-fulfill desired bandwidth requirement. Used when V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not
-set. Unit is in Hz. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables/disables LNA automatic gain control (AGC)</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables/disables mixer automatic gain control (AGC)</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables/disables IF automatic gain control (AGC)</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">LNA (low noise amplifier) gain is first
-gain stage on the RF tuner signal path. It is located very close to tuner
-antenna input. Used when <constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> is not set.
-The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Mixer gain is second gain stage on the RF
-tuner signal path. It is located inside mixer block, where RF signal is
-down-converted by the mixer. Used when <constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant>
-is not set. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">IF gain is last gain stage on the RF tuner
-signal path. It is located on output of RF tuner. It controls signal level of
-intermediate frequency output or baseband output. Used when
-<constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant> is not set. The range and step are
-driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RF_TUNER_PLL_LOCK</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Is synthesizer PLL locked? RF tuner is
-receiving given frequency when that control is set. This is a read-only control.
-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-</section>
diff --git a/Documentation/DocBook/media/v4l/crop.pdf b/Documentation/DocBook/media/v4l/crop.pdf
deleted file mode 100644
index c9fb81cd32f3..000000000000
--- a/Documentation/DocBook/media/v4l/crop.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml
deleted file mode 100644
index e1c5f9406d6a..000000000000
--- a/Documentation/DocBook/media/v4l/dev-capture.xml
+++ /dev/null
@@ -1,110 +0,0 @@
- <title>Video Capture Interface</title>
-
- <para>Video capture devices sample an analog video signal and store
-the digitized images in memory. Today nearly all devices can capture
-at full 25 or 30 frames/second. With this interface applications can
-control the capture process and move images from the driver into user
-space.</para>
-
- <para>Conventionally V4L2 video capture devices are accessed through
-character device special files named <filename>/dev/video</filename>
-and <filename>/dev/video0</filename> to
-<filename>/dev/video63</filename> with major number 81 and minor
-numbers 0 to 63. <filename>/dev/video</filename> is typically a
-symbolic link to the preferred video device. Note the same device
-files are used for video output devices.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the video capture interface set the
-<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
-<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
-they may also support the <link linkend="overlay">video overlay</link>
-(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
-linkend="raw-vbi">raw VBI capture</link>
-(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
-the read/write or streaming I/O methods must be supported. Tuners and
-audio inputs are optional.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Video capture devices shall support <link
-linkend="audio">audio input</link>, <link
-linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
-<link linkend="crop">cropping and scaling</link> and <link
-linkend="streaming-par">streaming parameter</link> ioctls as needed.
-The <link linkend="video">video input</link> and <link
-linkend="standard">video standard</link> ioctls must be supported by
-all video capture devices.</para>
- </section>
-
- <section>
- <title>Image Format Negotiation</title>
-
- <para>The result of a capture operation is determined by
-cropping and image format parameters. The former select an area of the
-video picture to capture, the latter how images are stored in memory,
-&ie; in RGB or YUV format, the number of bits per pixel or width and
-height. Together they also define how images are scaled in the
-process.</para>
-
- <para>As usual these parameters are <emphasis>not</emphasis> reset
-at &func-open; time to permit Unix tool chains, programming a device
-and then reading from it as if it was a plain file. Well written V4L2
-applications ensure they really get what they want, including cropping
-and scaling.</para>
-
- <para>Cropping initialization at minimum requires to reset the
-parameters to defaults. An example is given in <xref
-linkend="crop" />.</para>
-
- <para>To query the current image format applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
-&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-pix-format; <structfield>pix</structfield> or the
-&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
-<structfield>fmt</structfield> union.</para>
-
- <para>To request different parameters applications set the
-<structfield>type</structfield> field of a &v4l2-format; as above and
-initialize all fields of the &v4l2-pix-format;
-<structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union, or better just modify the
-results of <constant>VIDIOC_G_FMT</constant>, and call the
-&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
-adjust the parameters and finally return the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does.</para>
-
- <para>Like <constant>VIDIOC_S_FMT</constant> the
-&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
-without disabling I/O or possibly time consuming hardware
-preparations.</para>
-
- <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
-are discussed in <xref linkend="pixfmt" />. See also the specification of the
-<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
-and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
-capture devices must implement both the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl, even if
-<constant>VIDIOC_S_FMT</constant> ignores all requests and always
-returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
-<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
- </section>
-
- <section>
- <title>Reading Images</title>
-
- <para>A video capture device may support the <link
-linkend="rw">read() function</link> and/or streaming (<link
-linkend="mmap">memory mapping</link> or <link
-linkend="userp">user pointer</link>) I/O. See <xref
-linkend="io" /> for details.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml
deleted file mode 100644
index ff44c16fc080..000000000000
--- a/Documentation/DocBook/media/v4l/dev-codec.xml
+++ /dev/null
@@ -1,27 +0,0 @@
- <title>Codec Interface</title>
-
- <para>A V4L2 codec can compress, decompress, transform, or otherwise
-convert video data from one format into another format, in memory. Typically
-such devices are memory-to-memory devices (i.e. devices with the
-<constant>V4L2_CAP_VIDEO_M2M</constant> or <constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant>
-capability set).
-</para>
-
- <para>A memory-to-memory video node acts just like a normal video node, but it
-supports both output (sending frames from memory to the codec hardware) and
-capture (receiving the processed frames from the codec hardware into memory)
-stream I/O. An application will have to setup the stream
-I/O for both sides and finally call &VIDIOC-STREAMON; for both capture and output
-to start the codec.</para>
-
- <para>Video compression codecs use the MPEG controls to setup their codec parameters
-(note that the MPEG controls actually support many more codecs than just MPEG).
-See <xref linkend="mpeg-controls"></xref>.</para>
-
- <para>Memory-to-memory devices can often be used as a shared resource: you can
-open the video node multiple times, each application setting up their own codec properties
-that are local to the file handle, and each can use it independently from the others.
-The driver will arbitrate access to the codec and reprogram it whenever another file
-handler gets access. This is different from the usual video node behavior where the video properties
-are global to the device (i.e. changing something through one file handle is visible
-through another file handle).</para>
diff --git a/Documentation/DocBook/media/v4l/dev-effect.xml b/Documentation/DocBook/media/v4l/dev-effect.xml
deleted file mode 100644
index 2350a67c0710..000000000000
--- a/Documentation/DocBook/media/v4l/dev-effect.xml
+++ /dev/null
@@ -1,17 +0,0 @@
- <title>Effect Devices Interface</title>
-
- <note>
- <title>Suspended</title>
-
- <para>This interface has been be suspended from the V4L2 API
-implemented in Linux 2.6 until we have more experience with effect
-device interfaces.</para>
- </note>
-
- <para>A V4L2 video effect device can do image effects, filtering, or
-combine two or more images or image streams. For example video
-transitions or wipes. Applications send data to be processed and
-receive the result data either with &func-read; and &func-write;
-functions, or through the streaming I/O mechanism.</para>
-
- <para>[to do]</para>
diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml
deleted file mode 100644
index 19f4becfae34..000000000000
--- a/Documentation/DocBook/media/v4l/dev-event.xml
+++ /dev/null
@@ -1,43 +0,0 @@
- <title>Event Interface</title>
-
- <para>The V4L2 event interface provides a means for a user to get
- immediately notified on certain conditions taking place on a device.
- This might include start of frame or loss of signal events, for
- example. Changes in the value or state of a V4L2 control can also be
- reported through events.
- </para>
-
- <para>To receive events, the events the user is interested in first must
- be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is
- subscribed, the events of subscribed types are dequeueable using the
- &VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using
- VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type V4L2_EVENT_ALL may
- be used to unsubscribe all the events the driver supports.</para>
-
- <para>The event subscriptions and event queues are specific to file
- handles. Subscribing an event on one file handle does not affect
- other file handles.</para>
-
- <para>The information on dequeueable events is obtained by using select or
- poll system calls on video devices. The V4L2 events use POLLPRI events on
- poll system call and exceptions on select system call.</para>
-
- <para>Starting with kernel 3.1 certain guarantees can be given with
- regards to events:<orderedlist>
- <listitem>
- <para>Each subscribed event has its own internal dedicated event queue.
-This means that flooding of one event type will not interfere with other
-event types.</para>
- </listitem>
- <listitem>
- <para>If the internal event queue for a particular subscribed event
-becomes full, then the oldest event in that queue will be dropped.</para>
- </listitem>
- <listitem>
- <para>Where applicable, certain event types can ensure that the payload
-of the oldest event that is about to be dropped will be merged with the payload
-of the next oldest event. Thus ensuring that no information is lost, but only an
-intermediate step leading up to that information. See the documentation for the
-event you want to subscribe to whether this is applicable for that event or not.</para>
- </listitem>
- </orderedlist></para>
diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml
deleted file mode 100644
index 54853329140b..000000000000
--- a/Documentation/DocBook/media/v4l/dev-osd.xml
+++ /dev/null
@@ -1,149 +0,0 @@
- <title>Video Output Overlay Interface</title>
- <subtitle>Also known as On-Screen Display (OSD)</subtitle>
-
- <para>Some video output devices can overlay a framebuffer image onto
-the outgoing video signal. Applications can set up such an overlay
-using this interface, which borrows structures and ioctls of the <link
-linkend="overlay">Video Overlay</link> interface.</para>
-
- <para>The OSD function is accessible through the same character
-special file as the <link linkend="capture">Video Output</link> function.
-Note the default function of such a <filename>/dev/video</filename> device
-is video capturing or output. The OSD function is only available after
-calling the &VIDIOC-S-FMT; ioctl.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the <wordasword>Video Output
-Overlay</wordasword> interface set the
-<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl.</para>
- </section>
-
- <section>
- <title>Framebuffer</title>
-
- <para>Contrary to the <wordasword>Video Overlay</wordasword>
-interface the framebuffer is normally implemented on the TV card and
-not the graphics card. On Linux it is accessible as a framebuffer
-device (<filename>/dev/fbN</filename>). Given a V4L2 device,
-applications can find the corresponding framebuffer device by calling
-the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
-physical address of the framebuffer in the
-<structfield>base</structfield> field of &v4l2-framebuffer;. The
-framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
-returns the same address in the <structfield>smem_start</structfield>
-field of struct <structname>fb_fix_screeninfo</structname>. The
-<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
-<structname>fb_fix_screeninfo</structname> are defined in the
-<filename>linux/fb.h</filename> header file.</para>
-
- <para>The width and height of the framebuffer depends on the
-current video standard. A V4L2 driver may reject attempts to change
-the video standard (or any other ioctl which would imply a framebuffer
-size change) with an &EBUSY; until all applications closed the
-framebuffer device.</para>
-
- <example>
- <title>Finding a framebuffer device for OSD</title>
-
- <programlisting>
-#include &lt;linux/fb.h&gt;
-
-&v4l2-framebuffer; fbuf;
-unsigned int i;
-int fb_fd;
-
-if (-1 == ioctl(fd, VIDIOC_G_FBUF, &amp;fbuf)) {
- perror("VIDIOC_G_FBUF");
- exit(EXIT_FAILURE);
-}
-
-for (i = 0; i &lt; 30; i++) {
- char dev_name[16];
- struct fb_fix_screeninfo si;
-
- snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
-
- fb_fd = open(dev_name, O_RDWR);
- if (-1 == fb_fd) {
- switch (errno) {
- case ENOENT: /* no such file */
- case ENXIO: /* no driver */
- continue;
-
- default:
- perror("open");
- exit(EXIT_FAILURE);
- }
- }
-
- if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
- if (si.smem_start == (unsigned long)fbuf.base)
- break;
- } else {
- /* Apparently not a framebuffer device. */
- }
-
- close(fb_fd);
- fb_fd = -1;
-}
-
-/* fb_fd is the file descriptor of the framebuffer device
- for the video output overlay, or -1 if no device was found. */
-</programlisting>
- </example>
- </section>
-
- <section>
- <title>Overlay Window and Scaling</title>
-
- <para>The overlay is controlled by source and target rectangles.
-The source rectangle selects a subsection of the framebuffer image to
-be overlaid, the target rectangle an area in the outgoing video signal
-where the image will appear. Drivers may or may not support scaling,
-and arbitrary sizes and positions of these rectangles. Further drivers
-may support any (or none) of the clipping/blending methods defined for
-the <link linkend="overlay">Video Overlay</link> interface.</para>
-
- <para>A &v4l2-window; defines the size of the source rectangle,
-its position in the framebuffer and the clipping/blending method to be
-used for the overlay. To get the current parameters applications set
-the <structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
-&VIDIOC-G-FMT; ioctl. The driver fills the
-<structname>v4l2_window</structname> substructure named
-<structfield>win</structfield>. It is not possible to retrieve a
-previously programmed clipping list or bitmap.</para>
-
- <para>To program the source rectangle applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
-the <structfield>win</structfield> substructure and call the
-&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
-hardware limits and returns the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does. Like
-<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
-used to learn about driver capabilities without actually changing
-driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
-after the overlay has been enabled.</para>
-
- <para>A &v4l2-crop; defines the size and position of the target
-rectangle. The scaling factor of the overlay is implied by the width
-and height given in &v4l2-window; and &v4l2-crop;. The cropping API
-applies to <wordasword>Video Output</wordasword> and <wordasword>Video
-Output Overlay</wordasword> devices in the same way as to
-<wordasword>Video Capture</wordasword> and <wordasword>Video
-Overlay</wordasword> devices, merely reversing the direction of the
-data flow. For more information see <xref linkend="crop" />.</para>
- </section>
-
- <section>
- <title>Enabling Overlay</title>
-
- <para>There is no V4L2 ioctl to enable or disable the overlay,
-however the framebuffer interface of the driver may support the
-<constant>FBIOBLANK</constant> ioctl.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-output.xml b/Documentation/DocBook/media/v4l/dev-output.xml
deleted file mode 100644
index 9130a3dc7880..000000000000
--- a/Documentation/DocBook/media/v4l/dev-output.xml
+++ /dev/null
@@ -1,106 +0,0 @@
- <title>Video Output Interface</title>
-
- <para>Video output devices encode stills or image sequences as
-analog video signal. With this interface applications can
-control the encoding process and move images from user space to
-the driver.</para>
-
- <para>Conventionally V4L2 video output devices are accessed through
-character device special files named <filename>/dev/video</filename>
-and <filename>/dev/video0</filename> to
-<filename>/dev/video63</filename> with major number 81 and minor
-numbers 0 to 63. <filename>/dev/video</filename> is typically a
-symbolic link to the preferred video device. Note the same device
-files are used for video capture devices.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the video output interface set the
-<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
-<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
-they may also support the <link linkend="raw-vbi">raw VBI
-output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
-least one of the read/write or streaming I/O methods must be
-supported. Modulators and audio outputs are optional.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Video output devices shall support <link
-linkend="audio">audio output</link>, <link
-linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
-<link linkend="crop">cropping and scaling</link> and <link
-linkend="streaming-par">streaming parameter</link> ioctls as needed.
-The <link linkend="video">video output</link> and <link
-linkend="standard">video standard</link> ioctls must be supported by
-all video output devices.</para>
- </section>
-
- <section>
- <title>Image Format Negotiation</title>
-
- <para>The output is determined by cropping and image format
-parameters. The former select an area of the video picture where the
-image will appear, the latter how images are stored in memory, &ie; in
-RGB or YUV format, the number of bits per pixel or width and height.
-Together they also define how images are scaled in the process.</para>
-
- <para>As usual these parameters are <emphasis>not</emphasis> reset
-at &func-open; time to permit Unix tool chains, programming a device
-and then writing to it as if it was a plain file. Well written V4L2
-applications ensure they really get what they want, including cropping
-and scaling.</para>
-
- <para>Cropping initialization at minimum requires to reset the
-parameters to defaults. An example is given in <xref
-linkend="crop" />.</para>
-
- <para>To query the current image format applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
-&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-pix-format; <structfield>pix</structfield> or the
-&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
-<structfield>fmt</structfield> union.</para>
-
- <para>To request different parameters applications set the
-<structfield>type</structfield> field of a &v4l2-format; as above and
-initialize all fields of the &v4l2-pix-format;
-<structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union, or better just modify the
-results of <constant>VIDIOC_G_FMT</constant>, and call the
-&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
-adjust the parameters and finally return the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does.</para>
-
- <para>Like <constant>VIDIOC_S_FMT</constant> the
-&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
-without disabling I/O or possibly time consuming hardware
-preparations.</para>
-
- <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
-are discussed in <xref linkend="pixfmt" />. See also the specification of the
-<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
-and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
-output devices must implement both the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl, even if
-<constant>VIDIOC_S_FMT</constant> ignores all requests and always
-returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
-<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
- </section>
-
- <section>
- <title>Writing Images</title>
-
- <para>A video output device may support the <link
-linkend="rw">write() function</link> and/or streaming (<link
-linkend="mmap">memory mapping</link> or <link
-linkend="userp">user pointer</link>) I/O. See <xref
-linkend="io" /> for details.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-overlay.xml b/Documentation/DocBook/media/v4l/dev-overlay.xml
deleted file mode 100644
index cc6e0c5c960c..000000000000
--- a/Documentation/DocBook/media/v4l/dev-overlay.xml
+++ /dev/null
@@ -1,368 +0,0 @@
- <title>Video Overlay Interface</title>
- <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>
-
- <para>Video overlay devices have the ability to genlock (TV-)video
-into the (VGA-)video signal of a graphics card, or to store captured
-images directly in video memory of a graphics card, typically with
-clipping. This can be considerable more efficient than capturing
-images and displaying them by other means. In the old days when only
-nuclear power plants needed cooling towers this used to be the only
-way to put live video into a window.</para>
-
- <para>Video overlay devices are accessed through the same character
-special files as <link linkend="capture">video capture</link> devices.
-Note the default function of a <filename>/dev/video</filename> device
-is video capturing. The overlay function is only available after
-calling the &VIDIOC-S-FMT; ioctl.</para>
-
- <para>The driver may support simultaneous overlay and capturing
-using the read/write and streaming I/O methods. If so, operation at
-the nominal frame rate of the video standard is not guaranteed. Frames
-may be directed away from overlay to capture, or one field may be used
-for overlay and the other for capture if the capture parameters permit
-this.</para>
-
- <para>Applications should use different file descriptors for
-capturing and overlay. This must be supported by all drivers capable
-of simultaneous capturing and overlay. Optionally these drivers may
-also permit capturing and overlay with a single file descriptor for
-compatibility with V4L and earlier versions of V4L2.<footnote>
- <para>A common application of two file descriptors is the
-XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
-a V4L2 application. While the X server controls video overlay, the
-application can take advantage of memory mapping and DMA.</para>
- <para>In the opinion of the designers of this API, no driver
-writer taking the efforts to support simultaneous capturing and
-overlay will restrict this ability by requiring a single file
-descriptor, as in V4L and earlier versions of V4L2. Making this
-optional means applications depending on two file descriptors need
-backup routines to be compatible with all drivers, which is
-considerable more work than using two fds in applications which do
-not. Also two fd's fit the general concept of one file descriptor for
-each logical stream. Hence as a complexity trade-off drivers
-<emphasis>must</emphasis> support two file descriptors and
-<emphasis>may</emphasis> support single fd operation.</para>
- </footnote></para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the video overlay interface set the
-<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
-below must be supported. Tuners and audio inputs are optional.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Video overlay devices shall support <link
-linkend="audio">audio input</link>, <link
-linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
-<link linkend="crop">cropping and scaling</link> and <link
-linkend="streaming-par">streaming parameter</link> ioctls as needed.
-The <link linkend="video">video input</link> and <link
-linkend="standard">video standard</link> ioctls must be supported by
-all video overlay devices.</para>
- </section>
-
- <section>
- <title>Setup</title>
-
- <para>Before overlay can commence applications must program the
-driver with frame buffer parameters, namely the address and size of
-the frame buffer and the image format, for example RGB 5:6:5. The
-&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
-and set these parameters, respectively. The
-<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
-allows to set up DMA into physical memory, bypassing the memory
-protection mechanisms of the kernel. Only the superuser can change the
-frame buffer address and size. Users are not supposed to run TV
-applications as root or with SUID bit set. A small helper application
-with suitable privileges should query the graphics system and program
-the V4L2 driver at the appropriate time.</para>
-
- <para>Some devices add the video overlay to the output signal
-of the graphics card. In this case the frame buffer is not modified by
-the video device, and the frame buffer address and pixel format are
-not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
-is not privileged. An application can check for this type of device by
-calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>
-
- <para>A driver may support any (or none) of five clipping/blending
-methods:<orderedlist>
- <listitem>
- <para>Chroma-keying displays the overlaid image only where
-pixels in the primary graphics surface assume a certain color.</para>
- </listitem>
- <listitem>
- <para>A bitmap can be specified where each bit corresponds
-to a pixel in the overlaid image. When the bit is set, the
-corresponding video pixel is displayed, otherwise a pixel of the
-graphics surface.</para>
- </listitem>
- <listitem>
- <para>A list of clipping rectangles can be specified. In
-these regions <emphasis>no</emphasis> video is displayed, so the
-graphics surface can be seen here.</para>
- </listitem>
- <listitem>
- <para>The framebuffer has an alpha channel that can be used
-to clip or blend the framebuffer with the video.</para>
- </listitem>
- <listitem>
- <para>A global alpha value can be specified to blend the
-framebuffer contents with video images.</para>
- </listitem>
- </orderedlist></para>
-
- <para>When simultaneous capturing and overlay is supported and
-the hardware prohibits different image and frame buffer formats, the
-format requested first takes precedence. The attempt to capture
-(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
-&EBUSY; or return accordingly modified parameters..</para>
- </section>
-
- <section>
- <title>Overlay Window</title>
-
- <para>The overlaid image is determined by cropping and overlay
-window parameters. The former select an area of the video picture to
-capture, the latter how images are overlaid and clipped. Cropping
-initialization at minimum requires to reset the parameters to
-defaults. An example is given in <xref linkend="crop" />.</para>
-
- <para>The overlay window is described by a &v4l2-window;. It
-defines the size of the image, its position over the graphics surface
-and the clipping to be applied. To get the current parameters
-applications set the <structfield>type</structfield> field of a
-&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and
-call the &VIDIOC-G-FMT; ioctl. The driver fills the
-<structname>v4l2_window</structname> substructure named
-<structfield>win</structfield>. It is not possible to retrieve a
-previously programmed clipping list or bitmap.</para>
-
- <para>To program the overlay window applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the
-<structfield>win</structfield> substructure and call the
-&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
-hardware limits and returns the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does. Like
-<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
-used to learn about driver capabilities without actually changing
-driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
-after the overlay has been enabled.</para>
-
- <para>The scaling factor of the overlaid image is implied by the
-width and height given in &v4l2-window; and the size of the cropping
-rectangle. For more information see <xref linkend="crop" />.</para>
-
- <para>When simultaneous capturing and overlay is supported and
-the hardware prohibits different image and window sizes, the size
-requested first takes precedence. The attempt to capture or overlay as
-well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
-modified parameters.</para>
-
- <table pgwide="1" frame="none" id="v4l2-window">
- <title>struct <structname>v4l2_window</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>w</structfield></entry>
- <entry>Size and position of the window relative to the
-top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
-window can extend the frame buffer width and height, the
-<structfield>x</structfield> and <structfield>y</structfield>
-coordinates can be negative, and it can lie completely outside the
-frame buffer. The driver clips the window accordingly, or if that is
-not possible, modifies its size and/or position.</entry>
- </row>
- <row>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>Applications set this field to determine which
-video field shall be overlaid, typically one of
-<constant>V4L2_FIELD_ANY</constant> (0),
-<constant>V4L2_FIELD_TOP</constant>,
-<constant>V4L2_FIELD_BOTTOM</constant> or
-<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
-a different field order and return the actual setting here.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>chromakey</structfield></entry>
- <entry>When chroma-keying has been negotiated with
-&VIDIOC-S-FBUF; applications set this field to the desired pixel value
-for the chroma key. The format is the same as the pixel format of the
-framebuffer (&v4l2-framebuffer;
-<structfield>fmt.pixelformat</structfield> field), with bytes in host
-order. E.&nbsp;g. for <link
-linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
-the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
-endian host.</entry>
- </row>
- <row>
- <entry>&v4l2-clip; *</entry>
- <entry><structfield>clips</structfield></entry>
- <entry>When chroma-keying has <emphasis>not</emphasis>
-been negotiated and &VIDIOC-G-FBUF; indicated this capability,
-applications can set this field to point to an array of
-clipping rectangles.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Like the window coordinates
-<structfield>w</structfield>, clipping rectangles are defined relative
-to the top, left corner of the frame buffer. However clipping
-rectangles must not extend the frame buffer width and height, and they
-must not overlap. If possible applications should merge adjacent
-rectangles. Whether this must create x-y or y-x bands, or the order of
-rectangles, is not defined. When clip lists are not supported the
-driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
-are undefined.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>clipcount</structfield></entry>
- <entry>When the application set the
-<structfield>clips</structfield> field, this field must contain the
-number of clipping rectangles in the list. When clip lists are not
-supported the driver ignores this field, its contents after calling
-<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
-supported but no clipping is desired this field must be set to
-zero.</entry>
- </row>
- <row>
- <entry>void *</entry>
- <entry><structfield>bitmap</structfield></entry>
- <entry>When chroma-keying has
-<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
-this capability, applications can set this field to point to a
-clipping bit mask.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>It must be of the same size
-as the window, <structfield>w.width</structfield> and
-<structfield>w.height</structfield>. Each bit corresponds to a pixel
-in the overlaid image, which is displayed only when the bit is
-<emphasis>set</emphasis>. Pixel coordinates translate to bits like:
-<programlisting>
-((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] &amp; (1 &lt;&lt; (x &amp; 7))</programlisting></para><para>where <structfield>0</structfield> &le; x &lt;
-<structfield>w.width</structfield> and <structfield>0</structfield> &le;
-y &lt;<structfield>w.height</structfield>.<footnote>
- <para>Should we require
- <structfield>w.width</structfield> to be a multiple of
- eight?</para>
- </footnote></para><para>When a clipping
-bit mask is not supported the driver ignores this field, its contents
-after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
-but no clipping is desired this field must be set to
-<constant>NULL</constant>.</para><para>Applications need not create a
-clip list or bit mask. When they pass both, or despite negotiating
-chroma-keying, the results are undefined. Regardless of the chosen
-method, the clipping abilities of the hardware may be limited in
-quantity or quality. The results when these limits are exceeded are
-undefined.<footnote>
- <para>When the image is written into frame buffer
-memory it will be undesirable if the driver clips out less pixels
-than expected, because the application and graphics system are not
-aware these regions need to be refreshed. The driver should clip out
-more pixels or not write the image at all.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>global_alpha</structfield></entry>
- <entry>The global alpha value used to blend the
-framebuffer with video images, if global alpha blending has been
-negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
-&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Note this field was added in Linux 2.6.23, extending the structure. However
-the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
-which take a pointer to a <link
-linkend="v4l2-format">v4l2_format</link> parent structure with padding
-bytes at the end, are not affected.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-clip">
- <title>struct <structname>v4l2_clip</structname><footnote>
- <para>The X Window system defines "regions" which are
-vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
-x1 and height = y2 - y1, so one cannot pass X11 clip lists
-directly.</para>
- </footnote></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>c</structfield></entry>
- <entry>Coordinates of the clipping rectangle, relative to
-the top, left corner of the frame buffer. Only window pixels
-<emphasis>outside</emphasis> all clipping rectangles are
-displayed.</entry>
- </row>
- <row>
- <entry>&v4l2-clip; *</entry>
- <entry><structfield>next</structfield></entry>
- <entry>Pointer to the next clipping rectangle, NULL when
-this is the last rectangle. Drivers ignore this field, it cannot be
-used to pass a linked list of clipping rectangles.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- NB for easier reading this table is duplicated
- in the vidioc-cropcap chapter.-->
-
- <table pgwide="1" frame="none" id="v4l2-rect">
- <title>struct <structname>v4l2_rect</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__s32</entry>
- <entry><structfield>left</structfield></entry>
- <entry>Horizontal offset of the top, left corner of the
-rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>top</structfield></entry>
- <entry>Vertical offset of the top, left corner of the
-rectangle, in pixels. Offsets increase to the right and down.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Width of the rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Height of the rectangle, in pixels.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Enabling Overlay</title>
-
- <para>To start or stop the frame buffer overlay applications call
-the &VIDIOC-OVERLAY; ioctl.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-radio.xml b/Documentation/DocBook/media/v4l/dev-radio.xml
deleted file mode 100644
index 3e6ac73b36af..000000000000
--- a/Documentation/DocBook/media/v4l/dev-radio.xml
+++ /dev/null
@@ -1,49 +0,0 @@
- <title>Radio Interface</title>
-
- <para>This interface is intended for AM and FM (analog) radio
-receivers and transmitters.</para>
-
- <para>Conventionally V4L2 radio devices are accessed through
-character device special files named <filename>/dev/radio</filename>
-and <filename>/dev/radio0</filename> to
-<filename>/dev/radio63</filename> with major number 81 and minor
-numbers 64 to 127.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the radio interface set the
-<constant>V4L2_CAP_RADIO</constant> and
-<constant>V4L2_CAP_TUNER</constant> or
-<constant>V4L2_CAP_MODULATOR</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of
-capability flags are reserved for future extensions.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Radio devices can support <link
-linkend="control">controls</link>, and must support the <link
-linkend="tuner">tuner or modulator</link> ioctls.</para>
-
- <para>They do not support the video input or output, audio input
-or output, video standard, cropping and scaling, compression and
-streaming parameter, or overlay ioctls. All other ioctls and I/O
-methods are reserved for future extensions.</para>
- </section>
-
- <section>
- <title>Programming</title>
-
- <para>Radio devices may have a couple audio controls (as discussed
-in <xref linkend="control" />) such as a volume control, possibly custom
-controls. Further all radio devices have one tuner or modulator (these are
-discussed in <xref linkend="tuner" />) with index number zero to select
-the radio frequency and to determine if a monaural or FM stereo
-program is received/emitted. Drivers switch automatically between AM and FM
-depending on the selected frequency. The &VIDIOC-G-TUNER; or
-&VIDIOC-G-MODULATOR; ioctl
-reports the supported frequency range.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
deleted file mode 100644
index f4b61b6ce3c2..000000000000
--- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
+++ /dev/null
@@ -1,345 +0,0 @@
- <title>Raw VBI Data Interface</title>
-
- <para>VBI is an abbreviation of Vertical Blanking Interval, a gap
-in the sequence of lines of an analog video signal. During VBI
-no picture information is transmitted, allowing some time while the
-electron beam of a cathode ray tube TV returns to the top of the
-screen. Using an oscilloscope you will find here the vertical
-synchronization pulses and short data packages ASK
-modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal
-level represents a '1' bit, a low level a '0' bit.</para></footnote>
-onto the video signal. These are transmissions of services such as
-Teletext or Closed Caption.</para>
-
- <para>Subject of this interface type is raw VBI data, as sampled off
-a video signal, or to be added to a signal for output.
-The data format is similar to uncompressed video images, a number of
-lines times a number of samples per line, we call this a VBI image.</para>
-
- <para>Conventionally V4L2 VBI devices are accessed through character
-device special files named <filename>/dev/vbi</filename> and
-<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with
-major number 81 and minor numbers 224 to 255.
-<filename>/dev/vbi</filename> is typically a symbolic link to the
-preferred VBI device. This convention applies to both input and output
-devices.</para>
-
- <para>To address the problems of finding related video and VBI
-devices VBI capturing and output is also available as device function
-under <filename>/dev/video</filename>. To capture or output raw VBI
-data with these devices applications must call the &VIDIOC-S-FMT;
-ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing
-or output is the default device function.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the raw VBI capturing or output API set
-the <constant>V4L2_CAP_VBI_CAPTURE</constant> or
-<constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
-read/write, streaming or asynchronous I/O methods must be
-supported. VBI devices may or may not have a tuner or modulator.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>VBI devices shall support <link linkend="video">video
-input or output</link>, <link linkend="tuner">tuner or
-modulator</link>, and <link linkend="control">controls</link> ioctls
-as needed. The <link linkend="standard">video standard</link> ioctls provide
-information vital to program a VBI device, therefore must be
-supported.</para>
- </section>
-
- <section>
- <title>Raw VBI Format Negotiation</title>
-
- <para>Raw VBI sampling abilities can vary, in particular the
-sampling frequency. To properly interpret the data V4L2 specifies an
-ioctl to query the sampling parameters. Moreover, to allow for some
-flexibility applications can also suggest different parameters.</para>
-
- <para>As usual these parameters are <emphasis>not</emphasis>
-reset at &func-open; time to permit Unix tool chains, programming a
-device and then reading from it as if it was a plain file. Well
-written V4L2 applications should always ensure they really get what
-they want, requesting reasonable parameters and then checking if the
-actual parameters are suitable.</para>
-
- <para>To query the current raw VBI capture parameters
-applications set the <structfield>type</structfield> field of a
-&v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or
-<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the
-&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-vbi-format; <structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union.</para>
-
- <para>To request different parameters applications set the
-<structfield>type</structfield> field of a &v4l2-format; as above and
-initialize all fields of the &v4l2-vbi-format;
-<structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union, or better just modify the
-results of <constant>VIDIOC_G_FMT</constant>, and call the
-&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return
-an &EINVAL; only when the given parameters are ambiguous, otherwise
-they modify the parameters according to the hardware capabilites and
-return the actual parameters. When the driver allocates resources at
-this point, it may return an &EBUSY; to indicate the returned
-parameters are valid but the required resources are currently not
-available. That may happen for instance when the video and VBI areas
-to capture would overlap, or when the driver supports multiple opens
-and another process already requested VBI capturing or output. Anyway,
-applications must expect other resource allocation points which may
-return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl
-and the first read(), write() and select() call.</para>
-
- <para>VBI devices must implement both the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl, even if
-<constant>VIDIOC_S_FMT</constant> ignores all requests and always
-returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
-<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
-
- <table pgwide="1" frame="none" id="v4l2-vbi-format">
- <title>struct <structname>v4l2_vbi_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>sampling_rate</structfield></entry>
- <entry>Samples per second, i.&nbsp;e. unit 1 Hz.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>offset</structfield></entry>
- <entry><para>Horizontal offset of the VBI image,
-relative to the leading edge of the line synchronization pulse and
-counted in samples: The first sample in the VBI image will be located
-<structfield>offset</structfield> /
-<structfield>sampling_rate</structfield> seconds following the leading
-edge. See also <xref linkend="vbi-hsync" />.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>samples_per_line</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>sample_format</structfield></entry>
- <entry><para>Defines the sample format as in <xref
-linkend="pixfmt" />, a four-character-code.<footnote>
- <para>A few devices may be unable to
-sample VBI data at all but can extend the video capture window to the
-VBI region.</para>
- </footnote> Usually this is
-<constant>V4L2_PIX_FMT_GREY</constant>, i.&nbsp;e. each sample
-consists of 8 bits with lower values oriented towards the black level.
-Do not assume any other correlation of values with the signal level.
-For example, the MSB does not necessarily indicate if the signal is
-'high' or 'low' because 128 may not be the mean value of the
-signal. Drivers shall not convert the sample format by software.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>start</structfield>[2]</entry>
- <entry>This is the scanning system line number
-associated with the first line of the VBI image, of the first and the
-second field respectively. See <xref linkend="vbi-525" /> and
-<xref linkend="vbi-625" /> for valid values.
-The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
-<constant>V4L2_VBI_ITU_525_F2_START</constant>,
-<constant>V4L2_VBI_ITU_625_F1_START</constant> and
-<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start line
-numbers for each field for each 525 or 625 line format as a convenience.
-Don't forget that ITU line numbering starts at 1, not 0.
-VBI input drivers can return start values 0 if the hardware cannot
-reliable identify scanning lines, VBI acquisition may not require this
-information.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>count</structfield>[2]</entry>
- <entry>The number of lines in the first and second
-field image, respectively.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>Drivers should be as
-flexibility as possible. For example, it may be possible to extend or
-move the VBI capture window down to the picture area, implementing a
-'full field mode' to capture data service transmissions embedded in
-the picture.</para><para>An application can set the first or second
-<structfield>count</structfield> value to zero if no data is required
-from the respective field; <structfield>count</structfield>[1] if the
-scanning system is progressive, &ie; not interlaced. The
-corresponding start value shall be ignored by the application and
-driver. Anyway, drivers may not support single field capturing and
-return both count values non-zero.</para><para>Both
-<structfield>count</structfield> values set to zero, or line numbers
-outside the bounds depicted in <xref linkend="vbi-525" /> and <xref
- linkend="vbi-625" />, or a field image covering
-lines of two fields, are invalid and shall not be returned by the
-driver.</para><para>To initialize the <structfield>start</structfield>
-and <structfield>count</structfield> fields, applications must first
-determine the current video standard selection. The &v4l2-std-id; or
-the <structfield>framelines</structfield> field of &v4l2-standard; can
-be evaluated for this purpose.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>See <xref linkend="vbifmt-flags" /> below. Currently
-only drivers set flags, applications must set this field to
-zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>This array is reserved for future extensions.
-Drivers and applications must set it to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="vbifmt-flags">
- <title>Raw VBI Format Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_VBI_UNSYNC</constant></entry>
- <entry>0x0001</entry>
- <entry><para>This flag indicates hardware which does not
-properly distinguish between fields. Normally the VBI image stores the
-first field (lower scanning line numbers) first in memory. This may be
-a top or bottom field depending on the video standard. When this flag
-is set the first or second field may be stored first, however the
-fields are still in correct temporal order with the older field first
-in memory.<footnote>
- <para>Most VBI services transmit on both fields, but
-some have different semantics depending on the field number. These
-cannot be reliable decoded or encoded when
-<constant>V4L2_VBI_UNSYNC</constant> is set.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry><constant>V4L2_VBI_INTERLACED</constant></entry>
- <entry>0x0002</entry>
- <entry>By default the two field images will be passed
-sequentially; all lines of the first field followed by all lines of
-the second field (compare <xref linkend="field-order" />
-<constant>V4L2_FIELD_SEQ_TB</constant> and
-<constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom
-field is first in memory depends on the video standard). When this
-flag is set, the two fields are interlaced (cf.
-<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the
-first field followed by the first line of the second field, then the
-two second lines, and so on. Such a layout may be necessary when the
-hardware has been programmed to capture or output interlaced video
-images and is unable to separate the fields for VBI capturing at
-the same time. For simplicity setting this flag implies that both
-<structfield>count</structfield> values are equal and non-zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <figure id="vbi-hsync">
- <title>Line synchronization</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="vbi_hsync.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="vbi_hsync.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>Line synchronization diagram</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <figure id="vbi-525">
- <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="vbi_525.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="vbi_525.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>NTSC field synchronization diagram</phrase>
- </textobject>
- <caption>
- <para>(1) For the purpose of this specification field 2
-starts in line 264 and not 263.5 because half line capturing is not
-supported.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <figure id="vbi-625">
- <title>ITU-R 625 line numbering</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="vbi_625.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="vbi_625.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>PAL/SECAM field synchronization diagram</phrase>
- </textobject>
- <caption>
- <para>(1) For the purpose of this specification field 2
-starts in line 314 and not 313.5 because half line capturing is not
-supported.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>Remember the VBI image format depends on the selected
-video standard, therefore the application must choose a new standard or
-query the current standard first. Attempts to read or write data ahead
-of format negotiation, or after switching the video standard which may
-invalidate the negotiated VBI parameters, should be refused by the
-driver. A format change during active I/O is not permitted.</para>
- </section>
-
- <section>
- <title>Reading and writing VBI images</title>
-
- <para>To assure synchronization with the field number and easier
-implementation, the smallest unit of data passed at a time is one
-frame, consisting of two fields of VBI images immediately following in
-memory.</para>
-
- <para>The total size of a frame computes as follows:</para>
-
- <programlisting>
-(<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) *
-<structfield>samples_per_line</structfield> * sample size in bytes</programlisting>
-
- <para>The sample size is most likely always one byte,
-applications must check the <structfield>sample_format</structfield>
-field though, to function properly with other drivers.</para>
-
- <para>A VBI device may support <link
- linkend="rw">read/write</link> and/or streaming (<link
- linkend="mmap">memory mapping</link> or <link
- linkend="userp">user pointer</link>) I/O. The latter bears the
-possibility of synchronizing video and
-VBI data by using buffer timestamps.</para>
-
- <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(),
-write() and select() call can be resource allocation points returning
-an &EBUSY; if the required hardware resources are temporarily
-unavailable, for example the device is already in use by another
-process.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml
deleted file mode 100644
index be2f33737323..000000000000
--- a/Documentation/DocBook/media/v4l/dev-rds.xml
+++ /dev/null
@@ -1,196 +0,0 @@
- <title>RDS Interface</title>
-
- <para>The Radio Data System transmits supplementary
-information in binary format, for example the station name or travel
-information, on an inaudible audio subcarrier of a radio program. This
-interface is aimed at devices capable of receiving and/or transmitting RDS
-information.</para>
-
- <para>For more information see the core RDS standard <xref linkend="iec62106" />
-and the RBDS standard <xref linkend="nrsc4" />.</para>
-
- <para>Note that the RBDS standard as is used in the USA is almost identical
-to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the
-fields have slightly different meanings. See the RBDS standard for more
-information.</para>
-
- <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
-This is a proprietary format which seems to be discontinued. The RDS interface does not
-support this format. Should support for MMBS (or the so-called 'E blocks' in general)
-be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the RDS capturing API set
-the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS
-will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in
-the <structfield>capability</structfield> field of &v4l2-tuner;. If
-the driver only passes RDS blocks without interpreting the data
-the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be
-set, see <link linkend="reading-rds-data">Reading RDS data</link>.
-For future use the
-flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been
-defined. However, a driver for a radio tuner with this capability does
-not yet exist, so if you are planning to write such a driver you
-should discuss this on the linux-media mailing list: &v4l-ml;.</para>
-
- <para> Whether an RDS signal is present can be detected by looking
-at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;:
-the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data
-was detected.</para>
-
- <para>Devices supporting the RDS output API
-set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl.
-Any modulator that supports RDS will set the
-<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
-field of &v4l2-modulator;.
-In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
-bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.
-If the driver only passes RDS blocks without interpreting the data
-the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the
-tuner is capable of handling RDS entities like program identification codes and radio
-text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set,
-see <link linkend="writing-rds-data">Writing RDS data</link> and
-<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para>
- </section>
-
- <section id="reading-rds-data">
- <title>Reading RDS data</title>
-
- <para>RDS data can be read from the radio device
-with the &func-read; function. The data is packed in groups of three bytes.</para>
- </section>
-
- <section id="writing-rds-data">
- <title>Writing RDS data</title>
-
- <para>RDS data can be written to the radio device
-with the &func-write; function. The data is packed in groups of three bytes,
-as follows:</para>
- </section>
-
- <section>
- <title>RDS datastructures</title>
- <table frame="none" pgwide="1" id="v4l2-rds-data">
- <title>struct
-<structname>v4l2_rds_data</structname></title>
- <tgroup cols="3">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="5*" />
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>lsb</structfield></entry>
- <entry>Least Significant Byte of RDS Block</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>msb</structfield></entry>
- <entry>Most Significant Byte of RDS Block</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>block</structfield></entry>
- <entry>Block description</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table frame="none" pgwide="1" id="v4l2-rds-block">
- <title>Block description</title>
- <tgroup cols="2">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="5*" />
- <tbody valign="top">
- <row>
- <entry>Bits 0-2</entry>
- <entry>Block (aka offset) of the received data.</entry>
- </row>
- <row>
- <entry>Bits 3-5</entry>
- <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
- </row>
- <row>
- <entry>Bit 6</entry>
- <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
- </row>
- <row>
- <entry>Bit 7</entry>
- <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
- <title>Block defines</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="1*" />
- <colspec colname="c4" colwidth="5*" />
- <tbody valign="top">
- <row>
- <entry>V4L2_RDS_BLOCK_MSK</entry>
- <entry> </entry>
- <entry>7</entry>
- <entry>Mask for bits 0-2 to get the block ID.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_A</entry>
- <entry> </entry>
- <entry>0</entry>
- <entry>Block A.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_B</entry>
- <entry> </entry>
- <entry>1</entry>
- <entry>Block B.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_C</entry>
- <entry> </entry>
- <entry>2</entry>
- <entry>Block C.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_D</entry>
- <entry> </entry>
- <entry>3</entry>
- <entry>Block D.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_C_ALT</entry>
- <entry> </entry>
- <entry>4</entry>
- <entry>Block C'.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_INVALID</entry>
- <entry>read-only</entry>
- <entry>7</entry>
- <entry>An invalid block.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
- <entry>read-only</entry>
- <entry>0x40</entry>
- <entry>A bit error was detected but corrected.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_ERROR</entry>
- <entry>read-only</entry>
- <entry>0x80</entry>
- <entry>An uncorrectable error occurred.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml
deleted file mode 100644
index f8903568a243..000000000000
--- a/Documentation/DocBook/media/v4l/dev-sdr.xml
+++ /dev/null
@@ -1,120 +0,0 @@
- <title>Software Defined Radio Interface (SDR)</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>
-SDR is an abbreviation of Software Defined Radio, the radio device
-which uses application software for modulation or demodulation. This interface
-is intended for controlling and data streaming of such devices.
- </para>
-
- <para>
-SDR devices are accessed through character device special files named
-<filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename>
-with major number 81 and dynamically allocated minor numbers 0 to 255.
- </para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>
-Devices supporting the SDR receiver interface set the
-<constant>V4L2_CAP_SDR_CAPTURE</constant> and
-<constant>V4L2_CAP_TUNER</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an
-Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver.
-At least one of the read/write, streaming or asynchronous I/O methods must
-be supported.
- </para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>
-SDR devices can support <link linkend="control">controls</link>, and must
-support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used
-for setting the ADC sampling rate (sampling frequency) and the possible RF tuner
-frequency.
- </para>
-
- <para>
-The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and
-the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The
-tuner index of the RF tuner (if any) must always follow the ADC tuner index.
-Normally the ADC tuner is #0 and the RF tuner is #1.
- </para>
-
- <para>
-The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported.
- </para>
- </section>
-
- <section>
- <title>Data Format Negotiation</title>
-
- <para>
-The SDR capture device uses the <link linkend="format">format</link> ioctls to
-select the capture format. Both the sampling resolution and the data streaming
-format are bound to that selectable format. In addition to the basic
-<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl
-must be supported as well.
- </para>
-
- <para>
-To use the <link linkend="format">format</link> ioctls applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format;
-<structfield>sdr</structfield> member of the <structfield>fmt</structfield>
-union as needed per the desired operation.
-Currently there is two fields, <structfield>pixelformat</structfield> and
-<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are
-used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC
-code of the data format. The <structfield>buffersize</structfield> field is
-maximum buffer size in bytes required for data transfer, set by the driver in
-order to inform application.
- </para>
-
- <table pgwide="1" frame="none" id="v4l2-sdr-format">
- <title>struct <structname>v4l2_sdr_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>
-The data format or type of compression, set by the application. This is a
-little endian <link linkend="v4l2-fourcc">four character code</link>.
-V4L2 defines SDR formats in <xref linkend="sdr-formats" />.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>buffersize</structfield></entry>
- <entry>
-Maximum size in bytes required for data. Value is set by the driver.
- </entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>reserved[24]</structfield></entry>
- <entry>This array is reserved for future extensions.
-Drivers and applications must set it to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
-An SDR device may support <link linkend="rw">read/write</link>
-and/or streaming (<link linkend="mmap">memory mapping</link>
-or <link linkend="userp">user pointer</link>) I/O.
- </para>
-
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
deleted file mode 100644
index 0aec62ed2bf8..000000000000
--- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
+++ /dev/null
@@ -1,706 +0,0 @@
- <title>Sliced VBI Data Interface</title>
-
- <para>VBI stands for Vertical Blanking Interval, a gap in the
-sequence of lines of an analog video signal. During VBI no picture
-information is transmitted, allowing some time while the electron beam
-of a cathode ray tube TV returns to the top of the screen.</para>
-
- <para>Sliced VBI devices use hardware to demodulate data transmitted
-in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by
-software, see also the <link linkend="raw-vbi">raw VBI
-interface</link>. The data is passed as short packets of fixed size,
-covering one scan line each. The number of packets per video frame is
-variable.</para>
-
- <para>Sliced VBI capture and output devices are accessed through the
-same character special files as raw VBI devices. When a driver
-supports both interfaces, the default function of a
-<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI
-capturing or output, and the sliced VBI function is only available
-after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
-<filename>/dev/video</filename> device may support the sliced VBI API,
-however the default function here is video capturing or output.
-Different file descriptors must be used to pass raw and sliced VBI
-data simultaneously, if this is supported by the driver.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the sliced VBI capturing or output API
-set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or
-<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
-read/write, streaming or asynchronous <link linkend="io">I/O
-methods</link> must be supported. Sliced VBI devices may have a tuner
-or modulator.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Sliced VBI devices shall support <link linkend="video">video
-input or output</link> and <link linkend="tuner">tuner or
-modulator</link> ioctls if they have these capabilities, and they may
-support <link linkend="control">control</link> ioctls. The <link
-linkend="standard">video standard</link> ioctls provide information
-vital to program a sliced VBI device, therefore must be
-supported.</para>
- </section>
-
- <section id="sliced-vbi-format-negotitation">
- <title>Sliced VBI Format Negotiation</title>
-
- <para>To find out which data services are supported by the
-hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
-All drivers implementing the sliced VBI interface must support this
-ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
-when the number of VBI lines the hardware can capture or output per
-frame, or the number of services it can identify on a given line are
-limited. For example on PAL line 16 the hardware may be able to look
-for a VPS or Teletext signal, but not both at the same time.</para>
-
- <para>To determine the currently selected services applications
-set the <structfield>type </structfield> field of &v4l2-format; to
-<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>
-V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT;
-ioctl fills the <structfield>fmt.sliced</structfield> member, a
-&v4l2-sliced-vbi-format;.</para>
-
- <para>Applications can request different parameters by
-initializing or modifying the <structfield>fmt.sliced</structfield>
-member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the
-<structname>v4l2_format</structname> structure.</para>
-
- <para>The sliced VBI API is more complicated than the raw VBI API
-because the hardware must be told which VBI service to expect on each
-scan line. Not all services may be supported by the hardware on all
-lines (this is especially true for VBI output where Teletext is often
-unsupported and other services can only be inserted in one specific
-line). In many cases, however, it is sufficient to just set the
-<structfield>service_set</structfield> field to the required services
-and let the driver fill the <structfield>service_lines</structfield>
-array according to hardware capabilities. Only if more precise control
-is needed should the programmer set the
-<structfield>service_lines</structfield> array explicitly.</para>
-
- <para>The &VIDIOC-S-FMT; ioctl modifies the parameters
-according to hardware capabilities. When the driver allocates
-resources at this point, it may return an &EBUSY; if the required
-resources are temporarily unavailable. Other resource allocation
-points which may return <errorcode>EBUSY</errorcode> can be the
-&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and
-&func-select; call.</para>
-
- <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format">
- <title>struct
-<structname>v4l2_sliced_vbi_format</structname></title>
- <tgroup cols="5">
- <colspec colname="c1" colwidth="3*" />
- <colspec colname="c2" colwidth="3*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="2*" />
- <colspec colname="c5" colwidth="2*" />
- <spanspec namest="c3" nameend="c5" spanname="hspan" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>service_set</structfield></entry>
- <entry spanname="hspan"><para>If
-<structfield>service_set</structfield> is non-zero when passed with
-&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the
-<structfield>service_lines</structfield> array will be filled by the
-driver according to the services specified in this field. For example,
-if <structfield>service_set</structfield> is initialized with
-<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a
-driver for the cx25840 video decoder sets lines 7-22 of both
-fields<footnote><para>According to <link
-linkend="ets300706">ETS&nbsp;300&nbsp;706</link> lines 6-22 of the
-first field and lines 5-22 of the second field may carry Teletext
-data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant>
-and line 23 of the first field to
-<constant>V4L2_SLICED_WSS_625</constant>. If
-<structfield>service_set</structfield> is set to zero, then the values
-of <structfield>service_lines</structfield> will be used instead.
-</para><para>On return the driver sets this field to the union of all
-elements of the returned <structfield>service_lines</structfield>
-array. It may contain less services than requested, perhaps just one,
-if the hardware cannot handle more services simultaneously. It may be
-empty (zero) if none of the requested services are supported by the
-hardware.</para></entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>service_lines</structfield>[2][24]</entry>
- <entry spanname="hspan"><para>Applications initialize this
-array with sets of data services the driver shall look for or insert
-on the respective scan line. Subject to hardware capabilities drivers
-return the requested set, a subset, which may be just a single
-service, or an empty set. When the hardware cannot handle multiple
-services on the same line the driver shall choose one. No assumptions
-can be made on which service the driver chooses.</para><para>Data
-services are defined in <xref linkend="vbi-services2" />. Array indices
-map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref
- linkend="vbi-625" />) as follows: <!-- No nested
-tables, sigh. --></para></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Element</entry>
- <entry>525 line systems</entry>
- <entry>625 line systems</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[0][1]</entry>
- <entry align="center">1</entry>
- <entry align="center">1</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[0][23]</entry>
- <entry align="center">23</entry>
- <entry align="center">23</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[1][1]</entry>
- <entry align="center">264</entry>
- <entry align="center">314</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[1][23]</entry>
- <entry align="center">286</entry>
- <entry align="center">336</entry>
- </row>
- <!-- End of line numbers table. -->
- <row>
- <entry></entry>
- <entry></entry>
- <entry spanname="hspan">Drivers must set
-<structfield>service_lines</structfield>[0][0] and
-<structfield>service_lines</structfield>[1][0] to zero.
-The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
-<constant>V4L2_VBI_ITU_525_F2_START</constant>,
-<constant>V4L2_VBI_ITU_625_F1_START</constant> and
-<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start
-line numbers for each field for each 525 or 625 line format as a
-convenience. Don't forget that ITU line numbering starts at 1, not 0.
-</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>io_size</structfield></entry>
- <entry spanname="hspan">Maximum number of bytes passed by
-one &func-read; or &func-write; call, and the buffer size in bytes for
-the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
-the size of &v4l2-sliced-vbi-data; times the number of non-zero
-elements in the returned <structfield>service_lines</structfield>
-array (that is the number of lines potentially carrying data).</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry spanname="hspan">This array is reserved for future
-extensions. Applications and drivers must set it to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- See also vidioc-g-sliced-vbi-cap.sgml -->
- <table frame="none" pgwide="1" id="vbi-services2">
- <title>Sliced VBI services</title>
- <tgroup cols="5">
- <colspec colname="c1" colwidth="2*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="1*" />
- <colspec colname="c4" colwidth="2*" />
- <colspec colname="c5" colwidth="2*" />
- <spanspec namest="c3" nameend="c5" spanname="rlp" />
- <thead>
- <row>
- <entry>Symbol</entry>
- <entry>Value</entry>
- <entry>Reference</entry>
- <entry>Lines, usually</entry>
- <entry>Payload</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SLICED_TELETEXT_B</constant>
-(Teletext System B)</entry>
- <entry>0x0001</entry>
- <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
- <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
- <entry>Last 42 of the 45 byte Teletext packet, that is
-without clock run-in and framing code, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VPS</constant></entry>
- <entry>0x0400</entry>
- <entry><xref linkend="ets300231" /></entry>
- <entry>PAL line 16</entry>
- <entry>Byte number 3 to 15 according to Figure 9 of
-ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
- <entry>0x1000</entry>
- <entry><xref linkend="cea608" /></entry>
- <entry>NTSC line 21, 284 (second field 21)</entry>
- <entry>Two bytes in transmission order, including parity
-bit, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
- <entry>0x4000</entry>
- <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry>
- <entry>PAL/SECAM line 23</entry>
- <entry><screen>
-Byte 0 1
- msb lsb msb lsb
- Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
-</screen></entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
- <entry>0x1000</entry>
- <entry spanname="rlp">Set of services applicable to 525
-line systems.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
- <entry>0x4401</entry>
- <entry spanname="rlp">Set of services applicable to 625
-line systems.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Drivers may return an &EINVAL; when applications attempt to
-read or write data without prior format negotiation, after switching
-the video standard (which may invalidate the negotiated VBI
-parameters) and after switching the video input (which may change the
-video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
-an &EBUSY; when applications attempt to change the format while i/o is
-in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
-and after the first &func-read; or &func-write; call).</para>
- </section>
-
- <section>
- <title>Reading and writing sliced VBI data</title>
-
- <para>A single &func-read; or &func-write; call must pass all data
-belonging to one video frame. That is an array of
-<structname>v4l2_sliced_vbi_data</structname> structures with one or
-more elements and a total size not exceeding
-<structfield>io_size</structfield> bytes. Likewise in streaming I/O
-mode one buffer of <structfield>io_size</structfield> bytes must
-contain data of one video frame. The <structfield>id</structfield> of
-unused <structname>v4l2_sliced_vbi_data</structname> elements must be
-zero.</para>
-
- <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
- <title>struct
-<structname>v4l2_sliced_vbi_data</structname></title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>A flag from <xref linkend="vbi-services" />
-identifying the type of data in this packet. Only a single bit must be
-set. When the <structfield>id</structfield> of a captured packet is
-zero, the packet is empty and the contents of other fields are
-undefined. Applications shall ignore empty packets. When the
-<structfield>id</structfield> of a packet for output is zero the
-contents of the <structfield>data</structfield> field are undefined
-and the driver must no longer insert data on the requested
-<structfield>field</structfield> and
-<structfield>line</structfield>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>field</structfield></entry>
- <entry>The video field number this data has been captured
-from, or shall be inserted at. <constant>0</constant> for the first
-field, <constant>1</constant> for the second field.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>line</structfield></entry>
- <entry>The field (as opposed to frame) line number this
-data has been captured from, or shall be inserted at. See <xref
- linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
-values. Sliced VBI capture devices can set the line number of all
-packets to <constant>0</constant> if the hardware cannot reliably
-identify scan lines. The field number must always be valid.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield></entry>
- <entry>This field is reserved for future extensions.
-Applications and drivers must set it to zero.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>data</structfield>[48]</entry>
- <entry>The packet payload. See <xref
- linkend="vbi-services" /> for the contents and number of
-bytes passed for each data type. The contents of padding bytes at the
-end of this array are undefined, drivers and applications shall ignore
-them.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Packets are always passed in ascending line number order,
-without duplicate line numbers. The &func-write; function and the
-&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
-this rule. They must also return an &EINVAL; when applications pass an
-incorrect field or line number, or a combination of
-<structfield>field</structfield>, <structfield>line</structfield> and
-<structfield>id</structfield> which has not been negotiated with the
-&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
-unknown the driver must pass the packets in transmitted order. The
-driver can insert empty packets with <structfield>id</structfield> set
-to zero anywhere in the packet array.</para>
-
- <para>To assure synchronization and to distinguish from frame
-dropping, when a captured frame does not carry any of the requested
-data services drivers must pass one or more empty packets. When an
-application fails to pass VBI data in time for output, the driver
-must output the last VPS and WSS packet again, and disable the output
-of Closed Caption and Teletext data, or output data which is ignored
-by Closed Caption and Teletext decoders.</para>
-
- <para>A sliced VBI device may support <link
-linkend="rw">read/write</link> and/or streaming (<link
-linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
-pointer</link>) I/O. The latter bears the possibility of synchronizing
-video and VBI data by using buffer timestamps.</para>
-
- </section>
-
- <section>
- <title>Sliced VBI Data in MPEG Streams</title>
-
- <para>If a device can produce an MPEG output stream, it may be
-capable of providing <link
-linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
-services</link> as data embedded in the MPEG stream. Users or
-applications control this sliced VBI data insertion with the <link
-linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
-control.</para>
-
- <para>If the driver does not provide the <link
-linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
-control, or only allows that control to be set to <link
-linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
-V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
-cannot embed sliced VBI data in the MPEG stream.</para>
-
- <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
-V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
-the device driver to capture nor cease capturing sliced VBI data. The
-control only indicates to embed sliced VBI data in the MPEG stream, if
-an application has negotiated sliced VBI service be captured.</para>
-
- <para>It may also be the case that a device can embed sliced VBI
-data in only certain types of MPEG streams: for example in an MPEG-2
-PS but not an MPEG-2 TS. In this situation, if sliced VBI data
-insertion is requested, the sliced VBI data will be embedded in MPEG
-stream types when supported, and silently omitted from MPEG stream
-types where sliced VBI data insertion is not supported by the device.
-</para>
-
- <para>The following subsections specify the format of the
-embedded sliced VBI data.</para>
-
- <section>
- <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
- <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
-V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
-format shall be interpreted by drivers as a control to cease
-embedding sliced VBI data in MPEG streams. Neither the device nor
-driver shall insert "empty" embedded sliced VBI data packets in the
-MPEG stream when this format is set. No MPEG stream data structures
-are specified for this format.</para>
- </section>
-
- <section>
- <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
- <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
-V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
-format, when supported, indicates to the driver to embed up to 36
-lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
-Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
-Program Pack</emphasis> in the MPEG stream.</para>
-
- <para><emphasis>Historical context</emphasis>: This format
-specification originates from a custom, embedded, sliced VBI data
-format used by the <filename>ivtv</filename> driver. This format
-has already been informally specified in the kernel sources in the
-file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
-. The maximum size of the payload and other aspects of this format
-are driven by the CX23415 MPEG decoder's capabilities and limitations
-with respect to extracting, decoding, and displaying sliced VBI data
-embedded within an MPEG stream.</para>
-
- <para>This format's use is <emphasis>not</emphasis> exclusive to
-the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
-exclusive to CX2341x devices, as the sliced VBI data packet insertion
-into the MPEG stream is implemented in driver software. At least the
-<filename>cx18</filename> driver provides sliced VBI data insertion
-into an MPEG-2 PS in this format as well.</para>
-
- <para>The following definitions specify the payload of the
-MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
-sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
-<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
-(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
-and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
-not detailed here. Please refer to the MPEG-2 specifications for
-details on those packet headers.)</para>
-
- <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
-</emphasis> packets that contain sliced VBI data is specified by
-&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
-length, depending on the actual number of lines of sliced VBI data
-present in a video frame. The payload may be padded at the end with
-unspecified fill bytes to align the end of the payload to a 4-byte
-boundary. The payload shall never exceed 1552 bytes (2 fields with
-18 lines/field with 43 bytes of data/line and a 4 byte magic number).
-</para>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
- <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
- </title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>magic</structfield>[4]</entry>
- <entry></entry>
- <entry>A "magic" constant from <xref
- linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
-this is a valid sliced VBI data payload and also indicates which
-member of the anonymous union, <structfield>itv0</structfield> or
-<structfield>ITV0</structfield>, to use for the payload data.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry>(anonymous)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
- <structname>v4l2_mpeg_vbi_itv0</structname></link>
- </entry>
- <entry><structfield>itv0</structfield></entry>
- <entry>The primary form of the sliced VBI data payload
-that contains anywhere from 1 to 35 lines of sliced VBI data.
-Line masks are provided in this form of the payload indicating
-which VBI lines are provided.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
- <structname>v4l2_mpeg_vbi_ITV0</structname></link>
- </entry>
- <entry><structfield>ITV0</structfield></entry>
- <entry>An alternate form of the sliced VBI data payload
-used when 36 lines of sliced VBI data are present. No line masks are
-provided in this form of the payload; all valid line mask bits are
-implcitly set.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
- <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
- <structfield>magic</structfield> field</title>
- <tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry align="left">Defined Symbol</entry>
- <entry align="left">Value</entry>
- <entry align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant>
- </entry>
- <entry>"itv0"</entry>
- <entry>Indicates the <structfield>itv0</structfield>
-member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant>
- </entry>
- <entry>"ITV0"</entry>
- <entry>Indicates the <structfield>ITV0</structfield>
-member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
-that 36 lines of sliced VBI data are present.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
- <title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
- </title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__le32</entry>
- <entry><structfield>linemask</structfield>[2]</entry>
- <entry><para>Bitmasks indicating the VBI service lines
-present. These <structfield>linemask</structfield> values are stored
-in little endian byte order in the MPEG stream. Some reference
-<structfield>linemask</structfield> bit positions with their
-corresponding VBI line number and video field are given below.
-b<subscript>0</subscript> indicates the least significant bit of a
-<structfield>linemask</structfield> value:<screen>
-<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field
-<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field
-<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field
-<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field
-<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field
-<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field
-<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry>
- </row>
- <row>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
- <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
- </entry>
- <entry><structfield>line</structfield>[35]</entry>
- <entry>This is a variable length array that holds from 1
-to 35 lines of sliced VBI data. The sliced VBI data lines present
-correspond to the bits set in the <structfield>linemask</structfield>
-array, starting from b<subscript>0</subscript> of <structfield>
-linemask</structfield>[0] up through b<subscript>31</subscript> of
-<structfield>linemask</structfield>[0], and from b<subscript>0
-</subscript> of <structfield>linemask</structfield>[1] up through b
-<subscript>3</subscript> of <structfield>linemask</structfield>[1].
-<structfield>line</structfield>[0] corresponds to the first bit
-found set in the <structfield>linemask</structfield> array,
-<structfield>line</structfield>[1] corresponds to the second bit
-found set in the <structfield>linemask</structfield> array, etc.
-If no <structfield>linemask</structfield> array bits are set, then
-<structfield>line</structfield>[0] may contain one line of
-unspecified data that should be ignored by applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
- <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
- </title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
- <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
- </entry>
- <entry><structfield>line</structfield>[36]</entry>
- <entry>A fixed length array of 36 lines of sliced VBI
-data. <structfield>line</structfield>[0] through <structfield>line
-</structfield>[17] correspond to lines 6 through 23 of the
-first field. <structfield>line</structfield>[18] through
-<structfield>line</structfield>[35] corresponds to lines 6
-through 23 of the second field.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
- <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
- </title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>id</structfield></entry>
- <entry>A line identifier value from
-<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
-the type of sliced VBI data stored on this line.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>data</structfield>[42]</entry>
- <entry>The sliced VBI data for the line.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
- <title>Line Identifiers for struct <link
- linkend="v4l2-mpeg-vbi-itv0-line"><structname>
-v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
-</structfield> field</title>
- <tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry align="left">Defined Symbol</entry>
- <entry align="left">Value</entry>
- <entry align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
- </entry>
- <entry>1</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant>
- </entry>
- <entry>4</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant>
- </entry>
- <entry>5</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant>
- </entry>
- <entry>7</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml
deleted file mode 100644
index 4f0ba58c9bd9..000000000000
--- a/Documentation/DocBook/media/v4l/dev-subdev.xml
+++ /dev/null
@@ -1,484 +0,0 @@
- <title>Sub-device Interface</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>The complex nature of V4L2 devices, where hardware is often made of
- several integrated circuits that need to interact with each other in a
- controlled way, leads to complex V4L2 drivers. The drivers usually reflect
- the hardware model in software, and model the different hardware components
- as software blocks called sub-devices.</para>
-
- <para>V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
- implements the media device API, they will automatically inherit from media
- entities. Applications will be able to enumerate the sub-devices and discover
- the hardware topology using the media entities, pads and links enumeration
- API.</para>
-
- <para>In addition to make sub-devices discoverable, drivers can also choose
- to make them directly configurable by applications. When both the sub-device
- driver and the V4L2 device driver support this, sub-devices will feature a
- character device node on which ioctls can be called to
- <itemizedlist>
- <listitem><para>query, read and write sub-devices controls</para></listitem>
- <listitem><para>subscribe and unsubscribe to events and retrieve them</para></listitem>
- <listitem><para>negotiate image formats on individual pads</para></listitem>
- </itemizedlist>
- </para>
-
- <para>Sub-device character device nodes, conventionally named
- <filename>/dev/v4l-subdev*</filename>, use major number 81.</para>
-
- <section>
- <title>Controls</title>
- <para>Most V4L2 controls are implemented by sub-device hardware. Drivers
- usually merge all controls and expose them through video device nodes.
- Applications can control all sub-devices through a single interface.</para>
-
- <para>Complex devices sometimes implement the same control in different
- pieces of hardware. This situation is common in embedded platforms, where
- both sensors and image processing hardware implement identical functions,
- such as contrast adjustment, white balance or faulty pixels correction. As
- the V4L2 controls API doesn't support several identical controls in a single
- device, all but one of the identical controls are hidden.</para>
-
- <para>Applications can access those hidden controls through the sub-device
- node with the V4L2 control API described in <xref linkend="control" />. The
- ioctls behave identically as when issued on V4L2 device nodes, with the
- exception that they deal only with controls implemented in the sub-device.
- </para>
-
- <para>Depending on the driver, those controls might also be exposed through
- one (or several) V4L2 device nodes.</para>
- </section>
-
- <section>
- <title>Events</title>
- <para>V4L2 sub-devices can notify applications of events as described in
- <xref linkend="event" />. The API behaves identically as when used on V4L2
- device nodes, with the exception that it only deals with events generated by
- the sub-device. Depending on the driver, those events might also be reported
- on one (or several) V4L2 device nodes.</para>
- </section>
-
- <section id="pad-level-formats">
- <title>Pad-level Formats</title>
-
- <warning><para>Pad-level formats are only applicable to very complex device that
- need to expose low-level format configuration to user space. Generic V4L2
- applications do <emphasis>not</emphasis> need to use the API described in
- this section.</para></warning>
-
- <note><para>For the purpose of this section, the term
- <wordasword>format</wordasword> means the combination of media bus data
- format, frame width and frame height.</para></note>
-
- <para>Image formats are typically negotiated on video capture and
- output devices using the format and <link
- linkend="vidioc-subdev-g-selection">selection</link> ioctls. The
- driver is responsible for configuring every block in the video
- pipeline according to the requested format at the pipeline input
- and/or output.</para>
-
- <para>For complex devices, such as often found in embedded systems,
- identical image sizes at the output of a pipeline can be achieved using
- different hardware configurations. One such example is shown on
- <xref linkend="pipeline-scaling" />, where
- image scaling can be performed on both the video sensor and the host image
- processing hardware.</para>
-
- <figure id="pipeline-scaling">
- <title>Image Format Negotiation on Pipelines</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="pipeline.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="pipeline.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>High quality and high speed pipeline configuration</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>The sensor scaler is usually of less quality than the host scaler, but
- scaling on the sensor is required to achieve higher frame rates. Depending
- on the use case (quality vs. speed), the pipeline must be configured
- differently. Applications need to configure the formats at every point in
- the pipeline explicitly.</para>
-
- <para>Drivers that implement the <link linkend="media-controller-intro">media
- API</link> can expose pad-level image format configuration to applications.
- When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and
- &VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.</para>
-
- <para>Applications are responsible for configuring coherent parameters on
- the whole pipeline and making sure that connected pads have compatible
- formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON;
- time, and an &EPIPE; is then returned if the configuration is
- invalid.</para>
-
- <para>Pad-level image format configuration support can be tested by calling
- the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL;
- pad-level format configuration is not supported by the sub-device.</para>
-
- <section>
- <title>Format Negotiation</title>
-
- <para>Acceptable formats on pads can (and usually do) depend on a number
- of external parameters, such as formats on other pads, active links, or
- even controls. Finding a combination of formats on all pads in a video
- pipeline, acceptable to both application and driver, can't rely on formats
- enumeration only. A format negotiation mechanism is required.</para>
-
- <para>Central to the format negotiation mechanism are the get/set format
- operations. When called with the <structfield>which</structfield> argument
- set to <constant>V4L2_SUBDEV_FORMAT_TRY</constant>, the
- &VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of
- formats parameters that are not connected to the hardware configuration.
- Modifying those 'try' formats leaves the device state untouched (this
- applies to both the software state stored in the driver and the hardware
- state stored in the device itself).</para>
-
- <para>While not kept as part of the device state, try formats are stored
- in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return
- the last try format set <emphasis>on the same sub-device file
- handle</emphasis>. Several applications querying the same sub-device at
- the same time will thus not interact with each other.</para>
-
- <para>To find out whether a particular format is supported by the device,
- applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if
- needed, change the requested <structfield>format</structfield> based on
- device requirements and return the possibly modified value. Applications
- can then choose to try a different format or accept the returned value and
- continue.</para>
-
- <para>Formats returned by the driver during a negotiation iteration are
- guaranteed to be supported by the device. In particular, drivers guarantee
- that a returned format will not be further changed if passed to an
- &VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as
- formats on other pads or links' configuration are not changed).</para>
-
- <para>Drivers automatically propagate formats inside sub-devices. When a
- try or active format is set on a pad, corresponding formats on other pads
- of the same sub-device can be modified by the driver. Drivers are free to
- modify formats as required by the device. However, they should comply with
- the following rules when possible:
- <itemizedlist>
- <listitem><para>Formats should be propagated from sink pads to source pads.
- Modifying a format on a source pad should not modify the format on any
- sink pad.</para></listitem>
- <listitem><para>Sub-devices that scale frames using variable scaling factors
- should reset the scale factors to default values when sink pads formats
- are modified. If the 1:1 scaling ratio is supported, this means that
- source pads formats should be reset to the sink pads formats.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>Formats are not propagated across links, as that would involve
- propagating them from one sub-device file handle to another. Applications
- must then take care to configure both ends of every link explicitly with
- compatible formats. Identical formats on the two ends of a link are
- guaranteed to be compatible. Drivers are free to accept different formats
- matching device requirements as being compatible.</para>
-
- <para><xref linkend="sample-pipeline-config" />
- shows a sample configuration sequence for the pipeline described in
- <xref linkend="pipeline-scaling" /> (table
- columns list entity names and pad numbers).</para>
-
- <table pgwide="0" frame="none" id="sample-pipeline-config">
- <title>Sample Pipeline Configuration</title>
- <tgroup cols="3">
- <colspec colname="what"/>
- <colspec colname="sensor-0 format" />
- <colspec colname="frontend-0 format" />
- <colspec colname="frontend-1 format" />
- <colspec colname="scaler-0 format" />
- <colspec colname="scaler-0 compose" />
- <colspec colname="scaler-1 format" />
- <thead>
- <row>
- <entry></entry>
- <entry>Sensor/0 format</entry>
- <entry>Frontend/0 format</entry>
- <entry>Frontend/1 format</entry>
- <entry>Scaler/0 format</entry>
- <entry>Scaler/0 compose selection rectangle</entry>
- <entry>Scaler/1 format</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Initial state</entry>
- <entry>2048x1536/SGRBG8_1X8</entry>
- <entry>(default)</entry>
- <entry>(default)</entry>
- <entry>(default)</entry>
- <entry>(default)</entry>
- <entry>(default)</entry>
- </row>
- <row>
- <entry>Configure frontend sink format</entry>
- <entry>2048x1536/SGRBG8_1X8</entry>
- <entry><emphasis>2048x1536/SGRBG8_1X8</emphasis></entry>
- <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry>
- <entry>(default)</entry>
- <entry>(default)</entry>
- <entry>(default)</entry>
- </row>
- <row>
- <entry>Configure scaler sink format</entry>
- <entry>2048x1536/SGRBG8_1X8</entry>
- <entry>2048x1536/SGRBG8_1X8</entry>
- <entry>2046x1534/SGRBG8_1X8</entry>
- <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry>
- <entry><emphasis>0,0/2046x1534</emphasis></entry>
- <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry>
- </row>
- <row>
- <entry>Configure scaler sink compose selection</entry>
- <entry>2048x1536/SGRBG8_1X8</entry>
- <entry>2048x1536/SGRBG8_1X8</entry>
- <entry>2046x1534/SGRBG8_1X8</entry>
- <entry>2046x1534/SGRBG8_1X8</entry>
- <entry><emphasis>0,0/1280x960</emphasis></entry>
- <entry><emphasis>1280x960/SGRBG8_1X8</emphasis></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- <orderedlist>
- <listitem><para>Initial state. The sensor source pad format is
- set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8
- media bus code. Formats on the host frontend and scaler sink
- and source pads have the default values, as well as the
- compose rectangle on the scaler's sink pad.</para></listitem>
-
- <listitem><para>The application configures the frontend sink
- pad format's size to 2048x1536 and its media bus code to
- V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the format to
- the frontend source pad.</para></listitem>
-
- <listitem><para>The application configures the scaler sink pad
- format's size to 2046x1534 and the media bus code to
- V4L2_MBUS_FMT_SGRBG_1X8 to match the frontend source size and
- media bus code. The media bus code on the sink pad is set to
- V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the size to the
- compose selection rectangle on the scaler's sink pad, and the
- format to the scaler source pad.</para></listitem>
-
- <listitem><para>The application configures the size of the compose
- selection rectangle of the scaler's sink pad 1280x960. The driver
- propagates the size to the scaler's source pad
- format.</para></listitem>
-
- </orderedlist>
- </para>
-
- <para>When satisfied with the try results, applications can set the active
- formats by setting the <structfield>which</structfield> argument to
- <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. Active formats are changed
- exactly as try formats by drivers. To avoid modifying the hardware state
- during format negotiation, applications should negotiate try formats first
- and then modify the active settings using the try formats returned during
- the last negotiation iteration. This guarantees that the active format
- will be applied as-is by the driver without being modified.
- </para>
- </section>
-
- <section id="v4l2-subdev-selections">
- <title>Selections: cropping, scaling and composition</title>
-
- <para>Many sub-devices support cropping frames on their input or output
- pads (or possible even on both). Cropping is used to select the area of
- interest in an image, typically on an image sensor or a video decoder. It can
- also be used as part of digital zoom implementations to select the area of
- the image that will be scaled up.</para>
-
- <para>Crop settings are defined by a crop rectangle and represented in a
- &v4l2-rect; by the coordinates of the top left corner and the rectangle
- size. Both the coordinates and sizes are expressed in pixels.</para>
-
- <para>As for pad formats, drivers store try and active
- rectangles for the selection targets <xref
- linkend="v4l2-selections-common" />.</para>
-
- <para>On sink pads, cropping is applied relative to the
- current pad format. The pad format represents the image size as
- received by the sub-device from the previous block in the
- pipeline, and the crop rectangle represents the sub-image that
- will be transmitted further inside the sub-device for
- processing.</para>
-
- <para>The scaling operation changes the size of the image by
- scaling it to new dimensions. The scaling ratio isn't specified
- explicitly, but is implied from the original and scaled image
- sizes. Both sizes are represented by &v4l2-rect;.</para>
-
- <para>Scaling support is optional. When supported by a subdev,
- the crop rectangle on the subdev's sink pad is scaled to the
- size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL
- using <constant>V4L2_SEL_TGT_COMPOSE</constant>
- selection target on the same pad. If the subdev supports scaling
- but not composing, the top and left values are not used and must
- always be set to zero.</para>
-
- <para>On source pads, cropping is similar to sink pads, with the
- exception that the source size from which the cropping is
- performed, is the COMPOSE rectangle on the sink pad. In both
- sink and source pads, the crop rectangle must be entirely
- contained inside the source image size for the crop
- operation.</para>
-
- <para>The drivers should always use the closest possible
- rectangle the user requests on all selection targets, unless
- specifically told otherwise.
- <constant>V4L2_SEL_FLAG_GE</constant> and
- <constant>V4L2_SEL_FLAG_LE</constant> flags may be
- used to round the image size either up or down. <xref
- linkend="v4l2-selection-flags" /></para>
- </section>
-
- <section>
- <title>Types of selection targets</title>
-
- <section>
- <title>Actual targets</title>
-
- <para>Actual targets (without a postfix) reflect the actual
- hardware configuration at any point of time. There is a BOUNDS
- target corresponding to every actual target.</para>
- </section>
-
- <section>
- <title>BOUNDS targets</title>
-
- <para>BOUNDS targets is the smallest rectangle that contains all
- valid actual rectangles. It may not be possible to set the actual
- rectangle as large as the BOUNDS rectangle, however. This may be
- because e.g. a sensor's pixel array is not rectangular but
- cross-shaped or round. The maximum size may also be smaller than the
- BOUNDS rectangle.</para>
- </section>
-
- </section>
-
- <section>
- <title>Order of configuration and format propagation</title>
-
- <para>Inside subdevs, the order of image processing steps will
- always be from the sink pad towards the source pad. This is also
- reflected in the order in which the configuration must be
- performed by the user: the changes made will be propagated to
- any subsequent stages. If this behaviour is not desired, the
- user must set
- <constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant> flag. This
- flag causes no propagation of the changes are allowed in any
- circumstances. This may also cause the accessed rectangle to be
- adjusted by the driver, depending on the properties of the
- underlying hardware.</para>
-
- <para>The coordinates to a step always refer to the actual size
- of the previous step. The exception to this rule is the source
- compose rectangle, which refers to the sink compose bounds
- rectangle --- if it is supported by the hardware.</para>
-
- <orderedlist>
- <listitem><para>Sink pad format. The user configures the sink pad
- format. This format defines the parameters of the image the
- entity receives through the pad for further processing.</para></listitem>
-
- <listitem><para>Sink pad actual crop selection. The sink pad crop
- defines the crop performed to the sink pad format.</para></listitem>
-
- <listitem><para>Sink pad actual compose selection. The size of the
- sink pad compose rectangle defines the scaling ratio compared
- to the size of the sink pad crop rectangle. The location of
- the compose rectangle specifies the location of the actual
- sink compose rectangle in the sink compose bounds
- rectangle.</para></listitem>
-
- <listitem><para>Source pad actual crop selection. Crop on the source
- pad defines crop performed to the image in the sink compose
- bounds rectangle.</para></listitem>
-
- <listitem><para>Source pad format. The source pad format defines the
- output pixel format of the subdev, as well as the other
- parameters with the exception of the image width and height.
- Width and height are defined by the size of the source pad
- actual crop selection.</para></listitem>
- </orderedlist>
-
- <para>Accessing any of the above rectangles not supported by the
- subdev will return <constant>EINVAL</constant>. Any rectangle
- referring to a previous unsupported rectangle coordinates will
- instead refer to the previous supported rectangle. For example,
- if sink crop is not supported, the compose selection will refer
- to the sink pad format dimensions instead.</para>
-
- <figure id="subdev-image-processing-crop">
- <title>Image processing in subdevs: simple crop example</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="subdev-image-processing-crop.svg"
- format="SVG" scale="200" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>In the above example, the subdev supports cropping on its
- sink pad. To configure it, the user sets the media bus format on
- the subdev's sink pad. Now the actual crop rectangle can be set
- on the sink pad --- the location and size of this rectangle
- reflect the location and size of a rectangle to be cropped from
- the sink format. The size of the sink crop rectangle will also
- be the size of the format of the subdev's source pad.</para>
-
- <figure id="subdev-image-processing-scaling-multi-source">
- <title>Image processing in subdevs: scaling with multiple sources</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="subdev-image-processing-scaling-multi-source.svg"
- format="SVG" scale="200" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>In this example, the subdev is capable of first cropping,
- then scaling and finally cropping for two source pads
- individually from the resulting scaled image. The location of
- the scaled image in the cropped image is ignored in sink compose
- target. Both of the locations of the source crop rectangles
- refer to the sink scaling rectangle, independently cropping an
- area at location specified by the source crop rectangle from
- it.</para>
-
- <figure id="subdev-image-processing-full">
- <title>Image processing in subdevs: scaling and composition
- with multiple sinks and sources</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="subdev-image-processing-full.svg"
- format="SVG" scale="200" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The subdev driver supports two sink pads and two source
- pads. The images from both of the sink pads are individually
- cropped, then scaled and further composed on the composition
- bounds rectangle. From that, two independent streams are cropped
- and sent out of the subdev from the source pads.</para>
-
- </section>
-
- </section>
-
- &sub-subdev-formats;
diff --git a/Documentation/DocBook/media/v4l/dev-teletext.xml b/Documentation/DocBook/media/v4l/dev-teletext.xml
deleted file mode 100644
index bd21c64d70f3..000000000000
--- a/Documentation/DocBook/media/v4l/dev-teletext.xml
+++ /dev/null
@@ -1,29 +0,0 @@
- <title>Teletext Interface</title>
-
- <para>This interface was aimed at devices receiving and demodulating
-Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the
-Teletext packages and storing formatted pages in cache memory. Such
-devices are usually implemented as microcontrollers with serial
-interface (I<superscript>2</superscript>C) and could be found on old
-TV cards, dedicated Teletext decoding cards and home-brew devices
-connected to the PC parallel port.</para>
-
- <para>The Teletext API was designed by Martin Buck. It was defined in
-the kernel header file <filename>linux/videotext.h</filename>, the
-specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/">
-ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of
-the German public television Teletext service.)</para>
-
- <para>Eventually the Teletext API was integrated into the V4L API
-with character device file names <filename>/dev/vtx0</filename> to
-<filename>/dev/vtx31</filename>, device major number 81, minor numbers
-192 to 223.</para>
-
- <para>However, teletext decoders were quickly replaced by more
-generic VBI demodulators and those dedicated teletext decoders no longer exist.
-For many years the vtx devices were still around, even though nobody used
-them. So the decision was made to finally remove support for the Teletext API in
-kernel 2.6.37.</para>
-
- <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or
-<link linkend="sliced">sliced</link> VBI API.</para>
diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml
deleted file mode 100644
index 7c6638bacedb..000000000000
--- a/Documentation/DocBook/media/v4l/driver.xml
+++ /dev/null
@@ -1,200 +0,0 @@
- <title>V4L2 Driver Programming</title>
-
- <!-- This part defines the interface between the "videodev"
- module and individual drivers. -->
-
- <para>to do</para>
-<!--
- <para>V4L2 is a two-layer driver system. The top layer is the "videodev"
-kernel module. When videodev initializes it registers as character device
-with major number 81, and it registers a set of file operations. All V4L2
-drivers are really clients of videodev, which calls V4L2 drivers through
-driver method functions. V4L2 drivers are also written as kernel modules.
-After probing the hardware they register one or more devices with
-videodev.</para>
-
- <section id="driver-modules">
- <title>Driver Modules</title>
-
- <para>V4L2 driver modules must have an initialization function which is
-called after the module was loaded into kernel, an exit function whis is
-called before the module is removed. When the driver is compiled into the
-kernel these functions called at system boot and shutdown time.</para>
-
- <informalexample>
- <programlisting>
-#include &lt;linux/module.h&gt;
-
-/* Export information about this module. For details and other useful
- macros see <filename>linux/module.h</filename>. */
-MODULE_DESCRIPTION("my - driver for my hardware");
-MODULE_AUTHOR("Your name here");
-MODULE_LICENSE("GPL");
-
-static void
-my_module_exit (void)
-{
- /* Free all resources allocated by my_module_init(). */
-}
-
-static int
-my_module_init (void)
-{
- /* Bind the driver to the supported hardware, see
- <link linkend="driver-pci"> and
- <link linkend="driver-usb"> for examples. */
-
- return 0; /* a negative value on error, 0 on success. */
-}
-
-/* Export module functions. */
-module_init (my_module_init);
-module_exit (my_module_exit);
-</programlisting>
- </informalexample>
-
- <para>Users can add parameters when kernel modules are inserted:</para>
-
- <informalexample>
- <programlisting>
-include &lt;linux/moduleparam.h&gt;
-
-static int my_option = 123;
-static int my_option_array[47];
-
-/* Export the symbol, an int, with access permissions 0664.
- See <filename>linux/moduleparam.h</filename> for other types. */
-module_param (my_option, int, 0644);
-module_param_array (my_option_array, int, NULL, 0644);
-
-MODULE_PARM_DESC (my_option, "Does magic things, default 123");
-</programlisting>
- </informalexample>
-
- <para>One parameter should be supported by all V4L2 drivers, the minor
-number of the device it will register. Purpose is to predictably link V4L2
-drivers to device nodes if more than one video device is installed. Use the
-name of the device node followed by a "_nr" suffix, for example "video_nr"
-for <filename>/dev/video</filename>.</para>
-
- <informalexample>
- <programlisting>
-/* Minor number of the device, -1 to allocate the first unused. */
-static int video_nr = -1;
-
-module_param (video_nr, int, 0444);
-</programlisting>
- </informalexample>
- </section>
-
- <section id="driver-pci">
- <title>PCI Devices</title>
-
- <para>PCI devices are initialized like this:</para>
-
- <informalexample>
- <programlisting>
-typedef struct {
- /* State of one physical device. */
-} my_device;
-
-static int
-my_resume (struct pci_dev * pci_dev)
-{
- /* Restore the suspended device to working state. */
-}
-
-static int
-my_suspend (struct pci_dev * pci_dev,
- pm_message_t state)
-{
- /* This function is called before the system goes to sleep.
- Stop all DMAs and disable interrupts, then put the device
- into a low power state. For details see the kernel
- sources under <filename>Documentation/power</filename>. */
-
- return 0; /* a negative value on error, 0 on success. */
-}
-
-static void
-my_remove (struct pci_dev * pci_dev)
-{
- my_device *my = pci_get_drvdata (pci_dev);
-
- /* Describe me. */
-}
-
-static int
-my_probe (struct pci_dev * pci_dev,
- const struct pci_device_id * pci_id)
-{
- my_device *my;
-
- /* Describe me. */
-
- /* You can allocate per-device data here and store a pointer
- to it in the pci_dev structure. */
- my = ...;
- pci_set_drvdata (pci_dev, my);
-
- return 0; /* a negative value on error, 0 on success. */
-}
-
-/* A list of supported PCI devices. */
-static struct pci_device_id
-my_pci_device_ids [] = {
- { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
- PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 },
- { 0 } /* end of list */
-};
-
-/* Load our module if supported PCI devices are installed. */
-MODULE_DEVICE_TABLE (pci, my_pci_device_ids);
-
-static struct pci_driver
-my_pci_driver = {
- .name = "my",
- .id_table = my_pci_device_ids,
-
- .probe = my_probe,
- .remove = my_remove,
-
- /* Power management functions. */
- .suspend = my_suspend,
- .resume = my_resume,
-};
-
-static void
-my_module_exit (void)
-{
- pci_unregister_driver (&my_pci_driver);
-}
-
-static int
-my_module_init (void)
-{
- return pci_register_driver (&my_pci_driver);
-}
-</programlisting>
- </informalexample>
- </section>
-
- <section id="driver-usb">
- <title>USB Devices</title>
- <para>to do</para>
- </section>
- <section id="driver-registering">
- <title>Registering V4L2 Drivers</title>
-
- <para>After a V4L2 driver probed the hardware it registers one or more
-devices with the videodev module.</para>
- </section>
- <section id="driver-file-ops">
- <title>File Operations</title>
- <para>to do</para>
- </section>
- <section id="driver-internal-api">
- <title>Internal API</title>
- <para>to do</para>
- </section>
--->
diff --git a/Documentation/DocBook/media/v4l/fdl-appendix.xml b/Documentation/DocBook/media/v4l/fdl-appendix.xml
deleted file mode 100644
index ae22394ba997..000000000000
--- a/Documentation/DocBook/media/v4l/fdl-appendix.xml
+++ /dev/null
@@ -1,671 +0,0 @@
-<!--
- The GNU Free Documentation License 1.1 in DocBook
- Markup by Eric Baudais <baudais@okstate.edu>
- Maintained by the GNOME Documentation Project
- http://live.gnome.org/DocumentationProject
- Version: 1.0.1
- Last Modified: Nov 16, 2000
--->
-
-<appendix id="fdl">
- <appendixinfo>
- <releaseinfo>
- Version 1.1, March 2000
- </releaseinfo>
- <copyright>
- <year>2000</year><holder>Free Software Foundation, Inc.</holder>
- </copyright>
- <legalnotice id="fdl-legalnotice">
- <para>
- <address>Free Software Foundation, Inc. <street>59 Temple Place,
- Suite 330</street>, <city>Boston</city>, <state>MA</state>
- <postcode>02111-1307</postcode> <country>USA</country></address>
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- </para>
- </legalnotice>
- </appendixinfo>
- <title>GNU Free Documentation License</title>
-
- <sect1 id="fdl-preamble">
- <title>0. PREAMBLE</title>
- <para>
- The purpose of this License is to make a manual, textbook, or
- other written document <quote>free</quote> in the sense of
- freedom: to assure everyone the effective freedom to copy and
- redistribute it, with or without modifying it, either
- commercially or noncommercially. Secondarily, this License
- preserves for the author and publisher a way to get credit for
- their work, while not being considered responsible for
- modifications made by others.
- </para>
-
- <para>
- This License is a kind of <quote>copyleft</quote>, which means
- that derivative works of the document must themselves be free in
- the same sense. It complements the GNU General Public License,
- which is a copyleft license designed for free software.
- </para>
-
- <para>
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same
- freedoms that the software does. But this License is not limited
- to software manuals; it can be used for any textual work,
- regardless of subject matter or whether it is published as a
- printed book. We recommend this License principally for works
- whose purpose is instruction or reference.
- </para>
- </sect1>
- <sect1 id="fdl-section1">
- <title>1. APPLICABILITY AND DEFINITIONS</title>
- <para id="fdl-document">
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be
- distributed under the terms of this License. The
- <quote>Document</quote>, below, refers to any such manual or
- work. Any member of the public is a licensee, and is addressed
- as <quote>you</quote>.
- </para>
-
- <para id="fdl-modified">
- A <quote>Modified Version</quote> of the Document means any work
- containing the Document or a portion of it, either copied
- verbatim, or with modifications and/or translated into another
- language.
- </para>
-
- <para id="fdl-secondary">
- A <quote>Secondary Section</quote> is a named appendix or a
- front-matter section of the <link
- linkend="fdl-document">Document</link> that deals exclusively
- with the relationship of the publishers or authors of the
- Document to the Document's overall subject (or to related
- matters) and contains nothing that could fall directly within
- that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of
- legal, commercial, philosophical, ethical or political position
- regarding them.
- </para>
-
- <para id="fdl-invariant">
- The <quote>Invariant Sections</quote> are certain <link
- linkend="fdl-secondary"> Secondary Sections</link> whose titles
- are designated, as being those of Invariant Sections, in the
- notice that says that the <link
- linkend="fdl-document">Document</link> is released under this
- License.
- </para>
-
- <para id="fdl-cover-texts">
- The <quote>Cover Texts</quote> are certain short passages of
- text that are listed, as Front-Cover Texts or Back-Cover Texts,
- in the notice that says that the <link
- linkend="fdl-document">Document</link> is released under this
- License.
- </para>
-
- <para id="fdl-transparent">
- A <quote>Transparent</quote> copy of the <link
- linkend="fdl-document"> Document</link> means a machine-readable
- copy, represented in a format whose specification is available
- to the general public, whose contents can be viewed and edited
- directly and straightforwardly with generic text editors or (for
- images composed of pixels) generic paint programs or (for
- drawings) some widely available drawing editor, and that is
- suitable for input to text formatters or for automatic
- translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format
- whose markup has been designed to thwart or discourage
- subsequent modification by readers is not Transparent. A copy
- that is not <quote>Transparent</quote> is called
- <quote>Opaque</quote>.
- </para>
-
- <para>
- Examples of suitable formats for Transparent copies include
- plain ASCII without markup, Texinfo input format, LaTeX input
- format, SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human
- modification. Opaque formats include PostScript, PDF,
- proprietary formats that can be read and edited only by
- proprietary word processors, SGML or XML for which the DTD
- and/or processing tools are not generally available, and the
- machine-generated HTML produced by some word processors for
- output purposes only.
- </para>
-
- <para id="fdl-title-page">
- The <quote>Title Page</quote> means, for a printed book, the
- title page itself, plus such following pages as are needed to
- hold, legibly, the material this License requires to appear in
- the title page. For works in formats which do not have any title
- page as such, <quote>Title Page</quote> means the text near the
- most prominent appearance of the work's title, preceding the
- beginning of the body of the text.
- </para>
- </sect1>
-
- <sect1 id="fdl-section2">
- <title>2. VERBATIM COPYING</title>
- <para>
- You may copy and distribute the <link
- linkend="fdl-document">Document</link> in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that
- you add no other conditions whatsoever to those of this
- License. You may not use technical measures to obstruct or
- control the reading or further copying of the copies you make or
- distribute. However, you may accept compensation in exchange for
- copies. If you distribute a large enough number of copies you
- must also follow the conditions in <link
- linkend="fdl-section3">section 3</link>.
- </para>
-
- <para>
- You may also lend copies, under the same conditions stated
- above, and you may publicly display copies.
- </para>
- </sect1>
-
- <sect1 id="fdl-section3">
- <title>3. COPYING IN QUANTITY</title>
- <para>
- If you publish printed copies of the <link
- linkend="fdl-document">Document</link> numbering more than 100,
- and the Document's license notice requires <link
- linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
- the copies in covers that carry, clearly and legibly, all these
- Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also
- clearly and legibly identify you as the publisher of these
- copies. The front cover must present the full title with all
- words of the title equally prominent and visible. You may add
- other material on the covers in addition. Copying with changes
- limited to the covers, as long as they preserve the title of the
- <link linkend="fdl-document">Document</link> and satisfy these
- conditions, can be treated as verbatim copying in other
- respects.
- </para>
-
- <para>
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
- </para>
-
- <para>
- If you publish or distribute <link
- linkend="fdl-transparent">Opaque</link> copies of the <link
- linkend="fdl-document">Document</link> numbering more than 100,
- you must either include a machine-readable <link
- linkend="fdl-transparent">Transparent</link> copy along with
- each Opaque copy, or state in or with each Opaque copy a
- publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added
- material, which the general network-using public has access to
- download anonymously at no charge using public-standard network
- protocols. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will
- remain thus accessible at the stated location until at least one
- year after the last time you distribute an Opaque copy (directly
- or through your agents or retailers) of that edition to the
- public.
- </para>
-
- <para>
- It is requested, but not required, that you contact the authors
- of the <link linkend="fdl-document">Document</link> well before
- redistributing any large number of copies, to give them a chance
- to provide you with an updated version of the Document.
- </para>
- </sect1>
-
- <sect1 id="fdl-section4">
- <title>4. MODIFICATIONS</title>
- <para>
- You may copy and distribute a <link
- linkend="fdl-modified">Modified Version</link> of the <link
- linkend="fdl-document">Document</link> under the conditions of
- sections <link linkend="fdl-section2">2</link> and <link
- linkend="fdl-section3">3</link> above, provided that you release
- the Modified Version under precisely this License, with the
- Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version
- to whoever possesses a copy of it. In addition, you must do
- these things in the Modified Version:
- </para>
-
- <itemizedlist mark="opencircle">
- <listitem>
- <formalpara>
- <title>A</title>
- <para>
- Use in the <link linkend="fdl-title-page">Title
- Page</link> (and on the covers, if any) a title distinct
- from that of the <link
- linkend="fdl-document">Document</link>, and from those of
- previous versions (which should, if there were any, be
- listed in the History section of the Document). You may
- use the same title as a previous version if the original
- publisher of that version gives permission.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>B</title>
- <para>
- List on the <link linkend="fdl-title-page">Title
- Page</link>, as authors, one or more persons or entities
- responsible for authorship of the modifications in the
- <link linkend="fdl-modified">Modified Version</link>,
- together with at least five of the principal authors of
- the <link linkend="fdl-document">Document</link> (all of
- its principal authors, if it has less than five).
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>C</title>
- <para>
- State on the <link linkend="fdl-title-page">Title
- Page</link> the name of the publisher of the <link
- linkend="fdl-modified">Modified Version</link>, as the
- publisher.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>D</title>
- <para>
- Preserve all the copyright notices of the <link
- linkend="fdl-document">Document</link>.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>E</title>
- <para>
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>F</title>
- <para>
- Include, immediately after the copyright notices, a
- license notice giving the public permission to use the
- <link linkend="fdl-modified">Modified Version</link> under
- the terms of this License, in the form shown in the
- Addendum below.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>G</title>
- <para>
- Preserve in that license notice the full lists of <link
- linkend="fdl-invariant"> Invariant Sections</link> and
- required <link linkend="fdl-cover-texts">Cover
- Texts</link> given in the <link
- linkend="fdl-document">Document's</link> license notice.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>H</title>
- <para>
- Include an unaltered copy of this License.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>I</title>
- <para>
- Preserve the section entitled <quote>History</quote>, and
- its title, and add to it an item stating at least the
- title, year, new authors, and publisher of the <link
- linkend="fdl-modified">Modified Version </link>as given on
- the <link linkend="fdl-title-page">Title Page</link>. If
- there is no section entitled <quote>History</quote> in the
- <link linkend="fdl-document">Document</link>, create one
- stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>J</title>
- <para>
- Preserve the network location, if any, given in the <link
- linkend="fdl-document">Document</link> for public access
- to a <link linkend="fdl-transparent">Transparent</link>
- copy of the Document, and likewise the network locations
- given in the Document for previous versions it was based
- on. These may be placed in the <quote>History</quote>
- section. You may omit a network location for a work that
- was published at least four years before the Document
- itself, or if the original publisher of the version it
- refers to gives permission.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>K</title>
- <para>
- In any section entitled <quote>Acknowledgements</quote> or
- <quote>Dedications</quote>, preserve the section's title,
- and preserve in the section all the substance and tone of
- each of the contributor acknowledgements and/or
- dedications given therein.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>L</title>
- <para>
- Preserve all the <link linkend="fdl-invariant">Invariant
- Sections</link> of the <link
- linkend="fdl-document">Document</link>, unaltered in their
- text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>M</title>
- <para>
- Delete any section entitled
- <quote>Endorsements</quote>. Such a section may not be
- included in the <link linkend="fdl-modified">Modified
- Version</link>.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>N</title>
- <para>
- Do not retitle any existing section as
- <quote>Endorsements</quote> or to conflict in title with
- any <link linkend="fdl-invariant">Invariant
- Section</link>.
- </para>
- </formalpara>
- </listitem>
- </itemizedlist>
-
- <para>
- If the <link linkend="fdl-modified">Modified Version</link>
- includes new front-matter sections or appendices that qualify as
- <link linkend="fdl-secondary">Secondary Sections</link> and
- contain no material copied from the Document, you may at your
- option designate some or all of these sections as invariant. To
- do this, add their titles to the list of <link
- linkend="fdl-invariant">Invariant Sections</link> in the
- Modified Version's license notice. These titles must be
- distinct from any other section titles.
- </para>
-
- <para>
- You may add a section entitled <quote>Endorsements</quote>,
- provided it contains nothing but endorsements of your <link
- linkend="fdl-modified">Modified Version</link> by various
- parties--for example, statements of peer review or that the text
- has been approved by an organization as the authoritative
- definition of a standard.
- </para>
-
- <para>
- You may add a passage of up to five words as a <link
- linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
- of up to 25 words as a <link
- linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
- the list of <link linkend="fdl-cover-texts">Cover Texts</link>
- in the <link linkend="fdl-modified">Modified Version</link>.
- Only one passage of Front-Cover Text and one of Back-Cover Text
- may be added by (or through arrangements made by) any one
- entity. If the <link linkend="fdl-document">Document</link>
- already includes a cover text for the same cover, previously
- added by you or by arrangement made by the same entity you are
- acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
- </para>
-
- <para>
- The author(s) and publisher(s) of the <link
- linkend="fdl-document">Document</link> do not by this License
- give permission to use their names for publicity for or to
- assert or imply endorsement of any <link
- linkend="fdl-modified">Modified Version </link>.
- </para>
- </sect1>
-
- <sect1 id="fdl-section5">
- <title>5. COMBINING DOCUMENTS</title>
- <para>
- You may combine the <link linkend="fdl-document">Document</link>
- with other documents released under this License, under the
- terms defined in <link linkend="fdl-section4">section 4</link>
- above for modified versions, provided that you include in the
- combination all of the <link linkend="fdl-invariant">Invariant
- Sections</link> of all of the original documents, unmodified,
- and list them all as Invariant Sections of your combined work in
- its license notice.
- </para>
-
- <para>
- The combined work need only contain one copy of this License,
- and multiple identical <link linkend="fdl-invariant">Invariant
- Sections</link> may be replaced with a single copy. If there are
- multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding
- at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique
- number. Make the same adjustment to the section titles in the
- list of Invariant Sections in the license notice of the combined
- work.
- </para>
-
- <para>
- In the combination, you must combine any sections entitled
- <quote>History</quote> in the various original documents,
- forming one section entitled <quote>History</quote>; likewise
- combine any sections entitled <quote>Acknowledgements</quote>,
- and any sections entitled <quote>Dedications</quote>. You must
- delete all sections entitled <quote>Endorsements.</quote>
- </para>
- </sect1>
-
- <sect1 id="fdl-section6">
- <title>6. COLLECTIONS OF DOCUMENTS</title>
- <para>
- You may make a collection consisting of the <link
- linkend="fdl-document">Document</link> and other documents
- released under this License, and replace the individual copies
- of this License in the various documents with a single copy that
- is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
- </para>
-
- <para>
- You may extract a single document from such a collection, and
- dispbibute it individually under this License, provided you
- insert a copy of this License into the extracted document, and
- follow this License in all other respects regarding verbatim
- copying of that document.
- </para>
- </sect1>
-
- <sect1 id="fdl-section7">
- <title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
- <para>
- A compilation of the <link
- linkend="fdl-document">Document</link> or its derivatives with
- other separate and independent documents or works, in or on a
- volume of a storage or distribution medium, does not as a whole
- count as a <link linkend="fdl-modified">Modified Version</link>
- of the Document, provided no compilation copyright is claimed
- for the compilation. Such a compilation is called an
- <quote>aggregate</quote>, and this License does not apply to the
- other self-contained works thus compiled with the Document , on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document. If the <link
- linkend="fdl-cover-texts">Cover Text</link> requirement of <link
- linkend="fdl-section3">section 3</link> is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may
- be placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
- </para>
- </sect1>
-
- <sect1 id="fdl-section8">
- <title>8. TRANSLATION</title>
- <para>
- Translation is considered a kind of modification, so you may
- distribute translations of the <link
- linkend="fdl-document">Document</link> under the terms of <link
- linkend="fdl-section4">section 4</link>. Replacing <link
- linkend="fdl-invariant"> Invariant Sections</link> with
- translations requires special permission from their copyright
- holders, but you may include translations of some or all
- Invariant Sections in addition to the original versions of these
- Invariant Sections. You may include a translation of this
- License provided that you also include the original English
- version of this License. In case of a disagreement between the
- translation and the original English version of this License,
- the original English version will prevail.
- </para>
- </sect1>
-
- <sect1 id="fdl-section9">
- <title>9. TERMINATION</title>
- <para>
- You may not copy, modify, sublicense, or distribute the <link
- linkend="fdl-document">Document</link> except as expressly
- provided for under this License. Any other attempt to copy,
- modify, sublicense or distribute the Document is void, and will
- automatically terminate your rights under this License. However,
- parties who have received copies, or rights, from you under this
- License will not have their licenses terminated so long as such
- parties remain in full compliance.
- </para>
- </sect1>
-
- <sect1 id="fdl-section10">
- <title>10. FUTURE REVISIONS OF THIS LICENSE</title>
- <para>
- The <ulink type="http"
- url="http://www.gnu.org/fsf/fsf.html">Free Software
- Foundation</ulink> may publish new, revised versions of the GNU
- Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ
- in detail to address new problems or concerns. See <ulink
- type="http"
- url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
- </para>
-
- <para>
- Each version of the License is given a distinguishing version
- number. If the <link linkend="fdl-document">Document</link>
- specifies that a particular numbered version of this License
- <quote>or any later version</quote> applies to it, you have the
- option of following the terms and conditions either of that
- specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by
- the Free Software Foundation.
- </para>
- </sect1>
-
- <sect1 id="fdl-using">
- <title>Addendum</title>
- <para>
- To use this License in a document you have written, include a copy of
- the License in the document and put the following copyright and
- license notices just after the title page:
- </para>
-
- <blockquote>
- <para>
- Copyright &copy; YEAR YOUR NAME.
- </para>
- <para>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License, Version 1.1 or any later version published by the
- Free Software Foundation; with the <link
- linkend="fdl-invariant">Invariant Sections</link> being LIST
- THEIR TITLES, with the <link
- linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
- and with the <link linkend="fdl-cover-texts">Back-Cover
- Texts</link> being LIST. A copy of the license is included in
- the section entitled <quote>GNU Free Documentation
- License</quote>.
- </para>
- </blockquote>
-
- <para>
- If you have no <link linkend="fdl-invariant">Invariant
- Sections</link>, write <quote>with no Invariant Sections</quote>
- instead of saying which ones are invariant. If you have no
- <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
- <quote>no Front-Cover Texts</quote> instead of
- <quote>Front-Cover Texts being LIST</quote>; likewise for <link
- linkend="fdl-cover-texts">Back-Cover Texts</link>.
- </para>
-
- <para>
- If your document contains nontrivial examples of program code,
- we recommend releasing these examples in parallel under your
- choice of free software license, such as the <ulink type="http"
- url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
- License</ulink>, to permit their use in free software.
- </para>
- </sect1>
-</appendix>
-
-
-
-
-
-
diff --git a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf b/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
deleted file mode 100644
index 26598b23f80d..000000000000
--- a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf b/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
deleted file mode 100644
index 4965b22ddb3a..000000000000
--- a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/func-close.xml b/Documentation/DocBook/media/v4l/func-close.xml
deleted file mode 100644
index 232920d2f3c6..000000000000
--- a/Documentation/DocBook/media/v4l/func-close.xml
+++ /dev/null
@@ -1,62 +0,0 @@
-<refentry id="func-close">
- <refmeta>
- <refentrytitle>V4L2 close()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-close</refname>
- <refpurpose>Close a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>close</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Closes the device. Any I/O in progress is terminated and
-resources associated with the file descriptor are freed. However data
-format parameters, current input or output, control values or other
-properties remain unchanged.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>The function returns <returnvalue>0</returnvalue> on
-success, <returnvalue>-1</returnvalue> on failure and the
-<varname>errno</varname> is set appropriately. Possible error
-codes:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid open file
-descriptor.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-ioctl.xml b/Documentation/DocBook/media/v4l/func-ioctl.xml
deleted file mode 100644
index 4394184a1a6d..000000000000
--- a/Documentation/DocBook/media/v4l/func-ioctl.xml
+++ /dev/null
@@ -1,71 +0,0 @@
-<refentry id="func-ioctl">
- <refmeta>
- <refentrytitle>V4L2 ioctl()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-ioctl</refname>
- <refpurpose>Program a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>void *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>V4L2 ioctl request code as defined in the <filename>videodev2.h</filename> header file, for example
-VIDIOC_QUERYCAP.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para>Pointer to a function parameter, usually a structure.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The <function>ioctl()</function> function is used to program
-V4L2 devices. The argument <parameter>fd</parameter> must be an open
-file descriptor. An ioctl <parameter>request</parameter> has encoded
-in it whether the argument is an input, output or read/write
-parameter, and the size of the argument <parameter>argp</parameter> in
-bytes. Macros and defines specifying V4L2 ioctl requests are located
-in the <filename>videodev2.h</filename> header file.
-Applications should use their own copy, not include the version in the
-kernel sources on the system they compile on. All V4L2 ioctl requests,
-their respective function and parameters are specified in <xref
- linkend="user-func" />.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
- <para>When an ioctl that takes an output or read/write parameter fails,
- the parameter remains unmodified.</para>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml
deleted file mode 100644
index f31ad71bf301..000000000000
--- a/Documentation/DocBook/media/v4l/func-mmap.xml
+++ /dev/null
@@ -1,183 +0,0 @@
-<refentry id="func-mmap">
- <refmeta>
- <refentrytitle>V4L2 mmap()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-mmap</refname>
- <refpurpose>Map device memory into application address space</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>
-#include &lt;unistd.h&gt;
-#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>void *<function>mmap</function></funcdef>
- <paramdef>void *<parameter>start</parameter></paramdef>
- <paramdef>size_t <parameter>length</parameter></paramdef>
- <paramdef>int <parameter>prot</parameter></paramdef>
- <paramdef>int <parameter>flags</parameter></paramdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>off_t <parameter>offset</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
- <variablelist>
- <varlistentry>
- <term><parameter>start</parameter></term>
- <listitem>
- <para>Map the buffer to this address in the
-application's address space. When the <constant>MAP_FIXED</constant>
-flag is specified, <parameter>start</parameter> must be a multiple of the
-pagesize and mmap will fail when the specified address
-cannot be used. Use of this option is discouraged; applications should
-just specify a <constant>NULL</constant> pointer here.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>length</parameter></term>
- <listitem>
- <para>Length of the memory area to map. This must be the
-same value as returned by the driver in the &v4l2-buffer;
-<structfield>length</structfield> field for the
-single-planar API, and the same value as returned by the driver
-in the &v4l2-plane; <structfield>length</structfield> field for the
-multi-planar API.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prot</parameter></term>
- <listitem>
- <para>The <parameter>prot</parameter> argument describes the
-desired memory protection. Regardless of the device type and the
-direction of data exchange it should be set to
-<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
-permitting read and write access to image buffers. Drivers should
-support at least this combination of flags. Note the Linux
-<filename>video-buf</filename> kernel module, which is used by the
-bttv, saa7134, saa7146, cx88 and vivi driver supports only
-<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
-the driver does not support the desired protection the
-<function>mmap()</function> function fails.</para>
- <para>Note device memory accesses (&eg; the memory on a
-graphics card with video capturing hardware) may incur a performance
-penalty compared to main memory accesses, or reads may be
-significantly slower than writes or vice versa. Other I/O methods may
-be more efficient in this case.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>The <parameter>flags</parameter> parameter
-specifies the type of the mapped object, mapping options and whether
-modifications made to the mapped copy of the page are private to the
-process or are to be shared with other references.</para>
- <para><constant>MAP_FIXED</constant> requests that the
-driver selects no other address than the one specified. If the
-specified address cannot be used, <function>mmap()</function> will fail. If
-<constant>MAP_FIXED</constant> is specified,
-<parameter>start</parameter> must be a multiple of the pagesize. Use
-of this option is discouraged.</para>
- <para>One of the <constant>MAP_SHARED</constant> or
-<constant>MAP_PRIVATE</constant> flags must be set.
-<constant>MAP_SHARED</constant> allows applications to share the
-mapped memory with other (&eg; child-) processes. Note the Linux
-<filename>video-buf</filename> module which is used by the bttv,
-saa7134, saa7146, cx88 and vivi driver supports only
-<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
-requests copy-on-write semantics. V4L2 applications should not set the
-<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>,
-<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant>
-flag.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>offset</parameter></term>
- <listitem>
- <para>Offset of the buffer in device memory. This must be the
-same value as returned by the driver in the &v4l2-buffer;
-<structfield>m</structfield> union <structfield>offset</structfield> field for
-the single-planar API, and the same value as returned by the driver
-in the &v4l2-plane; <structfield>m</structfield> union
-<structfield>mem_offset</structfield> field for the multi-planar API.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The <function>mmap()</function> function asks to map
-<parameter>length</parameter> bytes starting at
-<parameter>offset</parameter> in the memory of the device specified by
-<parameter>fd</parameter> into the application address space,
-preferably at address <parameter>start</parameter>. This latter
-address is a hint only, and is usually specified as 0.</para>
-
- <para>Suitable length and offset parameters are queried with the
-&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the
-&VIDIOC-REQBUFS; ioctl before they can be queried.</para>
-
- <para>To unmap buffers the &func-munmap; function is used.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success <function>mmap()</function> returns a pointer to
-the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
-returned, and the <varname>errno</varname> variable is set
-appropriately. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid file
-descriptor.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is
-not open for reading and writing.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>start</parameter> or
-<parameter>length</parameter> or <parameter>offset</parameter> are not
-suitable. (E.&nbsp;g. they are too large, or not aligned on a
-<constant>PAGESIZE</constant> boundary.)</para>
- <para>The <parameter>flags</parameter> or
-<parameter>prot</parameter> value is not supported.</para>
- <para>No buffers have been allocated with the
-&VIDIOC-REQBUFS; ioctl.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOMEM</errorcode></term>
- <listitem>
- <para>Not enough physical or virtual memory was available to
-complete the request.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-munmap.xml b/Documentation/DocBook/media/v4l/func-munmap.xml
deleted file mode 100644
index 860d49ca54a5..000000000000
--- a/Documentation/DocBook/media/v4l/func-munmap.xml
+++ /dev/null
@@ -1,76 +0,0 @@
-<refentry id="func-munmap">
- <refmeta>
- <refentrytitle>V4L2 munmap()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-munmap</refname>
- <refpurpose>Unmap device memory</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>
-#include &lt;unistd.h&gt;
-#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>munmap</function></funcdef>
- <paramdef>void *<parameter>start</parameter></paramdef>
- <paramdef>size_t <parameter>length</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>Arguments</title>
- <variablelist>
- <varlistentry>
- <term><parameter>start</parameter></term>
- <listitem>
- <para>Address of the mapped buffer as returned by the
-&func-mmap; function.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>length</parameter></term>
- <listitem>
- <para>Length of the mapped buffer. This must be the same
-value as given to <function>mmap()</function> and returned by the
-driver in the &v4l2-buffer; <structfield>length</structfield>
-field for the single-planar API and in the &v4l2-plane;
-<structfield>length</structfield> field for the multi-planar API.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Unmaps a previously with the &func-mmap; function mapped
-buffer and frees it, if possible. <!-- ? This function (not freeing)
-has no impact on I/O in progress, specifically it does not imply
-&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
-enqueued, dequeued or queried, they are just not accessible by the
-application.--></para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success <function>munmap()</function> returns 0, on
-failure -1 and the <varname>errno</varname> variable is set
-appropriately:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>start</parameter> or
-<parameter>length</parameter> is incorrect, or no buffers have been
-mapped yet.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-open.xml b/Documentation/DocBook/media/v4l/func-open.xml
deleted file mode 100644
index cf64e207c3ee..000000000000
--- a/Documentation/DocBook/media/v4l/func-open.xml
+++ /dev/null
@@ -1,113 +0,0 @@
-<refentry id="func-open">
- <refmeta>
- <refentrytitle>V4L2 open()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-open</refname>
- <refpurpose>Open a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>open</function></funcdef>
- <paramdef>const char *<parameter>device_name</parameter></paramdef>
- <paramdef>int <parameter>flags</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>device_name</parameter></term>
- <listitem>
- <para>Device to be opened.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>Open flags. Access mode must be
-<constant>O_RDWR</constant>. This is just a technicality, input devices
-still support only reading and output devices only writing.</para>
- <para>When the <constant>O_NONBLOCK</constant> flag is
-given, the read() function and the &VIDIOC-DQBUF; ioctl will return
-the &EAGAIN; when no data is available or no buffer is in the driver
-outgoing queue, otherwise these functions block until data becomes
-available. All V4L2 drivers exchanging data with applications must
-support the <constant>O_NONBLOCK</constant> flag.</para>
- <para>Other flags have no effect.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
-
- <para>To open a V4L2 device applications call
-<function>open()</function> with the desired device name. This
-function has no side effects; all data format parameters, current
-input or output, control values or other properties remain unchanged.
-At the first <function>open()</function> call after loading the driver
-they will be reset to default values, drivers are never in an
-undefined state.</para>
- </refsect1>
- <refsect1>
- <title>Return Value</title>
-
- <para>On success <function>open</function> returns the new file
-descriptor. On error -1 is returned, and the <varname>errno</varname>
-variable is set appropriately. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para>The caller has no permission to access the
-device.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple opens and the
-device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENXIO</errorcode></term>
- <listitem>
- <para>No device corresponding to this device special file
-exists.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOMEM</errorcode></term>
- <listitem>
- <para>Not enough kernel memory was available to complete the
-request.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EMFILE</errorcode></term>
- <listitem>
- <para>The process already has the maximum number of
-files open.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENFILE</errorcode></term>
- <listitem>
- <para>The limit on the total number of files open on the
-system has been reached.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml
deleted file mode 100644
index 4c73f115219b..000000000000
--- a/Documentation/DocBook/media/v4l/func-poll.xml
+++ /dev/null
@@ -1,142 +0,0 @@
-<refentry id="func-poll">
- <refmeta>
- <refentrytitle>V4L2 poll()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-poll</refname>
- <refpurpose>Wait for some event on a file descriptor</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;sys/poll.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>poll</function></funcdef>
- <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
- <paramdef>unsigned int <parameter>nfds</parameter></paramdef>
- <paramdef>int <parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>With the <function>poll()</function> function applications
-can suspend execution until the driver has captured data or is ready
-to accept data for output.</para>
-
- <para>When streaming I/O has been negotiated this function waits
-until a buffer has been filled by the capture device and can be dequeued
-with the &VIDIOC-DQBUF; ioctl. For output devices this function waits
-until the device is ready to accept a new buffer to be queued up with
-the &VIDIOC-QBUF; ioctl for display. When buffers are already in the outgoing
-queue of the driver (capture) or the incoming queue isn't full (display)
-the function returns immediately.</para>
-
- <para>On success <function>poll()</function> returns the number of
-file descriptors that have been selected (that is, file descriptors
-for which the <structfield>revents</structfield> field of the
-respective <structname>pollfd</structname> structure is non-zero).
-Capture devices set the <constant>POLLIN</constant> and
-<constant>POLLRDNORM</constant> flags in the
-<structfield>revents</structfield> field, output devices the
-<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
-flags. When the function timed out it returns a value of zero, on
-failure it returns <returnvalue>-1</returnvalue> and the
-<varname>errno</varname> variable is set appropriately. When the
-application did not call &VIDIOC-STREAMON; the
-<function>poll()</function> function succeeds, but sets the
-<constant>POLLERR</constant> flag in the
-<structfield>revents</structfield> field. When the
-application has called &VIDIOC-STREAMON; for a capture device but hasn't
-yet called &VIDIOC-QBUF;, the <function>poll()</function> function
-succeeds and sets the <constant>POLLERR</constant> flag in the
-<structfield>revents</structfield> field. For output devices this
-same situation will cause <function>poll()</function> to succeed
-as well, but it sets the <constant>POLLOUT</constant> and
-<constant>POLLWRNORM</constant> flags in the <structfield>revents</structfield>
-field.</para>
-
- <para>If an event occurred (see &VIDIOC-DQEVENT;) then
-<constant>POLLPRI</constant> will be set in the <structfield>revents</structfield>
-field and <function>poll()</function> will return.</para>
-
- <para>When use of the <function>read()</function> function has
-been negotiated and the driver does not capture yet, the
-<function>poll</function> function starts capturing. When that fails
-it returns a <constant>POLLERR</constant> as above. Otherwise it waits
-until data has been captured and can be read. When the driver captures
-continuously (as opposed to, for example, still images) the function
-may return immediately.</para>
-
- <para>When use of the <function>write()</function> function has
-been negotiated and the driver does not stream yet, the
-<function>poll</function> function starts streaming. When that fails
-it returns a <constant>POLLERR</constant> as above. Otherwise it waits
-until the driver is ready for a non-blocking
-<function>write()</function> call.</para>
-
- <para>If the caller is only interested in events (just
-<constant>POLLPRI</constant> is set in the <structfield>events</structfield>
-field), then <function>poll()</function> will <emphasis>not</emphasis>
-start streaming if the driver does not stream yet. This makes it
-possible to just poll for events and not for buffers.</para>
-
- <para>All drivers implementing the <function>read()</function> or
-<function>write()</function> function or streaming I/O must also
-support the <function>poll()</function> function.</para>
-
- <para>For more details see the
-<function>poll()</function> manual page.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, <function>poll()</function> returns the number
-structures which have non-zero <structfield>revents</structfield>
-fields, or zero if the call timed out. On error
-<returnvalue>-1</returnvalue> is returned, and the
-<varname>errno</varname> variable is set appropriately:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para>One or more of the <parameter>ufds</parameter> members
-specify an invalid file descriptor.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple read or write
-streams and the device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para><parameter>ufds</parameter> references an inaccessible
-memory area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>nfds</parameter> argument is greater
-than <constant>OPEN_MAX</constant>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml
deleted file mode 100644
index e218bbfbd362..000000000000
--- a/Documentation/DocBook/media/v4l/func-read.xml
+++ /dev/null
@@ -1,181 +0,0 @@
-<refentry id="func-read">
- <refmeta>
- <refentrytitle>V4L2 read()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-read</refname>
- <refpurpose>Read from a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>ssize_t <function>read</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>void *<parameter>buf</parameter></paramdef>
- <paramdef>size_t <parameter>count</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>buf</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>count</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para><function>read()</function> attempts to read up to
-<parameter>count</parameter> bytes from file descriptor
-<parameter>fd</parameter> into the buffer starting at
-<parameter>buf</parameter>. The layout of the data in the buffer is
-discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero,
-<function>read()</function> returns zero and has no other results. If
-<parameter>count</parameter> is greater than
-<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless
-of the <parameter>count</parameter> value each
-<function>read()</function> call will provide at most one frame (two
-fields) worth of data.</para>
-
- <para>By default <function>read()</function> blocks until data
-becomes available. When the <constant>O_NONBLOCK</constant> flag was
-given to the &func-open; function it
-returns immediately with an &EAGAIN; when no data is available. The
-&func-select; or &func-poll; functions
-can always be used to suspend execution until data becomes available. All
-drivers supporting the <function>read()</function> function must also
-support <function>select()</function> and
-<function>poll()</function>.</para>
-
- <para>Drivers can implement read functionality in different
-ways, using a single or multiple buffers and discarding the oldest or
-newest frames once the internal buffers are filled.</para>
-
- <para><function>read()</function> never returns a "snapshot" of a
-buffer being filled. Using a single buffer the driver will stop
-capturing when the application starts reading the buffer until the
-read is finished. Thus only the period of the vertical blanking
-interval is available for reading, or the capture rate must fall below
-the nominal frame rate of the video standard.</para>
-
-<para>The behavior of
-<function>read()</function> when called during the active picture
-period or the vertical blanking separating the top and bottom field
-depends on the discarding policy. A driver discarding the oldest
-frames keeps capturing into an internal buffer, continuously
-overwriting the previously, not read frame, and returns the frame
-being received at the time of the <function>read()</function> call as
-soon as it is complete.</para>
-
- <para>A driver discarding the newest frames stops capturing until
-the next <function>read()</function> call. The frame being received at
-<function>read()</function> time is discarded, returning the following
-frame instead. Again this implies a reduction of the capture rate to
-one half or less of the nominal frame rate. An example of this model
-is the video read mode of the bttv driver, initiating a DMA to user
-memory when <function>read()</function> is called and returning when
-the DMA finished.</para>
-
- <para>In the multiple buffer model drivers maintain a ring of
-internal buffers, automatically advancing to the next free buffer.
-This allows continuous capturing when the application can empty the
-buffers fast enough. Again, the behavior when the driver runs out of
-free buffers depends on the discarding policy.</para>
-
- <para>Applications can get and set the number of buffers used
-internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM;
-ioctls. They are optional, however. The discarding policy is not
-reported and cannot be changed. For minimum requirements see <xref
- linkend="devices" />.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, the number of bytes read is returned. It is not
-an error if this number is smaller than the number of bytes requested,
-or the amount of data required for one frame. This may happen for
-example because <function>read()</function> was interrupted by a
-signal. On error, -1 is returned, and the <varname>errno</varname>
-variable is set appropriately. In this case the next read will start
-at the beginning of a new frame. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EAGAIN</errorcode></term>
- <listitem>
- <para>Non-blocking I/O has been selected using
-O_NONBLOCK and no data was immediately available for reading.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid file
-descriptor or is not open for reading, or the process already has the
-maximum number of files open.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple read streams and the
-device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para><parameter>buf</parameter> references an inaccessible
-memory area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal before any
-data was read.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EIO</errorcode></term>
- <listitem>
- <para>I/O error. This indicates some hardware problem or a
-failure to communicate with a remote device (USB camera etc.).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <function>read()</function> function is not
-supported by this driver, not on this device, or generally not on this
-type of device.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-select.xml b/Documentation/DocBook/media/v4l/func-select.xml
deleted file mode 100644
index e12a60d9bd85..000000000000
--- a/Documentation/DocBook/media/v4l/func-select.xml
+++ /dev/null
@@ -1,130 +0,0 @@
-<refentry id="func-select">
- <refmeta>
- <refentrytitle>V4L2 select()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-select</refname>
- <refpurpose>Synchronous I/O multiplexing</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>
-#include &lt;sys/time.h&gt;
-#include &lt;sys/types.h&gt;
-#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>select</function></funcdef>
- <paramdef>int <parameter>nfds</parameter></paramdef>
- <paramdef>fd_set *<parameter>readfds</parameter></paramdef>
- <paramdef>fd_set *<parameter>writefds</parameter></paramdef>
- <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef>
- <paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>With the <function>select()</function> function applications
-can suspend execution until the driver has captured data or is ready
-to accept data for output.</para>
-
- <para>When streaming I/O has been negotiated this function waits
-until a buffer has been filled or displayed and can be dequeued with
-the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
-queue of the driver the function returns immediately.</para>
-
- <para>On success <function>select()</function> returns the total
-number of bits set in the <structname>fd_set</structname>s. When the
-function timed out it returns a value of zero. On failure it returns
-<returnvalue>-1</returnvalue> and the <varname>errno</varname>
-variable is set appropriately. When the application did not call
-&VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
-<function>select()</function> function succeeds, setting the bit of
-the file descriptor in <parameter>readfds</parameter> or
-<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
-will fail.<footnote><para>The Linux kernel implements
-<function>select()</function> like the &func-poll; function, but
-<function>select()</function> cannot return a
-<constant>POLLERR</constant>.</para>
- </footnote></para>
-
- <para>When use of the <function>read()</function> function has
-been negotiated and the driver does not capture yet, the
-<function>select()</function> function starts capturing. When that
-fails, <function>select()</function> returns successful and a
-subsequent <function>read()</function> call, which also attempts to
-start capturing, will return an appropriate error code. When the
-driver captures continuously (as opposed to, for example, still
-images) and data is already available the
-<function>select()</function> function returns immediately.</para>
-
- <para>When use of the <function>write()</function> function has
-been negotiated the <function>select()</function> function just waits
-until the driver is ready for a non-blocking
-<function>write()</function> call.</para>
-
- <para>All drivers implementing the <function>read()</function> or
-<function>write()</function> function or streaming I/O must also
-support the <function>select()</function> function.</para>
-
- <para>For more details see the <function>select()</function>
-manual page.</para>
-
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, <function>select()</function> returns the number
-of descriptors contained in the three returned descriptor sets, which
-will be zero if the timeout expired. On error
-<returnvalue>-1</returnvalue> is returned, and the
-<varname>errno</varname> variable is set appropriately; the sets and
-<parameter>timeout</parameter> are undefined. Possible error codes
-are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para>One or more of the file descriptor sets specified a
-file descriptor that is not open.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple read or write
-streams and the device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para>The <parameter>readfds</parameter>,
-<parameter>writefds</parameter>, <parameter>exceptfds</parameter> or
-<parameter>timeout</parameter> pointer references an inaccessible memory
-area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>nfds</parameter> argument is less than
-zero or greater than <constant>FD_SETSIZE</constant>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-write.xml b/Documentation/DocBook/media/v4l/func-write.xml
deleted file mode 100644
index 575207885726..000000000000
--- a/Documentation/DocBook/media/v4l/func-write.xml
+++ /dev/null
@@ -1,128 +0,0 @@
-<refentry id="func-write">
- <refmeta>
- <refentrytitle>V4L2 write()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-write</refname>
- <refpurpose>Write to a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>ssize_t <function>write</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>void *<parameter>buf</parameter></paramdef>
- <paramdef>size_t <parameter>count</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>buf</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>count</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para><function>write()</function> writes up to
-<parameter>count</parameter> bytes to the device referenced by the
-file descriptor <parameter>fd</parameter> from the buffer starting at
-<parameter>buf</parameter>. When the hardware outputs are not active
-yet, this function enables them. When <parameter>count</parameter> is
-zero, <function>write()</function> returns
-<returnvalue>0</returnvalue> without any other effect.</para>
-
- <para>When the application does not provide more data in time, the
-previous video frame, raw VBI image, sliced VPS or WSS data is
-displayed again. Sliced Teletext or Closed Caption data is not
-repeated, the driver inserts a blank line instead.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, the number of bytes written are returned. Zero
-indicates nothing was written. On error, <returnvalue>-1</returnvalue>
-is returned, and the <varname>errno</varname> variable is set
-appropriately. In this case the next write will start at the beginning
-of a new frame. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EAGAIN</errorcode></term>
- <listitem>
- <para>Non-blocking I/O has been selected using the <link
-linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no
-buffer space was available to write the data immediately.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid file
-descriptor or is not open for writing.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple write streams and the
-device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para><parameter>buf</parameter> references an inaccessible
-memory area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal before any
-data was written.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EIO</errorcode></term>
- <listitem>
- <para>I/O error. This indicates some hardware problem.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <function>write()</function> function is not
-supported by this driver, not on this device, or generally not on this
-type of device.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml
deleted file mode 100644
index 7e29a4e1f696..000000000000
--- a/Documentation/DocBook/media/v4l/gen-errors.xml
+++ /dev/null
@@ -1,77 +0,0 @@
-<title>Generic Error Codes</title>
-
-<table frame="none" pgwide="1" id="gen-errors">
- <title>Generic error codes</title>
- <tgroup cols="2">
- &cs-str;
- <tbody valign="top">
- <!-- Keep it ordered alphabetically -->
- <row>
- <entry>EAGAIN (aka EWOULDBLOCK)</entry>
- <entry>The ioctl can't be handled because the device is in state where
- it can't perform it. This could happen for example in case where
- device is sleeping and ioctl is performed to query statistics.
- It is also returned when the ioctl would need to wait
- for an event, but the device was opened in non-blocking mode.
- </entry>
- </row>
- <row>
- <entry>EBADF</entry>
- <entry>The file descriptor is not a valid.</entry>
- </row>
- <row>
- <entry>EBUSY</entry>
- <entry>The ioctl can't be handled because the device is busy. This is
- typically return while device is streaming, and an ioctl tried to
- change something that would affect the stream, or would require the
- usage of a hardware resource that was already allocated. The ioctl
- must not be retried without performing another action to fix the
- problem first (typically: stop the stream before retrying).</entry>
- </row>
- <row>
- <entry>EFAULT</entry>
- <entry>There was a failure while copying data from/to userspace,
- probably caused by an invalid pointer reference.</entry>
- </row>
- <row>
- <entry>EINVAL</entry>
- <entry>One or more of the ioctl parameters are invalid or out of the
- allowed range. This is a widely used error code. See the individual
- ioctl requests for specific causes.</entry>
- </row>
- <row>
- <entry>ENODEV</entry>
- <entry>Device not found or was removed.</entry>
- </row>
- <row>
- <entry>ENOMEM</entry>
- <entry>There's not enough memory to handle the desired operation.</entry>
- </row>
- <row>
- <entry>ENOTTY</entry>
- <entry>The ioctl is not supported by the driver, actually meaning that
- the required functionality is not available, or the file
- descriptor is not for a media device.</entry>
- </row>
- <row>
- <entry>ENOSPC</entry>
- <entry>On USB devices, the stream ioctl's can return this error, meaning
- that this request would overcommit the usb bandwidth reserved
- for periodic transfers (up to 80% of the USB bandwidth).</entry>
- </row>
- <row>
- <entry>EPERM</entry>
- <entry>Permission denied. Can be returned if the device needs write
- permission, or some special capabilities is needed
- (e. g. root)</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>Note 1: ioctls may return other error codes. Since errors may have side
-effects such as a driver reset, applications should abort on unexpected errors.
-</para>
-
-<para>Note 2: Request-specific error codes are listed in the individual
-requests descriptions.</para>
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
deleted file mode 100644
index 1c17f802b471..000000000000
--- a/Documentation/DocBook/media/v4l/io.xml
+++ /dev/null
@@ -1,1533 +0,0 @@
- <title>Input/Output</title>
-
- <para>The V4L2 API defines several different methods to read from or
-write to a device. All drivers exchanging data with applications must
-support at least one of them.</para>
-
- <para>The classic I/O method using the <function>read()</function>
-and <function>write()</function> function is automatically selected
-after opening a V4L2 device. When the driver does not support this
-method attempts to read or write will fail at any time.</para>
-
- <para>Other methods must be negotiated. To select the streaming I/O
-method with memory mapped or user buffers applications call the
-&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
-yet.</para>
-
- <para>Video overlay can be considered another I/O method, although
-the application does not directly receive the image data. It is
-selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
-For more information see <xref linkend="overlay" />.</para>
-
- <para>Generally exactly one I/O method, including overlay, is
-associated with each file descriptor. The only exceptions are
-applications not exchanging data with a driver ("panel applications",
-see <xref linkend="open" />) and drivers permitting simultaneous video capturing
-and overlay using the same file descriptor, for compatibility with V4L
-and earlier versions of V4L2.</para>
-
- <para><constant>VIDIOC_S_FMT</constant> and
-<constant>VIDIOC_REQBUFS</constant> would permit this to some degree,
-but for simplicity drivers need not support switching the I/O method
-(after first switching away from read/write) other than by closing
-and reopening the device.</para>
-
- <para>The following sections describe the various I/O methods in
-more detail.</para>
-
- <section id="rw">
- <title>Read/Write</title>
-
- <para>Input and output devices support the
-<function>read()</function> and <function>write()</function> function,
-respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
-
- <para>Drivers may need the CPU to copy the data, but they may also
-support DMA to or from user memory, so this I/O method is not
-necessarily less efficient than other methods merely exchanging buffer
-pointers. It is considered inferior though because no meta-information
-like frame counters or timestamps are passed. This information is
-necessary to recognize frame dropping and to synchronize with other
-data streams. However this is also the simplest I/O method, requiring
-little or no setup to exchange data. It permits command line stunts
-like this (the <application>vidctrl</application> tool is
-fictitious):</para>
-
- <informalexample>
- <screen>
-&gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
-&gt; dd if=/dev/video of=myimage.422 bs=202752 count=1
-</screen>
- </informalexample>
-
- <para>To read from the device applications use the
-&func-read; function, to write the &func-write; function.
-Drivers must implement one I/O method if they
-exchange data with applications, but it need not be this.<footnote>
- <para>It would be desirable if applications could depend on
-drivers supporting all I/O interfaces, but as much as the complex
-memory mapping I/O can be inadequate for some devices we have no
-reason to require this interface, which is most useful for simple
-applications capturing still images.</para>
- </footnote> When reading or writing is supported, the driver
-must also support the &func-select; and &func-poll;
-function.<footnote>
- <para>At the driver level <function>select()</function> and
-<function>poll()</function> are the same, and
-<function>select()</function> is too important to be optional.</para>
- </footnote></para>
- </section>
-
- <section id="mmap">
- <title>Streaming I/O (Memory Mapping)</title>
-
- <para>Input and output devices support this I/O method when the
-<constant>V4L2_CAP_STREAMING</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
-streaming methods, to determine if the memory mapping flavor is
-supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
-
- <para>Streaming is an I/O method where only pointers to buffers
-are exchanged between application and driver, the data itself is not
-copied. Memory mapping is primarily intended to map buffers in device
-memory into the application's address space. Device memory can be for
-example the video memory on a graphics card with a video capture
-add-on. However, being the most efficient I/O method available for a
-long time, many other drivers support streaming as well, allocating
-buffers in DMA-able main memory.</para>
-
- <para>A driver can support many sets of buffers. Each set is
-identified by a unique buffer type value. The sets are independent and
-each set can hold a different type of data. To access different sets
-at the same time different file descriptors must be used.<footnote>
- <para>One could use one file descriptor and set the buffer
-type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
-the <function>select()</function> function ambiguous. We also like the
-clean approach of one file descriptor per logical stream. Video
-overlay for example is also a logical stream, although the CPU is not
-needed for continuous operation.</para>
- </footnote></para>
-
- <para>To allocate device buffers applications call the
-&VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer
-type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.
-This ioctl can also be used to change the number of buffers or to free
-the allocated memory, provided none of the buffers are still
-mapped.</para>
-
- <para>Before applications can access the buffers they must map
-them into their address space with the &func-mmap; function. The
-location of the buffers in device memory can be determined with the
-&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
-<structfield>m.offset</structfield> and <structfield>length</structfield>
-returned in a &v4l2-buffer; are passed as sixth and second parameter to the
-<function>mmap()</function> function. When using the multi-planar API,
-&v4l2-buffer; contains an array of &v4l2-plane; structures, each
-containing its own <structfield>m.offset</structfield> and
-<structfield>length</structfield>. When using the multi-planar API, every
-plane of every buffer has to be mapped separately, so the number of
-calls to &func-mmap; should be equal to number of buffers times number of
-planes in each buffer. The offset and length values must not be modified.
-Remember, the buffers are allocated in physical memory, as opposed to virtual
-memory, which can be swapped out to disk. Applications should free the buffers
-as soon as possible with the &func-munmap; function.</para>
-
- <example>
- <title>Mapping buffers in the single-planar API</title>
- <programlisting>
-&v4l2-requestbuffers; reqbuf;
-struct {
- void *start;
- size_t length;
-} *buffers;
-unsigned int i;
-
-memset(&amp;reqbuf, 0, sizeof(reqbuf));
-reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-reqbuf.memory = V4L2_MEMORY_MMAP;
-reqbuf.count = 20;
-
-if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
- if (errno == EINVAL)
- printf("Video capturing or mmap-streaming is not supported\n");
- else
- perror("VIDIOC_REQBUFS");
-
- exit(EXIT_FAILURE);
-}
-
-/* We want at least five buffers. */
-
-if (reqbuf.count &lt; 5) {
- /* You may need to free the buffers here. */
- printf("Not enough buffer memory\n");
- exit(EXIT_FAILURE);
-}
-
-buffers = calloc(reqbuf.count, sizeof(*buffers));
-assert(buffers != NULL);
-
-for (i = 0; i &lt; reqbuf.count; i++) {
- &v4l2-buffer; buffer;
-
- memset(&amp;buffer, 0, sizeof(buffer));
- buffer.type = reqbuf.type;
- buffer.memory = V4L2_MEMORY_MMAP;
- buffer.index = i;
-
- if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
- perror("VIDIOC_QUERYBUF");
- exit(EXIT_FAILURE);
- }
-
- buffers[i].length = buffer.length; /* remember for munmap() */
-
- buffers[i].start = mmap(NULL, buffer.length,
- PROT_READ | PROT_WRITE, /* recommended */
- MAP_SHARED, /* recommended */
- fd, buffer.m.offset);
-
- if (MAP_FAILED == buffers[i].start) {
- /* If you do not exit here you should unmap() and free()
- the buffers mapped so far. */
- perror("mmap");
- exit(EXIT_FAILURE);
- }
-}
-
-/* Cleanup. */
-
-for (i = 0; i &lt; reqbuf.count; i++)
- munmap(buffers[i].start, buffers[i].length);
- </programlisting>
- </example>
-
- <example>
- <title>Mapping buffers in the multi-planar API</title>
- <programlisting>
-&v4l2-requestbuffers; reqbuf;
-/* Our current format uses 3 planes per buffer */
-#define FMT_NUM_PLANES = 3
-
-struct {
- void *start[FMT_NUM_PLANES];
- size_t length[FMT_NUM_PLANES];
-} *buffers;
-unsigned int i, j;
-
-memset(&amp;reqbuf, 0, sizeof(reqbuf));
-reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
-reqbuf.memory = V4L2_MEMORY_MMAP;
-reqbuf.count = 20;
-
-if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) &lt; 0) {
- if (errno == EINVAL)
- printf("Video capturing or mmap-streaming is not supported\n");
- else
- perror("VIDIOC_REQBUFS");
-
- exit(EXIT_FAILURE);
-}
-
-/* We want at least five buffers. */
-
-if (reqbuf.count &lt; 5) {
- /* You may need to free the buffers here. */
- printf("Not enough buffer memory\n");
- exit(EXIT_FAILURE);
-}
-
-buffers = calloc(reqbuf.count, sizeof(*buffers));
-assert(buffers != NULL);
-
-for (i = 0; i &lt; reqbuf.count; i++) {
- &v4l2-buffer; buffer;
- &v4l2-plane; planes[FMT_NUM_PLANES];
-
- memset(&amp;buffer, 0, sizeof(buffer));
- buffer.type = reqbuf.type;
- buffer.memory = V4L2_MEMORY_MMAP;
- buffer.index = i;
- /* length in struct v4l2_buffer in multi-planar API stores the size
- * of planes array. */
- buffer.length = FMT_NUM_PLANES;
- buffer.m.planes = planes;
-
- if (ioctl(fd, &VIDIOC-QUERYBUF;, &amp;buffer) &lt; 0) {
- perror("VIDIOC_QUERYBUF");
- exit(EXIT_FAILURE);
- }
-
- /* Every plane has to be mapped separately */
- for (j = 0; j &lt; FMT_NUM_PLANES; j++) {
- buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
-
- buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
- PROT_READ | PROT_WRITE, /* recommended */
- MAP_SHARED, /* recommended */
- fd, buffer.m.planes[j].m.offset);
-
- if (MAP_FAILED == buffers[i].start[j]) {
- /* If you do not exit here you should unmap() and free()
- the buffers and planes mapped so far. */
- perror("mmap");
- exit(EXIT_FAILURE);
- }
- }
-}
-
-/* Cleanup. */
-
-for (i = 0; i &lt; reqbuf.count; i++)
- for (j = 0; j &lt; FMT_NUM_PLANES; j++)
- munmap(buffers[i].start[j], buffers[i].length[j]);
- </programlisting>
- </example>
-
- <para>Conceptually streaming drivers maintain two buffer queues, an incoming
-and an outgoing queue. They separate the synchronous capture or output
-operation locked to a video clock from the application which is
-subject to random disk or network delays and preemption by
-other processes, thereby reducing the probability of data loss.
-The queues are organized as FIFOs, buffers will be
-output in the order enqueued in the incoming FIFO, and were
-captured in the order dequeued from the outgoing FIFO.</para>
-
- <para>The driver may require a minimum number of buffers enqueued
-at all times to function, apart of this no limit exists on the number
-of buffers applications can enqueue in advance, or dequeue and
-process. They can also enqueue in a different order than buffers have
-been dequeued, and the driver can <emphasis>fill</emphasis> enqueued
-<emphasis>empty</emphasis> buffers in any order. <footnote>
- <para>Random enqueue order permits applications processing
-images out of order (such as video codecs) to return buffers earlier,
-reducing the probability of data loss. Random fill order allows
-drivers to reuse buffers on a LIFO-basis, taking advantage of caches
-holding scatter-gather lists and the like.</para>
- </footnote> The index number of a buffer (&v4l2-buffer;
-<structfield>index</structfield>) plays no role here, it only
-identifies the buffer.</para>
-
- <para>Initially all mapped buffers are in dequeued state,
-inaccessible by the driver. For capturing applications it is customary
-to first enqueue all mapped buffers, then to start capturing and enter
-the read loop. Here the application waits until a filled buffer can be
-dequeued, and re-enqueues the buffer when the data is no longer
-needed. Output applications fill and enqueue buffers, when enough
-buffers are stacked up the output is started with
-<constant>VIDIOC_STREAMON</constant>. In the write loop, when
-the application runs out of free buffers, it must wait until an empty
-buffer can be dequeued and reused.</para>
-
- <para>To enqueue and dequeue a buffer applications use the
-&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
-mapped, enqueued, full or empty can be determined at any time using the
-&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
-application until one or more buffers can be dequeued. By default
-<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
-outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
-given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
-returns immediately with an &EAGAIN; when no buffer is available. The
-&func-select; or &func-poll; functions are always available.</para>
-
- <para>To start and stop capturing or output applications call the
-&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
-<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
-queues as a side effect. Since there is no notion of doing anything
-"now" on a multitasking system, if an application needs to synchronize
-with another event it should examine the &v4l2-buffer;
-<structfield>timestamp</structfield> of captured or outputted buffers.
-</para>
-
- <para>Drivers implementing memory mapping I/O must
-support the <constant>VIDIOC_REQBUFS</constant>,
-<constant>VIDIOC_QUERYBUF</constant>,
-<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
-<constant>VIDIOC_STREAMON</constant> and
-<constant>VIDIOC_STREAMOFF</constant> ioctl, the
-<function>mmap()</function>, <function>munmap()</function>,
-<function>select()</function> and <function>poll()</function>
-function.<footnote>
- <para>At the driver level <function>select()</function> and
-<function>poll()</function> are the same, and
-<function>select()</function> is too important to be optional. The
-rest should be evident.</para>
- </footnote></para>
-
- <para>[capture example]</para>
-
- </section>
-
- <section id="userp">
- <title>Streaming I/O (User Pointers)</title>
-
- <para>Input and output devices support this I/O method when the
-<constant>V4L2_CAP_STREAMING</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
-pointer method (not only memory mapping) is supported must be
-determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
-
- <para>This I/O method combines advantages of the read/write and
-memory mapping methods. Buffers (planes) are allocated by the application
-itself, and can reside for example in virtual or shared memory. Only
-pointers to data are exchanged, these pointers and meta-information
-are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
-The driver must be switched into user pointer I/O mode by calling the
-&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
-beforehand, consequently they are not indexed and cannot be queried like mapped
-buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
-
- <example>
- <title>Initiating streaming I/O with user pointers</title>
-
- <programlisting>
-&v4l2-requestbuffers; reqbuf;
-
-memset (&amp;reqbuf, 0, sizeof (reqbuf));
-reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-reqbuf.memory = V4L2_MEMORY_USERPTR;
-
-if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
- if (errno == EINVAL)
- printf ("Video capturing or user pointer streaming is not supported\n");
- else
- perror ("VIDIOC_REQBUFS");
-
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <para>Buffer (plane) addresses and sizes are passed on the fly with the
-&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
-applications can pass different addresses and sizes at each
-<constant>VIDIOC_QBUF</constant> call. If required by the hardware the
-driver swaps memory pages within physical memory to create a
-continuous area of memory. This happens transparently to the
-application in the virtual memory subsystem of the kernel. When buffer
-pages have been swapped out to disk they are brought back and finally
-locked in physical memory for DMA.<footnote>
- <para>We expect that frequently used buffers are typically not
-swapped out. Anyway, the process of swapping, locking or generating
-scatter-gather lists may be time consuming. The delay can be masked by
-the depth of the incoming buffer queue, and perhaps by maintaining
-caches assuming a buffer will be soon enqueued again. On the other
-hand, to optimize memory usage drivers can limit the number of buffers
-locked in advance and recycle the most recently used buffers first. Of
-course, the pages of empty buffers in the incoming queue need not be
-saved to disk. Output buffers must be saved on the incoming and
-outgoing queue because an application may share them with other
-processes.</para>
- </footnote></para>
-
- <para>Filled or displayed buffers are dequeued with the
-&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
-time between the completion of the DMA and this ioctl. The memory is
-also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
-when the device is closed. Applications must take care not to free
-buffers without dequeuing. For once, the buffers remain locked until
-further, wasting physical memory. Second the driver will not be
-notified when the memory is returned to the application's free list
-and subsequently reused for other purposes, possibly completing the
-requested DMA and overwriting valuable data.</para>
-
- <para>For capturing applications it is customary to enqueue a
-number of empty buffers, to start capturing and enter the read loop.
-Here the application waits until a filled buffer can be dequeued, and
-re-enqueues the buffer when the data is no longer needed. Output
-applications fill and enqueue buffers, when enough buffers are stacked
-up output is started. In the write loop, when the application
-runs out of free buffers it must wait until an empty buffer can be
-dequeued and reused. Two methods exist to suspend execution of the
-application until one or more buffers can be dequeued. By default
-<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
-outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
-given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
-returns immediately with an &EAGAIN; when no buffer is available. The
-&func-select; or &func-poll; function are always available.</para>
-
- <para>To start and stop capturing or output applications call the
-&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
-<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
-queues and unlocks all buffers as a side effect. Since there is no
-notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the &v4l2-buffer; <structfield>timestamp</structfield> of captured
-or outputted buffers.</para>
-
- <para>Drivers implementing user pointer I/O must
-support the <constant>VIDIOC_REQBUFS</constant>,
-<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
-<constant>VIDIOC_STREAMON</constant> and
-<constant>VIDIOC_STREAMOFF</constant> ioctl, the
-<function>select()</function> and <function>poll()</function> function.<footnote>
- <para>At the driver level <function>select()</function> and
-<function>poll()</function> are the same, and
-<function>select()</function> is too important to be optional. The
-rest should be evident.</para>
- </footnote></para>
- </section>
-
- <section id="dmabuf">
- <title>Streaming I/O (DMA buffer importing)</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
-<para>The DMABUF framework provides a generic method for sharing buffers
-between multiple devices. Device drivers that support DMABUF can export a DMA
-buffer to userspace as a file descriptor (known as the exporter role), import a
-DMA buffer from userspace using a file descriptor previously exported for a
-different or the same device (known as the importer role), or both. This
-section describes the DMABUF importer role API in V4L2.</para>
-
- <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for
-details about exporting V4L2 buffers as DMABUF file descriptors.</para>
-
-<para>Input and output devices support the streaming I/O method when the
-<constant>V4L2_CAP_STREAMING</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability; returned by
-the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through
-DMABUF file descriptors is supported is determined by calling the
-&VIDIOC-REQBUFS; ioctl with the memory type set to
-<constant>V4L2_MEMORY_DMABUF</constant>.</para>
-
- <para>This I/O method is dedicated to sharing DMA buffers between different
-devices, which may be V4L devices or other video-related devices (e.g. DRM).
-Buffers (planes) are allocated by a driver on behalf of an application. Next,
-these buffers are exported to the application as file descriptors using an API
-which is specific for an allocator driver. Only such file descriptor are
-exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or
-in &v4l2-plane; in the multi-planar API case). The driver must be switched
-into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer
-type.</para>
-
- <example>
- <title>Initiating streaming I/O with DMABUF file descriptors</title>
-
- <programlisting>
-&v4l2-requestbuffers; reqbuf;
-
-memset(&amp;reqbuf, 0, sizeof (reqbuf));
-reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-reqbuf.memory = V4L2_MEMORY_DMABUF;
-reqbuf.count = 1;
-
-if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
- if (errno == EINVAL)
- printf("Video capturing or DMABUF streaming is not supported\n");
- else
- perror("VIDIOC_REQBUFS");
-
- exit(EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <para>The buffer (plane) file descriptor is passed on the fly with the
-&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be
-associated with a different DMABUF descriptor. Although buffers are commonly
-cycled, applications can pass a different DMABUF descriptor at each
-<constant>VIDIOC_QBUF</constant> call.</para>
-
- <example>
- <title>Queueing DMABUF using single plane API</title>
-
- <programlisting>
-int buffer_queue(int v4lfd, int index, int dmafd)
-{
- &v4l2-buffer; buf;
-
- memset(&amp;buf, 0, sizeof buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_DMABUF;
- buf.index = index;
- buf.m.fd = dmafd;
-
- if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {
- perror("VIDIOC_QBUF");
- return -1;
- }
-
- return 0;
-}
- </programlisting>
- </example>
-
- <example>
- <title>Queueing DMABUF using multi plane API</title>
-
- <programlisting>
-int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
-{
- &v4l2-buffer; buf;
- &v4l2-plane; planes[VIDEO_MAX_PLANES];
- int i;
-
- memset(&amp;buf, 0, sizeof buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
- buf.memory = V4L2_MEMORY_DMABUF;
- buf.index = index;
- buf.m.planes = planes;
- buf.length = n_planes;
-
- memset(&amp;planes, 0, sizeof planes);
-
- for (i = 0; i &lt; n_planes; ++i)
- buf.m.planes[i].m.fd = dmafd[i];
-
- if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {
- perror("VIDIOC_QBUF");
- return -1;
- }
-
- return 0;
-}
- </programlisting>
- </example>
-
- <para>Captured or displayed buffers are dequeued with the
-&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any
-time between the completion of the DMA and this ioctl. The memory is
-also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
-when the device is closed.</para>
-
- <para>For capturing applications it is customary to enqueue a
-number of empty buffers, to start capturing and enter the read loop.
-Here the application waits until a filled buffer can be dequeued, and
-re-enqueues the buffer when the data is no longer needed. Output
-applications fill and enqueue buffers, when enough buffers are stacked
-up output is started. In the write loop, when the application
-runs out of free buffers it must wait until an empty buffer can be
-dequeued and reused. Two methods exist to suspend execution of the
-application until one or more buffers can be dequeued. By default
-<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
-outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
-given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
-returns immediately with an &EAGAIN; when no buffer is available. The
-&func-select; and &func-poll; functions are always available.</para>
-
- <para>To start and stop capturing or displaying applications call the
-&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that
-<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and
-unlocks all buffers as a side effect. Since there is no notion of doing
-anything "now" on a multitasking system, if an application needs to synchronize
-with another event it should examine the &v4l2-buffer;
-<structfield>timestamp</structfield> of captured or outputted buffers.</para>
-
- <para>Drivers implementing DMABUF importing I/O must support the
-<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,
-<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and
-<constant>VIDIOC_STREAMOFF</constant> ioctls, and the
-<function>select()</function> and <function>poll()</function> functions.</para>
-
- </section>
-
- <section id="async">
- <title>Asynchronous I/O</title>
-
- <para>This method is not defined yet.</para>
- </section>
-
- <section id="buffer">
- <title>Buffers</title>
-
- <para>A buffer contains data exchanged by application and
-driver using one of the Streaming I/O methods. In the multi-planar API, the
-data is held in planes, while the buffer structure acts as a container
-for the planes. Only pointers to buffers (planes) are exchanged, the data
-itself is not copied. These pointers, together with meta-information like
-timestamps or field parity, are stored in a struct
-<structname>v4l2_buffer</structname>, argument to
-the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
-In the multi-planar API, some plane-specific members of struct
-<structname>v4l2_buffer</structname>, such as pointers and sizes for each
-plane, are stored in struct <structname>v4l2_plane</structname> instead.
-In that case, struct <structname>v4l2_buffer</structname> contains an array of
-plane structures.</para>
-
- <para>Dequeued video buffers come with timestamps. The driver
- decides at which part of the frame and with which clock the
- timestamp is taken. Please see flags in the masks
- <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and
- <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref
- linkend="buffer-flags" />. These flags are always valid and constant
- across all buffers during the whole video stream. Changes in these
- flags may take place as a side effect of &VIDIOC-S-INPUT; or
- &VIDIOC-S-OUTPUT; however. The
- <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type
- which is used by e.g. on mem-to-mem devices is an exception to the
- rule: the timestamp source flags are copied from the OUTPUT video
- buffer to the CAPTURE video buffer.</para>
-
- <table frame="none" pgwide="1" id="v4l2-buffer">
- <title>struct <structname>v4l2_buffer</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry></entry>
- <entry>Number of the buffer, set by the application except
-when calling &VIDIOC-DQBUF;, then it is set by the driver.
-This field can range from zero to the number of buffers allocated
-with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>),
-plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>Type of the buffer, same as &v4l2-format;
-<structfield>type</structfield> or &v4l2-requestbuffers;
-<structfield>type</structfield>, set by the application. See <xref
-linkend="v4l2-buf-type" /></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>bytesused</structfield></entry>
- <entry></entry>
- <entry>The number of bytes occupied by the data in the
-buffer. It depends on the negotiated data format and may change with
-each buffer for compressed variable size data like JPEG images.
-Drivers must set this field when <structfield>type</structfield>
-refers to an input stream, applications when it refers to an output stream.
-If the application sets this to 0 for an output stream, then
-<structfield>bytesused</structfield> will be set to the size of the
-buffer (see the <structfield>length</structfield> field of this struct) by
-the driver. For multiplanar formats this field is ignored and the
-<structfield>planes</structfield> pointer is used instead.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry></entry>
- <entry>Flags set by the application or driver, see <xref
-linkend="buffer-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>field</structfield></entry>
- <entry></entry>
- <entry>Indicates the field order of the image in the
-buffer, see <xref linkend="v4l2-field" />. This field is not used when
-the buffer contains VBI data. Drivers must set it when
-<structfield>type</structfield> refers to an input stream,
-applications when it refers to an output stream.</entry>
- </row>
- <row>
- <entry>struct timeval</entry>
- <entry><structfield>timestamp</structfield></entry>
- <entry></entry>
- <entry><para>For input streams this is time when the first data
- byte was captured, as returned by the
- <function>clock_gettime()</function> function for the relevant
- clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
- <xref linkend="buffer-flags" />. For output streams the driver
- stores the time at which the last data byte was actually sent out
- in the <structfield>timestamp</structfield> field. This permits
- applications to monitor the drift between the video and system
- clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant>
- the application has to fill in the timestamp which will be copied
- by the driver to the capture stream.</para></entry>
- </row>
- <row>
- <entry>&v4l2-timecode;</entry>
- <entry><structfield>timecode</structfield></entry>
- <entry></entry>
- <entry>When <structfield>type</structfield> is
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
-<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
-<structfield>flags</structfield>, this structure contains a frame
-timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
-mode the top and bottom field contain the same timecode.
-Timecodes are intended to help video editing and are typically recorded on
-video tapes, but also embedded in compressed formats like MPEG. This
-field is independent of the <structfield>timestamp</structfield> and
-<structfield>sequence</structfield> fields.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>sequence</structfield></entry>
- <entry></entry>
- <entry>Set by the driver, counting the frames (not fields!) in
-sequence. This field is set for both input and output devices.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>In <link
-linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
-bottom field have the same sequence number. The count starts at zero
-and includes dropped or repeated frames. A dropped frame was received
-by an input device but could not be stored due to lack of free buffer
-space. A repeated frame was displayed again by an output device
-because the application did not pass new data in
-time.</para><para>Note this may count the frames received
-e.g. over USB, without taking into account the frames dropped by the
-remote hardware due to limited compression throughput or bus
-bandwidth. These devices identify by not enumerating any video
-standards, see <xref linkend="standard" />.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>memory</structfield></entry>
- <entry></entry>
- <entry>This field must be set by applications and/or drivers
-in accordance with the selected I/O method. See <xref linkend="v4l2-memory"
- /></entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield>m</structfield></entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>offset</structfield></entry>
- <entry>For the single-planar API and when
-<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
-is the offset of the buffer from the start of the device memory. The value is
-returned by the driver and apart of serving as parameter to the &func-mmap;
-function not useful for applications. See <xref linkend="mmap" /> for details
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>unsigned long</entry>
- <entry><structfield>userptr</structfield></entry>
- <entry>For the single-planar API and when
-<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
-this is a pointer to the buffer (casted to unsigned long type) in virtual
-memory, set by the application. See <xref linkend="userp" /> for details.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct v4l2_plane</entry>
- <entry><structfield>*planes</structfield></entry>
- <entry>When using the multi-planar API, contains a userspace pointer
- to an array of &v4l2-plane;. The size of the array should be put
- in the <structfield>length</structfield> field of this
- <structname>v4l2_buffer</structname> structure.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>int</entry>
- <entry><structfield>fd</structfield></entry>
- <entry>For the single-plane API and when
-<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this
-is the file descriptor associated with a DMABUF buffer.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>length</structfield></entry>
- <entry></entry>
- <entry>Size of the buffer (not the payload) in bytes for the
- single-planar API. This is set by the driver based on the calls to
- &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets
- this to the number of elements in the <structfield>planes</structfield>
- array. The driver will fill in the actual number of valid elements in
- that array.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved2</structfield></entry>
- <entry></entry>
- <entry>A place holder for future extensions. Applications
-should set this to 0.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield></entry>
- <entry></entry>
- <entry>A place holder for future extensions. Applications
-should set this to 0.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-plane">
- <title>struct <structname>v4l2_plane</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>bytesused</structfield></entry>
- <entry></entry>
- <entry>The number of bytes occupied by data in the plane
- (its payload). Drivers must set this field when <structfield>type</structfield>
- refers to an input stream, applications when it refers to an output stream.
- If the application sets this to 0 for an output stream, then
- <structfield>bytesused</structfield> will be set to the size of the
- plane (see the <structfield>length</structfield> field of this struct)
- by the driver. Note that the actual image data starts at
- <structfield>data_offset</structfield> which may not be 0.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>length</structfield></entry>
- <entry></entry>
- <entry>Size in bytes of the plane (not its payload). This is set by the driver
- based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield>m</structfield></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>mem_offset</structfield></entry>
- <entry>When the memory type in the containing &v4l2-buffer; is
- <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
- should be passed to &func-mmap;, similar to the
- <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>unsigned long</entry>
- <entry><structfield>userptr</structfield></entry>
- <entry>When the memory type in the containing &v4l2-buffer; is
- <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
- pointer to the memory allocated for this plane by an application.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>int</entry>
- <entry><structfield>fd</structfield></entry>
- <entry>When the memory type in the containing &v4l2-buffer; is
- <constant>V4L2_MEMORY_DMABUF</constant>, this is a file
- descriptor associated with a DMABUF buffer, similar to the
- <structfield>fd</structfield> field in &v4l2-buffer;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>data_offset</structfield></entry>
- <entry></entry>
- <entry>Offset in bytes to video data in the plane.
- Drivers must set this field when <structfield>type</structfield>
- refers to an input stream, applications when it refers to an output stream.
- Note that data_offset is included in <structfield>bytesused</structfield>.
- So the size of the image in the plane is
- <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
- offset <structfield>data_offset</structfield> from the start of the plane.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved[11]</structfield></entry>
- <entry></entry>
- <entry>Reserved for future use. Should be zeroed by an
- application.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-buf-type">
- <title>enum v4l2_buf_type</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
- <entry>1</entry>
- <entry>Buffer of a single-planar video capture stream, see <xref
- linkend="capture" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
- </entry>
- <entry>9</entry>
- <entry>Buffer of a multi-planar video capture stream, see <xref
- linkend="capture" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
- <entry>2</entry>
- <entry>Buffer of a single-planar video output stream, see <xref
- linkend="output" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
- </entry>
- <entry>10</entry>
- <entry>Buffer of a multi-planar video output stream, see <xref
- linkend="output" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
- <entry>3</entry>
- <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
- <entry>4</entry>
- <entry>Buffer of a raw VBI capture stream, see <xref
- linkend="raw-vbi" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
- <entry>5</entry>
- <entry>Buffer of a raw VBI output stream, see <xref
- linkend="raw-vbi" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
- <entry>6</entry>
- <entry>Buffer of a sliced VBI capture stream, see <xref
- linkend="sliced" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
- <entry>7</entry>
- <entry>Buffer of a sliced VBI output stream, see <xref
- linkend="sliced" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
- <entry>8</entry>
- <entry>Buffer for video output overlay (OSD), see <xref
- linkend="osd" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry>
- <entry>11</entry>
- <entry>Buffer for Software Defined Radio (SDR), see <xref
- linkend="sdr" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="buffer-flags">
- <title>Buffer Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
- <entry>0x00000001</entry>
- <entry>The buffer resides in device memory and has been mapped
-into the application's address space, see <xref linkend="mmap" /> for details.
-Drivers set or clear this flag when the
-<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
- linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
- linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
- <entry>0x00000002</entry>
- <entry>Internally drivers maintain two buffer queues, an
-incoming and outgoing queue. When this flag is set, the buffer is
-currently on the incoming queue. It automatically moves to the
-outgoing queue after the buffer has been filled (capture devices) or
-displayed (output devices). Drivers set or clear this flag when the
-<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
-(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
-always set and after <constant>VIDIOC_DQBUF</constant> always
-cleared.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
- <entry>0x00000004</entry>
- <entry>When this flag is set, the buffer is currently on
-the outgoing queue, ready to be dequeued from the driver. Drivers set
-or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
-is called. After calling the <constant>VIDIOC_QBUF</constant> or
-<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
-buffer cannot be on both queues at the same time, the
-<constant>V4L2_BUF_FLAG_QUEUED</constant> and
-<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
-They can be both cleared however, then the buffer is in "dequeued"
-state, in the application domain so to say.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
- <entry>0x00000040</entry>
- <entry>When this flag is set, the buffer has been dequeued
- successfully, although the data might have been corrupted.
- This is recoverable, streaming may continue as normal and
- the buffer may be reused normally.
- Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
- ioctl is called.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
- <entry>0x00000008</entry>
- <entry>Drivers set or clear this flag when calling the
-<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
-capture devices when the buffer contains a compressed image which is a
-key frame (or field), &ie; can be decompressed on its own. Also known as
-an I-frame. Applications can set this bit when <structfield>type</structfield>
-refers to an output stream.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
- <entry>0x00000010</entry>
- <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
-this flags predicted frames or fields which contain only differences to a
-previous key frame. Applications can set this bit when <structfield>type</structfield>
-refers to an output stream.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
- <entry>0x00000020</entry>
- <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
-this flags a bi-directional predicted frame or field which contains only
-the differences between the current frame and both the preceding and following
-key frames to specify its content. Applications can set this bit when
-<structfield>type</structfield> refers to an output stream.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
- <entry>0x00000100</entry>
- <entry>The <structfield>timecode</structfield> field is valid.
-Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
-ioctl is called. Applications can set this bit and the corresponding
-<structfield>timecode</structfield> structure when <structfield>type</structfield>
-refers to an output stream.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
- <entry>0x00000400</entry>
- <entry>The buffer has been prepared for I/O and can be queued by the
-application. Drivers set or clear this flag when the
-<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
- linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link
- linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
- linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
- <entry>0x00000800</entry>
- <entry>Caches do not have to be invalidated for this buffer.
-Typically applications shall use this flag if the data captured in the buffer
-is not going to be touched by the CPU, instead the buffer will, probably, be
-passed on to a DMA-capable hardware unit for further processing or output.
-</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
- <entry>0x00001000</entry>
- <entry>Caches do not have to be cleaned for this buffer.
-Typically applications shall use this flag for output buffers if the data
-in this buffer has not been created by the CPU but by some DMA-capable unit,
-in which case caches have not been used.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
- <entry>0x0000e000</entry>
- <entry>Mask for timestamp types below. To test the
- timestamp type, mask out bits not belonging to timestamp
- type by performing a logical and operation with buffer
- flags and timestamp mask.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry>
- <entry>0x00000000</entry>
- <entry>Unknown timestamp type. This type is used by
- drivers before Linux 3.9 and may be either monotonic (see
- below) or realtime (wall clock). Monotonic clock has been
- favoured in embedded systems whereas most of the drivers
- use the realtime clock. Either kinds of timestamps are
- available in user space via
- <function>clock_gettime(2)</function> using clock IDs
- <constant>CLOCK_MONOTONIC</constant> and
- <constant>CLOCK_REALTIME</constant>, respectively.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry>
- <entry>0x00002000</entry>
- <entry>The buffer timestamp has been taken from the
- <constant>CLOCK_MONOTONIC</constant> clock. To access the
- same clock outside V4L2, use
- <function>clock_gettime(2)</function> .</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry>
- <entry>0x00004000</entry>
- <entry>The CAPTURE buffer timestamp has been taken from the
- corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry>
- <entry>0x00070000</entry>
- <entry>Mask for timestamp sources below. The timestamp source
- defines the point of time the timestamp is taken in relation to
- the frame. Logical 'and' operation between the
- <structfield>flags</structfield> field and
- <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the
- value of the timestamp source. Applications must set the timestamp
- source when <structfield>type</structfield> refers to an output stream
- and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>
- <entry>0x00000000</entry>
- <entry>End Of Frame. The buffer timestamp has been taken
- when the last pixel of the frame has been received or the
- last pixel of the frame has been transmitted. In practice,
- software generated timestamps will typically be read from
- the clock a small amount of time after the last pixel has
- been received or transmitten, depending on the system and
- other activity in it.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry>
- <entry>0x00010000</entry>
- <entry>Start Of Exposure. The buffer timestamp has been
- taken when the exposure of the frame has begun. This is
- only valid for the
- <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer
- type.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-memory">
- <title>enum v4l2_memory</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
- <entry>1</entry>
- <entry>The buffer is used for <link linkend="mmap">memory
-mapping</link> I/O.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
- <entry>2</entry>
- <entry>The buffer is used for <link linkend="userp">user
-pointer</link> I/O.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
- <entry>3</entry>
- <entry>[to do]</entry>
- </row>
- <row>
- <entry><constant>V4L2_MEMORY_DMABUF</constant></entry>
- <entry>4</entry>
- <entry>The buffer is used for <link linkend="dmabuf">DMA shared
-buffer</link> I/O.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section>
- <title>Timecodes</title>
-
- <para>The <structname>v4l2_timecode</structname> structure is
-designed to hold a <xref linkend="smpte12m" /> or similar timecode.
-(struct <structname>timeval</structname> timestamps are stored in
-&v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
-
- <table frame="none" pgwide="1" id="v4l2-timecode">
- <title>struct <structname>v4l2_timecode</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Frame rate the timecodes are based on, see <xref
- linkend="timecode-type" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>frames</structfield></entry>
- <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
- type of timecode.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>seconds</structfield></entry>
- <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>minutes</structfield></entry>
- <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>hours</structfield></entry>
- <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>userbits</structfield>[4]</entry>
- <entry>The "user group" bits from the timecode.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="timecode-type">
- <title>Timecode Types</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
- <entry>1</entry>
- <entry>24 frames per second, i.&nbsp;e. film.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
- <entry>2</entry>
- <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
- <entry>3</entry>
- <entry>30 frames per second, &ie; NTSC video.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
- <entry>4</entry>
- <entry></entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
- <entry>5</entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="timecode-flags">
- <title>Timecode Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
- <entry>0x0001</entry>
- <entry>Indicates "drop frame" semantics for counting frames
-in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
-each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
-count.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
- <entry>0x0002</entry>
- <entry>The "color frame" flag.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
- <entry>0x000C</entry>
- <entry>Field mask for the "binary group flags".</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
- <entry>0x0000</entry>
- <entry>Unspecified format.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
- <entry>0x0008</entry>
- <entry>8-bit ISO characters.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- <section id="field-order">
- <title>Field Order</title>
-
- <para>We have to distinguish between progressive and interlaced
-video. Progressive video transmits all lines of a video image
-sequentially. Interlaced video divides an image into two fields,
-containing only the odd and even lines of the image, respectively.
-Alternating the so called odd and even field are transmitted, and due
-to a small delay between fields a cathode ray TV displays the lines
-interleaved, yielding the original frame. This curious technique was
-invented because at refresh rates similar to film the image would
-fade out too quickly. Transmitting fields reduces the flicker without
-the necessity of doubling the frame rate and with it the bandwidth
-required for each channel.</para>
-
- <para>It is important to understand a video camera does not expose
-one frame at a time, merely transmitting the frames separated into
-fields. The fields are in fact captured at two different instances in
-time. An object on screen may well move between one field and the
-next. For applications analysing motion it is of paramount importance
-to recognize which field of a frame is older, the <emphasis>temporal
-order</emphasis>.</para>
-
- <para>When the driver provides or accepts images field by field
-rather than interleaved, it is also important applications understand
-how the fields combine to frames. We distinguish between top (aka odd) and
-bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
-of the top field is the first line of an interlaced frame, the first
-line of the bottom field is the second line of that frame.</para>
-
- <para>However because fields were captured one after the other,
-arguing whether a frame commences with the top or bottom field is
-pointless. Any two successive top and bottom, or bottom and top fields
-yield a valid frame. Only when the source was progressive to begin
-with, &eg; when transferring film to video, two fields may come from
-the same frame, creating a natural order.</para>
-
- <para>Counter to intuition the top field is not necessarily the
-older field. Whether the older field contains the top or bottom lines
-is a convention determined by the video standard. Hence the
-distinction between temporal and spatial order of fields. The diagrams
-below should make this clearer.</para>
-
- <para>All video capture and output devices must report the current
-field order. Some drivers may permit the selection of a different
-order, to this end applications initialize the
-<structfield>field</structfield> field of &v4l2-pix-format; before
-calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
-have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
-
- <table frame="none" pgwide="1" id="v4l2-field">
- <title>enum v4l2_field</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FIELD_ANY</constant></entry>
- <entry>0</entry>
- <entry>Applications request this field order when any
-one of the <constant>V4L2_FIELD_NONE</constant>,
-<constant>V4L2_FIELD_TOP</constant>,
-<constant>V4L2_FIELD_BOTTOM</constant>, or
-<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
-Drivers choose depending on hardware capabilities or e.&nbsp;g. the
-requested image size, and return the actual field order. Drivers must
-never return <constant>V4L2_FIELD_ANY</constant>. If multiple
-field orders are possible the driver must choose one of the possible
-field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer;
-<structfield>field</structfield> can never be
-<constant>V4L2_FIELD_ANY</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_NONE</constant></entry>
- <entry>1</entry>
- <entry>Images are in progressive format, not interlaced.
-The driver may also indicate this order when it cannot distinguish
-between <constant>V4L2_FIELD_TOP</constant> and
-<constant>V4L2_FIELD_BOTTOM</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_TOP</constant></entry>
- <entry>2</entry>
- <entry>Images consist of the top (aka odd) field only.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
- <entry>3</entry>
- <entry>Images consist of the bottom (aka even) field only.
-Applications may wish to prevent a device from capturing interlaced
-images because they will have "comb" or "feathering" artefacts around
-moving objects.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
- <entry>4</entry>
- <entry>Images contain both fields, interleaved line by
-line. The temporal order of the fields (whether the top or bottom
-field is first transmitted) depends on the current video standard.
-M/NTSC transmits the bottom field first, all other standards the top
-field first.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
- <entry>5</entry>
- <entry>Images contain both fields, the top field lines
-are stored first in memory, immediately followed by the bottom field
-lines. Fields are always stored in temporal order, the older one first
-in memory. Image sizes refer to the frame, not fields.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
- <entry>6</entry>
- <entry>Images contain both fields, the bottom field
-lines are stored first in memory, immediately followed by the top
-field lines. Fields are always stored in temporal order, the older one
-first in memory. Image sizes refer to the frame, not fields.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
- <entry>7</entry>
- <entry>The two fields of a frame are passed in separate
-buffers, in temporal order, &ie; the older one first. To indicate the field
-parity (whether the current field is a top or bottom field) the driver
-or application, depending on data direction, must set &v4l2-buffer;
-<structfield>field</structfield> to
-<constant>V4L2_FIELD_TOP</constant> or
-<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
-to build a frame. If fields are successive, without any dropped fields
-between them (fields can drop individually), can be determined from
-the &v4l2-buffer; <structfield>sequence</structfield> field. This format
-cannot be selected when using the read/write I/O method since there
-is no way to communicate if a field was a top or bottom field.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
- <entry>8</entry>
- <entry>Images contain both fields, interleaved line by
-line, top field first. The top field is transmitted first.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
- <entry>9</entry>
- <entry>Images contain both fields, interleaved line by
-line, top field first. The bottom field is transmitted first.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <figure id="fieldseq-tb">
- <title>Field Order, Top Field First Transmitted</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fieldseq_tb.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="fieldseq_tb.gif" format="GIF" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <figure id="fieldseq-bt">
- <title>Field Order, Bottom Field First Transmitted</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fieldseq_bt.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="fieldseq_bt.gif" format="GIF" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
diff --git a/Documentation/DocBook/media/v4l/keytable.c.xml b/Documentation/DocBook/media/v4l/keytable.c.xml
deleted file mode 100644
index d53254a3be15..000000000000
--- a/Documentation/DocBook/media/v4l/keytable.c.xml
+++ /dev/null
@@ -1,172 +0,0 @@
-<programlisting>
-/* keytable.c - This program allows checking/replacing keys at IR
-
- Copyright (C) 2006-2009 Mauro Carvalho Chehab &lt;mchehab@infradead.org&gt;
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation, version 2 of the License.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- */
-
-#include &lt;ctype.h&gt;
-#include &lt;errno.h&gt;
-#include &lt;fcntl.h&gt;
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-#include &lt;string.h&gt;
-#include &lt;linux/input.h&gt;
-#include &lt;sys/ioctl.h&gt;
-
-#include "parse.h"
-
-void prtcode (int *codes)
-{
- struct parse_key *p;
-
- for (p=keynames;p-&gt;name!=NULL;p++) {
- if (p-&gt;value == (unsigned)codes[1]) {
- printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p-&gt;name, codes[1]);
- return;
- }
- }
-
- if (isprint (codes[1]))
- printf("scancode %d = '%c' (0x%02x)\n", codes[0], codes[1], codes[1]);
- else
- printf("scancode %d = 0x%02x\n", codes[0], codes[1]);
-}
-
-int parse_code(char *string)
-{
- struct parse_key *p;
-
- for (p=keynames;p-&gt;name!=NULL;p++) {
- if (!strcasecmp(p-&gt;name, string)) {
- return p-&gt;value;
- }
- }
- return -1;
-}
-
-int main (int argc, char *argv[])
-{
- int fd;
- unsigned int i, j;
- int codes[2];
-
- if (argc&lt;2 || argc&gt;4) {
- printf ("usage: %s &lt;device&gt; to get table; or\n"
- " %s &lt;device&gt; &lt;scancode&gt; &lt;keycode&gt;\n"
- " %s &lt;device&gt; &lt;keycode_file&gt;\n",*argv,*argv,*argv);
- return -1;
- }
-
- if ((fd = open(argv[1], O_RDONLY)) &lt; 0) {
- perror("Couldn't open input device");
- return(-1);
- }
-
- if (argc==4) {
- int value;
-
- value=parse_code(argv[3]);
-
- if (value==-1) {
- value = strtol(argv[3], NULL, 0);
- if (errno)
- perror("value");
- }
-
- codes [0] = (unsigned) strtol(argv[2], NULL, 0);
- codes [1] = (unsigned) value;
-
- if(ioctl(fd, EVIOCSKEYCODE, codes))
- perror ("EVIOCSKEYCODE");
-
- if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
- prtcode(codes);
- return 0;
- }
-
- if (argc==3) {
- FILE *fin;
- int value;
- char *scancode, *keycode, s[2048];
-
- fin=fopen(argv[2],"r");
- if (fin==NULL) {
- perror ("opening keycode file");
- return -1;
- }
-
- /* Clears old table */
- for (j = 0; j &lt; 256; j++) {
- for (i = 0; i &lt; 256; i++) {
- codes[0] = (j &lt;&lt; 8) | i;
- codes[1] = KEY_RESERVED;
- ioctl(fd, EVIOCSKEYCODE, codes);
- }
- }
-
- while (fgets(s,sizeof(s),fin)) {
- scancode=strtok(s,"\n\t =:");
- if (!scancode) {
- perror ("parsing input file scancode");
- return -1;
- }
- if (!strcasecmp(scancode, "scancode")) {
- scancode = strtok(NULL,"\n\t =:");
- if (!scancode) {
- perror ("parsing input file scancode");
- return -1;
- }
- }
-
- keycode=strtok(NULL,"\n\t =:(");
- if (!keycode) {
- perror ("parsing input file keycode");
- return -1;
- }
-
- // printf ("parsing %s=%s:", scancode, keycode);
- value=parse_code(keycode);
- // printf ("\tvalue=%d\n",value);
-
- if (value==-1) {
- value = strtol(keycode, NULL, 0);
- if (errno)
- perror("value");
- }
-
- codes [0] = (unsigned) strtol(scancode, NULL, 0);
- codes [1] = (unsigned) value;
-
- // printf("\t%04x=%04x\n",codes[0], codes[1]);
- if(ioctl(fd, EVIOCSKEYCODE, codes)) {
- fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
- perror ("EVIOCSKEYCODE");
- }
-
- if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
- prtcode(codes);
- }
- return 0;
- }
-
- /* Get scancode table */
- for (j = 0; j &lt; 256; j++) {
- for (i = 0; i &lt; 256; i++) {
- codes[0] = (j &lt;&lt; 8) | i;
- if (!ioctl(fd, EVIOCGKEYCODE, codes) &amp;&amp; codes[1] != KEY_RESERVED)
- prtcode(codes);
- }
- }
- return 0;
-}
-
-</programlisting>
diff --git a/Documentation/DocBook/media/v4l/libv4l.xml b/Documentation/DocBook/media/v4l/libv4l.xml
deleted file mode 100644
index d3b71e20003c..000000000000
--- a/Documentation/DocBook/media/v4l/libv4l.xml
+++ /dev/null
@@ -1,160 +0,0 @@
-<title>Libv4l Userspace Library</title>
-<section id="libv4l-introduction">
- <title>Introduction</title>
-
- <para>libv4l is a collection of libraries which adds a thin abstraction
-layer on top of video4linux2 devices. The purpose of this (thin) layer
-is to make it easy for application writers to support a wide variety of
-devices without having to write separate code for different devices in the
-same class.</para>
-<para>An example of using libv4l is provided by
-<link linkend='v4l2grab-example'>v4l2grab</link>.
-</para>
-
- <para>libv4l consists of 3 different libraries:</para>
- <section>
- <title>libv4lconvert</title>
-
- <para>libv4lconvert is a library that converts several
-different pixelformats found in V4L2 drivers into a few common RGB and
-YUY formats.</para>
- <para>It currently accepts the following V4L2 driver formats:
-<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>,
-<link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>,
-<link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>,
-<link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>,
-<link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>,
-<link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>,
-<link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>,
-<link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>,
-<link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>,
-<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>,
-<link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>,
-<link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>,
-<link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>,
-<link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>,
-<link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>,
-<link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>,
-<link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>,
-<link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>,
-<link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>,
-<link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>,
-<constant>V4L2_PIX_FMT_SRGGB8</constant>,
-<link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>,
-<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>,
-<link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>,
-<link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
-and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>.
-</para>
- <para>Later on libv4lconvert was expanded to also be able to do
-various video processing functions to improve webcam video quality.
-The video processing is split in to 2 parts: libv4lconvert/control and
-libv4lconvert/processing.</para>
-
- <para>The control part is used to offer video controls which can
-be used to control the video processing functions made available by
- libv4lconvert/processing. These controls are stored application wide
-(until reboot) by using a persistent shared memory object.</para>
-
- <para>libv4lconvert/processing offers the actual video
-processing functionality.</para>
- </section>
- <section>
- <title>libv4l1</title>
- <para>This library offers functions that can be used to quickly
-make v4l1 applications work with v4l2 devices. These functions work exactly
-like the normal open/close/etc, except that libv4l1 does full emulation of
-the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it
-will just pass calls through.</para>
- <para>Since those functions are emulations of the old V4L1 API,
-it shouldn't be used for new applications.</para>
- </section>
- <section>
- <title>libv4l2</title>
- <para>This library should be used for all modern V4L2
-applications.</para>
- <para>It provides handles to call V4L2 open/ioctl/close/poll
-methods. Instead of just providing the raw output of the device, it enhances
-the calls in the sense that it will use libv4lconvert to provide more video
-formats and to enhance the image quality.</para>
- <para>In most cases, libv4l2 just passes the calls directly
-through to the v4l2 driver, intercepting the calls to
-<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>,
-<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>
-<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>
-<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>
-and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>
-in order to emulate the formats
-<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>,
-<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>,
-<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>,
-and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
-if they aren't available in the driver.
-<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>
-keeps enumerating the hardware supported formats, plus the emulated formats
-offered by libv4l at the end.
-</para>
- <section id="libv4l-ops">
- <title>Libv4l device control functions</title>
- <para>The common file operation methods are provided by
-libv4l.</para>
- <para>Those functions operate just like glibc
-open/close/dup/ioctl/read/mmap/munmap:</para>
-<itemizedlist><listitem>
- <para>int v4l2_open(const char *file, int oflag,
-...) -
-operates like the standard <link linkend='func-open'>open()</link> function.
-</para></listitem><listitem>
- <para>int v4l2_close(int fd) -
-operates like the standard <link linkend='func-close'>close()</link> function.
-</para></listitem><listitem>
- <para>int v4l2_dup(int fd) -
-operates like the standard dup() function, duplicating a file handler.
-</para></listitem><listitem>
- <para>int v4l2_ioctl (int fd, unsigned long int request, ...) -
-operates like the standard <link linkend='func-ioctl'>ioctl()</link> function.
-</para></listitem><listitem>
- <para>int v4l2_read (int fd, void* buffer, size_t n) -
-operates like the standard <link linkend='func-read'>read()</link> function.
-</para></listitem><listitem>
- <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); -
-operates like the standard <link linkend='func-mmap'>mmap()</link> function.
-</para></listitem><listitem>
- <para>int v4l2_munmap(void *_start, size_t length); -
-operates like the standard <link linkend='func-munmap'>munmap()</link> function.
-</para></listitem>
-</itemizedlist>
- <para>Those functions provide additional control:</para>
-<itemizedlist><listitem>
- <para>int v4l2_fd_open(int fd, int v4l2_flags) -
-opens an already opened fd for further use through v4l2lib and possibly
-modify libv4l2's default behavior through the v4l2_flags argument.
-Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>,
-to disable format conversion.
-</para></listitem><listitem>
- <para>int v4l2_set_control(int fd, int cid, int value) -
-This function takes a value of 0 - 65535, and then scales that range to
-the actual range of the given v4l control id, and then if the cid exists
-and is not locked sets the cid to the scaled value.
-</para></listitem><listitem>
- <para>int v4l2_get_control(int fd, int cid) -
-This function returns a value of 0 - 65535, scaled to from the actual range
-of the given v4l control id. when the cid does not exist, could not be
-accessed for some reason, or some error occurred 0 is returned.
-</para></listitem>
-</itemizedlist>
- </section>
- </section>
- <section>
-
- <title>v4l1compat.so wrapper library</title>
-
- <para>This library intercepts calls to
-open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l
-counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also
-emulates V4L1 calls via V4L2 API.</para>
- <para>It allows usage of binary legacy applications that
-still don't use libv4l.</para>
- </section>
-
-</section>
diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml
deleted file mode 100644
index 34cada2ca710..000000000000
--- a/Documentation/DocBook/media/v4l/lirc_device_interface.xml
+++ /dev/null
@@ -1,255 +0,0 @@
-<section id="lirc_dev">
-<title>LIRC Device Interface</title>
-
-
-<section id="lirc_dev_intro">
-<title>Introduction</title>
-
-<para>The LIRC device interface is a bi-directional interface for
-transporting raw IR data between userspace and kernelspace. Fundamentally,
-it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number
-of standard struct file_operations defined on it. With respect to
-transporting raw IR data to and fro, the essential fops are read, write
-and ioctl.</para>
-
-<para>Example dmesg output upon a driver registering w/LIRC:</para>
- <blockquote>
- <para>$ dmesg |grep lirc_dev</para>
- <para>lirc_dev: IR Remote Control driver registered, major 248</para>
- <para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para>
- </blockquote>
-
-<para>What you should see for a chardev:</para>
- <blockquote>
- <para>$ ls -l /dev/lirc*</para>
- <para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para>
- </blockquote>
-</section>
-
-<section id="lirc_read">
-<title>LIRC read fop</title>
-
-<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The
-exact format of the data depends on what modes a driver supports, and what
-mode has been selected. lircd obtains supported modes and sets the active mode
-via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally
-preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
-describing an IR signal are read from the chardev.</para>
-
-<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para>
-</section>
-
-<section id="lirc_write">
-<title>LIRC write fop</title>
-
-<para>The data written to the chardev is a pulse/space sequence of integer
-values. Pulses and spaces are only marked implicitly by their position. The
-data must start and end with a pulse, therefore, the data must always include
-an uneven number of samples. The write function must block until the data has
-been transmitted by the hardware. If more data is provided than the hardware
-can send, the driver returns EINVAL.</para>
-
-</section>
-
-<section id="lirc_ioctl">
-<title>LIRC ioctl fop</title>
-
-<para>The LIRC device's ioctl definition is bound by the ioctl function
-definition of struct file_operations, leaving us with an unsigned int
-for the ioctl command and an unsigned long for the arg. For the purposes
-of ioctl portability across 32-bit and 64-bit, these values are capped
-to their 32-bit sizes.</para>
-
-<para>The following ioctls can be used to change specific hardware settings.
-In general each driver should have a default set of settings. The driver
-implementation is expected to re-apply the default settings when the device
-is closed by user-space, so that every application opening the device can rely
-on working with the default settings initially.</para>
-
-<variablelist>
- <varlistentry>
- <term>LIRC_GET_FEATURES</term>
- <listitem>
- <para>Obviously, get the underlying hardware device's features. If a driver
- does not announce support of certain features, calling of the corresponding
- ioctls is undefined.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_SEND_MODE</term>
- <listitem>
- <para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_REC_MODE</term>
- <listitem>
- <para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE
- are supported by lircd.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_SEND_CARRIER</term>
- <listitem>
- <para>Get carrier frequency (in Hz) currently used for transmit.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_REC_CARRIER</term>
- <listitem>
- <para>Get carrier frequency (in Hz) currently used for IR reception.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term>
- <listitem>
- <para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently,
- no special meaning is defined for 0 or 100, but this could be used to switch
- off carrier generation in the future, so these values should be reserved.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_REC_RESOLUTION</term>
- <listitem>
- <para>Some receiver have maximum resolution which is defined by internal
- sample rate or data format limitations. E.g. it's common that signals can
- only be reported in 50 microsecond steps. This integer value is used by
- lircd to automatically adjust the aeps tolerance value in the lircd
- config file.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_M{IN,AX}_TIMEOUT</term>
- <listitem>
- <para>Some devices have internal timers that can be used to detect when
- there's no IR activity for a long time. This can help lircd in detecting
- that a IR signal is finished and can speed up the decoding process.
- Returns an integer value with the minimum/maximum timeout that can be
- set. Some devices have a fixed timeout, in that case both ioctls will
- return the same value even though the timeout cannot be changed.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term>
- <listitem>
- <para>Some devices are able to filter out spikes in the incoming signal
- using given filter rules. These ioctls return the hardware capabilities
- that describe the bounds of the possible filters. Filter settings depend
- on the IR protocols that are expected. lircd derives the settings from
- all protocols definitions found in its config file.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_GET_LENGTH</term>
- <listitem>
- <para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
- Reads on the device must be done in blocks matching the bit count.
- The bit could should be rounded up so that it matches full bytes.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_{SEND,REC}_MODE</term>
- <listitem>
- <para>Set send/receive mode. Largely obsolete for send, as only
- LIRC_MODE_PULSE is supported.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_{SEND,REC}_CARRIER</term>
- <listitem>
- <para>Set send/receive carrier (in Hz).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_TRANSMITTER_MASK</term>
- <listitem>
- <para>This enables the given set of transmitters. The first transmitter
- is encoded by the least significant bit, etc. When an invalid bit mask
- is given, i.e. a bit is set, even though the device does not have so many
- transitters, then this ioctl returns the number of available transitters
- and does nothing otherwise.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_REC_TIMEOUT</term>
- <listitem>
- <para>Sets the integer value for IR inactivity timeout (cf.
- LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if
- supported by the hardware) disables all hardware timeouts and data should
- be reported as soon as possible. If the exact value cannot be set, then
- the next possible value _greater_ than the given value should be set.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_REC_TIMEOUT_REPORTS</term>
- <listitem>
- <para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
- default, timeout reports should be turned off.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term>
- <listitem>
- <para>Pulses/spaces shorter than this are filtered out by hardware. If
- filters cannot be set independently for pulse/space, the corresponding
- ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_MEASURE_CARRIER_MODE</term>
- <listitem>
- <para>Enable (1)/disable (0) measure mode. If enabled, from the next key
- press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default
- this should be turned off.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term>
- <listitem>
- <para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
- with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER
- with the upper bound.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_NOTIFY_DECODE</term>
- <listitem>
- <para>This ioctl is called by lircd whenever a successful decoding of an
- incoming IR signal could be done. This can be used by supporting hardware
- to give visual feedback to the user e.g. by flashing a LED.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SETUP_{START,END}</term>
- <listitem>
- <para>Setting of several driver parameters can be optimized by encapsulating
- the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a
- driver receives a LIRC_SETUP_START ioctl it can choose to not commit
- further setting changes to the hardware until a LIRC_SETUP_END is received.
- But this is open to the driver implementation and every driver must also
- handle parameter changes which are not encapsulated by LIRC_SETUP_START
- and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>LIRC_SET_WIDEBAND_RECEIVER</term>
- <listitem>
- <para>Some receivers are equipped with special wide band receiver which is intended
- to be used to learn output of existing remote.
- Calling that ioctl with (1) will enable it, and with (0) disable it.
- This might be useful of receivers that have otherwise narrow band receiver
- that prevents them to be used with some remotes.
- Wide band receiver might also be more precise
- On the other hand its disadvantage it usually reduced range of reception.
- Note: wide band receiver might be implictly enabled if you enable
- carrier reports. In that case it will be disabled as soon as you disable
- carrier reports. Trying to disable wide band receiver while carrier
- reports are active will do nothing.</para>
- </listitem>
- </varlistentry>
-</variablelist>
-<section id="lirc_dev_errors">
- &return-value;
-</section>
-</section>
-</section>
diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml
deleted file mode 100644
index 873ac3a621f0..000000000000
--- a/Documentation/DocBook/media/v4l/media-controller.xml
+++ /dev/null
@@ -1,89 +0,0 @@
-<partinfo>
- <authorgroup>
- <author>
- <firstname>Laurent</firstname>
- <surname>Pinchart</surname>
- <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation>
- <contrib>Initial version.</contrib>
- </author>
- </authorgroup>
- <copyright>
- <year>2010</year>
- <holder>Laurent Pinchart</holder>
- </copyright>
-
- <revhistory>
- <!-- Put document revisions here, newest first. -->
- <revision>
- <revnumber>1.0.0</revnumber>
- <date>2010-11-10</date>
- <authorinitials>lp</authorinitials>
- <revremark>Initial revision</revremark>
- </revision>
- </revhistory>
-</partinfo>
-
-<title>Media Controller API</title>
-
-<chapter id="media_controller">
- <title>Media Controller</title>
-
- <section id="media-controller-intro">
- <title>Introduction</title>
- <para>Media devices increasingly handle multiple related functions. Many USB
- cameras include microphones, video capture hardware can also output video,
- or SoC camera interfaces also perform memory-to-memory operations similar to
- video codecs.</para>
- <para>Independent functions, even when implemented in the same hardware, can
- be modelled as separate devices. A USB camera with a microphone will be
- presented to userspace applications as V4L2 and ALSA capture devices. The
- devices' relationships (when using a webcam, end-users shouldn't have to
- manually select the associated USB microphone), while not made available
- directly to applications by the drivers, can usually be retrieved from
- sysfs.</para>
- <para>With more and more advanced SoC devices being introduced, the current
- approach will not scale. Device topologies are getting increasingly complex
- and can't always be represented by a tree structure. Hardware blocks are
- shared between different functions, creating dependencies between seemingly
- unrelated devices.</para>
- <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for
- applications to access hardware parameters. As newer hardware expose an
- increasingly high number of those parameters, drivers need to guess what
- applications really require based on limited information, thereby
- implementing policies that belong to userspace.</para>
- <para>The media controller API aims at solving those problems.</para>
- </section>
-
- <section id="media-controller-model">
- <title>Media device model</title>
- <para>Discovering a device internal topology, and configuring it at runtime,
- is one of the goals of the media controller API. To achieve this, hardware
- devices are modelled as an oriented graph of building blocks called entities
- connected through pads.</para>
- <para>An entity is a basic media hardware or software building block. It can
- correspond to a large variety of logical blocks such as physical hardware
- devices (CMOS sensor for instance), logical hardware devices (a building
- block in a System-on-Chip image processing pipeline), DMA channels or
- physical connectors.</para>
- <para>A pad is a connection endpoint through which an entity can interact
- with other entities. Data (not restricted to video) produced by an entity
- flows from the entity's output to one or more entity inputs. Pads should not
- be confused with physical pins at chip boundaries.</para>
- <para>A link is a point-to-point oriented connection between two pads,
- either on the same entity or on different entities. Data flows from a source
- pad to a sink pad.</para>
- </section>
-</chapter>
-
-<appendix id="media-user-func">
- <title>Function Reference</title>
- <!-- Keep this alphabetically sorted. -->
- &sub-media-func-open;
- &sub-media-func-close;
- &sub-media-func-ioctl;
- <!-- All ioctls go here. -->
- &sub-media-ioc-device-info;
- &sub-media-ioc-enum-entities;
- &sub-media-ioc-enum-links;
- &sub-media-ioc-setup-link;
-</appendix>
diff --git a/Documentation/DocBook/media/v4l/media-func-close.xml b/Documentation/DocBook/media/v4l/media-func-close.xml
deleted file mode 100644
index be149c802aeb..000000000000
--- a/Documentation/DocBook/media/v4l/media-func-close.xml
+++ /dev/null
@@ -1,59 +0,0 @@
-<refentry id="media-func-close">
- <refmeta>
- <refentrytitle>media close()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>media-close</refname>
- <refpurpose>Close a media device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>close</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Closes the media device. Resources associated with the file descriptor
- are freed. The device configuration remain unchanged.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para><function>close</function> returns 0 on success. On error, -1 is
- returned, and <varname>errno</varname> is set appropriately. Possible error
- codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid open file descriptor.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-func-ioctl.xml b/Documentation/DocBook/media/v4l/media-func-ioctl.xml
deleted file mode 100644
index 39478d0fbcaa..000000000000
--- a/Documentation/DocBook/media/v4l/media-func-ioctl.xml
+++ /dev/null
@@ -1,73 +0,0 @@
-<refentry id="media-func-ioctl">
- <refmeta>
- <refentrytitle>media ioctl()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>media-ioctl</refname>
- <refpurpose>Control a media device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>void *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>Media ioctl request code as defined in the media.h header file,
- for example MEDIA_IOC_SETUP_LINK.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para>Pointer to a request-specific structure.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
- <para>The <function>ioctl()</function> function manipulates media device
- parameters. The argument <parameter>fd</parameter> must be an open file
- descriptor.</para>
- <para>The ioctl <parameter>request</parameter> code specifies the media
- function to be called. It has encoded in it whether the argument is an
- input, output or read/write parameter, and the size of the argument
- <parameter>argp</parameter> in bytes.</para>
- <para>Macros and structures definitions specifying media ioctl requests and
- their parameters are located in the media.h header file. All media ioctl
- requests, their respective function and parameters are specified in
- <xref linkend="media-user-func" />.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <para>Request-specific error codes are listed in the
- individual requests descriptions.</para>
- <para>When an ioctl that takes an output or read/write parameter fails,
- the parameter remains unmodified.</para>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-func-open.xml b/Documentation/DocBook/media/v4l/media-func-open.xml
deleted file mode 100644
index f7df034dc9ed..000000000000
--- a/Documentation/DocBook/media/v4l/media-func-open.xml
+++ /dev/null
@@ -1,94 +0,0 @@
-<refentry id="media-func-open">
- <refmeta>
- <refentrytitle>media open()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>media-open</refname>
- <refpurpose>Open a media device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>open</function></funcdef>
- <paramdef>const char *<parameter>device_name</parameter></paramdef>
- <paramdef>int <parameter>flags</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>device_name</parameter></term>
- <listitem>
- <para>Device to be opened.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>Open flags. Access mode must be either <constant>O_RDONLY</constant>
- or <constant>O_RDWR</constant>. Other flags have no effect.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>To open a media device applications call <function>open()</function>
- with the desired device name. The function has no side effects; the device
- configuration remain unchanged.</para>
- <para>When the device is opened in read-only mode, attemps to modify its
- configuration will result in an error, and <varname>errno</varname> will be
- set to <errorcode>EBADF</errorcode>.</para>
- </refsect1>
- <refsect1>
- <title>Return Value</title>
-
- <para><function>open</function> returns the new file descriptor on success.
- On error, -1 is returned, and <varname>errno</varname> is set appropriately.
- Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para>The requested access to the file is not allowed.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EMFILE</errorcode></term>
- <listitem>
- <para>The process already has the maximum number of files open.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENFILE</errorcode></term>
- <listitem>
- <para>The system limit on the total number of open files has been
- reached.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOMEM</errorcode></term>
- <listitem>
- <para>Insufficient kernel memory was available.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENXIO</errorcode></term>
- <listitem>
- <para>No device corresponding to this device special file exists.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-device-info.xml b/Documentation/DocBook/media/v4l/media-ioc-device-info.xml
deleted file mode 100644
index 2ce521419e67..000000000000
--- a/Documentation/DocBook/media/v4l/media-ioc-device-info.xml
+++ /dev/null
@@ -1,132 +0,0 @@
-<refentry id="media-ioc-device-info">
- <refmeta>
- <refentrytitle>ioctl MEDIA_IOC_DEVICE_INFO</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>MEDIA_IOC_DEVICE_INFO</refname>
- <refpurpose>Query device information</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct media_device_info *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>File descriptor returned by
- <link linkend='media-func-open'><function>open()</function></link>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>MEDIA_IOC_DEVICE_INFO</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant>
- ioctl. To query device information, applications call the ioctl with a
- pointer to a &media-device-info;. The driver fills the structure and returns
- the information to the application.
- The ioctl never fails.</para>
-
- <table pgwide="1" frame="none" id="media-device-info">
- <title>struct <structname>media_device_info</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>char</entry>
- <entry><structfield>driver</structfield>[16]</entry>
- <entry><para>Name of the driver implementing the media API as a
- NUL-terminated ASCII string. The driver version is stored in the
- <structfield>driver_version</structfield> field.</para>
- <para>Driver specific applications can use this information to
- verify the driver identity. It is also useful to work around
- known bugs, or to identify drivers in error reports.</para></entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>model</structfield>[32]</entry>
- <entry>Device model name as a NUL-terminated UTF-8 string. The
- device version is stored in the <structfield>device_version</structfield>
- field and is not be appended to the model name.</entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>serial</structfield>[40]</entry>
- <entry>Serial number as a NUL-terminated ASCII string.</entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>bus_info</structfield>[32]</entry>
- <entry>Location of the device in the system as a NUL-terminated
- ASCII string. This includes the bus type name (PCI, USB, ...) and a
- bus-specific identifier.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>media_version</structfield></entry>
- <entry>Media API version, formatted with the
- <constant>KERNEL_VERSION()</constant> macro.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>hw_revision</structfield></entry>
- <entry>Hardware device revision in a driver-specific format.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>media_version</structfield></entry>
- <entry>Media device driver version, formatted with the
- <constant>KERNEL_VERSION()</constant> macro. Together with the
- <structfield>driver</structfield> field this identifies a particular
- driver.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[31]</entry>
- <entry>Reserved for future extensions. Drivers and applications must
- set this array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The <structfield>serial</structfield> and <structfield>bus_info</structfield>
- fields can be used to distinguish between multiple instances of otherwise
- identical hardware. The serial number takes precedence when provided and can
- be assumed to be unique. If the serial number is an empty string, the
- <structfield>bus_info</structfield> field can be used instead. The
- <structfield>bus_info</structfield> field is guaranteed to be unique, but
- can vary across reboots or device unplug/replug.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
deleted file mode 100644
index 5872f8bbf774..000000000000
--- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
+++ /dev/null
@@ -1,280 +0,0 @@
-<refentry id="media-ioc-enum-entities">
- <refmeta>
- <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
- <refpurpose>Enumerate entities and their properties</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>File descriptor returned by
- <link linkend='media-func-open'><function>open()</function></link>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>MEDIA_IOC_ENUM_ENTITIES</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
- <para>To query the attributes of an entity, applications set the id field
- of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
- ioctl with a pointer to this structure. The driver fills the rest of the
- structure or returns an &EINVAL; when the id is invalid.</para>
- <para>Entities can be enumerated by or'ing the id with the
- <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
- information about the entity with the smallest id strictly larger than the
- requested one ('next entity'), or the &EINVAL; if there is none.</para>
- <para>Entity IDs can be non-contiguous. Applications must
- <emphasis>not</emphasis> try to enumerate entities by calling
- MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
- <para>Two or more entities that share a common non-zero
- <structfield>group_id</structfield> value are considered as logically
- grouped. Groups are used to report
- <itemizedlist>
- <listitem><para>ALSA, VBI and video nodes that carry the same media
- stream</para></listitem>
- <listitem><para>lens and flash controllers associated with a sensor</para></listitem>
- </itemizedlist>
- </para>
-
- <table pgwide="1" frame="none" id="media-entity-desc">
- <title>struct <structname>media_entity_desc</structname></title>
- <tgroup cols="5">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <colspec colname="c5" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Entity id, set by the application. When the id is or'ed with
- <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
- flag and returns the first entity with a larger id.</entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry></entry>
- <entry></entry>
- <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>revision</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Entity revision in a driver/hardware specific format.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>group_id</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Entity group ID</entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>pads</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Number of pads</entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>links</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Total number of outbound links. Inbound links are not counted
- in this field.</entry>
- </row>
- <row>
- <entry>union</entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct</entry>
- <entry><structfield>dev</structfield></entry>
- <entry></entry>
- <entry>Valid for (sub-)devices that create a single device node.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>major</structfield></entry>
- <entry>Device node major number.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>minor</structfield></entry>
- <entry>Device node minor number.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u8</entry>
- <entry><structfield>raw</structfield>[184]</entry>
- <entry></entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="media-entity-type">
- <title>Media entity types</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry>
- <entry>Unknown device node</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry>
- <entry>V4L video, radio or vbi device node</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry>
- <entry>Frame buffer device node</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry>
- <entry>ALSA card</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_FE</constant></entry>
- <entry>DVB frontend devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_DEMUX</constant></entry>
- <entry>DVB demux devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_DVR</constant></entry>
- <entry>DVB DVR devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_CA</constant></entry>
- <entry>DVB CAM devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_NET</constant></entry>
- <entry>DVB network devnode</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry>
- <entry>Unknown V4L sub-device</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry>
- <entry>Video sensor</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry>
- <entry>Flash controller</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry>
- <entry>Lens controller</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_DECODER</constant></entry>
- <entry>Video decoder, the basic function of the video decoder is to
- accept analogue video from a wide variety of sources such as
- broadcast, DVD players, cameras and video cassette recorders, in
- either NTSC, PAL or HD format and still occasionally SECAM, separate
- it into its component parts, luminance and chrominance, and output
- it in some digital video standard, with appropriate embedded timing
- signals.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_TUNER</constant></entry>
- <entry>TV and/or radio tuner</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="media-entity-flag">
- <title>Media entity flags</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
- <entry>Default entity for its type. Used to discover the default
- audio, VBI and video devices, the default camera sensor, ...</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &media-entity-desc; <structfield>id</structfield> references
- a non-existing entity.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
deleted file mode 100644
index 74fb394ec667..000000000000
--- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
+++ /dev/null
@@ -1,216 +0,0 @@
-<refentry id="media-ioc-enum-links">
- <refmeta>
- <refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>MEDIA_IOC_ENUM_LINKS</refname>
- <refpurpose>Enumerate all pads and links for a given entity</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct media_links_enum *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>File descriptor returned by
- <link linkend='media-func-open'><function>open()</function></link>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>MEDIA_IOC_ENUM_LINKS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To enumerate pads and/or links for a given entity, applications set
- the entity field of a &media-links-enum; structure and initialize the
- &media-pad-desc; and &media-link-desc; structure arrays pointed by the
- <structfield>pads</structfield> and <structfield>links</structfield> fields.
- They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this
- structure.</para>
- <para>If the <structfield>pads</structfield> field is not NULL, the driver
- fills the <structfield>pads</structfield> array with information about the
- entity's pads. The array must have enough room to store all the entity's
- pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES;
- ioctl.</para>
- <para>If the <structfield>links</structfield> field is not NULL, the driver
- fills the <structfield>links</structfield> array with information about the
- entity's outbound links. The array must have enough room to store all the
- entity's outbound links. The number of outbound links can be retrieved with
- the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para>
- <para>Only forward links that originate at one of the entity's source pads
- are returned during the enumeration process.</para>
-
- <table pgwide="1" frame="none" id="media-links-enum">
- <title>struct <structname>media_links_enum</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>entity</structfield></entry>
- <entry>Entity id, set by the application.</entry>
- </row>
- <row>
- <entry>&media-pad-desc;</entry>
- <entry>*<structfield>pads</structfield></entry>
- <entry>Pointer to a pads array allocated by the application. Ignored
- if NULL.</entry>
- </row>
- <row>
- <entry>&media-link-desc;</entry>
- <entry>*<structfield>links</structfield></entry>
- <entry>Pointer to a links array allocated by the application. Ignored
- if NULL.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="media-pad-desc">
- <title>struct <structname>media_pad_desc</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>entity</structfield></entry>
- <entry>ID of the entity this pad belongs to.</entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>index</structfield></entry>
- <entry>0-based pad index.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="media-pad-flag">
- <title>Media pad flags</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_PAD_FL_SINK</constant></entry>
- <entry>Input pad, relative to the entity. Input pads sink data and
- are targets of links.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>
- <entry>Output pad, relative to the entity. Output pads source data
- and are origins of links.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_PAD_FL_MUST_CONNECT</constant></entry>
- <entry>If this flag is set and the pad is linked to any other
- pad, then at least one of those links must be enabled for the
- entity to be able to stream. There could be temporary reasons
- (e.g. device configuration dependent) for the pad to need
- enabled links even when this flag isn't set; the absence of the
- flag doesn't imply there is none.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="media-link-desc">
- <title>struct <structname>media_link_desc</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>&media-pad-desc;</entry>
- <entry><structfield>source</structfield></entry>
- <entry>Pad at the origin of this link.</entry>
- </row>
- <row>
- <entry>&media-pad-desc;</entry>
- <entry><structfield>sink</structfield></entry>
- <entry>Pad at the target of this link.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="media-link-flag">
- <title>Media link flags</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <tbody valign="top">
- <row>
- <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>
- <entry>The link is enabled and can be used to transfer media data.
- When two or more links target a sink pad, only one of them can be
- enabled at a time.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>
- <entry>The link enabled state can't be modified at runtime. An
- immutable link is always enabled.</entry>
- </row>
- <row>
- <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry>
- <entry>The link enabled state can be modified during streaming. This
- flag is set by drivers and is read-only for applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and
- <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &media-links-enum; <structfield>id</structfield> references
- a non-existing entity.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml b/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml
deleted file mode 100644
index fc2e522ee65a..000000000000
--- a/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml
+++ /dev/null
@@ -1,84 +0,0 @@
-<refentry id="media-ioc-setup-link">
- <refmeta>
- <refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>MEDIA_IOC_SETUP_LINK</refname>
- <refpurpose>Modify the properties of a link</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>File descriptor returned by
- <link linkend='media-func-open'><function>open()</function></link>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>MEDIA_IOC_SETUP_LINK</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To change link properties applications fill a &media-link-desc; with
- link identification information (source and sink pad) and the new requested
- link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to
- that structure.</para>
- <para>The only configurable property is the <constant>ENABLED</constant>
- link flag to enable/disable a link. Links marked with the
- <constant>IMMUTABLE</constant> link flag can not be enabled or disabled.
- </para>
- <para>Link configuration has no side effect on other links. If an enabled
- link at the sink pad prevents the link from being enabled, the driver
- returns with an &EBUSY;.</para>
- <para>Only links marked with the <constant>DYNAMIC</constant> link flag can
- be enabled/disabled while streaming media data. Attempting to enable or
- disable a streaming non-dynamic link will return an &EBUSY;.</para>
- <para>If the specified link can't be found the driver returns with an
- &EINVAL;.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &media-link-desc; references a non-existing link, or the
- link is immutable and an attempt to modify its configuration was made.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pipeline.pdf b/Documentation/DocBook/media/v4l/pipeline.pdf
deleted file mode 100644
index ee3e37f04b6a..000000000000
--- a/Documentation/DocBook/media/v4l/pipeline.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/pixfmt-grey.xml b/Documentation/DocBook/media/v4l/pixfmt-grey.xml
deleted file mode 100644
index bee970d3f76d..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-grey.xml
+++ /dev/null
@@ -1,62 +0,0 @@
- <refentry id="V4L2-PIX-FMT-GREY">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_GREY ('GREY')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_GREY</constant></refname>
- <refpurpose>Grey-scale image</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a grey-scale image. It is really a degenerate
-Y'CbCr format which simply contains no Cb or Cr data.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_GREY</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-m420.xml b/Documentation/DocBook/media/v4l/pixfmt-m420.xml
deleted file mode 100644
index aadae92c5d04..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-m420.xml
+++ /dev/null
@@ -1,139 +0,0 @@
- <refentry id="V4L2-PIX-FMT-M420">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_M420 ('M420')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_M420</constant></refname>
- <refpurpose>Format with &frac12; horizontal and vertical chroma
- resolution, also known as YUV 4:2:0. Hybrid plane line-interleaved
- layout.</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>M420 is a YUV format with &frac12; horizontal and vertical chroma
- subsampling (YUV 4:2:0). Pixels are organized as interleaved luma and
- chroma planes. Two lines of luma data are followed by one line of chroma
- data.</para>
- <para>The luma plane has one byte per pixel. The chroma plane contains
- interleaved CbCr pixels subsampled by &frac12; in the horizontal and
- vertical directions. Each CbCr pair belongs to four pixels. For example,
-Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
-Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
-Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.</para>
-
- <para>All line lengths are identical: if the Y lines include pad bytes
- so do the CbCr lines.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_M420</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;20:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml
deleted file mode 100644
index 84dd4fd7cb80..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml
+++ /dev/null
@@ -1,143 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-NV12"><constant>V4L2_PIX_FMT_NV12</constant></refname>
- <refname id="V4L2-PIX-FMT-NV21"><constant>V4L2_PIX_FMT_NV21</constant></refname>
- <refpurpose>Formats with &frac12; horizontal and vertical
-chroma resolution, also known as YUV 4:2:0. One luminance and one
-chrominance plane with alternating chroma samples as opposed to
-<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These are two-plane versions of the YUV 4:2:0 format.
-The three components are separated into two sub-images or planes. The
-Y plane is first. The Y plane has one byte per pixel. For
-<constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane
-immediately follows the Y plane in memory. The CbCr plane is the same
-width, in bytes, as the Y plane (and of the image), but is half as
-tall in pixels. Each CbCr pair belongs to four pixels. For example,
-Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
-Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
-Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.
-<constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and
-Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
-
- <para>If the Y plane has pad bytes after each row, then the
-CbCr plane has as many pad bytes after its rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_NV12</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;20:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml
deleted file mode 100644
index f3a3d459fcdf..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml
+++ /dev/null
@@ -1,153 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-NV12M"><constant>V4L2_PIX_FMT_NV12M</constant></refname>
- <refname id="V4L2-PIX-FMT-NV21M"><constant>V4L2_PIX_FMT_NV21M</constant></refname>
- <refname id="V4L2-PIX-FMT-NV12MT-16X16"><constant>V4L2_PIX_FMT_NV12MT_16X16</constant></refname>
- <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> and <constant>V4L2_PIX_FMT_NV21</constant> with planes
- non contiguous in memory. </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format.
-The three components are separated into two sub-images or planes.
-<constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12
-</constant> in that the two planes are non-contiguous in memory, i.e. the chroma
-plane do not necessarily immediately follows the luma plane.
-The luminance data occupies the first plane. The Y plane has one byte per pixel.
-In the second plane there is a chrominance data with alternating chroma samples.
-The CbCr plane is the same width, in bytes, as the Y plane (and of the image),
-but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example,
-Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
-Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
-Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.
-<constant>V4L2_PIX_FMT_NV12MT_16X16</constant> is the tiled version of
-<constant>V4L2_PIX_FMT_NV12M</constant> with 16x16 macroblock tiles. Here pixels
-are arranged in 16x16 2D tiles and tiles are arranged in linear order in memory.
-<constant>V4L2_PIX_FMT_NV21M</constant> is the same as <constant>V4L2_PIX_FMT_NV12M</constant>
-except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
-
- <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be
-used only in drivers and applications that support the multi-planar API,
-described in <xref linkend="planar-apis"/>. </para>
-
- <para>If the Y plane has pad bytes after each row, then the
-CbCr plane has as many pad bytes after its rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_NV12M</constant> 4 &times; 4 pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start0&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;4:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml
deleted file mode 100644
index 8a70a1707b7a..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml
+++ /dev/null
@@ -1,66 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_NV12MT ('TM12')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-NV12MT"><constant>V4L2_PIX_FMT_NV12MT
-</constant></refname>
- <refpurpose>Formats with &frac12; horizontal and vertical
-chroma resolution. This format has two planes - one for luminance and one for
-chrominance. Chroma samples are interleaved. The difference to
-<constant>V4L2_PIX_FMT_NV12</constant> is the memory layout. Pixels are
-grouped in macroblocks of 64x32 size. The order of macroblocks in memory is
-also not standard.
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is the two-plane versions of the YUV 4:2:0 format where data
-is grouped into 64x32 macroblocks. The three components are separated into two
-sub-images or planes. The Y plane has one byte per pixel and pixels are grouped
-into 64x32 macroblocks. The CbCr plane has the same width, in bytes, as the Y
-plane (and the image), but is half as tall in pixels. The chroma plane is also
-grouped into 64x32 macroblocks.</para>
- <para>Width of the buffer has to be aligned to the multiple of 128, and
-height alignment is 32. Every four adjacent buffers - two horizontally and two
-vertically are grouped together and are located in memory in Z or flipped Z
-order. </para>
- <para>Layout of macroblocks in memory is presented in the following
-figure.</para>
- <para><figure id="nv12mt">
- <title><constant>V4L2_PIX_FMT_NV12MT</constant> macroblock Z shape
-memory layout</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="nv12mt.gif" format="GIF" />
- </imageobject>
- </mediaobject>
- </figure>
- The requirement that width is multiple of 128 is implemented because,
-the Z shape cannot be cut in half horizontally. In case the vertical resolution
-of macroblocks is odd then the last row of macroblocks is arranged in a linear
-order. </para>
- <para>In case of chroma the layout is identical. Cb and Cr samples are
-interleaved. Height of the buffer is aligned to 32.
- </para>
- <example>
- <title>Memory layout of macroblocks in <constant>V4L2_PIX_FMT_NV12
-</constant> format pixel image - extreme case</title>
- <para>
- <figure id="nv12mt_ex">
- <title>Example <constant>V4L2_PIX_FMT_NV12MT</constant> memory
-layout of macroblocks</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="nv12mt_example.gif" format="GIF" />
- </imageobject>
- </mediaobject>
- </figure>
- Memory layout of macroblocks of <constant>V4L2_PIX_FMT_NV12MT
-</constant> format in most extreme case.
- </para>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml
deleted file mode 100644
index 8ae1f8a810d0..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml
+++ /dev/null
@@ -1,166 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-NV16"><constant>V4L2_PIX_FMT_NV16</constant></refname>
- <refname id="V4L2-PIX-FMT-NV61"><constant>V4L2_PIX_FMT_NV61</constant></refname>
- <refpurpose>Formats with &frac12; horizontal
-chroma resolution, also known as YUV 4:2:2. One luminance and one
-chrominance plane with alternating chroma samples as opposed to
-<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These are two-plane versions of the YUV 4:2:2 format.
-The three components are separated into two sub-images or planes. The
-Y plane is first. The Y plane has one byte per pixel. For
-<constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane
-immediately follows the Y plane in memory. The CbCr plane is the same
-width and height, in bytes, as the Y plane (and of the image).
-Each CbCr pair belongs to two pixels. For example,
-Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
-Y'<subscript>00</subscript>, Y'<subscript>01</subscript>.
-<constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and
-Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
-
- <para>If the Y plane has pad bytes after each row, then the
-CbCr plane has as many pad bytes after its rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_NV16</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;20:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;28:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml
deleted file mode 100644
index fb2b5e35d665..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml
+++ /dev/null
@@ -1,170 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-NV16M"><constant>V4L2_PIX_FMT_NV16M</constant></refname>
- <refname id="V4L2-PIX-FMT-NV61M"><constant>V4L2_PIX_FMT_NV61M</constant></refname>
- <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV16</constant> and <constant>V4L2_PIX_FMT_NV61</constant> with planes
- non contiguous in memory. </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a multi-planar, two-plane version of the YUV 4:2:2 format.
-The three components are separated into two sub-images or planes.
-<constant>V4L2_PIX_FMT_NV16M</constant> differs from <constant>V4L2_PIX_FMT_NV16
-</constant> in that the two planes are non-contiguous in memory, i.e. the chroma
-plane does not necessarily immediately follow the luma plane.
-The luminance data occupies the first plane. The Y plane has one byte per pixel.
-In the second plane there is chrominance data with alternating chroma samples.
-The CbCr plane is the same width and height, in bytes, as the Y plane.
-Each CbCr pair belongs to two pixels. For example,
-Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
-Y'<subscript>00</subscript>, Y'<subscript>01</subscript>.
-<constant>V4L2_PIX_FMT_NV61M</constant> is the same as <constant>V4L2_PIX_FMT_NV16M</constant>
-except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
-
- <para><constant>V4L2_PIX_FMT_NV16M</constant> and
-<constant>V4L2_PIX_FMT_NV61M</constant> are intended to be used only in drivers
-and applications that support the multi-planar API, described in
-<xref linkend="planar-apis"/>. </para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_NV16M</constant> 4 &times; 4 pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start0&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>02</subscript></entry>
- <entry>Cr<subscript>02</subscript></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;4:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>12</subscript></entry>
- <entry>Cr<subscript>12</subscript></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;8:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Cb<subscript>22</subscript></entry>
- <entry>Cr<subscript>22</subscript></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;12:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Cb<subscript>32</subscript></entry>
- <entry>Cr<subscript>32</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv24.xml b/Documentation/DocBook/media/v4l/pixfmt-nv24.xml
deleted file mode 100644
index fb255f2ca9dd..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-nv24.xml
+++ /dev/null
@@ -1,121 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-NV24"><constant>V4L2_PIX_FMT_NV24</constant></refname>
- <refname id="V4L2-PIX-FMT-NV42"><constant>V4L2_PIX_FMT_NV42</constant></refname>
- <refpurpose>Formats with full horizontal and vertical
-chroma resolutions, also known as YUV 4:4:4. One luminance and one
-chrominance plane with alternating chroma samples as opposed to
-<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These are two-plane versions of the YUV 4:4:4 format. The three
- components are separated into two sub-images or planes. The Y plane is
- first, with each Y sample stored in one byte per pixel. For
- <constant>V4L2_PIX_FMT_NV24</constant>, a combined CbCr plane
- immediately follows the Y plane in memory. The CbCr plane has the same
- width and height, in pixels, as the Y plane (and the image). Each line
- contains one CbCr pair per pixel, with each Cb and Cr sample stored in
- one byte. <constant>V4L2_PIX_FMT_NV42</constant> is the same except that
- the Cb and Cr samples are swapped, the CrCb plane starts with a Cr
- sample.</para>
-
- <para>If the Y plane has pad bytes after each row, then the CbCr plane
- has twice as many pad bytes after its rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_NV24</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- <entry>Cb<subscript>02</subscript></entry>
- <entry>Cr<subscript>02</subscript></entry>
- <entry>Cb<subscript>03</subscript></entry>
- <entry>Cr<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- <entry>Cb<subscript>12</subscript></entry>
- <entry>Cr<subscript>12</subscript></entry>
- <entry>Cb<subscript>13</subscript></entry>
- <entry>Cr<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;32:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- <entry>Cb<subscript>22</subscript></entry>
- <entry>Cr<subscript>22</subscript></entry>
- <entry>Cb<subscript>23</subscript></entry>
- <entry>Cr<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;40:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- <entry>Cb<subscript>32</subscript></entry>
- <entry>Cr<subscript>32</subscript></entry>
- <entry>Cb<subscript>33</subscript></entry>
- <entry>Cr<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
deleted file mode 100644
index b60fb935b91b..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
+++ /dev/null
@@ -1,937 +0,0 @@
-<refentry id="packed-rgb">
- <refmeta>
- <refentrytitle>Packed RGB formats</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>Packed RGB formats</refname>
- <refpurpose>Packed RGB formats</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These formats are designed to match the pixel formats of
-typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
-per pixel. These are all packed-pixel formats, meaning all the data
-for a pixel lie next to each other in memory.</para>
-
- <table pgwide="1" frame="none" id="rgb-formats">
- <title>Packed RGB Image Formats</title>
- <tgroup cols="37" align="center">
- <colspec colname="id" align="left" />
- <colspec colname="fourcc" />
- <colspec colname="bit" />
-
- <colspec colnum="4" colname="b07" align="center" />
- <colspec colnum="5" colname="b06" align="center" />
- <colspec colnum="6" colname="b05" align="center" />
- <colspec colnum="7" colname="b04" align="center" />
- <colspec colnum="8" colname="b03" align="center" />
- <colspec colnum="9" colname="b02" align="center" />
- <colspec colnum="10" colname="b01" align="center" />
- <colspec colnum="11" colname="b00" align="center" />
-
- <colspec colnum="13" colname="b17" align="center" />
- <colspec colnum="14" colname="b16" align="center" />
- <colspec colnum="15" colname="b15" align="center" />
- <colspec colnum="16" colname="b14" align="center" />
- <colspec colnum="17" colname="b13" align="center" />
- <colspec colnum="18" colname="b12" align="center" />
- <colspec colnum="19" colname="b11" align="center" />
- <colspec colnum="20" colname="b10" align="center" />
-
- <colspec colnum="22" colname="b27" align="center" />
- <colspec colnum="23" colname="b26" align="center" />
- <colspec colnum="24" colname="b25" align="center" />
- <colspec colnum="25" colname="b24" align="center" />
- <colspec colnum="26" colname="b23" align="center" />
- <colspec colnum="27" colname="b22" align="center" />
- <colspec colnum="28" colname="b21" align="center" />
- <colspec colnum="29" colname="b20" align="center" />
-
- <colspec colnum="31" colname="b37" align="center" />
- <colspec colnum="32" colname="b36" align="center" />
- <colspec colnum="33" colname="b35" align="center" />
- <colspec colnum="34" colname="b34" align="center" />
- <colspec colnum="35" colname="b33" align="center" />
- <colspec colnum="36" colname="b32" align="center" />
- <colspec colnum="37" colname="b31" align="center" />
- <colspec colnum="38" colname="b30" align="center" />
-
- <spanspec namest="b07" nameend="b00" spanname="b0" />
- <spanspec namest="b17" nameend="b10" spanname="b1" />
- <spanspec namest="b27" nameend="b20" spanname="b2" />
- <spanspec namest="b37" nameend="b30" spanname="b3" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>&nbsp;</entry>
- <entry spanname="b0">Byte&nbsp;0 in memory</entry>
- <entry spanname="b1">Byte&nbsp;1</entry>
- <entry spanname="b2">Byte&nbsp;2</entry>
- <entry spanname="b3">Byte&nbsp;3</entry>
- </row>
- <row>
- <entry>&nbsp;</entry>
- <entry>&nbsp;</entry>
- <entry>Bit</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-RGB332">
- <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
- <entry>'RGB1'</entry>
- <entry></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-ARGB444">
- <entry><constant>V4L2_PIX_FMT_ARGB444</constant></entry>
- <entry>'AR12'</entry>
- <entry></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-XRGB444">
- <entry><constant>V4L2_PIX_FMT_XRGB444</constant></entry>
- <entry>'XR12'</entry>
- <entry></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-ARGB555">
- <entry><constant>V4L2_PIX_FMT_ARGB555</constant></entry>
- <entry>'AR15'</entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-XRGB555">
- <entry><constant>V4L2_PIX_FMT_XRGB555</constant></entry>
- <entry>'XR15'</entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-RGB565">
- <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
- <entry>'RGBP'</entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-ARGB555X">
- <entry><constant>V4L2_PIX_FMT_ARGB555X</constant></entry>
- <entry>'AR15' | (1 &lt;&lt; 31)</entry>
- <entry></entry>
- <entry>a</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-XRGB555X">
- <entry><constant>V4L2_PIX_FMT_XRGB555X</constant></entry>
- <entry>'XR15' | (1 &lt;&lt; 31)</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-RGB565X">
- <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
- <entry>'RGBR'</entry>
- <entry></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-BGR24">
- <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
- <entry>'BGR3'</entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-RGB24">
- <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
- <entry>'RGB3'</entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-BGR666">
- <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
- <entry>'BGRH'</entry>
- <entry></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- </row>
- <row id="V4L2-PIX-FMT-ABGR32">
- <entry><constant>V4L2_PIX_FMT_ABGR32</constant></entry>
- <entry>'AR24'</entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-XBGR32">
- <entry><constant>V4L2_PIX_FMT_XBGR32</constant></entry>
- <entry>'XR24'</entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- </row>
- <row id="V4L2-PIX-FMT-ARGB32">
- <entry><constant>V4L2_PIX_FMT_ARGB32</constant></entry>
- <entry>'BA24'</entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-XRGB32">
- <entry><constant>V4L2_PIX_FMT_XRGB32</constant></entry>
- <entry>'BX24'</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Bit 7 is the most significant bit.</para>
-
- <para>The usage and value of the alpha bits (a) in the ARGB and ABGR formats
- (collectively referred to as alpha formats) depend on the device type and
- hardware operation. <link linkend="capture">Capture</link> devices
- (including capture queues of mem-to-mem devices) fill the alpha component in
- memory. When the device outputs an alpha channel the alpha component will
- have a meaningful value. Otherwise, when the device doesn't output an alpha
- channel but can set the alpha bit to a user-configurable value, the <link
- linkend="v4l2-alpha-component"><constant>V4L2_CID_ALPHA_COMPONENT</constant>
- </link> control is used to specify that alpha value, and the alpha component
- of all pixels will be set to the value specified by that control. Otherwise
- a corresponding format without an alpha component (XRGB or XBGR) must be
- used instead of an alpha format.</para>
-
- <para><link linkend="output">Output</link> devices (including output queues
- of mem-to-mem devices and <link linkend="osd">video output overlay</link>
- devices) read the alpha component from memory. When the device processes the
- alpha channel the alpha component must be filled with meaningful values by
- applications. Otherwise a corresponding format without an alpha component
- (XRGB or XBGR) must be used instead of an alpha format.</para>
-
- <para>The XRGB and XBGR formats contain undefined bits (-). Applications,
- devices and drivers must ignore those bits, for both <link
- linkend="capture">capture</link> and <link linkend="output">output</link>
- devices.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
-image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="13" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>B<subscript>00</subscript></entry>
- <entry>G<subscript>00</subscript></entry>
- <entry>R<subscript>00</subscript></entry>
- <entry>B<subscript>01</subscript></entry>
- <entry>G<subscript>01</subscript></entry>
- <entry>R<subscript>01</subscript></entry>
- <entry>B<subscript>02</subscript></entry>
- <entry>G<subscript>02</subscript></entry>
- <entry>R<subscript>02</subscript></entry>
- <entry>B<subscript>03</subscript></entry>
- <entry>G<subscript>03</subscript></entry>
- <entry>R<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>B<subscript>10</subscript></entry>
- <entry>G<subscript>10</subscript></entry>
- <entry>R<subscript>10</subscript></entry>
- <entry>B<subscript>11</subscript></entry>
- <entry>G<subscript>11</subscript></entry>
- <entry>R<subscript>11</subscript></entry>
- <entry>B<subscript>12</subscript></entry>
- <entry>G<subscript>12</subscript></entry>
- <entry>R<subscript>12</subscript></entry>
- <entry>B<subscript>13</subscript></entry>
- <entry>G<subscript>13</subscript></entry>
- <entry>R<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>B<subscript>20</subscript></entry>
- <entry>G<subscript>20</subscript></entry>
- <entry>R<subscript>20</subscript></entry>
- <entry>B<subscript>21</subscript></entry>
- <entry>G<subscript>21</subscript></entry>
- <entry>R<subscript>21</subscript></entry>
- <entry>B<subscript>22</subscript></entry>
- <entry>G<subscript>22</subscript></entry>
- <entry>R<subscript>22</subscript></entry>
- <entry>B<subscript>23</subscript></entry>
- <entry>G<subscript>23</subscript></entry>
- <entry>R<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;36:</entry>
- <entry>B<subscript>30</subscript></entry>
- <entry>G<subscript>30</subscript></entry>
- <entry>R<subscript>30</subscript></entry>
- <entry>B<subscript>31</subscript></entry>
- <entry>G<subscript>31</subscript></entry>
- <entry>R<subscript>31</subscript></entry>
- <entry>B<subscript>32</subscript></entry>
- <entry>G<subscript>32</subscript></entry>
- <entry>R<subscript>32</subscript></entry>
- <entry>B<subscript>33</subscript></entry>
- <entry>G<subscript>33</subscript></entry>
- <entry>R<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
-
- <para>Formats defined in <xref linkend="rgb-formats-deprecated"/> are
- deprecated and must not be used by new drivers. They are documented here for
- reference. The meaning of their alpha bits (a) is ill-defined and
- interpreted as in either the corresponding ARGB or XRGB format, depending on
- the driver.</para>
-
- <table pgwide="1" frame="none" id="rgb-formats-deprecated">
- <title>Deprecated Packed RGB Image Formats</title>
- <tgroup cols="37" align="center">
- <colspec colname="id" align="left" />
- <colspec colname="fourcc" />
- <colspec colname="bit" />
-
- <colspec colnum="4" colname="b07" align="center" />
- <colspec colnum="5" colname="b06" align="center" />
- <colspec colnum="6" colname="b05" align="center" />
- <colspec colnum="7" colname="b04" align="center" />
- <colspec colnum="8" colname="b03" align="center" />
- <colspec colnum="9" colname="b02" align="center" />
- <colspec colnum="10" colname="b01" align="center" />
- <colspec colnum="11" colname="b00" align="center" />
-
- <colspec colnum="13" colname="b17" align="center" />
- <colspec colnum="14" colname="b16" align="center" />
- <colspec colnum="15" colname="b15" align="center" />
- <colspec colnum="16" colname="b14" align="center" />
- <colspec colnum="17" colname="b13" align="center" />
- <colspec colnum="18" colname="b12" align="center" />
- <colspec colnum="19" colname="b11" align="center" />
- <colspec colnum="20" colname="b10" align="center" />
-
- <colspec colnum="22" colname="b27" align="center" />
- <colspec colnum="23" colname="b26" align="center" />
- <colspec colnum="24" colname="b25" align="center" />
- <colspec colnum="25" colname="b24" align="center" />
- <colspec colnum="26" colname="b23" align="center" />
- <colspec colnum="27" colname="b22" align="center" />
- <colspec colnum="28" colname="b21" align="center" />
- <colspec colnum="29" colname="b20" align="center" />
-
- <colspec colnum="31" colname="b37" align="center" />
- <colspec colnum="32" colname="b36" align="center" />
- <colspec colnum="33" colname="b35" align="center" />
- <colspec colnum="34" colname="b34" align="center" />
- <colspec colnum="35" colname="b33" align="center" />
- <colspec colnum="36" colname="b32" align="center" />
- <colspec colnum="37" colname="b31" align="center" />
- <colspec colnum="38" colname="b30" align="center" />
-
- <spanspec namest="b07" nameend="b00" spanname="b0" />
- <spanspec namest="b17" nameend="b10" spanname="b1" />
- <spanspec namest="b27" nameend="b20" spanname="b2" />
- <spanspec namest="b37" nameend="b30" spanname="b3" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>&nbsp;</entry>
- <entry spanname="b0">Byte&nbsp;0 in memory</entry>
- <entry spanname="b1">Byte&nbsp;1</entry>
- <entry spanname="b2">Byte&nbsp;2</entry>
- <entry spanname="b3">Byte&nbsp;3</entry>
- </row>
- <row>
- <entry>&nbsp;</entry>
- <entry>&nbsp;</entry>
- <entry>Bit</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody>
- <row id="V4L2-PIX-FMT-RGB444">
- <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
- <entry>'R444'</entry>
- <entry></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-RGB555">
- <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
- <entry>'RGBO'</entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-RGB555X">
- <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
- <entry>'RGBQ'</entry>
- <entry></entry>
- <entry>a</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-BGR32">
- <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
- <entry>'BGR4'</entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- </row>
- <row id="V4L2-PIX-FMT-RGB32">
- <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
- <entry>'RGB4'</entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>A test utility to determine which RGB formats a driver
-actually supports is available from the LinuxTV v4l-dvb repository.
-See &v4l-dvb; for access instructions.</para>
-
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml
deleted file mode 100644
index 33fa5a47a865..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml
+++ /dev/null
@@ -1,236 +0,0 @@
-<refentry id="packed-yuv">
- <refmeta>
- <refentrytitle>Packed YUV formats</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>Packed YUV formats</refname>
- <refpurpose>Packed YUV formats</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>Similar to the packed RGB formats these formats store
-the Y, Cb and Cr component of each pixel in one 16 or 32 bit
-word.</para>
-
- <table pgwide="1" frame="none">
- <title>Packed YUV Image Formats</title>
- <tgroup cols="37" align="center">
- <colspec colname="id" align="left" />
- <colspec colname="fourcc" />
- <colspec colname="bit" />
-
- <colspec colnum="4" colname="b07" align="center" />
- <colspec colnum="5" colname="b06" align="center" />
- <colspec colnum="6" colname="b05" align="center" />
- <colspec colnum="7" colname="b04" align="center" />
- <colspec colnum="8" colname="b03" align="center" />
- <colspec colnum="9" colname="b02" align="center" />
- <colspec colnum="10" colname="b01" align="center" />
- <colspec colnum="11" colname="b00" align="center" />
-
- <colspec colnum="13" colname="b17" align="center" />
- <colspec colnum="14" colname="b16" align="center" />
- <colspec colnum="15" colname="b15" align="center" />
- <colspec colnum="16" colname="b14" align="center" />
- <colspec colnum="17" colname="b13" align="center" />
- <colspec colnum="18" colname="b12" align="center" />
- <colspec colnum="19" colname="b11" align="center" />
- <colspec colnum="20" colname="b10" align="center" />
-
- <colspec colnum="22" colname="b27" align="center" />
- <colspec colnum="23" colname="b26" align="center" />
- <colspec colnum="24" colname="b25" align="center" />
- <colspec colnum="25" colname="b24" align="center" />
- <colspec colnum="26" colname="b23" align="center" />
- <colspec colnum="27" colname="b22" align="center" />
- <colspec colnum="28" colname="b21" align="center" />
- <colspec colnum="29" colname="b20" align="center" />
-
- <colspec colnum="31" colname="b37" align="center" />
- <colspec colnum="32" colname="b36" align="center" />
- <colspec colnum="33" colname="b35" align="center" />
- <colspec colnum="34" colname="b34" align="center" />
- <colspec colnum="35" colname="b33" align="center" />
- <colspec colnum="36" colname="b32" align="center" />
- <colspec colnum="37" colname="b31" align="center" />
- <colspec colnum="38" colname="b30" align="center" />
-
- <spanspec namest="b07" nameend="b00" spanname="b0" />
- <spanspec namest="b17" nameend="b10" spanname="b1" />
- <spanspec namest="b27" nameend="b20" spanname="b2" />
- <spanspec namest="b37" nameend="b30" spanname="b3" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>&nbsp;</entry>
- <entry spanname="b0">Byte&nbsp;0 in memory</entry>
- <entry spanname="b1">Byte&nbsp;1</entry>
- <entry spanname="b2">Byte&nbsp;2</entry>
- <entry spanname="b3">Byte&nbsp;3</entry>
- </row>
- <row>
- <entry>&nbsp;</entry>
- <entry>&nbsp;</entry>
- <entry>Bit</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- <entry>&nbsp;</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-YUV444">
- <entry><constant>V4L2_PIX_FMT_YUV444</constant></entry>
- <entry>'Y444'</entry>
- <entry></entry>
- <entry>Cb<subscript>3</subscript></entry>
- <entry>Cb<subscript>2</subscript></entry>
- <entry>Cb<subscript>1</subscript></entry>
- <entry>Cb<subscript>0</subscript></entry>
- <entry>Cr<subscript>3</subscript></entry>
- <entry>Cr<subscript>2</subscript></entry>
- <entry>Cr<subscript>1</subscript></entry>
- <entry>Cr<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry>Y'<subscript>3</subscript></entry>
- <entry>Y'<subscript>2</subscript></entry>
- <entry>Y'<subscript>1</subscript></entry>
- <entry>Y'<subscript>0</subscript></entry>
- </row>
-
- <row id="V4L2-PIX-FMT-YUV555">
- <entry><constant>V4L2_PIX_FMT_YUV555</constant></entry>
- <entry>'YUVO'</entry>
- <entry></entry>
- <entry>Cb<subscript>2</subscript></entry>
- <entry>Cb<subscript>1</subscript></entry>
- <entry>Cb<subscript>0</subscript></entry>
- <entry>Cr<subscript>4</subscript></entry>
- <entry>Cr<subscript>3</subscript></entry>
- <entry>Cr<subscript>2</subscript></entry>
- <entry>Cr<subscript>1</subscript></entry>
- <entry>Cr<subscript>0</subscript></entry>
- <entry></entry>
- <entry>a</entry>
- <entry>Y'<subscript>4</subscript></entry>
- <entry>Y'<subscript>3</subscript></entry>
- <entry>Y'<subscript>2</subscript></entry>
- <entry>Y'<subscript>1</subscript></entry>
- <entry>Y'<subscript>0</subscript></entry>
- <entry>Cb<subscript>4</subscript></entry>
- <entry>Cb<subscript>3</subscript></entry>
- </row>
-
- <row id="V4L2-PIX-FMT-YUV565">
- <entry><constant>V4L2_PIX_FMT_YUV565</constant></entry>
- <entry>'YUVP'</entry>
- <entry></entry>
- <entry>Cb<subscript>2</subscript></entry>
- <entry>Cb<subscript>1</subscript></entry>
- <entry>Cb<subscript>0</subscript></entry>
- <entry>Cr<subscript>4</subscript></entry>
- <entry>Cr<subscript>3</subscript></entry>
- <entry>Cr<subscript>2</subscript></entry>
- <entry>Cr<subscript>1</subscript></entry>
- <entry>Cr<subscript>0</subscript></entry>
- <entry></entry>
- <entry>Y'<subscript>4</subscript></entry>
- <entry>Y'<subscript>3</subscript></entry>
- <entry>Y'<subscript>2</subscript></entry>
- <entry>Y'<subscript>1</subscript></entry>
- <entry>Y'<subscript>0</subscript></entry>
- <entry>Cb<subscript>5</subscript></entry>
- <entry>Cb<subscript>4</subscript></entry>
- <entry>Cb<subscript>3</subscript></entry>
- </row>
-
- <row id="V4L2-PIX-FMT-YUV32">
- <entry><constant>V4L2_PIX_FMT_YUV32</constant></entry>
- <entry>'YUV4'</entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry></entry>
- <entry>Y'<subscript>7</subscript></entry>
- <entry>Y'<subscript>6</subscript></entry>
- <entry>Y'<subscript>5</subscript></entry>
- <entry>Y'<subscript>4</subscript></entry>
- <entry>Y'<subscript>3</subscript></entry>
- <entry>Y'<subscript>2</subscript></entry>
- <entry>Y'<subscript>1</subscript></entry>
- <entry>Y'<subscript>0</subscript></entry>
- <entry></entry>
- <entry>Cb<subscript>7</subscript></entry>
- <entry>Cb<subscript>6</subscript></entry>
- <entry>Cb<subscript>5</subscript></entry>
- <entry>Cb<subscript>4</subscript></entry>
- <entry>Cb<subscript>3</subscript></entry>
- <entry>Cb<subscript>2</subscript></entry>
- <entry>Cb<subscript>1</subscript></entry>
- <entry>Cb<subscript>0</subscript></entry>
- <entry></entry>
- <entry>Cr<subscript>7</subscript></entry>
- <entry>Cr<subscript>6</subscript></entry>
- <entry>Cr<subscript>5</subscript></entry>
- <entry>Cr<subscript>4</subscript></entry>
- <entry>Cr<subscript>3</subscript></entry>
- <entry>Cr<subscript>2</subscript></entry>
- <entry>Cr<subscript>1</subscript></entry>
- <entry>Cr<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Bit 7 is the most significant bit. The value of a = alpha
-bits is undefined when reading from the driver, ignored when writing
-to the driver, except when alpha blending has been negotiated for a
-<link linkend="overlay">Video Overlay</link> or <link
-linkend="osd">Video Output Overlay</link>.</para>
-
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml
deleted file mode 100644
index 6494b05d84a1..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml
+++ /dev/null
@@ -1,83 +0,0 @@
-<refentry id="V4L2-PIX-FMT-SBGGR16">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SBGGR16 ('BYR2')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_SBGGR16</constant></refname>
- <refpurpose>Bayer RGB format</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This format is similar to <link
-linkend="V4L2-PIX-FMT-SBGGR8">
-<constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has
-a depth of 16 bits. The least significant byte is stored at lower
-memory addresses (little-endian). Note the actual sampling precision
-may be lower than 16 bits, for example 10 bits per pixel with values
-in range 0 to 1023.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>B<subscript>00low</subscript></entry>
- <entry>B<subscript>00high</subscript></entry>
- <entry>G<subscript>01low</subscript></entry>
- <entry>G<subscript>01high</subscript></entry>
- <entry>B<subscript>02low</subscript></entry>
- <entry>B<subscript>02high</subscript></entry>
- <entry>G<subscript>03low</subscript></entry>
- <entry>G<subscript>03high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>G<subscript>10low</subscript></entry>
- <entry>G<subscript>10high</subscript></entry>
- <entry>R<subscript>11low</subscript></entry>
- <entry>R<subscript>11high</subscript></entry>
- <entry>G<subscript>12low</subscript></entry>
- <entry>G<subscript>12high</subscript></entry>
- <entry>R<subscript>13low</subscript></entry>
- <entry>R<subscript>13high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>B<subscript>20low</subscript></entry>
- <entry>B<subscript>20high</subscript></entry>
- <entry>G<subscript>21low</subscript></entry>
- <entry>G<subscript>21high</subscript></entry>
- <entry>B<subscript>22low</subscript></entry>
- <entry>B<subscript>22high</subscript></entry>
- <entry>G<subscript>23low</subscript></entry>
- <entry>G<subscript>23high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>G<subscript>30low</subscript></entry>
- <entry>G<subscript>30high</subscript></entry>
- <entry>R<subscript>31low</subscript></entry>
- <entry>R<subscript>31high</subscript></entry>
- <entry>G<subscript>32low</subscript></entry>
- <entry>G<subscript>32high</subscript></entry>
- <entry>R<subscript>33low</subscript></entry>
- <entry>R<subscript>33high</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml
deleted file mode 100644
index 5eaf2b42d3f7..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml
+++ /dev/null
@@ -1,67 +0,0 @@
- <refentry id="V4L2-PIX-FMT-SBGGR8">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SBGGR8 ('BA81')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_SBGGR8</constant></refname>
- <refpurpose>Bayer RGB format</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is commonly the native format of digital cameras,
-reflecting the arrangement of sensors on the CCD device. Only one red,
-green or blue value is given for each pixel. Missing components must
-be interpolated from neighbouring pixels. From left to right the first
-row consists of a blue and green value, the second row of a green and
-red value. This scheme repeats to the right and down for every two
-columns and rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>B<subscript>00</subscript></entry>
- <entry>G<subscript>01</subscript></entry>
- <entry>B<subscript>02</subscript></entry>
- <entry>G<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>G<subscript>10</subscript></entry>
- <entry>R<subscript>11</subscript></entry>
- <entry>G<subscript>12</subscript></entry>
- <entry>R<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>B<subscript>20</subscript></entry>
- <entry>G<subscript>21</subscript></entry>
- <entry>B<subscript>22</subscript></entry>
- <entry>G<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>G<subscript>30</subscript></entry>
- <entry>R<subscript>31</subscript></entry>
- <entry>G<subscript>32</subscript></entry>
- <entry>R<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml
deleted file mode 100644
index 6118d8f7a20c..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml
+++ /dev/null
@@ -1,44 +0,0 @@
-<refentry id="V4L2-SDR-FMT-CS08">
- <refmeta>
- <refentrytitle>V4L2_SDR_FMT_CS8 ('CS08')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>
- <constant>V4L2_SDR_FMT_CS8</constant>
- </refname>
- <refpurpose>Complex signed 8-bit IQ sample</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>
-This format contains sequence of complex number samples. Each complex number
-consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
-represented as a 8 bit signed number. I value comes first and Q value after
-that.
- </para>
- <example>
- <title><constant>V4L2_SDR_FMT_CS8</constant> 1 sample</title>
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="2" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>I'<subscript>0</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;1:</entry>
- <entry>Q'<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml
deleted file mode 100644
index e4b494ce1369..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml
+++ /dev/null
@@ -1,47 +0,0 @@
-<refentry id="V4L2-SDR-FMT-CS14LE">
- <refmeta>
- <refentrytitle>V4L2_SDR_FMT_CS14LE ('CS14')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>
- <constant>V4L2_SDR_FMT_CS14LE</constant>
- </refname>
- <refpurpose>Complex signed 14-bit little endian IQ sample</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>
-This format contains sequence of complex number samples. Each complex number
-consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
-represented as a 14 bit signed little endian number. I value comes first
-and Q value after that. 14 bit value is stored in 16 bit space with unused
-high bits padded with 0.
- </para>
- <example>
- <title><constant>V4L2_SDR_FMT_CS14LE</constant> 1 sample</title>
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="3" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>I'<subscript>0[7:0]</subscript></entry>
- <entry>I'<subscript>0[13:8]</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;2:</entry>
- <entry>Q'<subscript>0[7:0]</subscript></entry>
- <entry>Q'<subscript>0[13:8]</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml
deleted file mode 100644
index 2d80104c178b..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml
+++ /dev/null
@@ -1,44 +0,0 @@
-<refentry id="V4L2-SDR-FMT-CU08">
- <refmeta>
- <refentrytitle>V4L2_SDR_FMT_CU8 ('CU08')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>
- <constant>V4L2_SDR_FMT_CU8</constant>
- </refname>
- <refpurpose>Complex unsigned 8-bit IQ sample</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>
-This format contains sequence of complex number samples. Each complex number
-consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
-represented as a 8 bit unsigned number. I value comes first and Q value after
-that.
- </para>
- <example>
- <title><constant>V4L2_SDR_FMT_CU8</constant> 1 sample</title>
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="2" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>I'<subscript>0</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;1:</entry>
- <entry>Q'<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml
deleted file mode 100644
index 26288ffa9071..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml
+++ /dev/null
@@ -1,46 +0,0 @@
-<refentry id="V4L2-SDR-FMT-CU16LE">
- <refmeta>
- <refentrytitle>V4L2_SDR_FMT_CU16LE ('CU16')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>
- <constant>V4L2_SDR_FMT_CU16LE</constant>
- </refname>
- <refpurpose>Complex unsigned 16-bit little endian IQ sample</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>
-This format contains sequence of complex number samples. Each complex number
-consist two parts, called In-phase and Quadrature (IQ). Both I and Q are
-represented as a 16 bit unsigned little endian number. I value comes first
-and Q value after that.
- </para>
- <example>
- <title><constant>V4L2_SDR_FMT_CU16LE</constant> 1 sample</title>
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="3" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>I'<subscript>0[7:0]</subscript></entry>
- <entry>I'<subscript>0[15:8]</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;2:</entry>
- <entry>Q'<subscript>0[7:0]</subscript></entry>
- <entry>Q'<subscript>0[15:8]</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml
deleted file mode 100644
index 3df076b99f94..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml
+++ /dev/null
@@ -1,40 +0,0 @@
-<refentry id="V4L2-SDR-FMT-RU12LE">
- <refmeta>
- <refentrytitle>V4L2_SDR_FMT_RU12LE ('RU12')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname>
- <constant>V4L2_SDR_FMT_RU12LE</constant>
- </refname>
- <refpurpose>Real unsigned 12-bit little endian sample</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>
-This format contains sequence of real number samples. Each sample is
-represented as a 12 bit unsigned little endian number. Sample is stored
-in 16 bit space with unused high bits padded with 0.
- </para>
- <example>
- <title><constant>V4L2_SDR_FMT_RU12LE</constant> 1 sample</title>
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="3" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>I'<subscript>0[7:0]</subscript></entry>
- <entry>I'<subscript>0[11:8]</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml
deleted file mode 100644
index fee65dca79c5..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml
+++ /dev/null
@@ -1,67 +0,0 @@
- <refentry id="V4L2-PIX-FMT-SGBRG8">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SGBRG8 ('GBRG')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_SGBRG8</constant></refname>
- <refpurpose>Bayer RGB format</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is commonly the native format of digital cameras,
-reflecting the arrangement of sensors on the CCD device. Only one red,
-green or blue value is given for each pixel. Missing components must
-be interpolated from neighbouring pixels. From left to right the first
-row consists of a green and blue value, the second row of a red and
-green value. This scheme repeats to the right and down for every two
-columns and rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>G<subscript>00</subscript></entry>
- <entry>B<subscript>01</subscript></entry>
- <entry>G<subscript>02</subscript></entry>
- <entry>B<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>R<subscript>10</subscript></entry>
- <entry>G<subscript>11</subscript></entry>
- <entry>R<subscript>12</subscript></entry>
- <entry>G<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>G<subscript>20</subscript></entry>
- <entry>B<subscript>21</subscript></entry>
- <entry>G<subscript>22</subscript></entry>
- <entry>B<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>R<subscript>30</subscript></entry>
- <entry>G<subscript>31</subscript></entry>
- <entry>R<subscript>32</subscript></entry>
- <entry>G<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml
deleted file mode 100644
index 7803b8c41b45..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml
+++ /dev/null
@@ -1,67 +0,0 @@
- <refentry id="V4L2-PIX-FMT-SGRBG8">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname>
- <refpurpose>Bayer RGB format</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is commonly the native format of digital cameras,
-reflecting the arrangement of sensors on the CCD device. Only one red,
-green or blue value is given for each pixel. Missing components must
-be interpolated from neighbouring pixels. From left to right the first
-row consists of a green and blue value, the second row of a red and
-green value. This scheme repeats to the right and down for every two
-columns and rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 &times;
-4 pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>G<subscript>00</subscript></entry>
- <entry>R<subscript>01</subscript></entry>
- <entry>G<subscript>02</subscript></entry>
- <entry>R<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>B<subscript>10</subscript></entry>
- <entry>G<subscript>11</subscript></entry>
- <entry>B<subscript>12</subscript></entry>
- <entry>G<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>G<subscript>20</subscript></entry>
- <entry>R<subscript>21</subscript></entry>
- <entry>G<subscript>22</subscript></entry>
- <entry>R<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>B<subscript>30</subscript></entry>
- <entry>G<subscript>31</subscript></entry>
- <entry>B<subscript>32</subscript></entry>
- <entry>G<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml
deleted file mode 100644
index f34d03ebda3a..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml
+++ /dev/null
@@ -1,90 +0,0 @@
- <refentry id="pixfmt-srggb10">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SRGGB10 ('RG10'),
- V4L2_PIX_FMT_SGRBG10 ('BA10'),
- V4L2_PIX_FMT_SGBRG10 ('GB10'),
- V4L2_PIX_FMT_SBGGR10 ('BG10'),
- </refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-SRGGB10"><constant>V4L2_PIX_FMT_SRGGB10</constant></refname>
- <refname id="V4L2-PIX-FMT-SGRBG10"><constant>V4L2_PIX_FMT_SGRBG10</constant></refname>
- <refname id="V4L2-PIX-FMT-SGBRG10"><constant>V4L2_PIX_FMT_SGBRG10</constant></refname>
- <refname id="V4L2-PIX-FMT-SBGGR10"><constant>V4L2_PIX_FMT_SBGGR10</constant></refname>
- <refpurpose>10-bit Bayer formats expanded to 16 bits</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These four pixel formats are raw sRGB / Bayer formats with
-10 bits per colour. Each colour component is stored in a 16-bit word, with 6
-unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
-and n/2 blue or red samples, with alternating red and blue rows. Bytes are
-stored in memory in little endian order. They are conventionally described
-as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these
-formats</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SBGGR10</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte, high 6 bits in high bytes are 0.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>B<subscript>00low</subscript></entry>
- <entry>B<subscript>00high</subscript></entry>
- <entry>G<subscript>01low</subscript></entry>
- <entry>G<subscript>01high</subscript></entry>
- <entry>B<subscript>02low</subscript></entry>
- <entry>B<subscript>02high</subscript></entry>
- <entry>G<subscript>03low</subscript></entry>
- <entry>G<subscript>03high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>G<subscript>10low</subscript></entry>
- <entry>G<subscript>10high</subscript></entry>
- <entry>R<subscript>11low</subscript></entry>
- <entry>R<subscript>11high</subscript></entry>
- <entry>G<subscript>12low</subscript></entry>
- <entry>G<subscript>12high</subscript></entry>
- <entry>R<subscript>13low</subscript></entry>
- <entry>R<subscript>13high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>B<subscript>20low</subscript></entry>
- <entry>B<subscript>20high</subscript></entry>
- <entry>G<subscript>21low</subscript></entry>
- <entry>G<subscript>21high</subscript></entry>
- <entry>B<subscript>22low</subscript></entry>
- <entry>B<subscript>22high</subscript></entry>
- <entry>G<subscript>23low</subscript></entry>
- <entry>G<subscript>23high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>G<subscript>30low</subscript></entry>
- <entry>G<subscript>30high</subscript></entry>
- <entry>R<subscript>31low</subscript></entry>
- <entry>R<subscript>31high</subscript></entry>
- <entry>G<subscript>32low</subscript></entry>
- <entry>G<subscript>32high</subscript></entry>
- <entry>R<subscript>33low</subscript></entry>
- <entry>R<subscript>33high</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml
deleted file mode 100644
index d2e5845e57fb..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml
+++ /dev/null
@@ -1,34 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>
- V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'),
- V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'),
- V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'),
- V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'),
- </refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-SBGGR10ALAW8">
- <constant>V4L2_PIX_FMT_SBGGR10ALAW8</constant>
- </refname>
- <refname id="V4L2-PIX-FMT-SGBRG10ALAW8">
- <constant>V4L2_PIX_FMT_SGBRG10ALAW8</constant>
- </refname>
- <refname id="V4L2-PIX-FMT-SGRBG10ALAW8">
- <constant>V4L2_PIX_FMT_SGRBG10ALAW8</constant>
- </refname>
- <refname id="V4L2-PIX-FMT-SRGGB10ALAW8">
- <constant>V4L2_PIX_FMT_SRGGB10ALAW8</constant>
- </refname>
- <refpurpose>10-bit Bayer formats compressed to 8 bits</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>These four pixel formats are raw sRGB / Bayer
- formats with 10 bits per color compressed to 8 bits each,
- using the A-LAW algorithm. Each color component consumes 8
- bits of memory. In other respects this format is similar to
- <xref linkend="V4L2-PIX-FMT-SRGGB8"></xref>.</para>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml
deleted file mode 100644
index bde89878c5c5..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml
+++ /dev/null
@@ -1,28 +0,0 @@
- <refentry id="pixfmt-srggb10dpcm8">
- <refmeta>
- <refentrytitle>
- V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'),
- V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'),
- V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'),
- V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'),
- </refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-SBGGR10DPCM8"><constant>V4L2_PIX_FMT_SBGGR10DPCM8</constant></refname>
- <refname id="V4L2-PIX-FMT-SGBRG10DPCM8"><constant>V4L2_PIX_FMT_SGBRG10DPCM8</constant></refname>
- <refname id="V4L2-PIX-FMT-SGRBG10DPCM8"><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></refname>
- <refname id="V4L2-PIX-FMT-SRGGB10DPCM8"><constant>V4L2_PIX_FMT_SRGGB10DPCM8</constant></refname>
- <refpurpose>10-bit Bayer formats compressed to 8 bits</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These four pixel formats are raw sRGB / Bayer formats
- with 10 bits per colour compressed to 8 bits each, using DPCM
- compression. DPCM, differential pulse-code modulation, is lossy.
- Each colour component consumes 8 bits of memory. In other respects
- this format is similar to <xref linkend="pixfmt-srggb10" />.</para>
-
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml
deleted file mode 100644
index a8cc102cde4f..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml
+++ /dev/null
@@ -1,99 +0,0 @@
- <refentry id="pixfmt-srggb10p">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SRGGB10P ('pRAA'),
- V4L2_PIX_FMT_SGRBG10P ('pgAA'),
- V4L2_PIX_FMT_SGBRG10P ('pGAA'),
- V4L2_PIX_FMT_SBGGR10P ('pBAA'),
- </refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-SRGGB10P"><constant>V4L2_PIX_FMT_SRGGB10P</constant></refname>
- <refname id="V4L2-PIX-FMT-SGRBG10P"><constant>V4L2_PIX_FMT_SGRBG10P</constant></refname>
- <refname id="V4L2-PIX-FMT-SGBRG10P"><constant>V4L2_PIX_FMT_SGBRG10P</constant></refname>
- <refname id="V4L2-PIX-FMT-SBGGR10P"><constant>V4L2_PIX_FMT_SBGGR10P</constant></refname>
- <refpurpose>10-bit packed Bayer formats</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These four pixel formats are packed raw sRGB /
- Bayer formats with 10 bits per colour. Every four consecutive
- colour components are packed into 5 bytes. Each of the first 4
- bytes contain the 8 high order bits of the pixels, and the
- fifth byte contains the two least significants bits of each
- pixel, in the same order.</para>
-
- <para>Each n-pixel row contains n/2 green samples and n/2 blue
- or red samples, with alternating green-red and green-blue
- rows. They are conventionally described as GRGR... BGBG...,
- RGRG... GBGB..., etc. Below is an example of one of these
- formats:</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SBGGR10P</constant> 4 &times; 4
- pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="topbot" colsep="1" rowsep="1">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>B<subscript>00high</subscript></entry>
- <entry>G<subscript>01high</subscript></entry>
- <entry>B<subscript>02high</subscript></entry>
- <entry>G<subscript>03high</subscript></entry>
- <entry>B<subscript>00low</subscript>(bits 7--6)
- G<subscript>01low</subscript>(bits 5--4)
- B<subscript>02low</subscript>(bits 3--2)
- G<subscript>03low</subscript>(bits 1--0)
- </entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;5:</entry>
- <entry>G<subscript>10high</subscript></entry>
- <entry>R<subscript>11high</subscript></entry>
- <entry>G<subscript>12high</subscript></entry>
- <entry>R<subscript>13high</subscript></entry>
- <entry>G<subscript>10low</subscript>(bits 7--6)
- R<subscript>11low</subscript>(bits 5--4)
- G<subscript>12low</subscript>(bits 3--2)
- R<subscript>13low</subscript>(bits 1--0)
- </entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;10:</entry>
- <entry>B<subscript>20high</subscript></entry>
- <entry>G<subscript>21high</subscript></entry>
- <entry>B<subscript>22high</subscript></entry>
- <entry>G<subscript>23high</subscript></entry>
- <entry>B<subscript>20low</subscript>(bits 7--6)
- G<subscript>21low</subscript>(bits 5--4)
- B<subscript>22low</subscript>(bits 3--2)
- G<subscript>23low</subscript>(bits 1--0)
- </entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;15:</entry>
- <entry>G<subscript>30high</subscript></entry>
- <entry>R<subscript>31high</subscript></entry>
- <entry>G<subscript>32high</subscript></entry>
- <entry>R<subscript>33high</subscript></entry>
- <entry>G<subscript>30low</subscript>(bits 7--6)
- R<subscript>31low</subscript>(bits 5--4)
- G<subscript>32low</subscript>(bits 3--2)
- R<subscript>33low</subscript>(bits 1--0)
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
deleted file mode 100644
index 0c8e4adf417f..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
+++ /dev/null
@@ -1,90 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SRGGB12 ('RG12'),
- V4L2_PIX_FMT_SGRBG12 ('BA12'),
- V4L2_PIX_FMT_SGBRG12 ('GB12'),
- V4L2_PIX_FMT_SBGGR12 ('BG12'),
- </refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-SRGGB12"><constant>V4L2_PIX_FMT_SRGGB12</constant></refname>
- <refname id="V4L2-PIX-FMT-SGRBG12"><constant>V4L2_PIX_FMT_SGRBG12</constant></refname>
- <refname id="V4L2-PIX-FMT-SGBRG12"><constant>V4L2_PIX_FMT_SGBRG12</constant></refname>
- <refname id="V4L2-PIX-FMT-SBGGR12"><constant>V4L2_PIX_FMT_SBGGR12</constant></refname>
- <refpurpose>12-bit Bayer formats expanded to 16 bits</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These four pixel formats are raw sRGB / Bayer formats with
-12 bits per colour. Each colour component is stored in a 16-bit word, with 4
-unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
-and n/2 blue or red samples, with alternating red and blue rows. Bytes are
-stored in memory in little endian order. They are conventionally described
-as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these
-formats</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SBGGR12</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte, high 6 bits in high bytes are 0.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>B<subscript>00low</subscript></entry>
- <entry>B<subscript>00high</subscript></entry>
- <entry>G<subscript>01low</subscript></entry>
- <entry>G<subscript>01high</subscript></entry>
- <entry>B<subscript>02low</subscript></entry>
- <entry>B<subscript>02high</subscript></entry>
- <entry>G<subscript>03low</subscript></entry>
- <entry>G<subscript>03high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>G<subscript>10low</subscript></entry>
- <entry>G<subscript>10high</subscript></entry>
- <entry>R<subscript>11low</subscript></entry>
- <entry>R<subscript>11high</subscript></entry>
- <entry>G<subscript>12low</subscript></entry>
- <entry>G<subscript>12high</subscript></entry>
- <entry>R<subscript>13low</subscript></entry>
- <entry>R<subscript>13high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>B<subscript>20low</subscript></entry>
- <entry>B<subscript>20high</subscript></entry>
- <entry>G<subscript>21low</subscript></entry>
- <entry>G<subscript>21high</subscript></entry>
- <entry>B<subscript>22low</subscript></entry>
- <entry>B<subscript>22high</subscript></entry>
- <entry>G<subscript>23low</subscript></entry>
- <entry>G<subscript>23high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>G<subscript>30low</subscript></entry>
- <entry>G<subscript>30high</subscript></entry>
- <entry>R<subscript>31low</subscript></entry>
- <entry>R<subscript>31high</subscript></entry>
- <entry>G<subscript>32low</subscript></entry>
- <entry>G<subscript>32high</subscript></entry>
- <entry>R<subscript>33low</subscript></entry>
- <entry>R<subscript>33high</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml
deleted file mode 100644
index 2570e3be3cf1..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml
+++ /dev/null
@@ -1,67 +0,0 @@
- <refentry id="V4L2-PIX-FMT-SRGGB8">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_SRGGB8 ('RGGB')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_SRGGB8</constant></refname>
- <refpurpose>Bayer RGB format</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is commonly the native format of digital cameras,
-reflecting the arrangement of sensors on the CCD device. Only one red,
-green or blue value is given for each pixel. Missing components must
-be interpolated from neighbouring pixels. From left to right the first
-row consists of a red and green value, the second row of a green and
-blue value. This scheme repeats to the right and down for every two
-columns and rows.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_SRGGB8</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>R<subscript>00</subscript></entry>
- <entry>G<subscript>01</subscript></entry>
- <entry>R<subscript>02</subscript></entry>
- <entry>G<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>G<subscript>10</subscript></entry>
- <entry>B<subscript>11</subscript></entry>
- <entry>G<subscript>12</subscript></entry>
- <entry>B<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>R<subscript>20</subscript></entry>
- <entry>G<subscript>21</subscript></entry>
- <entry>R<subscript>22</subscript></entry>
- <entry>G<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>G<subscript>30</subscript></entry>
- <entry>B<subscript>31</subscript></entry>
- <entry>G<subscript>32</subscript></entry>
- <entry>B<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-uv8.xml b/Documentation/DocBook/media/v4l/pixfmt-uv8.xml
deleted file mode 100644
index c507c1f73cd0..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-uv8.xml
+++ /dev/null
@@ -1,62 +0,0 @@
- <refentry id="V4L2-PIX-FMT-UV8">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_UV8 ('UV8')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_UV8</constant></refname>
- <refpurpose>UV plane interleaved</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <para>In this format there is no Y plane, Only CbCr plane. ie
- (UV interleaved)</para>
- <example>
- <title>
- <constant>V4L2_PIX_FMT_UV8</constant>
- pixel image
- </title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml
deleted file mode 100644
index b1f6801a17ff..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml
+++ /dev/null
@@ -1,120 +0,0 @@
- <refentry id="V4L2-PIX-FMT-UYVY">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_UYVY ('UYVY')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_UYVY</constant></refname>
- <refpurpose>Variation of
-<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
-in memory</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>In this format each four bytes is two pixels. Each four
-bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
-the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
-components have half the horizontal resolution of the Y
-component.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_UYVY</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml
deleted file mode 100644
index 82803408b389..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml
+++ /dev/null
@@ -1,120 +0,0 @@
- <refentry id="V4L2-PIX-FMT-VYUY">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_VYUY ('VYUY')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_VYUY</constant></refname>
- <refpurpose>Variation of
-<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
-in memory</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>In this format each four bytes is two pixels. Each four
-bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
-the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
-components have half the horizontal resolution of the Y
-component.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_VYUY</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y10.xml b/Documentation/DocBook/media/v4l/pixfmt-y10.xml
deleted file mode 100644
index d065043db8d8..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-y10.xml
+++ /dev/null
@@ -1,79 +0,0 @@
-<refentry id="V4L2-PIX-FMT-Y10">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_Y10 ('Y10 ')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_Y10</constant></refname>
- <refpurpose>Grey-scale image</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a grey-scale image with a depth of 10 bits per pixel. Pixels
-are stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_Y10</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00low</subscript></entry>
- <entry>Y'<subscript>00high</subscript></entry>
- <entry>Y'<subscript>01low</subscript></entry>
- <entry>Y'<subscript>01high</subscript></entry>
- <entry>Y'<subscript>02low</subscript></entry>
- <entry>Y'<subscript>02high</subscript></entry>
- <entry>Y'<subscript>03low</subscript></entry>
- <entry>Y'<subscript>03high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>10low</subscript></entry>
- <entry>Y'<subscript>10high</subscript></entry>
- <entry>Y'<subscript>11low</subscript></entry>
- <entry>Y'<subscript>11high</subscript></entry>
- <entry>Y'<subscript>12low</subscript></entry>
- <entry>Y'<subscript>12high</subscript></entry>
- <entry>Y'<subscript>13low</subscript></entry>
- <entry>Y'<subscript>13high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Y'<subscript>20low</subscript></entry>
- <entry>Y'<subscript>20high</subscript></entry>
- <entry>Y'<subscript>21low</subscript></entry>
- <entry>Y'<subscript>21high</subscript></entry>
- <entry>Y'<subscript>22low</subscript></entry>
- <entry>Y'<subscript>22high</subscript></entry>
- <entry>Y'<subscript>23low</subscript></entry>
- <entry>Y'<subscript>23high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Y'<subscript>30low</subscript></entry>
- <entry>Y'<subscript>30high</subscript></entry>
- <entry>Y'<subscript>31low</subscript></entry>
- <entry>Y'<subscript>31high</subscript></entry>
- <entry>Y'<subscript>32low</subscript></entry>
- <entry>Y'<subscript>32high</subscript></entry>
- <entry>Y'<subscript>33low</subscript></entry>
- <entry>Y'<subscript>33high</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y10b.xml b/Documentation/DocBook/media/v4l/pixfmt-y10b.xml
deleted file mode 100644
index adb0ad808c93..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-y10b.xml
+++ /dev/null
@@ -1,43 +0,0 @@
-<refentry id="V4L2-PIX-FMT-Y10BPACK">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_Y10BPACK ('Y10B')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_Y10BPACK</constant></refname>
- <refpurpose>Grey-scale image as a bit-packed array</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a packed grey-scale image format with a depth of 10 bits per
- pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
- with no padding between them and with the most significant bits coming
- first from the left.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_Y10BPACK</constant> 4 pixel data stream taking 5 bytes</title>
-
- <formalpara>
- <title>Bit-packed representation</title>
- <para>pixels cross the byte boundary and have a ratio of 5 bytes for each 4
- pixels.
- <informaltable frame="all">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>Y'<subscript>00[9:2]</subscript></entry>
- <entry>Y'<subscript>00[1:0]</subscript>Y'<subscript>01[9:4]</subscript></entry>
- <entry>Y'<subscript>01[3:0]</subscript>Y'<subscript>02[9:6]</subscript></entry>
- <entry>Y'<subscript>02[5:0]</subscript>Y'<subscript>03[9:8]</subscript></entry>
- <entry>Y'<subscript>03[7:0]</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y12.xml b/Documentation/DocBook/media/v4l/pixfmt-y12.xml
deleted file mode 100644
index ff417b858cc9..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-y12.xml
+++ /dev/null
@@ -1,79 +0,0 @@
-<refentry id="V4L2-PIX-FMT-Y12">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_Y12 ('Y12 ')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_Y12</constant></refname>
- <refpurpose>Grey-scale image</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a grey-scale image with a depth of 12 bits per pixel. Pixels
-are stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_Y12</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00low</subscript></entry>
- <entry>Y'<subscript>00high</subscript></entry>
- <entry>Y'<subscript>01low</subscript></entry>
- <entry>Y'<subscript>01high</subscript></entry>
- <entry>Y'<subscript>02low</subscript></entry>
- <entry>Y'<subscript>02high</subscript></entry>
- <entry>Y'<subscript>03low</subscript></entry>
- <entry>Y'<subscript>03high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>10low</subscript></entry>
- <entry>Y'<subscript>10high</subscript></entry>
- <entry>Y'<subscript>11low</subscript></entry>
- <entry>Y'<subscript>11high</subscript></entry>
- <entry>Y'<subscript>12low</subscript></entry>
- <entry>Y'<subscript>12high</subscript></entry>
- <entry>Y'<subscript>13low</subscript></entry>
- <entry>Y'<subscript>13high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Y'<subscript>20low</subscript></entry>
- <entry>Y'<subscript>20high</subscript></entry>
- <entry>Y'<subscript>21low</subscript></entry>
- <entry>Y'<subscript>21high</subscript></entry>
- <entry>Y'<subscript>22low</subscript></entry>
- <entry>Y'<subscript>22high</subscript></entry>
- <entry>Y'<subscript>23low</subscript></entry>
- <entry>Y'<subscript>23high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Y'<subscript>30low</subscript></entry>
- <entry>Y'<subscript>30high</subscript></entry>
- <entry>Y'<subscript>31low</subscript></entry>
- <entry>Y'<subscript>31high</subscript></entry>
- <entry>Y'<subscript>32low</subscript></entry>
- <entry>Y'<subscript>32high</subscript></entry>
- <entry>Y'<subscript>33low</subscript></entry>
- <entry>Y'<subscript>33high</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y16.xml b/Documentation/DocBook/media/v4l/pixfmt-y16.xml
deleted file mode 100644
index ff4f727d5624..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-y16.xml
+++ /dev/null
@@ -1,81 +0,0 @@
-<refentry id="V4L2-PIX-FMT-Y16">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_Y16 ('Y16 ')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_Y16</constant></refname>
- <refpurpose>Grey-scale image</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This is a grey-scale image with a depth of 16 bits per
-pixel. The least significant byte is stored at lower memory addresses
-(little-endian). Note the actual sampling precision may be lower than
-16 bits, for example 10 bits per pixel with values in range 0 to
-1023.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_Y16</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00low</subscript></entry>
- <entry>Y'<subscript>00high</subscript></entry>
- <entry>Y'<subscript>01low</subscript></entry>
- <entry>Y'<subscript>01high</subscript></entry>
- <entry>Y'<subscript>02low</subscript></entry>
- <entry>Y'<subscript>02high</subscript></entry>
- <entry>Y'<subscript>03low</subscript></entry>
- <entry>Y'<subscript>03high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>10low</subscript></entry>
- <entry>Y'<subscript>10high</subscript></entry>
- <entry>Y'<subscript>11low</subscript></entry>
- <entry>Y'<subscript>11high</subscript></entry>
- <entry>Y'<subscript>12low</subscript></entry>
- <entry>Y'<subscript>12high</subscript></entry>
- <entry>Y'<subscript>13low</subscript></entry>
- <entry>Y'<subscript>13high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Y'<subscript>20low</subscript></entry>
- <entry>Y'<subscript>20high</subscript></entry>
- <entry>Y'<subscript>21low</subscript></entry>
- <entry>Y'<subscript>21high</subscript></entry>
- <entry>Y'<subscript>22low</subscript></entry>
- <entry>Y'<subscript>22high</subscript></entry>
- <entry>Y'<subscript>23low</subscript></entry>
- <entry>Y'<subscript>23high</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Y'<subscript>30low</subscript></entry>
- <entry>Y'<subscript>30high</subscript></entry>
- <entry>Y'<subscript>31low</subscript></entry>
- <entry>Y'<subscript>31high</subscript></entry>
- <entry>Y'<subscript>32low</subscript></entry>
- <entry>Y'<subscript>32high</subscript></entry>
- <entry>Y'<subscript>33low</subscript></entry>
- <entry>Y'<subscript>33high</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml b/Documentation/DocBook/media/v4l/pixfmt-y41p.xml
deleted file mode 100644
index 98dcb91d2917..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml
+++ /dev/null
@@ -1,149 +0,0 @@
- <refentry id="V4L2-PIX-FMT-Y41P">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_Y41P ('Y41P')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_Y41P</constant></refname>
- <refpurpose>Format with &frac14; horizontal chroma
-resolution, also known as YUV 4:1:1</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>In this format each 12 bytes is eight pixels. In the
-twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair
-goes with the first four Y's, and the second CbCr pair goes with the
-other four Y's. The Cb and Cr components have one fourth the
-horizontal resolution of the Y component.</para>
-
- <para>Do not confuse this format with <link
-linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>.
-Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while
-YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_Y41P</constant> 8 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="13" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- <entry>Y'<subscript>04</subscript></entry>
- <entry>Y'<subscript>05</subscript></entry>
- <entry>Y'<subscript>06</subscript></entry>
- <entry>Y'<subscript>07</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- <entry>Y'<subscript>14</subscript></entry>
- <entry>Y'<subscript>15</subscript></entry>
- <entry>Y'<subscript>16</subscript></entry>
- <entry>Y'<subscript>17</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- <entry>Y'<subscript>24</subscript></entry>
- <entry>Y'<subscript>25</subscript></entry>
- <entry>Y'<subscript>26</subscript></entry>
- <entry>Y'<subscript>27</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;36:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- <entry>Y'<subscript>34</subscript></entry>
- <entry>Y'<subscript>35</subscript></entry>
- <entry>Y'<subscript>36</subscript></entry>
- <entry>Y'<subscript>37</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="15" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry><entry></entry>
- <entry>4</entry><entry></entry><entry>5</entry><entry></entry>
- <entry>6</entry><entry></entry><entry>7</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml
deleted file mode 100644
index 0869dce5f92c..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml
+++ /dev/null
@@ -1,133 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></refname>
- <refname id="V4L2-PIX-FMT-YUV410"><constant>V4L2_PIX_FMT_YUV410</constant></refname>
- <refpurpose>Planar formats with &frac14; horizontal and
-vertical chroma resolution, also known as YUV 4:1:0</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These are planar formats, as opposed to a packed format.
-The three components are separated into three sub-images or planes.
-The Y plane is first. The Y plane has one byte per pixel. For
-<constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately
-follows the Y plane in memory. The Cr plane is &frac14; the width and
-&frac14; the height of the Y plane (and of the image). Each Cr belongs
-to 16 pixels, a four-by-four square of the image. Following the Cr
-plane is the Cb plane, just like the Cr plane.
-<constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb
-plane comes first, then the Cr plane.</para>
-
- <para>If the Y plane has pad bytes after each row, then the Cr
-and Cb planes have &frac14; as many pad bytes after their rows. In
-other words, four Cx rows (including padding) are exactly as long as
-one Y row (including padding).</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YVU410</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;17:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry></entry><entry></entry><entry>C</entry>
- <entry></entry><entry></entry><entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml
deleted file mode 100644
index 086dc731bf02..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml
+++ /dev/null
@@ -1,147 +0,0 @@
- <refentry id="V4L2-PIX-FMT-YUV411P">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YUV411P ('411P')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_YUV411P</constant></refname>
- <refpurpose>Format with &frac14; horizontal chroma resolution,
-also known as YUV 4:1:1. Planar layout as opposed to
-<constant>V4L2_PIX_FMT_Y41P</constant></refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This format is not commonly used. This is a planar
-format similar to the 4:2:2 planar format except with half as many
-chroma. The three components are separated into three sub-images or
-planes. The Y plane is first. The Y plane has one byte per pixel. The
-Cb plane immediately follows the Y plane in memory. The Cb plane is
-&frac14; the width of the Y plane (and of the image). Each Cb belongs
-to 4 pixels all on the same row. For example,
-Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
-Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and
-Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane,
-just like the Cb plane.</para>
-
- <para>If the Y plane has pad bytes after each row, then the Cr
-and Cb planes have &frac14; as many pad bytes after their rows. In
-other words, four C x rows (including padding) is exactly as long as
-one Y row (including padding).</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;17:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;18:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;19:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;20:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;21:</entry>
- <entry>Cr<subscript>10</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;22:</entry>
- <entry>Cr<subscript>20</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;23:</entry>
- <entry>Cr<subscript>30</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml
deleted file mode 100644
index 48649fac1596..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml
+++ /dev/null
@@ -1,149 +0,0 @@
- <refentry>
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname id="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></refname>
- <refname id="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></refname>
- <refpurpose>Planar formats with &frac12; horizontal and
-vertical chroma resolution, also known as YUV 4:2:0</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>These are planar formats, as opposed to a packed format.
-The three components are separated into three sub- images or planes.
-The Y plane is first. The Y plane has one byte per pixel. For
-<constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately
-follows the Y plane in memory. The Cr plane is half the width and half
-the height of the Y plane (and of the image). Each Cr belongs to four
-pixels, a two-by-two square of the image. For example,
-Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
-Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
-Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane,
-just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is
-the same except the Cb plane comes first, then the Cr plane.</para>
-
- <para>If the Y plane has pad bytes after each row, then the Cr
-and Cb planes have half as many pad bytes after their rows. In other
-words, two Cx rows (including padding) is exactly as long as one Y row
-(including padding).</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YVU420</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;18:</entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;20:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;22:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml
deleted file mode 100644
index e781cc61786c..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml
+++ /dev/null
@@ -1,154 +0,0 @@
- <refentry id="V4L2-PIX-FMT-YUV420M">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YUV420M ('YM12')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname>
- <refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant>
- with planes non contiguous in memory. </refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Description</title>
-
- <para>This is a multi-planar format, as opposed to a packed format.
-The three components are separated into three sub- images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. The Cb data
-constitutes the second plane which is half the width and half
-the height of the Y plane (and of the image). Each Cb belongs to four
-pixels, a two-by-two square of the image. For example,
-Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
-Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
-Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is
-in the third plane. </para>
-
- <para>If the Y plane has pad bytes after each row, then the Cb
-and Cr planes have half as many pad bytes after their rows. In other
-words, two Cx rows (including padding) is exactly as long as one Y row
-(including padding).</para>
-
- <para><constant>V4L2_PIX_FMT_YUV420M</constant> is intended to be
-used only in drivers and applications that support the multi-planar API,
-described in <xref linkend="planar-apis"/>. </para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YUV420M</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start0&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry>start1&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;2:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry>start2&nbsp;+&nbsp;0:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start2&nbsp;+&nbsp;2:</entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml
deleted file mode 100644
index 4ce6463fe0a5..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml
+++ /dev/null
@@ -1,153 +0,0 @@
- <refentry id="V4L2-PIX-FMT-YUV422P">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YUV422P ('422P')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_YUV422P</constant></refname>
- <refpurpose>Format with &frac12; horizontal chroma resolution,
-also known as YUV 4:2:2. Planar layout as opposed to
-<constant>V4L2_PIX_FMT_YUYV</constant></refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>This format is not commonly used. This is a planar
-version of the YUYV format. The three components are separated into
-three sub-images or planes. The Y plane is first. The Y plane has one
-byte per pixel. The Cb plane immediately follows the Y plane in
-memory. The Cb plane is half the width of the Y plane (and of the
-image). Each Cb belongs to two pixels. For example,
-Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
-Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane,
-just like the Cb plane.</para>
-
- <para>If the Y plane has pad bytes after each row, then the Cr
-and Cb planes have half as many pad bytes after their rows. In other
-words, two Cx rows (including padding) is exactly as long as one Y row
-(including padding).</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YUV422P</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;18:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;20:</entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;22:</entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;26:</entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;28:</entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;30:</entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml
deleted file mode 100644
index 58384092251a..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml
+++ /dev/null
@@ -1,120 +0,0 @@
- <refentry id="V4L2-PIX-FMT-YUYV">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YUYV ('YUYV')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_YUYV</constant></refname>
- <refpurpose>Packed format with &frac12; horizontal chroma
-resolution, also known as YUV 4:2:2</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>In this format each four bytes is two pixels. Each four
-bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
-the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
-components have half the horizontal resolution of the Y component.
-<constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows
-environment as YUY2.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YUYV</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml
deleted file mode 100644
index 2330667907c7..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml
+++ /dev/null
@@ -1,154 +0,0 @@
- <refentry id="V4L2-PIX-FMT-YVU420M">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YVU420M ('YM21')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname> <constant>V4L2_PIX_FMT_YVU420M</constant></refname>
- <refpurpose>Variation of <constant>V4L2_PIX_FMT_YVU420</constant>
- with planes non contiguous in memory. </refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Description</title>
-
- <para>This is a multi-planar format, as opposed to a packed format.
-The three components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. The Cr data
-constitutes the second plane which is half the width and half
-the height of the Y plane (and of the image). Each Cr belongs to four
-pixels, a two-by-two square of the image. For example,
-Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
-Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
-Y'<subscript>11</subscript>. The Cb data, just like the Cr plane, constitutes
-the third plane. </para>
-
- <para>If the Y plane has pad bytes after each row, then the Cr
-and Cb planes have half as many pad bytes after their rows. In other
-words, two Cx rows (including padding) is exactly as long as one Y row
-(including padding).</para>
-
- <para><constant>V4L2_PIX_FMT_YVU420M</constant> is intended to be
-used only in drivers and applications that support the multi-planar API,
-described in <xref linkend="planar-apis"/>. </para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="5" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start0&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;4:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- </row>
- <row>
- <entry>start0&nbsp;+&nbsp;12:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry>start1&nbsp;+&nbsp;0:</entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start1&nbsp;+&nbsp;2:</entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry>start2&nbsp;+&nbsp;0:</entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start2&nbsp;+&nbsp;2:</entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry><entry>C</entry><entry></entry><entry></entry>
- <entry></entry><entry>C</entry><entry></entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry></entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml
deleted file mode 100644
index bfffdc76d3da..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml
+++ /dev/null
@@ -1,120 +0,0 @@
- <refentry id="V4L2-PIX-FMT-YVYU">
- <refmeta>
- <refentrytitle>V4L2_PIX_FMT_YVYU ('YVYU')</refentrytitle>
- &manvol;
- </refmeta>
- <refnamediv>
- <refname><constant>V4L2_PIX_FMT_YVYU</constant></refname>
- <refpurpose>Variation of
-<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
-in memory</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
-
- <para>In this format each four bytes is two pixels. Each four
-bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
-the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
-components have half the horizontal resolution of the Y
-component.</para>
-
- <example>
- <title><constant>V4L2_PIX_FMT_YVYU</constant> 4 &times; 4
-pixel image</title>
-
- <formalpara>
- <title>Byte Order.</title>
- <para>Each cell is one byte.
- <informaltable frame="none">
- <tgroup cols="9" align="center">
- <colspec align="left" colwidth="2*" />
- <tbody valign="top">
- <row>
- <entry>start&nbsp;+&nbsp;0:</entry>
- <entry>Y'<subscript>00</subscript></entry>
- <entry>Cr<subscript>00</subscript></entry>
- <entry>Y'<subscript>01</subscript></entry>
- <entry>Cb<subscript>00</subscript></entry>
- <entry>Y'<subscript>02</subscript></entry>
- <entry>Cr<subscript>01</subscript></entry>
- <entry>Y'<subscript>03</subscript></entry>
- <entry>Cb<subscript>01</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;8:</entry>
- <entry>Y'<subscript>10</subscript></entry>
- <entry>Cr<subscript>10</subscript></entry>
- <entry>Y'<subscript>11</subscript></entry>
- <entry>Cb<subscript>10</subscript></entry>
- <entry>Y'<subscript>12</subscript></entry>
- <entry>Cr<subscript>11</subscript></entry>
- <entry>Y'<subscript>13</subscript></entry>
- <entry>Cb<subscript>11</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;16:</entry>
- <entry>Y'<subscript>20</subscript></entry>
- <entry>Cr<subscript>20</subscript></entry>
- <entry>Y'<subscript>21</subscript></entry>
- <entry>Cb<subscript>20</subscript></entry>
- <entry>Y'<subscript>22</subscript></entry>
- <entry>Cr<subscript>21</subscript></entry>
- <entry>Y'<subscript>23</subscript></entry>
- <entry>Cb<subscript>21</subscript></entry>
- </row>
- <row>
- <entry>start&nbsp;+&nbsp;24:</entry>
- <entry>Y'<subscript>30</subscript></entry>
- <entry>Cr<subscript>30</subscript></entry>
- <entry>Y'<subscript>31</subscript></entry>
- <entry>Cb<subscript>30</subscript></entry>
- <entry>Y'<subscript>32</subscript></entry>
- <entry>Cr<subscript>31</subscript></entry>
- <entry>Y'<subscript>33</subscript></entry>
- <entry>Cb<subscript>31</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
-
- <formalpara>
- <title>Color Sample Location.</title>
- <para>
- <informaltable frame="none">
- <tgroup cols="7" align="center">
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
- <entry>2</entry><entry></entry><entry>3</entry>
- </row>
- <row>
- <entry>0</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>2</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- <row>
- <entry>3</entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
- <entry>Y</entry><entry>C</entry><entry>Y</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </formalpara>
- </example>
- </refsect1>
- </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml
deleted file mode 100644
index fcde4e20205e..000000000000
--- a/Documentation/DocBook/media/v4l/pixfmt.xml
+++ /dev/null
@@ -1,1801 +0,0 @@
- <title>Image Formats</title>
-
- <para>The V4L2 API was primarily designed for devices exchanging
-image data with applications. The
-<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane
-</structname> structures define the format and layout of an image in memory.
-The former is used with the single-planar API, while the latter is used with the
-multi-planar version (see <xref linkend="planar-apis"/>). Image formats are
-negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
-capturing and output, for overlay frame buffer formats see also
-&VIDIOC-G-FBUF;.)</para>
-
-<section>
- <title>Single-planar format structure</title>
- <table pgwide="1" frame="none" id="v4l2-pix-format">
- <title>struct <structname>v4l2_pix_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Image width in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Image height in pixels. If <structfield>field</structfield> is
- one of <constant>V4L2_FIELD_TOP</constant>, <constant>V4L2_FIELD_BOTTOM</constant>
- or <constant>V4L2_FIELD_ALTERNATE</constant> then height refers to the
- number of lines in the field, otherwise it refers to the number of
- lines in the frame (which is twice the field height for interlaced
- formats).</entry>
- </row>
- <row>
- <entry spanname="hspan">Applications set these fields to
-request an image size, drivers return the closest possible values. In
-case of planar formats the <structfield>width</structfield> and
-<structfield>height</structfield> applies to the largest plane. To
-avoid ambiguities drivers must return values rounded up to a multiple
-of the scale factor of any smaller planes. For example when the image
-format is YUV 4:2:0, <structfield>width</structfield> and
-<structfield>height</structfield> must be multiples of two.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>The pixel format or type of compression, set by the
-application. This is a little endian <link
-linkend="v4l2-fourcc">four character code</link>. V4L2 defines
-standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
-linkend="yuv-formats" />, and reserved codes in <xref
-linkend="reserved-formats" /></entry>
- </row>
- <row>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>Video images are typically interlaced. Applications
-can request to capture or output only the top or bottom field, or both
-fields interlaced or sequentially stored in one buffer or alternating
-in separate buffers. Drivers return the actual field order selected.
-For more details on fields see <xref linkend="field-order" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>bytesperline</structfield></entry>
- <entry>Distance in bytes between the leftmost pixels in two
-adjacent lines.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>Both applications and drivers
-can set this field to request padding bytes at the end of each line.
-Drivers however may ignore the value requested by the application,
-returning <structfield>width</structfield> times bytes per pixel or a
-larger value required by the hardware. That implies applications can
-just set this field to zero to get a reasonable
-default.</para><para>Video hardware may access padding bytes,
-therefore they must reside in accessible memory. Consider cases where
-padding bytes after the last line of an image cross a system page
-boundary. Input devices may write padding bytes, the value is
-undefined. Output devices ignore the contents of padding
-bytes.</para><para>When the image format is planar the
-<structfield>bytesperline</structfield> value applies to the first
-plane and is divided by the same factor as the
-<structfield>width</structfield> field for the other planes. For
-example the Cb and Cr planes of a YUV 4:2:0 image have half as many
-padding bytes following each line as the Y plane. To avoid ambiguities
-drivers must return a <structfield>bytesperline</structfield> value
-rounded up to a multiple of the scale factor.</para>
-<para>For compressed formats the <structfield>bytesperline</structfield>
-value makes no sense. Applications and drivers must set this to 0 in
-that case.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>sizeimage</structfield></entry>
- <entry>Size in bytes of the buffer to hold a complete image,
-set by the driver. Usually this is
-<structfield>bytesperline</structfield> times
-<structfield>height</structfield>. When the image consists of variable
-length compressed data this is the maximum number of bytes required to
-hold an image.</entry>
- </row>
- <row>
- <entry>&v4l2-colorspace;</entry>
- <entry><structfield>colorspace</structfield></entry>
- <entry>This information supplements the
-<structfield>pixelformat</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>priv</structfield></entry>
- <entry><para>This field indicates whether the remaining fields of the
-<structname>v4l2_pix_format</structname> structure, also called the extended
-fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it
-indicates that the extended fields have been correctly initialized. When set to
-any other value it indicates that the extended fields contain undefined values.
-</para>
-<para>Applications that wish to use the pixel format extended fields must first
-ensure that the feature is supported by querying the device for the
-<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link>
-capability. If the capability isn't set the pixel format extended fields are not
-supported and using the extended fields will lead to undefined results.</para>
-<para>To use the extended fields, applications must set the
-<structfield>priv</structfield> field to
-<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields
-and zero the unused bytes of the <structname>v4l2_format</structname>
-<structfield>raw_data</structfield> field.</para>
-<para>When the <structfield>priv</structfield> field isn't set to
-<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the
-extended fields were set to zero. On return drivers must set the
-<structfield>priv</structfield> field to
-<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to
-applicable values.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags set by the application or driver, see <xref
-linkend="format-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-ycbcr-encoding;</entry>
- <entry><structfield>ycbcr_enc</structfield></entry>
- <entry>This information supplements the
-<structfield>colorspace</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-quantization;</entry>
- <entry><structfield>quantization</structfield></entry>
- <entry>This information supplements the
-<structfield>colorspace</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-</section>
-
-<section>
- <title>Multi-planar format structures</title>
- <para>The <structname>v4l2_plane_pix_format</structname> structures define
- size and layout for each of the planes in a multi-planar format.
- The <structname>v4l2_pix_format_mplane</structname> structure contains
- information common to all planes (such as image width and height) and
- an array of <structname>v4l2_plane_pix_format</structname> structures,
- describing all planes of that format.</para>
- <table pgwide="1" frame="none" id="v4l2-plane-pix-format">
- <title>struct <structname>v4l2_plane_pix_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>sizeimage</structfield></entry>
- <entry>Maximum size in bytes required for image data in this plane.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>bytesperline</structfield></entry>
- <entry>Distance in bytes between the leftmost pixels in two adjacent
- lines. See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>reserved[6]</structfield></entry>
- <entry>Reserved for future extensions. Should be zeroed by the
- application.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="v4l2-pix-format-mplane">
- <title>struct <structname>v4l2_pix_format_mplane</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Image width in pixels. See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Image height in pixels. See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>The pixel format. Both single- and multi-planar four character
-codes can be used.</entry>
- </row>
- <row>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>&v4l2-colorspace;</entry>
- <entry><structfield>colorspace</structfield></entry>
- <entry>See &v4l2-pix-format;.</entry>
- </row>
- <row>
- <entry>&v4l2-plane-pix-format;</entry>
- <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry>
- <entry>An array of structures describing format of each plane this
- pixel format consists of. The number of valid entries in this array
- has to be put in the <structfield>num_planes</structfield>
- field.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>num_planes</structfield></entry>
- <entry>Number of planes (i.e. separate memory buffers) for this format
- and the number of valid entries in the
- <structfield>plane_fmt</structfield> array.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags set by the application or driver, see <xref
-linkend="format-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-ycbcr-encoding;</entry>
- <entry><structfield>ycbcr_enc</structfield></entry>
- <entry>This information supplements the
-<structfield>colorspace</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-quantization;</entry>
- <entry><structfield>quantization</structfield></entry>
- <entry>This information supplements the
-<structfield>colorspace</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>reserved[8]</structfield></entry>
- <entry>Reserved for future extensions. Should be zeroed by the
- application.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-</section>
-
- <section>
- <title>Standard Image Formats</title>
-
- <para>In order to exchange images between drivers and
-applications, it is necessary to have standard image data formats
-which both sides will interpret the same way. V4L2 includes several
-such formats, and this section is intended to be an unambiguous
-specification of the standard image data formats in V4L2.</para>
-
- <para>V4L2 drivers are not limited to these formats, however.
-Driver-specific formats are possible. In that case the application may
-depend on a codec to convert images to one of the standard formats
-when needed. But the data can still be stored and retrieved in the
-proprietary format. For example, a device may support a proprietary
-compressed format. Applications can still capture and save the data in
-the compressed format, saving much disk space, and later use a codec
-to convert the images to the X Windows screen format when the video is
-to be displayed.</para>
-
- <para>Even so, ultimately, some standard formats are needed, so
-the V4L2 specification would not be complete without well-defined
-standard formats.</para>
-
- <para>The V4L2 standard formats are mainly uncompressed formats. The
-pixels are always arranged in memory from left to right, and from top
-to bottom. The first byte of data in the image buffer is always for
-the leftmost pixel of the topmost row. Following that is the pixel
-immediately to its right, and so on until the end of the top row of
-pixels. Following the rightmost pixel of the row there may be zero or
-more bytes of padding to guarantee that each row of pixel data has a
-certain alignment. Following the pad bytes, if any, is data for the
-leftmost pixel of the second row from the top, and so on. The last row
-has just as many pad bytes after it as the other rows.</para>
-
- <para>In V4L2 each format has an identifier which looks like
-<constant>PIX_FMT_XXX</constant>, defined in the <link
-linkend="videodev">videodev2.h</link> header file. These identifiers
-represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
-which are also listed below, however they are not the same as those
-used in the Windows world.</para>
-
- <para>For some formats, data is stored in separate, discontiguous
-memory buffers. Those formats are identified by a separate set of FourCC codes
-and are referred to as "multi-planar formats". For example, a YUV422 frame is
-normally stored in one memory buffer, but it can also be placed in two or three
-separate buffers, with Y component in one buffer and CbCr components in another
-in the 2-planar version or with each component in its own buffer in the
-3-planar case. Those sub-buffers are referred to as "planes".</para>
- </section>
-
- <section id="colorspaces">
- <title>Colorspaces</title>
-
- <para>'Color' is a very complex concept and depends on physics, chemistry and
-biology. Just because you have three numbers that describe the 'red', 'green'
-and 'blue' components of the color of a pixel does not mean that you can accurately
-display that color. A colorspace defines what it actually <emphasis>means</emphasis>
-to have an RGB value of e.g. (255,&nbsp;0,&nbsp;0). That is, which color should be
-reproduced on the screen in a perfectly calibrated environment.</para>
-
- <para>In order to do that we first need to have a good definition of
-color, i.e. some way to uniquely and unambiguously define a color so that someone
-else can reproduce it. Human color vision is trichromatic since the human eye has
-color receptors that are sensitive to three different wavelengths of light. Hence
-the need to use three numbers to describe color. Be glad you are not a mantis shrimp
-as those are sensitive to 12 different wavelengths, so instead of RGB we would be
-using the ABCDEFGHIJKL colorspace...</para>
-
- <para>Color exists only in the eye and brain and is the result of how strongly
-color receptors are stimulated. This is based on the Spectral
-Power Distribution (SPD) which is a graph showing the intensity (radiant power)
-of the light at wavelengths covering the visible spectrum as it enters the eye.
-The science of colorimetry is about the relationship between the SPD and color as
-perceived by the human brain.</para>
-
- <para>Since the human eye has only three color receptors it is perfectly
-possible that different SPDs will result in the same stimulation of those receptors
-and are perceived as the same color, even though the SPD of the light is
-different.</para>
-
- <para>In the 1920s experiments were devised to determine the relationship
-between SPDs and the perceived color and that resulted in the CIE 1931 standard
-that defines spectral weighting functions that model the perception of color.
-Specifically that standard defines functions that can take an SPD and calculate
-the stimulus for each color receptor. After some further mathematical transforms
-these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values
-and these X, Y and Z values describe a color as perceived by a human unambiguously.
-These X, Y and Z values are all in the range [0&hellip;1].</para>
-
- <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often
-the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para>
-
- <para>x = X / (X + Y + Z)</para>
- <para>y = Y / (X + Y + Z)</para>
-
- <para>The x and y values are the chromaticity coordinates and can be used to
-define a color without the luminance component Y. It is very confusing to
-have such similar names for these colorspaces. Just be aware that if colors
-are specified with lower case 'x' and 'y', then the CIE xyY colorspace is
-used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing
-to do with luminance. Together x and y specify a color, and Y the luminance.
-That is really all you need to remember from a practical point of view. At
-the end of this section you will find reading resources that go into much more
-detail if you are interested.
-</para>
-
- <para>A monitor or TV will reproduce colors by emitting light at three
-different wavelengths, the combination of which will stimulate the color receptors
-in the eye and thus cause the perception of color. Historically these wavelengths
-were defined by the red, green and blue phosphors used in the displays. These
-<emphasis>color primaries</emphasis> are part of what defines a colorspace.</para>
-
- <para>Different display devices will have different primaries and some
-primaries are more suitable for some display technologies than others. This has
-resulted in a variety of colorspaces that are used for different display
-technologies or uses. To define a colorspace you need to define the three
-color primaries (these are typically defined as x,&nbsp;y chromaticity coordinates
-from the CIE xyY colorspace) but also the white reference: that is the color obtained
-when all three primaries are at maximum power. This determines the relative power
-or energy of the primaries. This is usually chosen to be close to daylight which has
-been defined as the CIE D65 Illuminant.</para>
-
- <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors.
-Other colorspaces are defined by three chromaticity coordinates defined in the
-CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that
-transforms CIE XYZ colors to colors in the new colorspace.
-</para>
-
- <para>Both the CIE XYZ and the RGB colorspace that are derived from the
-specific chromaticity primaries are linear colorspaces. But neither the eye,
-nor display technology is linear. Doubling the values of all components in
-the linear colorspace will not be perceived as twice the intensity of the color.
-So each colorspace also defines a transfer function that takes a linear color
-component value and transforms it to the non-linear component value, which is a
-closer match to the non-linear performance of both the eye and displays. Linear
-component values are denoted RGB, non-linear are denoted as R'G'B'. In general
-colors used in graphics are all R'G'B', except in openGL which uses linear RGB.
-Special care should be taken when dealing with openGL to provide linear RGB colors
-or to use the built-in openGL support to apply the inverse transfer function.</para>
-
- <para>The final piece that defines a colorspace is a function that
-transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined
-by the so-called luma coefficients. There may be multiple possible Y'CbCr
-encodings allowed for the same colorspace. Many encodings of color
-prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human
-eye is more sensitive to differences in luminance than in color this encoding
-allows one to reduce the amount of color information compared to the luma
-data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace.
-Also note that Y'CbCr is often called YCbCr or YUV even though these are
-strictly speaking wrong.</para>
-
- <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not
-correct, it is just an encoding of an R'G'B' color into luma and chroma
-values. The underlying colorspace that is associated with the R'G'B' color
-is also associated with the Y'CbCr color.</para>
-
- <para>The final step is how the RGB, R'G'B' or Y'CbCr values are
-quantized. The CIE XYZ colorspace where X, Y and Z are in the range
-[0&hellip;1] describes all colors that humans can perceive, but the transform to
-another colorspace will produce colors that are outside the [0&hellip;1] range.
-Once clamped to the [0&hellip;1] range those colors can no longer be reproduced
-in that colorspace. This clamping is what reduces the extent or gamut of the
-colorspace. How the range of [0&hellip;1] is translated to integer values in the
-range of [0&hellip;255] (or higher, depending on the color depth) is called the
-quantization. This is <emphasis>not</emphasis> part of the colorspace
-definition. In practice RGB or R'G'B' values are full range, i.e. they
-use the full [0&hellip;255] range. Y'CbCr values on the other hand are limited
-range with Y' using [16&hellip;235] and Cb and Cr using [16&hellip;240].</para>
-
- <para>Unfortunately, in some cases limited range RGB is also used
-where the components use the range [16&hellip;235]. And full range Y'CbCr also exists
-using the [0&hellip;255] range.</para>
-
- <para>In order to correctly interpret a color you need to know the
-quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding
-and the colorspace.
-From that information you can calculate the corresponding CIE XYZ color
-and map that again to whatever colorspace your display device uses.</para>
-
- <para>The colorspace definition itself consists of the three
-chromaticity primaries, the white reference chromaticity, a transfer
-function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While
-some colorspace standards correctly define all four, quite often the colorspace
-standard only defines some, and you have to rely on other standards for
-the missing pieces. The fact that colorspaces are often a mix of different
-standards also led to very confusing naming conventions where the name of
-a standard was used to name a colorspace when in fact that standard was
-part of various other colorspaces as well.</para>
-
- <para>If you want to read more about colors and colorspaces, then the
-following resources are useful: <xref linkend="poynton" /> is a good practical
-book for video engineers, <xref linkend="colimg" /> has a much broader scope and
-describes many more aspects of color (physics, chemistry, biology, etc.).
-The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink>
-website is an excellent resource, especially with respect to the mathematics behind
-colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article
-is also very useful.</para>
- </section>
-
- <section>
- <title>Defining Colorspaces in V4L2</title>
- <para>In V4L2 colorspaces are defined by three values. The first is the colorspace
-identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer
-function, the default Y'CbCr encoding and the default quantization method. The second
-is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard
-Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;)
-to specify non-standard quantization methods. Most of the time only the colorspace
-field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note
-that the default R'G'B' quantization is full range for all colorspaces except for
-BT.2020 which uses limited range R'G'B' quantization.</para>
-
- <table pgwide="1" frame="none" id="v4l2-colorspace">
- <title>V4L2 Colorspaces</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
- <entry>See <xref linkend="col-smpte-170m" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_REC709</constant></entry>
- <entry>See <xref linkend="col-rec709" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
- <entry>See <xref linkend="col-srgb" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry>
- <entry>See <xref linkend="col-adobergb" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry>
- <entry>See <xref linkend="col-bt2020" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry>
- <entry>See <xref linkend="col-smpte-240m" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry>
- <entry>See <xref linkend="col-sysm" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry>
- <entry>See <xref linkend="col-sysbg" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
- <entry>See <xref linkend="col-jpeg" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding">
- <title>V4L2 Y'CbCr Encodings</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry>
- <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_601</constant></entry>
- <entry>Use the BT.601 Y'CbCr encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_709</constant></entry>
- <entry>Use the Rec. 709 Y'CbCr encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry>
- <entry>Use the extended gamut xvYCC BT.601 encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry>
- <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry>
- <entry>Use the extended gamut sYCC encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry>
- <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry>
- <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-quantization">
- <title>V4L2 Quantization Methods</title>
- <tgroup cols="2" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry>
- <entry>Use the default quantization encoding as defined by the colorspace.
-This is always full range for R'G'B' (except for the BT.2020 colorspace) and usually
-limited range for Y'CbCr.</entry>
- </row>
- <row>
- <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry>
- <entry>Use the full range quantization encoding. I.e. the range [0&hellip;1]
-is mapped to [0&hellip;255] (with possible clipping to [1&hellip;254] to avoid the
-0x00 and 0xff values). Cb and Cr are mapped from [-0.5&hellip;0.5] to [0&hellip;255]
-(with possible clipping to [1&hellip;254] to avoid the 0x00 and 0xff values).</entry>
- </row>
- <row>
- <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry>
- <entry>Use the limited range quantization encoding. I.e. the range [0&hellip;1]
-is mapped to [16&hellip;235]. Cb and Cr are mapped from [-0.5&hellip;0.5] to [16&hellip;240].
-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Detailed Colorspace Descriptions</title>
- <section id="col-smpte-170m">
- <title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title>
- <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV
-in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>.
-The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and
-the white reference are:</para>
- <table frame="none">
- <title>SMPTE 170M Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.630</entry>
- <entry>0.340</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.310</entry>
- <entry>0.595</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.155</entry>
- <entry>0.070</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The red, green and blue chromaticities are also often referred to
-as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para>
- <variablelist>
- <varlistentry>
- <term>The transfer function defined for SMPTE 170M is the same as the
-one defined in Rec. 709.</term>
- <listitem>
- <para>L' = -1.099(-L)<superscript>0.45</superscript>&nbsp;+&nbsp;0.099&nbsp;for&nbsp;L&nbsp;&le;&nbsp;-0.018</para>
- <para>L' = 4.5L&nbsp;for&nbsp;-0.018&nbsp;&lt;&nbsp;L&nbsp;&lt;&nbsp;0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;L&nbsp;&ge;&nbsp;0.018</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = -((L'&nbsp;-&nbsp;0.099)&nbsp;/&nbsp;-1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&le;&nbsp;-0.081</para>
- <para>L = L'&nbsp;/&nbsp;4.5&nbsp;for&nbsp;-0.081&nbsp;&lt;&nbsp;L'&nbsp;&lt;&nbsp;0.081</para>
- <para>L = ((L'&nbsp;+&nbsp;0.099)&nbsp;/&nbsp;1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&ge;&nbsp;0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.299R'&nbsp;+&nbsp;0.587G'&nbsp;+&nbsp;0.114B'</para>
- <para>Cb&nbsp;=&nbsp;-0.169R'&nbsp;-&nbsp;0.331G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.419G'&nbsp;-&nbsp;0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are
-clamped to the range [-0.5&hellip;0.5]. This conversion to Y'CbCr is identical to the one
-defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even
-though BT.601 does not mention any color primaries.</para>
- <para>The default quantization is limited range, but full range is possible although
-rarely seen.</para>
- </section>
-
- <section id="col-rec709">
- <title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title>
- <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default
-Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is
-limited range. The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>Rec. 709 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.640</entry>
- <entry>0.330</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.300</entry>
- <entry>0.600</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.150</entry>
- <entry>0.060</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The full name of this standard is Rec. ITU-R BT.709-5.</para>
- <variablelist>
- <varlistentry>
- <term>Transfer function. Normally L is in the range [0&hellip;1], but for the extended
-gamut xvYCC encoding values outside that range are allowed.</term>
- <listitem>
- <para>L' = -1.099(-L)<superscript>0.45</superscript>&nbsp;+&nbsp;0.099&nbsp;for&nbsp;L&nbsp;&le;&nbsp;-0.018</para>
- <para>L' = 4.5L&nbsp;for&nbsp;-0.018&nbsp;&lt;&nbsp;L&nbsp;&lt;&nbsp;0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;L&nbsp;&ge;&nbsp;0.018</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = -((L'&nbsp;-&nbsp;0.099)&nbsp;/&nbsp;-1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&le;&nbsp;-0.081</para>
- <para>L = L'&nbsp;/&nbsp;4.5&nbsp;for&nbsp;-0.081&nbsp;&lt;&nbsp;L'&nbsp;&lt;&nbsp;0.081</para>
- <para>L = ((L'&nbsp;+&nbsp;0.099)&nbsp;/&nbsp;1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&ge;&nbsp;0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following
-<constant>V4L2_YCBCR_ENC_709</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.2126R'&nbsp;+&nbsp;0.7152G'&nbsp;+&nbsp;0.0722B'</para>
- <para>Cb&nbsp;=&nbsp;-0.1146R'&nbsp;-&nbsp;0.3854G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.4542G'&nbsp;-&nbsp;0.0458B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are
-clamped to the range [-0.5&hellip;0.5].</para>
- <para>The default quantization is limited range, but full range is possible although
-rarely seen.</para>
- <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default
-for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which
-case the BT.601 Y'CbCr encoding is used.</para>
- <para>Two additional extended gamut Y'CbCr encodings are also possible with this colorspace:</para>
- <variablelist>
- <varlistentry>
- <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />)
-is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range
-[0&hellip;1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;(219&nbsp;/&nbsp;256)&nbsp;*&nbsp;(0.2126R'&nbsp;+&nbsp;0.7152G'&nbsp;+&nbsp;0.0722B')&nbsp;+&nbsp;(16&nbsp;/&nbsp;256)</para>
- <para>Cb&nbsp;=&nbsp;(224&nbsp;/&nbsp;256)&nbsp;*&nbsp;(-0.1146R'&nbsp;-&nbsp;0.3854G'&nbsp;+&nbsp;0.5B')</para>
- <para>Cr&nbsp;=&nbsp;(224&nbsp;/&nbsp;256)&nbsp;*&nbsp;(0.5R'&nbsp;-&nbsp;0.4542G'&nbsp;-&nbsp;0.0458B')</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar
-to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range
-[0&hellip;1]. The resulting Y', Cb and Cr values are scaled and offset:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;(219&nbsp;/&nbsp;256)&nbsp;*&nbsp;(0.299R'&nbsp;+&nbsp;0.587G'&nbsp;+&nbsp;0.114B')&nbsp;+&nbsp;(16&nbsp;/&nbsp;256)</para>
- <para>Cb&nbsp;=&nbsp;(224&nbsp;/&nbsp;256)&nbsp;*&nbsp;(-0.169R'&nbsp;-&nbsp;0.331G'&nbsp;+&nbsp;0.5B')</para>
- <para>Cr&nbsp;=&nbsp;(224&nbsp;/&nbsp;256)&nbsp;*&nbsp;(0.5R'&nbsp;-&nbsp;0.419G'&nbsp;-&nbsp;0.081B')</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are clamped
-to the range [-0.5&hellip;0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be used by
-selecting <constant>V4L2_YCBCR_ENC_XV709</constant> or <constant>V4L2_YCBCR_ENC_XV601</constant>.
-The xvYCC encodings always use full range quantization.</para>
- </section>
-
- <section id="col-srgb">
- <title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title>
- <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The
-default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization
-is full range. The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>sRGB Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.640</entry>
- <entry>0.330</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.300</entry>
- <entry>0.600</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.150</entry>
- <entry>0.060</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>These chromaticities are identical to the Rec. 709 colorspace.</para>
- <variablelist>
- <varlistentry>
- <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term>
- <listitem>
- <para>L' = -1.055(-L)<superscript>1/2.4</superscript>&nbsp;+&nbsp;0.055&nbsp;for&nbsp;L&nbsp;&lt;&nbsp;-0.0031308</para>
- <para>L' = 12.92L&nbsp;for&nbsp;-0.0031308&nbsp;&le;&nbsp;L&nbsp;&le;&nbsp;0.0031308</para>
- <para>L' = 1.055L<superscript>1/2.4</superscript>&nbsp;-&nbsp;0.055&nbsp;for&nbsp;0.0031308&nbsp;&lt;&nbsp;L&nbsp;&le;&nbsp;1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = -((-L'&nbsp;+&nbsp;0.055)&nbsp;/&nbsp;1.055)<superscript>2.4</superscript>&nbsp;for&nbsp;L'&nbsp;&lt;&nbsp;-0.04045</para>
- <para>L = L'&nbsp;/&nbsp;12.92&nbsp;for&nbsp;-0.04045&nbsp;&le;&nbsp;L'&nbsp;&le;&nbsp;0.04045</para>
- <para>L = ((L'&nbsp;+&nbsp;0.055)&nbsp;/&nbsp;1.055)<superscript>2.4</superscript>&nbsp;for&nbsp;L'&nbsp;&gt;&nbsp;0.04045</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following
-<constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.2990R'&nbsp;+&nbsp;0.5870G'&nbsp;+&nbsp;0.1140B'</para>
- <para>Cb&nbsp;=&nbsp;-0.1687R'&nbsp;-&nbsp;0.3313G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.4187G'&nbsp;-&nbsp;0.0813B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are clamped
-to the range [-0.5&hellip;0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always
-full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant>
-encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr
-values before quantization, but this encoding does not do that.</para>
- </section>
-
- <section id="col-adobergb">
- <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title>
- <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics
-that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard.
-The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr
-quantization is limited range. The chromaticities of the primary colors and the white reference
-are:</para>
- <table frame="none">
- <title>Adobe RGB Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.6400</entry>
- <entry>0.3300</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.2100</entry>
- <entry>0.7100</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.1500</entry>
- <entry>0.0600</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>Transfer function:</term>
- <listitem>
- <para>L' = L<superscript>1/2.19921875</superscript></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'<superscript>2.19921875</superscript></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
-following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.299R'&nbsp;+&nbsp;0.587G'&nbsp;+&nbsp;0.114B'</para>
- <para>Cb&nbsp;=&nbsp;-0.169R'&nbsp;-&nbsp;0.331G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.419G'&nbsp;-&nbsp;0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are
-clamped to the range [-0.5&hellip;0.5]. This transform is identical to one defined in
-SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para>
- </section>
-
- <section id="col-bt2020">
- <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title>
- <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition
-television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>.
-The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization.
-The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>BT.2020 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.708</entry>
- <entry>0.292</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.170</entry>
- <entry>0.797</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.131</entry>
- <entry>0.046</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>Transfer function (same as Rec. 709):</term>
- <listitem>
- <para>L' = 4.5L&nbsp;for&nbsp;0&nbsp;&le;&nbsp;L&nbsp;&lt;&nbsp;0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&le;&nbsp;L&nbsp;&le;&nbsp;1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'&nbsp;/&nbsp;4.5&nbsp;for&nbsp;L'&nbsp;&lt;&nbsp;0.081</para>
- <para>L = ((L'&nbsp;+&nbsp;0.099)&nbsp;/&nbsp;1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&ge;&nbsp;0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
-following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.2627R'&nbsp;+&nbsp;0.6780G'&nbsp;+&nbsp;0.0593B'</para>
- <para>Cb&nbsp;=&nbsp;-0.1396R'&nbsp;-&nbsp;0.3604G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.4598G'&nbsp;-&nbsp;0.0402B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are
-clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range.</para>
- <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
-(<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para>
- <variablelist>
- <varlistentry>
- <term>Luma:</term>
- <listitem>
- <para>Yc'&nbsp;=&nbsp;(0.2627R&nbsp;+&nbsp;0.6780G&nbsp;+&nbsp;0.0593B)'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>B'&nbsp;-&nbsp;Yc'&nbsp;&le;&nbsp;0:</term>
- <listitem>
- <para>Cbc&nbsp;=&nbsp;(B'&nbsp;-&nbsp;Yc')&nbsp;/&nbsp;1.9404</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>B'&nbsp;-&nbsp;Yc'&nbsp;&gt;&nbsp;0:</term>
- <listitem>
- <para>Cbc&nbsp;=&nbsp;(B'&nbsp;-&nbsp;Yc')&nbsp;/&nbsp;1.5816</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>R'&nbsp;-&nbsp;Yc'&nbsp;&le;&nbsp;0:</term>
- <listitem>
- <para>Crc&nbsp;=&nbsp;(R'&nbsp;-&nbsp;Y')&nbsp;/&nbsp;1.7184</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>R'&nbsp;-&nbsp;Yc'&nbsp;&gt;&nbsp;0:</term>
- <listitem>
- <para>Crc&nbsp;=&nbsp;(R'&nbsp;-&nbsp;Y')&nbsp;/&nbsp;0.9936</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Yc' is clamped to the range [0&hellip;1] and Cbc and Crc are
-clamped to the range [-0.5&hellip;0.5]. The Yc'CbcCrc quantization is limited range.</para>
- </section>
-
- <section id="col-smpte-240m">
- <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title>
- <para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998).
-It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>.
-The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the
-white reference are:</para>
- <table frame="none">
- <title>SMPTE 240M Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.630</entry>
- <entry>0.340</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.310</entry>
- <entry>0.595</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.155</entry>
- <entry>0.070</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>These chromaticities are identical to the SMPTE 170M colorspace.</para>
- <variablelist>
- <varlistentry>
- <term>Transfer function:</term>
- <listitem>
- <para>L' = 4L&nbsp;for&nbsp;0&nbsp;&le;&nbsp;L&nbsp;&lt;&nbsp;0.0228</para>
- <para>L' = 1.1115L<superscript>0.45</superscript>&nbsp;-&nbsp;0.1115&nbsp;for&nbsp;0.0228&nbsp;&le;&nbsp;L&nbsp;&le;&nbsp;1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'&nbsp;/&nbsp;4&nbsp;for&nbsp;0&nbsp;&le;&nbsp;L'&nbsp;&lt;&nbsp;0.0913</para>
- <para>L = ((L'&nbsp;+&nbsp;0.1115)&nbsp;/&nbsp;1.1115)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&ge;&nbsp;0.0913</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
-following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.2122R'&nbsp;+&nbsp;0.7013G'&nbsp;+&nbsp;0.0865B'</para>
- <para>Cb&nbsp;=&nbsp;-0.1161R'&nbsp;-&nbsp;0.3839G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.4451G'&nbsp;-&nbsp;0.0549B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Yc' is clamped to the range [0&hellip;1] and Cbc and Crc are
-clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range.</para>
- </section>
-
- <section id="col-sysm">
- <title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title>
- <para>This standard defines the colorspace used by NTSC in 1953. In practice this
-colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding
-is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range.
-The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>NTSC 1953 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.67</entry>
- <entry>0.33</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.21</entry>
- <entry>0.71</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.14</entry>
- <entry>0.08</entry>
- </row>
- <row>
- <entry>White Reference (C)</entry>
- <entry>0.310</entry>
- <entry>0.316</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>Note that this colorspace uses Illuminant C instead of D65 as the
-white reference. To correctly convert an image in this colorspace to another
-that uses D65 you need to apply a chromatic adaptation algorithm such as the
-Bradford method.</para>
- <variablelist>
- <varlistentry>
- <term>The transfer function was never properly defined for NTSC 1953. The
-Rec. 709 transfer function is recommended in the literature:</term>
- <listitem>
- <para>L' = 4.5L&nbsp;for&nbsp;0&nbsp;&le;&nbsp;L&nbsp;&lt;&nbsp;0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&le;&nbsp;L&nbsp;&le;&nbsp;1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'&nbsp;/&nbsp;4.5&nbsp;for&nbsp;L'&nbsp;&lt;&nbsp;0.081</para>
- <para>L = ((L'&nbsp;+&nbsp;0.099)&nbsp;/&nbsp;1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&ge;&nbsp;0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
-following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.299R'&nbsp;+&nbsp;0.587G'&nbsp;+&nbsp;0.114B'</para>
- <para>Cb&nbsp;=&nbsp;-0.169R'&nbsp;-&nbsp;0.331G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.419G'&nbsp;-&nbsp;0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are
-clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range.
-This transform is identical to one defined in SMPTE 170M/BT.601.</para>
- </section>
-
- <section id="col-sysbg">
- <title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title>
- <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this
-colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding
-is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range.
-The chromaticities of the primary colors and the white reference are:</para>
- <table frame="none">
- <title>EBU Tech. 3213 Chromaticities</title>
- <tgroup cols="3" align="left">
- &cs-str;
- <thead>
- <row>
- <entry>Color</entry>
- <entry>x</entry>
- <entry>y</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Red</entry>
- <entry>0.64</entry>
- <entry>0.33</entry>
- </row>
- <row>
- <entry>Green</entry>
- <entry>0.29</entry>
- <entry>0.60</entry>
- </row>
- <row>
- <entry>Blue</entry>
- <entry>0.15</entry>
- <entry>0.06</entry>
- </row>
- <row>
- <entry>White Reference (D65)</entry>
- <entry>0.3127</entry>
- <entry>0.3290</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term>The transfer function was never properly defined for this colorspace.
-The Rec. 709 transfer function is recommended in the literature:</term>
- <listitem>
- <para>L' = 4.5L&nbsp;for&nbsp;0&nbsp;&le;&nbsp;L&nbsp;&lt;&nbsp;0.018</para>
- <para>L' = 1.099L<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&le;&nbsp;L&nbsp;&le;&nbsp;1</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Inverse Transfer function:</term>
- <listitem>
- <para>L = L'&nbsp;/&nbsp;4.5&nbsp;for&nbsp;L'&nbsp;&lt;&nbsp;0.081</para>
- <para>L = ((L'&nbsp;+&nbsp;0.099)&nbsp;/&nbsp;1.099)<superscript>1/0.45</superscript>&nbsp;for&nbsp;L'&nbsp;&ge;&nbsp;0.081</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the
-following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term>
- <listitem>
- <para>Y'&nbsp;=&nbsp;0.299R'&nbsp;+&nbsp;0.587G'&nbsp;+&nbsp;0.114B'</para>
- <para>Cb&nbsp;=&nbsp;-0.169R'&nbsp;-&nbsp;0.331G'&nbsp;+&nbsp;0.5B'</para>
- <para>Cr&nbsp;=&nbsp;0.5R'&nbsp;-&nbsp;0.419G'&nbsp;-&nbsp;0.081B'</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Y' is clamped to the range [0&hellip;1] and Cb and Cr are
-clamped to the range [-0.5&hellip;0.5]. The Y'CbCr quantization is limited range.
-This transform is identical to one defined in SMPTE 170M/BT.601.</para>
- </section>
-
- <section id="col-jpeg">
- <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title>
- <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities
-of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is
-<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where
-Y' is scaled to [0&hellip;255] and Cb/Cr are scaled to [-128&hellip;128] and
-then clipped to [-128&hellip;127].</para>
- <para>Note that the JPEG standard does not actually store colorspace information.
-So if something other than sRGB is used, then the driver will have to set that information
-explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be
-an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant>
-and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para>
- </section>
-
- </section>
-
- <section id="pixfmt-indexed">
- <title>Indexed Format</title>
-
- <para>In this format each pixel is represented by an 8 bit index
-into a 256 entry ARGB palette. It is intended for <link
-linkend="osd">Video Output Overlays</link> only. There are no ioctls to
-access the palette, this must be done with ioctls of the Linux framebuffer API.</para>
-
- <table pgwide="0" frame="none">
- <title>Indexed Image Format</title>
- <tgroup cols="37" align="center">
- <colspec colname="id" align="left" />
- <colspec colname="fourcc" />
- <colspec colname="bit" />
-
- <colspec colnum="4" colname="b07" align="center" />
- <colspec colnum="5" colname="b06" align="center" />
- <colspec colnum="6" colname="b05" align="center" />
- <colspec colnum="7" colname="b04" align="center" />
- <colspec colnum="8" colname="b03" align="center" />
- <colspec colnum="9" colname="b02" align="center" />
- <colspec colnum="10" colname="b01" align="center" />
- <colspec colnum="11" colname="b00" align="center" />
-
- <spanspec namest="b07" nameend="b00" spanname="b0" />
- <spanspec namest="b17" nameend="b10" spanname="b1" />
- <spanspec namest="b27" nameend="b20" spanname="b2" />
- <spanspec namest="b37" nameend="b30" spanname="b3" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>&nbsp;</entry>
- <entry spanname="b0">Byte&nbsp;0</entry>
- </row>
- <row>
- <entry>&nbsp;</entry>
- <entry>&nbsp;</entry>
- <entry>Bit</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-PAL8">
- <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry>
- <entry>'PAL8'</entry>
- <entry></entry>
- <entry>i<subscript>7</subscript></entry>
- <entry>i<subscript>6</subscript></entry>
- <entry>i<subscript>5</subscript></entry>
- <entry>i<subscript>4</subscript></entry>
- <entry>i<subscript>3</subscript></entry>
- <entry>i<subscript>2</subscript></entry>
- <entry>i<subscript>1</subscript></entry>
- <entry>i<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="pixfmt-rgb">
- <title>RGB Formats</title>
-
- &sub-packed-rgb;
- &sub-sbggr8;
- &sub-sgbrg8;
- &sub-sgrbg8;
- &sub-srggb8;
- &sub-sbggr16;
- &sub-srggb10;
- &sub-srggb10p;
- &sub-srggb10alaw8;
- &sub-srggb10dpcm8;
- &sub-srggb12;
- </section>
-
- <section id="yuv-formats">
- <title>YUV Formats</title>
-
- <para>YUV is the format native to TV broadcast and composite video
-signals. It separates the brightness information (Y) from the color
-information (U and V or Cb and Cr). The color information consists of
-red and blue <emphasis>color difference</emphasis> signals, this way
-the green component can be reconstructed by subtracting from the
-brightness component. See <xref linkend="colorspaces" /> for conversion
-examples. YUV was chosen because early television would only transmit
-brightness information. To add color in a way compatible with existing
-receivers a new signal carrier was added to transmit the color
-difference signals. Secondary in the YUV format the U and V components
-usually have lower resolution than the Y component. This is an analog
-video compression technique taking advantage of a property of the
-human visual system, being more sensitive to brightness
-information.</para>
-
- &sub-packed-yuv;
- &sub-grey;
- &sub-y10;
- &sub-y12;
- &sub-y10b;
- &sub-y16;
- &sub-uv8;
- &sub-yuyv;
- &sub-uyvy;
- &sub-yvyu;
- &sub-vyuy;
- &sub-y41p;
- &sub-yuv420;
- &sub-yuv420m;
- &sub-yvu420m;
- &sub-yuv410;
- &sub-yuv422p;
- &sub-yuv411p;
- &sub-nv12;
- &sub-nv12m;
- &sub-nv12mt;
- &sub-nv16;
- &sub-nv16m;
- &sub-nv24;
- &sub-m420;
- </section>
-
- <section>
- <title>Compressed Formats</title>
-
- <table pgwide="1" frame="none" id="compressed-formats">
- <title>Compressed Image Formats</title>
- <tgroup cols="3" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-JPEG">
- <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry>
- <entry>'JPEG'</entry>
- <entry>TBD. See also &VIDIOC-G-JPEGCOMP;,
- &VIDIOC-S-JPEGCOMP;.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG">
- <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry>
- <entry>'MPEG'</entry>
- <entry>MPEG multiplexed stream. The actual format is determined by
-extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
-<xref linkend="mpeg-control-id" />.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H264">
- <entry><constant>V4L2_PIX_FMT_H264</constant></entry>
- <entry>'H264'</entry>
- <entry>H264 video elementary stream with start codes.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H264-NO-SC">
- <entry><constant>V4L2_PIX_FMT_H264_NO_SC</constant></entry>
- <entry>'AVC1'</entry>
- <entry>H264 video elementary stream without start codes.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H264-MVC">
- <entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry>
- <entry>'M264'</entry>
- <entry>H264 MVC video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-H263">
- <entry><constant>V4L2_PIX_FMT_H263</constant></entry>
- <entry>'H263'</entry>
- <entry>H263 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG1">
- <entry><constant>V4L2_PIX_FMT_MPEG1</constant></entry>
- <entry>'MPG1'</entry>
- <entry>MPEG1 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG2">
- <entry><constant>V4L2_PIX_FMT_MPEG2</constant></entry>
- <entry>'MPG2'</entry>
- <entry>MPEG2 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MPEG4">
- <entry><constant>V4L2_PIX_FMT_MPEG4</constant></entry>
- <entry>'MPG4'</entry>
- <entry>MPEG4 video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-XVID">
- <entry><constant>V4L2_PIX_FMT_XVID</constant></entry>
- <entry>'XVID'</entry>
- <entry>Xvid video elementary stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-VC1-ANNEX-G">
- <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_G</constant></entry>
- <entry>'VC1G'</entry>
- <entry>VC1, SMPTE 421M Annex G compliant stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-VC1-ANNEX-L">
- <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_L</constant></entry>
- <entry>'VC1L'</entry>
- <entry>VC1, SMPTE 421M Annex L compliant stream.</entry>
- </row>
- <row id="V4L2-PIX-FMT-VP8">
- <entry><constant>V4L2_PIX_FMT_VP8</constant></entry>
- <entry>'VP80'</entry>
- <entry>VP8 video elementary stream.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="sdr-formats">
- <title>SDR Formats</title>
-
- <para>These formats are used for <link linkend="sdr">SDR Capture</link>
-interface only.</para>
-
- &sub-sdr-cu08;
- &sub-sdr-cu16le;
- &sub-sdr-cs08;
- &sub-sdr-cs14le;
- &sub-sdr-ru12le;
-
- </section>
-
- <section id="pixfmt-reserved">
- <title>Reserved Format Identifiers</title>
-
- <para>These formats are not defined by this specification, they
-are just listed for reference and to avoid naming conflicts. If you
-want to register your own format, send an e-mail to the linux-media mailing
-list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
-file. If you want to share your format with other developers add a
-link to your documentation and send a copy to the linux-media mailing list
-for inclusion in this section. If you think your format should be listed
-in a standard format section please make a proposal on the linux-media mailing
-list.</para>
-
- <table pgwide="1" frame="none" id="reserved-formats">
- <title>Reserved Image Formats</title>
- <tgroup cols="3" align="left">
- &cs-def;
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="V4L2-PIX-FMT-DV">
- <entry><constant>V4L2_PIX_FMT_DV</constant></entry>
- <entry>'dvsd'</entry>
- <entry>unknown</entry>
- </row>
- <row id="V4L2-PIX-FMT-ET61X251">
- <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry>
- <entry>'E625'</entry>
- <entry>Compressed format of the ET61X251 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-HI240">
- <entry><constant>V4L2_PIX_FMT_HI240</constant></entry>
- <entry>'HI24'</entry>
- <entry><para>8 bit RGB format used by the BTTV driver.</para></entry>
- </row>
- <row id="V4L2-PIX-FMT-HM12">
- <entry><constant>V4L2_PIX_FMT_HM12</constant></entry>
- <entry>'HM12'</entry>
- <entry><para>YUV 4:2:0 format used by the
-IVTV driver, <ulink url="http://www.ivtvdriver.org/">
-http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
-kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
-</para></entry>
- </row>
- <row id="V4L2-PIX-FMT-CPIA1">
- <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry>
- <entry>'CPIA'</entry>
- <entry>YUV format used by the gspca cpia1 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-JPGL">
- <entry><constant>V4L2_PIX_FMT_JPGL</constant></entry>
- <entry>'JPGL'</entry>
- <entry>JPEG-Light format (Pegasus Lossless JPEG)
- used in Divio webcams NW 80x.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA501">
- <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
- <entry>'S501'</entry>
- <entry>YUYV per line used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA505">
- <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry>
- <entry>'S505'</entry>
- <entry>YYUV per line used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA508">
- <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry>
- <entry>'S508'</entry>
- <entry>YUVY per line used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SPCA561">
- <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry>
- <entry>'S561'</entry>
- <entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-PAC207">
- <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry>
- <entry>'P207'</entry>
- <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MR97310A">
- <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry>
- <entry>'M310'</entry>
- <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-JL2005BCD">
- <entry><constant>V4L2_PIX_FMT_JL2005BCD</constant></entry>
- <entry>'JL20'</entry>
- <entry>JPEG compressed RGGB Bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-OV511">
- <entry><constant>V4L2_PIX_FMT_OV511</constant></entry>
- <entry>'O511'</entry>
- <entry>OV511 JPEG format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-OV518">
- <entry><constant>V4L2_PIX_FMT_OV518</constant></entry>
- <entry>'O518'</entry>
- <entry>OV518 JPEG format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-PJPG">
- <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry>
- <entry>'PJPG'</entry>
- <entry>Pixart 73xx JPEG format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SE401">
- <entry><constant>V4L2_PIX_FMT_SE401</constant></entry>
- <entry>'S401'</entry>
- <entry>Compressed RGB format used by the gspca se401 driver</entry>
- </row>
- <row id="V4L2-PIX-FMT-SQ905C">
- <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry>
- <entry>'905C'</entry>
- <entry>Compressed RGGB bayer format used by the gspca driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-MJPEG">
- <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry>
- <entry>'MJPG'</entry>
- <entry>Compressed format used by the Zoran driver</entry>
- </row>
- <row id="V4L2-PIX-FMT-PWC1">
- <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry>
- <entry>'PWC1'</entry>
- <entry>Compressed format of the PWC driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-PWC2">
- <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry>
- <entry>'PWC2'</entry>
- <entry>Compressed format of the PWC driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SN9C10X">
- <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry>
- <entry>'S910'</entry>
- <entry>Compressed format of the SN9C102 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SN9C20X-I420">
- <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
- <entry>'S920'</entry>
- <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-SN9C2028">
- <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry>
- <entry>'SONX'</entry>
- <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-STV0680">
- <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry>
- <entry>'S680'</entry>
- <entry>Bayer format of the gspca stv0680 driver.</entry>
- </row>
- <row id="V4L2-PIX-FMT-WNVA">
- <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
- <entry>'WNVA'</entry>
- <entry><para>Used by the Winnov Videum driver, <ulink
-url="http://www.thedirks.org/winnov/">
-http://www.thedirks.org/winnov/</ulink></para></entry>
- </row>
- <row id="V4L2-PIX-FMT-TM6000">
- <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry>
- <entry>'TM60'</entry>
- <entry><para>Used by Trident tm6000</para></entry>
- </row>
- <row id="V4L2-PIX-FMT-CIT-YYVYUY">
- <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry>
- <entry>'CITV'</entry>
- <entry><para>Used by xirlink CIT, found at IBM webcams.</para>
- <para>Uses one line of Y then 1 line of VYUY</para>
- </entry>
- </row>
- <row id="V4L2-PIX-FMT-KONICA420">
- <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry>
- <entry>'KONI'</entry>
- <entry><para>Used by Konica webcams.</para>
- <para>YUV420 planar in blocks of 256 pixels.</para>
- </entry>
- </row>
- <row id="V4L2-PIX-FMT-YYUV">
- <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
- <entry>'YYUV'</entry>
- <entry>unknown</entry>
- </row>
- <row id="V4L2-PIX-FMT-Y4">
- <entry><constant>V4L2_PIX_FMT_Y4</constant></entry>
- <entry>'Y04 '</entry>
- <entry>Old 4-bit greyscale format. Only the most significant 4 bits of each byte are used,
-the other bits are set to 0.</entry>
- </row>
- <row id="V4L2-PIX-FMT-Y6">
- <entry><constant>V4L2_PIX_FMT_Y6</constant></entry>
- <entry>'Y06 '</entry>
- <entry>Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used,
-the other bits are set to 0.</entry>
- </row>
- <row id="V4L2-PIX-FMT-S5C-UYVY-JPG">
- <entry><constant>V4L2_PIX_FMT_S5C_UYVY_JPG</constant></entry>
- <entry>'S5CI'</entry>
- <entry>Two-planar format used by Samsung S5C73MX cameras. The
-first plane contains interleaved JPEG and UYVY image data, followed by meta data
-in form of an array of offsets to the UYVY data blocks. The actual pointer array
-follows immediately the interleaved JPEG/UYVY data, the number of entries in
-this array equals the height of the UYVY image. Each entry is a 4-byte unsigned
-integer in big endian order and it's an offset to a single pixel line of the
-UYVY image. The first plane can start either with JPEG or UYVY data chunk. The
-size of a single UYVY block equals the UYVY image's width multiplied by 2. The
-size of a JPEG chunk depends on the image and can vary with each line.
-<para>The second plane, at an offset of 4084 bytes, contains a 4-byte offset to
-the pointer array in the first plane. This offset is followed by a 4-byte value
-indicating size of the pointer array. All numbers in the second plane are also
-in big endian order. Remaining data in the second plane is undefined. The
-information in the second plane allows to easily find location of the pointer
-array, which can be different for each frame. The size of the pointer array is
-constant for given UYVY image height.</para>
-<para>In order to extract UYVY and JPEG frames an application can initially set
-a data pointer to the start of first plane and then add an offset from the first
-entry of the pointers table. Such a pointer indicates start of an UYVY image
-pixel line. Whole UYVY line can be copied to a separate buffer. These steps
-should be repeated for each line, i.e. the number of entries in the pointer
-array. Anything what's in between the UYVY lines is JPEG data and should be
-concatenated to form the JPEG stream. </para>
-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="format-flags">
- <title>Format Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry>
- <entry>0x00000001</entry>
- <entry>The color values are premultiplied by the alpha channel
-value. For example, if a light blue pixel with 50% transparency was described by
-RGBA values (128, 192, 255, 128), the same pixel described with premultiplied
-colors would be described by RGBA values (64, 96, 128, 128) </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
diff --git a/Documentation/DocBook/media/v4l/planar-apis.xml b/Documentation/DocBook/media/v4l/planar-apis.xml
deleted file mode 100644
index 878ce2040488..000000000000
--- a/Documentation/DocBook/media/v4l/planar-apis.xml
+++ /dev/null
@@ -1,62 +0,0 @@
-<section id="planar-apis">
- <title>Single- and multi-planar APIs</title>
-
- <para>Some devices require data for each input or output video frame
- to be placed in discontiguous memory buffers. In such cases, one
- video frame has to be addressed using more than one memory address, i.e. one
- pointer per "plane". A plane is a sub-buffer of the current frame. For
- examples of such formats see <xref linkend="pixfmt" />.</para>
-
- <para>Initially, V4L2 API did not support multi-planar buffers and a set of
- extensions has been introduced to handle them. Those extensions constitute
- what is being referred to as the "multi-planar API".</para>
-
- <para>Some of the V4L2 API calls and structures are interpreted differently,
- depending on whether single- or multi-planar API is being used. An application
- can choose whether to use one or the other by passing a corresponding buffer
- type to its ioctl calls. Multi-planar versions of buffer types are suffixed
- with an `_MPLANE' string. For a list of available multi-planar buffer types
- see &v4l2-buf-type;.
- </para>
-
- <section>
- <title>Multi-planar formats</title>
- <para>Multi-planar API introduces new multi-planar formats. Those formats
- use a separate set of FourCC codes. It is important to distinguish between
- the multi-planar API and a multi-planar format. Multi-planar API calls can
- handle all single-planar formats as well (as long as they are passed in
- multi-planar API structures), while the single-planar API cannot
- handle multi-planar formats.</para>
- </section>
-
- <section>
- <title>Calls that distinguish between single and multi-planar APIs</title>
- <variablelist>
- <varlistentry>
- <term>&VIDIOC-QUERYCAP;</term>
- <listitem><para>Two additional multi-planar capabilities are added. They can
- be set together with non-multi-planar ones for devices that handle
- both single- and multi-planar formats.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
- <listitem><para>New structures for describing multi-planar formats are added:
- &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
- define new multi-planar formats, which have distinct FourCC codes from
- the existing single-planar ones.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
- <listitem><para>A new &v4l2-plane; structure for describing planes is added.
- Arrays of this structure are passed in the new
- <structfield>m.planes</structfield> field of &v4l2-buffer;.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>&VIDIOC-REQBUFS;</term>
- <listitem><para>Will allocate multi-planar buffers as requested.</para></listitem>
- </varlistentry>
- </variablelist>
- </section>
-</section>
diff --git a/Documentation/DocBook/media/v4l/remote_controllers.xml b/Documentation/DocBook/media/v4l/remote_controllers.xml
deleted file mode 100644
index 5124a6c4daa8..000000000000
--- a/Documentation/DocBook/media/v4l/remote_controllers.xml
+++ /dev/null
@@ -1,320 +0,0 @@
-<partinfo>
-<authorgroup>
-<author>
-<firstname>Mauro</firstname>
-<surname>Chehab</surname>
-<othername role="mi">Carvalho</othername>
-<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
-<contrib>Initial version.</contrib>
-</author>
-</authorgroup>
-<copyright>
- <year>2009-2014</year>
- <holder>Mauro Carvalho Chehab</holder>
-</copyright>
-
-<revhistory>
-<!-- Put document revisions here, newest first. -->
-<revision>
-<revnumber>3.15</revnumber>
-<date>2014-02-06</date>
-<authorinitials>mcc</authorinitials>
-<revremark>Added the interface description and the RC sysfs class description.</revremark>
-</revision>
-<revision>
-<revnumber>1.0</revnumber>
-<date>2009-09-06</date>
-<authorinitials>mcc</authorinitials>
-<revremark>Initial revision</revremark>
-</revision>
-</revhistory>
-</partinfo>
-
- <title>Remote Controller API</title>
- <chapter id="remote_controllers">
-
-<title>Remote Controllers</title>
-
-<section id="Remote_controllers_Intro">
-<title>Introduction</title>
-
-<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each
-manufacturer has their own type of control. It is not rare for the same manufacturer to ship different
-types of controls, depending on the device.</para>
-<para>A Remote Controller interface is mapped as a normal evdev/input interface, just like a keyboard or a mouse.
-So, it uses all ioctls already defined for any other input devices.</para>
-<para>However, remove controllers are more flexible than a normal input device, as the IR
-receiver (and/or transmitter) can be used in conjunction with a wide variety of different IR remotes.</para>
-<para>In order to allow flexibility, the Remote Controller subsystem allows controlling the
-RC-specific attributes via <link linkend="remote_controllers_sysfs_nodes">the sysfs class nodes</link>.</para>
-</section>
-
-<section id="remote_controllers_sysfs_nodes">
-<title>Remote Controller's sysfs nodes</title>
-<para>As defined at <constant>Documentation/ABI/testing/sysfs-class-rc</constant>, those are the sysfs nodes that control the Remote Controllers:</para>
-
-<section id="sys_class_rc">
-<title>/sys/class/rc/</title>
-<para>The <constant>/sys/class/rc/</constant> class sub-directory belongs to the Remote Controller
-core and provides a sysfs interface for configuring infrared remote controller receivers.
-</para>
-
-</section>
-<section id="sys_class_rc_rcN">
-<title>/sys/class/rc/rcN/</title>
-<para>A <constant>/sys/class/rc/rcN</constant> directory is created for each remote
- control receiver device where N is the number of the receiver.</para>
-
-</section>
-<section id="sys_class_rc_rcN_protocols">
-<title>/sys/class/rc/rcN/protocols</title>
-<para>Reading this file returns a list of available protocols, something like:</para>
-<para><constant>rc5 [rc6] nec jvc [sony]</constant></para>
-<para>Enabled protocols are shown in [] brackets.</para>
-<para>Writing "+proto" will add a protocol to the list of enabled protocols.</para>
-<para>Writing "-proto" will remove a protocol from the list of enabled protocols.</para>
-<para>Writing "proto" will enable only "proto".</para>
-<para>Writing "none" will disable all protocols.</para>
-<para>Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.</para>
-
-</section>
-<section id="sys_class_rc_rcN_filter">
-<title>/sys/class/rc/rcN/filter</title>
-<para>Sets the scancode filter expected value.</para>
-<para>Use in combination with <constant>/sys/class/rc/rcN/filter_mask</constant> to set the
-expected value of the bits set in the filter mask.
-If the hardware supports it then scancodes which do not match
-the filter will be ignored. Otherwise the write will fail with
-an error.</para>
-<para>This value may be reset to 0 if the current protocol is altered.</para>
-
-</section>
-<section id="sys_class_rc_rcN_filter_mask">
-<title>/sys/class/rc/rcN/filter_mask</title>
-<para>Sets the scancode filter mask of bits to compare.
-Use in combination with <constant>/sys/class/rc/rcN/filter</constant> to set the bits
-of the scancode which should be compared against the expected
-value. A value of 0 disables the filter to allow all valid
-scancodes to be processed.</para>
-<para>If the hardware supports it then scancodes which do not match
-the filter will be ignored. Otherwise the write will fail with
-an error.</para>
-<para>This value may be reset to 0 if the current protocol is altered.</para>
-
-</section>
-<section id="sys_class_rc_rcN_wakeup_protocols">
-<title>/sys/class/rc/rcN/wakeup_protocols</title>
-<para>Reading this file returns a list of available protocols to use for the
-wakeup filter, something like:</para>
-<para><constant>rc5 rc6 nec jvc [sony]</constant></para>
-<para>The enabled wakeup protocol is shown in [] brackets.</para>
-<para>Writing "+proto" will add a protocol to the list of enabled wakeup
-protocols.</para>
-<para>Writing "-proto" will remove a protocol from the list of enabled wakeup
-protocols.</para>
-<para>Writing "proto" will use "proto" for wakeup events.</para>
-<para>Writing "none" will disable wakeup.</para>
-<para>Write fails with EINVAL if an invalid protocol combination or unknown
-protocol name is used, or if wakeup is not supported by the hardware.</para>
-
-</section>
-<section id="sys_class_rc_rcN_wakeup_filter">
-<title>/sys/class/rc/rcN/wakeup_filter</title>
-<para>Sets the scancode wakeup filter expected value.
-Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter_mask</constant> to
-set the expected value of the bits set in the wakeup filter mask
-to trigger a system wake event.</para>
-<para>If the hardware supports it and wakeup_filter_mask is not 0 then
-scancodes which match the filter will wake the system from e.g.
-suspend to RAM or power off.
-Otherwise the write will fail with an error.</para>
-<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
-
-</section>
-<section id="sys_class_rc_rcN_wakeup_filter_mask">
-<title>/sys/class/rc/rcN/wakeup_filter_mask</title>
-<para>Sets the scancode wakeup filter mask of bits to compare.
-Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter</constant> to set
-the bits of the scancode which should be compared against the
-expected value to trigger a system wake event.</para>
-<para>If the hardware supports it and wakeup_filter_mask is not 0 then
-scancodes which match the filter will wake the system from e.g.
-suspend to RAM or power off.
-Otherwise the write will fail with an error.</para>
-<para>This value may be reset to 0 if the wakeup protocol is altered.</para>
-</section>
-</section>
-
-<section id="Remote_controllers_tables">
-<title>Remote controller tables</title>
-<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for
-different devices. This caused the same IR keyname to be mapped completely differently on
-different IR devices. This resulted that the same IR keyname to be mapped completely different on
-different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para>
-<para>This standard should be used by both V4L/DVB drivers and userspace applications</para>
-<para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para>
-
-<table pgwide="1" frame="none" id="rc_standard_keymap">
-<title>IR default keymapping</title>
-<tgroup cols="3">
-&cs-str;
-<tbody valign="top">
-<row>
-<entry>Key code</entry>
-<entry>Meaning</entry>
-<entry>Key examples on IR</entry>
-</row>
-
-<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row>
-
-<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row>
-<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row>
-<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row>
-<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row>
-<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row>
-<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row>
-<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row>
-<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row>
-<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row>
-<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row>
-
-<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row>
-
-<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>&gt;&gt; / FORWARD</entry></row>
-<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry>&lt;&lt;&lt; / BACK</entry></row>
-<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>&gt;&gt;&gt; / FORWARD</entry></row>
-<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row>
-<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row>
-<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry>&lt;&lt; / PREV / PREVIOUS</entry></row>
-<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row>
-<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row>
-<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / &gt;</entry></row>
-<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row>
-<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row>
-<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row>
-<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row>
-<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row>
-<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row>
-<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row>
-<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row>
-
-<row><entry><emphasis role="bold">Image control</emphasis></entry></row>
-
-<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row>
-<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row>
-
-<row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row>
-<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row>
-<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row>
-
-<row><entry><emphasis role="bold">Audio control</emphasis></entry></row>
-
-<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row>
-<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row>
-<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row>
-<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row>
-<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row>
-<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row>
-
-<row><entry><emphasis role="bold">Channel control</emphasis></entry></row>
-
-<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row>
-<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row>
-<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row>
-<row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row>
-<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row>
-
-<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row>
-
-<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row>
-<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row>
-<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row>
-<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row>
-
-<row><entry><emphasis role="bold">Media selection</emphasis></entry></row>
-
-<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row>
-<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row>
-<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-&gt; ) / CLOSE / OPEN</entry></row>
-
-<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row>
-<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row>
-<row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row>
-<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row>
-<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row>
-<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row>
-<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row>
-
-<row><entry><emphasis role="bold">Power control</emphasis></entry></row>
-
-<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row>
-<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row>
-<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row>
-<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row>
-
-<row><entry><emphasis role="bold">Window control</emphasis></entry></row>
-
-<row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row>
-<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row>
-<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row>
-<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row>
-<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row>
-<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row>
-<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row>
-<row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row>
-
-<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row>
-
-<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row>
-<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row>
-<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row>
-<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row>
-<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row>
-<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row>
-<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row>
-<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row>
-<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row>
-
-<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row>
-
-<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row>
-<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row>
-
-</tbody>
-</tgroup>
-</table>
-
-<para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para>
-
-<table pgwide="1" frame="none" id="rc_keymap_notes">
-<title>Notes</title>
-<tgroup cols="1">
-&cs-str;
-<tbody valign="top">
-<row>
-<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry>
-</row><row>
-<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry>
-</row><row>
-<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry>
-</row><row>
-<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry>
-</row>
-</tbody>
-</tgroup>
-</table>
-
-</section>
-
-<section id="Remote_controllers_table_change">
-<title>Changing default Remote Controller mappings</title>
-<para>The event interface provides two ioctls to be used against
-the /dev/input/event device, to allow changing the default
-keymapping.</para>
-
-<para>This program demonstrates how to replace the keymap tables.</para>
-&sub-keytable-c;
-</section>
-
-&sub-lirc_device_interface;
-</chapter>
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml
deleted file mode 100644
index 28cbded766c9..000000000000
--- a/Documentation/DocBook/media/v4l/selection-api.xml
+++ /dev/null
@@ -1,324 +0,0 @@
-<section id="selection-api">
-
- <title>Experimental API for cropping, composing and scaling</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link linkend="experimental">experimental</link>
-interface and may change in the future.</para>
- </note>
-
- <section>
- <title>Introduction</title>
-
-<para>Some video capture devices can sample a subsection of a picture and
-shrink or enlarge it to an image of arbitrary size. Next, the devices can
-insert the image into larger one. Some video output devices can crop part of an
-input image, scale it up or down and insert it at an arbitrary scan line and
-horizontal offset into a video signal. We call these abilities cropping,
-scaling and composing.</para>
-
-<para>On a video <emphasis>capture</emphasis> device the source is a video
-signal, and the cropping target determine the area actually sampled. The sink
-is an image stored in a memory buffer. The composing area specifies which part
-of the buffer is actually written to by the hardware. </para>
-
-<para>On a video <emphasis>output</emphasis> device the source is an image in a
-memory buffer, and the cropping target is a part of an image to be shown on a
-display. The sink is the display or the graphics screen. The application may
-select the part of display where the image should be displayed. The size and
-position of such a window is controlled by the compose target.</para>
-
-<para>Rectangles for all cropping and composing targets are defined even if the
-device does supports neither cropping nor composing. Their size and position
-will be fixed in such a case. If the device does not support scaling then the
-cropping and composing rectangles have the same size.</para>
-
- </section>
-
- <section>
- <title>Selection targets</title>
-
- <para>
- <figure id="sel-targets-capture">
- <title>Cropping and composing targets</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="selection.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>Targets used by a cropping, composing and scaling
- process</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
-
- <para>See <xref linkend="v4l2-selection-targets" /> for more
- information.</para>
- </section>
-
- <section>
-
- <title>Configuration</title>
-
-<para>Applications can use the <link linkend="vidioc-g-selection">selection
-API</link> to select an area in a video signal or a buffer, and to query for
-default settings and hardware limits.</para>
-
-<para>Video hardware can have various cropping, composing and scaling
-limitations. It may only scale up or down, support only discrete scaling
-factors, or have different scaling abilities in the horizontal and vertical
-directions. Also it may not support scaling at all. At the same time the
-cropping/composing rectangles may have to be aligned, and both the source and
-the sink may have arbitrary upper and lower size limits. Therefore, as usual,
-drivers are expected to adjust the requested parameters and return the actual
-values selected. An application can control the rounding behaviour using <link
-linkend="v4l2-selection-flags"> constraint flags </link>.</para>
-
- <section>
-
- <title>Configuration of video capture</title>
-
-<para>See figure <xref linkend="sel-targets-capture" /> for examples of the
-selection targets available for a video capture device. It is recommended to
-configure the cropping targets before to the composing targets.</para>
-
-<para>The range of coordinates of the top left corner, width and height of
-areas that can be sampled is given by the <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>
-target. It is recommended for the driver developers to put the
-top/left corner at position <constant>(0,0)</constant>. The rectangle's
-coordinates are expressed in pixels.</para>
-
-<para>The top left corner, width and height of the source rectangle, that is
-the area actually sampled, is given by the <constant>V4L2_SEL_TGT_CROP</constant>
-target. It uses the same coordinate system as <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>.
-The active cropping area must lie completely inside the capture boundaries. The
-driver may further adjust the requested size and/or position according to hardware
-limitations.</para>
-
-<para>Each capture device has a default source rectangle, given by the
-<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant> target. This rectangle shall
-over what the driver writer considers the complete picture. Drivers shall set
-the active crop rectangle to the default when the driver is first loaded, but
-not later.</para>
-
-<para>The composing targets refer to a memory buffer. The limits of composing
-coordinates are obtained using <constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant>.
-All coordinates are expressed in pixels. The rectangle's top/left
-corner must be located at position <constant>(0,0)</constant>. The width and
-height are equal to the image size set by <constant>VIDIOC_S_FMT</constant>.
-</para>
-
-<para>The part of a buffer into which the image is inserted by the hardware is
-controlled by the <constant>V4L2_SEL_TGT_COMPOSE</constant> target.
-The rectangle's coordinates are also expressed in the same coordinate system as
-the bounds rectangle. The composing rectangle must lie completely inside bounds
-rectangle. The driver must adjust the composing rectangle to fit to the
-bounding limits. Moreover, the driver can perform other adjustments according
-to hardware limitations. The application can control rounding behaviour using
-<link linkend="v4l2-selection-flags"> constraint flags</link>.</para>
-
-<para>For capture devices the default composing rectangle is queried using
-<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the
-bounding rectangle.</para>
-
-<para>The part of a buffer that is modified by the hardware is given by
-<constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>. It contains all pixels
-defined using <constant>V4L2_SEL_TGT_COMPOSE</constant> plus all
-padding data modified by hardware during insertion process. All pixels outside
-this rectangle <emphasis>must not</emphasis> be changed by the hardware. The
-content of pixels that lie inside the padded area but outside active area is
-undefined. The application can use the padded and active rectangles to detect
-where the rubbish pixels are located and remove them if needed.</para>
-
- </section>
-
- <section>
-
- <title>Configuration of video output</title>
-
-<para>For output devices targets and ioctls are used similarly to the video
-capture case. The <emphasis>composing</emphasis> rectangle refers to the
-insertion of an image into a video signal. The cropping rectangles refer to a
-memory buffer. It is recommended to configure the composing targets before to
-the cropping targets.</para>
-
-<para>The cropping targets refer to the memory buffer that contains an image to
-be inserted into a video signal or graphical screen. The limits of cropping
-coordinates are obtained using <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>.
-All coordinates are expressed in pixels. The top/left corner is always point
-<constant>(0,0)</constant>. The width and height is equal to the image size
-specified using <constant>VIDIOC_S_FMT</constant> ioctl.</para>
-
-<para>The top left corner, width and height of the source rectangle, that is
-the area from which image date are processed by the hardware, is given by the
-<constant>V4L2_SEL_TGT_CROP</constant>. Its coordinates are expressed
-in in the same coordinate system as the bounds rectangle. The active cropping
-area must lie completely inside the crop boundaries and the driver may further
-adjust the requested size and/or position according to hardware
-limitations.</para>
-
-<para>For output devices the default cropping rectangle is queried using
-<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant>. It is usually equal to the
-bounding rectangle.</para>
-
-<para>The part of a video signal or graphics display where the image is
-inserted by the hardware is controlled by <constant>V4L2_SEL_TGT_COMPOSE</constant>
-target. The rectangle's coordinates are expressed in pixels. The composing
-rectangle must lie completely inside the bounds rectangle. The driver must
-adjust the area to fit to the bounding limits. Moreover, the driver can
-perform other adjustments according to hardware limitations.</para>
-
-<para>The device has a default composing rectangle, given by the
-<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what
-the driver writer considers the complete picture. It is recommended for the
-driver developers to put the top/left corner at position <constant>(0,0)</constant>.
-Drivers shall set the active composing rectangle to the default
-one when the driver is first loaded.</para>
-
-<para>The devices may introduce additional content to video signal other than
-an image from memory buffers. It includes borders around an image. However,
-such a padded area is driver-dependent feature not covered by this document.
-Driver developers are encouraged to keep padded rectangle equal to active one.
-The padded target is accessed by the <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>
-identifier. It must contain all pixels from the <constant>V4L2_SEL_TGT_COMPOSE</constant>
-target.</para>
-
- </section>
-
- <section>
-
- <title>Scaling control</title>
-
-<para>An application can detect if scaling is performed by comparing the width
-and the height of rectangles obtained using <constant>V4L2_SEL_TGT_CROP</constant>
-and <constant>V4L2_SEL_TGT_COMPOSE</constant> targets. If
-these are not equal then the scaling is applied. The application can compute
-the scaling ratios using these values.</para>
-
- </section>
-
- </section>
-
- <section>
-
- <title>Comparison with old cropping API</title>
-
-<para>The selection API was introduced to cope with deficiencies of previous
-<link linkend="crop"> API</link>, that was designed to control simple capture
-devices. Later the cropping API was adopted by video output drivers. The ioctls
-are used to select a part of the display were the video signal is inserted. It
-should be considered as an API abuse because the described operation is
-actually the composing. The selection API makes a clear distinction between
-composing and cropping operations by setting the appropriate targets. The V4L2
-API lacks any support for composing to and cropping from an image inside a
-memory buffer. The application could configure a capture device to fill only a
-part of an image by abusing V4L2 API. Cropping a smaller image from a larger
-one is achieved by setting the field
-&v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets
-could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield>
-before calling <constant>VIDIOC_QBUF</constant>. Those
-operations should be avoided because they are not portable (endianness), and do
-not work for macroblock and Bayer formats and mmap buffers. The selection API
-deals with configuration of buffer cropping/composing in a clear, intuitive and
-portable way. Next, with the selection API the concepts of the padded target
-and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap;
-have no reserved fields. Therefore there is no way to extend their functionality.
-The new &v4l2-selection; provides a lot of place for future
-extensions. Driver developers are encouraged to implement only selection API.
-The former cropping API would be simulated using the new one.</para>
-
- </section>
-
- <section>
- <title>Examples</title>
- <example>
- <title>Resetting the cropping parameters</title>
-
- <para>(A video capture device is assumed; change
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to
-<constant>V4L2_SEL_TGT_COMPOSE_*</constant> family to configure composing
-area)</para>
-
- <programlisting>
-
- &v4l2-selection; sel = {
- .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
- .target = V4L2_SEL_TGT_CROP_DEFAULT,
- };
- ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;sel);
- if (ret)
- exit(-1);
- sel.target = V4L2_SEL_TGT_CROP;
- ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel);
- if (ret)
- exit(-1);
-
- </programlisting>
- </example>
-
- <example>
- <title>Simple downscaling</title>
- <para>Setting a composing area on output of size of <emphasis> at most
-</emphasis> half of limit placed at a center of a display.</para>
- <programlisting>
-
- &v4l2-selection; sel = {
- .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
- .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
- };
- struct v4l2_rect r;
-
- ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;sel);
- if (ret)
- exit(-1);
- /* setting smaller compose rectangle */
- r.width = sel.r.width / 2;
- r.height = sel.r.height / 2;
- r.left = sel.r.width / 4;
- r.top = sel.r.height / 4;
- sel.r = r;
- sel.target = V4L2_SEL_TGT_COMPOSE;
- sel.flags = V4L2_SEL_FLAG_LE;
- ret = ioctl(fd, &VIDIOC-S-SELECTION;, &amp;sel);
- if (ret)
- exit(-1);
-
- </programlisting>
- </example>
-
- <example>
- <title>Querying for scaling factors</title>
- <para>A video output device is assumed; change
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para>
- <programlisting>
-
- &v4l2-selection; compose = {
- .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
- .target = V4L2_SEL_TGT_COMPOSE,
- };
- &v4l2-selection; crop = {
- .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
- .target = V4L2_SEL_TGT_CROP,
- };
- double hscale, vscale;
-
- ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;compose);
- if (ret)
- exit(-1);
- ret = ioctl(fd, &VIDIOC-G-SELECTION;, &amp;crop);
- if (ret)
- exit(-1);
-
- /* computing scaling factors */
- hscale = (double)compose.r.width / crop.r.width;
- vscale = (double)compose.r.height / crop.r.height;
-
- </programlisting>
- </example>
-
- </section>
-
-</section>
diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml
deleted file mode 100644
index d6d56fb6f9c0..000000000000
--- a/Documentation/DocBook/media/v4l/selections-common.xml
+++ /dev/null
@@ -1,180 +0,0 @@
-<section id="v4l2-selections-common">
-
- <title>Common selection definitions</title>
-
- <para>While the <link linkend="selection-api">V4L2 selection
- API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev
- selection APIs</link> are very similar, there's one fundamental
- difference between the two. On sub-device API, the selection
- rectangle refers to the media bus format, and is bound to a
- sub-device's pad. On the V4L2 interface the selection rectangles
- refer to the in-memory pixel format.</para>
-
- <para>This section defines the common definitions of the
- selection interfaces on the two APIs.</para>
-
- <section id="v4l2-selection-targets">
-
- <title>Selection targets</title>
-
- <para>The precise meaning of the selection targets may be
- dependent on which of the two interfaces they are used.</para>
-
- <table pgwide="1" frame="none" id="v4l2-selection-targets-table">
- <title>Selection target definitions</title>
- <tgroup cols="5">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <colspec colname="c5" />
- &cs-def;
- <thead>
- <row rowsep="1">
- <entry align="left">Target name</entry>
- <entry align="left">id</entry>
- <entry align="left">Definition</entry>
- <entry align="left">Valid for V4L2</entry>
- <entry align="left">Valid for V4L2 subdev</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SEL_TGT_CROP</constant></entry>
- <entry>0x0000</entry>
- <entry>Crop rectangle. Defines the cropped area.</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry>
- <entry>0x0001</entry>
- <entry>Suggested cropping rectangle that covers the "whole picture".</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry>
- <entry>0x0002</entry>
- <entry>Bounds of the crop rectangle. All valid crop
- rectangles fit inside the crop bounds rectangle.
- </entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_NATIVE_SIZE</constant></entry>
- <entry>0x0003</entry>
- <entry>The native size of the device, e.g. a sensor's
- pixel array. <structfield>left</structfield> and
- <structfield>top</structfield> fields are zero for this
- target. Setting the native size will generally only make
- sense for memory to memory devices where the software can
- create a canvas of a given size in which for example a
- video frame can be composed. In that case
- V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size
- of that canvas.
- </entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry>
- <entry>0x0100</entry>
- <entry>Compose rectangle. Used to configure scaling
- and composition.</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry>
- <entry>0x0101</entry>
- <entry>Suggested composition rectangle that covers the "whole picture".</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
- <entry>0x0102</entry>
- <entry>Bounds of the compose rectangle. All valid compose
- rectangles fit inside the compose bounds rectangle.</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry>
- <entry>0x0103</entry>
- <entry>The active area and all padding pixels that are inserted or
- modified by hardware.</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="v4l2-selection-flags">
-
- <title>Selection flags</title>
-
- <table pgwide="1" frame="none" id="v4l2-selection-flags-table">
- <title>Selection flag definitions</title>
- <tgroup cols="5">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <colspec colname="c5" />
- &cs-def;
- <thead>
- <row rowsep="1">
- <entry align="left">Flag name</entry>
- <entry align="left">id</entry>
- <entry align="left">Definition</entry>
- <entry align="left">Valid for V4L2</entry>
- <entry align="left">Valid for V4L2 subdev</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SEL_FLAG_GE</constant></entry>
- <entry>(1 &lt;&lt; 0)</entry>
- <entry>Suggest the driver it should choose greater or
- equal rectangle (in size) than was requested. Albeit the
- driver may choose a lesser size, it will only do so due to
- hardware limitations. Without this flag (and
- <constant>V4L2_SEL_FLAG_LE</constant>) the
- behaviour is to choose the closest possible
- rectangle.</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_FLAG_LE</constant></entry>
- <entry>(1 &lt;&lt; 1)</entry>
- <entry>Suggest the driver it
- should choose lesser or equal rectangle (in size) than was
- requested. Albeit the driver may choose a greater size, it
- will only do so due to hardware limitations.</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry><constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant></entry>
- <entry>(1 &lt;&lt; 2)</entry>
- <entry>The configuration must not be propagated to any
- further processing steps. If this flag is not given, the
- configuration is propagated inside the subdevice to all
- further processing steps.</entry>
- <entry>No</entry>
- <entry>Yes</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
-</section>
diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml
deleted file mode 100644
index 2588ad781242..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-formats.xml
+++ /dev/null
@@ -1,4038 +0,0 @@
-<section id="v4l2-mbus-format">
- <title>Media Bus Formats</title>
-
- <table pgwide="1" frame="none" id="v4l2-mbus-framefmt">
- <title>struct <structname>v4l2_mbus_framefmt</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Image width, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Image height, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>code</structfield></entry>
- <entry>Format code, from &v4l2-mbus-pixelcode;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>field</structfield></entry>
- <entry>Field order, from &v4l2-field;. See
- <xref linkend="field-order" /> for details.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>colorspace</structfield></entry>
- <entry>Image colorspace, from &v4l2-colorspace;. See
- <xref linkend="colorspaces" /> for details.</entry>
- </row>
- <row>
- <entry>&v4l2-ycbcr-encoding;</entry>
- <entry><structfield>ycbcr_enc</structfield></entry>
- <entry>This information supplements the
-<structfield>colorspace</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>&v4l2-quantization;</entry>
- <entry><structfield>quantization</structfield></entry>
- <entry>This information supplements the
-<structfield>colorspace</structfield> and must be set by the driver for
-capture streams and by the application for output streams,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[6]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <section id="v4l2-mbus-pixelcode">
- <title>Media Bus Pixel Codes</title>
-
- <para>The media bus pixel codes describe image formats as flowing over
- physical busses (both between separate physical components and inside SoC
- devices). This should not be confused with the V4L2 pixel formats that
- describe, using four character codes, image formats as stored in memory.
- </para>
-
- <para>While there is a relationship between image formats on busses and
- image formats in memory (a raw Bayer image won't be magically converted to
- JPEG just by storing it to memory), there is no one-to-one correspondance
- between them.</para>
-
- <section>
- <title>Packed RGB Formats</title>
-
- <para>Those formats transfer pixel data as red, green and blue components.
- The format code is made of the following information.
- <itemizedlist>
- <listitem><para>The red, green and blue components order code, as encoded in a
- pixel sample. Possible values are RGB and BGR.</para></listitem>
- <listitem><para>The number of bits per component, for each component. The values
- can be different for all components. Common values are 555 and 565.</para>
- </listitem>
- <listitem><para>The number of bus samples per pixel. Pixels that are wider than
- the bus width must be transferred in multiple samples. Common values are
- 1 and 2.</para></listitem>
- <listitem><para>The bus width.</para></listitem>
- <listitem><para>For formats where the total number of bits per pixel is smaller
- than the number of bus samples per pixel times the bus width, a padding
- value stating if the bytes are padded in their most high order bits
- (PADHI) or low order bits (PADLO). A "C" prefix is used for component-wise
- padding in the most high order bits (CPADHI) or low order bits (CPADLO)
- of each separate component.</para></listitem>
- <listitem><para>For formats where the number of bus samples per pixel is larger
- than 1, an endianness value stating if the pixel is transferred MSB first
- (BE) or LSB first (LE).</para></listitem>
- </itemizedlist>
- </para>
-
- <para>For instance, a format where pixels are encoded as 5-bits red, 5-bits
- green and 5-bit blue values padded on the high bit, transferred as 2 8-bit
- samples per pixel with the most significant bits (padding, red and half of
- the green value) transferred first will be named
- <constant>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</constant>.
- </para>
-
- <para>The following tables list existing packed RGB formats.</para>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-rgb">
- <title>RGB formats</title>
- <tgroup cols="27">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="center"/>
- <colspec colname="bit" />
- <colspec colnum="4" colname="b31" align="center" />
- <colspec colnum="5" colname="b20" align="center" />
- <colspec colnum="6" colname="b29" align="center" />
- <colspec colnum="7" colname="b28" align="center" />
- <colspec colnum="8" colname="b27" align="center" />
- <colspec colnum="9" colname="b26" align="center" />
- <colspec colnum="10" colname="b25" align="center" />
- <colspec colnum="11" colname="b24" align="center" />
- <colspec colnum="12" colname="b23" align="center" />
- <colspec colnum="13" colname="b22" align="center" />
- <colspec colnum="14" colname="b21" align="center" />
- <colspec colnum="15" colname="b20" align="center" />
- <colspec colnum="16" colname="b19" align="center" />
- <colspec colnum="17" colname="b18" align="center" />
- <colspec colnum="18" colname="b17" align="center" />
- <colspec colnum="19" colname="b16" align="center" />
- <colspec colnum="20" colname="b15" align="center" />
- <colspec colnum="21" colname="b14" align="center" />
- <colspec colnum="22" colname="b13" align="center" />
- <colspec colnum="23" colname="b12" align="center" />
- <colspec colnum="24" colname="b11" align="center" />
- <colspec colnum="25" colname="b10" align="center" />
- <colspec colnum="26" colname="b09" align="center" />
- <colspec colnum="27" colname="b08" align="center" />
- <colspec colnum="28" colname="b07" align="center" />
- <colspec colnum="29" colname="b06" align="center" />
- <colspec colnum="30" colname="b05" align="center" />
- <colspec colnum="31" colname="b04" align="center" />
- <colspec colnum="32" colname="b03" align="center" />
- <colspec colnum="33" colname="b02" align="center" />
- <colspec colnum="34" colname="b01" align="center" />
- <colspec colnum="35" colname="b00" align="center" />
- <spanspec namest="b31" nameend="b00" spanname="b0" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry></entry>
- <entry spanname="b0">Data organization</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Bit</entry>
- <entry>31</entry>
- <entry>30</entry>
- <entry>29</entry>
- <entry>28</entry>
- <entry>27</entry>
- <entry>26</entry>
- <entry>25</entry>
- <entry>24</entry>
- <entry>23</entry>
- <entry>22</entry>
- <entry>21</entry>
- <entry>20</entry>
- <entry>19</entry>
- <entry>18</entry>
- <entry>17</entry>
- <entry>16</entry>
- <entry>15</entry>
- <entry>14</entry>
- <entry>13</entry>
- <entry>12</entry>
- <entry>11</entry>
- <entry>10</entry>
- <entry>9</entry>
- <entry>8</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-RGB444-1X12">
- <entry>MEDIA_BUS_FMT_RGB444_1X12</entry>
- <entry>0x1016</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE">
- <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE</entry>
- <entry>0x1001</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE">
- <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE</entry>
- <entry>0x1002</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE">
- <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</entry>
- <entry>0x1003</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>0</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE">
- <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE</entry>
- <entry>0x1004</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>0</entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB565-1X16">
- <entry>MEDIA_BUS_FMT_RGB565_1X16</entry>
- <entry>0x1017</entry>
- <entry></entry>
- &dash-ent-16;
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-BGR565-2X8-BE">
- <entry>MEDIA_BUS_FMT_BGR565_2X8_BE</entry>
- <entry>0x1005</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-BGR565-2X8-LE">
- <entry>MEDIA_BUS_FMT_BGR565_2X8_LE</entry>
- <entry>0x1006</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB565-2X8-BE">
- <entry>MEDIA_BUS_FMT_RGB565_2X8_BE</entry>
- <entry>0x1007</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB565-2X8-LE">
- <entry>MEDIA_BUS_FMT_RGB565_2X8_LE</entry>
- <entry>0x1008</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB666-1X18">
- <entry>MEDIA_BUS_FMT_RGB666_1X18</entry>
- <entry>0x1009</entry>
- <entry></entry>
- &dash-ent-14;
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RBG888-1X24">
- <entry>MEDIA_BUS_FMT_RBG888_1X24</entry>
- <entry>0x100e</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB666-1X24_CPADHI">
- <entry>MEDIA_BUS_FMT_RGB666_1X24_CPADHI</entry>
- <entry>0x1015</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>0</entry>
- <entry>0</entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-BGR888-1X24">
- <entry>MEDIA_BUS_FMT_BGR888_1X24</entry>
- <entry>0x1013</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-GBR888-1X24">
- <entry>MEDIA_BUS_FMT_GBR888_1X24</entry>
- <entry>0x1014</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB888-1X24">
- <entry>MEDIA_BUS_FMT_RGB888_1X24</entry>
- <entry>0x100a</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB888-2X12-BE">
- <entry>MEDIA_BUS_FMT_RGB888_2X12_BE</entry>
- <entry>0x100b</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB888-2X12-LE">
- <entry>MEDIA_BUS_FMT_RGB888_2X12_LE</entry>
- <entry>0x100c</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-ARGB888-1X32">
- <entry>MEDIA_BUS_FMT_ARGB888_1X32</entry>
- <entry>0x100d</entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB888-1X32-PADHI">
- <entry>MEDIA_BUS_FMT_RGB888_1X32_PADHI</entry>
- <entry>0x100f</entry>
- <entry></entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>On LVDS buses, usually each sample is transferred serialized in
- seven time slots per pixel clock, on three (18-bit) or four (24-bit)
- differential data pairs at the same time. The remaining bits are used for
- control signals as defined by SPWG/PSWG/VESA or JEIDA standards.
- The 24-bit RGB format serialized in seven time slots on four lanes using
- JEIDA defined bit mapping will be named
- <constant>MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA</constant>, for example.
- </para>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-rgb-lvds">
- <title>LVDS RGB formats</title>
- <tgroup cols="8">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="center" />
- <colspec colname="slot" align="center" />
- <colspec colname="lane" />
- <colspec colnum="5" colname="l03" align="center" />
- <colspec colnum="6" colname="l02" align="center" />
- <colspec colnum="7" colname="l01" align="center" />
- <colspec colnum="8" colname="l00" align="center" />
- <spanspec namest="l03" nameend="l00" spanname="l0" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry></entry>
- <entry></entry>
- <entry spanname="l0">Data organization</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Timeslot</entry>
- <entry>Lane</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-RGB666-1X7X3-SPWG">
- <entry>MEDIA_BUS_FMT_RGB666_1X7X3_SPWG</entry>
- <entry>0x1010</entry>
- <entry>0</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>d</entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>1</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>d</entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>2</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>d</entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>3</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>4</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>5</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>6</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB888-1X7X4-SPWG">
- <entry>MEDIA_BUS_FMT_RGB888_1X7X4_SPWG</entry>
- <entry>0x1011</entry>
- <entry>0</entry>
- <entry></entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>1</entry>
- <entry></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>d</entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>2</entry>
- <entry></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>d</entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>3</entry>
- <entry></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>4</entry>
- <entry></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>5</entry>
- <entry></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>6</entry>
- <entry></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA">
- <entry>MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA</entry>
- <entry>0x1012</entry>
- <entry>0</entry>
- <entry></entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>1</entry>
- <entry></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>d</entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>r<subscript>7</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>2</entry>
- <entry></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>d</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>3</entry>
- <entry></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>4</entry>
- <entry></entry>
- <entry>g<subscript>0</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>5</entry>
- <entry></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>6</entry>
- <entry></entry>
- <entry>r<subscript>0</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Bayer Formats</title>
-
- <para>Those formats transfer pixel data as red, green and blue components.
- The format code is made of the following information.
- <itemizedlist>
- <listitem><para>The red, green and blue components order code, as encoded in a
- pixel sample. The possible values are shown in <xref
- linkend="bayer-patterns" />.</para></listitem>
- <listitem><para>The number of bits per pixel component. All components are
- transferred on the same number of bits. Common values are 8, 10 and 12.</para>
- </listitem>
- <listitem><para>The compression (optional). If the pixel components are
- ALAW- or DPCM-compressed, a mention of the compression scheme and the
- number of bits per compressed pixel component.</para></listitem>
- <listitem><para>The number of bus samples per pixel. Pixels that are wider than
- the bus width must be transferred in multiple samples. Common values are
- 1 and 2.</para></listitem>
- <listitem><para>The bus width.</para></listitem>
- <listitem><para>For formats where the total number of bits per pixel is smaller
- than the number of bus samples per pixel times the bus width, a padding
- value stating if the bytes are padded in their most high order bits
- (PADHI) or low order bits (PADLO).</para></listitem>
- <listitem><para>For formats where the number of bus samples per pixel is larger
- than 1, an endianness value stating if the pixel is transferred MSB first
- (BE) or LSB first (LE).</para></listitem>
- </itemizedlist>
- </para>
-
- <para>For instance, a format with uncompressed 10-bit Bayer components
- arranged in a red, green, green, blue pattern transferred as 2 8-bit
- samples per pixel with the least significant bits transferred first will
- be named <constant>MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE</constant>.
- </para>
-
- <figure id="bayer-patterns">
- <title>Bayer Patterns</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="bayer.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>Bayer filter color patterns</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>The following table lists existing packed Bayer formats. The data
- organization is given as an example for the first pixel only.</para>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-bayer">
- <title>Bayer Formats</title>
- <tgroup cols="15">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="center"/>
- <colspec colname="bit" />
- <colspec colnum="4" colname="b11" align="center" />
- <colspec colnum="5" colname="b10" align="center" />
- <colspec colnum="6" colname="b09" align="center" />
- <colspec colnum="7" colname="b08" align="center" />
- <colspec colnum="8" colname="b07" align="center" />
- <colspec colnum="9" colname="b06" align="center" />
- <colspec colnum="10" colname="b05" align="center" />
- <colspec colnum="11" colname="b04" align="center" />
- <colspec colnum="12" colname="b03" align="center" />
- <colspec colnum="13" colname="b02" align="center" />
- <colspec colnum="14" colname="b01" align="center" />
- <colspec colnum="15" colname="b00" align="center" />
- <spanspec namest="b11" nameend="b00" spanname="b0" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry></entry>
- <entry spanname="b0">Data organization</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Bit</entry>
- <entry>11</entry>
- <entry>10</entry>
- <entry>9</entry>
- <entry>8</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-SBGGR8-1X8">
- <entry>MEDIA_BUS_FMT_SBGGR8_1X8</entry>
- <entry>0x3001</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGBRG8-1X8">
- <entry>MEDIA_BUS_FMT_SGBRG8_1X8</entry>
- <entry>0x3013</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGRBG8-1X8">
- <entry>MEDIA_BUS_FMT_SGRBG8_1X8</entry>
- <entry>0x3002</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SRGGB8-1X8">
- <entry>MEDIA_BUS_FMT_SRGGB8_1X8</entry>
- <entry>0x3014</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8">
- <entry>MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8</entry>
- <entry>0x3015</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8">
- <entry>MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8</entry>
- <entry>0x3016</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8">
- <entry>MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8</entry>
- <entry>0x3017</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8">
- <entry>MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8</entry>
- <entry>0x3018</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8">
- <entry>MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8</entry>
- <entry>0x300b</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8">
- <entry>MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8</entry>
- <entry>0x300c</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8">
- <entry>MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8</entry>
- <entry>0x3009</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8">
- <entry>MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8</entry>
- <entry>0x300d</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE">
- <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE</entry>
- <entry>0x3003</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>b<subscript>9</subscript></entry>
- <entry>b<subscript>8</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE">
- <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE</entry>
- <entry>0x3004</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>b<subscript>9</subscript></entry>
- <entry>b<subscript>8</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE">
- <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE</entry>
- <entry>0x3005</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>9</subscript></entry>
- <entry>b<subscript>8</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE">
- <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE</entry>
- <entry>0x3006</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>9</subscript></entry>
- <entry>b<subscript>8</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR10-1X10">
- <entry>MEDIA_BUS_FMT_SBGGR10_1X10</entry>
- <entry>0x3007</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>b<subscript>9</subscript></entry>
- <entry>b<subscript>8</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGBRG10-1X10">
- <entry>MEDIA_BUS_FMT_SGBRG10_1X10</entry>
- <entry>0x300e</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>9</subscript></entry>
- <entry>g<subscript>8</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGRBG10-1X10">
- <entry>MEDIA_BUS_FMT_SGRBG10_1X10</entry>
- <entry>0x300a</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>g<subscript>9</subscript></entry>
- <entry>g<subscript>8</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SRGGB10-1X10">
- <entry>MEDIA_BUS_FMT_SRGGB10_1X10</entry>
- <entry>0x300f</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>r<subscript>9</subscript></entry>
- <entry>r<subscript>8</subscript></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SBGGR12-1X12">
- <entry>MEDIA_BUS_FMT_SBGGR12_1X12</entry>
- <entry>0x3008</entry>
- <entry></entry>
- <entry>b<subscript>11</subscript></entry>
- <entry>b<subscript>10</subscript></entry>
- <entry>b<subscript>9</subscript></entry>
- <entry>b<subscript>8</subscript></entry>
- <entry>b<subscript>7</subscript></entry>
- <entry>b<subscript>6</subscript></entry>
- <entry>b<subscript>5</subscript></entry>
- <entry>b<subscript>4</subscript></entry>
- <entry>b<subscript>3</subscript></entry>
- <entry>b<subscript>2</subscript></entry>
- <entry>b<subscript>1</subscript></entry>
- <entry>b<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGBRG12-1X12">
- <entry>MEDIA_BUS_FMT_SGBRG12_1X12</entry>
- <entry>0x3010</entry>
- <entry></entry>
- <entry>g<subscript>11</subscript></entry>
- <entry>g<subscript>10</subscript></entry>
- <entry>g<subscript>9</subscript></entry>
- <entry>g<subscript>8</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SGRBG12-1X12">
- <entry>MEDIA_BUS_FMT_SGRBG12_1X12</entry>
- <entry>0x3011</entry>
- <entry></entry>
- <entry>g<subscript>11</subscript></entry>
- <entry>g<subscript>10</subscript></entry>
- <entry>g<subscript>9</subscript></entry>
- <entry>g<subscript>8</subscript></entry>
- <entry>g<subscript>7</subscript></entry>
- <entry>g<subscript>6</subscript></entry>
- <entry>g<subscript>5</subscript></entry>
- <entry>g<subscript>4</subscript></entry>
- <entry>g<subscript>3</subscript></entry>
- <entry>g<subscript>2</subscript></entry>
- <entry>g<subscript>1</subscript></entry>
- <entry>g<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-SRGGB12-1X12">
- <entry>MEDIA_BUS_FMT_SRGGB12_1X12</entry>
- <entry>0x3012</entry>
- <entry></entry>
- <entry>r<subscript>11</subscript></entry>
- <entry>r<subscript>10</subscript></entry>
- <entry>r<subscript>9</subscript></entry>
- <entry>r<subscript>8</subscript></entry>
- <entry>r<subscript>7</subscript></entry>
- <entry>r<subscript>6</subscript></entry>
- <entry>r<subscript>5</subscript></entry>
- <entry>r<subscript>4</subscript></entry>
- <entry>r<subscript>3</subscript></entry>
- <entry>r<subscript>2</subscript></entry>
- <entry>r<subscript>1</subscript></entry>
- <entry>r<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Packed YUV Formats</title>
-
- <para>Those data formats transfer pixel data as (possibly downsampled) Y, U
- and V components. Some formats include dummy bits in some of their samples
- and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma) formats.
- One cannot rely on the values of these dummy bits as those are undefined.
- </para>
- <para>The format code is made of the following information.
- <itemizedlist>
- <listitem><para>The Y, U and V components order code, as transferred on the
- bus. Possible values are YUYV, UYVY, YVYU and VYUY for formats with no
- dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC formats.
- </para></listitem>
- <listitem><para>The number of bits per pixel component. All components are
- transferred on the same number of bits. Common values are 8, 10 and 12.</para>
- </listitem>
- <listitem><para>The number of bus samples per pixel. Pixels that are wider than
- the bus width must be transferred in multiple samples. Common values are
- 1, 1.5 (encoded as 1_5) and 2.</para></listitem>
- <listitem><para>The bus width. When the bus width is larger than the number of
- bits per pixel component, several components are packed in a single bus
- sample. The components are ordered as specified by the order code, with
- components on the left of the code transferred in the high order bits.
- Common values are 8 and 16.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>For instance, a format where pixels are encoded as 8-bit YUV values
- downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the
- U, Y, V, Y order will be named <constant>MEDIA_BUS_FMT_UYVY8_2X8</constant>.
- </para>
-
- <para><xref linkend="v4l2-mbus-pixelcode-yuv8"/> lists existing packed YUV
- formats and describes the organization of each pixel data in each sample.
- When a format pattern is split across multiple samples each of the samples
- in the pattern is described.</para>
-
- <para>The role of each bit transferred over the bus is identified by one
- of the following codes.</para>
-
- <itemizedlist>
- <listitem><para>y<subscript>x</subscript> for luma component bit number x</para></listitem>
- <listitem><para>u<subscript>x</subscript> for blue chroma component bit number x</para></listitem>
- <listitem><para>v<subscript>x</subscript> for red chroma component bit number x</para></listitem>
- <listitem><para>a<subscript>x</subscript> for alpha component bit number x</para></listitem>
- <listitem><para>- for non-available bits (for positions higher than the bus width)</para></listitem>
- <listitem><para>d for dummy bits</para></listitem>
- </itemizedlist>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-yuv8">
- <title>YUV Formats</title>
- <tgroup cols="23">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="center"/>
- <colspec colname="bit" />
- <colspec colnum="4" colname="b31" align="center" />
- <colspec colnum="5" colname="b20" align="center" />
- <colspec colnum="6" colname="b29" align="center" />
- <colspec colnum="7" colname="b28" align="center" />
- <colspec colnum="8" colname="b27" align="center" />
- <colspec colnum="9" colname="b26" align="center" />
- <colspec colnum="10" colname="b25" align="center" />
- <colspec colnum="11" colname="b24" align="center" />
- <colspec colnum="12" colname="b23" align="center" />
- <colspec colnum="13" colname="b22" align="center" />
- <colspec colnum="14" colname="b21" align="center" />
- <colspec colnum="15" colname="b20" align="center" />
- <colspec colnum="16" colname="b19" align="center" />
- <colspec colnum="17" colname="b18" align="center" />
- <colspec colnum="18" colname="b17" align="center" />
- <colspec colnum="19" colname="b16" align="center" />
- <colspec colnum="20" colname="b15" align="center" />
- <colspec colnum="21" colname="b14" align="center" />
- <colspec colnum="22" colname="b13" align="center" />
- <colspec colnum="23" colname="b12" align="center" />
- <colspec colnum="24" colname="b11" align="center" />
- <colspec colnum="25" colname="b10" align="center" />
- <colspec colnum="26" colname="b09" align="center" />
- <colspec colnum="27" colname="b08" align="center" />
- <colspec colnum="28" colname="b07" align="center" />
- <colspec colnum="29" colname="b06" align="center" />
- <colspec colnum="30" colname="b05" align="center" />
- <colspec colnum="31" colname="b04" align="center" />
- <colspec colnum="32" colname="b03" align="center" />
- <colspec colnum="33" colname="b02" align="center" />
- <colspec colnum="34" colname="b01" align="center" />
- <colspec colnum="35" colname="b00" align="center" />
- <spanspec namest="b31" nameend="b00" spanname="b0" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry></entry>
- <entry spanname="b0">Data organization</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Bit</entry>
- <entry>31</entry>
- <entry>30</entry>
- <entry>29</entry>
- <entry>28</entry>
- <entry>27</entry>
- <entry>26</entry>
- <entry>25</entry>
- <entry>24</entry>
- <entry>23</entry>
- <entry>22</entry>
- <entry>21</entry>
- <entry>10</entry>
- <entry>19</entry>
- <entry>18</entry>
- <entry>17</entry>
- <entry>16</entry>
- <entry>15</entry>
- <entry>14</entry>
- <entry>13</entry>
- <entry>12</entry>
- <entry>11</entry>
- <entry>10</entry>
- <entry>9</entry>
- <entry>8</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-Y8-1X8">
- <entry>MEDIA_BUS_FMT_Y8_1X8</entry>
- <entry>0x2001</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UV8-1X8">
- <entry>MEDIA_BUS_FMT_UV8_1X8</entry>
- <entry>0x2015</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY8-1_5X8">
- <entry>MEDIA_BUS_FMT_UYVY8_1_5X8</entry>
- <entry>0x2002</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY8-1_5X8">
- <entry>MEDIA_BUS_FMT_VYUY8_1_5X8</entry>
- <entry>0x2003</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV8-1_5X8">
- <entry>MEDIA_BUS_FMT_YUYV8_1_5X8</entry>
- <entry>0x2004</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU8-1_5X8">
- <entry>MEDIA_BUS_FMT_YVYU8_1_5X8</entry>
- <entry>0x2005</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY8-2X8">
- <entry>MEDIA_BUS_FMT_UYVY8_2X8</entry>
- <entry>0x2006</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY8-2X8">
- <entry>MEDIA_BUS_FMT_VYUY8_2X8</entry>
- <entry>0x2007</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV8-2X8">
- <entry>MEDIA_BUS_FMT_YUYV8_2X8</entry>
- <entry>0x2008</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU8-2X8">
- <entry>MEDIA_BUS_FMT_YVYU8_2X8</entry>
- <entry>0x2009</entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-24;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-Y10-1X10">
- <entry>MEDIA_BUS_FMT_Y10_1X10</entry>
- <entry>0x200a</entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY10-2X10">
- <entry>MEDIA_BUS_FMT_UYVY10_2X10</entry>
- <entry>0x2018</entry>
- <entry></entry>
- &dash-ent-22;
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY10-2X10">
- <entry>MEDIA_BUS_FMT_VYUY10_2X10</entry>
- <entry>0x2019</entry>
- <entry></entry>
- &dash-ent-22;
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV10-2X10">
- <entry>MEDIA_BUS_FMT_YUYV10_2X10</entry>
- <entry>0x200b</entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU10-2X10">
- <entry>MEDIA_BUS_FMT_YVYU10_2X10</entry>
- <entry>0x200c</entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-22;
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-Y12-1X12">
- <entry>MEDIA_BUS_FMT_Y12_1X12</entry>
- <entry>0x2013</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY12-2X12">
- <entry>MEDIA_BUS_FMT_UYVY12_2X12</entry>
- <entry>0x201c</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY12-2X12">
- <entry>MEDIA_BUS_FMT_VYUY12_2X12</entry>
- <entry>0x201d</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV12-2X12">
- <entry>MEDIA_BUS_FMT_YUYV12_2X12</entry>
- <entry>0x201e</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU12-2X12">
- <entry>MEDIA_BUS_FMT_YVYU12_2X12</entry>
- <entry>0x201f</entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-20;
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY8-1X16">
- <entry>MEDIA_BUS_FMT_UYVY8_1X16</entry>
- <entry>0x200f</entry>
- <entry></entry>
- &dash-ent-16;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY8-1X16">
- <entry>MEDIA_BUS_FMT_VYUY8_1X16</entry>
- <entry>0x2010</entry>
- <entry></entry>
- &dash-ent-16;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV8-1X16">
- <entry>MEDIA_BUS_FMT_YUYV8_1X16</entry>
- <entry>0x2011</entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU8-1X16">
- <entry>MEDIA_BUS_FMT_YVYU8_1X16</entry>
- <entry>0x2012</entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YDYUYDYV8-1X16">
- <entry>MEDIA_BUS_FMT_YDYUYDYV8_1X16</entry>
- <entry>0x2014</entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- <entry>d</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-16;
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY10-1X20">
- <entry>MEDIA_BUS_FMT_UYVY10_1X20</entry>
- <entry>0x201a</entry>
- <entry></entry>
- &dash-ent-12;
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-12;
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY10-1X20">
- <entry>MEDIA_BUS_FMT_VYUY10_1X20</entry>
- <entry>0x201b</entry>
- <entry></entry>
- &dash-ent-12;
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-12;
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV10-1X20">
- <entry>MEDIA_BUS_FMT_YUYV10_1X20</entry>
- <entry>0x200d</entry>
- <entry></entry>
- &dash-ent-12;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-12;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU10-1X20">
- <entry>MEDIA_BUS_FMT_YVYU10_1X20</entry>
- <entry>0x200e</entry>
- <entry></entry>
- &dash-ent-12;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-12;
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VUY8-1X24">
- <entry>MEDIA_BUS_FMT_VUY8_1X24</entry>
- <entry>0x201a</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUV8-1X24">
- <entry>MEDIA_BUS_FMT_YUV8_1X24</entry>
- <entry>0x2025</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-UYVY12-1X24">
- <entry>MEDIA_BUS_FMT_UYVY12_1X24</entry>
- <entry>0x2020</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-8;
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-VYUY12-1X24">
- <entry>MEDIA_BUS_FMT_VYUY12_1X24</entry>
- <entry>0x2021</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-8;
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUYV12-1X24">
- <entry>MEDIA_BUS_FMT_YUYV12_1X24</entry>
- <entry>0x2022</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-8;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YVYU12-1X24">
- <entry>MEDIA_BUS_FMT_YVYU12_1X24</entry>
- <entry>0x2023</entry>
- <entry></entry>
- &dash-ent-8;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>v<subscript>11</subscript></entry>
- <entry>v<subscript>10</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- &dash-ent-8;
- <entry>y<subscript>11</subscript></entry>
- <entry>y<subscript>10</subscript></entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>11</subscript></entry>
- <entry>u<subscript>10</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-YUV10-1X30">
- <entry>MEDIA_BUS_FMT_YUV10_1X30</entry>
- <entry>0x2016</entry>
- <entry></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>y<subscript>9</subscript></entry>
- <entry>y<subscript>8</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>9</subscript></entry>
- <entry>u<subscript>8</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>v<subscript>9</subscript></entry>
- <entry>v<subscript>8</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- <row id="MEDIA-BUS-FMT-AYUV8-1X32">
- <entry>MEDIA_BUS_FMT_AYUV8_1X32</entry>
- <entry>0x2017</entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry>y<subscript>7</subscript></entry>
- <entry>y<subscript>6</subscript></entry>
- <entry>y<subscript>5</subscript></entry>
- <entry>y<subscript>4</subscript></entry>
- <entry>y<subscript>3</subscript></entry>
- <entry>y<subscript>2</subscript></entry>
- <entry>y<subscript>1</subscript></entry>
- <entry>y<subscript>0</subscript></entry>
- <entry>u<subscript>7</subscript></entry>
- <entry>u<subscript>6</subscript></entry>
- <entry>u<subscript>5</subscript></entry>
- <entry>u<subscript>4</subscript></entry>
- <entry>u<subscript>3</subscript></entry>
- <entry>u<subscript>2</subscript></entry>
- <entry>u<subscript>1</subscript></entry>
- <entry>u<subscript>0</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>HSV/HSL Formats</title>
-
- <para>Those formats transfer pixel data as RGB values in a cylindrical-coordinate
- system using Hue-Saturation-Value or Hue-Saturation-Lightness components. The
- format code is made of the following information.
- <itemizedlist>
- <listitem><para>The hue, saturation, value or lightness and optional alpha
- components order code, as encoded in a pixel sample. The only currently
- supported value is AHSV.
- </para></listitem>
- <listitem><para>The number of bits per component, for each component. The values
- can be different for all components. The only currently supported value is 8888.
- </para></listitem>
- <listitem><para>The number of bus samples per pixel. Pixels that are wider than
- the bus width must be transferred in multiple samples. The only currently
- supported value is 1.</para></listitem>
- <listitem><para>The bus width.</para></listitem>
- <listitem><para>For formats where the total number of bits per pixel is smaller
- than the number of bus samples per pixel times the bus width, a padding
- value stating if the bytes are padded in their most high order bits
- (PADHI) or low order bits (PADLO).</para></listitem>
- <listitem><para>For formats where the number of bus samples per pixel is larger
- than 1, an endianness value stating if the pixel is transferred MSB first
- (BE) or LSB first (LE).</para></listitem>
- </itemizedlist>
- </para>
-
- <para>The following table lists existing HSV/HSL formats.</para>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-hsv">
- <title>HSV/HSL formats</title>
- <tgroup cols="27">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="center"/>
- <colspec colname="bit" />
- <colspec colnum="4" colname="b31" align="center" />
- <colspec colnum="5" colname="b20" align="center" />
- <colspec colnum="6" colname="b29" align="center" />
- <colspec colnum="7" colname="b28" align="center" />
- <colspec colnum="8" colname="b27" align="center" />
- <colspec colnum="9" colname="b26" align="center" />
- <colspec colnum="10" colname="b25" align="center" />
- <colspec colnum="11" colname="b24" align="center" />
- <colspec colnum="12" colname="b23" align="center" />
- <colspec colnum="13" colname="b22" align="center" />
- <colspec colnum="14" colname="b21" align="center" />
- <colspec colnum="15" colname="b20" align="center" />
- <colspec colnum="16" colname="b19" align="center" />
- <colspec colnum="17" colname="b18" align="center" />
- <colspec colnum="18" colname="b17" align="center" />
- <colspec colnum="19" colname="b16" align="center" />
- <colspec colnum="20" colname="b15" align="center" />
- <colspec colnum="21" colname="b14" align="center" />
- <colspec colnum="22" colname="b13" align="center" />
- <colspec colnum="23" colname="b12" align="center" />
- <colspec colnum="24" colname="b11" align="center" />
- <colspec colnum="25" colname="b10" align="center" />
- <colspec colnum="26" colname="b09" align="center" />
- <colspec colnum="27" colname="b08" align="center" />
- <colspec colnum="28" colname="b07" align="center" />
- <colspec colnum="29" colname="b06" align="center" />
- <colspec colnum="30" colname="b05" align="center" />
- <colspec colnum="31" colname="b04" align="center" />
- <colspec colnum="32" colname="b03" align="center" />
- <colspec colnum="33" colname="b02" align="center" />
- <colspec colnum="34" colname="b01" align="center" />
- <colspec colnum="35" colname="b00" align="center" />
- <spanspec namest="b31" nameend="b00" spanname="b0" />
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry></entry>
- <entry spanname="b0">Data organization</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Bit</entry>
- <entry>31</entry>
- <entry>30</entry>
- <entry>29</entry>
- <entry>28</entry>
- <entry>27</entry>
- <entry>26</entry>
- <entry>25</entry>
- <entry>24</entry>
- <entry>23</entry>
- <entry>22</entry>
- <entry>21</entry>
- <entry>20</entry>
- <entry>19</entry>
- <entry>18</entry>
- <entry>17</entry>
- <entry>16</entry>
- <entry>15</entry>
- <entry>14</entry>
- <entry>13</entry>
- <entry>12</entry>
- <entry>11</entry>
- <entry>10</entry>
- <entry>9</entry>
- <entry>8</entry>
- <entry>7</entry>
- <entry>6</entry>
- <entry>5</entry>
- <entry>4</entry>
- <entry>3</entry>
- <entry>2</entry>
- <entry>1</entry>
- <entry>0</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-AHSV8888-1X32">
- <entry>MEDIA_BUS_FMT_AHSV8888_1X32</entry>
- <entry>0x6001</entry>
- <entry></entry>
- <entry>a<subscript>7</subscript></entry>
- <entry>a<subscript>6</subscript></entry>
- <entry>a<subscript>5</subscript></entry>
- <entry>a<subscript>4</subscript></entry>
- <entry>a<subscript>3</subscript></entry>
- <entry>a<subscript>2</subscript></entry>
- <entry>a<subscript>1</subscript></entry>
- <entry>a<subscript>0</subscript></entry>
- <entry>h<subscript>7</subscript></entry>
- <entry>h<subscript>6</subscript></entry>
- <entry>h<subscript>5</subscript></entry>
- <entry>h<subscript>4</subscript></entry>
- <entry>h<subscript>3</subscript></entry>
- <entry>h<subscript>2</subscript></entry>
- <entry>h<subscript>1</subscript></entry>
- <entry>h<subscript>0</subscript></entry>
- <entry>s<subscript>7</subscript></entry>
- <entry>s<subscript>6</subscript></entry>
- <entry>s<subscript>5</subscript></entry>
- <entry>s<subscript>4</subscript></entry>
- <entry>s<subscript>3</subscript></entry>
- <entry>s<subscript>2</subscript></entry>
- <entry>s<subscript>1</subscript></entry>
- <entry>s<subscript>0</subscript></entry>
- <entry>v<subscript>7</subscript></entry>
- <entry>v<subscript>6</subscript></entry>
- <entry>v<subscript>5</subscript></entry>
- <entry>v<subscript>4</subscript></entry>
- <entry>v<subscript>3</subscript></entry>
- <entry>v<subscript>2</subscript></entry>
- <entry>v<subscript>1</subscript></entry>
- <entry>v<subscript>0</subscript></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>JPEG Compressed Formats</title>
-
- <para>Those data formats consist of an ordered sequence of 8-bit bytes
- obtained from JPEG compression process. Additionally to the
- <constant>_JPEG</constant> postfix the format code is made of
- the following information.
- <itemizedlist>
- <listitem><para>The number of bus samples per entropy encoded byte.</para></listitem>
- <listitem><para>The bus width.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>For instance, for a JPEG baseline process and an 8-bit bus width
- the format will be named <constant>MEDIA_BUS_FMT_JPEG_1X8</constant>.
- </para>
-
- <para>The following table lists existing JPEG compressed formats.</para>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-jpeg">
- <title>JPEG Formats</title>
- <tgroup cols="3">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="left"/>
- <colspec colname="remarks" align="left"/>
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>Remarks</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-JPEG-1X8">
- <entry>MEDIA_BUS_FMT_JPEG_1X8</entry>
- <entry>0x4001</entry>
- <entry>Besides of its usage for the parallel bus this format is
- recommended for transmission of JPEG data over MIPI CSI bus
- using the User Defined 8-bit Data types.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="v4l2-mbus-vendor-spec-fmts">
- <title>Vendor and Device Specific Formats</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
-interface and may change in the future.</para>
- </note>
-
- <para>This section lists complex data formats that are either vendor or
- device specific.
- </para>
-
- <para>The following table lists the existing vendor and device specific
- formats.</para>
-
- <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-vendor-specific">
- <title>Vendor and device specific formats</title>
- <tgroup cols="3">
- <colspec colname="id" align="left" />
- <colspec colname="code" align="left"/>
- <colspec colname="remarks" align="left"/>
- <thead>
- <row>
- <entry>Identifier</entry>
- <entry>Code</entry>
- <entry>Comments</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row id="MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8">
- <entry>MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8</entry>
- <entry>0x5001</entry>
- <entry>
- Interleaved raw UYVY and JPEG image format with embedded
- meta-data used by Samsung S3C73MX camera sensors.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- </section>
-</section>
diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia b/Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia
deleted file mode 100644
index e32ba5362e1d..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia
+++ /dev/null
@@ -1,614 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
- <dia:diagramdata>
- <dia:attribute name="background">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="pagebreak">
- <dia:color val="#000099"/>
- </dia:attribute>
- <dia:attribute name="paper">
- <dia:composite type="paper">
- <dia:attribute name="name">
- <dia:string>#A4#</dia:string>
- </dia:attribute>
- <dia:attribute name="tmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="bmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="lmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="rmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="is_portrait">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="scaling">
- <dia:real val="0.49000000953674316"/>
- </dia:attribute>
- <dia:attribute name="fitto">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="grid">
- <dia:composite type="grid">
- <dia:attribute name="width_x">
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="width_y">
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="visible_x">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="visible_y">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:composite type="color"/>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#d8e5e5"/>
- </dia:attribute>
- <dia:attribute name="guides">
- <dia:composite type="guides">
- <dia:attribute name="hguides"/>
- <dia:attribute name="vguides"/>
- </dia:composite>
- </dia:attribute>
- </dia:diagramdata>
- <dia:layer name="Background" visible="true" active="true">
- <dia:object type="Standard - Box" version="0" id="O0">
- <dia:attribute name="obj_pos">
- <dia:point val="-0.4,6.5"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-0.45,6.45;23.1387,16.2"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-0.4,6.5"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="23.48871579904775"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="9.6500000000000004"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O1">
- <dia:attribute name="obj_pos">
- <dia:point val="0.225,9.45"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.175,9.4;8.225,14.7"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="0.225,9.45"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="7.9499999999999975"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="5.1999999999999975"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O2">
- <dia:attribute name="obj_pos">
- <dia:point val="3.175,10.55"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.125,10.5;7.925,14.45"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="3.175,10.55"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="4.6999999999999975"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.8499999999999979"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O3">
- <dia:attribute name="obj_pos">
- <dia:point val="3.725,11.3875"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.725,10.7925;6.6025,13.14"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink
-crop
-selection#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="3.725,11.3875"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O4">
- <dia:attribute name="obj_pos">
- <dia:point val="1.475,7.9"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="1.475,7.305;1.475,8.0525"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>##</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="1.475,7.9"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O5">
- <dia:attribute name="obj_pos">
- <dia:point val="0.426918,7.89569"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.426918,7.30069;3.90942,8.84819"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink media
-bus format#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="0.426918,7.89569"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O6">
- <dia:attribute name="obj_pos">
- <dia:point val="17.4887,7.75"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="17.4887,7.155;21.8112,8.7025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#source media
-bus format#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="17.4887,7.75"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O7">
- <dia:attribute name="obj_pos">
- <dia:point val="17.5244,9.5417"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="17.4744,9.4917;22.2387,13.35"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="17.5244,9.5417"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="4.6643157990477508"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.758300000000002"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O8">
- <dia:attribute name="obj_pos">
- <dia:point val="17.5244,13.3"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.12132,13.2463;17.5781,14.4537"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="17.5244,13.3"/>
- <dia:point val="3.175,14.4"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O7" connection="5"/>
- <dia:connection handle="1" to="O2" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O9">
- <dia:attribute name="obj_pos">
- <dia:point val="17.5244,9.5417"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.12162,9.48832;17.5778,10.6034"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="17.5244,9.5417"/>
- <dia:point val="3.175,10.55"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O7" connection="0"/>
- <dia:connection handle="1" to="O2" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O10">
- <dia:attribute name="obj_pos">
- <dia:point val="22.1887,13.3"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.82132,13.2463;22.2424,14.4537"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="22.1887,13.3"/>
- <dia:point val="7.875,14.4"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O7" connection="7"/>
- <dia:connection handle="1" to="O2" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O11">
- <dia:attribute name="obj_pos">
- <dia:point val="22.1887,9.5417"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.82161,9.48831;22.2421,10.6034"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="22.1887,9.5417"/>
- <dia:point val="7.875,10.55"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O7" connection="2"/>
- <dia:connection handle="1" to="O2" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O12">
- <dia:attribute name="obj_pos">
- <dia:point val="23.23,10.5742"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="23.18,10.5242;24.13,11.4742"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="23.23,10.5742"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O13">
- <dia:attribute name="obj_pos">
- <dia:point val="24.08,10.9992"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.03,10.6388;32.4953,11.3624"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="24.08,10.9992"/>
- <dia:point val="32.3835,11.0007"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O12" connection="3"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O14">
- <dia:attribute name="obj_pos">
- <dia:point val="25.3454,10.49"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.3454,9.895;29.9904,10.6425"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 1 (source)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="25.3454,10.49"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O15">
- <dia:attribute name="obj_pos">
- <dia:point val="-1.44491,11.6506"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-1.49491,11.6006;-0.54491,12.5506"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-1.44491,11.6506"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O16">
- <dia:attribute name="obj_pos">
- <dia:point val="-9.61991,12.09"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-9.67,11.7149;-1.33311,12.4385"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="-9.61991,12.09"/>
- <dia:point val="-1.44491,12.0756"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O15" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O17">
- <dia:attribute name="obj_pos">
- <dia:point val="-7.39291,11.49"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-7.39291,10.895;-3.58791,11.6425"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 0 (sink)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="-7.39291,11.49"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- </dia:layer>
-</dia:diagram>
diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg b/Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg
deleted file mode 100644
index 18b0f5de9ed2..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg
+++ /dev/null
@@ -1,63 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/>
- <g>
- <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/>
- </g>
- <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75">
- <tspan x="74.5" y="227.75">sink</tspan>
- <tspan x="74.5" y="243.75">crop</tspan>
- <tspan x="74.5" y="259.75">selection</tspan>
- </text>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
- <tspan x="29.5" y="158"></tspan>
- </text>
- <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
- <tspan x="8.53836" y="157.914">sink media</tspan>
- <tspan x="8.53836" y="173.914">bus format</tspan>
- </text>
- <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155">
- <tspan x="349.774" y="155">source media</tspan>
- <tspan x="349.774" y="171">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/>
- <g>
- <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/>
- <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8">
- <tspan x="506.908" y="209.8">pad 1 (source)</tspan>
- </text>
- <g>
- <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
- <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
- <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
- </text>
-</svg>
diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-full.dia b/Documentation/DocBook/media/v4l/subdev-image-processing-full.dia
deleted file mode 100644
index a0d782927840..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-image-processing-full.dia
+++ /dev/null
@@ -1,1588 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
- <dia:diagramdata>
- <dia:attribute name="background">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="pagebreak">
- <dia:color val="#000099"/>
- </dia:attribute>
- <dia:attribute name="paper">
- <dia:composite type="paper">
- <dia:attribute name="name">
- <dia:string>#A4#</dia:string>
- </dia:attribute>
- <dia:attribute name="tmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="bmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="lmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="rmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="is_portrait">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="scaling">
- <dia:real val="0.49000000953674316"/>
- </dia:attribute>
- <dia:attribute name="fitto">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="grid">
- <dia:composite type="grid">
- <dia:attribute name="width_x">
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="width_y">
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="visible_x">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="visible_y">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:composite type="color"/>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#d8e5e5"/>
- </dia:attribute>
- <dia:attribute name="guides">
- <dia:composite type="guides">
- <dia:attribute name="hguides"/>
- <dia:attribute name="vguides"/>
- </dia:composite>
- </dia:attribute>
- </dia:diagramdata>
- <dia:layer name="Background" visible="true" active="true">
- <dia:object type="Standard - Box" version="0" id="O0">
- <dia:attribute name="obj_pos">
- <dia:point val="15.945,6.45"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="15.895,6.4;26.4,18.95"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="15.945,6.45"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="10.404999999254942"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="12.449999999999992"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#ff765a"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O1">
- <dia:attribute name="obj_pos">
- <dia:point val="-0.1,3.65"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-0.15,3.6;40.25,20.85"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-0.1,3.65"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="40.300000000000004"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="17.149999999999999"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O2">
- <dia:attribute name="obj_pos">
- <dia:point val="-1.05,7.9106"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-1.1,7.8606;-0.15,8.8106"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-1.05,7.9106"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O3">
- <dia:attribute name="obj_pos">
- <dia:point val="40.3366,9.8342"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="40.2866,9.7842;41.2366,10.7342"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="40.3366,9.8342"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O4">
- <dia:attribute name="obj_pos">
- <dia:point val="-9.225,8.35"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-9.27509,7.97487;-0.938197,8.69848"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="-9.225,8.35"/>
- <dia:point val="-1.05,8.3356"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O2" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O5">
- <dia:attribute name="obj_pos">
- <dia:point val="41.1866,10.2592"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="41.1366,9.89879;49.6019,10.6224"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="41.1866,10.2592"/>
- <dia:point val="49.4901,10.2607"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O3" connection="3"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O6">
- <dia:attribute name="obj_pos">
- <dia:point val="-6.998,7.75"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-6.998,7.155;-3.193,7.9025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 0 (sink)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="-6.998,7.75"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O7">
- <dia:attribute name="obj_pos">
- <dia:point val="42.452,9.75"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="42.452,9.155;47.097,9.9025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 2 (source)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="42.452,9.75"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O8">
- <dia:attribute name="obj_pos">
- <dia:point val="0.275,6"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.225,5.95;8.275,11.25"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="0.275,6"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="7.9499999999999975"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="5.1999999999999975"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O9">
- <dia:attribute name="obj_pos">
- <dia:point val="3.125,6.8"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.075,6.75;7.875,10.7"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="3.125,6.8"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="4.6999999999999975"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.8499999999999979"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O10">
- <dia:attribute name="obj_pos">
- <dia:point val="1.525,4.45"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="1.525,3.855;1.525,4.6025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>##</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="1.525,4.45"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O11">
- <dia:attribute name="obj_pos">
- <dia:point val="0.476918,4.44569"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.476918,3.85069;3.95942,5.39819"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink media
-bus format#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="0.476918,4.44569"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O12">
- <dia:attribute name="obj_pos">
- <dia:point val="16.6822,9.28251"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="16.6322,9.23251;24.9922,17.9564"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="16.6822,9.28251"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="8.2600228398861297"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="8.6238900617957164"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#00ff00"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O13">
- <dia:attribute name="obj_pos">
- <dia:point val="16.6822,17.9064"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.05732,10.5823;16.7499,17.9741"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="16.6822,17.9064"/>
- <dia:point val="3.125,10.65"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O12" connection="5"/>
- <dia:connection handle="1" to="O9" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O14">
- <dia:attribute name="obj_pos">
- <dia:point val="16.6822,9.28251"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3.06681,6.74181;16.7404,9.3407"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="16.6822,9.28251"/>
- <dia:point val="3.125,6.8"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O12" connection="0"/>
- <dia:connection handle="1" to="O9" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O15">
- <dia:attribute name="obj_pos">
- <dia:point val="24.9422,17.9064"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.75945,10.5845;25.0077,17.9719"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="24.9422,17.9064"/>
- <dia:point val="7.825,10.65"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O12" connection="7"/>
- <dia:connection handle="1" to="O9" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O16">
- <dia:attribute name="obj_pos">
- <dia:point val="24.9422,9.28251"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.76834,6.74334;24.9989,9.33917"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="24.9422,9.28251"/>
- <dia:point val="7.825,6.8"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O12" connection="2"/>
- <dia:connection handle="1" to="O9" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O17">
- <dia:attribute name="obj_pos">
- <dia:point val="16.7352,7.47209"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="16.7352,6.87709;22.5602,8.42459"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink compose
-selection (scaling)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="16.7352,7.47209"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#00ff00"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O18">
- <dia:attribute name="obj_pos">
- <dia:point val="20.4661,9.72825"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="20.4161,9.67825;25.5254,13.3509"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="20.4661,9.72825"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.009308462554376"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.5726155970598077"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O19">
- <dia:attribute name="obj_pos">
- <dia:point val="34.475,5.2564"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="34.475,4.6614;38.7975,6.2089"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#source media
-bus format#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="34.475,5.2564"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O20">
- <dia:attribute name="obj_pos">
- <dia:point val="34.4244,8.6917"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="34.3744,8.6417;39.4837,12.3143"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="34.4244,8.6917"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.009308462554376"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.5726155970598077"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O21">
- <dia:attribute name="obj_pos">
- <dia:point val="34.4244,12.2643"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="20.4125,12.2107;34.478,13.3545"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.4244,12.2643"/>
- <dia:point val="20.4661,13.3009"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O20" connection="5"/>
- <dia:connection handle="1" to="O18" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O22">
- <dia:attribute name="obj_pos">
- <dia:point val="34.4244,8.6917"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="20.4125,8.63813;34.478,9.78182"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.4244,8.6917"/>
- <dia:point val="20.4661,9.72825"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O20" connection="0"/>
- <dia:connection handle="1" to="O18" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O23">
- <dia:attribute name="obj_pos">
- <dia:point val="39.4337,12.2643"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.4218,12.2107;39.4873,13.3545"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="39.4337,12.2643"/>
- <dia:point val="25.4754,13.3009"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O20" connection="7"/>
- <dia:connection handle="1" to="O18" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O24">
- <dia:attribute name="obj_pos">
- <dia:point val="39.4337,8.6917"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.4218,8.63813;39.4873,9.78182"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="39.4337,8.6917"/>
- <dia:point val="25.4754,9.72825"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O20" connection="2"/>
- <dia:connection handle="1" to="O18" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O25">
- <dia:attribute name="obj_pos">
- <dia:point val="16.25,5.15"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="16.25,4.555;21.68,6.1025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink compose
-bounds selection#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="16.25,5.15"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#ff765a"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O26">
- <dia:attribute name="obj_pos">
- <dia:point val="-1.02991,16.6506"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-1.07991,16.6006;-0.12991,17.5506"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-1.02991,16.6506"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O27">
- <dia:attribute name="obj_pos">
- <dia:point val="-9.20491,17.09"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-9.255,16.7149;-0.918107,17.4385"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="-9.20491,17.09"/>
- <dia:point val="-1.02991,17.0756"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O26" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O28">
- <dia:attribute name="obj_pos">
- <dia:point val="-6.95,16.45"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-6.95,15.855;-3.145,16.6025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 1 (sink)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="-6.95,16.45"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O29">
- <dia:attribute name="obj_pos">
- <dia:point val="0.390412,14.64"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.340412,14.59;6.045,18.8"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="0.390412,14.64"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.604587512785236"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="4.1099999999999994"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O30">
- <dia:attribute name="obj_pos">
- <dia:point val="2.645,15.74"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="2.595,15.69;5.6,18.3"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="2.645,15.74"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="2.904999999254942"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="2.5100000000000016"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O31">
- <dia:attribute name="obj_pos">
- <dia:point val="1.595,12.99"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="1.595,12.395;1.595,13.1425"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>##</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="1.595,12.99"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O32">
- <dia:attribute name="obj_pos">
- <dia:point val="17.945,12.595"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="2.58596,12.536;18.004,15.799"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="17.945,12.595"/>
- <dia:point val="2.645,15.74"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O36" connection="0"/>
- <dia:connection handle="1" to="O30" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O33">
- <dia:attribute name="obj_pos">
- <dia:point val="17.945,15.8"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="2.58772,15.7427;18.0023,18.3073"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="17.945,15.8"/>
- <dia:point val="2.645,18.25"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O36" connection="5"/>
- <dia:connection handle="1" to="O30" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O34">
- <dia:attribute name="obj_pos">
- <dia:point val="21.7,15.8"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="5.49307,15.7431;21.7569,18.3069"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="21.7,15.8"/>
- <dia:point val="5.55,18.25"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O36" connection="7"/>
- <dia:connection handle="1" to="O30" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O35">
- <dia:attribute name="obj_pos">
- <dia:point val="21.7,12.595"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="5.49136,12.5364;21.7586,15.7986"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="21.7,12.595"/>
- <dia:point val="5.55,15.74"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O36" connection="2"/>
- <dia:connection handle="1" to="O30" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O36">
- <dia:attribute name="obj_pos">
- <dia:point val="17.945,12.595"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="17.895,12.545;21.75,15.85"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="17.945,12.595"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="3.7549999992549452"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.2049999992549427"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#00ff00"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O37">
- <dia:attribute name="obj_pos">
- <dia:point val="22.1631,14.2233"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="22.1131,14.1733;25.45,16.7"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="22.1631,14.2233"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="3.2369000000000021"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="2.4267000000000003"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O38">
- <dia:attribute name="obj_pos">
- <dia:point val="34.6714,16.2367"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="34.6214,16.1867;37.9,18.75"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="34.6714,16.2367"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="3.178600000000003"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="2.4632999999999967"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O39">
- <dia:attribute name="obj_pos">
- <dia:point val="34.6714,18.7"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="22.1057,16.5926;34.7288,18.7574"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.6714,18.7"/>
- <dia:point val="22.1631,16.65"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O38" connection="5"/>
- <dia:connection handle="1" to="O37" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O40">
- <dia:attribute name="obj_pos">
- <dia:point val="34.6714,16.2367"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="22.1058,14.166;34.7287,16.294"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.6714,16.2367"/>
- <dia:point val="22.1631,14.2233"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O38" connection="0"/>
- <dia:connection handle="1" to="O37" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O41">
- <dia:attribute name="obj_pos">
- <dia:point val="37.85,18.7"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.3425,16.5925;37.9075,18.7575"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="37.85,18.7"/>
- <dia:point val="25.4,16.65"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O38" connection="7"/>
- <dia:connection handle="1" to="O37" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O42">
- <dia:attribute name="obj_pos">
- <dia:point val="37.85,16.2367"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.3427,14.166;37.9073,16.294"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="37.85,16.2367"/>
- <dia:point val="25.4,14.2233"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O38" connection="2"/>
- <dia:connection handle="1" to="O37" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O43">
- <dia:attribute name="obj_pos">
- <dia:point val="40.347,16.7742"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="40.297,16.7242;41.247,17.6742"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="40.347,16.7742"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O44">
- <dia:attribute name="obj_pos">
- <dia:point val="41.197,17.1992"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="41.147,16.8388;49.6123,17.5624"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="41.197,17.1992"/>
- <dia:point val="49.5005,17.2007"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O43" connection="3"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O45">
- <dia:attribute name="obj_pos">
- <dia:point val="42.4624,16.69"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="42.4624,16.095;47.1074,16.8425"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 3 (source)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="42.4624,16.69"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O46">
- <dia:attribute name="obj_pos">
- <dia:point val="9.85,4.55"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="9.85,3.955;12.7275,6.3025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink
-crop
-selection#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="9.85,4.55"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O47">
- <dia:attribute name="obj_pos">
- <dia:point val="27.65,4.75"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="27.65,4.155;30.5275,6.5025"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#source
-crop
-selection#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="27.65,4.75"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O48">
- <dia:attribute name="obj_pos">
- <dia:point val="10.55,6.6"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.7135,6.39438;10.6035,7.11605"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="10.55,6.6"/>
- <dia:point val="7.825,6.8"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O9" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O49">
- <dia:attribute name="obj_pos">
- <dia:point val="10.45,6.55"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="5.48029,6.48236;10.5176,15.8387"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="10.45,6.55"/>
- <dia:point val="5.55,15.74"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O30" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O50">
- <dia:attribute name="obj_pos">
- <dia:point val="27.5246,6.66071"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.406,6.59136;27.594,9.82122"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="27.5246,6.66071"/>
- <dia:point val="25.4754,9.72825"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O18" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O51">
- <dia:attribute name="obj_pos">
- <dia:point val="27.5036,6.68935"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="25.2161,6.62775;27.5652,14.331"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="27.5036,6.68935"/>
- <dia:point val="25.4,14.2233"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O37" connection="2"/>
- </dia:connections>
- </dia:object>
- </dia:layer>
-</dia:diagram>
diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-full.svg b/Documentation/DocBook/media/v4l/subdev-image-processing-full.svg
deleted file mode 100644
index 3322cf4c0093..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-image-processing-full.svg
+++ /dev/null
@@ -1,163 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
- <g>
- <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/>
- </g>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/>
- <g>
- <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/>
- <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/>
- <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155">
- <tspan x="-139.96" y="155">pad 0 (sink)</tspan>
- </text>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195">
- <tspan x="849.04" y="195">pad 2 (source)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89">
- <tspan x="30.5" y="89"></tspan>
- </text>
- <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138">
- <tspan x="9.53836" y="88.9138">sink media</tspan>
- <tspan x="9.53836" y="104.914">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/>
- <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
- <tspan x="334.704" y="149.442">sink compose</tspan>
- <tspan x="334.704" y="165.442">selection (scaling)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/>
- </g>
- <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128">
- <tspan x="689.5" y="105.128">source media</tspan>
- <tspan x="689.5" y="121.128">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/>
- <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103">
- <tspan x="325" y="103">sink compose</tspan>
- <tspan x="325" y="119">bounds selection</tspan>
- </text>
- <g>
- <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/>
- <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329">
- <tspan x="-139" y="329">pad 1 (sink)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8">
- <tspan x="31.9" y="259.8"></tspan>
- </text>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/>
- <g>
- <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/>
- <g>
- <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/>
- <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8">
- <tspan x="849.248" y="333.8">pad 3 (source)</tspan>
- </text>
- <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91">
- <tspan x="197" y="91">sink</tspan>
- <tspan x="197" y="107">crop</tspan>
- <tspan x="197" y="123">selection</tspan>
- </text>
- <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95">
- <tspan x="553" y="95">source</tspan>
- <tspan x="553" y="111">crop</tspan>
- <tspan x="553" y="127">selection</tspan>
- </text>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/>
- <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/>
- <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/>
- <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/>
- <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
- </g>
-</svg>
diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia b/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia
deleted file mode 100644
index 0cd50a7bda80..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia
+++ /dev/null
@@ -1,1152 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
- <dia:diagramdata>
- <dia:attribute name="background">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="pagebreak">
- <dia:color val="#000099"/>
- </dia:attribute>
- <dia:attribute name="paper">
- <dia:composite type="paper">
- <dia:attribute name="name">
- <dia:string>#A4#</dia:string>
- </dia:attribute>
- <dia:attribute name="tmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="bmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="lmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="rmargin">
- <dia:real val="2.8222000598907471"/>
- </dia:attribute>
- <dia:attribute name="is_portrait">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="scaling">
- <dia:real val="0.49000000953674316"/>
- </dia:attribute>
- <dia:attribute name="fitto">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="grid">
- <dia:composite type="grid">
- <dia:attribute name="width_x">
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="width_y">
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="visible_x">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="visible_y">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:composite type="color"/>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#d8e5e5"/>
- </dia:attribute>
- <dia:attribute name="guides">
- <dia:composite type="guides">
- <dia:attribute name="hguides"/>
- <dia:attribute name="vguides"/>
- </dia:composite>
- </dia:attribute>
- </dia:diagramdata>
- <dia:layer name="Background" visible="true" active="true">
- <dia:object type="Standard - Box" version="0" id="O0">
- <dia:attribute name="obj_pos">
- <dia:point val="-0.4,6.5"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-0.45,6.45;39.95,22.9"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-0.4,6.5"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="40.299999999999997"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="16.349999999999998"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O1">
- <dia:attribute name="obj_pos">
- <dia:point val="0.225,9.45"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.175,9.4;8.225,14.7"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="0.225,9.45"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="7.9499999999999975"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="5.1999999999999975"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O2">
- <dia:attribute name="obj_pos">
- <dia:point val="2.475,10.2"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="2.425,10.15;7.225,14.1"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="2.475,10.2"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="4.6999999999999975"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.8499999999999979"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O3">
- <dia:attribute name="obj_pos">
- <dia:point val="3,11.2"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="3,10.605;5.8775,12.9525"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink
-crop
-selection#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="3,11.2"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#0000ff"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O4">
- <dia:attribute name="obj_pos">
- <dia:point val="1.475,7.9"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="1.475,7.305;1.475,8.0525"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>##</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="1.475,7.9"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O5">
- <dia:attribute name="obj_pos">
- <dia:point val="0.426918,7.89569"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="0.426918,7.30069;3.90942,8.84819"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink media
-bus format#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="0.426918,7.89569"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#a52a2a"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O6">
- <dia:attribute name="obj_pos">
- <dia:point val="16.6822,9.28251"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="16.6322,9.23251;24.9922,17.9564"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="16.6822,9.28251"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="8.2600228398861297"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="8.6238900617957164"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#00ff00"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O7">
- <dia:attribute name="obj_pos">
- <dia:point val="16.6822,17.9064"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="2.41365,13.9886;16.7436,17.9678"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="16.6822,17.9064"/>
- <dia:point val="2.475,14.05"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O6" connection="5"/>
- <dia:connection handle="1" to="O2" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O8">
- <dia:attribute name="obj_pos">
- <dia:point val="16.6822,9.28251"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="2.42188,9.22939;16.7353,10.2531"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="16.6822,9.28251"/>
- <dia:point val="2.475,10.2"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O6" connection="0"/>
- <dia:connection handle="1" to="O2" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O9">
- <dia:attribute name="obj_pos">
- <dia:point val="24.9422,17.9064"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.11553,13.9905;25.0017,17.9659"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="24.9422,17.9064"/>
- <dia:point val="7.175,14.05"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O6" connection="7"/>
- <dia:connection handle="1" to="O2" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O10">
- <dia:attribute name="obj_pos">
- <dia:point val="24.9422,9.28251"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="7.12249,9.23;24.9947,10.2525"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="24.9422,9.28251"/>
- <dia:point val="7.175,10.2"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O6" connection="2"/>
- <dia:connection handle="1" to="O2" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O11">
- <dia:attribute name="obj_pos">
- <dia:point val="16.7352,7.47209"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="16.7352,6.87709;22.5602,8.42459"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#sink compose
-selection (scaling)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="16.7352,7.47209"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#00ff00"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O12">
- <dia:attribute name="obj_pos">
- <dia:point val="19.1161,9.97825"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="19.0661,9.92825;24.1754,13.6009"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="19.1161,9.97825"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.009308462554376"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.5726155970598077"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O13">
- <dia:attribute name="obj_pos">
- <dia:point val="27.1661,7.47209"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="27.1661,6.87709;30.0436,9.22459"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#source
-crop
-selection#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="27.1661,7.47209"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O14">
- <dia:attribute name="obj_pos">
- <dia:point val="34.575,7.8564"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="34.575,7.2614;38.8975,8.8089"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#source media
-bus format#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="34.575,7.8564"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O15">
- <dia:attribute name="obj_pos">
- <dia:point val="34.5244,11.2917"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="34.4744,11.2417;39.5837,14.9143"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="34.5244,11.2917"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.009308462554376"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.5726155970598077"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O16">
- <dia:attribute name="obj_pos">
- <dia:point val="34.5244,14.8643"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="19.062,13.4968;34.5785,14.9184"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.5244,14.8643"/>
- <dia:point val="19.1161,13.5509"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O15" connection="5"/>
- <dia:connection handle="1" to="O12" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O17">
- <dia:attribute name="obj_pos">
- <dia:point val="34.5244,11.2917"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="19.062,9.92418;34.5785,11.3458"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.5244,11.2917"/>
- <dia:point val="19.1161,9.97825"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O15" connection="0"/>
- <dia:connection handle="1" to="O12" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O18">
- <dia:attribute name="obj_pos">
- <dia:point val="39.5337,14.8643"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.0713,13.4968;39.5878,14.9184"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="39.5337,14.8643"/>
- <dia:point val="24.1254,13.5509"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O15" connection="7"/>
- <dia:connection handle="1" to="O12" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O19">
- <dia:attribute name="obj_pos">
- <dia:point val="39.5337,11.2917"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.0713,9.92418;39.5878,11.3458"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="39.5337,11.2917"/>
- <dia:point val="24.1254,9.97825"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O15" connection="2"/>
- <dia:connection handle="1" to="O12" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O20">
- <dia:attribute name="obj_pos">
- <dia:point val="39.98,12.0742"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="39.93,12.0242;40.88,12.9742"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="39.98,12.0742"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O21">
- <dia:attribute name="obj_pos">
- <dia:point val="40.83,12.4992"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="40.78,12.1388;49.2453,12.8624"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="40.83,12.4992"/>
- <dia:point val="49.1335,12.5007"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O20" connection="3"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O22">
- <dia:attribute name="obj_pos">
- <dia:point val="42.0954,11.99"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="42.0954,11.395;46.7404,12.1425"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 1 (source)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="42.0954,11.99"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O23">
- <dia:attribute name="obj_pos">
- <dia:point val="-1.44491,11.6506"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-1.49491,11.6006;-0.54491,12.5506"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="-1.44491,11.6506"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O24">
- <dia:attribute name="obj_pos">
- <dia:point val="-9.61991,12.09"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-9.67,11.7149;-1.33311,12.4385"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="-9.61991,12.09"/>
- <dia:point val="-1.44491,12.0756"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O23" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O25">
- <dia:attribute name="obj_pos">
- <dia:point val="-7.39291,11.49"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="-7.39291,10.895;-3.58791,11.6425"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 0 (sink)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="-7.39291,11.49"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O26">
- <dia:attribute name="obj_pos">
- <dia:point val="19.4911,13.8333"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="19.4411,13.7833;24.5504,17.4559"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="19.4911,13.8333"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.009308462554376"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.5726155970598077"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="false"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Box" version="0" id="O27">
- <dia:attribute name="obj_pos">
- <dia:point val="34.4994,17.2967"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="34.4494,17.2467;39.5587,20.9193"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="34.4994,17.2967"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="5.009308462554376"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="3.5726155970598077"/>
- </dia:attribute>
- <dia:attribute name="border_width">
- <dia:real val="0.10000000149011612"/>
- </dia:attribute>
- <dia:attribute name="border_color">
- <dia:color val="#8b6914"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O28">
- <dia:attribute name="obj_pos">
- <dia:point val="34.4994,20.8693"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="19.4311,17.3459;34.5594,20.9293"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.4994,20.8693"/>
- <dia:point val="19.4911,17.4059"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O27" connection="5"/>
- <dia:connection handle="1" to="O26" connection="5"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O29">
- <dia:attribute name="obj_pos">
- <dia:point val="34.4994,17.2967"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="19.4311,13.7733;34.5594,17.3567"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="34.4994,17.2967"/>
- <dia:point val="19.4911,13.8333"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O27" connection="0"/>
- <dia:connection handle="1" to="O26" connection="0"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O30">
- <dia:attribute name="obj_pos">
- <dia:point val="39.5087,20.8693"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.4404,17.3459;39.5687,20.9293"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="39.5087,20.8693"/>
- <dia:point val="24.5004,17.4059"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O27" connection="7"/>
- <dia:connection handle="1" to="O26" connection="7"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O31">
- <dia:attribute name="obj_pos">
- <dia:point val="39.5087,17.2967"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.4404,13.7733;39.5687,17.3567"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="39.5087,17.2967"/>
- <dia:point val="24.5004,13.8333"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#e60505"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="4"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O27" connection="2"/>
- <dia:connection handle="1" to="O26" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Geometric - Perfect Circle" version="1" id="O32">
- <dia:attribute name="obj_pos">
- <dia:point val="39.855,18.7792"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="39.805,18.7292;40.755,19.6792"/>
- </dia:attribute>
- <dia:attribute name="meta">
- <dia:composite type="dict"/>
- </dia:attribute>
- <dia:attribute name="elem_corner">
- <dia:point val="39.855,18.7792"/>
- </dia:attribute>
- <dia:attribute name="elem_width">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="elem_height">
- <dia:real val="0.84999999999999787"/>
- </dia:attribute>
- <dia:attribute name="line_width">
- <dia:real val="0.10000000000000001"/>
- </dia:attribute>
- <dia:attribute name="line_colour">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="fill_colour">
- <dia:color val="#ffffff"/>
- </dia:attribute>
- <dia:attribute name="show_background">
- <dia:boolean val="true"/>
- </dia:attribute>
- <dia:attribute name="line_style">
- <dia:enum val="0"/>
- <dia:real val="1"/>
- </dia:attribute>
- <dia:attribute name="flip_horizontal">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="flip_vertical">
- <dia:boolean val="false"/>
- </dia:attribute>
- <dia:attribute name="subscale">
- <dia:real val="1"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O33">
- <dia:attribute name="obj_pos">
- <dia:point val="40.705,19.2042"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="40.655,18.8438;49.1203,19.5674"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="40.705,19.2042"/>
- <dia:point val="49.0085,19.2057"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="0" to="O32" connection="3"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Text" version="1" id="O34">
- <dia:attribute name="obj_pos">
- <dia:point val="41.9704,18.695"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="41.9704,18.1;46.6154,18.8475"/>
- </dia:attribute>
- <dia:attribute name="text">
- <dia:composite type="text">
- <dia:attribute name="string">
- <dia:string>#pad 2 (source)#</dia:string>
- </dia:attribute>
- <dia:attribute name="font">
- <dia:font family="sans" style="0" name="Helvetica"/>
- </dia:attribute>
- <dia:attribute name="height">
- <dia:real val="0.80000000000000004"/>
- </dia:attribute>
- <dia:attribute name="pos">
- <dia:point val="41.9704,18.695"/>
- </dia:attribute>
- <dia:attribute name="color">
- <dia:color val="#000000"/>
- </dia:attribute>
- <dia:attribute name="alignment">
- <dia:enum val="0"/>
- </dia:attribute>
- </dia:composite>
- </dia:attribute>
- <dia:attribute name="valign">
- <dia:enum val="3"/>
- </dia:attribute>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O35">
- <dia:attribute name="obj_pos">
- <dia:point val="27.3,9.55"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.0146,9.49376;27.3562,10.255"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="27.3,9.55"/>
- <dia:point val="24.1254,9.97825"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O12" connection="2"/>
- </dia:connections>
- </dia:object>
- <dia:object type="Standard - Line" version="0" id="O36">
- <dia:attribute name="obj_pos">
- <dia:point val="27.3454,9.53624"/>
- </dia:attribute>
- <dia:attribute name="obj_bb">
- <dia:rectangle val="24.4311,9.46695;27.4147,13.9265"/>
- </dia:attribute>
- <dia:attribute name="conn_endpoints">
- <dia:point val="27.3454,9.53624"/>
- <dia:point val="24.5004,13.8333"/>
- </dia:attribute>
- <dia:attribute name="numcp">
- <dia:int val="1"/>
- </dia:attribute>
- <dia:attribute name="line_color">
- <dia:color val="#a020f0"/>
- </dia:attribute>
- <dia:attribute name="end_arrow">
- <dia:enum val="22"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_length">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:attribute name="end_arrow_width">
- <dia:real val="0.5"/>
- </dia:attribute>
- <dia:connections>
- <dia:connection handle="1" to="O26" connection="2"/>
- </dia:connections>
- </dia:object>
- </dia:layer>
-</dia:diagram>
diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg
deleted file mode 100644
index 2340c0f8bc92..000000000000
--- a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg
+++ /dev/null
@@ -1,116 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/>
- <g>
- <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/>
- </g>
- <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224">
- <tspan x="60" y="224">sink</tspan>
- <tspan x="60" y="240">crop</tspan>
- <tspan x="60" y="256">selection</tspan>
- </text>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
- <tspan x="29.5" y="158"></tspan>
- </text>
- <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
- <tspan x="8.53836" y="157.914">sink media</tspan>
- <tspan x="8.53836" y="173.914">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/>
- <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
- <tspan x="334.704" y="149.442">sink compose</tspan>
- <tspan x="334.704" y="165.442">selection (scaling)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/>
- </g>
- <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442">
- <tspan x="543.322" y="149.442">source</tspan>
- <tspan x="543.322" y="165.442">crop</tspan>
- <tspan x="543.322" y="181.442">selection</tspan>
- </text>
- <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128">
- <tspan x="691.5" y="157.128">source media</tspan>
- <tspan x="691.5" y="173.128">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/>
- <g>
- <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/>
- <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8">
- <tspan x="841.908" y="239.8">pad 1 (source)</tspan>
- </text>
- <g>
- <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
- <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
- <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
- </text>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/>
- <g>
- <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/>
- <g>
- <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/>
- <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9">
- <tspan x="839.408" y="373.9">pad 2 (source)</tspan>
- </text>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/>
- <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/>
- <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
- </g>
-</svg>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
deleted file mode 100644
index e98caa1c39bd..000000000000
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ /dev/null
@@ -1,709 +0,0 @@
- <partinfo>
- <authorgroup>
- <author>
- <firstname>Michael</firstname>
- <surname>Schimek</surname>
- <othername role="mi">H</othername>
- <affiliation>
- <address>
- <email>mschimek@gmx.at</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Bill</firstname>
- <surname>Dirks</surname>
- <!-- Commented until Bill opts in to be spammed.
- <affiliation>
- <address>
- <email>bill@thedirks.org</email>
- </address>
- </affiliation> -->
- <contrib>Original author of the V4L2 API and
-documentation.</contrib>
- </author>
-
- <author>
- <firstname>Hans</firstname>
- <surname>Verkuil</surname>
- <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
-the extended control ioctls, major parts of the sliced VBI API, the
-MPEG encoder and decoder APIs and the DV Timings API.</contrib>
- <affiliation>
- <address>
- <email>hverkuil@xs4all.nl</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Martin</firstname>
- <surname>Rubli</surname>
- <!--
- <affiliation>
- <address>
- <email>martin_rubli@logitech.com</email>
- </address>
- </affiliation> -->
- <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
-and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
- </author>
-
- <author>
- <firstname>Andy</firstname>
- <surname>Walls</surname>
- <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
-MPEG stream embedded, sliced VBI data format in this specification.
-</contrib>
- <affiliation>
- <address>
- <email>awalls@md.metrocast.net</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Mauro</firstname>
- <surname>Carvalho Chehab</surname>
- <contrib>Documented libv4l, designed and added v4l2grab example,
-Remote Controller chapter.</contrib>
- <affiliation>
- <address>
- <email>m.chehab@samsung.com</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Muralidharan</firstname>
- <surname>Karicheri</surname>
- <contrib>Documented the Digital Video timings API.</contrib>
- <affiliation>
- <address>
- <email>m-karicheri2@ti.com</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Pawel</firstname>
- <surname>Osciak</surname>
- <contrib>Designed and documented the multi-planar API.</contrib>
- <affiliation>
- <address>
- <email>pawel AT osciak.com</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Sakari</firstname>
- <surname>Ailus</surname>
- <contrib>Subdev selections API.</contrib>
- <affiliation>
- <address>
- <email>sakari.ailus@iki.fi</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Antti</firstname>
- <surname>Palosaari</surname>
- <contrib>SDR API.</contrib>
- <affiliation>
- <address>
- <email>crope@iki.fi</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>1999</year>
- <year>2000</year>
- <year>2001</year>
- <year>2002</year>
- <year>2003</year>
- <year>2004</year>
- <year>2005</year>
- <year>2006</year>
- <year>2007</year>
- <year>2008</year>
- <year>2009</year>
- <year>2010</year>
- <year>2011</year>
- <year>2012</year>
- <year>2013</year>
- <year>2014</year>
- <year>2015</year>
- <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
-Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
- Pawel Osciak</holder>
- </copyright>
- <legalnotice>
- <para>Except when explicitly stated as GPL, programming examples within
- this part can be used and distributed without restrictions.</para>
- </legalnotice>
- <revhistory>
- <!-- Put document revisions here, newest first. -->
- <!-- API revisions (changes and additions of defines, enums,
-structs, ioctls) must be noted in more detail in the history chapter
-(compat.xml), along with the possible impact on existing drivers and
-applications. -->
-
- <revision>
- <revnumber>3.21</revnumber>
- <date>2015-02-13</date>
- <authorinitials>mcc</authorinitials>
- <revremark>Fix documentation for media controller device nodes and add support for DVB device nodes.
-Add support for Tuner sub-device.
- </revremark>
- </revision>
- <revision>
- <revnumber>3.19</revnumber>
- <date>2014-12-05</date>
- <authorinitials>hv</authorinitials>
- <revremark>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; and &v4l2-quantization; fields
-to &v4l2-pix-format;, &v4l2-pix-format-mplane; and &v4l2-mbus-framefmt;.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.17</revnumber>
- <date>2014-08-04</date>
- <authorinitials>lp, hv</authorinitials>
- <revremark>Extended &v4l2-pix-format;. Added format flags. Added compound control types
-and VIDIOC_QUERY_EXT_CTRL.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.15</revnumber>
- <date>2014-02-03</date>
- <authorinitials>hv, ap</authorinitials>
- <revremark>Update several sections of "Common API Elements": "Opening and Closing Devices"
-"Querying Capabilities", "Application Priority", "Video Inputs and Outputs", "Audio Inputs and Outputs"
-"Tuners and Modulators", "Video Standards" and "Digital Video (DV) Timings". Added SDR API.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.14</revnumber>
- <date>2013-11-25</date>
- <authorinitials>rr</authorinitials>
- <revremark>Set width and height as unsigned on v4l2_rect.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.11</revnumber>
- <date>2013-05-26</date>
- <authorinitials>hv</authorinitials>
- <revremark>Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.10</revnumber>
- <date>2013-03-25</date>
- <authorinitials>hv</authorinitials>
- <revremark>Remove obsolete and unused DV_PRESET ioctls:
- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
- VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability
- flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. Added VIDIOC_DBG_G_CHIP_INFO.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.9</revnumber>
- <date>2012-12-03</date>
- <authorinitials>sa, sn</authorinitials>
- <revremark>Added timestamp types to v4l2_buffer.
- Added V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.6</revnumber>
- <date>2012-07-02</date>
- <authorinitials>hv</authorinitials>
- <revremark>Added VIDIOC_ENUM_FREQ_BANDS.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.5</revnumber>
- <date>2012-05-07</date>
- <authorinitials>sa, sn, hv</authorinitials>
- <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev
- selections API. Improved the description of V4L2_CID_COLORFX
- control, added V4L2_CID_COLORFX_CBCR control.
- Added camera controls V4L2_CID_AUTO_EXPOSURE_BIAS,
- V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_IMAGE_STABILIZATION,
- V4L2_CID_ISO_SENSITIVITY, V4L2_CID_ISO_SENSITIVITY_AUTO,
- V4L2_CID_EXPOSURE_METERING, V4L2_CID_SCENE_MODE,
- V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START,
- V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS
- and V4L2_CID_AUTO_FOCUS_RANGE.
- Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
- VIDIOC_DV_TIMINGS_CAP.
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.4</revnumber>
- <date>2012-01-25</date>
- <authorinitials>sn</authorinitials>
- <revremark>Added <link linkend="jpeg-controls">JPEG compression
- control class.</link>
- </revremark>
- </revision>
-
- <revision>
- <revnumber>3.3</revnumber>
- <date>2012-01-11</date>
- <authorinitials>hv</authorinitials>
- <revremark>Added device_caps field to struct v4l2_capabilities.</revremark>
- </revision>
-
- <revision>
- <revnumber>3.2</revnumber>
- <date>2011-08-26</date>
- <authorinitials>hv</authorinitials>
- <revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark>
- </revision>
-
- <revision>
- <revnumber>3.1</revnumber>
- <date>2011-06-27</date>
- <authorinitials>mcc, po, hv</authorinitials>
- <revremark>Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.
- Standardize an error code for invalid ioctl.
- Added V4L2_CTRL_TYPE_BITMASK.</revremark>
- </revision>
-
- <revision>
- <revnumber>2.6.39</revnumber>
- <date>2011-03-01</date>
- <authorinitials>mcc, po</authorinitials>
- <revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark>
- </revision>
-
- <revision>
- <revnumber>2.6.37</revnumber>
- <date>2010-08-06</date>
- <authorinitials>hv</authorinitials>
- <revremark>Removed obsolete vtx (videotext) API.</revremark>
- </revision>
-
- <revision>
- <revnumber>2.6.33</revnumber>
- <date>2009-12-03</date>
- <authorinitials>mk</authorinitials>
- <revremark>Added documentation for the Digital Video timings API.</revremark>
- </revision>
-
- <revision>
- <revnumber>2.6.32</revnumber>
- <date>2009-08-31</date>
- <authorinitials>mcc</authorinitials>
- <revremark>Now, revisions will match the kernel version where
-the V4L2 API changes will be used by the Linux Kernel.
-Also added Remote Controller chapter.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.29</revnumber>
- <date>2009-08-26</date>
- <authorinitials>ev</authorinitials>
- <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.28</revnumber>
- <date>2009-08-26</date>
- <authorinitials>gl</authorinitials>
- <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.27</revnumber>
- <date>2009-08-15</date>
- <authorinitials>mcc</authorinitials>
- <revremark>Added libv4l and Remote Controller documentation;
-added v4l2grab and keytable application examples.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.26</revnumber>
- <date>2009-07-23</date>
- <authorinitials>hv</authorinitials>
- <revremark>Finalized the RDS capture API. Added modulator and RDS encoder
-capabilities. Added support for string controls.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.25</revnumber>
- <date>2009-01-18</date>
- <authorinitials>hv</authorinitials>
- <revremark>Added pixel formats VYUY, NV16 and NV61, and changed
-the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
-Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
-V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.24</revnumber>
- <date>2008-03-04</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Added pixel formats Y16 and SBGGR16, new controls
-and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.23</revnumber>
- <date>2007-08-30</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
-Clarified the byte order of packed pixel formats.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.22</revnumber>
- <date>2007-08-29</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Added the Video Output Overlay interface, new MPEG
-controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
-VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
-VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
-Clarifications in the cropping chapter, about RGB pixel formats, the
-mmap(), poll(), select(), read() and write() functions. Typographical
-fixes.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.21</revnumber>
- <date>2006-12-19</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.20</revnumber>
- <date>2006-11-24</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Clarified the purpose of the audioset field in
-struct v4l2_input and v4l2_output.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.19</revnumber>
- <date>2006-10-19</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.18</revnumber>
- <date>2006-10-18</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Added the description of extended controls by Hans
-Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.17</revnumber>
- <date>2006-10-12</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.16</revnumber>
- <date>2006-10-08</date>
- <authorinitials>mhs</authorinitials>
- <revremark>VIDIOC_ENUM_FRAMESIZES and
-VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.15</revnumber>
- <date>2006-09-23</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Cleaned up the bibliography, added BT.653 and
-BT.1119. capture.c/start_capturing() for user pointer I/O did not
-initialize the buffer index. Documented the V4L MPEG and MJPEG
-VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
-formats. See the history chapter for API changes.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.14</revnumber>
- <date>2006-09-14</date>
- <authorinitials>mr</authorinitials>
- <revremark>Added VIDIOC_ENUM_FRAMESIZES and
-VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
-digital devices.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.13</revnumber>
- <date>2006-04-07</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Corrected the description of struct v4l2_window
-clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
-defines.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.12</revnumber>
- <date>2006-02-03</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Corrected the description of struct
-v4l2_captureparm and v4l2_outputparm.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.11</revnumber>
- <date>2006-01-27</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Improved the description of struct
-v4l2_tuner.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.10</revnumber>
- <date>2006-01-10</date>
- <authorinitials>mhs</authorinitials>
- <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
-clarifications.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.9</revnumber>
- <date>2005-11-27</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Improved the 525 line numbering diagram. Hans
-Verkuil and I rewrote the sliced VBI section. He also contributed a
-VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
-selection example. Various updates.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.8</revnumber>
- <date>2004-10-04</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Somehow a piece of junk slipped into the capture
-example, removed.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.7</revnumber>
- <date>2004-09-19</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Fixed video standard selection, control
-enumeration, downscaling and aspect example. Added read and user
-pointer i/o to video capture example.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.6</revnumber>
- <date>2004-08-01</date>
- <authorinitials>mhs</authorinitials>
- <revremark>v4l2_buffer changes, added video capture example,
-various corrections.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.5</revnumber>
- <date>2003-11-05</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Pixel format erratum.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.4</revnumber>
- <date>2003-09-17</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Corrected source and Makefile to generate a PDF.
-SGML fixes. Added latest API changes. Closed gaps in the history
-chapter.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.3</revnumber>
- <date>2003-02-05</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Another draft, more corrections.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.2</revnumber>
- <date>2003-01-15</date>
- <authorinitials>mhs</authorinitials>
- <revremark>Second draft, with corrections pointed out by Gerd
-Knorr.</revremark>
- </revision>
-
- <revision>
- <revnumber>0.1</revnumber>
- <date>2002-12-01</date>
- <authorinitials>mhs</authorinitials>
- <revremark>First draft, based on documentation by Bill Dirks
-and discussions on the V4L mailing list.</revremark>
- </revision>
- </revhistory>
-</partinfo>
-
-<title>Video for Linux Two API Specification</title>
- <subtitle>Revision 3.19</subtitle>
-
- <chapter id="common">
- &sub-common;
- </chapter>
-
- <chapter id="pixfmt">
- &sub-pixfmt;
- </chapter>
-
- <chapter id="io">
- &sub-io;
- </chapter>
-
- <chapter id="devices">
- <title>Interfaces</title>
-
- <section id="capture"> &sub-dev-capture; </section>
- <section id="overlay"> &sub-dev-overlay; </section>
- <section id="output"> &sub-dev-output; </section>
- <section id="osd"> &sub-dev-osd; </section>
- <section id="codec"> &sub-dev-codec; </section>
- <section id="effect"> &sub-dev-effect; </section>
- <section id="raw-vbi"> &sub-dev-raw-vbi; </section>
- <section id="sliced"> &sub-dev-sliced-vbi; </section>
- <section id="ttx"> &sub-dev-teletext; </section>
- <section id="radio"> &sub-dev-radio; </section>
- <section id="rds"> &sub-dev-rds; </section>
- <section id="sdr"> &sub-dev-sdr; </section>
- <section id="event"> &sub-dev-event; </section>
- <section id="subdev"> &sub-dev-subdev; </section>
- </chapter>
-
- <chapter id="driver">
- &sub-driver;
- </chapter>
-
- <chapter id="libv4l">
- &sub-libv4l;
- </chapter>
-
- <chapter id="compat">
- &sub-compat;
- </chapter>
-
- <appendix id="user-func">
- <title>Function Reference</title>
-
- <!-- Keep this alphabetically sorted. -->
-
- &sub-close;
- &sub-ioctl;
- <!-- All ioctls go here. -->
- &sub-create-bufs;
- &sub-cropcap;
- &sub-dbg-g-chip-info;
- &sub-dbg-g-register;
- &sub-decoder-cmd;
- &sub-dqevent;
- &sub-dv-timings-cap;
- &sub-encoder-cmd;
- &sub-enumaudio;
- &sub-enumaudioout;
- &sub-enum-dv-timings;
- &sub-enum-fmt;
- &sub-enum-framesizes;
- &sub-enum-frameintervals;
- &sub-enum-freq-bands;
- &sub-enuminput;
- &sub-enumoutput;
- &sub-enumstd;
- &sub-expbuf;
- &sub-g-audio;
- &sub-g-audioout;
- &sub-g-crop;
- &sub-g-ctrl;
- &sub-g-dv-timings;
- &sub-g-edid;
- &sub-g-enc-index;
- &sub-g-ext-ctrls;
- &sub-g-fbuf;
- &sub-g-fmt;
- &sub-g-frequency;
- &sub-g-input;
- &sub-g-jpegcomp;
- &sub-g-modulator;
- &sub-g-output;
- &sub-g-parm;
- &sub-g-priority;
- &sub-g-selection;
- &sub-g-sliced-vbi-cap;
- &sub-g-std;
- &sub-g-tuner;
- &sub-log-status;
- &sub-overlay;
- &sub-prepare-buf;
- &sub-qbuf;
- &sub-querybuf;
- &sub-querycap;
- &sub-queryctrl;
- &sub-query-dv-timings;
- &sub-querystd;
- &sub-reqbufs;
- &sub-s-hw-freq-seek;
- &sub-streamon;
- &sub-subdev-enum-frame-interval;
- &sub-subdev-enum-frame-size;
- &sub-subdev-enum-mbus-code;
- &sub-subdev-g-crop;
- &sub-subdev-g-fmt;
- &sub-subdev-g-frame-interval;
- &sub-subdev-g-selection;
- &sub-subscribe-event;
- <!-- End of ioctls. -->
- &sub-mmap;
- &sub-munmap;
- &sub-open;
- &sub-poll;
- &sub-read;
- &sub-select;
- &sub-write;
- </appendix>
-
- <appendix>
- <title>Common definitions for V4L2 and V4L2 subdev interfaces</title>
- &sub-selections-common;
- </appendix>
-
- <appendix id="videodev">
- <title>Video For Linux Two Header File</title>
- &sub-videodev2-h;
- </appendix>
-
- <appendix id="capture-example">
- <title>Video Capture Example</title>
- &sub-capture-c;
- </appendix>
-
- <appendix id="v4l2grab-example">
- <title>Video Grabber example using libv4l</title>
- <para>This program demonstrates how to grab V4L2 images in ppm format by
-using libv4l handlers. The advantage is that this grabber can potentially work
-with any V4L2 driver.</para>
- &sub-v4l2grab-c;
- </appendix>
-
- &sub-media-indices;
-
- &sub-biblio;
-
diff --git a/Documentation/DocBook/media/v4l/v4l2grab.c.xml b/Documentation/DocBook/media/v4l/v4l2grab.c.xml
deleted file mode 100644
index bed12e40be27..000000000000
--- a/Documentation/DocBook/media/v4l/v4l2grab.c.xml
+++ /dev/null
@@ -1,164 +0,0 @@
-<programlisting>
-/* V4L2 video picture grabber
- Copyright (C) 2009 Mauro Carvalho Chehab &lt;mchehab@infradead.org&gt;
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation version 2 of the License.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- */
-
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-#include &lt;string.h&gt;
-#include &lt;fcntl.h&gt;
-#include &lt;errno.h&gt;
-#include &lt;sys/ioctl.h&gt;
-#include &lt;sys/types.h&gt;
-#include &lt;sys/time.h&gt;
-#include &lt;sys/mman.h&gt;
-#include &lt;linux/videodev2.h&gt;
-#include "../libv4l/include/libv4l2.h"
-
-#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
-
-struct buffer {
- void *start;
- size_t length;
-};
-
-static void xioctl(int fh, int request, void *arg)
-{
- int r;
-
- do {
- r = v4l2_ioctl(fh, request, arg);
- } while (r == -1 &amp;&amp; ((errno == EINTR) || (errno == EAGAIN)));
-
- if (r == -1) {
- fprintf(stderr, "error %d, %s\n", errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-}
-
-int main(int argc, char **argv)
-{
- struct <link linkend="v4l2-format">v4l2_format</link> fmt;
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
- struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
- enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
- fd_set fds;
- struct timeval tv;
- int r, fd = -1;
- unsigned int i, n_buffers;
- char *dev_name = "/dev/video0";
- char out_name[256];
- FILE *fout;
- struct buffer *buffers;
-
- fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
- if (fd &lt; 0) {
- perror("Cannot open device");
- exit(EXIT_FAILURE);
- }
-
- CLEAR(fmt);
- fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- fmt.fmt.pix.width = 640;
- fmt.fmt.pix.height = 480;
- fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
- fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
- xioctl(fd, VIDIOC_S_FMT, &amp;fmt);
- if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
- printf("Libv4l didn't accept RGB24 format. Can't proceed.\n");
- exit(EXIT_FAILURE);
- }
- if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
- printf("Warning: driver is sending image at %dx%d\n",
- fmt.fmt.pix.width, fmt.fmt.pix.height);
-
- CLEAR(req);
- req.count = 2;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_MMAP;
- xioctl(fd, VIDIOC_REQBUFS, &amp;req);
-
- buffers = calloc(req.count, sizeof(*buffers));
- for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = n_buffers;
-
- xioctl(fd, VIDIOC_QUERYBUF, &amp;buf);
-
- buffers[n_buffers].length = buf.length;
- buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
- PROT_READ | PROT_WRITE, MAP_SHARED,
- fd, buf.m.offset);
-
- if (MAP_FAILED == buffers[n_buffers].start) {
- perror("mmap");
- exit(EXIT_FAILURE);
- }
- }
-
- for (i = 0; i &lt; n_buffers; ++i) {
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = i;
- xioctl(fd, VIDIOC_QBUF, &amp;buf);
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- xioctl(fd, VIDIOC_STREAMON, &amp;type);
- for (i = 0; i &lt; 20; i++) {
- do {
- FD_ZERO(&amp;fds);
- FD_SET(fd, &amp;fds);
-
- /* Timeout. */
- tv.tv_sec = 2;
- tv.tv_usec = 0;
-
- r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
- } while ((r == -1 &amp;&amp; (errno = EINTR)));
- if (r == -1) {
- perror("select");
- return errno;
- }
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- xioctl(fd, VIDIOC_DQBUF, &amp;buf);
-
- sprintf(out_name, "out%03d.ppm", i);
- fout = fopen(out_name, "w");
- if (!fout) {
- perror("Cannot open image");
- exit(EXIT_FAILURE);
- }
- fprintf(fout, "P6\n%d %d 255\n",
- fmt.fmt.pix.width, fmt.fmt.pix.height);
- fwrite(buffers[buf.index].start, buf.bytesused, 1, fout);
- fclose(fout);
-
- xioctl(fd, VIDIOC_QBUF, &amp;buf);
- }
-
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- xioctl(fd, VIDIOC_STREAMOFF, &amp;type);
- for (i = 0; i &lt; n_buffers; ++i)
- v4l2_munmap(buffers[i].start, buffers[i].length);
- v4l2_close(fd);
-
- return 0;
-}
-</programlisting>
diff --git a/Documentation/DocBook/media/v4l/vbi_525.pdf b/Documentation/DocBook/media/v4l/vbi_525.pdf
deleted file mode 100644
index 9e72c25b208d..000000000000
--- a/Documentation/DocBook/media/v4l/vbi_525.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_625.pdf b/Documentation/DocBook/media/v4l/vbi_625.pdf
deleted file mode 100644
index 765235e33a4d..000000000000
--- a/Documentation/DocBook/media/v4l/vbi_625.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_hsync.pdf b/Documentation/DocBook/media/v4l/vbi_hsync.pdf
deleted file mode 100644
index 200b668189bf..000000000000
--- a/Documentation/DocBook/media/v4l/vbi_hsync.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
deleted file mode 100644
index 9b700a5f4df7..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-<refentry id="vidioc-create-bufs">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_CREATE_BUFS</refname>
- <refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer
- I/O</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_create_buffers *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_CREATE_BUFS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>This ioctl is used to create buffers for <link linkend="mmap">memory
-mapped</link> or <link linkend="userp">user pointer</link> or <link
-linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
-addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
-control over buffers is required. This ioctl can be called multiple times to
-create buffers of different sizes.</para>
-
- <para>To allocate the device buffers applications must initialize the
-relevant fields of the <structname>v4l2_create_buffers</structname> structure.
-The <structfield>count</structfield> field must be set to the number of
-requested buffers, the <structfield>memory</structfield> field specifies the
-requested I/O method and the <structfield>reserved</structfield> array must be
-zeroed.</para>
-
- <para>The <structfield>format</structfield> field specifies the image format
-that the buffers must be able to handle. The application has to fill in this
-&v4l2-format;. Usually this will be done using the
-<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
-to ensure that the requested format is supported by the driver. Unsupported
-formats will result in an error.</para>
-
- <para>The buffers created by this ioctl will have as minimum size the size
-defined by the <structfield>format.pix.sizeimage</structfield> field. If the
-<structfield>format.pix.sizeimage</structfield> field is less than the minimum
-required for the given format, then <structfield>sizeimage</structfield> will be
-increased by the driver to that minimum to allocate the buffers. If it is
-larger, then the value will be used as-is. The same applies to the
-<structfield>sizeimage</structfield> field of the
-<structname>v4l2_plane_pix_format</structname> structure in the case of
-multiplanar formats.</para>
-
- <para>When the ioctl is called with a pointer to this structure the driver
-will attempt to allocate up to the requested number of buffers and store the
-actual number allocated and the starting index in the
-<structfield>count</structfield> and the <structfield>index</structfield> fields
-respectively. On return <structfield>count</structfield> can be smaller than
-the number requested. The driver may also increase buffer sizes if required,
-however, it will not update <structfield>sizeimage</structfield> field values.
-The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
-information.</para>
-
- <table pgwide="1" frame="none" id="v4l2-create-buffers">
- <title>struct <structname>v4l2_create_buffers</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>The starting buffer index, returned by the driver.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>count</structfield></entry>
- <entry>The number of buffers requested or granted. If count == 0, then
- <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield>
- to the current number of created buffers, and it will check the validity of
- <structfield>memory</structfield> and <structfield>format.type</structfield>.
- If those are invalid -1 is returned and errno is set to &EINVAL;,
- otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will
- never set errno to &EBUSY; in this particular case.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>memory</structfield></entry>
- <entry>Applications set this field to
-<constant>V4L2_MEMORY_MMAP</constant>,
-<constant>V4L2_MEMORY_DMABUF</constant> or
-<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
-/></entry>
- </row>
- <row>
- <entry>&v4l2-format;</entry>
- <entry><structfield>format</structfield></entry>
- <entry>Filled in by the application, preserved by the driver.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>A place holder for future extensions.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>ENOMEM</errorcode></term>
- <listitem>
- <para>No memory to allocate buffers for <link linkend="mmap">memory
-mapped</link> I/O.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The buffer type (<structfield>format.type</structfield> field),
-requested I/O method (<structfield>memory</structfield>) or format
-(<structfield>format</structfield> field) is not valid.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml
deleted file mode 100644
index 50cb940cbe5c..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml
+++ /dev/null
@@ -1,166 +0,0 @@
-<refentry id="vidioc-cropcap">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_CROPCAP</refname>
- <refpurpose>Information about the video cropping and scaling abilities</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_cropcap
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_CROPCAP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Applications use this function to query the cropping
-limits, the pixel aspect of images and to calculate scale factors.
-They set the <structfield>type</structfield> field of a v4l2_cropcap
-structure to the respective buffer (stream) type and call the
-<constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this
-structure. Drivers fill the rest of the structure. The results are
-constant except when switching the video standard. Remember this
-switch can occur implicit when switching the video input or
-output.</para>
-
-<para>Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
-instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
-and use <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>.</para>
-
- <para>This ioctl must be implemented for video capture or output devices that
-support cropping and/or scaling and/or have non-square pixels, and for overlay devices.</para>
-
- <table pgwide="1" frame="none" id="v4l2-cropcap">
- <title>struct <structname>v4l2_cropcap</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the data stream, set by the application.
-Only these types are valid here:
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and
-<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry>
- </row>
- <row>
- <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
- <entry><structfield>bounds</structfield></entry>
- <entry>Defines the window within capturing or output is
-possible, this may exclude for example the horizontal and vertical
-blanking areas. The cropping rectangle cannot exceed these limits.
-Width and height are defined in pixels, the driver writer is free to
-choose origin and units of the coordinate system in the analog
-domain.</entry>
- </row>
- <row>
- <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
- <entry><structfield>defrect</structfield></entry>
- <entry>Default cropping rectangle, it shall cover the
-"whole picture". Assuming pixel aspect 1/1 this could be for example a
-640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
-768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
-the active picture area. The same co-ordinate system as for
- <structfield>bounds</structfield> is used.</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>pixelaspect</structfield></entry>
- <entry><para>This is the pixel aspect (y / x) when no
-scaling is applied, the ratio of the actual sampling
-frequency and the frequency required to get square
-pixels.</para><para>When cropping coordinates refer to square pixels,
-the driver sets <structfield>pixelaspect</structfield> to 1/1. Other
-common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
-according to [<xref linkend="itu601" />].</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- NB this table is duplicated in the overlay chapter. -->
-
- <table pgwide="1" frame="none" id="v4l2-rect-crop">
- <title>struct <structname>v4l2_rect</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__s32</entry>
- <entry><structfield>left</structfield></entry>
- <entry>Horizontal offset of the top, left corner of the
-rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>top</structfield></entry>
- <entry>Vertical offset of the top, left corner of the
-rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Width of the rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Height of the rectangle, in pixels.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-cropcap; <structfield>type</structfield> is
-invalid.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml
deleted file mode 100644
index 4c4603c135fe..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml
+++ /dev/null
@@ -1,207 +0,0 @@
-<refentry id="vidioc-dbg-g-chip-info">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_INFO</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_DBG_G_CHIP_INFO</refname>
- <refpurpose>Identify the chips on a TV card</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_dbg_chip_info
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_DBG_G_CHIP_INFO</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link
-linkend="experimental">experimental</link> interface and may change in
-the future.</para>
- </note>
-
- <para>For driver debugging purposes this ioctl allows test
-applications to query the driver about the chips present on the TV
-card. Regular applications must not use it. When you found a chip
-specific bug, please contact the linux-media mailing list (&v4l-ml;)
-so it can be fixed.</para>
-
- <para>Additionally the Linux kernel must be compiled with the
-<constant>CONFIG_VIDEO_ADV_DEBUG</constant> option to enable this ioctl.</para>
-
- <para>To query the driver applications must initialize the
-<structfield>match.type</structfield> and
-<structfield>match.addr</structfield> or <structfield>match.name</structfield>
-fields of a &v4l2-dbg-chip-info;
-and call <constant>VIDIOC_DBG_G_CHIP_INFO</constant> with a pointer to
-this structure. On success the driver stores information about the
-selected chip in the <structfield>name</structfield> and
-<structfield>flags</structfield> fields.</para>
-
- <para>When <structfield>match.type</structfield> is
-<constant>V4L2_CHIP_MATCH_BRIDGE</constant>,
-<structfield>match.addr</structfield> selects the nth bridge 'chip'
-on the TV card. You can enumerate all chips by starting at zero and
-incrementing <structfield>match.addr</structfield> by one until
-<constant>VIDIOC_DBG_G_CHIP_INFO</constant> fails with an &EINVAL;.
-The number zero always selects the bridge chip itself, &eg; the chip
-connected to the PCI or USB bus. Non-zero numbers identify specific
-parts of the bridge chip such as an AC97 register block.</para>
-
- <para>When <structfield>match.type</structfield> is
-<constant>V4L2_CHIP_MATCH_SUBDEV</constant>,
-<structfield>match.addr</structfield> selects the nth sub-device. This
-allows you to enumerate over all sub-devices.</para>
-
- <para>On success, the <structfield>name</structfield> field will
-contain a chip name and the <structfield>flags</structfield> field will
-contain <constant>V4L2_CHIP_FL_READABLE</constant> if the driver supports
-reading registers from the device or <constant>V4L2_CHIP_FL_WRITABLE</constant>
-if the driver supports writing registers to the device.</para>
-
- <para>We recommended the <application>v4l2-dbg</application>
-utility over calling this ioctl directly. It is available from the
-LinuxTV v4l-dvb repository; see <ulink
-url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
-access instructions.</para>
-
- <!-- Note for convenience vidioc-dbg-g-register.sgml
- contains a duplicate of this table. -->
- <table pgwide="1" frame="none" id="name-v4l2-dbg-match">
- <title>struct <structname>v4l2_dbg_match</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>See <xref linkend="name-chip-match-types" /> for a list of
-possible types.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry>(anonymous)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>addr</structfield></entry>
- <entry>Match a chip by this number, interpreted according
-to the <structfield>type</structfield> field.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>char</entry>
- <entry><structfield>name[32]</structfield></entry>
- <entry>Match a chip by this name, interpreted according
-to the <structfield>type</structfield> field. Currently unused.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-dbg-chip-info">
- <title>struct <structname>v4l2_dbg_chip_info</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>struct v4l2_dbg_match</entry>
- <entry><structfield>match</structfield></entry>
- <entry>How to match the chip, see <xref linkend="name-v4l2-dbg-match" />.</entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>name[32]</structfield></entry>
- <entry>The name of the chip.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Set by the driver. If <constant>V4L2_CHIP_FL_READABLE</constant>
-is set, then the driver supports reading registers from the device. If
-<constant>V4L2_CHIP_FL_WRITABLE</constant> is set, then it supports writing registers.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved[8]</structfield></entry>
- <entry>Reserved fields, both application and driver must set these to 0.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- Note for convenience vidioc-dbg-g-register.sgml
- contains a duplicate of this table. -->
- <table pgwide="1" frame="none" id="name-chip-match-types">
- <title>Chip Match Types</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry>
- <entry>0</entry>
- <entry>Match the nth chip on the card, zero for the
- bridge chip. Does not match sub-devices.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry>
- <entry>4</entry>
- <entry>Match the nth sub-device.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <structfield>match_type</structfield> is invalid or
-no device could be matched.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
deleted file mode 100644
index 3d038e75d12b..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
+++ /dev/null
@@ -1,227 +0,0 @@
-<refentry id="vidioc-dbg-g-register">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_DBG_G_REGISTER</refname>
- <refname>VIDIOC_DBG_S_REGISTER</refname>
- <refpurpose>Read or write hardware registers</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_dbg_register
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link linkend="experimental">experimental</link>
-interface and may change in the future.</para>
- </note>
-
- <para>For driver debugging purposes these ioctls allow test
-applications to access hardware registers directly. Regular
-applications must not use them.</para>
-
- <para>Since writing or even reading registers can jeopardize the
-system security, its stability and damage the hardware, both ioctls
-require superuser privileges. Additionally the Linux kernel must be
-compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
-to enable these ioctls.</para>
-
- <para>To write a register applications must initialize all fields
-of a &v4l2-dbg-register; except for <structfield>size</structfield> and call
-<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
-structure. The <structfield>match.type</structfield> and
-<structfield>match.addr</structfield> or <structfield>match.name</structfield>
-fields select a chip on the TV
-card, the <structfield>reg</structfield> field specifies a register
-number and the <structfield>val</structfield> field the value to be
-written into the register.</para>
-
- <para>To read a register applications must initialize the
-<structfield>match.type</structfield>,
-<structfield>match.addr</structfield> or <structfield>match.name</structfield> and
-<structfield>reg</structfield> fields, and call
-<constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this
-structure. On success the driver stores the register value in the
-<structfield>val</structfield> field and the size (in bytes) of the
-value in <structfield>size</structfield>.</para>
-
- <para>When <structfield>match.type</structfield> is
-<constant>V4L2_CHIP_MATCH_BRIDGE</constant>,
-<structfield>match.addr</structfield> selects the nth non-sub-device chip
-on the TV card. The number zero always selects the host chip, &eg; the
-chip connected to the PCI or USB bus. You can find out which chips are
-present with the &VIDIOC-DBG-G-CHIP-INFO; ioctl.</para>
-
- <para>When <structfield>match.type</structfield> is
-<constant>V4L2_CHIP_MATCH_SUBDEV</constant>,
-<structfield>match.addr</structfield> selects the nth sub-device.</para>
-
- <para>These ioctls are optional, not all drivers may support them.
-However when a driver supports these ioctls it must also support
-&VIDIOC-DBG-G-CHIP-INFO;. Conversely it may support
-<constant>VIDIOC_DBG_G_CHIP_INFO</constant> but not these ioctls.</para>
-
- <para><constant>VIDIOC_DBG_G_REGISTER</constant> and
-<constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux
-2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para>
-
- <para>We recommended the <application>v4l2-dbg</application>
-utility over calling these ioctls directly. It is available from the
-LinuxTV v4l-dvb repository; see <ulink
-url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
-access instructions.</para>
-
- <!-- Note for convenience vidioc-dbg-g-chip-info.sgml
- contains a duplicate of this table. -->
- <table pgwide="1" frame="none" id="v4l2-dbg-match">
- <title>struct <structname>v4l2_dbg_match</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>See <xref linkend="chip-match-types" /> for a list of
-possible types.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry>(anonymous)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>addr</structfield></entry>
- <entry>Match a chip by this number, interpreted according
-to the <structfield>type</structfield> field.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>char</entry>
- <entry><structfield>name[32]</structfield></entry>
- <entry>Match a chip by this name, interpreted according
-to the <structfield>type</structfield> field. Currently unused.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <table pgwide="1" frame="none" id="v4l2-dbg-register">
- <title>struct <structname>v4l2_dbg_register</structname></title>
- <tgroup cols="4">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c4" />
- <tbody valign="top">
- <row>
- <entry>struct v4l2_dbg_match</entry>
- <entry><structfield>match</structfield></entry>
- <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>size</structfield></entry>
- <entry>The register size in bytes.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>reg</structfield></entry>
- <entry>A register number.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>val</structfield></entry>
- <entry>The value read from, or to be written into the
-register.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- Note for convenience vidioc-dbg-g-chip-info.sgml
- contains a duplicate of this table. -->
- <table pgwide="1" frame="none" id="chip-match-types">
- <title>Chip Match Types</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry>
- <entry>0</entry>
- <entry>Match the nth chip on the card, zero for the
- bridge chip. Does not match sub-devices.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry>
- <entry>4</entry>
- <entry>Match the nth sub-device.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EPERM</errorcode></term>
- <listitem>
- <para>Insufficient permissions. Root privileges are required
-to execute these ioctls.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
deleted file mode 100644
index 9215627b04c7..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml
+++ /dev/null
@@ -1,249 +0,0 @@
-<refentry id="vidioc-decoder-cmd">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_DECODER_CMD</refname>
- <refname>VIDIOC_TRY_DECODER_CMD</refname>
- <refpurpose>Execute an decoder command</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_decoder_cmd *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>These ioctls control an audio/video (usually MPEG-) decoder.
-<constant>VIDIOC_DECODER_CMD</constant> sends a command to the
-decoder, <constant>VIDIOC_TRY_DECODER_CMD</constant> can be used to
-try a command without actually executing it. To send a command applications
-must initialize all fields of a &v4l2-decoder-cmd; and call
-<constant>VIDIOC_DECODER_CMD</constant> or <constant>VIDIOC_TRY_DECODER_CMD</constant>
-with a pointer to this structure.</para>
-
- <para>The <structfield>cmd</structfield> field must contain the
-command code. Some commands use the <structfield>flags</structfield> field for
-additional information.
-</para>
-
- <para>A <function>write</function>() or &VIDIOC-STREAMON; call sends an implicit
-START command to the decoder if it has not been started yet.
-</para>
-
- <para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming
-file descriptor sends an implicit immediate STOP command to the decoder, and all
-buffered data is discarded.</para>
-
- <para>These ioctls are optional, not all drivers may support
-them. They were introduced in Linux 3.3.</para>
-
- <table pgwide="1" frame="none" id="v4l2-decoder-cmd">
- <title>struct <structname>v4l2_decoder_cmd</structname></title>
- <tgroup cols="5">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>cmd</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>The decoder command, see <xref linkend="decoder-cmds" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry></entry>
- <entry></entry>
- <entry>Flags to go with the command. If no flags are defined for
-this command, drivers and applications must set this field to zero.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry>(anonymous)</entry>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct</entry>
- <entry><structfield>start</structfield></entry>
- <entry></entry>
- <entry>Structure containing additional data for the
-<constant>V4L2_DEC_CMD_START</constant> command.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>__s32</entry>
- <entry><structfield>speed</structfield></entry>
- <entry>Playback speed and direction. The playback speed is defined as
-<structfield>speed</structfield>/1000 of the normal speed. So 1000 is normal playback.
-Negative numbers denote reverse playback, so -1000 does reverse playback at normal
-speed. Speeds -1, 0 and 1 have special meanings: speed 0 is shorthand for 1000
-(normal playback). A speed of 1 steps just one frame forward, a speed of -1 steps
-just one frame back.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>format</structfield></entry>
- <entry>Format restrictions. This field is set by the driver, not the
-application. Possible values are <constant>V4L2_DEC_START_FMT_NONE</constant> if
-there are no format restrictions or <constant>V4L2_DEC_START_FMT_GOP</constant>
-if the decoder operates on full GOPs (<wordasword>Group Of Pictures</wordasword>).
-This is usually the case for reverse playback: the decoder needs full GOPs, which
-it can then play in reverse order. So to implement reverse playback the application
-must feed the decoder the last GOP in the video file, then the GOP before that, etc. etc.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct</entry>
- <entry><structfield>stop</structfield></entry>
- <entry></entry>
- <entry>Structure containing additional data for the
-<constant>V4L2_DEC_CMD_STOP</constant> command.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>__u64</entry>
- <entry><structfield>pts</structfield></entry>
- <entry>Stop playback at this <structfield>pts</structfield> or immediately
-if the playback is already past that timestamp. Leave to 0 if you want to stop after the
-last frame was decoded.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct</entry>
- <entry><structfield>raw</structfield></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>data</structfield>[16]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="decoder-cmds">
- <title>Decoder Commands</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_DEC_CMD_START</constant></entry>
- <entry>0</entry>
- <entry>Start the decoder. When the decoder is already
-running or paused, this command will just change the playback speed.
-That means that calling <constant>V4L2_DEC_CMD_START</constant> when
-the decoder was paused will <emphasis>not</emphasis> resume the decoder.
-You have to explicitly call <constant>V4L2_DEC_CMD_RESUME</constant> for that.
-This command has one flag:
-<constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant>. If set, then audio will
-be muted when playing back at a non-standard speed.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_DEC_CMD_STOP</constant></entry>
- <entry>1</entry>
- <entry>Stop the decoder. When the decoder is already stopped,
-this command does nothing. This command has two flags:
-if <constant>V4L2_DEC_CMD_STOP_TO_BLACK</constant> is set, then the decoder will
-set the picture to black after it stopped decoding. Otherwise the last image will
-repeat. If <constant>V4L2_DEC_CMD_STOP_IMMEDIATELY</constant> is set, then the decoder
-stops immediately (ignoring the <structfield>pts</structfield> value), otherwise it
-will keep decoding until timestamp >= pts or until the last of the pending data from
-its internal buffers was decoded.
-</entry>
- </row>
- <row>
- <entry><constant>V4L2_DEC_CMD_PAUSE</constant></entry>
- <entry>2</entry>
- <entry>Pause the decoder. When the decoder has not been
-started yet, the driver will return an &EPERM;. When the decoder is
-already paused, this command does nothing. This command has one flag:
-if <constant>V4L2_DEC_CMD_PAUSE_TO_BLACK</constant> is set, then set the
-decoder output to black when paused.
-</entry>
- </row>
- <row>
- <entry><constant>V4L2_DEC_CMD_RESUME</constant></entry>
- <entry>3</entry>
- <entry>Resume decoding after a PAUSE command. When the
-decoder has not been started yet, the driver will return an &EPERM;.
-When the decoder is already running, this command does nothing. No
-flags are defined for this command.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <structfield>cmd</structfield> field is invalid.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EPERM</errorcode></term>
- <listitem>
- <para>The application sent a PAUSE or RESUME command when
-the decoder was not running.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
deleted file mode 100644
index 50ccd33948c1..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ /dev/null
@@ -1,468 +0,0 @@
-<refentry id="vidioc-dqevent">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_DQEVENT</refname>
- <refpurpose>Dequeue event</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_event
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_DQEVENT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Dequeue an event from a video device. No input is required
- for this ioctl. All the fields of the &v4l2-event; structure are
- filled by the driver. The file handle will also receive exceptions
- which the application may get by e.g. using the select system
- call.</para>
-
- <table frame="none" pgwide="1" id="v4l2-event">
- <title>struct <structname>v4l2_event</structname></title>
- <tgroup cols="4">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>Type of the event, see <xref linkend="event-type" />.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield>u</structfield></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-event-vsync;</entry>
- <entry><structfield>vsync</structfield></entry>
- <entry>Event data for event <constant>V4L2_EVENT_VSYNC</constant>.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-event-ctrl;</entry>
- <entry><structfield>ctrl</structfield></entry>
- <entry>Event data for event <constant>V4L2_EVENT_CTRL</constant>.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-event-frame-sync;</entry>
- <entry><structfield>frame_sync</structfield></entry>
- <entry>Event data for event
- <constant>V4L2_EVENT_FRAME_SYNC</constant>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-event-motion-det;</entry>
- <entry><structfield>motion_det</structfield></entry>
- <entry>Event data for event V4L2_EVENT_MOTION_DET.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-event-src-change;</entry>
- <entry><structfield>src_change</structfield></entry>
- <entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u8</entry>
- <entry><structfield>data</structfield>[64]</entry>
- <entry>Event data. Defined by the event type. The union
- should be used to define easily accessible type for
- events.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pending</structfield></entry>
- <entry></entry>
- <entry>Number of pending events excluding this one.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>sequence</structfield></entry>
- <entry></entry>
- <entry>Event sequence number. The sequence number is
- incremented for every subscribed event that takes place.
- If sequence numbers are not contiguous it means that
- events have been lost.
- </entry>
- </row>
- <row>
- <entry>struct timespec</entry>
- <entry><structfield>timestamp</structfield></entry>
- <entry></entry>
- <entry>Event timestamp.</entry>
- </row>
- <row>
- <entry>u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry></entry>
- <entry>The ID associated with the event source. If the event does not
- have an associated ID (this depends on the event type), then this
- is 0.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry></entry>
- <entry>Reserved for future extensions. Drivers must set
- the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="event-type">
- <title>Event Types</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EVENT_ALL</constant></entry>
- <entry>0</entry>
- <entry>All events. V4L2_EVENT_ALL is valid only for
- VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_VSYNC</constant></entry>
- <entry>1</entry>
- <entry>This event is triggered on the vertical sync.
- This event has a &v4l2-event-vsync; associated with it.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_EOS</constant></entry>
- <entry>2</entry>
- <entry>This event is triggered when the end of a stream is reached.
- This is typically used with MPEG decoders to report to the application
- when the last of the MPEG stream has been decoded.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_CTRL</constant></entry>
- <entry>3</entry>
- <entry><para>This event requires that the <structfield>id</structfield>
- matches the control ID from which you want to receive events.
- This event is triggered if the control's value changes, if a
- button control is pressed or if the control's flags change.
- This event has a &v4l2-event-ctrl; associated with it. This struct
- contains much of the same information as &v4l2-queryctrl; and
- &v4l2-control;.</para>
-
- <para>If the event is generated due to a call to &VIDIOC-S-CTRL; or
- &VIDIOC-S-EXT-CTRLS;, then the event will <emphasis>not</emphasis> be sent to
- the file handle that called the ioctl function. This prevents
- nasty feedback loops. If you <emphasis>do</emphasis> want to get the
- event, then set the <constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant>
- flag.
- </para>
-
- <para>This event type will ensure that no information is lost when
- more events are raised than there is room internally. In that
- case the &v4l2-event-ctrl; of the second-oldest event is kept,
- but the <structfield>changes</structfield> field of the
- second-oldest event is ORed with the <structfield>changes</structfield>
- field of the oldest event.</para>
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry>
- <entry>4</entry>
- <entry>
- <para>Triggered immediately when the reception of a
- frame has begun. This event has a
- &v4l2-event-frame-sync; associated with it.</para>
-
- <para>If the hardware needs to be stopped in the case of a
- buffer underrun it might not be able to generate this event.
- In such cases the <structfield>frame_sequence</structfield>
- field in &v4l2-event-frame-sync; will not be incremented. This
- causes two consecutive frame sequence numbers to have n times
- frame interval in between them.</para>
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_SOURCE_CHANGE</constant></entry>
- <entry>5</entry>
- <entry>
- <para>This event is triggered when a source parameter change is
- detected during runtime by the video device. It can be a
- runtime resolution change triggered by a video decoder or the
- format change happening on an input connector.
- This event requires that the <structfield>id</structfield>
- matches the input index (when used with a video device node)
- or the pad index (when used with a subdevice node) from which
- you want to receive events.</para>
-
- <para>This event has a &v4l2-event-src-change; associated
- with it. The <structfield>changes</structfield> bitfield denotes
- what has changed for the subscribed pad. If multiple events
- occurred before application could dequeue them, then the changes
- will have the ORed value of all the events generated.</para>
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_MOTION_DET</constant></entry>
- <entry>6</entry>
- <entry>
- <para>Triggered whenever the motion detection state for one or more of the regions
- changes. This event has a &v4l2-event-motion-det; associated with it.</para>
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
- <entry>0x08000000</entry>
- <entry>Base event number for driver-private events.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-event-vsync">
- <title>struct <structname>v4l2_event_vsync</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>field</structfield></entry>
- <entry>The upcoming field. See &v4l2-field;.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-event-ctrl">
- <title>struct <structname>v4l2_event_ctrl</structname></title>
- <tgroup cols="4">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>changes</structfield></entry>
- <entry></entry>
- <entry>A bitmask that tells what has changed. See <xref linkend="ctrl-changes-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>The type of the control. See &v4l2-ctrl-type;.</entry>
- </row>
- <row>
- <entry>union (anonymous)</entry>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>__s32</entry>
- <entry><structfield>value</structfield></entry>
- <entry>The 32-bit value of the control for 32-bit control types.
- This is 0 for string controls since the value of a string
- cannot be passed using &VIDIOC-DQEVENT;.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__s64</entry>
- <entry><structfield>value64</structfield></entry>
- <entry>The 64-bit value of the control for 64-bit control types.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry></entry>
- <entry>The control flags. See <xref linkend="control-flags" />.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>minimum</structfield></entry>
- <entry></entry>
- <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>maximum</structfield></entry>
- <entry></entry>
- <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>step</structfield></entry>
- <entry></entry>
- <entry>The step value of the control. See &v4l2-queryctrl;.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>default_value</structfield></entry>
- <entry></entry>
- <entry>The default value value of the control. See &v4l2-queryctrl;.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-event-frame-sync">
- <title>struct <structname>v4l2_event_frame_sync</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>frame_sequence</structfield></entry>
- <entry>
- The sequence number of the frame being received.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-event-src-change">
- <title>struct <structname>v4l2_event_src_change</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>changes</structfield></entry>
- <entry>
- A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-event-motion-det">
- <title>struct <structname>v4l2_event_motion_det</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>
- Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant>
- is set, then the <structfield>frame_sequence</structfield> field is valid,
- otherwise that field should be ignored.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>frame_sequence</structfield></entry>
- <entry>
- The sequence number of the frame being received. Only valid if the
- <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>region_mask</structfield></entry>
- <entry>
- The bitmask of the regions that reported motion. There is at least one
- region. If this field is 0, then no motion was detected at all.
- If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control
- (see <xref linkend="detect-controls" />) to assign a different region
- to each cell in the motion detection grid, then that all cells
- are automatically assigned to the default region 0.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="ctrl-changes-flags">
- <title>Control Changes</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry>
- <entry>0x0001</entry>
- <entry>This control event was triggered because the value of the control
- changed. Special cases: Volatile controls do no generate this event;
- If a control has the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant>
- flag set, then this event is sent as well, regardless its value.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry>
- <entry>0x0002</entry>
- <entry>This control event was triggered because the control flags
- changed.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_CTRL_CH_RANGE</constant></entry>
- <entry>0x0004</entry>
- <entry>This control event was triggered because the minimum,
- maximum, step or the default value of the control changed.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="src-changes-flags">
- <title>Source Changes</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry>
- <entry>0x0001</entry>
- <entry>This event gets triggered when a resolution change is
- detected at an input. This can come from an input connector or
- from a video decoder.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
deleted file mode 100644
index a2017bfcaed2..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
+++ /dev/null
@@ -1,214 +0,0 @@
-<refentry id="vidioc-dv-timings-cap">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_DV_TIMINGS_CAP</refname>
- <refname>VIDIOC_SUBDEV_DV_TIMINGS_CAP</refname>
- <refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_dv_timings_cap *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>To query the capabilities of the DV receiver/transmitter applications
-can call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node
-and the driver will fill in the structure. Note that drivers may return
-different values after switching the video input or output.</para>
-
- <para>When implemented by the driver DV capabilities of subdevices can be
-queried by calling the <constant>VIDIOC_SUBDEV_DV_TIMINGS_CAP</constant> ioctl
-directly on a subdevice node. The capabilities are specific to inputs (for DV
-receivers) or outputs (for DV transmitters), applications must specify the
-desired pad number in the &v4l2-dv-timings-cap; <structfield>pad</structfield>
-field. Attempts to query capabilities on a pad that doesn't support them will
-return an &EINVAL;.</para>
-
- <table pgwide="1" frame="none" id="v4l2-bt-timings-cap">
- <title>struct <structname>v4l2_bt_timings_cap</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>min_width</structfield></entry>
- <entry>Minimum width of the active video in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>max_width</structfield></entry>
- <entry>Maximum width of the active video in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>min_height</structfield></entry>
- <entry>Minimum height of the active video in lines.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>max_height</structfield></entry>
- <entry>Maximum height of the active video in lines.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>min_pixelclock</structfield></entry>
- <entry>Minimum pixelclock frequency in Hz.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>max_pixelclock</structfield></entry>
- <entry>Maximum pixelclock frequency in Hz.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>standards</structfield></entry>
- <entry>The video standard(s) supported by the hardware.
- See <xref linkend="dv-bt-standards"/> for a list of standards.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capabilities</structfield></entry>
- <entry>Several flags giving more information about the capabilities.
- See <xref linkend="dv-bt-cap-capabilities"/> for a description of the flags.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[16]</entry>
- <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-dv-timings-cap">
- <title>struct <structname>v4l2_dv_timings_cap</structname></title>
- <tgroup cols="4">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API. This field
- is only used when operating on a subdevice node. When operating on a
- video node applications must set this field to zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield></structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-bt-timings-cap;</entry>
- <entry><structfield>bt</structfield></entry>
- <entry>BT.656/1120 timings capabilities of the hardware.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>raw_data</structfield>[32]</entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="dv-bt-cap-capabilities">
- <title>DV BT Timing capabilities</title>
- <tgroup cols="2">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>Flag</entry>
- <entry>Description</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_CAP_INTERLACED</entry>
- <entry>Interlaced formats are supported.
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_CAP_PROGRESSIVE</entry>
- <entry>Progressive formats are supported.
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_CAP_REDUCED_BLANKING</entry>
- <entry>CVT/GTF specific: the timings can make use of reduced blanking (CVT)
-or the 'Secondary GTF' curve (GTF).
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_CAP_CUSTOM</entry>
- <entry>Can support non-standard timings, i.e. timings not belonging to the
-standards set in the <structfield>standards</structfield> field.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
deleted file mode 100644
index 0619ca5d2d36..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
+++ /dev/null
@@ -1,189 +0,0 @@
-<refentry id="vidioc-encoder-cmd">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENCODER_CMD</refname>
- <refname>VIDIOC_TRY_ENCODER_CMD</refname>
- <refpurpose>Execute an encoder command</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>These ioctls control an audio/video (usually MPEG-) encoder.
-<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the
-encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
-try a command without actually executing it.</para>
-
- <para>To send a command applications must initialize all fields of a
- &v4l2-encoder-cmd; and call
- <constant>VIDIOC_ENCODER_CMD</constant> or
- <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this
- structure.</para>
-
- <para>The <structfield>cmd</structfield> field must contain the
-command code. The <structfield>flags</structfield> field is currently
-only used by the STOP command and contains one bit: If the
-<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
-encoding will continue until the end of the current <wordasword>Group
-Of Pictures</wordasword>, otherwise it will stop immediately.</para>
-
- <para>A <function>read</function>() or &VIDIOC-STREAMON; call sends an implicit
-START command to the encoder if it has not been started yet. After a STOP command,
-<function>read</function>() calls will read the remaining data
-buffered by the driver. When the buffer is empty,
-<function>read</function>() will return zero and the next
-<function>read</function>() call will restart the encoder.</para>
-
- <para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming
-file descriptor sends an implicit immediate STOP to the encoder, and all buffered
-data is discarded.</para>
-
- <para>These ioctls are optional, not all drivers may support
-them. They were introduced in Linux 2.6.21.</para>
-
- <table pgwide="1" frame="none" id="v4l2-encoder-cmd">
- <title>struct <structname>v4l2_encoder_cmd</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>cmd</structfield></entry>
- <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags to go with the command, see <xref
- linkend="encoder-flags" />. If no flags are defined for
-this command, drivers and applications must set this field to
-zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>data</structfield>[8]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="encoder-cmds">
- <title>Encoder Commands</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_ENC_CMD_START</constant></entry>
- <entry>0</entry>
- <entry>Start the encoder. When the encoder is already
-running or paused, this command does nothing. No flags are defined for
-this command.</entry>
- </row>
- <row>
- <entry><constant>V4L2_ENC_CMD_STOP</constant></entry>
- <entry>1</entry>
- <entry>Stop the encoder. When the
-<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
-encoding will continue until the end of the current <wordasword>Group
-Of Pictures</wordasword>, otherwise encoding will stop immediately.
-When the encoder is already stopped, this command does
-nothing.</entry>
- </row>
- <row>
- <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry>
- <entry>2</entry>
- <entry>Pause the encoder. When the encoder has not been
-started yet, the driver will return an &EPERM;. When the encoder is
-already paused, this command does nothing. No flags are defined for
-this command.</entry>
- </row>
- <row>
- <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry>
- <entry>3</entry>
- <entry>Resume encoding after a PAUSE command. When the
-encoder has not been started yet, the driver will return an &EPERM;.
-When the encoder is already running, this command does nothing. No
-flags are defined for this command.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="encoder-flags">
- <title>Encoder Command Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry>
- <entry>0x0001</entry>
- <entry>Stop encoding at the end of the current <wordasword>Group Of
-Pictures</wordasword>, rather than immediately.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <structfield>cmd</structfield> field is invalid.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EPERM</errorcode></term>
- <listitem>
- <para>The application sent a PAUSE or RESUME command when
-the encoder was not running.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
deleted file mode 100644
index 6e3cadd4e1f9..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
+++ /dev/null
@@ -1,133 +0,0 @@
-<refentry id="vidioc-enum-dv-timings">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUM_DV_TIMINGS</refname>
- <refname>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refname>
- <refpurpose>Enumerate supported Digital Video timings</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_enum_dv_timings *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>While some DV receivers or transmitters support a wide range of timings, others
-support only a limited number of timings. With this ioctl applications can enumerate a list
-of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also supports other
-standards or even custom timings that are not in this list.</para>
-
- <para>To query the available timings, applications initialize the
-<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
-and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a
-pointer to this structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
-applications shall begin at index zero, incrementing by one until the
-driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
-different set of DV timings after switching the video input or
-output.</para>
-
- <para>When implemented by the driver DV timings of subdevices can be queried
-by calling the <constant>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</constant> ioctl directly
-on a subdevice node. The DV timings are specific to inputs (for DV receivers) or
-outputs (for DV transmitters), applications must specify the desired pad number
-in the &v4l2-enum-dv-timings; <structfield>pad</structfield> field. Attempts to
-enumerate timings on a pad that doesn't support them will return an &EINVAL;.</para>
-
- <table pgwide="1" frame="none" id="v4l2-enum-dv-timings">
- <title>struct <structname>v4l2_enum_dv_timings</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the DV timings, set by the
-application.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API. This field
- is only used when operating on a subdevice node. When operating on a
- video node applications must set this field to zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions. Drivers and applications must
- set the array to zero.</entry>
- </row>
- <row>
- <entry>&v4l2-dv-timings;</entry>
- <entry><structfield>timings</structfield></entry>
- <entry>The timings.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-enum-dv-timings; <structfield>index</structfield>
-is out of bounds or the <structfield>pad</structfield> number is invalid.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>Digital video presets are not supported for this input or output.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
deleted file mode 100644
index f8dfeed34fca..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
+++ /dev/null
@@ -1,159 +0,0 @@
-<refentry id="vidioc-enum-fmt">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUM_FMT</refname>
- <refpurpose>Enumerate image formats</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_fmtdesc
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUM_FMT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To enumerate image formats applications initialize the
-<structfield>type</structfield> and <structfield>index</structfield>
-field of &v4l2-fmtdesc; and call the
-<constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
-structure. Drivers fill the rest of the structure or return an
-&EINVAL;. All formats are enumerable by beginning at index zero and
-incrementing by one until <errorcode>EINVAL</errorcode> is
-returned.</para>
-
- <para>Note that after switching input or output the list of enumerated image
-formats may be different.</para>
-
- <table pgwide="1" frame="none" id="v4l2-fmtdesc">
- <title>struct <structname>v4l2_fmtdesc</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the format in the enumeration, set by
-the application. This is in no way related to the <structfield>
-pixelformat</structfield> field.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the data stream, set by the application.
-Only these types are valid here:
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and
-<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>See <xref linkend="fmtdesc-flags" /></entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>description</structfield>[32]</entry>
- <entry>Description of the format, a NUL-terminated ASCII
-string. This information is intended for the user, for example: "YUV
-4:2:2".</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>The image format identifier. This is a
-four character code as computed by the v4l2_fourcc()
-macro:</entry>
- </row>
- <row>
- <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
-#define v4l2_fourcc(a,b,c,d) (((__u32)(a)&lt;&lt;0)|((__u32)(b)&lt;&lt;8)|((__u32)(c)&lt;&lt;16)|((__u32)(d)&lt;&lt;24))
-</programlisting></para><para>Several image formats are already
-defined by this specification in <xref linkend="pixfmt" />. Note these
-codes are not the same as those used in the Windows world.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry>Reserved for future extensions. Drivers must set
-the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="fmtdesc-flags">
- <title>Image Format Description Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
- <entry>0x0001</entry>
- <entry>This is a compressed format.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
- <entry>0x0002</entry>
- <entry>This format is not native to the device but emulated
-through software (usually libv4l2), where possible try to use a native format
-instead for better performance.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-fmtdesc; <structfield>type</structfield>
-is not supported or the <structfield>index</structfield> is out of
-bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
deleted file mode 100644
index 5fd72c4c33e3..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
+++ /dev/null
@@ -1,259 +0,0 @@
-<refentry id="vidioc-enum-frameintervals">
-
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUM_FRAMEINTERVALS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUM_FRAMEINTERVALS</refname>
- <refpurpose>Enumerate frame intervals</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_frmivalenum *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUM_FRAMEINTERVALS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para>Pointer to a &v4l2-frmivalenum; structure that
-contains a pixel format and size and receives a frame interval.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>This ioctl allows applications to enumerate all frame
-intervals that the device supports for the given pixel format and
-frame size.</para>
- <para>The supported pixel formats and frame sizes can be obtained
-by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES;
-functions.</para>
- <para>The return value and the content of the
-<structfield>v4l2_frmivalenum.type</structfield> field depend on the
-type of frame intervals the device supports. Here are the semantics of
-the function for the different cases:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Discrete:</emphasis> The function
-returns success if the given index value (zero-based) is valid. The
-application should increase the index by one for each call until
-<constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type`
-field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the
-union only the `discrete` member is valid.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Step-wise:</emphasis> The function
-returns success if the given index value is zero and
-<constant>EINVAL</constant> for any other index value. The
-<structfield>v4l2_frmivalenum.type</structfield> field is set to
-<constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant> by the driver. Of the
-union only the <structfield>stepwise</structfield> member is
-valid.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Continuous:</emphasis> This is a
-special case of the step-wise type above. The function returns success
-if the given index value is zero and <constant>EINVAL</constant> for
-any other index value. The
-<structfield>v4l2_frmivalenum.type</structfield> field is set to
-<constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant> by the driver. Of
-the union only the <structfield>stepwise</structfield> member is valid
-and the <structfield>step</structfield> value is set to 1.</para>
- </listitem>
- </itemizedlist>
-
- <para>When the application calls the function with index zero, it
-must check the <structfield>type</structfield> field to determine the
-type of frame interval enumeration the device supports. Only for the
-<constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make
-sense to increase the index value to receive more frame
-intervals.</para>
- <para>Note that the order in which the frame intervals are
-returned has no special meaning. In particular does it not say
-anything about potential default frame intervals.</para>
- <para>Applications can assume that the enumeration data does not
-change without any interaction from the application itself. This means
-that the enumeration data is consistent if the application does not
-perform any other ioctl calls while it runs the frame interval
-enumeration.</para>
- </refsect1>
-
- <refsect1>
- <title>Notes</title>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Frame intervals and frame
-rates:</emphasis> The V4L2 API uses frame intervals instead of frame
-rates. Given the frame interval the frame rate can be computed as
-follows:<screen>frame_rate = 1 / frame_interval</screen></para>
- </listitem>
- </itemizedlist>
-
- </refsect1>
-
- <refsect1>
- <title>Structs</title>
-
- <para>In the structs below, <emphasis>IN</emphasis> denotes a
-value that has to be filled in by the application,
-<emphasis>OUT</emphasis> denotes values that the driver fills in. The
-application should zero out all members except for the
-<emphasis>IN</emphasis> fields.</para>
-
- <table pgwide="1" frame="none" id="v4l2-frmival-stepwise">
- <title>struct <structname>v4l2_frmival_stepwise</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>min</structfield></entry>
- <entry>Minimum frame interval [s].</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>max</structfield></entry>
- <entry>Maximum frame interval [s].</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>step</structfield></entry>
- <entry>Frame interval step size [s].</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-frmivalenum">
- <title>struct <structname>v4l2_frmivalenum</structname></title>
- <tgroup cols="4">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry></entry>
- <entry>IN: Index of the given frame interval in the
-enumeration.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixel_format</structfield></entry>
- <entry></entry>
- <entry>IN: Pixel format for which the frame intervals are
-enumerated.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry></entry>
- <entry>IN: Frame width for which the frame intervals are
-enumerated.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry></entry>
- <entry>IN: Frame height for which the frame intervals are
-enumerated.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>OUT: Frame interval type the device supports.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry></entry>
- <entry></entry>
- <entry>OUT: Frame interval with the given index.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>discrete</structfield></entry>
- <entry>Frame interval [s].</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-frmival-stepwise;</entry>
- <entry><structfield>stepwise</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved[2]</structfield></entry>
- <entry></entry>
- <entry>Reserved space for future use.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- <title>Enums</title>
-
- <table pgwide="1" frame="none" id="v4l2-frmivaltypes">
- <title>enum <structname>v4l2_frmivaltypes</structname></title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant></entry>
- <entry>1</entry>
- <entry>Discrete frame interval.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant></entry>
- <entry>2</entry>
- <entry>Continuous frame interval.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant></entry>
- <entry>3</entry>
- <entry>Step-wise defined frame interval.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
deleted file mode 100644
index a78454b5abcd..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
+++ /dev/null
@@ -1,264 +0,0 @@
-<refentry id="vidioc-enum-framesizes">
-
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUM_FRAMESIZES</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUM_FRAMESIZES</refname>
- <refpurpose>Enumerate frame sizes</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_frmsizeenum *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUM_FRAMESIZES</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para>Pointer to a &v4l2-frmsizeenum; that contains an index
-and pixel format and receives a frame width and height.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>This ioctl allows applications to enumerate all frame sizes
-(&ie; width and height in pixels) that the device supports for the
-given pixel format.</para>
- <para>The supported pixel formats can be obtained by using the
-&VIDIOC-ENUM-FMT; function.</para>
- <para>The return value and the content of the
-<structfield>v4l2_frmsizeenum.type</structfield> field depend on the
-type of frame sizes the device supports. Here are the semantics of the
-function for the different cases:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">Discrete:</emphasis> The function
-returns success if the given index value (zero-based) is valid. The
-application should increase the index by one for each call until
-<constant>EINVAL</constant> is returned. The
-<structfield>v4l2_frmsizeenum.type</structfield> field is set to
-<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> by the driver. Of the
-union only the <structfield>discrete</structfield> member is
-valid.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Step-wise:</emphasis> The function
-returns success if the given index value is zero and
-<constant>EINVAL</constant> for any other index value. The
-<structfield>v4l2_frmsizeenum.type</structfield> field is set to
-<constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant> by the driver. Of the
-union only the <structfield>stepwise</structfield> member is
-valid.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">Continuous:</emphasis> This is a
-special case of the step-wise type above. The function returns success
-if the given index value is zero and <constant>EINVAL</constant> for
-any other index value. The
-<structfield>v4l2_frmsizeenum.type</structfield> field is set to
-<constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant> by the driver. Of
-the union only the <structfield>stepwise</structfield> member is valid
-and the <structfield>step_width</structfield> and
-<structfield>step_height</structfield> values are set to 1.</para>
- </listitem>
- </itemizedlist>
-
- <para>When the application calls the function with index zero, it
-must check the <structfield>type</structfield> field to determine the
-type of frame size enumeration the device supports. Only for the
-<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make
-sense to increase the index value to receive more frame sizes.</para>
- <para>Note that the order in which the frame sizes are returned
-has no special meaning. In particular does it not say anything about
-potential default format sizes.</para>
- <para>Applications can assume that the enumeration data does not
-change without any interaction from the application itself. This means
-that the enumeration data is consistent if the application does not
-perform any other ioctl calls while it runs the frame size
-enumeration.</para>
- </refsect1>
-
- <refsect1>
- <title>Structs</title>
-
- <para>In the structs below, <emphasis>IN</emphasis> denotes a
-value that has to be filled in by the application,
-<emphasis>OUT</emphasis> denotes values that the driver fills in. The
-application should zero out all members except for the
-<emphasis>IN</emphasis> fields.</para>
-
- <table pgwide="1" frame="none" id="v4l2-frmsize-discrete">
- <title>struct <structname>v4l2_frmsize_discrete</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Width of the frame [pixel].</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Height of the frame [pixel].</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-frmsize-stepwise">
- <title>struct <structname>v4l2_frmsize_stepwise</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>min_width</structfield></entry>
- <entry>Minimum frame width [pixel].</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>max_width</structfield></entry>
- <entry>Maximum frame width [pixel].</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>step_width</structfield></entry>
- <entry>Frame width step size [pixel].</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>min_height</structfield></entry>
- <entry>Minimum frame height [pixel].</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>max_height</structfield></entry>
- <entry>Maximum frame height [pixel].</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>step_height</structfield></entry>
- <entry>Frame height step size [pixel].</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-frmsizeenum">
- <title>struct <structname>v4l2_frmsizeenum</structname></title>
- <tgroup cols="4">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry></entry>
- <entry>IN: Index of the given frame size in the enumeration.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pixel_format</structfield></entry>
- <entry></entry>
- <entry>IN: Pixel format for which the frame sizes are enumerated.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>OUT: Frame size type the device supports.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry></entry>
- <entry></entry>
- <entry>OUT: Frame size with the given index.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-frmsize-discrete;</entry>
- <entry><structfield>discrete</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-frmsize-stepwise;</entry>
- <entry><structfield>stepwise</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved[2]</structfield></entry>
- <entry></entry>
- <entry>Reserved space for future use.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- <title>Enums</title>
-
- <table pgwide="1" frame="none" id="v4l2-frmsizetypes">
- <title>enum <structname>v4l2_frmsizetypes</structname></title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant></entry>
- <entry>1</entry>
- <entry>Discrete frame size.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant></entry>
- <entry>2</entry>
- <entry>Continuous frame size.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant></entry>
- <entry>3</entry>
- <entry>Step-wise defined frame size.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml b/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml
deleted file mode 100644
index 4e8ea65f7282..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml
+++ /dev/null
@@ -1,181 +0,0 @@
-<refentry id="vidioc-enum-freq-bands">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUM_FREQ_BANDS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUM_FREQ_BANDS</refname>
- <refpurpose>Enumerate supported frequency bands</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_frequency_band
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUM_FREQ_BANDS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>Enumerates the frequency bands that a tuner or modulator supports.
-To do this applications initialize the <structfield>tuner</structfield>,
-<structfield>type</structfield> and <structfield>index</structfield> fields,
-and zero out the <structfield>reserved</structfield> array of a &v4l2-frequency-band; and
-call the <constant>VIDIOC_ENUM_FREQ_BANDS</constant> ioctl with a pointer
-to this structure.</para>
-
- <para>This ioctl is supported if the <constant>V4L2_TUNER_CAP_FREQ_BANDS</constant> capability
- of the corresponding tuner/modulator is set.</para>
-
- <table pgwide="1" frame="none" id="v4l2-frequency-band">
- <title>struct <structname>v4l2_frequency_band</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>tuner</structfield></entry>
- <entry>The tuner or modulator index number. This is the
-same value as in the &v4l2-input; <structfield>tuner</structfield>
-field and the &v4l2-tuner; <structfield>index</structfield> field, or
-the &v4l2-output; <structfield>modulator</structfield> field and the
-&v4l2-modulator; <structfield>index</structfield> field.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>The tuner type. This is the same value as in the
-&v4l2-tuner; <structfield>type</structfield> field. The type must be set
-to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename>
-device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant>
-for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for
-modulators (currently only radio modulators are supported).
-See <xref linkend="v4l2-tuner-type" /></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Identifies the frequency band, set by the application.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry spanname="hspan">The tuner/modulator capability flags for
-this frequency band, see <xref linkend="tuner-capability" />. The <constant>V4L2_TUNER_CAP_LOW</constant>
-or <constant>V4L2_TUNER_CAP_1HZ</constant> capability must be the same for all frequency bands of the selected tuner/modulator.
-So either all bands have that capability set, or none of them have that capability.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangelow</structfield></entry>
- <entry spanname="hspan">The lowest tunable frequency in
-units of 62.5 kHz, or if the <structfield>capability</structfield>
-flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangehigh</structfield></entry>
- <entry spanname="hspan">The highest tunable frequency in
-units of 62.5 kHz, or if the <structfield>capability</structfield>
-flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>modulation</structfield></entry>
- <entry spanname="hspan">The supported modulation systems of this frequency band.
- See <xref linkend="band-modulation" />. Note that currently only one
- modulation system per frequency band is supported. More work will need to
- be done if multiple modulation systems are possible. Contact the
- linux-media mailing list (&v4l-ml;) if you need that functionality.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[9]</entry>
- <entry>Reserved for future extensions. Applications and drivers
- must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="band-modulation">
- <title>Band Modulation Systems</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_BAND_MODULATION_VSB</constant></entry>
- <entry>0x02</entry>
- <entry>Vestigial Sideband modulation, used for analog TV.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BAND_MODULATION_FM</constant></entry>
- <entry>0x04</entry>
- <entry>Frequency Modulation, commonly used for analog radio.</entry>
- </row>
- <row>
- <entry><constant>V4L2_BAND_MODULATION_AM</constant></entry>
- <entry>0x08</entry>
- <entry>Amplitude Modulation, commonly used for analog radio.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <structfield>tuner</structfield> or <structfield>index</structfield>
-is out of bounds or the <structfield>type</structfield> field is wrong.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml b/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml
deleted file mode 100644
index ea816ab2e49e..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml
+++ /dev/null
@@ -1,76 +0,0 @@
-<refentry id="vidioc-enumaudio">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUMAUDIO</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUMAUDIO</refname>
- <refpurpose>Enumerate audio inputs</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUMAUDIO</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of an audio input applications
-initialize the <structfield>index</structfield> field and zero out the
-<structfield>reserved</structfield> array of a &v4l2-audio;
-and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer
-to this structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the index is out of bounds. To enumerate all audio
-inputs applications shall begin at index zero, incrementing by one
-until the driver returns <errorcode>EINVAL</errorcode>.</para>
-
- <para>See <xref linkend="vidioc-g-audio" /> for a description of
-&v4l2-audio;.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The number of the audio input is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml b/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml
deleted file mode 100644
index 2e87cedb0d32..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml
+++ /dev/null
@@ -1,79 +0,0 @@
-<refentry id="vidioc-enumaudioout">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUMAUDOUT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUMAUDOUT</refname>
- <refpurpose>Enumerate audio outputs</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUMAUDOUT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of an audio output applications
-initialize the <structfield>index</structfield> field and zero out the
-<structfield>reserved</structfield> array of a &v4l2-audioout; and
-call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
-to this structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the index is out of bounds. To enumerate all audio
-outputs applications shall begin at index zero, incrementing by one
-until the driver returns <errorcode>EINVAL</errorcode>.</para>
-
- <para>Note connectors on a TV card to loop back the received audio
-signal to a sound card are not audio outputs in this sense.</para>
-
- <para>See <xref linkend="vidioc-g-audioout" /> for a description of
-&v4l2-audioout;.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The number of the audio output is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
deleted file mode 100644
index 603fecef9083..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
+++ /dev/null
@@ -1,316 +0,0 @@
-<refentry id="vidioc-enuminput">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUMINPUT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUMINPUT</refname>
- <refpurpose>Enumerate video inputs</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_input
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUMINPUT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of a video input applications
-initialize the <structfield>index</structfield> field of &v4l2-input;
-and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a
-pointer to this structure. Drivers fill the rest of the structure or
-return an &EINVAL; when the index is out of bounds. To enumerate all
-inputs applications shall begin at index zero, incrementing by one
-until the driver returns <errorcode>EINVAL</errorcode>.</para>
-
- <table frame="none" pgwide="1" id="v4l2-input">
- <title>struct <structname>v4l2_input</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Identifies the input, set by the
-application.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the video input, a NUL-terminated ASCII
-string, for example: "Vin (Composite 2)". This information is intended
-for the user, preferably the connector label on the device itself.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the input, see <xref
- linkend="input-type" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>audioset</structfield></entry>
- <entry><para>Drivers can enumerate up to 32 video and
-audio inputs. This field shows which audio inputs were selectable as
-audio source if this was the currently selected video input. It is a
-bit mask. The LSB corresponds to audio input 0, the MSB to input 31.
-Any number of bits can be set, or none.</para><para>When the driver
-does not enumerate audio inputs no bits must be set. Applications
-shall not interpret this as lack of audio support. Some drivers
-automatically select audio sources and do not enumerate them since
-there is no choice anyway.</para><para>For details on audio inputs and
-how to select the current input see <xref
- linkend="audio" />.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>tuner</structfield></entry>
- <entry>Capture devices can have zero or more tuners (RF
-demodulators). When the <structfield>type</structfield> is set to
-<constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and
-this field identifies the tuner. It corresponds to
-&v4l2-tuner; field <structfield>index</structfield>. For details on
-tuners see <xref linkend="tuner" />.</entry>
- </row>
- <row>
- <entry>&v4l2-std-id;</entry>
- <entry><structfield>std</structfield></entry>
- <entry>Every video input supports one or more different
-video standards. This field is a set of all supported standards. For
-details on video standards and how to switch see <xref
-linkend="standard" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>status</structfield></entry>
- <entry>This field provides status information about the
-input. See <xref linkend="input-status" /> for flags.
-With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the
-current input.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capabilities</structfield></entry>
- <entry>This field provides capabilities for the
-input. See <xref linkend="input-capabilities" /> for flags.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[3]</entry>
- <entry>Reserved for future extensions. Drivers must set
-the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="input-type">
- <title>Input Types</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
- <entry>1</entry>
- <entry>This input uses a tuner (RF demodulator).</entry>
- </row>
- <row>
- <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
- <entry>2</entry>
- <entry>Analog baseband input, for example CVBS /
-Composite Video, S-Video, RGB.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- Status flags based on proposal by Mark McClelland,
-video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re:
-v4l2 api". "Why are some of them inverted? So that the driver doesn't
-have to lie about the status in cases where it can't tell one way or
-the other. Plus, a status of zero would generally mean that everything
-is OK." -->
-
- <table frame="none" pgwide="1" id="input-status">
- <title>Input Status Flags</title>
- <tgroup cols="3">
- <colspec colname="c1" />
- <colspec colname="c2" align="center" />
- <colspec colname="c3" />
- <spanspec namest="c1" nameend="c3" spanname="hspan"
- align="left" />
- <tbody valign="top">
- <row>
- <entry spanname="hspan">General</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_POWER</constant></entry>
- <entry>0x00000001</entry>
- <entry>Attached device is off.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry>
- <entry>0x00000002</entry>
- <entry></entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry>
- <entry>0x00000004</entry>
- <entry>The hardware supports color decoding, but does not
-detect color modulation in the signal.</entry>
- </row>
- <row>
- <entry spanname="hspan">Sensor Orientation</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_HFLIP</constant></entry>
- <entry>0x00000010</entry>
- <entry>The input is connected to a device that produces a signal
-that is flipped horizontally and does not correct this before passing the
-signal to userspace.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_VFLIP</constant></entry>
- <entry>0x00000020</entry>
- <entry>The input is connected to a device that produces a signal
-that is flipped vertically and does not correct this before passing the
-signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry>
- </row>
- <row>
- <entry spanname="hspan">Analog Video</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry>
- <entry>0x00000100</entry>
- <entry>No horizontal sync lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry>
- <entry>0x00000200</entry>
- <entry>A color killer circuit automatically disables color
-decoding when it detects no color modulation. When this flag is set
-the color killer is enabled <emphasis>and</emphasis> has shut off
-color decoding.</entry>
- </row>
- <row>
- <entry spanname="hspan">Digital Video</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry>
- <entry>0x00010000</entry>
- <entry>No synchronization lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_EQU</constant></entry>
- <entry>0x00020000</entry>
- <entry>No equalizer lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry>
- <entry>0x00040000</entry>
- <entry>Carrier recovery failed.</entry>
- </row>
- <row>
- <entry spanname="hspan">VCR and Set-Top Box</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_MACROVISION</constant></entry>
- <entry>0x01000000</entry>
- <entry>Macrovision is an analog copy prevention system
-mangling the video signal to confuse video recorders. When this
-flag is set Macrovision has been detected.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry>
- <entry>0x02000000</entry>
- <entry>Conditional access denied.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_ST_VTR</constant></entry>
- <entry>0x04000000</entry>
- <entry>VTR time constant. [?]</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- Capability flags based on video timings RFC by Muralidharan
-Karicheri, titled RFC (v1.2): V4L - Support for video timings at the
-input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
- -->
- <table frame="none" pgwide="1" id="input-capabilities">
- <title>Input capabilities</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_IN_CAP_DV_TIMINGS</constant></entry>
- <entry>0x00000002</entry>
- <entry>This input supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_CAP_STD</constant></entry>
- <entry>0x00000004</entry>
- <entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry>
- </row>
- <row>
- <entry><constant>V4L2_IN_CAP_NATIVE_SIZE</constant></entry>
- <entry>0x00000008</entry>
- <entry>This input supports setting the native size using
- the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant>
- selection target, see <xref
- linkend="v4l2-selections-common"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-input; <structfield>index</structfield> is
-out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
deleted file mode 100644
index 773fb1258c24..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
+++ /dev/null
@@ -1,201 +0,0 @@
-<refentry id="vidioc-enumoutput">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUMOUTPUT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUMOUTPUT</refname>
- <refpurpose>Enumerate video outputs</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_output *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUMOUTPUT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of a video outputs applications
-initialize the <structfield>index</structfield> field of &v4l2-output;
-and call the <constant>VIDIOC_ENUMOUTPUT</constant> ioctl with a
-pointer to this structure. Drivers fill the rest of the structure or
-return an &EINVAL; when the index is out of bounds. To enumerate all
-outputs applications shall begin at index zero, incrementing by one
-until the driver returns <errorcode>EINVAL</errorcode>.</para>
-
- <table frame="none" pgwide="1" id="v4l2-output">
- <title>struct <structname>v4l2_output</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Identifies the output, set by the
-application.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the video output, a NUL-terminated ASCII
-string, for example: "Vout". This information is intended for the
-user, preferably the connector label on the device itself.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the output, see <xref
- linkend="output-type" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>audioset</structfield></entry>
- <entry><para>Drivers can enumerate up to 32 video and
-audio outputs. This field shows which audio outputs were
-selectable as the current output if this was the currently selected
-video output. It is a bit mask. The LSB corresponds to audio output 0,
-the MSB to output 31. Any number of bits can be set, or
-none.</para><para>When the driver does not enumerate audio outputs no
-bits must be set. Applications shall not interpret this as lack of
-audio support. Drivers may automatically select audio outputs without
-enumerating them.</para><para>For details on audio outputs and how to
-select the current output see <xref linkend="audio" />.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>modulator</structfield></entry>
- <entry>Output devices can have zero or more RF modulators.
-When the <structfield>type</structfield> is
-<constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF
-connector and this field identifies the modulator. It corresponds to
-&v4l2-modulator; field <structfield>index</structfield>. For details
-on modulators see <xref linkend="tuner" />.</entry>
- </row>
- <row>
- <entry>&v4l2-std-id;</entry>
- <entry><structfield>std</structfield></entry>
- <entry>Every video output supports one or more different
-video standards. This field is a set of all supported standards. For
-details on video standards and how to switch see <xref
- linkend="standard" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capabilities</structfield></entry>
- <entry>This field provides capabilities for the
-output. See <xref linkend="output-capabilities" /> for flags.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[3]</entry>
- <entry>Reserved for future extensions. Drivers must set
-the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="output-type">
- <title>Output Type</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry>
- <entry>1</entry>
- <entry>This output is an analog TV modulator.</entry>
- </row>
- <row>
- <entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry>
- <entry>2</entry>
- <entry>Analog baseband output, for example Composite /
-CVBS, S-Video, RGB.</entry>
- </row>
- <row>
- <entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry>
- <entry>3</entry>
- <entry>[?]</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- Capabilities flags based on video timings RFC by Muralidharan
-Karicheri, titled RFC (v1.2): V4L - Support for video timings at the
-input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
- -->
- <table frame="none" pgwide="1" id="output-capabilities">
- <title>Output capabilities</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_OUT_CAP_DV_TIMINGS</constant></entry>
- <entry>0x00000002</entry>
- <entry>This output supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry>
- </row>
- <row>
- <entry><constant>V4L2_OUT_CAP_STD</constant></entry>
- <entry>0x00000004</entry>
- <entry>This output supports setting the TV standard by using VIDIOC_S_STD.</entry>
- </row>
- <row>
- <entry><constant>V4L2_OUT_CAP_NATIVE_SIZE</constant></entry>
- <entry>0x00000008</entry>
- <entry>This output supports setting the native size using
- the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant>
- selection target, see <xref
- linkend="v4l2-selections-common"/>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-output; <structfield>index</structfield>
-is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
deleted file mode 100644
index 8065099401d1..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
+++ /dev/null
@@ -1,389 +0,0 @@
-<refentry id="vidioc-enumstd">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_ENUMSTD</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_ENUMSTD</refname>
- <refpurpose>Enumerate supported video standards</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_standard *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_ENUMSTD</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of a video standard,
-especially a custom (driver defined) one, applications initialize the
-<structfield>index</structfield> field of &v4l2-standard; and call the
-<constant>VIDIOC_ENUMSTD</constant> ioctl with a pointer to this
-structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the index is out of bounds. To enumerate all standards
-applications shall begin at index zero, incrementing by one until the
-driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a
-different set of standards after switching the video input or
-output.<footnote>
- <para>The supported standards may overlap and we need an
-unambiguous set to find the current standard returned by
-<constant>VIDIOC_G_STD</constant>.</para>
- </footnote></para>
-
- <table pgwide="1" frame="none" id="v4l2-standard">
- <title>struct <structname>v4l2_standard</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the video standard, set by the
-application.</entry>
- </row>
- <row>
- <entry>&v4l2-std-id;</entry>
- <entry><structfield>id</structfield></entry>
- <entry>The bits in this field identify the standard as
-one of the common standards listed in <xref linkend="v4l2-std-id" />,
-or if bits 32 to 63 are set as custom standards. Multiple bits can be
-set if the hardware does not distinguish between these standards,
-however separate indices do not indicate the opposite. The
-<structfield>id</structfield> must be unique. No other enumerated
-<structname>v4l2_standard</structname> structure, for this input or
-output anyway, can contain the same set of bits.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[24]</entry>
- <entry>Name of the standard, a NUL-terminated ASCII
-string, for example: "PAL-B/G", "NTSC Japan". This information is
-intended for the user.</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>frameperiod</structfield></entry>
- <entry>The frame period (not field period) is numerator
-/ denominator. For example M/NTSC has a frame period of 1001 /
-30000 seconds.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>framelines</structfield></entry>
- <entry>Total lines per frame including blanking,
-e.&nbsp;g. 625 for B/PAL.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry>Reserved for future extensions. Drivers must set
-the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-fract">
- <title>struct <structname>v4l2_fract</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>numerator</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>denominator</structfield></entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-std-id">
- <title>typedef <structname>v4l2_std_id</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u64</entry>
- <entry><structfield>v4l2_std_id</structfield></entry>
- <entry>This type is a set, each bit representing another
-video standard as listed below and in <xref
-linkend="video-standards" />. The 32 most significant bits are reserved
-for custom (driver defined) video standards.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><programlisting>
-#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
-#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
-#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
-#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
-#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
-#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
-#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
-#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
-
-#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
-#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
-#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
-#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
-</programlisting></para><para><constant>V4L2_STD_PAL_60</constant> is
-a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color
-modulation with a 4.43 MHz color subcarrier. Some PAL video recorders
-can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic
-PAL TV.</para><para><programlisting>
-#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
-#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
-#define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
-</programlisting></para><para><constant>V4L2_STD_NTSC_443</constant>
-is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC
-color modulation with a 4.43 MHz color
-subcarrier.</para><para><programlisting>
-#define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
-
-#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
-#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
-#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
-#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
-#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
-#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
-#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
-#define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
-
-/* ATSC/HDTV */
-#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
-#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
-</programlisting></para><para><!-- ATSC proposal by Mark McClelland,
-video4linux-list@redhat.com on 17 Oct 2002
---><constant>V4L2_STD_ATSC_8_VSB</constant> and
-<constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital
-TV standards. Presently the V4L2 API does not support digital TV. See
-also the Linux DVB API at <ulink
-url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
-<para><programlisting>
-#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
- V4L2_STD_PAL_B1 |\
- V4L2_STD_PAL_G)
-#define V4L2_STD_B (V4L2_STD_PAL_B |\
- V4L2_STD_PAL_B1 |\
- V4L2_STD_SECAM_B)
-#define V4L2_STD_GH (V4L2_STD_PAL_G |\
- V4L2_STD_PAL_H |\
- V4L2_STD_SECAM_G |\
- V4L2_STD_SECAM_H)
-#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\
- V4L2_STD_PAL_D1 |\
- V4L2_STD_PAL_K)
-#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\
- V4L2_STD_PAL_DK |\
- V4L2_STD_PAL_H |\
- V4L2_STD_PAL_I)
-#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\
- V4L2_STD_NTSC_M_JP |\
- V4L2_STD_NTSC_M_KR)
-#define V4L2_STD_MN (V4L2_STD_PAL_M |\
- V4L2_STD_PAL_N |\
- V4L2_STD_PAL_Nc |\
- V4L2_STD_NTSC)
-#define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\
- V4L2_STD_SECAM_K |\
- V4L2_STD_SECAM_K1)
-#define V4L2_STD_DK (V4L2_STD_PAL_DK |\
- V4L2_STD_SECAM_DK)
-
-#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\
- V4L2_STD_SECAM_G |\
- V4L2_STD_SECAM_H |\
- V4L2_STD_SECAM_DK |\
- V4L2_STD_SECAM_L |\
- V4L2_STD_SECAM_LC)
-
-#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\
- V4L2_STD_PAL_60 |\
- V4L2_STD_NTSC |\
- V4L2_STD_NTSC_443)
-#define V4L2_STD_625_50 (V4L2_STD_PAL |\
- V4L2_STD_PAL_N |\
- V4L2_STD_PAL_Nc |\
- V4L2_STD_SECAM)
-
-#define V4L2_STD_UNKNOWN 0
-#define V4L2_STD_ALL (V4L2_STD_525_60 |\
- V4L2_STD_625_50)
-</programlisting></para>
-
- <table pgwide="1" id="video-standards" orient="land">
- <title>Video Standards (based on [<xref linkend="itu470" />])</title>
- <tgroup cols="12" colsep="1" rowsep="1" align="center">
- <colspec colname="c1" align="left" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <colspec colname="c5" />
- <colspec colnum="7" colname="c7" />
- <colspec colnum="9" colname="c9" />
- <colspec colnum="12" colname="c12" />
- <spanspec namest="c2" nameend="c3" spanname="m" align="center" />
- <spanspec namest="c4" nameend="c12" spanname="x" align="center" />
- <spanspec namest="c5" nameend="c7" spanname="b" align="center" />
- <spanspec namest="c9" nameend="c12" spanname="s" align="center" />
- <thead>
- <row>
- <entry>Characteristics</entry>
- <entry><para>M/NTSC<footnote><para>Japan uses a standard
-similar to M/NTSC
-(V4L2_STD_NTSC_M_JP).</para></footnote></para></entry>
- <entry>M/PAL</entry>
- <entry><para>N/PAL<footnote><para> The values in
-brackets apply to the combination N/PAL a.k.a.
-N<subscript>C</subscript> used in Argentina
-(V4L2_STD_PAL_Nc).</para></footnote></para></entry>
- <entry align="center">B, B1, G/PAL</entry>
- <entry align="center">D, D1, K/PAL</entry>
- <entry align="center">H/PAL</entry>
- <entry align="center">I/PAL</entry>
- <entry align="center">B, G/SECAM</entry>
- <entry align="center">D, K/SECAM</entry>
- <entry align="center">K1/SECAM</entry>
- <entry align="center">L/SECAM</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Frame lines</entry>
- <entry spanname="m">525</entry>
- <entry spanname="x">625</entry>
- </row>
- <row>
- <entry>Frame period (s)</entry>
- <entry spanname="m">1001/30000</entry>
- <entry spanname="x">1/25</entry>
- </row>
- <row>
- <entry>Chrominance sub-carrier frequency (Hz)</entry>
- <entry>3579545 &plusmn;&nbsp;10</entry>
- <entry>3579611.49 &plusmn;&nbsp;10</entry>
- <entry>4433618.75 &plusmn;&nbsp;5 (3582056.25
-&plusmn;&nbsp;5)</entry>
- <entry spanname="b">4433618.75 &plusmn;&nbsp;5</entry>
- <entry>4433618.75 &plusmn;&nbsp;1</entry>
- <entry spanname="s">f<subscript>OR</subscript>&nbsp;=
-4406250 &plusmn;&nbsp;2000, f<subscript>OB</subscript>&nbsp;= 4250000
-&plusmn;&nbsp;2000</entry>
- </row>
- <row>
- <entry>Nominal radio-frequency channel bandwidth
-(MHz)</entry>
- <entry>6</entry>
- <entry>6</entry>
- <entry>6</entry>
- <entry>B: 7; B1, G: 8</entry>
- <entry>8</entry>
- <entry>8</entry>
- <entry>8</entry>
- <entry>8</entry>
- <entry>8</entry>
- <entry>8</entry>
- <entry>8</entry>
- </row>
- <row>
- <entry>Sound carrier relative to vision carrier
-(MHz)</entry>
- <entry>+&nbsp;4.5</entry>
- <entry>+&nbsp;4.5</entry>
- <entry>+&nbsp;4.5</entry>
- <entry><para>+&nbsp;5.5 &plusmn;&nbsp;0.001
-<footnote><para>In the Federal Republic of Germany, Austria, Italy,
-the Netherlands, Slovakia and Switzerland a system of two sound
-carriers is used, the frequency of the second carrier being
-242.1875&nbsp;kHz above the frequency of the first sound carrier. For
-stereophonic sound transmissions a similar system is used in
-Australia.</para></footnote> <footnote><para>New Zealand uses a sound
-carrier displaced 5.4996 &plusmn;&nbsp;0.0005 MHz from the vision
-carrier.</para></footnote> <footnote><para>In Denmark, Finland, New
-Zealand, Sweden and Spain a system of two sound carriers is used. In
-Iceland, Norway and Poland the same system is being introduced. The
-second carrier is 5.85&nbsp;MHz above the vision carrier and is DQPSK
-modulated with 728&nbsp;kbit/s sound and data multiplex. (NICAM
-system)</para></footnote> <footnote><para>In the United Kingdom, a
-system of two sound carriers is used. The second sound carrier is
-6.552&nbsp;MHz above the vision carrier and is DQPSK modulated with a
-728&nbsp;kbit/s sound and data multiplex able to carry two sound
-channels. (NICAM system)</para></footnote></para></entry>
- <entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
- <entry>+&nbsp;5.5</entry>
- <entry>+&nbsp;5.9996 &plusmn;&nbsp;0.0005</entry>
- <entry>+&nbsp;5.5 &plusmn;&nbsp;0.001</entry>
- <entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
- <entry>+&nbsp;6.5</entry>
- <entry><para>+&nbsp;6.5 <footnote><para>In France, a
-digital carrier 5.85 MHz away from the vision carrier may be used in
-addition to the main sound carrier. It is modulated in differentially
-encoded QPSK with a 728 kbit/s sound and data multiplexer capable of
-carrying two sound channels. (NICAM
-system)</para></footnote></para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-standard; <structfield>index</structfield>
-is out of bounds.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>Standard video timings are not supported for this input or output.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
deleted file mode 100644
index 4165e7bfa4ff..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
+++ /dev/null
@@ -1,210 +0,0 @@
-<refentry id="vidioc-expbuf">
-
- <refmeta>
- <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_EXPBUF</refname>
- <refpurpose>Export a buffer as a DMABUF file descriptor.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_exportbuffer *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_EXPBUF</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
-<para>This ioctl is an extension to the <link linkend="mmap">memory
-mapping</link> I/O method, therefore it is available only for
-<constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a
-buffer as a DMABUF file at any time after buffers have been allocated with the
-&VIDIOC-REQBUFS; ioctl.</para>
-
-<para> To export a buffer, applications fill &v4l2-exportbuffer;. The
-<structfield> type </structfield> field is set to the same buffer type as was
-previously used with &v4l2-requestbuffers;<structfield> type </structfield>.
-Applications must also set the <structfield> index </structfield> field. Valid
-index numbers range from zero to the number of buffers allocated with
-&VIDIOC-REQBUFS; (&v4l2-requestbuffers;<structfield> count </structfield>)
-minus one. For the multi-planar API, applications set the <structfield> plane
-</structfield> field to the index of the plane to be exported. Valid planes
-range from zero to the maximal number of valid planes for the currently active
-format. For the single-planar API, applications must set <structfield> plane
-</structfield> to zero. Additional flags may be posted in the <structfield>
-flags </structfield> field. Refer to a manual for open() for details.
-Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All
-other fields must be set to zero.
-In the case of multi-planar API, every plane is exported separately using
-multiple <constant> VIDIOC_EXPBUF </constant> calls. </para>
-
-<para> After calling <constant>VIDIOC_EXPBUF</constant> the <structfield> fd
-</structfield> field will be set by a driver. This is a DMABUF file
-descriptor. The application may pass it to other DMABUF-aware devices. Refer to
-<link linkend="dmabuf">DMABUF importing</link> for details about importing
-DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it
-is no longer used to allow the associated memory to be reclaimed. </para>
- </refsect1>
-
- <refsect1>
- <title>Examples</title>
-
- <example>
- <title>Exporting a buffer.</title>
- <programlisting>
-int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd)
-{
- &v4l2-exportbuffer; expbuf;
-
- memset(&amp;expbuf, 0, sizeof(expbuf));
- expbuf.type = bt;
- expbuf.index = index;
- if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;expbuf) == -1) {
- perror("VIDIOC_EXPBUF");
- return -1;
- }
-
- *dmafd = expbuf.fd;
-
- return 0;
-}
- </programlisting>
- </example>
-
- <example>
- <title>Exporting a buffer using the multi-planar API.</title>
- <programlisting>
-int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index,
- int dmafd[], int n_planes)
-{
- int i;
-
- for (i = 0; i &lt; n_planes; ++i) {
- &v4l2-exportbuffer; expbuf;
-
- memset(&amp;expbuf, 0, sizeof(expbuf));
- expbuf.type = bt;
- expbuf.index = index;
- expbuf.plane = i;
- if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;expbuf) == -1) {
- perror("VIDIOC_EXPBUF");
- while (i)
- close(dmafd[--i]);
- return -1;
- }
- dmafd[i] = expbuf.fd;
- }
-
- return 0;
-}
- </programlisting>
- </example>
-
- <table pgwide="1" frame="none" id="v4l2-exportbuffer">
- <title>struct <structname>v4l2_exportbuffer</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the buffer, same as &v4l2-format;
-<structfield>type</structfield> or &v4l2-requestbuffers;
-<structfield>type</structfield>, set by the application. See <xref
-linkend="v4l2-buf-type" /></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the buffer, set by the application. This field is
-only used for <link linkend="mmap">memory mapping</link> I/O and can range from
-zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or
-&VIDIOC-CREATE-BUFS; ioctls. </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>plane</structfield></entry>
- <entry>Index of the plane to be exported when using the
-multi-planar API. Otherwise this value must be set to zero. </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags for the newly created file, currently only <constant>
-O_CLOEXEC </constant>, <constant>O_RDONLY</constant>, <constant>O_WRONLY
-</constant>, and <constant>O_RDWR</constant> are supported, refer to the manual
-of open() for more details.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>fd</structfield></entry>
- <entry>The DMABUF file descriptor associated with a buffer. Set by
- the driver.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved[11]</structfield></entry>
- <entry>Reserved field for future use. Must be set to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
-
- <refsect1>
- &return-value;
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>A queue is not in MMAP mode or DMABUF exporting is not
-supported or <structfield> flags </structfield> or <structfield> type
-</structfield> or <structfield> index </structfield> or <structfield> plane
-</structfield> fields are invalid.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-audio.xml b/Documentation/DocBook/media/v4l/vidioc-g-audio.xml
deleted file mode 100644
index d7bb9b3738f6..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-audio.xml
+++ /dev/null
@@ -1,172 +0,0 @@
-<refentry id="vidioc-g-audio">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_AUDIO</refname>
- <refname>VIDIOC_S_AUDIO</refname>
- <refpurpose>Query or select the current audio input and its
-attributes</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_audio *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the current audio input applications zero out the
-<structfield>reserved</structfield> array of a &v4l2-audio;
-and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer
-to this structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the device has no audio inputs, or none which combine
-with the current video input.</para>
-
- <para>Audio inputs have one writable property, the audio mode. To
-select the current audio input <emphasis>and</emphasis> change the
-audio mode, applications initialize the
-<structfield>index</structfield> and <structfield>mode</structfield>
-fields, and the
-<structfield>reserved</structfield> array of a
-<structname>v4l2_audio</structname> structure and call the
-<constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a
-different audio mode if the request cannot be satisfied. However, this
-is a write-only ioctl, it does not return the actual new audio
-mode.</para>
-
- <table pgwide="1" frame="none" id="v4l2-audio">
- <title>struct <structname>v4l2_audio</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Identifies the audio input, set by the
-driver or application.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the audio input, a NUL-terminated ASCII
-string, for example: "Line In". This information is intended for the
-user, preferably the connector label on the device itself.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry>Audio capability flags, see <xref
- linkend="audio-capability" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>mode</structfield></entry>
- <entry>Audio mode flags set by drivers and applications (on
- <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="audio-capability">
- <title>Audio Capability Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_AUDCAP_STEREO</constant></entry>
- <entry>0x00001</entry>
- <entry>This is a stereo input. The flag is intended to
-automatically disable stereo recording etc. when the signal is always
-monaural. The API provides no means to detect if stereo is
-<emphasis>received</emphasis>, unless the audio input belongs to a
-tuner.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUDCAP_AVL</constant></entry>
- <entry>0x00002</entry>
- <entry>Automatic Volume Level mode is supported.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="audio-mode">
- <title>Audio Mode Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_AUDMODE_AVL</constant></entry>
- <entry>0x00001</entry>
- <entry>AVL mode is on.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>No audio inputs combine with the current video input,
-or the number of the selected audio input is out of bounds or it does
-not combine.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml b/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml
deleted file mode 100644
index 200a2704a970..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-<refentry id="vidioc-g-audioout">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_AUDOUT</refname>
- <refname>VIDIOC_S_AUDOUT</refname>
- <refpurpose>Query or select the current audio output</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the current audio output applications zero out the
-<structfield>reserved</structfield> array of a &v4l2-audioout; and
-call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
-to this structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the device has no audio inputs, or none which combine
-with the current video output.</para>
-
- <para>Audio outputs have no writable properties. Nevertheless, to
-select the current audio output applications can initialize the
-<structfield>index</structfield> field and
-<structfield>reserved</structfield> array (which in the future may
-contain writable properties) of a
-<structname>v4l2_audioout</structname> structure and call the
-<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
-requested output or return the &EINVAL; when the index is out of
-bounds. This is a write-only ioctl, it does not return the current
-audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
-does.</para>
-
- <para>Note connectors on a TV card to loop back the received audio
-signal to a sound card are not audio outputs in this sense.</para>
-
- <table pgwide="1" frame="none" id="v4l2-audioout">
- <title>struct <structname>v4l2_audioout</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Identifies the audio output, set by the
-driver or application.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the audio output, a NUL-terminated ASCII
-string, for example: "Line Out". This information is intended for the
-user, preferably the connector label on the device itself.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry>Audio capability flags, none defined yet. Drivers
-must set this field to zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>mode</structfield></entry>
- <entry>Audio mode, none defined yet. Drivers and
-applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
-field to zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>No audio outputs combine with the current video
-output, or the number of the selected audio output is out of bounds or
-it does not combine.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml
deleted file mode 100644
index e6c4efb9e8b4..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml
+++ /dev/null
@@ -1,129 +0,0 @@
-<refentry id="vidioc-g-crop">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_CROP</refname>
- <refname>VIDIOC_S_CROP</refname>
- <refpurpose>Get or set the current cropping rectangle</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_crop *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_crop *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_CROP, VIDIOC_S_CROP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the cropping rectangle size and position
-applications set the <structfield>type</structfield> field of a
-<structname>v4l2_crop</structname> structure to the respective buffer
-(stream) type and call the <constant>VIDIOC_G_CROP</constant> ioctl
-with a pointer to this structure. The driver fills the rest of the
-structure or returns the &EINVAL; if cropping is not supported.</para>
-
- <para>To change the cropping rectangle applications initialize the
-<structfield>type</structfield> and &v4l2-rect; substructure named
-<structfield>c</structfield> of a v4l2_crop structure and call the
-<constant>VIDIOC_S_CROP</constant> ioctl with a pointer to this
-structure.</para>
-
-<para>Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
-instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
-and use <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>.</para>
-
- <para>The driver first adjusts the requested dimensions against
-hardware limits, &ie; the bounds given by the capture/output window,
-and it rounds to the closest possible values of horizontal and
-vertical offset, width and height. In particular the driver must round
-the vertical offset of the cropping rectangle to frame lines modulo
-two, such that the field order cannot be confused.</para>
-
- <para>Second the driver adjusts the image size (the opposite
-rectangle of the scaling process, source or target depending on the
-data direction) to the closest size possible while maintaining the
-current horizontal and vertical scaling factor.</para>
-
- <para>Finally the driver programs the hardware with the actual
-cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a
-write-only ioctl, it does not return the actual parameters. To query
-them applications must call <constant>VIDIOC_G_CROP</constant> and
-&VIDIOC-G-FMT;. When the parameters are unsuitable the application may
-modify the cropping or image parameters and repeat the cycle until
-satisfactory parameters have been negotiated.</para>
-
- <para>When cropping is not supported then no parameters are
-changed and <constant>VIDIOC_S_CROP</constant> returns the
-&EINVAL;.</para>
-
- <table pgwide="1" frame="none" id="v4l2-crop">
- <title>struct <structname>v4l2_crop</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the data stream, set by the application.
-Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and
-<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry>
- </row>
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>c</structfield></entry>
- <entry>Cropping rectangle. The same co-ordinate system as
-for &v4l2-cropcap; <structfield>bounds</structfield> is used.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml
deleted file mode 100644
index ee2820d6ca66..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml
+++ /dev/null
@@ -1,133 +0,0 @@
-<refentry id="vidioc-g-ctrl">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_CTRL</refname>
- <refname>VIDIOC_S_CTRL</refname>
- <refpurpose>Get or set the value of a control</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_control
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To get the current value of a control applications
-initialize the <structfield>id</structfield> field of a struct
-<structname>v4l2_control</structname> and call the
-<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this
-structure. To change the value of a control applications initialize
-the <structfield>id</structfield> and <structfield>value</structfield>
-fields of a struct <structname>v4l2_control</structname> and call the
-<constant>VIDIOC_S_CTRL</constant> ioctl.</para>
-
- <para>When the <structfield>id</structfield> is invalid drivers
-return an &EINVAL;. When the <structfield>value</structfield> is out
-of bounds drivers can choose to take the closest valid value or return
-an &ERANGE;, whatever seems more appropriate. However,
-<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
-return the actual new value. If the <structfield>value</structfield>
-is inappropriate for the control (e.g. if it refers to an unsupported
-menu index of a menu control), then &EINVAL; is returned as well.</para>
-
- <para>These ioctls work only with user controls. For other
-control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
-&VIDIOC-TRY-EXT-CTRLS; must be used.</para>
-
- <table pgwide="1" frame="none" id="v4l2-control">
- <title>struct <structname>v4l2_control</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>Identifies the control, set by the
-application.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>value</structfield></entry>
- <entry>New value or current value.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-control; <structfield>id</structfield> is
-invalid or the <structfield>value</structfield> is inappropriate for
-the given control (i.e. if a menu item is selected that is not supported
-by the driver according to &VIDIOC-QUERYMENU;).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ERANGE</errorcode></term>
- <listitem>
- <para>The &v4l2-control; <structfield>value</structfield>
-is out of bounds.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The control is temporarily not changeable, possibly
-because another applications took over control of the device function
-this control belongs to.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para>Attempt to set a read-only control or to get a
- write-only control.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
deleted file mode 100644
index 764b635ed4cf..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
+++ /dev/null
@@ -1,341 +0,0 @@
-<refentry id="vidioc-g-dv-timings">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_DV_TIMINGS</refname>
- <refname>VIDIOC_S_DV_TIMINGS</refname>
- <refpurpose>Get or set DV timings for input or output</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
- <para>To set DV timings for the input or output, applications use the
-<constant>VIDIOC_S_DV_TIMINGS</constant> ioctl and to get the current timings,
-applications use the <constant>VIDIOC_G_DV_TIMINGS</constant> ioctl. The detailed timing
-information is filled in using the structure &v4l2-dv-timings;. These ioctls take
-a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not supported
-or the timing values are not correct, the driver returns &EINVAL;.</para>
-<para>The <filename>linux/v4l2-dv-timings.h</filename> header can be used to get the
-timings of the formats in the <xref linkend="cea861" /> and <xref linkend="vesadmt" />
-standards. If the current input or output does not support DV timings (e.g. if
-&VIDIOC-ENUMINPUT; does not set the <constant>V4L2_IN_CAP_DV_TIMINGS</constant> flag), then
-&ENODATA; is returned.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>This ioctl is not supported, or the
-<constant>VIDIOC_S_DV_TIMINGS</constant> parameter was unsuitable.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>Digital video timings are not supported for this input or output.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The device is busy and therefore can not change the timings.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <table pgwide="1" frame="none" id="v4l2-bt-timings">
- <title>struct <structname>v4l2_bt_timings</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Width of the active video in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Height of the active video frame in lines. So for interlaced formats the
- height of the active video in each field is <structfield>height</structfield>/2.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>interlaced</structfield></entry>
- <entry>Progressive (0) or interlaced (1)</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>polarities</structfield></entry>
- <entry>This is a bit mask that defines polarities of sync signals.
-bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_HSYNC_POS_POL) is for horizontal sync polarity. If the bit is set
-(1) it is positive polarity and if is cleared (0), it is negative polarity.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>pixelclock</structfield></entry>
- <entry>Pixel clock in Hz. Ex. 74.25MHz->74250000</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>hfrontporch</structfield></entry>
- <entry>Horizontal front porch in pixels</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>hsync</structfield></entry>
- <entry>Horizontal sync length in pixels</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>hbackporch</structfield></entry>
- <entry>Horizontal back porch in pixels</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>vfrontporch</structfield></entry>
- <entry>Vertical front porch in lines. For interlaced formats this refers to the
- odd field (aka field 1).</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>vsync</structfield></entry>
- <entry>Vertical sync length in lines. For interlaced formats this refers to the
- odd field (aka field 1).</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>vbackporch</structfield></entry>
- <entry>Vertical back porch in lines. For interlaced formats this refers to the
- odd field (aka field 1).</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>il_vfrontporch</structfield></entry>
- <entry>Vertical front porch in lines for the even field (aka field 2) of
- interlaced field formats. Must be 0 for progressive formats.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>il_vsync</structfield></entry>
- <entry>Vertical sync length in lines for the even field (aka field 2) of
- interlaced field formats. Must be 0 for progressive formats.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>il_vbackporch</structfield></entry>
- <entry>Vertical back porch in lines for the even field (aka field 2) of
- interlaced field formats. Must be 0 for progressive formats.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>standards</structfield></entry>
- <entry>The video standard(s) this format belongs to. This will be filled in by
- the driver. Applications must set this to 0. See <xref linkend="dv-bt-standards"/>
- for a list of standards.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Several flags giving more information about the format.
- See <xref linkend="dv-bt-flags"/> for a description of the flags.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-dv-timings">
- <title>struct <structname>v4l2_dv_timings</structname></title>
- <tgroup cols="4">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield></structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-bt-timings;</entry>
- <entry><structfield>bt</structfield></entry>
- <entry>Timings defined by BT.656/1120 specifications</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[32]</entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="dv-timing-types">
- <title>DV Timing types</title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>Timing type</entry>
- <entry>value</entry>
- <entry>Description</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_656_1120</entry>
- <entry>0</entry>
- <entry>BT.656/1120 timings</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="dv-bt-standards">
- <title>DV BT Timing standards</title>
- <tgroup cols="2">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>Timing standard</entry>
- <entry>Description</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_STD_CEA861</entry>
- <entry>The timings follow the CEA-861 Digital TV Profile standard</entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_STD_DMT</entry>
- <entry>The timings follow the VESA Discrete Monitor Timings standard</entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_STD_CVT</entry>
- <entry>The timings follow the VESA Coordinated Video Timings standard</entry>
- </row>
- <row>
- <entry>V4L2_DV_BT_STD_GTF</entry>
- <entry>The timings follow the VESA Generalized Timings Formula standard</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table pgwide="1" frame="none" id="dv-bt-flags">
- <title>DV BT Timing flags</title>
- <tgroup cols="2">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>Flag</entry>
- <entry>Description</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry>V4L2_DV_FL_REDUCED_BLANKING</entry>
- <entry>CVT/GTF specific: the timings use reduced blanking (CVT) or the 'Secondary
-GTF' curve (GTF). In both cases the horizontal and/or vertical blanking
-intervals are reduced, allowing a higher resolution over the same
-bandwidth. This is a read-only flag, applications must not set this.
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_FL_CAN_REDUCE_FPS</entry>
- <entry>CEA-861 specific: set for CEA-861 formats with a framerate that is a multiple
-of six. These formats can be optionally played at 1 / 1.001 speed to
-be compatible with 60 Hz based standards such as NTSC and PAL-M that use a framerate of
-29.97 frames per second. If the transmitter can't generate such frequencies, then the
-flag will also be cleared. This is a read-only flag, applications must not set this.
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_FL_REDUCED_FPS</entry>
- <entry>CEA-861 specific: only valid for video transmitters, the flag is cleared
-by receivers. It is also only valid for formats with the V4L2_DV_FL_CAN_REDUCE_FPS flag
-set, for other formats the flag will be cleared by the driver.
-
-If the application sets this flag, then the pixelclock used to set up the transmitter is
-divided by 1.001 to make it compatible with NTSC framerates. If the transmitter
-can't generate such frequencies, then the flag will also be cleared.
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_FL_HALF_LINE</entry>
- <entry>Specific to interlaced formats: if set, then the vertical frontporch
-of field 1 (aka the odd field) is really one half-line longer and the vertical backporch
-of field 2 (aka the even field) is really one half-line shorter, so each field has exactly
-the same number of half-lines. Whether half-lines can be detected or used depends on
-the hardware.
- </entry>
- </row>
- <row>
- <entry>V4L2_DV_FL_IS_CE_VIDEO</entry>
- <entry>If set, then this is a Consumer Electronics (CE) video format.
-Such formats differ from other formats (commonly called IT formats) in that if
-R'G'B' encoding is used then by default the R'G'B' values use limited range
-(i.e. 16-235) as opposed to full range (i.e. 0-255). All formats defined in CEA-861
-except for the 640x480p59.94 format are CE formats.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
deleted file mode 100644
index 6df40db4c8ba..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml
+++ /dev/null
@@ -1,162 +0,0 @@
-<refentry id="vidioc-g-edid">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_EDID</refname>
- <refname>VIDIOC_S_EDID</refname>
- <refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_EDID, VIDIOC_S_EDID</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
- <para>These ioctls can be used to get or set an EDID associated with an input
- from a receiver or an output of a transmitter device. They can be
- used with subdevice nodes (/dev/v4l-subdevX) or with video nodes (/dev/videoX).</para>
-
- <para>When used with video nodes the <structfield>pad</structfield> field represents the
- input (for video capture devices) or output (for video output devices) index as
- is returned by &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively. When used
- with subdevice nodes the <structfield>pad</structfield> field represents the
- input or output pad of the subdevice. If there is no EDID support for the given
- <structfield>pad</structfield> value, then the &EINVAL; will be returned.</para>
-
- <para>To get the EDID data the application has to fill in the <structfield>pad</structfield>,
- <structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield>
- fields and call <constant>VIDIOC_G_EDID</constant>. The current EDID from block
- <structfield>start_block</structfield> and of size <structfield>blocks</structfield>
- will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield>
- pointer must point to memory at least <structfield>blocks</structfield>&nbsp;*&nbsp;128 bytes
- large (the size of one block is 128 bytes).</para>
-
- <para>If there are fewer blocks than specified, then the driver will set <structfield>blocks</structfield>
- to the actual number of blocks. If there are no EDID blocks available at all, then the error code
- ENODATA is set.</para>
-
- <para>If blocks have to be retrieved from the sink, then this call will block until they
- have been read.</para>
-
- <para>To set the EDID blocks of a receiver the application has to fill in the <structfield>pad</structfield>,
- <structfield>blocks</structfield> and <structfield>edid</structfield> fields and set
- <structfield>start_block</structfield> to 0. It is not possible to set part of an EDID,
- it is always all or nothing. Setting the EDID data is only valid for receivers as it makes
- no sense for a transmitter.</para>
-
- <para>The driver assumes that the full EDID is passed in. If there are more EDID blocks than
- the hardware can handle then the EDID is not written, but instead the error code E2BIG is set
- and <structfield>blocks</structfield> is set to the maximum that the hardware supports.
- If <structfield>start_block</structfield> is any
- value other than 0 then the error code EINVAL is set.</para>
-
- <para>To disable an EDID you set <structfield>blocks</structfield> to 0. Depending on the
- hardware this will drive the hotplug pin low and/or block the source from reading the EDID
- data in some way. In any case, the end result is the same: the EDID is no longer available.
- </para>
-
- <table pgwide="1" frame="none" id="v4l2-edid">
- <title>struct <structname>v4l2_edid</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad for which to get/set the EDID blocks. When used with a video device
- node the pad represents the input or output index as returned by
- &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>start_block</structfield></entry>
- <entry>Read the EDID from starting with this block. Must be 0 when setting
- the EDID.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>blocks</structfield></entry>
- <entry>The number of blocks to get or set. Must be less or equal to 256 (the
- maximum number of blocks as defined by the standard). When you set the EDID and
- <structfield>blocks</structfield> is 0, then the EDID is disabled or erased.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[5]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- <row>
- <entry>__u8&nbsp;*</entry>
- <entry><structfield>edid</structfield></entry>
- <entry>Pointer to memory that contains the EDID. The minimum size is
- <structfield>blocks</structfield>&nbsp;*&nbsp;128.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>The EDID data is not available.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>E2BIG</errorcode></term>
- <listitem>
- <para>The EDID data you provided is more than the hardware can handle.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml
deleted file mode 100644
index be25029a16f1..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml
+++ /dev/null
@@ -1,189 +0,0 @@
-<refentry id="vidioc-g-enc-index">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_ENC_INDEX</refname>
- <refpurpose>Get meta data about a compressed video stream</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_enc_idx *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_ENC_INDEX</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides
-meta data about a compressed video stream the same or another
-application currently reads from the driver, which is useful for
-random access into the stream without decoding it.</para>
-
- <para>To read the data applications must call
-<constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a
-&v4l2-enc-idx;. On success the driver fills the
-<structfield>entry</structfield> array, stores the number of elements
-written in the <structfield>entries</structfield> field, and
-initializes the <structfield>entries_cap</structfield> field.</para>
-
- <para>Each element of the <structfield>entry</structfield> array
-contains meta data about one picture. A
-<constant>VIDIOC_G_ENC_INDEX</constant> call reads up to
-<constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver
-buffer, which can hold up to <structfield>entries_cap</structfield>
-entries. This number can be lower or higher than
-<constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the
-application fails to read the meta data in time the oldest entries
-will be lost. When the buffer is empty or no capturing/encoding is in
-progress, <structfield>entries</structfield> will be zero.</para>
-
- <para>Currently this ioctl is only defined for MPEG-2 program
-streams and video elementary streams.</para>
-
- <table pgwide="1" frame="none" id="v4l2-enc-idx">
- <title>struct <structname>v4l2_enc_idx</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>entries</structfield></entry>
- <entry>The number of entries the driver stored in the
-<structfield>entry</structfield> array.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>entries_cap</structfield></entry>
- <entry>The number of entries the driver can
-buffer. Must be greater than zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry spanname="hspan">Reserved for future extensions.
-Drivers must set the array to zero.</entry>
- </row>
- <row>
- <entry>&v4l2-enc-idx-entry;</entry>
- <entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry>
- <entry>Meta data about a compressed video stream. Each
-element of the array corresponds to one picture, sorted in ascending
-order by their <structfield>offset</structfield>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-enc-idx-entry">
- <title>struct <structname>v4l2_enc_idx_entry</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u64</entry>
- <entry><structfield>offset</structfield></entry>
- <entry>The offset in bytes from the beginning of the
-compressed video stream to the beginning of this picture, that is a
-<wordasword>PES packet header</wordasword> as defined in <xref
- linkend="mpeg2part1" /> or a <wordasword>picture
-header</wordasword> as defined in <xref linkend="mpeg2part2" />. When
-the encoder is stopped, the driver resets the offset to zero.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>pts</structfield></entry>
- <entry>The 33 bit <wordasword>Presentation Time
-Stamp</wordasword> of this picture as defined in <xref
- linkend="mpeg2part1" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>length</structfield></entry>
- <entry>The length of this picture in bytes.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags containing the coding type of this picture, see <xref
- linkend="enc-idx-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions.
-Drivers must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="enc-idx-flags">
- <title>Index Entry Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry>
- <entry>0x00</entry>
- <entry>This is an Intra-coded picture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry>
- <entry>0x01</entry>
- <entry>This is a Predictive-coded picture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry>
- <entry>0x02</entry>
- <entry>This is a Bidirectionally predictive-coded
-picture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry>
- <entry>0x0F</entry>
- <entry><wordasword>AND</wordasword> the flags field with
-this mask to obtain the picture coding type.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
deleted file mode 100644
index c5bdbfcc42b3..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
+++ /dev/null
@@ -1,427 +0,0 @@
-<refentry id="vidioc-g-ext-ctrls">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
-VIDIOC_TRY_EXT_CTRLS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_EXT_CTRLS</refname>
- <refname>VIDIOC_S_EXT_CTRLS</refname>
- <refname>VIDIOC_TRY_EXT_CTRLS</refname>
- <refpurpose>Get or set the value of several controls, try control
-values</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_ext_controls
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
-VIDIOC_TRY_EXT_CTRLS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>These ioctls allow the caller to get or set multiple
-controls atomically. Control IDs are grouped into control classes (see
-<xref linkend="ctrl-class" />) and all controls in the control array
-must belong to the same control class.</para>
-
- <para>Applications must always fill in the
-<structfield>count</structfield>,
-<structfield>ctrl_class</structfield>,
-<structfield>controls</structfield> and
-<structfield>reserved</structfield> fields of &v4l2-ext-controls;, and
-initialize the &v4l2-ext-control; array pointed to by the
-<structfield>controls</structfield> fields.</para>
-
- <para>To get the current value of a set of controls applications
-initialize the <structfield>id</structfield>,
-<structfield>size</structfield> and <structfield>reserved2</structfield> fields
-of each &v4l2-ext-control; and call the
-<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
-must also set the <structfield>string</structfield> field. Controls
-of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set)
-must set the <structfield>ptr</structfield> field.</para>
-
- <para>If the <structfield>size</structfield> is too small to
-receive the control result (only relevant for pointer-type controls
-like strings), then the driver will set <structfield>size</structfield>
-to a valid value and return an &ENOSPC;. You should re-allocate the
-memory to this new size and try again. For the string type it is possible that
-the same issue occurs again if the string has grown in the meantime. It is
-recommended to call &VIDIOC-QUERYCTRL; first and use
-<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
-value. It is guaranteed that that is sufficient memory.
-</para>
-
- <para>N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial
-array, all elements have to be set or retrieved. The total size is calculated
-as <structfield>elems</structfield> * <structfield>elem_size</structfield>.
-These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para>
-
- <para>To change the value of a set of controls applications
-initialize the <structfield>id</structfield>, <structfield>size</structfield>,
-<structfield>reserved2</structfield> and
-<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and
-call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
-will only be set if <emphasis>all</emphasis> control values are
-valid.</para>
-
- <para>To check if a set of controls have correct values applications
-initialize the <structfield>id</structfield>, <structfield>size</structfield>,
-<structfield>reserved2</structfield> and
-<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and
-call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
-the driver whether wrong values are automatically adjusted to a valid
-value or if an error is returned.</para>
-
- <para>When the <structfield>id</structfield> or
-<structfield>ctrl_class</structfield> is invalid drivers return an
-&EINVAL;. When the value is out of bounds drivers can choose to take
-the closest valid value or return an &ERANGE;, whatever seems more
-appropriate. In the first case the new value is set in
-&v4l2-ext-control;. If the new control value is inappropriate (e.g. the
-given menu index is not supported by the menu control), then this will
-also result in an &EINVAL; error.</para>
-
- <para>The driver will only set/get these controls if all control
-values are correct. This prevents the situation where only some of the
-controls were set/get. Only low-level errors (&eg; a failed i2c
-command) can still cause this situation.</para>
-
- <table pgwide="1" frame="none" id="v4l2-ext-control">
- <title>struct <structname>v4l2_ext_control</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry></entry>
- <entry>Identifies the control, set by the
-application.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>size</structfield></entry>
- <entry></entry>
- <entry>The total size in bytes of the payload of this
-control. This is normally 0, but for pointer controls this should be
-set to the size of the memory containing the payload, or that will
-receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds
-that this value is less than is required to store
-the payload result, then it is set to a value large enough to store the
-payload result and ENOSPC is returned. Note that for string controls
-this <structfield>size</structfield> field should not be confused with the length of the string.
-This field refers to the size of the memory that contains the string.
-The actual <emphasis>length</emphasis> of the string may well be much smaller.
-</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved2</structfield>[1]</entry>
- <entry></entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry>(anonymous)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__s32</entry>
- <entry><structfield>value</structfield></entry>
- <entry>New value or current value. Valid if this control is not of
-type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
-<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__s64</entry>
- <entry><structfield>value64</structfield></entry>
- <entry>New value or current value. Valid if this control is of
-type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
-<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>char *</entry>
- <entry><structfield>string</structfield></entry>
- <entry>A pointer to a string. Valid if this control is of
-type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u8 *</entry>
- <entry><structfield>p_u8</structfield></entry>
- <entry>A pointer to a matrix control of unsigned 8-bit values.
-Valid if this control is of type <constant>V4L2_CTRL_TYPE_U8</constant>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u16 *</entry>
- <entry><structfield>p_u16</structfield></entry>
- <entry>A pointer to a matrix control of unsigned 16-bit values.
-Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>void *</entry>
- <entry><structfield>ptr</structfield></entry>
- <entry>A pointer to a compound type which can be an N-dimensional array and/or a
-compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>).
-Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control.
-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-ext-controls">
- <title>struct <structname>v4l2_ext_controls</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>ctrl_class</structfield></entry>
- <entry>The control class to which all controls belong, see
-<xref linkend="ctrl-class" />. Drivers that use a kernel framework for handling
-controls will also accept a value of 0 here, meaning that the controls can
-belong to any control class. Whether drivers support this can be tested by setting
-<structfield>ctrl_class</structfield> to 0 and calling <constant>VIDIOC_TRY_EXT_CTRLS</constant>
-with a <structfield>count</structfield> of 0. If that succeeds, then the driver
-supports this feature.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>count</structfield></entry>
- <entry>The number of controls in the controls array. May
-also be zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>error_idx</structfield></entry>
- <entry><para>Set by the driver in case of an error. If the error is
-associated with a particular control, then <structfield>error_idx</structfield>
-is set to the index of that control. If the error is not related to a specific
-control, or the validation step failed (see below), then
-<structfield>error_idx</structfield> is set to <structfield>count</structfield>.
-The value is undefined if the ioctl returned 0 (success).</para>
-
-<para>Before controls are read from/written to hardware a validation step
-takes place: this checks if all controls in the list are valid controls,
-if no attempt is made to write to a read-only control or read from a write-only
-control, and any other up-front checks that can be done without accessing the
-hardware. The exact validations done during this step are driver dependent
-since some checks might require hardware access for some devices, thus making
-it impossible to do those checks up-front. However, drivers should make a
-best-effort to do as many up-front checks as possible.</para>
-
-<para>This check is done to avoid leaving the hardware in an inconsistent state due
-to easy-to-avoid problems. But it leads to another problem: the application needs to
-know whether an error came from the validation step (meaning that the hardware
-was not touched) or from an error during the actual reading from/writing to hardware.</para>
-
-<para>The, in hindsight quite poor, solution for that is to set <structfield>error_idx</structfield>
-to <structfield>count</structfield> if the validation failed. This has the
-unfortunate side-effect that it is not possible to see which control failed the
-validation. If the validation was successful and the error happened while
-accessing the hardware, then <structfield>error_idx</structfield> is less than
-<structfield>count</structfield> and only the controls up to
-<structfield>error_idx-1</structfield> were read or written correctly, and the
-state of the remaining controls is undefined.</para>
-
-<para>Since <constant>VIDIOC_TRY_EXT_CTRLS</constant> does not access hardware
-there is also no need to handle the validation step in this special way,
-so <structfield>error_idx</structfield> will just be set to the control that
-failed the validation step instead of to <structfield>count</structfield>.
-This means that if <constant>VIDIOC_S_EXT_CTRLS</constant> fails with
-<structfield>error_idx</structfield> set to <structfield>count</structfield>,
-then you can call <constant>VIDIOC_TRY_EXT_CTRLS</constant> to try to discover
-the actual control that failed the validation step. Unfortunately, there
-is no <constant>TRY</constant> equivalent for <constant>VIDIOC_G_EXT_CTRLS</constant>.
-</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- <row>
- <entry>&v4l2-ext-control; *</entry>
- <entry><structfield>controls</structfield></entry>
- <entry>Pointer to an array of
-<structfield>count</structfield> v4l2_ext_control structures. Ignored
-if <structfield>count</structfield> equals zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="ctrl-class">
- <title>Control classes</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry>
- <entry>0x980000</entry>
- <entry>The class containing user controls. These controls
-are described in <xref linkend="control" />. All controls that can be set
-using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this
-class.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry>
- <entry>0x990000</entry>
- <entry>The class containing MPEG compression controls.
-These controls are described in <xref
- linkend="mpeg-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry>
- <entry>0x9a0000</entry>
- <entry>The class containing camera controls.
-These controls are described in <xref
- linkend="camera-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry>
- <entry>0x9b0000</entry>
- <entry>The class containing FM Transmitter (FM TX) controls.
-These controls are described in <xref
- linkend="fm-tx-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_FLASH</constant></entry>
- <entry>0x9c0000</entry>
- <entry>The class containing flash device controls.
-These controls are described in <xref
- linkend="flash-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_JPEG</constant></entry>
- <entry>0x9d0000</entry>
- <entry>The class containing JPEG compression controls.
-These controls are described in <xref
- linkend="jpeg-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_IMAGE_SOURCE</constant></entry>
- <entry>0x9e0000</entry> <entry>The class containing image
- source controls. These controls are described in <xref
- linkend="image-source-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_IMAGE_PROC</constant></entry>
- <entry>0x9f0000</entry> <entry>The class containing image
- processing controls. These controls are described in <xref
- linkend="image-process-controls" />.</entry>
- </row>
-
- <row>
- <entry><constant>V4L2_CTRL_CLASS_FM_RX</constant></entry>
- <entry>0xa10000</entry>
- <entry>The class containing FM Receiver (FM RX) controls.
-These controls are described in <xref
- linkend="fm-rx-controls" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_CLASS_RF_TUNER</constant></entry>
- <entry>0xa20000</entry>
- <entry>The class containing RF tuner controls.
-These controls are described in <xref linkend="rf-tuner-controls" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-ext-control; <structfield>id</structfield>
-is invalid, the &v4l2-ext-controls;
-<structfield>ctrl_class</structfield> is invalid, or the &v4l2-ext-control;
-<structfield>value</structfield> was inappropriate (e.g. the given menu
-index is not supported by the driver). This error code is
-also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and
-<constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more
-control values are in conflict.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ERANGE</errorcode></term>
- <listitem>
- <para>The &v4l2-ext-control; <structfield>value</structfield>
-is out of bounds.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The control is temporarily not changeable, possibly
-because another applications took over control of the device function
-this control belongs to.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOSPC</errorcode></term>
- <listitem>
- <para>The space reserved for the control's payload is insufficient.
-The field <structfield>size</structfield> is set to a value that is enough
-to store the payload and this error code is returned.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para>Attempt to try or set a read-only control or to get a
- write-only control.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
-
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
deleted file mode 100644
index 77607cc19688..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
+++ /dev/null
@@ -1,459 +0,0 @@
-<refentry id="vidioc-g-fbuf">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_FBUF</refname>
- <refname>VIDIOC_S_FBUF</refname>
- <refpurpose>Get or set frame buffer overlay parameters</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and
-<constant>VIDIOC_S_FBUF</constant> ioctl to get and set the
-framebuffer parameters for a <link linkend="overlay">Video
-Overlay</link> or <link linkend="osd">Video Output Overlay</link>
-(OSD). The type of overlay is implied by the device type (capture or
-output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl.
-One <filename>/dev/videoN</filename> device must not support both
-kinds of overlay.</para>
-
- <para>The V4L2 API distinguishes destructive and non-destructive
-overlays. A destructive overlay copies captured video images into the
-video memory of a graphics card. A non-destructive overlay blends
-video images into a VGA signal or graphics into a video signal.
-<wordasword>Video Output Overlays</wordasword> are always
-non-destructive.</para>
-
- <para>To get the current parameters applications call the
-<constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a
-<structname>v4l2_framebuffer</structname> structure. The driver fills
-all fields of the structure or returns an &EINVAL; when overlays are
-not supported.</para>
-
- <para>To set the parameters for a <wordasword>Video Output
-Overlay</wordasword>, applications must initialize the
-<structfield>flags</structfield> field of a struct
-<structname>v4l2_framebuffer</structname>. Since the framebuffer is
-implemented on the TV card all other parameters are determined by the
-driver. When an application calls <constant>VIDIOC_S_FBUF</constant>
-with a pointer to this structure, the driver prepares for the overlay
-and returns the framebuffer parameters as
-<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
-code.</para>
-
- <para>To set the parameters for a <wordasword>non-destructive
-Video Overlay</wordasword>, applications must initialize the
-<structfield>flags</structfield> field, the
-<structfield>fmt</structfield> substructure, and call
-<constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the
-overlay and returns the framebuffer parameters as
-<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
-code.</para>
-
- <para>For a <wordasword>destructive Video Overlay</wordasword>
-applications must additionally provide a
-<structfield>base</structfield> address. Setting up a DMA to a
-random memory location can jeopardize the system security, its
-stability or even damage the hardware, therefore only the superuser
-can set the parameters for a destructive video overlay.</para>
-
- <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.-->
-
- <table pgwide="1" frame="none" id="v4l2-framebuffer">
- <title>struct <structname>v4l2_framebuffer</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry></entry>
- <entry>Overlay capability flags set by the driver, see
-<xref linkend="framebuffer-cap" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry></entry>
- <entry>Overlay control flags set by application and
-driver, see <xref linkend="framebuffer-flags" /></entry>
- </row>
- <row>
- <entry>void *</entry>
- <entry><structfield>base</structfield></entry>
- <entry></entry>
- <entry>Physical base address of the framebuffer,
-that is the address of the pixel in the top left corner of the
-framebuffer.<footnote><para>A physical base address may not suit all
-platforms. GK notes in theory we should pass something like PCI device
-+ memory region + offset instead. If you encounter problems please
-discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>This field is irrelevant to
-<wordasword>non-destructive Video Overlays</wordasword>. For
-<wordasword>destructive Video Overlays</wordasword> applications must
-provide a base address. The driver may accept only base addresses
-which are a multiple of two, four or eight bytes. For
-<wordasword>Video Output Overlays</wordasword> the driver must return
-a valid base address, so applications can find the corresponding Linux
-framebuffer device (see <xref linkend="osd" />).</entry>
- </row>
- <row>
- <entry>struct</entry>
- <entry><structfield>fmt</structfield></entry>
- <entry></entry>
- <entry>Layout of the frame buffer.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Width of the frame buffer in pixels.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Height of the frame buffer in pixels.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>pixelformat</structfield></entry>
- <entry>The pixel format of the
-framebuffer.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>For <wordasword>non-destructive Video
-Overlays</wordasword> this field only defines a format for the
-&v4l2-window; <structfield>chromakey</structfield> field.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>For <wordasword>destructive Video
-Overlays</wordasword> applications must initialize this field. For
-<wordasword>Video Output Overlays</wordasword> the driver must return
-a valid format.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- <entry>Usually this is an RGB format (for example
-<link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>)
-but YUV formats (only packed YUV formats when chroma keying is used,
-not including <constant>V4L2_PIX_FMT_YUYV</constant> and
-<constant>V4L2_PIX_FMT_UYVY</constant>) and the
-<constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The
-behavior of the driver when an application requests a compressed
-format is undefined. See <xref linkend="pixfmt" /> for information on
-pixel formats.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>Drivers and applications shall ignore this field.
-If applicable, the field order is selected with the &VIDIOC-S-FMT;
-ioctl, using the <structfield>field</structfield> field of
-&v4l2-window;.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>bytesperline</structfield></entry>
- <entry>Distance in bytes between the leftmost pixels in
-two adjacent lines.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>This field is irrelevant to
-<wordasword>non-destructive Video
-Overlays</wordasword>.</para><para>For <wordasword>destructive Video
-Overlays</wordasword> both applications and drivers can set this field
-to request padding bytes at the end of each line. Drivers however may
-ignore the requested value, returning <structfield>width</structfield>
-times bytes-per-pixel or a larger value required by the hardware. That
-implies applications can just set this field to zero to get a
-reasonable default.</para><para>For <wordasword>Video Output
-Overlays</wordasword> the driver must return a valid
-value.</para><para>Video hardware may access padding bytes, therefore
-they must reside in accessible memory. Consider for example the case
-where padding bytes after the last line of an image cross a system
-page boundary. Capture devices may write padding bytes, the value is
-undefined. Output devices ignore the contents of padding
-bytes.</para><para>When the image format is planar the
-<structfield>bytesperline</structfield> value applies to the first
-plane and is divided by the same factor as the
-<structfield>width</structfield> field for the other planes. For
-example the Cb and Cr planes of a YUV 4:2:0 image have half as many
-padding bytes following each line as the Y plane. To avoid ambiguities
-drivers must return a <structfield>bytesperline</structfield> value
-rounded up to a multiple of the scale factor.</para></entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>sizeimage</structfield></entry>
- <entry><para>This field is irrelevant to
-<wordasword>non-destructive Video Overlays</wordasword>. For
-<wordasword>destructive Video Overlays</wordasword> applications must
-initialize this field. For <wordasword>Video Output
-Overlays</wordasword> the driver must return a valid
-format.</para><para>Together with <structfield>base</structfield> it
-defines the framebuffer memory accessible by the
-driver.</para></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-colorspace;</entry>
- <entry><structfield>colorspace</structfield></entry>
- <entry>This information supplements the
-<structfield>pixelformat</structfield> and must be set by the driver,
-see <xref linkend="colorspaces" />.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u32</entry>
- <entry><structfield>priv</structfield></entry>
- <entry>Reserved. Drivers and applications must set this field to
-zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="framebuffer-cap">
- <title>Frame Buffer Capability Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry>
- <entry>0x0001</entry>
- <entry>The device is capable of non-destructive overlays.
-When the driver clears this flag, only destructive overlays are
-supported. There are no drivers yet which support both destructive and
-non-destructive overlays. Video Output Overlays are in practice always
-non-destructive.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
- <entry>0x0002</entry>
- <entry>The device supports clipping by chroma-keying the
-images. That is, image pixels replace pixels in the VGA or video
-signal only where the latter assume a certain color. Chroma-keying
-makes no sense for destructive overlays.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry>
- <entry>0x0004</entry>
- <entry>The device supports clipping using a list of clip
-rectangles.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry>
- <entry>0x0008</entry>
- <entry>The device supports clipping using a bit mask.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry>
- <entry>0x0010</entry>
- <entry>The device supports clipping/blending using the
-alpha channel of the framebuffer or VGA signal. Alpha blending makes
-no sense for destructive overlays.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry>
- <entry>0x0020</entry>
- <entry>The device supports alpha blending using a global
-alpha value. Alpha blending makes no sense for destructive overlays.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry>
- <entry>0x0040</entry>
- <entry>The device supports clipping/blending using the
-inverted alpha channel of the framebuffer or VGA signal. Alpha
-blending makes no sense for destructive overlays.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry>
- <entry>0x0080</entry>
- <entry>The device supports Source Chroma-keying. Video pixels
-with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of
-<constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="framebuffer-flags">
- <title>Frame Buffer Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
- <entry>0x0001</entry>
- <entry>The framebuffer is the primary graphics surface.
-In other words, the overlay is destructive. This flag is typically set by any
-driver that doesn't have the <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
-capability and it is cleared otherwise.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
- <entry>0x0002</entry>
- <entry>If this flag is set for a video capture device, then the
-driver will set the initial overlay size to cover the full framebuffer size,
-otherwise the existing overlay size (as set by &VIDIOC-S-FMT;) will be used.
-
-Only one video capture driver (bttv) supports this flag. The use of this flag
-for capture devices is deprecated. There is no way to detect which drivers
-support this flag, so the only reliable method of setting the overlay size is
-through &VIDIOC-S-FMT;.
-
-If this flag is set for a video output device, then the video output overlay
-window is relative to the top-left corner of the framebuffer and restricted
-to the size of the framebuffer. If it is cleared, then the video output
-overlay window is relative to the video output display.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
- <entry>0x0004</entry>
- <entry>Use chroma-keying. The chroma-key color is
-determined by the <structfield>chromakey</structfield> field of
-&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
- linkend="overlay" />
-and
- <xref linkend="osd" />.</entry>
- </row>
- <row>
- <entry spanname="hspan">There are no flags to enable
-clipping using a list of clip rectangles or a bitmap. These methods
-are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
- linkend="overlay" /> and <xref linkend="osd" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
- <entry>0x0008</entry>
- <entry>Use the alpha channel of the framebuffer to clip or
-blend framebuffer pixels with video images. The blend
-function is: output = framebuffer pixel * alpha + video pixel * (1 -
-alpha). The actual alpha depth depends on the framebuffer pixel
-format.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
- <entry>0x0010</entry>
- <entry>Use a global alpha value to blend the framebuffer
-with video images. The blend function is: output = (framebuffer pixel
-* alpha + video pixel * (255 - alpha)) / 255. The alpha value is
-determined by the <structfield>global_alpha</structfield> field of
-&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
- linkend="overlay" />
-and <xref linkend="osd" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
- <entry>0x0020</entry>
- <entry>Like
-<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel
-of the framebuffer to clip or blend framebuffer pixels with video
-images, but with an inverted alpha value. The blend function is:
-output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
-actual alpha depth depends on the framebuffer pixel format.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry>
- <entry>0x0040</entry>
- <entry>Use source chroma-keying. The source chroma-key color is
-determined by the <structfield>chromakey</structfield> field of
-&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
-linkend="overlay" /> and <xref linkend="osd" />.
-Both chroma-keying are mutual exclusive to each other, so same
-<structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EPERM</errorcode></term>
- <listitem>
- <para><constant>VIDIOC_S_FBUF</constant> can only be called
-by a privileged user to negotiate the parameters for a destructive
-overlay.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
deleted file mode 100644
index 4fe19a7a9a31..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
+++ /dev/null
@@ -1,204 +0,0 @@
-<refentry id="vidioc-g-fmt">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
-VIDIOC_TRY_FMT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_FMT</refname>
- <refname>VIDIOC_S_FMT</refname>
- <refname>VIDIOC_TRY_FMT</refname>
- <refpurpose>Get or set the data format, try a format</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_format
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>These ioctls are used to negotiate the format of data
-(typically image format) exchanged between driver and
-application.</para>
-
- <para>To query the current parameters applications set the
-<structfield>type</structfield> field of a struct
-<structname>v4l2_format</structname> to the respective buffer (stream)
-type. For example video capture devices use
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
-calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
-this structure the driver fills the respective member of the
-<structfield>fmt</structfield> union. In case of video capture devices
-that is either the &v4l2-pix-format; <structfield>pix</structfield> or
-the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
-When the requested buffer type is not supported drivers return an
-&EINVAL;.</para>
-
- <para>To change the current format parameters applications
-initialize the <structfield>type</structfield> field and all
-fields of the respective <structfield>fmt</structfield>
-union member. For details see the documentation of the various devices
-types in <xref linkend="devices" />. Good practice is to query the
-current parameters first, and to
-modify only those parameters not suitable for the application. When
-the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
-with a pointer to a <structname>v4l2_format</structname> structure
-the driver checks
-and adjusts the parameters against hardware abilities. Drivers
-should not return an error code unless the <structfield>type</structfield> field is invalid, this is
-a mechanism to fathom device capabilities and to approach parameters
-acceptable for both the application and driver. On success the driver
-may program the hardware, allocate resources and generally prepare for
-data exchange.
-Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
-current format parameters as <constant>VIDIOC_G_FMT</constant> does.
-Very simple, inflexible devices may even ignore all input and always
-return the default parameters. However all V4L2 devices exchanging
-data with the application must implement the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
-type is not supported drivers return an &EINVAL; on a
-<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
-progress or the resource is not available for other reasons drivers
-return the &EBUSY;.</para>
-
- <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
-to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
-change driver state. It can also be called at any time, never
-returning <errorcode>EBUSY</errorcode>. This function is provided to
-negotiate parameters, to learn about hardware limitations, without
-disabling I/O or possibly time consuming hardware preparations.
-Although strongly recommended drivers are not required to implement
-this ioctl.</para>
-
- <para>The format as returned by <constant>VIDIOC_TRY_FMT</constant>
-must be identical to what <constant>VIDIOC_S_FMT</constant> returns for
-the same input or output.</para>
-
- <table pgwide="1" frame="none" id="v4l2-format">
- <title>struct <structname>v4l2_format</structname></title>
- <tgroup cols="4">
- <colspec colname="c1" />
- <colspec colname="c2" />
- <colspec colname="c3" />
- <colspec colname="c4" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>Type of the data stream, see <xref
- linkend="v4l2-buf-type" />.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield>fmt</structfield></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-pix-format;</entry>
- <entry><structfield>pix</structfield></entry>
- <entry>Definition of an image format, see <xref
- linkend="pixfmt" />, used by video capture and output
-devices.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-pix-format-mplane;</entry>
- <entry><structfield>pix_mp</structfield></entry>
- <entry>Definition of an image format, see <xref
- linkend="pixfmt" />, used by video capture and output
-devices that support the <link linkend="planar-apis">multi-planar
-version of the API</link>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-window;</entry>
- <entry><structfield>win</structfield></entry>
- <entry>Definition of an overlaid image, see <xref
- linkend="overlay" />, used by video overlay devices.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-vbi-format;</entry>
- <entry><structfield>vbi</structfield></entry>
- <entry>Raw VBI capture or output parameters. This is
-discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
-capture and output devices.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-sliced-vbi-format;</entry>
- <entry><structfield>sliced</structfield></entry>
- <entry>Sliced VBI capture or output parameters. See
-<xref linkend="sliced" /> for details. Used by sliced VBI
-capture and output devices.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-sdr-format;</entry>
- <entry><structfield>sdr</structfield></entry>
- <entry>Definition of a data format, see
-<xref linkend="pixfmt" />, used by SDR capture devices.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u8</entry>
- <entry><structfield>raw_data</structfield>[200]</entry>
- <entry>Place holder for future extensions.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-format; <structfield>type</structfield>
-field is invalid or the requested buffer type not supported.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml
deleted file mode 100644
index d1034fb61d15..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml
+++ /dev/null
@@ -1,148 +0,0 @@
-<refentry id="vidioc-g-frequency">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_FREQUENCY</refname>
- <refname>VIDIOC_S_FREQUENCY</refname>
- <refpurpose>Get or set tuner or modulator radio
-frequency</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_frequency
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_frequency
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To get the current tuner or modulator radio frequency
-applications set the <structfield>tuner</structfield> field of a
-&v4l2-frequency; to the respective tuner or modulator number (only
-input devices have tuners, only output devices have modulators), zero
-out the <structfield>reserved</structfield> array and
-call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer
-to this structure. The driver stores the current frequency in the
-<structfield>frequency</structfield> field.</para>
-
- <para>To change the current tuner or modulator radio frequency
-applications initialize the <structfield>tuner</structfield>,
-<structfield>type</structfield> and
-<structfield>frequency</structfield> fields, and the
-<structfield>reserved</structfield> array of a &v4l2-frequency; and
-call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer
-to this structure. When the requested frequency is not possible the
-driver assumes the closest possible value. However
-<constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does
-not return the actual new frequency.</para>
-
- <table pgwide="1" frame="none" id="v4l2-frequency">
- <title>struct <structname>v4l2_frequency</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>tuner</structfield></entry>
- <entry>The tuner or modulator index number. This is the
-same value as in the &v4l2-input; <structfield>tuner</structfield>
-field and the &v4l2-tuner; <structfield>index</structfield> field, or
-the &v4l2-output; <structfield>modulator</structfield> field and the
-&v4l2-modulator; <structfield>index</structfield> field.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>The tuner type. This is the same value as in the
-&v4l2-tuner; <structfield>type</structfield> field. The type must be set
-to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename>
-device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant>
-for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for
-modulators (currently only radio modulators are supported).
-See <xref linkend="v4l2-tuner-type" /></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>frequency</structfield></entry>
- <entry>Tuning frequency in units of 62.5 kHz, or if the
-&v4l2-tuner; or &v4l2-modulator; <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz. A 1 Hz unit is used when the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Drivers and
- applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <structfield>tuner</structfield> index is out of
-bounds or the value in the <structfield>type</structfield> field is
-wrong.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>A hardware seek is in progress.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-input.xml b/Documentation/DocBook/media/v4l/vidioc-g-input.xml
deleted file mode 100644
index 1d43065090dd..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-input.xml
+++ /dev/null
@@ -1,83 +0,0 @@
-<refentry id="vidioc-g-input">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_INPUT</refname>
- <refname>VIDIOC_S_INPUT</refname>
- <refpurpose>Query or select the current video input</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>int *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_INPUT, VIDIOC_S_INPUT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the current video input applications call the
-<constant>VIDIOC_G_INPUT</constant> ioctl with a pointer to an integer
-where the driver stores the number of the input, as in the
-&v4l2-input; <structfield>index</structfield> field. This ioctl will
-fail only when there are no video inputs, returning
-<errorcode>EINVAL</errorcode>.</para>
-
- <para>To select a video input applications store the number of the
-desired input in an integer and call the
-<constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this
-integer. Side effects are possible. For example inputs may support
-different video standards, so the driver may implicitly switch the
-current standard. Because of these possible side effects applications
-must select an input before querying or negotiating any other parameters.</para>
-
- <para>Information about video inputs is available using the
-&VIDIOC-ENUMINPUT; ioctl.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The number of the video input is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
deleted file mode 100644
index 098ff483802e..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
+++ /dev/null
@@ -1,175 +0,0 @@
-<refentry id="vidioc-g-jpegcomp">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_JPEGCOMP</refname>
- <refname>VIDIOC_S_JPEGCOMP</refname>
- <refpurpose></refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>v4l2_jpegcompression *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const v4l2_jpegcompression *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>These ioctls are <emphasis role="bold">deprecated</emphasis>.
- New drivers and applications should use <link linkend="jpeg-controls">
- JPEG class controls</link> for image quality and JPEG markers control.
- </para>
-
- <para>[to do]</para>
-
- <para>Ronald Bultje elaborates:</para>
-
- <!-- See video4linux-list@redhat.com on 16 Oct 2002, subject
-"Re: [V4L] Re: v4l2 api / Zoran v4l2_jpegcompression" -->
-
- <para>APP is some application-specific information. The
-application can set it itself, and it'll be stored in the JPEG-encoded
-fields (eg; interlacing information for in an AVI or so). COM is the
-same, but it's comments, like 'encoded by me' or so.</para>
-
- <para>jpeg_markers describes whether the huffman tables,
-quantization tables and the restart interval information (all
-JPEG-specific stuff) should be stored in the JPEG-encoded fields.
-These define how the JPEG field is encoded. If you omit them,
-applications assume you've used standard encoding. You usually do want
-to add them.</para>
-
- <!-- NB VIDIOC_S_JPEGCOMP is w/o. -->
-
- <table pgwide="1" frame="none" id="v4l2-jpegcompression">
- <title>struct <structname>v4l2_jpegcompression</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>int</entry>
- <entry><structfield>quality</structfield></entry>
- <entry>Deprecated. If <link linkend="jpeg-quality-control"><constant>
- V4L2_CID_JPEG_COMPRESSION_QUALITY</constant></link> control is exposed
- by a driver applications should use it instead and ignore this field.
- </entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><structfield>APPn</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><structfield>APP_len</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>APP_data</structfield>[60]</entry>
- <entry></entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><structfield>COM_len</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>COM_data</structfield>[60]</entry>
- <entry></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>jpeg_markers</structfield></entry>
- <entry>See <xref linkend="jpeg-markers"/>. Deprecated.
- If <link linkend="jpeg-active-marker-control"><constant>
- V4L2_CID_JPEG_ACTIVE_MARKER</constant></link> control
- is exposed by a driver applications should use it instead
- and ignore this field.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="jpeg-markers">
- <title>JPEG Markers Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_JPEG_MARKER_DHT</constant></entry>
- <entry>(1&lt;&lt;3)</entry>
- <entry>Define Huffman Tables</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_MARKER_DQT</constant></entry>
- <entry>(1&lt;&lt;4)</entry>
- <entry>Define Quantization Tables</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_MARKER_DRI</constant></entry>
- <entry>(1&lt;&lt;5)</entry>
- <entry>Define Restart Interval</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_MARKER_COM</constant></entry>
- <entry>(1&lt;&lt;6)</entry>
- <entry>Comment segment</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_MARKER_APP</constant></entry>
- <entry>(1&lt;&lt;7)</entry>
- <entry>App segment, driver will always use APP0</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml
deleted file mode 100644
index 7068b599a00d..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml
+++ /dev/null
@@ -1,240 +0,0 @@
-<refentry id="vidioc-g-modulator">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_MODULATOR</refname>
- <refname>VIDIOC_S_MODULATOR</refname>
- <refpurpose>Get or set modulator attributes</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_modulator
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_modulator
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of a modulator applications initialize
-the <structfield>index</structfield> field and zero out the
-<structfield>reserved</structfield> array of a &v4l2-modulator; and
-call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer
-to this structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the index is out of bounds. To enumerate all modulators
-applications shall begin at index zero, incrementing by one until the
-driver returns <errorcode>EINVAL</errorcode>.</para>
-
- <para>Modulators have two writable properties, an audio
-modulation set and the radio frequency. To change the modulated audio
-subprograms, applications initialize the <structfield>index
-</structfield> and <structfield>txsubchans</structfield> fields and the
-<structfield>reserved</structfield> array and call the
-<constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a
-different audio modulation if the request cannot be satisfied. However
-this is a write-only ioctl, it does not return the actual audio
-modulation selected.</para>
-
- <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
-is available.</para>
-
- <table pgwide="1" frame="none" id="v4l2-modulator">
- <title>struct <structname>v4l2_modulator</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Identifies the modulator, set by the
-application.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the modulator, a NUL-terminated ASCII
-string. This information is intended for the user.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry>Modulator capability flags. No flags are defined
-for this field, the tuner flags in &v4l2-tuner;
-are used accordingly. The audio flags indicate the ability
-to encode audio subprograms. They will <emphasis>not</emphasis>
-change for example with the current video standard.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangelow</structfield></entry>
- <entry>The lowest tunable frequency in units of 62.5
-KHz, or if the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz, or if the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangehigh</structfield></entry>
- <entry>The highest tunable frequency in units of 62.5
-KHz, or if the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz, or if the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>txsubchans</structfield></entry>
- <entry>With this field applications can determine how
-audio sub-carriers shall be modulated. It contains a set of flags as
-defined in <xref linkend="modulator-txsubchans" />. Note the tuner
-<structfield>rxsubchans</structfield> flags are reused, but the
-semantics are different. Video output devices are assumed to have an
-analog or PCM audio input with 1-3 channels. The
-<structfield>txsubchans</structfield> flags select one or more
-channels for modulation, together with some audio subprogram
-indicator, for example a stereo pilot tone.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="modulator-txsubchans">
- <title>Modulator Audio Transmission Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
- <entry>0x0001</entry>
- <entry>Modulate channel 1 as mono audio, when the input
-has more channels, a down-mix of channel 1 and 2. This flag does not
-combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or
-<constant>V4L2_TUNER_SUB_LANG1</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
- <entry>0x0002</entry>
- <entry>Modulate channel 1 and 2 as left and right
-channel of a stereo audio signal. When the input has only one channel
-or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also
-set, channel 1 is encoded as left and right channel. This flag does
-not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or
-<constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not
-support stereo audio it shall fall back to mono.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
- <entry>0x0008</entry>
- <entry>Modulate channel 1 and 2 as primary and secondary
-language of a bilingual audio signal. When the input has only one
-channel it is used for both languages. It is not possible to encode
-the primary or secondary language only. This flag does not combine
-with <constant>V4L2_TUNER_SUB_MONO</constant>,
-<constant>V4L2_TUNER_SUB_STEREO</constant> or
-<constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not
-support the respective audio matrix, or the current video standard
-does not permit bilingual audio the
-<constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL;
-and the driver shall fall back to mono or stereo mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
- <entry>0x0004</entry>
- <entry>Same effect as
-<constant>V4L2_TUNER_SUB_SAP</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
- <entry>0x0004</entry>
- <entry>When combined with <constant>V4L2_TUNER_SUB_MONO
-</constant> the first channel is encoded as mono audio, the last
-channel as Second Audio Program. When the input has only one channel
-it is used for both audio tracks. When the input has three channels
-the mono track is a down-mix of channel 1 and 2. When combined with
-<constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are
-encoded as left and right stereo audio, channel 3 as Second Audio
-Program. When the input has only two channels, the first is encoded as
-left and right channel and the second as SAP. When the input has only
-one channel it is used for all audio tracks. It is not possible to
-encode a Second Audio Program only. This flag must combine with
-<constant>V4L2_TUNER_SUB_MONO</constant> or
-<constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not
-support the respective audio matrix, or the current video standard
-does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl
-shall return an &EINVAL; and driver shall fall back to mono or stereo
-mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
- <entry>0x0010</entry>
- <entry>Enable the RDS encoder for a radio FM transmitter.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-modulator;
-<structfield>index</structfield> is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-output.xml b/Documentation/DocBook/media/v4l/vidioc-g-output.xml
deleted file mode 100644
index 4533068ecb8a..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-output.xml
+++ /dev/null
@@ -1,85 +0,0 @@
-<refentry id="vidioc-g-output">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_OUTPUT</refname>
- <refname>VIDIOC_S_OUTPUT</refname>
- <refpurpose>Query or select the current video output</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>int *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the current video output applications call the
-<constant>VIDIOC_G_OUTPUT</constant> ioctl with a pointer to an integer
-where the driver stores the number of the output, as in the
-&v4l2-output; <structfield>index</structfield> field. This ioctl
-will fail only when there are no video outputs, returning the
-&EINVAL;.</para>
-
- <para>To select a video output applications store the number of the
-desired output in an integer and call the
-<constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer.
-Side effects are possible. For example outputs may support different
-video standards, so the driver may implicitly switch the current
-standard.
-standard. Because of these possible side effects applications
-must select an output before querying or negotiating any other parameters.</para>
-
- <para>Information about video outputs is available using the
-&VIDIOC-ENUMOUTPUT; ioctl.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The number of the video output is out of bounds, or
-there are no video outputs at all.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml
deleted file mode 100644
index f4e28e7d4751..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml
+++ /dev/null
@@ -1,314 +0,0 @@
-<refentry id="vidioc-g-parm">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_PARM</refname>
- <refname>VIDIOC_S_PARM</refname>
- <refpurpose>Get or set streaming parameters</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>v4l2_streamparm *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_PARM, VIDIOC_S_PARM</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The current video standard determines a nominal number of
-frames per second. If less than this number of frames is to be
-captured or output, applications can request frame skipping or
-duplicating on the driver side. This is especially useful when using
-the <function>read()</function> or <function>write()</function>, which
-are not augmented by timestamps or sequence counters, and to avoid
-unnecessary data copying.</para>
-
- <para>Further these ioctls can be used to determine the number of
-buffers used internally by a driver in read/write mode. For
-implications see the section discussing the &func-read;
-function.</para>
-
- <para>To get and set the streaming parameters applications call
-the <constant>VIDIOC_G_PARM</constant> and
-<constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a
-pointer to a struct <structname>v4l2_streamparm</structname> which
-contains a union holding separate parameters for input and output
-devices.</para>
-
- <table pgwide="1" frame="none" id="v4l2-streamparm">
- <title>struct <structname>v4l2_streamparm</structname></title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry></entry>
- <entry>The buffer (stream) type, same as &v4l2-format;
-<structfield>type</structfield>, set by the application. See <xref
- linkend="v4l2-buf-type" /></entry>
- </row>
- <row>
- <entry>union</entry>
- <entry><structfield>parm</structfield></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-captureparm;</entry>
- <entry><structfield>capture</structfield></entry>
- <entry>Parameters for capture devices, used when
-<structfield>type</structfield> is
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>&v4l2-outputparm;</entry>
- <entry><structfield>output</structfield></entry>
- <entry>Parameters for output devices, used when
-<structfield>type</structfield> is
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u8</entry>
- <entry><structfield>raw_data</structfield>[200]</entry>
- <entry>A place holder for future extensions.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-captureparm">
- <title>struct <structname>v4l2_captureparm</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry>See <xref linkend="parm-caps" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capturemode</structfield></entry>
- <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>timeperframe</structfield></entry>
- <entry><para>This is the desired period between
-successive frames captured by the driver, in seconds. The
-field is intended to skip frames on the driver side, saving I/O
-bandwidth.</para><para>Applications store here the desired frame
-period, drivers return the actual frame period, which must be greater
-or equal to the nominal frame period determined by the current video
-standard (&v4l2-standard; <structfield>frameperiod</structfield>
-field). Changing the video standard (also implicitly by switching the
-video input) may reset this parameter to the nominal frame period. To
-reset manually applications can just set this field to
-zero.</para><para>Drivers support this function only when they set the
-<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
-<structfield>capability</structfield> field.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>extendedmode</structfield></entry>
- <entry>Custom (driver specific) streaming parameters. When
-unused, applications and drivers must set this field to zero.
-Applications using this field should check the driver name and
-version, see <xref linkend="querycap" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>readbuffers</structfield></entry>
- <entry>Applications set this field to the desired number
-of buffers used internally by the driver in &func-read; mode. Drivers
-return the actual number of buffers. When an application requests zero
-buffers, drivers should just return the current setting rather than
-the minimum or an error code. For details see <xref
- linkend="rw" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-outputparm">
- <title>struct <structname>v4l2_outputparm</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry>See <xref linkend="parm-caps" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>outputmode</structfield></entry>
- <entry>Set by drivers and applications, see <xref
- linkend="parm-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>timeperframe</structfield></entry>
- <entry>This is the desired period between
-successive frames output by the driver, in seconds.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>The field is intended to
-repeat frames on the driver side in &func-write; mode (in streaming
-mode timestamps can be used to throttle the output), saving I/O
-bandwidth.</para><para>Applications store here the desired frame
-period, drivers return the actual frame period, which must be greater
-or equal to the nominal frame period determined by the current video
-standard (&v4l2-standard; <structfield>frameperiod</structfield>
-field). Changing the video standard (also implicitly by switching the
-video output) may reset this parameter to the nominal frame period. To
-reset manually applications can just set this field to
-zero.</para><para>Drivers support this function only when they set the
-<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
-<structfield>capability</structfield> field.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>extendedmode</structfield></entry>
- <entry>Custom (driver specific) streaming parameters. When
-unused, applications and drivers must set this field to zero.
-Applications using this field should check the driver name and
-version, see <xref linkend="querycap" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>writebuffers</structfield></entry>
- <entry>Applications set this field to the desired number
-of buffers used internally by the driver in
-<function>write()</function> mode. Drivers return the actual number of
-buffers. When an application requests zero buffers, drivers should
-just return the current setting rather than the minimum or an error
-code. For details see <xref linkend="rw" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry>Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="parm-caps">
- <title>Streaming Parameters Capabilites</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry>
- <entry>0x1000</entry>
- <entry>The frame skipping/repeating controlled by the
-<structfield>timeperframe</structfield> field is supported.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="parm-flags">
- <title>Capture Parameters Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry>
- <entry>0x0001</entry>
- <entry><para>High quality imaging mode. High quality mode
-is intended for still imaging applications. The idea is to get the
-best possible image quality that the hardware can deliver. It is not
-defined how the driver writer may achieve that; it will depend on the
-hardware and the ingenuity of the driver writer. High quality mode is
-a different mode from the the regular motion video capture modes. In
-high quality mode:<itemizedlist>
- <listitem>
- <para>The driver may be able to capture higher
-resolutions than for motion capture.</para>
- </listitem>
- <listitem>
- <para>The driver may support fewer pixel formats
-than motion capture (eg; true color).</para>
- </listitem>
- <listitem>
- <para>The driver may capture and arithmetically
-combine multiple successive fields or frames to remove color edge
-artifacts and reduce the noise in the video data.
-</para>
- </listitem>
- <listitem>
- <para>The driver may capture images in slices like
-a scanner in order to handle larger format images than would otherwise
-be possible. </para>
- </listitem>
- <listitem>
- <para>An image capture operation may be
-significantly slower than motion capture. </para>
- </listitem>
- <listitem>
- <para>Moving objects in the image might have
-excessive motion blur. </para>
- </listitem>
- <listitem>
- <para>Capture might only work through the
-<function>read()</function> call.</para>
- </listitem>
- </itemizedlist></para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml b/Documentation/DocBook/media/v4l/vidioc-g-priority.xml
deleted file mode 100644
index 6a81b4fe9538..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml
+++ /dev/null
@@ -1,135 +0,0 @@
-<refentry id="vidioc-g-priority">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_PRIORITY</refname>
- <refname>VIDIOC_S_PRIORITY</refname>
- <refpurpose>Query or request the access priority associated with a
-file descriptor</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para>Pointer to an enum v4l2_priority type.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the current access priority
-applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl
-with a pointer to an enum v4l2_priority variable where the driver stores
-the current priority.</para>
-
- <para>To request an access priority applications store the
-desired priority in an enum v4l2_priority variable and call
-<constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this
-variable.</para>
-
- <table frame="none" pgwide="1" id="v4l2-priority">
- <title>enum v4l2_priority</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PRIORITY_UNSET</constant></entry>
- <entry>0</entry>
- <entry></entry>
- </row>
- <row>
- <entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry>
- <entry>1</entry>
- <entry>Lowest priority, usually applications running in
-background, for example monitoring VBI transmissions. A proxy
-application running in user space will be necessary if multiple
-applications want to read from a device at this priority.</entry>
- </row>
- <row>
- <entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry>
- <entry>2</entry>
- <entry></entry>
- </row>
- <row>
- <entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry>
- <entry>2</entry>
- <entry>Medium priority, usually applications started and
-interactively controlled by the user. For example TV viewers, Teletext
-browsers, or just "panel" applications to change the channel or video
-controls. This is the default priority unless an application requests
-another.</entry>
- </row>
- <row>
- <entry><constant>V4L2_PRIORITY_RECORD</constant></entry>
- <entry>3</entry>
- <entry>Highest priority. Only one file descriptor can have
-this priority, it blocks any other fd from changing device properties.
-Usually applications which must not be interrupted, like video
-recording.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The requested priority value is invalid.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>Another application already requested higher
-priority.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
deleted file mode 100644
index 0bb5c060db27..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml
+++ /dev/null
@@ -1,239 +0,0 @@
-<refentry id="vidioc-g-selection">
-
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_SELECTION</refname>
- <refname>VIDIOC_S_SELECTION</refname>
- <refpurpose>Get or set one of the selection rectangles</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_selection *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>The ioctls are used to query and configure selection rectangles.</para>
-
-<para>To query the cropping (composing) rectangle set &v4l2-selection;
-<structfield> type </structfield> field to the respective buffer type.
-Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
-instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and use
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
-setting the value of &v4l2-selection; <structfield>target</structfield> field
-to <constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>).
-Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" />
-for additional targets. The <structfield>flags</structfield> and <structfield>reserved
-</structfield> fields of &v4l2-selection; are ignored and they must be filled
-with zeros. The driver fills the rest of the structure or
-returns &EINVAL; if incorrect buffer type or target was used. If cropping
-(composing) is not supported then the active rectangle is not mutable and it is
-always equal to the bounds rectangle. Finally, the &v4l2-rect;
-<structfield>r</structfield> rectangle is filled with the current cropping
-(composing) coordinates. The coordinates are expressed in driver-dependent
-units. The only exception are rectangles for images in raw formats, whose
-coordinates are always expressed in pixels.</para>
-
-<para>To change the cropping (composing) rectangle set the &v4l2-selection;
-<structfield>type</structfield> field to the respective buffer type. Do not
-use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>
-instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is
-setting the value of &v4l2-selection; <structfield>target</structfield> to
-<constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>).
-Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" />
-for additional targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be
-set to the desired active area. Field &v4l2-selection; <structfield> reserved
-</structfield> is ignored and must be filled with zeros. The driver may adjust
-coordinates of the requested rectangle. An application may
-introduce constraints to control rounding behaviour. The &v4l2-selection;
-<structfield>flags</structfield> field must be set to one of the following:
-
-<itemizedlist>
- <listitem>
-<para><constant>0</constant> - The driver can adjust the rectangle size freely
-and shall choose a crop/compose rectangle as close as possible to the requested
-one.</para>
- </listitem>
- <listitem>
-<para><constant>V4L2_SEL_FLAG_GE</constant> - The driver is not allowed to
-shrink the rectangle. The original rectangle must lay inside the adjusted
-one.</para>
- </listitem>
- <listitem>
-<para><constant>V4L2_SEL_FLAG_LE</constant> - The driver is not allowed to
-enlarge the rectangle. The adjusted rectangle must lay inside the original
-one.</para>
- </listitem>
- <listitem>
-<para><constant>V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE</constant> - The driver
-must choose the size exactly the same as in the requested rectangle.</para>
- </listitem>
-</itemizedlist>
-
-Please refer to <xref linkend="sel-const-adjust" />.
-
-</para>
-
-<para> The driver may have to adjusts the requested dimensions against hardware
-limits and other parts as the pipeline, i.e. the bounds given by the
-capture/output window or TV display. The closest possible values of horizontal
-and vertical offset and sizes are chosen according to following priority:
-
-<orderedlist>
- <listitem>
- <para>Satisfy constraints from &v4l2-selection; <structfield>flags</structfield>.</para>
- </listitem>
- <listitem>
- <para>Adjust width, height, left, and top to hardware limits and alignments.</para>
- </listitem>
- <listitem>
- <para>Keep center of adjusted rectangle as close as possible to the original one.</para>
- </listitem>
- <listitem>
- <para>Keep width and height as close as possible to original ones.</para>
- </listitem>
- <listitem>
- <para>Keep horizontal and vertical offset as close as possible to original ones.</para>
- </listitem>
-</orderedlist>
-
-On success the &v4l2-rect; <structfield>r</structfield> field contains
-the adjusted rectangle. When the parameters are unsuitable the application may
-modify the cropping (composing) or image parameters and repeat the cycle until
-satisfactory parameters have been negotiated. If constraints flags have to be
-violated at then ERANGE is returned. The error indicates that <emphasis>there
-exist no rectangle</emphasis> that satisfies the constraints.</para>
-
- <para>Selection targets and flags are documented in <xref
- linkend="v4l2-selections-common"/>.</para>
-
- <para>
- <figure id="sel-const-adjust">
- <title>Size adjustments with constraint flags.</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="constraints.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>Behaviour of rectangle adjustment for different constraint
- flags.</phrase>
- </textobject>
- </mediaobject>
- </figure>
- </para>
-
- <para>
- <table pgwide="1" frame="none" id="v4l2-selection">
- <title>struct <structname>v4l2_selection</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the buffer (from &v4l2-buf-type;).</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>target</structfield></entry>
- <entry>Used to select between <link linkend="v4l2-selections-common"> cropping
- and composing rectangles</link>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags controlling the selection rectangle adjustments, refer to
- <link linkend="v4l2-selection-flags">selection flags</link>.</entry>
- </row>
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>r</structfield></entry>
- <entry>The selection rectangle.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved[9]</structfield></entry>
- <entry>Reserved fields for future use.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </refsect1>
-
- <refsect1>
- &return-value;
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>Given buffer type <structfield>type</structfield> or
-the selection target <structfield>target</structfield> is not supported,
-or the <structfield>flags</structfield> argument is not valid.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ERANGE</errorcode></term>
- <listitem>
- <para>It is not possible to adjust &v4l2-rect; <structfield>
-r</structfield> rectangle to satisfy all contraints given in the
-<structfield>flags</structfield> argument.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>It is not possible to apply change of the selection rectangle
-at the moment. Usually because streaming is in progress.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml b/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml
deleted file mode 100644
index d05623c55403..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml
+++ /dev/null
@@ -1,255 +0,0 @@
-<refentry id="vidioc-g-sliced-vbi-cap">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_SLICED_VBI_CAP</refname>
- <refpurpose>Query sliced VBI capabilities</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_SLICED_VBI_CAP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To find out which data services are supported by a sliced
-VBI capture or output device, applications initialize the
-<structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;,
-clear the <structfield>reserved</structfield> array and
-call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The
-driver fills in the remaining fields or returns an &EINVAL; if the
-sliced VBI API is unsupported or <structfield>type</structfield>
-is invalid.</para>
-
- <para>Note the <structfield>type</structfield> field was added,
-and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para>
-
- <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap">
- <title>struct <structname>v4l2_sliced_vbi_cap</structname></title>
- <tgroup cols="5">
- <colspec colname="c1" colwidth="3*" />
- <colspec colname="c2" colwidth="3*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="2*" />
- <colspec colname="c5" colwidth="2*" />
- <spanspec spanname="hspan" namest="c3" nameend="c5" />
- <tbody valign="top">
- <row>
- <entry>__u16</entry>
- <entry><structfield>service_set</structfield></entry>
- <entry spanname="hspan">A set of all data services
-supported by the driver. Equal to the union of all elements of the
-<structfield>service_lines </structfield> array.</entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>service_lines</structfield>[2][24]</entry>
- <entry spanname="hspan">Each element of this array
-contains a set of data services the hardware can look for or insert
-into a particular scan line. Data services are defined in <xref
- linkend="vbi-services" />. Array indices map to ITU-R
-line numbers (see also <xref
- linkend="vbi-525" /> and <xref
-linkend="vbi-625" />) as follows:</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Element</entry>
- <entry>525 line systems</entry>
- <entry>625 line systems</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[0][1]</entry>
- <entry align="center">1</entry>
- <entry align="center">1</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[0][23]</entry>
- <entry align="center">23</entry>
- <entry align="center">23</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[1][1]</entry>
- <entry align="center">264</entry>
- <entry align="center">314</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[1][23]</entry>
- <entry align="center">286</entry>
- <entry align="center">336</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry spanname="hspan">The number of VBI lines the
-hardware can capture or output per frame, or the number of services it
-can identify on a given line may be limited. For example on PAL line
-16 the hardware may be able to look for a VPS or Teletext signal, but
-not both at the same time. Applications can learn about these limits
-using the &VIDIOC-S-FMT; ioctl as described in <xref
- linkend="sliced" />.</entry>
- </row>
- <row>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry spanname="hspan">Drivers must set
-<structfield>service_lines</structfield>[0][0] and
-<structfield>service_lines</structfield>[1][0] to zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the data stream, see <xref
- linkend="v4l2-buf-type" />. Should be
-<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or
-<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[3]</entry>
- <entry spanname="hspan">This array is reserved for future
-extensions. Applications and drivers must set it to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- See also dev-sliced-vbi.sgml -->
- <table pgwide="1" frame="none" id="vbi-services">
- <title>Sliced VBI services</title>
- <tgroup cols="5">
- <colspec colname="c1" colwidth="2*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="1*" />
- <colspec colname="c4" colwidth="2*" />
- <colspec colname="c5" colwidth="2*" />
- <spanspec spanname='rlp' namest='c3' nameend='c5' />
- <thead>
- <row>
- <entry>Symbol</entry>
- <entry>Value</entry>
- <entry>Reference</entry>
- <entry>Lines, usually</entry>
- <entry>Payload</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext
-System B)</entry>
- <entry>0x0001</entry>
- <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
- <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
- <entry>Last 42 of the 45 byte Teletext packet, that is
-without clock run-in and framing code, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VPS</constant></entry>
- <entry>0x0400</entry>
- <entry><xref linkend="ets300231" /></entry>
- <entry>PAL line 16</entry>
- <entry>Byte number 3 to 15 according to Figure 9 of
-ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
- <entry>0x1000</entry>
- <entry><xref linkend="cea608" /></entry>
- <entry>NTSC line 21, 284 (second field 21)</entry>
- <entry>Two bytes in transmission order, including parity
-bit, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
- <entry>0x4000</entry>
- <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry>
- <entry>PAL/SECAM line 23</entry>
- <entry><screen>
-Byte 0 1
- msb lsb msb lsb
-Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
-</screen></entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
- <entry>0x1000</entry>
- <entry spanname="rlp">Set of services applicable to 525
-line systems.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
- <entry>0x4401</entry>
- <entry spanname="rlp">Set of services applicable to 625
-line systems.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The value in the <structfield>type</structfield> field is
-wrong.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-std.xml b/Documentation/DocBook/media/v4l/vidioc-g-std.xml
deleted file mode 100644
index 4a898417de28..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-std.xml
+++ /dev/null
@@ -1,98 +0,0 @@
-<refentry id="vidioc-g-std">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_STD, VIDIOC_S_STD</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_STD</refname>
- <refname>VIDIOC_S_STD</refname>
- <refpurpose>Query or select the video standard of the current input</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>v4l2_std_id
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const v4l2_std_id
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_STD, VIDIOC_S_STD</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query and select the current video standard applications
-use the <constant>VIDIOC_G_STD</constant> and <constant>VIDIOC_S_STD</constant> ioctls which take a pointer to a
-&v4l2-std-id; type as argument. <constant>VIDIOC_G_STD</constant> can
-return a single flag or a set of flags as in &v4l2-standard; field
-<structfield>id</structfield>. The flags must be unambiguous such
-that they appear in only one enumerated <structname>v4l2_standard</structname> structure.</para>
-
- <para><constant>VIDIOC_S_STD</constant> accepts one or more
-flags, being a write-only ioctl it does not return the actual new standard as
-<constant>VIDIOC_G_STD</constant> does. When no flags are given or
-the current input does not support the requested standard the driver
-returns an &EINVAL;. When the standard set is ambiguous drivers may
-return <errorcode>EINVAL</errorcode> or choose any of the requested
-standards. If the current input or output does not support standard video timings (e.g. if
-&VIDIOC-ENUMINPUT; does not set the <constant>V4L2_IN_CAP_STD</constant> flag), then
-&ENODATA; is returned.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <constant>VIDIOC_S_STD</constant> parameter was unsuitable.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>Standard video timings are not supported for this input or output.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml
deleted file mode 100644
index b0d865933da6..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml
+++ /dev/null
@@ -1,578 +0,0 @@
-<refentry id="vidioc-g-tuner">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_G_TUNER</refname>
- <refname>VIDIOC_S_TUNER</refname>
- <refpurpose>Get or set tuner attributes</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_tuner
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_tuner
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of a tuner applications initialize the
-<structfield>index</structfield> field and zero out the
-<structfield>reserved</structfield> array of a &v4l2-tuner; and call the
-<constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this
-structure. Drivers fill the rest of the structure or return an
-&EINVAL; when the index is out of bounds. To enumerate all tuners
-applications shall begin at index zero, incrementing by one until the
-driver returns <errorcode>EINVAL</errorcode>.</para>
-
- <para>Tuners have two writable properties, the audio mode and
-the radio frequency. To change the audio mode, applications initialize
-the <structfield>index</structfield>,
-<structfield>audmode</structfield> and
-<structfield>reserved</structfield> fields and call the
-<constant>VIDIOC_S_TUNER</constant> ioctl. This will
-<emphasis>not</emphasis> change the current tuner, which is determined
-by the current video input. Drivers may choose a different audio mode
-if the requested mode is invalid or unsupported. Since this is a
-<!-- FIXME -->write-only ioctl, it does not return the actually
-selected audio mode.</para>
-
- <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
-is available.</para>
-
- <table pgwide="1" frame="none" id="v4l2-tuner">
- <title>struct <structname>v4l2_tuner</structname></title>
- <tgroup cols="3">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="1*" />
- <colspec colname="c4" colwidth="1*" />
- <spanspec spanname="hspan" namest="c3" nameend="c4" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry spanname="hspan">Identifies the tuner, set by the
-application.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry spanname="hspan"><para>Name of the tuner, a
-NUL-terminated ASCII string. This information is intended for the
-user.<!-- FIXME Video inputs already have a name, the purpose of this
-field is not quite clear.--></para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry spanname="hspan">Type of the tuner, see <xref
- linkend="v4l2-tuner-type" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capability</structfield></entry>
- <entry spanname="hspan"><para>Tuner capability flags, see
-<xref linkend="tuner-capability" />. Audio flags indicate the ability
-to decode audio subprograms. They will <emphasis>not</emphasis>
-change, for example with the current video standard.</para><para>When
-the structure refers to a radio tuner the
-<constant>V4L2_TUNER_CAP_LANG1</constant>,
-<constant>V4L2_TUNER_CAP_LANG2</constant> and
-<constant>V4L2_TUNER_CAP_NORM</constant> flags can't be used.</para>
-<para>If multiple frequency bands are supported, then
-<structfield>capability</structfield> is the union of all
-<structfield>capability</structfield> fields of each &v4l2-frequency-band;.
-</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangelow</structfield></entry>
- <entry spanname="hspan">The lowest tunable frequency in
-units of 62.5 kHz, or if the <structfield>capability</structfield>
-flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz, or if the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.
-If multiple frequency bands are supported, then
-<structfield>rangelow</structfield> is the lowest frequency
-of all the frequency bands.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangehigh</structfield></entry>
- <entry spanname="hspan">The highest tunable frequency in
-units of 62.5 kHz, or if the <structfield>capability</structfield>
-flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
-Hz, or if the <structfield>capability</structfield> flag
-<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.
-If multiple frequency bands are supported, then
-<structfield>rangehigh</structfield> is the highest frequency
-of all the frequency bands.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rxsubchans</structfield></entry>
- <entry spanname="hspan"><para>Some tuners or audio
-decoders can determine the received audio subprograms by analyzing
-audio carriers, pilot tones or other indicators. To pass this
-information drivers set flags defined in <xref
- linkend="tuner-rxsubchans" /> in this field. For
-example:</para></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
- <entry>receiving mono audio</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><constant>STEREO | SAP</constant></entry>
- <entry>receiving stereo audio and a secondary audio
-program</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><constant>MONO | STEREO</constant></entry>
- <entry>receiving mono or stereo audio, the hardware cannot
-distinguish</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><constant>LANG1 | LANG2</constant></entry>
- <entry>receiving bilingual audio</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry>
- <entry>receiving mono, stereo or bilingual
-audio</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry spanname="hspan"><para>When the
-<constant>V4L2_TUNER_CAP_STEREO</constant>,
-<constant>_LANG1</constant>, <constant>_LANG2</constant> or
-<constant>_SAP</constant> flag is cleared in the
-<structfield>capability</structfield> field, the corresponding
-<constant>V4L2_TUNER_SUB_</constant> flag must not be set
-here.</para><para>This field is valid only if this is the tuner of the
-current video input, or when the structure refers to a radio
-tuner.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>audmode</structfield></entry>
- <entry spanname="hspan"><para>The selected audio mode, see
-<xref linkend="tuner-audmode" /> for valid values. The audio mode does
-not affect audio subprogram detection, and like a <link
-linkend="control">control</link> it does not automatically change
-unless the requested mode is invalid or unsupported. See <xref
- linkend="tuner-matrix" /> for possible results when
-the selected and received audio programs do not
-match.</para><para>Currently this is the only field of struct
-<structname>v4l2_tuner</structname> applications can
-change.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>signal</structfield></entry>
- <entry spanname="hspan">The signal strength if known, ranging
-from 0 to 65535. Higher values indicate a better signal.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>afc</structfield></entry>
- <entry spanname="hspan">Automatic frequency control: When the
-<structfield>afc</structfield> value is negative, the frequency is too
-low, when positive too high.<!-- FIXME need example what to do when it never
-settles at zero, &ie; range is what? --></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[4]</entry>
- <entry spanname="hspan">Reserved for future extensions. Drivers and
-applications must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-tuner-type">
- <title>enum v4l2_tuner_type</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TUNER_RADIO</constant></entry>
- <entry>1</entry>
- <entry></entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry>
- <entry>2</entry>
- <entry></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="tuner-capability">
- <title>Tuner and Modulator Capability Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry>
- <entry>0x0001</entry>
- <entry>When set, tuning frequencies are expressed in units of
-62.5 Hz instead of 62.5 kHz.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry>
- <entry>0x0002</entry>
- <entry>This is a multi-standard tuner; the video standard
-can or must be switched. (B/G PAL tuners for example are typically not
- considered multi-standard because the video standard is automatically
- determined from the frequency band.) The set of supported video
- standards is available from the &v4l2-input; pointing to this tuner,
- see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only
- <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_HWSEEK_BOUNDED</constant></entry>
- <entry>0x0004</entry>
- <entry>If set, then this tuner supports the hardware seek functionality
- where the seek stops when it reaches the end of the frequency range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_HWSEEK_WRAP</constant></entry>
- <entry>0x0008</entry>
- <entry>If set, then this tuner supports the hardware seek functionality
- where the seek wraps around when it reaches the end of the frequency range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry>
- <entry>0x0010</entry>
- <entry>Stereo audio reception is supported.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry>
- <entry>0x0040</entry>
- <entry>Reception of the primary language of a bilingual
-audio program is supported. Bilingual audio is a feature of
-two-channel systems, transmitting the primary language monaural on the
-main audio carrier and a secondary language monaural on a second
-carrier. Only
- <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry>
- <entry>0x0020</entry>
- <entry>Reception of the secondary language of a bilingual
-audio program is supported. Only
- <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry>
- <entry>0x0020</entry>
- <entry><para>Reception of a secondary audio program is
-supported. This is a feature of the BTSC system which accompanies the
-NTSC video standard. Two audio carriers are available for mono or
-stereo transmissions of a primary language, and an independent third
-carrier for a monaural secondary language. Only
- <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the
-<constant>V4L2_TUNER_CAP_LANG2</constant> and
-<constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms.
-<constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner
-supports the <constant>V4L2_STD_NTSC_M</constant> video
-standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry>
- <entry>0x0080</entry>
- <entry>RDS capture is supported. This capability is only valid for
-radio tuners.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant></entry>
- <entry>0x0100</entry>
- <entry>The RDS data is passed as unparsed RDS blocks.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant></entry>
- <entry>0x0200</entry>
- <entry>The RDS data is parsed by the hardware and set via controls.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_FREQ_BANDS</constant></entry>
- <entry>0x0400</entry>
- <entry>The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate
- the available frequency bands.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant></entry>
- <entry>0x0800</entry>
- <entry>The range to search when using the hardware seek functionality
- is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_CAP_1HZ</constant></entry>
- <entry>0x1000</entry>
- <entry>When set, tuning frequencies are expressed in units of 1 Hz instead of 62.5 kHz.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="tuner-rxsubchans">
- <title>Tuner Audio Reception Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
- <entry>0x0001</entry>
- <entry>The tuner receives a mono audio signal.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
- <entry>0x0002</entry>
- <entry>The tuner receives a stereo audio signal.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
- <entry>0x0008</entry>
- <entry>The tuner receives the primary language of a
-bilingual audio signal. Drivers must clear this flag when the current
-video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
- <entry>0x0004</entry>
- <entry>The tuner receives the secondary language of a
-bilingual audio signal (or a second audio program).</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
- <entry>0x0004</entry>
- <entry>The tuner receives a Second Audio Program. Note the
-<constant>V4L2_TUNER_SUB_LANG2</constant> and
-<constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The
-<constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
-current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
- <entry>0x0010</entry>
- <entry>The tuner receives an RDS channel.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="tuner-audmode">
- <title>Tuner Audio Modes</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry>
- <entry>0</entry>
- <entry>Play mono audio. When the tuner receives a stereo
-signal this a down-mix of the left and right channel. When the tuner
-receives a bilingual or SAP signal this mode selects the primary
-language.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry>
- <entry>1</entry>
- <entry><para>Play stereo audio. When the tuner receives
-bilingual audio it may play different languages on the left and right
-channel or the primary language is played on both channels.</para><para>Playing
-different languages in this mode is
-deprecated. New drivers should do this only in
-<constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
-receives no stereo signal or does not support stereo reception the
-driver shall fall back to <constant>MODE_MONO</constant>.</para></entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry>
- <entry>3</entry>
- <entry>Play the primary language, mono or stereo. Only
-<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
-mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry>
- <entry>2</entry>
- <entry>Play the secondary language, mono. When the tuner
-receives no bilingual audio or SAP, or their reception is not
-supported the driver shall fall back to mono or stereo mode. Only
-<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
-mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry>
- <entry>2</entry>
- <entry>Play the Second Audio Program. When the tuner
-receives no bilingual audio or SAP, or their reception is not
-supported the driver shall fall back to mono or stereo mode. Only
-<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
-Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and
-<constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry>
- </row>
- <row>
- <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry>
- <entry>4</entry>
- <entry>Play the primary language on the left channel, the
-secondary language on the right channel. When the tuner receives no
-bilingual audio or SAP, it shall fall back to
-<constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
-Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
-mode.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="all" id="tuner-matrix">
- <title>Tuner Audio Matrix</title>
- <tgroup cols="6" align="center">
- <colspec align="left" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colwidth="1*" />
- <colspec colwidth="1*" />
- <colspec colnum="6" colname="c6" colwidth="1*" />
- <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" />
- <thead>
- <row>
- <entry></entry>
- <entry spanname="hspan">Selected
-<constant>V4L2_TUNER_MODE_</constant></entry>
- </row>
- <row>
- <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry>
- <entry><constant>MONO</constant></entry>
- <entry><constant>STEREO</constant></entry>
- <entry><constant>LANG1</constant></entry>
- <entry><constant>LANG2 = SAP</constant></entry>
- <entry><constant>LANG1_LANG2</constant><footnote><para>This
-mode has been added in Linux 2.6.17 and may not be supported by older
-drivers.</para></footnote></entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>MONO</constant></entry>
- <entry>Mono</entry>
- <entry>Mono/Mono</entry>
- <entry>Mono</entry>
- <entry>Mono</entry>
- <entry>Mono/Mono</entry>
- </row>
- <row>
- <entry><constant>MONO | SAP</constant></entry>
- <entry>Mono</entry>
- <entry>Mono/Mono</entry>
- <entry>Mono</entry>
- <entry>SAP</entry>
- <entry>Mono/SAP (preferred) or Mono/Mono</entry>
- </row>
- <row>
- <entry><constant>STEREO</constant></entry>
- <entry>L+R</entry>
- <entry>L/R</entry>
- <entry>Stereo L/R (preferred) or Mono L+R</entry>
- <entry>Stereo L/R (preferred) or Mono L+R</entry>
- <entry>L/R (preferred) or L+R/L+R</entry>
- </row>
- <row>
- <entry><constant>STEREO | SAP</constant></entry>
- <entry>L+R</entry>
- <entry>L/R</entry>
- <entry>Stereo L/R (preferred) or Mono L+R</entry>
- <entry>SAP</entry>
- <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry>
- </row>
- <row>
- <entry><constant>LANG1 | LANG2</constant></entry>
- <entry>Language&nbsp;1</entry>
- <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
-both languages in <constant>MODE_STEREO</constant> is deprecated. In
-the future drivers should produce only the primary language in this
-mode. Applications should request
-<constant>MODE_LANG1_LANG2</constant> to record both languages or a
-stereo signal.</para></footnote>) or
-Lang1/Lang1</entry>
- <entry>Language&nbsp;1</entry>
- <entry>Language&nbsp;2</entry>
- <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-tuner; <structfield>index</structfield> is
-out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-log-status.xml b/Documentation/DocBook/media/v4l/vidioc-log-status.xml
deleted file mode 100644
index 5ded7d35e27b..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-log-status.xml
+++ /dev/null
@@ -1,41 +0,0 @@
-<refentry id="vidioc-log-status">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_LOG_STATUS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_LOG_STATUS</refname>
- <refpurpose>Log driver status information</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>As the video/audio devices become more complicated it
-becomes harder to debug problems. When this ioctl is called the driver
-will output the current device status to the kernel log. This is
-particular useful when dealing with problems like no sound, no video
-and incorrectly tuned channels. Also many modern devices autodetect
-video and audio standards and this ioctl will report what the device
-thinks what the standard is. Mismatches may give an indication where
-the problem is.</para>
-
- <para>This ioctl is optional and not all drivers support it. It
-was introduced in Linux 2.6.15.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-overlay.xml b/Documentation/DocBook/media/v4l/vidioc-overlay.xml
deleted file mode 100644
index 250a7de1877f..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-overlay.xml
+++ /dev/null
@@ -1,74 +0,0 @@
-<refentry id="vidioc-overlay">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_OVERLAY</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_OVERLAY</refname>
- <refpurpose>Start or stop video overlay</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const int *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_OVERLAY</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>This ioctl is part of the <link linkend="overlay">video
- overlay</link> I/O method. Applications call
- <constant>VIDIOC_OVERLAY</constant> to start or stop the
- overlay. It takes a pointer to an integer which must be set to
- zero by the application to stop overlay, to one to start.</para>
-
- <para>Drivers do not support &VIDIOC-STREAMON; or
-&VIDIOC-STREAMOFF; with <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The overlay parameters have not been set up. See <xref
-linkend="overlay" /> for the necessary steps.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml
deleted file mode 100644
index fa7ad7e33228..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml
+++ /dev/null
@@ -1,94 +0,0 @@
-<refentry id="vidioc-prepare-buf">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_PREPARE_BUF</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_PREPARE_BUF</refname>
- <refpurpose>Prepare a buffer for I/O</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_PREPARE_BUF</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>Applications can optionally call the
-<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer
-to the driver before actually enqueuing it, using the
-<constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O.
-Such preparations may include cache invalidation or cleaning. Performing them
-in advance saves time during the actual I/O. In case such cache operations are
-not required, the application can use one of
-<constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and
-<constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective
-step.</para>
-
- <para>The <structname>v4l2_buffer</structname> structure is
-specified in <xref linkend="buffer" />.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>File I/O is in progress.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The buffer <structfield>type</structfield> is not
-supported, or the <structfield>index</structfield> is out of bounds,
-or no buffers have been allocated yet, or the
-<structfield>userptr</structfield> or
-<structfield>length</structfield> are invalid.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
deleted file mode 100644
index 3504a7f2f382..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
+++ /dev/null
@@ -1,192 +0,0 @@
-<refentry id="vidioc-qbuf">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_QBUF</refname>
- <refname>VIDIOC_DQBUF</refname>
- <refpurpose>Exchange a buffer with the driver</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_QBUF, VIDIOC_DQBUF</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Applications call the <constant>VIDIOC_QBUF</constant> ioctl
-to enqueue an empty (capturing) or filled (output) buffer in the
-driver's incoming queue. The semantics depend on the selected I/O
-method.</para>
-
- <para>To enqueue a buffer applications set the <structfield>type</structfield>
-field of a &v4l2-buffer; to the same buffer type as was previously used
-with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
-<structfield>type</structfield>. Applications must also set the
-<structfield>index</structfield> field. Valid index numbers range from
-zero to the number of buffers allocated with &VIDIOC-REQBUFS;
-(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
-contents of the struct <structname>v4l2_buffer</structname> returned
-by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
-intended for output (<structfield>type</structfield> is
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
-<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
-initialize the <structfield>bytesused</structfield>,
-<structfield>field</structfield> and
-<structfield>timestamp</structfield> fields, see <xref
-linkend="buffer" /> for details.
-Applications must also set <structfield>flags</structfield> to 0.
-The <structfield>reserved2</structfield> and
-<structfield>reserved</structfield> fields must be set to 0. When using
-the <link linkend="planar-apis">multi-planar API</link>, the
-<structfield>m.planes</structfield> field must contain a userspace pointer
-to a filled-in array of &v4l2-plane; and the <structfield>length</structfield>
-field must be set to the number of elements in that array.
-</para>
-
- <para>To enqueue a <link linkend="mmap">memory mapped</link>
-buffer applications set the <structfield>memory</structfield>
-field to <constant>V4L2_MEMORY_MMAP</constant>. When
-<constant>VIDIOC_QBUF</constant> is called with a pointer to this
-structure the driver sets the
-<constant>V4L2_BUF_FLAG_MAPPED</constant> and
-<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
-<constant>V4L2_BUF_FLAG_DONE</constant> flag in the
-<structfield>flags</structfield> field, or it returns an
-&EINVAL;.</para>
-
- <para>To enqueue a <link linkend="userp">user pointer</link>
-buffer applications set the <structfield>memory</structfield>
-field to <constant>V4L2_MEMORY_USERPTR</constant>, the
-<structfield>m.userptr</structfield> field to the address of the
-buffer and <structfield>length</structfield> to its size. When the multi-planar
-API is used, <structfield>m.userptr</structfield> and
-<structfield>length</structfield> members of the passed array of &v4l2-plane;
-have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with
-a pointer to this structure the driver sets the
-<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
-<constant>V4L2_BUF_FLAG_MAPPED</constant> and
-<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
-<structfield>flags</structfield> field, or it returns an error code.
-This ioctl locks the memory pages of the buffer in physical memory,
-they cannot be swapped out to disk. Buffers remain locked until
-dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
-called, or until the device is closed.</para>
-
- <para>To enqueue a <link linkend="dmabuf">DMABUF</link> buffer applications
-set the <structfield>memory</structfield> field to
-<constant>V4L2_MEMORY_DMABUF</constant> and the <structfield>m.fd</structfield>
-field to a file descriptor associated with a DMABUF buffer. When the
-multi-planar API is used the <structfield>m.fd</structfield> fields of the
-passed array of &v4l2-plane; have to be used instead. When
-<constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the
-driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
-<constant>V4L2_BUF_FLAG_MAPPED</constant> and
-<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
-<structfield>flags</structfield> field, or it returns an error code. This
-ioctl locks the buffer. Locking a buffer means passing it to a driver for a
-hardware access (usually DMA). If an application accesses (reads/writes) a
-locked buffer then the result is undefined. Buffers remain locked until
-dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or
-until the device is closed.</para>
-
- <para>Applications call the <constant>VIDIOC_DQBUF</constant>
-ioctl to dequeue a filled (capturing) or displayed (output) buffer
-from the driver's outgoing queue. They just set the
-<structfield>type</structfield>, <structfield>memory</structfield>
-and <structfield>reserved</structfield>
-fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
-is called with a pointer to this structure the driver fills the
-remaining fields or returns an error code. The driver may also set
-<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
-field. It indicates a non-critical (recoverable) streaming error. In such case
-the application may continue as normal, but should be aware that data in the
-dequeued buffer might be corrupted. When using the multi-planar API, the
-planes array must be passed in as well.</para>
-
- <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
-buffer is in the outgoing queue. When the
-<constant>O_NONBLOCK</constant> flag was given to the &func-open;
-function, <constant>VIDIOC_DQBUF</constant> returns immediately
-with an &EAGAIN; when no buffer is available.</para>
-
- <para>The <structname>v4l2_buffer</structname> structure is
-specified in <xref linkend="buffer" />.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EAGAIN</errorcode></term>
- <listitem>
- <para>Non-blocking I/O has been selected using
-<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
-queue.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The buffer <structfield>type</structfield> is not
-supported, or the <structfield>index</structfield> is out of bounds,
-or no buffers have been allocated yet, or the
-<structfield>userptr</structfield> or
-<structfield>length</structfield> are invalid.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EIO</errorcode></term>
- <listitem>
- <para><constant>VIDIOC_DQBUF</constant> failed due to an
-internal error. Can also indicate temporary problems like signal
-loss. Note the driver might dequeue an (empty) buffer despite
-returning an error, or even stop capturing. Reusing such buffer may be unsafe
-though and its details (e.g. <structfield>index</structfield>) may not be
-returned either. It is recommended that drivers indicate recoverable errors
-by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
-In that case the application should be able to safely reuse the buffer and
-continue streaming.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
deleted file mode 100644
index e185f149e0a1..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
+++ /dev/null
@@ -1,110 +0,0 @@
-<refentry id="vidioc-query-dv-timings">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_QUERY_DV_TIMINGS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_QUERY_DV_TIMINGS</refname>
- <refpurpose>Sense the DV preset received by the current
-input</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_QUERY_DV_TIMINGS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental"> experimental </link>
- interface and may change in the future.</para>
- </note>
-
- <para>The hardware may be able to detect the current DV timings
-automatically, similar to sensing the video standard. To do so, applications
-call <constant>VIDIOC_QUERY_DV_TIMINGS</constant> with a pointer to a
-&v4l2-dv-timings;. Once the hardware detects the timings, it will fill in the
-timings structure.
-
-If the timings could not be detected because there was no signal, then
-<errorcode>ENOLINK</errorcode> is returned. If a signal was detected, but
-it was unstable and the receiver could not lock to the signal, then
-<errorcode>ENOLCK</errorcode> is returned. If the receiver could lock to the signal,
-but the format is unsupported (e.g. because the pixelclock is out of range
-of the hardware capabilities), then the driver fills in whatever timings it
-could find and returns <errorcode>ERANGE</errorcode>. In that case the application
-can call &VIDIOC-DV-TIMINGS-CAP; to compare the found timings with the hardware's
-capabilities in order to give more precise feedback to the user.
-</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>Digital video timings are not supported for this input or output.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOLINK</errorcode></term>
- <listitem>
- <para>No timings could be detected because no signal was found.
-</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOLCK</errorcode></term>
- <listitem>
- <para>The signal was unstable and the hardware could not lock on to it.
-</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ERANGE</errorcode></term>
- <listitem>
- <para>Timings were found, but they are out of range of the hardware
-capabilities.
-</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
deleted file mode 100644
index a597155c052d..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
+++ /dev/null
@@ -1,105 +0,0 @@
-<refentry id="vidioc-querybuf">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_QUERYBUF</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_QUERYBUF</refname>
- <refpurpose>Query the status of a buffer</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_QUERYBUF</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>This ioctl is part of the <link linkend="mmap">streaming
-</link> I/O method. It can be used to query the status of a
-buffer at any time after buffers have been allocated with the
-&VIDIOC-REQBUFS; ioctl.</para>
-
- <para>Applications set the <structfield>type</structfield> field
- of a &v4l2-buffer; to the same buffer type as was previously used with
-&v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
-<structfield>type</structfield>, and the <structfield>index</structfield>
- field. Valid index numbers range from zero
-to the number of buffers allocated with &VIDIOC-REQBUFS;
- (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
-The <structfield>reserved</structfield> field should to set to 0.
-When using the <link linkend="planar-apis">multi-planar API</link>, the
-<structfield>m.planes</structfield> field must contain a userspace pointer to an
-array of &v4l2-plane; and the <structfield>length</structfield> field has
-to be set to the number of elements in that array.
-After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
- this structure drivers return an error code or fill the rest of
-the structure.</para>
-
- <para>In the <structfield>flags</structfield> field the
-<constant>V4L2_BUF_FLAG_MAPPED</constant>,
-<constant>V4L2_BUF_FLAG_PREPARED</constant>,
-<constant>V4L2_BUF_FLAG_QUEUED</constant> and
-<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
-<structfield>memory</structfield> field will be set to the current
-I/O method. For the single-planar API, the <structfield>m.offset</structfield>
-contains the offset of the buffer from the start of the device memory,
-the <structfield>length</structfield> field its size. For the multi-planar API,
-fields <structfield>m.mem_offset</structfield> and
-<structfield>length</structfield> in the <structfield>m.planes</structfield>
-array elements will be used instead and the <structfield>length</structfield>
-field of &v4l2-buffer; is set to the number of filled-in array elements.
-The driver may or may not set the remaining fields and flags, they are
-meaningless in this context.</para>
-
- <para>The <structname>v4l2_buffer</structname> structure is
- specified in <xref linkend="buffer" />.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The buffer <structfield>type</structfield> is not
-supported, or the <structfield>index</structfield> is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml
deleted file mode 100644
index 20fda75a012d..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml
+++ /dev/null
@@ -1,344 +0,0 @@
-<refentry id="vidioc-querycap">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_QUERYCAP</refname>
- <refpurpose>Query device capabilities</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_capability *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_QUERYCAP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>All V4L2 devices support the
-<constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify
-kernel devices compatible with this specification and to obtain
-information about driver and hardware capabilities. The ioctl takes a
-pointer to a &v4l2-capability; which is filled by the driver. When the
-driver is not compatible with this specification the ioctl returns an
-&EINVAL;.</para>
-
- <table pgwide="1" frame="none" id="v4l2-capability">
- <title>struct <structname>v4l2_capability</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>driver</structfield>[16]</entry>
- <entry><para>Name of the driver, a unique NUL-terminated
-ASCII string. For example: "bttv". Driver specific applications can
-use this information to verify the driver identity. It is also useful
-to work around known bugs, or to identify drivers in error reports.</para>
-<para>Storing strings in fixed sized arrays is bad
-practice but unavoidable here. Drivers and applications should take
-precautions to never read or write beyond the end of the array and to
-make sure the strings are properly NUL-terminated.</para></entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>card</structfield>[32]</entry>
- <entry>Name of the device, a NUL-terminated UTF-8 string.
-For example: "Yoyodyne TV/FM". One driver may support different brands
-or models of video hardware. This information is intended for users,
-for example in a menu of available devices. Since multiple TV cards of
-the same brand may be installed which are supported by the same
-driver, this name should be combined with the character device file
-name (&eg; <filename>/dev/video2</filename>) or the
-<structfield>bus_info</structfield> string to avoid
-ambiguities.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>bus_info</structfield>[32]</entry>
- <entry>Location of the device in the system, a
-NUL-terminated ASCII string. For example: "PCI:0000:05:06.0". This
-information is intended for users, to distinguish multiple
-identical devices. If no such information is available the field must
-simply count the devices controlled by the driver ("platform:vivi-000").
-The bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI Express boards,
-"usb-" for USB devices, "I2C:" for i2c devices, "ISA:" for ISA devices,
-"parport" for parallel port devices and "platform:" for platform devices.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>version</structfield></entry>
- <entry><para>Version number of the driver.</para>
-<para>Starting with kernel 3.1, the version reported is provided by the
-V4L2 subsystem following the kernel numbering scheme. However, it
-may not always return the same version as the kernel if, for example,
-a stable or distribution-modified kernel uses the V4L2 stack from a
-newer kernel.</para>
-<para>The version number is formatted using the
-<constant>KERNEL_VERSION()</constant> macro:</para></entry>
- </row>
- <row>
- <entry spanname="hspan"><para>
-<programlisting>
-#define KERNEL_VERSION(a,b,c) (((a) &lt;&lt; 16) + ((b) &lt;&lt; 8) + (c))
-
-__u32 version = KERNEL_VERSION(0, 8, 1);
-
-printf ("Version: %u.%u.%u\n",
- (version &gt;&gt; 16) &amp; 0xFF,
- (version &gt;&gt; 8) &amp; 0xFF,
- version &amp; 0xFF);
-</programlisting></para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>capabilities</structfield></entry>
- <entry>Available capabilities of the physical device as a whole, see <xref
- linkend="device-capabilities" />. The same physical device can export
- multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and /dev/radioZ).
- The <structfield>capabilities</structfield> field should contain a union
- of all capabilities available around the several V4L2 devices exported
- to userspace.
- For all those devices the <structfield>capabilities</structfield> field
- returns the same set of capabilities. This allows applications to open
- just one of the devices (typically the video device) and discover whether
- video, vbi and/or radio are also supported.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>device_caps</structfield></entry>
- <entry>Device capabilities of the opened device, see <xref
- linkend="device-capabilities" />. Should contain the available capabilities
- of that specific device node. So, for example, <structfield>device_caps</structfield>
- of a radio device will only contain radio related capabilities and
- no video or vbi capabilities. This field is only set if the <structfield>capabilities</structfield>
- field contains the <constant>V4L2_CAP_DEVICE_CAPS</constant> capability.
- Only the <structfield>capabilities</structfield> field can have the
- <constant>V4L2_CAP_DEVICE_CAPS</constant> capability, <structfield>device_caps</structfield>
- will never set <constant>V4L2_CAP_DEVICE_CAPS</constant>.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[3]</entry>
- <entry>Reserved for future extensions. Drivers must set
-this array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="device-capabilities">
- <title>Device Capabilities Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
- <entry>0x00000001</entry>
- <entry>The device supports the single-planar API through the <link
-linkend="capture">Video Capture</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry>
- <entry>0x00001000</entry>
- <entry>The device supports the
- <link linkend="planar-apis">multi-planar API</link> through the
- <link linkend="capture">Video Capture</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
- <entry>0x00000002</entry>
- <entry>The device supports the single-planar API through the <link
-linkend="output">Video Output</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry>
- <entry>0x00002000</entry>
- <entry>The device supports the
- <link linkend="planar-apis">multi-planar API</link> through the
- <link linkend="output">Video Output</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_M2M</constant></entry>
- <entry>0x00004000</entry>
- <entry>The device supports the single-planar API through the
- Video Memory-To-Memory interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant></entry>
- <entry>0x00008000</entry>
- <entry>The device supports the
- <link linkend="planar-apis">multi-planar API</link> through the
- Video Memory-To-Memory interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
- <entry>0x00000004</entry>
- <entry>The device supports the <link
-linkend="overlay">Video Overlay</link> interface. A video overlay device
-typically stores captured images directly in the video memory of a
-graphics card, with hardware clipping and scaling.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
- <entry>0x00000010</entry>
- <entry>The device supports the <link linkend="raw-vbi">Raw
-VBI Capture</link> interface, providing Teletext and Closed Caption
-data.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry>
- <entry>0x00000020</entry>
- <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry>
- <entry>0x00000040</entry>
- <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry>
- <entry>0x00000080</entry>
- <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry>
- <entry>0x00000100</entry>
- <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry>
- <entry>0x00000200</entry>
- <entry>The device supports the <link linkend="osd">Video
-Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video
-Overlay</wordasword> interface, this is a secondary function of video
-output devices and overlays an image onto an outgoing video signal.
-When the driver sets this flag, it must clear the
-<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice
-versa.<footnote><para>The &v4l2-framebuffer; lacks an
-&v4l2-buf-type; field, therefore the type of overlay is implied by the
-driver capabilities.</para></footnote></entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry>
- <entry>0x00000400</entry>
- <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for
-hardware frequency seeking.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry>
- <entry>0x00000800</entry>
- <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_TUNER</constant></entry>
- <entry>0x00010000</entry>
- <entry>The device has some sort of tuner to
-receive RF-modulated video signals. For more information about
-tuner programming see
-<xref linkend="tuner" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_AUDIO</constant></entry>
- <entry>0x00020000</entry>
- <entry>The device has audio inputs or outputs. It may or
-may not support audio recording or playback, in PCM or compressed
-formats. PCM audio support must be implemented as ALSA or OSS
-interface. For more information on audio inputs and outputs see <xref
- linkend="audio" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_RADIO</constant></entry>
- <entry>0x00040000</entry>
- <entry>This is a radio receiver.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_MODULATOR</constant></entry>
- <entry>0x00080000</entry>
- <entry>The device has some sort of modulator to
-emit RF-modulated video/audio signals. For more information about
-modulator programming see
-<xref linkend="tuner" />.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_SDR_CAPTURE</constant></entry>
- <entry>0x00100000</entry>
- <entry>The device supports the
-<link linkend="sdr">SDR Capture</link> interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry>
- <entry>0x00200000</entry>
- <entry>The device supports the &v4l2-pix-format; extended
-fields.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_READWRITE</constant></entry>
- <entry>0x01000000</entry>
- <entry>The device supports the <link
-linkend="rw">read()</link> and/or <link linkend="rw">write()</link>
-I/O methods.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_ASYNCIO</constant></entry>
- <entry>0x02000000</entry>
- <entry>The device supports the <link
-linkend="async">asynchronous</link> I/O methods.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_STREAMING</constant></entry>
- <entry>0x04000000</entry>
- <entry>The device supports the <link
-linkend="mmap">streaming</link> I/O method.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CAP_DEVICE_CAPS</constant></entry>
- <entry>0x80000000</entry>
- <entry>The driver fills the <structfield>device_caps</structfield>
- field. This capability can only appear in the <structfield>capabilities</structfield>
- field and never in the <structfield>device_caps</structfield> field.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
deleted file mode 100644
index dc83ad70f8dc..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
+++ /dev/null
@@ -1,650 +0,0 @@
-<refentry id="vidioc-queryctrl">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_QUERYCTRL</refname>
- <refname>VIDIOC_QUERY_EXT_CTRL</refname>
- <refname>VIDIOC_QUERYMENU</refname>
- <refpurpose>Enumerate controls and menu control items</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>To query the attributes of a control applications set the
-<structfield>id</structfield> field of a &v4l2-queryctrl; and call the
-<constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this
-structure. The driver fills the rest of the structure or returns an
-&EINVAL; when the <structfield>id</structfield> is invalid.</para>
-
- <para>It is possible to enumerate controls by calling
-<constant>VIDIOC_QUERYCTRL</constant> with successive
-<structfield>id</structfield> values starting from
-<constant>V4L2_CID_BASE</constant> up to and exclusive
-<constant>V4L2_CID_LASTP1</constant>. Drivers may return
-<errorcode>EINVAL</errorcode> if a control in this range is not
-supported. Further applications can enumerate private controls, which
-are not defined in this specification, by starting at
-<constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing
-<structfield>id</structfield> until the driver returns
-<errorcode>EINVAL</errorcode>.</para>
-
- <para>In both cases, when the driver sets the
-<constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the
-<structfield>flags</structfield> field this control is permanently
-disabled and should be ignored by the application.<footnote>
- <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was
-intended for two purposes: Drivers can skip predefined controls not
-supported by the hardware (although returning EINVAL would do as
-well), or disable predefined and private controls after hardware
-detection without the trouble of reordering control arrays and indices
-(EINVAL cannot be used to skip private controls because it would
-prematurely end the enumeration).</para></footnote></para>
-
- <para>When the application ORs <structfield>id</structfield> with
-<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the
-next supported non-compound control, or <errorcode>EINVAL</errorcode>
-if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
-flag can be specified to enumerate all compound controls (i.e. controls
-with type &ge; <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). Specify both
-<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and
-<constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate
-all controls, compound or not. Drivers which do not support these flags yet
-always return <errorcode>EINVAL</errorcode>.</para>
-
- <para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was
-introduced in order to better support controls that can use compound
-types, and to expose additional control information that cannot be
-returned in &v4l2-queryctrl; since that structure is full.</para>
-
- <para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the
-same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the
-<structfield>reserved</structfield> array must be zeroed as well.</para>
-
- <para>Additional information is required for menu controls: the
-names of the menu items. To query them applications set the
-<structfield>id</structfield> and <structfield>index</structfield>
-fields of &v4l2-querymenu; and call the
-<constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this
-structure. The driver fills the rest of the structure or returns an
-&EINVAL; when the <structfield>id</structfield> or
-<structfield>index</structfield> is invalid. Menu items are enumerated
-by calling <constant>VIDIOC_QUERYMENU</constant> with successive
-<structfield>index</structfield> values from &v4l2-queryctrl;
-<structfield>minimum</structfield> to
-<structfield>maximum</structfield>, inclusive. Note that it is possible
-for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some
-indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>.
-In that case that particular menu item is not supported by this driver. Also note that
-the <structfield>minimum</structfield> value is not necessarily 0.</para>
-
- <para>See also the examples in <xref linkend="control" />.</para>
-
- <table pgwide="1" frame="none" id="v4l2-queryctrl">
- <title>struct <structname>v4l2_queryctrl</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>Identifies the control, set by the application. See
-<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
-with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns
-the first control with a higher ID. Drivers which do not support this
-flag yet always return an &EINVAL;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of control, see <xref
- linkend="v4l2-ctrl-type" />.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the control, a NUL-terminated ASCII
-string. This information is intended for the user.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>minimum</structfield></entry>
- <entry>Minimum value, inclusive. This field gives a lower
-bound for the control. See &v4l2-ctrl-type; how the minimum value is to
-be used for each possible control type. Note that this a signed 32-bit value.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>maximum</structfield></entry>
- <entry>Maximum value, inclusive. This field gives an upper
-bound for the control. See &v4l2-ctrl-type; how the maximum value is to
-be used for each possible control type. Note that this a signed 32-bit value.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>step</structfield></entry>
- <entry><para>This field gives a step size for the control.
-See &v4l2-ctrl-type; how the step value is to be used for each possible
-control type. Note that this an unsigned 32-bit value.
-</para><para>Generally drivers should not scale hardware
-control values. It may be necessary for example when the
-<structfield>name</structfield> or <structfield>id</structfield> imply
-a particular unit and the hardware actually accepts only multiples of
-said unit. If so, drivers must take care values are properly rounded
-when scaling, such that errors will not accumulate on repeated
-read-write cycles.</para><para>This field gives the smallest change of
-an integer control actually affecting hardware. Often the information
-is needed when the user can change controls by keyboard or GUI
-buttons, rather than a slider. When for example a hardware register
-accepts values 0-511 and the driver reports 0-65535, step should be
-128.</para><para>Note that although signed, the step value is supposed to
-be always positive.</para></entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>default_value</structfield></entry>
- <entry>The default value of a
-<constant>V4L2_CTRL_TYPE_INTEGER</constant>,
-<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
-<constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control.
-Not valid for other types of controls.
-Note that drivers reset controls to their default value only when the
-driver is first loaded, never afterwards.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Control flags, see <xref
- linkend="control-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>Reserved for future extensions. Drivers must set
-the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-query-ext-ctrl">
- <title>struct <structname>v4l2_query_ext_ctrl</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>Identifies the control, set by the application. See
-<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
-with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the
-flag and returns the first non-compound control with a higher ID. When the
-ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver
-clears the flag and returns the first compound control with a higher ID.
-Set both to get the first control (compound or not) with a higher ID.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of control, see <xref
- linkend="v4l2-ctrl-type" />.</entry>
- </row>
- <row>
- <entry>char</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the control, a NUL-terminated ASCII
-string. This information is intended for the user.</entry>
- </row>
- <row>
- <entry>__s64</entry>
- <entry><structfield>minimum</structfield></entry>
- <entry>Minimum value, inclusive. This field gives a lower
-bound for the control. See &v4l2-ctrl-type; how the minimum value is to
-be used for each possible control type. Note that this a signed 64-bit value.</entry>
- </row>
- <row>
- <entry>__s64</entry>
- <entry><structfield>maximum</structfield></entry>
- <entry>Maximum value, inclusive. This field gives an upper
-bound for the control. See &v4l2-ctrl-type; how the maximum value is to
-be used for each possible control type. Note that this a signed 64-bit value.</entry>
- </row>
- <row>
- <entry>__u64</entry>
- <entry><structfield>step</structfield></entry>
- <entry><para>This field gives a step size for the control.
-See &v4l2-ctrl-type; how the step value is to be used for each possible
-control type. Note that this an unsigned 64-bit value.
-</para><para>Generally drivers should not scale hardware
-control values. It may be necessary for example when the
-<structfield>name</structfield> or <structfield>id</structfield> imply
-a particular unit and the hardware actually accepts only multiples of
-said unit. If so, drivers must take care values are properly rounded
-when scaling, such that errors will not accumulate on repeated
-read-write cycles.</para><para>This field gives the smallest change of
-an integer control actually affecting hardware. Often the information
-is needed when the user can change controls by keyboard or GUI
-buttons, rather than a slider. When for example a hardware register
-accepts values 0-511 and the driver reports 0-65535, step should be
-128.</para></entry>
- </row>
- <row>
- <entry>__s64</entry>
- <entry><structfield>default_value</structfield></entry>
- <entry>The default value of a
-<constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>,
-<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
-<constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>,
-<constant>_U8</constant> or <constant>_U16</constant> control.
-Not valid for other types of controls.
-Note that drivers reset controls to their default value only when the
-driver is first loaded, never afterwards.
-</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Control flags, see <xref
- linkend="control-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>elem_size</structfield></entry>
- <entry>The size in bytes of a single element of the array.
-Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the
-position of cell <constant>(z, y, x)</constant> as follows:
-<constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield>
-is always valid, also when the control isn't an array. For string controls
-<structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>.
-</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>elems</structfield></entry>
- <entry>The number of elements in the N-dimensional array. If this control
-is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield>
-field can never be 0.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>nr_of_dims</structfield></entry>
- <entry>The number of dimension in the N-dimensional array. If this control
-is not an array, then this field is 0.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry>
- <entry>The size of each dimension. The first <structfield>nr_of_dims</structfield>
-elements of this array must be non-zero, all remaining elements must be zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[32]</entry>
- <entry>Reserved for future extensions. Applications and drivers
-must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-querymenu">
- <title>struct <structname>v4l2_querymenu</structname></title>
- <tgroup cols="4">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry></entry>
- <entry><structfield>id</structfield></entry>
- <entry>Identifies the control, set by the application
-from the respective &v4l2-queryctrl;
-<structfield>id</structfield>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry></entry>
- <entry><structfield>index</structfield></entry>
- <entry>Index of the menu item, starting at zero, set by
- the application.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry></entry>
- <entry>__u8</entry>
- <entry><structfield>name</structfield>[32]</entry>
- <entry>Name of the menu item, a NUL-terminated ASCII
-string. This information is intended for the user. This field is valid
-for <constant>V4L2_CTRL_FLAG_MENU</constant> type controls.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>__s64</entry>
- <entry><structfield>value</structfield></entry>
- <entry>
- Value of the integer menu item. This field is valid for
- <constant>V4L2_CTRL_FLAG_INTEGER_MENU</constant> type
- controls.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry></entry>
- <entry><structfield>reserved</structfield></entry>
- <entry>Reserved for future extensions. Drivers must set
-the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-ctrl-type">
- <title>enum v4l2_ctrl_type</title>
- <tgroup cols="5" align="left">
- <colspec colwidth="30*" />
- <colspec colwidth="5*" align="center" />
- <colspec colwidth="5*" align="center" />
- <colspec colwidth="5*" align="center" />
- <colspec colwidth="55*" />
- <thead>
- <row>
- <entry>Type</entry>
- <entry><structfield>minimum</structfield></entry>
- <entry><structfield>step</structfield></entry>
- <entry><structfield>maximum</structfield></entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>An integer-valued control ranging from minimum to
-maximum inclusive. The step value indicates the increment between
-values which are actually different on the hardware.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry>
- <entry>0</entry>
- <entry>1</entry>
- <entry>1</entry>
- <entry>A boolean-valued control. Zero corresponds to
-"disabled", and one means "enabled".</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry>
- <entry>&ge; 0</entry>
- <entry>1</entry>
- <entry>N-1</entry>
- <entry>The control has a menu of N choices. The names of
-the menu items can be enumerated with the
-<constant>VIDIOC_QUERYMENU</constant> ioctl.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_INTEGER_MENU</constant></entry>
- <entry>&ge; 0</entry>
- <entry>1</entry>
- <entry>N-1</entry>
- <entry>
- The control has a menu of N choices. The values of the
- menu items can be enumerated with the
- <constant>VIDIOC_QUERYMENU</constant> ioctl. This is
- similar to <constant>V4L2_CTRL_TYPE_MENU</constant>
- except that instead of strings, the menu items are
- signed 64-bit integers.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_BITMASK</constant></entry>
- <entry>0</entry>
- <entry>n/a</entry>
- <entry>any</entry>
- <entry>A bitmask field. The maximum value is the set of bits that can
-be used, all other bits are to be 0. The maximum value is interpreted as a __u32,
-allowing the use of bit 31 in the bitmask.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>0</entry>
- <entry>A control which performs an action when set.
-Drivers must ignore the value passed with
-<constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a
-<constant>VIDIOC_G_CTRL</constant> attempt.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>A 64-bit integer valued control. Minimum, maximum
-and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>.
-Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit
-min/max/step values, they should be interpreted as n/a when using
-<constant>VIDIOC_QUERYCTRL</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
- <entry>&ge; 0</entry>
- <entry>&ge; 1</entry>
- <entry>&ge; 0</entry>
- <entry>The minimum and maximum string lengths. The step size
-means that the string must be (minimum + N * step) characters long for
-N &ge; 0. These lengths do not include the terminating zero, so in order to
-pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the
-<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can
-set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1.
-Which character encoding is used will depend on the string control itself and
-should be part of the control documentation.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry>
- <entry>n/a</entry>
- <entry>n/a</entry>
- <entry>n/a</entry>
- <entry>This is not a control. When
-<constant>VIDIOC_QUERYCTRL</constant> is called with a control ID
-equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the
-ioctl returns the name of the control class and this control type.
-Older drivers which do not support this feature return an
-&EINVAL;.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_U8</constant></entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>An unsigned 8-bit valued control ranging from minimum to
-maximum inclusive. The step value indicates the increment between
-values which are actually different on the hardware.
-</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_TYPE_U16</constant></entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>any</entry>
- <entry>An unsigned 16-bit valued control ranging from minimum to
-maximum inclusive. The step value indicates the increment between
-values which are actually different on the hardware.
-</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="control-flags">
- <title>Control Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry>
- <entry>0x0001</entry>
- <entry>This control is permanently disabled and should be
-ignored by the application. Any attempt to change the control will
-result in an &EINVAL;.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry>
- <entry>0x0002</entry>
- <entry>This control is temporarily unchangeable, for
-example because another application took over control of the
-respective resource. Such controls may be displayed specially in a
-user interface. Attempts to change the control may result in an
-&EBUSY;.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry>
- <entry>0x0004</entry>
- <entry>This control is permanently readable only. Any
-attempt to change the control will result in an &EINVAL;.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry>
- <entry>0x0008</entry>
- <entry>A hint that changing this control may affect the
-value of other controls within the same control class. Applications
-should update their user interface accordingly.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry>
- <entry>0x0010</entry>
- <entry>This control is not applicable to the current
-configuration and should be displayed accordingly in a user interface.
-For example the flag may be set on a MPEG audio level 2 bitrate
-control when MPEG audio encoding level 1 was selected with another
-control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry>
- <entry>0x0020</entry>
- <entry>A hint that this control is best represented as a
-slider-like element in a user interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry>
- <entry>0x0040</entry>
- <entry>This control is permanently writable only. Any
-attempt to read the control will result in an &EACCES; error code. This
-flag is typically present for relative controls or action controls where
-writing a value will cause the device to carry out a given action
-(&eg; motor control) but no meaningful value can be returned.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_VOLATILE</constant></entry>
- <entry>0x0080</entry>
- <entry>This control is volatile, which means that the value of the control
-changes continuously. A typical example would be the current gain value if the device
-is in auto-gain mode. In such a case the hardware calculates the gain value based on
-the lighting conditions which can change over time. Note that setting a new value for
-a volatile control will have no effect and no <constant>V4L2_EVENT_CTRL_CH_VALUE</constant>
-will be sent, unless the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant> flag
-(see below) is also set. Otherwise the new value will just be ignored.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry>
- <entry>0x0100</entry>
- <entry>This control has a pointer type, so its value has to be accessed
-using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls
-that are an array, string, or have a compound type. In all cases you have to set a
-pointer to memory containing the payload of the control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant></entry>
- <entry>0x0200</entry>
- <entry>The value provided to the control will be propagated to the driver
-even if remains constant. This is required when the control represents an action
-on the hardware. For example: clearing an error flag or triggering the flash. All the
-controls of the type <constant>V4L2_CTRL_TYPE_BUTTON</constant> have this flag set.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-queryctrl; <structfield>id</structfield>
-is invalid. The &v4l2-querymenu; <structfield>id</structfield> is
-invalid or <structfield>index</structfield> is out of range (less than
-<structfield>minimum</structfield> or greater than <structfield>maximum</structfield>)
-or this particular menu item is not supported by the driver.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para>An attempt was made to read a write-only control.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-querystd.xml b/Documentation/DocBook/media/v4l/vidioc-querystd.xml
deleted file mode 100644
index 222348542182..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-querystd.xml
+++ /dev/null
@@ -1,75 +0,0 @@
-<refentry id="vidioc-querystd">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_QUERYSTD</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_QUERYSTD</refname>
- <refpurpose>Sense the video standard received by the current
-input</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>v4l2_std_id *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_QUERYSTD</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The hardware may be able to detect the current video
-standard automatically. To do so, applications call <constant>
-VIDIOC_QUERYSTD</constant> with a pointer to a &v4l2-std-id; type. The
-driver stores here a set of candidates, this can be a single flag or a
-set of supported standards if for example the hardware can only
-distinguish between 50 and 60 Hz systems. If no signal was detected,
-then the driver will return V4L2_STD_UNKNOWN. When detection is not
-possible or fails, the set must contain all standards supported by the
-current video input or output.</para>
-
- </refsect1>
-
- <refsect1>
- &return-value;
- <variablelist>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>Standard video timings are not supported for this input or output.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
deleted file mode 100644
index 78a06a9a5ece..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
+++ /dev/null
@@ -1,137 +0,0 @@
-<refentry id="vidioc-reqbufs">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_REQBUFS</refname>
- <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_REQBUFS</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
-<para>This ioctl is used to initiate <link linkend="mmap">memory mapped</link>,
-<link linkend="userp">user pointer</link> or <link
-linkend="dmabuf">DMABUF</link> based I/O. Memory mapped buffers are located in
-device memory and must be allocated with this ioctl before they can be mapped
-into the application's address space. User buffers are allocated by
-applications themselves, and this ioctl is merely used to switch the driver
-into user pointer I/O mode and to setup some internal structures.
-Similarly, DMABUF buffers are allocated by applications through a device
-driver, and this ioctl only configures the driver into DMABUF I/O mode without
-performing any direct allocation.</para>
-
- <para>To allocate device buffers applications initialize all fields of the
-<structname>v4l2_requestbuffers</structname> structure. They set the
-<structfield>type</structfield> field to the respective stream or buffer type,
-the <structfield>count</structfield> field to the desired number of buffers,
-<structfield>memory</structfield> must be set to the requested I/O method and
-the <structfield>reserved</structfield> array must be zeroed. When the ioctl is
-called with a pointer to this structure the driver will attempt to allocate the
-requested number of buffers and it stores the actual number allocated in the
-<structfield>count</structfield> field. It can be smaller than the number
-requested, even zero, when the driver runs out of free memory. A larger number
-is also possible when the driver requires more buffers to function correctly.
-For example video output requires at least two buffers, one displayed and one
-filled by the application.</para>
- <para>When the I/O method is not supported the ioctl
-returns an &EINVAL;.</para>
-
- <para>Applications can call <constant>VIDIOC_REQBUFS</constant>
-again to change the number of buffers, however this cannot succeed
-when any buffers are still mapped. A <structfield>count</structfield>
-value of zero frees all buffers, after aborting or finishing any DMA
-in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no
-reason why munmap()ping one or even all buffers must imply
-streamoff.--></para>
-
- <table pgwide="1" frame="none" id="v4l2-requestbuffers">
- <title>struct <structname>v4l2_requestbuffers</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>count</structfield></entry>
- <entry>The number of buffers requested or granted.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the stream or buffers, this is the same
-as the &v4l2-format; <structfield>type</structfield> field. See <xref
- linkend="v4l2-buf-type" /> for valid values.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>memory</structfield></entry>
- <entry>Applications set this field to
-<constant>V4L2_MEMORY_MMAP</constant>,
-<constant>V4L2_MEMORY_DMABUF</constant> or
-<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
-/>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>A place holder for future extensions. This array should
-be zeroed by applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The buffer type (<structfield>type</structfield> field) or the
-requested I/O method (<structfield>memory</structfield>) is not
-supported.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml
deleted file mode 100644
index a5fc4c4880f3..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml
+++ /dev/null
@@ -1,188 +0,0 @@
-<refentry id="vidioc-s-hw-freq-seek">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_S_HW_FREQ_SEEK</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_S_HW_FREQ_SEEK</refname>
- <refpurpose>Perform a hardware frequency seek</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_hw_freq_seek
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_S_HW_FREQ_SEEK</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Start a hardware frequency seek from the current frequency.
-To do this applications initialize the <structfield>tuner</structfield>,
-<structfield>type</structfield>, <structfield>seek_upward</structfield>,
-<structfield>wrap_around</structfield>, <structfield>spacing</structfield>,
-<structfield>rangelow</structfield> and <structfield>rangehigh</structfield>
-fields, and zero out the <structfield>reserved</structfield> array of a
-&v4l2-hw-freq-seek; and call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant>
-ioctl with a pointer to this structure.</para>
-
- <para>The <structfield>rangelow</structfield> and
-<structfield>rangehigh</structfield> fields can be set to a non-zero value to
-tell the driver to search a specific band. If the &v4l2-tuner;
-<structfield>capability</structfield> field has the
-<constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant> flag set, these values
-must fall within one of the bands returned by &VIDIOC-ENUM-FREQ-BANDS;. If
-the <constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant> flag is not set,
-then these values must exactly match those of one of the bands returned by
-&VIDIOC-ENUM-FREQ-BANDS;. If the current frequency of the tuner does not fall
-within the selected band it will be clamped to fit in the band before the
-seek is started.</para>
-
- <para>If an error is returned, then the original frequency will
- be restored.</para>
-
- <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para>
-
- <para>If this ioctl is called from a non-blocking filehandle, then &EAGAIN; is
- returned and no seek takes place.</para>
-
- <table pgwide="1" frame="none" id="v4l2-hw-freq-seek">
- <title>struct <structname>v4l2_hw_freq_seek</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>tuner</structfield></entry>
- <entry>The tuner index number. This is the
-same value as in the &v4l2-input; <structfield>tuner</structfield>
-field and the &v4l2-tuner; <structfield>index</structfield> field.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>The tuner type. This is the same value as in the
-&v4l2-tuner; <structfield>type</structfield> field. See <xref
- linkend="v4l2-tuner-type" /></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>seek_upward</structfield></entry>
- <entry>If non-zero, seek upward from the current frequency, else seek downward.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>wrap_around</structfield></entry>
- <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking.
- The &v4l2-tuner; <structfield>capability</structfield> field will tell you what the
- hardware supports.
- </entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>spacing</structfield></entry>
- <entry>If non-zero, defines the hardware seek resolution in Hz. The driver selects the nearest value that is supported by the device. If spacing is zero a reasonable default value is used.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangelow</structfield></entry>
- <entry>If non-zero, the lowest tunable frequency of the band to
-search in units of 62.5 kHz, or if the &v4l2-tuner;
-<structfield>capability</structfield> field has the
-<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner;
-<structfield>capability</structfield> field has the
-<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz.
-If <structfield>rangelow</structfield> is zero a reasonable default value
-is used.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>rangehigh</structfield></entry>
- <entry>If non-zero, the highest tunable frequency of the band to
-search in units of 62.5 kHz, or if the &v4l2-tuner;
-<structfield>capability</structfield> field has the
-<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner;
-<structfield>capability</structfield> field has the
-<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz.
-If <structfield>rangehigh</structfield> is zero a reasonable default value
-is used.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[5]</entry>
- <entry>Reserved for future extensions. Applications
- must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <structfield>tuner</structfield> index is out of
-bounds, the <structfield>wrap_around</structfield> value is not supported or
-one of the values in the <structfield>type</structfield>,
-<structfield>rangelow</structfield> or <structfield>rangehigh</structfield>
-fields is wrong.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EAGAIN</errorcode></term>
- <listitem>
- <para>Attempted to call <constant>VIDIOC_S_HW_FREQ_SEEK</constant>
- with the filehandle in non-blocking mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENODATA</errorcode></term>
- <listitem>
- <para>The hardware seek found no channels.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>Another hardware seek is already in progress.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-streamon.xml b/Documentation/DocBook/media/v4l/vidioc-streamon.xml
deleted file mode 100644
index df2c63d07bac..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-streamon.xml
+++ /dev/null
@@ -1,128 +0,0 @@
-<refentry id="vidioc-streamon">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_STREAMON</refname>
- <refname>VIDIOC_STREAMOFF</refname>
- <refpurpose>Start or stop streaming I/O</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const int *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_STREAMON, VIDIOC_STREAMOFF</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The <constant>VIDIOC_STREAMON</constant> and
-<constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture
-or output process during streaming (<link linkend="mmap">memory
-mapping</link>, <link linkend="userp">user pointer</link> or
-<link linkend="dmabuf">DMABUF</link>) I/O.</para>
-
- <para>Capture hardware is disabled and no input
-buffers are filled (if there are any empty buffers in the incoming
-queue) until <constant>VIDIOC_STREAMON</constant> has been called.
-Output hardware is disabled and no video signal is
-produced until <constant>VIDIOC_STREAMON</constant> has been called.
-The ioctl will succeed when at least one output buffer is in the
-incoming queue.</para>
-
- <para>Memory-to-memory devices will not start until
-<constant>VIDIOC_STREAMON</constant> has been called for both the capture
-and output stream types.</para>
-
- <para>If <constant>VIDIOC_STREAMON</constant> fails then any already
-queued buffers will remain queued.</para>
-
- <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
-aborting or finishing any DMA in progress, unlocks any user pointer
-buffers locked in physical memory, and it removes all buffers from the
-incoming and outgoing queues. That means all images captured but not
-dequeued yet will be lost, likewise all images enqueued for output but
-not transmitted yet. I/O returns to the same state as after calling
-&VIDIOC-REQBUFS; and can be restarted accordingly.</para>
-
- <para>If buffers have been queued with &VIDIOC-QBUF; and
-<constant>VIDIOC_STREAMOFF</constant> is called without ever having
-called <constant>VIDIOC_STREAMON</constant>, then those queued buffers
-will also be removed from the incoming queue and all are returned to the
-same state as after calling &VIDIOC-REQBUFS; and can be restarted
-accordingly.</para>
-
- <para>Both ioctls take a pointer to an integer, the desired buffer or
-stream type. This is the same as &v4l2-requestbuffers;
-<structfield>type</structfield>.</para>
-
- <para>If <constant>VIDIOC_STREAMON</constant> is called when streaming
-is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called
-when streaming is already stopped, then 0 is returned. Nothing happens in the
-case of <constant>VIDIOC_STREAMON</constant>, but <constant>VIDIOC_STREAMOFF</constant>
-will return queued buffers to their starting state as mentioned above.</para>
-
- <para>Note that applications can be preempted for unknown periods right
-before or after the <constant>VIDIOC_STREAMON</constant> or
-<constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
-starting or stopping "now". Buffer timestamps can be used to
-synchronize with other events.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The buffer <structfield>type</structfield> is not supported,
- or no buffers have been allocated (memory mapping) or enqueued
- (output) yet.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EPIPE</errorcode></term>
- <listitem>
- <para>The driver implements <link
- linkend="pad-level-formats">pad-level format configuration</link> and
- the pipeline configuration is invalid.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml
deleted file mode 100644
index cff59f5cbf04..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml
+++ /dev/null
@@ -1,157 +0,0 @@
-<refentry id="vidioc-subdev-enum-frame-interval">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname>
- <refpurpose>Enumerate frame intervals</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_frame_interval_enum *
- <parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>This ioctl lets applications enumerate available frame intervals on a
- given sub-device pad. Frame intervals only makes sense for sub-devices that
- can control the frame period on their own. This includes, for instance,
- image sensors and TV tuners.</para>
-
- <para>For the common use case of image sensors, the frame intervals
- available on the sub-device output pad depend on the frame format and size
- on the same pad. Applications must thus specify the desired format and size
- when enumerating frame intervals.</para>
-
- <para>To enumerate frame intervals applications initialize the
- <structfield>index</structfield>, <structfield>pad</structfield>,
- <structfield>which</structfield>, <structfield>code</structfield>,
- <structfield>width</structfield> and <structfield>height</structfield>
- fields of &v4l2-subdev-frame-interval-enum; and call the
- <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
- to this structure. Drivers fill the rest of the structure or return
- an &EINVAL; if one of the input fields is invalid. All frame intervals are
- enumerable by beginning at index zero and incrementing by one until
- <errorcode>EINVAL</errorcode> is returned.</para>
-
- <para>Available frame intervals may depend on the current 'try' formats
- at other pads of the sub-device, as well as on the current active links. See
- &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
-
- <para>Sub-devices that support the frame interval enumeration ioctl should
- implemented it on a single pad only. Its behaviour when supported on
- multiple pads of the same sub-device is not defined.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
- <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the format in the enumeration, set by the
- application.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>code</structfield></entry>
- <entry>The media bus format code, as defined in
- <xref linkend="v4l2-mbus-format" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Frame width, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Frame height, in pixels.</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>interval</structfield></entry>
- <entry>Period, in seconds, between consecutive video frames.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry>Frame intervals to be enumerated, from &v4l2-subdev-format-whence;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-frame-interval-enum;
- <structfield>pad</structfield> references a non-existing pad, one of
- the <structfield>code</structfield>, <structfield>width</structfield>
- or <structfield>height</structfield> fields are invalid for the given
- pad or the <structfield>index</structfield> field is out of bounds.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml
deleted file mode 100644
index abd545ede67a..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml
+++ /dev/null
@@ -1,159 +0,0 @@
-<refentry id="vidioc-subdev-enum-frame-size">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refname>
- <refpurpose>Enumerate media bus frame sizes</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_frame_size_enum *
- <parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>This ioctl allows applications to enumerate all frame sizes
- supported by a sub-device on the given pad for the given media bus format.
- Supported formats can be retrieved with the &VIDIOC-SUBDEV-ENUM-MBUS-CODE;
- ioctl.</para>
-
- <para>To enumerate frame sizes applications initialize the
- <structfield>pad</structfield>, <structfield>which</structfield> ,
- <structfield>code</structfield> and <structfield>index</structfield>
- fields of the &v4l2-subdev-mbus-code-enum; and call the
- <constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant> ioctl with a pointer to
- the structure. Drivers fill the minimum and maximum frame sizes or return
- an &EINVAL; if one of the input parameters is invalid.</para>
-
- <para>Sub-devices that only support discrete frame sizes (such as most
- sensors) will return one or more frame sizes with identical minimum and
- maximum values.</para>
-
- <para>Not all possible sizes in given [minimum, maximum] ranges need to be
- supported. For instance, a scaler that uses a fixed-point scaling ratio
- might not be able to produce every frame size between the minimum and
- maximum values. Applications must use the &VIDIOC-SUBDEV-S-FMT; ioctl to
- try the sub-device for an exact supported frame size.</para>
-
- <para>Available frame sizes may depend on the current 'try' formats at other
- pads of the sub-device, as well as on the current active links and the
- current values of V4L2 controls. See &VIDIOC-SUBDEV-G-FMT; for more
- information about try formats.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-frame-size-enum">
- <title>struct <structname>v4l2_subdev_frame_size_enum</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the format in the enumeration, set by the
- application.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>code</structfield></entry>
- <entry>The media bus format code, as defined in
- <xref linkend="v4l2-mbus-format" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>min_width</structfield></entry>
- <entry>Minimum frame width, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>max_width</structfield></entry>
- <entry>Maximum frame width, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>min_height</structfield></entry>
- <entry>Minimum frame height, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>max_height</structfield></entry>
- <entry>Maximum frame height, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry>Frame sizes to be enumerated, from &v4l2-subdev-format-whence;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-frame-size-enum; <structfield>pad</structfield>
- references a non-existing pad, the <structfield>code</structfield> is
- invalid for the given pad or the <structfield>index</structfield>
- field is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml
deleted file mode 100644
index 0bcb278fd062..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml
+++ /dev/null
@@ -1,124 +0,0 @@
-<refentry id="vidioc-subdev-enum-mbus-code">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_ENUM_MBUS_CODE</refname>
- <refpurpose>Enumerate media bus formats</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_mbus_code_enum *
- <parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_ENUM_MBUS_CODE</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>To enumerate media bus formats available at a given sub-device pad
- applications initialize the <structfield>pad</structfield>, <structfield>which</structfield>
- and <structfield>index</structfield> fields of &v4l2-subdev-mbus-code-enum; and
- call the <constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant> ioctl with a
- pointer to this structure. Drivers fill the rest of the structure or return
- an &EINVAL; if either the <structfield>pad</structfield> or
- <structfield>index</structfield> are invalid. All media bus formats are
- enumerable by beginning at index zero and incrementing by one until
- <errorcode>EINVAL</errorcode> is returned.</para>
-
- <para>Available media bus formats may depend on the current 'try' formats
- at other pads of the sub-device, as well as on the current active links. See
- &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-mbus-code-enum">
- <title>struct <structname>v4l2_subdev_mbus_code_enum</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>index</structfield></entry>
- <entry>Number of the format in the enumeration, set by the
- application.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>code</structfield></entry>
- <entry>The media bus format code, as defined in
- <xref linkend="v4l2-mbus-format" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry>Media bus format codes to be enumerated, from &v4l2-subdev-format-whence;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-mbus-code-enum; <structfield>pad</structfield>
- references a non-existing pad, or the <structfield>index</structfield>
- field is out of bounds.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml
deleted file mode 100644
index 4cddd788c589..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml
+++ /dev/null
@@ -1,158 +0,0 @@
-<refentry id="vidioc-subdev-g-crop">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_G_CROP</refname>
- <refname>VIDIOC_SUBDEV_S_CROP</refname>
- <refpurpose>Get or set the crop rectangle on a subdev pad</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>const struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Obsolete</title>
-
- <para>This is an <link linkend="obsolete">obsolete</link>
- interface and may be removed in the future. It is superseded by
- <link linkend="vidioc-subdev-g-selection">the selection
- API</link>.</para>
- </note>
-
- <para>To retrieve the current crop rectangle applications set the
- <structfield>pad</structfield> field of a &v4l2-subdev-crop; to the
- desired pad number as reported by the media API and the
- <structfield>which</structfield> field to
- <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. They then call the
- <constant>VIDIOC_SUBDEV_G_CROP</constant> ioctl with a pointer to this
- structure. The driver fills the members of the <structfield>rect</structfield>
- field or returns &EINVAL; if the input arguments are invalid, or if cropping
- is not supported on the given pad.</para>
-
- <para>To change the current crop rectangle applications set both the
- <structfield>pad</structfield> and <structfield>which</structfield> fields
- and all members of the <structfield>rect</structfield> field. They then call
- the <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctl with a pointer to this
- structure. The driver verifies the requested crop rectangle, adjusts it
- based on the hardware capabilities and configures the device. Upon return
- the &v4l2-subdev-crop; contains the current format as would be returned
- by a <constant>VIDIOC_SUBDEV_G_CROP</constant> call.</para>
-
- <para>Applications can query the device capabilities by setting the
- <structfield>which</structfield> to
- <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' crop
- rectangles are not applied to the device by the driver, but are mangled
- exactly as active crop rectangles and stored in the sub-device file handle.
- Two applications querying the same sub-device would thus not interact with
- each other.</para>
-
- <para>Drivers must not return an error solely because the requested crop
- rectangle doesn't match the device capabilities. They must instead modify
- the rectangle to match what the hardware can provide. The modified format
- should be as close as possible to the original request.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-crop">
- <title>struct <structname>v4l2_subdev_crop</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media framework.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry>Crop rectangle to get or set, from
- &v4l2-subdev-format-whence;.</entry>
- </row>
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>rect</structfield></entry>
- <entry>Crop rectangle boundaries, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The crop rectangle can't be changed because the pad is currently
- busy. This can be caused, for instance, by an active video stream on
- the pad. The ioctl must not be retried without performing another
- action to fix the problem first. Only returned by
- <constant>VIDIOC_SUBDEV_S_CROP</constant></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-crop; <structfield>pad</structfield>
- references a non-existing pad, the <structfield>which</structfield>
- field references a non-existing format, or cropping is not supported
- on the given subdev pad.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml
deleted file mode 100644
index a67cde6f8c54..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml
+++ /dev/null
@@ -1,183 +0,0 @@
-<refentry id="vidioc-subdev-g-fmt">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_G_FMT</refname>
- <refname>VIDIOC_SUBDEV_S_FMT</refname>
- <refpurpose>Get or set the data format on a subdev pad</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_format *<parameter>argp</parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>These ioctls are used to negotiate the frame format at specific
- subdev pads in the image pipeline.</para>
-
- <para>To retrieve the current format applications set the
- <structfield>pad</structfield> field of a &v4l2-subdev-format; to the
- desired pad number as reported by the media API and the
- <structfield>which</structfield> field to
- <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. When they call the
- <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl with a pointer to this
- structure the driver fills the members of the <structfield>format</structfield>
- field.</para>
-
- <para>To change the current format applications set both the
- <structfield>pad</structfield> and <structfield>which</structfield> fields
- and all members of the <structfield>format</structfield> field. When they
- call the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl with a pointer to this
- structure the driver verifies the requested format, adjusts it based on the
- hardware capabilities and configures the device. Upon return the
- &v4l2-subdev-format; contains the current format as would be returned by a
- <constant>VIDIOC_SUBDEV_G_FMT</constant> call.</para>
-
- <para>Applications can query the device capabilities by setting the
- <structfield>which</structfield> to
- <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' formats are not
- applied to the device by the driver, but are changed exactly as active
- formats and stored in the sub-device file handle. Two applications querying
- the same sub-device would thus not interact with each other.</para>
-
- <para>For instance, to try a format at the output pad of a sub-device,
- applications would first set the try format at the sub-device input with the
- <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl. They would then either
- retrieve the default format at the output pad with the
- <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl, or set the desired output
- pad format with the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl and check
- the returned value.</para>
-
- <para>Try formats do not depend on active formats, but can depend on the
- current links configuration or sub-device controls value. For instance, a
- low-pass noise filter might crop pixels at the frame boundaries, modifying
- its output frame size.</para>
-
- <para>Drivers must not return an error solely because the requested format
- doesn't match the device capabilities. They must instead modify the format
- to match what the hardware can provide. The modified format should be as
- close as possible to the original request.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-format">
- <title>struct <structname>v4l2_subdev_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry>Format to modified, from &v4l2-subdev-format-whence;.</entry>
- </row>
- <row>
- <entry>&v4l2-mbus-framefmt;</entry>
- <entry><structfield>format</structfield></entry>
- <entry>Definition of an image format, see <xref
- linkend="v4l2-mbus-framefmt" /> for details.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-format-whence">
- <title>enum <structname>v4l2_subdev_format_whence</structname></title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry>V4L2_SUBDEV_FORMAT_TRY</entry>
- <entry>0</entry>
- <entry>Try formats, used for querying device capabilities.</entry>
- </row>
- <row>
- <entry>V4L2_SUBDEV_FORMAT_ACTIVE</entry>
- <entry>1</entry>
- <entry>Active formats, applied to the hardware.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The format can't be changed because the pad is currently busy.
- This can be caused, for instance, by an active video stream on the
- pad. The ioctl must not be retried without performing another action
- to fix the problem first. Only returned by
- <constant>VIDIOC_SUBDEV_S_FMT</constant></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-format; <structfield>pad</structfield>
- references a non-existing pad, or the <structfield>which</structfield>
- field references a non-existing format.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml
deleted file mode 100644
index 0bc3ea22d31f..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml
+++ /dev/null
@@ -1,141 +0,0 @@
-<refentry id="vidioc-subdev-g-frame-interval">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_G_FRAME_INTERVAL</refname>
- <refname>VIDIOC_SUBDEV_S_FRAME_INTERVAL</refname>
- <refpurpose>Get or set the frame interval on a subdev pad</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_frame_interval *<parameter>argp</parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>These ioctls are used to get and set the frame interval at specific
- subdev pads in the image pipeline. The frame interval only makes sense for
- sub-devices that can control the frame period on their own. This includes,
- for instance, image sensors and TV tuners. Sub-devices that don't support
- frame intervals must not implement these ioctls.</para>
-
- <para>To retrieve the current frame interval applications set the
- <structfield>pad</structfield> field of a &v4l2-subdev-frame-interval; to
- the desired pad number as reported by the media controller API. When they
- call the <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> ioctl with a
- pointer to this structure the driver fills the members of the
- <structfield>interval</structfield> field.</para>
-
- <para>To change the current frame interval applications set both the
- <structfield>pad</structfield> field and all members of the
- <structfield>interval</structfield> field. When they call the
- <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant> ioctl with a pointer to
- this structure the driver verifies the requested interval, adjusts it based
- on the hardware capabilities and configures the device. Upon return the
- &v4l2-subdev-frame-interval; contains the current frame interval as would be
- returned by a <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> call.
- </para>
-
- <para>Drivers must not return an error solely because the requested interval
- doesn't match the device capabilities. They must instead modify the interval
- to match what the hardware can provide. The modified interval should be as
- close as possible to the original request.</para>
-
- <para>Sub-devices that support the frame interval ioctls should implement
- them on a single pad only. Their behaviour when supported on multiple pads
- of the same sub-device is not defined.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval">
- <title>struct <structname>v4l2_subdev_frame_interval</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media controller API.</entry>
- </row>
- <row>
- <entry>&v4l2-fract;</entry>
- <entry><structfield>interval</structfield></entry>
- <entry>Period, in seconds, between consecutive video frames.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[9]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The frame interval can't be changed because the pad is currently
- busy. This can be caused, for instance, by an active video stream on
- the pad. The ioctl must not be retried without performing another
- action to fix the problem first. Only returned by
- <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-frame-interval; <structfield>pad</structfield>
- references a non-existing pad, or the pad doesn't support frame
- intervals.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
deleted file mode 100644
index c62a7360719b..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-<refentry id="vidioc-subdev-g-selection">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBDEV_G_SELECTION</refname>
- <refname>VIDIOC_SUBDEV_S_SELECTION</refname>
- <refpurpose>Get or set selection rectangles on a subdev pad</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_subdev_selection *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>The selections are used to configure various image
- processing functionality performed by the subdevs which affect the
- image size. This currently includes cropping, scaling and
- composition.</para>
-
- <para>The selection API replaces <link
- linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All
- the function of the crop API, and more, are supported by the
- selections API.</para>
-
- <para>See <xref linkend="subdev"></xref> for
- more information on how each selection target affects the image
- processing pipeline inside the subdevice.</para>
-
- <refsect2>
- <title>Types of selection targets</title>
-
- <para>There are two types of selection targets: actual and bounds. The
- actual targets are the targets which configure the hardware. The BOUNDS
- target will return a rectangle that contain all possible actual
- rectangles.</para>
- </refsect2>
-
- <refsect2>
- <title>Discovering supported features</title>
-
- <para>To discover which targets are supported, the user can
- perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them.
- Any unsupported target will return
- <constant>EINVAL</constant>.</para>
-
- <para>Selection targets and flags are documented in <xref
- linkend="v4l2-selections-common"/>.</para>
-
- <table pgwide="1" frame="none" id="v4l2-subdev-selection">
- <title>struct <structname>v4l2_subdev_selection</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry>Active or try selection, from
- &v4l2-subdev-format-whence;.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>pad</structfield></entry>
- <entry>Pad number as reported by the media framework.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>target</structfield></entry>
- <entry>Target selection rectangle. See
- <xref linkend="v4l2-selections-common" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Flags. See
- <xref linkend="v4l2-selection-flags" />.</entry>
- </row>
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>r</structfield></entry>
- <entry>Selection rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[8]</entry>
- <entry>Reserved for future extensions. Applications and drivers must
- set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </refsect2>
-
- </refsect1>
-
- <refsect1>
- &return-value;
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The selection rectangle can't be changed because the
- pad is currently busy. This can be caused, for instance, by
- an active video stream on the pad. The ioctl must not be
- retried without performing another action to fix the problem
- first. Only returned by
- <constant>VIDIOC_SUBDEV_S_SELECTION</constant></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The &v4l2-subdev-selection;
- <structfield>pad</structfield> references a non-existing
- pad, the <structfield>which</structfield> field references a
- non-existing format, or the selection target is not
- supported on the given subdev pad.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
deleted file mode 100644
index d0332f610929..000000000000
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ /dev/null
@@ -1,129 +0,0 @@
-<refentry id="vidioc-subscribe-event">
- <refmeta>
- <refentrytitle>ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refname>
- <refpurpose>Subscribe or unsubscribe event</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>struct v4l2_event_subscription
-*<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Subscribe or unsubscribe V4L2 event. Subscribed events are
- dequeued by using the &VIDIOC-DQEVENT; ioctl.</para>
-
- <table frame="none" pgwide="1" id="v4l2-event-subscription">
- <title>struct <structname>v4l2_event_subscription</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>type</structfield></entry>
- <entry>Type of the event, see <xref linkend="event-type" />. Note that
-<constant>V4L2_EVENT_ALL</constant> can be used with VIDIOC_UNSUBSCRIBE_EVENT
-for unsubscribing all events at once.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>ID of the event source. If there is no ID associated with
- the event source, then set this to 0. Whether or not an event
- needs an ID depends on the event type.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>Event flags, see <xref linkend="event-flags" />.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[5]</entry>
- <entry>Reserved for future extensions. Drivers and applications
- must set the array to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="event-flags">
- <title>Event Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EVENT_SUB_FL_SEND_INITIAL</constant></entry>
- <entry>0x0001</entry>
- <entry>When this event is subscribed an initial event will be sent
- containing the current status. This only makes sense for events
- that are triggered by a status change such as <constant>V4L2_EVENT_CTRL</constant>.
- Other events will ignore this flag.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant></entry>
- <entry>0x0002</entry>
- <entry><para>If set, then events directly caused by an ioctl will also be sent to
- the filehandle that called that ioctl. For example, changing a control using
- &VIDIOC-S-CTRL; will cause a V4L2_EVENT_CTRL to be sent back to that same
- filehandle. Normally such events are suppressed to prevent feedback loops
- where an application changes a control to a one value and then another, and
- then receives an event telling it that that control has changed to the first
- value.</para>
-
- <para>Since it can't tell whether that event was caused by another application
- or by the &VIDIOC-S-CTRL; call it is hard to decide whether to set the
- control to the value in the event, or ignore it.</para>
-
- <para>Think carefully when you set this flag so you won't get into situations
- like that.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </refsect1>
- <refsect1>
- &return-value;
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/vbi_525.gif.b64 b/Documentation/DocBook/media/vbi_525.gif.b64
deleted file mode 100644
index d5dcf06f2aef..000000000000
--- a/Documentation/DocBook/media/vbi_525.gif.b64
+++ /dev/null
@@ -1,84 +0,0 @@
-R0lGODlhKgPIAIAAAAAAAP///yH5BAEAAAEALAAAAAAqA8gAAAL+jI+py+0Po5y02ouz3rz7D4bi
-SJbmiabqWgJs475LLCt0fdy4oeN9/QPuEEFZkXVcJZXDXNP5pC0TgGrMSrRMidhA1/uNbB9j2CZ8
-Kc+qHDXDTT2jK3BuPau13vFpdmc/p6Uh5SeYoXMHyFNomEeYiNEVKCFFx8Wz2Eh56YWp2bfnGXk1
-OEhaKnem2rYa6vp3KIqaBhULmsk4Ufc1KTbq4rfbhxkcOQx22limZ4P8STYH3PsGu8pqe439aw36
-eji9qT1rGCpraf5MkQynyJeuG0c73imvLYzuUAwF/P6WTK8vHDdj2Qia8hYL4bF2o/CpmydOXa6I
-uqQNPFepny/+d+cM0qsH8qNGCI8M3gvG7KG8iSJJVoNIp1w5h/C+gSPjgWE9hR0Lqmzp0RFPjLV+
-hoRki2XNPJyCVmy2U6KnHm6WnboRcOPFkS59xqQpEKZRpkDHfi1rdqlXgTMVKVVL7h/cnmi1rtxq
-t27Yn1n5xrySUi81iYAlvR2MN23Fm/nkyHzp9G9iSof3Ps1pE3PmyV2dhaSL1Jiee3/ZjI5Mkhlj
-xDPXGnkClgns1pxV0K6d4rbYF7pRv44CW7Dtojt6f/YxO7hxrrmVJ3/eZDnd4tCjVw+OPbv27dy7
-e/8OPrz48eTLmz+PPr369ezbu38PP778+fTr27+PP7/+/fz++/v/D2CAAg5IYIEGHohgggouSNFv
-1l2HHIRCACehgw9eOIR0001I4YVq8MJIVZItUpJiG564GG75VJaXb5aVthtljwnV1mauyXijVqtB
-FVRoK7Foxi0kNphaYdhYNRUxQMZDWZKd9IXTQTmmFluUDQln5TcqBrnlYEOhaGJXNZrUpR24sLPN
-kC6uaBGWMywERpWISeUZacIE5iZH8OApJ3FrtvhnY5AdR1iZVOw4p1BTZhljlGNG1aijfgIKl4+f
-kNZjoIL2ySOacX4kYlyyfDgooWBSWmikOH15mU5ksfqiqUVqNsySXN7FqZ5jWdoTr7sSqaOtTH6Y
-EajMNZX+kbC53qopDDMuymhprgLbGaTUbgrtm8smCqOqQRYbZrV58vijtzZgNW2TTHZEag7rHFuU
-Pp4aSq6sc9EJa7jinpVuq/Ruy+xSj9KibL0YyRXrXr7WlC+242qrDMJsEYYSVvAiUzGJwg7c7BqI
-GjyiuQ5f7PG/7j57VqkpqryyyJ0WDDBxC29ymr3+YFEzyRpLE5qG91qYYYVAR4hh0B0WTbTRR1Mn
-NBKTDs0h0lErTTXTSyddNdZabw311ET7nLDTTct2tddmn82bc2V3zbbYazMId9xyz0133XbfjXfe
-eu/Nd99+/w144IIPTnjhhh+OeOKKczcR2CYvDnnkkgf+XoTF2eUCs9uTb85554MrVUjmJGDuuMue
-n4566gKyxM+T2L37cNqqz0577QG2/ikpVxEie7LflW578MIPL1vroVdifOy3outkscD/THz00k+v
-ne46ApQT70o2ZWz1RT5Pffji2w4YWcqLkrzvMhNT/Wjuvy/6+PLPL/w/854vr+t58gP+vufySb8A
-CnB8phEBmo7nhDHwz3vQGKADH0jAT4UgVGZQILjeBsEManB6GqKgP+h0vtFtcIQk5KAJpqAa/znL
-Xc4CXv9KCMP2fMyA8fvDDCdYwzbg7IQbwZ0IqeHCGArRbj4UwgvxgDJSHXEfIUQVEpuIqiLycIhU
-jJv+FNO2RCeJQ4kPuuIHUMi+Kb4piFUso4K8yIQsYm8cIlKj9VrQQyiqUH9mrOPm0DgcN8YsXoLQ
-Ix1HAMY/ArKCdiyk5PDYHD+6qo1dlOPItIXIG0XSkJT02yR5qEg2EqyRHYyjzyrnyEqK8oyhTEgj
-7bFJo13SI2EwzCdDhDP4yXKWtKxYLWWJsVu+L5e6rFkv4bezX9pSmDd0XzdgZkwa7SJnFDMNMX35
-TFdGM5jE5GU1o4kn1WDzmXbg2TaFaSZrgvNks+ymOL9Jy3DesGUiSd5wmEhGt5SiHUipp+naCZL7
-6ZOV+WyixMJhT1MKlJ+CFCP2nmexf9plCZZbJWT+3Cm7MJIxSfGcp0WTglGC9CtL+9RERz3aT3pm
-FFeiuShBHcqNN75ToqjkaBhXqr8XJnSPIC0oHP2JU5FqdKQ2g5jyLNerfgo1qDolKTlMmsqTlrJa
-Km1OAmOGCKa+1KkstRBEUdDQpUpqoEk1KlF2ei2fftQoYyVrSFERUK9aQp4tRakmbXrTqtbUpXD9
-oVw1d9UTZLWiXO0jWnn61Y7xca5mJWxhifpXsKr1IWxV6kQPitc1GnZOTcVqFhRq0Lxmdqp6palb
-L5vYxQL0nkA9rGnVgql9FvWoiu2qX9uqVWxVtrNP/em6lsdZ2t6VbE9ap1B9y9qS9jWwwS2uzvD+
-OdmFDjWoIF0tcZ+7VqTWFLjMpS5Ri6krsaoJpt6M2hFLK7bGuha6DAPsqSi7XNSmV73NDa1xVSLe
-1xLUqlaLbViWCF7vJu27ns2pe8k72rCSq6z3XW+B22ve8rZWvuM9LW/xm13LPo2q9mUufScU3+gm
-OMCiDRtukytVEIcYsRuO44I1LNz5RrTCytXvfo/G3wnTNsOM/S98S+zED1vYwS0WsWxxGkLMbjXF
-DWbvhV185CS/GMm9ky6KOywmHM/xxz7WMY97bFbn3vjENR7ulSVM05QumcljXnGMabwnGysYylO2
-spG/TOUqo1fLa35vl4ksZ7uyeMRmrq8akav+5OI5+c5sFlRaezpgA/P5zXDGLZ05bOc0e5nRD/Zz
-mfscHWYiQdNKAK6n4wfAxSTi09wk5zipqctunvqct1T1L8P5i1GLLtTsdMRBrBvrHNoE18fEL6dH
-CexgC3vYxC62sY+N7GQre9nMbraznw3taEt72tSutrWvje1sa3vb3O62t78N7nCLe9zkLre5z43u
-dKt73exut7vfDe94y3ve9K63ve9t7SBkNdH47re/9Qq6CAP63wQvuGZ2mYneFoPWBm+4w8VUWiMB
-5IIPr7jFX2a/YCZ8zxfvuLnf1VB5QcnjJDd4YTKucN3xuuQsb7nLXw7zmMt85jSvuc1vjvP+nOt8
-5zzvuc9/DvSgC33oRC+60Y+O9KQrfelMb7rTnw71qEt96lSvutWvjvWsa33rXO+6178O9rCLfexk
-L7vZz472scG0vllD24rZzrW28bbtcl873N2uObUfqkQzJFaJPAO9Fm53W34/mcbO+7/t9j1ksfzY
-MiUO+DaXDPCLT9VpKr8yZnpQDM50JcmkyTOdNT5Enx8mxhAPaxApq/CULxjFV9S8kT9yhWts0zL4
-JVnX44uigl1481Cf8KsI3Kf+Er6biMXS18/+gy2JJfBzFw/Mc35U0NcXJxAh+4A1ENC69xdoER38
-34Mf+sZvF/5OP3yQ+QKAt8+14Z9/2dH+H3dnh4d/Als5f1MzMcdsCoj5SfwwqXVb/Mca6qd9WBaA
-R/J+1qddDHeAUZZy85c+mOcp/ndc5QMqGyMawrd5ACVx/8dYKrcsFQg7DAhEu6NAG7g9q3cU3RN4
-zBJV9jdwsXM/GQiCRuZWNWh7Msh3QmaAhoYSIyhja1ALbQJ/obM+L0iExvJry8d8LpiAuPdSN7h9
-3VOD3kdHW1AVsOOAxEclTySEIIQOHViF7XSFZQgUVFiGj8CCYpiGR+g8Axgt24c8Q9gpvTJbHjZg
-IjguFJQVZChbH2h/2rODJjgqxieDGTiFevgyFKWGAYOBj8gtVPF564IpLRKJgziAgAj+ieFniNxX
-fUo4LPcXhn2YEqMnif+TMYNHgKoWeTTYTGoifZzXeAsoivpXJ2f4PaHHik7oMZ1ni4yIi8fDib+I
-gen3g6pohE34gMa4cbO4ixJkh8m4d0HYi5Lniq1XjMqojcqgd2AmNXVnd3g3juRIYXT3dnGXjuZ4
-jl/zjboVjuvIjvB4d/NoUOiYd+qYj/Z4j+6IQXNXj/IojuAYkAK5j/yoZwV5kAa5kA2Zdg8JkREp
-kRNJkRVpkT73ZxwnjASpjwCJkIP0jv3Yke34kSAZjww5kPQ4kiSZkipZkhOkNifpkOWIkjQ5kzZJ
-NqyXi9uYeIrXho8TZtTlCjnEMfn+Z07jN3n3hIuC1ZNKeY2JiD6Zs0gC5iWzliav+Inv51vKx3wo
-WIrTV3uh2IqC9zjZN5ZL2DBgSZW+iI2GBpTT2IwmtpajqJSGIY232JRbuQ1myZZoKZZZmTt8ySV3
-ggapWEHRAJjU2JaL6YVMKYepMpe/GJlH6ZTI2Jdu6ZRcuZGQBJePqTCTmYRG2XyO6Q52Ui5QuJn7
-sA4amC2XOYeJCWukWVugeX2y+ZeiGZSO0ZrncpdGWYKwOZq2mV94SXwzEyymCULIo4u0h5rt95ZD
-uZuuyS2xSJuNeZZ3WJlhBmRQBAhCGVrLmRfGCXF1yTyg2ThkQlZ5eJ3lWYipOZ3+UKmd/uSDrwmf
-ciSY76kuacmY+Hk9lWmEwumJ8BmDSBl9/zKgpEmI6CkjGcOM/MmN3QicnRmX0OBpuvmW3GlD4jkr
-QEmUFuqfHXokUjkPGtoYDSqd+meiE+qMehmf0ZmQComTHtmScSWTMWqjHPmSMPmPMhpRGemjMYmP
-N4mjM0qjMHqjLkmkL5qjIPCjLXqhLqqkSWqSQXqkSFqTLHmlVpqlIrmkF+mlXwqmYSqmY7puiEim
-Zzogj4GEaMqmAIIQmtmmcTofbyqhcqp0GSlD1gCndvpvuqYldSU3dOqkfJpun/VFt1md5sFQjOKn
-hFpu+dObKVMXUnSMx5AfDBX+agfqqH0qQQtkCrMZf81gqBvnmemBTZtacuCyp98yFbyAD/NJSLiD
-p4dKoSuHqu62qJHqlpTYJ5AgcvKBqbfqclroUOUZBynoFP/pHrMqrI8KL2CErB1YQPHBrM06bjwJ
-lxsDJCkkqgD3WNZ6Ro16lT5gq0JCnBPGrfs5SerJcaOKm+BaH+4KC5kkZoR2nTTBrixToKCESTwK
-r2mqkatySi1lr/uJr7nFpJ6kooMWpf8KsHpErwQraed6sIAKLez6SQHrsHAjr6wQsSpGMzzIqp0U
-ZfwKR9W6sfzRsarwsXnWrYDJryurohjbWSibsvohs5MmaBI7se45qQhLq5L+YrIiZLM3ix85i2e/
-oRMHJLJesmfoArVPyWqldnivNrW1hGqvhk5Xi7VcW05ei0u9JrbKNLbS8nioyE1bC7bAtLYIt7Xo
-BLfmBLdWW7Vz20vq9E2mFrZ1u2qihrcdRHq19Vj5CoaFVqIMC2kAdq/U57KWqGh0hWBJu2WG67Q6
-y11AO6WEq6O71WjIhbRSBaubG1OVZrH7R7lAhLhyGWmLO4MHtmOUhoDqhWaJO7mru34YorlBC1mV
-Frr8RmWf61K9q7uaRaO5K1m26xKzq7qKa7CM+7qu27nadVaWC4GnCxXKS2HG+1CYm7nHG717FVnC
-Syuje7mlq0XIK7DUO2T+6Luwvhu97gu7iya7qVu97Fu5khtZ5ju+2ru94uu8v6ux1Oe/BUG8ema8
-A+y9T8Zg9suZCGqZjtu4pfm4wUu/68u8FqzAFwa8H7bBjgZVyAi+vDuo8xvAIVy/F5y++Eu7dZaI
-wym/sQvDL6xc2IvBLFy7C6zBJfxECPV9BIZe+ru/CZy96DfEWHm/DDxGFYyZ1luqcfa+EPy8MQy6
-SsyqXLbCPeti5fq74gq62JWtSMTFwavFUgyPFShlKVxkV7y8ienCkPvEEhzBEkzDS4zEBaq+ZXxp
-+RtopEs1MQYwCIzAQJzEZ1zFBPq/8evGiOzEWUbFR4zChZzG5bvHkoz+aWRmyZRsw5mMxRl8w51M
-sYcMvYrsZqFMwiq8xpp8yptcyavMynw8yXrcyqksy7d7x5D8yA46ymScyzKcyKUcySfsyWpMy5Z2
-yZjsyrGMzOBoxlYcsrXsyMHMum28yKSsyz8cub9cw8Kczc1MzK+szHl8zMX8zXVcuNh8uIT8zJ/c
-utUsvVHMyxTszA3MxOWMw8mMx+BcxOIczsY8y9s8zOZsy9DcvOv8zrvcy+zcgI0sz+RsugBdvPic
-z/Z8zxmSoqNT0aq4a1JiI92Q0bm2aqeqt3cb0qk20q1W0iYttbR4ax3N0RsNBBdNQ114QjCNQzLd
-AjRttDmt0zvN0z1u7dM/DdRBLdRDTdRFbdRHjdRJrdRLzdRN7dRPDdVRLdVTTdVVbdVXjdVfVBkx
-+APSnNU5bZaaCsVfPdQnR8TkJwlnTdZAnSwXJIidutZBHbhrqpqnuKpx/a9c3RdvndZ43dO+pCSY
-E9gqF8bNWgAAOw==
diff --git a/Documentation/DocBook/media/vbi_625.gif.b64 b/Documentation/DocBook/media/vbi_625.gif.b64
deleted file mode 100644
index 831f49a02821..000000000000
--- a/Documentation/DocBook/media/vbi_625.gif.b64
+++ /dev/null
@@ -1,90 +0,0 @@
-R0lGODlhKgPIAIAAAAAAAP///yH5BAEAAAEALAAAAAAqA8gAAAL+jI+py+0Po5y02ouz3rz7D4bi
-SJbmiabqWgJs475LLCt0fdy4oeN9/QPuEEFZkXVcJZXDXNP5pC0TgGrOCqVMidhAVdqVbLmx73Wc
-FXfNabGFzfbG3Rz0bDO/2G1hzJ7o8ceT56dB+Gb4JciD16fnh3VI97bmOCE4tyhVUSbHKOlg1xnp
-6aWFKDfaecrqQlrK2vqK2bjImPFaiLuKuxvY+2HLq1tniHcLzFmWy6mnitxMeWs5iaZo0xZhTahj
-rdzXHa3m6Eod+h1+LW7MXpx83P7962y+ju4O//5oGr8PHUvs36VjoCBsujTsxp5t0MIB1MZLYb07
-CBt+QlWRHz/+Zto62NLYD+Ouj7Q+ZlMj0J80kCr1iaSHT6WmeAXPAXOVzNs0hw8fHAwzkeLATz9E
-xVo2qCa2o7AA9Wz5cmXIgFAhKu2Yb2q1rFSrDmUZFeUgrQaLdhWriFZKGKt6LNTSlopXthevrIUB
-d9rSp6FGcbnLwCRYe2ELo+VK+CxEwF9XkoypeCtZn05dTiqlNupMxnyWxXkL17OVtHz7loMTdO+4
-pGsMsz0dKbVcyK7LXsWbyKSweTA95qatDHho4T7TqqsdWN1toaFbExNMHMkTzimgR2cSZfpgI9qt
-T8aePbz4IQebeLcsZDz56ecjv2g/9z37+fTNd6+vPb/+/fz++/v/D2CAAg5IYIEGHohgggouyGCD
-Dj4IYYQSTkhhhRZeiGGGGm7IYYcefghiiCKOSGKJJp6IYooqrsjidyrAh9yL+K2nng/31WgjjtzN
-mKOO8lFHxhlJxRjkkEY2tloWy51k2mxAVoaQQkImRiRuIyEmD5ZIomeVYMLIZhMkS6rWm4vJecZl
-cWBsRomUz+Vlymg4bWflYnGWo5FOGZ02FphPYmbkmHQmRxRSgzJXpntl/UlmcIca5ItvilJJx2OS
-TkrZo5k6CgemfBDFKJPF7ZRTIZsMgxUip4qKKFN5UropSKD54xasW9p6a65VBiYmb/dc2qZuwMaH
-laXvZEb+FbKPCKpkm68KutBoTshZWpN6MRqtm6H+8ZmTulabqplhXikuNtBhgqqnM6SLa7jE2nZd
-rGzK5CeUqMxJq6l2YavvTn6yGVG7zGn77aZgvOvuruvGexnCndXLq5YCC2Vsmg2LUzGcTSm8r7fg
-0pUKxMgwdOdY/O4JaMkFf/pqyiv/Jau9CY/asqatOlwnzuM6JvHMOsPsZaQZ/3zzV0NfdnS4HL3c
-KsBZpnIk01NCHbXP1o4MsSjgyAzp0xsddzHRHqOz2289d83wmb46e/aibauZNhXGMWuz3KjNG6Vz
-+fooHY/p8Q0ejYDL6PeO9hX+4+DVsRr4DjByPMLjE5v+ILnUJ1Qe9t+Cb855j4d/jrnVfSuOQuii
-N+5555qrbjjrrTt+Y4uyz0577bbfjnvuuu/Oe+++/w588MIPT3zxxh+PfPLKL8+87rWGYLqI0TdP
-ffWwM249oXKDgC/y02cPfvgkkPJ97t137075HKovfvvuQ1KXh9zKJ6V37A7P/vv6739Oa0BFnoRK
-QG9+2PlJMLDnu/zxb4EMxJPJ/DLA/sXvF0EogsgG5hQDkupeCOydAhkIwvcdAYJeqYdfymOMCvLK
-Swe7yKqgkLU4dZB3AaRbCG8YwhrOEGazUaHJNuKboqjQaRBMSDrqBkOu4W9uTAQbDp8IRSV2jFtm
-2Y7+thwIDyzi64VIBKIMvQip+/Gwit5Tkw2jiMbsGcVRPfyhBTdGq7gY6ovoG1UL6ximJSwtVLjT
-YRr/mMZZFctJRZSgLswiR73gMWcsqw0Jx0a8DwJyksAj4CCjRr7T2aSCiQTiIiMGsvg8UorBkyQl
-T7k7S3aNXQJEm2lWxcl9bRGFnWFM2TAIyuOZEpUpOqNHLhgMX9ahXqq02xZTQrCdRQyWdpolq+Yk
-uTdqMoG8BOEnZSSsHYLRRmukFAnFGKOA2ayVsBjhNkUgTVcab5fVNNE1F5fNk33wnY2y2iOBWbQ2
-8rFj9axLNBmZy3W2c4H0vFwXcTmUeXaxmBmUlf3+LkmSdJprn5kb50AvWruCUu6g3gKNQrtZmns+
-dJUU/WE/6bjRgAIUoyx1J0e599I0eNQ+INXVPaEH0ZTeAZzE2QI7WwrU7Hw0KzNdT00rOkqckjSm
-9jynUvMJyaBKVX5MDSJN9jHUj+UzqTCdGtWcOECJyAmf8CqSbWDTxLSiVa1MZA1b5+bWt5ImZHI1
-Dj2YZddgiSyvel1rXc3w17bSNbCiIWxhDUsGwyoWbNdYrGITO1jCJjatRXIsYs/gV7betbJkhZtM
-ndqChkaPJ6fYTdk2g9pyQUmVrJVJQDS6Qnak9pBX1RxXxyfa2o4LmoG7LW6nVdJjgfa3imzc/Ez+
-K9ubKNdiuWytSJz7XKbCliKzxapuE+fJ3k5wHVOoX3AB4tvIAYKnxEUp4Yp7Xj5Od6LLtS5tmYtQ
-8Lo2uq5Fbns5+N7Xei68T82ufl3J2/Tyt78Bxm6BS5fb9HJ0vXI57X2jcUv50pe7842uffOLX/f+
-t3UDPmAS59Xd8X63MR32sD9tO1zxfti4y0phcjEMYdV+dsISpnB9XfzgVuS4xgberk79S+Pdphid
-CRbwkEML3KpKmMH6OC6OYaxjKGtVNdDlMYn1e2ENZ3jLQdbuFxe34grL68hdRa+RyaviQo02g51F
-kpN74WApV0rGFumy0sQs3yxzOcpatjOY/eX+Zbols06wCXSbrwzWPyt5w9hdsHQfHVM0L5POMfPz
-mC09Zj3HWM6XZPToFo3nT7Nv0F7e3KhJ+WNHa5rPe04opUkN4FDf+cZwfnGfWY3pH59am2UGda51
-PZ5dj7glb+4Xp5d66yl3VNax/nVzHx3nZM9ZuCiutrV7vN9gZ3t1xW7xjqct7YoK2dlUZnasV+3q
-Y2cqwsL2tY2vLerrDfu68ea2t40dbmS32nIzfreVkYblJ+d73d8GOLxLzeFtHzzhC1e0qgW+705H
-fJrlJveyLb5sdIN74gSnNsM/DvJ6N1zk2H5dt1Vla45v8tWofjbG+01hjUt80wO/dMgRXvL+nOsc
-CHM1Qs/fw9fhkEtMmrBhovMW2Mn+Vel1Zbpcnf50r7KN6CMpOj6DjoSfZ/3o1dG6Erz+da5Pdexk
-L7vZz472tKt97Wxvu9vfDve4y33udK+73e+O97zrfe9877vf/w74wAt+8IQvvOEPj/jEK37xjG+8
-4x8P+chLfvKUr7zlL4/5zGt+85zvvOfx7sNrXfzzpC89gyQB6zqbfvWsL9Bh7xgyNbd+9rT3zxwr
-3aly1n73vAcdMw7rxt4Lf/iE4+LX2rJH4it/+bLNvSI7JXbmS3/61K++9a+P/exrf/vc7773vw/+
-8It//OQvv/nPj/70q3/97G+/+98P//j+y3/+9K+//e+P//zrf//877///w+AASiAA0iABWiAB4iA
-CaiAC8iADeiADwiBtoc4n+Y6FChvFYg6qaOBG/g6HNiBq3OBE7gua1I1FCd1JKhsXkVa4jaCPRRD
-XoOCKUg1MMeCtVQZ0RdVZQVD/+I1dzImWsMT0AKDUmeCR3I3HHOELXdSahMoP/g0n/GCUdKETvgn
-5MMnJ3MYX4VFRQgoUChIboMmybdSIHOFYqhSfQFoJlWDQGOEYjMLs2A5b7iC6kQzaCJ6ayhLX6VN
-JONAgHVUdSiHu2KFPoaHD5QykrZDsYEq3VQSUzQ5qzUyMniDOTiGNoeFGPE8/DZjQjj+XzhIiXfm
-ibymegeFLBqkiZFYM4XoMXqjiqNHiskSikqIKIX2iDA3K9mSJ9QiiZmAiq3YhrIIjCoYjOrFilQo
-dGamibzoMlxoViozBrhIg8yojDOYjM6hi9XoXZcohf/whVaBWYi4LZXQh7WYhNsiil9Gi6eIe4lY
-KsP4Um6yV+04jKVIV7U4ilVIVKkYKzXGUAZHS3QoGbEniRv0j/tYWpmojqT1h+5yTANZaY5Whc8g
-Q8QEJ/AIjlrTi+aIMkn0M7lgKAupPQTTjWiIexfpDBZhhp+4PQ/Zj2TYUNpYh81CkRsJezKYSUt4
-hi6piDBJkuOYkji5ks5nSUA4JZz+uI1KMpPHyBIjeTVqBpKvcYNRmCTRCJBNmYtPaZV22Ip5cHv8
-xpVEWJVQiZRMKZakYZRS+HNkyYRaqJYtaIRS6Y0zGI/zRmlEJoIKFoIeaIF6mYEg6Jcf+JeNlpd/
-Y0qFGTsY2JeCGZiKCZiNuZeO+ZiMCZnnZZikg2CWaVCYiWSaWV6I6XB8mZiRKZmiGYGlaZqniZqp
-qZqryZqt2WuDOZl4uZikKZux+ZmzGZq5WZu2mZmc2ZueeZm+aZfC2V+wyZupZpy0eZu4uZzHuZlE
-OYUK85UlaJA6uJTSuTXU6IvTeJbwpUw9CDluKTZAWZ3N8TZiWZdulZ7UaY9s6Z3+NqidDjmNmFiR
-ntAtKRiI9qknh+GFgoh842iTqvCR7QmWDmmI79mT6hJKCgpVBkpm5RmewQWODRqSP5mTMWmhFLow
-XyOPzdBCC/VfBVmJBqOS5BlfIPomJeqOGvqd40mX71gL53km8RQscdOi6siRCHqiOMqNDGouwCSi
-TUKCSXmUYLSfRzmHYYmeD3mK98meI+qLKgqhUbqWBEqIDpqhUOqS63mOXfqkPJp6SgpgF+RgTnNv
-6Uil8MiOKcpr9AhHzNgsUjpiSZMRXGqidzqCV7c2ERqkVLqicroXdEozb5qQZNSeikimiSiROEGk
-YMhm+FifPTo5v7dPGNkyWTr+pzJ6oQ6ahy76p16KqSy6oYLqp6DqpTB6qqU4oeeIkBjzhDv5iNMZ
-n1NapUlKq/DplOT4P1+6qTwqXbEoqp7lqakao5qKqz66klwqTFQkWJAzV0Z3V31KosT5msmpm7up
-nMH5OcCprdaKrdn6m9yqU5W5reK6meUKms05mteqruwart7aru46rncZr99qr/farelar/mqr+/K
-nPvqr//qmgNLsAVrsAeLsAl7O8ansNP3U9ZjKaHasID0sNxTsc3Dbi86sfxzaPzRsZOUse62sR9y
-Ho8BI+RUp1KhhlMVshc7sgMSG8N0pUGZi8HET2KRYUxGSS37sh60jMuCZgD+Sqgn6U+xtLLTJqIS
-5bInEkD7+LE9qyASQShBCBX3g0j66KHFZbRDS3CkhkfQtLQu9UqGKrJQmyD+s1O1MpciRrYn9opm
-xkrPMkO0VEVqe7QNdFlm2yIFpoxusap1ezO8lTWdFJVu25U3qjKpeDBhWyI1BKx6CyJJJWltyahW
-dCrRgowf9kKH26s3qXrSAkV+BLm086EvKaYNirIZpyqlK2Lsxbmiij5xG7qjKzwh9oxA8k8eCmtf
-m10+pTFXyrgkEry0GyDd5Q2ykbtmtE1DtFN2YUGY2ranyjzDq3ePi05PO3U+IEzF6rsV8byg25mT
-BpJS+0aryqnTe33mC1P+WUVv+iYE6otUMzss4utNpuu6yGlN6auxWWtUMbFGWZW8S6Gza1hiXHJg
-w4lD1Jt38EtBNOW/NMdN+ysqBYwwFDwXB1ycxCsgDGxV/du+7ssdHAyhFtwuJFy/Ioy4GuyxEjwQ
-7OtpMxfCLEwnJvwyNGxTD6qjKkwjLvy++QjBPVy2UmTD0zTETYXCWqrD9MHDMexxuMbEAdxGAZwJ
-sNoCQOGH2MtZjhVZSWdZr7d0W9x00cqseAV2Z7VXz2pZYNx0XRxXSafGXRzGUwjHbwVZcxzHscfG
-39hEWWzHalXH2/saYsWrxYqSMnxxA6xyhoRviTxpyMqkV/Zy9+iPEMf+v+q2cqaGw8BSxEsGaZyR
-jWsWZmdmyM92xLOGyD9cyfdWc7iBN5Dsb678b6ZMyaWVcqjcY6XcbKfMySAGiqO8iUFMaJncaxh8
-rpucboucyoxMXTksybP2ygZnYzIXRrXsxLfsy3Wmy5A8wGH6Wbh8admMaNesusCMS+AMw7RcawUH
-wgm5otzscs8sy+mMzNW8cSjmzeNmzrkcaUr4yYFGzhh0z738z4c80PaLcvK8yo08nu68o84cy/qM
-0Adtyay8rcRcXsY8yW56buKsptPTzwkX0C6Xzx03zy1MzcccngxdcfDcbNE8yyatziSdbSFdzgX9
-yxqdaRxdZIpm0b/+iaY+PcgeJs2UEW3KjKeQGMmPDM2cHNHJbMv1DNKAbMpYLNKJ2kH1I9W5TNWk
-nNWwTHJ9M9SKnNDL7Mgq7YpevdTa/NJuUNRPjXNvbWQKt3NwPdc8nSNhjRdtTc9wqtQOjdZ+PclN
-jc4TrdBy/dV0bdcjp62SZNYEdtdr3RF6jdKH2s6VLYqN/cuCDdOETdYX2G6f7dmGfdg3F9c7gtex
-FdOXvNCWrV6sDZF3KNGqbNT6FNqKDWyiXdqkXdeL/diazdYnDdXsfNmuXWVq7duRDdznPNqJrdvM
-vdu8XdG4DWan3bypTdFlTdzmNm4ufdzTbN2FbdvFLN3OvdzkHd7RF93bJf3b393ZKZ3dSY3Z2AzZ
-3s3ZAhzd551mNv3Ozw3U5lHGpfPfl3NGA351Rmfgj6XHd7xYUKdZCR51rGE2vVJ1E04eAU45Fl7F
-1htMGv5LHN7hXZ3EIS7iI07iJW7iJ47iKa7iK87iLe7iLw7jMS7jM07jNW7jN47jOa7jO87jPe7j
-Pw7kQV68E+EQhqrAQs6aZmirzYzkQC4aAmmIygHlTS7kP0G3gRJ8VB7kAGCRbQB8uqflTu6Ci4jl
-ehjmPs7laf58XB7Fau6DR56aBQAAOw==
diff --git a/Documentation/DocBook/media/vbi_hsync.gif.b64 b/Documentation/DocBook/media/vbi_hsync.gif.b64
deleted file mode 100644
index cdafabed5c11..000000000000
--- a/Documentation/DocBook/media/vbi_hsync.gif.b64
+++ /dev/null
@@ -1,43 +0,0 @@
-R0lGODlhBwHJAOcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4O
-Dg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEh
-ISIiIiMjIyQkJCUlJSYmJicnJygoKCkpKSoqKisrKywsLC0tLS4uLi8vLzAwMDExMTIyMjMzMzQ0
-NDU1NTY2Njc3Nzg4ODk5OTo6Ojs7Ozw8PD09PT4+Pj8/P0BAQEFBQUJCQkNDQ0REREVFRUZGRkdH
-R0hISElJSUpKSktLS0xMTE1NTU5OTk9PT1BQUFFRUVJSUlNTU1RUVFVVVVZWVldXV1hYWFlZWVpa
-WltbW1xcXF1dXV5eXl9fX2BgYGFhYWJiYmNjY2RkZGVlZWZmZmdnZ2hoaGlpaWpqamtra2xsbG1t
-bW5ubm9vb3BwcHFxcXJycnNzc3R0dHV1dXZ2dnd3d3h4eHl5eXp6ent7e3x8fH19fX5+fn9/f4CA
-gIGBgYKCgoODg4SEhIWFhYaGhoeHh4iIiImJiYqKiouLi4yMjI2NjY6Ojo+Pj5CQkJGRkZKSkpOT
-k5SUlJWVlZaWlpeXl5iYmJmZmZqampubm5ycnJ2dnZ6enp+fn6CgoKGhoaKioqOjo6SkpKWlpaam
-pqenp6ioqKmpqaqqqqurq6ysrK2tra6urq+vr7CwsLGxsbKysrOzs7S0tLW1tba2tre3t7i4uLm5
-ubq6uru7u7y8vL29vb6+vr+/v8DAwMHBwcLCwsPDw8TExMXFxcbGxsfHx8jIyMnJycrKysvLy8zM
-zM3Nzc7Ozs/Pz9DQ0NHR0dLS0tPT09TU1NXV1dbW1tfX19jY2NnZ2dra2tvb29zc3N3d3d7e3t/f
-3+Dg4OHh4eLi4uPj4+Tk5OXl5ebm5ufn5+jo6Onp6erq6uvr6+zs7O3t7e7u7u/v7/Dw8PHx8fLy
-8vPz8/T09PX19fb29vf39/j4+Pn5+fr6+vv7+/z8/P39/f7+/v///ywAAAAABwHJAAAI/gD/CRxI
-sKDBgwgTKlzIsKHDhxAjSpxIsaLFixgzatzIsaPHjyBDihxJsqTJkyhTqlzJsqXLlzBjypxJs6bN
-mzhz6tzJs6fPn0CDCh1KtKjRo0iTKl3KtKnTp1CjSp1KtarVqyQBYN1aVSvXr1C9gh2rVOxCsV4B
-mE2b0GxDt2TjtnWo9l9du2rrar2bl+BavQL3ApZLeC5du3j77g2MF/FAtIv1AoZb+Gfey5gza97M
-ua/ByJ4XI8b8+PHl0ZkrE6XsuCDr1xD5ip7d2m9pv6IZqxYK+zPC3g/T0mabGLdk4YEH7wYK3PZB
-yqyXSw/++3l139OzS4R+Hbtr7eCp/nv/bp18+PMKuZcfj7792fXm47ufz/52fd308zu/X3u/fv3N
-+Sfgf/MFaJ98BLpnIH4IJojegv0d6GB7EEI4oXYVdnfhgxoOyOCG4WXIH4jTidggiSV2KOGHKGa3
-oIUtqvaiijEuNyN8NUp344g5EqYef9H1KNePJwYpJFlEehjhkT7iuCKLTMZl4olRgjWlklV+deWT
-WWpJ45JgdrnVllCKOeaXMJrZFZpfqmkVmWG6SRWcRsoZFZl12hkWmzxemCdXeAr555lOgjnof4de
-tSOVG0KWaFl3GVponH52ZumlmGaq6aaY0pjmhJppmRqQbTaKm6gewgnio2uSOumq/jpO+qmDrE5F
-p6AtSZZeSrf2WOtEoZEmm2C/Astnn6CapKtjbClWZki95lhsbLcRtxmlHkVb47TBWcuYcGvxeiyj
-fp7kGbOJEZscStrGyK1T7bb4blPxojgvU4Hiulu+vto4Lpck3rvUoljCuq+npZp6cKGz0uovwwmX
-u3CRESc7sZINJyhwWbJW7PDFXGZM4MZI1WsvyCF7rDHKZYqMKMuSvmqwS5yOypHJAcP0K8k4z5xr
-RTz/C7DPLO2crdDPEr2S0R31rDDNQB/dMbISQ01R0FOT+/TPV0vtqtZVc21s0wjLLONFJG8XNdkQ
-y5z2UNy+TW3XbN8Ho9xBxa3z/to3lz0i3nljBPhbfG+UZMoqG5db2+KJ9O7gDDHd99dUstpscsgR
-x6CzqC0O0uN70z05xVlHdNpwgvUHGWrFef5RppGHPjawNddue3nB5nYufsKmu/vrhL/3kuRqq1Tr
-6pd/G+6HymGLdvC7Dl+46cYD7aywoSleXGOtj5RnnZALP3vx7Bb2J/iyk6++subTZanz2ZJ2te2R
-st8+9NaFHx/x1Jff5GFz0Z9/+Dc3c9EnSK4ryfLG1z89GaY6AjwQARvnQLfBr24XpFrizGSk+tlv
-aOJbXwULxj3/gTB6DBwhCD2oQLBtkIR66mAEVTe9AqqQhCzMigvNhsIbrnCG/m6ZIAB9+MPqwfCB
-IryhDI14QiQ2kIiUyqH3dqhBHtoJfSZs4gu16CYsGpCKYDyinLz4QS5W8YwcjF0WkxbCJxKRjC0M
-oxnlmCU46tA19BPiCO04xZjM8IBq/GL63hjIMloNitiS4uv+aMUxRk5/ihQXIhMJSUaiUUzgq6RM
-LEmhR5qLk2LsoieVBco5YnKUCiwlG2OIyqyoMoNpPIsm/TjJRMKya698JYZiB7kELq2W6OvlLT8H
-TF62MJfM+R3+lnnIAB5zk8zBHOZks7/BqEuXwXwmLS1DzestDnmNud5MsqlDZPKGWMkzT+9CBc33
-5PGd8IynPOfJwkilLp37/gniN8dZyDgOcienCadudnc6anavnT30p/SKokvH9fOO/+RmqxIK0YUi
-EosBNVz2tnnRR9KzUxyFYjAzqpHehZSQbdxYEBEqUhcVM0WTbGhNZBor+7xNj8SMaT7TJc1Tgcug
-Bf2LNZnlKODp1KYCbR64ujcZ0OBxe5FR3jAfqsSdNiujucMnPnl3uaxiraNI3ep3hro8161uNLbB
-G00fNk3abG+aAiXqcKqlGG8Oy6hgLang+HnUjERyiBFV4VpZitKa5rWEgKJjldgpKs5d9KOQjeym
-XkrSMdnzpYatpWY3y1l6NXGB3RlsZ9eDzp7ydKmnW1dAlTnaQ94zruEkS2tUnfra1iIUdRvlHueu
-iS7N2daic1VncEEz3N/6MbVyNU1TV0tUdL3VuF6aKnQhJdrpWve62M2udrfL3e5697vgDa94x0ve
-8lIkIAA7
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl
deleted file mode 100644
index 03f9a1f8d413..000000000000
--- a/Documentation/DocBook/media_api.tmpl
+++ /dev/null
@@ -1,88 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % media-entities SYSTEM "./media-entities.tmpl"> %media-entities;
-<!ENTITY media-indices SYSTEM "./media-indices.tmpl">
-
-<!ENTITY eg "e.&nbsp;g.">
-<!ENTITY ie "i.&nbsp;e.">
-<!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>.">
-<!ENTITY i2c "I<superscript>2</superscript>C">
-<!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>">
-<!ENTITY return-value-dvb "<para>RETURN VALUE</para><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>">
-<!ENTITY manvol "<manvolnum>2</manvolnum>">
-
-<!-- Table templates: structs, structs w/union, defines. -->
-<!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />">
-<!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />">
-<!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />">
-
-<!-- Video for Linux mailing list address. -->
-<!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>">
-
-<!-- LinuxTV v4l-dvb repository. -->
-<!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>">
-<!ENTITY dash-ent-8 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-10 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-12 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-14 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-16 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-20 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-22 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-<!ENTITY dash-ent-24 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>">
-]>
-
-<book id="media_api">
-<bookinfo>
- <title>LINUX MEDIA INFRASTRUCTURE API</title>
-
- <copyright>
- <year>2009-2014</year>
- <holder>LinuxTV Developers</holder>
- </copyright>
-
- <legalnotice>
- <para>Permission is granted to copy, distribute and/or modify
- this document under the terms of the GNU Free Documentation License,
- Version 1.1 or any later version published by the Free Software
- Foundation. A copy of the license is included in the chapter entitled
- "GNU Free Documentation License"</para>
- </legalnotice>
-</bookinfo>
-
-<toc></toc> <!-- autogenerated -->
-
-<preface>
- <title>Introduction</title>
-
- <para>This document covers the Linux Kernel to Userspace API's used by
- video and radio streaming devices, including video cameras,
- analog and digital TV receiver cards, AM/FM receiver cards,
- streaming capture and output devices, codec devices and remote
- controllers.</para>
- <para>It is divided into four parts.</para>
- <para>The first part covers radio, video capture and output,
- cameras, analog TV devices and codecs.</para>
- <para>The second part covers the
- API used for digital TV and Internet reception via one of the
- several digital tv standards. While it is called as DVB API,
- in fact it covers several different video standards including
- DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated
- to document support also for DVB-S2, ISDB-T and ISDB-S.</para>
- <para>The third part covers the Remote Controller API.</para>
- <para>The fourth part covers the Media Controller API.</para>
- <para>For additional information and for the latest development code,
- see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
- <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para>
-</preface>
-
-<part id="v4l2spec">&sub-v4l2;</part>
-<part id="dvbapi">&sub-dvbapi;</part>
-<part id="remotes">&sub-remote_controllers;</part>
-<part id="media_common">&sub-media-controller;</part>
-
-<chapter id="gen_errors">&sub-gen-errors;</chapter>
-
-&sub-fdl-appendix;
-
-</book>
diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl
deleted file mode 100644
index 7da8f0402af5..000000000000
--- a/Documentation/DocBook/mtdnand.tmpl
+++ /dev/null
@@ -1,1292 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="MTD-NAND-Guide">
- <bookinfo>
- <title>MTD NAND Driver Programming Interface</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2004</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The generic NAND driver supports almost all NAND and AG-AND based
- chips and connects them to the Memory Technology Devices (MTD)
- subsystem of the Linux Kernel.
- </para>
- <para>
- This documentation is provided for developers who want to implement
- board drivers or filesystem drivers suitable for NAND devices.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None.
- </para>
- </chapter>
-
- <chapter id="dochints">
- <title>Documentation hints</title>
- <para>
- The function and structure docs are autogenerated. Each function and
- struct member has a short description which is marked with an [XXX] identifier.
- The following chapters explain the meaning of those identifiers.
- </para>
- <sect1 id="Function_identifiers_XXX">
- <title>Function identifiers [XXX]</title>
- <para>
- The functions are marked with [XXX] identifiers in the short
- comment. The identifiers explain the usage and scope of the
- functions. Following identifiers are used:
- </para>
- <itemizedlist>
- <listitem><para>
- [MTD Interface]</para><para>
- These functions provide the interface to the MTD kernel API.
- They are not replaceable and provide functionality
- which is complete hardware independent.
- </para></listitem>
- <listitem><para>
- [NAND Interface]</para><para>
- These functions are exported and provide the interface to the NAND kernel API.
- </para></listitem>
- <listitem><para>
- [GENERIC]</para><para>
- Generic functions are not replaceable and provide functionality
- which is complete hardware independent.
- </para></listitem>
- <listitem><para>
- [DEFAULT]</para><para>
- Default functions provide hardware related functionality which is suitable
- for most of the implementations. These functions can be replaced by the
- board driver if necessary. Those functions are called via pointers in the
- NAND chip description structure. The board driver can set the functions which
- should be replaced by board dependent functions before calling nand_scan().
- If the function pointer is NULL on entry to nand_scan() then the pointer
- is set to the default function which is suitable for the detected chip type.
- </para></listitem>
- </itemizedlist>
- </sect1>
- <sect1 id="Struct_member_identifiers_XXX">
- <title>Struct member identifiers [XXX]</title>
- <para>
- The struct members are marked with [XXX] identifiers in the
- comment. The identifiers explain the usage and scope of the
- members. Following identifiers are used:
- </para>
- <itemizedlist>
- <listitem><para>
- [INTERN]</para><para>
- These members are for NAND driver internal use only and must not be
- modified. Most of these values are calculated from the chip geometry
- information which is evaluated during nand_scan().
- </para></listitem>
- <listitem><para>
- [REPLACEABLE]</para><para>
- Replaceable members hold hardware related functions which can be
- provided by the board driver. The board driver can set the functions which
- should be replaced by board dependent functions before calling nand_scan().
- If the function pointer is NULL on entry to nand_scan() then the pointer
- is set to the default function which is suitable for the detected chip type.
- </para></listitem>
- <listitem><para>
- [BOARDSPECIFIC]</para><para>
- Board specific members hold hardware related information which must
- be provided by the board driver. The board driver must set the function
- pointers and datafields before calling nand_scan().
- </para></listitem>
- <listitem><para>
- [OPTIONAL]</para><para>
- Optional members can hold information relevant for the board driver. The
- generic NAND driver code does not use this information.
- </para></listitem>
- </itemizedlist>
- </sect1>
- </chapter>
-
- <chapter id="basicboarddriver">
- <title>Basic board driver</title>
- <para>
- For most boards it will be sufficient to provide just the
- basic functions and fill out some really board dependent
- members in the nand chip description structure.
- </para>
- <sect1 id="Basic_defines">
- <title>Basic defines</title>
- <para>
- At least you have to provide a mtd structure and
- a storage for the ioremap'ed chip address.
- You can allocate the mtd structure using kmalloc
- or you can allocate it statically.
- In case of static allocation you have to allocate
- a nand_chip structure too.
- </para>
- <para>
- Kmalloc based example
- </para>
- <programlisting>
-static struct mtd_info *board_mtd;
-static void __iomem *baseaddr;
- </programlisting>
- <para>
- Static example
- </para>
- <programlisting>
-static struct mtd_info board_mtd;
-static struct nand_chip board_chip;
-static void __iomem *baseaddr;
- </programlisting>
- </sect1>
- <sect1 id="Partition_defines">
- <title>Partition defines</title>
- <para>
- If you want to divide your device into partitions, then
- define a partitioning scheme suitable to your board.
- </para>
- <programlisting>
-#define NUM_PARTITIONS 2
-static struct mtd_partition partition_info[] = {
- { .name = "Flash partition 1",
- .offset = 0,
- .size = 8 * 1024 * 1024 },
- { .name = "Flash partition 2",
- .offset = MTDPART_OFS_NEXT,
- .size = MTDPART_SIZ_FULL },
-};
- </programlisting>
- </sect1>
- <sect1 id="Hardware_control_functions">
- <title>Hardware control function</title>
- <para>
- The hardware control function provides access to the
- control pins of the NAND chip(s).
- The access can be done by GPIO pins or by address lines.
- If you use address lines, make sure that the timing
- requirements are met.
- </para>
- <para>
- <emphasis>GPIO based example</emphasis>
- </para>
- <programlisting>
-static void board_hwcontrol(struct mtd_info *mtd, int cmd)
-{
- switch(cmd){
- case NAND_CTL_SETCLE: /* Set CLE pin high */ break;
- case NAND_CTL_CLRCLE: /* Set CLE pin low */ break;
- case NAND_CTL_SETALE: /* Set ALE pin high */ break;
- case NAND_CTL_CLRALE: /* Set ALE pin low */ break;
- case NAND_CTL_SETNCE: /* Set nCE pin low */ break;
- case NAND_CTL_CLRNCE: /* Set nCE pin high */ break;
- }
-}
- </programlisting>
- <para>
- <emphasis>Address lines based example.</emphasis> It's assumed that the
- nCE pin is driven by a chip select decoder.
- </para>
- <programlisting>
-static void board_hwcontrol(struct mtd_info *mtd, int cmd)
-{
- struct nand_chip *this = (struct nand_chip *) mtd->priv;
- switch(cmd){
- case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break;
- case NAND_CTL_CLRCLE: this->IO_ADDR_W &amp;= ~CLE_ADRR_BIT; break;
- case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break;
- case NAND_CTL_CLRALE: this->IO_ADDR_W &amp;= ~ALE_ADRR_BIT; break;
- }
-}
- </programlisting>
- </sect1>
- <sect1 id="Device_ready_function">
- <title>Device ready function</title>
- <para>
- If the hardware interface has the ready busy pin of the NAND chip connected to a
- GPIO or other accessible I/O pin, this function is used to read back the state of the
- pin. The function has no arguments and should return 0, if the device is busy (R/B pin
- is low) and 1, if the device is ready (R/B pin is high).
- If the hardware interface does not give access to the ready busy pin, then
- the function must not be defined and the function pointer this->dev_ready is set to NULL.
- </para>
- </sect1>
- <sect1 id="Init_function">
- <title>Init function</title>
- <para>
- The init function allocates memory and sets up all the board
- specific parameters and function pointers. When everything
- is set up nand_scan() is called. This function tries to
- detect and identify then chip. If a chip is found all the
- internal data fields are initialized accordingly.
- The structure(s) have to be zeroed out first and then filled with the necessary
- information about the device.
- </para>
- <programlisting>
-static int __init board_init (void)
-{
- struct nand_chip *this;
- int err = 0;
-
- /* Allocate memory for MTD device structure and private data */
- board_mtd = kzalloc(sizeof(struct mtd_info) + sizeof(struct nand_chip), GFP_KERNEL);
- if (!board_mtd) {
- printk ("Unable to allocate NAND MTD device structure.\n");
- err = -ENOMEM;
- goto out;
- }
-
- /* map physical address */
- baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024);
- if (!baseaddr) {
- printk("Ioremap to access NAND chip failed\n");
- err = -EIO;
- goto out_mtd;
- }
-
- /* Get pointer to private data */
- this = (struct nand_chip *) ();
- /* Link the private data with the MTD structure */
- board_mtd->priv = this;
-
- /* Set address of NAND IO lines */
- this->IO_ADDR_R = baseaddr;
- this->IO_ADDR_W = baseaddr;
- /* Reference hardware control function */
- this->hwcontrol = board_hwcontrol;
- /* Set command delay time, see datasheet for correct value */
- this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
- /* Assign the device ready function, if available */
- this->dev_ready = board_dev_ready;
- this->eccmode = NAND_ECC_SOFT;
-
- /* Scan to find existence of the device */
- if (nand_scan (board_mtd, 1)) {
- err = -ENXIO;
- goto out_ior;
- }
-
- add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS);
- goto out;
-
-out_ior:
- iounmap(baseaddr);
-out_mtd:
- kfree (board_mtd);
-out:
- return err;
-}
-module_init(board_init);
- </programlisting>
- </sect1>
- <sect1 id="Exit_function">
- <title>Exit function</title>
- <para>
- The exit function is only necessary if the driver is
- compiled as a module. It releases all resources which
- are held by the chip driver and unregisters the partitions
- in the MTD layer.
- </para>
- <programlisting>
-#ifdef MODULE
-static void __exit board_cleanup (void)
-{
- /* Release resources, unregister device */
- nand_release (board_mtd);
-
- /* unmap physical address */
- iounmap(baseaddr);
-
- /* Free the MTD device structure */
- kfree (board_mtd);
-}
-module_exit(board_cleanup);
-#endif
- </programlisting>
- </sect1>
- </chapter>
-
- <chapter id="boarddriversadvanced">
- <title>Advanced board driver functions</title>
- <para>
- This chapter describes the advanced functionality of the NAND
- driver. For a list of functions which can be overridden by the board
- driver see the documentation of the nand_chip structure.
- </para>
- <sect1 id="Multiple_chip_control">
- <title>Multiple chip control</title>
- <para>
- The nand driver can control chip arrays. Therefore the
- board driver must provide an own select_chip function. This
- function must (de)select the requested chip.
- The function pointer in the nand_chip structure must
- be set before calling nand_scan(). The maxchip parameter
- of nand_scan() defines the maximum number of chips to
- scan for. Make sure that the select_chip function can
- handle the requested number of chips.
- </para>
- <para>
- The nand driver concatenates the chips to one virtual
- chip and provides this virtual chip to the MTD layer.
- </para>
- <para>
- <emphasis>Note: The driver can only handle linear chip arrays
- of equally sized chips. There is no support for
- parallel arrays which extend the buswidth.</emphasis>
- </para>
- <para>
- <emphasis>GPIO based example</emphasis>
- </para>
- <programlisting>
-static void board_select_chip (struct mtd_info *mtd, int chip)
-{
- /* Deselect all chips, set all nCE pins high */
- GPIO(BOARD_NAND_NCE) |= 0xff;
- if (chip >= 0)
- GPIO(BOARD_NAND_NCE) &amp;= ~ (1 &lt;&lt; chip);
-}
- </programlisting>
- <para>
- <emphasis>Address lines based example.</emphasis>
- Its assumed that the nCE pins are connected to an
- address decoder.
- </para>
- <programlisting>
-static void board_select_chip (struct mtd_info *mtd, int chip)
-{
- struct nand_chip *this = (struct nand_chip *) mtd->priv;
-
- /* Deselect all chips */
- this->IO_ADDR_R &amp;= ~BOARD_NAND_ADDR_MASK;
- this->IO_ADDR_W &amp;= ~BOARD_NAND_ADDR_MASK;
- switch (chip) {
- case 0:
- this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
- this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
- break;
- ....
- case n:
- this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
- this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
- break;
- }
-}
- </programlisting>
- </sect1>
- <sect1 id="Hardware_ECC_support">
- <title>Hardware ECC support</title>
- <sect2 id="Functions_and_constants">
- <title>Functions and constants</title>
- <para>
- The nand driver supports three different types of
- hardware ECC.
- <itemizedlist>
- <listitem><para>NAND_ECC_HW3_256</para><para>
- Hardware ECC generator providing 3 bytes ECC per
- 256 byte.
- </para> </listitem>
- <listitem><para>NAND_ECC_HW3_512</para><para>
- Hardware ECC generator providing 3 bytes ECC per
- 512 byte.
- </para> </listitem>
- <listitem><para>NAND_ECC_HW6_512</para><para>
- Hardware ECC generator providing 6 bytes ECC per
- 512 byte.
- </para> </listitem>
- <listitem><para>NAND_ECC_HW8_512</para><para>
- Hardware ECC generator providing 6 bytes ECC per
- 512 byte.
- </para> </listitem>
- </itemizedlist>
- If your hardware generator has a different functionality
- add it at the appropriate place in nand_base.c
- </para>
- <para>
- The board driver must provide following functions:
- <itemizedlist>
- <listitem><para>enable_hwecc</para><para>
- This function is called before reading / writing to
- the chip. Reset or initialize the hardware generator
- in this function. The function is called with an
- argument which let you distinguish between read
- and write operations.
- </para> </listitem>
- <listitem><para>calculate_ecc</para><para>
- This function is called after read / write from / to
- the chip. Transfer the ECC from the hardware to
- the buffer. If the option NAND_HWECC_SYNDROME is set
- then the function is only called on write. See below.
- </para> </listitem>
- <listitem><para>correct_data</para><para>
- In case of an ECC error this function is called for
- error detection and correction. Return 1 respectively 2
- in case the error can be corrected. If the error is
- not correctable return -1. If your hardware generator
- matches the default algorithm of the nand_ecc software
- generator then use the correction function provided
- by nand_ecc instead of implementing duplicated code.
- </para> </listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="Hardware_ECC_with_syndrome_calculation">
- <title>Hardware ECC with syndrome calculation</title>
- <para>
- Many hardware ECC implementations provide Reed-Solomon
- codes and calculate an error syndrome on read. The syndrome
- must be converted to a standard Reed-Solomon syndrome
- before calling the error correction code in the generic
- Reed-Solomon library.
- </para>
- <para>
- The ECC bytes must be placed immediately after the data
- bytes in order to make the syndrome generator work. This
- is contrary to the usual layout used by software ECC. The
- separation of data and out of band area is not longer
- possible. The nand driver code handles this layout and
- the remaining free bytes in the oob area are managed by
- the autoplacement code. Provide a matching oob-layout
- in this case. See rts_from4.c and diskonchip.c for
- implementation reference. In those cases we must also
- use bad block tables on FLASH, because the ECC layout is
- interfering with the bad block marker positions.
- See bad block table support for details.
- </para>
- </sect2>
- </sect1>
- <sect1 id="Bad_Block_table_support">
- <title>Bad block table support</title>
- <para>
- Most NAND chips mark the bad blocks at a defined
- position in the spare area. Those blocks must
- not be erased under any circumstances as the bad
- block information would be lost.
- It is possible to check the bad block mark each
- time when the blocks are accessed by reading the
- spare area of the first page in the block. This
- is time consuming so a bad block table is used.
- </para>
- <para>
- The nand driver supports various types of bad block
- tables.
- <itemizedlist>
- <listitem><para>Per device</para><para>
- The bad block table contains all bad block information
- of the device which can consist of multiple chips.
- </para> </listitem>
- <listitem><para>Per chip</para><para>
- A bad block table is used per chip and contains the
- bad block information for this particular chip.
- </para> </listitem>
- <listitem><para>Fixed offset</para><para>
- The bad block table is located at a fixed offset
- in the chip (device). This applies to various
- DiskOnChip devices.
- </para> </listitem>
- <listitem><para>Automatic placed</para><para>
- The bad block table is automatically placed and
- detected either at the end or at the beginning
- of a chip (device)
- </para> </listitem>
- <listitem><para>Mirrored tables</para><para>
- The bad block table is mirrored on the chip (device) to
- allow updates of the bad block table without data loss.
- </para> </listitem>
- </itemizedlist>
- </para>
- <para>
- nand_scan() calls the function nand_default_bbt().
- nand_default_bbt() selects appropriate default
- bad block table descriptors depending on the chip information
- which was retrieved by nand_scan().
- </para>
- <para>
- The standard policy is scanning the device for bad
- blocks and build a ram based bad block table which
- allows faster access than always checking the
- bad block information on the flash chip itself.
- </para>
- <sect2 id="Flash_based_tables">
- <title>Flash based tables</title>
- <para>
- It may be desired or necessary to keep a bad block table in FLASH.
- For AG-AND chips this is mandatory, as they have no factory marked
- bad blocks. They have factory marked good blocks. The marker pattern
- is erased when the block is erased to be reused. So in case of
- powerloss before writing the pattern back to the chip this block
- would be lost and added to the bad blocks. Therefore we scan the
- chip(s) when we detect them the first time for good blocks and
- store this information in a bad block table before erasing any
- of the blocks.
- </para>
- <para>
- The blocks in which the tables are stored are protected against
- accidental access by marking them bad in the memory bad block
- table. The bad block table management functions are allowed
- to circumvent this protection.
- </para>
- <para>
- The simplest way to activate the FLASH based bad block table support
- is to set the option NAND_BBT_USE_FLASH in the bbt_option field of
- the nand chip structure before calling nand_scan(). For AG-AND
- chips is this done by default.
- This activates the default FLASH based bad block table functionality
- of the NAND driver. The default bad block table options are
- <itemizedlist>
- <listitem><para>Store bad block table per chip</para></listitem>
- <listitem><para>Use 2 bits per block</para></listitem>
- <listitem><para>Automatic placement at the end of the chip</para></listitem>
- <listitem><para>Use mirrored tables with version numbers</para></listitem>
- <listitem><para>Reserve 4 blocks at the end of the chip</para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="User_defined_tables">
- <title>User defined tables</title>
- <para>
- User defined tables are created by filling out a
- nand_bbt_descr structure and storing the pointer in the
- nand_chip structure member bbt_td before calling nand_scan().
- If a mirror table is necessary a second structure must be
- created and a pointer to this structure must be stored
- in bbt_md inside the nand_chip structure. If the bbt_md
- member is set to NULL then only the main table is used
- and no scan for the mirrored table is performed.
- </para>
- <para>
- The most important field in the nand_bbt_descr structure
- is the options field. The options define most of the
- table properties. Use the predefined constants from
- nand.h to define the options.
- <itemizedlist>
- <listitem><para>Number of bits per block</para>
- <para>The supported number of bits is 1, 2, 4, 8.</para></listitem>
- <listitem><para>Table per chip</para>
- <para>Setting the constant NAND_BBT_PERCHIP selects that
- a bad block table is managed for each chip in a chip array.
- If this option is not set then a per device bad block table
- is used.</para></listitem>
- <listitem><para>Table location is absolute</para>
- <para>Use the option constant NAND_BBT_ABSPAGE and
- define the absolute page number where the bad block
- table starts in the field pages. If you have selected bad block
- tables per chip and you have a multi chip array then the start page
- must be given for each chip in the chip array. Note: there is no scan
- for a table ident pattern performed, so the fields
- pattern, veroffs, offs, len can be left uninitialized</para></listitem>
- <listitem><para>Table location is automatically detected</para>
- <para>The table can either be located in the first or the last good
- blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place
- the bad block table at the end of the chip (device). The
- bad block tables are marked and identified by a pattern which
- is stored in the spare area of the first page in the block which
- holds the bad block table. Store a pointer to the pattern
- in the pattern field. Further the length of the pattern has to be
- stored in len and the offset in the spare area must be given
- in the offs member of the nand_bbt_descr structure. For mirrored
- bad block tables different patterns are mandatory.</para></listitem>
- <listitem><para>Table creation</para>
- <para>Set the option NAND_BBT_CREATE to enable the table creation
- if no table can be found during the scan. Usually this is done only
- once if a new chip is found. </para></listitem>
- <listitem><para>Table write support</para>
- <para>Set the option NAND_BBT_WRITE to enable the table write support.
- This allows the update of the bad block table(s) in case a block has
- to be marked bad due to wear. The MTD interface function block_markbad
- is calling the update function of the bad block table. If the write
- support is enabled then the table is updated on FLASH.</para>
- <para>
- Note: Write support should only be enabled for mirrored tables with
- version control.
- </para></listitem>
- <listitem><para>Table version control</para>
- <para>Set the option NAND_BBT_VERSION to enable the table version control.
- It's highly recommended to enable this for mirrored tables with write
- support. It makes sure that the risk of losing the bad block
- table information is reduced to the loss of the information about the
- one worn out block which should be marked bad. The version is stored in
- 4 consecutive bytes in the spare area of the device. The position of
- the version number is defined by the member veroffs in the bad block table
- descriptor.</para></listitem>
- <listitem><para>Save block contents on write</para>
- <para>
- In case that the block which holds the bad block table does contain
- other useful information, set the option NAND_BBT_SAVECONTENT. When
- the bad block table is written then the whole block is read the bad
- block table is updated and the block is erased and everything is
- written back. If this option is not set only the bad block table
- is written and everything else in the block is ignored and erased.
- </para></listitem>
- <listitem><para>Number of reserved blocks</para>
- <para>
- For automatic placement some blocks must be reserved for
- bad block table storage. The number of reserved blocks is defined
- in the maxblocks member of the bad block table description structure.
- Reserving 4 blocks for mirrored tables should be a reasonable number.
- This also limits the number of blocks which are scanned for the bad
- block table ident pattern.
- </para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
- <sect1 id="Spare_area_placement">
- <title>Spare area (auto)placement</title>
- <para>
- The nand driver implements different possibilities for
- placement of filesystem data in the spare area,
- <itemizedlist>
- <listitem><para>Placement defined by fs driver</para></listitem>
- <listitem><para>Automatic placement</para></listitem>
- </itemizedlist>
- The default placement function is automatic placement. The
- nand driver has built in default placement schemes for the
- various chiptypes. If due to hardware ECC functionality the
- default placement does not fit then the board driver can
- provide a own placement scheme.
- </para>
- <para>
- File system drivers can provide a own placement scheme which
- is used instead of the default placement scheme.
- </para>
- <para>
- Placement schemes are defined by a nand_oobinfo structure
- <programlisting>
-struct nand_oobinfo {
- int useecc;
- int eccbytes;
- int eccpos[24];
- int oobfree[8][2];
-};
- </programlisting>
- <itemizedlist>
- <listitem><para>useecc</para><para>
- The useecc member controls the ecc and placement function. The header
- file include/mtd/mtd-abi.h contains constants to select ecc and
- placement. MTD_NANDECC_OFF switches off the ecc complete. This is
- not recommended and available for testing and diagnosis only.
- MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE
- selects automatic placement.
- </para></listitem>
- <listitem><para>eccbytes</para><para>
- The eccbytes member defines the number of ecc bytes per page.
- </para></listitem>
- <listitem><para>eccpos</para><para>
- The eccpos array holds the byte offsets in the spare area where
- the ecc codes are placed.
- </para></listitem>
- <listitem><para>oobfree</para><para>
- The oobfree array defines the areas in the spare area which can be
- used for automatic placement. The information is given in the format
- {offset, size}. offset defines the start of the usable area, size the
- length in bytes. More than one area can be defined. The list is terminated
- by an {0, 0} entry.
- </para></listitem>
- </itemizedlist>
- </para>
- <sect2 id="Placement_defined_by_fs_driver">
- <title>Placement defined by fs driver</title>
- <para>
- The calling function provides a pointer to a nand_oobinfo
- structure which defines the ecc placement. For writes the
- caller must provide a spare area buffer along with the
- data buffer. The spare area buffer size is (number of pages) *
- (size of spare area). For reads the buffer size is
- (number of pages) * ((size of spare area) + (number of ecc
- steps per page) * sizeof (int)). The driver stores the
- result of the ecc check for each tuple in the spare buffer.
- The storage sequence is
- </para>
- <para>
- &lt;spare data page 0&gt;&lt;ecc result 0&gt;...&lt;ecc result n&gt;
- </para>
- <para>
- ...
- </para>
- <para>
- &lt;spare data page n&gt;&lt;ecc result 0&gt;...&lt;ecc result n&gt;
- </para>
- <para>
- This is a legacy mode used by YAFFS1.
- </para>
- <para>
- If the spare area buffer is NULL then only the ECC placement is
- done according to the given scheme in the nand_oobinfo structure.
- </para>
- </sect2>
- <sect2 id="Automatic_placement">
- <title>Automatic placement</title>
- <para>
- Automatic placement uses the built in defaults to place the
- ecc bytes in the spare area. If filesystem data have to be stored /
- read into the spare area then the calling function must provide a
- buffer. The buffer size per page is determined by the oobfree array in
- the nand_oobinfo structure.
- </para>
- <para>
- If the spare area buffer is NULL then only the ECC placement is
- done according to the default builtin scheme.
- </para>
- </sect2>
- </sect1>
- <sect1 id="Spare_area_autoplacement_default">
- <title>Spare area autoplacement default schemes</title>
- <sect2 id="pagesize_256">
- <title>256 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1</entry>
-</row>
-<row>
-<entry>0x02</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2</entry>
-</row>
-<row>
-<entry>0x03</entry>
-<entry>Autoplace 0</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x04</entry>
-<entry>Autoplace 1</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x05</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x06</entry>
-<entry>Autoplace 2</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x07</entry>
-<entry>Autoplace 3</entry>
-<entry></entry>
-</row>
-</tbody></tgroup></informaltable>
- </sect2>
- <sect2 id="pagesize_512">
- <title>512 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0 of the lower 256 Byte data in
-this page</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1 of the lower 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x02</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2 of the lower 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x03</entry>
-<entry>ECC byte 3</entry>
-<entry>Error correction code byte 0 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x04</entry>
-<entry>reserved</entry>
-<entry>reserved</entry>
-</row>
-<row>
-<entry>0x05</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x06</entry>
-<entry>ECC byte 4</entry>
-<entry>Error correction code byte 1 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x07</entry>
-<entry>ECC byte 5</entry>
-<entry>Error correction code byte 2 of the upper 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x08 - 0x0F</entry>
-<entry>Autoplace 0 - 7</entry>
-<entry></entry>
-</row>
-</tbody></tgroup></informaltable>
- </sect2>
- <sect2 id="pagesize_2048">
- <title>2048 byte pagesize</title>
-<informaltable><tgroup cols="3"><tbody>
-<row>
-<entry>Offset</entry>
-<entry>Content</entry>
-<entry>Comment</entry>
-</row>
-<row>
-<entry>0x00</entry>
-<entry>Bad block marker</entry>
-<entry>If any bit in this byte is zero, then this block is bad.
-This applies only to the first page in a block. In the remaining
-pages this byte is reserved</entry>
-</row>
-<row>
-<entry>0x01</entry>
-<entry>Reserved</entry>
-<entry>Reserved</entry>
-</row>
-<row>
-<entry>0x02-0x27</entry>
-<entry>Autoplace 0 - 37</entry>
-<entry></entry>
-</row>
-<row>
-<entry>0x28</entry>
-<entry>ECC byte 0</entry>
-<entry>Error correction code byte 0 of the first 256 Byte data in
-this page</entry>
-</row>
-<row>
-<entry>0x29</entry>
-<entry>ECC byte 1</entry>
-<entry>Error correction code byte 1 of the first 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2A</entry>
-<entry>ECC byte 2</entry>
-<entry>Error correction code byte 2 of the first 256 Bytes data in
-this page</entry>
-</row>
-<row>
-<entry>0x2B</entry>
-<entry>ECC byte 3</entry>
-<entry>Error correction code byte 0 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2C</entry>
-<entry>ECC byte 4</entry>
-<entry>Error correction code byte 1 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2D</entry>
-<entry>ECC byte 5</entry>
-<entry>Error correction code byte 2 of the second 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2E</entry>
-<entry>ECC byte 6</entry>
-<entry>Error correction code byte 0 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x2F</entry>
-<entry>ECC byte 7</entry>
-<entry>Error correction code byte 1 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x30</entry>
-<entry>ECC byte 8</entry>
-<entry>Error correction code byte 2 of the third 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x31</entry>
-<entry>ECC byte 9</entry>
-<entry>Error correction code byte 0 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x32</entry>
-<entry>ECC byte 10</entry>
-<entry>Error correction code byte 1 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x33</entry>
-<entry>ECC byte 11</entry>
-<entry>Error correction code byte 2 of the fourth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x34</entry>
-<entry>ECC byte 12</entry>
-<entry>Error correction code byte 0 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x35</entry>
-<entry>ECC byte 13</entry>
-<entry>Error correction code byte 1 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x36</entry>
-<entry>ECC byte 14</entry>
-<entry>Error correction code byte 2 of the fifth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x37</entry>
-<entry>ECC byte 15</entry>
-<entry>Error correction code byte 0 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x38</entry>
-<entry>ECC byte 16</entry>
-<entry>Error correction code byte 1 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x39</entry>
-<entry>ECC byte 17</entry>
-<entry>Error correction code byte 2 of the sixt 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3A</entry>
-<entry>ECC byte 18</entry>
-<entry>Error correction code byte 0 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3B</entry>
-<entry>ECC byte 19</entry>
-<entry>Error correction code byte 1 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3C</entry>
-<entry>ECC byte 20</entry>
-<entry>Error correction code byte 2 of the seventh 256 Bytes of
-data in this page</entry>
-</row>
-<row>
-<entry>0x3D</entry>
-<entry>ECC byte 21</entry>
-<entry>Error correction code byte 0 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3E</entry>
-<entry>ECC byte 22</entry>
-<entry>Error correction code byte 1 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-<row>
-<entry>0x3F</entry>
-<entry>ECC byte 23</entry>
-<entry>Error correction code byte 2 of the eighth 256 Bytes of data
-in this page</entry>
-</row>
-</tbody></tgroup></informaltable>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="filesystems">
- <title>Filesystem support</title>
- <para>
- The NAND driver provides all necessary functions for a
- filesystem via the MTD interface.
- </para>
- <para>
- Filesystems must be aware of the NAND peculiarities and
- restrictions. One major restrictions of NAND Flash is, that you cannot
- write as often as you want to a page. The consecutive writes to a page,
- before erasing it again, are restricted to 1-3 writes, depending on the
- manufacturers specifications. This applies similar to the spare area.
- </para>
- <para>
- Therefore NAND aware filesystems must either write in page size chunks
- or hold a writebuffer to collect smaller writes until they sum up to
- pagesize. Available NAND aware filesystems: JFFS2, YAFFS.
- </para>
- <para>
- The spare area usage to store filesystem data is controlled by
- the spare area placement functionality which is described in one
- of the earlier chapters.
- </para>
- </chapter>
- <chapter id="tools">
- <title>Tools</title>
- <para>
- The MTD project provides a couple of helpful tools to handle NAND Flash.
- <itemizedlist>
- <listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem>
- <listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem>
- <listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem>
- </itemizedlist>
- </para>
- <para>
- These tools are aware of the NAND restrictions. Please use those tools
- instead of complaining about errors which are caused by non NAND aware
- access methods.
- </para>
- </chapter>
-
- <chapter id="defines">
- <title>Constants</title>
- <para>
- This chapter describes the constants which might be relevant for a driver developer.
- </para>
- <sect1 id="Chip_option_constants">
- <title>Chip option constants</title>
- <sect2 id="Constants_for_chip_id_table">
- <title>Constants for chip id table</title>
- <para>
- These constants are defined in nand.h. They are ored together to describe
- the chip functionality.
- <programlisting>
-/* Buswitdh is 16 bit */
-#define NAND_BUSWIDTH_16 0x00000002
-/* Device supports partial programming without padding */
-#define NAND_NO_PADDING 0x00000004
-/* Chip has cache program function */
-#define NAND_CACHEPRG 0x00000008
-/* Chip has copy back function */
-#define NAND_COPYBACK 0x00000010
-/* AND Chip which has 4 banks and a confusing page / block
- * assignment. See Renesas datasheet for further information */
-#define NAND_IS_AND 0x00000020
-/* Chip has a array of 4 pages which can be read without
- * additional ready /busy waits */
-#define NAND_4PAGE_ARRAY 0x00000040
- </programlisting>
- </para>
- </sect2>
- <sect2 id="Constants_for_runtime_options">
- <title>Constants for runtime options</title>
- <para>
- These constants are defined in nand.h. They are ored together to describe
- the functionality.
- <programlisting>
-/* The hw ecc generator provides a syndrome instead a ecc value on read
- * This can only work if we have the ecc bytes directly behind the
- * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
-#define NAND_HWECC_SYNDROME 0x00020000
- </programlisting>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="EEC_selection_constants">
- <title>ECC selection constants</title>
- <para>
- Use these constants to select the ECC algorithm.
- <programlisting>
-/* No ECC. Usage is not recommended ! */
-#define NAND_ECC_NONE 0
-/* Software ECC 3 byte ECC per 256 Byte data */
-#define NAND_ECC_SOFT 1
-/* Hardware ECC 3 byte ECC per 256 Byte data */
-#define NAND_ECC_HW3_256 2
-/* Hardware ECC 3 byte ECC per 512 Byte data */
-#define NAND_ECC_HW3_512 3
-/* Hardware ECC 6 byte ECC per 512 Byte data */
-#define NAND_ECC_HW6_512 4
-/* Hardware ECC 6 byte ECC per 512 Byte data */
-#define NAND_ECC_HW8_512 6
- </programlisting>
- </para>
- </sect1>
-
- <sect1 id="Hardware_control_related_constants">
- <title>Hardware control related constants</title>
- <para>
- These constants describe the requested hardware access function when
- the boardspecific hardware control function is called
- <programlisting>
-/* Select the chip by setting nCE to low */
-#define NAND_CTL_SETNCE 1
-/* Deselect the chip by setting nCE to high */
-#define NAND_CTL_CLRNCE 2
-/* Select the command latch by setting CLE to high */
-#define NAND_CTL_SETCLE 3
-/* Deselect the command latch by setting CLE to low */
-#define NAND_CTL_CLRCLE 4
-/* Select the address latch by setting ALE to high */
-#define NAND_CTL_SETALE 5
-/* Deselect the address latch by setting ALE to low */
-#define NAND_CTL_CLRALE 6
-/* Set write protection by setting WP to high. Not used! */
-#define NAND_CTL_SETWP 7
-/* Clear write protection by setting WP to low. Not used! */
-#define NAND_CTL_CLRWP 8
- </programlisting>
- </para>
- </sect1>
-
- <sect1 id="Bad_block_table_constants">
- <title>Bad block table related constants</title>
- <para>
- These constants describe the options used for bad block
- table descriptors.
- <programlisting>
-/* Options for the bad block table descriptors */
-
-/* The number of bits used per block in the bbt on the device */
-#define NAND_BBT_NRBITS_MSK 0x0000000F
-#define NAND_BBT_1BIT 0x00000001
-#define NAND_BBT_2BIT 0x00000002
-#define NAND_BBT_4BIT 0x00000004
-#define NAND_BBT_8BIT 0x00000008
-/* The bad block table is in the last good block of the device */
-#define NAND_BBT_LASTBLOCK 0x00000010
-/* The bbt is at the given page, else we must scan for the bbt */
-#define NAND_BBT_ABSPAGE 0x00000020
-/* bbt is stored per chip on multichip devices */
-#define NAND_BBT_PERCHIP 0x00000080
-/* bbt has a version counter at offset veroffs */
-#define NAND_BBT_VERSION 0x00000100
-/* Create a bbt if none axists */
-#define NAND_BBT_CREATE 0x00000200
-/* Write bbt if necessary */
-#define NAND_BBT_WRITE 0x00001000
-/* Read and write back block contents when writing bbt */
-#define NAND_BBT_SAVECONTENT 0x00002000
- </programlisting>
- </para>
- </sect1>
-
- </chapter>
-
- <chapter id="structs">
- <title>Structures</title>
- <para>
- This chapter contains the autogenerated documentation of the structures which are
- used in the NAND driver and might be relevant for a driver developer. Each
- struct member has a short description which is marked with an [XXX] identifier.
- See the chapter "Documentation hints" for an explanation.
- </para>
-!Iinclude/linux/mtd/nand.h
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the NAND kernel API functions
- which are exported. Each function has a short description which is marked with an [XXX] identifier.
- See the chapter "Documentation hints" for an explanation.
- </para>
-!Edrivers/mtd/nand/nand_base.c
-!Edrivers/mtd/nand/nand_bbt.c
-!Edrivers/mtd/nand/nand_ecc.c
- </chapter>
-
- <chapter id="intfunctions">
- <title>Internal Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the NAND driver internal functions.
- Each function has a short description which is marked with an [XXX] identifier.
- See the chapter "Documentation hints" for an explanation.
- The functions marked with [DEFAULT] might be relevant for a board driver developer.
- </para>
-!Idrivers/mtd/nand/nand_base.c
-!Idrivers/mtd/nand/nand_bbt.c
-<!-- No internal functions for kernel-doc:
-X!Idrivers/mtd/nand/nand_ecc.c
--->
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The following people have contributed to the NAND driver:
- <orderedlist>
- <listitem><para>Steven J. Hill<email>sjhill@realitydiluted.com</email></para></listitem>
- <listitem><para>David Woodhouse<email>dwmw2@infradead.org</email></para></listitem>
- <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
- </orderedlist>
- A lot of users have provided bugfixes, improvements and helping hands for testing.
- Thanks a lot.
- </para>
- <para>
- The following people have contributed to this document:
- <orderedlist>
- <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
- </orderedlist>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/networking.tmpl b/Documentation/DocBook/networking.tmpl
deleted file mode 100644
index 29df25016c7c..000000000000
--- a/Documentation/DocBook/networking.tmpl
+++ /dev/null
@@ -1,111 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="LinuxNetworking">
- <bookinfo>
- <title>Linux Networking and Network Devices APIs</title>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="netcore">
- <title>Linux Networking</title>
- <sect1><title>Networking Base Types</title>
-!Iinclude/linux/net.h
- </sect1>
- <sect1><title>Socket Buffer Functions</title>
-!Iinclude/linux/skbuff.h
-!Iinclude/net/sock.h
-!Enet/socket.c
-!Enet/core/skbuff.c
-!Enet/core/sock.c
-!Enet/core/datagram.c
-!Enet/core/stream.c
- </sect1>
- <sect1><title>Socket Filter</title>
-!Enet/core/filter.c
- </sect1>
- <sect1><title>Generic Network Statistics</title>
-!Iinclude/uapi/linux/gen_stats.h
-!Enet/core/gen_stats.c
-!Enet/core/gen_estimator.c
- </sect1>
- <sect1><title>SUN RPC subsystem</title>
-<!-- The !D functionality is not perfect, garbage has to be protected by comments
-!Dnet/sunrpc/sunrpc_syms.c
--->
-!Enet/sunrpc/xdr.c
-!Enet/sunrpc/svc_xprt.c
-!Enet/sunrpc/xprt.c
-!Enet/sunrpc/sched.c
-!Enet/sunrpc/socklib.c
-!Enet/sunrpc/stats.c
-!Enet/sunrpc/rpc_pipe.c
-!Enet/sunrpc/rpcb_clnt.c
-!Enet/sunrpc/clnt.c
- </sect1>
- <sect1><title>WiMAX</title>
-!Enet/wimax/op-msg.c
-!Enet/wimax/op-reset.c
-!Enet/wimax/op-rfkill.c
-!Enet/wimax/stack.c
-!Iinclude/net/wimax.h
-!Iinclude/uapi/linux/wimax.h
- </sect1>
- </chapter>
-
- <chapter id="netdev">
- <title>Network device support</title>
- <sect1><title>Driver Support</title>
-!Enet/core/dev.c
-!Enet/ethernet/eth.c
-!Enet/sched/sch_generic.c
-!Iinclude/linux/etherdevice.h
-!Iinclude/linux/netdevice.h
- </sect1>
- <sect1><title>PHY Support</title>
-!Edrivers/net/phy/phy.c
-!Idrivers/net/phy/phy.c
-!Edrivers/net/phy/phy_device.c
-!Idrivers/net/phy/phy_device.c
-!Edrivers/net/phy/mdio_bus.c
-!Idrivers/net/phy/mdio_bus.c
- </sect1>
-<!-- FIXME: Removed for now since no structured comments in source
- <sect1><title>Wireless</title>
-X!Enet/core/wireless.c
- </sect1>
--->
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl
deleted file mode 100644
index 50479360d845..000000000000
--- a/Documentation/DocBook/rapidio.tmpl
+++ /dev/null
@@ -1,158 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
- <!ENTITY rapidio SYSTEM "rapidio.xml">
- ]>
-
-<book id="RapidIO-Guide">
- <bookinfo>
- <title>RapidIO Subsystem Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Matt</firstname>
- <surname>Porter</surname>
- <affiliation>
- <address>
- <email>mporter@kernel.crashing.org</email>
- <email>mporter@mvista.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2005</year>
- <holder>MontaVista Software, Inc.</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- RapidIO is a high speed switched fabric interconnect with
- features aimed at the embedded market. RapidIO provides
- support for memory-mapped I/O as well as message-based
- transactions over the switched fabric network. RapidIO has
- a standardized discovery mechanism not unlike the PCI bus
- standard that allows simple detection of devices in a
- network.
- </para>
- <para>
- This documentation is provided for developers intending
- to support RapidIO on new architectures, write new drivers,
- or to understand the subsystem internals.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs and Limitations</title>
-
- <sect1 id="known_bugs">
- <title>Bugs</title>
- <para>None. ;)</para>
- </sect1>
- <sect1 id="Limitations">
- <title>Limitations</title>
- <para>
- <orderedlist>
- <listitem><para>Access/management of RapidIO memory regions is not supported</para></listitem>
- <listitem><para>Multiple host enumeration is not supported</para></listitem>
- </orderedlist>
- </para>
- </sect1>
- </chapter>
-
- <chapter id="drivers">
- <title>RapidIO driver interface</title>
- <para>
- Drivers are provided a set of calls in order
- to interface with the subsystem to gather info
- on devices, request/map memory region resources,
- and manage mailboxes/doorbells.
- </para>
- <sect1 id="Functions">
- <title>Functions</title>
-!Iinclude/linux/rio_drv.h
-!Edrivers/rapidio/rio-driver.c
-!Edrivers/rapidio/rio.c
- </sect1>
- </chapter>
-
- <chapter id="internals">
- <title>Internals</title>
-
- <para>
- This chapter contains the autogenerated documentation of the RapidIO
- subsystem.
- </para>
-
- <sect1 id="Structures"><title>Structures</title>
-!Iinclude/linux/rio.h
- </sect1>
- <sect1 id="Enumeration_and_Discovery"><title>Enumeration and Discovery</title>
-!Idrivers/rapidio/rio-scan.c
- </sect1>
- <sect1 id="Driver_functionality"><title>Driver functionality</title>
-!Idrivers/rapidio/rio.c
-!Idrivers/rapidio/rio-access.c
- </sect1>
- <sect1 id="Device_model_support"><title>Device model support</title>
-!Idrivers/rapidio/rio-driver.c
- </sect1>
- <sect1 id="Sysfs_support"><title>Sysfs support</title>
-!Idrivers/rapidio/rio-sysfs.c
- </sect1>
- <sect1 id="PPC32_support"><title>PPC32 support</title>
-!Iarch/powerpc/sysdev/fsl_rio.c
- </sect1>
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The following people have contributed to the RapidIO
- subsystem directly or indirectly:
- <orderedlist>
- <listitem><para>Matt Porter<email>mporter@kernel.crashing.org</email></para></listitem>
- <listitem><para>Randy Vinson<email>rvinson@mvista.com</email></para></listitem>
- <listitem><para>Dan Malek<email>dan@embeddedalley.com</email></para></listitem>
- </orderedlist>
- </para>
- <para>
- The following people have contributed to this document:
- <orderedlist>
- <listitem><para>Matt Porter<email>mporter@kernel.crashing.org</email></para></listitem>
- </orderedlist>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl
deleted file mode 100644
index 3b08a085d2c7..000000000000
--- a/Documentation/DocBook/regulator.tmpl
+++ /dev/null
@@ -1,304 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="regulator-api">
- <bookinfo>
- <title>Voltage and current regulator API</title>
-
- <authorgroup>
- <author>
- <firstname>Liam</firstname>
- <surname>Girdwood</surname>
- <affiliation>
- <address>
- <email>lrg@slimlogic.co.uk</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Mark</firstname>
- <surname>Brown</surname>
- <affiliation>
- <orgname>Wolfson Microelectronics</orgname>
- <address>
- <email>broonie@opensource.wolfsonmicro.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2007-2008</year>
- <holder>Wolfson Microelectronics</holder>
- </copyright>
- <copyright>
- <year>2008</year>
- <holder>Liam Girdwood</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- This framework is designed to provide a standard kernel
- interface to control voltage and current regulators.
- </para>
- <para>
- The intention is to allow systems to dynamically control
- regulator power output in order to save power and prolong
- battery life. This applies to both voltage regulators (where
- voltage output is controllable) and current sinks (where current
- limit is controllable).
- </para>
- <para>
- Note that additional (and currently more complete) documentation
- is available in the Linux kernel source under
- <filename>Documentation/power/regulator</filename>.
- </para>
-
- <sect1 id="glossary">
- <title>Glossary</title>
- <para>
- The regulator API uses a number of terms which may not be
- familiar:
- </para>
- <glossary>
-
- <glossentry>
- <glossterm>Regulator</glossterm>
- <glossdef>
- <para>
- Electronic device that supplies power to other devices. Most
- regulators can enable and disable their output and some can also
- control their output voltage or current.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Consumer</glossterm>
- <glossdef>
- <para>
- Electronic device which consumes power provided by a regulator.
- These may either be static, requiring only a fixed supply, or
- dynamic, requiring active management of the regulator at
- runtime.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Power Domain</glossterm>
- <glossdef>
- <para>
- The electronic circuit supplied by a given regulator, including
- the regulator and all consumer devices. The configuration of
- the regulator is shared between all the components in the
- circuit.
- </para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Power Management Integrated Circuit</glossterm>
- <acronym>PMIC</acronym>
- <glossdef>
- <para>
- An IC which contains numerous regulators and often also other
- subsystems. In an embedded system the primary PMIC is often
- equivalent to a combination of the PSU and southbridge in a
- desktop system.
- </para>
- </glossdef>
- </glossentry>
- </glossary>
- </sect1>
- </chapter>
-
- <chapter id="consumer">
- <title>Consumer driver interface</title>
- <para>
- This offers a similar API to the kernel clock framework.
- Consumer drivers use <link
- linkend='API-regulator-get'>get</link> and <link
- linkend='API-regulator-put'>put</link> operations to acquire and
- release regulators. Functions are
- provided to <link linkend='API-regulator-enable'>enable</link>
- and <link linkend='API-regulator-disable'>disable</link> the
- regulator and to get and set the runtime parameters of the
- regulator.
- </para>
- <para>
- When requesting regulators consumers use symbolic names for their
- supplies, such as "Vcc", which are mapped into actual regulator
- devices by the machine interface.
- </para>
- <para>
- A stub version of this API is provided when the regulator
- framework is not in use in order to minimise the need to use
- ifdefs.
- </para>
-
- <sect1 id="consumer-enable">
- <title>Enabling and disabling</title>
- <para>
- The regulator API provides reference counted enabling and
- disabling of regulators. Consumer devices use the <function><link
- linkend='API-regulator-enable'>regulator_enable</link></function>
- and <function><link
- linkend='API-regulator-disable'>regulator_disable</link>
- </function> functions to enable and disable regulators. Calls
- to the two functions must be balanced.
- </para>
- <para>
- Note that since multiple consumers may be using a regulator and
- machine constraints may not allow the regulator to be disabled
- there is no guarantee that calling
- <function>regulator_disable</function> will actually cause the
- supply provided by the regulator to be disabled. Consumer
- drivers should assume that the regulator may be enabled at all
- times.
- </para>
- </sect1>
-
- <sect1 id="consumer-config">
- <title>Configuration</title>
- <para>
- Some consumer devices may need to be able to dynamically
- configure their supplies. For example, MMC drivers may need to
- select the correct operating voltage for their cards. This may
- be done while the regulator is enabled or disabled.
- </para>
- <para>
- The <function><link
- linkend='API-regulator-set-voltage'>regulator_set_voltage</link>
- </function> and <function><link
- linkend='API-regulator-set-current-limit'
- >regulator_set_current_limit</link>
- </function> functions provide the primary interface for this.
- Both take ranges of voltages and currents, supporting drivers
- that do not require a specific value (eg, CPU frequency scaling
- normally permits the CPU to use a wider range of supply
- voltages at lower frequencies but does not require that the
- supply voltage be lowered). Where an exact value is required
- both minimum and maximum values should be identical.
- </para>
- </sect1>
-
- <sect1 id="consumer-callback">
- <title>Callbacks</title>
- <para>
- Callbacks may also be <link
- linkend='API-regulator-register-notifier'>registered</link>
- for events such as regulation failures.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="driver">
- <title>Regulator driver interface</title>
- <para>
- Drivers for regulator chips <link
- linkend='API-regulator-register'>register</link> the regulators
- with the regulator core, providing operations structures to the
- core. A <link
- linkend='API-regulator-notifier-call-chain'>notifier</link> interface
- allows error conditions to be reported to the core.
- </para>
- <para>
- Registration should be triggered by explicit setup done by the
- platform, supplying a <link
- linkend='API-struct-regulator-init-data'>struct
- regulator_init_data</link> for the regulator containing
- <link linkend='machine-constraint'>constraint</link> and
- <link linkend='machine-supply'>supply</link> information.
- </para>
- </chapter>
-
- <chapter id="machine">
- <title>Machine interface</title>
- <para>
- This interface provides a way to define how regulators are
- connected to consumers on a given system and what the valid
- operating parameters are for the system.
- </para>
-
- <sect1 id="machine-supply">
- <title>Supplies</title>
- <para>
- Regulator supplies are specified using <link
- linkend='API-struct-regulator-consumer-supply'>struct
- regulator_consumer_supply</link>. This is done at
- <link linkend='driver'>driver registration
- time</link> as part of the machine constraints.
- </para>
- </sect1>
-
- <sect1 id="machine-constraint">
- <title>Constraints</title>
- <para>
- As well as defining the connections the machine interface
- also provides constraints defining the operations that
- clients are allowed to perform and the parameters that may be
- set. This is required since generally regulator devices will
- offer more flexibility than it is safe to use on a given
- system, for example supporting higher supply voltages than the
- consumers are rated for.
- </para>
- <para>
- This is done at <link linkend='driver'>driver
- registration time</link> by providing a <link
- linkend='API-struct-regulation-constraints'>struct
- regulation_constraints</link>.
- </para>
- <para>
- The constraints may also specify an initial configuration for the
- regulator in the constraints, which is particularly useful for
- use with static consumers.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="api">
- <title>API reference</title>
- <para>
- Due to limitations of the kernel documentation framework and the
- existing layout of the source code the entire regulator API is
- documented here.
- </para>
-!Iinclude/linux/regulator/consumer.h
-!Iinclude/linux/regulator/machine.h
-!Iinclude/linux/regulator/driver.h
-!Edrivers/regulator/core.c
- </chapter>
-</book>
diff --git a/Documentation/DocBook/s390-drivers.tmpl b/Documentation/DocBook/s390-drivers.tmpl
deleted file mode 100644
index 95bfc12e5439..000000000000
--- a/Documentation/DocBook/s390-drivers.tmpl
+++ /dev/null
@@ -1,161 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="s390drivers">
- <bookinfo>
- <title>Writing s390 channel device drivers</title>
-
- <authorgroup>
- <author>
- <firstname>Cornelia</firstname>
- <surname>Huck</surname>
- <affiliation>
- <address>
- <email>cornelia.huck@de.ibm.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2007</year>
- <holder>IBM Corp.</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- This document describes the interfaces available for device drivers that
- drive s390 based channel attached I/O devices. This includes interfaces for
- interaction with the hardware and interfaces for interacting with the
- common driver core. Those interfaces are provided by the s390 common I/O
- layer.
- </para>
- <para>
- The document assumes a familarity with the technical terms associated
- with the s390 channel I/O architecture. For a description of this
- architecture, please refer to the "z/Architecture: Principles of
- Operation", IBM publication no. SA22-7832.
- </para>
- <para>
- While most I/O devices on a s390 system are typically driven through the
- channel I/O mechanism described here, there are various other methods
- (like the diag interface). These are out of the scope of this document.
- </para>
- <para>
- Some additional information can also be found in the kernel source
- under Documentation/s390/driver-model.txt.
- </para>
- </chapter>
- <chapter id="ccw">
- <title>The ccw bus</title>
- <para>
- The ccw bus typically contains the majority of devices available to
- a s390 system. Named after the channel command word (ccw), the basic
- command structure used to address its devices, the ccw bus contains
- so-called channel attached devices. They are addressed via I/O
- subchannels, visible on the css bus. A device driver for
- channel-attached devices, however, will never interact with the
- subchannel directly, but only via the I/O device on the ccw bus,
- the ccw device.
- </para>
- <sect1 id="channelIO">
- <title>I/O functions for channel-attached devices</title>
- <para>
- Some hardware structures have been translated into C structures for use
- by the common I/O layer and device drivers. For more information on
- the hardware structures represented here, please consult the Principles
- of Operation.
- </para>
-!Iarch/s390/include/asm/cio.h
- </sect1>
- <sect1 id="ccwdev">
- <title>ccw devices</title>
- <para>
- Devices that want to initiate channel I/O need to attach to the ccw bus.
- Interaction with the driver core is done via the common I/O layer, which
- provides the abstractions of ccw devices and ccw device drivers.
- </para>
- <para>
- The functions that initiate or terminate channel I/O all act upon a
- ccw device structure. Device drivers must not bypass those functions
- or strange side effects may happen.
- </para>
-!Iarch/s390/include/asm/ccwdev.h
-!Edrivers/s390/cio/device.c
-!Edrivers/s390/cio/device_ops.c
- </sect1>
- <sect1 id="cmf">
- <title>The channel-measurement facility</title>
- <para>
- The channel-measurement facility provides a means to collect
- measurement data which is made available by the channel subsystem
- for each channel attached device.
- </para>
-!Iarch/s390/include/asm/cmb.h
-!Edrivers/s390/cio/cmf.c
- </sect1>
- </chapter>
-
- <chapter id="ccwgroup">
- <title>The ccwgroup bus</title>
- <para>
- The ccwgroup bus only contains artificial devices, created by the user.
- Many networking devices (e.g. qeth) are in fact composed of several
- ccw devices (like read, write and data channel for qeth). The
- ccwgroup bus provides a mechanism to create a meta-device which
- contains those ccw devices as slave devices and can be associated
- with the netdevice.
- </para>
- <sect1 id="ccwgroupdevices">
- <title>ccw group devices</title>
-!Iarch/s390/include/asm/ccwgroup.h
-!Edrivers/s390/cio/ccwgroup.c
- </sect1>
- </chapter>
-
- <chapter id="genericinterfaces">
- <title>Generic interfaces</title>
- <para>
- Some interfaces are available to other drivers that do not necessarily
- have anything to do with the busses described above, but still are
- indirectly using basic infrastructure in the common I/O layer.
- One example is the support for adapter interrupts.
- </para>
-!Edrivers/s390/cio/airq.c
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl
deleted file mode 100644
index 324b53494f08..000000000000
--- a/Documentation/DocBook/scsi.tmpl
+++ /dev/null
@@ -1,409 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="scsimid">
- <bookinfo>
- <title>SCSI Interfaces Guide</title>
-
- <authorgroup>
- <author>
- <firstname>James</firstname>
- <surname>Bottomley</surname>
- <affiliation>
- <address>
- <email>James.Bottomley@hansenpartnership.com</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Rob</firstname>
- <surname>Landley</surname>
- <affiliation>
- <address>
- <email>rob@landley.net</email>
- </address>
- </affiliation>
- </author>
-
- </authorgroup>
-
- <copyright>
- <year>2007</year>
- <holder>Linux Foundation</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <sect1 id="protocol_vs_bus">
- <title>Protocol vs bus</title>
- <para>
- Once upon a time, the Small Computer Systems Interface defined both
- a parallel I/O bus and a data protocol to connect a wide variety of
- peripherals (disk drives, tape drives, modems, printers, scanners,
- optical drives, test equipment, and medical devices) to a host
- computer.
- </para>
- <para>
- 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.
- </para>
- <para>
- The <ulink url='http://www.t10.org/scsi-3.htm'>SCSI protocol</ulink>
- is a big-endian peer-to-peer packet based protocol. SCSI commands
- are 6, 10, 12, or 16 bytes long, often followed by an associated data
- payload.
- </para>
- <para>
- SCSI commands can be transported over just about any kind of bus, and
- are the default protocol for storage devices attached to USB, SATA,
- SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are
- also commonly exchanged over Infiniband,
- <ulink url='http://i2o.shadowconnect.com/faq.php'>I20</ulink>, TCP/IP
- (<ulink url='http://en.wikipedia.org/wiki/ISCSI'>iSCSI</ulink>), even
- <ulink url='http://cyberelk.net/tim/parport/parscsi.html'>Parallel
- ports</ulink>.
- </para>
- </sect1>
- <sect1 id="subsystem_design">
- <title>Design of the Linux SCSI subsystem</title>
- <para>
- The SCSI subsystem uses a three layer design, with upper, mid, and low
- layers. Every operation involving the SCSI subsystem (such as reading
- a sector from a disk) uses one driver at each of the 3 levels: one
- upper layer driver, one lower layer driver, and the SCSI midlayer.
- </para>
- <para>
- The SCSI upper layer provides the interface between userspace and the
- kernel, in the form of block and char device nodes for I/O and
- ioctl(). The SCSI lower layer contains drivers for specific hardware
- devices.
- </para>
- <para>
- In between is the SCSI mid-layer, analogous to a network routing
- layer such as the IPv4 stack. The SCSI mid-layer routes a packet
- based data protocol between the upper layer's /dev nodes and the
- corresponding devices in the lower layer. It manages command queues,
- provides error handling and power management functions, and responds
- to ioctl() requests.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="upper_layer">
- <title>SCSI upper layer</title>
- <para>
- The upper layer supports the user-kernel interface by providing
- device nodes.
- </para>
- <sect1 id="sd">
- <title>sd (SCSI Disk)</title>
- <para>sd (sd_mod.o)</para>
-<!-- !Idrivers/scsi/sd.c -->
- </sect1>
- <sect1 id="sr">
- <title>sr (SCSI CD-ROM)</title>
- <para>sr (sr_mod.o)</para>
- </sect1>
- <sect1 id="st">
- <title>st (SCSI Tape)</title>
- <para>st (st.o)</para>
- </sect1>
- <sect1 id="sg">
- <title>sg (SCSI Generic)</title>
- <para>sg (sg.o)</para>
- </sect1>
- <sect1 id="ch">
- <title>ch (SCSI Media Changer)</title>
- <para>ch (ch.c)</para>
- </sect1>
- </chapter>
-
- <chapter id="mid_layer">
- <title>SCSI mid layer</title>
-
- <sect1 id="midlayer_implementation">
- <title>SCSI midlayer implementation</title>
- <sect2 id="scsi_device.h">
- <title>include/scsi/scsi_device.h</title>
- <para>
- </para>
-!Iinclude/scsi/scsi_device.h
- </sect2>
-
- <sect2 id="scsi.c">
- <title>drivers/scsi/scsi.c</title>
- <para>Main file for the SCSI midlayer.</para>
-!Edrivers/scsi/scsi.c
- </sect2>
- <sect2 id="scsicam.c">
- <title>drivers/scsi/scsicam.c</title>
- <para>
- <ulink url='http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf'>SCSI
- Common Access Method</ulink> support functions, for use with
- HDIO_GETGEO, etc.
- </para>
-!Edrivers/scsi/scsicam.c
- </sect2>
- <sect2 id="scsi_error.c">
- <title>drivers/scsi/scsi_error.c</title>
- <para>Common SCSI error/timeout handling routines.</para>
-!Edrivers/scsi/scsi_error.c
- </sect2>
- <sect2 id="scsi_devinfo.c">
- <title>drivers/scsi/scsi_devinfo.c</title>
- <para>
- Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
- devices.
- </para>
-!Idrivers/scsi/scsi_devinfo.c
- </sect2>
- <sect2 id="scsi_ioctl.c">
- <title>drivers/scsi/scsi_ioctl.c</title>
- <para>
- Handle ioctl() calls for SCSI devices.
- </para>
-!Edrivers/scsi/scsi_ioctl.c
- </sect2>
- <sect2 id="scsi_lib.c">
- <title>drivers/scsi/scsi_lib.c</title>
- <para>
- SCSI queuing library.
- </para>
-!Edrivers/scsi/scsi_lib.c
- </sect2>
- <sect2 id="scsi_lib_dma.c">
- <title>drivers/scsi/scsi_lib_dma.c</title>
- <para>
- SCSI library functions depending on DMA
- (map and unmap scatter-gather lists).
- </para>
-!Edrivers/scsi/scsi_lib_dma.c
- </sect2>
- <sect2 id="scsi_module.c">
- <title>drivers/scsi/scsi_module.c</title>
- <para>
- The file drivers/scsi/scsi_module.c contains legacy support for
- old-style host templates. It should never be used by any new driver.
- </para>
- </sect2>
- <sect2 id="scsi_proc.c">
- <title>drivers/scsi/scsi_proc.c</title>
- <para>
- The functions in this file provide an interface between
- the PROC file system and the SCSI device drivers
- It is mainly used for debugging, statistics and to pass
- information directly to the lowlevel driver.
-
- I.E. plumbing to manage /proc/scsi/*
- </para>
-!Idrivers/scsi/scsi_proc.c
- </sect2>
- <sect2 id="scsi_netlink.c">
- <title>drivers/scsi/scsi_netlink.c</title>
- <para>
- Infrastructure to provide async events from transports to userspace
- via netlink, using a single NETLINK_SCSITRANSPORT protocol for all
- transports.
-
- See <ulink url='http://marc.info/?l=linux-scsi&amp;m=115507374832500&amp;w=2'>the
- original patch submission</ulink> for more details.
- </para>
-!Idrivers/scsi/scsi_netlink.c
- </sect2>
- <sect2 id="scsi_scan.c">
- <title>drivers/scsi/scsi_scan.c</title>
- <para>
- Scan a host to determine which (if any) devices are attached.
-
- The general scanning/probing algorithm is as follows, exceptions are
- made to it depending on device specific flags, compilation options,
- and global variable (boot or module load time) settings.
-
- A specific LUN is scanned via an INQUIRY command; if the LUN has a
- device attached, a scsi_device is allocated and setup for it.
-
- For every id of every channel on the given host, start by scanning
- LUN 0. Skip hosts that don't respond at all to a scan of LUN 0.
- Otherwise, if LUN 0 has a device attached, allocate and setup a
- scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN,
- and scan all of the LUNs returned by the REPORT LUN; else,
- sequentially scan LUNs up until some maximum is reached, or a LUN is
- seen that cannot have a device attached to it.
- </para>
-!Idrivers/scsi/scsi_scan.c
- </sect2>
- <sect2 id="scsi_sysctl.c">
- <title>drivers/scsi/scsi_sysctl.c</title>
- <para>
- Set up the sysctl entry: "/dev/scsi/logging_level"
- (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
- </para>
- </sect2>
- <sect2 id="scsi_sysfs.c">
- <title>drivers/scsi/scsi_sysfs.c</title>
- <para>
- SCSI sysfs interface routines.
- </para>
-!Edrivers/scsi/scsi_sysfs.c
- </sect2>
- <sect2 id="hosts.c">
- <title>drivers/scsi/hosts.c</title>
- <para>
- mid to lowlevel SCSI driver interface
- </para>
-!Edrivers/scsi/hosts.c
- </sect2>
- <sect2 id="constants.c">
- <title>drivers/scsi/constants.c</title>
- <para>
- mid to lowlevel SCSI driver interface
- </para>
-!Edrivers/scsi/constants.c
- </sect2>
- </sect1>
-
- <sect1 id="Transport_classes">
- <title>Transport classes</title>
- <para>
- Transport classes are service libraries for drivers in the SCSI
- lower layer, which expose transport attributes in sysfs.
- </para>
- <sect2 id="Fibre_Channel_transport">
- <title>Fibre Channel transport</title>
- <para>
- The file drivers/scsi/scsi_transport_fc.c defines transport attributes
- for Fibre Channel.
- </para>
-!Edrivers/scsi/scsi_transport_fc.c
- </sect2>
- <sect2 id="iSCSI_transport">
- <title>iSCSI transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_iscsi.c defines transport
- attributes for the iSCSI class, which sends SCSI packets over TCP/IP
- connections.
- </para>
-!Edrivers/scsi/scsi_transport_iscsi.c
- </sect2>
- <sect2 id="SAS_transport">
- <title>Serial Attached SCSI (SAS) transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_sas.c defines transport
- attributes for Serial Attached SCSI, a variant of SATA aimed at
- large high-end systems.
- </para>
- <para>
- The SAS transport class contains common code to deal with SAS HBAs,
- an aproximated representation of SAS topologies in the driver model,
- and various sysfs attributes to expose these topologies and management
- interfaces to userspace.
- </para>
- <para>
- In addition to the basic SCSI core objects this transport class
- introduces two additional intermediate objects: The SAS PHY
- as represented by struct sas_phy defines an "outgoing" PHY on
- a SAS HBA or Expander, and the SAS remote PHY represented by
- struct sas_rphy defines an "incoming" PHY on a SAS Expander or
- end device. Note that this is purely a software concept, the
- underlying hardware for a PHY and a remote PHY is the exactly
- the same.
- </para>
- <para>
- There is no concept of a SAS port in this code, users can see
- what PHYs form a wide port based on the port_identifier attribute,
- which is the same for all PHYs in a port.
- </para>
-!Edrivers/scsi/scsi_transport_sas.c
- </sect2>
- <sect2 id="SATA_transport">
- <title>SATA transport class</title>
- <para>
- The SATA transport is handled by libata, which has its own book of
- documentation in this directory.
- </para>
- </sect2>
- <sect2 id="SPI_transport">
- <title>Parallel SCSI (SPI) transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_spi.c defines transport
- attributes for traditional (fast/wide/ultra) SCSI busses.
- </para>
-!Edrivers/scsi/scsi_transport_spi.c
- </sect2>
- <sect2 id="SRP_transport">
- <title>SCSI RDMA (SRP) transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_srp.c defines transport
- attributes for SCSI over Remote Direct Memory Access.
- </para>
-!Edrivers/scsi/scsi_transport_srp.c
- </sect2>
- </sect1>
-
- </chapter>
-
- <chapter id="lower_layer">
- <title>SCSI lower layer</title>
- <sect1 id="hba_drivers">
- <title>Host Bus Adapter transport types</title>
- <para>
- Many modern device controllers use the SCSI command set as a protocol to
- communicate with their devices through many different types of physical
- connections.
- </para>
- <para>
- In SCSI language a bus capable of carrying SCSI commands is
- called a "transport", and a controller connecting to such a bus is
- called a "host bus adapter" (HBA).
- </para>
- <sect2 id="scsi_debug.c">
- <title>Debug transport</title>
- <para>
- The file drivers/scsi/scsi_debug.c simulates a host adapter with a
- variable number of disks (or disk like devices) attached, sharing a
- common amount of RAM. Does a lot of checking to make sure that we are
- not getting blocks mixed up, and panics the kernel if anything out of
- the ordinary is seen.
- </para>
- <para>
- To be more realistic, the simulated devices have the transport
- attributes of SAS disks.
- </para>
- <para>
- For documentation see
- <ulink url='http://sg.danny.cz/sg/sdebug26.html'>http://sg.danny.cz/sg/sdebug26.html</ulink>
- </para>
-<!-- !Edrivers/scsi/scsi_debug.c -->
- </sect2>
- <sect2 id="todo">
- <title>todo</title>
- <para>Parallel (fast/wide/ultra) SCSI, USB, SATA,
- SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband,
- I20, iSCSI, Parallel ports, netlink...
- </para>
- </sect2>
- </sect1>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl
deleted file mode 100644
index 4a38f604fa66..000000000000
--- a/Documentation/DocBook/sh.tmpl
+++ /dev/null
@@ -1,105 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="sh-drivers">
- <bookinfo>
- <title>SuperH Interfaces Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Paul</firstname>
- <surname>Mundt</surname>
- <affiliation>
- <address>
- <email>lethal@linux-sh.org</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2008-2010</year>
- <holder>Paul Mundt</holder>
- </copyright>
- <copyright>
- <year>2008-2010</year>
- <holder>Renesas Technology Corp.</holder>
- </copyright>
- <copyright>
- <year>2010</year>
- <holder>Renesas Electronics Corp.</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="mm">
- <title>Memory Management</title>
- <sect1 id="sh4">
- <title>SH-4</title>
- <sect2 id="sq">
- <title>Store Queue API</title>
-!Earch/sh/kernel/cpu/sh4/sq.c
- </sect2>
- </sect1>
- <sect1 id="sh5">
- <title>SH-5</title>
- <sect2 id="tlb">
- <title>TLB Interfaces</title>
-!Iarch/sh/mm/tlb-sh5.c
-!Iarch/sh/include/asm/tlb_64.h
- </sect2>
- </sect1>
- </chapter>
- <chapter id="mach">
- <title>Machine Specific Interfaces</title>
- <sect1 id="dreamcast">
- <title>mach-dreamcast</title>
-!Iarch/sh/boards/mach-dreamcast/rtc.c
- </sect1>
- <sect1 id="x3proto">
- <title>mach-x3proto</title>
-!Earch/sh/boards/mach-x3proto/ilsel.c
- </sect1>
- </chapter>
- <chapter id="busses">
- <title>Busses</title>
- <sect1 id="superhyway">
- <title>SuperHyway</title>
-!Edrivers/sh/superhyway/superhyway.c
- </sect1>
-
- <sect1 id="maple">
- <title>Maple</title>
-!Edrivers/sh/maple/maple.c
- </sect1>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl
deleted file mode 100644
index 85b25275196f..000000000000
--- a/Documentation/DocBook/stylesheet.xsl
+++ /dev/null
@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
-<param name="chunk.quietly">1</param>
-<param name="funcsynopsis.style">ansi</param>
-<param name="funcsynopsis.tabular.threshold">80</param>
-<param name="callout.graphics">0</param>
-<!-- <param name="paper.type">A4</param> -->
-<param name="generate.section.toc.level">2</param>
-<param name="use.id.as.filename">1</param>
-</stylesheet>
diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl
deleted file mode 100644
index b57a9ede3224..000000000000
--- a/Documentation/DocBook/tracepoint.tmpl
+++ /dev/null
@@ -1,112 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Tracepoints">
- <bookinfo>
- <title>The Linux Kernel Tracepoint API</title>
-
- <authorgroup>
- <author>
- <firstname>Jason</firstname>
- <surname>Baron</surname>
- <affiliation>
- <address>
- <email>jbaron@redhat.com</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>William</firstname>
- <surname>Cohen</surname>
- <affiliation>
- <address>
- <email>wcohen@redhat.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- Tracepoints are static probe points that are located in strategic points
- throughout the kernel. 'Probes' register/unregister with tracepoints
- via a callback mechanism. The 'probes' are strictly typed functions that
- are passed a unique set of parameters defined by each tracepoint.
- </para>
-
- <para>
- From this simple callback mechanism, 'probes' can be used to profile, debug,
- and understand kernel behavior. There are a number of tools that provide a
- framework for using 'probes'. These tools include Systemtap, ftrace, and
- LTTng.
- </para>
-
- <para>
- Tracepoints are defined in a number of header files via various macros. Thus,
- the purpose of this document is to provide a clear accounting of the available
- tracepoints. The intention is to understand not only what tracepoints are
- available but also to understand where future tracepoints might be added.
- </para>
-
- <para>
- The API presented has functions of the form:
- <function>trace_tracepointname(function parameters)</function>. These are the
- tracepoints callbacks that are found throughout the code. Registering and
- unregistering probes with these callback sites is covered in the
- <filename>Documentation/trace/*</filename> directory.
- </para>
- </chapter>
-
- <chapter id="irq">
- <title>IRQ</title>
-!Iinclude/trace/events/irq.h
- </chapter>
-
- <chapter id="signal">
- <title>SIGNAL</title>
-!Iinclude/trace/events/signal.h
- </chapter>
-
- <chapter id="block">
- <title>Block IO</title>
-!Iinclude/trace/events/block.h
- </chapter>
-
- <chapter id="workqueue">
- <title>Workqueue</title>
-!Iinclude/trace/events/workqueue.h
- </chapter>
-</book>
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
deleted file mode 100644
index cd0e452dfed5..000000000000
--- a/Documentation/DocBook/uio-howto.tmpl
+++ /dev/null
@@ -1,1050 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []>
-
-<book id="index">
-<bookinfo>
-<title>The Userspace I/O HOWTO</title>
-
-<author>
- <firstname>Hans-Jürgen</firstname>
- <surname>Koch</surname>
- <authorblurb><para>Linux developer, Linutronix</para></authorblurb>
- <affiliation>
- <orgname>
- <ulink url="http://www.linutronix.de">Linutronix</ulink>
- </orgname>
-
- <address>
- <email>hjk@hansjkoch.de</email>
- </address>
- </affiliation>
-</author>
-
-<copyright>
- <year>2006-2008</year>
- <holder>Hans-Jürgen Koch.</holder>
-</copyright>
-<copyright>
- <year>2009</year>
- <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder>
-</copyright>
-
-<legalnotice>
-<para>
-This documentation is Free Software licensed under the terms of the
-GPL version 2.
-</para>
-</legalnotice>
-
-<pubdate>2006-12-11</pubdate>
-
-<abstract>
- <para>This HOWTO describes concept and usage of Linux kernel's
- Userspace I/O system.</para>
-</abstract>
-
-<revhistory>
- <revision>
- <revnumber>0.9</revnumber>
- <date>2009-07-16</date>
- <authorinitials>mst</authorinitials>
- <revremark>Added generic pci driver
- </revremark>
- </revision>
- <revision>
- <revnumber>0.8</revnumber>
- <date>2008-12-24</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Added name attributes in mem and portio sysfs directories.
- </revremark>
- </revision>
- <revision>
- <revnumber>0.7</revnumber>
- <date>2008-12-23</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Added generic platform drivers and offset attribute.</revremark>
- </revision>
- <revision>
- <revnumber>0.6</revnumber>
- <date>2008-12-05</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Added description of portio sysfs attributes.</revremark>
- </revision>
- <revision>
- <revnumber>0.5</revnumber>
- <date>2008-05-22</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Added description of write() function.</revremark>
- </revision>
- <revision>
- <revnumber>0.4</revnumber>
- <date>2007-11-26</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Removed section about uio_dummy.</revremark>
- </revision>
- <revision>
- <revnumber>0.3</revnumber>
- <date>2007-04-29</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Added section about userspace drivers.</revremark>
- </revision>
- <revision>
- <revnumber>0.2</revnumber>
- <date>2007-02-13</date>
- <authorinitials>hjk</authorinitials>
- <revremark>Update after multiple mappings were added.</revremark>
- </revision>
- <revision>
- <revnumber>0.1</revnumber>
- <date>2006-12-11</date>
- <authorinitials>hjk</authorinitials>
- <revremark>First draft.</revremark>
- </revision>
-</revhistory>
-</bookinfo>
-
-<chapter id="aboutthisdoc">
-<?dbhtml filename="aboutthis.html"?>
-<title>About this document</title>
-
-<sect1 id="translations">
-<?dbhtml filename="translations.html"?>
-<title>Translations</title>
-
-<para>If you know of any translations for this document, or you are
-interested in translating it, please email me
-<email>hjk@hansjkoch.de</email>.
-</para>
-</sect1>
-
-<sect1 id="preface">
-<title>Preface</title>
- <para>
- For many types of devices, creating a Linux kernel driver is
- overkill. All that is really needed is some way to handle an
- interrupt and provide access to the memory space of the
- device. The logic of controlling the device does not
- necessarily have to be within the kernel, as the device does
- not need to take advantage of any of other resources that the
- kernel provides. One such common class of devices that are
- like this are for industrial I/O cards.
- </para>
- <para>
- To address this situation, the userspace I/O system (UIO) was
- designed. For typical industrial I/O cards, only a very small
- kernel module is needed. The main part of the driver will run in
- user space. This simplifies development and reduces the risk of
- serious bugs within a kernel module.
- </para>
- <para>
- Please note that UIO is not an universal driver interface. Devices
- that are already handled well by other kernel subsystems (like
- networking or serial or USB) are no candidates for an UIO driver.
- Hardware that is ideally suited for an UIO driver fulfills all of
- the following:
- </para>
-<itemizedlist>
-<listitem>
- <para>The device has memory that can be mapped. The device can be
- controlled completely by writing to this memory.</para>
-</listitem>
-<listitem>
- <para>The device usually generates interrupts.</para>
-</listitem>
-<listitem>
- <para>The device does not fit into one of the standard kernel
- subsystems.</para>
-</listitem>
-</itemizedlist>
-</sect1>
-
-<sect1 id="thanks">
-<title>Acknowledgments</title>
- <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of
- Linutronix, who have not only written most of the UIO code, but also
- helped greatly writing this HOWTO by giving me all kinds of background
- information.</para>
-</sect1>
-
-<sect1 id="feedback">
-<title>Feedback</title>
- <para>Find something wrong with this document? (Or perhaps something
- right?) I would love to hear from you. Please email me at
- <email>hjk@hansjkoch.de</email>.</para>
-</sect1>
-</chapter>
-
-<chapter id="about">
-<?dbhtml filename="about.html"?>
-<title>About UIO</title>
-
-<para>If you use UIO for your card's driver, here's what you get:</para>
-
-<itemizedlist>
-<listitem>
- <para>only one small kernel module to write and maintain.</para>
-</listitem>
-<listitem>
- <para>develop the main part of your driver in user space,
- with all the tools and libraries you're used to.</para>
-</listitem>
-<listitem>
- <para>bugs in your driver won't crash the kernel.</para>
-</listitem>
-<listitem>
- <para>updates of your driver can take place without recompiling
- the kernel.</para>
-</listitem>
-</itemizedlist>
-
-<sect1 id="how_uio_works">
-<title>How UIO works</title>
- <para>
- Each UIO device is accessed through a device file and several
- sysfs attribute files. The device file will be called
- <filename>/dev/uio0</filename> for the first device, and
- <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename>
- and so on for subsequent devices.
- </para>
-
- <para><filename>/dev/uioX</filename> is used to access the
- address space of the card. Just use
- <function>mmap()</function> to access registers or RAM
- locations of your card.
- </para>
-
- <para>
- Interrupts are handled by reading from
- <filename>/dev/uioX</filename>. A blocking
- <function>read()</function> from
- <filename>/dev/uioX</filename> will return as soon as an
- interrupt occurs. You can also use
- <function>select()</function> on
- <filename>/dev/uioX</filename> to wait for an interrupt. The
- integer value read from <filename>/dev/uioX</filename>
- represents the total interrupt count. You can use this number
- to figure out if you missed some interrupts.
- </para>
- <para>
- For some hardware that has more than one interrupt source internally,
- but not separate IRQ mask and status registers, there might be
- situations where userspace cannot determine what the interrupt source
- was if the kernel handler disables them by writing to the chip's IRQ
- register. In such a case, the kernel has to disable the IRQ completely
- to leave the chip's register untouched. Now the userspace part can
- determine the cause of the interrupt, but it cannot re-enable
- interrupts. Another cornercase is chips where re-enabling interrupts
- is a read-modify-write operation to a combined IRQ status/acknowledge
- register. This would be racy if a new interrupt occurred
- simultaneously.
- </para>
- <para>
- To address these problems, UIO also implements a write() function. It
- is normally not used and can be ignored for hardware that has only a
- single interrupt source or has separate IRQ mask and status registers.
- If you need it, however, a write to <filename>/dev/uioX</filename>
- will call the <function>irqcontrol()</function> function implemented
- by the driver. You have to write a 32-bit value that is usually either
- 0 or 1 to disable or enable interrupts. If a driver does not implement
- <function>irqcontrol()</function>, <function>write()</function> will
- return with <varname>-ENOSYS</varname>.
- </para>
-
- <para>
- To handle interrupts properly, your custom kernel module can
- provide its own interrupt handler. It will automatically be
- called by the built-in handler.
- </para>
-
- <para>
- For cards that don't generate interrupts but need to be
- polled, there is the possibility to set up a timer that
- triggers the interrupt handler at configurable time intervals.
- This interrupt simulation is done by calling
- <function>uio_event_notify()</function>
- from the timer's event handler.
- </para>
-
- <para>
- Each driver provides attributes that are used to read or write
- variables. These attributes are accessible through sysfs
- files. A custom kernel driver module can add its own
- attributes to the device owned by the uio driver, but not added
- to the UIO device itself at this time. This might change in the
- future if it would be found to be useful.
- </para>
-
- <para>
- The following standard attributes are provided by the UIO
- framework:
- </para>
-<itemizedlist>
-<listitem>
- <para>
- <filename>name</filename>: The name of your device. It is
- recommended to use the name of your kernel module for this.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>version</filename>: A version string defined by your
- driver. This allows the user space part of your driver to deal
- with different versions of the kernel module.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>event</filename>: The total number of interrupts
- handled by the driver since the last time the device node was
- read.
- </para>
-</listitem>
-</itemizedlist>
-<para>
- These attributes appear under the
- <filename>/sys/class/uio/uioX</filename> directory. Please
- note that this directory might be a symlink, and not a real
- directory. Any userspace code that accesses it must be able
- to handle this.
-</para>
-<para>
- Each UIO device can make one or more memory regions available for
- memory mapping. This is necessary because some industrial I/O cards
- require access to more than one PCI memory region in a driver.
-</para>
-<para>
- Each mapping has its own directory in sysfs, the first mapping
- appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>.
- Subsequent mappings create directories <filename>map1/</filename>,
- <filename>map2/</filename>, and so on. These directories will only
- appear if the size of the mapping is not 0.
-</para>
-<para>
- Each <filename>mapX/</filename> directory contains four read-only files
- that show attributes of the memory:
-</para>
-<itemizedlist>
-<listitem>
- <para>
- <filename>name</filename>: A string identifier for this mapping. This
- is optional, the string can be empty. Drivers can set this to make it
- easier for userspace to find the correct mapping.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>addr</filename>: The address of memory that can be mapped.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>size</filename>: The size, in bytes, of the memory
- pointed to by addr.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>offset</filename>: The offset, in bytes, that has to be
- added to the pointer returned by <function>mmap()</function> to get
- to the actual device memory. This is important if the device's memory
- is not page aligned. Remember that pointers returned by
- <function>mmap()</function> are always page aligned, so it is good
- style to always add this offset.
- </para>
-</listitem>
-</itemizedlist>
-
-<para>
- From userspace, the different mappings are distinguished by adjusting
- the <varname>offset</varname> parameter of the
- <function>mmap()</function> call. To map the memory of mapping N, you
- have to use N times the page size as your offset:
-</para>
-<programlisting format="linespecific">
-offset = N * getpagesize();
-</programlisting>
-
-<para>
- Sometimes there is hardware with memory-like regions that can not be
- mapped with the technique described here, but there are still ways to
- access them from userspace. The most common example are x86 ioports.
- On x86 systems, userspace can access these ioports using
- <function>ioperm()</function>, <function>iopl()</function>,
- <function>inb()</function>, <function>outb()</function>, and similar
- functions.
-</para>
-<para>
- Since these ioport regions can not be mapped, they will not appear under
- <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory
- described above. Without information about the port regions a hardware
- has to offer, it becomes difficult for the userspace part of the
- driver to find out which ports belong to which UIO device.
-</para>
-<para>
- To address this situation, the new directory
- <filename>/sys/class/uio/uioX/portio/</filename> was added. It only
- exists if the driver wants to pass information about one or more port
- regions to userspace. If that is the case, subdirectories named
- <filename>port0</filename>, <filename>port1</filename>, and so on,
- will appear underneath
- <filename>/sys/class/uio/uioX/portio/</filename>.
-</para>
-<para>
- Each <filename>portX/</filename> directory contains four read-only
- files that show name, start, size, and type of the port region:
-</para>
-<itemizedlist>
-<listitem>
- <para>
- <filename>name</filename>: A string identifier for this port region.
- The string is optional and can be empty. Drivers can set it to make it
- easier for userspace to find a certain port region.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>start</filename>: The first port of this region.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>size</filename>: The number of ports in this region.
- </para>
-</listitem>
-<listitem>
- <para>
- <filename>porttype</filename>: A string describing the type of port.
- </para>
-</listitem>
-</itemizedlist>
-
-
-</sect1>
-</chapter>
-
-<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
-<?dbhtml filename="custom_kernel_module.html"?>
-<title>Writing your own kernel module</title>
- <para>
- Please have a look at <filename>uio_cif.c</filename> as an
- example. The following paragraphs explain the different
- sections of this file.
- </para>
-
-<sect1 id="uio_info">
-<title>struct uio_info</title>
- <para>
- This structure tells the framework the details of your driver,
- Some of the members are required, others are optional.
- </para>
-
-<itemizedlist>
-<listitem><para>
-<varname>const char *name</varname>: Required. The name of your driver as
-it will appear in sysfs. I recommend using the name of your module for this.
-</para></listitem>
-
-<listitem><para>
-<varname>const char *version</varname>: Required. This string appears in
-<filename>/sys/class/uio/uioX/version</filename>.
-</para></listitem>
-
-<listitem><para>
-<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you
-have memory that can be mapped with <function>mmap()</function>. For each
-mapping you need to fill one of the <varname>uio_mem</varname> structures.
-See the description below for details.
-</para></listitem>
-
-<listitem><para>
-<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required
-if you want to pass information about ioports to userspace. For each port
-region you need to fill one of the <varname>uio_port</varname> structures.
-See the description below for details.
-</para></listitem>
-
-<listitem><para>
-<varname>long irq</varname>: Required. If your hardware generates an
-interrupt, it's your modules task to determine the irq number during
-initialization. If you don't have a hardware generated interrupt but
-want to trigger the interrupt handler in some other way, set
-<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
-If you had no interrupt at all, you could set
-<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
-rarely makes sense.
-</para></listitem>
-
-<listitem><para>
-<varname>unsigned long irq_flags</varname>: Required if you've set
-<varname>irq</varname> to a hardware interrupt number. The flags given
-here will be used in the call to <function>request_irq()</function>.
-</para></listitem>
-
-<listitem><para>
-<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct
-*vma)</varname>: Optional. If you need a special
-<function>mmap()</function> function, you can set it here. If this
-pointer is not NULL, your <function>mmap()</function> will be called
-instead of the built-in one.
-</para></listitem>
-
-<listitem><para>
-<varname>int (*open)(struct uio_info *info, struct inode *inode)
-</varname>: Optional. You might want to have your own
-<function>open()</function>, e.g. to enable interrupts only when your
-device is actually used.
-</para></listitem>
-
-<listitem><para>
-<varname>int (*release)(struct uio_info *info, struct inode *inode)
-</varname>: Optional. If you define your own
-<function>open()</function>, you will probably also want a custom
-<function>release()</function> function.
-</para></listitem>
-
-<listitem><para>
-<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on)
-</varname>: Optional. If you need to be able to enable or disable
-interrupts from userspace by writing to <filename>/dev/uioX</filename>,
-you can implement this function. The parameter <varname>irq_on</varname>
-will be 0 to disable interrupts and 1 to enable them.
-</para></listitem>
-</itemizedlist>
-
-<para>
-Usually, your device will have one or more memory regions that can be mapped
-to user space. For each region, you have to set up a
-<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array.
-Here's a description of the fields of <varname>struct uio_mem</varname>:
-</para>
-
-<itemizedlist>
-<listitem><para>
-<varname>const char *name</varname>: Optional. Set this to help identify
-the memory region, it will show up in the corresponding sysfs node.
-</para></listitem>
-
-<listitem><para>
-<varname>int memtype</varname>: Required if the mapping is used. Set this to
-<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your
-card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical
-memory (e.g. allocated with <function>kmalloc()</function>). There's also
-<varname>UIO_MEM_VIRTUAL</varname> for virtual memory.
-</para></listitem>
-
-<listitem><para>
-<varname>phys_addr_t addr</varname>: Required if the mapping is used.
-Fill in the address of your memory block. This address is the one that
-appears in sysfs.
-</para></listitem>
-
-<listitem><para>
-<varname>resource_size_t size</varname>: Fill in the size of the
-memory block that <varname>addr</varname> points to. If <varname>size</varname>
-is zero, the mapping is considered unused. Note that you
-<emphasis>must</emphasis> initialize <varname>size</varname> with zero for
-all unused mappings.
-</para></listitem>
-
-<listitem><para>
-<varname>void *internal_addr</varname>: If you have to access this memory
-region from within your kernel module, you will want to map it internally by
-using something like <function>ioremap()</function>. Addresses
-returned by this function cannot be mapped to user space, so you must not
-store it in <varname>addr</varname>. Use <varname>internal_addr</varname>
-instead to remember such an address.
-</para></listitem>
-</itemizedlist>
-
-<para>
-Please do not touch the <varname>map</varname> element of
-<varname>struct uio_mem</varname>! It is used by the UIO framework
-to set up sysfs files for this mapping. Simply leave it alone.
-</para>
-
-<para>
-Sometimes, your device can have one or more port regions which can not be
-mapped to userspace. But if there are other possibilities for userspace to
-access these ports, it makes sense to make information about the ports
-available in sysfs. For each region, you have to set up a
-<varname>struct uio_port</varname> in the <varname>port[]</varname> array.
-Here's a description of the fields of <varname>struct uio_port</varname>:
-</para>
-
-<itemizedlist>
-<listitem><para>
-<varname>char *porttype</varname>: Required. Set this to one of the predefined
-constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86
-architectures.
-</para></listitem>
-
-<listitem><para>
-<varname>unsigned long start</varname>: Required if the port region is used.
-Fill in the number of the first port of this region.
-</para></listitem>
-
-<listitem><para>
-<varname>unsigned long size</varname>: Fill in the number of ports in this
-region. If <varname>size</varname> is zero, the region is considered unused.
-Note that you <emphasis>must</emphasis> initialize <varname>size</varname>
-with zero for all unused regions.
-</para></listitem>
-</itemizedlist>
-
-<para>
-Please do not touch the <varname>portio</varname> element of
-<varname>struct uio_port</varname>! It is used internally by the UIO
-framework to set up sysfs files for this region. Simply leave it alone.
-</para>
-
-</sect1>
-
-<sect1 id="adding_irq_handler">
-<title>Adding an interrupt handler</title>
- <para>
- What you need to do in your interrupt handler depends on your
- hardware and on how you want to handle it. You should try to
- keep the amount of code in your kernel interrupt handler low.
- If your hardware requires no action that you
- <emphasis>have</emphasis> to perform after each interrupt,
- then your handler can be empty.</para> <para>If, on the other
- hand, your hardware <emphasis>needs</emphasis> some action to
- be performed after each interrupt, then you
- <emphasis>must</emphasis> do it in your kernel module. Note
- that you cannot rely on the userspace part of your driver. Your
- userspace program can terminate at any time, possibly leaving
- your hardware in a state where proper interrupt handling is
- still required.
- </para>
-
- <para>
- There might also be applications where you want to read data
- from your hardware at each interrupt and buffer it in a piece
- of kernel memory you've allocated for that purpose. With this
- technique you could avoid loss of data if your userspace
- program misses an interrupt.
- </para>
-
- <para>
- A note on shared interrupts: Your driver should support
- interrupt sharing whenever this is possible. It is possible if
- and only if your driver can detect whether your hardware has
- triggered the interrupt or not. This is usually done by looking
- at an interrupt status register. If your driver sees that the
- IRQ bit is actually set, it will perform its actions, and the
- handler returns IRQ_HANDLED. If the driver detects that it was
- not your hardware that caused the interrupt, it will do nothing
- and return IRQ_NONE, allowing the kernel to call the next
- possible interrupt handler.
- </para>
-
- <para>
- If you decide not to support shared interrupts, your card
- won't work in computers with no free interrupts. As this
- frequently happens on the PC platform, you can save yourself a
- lot of trouble by supporting interrupt sharing.
- </para>
-</sect1>
-
-<sect1 id="using_uio_pdrv">
-<title>Using uio_pdrv for platform devices</title>
- <para>
- In many cases, UIO drivers for platform devices can be handled in a
- generic way. In the same place where you define your
- <varname>struct platform_device</varname>, you simply also implement
- your interrupt handler and fill your
- <varname>struct uio_info</varname>. A pointer to this
- <varname>struct uio_info</varname> is then used as
- <varname>platform_data</varname> for your platform device.
- </para>
- <para>
- You also need to set up an array of <varname>struct resource</varname>
- containing addresses and sizes of your memory mappings. This
- information is passed to the driver using the
- <varname>.resource</varname> and <varname>.num_resources</varname>
- elements of <varname>struct platform_device</varname>.
- </para>
- <para>
- You now have to set the <varname>.name</varname> element of
- <varname>struct platform_device</varname> to
- <varname>"uio_pdrv"</varname> to use the generic UIO platform device
- driver. This driver will fill the <varname>mem[]</varname> array
- according to the resources given, and register the device.
- </para>
- <para>
- The advantage of this approach is that you only have to edit a file
- you need to edit anyway. You do not have to create an extra driver.
- </para>
-</sect1>
-
-<sect1 id="using_uio_pdrv_genirq">
-<title>Using uio_pdrv_genirq for platform devices</title>
- <para>
- Especially in embedded devices, you frequently find chips where the
- irq pin is tied to its own dedicated interrupt line. In such cases,
- where you can be really sure the interrupt is not shared, we can take
- the concept of <varname>uio_pdrv</varname> one step further and use a
- generic interrupt handler. That's what
- <varname>uio_pdrv_genirq</varname> does.
- </para>
- <para>
- The setup for this driver is the same as described above for
- <varname>uio_pdrv</varname>, except that you do not implement an
- interrupt handler. The <varname>.handler</varname> element of
- <varname>struct uio_info</varname> must remain
- <varname>NULL</varname>. The <varname>.irq_flags</varname> element
- must not contain <varname>IRQF_SHARED</varname>.
- </para>
- <para>
- You will set the <varname>.name</varname> element of
- <varname>struct platform_device</varname> to
- <varname>"uio_pdrv_genirq"</varname> to use this driver.
- </para>
- <para>
- The generic interrupt handler of <varname>uio_pdrv_genirq</varname>
- will simply disable the interrupt line using
- <function>disable_irq_nosync()</function>. After doing its work,
- userspace can reenable the interrupt by writing 0x00000001 to the UIO
- device file. The driver already implements an
- <function>irq_control()</function> to make this possible, you must not
- implement your own.
- </para>
- <para>
- Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of
- interrupt handler code. You also do not need to know anything about
- the chip's internal registers to create the kernel part of the driver.
- All you need to know is the irq number of the pin the chip is
- connected to.
- </para>
-</sect1>
-
-<sect1 id="using-uio_dmem_genirq">
-<title>Using uio_dmem_genirq for platform devices</title>
- <para>
- In addition to statically allocated memory ranges, they may also be
- a desire to use dynamically allocated regions in a user space driver.
- In particular, being able to access memory made available through the
- dma-mapping API, may be particularly useful. The
- <varname>uio_dmem_genirq</varname> driver provides a way to accomplish
- this.
- </para>
- <para>
- This driver is used in a similar manner to the
- <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt
- configuration and handling.
- </para>
- <para>
- Set the <varname>.name</varname> element of
- <varname>struct platform_device</varname> to
- <varname>"uio_dmem_genirq"</varname> to use this driver.
- </para>
- <para>
- When using this driver, fill in the <varname>.platform_data</varname>
- element of <varname>struct platform_device</varname>, which is of type
- <varname>struct uio_dmem_genirq_pdata</varname> and which contains the
- following elements:
- </para>
- <itemizedlist>
- <listitem><para><varname>struct uio_info uioinfo</varname>: The same
- structure used as the <varname>uio_pdrv_genirq</varname> platform
- data</para></listitem>
- <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>:
- Pointer to list of sizes of dynamic memory regions to be mapped into
- user space.
- </para></listitem>
- <listitem><para><varname>unsigned int num_dynamic_regions</varname>:
- Number of elements in <varname>dynamic_region_sizes</varname> array.
- </para></listitem>
- </itemizedlist>
- <para>
- The dynamic regions defined in the platform data will be appended to
- the <varname> mem[] </varname> array after the platform device
- resources, which implies that the total number of static and dynamic
- memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>.
- </para>
- <para>
- The dynamic memory regions will be allocated when the UIO device file,
- <varname>/dev/uioX</varname> is opened.
- Similar to static memory resources, the memory region information for
- dynamic regions is then visible via sysfs at
- <varname>/sys/class/uio/uioX/maps/mapY/*</varname>.
- The dynamic memory regions will be freed when the UIO device file is
- closed. When no processes are holding the device file open, the address
- returned to userspace is ~0.
- </para>
-</sect1>
-
-</chapter>
-
-<chapter id="userspace_driver" xreflabel="Writing a driver in user space">
-<?dbhtml filename="userspace_driver.html"?>
-<title>Writing a driver in userspace</title>
- <para>
- Once you have a working kernel module for your hardware, you can
- write the userspace part of your driver. You don't need any special
- libraries, your driver can be written in any reasonable language,
- you can use floating point numbers and so on. In short, you can
- use all the tools and libraries you'd normally use for writing a
- userspace application.
- </para>
-
-<sect1 id="getting_uio_information">
-<title>Getting information about your UIO device</title>
- <para>
- Information about all UIO devices is available in sysfs. The
- first thing you should do in your driver is check
- <varname>name</varname> and <varname>version</varname> to
- make sure your talking to the right device and that its kernel
- driver has the version you expect.
- </para>
- <para>
- You should also make sure that the memory mapping you need
- exists and has the size you expect.
- </para>
- <para>
- There is a tool called <varname>lsuio</varname> that lists
- UIO devices and their attributes. It is available here:
- </para>
- <para>
- <ulink url="http://www.osadl.org/projects/downloads/UIO/user/">
- http://www.osadl.org/projects/downloads/UIO/user/</ulink>
- </para>
- <para>
- With <varname>lsuio</varname> you can quickly check if your
- kernel module is loaded and which attributes it exports.
- Have a look at the manpage for details.
- </para>
- <para>
- The source code of <varname>lsuio</varname> can serve as an
- example for getting information about an UIO device.
- The file <filename>uio_helper.c</filename> contains a lot of
- functions you could use in your userspace driver code.
- </para>
-</sect1>
-
-<sect1 id="mmap_device_memory">
-<title>mmap() device memory</title>
- <para>
- After you made sure you've got the right device with the
- memory mappings you need, all you have to do is to call
- <function>mmap()</function> to map the device's memory
- to userspace.
- </para>
- <para>
- The parameter <varname>offset</varname> of the
- <function>mmap()</function> call has a special meaning
- for UIO devices: It is used to select which mapping of
- your device you want to map. To map the memory of
- mapping N, you have to use N times the page size as
- your offset:
- </para>
-<programlisting format="linespecific">
- offset = N * getpagesize();
-</programlisting>
- <para>
- N starts from zero, so if you've got only one memory
- range to map, set <varname>offset = 0</varname>.
- A drawback of this technique is that memory is always
- mapped beginning with its start address.
- </para>
-</sect1>
-
-<sect1 id="wait_for_interrupts">
-<title>Waiting for interrupts</title>
- <para>
- After you successfully mapped your devices memory, you
- can access it like an ordinary array. Usually, you will
- perform some initialization. After that, your hardware
- starts working and will generate an interrupt as soon
- as it's finished, has some data available, or needs your
- attention because an error occurred.
- </para>
- <para>
- <filename>/dev/uioX</filename> is a read-only file. A
- <function>read()</function> will always block until an
- interrupt occurs. There is only one legal value for the
- <varname>count</varname> parameter of
- <function>read()</function>, and that is the size of a
- signed 32 bit integer (4). Any other value for
- <varname>count</varname> causes <function>read()</function>
- to fail. The signed 32 bit integer read is the interrupt
- count of your device. If the value is one more than the value
- you read the last time, everything is OK. If the difference
- is greater than one, you missed interrupts.
- </para>
- <para>
- You can also use <function>select()</function> on
- <filename>/dev/uioX</filename>.
- </para>
-</sect1>
-
-</chapter>
-
-<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards">
-<?dbhtml filename="uio_pci_generic.html"?>
-<title>Generic PCI UIO driver</title>
- <para>
- The generic driver is a kernel module named uio_pci_generic.
- It can work with any device compliant to PCI 2.3 (circa 2002) and
- any compliant PCI Express device. Using this, you only need to
- write the userspace driver, removing the need to write
- a hardware-specific kernel module.
- </para>
-
-<sect1 id="uio_pci_generic_binding">
-<title>Making the driver recognize the device</title>
- <para>
-Since the driver does not declare any device ids, it will not get loaded
-automatically and will not automatically bind to any devices, you must load it
-and allocate id to the driver yourself. For example:
- <programlisting>
- modprobe uio_pci_generic
- echo &quot;8086 10f5&quot; &gt; /sys/bus/pci/drivers/uio_pci_generic/new_id
- </programlisting>
- </para>
- <para>
-If there already is a hardware specific kernel driver for your device, the
-generic driver still won't bind to it, in this case if you want to use the
-generic driver (why would you?) you'll have to manually unbind the hardware
-specific driver and bind the generic driver, like this:
- <programlisting>
- echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/e1000e/unbind
- echo -n 0000:00:19.0 &gt; /sys/bus/pci/drivers/uio_pci_generic/bind
- </programlisting>
- </para>
- <para>
-You can verify that the device has been bound to the driver
-by looking for it in sysfs, for example like the following:
- <programlisting>
- ls -l /sys/bus/pci/devices/0000:00:19.0/driver
- </programlisting>
-Which if successful should print
- <programlisting>
- .../0000:00:19.0/driver -&gt; ../../../bus/pci/drivers/uio_pci_generic
- </programlisting>
-Note that the generic driver will not bind to old PCI 2.2 devices.
-If binding the device failed, run the following command:
- <programlisting>
- dmesg
- </programlisting>
-and look in the output for failure reasons
- </para>
-</sect1>
-
-<sect1 id="uio_pci_generic_internals">
-<title>Things to know about uio_pci_generic</title>
- <para>
-Interrupts are handled using the Interrupt Disable bit in the PCI command
-register and Interrupt Status bit in the PCI status register. All devices
-compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should
-support these bits. uio_pci_generic detects this support, and won't bind to
-devices which do not support the Interrupt Disable Bit in the command register.
- </para>
- <para>
-On each interrupt, uio_pci_generic sets the Interrupt Disable bit.
-This prevents the device from generating further interrupts
-until the bit is cleared. The userspace driver should clear this
-bit before blocking and waiting for more interrupts.
- </para>
-</sect1>
-<sect1 id="uio_pci_generic_userspace">
-<title>Writing userspace driver using uio_pci_generic</title>
- <para>
-Userspace driver can use pci sysfs interface, or the
-libpci libray that wraps it, to talk to the device and to
-re-enable interrupts by writing to the command register.
- </para>
-</sect1>
-<sect1 id="uio_pci_generic_example">
-<title>Example code using uio_pci_generic</title>
- <para>
-Here is some sample userspace driver code using uio_pci_generic:
-<programlisting>
-#include &lt;stdlib.h&gt;
-#include &lt;stdio.h&gt;
-#include &lt;unistd.h&gt;
-#include &lt;sys/types.h&gt;
-#include &lt;sys/stat.h&gt;
-#include &lt;fcntl.h&gt;
-#include &lt;errno.h&gt;
-
-int main()
-{
- int uiofd;
- int configfd;
- int err;
- int i;
- unsigned icount;
- unsigned char command_high;
-
- uiofd = open(&quot;/dev/uio0&quot;, O_RDONLY);
- if (uiofd &lt; 0) {
- perror(&quot;uio open:&quot;);
- return errno;
- }
- configfd = open(&quot;/sys/class/uio/uio0/device/config&quot;, O_RDWR);
- if (configfd &lt; 0) {
- perror(&quot;config open:&quot;);
- return errno;
- }
-
- /* Read and cache command value */
- err = pread(configfd, &amp;command_high, 1, 5);
- if (err != 1) {
- perror(&quot;command config read:&quot;);
- return errno;
- }
- command_high &amp;= ~0x4;
-
- for(i = 0;; ++i) {
- /* Print out a message, for debugging. */
- if (i == 0)
- fprintf(stderr, &quot;Started uio test driver.\n&quot;);
- else
- fprintf(stderr, &quot;Interrupts: %d\n&quot;, icount);
-
- /****************************************/
- /* Here we got an interrupt from the
- device. Do something to it. */
- /****************************************/
-
- /* Re-enable interrupts. */
- err = pwrite(configfd, &amp;command_high, 1, 5);
- if (err != 1) {
- perror(&quot;config write:&quot;);
- break;
- }
-
- /* Wait for next interrupt. */
- err = read(uiofd, &amp;icount, 4);
- if (err != 4) {
- perror(&quot;uio read:&quot;);
- break;
- }
-
- }
- return errno;
-}
-
-</programlisting>
- </para>
-</sect1>
-
-</chapter>
-
-<appendix id="app1">
-<title>Further information</title>
-<itemizedlist>
- <listitem><para>
- <ulink url="http://www.osadl.org">
- OSADL homepage.</ulink>
- </para></listitem>
- <listitem><para>
- <ulink url="http://www.linutronix.de">
- Linutronix homepage.</ulink>
- </para></listitem>
-</itemizedlist>
-</appendix>
-
-</book>
diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl
deleted file mode 100644
index 4cd5b2cd0f3d..000000000000
--- a/Documentation/DocBook/usb.tmpl
+++ /dev/null
@@ -1,980 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Linux-USB-API">
- <bookinfo>
- <title>The Linux-USB Host Side API</title>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
-<chapter id="intro">
- <title>Introduction to USB on Linux</title>
-
- <para>A Universal Serial Bus (USB) is used to connect a host,
- such as a PC or workstation, to a number of peripheral
- devices. USB uses a tree 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
- one USB 2.0 tree (480 Mbit/sec each) with
- a few USB 1.1 trees (12 Mbit/sec each) that are used when you
- connect a USB 1.1 device directly to the machine's "root hub".
- </para>
-
- <para>That master/slave asymmetry was designed-in for a number of
- reasons, one being ease of use. It is not physically possible to
- assemble (legal) USB cables incorrectly: all upstream "to the host"
- connectors are the rectangular type (matching the sockets on
- root hubs), and all downstream connectors are the squarish type
- (or they are built into the peripheral).
- Also, the host software doesn't need to deal with distributed
- auto-configuration since the pre-designated master node manages all that.
- And finally, at the electrical level, bus protocol overhead is reduced by
- eliminating arbitration and moving scheduling into the host software.
- </para>
-
- <para>USB 1.0 was announced in January 1996 and was revised
- as USB 1.1 (with improvements in hub specification and
- support for interrupt-out transfers) in September 1998.
- USB 2.0 was released in April 2000, adding high-speed
- transfers and transaction-translating hubs (used for USB 1.1
- and 1.0 backward compatibility).
- </para>
-
- <para>Kernel developers added USB support to Linux early in the 2.2 kernel
- series, shortly before 2.3 development forked. Updates from 2.3 were
- regularly folded back into 2.2 releases, which improved reliability and
- brought <filename>/sbin/hotplug</filename> support as well more drivers.
- Such improvements were continued in the 2.5 kernel series, where they added
- USB 2.0 support, improved performance, and made the host controller drivers
- (HCDs) more consistent. They also simplified the API (to make bugs less
- likely) and added internal "kerneldoc" documentation.
- </para>
-
- <para>Linux can run inside USB devices as well as on
- the hosts that control the devices.
- But USB device drivers running inside those peripherals
- don't do the same things as the ones running inside hosts,
- so they've been given a different name:
- <emphasis>gadget drivers</emphasis>.
- This document does not cover gadget drivers.
- </para>
-
- </chapter>
-
-<chapter id="host">
- <title>USB Host-Side API Model</title>
-
- <para>Host-side drivers for USB devices talk to the "usbcore" APIs.
- There are two. One is intended for
- <emphasis>general-purpose</emphasis> drivers (exposed through
- driver frameworks), and the other is for drivers that are
- <emphasis>part of the core</emphasis>.
- Such core drivers include the <emphasis>hub</emphasis> driver
- (which manages trees of USB devices) and several different kinds
- of <emphasis>host controller drivers</emphasis>,
- which control individual busses.
- </para>
-
- <para>The device model seen by USB drivers is relatively complex.
- </para>
-
- <itemizedlist>
-
- <listitem><para>USB supports four kinds of data transfers
- (control, bulk, interrupt, and isochronous). Two of them (control
- and bulk) use bandwidth as it's available,
- while the other two (interrupt and isochronous)
- are scheduled to provide guaranteed bandwidth.
- </para></listitem>
-
- <listitem><para>The device description model includes one or more
- "configurations" per device, only one of which is active at a time.
- Devices that are capable of high-speed operation must also support
- full-speed configurations, along with a way to ask about the
- "other speed" configurations which might be used.
- </para></listitem>
-
- <listitem><para>Configurations have one or more "interfaces", each
- of which may have "alternate settings". Interfaces may be
- standardized by USB "Class" specifications, or may be specific to
- a vendor or device.</para>
-
- <para>USB device drivers actually bind to interfaces, not devices.
- Think of them as "interface drivers", though you
- may not see many devices where the distinction is important.
- <emphasis>Most USB devices are simple, with only one configuration,
- one interface, and one alternate setting.</emphasis>
- </para></listitem>
-
- <listitem><para>Interfaces have one or more "endpoints", each of
- which supports one type and direction of data transfer such as
- "bulk out" or "interrupt in". The entire configuration may have
- up to sixteen endpoints in each direction, allocated as needed
- among all the interfaces.
- </para></listitem>
-
- <listitem><para>Data transfer on USB is packetized; each endpoint
- has a maximum packet size.
- Drivers must often be aware of conventions such as flagging the end
- of bulk transfers using "short" (including zero length) packets.
- </para></listitem>
-
- <listitem><para>The Linux USB API supports synchronous calls for
- control and bulk messages.
- It also supports asynchronous calls for all kinds of data transfer,
- using request structures called "URBs" (USB Request Blocks).
- </para></listitem>
-
- </itemizedlist>
-
- <para>Accordingly, the USB Core API exposed to device drivers
- covers quite a lot of territory. You'll probably need to consult
- the USB 2.0 specification, available online from www.usb.org at
- no cost, as well as class or device specifications.
- </para>
-
- <para>The only host-side drivers that actually touch hardware
- (reading/writing registers, handling IRQs, and so on) are the HCDs.
- In theory, all HCDs provide the same functionality through the same
- API. In practice, that's becoming more true on the 2.5 kernels,
- but there are still differences that crop up especially with
- fault handling. Different controllers don't necessarily report
- the same aspects of failures, and recovery from faults (including
- software-induced ones like unlinking an URB) isn't yet fully
- consistent.
- Device driver authors should make a point of doing disconnect
- testing (while the device is active) with each different host
- controller driver, to make sure drivers don't have bugs of
- their own as well as to make sure they aren't relying on some
- HCD-specific behavior.
- (You will need external USB 1.1 and/or
- USB 2.0 hubs to perform all those tests.)
- </para>
-
- </chapter>
-
-<chapter id="types"><title>USB-Standard Types</title>
-
- <para>In <filename>&lt;linux/usb/ch9.h&gt;</filename> you will find
- the USB data types defined in chapter 9 of the USB specification.
- These data types are used throughout USB, and in APIs including
- this host side API, gadget APIs, and usbfs.
- </para>
-
-!Iinclude/linux/usb/ch9.h
-
- </chapter>
-
-<chapter id="hostside"><title>Host-Side Data Types and Macros</title>
-
- <para>The host side API exposes several layers to drivers, some of
- which are more necessary than others.
- These support lifecycle models for host side drivers
- and devices, and support passing buffers through usbcore to
- some HCD that performs the I/O for the device driver.
- </para>
-
-
-!Iinclude/linux/usb.h
-
- </chapter>
-
- <chapter id="usbcore"><title>USB Core APIs</title>
-
- <para>There are two basic I/O models in the USB API.
- The most elemental one is asynchronous: drivers submit requests
- in the form of an URB, and the URB's completion callback
- handle the next step.
- All USB transfer types support that model, although there
- are special cases for control URBs (which always have setup
- and status stages, but may not have a data stage) and
- isochronous URBs (which allow large packets and include
- per-packet fault reports).
- Built on top of that is synchronous API support, where a
- driver calls a routine that allocates one or more URBs,
- submits them, and waits until they complete.
- There are synchronous wrappers for single-buffer control
- and bulk transfers (which are awkward to use in some
- driver disconnect scenarios), and for scatterlist based
- streaming i/o (bulk or interrupt).
- </para>
-
- <para>USB drivers need to provide buffers that can be
- used for DMA, although they don't necessarily need to
- provide the DMA mapping themselves.
- There are APIs to use used when allocating DMA buffers,
- which can prevent use of bounce buffers on some systems.
- In some cases, drivers may be able to rely on 64bit DMA
- to eliminate another kind of bounce buffer.
- </para>
-
-!Edrivers/usb/core/urb.c
-!Edrivers/usb/core/message.c
-!Edrivers/usb/core/file.c
-!Edrivers/usb/core/driver.c
-!Edrivers/usb/core/usb.c
-!Edrivers/usb/core/hub.c
- </chapter>
-
- <chapter id="hcd"><title>Host Controller APIs</title>
-
- <para>These APIs are only for use by host controller drivers,
- most of which implement standard register interfaces such as
- EHCI, OHCI, or UHCI.
- UHCI was one of the first interfaces, designed by Intel and
- also used by VIA; it doesn't do much in hardware.
- OHCI was designed later, to have the hardware do more work
- (bigger transfers, tracking protocol state, and so on).
- EHCI was designed with USB 2.0; its design has features that
- resemble OHCI (hardware does much more work) as well as
- UHCI (some parts of ISO support, TD list processing).
- </para>
-
- <para>There are host controllers other than the "big three",
- although most PCI based controllers (and a few non-PCI based
- ones) use one of those interfaces.
- Not all host controllers use DMA; some use PIO, and there
- is also a simulator.
- </para>
-
- <para>The same basic APIs are available to drivers for all
- those controllers.
- For historical reasons they are in two layers:
- <structname>struct usb_bus</structname> is a rather thin
- layer that became available in the 2.2 kernels, while
- <structname>struct usb_hcd</structname> is a more featureful
- layer (available in later 2.4 kernels and in 2.5) that
- lets HCDs share common code, to shrink driver size
- and significantly reduce hcd-specific behaviors.
- </para>
-
-!Edrivers/usb/core/hcd.c
-!Edrivers/usb/core/hcd-pci.c
-!Idrivers/usb/core/buffer.c
- </chapter>
-
- <chapter id="usbfs">
- <title>The USB Filesystem (usbfs)</title>
-
- <para>This chapter presents the Linux <emphasis>usbfs</emphasis>.
- You may prefer to avoid writing new kernel code for your
- USB driver; that's the problem that usbfs set out to solve.
- User mode device drivers are usually packaged as applications
- or libraries, and may use usbfs through some programming library
- that wraps it. Such libraries include
- <ulink url="http://libusb.sourceforge.net">libusb</ulink>
- for C/C++, and
- <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java.
- </para>
-
- <note><title>Unfinished</title>
- <para>This particular documentation is incomplete,
- especially with respect to the asynchronous mode.
- As of kernel 2.5.66 the code and this (new) documentation
- need to be cross-reviewed.
- </para>
- </note>
-
- <para>Configure usbfs into Linux kernels by enabling the
- <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS),
- and you get basic support for user mode USB device drivers.
- Until relatively recently it was often (confusingly) called
- <emphasis>usbdevfs</emphasis> although it wasn't solving what
- <emphasis>devfs</emphasis> was.
- Every USB device will appear in usbfs, regardless of whether or
- not it has a kernel driver.
- </para>
-
- <sect1 id="usbfs-files">
- <title>What files are in "usbfs"?</title>
-
- <para>Conventionally mounted at
- <filename>/proc/bus/usb</filename>, usbfs
- features include:
- <itemizedlist>
- <listitem><para><filename>/proc/bus/usb/devices</filename>
- ... a text file
- showing each of the USB devices on known to the kernel,
- and their configuration descriptors.
- You can also poll() this to learn about new devices.
- </para></listitem>
- <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename>
- ... magic files
- exposing the each device's configuration descriptors, and
- supporting a series of ioctls for making device requests,
- including I/O to devices. (Purely for access by programs.)
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para> Each bus is given a number (BBB) based on when it was
- enumerated; within each bus, each device is given a similar
- number (DDD).
- Those BBB/DDD paths are not "stable" identifiers;
- expect them to change even if you always leave the devices
- plugged in to the same hub port.
- <emphasis>Don't even think of saving these in application
- configuration files.</emphasis>
- Stable identifiers are available, for user mode applications
- that want to use them. HID and networking devices expose
- these stable IDs, so that for example you can be sure that
- you told the right UPS to power down its second server.
- "usbfs" doesn't (yet) expose those IDs.
- </para>
-
- </sect1>
-
- <sect1 id="usbfs-fstab">
- <title>Mounting and Access Control</title>
-
- <para>There are a number of mount options for usbfs, which will
- be of most interest to you if you need to override the default
- access control policy.
- That policy is that only root may read or write device files
- (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read
- the <filename>devices</filename>
- or <filename>drivers</filename> files.
- I/O requests to the device also need the CAP_SYS_RAWIO capability,
- </para>
-
- <para>The significance of that is that by default, all user mode
- device drivers need super-user privileges.
- You can change modes or ownership in a driver setup
- when the device hotplugs, or maye just start the
- driver right then, as a privileged server (or some activity
- within one).
- That's the most secure approach for multi-user systems,
- but for single user systems ("trusted" by that user)
- it's more convenient just to grant everyone all access
- (using the <emphasis>devmode=0666</emphasis> option)
- so the driver can start whenever it's needed.
- </para>
-
- <para>The mount options for usbfs, usable in /etc/fstab or
- in command line invocations of <emphasis>mount</emphasis>, are:
-
- <variablelist>
- <varlistentry>
- <term><emphasis>busgid</emphasis>=NNNNN</term>
- <listitem><para>Controls the GID used for the
- /proc/bus/usb/BBB
- directories. (Default: 0)</para></listitem></varlistentry>
- <varlistentry><term><emphasis>busmode</emphasis>=MMM</term>
- <listitem><para>Controls the file mode used for the
- /proc/bus/usb/BBB
- directories. (Default: 0555)
- </para></listitem></varlistentry>
- <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term>
- <listitem><para>Controls the UID used for the
- /proc/bus/usb/BBB
- directories. (Default: 0)</para></listitem></varlistentry>
-
- <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term>
- <listitem><para>Controls the GID used for the
- /proc/bus/usb/BBB/DDD
- files. (Default: 0)</para></listitem></varlistentry>
- <varlistentry><term><emphasis>devmode</emphasis>=MMM</term>
- <listitem><para>Controls the file mode used for the
- /proc/bus/usb/BBB/DDD
- files. (Default: 0644)</para></listitem></varlistentry>
- <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term>
- <listitem><para>Controls the UID used for the
- /proc/bus/usb/BBB/DDD
- files. (Default: 0)</para></listitem></varlistentry>
-
- <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term>
- <listitem><para>Controls the GID used for the
- /proc/bus/usb/devices and drivers files.
- (Default: 0)</para></listitem></varlistentry>
- <varlistentry><term><emphasis>listmode</emphasis>=MMM</term>
- <listitem><para>Controls the file mode used for the
- /proc/bus/usb/devices and drivers files.
- (Default: 0444)</para></listitem></varlistentry>
- <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term>
- <listitem><para>Controls the UID used for the
- /proc/bus/usb/devices and drivers files.
- (Default: 0)</para></listitem></varlistentry>
- </variablelist>
-
- </para>
-
- <para>Note that many Linux distributions hard-wire the mount options
- for usbfs in their init scripts, such as
- <filename>/etc/rc.d/rc.sysinit</filename>,
- rather than making it easy to set this per-system
- policy in <filename>/etc/fstab</filename>.
- </para>
-
- </sect1>
-
- <sect1 id="usbfs-devices">
- <title>/proc/bus/usb/devices</title>
-
- <para>This file is handy for status viewing tools in user
- mode, which can scan the text format and ignore most of it.
- More detailed device status (including class and vendor
- status) is available from device-specific files.
- For information about the current format of this file,
- see the
- <filename>Documentation/usb/proc_usb_info.txt</filename>
- file in your Linux kernel sources.
- </para>
-
- <para>This file, in combination with the poll() system call, can
- also be used to detect when devices are added or removed:
-<programlisting>int fd;
-struct pollfd pfd;
-
-fd = open("/proc/bus/usb/devices", O_RDONLY);
-pfd = { fd, POLLIN, 0 };
-for (;;) {
- /* The first time through, this call will return immediately. */
- poll(&amp;pfd, 1, -1);
-
- /* To see what's changed, compare the file's previous and current
- contents or scan the filesystem. (Scanning is more precise.) */
-}</programlisting>
- Note that this behavior is intended to be used for informational
- and debug purposes. It would be more appropriate to use programs
- such as udev or HAL to initialize a device or start a user-mode
- helper program, for instance.
- </para>
- </sect1>
-
- <sect1 id="usbfs-bbbddd">
- <title>/proc/bus/usb/BBB/DDD</title>
-
- <para>Use these files in one of these basic ways:
- </para>
-
- <para><emphasis>They can be read,</emphasis>
- producing first the device descriptor
- (18 bytes) and then the descriptors for the current configuration.
- See the USB 2.0 spec for details about those binary data formats.
- You'll need to convert most multibyte values from little endian
- format to your native host byte order, although a few of the
- fields in the device descriptor (both of the BCD-encoded fields,
- and the vendor and product IDs) will be byteswapped for you.
- Note that configuration descriptors include descriptors for
- interfaces, altsettings, endpoints, and maybe additional
- class descriptors.
- </para>
-
- <para><emphasis>Perform USB operations</emphasis> using
- <emphasis>ioctl()</emphasis> requests to make endpoint I/O
- requests (synchronously or asynchronously) or manage
- the device.
- These requests need the CAP_SYS_RAWIO capability,
- as well as filesystem access permissions.
- Only one ioctl request can be made on one of these
- device files at a time.
- This means that if you are synchronously reading an endpoint
- from one thread, you won't be able to write to a different
- endpoint from another thread until the read completes.
- This works for <emphasis>half duplex</emphasis> protocols,
- but otherwise you'd use asynchronous i/o requests.
- </para>
-
- </sect1>
-
-
- <sect1 id="usbfs-lifecycle">
- <title>Life Cycle of User Mode Drivers</title>
-
- <para>Such a driver first needs to find a device file
- for a device it knows how to handle.
- Maybe it was told about it because a
- <filename>/sbin/hotplug</filename> event handling agent
- chose that driver to handle the new device.
- Or maybe it's an application that scans all the
- /proc/bus/usb device files, and ignores most devices.
- In either case, it should <function>read()</function> all
- the descriptors from the device file,
- and check them against what it knows how to handle.
- It might just reject everything except a particular
- vendor and product ID, or need a more complex policy.
- </para>
-
- <para>Never assume there will only be one such device
- on the system at a time!
- If your code can't handle more than one device at
- a time, at least detect when there's more than one, and
- have your users choose which device to use.
- </para>
-
- <para>Once your user mode driver knows what device to use,
- it interacts with it in either of two styles.
- The simple style is to make only control requests; some
- devices don't need more complex interactions than those.
- (An example might be software using vendor-specific control
- requests for some initialization or configuration tasks,
- with a kernel driver for the rest.)
- </para>
-
- <para>More likely, you need a more complex style driver:
- one using non-control endpoints, reading or writing data
- and claiming exclusive use of an interface.
- <emphasis>Bulk</emphasis> transfers are easiest to use,
- but only their sibling <emphasis>interrupt</emphasis> transfers
- work with low speed devices.
- Both interrupt and <emphasis>isochronous</emphasis> transfers
- offer service guarantees because their bandwidth is reserved.
- Such "periodic" transfers are awkward to use through usbfs,
- unless you're using the asynchronous calls. However, interrupt
- transfers can also be used in a synchronous "one shot" style.
- </para>
-
- <para>Your user-mode driver should never need to worry
- about cleaning up request state when the device is
- disconnected, although it should close its open file
- descriptors as soon as it starts seeing the ENODEV
- errors.
- </para>
-
- </sect1>
-
- <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title>
-
- <para>To use these ioctls, you need to include the following
- headers in your userspace program:
-<programlisting>#include &lt;linux/usb.h&gt;
-#include &lt;linux/usbdevice_fs.h&gt;
-#include &lt;asm/byteorder.h&gt;</programlisting>
- The standard USB device model requests, from "Chapter 9" of
- the USB 2.0 specification, are automatically included from
- the <filename>&lt;linux/usb/ch9.h&gt;</filename> header.
- </para>
-
- <para>Unless noted otherwise, the ioctl requests
- described here will
- update the modification time on the usbfs file to which
- they are applied (unless they fail).
- A return of zero indicates success; otherwise, a
- standard USB error code is returned. (These are
- documented in
- <filename>Documentation/usb/error-codes.txt</filename>
- in your kernel sources.)
- </para>
-
- <para>Each of these files multiplexes access to several
- I/O streams, one per endpoint.
- Each device has one control endpoint (endpoint zero)
- which supports a limited RPC style RPC access.
- Devices are configured
- by hub_wq (in the kernel) setting a device-wide
- <emphasis>configuration</emphasis> that affects things
- like power consumption and basic functionality.
- The endpoints are part of USB <emphasis>interfaces</emphasis>,
- which may have <emphasis>altsettings</emphasis>
- affecting things like which endpoints are available.
- Many devices only have a single configuration and interface,
- so drivers for them will ignore configurations and altsettings.
- </para>
-
-
- <sect2 id="usbfs-mgmt">
- <title>Management/Status Requests</title>
-
- <para>A number of usbfs requests don't deal very directly
- with device I/O.
- They mostly relate to device management and status.
- These are all synchronous requests.
- </para>
-
- <variablelist>
-
- <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term>
- <listitem><para>This is used to force usbfs to
- claim a specific interface,
- which has not previously been claimed by usbfs or any other
- kernel driver.
- The ioctl parameter is an integer holding the number of
- the interface (bInterfaceNumber from descriptor).
- </para><para>
- Note that if your driver doesn't claim an interface
- before trying to use one of its endpoints, and no
- other driver has bound to it, then the interface is
- automatically claimed by usbfs.
- </para><para>
- This claim will be released by a RELEASEINTERFACE ioctl,
- or by closing the file descriptor.
- File modification time is not updated by this request.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_CONNECTINFO</term>
- <listitem><para>Says whether the device is lowspeed.
- The ioctl parameter points to a structure like this:
-<programlisting>struct usbdevfs_connectinfo {
- unsigned int devnum;
- unsigned char slow;
-}; </programlisting>
- File modification time is not updated by this request.
- </para><para>
- <emphasis>You can't tell whether a "not slow"
- device is connected at high speed (480 MBit/sec)
- or just full speed (12 MBit/sec).</emphasis>
- You should know the devnum value already,
- it's the DDD value of the device file name.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_GETDRIVER</term>
- <listitem><para>Returns the name of the kernel driver
- bound to a given interface (a string). Parameter
- is a pointer to this structure, which is modified:
-<programlisting>struct usbdevfs_getdriver {
- unsigned int interface;
- char driver[USBDEVFS_MAXDRIVERNAME + 1];
-};</programlisting>
- File modification time is not updated by this request.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_IOCTL</term>
- <listitem><para>Passes a request from userspace through
- to a kernel driver that has an ioctl entry in the
- <emphasis>struct usb_driver</emphasis> it registered.
-<programlisting>struct usbdevfs_ioctl {
- int ifno;
- int ioctl_code;
- void *data;
-};
-
-/* user mode call looks like this.
- * 'request' becomes the driver->ioctl() 'code' parameter.
- * the size of 'param' is encoded in 'request', and that data
- * is copied to or from the driver->ioctl() 'buf' parameter.
- */
-static int
-usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
-{
- struct usbdevfs_ioctl wrapper;
-
- wrapper.ifno = ifno;
- wrapper.ioctl_code = request;
- wrapper.data = param;
-
- return ioctl (fd, USBDEVFS_IOCTL, &amp;wrapper);
-} </programlisting>
- File modification time is not updated by this request.
- </para><para>
- This request lets kernel drivers talk to user mode code
- through filesystem operations even when they don't create
- a character or block special device.
- It's also been used to do things like ask devices what
- device special file should be used.
- Two pre-defined ioctls are used
- to disconnect and reconnect kernel drivers, so
- that user mode code can completely manage binding
- and configuration of devices.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
- <listitem><para>This is used to release the claim usbfs
- made on interface, either implicitly or because of a
- USBDEVFS_CLAIMINTERFACE call, before the file
- descriptor is closed.
- The ioctl parameter is an integer holding the number of
- the interface (bInterfaceNumber from descriptor);
- File modification time is not updated by this request.
- </para><warning><para>
- <emphasis>No security check is made to ensure
- that the task which made the claim is the one
- which is releasing it.
- This means that user mode driver may interfere
- other ones. </emphasis>
- </para></warning></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_RESETEP</term>
- <listitem><para>Resets the data toggle value for an endpoint
- (bulk or interrupt) to DATA0.
- The ioctl parameter is an integer endpoint number
- (1 to 15, as identified in the endpoint descriptor),
- with USB_DIR_IN added if the device's endpoint sends
- data to the host.
- </para><warning><para>
- <emphasis>Avoid using this request.
- It should probably be removed.</emphasis>
- Using it typically means the device and driver will lose
- toggle synchronization. If you really lost synchronization,
- you likely need to completely handshake with the device,
- using a request like CLEAR_HALT
- or SET_INTERFACE.
- </para></warning></listitem></varlistentry>
-
- </variablelist>
-
- </sect2>
-
- <sect2 id="usbfs-sync">
- <title>Synchronous I/O Support</title>
-
- <para>Synchronous requests involve the kernel blocking
- until the user mode request completes, either by
- finishing successfully or by reporting an error.
- In most cases this is the simplest way to use usbfs,
- although as noted above it does prevent performing I/O
- to more than one endpoint at a time.
- </para>
-
- <variablelist>
-
- <varlistentry><term>USBDEVFS_BULK</term>
- <listitem><para>Issues a bulk read or write request to the
- device.
- The ioctl parameter is a pointer to this structure:
-<programlisting>struct usbdevfs_bulktransfer {
- unsigned int ep;
- unsigned int len;
- unsigned int timeout; /* in milliseconds */
- void *data;
-};</programlisting>
- </para><para>The "ep" value identifies a
- bulk endpoint number (1 to 15, as identified in an endpoint
- descriptor),
- masked with USB_DIR_IN when referring to an endpoint which
- sends data to the host from the device.
- The length of the data buffer is identified by "len";
- Recent kernels support requests up to about 128KBytes.
- <emphasis>FIXME say how read length is returned,
- and how short reads are handled.</emphasis>.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_CLEAR_HALT</term>
- <listitem><para>Clears endpoint halt (stall) and
- resets the endpoint toggle. This is only
- meaningful for bulk or interrupt endpoints.
- The ioctl parameter is an integer endpoint number
- (1 to 15, as identified in an endpoint descriptor),
- masked with USB_DIR_IN when referring to an endpoint which
- sends data to the host from the device.
- </para><para>
- Use this on bulk or interrupt endpoints which have
- stalled, returning <emphasis>-EPIPE</emphasis> status
- to a data transfer request.
- Do not issue the control request directly, since
- that could invalidate the host's record of the
- data toggle.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_CONTROL</term>
- <listitem><para>Issues a control request to the device.
- The ioctl parameter points to a structure like this:
-<programlisting>struct usbdevfs_ctrltransfer {
- __u8 bRequestType;
- __u8 bRequest;
- __u16 wValue;
- __u16 wIndex;
- __u16 wLength;
- __u32 timeout; /* in milliseconds */
- void *data;
-};</programlisting>
- </para><para>
- The first eight bytes of this structure are the contents
- of the SETUP packet to be sent to the device; see the
- USB 2.0 specification for details.
- The bRequestType value is composed by combining a
- USB_TYPE_* value, a USB_DIR_* value, and a
- USB_RECIP_* value (from
- <emphasis>&lt;linux/usb.h&gt;</emphasis>).
- If wLength is nonzero, it describes the length of the data
- buffer, which is either written to the device
- (USB_DIR_OUT) or read from the device (USB_DIR_IN).
- </para><para>
- At this writing, you can't transfer more than 4 KBytes
- of data to or from a device; usbfs has a limit, and
- some host controller drivers have a limit.
- (That's not usually a problem.)
- <emphasis>Also</emphasis> there's no way to say it's
- not OK to get a short read back from the device.
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_RESET</term>
- <listitem><para>Does a USB level device reset.
- The ioctl parameter is ignored.
- After the reset, this rebinds all device interfaces.
- File modification time is not updated by this request.
- </para><warning><para>
- <emphasis>Avoid using this call</emphasis>
- until some usbcore bugs get fixed,
- since it does not fully synchronize device, interface,
- and driver (not just usbfs) state.
- </para></warning></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_SETINTERFACE</term>
- <listitem><para>Sets the alternate setting for an
- interface. The ioctl parameter is a pointer to a
- structure like this:
-<programlisting>struct usbdevfs_setinterface {
- unsigned int interface;
- unsigned int altsetting;
-}; </programlisting>
- File modification time is not updated by this request.
- </para><para>
- Those struct members are from some interface descriptor
- applying to the current configuration.
- The interface number is the bInterfaceNumber value, and
- the altsetting number is the bAlternateSetting value.
- (This resets each endpoint in the interface.)
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
- <listitem><para>Issues the
- <function>usb_set_configuration</function> call
- for the device.
- The parameter is an integer holding the number of
- a configuration (bConfigurationValue from descriptor).
- File modification time is not updated by this request.
- </para><warning><para>
- <emphasis>Avoid using this call</emphasis>
- until some usbcore bugs get fixed,
- since it does not fully synchronize device, interface,
- and driver (not just usbfs) state.
- </para></warning></listitem></varlistentry>
-
- </variablelist>
- </sect2>
-
- <sect2 id="usbfs-async">
- <title>Asynchronous I/O Support</title>
-
- <para>As mentioned above, there are situations where it may be
- important to initiate concurrent operations from user mode code.
- This is particularly important for periodic transfers
- (interrupt and isochronous), but it can be used for other
- kinds of USB requests too.
- In such cases, the asynchronous requests described here
- are essential. Rather than submitting one request and having
- the kernel block until it completes, the blocking is separate.
- </para>
-
- <para>These requests are packaged into a structure that
- resembles the URB used by kernel device drivers.
- (No POSIX Async I/O support here, sorry.)
- It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
- endpoint (number, masked with USB_DIR_IN as appropriate),
- buffer and length, and a user "context" value serving to
- uniquely identify each request.
- (It's usually a pointer to per-request data.)
- Flags can modify requests (not as many as supported for
- kernel drivers).
- </para>
-
- <para>Each request can specify a realtime signal number
- (between SIGRTMIN and SIGRTMAX, inclusive) to request a
- signal be sent when the request completes.
- </para>
-
- <para>When usbfs returns these urbs, the status value
- is updated, and the buffer may have been modified.
- Except for isochronous transfers, the actual_length is
- updated to say how many bytes were transferred; if the
- USBDEVFS_URB_DISABLE_SPD flag is set
- ("short packets are not OK"), if fewer bytes were read
- than were requested then you get an error report.
- </para>
-
-<programlisting>struct usbdevfs_iso_packet_desc {
- unsigned int length;
- unsigned int actual_length;
- unsigned int status;
-};
-
-struct usbdevfs_urb {
- unsigned char type;
- unsigned char endpoint;
- int status;
- unsigned int flags;
- void *buffer;
- int buffer_length;
- int actual_length;
- int start_frame;
- int number_of_packets;
- int error_count;
- unsigned int signr;
- void *usercontext;
- struct usbdevfs_iso_packet_desc iso_frame_desc[];
-};</programlisting>
-
- <para> For these asynchronous requests, the file modification
- time reflects when the request was initiated.
- This contrasts with their use with the synchronous requests,
- where it reflects when requests complete.
- </para>
-
- <variablelist>
-
- <varlistentry><term>USBDEVFS_DISCARDURB</term>
- <listitem><para>
- <emphasis>TBS</emphasis>
- File modification time is not updated by this request.
- </para><para>
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_DISCSIGNAL</term>
- <listitem><para>
- <emphasis>TBS</emphasis>
- File modification time is not updated by this request.
- </para><para>
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_REAPURB</term>
- <listitem><para>
- <emphasis>TBS</emphasis>
- File modification time is not updated by this request.
- </para><para>
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
- <listitem><para>
- <emphasis>TBS</emphasis>
- File modification time is not updated by this request.
- </para><para>
- </para></listitem></varlistentry>
-
- <varlistentry><term>USBDEVFS_SUBMITURB</term>
- <listitem><para>
- <emphasis>TBS</emphasis>
- </para><para>
- </para></listitem></varlistentry>
-
- </variablelist>
- </sect2>
-
- </sect1>
-
- </chapter>
-
-</book>
-<!-- vim:syntax=sgml:sw=4
--->
diff --git a/Documentation/DocBook/w1.tmpl b/Documentation/DocBook/w1.tmpl
deleted file mode 100644
index b0228d4c81bb..000000000000
--- a/Documentation/DocBook/w1.tmpl
+++ /dev/null
@@ -1,101 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="w1id">
- <bookinfo>
- <title>W1: Dallas' 1-wire bus</title>
-
- <authorgroup>
- <author>
- <firstname>David</firstname>
- <surname>Fries</surname>
- <affiliation>
- <address>
- <email>David@Fries.net</email>
- </address>
- </affiliation>
- </author>
-
- </authorgroup>
-
- <copyright>
- <year>2013</year>
- <!--
- <holder></holder>
- -->
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
-
- <chapter id="w1_internal">
- <title>W1 API internal to the kernel</title>
-
- <sect1 id="w1_internal_api">
- <title>W1 API internal to the kernel</title>
- <sect2 id="w1.h">
- <title>drivers/w1/w1.h</title>
- <para>W1 core functions.</para>
-!Idrivers/w1/w1.h
- </sect2>
-
- <sect2 id="w1.c">
- <title>drivers/w1/w1.c</title>
- <para>W1 core functions.</para>
-!Idrivers/w1/w1.c
- </sect2>
-
- <sect2 id="w1_family.h">
- <title>drivers/w1/w1_family.h</title>
- <para>Allows registering device family operations.</para>
-!Idrivers/w1/w1_family.h
- </sect2>
-
- <sect2 id="w1_family.c">
- <title>drivers/w1/w1_family.c</title>
- <para>Allows registering device family operations.</para>
-!Edrivers/w1/w1_family.c
- </sect2>
-
- <sect2 id="w1_int.c">
- <title>drivers/w1/w1_int.c</title>
- <para>W1 internal initialization for master devices.</para>
-!Edrivers/w1/w1_int.c
- </sect2>
-
- <sect2 id="w1_netlink.h">
- <title>drivers/w1/w1_netlink.h</title>
- <para>W1 external netlink API structures and commands.</para>
-!Idrivers/w1/w1_netlink.h
- </sect2>
-
- <sect2 id="w1_io.c">
- <title>drivers/w1/w1_io.c</title>
- <para>W1 input/output.</para>
-!Edrivers/w1/w1_io.c
-!Idrivers/w1/w1_io.c
- </sect2>
-
- </sect1>
-
-
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl
deleted file mode 100644
index 84ef6a90131c..000000000000
--- a/Documentation/DocBook/writing-an-alsa-driver.tmpl
+++ /dev/null
@@ -1,6221 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<!-- ****************************************************** -->
-<!-- Header -->
-<!-- ****************************************************** -->
-<book id="Writing-an-ALSA-Driver">
- <bookinfo>
- <title>Writing an ALSA Driver</title>
- <author>
- <firstname>Takashi</firstname>
- <surname>Iwai</surname>
- <affiliation>
- <address>
- <email>tiwai@suse.de</email>
- </address>
- </affiliation>
- </author>
-
- <date>Oct 15, 2007</date>
- <edition>0.3.7</edition>
-
- <abstract>
- <para>
- This document describes how to write an ALSA (Advanced Linux
- Sound Architecture) driver.
- </para>
- </abstract>
-
- <legalnotice>
- <para>
- Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email>
- </para>
-
- <para>
- This document is free; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
- </para>
-
- <para>
- This document is distributed in the hope that it will be useful,
- but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
- implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
- PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
- for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
- </legalnotice>
-
- </bookinfo>
-
-<!-- ****************************************************** -->
-<!-- Preface -->
-<!-- ****************************************************** -->
- <preface id="preface">
- <title>Preface</title>
- <para>
- This document describes how to write an
- <ulink url="http://www.alsa-project.org/"><citetitle>
- ALSA (Advanced Linux Sound Architecture)</citetitle></ulink>
- driver. The document focuses mainly on PCI soundcards.
- In the case of other device types, the API might
- be different, too. However, at least the ALSA kernel API is
- consistent, and therefore it would be still a bit help for
- writing them.
- </para>
-
- <para>
- This document targets people who already have enough
- C language skills and have basic linux kernel programming
- knowledge. This document doesn't explain the general
- topic of linux kernel coding and doesn't cover low-level
- driver implementation details. It only describes
- the standard way to write a PCI sound driver on ALSA.
- </para>
-
- <para>
- If you are already familiar with the older ALSA ver.0.5.x API, you
- can check the drivers such as <filename>sound/pci/es1938.c</filename> or
- <filename>sound/pci/maestro3.c</filename> which have also almost the same
- code-base in the ALSA 0.5.x tree, so you can compare the differences.
- </para>
-
- <para>
- This document is still a draft version. Any feedback and
- corrections, please!!
- </para>
- </preface>
-
-
-<!-- ****************************************************** -->
-<!-- File Tree Structure -->
-<!-- ****************************************************** -->
- <chapter id="file-tree">
- <title>File Tree Structure</title>
-
- <section id="file-tree-general">
- <title>General</title>
- <para>
- The ALSA drivers are provided in two ways.
- </para>
-
- <para>
- One is the trees provided as a tarball or via cvs from the
- ALSA's ftp site, and another is the 2.6 (or later) Linux kernel
- tree. To synchronize both, the ALSA driver tree is split into
- two different trees: alsa-kernel and alsa-driver. The former
- contains purely the source code for the Linux 2.6 (or later)
- tree. This tree is designed only for compilation on 2.6 or
- later environment. The latter, alsa-driver, contains many subtle
- files for compiling ALSA drivers outside of the Linux kernel tree,
- wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API,
- and additional drivers which are still in development or in
- tests. The drivers in alsa-driver tree will be moved to
- alsa-kernel (and eventually to the 2.6 kernel tree) when they are
- finished and confirmed to work fine.
- </para>
-
- <para>
- The file tree structure of ALSA driver is depicted below. Both
- alsa-kernel and alsa-driver have almost the same file
- structure, except for <quote>core</quote> directory. It's
- named as <quote>acore</quote> in alsa-driver tree.
-
- <example>
- <title>ALSA File Tree Structure</title>
- <literallayout>
- sound
- /core
- /oss
- /seq
- /oss
- /instr
- /ioctl32
- /include
- /drivers
- /mpu401
- /opl3
- /i2c
- /l3
- /synth
- /emux
- /pci
- /(cards)
- /isa
- /(cards)
- /arm
- /ppc
- /sparc
- /usb
- /pcmcia /(cards)
- /oss
- </literallayout>
- </example>
- </para>
- </section>
-
- <section id="file-tree-core-directory">
- <title>core directory</title>
- <para>
- This directory contains the middle layer which is the heart
- of ALSA drivers. In this directory, the native ALSA modules are
- stored. The sub-directories contain different modules and are
- dependent upon the kernel config.
- </para>
-
- <section id="file-tree-core-directory-oss">
- <title>core/oss</title>
-
- <para>
- The codes for PCM and mixer OSS emulation modules are stored
- in this directory. The rawmidi OSS emulation is included in
- the ALSA rawmidi code since it's quite small. The sequencer
- code is stored in <filename>core/seq/oss</filename> directory (see
- <link linkend="file-tree-core-directory-seq-oss"><citetitle>
- below</citetitle></link>).
- </para>
- </section>
-
- <section id="file-tree-core-directory-ioctl32">
- <title>core/ioctl32</title>
-
- <para>
- This directory contains the 32bit-ioctl wrappers for 64bit
- architectures such like x86-64, ppc64 and sparc64. For 32bit
- and alpha architectures, these are not compiled.
- </para>
- </section>
-
- <section id="file-tree-core-directory-seq">
- <title>core/seq</title>
- <para>
- This directory and its sub-directories are for the ALSA
- sequencer. This directory contains the sequencer core and
- primary sequencer modules such like snd-seq-midi,
- snd-seq-virmidi, etc. They are compiled only when
- <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel
- config.
- </para>
- </section>
-
- <section id="file-tree-core-directory-seq-oss">
- <title>core/seq/oss</title>
- <para>
- This contains the OSS sequencer emulation codes.
- </para>
- </section>
-
- <section id="file-tree-core-directory-deq-instr">
- <title>core/seq/instr</title>
- <para>
- This directory contains the modules for the sequencer
- instrument layer.
- </para>
- </section>
- </section>
-
- <section id="file-tree-include-directory">
- <title>include directory</title>
- <para>
- This is the place for the public header files of ALSA drivers,
- which are to be exported to user-space, or included by
- several files at different directories. Basically, the private
- header files should not be placed in this directory, but you may
- still find files there, due to historical reasons :)
- </para>
- </section>
-
- <section id="file-tree-drivers-directory">
- <title>drivers directory</title>
- <para>
- This directory contains code shared among different drivers
- on different architectures. They are hence supposed not to be
- architecture-specific.
- For example, the dummy pcm driver and the serial MIDI
- driver are found in this directory. In the sub-directories,
- there is code for components which are independent from
- bus and cpu architectures.
- </para>
-
- <section id="file-tree-drivers-directory-mpu401">
- <title>drivers/mpu401</title>
- <para>
- The MPU401 and MPU401-UART modules are stored here.
- </para>
- </section>
-
- <section id="file-tree-drivers-directory-opl3">
- <title>drivers/opl3 and opl4</title>
- <para>
- The OPL3 and OPL4 FM-synth stuff is found here.
- </para>
- </section>
- </section>
-
- <section id="file-tree-i2c-directory">
- <title>i2c directory</title>
- <para>
- This contains the ALSA i2c components.
- </para>
-
- <para>
- Although there is a standard i2c layer on Linux, ALSA has its
- own i2c code for some cards, because the soundcard needs only a
- simple operation and the standard i2c API is too complicated for
- such a purpose.
- </para>
-
- <section id="file-tree-i2c-directory-l3">
- <title>i2c/l3</title>
- <para>
- This is a sub-directory for ARM L3 i2c.
- </para>
- </section>
- </section>
-
- <section id="file-tree-synth-directory">
- <title>synth directory</title>
- <para>
- This contains the synth middle-level modules.
- </para>
-
- <para>
- So far, there is only Emu8000/Emu10k1 synth driver under
- the <filename>synth/emux</filename> sub-directory.
- </para>
- </section>
-
- <section id="file-tree-pci-directory">
- <title>pci directory</title>
- <para>
- This directory and its sub-directories hold the top-level card modules
- for PCI soundcards and the code specific to the PCI BUS.
- </para>
-
- <para>
- The drivers compiled from a single file are stored directly
- in the pci directory, while the drivers with several source files are
- stored on their own sub-directory (e.g. emu10k1, ice1712).
- </para>
- </section>
-
- <section id="file-tree-isa-directory">
- <title>isa directory</title>
- <para>
- This directory and its sub-directories hold the top-level card modules
- for ISA soundcards.
- </para>
- </section>
-
- <section id="file-tree-arm-ppc-sparc-directories">
- <title>arm, ppc, and sparc directories</title>
- <para>
- They are used for top-level card modules which are
- specific to one of these architectures.
- </para>
- </section>
-
- <section id="file-tree-usb-directory">
- <title>usb directory</title>
- <para>
- This directory contains the USB-audio driver. In the latest version, the
- USB MIDI driver is integrated in the usb-audio driver.
- </para>
- </section>
-
- <section id="file-tree-pcmcia-directory">
- <title>pcmcia directory</title>
- <para>
- The PCMCIA, especially PCCard drivers will go here. CardBus
- drivers will be in the pci directory, because their API is identical
- to that of standard PCI cards.
- </para>
- </section>
-
- <section id="file-tree-oss-directory">
- <title>oss directory</title>
- <para>
- The OSS/Lite source files are stored here in Linux 2.6 (or
- later) tree. In the ALSA driver tarball, this directory is empty,
- of course :)
- </para>
- </section>
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Basic Flow for PCI Drivers -->
-<!-- ****************************************************** -->
- <chapter id="basic-flow">
- <title>Basic Flow for PCI Drivers</title>
-
- <section id="basic-flow-outline">
- <title>Outline</title>
- <para>
- The minimum flow for PCI soundcards is as follows:
-
- <itemizedlist>
- <listitem><para>define the PCI ID table (see the section
- <link linkend="pci-resource-entries"><citetitle>PCI Entries
- </citetitle></link>).</para></listitem>
- <listitem><para>create <function>probe()</function> callback.</para></listitem>
- <listitem><para>create <function>remove()</function> callback.</para></listitem>
- <listitem><para>create a <structname>pci_driver</structname> structure
- containing the three pointers above.</para></listitem>
- <listitem><para>create an <function>init()</function> function just calling
- the <function>pci_register_driver()</function> to register the pci_driver table
- defined above.</para></listitem>
- <listitem><para>create an <function>exit()</function> function to call
- the <function>pci_unregister_driver()</function> function.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="basic-flow-example">
- <title>Full Code Example</title>
- <para>
- The code example is shown below. Some parts are kept
- unimplemented at this moment but will be filled in the
- next sections. The numbers in the comment lines of the
- <function>snd_mychip_probe()</function> function
- refer to details explained in the following section.
-
- <example>
- <title>Basic Flow for PCI Drivers - Example</title>
- <programlisting>
-<![CDATA[
- #include <linux/init.h>
- #include <linux/pci.h>
- #include <linux/slab.h>
- #include <sound/core.h>
- #include <sound/initval.h>
-
- /* module parameters (see "Module Parameters") */
- /* SNDRV_CARDS: maximum number of cards supported by this module */
- static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
- static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
- static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
-
- /* definition of the chip-specific record */
- struct mychip {
- struct snd_card *card;
- /* the rest of the implementation will be in section
- * "PCI Resource Management"
- */
- };
-
- /* chip-specific destructor
- * (see "PCI Resource Management")
- */
- static int snd_mychip_free(struct mychip *chip)
- {
- .... /* will be implemented later... */
- }
-
- /* component-destructor
- * (see "Management of Cards and Components")
- */
- static int snd_mychip_dev_free(struct snd_device *device)
- {
- return snd_mychip_free(device->device_data);
- }
-
- /* chip-specific constructor
- * (see "Management of Cards and Components")
- */
- static int snd_mychip_create(struct snd_card *card,
- struct pci_dev *pci,
- struct mychip **rchip)
- {
- struct mychip *chip;
- int err;
- static struct snd_device_ops ops = {
- .dev_free = snd_mychip_dev_free,
- };
-
- *rchip = NULL;
-
- /* check PCI availability here
- * (see "PCI Resource Management")
- */
- ....
-
- /* allocate a chip-specific data with zero filled */
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
- if (chip == NULL)
- return -ENOMEM;
-
- chip->card = card;
-
- /* rest of initialization here; will be implemented
- * later, see "PCI Resource Management"
- */
- ....
-
- err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
- if (err < 0) {
- snd_mychip_free(chip);
- return err;
- }
-
- *rchip = chip;
- return 0;
- }
-
- /* constructor -- see "Constructor" sub-section */
- static int snd_mychip_probe(struct pci_dev *pci,
- const struct pci_device_id *pci_id)
- {
- static int dev;
- struct snd_card *card;
- struct mychip *chip;
- int err;
-
- /* (1) */
- if (dev >= SNDRV_CARDS)
- return -ENODEV;
- if (!enable[dev]) {
- dev++;
- return -ENOENT;
- }
-
- /* (2) */
- err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
- 0, &card);
- if (err < 0)
- return err;
-
- /* (3) */
- err = snd_mychip_create(card, pci, &chip);
- if (err < 0) {
- snd_card_free(card);
- return err;
- }
-
- /* (4) */
- strcpy(card->driver, "My Chip");
- strcpy(card->shortname, "My Own Chip 123");
- sprintf(card->longname, "%s at 0x%lx irq %i",
- card->shortname, chip->ioport, chip->irq);
-
- /* (5) */
- .... /* implemented later */
-
- /* (6) */
- err = snd_card_register(card);
- if (err < 0) {
- snd_card_free(card);
- return err;
- }
-
- /* (7) */
- pci_set_drvdata(pci, card);
- dev++;
- return 0;
- }
-
- /* destructor -- see the "Destructor" sub-section */
- static void snd_mychip_remove(struct pci_dev *pci)
- {
- snd_card_free(pci_get_drvdata(pci));
- pci_set_drvdata(pci, NULL);
- }
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="basic-flow-constructor">
- <title>Constructor</title>
- <para>
- The real constructor of PCI drivers is the <function>probe</function> callback.
- The <function>probe</function> callback and other component-constructors which are called
- from the <function>probe</function> callback cannot be used with
- the <parameter>__init</parameter> prefix
- because any PCI device could be a hotplug device.
- </para>
-
- <para>
- In the <function>probe</function> callback, the following scheme is often used.
- </para>
-
- <section id="basic-flow-constructor-device-index">
- <title>1) Check and increment the device index.</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int dev;
- ....
- if (dev >= SNDRV_CARDS)
- return -ENODEV;
- if (!enable[dev]) {
- dev++;
- return -ENOENT;
- }
-]]>
- </programlisting>
- </informalexample>
-
- where enable[dev] is the module option.
- </para>
-
- <para>
- Each time the <function>probe</function> callback is called, check the
- availability of the device. If not available, simply increment
- the device index and returns. dev will be incremented also
- later (<link
- linkend="basic-flow-constructor-set-pci"><citetitle>step
- 7</citetitle></link>).
- </para>
- </section>
-
- <section id="basic-flow-constructor-create-card">
- <title>2) Create a card instance</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_card *card;
- int err;
- ....
- err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
- 0, &card);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The details will be explained in the section
- <link linkend="card-management-card-instance"><citetitle>
- Management of Cards and Components</citetitle></link>.
- </para>
- </section>
-
- <section id="basic-flow-constructor-create-main">
- <title>3) Create a main component</title>
- <para>
- In this part, the PCI resources are allocated.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mychip *chip;
- ....
- err = snd_mychip_create(card, pci, &chip);
- if (err < 0) {
- snd_card_free(card);
- return err;
- }
-]]>
- </programlisting>
- </informalexample>
-
- The details will be explained in the section <link
- linkend="pci-resource"><citetitle>PCI Resource
- Management</citetitle></link>.
- </para>
- </section>
-
- <section id="basic-flow-constructor-main-component">
- <title>4) Set the driver ID and name strings.</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- strcpy(card->driver, "My Chip");
- strcpy(card->shortname, "My Own Chip 123");
- sprintf(card->longname, "%s at 0x%lx irq %i",
- card->shortname, chip->ioport, chip->irq);
-]]>
- </programlisting>
- </informalexample>
-
- The driver field holds the minimal ID string of the
- chip. This is used by alsa-lib's configurator, so keep it
- simple but unique.
- Even the same driver can have different driver IDs to
- distinguish the functionality of each chip type.
- </para>
-
- <para>
- The shortname field is a string shown as more verbose
- name. The longname field contains the information
- shown in <filename>/proc/asound/cards</filename>.
- </para>
- </section>
-
- <section id="basic-flow-constructor-create-other">
- <title>5) Create other components, such as mixer, MIDI, etc.</title>
- <para>
- Here you define the basic components such as
- <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>,
- mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>),
- MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>),
- and other interfaces.
- Also, if you want a <link linkend="proc-interface"><citetitle>proc
- file</citetitle></link>, define it here, too.
- </para>
- </section>
-
- <section id="basic-flow-constructor-register-card">
- <title>6) Register the card instance.</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- err = snd_card_register(card);
- if (err < 0) {
- snd_card_free(card);
- return err;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Will be explained in the section <link
- linkend="card-management-registration"><citetitle>Management
- of Cards and Components</citetitle></link>, too.
- </para>
- </section>
-
- <section id="basic-flow-constructor-set-pci">
- <title>7) Set the PCI driver data and return zero.</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- pci_set_drvdata(pci, card);
- dev++;
- return 0;
-]]>
- </programlisting>
- </informalexample>
-
- In the above, the card record is stored. This pointer is
- used in the remove callback and power-management
- callbacks, too.
- </para>
- </section>
- </section>
-
- <section id="basic-flow-destructor">
- <title>Destructor</title>
- <para>
- The destructor, remove callback, simply releases the card
- instance. Then the ALSA middle layer will release all the
- attached components automatically.
- </para>
-
- <para>
- It would be typically like the following:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void snd_mychip_remove(struct pci_dev *pci)
- {
- snd_card_free(pci_get_drvdata(pci));
- pci_set_drvdata(pci, NULL);
- }
-]]>
- </programlisting>
- </informalexample>
-
- The above code assumes that the card pointer is set to the PCI
- driver data.
- </para>
- </section>
-
- <section id="basic-flow-header-files">
- <title>Header Files</title>
- <para>
- For the above example, at least the following include files
- are necessary.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- #include <linux/init.h>
- #include <linux/pci.h>
- #include <linux/slab.h>
- #include <sound/core.h>
- #include <sound/initval.h>
-]]>
- </programlisting>
- </informalexample>
-
- where the last one is necessary only when module options are
- defined in the source file. If the code is split into several
- files, the files without module options don't need them.
- </para>
-
- <para>
- In addition to these headers, you'll need
- <filename>&lt;linux/interrupt.h&gt;</filename> for interrupt
- handling, and <filename>&lt;asm/io.h&gt;</filename> for I/O
- access. If you use the <function>mdelay()</function> or
- <function>udelay()</function> functions, you'll need to include
- <filename>&lt;linux/delay.h&gt;</filename> too.
- </para>
-
- <para>
- The ALSA interfaces like the PCM and control APIs are defined in other
- <filename>&lt;sound/xxx.h&gt;</filename> header files.
- They have to be included after
- <filename>&lt;sound/core.h&gt;</filename>.
- </para>
-
- </section>
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Management of Cards and Components -->
-<!-- ****************************************************** -->
- <chapter id="card-management">
- <title>Management of Cards and Components</title>
-
- <section id="card-management-card-instance">
- <title>Card Instance</title>
- <para>
- For each soundcard, a <quote>card</quote> record must be allocated.
- </para>
-
- <para>
- A card record is the headquarters of the soundcard. It manages
- the whole list of devices (components) on the soundcard, such as
- PCM, mixers, MIDI, synthesizer, and so on. Also, the card
- record holds the ID and the name strings of the card, manages
- the root of proc files, and controls the power-management states
- and hotplug disconnections. The component list on the card
- record is used to manage the correct release of resources at
- destruction.
- </para>
-
- <para>
- As mentioned above, to create a card instance, call
- <function>snd_card_new()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_card *card;
- int err;
- err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The function takes six arguments: the parent device pointer,
- the card-index number, the id string, the module pointer (usually
- <constant>THIS_MODULE</constant>),
- the size of extra-data space, and the pointer to return the
- card instance. The extra_size argument is used to
- allocate card-&gt;private_data for the
- chip-specific data. Note that these data
- are allocated by <function>snd_card_new()</function>.
- </para>
-
- <para>
- The first argument, the pointer of struct
- <structname>device</structname>, specifies the parent device.
- For PCI devices, typically &amp;pci-&gt; is passed there.
- </para>
- </section>
-
- <section id="card-management-component">
- <title>Components</title>
- <para>
- After the card is created, you can attach the components
- (devices) to the card instance. In an ALSA driver, a component is
- represented as a struct <structname>snd_device</structname> object.
- A component can be a PCM instance, a control interface, a raw
- MIDI interface, etc. Each such instance has one component
- entry.
- </para>
-
- <para>
- A component can be created via
- <function>snd_device_new()</function> function.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- This takes the card pointer, the device-level
- (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the
- callback pointers (<parameter>&amp;ops</parameter>). The
- device-level defines the type of components and the order of
- registration and de-registration. For most components, the
- device-level is already defined. For a user-defined component,
- you can use <constant>SNDRV_DEV_LOWLEVEL</constant>.
- </para>
-
- <para>
- This function itself doesn't allocate the data space. The data
- must be allocated manually beforehand, and its pointer is passed
- as the argument. This pointer (<parameter>chip</parameter> in the
- above example) is used as the identifier for the instance.
- </para>
-
- <para>
- Each pre-defined ALSA component such as ac97 and pcm calls
- <function>snd_device_new()</function> inside its
- constructor. The destructor for each component is defined in the
- callback pointers. Hence, you don't need to take care of
- calling a destructor for such a component.
- </para>
-
- <para>
- If you wish to create your own component, you need to
- set the destructor function to the dev_free callback in
- the <parameter>ops</parameter>, so that it can be released
- automatically via <function>snd_card_free()</function>.
- The next example will show an implementation of chip-specific
- data.
- </para>
- </section>
-
- <section id="card-management-chip-specific">
- <title>Chip-Specific Data</title>
- <para>
- Chip-specific information, e.g. the I/O port address, its
- resource pointer, or the irq number, is stored in the
- chip-specific record.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mychip {
- ....
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- In general, there are two ways of allocating the chip record.
- </para>
-
- <section id="card-management-chip-specific-snd-card-new">
- <title>1. Allocating via <function>snd_card_new()</function>.</title>
- <para>
- As mentioned above, you can pass the extra-data-length
- to the 5th argument of <function>snd_card_new()</function>, i.e.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
- sizeof(struct mychip), &card);
-]]>
- </programlisting>
- </informalexample>
-
- struct <structname>mychip</structname> is the type of the chip record.
- </para>
-
- <para>
- In return, the allocated record can be accessed as
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mychip *chip = card->private_data;
-]]>
- </programlisting>
- </informalexample>
-
- With this method, you don't have to allocate twice.
- The record is released together with the card instance.
- </para>
- </section>
-
- <section id="card-management-chip-specific-allocate-extra">
- <title>2. Allocating an extra device.</title>
-
- <para>
- After allocating a card instance via
- <function>snd_card_new()</function> (with
- <constant>0</constant> on the 4th arg), call
- <function>kzalloc()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_card *card;
- struct mychip *chip;
- err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
- 0, &card);
- .....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The chip record should have the field to hold the card
- pointer at least,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mychip {
- struct snd_card *card;
- ....
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Then, set the card pointer in the returned chip instance.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- chip->card = card;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Next, initialize the fields, and register this chip
- record as a low-level device with a specified
- <parameter>ops</parameter>,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct snd_device_ops ops = {
- .dev_free = snd_mychip_dev_free,
- };
- ....
- snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
-]]>
- </programlisting>
- </informalexample>
-
- <function>snd_mychip_dev_free()</function> is the
- device-destructor function, which will call the real
- destructor.
- </para>
-
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_mychip_dev_free(struct snd_device *device)
- {
- return snd_mychip_free(device->device_data);
- }
-]]>
- </programlisting>
- </informalexample>
-
- where <function>snd_mychip_free()</function> is the real destructor.
- </para>
- </section>
- </section>
-
- <section id="card-management-registration">
- <title>Registration and Release</title>
- <para>
- After all components are assigned, register the card instance
- by calling <function>snd_card_register()</function>. Access
- to the device files is enabled at this point. That is, before
- <function>snd_card_register()</function> is called, the
- components are safely inaccessible from external side. If this
- call fails, exit the probe function after releasing the card via
- <function>snd_card_free()</function>.
- </para>
-
- <para>
- For releasing the card instance, you can call simply
- <function>snd_card_free()</function>. As mentioned earlier, all
- components are released automatically by this call.
- </para>
-
- <para>
- For a device which allows hotplugging, you can use
- <function>snd_card_free_when_closed</function>. This one will
- postpone the destruction until all devices are closed.
- </para>
-
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- PCI Resource Management -->
-<!-- ****************************************************** -->
- <chapter id="pci-resource">
- <title>PCI Resource Management</title>
-
- <section id="pci-resource-example">
- <title>Full Code Example</title>
- <para>
- In this section, we'll complete the chip-specific constructor,
- destructor and PCI entries. Example code is shown first,
- below.
-
- <example>
- <title>PCI Resource Management Example</title>
- <programlisting>
-<![CDATA[
- struct mychip {
- struct snd_card *card;
- struct pci_dev *pci;
-
- unsigned long port;
- int irq;
- };
-
- static int snd_mychip_free(struct mychip *chip)
- {
- /* disable hardware here if any */
- .... /* (not implemented in this document) */
-
- /* release the irq */
- if (chip->irq >= 0)
- free_irq(chip->irq, chip);
- /* release the I/O ports & memory */
- pci_release_regions(chip->pci);
- /* disable the PCI entry */
- pci_disable_device(chip->pci);
- /* release the data */
- kfree(chip);
- return 0;
- }
-
- /* chip-specific constructor */
- static int snd_mychip_create(struct snd_card *card,
- struct pci_dev *pci,
- struct mychip **rchip)
- {
- struct mychip *chip;
- int err;
- static struct snd_device_ops ops = {
- .dev_free = snd_mychip_dev_free,
- };
-
- *rchip = NULL;
-
- /* initialize the PCI entry */
- err = pci_enable_device(pci);
- if (err < 0)
- return err;
- /* check PCI availability (28bit DMA) */
- if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
- pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
- printk(KERN_ERR "error to set 28bit mask DMA\n");
- pci_disable_device(pci);
- return -ENXIO;
- }
-
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
- if (chip == NULL) {
- pci_disable_device(pci);
- return -ENOMEM;
- }
-
- /* initialize the stuff */
- chip->card = card;
- chip->pci = pci;
- chip->irq = -1;
-
- /* (1) PCI resource allocation */
- err = pci_request_regions(pci, "My Chip");
- if (err < 0) {
- kfree(chip);
- pci_disable_device(pci);
- return err;
- }
- chip->port = pci_resource_start(pci, 0);
- if (request_irq(pci->irq, snd_mychip_interrupt,
- IRQF_SHARED, KBUILD_MODNAME, chip)) {
- printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
- snd_mychip_free(chip);
- return -EBUSY;
- }
- chip->irq = pci->irq;
-
- /* (2) initialization of the chip hardware */
- .... /* (not implemented in this document) */
-
- err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
- if (err < 0) {
- snd_mychip_free(chip);
- return err;
- }
-
- *rchip = chip;
- return 0;
- }
-
- /* PCI IDs */
- static struct pci_device_id snd_mychip_ids[] = {
- { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
- PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
- ....
- { 0, }
- };
- MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
-
- /* pci_driver definition */
- static struct pci_driver driver = {
- .name = KBUILD_MODNAME,
- .id_table = snd_mychip_ids,
- .probe = snd_mychip_probe,
- .remove = snd_mychip_remove,
- };
-
- /* module initialization */
- static int __init alsa_card_mychip_init(void)
- {
- return pci_register_driver(&driver);
- }
-
- /* module clean up */
- static void __exit alsa_card_mychip_exit(void)
- {
- pci_unregister_driver(&driver);
- }
-
- module_init(alsa_card_mychip_init)
- module_exit(alsa_card_mychip_exit)
-
- EXPORT_NO_SYMBOLS; /* for old kernels only */
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="pci-resource-some-haftas">
- <title>Some Hafta's</title>
- <para>
- The allocation of PCI resources is done in the
- <function>probe()</function> function, and usually an extra
- <function>xxx_create()</function> function is written for this
- purpose.
- </para>
-
- <para>
- In the case of PCI devices, you first have to call
- the <function>pci_enable_device()</function> function before
- allocating resources. Also, you need to set the proper PCI DMA
- mask to limit the accessed I/O range. In some cases, you might
- need to call <function>pci_set_master()</function> function,
- too.
- </para>
-
- <para>
- Suppose the 28bit mask, and the code to be added would be like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- err = pci_enable_device(pci);
- if (err < 0)
- return err;
- if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
- pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
- printk(KERN_ERR "error to set 28bit mask DMA\n");
- pci_disable_device(pci);
- return -ENXIO;
- }
-
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- <section id="pci-resource-resource-allocation">
- <title>Resource Allocation</title>
- <para>
- The allocation of I/O ports and irqs is done via standard kernel
- functions. Unlike ALSA ver.0.5.x., there are no helpers for
- that. And these resources must be released in the destructor
- function (see below). Also, on ALSA 0.9.x, you don't need to
- allocate (pseudo-)DMA for PCI like in ALSA 0.5.x.
- </para>
-
- <para>
- Now assume that the PCI device has an I/O port with 8 bytes
- and an interrupt. Then struct <structname>mychip</structname> will have the
- following fields:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mychip {
- struct snd_card *card;
-
- unsigned long port;
- int irq;
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- For an I/O port (and also a memory region), you need to have
- the resource pointer for the standard resource management. For
- an irq, you have to keep only the irq number (integer). But you
- need to initialize this number as -1 before actual allocation,
- since irq 0 is valid. The port address and its resource pointer
- can be initialized as null by
- <function>kzalloc()</function> automatically, so you
- don't have to take care of resetting them.
- </para>
-
- <para>
- The allocation of an I/O port is done like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- err = pci_request_regions(pci, "My Chip");
- if (err < 0) {
- kfree(chip);
- pci_disable_device(pci);
- return err;
- }
- chip->port = pci_resource_start(pci, 0);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- <!-- obsolete -->
- It will reserve the I/O port region of 8 bytes of the given
- PCI device. The returned value, chip-&gt;res_port, is allocated
- via <function>kmalloc()</function> by
- <function>request_region()</function>. The pointer must be
- released via <function>kfree()</function>, but there is a
- problem with this. This issue will be explained later.
- </para>
-
- <para>
- The allocation of an interrupt source is done like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- if (request_irq(pci->irq, snd_mychip_interrupt,
- IRQF_SHARED, KBUILD_MODNAME, chip)) {
- printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
- snd_mychip_free(chip);
- return -EBUSY;
- }
- chip->irq = pci->irq;
-]]>
- </programlisting>
- </informalexample>
-
- where <function>snd_mychip_interrupt()</function> is the
- interrupt handler defined <link
- linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>.
- Note that chip-&gt;irq should be defined
- only when <function>request_irq()</function> succeeded.
- </para>
-
- <para>
- On the PCI bus, interrupts can be shared. Thus,
- <constant>IRQF_SHARED</constant> is used as the interrupt flag of
- <function>request_irq()</function>.
- </para>
-
- <para>
- The last argument of <function>request_irq()</function> is the
- data pointer passed to the interrupt handler. Usually, the
- chip-specific record is used for that, but you can use what you
- like, too.
- </para>
-
- <para>
- I won't give details about the interrupt handler at this
- point, but at least its appearance can be explained now. The
- interrupt handler looks usually like the following:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
- {
- struct mychip *chip = dev_id;
- ....
- return IRQ_HANDLED;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Now let's write the corresponding destructor for the resources
- above. The role of destructor is simple: disable the hardware
- (if already activated) and release the resources. So far, we
- have no hardware part, so the disabling code is not written here.
- </para>
-
- <para>
- To release the resources, the <quote>check-and-release</quote>
- method is a safer way. For the interrupt, do like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- if (chip->irq >= 0)
- free_irq(chip->irq, chip);
-]]>
- </programlisting>
- </informalexample>
-
- Since the irq number can start from 0, you should initialize
- chip-&gt;irq with a negative value (e.g. -1), so that you can
- check the validity of the irq number as above.
- </para>
-
- <para>
- When you requested I/O ports or memory regions via
- <function>pci_request_region()</function> or
- <function>pci_request_regions()</function> like in this example,
- release the resource(s) using the corresponding function,
- <function>pci_release_region()</function> or
- <function>pci_release_regions()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- pci_release_regions(chip->pci);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- When you requested manually via <function>request_region()</function>
- or <function>request_mem_region</function>, you can release it via
- <function>release_resource()</function>. Suppose that you keep
- the resource pointer returned from <function>request_region()</function>
- in chip-&gt;res_port, the release procedure looks like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- release_and_free_resource(chip->res_port);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Don't forget to call <function>pci_disable_device()</function>
- before the end.
- </para>
-
- <para>
- And finally, release the chip-specific record.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- kfree(chip);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- We didn't implement the hardware disabling part in the above.
- If you need to do this, please note that the destructor may be
- called even before the initialization of the chip is completed.
- It would be better to have a flag to skip hardware disabling
- if the hardware was not initialized yet.
- </para>
-
- <para>
- When the chip-data is assigned to the card using
- <function>snd_device_new()</function> with
- <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is
- called at the last. That is, it is assured that all other
- components like PCMs and controls have already been released.
- You don't have to stop PCMs, etc. explicitly, but just
- call low-level hardware stopping.
- </para>
-
- <para>
- The management of a memory-mapped region is almost as same as
- the management of an I/O port. You'll need three fields like
- the following:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mychip {
- ....
- unsigned long iobase_phys;
- void __iomem *iobase_virt;
- };
-]]>
- </programlisting>
- </informalexample>
-
- and the allocation would be like below:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- if ((err = pci_request_regions(pci, "My Chip")) < 0) {
- kfree(chip);
- return err;
- }
- chip->iobase_phys = pci_resource_start(pci, 0);
- chip->iobase_virt = ioremap_nocache(chip->iobase_phys,
- pci_resource_len(pci, 0));
-]]>
- </programlisting>
- </informalexample>
-
- and the corresponding destructor would be:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_mychip_free(struct mychip *chip)
- {
- ....
- if (chip->iobase_virt)
- iounmap(chip->iobase_virt);
- ....
- pci_release_regions(chip->pci);
- ....
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- </section>
-
- <section id="pci-resource-entries">
- <title>PCI Entries</title>
- <para>
- So far, so good. Let's finish the missing PCI
- stuff. At first, we need a
- <structname>pci_device_id</structname> table for this
- chipset. It's a table of PCI vendor/device ID number, and some
- masks.
- </para>
-
- <para>
- For example,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct pci_device_id snd_mychip_ids[] = {
- { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
- PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
- ....
- { 0, }
- };
- MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The first and second fields of
- the <structname>pci_device_id</structname> structure are the vendor and
- device IDs. If you have no reason to filter the matching
- devices, you can leave the remaining fields as above. The last
- field of the <structname>pci_device_id</structname> struct contains
- private data for this entry. You can specify any value here, for
- example, to define specific operations for supported device IDs.
- Such an example is found in the intel8x0 driver.
- </para>
-
- <para>
- The last entry of this list is the terminator. You must
- specify this all-zero entry.
- </para>
-
- <para>
- Then, prepare the <structname>pci_driver</structname> record:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct pci_driver driver = {
- .name = KBUILD_MODNAME,
- .id_table = snd_mychip_ids,
- .probe = snd_mychip_probe,
- .remove = snd_mychip_remove,
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The <structfield>probe</structfield> and
- <structfield>remove</structfield> functions have already
- been defined in the previous sections.
- The <structfield>name</structfield>
- field is the name string of this device. Note that you must not
- use a slash <quote>/</quote> in this string.
- </para>
-
- <para>
- And at last, the module entries:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int __init alsa_card_mychip_init(void)
- {
- return pci_register_driver(&driver);
- }
-
- static void __exit alsa_card_mychip_exit(void)
- {
- pci_unregister_driver(&driver);
- }
-
- module_init(alsa_card_mychip_init)
- module_exit(alsa_card_mychip_exit)
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Note that these module entries are tagged with
- <parameter>__init</parameter> and
- <parameter>__exit</parameter> prefixes.
- </para>
-
- <para>
- Oh, one thing was forgotten. If you have no exported symbols,
- you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels).
-
- <informalexample>
- <programlisting>
-<![CDATA[
- EXPORT_NO_SYMBOLS;
-]]>
- </programlisting>
- </informalexample>
-
- That's all!
- </para>
- </section>
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- PCM Interface -->
-<!-- ****************************************************** -->
- <chapter id="pcm-interface">
- <title>PCM Interface</title>
-
- <section id="pcm-interface-general">
- <title>General</title>
- <para>
- The PCM middle layer of ALSA is quite powerful and it is only
- necessary for each driver to implement the low-level functions
- to access its hardware.
- </para>
-
- <para>
- For accessing to the PCM layer, you need to include
- <filename>&lt;sound/pcm.h&gt;</filename> first. In addition,
- <filename>&lt;sound/pcm_params.h&gt;</filename> might be needed
- if you access to some functions related with hw_param.
- </para>
-
- <para>
- Each card device can have up to four pcm instances. A pcm
- instance corresponds to a pcm device file. The limitation of
- number of instances comes only from the available bit size of
- the Linux's device numbers. Once when 64bit device number is
- used, we'll have more pcm instances available.
- </para>
-
- <para>
- A pcm instance consists of pcm playback and capture streams,
- and each pcm stream consists of one or more pcm substreams. Some
- soundcards support multiple playback functions. For example,
- emu10k1 has a PCM playback of 32 stereo substreams. In this case, at
- each open, a free substream is (usually) automatically chosen
- and opened. Meanwhile, when only one substream exists and it was
- already opened, the successful open will either block
- or error with <constant>EAGAIN</constant> according to the
- file open mode. But you don't have to care about such details in your
- driver. The PCM middle layer will take care of such work.
- </para>
- </section>
-
- <section id="pcm-interface-example">
- <title>Full Code Example</title>
- <para>
- The example code below does not include any hardware access
- routines but shows only the skeleton, how to build up the PCM
- interfaces.
-
- <example>
- <title>PCM Example Code</title>
- <programlisting>
-<![CDATA[
- #include <sound/pcm.h>
- ....
-
- /* hardware definition */
- static struct snd_pcm_hardware snd_mychip_playback_hw = {
- .info = (SNDRV_PCM_INFO_MMAP |
- SNDRV_PCM_INFO_INTERLEAVED |
- SNDRV_PCM_INFO_BLOCK_TRANSFER |
- SNDRV_PCM_INFO_MMAP_VALID),
- .formats = SNDRV_PCM_FMTBIT_S16_LE,
- .rates = SNDRV_PCM_RATE_8000_48000,
- .rate_min = 8000,
- .rate_max = 48000,
- .channels_min = 2,
- .channels_max = 2,
- .buffer_bytes_max = 32768,
- .period_bytes_min = 4096,
- .period_bytes_max = 32768,
- .periods_min = 1,
- .periods_max = 1024,
- };
-
- /* hardware definition */
- static struct snd_pcm_hardware snd_mychip_capture_hw = {
- .info = (SNDRV_PCM_INFO_MMAP |
- SNDRV_PCM_INFO_INTERLEAVED |
- SNDRV_PCM_INFO_BLOCK_TRANSFER |
- SNDRV_PCM_INFO_MMAP_VALID),
- .formats = SNDRV_PCM_FMTBIT_S16_LE,
- .rates = SNDRV_PCM_RATE_8000_48000,
- .rate_min = 8000,
- .rate_max = 48000,
- .channels_min = 2,
- .channels_max = 2,
- .buffer_bytes_max = 32768,
- .period_bytes_min = 4096,
- .period_bytes_max = 32768,
- .periods_min = 1,
- .periods_max = 1024,
- };
-
- /* open callback */
- static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- struct snd_pcm_runtime *runtime = substream->runtime;
-
- runtime->hw = snd_mychip_playback_hw;
- /* more hardware-initialization will be done here */
- ....
- return 0;
- }
-
- /* close callback */
- static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- /* the hardware-specific codes will be here */
- ....
- return 0;
-
- }
-
- /* open callback */
- static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- struct snd_pcm_runtime *runtime = substream->runtime;
-
- runtime->hw = snd_mychip_capture_hw;
- /* more hardware-initialization will be done here */
- ....
- return 0;
- }
-
- /* close callback */
- static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- /* the hardware-specific codes will be here */
- ....
- return 0;
-
- }
-
- /* hw_params callback */
- static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
- struct snd_pcm_hw_params *hw_params)
- {
- return snd_pcm_lib_malloc_pages(substream,
- params_buffer_bytes(hw_params));
- }
-
- /* hw_free callback */
- static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
- {
- return snd_pcm_lib_free_pages(substream);
- }
-
- /* prepare callback */
- static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- struct snd_pcm_runtime *runtime = substream->runtime;
-
- /* set up the hardware with the current configuration
- * for example...
- */
- mychip_set_sample_format(chip, runtime->format);
- mychip_set_sample_rate(chip, runtime->rate);
- mychip_set_channels(chip, runtime->channels);
- mychip_set_dma_setup(chip, runtime->dma_addr,
- chip->buffer_size,
- chip->period_size);
- return 0;
- }
-
- /* trigger callback */
- static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
- int cmd)
- {
- switch (cmd) {
- case SNDRV_PCM_TRIGGER_START:
- /* do something to start the PCM engine */
- ....
- break;
- case SNDRV_PCM_TRIGGER_STOP:
- /* do something to stop the PCM engine */
- ....
- break;
- default:
- return -EINVAL;
- }
- }
-
- /* pointer callback */
- static snd_pcm_uframes_t
- snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- unsigned int current_ptr;
-
- /* get the current hardware pointer */
- current_ptr = mychip_get_hw_pointer(chip);
- return current_ptr;
- }
-
- /* operators */
- static struct snd_pcm_ops snd_mychip_playback_ops = {
- .open = snd_mychip_playback_open,
- .close = snd_mychip_playback_close,
- .ioctl = snd_pcm_lib_ioctl,
- .hw_params = snd_mychip_pcm_hw_params,
- .hw_free = snd_mychip_pcm_hw_free,
- .prepare = snd_mychip_pcm_prepare,
- .trigger = snd_mychip_pcm_trigger,
- .pointer = snd_mychip_pcm_pointer,
- };
-
- /* operators */
- static struct snd_pcm_ops snd_mychip_capture_ops = {
- .open = snd_mychip_capture_open,
- .close = snd_mychip_capture_close,
- .ioctl = snd_pcm_lib_ioctl,
- .hw_params = snd_mychip_pcm_hw_params,
- .hw_free = snd_mychip_pcm_hw_free,
- .prepare = snd_mychip_pcm_prepare,
- .trigger = snd_mychip_pcm_trigger,
- .pointer = snd_mychip_pcm_pointer,
- };
-
- /*
- * definitions of capture are omitted here...
- */
-
- /* create a pcm device */
- static int snd_mychip_new_pcm(struct mychip *chip)
- {
- struct snd_pcm *pcm;
- int err;
-
- err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
- if (err < 0)
- return err;
- pcm->private_data = chip;
- strcpy(pcm->name, "My Chip");
- chip->pcm = pcm;
- /* set operators */
- snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
- &snd_mychip_playback_ops);
- snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
- &snd_mychip_capture_ops);
- /* pre-allocation of buffers */
- /* NOTE: this may fail */
- snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
- snd_dma_pci_data(chip->pci),
- 64*1024, 64*1024);
- return 0;
- }
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="pcm-interface-constructor">
- <title>Constructor</title>
- <para>
- A pcm instance is allocated by the <function>snd_pcm_new()</function>
- function. It would be better to create a constructor for pcm,
- namely,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_mychip_new_pcm(struct mychip *chip)
- {
- struct snd_pcm *pcm;
- int err;
-
- err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
- if (err < 0)
- return err;
- pcm->private_data = chip;
- strcpy(pcm->name, "My Chip");
- chip->pcm = pcm;
- ....
- return 0;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The <function>snd_pcm_new()</function> function takes four
- arguments. The first argument is the card pointer to which this
- pcm is assigned, and the second is the ID string.
- </para>
-
- <para>
- The third argument (<parameter>index</parameter>, 0 in the
- above) is the index of this new pcm. It begins from zero. If
- you create more than one pcm instances, specify the
- different numbers in this argument. For example,
- <parameter>index</parameter> = 1 for the second PCM device.
- </para>
-
- <para>
- The fourth and fifth arguments are the number of substreams
- for playback and capture, respectively. Here 1 is used for
- both arguments. When no playback or capture substreams are available,
- pass 0 to the corresponding argument.
- </para>
-
- <para>
- If a chip supports multiple playbacks or captures, you can
- specify more numbers, but they must be handled properly in
- open/close, etc. callbacks. When you need to know which
- substream you are referring to, then it can be obtained from
- struct <structname>snd_pcm_substream</structname> data passed to each callback
- as follows:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_pcm_substream *substream;
- int index = substream->number;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- After the pcm is created, you need to set operators for each
- pcm stream.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
- &snd_mychip_playback_ops);
- snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
- &snd_mychip_capture_ops);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The operators are defined typically like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct snd_pcm_ops snd_mychip_playback_ops = {
- .open = snd_mychip_pcm_open,
- .close = snd_mychip_pcm_close,
- .ioctl = snd_pcm_lib_ioctl,
- .hw_params = snd_mychip_pcm_hw_params,
- .hw_free = snd_mychip_pcm_hw_free,
- .prepare = snd_mychip_pcm_prepare,
- .trigger = snd_mychip_pcm_trigger,
- .pointer = snd_mychip_pcm_pointer,
- };
-]]>
- </programlisting>
- </informalexample>
-
- All the callbacks are described in the
- <link linkend="pcm-interface-operators"><citetitle>
- Operators</citetitle></link> subsection.
- </para>
-
- <para>
- After setting the operators, you probably will want to
- pre-allocate the buffer. For the pre-allocation, simply call
- the following:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
- snd_dma_pci_data(chip->pci),
- 64*1024, 64*1024);
-]]>
- </programlisting>
- </informalexample>
-
- It will allocate a buffer up to 64kB as default.
- Buffer management details will be described in the later section <link
- linkend="buffer-and-memory"><citetitle>Buffer and Memory
- Management</citetitle></link>.
- </para>
-
- <para>
- Additionally, you can set some extra information for this pcm
- in pcm-&gt;info_flags.
- The available values are defined as
- <constant>SNDRV_PCM_INFO_XXX</constant> in
- <filename>&lt;sound/asound.h&gt;</filename>, which is used for
- the hardware definition (described later). When your soundchip
- supports only half-duplex, specify like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- <section id="pcm-interface-destructor">
- <title>... And the Destructor?</title>
- <para>
- The destructor for a pcm instance is not always
- necessary. Since the pcm device will be released by the middle
- layer code automatically, you don't have to call the destructor
- explicitly.
- </para>
-
- <para>
- The destructor would be necessary if you created
- special records internally and needed to release them. In such a
- case, set the destructor function to
- pcm-&gt;private_free:
-
- <example>
- <title>PCM Instance with a Destructor</title>
- <programlisting>
-<![CDATA[
- static void mychip_pcm_free(struct snd_pcm *pcm)
- {
- struct mychip *chip = snd_pcm_chip(pcm);
- /* free your own data */
- kfree(chip->my_private_pcm_data);
- /* do what you like else */
- ....
- }
-
- static int snd_mychip_new_pcm(struct mychip *chip)
- {
- struct snd_pcm *pcm;
- ....
- /* allocate your own data */
- chip->my_private_pcm_data = kmalloc(...);
- /* set the destructor */
- pcm->private_data = chip;
- pcm->private_free = mychip_pcm_free;
- ....
- }
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="pcm-interface-runtime">
- <title>Runtime Pointer - The Chest of PCM Information</title>
- <para>
- When the PCM substream is opened, a PCM runtime instance is
- allocated and assigned to the substream. This pointer is
- accessible via <constant>substream-&gt;runtime</constant>.
- This runtime pointer holds most information you need
- to control the PCM: the copy of hw_params and sw_params configurations, the buffer
- pointers, mmap records, spinlocks, etc.
- </para>
-
- <para>
- The definition of runtime instance is found in
- <filename>&lt;sound/pcm.h&gt;</filename>. Here are
- the contents of this file:
- <informalexample>
- <programlisting>
-<![CDATA[
-struct _snd_pcm_runtime {
- /* -- Status -- */
- struct snd_pcm_substream *trigger_master;
- snd_timestamp_t trigger_tstamp; /* trigger timestamp */
- int overrange;
- snd_pcm_uframes_t avail_max;
- snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
- snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
-
- /* -- HW params -- */
- snd_pcm_access_t access; /* access mode */
- snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
- snd_pcm_subformat_t subformat; /* subformat */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels */
- snd_pcm_uframes_t period_size; /* period size */
- unsigned int periods; /* periods */
- snd_pcm_uframes_t buffer_size; /* buffer size */
- unsigned int tick_time; /* tick time */
- snd_pcm_uframes_t min_align; /* Min alignment for the format */
- size_t byte_align;
- unsigned int frame_bits;
- unsigned int sample_bits;
- unsigned int info;
- unsigned int rate_num;
- unsigned int rate_den;
-
- /* -- SW params -- */
- struct timespec tstamp_mode; /* mmap timestamp is updated */
- unsigned int period_step;
- unsigned int sleep_min; /* min ticks to sleep */
- snd_pcm_uframes_t start_threshold;
- snd_pcm_uframes_t stop_threshold;
- snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
- noise is nearest than this */
- snd_pcm_uframes_t silence_size; /* Silence filling size */
- snd_pcm_uframes_t boundary; /* pointers wrap point */
-
- snd_pcm_uframes_t silenced_start;
- snd_pcm_uframes_t silenced_size;
-
- snd_pcm_sync_id_t sync; /* hardware synchronization ID */
-
- /* -- mmap -- */
- volatile struct snd_pcm_mmap_status *status;
- volatile struct snd_pcm_mmap_control *control;
- atomic_t mmap_count;
-
- /* -- locking / scheduling -- */
- spinlock_t lock;
- wait_queue_head_t sleep;
- struct timer_list tick_timer;
- struct fasync_struct *fasync;
-
- /* -- private section -- */
- void *private_data;
- void (*private_free)(struct snd_pcm_runtime *runtime);
-
- /* -- hardware description -- */
- struct snd_pcm_hardware hw;
- struct snd_pcm_hw_constraints hw_constraints;
-
- /* -- interrupt callbacks -- */
- void (*transfer_ack_begin)(struct snd_pcm_substream *substream);
- void (*transfer_ack_end)(struct snd_pcm_substream *substream);
-
- /* -- timer -- */
- unsigned int timer_resolution; /* timer resolution */
-
- /* -- DMA -- */
- unsigned char *dma_area; /* DMA area */
- dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
- size_t dma_bytes; /* size of DMA area */
-
- struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
-
-#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
- /* -- OSS things -- */
- struct snd_pcm_oss_runtime oss;
-#endif
-};
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- For the operators (callbacks) of each sound driver, most of
- these records are supposed to be read-only. Only the PCM
- middle-layer changes / updates them. The exceptions are
- the hardware description (hw), interrupt callbacks
- (transfer_ack_xxx), DMA buffer information, and the private
- data. Besides, if you use the standard buffer allocation
- method via <function>snd_pcm_lib_malloc_pages()</function>,
- you don't need to set the DMA buffer information by yourself.
- </para>
-
- <para>
- In the sections below, important records are explained.
- </para>
-
- <section id="pcm-interface-runtime-hw">
- <title>Hardware Description</title>
- <para>
- The hardware descriptor (struct <structname>snd_pcm_hardware</structname>)
- contains the definitions of the fundamental hardware
- configuration. Above all, you'll need to define this in
- <link linkend="pcm-interface-operators-open-callback"><citetitle>
- the open callback</citetitle></link>.
- Note that the runtime instance holds the copy of the
- descriptor, not the pointer to the existing descriptor. That
- is, in the open callback, you can modify the copied descriptor
- (<constant>runtime-&gt;hw</constant>) as you need. For example, if the maximum
- number of channels is 1 only on some chip models, you can
- still use the same hardware descriptor and change the
- channels_max later:
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_pcm_runtime *runtime = substream->runtime;
- ...
- runtime->hw = snd_mychip_playback_hw; /* common definition */
- if (chip->model == VERY_OLD_ONE)
- runtime->hw.channels_max = 1;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Typically, you'll have a hardware descriptor as below:
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct snd_pcm_hardware snd_mychip_playback_hw = {
- .info = (SNDRV_PCM_INFO_MMAP |
- SNDRV_PCM_INFO_INTERLEAVED |
- SNDRV_PCM_INFO_BLOCK_TRANSFER |
- SNDRV_PCM_INFO_MMAP_VALID),
- .formats = SNDRV_PCM_FMTBIT_S16_LE,
- .rates = SNDRV_PCM_RATE_8000_48000,
- .rate_min = 8000,
- .rate_max = 48000,
- .channels_min = 2,
- .channels_max = 2,
- .buffer_bytes_max = 32768,
- .period_bytes_min = 4096,
- .period_bytes_max = 32768,
- .periods_min = 1,
- .periods_max = 1024,
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- <itemizedlist>
- <listitem><para>
- The <structfield>info</structfield> field contains the type and
- capabilities of this pcm. The bit flags are defined in
- <filename>&lt;sound/asound.h&gt;</filename> as
- <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you
- have to specify whether the mmap is supported and which
- interleaved format is supported.
- When the hardware supports mmap, add the
- <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the
- hardware supports the interleaved or the non-interleaved
- formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or
- <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must
- be set, respectively. If both are supported, you can set both,
- too.
- </para>
-
- <para>
- In the above example, <constant>MMAP_VALID</constant> and
- <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap
- mode. Usually both are set. Of course,
- <constant>MMAP_VALID</constant> is set only if the mmap is
- really supported.
- </para>
-
- <para>
- The other possible flags are
- <constant>SNDRV_PCM_INFO_PAUSE</constant> and
- <constant>SNDRV_PCM_INFO_RESUME</constant>. The
- <constant>PAUSE</constant> bit means that the pcm supports the
- <quote>pause</quote> operation, while the
- <constant>RESUME</constant> bit means that the pcm supports
- the full <quote>suspend/resume</quote> operation.
- If the <constant>PAUSE</constant> flag is set,
- the <structfield>trigger</structfield> callback below
- must handle the corresponding (pause push/release) commands.
- The suspend/resume trigger commands can be defined even without
- the <constant>RESUME</constant> flag. See <link
- linkend="power-management"><citetitle>
- Power Management</citetitle></link> section for details.
- </para>
-
- <para>
- When the PCM substreams can be synchronized (typically,
- synchronized start/stop of a playback and a capture streams),
- you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
- too. In this case, you'll need to check the linked-list of
- PCM substreams in the trigger callback. This will be
- described in the later section.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <structfield>formats</structfield> field contains the bit-flags
- of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>).
- If the hardware supports more than one format, give all or'ed
- bits. In the example above, the signed 16bit little-endian
- format is specified.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <structfield>rates</structfield> field contains the bit-flags of
- supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>).
- When the chip supports continuous rates, pass
- <constant>CONTINUOUS</constant> bit additionally.
- The pre-defined rate bits are provided only for typical
- rates. If your chip supports unconventional rates, you need to add
- the <constant>KNOT</constant> bit and set up the hardware
- constraint manually (explained later).
- </para>
- </listitem>
-
- <listitem>
- <para>
- <structfield>rate_min</structfield> and
- <structfield>rate_max</structfield> define the minimum and
- maximum sample rate. This should correspond somehow to
- <structfield>rates</structfield> bits.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <structfield>channel_min</structfield> and
- <structfield>channel_max</structfield>
- define, as you might already expected, the minimum and maximum
- number of channels.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <structfield>buffer_bytes_max</structfield> defines the
- maximum buffer size in bytes. There is no
- <structfield>buffer_bytes_min</structfield> field, since
- it can be calculated from the minimum period size and the
- minimum number of periods.
- Meanwhile, <structfield>period_bytes_min</structfield> and
- define the minimum and maximum size of the period in bytes.
- <structfield>periods_max</structfield> and
- <structfield>periods_min</structfield> define the maximum and
- minimum number of periods in the buffer.
- </para>
-
- <para>
- The <quote>period</quote> is a term that corresponds to
- a fragment in the OSS world. The period defines the size at
- which a PCM interrupt is generated. This size strongly
- depends on the hardware.
- Generally, the smaller period size will give you more
- interrupts, that is, more controls.
- In the case of capture, this size defines the input latency.
- On the other hand, the whole buffer size defines the
- output latency for the playback direction.
- </para>
- </listitem>
-
- <listitem>
- <para>
- There is also a field <structfield>fifo_size</structfield>.
- This specifies the size of the hardware FIFO, but currently it
- is neither used in the driver nor in the alsa-lib. So, you
- can ignore this field.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="pcm-interface-runtime-config">
- <title>PCM Configurations</title>
- <para>
- Ok, let's go back again to the PCM runtime records.
- The most frequently referred records in the runtime instance are
- the PCM configurations.
- The PCM configurations are stored in the runtime instance
- after the application sends <type>hw_params</type> data via
- alsa-lib. There are many fields copied from hw_params and
- sw_params structs. For example,
- <structfield>format</structfield> holds the format type
- chosen by the application. This field contains the enum value
- <constant>SNDRV_PCM_FORMAT_XXX</constant>.
- </para>
-
- <para>
- One thing to be noted is that the configured buffer and period
- sizes are stored in <quote>frames</quote> in the runtime.
- In the ALSA world, 1 frame = channels * samples-size.
- For conversion between frames and bytes, you can use the
- <function>frames_to_bytes()</function> and
- <function>bytes_to_frames()</function> helper functions.
- <informalexample>
- <programlisting>
-<![CDATA[
- period_bytes = frames_to_bytes(runtime, runtime->period_size);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Also, many software parameters (sw_params) are
- stored in frames, too. Please check the type of the field.
- <type>snd_pcm_uframes_t</type> is for the frames as unsigned
- integer while <type>snd_pcm_sframes_t</type> is for the frames
- as signed integer.
- </para>
- </section>
-
- <section id="pcm-interface-runtime-dma">
- <title>DMA Buffer Information</title>
- <para>
- The DMA buffer is defined by the following four fields,
- <structfield>dma_area</structfield>,
- <structfield>dma_addr</structfield>,
- <structfield>dma_bytes</structfield> and
- <structfield>dma_private</structfield>.
- The <structfield>dma_area</structfield> holds the buffer
- pointer (the logical address). You can call
- <function>memcpy</function> from/to
- this pointer. Meanwhile, <structfield>dma_addr</structfield>
- holds the physical address of the buffer. This field is
- specified only when the buffer is a linear buffer.
- <structfield>dma_bytes</structfield> holds the size of buffer
- in bytes. <structfield>dma_private</structfield> is used for
- the ALSA DMA allocator.
- </para>
-
- <para>
- If you use a standard ALSA function,
- <function>snd_pcm_lib_malloc_pages()</function>, for
- allocating the buffer, these fields are set by the ALSA middle
- layer, and you should <emphasis>not</emphasis> change them by
- yourself. You can read them but not write them.
- On the other hand, if you want to allocate the buffer by
- yourself, you'll need to manage it in hw_params callback.
- At least, <structfield>dma_bytes</structfield> is mandatory.
- <structfield>dma_area</structfield> is necessary when the
- buffer is mmapped. If your driver doesn't support mmap, this
- field is not necessary. <structfield>dma_addr</structfield>
- is also optional. You can use
- <structfield>dma_private</structfield> as you like, too.
- </para>
- </section>
-
- <section id="pcm-interface-runtime-status">
- <title>Running Status</title>
- <para>
- The running status can be referred via <constant>runtime-&gt;status</constant>.
- This is the pointer to the struct <structname>snd_pcm_mmap_status</structname>
- record. For example, you can get the current DMA hardware
- pointer via <constant>runtime-&gt;status-&gt;hw_ptr</constant>.
- </para>
-
- <para>
- The DMA application pointer can be referred via
- <constant>runtime-&gt;control</constant>, which points to the
- struct <structname>snd_pcm_mmap_control</structname> record.
- However, accessing directly to this value is not recommended.
- </para>
- </section>
-
- <section id="pcm-interface-runtime-private">
- <title>Private Data</title>
- <para>
- You can allocate a record for the substream and store it in
- <constant>runtime-&gt;private_data</constant>. Usually, this
- is done in
- <link linkend="pcm-interface-operators-open-callback"><citetitle>
- the open callback</citetitle></link>.
- Don't mix this with <constant>pcm-&gt;private_data</constant>.
- The <constant>pcm-&gt;private_data</constant> usually points to the
- chip instance assigned statically at the creation of PCM, while the
- <constant>runtime-&gt;private_data</constant> points to a dynamic
- data structure created at the PCM open callback.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_open(struct snd_pcm_substream *substream)
- {
- struct my_pcm_data *data;
- ....
- data = kmalloc(sizeof(*data), GFP_KERNEL);
- substream->runtime->private_data = data;
- ....
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The allocated object must be released in
- <link linkend="pcm-interface-operators-open-callback"><citetitle>
- the close callback</citetitle></link>.
- </para>
- </section>
-
- <section id="pcm-interface-runtime-intr">
- <title>Interrupt Callbacks</title>
- <para>
- The field <structfield>transfer_ack_begin</structfield> and
- <structfield>transfer_ack_end</structfield> are called at
- the beginning and at the end of
- <function>snd_pcm_period_elapsed()</function>, respectively.
- </para>
- </section>
-
- </section>
-
- <section id="pcm-interface-operators">
- <title>Operators</title>
- <para>
- OK, now let me give details about each pcm callback
- (<parameter>ops</parameter>). In general, every callback must
- return 0 if successful, or a negative error number
- such as <constant>-EINVAL</constant>. To choose an appropriate
- error number, it is advised to check what value other parts of
- the kernel return when the same kind of request fails.
- </para>
-
- <para>
- The callback function takes at least the argument with
- <structname>snd_pcm_substream</structname> pointer. To retrieve
- the chip record from the given substream instance, you can use the
- following macro.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- int xxx() {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- ....
- }
-]]>
- </programlisting>
- </informalexample>
-
- The macro reads <constant>substream-&gt;private_data</constant>,
- which is a copy of <constant>pcm-&gt;private_data</constant>.
- You can override the former if you need to assign different data
- records per PCM substream. For example, the cmi8330 driver assigns
- different private_data for playback and capture directions,
- because it uses two different codecs (SB- and AD-compatible) for
- different directions.
- </para>
-
- <section id="pcm-interface-operators-open-callback">
- <title>open callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_open(struct snd_pcm_substream *substream);
-]]>
- </programlisting>
- </informalexample>
-
- This is called when a pcm substream is opened.
- </para>
-
- <para>
- At least, here you have to initialize the runtime-&gt;hw
- record. Typically, this is done by like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_open(struct snd_pcm_substream *substream)
- {
- struct mychip *chip = snd_pcm_substream_chip(substream);
- struct snd_pcm_runtime *runtime = substream->runtime;
-
- runtime->hw = snd_mychip_playback_hw;
- return 0;
- }
-]]>
- </programlisting>
- </informalexample>
-
- where <parameter>snd_mychip_playback_hw</parameter> is the
- pre-defined hardware description.
- </para>
-
- <para>
- You can allocate a private data in this callback, as described
- in <link linkend="pcm-interface-runtime-private"><citetitle>
- Private Data</citetitle></link> section.
- </para>
-
- <para>
- If the hardware configuration needs more constraints, set the
- hardware constraints here, too.
- See <link linkend="pcm-interface-constraints"><citetitle>
- Constraints</citetitle></link> for more details.
- </para>
- </section>
-
- <section id="pcm-interface-operators-close-callback">
- <title>close callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_close(struct snd_pcm_substream *substream);
-]]>
- </programlisting>
- </informalexample>
-
- Obviously, this is called when a pcm substream is closed.
- </para>
-
- <para>
- Any private instance for a pcm substream allocated in the
- open callback will be released here.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_close(struct snd_pcm_substream *substream)
- {
- ....
- kfree(substream->runtime->private_data);
- ....
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- <section id="pcm-interface-operators-ioctl-callback">
- <title>ioctl callback</title>
- <para>
- This is used for any special call to pcm ioctls. But
- usually you can pass a generic ioctl callback,
- <function>snd_pcm_lib_ioctl</function>.
- </para>
- </section>
-
- <section id="pcm-interface-operators-hw-params-callback">
- <title>hw_params callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
- struct snd_pcm_hw_params *hw_params);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- This is called when the hardware parameter
- (<structfield>hw_params</structfield>) is set
- up by the application,
- that is, once when the buffer size, the period size, the
- format, etc. are defined for the pcm substream.
- </para>
-
- <para>
- Many hardware setups should be done in this callback,
- including the allocation of buffers.
- </para>
-
- <para>
- Parameters to be initialized are retrieved by
- <function>params_xxx()</function> macros. To allocate
- buffer, you can call a helper function,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
-]]>
- </programlisting>
- </informalexample>
-
- <function>snd_pcm_lib_malloc_pages()</function> is available
- only when the DMA buffers have been pre-allocated.
- See the section <link
- linkend="buffer-and-memory-buffer-types"><citetitle>
- Buffer Types</citetitle></link> for more details.
- </para>
-
- <para>
- Note that this and <structfield>prepare</structfield> callbacks
- may be called multiple times per initialization.
- For example, the OSS emulation may
- call these callbacks at each change via its ioctl.
- </para>
-
- <para>
- Thus, you need to be careful not to allocate the same buffers
- many times, which will lead to memory leaks! Calling the
- helper function above many times is OK. It will release the
- previous buffer automatically when it was already allocated.
- </para>
-
- <para>
- Another note is that this callback is non-atomic
- (schedulable) as default, i.e. when no
- <structfield>nonatomic</structfield> flag set.
- This is important, because the
- <structfield>trigger</structfield> callback
- is atomic (non-schedulable). That is, mutexes or any
- schedule-related functions are not available in
- <structfield>trigger</structfield> callback.
- Please see the subsection
- <link linkend="pcm-interface-atomicity"><citetitle>
- Atomicity</citetitle></link> for details.
- </para>
- </section>
-
- <section id="pcm-interface-operators-hw-free-callback">
- <title>hw_free callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- This is called to release the resources allocated via
- <structfield>hw_params</structfield>. For example, releasing the
- buffer via
- <function>snd_pcm_lib_malloc_pages()</function> is done by
- calling the following:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_lib_free_pages(substream);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- This function is always called before the close callback is called.
- Also, the callback may be called multiple times, too.
- Keep track whether the resource was already released.
- </para>
- </section>
-
- <section id="pcm-interface-operators-prepare-callback">
- <title>prepare callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_prepare(struct snd_pcm_substream *substream);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- This callback is called when the pcm is
- <quote>prepared</quote>. You can set the format type, sample
- rate, etc. here. The difference from
- <structfield>hw_params</structfield> is that the
- <structfield>prepare</structfield> callback will be called each
- time
- <function>snd_pcm_prepare()</function> is called, i.e. when
- recovering after underruns, etc.
- </para>
-
- <para>
- Note that this callback is now non-atomic.
- You can use schedule-related functions safely in this callback.
- </para>
-
- <para>
- In this and the following callbacks, you can refer to the
- values via the runtime record,
- substream-&gt;runtime.
- For example, to get the current
- rate, format or channels, access to
- runtime-&gt;rate,
- runtime-&gt;format or
- runtime-&gt;channels, respectively.
- The physical address of the allocated buffer is set to
- runtime-&gt;dma_area. The buffer and period sizes are
- in runtime-&gt;buffer_size and runtime-&gt;period_size,
- respectively.
- </para>
-
- <para>
- Be careful that this callback will be called many times at
- each setup, too.
- </para>
- </section>
-
- <section id="pcm-interface-operators-trigger-callback">
- <title>trigger callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
-]]>
- </programlisting>
- </informalexample>
-
- This is called when the pcm is started, stopped or paused.
- </para>
-
- <para>
- Which action is specified in the second argument,
- <constant>SNDRV_PCM_TRIGGER_XXX</constant> in
- <filename>&lt;sound/pcm.h&gt;</filename>. At least,
- the <constant>START</constant> and <constant>STOP</constant>
- commands must be defined in this callback.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- switch (cmd) {
- case SNDRV_PCM_TRIGGER_START:
- /* do something to start the PCM engine */
- break;
- case SNDRV_PCM_TRIGGER_STOP:
- /* do something to stop the PCM engine */
- break;
- default:
- return -EINVAL;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- When the pcm supports the pause operation (given in the info
- field of the hardware table), the <constant>PAUSE_PUSH</constant>
- and <constant>PAUSE_RELEASE</constant> commands must be
- handled here, too. The former is the command to pause the pcm,
- and the latter to restart the pcm again.
- </para>
-
- <para>
- When the pcm supports the suspend/resume operation,
- regardless of full or partial suspend/resume support,
- the <constant>SUSPEND</constant> and <constant>RESUME</constant>
- commands must be handled, too.
- These commands are issued when the power-management status is
- changed. Obviously, the <constant>SUSPEND</constant> and
- <constant>RESUME</constant> commands
- suspend and resume the pcm substream, and usually, they
- are identical to the <constant>STOP</constant> and
- <constant>START</constant> commands, respectively.
- See the <link linkend="power-management"><citetitle>
- Power Management</citetitle></link> section for details.
- </para>
-
- <para>
- As mentioned, this callback is atomic as default unless
- <structfield>nonatomic</structfield> flag set, and
- you cannot call functions which may sleep.
- The trigger callback should be as minimal as possible,
- just really triggering the DMA. The other stuff should be
- initialized hw_params and prepare callbacks properly
- beforehand.
- </para>
- </section>
-
- <section id="pcm-interface-operators-pointer-callback">
- <title>pointer callback</title>
- <para>
- <informalexample>
- <programlisting>
-<![CDATA[
- static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
-]]>
- </programlisting>
- </informalexample>
-
- This callback is called when the PCM middle layer inquires
- the current hardware position on the buffer. The position must
- be returned in frames,
- ranging from 0 to buffer_size - 1.
- </para>
-
- <para>
- This is called usually from the buffer-update routine in the
- pcm middle layer, which is invoked when
- <function>snd_pcm_period_elapsed()</function> is called in the
- interrupt routine. Then the pcm middle layer updates the
- position and calculates the available space, and wakes up the
- sleeping poll threads, etc.
- </para>
-
- <para>
- This callback is also atomic as default.
- </para>
- </section>
-
- <section id="pcm-interface-operators-copy-silence">
- <title>copy and silence callbacks</title>
- <para>
- These callbacks are not mandatory, and can be omitted in
- most cases. These callbacks are used when the hardware buffer
- cannot be in the normal memory space. Some chips have their
- own buffer on the hardware which is not mappable. In such a
- case, you have to transfer the data manually from the memory
- buffer to the hardware buffer. Or, if the buffer is
- non-contiguous on both physical and virtual memory spaces,
- these callbacks must be defined, too.
- </para>
-
- <para>
- If these two callbacks are defined, copy and set-silence
- operations are done by them. The detailed will be described in
- the later section <link
- linkend="buffer-and-memory"><citetitle>Buffer and Memory
- Management</citetitle></link>.
- </para>
- </section>
-
- <section id="pcm-interface-operators-ack">
- <title>ack callback</title>
- <para>
- This callback is also not mandatory. This callback is called
- when the appl_ptr is updated in read or write operations.
- Some drivers like emu10k1-fx and cs46xx need to track the
- current appl_ptr for the internal buffer, and this callback
- is useful only for such a purpose.
- </para>
- <para>
- This callback is atomic as default.
- </para>
- </section>
-
- <section id="pcm-interface-operators-page-callback">
- <title>page callback</title>
-
- <para>
- This callback is optional too. This callback is used
- mainly for non-contiguous buffers. The mmap calls this
- callback to get the page address. Some examples will be
- explained in the later section <link
- linkend="buffer-and-memory"><citetitle>Buffer and Memory
- Management</citetitle></link>, too.
- </para>
- </section>
- </section>
-
- <section id="pcm-interface-interrupt-handler">
- <title>Interrupt Handler</title>
- <para>
- The rest of pcm stuff is the PCM interrupt handler. The
- role of PCM interrupt handler in the sound driver is to update
- the buffer position and to tell the PCM middle layer when the
- buffer position goes across the prescribed period size. To
- inform this, call the <function>snd_pcm_period_elapsed()</function>
- function.
- </para>
-
- <para>
- There are several types of sound chips to generate the interrupts.
- </para>
-
- <section id="pcm-interface-interrupt-handler-boundary">
- <title>Interrupts at the period (fragment) boundary</title>
- <para>
- This is the most frequently found type: the hardware
- generates an interrupt at each period boundary.
- In this case, you can call
- <function>snd_pcm_period_elapsed()</function> at each
- interrupt.
- </para>
-
- <para>
- <function>snd_pcm_period_elapsed()</function> takes the
- substream pointer as its argument. Thus, you need to keep the
- substream pointer accessible from the chip instance. For
- example, define substream field in the chip record to hold the
- current running substream pointer, and set the pointer value
- at open callback (and reset at close callback).
- </para>
-
- <para>
- If you acquire a spinlock in the interrupt handler, and the
- lock is used in other pcm callbacks, too, then you have to
- release the lock before calling
- <function>snd_pcm_period_elapsed()</function>, because
- <function>snd_pcm_period_elapsed()</function> calls other pcm
- callbacks inside.
- </para>
-
- <para>
- Typical code would be like:
-
- <example>
- <title>Interrupt Handler Case #1</title>
- <programlisting>
-<![CDATA[
- static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
- {
- struct mychip *chip = dev_id;
- spin_lock(&chip->lock);
- ....
- if (pcm_irq_invoked(chip)) {
- /* call updater, unlock before it */
- spin_unlock(&chip->lock);
- snd_pcm_period_elapsed(chip->substream);
- spin_lock(&chip->lock);
- /* acknowledge the interrupt if necessary */
- }
- ....
- spin_unlock(&chip->lock);
- return IRQ_HANDLED;
- }
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="pcm-interface-interrupt-handler-timer">
- <title>High frequency timer interrupts</title>
- <para>
- This happens when the hardware doesn't generate interrupts
- at the period boundary but issues timer interrupts at a fixed
- timer rate (e.g. es1968 or ymfpci drivers).
- In this case, you need to check the current hardware
- position and accumulate the processed sample length at each
- interrupt. When the accumulated size exceeds the period
- size, call
- <function>snd_pcm_period_elapsed()</function> and reset the
- accumulator.
- </para>
-
- <para>
- Typical code would be like the following.
-
- <example>
- <title>Interrupt Handler Case #2</title>
- <programlisting>
-<![CDATA[
- static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
- {
- struct mychip *chip = dev_id;
- spin_lock(&chip->lock);
- ....
- if (pcm_irq_invoked(chip)) {
- unsigned int last_ptr, size;
- /* get the current hardware pointer (in frames) */
- last_ptr = get_hw_ptr(chip);
- /* calculate the processed frames since the
- * last update
- */
- if (last_ptr < chip->last_ptr)
- size = runtime->buffer_size + last_ptr
- - chip->last_ptr;
- else
- size = last_ptr - chip->last_ptr;
- /* remember the last updated point */
- chip->last_ptr = last_ptr;
- /* accumulate the size */
- chip->size += size;
- /* over the period boundary? */
- if (chip->size >= runtime->period_size) {
- /* reset the accumulator */
- chip->size %= runtime->period_size;
- /* call updater */
- spin_unlock(&chip->lock);
- snd_pcm_period_elapsed(substream);
- spin_lock(&chip->lock);
- }
- /* acknowledge the interrupt if necessary */
- }
- ....
- spin_unlock(&chip->lock);
- return IRQ_HANDLED;
- }
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="pcm-interface-interrupt-handler-both">
- <title>On calling <function>snd_pcm_period_elapsed()</function></title>
- <para>
- In both cases, even if more than one period are elapsed, you
- don't have to call
- <function>snd_pcm_period_elapsed()</function> many times. Call
- only once. And the pcm layer will check the current hardware
- pointer and update to the latest status.
- </para>
- </section>
- </section>
-
- <section id="pcm-interface-atomicity">
- <title>Atomicity</title>
- <para>
- One of the most important (and thus difficult to debug) problems
- in kernel programming are race conditions.
- In the Linux kernel, they are usually avoided via spin-locks, mutexes
- or semaphores. In general, if a race condition can happen
- in an interrupt handler, it has to be managed atomically, and you
- have to use a spinlock to protect the critical session. If the
- critical section is not in interrupt handler code and
- if taking a relatively long time to execute is acceptable, you
- should use mutexes or semaphores instead.
- </para>
-
- <para>
- As already seen, some pcm callbacks are atomic and some are
- not. For example, the <parameter>hw_params</parameter> callback is
- non-atomic, while <parameter>trigger</parameter> callback is
- atomic. This means, the latter is called already in a spinlock
- held by the PCM middle layer. Please take this atomicity into
- account when you choose a locking scheme in the callbacks.
- </para>
-
- <para>
- In the atomic callbacks, you cannot use functions which may call
- <function>schedule</function> or go to
- <function>sleep</function>. Semaphores and mutexes can sleep,
- and hence they cannot be used inside the atomic callbacks
- (e.g. <parameter>trigger</parameter> callback).
- To implement some delay in such a callback, please use
- <function>udelay()</function> or <function>mdelay()</function>.
- </para>
-
- <para>
- All three atomic callbacks (trigger, pointer, and ack) are
- called with local interrupts disabled.
- </para>
-
- <para>
- The recent changes in PCM core code, however, allow all PCM
- operations to be non-atomic. This assumes that the all caller
- sides are in non-atomic contexts. For example, the function
- <function>snd_pcm_period_elapsed()</function> is called
- typically from the interrupt handler. But, if you set up the
- driver to use a threaded interrupt handler, this call can be in
- non-atomic context, too. In such a case, you can set
- <structfield>nonatomic</structfield> filed of
- <structname>snd_pcm</structname> object after creating it.
- When this flag is set, mutex and rwsem are used internally in
- the PCM core instead of spin and rwlocks, so that you can call
- all PCM functions safely in a non-atomic context.
- </para>
-
- </section>
- <section id="pcm-interface-constraints">
- <title>Constraints</title>
- <para>
- If your chip supports unconventional sample rates, or only the
- limited samples, you need to set a constraint for the
- condition.
- </para>
-
- <para>
- For example, in order to restrict the sample rates in the some
- supported values, use
- <function>snd_pcm_hw_constraint_list()</function>.
- You need to call this function in the open callback.
-
- <example>
- <title>Example of Hardware Constraints</title>
- <programlisting>
-<![CDATA[
- static unsigned int rates[] =
- {4000, 10000, 22050, 44100};
- static struct snd_pcm_hw_constraint_list constraints_rates = {
- .count = ARRAY_SIZE(rates),
- .list = rates,
- .mask = 0,
- };
-
- static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
- {
- int err;
- ....
- err = snd_pcm_hw_constraint_list(substream->runtime, 0,
- SNDRV_PCM_HW_PARAM_RATE,
- &constraints_rates);
- if (err < 0)
- return err;
- ....
- }
-]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- There are many different constraints.
- Look at <filename>sound/pcm.h</filename> for a complete list.
- You can even define your own constraint rules.
- For example, let's suppose my_chip can manage a substream of 1 channel
- if and only if the format is S16_LE, otherwise it supports any format
- specified in the <structname>snd_pcm_hardware</structname> structure (or in any
- other constraint_list). You can build a rule like this:
-
- <example>
- <title>Example of Hardware Constraints for Channels</title>
- <programlisting>
-<![CDATA[
- static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
- struct snd_pcm_hw_rule *rule)
- {
- struct snd_interval *c = hw_param_interval(params,
- SNDRV_PCM_HW_PARAM_CHANNELS);
- struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
- struct snd_interval ch;
-
- snd_interval_any(&ch);
- if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
- ch.min = ch.max = 1;
- ch.integer = 1;
- return snd_interval_refine(c, &ch);
- }
- return 0;
- }
-]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- Then you need to call this function to add your rule:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
- hw_rule_channels_by_format, NULL,
- SNDRV_PCM_HW_PARAM_FORMAT, -1);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The rule function is called when an application sets the PCM
- format, and it refines the number of channels accordingly.
- But an application may set the number of channels before
- setting the format. Thus you also need to define the inverse rule:
-
- <example>
- <title>Example of Hardware Constraints for Formats</title>
- <programlisting>
-<![CDATA[
- static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
- struct snd_pcm_hw_rule *rule)
- {
- struct snd_interval *c = hw_param_interval(params,
- SNDRV_PCM_HW_PARAM_CHANNELS);
- struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
- struct snd_mask fmt;
-
- snd_mask_any(&fmt); /* Init the struct */
- if (c->min < 2) {
- fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
- return snd_mask_refine(f, &fmt);
- }
- return 0;
- }
-]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- ...and in the open callback:
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
- hw_rule_format_by_channels, NULL,
- SNDRV_PCM_HW_PARAM_CHANNELS, -1);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- I won't give more details here, rather I
- would like to say, <quote>Luke, use the source.</quote>
- </para>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Control Interface -->
-<!-- ****************************************************** -->
- <chapter id="control-interface">
- <title>Control Interface</title>
-
- <section id="control-interface-general">
- <title>General</title>
- <para>
- The control interface is used widely for many switches,
- sliders, etc. which are accessed from user-space. Its most
- important use is the mixer interface. In other words, since ALSA
- 0.9.x, all the mixer stuff is implemented on the control kernel API.
- </para>
-
- <para>
- ALSA has a well-defined AC97 control module. If your chip
- supports only the AC97 and nothing else, you can skip this
- section.
- </para>
-
- <para>
- The control API is defined in
- <filename>&lt;sound/control.h&gt;</filename>.
- Include this file if you want to add your own controls.
- </para>
- </section>
-
- <section id="control-interface-definition">
- <title>Definition of Controls</title>
- <para>
- To create a new control, you need to define the
- following three
- callbacks: <structfield>info</structfield>,
- <structfield>get</structfield> and
- <structfield>put</structfield>. Then, define a
- struct <structname>snd_kcontrol_new</structname> record, such as:
-
- <example>
- <title>Definition of a Control</title>
- <programlisting>
-<![CDATA[
- static struct snd_kcontrol_new my_control = {
- .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
- .name = "PCM Playback Switch",
- .index = 0,
- .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
- .private_value = 0xffff,
- .info = my_control_info,
- .get = my_control_get,
- .put = my_control_put
- };
-]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- The <structfield>iface</structfield> field specifies the control
- type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which
- is usually <constant>MIXER</constant>.
- Use <constant>CARD</constant> for global controls that are not
- logically part of the mixer.
- If the control is closely associated with some specific device on
- the sound card, use <constant>HWDEP</constant>,
- <constant>PCM</constant>, <constant>RAWMIDI</constant>,
- <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and
- specify the device number with the
- <structfield>device</structfield> and
- <structfield>subdevice</structfield> fields.
- </para>
-
- <para>
- The <structfield>name</structfield> is the name identifier
- string. Since ALSA 0.9.x, the control name is very important,
- because its role is classified from its name. There are
- pre-defined standard control names. The details are described in
- the <link linkend="control-interface-control-names"><citetitle>
- Control Names</citetitle></link> subsection.
- </para>
-
- <para>
- The <structfield>index</structfield> field holds the index number
- of this control. If there are several different controls with
- the same name, they can be distinguished by the index
- number. This is the case when
- several codecs exist on the card. If the index is zero, you can
- omit the definition above.
- </para>
-
- <para>
- The <structfield>access</structfield> field contains the access
- type of this control. Give the combination of bit masks,
- <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there.
- The details will be explained in
- the <link linkend="control-interface-access-flags"><citetitle>
- Access Flags</citetitle></link> subsection.
- </para>
-
- <para>
- The <structfield>private_value</structfield> field contains
- an arbitrary long integer value for this record. When using
- the generic <structfield>info</structfield>,
- <structfield>get</structfield> and
- <structfield>put</structfield> callbacks, you can pass a value
- through this field. If several small numbers are necessary, you can
- combine them in bitwise. Or, it's possible to give a pointer
- (casted to unsigned long) of some record to this field, too.
- </para>
-
- <para>
- The <structfield>tlv</structfield> field can be used to provide
- metadata about the control; see the
- <link linkend="control-interface-tlv">
- <citetitle>Metadata</citetitle></link> subsection.
- </para>
-
- <para>
- The other three are
- <link linkend="control-interface-callbacks"><citetitle>
- callback functions</citetitle></link>.
- </para>
- </section>
-
- <section id="control-interface-control-names">
- <title>Control Names</title>
- <para>
- There are some standards to define the control names. A
- control is usually defined from the three parts as
- <quote>SOURCE DIRECTION FUNCTION</quote>.
- </para>
-
- <para>
- The first, <constant>SOURCE</constant>, specifies the source
- of the control, and is a string such as <quote>Master</quote>,
- <quote>PCM</quote>, <quote>CD</quote> and
- <quote>Line</quote>. There are many pre-defined sources.
- </para>
-
- <para>
- The second, <constant>DIRECTION</constant>, is one of the
- following strings according to the direction of the control:
- <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass
- Playback</quote> and <quote>Bypass Capture</quote>. Or, it can
- be omitted, meaning both playback and capture directions.
- </para>
-
- <para>
- The third, <constant>FUNCTION</constant>, is one of the
- following strings according to the function of the control:
- <quote>Switch</quote>, <quote>Volume</quote> and
- <quote>Route</quote>.
- </para>
-
- <para>
- The example of control names are, thus, <quote>Master Capture
- Switch</quote> or <quote>PCM Playback Volume</quote>.
- </para>
-
- <para>
- There are some exceptions:
- </para>
-
- <section id="control-interface-control-names-global">
- <title>Global capture and playback</title>
- <para>
- <quote>Capture Source</quote>, <quote>Capture Switch</quote>
- and <quote>Capture Volume</quote> are used for the global
- capture (input) source, switch and volume. Similarly,
- <quote>Playback Switch</quote> and <quote>Playback
- Volume</quote> are used for the global output gain switch and
- volume.
- </para>
- </section>
-
- <section id="control-interface-control-names-tone">
- <title>Tone-controls</title>
- <para>
- tone-control switch and volumes are specified like
- <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control -
- Switch</quote>, <quote>Tone Control - Bass</quote>,
- <quote>Tone Control - Center</quote>.
- </para>
- </section>
-
- <section id="control-interface-control-names-3d">
- <title>3D controls</title>
- <para>
- 3D-control switches and volumes are specified like <quote>3D
- Control - XXX</quote>, e.g. <quote>3D Control -
- Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D
- Control - Space</quote>.
- </para>
- </section>
-
- <section id="control-interface-control-names-mic">
- <title>Mic boost</title>
- <para>
- Mic-boost switch is set as <quote>Mic Boost</quote> or
- <quote>Mic Boost (6dB)</quote>.
- </para>
-
- <para>
- More precise information can be found in
- <filename>Documentation/sound/alsa/ControlNames.txt</filename>.
- </para>
- </section>
- </section>
-
- <section id="control-interface-access-flags">
- <title>Access Flags</title>
-
- <para>
- The access flag is the bitmask which specifies the access type
- of the given control. The default access type is
- <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>,
- which means both read and write are allowed to this control.
- When the access flag is omitted (i.e. = 0), it is
- considered as <constant>READWRITE</constant> access as default.
- </para>
-
- <para>
- When the control is read-only, pass
- <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead.
- In this case, you don't have to define
- the <structfield>put</structfield> callback.
- Similarly, when the control is write-only (although it's a rare
- case), you can use the <constant>WRITE</constant> flag instead, and
- you don't need the <structfield>get</structfield> callback.
- </para>
-
- <para>
- If the control value changes frequently (e.g. the VU meter),
- <constant>VOLATILE</constant> flag should be given. This means
- that the control may be changed without
- <link linkend="control-interface-change-notification"><citetitle>
- notification</citetitle></link>. Applications should poll such
- a control constantly.
- </para>
-
- <para>
- When the control is inactive, set
- the <constant>INACTIVE</constant> flag, too.
- There are <constant>LOCK</constant> and
- <constant>OWNER</constant> flags to change the write
- permissions.
- </para>
-
- </section>
-
- <section id="control-interface-callbacks">
- <title>Callbacks</title>
-
- <section id="control-interface-callbacks-info">
- <title>info callback</title>
- <para>
- The <structfield>info</structfield> callback is used to get
- detailed information on this control. This must store the
- values of the given struct <structname>snd_ctl_elem_info</structname>
- object. For example, for a boolean control with a single
- element:
-
- <example>
- <title>Example of info callback</title>
- <programlisting>
-<![CDATA[
- static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
- struct snd_ctl_elem_info *uinfo)
- {
- uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
- uinfo->count = 1;
- uinfo->value.integer.min = 0;
- uinfo->value.integer.max = 1;
- return 0;
- }
-]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- The <structfield>type</structfield> field specifies the type
- of the control. There are <constant>BOOLEAN</constant>,
- <constant>INTEGER</constant>, <constant>ENUMERATED</constant>,
- <constant>BYTES</constant>, <constant>IEC958</constant> and
- <constant>INTEGER64</constant>. The
- <structfield>count</structfield> field specifies the
- number of elements in this control. For example, a stereo
- volume would have count = 2. The
- <structfield>value</structfield> field is a union, and
- the values stored are depending on the type. The boolean and
- integer types are identical.
- </para>
-
- <para>
- The enumerated type is a bit different from others. You'll
- need to set the string for the currently given item index.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
- struct snd_ctl_elem_info *uinfo)
- {
- static char *texts[4] = {
- "First", "Second", "Third", "Fourth"
- };
- uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
- uinfo->count = 1;
- uinfo->value.enumerated.items = 4;
- if (uinfo->value.enumerated.item > 3)
- uinfo->value.enumerated.item = 3;
- strcpy(uinfo->value.enumerated.name,
- texts[uinfo->value.enumerated.item]);
- return 0;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The above callback can be simplified with a helper function,
- <function>snd_ctl_enum_info</function>. The final code
- looks like below.
- (You can pass ARRAY_SIZE(texts) instead of 4 in the third
- argument; it's a matter of taste.)
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
- struct snd_ctl_elem_info *uinfo)
- {
- static char *texts[4] = {
- "First", "Second", "Third", "Fourth"
- };
- return snd_ctl_enum_info(uinfo, 1, 4, texts);
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Some common info callbacks are available for your convenience:
- <function>snd_ctl_boolean_mono_info()</function> and
- <function>snd_ctl_boolean_stereo_info()</function>.
- Obviously, the former is an info callback for a mono channel
- boolean item, just like <function>snd_myctl_mono_info</function>
- above, and the latter is for a stereo channel boolean item.
- </para>
-
- </section>
-
- <section id="control-interface-callbacks-get">
- <title>get callback</title>
-
- <para>
- This callback is used to read the current value of the
- control and to return to user-space.
- </para>
-
- <para>
- For example,
-
- <example>
- <title>Example of get callback</title>
- <programlisting>
-<![CDATA[
- static int snd_myctl_get(struct snd_kcontrol *kcontrol,
- struct snd_ctl_elem_value *ucontrol)
- {
- struct mychip *chip = snd_kcontrol_chip(kcontrol);
- ucontrol->value.integer.value[0] = get_some_value(chip);
- return 0;
- }
-]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- The <structfield>value</structfield> field depends on
- the type of control as well as on the info callback. For example,
- the sb driver uses this field to store the register offset,
- the bit-shift and the bit-mask. The
- <structfield>private_value</structfield> field is set as follows:
- <informalexample>
- <programlisting>
-<![CDATA[
- .private_value = reg | (shift << 16) | (mask << 24)
-]]>
- </programlisting>
- </informalexample>
- and is retrieved in callbacks like
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
- struct snd_ctl_elem_value *ucontrol)
- {
- int reg = kcontrol->private_value & 0xff;
- int shift = (kcontrol->private_value >> 16) & 0xff;
- int mask = (kcontrol->private_value >> 24) & 0xff;
- ....
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- In the <structfield>get</structfield> callback,
- you have to fill all the elements if the
- control has more than one elements,
- i.e. <structfield>count</structfield> &gt; 1.
- In the example above, we filled only one element
- (<structfield>value.integer.value[0]</structfield>) since it's
- assumed as <structfield>count</structfield> = 1.
- </para>
- </section>
-
- <section id="control-interface-callbacks-put">
- <title>put callback</title>
-
- <para>
- This callback is used to write a value from user-space.
- </para>
-
- <para>
- For example,
-
- <example>
- <title>Example of put callback</title>
- <programlisting>
-<![CDATA[
- static int snd_myctl_put(struct snd_kcontrol *kcontrol,
- struct snd_ctl_elem_value *ucontrol)
- {
- struct mychip *chip = snd_kcontrol_chip(kcontrol);
- int changed = 0;
- if (chip->current_value !=
- ucontrol->value.integer.value[0]) {
- change_current_value(chip,
- ucontrol->value.integer.value[0]);
- changed = 1;
- }
- return changed;
- }
-]]>
- </programlisting>
- </example>
-
- As seen above, you have to return 1 if the value is
- changed. If the value is not changed, return 0 instead.
- If any fatal error happens, return a negative error code as
- usual.
- </para>
-
- <para>
- As in the <structfield>get</structfield> callback,
- when the control has more than one elements,
- all elements must be evaluated in this callback, too.
- </para>
- </section>
-
- <section id="control-interface-callbacks-all">
- <title>Callbacks are not atomic</title>
- <para>
- All these three callbacks are basically not atomic.
- </para>
- </section>
- </section>
-
- <section id="control-interface-constructor">
- <title>Constructor</title>
- <para>
- When everything is ready, finally we can create a new
- control. To create a control, there are two functions to be
- called, <function>snd_ctl_new1()</function> and
- <function>snd_ctl_add()</function>.
- </para>
-
- <para>
- In the simplest way, you can do like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
- if (err < 0)
- return err;
-]]>
- </programlisting>
- </informalexample>
-
- where <parameter>my_control</parameter> is the
- struct <structname>snd_kcontrol_new</structname> object defined above, and chip
- is the object pointer to be passed to
- kcontrol-&gt;private_data
- which can be referred to in callbacks.
- </para>
-
- <para>
- <function>snd_ctl_new1()</function> allocates a new
- <structname>snd_kcontrol</structname> instance,
- and <function>snd_ctl_add</function> assigns the given
- control component to the card.
- </para>
- </section>
-
- <section id="control-interface-change-notification">
- <title>Change Notification</title>
- <para>
- If you need to change and update a control in the interrupt
- routine, you can call <function>snd_ctl_notify()</function>. For
- example,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
-]]>
- </programlisting>
- </informalexample>
-
- This function takes the card pointer, the event-mask, and the
- control id pointer for the notification. The event-mask
- specifies the types of notification, for example, in the above
- example, the change of control values is notified.
- The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname>
- to be notified.
- You can find some examples in <filename>es1938.c</filename> or
- <filename>es1968.c</filename> for hardware volume interrupts.
- </para>
- </section>
-
- <section id="control-interface-tlv">
- <title>Metadata</title>
- <para>
- To provide information about the dB values of a mixer control, use
- on of the <constant>DECLARE_TLV_xxx</constant> macros from
- <filename>&lt;sound/tlv.h&gt;</filename> to define a variable
- containing this information, set the<structfield>tlv.p
- </structfield> field to point to this variable, and include the
- <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the
- <structfield>access</structfield> field; like this:
- <informalexample>
- <programlisting>
-<![CDATA[
- static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
-
- static struct snd_kcontrol_new my_control = {
- ...
- .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
- SNDRV_CTL_ELEM_ACCESS_TLV_READ,
- ...
- .tlv.p = db_scale_my_control,
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The <function>DECLARE_TLV_DB_SCALE</function> macro defines
- information about a mixer control where each step in the control's
- value changes the dB value by a constant dB amount.
- The first parameter is the name of the variable to be defined.
- The second parameter is the minimum value, in units of 0.01 dB.
- The third parameter is the step size, in units of 0.01 dB.
- Set the fourth parameter to 1 if the minimum value actually mutes
- the control.
- </para>
-
- <para>
- The <function>DECLARE_TLV_DB_LINEAR</function> macro defines
- information about a mixer control where the control's value affects
- the output linearly.
- The first parameter is the name of the variable to be defined.
- The second parameter is the minimum value, in units of 0.01 dB.
- The third parameter is the maximum value, in units of 0.01 dB.
- If the minimum value mutes the control, set the second parameter to
- <constant>TLV_DB_GAIN_MUTE</constant>.
- </para>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- API for AC97 Codec -->
-<!-- ****************************************************** -->
- <chapter id="api-ac97">
- <title>API for AC97 Codec</title>
-
- <section>
- <title>General</title>
- <para>
- The ALSA AC97 codec layer is a well-defined one, and you don't
- have to write much code to control it. Only low-level control
- routines are necessary. The AC97 codec API is defined in
- <filename>&lt;sound/ac97_codec.h&gt;</filename>.
- </para>
- </section>
-
- <section id="api-ac97-example">
- <title>Full Code Example</title>
- <para>
- <example>
- <title>Example of AC97 Interface</title>
- <programlisting>
-<![CDATA[
- struct mychip {
- ....
- struct snd_ac97 *ac97;
- ....
- };
-
- static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
- unsigned short reg)
- {
- struct mychip *chip = ac97->private_data;
- ....
- /* read a register value here from the codec */
- return the_register_value;
- }
-
- static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
- unsigned short reg, unsigned short val)
- {
- struct mychip *chip = ac97->private_data;
- ....
- /* write the given register value to the codec */
- }
-
- static int snd_mychip_ac97(struct mychip *chip)
- {
- struct snd_ac97_bus *bus;
- struct snd_ac97_template ac97;
- int err;
- static struct snd_ac97_bus_ops ops = {
- .write = snd_mychip_ac97_write,
- .read = snd_mychip_ac97_read,
- };
-
- err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
- if (err < 0)
- return err;
- memset(&ac97, 0, sizeof(ac97));
- ac97.private_data = chip;
- return snd_ac97_mixer(bus, &ac97, &chip->ac97);
- }
-
-]]>
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="api-ac97-constructor">
- <title>Constructor</title>
- <para>
- To create an ac97 instance, first call <function>snd_ac97_bus</function>
- with an <type>ac97_bus_ops_t</type> record with callback functions.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_ac97_bus *bus;
- static struct snd_ac97_bus_ops ops = {
- .write = snd_mychip_ac97_write,
- .read = snd_mychip_ac97_read,
- };
-
- snd_ac97_bus(card, 0, &ops, NULL, &pbus);
-]]>
- </programlisting>
- </informalexample>
-
- The bus record is shared among all belonging ac97 instances.
- </para>
-
- <para>
- And then call <function>snd_ac97_mixer()</function> with an
- struct <structname>snd_ac97_template</structname>
- record together with the bus pointer created above.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_ac97_template ac97;
- int err;
-
- memset(&ac97, 0, sizeof(ac97));
- ac97.private_data = chip;
- snd_ac97_mixer(bus, &ac97, &chip->ac97);
-]]>
- </programlisting>
- </informalexample>
-
- where chip-&gt;ac97 is a pointer to a newly created
- <type>ac97_t</type> instance.
- In this case, the chip pointer is set as the private data, so that
- the read/write callback functions can refer to this chip instance.
- This instance is not necessarily stored in the chip
- record. If you need to change the register values from the
- driver, or need the suspend/resume of ac97 codecs, keep this
- pointer to pass to the corresponding functions.
- </para>
- </section>
-
- <section id="api-ac97-callbacks">
- <title>Callbacks</title>
- <para>
- The standard callbacks are <structfield>read</structfield> and
- <structfield>write</structfield>. Obviously they
- correspond to the functions for read and write accesses to the
- hardware low-level codes.
- </para>
-
- <para>
- The <structfield>read</structfield> callback returns the
- register value specified in the argument.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
- unsigned short reg)
- {
- struct mychip *chip = ac97->private_data;
- ....
- return the_register_value;
- }
-]]>
- </programlisting>
- </informalexample>
-
- Here, the chip can be cast from ac97-&gt;private_data.
- </para>
-
- <para>
- Meanwhile, the <structfield>write</structfield> callback is
- used to set the register value.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
- unsigned short reg, unsigned short val)
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- These callbacks are non-atomic like the control API callbacks.
- </para>
-
- <para>
- There are also other callbacks:
- <structfield>reset</structfield>,
- <structfield>wait</structfield> and
- <structfield>init</structfield>.
- </para>
-
- <para>
- The <structfield>reset</structfield> callback is used to reset
- the codec. If the chip requires a special kind of reset, you can
- define this callback.
- </para>
-
- <para>
- The <structfield>wait</structfield> callback is used to
- add some waiting time in the standard initialization of the codec. If the
- chip requires the extra waiting time, define this callback.
- </para>
-
- <para>
- The <structfield>init</structfield> callback is used for
- additional initialization of the codec.
- </para>
- </section>
-
- <section id="api-ac97-updating-registers">
- <title>Updating Registers in The Driver</title>
- <para>
- If you need to access to the codec from the driver, you can
- call the following functions:
- <function>snd_ac97_write()</function>,
- <function>snd_ac97_read()</function>,
- <function>snd_ac97_update()</function> and
- <function>snd_ac97_update_bits()</function>.
- </para>
-
- <para>
- Both <function>snd_ac97_write()</function> and
- <function>snd_ac97_update()</function> functions are used to
- set a value to the given register
- (<constant>AC97_XXX</constant>). The difference between them is
- that <function>snd_ac97_update()</function> doesn't write a
- value if the given value has been already set, while
- <function>snd_ac97_write()</function> always rewrites the
- value.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_ac97_write(ac97, AC97_MASTER, 0x8080);
- snd_ac97_update(ac97, AC97_MASTER, 0x8080);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- <function>snd_ac97_read()</function> is used to read the value
- of the given register. For example,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- value = snd_ac97_read(ac97, AC97_MASTER);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- <function>snd_ac97_update_bits()</function> is used to update
- some bits in the given register.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_ac97_update_bits(ac97, reg, mask, value);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Also, there is a function to change the sample rate (of a
- given register such as
- <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or
- DRA is supported by the codec:
- <function>snd_ac97_set_rate()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The following registers are available to set the rate:
- <constant>AC97_PCM_MIC_ADC_RATE</constant>,
- <constant>AC97_PCM_FRONT_DAC_RATE</constant>,
- <constant>AC97_PCM_LR_ADC_RATE</constant>,
- <constant>AC97_SPDIF</constant>. When
- <constant>AC97_SPDIF</constant> is specified, the register is
- not really changed but the corresponding IEC958 status bits will
- be updated.
- </para>
- </section>
-
- <section id="api-ac97-clock-adjustment">
- <title>Clock Adjustment</title>
- <para>
- In some chips, the clock of the codec isn't 48000 but using a
- PCI clock (to save a quartz!). In this case, change the field
- bus-&gt;clock to the corresponding
- value. For example, intel8x0
- and es1968 drivers have their own function to read from the clock.
- </para>
- </section>
-
- <section id="api-ac97-proc-files">
- <title>Proc Files</title>
- <para>
- The ALSA AC97 interface will create a proc file such as
- <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and
- <filename>ac97#0-0+regs</filename>. You can refer to these files to
- see the current status and registers of the codec.
- </para>
- </section>
-
- <section id="api-ac97-multiple-codecs">
- <title>Multiple Codecs</title>
- <para>
- When there are several codecs on the same card, you need to
- call <function>snd_ac97_mixer()</function> multiple times with
- ac97.num=1 or greater. The <structfield>num</structfield> field
- specifies the codec number.
- </para>
-
- <para>
- If you set up multiple codecs, you either need to write
- different callbacks for each codec or check
- ac97-&gt;num in the callback routines.
- </para>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- MIDI (MPU401-UART) Interface -->
-<!-- ****************************************************** -->
- <chapter id="midi-interface">
- <title>MIDI (MPU401-UART) Interface</title>
-
- <section id="midi-interface-general">
- <title>General</title>
- <para>
- Many soundcards have built-in MIDI (MPU401-UART)
- interfaces. When the soundcard supports the standard MPU401-UART
- interface, most likely you can use the ALSA MPU401-UART API. The
- MPU401-UART API is defined in
- <filename>&lt;sound/mpu401.h&gt;</filename>.
- </para>
-
- <para>
- Some soundchips have a similar but slightly different
- implementation of mpu401 stuff. For example, emu10k1 has its own
- mpu401 routines.
- </para>
- </section>
-
- <section id="midi-interface-constructor">
- <title>Constructor</title>
- <para>
- To create a rawmidi object, call
- <function>snd_mpu401_uart_new()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_rawmidi *rmidi;
- snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
- irq, &rmidi);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The first argument is the card pointer, and the second is the
- index of this component. You can create up to 8 rawmidi
- devices.
- </para>
-
- <para>
- The third argument is the type of the hardware,
- <constant>MPU401_HW_XXX</constant>. If it's not a special one,
- you can use <constant>MPU401_HW_MPU401</constant>.
- </para>
-
- <para>
- The 4th argument is the I/O port address. Many
- backward-compatible MPU401 have an I/O port such as 0x330. Or, it
- might be a part of its own PCI I/O region. It depends on the
- chip design.
- </para>
-
- <para>
- The 5th argument is a bitflag for additional information.
- When the I/O port address above is part of the PCI I/O
- region, the MPU401 I/O port might have been already allocated
- (reserved) by the driver itself. In such a case, pass a bit flag
- <constant>MPU401_INFO_INTEGRATED</constant>,
- and the mpu401-uart layer will allocate the I/O ports by itself.
- </para>
-
- <para>
- When the controller supports only the input or output MIDI stream,
- pass the <constant>MPU401_INFO_INPUT</constant> or
- <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively.
- Then the rawmidi instance is created as a single stream.
- </para>
-
- <para>
- <constant>MPU401_INFO_MMIO</constant> bitflag is used to change
- the access method to MMIO (via readb and writeb) instead of
- iob and outb. In this case, you have to pass the iomapped address
- to <function>snd_mpu401_uart_new()</function>.
- </para>
-
- <para>
- When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output
- stream isn't checked in the default interrupt handler. The driver
- needs to call <function>snd_mpu401_uart_interrupt_tx()</function>
- by itself to start processing the output stream in the irq handler.
- </para>
-
- <para>
- If the MPU-401 interface shares its interrupt with the other logical
- devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant>
- (see <link linkend="midi-interface-interrupt-handler"><citetitle>
- below</citetitle></link>).
- </para>
-
- <para>
- Usually, the port address corresponds to the command port and
- port + 1 corresponds to the data port. If not, you may change
- the <structfield>cport</structfield> field of
- struct <structname>snd_mpu401</structname> manually
- afterward. However, <structname>snd_mpu401</structname> pointer is not
- returned explicitly by
- <function>snd_mpu401_uart_new()</function>. You need to cast
- rmidi-&gt;private_data to
- <structname>snd_mpu401</structname> explicitly,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_mpu401 *mpu;
- mpu = rmidi->private_data;
-]]>
- </programlisting>
- </informalexample>
-
- and reset the cport as you like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- mpu->cport = my_own_control_port;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The 6th argument specifies the ISA irq number that will be
- allocated. If no interrupt is to be allocated (because your
- code is already allocating a shared interrupt, or because the
- device does not use interrupts), pass -1 instead.
- For a MPU-401 device without an interrupt, a polling timer
- will be used instead.
- </para>
- </section>
-
- <section id="midi-interface-interrupt-handler">
- <title>Interrupt Handler</title>
- <para>
- When the interrupt is allocated in
- <function>snd_mpu401_uart_new()</function>, an exclusive ISA
- interrupt handler is automatically used, hence you don't have
- anything else to do than creating the mpu401 stuff. Otherwise, you
- have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call
- <function>snd_mpu401_uart_interrupt()</function> explicitly from your
- own interrupt handler when it has determined that a UART interrupt
- has occurred.
- </para>
-
- <para>
- In this case, you need to pass the private_data of the
- returned rawmidi object from
- <function>snd_mpu401_uart_new()</function> as the second
- argument of <function>snd_mpu401_uart_interrupt()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- RawMIDI Interface -->
-<!-- ****************************************************** -->
- <chapter id="rawmidi-interface">
- <title>RawMIDI Interface</title>
-
- <section id="rawmidi-interface-overview">
- <title>Overview</title>
-
- <para>
- The raw MIDI interface is used for hardware MIDI ports that can
- be accessed as a byte stream. It is not used for synthesizer
- chips that do not directly understand MIDI.
- </para>
-
- <para>
- ALSA handles file and buffer management. All you have to do is
- to write some code to move data between the buffer and the
- hardware.
- </para>
-
- <para>
- The rawmidi API is defined in
- <filename>&lt;sound/rawmidi.h&gt;</filename>.
- </para>
- </section>
-
- <section id="rawmidi-interface-constructor">
- <title>Constructor</title>
-
- <para>
- To create a rawmidi device, call the
- <function>snd_rawmidi_new</function> function:
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_rawmidi *rmidi;
- err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
- if (err < 0)
- return err;
- rmidi->private_data = chip;
- strcpy(rmidi->name, "My MIDI");
- rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
- SNDRV_RAWMIDI_INFO_INPUT |
- SNDRV_RAWMIDI_INFO_DUPLEX;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The first argument is the card pointer, the second argument is
- the ID string.
- </para>
-
- <para>
- The third argument is the index of this component. You can
- create up to 8 rawmidi devices.
- </para>
-
- <para>
- The fourth and fifth arguments are the number of output and
- input substreams, respectively, of this device (a substream is
- the equivalent of a MIDI port).
- </para>
-
- <para>
- Set the <structfield>info_flags</structfield> field to specify
- the capabilities of the device.
- Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is
- at least one output port,
- <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at
- least one input port,
- and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device
- can handle output and input at the same time.
- </para>
-
- <para>
- After the rawmidi device is created, you need to set the
- operators (callbacks) for each substream. There are helper
- functions to set the operators for all the substreams of a device:
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
- snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The operators are usually defined like this:
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct snd_rawmidi_ops snd_mymidi_output_ops = {
- .open = snd_mymidi_output_open,
- .close = snd_mymidi_output_close,
- .trigger = snd_mymidi_output_trigger,
- };
-]]>
- </programlisting>
- </informalexample>
- These callbacks are explained in the <link
- linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link>
- section.
- </para>
-
- <para>
- If there are more than one substream, you should give a
- unique name to each of them:
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_rawmidi_substream *substream;
- list_for_each_entry(substream,
- &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
- list {
- sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
- }
- /* same for SNDRV_RAWMIDI_STREAM_INPUT */
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- <section id="rawmidi-interface-callbacks">
- <title>Callbacks</title>
-
- <para>
- In all the callbacks, the private data that you've set for the
- rawmidi device can be accessed as
- substream-&gt;rmidi-&gt;private_data.
- <!-- <code> isn't available before DocBook 4.3 -->
- </para>
-
- <para>
- If there is more than one port, your callbacks can determine the
- port index from the struct snd_rawmidi_substream data passed to each
- callback:
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_rawmidi_substream *substream;
- int index = substream->number;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <section id="rawmidi-interface-op-open">
- <title><function>open</function> callback</title>
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_open(struct snd_rawmidi_substream *substream);
-]]>
- </programlisting>
- </informalexample>
-
- <para>
- This is called when a substream is opened.
- You can initialize the hardware here, but you shouldn't
- start transmitting/receiving data yet.
- </para>
- </section>
-
- <section id="rawmidi-interface-op-close">
- <title><function>close</function> callback</title>
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_xxx_close(struct snd_rawmidi_substream *substream);
-]]>
- </programlisting>
- </informalexample>
-
- <para>
- Guess what.
- </para>
-
- <para>
- The <function>open</function> and <function>close</function>
- callbacks of a rawmidi device are serialized with a mutex,
- and can sleep.
- </para>
- </section>
-
- <section id="rawmidi-interface-op-trigger-out">
- <title><function>trigger</function> callback for output
- substreams</title>
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
-]]>
- </programlisting>
- </informalexample>
-
- <para>
- This is called with a nonzero <parameter>up</parameter>
- parameter when there is some data in the substream buffer that
- must be transmitted.
- </para>
-
- <para>
- To read data from the buffer, call
- <function>snd_rawmidi_transmit_peek</function>. It will
- return the number of bytes that have been read; this will be
- less than the number of bytes requested when there are no more
- data in the buffer.
- After the data have been transmitted successfully, call
- <function>snd_rawmidi_transmit_ack</function> to remove the
- data from the substream buffer:
- <informalexample>
- <programlisting>
-<![CDATA[
- unsigned char data;
- while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
- if (snd_mychip_try_to_transmit(data))
- snd_rawmidi_transmit_ack(substream, 1);
- else
- break; /* hardware FIFO full */
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- If you know beforehand that the hardware will accept data, you
- can use the <function>snd_rawmidi_transmit</function> function
- which reads some data and removes them from the buffer at once:
- <informalexample>
- <programlisting>
-<![CDATA[
- while (snd_mychip_transmit_possible()) {
- unsigned char data;
- if (snd_rawmidi_transmit(substream, &data, 1) != 1)
- break; /* no more data */
- snd_mychip_transmit(data);
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- If you know beforehand how many bytes you can accept, you can
- use a buffer size greater than one with the
- <function>snd_rawmidi_transmit*</function> functions.
- </para>
-
- <para>
- The <function>trigger</function> callback must not sleep. If
- the hardware FIFO is full before the substream buffer has been
- emptied, you have to continue transmitting data later, either
- in an interrupt handler, or with a timer if the hardware
- doesn't have a MIDI transmit interrupt.
- </para>
-
- <para>
- The <function>trigger</function> callback is called with a
- zero <parameter>up</parameter> parameter when the transmission
- of data should be aborted.
- </para>
- </section>
-
- <section id="rawmidi-interface-op-trigger-in">
- <title><function>trigger</function> callback for input
- substreams</title>
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
-]]>
- </programlisting>
- </informalexample>
-
- <para>
- This is called with a nonzero <parameter>up</parameter>
- parameter to enable receiving data, or with a zero
- <parameter>up</parameter> parameter do disable receiving data.
- </para>
-
- <para>
- The <function>trigger</function> callback must not sleep; the
- actual reading of data from the device is usually done in an
- interrupt handler.
- </para>
-
- <para>
- When data reception is enabled, your interrupt handler should
- call <function>snd_rawmidi_receive</function> for all received
- data:
- <informalexample>
- <programlisting>
-<![CDATA[
- void snd_mychip_midi_interrupt(...)
- {
- while (mychip_midi_available()) {
- unsigned char data;
- data = mychip_midi_read();
- snd_rawmidi_receive(substream, &data, 1);
- }
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- <section id="rawmidi-interface-op-drain">
- <title><function>drain</function> callback</title>
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
-]]>
- </programlisting>
- </informalexample>
-
- <para>
- This is only used with output substreams. This function should wait
- until all data read from the substream buffer have been transmitted.
- This ensures that the device can be closed and the driver unloaded
- without losing data.
- </para>
-
- <para>
- This callback is optional. If you do not set
- <structfield>drain</structfield> in the struct snd_rawmidi_ops
- structure, ALSA will simply wait for 50&nbsp;milliseconds
- instead.
- </para>
- </section>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Miscellaneous Devices -->
-<!-- ****************************************************** -->
- <chapter id="misc-devices">
- <title>Miscellaneous Devices</title>
-
- <section id="misc-devices-opl3">
- <title>FM OPL3</title>
- <para>
- The FM OPL3 is still used in many chips (mainly for backward
- compatibility). ALSA has a nice OPL3 FM control layer, too. The
- OPL3 API is defined in
- <filename>&lt;sound/opl3.h&gt;</filename>.
- </para>
-
- <para>
- FM registers can be directly accessed through the direct-FM API,
- defined in <filename>&lt;sound/asound_fm.h&gt;</filename>. In
- ALSA native mode, FM registers are accessed through
- the Hardware-Dependent Device direct-FM extension API, whereas in
- OSS compatible mode, FM registers can be accessed with the OSS
- direct-FM compatible API in <filename>/dev/dmfmX</filename> device.
- </para>
-
- <para>
- To create the OPL3 component, you have two functions to
- call. The first one is a constructor for the <type>opl3_t</type>
- instance.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_opl3 *opl3;
- snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
- integrated, &opl3);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The first argument is the card pointer, the second one is the
- left port address, and the third is the right port address. In
- most cases, the right port is placed at the left port + 2.
- </para>
-
- <para>
- The fourth argument is the hardware type.
- </para>
-
- <para>
- When the left and right ports have been already allocated by
- the card driver, pass non-zero to the fifth argument
- (<parameter>integrated</parameter>). Otherwise, the opl3 module will
- allocate the specified ports by itself.
- </para>
-
- <para>
- When the accessing the hardware requires special method
- instead of the standard I/O access, you can create opl3 instance
- separately with <function>snd_opl3_new()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_opl3 *opl3;
- snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Then set <structfield>command</structfield>,
- <structfield>private_data</structfield> and
- <structfield>private_free</structfield> for the private
- access function, the private data and the destructor.
- The l_port and r_port are not necessarily set. Only the
- command must be set properly. You can retrieve the data
- from the opl3-&gt;private_data field.
- </para>
-
- <para>
- After creating the opl3 instance via <function>snd_opl3_new()</function>,
- call <function>snd_opl3_init()</function> to initialize the chip to the
- proper state. Note that <function>snd_opl3_create()</function> always
- calls it internally.
- </para>
-
- <para>
- If the opl3 instance is created successfully, then create a
- hwdep device for this opl3.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_hwdep *opl3hwdep;
- snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The first argument is the <type>opl3_t</type> instance you
- created, and the second is the index number, usually 0.
- </para>
-
- <para>
- The third argument is the index-offset for the sequencer
- client assigned to the OPL3 port. When there is an MPU401-UART,
- give 1 for here (UART always takes 0).
- </para>
- </section>
-
- <section id="misc-devices-hardware-dependent">
- <title>Hardware-Dependent Devices</title>
- <para>
- Some chips need user-space access for special
- controls or for loading the micro code. In such a case, you can
- create a hwdep (hardware-dependent) device. The hwdep API is
- defined in <filename>&lt;sound/hwdep.h&gt;</filename>. You can
- find examples in opl3 driver or
- <filename>isa/sb/sb16_csp.c</filename>.
- </para>
-
- <para>
- The creation of the <type>hwdep</type> instance is done via
- <function>snd_hwdep_new()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_hwdep *hw;
- snd_hwdep_new(card, "My HWDEP", 0, &hw);
-]]>
- </programlisting>
- </informalexample>
-
- where the third argument is the index number.
- </para>
-
- <para>
- You can then pass any pointer value to the
- <parameter>private_data</parameter>.
- If you assign a private data, you should define the
- destructor, too. The destructor function is set in
- the <structfield>private_free</structfield> field.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
- hw->private_data = p;
- hw->private_free = mydata_free;
-]]>
- </programlisting>
- </informalexample>
-
- and the implementation of the destructor would be:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void mydata_free(struct snd_hwdep *hw)
- {
- struct mydata *p = hw->private_data;
- kfree(p);
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The arbitrary file operations can be defined for this
- instance. The file operators are defined in
- the <parameter>ops</parameter> table. For example, assume that
- this chip needs an ioctl.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- hw->ops.open = mydata_open;
- hw->ops.ioctl = mydata_ioctl;
- hw->ops.release = mydata_release;
-]]>
- </programlisting>
- </informalexample>
-
- And implement the callback functions as you like.
- </para>
- </section>
-
- <section id="misc-devices-IEC958">
- <title>IEC958 (S/PDIF)</title>
- <para>
- Usually the controls for IEC958 devices are implemented via
- the control interface. There is a macro to compose a name string for
- IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function>
- defined in <filename>&lt;include/asound.h&gt;</filename>.
- </para>
-
- <para>
- There are some standard controls for IEC958 status bits. These
- controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>,
- and the size of element is fixed as 4 bytes array
- (value.iec958.status[x]). For the <structfield>info</structfield>
- callback, you don't specify
- the value field for this type (the count field must be set,
- though).
- </para>
-
- <para>
- <quote>IEC958 Playback Con Mask</quote> is used to return the
- bit-mask for the IEC958 status bits of consumer mode. Similarly,
- <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for
- professional mode. They are read-only controls, and are defined
- as MIXER controls (iface =
- <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>).
- </para>
-
- <para>
- Meanwhile, <quote>IEC958 Playback Default</quote> control is
- defined for getting and setting the current default IEC958
- bits. Note that this one is usually defined as a PCM control
- (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>),
- although in some places it's defined as a MIXER control.
- </para>
-
- <para>
- In addition, you can define the control switches to
- enable/disable or to set the raw bit mode. The implementation
- will depend on the chip, but the control should be named as
- <quote>IEC958 xxx</quote>, preferably using
- the <function>SNDRV_CTL_NAME_IEC958()</function> macro.
- </para>
-
- <para>
- You can find several cases, for example,
- <filename>pci/emu10k1</filename>,
- <filename>pci/ice1712</filename>, or
- <filename>pci/cmipci.c</filename>.
- </para>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Buffer and Memory Management -->
-<!-- ****************************************************** -->
- <chapter id="buffer-and-memory">
- <title>Buffer and Memory Management</title>
-
- <section id="buffer-and-memory-buffer-types">
- <title>Buffer Types</title>
- <para>
- ALSA provides several different buffer allocation functions
- depending on the bus and the architecture. All these have a
- consistent API. The allocation of physically-contiguous pages is
- done via
- <function>snd_malloc_xxx_pages()</function> function, where xxx
- is the bus type.
- </para>
-
- <para>
- The allocation of pages with fallback is
- <function>snd_malloc_xxx_pages_fallback()</function>. This
- function tries to allocate the specified pages but if the pages
- are not available, it tries to reduce the page sizes until
- enough space is found.
- </para>
-
- <para>
- The release the pages, call
- <function>snd_free_xxx_pages()</function> function.
- </para>
-
- <para>
- Usually, ALSA drivers try to allocate and reserve
- a large contiguous physical space
- at the time the module is loaded for the later use.
- This is called <quote>pre-allocation</quote>.
- As already written, you can call the following function at
- pcm instance construction time (in the case of PCI bus).
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
- snd_dma_pci_data(pci), size, max);
-]]>
- </programlisting>
- </informalexample>
-
- where <parameter>size</parameter> is the byte size to be
- pre-allocated and the <parameter>max</parameter> is the maximum
- size to be changed via the <filename>prealloc</filename> proc file.
- The allocator will try to get an area as large as possible
- within the given size.
- </para>
-
- <para>
- The second argument (type) and the third argument (device pointer)
- are dependent on the bus.
- In the case of the ISA bus, pass <function>snd_dma_isa_data()</function>
- as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type.
- For the continuous buffer unrelated to the bus can be pre-allocated
- with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
- <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
- where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
- use.
- For the PCI scatter-gather buffers, use
- <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
- <function>snd_dma_pci_data(pci)</function>
- (see the
- <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers
- </citetitle></link> section).
- </para>
-
- <para>
- Once the buffer is pre-allocated, you can use the
- allocator in the <structfield>hw_params</structfield> callback:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_pcm_lib_malloc_pages(substream, size);
-]]>
- </programlisting>
- </informalexample>
-
- Note that you have to pre-allocate to use this function.
- </para>
- </section>
-
- <section id="buffer-and-memory-external-hardware">
- <title>External Hardware Buffers</title>
- <para>
- Some chips have their own hardware buffers and the DMA
- transfer from the host memory is not available. In such a case,
- you need to either 1) copy/set the audio data directly to the
- external hardware buffer, or 2) make an intermediate buffer and
- copy/set the data from it to the external hardware buffer in
- interrupts (or in tasklets, preferably).
- </para>
-
- <para>
- The first case works fine if the external hardware buffer is large
- enough. This method doesn't need any extra buffers and thus is
- more effective. You need to define the
- <structfield>copy</structfield> and
- <structfield>silence</structfield> callbacks for
- the data transfer. However, there is a drawback: it cannot
- be mmapped. The examples are GUS's GF1 PCM or emu8000's
- wavetable PCM.
- </para>
-
- <para>
- The second case allows for mmap on the buffer, although you have
- to handle an interrupt or a tasklet to transfer the data
- from the intermediate buffer to the hardware buffer. You can find an
- example in the vxpocket driver.
- </para>
-
- <para>
- Another case is when the chip uses a PCI memory-map
- region for the buffer instead of the host memory. In this case,
- mmap is available only on certain architectures like the Intel one.
- In non-mmap mode, the data cannot be transferred as in the normal
- way. Thus you need to define the <structfield>copy</structfield> and
- <structfield>silence</structfield> callbacks as well,
- as in the cases above. The examples are found in
- <filename>rme32.c</filename> and <filename>rme96.c</filename>.
- </para>
-
- <para>
- The implementation of the <structfield>copy</structfield> and
- <structfield>silence</structfield> callbacks depends upon
- whether the hardware supports interleaved or non-interleaved
- samples. The <structfield>copy</structfield> callback is
- defined like below, a bit
- differently depending whether the direction is playback or
- capture:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int playback_copy(struct snd_pcm_substream *substream, int channel,
- snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count);
- static int capture_copy(struct snd_pcm_substream *substream, int channel,
- snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- In the case of interleaved samples, the second argument
- (<parameter>channel</parameter>) is not used. The third argument
- (<parameter>pos</parameter>) points the
- current position offset in frames.
- </para>
-
- <para>
- The meaning of the fourth argument is different between
- playback and capture. For playback, it holds the source data
- pointer, and for capture, it's the destination data pointer.
- </para>
-
- <para>
- The last argument is the number of frames to be copied.
- </para>
-
- <para>
- What you have to do in this callback is again different
- between playback and capture directions. In the
- playback case, you copy the given amount of data
- (<parameter>count</parameter>) at the specified pointer
- (<parameter>src</parameter>) to the specified offset
- (<parameter>pos</parameter>) on the hardware buffer. When
- coded like memcpy-like way, the copy would be like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src,
- frames_to_bytes(runtime, count));
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- For the capture direction, you copy the given amount of
- data (<parameter>count</parameter>) at the specified offset
- (<parameter>pos</parameter>) on the hardware buffer to the
- specified pointer (<parameter>dst</parameter>).
-
- <informalexample>
- <programlisting>
-<![CDATA[
- my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos),
- frames_to_bytes(runtime, count));
-]]>
- </programlisting>
- </informalexample>
-
- Note that both the position and the amount of data are given
- in frames.
- </para>
-
- <para>
- In the case of non-interleaved samples, the implementation
- will be a bit more complicated.
- </para>
-
- <para>
- You need to check the channel argument, and if it's -1, copy
- the whole channels. Otherwise, you have to copy only the
- specified channel. Please check
- <filename>isa/gus/gus_pcm.c</filename> as an example.
- </para>
-
- <para>
- The <structfield>silence</structfield> callback is also
- implemented in a similar way.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int silence(struct snd_pcm_substream *substream, int channel,
- snd_pcm_uframes_t pos, snd_pcm_uframes_t count);
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The meanings of arguments are the same as in the
- <structfield>copy</structfield>
- callback, although there is no <parameter>src/dst</parameter>
- argument. In the case of interleaved samples, the channel
- argument has no meaning, as well as on
- <structfield>copy</structfield> callback.
- </para>
-
- <para>
- The role of <structfield>silence</structfield> callback is to
- set the given amount
- (<parameter>count</parameter>) of silence data at the
- specified offset (<parameter>pos</parameter>) on the hardware
- buffer. Suppose that the data format is signed (that is, the
- silent-data is 0), and the implementation using a memset-like
- function would be like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0,
- frames_to_bytes(runtime, count));
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- In the case of non-interleaved samples, again, the
- implementation becomes a bit more complicated. See, for example,
- <filename>isa/gus/gus_pcm.c</filename>.
- </para>
- </section>
-
- <section id="buffer-and-memory-non-contiguous">
- <title>Non-Contiguous Buffers</title>
- <para>
- If your hardware supports the page table as in emu10k1 or the
- buffer descriptors as in via82xx, you can use the scatter-gather
- (SG) DMA. ALSA provides an interface for handling SG-buffers.
- The API is provided in <filename>&lt;sound/pcm.h&gt;</filename>.
- </para>
-
- <para>
- For creating the SG-buffer handler, call
- <function>snd_pcm_lib_preallocate_pages()</function> or
- <function>snd_pcm_lib_preallocate_pages_for_all()</function>
- with <constant>SNDRV_DMA_TYPE_DEV_SG</constant>
- in the PCM constructor like other PCI pre-allocator.
- You need to pass <function>snd_dma_pci_data(pci)</function>,
- where pci is the struct <structname>pci_dev</structname> pointer
- of the chip as well.
- The <type>struct snd_sg_buf</type> instance is created as
- substream-&gt;dma_private. You can cast
- the pointer like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Then call <function>snd_pcm_lib_malloc_pages()</function>
- in the <structfield>hw_params</structfield> callback
- as well as in the case of normal PCI buffer.
- The SG-buffer handler will allocate the non-contiguous kernel
- pages of the given size and map them onto the virtually contiguous
- memory. The virtual pointer is addressed in runtime-&gt;dma_area.
- The physical address (runtime-&gt;dma_addr) is set to zero,
- because the buffer is physically non-contiguous.
- The physical address table is set up in sgbuf-&gt;table.
- You can get the physical address at a certain offset via
- <function>snd_pcm_sgbuf_get_addr()</function>.
- </para>
-
- <para>
- When a SG-handler is used, you need to set
- <function>snd_pcm_sgbuf_ops_page</function> as
- the <structfield>page</structfield> callback.
- (See <link linkend="pcm-interface-operators-page-callback">
- <citetitle>page callback section</citetitle></link>.)
- </para>
-
- <para>
- To release the data, call
- <function>snd_pcm_lib_free_pages()</function> in the
- <structfield>hw_free</structfield> callback as usual.
- </para>
- </section>
-
- <section id="buffer-and-memory-vmalloced">
- <title>Vmalloc'ed Buffers</title>
- <para>
- It's possible to use a buffer allocated via
- <function>vmalloc</function>, for example, for an intermediate
- buffer. Since the allocated pages are not contiguous, you need
- to set the <structfield>page</structfield> callback to obtain
- the physical address at every offset.
- </para>
-
- <para>
- The implementation of <structfield>page</structfield> callback
- would be like this:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- #include <linux/vmalloc.h>
-
- /* get the physical page pointer on the given offset */
- static struct page *mychip_page(struct snd_pcm_substream *substream,
- unsigned long offset)
- {
- void *pageptr = substream->runtime->dma_area + offset;
- return vmalloc_to_page(pageptr);
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Proc Interface -->
-<!-- ****************************************************** -->
- <chapter id="proc-interface">
- <title>Proc Interface</title>
- <para>
- ALSA provides an easy interface for procfs. The proc files are
- very useful for debugging. I recommend you set up proc files if
- you write a driver and want to get a running status or register
- dumps. The API is found in
- <filename>&lt;sound/info.h&gt;</filename>.
- </para>
-
- <para>
- To create a proc file, call
- <function>snd_card_proc_new()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- struct snd_info_entry *entry;
- int err = snd_card_proc_new(card, "my-file", &entry);
-]]>
- </programlisting>
- </informalexample>
-
- where the second argument specifies the name of the proc file to be
- created. The above example will create a file
- <filename>my-file</filename> under the card directory,
- e.g. <filename>/proc/asound/card0/my-file</filename>.
- </para>
-
- <para>
- Like other components, the proc entry created via
- <function>snd_card_proc_new()</function> will be registered and
- released automatically in the card registration and release
- functions.
- </para>
-
- <para>
- When the creation is successful, the function stores a new
- instance in the pointer given in the third argument.
- It is initialized as a text proc file for read only. To use
- this proc file as a read-only text file as it is, set the read
- callback with a private data via
- <function>snd_info_set_text_ops()</function>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_info_set_text_ops(entry, chip, my_proc_read);
-]]>
- </programlisting>
- </informalexample>
-
- where the second argument (<parameter>chip</parameter>) is the
- private data to be used in the callbacks. The third parameter
- specifies the read buffer size and the fourth
- (<parameter>my_proc_read</parameter>) is the callback function, which
- is defined like
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void my_proc_read(struct snd_info_entry *entry,
- struct snd_info_buffer *buffer);
-]]>
- </programlisting>
- </informalexample>
-
- </para>
-
- <para>
- In the read callback, use <function>snd_iprintf()</function> for
- output strings, which works just like normal
- <function>printf()</function>. For example,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static void my_proc_read(struct snd_info_entry *entry,
- struct snd_info_buffer *buffer)
- {
- struct my_chip *chip = entry->private_data;
-
- snd_iprintf(buffer, "This is my chip!\n");
- snd_iprintf(buffer, "Port = %ld\n", chip->port);
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The file permissions can be changed afterwards. As default, it's
- set as read only for all users. If you want to add write
- permission for the user (root as default), do as follows:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
-]]>
- </programlisting>
- </informalexample>
-
- and set the write buffer size and the callback
-
- <informalexample>
- <programlisting>
-<![CDATA[
- entry->c.text.write = my_proc_write;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- For the write callback, you can use
- <function>snd_info_get_line()</function> to get a text line, and
- <function>snd_info_get_str()</function> to retrieve a string from
- the line. Some examples are found in
- <filename>core/oss/mixer_oss.c</filename>, core/oss/and
- <filename>pcm_oss.c</filename>.
- </para>
-
- <para>
- For a raw-data proc-file, set the attributes as follows:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct snd_info_entry_ops my_file_io_ops = {
- .read = my_file_io_read,
- };
-
- entry->content = SNDRV_INFO_CONTENT_DATA;
- entry->private_data = chip;
- entry->c.ops = &my_file_io_ops;
- entry->size = 4096;
- entry->mode = S_IFREG | S_IRUGO;
-]]>
- </programlisting>
- </informalexample>
-
- For the raw data, <structfield>size</structfield> field must be
- set properly. This specifies the maximum size of the proc file access.
- </para>
-
- <para>
- The read/write callbacks of raw mode are more direct than the text mode.
- You need to use a low-level I/O functions such as
- <function>copy_from/to_user()</function> to transfer the
- data.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static ssize_t my_file_io_read(struct snd_info_entry *entry,
- void *file_private_data,
- struct file *file,
- char *buf,
- size_t count,
- loff_t pos)
- {
- if (copy_to_user(buf, local_data + pos, count))
- return -EFAULT;
- return count;
- }
-]]>
- </programlisting>
- </informalexample>
-
- If the size of the info entry has been set up properly,
- <structfield>count</structfield> and <structfield>pos</structfield> are
- guaranteed to fit within 0 and the given size.
- You don't have to check the range in the callbacks unless any
- other condition is required.
-
- </para>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Power Management -->
-<!-- ****************************************************** -->
- <chapter id="power-management">
- <title>Power Management</title>
- <para>
- If the chip is supposed to work with suspend/resume
- functions, you need to add power-management code to the
- driver. The additional code for power-management should be
- <function>ifdef</function>'ed with
- <constant>CONFIG_PM</constant>.
- </para>
-
- <para>
- If the driver <emphasis>fully</emphasis> supports suspend/resume
- that is, the device can be
- properly resumed to its state when suspend was called,
- you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag
- in the pcm info field. Usually, this is possible when the
- registers of the chip can be safely saved and restored to
- RAM. If this is set, the trigger callback is called with
- <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume
- callback completes.
- </para>
-
- <para>
- Even if the driver doesn't support PM fully but
- partial suspend/resume is still possible, it's still worthy to
- implement suspend/resume callbacks. In such a case, applications
- would reset the status by calling
- <function>snd_pcm_prepare()</function> and restart the stream
- appropriately. Hence, you can define suspend/resume callbacks
- below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant>
- info flag to the PCM.
- </para>
-
- <para>
- Note that the trigger with SUSPEND can always be called when
- <function>snd_pcm_suspend_all</function> is called,
- regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag.
- The <constant>RESUME</constant> flag affects only the behavior
- of <function>snd_pcm_resume()</function>.
- (Thus, in theory,
- <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed
- to be handled in the trigger callback when no
- <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But,
- it's better to keep it for compatibility reasons.)
- </para>
- <para>
- In the earlier version of ALSA drivers, a common
- power-management layer was provided, but it has been removed.
- The driver needs to define the suspend/resume hooks according to
- the bus the device is connected to. In the case of PCI drivers, the
- callbacks look like below:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- #ifdef CONFIG_PM
- static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
- {
- .... /* do things for suspend */
- return 0;
- }
- static int snd_my_resume(struct pci_dev *pci)
- {
- .... /* do things for suspend */
- return 0;
- }
- #endif
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The scheme of the real suspend job is as follows.
-
- <orderedlist>
- <listitem><para>Retrieve the card and the chip data.</para></listitem>
- <listitem><para>Call <function>snd_power_change_state()</function> with
- <constant>SNDRV_CTL_POWER_D3hot</constant> to change the
- power status.</para></listitem>
- <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem>
- <listitem><para>If AC97 codecs are used, call
- <function>snd_ac97_suspend()</function> for each codec.</para></listitem>
- <listitem><para>Save the register values if necessary.</para></listitem>
- <listitem><para>Stop the hardware if necessary.</para></listitem>
- <listitem><para>Disable the PCI device by calling
- <function>pci_disable_device()</function>. Then, call
- <function>pci_save_state()</function> at last.</para></listitem>
- </orderedlist>
- </para>
-
- <para>
- A typical code would be like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int mychip_suspend(struct pci_dev *pci, pm_message_t state)
- {
- /* (1) */
- struct snd_card *card = pci_get_drvdata(pci);
- struct mychip *chip = card->private_data;
- /* (2) */
- snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
- /* (3) */
- snd_pcm_suspend_all(chip->pcm);
- /* (4) */
- snd_ac97_suspend(chip->ac97);
- /* (5) */
- snd_mychip_save_registers(chip);
- /* (6) */
- snd_mychip_stop_hardware(chip);
- /* (7) */
- pci_disable_device(pci);
- pci_save_state(pci);
- return 0;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- The scheme of the real resume job is as follows.
-
- <orderedlist>
- <listitem><para>Retrieve the card and the chip data.</para></listitem>
- <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>.
- Then enable the pci device again by calling <function>pci_enable_device()</function>.
- Call <function>pci_set_master()</function> if necessary, too.</para></listitem>
- <listitem><para>Re-initialize the chip.</para></listitem>
- <listitem><para>Restore the saved registers if necessary.</para></listitem>
- <listitem><para>Resume the mixer, e.g. calling
- <function>snd_ac97_resume()</function>.</para></listitem>
- <listitem><para>Restart the hardware (if any).</para></listitem>
- <listitem><para>Call <function>snd_power_change_state()</function> with
- <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem>
- </orderedlist>
- </para>
-
- <para>
- A typical code would be like:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int mychip_resume(struct pci_dev *pci)
- {
- /* (1) */
- struct snd_card *card = pci_get_drvdata(pci);
- struct mychip *chip = card->private_data;
- /* (2) */
- pci_restore_state(pci);
- pci_enable_device(pci);
- pci_set_master(pci);
- /* (3) */
- snd_mychip_reinit_chip(chip);
- /* (4) */
- snd_mychip_restore_registers(chip);
- /* (5) */
- snd_ac97_resume(chip->ac97);
- /* (6) */
- snd_mychip_restart_chip(chip);
- /* (7) */
- snd_power_change_state(card, SNDRV_CTL_POWER_D0);
- return 0;
- }
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- As shown in the above, it's better to save registers after
- suspending the PCM operations via
- <function>snd_pcm_suspend_all()</function> or
- <function>snd_pcm_suspend()</function>. It means that the PCM
- streams are already stopped when the register snapshot is
- taken. But, remember that you don't have to restart the PCM
- stream in the resume callback. It'll be restarted via
- trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>
- when necessary.
- </para>
-
- <para>
- OK, we have all callbacks now. Let's set them up. In the
- initialization of the card, make sure that you can get the chip
- data from the card instance, typically via
- <structfield>private_data</structfield> field, in case you
- created the chip data individually.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_mychip_probe(struct pci_dev *pci,
- const struct pci_device_id *pci_id)
- {
- ....
- struct snd_card *card;
- struct mychip *chip;
- int err;
- ....
- err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
- 0, &card);
- ....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
- ....
- card->private_data = chip;
- ....
- }
-]]>
- </programlisting>
- </informalexample>
-
- When you created the chip data with
- <function>snd_card_new()</function>, it's anyway accessible
- via <structfield>private_data</structfield> field.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int snd_mychip_probe(struct pci_dev *pci,
- const struct pci_device_id *pci_id)
- {
- ....
- struct snd_card *card;
- struct mychip *chip;
- int err;
- ....
- err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
- sizeof(struct mychip), &card);
- ....
- chip = card->private_data;
- ....
- }
-]]>
- </programlisting>
- </informalexample>
-
- </para>
-
- <para>
- If you need a space to save the registers, allocate the
- buffer for it here, too, since it would be fatal
- if you cannot allocate a memory in the suspend phase.
- The allocated buffer should be released in the corresponding
- destructor.
- </para>
-
- <para>
- And next, set suspend/resume callbacks to the pci_driver.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static struct pci_driver driver = {
- .name = KBUILD_MODNAME,
- .id_table = snd_my_ids,
- .probe = snd_my_probe,
- .remove = snd_my_remove,
- #ifdef CONFIG_PM
- .suspend = snd_my_suspend,
- .resume = snd_my_resume,
- #endif
- };
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Module Parameters -->
-<!-- ****************************************************** -->
- <chapter id="module-parameters">
- <title>Module Parameters</title>
- <para>
- There are standard module options for ALSA. At least, each
- module should have the <parameter>index</parameter>,
- <parameter>id</parameter> and <parameter>enable</parameter>
- options.
- </para>
-
- <para>
- If the module supports multiple cards (usually up to
- 8 = <constant>SNDRV_CARDS</constant> cards), they should be
- arrays. The default initial values are defined already as
- constants for easier programming:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
- static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
- static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- If the module supports only a single card, they could be single
- variables, instead. <parameter>enable</parameter> option is not
- always necessary in this case, but it would be better to have a
- dummy option for compatibility.
- </para>
-
- <para>
- The module parameters must be declared with the standard
- <function>module_param()()</function>,
- <function>module_param_array()()</function> and
- <function>MODULE_PARM_DESC()</function> macros.
- </para>
-
- <para>
- The typical coding would be like below:
-
- <informalexample>
- <programlisting>
-<![CDATA[
- #define CARD_NAME "My Chip"
-
- module_param_array(index, int, NULL, 0444);
- MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
- module_param_array(id, charp, NULL, 0444);
- MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
- module_param_array(enable, bool, NULL, 0444);
- MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- Also, don't forget to define the module description, classes,
- license and devices. Especially, the recent modprobe requires to
- define the module license as GPL, etc., otherwise the system is
- shown as <quote>tainted</quote>.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- MODULE_DESCRIPTION("My Chip");
- MODULE_LICENSE("GPL");
- MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}");
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- How To Put Your Driver -->
-<!-- ****************************************************** -->
- <chapter id="how-to-put-your-driver">
- <title>How To Put Your Driver Into ALSA Tree</title>
- <section>
- <title>General</title>
- <para>
- So far, you've learned how to write the driver codes.
- And you might have a question now: how to put my own
- driver into the ALSA driver tree?
- Here (finally :) the standard procedure is described briefly.
- </para>
-
- <para>
- Suppose that you create a new PCI driver for the card
- <quote>xyz</quote>. The card module name would be
- snd-xyz. The new driver is usually put into the alsa-driver
- tree, <filename>alsa-driver/pci</filename> directory in
- the case of PCI cards.
- Then the driver is evaluated, audited and tested
- by developers and users. After a certain time, the driver
- will go to the alsa-kernel tree (to the corresponding directory,
- such as <filename>alsa-kernel/pci</filename>) and eventually
- will be integrated into the Linux 2.6 tree (the directory would be
- <filename>linux/sound/pci</filename>).
- </para>
-
- <para>
- In the following sections, the driver code is supposed
- to be put into alsa-driver tree. The two cases are covered:
- a driver consisting of a single source file and one consisting
- of several source files.
- </para>
- </section>
-
- <section>
- <title>Driver with A Single Source File</title>
- <para>
- <orderedlist>
- <listitem>
- <para>
- Modify alsa-driver/pci/Makefile
- </para>
-
- <para>
- Suppose you have a file xyz.c. Add the following
- two lines
- <informalexample>
- <programlisting>
-<![CDATA[
- snd-xyz-objs := xyz.o
- obj-$(CONFIG_SND_XYZ) += snd-xyz.o
-]]>
- </programlisting>
- </informalexample>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Create the Kconfig entry
- </para>
-
- <para>
- Add the new entry of Kconfig for your xyz driver.
- <informalexample>
- <programlisting>
-<![CDATA[
- config SND_XYZ
- tristate "Foobar XYZ"
- depends on SND
- select SND_PCM
- help
- Say Y here to include support for Foobar XYZ soundcard.
-
- To compile this driver as a module, choose M here: the module
- will be called snd-xyz.
-]]>
- </programlisting>
- </informalexample>
-
- the line, select SND_PCM, specifies that the driver xyz supports
- PCM. In addition to SND_PCM, the following components are
- supported for select command:
- SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART,
- SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC.
- Add the select command for each supported component.
- </para>
-
- <para>
- Note that some selections imply the lowlevel selections.
- For example, PCM includes TIMER, MPU401_UART includes RAWMIDI,
- AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP.
- You don't need to give the lowlevel selections again.
- </para>
-
- <para>
- For the details of Kconfig script, refer to the kbuild
- documentation.
- </para>
-
- </listitem>
-
- <listitem>
- <para>
- Run cvscompile script to re-generate the configure script and
- build the whole stuff again.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <section>
- <title>Drivers with Several Source Files</title>
- <para>
- Suppose that the driver snd-xyz have several source files.
- They are located in the new subdirectory,
- pci/xyz.
-
- <orderedlist>
- <listitem>
- <para>
- Add a new directory (<filename>xyz</filename>) in
- <filename>alsa-driver/pci/Makefile</filename> as below
-
- <informalexample>
- <programlisting>
-<![CDATA[
- obj-$(CONFIG_SND) += xyz/
-]]>
- </programlisting>
- </informalexample>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Under the directory <filename>xyz</filename>, create a Makefile
-
- <example>
- <title>Sample Makefile for a driver xyz</title>
- <programlisting>
-<![CDATA[
- ifndef SND_TOPDIR
- SND_TOPDIR=../..
- endif
-
- include $(SND_TOPDIR)/toplevel.config
- include $(SND_TOPDIR)/Makefile.conf
-
- snd-xyz-objs := xyz.o abc.o def.o
-
- obj-$(CONFIG_SND_XYZ) += snd-xyz.o
-
- include $(SND_TOPDIR)/Rules.make
-]]>
- </programlisting>
- </example>
- </para>
- </listitem>
-
- <listitem>
- <para>
- Create the Kconfig entry
- </para>
-
- <para>
- This procedure is as same as in the last section.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Run cvscompile script to re-generate the configure script and
- build the whole stuff again.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- </chapter>
-
-<!-- ****************************************************** -->
-<!-- Useful Functions -->
-<!-- ****************************************************** -->
- <chapter id="useful-functions">
- <title>Useful Functions</title>
-
- <section id="useful-functions-snd-printk">
- <title><function>snd_printk()</function> and friends</title>
- <para>
- ALSA provides a verbose version of the
- <function>printk()</function> function. If a kernel config
- <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this
- function prints the given message together with the file name
- and the line of the caller. The <constant>KERN_XXX</constant>
- prefix is processed as
- well as the original <function>printk()</function> does, so it's
- recommended to add this prefix, e.g.
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n");
-]]>
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- There are also <function>printk()</function>'s for
- debugging. <function>snd_printd()</function> can be used for
- general debugging purposes. If
- <constant>CONFIG_SND_DEBUG</constant> is set, this function is
- compiled, and works just like
- <function>snd_printk()</function>. If the ALSA is compiled
- without the debugging flag, it's ignored.
- </para>
-
- <para>
- <function>snd_printdd()</function> is compiled in only when
- <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note
- that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default
- even if you configure the alsa-driver with
- <option>--with-debug=full</option> option. You need to give
- explicitly <option>--with-debug=detect</option> option instead.
- </para>
- </section>
-
- <section id="useful-functions-snd-bug">
- <title><function>snd_BUG()</function></title>
- <para>
- It shows the <computeroutput>BUG?</computeroutput> message and
- stack trace as well as <function>snd_BUG_ON</function> at the point.
- It's useful to show that a fatal error happens there.
- </para>
- <para>
- When no debug flag is set, this macro is ignored.
- </para>
- </section>
-
- <section id="useful-functions-snd-bug-on">
- <title><function>snd_BUG_ON()</function></title>
- <para>
- <function>snd_BUG_ON()</function> macro is similar with
- <function>WARN_ON()</function> macro. For example,
-
- <informalexample>
- <programlisting>
-<![CDATA[
- snd_BUG_ON(!pointer);
-]]>
- </programlisting>
- </informalexample>
-
- or it can be used as the condition,
- <informalexample>
- <programlisting>
-<![CDATA[
- if (snd_BUG_ON(non_zero_is_bug))
- return -EINVAL;
-]]>
- </programlisting>
- </informalexample>
-
- </para>
-
- <para>
- The macro takes an conditional expression to evaluate.
- When <constant>CONFIG_SND_DEBUG</constant>, is set, if the
- expression is non-zero, it shows the warning message such as
- <computeroutput>BUG? (xxx)</computeroutput>
- normally followed by stack trace.
-
- In both cases it returns the evaluated value.
- </para>
-
- </section>
-
- </chapter>
-
-
-<!-- ****************************************************** -->
-<!-- Acknowledgments -->
-<!-- ****************************************************** -->
- <chapter id="acknowledgments">
- <title>Acknowledgments</title>
- <para>
- I would like to thank Phil Kerr for his help for improvement and
- corrections of this document.
- </para>
- <para>
- Kevin Conder reformatted the original plain-text to the
- DocBook format.
- </para>
- <para>
- Giuliano Pochini corrected typos and contributed the example codes
- in the hardware constraints section.
- </para>
- </chapter>
-</book>
diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl
deleted file mode 100644
index 837eca77f274..000000000000
--- a/Documentation/DocBook/writing_musb_glue_layer.tmpl
+++ /dev/null
@@ -1,873 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Writing-MUSB-Glue-Layer">
- <bookinfo>
- <title>Writing an MUSB Glue Layer</title>
-
- <authorgroup>
- <author>
- <firstname>Apelete</firstname>
- <surname>Seketeli</surname>
- <affiliation>
- <address>
- <email>apelete at seketeli.net</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2014</year>
- <holder>Apelete Seketeli</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute it
- and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later version.
- </para>
-
- <para>
- This documentation is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public License
- along with this documentation; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the Linux kernel source
- tree.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="introduction">
- <title>Introduction</title>
- <para>
- The Linux MUSB subsystem is part of the larger Linux USB
- subsystem. It provides support for embedded USB Device Controllers
- (UDC) that do not use Universal Host Controller Interface (UHCI)
- or Open Host Controller Interface (OHCI).
- </para>
- <para>
- Instead, these embedded UDC rely on the USB On-the-Go (OTG)
- specification which they implement at least partially. The silicon
- reference design used in most cases is the Multipoint USB
- Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor
- Graphics Inventra™ design.
- </para>
- <para>
- As a self-taught exercise I have written an MUSB glue layer for
- the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers
- in the kernel source tree. This layer can be found at
- drivers/usb/musb/jz4740.c. In this documentation I will walk
- through the basics of the jz4740.c glue layer, explaining the
- different pieces and what needs to be done in order to write your
- own device glue layer.
- </para>
- </chapter>
-
- <chapter id="linux-musb-basics">
- <title>Linux MUSB Basics</title>
- <para>
- To get started on the topic, please read USB On-the-Go Basics (see
- Resources) which provides an introduction of USB OTG operation at
- the hardware level. A couple of wiki pages by Texas Instruments
- and Analog Devices also provide an overview of the Linux kernel
- MUSB configuration, albeit focused on some specific devices
- provided by these companies. Finally, getting acquainted with the
- USB specification at USB home page may come in handy, with
- practical instance provided through the Writing USB Device Drivers
- documentation (again, see Resources).
- </para>
- <para>
- Linux USB stack is a layered architecture in which the MUSB
- controller hardware sits at the lowest. The MUSB controller driver
- abstract the MUSB controller hardware to the Linux USB stack.
- </para>
- <programlisting>
- ------------------------
- | | &lt;------- drivers/usb/gadget
- | Linux USB Core Stack | &lt;------- drivers/usb/host
- | | &lt;------- drivers/usb/core
- ------------------------
- ⬍
- --------------------------
- | | &lt;------ drivers/usb/musb/musb_gadget.c
- | MUSB Controller driver | &lt;------ drivers/usb/musb/musb_host.c
- | | &lt;------ drivers/usb/musb/musb_core.c
- --------------------------
- ⬍
- ---------------------------------
- | MUSB Platform Specific Driver |
- | | &lt;-- drivers/usb/musb/jz4740.c
- | aka &quot;Glue Layer&quot; |
- ---------------------------------
- ⬍
- ---------------------------------
- | MUSB Controller Hardware |
- ---------------------------------
- </programlisting>
- <para>
- As outlined above, the glue layer is actually the platform
- specific code sitting in between the controller driver and the
- controller hardware.
- </para>
- <para>
- Just like a Linux USB driver needs to register itself with the
- Linux USB subsystem, the MUSB glue layer needs first to register
- itself with the MUSB controller driver. This will allow the
- controller driver to know about which device the glue layer
- supports and which functions to call when a supported device is
- detected or released; remember we are talking about an embedded
- controller chip here, so no insertion or removal at run-time.
- </para>
- <para>
- All of this information is passed to the MUSB controller driver
- through a platform_driver structure defined in the glue layer as:
- </para>
- <programlisting linenumbering="numbered">
-static struct platform_driver jz4740_driver = {
- .probe = jz4740_probe,
- .remove = jz4740_remove,
- .driver = {
- .name = "musb-jz4740",
- },
-};
- </programlisting>
- <para>
- The probe and remove function pointers are called when a matching
- device is detected and, respectively, released. The name string
- describes the device supported by this glue layer. In the current
- case it matches a platform_device structure declared in
- arch/mips/jz4740/platform.c. Note that we are not using device
- tree bindings here.
- </para>
- <para>
- In order to register itself to the controller driver, the glue
- layer goes through a few steps, basically allocating the
- controller hardware resources and initialising a couple of
- circuits. To do so, it needs to keep track of the information used
- throughout these steps. This is done by defining a private
- jz4740_glue structure:
- </para>
- <programlisting linenumbering="numbered">
-struct jz4740_glue {
- struct device *dev;
- struct platform_device *musb;
- struct clk *clk;
-};
- </programlisting>
- <para>
- The dev and musb members are both device structure variables. The
- first one holds generic information about the device, since it's
- the basic device structure, and the latter holds information more
- closely related to the subsystem the device is registered to. The
- clk variable keeps information related to the device clock
- operation.
- </para>
- <para>
- Let's go through the steps of the probe function that leads the
- glue layer to register itself to the controller driver.
- </para>
- <para>
- N.B.: For the sake of readability each function will be split in
- logical parts, each part being shown as if it was independent from
- the others.
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
- struct platform_device *musb;
- struct jz4740_glue *glue;
- struct clk *clk;
- int ret;
-
- glue = devm_kzalloc(&amp;pdev->dev, sizeof(*glue), GFP_KERNEL);
- if (!glue)
- return -ENOMEM;
-
- musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
- if (!musb) {
- dev_err(&amp;pdev->dev, "failed to allocate musb device\n");
- return -ENOMEM;
- }
-
- clk = devm_clk_get(&amp;pdev->dev, "udc");
- if (IS_ERR(clk)) {
- dev_err(&amp;pdev->dev, "failed to get clock\n");
- ret = PTR_ERR(clk);
- goto err_platform_device_put;
- }
-
- ret = clk_prepare_enable(clk);
- if (ret) {
- dev_err(&amp;pdev->dev, "failed to enable clock\n");
- goto err_platform_device_put;
- }
-
- musb->dev.parent = &amp;pdev->dev;
-
- glue->dev = &amp;pdev->dev;
- glue->musb = musb;
- glue->clk = clk;
-
- return 0;
-
-err_platform_device_put:
- platform_device_put(musb);
- return ret;
-}
- </programlisting>
- <para>
- The first few lines of the probe function allocate and assign the
- glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows
- the allocation process to sleep and wait for memory, thus being
- usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line
- 12) allows automatic allocation and management of device IDs in
- order to avoid device namespace collisions with explicit IDs. With
- devm_clk_get() (line 18) the glue layer allocates the clock -- the
- <literal>devm_</literal> prefix indicates that clk_get() is
- managed: it automatically frees the allocated clock resource data
- when the device is released -- and enable it.
- </para>
- <para>
- Then comes the registration steps:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
- struct musb_hdrc_platform_data *pdata = &amp;jz4740_musb_platform_data;
-
- pdata->platform_ops = &amp;jz4740_musb_ops;
-
- platform_set_drvdata(pdev, glue);
-
- ret = platform_device_add_resources(musb, pdev->resource,
- pdev->num_resources);
- if (ret) {
- dev_err(&amp;pdev->dev, "failed to add resources\n");
- goto err_clk_disable;
- }
-
- ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
- if (ret) {
- dev_err(&amp;pdev->dev, "failed to add platform_data\n");
- goto err_clk_disable;
- }
-
- return 0;
-
-err_clk_disable:
- clk_disable_unprepare(clk);
-err_platform_device_put:
- platform_device_put(musb);
- return ret;
-}
- </programlisting>
- <para>
- The first step is to pass the device data privately held by the
- glue layer on to the controller driver through
- platform_set_drvdata() (line 7). Next is passing on the device
- resources information, also privately held at that point, through
- platform_device_add_resources() (line 9).
- </para>
- <para>
- Finally comes passing on the platform specific data to the
- controller driver (line 16). Platform data will be discussed in
- <link linkend="device-platform-data">Chapter 4</link>, but here
- we are looking at the platform_ops function pointer (line 5) in
- musb_hdrc_platform_data structure (line 3). This function
- pointer allows the MUSB controller driver to know which function
- to call for device operation:
- </para>
- <programlisting linenumbering="numbered">
-static const struct musb_platform_ops jz4740_musb_ops = {
- .init = jz4740_musb_init,
- .exit = jz4740_musb_exit,
-};
- </programlisting>
- <para>
- Here we have the minimal case where only init and exit functions
- are called by the controller driver when needed. Fact is the
- JZ4740 MUSB controller is a basic controller, lacking some
- features found in other controllers, otherwise we may also have
- pointers to a few other functions like a power management function
- or a function to switch between OTG and non-OTG modes, for
- instance.
- </para>
- <para>
- At that point of the registration process, the controller driver
- actually calls the init function:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
- musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
- if (!musb->xceiv) {
- pr_err("HS UDC: no transceiver configured\n");
- return -ENODEV;
- }
-
- /* Silicon does not implement ConfigData register.
- * Set dyn_fifo to avoid reading EP config from hardware.
- */
- musb->dyn_fifo = true;
-
- musb->isr = jz4740_musb_interrupt;
-
- return 0;
-}
- </programlisting>
- <para>
- The goal of jz4740_musb_init() is to get hold of the transceiver
- driver data of the MUSB controller hardware and pass it on to the
- MUSB controller driver, as usual. The transceiver is the circuitry
- inside the controller hardware responsible for sending/receiving
- the USB data. Since it is an implementation of the physical layer
- of the OSI model, the transceiver is also referred to as PHY.
- </para>
- <para>
- Getting hold of the MUSB PHY driver data is done with
- usb_get_phy() which returns a pointer to the structure
- containing the driver instance data. The next couple of
- instructions (line 12 and 14) are used as a quirk and to setup
- IRQ handling respectively. Quirks and IRQ handling will be
- discussed later in <link linkend="device-quirks">Chapter
- 5</link> and <link linkend="handling-irqs">Chapter 3</link>.
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_exit(struct musb *musb)
-{
- usb_put_phy(musb->xceiv);
-
- return 0;
-}
- </programlisting>
- <para>
- Acting as the counterpart of init, the exit function releases the
- MUSB PHY driver when the controller hardware itself is about to be
- released.
- </para>
- <para>
- Again, note that init and exit are fairly simple in this case due
- to the basic set of features of the JZ4740 controller hardware.
- When writing an musb glue layer for a more complex controller
- hardware, you might need to take care of more processing in those
- two functions.
- </para>
- <para>
- Returning from the init function, the MUSB controller driver jumps
- back into the probe function:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
- ret = platform_device_add(musb);
- if (ret) {
- dev_err(&amp;pdev->dev, "failed to register musb device\n");
- goto err_clk_disable;
- }
-
- return 0;
-
-err_clk_disable:
- clk_disable_unprepare(clk);
-err_platform_device_put:
- platform_device_put(musb);
- return ret;
-}
- </programlisting>
- <para>
- This is the last part of the device registration process where the
- glue layer adds the controller hardware device to Linux kernel
- device hierarchy: at this stage, all known information about the
- device is passed on to the Linux USB core stack.
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_remove(struct platform_device *pdev)
-{
- struct jz4740_glue *glue = platform_get_drvdata(pdev);
-
- platform_device_unregister(glue->musb);
- clk_disable_unprepare(glue->clk);
-
- return 0;
-}
- </programlisting>
- <para>
- Acting as the counterpart of probe, the remove function unregister
- the MUSB controller hardware (line 5) and disable the clock (line
- 6), allowing it to be gated.
- </para>
- </chapter>
-
- <chapter id="handling-irqs">
- <title>Handling IRQs</title>
- <para>
- Additionally to the MUSB controller hardware basic setup and
- registration, the glue layer is also responsible for handling the
- IRQs:
- </para>
- <programlisting linenumbering="numbered">
-static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
-{
- unsigned long flags;
- irqreturn_t retval = IRQ_NONE;
- struct musb *musb = __hci;
-
- spin_lock_irqsave(&amp;musb->lock, flags);
-
- musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
- musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
- musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
-
- /*
- * The controller is gadget only, the state of the host mode IRQ bits is
- * undefined. Mask them to make sure that the musb driver core will
- * never see them set
- */
- musb->int_usb &amp;= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
- MUSB_INTR_RESET | MUSB_INTR_SOF;
-
- if (musb->int_usb || musb->int_tx || musb->int_rx)
- retval = musb_interrupt(musb);
-
- spin_unlock_irqrestore(&amp;musb->lock, flags);
-
- return retval;
-}
- </programlisting>
- <para>
- Here the glue layer mostly has to read the relevant hardware
- registers and pass their values on to the controller driver which
- will handle the actual event that triggered the IRQ.
- </para>
- <para>
- The interrupt handler critical section is protected by the
- spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
- functions (line 7 and 24 respectively), which prevent the
- interrupt handler code to be run by two different threads at the
- same time.
- </para>
- <para>
- Then the relevant interrupt registers are read (line 9 to 11):
- </para>
- <itemizedlist>
- <listitem>
- <para>
- MUSB_INTRUSB: indicates which USB interrupts are currently
- active,
- </para>
- </listitem>
- <listitem>
- <para>
- MUSB_INTRTX: indicates which of the interrupts for TX
- endpoints are currently active,
- </para>
- </listitem>
- <listitem>
- <para>
- MUSB_INTRRX: indicates which of the interrupts for TX
- endpoints are currently active.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Note that musb_readb() is used to read 8-bit registers at most,
- while musb_readw() allows us to read at most 16-bit registers.
- There are other functions that can be used depending on the size
- of your device registers. See musb_io.h for more information.
- </para>
- <para>
- Instruction on line 18 is another quirk specific to the JZ4740
- USB device controller, which will be discussed later in <link
- linkend="device-quirks">Chapter 5</link>.
- </para>
- <para>
- The glue layer still needs to register the IRQ handler though.
- Remember the instruction on line 14 of the init function:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
- musb->isr = jz4740_musb_interrupt;
-
- return 0;
-}
- </programlisting>
- <para>
- This instruction sets a pointer to the glue layer IRQ handler
- function, in order for the controller hardware to call the handler
- back when an IRQ comes from the controller hardware. The interrupt
- handler is now implemented and registered.
- </para>
- </chapter>
-
- <chapter id="device-platform-data">
- <title>Device Platform Data</title>
- <para>
- In order to write an MUSB glue layer, you need to have some data
- describing the hardware capabilities of your controller hardware,
- which is called the platform data.
- </para>
- <para>
- Platform data is specific to your hardware, though it may cover a
- broad range of devices, and is generally found somewhere in the
- arch/ directory, depending on your device architecture.
- </para>
- <para>
- For instance, platform data for the JZ4740 SoC is found in
- arch/mips/jz4740/platform.c. In the platform.c file each device of
- the JZ4740 SoC is described through a set of structures.
- </para>
- <para>
- Here is the part of arch/mips/jz4740/platform.c that covers the
- USB Device Controller (UDC):
- </para>
- <programlisting linenumbering="numbered">
-/* USB Device Controller */
-struct platform_device jz4740_udc_xceiv_device = {
- .name = "usb_phy_gen_xceiv",
- .id = 0,
-};
-
-static struct resource jz4740_udc_resources[] = {
- [0] = {
- .start = JZ4740_UDC_BASE_ADDR,
- .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
- .flags = IORESOURCE_MEM,
- },
- [1] = {
- .start = JZ4740_IRQ_UDC,
- .end = JZ4740_IRQ_UDC,
- .flags = IORESOURCE_IRQ,
- .name = "mc",
- },
-};
-
-struct platform_device jz4740_udc_device = {
- .name = "musb-jz4740",
- .id = -1,
- .dev = {
- .dma_mask = &amp;jz4740_udc_device.dev.coherent_dma_mask,
- .coherent_dma_mask = DMA_BIT_MASK(32),
- },
- .num_resources = ARRAY_SIZE(jz4740_udc_resources),
- .resource = jz4740_udc_resources,
-};
- </programlisting>
- <para>
- The jz4740_udc_xceiv_device platform device structure (line 2)
- describes the UDC transceiver with a name and id number.
- </para>
- <para>
- At the time of this writing, note that
- &quot;usb_phy_gen_xceiv&quot; is the specific name to be used for
- all transceivers that are either built-in with reference USB IP or
- autonomous and doesn't require any PHY programming. You will need
- to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make
- use of the corresponding transceiver driver. The id field could be
- set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to
- PLATFORM_DEVID_AUTO) or start with 0 for the first device of this
- kind if we want a specific id number.
- </para>
- <para>
- The jz4740_udc_resources resource structure (line 7) defines the
- UDC registers base addresses.
- </para>
- <para>
- The first array (line 9 to 11) defines the UDC registers base
- memory addresses: start points to the first register memory
- address, end points to the last register memory address and the
- flags member defines the type of resource we are dealing with. So
- IORESOURCE_MEM is used to define the registers memory addresses.
- The second array (line 14 to 17) defines the UDC IRQ registers
- addresses. Since there is only one IRQ register available for the
- JZ4740 UDC, start and end point at the same address. The
- IORESOURCE_IRQ flag tells that we are dealing with IRQ resources,
- and the name &quot;mc&quot; is in fact hard-coded in the MUSB core
- in order for the controller driver to retrieve this IRQ resource
- by querying it by its name.
- </para>
- <para>
- Finally, the jz4740_udc_device platform device structure (line 21)
- describes the UDC itself.
- </para>
- <para>
- The &quot;musb-jz4740&quot; name (line 22) defines the MUSB
- driver that is used for this device; remember this is in fact
- the name that we used in the jz4740_driver platform driver
- structure in <link linkend="linux-musb-basics">Chapter
- 2</link>. The id field (line 23) is set to -1 (equivalent to
- PLATFORM_DEVID_NONE) since we do not need an id for the device:
- the MUSB controller driver was already set to allocate an
- automatic id in <link linkend="linux-musb-basics">Chapter
- 2</link>. In the dev field we care for DMA related information
- here. The dma_mask field (line 25) defines the width of the DMA
- mask that is going to be used, and coherent_dma_mask (line 26)
- has the same purpose but for the alloc_coherent DMA mappings: in
- both cases we are using a 32 bits mask. Then the resource field
- (line 29) is simply a pointer to the resource structure defined
- before, while the num_resources field (line 28) keeps track of
- the number of arrays defined in the resource structure (in this
- case there were two resource arrays defined before).
- </para>
- <para>
- With this quick overview of the UDC platform data at the arch/
- level now done, let's get back to the MUSB glue layer specific
- platform data in drivers/usb/musb/jz4740.c:
- </para>
- <programlisting linenumbering="numbered">
-static struct musb_hdrc_config jz4740_musb_config = {
- /* Silicon does not implement USB OTG. */
- .multipoint = 0,
- /* Max EPs scanned, driver will decide which EP can be used. */
- .num_eps = 4,
- /* RAMbits needed to configure EPs from table */
- .ram_bits = 9,
- .fifo_cfg = jz4740_musb_fifo_cfg,
- .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
-};
-
-static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
- .mode = MUSB_PERIPHERAL,
- .config = &amp;jz4740_musb_config,
-};
- </programlisting>
- <para>
- First the glue layer configures some aspects of the controller
- driver operation related to the controller hardware specifics.
- This is done through the jz4740_musb_config musb_hdrc_config
- structure.
- </para>
- <para>
- Defining the OTG capability of the controller hardware, the
- multipoint member (line 3) is set to 0 (equivalent to false)
- since the JZ4740 UDC is not OTG compatible. Then num_eps (line
- 5) defines the number of USB endpoints of the controller
- hardware, including endpoint 0: here we have 3 endpoints +
- endpoint 0. Next is ram_bits (line 7) which is the width of the
- RAM address bus for the MUSB controller hardware. This
- information is needed when the controller driver cannot
- automatically configure endpoints by reading the relevant
- controller hardware registers. This issue will be discussed when
- we get to device quirks in <link linkend="device-quirks">Chapter
- 5</link>. Last two fields (line 8 and 9) are also about device
- quirks: fifo_cfg points to the USB endpoints configuration table
- and fifo_cfg_size keeps track of the size of the number of
- entries in that configuration table. More on that later in <link
- linkend="device-quirks">Chapter 5</link>.
- </para>
- <para>
- Then this configuration is embedded inside
- jz4740_musb_platform_data musb_hdrc_platform_data structure (line
- 11): config is a pointer to the configuration structure itself,
- and mode tells the controller driver if the controller hardware
- may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG
- which is a dual mode.
- </para>
- <para>
- Remember that jz4740_musb_platform_data is then used to convey
- platform data information as we have seen in the probe function
- in <link linkend="linux-musb-basics">Chapter 2</link>
- </para>
- </chapter>
-
- <chapter id="device-quirks">
- <title>Device Quirks</title>
- <para>
- Completing the platform data specific to your device, you may also
- need to write some code in the glue layer to work around some
- device specific limitations. These quirks may be due to some
- hardware bugs, or simply be the result of an incomplete
- implementation of the USB On-the-Go specification.
- </para>
- <para>
- The JZ4740 UDC exhibits such quirks, some of which we will discuss
- here for the sake of insight even though these might not be found
- in the controller hardware you are working on.
- </para>
- <para>
- Let's get back to the init function first:
- </para>
- <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
- musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
- if (!musb->xceiv) {
- pr_err("HS UDC: no transceiver configured\n");
- return -ENODEV;
- }
-
- /* Silicon does not implement ConfigData register.
- * Set dyn_fifo to avoid reading EP config from hardware.
- */
- musb->dyn_fifo = true;
-
- musb->isr = jz4740_musb_interrupt;
-
- return 0;
-}
- </programlisting>
- <para>
- Instruction on line 12 helps the MUSB controller driver to work
- around the fact that the controller hardware is missing registers
- that are used for USB endpoints configuration.
- </para>
- <para>
- Without these registers, the controller driver is unable to read
- the endpoints configuration from the hardware, so we use line 12
- instruction to bypass reading the configuration from silicon, and
- rely on a hard-coded table that describes the endpoints
- configuration instead:
- </para>
- <programlisting linenumbering="numbered">
-static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
-{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
-{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
-{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
-};
- </programlisting>
- <para>
- Looking at the configuration table above, we see that each
- endpoints is described by three fields: hw_ep_num is the endpoint
- number, style is its direction (either FIFO_TX for the controller
- driver to send packets in the controller hardware, or FIFO_RX to
- receive packets from hardware), and maxpacket defines the maximum
- size of each data packet that can be transmitted over that
- endpoint. Reading from the table, the controller driver knows that
- endpoint 1 can be used to send and receive USB data packets of 512
- bytes at once (this is in fact a bulk in/out endpoint), and
- endpoint 2 can be used to send data packets of 64 bytes at once
- (this is in fact an interrupt endpoint).
- </para>
- <para>
- Note that there is no information about endpoint 0 here: that one
- is implemented by default in every silicon design, with a
- predefined configuration according to the USB specification. For
- more examples of endpoint configuration tables, see musb_core.c.
- </para>
- <para>
- Let's now get back to the interrupt handler function:
- </para>
- <programlisting linenumbering="numbered">
-static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
-{
- unsigned long flags;
- irqreturn_t retval = IRQ_NONE;
- struct musb *musb = __hci;
-
- spin_lock_irqsave(&amp;musb->lock, flags);
-
- musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
- musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
- musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
-
- /*
- * The controller is gadget only, the state of the host mode IRQ bits is
- * undefined. Mask them to make sure that the musb driver core will
- * never see them set
- */
- musb->int_usb &amp;= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
- MUSB_INTR_RESET | MUSB_INTR_SOF;
-
- if (musb->int_usb || musb->int_tx || musb->int_rx)
- retval = musb_interrupt(musb);
-
- spin_unlock_irqrestore(&amp;musb->lock, flags);
-
- return retval;
-}
- </programlisting>
- <para>
- Instruction on line 18 above is a way for the controller driver to
- work around the fact that some interrupt bits used for USB host
- mode operation are missing in the MUSB_INTRUSB register, thus left
- in an undefined hardware state, since this MUSB controller
- hardware is used in peripheral mode only. As a consequence, the
- glue layer masks these missing bits out to avoid parasite
- interrupts by doing a logical AND operation between the value read
- from MUSB_INTRUSB and the bits that are actually implemented in
- the register.
- </para>
- <para>
- These are only a couple of the quirks found in the JZ4740 USB
- device controller. Some others were directly addressed in the MUSB
- core since the fixes were generic enough to provide a better
- handling of the issues for others controller hardware eventually.
- </para>
- </chapter>
-
- <chapter id="conclusion">
- <title>Conclusion</title>
- <para>
- Writing a Linux MUSB glue layer should be a more accessible task,
- as this documentation tries to show the ins and outs of this
- exercise.
- </para>
- <para>
- The JZ4740 USB device controller being fairly simple, I hope its
- glue layer serves as a good example for the curious mind. Used
- with the current MUSB glue layers, this documentation should
- provide enough guidance to get started; should anything gets out
- of hand, the linux-usb mailing list archive is another helpful
- resource to browse through.
- </para>
- </chapter>
-
- <chapter id="acknowledgements">
- <title>Acknowledgements</title>
- <para>
- Many thanks to Lars-Peter Clausen and Maarten ter Huurne for
- answering my questions while I was writing the JZ4740 glue layer
- and for helping me out getting the code in good shape.
- </para>
- <para>
- I would also like to thank the Qi-Hardware community at large for
- its cheerful guidance and support.
- </para>
- </chapter>
-
- <chapter id="resources">
- <title>Resources</title>
- <para>
- USB Home Page:
- <ulink url="http://www.usb.org">http://www.usb.org</ulink>
- </para>
- <para>
- linux-usb Mailing List Archives:
- <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink>
- </para>
- <para>
- USB On-the-Go Basics:
- <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink>
- </para>
- <para>
- Writing USB Device Drivers:
- <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink>
- </para>
- <para>
- Texas Instruments USB Configuration Wiki Page:
- <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink>
- </para>
- <para>
- Analog Devices Blackfin MUSB Configuration:
- <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink>
- </para>
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl
deleted file mode 100644
index 3210dcf741c9..000000000000
--- a/Documentation/DocBook/writing_usb_driver.tmpl
+++ /dev/null
@@ -1,412 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="USBDeviceDriver">
- <bookinfo>
- <title>Writing USB Device Drivers</title>
-
- <authorgroup>
- <author>
- <firstname>Greg</firstname>
- <surname>Kroah-Hartman</surname>
- <affiliation>
- <address>
- <email>greg@kroah.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2001-2002</year>
- <holder>Greg Kroah-Hartman</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
-
- <para>
- This documentation is based on an article published in
- Linux Journal Magazine, October 2001, Issue 90.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The Linux USB subsystem has grown from supporting only two different
- types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
- different types of devices in the 2.4 kernel. Linux currently supports
- almost all USB class devices (standard types of devices like keyboards,
- mice, modems, printers and speakers) and an ever-growing number of
- vendor-specific devices (such as USB to serial converters, digital
- cameras, Ethernet devices and MP3 players). For a full list of the
- different USB devices currently supported, see Resources.
- </para>
- <para>
- The remaining kinds of USB devices that do not have support on Linux are
- almost all vendor-specific devices. Each vendor decides to implement a
- custom protocol to talk to their device, so a custom driver usually needs
- to be created. Some vendors are open with their USB protocols and help
- with the creation of Linux drivers, while others do not publish them, and
- developers are forced to reverse-engineer. See Resources for some links
- to handy reverse-engineering tools.
- </para>
- <para>
- Because each different protocol causes a new driver to be created, I have
- written a generic USB driver skeleton, modelled after the pci-skeleton.c
- file in the kernel source tree upon which many PCI network drivers have
- been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c
- in the kernel source tree. In this article I will walk through the basics
- of the skeleton driver, explaining the different pieces and what needs to
- be done to customize it to your specific device.
- </para>
- </chapter>
-
- <chapter id="basics">
- <title>Linux USB Basics</title>
- <para>
- If you are going to write a Linux USB driver, please become familiar with
- the USB protocol specification. It can be found, along with many other
- useful documents, at the USB home page (see Resources). An excellent
- introduction to the Linux USB subsystem can be found at the USB Working
- Devices List (see Resources). It explains how the Linux USB subsystem is
- structured and introduces the reader to the concept of USB urbs
- (USB Request Blocks), which are essential to USB drivers.
- </para>
- <para>
- The first thing a Linux USB driver needs to do is register itself with
- the Linux USB subsystem, giving it some information about which devices
- the driver supports and which functions to call when a device supported
- by the driver is inserted or removed from the system. All of this
- information is passed to the USB subsystem in the usb_driver structure.
- The skeleton driver declares a usb_driver as:
- </para>
- <programlisting>
-static struct usb_driver skel_driver = {
- .name = "skeleton",
- .probe = skel_probe,
- .disconnect = skel_disconnect,
- .fops = &amp;skel_fops,
- .minor = USB_SKEL_MINOR_BASE,
- .id_table = skel_table,
-};
- </programlisting>
- <para>
- The variable name is a string that describes the driver. It is used in
- informational messages printed to the system log. The probe and
- disconnect function pointers are called when a device that matches the
- information provided in the id_table variable is either seen or removed.
- </para>
- <para>
- The fops and minor variables are optional. Most USB drivers hook into
- another kernel subsystem, such as the SCSI, network or TTY subsystem.
- These types of drivers register themselves with the other kernel
- subsystem, and any user-space interactions are provided through that
- interface. But for drivers that do not have a matching kernel subsystem,
- such as MP3 players or scanners, a method of interacting with user space
- is needed. The USB subsystem provides a way to register a minor device
- number and a set of file_operations function pointers that enable this
- user-space interaction. The skeleton driver needs this kind of interface,
- so it provides a minor starting number and a pointer to its
- file_operations functions.
- </para>
- <para>
- The USB driver is then registered with a call to usb_register, usually in
- the driver's init function, as shown here:
- </para>
- <programlisting>
-static int __init usb_skel_init(void)
-{
- int result;
-
- /* register this driver with the USB subsystem */
- result = usb_register(&amp;skel_driver);
- if (result &lt; 0) {
- err(&quot;usb_register failed for the &quot;__FILE__ &quot;driver.&quot;
- &quot;Error number %d&quot;, result);
- return -1;
- }
-
- return 0;
-}
-module_init(usb_skel_init);
- </programlisting>
- <para>
- When the driver is unloaded from the system, it needs to deregister
- itself with the USB subsystem. This is done with the usb_deregister
- function:
- </para>
- <programlisting>
-static void __exit usb_skel_exit(void)
-{
- /* deregister this driver with the USB subsystem */
- usb_deregister(&amp;skel_driver);
-}
-module_exit(usb_skel_exit);
- </programlisting>
- <para>
- To enable the linux-hotplug system to load the driver automatically when
- the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The
- following code tells the hotplug scripts that this module supports a
- single device with a specific vendor and product ID:
- </para>
- <programlisting>
-/* table of devices that work with this driver */
-static struct usb_device_id skel_table [] = {
- { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
- { } /* Terminating entry */
-};
-MODULE_DEVICE_TABLE (usb, skel_table);
- </programlisting>
- <para>
- There are other macros that can be used in describing a usb_device_id for
- drivers that support a whole class of USB drivers. See usb.h for more
- information on this.
- </para>
- </chapter>
-
- <chapter id="device">
- <title>Device operation</title>
- <para>
- When a device is plugged into the USB bus that matches the device ID
- pattern that your driver registered with the USB core, the probe function
- is called. The usb_device structure, interface number and the interface ID
- are passed to the function:
- </para>
- <programlisting>
-static int skel_probe(struct usb_interface *interface,
- const struct usb_device_id *id)
- </programlisting>
- <para>
- The driver now needs to verify that this device is actually one that it
- can accept. If so, it returns 0.
- If not, or if any error occurs during initialization, an errorcode
- (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>)
- is returned from the probe function.
- </para>
- <para>
- In the skeleton driver, we determine what end points are marked as bulk-in
- and bulk-out. We create buffers to hold the data that will be sent and
- received from the device, and a USB urb to write data to the device is
- initialized.
- </para>
- <para>
- Conversely, when the device is removed from the USB bus, the disconnect
- function is called with the device pointer. The driver needs to clean any
- private data that has been allocated at this time and to shut down any
- pending urbs that are in the USB system.
- </para>
- <para>
- Now that the device is plugged into the system and the driver is bound to
- the device, any of the functions in the file_operations structure that
- were passed to the USB subsystem will be called from a user program trying
- to talk to the device. The first function called will be open, as the
- program tries to open the device for I/O. We increment our private usage
- count and save a pointer to our internal structure in the file
- structure. This is done so that future calls to file operations will
- enable the driver to determine which device the user is addressing. All
- of this is done with the following code:
- </para>
- <programlisting>
-/* increment our usage count for the module */
-++skel->open_count;
-
-/* save our object in the file's private structure */
-file->private_data = dev;
- </programlisting>
- <para>
- After the open function is called, the read and write functions are called
- to receive and send data to the device. In the skel_write function, we
- receive a pointer to some data that the user wants to send to the device
- and the size of the data. The function determines how much data it can
- send to the device based on the size of the write urb it has created (this
- size depends on the size of the bulk out end point that the device has).
- Then it copies the data from user space to kernel space, points the urb to
- the data and submits the urb to the USB subsystem. This can be seen in
- the following code:
- </para>
- <programlisting>
-/* we can only write as much as 1 urb will hold */
-bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
-
-/* copy the data from user space into our urb */
-copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
-
-/* set up our urb */
-usb_fill_bulk_urb(skel->write_urb,
- skel->dev,
- usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
- skel->write_urb->transfer_buffer,
- bytes_written,
- skel_write_bulk_callback,
- skel);
-
-/* send the data out the bulk port */
-result = usb_submit_urb(skel->write_urb);
-if (result) {
- err(&quot;Failed submitting write urb, error %d&quot;, result);
-}
- </programlisting>
- <para>
- When the write urb is filled up with the proper information using the
- usb_fill_bulk_urb function, we point the urb's completion callback to call our
- own skel_write_bulk_callback function. This function is called when the
- urb is finished by the USB subsystem. The callback function is called in
- interrupt context, so caution must be taken not to do very much processing
- at that time. Our implementation of skel_write_bulk_callback merely
- reports if the urb was completed successfully or not and then returns.
- </para>
- <para>
- The read function works a bit differently from the write function in that
- we do not use an urb to transfer data from the device to the driver.
- Instead we call the usb_bulk_msg function, which can be used to send or
- receive data from a device without having to create urbs and handle
- urb completion callback functions. We call the usb_bulk_msg function,
- giving it a buffer into which to place any data received from the device
- and a timeout value. If the timeout period expires without receiving any
- data from the device, the function will fail and return an error message.
- This can be shown with the following code:
- </para>
- <programlisting>
-/* do an immediate bulk read to get data from the device */
-retval = usb_bulk_msg (skel->dev,
- usb_rcvbulkpipe (skel->dev,
- skel->bulk_in_endpointAddr),
- skel->bulk_in_buffer,
- skel->bulk_in_size,
- &amp;count, HZ*10);
-/* if the read was successful, copy the data to user space */
-if (!retval) {
- if (copy_to_user (buffer, skel->bulk_in_buffer, count))
- retval = -EFAULT;
- else
- retval = count;
-}
- </programlisting>
- <para>
- The usb_bulk_msg function can be very useful for doing single reads or
- writes to a device; however, if you need to read or write constantly to a
- device, it is recommended to set up your own urbs and submit them to the
- USB subsystem.
- </para>
- <para>
- When the user program releases the file handle that it has been using to
- talk to the device, the release function in the driver is called. In this
- function we decrement our private usage count and wait for possible
- pending writes:
- </para>
- <programlisting>
-/* decrement our usage count for the device */
---skel->open_count;
- </programlisting>
- <para>
- One of the more difficult problems that USB drivers must be able to handle
- smoothly is the fact that the USB device may be removed from the system at
- any point in time, even if a program is currently talking to it. It needs
- to be able to shut down any current reads and writes and notify the
- user-space programs that the device is no longer there. The following
- code (function <function>skel_delete</function>)
- is an example of how to do this: </para>
- <programlisting>
-static inline void skel_delete (struct usb_skel *dev)
-{
- kfree (dev->bulk_in_buffer);
- if (dev->bulk_out_buffer != NULL)
- usb_free_coherent (dev->udev, dev->bulk_out_size,
- dev->bulk_out_buffer,
- dev->write_urb->transfer_dma);
- usb_free_urb (dev->write_urb);
- kfree (dev);
-}
- </programlisting>
- <para>
- If a program currently has an open handle to the device, we reset the flag
- <literal>device_present</literal>. For
- every read, write, release and other functions that expect a device to be
- present, the driver first checks this flag to see if the device is
- still present. If not, it releases that the device has disappeared, and a
- -ENODEV error is returned to the user-space program. When the release
- function is eventually called, it determines if there is no device
- and if not, it does the cleanup that the skel_disconnect
- function normally does if there are no open files on the device (see
- Listing 5).
- </para>
- </chapter>
-
- <chapter id="iso">
- <title>Isochronous Data</title>
- <para>
- This usb-skeleton driver does not have any examples of interrupt or
- isochronous data being sent to or from the device. Interrupt data is sent
- almost exactly as bulk data is, with a few minor exceptions. Isochronous
- data works differently with continuous streams of data being sent to or
- from the device. The audio and video camera drivers are very good examples
- of drivers that handle isochronous data and will be useful if you also
- need to do this.
- </para>
- </chapter>
-
- <chapter id="Conclusion">
- <title>Conclusion</title>
- <para>
- Writing Linux USB device drivers is not a difficult task as the
- usb-skeleton driver shows. This driver, combined with the other current
- USB drivers, should provide enough examples to help a beginning author
- create a working driver in a minimal amount of time. The linux-usb-devel
- mailing list archives also contain a lot of helpful information.
- </para>
- </chapter>
-
- <chapter id="resources">
- <title>Resources</title>
- <para>
- The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink>
- </para>
- <para>
- Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink>
- </para>
- <para>
- Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink>
- </para>
- <para>
- linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink>
- </para>
- <para>
- Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink>
- </para>
- <para>
- USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink>
- </para>
- </chapter>
-
-</book>
diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl
deleted file mode 100644
index 6f3883be877e..000000000000
--- a/Documentation/DocBook/z8530book.tmpl
+++ /dev/null
@@ -1,371 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Z85230Guide">
- <bookinfo>
- <title>Z8530 Programming Guide</title>
-
- <authorgroup>
- <author>
- <firstname>Alan</firstname>
- <surname>Cox</surname>
- <affiliation>
- <address>
- <email>alan@lxorguk.ukuu.org.uk</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2000</year>
- <holder>Alan Cox</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The Z85x30 family synchronous/asynchronous controller chips are
- used on a large number of cheap network interface cards. The
- kernel provides a core interface layer that is designed to make
- it easy to provide WAN services using this chip.
- </para>
- <para>
- The current driver only support synchronous operation. Merging the
- asynchronous driver support into this code to allow any Z85x30
- device to be used as both a tty interface and as a synchronous
- controller is a project for Linux post the 2.4 release
- </para>
- </chapter>
-
- <chapter id="Driver_Modes">
- <title>Driver Modes</title>
- <para>
- The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices
- in three different modes. Each mode can be applied to an individual
- channel on the chip (each chip has two channels).
- </para>
- <para>
- The PIO synchronous mode supports the most common Z8530 wiring. Here
- the chip is interface to the I/O and interrupt facilities of the
- host machine but not to the DMA subsystem. When running PIO the
- Z8530 has extremely tight timing requirements. Doing high speeds,
- even with a Z85230 will be tricky. Typically you should expect to
- achieve at best 9600 baud with a Z8C530 and 64Kbits with a Z85230.
- </para>
- <para>
- The DMA mode supports the chip when it is configured to use dual DMA
- channels on an ISA bus. The better cards tend to support this mode
- of operation for a single channel. With DMA running the Z85230 tops
- out when it starts to hit ISA DMA constraints at about 512Kbits. It
- is worth noting here that many PC machines hang or crash when the
- chip is driven fast enough to hold the ISA bus solid.
- </para>
- <para>
- Transmit DMA mode uses a single DMA channel. The DMA channel is used
- for transmission as the transmit FIFO is smaller than the receive
- FIFO. it gives better performance than pure PIO mode but is nowhere
- near as ideal as pure DMA mode.
- </para>
- </chapter>
-
- <chapter id="Using_the_Z85230_driver">
- <title>Using the Z85230 driver</title>
- <para>
- The Z85230 driver provides the back end interface to your board. To
- configure a Z8530 interface you need to detect the board and to
- identify its ports and interrupt resources. It is also your problem
- to verify the resources are available.
- </para>
- <para>
- Having identified the chip you need to fill in a struct z8530_dev,
- which describes each chip. This object must exist until you finally
- shutdown the board. Firstly zero the active field. This ensures
- nothing goes off without you intending it. The irq field should
- be set to the interrupt number of the chip. (Each chip has a single
- interrupt source rather than each channel). You are responsible
- for allocating the interrupt line. The interrupt handler should be
- set to <function>z8530_interrupt</function>. The device id should
- be set to the z8530_dev structure pointer. Whether the interrupt can
- be shared or not is board dependent, and up to you to initialise.
- </para>
- <para>
- The structure holds two channel structures.
- Initialise chanA.ctrlio and chanA.dataio with the address of the
- control and data ports. You can or this with Z8530_PORT_SLEEP to
- indicate your interface needs the 5uS delay for chip settling done
- in software. The PORT_SLEEP option is architecture specific. Other
- flags may become available on future platforms, eg for MMIO.
- Initialise the chanA.irqs to &amp;z8530_nop to start the chip up
- as disabled and discarding interrupt events. This ensures that
- stray interrupts will be mopped up and not hang the bus. Set
- chanA.dev to point to the device structure itself. The
- private and name field you may use as you wish. The private field
- is unused by the Z85230 layer. The name is used for error reporting
- and it may thus make sense to make it match the network name.
- </para>
- <para>
- Repeat the same operation with the B channel if your chip has
- both channels wired to something useful. This isn't always the
- case. If it is not wired then the I/O values do not matter, but
- you must initialise chanB.dev.
- </para>
- <para>
- If your board has DMA facilities then initialise the txdma and
- rxdma fields for the relevant channels. You must also allocate the
- ISA DMA channels and do any necessary board level initialisation
- to configure them. The low level driver will do the Z8530 and
- DMA controller programming but not board specific magic.
- </para>
- <para>
- Having initialised the device you can then call
- <function>z8530_init</function>. This will probe the chip and
- reset it into a known state. An identification sequence is then
- run to identify the chip type. If the checks fail to pass the
- function returns a non zero error code. Typically this indicates
- that the port given is not valid. After this call the
- type field of the z8530_dev structure is initialised to either
- Z8530, Z85C30 or Z85230 according to the chip found.
- </para>
- <para>
- Once you have called z8530_init you can also make use of the utility
- function <function>z8530_describe</function>. This provides a
- consistent reporting format for the Z8530 devices, and allows all
- the drivers to provide consistent reporting.
- </para>
- </chapter>
-
- <chapter id="Attaching_Network_Interfaces">
- <title>Attaching Network Interfaces</title>
- <para>
- If you wish to use the network interface facilities of the driver,
- then you need to attach a network device to each channel that is
- present and in use. In addition to use the generic HDLC
- you need to follow some additional plumbing rules. They may seem
- complex but a look at the example hostess_sv11 driver should
- reassure you.
- </para>
- <para>
- The network device used for each channel should be pointed to by
- the netdevice field of each channel. The hdlc-&gt; priv field of the
- network device points to your private data - you will need to be
- able to find your private data from this.
- </para>
- <para>
- The way most drivers approach this particular problem is to
- create a structure holding the Z8530 device definition and
- put that into the private field of the network device. The
- network device fields of the channels then point back to the
- network devices.
- </para>
- <para>
- If you wish to use the generic HDLC then you need to register
- the HDLC device.
- </para>
- <para>
- Before you register your network device you will also need to
- provide suitable handlers for most of the network device callbacks.
- See the network device documentation for more details on this.
- </para>
- </chapter>
-
- <chapter id="Configuring_And_Activating_The_Port">
- <title>Configuring And Activating The Port</title>
- <para>
- The Z85230 driver provides helper functions and tables to load the
- port registers on the Z8530 chips. When programming the register
- settings for a channel be aware that the documentation recommends
- initialisation orders. Strange things happen when these are not
- followed.
- </para>
- <para>
- <function>z8530_channel_load</function> takes an array of
- pairs of initialisation values in an array of u8 type. The first
- value is the Z8530 register number. Add 16 to indicate the alternate
- register bank on the later chips. The array is terminated by a 255.
- </para>
- <para>
- The driver provides a pair of public tables. The
- z8530_hdlc_kilostream table is for the UK 'Kilostream' service and
- also happens to cover most other end host configurations. The
- z8530_hdlc_kilostream_85230 table is the same configuration using
- the enhancements of the 85230 chip. The configuration loaded is
- standard NRZ encoded synchronous data with HDLC bitstuffing. All
- of the timing is taken from the other end of the link.
- </para>
- <para>
- When writing your own tables be aware that the driver internally
- tracks register values. It may need to reload values. You should
- therefore be sure to set registers 1-7, 9-11, 14 and 15 in all
- configurations. Where the register settings depend on DMA selection
- the driver will update the bits itself when you open or close.
- Loading a new table with the interface open is not recommended.
- </para>
- <para>
- There are three standard configurations supported by the core
- code. In PIO mode the interface is programmed up to use
- interrupt driven PIO. This places high demands on the host processor
- to avoid latency. The driver is written to take account of latency
- issues but it cannot avoid latencies caused by other drivers,
- notably IDE in PIO mode. Because the drivers allocate buffers you
- must also prevent MTU changes while the port is open.
- </para>
- <para>
- Once the port is open it will call the rx_function of each channel
- whenever a completed packet arrived. This is invoked from
- interrupt context and passes you the channel and a network
- buffer (struct sk_buff) holding the data. The data includes
- the CRC bytes so most users will want to trim the last two
- bytes before processing the data. This function is very timing
- critical. When you wish to simply discard data the support
- code provides the function <function>z8530_null_rx</function>
- to discard the data.
- </para>
- <para>
- To active PIO mode sending and receiving the <function>
- z8530_sync_open</function> is called. This expects to be passed
- the network device and the channel. Typically this is called from
- your network device open callback. On a failure a non zero error
- status is returned. The <function>z8530_sync_close</function>
- function shuts down a PIO channel. This must be done before the
- channel is opened again and before the driver shuts down
- and unloads.
- </para>
- <para>
- The ideal mode of operation is dual channel DMA mode. Here the
- kernel driver will configure the board for DMA in both directions.
- The driver also handles ISA DMA issues such as controller
- programming and the memory range limit for you. This mode is
- activated by calling the <function>z8530_sync_dma_open</function>
- function. On failure a non zero error value is returned.
- Once this mode is activated it can be shut down by calling the
- <function>z8530_sync_dma_close</function>. You must call the close
- function matching the open mode you used.
- </para>
- <para>
- The final supported mode uses a single DMA channel to drive the
- transmit side. As the Z85C30 has a larger FIFO on the receive
- channel this tends to increase the maximum speed a little.
- This is activated by calling the <function>z8530_sync_txdma_open
- </function>. This returns a non zero error code on failure. The
- <function>z8530_sync_txdma_close</function> function closes down
- the Z8530 interface from this mode.
- </para>
- </chapter>
-
- <chapter id="Network_Layer_Functions">
- <title>Network Layer Functions</title>
- <para>
- The Z8530 layer provides functions to queue packets for
- transmission. The driver internally buffers the frame currently
- being transmitted and one further frame (in order to keep back
- to back transmission running). Any further buffering is up to
- the caller.
- </para>
- <para>
- The function <function>z8530_queue_xmit</function> takes a network
- buffer in sk_buff format and queues it for transmission. The
- caller must provide the entire packet with the exception of the
- bitstuffing and CRC. This is normally done by the caller via
- the generic HDLC interface layer. It returns 0 if the buffer has been
- queued and non zero values for queue full. If the function accepts
- the buffer it becomes property of the Z8530 layer and the caller
- should not free it.
- </para>
- <para>
- The function <function>z8530_get_stats</function> returns a pointer
- to an internally maintained per interface statistics block. This
- provides most of the interface code needed to implement the network
- layer get_stats callback.
- </para>
- </chapter>
-
- <chapter id="Porting_The_Z8530_Driver">
- <title>Porting The Z8530 Driver</title>
- <para>
- The Z8530 driver is written to be portable. In DMA mode it makes
- assumptions about the use of ISA DMA. These are probably warranted
- in most cases as the Z85230 in particular was designed to glue to PC
- type machines. The PIO mode makes no real assumptions.
- </para>
- <para>
- Should you need to retarget the Z8530 driver to another architecture
- the only code that should need changing are the port I/O functions.
- At the moment these assume PC I/O port accesses. This may not be
- appropriate for all platforms. Replacing
- <function>z8530_read_port</function> and <function>z8530_write_port
- </function> is intended to be all that is required to port this
- driver layer.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- <variablelist>
- <varlistentry><term>Interrupt Locking</term>
- <listitem>
- <para>
- The locking in the driver is done via the global cli/sti lock. This
- makes for relatively poor SMP performance. Switching this to use a
- per device spin lock would probably materially improve performance.
- </para>
- </listitem></varlistentry>
-
- <varlistentry><term>Occasional Failures</term>
- <listitem>
- <para>
- We have reports of occasional failures when run for very long
- periods of time and the driver starts to receive junk frames. At
- the moment the cause of this is not clear.
- </para>
- </listitem></varlistentry>
- </variablelist>
-
- </para>
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
-!Edrivers/net/wan/z85230.c
- </chapter>
-
- <chapter id="intfunctions">
- <title>Internal Functions</title>
-!Idrivers/net/wan/z85230.c
- </chapter>
-
-</book>
diff --git a/Documentation/EDID/1024x768.S b/Documentation/EDID/1024x768.S
deleted file mode 100644
index 6f3e4b75e49e..000000000000
--- a/Documentation/EDID/1024x768.S
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- 1024x768.S: EDID data set for standard 1024x768 60 Hz monitor
-
- Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org>
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-*/
-
-/* EDID */
-#define VERSION 1
-#define REVISION 3
-
-/* Display */
-#define CLOCK 65000 /* kHz */
-#define XPIX 1024
-#define YPIX 768
-#define XY_RATIO XY_RATIO_4_3
-#define XBLANK 320
-#define YBLANK 38
-#define XOFFSET 8
-#define XPULSE 144
-#define YOFFSET (63+3)
-#define YPULSE (63+6)
-#define DPI 72
-#define VFREQ 60 /* Hz */
-#define TIMING_NAME "Linux XGA"
-#define ESTABLISHED_TIMING2_BITS 0x08 /* Bit 3 -> 1024x768 @60 Hz */
-#define HSYNC_POL 0
-#define VSYNC_POL 0
-#define CRC 0x55
-
-#include "edid.S"
diff --git a/Documentation/EDID/1280x1024.S b/Documentation/EDID/1280x1024.S
deleted file mode 100644
index bd9bef2a65af..000000000000
--- a/Documentation/EDID/1280x1024.S
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- 1280x1024.S: EDID data set for standard 1280x1024 60 Hz monitor
-
- Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org>
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-*/
-
-/* EDID */
-#define VERSION 1
-#define REVISION 3
-
-/* Display */
-#define CLOCK 108000 /* kHz */
-#define XPIX 1280
-#define YPIX 1024
-#define XY_RATIO XY_RATIO_5_4
-#define XBLANK 408
-#define YBLANK 42
-#define XOFFSET 48
-#define XPULSE 112
-#define YOFFSET (63+1)
-#define YPULSE (63+3)
-#define DPI 72
-#define VFREQ 60 /* Hz */
-#define TIMING_NAME "Linux SXGA"
-/* No ESTABLISHED_TIMINGx_BITS */
-#define HSYNC_POL 1
-#define VSYNC_POL 1
-#define CRC 0xa0
-
-#include "edid.S"
diff --git a/Documentation/EDID/1600x1200.S b/Documentation/EDID/1600x1200.S
deleted file mode 100644
index a45101c6160c..000000000000
--- a/Documentation/EDID/1600x1200.S
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- 1600x1200.S: EDID data set for standard 1600x1200 60 Hz monitor
-
- Copyright (C) 2013 Carsten Emde <C.Emde@osadl.org>
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-*/
-
-/* EDID */
-#define VERSION 1
-#define REVISION 3
-
-/* Display */
-#define CLOCK 162000 /* kHz */
-#define XPIX 1600
-#define YPIX 1200
-#define XY_RATIO XY_RATIO_4_3
-#define XBLANK 560
-#define YBLANK 50
-#define XOFFSET 64
-#define XPULSE 192
-#define YOFFSET (63+1)
-#define YPULSE (63+3)
-#define DPI 72
-#define VFREQ 60 /* Hz */
-#define TIMING_NAME "Linux UXGA"
-/* No ESTABLISHED_TIMINGx_BITS */
-#define HSYNC_POL 1
-#define VSYNC_POL 1
-#define CRC 0x9d
-
-#include "edid.S"
diff --git a/Documentation/EDID/1680x1050.S b/Documentation/EDID/1680x1050.S
deleted file mode 100644
index b0d7c69282b4..000000000000
--- a/Documentation/EDID/1680x1050.S
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- 1680x1050.S: EDID data set for standard 1680x1050 60 Hz monitor
-
- Copyright (C) 2012 Carsten Emde <C.Emde@osadl.org>
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-*/
-
-/* EDID */
-#define VERSION 1
-#define REVISION 3
-
-/* Display */
-#define CLOCK 146250 /* kHz */
-#define XPIX 1680
-#define YPIX 1050
-#define XY_RATIO XY_RATIO_16_10
-#define XBLANK 560
-#define YBLANK 39
-#define XOFFSET 104
-#define XPULSE 176
-#define YOFFSET (63+3)
-#define YPULSE (63+6)
-#define DPI 96
-#define VFREQ 60 /* Hz */
-#define TIMING_NAME "Linux WSXGA"
-/* No ESTABLISHED_TIMINGx_BITS */
-#define HSYNC_POL 1
-#define VSYNC_POL 1
-#define CRC 0x26
-
-#include "edid.S"
diff --git a/Documentation/EDID/1920x1080.S b/Documentation/EDID/1920x1080.S
deleted file mode 100644
index 3084355e81e7..000000000000
--- a/Documentation/EDID/1920x1080.S
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- 1920x1080.S: EDID data set for standard 1920x1080 60 Hz monitor
-
- Copyright (C) 2012 Carsten Emde <C.Emde@osadl.org>
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-*/
-
-/* EDID */
-#define VERSION 1
-#define REVISION 3
-
-/* Display */
-#define CLOCK 148500 /* kHz */
-#define XPIX 1920
-#define YPIX 1080
-#define XY_RATIO XY_RATIO_16_9
-#define XBLANK 280
-#define YBLANK 45
-#define XOFFSET 88
-#define XPULSE 44
-#define YOFFSET (63+4)
-#define YPULSE (63+5)
-#define DPI 96
-#define VFREQ 60 /* Hz */
-#define TIMING_NAME "Linux FHD"
-/* No ESTABLISHED_TIMINGx_BITS */
-#define HSYNC_POL 1
-#define VSYNC_POL 1
-#define CRC 0x05
-
-#include "edid.S"
diff --git a/Documentation/EDID/800x600.S b/Documentation/EDID/800x600.S
deleted file mode 100644
index 6644e26d5801..000000000000
--- a/Documentation/EDID/800x600.S
+++ /dev/null
@@ -1,41 +0,0 @@
-/*
- 800x600.S: EDID data set for standard 800x600 60 Hz monitor
-
- Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org>
- Copyright (C) 2014 Linaro Limited
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-*/
-
-/* EDID */
-#define VERSION 1
-#define REVISION 3
-
-/* Display */
-#define CLOCK 40000 /* kHz */
-#define XPIX 800
-#define YPIX 600
-#define XY_RATIO XY_RATIO_4_3
-#define XBLANK 256
-#define YBLANK 28
-#define XOFFSET 40
-#define XPULSE 128
-#define YOFFSET (63+1)
-#define YPULSE (63+4)
-#define DPI 72
-#define VFREQ 60 /* Hz */
-#define TIMING_NAME "Linux SVGA"
-#define ESTABLISHED_TIMING1_BITS 0x01 /* Bit 0: 800x600 @ 60Hz */
-#define HSYNC_POL 1
-#define VSYNC_POL 1
-#define CRC 0xc2
-
-#include "edid.S"
diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/HOWTO.txt
deleted file mode 100644
index 835db332289b..000000000000
--- a/Documentation/EDID/HOWTO.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-In the good old days when graphics parameters were configured explicitly
-in a file called xorg.conf, even broken hardware could be managed.
-
-Today, with the advent of Kernel Mode Setting, a graphics board is
-either correctly working because all components follow the standards -
-or the computer is unusable, because the screen remains dark after
-booting or it displays the wrong area. Cases when this happens are:
-- The graphics board does not recognize the monitor.
-- The graphics board is unable to detect any EDID data.
-- The graphics board incorrectly forwards EDID data to the driver.
-- The monitor sends no or bogus EDID data.
-- A KVM sends its own EDID data instead of querying the connected monitor.
-Adding the kernel parameter "nomodeset" helps in most cases, but causes
-restrictions later on.
-
-As a remedy for such situations, the kernel configuration item
-CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an
-individually prepared or corrected EDID data set in the /lib/firmware
-directory from where it is loaded via the firmware interface. The code
-(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for
-commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200,
-1680x1050, 1920x1080) as binary blobs, but the kernel source tree does
-not contain code to create these data. In order to elucidate the origin
-of the built-in binary EDID blobs and to facilitate the creation of
-individual data for a specific misbehaving monitor, commented sources
-and a Makefile environment are given here.
-
-To create binary EDID and C source code files from the existing data
-material, simply type "make".
-
-If you want to create your own EDID file, copy the file 1024x768.S,
-replace the settings with your own data and add a new target to the
-Makefile. Please note that the EDID data structure expects the timing
-values in a different way as compared to the standard X11 format.
-
-X11:
-HTimings: hdisp hsyncstart hsyncend htotal
-VTimings: vdisp vsyncstart vsyncend vtotal
-
-EDID:
-#define XPIX hdisp
-#define XBLANK htotal-hdisp
-#define XOFFSET hsyncstart-hdisp
-#define XPULSE hsyncend-hsyncstart
-
-#define YPIX vdisp
-#define YBLANK vtotal-vdisp
-#define YOFFSET (63+(vsyncstart-vdisp))
-#define YPULSE (63+(vsyncend-vsyncstart))
-
-The CRC value in the last line
- #define CRC 0x55
-also is a bit tricky. After a first version of the binary data set is
-created, it must be checked with the "edid-decode" utility which will
-most probably complain about a wrong CRC. Fortunately, the utility also
-displays the correct CRC which must then be inserted into the source
-file. After the make procedure is repeated, the EDID data set is ready
-to be used.
diff --git a/Documentation/EDID/Makefile b/Documentation/EDID/Makefile
deleted file mode 100644
index 17763ca3f12b..000000000000
--- a/Documentation/EDID/Makefile
+++ /dev/null
@@ -1,26 +0,0 @@
-
-SOURCES := $(wildcard [0-9]*x[0-9]*.S)
-
-BIN := $(patsubst %.S, %.bin, $(SOURCES))
-
-IHEX := $(patsubst %.S, %.bin.ihex, $(SOURCES))
-
-CODE := $(patsubst %.S, %.c, $(SOURCES))
-
-all: $(BIN) $(IHEX) $(CODE)
-
-clean:
- @rm -f *.o *.bin.ihex *.bin *.c
-
-%.o: %.S
- @cc -c $^
-
-%.bin: %.o
- @objcopy -Obinary $^ $@
-
-%.bin.ihex: %.o
- @objcopy -Oihex $^ $@
- @dos2unix $@ 2>/dev/null
-
-%.c: %.bin
- @echo "{" >$@; hexdump -f hex $^ >>$@; echo "};" >>$@
diff --git a/Documentation/EDID/edid.S b/Documentation/EDID/edid.S
deleted file mode 100644
index 7ac03276d7a2..000000000000
--- a/Documentation/EDID/edid.S
+++ /dev/null
@@ -1,272 +0,0 @@
-/*
- edid.S: EDID data template
-
- Copyright (C) 2012 Carsten Emde <C.Emde@osadl.org>
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-*/
-
-
-/* Manufacturer */
-#define MFG_LNX1 'L'
-#define MFG_LNX2 'N'
-#define MFG_LNX3 'X'
-#define SERIAL 0
-#define YEAR 2012
-#define WEEK 5
-
-/* EDID 1.3 standard definitions */
-#define XY_RATIO_16_10 0b00
-#define XY_RATIO_4_3 0b01
-#define XY_RATIO_5_4 0b10
-#define XY_RATIO_16_9 0b11
-
-/* Provide defaults for the timing bits */
-#ifndef ESTABLISHED_TIMING1_BITS
-#define ESTABLISHED_TIMING1_BITS 0x00
-#endif
-#ifndef ESTABLISHED_TIMING2_BITS
-#define ESTABLISHED_TIMING2_BITS 0x00
-#endif
-#ifndef ESTABLISHED_TIMING3_BITS
-#define ESTABLISHED_TIMING3_BITS 0x00
-#endif
-
-#define mfgname2id(v1,v2,v3) \
- ((((v1-'@')&0x1f)<<10)+(((v2-'@')&0x1f)<<5)+((v3-'@')&0x1f))
-#define swap16(v1) ((v1>>8)+((v1&0xff)<<8))
-#define msbs2(v1,v2) ((((v1>>8)&0x0f)<<4)+((v2>>8)&0x0f))
-#define msbs4(v1,v2,v3,v4) \
- (((v1&0x03)>>2)+((v2&0x03)>>4)+((v3&0x03)>>6)+((v4&0x03)>>8))
-#define pixdpi2mm(pix,dpi) ((pix*25)/dpi)
-#define xsize pixdpi2mm(XPIX,DPI)
-#define ysize pixdpi2mm(YPIX,DPI)
-
- .data
-
-/* Fixed header pattern */
-header: .byte 0x00,0xff,0xff,0xff,0xff,0xff,0xff,0x00
-
-mfg_id: .word swap16(mfgname2id(MFG_LNX1, MFG_LNX2, MFG_LNX3))
-
-prod_code: .word 0
-
-/* Serial number. 32 bits, little endian. */
-serial_number: .long SERIAL
-
-/* Week of manufacture */
-week: .byte WEEK
-
-/* Year of manufacture, less 1990. (1990-2245)
- If week=255, it is the model year instead */
-year: .byte YEAR-1990
-
-version: .byte VERSION /* EDID version, usually 1 (for 1.3) */
-revision: .byte REVISION /* EDID revision, usually 3 (for 1.3) */
-
-/* If Bit 7=1 Digital input. If set, the following bit definitions apply:
- Bits 6-1 Reserved, must be 0
- Bit 0 Signal is compatible with VESA DFP 1.x TMDS CRGB,
- 1 pixel per clock, up to 8 bits per color, MSB aligned,
- If Bit 7=0 Analog input. If clear, the following bit definitions apply:
- Bits 6-5 Video white and sync levels, relative to blank
- 00=+0.7/-0.3 V; 01=+0.714/-0.286 V;
- 10=+1.0/-0.4 V; 11=+0.7/0 V
- Bit 4 Blank-to-black setup (pedestal) expected
- Bit 3 Separate sync supported
- Bit 2 Composite sync (on HSync) supported
- Bit 1 Sync on green supported
- Bit 0 VSync pulse must be serrated when somposite or
- sync-on-green is used. */
-video_parms: .byte 0x6d
-
-/* Maximum horizontal image size, in centimetres
- (max 292 cm/115 in at 16:9 aspect ratio) */
-max_hor_size: .byte xsize/10
-
-/* Maximum vertical image size, in centimetres.
- If either byte is 0, undefined (e.g. projector) */
-max_vert_size: .byte ysize/10
-
-/* Display gamma, minus 1, times 100 (range 1.00-3.5 */
-gamma: .byte 120
-
-/* Bit 7 DPMS standby supported
- Bit 6 DPMS suspend supported
- Bit 5 DPMS active-off supported
- Bits 4-3 Display type: 00=monochrome; 01=RGB colour;
- 10=non-RGB multicolour; 11=undefined
- Bit 2 Standard sRGB colour space. Bytes 25-34 must contain
- sRGB standard values.
- Bit 1 Preferred timing mode specified in descriptor block 1.
- Bit 0 GTF supported with default parameter values. */
-dsp_features: .byte 0xea
-
-/* Chromaticity coordinates. */
-/* Red and green least-significant bits
- Bits 7-6 Red x value least-significant 2 bits
- Bits 5-4 Red y value least-significant 2 bits
- Bits 3-2 Green x value lst-significant 2 bits
- Bits 1-0 Green y value least-significant 2 bits */
-red_green_lsb: .byte 0x5e
-
-/* Blue and white least-significant 2 bits */
-blue_white_lsb: .byte 0xc0
-
-/* Red x value most significant 8 bits.
- 0-255 encodes 0-0.996 (255/256); 0-0.999 (1023/1024) with lsbits */
-red_x_msb: .byte 0xa4
-
-/* Red y value most significant 8 bits */
-red_y_msb: .byte 0x59
-
-/* Green x and y value most significant 8 bits */
-green_x_y_msb: .byte 0x4a,0x98
-
-/* Blue x and y value most significant 8 bits */
-blue_x_y_msb: .byte 0x25,0x20
-
-/* Default white point x and y value most significant 8 bits */
-white_x_y_msb: .byte 0x50,0x54
-
-/* Established timings */
-/* Bit 7 720x400 @ 70 Hz
- Bit 6 720x400 @ 88 Hz
- Bit 5 640x480 @ 60 Hz
- Bit 4 640x480 @ 67 Hz
- Bit 3 640x480 @ 72 Hz
- Bit 2 640x480 @ 75 Hz
- Bit 1 800x600 @ 56 Hz
- Bit 0 800x600 @ 60 Hz */
-estbl_timing1: .byte ESTABLISHED_TIMING1_BITS
-
-/* Bit 7 800x600 @ 72 Hz
- Bit 6 800x600 @ 75 Hz
- Bit 5 832x624 @ 75 Hz
- Bit 4 1024x768 @ 87 Hz, interlaced (1024x768)
- Bit 3 1024x768 @ 60 Hz
- Bit 2 1024x768 @ 72 Hz
- Bit 1 1024x768 @ 75 Hz
- Bit 0 1280x1024 @ 75 Hz */
-estbl_timing2: .byte ESTABLISHED_TIMING2_BITS
-
-/* Bit 7 1152x870 @ 75 Hz (Apple Macintosh II)
- Bits 6-0 Other manufacturer-specific display mod */
-estbl_timing3: .byte ESTABLISHED_TIMING3_BITS
-
-/* Standard timing */
-/* X resolution, less 31, divided by 8 (256-2288 pixels) */
-std_xres: .byte (XPIX/8)-31
-/* Y resolution, X:Y pixel ratio
- Bits 7-6 X:Y pixel ratio: 00=16:10; 01=4:3; 10=5:4; 11=16:9.
- Bits 5-0 Vertical frequency, less 60 (60-123 Hz) */
-std_vres: .byte (XY_RATIO<<6)+VFREQ-60
- .fill 7,2,0x0101 /* Unused */
-
-descriptor1:
-/* Pixel clock in 10 kHz units. (0.-655.35 MHz, little-endian) */
-clock: .word CLOCK/10
-
-/* Horizontal active pixels 8 lsbits (0-4095) */
-x_act_lsb: .byte XPIX&0xff
-/* Horizontal blanking pixels 8 lsbits (0-4095)
- End of active to start of next active. */
-x_blk_lsb: .byte XBLANK&0xff
-/* Bits 7-4 Horizontal active pixels 4 msbits
- Bits 3-0 Horizontal blanking pixels 4 msbits */
-x_msbs: .byte msbs2(XPIX,XBLANK)
-
-/* Vertical active lines 8 lsbits (0-4095) */
-y_act_lsb: .byte YPIX&0xff
-/* Vertical blanking lines 8 lsbits (0-4095) */
-y_blk_lsb: .byte YBLANK&0xff
-/* Bits 7-4 Vertical active lines 4 msbits
- Bits 3-0 Vertical blanking lines 4 msbits */
-y_msbs: .byte msbs2(YPIX,YBLANK)
-
-/* Horizontal sync offset pixels 8 lsbits (0-1023) From blanking start */
-x_snc_off_lsb: .byte XOFFSET&0xff
-/* Horizontal sync pulse width pixels 8 lsbits (0-1023) */
-x_snc_pls_lsb: .byte XPULSE&0xff
-/* Bits 7-4 Vertical sync offset lines 4 lsbits -63)
- Bits 3-0 Vertical sync pulse width lines 4 lsbits -63) */
-y_snc_lsb: .byte ((YOFFSET-63)<<4)+(YPULSE-63)
-/* Bits 7-6 Horizontal sync offset pixels 2 msbits
- Bits 5-4 Horizontal sync pulse width pixels 2 msbits
- Bits 3-2 Vertical sync offset lines 2 msbits
- Bits 1-0 Vertical sync pulse width lines 2 msbits */
-xy_snc_msbs: .byte msbs4(XOFFSET,XPULSE,YOFFSET,YPULSE)
-
-/* Horizontal display size, mm, 8 lsbits (0-4095 mm, 161 in) */
-x_dsp_size: .byte xsize&0xff
-
-/* Vertical display size, mm, 8 lsbits (0-4095 mm, 161 in) */
-y_dsp_size: .byte ysize&0xff
-
-/* Bits 7-4 Horizontal display size, mm, 4 msbits
- Bits 3-0 Vertical display size, mm, 4 msbits */
-dsp_size_mbsb: .byte msbs2(xsize,ysize)
-
-/* Horizontal border pixels (each side; total is twice this) */
-x_border: .byte 0
-/* Vertical border lines (each side; total is twice this) */
-y_border: .byte 0
-
-/* Bit 7 Interlaced
- Bits 6-5 Stereo mode: 00=No stereo; other values depend on bit 0:
- Bit 0=0: 01=Field sequential, sync=1 during right; 10=similar,
- sync=1 during left; 11=4-way interleaved stereo
- Bit 0=1 2-way interleaved stereo: 01=Right image on even lines;
- 10=Left image on even lines; 11=side-by-side
- Bits 4-3 Sync type: 00=Analog composite; 01=Bipolar analog composite;
- 10=Digital composite (on HSync); 11=Digital separate
- Bit 2 If digital separate: Vertical sync polarity (1=positive)
- Other types: VSync serrated (HSync during VSync)
- Bit 1 If analog sync: Sync on all 3 RGB lines (else green only)
- Digital: HSync polarity (1=positive)
- Bit 0 2-way line-interleaved stereo, if bits 4-3 are not 00. */
-features: .byte 0x18+(VSYNC_POL<<2)+(HSYNC_POL<<1)
-
-descriptor2: .byte 0,0 /* Not a detailed timing descriptor */
- .byte 0 /* Must be zero */
- .byte 0xff /* Descriptor is monitor serial number (text) */
- .byte 0 /* Must be zero */
-start1: .ascii "Linux #0"
-end1: .byte 0x0a /* End marker */
- .fill 12-(end1-start1), 1, 0x20 /* Padded spaces */
-descriptor3: .byte 0,0 /* Not a detailed timing descriptor */
- .byte 0 /* Must be zero */
- .byte 0xfd /* Descriptor is monitor range limits */
- .byte 0 /* Must be zero */
-start2: .byte VFREQ-1 /* Minimum vertical field rate (1-255 Hz) */
- .byte VFREQ+1 /* Maximum vertical field rate (1-255 Hz) */
- .byte (CLOCK/(XPIX+XBLANK))-1 /* Minimum horizontal line rate
- (1-255 kHz) */
- .byte (CLOCK/(XPIX+XBLANK))+1 /* Maximum horizontal line rate
- (1-255 kHz) */
- .byte (CLOCK/10000)+1 /* Maximum pixel clock rate, rounded up
- to 10 MHz multiple (10-2550 MHz) */
- .byte 0 /* No extended timing information type */
-end2: .byte 0x0a /* End marker */
- .fill 12-(end2-start2), 1, 0x20 /* Padded spaces */
-descriptor4: .byte 0,0 /* Not a detailed timing descriptor */
- .byte 0 /* Must be zero */
- .byte 0xfc /* Descriptor is text */
- .byte 0 /* Must be zero */
-start3: .ascii TIMING_NAME
-end3: .byte 0x0a /* End marker */
- .fill 12-(end3-start3), 1, 0x20 /* Padded spaces */
-extensions: .byte 0 /* Number of extensions to follow */
-checksum: .byte CRC /* Sum of all bytes must be 0 */
diff --git a/Documentation/EDID/hex b/Documentation/EDID/hex
deleted file mode 100644
index 8873ebb618af..000000000000
--- a/Documentation/EDID/hex
+++ /dev/null
@@ -1 +0,0 @@
-"\t" 8/1 "0x%02x, " "\n"
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
deleted file mode 100644
index 93aa8604630e..000000000000
--- a/Documentation/HOWTO
+++ /dev/null
@@ -1,609 +0,0 @@
-HOWTO do Linux kernel development
----------------------------------
-
-This is the be-all, end-all document on this topic. It contains
-instructions on how to become a Linux kernel developer and how to learn
-to work with the Linux kernel development community. It tries to not
-contain anything related to the technical aspects of kernel programming,
-but will help point you in the right direction for that.
-
-If anything in this document becomes out of date, please send in patches
-to the maintainer of this file, who is listed at the bottom of the
-document.
-
-
-Introduction
-------------
-
-So, you want to learn how to become a Linux kernel developer? Or you
-have been told by your manager, "Go write a Linux driver for this
-device." This document's goal is to teach you everything you need to
-know to achieve this by describing the process you need to go through,
-and hints on how to work with the community. It will also try to
-explain some of the reasons why the community works like it does.
-
-The kernel is written mostly in C, with some architecture-dependent
-parts written in assembly. A good understanding of C is required for
-kernel development. Assembly (any architecture) is not required unless
-you plan to do low-level development for that architecture. Though they
-are not a good substitute for a solid C education and/or years of
-experience, the following books are good for, if anything, reference:
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
- - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
-
-The kernel is written using GNU C and the GNU toolchain. While it
-adheres to the ISO C89 standard, it uses a number of extensions that are
-not featured in the standard. The kernel is a freestanding C
-environment, with no reliance on the standard C library, so some
-portions of the C standard are not supported. Arbitrary long long
-divisions and floating point are not allowed. It can sometimes be
-difficult to understand the assumptions the kernel has on the toolchain
-and the extensions that it uses, and unfortunately there is no
-definitive reference for them. Please check the gcc info pages (`info
-gcc`) for some information on them.
-
-Please remember that you are trying to learn how to work with the
-existing development community. It is a diverse group of people, with
-high standards for coding, style and procedure. These standards have
-been created over time based on what they have found to work best for
-such a large and geographically dispersed team. Try to learn as much as
-possible about these standards ahead of time, as they are well
-documented; do not expect people to adapt to you or your company's way
-of doing things.
-
-
-Legal Issues
-------------
-
-The Linux kernel source code is released under the GPL. Please see the
-file, COPYING, in the main directory of the source tree, for details on
-the license. If you have further questions about the license, please
-contact a lawyer, and do not ask on the Linux kernel mailing list. The
-people on the mailing lists are not lawyers, and you should not rely on
-their statements on legal matters.
-
-For common questions and answers about the GPL, please see:
- http://www.gnu.org/licenses/gpl-faq.html
-
-
-Documentation
-------------
-
-The Linux kernel source tree has a large range of documents that are
-invaluable for learning how to interact with the kernel community. When
-new features are added to the kernel, it is recommended that new
-documentation files are also added which explain how to use the feature.
-When a kernel change causes the interface that the kernel exposes to
-userspace to change, it is recommended that you send the information or
-a patch to the manual pages explaining the change to the manual pages
-maintainer at mtk.manpages@gmail.com, and CC the list
-linux-api@vger.kernel.org.
-
-Here is a list of files that are in the kernel source tree that are
-required reading:
- README
- This file gives a short background on the Linux kernel and describes
- what is necessary to do to configure and build the kernel. People
- who are new to the kernel should start here.
-
- Documentation/Changes
- This file gives a list of the minimum levels of various software
- packages that are necessary to build and run the kernel
- successfully.
-
- Documentation/CodingStyle
- This describes the Linux kernel coding style, and some of the
- rationale behind it. All new code is expected to follow the
- guidelines in this document. Most maintainers will only accept
- patches if these rules are followed, and many people will only
- review code if it is in the proper style.
-
- Documentation/SubmittingPatches
- Documentation/SubmittingDrivers
- These files describe in explicit detail how to successfully create
- and send a patch, including (but not limited to):
- - Email contents
- - Email format
- - Who to send it to
- Following these rules will not guarantee success (as all patches are
- subject to scrutiny for content and style), but not following them
- will almost always prevent it.
-
- Other excellent descriptions of how to create patches properly are:
- "The Perfect Patch"
- http://www.ozlabs.org/~akpm/stuff/tpp.txt
- "Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
-
- Documentation/stable_api_nonsense.txt
- This file describes the rationale behind the conscious decision to
- not have a stable API within the kernel, including things like:
- - Subsystem shim-layers (for compatibility?)
- - Driver portability between Operating Systems.
- - Mitigating rapid change within the kernel source tree (or
- preventing rapid change)
- This document is crucial for understanding the Linux development
- philosophy and is very important for people moving to Linux from
- development on other Operating Systems.
-
- Documentation/SecurityBugs
- If you feel you have found a security problem in the Linux kernel,
- please follow the steps in this document to help notify the kernel
- developers, and help solve the issue.
-
- Documentation/ManagementStyle
- This document describes how Linux kernel maintainers operate and the
- shared ethos behind their methodologies. This is important reading
- for anyone new to kernel development (or anyone simply curious about
- it), as it resolves a lot of common misconceptions and confusion
- about the unique behavior of kernel maintainers.
-
- Documentation/stable_kernel_rules.txt
- This file describes the rules on how the stable kernel releases
- happen, and what to do if you want to get a change into one of these
- releases.
-
- Documentation/kernel-docs.txt
- A list of external documentation that pertains to kernel
- development. Please consult this list if you do not find what you
- are looking for within the in-kernel documentation.
-
- Documentation/applying-patches.txt
- A good introduction describing exactly what a patch is and how to
- apply it to the different development branches of the kernel.
-
-The kernel also has a large number of documents that can be
-automatically generated from the source code itself. This includes a
-full description of the in-kernel API, and rules on how to handle
-locking properly. The documents will be created in the
-Documentation/DocBook/ directory and can be generated as PDF,
-Postscript, HTML, and man pages by running:
- make pdfdocs
- make psdocs
- make htmldocs
- make mandocs
-respectively from the main kernel source directory.
-
-
-Becoming A Kernel Developer
----------------------------
-
-If you do not know anything about Linux kernel development, you should
-look at the Linux KernelNewbies project:
- http://kernelnewbies.org
-It consists of a helpful mailing list where you can ask almost any type
-of basic kernel development question (make sure to search the archives
-first, before asking something that has already been answered in the
-past.) It also has an IRC channel that you can use to ask questions in
-real-time, and a lot of helpful documentation that is useful for
-learning about Linux kernel development.
-
-The website has basic information about code organization, subsystems,
-and current projects (both in-tree and out-of-tree). It also describes
-some basic logistical information, like how to compile a kernel and
-apply a patch.
-
-If you do not know where you want to start, but you want to look for
-some task to start doing to join into the kernel development community,
-go to the Linux Kernel Janitor's project:
- http://kernelnewbies.org/KernelJanitors
-It is a great place to start. It describes a list of relatively simple
-problems that need to be cleaned up and fixed within the Linux kernel
-source tree. Working with the developers in charge of this project, you
-will learn the basics of getting your patch into the Linux kernel tree,
-and possibly be pointed in the direction of what to go work on next, if
-you do not already have an idea.
-
-If you already have a chunk of code that you want to put into the kernel
-tree, but need some help getting it in the proper form, the
-kernel-mentors project was created to help you out with this. It is a
-mailing list, and can be found at:
- http://selenic.com/mailman/listinfo/kernel-mentors
-
-Before making any actual modifications to the Linux kernel code, it is
-imperative to understand how the code in question works. For this
-purpose, nothing is better than reading through it directly (most tricky
-bits are commented well), perhaps even with the help of specialized
-tools. One such tool that is particularly recommended is the Linux
-Cross-Reference project, which is able to present source code in a
-self-referential, indexed webpage format. An excellent up-to-date
-repository of the kernel code may be found at:
- http://lxr.linux.no/+trees
-
-
-The development process
------------------------
-
-Linux kernel development process currently consists of a few different
-main kernel "branches" and lots of different subsystem-specific kernel
-branches. These different branches are:
- - main 3.x kernel tree
- - 3.x.y -stable kernel tree
- - 3.x -git kernel patches
- - subsystem specific kernel trees and patches
- - the 3.x -next kernel tree for integration tests
-
-3.x kernel tree
------------------
-3.x kernels are maintained by Linus Torvalds, and can be found on
-kernel.org in the pub/linux/kernel/v3.x/ directory. Its development
-process is as follows:
- - As soon as a new kernel is released a two weeks window is open,
- during this period of time maintainers can submit big diffs to
- Linus, usually the patches that have already been included in the
- -next kernel for a few weeks. The preferred way to submit big changes
- is using git (the kernel's source management tool, more information
- can be found at http://git-scm.com/) but plain patches are also just
- fine.
- - After two weeks a -rc1 kernel is released it is now possible to push
- only patches that do not include new features that could affect the
- stability of the whole kernel. Please note that a whole new driver
- (or filesystem) might be accepted after -rc1 because there is no
- risk of causing regressions with such a change as long as the change
- is self-contained and does not affect areas outside of the code that
- is being added. git can be used to send patches to Linus after -rc1
- is released, but the patches need to also be sent to a public
- mailing list for review.
- - A new -rc is released whenever Linus deems the current git tree to
- be in a reasonably sane state adequate for testing. The goal is to
- release a new -rc kernel every week.
- - Process continues until the kernel is considered "ready", the
- process should last around 6 weeks.
- - Known regressions in each release are periodically posted to the
- linux-kernel mailing list. The goal is to reduce the length of
- that list to zero before declaring the kernel to be "ready," but, in
- the real world, a small number of regressions often remain at
- release time.
-
-It is worth mentioning what Andrew Morton wrote on the linux-kernel
-mailing list about kernel releases:
- "Nobody knows when a kernel will be released, because it's
- released according to perceived bug status, not according to a
- preconceived timeline."
-
-3.x.y -stable kernel tree
----------------------------
-Kernels with 3-part versions are -stable kernels. They contain
-relatively small and critical fixes for security problems or significant
-regressions discovered in a given 3.x kernel.
-
-This is the recommended branch for users who want the most recent stable
-kernel and are not interested in helping test development/experimental
-versions.
-
-If no 3.x.y kernel is available, then the highest numbered 3.x
-kernel is the current stable kernel.
-
-3.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
-are released as needs dictate. The normal release period is approximately
-two weeks, but it can be longer if there are no pressing problems. A
-security-related problem, instead, can cause a release to happen almost
-instantly.
-
-The file Documentation/stable_kernel_rules.txt in the kernel tree
-documents what kinds of changes are acceptable for the -stable tree, and
-how the release process works.
-
-3.x -git patches
-------------------
-These are daily snapshots of Linus' kernel tree which are managed in a
-git repository (hence the name.) These patches are usually released
-daily and represent the current state of Linus' tree. They are more
-experimental than -rc kernels since they are generated automatically
-without even a cursory glance to see if they are sane.
-
-Subsystem Specific kernel trees and patches
--------------------------------------------
-The maintainers of the various kernel subsystems --- and also many
-kernel subsystem developers --- expose their current state of
-development in source repositories. That way, others can see what is
-happening in the different areas of the kernel. In areas where
-development is rapid, a developer may be asked to base his submissions
-onto such a subsystem kernel tree so that conflicts between the
-submission and other already ongoing work are avoided.
-
-Most of these repositories are git trees, but there are also other SCMs
-in use, or patch queues being published as quilt series. Addresses of
-these subsystem repositories are listed in the MAINTAINERS file. Many
-of them can be browsed at http://git.kernel.org/.
-
-Before a proposed patch is committed to such a subsystem tree, it is
-subject to review which primarily happens on mailing lists (see the
-respective section below). For several kernel subsystems, this review
-process is tracked with the tool patchwork. Patchwork offers a web
-interface which shows patch postings, any comments on a patch or
-revisions to it, and maintainers can mark patches as under review,
-accepted, or rejected. Most of these patchwork sites are listed at
-http://patchwork.kernel.org/.
-
-3.x -next kernel tree for integration tests
----------------------------------------------
-Before updates from subsystem trees are merged into the mainline 3.x
-tree, they need to be integration-tested. For this purpose, a special
-testing repository exists into which virtually all subsystem trees are
-pulled on an almost daily basis:
- http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
-
-This way, the -next kernel gives a summary outlook onto what will be
-expected to go into the mainline kernel at the next merge period.
-Adventurous testers are very welcome to runtime-test the -next kernel.
-
-
-Bug Reporting
--------------
-
-bugzilla.kernel.org is where the Linux kernel developers track kernel
-bugs. Users are encouraged to report all bugs that they find in this
-tool. For details on how to use the kernel bugzilla, please see:
- http://bugzilla.kernel.org/page.cgi?id=faq.html
-
-The file REPORTING-BUGS in the main kernel source directory has a good
-template for how to report a possible kernel bug, and details what kind
-of information is needed by the kernel developers to help track down the
-problem.
-
-
-Managing bug reports
---------------------
-
-One of the best ways to put into practice your hacking skills is by fixing
-bugs reported by other people. Not only you will help to make the kernel
-more stable, you'll learn to fix real world problems and you will improve
-your skills, and other developers will be aware of your presence. Fixing
-bugs is one of the best ways to get merits among other developers, because
-not many people like wasting time fixing other people's bugs.
-
-To work in the already reported bug reports, go to http://bugzilla.kernel.org.
-If you want to be advised of the future bug reports, you can subscribe to the
-bugme-new mailing list (only new bug reports are mailed here) or to the
-bugme-janitor mailing list (every change in the bugzilla is mailed here)
-
- http://lists.linux-foundation.org/mailman/listinfo/bugme-new
- http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
-
-
-Mailing lists
--------------
-
-As some of the above documents describe, the majority of the core kernel
-developers participate on the Linux Kernel Mailing list. Details on how
-to subscribe and unsubscribe from the list can be found at:
- http://vger.kernel.org/vger-lists.html#linux-kernel
-There are archives of the mailing list on the web in many different
-places. Use a search engine to find these archives. For example:
- http://dir.gmane.org/gmane.linux.kernel
-It is highly recommended that you search the archives about the topic
-you want to bring up, before you post it to the list. A lot of things
-already discussed in detail are only recorded at the mailing list
-archives.
-
-Most of the individual kernel subsystems also have their own separate
-mailing list where they do their development efforts. See the
-MAINTAINERS file for a list of what these lists are for the different
-groups.
-
-Many of the lists are hosted on kernel.org. Information on them can be
-found at:
- http://vger.kernel.org/vger-lists.html
-
-Please remember to follow good behavioral habits when using the lists.
-Though a bit cheesy, the following URL has some simple guidelines for
-interacting with the list (or any list):
- http://www.albion.com/netiquette/
-
-If multiple people respond to your mail, the CC: list of recipients may
-get pretty large. Don't remove anybody from the CC: list without a good
-reason, or don't reply only to the list address. Get used to receiving the
-mail twice, one from the sender and the one from the list, and don't try
-to tune that by adding fancy mail-headers, people will not like it.
-
-Remember to keep the context and the attribution of your replies intact,
-keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and
-add your statements between the individual quoted sections instead of
-writing at the top of the mail.
-
-If you add patches to your mail, make sure they are plain readable text
-as stated in Documentation/SubmittingPatches. Kernel developers don't
-want to deal with attachments or compressed patches; they may want
-to comment on individual lines of your patch, which works only that way.
-Make sure you use a mail program that does not mangle spaces and tab
-characters. A good first test is to send the mail to yourself and try
-to apply your own patch by yourself. If that doesn't work, get your
-mail program fixed or change it until it works.
-
-Above all, please remember to show respect to other subscribers.
-
-
-Working with the community
---------------------------
-
-The goal of the kernel community is to provide the best possible kernel
-there is. When you submit a patch for acceptance, it will be reviewed
-on its technical merits and those alone. So, what should you be
-expecting?
- - criticism
- - comments
- - requests for change
- - requests for justification
- - silence
-
-Remember, this is part of getting your patch into the kernel. You have
-to be able to take criticism and comments about your patches, evaluate
-them at a technical level and either rework your patches or provide
-clear and concise reasoning as to why those changes should not be made.
-If there are no responses to your posting, wait a few days and try
-again, sometimes things get lost in the huge volume.
-
-What should you not do?
- - expect your patch to be accepted without question
- - become defensive
- - ignore comments
- - resubmit the patch without making any of the requested changes
-
-In a community that is looking for the best technical solution possible,
-there will always be differing opinions on how beneficial a patch is.
-You have to be cooperative, and willing to adapt your idea to fit within
-the kernel. Or at least be willing to prove your idea is worth it.
-Remember, being wrong is acceptable as long as you are willing to work
-toward a solution that is right.
-
-It is normal that the answers to your first patch might simply be a list
-of a dozen things you should correct. This does _not_ imply that your
-patch will not be accepted, and it is _not_ meant against you
-personally. Simply correct all issues raised against your patch and
-resend it.
-
-
-Differences between the kernel community and corporate structures
------------------------------------------------------------------
-
-The kernel community works differently than most traditional corporate
-development environments. Here are a list of things that you can try to
-do to avoid problems:
- Good things to say regarding your proposed changes:
- - "This solves multiple problems."
- - "This deletes 2000 lines of code."
- - "Here is a patch that explains what I am trying to describe."
- - "I tested it on 5 different architectures..."
- - "Here is a series of small patches that..."
- - "This increases performance on typical machines..."
-
- Bad things you should avoid saying:
- - "We did it this way in AIX/ptx/Solaris, so therefore it must be
- good..."
- - "I've being doing this for 20 years, so..."
- - "This is required for my company to make money"
- - "This is for our Enterprise product line."
- - "Here is my 1000 page design document that describes my idea"
- - "I've been working on this for 6 months..."
- - "Here's a 5000 line patch that..."
- - "I rewrote all of the current mess, and here it is..."
- - "I have a deadline, and this patch needs to be applied now."
-
-Another way the kernel community is different than most traditional
-software engineering work environments is the faceless nature of
-interaction. One benefit of using email and irc as the primary forms of
-communication is the lack of discrimination based on gender or race.
-The Linux kernel work environment is accepting of women and minorities
-because all you are is an email address. The international aspect also
-helps to level the playing field because you can't guess gender based on
-a person's name. A man may be named Andrea and a woman may be named Pat.
-Most women who have worked in the Linux kernel and have expressed an
-opinion have had positive experiences.
-
-The language barrier can cause problems for some people who are not
-comfortable with English. A good grasp of the language can be needed in
-order to get ideas across properly on mailing lists, so it is
-recommended that you check your emails to make sure they make sense in
-English before sending them.
-
-
-Break up your changes
----------------------
-
-The Linux kernel community does not gladly accept large chunks of code
-dropped on it all at once. The changes need to be properly introduced,
-discussed, and broken up into tiny, individual portions. This is almost
-the exact opposite of what companies are used to doing. Your proposal
-should also be introduced very early in the development process, so that
-you can receive feedback on what you are doing. It also lets the
-community feel that you are working with them, and not simply using them
-as a dumping ground for your feature. However, don't send 50 emails at
-one time to a mailing list, your patch series should be smaller than
-that almost all of the time.
-
-The reasons for breaking things up are the following:
-
-1) Small patches increase the likelihood that your patches will be
- applied, since they don't take much time or effort to verify for
- correctness. A 5 line patch can be applied by a maintainer with
- barely a second glance. However, a 500 line patch may take hours to
- review for correctness (the time it takes is exponentially
- proportional to the size of the patch, or something).
-
- Small patches also make it very easy to debug when something goes
- wrong. It's much easier to back out patches one by one than it is
- to dissect a very large patch after it's been applied (and broken
- something).
-
-2) It's important not only to send small patches, but also to rewrite
- and simplify (or simply re-order) patches before submitting them.
-
-Here is an analogy from kernel developer Al Viro:
- "Think of a teacher grading homework from a math student. The
- teacher does not want to see the student's trials and errors
- before they came up with the solution. They want to see the
- cleanest, most elegant answer. A good student knows this, and
- would never submit her intermediate work before the final
- solution."
-
- The same is true of kernel development. The maintainers and
- reviewers do not want to see the thought process behind the
- solution to the problem one is solving. They want to see a
- simple and elegant solution."
-
-It may be challenging to keep the balance between presenting an elegant
-solution and working together with the community and discussing your
-unfinished work. Therefore it is good to get early in the process to
-get feedback to improve your work, but also keep your changes in small
-chunks that they may get already accepted, even when your whole task is
-not ready for inclusion now.
-
-Also realize that it is not acceptable to send patches for inclusion
-that are unfinished and will be "fixed up later."
-
-
-Justify your change
--------------------
-
-Along with breaking up your patches, it is very important for you to let
-the Linux community know why they should add this change. New features
-must be justified as being needed and useful.
-
-
-Document your change
---------------------
-
-When sending in your patches, pay special attention to what you say in
-the text in your email. This information will become the ChangeLog
-information for the patch, and will be preserved for everyone to see for
-all time. It should describe the patch completely, containing:
- - why the change is necessary
- - the overall design approach in the patch
- - implementation details
- - testing results
-
-For more details on what this should all look like, please see the
-ChangeLog section of the document:
- "The Perfect Patch"
- http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-
-
-
-All of these things are sometimes very hard to do. It can take years to
-perfect these practices (if at all). It's a continuous process of
-improvement that requires a lot of patience and determination. But
-don't give up, it's possible. Many have done it before, and each had to
-start exactly where you are now.
-
-
-
-
-----------
-Thanks to Paolo Ciarrocchi who allowed the "Development Process"
-(http://lwn.net/Articles/94386/) section
-to be based on text he had written, and to Randy Dunlap and Gerrit
-Huizenga for some of the list of things you should and should not say.
-Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
-Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
-Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
-David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for
-their review, comments, and contributions. Without their help, this
-document would not have been possible.
-
-
-
-Maintainer: Greg Kroah-Hartman <greg@kroah.com>
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt
deleted file mode 100644
index 653d5d739d7f..000000000000
--- a/Documentation/IPMI.txt
+++ /dev/null
@@ -1,719 +0,0 @@
-
- The Linux IPMI Driver
- ---------------------
- Corey Minyard
- <minyard@mvista.com>
- <minyard@acm.org>
-
-The Intelligent Platform Management Interface, or IPMI, is a
-standard for controlling intelligent devices that monitor a system.
-It provides for dynamic discovery of sensors in the system and the
-ability to monitor the sensors and be informed when the sensor's
-values change or go outside certain boundaries. It also has a
-standardized database for field-replaceable units (FRUs) and a watchdog
-timer.
-
-To use this, you need an interface to an IPMI controller in your
-system (called a Baseboard Management Controller, or BMC) and
-management software that can use the IPMI system.
-
-This document describes how to use the IPMI driver for Linux. If you
-are not familiar with IPMI itself, see the web site at
-http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big
-subject and I can't cover it all here!
-
-Configuration
--------------
-
-The Linux IPMI driver is modular, which means you have to pick several
-things to have it work right depending on your hardware. Most of
-these are available in the 'Character Devices' menu then the IPMI
-menu.
-
-No matter what, you must pick 'IPMI top-level message handler' to use
-IPMI. What you do beyond that depends on your needs and hardware.
-
-The message handler does not provide any user-level interfaces.
-Kernel code (like the watchdog) can still use it. If you need access
-from userland, you need to select 'Device interface for IPMI' if you
-want access through a device driver.
-
-The driver interface depends on your hardware. If your system
-properly provides the SMBIOS info for IPMI, the driver will detect it
-and just work. If you have a board with a standard interface (These
-will generally be either "KCS", "SMIC", or "BT", consult your hardware
-manual), choose the 'IPMI SI handler' option. A driver also exists
-for direct I2C access to the IPMI management controller. Some boards
-support this, but it is unknown if it will work on every board. For
-this, choose 'IPMI SMBus handler', but be ready to try to do some
-figuring to see if it will work on your system if the SMBIOS/APCI
-information is wrong or not present. It is fairly safe to have both
-these enabled and let the drivers auto-detect what is present.
-
-You should generally enable ACPI on your system, as systems with IPMI
-can have ACPI tables describing them.
-
-If you have a standard interface and the board manufacturer has done
-their job correctly, the IPMI controller should be automatically
-detected (via ACPI or SMBIOS tables) and should just work. Sadly,
-many boards do not have this information. The driver attempts
-standard defaults, but they may not work. If you fall into this
-situation, you need to read the section below named 'The SI Driver' or
-"The SMBus Driver" on how to hand-configure your system.
-
-IPMI defines a standard watchdog timer. You can enable this with the
-'IPMI Watchdog Timer' config option. If you compile the driver into
-the kernel, then via a kernel command-line option you can have the
-watchdog timer start as soon as it initializes. It also have a lot
-of other options, see the 'Watchdog' section below for more details.
-Note that you can also have the watchdog continue to run if it is
-closed (by default it is disabled on close). Go into the 'Watchdog
-Cards' menu, enable 'Watchdog Timer Support', and enable the option
-'Disable watchdog shutdown on close'.
-
-IPMI systems can often be powered off using IPMI commands. Select
-'IPMI Poweroff' to do this. The driver will auto-detect if the system
-can be powered off by IPMI. It is safe to enable this even if your
-system doesn't support this option. This works on ATCA systems, the
-Radisys CPI1 card, and any IPMI system that supports standard chassis
-management commands.
-
-If you want the driver to put an event into the event log on a panic,
-enable the 'Generate a panic event to all BMCs on a panic' option. If
-you want the whole panic string put into the event log using OEM
-events, enable the 'Generate OEM events containing the panic string'
-option.
-
-Basic Design
-------------
-
-The Linux IPMI driver is designed to be very modular and flexible, you
-only need to take the pieces you need and you can use it in many
-different ways. Because of that, it's broken into many chunks of
-code. These chunks (by module name) are:
-
-ipmi_msghandler - This is the central piece of software for the IPMI
-system. It handles all messages, message timing, and responses. The
-IPMI users tie into this, and the IPMI physical interfaces (called
-System Management Interfaces, or SMIs) also tie in here. This
-provides the kernelland interface for IPMI, but does not provide an
-interface for use by application processes.
-
-ipmi_devintf - This provides a userland IOCTL interface for the IPMI
-driver, each open file for this device ties in to the message handler
-as an IPMI user.
-
-ipmi_si - A driver for various system interfaces. This supports KCS,
-SMIC, and BT interfaces. Unless you have an SMBus interface or your
-own custom interface, you probably need to use this.
-
-ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the
-I2C kernel driver's SMBus interfaces to send and receive IPMI messages
-over the SMBus.
-
-ipmi_watchdog - IPMI requires systems to have a very capable watchdog
-timer. This driver implements the standard Linux watchdog timer
-interface on top of the IPMI message handler.
-
-ipmi_poweroff - Some systems support the ability to be turned off via
-IPMI commands.
-
-These are all individually selectable via configuration options.
-
-Note that the KCS-only interface has been removed. The af_ipmi driver
-is no longer supported and has been removed because it was impossible
-to do 32 bit emulation on 64-bit kernels with it.
-
-Much documentation for the interface is in the include files. The
-IPMI include files are:
-
-net/af_ipmi.h - Contains the socket interface.
-
-linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
-
-linux/ipmi_smi.h - Contains the interface for system management interfaces
-(things that interface to IPMI controllers) to use.
-
-linux/ipmi_msgdefs.h - General definitions for base IPMI messaging.
-
-
-Addressing
-----------
-
-The IPMI addressing works much like IP addresses, you have an overlay
-to handle the different address types. The overlay is:
-
- struct ipmi_addr
- {
- int addr_type;
- short channel;
- char data[IPMI_MAX_ADDR_SIZE];
- };
-
-The addr_type determines what the address really is. The driver
-currently understands two different types of addresses.
-
-"System Interface" addresses are defined as:
-
- struct ipmi_system_interface_addr
- {
- int addr_type;
- short channel;
- };
-
-and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking
-straight to the BMC on the current card. The channel must be
-IPMI_BMC_CHANNEL.
-
-Messages that are destined to go out on the IPMB bus use the
-IPMI_IPMB_ADDR_TYPE address type. The format is
-
- struct ipmi_ipmb_addr
- {
- int addr_type;
- short channel;
- unsigned char slave_addr;
- unsigned char lun;
- };
-
-The "channel" here is generally zero, but some devices support more
-than one channel, it corresponds to the channel as defined in the IPMI
-spec.
-
-
-Messages
---------
-
-Messages are defined as:
-
-struct ipmi_msg
-{
- unsigned char netfn;
- unsigned char lun;
- unsigned char cmd;
- unsigned char *data;
- int data_len;
-};
-
-The driver takes care of adding/stripping the header information. The
-data portion is just the data to be send (do NOT put addressing info
-here) or the response. Note that the completion code of a response is
-the first item in "data", it is not stripped out because that is how
-all the messages are defined in the spec (and thus makes counting the
-offsets a little easier :-).
-
-When using the IOCTL interface from userland, you must provide a block
-of data for "data", fill it, and set data_len to the length of the
-block of data, even when receiving messages. Otherwise the driver
-will have no place to put the message.
-
-Messages coming up from the message handler in kernelland will come in
-as:
-
- struct ipmi_recv_msg
- {
- struct list_head link;
-
- /* The type of message as defined in the "Receive Types"
- defines above. */
- int recv_type;
-
- ipmi_user_t *user;
- struct ipmi_addr addr;
- long msgid;
- struct ipmi_msg msg;
-
- /* Call this when done with the message. It will presumably free
- the message and do any other necessary cleanup. */
- void (*done)(struct ipmi_recv_msg *msg);
-
- /* Place-holder for the data, don't make any assumptions about
- the size or existence of this, since it may change. */
- unsigned char msg_data[IPMI_MAX_MSG_LENGTH];
- };
-
-You should look at the receive type and handle the message
-appropriately.
-
-
-The Upper Layer Interface (Message Handler)
--------------------------------------------
-
-The upper layer of the interface provides the users with a consistent
-view of the IPMI interfaces. It allows multiple SMI interfaces to be
-addressed (because some boards actually have multiple BMCs on them)
-and the user should not have to care what type of SMI is below them.
-
-
-Creating the User
-
-To user the message handler, you must first create a user using
-ipmi_create_user. The interface number specifies which SMI you want
-to connect to, and you must supply callback functions to be called
-when data comes in. The callback function can run at interrupt level,
-so be careful using the callbacks. This also allows to you pass in a
-piece of data, the handler_data, that will be passed back to you on
-all calls.
-
-Once you are done, call ipmi_destroy_user() to get rid of the user.
-
-From userland, opening the device automatically creates a user, and
-closing the device automatically destroys the user.
-
-
-Messaging
-
-To send a message from kernel-land, the ipmi_request() call does
-pretty much all message handling. Most of the parameter are
-self-explanatory. However, it takes a "msgid" parameter. This is NOT
-the sequence number of messages. It is simply a long value that is
-passed back when the response for the message is returned. You may
-use it for anything you like.
-
-Responses come back in the function pointed to by the ipmi_recv_hndl
-field of the "handler" that you passed in to ipmi_create_user().
-Remember again, these may be running at interrupt level. Remember to
-look at the receive type, too.
-
-From userland, you fill out an ipmi_req_t structure and use the
-IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select()
-or poll() to wait for messages to come in. However, you cannot use
-read() to get them, you must call the IPMICTL_RECEIVE_MSG with the
-ipmi_recv_t structure to actually get the message. Remember that you
-must supply a pointer to a block of data in the msg.data field, and
-you must fill in the msg.data_len field with the size of the data.
-This gives the receiver a place to actually put the message.
-
-If the message cannot fit into the data you provide, you will get an
-EMSGSIZE error and the driver will leave the data in the receive
-queue. If you want to get it and have it truncate the message, us
-the IPMICTL_RECEIVE_MSG_TRUNC ioctl.
-
-When you send a command (which is defined by the lowest-order bit of
-the netfn per the IPMI spec) on the IPMB bus, the driver will
-automatically assign the sequence number to the command and save the
-command. If the response is not receive in the IPMI-specified 5
-seconds, it will generate a response automatically saying the command
-timed out. If an unsolicited response comes in (if it was after 5
-seconds, for instance), that response will be ignored.
-
-In kernelland, after you receive a message and are done with it, you
-MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note
-that you should NEVER mess with the "done" field of a message, that is
-required to properly clean up the message.
-
-Note that when sending, there is an ipmi_request_supply_msgs() call
-that lets you supply the smi and receive message. This is useful for
-pieces of code that need to work even if the system is out of buffers
-(the watchdog timer uses this, for instance). You supply your own
-buffer and own free routines. This is not recommended for normal use,
-though, since it is tricky to manage your own buffers.
-
-
-Events and Incoming Commands
-
-The driver takes care of polling for IPMI events and receiving
-commands (commands are messages that are not responses, they are
-commands that other things on the IPMB bus have sent you). To receive
-these, you must register for them, they will not automatically be sent
-to you.
-
-To receive events, you must call ipmi_set_gets_events() and set the
-"val" to non-zero. Any events that have been received by the driver
-since startup will immediately be delivered to the first user that
-registers for events. After that, if multiple users are registered
-for events, they will all receive all events that come in.
-
-For receiving commands, you have to individually register commands you
-want to receive. Call ipmi_register_for_cmd() and supply the netfn
-and command name for each command you want to receive. You also
-specify a bitmask of the channels you want to receive the command from
-(or use IPMI_CHAN_ALL for all channels if you don't care). Only one
-user may be registered for each netfn/cmd/channel, but different users
-may register for different commands, or the same command if the
-channel bitmasks do not overlap.
-
-From userland, equivalent IOCTLs are provided to do these functions.
-
-
-The Lower Layer (SMI) Interface
--------------------------------
-
-As mentioned before, multiple SMI interfaces may be registered to the
-message handler, each of these is assigned an interface number when
-they register with the message handler. They are generally assigned
-in the order they register, although if an SMI unregisters and then
-another one registers, all bets are off.
-
-The ipmi_smi.h defines the interface for management interfaces, see
-that for more details.
-
-
-The SI Driver
--------------
-
-The SI driver allows up to 4 KCS or SMIC interfaces to be configured
-in the system. By default, scan the ACPI tables for interfaces, and
-if it doesn't find any the driver will attempt to register one KCS
-interface at the spec-specified I/O port 0xca2 without interrupts.
-You can change this at module load time (for a module) with:
-
- modprobe ipmi_si.o type=<type1>,<type2>....
- ports=<port1>,<port2>... addrs=<addr1>,<addr2>...
- irqs=<irq1>,<irq2>...
- regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,...
- regshifts=<shift1>,<shift2>,...
- slave_addrs=<addr1>,<addr2>,...
- force_kipmid=<enable1>,<enable2>,...
- kipmid_max_busy_us=<ustime1>,<ustime2>,...
- unload_when_empty=[0|1]
- trydefaults=[0|1] trydmi=[0|1] tryacpi=[0|1]
- tryplatform=[0|1] trypci=[0|1]
-
-Each of these except try... items is a list, the first item for the
-first interface, second item for the second interface, etc.
-
-The si_type may be either "kcs", "smic", or "bt". If you leave it blank, it
-defaults to "kcs".
-
-If you specify addrs as non-zero for an interface, the driver will
-use the memory address given as the address of the device. This
-overrides si_ports.
-
-If you specify ports as non-zero for an interface, the driver will
-use the I/O port given as the device address.
-
-If you specify irqs as non-zero for an interface, the driver will
-attempt to use the given interrupt for the device.
-
-trydefaults sets whether the standard IPMI interface at 0xca2 and
-any interfaces specified by ACPE are tried. By default, the driver
-tries it, set this value to zero to turn this off.
-
-The other try... items disable discovery by their corresponding
-names. These are all enabled by default, set them to zero to disable
-them. The tryplatform disables openfirmware.
-
-The next three parameters have to do with register layout. The
-registers used by the interfaces may not appear at successive
-locations and they may not be in 8-bit registers. These parameters
-allow the layout of the data in the registers to be more precisely
-specified.
-
-The regspacings parameter give the number of bytes between successive
-register start addresses. For instance, if the regspacing is set to 4
-and the start address is 0xca2, then the address for the second
-register would be 0xca6. This defaults to 1.
-
-The regsizes parameter gives the size of a register, in bytes. The
-data used by IPMI is 8-bits wide, but it may be inside a larger
-register. This parameter allows the read and write type to specified.
-It may be 1, 2, 4, or 8. The default is 1.
-
-Since the register size may be larger than 32 bits, the IPMI data may not
-be in the lower 8 bits. The regshifts parameter give the amount to shift
-the data to get to the actual IPMI data.
-
-The slave_addrs specifies the IPMI address of the local BMC. This is
-usually 0x20 and the driver defaults to that, but in case it's not, it
-can be specified when the driver starts up.
-
-The force_ipmid parameter forcefully enables (if set to 1) or disables
-(if set to 0) the kernel IPMI daemon. Normally this is auto-detected
-by the driver, but systems with broken interrupts might need an enable,
-or users that don't want the daemon (don't need the performance, don't
-want the CPU hit) can disable it.
-
-If unload_when_empty is set to 1, the driver will be unloaded if it
-doesn't find any interfaces or all the interfaces fail to work. The
-default is one. Setting to 0 is useful with the hotmod, but is
-obviously only useful for modules.
-
-When compiled into the kernel, the parameters can be specified on the
-kernel command line as:
-
- ipmi_si.type=<type1>,<type2>...
- ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>...
- ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.trydefaults=[0|1]
- ipmi_si.regspacings=<sp1>,<sp2>,...
- ipmi_si.regsizes=<size1>,<size2>,...
- ipmi_si.regshifts=<shift1>,<shift2>,...
- ipmi_si.slave_addrs=<addr1>,<addr2>,...
- ipmi_si.force_kipmid=<enable1>,<enable2>,...
- ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,...
-
-It works the same as the module parameters of the same names.
-
-By default, the driver will attempt to detect any device specified by
-ACPI, and if none of those then a KCS device at the spec-specified
-0xca2. If you want to turn this off, set the "trydefaults" option to
-false.
-
-If your IPMI interface does not support interrupts and is a KCS or
-SMIC interface, the IPMI driver will start a kernel thread for the
-interface to help speed things up. This is a low-priority kernel
-thread that constantly polls the IPMI driver while an IPMI operation
-is in progress. The force_kipmid module parameter will all the user to
-force this thread on or off. If you force it off and don't have
-interrupts, the driver will run VERY slowly. Don't blame me,
-these interfaces suck.
-
-Unfortunately, this thread can use a lot of CPU depending on the
-interface's performance. This can waste a lot of CPU and cause
-various issues with detecting idle CPU and using extra power. To
-avoid this, the kipmid_max_busy_us sets the maximum amount of time, in
-microseconds, that kipmid will spin before sleeping for a tick. This
-value sets a balance between performance and CPU waste and needs to be
-tuned to your needs. Maybe, someday, auto-tuning will be added, but
-that's not a simple thing and even the auto-tuning would need to be
-tuned to the user's desired performance.
-
-The driver supports a hot add and remove of interfaces. This way,
-interfaces can be added or removed after the kernel is up and running.
-This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a
-write-only parameter. You write a string to this interface. The string
-has the format:
- <op1>[:op2[:op3...]]
-The "op"s are:
- add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]]
-You can specify more than one interface on the line. The "opt"s are:
- rsp=<regspacing>
- rsi=<regsize>
- rsh=<regshift>
- irq=<irq>
- ipmb=<ipmb slave addr>
-and these have the same meanings as discussed above. Note that you
-can also use this on the kernel command line for a more compact format
-for specifying an interface. Note that when removing an interface,
-only the first three parameters (si type, address type, and address)
-are used for the comparison. Any options are ignored for removing.
-
-The SMBus Driver (SSIF)
------------------------
-
-The SMBus driver allows up to 4 SMBus devices to be configured in the
-system. By default, the driver will only register with something it
-finds in DMI or ACPI tables. You can change this
-at module load time (for a module) with:
-
- modprobe ipmi_ssif.o
- addr=<i2caddr1>[,<i2caddr2>[,...]]
- adapter=<adapter1>[,<adapter2>[...]]
- dbg=<flags1>,<flags2>...
- slave_addrs=<addr1>,<addr2>,...
- [dbg_probe=1]
-
-The addresses are normal I2C addresses. The adapter is the string
-name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name.
-It is *NOT* i2c-<n> itself.
-
-The debug flags are bit flags for each BMC found, they are:
-IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8
-
-Setting dbg_probe to 1 will enable debugging of the probing and
-detection process for BMCs on the SMBusses.
-
-The slave_addrs specifies the IPMI address of the local BMC. This is
-usually 0x20 and the driver defaults to that, but in case it's not, it
-can be specified when the driver starts up.
-
-Discovering the IPMI compliant BMC on the SMBus can cause devices on
-the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI
-message as a block write to the I2C bus and waits for a response.
-This action can be detrimental to some I2C devices. It is highly
-recommended that the known I2C address be given to the SMBus driver in
-the smb_addr parameter unless you have DMI or ACPI data to tell the
-driver what to use.
-
-When compiled into the kernel, the addresses can be specified on the
-kernel command line as:
-
- ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]]
- ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]]
- ipmi_ssif.dbg=<flags1>[,<flags2>[...]]
- ipmi_ssif.dbg_probe=1
- ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]]
-
-These are the same options as on the module command line.
-
-The I2C driver does not support non-blocking access or polling, so
-this driver cannod to IPMI panic events, extend the watchdog at panic
-time, or other panic-related IPMI functions without special kernel
-patches and driver modifications. You can get those at the openipmi
-web page.
-
-The driver supports a hot add and remove of interfaces through the I2C
-sysfs interface.
-
-Other Pieces
-------------
-
-Get the detailed info related with the IPMI device
---------------------------------------------------
-
-Some users need more detailed information about a device, like where
-the address came from or the raw base device for the IPMI interface.
-You can use the IPMI smi_watcher to catch the IPMI interfaces as they
-come or go, and to grab the information, you can use the function
-ipmi_get_smi_info(), which returns the following structure:
-
-struct ipmi_smi_info {
- enum ipmi_addr_src addr_src;
- struct device *dev;
- union {
- struct {
- void *acpi_handle;
- } acpi_info;
- } addr_info;
-};
-
-Currently special info for only for SI_ACPI address sources is
-returned. Others may be added as necessary.
-
-Note that the dev pointer is included in the above structure, and
-assuming ipmi_smi_get_info returns success, you must call put_device
-on the dev pointer.
-
-
-Watchdog
---------
-
-A watchdog timer is provided that implements the Linux-standard
-watchdog timer interface. It has three module parameters that can be
-used to control it:
-
- modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type>
- preaction=<preaction type> preop=<preop type> start_now=x
- nowayout=x ifnum_to_use=n
-
-ifnum_to_use specifies which interface the watchdog timer should use.
-The default is -1, which means to pick the first one registered.
-
-The timeout is the number of seconds to the action, and the pretimeout
-is the amount of seconds before the reset that the pre-timeout panic will
-occur (if pretimeout is zero, then pretimeout will not be enabled). Note
-that the pretimeout is the time before the final timeout. So if the
-timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout
-will occur in 40 second (10 seconds before the timeout).
-
-The action may be "reset", "power_cycle", or "power_off", and
-specifies what to do when the timer times out, and defaults to
-"reset".
-
-The preaction may be "pre_smi" for an indication through the SMI
-interface, "pre_int" for an indication through the SMI with an
-interrupts, and "pre_nmi" for a NMI on a preaction. This is how
-the driver is informed of the pretimeout.
-
-The preop may be set to "preop_none" for no operation on a pretimeout,
-"preop_panic" to set the preoperation to panic, or "preop_give_data"
-to provide data to read from the watchdog device when the pretimeout
-occurs. A "pre_nmi" setting CANNOT be used with "preop_give_data"
-because you can't do data operations from an NMI.
-
-When preop is set to "preop_give_data", one byte comes ready to read
-on the device when the pretimeout occurs. Select and fasync work on
-the device, as well.
-
-If start_now is set to 1, the watchdog timer will start running as
-soon as the driver is loaded.
-
-If nowayout is set to 1, the watchdog timer will not stop when the
-watchdog device is closed. The default value of nowayout is true
-if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not.
-
-When compiled into the kernel, the kernel command line is available
-for configuring the watchdog:
-
- ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t>
- ipmi_watchdog.action=<action type>
- ipmi_watchdog.preaction=<preaction type>
- ipmi_watchdog.preop=<preop type>
- ipmi_watchdog.start_now=x
- ipmi_watchdog.nowayout=x
-
-The options are the same as the module parameter options.
-
-The watchdog will panic and start a 120 second reset timeout if it
-gets a pre-action. During a panic or a reboot, the watchdog will
-start a 120 timer if it is running to make sure the reboot occurs.
-
-Note that if you use the NMI preaction for the watchdog, you MUST NOT
-use the nmi watchdog. There is no reasonable way to tell if an NMI
-comes from the IPMI controller, so it must assume that if it gets an
-otherwise unhandled NMI, it must be from IPMI and it will panic
-immediately.
-
-Once you open the watchdog timer, you must write a 'V' character to the
-device to close it, or the timer will not stop. This is a new semantic
-for the driver, but makes it consistent with the rest of the watchdog
-drivers in Linux.
-
-
-Panic Timeouts
---------------
-
-The OpenIPMI driver supports the ability to put semi-custom and custom
-events in the system event log if a panic occurs. if you enable the
-'Generate a panic event to all BMCs on a panic' option, you will get
-one event on a panic in a standard IPMI event format. If you enable
-the 'Generate OEM events containing the panic string' option, you will
-also get a bunch of OEM events holding the panic string.
-
-
-The field settings of the events are:
-* Generator ID: 0x21 (kernel)
-* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format)
-* Sensor Type: 0x20 (OS critical stop sensor)
-* Sensor #: The first byte of the panic string (0 if no panic string)
-* Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info)
-* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3)
-* Event data 2: second byte of panic string
-* Event data 3: third byte of panic string
-See the IPMI spec for the details of the event layout. This event is
-always sent to the local management controller. It will handle routing
-the message to the right place
-
-Other OEM events have the following format:
-Record ID (bytes 0-1): Set by the SEL.
-Record type (byte 2): 0xf0 (OEM non-timestamped)
-byte 3: The slave address of the card saving the panic
-byte 4: A sequence number (starting at zero)
-The rest of the bytes (11 bytes) are the panic string. If the panic string
-is longer than 11 bytes, multiple messages will be sent with increasing
-sequence numbers.
-
-Because you cannot send OEM events using the standard interface, this
-function will attempt to find an SEL and add the events there. It
-will first query the capabilities of the local management controller.
-If it has an SEL, then they will be stored in the SEL of the local
-management controller. If not, and the local management controller is
-an event generator, the event receiver from the local management
-controller will be queried and the events sent to the SEL on that
-device. Otherwise, the events go nowhere since there is nowhere to
-send them.
-
-
-Poweroff
---------
-
-If the poweroff capability is selected, the IPMI driver will install
-a shutdown function into the standard poweroff function pointer. This
-is in the ipmi_poweroff module. When the system requests a powerdown,
-it will send the proper IPMI commands to do this. This is supported on
-several platforms.
-
-There is a module parameter named "poweroff_powercycle" that may
-either be zero (do a power down) or non-zero (do a power cycle, power
-the system off, then power it on in a few seconds). Setting
-ipmi_poweroff.poweroff_control=x will do the same thing on the kernel
-command line. The parameter is also available via the proc filesystem
-in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system
-does not support power cycling, it will always do the power off.
-
-The "ifnum_to_use" parameter specifies which interface the poweroff
-code should use. The default is -1, which means to pick the first one
-registered.
-
-Note that if you have ACPI enabled, the system will prefer using ACPI to
-power off.
diff --git a/Documentation/IRQ-affinity.txt b/Documentation/IRQ-affinity.txt
deleted file mode 100644
index 01a675175a36..000000000000
--- a/Documentation/IRQ-affinity.txt
+++ /dev/null
@@ -1,65 +0,0 @@
-ChangeLog:
- Started by Ingo Molnar <mingo@redhat.com>
- Update by Max Krasnyansky <maxk@qualcomm.com>
-
-SMP IRQ affinity
-
-/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
-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.
-
-/proc/irq/default_smp_affinity specifies default affinity mask that applies
-to all non-active IRQs. Once IRQ is allocated/activated its affinity bitmask
-will be set to the default mask. It can then be changed as described above.
-Default mask is 0xffffffff.
-
-Here is an example of restricting IRQ44 (eth1) to CPU0-3 then restricting
-it to CPU4-7 (this is an 8-CPU SMP box):
-
-[root@moon 44]# cd /proc/irq/44
-[root@moon 44]# cat smp_affinity
-ffffffff
-
-[root@moon 44]# echo 0f > smp_affinity
-[root@moon 44]# cat smp_affinity
-0000000f
-[root@moon 44]# ping -f h
-PING hell (195.4.7.3): 56 data bytes
-...
---- hell ping statistics ---
-6029 packets transmitted, 6027 packets received, 0% packet loss
-round-trip min/avg/max = 0.1/0.1/0.4 ms
-[root@moon 44]# cat /proc/interrupts | grep 'CPU\|44:'
- CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7
- 44: 1068 1785 1785 1783 0 0 0 0 IO-APIC-level eth1
-
-As can be seen from the line above IRQ44 was delivered only to the first four
-processors (0-3).
-Now lets restrict that IRQ to CPU(4-7).
-
-[root@moon 44]# echo f0 > smp_affinity
-[root@moon 44]# cat smp_affinity
-000000f0
-[root@moon 44]# ping -f h
-PING hell (195.4.7.3): 56 data bytes
-..
---- hell ping statistics ---
-2779 packets transmitted, 2777 packets received, 0% packet loss
-round-trip min/avg/max = 0.1/0.5/585.4 ms
-[root@moon 44]# cat /proc/interrupts | 'CPU\|44:'
- CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7
- 44: 1068 1785 1785 1783 1784 1069 1070 1069 IO-APIC-level eth1
-
-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:
-
-[root@moon 44]# echo 1024-1031 > smp_affinity_list
-[root@moon 44]# cat smp_affinity_list
-1024-1031
-
-Note that to do this with a bitmask would require 32 bitmasks of zero
-to follow the pertinent one.
diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt
deleted file mode 100644
index 3a8e15cba816..000000000000
--- a/Documentation/IRQ-domain.txt
+++ /dev/null
@@ -1,223 +0,0 @@
-irq_domain interrupt number mapping library
-
-The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
-that each one gets assigned non-overlapping allocations of Linux
-IRQ numbers.
-
-The number of interrupt controllers registered as unique irqchips
-show a rising tendency: for example subdrivers of different kinds
-such as GPIO controllers avoid reimplementing identical callback
-mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
-
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
-
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
-
-The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
-irq numbers, but they don't provide any support for reverse mapping of
-the controller-local IRQ (hwirq) number into the Linux IRQ number
-space.
-
-The irq_domain library adds mapping between hwirq and IRQ numbers on
-top of the irq_alloc_desc*() API. An irq_domain to manage mapping is
-preferred over interrupt controller drivers open coding their own
-reverse mapping scheme.
-
-irq_domain also implements translation from Device Tree interrupt
-specifiers to hwirq numbers, and can be easily extended to support
-other IRQ topology data sources.
-
-=== irq_domain usage ===
-An interrupt controller driver creates and registers an irq_domain by
-calling one of the irq_domain_add_*() functions (each mapping method
-has a different allocator function, more on that later). The function
-will return a pointer to the irq_domain on success. The caller must
-provide the allocator function with an irq_domain_ops structure.
-
-In most cases, the irq_domain will begin empty without any mappings
-between hwirq and IRQ numbers. Mappings are added to the irq_domain
-by calling irq_create_mapping() which accepts the irq_domain and a
-hwirq number as arguments. If a mapping for the hwirq doesn't already
-exist then it will allocate a new Linux irq_desc, associate it with
-the hwirq, and call the .map() callback so the driver can perform any
-required hardware setup.
-
-When an interrupt is received, irq_find_mapping() function should
-be used to find the Linux IRQ number from the hwirq number.
-
-The irq_create_mapping() function must be called *atleast once*
-before any call to irq_find_mapping(), lest the descriptor will not
-be allocated.
-
-If the driver has the Linux IRQ number or the irq_data pointer, and
-needs to know the associated hwirq number (such as in the irq_chip
-callbacks) then it can be directly obtained from irq_data->hwirq.
-
-=== 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.
-Which reverse map type should be used depends on the use case. Each
-of the reverse map types are described below:
-
-==== Linear ====
-irq_domain_add_linear()
-
-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
-allocated for in-use IRQs. The disadvantage is that the table must be
-as large as the largest possible hwirq number.
-
-The majority of drivers should use the linear map.
-
-==== Tree ====
-irq_domain_add_tree()
-
-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
-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.
-
-Very few drivers should need this mapping.
-
-==== No Map ===-
-irq_domain_add_nomap()
-
-The No Map mapping is to be used when the hwirq number is
-programmable in the hardware. In this case it is best to program the
-Linux IRQ number into the hardware itself so that no mapping is
-required. Calling irq_create_direct_mapping() will allocate a Linux
-IRQ number and call the .map() callback so that driver can program the
-Linux IRQ number into the hardware.
-
-Most drivers cannot use this mapping.
-
-==== Legacy ====
-irq_domain_add_simple()
-irq_domain_add_legacy()
-irq_domain_add_legacy_isa()
-
-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
-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
-mapping should be used.
-
-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
-mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ
-numbers.
-
-Most users of legacy mappings should use irq_domain_add_simple() 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_add_linear() which means
-*no* irq descriptors will be allocated.
-
-A typical use case for simple domains is where an irqchip provider
-is supporting both dynamic and static IRQ assignments.
-
-In order to avoid ending up in a situation where a linear domain is
-used and no descriptor gets allocated it is very important to make sure
-that the driver using the simple domain call irq_create_mapping()
-before any irq_find_mapping() since the latter will actually work
-for the static IRQ assignment case.
-
-==== 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:
-
-Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
-
-There are three interrupt controllers involved:
-1) IOAPIC controller
-2) Interrupt remapping controller
-3) Local APIC controller
-
-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
-as below will be built for the example above.
- CPU Vector irq_domain (root irq_domain to manage CPU vectors)
- ^
- |
- Interrupt Remapping irq_domain (manage irq_remapping entries)
- ^
- |
- IOAPIC irq_domain (manage IOAPIC delivery entries/pins)
-
-There are four major interfaces to use hierarchy irq_domain:
-1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt
- controller related resources to deliver these interrupts.
-2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller
- related resources associated with these interrupts.
-3) irq_domain_activate_irq(): activate interrupt controller hardware to
- deliver the interrupt.
-3) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
- to stop delivering the interrupt.
-
-Following changes are needed to support hierarchy irq_domain.
-1) a new field 'parent' is added to struct irq_domain; it's used to
- maintain irq_domain hierarchy information.
-2) a new field 'parent_data' is added to struct irq_data; it's used to
- build hierarchy irq_data to match hierarchy irq_domains. The irq_data
- is used to store irq_domain pointer and hardware irq number.
-3) new callbacks are added to struct irq_domain_ops to support hierarchy
- irq_domain operations.
-
-With support of hierarchy irq_domain and hierarchy irq_data ready, an
-irq_domain structure is built for each interrupt controller, and an
-irq_data structure is allocated for each irq_domain associated with an
-IRQ. Now we could go one step further to support stacked(hierarchy)
-irq_chip. That is, an irq_chip is associated with each irq_data along
-the hierarchy. A child irq_chip may implement a required action by
-itself or by cooperating with its parent irq_chip.
-
-With stacked irq_chip, interrupt controller driver only needs to deal
-with the hardware managed by itself and may ask for services from its
-parent irq_chip when needed. So we could achieve a much cleaner
-software architecture.
-
-For an interrupt controller driver to support hierarchy irq_domain, it
-needs to:
-1) Implement irq_domain_ops.alloc and irq_domain_ops.free
-2) Optionally implement irq_domain_ops.activate and
- irq_domain_ops.deactivate.
-3) Optionally implement an irq_chip to manage the interrupt controller
- hardware.
-4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,
- they are unused with hierarchy irq_domain.
-
-Hierarchy irq_domain may also be used to support other architectures,
-such as ARM, ARM64 etc.
diff --git a/Documentation/IRQ.txt b/Documentation/IRQ.txt
deleted file mode 100644
index 1011e7175021..000000000000
--- a/Documentation/IRQ.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-What is an IRQ?
-
-An IRQ is an interrupt request from a device.
-Currently they can come in over a pin, or over a packet.
-Several devices may be connected to the same pin thus
-sharing an IRQ.
-
-An IRQ number is a kernel identifier used to talk about a hardware
-interrupt source. Typically this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements the details
-are architecture specific.
-
-An IRQ number is an enumeration of the possible interrupt sources on a
-machine. Typically what is enumerated is the number of input pins on
-all of the interrupt controller in the system. In the case of ISA
-what is enumerated are the 16 input pins on the two i8259 interrupt
-controllers.
-
-Architectures can assign additional meaning to the IRQ numbers, and
-are encouraged to in the case where there is any manual configuration
-of the hardware involved. The ISA IRQs are a classic example of
-assigning this kind of additional meaning.
diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt
deleted file mode 100644
index cf9431db8731..000000000000
--- a/Documentation/Intel-IOMMU.txt
+++ /dev/null
@@ -1,111 +0,0 @@
-Linux IOMMU Support
-===================
-
-The architecture spec can be obtained from the below location.
-
-http://www.intel.com/technology/virtualization/
-
-This guide gives a quick cheat sheet for some basic understanding.
-
-Some Keywords
-
-DMAR - DMA remapping
-DRHD - DMA Engine Reporting Structure
-RMRR - Reserved memory Region Reporting Structure
-ZLR - Zero length reads from PCI devices
-IOVA - IO Virtual address.
-
-Basic stuff
------------
-
-ACPI enumerates and lists the different DMA engines in the platform, and
-device scope relationships between PCI devices and which DMA engine controls
-them.
-
-What is RMRR?
--------------
-
-There are some devices the BIOS controls, for e.g USB devices to perform
-PS2 emulation. The regions of memory used for these devices are marked
-reserved in the e820 map. When we turn on DMA translation, DMA to those
-regions will fail. Hence BIOS uses RMRR to specify these regions along with
-devices that need to access these regions. OS is expected to setup
-unity mappings for these regions for these devices to access these regions.
-
-How is IOVA generated?
----------------------
-
-Well behaved drivers call pci_map_*() calls before sending command to device
-that needs to perform DMA. Once DMA is completed and mapping is no longer
-required, device performs a pci_unmap_*() calls to unmap the region.
-
-The Intel IOMMU driver allocates a virtual address per domain. Each PCIE
-device has its own domain (hence protection). Devices under p2p bridges
-share the virtual address with all devices under the p2p bridge due to
-transaction id aliasing for p2p bridges.
-
-IOVA generation is pretty generic. We used the same technique as vmalloc()
-but these are not global address spaces, but separate for each domain.
-Different DMA engines may support different number of domains.
-
-We also allocate guard pages with each mapping, so we can attempt to catch
-any overflow that might happen.
-
-
-Graphics Problems?
-------------------
-If you encounter issues with graphics devices, you can try adding
-option intel_iommu=igfx_off to turn off the integrated graphics engine.
-If this fixes anything, please ensure you file a bug reporting the problem.
-
-Some exceptions to IOVA
------------------------
-Interrupt ranges are not address translated, (0xfee00000 - 0xfeefffff).
-The same is true for peer to peer transactions. Hence we reserve the
-address from PCI MMIO ranges so they are not allocated for IOVA addresses.
-
-
-Fault reporting
----------------
-When errors are reported, the DMA engine signals via an interrupt. The fault
-reason and device that caused it with fault reason is printed on console.
-
-See below for sample.
-
-
-Boot Message Sample
--------------------
-
-Something like this gets printed indicating presence of DMAR tables
-in ACPI.
-
-ACPI: DMAR (v001 A M I OEMDMAR 0x00000001 MSFT 0x00000097) @ 0x000000007f5b5ef0
-
-When DMAR is being processed and initialized by ACPI, prints DMAR locations
-and any RMRR's processed.
-
-ACPI DMAR:Host address width 36
-ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed90000
-ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed91000
-ACPI DMAR:DRHD (flags: 0x00000001)base: 0x00000000fed93000
-ACPI DMAR:RMRR base: 0x00000000000ed000 end: 0x00000000000effff
-ACPI DMAR:RMRR base: 0x000000007f600000 end: 0x000000007fffffff
-
-When DMAR is enabled for use, you will notice..
-
-PCI-DMA: Using DMAR IOMMU
-
-Fault reporting
----------------
-
-DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
-DMAR:[fault reason 05] PTE Write access is not set
-DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
-DMAR:[fault reason 05] PTE Write access is not set
-
-TBD
-----
-
-- For compatibility testing, could use unity map domain for all devices, just
- provide a 1-1 for all useful memory under a single domain for all devices.
-- API for paravirt ops for abstracting functionality for VMM folks.
diff --git a/Documentation/Kconfig b/Documentation/Kconfig
new file mode 100644
index 000000000000..8b6c4b84b218
--- /dev/null
+++ b/Documentation/Kconfig
@@ -0,0 +1,28 @@
+if COMPILE_TEST
+
+menu "Documentation"
+
+config WARN_MISSING_DOCUMENTS
+ bool "Warn if there's a missing documentation file"
+ help
+ It is not uncommon that a document gets renamed.
+ This option makes the Kernel to check for missing dependencies,
+ warning when something is missing. Works only if the Kernel
+ is built from a git tree.
+
+ If unsure, select 'N'.
+
+config WARN_ABI_ERRORS
+ bool "Warn if there are errors at ABI files"
+ help
+ The files under Documentation/ABI should follow what's
+ described at Documentation/ABI/README. Yet, as they're manually
+ written, it would be possible that some of those files would
+ have errors that would break them for being parsed by
+ tools/docs/get_abi.py. Add a check to verify them.
+
+ If unsure, select 'N'.
+
+endmenu
+
+endif
diff --git a/Documentation/Makefile b/Documentation/Makefile
index bc0548201755..e96ac6dcac4f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,4 +1,114 @@
-subdir-y := accounting auxdisplay blackfin connector \
- filesystems filesystems ia64 laptops mic misc-devices \
- networking pcmcia prctl ptp spi timers vDSO video4linux \
- watchdog
+# -*- makefile -*-
+# Makefile for Sphinx documentation
+#
+
+# for cleaning
+subdir- := devicetree/bindings
+
+ifneq ($(MAKECMDGOALS),cleandocs)
+# Check for broken documentation file references
+ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
+$(shell $(srctree)/tools/docs/documentation-file-ref-check --warn)
+endif
+
+# Check for broken ABI files
+ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
+$(shell $(srctree)/tools/docs/get_abi.py --dir $(srctree)/Documentation/ABI validate)
+endif
+endif
+
+# You can set these variables from the command line.
+SPHINXBUILD = sphinx-build
+SPHINXOPTS =
+SPHINXDIRS = .
+DOCS_THEME =
+DOCS_CSS =
+RUSTDOC =
+PAPER =
+BUILDDIR = $(obj)/output
+PDFLATEX = xelatex
+LATEXOPTS = -interaction=batchmode -no-shell-escape
+
+PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__)
+
+# Wrapper for sphinx-build
+
+BUILD_WRAPPER = $(srctree)/tools/docs/sphinx-build-wrapper
+
+# For denylisting "variable font" files
+# Can be overridden by setting as an env variable
+FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf
+
+# User-friendly check for sphinx-build
+HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
+
+ifeq ($(HAVE_SPHINX),0)
+
+.DEFAULT:
+ $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
+ @echo
+ @$(srctree)/tools/docs/sphinx-pre-install
+ @echo " SKIP Sphinx $@ target."
+
+else # HAVE_SPHINX
+
+# Common documentation targets
+htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
+ $(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
+ $(srctree)/tools/docs/sphinx-pre-install --version-check
+ +$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
+ $(PYTHON3) $(BUILD_WRAPPER) $@ \
+ --sphinxdirs="$(SPHINXDIRS)" $(RUSTDOC) \
+ --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
+ --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)
+
+
+endif
+
+# The following targets are independent of HAVE_SPHINX, and the rules should
+# work or silently pass without Sphinx.
+
+htmldocs-redirects: $(srctree)/Documentation/.renames.txt
+ @tools/docs/gen-redirects.py --output $(BUILDDIR) < $<
+
+refcheckdocs:
+ $(Q)cd $(srctree); tools/docs/documentation-file-ref-check
+
+cleandocs:
+ $(Q)rm -rf $(BUILDDIR)
+
+# Used only on help
+_SPHINXDIRS = $(shell printf "%s\n" $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)) | sort -f)
+
+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 ' mandocs - Man pages'
+ @echo ' latexdocs - LaTeX'
+ @echo ' pdfdocs - PDF'
+ @echo ' epubdocs - EPUB'
+ @echo ' xmldocs - XML'
+ @echo ' linkcheckdocs - check for broken external links'
+ @echo ' (will connect to external hosts)'
+ @echo ' refcheckdocs - check for references to non-existing files under'
+ @echo ' Documentation'
+ @echo ' cleandocs - clean all generated files'
+ @echo
+ @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
+ @echo ' top level values for SPHINXDIRS are: $(_SPHINXDIRS)'
+ @echo ' you may also use a subdirectory like SPHINXDIRS=userspace-api/media,'
+ @echo ' provided that there is an index.rst file at the subdirectory.'
+ @echo
+ @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
+ @echo
+ @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'
+ @echo
+ @echo ' make PAPER={a4|letter} Specifies the paper size used for LaTeX/PDF output.'
+ @echo
+ @echo ' make FONTS_CONF_DENY_VF={path} sets a deny list to block variable Noto CJK fonts'
+ @echo ' for PDF build. See tools/lib/python/kdoc/latex_fonts.py for more details'
+ @echo
+ @echo ' Default location for the generated documents is Documentation/output'
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle
deleted file mode 100644
index a211ee8d8b44..000000000000
--- a/Documentation/ManagementStyle
+++ /dev/null
@@ -1,276 +0,0 @@
-
- Linux kernel management style
-
-This is a short document describing the preferred (or made up, depending
-on who you ask) management style for the linux kernel. It's meant to
-mirror the CodingStyle document to some degree, and mainly written to
-avoid answering (*) the same (or similar) questions over and over again.
-
-Management style is very personal and much harder to quantify than
-simple coding style rules, so this document may or may not have anything
-to do with reality. It started as a lark, but that doesn't mean that it
-might not actually be true. You'll have to decide for yourself.
-
-Btw, when talking about "kernel manager", it's all about the technical
-lead persons, not the people who do traditional management inside
-companies. If you sign purchase orders or you have any clue about the
-budget of your group, you're almost certainly not a kernel manager.
-These suggestions may or may not apply to you.
-
-First off, I'd suggest buying "Seven Habits of Highly Effective
-People", and NOT read it. Burn it, it's a great symbolic gesture.
-
-(*) This document does so not so much by answering the question, but by
-making it painfully obvious to the questioner that we don't have a clue
-to what the answer is.
-
-Anyway, here goes:
-
-
- Chapter 1: Decisions
-
-Everybody thinks managers make decisions, and that decision-making is
-important. The bigger and more painful the decision, the bigger the
-manager must be to make it. That's very deep and obvious, but it's not
-actually true.
-
-The name of the game is to _avoid_ having to make a decision. In
-particular, if somebody tells you "choose (a) or (b), we really need you
-to decide on this", you're in trouble as a manager. The people you
-manage had better know the details better than you, so if they come to
-you for a technical decision, you're screwed. You're clearly not
-competent to make that decision for them.
-
-(Corollary:if the people you manage don't know the details better than
-you, you're also screwed, although for a totally different reason.
-Namely that you are in the wrong job, and that _they_ should be managing
-your brilliance instead).
-
-So the name of the game is to _avoid_ decisions, at least the big and
-painful ones. Making small and non-consequential decisions is fine, and
-makes you look like you know what you're doing, so what a kernel manager
-needs to do is to turn the big and painful ones into small things where
-nobody really cares.
-
-It helps to realize that the key difference between a big decision and a
-small one is whether you can fix your decision afterwards. Any decision
-can be made small by just always making sure that if you were wrong (and
-you _will_ be wrong), you can always undo the damage later by
-backtracking. Suddenly, you get to be doubly managerial for making
-_two_ inconsequential decisions - the wrong one _and_ the right one.
-
-And people will even see that as true leadership (*cough* bullshit
-*cough*).
-
-Thus the key to avoiding big decisions becomes to just avoiding to do
-things that can't be undone. Don't get ushered into a corner from which
-you cannot escape. A cornered rat may be dangerous - a cornered manager
-is just pitiful.
-
-It turns out that since nobody would be stupid enough to ever really let
-a kernel manager have huge fiscal responsibility _anyway_, it's usually
-fairly easy to backtrack. Since you're not going to be able to waste
-huge amounts of money that you might not be able to repay, the only
-thing you can backtrack on is a technical decision, and there
-back-tracking is very easy: just tell everybody that you were an
-incompetent nincompoop, say you're sorry, and undo all the worthless
-work you had people work on for the last year. Suddenly the decision
-you made a year ago wasn't a big decision after all, since it could be
-easily undone.
-
-It turns out that some people have trouble with this approach, for two
-reasons:
- - admitting you were an idiot is harder than it looks. We all like to
- maintain appearances, and coming out in public to say that you were
- wrong is sometimes very hard indeed.
- - having somebody tell you that what you worked on for the last year
- wasn't worthwhile after all can be hard on the poor lowly engineers
- too, and while the actual _work_ was easy enough to undo by just
- deleting it, you may have irrevocably lost the trust of that
- engineer. And remember: "irrevocable" was what we tried to avoid in
- the first place, and your decision ended up being a big one after
- all.
-
-Happily, both of these reasons can be mitigated effectively by just
-admitting up-front that you don't have a friggin' clue, and telling
-people ahead of the fact that your decision is purely preliminary, and
-might be the wrong thing. You should always reserve the right to change
-your mind, and make people very _aware_ of that. And it's much easier
-to admit that you are stupid when you haven't _yet_ done the really
-stupid thing.
-
-Then, when it really does turn out to be stupid, people just roll their
-eyes and say "Oops, he did it again".
-
-This preemptive admission of incompetence might also make the people who
-actually do the work also think twice about whether it's worth doing or
-not. After all, if _they_ aren't certain whether it's a good idea, you
-sure as hell shouldn't encourage them by promising them that what they
-work on will be included. Make them at least think twice before they
-embark on a big endeavor.
-
-Remember: they'd better know more about the details than you do, and
-they usually already think they have the answer to everything. The best
-thing you can do as a manager is not to instill confidence, but rather a
-healthy dose of critical thinking on what they do.
-
-Btw, another way to avoid a decision is to plaintively just whine "can't
-we just do both?" and look pitiful. Trust me, it works. If it's not
-clear which approach is better, they'll eventually figure it out. The
-answer may end up being that both teams get so frustrated by the
-situation that they just give up.
-
-That may sound like a failure, but it's usually a sign that there was
-something wrong with both projects, and the reason the people involved
-couldn't decide was that they were both wrong. You end up coming up
-smelling like roses, and you avoided yet another decision that you could
-have screwed up on.
-
-
- Chapter 2: People
-
-Most people are idiots, and being a manager means you'll have to deal
-with it, and perhaps more importantly, that _they_ have to deal with
-_you_.
-
-It turns out that while it's easy to undo technical mistakes, it's not
-as easy to undo personality disorders. You just have to live with
-theirs - and yours.
-
-However, in order to prepare yourself as a kernel manager, it's best to
-remember not to burn any bridges, bomb any innocent villagers, or
-alienate too many kernel developers. It turns out that alienating people
-is fairly easy, and un-alienating them is hard. Thus "alienating"
-immediately falls under the heading of "not reversible", and becomes a
-no-no according to Chapter 1.
-
-There's just a few simple rules here:
- (1) don't call people d*ckheads (at least not in public)
- (2) learn how to apologize when you forgot rule (1)
-
-The problem with #1 is that it's very easy to do, since you can say
-"you're a d*ckhead" in millions of different ways (*), sometimes without
-even realizing it, and almost always with a white-hot conviction that
-you are right.
-
-And the more convinced you are that you are right (and let's face it,
-you can call just about _anybody_ a d*ckhead, and you often _will_ be
-right), the harder it ends up being to apologize afterwards.
-
-To solve this problem, you really only have two options:
- - get really good at apologies
- - spread the "love" out so evenly that nobody really ends up feeling
- like they get unfairly targeted. Make it inventive enough, and they
- might even be amused.
-
-The option of being unfailingly polite really doesn't exist. Nobody will
-trust somebody who is so clearly hiding his true character.
-
-(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
-frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
-scan nearly as well. But I'm sure he thought about it.
-
-
- Chapter 3: People II - the Good Kind
-
-While it turns out that most people are idiots, the corollary to that is
-sadly that you are one too, and that while we can all bask in the secure
-knowledge that we're better than the average person (let's face it,
-nobody ever believes that they're average or below-average), we should
-also admit that we're not the sharpest knife around, and there will be
-other people that are less of an idiot than you are.
-
-Some people react badly to smart people. Others take advantage of them.
-
-Make sure that you, as a kernel maintainer, are in the second group.
-Suck up to them, because they are the people who will make your job
-easier. In particular, they'll be able to make your decisions for you,
-which is what the game is all about.
-
-So when you find somebody smarter than you are, just coast along. Your
-management responsibilities largely become ones of saying "Sounds like a
-good idea - go wild", or "That sounds good, but what about xxx?". The
-second version in particular is a great way to either learn something
-new about "xxx" or seem _extra_ managerial by pointing out something the
-smarter person hadn't thought about. In either case, you win.
-
-One thing to look out for is to realize that greatness in one area does
-not necessarily translate to other areas. So you might prod people in
-specific directions, but let's face it, they might be good at what they
-do, and suck at everything else. The good news is that people tend to
-naturally gravitate back to what they are good at, so it's not like you
-are doing something irreversible when you _do_ prod them in some
-direction, just don't push too hard.
-
-
- Chapter 4: Placing blame
-
-Things will go wrong, and people want somebody to blame. Tag, you're it.
-
-It's not actually that hard to accept the blame, especially if people
-kind of realize that it wasn't _all_ your fault. Which brings us to the
-best way of taking the blame: do it for another guy. You'll feel good
-for taking the fall, he'll feel good about not getting blamed, and the
-guy who lost his whole 36GB porn-collection because of your incompetence
-will grudgingly admit that you at least didn't try to weasel out of it.
-
-Then make the developer who really screwed up (if you can find him) know
-_in_private_ that he screwed up. Not just so he can avoid it in the
-future, but so that he knows he owes you one. And, perhaps even more
-importantly, he's also likely the person who can fix it. Because, let's
-face it, it sure ain't you.
-
-Taking the blame is also why you get to be manager in the first place.
-It's part of what makes people trust you, and allow you the potential
-glory, because you're the one who gets to say "I screwed up". And if
-you've followed the previous rules, you'll be pretty good at saying that
-by now.
-
-
- Chapter 5: Things to avoid
-
-There's one thing people hate even more than being called "d*ckhead",
-and that is being called a "d*ckhead" in a sanctimonious voice. The
-first you can apologize for, the second one you won't really get the
-chance. They likely will no longer be listening even if you otherwise
-do a good job.
-
-We all think we're better than anybody else, which means that when
-somebody else puts on airs, it _really_ rubs us the wrong way. You may
-be morally and intellectually superior to everybody around you, but
-don't try to make it too obvious unless you really _intend_ to irritate
-somebody (*).
-
-Similarly, don't be too polite or subtle about things. Politeness easily
-ends up going overboard and hiding the problem, and as they say, "On the
-internet, nobody can hear you being subtle". Use a big blunt object to
-hammer the point in, because you can't really depend on people getting
-your point otherwise.
-
-Some humor can help pad both the bluntness and the moralizing. Going
-overboard to the point of being ridiculous can drive a point home
-without making it painful to the recipient, who just thinks you're being
-silly. It can thus help get through the personal mental block we all
-have about criticism.
-
-(*) Hint: internet newsgroups that are not directly related to your work
-are great ways to take out your frustrations at other people. Write
-insulting posts with a sneer just to get into a good flame every once in
-a while, and you'll feel cleansed. Just don't crap too close to home.
-
-
- Chapter 6: Why me?
-
-Since your main responsibility seems to be to take the blame for other
-peoples mistakes, and make it painfully obvious to everybody else that
-you're incompetent, the obvious question becomes one of why do it in the
-first place?
-
-First off, while you may or may not get screaming teenage girls (or
-boys, let's not be judgmental or sexist here) knocking on your dressing
-room door, you _will_ get an immense feeling of personal accomplishment
-for being "in charge". Never mind the fact that you're really leading
-by trying to keep up with everybody else and running after them as fast
-as you can. Everybody will still think you're the person in charge.
-
-It's a great job if you can hack it.
diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
deleted file mode 100644
index 147231f1613e..000000000000
--- a/Documentation/PCI/00-INDEX
+++ /dev/null
@@ -1,14 +0,0 @@
-00-INDEX
- - this file
-MSI-HOWTO.txt
- - the Message Signaled Interrupts (MSI) Driver Guide HOWTO and FAQ.
-PCIEBUS-HOWTO.txt
- - a guide describing the PCI Express Port Bus driver
-pci-error-recovery.txt
- - info on PCI error recovery
-pci-iov-howto.txt
- - the PCI Express I/O Virtualization HOWTO
-pci.txt
- - info on the PCI subsystem for device driver authors
-pcieaer-howto.txt
- - the PCI Express Advanced Error Reporting Driver Guide HOWTO
diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.txt
deleted file mode 100644
index 1179850f453c..000000000000
--- a/Documentation/PCI/MSI-HOWTO.txt
+++ /dev/null
@@ -1,587 +0,0 @@
- The MSI Driver Guide HOWTO
- Tom L Nguyen tom.l.nguyen@intel.com
- 10/03/2003
- Revised Feb 12, 2004 by Martine Silbermann
- email: Martine.Silbermann@hp.com
- Revised Jun 25, 2004 by Tom L Nguyen
- Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com>
- Copyright 2003, 2008 Intel Corporation
-
-1. About this guide
-
-This guide describes the basics of Message Signaled Interrupts (MSIs),
-the advantages of using MSI over traditional interrupt mechanisms, how
-to change your driver to use MSI or MSI-X and some basic diagnostics to
-try if a device doesn't support MSIs.
-
-
-2. What are MSIs?
-
-A Message Signaled Interrupt is a write from the device to a special
-address which causes an interrupt to be received by the CPU.
-
-The MSI capability was first specified in PCI 2.2 and was later enhanced
-in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X
-capability was also introduced with PCI 3.0. It supports more interrupts
-per device than MSI and allows interrupts to be independently configured.
-
-Devices may support both MSI and MSI-X, but only one can be enabled at
-a time.
-
-
-3. Why use MSIs?
-
-There are three reasons why using MSIs can give an advantage over
-traditional pin-based interrupts.
-
-Pin-based PCI interrupts are often shared amongst several devices.
-To support this, the kernel must call each interrupt handler associated
-with an interrupt, which leads to reduced performance for the system as
-a whole. MSIs are never shared, so this problem cannot arise.
-
-When a device writes data to memory, then raises a pin-based interrupt,
-it is possible that the interrupt may arrive before all the data has
-arrived in memory (this becomes more likely with devices behind PCI-PCI
-bridges). In order to ensure that all the data has arrived in memory,
-the interrupt handler must read a register on the device which raised
-the interrupt. PCI transaction ordering rules require that all the data
-arrive in memory before the value may be returned from the register.
-Using MSIs avoids this problem as the interrupt-generating write cannot
-pass the data writes, so by the time the interrupt is raised, the driver
-knows that all the data has arrived in memory.
-
-PCI devices can only support a single pin-based interrupt per function.
-Often drivers have to query the device to find out what event has
-occurred, slowing down interrupt handling for the common case. With
-MSIs, a device can support more interrupts, allowing each interrupt
-to be specialised to a different purpose. One possible design gives
-infrequent conditions (such as errors) their own interrupt which allows
-the driver to handle the normal interrupt handling path more efficiently.
-Other possible designs include giving one interrupt to each packet queue
-in a network card or each port in a storage controller.
-
-
-4. How to use MSIs
-
-PCI devices are initialised to use pin-based interrupts. The device
-driver has to set up the device to use MSI or MSI-X. Not all machines
-support MSIs correctly, and for those machines, the APIs described below
-will simply fail and the device will continue to use pin-based interrupts.
-
-4.1 Include kernel support for MSIs
-
-To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
-option enabled. This option is only available on some architectures,
-and it may depend on some other options also being set. For example,
-on x86, you must also enable X86_UP_APIC or SMP in order to see the
-CONFIG_PCI_MSI option.
-
-4.2 Using MSI
-
-Most of the hard work is done for the driver in the PCI layer. It simply
-has to request that the PCI layer set up the MSI capability for this
-device.
-
-4.2.1 pci_enable_msi
-
-int pci_enable_msi(struct pci_dev *dev)
-
-A successful call allocates ONE interrupt to the device, regardless
-of how many MSIs the device supports. The device is switched from
-pin-based interrupt mode to MSI mode. The dev->irq number is changed
-to a new number which represents the message signaled interrupt;
-consequently, this function should be called before the driver calls
-request_irq(), because an MSI is delivered via a vector that is
-different from the vector of a pin-based interrupt.
-
-4.2.2 pci_enable_msi_range
-
-int pci_enable_msi_range(struct pci_dev *dev, int minvec, int maxvec)
-
-This function allows a device driver to request any number of MSI
-interrupts within specified range from 'minvec' to 'maxvec'.
-
-If this function returns a positive number it indicates the number of
-MSI interrupts that have been successfully allocated. In this case
-the device is switched from pin-based interrupt mode to MSI mode and
-updates dev->irq to be the lowest of the new interrupts assigned to it.
-The other interrupts assigned to the device are in the range dev->irq
-to dev->irq + returned value - 1. Device driver can use the returned
-number of successfully allocated MSI interrupts to further allocate
-and initialize device resources.
-
-If this function returns a negative number, it indicates an error and
-the driver should not attempt to request any more MSI interrupts for
-this device.
-
-This function should be called before the driver calls request_irq(),
-because MSI interrupts are delivered via vectors that are different
-from the vector of a pin-based interrupt.
-
-It is ideal if drivers can cope with a variable number of MSI interrupts;
-there are many reasons why the platform may not be able to provide the
-exact number that a driver asks for.
-
-There could be devices that can not operate with just any number of MSI
-interrupts within a range. See chapter 4.3.1.3 to get the idea how to
-handle such devices for MSI-X - the same logic applies to MSI.
-
-4.2.1.1 Maximum possible number of MSI interrupts
-
-The typical usage of MSI interrupts is to allocate as many vectors as
-possible, likely up to the limit returned by pci_msi_vec_count() function:
-
-static int foo_driver_enable_msi(struct pci_dev *pdev, int nvec)
-{
- return pci_enable_msi_range(pdev, 1, nvec);
-}
-
-Note the value of 'minvec' parameter is 1. As 'minvec' is inclusive,
-the value of 0 would be meaningless and could result in error.
-
-Some devices have a minimal limit on number of MSI interrupts.
-In this case the function could look like this:
-
-static int foo_driver_enable_msi(struct pci_dev *pdev, int nvec)
-{
- return pci_enable_msi_range(pdev, FOO_DRIVER_MINIMUM_NVEC, nvec);
-}
-
-4.2.1.2 Exact number of MSI interrupts
-
-If a driver is unable or unwilling to deal with a variable number of MSI
-interrupts it could request a particular number of interrupts by passing
-that number to pci_enable_msi_range() function as both 'minvec' and 'maxvec'
-parameters:
-
-static int foo_driver_enable_msi(struct pci_dev *pdev, int nvec)
-{
- return pci_enable_msi_range(pdev, nvec, nvec);
-}
-
-Note, unlike pci_enable_msi_exact() function, which could be also used to
-enable a particular number of MSI-X interrupts, pci_enable_msi_range()
-returns either a negative errno or 'nvec' (not negative errno or 0 - as
-pci_enable_msi_exact() does).
-
-4.2.1.3 Single MSI mode
-
-The most notorious example of the request type described above is
-enabling the single MSI mode for a device. It could be done by passing
-two 1s as 'minvec' and 'maxvec':
-
-static int foo_driver_enable_single_msi(struct pci_dev *pdev)
-{
- return pci_enable_msi_range(pdev, 1, 1);
-}
-
-Note, unlike pci_enable_msi() function, which could be also used to
-enable the single MSI mode, pci_enable_msi_range() returns either a
-negative errno or 1 (not negative errno or 0 - as pci_enable_msi()
-does).
-
-4.2.3 pci_enable_msi_exact
-
-int pci_enable_msi_exact(struct pci_dev *dev, int nvec)
-
-This variation on pci_enable_msi_range() call allows a device driver to
-request exactly 'nvec' MSIs.
-
-If this function returns a negative number, it indicates an error and
-the driver should not attempt to request any more MSI interrupts for
-this device.
-
-By contrast with pci_enable_msi_range() function, pci_enable_msi_exact()
-returns zero in case of success, which indicates MSI interrupts have been
-successfully allocated.
-
-4.2.4 pci_disable_msi
-
-void pci_disable_msi(struct pci_dev *dev)
-
-This function should be used to undo the effect of pci_enable_msi_range().
-Calling it restores dev->irq to the pin-based interrupt number and frees
-the previously allocated MSIs. The interrupts may subsequently be assigned
-to another device, so drivers should not cache the value of dev->irq.
-
-Before calling this function, a device driver must always call free_irq()
-on any interrupt for which it previously called request_irq().
-Failure to do so results in a BUG_ON(), leaving the device with
-MSI enabled and thus leaking its vector.
-
-4.2.4 pci_msi_vec_count
-
-int pci_msi_vec_count(struct pci_dev *dev)
-
-This function could be used to retrieve the number of MSI vectors the
-device requested (via the Multiple Message Capable register). The MSI
-specification only allows the returned value to be a power of two,
-up to a maximum of 2^5 (32).
-
-If this function returns a negative number, it indicates the device is
-not capable of sending MSIs.
-
-If this function returns a positive number, it indicates the maximum
-number of MSI interrupt vectors that could be allocated.
-
-4.3 Using MSI-X
-
-The MSI-X capability is much more flexible than the MSI capability.
-It supports up to 2048 interrupts, each of which can be controlled
-independently. To support this flexibility, drivers must use an array of
-`struct msix_entry':
-
-struct msix_entry {
- u16 vector; /* kernel uses to write alloc vector */
- u16 entry; /* driver uses to specify entry */
-};
-
-This allows for the device to use these interrupts in a sparse fashion;
-for example, it could use interrupts 3 and 1027 and yet allocate only a
-two-element array. The driver is expected to fill in the 'entry' value
-in each element of the array to indicate for which entries the kernel
-should assign interrupts; it is invalid to fill in two entries with the
-same number.
-
-4.3.1 pci_enable_msix_range
-
-int pci_enable_msix_range(struct pci_dev *dev, struct msix_entry *entries,
- int minvec, int maxvec)
-
-Calling this function asks the PCI subsystem to allocate any number of
-MSI-X interrupts within specified range from 'minvec' to 'maxvec'.
-The 'entries' argument is a pointer to an array of msix_entry structs
-which should be at least 'maxvec' entries in size.
-
-On success, the device is switched into MSI-X mode and the function
-returns the number of MSI-X interrupts that have been successfully
-allocated. In this case the 'vector' member in entries numbered from
-0 to the returned value - 1 is populated with the interrupt number;
-the driver should then call request_irq() for each 'vector' that it
-decides to use. The device driver is responsible for keeping track of the
-interrupts assigned to the MSI-X vectors so it can free them again later.
-Device driver can use the returned number of successfully allocated MSI-X
-interrupts to further allocate and initialize device resources.
-
-If this function returns a negative number, it indicates an error and
-the driver should not attempt to allocate any more MSI-X interrupts for
-this device.
-
-This function, in contrast with pci_enable_msi_range(), does not adjust
-dev->irq. The device will not generate interrupts for this interrupt
-number once MSI-X is enabled.
-
-Device drivers should normally call this function once per device
-during the initialization phase.
-
-It is ideal if drivers can cope with a variable number of MSI-X interrupts;
-there are many reasons why the platform may not be able to provide the
-exact number that a driver asks for.
-
-There could be devices that can not operate with just any number of MSI-X
-interrupts within a range. E.g., an network adapter might need let's say
-four vectors per each queue it provides. Therefore, a number of MSI-X
-interrupts allocated should be a multiple of four. In this case interface
-pci_enable_msix_range() can not be used alone to request MSI-X interrupts
-(since it can allocate any number within the range, without any notion of
-the multiple of four) and the device driver should master a custom logic
-to request the required number of MSI-X interrupts.
-
-4.3.1.1 Maximum possible number of MSI-X interrupts
-
-The typical usage of MSI-X interrupts is to allocate as many vectors as
-possible, likely up to the limit returned by pci_msix_vec_count() function:
-
-static int foo_driver_enable_msix(struct foo_adapter *adapter, int nvec)
-{
- return pci_enable_msix_range(adapter->pdev, adapter->msix_entries,
- 1, nvec);
-}
-
-Note the value of 'minvec' parameter is 1. As 'minvec' is inclusive,
-the value of 0 would be meaningless and could result in error.
-
-Some devices have a minimal limit on number of MSI-X interrupts.
-In this case the function could look like this:
-
-static int foo_driver_enable_msix(struct foo_adapter *adapter, int nvec)
-{
- return pci_enable_msix_range(adapter->pdev, adapter->msix_entries,
- FOO_DRIVER_MINIMUM_NVEC, nvec);
-}
-
-4.3.1.2 Exact number of MSI-X interrupts
-
-If a driver is unable or unwilling to deal with a variable number of MSI-X
-interrupts it could request a particular number of interrupts by passing
-that number to pci_enable_msix_range() function as both 'minvec' and 'maxvec'
-parameters:
-
-static int foo_driver_enable_msix(struct foo_adapter *adapter, int nvec)
-{
- return pci_enable_msix_range(adapter->pdev, adapter->msix_entries,
- nvec, nvec);
-}
-
-Note, unlike pci_enable_msix_exact() function, which could be also used to
-enable a particular number of MSI-X interrupts, pci_enable_msix_range()
-returns either a negative errno or 'nvec' (not negative errno or 0 - as
-pci_enable_msix_exact() does).
-
-4.3.1.3 Specific requirements to the number of MSI-X interrupts
-
-As noted above, there could be devices that can not operate with just any
-number of MSI-X interrupts within a range. E.g., let's assume a device that
-is only capable sending the number of MSI-X interrupts which is a power of
-two. A routine that enables MSI-X mode for such device might look like this:
-
-/*
- * Assume 'minvec' and 'maxvec' are non-zero
- */
-static int foo_driver_enable_msix(struct foo_adapter *adapter,
- int minvec, int maxvec)
-{
- int rc;
-
- minvec = roundup_pow_of_two(minvec);
- maxvec = rounddown_pow_of_two(maxvec);
-
- if (minvec > maxvec)
- return -ERANGE;
-
-retry:
- rc = pci_enable_msix_range(adapter->pdev, adapter->msix_entries,
- maxvec, maxvec);
- /*
- * -ENOSPC is the only error code allowed to be analyzed
- */
- if (rc == -ENOSPC) {
- if (maxvec == 1)
- return -ENOSPC;
-
- maxvec /= 2;
-
- if (minvec > maxvec)
- return -ENOSPC;
-
- goto retry;
- }
-
- return rc;
-}
-
-Note how pci_enable_msix_range() return value is analyzed for a fallback -
-any error code other than -ENOSPC indicates a fatal error and should not
-be retried.
-
-4.3.2 pci_enable_msix_exact
-
-int pci_enable_msix_exact(struct pci_dev *dev,
- struct msix_entry *entries, int nvec)
-
-This variation on pci_enable_msix_range() call allows a device driver to
-request exactly 'nvec' MSI-Xs.
-
-If this function returns a negative number, it indicates an error and
-the driver should not attempt to allocate any more MSI-X interrupts for
-this device.
-
-By contrast with pci_enable_msix_range() function, pci_enable_msix_exact()
-returns zero in case of success, which indicates MSI-X interrupts have been
-successfully allocated.
-
-Another version of a routine that enables MSI-X mode for a device with
-specific requirements described in chapter 4.3.1.3 might look like this:
-
-/*
- * Assume 'minvec' and 'maxvec' are non-zero
- */
-static int foo_driver_enable_msix(struct foo_adapter *adapter,
- int minvec, int maxvec)
-{
- int rc;
-
- minvec = roundup_pow_of_two(minvec);
- maxvec = rounddown_pow_of_two(maxvec);
-
- if (minvec > maxvec)
- return -ERANGE;
-
-retry:
- rc = pci_enable_msix_exact(adapter->pdev,
- adapter->msix_entries, maxvec);
-
- /*
- * -ENOSPC is the only error code allowed to be analyzed
- */
- if (rc == -ENOSPC) {
- if (maxvec == 1)
- return -ENOSPC;
-
- maxvec /= 2;
-
- if (minvec > maxvec)
- return -ENOSPC;
-
- goto retry;
- } else if (rc < 0) {
- return rc;
- }
-
- return maxvec;
-}
-
-4.3.3 pci_disable_msix
-
-void pci_disable_msix(struct pci_dev *dev)
-
-This function should be used to undo the effect of pci_enable_msix_range().
-It frees the previously allocated MSI-X interrupts. The interrupts may
-subsequently be assigned to another device, so drivers should not cache
-the value of the 'vector' elements over a call to pci_disable_msix().
-
-Before calling this function, a device driver must always call free_irq()
-on any interrupt for which it previously called request_irq().
-Failure to do so results in a BUG_ON(), leaving the device with
-MSI-X enabled and thus leaking its vector.
-
-4.3.3 The MSI-X Table
-
-The MSI-X capability specifies a BAR and offset within that BAR for the
-MSI-X Table. This address is mapped by the PCI subsystem, and should not
-be accessed directly by the device driver. If the driver wishes to
-mask or unmask an interrupt, it should call disable_irq() / enable_irq().
-
-4.3.4 pci_msix_vec_count
-
-int pci_msix_vec_count(struct pci_dev *dev)
-
-This function could be used to retrieve number of entries in the device
-MSI-X table.
-
-If this function returns a negative number, it indicates the device is
-not capable of sending MSI-Xs.
-
-If this function returns a positive number, it indicates the maximum
-number of MSI-X interrupt vectors that could be allocated.
-
-4.4 Handling devices implementing both MSI and MSI-X capabilities
-
-If a device implements both MSI and MSI-X capabilities, it can
-run in either MSI mode or MSI-X mode, but not both simultaneously.
-This is a requirement of the PCI spec, and it is enforced by the
-PCI layer. Calling pci_enable_msi_range() when MSI-X is already
-enabled or pci_enable_msix_range() when MSI is already enabled
-results in an error. If a device driver wishes to switch between MSI
-and MSI-X at runtime, it must first quiesce the device, then switch
-it back to pin-interrupt mode, before calling pci_enable_msi_range()
-or pci_enable_msix_range() and resuming operation. This is not expected
-to be a common operation but may be useful for debugging or testing
-during development.
-
-4.5 Considerations when using MSIs
-
-4.5.1 Choosing between MSI-X and MSI
-
-If your device supports both MSI-X and MSI capabilities, you should use
-the MSI-X facilities in preference to the MSI facilities. As mentioned
-above, MSI-X supports any number of interrupts between 1 and 2048.
-In contrast, MSI is restricted to a maximum of 32 interrupts (and
-must be a power of two). In addition, the MSI interrupt vectors must
-be allocated consecutively, so the system might not be able to allocate
-as many vectors for MSI as it could for MSI-X. On some platforms, MSI
-interrupts must all be targeted at the same set of CPUs whereas MSI-X
-interrupts can all be targeted at different CPUs.
-
-4.5.2 Spinlocks
-
-Most device drivers have a per-device spinlock which is taken in the
-interrupt handler. With pin-based interrupts or a single MSI, it is not
-necessary to disable interrupts (Linux guarantees the same interrupt will
-not be re-entered). If a device uses multiple interrupts, the driver
-must disable interrupts while the lock is held. If the device sends
-a different interrupt, the driver will deadlock trying to recursively
-acquire the spinlock. Such deadlocks can be avoided by using
-spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
-and acquire the lock (see Documentation/DocBook/kernel-locking).
-
-4.6 How to tell whether MSI/MSI-X is enabled on a device
-
-Using 'lspci -v' (as root) may show some devices with "MSI", "Message
-Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
-has an 'Enable' flag which is followed with either "+" (enabled)
-or "-" (disabled).
-
-
-5. MSI quirks
-
-Several PCI chipsets or devices are known not to support MSIs.
-The PCI stack provides three ways to disable MSIs:
-
-1. globally
-2. on all devices behind a specific bridge
-3. on a single device
-
-5.1. Disabling MSIs globally
-
-Some host chipsets simply don't support MSIs properly. If we're
-lucky, the manufacturer knows this and has indicated it in the ACPI
-FADT table. In this case, Linux automatically disables MSIs.
-Some boards don't include this information in the table and so we have
-to detect them ourselves. The complete list of these is found near the
-quirk_disable_all_msi() function in drivers/pci/quirks.c.
-
-If you have a board which has problems with MSIs, you can pass pci=nomsi
-on the kernel command line to disable MSIs on all devices. It would be
-in your best interests to report the problem to linux-pci@vger.kernel.org
-including a full 'lspci -v' so we can add the quirks to the kernel.
-
-5.2. Disabling MSIs below a bridge
-
-Some PCI bridges are not able to route MSIs between busses properly.
-In this case, MSIs must be disabled on all devices behind the bridge.
-
-Some bridges allow you to enable MSIs by changing some bits in their
-PCI configuration space (especially the Hypertransport chipsets such
-as the nVidia nForce and Serverworks HT2000). As with host chipsets,
-Linux mostly knows about them and automatically enables MSIs if it can.
-If you have a bridge unknown to Linux, you can enable
-MSIs in configuration space using whatever method you know works, then
-enable MSIs on that bridge by doing:
-
- echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
-
-where $bridge is the PCI address of the bridge you've enabled (eg
-0000:00:0e.0).
-
-To disable MSIs, echo 0 instead of 1. Changing this value should be
-done with caution as it could break interrupt handling for all devices
-below this bridge.
-
-Again, please notify linux-pci@vger.kernel.org of any bridges that need
-special handling.
-
-5.3. Disabling MSIs on a single device
-
-Some devices are known to have faulty MSI implementations. Usually this
-is handled in the individual device driver, but occasionally it's necessary
-to handle this with a quirk. Some drivers have an option to disable use
-of MSI. While this is a convenient workaround for the driver author,
-it is not good practice, and should not be emulated.
-
-5.4. Finding why MSIs are disabled on a device
-
-From the above three sections, you can see that there are many reasons
-why MSIs may not be enabled for a given device. Your first step should
-be to examine your dmesg carefully to determine whether MSIs are enabled
-for your machine. You should also check your .config to be sure you
-have enabled CONFIG_PCI_MSI.
-
-Then, 'lspci -t' gives the list of bridges above a device. Reading
-/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1)
-or disabled (0). If 0 is found in any of the msi_bus files belonging
-to bridges between the PCI root and the device, MSIs are disabled.
-
-It is also worth checking the device driver to see whether it supports MSIs.
-For example, it may contain calls to pci_enable_msi_range() or
-pci_enable_msix_range().
diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/PCIEBUS-HOWTO.txt
deleted file mode 100644
index 6bd5f372adec..000000000000
--- a/Documentation/PCI/PCIEBUS-HOWTO.txt
+++ /dev/null
@@ -1,217 +0,0 @@
- The PCI Express Port Bus Driver Guide HOWTO
- Tom L Nguyen tom.l.nguyen@intel.com
- 11/03/2004
-
-1. About this guide
-
-This guide describes the basics of the PCI Express Port Bus driver
-and provides information on how to enable the service drivers to
-register/unregister with the PCI Express Port Bus Driver.
-
-2. Copyright 2004 Intel Corporation
-
-3. What is the PCI Express Port Bus Driver
-
-A PCI Express Port is a logical PCI-PCI Bridge structure. There
-are two types of PCI Express Port: the Root Port and the Switch
-Port. The Root Port originates a PCI Express link from a PCI Express
-Root Complex and the Switch Port connects PCI Express links to
-internal logical PCI buses. The Switch Port, which has its secondary
-bus representing the switch's internal routing logic, is called the
-switch's Upstream Port. The switch's Downstream Port is bridging from
-switch's internal routing bus to a bus representing the downstream
-PCI Express link from the PCI Express Switch.
-
-A PCI Express Port can provide up to four distinct functions,
-referred to in this document as services, depending on its port type.
-PCI Express Port's services include native hotplug support (HP),
-power management event support (PME), advanced error reporting
-support (AER), and virtual channel support (VC). These services may
-be handled by a single complex driver or be individually distributed
-and handled by corresponding service drivers.
-
-4. Why use the PCI Express Port Bus Driver?
-
-In existing Linux kernels, the Linux Device Driver Model allows a
-physical device to be handled by only a single driver. The PCI
-Express Port is a PCI-PCI Bridge device with multiple distinct
-services. To maintain a clean and simple solution each service
-may have its own software service driver. In this case several
-service drivers will compete for a single PCI-PCI Bridge device.
-For example, if the PCI Express Root Port native hotplug service
-driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
-kernel therefore does not load other service drivers for that Root
-Port. In other words, it is impossible to have multiple service
-drivers load and run on a PCI-PCI Bridge device simultaneously
-using the current driver model.
-
-To enable multiple service drivers running simultaneously requires
-having a PCI Express Port Bus driver, which manages all populated
-PCI Express Ports and distributes all provided service requests
-to the corresponding service drivers as required. Some key
-advantages of using the PCI Express Port Bus driver are listed below:
-
- - Allow multiple service drivers to run simultaneously on
- a PCI-PCI Bridge Port device.
-
- - Allow service drivers implemented in an independent
- staged approach.
-
- - Allow one service driver to run on multiple PCI-PCI Bridge
- Port devices.
-
- - Manage and distribute resources of a PCI-PCI Bridge Port
- device to requested service drivers.
-
-5. Configuring the PCI Express Port Bus Driver vs. Service Drivers
-
-5.1 Including the PCI Express Port Bus Driver Support into the Kernel
-
-Including the PCI Express Port Bus driver depends on whether the PCI
-Express support is included in the kernel config. The kernel will
-automatically include the PCI Express Port Bus driver as a kernel
-driver when the PCI Express support is enabled in the kernel.
-
-5.2 Enabling Service Driver Support
-
-PCI device drivers are implemented based on Linux Device Driver Model.
-All service drivers are PCI device drivers. As discussed above, it is
-impossible to load any service driver once the kernel has loaded the
-PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
-Model requires some minimal changes on existing service drivers that
-imposes no impact on the functionality of existing service drivers.
-
-A service driver is required to use the two APIs shown below to
-register its service with the PCI Express Port Bus driver (see
-section 5.2.1 & 5.2.2). It is important that a service driver
-initializes the pcie_port_service_driver data structure, included in
-header file /include/linux/pcieport_if.h, before calling these APIs.
-Failure to do so will result an identity mismatch, which prevents
-the PCI Express Port Bus driver from loading a service driver.
-
-5.2.1 pcie_port_service_register
-
-int pcie_port_service_register(struct pcie_port_service_driver *new)
-
-This API replaces the Linux Driver Model's pci_register_driver API. A
-service driver should always calls pcie_port_service_register at
-module init. Note that after service driver being loaded, calls
-such as pci_enable_device(dev) and pci_set_master(dev) are no longer
-necessary since these calls are executed by the PCI Port Bus driver.
-
-5.2.2 pcie_port_service_unregister
-
-void pcie_port_service_unregister(struct pcie_port_service_driver *new)
-
-pcie_port_service_unregister replaces the Linux Driver Model's
-pci_unregister_driver. It's always called by service driver when a
-module exits.
-
-5.2.3 Sample Code
-
-Below is sample service driver code to initialize the port service
-driver data structure.
-
-static struct pcie_port_service_id service_id[] = { {
- .vendor = PCI_ANY_ID,
- .device = PCI_ANY_ID,
- .port_type = PCIE_RC_PORT,
- .service_type = PCIE_PORT_SERVICE_AER,
- }, { /* end: all zeroes */ }
-};
-
-static struct pcie_port_service_driver root_aerdrv = {
- .name = (char *)device_name,
- .id_table = &service_id[0],
-
- .probe = aerdrv_load,
- .remove = aerdrv_unload,
-
- .suspend = aerdrv_suspend,
- .resume = aerdrv_resume,
-};
-
-Below is a sample code for registering/unregistering a service
-driver.
-
-static int __init aerdrv_service_init(void)
-{
- int retval = 0;
-
- retval = pcie_port_service_register(&root_aerdrv);
- if (!retval) {
- /*
- * FIX ME
- */
- }
- return retval;
-}
-
-static void __exit aerdrv_service_exit(void)
-{
- pcie_port_service_unregister(&root_aerdrv);
-}
-
-module_init(aerdrv_service_init);
-module_exit(aerdrv_service_exit);
-
-6. Possible Resource Conflicts
-
-Since all service drivers of a PCI-PCI Bridge Port device are
-allowed to run simultaneously, below lists a few of possible resource
-conflicts with proposed solutions.
-
-6.1 MSI Vector Resource
-
-The MSI capability structure enables a device software driver to call
-pci_enable_msi to request MSI based interrupts. Once MSI interrupts
-are enabled on a device, it stays in this mode until a device driver
-calls pci_disable_msi to disable MSI interrupts and revert back to
-INTx emulation mode. Since service drivers of the same PCI-PCI Bridge
-port share the same physical device, if an individual service driver
-calls pci_enable_msi/pci_disable_msi it may result unpredictable
-behavior. For example, two service drivers run simultaneously on the
-same physical Root Port. Both service drivers call pci_enable_msi to
-request MSI based interrupts. A service driver may not know whether
-any other service drivers have run on this Root Port. If either one
-of them calls pci_disable_msi, it puts the other service driver
-in a wrong interrupt mode.
-
-To avoid this situation all service drivers are not permitted to
-switch interrupt mode on its device. The PCI Express Port Bus driver
-is responsible for determining the interrupt mode and this should be
-transparent to service drivers. Service drivers need to know only
-the vector IRQ assigned to the field irq of struct pcie_device, which
-is passed in when the PCI Express Port Bus driver probes each service
-driver. Service drivers should use (struct pcie_device*)dev->irq to
-call request_irq/free_irq. In addition, the interrupt mode is stored
-in the field interrupt_mode of struct pcie_device.
-
-6.2 MSI-X Vector Resources
-
-Similar to the MSI a device driver for an MSI-X capable device can
-call pci_enable_msix to request MSI-X interrupts. All service drivers
-are not permitted to switch interrupt mode on its device. The PCI
-Express Port Bus driver is responsible for determining the interrupt
-mode and this should be transparent to service drivers. Any attempt
-by service driver to call pci_enable_msix/pci_disable_msix may
-result unpredictable behavior. Service drivers should use
-(struct pcie_device*)dev->irq and call request_irq/free_irq.
-
-6.3 PCI Memory/IO Mapped Regions
-
-Service drivers for PCI Express Power Management (PME), Advanced
-Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
-PCI configuration space on the PCI Express port. In all cases the
-registers accessed are independent of each other. This patch assumes
-that all service drivers will be well behaved and not overwrite
-other service driver's configuration settings.
-
-6.4 PCI Config Registers
-
-Each service driver runs its PCI config operations on its own
-capability structure except the PCI Express capability structure, in
-which Root Control register and Device Control register are shared
-between PME and AER. This patch assumes that all service drivers
-will be well behaved and not overwrite other service driver's
-configuration settings.
diff --git a/Documentation/PCI/acpi-info.rst b/Documentation/PCI/acpi-info.rst
new file mode 100644
index 000000000000..34c64a5a66ec
--- /dev/null
+++ b/Documentation/PCI/acpi-info.rst
@@ -0,0 +1,192 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================================
+ACPI considerations for PCI host bridges
+========================================
+
+The general rule is that the ACPI namespace should describe everything the
+OS might use unless there's another way for the OS to find it [1, 2].
+
+For example, there's no standard hardware mechanism for enumerating PCI
+host bridges, so the ACPI namespace must describe each host bridge, the
+method for accessing PCI config space below it, the address space windows
+the host bridge forwards to PCI (using _CRS), and the routing of legacy
+INTx interrupts (using _PRT).
+
+PCI devices, which are below the host bridge, generally do not need to be
+described via ACPI. The OS can discover them via the standard PCI
+enumeration mechanism, using config accesses to discover and identify
+devices and read and size their BARs. However, ACPI may describe PCI
+devices if it provides power management or hotplug functionality for them
+or if the device has INTx interrupts connected by platform interrupt
+controllers and a _PRT is needed to describe those connections.
+
+ACPI resource description is done via _CRS objects of devices in the ACPI
+namespace [2]. The _CRS is like a generalized PCI BAR: the OS can read
+_CRS and figure out what resource is being consumed even if it doesn't have
+a driver for the device [3]. That's important because it means an old OS
+can work correctly even on a system with new devices unknown to the OS.
+The new devices might not do anything, but the OS can at least make sure no
+resources conflict with them.
+
+Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
+reserving address space. The static tables are for things the OS needs to
+know early in boot, before it can parse the ACPI namespace. If a new table
+is defined, an old OS needs to operate correctly even though it ignores the
+table. _CRS allows that because it is generic and understood by the old
+OS; a static table does not.
+
+If the OS is expected to manage a non-discoverable device described via
+ACPI, that device will have a specific _HID/_CID that tells the OS what
+driver to bind to it, and the _CRS tells the OS and the driver where the
+device's registers are.
+
+PCI host bridges are PNP0A03 or PNP0A08 devices. Their _CRS should
+describe all the address space they consume. This includes all the windows
+they forward down to the PCI bus, as well as registers of the host bridge
+itself that are not forwarded to PCI. The host bridge registers include
+things like secondary/subordinate bus registers that determine the bus
+range below the bridge, window registers that describe the apertures, etc.
+These are all device-specific, non-architected things, so the only way a
+PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
+the device-specific details. The host bridge registers also include ECAM
+space, since it is consumed by the host bridge.
+
+ACPI defines a Consumer/Producer bit to distinguish the bridge registers
+("Consumer") from the bridge apertures ("Producer") [4, 5], but early
+BIOSes didn't use that bit correctly. The result is that the current ACPI
+spec defines Consumer/Producer only for the Extended Address Space
+descriptors; the bit should be ignored in the older QWord/DWord/Word
+Address Space descriptors. Consequently, OSes have to assume all
+QWord/DWord/Word descriptors are windows.
+
+Prior to the addition of Extended Address Space descriptors, the failure of
+Consumer/Producer meant there was no way to describe bridge registers in
+the PNP0A03/PNP0A08 device itself. The workaround was to describe the
+bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
+With the exception of ECAM, the bridge register space is device-specific
+anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
+know about it.
+
+New architectures should be able to use "Consumer" Extended Address Space
+descriptors in the PNP0A03 device for bridge registers, including ECAM,
+although a strict interpretation of [6] might prohibit this. Old x86 and
+ia64 kernels assume all address space descriptors, including "Consumer"
+Extended Address Space ones, are windows, so it would not be safe to
+describe bridge registers this way on those architectures.
+
+PNP0C02 "motherboard" devices are basically a catch-all. There's no
+programming model for them other than "don't use these resources for
+anything else." So a PNP0C02 _CRS should claim any address space that is
+(1) not claimed by _CRS under any other device object in the ACPI namespace
+and (2) should not be assigned by the OS to something else.
+
+The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
+unless there's a standard firmware interface for config access, e.g., the
+ia64 SAL interface [7]. A host bridge consumes ECAM memory address space
+and converts memory accesses into PCI configuration accesses. The spec
+defines the ECAM address space layout and functionality; only the base of
+the address space is device-specific. An ACPI OS learns the base address
+from either the static MCFG table or a _CBA method in the PNP0A03 device.
+
+The MCFG table must describe the ECAM space of non-hot pluggable host
+bridges [8]. Since MCFG is a static table and can't be updated by hotplug,
+a _CBA method in the PNP0A03 device describes the ECAM space of a
+hot-pluggable host bridge [9]. Note that for both MCFG and _CBA, the base
+address always corresponds to bus 0, even if the bus range below the bridge
+(which is reported via _CRS) doesn't start at 0.
+
+
+[1] ACPI 6.2, sec 6.1:
+ For any device that is on a non-enumerable type of bus (for example, an
+ ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI
+ system firmware must supply an _HID object ... for each device to
+ enable OSPM to do that.
+
+[2] ACPI 6.2, sec 3.7:
+ The OS enumerates motherboard devices simply by reading through the
+ ACPI Namespace looking for devices with hardware IDs.
+
+ Each device enumerated by ACPI includes ACPI-defined objects in the
+ ACPI Namespace that report the hardware resources the device could
+ occupy [_PRS], an object that reports the resources that are currently
+ used by the device [_CRS], and objects for configuring those resources
+ [_SRS]. The information is used by the Plug and Play OS (OSPM) to
+ configure the devices.
+
+[3] ACPI 6.2, sec 6.2:
+ OSPM uses device configuration objects to configure hardware resources
+ for devices enumerated via ACPI. Device configuration objects provide
+ information about current and possible resource requirements, the
+ relationship between shared resources, and methods for configuring
+ hardware resources.
+
+ When OSPM enumerates a device, it calls _PRS to determine the resource
+ requirements of the device. It may also call _CRS to find the current
+ resource settings for the device. Using this information, the Plug and
+ Play system determines what resources the device should consume and
+ sets those resources by calling the device’s _SRS control method.
+
+ In ACPI, devices can consume resources (for example, legacy keyboards),
+ provide resources (for example, a proprietary PCI bridge), or do both.
+ Unless otherwise specified, resources for a device are assumed to be
+ taken from the nearest matching resource above the device in the device
+ hierarchy.
+
+[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
+ QWord/DWord/Word Address Space Descriptor (.1, .2, .3)
+ General Flags: Bit [0] Ignored
+
+ Extended Address Space Descriptor (.4)
+ General Flags: Bit [0] Consumer/Producer:
+
+ * 1 – This device consumes this resource
+ * 0 – This device produces and consumes this resource
+
+[5] ACPI 6.2, sec 19.6.43:
+ ResourceUsage specifies whether the Memory range is consumed by
+ this device (ResourceConsumer) or passed on to child devices
+ (ResourceProducer). If nothing is specified, then
+ ResourceConsumer is assumed.
+
+[6] PCI Firmware 3.2, sec 4.1.2:
+ If the operating system does not natively comprehend reserving the
+ MMCFG region, the MMCFG region must be reserved by firmware. The
+ address range reported in the MCFG table or by _CBA method (see Section
+ 4.1.3) must be reserved by declaring a motherboard resource. For most
+ systems, the motherboard resource would appear at the root of the ACPI
+ namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and
+ the resources in this case should not be claimed in the root PCI bus’s
+ _CRS. The resources can optionally be returned in Int15 E820 or
+ EFIGetMemoryMap as reserved memory but must always be reported through
+ ACPI as a motherboard resource.
+
+[7] PCI Express 4.0, sec 7.2.2:
+ For systems that are PC-compatible, or that do not implement a
+ processor-architecture-specific firmware interface standard that allows
+ access to the Configuration Space, the ECAM is required as defined in
+ this section.
+
+[8] PCI Firmware 3.2, sec 4.1.2:
+ The MCFG table is an ACPI table that is used to communicate the base
+ addresses corresponding to the non-hot removable PCI Segment Groups
+ range within a PCI Segment Group available to the operating system at
+ boot. This is required for the PC-compatible systems.
+
+ The MCFG table is only used to communicate the base addresses
+ corresponding to the PCI Segment Groups available to the system at
+ boot.
+
+[9] PCI Firmware 3.2, sec 4.1.3:
+ The _CBA (Memory mapped Configuration Base Address) control method is
+ an optional ACPI object that returns the 64-bit memory mapped
+ configuration base address for the hot plug capable host bridge. The
+ base address returned by _CBA is processor-relative address. The _CBA
+ control method evaluates to an Integer.
+
+ This control method appears under a host bridge object. When the _CBA
+ method appears under an active host bridge object, the operating system
+ evaluates this structure to identify the memory mapped configuration
+ base address corresponding to the PCI Segment Group for the bus number
+ range specified in _CRS method. An ACPI name space object that contains
+ the _CBA method must also contain a corresponding _SEG method.
diff --git a/Documentation/PCI/boot-interrupts.rst b/Documentation/PCI/boot-interrupts.rst
new file mode 100644
index 000000000000..931077bb0953
--- /dev/null
+++ b/Documentation/PCI/boot-interrupts.rst
@@ -0,0 +1,159 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Boot Interrupts
+===============
+
+:Author: - Sean V Kelley <sean.v.kelley@linux.intel.com>
+
+Overview
+========
+
+On PCI Express, interrupts are represented with either MSI or inbound
+interrupt messages (Assert_INTx/Deassert_INTx). The integrated IO-APIC in a
+given Core IO converts the legacy interrupt messages from PCI Express to
+MSI interrupts. If the IO-APIC is disabled (via the mask bits in the
+IO-APIC table entries), the messages are routed to the legacy PCH. This
+in-band interrupt mechanism was traditionally necessary for systems that
+did not support the IO-APIC and for boot. Intel in the past has used the
+term "boot interrupts" to describe this mechanism. Further, the PCI Express
+protocol describes this in-band legacy wire-interrupt INTx mechanism for
+I/O devices to signal PCI-style level interrupts. The subsequent paragraphs
+describe problems with the Core IO handling of INTx message routing to the
+PCH and mitigation within BIOS and the OS.
+
+
+Issue
+=====
+
+When in-band legacy INTx messages are forwarded to the PCH, they in turn
+trigger a new interrupt for which the OS likely lacks a handler. When an
+interrupt goes unhandled over time, they are tracked by the Linux kernel as
+Spurious Interrupts. The IRQ will be disabled by the Linux kernel after it
+reaches a specific count with the error "nobody cared". This disabled IRQ
+now prevents valid usage by an existing interrupt which may happen to share
+the IRQ line::
+
+ irq 19: nobody cared (try booting with the "irqpoll" option)
+ CPU: 0 PID: 2988 Comm: irq/34-nipalk Tainted: 4.14.87-rt49-02410-g4a640ec-dirty #1
+ Hardware name: National Instruments NI PXIe-8880/NI PXIe-8880, BIOS 2.1.5f1 01/09/2020
+ Call Trace:
+
+ <IRQ>
+ ? dump_stack+0x46/0x5e
+ ? __report_bad_irq+0x2e/0xb0
+ ? note_interrupt+0x242/0x290
+ ? nNIKAL100_memoryRead16+0x8/0x10 [nikal]
+ ? handle_irq_event_percpu+0x55/0x70
+ ? handle_irq_event+0x4f/0x80
+ ? handle_fasteoi_irq+0x81/0x180
+ ? handle_irq+0x1c/0x30
+ ? do_IRQ+0x41/0xd0
+ ? common_interrupt+0x84/0x84
+ </IRQ>
+
+ handlers:
+ irq_default_primary_handler threaded usb_hcd_irq
+ Disabling IRQ #19
+
+
+Conditions
+==========
+
+The use of threaded interrupts is the most likely condition to trigger
+this problem today. Threaded interrupts may not be re-enabled after the IRQ
+handler wakes. These "one shot" conditions mean that the threaded interrupt
+needs to keep the interrupt line masked until the threaded handler has run.
+Especially when dealing with high data rate interrupts, the thread needs to
+run to completion; otherwise some handlers will end up in stack overflows
+since the interrupt of the issuing device is still active.
+
+Affected Chipsets
+=================
+
+The legacy interrupt forwarding mechanism exists today in a number of
+devices including but not limited to chipsets from AMD/ATI, Broadcom, and
+Intel. Changes made through the mitigations below have been applied to
+drivers/pci/quirks.c
+
+Starting with ICX there are no longer any IO-APICs in the Core IO's
+devices. IO-APIC is only in the PCH. Devices connected to the Core IO's
+PCIe Root Ports will use native MSI/MSI-X mechanisms.
+
+Mitigations
+===========
+
+The mitigations take the form of PCI quirks. The preference has been to
+first identify and make use of a means to disable the routing to the PCH.
+In such a case a quirk to disable boot interrupt generation can be
+added. [1]_
+
+Intel® 6300ESB I/O Controller Hub
+ Alternate Base Address Register:
+ BIE: Boot Interrupt Enable
+
+ == ===========================
+ 0 Boot interrupt is enabled.
+ 1 Boot interrupt is disabled.
+ == ===========================
+
+Intel® Sandy Bridge through Sky Lake based Xeon servers:
+ Coherent Interface Protocol Interrupt Control
+ dis_intx_route2pch/dis_intx_route2ich/dis_intx_route2dmi2:
+ When this bit is set. Local INTx messages received from the
+ Intel® Quick Data DMA/PCI Express ports are not routed to legacy
+ PCH - they are either converted into MSI via the integrated IO-APIC
+ (if the IO-APIC mask bit is clear in the appropriate entries)
+ or cause no further action (when mask bit is set)
+
+In the absence of a way to directly disable the routing, another approach
+has been to make use of PCI Interrupt pin to INTx routing tables for
+purposes of redirecting the interrupt handler to the rerouted interrupt
+line by default. Therefore, on chipsets where this INTx routing cannot be
+disabled, the Linux kernel will reroute the valid interrupt to its legacy
+interrupt. This redirection of the handler will prevent the occurrence of
+the spurious interrupt detection which would ordinarily disable the IRQ
+line due to excessive unhandled counts. [2]_
+
+The config option X86_REROUTE_FOR_BROKEN_BOOT_IRQS exists to enable (or
+disable) the redirection of the interrupt handler to the PCH interrupt
+line. The option can be overridden by either pci=ioapicreroute or
+pci=noioapicreroute. [3]_
+
+
+More Documentation
+==================
+
+There is an overview of the legacy interrupt handling in several datasheets
+(6300ESB and 6700PXH below). While largely the same, it provides insight
+into the evolution of its handling with chipsets.
+
+Example of disabling of the boot interrupt
+------------------------------------------
+
+ - Intel® 6300ESB I/O Controller Hub (Document # 300641-004US)
+ 5.7.3 Boot Interrupt
+ https://www.intel.com/content/dam/doc/datasheet/6300esb-io-controller-hub-datasheet.pdf
+
+ - Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families
+ Datasheet - Volume 2: Registers (Document # 330784-003)
+ 6.6.41 cipintrc Coherent Interface Protocol Interrupt Control
+ https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/xeon-e5-v3-datasheet-vol-2.pdf
+
+Example of handler rerouting
+----------------------------
+
+ - Intel® 6700PXH 64-bit PCI Hub (Document # 302628)
+ 2.15.2 PCI Express Legacy INTx Support and Boot Interrupt
+ https://www.intel.com/content/dam/doc/datasheet/6700pxh-64-bit-pci-hub-datasheet.pdf
+
+
+If you have any legacy PCI interrupt questions that aren't answered, email me.
+
+Cheers,
+ Sean V Kelley
+ sean.v.kelley@linux.intel.com
+
+.. [1] https://lore.kernel.org/r/12131949181903-git-send-email-sassmann@suse.de/
+.. [2] https://lore.kernel.org/r/12131949182094-git-send-email-sassmann@suse.de/
+.. [3] https://lore.kernel.org/r/487C8EA7.6020205@suse.de/
diff --git a/Documentation/PCI/controller/index.rst b/Documentation/PCI/controller/index.rst
new file mode 100644
index 000000000000..c2ce9ccdcfa0
--- /dev/null
+++ b/Documentation/PCI/controller/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================
+PCI Native Host Bridge and Endpoint Drivers
+===========================================
+
+.. toctree::
+ :maxdepth: 2
+
+ rcar-pcie-firmware
diff --git a/Documentation/PCI/controller/rcar-pcie-firmware.rst b/Documentation/PCI/controller/rcar-pcie-firmware.rst
new file mode 100644
index 000000000000..67d3bf66e315
--- /dev/null
+++ b/Documentation/PCI/controller/rcar-pcie-firmware.rst
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================================
+Firmware of PCIe controller for Renesas R-Car V4H
+=================================================
+
+Renesas R-Car V4H (r8a779g0) has a PCIe controller, requiring a specific
+firmware download during startup.
+
+However, Renesas currently cannot distribute the firmware free of charge.
+
+The firmware file "104_PCIe_fw_addr_data_ver1.05.txt" (note that the file name
+might be different between different datasheet revisions) can be found in the
+datasheet encoded as text, and as such, the file's content must be converted
+back to binary form. This can be achieved using the following example script:
+
+.. code-block:: sh
+
+ $ awk '/^\s*0x[0-9A-Fa-f]{4}\s+0x[0-9A-Fa-f]{4}/ { print substr($2,5,2) substr($2,3,2) }' \
+ 104_PCIe_fw_addr_data_ver1.05.txt | \
+ xxd -p -r > rcar_gen4_pcie.bin
+
+Once the text content has been converted into a binary firmware file, verify
+its checksum as follows:
+
+.. code-block:: sh
+
+ $ sha1sum rcar_gen4_pcie.bin
+ 1d0bd4b189b4eb009f5d564b1f93a79112994945 rcar_gen4_pcie.bin
+
+The resulting binary file called "rcar_gen4_pcie.bin" should be placed in the
+"/lib/firmware" directory before the driver runs.
diff --git a/Documentation/PCI/endpoint/function/binding/pci-ntb.rst b/Documentation/PCI/endpoint/function/binding/pci-ntb.rst
new file mode 100644
index 000000000000..40253d3d5163
--- /dev/null
+++ b/Documentation/PCI/endpoint/function/binding/pci-ntb.rst
@@ -0,0 +1,38 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+PCI NTB Endpoint Function
+==========================
+
+1) Create a subdirectory to pci_epf_ntb directory in configfs.
+
+Standard EPF Configurable Fields:
+
+================ ===========================================================
+vendorid should be 0x104c
+deviceid should be 0xb00d for TI's J721E SoC
+revid don't care
+progif_code don't care
+subclass_code should be 0x00
+baseclass_code should be 0x5
+cache_line_size don't care
+subsys_vendor_id don't care
+subsys_id don't care
+interrupt_pin don't care
+msi_interrupts don't care
+msix_interrupts don't care
+================ ===========================================================
+
+2) Create a subdirectory to directory created in 1
+
+NTB EPF specific configurable fields:
+
+================ ===========================================================
+db_count Number of doorbells; default = 4
+mw1 size of memory window1
+mw2 size of memory window2
+mw3 size of memory window3
+mw4 size of memory window4
+num_mws Number of memory windows; max = 4
+spad_count Number of scratchpad registers; default = 64
+================ ===========================================================
diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.rst b/Documentation/PCI/endpoint/function/binding/pci-test.rst
new file mode 100644
index 000000000000..57ee866fb165
--- /dev/null
+++ b/Documentation/PCI/endpoint/function/binding/pci-test.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+PCI Test Endpoint Function
+==========================
+
+name: Should be "pci_epf_test" to bind to the pci_epf_test driver.
+
+Configurable Fields:
+
+================ ===========================================================
+vendorid should be 0x104c
+deviceid should be 0xb500 for DRA74x and 0xb501 for DRA72x
+revid don't care
+progif_code don't care
+subclass_code don't care
+baseclass_code should be 0xff
+cache_line_size don't care
+subsys_vendor_id don't care
+subsys_id don't care
+interrupt_pin Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD
+msi_interrupts Should be 1 to 32 depending on the number of MSI interrupts
+ to test
+msix_interrupts Should be 1 to 2048 depending on the number of MSI-X
+ interrupts to test
+================ ===========================================================
diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
new file mode 100644
index 000000000000..dd1f62e731c9
--- /dev/null
+++ b/Documentation/PCI/endpoint/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+PCI Endpoint Framework
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ pci-endpoint
+ pci-endpoint-cfs
+ pci-test-function
+ pci-test-howto
+ pci-ntb-function
+ pci-ntb-howto
+ pci-vntb-function
+ pci-vntb-howto
+ pci-nvme-function
+
+ function/binding/pci-test
+ function/binding/pci-ntb
diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
new file mode 100644
index 000000000000..e69c2872ce3b
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
@@ -0,0 +1,138 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+Configuring PCI Endpoint Using CONFIGFS
+=======================================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
+PCI endpoint function and to bind the endpoint function
+with the endpoint controller. (For introducing other mechanisms to
+configure the PCI Endpoint Function refer to [1]).
+
+Mounting configfs
+=================
+
+The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
+directory. configfs can be mounted using the following command::
+
+ mount -t configfs none /sys/kernel/config
+
+Directory Structure
+===================
+
+The pci_ep configfs has two directories at its root: controllers and
+functions. Every EPC device present in the system will have an entry in
+the *controllers* directory and every EPF driver present in the system
+will have an entry in the *functions* directory.
+::
+
+ /sys/kernel/config/pci_ep/
+ .. controllers/
+ .. functions/
+
+Creating EPF Device
+===================
+
+Every registered EPF driver will be listed in controllers directory. The
+entries corresponding to EPF driver will be created by the EPF core.
+::
+
+ /sys/kernel/config/pci_ep/functions/
+ .. <EPF Driver1>/
+ ... <EPF Device 11>/
+ ... <EPF Device 21>/
+ ... <EPF Device 31>/
+ .. <EPF Driver2>/
+ ... <EPF Device 12>/
+ ... <EPF Device 22>/
+
+In order to create a <EPF device> of the type probed by <EPF Driver>, the
+user has to create a directory inside <EPF DriverN>.
+
+Every <EPF device> directory consists of the following entries that can be
+used to configure the standard configuration header of the endpoint function.
+(These entries are created by the framework when any new <EPF Device> is
+created)
+::
+
+ .. <EPF Driver1>/
+ ... <EPF Device 11>/
+ ... vendorid
+ ... deviceid
+ ... revid
+ ... progif_code
+ ... subclass_code
+ ... baseclass_code
+ ... cache_line_size
+ ... subsys_vendor_id
+ ... subsys_id
+ ... interrupt_pin
+ ... <Symlink EPF Device 31>/
+ ... primary/
+ ... <Symlink EPC Device1>/
+ ... secondary/
+ ... <Symlink EPC Device2>/
+
+If an EPF device has to be associated with 2 EPCs (like in the case of
+Non-transparent bridge), symlink of endpoint controller connected to primary
+interface should be added in 'primary' directory and symlink of endpoint
+controller connected to secondary interface should be added in 'secondary'
+directory.
+
+The <EPF Device> directory can have a list of symbolic links
+(<Symlink EPF Device 31>) to other <EPF Device>. These symbolic links should
+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 an EPC device.
+
+EPC Device
+==========
+
+Every registered EPC device will be listed in controllers directory. The
+entries corresponding to EPC device will be created by the EPC core.
+::
+
+ /sys/kernel/config/pci_ep/controllers/
+ .. <EPC Device1>/
+ ... <Symlink EPF Device11>/
+ ... <Symlink EPF Device12>/
+ ... start
+ .. <EPC Device2>/
+ ... <Symlink EPF Device21>/
+ ... <Symlink EPF Device22>/
+ ... start
+
+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 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
+establish the link with the host. This is usually done after
+all the EPF devices are created and linked with the EPC device.
+::
+
+ | controllers/
+ | <Directory: EPC name>/
+ | <Symbolic Link: Function>
+ | start
+ | functions/
+ | <Directory: EPF driver>/
+ | <Directory: EPF device>/
+ | vendorid
+ | deviceid
+ | revid
+ | progif_code
+ | subclass_code
+ | baseclass_code
+ | cache_line_size
+ | subsys_vendor_id
+ | subsys_id
+ | interrupt_pin
+ | function
+
+[1] Documentation/PCI/endpoint/pci-endpoint.rst
diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst
new file mode 100644
index 000000000000..0741c8cbd74e
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-endpoint.rst
@@ -0,0 +1,259 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+This document is a guide to use the PCI Endpoint Framework in order to create
+endpoint controller driver, endpoint function driver, and using configfs
+interface to bind the function driver to the controller driver.
+
+Introduction
+============
+
+Linux has a comprehensive PCI subsystem to support PCI controllers that
+operates in Root Complex mode. The subsystem has capability to scan PCI bus,
+assign memory resources and IRQ resources, load PCI driver (based on
+vendor ID, device ID), support other services like hot-plug, power management,
+advanced error reporting and virtual channels.
+
+However the PCI controller IP integrated in some SoCs is capable of operating
+either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
+add endpoint mode support in Linux. This will help to run Linux in an
+EP system which can have a wide variety of use cases from testing or
+validation, co-processor accelerator, etc.
+
+PCI Endpoint Core
+=================
+
+The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
+library, the Endpoint Function library, and the configfs layer to bind the
+endpoint function with the endpoint controller.
+
+PCI Endpoint Controller(EPC) Library
+------------------------------------
+
+The EPC library provides APIs to be used by the controller that can operate
+in endpoint mode. It also provides APIs to be used by function driver/library
+in order to implement a particular endpoint function.
+
+APIs for the PCI controller Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the PCI Endpoint core provides to be used
+by the PCI controller driver.
+
+* devm_pci_epc_create()/pci_epc_create()
+
+ The PCI controller driver should implement the following ops:
+
+ * write_header: ops to populate configuration space header
+ * set_bar: ops to configure the BAR
+ * clear_bar: ops to reset the BAR
+ * alloc_addr_space: ops to allocate in PCI controller address space
+ * free_addr_space: ops to free the allocated address space
+ * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt
+ * start: ops to start the PCI link
+ * stop: ops to stop the PCI link
+
+ The PCI controller driver can then create a new EPC device by invoking
+ devm_pci_epc_create()/pci_epc_create().
+
+* pci_epc_destroy()
+
+ The PCI controller driver can destroy the EPC device created by
+ pci_epc_create() using pci_epc_destroy().
+
+* pci_epc_linkup()
+
+ In order to notify all the function devices that the EPC device to which
+ they are linked has established a link with the host, the PCI controller
+ driver should invoke pci_epc_linkup().
+
+* pci_epc_mem_init()
+
+ Initialize the pci_epc_mem structure used for allocating EPC addr space.
+
+* pci_epc_mem_exit()
+
+ Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
+
+
+EPC APIs for the PCI Endpoint Function Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the PCI Endpoint core provides to be used
+by the PCI endpoint function driver.
+
+* pci_epc_write_header()
+
+ The PCI endpoint function driver should use pci_epc_write_header() to
+ write the standard configuration header to the endpoint controller.
+
+* pci_epc_set_bar()
+
+ The PCI endpoint function driver should use pci_epc_set_bar() to configure
+ the Base Address Register in order for the host to assign PCI addr space.
+ Register space of the function driver is usually configured
+ using this API.
+
+* pci_epc_clear_bar()
+
+ The PCI endpoint function driver should use pci_epc_clear_bar() to reset
+ the BAR.
+
+* pci_epc_raise_irq()
+
+ The PCI endpoint function driver should use pci_epc_raise_irq() to raise
+ Legacy Interrupt, MSI or MSI-X Interrupt.
+
+* pci_epc_mem_alloc_addr()
+
+ The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
+ allocate memory address from EPC addr space which is required to access
+ RC's buffer
+
+* pci_epc_mem_free_addr()
+
+ The PCI endpoint function driver should use pci_epc_mem_free_addr() to
+ free the memory space allocated using pci_epc_mem_alloc_addr().
+
+* pci_epc_map_addr()
+
+ A PCI endpoint function driver should use pci_epc_map_addr() to map to a RC
+ PCI address the CPU address of local memory obtained with
+ pci_epc_mem_alloc_addr().
+
+* pci_epc_unmap_addr()
+
+ A PCI endpoint function driver should use pci_epc_unmap_addr() to unmap the
+ CPU address of local memory mapped to a RC address with pci_epc_map_addr().
+
+* pci_epc_mem_map()
+
+ A PCI endpoint controller may impose constraints on the RC PCI addresses that
+ can be mapped. The function pci_epc_mem_map() allows endpoint function
+ drivers to allocate and map controller memory while handling such
+ constraints. This function will determine the size of the memory that must be
+ allocated with pci_epc_mem_alloc_addr() for successfully mapping a RC PCI
+ address range. This function will also indicate the size of the PCI address
+ range that was actually mapped, which can be less than the requested size, as
+ well as the offset into the allocated memory to use for accessing the mapped
+ RC PCI address range.
+
+* pci_epc_mem_unmap()
+
+ A PCI endpoint function driver can use pci_epc_mem_unmap() to unmap and free
+ controller memory that was allocated and mapped using pci_epc_mem_map().
+
+
+Other EPC APIs
+~~~~~~~~~~~~~~
+
+There are other APIs provided by the EPC library. These are used for binding
+the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
+using these APIs.
+
+* pci_epc_get()
+
+ Get a reference to the PCI endpoint controller based on the device name of
+ the controller.
+
+* pci_epc_put()
+
+ Release the reference to the PCI endpoint controller obtained using
+ pci_epc_get()
+
+* pci_epc_add_epf()
+
+ Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
+ can have up to 8 functions according to the specification.
+
+* pci_epc_remove_epf()
+
+ Remove the PCI endpoint function from PCI endpoint controller.
+
+* pci_epc_start()
+
+ The PCI endpoint function driver should invoke pci_epc_start() once it
+ has configured the endpoint function and wants to start the PCI link.
+
+* pci_epc_stop()
+
+ The PCI endpoint function driver should invoke pci_epc_stop() to stop
+ the PCI LINK.
+
+
+PCI Endpoint Function(EPF) Library
+----------------------------------
+
+The EPF library provides APIs to be used by the function driver and the EPC
+library to provide endpoint mode functionality.
+
+EPF APIs for the PCI Endpoint Function Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the PCI Endpoint core provides to be used
+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 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
+
+ The PCI Function driver can then register the PCI EPF driver by using
+ pci_epf_register_driver().
+
+* pci_epf_unregister_driver()
+
+ The PCI Function driver can unregister the PCI EPF driver by using
+ pci_epf_unregister_driver().
+
+* pci_epf_alloc_space()
+
+ The PCI Function driver can allocate space for a particular BAR using
+ pci_epf_alloc_space().
+
+* pci_epf_free_space()
+
+ The PCI Function driver can free the allocated space
+ (using pci_epf_alloc_space) by invoking pci_epf_free_space().
+
+APIs for the PCI Endpoint Controller Library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the PCI Endpoint core provides to be used
+by the PCI endpoint controller library.
+
+* pci_epf_linkup()
+
+ The PCI endpoint controller library invokes pci_epf_linkup() when the
+ EPC device has established the connection to the host.
+
+Other EPF APIs
+~~~~~~~~~~~~~~
+
+There are other APIs provided by the EPF library. These are used to notify
+the function driver when the EPF device is bound to the EPC device.
+pci-ep-cfs.c can be used as reference for using these APIs.
+
+* pci_epf_create()
+
+ Create a new PCI EPF device by passing the name of the PCI EPF device.
+ This name will be used to bind the EPF device to a EPF driver.
+
+* pci_epf_destroy()
+
+ Destroy the created PCI EPF device.
+
+* pci_epf_bind()
+
+ pci_epf_bind() should be invoked when the EPF device has been bound to
+ an EPC device.
+
+* pci_epf_unbind()
+
+ pci_epf_unbind() should be invoked when the binding between EPC device
+ and EPF device is lost.
diff --git a/Documentation/PCI/endpoint/pci-ntb-function.rst b/Documentation/PCI/endpoint/pci-ntb-function.rst
new file mode 100644
index 000000000000..3b9d836a4924
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-ntb-function.rst
@@ -0,0 +1,348 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI NTB Function
+=================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+PCI Non-Transparent Bridges (NTB) allow two host systems to communicate
+with each other by exposing each host as a device to the other host.
+NTBs typically support the ability to generate interrupts on the remote
+machine, expose memory ranges as BARs, and perform DMA. They also support
+scratchpads, which are areas of memory within the NTB that are accessible
+from both machines.
+
+PCI NTB Function allows two different systems (or hosts) to communicate
+with each other by configuring the endpoint instances in such a way that
+transactions from one system are routed to the other system.
+
+In the below diagram, PCI NTB function configures the SoC with multiple
+PCI Endpoint (EP) instances in such a way that transactions from one EP
+controller are routed to the other EP controller. Once PCI NTB function
+configures the SoC with multiple EP instances, HOST1 and HOST2 can
+communicate with each other using SoC as a bridge.
+
+.. code-block:: text
+
+ +-------------+ +-------------+
+ | | | |
+ | HOST1 | | HOST2 |
+ | | | |
+ +------^------+ +------^------+
+ | |
+ | |
+ +---------|-------------------------------------------------|---------+
+ | +------v------+ +------v------+ |
+ | | | | | |
+ | | EP | | EP | |
+ | | CONTROLLER1 | | CONTROLLER2 | |
+ | | <-----------------------------------> | |
+ | | | | | |
+ | | | | | |
+ | | | SoC With Multiple EP Instances | | |
+ | | | (Configured using NTB Function) | | |
+ | +-------------+ +-------------+ |
+ +---------------------------------------------------------------------+
+
+Constructs used for Implementing NTB
+====================================
+
+ 1) Config Region
+ 2) Self Scratchpad Registers
+ 3) Peer Scratchpad Registers
+ 4) Doorbell (DB) Registers
+ 5) Memory Window (MW)
+
+
+Config Region:
+--------------
+
+Config Region is a construct that is specific to NTB implemented using NTB
+Endpoint Function Driver. The host and endpoint side NTB function driver will
+exchange information with each other using this region. Config Region has
+Control/Status Registers for configuring the Endpoint Controller. Host can
+write into this region for configuring the outbound Address Translation Unit
+(ATU) and to indicate the link status. Endpoint can indicate the status of
+commands issued by host in this region. Endpoint can also indicate the
+scratchpad offset and number of memory windows to the host using this region.
+
+The format of Config Region is given below. All the fields here are 32 bits.
+
+.. code-block:: text
+
+ +------------------------+
+ | COMMAND |
+ +------------------------+
+ | ARGUMENT |
+ +------------------------+
+ | STATUS |
+ +------------------------+
+ | TOPOLOGY |
+ +------------------------+
+ | ADDRESS (LOWER 32) |
+ +------------------------+
+ | ADDRESS (UPPER 32) |
+ +------------------------+
+ | SIZE |
+ +------------------------+
+ | NO OF MEMORY WINDOW |
+ +------------------------+
+ | MEMORY WINDOW1 OFFSET |
+ +------------------------+
+ | SPAD OFFSET |
+ +------------------------+
+ | SPAD COUNT |
+ +------------------------+
+ | DB ENTRY SIZE |
+ +------------------------+
+ | DB DATA |
+ +------------------------+
+ | : |
+ +------------------------+
+ | : |
+ +------------------------+
+ | DB DATA |
+ +------------------------+
+
+
+ COMMAND:
+
+ NTB function supports three commands:
+
+ CMD_CONFIGURE_DOORBELL (0x1): Command to configure doorbell. Before
+ invoking this command, the host should allocate and initialize
+ MSI/MSI-X vectors (i.e., initialize the MSI/MSI-X Capability in the
+ Endpoint). The endpoint on receiving this command will configure
+ the outbound ATU such that transactions to Doorbell BAR will be routed
+ to the MSI/MSI-X address programmed by the host. The ARGUMENT
+ register should be populated with number of DBs to configure (in the
+ lower 16 bits) and if MSI or MSI-X should be configured (BIT 16).
+
+ CMD_CONFIGURE_MW (0x2): Command to configure memory window (MW). The
+ host invokes this command after allocating a buffer that can be
+ accessed by remote host. The allocated address should be programmed
+ in the ADDRESS register (64 bit), the size should be programmed in
+ the SIZE register and the memory window index should be programmed
+ in the ARGUMENT register. The endpoint on receiving this command
+ will configure the outbound ATU such that transactions to MW BAR
+ are routed to the address provided by the host.
+
+ CMD_LINK_UP (0x3): Command to indicate an NTB application is
+ bound to the EP device on the host side. Once the endpoint
+ receives this command from both the hosts, the endpoint will
+ raise a LINK_UP event to both the hosts to indicate the host
+ NTB applications can start communicating with each other.
+
+ ARGUMENT:
+
+ The value of this register is based on the commands issued in
+ command register. See COMMAND section for more information.
+
+ TOPOLOGY:
+
+ Set to NTB_TOPO_B2B_USD for Primary interface
+ Set to NTB_TOPO_B2B_DSD for Secondary interface
+
+ ADDRESS/SIZE:
+
+ Address and Size to be used while configuring the memory window.
+ See "CMD_CONFIGURE_MW" for more info.
+
+ MEMORY WINDOW1 OFFSET:
+
+ Memory Window 1 and Doorbell registers are packed together in the
+ same BAR. The initial portion of the region will have doorbell
+ registers and the latter portion of the region is for memory window 1.
+ This register will specify the offset of the memory window 1.
+
+ NO OF MEMORY WINDOW:
+
+ Specifies the number of memory windows supported by the NTB device.
+
+ SPAD OFFSET:
+
+ Self scratchpad region and config region are packed together in the
+ same BAR. The initial portion of the region will have config region
+ and the latter portion of the region is for self scratchpad. This
+ register will specify the offset of the self scratchpad registers.
+
+ SPAD COUNT:
+
+ Specifies the number of scratchpad registers supported by the NTB
+ device.
+
+ DB ENTRY SIZE:
+
+ Used to determine the offset within the DB BAR that should be written
+ in order to raise doorbell. EPF NTB can use either MSI or MSI-X to
+ ring doorbell (MSI-X support will be added later). MSI uses same
+ address for all the interrupts and MSI-X can provide different
+ addresses for different interrupts. The MSI/MSI-X address is provided
+ by the host and the address it gives is based on the MSI/MSI-X
+ implementation supported by the host. For instance, ARM platform
+ using GIC ITS will have the same MSI-X address for all the interrupts.
+ In order to support all the combinations and use the same mechanism
+ for both MSI and MSI-X, EPF NTB allocates a separate region in the
+ Outbound Address Space for each of the interrupts. This region will
+ be mapped to the MSI/MSI-X address provided by the host. If a host
+ provides the same address for all the interrupts, all the regions
+ will be translated to the same address. If a host provides different
+ addresses, the regions will be translated to different addresses. This
+ will ensure there is no difference while raising the doorbell.
+
+ DB DATA:
+
+ EPF NTB supports 32 interrupts, so there are 32 DB DATA registers.
+ This holds the MSI/MSI-X data that has to be written to MSI address
+ for raising doorbell interrupt. This will be populated by EPF NTB
+ while invoking CMD_CONFIGURE_DOORBELL.
+
+Scratchpad Registers:
+---------------------
+
+ Each host has its own register space allocated in the memory of NTB endpoint
+ controller. They are both readable and writable from both sides of the bridge.
+ They are used by applications built over NTB and can be used to pass control
+ and status information between both sides of a device.
+
+ Scratchpad registers has 2 parts
+ 1) Self Scratchpad: Host's own register space
+ 2) Peer Scratchpad: Remote host's register space.
+
+Doorbell Registers:
+-------------------
+
+ Doorbell Registers are used by the hosts to interrupt each other.
+
+Memory Window:
+--------------
+
+ Actual transfer of data between the two hosts will happen using the
+ memory window.
+
+Modeling Constructs:
+====================
+
+There are 5 or more distinct regions (config, self scratchpad, peer
+scratchpad, doorbell, one or more memory windows) to be modeled to achieve
+NTB functionality. At least one memory window is required while more than
+one is permitted. All these regions should be mapped to BARs for hosts to
+access these regions.
+
+If one 32-bit BAR is allocated for each of these regions, the scheme would
+look like this:
+
+====== ===============
+BAR NO CONSTRUCTS USED
+====== ===============
+BAR0 Config Region
+BAR1 Self Scratchpad
+BAR2 Peer Scratchpad
+BAR3 Doorbell
+BAR4 Memory Window 1
+BAR5 Memory Window 2
+====== ===============
+
+However if we allocate a separate BAR for each of the regions, there would not
+be enough BARs for all the regions in a platform that supports only 64-bit
+BARs.
+
+In order to be supported by most of the platforms, the regions should be
+packed and mapped to BARs in a way that provides NTB functionality and
+also makes sure the host doesn't access any region that it is not supposed
+to.
+
+The following scheme is used in EPF NTB Function:
+
+====== ===============================
+BAR NO CONSTRUCTS USED
+====== ===============================
+BAR0 Config Region + Self Scratchpad
+BAR1 Peer Scratchpad
+BAR2 Doorbell + Memory Window 1
+BAR3 Memory Window 2
+BAR4 Memory Window 3
+BAR5 Memory Window 4
+====== ===============================
+
+With this scheme, for the basic NTB functionality 3 BARs should be sufficient.
+
+Modeling Config/Scratchpad Region:
+----------------------------------
+
+.. code-block:: text
+
+ +-----------------+------->+------------------+ +-----------------+
+ | BAR0 | | CONFIG REGION | | BAR0 |
+ +-----------------+----+ +------------------+<-------+-----------------+
+ | BAR1 | | |SCRATCHPAD REGION | | BAR1 |
+ +-----------------+ +-->+------------------+<-------+-----------------+
+ | BAR2 | Local Memory | BAR2 |
+ +-----------------+ +-----------------+
+ | BAR3 | | BAR3 |
+ +-----------------+ +-----------------+
+ | BAR4 | | BAR4 |
+ +-----------------+ +-----------------+
+ | BAR5 | | BAR5 |
+ +-----------------+ +-----------------+
+ EP CONTROLLER 1 EP CONTROLLER 2
+
+Above diagram shows Config region + Scratchpad region for HOST1 (connected to
+EP controller 1) allocated in local memory. The HOST1 can access the config
+region and scratchpad region (self scratchpad) using BAR0 of EP controller 1.
+The peer host (HOST2 connected to EP controller 2) can also access this
+scratchpad region (peer scratchpad) using BAR1 of EP controller 2. This
+diagram shows the case where Config region and Scratchpad regions are allocated
+for HOST1, however the same is applicable for HOST2.
+
+Modeling Doorbell/Memory Window 1:
+----------------------------------
+
+.. code-block:: text
+
+ +-----------------+ +----->+----------------+-----------+-----------------+
+ | BAR0 | | | Doorbell 1 +-----------> MSI-X ADDRESS 1 |
+ +-----------------+ | +----------------+ +-----------------+
+ | BAR1 | | | Doorbell 2 +---------+ | |
+ +-----------------+----+ +----------------+ | | |
+ | BAR2 | | Doorbell 3 +-------+ | +-----------------+
+ +-----------------+----+ +----------------+ | +-> MSI-X ADDRESS 2 |
+ | BAR3 | | | Doorbell 4 +-----+ | +-----------------+
+ +-----------------+ | |----------------+ | | | |
+ | BAR4 | | | | | | +-----------------+
+ +-----------------+ | | MW1 +---+ | +-->+ MSI-X ADDRESS 3||
+ | BAR5 | | | | | | +-----------------+
+ +-----------------+ +----->-----------------+ | | | |
+ EP CONTROLLER 1 | | | | +-----------------+
+ | | | +---->+ MSI-X ADDRESS 4 |
+ +----------------+ | +-----------------+
+ EP CONTROLLER 2 | | |
+ (OB SPACE) | | |
+ +-------> MW1 |
+ | |
+ | |
+ +-----------------+
+ | |
+ | |
+ | |
+ | |
+ | |
+ +-----------------+
+ PCI Address Space
+ (Managed by HOST2)
+
+Above diagram shows how the doorbell and memory window 1 is mapped so that
+HOST1 can raise doorbell interrupt on HOST2 and also how HOST1 can access
+buffers exposed by HOST2 using memory window1 (MW1). Here doorbell and
+memory window 1 regions are allocated in EP controller 2 outbound (OB) address
+space. Allocating and configuring BARs for doorbell and memory window1
+is done during the initialization phase of NTB endpoint function driver.
+Mapping from EP controller 2 OB space to PCI address space is done when HOST2
+sends CMD_CONFIGURE_MW/CMD_CONFIGURE_DOORBELL.
+
+Modeling Optional Memory Windows:
+---------------------------------
+
+This is modeled the same was as MW1 but each of the additional memory windows
+is mapped to separate BARs.
diff --git a/Documentation/PCI/endpoint/pci-ntb-howto.rst b/Documentation/PCI/endpoint/pci-ntb-howto.rst
new file mode 100644
index 000000000000..4261e7157ef1
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-ntb-howto.rst
@@ -0,0 +1,158 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================================================
+PCI Non-Transparent Bridge (NTB) Endpoint Function (EPF) User Guide
+===================================================================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+This document is a guide to help users use pci-epf-ntb function driver
+and ntb_hw_epf host driver for NTB functionality. The list of steps to
+be followed in the host side and EP side is given below. For the hardware
+configuration and internals of NTB using configurable endpoints see
+Documentation/PCI/endpoint/pci-ntb-function.rst
+
+Endpoint Device
+===============
+
+Endpoint Controller Devices
+---------------------------
+
+For implementing NTB functionality at least two endpoint controller devices
+are required.
+
+To find the list of endpoint controller devices in the system::
+
+ # ls /sys/class/pci_epc/
+ 2900000.pcie-ep 2910000.pcie-ep
+
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
+ # ls /sys/kernel/config/pci_ep/controllers
+ 2900000.pcie-ep 2910000.pcie-ep
+
+
+Endpoint Function Drivers
+-------------------------
+
+To find the list of endpoint function drivers in the system::
+
+ # ls /sys/bus/pci-epf/drivers
+ pci_epf_ntb pci_epf_ntb
+
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
+ # ls /sys/kernel/config/pci_ep/functions
+ pci_epf_ntb pci_epf_ntb
+
+
+Creating pci-epf-ntb Device
+----------------------------
+
+PCI endpoint function device can be created using the configfs. To create
+pci-epf-ntb device, the following commands can be used::
+
+ # mount -t configfs none /sys/kernel/config
+ # cd /sys/kernel/config/pci_ep/
+ # mkdir functions/pci_epf_ntb/func1
+
+The "mkdir func1" above creates the pci-epf-ntb function device that will
+be probed by pci_epf_ntb driver.
+
+The PCI endpoint framework populates the directory with the following
+configurable fields::
+
+ # ls functions/pci_epf_ntb/func1
+ baseclass_code deviceid msi_interrupts pci-epf-ntb.0
+ progif_code secondary subsys_id vendorid
+ cache_line_size interrupt_pin msix_interrupts primary
+ revid subclass_code subsys_vendor_id
+
+The PCI endpoint function driver populates these entries with default values
+when the device is bound to the driver. The pci-epf-ntb driver populates
+vendorid with 0xffff and interrupt_pin with 0x0001::
+
+ # cat functions/pci_epf_ntb/func1/vendorid
+ 0xffff
+ # cat functions/pci_epf_ntb/func1/interrupt_pin
+ 0x0001
+
+
+Configuring pci-epf-ntb Device
+-------------------------------
+
+The user can configure the pci-epf-ntb device using its configfs entry. In order
+to change the vendorid and the deviceid, the following
+commands can be used::
+
+ # echo 0x104c > functions/pci_epf_ntb/func1/vendorid
+ # echo 0xb00d > functions/pci_epf_ntb/func1/deviceid
+
+The PCI endpoint framework also automatically creates a sub-directory in the
+function attribute directory. This sub-directory has the same name as the name
+of the function device and is populated with the following NTB specific
+attributes that can be configured by the user::
+
+ # ls functions/pci_epf_ntb/func1/pci_epf_ntb.0/
+ db_count mw1 mw2 mw3 mw4 num_mws
+ spad_count
+
+A sample configuration for NTB function is given below::
+
+ # echo 4 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/db_count
+ # echo 128 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/spad_count
+ # echo 2 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/num_mws
+ # echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw1
+ # echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw2
+
+Binding pci-epf-ntb Device to EP Controller
+--------------------------------------------
+
+NTB function device should be attached to two PCI endpoint controllers
+connected to the two hosts. Use the 'primary' and 'secondary' entries
+inside NTB function device to attach one PCI endpoint controller to
+primary interface and the other PCI endpoint controller to the secondary
+interface::
+
+ # ln -s controllers/2900000.pcie-ep/ functions/pci-epf-ntb/func1/primary
+ # ln -s controllers/2910000.pcie-ep/ functions/pci-epf-ntb/func1/secondary
+
+Once the above step is completed, both the PCI endpoint controllers are ready to
+establish a link with the host.
+
+
+Start the Link
+--------------
+
+In order for the endpoint device to establish a link with the host, the _start_
+field should be populated with '1'. For NTB, both the PCI endpoint controllers
+should establish link with the host::
+
+ # echo 1 > controllers/2900000.pcie-ep/start
+ # echo 1 > controllers/2910000.pcie-ep/start
+
+
+RootComplex Device
+==================
+
+lspci Output
+------------
+
+Note that the devices listed here correspond to the values populated in
+"Creating pci-epf-ntb Device" section above::
+
+ # lspci
+ 0000:00:00.0 PCI bridge: Texas Instruments Device b00d
+ 0000:01:00.0 RAM memory: Texas Instruments Device b00d
+
+
+Using ntb_hw_epf Device
+-----------------------
+
+The host side software follows the standard NTB software architecture in Linux.
+All the existing client side NTB utilities like NTB Transport Client and NTB
+Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
+function device.
+
+For more information on NTB see
+:doc:`Non-Transparent Bridge <../../driver-api/ntb>`
diff --git a/Documentation/PCI/endpoint/pci-nvme-function.rst b/Documentation/PCI/endpoint/pci-nvme-function.rst
new file mode 100644
index 000000000000..a68015317f7f
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-nvme-function.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI NVMe Function
+=================
+
+:Author: Damien Le Moal <dlemoal@kernel.org>
+
+The PCI NVMe endpoint function implements a PCI NVMe controller using the NVMe
+subsystem target core code. The driver for this function resides with the NVMe
+subsystem as drivers/nvme/target/pci-epf.c.
+
+See Documentation/nvme/nvme-pci-endpoint-target.rst for more details.
diff --git a/Documentation/PCI/endpoint/pci-test-function.rst b/Documentation/PCI/endpoint/pci-test-function.rst
new file mode 100644
index 000000000000..3c8521d7aa31
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-test-function.rst
@@ -0,0 +1,103 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI Test Function
+=================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+Traditionally PCI RC has always been validated by using standard
+PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
+However with the addition of EP-core in linux kernel, it is possible
+to configure a PCI controller that can operate in EP mode to work as
+a test device.
+
+The PCI endpoint test device is a virtual device (defined in software)
+used to test the endpoint functionality and serve as a sample driver
+for other PCI endpoint devices (to use the EP framework).
+
+The PCI endpoint test device has the following registers:
+
+ 1) PCI_ENDPOINT_TEST_MAGIC
+ 2) PCI_ENDPOINT_TEST_COMMAND
+ 3) PCI_ENDPOINT_TEST_STATUS
+ 4) PCI_ENDPOINT_TEST_SRC_ADDR
+ 5) PCI_ENDPOINT_TEST_DST_ADDR
+ 6) PCI_ENDPOINT_TEST_SIZE
+ 7) PCI_ENDPOINT_TEST_CHECKSUM
+ 8) PCI_ENDPOINT_TEST_IRQ_TYPE
+ 9) PCI_ENDPOINT_TEST_IRQ_NUMBER
+
+* PCI_ENDPOINT_TEST_MAGIC
+
+This register will be used to test BAR0. A known pattern will be written
+and read back from MAGIC register to verify BAR0.
+
+* PCI_ENDPOINT_TEST_COMMAND
+
+This register will be used by the host driver to indicate the function
+that the endpoint device must perform.
+
+======== ================================================================
+Bitfield Description
+======== ================================================================
+Bit 0 raise legacy IRQ
+Bit 1 raise MSI IRQ
+Bit 2 raise MSI-X IRQ
+Bit 3 read command (read data from RC buffer)
+Bit 4 write command (write data to RC buffer)
+Bit 5 copy command (copy data from one RC buffer to another RC buffer)
+======== ================================================================
+
+* PCI_ENDPOINT_TEST_STATUS
+
+This register reflects the status of the PCI endpoint device.
+
+======== ==============================
+Bitfield Description
+======== ==============================
+Bit 0 read success
+Bit 1 read fail
+Bit 2 write success
+Bit 3 write fail
+Bit 4 copy success
+Bit 5 copy fail
+Bit 6 IRQ raised
+Bit 7 source address is invalid
+Bit 8 destination address is invalid
+======== ==============================
+
+* PCI_ENDPOINT_TEST_SRC_ADDR
+
+This register contains the source address (RC buffer address) for the
+COPY/READ command.
+
+* PCI_ENDPOINT_TEST_DST_ADDR
+
+This register contains the destination address (RC buffer address) for
+the COPY/WRITE command.
+
+* PCI_ENDPOINT_TEST_IRQ_TYPE
+
+This register contains the interrupt type (Legacy/MSI) triggered
+for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
+
+Possible types:
+
+====== ==
+Legacy 0
+MSI 1
+MSI-X 2
+====== ==
+
+* PCI_ENDPOINT_TEST_IRQ_NUMBER
+
+This register contains the triggered ID interrupt.
+
+Admissible values:
+
+====== ===========
+Legacy 0
+MSI [1 .. 32]
+MSI-X [1 .. 2048]
+====== ===========
diff --git a/Documentation/PCI/endpoint/pci-test-howto.rst b/Documentation/PCI/endpoint/pci-test-howto.rst
new file mode 100644
index 000000000000..dd66858cde46
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-test-howto.rst
@@ -0,0 +1,220 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+PCI Test User Guide
+===================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+This document is a guide to help users use pci-epf-test function driver
+and pci_endpoint_test host driver for testing PCI. The list of steps to
+be followed in the host side and EP side is given below.
+
+Endpoint Device
+===============
+
+Endpoint Controller Devices
+---------------------------
+
+To find the list of endpoint controller devices in the system::
+
+ # ls /sys/class/pci_epc/
+ 51000000.pcie_ep
+
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
+ # ls /sys/kernel/config/pci_ep/controllers
+ 51000000.pcie_ep
+
+
+Endpoint Function Drivers
+-------------------------
+
+To find the list of endpoint function drivers in the system::
+
+ # ls /sys/bus/pci-epf/drivers
+ pci_epf_test
+
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
+ # ls /sys/kernel/config/pci_ep/functions
+ pci_epf_test
+
+
+Creating pci-epf-test Device
+----------------------------
+
+PCI endpoint function device can be created using the configfs. To create
+pci-epf-test device, the following commands can be used::
+
+ # mount -t configfs none /sys/kernel/config
+ # cd /sys/kernel/config/pci_ep/
+ # mkdir functions/pci_epf_test/func1
+
+The "mkdir func1" above creates the pci-epf-test function device that will
+be probed by pci_epf_test driver.
+
+The PCI endpoint framework populates the directory with the following
+configurable fields::
+
+ # ls functions/pci_epf_test/func1
+ baseclass_code interrupt_pin progif_code subsys_id
+ cache_line_size msi_interrupts revid subsys_vendorid
+ deviceid msix_interrupts subclass_code vendorid
+
+The PCI endpoint function driver populates these entries with default values
+when the device is bound to the driver. The pci-epf-test driver populates
+vendorid with 0xffff and interrupt_pin with 0x0001::
+
+ # cat functions/pci_epf_test/func1/vendorid
+ 0xffff
+ # cat functions/pci_epf_test/func1/interrupt_pin
+ 0x0001
+
+
+Configuring pci-epf-test Device
+-------------------------------
+
+The user can configure the pci-epf-test device using configfs entry. In order
+to change the vendorid and the number of MSI interrupts used by the function
+device, the following commands can be used::
+
+ # echo 0x104c > functions/pci_epf_test/func1/vendorid
+ # echo 0xb500 > functions/pci_epf_test/func1/deviceid
+ # echo 32 > functions/pci_epf_test/func1/msi_interrupts
+ # echo 2048 > functions/pci_epf_test/func1/msix_interrupts
+
+
+Binding pci-epf-test Device to EP Controller
+--------------------------------------------
+
+In order for the endpoint function device to be useful, it has to be bound to
+a PCI endpoint controller driver. Use the configfs to bind the function
+device to one of the controller driver present in the system::
+
+ # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
+
+Once the above step is completed, the PCI endpoint is ready to establish a link
+with the host.
+
+
+Start the Link
+--------------
+
+In order for the endpoint device to establish a link with the host, the _start_
+field should be populated with '1'::
+
+ # echo 1 > controllers/51000000.pcie_ep/start
+
+
+RootComplex Device
+==================
+
+lspci Output
+------------
+
+Note that the devices listed here correspond to the value populated in 1.4
+above::
+
+ 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
+ 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
+
+
+Using Endpoint Test function Device
+-----------------------------------
+
+Kselftest added in tools/testing/selftests/pci_endpoint can be used to run all
+the default PCI endpoint tests. To build the Kselftest for PCI endpoint
+subsystem, the following commands should be used::
+
+ # cd <kernel-dir>
+ # make -C tools/testing/selftests/pci_endpoint
+
+or if you desire to compile and install in your system::
+
+ # cd <kernel-dir>
+ # make -C tools/testing/selftests/pci_endpoint INSTALL_PATH=/usr/bin install
+
+The test will be located in <rootfs>/usr/bin/
+
+Kselftest Output
+~~~~~~~~~~~~~~~~
+::
+
+ # pci_endpoint_test
+ TAP version 13
+ 1..16
+ # Starting 16 tests from 9 test cases.
+ # RUN pci_ep_bar.BAR0.BAR_TEST ...
+ # OK pci_ep_bar.BAR0.BAR_TEST
+ ok 1 pci_ep_bar.BAR0.BAR_TEST
+ # RUN pci_ep_bar.BAR1.BAR_TEST ...
+ # OK pci_ep_bar.BAR1.BAR_TEST
+ ok 2 pci_ep_bar.BAR1.BAR_TEST
+ # RUN pci_ep_bar.BAR2.BAR_TEST ...
+ # OK pci_ep_bar.BAR2.BAR_TEST
+ ok 3 pci_ep_bar.BAR2.BAR_TEST
+ # RUN pci_ep_bar.BAR3.BAR_TEST ...
+ # OK pci_ep_bar.BAR3.BAR_TEST
+ ok 4 pci_ep_bar.BAR3.BAR_TEST
+ # RUN pci_ep_bar.BAR4.BAR_TEST ...
+ # OK pci_ep_bar.BAR4.BAR_TEST
+ ok 5 pci_ep_bar.BAR4.BAR_TEST
+ # RUN pci_ep_bar.BAR5.BAR_TEST ...
+ # OK pci_ep_bar.BAR5.BAR_TEST
+ ok 6 pci_ep_bar.BAR5.BAR_TEST
+ # RUN pci_ep_basic.CONSECUTIVE_BAR_TEST ...
+ # OK pci_ep_basic.CONSECUTIVE_BAR_TEST
+ ok 7 pci_ep_basic.CONSECUTIVE_BAR_TEST
+ # RUN pci_ep_basic.LEGACY_IRQ_TEST ...
+ # OK pci_ep_basic.LEGACY_IRQ_TEST
+ ok 8 pci_ep_basic.LEGACY_IRQ_TEST
+ # RUN pci_ep_basic.MSI_TEST ...
+ # OK pci_ep_basic.MSI_TEST
+ ok 9 pci_ep_basic.MSI_TEST
+ # RUN pci_ep_basic.MSIX_TEST ...
+ # OK pci_ep_basic.MSIX_TEST
+ ok 10 pci_ep_basic.MSIX_TEST
+ # RUN pci_ep_data_transfer.memcpy.READ_TEST ...
+ # OK pci_ep_data_transfer.memcpy.READ_TEST
+ ok 11 pci_ep_data_transfer.memcpy.READ_TEST
+ # RUN pci_ep_data_transfer.memcpy.WRITE_TEST ...
+ # OK pci_ep_data_transfer.memcpy.WRITE_TEST
+ ok 12 pci_ep_data_transfer.memcpy.WRITE_TEST
+ # RUN pci_ep_data_transfer.memcpy.COPY_TEST ...
+ # OK pci_ep_data_transfer.memcpy.COPY_TEST
+ ok 13 pci_ep_data_transfer.memcpy.COPY_TEST
+ # RUN pci_ep_data_transfer.dma.READ_TEST ...
+ # OK pci_ep_data_transfer.dma.READ_TEST
+ ok 14 pci_ep_data_transfer.dma.READ_TEST
+ # RUN pci_ep_data_transfer.dma.WRITE_TEST ...
+ # OK pci_ep_data_transfer.dma.WRITE_TEST
+ ok 15 pci_ep_data_transfer.dma.WRITE_TEST
+ # RUN pci_ep_data_transfer.dma.COPY_TEST ...
+ # OK pci_ep_data_transfer.dma.COPY_TEST
+ ok 16 pci_ep_data_transfer.dma.COPY_TEST
+ # PASSED: 16 / 16 tests passed.
+ # Totals: pass:16 fail:0 xfail:0 xpass:0 skip:0 error:0
+
+
+Testcase 16 (pci_ep_data_transfer.dma.COPY_TEST) will fail for most of the DMA
+capable endpoint controllers due to the absence of the MEMCPY over DMA. For such
+controllers, it is advisable to skip this testcase using this
+command::
+
+ # pci_endpoint_test -f pci_ep_bar -f pci_ep_basic -v memcpy -T COPY_TEST -v dma
+
+Kselftest EP Doorbell
+~~~~~~~~~~~~~~~~~~~~~
+
+If the Endpoint MSI controller is used for the doorbell usecase, run below
+command for testing it:
+
+ # pci_endpoint_test -f pcie_ep_doorbell
+
+ # Starting 1 tests from 1 test cases.
+ # RUN pcie_ep_doorbell.DOORBELL_TEST ...
+ # OK pcie_ep_doorbell.DOORBELL_TEST
+ ok 1 pcie_ep_doorbell.DOORBELL_TEST
+ # PASSED: 1 / 1 tests passed.
+ # Totals: pass:1 fail:0 xfail:0 xpass:0 skip:0 error:0
diff --git a/Documentation/PCI/endpoint/pci-vntb-function.rst b/Documentation/PCI/endpoint/pci-vntb-function.rst
new file mode 100644
index 000000000000..0c51f53ab972
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-vntb-function.rst
@@ -0,0 +1,129 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI vNTB Function
+=================
+
+:Author: Frank Li <Frank.Li@nxp.com>
+
+The difference between PCI NTB function and PCI vNTB function is
+
+PCI NTB function need at two endpoint instances and connect HOST1
+and HOST2.
+
+PCI vNTB function only use one host and one endpoint(EP), use NTB
+connect EP and PCI host
+
+.. code-block:: text
+
+
+ +------------+ +---------------------------------------+
+ | | | |
+ +------------+ | +--------------+
+ | NTB | | | NTB |
+ | NetDev | | | NetDev |
+ +------------+ | +--------------+
+ | NTB | | | NTB |
+ | Transfer | | | Transfer |
+ +------------+ | +--------------+
+ | | | | |
+ | PCI NTB | | | |
+ | EPF | | | |
+ | Driver | | | PCI Virtual |
+ | | +---------------+ | NTB Driver |
+ | | | PCI EP NTB |<------>| |
+ | | | FN Driver | | |
+ +------------+ +---------------+ +--------------+
+ | | | | | |
+ | PCI BUS | <-----> | PCI EP BUS | | Virtual PCI |
+ | | PCI | | | BUS |
+ +------------+ +---------------+--------+--------------+
+ PCI RC PCI EP
+
+Constructs used for Implementing vNTB
+=====================================
+
+ 1) Config Region
+ 2) Self Scratchpad Registers
+ 3) Peer Scratchpad Registers
+ 4) Doorbell (DB) Registers
+ 5) Memory Window (MW)
+
+
+Config Region:
+--------------
+
+It is same as PCI NTB Function driver
+
+Scratchpad Registers:
+---------------------
+
+It is appended after Config region.
+
+.. code-block:: text
+
+
+ +--------------------------------------------------+ Base
+ | |
+ | |
+ | |
+ | Common Config Register |
+ | |
+ | |
+ | |
+ +-----------------------+--------------------------+ Base + span_offset
+ | | |
+ | Peer Span Space | Span Space |
+ | | |
+ | | |
+ +-----------------------+--------------------------+ Base + span_offset
+ | | | + span_count * 4
+ | | |
+ | Span Space | Peer Span Space |
+ | | |
+ +-----------------------+--------------------------+
+ Virtual PCI Pcie Endpoint
+ NTB Driver NTB Driver
+
+
+Doorbell Registers:
+-------------------
+
+ Doorbell Registers are used by the hosts to interrupt each other.
+
+Memory Window:
+--------------
+
+ Actual transfer of data between the two hosts will happen using the
+ memory window.
+
+Modeling Constructs:
+====================
+
+32-bit BARs.
+
+====== ===============
+BAR NO CONSTRUCTS USED
+====== ===============
+BAR0 Config Region
+BAR1 Doorbell
+BAR2 Memory Window 1
+BAR3 Memory Window 2
+BAR4 Memory Window 3
+BAR5 Memory Window 4
+====== ===============
+
+64-bit BARs.
+
+====== ===============================
+BAR NO CONSTRUCTS USED
+====== ===============================
+BAR0 Config Region + Scratchpad
+BAR1
+BAR2 Doorbell
+BAR3
+BAR4 Memory Window 1
+BAR5
+====== ===============================
+
+
diff --git a/Documentation/PCI/endpoint/pci-vntb-howto.rst b/Documentation/PCI/endpoint/pci-vntb-howto.rst
new file mode 100644
index 000000000000..9a7a2f0a6849
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-vntb-howto.rst
@@ -0,0 +1,169 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================================================
+PCI Non-Transparent Bridge (NTB) Endpoint Function (EPF) User Guide
+===================================================================
+
+:Author: Frank Li <Frank.Li@nxp.com>
+
+This document is a guide to help users use pci-epf-vntb function driver
+and ntb_hw_epf host driver for NTB functionality. The list of steps to
+be followed in the host side and EP side is given below. For the hardware
+configuration and internals of NTB using configurable endpoints see
+Documentation/PCI/endpoint/pci-vntb-function.rst
+
+Endpoint Device
+===============
+
+Endpoint Controller Devices
+---------------------------
+
+To find the list of endpoint controller devices in the system::
+
+ # ls /sys/class/pci_epc/
+ 5f010000.pcie_ep
+
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
+ # ls /sys/kernel/config/pci_ep/controllers
+ 5f010000.pcie_ep
+
+Endpoint Function Drivers
+-------------------------
+
+To find the list of endpoint function drivers in the system::
+
+ # ls /sys/bus/pci-epf/drivers
+ pci_epf_ntb pci_epf_test pci_epf_vntb
+
+If PCI_ENDPOINT_CONFIGFS is enabled::
+
+ # ls /sys/kernel/config/pci_ep/functions
+ pci_epf_ntb pci_epf_test pci_epf_vntb
+
+
+Creating pci-epf-vntb Device
+----------------------------
+
+PCI endpoint function device can be created using the configfs. To create
+pci-epf-vntb device, the following commands can be used::
+
+ # mount -t configfs none /sys/kernel/config
+ # cd /sys/kernel/config/pci_ep/
+ # mkdir functions/pci_epf_vntb/func1
+
+The "mkdir func1" above creates the pci-epf-ntb function device that will
+be probed by pci_epf_vntb driver.
+
+The PCI endpoint framework populates the directory with the following
+configurable fields::
+
+ # ls functions/pci_epf_ntb/func1
+ baseclass_code deviceid msi_interrupts pci-epf-ntb.0
+ progif_code secondary subsys_id vendorid
+ cache_line_size interrupt_pin msix_interrupts primary
+ revid subclass_code subsys_vendor_id
+
+The PCI endpoint function driver populates these entries with default values
+when the device is bound to the driver. The pci-epf-vntb driver populates
+vendorid with 0xffff and interrupt_pin with 0x0001::
+
+ # cat functions/pci_epf_vntb/func1/vendorid
+ 0xffff
+ # cat functions/pci_epf_vntb/func1/interrupt_pin
+ 0x0001
+
+
+Configuring pci-epf-vntb Device
+-------------------------------
+
+The user can configure the pci-epf-vntb device using its configfs entry. In order
+to change the vendorid and the deviceid, the following
+commands can be used::
+
+ # echo 0x1957 > functions/pci_epf_vntb/func1/vendorid
+ # echo 0x0809 > functions/pci_epf_vntb/func1/deviceid
+
+The PCI endpoint framework also automatically creates a sub-directory in the
+function attribute directory. This sub-directory has the same name as the name
+of the function device and is populated with the following NTB specific
+attributes that can be configured by the user::
+
+ # ls functions/pci_epf_vntb/func1/pci_epf_vntb.0/
+ ctrl_bar db_count mw1_bar mw2_bar mw3_bar mw4_bar spad_count
+ db_bar mw1 mw2 mw3 mw4 num_mws vbus_number
+ vntb_vid vntb_pid
+
+A sample configuration for NTB function is given below::
+
+ # echo 4 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/db_count
+ # echo 128 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/spad_count
+ # echo 1 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/num_mws
+ # echo 0x100000 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/mw1
+
+By default, each construct is assigned a BAR, as needed and in order.
+Should a specific BAR setup be required by the platform, BAR may be assigned
+to each construct using the related ``XYZ_bar`` entry.
+
+A sample configuration for virtual NTB driver for virtual PCI bus::
+
+ # echo 0x1957 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vntb_vid
+ # echo 0x080A > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vntb_pid
+ # echo 0x10 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vbus_number
+
+Binding pci-epf-ntb Device to EP Controller
+--------------------------------------------
+
+NTB function device should be attached to PCI endpoint controllers
+connected to the host.
+
+ # ln -s controllers/5f010000.pcie_ep functions/pci-epf-ntb/func1/primary
+
+Once the above step is completed, the PCI endpoint controllers are ready to
+establish a link with the host.
+
+
+Start the Link
+--------------
+
+In order for the endpoint device to establish a link with the host, the _start_
+field should be populated with '1'. For NTB, both the PCI endpoint controllers
+should establish link with the host (imx8 don't need this steps)::
+
+ # echo 1 > controllers/5f010000.pcie_ep/start
+
+RootComplex Device
+==================
+
+lspci Output at Host side
+-------------------------
+
+Note that the devices listed here correspond to the values populated in
+"Creating pci-epf-ntb Device" section above::
+
+ # lspci
+ 00:00.0 PCI bridge: Freescale Semiconductor Inc Device 0000 (rev 01)
+ 01:00.0 RAM memory: Freescale Semiconductor Inc Device 0809
+
+Endpoint Device / Virtual PCI bus
+=================================
+
+lspci Output at EP Side / Virtual PCI bus
+-----------------------------------------
+
+Note that the devices listed here correspond to the values populated in
+"Creating pci-epf-ntb Device" section above::
+
+ # lspci
+ 10:00.0 Unassigned class [ffff]: Dawicontrol Computersysteme GmbH Device 1234 (rev ff)
+
+Using ntb_hw_epf Device
+-----------------------
+
+The host side software follows the standard NTB software architecture in Linux.
+All the existing client side NTB utilities like NTB Transport Client and NTB
+Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
+function device.
+
+For more information on NTB see
+:doc:`Non-Transparent Bridge <../../driver-api/ntb>`
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
new file mode 100644
index 000000000000..5d720d2a415e
--- /dev/null
+++ b/Documentation/PCI/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI Bus Subsystem
+=================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ pci
+ pciebus-howto
+ pci-iov-howto
+ msi-howto
+ sysfs-pci
+ acpi-info
+ pci-error-recovery
+ pcieaer-howto
+ endpoint/index
+ controller/index
+ boot-interrupts
+ tph
diff --git a/Documentation/PCI/msi-howto.rst b/Documentation/PCI/msi-howto.rst
new file mode 100644
index 000000000000..0692c9aec66f
--- /dev/null
+++ b/Documentation/PCI/msi-howto.rst
@@ -0,0 +1,297 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==========================
+The MSI Driver Guide HOWTO
+==========================
+
+:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
+
+:Copyright: 2003, 2008 Intel Corporation
+
+About this guide
+================
+
+This guide describes the basics of Message Signaled Interrupts (MSIs),
+the advantages of using MSI over traditional interrupt mechanisms, how
+to change your driver to use MSI or MSI-X and some basic diagnostics to
+try if a device doesn't support MSIs.
+
+
+What are MSIs?
+==============
+
+A Message Signaled Interrupt is a write from the device to a special
+address which causes an interrupt to be received by the CPU.
+
+The MSI capability was first specified in PCI 2.2 and was later enhanced
+in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X
+capability was also introduced with PCI 3.0. It supports more interrupts
+per device than MSI and allows interrupts to be independently configured.
+
+Devices may support both MSI and MSI-X, but only one can be enabled at
+a time.
+
+
+Why use MSIs?
+=============
+
+There are three reasons why using MSIs can give an advantage over
+traditional pin-based interrupts.
+
+Pin-based PCI interrupts are often shared amongst several devices.
+To support this, the kernel must call each interrupt handler associated
+with an interrupt, which leads to reduced performance for the system as
+a whole. MSIs are never shared, so this problem cannot arise.
+
+When a device writes data to memory, then raises a pin-based interrupt,
+it is possible that the interrupt may arrive before all the data has
+arrived in memory (this becomes more likely with devices behind PCI-PCI
+bridges). In order to ensure that all the data has arrived in memory,
+the interrupt handler must read a register on the device which raised
+the interrupt. PCI transaction ordering rules require that all the data
+arrive in memory before the value may be returned from the register.
+Using MSIs avoids this problem as the interrupt-generating write cannot
+pass the data writes, so by the time the interrupt is raised, the driver
+knows that all the data has arrived in memory.
+
+PCI devices can only support a single pin-based interrupt per function.
+Often drivers have to query the device to find out what event has
+occurred, slowing down interrupt handling for the common case. With
+MSIs, a device can support more interrupts, allowing each interrupt
+to be specialised to a different purpose. One possible design gives
+infrequent conditions (such as errors) their own interrupt which allows
+the driver to handle the normal interrupt handling path more efficiently.
+Other possible designs include giving one interrupt to each packet queue
+in a network card or each port in a storage controller.
+
+
+How to use MSIs
+===============
+
+PCI devices are initialised to use pin-based interrupts. The device
+driver has to set up the device to use MSI or MSI-X. Not all machines
+support MSIs correctly, and for those machines, the APIs described below
+will simply fail and the device will continue to use pin-based interrupts.
+
+Include kernel support for MSIs
+-------------------------------
+
+To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
+option enabled. This option is only available on some architectures,
+and it may depend on some other options also being set. For example,
+on x86, you must also enable X86_UP_APIC or SMP in order to see the
+CONFIG_PCI_MSI option.
+
+Using MSI
+---------
+
+Most of the hard work is done for the driver in the PCI layer. The driver
+simply has to request that the PCI layer set up the MSI capability for this
+device.
+
+To automatically use MSI or MSI-X interrupt vectors, use the following
+function::
+
+ int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
+ unsigned int max_vecs, unsigned int flags);
+
+which allocates up to max_vecs interrupt vectors for a PCI device. It
+returns the number of vectors allocated or a negative error. If the device
+has a requirements for a minimum number of vectors the driver can pass a
+min_vecs argument set to this limit, and the PCI core will return -ENOSPC
+if it can't meet the minimum number of vectors.
+
+The flags argument is used to specify which type of interrupt can be used
+by the device and the driver (PCI_IRQ_INTX, PCI_IRQ_MSI, PCI_IRQ_MSIX).
+A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
+any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
+pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
+
+To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
+vectors, use the following function::
+
+ int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
+
+Any allocated resources should be freed before removing the device using
+the following function::
+
+ void pci_free_irq_vectors(struct pci_dev *dev);
+
+If a device supports both MSI-X and MSI capabilities, this API will use the
+MSI-X facilities in preference to the MSI facilities. MSI-X supports any
+number of interrupts between 1 and 2048. In contrast, MSI is restricted to
+a maximum of 32 interrupts (and must be a power of two). In addition, the
+MSI interrupt vectors must be allocated consecutively, so the system might
+not be able to allocate as many vectors for MSI as it could for MSI-X. On
+some platforms, MSI interrupts must all be targeted at the same set of CPUs
+whereas MSI-X interrupts can all be targeted at different CPUs.
+
+If a device supports neither MSI-X or MSI it will fall back to a single
+legacy IRQ vector.
+
+The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
+as possible, likely up to the limit supported by the device. If nvec is
+larger than the number supported by the device it will automatically be
+capped to the supported limit, so there is no need to query the number of
+vectors supported beforehand::
+
+ nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
+ if (nvec < 0)
+ goto out_err;
+
+If a driver is unable or unwilling to deal with a variable number of MSI
+interrupts it can request a particular number of interrupts by passing that
+number to pci_alloc_irq_vectors() function as both 'min_vecs' and
+'max_vecs' parameters::
+
+ ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
+ if (ret < 0)
+ goto out_err;
+
+The most notorious example of the request type described above is enabling
+the single MSI mode for a device. It could be done by passing two 1s as
+'min_vecs' and 'max_vecs'::
+
+ ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
+ if (ret < 0)
+ goto out_err;
+
+Some devices might not support using legacy line interrupts, in which case
+the driver can specify that only MSI or MSI-X is acceptable::
+
+ nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);
+ if (nvec < 0)
+ goto out_err;
+
+Legacy APIs
+-----------
+
+The following old APIs to enable and disable MSI or MSI-X interrupts should
+not be used in new code::
+
+ pci_enable_msi() /* deprecated */
+ pci_disable_msi() /* deprecated */
+ pci_enable_msix_range() /* deprecated */
+ pci_enable_msix_exact() /* deprecated */
+ pci_disable_msix() /* deprecated */
+
+Additionally there are APIs to provide the number of supported MSI or MSI-X
+vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these
+should be avoided in favor of letting pci_alloc_irq_vectors() cap the
+number of vectors. If you have a legitimate special use case for the count
+of vectors we might have to revisit that decision and add a
+pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
+
+Considerations when using MSIs
+------------------------------
+
+Spinlocks
+~~~~~~~~~
+
+Most device drivers have a per-device spinlock which is taken in the
+interrupt handler. With pin-based interrupts or a single MSI, it is not
+necessary to disable interrupts (Linux guarantees the same interrupt will
+not be re-entered). If a device uses multiple interrupts, the driver
+must disable interrupts while the lock is held. If the device sends
+a different interrupt, the driver will deadlock trying to recursively
+acquire the spinlock. Such deadlocks can be avoided by using
+spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
+and acquire the lock (see Documentation/kernel-hacking/locking.rst).
+
+How to tell whether MSI/MSI-X is enabled on a device
+----------------------------------------------------
+
+Using 'lspci -v' (as root) may show some devices with "MSI", "Message
+Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
+has an 'Enable' flag which is followed with either "+" (enabled)
+or "-" (disabled).
+
+
+MSI quirks
+==========
+
+Several PCI chipsets or devices are known not to support MSIs.
+The PCI stack provides three ways to disable MSIs:
+
+1. globally
+2. on all devices behind a specific bridge
+3. on a single device
+
+Disabling MSIs globally
+-----------------------
+
+Some host chipsets simply don't support MSIs properly. If we're
+lucky, the manufacturer knows this and has indicated it in the ACPI
+FADT table. In this case, Linux automatically disables MSIs.
+Some boards don't include this information in the table and so we have
+to detect them ourselves. The complete list of these is found near the
+quirk_disable_all_msi() function in drivers/pci/quirks.c.
+
+If you have a board which has problems with MSIs, you can pass pci=nomsi
+on the kernel command line to disable MSIs on all devices. It would be
+in your best interests to report the problem to linux-pci@vger.kernel.org
+including a full 'lspci -v' so we can add the quirks to the kernel.
+
+Disabling MSIs below a bridge
+-----------------------------
+
+Some PCI bridges are not able to route MSIs between buses properly.
+In this case, MSIs must be disabled on all devices behind the bridge.
+
+Some bridges allow you to enable MSIs by changing some bits in their
+PCI configuration space (especially the Hypertransport chipsets such
+as the nVidia nForce and Serverworks HT2000). As with host chipsets,
+Linux mostly knows about them and automatically enables MSIs if it can.
+If you have a bridge unknown to Linux, you can enable
+MSIs in configuration space using whatever method you know works, then
+enable MSIs on that bridge by doing::
+
+ echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
+
+where $bridge is the PCI address of the bridge you've enabled (eg
+0000:00:0e.0).
+
+To disable MSIs, echo 0 instead of 1. Changing this value should be
+done with caution as it could break interrupt handling for all devices
+below this bridge.
+
+Again, please notify linux-pci@vger.kernel.org of any bridges that need
+special handling.
+
+Disabling MSIs on a single device
+---------------------------------
+
+Some devices are known to have faulty MSI implementations. Usually this
+is handled in the individual device driver, but occasionally it's necessary
+to handle this with a quirk. Some drivers have an option to disable use
+of MSI. While this is a convenient workaround for the driver author,
+it is not good practice, and should not be emulated.
+
+Finding why MSIs are disabled on a device
+-----------------------------------------
+
+From the above three sections, you can see that there are many reasons
+why MSIs may not be enabled for a given device. Your first step should
+be to examine your dmesg carefully to determine whether MSIs are enabled
+for your machine. You should also check your .config to be sure you
+have enabled CONFIG_PCI_MSI.
+
+Then, 'lspci -t' gives the list of bridges above a device. Reading
+`/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1)
+or disabled (0). If 0 is found in any of the msi_bus files belonging
+to bridges between the PCI root and the device, MSIs are disabled.
+
+It is also worth checking the device driver to see whether it supports MSIs.
+For example, it may contain calls to pci_alloc_irq_vectors() with the
+PCI_IRQ_MSI or PCI_IRQ_MSIX flags.
+
+
+List of device drivers MSI(-X) APIs
+===================================
+
+The PCI/MSI subsystem has a dedicated C file for its exported device driver
+APIs — `drivers/pci/msi/api.c`. The following functions are exported:
+
+.. kernel-doc:: drivers/pci/msi/api.c
+ :export:
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
new file mode 100644
index 000000000000..43bc4e3665b4
--- /dev/null
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -0,0 +1,472 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+PCI Error Recovery
+==================
+
+
+:Authors: - Linas Vepstas <linasvepstas@gmail.com>
+ - Richard Lary <rlary@us.ibm.com>
+ - Mike Mason <mmlnx@us.ibm.com>
+
+
+Many PCI bus controllers are able to detect a variety of hardware
+PCI errors on the bus, such as parity errors on the data and address
+buses, as well as SERR and PERR errors. Some of the more advanced
+chipsets are able to deal with these errors; these include PCIe chipsets,
+and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
+pSeries boxes. A typical action taken is to disconnect the affected device,
+halting all I/O to it. The goal of a disconnection is to avoid system
+corruption; for example, to halt system memory corruption due to DMAs
+to "wild" addresses. Typically, a reconnection mechanism is also
+offered, so that the affected PCI device(s) are reset and put back
+into working condition. The reset phase requires coordination
+between the affected device drivers and the PCI controller chip.
+This document describes a generic API for notifying device drivers
+of a bus disconnection, and then performing error recovery.
+This API is currently implemented in the 2.6.16 and later kernels.
+
+Reporting and recovery is performed in several steps. First, when
+a PCI hardware error has resulted in a bus disconnect, that event
+is reported as soon as possible to all affected device drivers,
+including multiple instances of a device driver on multi-function
+cards. This allows device drivers to avoid deadlocking in spinloops,
+waiting for some i/o-space register to change, when it never will.
+It also gives the drivers a chance to defer incoming I/O as
+needed.
+
+Next, recovery is performed in several stages. Most of the complexity
+is forced by the need to handle multi-function devices, that is,
+devices that have multiple device drivers associated with them.
+In the first stage, each driver is allowed to indicate what type
+of reset it desires, the choices being a simple re-enabling of I/O
+or requesting a slot reset.
+
+If any driver requests a slot reset, that is what will be done.
+
+After a reset and/or a re-enabling of I/O, all drivers are
+again notified, so that they may then perform any device setup/config
+that may be required. After these have all completed, a final
+"resume normal operations" event is sent out.
+
+The biggest reason for choosing a kernel-based implementation rather
+than a user-space implementation was the need to deal with bus
+disconnects of PCI devices attached to storage media, and, in particular,
+disconnects from devices holding the root file system. If the root
+file system is disconnected, a user-space mechanism would have to go
+through a large number of contortions to complete recovery. Almost all
+of the current Linux file systems are not tolerant of disconnection
+from/reconnection to their underlying block device. By contrast,
+bus errors are easy to manage in the device driver. Indeed, most
+device drivers already handle very similar recovery procedures;
+for example, the SCSI-generic layer already provides significant
+mechanisms for dealing with SCSI bus errors and SCSI bus resets.
+
+
+Detailed Design
+===============
+
+Design and implementation details below, based on a chain of
+public email discussions with Ben Herrenschmidt, circa 5 April 2005.
+
+The error recovery API support is exposed to the driver in the form of
+a structure of function pointers pointed to by a new field in struct
+pci_driver. A driver that fails to provide the structure is "non-aware",
+and the actual recovery steps taken are platform dependent. The
+arch/powerpc implementation will simulate a PCI hotplug remove/add.
+
+This structure has the form::
+
+ struct pci_error_handlers
+ {
+ int (*error_detected)(struct pci_dev *dev, pci_channel_state_t);
+ int (*mmio_enabled)(struct pci_dev *dev);
+ int (*slot_reset)(struct pci_dev *dev);
+ void (*resume)(struct pci_dev *dev);
+ void (*cor_error_detected)(struct pci_dev *dev);
+ };
+
+The possible channel states are::
+
+ typedef enum {
+ pci_channel_io_normal, /* I/O channel is in normal state */
+ pci_channel_io_frozen, /* I/O to channel is blocked */
+ pci_channel_io_perm_failure, /* PCI card is dead */
+ } pci_channel_state_t;
+
+Possible return values are::
+
+ enum pci_ers_result {
+ PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
+ PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
+ PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
+ PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
+ PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
+ };
+
+A driver does not have to implement all of these callbacks; however,
+if it implements any, it must implement error_detected(). If a callback
+is not implemented, the corresponding feature is considered unsupported.
+For example, if mmio_enabled() and resume() aren't there, then it
+is assumed that the driver does not need these callbacks
+for recovery. Typically a driver will want to know about
+a slot_reset().
+
+The actual steps taken by a platform to recover from a PCI error
+event will be platform-dependent, but will follow the general
+sequence described below.
+
+STEP 0: Error Event
+-------------------
+A PCI bus error is detected by the PCI hardware. On powerpc, the slot
+is isolated, in that all I/O is blocked: all reads return 0xffffffff,
+all writes are ignored.
+
+Similarly, on platforms supporting Downstream Port Containment
+(PCIe r7.0 sec 6.2.11), the link to the sub-hierarchy with the
+faulting device is disabled. Any device in the sub-hierarchy
+becomes inaccessible.
+
+STEP 1: Notification
+--------------------
+Platform calls the error_detected() callback on every instance of
+every driver affected by the error.
+
+At this point, the device might not be accessible anymore, depending on
+the platform (the slot will be isolated on powerpc). The driver may
+already have "noticed" the error because of a failing I/O, but this
+is the proper "synchronization point", that is, it gives the driver
+a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
+to complete; it can take semaphores, schedule, etc... everything but
+touch the device. Within this function and after it returns, the driver
+shouldn't do any new IOs. Called in task context. This is sort of a
+"quiesce" point. See note about interrupts at the end of this doc.
+
+All drivers participating in this system must implement this call.
+The driver must return one of the following result codes:
+
+ - PCI_ERS_RESULT_RECOVERED
+ Driver returns this if it thinks the device is usable despite
+ the error and does not need further intervention.
+ - PCI_ERS_RESULT_CAN_RECOVER
+ Driver returns this if it thinks it might be able to recover
+ the HW by just banging IOs or if it wants to be given
+ a chance to extract some diagnostic information (see
+ mmio_enable, below).
+ - PCI_ERS_RESULT_NEED_RESET
+ Driver returns this if it can't recover without a
+ slot reset.
+ - PCI_ERS_RESULT_DISCONNECT
+ Driver returns this if it doesn't want to recover at all.
+
+The next step taken will depend on the result codes returned by the
+drivers.
+
+If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
+then the platform should re-enable IOs on the slot (or do nothing in
+particular, if the platform doesn't isolate slots), and recovery
+proceeds to STEP 2 (MMIO Enable).
+
+If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
+then recovery proceeds to STEP 4 (Slot Reset).
+
+If the platform is unable to recover the slot, the next step
+is STEP 6 (Permanent Failure).
+
+.. note::
+
+ The current powerpc implementation assumes that a device driver will
+ *not* schedule or semaphore in this routine; the current powerpc
+ implementation uses one kernel thread to notify all devices;
+ thus, if one device sleeps/schedules, all devices are affected.
+ Doing better requires complex multi-threaded logic in the error
+ recovery implementation (e.g. waiting for all notification threads
+ to "join" before proceeding with recovery.) This seems excessively
+ complex and not worth implementing.
+
+ The current powerpc implementation doesn't much care if the device
+ attempts I/O at this point, or not. I/Os will fail, returning
+ a value of 0xff on read, and writes will be dropped. If more than
+ EEH_MAX_FAILS I/Os are attempted to a frozen adapter, EEH
+ assumes that the device driver has gone into an infinite loop
+ and prints an error to syslog. A reboot is then required to
+ get the device working again.
+
+STEP 2: MMIO Enabled
+--------------------
+The platform re-enables MMIO to the device (but typically not the
+DMA), and then calls the mmio_enabled() callback on all affected
+device drivers.
+
+This is the "early recovery" call. IOs are allowed again, but DMA is
+not, with some restrictions. This is NOT a callback for the driver to
+start operations again, only to peek/poke at the device, extract diagnostic
+information, if any, and eventually do things like trigger a device local
+reset or some such, but not restart operations. This callback is made if
+all drivers on a segment agree that they can try to recover and if no automatic
+link reset was performed by the HW. If the platform can't just re-enable IOs
+without a slot reset or a link reset, it will not call this callback, and
+instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset).
+
+.. note::
+
+ On platforms supporting Advanced Error Reporting (PCIe r7.0 sec 6.2),
+ the faulting device may already be accessible in STEP 1 (Notification).
+ Drivers should nevertheless defer accesses to STEP 2 (MMIO Enabled)
+ to be compatible with EEH on powerpc and with s390 (where devices are
+ inaccessible until STEP 2).
+
+ On platforms supporting Downstream Port Containment, the link to the
+ sub-hierarchy with the faulting device is re-enabled in STEP 3 (Link
+ Reset). Hence devices in the sub-hierarchy are inaccessible until
+ STEP 4 (Slot Reset).
+
+ For errors such as Surprise Down (PCIe r7.0 sec 6.2.7), the device
+ may not even be accessible in STEP 4 (Slot Reset). Drivers can detect
+ accessibility by checking whether reads from the device return all 1's
+ (PCI_POSSIBLE_ERROR()).
+
+.. note::
+
+ The following is proposed; no platform implements this yet:
+ Proposal: All I/Os should be done _synchronously_ from within
+ this callback, errors triggered by them will be returned via
+ the normal pci_check_whatever() API, no new error_detected()
+ callback will be issued due to an error happening here. However,
+ such an error might cause IOs to be re-blocked for the whole
+ segment, and thus invalidate the recovery that other devices
+ on the same segment might have done, forcing the whole segment
+ into one of the next states, that is, link reset or slot reset.
+
+The driver should return one of the following result codes:
+ - PCI_ERS_RESULT_RECOVERED
+ Driver returns this if it thinks the device is fully
+ functional and thinks it is ready to start
+ normal driver operations again. There is no
+ guarantee that the driver will actually be
+ allowed to proceed, as another driver on the
+ same segment might have failed and thus triggered a
+ slot reset on platforms that support it.
+
+ - PCI_ERS_RESULT_NEED_RESET
+ Driver returns this if it thinks the device is not
+ recoverable in its current state and it needs a slot
+ reset to proceed.
+
+ - PCI_ERS_RESULT_DISCONNECT
+ Same as above. Total failure, no recovery even after
+ reset driver dead. (To be defined more precisely)
+
+The next step taken depends on the results returned by the drivers.
+If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
+proceeds to either STEP 3 (Link Reset) or to STEP 5 (Resume Operations).
+
+If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
+proceeds to STEP 4 (Slot Reset)
+
+STEP 3: Link Reset
+------------------
+The platform resets the link. This is a PCIe specific step
+and is done whenever a fatal error has been detected that can be
+"solved" by resetting the link.
+
+STEP 4: Slot Reset
+------------------
+
+In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
+platform will perform a slot reset on the requesting PCI device(s).
+The actual steps taken by a platform to perform a slot reset
+will be platform-dependent. Upon completion of slot reset, the
+platform will call the device slot_reset() callback.
+
+Powerpc platforms implement two levels of slot reset:
+soft reset(default) and fundamental(optional) reset.
+
+Powerpc soft reset consists of asserting the adapter #RST line and then
+restoring the PCI BARs and PCI configuration header to a state
+that is equivalent to what it would be after a fresh system
+power-on followed by power-on BIOS/system firmware initialization.
+Soft reset is also known as hot-reset.
+
+Powerpc fundamental reset is supported by PCIe cards only
+and results in device's state machines, hardware logic, port states and
+configuration registers to initialize to their default conditions.
+
+For most PCI devices, a soft reset will be sufficient for recovery.
+Optional fundamental reset is provided to support a limited number
+of PCIe devices for which a soft reset is not sufficient
+for recovery.
+
+If the platform supports PCI hotplug, then the reset might be
+performed by toggling the slot electrical power off/on.
+
+It is important for the platform to restore the PCI config space
+to the "fresh poweron" state, rather than the "last state". After
+a slot reset, the device driver will almost always use its standard
+device initialization routines, and an unusual config space setup
+may result in hung devices, kernel panics, or silent data corruption.
+
+This call gives drivers the chance to re-initialize the hardware
+(re-download firmware, etc.). At this point, the driver may assume
+that the card is in a fresh state and is fully functional. The slot
+is unfrozen and the driver has full access to PCI config space,
+memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
+will also be available.
+
+Drivers should not restart normal I/O processing operations
+at this point. If all device drivers report success on this
+callback, the platform will call resume() to complete the sequence,
+and let the driver restart normal I/O processing.
+
+A driver can still return a critical failure for this function if
+it can't get the device operational after reset. If the platform
+previously tried a soft reset, it might now try a hard reset (power
+cycle) and then call slot_reset() again. If the device still can't
+be recovered, there is nothing more that can be done; the platform
+will typically report a "permanent failure" in such a case. The
+device will be considered "dead" in this case.
+
+Drivers typically need to call pci_restore_state() after reset to
+re-initialize the device's config space registers and thereby
+bring it from D0\ :sub:`uninitialized` into D0\ :sub:`active` state
+(PCIe r7.0 sec 5.3.1.1). The PCI core invokes pci_save_state()
+on enumeration after initializing config space to ensure that a
+saved state is available for subsequent error recovery.
+Drivers which modify config space on probe may need to invoke
+pci_save_state() afterwards to record those changes for later
+error recovery. When going into system suspend, pci_save_state()
+is called for every PCI device and that state will be restored
+not only on resume, but also on any subsequent error recovery.
+In the unlikely event that the saved state recorded on suspend
+is unsuitable for error recovery, drivers should call
+pci_save_state() on resume.
+
+Drivers for multi-function cards will need to coordinate among
+themselves as to which driver instance will perform any "one-shot"
+or global device initialization. For example, the Symbios sym53cxx2
+driver performs device init only from PCI function 0::
+
+ + if (PCI_FUNC(pdev->devfn) == 0)
+ + sym_reset_scsi_bus(np, 0);
+
+Result codes:
+ - PCI_ERS_RESULT_DISCONNECT
+ Same as above.
+
+Drivers for PCIe cards that require a fundamental reset must
+set the needs_freset bit in the pci_dev structure in their probe function.
+For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
+PCI card types::
+
+ + /* Set EEH reset type to fundamental if required by hba */
+ + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
+ + pdev->needs_freset = 1;
+ +
+
+Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
+Failure).
+
+.. note::
+
+ The current powerpc implementation does not try a power-cycle
+ reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
+ However, it probably should.
+
+
+STEP 5: Resume Operations
+-------------------------
+The platform will call the resume() callback on all affected device
+drivers if all drivers on the segment have returned
+PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
+The goal of this callback is to tell the driver to restart activity,
+that everything is back and running. This callback does not return
+a result code.
+
+At this point, if a new error happens, the platform will restart
+a new error recovery sequence.
+
+STEP 6: Permanent Failure
+-------------------------
+A "permanent failure" has occurred, and the platform cannot recover
+the device. The platform will call error_detected() with a
+pci_channel_state_t value of pci_channel_io_perm_failure.
+
+The device driver should, at this point, assume the worst. It should
+cancel all pending I/O, refuse all new I/O, returning -EIO to
+higher layers. The device driver should then clean up all of its
+memory and remove itself from kernel operations, much as it would
+during system shutdown.
+
+The platform will typically notify the system operator of the
+permanent failure in some way. If the device is hotplug-capable,
+the operator will probably want to remove and replace the device.
+Note, however, not all failures are truly "permanent". Some are
+caused by over-heating, some by a poorly seated card. Many
+PCI error events are caused by software bugs, e.g. DMAs to
+wild addresses or bogus split transactions due to programming
+errors. See the discussion in Documentation/arch/powerpc/eeh-pci-error-recovery.rst
+for additional detail on real-life experience of the causes of
+software errors.
+
+
+Conclusion; General Remarks
+---------------------------
+The way the callbacks are called is platform policy. A platform with
+no slot reset capability may want to just "ignore" drivers that can't
+recover (disconnect them) and try to let other cards on the same segment
+recover. Keep in mind that in most real life cases, though, there will
+be only one driver per segment.
+
+Now, a note about interrupts. If you get an interrupt and your
+device is dead or has been isolated, there is a problem :)
+The current policy is to turn this into a platform policy.
+That is, the recovery API only requires that:
+
+ - There is no guarantee that interrupt delivery can proceed from any
+ device on the segment starting from the error detection and until the
+ slot_reset callback is called, at which point interrupts are expected
+ to be fully operational.
+
+ - There is no guarantee that interrupt delivery is stopped, that is,
+ a driver that gets an interrupt after detecting an error, or that detects
+ an error within the interrupt handler such that it prevents proper
+ ack'ing of the interrupt (and thus removal of the source) should just
+ return IRQ_NOTHANDLED. It's up to the platform to deal with that
+ condition, typically by masking the IRQ source during the duration of
+ the error handling. It is expected that the platform "knows" which
+ interrupts are routed to error-management capable slots and can deal
+ with temporarily disabling that IRQ number during error processing (this
+ isn't terribly complex). That means some IRQ latency for other devices
+ sharing the interrupt, but there is simply no other way. High end
+ platforms aren't supposed to share interrupts between many devices
+ anyway :)
+
+.. note::
+
+ Implementation details for the powerpc platform are discussed in
+ the file Documentation/arch/powerpc/eeh-pci-error-recovery.rst
+
+ As of this writing, there is a growing list of device drivers with
+ patches implementing error recovery. Not all of these patches are in
+ mainline yet. These may be used as "examples":
+
+ - drivers/scsi/ipr
+ - drivers/scsi/sym53c8xx_2
+ - drivers/scsi/qla2xxx
+ - drivers/scsi/lpfc
+ - drivers/next/bnx2.c
+ - drivers/next/e100.c
+ - drivers/net/e1000
+ - drivers/net/e1000e
+ - drivers/net/ixgbe
+ - drivers/net/cxgb3
+ - drivers/net/s2io.c
+
+ The cor_error_detected() callback is invoked in handle_error_source() when
+ the error severity is "correctable". The callback is optional and allows
+ additional logging to be done if desired. See example:
+
+ - drivers/cxl/pci.c
+
+The End
+-------
diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.txt
deleted file mode 100644
index ac26869c7db4..000000000000
--- a/Documentation/PCI/pci-error-recovery.txt
+++ /dev/null
@@ -1,431 +0,0 @@
-
- PCI Error Recovery
- ------------------
- February 2, 2006
-
- Current document maintainer:
- Linas Vepstas <linasvepstas@gmail.com>
- updated by Richard Lary <rlary@us.ibm.com>
- and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009
-
-
-Many PCI bus controllers are able to detect a variety of hardware
-PCI errors on the bus, such as parity errors on the data and address
-busses, as well as SERR and PERR errors. Some of the more advanced
-chipsets are able to deal with these errors; these include PCI-E chipsets,
-and the PCI-host bridges found on IBM Power4, Power5 and Power6-based
-pSeries boxes. A typical action taken is to disconnect the affected device,
-halting all I/O to it. The goal of a disconnection is to avoid system
-corruption; for example, to halt system memory corruption due to DMA's
-to "wild" addresses. Typically, a reconnection mechanism is also
-offered, so that the affected PCI device(s) are reset and put back
-into working condition. The reset phase requires coordination
-between the affected device drivers and the PCI controller chip.
-This document describes a generic API for notifying device drivers
-of a bus disconnection, and then performing error recovery.
-This API is currently implemented in the 2.6.16 and later kernels.
-
-Reporting and recovery is performed in several steps. First, when
-a PCI hardware error has resulted in a bus disconnect, that event
-is reported as soon as possible to all affected device drivers,
-including multiple instances of a device driver on multi-function
-cards. This allows device drivers to avoid deadlocking in spinloops,
-waiting for some i/o-space register to change, when it never will.
-It also gives the drivers a chance to defer incoming I/O as
-needed.
-
-Next, recovery is performed in several stages. Most of the complexity
-is forced by the need to handle multi-function devices, that is,
-devices that have multiple device drivers associated with them.
-In the first stage, each driver is allowed to indicate what type
-of reset it desires, the choices being a simple re-enabling of I/O
-or requesting a slot reset.
-
-If any driver requests a slot reset, that is what will be done.
-
-After a reset and/or a re-enabling of I/O, all drivers are
-again notified, so that they may then perform any device setup/config
-that may be required. After these have all completed, a final
-"resume normal operations" event is sent out.
-
-The biggest reason for choosing a kernel-based implementation rather
-than a user-space implementation was the need to deal with bus
-disconnects of PCI devices attached to storage media, and, in particular,
-disconnects from devices holding the root file system. If the root
-file system is disconnected, a user-space mechanism would have to go
-through a large number of contortions to complete recovery. Almost all
-of the current Linux file systems are not tolerant of disconnection
-from/reconnection to their underlying block device. By contrast,
-bus errors are easy to manage in the device driver. Indeed, most
-device drivers already handle very similar recovery procedures;
-for example, the SCSI-generic layer already provides significant
-mechanisms for dealing with SCSI bus errors and SCSI bus resets.
-
-
-Detailed Design
----------------
-Design and implementation details below, based on a chain of
-public email discussions with Ben Herrenschmidt, circa 5 April 2005.
-
-The error recovery API support is exposed to the driver in the form of
-a structure of function pointers pointed to by a new field in struct
-pci_driver. A driver that fails to provide the structure is "non-aware",
-and the actual recovery steps taken are platform dependent. The
-arch/powerpc implementation will simulate a PCI hotplug remove/add.
-
-This structure has the form:
-struct pci_error_handlers
-{
- int (*error_detected)(struct pci_dev *dev, enum pci_channel_state);
- int (*mmio_enabled)(struct pci_dev *dev);
- int (*link_reset)(struct pci_dev *dev);
- int (*slot_reset)(struct pci_dev *dev);
- void (*resume)(struct pci_dev *dev);
-};
-
-The possible channel states are:
-enum pci_channel_state {
- pci_channel_io_normal, /* I/O channel is in normal state */
- pci_channel_io_frozen, /* I/O to channel is blocked */
- pci_channel_io_perm_failure, /* PCI card is dead */
-};
-
-Possible return values are:
-enum pci_ers_result {
- PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */
- PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */
- PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */
- PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */
- PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */
-};
-
-A driver does not have to implement all of these callbacks; however,
-if it implements any, it must implement error_detected(). If a callback
-is not implemented, the corresponding feature is considered unsupported.
-For example, if mmio_enabled() and resume() aren't there, then it
-is assumed that the driver is not doing any direct recovery and requires
-a slot reset. If link_reset() is not implemented, the card is assumed to
-not care about link resets. Typically a driver will want to know about
-a slot_reset().
-
-The actual steps taken by a platform to recover from a PCI error
-event will be platform-dependent, but will follow the general
-sequence described below.
-
-STEP 0: Error Event
--------------------
-A PCI bus error is detected by the PCI hardware. On powerpc, the slot
-is isolated, in that all I/O is blocked: all reads return 0xffffffff,
-all writes are ignored.
-
-
-STEP 1: Notification
---------------------
-Platform calls the error_detected() callback on every instance of
-every driver affected by the error.
-
-At this point, the device might not be accessible anymore, depending on
-the platform (the slot will be isolated on powerpc). The driver may
-already have "noticed" the error because of a failing I/O, but this
-is the proper "synchronization point", that is, it gives the driver
-a chance to cleanup, waiting for pending stuff (timers, whatever, etc...)
-to complete; it can take semaphores, schedule, etc... everything but
-touch the device. Within this function and after it returns, the driver
-shouldn't do any new IOs. Called in task context. This is sort of a
-"quiesce" point. See note about interrupts at the end of this doc.
-
-All drivers participating in this system must implement this call.
-The driver must return one of the following result codes:
- - PCI_ERS_RESULT_CAN_RECOVER:
- Driver returns this if it thinks it might be able to recover
- the HW by just banging IOs or if it wants to be given
- a chance to extract some diagnostic information (see
- mmio_enable, below).
- - PCI_ERS_RESULT_NEED_RESET:
- Driver returns this if it can't recover without a
- slot reset.
- - PCI_ERS_RESULT_DISCONNECT:
- Driver returns this if it doesn't want to recover at all.
-
-The next step taken will depend on the result codes returned by the
-drivers.
-
-If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER,
-then the platform should re-enable IOs on the slot (or do nothing in
-particular, if the platform doesn't isolate slots), and recovery
-proceeds to STEP 2 (MMIO Enable).
-
-If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET),
-then recovery proceeds to STEP 4 (Slot Reset).
-
-If the platform is unable to recover the slot, the next step
-is STEP 6 (Permanent Failure).
-
->>> The current powerpc implementation assumes that a device driver will
->>> *not* schedule or semaphore in this routine; the current powerpc
->>> implementation uses one kernel thread to notify all devices;
->>> thus, if one device sleeps/schedules, all devices are affected.
->>> Doing better requires complex multi-threaded logic in the error
->>> recovery implementation (e.g. waiting for all notification threads
->>> to "join" before proceeding with recovery.) This seems excessively
->>> complex and not worth implementing.
-
->>> The current powerpc implementation doesn't much care if the device
->>> attempts I/O at this point, or not. I/O's will fail, returning
->>> a value of 0xff on read, and writes will be dropped. If more than
->>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH
->>> assumes that the device driver has gone into an infinite loop
->>> and prints an error to syslog. A reboot is then required to
->>> get the device working again.
-
-STEP 2: MMIO Enabled
--------------------
-The platform re-enables MMIO to the device (but typically not the
-DMA), and then calls the mmio_enabled() callback on all affected
-device drivers.
-
-This is the "early recovery" call. IOs are allowed again, but DMA is
-not, with some restrictions. This is NOT a callback for the driver to
-start operations again, only to peek/poke at the device, extract diagnostic
-information, if any, and eventually do things like trigger a device local
-reset or some such, but not restart operations. This callback is made if
-all drivers on a segment agree that they can try to recover and if no automatic
-link reset was performed by the HW. If the platform can't just re-enable IOs
-without a slot reset or a link reset, it will not call this callback, and
-instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset)
-
->>> The following is proposed; no platform implements this yet:
->>> Proposal: All I/O's should be done _synchronously_ from within
->>> this callback, errors triggered by them will be returned via
->>> the normal pci_check_whatever() API, no new error_detected()
->>> callback will be issued due to an error happening here. However,
->>> such an error might cause IOs to be re-blocked for the whole
->>> segment, and thus invalidate the recovery that other devices
->>> on the same segment might have done, forcing the whole segment
->>> into one of the next states, that is, link reset or slot reset.
-
-The driver should return one of the following result codes:
- - PCI_ERS_RESULT_RECOVERED
- Driver returns this if it thinks the device is fully
- functional and thinks it is ready to start
- normal driver operations again. There is no
- guarantee that the driver will actually be
- allowed to proceed, as another driver on the
- same segment might have failed and thus triggered a
- slot reset on platforms that support it.
-
- - PCI_ERS_RESULT_NEED_RESET
- Driver returns this if it thinks the device is not
- recoverable in its current state and it needs a slot
- reset to proceed.
-
- - PCI_ERS_RESULT_DISCONNECT
- Same as above. Total failure, no recovery even after
- reset driver dead. (To be defined more precisely)
-
-The next step taken depends on the results returned by the drivers.
-If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform
-proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations).
-
-If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform
-proceeds to STEP 4 (Slot Reset)
-
-STEP 3: Link Reset
-------------------
-The platform resets the link, and then calls the link_reset() callback
-on all affected device drivers. This is a PCI-Express specific state
-and is done whenever a non-fatal error has been detected that can be
-"solved" by resetting the link. This call informs the driver of the
-reset and the driver should check to see if the device appears to be
-in working condition.
-
-The driver is not supposed to restart normal driver I/O operations
-at this point. It should limit itself to "probing" the device to
-check its recoverability status. If all is right, then the platform
-will call resume() once all drivers have ack'd link_reset().
-
- Result codes:
- (identical to STEP 3 (MMIO Enabled)
-
-The platform then proceeds to either STEP 4 (Slot Reset) or STEP 5
-(Resume Operations).
-
->>> The current powerpc implementation does not implement this callback.
-
-STEP 4: Slot Reset
-------------------
-
-In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
-the platform will perform a slot reset on the requesting PCI device(s).
-The actual steps taken by a platform to perform a slot reset
-will be platform-dependent. Upon completion of slot reset, the
-platform will call the device slot_reset() callback.
-
-Powerpc platforms implement two levels of slot reset:
-soft reset(default) and fundamental(optional) reset.
-
-Powerpc soft reset consists of asserting the adapter #RST line and then
-restoring the PCI BAR's and PCI configuration header to a state
-that is equivalent to what it would be after a fresh system
-power-on followed by power-on BIOS/system firmware initialization.
-Soft reset is also known as hot-reset.
-
-Powerpc fundamental reset is supported by PCI Express cards only
-and results in device's state machines, hardware logic, port states and
-configuration registers to initialize to their default conditions.
-
-For most PCI devices, a soft reset will be sufficient for recovery.
-Optional fundamental reset is provided to support a limited number
-of PCI Express PCI devices for which a soft reset is not sufficient
-for recovery.
-
-If the platform supports PCI hotplug, then the reset might be
-performed by toggling the slot electrical power off/on.
-
-It is important for the platform to restore the PCI config space
-to the "fresh poweron" state, rather than the "last state". After
-a slot reset, the device driver will almost always use its standard
-device initialization routines, and an unusual config space setup
-may result in hung devices, kernel panics, or silent data corruption.
-
-This call gives drivers the chance to re-initialize the hardware
-(re-download firmware, etc.). At this point, the driver may assume
-that the card is in a fresh state and is fully functional. The slot
-is unfrozen and the driver has full access to PCI config space,
-memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X)
-will also be available.
-
-Drivers should not restart normal I/O processing operations
-at this point. If all device drivers report success on this
-callback, the platform will call resume() to complete the sequence,
-and let the driver restart normal I/O processing.
-
-A driver can still return a critical failure for this function if
-it can't get the device operational after reset. If the platform
-previously tried a soft reset, it might now try a hard reset (power
-cycle) and then call slot_reset() again. It the device still can't
-be recovered, there is nothing more that can be done; the platform
-will typically report a "permanent failure" in such a case. The
-device will be considered "dead" in this case.
-
-Drivers for multi-function cards will need to coordinate among
-themselves as to which driver instance will perform any "one-shot"
-or global device initialization. For example, the Symbios sym53cxx2
-driver performs device init only from PCI function 0:
-
-+ if (PCI_FUNC(pdev->devfn) == 0)
-+ sym_reset_scsi_bus(np, 0);
-
- Result codes:
- - PCI_ERS_RESULT_DISCONNECT
- Same as above.
-
-Drivers for PCI Express cards that require a fundamental reset must
-set the needs_freset bit in the pci_dev structure in their probe function.
-For example, the QLogic qla2xxx driver sets the needs_freset bit for certain
-PCI card types:
-
-+ /* Set EEH reset type to fundamental if required by hba */
-+ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha))
-+ pdev->needs_freset = 1;
-+
-
-Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent
-Failure).
-
->>> The current powerpc implementation does not try a power-cycle
->>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT.
->>> However, it probably should.
-
-
-STEP 5: Resume Operations
--------------------------
-The platform will call the resume() callback on all affected device
-drivers if all drivers on the segment have returned
-PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks.
-The goal of this callback is to tell the driver to restart activity,
-that everything is back and running. This callback does not return
-a result code.
-
-At this point, if a new error happens, the platform will restart
-a new error recovery sequence.
-
-STEP 6: Permanent Failure
--------------------------
-A "permanent failure" has occurred, and the platform cannot recover
-the device. The platform will call error_detected() with a
-pci_channel_state value of pci_channel_io_perm_failure.
-
-The device driver should, at this point, assume the worst. It should
-cancel all pending I/O, refuse all new I/O, returning -EIO to
-higher layers. The device driver should then clean up all of its
-memory and remove itself from kernel operations, much as it would
-during system shutdown.
-
-The platform will typically notify the system operator of the
-permanent failure in some way. If the device is hotplug-capable,
-the operator will probably want to remove and replace the device.
-Note, however, not all failures are truly "permanent". Some are
-caused by over-heating, some by a poorly seated card. Many
-PCI error events are caused by software bugs, e.g. DMA's to
-wild addresses or bogus split transactions due to programming
-errors. See the discussion in powerpc/eeh-pci-error-recovery.txt
-for additional detail on real-life experience of the causes of
-software errors.
-
-
-Conclusion; General Remarks
----------------------------
-The way the callbacks are called is platform policy. A platform with
-no slot reset capability may want to just "ignore" drivers that can't
-recover (disconnect them) and try to let other cards on the same segment
-recover. Keep in mind that in most real life cases, though, there will
-be only one driver per segment.
-
-Now, a note about interrupts. If you get an interrupt and your
-device is dead or has been isolated, there is a problem :)
-The current policy is to turn this into a platform policy.
-That is, the recovery API only requires that:
-
- - There is no guarantee that interrupt delivery can proceed from any
-device on the segment starting from the error detection and until the
-slot_reset callback is called, at which point interrupts are expected
-to be fully operational.
-
- - There is no guarantee that interrupt delivery is stopped, that is,
-a driver that gets an interrupt after detecting an error, or that detects
-an error within the interrupt handler such that it prevents proper
-ack'ing of the interrupt (and thus removal of the source) should just
-return IRQ_NOTHANDLED. It's up to the platform to deal with that
-condition, typically by masking the IRQ source during the duration of
-the error handling. It is expected that the platform "knows" which
-interrupts are routed to error-management capable slots and can deal
-with temporarily disabling that IRQ number during error processing (this
-isn't terribly complex). That means some IRQ latency for other devices
-sharing the interrupt, but there is simply no other way. High end
-platforms aren't supposed to share interrupts between many devices
-anyway :)
-
->>> Implementation details for the powerpc platform are discussed in
->>> the file Documentation/powerpc/eeh-pci-error-recovery.txt
-
->>> As of this writing, there is a growing list of device drivers with
->>> patches implementing error recovery. Not all of these patches are in
->>> mainline yet. These may be used as "examples":
->>>
->>> drivers/scsi/ipr
->>> drivers/scsi/sym53c8xx_2
->>> drivers/scsi/qla2xxx
->>> drivers/scsi/lpfc
->>> drivers/next/bnx2.c
->>> drivers/next/e100.c
->>> drivers/net/e1000
->>> drivers/net/e1000e
->>> drivers/net/ixgb
->>> drivers/net/ixgbe
->>> drivers/net/cxgb3
->>> drivers/net/s2io.c
->>> drivers/net/qlge
-
-The End
--------
diff --git a/Documentation/PCI/pci-iov-howto.rst b/Documentation/PCI/pci-iov-howto.rst
new file mode 100644
index 000000000000..27d35933cea2
--- /dev/null
+++ b/Documentation/PCI/pci-iov-howto.rst
@@ -0,0 +1,171 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+====================================
+PCI Express I/O Virtualization Howto
+====================================
+
+:Copyright: |copy| 2009 Intel Corporation
+:Authors: - Yu Zhao <yu.zhao@intel.com>
+ - Donald Dutile <ddutile@redhat.com>
+
+Overview
+========
+
+What is SR-IOV
+--------------
+
+Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
+capability which makes one physical device appear as multiple virtual
+devices. The physical device is referred to as Physical Function (PF)
+while the virtual devices are referred to as Virtual Functions (VF).
+Allocation of the VF can be dynamically controlled by the PF via
+registers encapsulated in the capability. By default, this feature is
+not enabled and the PF behaves as traditional PCIe device. Once it's
+turned on, each VF's PCI configuration space can be accessed by its own
+Bus, Device and Function Number (Routing ID). And each VF also has PCI
+Memory Space, which is used to map its register set. VF device driver
+operates on the register set so it can be functional and appear as a
+real existing PCI device.
+
+User Guide
+==========
+
+How can I enable SR-IOV capability
+----------------------------------
+
+Multiple methods are available for SR-IOV enablement.
+In the first method, the device driver (PF driver) will control the
+enabling and disabling of the capability via API provided by SR-IOV core.
+If the hardware has SR-IOV capability, loading its PF driver would
+enable it and all VFs associated with the PF. Some PF drivers require
+a module parameter to be set to determine the number of VFs to enable.
+In the second method, a write to the sysfs file sriov_numvfs will
+enable and disable the VFs associated with a PCIe PF. This method
+enables per-PF, VF enable/disable values versus the first method,
+which applies to all PFs of the same device. Additionally, the
+PCI SRIOV core support ensures that enable/disable operations are
+valid to reduce duplication in multiple drivers for the same
+checks, e.g., check numvfs == 0 if enabling VFs, ensure
+numvfs <= totalvfs.
+The second method is the recommended method for new/future VF devices.
+
+How can I use the Virtual Functions
+-----------------------------------
+
+The VF is treated as hot-plugged PCI devices in the kernel, so they
+should be able to work in the same way as real PCI devices. The VF
+requires device driver that is same as a normal PCI device's.
+
+Developer Guide
+===============
+
+SR-IOV API
+----------
+
+To enable SR-IOV capability:
+
+(a) For the first method, in the driver::
+
+ int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
+
+'nr_virtfn' is number of VFs to be enabled.
+
+(b) For the second method, from sysfs::
+
+ echo 'nr_virtfn' > \
+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
+
+To disable SR-IOV capability:
+
+(a) For the first method, in the driver::
+
+ void pci_disable_sriov(struct pci_dev *dev);
+
+(b) For the second method, from sysfs::
+
+ echo 0 > \
+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
+
+To enable auto probing VFs by a compatible driver on the host, run
+command below before enabling SR-IOV capabilities. This is the
+default behavior.
+::
+
+ echo 1 > \
+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
+
+To disable auto probing VFs by a compatible driver on the host, run
+command below before enabling SR-IOV capabilities. Updating this
+entry will not affect VFs which are already probed.
+::
+
+ echo 0 > \
+ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe
+
+Usage example
+-------------
+
+Following piece of code illustrates the usage of the SR-IOV API.
+::
+
+ static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
+ {
+ pci_enable_sriov(dev, NR_VIRTFN);
+
+ ...
+
+ return 0;
+ }
+
+ static void dev_remove(struct pci_dev *dev)
+ {
+ pci_disable_sriov(dev);
+
+ ...
+ }
+
+ static int dev_suspend(struct device *dev)
+ {
+ ...
+
+ return 0;
+ }
+
+ static int dev_resume(struct device *dev)
+ {
+ ...
+
+ return 0;
+ }
+
+ static void dev_shutdown(struct pci_dev *dev)
+ {
+ ...
+ }
+
+ static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
+ {
+ if (numvfs > 0) {
+ ...
+ pci_enable_sriov(dev, numvfs);
+ ...
+ return numvfs;
+ }
+ if (numvfs == 0) {
+ ....
+ pci_disable_sriov(dev);
+ ...
+ return 0;
+ }
+ }
+
+ static struct pci_driver dev_driver = {
+ .name = "SR-IOV Physical Function driver",
+ .id_table = dev_id_table,
+ .probe = dev_probe,
+ .remove = dev_remove,
+ .driver.pm = &dev_pm_ops,
+ .shutdown = dev_shutdown,
+ .sriov_configure = dev_sriov_configure,
+ };
diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.txt
deleted file mode 100644
index 2d91ae251982..000000000000
--- a/Documentation/PCI/pci-iov-howto.txt
+++ /dev/null
@@ -1,135 +0,0 @@
- PCI Express I/O Virtualization Howto
- Copyright (C) 2009 Intel Corporation
- Yu Zhao <yu.zhao@intel.com>
-
- Update: November 2012
- -- sysfs-based SRIOV enable-/disable-ment
- Donald Dutile <ddutile@redhat.com>
-
-1. Overview
-
-1.1 What is SR-IOV
-
-Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended
-capability which makes one physical device appear as multiple virtual
-devices. The physical device is referred to as Physical Function (PF)
-while the virtual devices are referred to as Virtual Functions (VF).
-Allocation of the VF can be dynamically controlled by the PF via
-registers encapsulated in the capability. By default, this feature is
-not enabled and the PF behaves as traditional PCIe device. Once it's
-turned on, each VF's PCI configuration space can be accessed by its own
-Bus, Device and Function Number (Routing ID). And each VF also has PCI
-Memory Space, which is used to map its register set. VF device driver
-operates on the register set so it can be functional and appear as a
-real existing PCI device.
-
-2. User Guide
-
-2.1 How can I enable SR-IOV capability
-
-Multiple methods are available for SR-IOV enablement.
-In the first method, the device driver (PF driver) will control the
-enabling and disabling of the capability via API provided by SR-IOV core.
-If the hardware has SR-IOV capability, loading its PF driver would
-enable it and all VFs associated with the PF. Some PF drivers require
-a module parameter to be set to determine the number of VFs to enable.
-In the second method, a write to the sysfs file sriov_numvfs will
-enable and disable the VFs associated with a PCIe PF. This method
-enables per-PF, VF enable/disable values versus the first method,
-which applies to all PFs of the same device. Additionally, the
-PCI SRIOV core support ensures that enable/disable operations are
-valid to reduce duplication in multiple drivers for the same
-checks, e.g., check numvfs == 0 if enabling VFs, ensure
-numvfs <= totalvfs.
-The second method is the recommended method for new/future VF devices.
-
-2.2 How can I use the Virtual Functions
-
-The VF is treated as hot-plugged PCI devices in the kernel, so they
-should be able to work in the same way as real PCI devices. The VF
-requires device driver that is same as a normal PCI device's.
-
-3. Developer Guide
-
-3.1 SR-IOV API
-
-To enable SR-IOV capability:
-(a) For the first method, in the driver:
- int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn);
- 'nr_virtfn' is number of VFs to be enabled.
-(b) For the second method, from sysfs:
- echo 'nr_virtfn' > \
- /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
-
-To disable SR-IOV capability:
-(a) For the first method, in the driver:
- void pci_disable_sriov(struct pci_dev *dev);
-(b) For the second method, from sysfs:
- echo 0 > \
- /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs
-
-3.2 Usage example
-
-Following piece of code illustrates the usage of the SR-IOV API.
-
-static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id)
-{
- pci_enable_sriov(dev, NR_VIRTFN);
-
- ...
-
- return 0;
-}
-
-static void dev_remove(struct pci_dev *dev)
-{
- pci_disable_sriov(dev);
-
- ...
-}
-
-static int dev_suspend(struct pci_dev *dev, pm_message_t state)
-{
- ...
-
- return 0;
-}
-
-static int dev_resume(struct pci_dev *dev)
-{
- ...
-
- return 0;
-}
-
-static void dev_shutdown(struct pci_dev *dev)
-{
- ...
-}
-
-static int dev_sriov_configure(struct pci_dev *dev, int numvfs)
-{
- if (numvfs > 0) {
- ...
- pci_enable_sriov(dev, numvfs);
- ...
- return numvfs;
- }
- if (numvfs == 0) {
- ....
- pci_disable_sriov(dev);
- ...
- return 0;
- }
-}
-
-static struct pci_driver dev_driver = {
- .name = "SR-IOV Physical Function driver",
- .id_table = dev_id_table,
- .probe = dev_probe,
- .remove = dev_remove,
- .suspend = dev_suspend,
- .resume = dev_resume,
- .shutdown = dev_shutdown,
- .sriov_configure = dev_sriov_configure,
-};
diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
new file mode 100644
index 000000000000..f4d2662871ab
--- /dev/null
+++ b/Documentation/PCI/pci.rst
@@ -0,0 +1,578 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+How To Write Linux PCI Drivers
+==============================
+
+:Authors: - Martin Mares <mj@ucw.cz>
+ - Grant Grundler <grundler@parisc-linux.org>
+
+The world of PCI is vast and full of (mostly unpleasant) surprises.
+Since each CPU architecture implements different chip-sets and PCI devices
+have different requirements (erm, "features"), the result is the PCI support
+in the Linux kernel is not as trivial as one would wish. This short paper
+tries to introduce all potential driver authors to Linux APIs for
+PCI device drivers.
+
+A more complete resource is the third edition of "Linux Device Drivers"
+by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
+LDD3 is available for free (under Creative Commons License) from:
+https://lwn.net/Kernel/LDD3/.
+
+However, keep in mind that all documents are subject to "bit rot".
+Refer to the source code if things are not working as described here.
+
+Please send questions/comments/patches about Linux PCI API to the
+"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
+
+
+Structure of PCI drivers
+========================
+PCI drivers "discover" PCI devices in a system via pci_register_driver().
+Actually, it's the other way around. When the PCI generic code discovers
+a new device, the driver with a matching "description" will be notified.
+Details on this below.
+
+pci_register_driver() leaves most of the probing for devices to
+the PCI layer and supports online insertion/removal of devices [thus
+supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
+pci_register_driver() call requires passing in a table of function
+pointers and thus dictates the high level structure of a driver.
+
+Once the driver knows about a PCI device and takes ownership, the
+driver generally needs to perform the following initialization:
+
+ - Enable the device
+ - Request MMIO/IOP resources
+ - Set the DMA mask size (for both coherent and streaming DMA)
+ - Allocate and initialize shared control data (pci_allocate_coherent())
+ - Access device configuration space (if needed)
+ - Register IRQ handler (request_irq())
+ - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
+ - Enable DMA/processing engines
+
+When done using the device, and perhaps the module needs to be unloaded,
+the driver needs to take the following steps:
+
+ - Disable the device from generating IRQs
+ - Release the IRQ (free_irq())
+ - Stop all DMA activity
+ - Release DMA buffers (both streaming and coherent)
+ - Unregister from other subsystems (e.g. scsi or netdev)
+ - Release MMIO/IOP resources
+ - Disable the device
+
+Most of these topics are covered in the following sections.
+For the rest look at LDD3 or <linux/pci.h> .
+
+If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
+the PCI functions described below are defined as inline functions either
+completely empty or just returning an appropriate error codes to avoid
+lots of ifdefs in the drivers.
+
+
+pci_register_driver() call
+==========================
+
+PCI device drivers call ``pci_register_driver()`` during their
+initialization with a pointer to a structure describing the driver
+(``struct pci_driver``):
+
+.. kernel-doc:: include/linux/pci.h
+ :functions: pci_driver
+
+The ID table is an array of ``struct pci_device_id`` entries ending with an
+all-zero entry. Definitions with static const are generally preferred.
+
+.. kernel-doc:: include/linux/mod_devicetable.h
+ :functions: pci_device_id
+
+Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
+a pci_device_id table.
+
+New PCI IDs may be added to a device driver pci_ids table at runtime
+as shown below::
+
+ echo "vendor device subvendor subdevice class class_mask driver_data" > \
+ /sys/bus/pci/drivers/{driver}/new_id
+
+All fields are passed in as hexadecimal values (no leading 0x).
+The vendor and device fields are mandatory, the others are optional. Users
+need pass only as many optional fields as necessary:
+
+ - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
+ - class and classmask fields default to 0
+ - driver_data defaults to 0UL.
+ - override_only field defaults to 0.
+
+Note that driver_data must match the value used by any of the pci_device_id
+entries defined in the driver. This makes the driver_data field mandatory
+if all the pci_device_id entries have a non-zero driver_data value.
+
+Once added, the driver probe routine will be invoked for any unclaimed
+PCI devices listed in its (newly updated) pci_ids list.
+
+When the driver exits, it just calls pci_unregister_driver() and the PCI layer
+automatically calls the remove hook for all devices handled by the driver.
+
+
+"Attributes" for driver functions/data
+--------------------------------------
+
+Please mark the initialization and cleanup functions where appropriate
+(the corresponding macros are defined in <linux/init.h>):
+
+ ====== =================================================
+ __init Initialization code. Thrown away after the driver
+ initializes.
+ __exit Exit code. Ignored for non-modular drivers.
+ ====== =================================================
+
+Tips on when/where to use the above attributes:
+ - The module_init()/module_exit() functions (and all
+ initialization functions called _only_ from these)
+ should be marked __init/__exit.
+
+ - Do not mark the struct pci_driver.
+
+ - Do NOT mark a function if you are not sure which mark to use.
+ Better to not mark the function than mark the function wrong.
+
+
+How to find PCI devices manually
+================================
+
+PCI drivers should have a really good reason for not using the
+pci_register_driver() interface to search for PCI devices.
+The main reason PCI devices are controlled by multiple drivers
+is because one PCI device implements several different HW services.
+E.g. combined serial/parallel port/floppy controller.
+
+A manual search may be performed using the following constructs:
+
+Searching by vendor and device ID::
+
+ struct pci_dev *dev = NULL;
+ while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
+ configure_device(dev);
+
+Searching by class ID (iterate in a similar way)::
+
+ pci_get_class(CLASS_ID, dev)
+
+Searching by both vendor/device and subsystem vendor/device ID::
+
+ pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
+
+You can use the constant PCI_ANY_ID as a wildcard replacement for
+VENDOR_ID or DEVICE_ID. This allows searching for any device from a
+specific vendor, for example.
+
+These functions are hotplug-safe. They increment the reference count on
+the pci_dev that they return. You must eventually (possibly at module unload)
+decrement the reference count on these devices by calling pci_dev_put().
+
+
+Device Initialization Steps
+===========================
+
+As noted in the introduction, most PCI drivers need the following steps
+for device initialization:
+
+ - Enable the device
+ - Request MMIO/IOP resources
+ - Set the DMA mask size (for both coherent and streaming DMA)
+ - Allocate and initialize shared control data (pci_allocate_coherent())
+ - Access device configuration space (if needed)
+ - Register IRQ handler (request_irq())
+ - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
+ - Enable DMA/processing engines.
+
+The driver can access PCI config space registers at any time.
+(Well, almost. When running BIST, config space can go away...but
+that will just result in a PCI Bus Master Abort and config reads
+will return garbage).
+
+
+Enable the PCI device
+---------------------
+Before touching any device registers, the driver needs to enable
+the PCI device by calling pci_enable_device(). This will:
+
+ - wake up the device if it was in suspended state,
+ - allocate I/O and memory regions of the device (if BIOS did not),
+ - allocate an IRQ (if BIOS did not).
+
+.. note::
+ pci_enable_device() can fail! Check the return value.
+
+.. warning::
+ OS BUG: we don't check resource allocations before enabling those
+ resources. The sequence would make more sense if we called
+ pci_request_resources() before calling pci_enable_device().
+ Currently, the device drivers can't detect the bug when two
+ devices have been allocated the same range. This is not a common
+ problem and unlikely to get fixed soon.
+
+ This has been discussed before but not changed as of 2.6.19:
+ https://lore.kernel.org/r/20060302180025.GC28895@flint.arm.linux.org.uk/
+
+
+pci_set_master() will enable DMA by setting the bus master bit
+in the PCI_COMMAND register. It also fixes the latency timer value if
+it's set to something bogus by the BIOS. pci_clear_master() will
+disable DMA by clearing the bus master bit.
+
+If the PCI device can use the PCI Memory-Write-Invalidate transaction,
+call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
+and also ensures that the cache line size register is set correctly.
+Check the return value of pci_set_mwi() as not all architectures
+or chip-sets may support Memory-Write-Invalidate. Alternatively,
+if Mem-Wr-Inval would be nice to have but is not required, call
+pci_try_set_mwi() to have the system do its best effort at enabling
+Mem-Wr-Inval.
+
+
+Request MMIO/IOP resources
+--------------------------
+Memory (MMIO), and I/O port addresses should NOT be read directly
+from the PCI device config space. Use the values in the pci_dev structure
+as the PCI "bus address" might have been remapped to a "host physical"
+address by the arch/chip-set specific kernel support.
+
+See Documentation/driver-api/io-mapping.rst for how to access device registers
+or device memory.
+
+The device driver needs to call pci_request_region() to verify
+no other device is already using the same address resource.
+Conversely, drivers should call pci_release_region() AFTER
+calling pci_disable_device().
+The idea is to prevent two devices colliding on the same address range.
+
+.. tip::
+ See OS BUG comment above. Currently (2.6.19), The driver can only
+ determine MMIO and IO Port resource availability _after_ calling
+ pci_enable_device().
+
+Generic flavors of pci_request_region() are request_mem_region()
+(for MMIO ranges) and request_region() (for IO Port ranges).
+Use these for address resources that are not described by "normal" PCI
+BARs.
+
+Also see pci_request_selected_regions() below.
+
+
+Set the DMA mask size
+---------------------
+.. note::
+ If anything below doesn't make sense, please refer to
+ Documentation/core-api/dma-api.rst. This section is just a reminder that
+ drivers need to indicate DMA capabilities of the device and is not
+ an authoritative source for DMA interfaces.
+
+While all drivers should explicitly indicate the DMA capability
+(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
+32-bit bus master capability for streaming data need the driver
+to "register" this capability by calling dma_set_mask() with
+appropriate parameters. In general this allows more efficient DMA
+on systems where System RAM exists above 4G _physical_ address.
+
+Drivers for all PCI-X and PCIe compliant devices must call
+dma_set_mask() as they are 64-bit DMA devices.
+
+Similarly, drivers must also "register" this capability if the device
+can directly address "coherent memory" in System RAM above 4G physical
+address by calling dma_set_coherent_mask().
+Again, this includes drivers for all PCI-X and PCIe compliant devices.
+Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
+64-bit DMA capable for payload ("streaming") data but not control
+("coherent") data.
+
+
+Setup shared control data
+-------------------------
+Once the DMA masks are set, the driver can allocate "coherent" (a.k.a. shared)
+memory. See Documentation/core-api/dma-api.rst for a full description of
+the DMA APIs. This section is just a reminder that it needs to be done
+before enabling DMA on the device.
+
+
+Initialize device registers
+---------------------------
+Some drivers will need specific "capability" fields programmed
+or other "vendor specific" register initialized or reset.
+E.g. clearing pending interrupts.
+
+
+Register IRQ handler
+--------------------
+While calling request_irq() is the last step described here,
+this is often just another intermediate step to initialize a device.
+This step can often be deferred until the device is opened for use.
+
+All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
+and use the devid to map IRQs to devices (remember that all PCI IRQ lines
+can be shared).
+
+request_irq() will associate an interrupt handler and device handle
+with an interrupt number. Historically interrupt numbers represent
+IRQ lines which run from the PCI device to the Interrupt controller.
+With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
+
+request_irq() also enables the interrupt. Make sure the device is
+quiesced and does not have any interrupts pending before registering
+the interrupt handler.
+
+MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
+which deliver interrupts to the CPU via a DMA write to a Local APIC.
+The fundamental difference between MSI and MSI-X is how multiple
+"vectors" get allocated. MSI requires contiguous blocks of vectors
+while MSI-X can allocate several individual ones.
+
+MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
+PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
+causes the PCI support to program CPU vector data into the PCI device
+capability registers. Many architectures, chip-sets, or BIOSes do NOT
+support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
+the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
+specify PCI_IRQ_INTX as well.
+
+Drivers that have different interrupt handlers for MSI/MSI-X and
+legacy INTx should chose the right one based on the msi_enabled
+and msix_enabled flags in the pci_dev structure after calling
+pci_alloc_irq_vectors.
+
+There are (at least) two really good reasons for using MSI:
+
+1) MSI is an exclusive interrupt vector by definition.
+ This means the interrupt handler doesn't have to verify
+ its device caused the interrupt.
+
+2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
+ to be visible to the host CPU(s) when the MSI is delivered. This
+ is important for both data coherency and avoiding stale control data.
+ This guarantee allows the driver to omit MMIO reads to flush
+ the DMA stream.
+
+See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
+of MSI/MSI-X usage.
+
+
+PCI device shutdown
+===================
+
+When a PCI device driver is being unloaded, most of the following
+steps need to be performed:
+
+ - Disable the device from generating IRQs
+ - Release the IRQ (free_irq())
+ - Stop all DMA activity
+ - Release DMA buffers (both streaming and coherent)
+ - Unregister from other subsystems (e.g. scsi or netdev)
+ - Disable device from responding to MMIO/IO Port addresses
+ - Release MMIO/IO Port resource(s)
+
+
+Stop IRQs on the device
+-----------------------
+How to do this is chip/device specific. If it's not done, it opens
+the possibility of a "screaming interrupt" if (and only if)
+the IRQ is shared with another device.
+
+When the shared IRQ handler is "unhooked", the remaining devices
+using the same IRQ line will still need the IRQ enabled. Thus if the
+"unhooked" device asserts IRQ line, the system will respond assuming
+it was one of the remaining devices asserted the IRQ line. Since none
+of the other devices will handle the IRQ, the system will "hang" until
+it decides the IRQ isn't going to get handled and masks the IRQ (100,000
+iterations later). Once the shared IRQ is masked, the remaining devices
+will stop functioning properly. Not a nice situation.
+
+This is another reason to use MSI or MSI-X if it's available.
+MSI and MSI-X are defined to be exclusive interrupts and thus
+are not susceptible to the "screaming interrupt" problem.
+
+
+Release the IRQ
+---------------
+Once the device is quiesced (no more IRQs), one can call free_irq().
+This function will return control once any pending IRQs are handled,
+"unhook" the drivers IRQ handler from that IRQ, and finally release
+the IRQ if no one else is using it.
+
+
+Stop all DMA activity
+---------------------
+It's extremely important to stop all DMA operations BEFORE attempting
+to deallocate DMA control data. Failure to do so can result in memory
+corruption, hangs, and on some chip-sets a hard crash.
+
+Stopping DMA after stopping the IRQs can avoid races where the
+IRQ handler might restart DMA engines.
+
+While this step sounds obvious and trivial, several "mature" drivers
+didn't get this step right in the past.
+
+
+Release DMA buffers
+-------------------
+Once DMA is stopped, clean up streaming DMA first.
+I.e. unmap data buffers and return buffers to "upstream"
+owners if there is one.
+
+Then clean up "coherent" buffers which contain the control data.
+
+See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
+
+
+Unregister from other subsystems
+--------------------------------
+Most low level PCI device drivers support some other subsystem
+like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
+driver isn't losing resources from that other subsystem.
+If this happens, typically the symptom is an Oops (panic) when
+the subsystem attempts to call into a driver that has been unloaded.
+
+
+Disable Device from responding to MMIO/IO Port addresses
+--------------------------------------------------------
+io_unmap() MMIO or IO Port resources and then call pci_disable_device().
+This is the symmetric opposite of pci_enable_device().
+Do not access device registers after calling pci_disable_device().
+
+
+Release MMIO/IO Port Resource(s)
+--------------------------------
+Call pci_release_region() to mark the MMIO or IO Port range as available.
+Failure to do so usually results in the inability to reload the driver.
+
+
+How to access PCI config space
+==============================
+
+You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
+space of a device represented by `struct pci_dev *`. All these functions return
+0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
+text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
+devices don't fail.
+
+If you don't have a struct pci_dev available, you can call
+`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
+and function on that bus.
+
+If you access fields in the standard portion of the config header, please
+use symbolic names of locations and bits declared in <linux/pci.h>.
+
+If you need to access Extended PCI Capability registers, just call
+pci_find_capability() for the particular capability and it will find the
+corresponding register block for you.
+
+
+Other interesting functions
+===========================
+
+============================= ================================================
+pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
+ bus and slot and number. If the device is
+ found, its reference count is increased.
+pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
+pci_find_capability() Find specified capability in device's capability
+ list.
+pci_resource_start() Returns bus start address for a given PCI region
+pci_resource_end() Returns bus end address for a given PCI region
+pci_resource_len() Returns the byte length of a PCI region
+pci_set_drvdata() Set private driver data pointer for a pci_dev
+pci_get_drvdata() Return private driver data pointer for a pci_dev
+pci_set_mwi() Enable Memory-Write-Invalidate transactions.
+pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
+============================= ================================================
+
+
+Miscellaneous hints
+===================
+
+When displaying PCI device names to the user (for example when a driver wants
+to tell the user what card has it found), please use pci_name(pci_dev).
+
+Always refer to the PCI devices by a pointer to the pci_dev structure.
+All PCI layer functions use this identification and it's the only
+reasonable one. Don't use bus/slot/function numbers except for very
+special purposes -- on systems with multiple primary buses their semantics
+can be pretty complex.
+
+Don't try to turn on Fast Back to Back writes in your driver. All devices
+on the bus need to be capable of doing it, so this is something which needs
+to be handled by platform and generic code, not individual drivers.
+
+
+Vendor and device identifications
+=================================
+
+Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
+are shared across multiple drivers. You can add private definitions in
+your driver if they're helpful, or just use plain hex constants.
+
+The device IDs are arbitrary hex numbers (vendor controlled) and normally used
+only in a single location, the pci_device_id table.
+
+Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
+There's a mirror of the pci.ids file at https://github.com/pciutils/pciids.
+
+
+Obsolete functions
+==================
+
+There are several functions which you might come across when trying to
+port an old driver to the new PCI interface. They are no longer present
+in the kernel as they aren't compatible with hotplug or PCI domains or
+having sane locking.
+
+================= ===========================================
+pci_find_device() Superseded by pci_get_device()
+pci_find_subsys() Superseded by pci_get_subsys()
+pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
+pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
+================= ===========================================
+
+The alternative is the traditional PCI device driver that walks PCI
+device lists. This is still possible but discouraged.
+
+
+MMIO Space and "Write Posting"
+==============================
+
+Converting a driver from using I/O Port space to using MMIO space
+often requires some additional changes. Specifically, "write posting"
+needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
+already do this. I/O Port space guarantees write transactions reach the PCI
+device before the CPU can continue. Writes to MMIO space allow the CPU
+to continue before the transaction reaches the PCI device. HW weenies
+call this "Write Posting" because the write completion is "posted" to
+the CPU before the transaction has reached its destination.
+
+Thus, timing sensitive code should add readl() where the CPU is
+expected to wait before doing other work. The classic "bit banging"
+sequence works fine for I/O Port space::
+
+ for (i = 8; --i; val >>= 1) {
+ outb(val & 1, ioport_reg); /* write bit */
+ udelay(10);
+ }
+
+The same sequence for MMIO space should be::
+
+ for (i = 8; --i; val >>= 1) {
+ writeb(val & 1, mmio_reg); /* write bit */
+ readb(safe_mmio_reg); /* flush posted write */
+ udelay(10);
+ }
+
+It is important that "safe_mmio_reg" not have any side effects that
+interferes with the correct operation of the device.
+
+Another case to watch out for is when resetting a PCI device. Use PCI
+Configuration space reads to flush the writel(). This will gracefully
+handle the PCI master abort on all platforms if the PCI device is
+expected to not respond to a readl(). Most x86 platforms will allow
+MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
+(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt
deleted file mode 100644
index 123881f62219..000000000000
--- a/Documentation/PCI/pci.txt
+++ /dev/null
@@ -1,635 +0,0 @@
-
- How To Write Linux PCI Drivers
-
- by Martin Mares <mj@ucw.cz> on 07-Feb-2000
- updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The world of PCI is vast and full of (mostly unpleasant) surprises.
-Since each CPU architecture implements different chip-sets and PCI devices
-have different requirements (erm, "features"), the result is the PCI support
-in the Linux kernel is not as trivial as one would wish. This short paper
-tries to introduce all potential driver authors to Linux APIs for
-PCI device drivers.
-
-A more complete resource is the third edition of "Linux Device Drivers"
-by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
-LDD3 is available for free (under Creative Commons License) from:
-
- http://lwn.net/Kernel/LDD3/
-
-However, keep in mind that all documents are subject to "bit rot".
-Refer to the source code if things are not working as described here.
-
-Please send questions/comments/patches about Linux PCI API to the
-"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
-
-
-
-0. Structure of PCI drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-PCI drivers "discover" PCI devices in a system via pci_register_driver().
-Actually, it's the other way around. When the PCI generic code discovers
-a new device, the driver with a matching "description" will be notified.
-Details on this below.
-
-pci_register_driver() leaves most of the probing for devices to
-the PCI layer and supports online insertion/removal of devices [thus
-supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
-pci_register_driver() call requires passing in a table of function
-pointers and thus dictates the high level structure of a driver.
-
-Once the driver knows about a PCI device and takes ownership, the
-driver generally needs to perform the following initialization:
-
- Enable the device
- Request MMIO/IOP resources
- Set the DMA mask size (for both coherent and streaming DMA)
- Allocate and initialize shared control data (pci_allocate_coherent())
- Access device configuration space (if needed)
- Register IRQ handler (request_irq())
- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
- Enable DMA/processing engines
-
-When done using the device, and perhaps the module needs to be unloaded,
-the driver needs to take the follow steps:
- Disable the device from generating IRQs
- Release the IRQ (free_irq())
- Stop all DMA activity
- Release DMA buffers (both streaming and coherent)
- Unregister from other subsystems (e.g. scsi or netdev)
- Release MMIO/IOP resources
- Disable the device
-
-Most of these topics are covered in the following sections.
-For the rest look at LDD3 or <linux/pci.h> .
-
-If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
-the PCI functions described below are defined as inline functions either
-completely empty or just returning an appropriate error codes to avoid
-lots of ifdefs in the drivers.
-
-
-
-1. pci_register_driver() call
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-PCI device drivers call pci_register_driver() during their
-initialization with a pointer to a structure describing the driver
-(struct pci_driver):
-
- field name Description
- ---------- ------------------------------------------------------
- id_table Pointer to table of device ID's the driver is
- interested in. Most drivers should export this
- table using MODULE_DEVICE_TABLE(pci,...).
-
- probe This probing function gets called (during execution
- of pci_register_driver() for already existing
- devices or later if a new device gets inserted) for
- all PCI devices which match the ID table and are not
- "owned" by the other drivers yet. This function gets
- passed a "struct pci_dev *" for each device whose
- entry in the ID table matches the device. The probe
- function returns zero when the driver chooses to
- take "ownership" of the device or an error code
- (negative number) otherwise.
- The probe function always gets called from process
- context, so it can sleep.
-
- remove The remove() function gets called whenever a device
- being handled by this driver is removed (either during
- deregistration of the driver or when it's manually
- pulled out of a hot-pluggable slot).
- The remove function always gets called from process
- context, so it can sleep.
-
- suspend Put device into low power state.
- suspend_late Put device into low power state.
-
- resume_early Wake device from low power state.
- resume Wake device from low power state.
-
- (Please see Documentation/power/pci.txt for descriptions
- of PCI Power Management and the related functions.)
-
- shutdown Hook into reboot_notifier_list (kernel/sys.c).
- Intended to stop any idling DMA operations.
- Useful for enabling wake-on-lan (NIC) or changing
- the power state of a device before reboot.
- e.g. drivers/net/e100.c.
-
- err_handler See Documentation/PCI/pci-error-recovery.txt
-
-
-The ID table is an array of struct pci_device_id entries ending with an
-all-zero entry. Definitions with static const are generally preferred.
-Use of the deprecated macro DEFINE_PCI_DEVICE_TABLE should be avoided.
-
-Each entry consists of:
-
- vendor,device Vendor and device ID to match (or PCI_ANY_ID)
-
- subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID)
- subdevice,
-
- class Device class, subclass, and "interface" to match.
- See Appendix D of the PCI Local Bus Spec or
- include/linux/pci_ids.h for a full list of classes.
- Most drivers do not need to specify class/class_mask
- as vendor/device is normally sufficient.
-
- class_mask limit which sub-fields of the class field are compared.
- See drivers/scsi/sym53c8xx_2/ for example of usage.
-
- driver_data Data private to the driver.
- Most drivers don't need to use driver_data field.
- Best practice is to use driver_data as an index
- into a static list of equivalent device types,
- instead of using it as a pointer.
-
-
-Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up
-a pci_device_id table.
-
-New PCI IDs may be added to a device driver pci_ids table at runtime
-as shown below:
-
-echo "vendor device subvendor subdevice class class_mask driver_data" > \
-/sys/bus/pci/drivers/{driver}/new_id
-
-All fields are passed in as hexadecimal values (no leading 0x).
-The vendor and device fields are mandatory, the others are optional. Users
-need pass only as many optional fields as necessary:
- o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
- o class and classmask fields default to 0
- o driver_data defaults to 0UL.
-
-Note that driver_data must match the value used by any of the pci_device_id
-entries defined in the driver. This makes the driver_data field mandatory
-if all the pci_device_id entries have a non-zero driver_data value.
-
-Once added, the driver probe routine will be invoked for any unclaimed
-PCI devices listed in its (newly updated) pci_ids list.
-
-When the driver exits, it just calls pci_unregister_driver() and the PCI layer
-automatically calls the remove hook for all devices handled by the driver.
-
-
-1.1 "Attributes" for driver functions/data
-
-Please mark the initialization and cleanup functions where appropriate
-(the corresponding macros are defined in <linux/init.h>):
-
- __init Initialization code. Thrown away after the driver
- initializes.
- __exit Exit code. Ignored for non-modular drivers.
-
-Tips on when/where to use the above attributes:
- o The module_init()/module_exit() functions (and all
- initialization functions called _only_ from these)
- should be marked __init/__exit.
-
- o Do not mark the struct pci_driver.
-
- o Do NOT mark a function if you are not sure which mark to use.
- Better to not mark the function than mark the function wrong.
-
-
-
-2. How to find PCI devices manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-PCI drivers should have a really good reason for not using the
-pci_register_driver() interface to search for PCI devices.
-The main reason PCI devices are controlled by multiple drivers
-is because one PCI device implements several different HW services.
-E.g. combined serial/parallel port/floppy controller.
-
-A manual search may be performed using the following constructs:
-
-Searching by vendor and device ID:
-
- struct pci_dev *dev = NULL;
- while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
- configure_device(dev);
-
-Searching by class ID (iterate in a similar way):
-
- pci_get_class(CLASS_ID, dev)
-
-Searching by both vendor/device and subsystem vendor/device ID:
-
- pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
-
-You can use the constant PCI_ANY_ID as a wildcard replacement for
-VENDOR_ID or DEVICE_ID. This allows searching for any device from a
-specific vendor, for example.
-
-These functions are hotplug-safe. They increment the reference count on
-the pci_dev that they return. You must eventually (possibly at module unload)
-decrement the reference count on these devices by calling pci_dev_put().
-
-
-
-3. Device Initialization Steps
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As noted in the introduction, most PCI drivers need the following steps
-for device initialization:
-
- Enable the device
- Request MMIO/IOP resources
- Set the DMA mask size (for both coherent and streaming DMA)
- Allocate and initialize shared control data (pci_allocate_coherent())
- Access device configuration space (if needed)
- Register IRQ handler (request_irq())
- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
- Enable DMA/processing engines.
-
-The driver can access PCI config space registers at any time.
-(Well, almost. When running BIST, config space can go away...but
-that will just result in a PCI Bus Master Abort and config reads
-will return garbage).
-
-
-3.1 Enable the PCI device
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Before touching any device registers, the driver needs to enable
-the PCI device by calling pci_enable_device(). This will:
- o wake up the device if it was in suspended state,
- o allocate I/O and memory regions of the device (if BIOS did not),
- o allocate an IRQ (if BIOS did not).
-
-NOTE: pci_enable_device() can fail! Check the return value.
-
-[ OS BUG: we don't check resource allocations before enabling those
- resources. The sequence would make more sense if we called
- pci_request_resources() before calling pci_enable_device().
- Currently, the device drivers can't detect the bug when when two
- devices have been allocated the same range. This is not a common
- problem and unlikely to get fixed soon.
-
- This has been discussed before but not changed as of 2.6.19:
- http://lkml.org/lkml/2006/3/2/194
-]
-
-pci_set_master() will enable DMA by setting the bus master bit
-in the PCI_COMMAND register. It also fixes the latency timer value if
-it's set to something bogus by the BIOS. pci_clear_master() will
-disable DMA by clearing the bus master bit.
-
-If the PCI device can use the PCI Memory-Write-Invalidate transaction,
-call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
-and also ensures that the cache line size register is set correctly.
-Check the return value of pci_set_mwi() as not all architectures
-or chip-sets may support Memory-Write-Invalidate. Alternatively,
-if Mem-Wr-Inval would be nice to have but is not required, call
-pci_try_set_mwi() to have the system do its best effort at enabling
-Mem-Wr-Inval.
-
-
-3.2 Request MMIO/IOP resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Memory (MMIO), and I/O port addresses should NOT be read directly
-from the PCI device config space. Use the values in the pci_dev structure
-as the PCI "bus address" might have been remapped to a "host physical"
-address by the arch/chip-set specific kernel support.
-
-See Documentation/io-mapping.txt for how to access device registers
-or device memory.
-
-The device driver needs to call pci_request_region() to verify
-no other device is already using the same address resource.
-Conversely, drivers should call pci_release_region() AFTER
-calling pci_disable_device().
-The idea is to prevent two devices colliding on the same address range.
-
-[ See OS BUG comment above. Currently (2.6.19), The driver can only
- determine MMIO and IO Port resource availability _after_ calling
- pci_enable_device(). ]
-
-Generic flavors of pci_request_region() are request_mem_region()
-(for MMIO ranges) and request_region() (for IO Port ranges).
-Use these for address resources that are not described by "normal" PCI
-BARs.
-
-Also see pci_request_selected_regions() below.
-
-
-3.3 Set the DMA mask size
-~~~~~~~~~~~~~~~~~~~~~~~~~
-[ If anything below doesn't make sense, please refer to
- Documentation/DMA-API.txt. This section is just a reminder that
- drivers need to indicate DMA capabilities of the device and is not
- an authoritative source for DMA interfaces. ]
-
-While all drivers should explicitly indicate the DMA capability
-(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
-32-bit bus master capability for streaming data need the driver
-to "register" this capability by calling pci_set_dma_mask() with
-appropriate parameters. In general this allows more efficient DMA
-on systems where System RAM exists above 4G _physical_ address.
-
-Drivers for all PCI-X and PCIe compliant devices must call
-pci_set_dma_mask() as they are 64-bit DMA devices.
-
-Similarly, drivers must also "register" this capability if the device
-can directly address "consistent memory" in System RAM above 4G physical
-address by calling pci_set_consistent_dma_mask().
-Again, this includes drivers for all PCI-X and PCIe compliant devices.
-Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
-64-bit DMA capable for payload ("streaming") data but not control
-("consistent") data.
-
-
-3.4 Setup shared control data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory. See Documentation/DMA-API.txt for a full description of
-the DMA APIs. This section is just a reminder that it needs to be done
-before enabling DMA on the device.
-
-
-3.5 Initialize device registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Some drivers will need specific "capability" fields programmed
-or other "vendor specific" register initialized or reset.
-E.g. clearing pending interrupts.
-
-
-3.6 Register IRQ handler
-~~~~~~~~~~~~~~~~~~~~~~~~
-While calling request_irq() is the last step described here,
-this is often just another intermediate step to initialize a device.
-This step can often be deferred until the device is opened for use.
-
-All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
-and use the devid to map IRQs to devices (remember that all PCI IRQ lines
-can be shared).
-
-request_irq() will associate an interrupt handler and device handle
-with an interrupt number. Historically interrupt numbers represent
-IRQ lines which run from the PCI device to the Interrupt controller.
-With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
-
-request_irq() also enables the interrupt. Make sure the device is
-quiesced and does not have any interrupts pending before registering
-the interrupt handler.
-
-MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
-which deliver interrupts to the CPU via a DMA write to a Local APIC.
-The fundamental difference between MSI and MSI-X is how multiple
-"vectors" get allocated. MSI requires contiguous blocks of vectors
-while MSI-X can allocate several individual ones.
-
-MSI capability can be enabled by calling pci_enable_msi() or
-pci_enable_msix() before calling request_irq(). This causes
-the PCI support to program CPU vector data into the PCI device
-capability registers.
-
-If your PCI device supports both, try to enable MSI-X first.
-Only one can be enabled at a time. Many architectures, chip-sets,
-or BIOSes do NOT support MSI or MSI-X and the call to pci_enable_msi/msix
-will fail. This is important to note since many drivers have
-two (or more) interrupt handlers: one for MSI/MSI-X and another for IRQs.
-They choose which handler to register with request_irq() based on the
-return value from pci_enable_msi/msix().
-
-There are (at least) two really good reasons for using MSI:
-1) MSI is an exclusive interrupt vector by definition.
- This means the interrupt handler doesn't have to verify
- its device caused the interrupt.
-
-2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
- to be visible to the host CPU(s) when the MSI is delivered. This
- is important for both data coherency and avoiding stale control data.
- This guarantee allows the driver to omit MMIO reads to flush
- the DMA stream.
-
-See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
-of MSI/MSI-X usage.
-
-
-
-4. PCI device shutdown
-~~~~~~~~~~~~~~~~~~~~~~~
-
-When a PCI device driver is being unloaded, most of the following
-steps need to be performed:
-
- Disable the device from generating IRQs
- Release the IRQ (free_irq())
- Stop all DMA activity
- Release DMA buffers (both streaming and consistent)
- Unregister from other subsystems (e.g. scsi or netdev)
- Disable device from responding to MMIO/IO Port addresses
- Release MMIO/IO Port resource(s)
-
-
-4.1 Stop IRQs on the device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-How to do this is chip/device specific. If it's not done, it opens
-the possibility of a "screaming interrupt" if (and only if)
-the IRQ is shared with another device.
-
-When the shared IRQ handler is "unhooked", the remaining devices
-using the same IRQ line will still need the IRQ enabled. Thus if the
-"unhooked" device asserts IRQ line, the system will respond assuming
-it was one of the remaining devices asserted the IRQ line. Since none
-of the other devices will handle the IRQ, the system will "hang" until
-it decides the IRQ isn't going to get handled and masks the IRQ (100,000
-iterations later). Once the shared IRQ is masked, the remaining devices
-will stop functioning properly. Not a nice situation.
-
-This is another reason to use MSI or MSI-X if it's available.
-MSI and MSI-X are defined to be exclusive interrupts and thus
-are not susceptible to the "screaming interrupt" problem.
-
-
-4.2 Release the IRQ
-~~~~~~~~~~~~~~~~~~~
-Once the device is quiesced (no more IRQs), one can call free_irq().
-This function will return control once any pending IRQs are handled,
-"unhook" the drivers IRQ handler from that IRQ, and finally release
-the IRQ if no one else is using it.
-
-
-4.3 Stop all DMA activity
-~~~~~~~~~~~~~~~~~~~~~~~~~
-It's extremely important to stop all DMA operations BEFORE attempting
-to deallocate DMA control data. Failure to do so can result in memory
-corruption, hangs, and on some chip-sets a hard crash.
-
-Stopping DMA after stopping the IRQs can avoid races where the
-IRQ handler might restart DMA engines.
-
-While this step sounds obvious and trivial, several "mature" drivers
-didn't get this step right in the past.
-
-
-4.4 Release DMA buffers
-~~~~~~~~~~~~~~~~~~~~~~~
-Once DMA is stopped, clean up streaming DMA first.
-I.e. unmap data buffers and return buffers to "upstream"
-owners if there is one.
-
-Then clean up "consistent" buffers which contain the control data.
-
-See Documentation/DMA-API.txt for details on unmapping interfaces.
-
-
-4.5 Unregister from other subsystems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Most low level PCI device drivers support some other subsystem
-like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
-driver isn't losing resources from that other subsystem.
-If this happens, typically the symptom is an Oops (panic) when
-the subsystem attempts to call into a driver that has been unloaded.
-
-
-4.6 Disable Device from responding to MMIO/IO Port addresses
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-io_unmap() MMIO or IO Port resources and then call pci_disable_device().
-This is the symmetric opposite of pci_enable_device().
-Do not access device registers after calling pci_disable_device().
-
-
-4.7 Release MMIO/IO Port Resource(s)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Call pci_release_region() to mark the MMIO or IO Port range as available.
-Failure to do so usually results in the inability to reload the driver.
-
-
-
-5. How to access PCI config space
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can use pci_(read|write)_config_(byte|word|dword) to access the config
-space of a device represented by struct pci_dev *. All these functions return 0
-when successful or an error code (PCIBIOS_...) which can be translated to a text
-string by pcibios_strerror. Most drivers expect that accesses to valid PCI
-devices don't fail.
-
-If you don't have a struct pci_dev available, you can call
-pci_bus_(read|write)_config_(byte|word|dword) to access a given device
-and function on that bus.
-
-If you access fields in the standard portion of the config header, please
-use symbolic names of locations and bits declared in <linux/pci.h>.
-
-If you need to access Extended PCI Capability registers, just call
-pci_find_capability() for the particular capability and it will find the
-corresponding register block for you.
-
-
-
-6. Other interesting functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
- bus and slot and number. If the device is
- found, its reference count is increased.
-pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
-pci_find_capability() Find specified capability in device's capability
- list.
-pci_resource_start() Returns bus start address for a given PCI region
-pci_resource_end() Returns bus end address for a given PCI region
-pci_resource_len() Returns the byte length of a PCI region
-pci_set_drvdata() Set private driver data pointer for a pci_dev
-pci_get_drvdata() Return private driver data pointer for a pci_dev
-pci_set_mwi() Enable Memory-Write-Invalidate transactions.
-pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
-
-
-
-7. Miscellaneous hints
-~~~~~~~~~~~~~~~~~~~~~~
-
-When displaying PCI device names to the user (for example when a driver wants
-to tell the user what card has it found), please use pci_name(pci_dev).
-
-Always refer to the PCI devices by a pointer to the pci_dev structure.
-All PCI layer functions use this identification and it's the only
-reasonable one. Don't use bus/slot/function numbers except for very
-special purposes -- on systems with multiple primary buses their semantics
-can be pretty complex.
-
-Don't try to turn on Fast Back to Back writes in your driver. All devices
-on the bus need to be capable of doing it, so this is something which needs
-to be handled by platform and generic code, not individual drivers.
-
-
-
-8. Vendor and device identifications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
-are shared across multiple drivers. You can add private definitions in
-your driver if they're helpful, or just use plain hex constants.
-
-The device IDs are arbitrary hex numbers (vendor controlled) and normally used
-only in a single location, the pci_device_id table.
-
-Please DO submit new vendor/device IDs to http://pciids.sourceforge.net/.
-
-
-
-9. Obsolete functions
-~~~~~~~~~~~~~~~~~~~~~
-
-There are several functions which you might come across when trying to
-port an old driver to the new PCI interface. They are no longer present
-in the kernel as they aren't compatible with hotplug or PCI domains or
-having sane locking.
-
-pci_find_device() Superseded by pci_get_device()
-pci_find_subsys() Superseded by pci_get_subsys()
-pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
-pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
-
-
-The alternative is the traditional PCI device driver that walks PCI
-device lists. This is still possible but discouraged.
-
-
-
-10. MMIO Space and "Write Posting"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Converting a driver from using I/O Port space to using MMIO space
-often requires some additional changes. Specifically, "write posting"
-needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
-already do this. I/O Port space guarantees write transactions reach the PCI
-device before the CPU can continue. Writes to MMIO space allow the CPU
-to continue before the transaction reaches the PCI device. HW weenies
-call this "Write Posting" because the write completion is "posted" to
-the CPU before the transaction has reached its destination.
-
-Thus, timing sensitive code should add readl() where the CPU is
-expected to wait before doing other work. The classic "bit banging"
-sequence works fine for I/O Port space:
-
- for (i = 8; --i; val >>= 1) {
- outb(val & 1, ioport_reg); /* write bit */
- udelay(10);
- }
-
-The same sequence for MMIO space should be:
-
- for (i = 8; --i; val >>= 1) {
- writeb(val & 1, mmio_reg); /* write bit */
- readb(safe_mmio_reg); /* flush posted write */
- udelay(10);
- }
-
-It is important that "safe_mmio_reg" not have any side effects that
-interferes with the correct operation of the device.
-
-Another case to watch out for is when resetting a PCI device. Use PCI
-Configuration space reads to flush the writel(). This will gracefully
-handle the PCI master abort on all platforms if the PCI device is
-expected to not respond to a readl(). Most x86 platforms will allow
-MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
-(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
-
diff --git a/Documentation/PCI/pcieaer-howto.rst b/Documentation/PCI/pcieaer-howto.rst
new file mode 100644
index 000000000000..3210c4792978
--- /dev/null
+++ b/Documentation/PCI/pcieaer-howto.rst
@@ -0,0 +1,257 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===========================================================
+The PCI Express Advanced Error Reporting Driver Guide HOWTO
+===========================================================
+
+:Authors: - T. Long Nguyen <tom.l.nguyen@intel.com>
+ - Yanmin Zhang <yanmin.zhang@intel.com>
+
+:Copyright: |copy| 2006 Intel Corporation
+
+Overview
+===========
+
+About this guide
+----------------
+
+This guide describes the basics of the PCI Express (PCIe) Advanced Error
+Reporting (AER) driver and provides information on how to use it, as
+well as how to enable the drivers of Endpoint devices to conform with
+the PCIe AER driver.
+
+
+What is the PCIe AER Driver?
+----------------------------
+
+PCIe error signaling can occur on the PCIe link itself
+or on behalf of transactions initiated on the link. PCIe
+defines two error reporting paradigms: the baseline capability and
+the Advanced Error Reporting capability. The baseline capability is
+required of all PCIe components providing a minimum defined
+set of error reporting requirements. Advanced Error Reporting
+capability is implemented with a PCIe Advanced Error Reporting
+extended capability structure providing more robust error reporting.
+
+The PCIe AER driver provides the infrastructure to support PCIe Advanced
+Error Reporting capability. The PCIe AER driver provides three basic
+functions:
+
+ - Gathers the comprehensive error information if errors occurred.
+ - Reports error to the users.
+ - Performs error recovery actions.
+
+The AER driver only attaches to Root Ports and RCECs that support the PCIe
+AER capability.
+
+
+User Guide
+==========
+
+Include the PCIe AER Root Driver into the Linux Kernel
+------------------------------------------------------
+
+The PCIe AER driver is a Root Port service driver attached
+via the PCIe Port Bus driver. If a user wants to use it, the driver
+must be compiled. It is enabled with CONFIG_PCIEAER, which
+depends on CONFIG_PCIEPORTBUS.
+
+Load PCIe AER Root Driver
+-------------------------
+
+Some systems have AER support in firmware. Enabling Linux AER support at
+the same time the firmware handles AER would result in unpredictable
+behavior. Therefore, Linux does not handle AER events unless the firmware
+grants AER control to the OS via the ACPI _OSC method. See the PCI Firmware
+Specification for details regarding _OSC usage.
+
+AER error output
+----------------
+
+When a PCIe AER error is captured, an error message will be output to
+console. If it's a correctable error, it is output as a warning message.
+Otherwise, it is printed as an error. So users could choose different
+log level to filter out correctable error messages.
+
+Below shows an example::
+
+ 0000:50:00.0: PCIe Bus Error: severity=Uncorrectable (Fatal), type=Transaction Layer, (Requester ID)
+ 0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
+ 0000:50:00.0: [20] UnsupReq (First)
+ 0000:50:00.0: TLP Header: 0x04000001 0x00200a03 0x05010000 0x00050100
+
+In the example, 'Requester ID' means the ID of the device that sent
+the error message to the Root Port. Please refer to PCIe specs for other
+fields.
+
+AER Ratelimits
+--------------
+
+Since error messages can be generated for each transaction, we may see
+large volumes of errors reported. To prevent spammy devices from flooding
+the console/stalling execution, messages are throttled by device and error
+type (correctable vs. non-fatal uncorrectable). Fatal errors, including
+DPC errors, are not ratelimited.
+
+AER uses the default ratelimit of DEFAULT_RATELIMIT_BURST (10 events) over
+DEFAULT_RATELIMIT_INTERVAL (5 seconds).
+
+Ratelimits are exposed in the form of sysfs attributes and configurable.
+See Documentation/ABI/testing/sysfs-bus-pci-devices-aer.
+
+AER Statistics / Counters
+-------------------------
+
+When PCIe AER errors are captured, the counters / statistics are also exposed
+in the form of sysfs attributes which are documented at
+Documentation/ABI/testing/sysfs-bus-pci-devices-aer.
+
+Developer Guide
+===============
+
+To enable error recovery, a software driver must provide callbacks.
+
+To support AER better, developers need to understand how AER works.
+
+PCIe errors are classified into two types: correctable errors
+and uncorrectable errors. This classification is based on the impact
+of those errors, which may result in degraded performance or function
+failure.
+
+Correctable errors pose no impacts on the functionality of the
+interface. The PCIe protocol can recover without any software
+intervention or any loss of data. These errors are detected and
+corrected by hardware.
+
+Unlike correctable errors, uncorrectable
+errors impact functionality of the interface. Uncorrectable errors
+can cause a particular transaction or a particular PCIe link
+to be unreliable. Depending on those error conditions, uncorrectable
+errors are further classified into non-fatal errors and fatal errors.
+Non-fatal errors cause the particular transaction to be unreliable,
+but the PCIe link itself is fully functional. Fatal errors, on
+the other hand, cause the link to be unreliable.
+
+When PCIe error reporting is enabled, a device will automatically send an
+error message to the Root Port above it when it captures
+an error. The Root Port, upon receiving an error reporting message,
+internally processes and logs the error message in its AER
+Capability structure. Error information being logged includes storing
+the error reporting agent's Requester ID into the Error Source
+Identification Registers and setting the error bits of the Root Error
+Status Register accordingly. If AER error reporting is enabled in the Root
+Error Command Register, the Root Port generates an interrupt when an
+error is detected.
+
+Note that the errors as described above are related to the PCIe
+hierarchy and links. These errors do not include any device specific
+errors because device specific errors will still get sent directly to
+the device driver.
+
+Provide callbacks
+-----------------
+
+PCI error-recovery callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The PCIe AER Root driver uses error callbacks to coordinate
+with downstream device drivers associated with a hierarchy in question
+when performing error recovery actions.
+
+Data struct pci_driver has a pointer, err_handler, to point to
+pci_error_handlers who consists of a couple of callback function
+pointers. The AER driver follows the rules defined in
+pci-error-recovery.rst except PCIe-specific parts (see
+below). Please refer to pci-error-recovery.rst for detailed
+definitions of the callbacks.
+
+The sections below specify when to call the error callback functions.
+
+Correctable errors
+~~~~~~~~~~~~~~~~~~
+
+Correctable errors pose no impacts on the functionality of
+the interface. The PCIe protocol can recover without any
+software intervention or any loss of data. These errors do not
+require any recovery actions. The AER driver clears the device's
+correctable error status register accordingly and logs these errors.
+
+Uncorrectable (non-fatal and fatal) errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The AER driver performs a Secondary Bus Reset to recover from
+uncorrectable errors. The reset is applied at the port above
+the originating device: If the originating device is an Endpoint,
+only the Endpoint is reset. If on the other hand the originating
+device has subordinate devices, those are all affected by the
+reset as well.
+
+If the originating device is a Root Complex Integrated Endpoint,
+there's no port above where a Secondary Bus Reset could be applied.
+In this case, the AER driver instead applies a Function Level Reset.
+
+If an error message indicates a non-fatal error, performing a reset
+at upstream is not required. The AER driver calls error_detected(dev,
+pci_channel_io_normal) to all drivers associated within a hierarchy in
+question. For example::
+
+ Endpoint <==> Downstream Port B <==> Upstream Port A <==> Root Port
+
+If Upstream Port A captures an AER error, the hierarchy consists of
+Downstream Port B and Endpoint.
+
+A driver may return PCI_ERS_RESULT_CAN_RECOVER,
+PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
+whether it can recover without a reset, considers the device unrecoverable
+or needs a reset for recovery. If all affected drivers agree that they can
+recover without a reset, it is skipped. Should one driver request a reset,
+it overrides all other drivers.
+
+If an error message indicates a fatal error, kernel will broadcast
+error_detected(dev, pci_channel_io_frozen) to all drivers within
+a hierarchy in question. Then, performing a reset at upstream is
+necessary. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER
+to indicate that recovery without a reset is possible, the error
+handling goes to mmio_enabled, but afterwards a reset is still
+performed.
+
+In other words, for non-fatal errors, drivers may opt in to a reset.
+But for fatal errors, they cannot opt out of a reset, based on the
+assumption that the link is unreliable.
+
+Frequently Asked Questions
+--------------------------
+
+Q:
+ What happens if a PCIe device driver does not provide an
+ error recovery handler (pci_driver->err_handler is equal to NULL)?
+
+A:
+ The devices attached with the driver won't be recovered.
+ The kernel will print out informational messages to identify
+ unrecoverable devices.
+
+
+Software error injection
+========================
+
+Debugging PCIe AER error recovery code is quite difficult because it
+is hard to trigger real hardware errors. Software based error
+injection can be used to fake various kinds of PCIe errors.
+
+First you should enable PCIe AER software error injection in kernel
+configuration, that is, following item should be in your .config.
+
+CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
+
+After reboot with new kernel or insert the module, a device file named
+/dev/aer_inject should be created.
+
+Then, you need a user space tool named aer-inject, which can be gotten
+from:
+
+ https://github.com/intel/aer-inject.git
+
+More information about aer-inject can be found in the document in
+its source code.
diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.txt
deleted file mode 100644
index b4987c0bcb20..000000000000
--- a/Documentation/PCI/pcieaer-howto.txt
+++ /dev/null
@@ -1,270 +0,0 @@
- The PCI Express Advanced Error Reporting Driver Guide HOWTO
- T. Long Nguyen <tom.l.nguyen@intel.com>
- Yanmin Zhang <yanmin.zhang@intel.com>
- 07/29/2006
-
-
-1. Overview
-
-1.1 About this guide
-
-This guide describes the basics of the PCI Express Advanced Error
-Reporting (AER) driver and provides information on how to use it, as
-well as how to enable the drivers of endpoint devices to conform with
-PCI Express AER driver.
-
-1.2 Copyright (C) Intel Corporation 2006.
-
-1.3 What is the PCI Express AER Driver?
-
-PCI Express error signaling can occur on the PCI Express link itself
-or on behalf of transactions initiated on the link. PCI Express
-defines two error reporting paradigms: the baseline capability and
-the Advanced Error Reporting capability. The baseline capability is
-required of all PCI Express components providing a minimum defined
-set of error reporting requirements. Advanced Error Reporting
-capability is implemented with a PCI Express advanced error reporting
-extended capability structure providing more robust error reporting.
-
-The PCI Express AER driver provides the infrastructure to support PCI
-Express Advanced Error Reporting capability. The PCI Express AER
-driver provides three basic functions:
-
-- Gathers the comprehensive error information if errors occurred.
-- Reports error to the users.
-- Performs error recovery actions.
-
-AER driver only attaches root ports which support PCI-Express AER
-capability.
-
-
-2. User Guide
-
-2.1 Include the PCI Express AER Root Driver into the Linux Kernel
-
-The PCI Express AER Root driver is a Root Port service driver attached
-to the PCI Express Port Bus driver. If a user wants to use it, the driver
-has to be compiled. Option CONFIG_PCIEAER supports this capability. It
-depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and
-CONFIG_PCIEAER = y.
-
-2.2 Load PCI Express AER Root Driver
-There is a case where a system has AER support in BIOS. Enabling the AER
-Root driver and having AER support in BIOS may result unpredictable
-behavior. To avoid this conflict, a successful load of the AER Root driver
-requires ACPI _OSC support in the BIOS to allow the AER Root driver to
-request for native control of AER. See the PCI FW 3.0 Specification for
-details regarding OSC usage. Currently, lots of firmwares don't provide
-_OSC support while they use PCI Express. To support such firmwares,
-forceload, a parameter of type bool, could enable AER to continue to
-be initiated although firmwares have no _OSC support. To enable the
-walkaround, pls. add aerdriver.forceload=y to kernel boot parameter line
-when booting kernel. Note that forceload=n by default.
-
-nosourceid, another parameter of type bool, can be used when broken
-hardware (mostly chipsets) has root ports that cannot obtain the reporting
-source ID. nosourceid=n by default.
-
-2.3 AER error output
-When a PCI-E AER error is captured, an error message will be outputted to
-console. If it's a correctable error, it is outputted as a warning.
-Otherwise, it is printed as an error. So users could choose different
-log level to filter out correctable error messages.
-
-Below shows an example:
-0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID)
-0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000
-0000:50:00.0: [20] Unsupported Request (First)
-0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100
-
-In the example, 'Requester ID' means the ID of the device who sends
-the error message to root port. Pls. refer to pci express specs for
-other fields.
-
-
-3. Developer Guide
-
-To enable AER aware support requires a software driver to configure
-the AER capability structure within its device and to provide callbacks.
-
-To support AER better, developers need understand how AER does work
-firstly.
-
-PCI Express errors are classified into two types: correctable errors
-and uncorrectable errors. This classification is based on the impacts
-of those errors, which may result in degraded performance or function
-failure.
-
-Correctable errors pose no impacts on the functionality of the
-interface. The PCI Express protocol can recover without any software
-intervention or any loss of data. These errors are detected and
-corrected by hardware. Unlike correctable errors, uncorrectable
-errors impact functionality of the interface. Uncorrectable errors
-can cause a particular transaction or a particular PCI Express link
-to be unreliable. Depending on those error conditions, uncorrectable
-errors are further classified into non-fatal errors and fatal errors.
-Non-fatal errors cause the particular transaction to be unreliable,
-but the PCI Express link itself is fully functional. Fatal errors, on
-the other hand, cause the link to be unreliable.
-
-When AER is enabled, a PCI Express device will automatically send an
-error message to the PCIe root port above it when the device captures
-an error. The Root Port, upon receiving an error reporting message,
-internally processes and logs the error message in its PCI Express
-capability structure. Error information being logged includes storing
-the error reporting agent's requestor ID into the Error Source
-Identification Registers and setting the error bits of the Root Error
-Status Register accordingly. If AER error reporting is enabled in Root
-Error Command Register, the Root Port generates an interrupt if an
-error is detected.
-
-Note that the errors as described above are related to the PCI Express
-hierarchy and links. These errors do not include any device specific
-errors because device specific errors will still get sent directly to
-the device driver.
-
-3.1 Configure the AER capability structure
-
-AER aware drivers of PCI Express component need change the device
-control registers to enable AER. They also could change AER registers,
-including mask and severity registers. Helper function
-pci_enable_pcie_error_reporting could be used to enable AER. See
-section 3.3.
-
-3.2. Provide callbacks
-
-3.2.1 callback reset_link to reset pci express link
-
-This callback is used to reset the pci express physical link when a
-fatal error happens. The root port aer service driver provides a
-default reset_link function, but different upstream ports might
-have different specifications to reset pci express link, so all
-upstream ports should provide their own reset_link functions.
-
-In struct pcie_port_service_driver, a new pointer, reset_link, is
-added.
-
-pci_ers_result_t (*reset_link) (struct pci_dev *dev);
-
-Section 3.2.2.2 provides more detailed info on when to call
-reset_link.
-
-3.2.2 PCI error-recovery callbacks
-
-The PCI Express AER Root driver uses error callbacks to coordinate
-with downstream device drivers associated with a hierarchy in question
-when performing error recovery actions.
-
-Data struct pci_driver has a pointer, err_handler, to point to
-pci_error_handlers who consists of a couple of callback function
-pointers. AER driver follows the rules defined in
-pci-error-recovery.txt except pci express specific parts (e.g.
-reset_link). Pls. refer to pci-error-recovery.txt for detailed
-definitions of the callbacks.
-
-Below sections specify when to call the error callback functions.
-
-3.2.2.1 Correctable errors
-
-Correctable errors pose no impacts on the functionality of
-the interface. The PCI Express protocol can recover without any
-software intervention or any loss of data. These errors do not
-require any recovery actions. The AER driver clears the device's
-correctable error status register accordingly and logs these errors.
-
-3.2.2.2 Non-correctable (non-fatal and fatal) errors
-
-If an error message indicates a non-fatal error, performing link reset
-at upstream is not required. The AER driver calls error_detected(dev,
-pci_channel_io_normal) to all drivers associated within a hierarchy in
-question. for example,
-EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort.
-If Upstream port A captures an AER error, the hierarchy consists of
-Downstream port B and EndPoint.
-
-A driver may return PCI_ERS_RESULT_CAN_RECOVER,
-PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on
-whether it can recover or the AER driver calls mmio_enabled as next.
-
-If an error message indicates a fatal error, kernel will broadcast
-error_detected(dev, pci_channel_io_frozen) to all drivers within
-a hierarchy in question. Then, performing link reset at upstream is
-necessary. As different kinds of devices might use different approaches
-to reset link, AER port service driver is required to provide the
-function to reset link. Firstly, kernel looks for if the upstream
-component has an aer driver. If it has, kernel uses the reset_link
-callback of the aer driver. If the upstream component has no aer driver
-and the port is downstream port, we will perform a hot reset as the
-default by setting the Secondary Bus Reset bit of the Bridge Control
-register associated with the downstream port. As for upstream ports,
-they should provide their own aer service drivers with reset_link
-function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and
-reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes
-to mmio_enabled.
-
-3.3 helper functions
-
-3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev);
-pci_enable_pcie_error_reporting enables the device to send error
-messages to root port when an error is detected. Note that devices
-don't enable the error reporting by default, so device drivers need
-call this function to enable it.
-
-3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev);
-pci_disable_pcie_error_reporting disables the device to send error
-messages to root port when an error is detected.
-
-3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);
-pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable
-error status register.
-
-3.4 Frequent Asked Questions
-
-Q: What happens if a PCI Express device driver does not provide an
-error recovery handler (pci_driver->err_handler is equal to NULL)?
-
-A: The devices attached with the driver won't be recovered. If the
-error is fatal, kernel will print out warning messages. Please refer
-to section 3 for more information.
-
-Q: What happens if an upstream port service driver does not provide
-callback reset_link?
-
-A: Fatal error recovery will fail if the errors are reported by the
-upstream ports who are attached by the service driver.
-
-Q: How does this infrastructure deal with driver that is not PCI
-Express aware?
-
-A: This infrastructure calls the error callback functions of the
-driver when an error happens. But if the driver is not aware of
-PCI Express, the device might not report its own errors to root
-port.
-
-Q: What modifications will that driver need to make it compatible
-with the PCI Express AER Root driver?
-
-A: It could call the helper functions to enable AER in devices and
-cleanup uncorrectable status register. Pls. refer to section 3.3.
-
-
-4. Software error injection
-
-Debugging PCIe AER error recovery code is quite difficult because it
-is hard to trigger real hardware errors. Software based error
-injection can be used to fake various kinds of PCIe errors.
-
-First you should enable PCIe AER software error injection in kernel
-configuration, that is, following item should be in your .config.
-
-CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m
-
-After reboot with new kernel or insert the module, a device file named
-/dev/aer_inject should be created.
-
-Then, you need a user space tool named aer-inject, which can be gotten
-from:
- http://www.kernel.org/pub/linux/utils/pci/aer-inject/
-
-More information about aer-inject can be found in the document comes
-with its source code.
diff --git a/Documentation/PCI/pciebus-howto.rst b/Documentation/PCI/pciebus-howto.rst
new file mode 100644
index 000000000000..375d9ce171f6
--- /dev/null
+++ b/Documentation/PCI/pciebus-howto.rst
@@ -0,0 +1,228 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===========================================
+The PCI Express Port Bus Driver Guide HOWTO
+===========================================
+
+:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004
+:Copyright: |copy| 2004 Intel Corporation
+
+About this guide
+================
+
+This guide describes the basics of the PCI Express Port Bus driver
+and provides information on how to enable the service drivers to
+register/unregister with the PCI Express Port Bus Driver.
+
+
+What is the PCI Express Port Bus Driver
+=======================================
+
+A PCI Express Port is a logical PCI-PCI Bridge structure. There
+are two types of PCI Express Port: the Root Port and the Switch
+Port. The Root Port originates a PCI Express link from a PCI Express
+Root Complex and the Switch Port connects PCI Express links to
+internal logical PCI buses. The Switch Port, which has its secondary
+bus representing the switch's internal routing logic, is called the
+switch's Upstream Port. The switch's Downstream Port is bridging from
+switch's internal routing bus to a bus representing the downstream
+PCI Express link from the PCI Express Switch.
+
+A PCI Express Port can provide up to four distinct functions,
+referred to in this document as services, depending on its port type.
+PCI Express Port's services include native hotplug support (HP),
+power management event support (PME), advanced error reporting
+support (AER), and virtual channel support (VC). These services may
+be handled by a single complex driver or be individually distributed
+and handled by corresponding service drivers.
+
+Why use the PCI Express Port Bus Driver?
+========================================
+
+In existing Linux kernels, the Linux Device Driver Model allows a
+physical device to be handled by only a single driver. The PCI
+Express Port is a PCI-PCI Bridge device with multiple distinct
+services. To maintain a clean and simple solution each service
+may have its own software service driver. In this case several
+service drivers will compete for a single PCI-PCI Bridge device.
+For example, if the PCI Express Root Port native hotplug service
+driver is loaded first, it claims a PCI-PCI Bridge Root Port. The
+kernel therefore does not load other service drivers for that Root
+Port. In other words, it is impossible to have multiple service
+drivers load and run on a PCI-PCI Bridge device simultaneously
+using the current driver model.
+
+To enable multiple service drivers running simultaneously requires
+having a PCI Express Port Bus driver, which manages all populated
+PCI Express Ports and distributes all provided service requests
+to the corresponding service drivers as required. Some key
+advantages of using the PCI Express Port Bus driver are listed below:
+
+ - Allow multiple service drivers to run simultaneously on
+ a PCI-PCI Bridge Port device.
+
+ - Allow service drivers implemented in an independent
+ staged approach.
+
+ - Allow one service driver to run on multiple PCI-PCI Bridge
+ Port devices.
+
+ - Manage and distribute resources of a PCI-PCI Bridge Port
+ device to requested service drivers.
+
+Configuring the PCI Express Port Bus Driver vs. Service Drivers
+===============================================================
+
+Including the PCI Express Port Bus Driver Support into the Kernel
+-----------------------------------------------------------------
+
+Including the PCI Express Port Bus driver depends on whether the PCI
+Express support is included in the kernel config. The kernel will
+automatically include the PCI Express Port Bus driver as a kernel
+driver when the PCI Express support is enabled in the kernel.
+
+Enabling Service Driver Support
+-------------------------------
+
+PCI device drivers are implemented based on Linux Device Driver Model.
+All service drivers are PCI device drivers. As discussed above, it is
+impossible to load any service driver once the kernel has loaded the
+PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver
+Model requires some minimal changes on existing service drivers that
+imposes no impact on the functionality of existing service drivers.
+
+A service driver is required to use the two APIs shown below to
+register its service with the PCI Express Port Bus driver (see
+section 5.2.1 & 5.2.2). It is important that a service driver
+initializes the pcie_port_service_driver data structure, included in
+header file /include/linux/pcieport_if.h, before calling these APIs.
+Failure to do so will result an identity mismatch, which prevents
+the PCI Express Port Bus driver from loading a service driver.
+
+pcie_port_service_register
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ int pcie_port_service_register(struct pcie_port_service_driver *new)
+
+This API replaces the Linux Driver Model's pci_register_driver API. A
+service driver should always calls pcie_port_service_register at
+module init. Note that after service driver being loaded, calls
+such as pci_enable_device(dev) and pci_set_master(dev) are no longer
+necessary since these calls are executed by the PCI Port Bus driver.
+
+pcie_port_service_unregister
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
+
+ void pcie_port_service_unregister(struct pcie_port_service_driver *new)
+
+pcie_port_service_unregister replaces the Linux Driver Model's
+pci_unregister_driver. It's always called by service driver when a
+module exits.
+
+Sample Code
+~~~~~~~~~~~
+
+Below is sample service driver code to initialize the port service
+driver data structure.
+::
+
+ static struct pcie_port_service_id service_id[] = { {
+ .vendor = PCI_ANY_ID,
+ .device = PCI_ANY_ID,
+ .port_type = PCIE_RC_PORT,
+ .service_type = PCIE_PORT_SERVICE_AER,
+ }, { /* end: all zeroes */ }
+ };
+
+ static struct pcie_port_service_driver root_aerdrv = {
+ .name = (char *)device_name,
+ .id_table = service_id,
+
+ .probe = aerdrv_load,
+ .remove = aerdrv_unload,
+
+ .suspend = aerdrv_suspend,
+ .resume = aerdrv_resume,
+ };
+
+Below is a sample code for registering/unregistering a service
+driver.
+::
+
+ static int __init aerdrv_service_init(void)
+ {
+ int retval = 0;
+
+ retval = pcie_port_service_register(&root_aerdrv);
+ if (!retval) {
+ /*
+ * FIX ME
+ */
+ }
+ return retval;
+ }
+
+ static void __exit aerdrv_service_exit(void)
+ {
+ pcie_port_service_unregister(&root_aerdrv);
+ }
+
+ module_init(aerdrv_service_init);
+ module_exit(aerdrv_service_exit);
+
+Possible Resource Conflicts
+===========================
+
+Since all service drivers of a PCI-PCI Bridge Port device are
+allowed to run simultaneously, below lists a few of possible resource
+conflicts with proposed solutions.
+
+MSI and MSI-X Vector Resource
+-----------------------------
+
+Once MSI or MSI-X interrupts are enabled on a device, it stays in this
+mode until they are disabled again. Since service drivers of the same
+PCI-PCI Bridge port share the same physical device, if an individual
+service driver enables or disables MSI/MSI-X mode it may result
+unpredictable behavior.
+
+To avoid this situation all service drivers are not permitted to
+switch interrupt mode on its device. The PCI Express Port Bus driver
+is responsible for determining the interrupt mode and this should be
+transparent to service drivers. Service drivers need to know only
+the vector IRQ assigned to the field irq of struct pcie_device, which
+is passed in when the PCI Express Port Bus driver probes each service
+driver. Service drivers should use (struct pcie_device*)dev->irq to
+call request_irq/free_irq. In addition, the interrupt mode is stored
+in the field interrupt_mode of struct pcie_device.
+
+PCI Memory/IO Mapped Regions
+----------------------------
+
+Service drivers for PCI Express Power Management (PME), Advanced
+Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access
+PCI configuration space on the PCI Express port. In all cases the
+registers accessed are independent of each other. This patch assumes
+that all service drivers will be well behaved and not overwrite
+other service driver's configuration settings.
+
+PCI Config Registers
+--------------------
+
+Each service driver runs its PCI config operations on its own
+capability structure except the PCI Express capability structure,
+that is shared between many drivers including the service drivers.
+RMW Capability accessors (pcie_capability_clear_and_set_word(),
+pcie_capability_set_word(), and pcie_capability_clear_word()) protect
+a selected set of PCI Express Capability Registers:
+
+* Link Control Register
+* Root Control Register
+* Link Control 2 Register
+
+Any change to those registers should be performed using RMW accessors to
+avoid problems due to concurrent updates. For the up-to-date list of
+protected registers, see pcie_capability_clear_and_set_word().
diff --git a/Documentation/PCI/sysfs-pci.rst b/Documentation/PCI/sysfs-pci.rst
new file mode 100644
index 000000000000..f495185aa88a
--- /dev/null
+++ b/Documentation/PCI/sysfs-pci.rst
@@ -0,0 +1,138 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================
+Accessing PCI device resources through sysfs
+============================================
+
+sysfs, usually mounted at /sys, provides access to PCI resources on platforms
+that support it. For example, a given bus might look like this::
+
+ /sys/devices/pci0000:17
+ |-- 0000:17:00.0
+ | |-- class
+ | |-- config
+ | |-- device
+ | |-- enable
+ | |-- irq
+ | |-- local_cpus
+ | |-- remove
+ | |-- resource
+ | |-- resource0
+ | |-- resource1
+ | |-- resource2
+ | |-- revision
+ | |-- rom
+ | |-- subsystem_device
+ | |-- subsystem_vendor
+ | `-- vendor
+ `-- ...
+
+The topmost element describes the PCI domain and bus number. In this case,
+the domain number is 0000 and the bus number is 17 (both values are in hex).
+This bus contains a single function device in slot 0. The domain and bus
+numbers are reproduced for convenience. Under the device directory are several
+files, each with their own function.
+
+ =================== =====================================================
+ file function
+ =================== =====================================================
+ class PCI class (ascii, ro)
+ config PCI config space (binary, rw)
+ device PCI device (ascii, ro)
+ enable Whether the device is enabled (ascii, rw)
+ irq IRQ number (ascii, ro)
+ local_cpus nearby CPU mask (cpumask, ro)
+ remove remove device from kernel's list (ascii, wo)
+ resource PCI resource host addresses (ascii, ro)
+ resource0..N PCI resource N, if present (binary, mmap, rw\ [1]_)
+ resource0_wc..N_wc PCI WC map resource N, if prefetchable (binary, mmap)
+ revision PCI revision (ascii, ro)
+ rom PCI ROM resource, if present (binary, ro)
+ subsystem_device PCI subsystem device (ascii, ro)
+ subsystem_vendor PCI subsystem vendor (ascii, ro)
+ vendor PCI vendor (ascii, ro)
+ =================== =====================================================
+
+::
+
+ ro - read only file
+ rw - file is readable and writable
+ wo - write only file
+ mmap - file is mmapable
+ ascii - file contains ascii text
+ binary - file contains binary data
+ cpumask - file contains a cpumask type
+
+.. [1] rw for IORESOURCE_IO (I/O port) regions only
+
+The read only files are informational, writes to them will be ignored, with
+the exception of the 'rom' file. Writable files can be used to perform
+actions on the device (e.g. changing config space, detaching a device).
+mmapable files are available via an mmap of the file at offset 0 and can be
+used to do actual device programming from userspace. Note that some platforms
+don't support mmapping of certain resources, so be sure to check the return
+value from any attempted mmap. The most notable of these are I/O port
+resources, which also provide read/write access.
+
+The 'enable' file provides a counter that indicates how many times the device
+has been enabled. If the 'enable' file currently returns '4', and a '1' is
+echoed into it, it will then return '5'. Echoing a '0' into it will decrease
+the count. Even when it returns to 0, though, some of the initialisation
+may not be reversed.
+
+The 'rom' file is special in that it provides read-only access to the device's
+ROM file, if available. It's disabled by default, however, so applications
+should write the string "1" to the file to enable it before attempting a read
+call, and disable it following the access by writing "0" to the file. Note
+that the device must be enabled for a rom read to return data successfully.
+In the event a driver is not bound to the device, it can be enabled using the
+'enable' file, documented above.
+
+The 'remove' file is used to remove the PCI device, by writing a non-zero
+integer to the file. This does not involve any kind of hot-plug functionality,
+e.g. powering off the device. The device is removed from the kernel's list of
+PCI devices, the sysfs directory for it is removed, and the device will be
+removed from any drivers attached to it. Removal of PCI root buses is
+disallowed.
+
+Accessing legacy resources through sysfs
+----------------------------------------
+
+Legacy I/O port and ISA memory resources are also provided in sysfs if the
+underlying platform supports them. They're located in the PCI class hierarchy,
+e.g.::
+
+ /sys/class/pci_bus/0000:17/
+ |-- bridge -> ../../../devices/pci0000:17
+ |-- cpuaffinity
+ |-- legacy_io
+ `-- legacy_mem
+
+The legacy_io file is a read/write file that can be used by applications to
+do legacy port I/O. The application should open the file, seek to the desired
+port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem
+file should be mmapped with an offset corresponding to the memory offset
+desired, e.g. 0xa0000 for the VGA frame buffer. The application can then
+simply dereference the returned pointer (after checking for errors of course)
+to access legacy memory space.
+
+Supporting PCI access on new platforms
+--------------------------------------
+
+In order to support PCI resource mapping as described above, Linux platform
+code should ideally define ARCH_GENERIC_PCI_MMAP_RESOURCE and use the generic
+implementation of that functionality. To support the historical interface of
+mmap() through files in /proc/bus/pci, platforms may also set HAVE_PCI_MMAP.
+
+Alternatively, platforms which set HAVE_PCI_MMAP may provide their own
+implementation of pci_mmap_resource_range() instead of defining
+ARCH_GENERIC_PCI_MMAP_RESOURCE.
+
+Platforms which support write-combining maps of PCI resources must define
+arch_can_pci_mmap_wc() which shall evaluate to non-zero at runtime when
+write-combining is permitted. Platforms which support maps of I/O resources
+define arch_can_pci_mmap_io() similarly.
+
+Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms
+wishing to support legacy functionality should define it and provide
+pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions.
diff --git a/Documentation/PCI/tph.rst b/Documentation/PCI/tph.rst
new file mode 100644
index 000000000000..e8993be64fd6
--- /dev/null
+++ b/Documentation/PCI/tph.rst
@@ -0,0 +1,132 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+
+===========
+TPH Support
+===========
+
+:Copyright: 2024 Advanced Micro Devices, Inc.
+:Authors: - Eric van Tassell <eric.vantassell@amd.com>
+ - Wei Huang <wei.huang2@amd.com>
+
+
+Overview
+========
+
+TPH (TLP Processing Hints) is a PCIe feature that allows endpoint devices
+to provide optimization hints for requests that target memory space.
+These hints, in a format called Steering Tags (STs), are embedded in the
+requester's TLP headers, enabling the system hardware, such as the Root
+Complex, to better manage platform resources for these requests.
+
+For example, on platforms with TPH-based direct data cache injection
+support, an endpoint device can include appropriate STs in its DMA
+traffic to specify which cache the data should be written to. This allows
+the CPU core to have a higher probability of getting data from cache,
+potentially improving performance and reducing latency in data
+processing.
+
+
+How to Use TPH
+==============
+
+TPH is presented as an optional extended capability in PCIe. The Linux
+kernel handles TPH discovery during boot, but it is up to the device
+driver to request TPH enablement if it is to be utilized. Once enabled,
+the driver uses the provided API to obtain the Steering Tag for the
+target memory and to program the ST into the device's ST table.
+
+Enable TPH support in Linux
+---------------------------
+
+To support TPH, the kernel must be built with the CONFIG_PCIE_TPH option
+enabled.
+
+Manage TPH
+----------
+
+To enable TPH for a device, use the following function::
+
+ int pcie_enable_tph(struct pci_dev *pdev, int mode);
+
+This function enables TPH support for device with a specific ST mode.
+Current supported modes include:
+
+ * PCI_TPH_ST_NS_MODE - NO ST Mode
+ * PCI_TPH_ST_IV_MODE - Interrupt Vector Mode
+ * PCI_TPH_ST_DS_MODE - Device Specific Mode
+
+`pcie_enable_tph()` checks whether the requested mode is actually
+supported by the device before enabling. The device driver can figure out
+which TPH mode is supported and can be properly enabled based on the
+return value of `pcie_enable_tph()`.
+
+To disable TPH, use the following function::
+
+ void pcie_disable_tph(struct pci_dev *pdev);
+
+Manage ST
+---------
+
+Steering Tags are platform specific. PCIe spec does not specify where STs
+are from. Instead PCI Firmware Specification defines an ACPI _DSM method
+(see the `Revised _DSM for Cache Locality TPH Features ECN
+<https://members.pcisig.com/wg/PCI-SIG/document/15470>`_) for retrieving
+STs for a target memory of various properties. This method is what is
+supported in this implementation.
+
+To retrieve a Steering Tag for a target memory associated with a specific
+CPU, use the following function::
+
+ int pcie_tph_get_cpu_st(struct pci_dev *pdev, enum tph_mem_type type,
+ unsigned int cpu_uid, u16 *tag);
+
+The `type` argument is used to specify the memory type, either volatile
+or persistent, of the target memory. The `cpu_uid` argument specifies the
+CPU where the memory is associated to.
+
+After the ST value is retrieved, the device driver can use the following
+function to write the ST into the device::
+
+ int pcie_tph_set_st_entry(struct pci_dev *pdev, unsigned int index,
+ u16 tag);
+
+The `index` argument is the ST table entry index the ST tag will be
+written into. `pcie_tph_set_st_entry()` will figure out the proper
+location of ST table, either in the MSI-X table or in the TPH Extended
+Capability space, and write the Steering Tag into the ST entry pointed by
+the `index` argument.
+
+It is completely up to the driver to decide how to use these TPH
+functions. For example a network device driver can use the TPH APIs above
+to update the Steering Tag when interrupt affinity of a RX/TX queue has
+been changed. Here is a sample code for IRQ affinity notifier:
+
+.. code-block:: c
+
+ static void irq_affinity_notified(struct irq_affinity_notify *notify,
+ const cpumask_t *mask)
+ {
+ struct drv_irq *irq;
+ unsigned int cpu_id;
+ u16 tag;
+
+ irq = container_of(notify, struct drv_irq, affinity_notify);
+ cpumask_copy(irq->cpu_mask, mask);
+
+ /* Pick a right CPU as the target - here is just an example */
+ cpu_id = cpumask_first(irq->cpu_mask);
+
+ if (pcie_tph_get_cpu_st(irq->pdev, TPH_MEM_TYPE_VM, cpu_id,
+ &tag))
+ return;
+
+ if (pcie_tph_set_st_entry(irq->pdev, irq->msix_nr, tag))
+ return;
+ }
+
+Disable TPH system-wide
+-----------------------
+
+There is a kernel command line option available to control TPH feature:
+ * "notph": TPH will be disabled for all endpoint devices.
diff --git a/Documentation/RCU/00-INDEX b/Documentation/RCU/00-INDEX
deleted file mode 100644
index f773a264ae02..000000000000
--- a/Documentation/RCU/00-INDEX
+++ /dev/null
@@ -1,36 +0,0 @@
-00-INDEX
- - This file
-arrayRCU.txt
- - Using RCU to Protect Read-Mostly Arrays
-checklist.txt
- - Review Checklist for RCU Patches
-listRCU.txt
- - Using RCU to Protect Read-Mostly Linked Lists
-lockdep.txt
- - RCU and lockdep checking
-lockdep-splat.txt
- - RCU Lockdep splats explained.
-NMI-RCU.txt
- - Using RCU to Protect Dynamic NMI Handlers
-rcu_dereference.txt
- - Proper care and feeding of return values from rcu_dereference()
-rcubarrier.txt
- - RCU and Unloadable Modules
-rculist_nulls.txt
- - RCU list primitives for use with SLAB_DESTROY_BY_RCU
-rcuref.txt
- - Reference-count design for elements of lists/arrays protected by RCU
-rcu.txt
- - RCU Concepts
-RTFP.txt
- - List of RCU papers (bibliography) going back to 1980.
-stallwarn.txt
- - RCU CPU stall warnings (module parameter rcu_cpu_stall_suppress)
-torture.txt
- - RCU Torture Test Operation (CONFIG_RCU_TORTURE_TEST)
-trace.txt
- - CONFIG_RCU_TRACE debugfs files and formats
-UP.txt
- - RCU on Uniprocessor Systems
-whatisRCU.txt
- - What is RCU?
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg
new file mode 100644
index 000000000000..727e270b11e4
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg
@@ -0,0 +1,474 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:28:20 2015 -->
+
+<!-- Magnification: 3.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="9.1in"
+ height="8.9in"
+ viewBox="-66 -66 10932 10707"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="BigTreeClassicRCU.fig">
+ <metadata
+ id="metadata106">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs104">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Mend"
+ style="overflow:visible;">
+ <path
+ id="path3864"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;"
+ transform="scale(0.4) rotate(180) translate(10,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="973"
+ inkscape:window-height="1137"
+ id="namedview102"
+ showgrid="false"
+ inkscape:zoom="0.9743589"
+ inkscape:cx="409.50003"
+ inkscape:cy="400.49997"
+ inkscape:window-x="915"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4" />
+ <g
+ style="stroke-width:.025in; fill:none"
+ id="g4">
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="0"
+ width="10800"
+ height="5625"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; "
+ id="rect6" />
+ <!-- Line: box -->
+ <rect
+ x="1125"
+ y="3600"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect8" />
+ <!-- Line: box -->
+ <rect
+ x="3825"
+ y="900"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect10" />
+ <!-- Line: box -->
+ <rect
+ x="6525"
+ y="3600"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect12" />
+ <!-- Line -->
+ <polyline
+ points="3375,6525 3375,5046 "
+ style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline14" />
+ <!-- Arrowhead on XXXpoint 3375 6525 - 3375 4860-->
+ <!-- Circle -->
+ <circle
+ cx="7425"
+ cy="6075"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle18" />
+ <!-- Circle -->
+ <circle
+ cx="7875"
+ cy="6075"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle20" />
+ <!-- Circle -->
+ <circle
+ cx="8325"
+ cy="6075"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle22" />
+ <!-- Circle -->
+ <circle
+ cx="2025"
+ cy="6075"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle24" />
+ <!-- Circle -->
+ <circle
+ cx="2475"
+ cy="6075"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle26" />
+ <!-- Circle -->
+ <circle
+ cx="2925"
+ cy="6075"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle28" />
+ <!-- Circle -->
+ <circle
+ cx="4725"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle30" />
+ <!-- Circle -->
+ <circle
+ cx="5175"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle32" />
+ <!-- Circle -->
+ <circle
+ cx="5625"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle34" />
+ <!-- Line: box -->
+ <rect
+ x="2025"
+ y="6525"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect36" />
+ <!-- Line -->
+ <polyline
+ points="2475,3600 3975,2310 "
+ style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline38" />
+ <!-- Arrowhead on XXXpoint 2475 3600 - 4116 2190-->
+ <!-- Line -->
+ <polyline
+ points="7875,3600 6372,2310 "
+ style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline42" />
+ <!-- Arrowhead on XXXpoint 7875 3600 - 6231 2190-->
+ <!-- Line -->
+ <polyline
+ points="6975,8775 6975,5046 "
+ style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline46" />
+ <!-- Arrowhead on XXXpoint 6975 8775 - 6975 4860-->
+ <!-- Line -->
+ <polyline
+ points="1575,8775 1575,5046 "
+ style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline50" />
+ <!-- Arrowhead on XXXpoint 1575 8775 - 1575 4860-->
+ <!-- Line -->
+ <polyline
+ points="8775,6525 8775,5046 "
+ style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline54" />
+ <!-- Arrowhead on XXXpoint 8775 6525 - 8775 4860-->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1575"
+ y="9225"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text58">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1575"
+ y="9675"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text60">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1575"
+ y="10350"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text62">CPU 0</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3375"
+ y="6975"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text64">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3375"
+ y="7425"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text66">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3375"
+ y="8100"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text68">CPU 15</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6975"
+ y="9225"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text70">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6975"
+ y="9675"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text72">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6975"
+ y="10350"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text74">CPU 1007</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="8730"
+ y="6930"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text76">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="8730"
+ y="7380"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text78">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="8730"
+ y="8055"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text80">CPU 1023</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="450"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="start"
+ id="text82">struct rcu_state</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2475"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text84">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2475"
+ y="4500"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text86">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7875"
+ y="4500"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text88">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7875"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text90">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5175"
+ y="1350"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text92">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5175"
+ y="1800"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text94">rcu_node</text>
+ <!-- Line: box -->
+ <rect
+ x="225"
+ y="8775"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect96" />
+ <!-- Line: box -->
+ <rect
+ x="5625"
+ y="8775"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect98" />
+ <!-- Line: box -->
+ <rect
+ x="7380"
+ y="6480"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect100" />
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg
new file mode 100644
index 000000000000..3a1a4f85dc3a
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg
@@ -0,0 +1,662 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:29:48 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="7.4000001in"
+ height="7.9000001in"
+ viewBox="-44 -44 8938 9526.283"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.92.2pre0 (973e216, 2017-07-25)"
+ sodipodi:docname="BigTreePreemptRCUBHdyntickCB.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker1177"
+ style="overflow:visible"
+ inkscape:isstock="true">
+ <path
+ id="path897"
+ d="M 0,0 5,-5 -12.5,0 5,5 Z"
+ style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Lend"
+ style="overflow:visible"
+ inkscape:isstock="true">
+ <path
+ id="path891"
+ d="M 0,0 5,-5 -12.5,0 5,5 Z"
+ style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1"
+ transform="matrix(-0.8,0,0,-0.8,-10,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 Z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1920"
+ inkscape:window-height="1019"
+ id="namedview208"
+ showgrid="false"
+ inkscape:zoom="1.0195195"
+ inkscape:cx="166.25478"
+ inkscape:cy="362.18693"
+ inkscape:window-x="0"
+ inkscape:window-y="0"
+ inkscape:window-maximized="1"
+ inkscape:current-layer="g4" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(0,-2415.6743)">
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8550 - 5710 6240-->
+ <polyline
+ points="5714 6518 5704 6272 5598 6494 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline20"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9750 - 4512 7590-->
+ <polyline
+ points="4514 7868 4506 7622 4396 7844 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline24"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1040 9750 - 1502 7590-->
+ <polyline
+ points="1504 7868 1496 7622 1386 7844 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline28"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2240 8550 - 2702 6390-->
+ <polyline
+ points="2704 6668 2696 6422 2586 6644 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline32"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9600 - 5744 5948-->
+ <polyline
+ points="5682 6220 5730 5978 5574 6170 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline36"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1086 9600 - 2780 5948-->
+ <polyline
+ points="2718 6220 2766 5978 2610 6170 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline40"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Line: box -->
+ <rect
+ x="12.340758"
+ y="2442.5947"
+ width="6300"
+ height="7045.3135"
+ rx="0"
+ style="fill:#ffffff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect42" />
+ <!-- Line: box -->
+ <rect
+ x="312.34076"
+ y="3017.7224"
+ width="5700"
+ height="3594.5476"
+ rx="0"
+ style="fill:#ffff00;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect44" />
+ <!-- Line -->
+ <polyline
+ points="1350,3900 2350,3040 "
+ style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline46"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Arrowhead on XXXpoint 1350 3900 - 2444 2960-->
+ <!-- Line -->
+ <polyline
+ points="4950,3900 3948,3040 "
+ style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline50"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Arrowhead on XXXpoint 4950 3900 - 3854 2960-->
+ <!-- Line -->
+ <polyline
+ points="4050,7050 4050,4864 "
+ style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline54"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Arrowhead on XXXpoint 4050 7050 - 4050 4740-->
+ <!-- Line -->
+ <polyline
+ points="1050,7050 1050,4864 "
+ style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline58"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Arrowhead on XXXpoint 1050 7050 - 1050 4740-->
+ <!-- Line -->
+ <polyline
+ points="2250,5850 2250,4864 "
+ style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline62"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Arrowhead on XXXpoint 2250 5850 - 2250 4740-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 8550 - 2250 6690-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 9750 - 1050 7890-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9750 - 4050 7890-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8550 - 5250 6690-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 6000 6300 - 8146 7986-->
+ <!-- Circle -->
+ <ellipse
+ cx="2862.3408"
+ cy="5749.5786"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle86"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="3162.3408"
+ cy="5749.5786"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle88"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="3462.3408"
+ cy="5749.5786"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle90"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="1362.3407"
+ cy="6899.834"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle92"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="1662.3407"
+ cy="6899.834"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle94"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="1962.3407"
+ cy="6899.834"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle96"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="4362.3408"
+ cy="6899.834"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle98"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="4662.3408"
+ cy="6899.834"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle100"
+ rx="76"
+ ry="72.849495" />
+ <!-- Circle -->
+ <ellipse
+ cx="4962.3408"
+ cy="6899.834"
+ style="fill:#000000;stroke:#000000;stroke-width:13.70675087"
+ id="circle102"
+ rx="76"
+ ry="72.849495" />
+ <!-- Line: box -->
+ <rect
+ x="6745.3027"
+ y="8146.0654"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect104" />
+ <!-- Line: box -->
+ <rect
+ x="6745.3027"
+ y="9583.8857"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect106" />
+ <!-- Line -->
+ <polyline
+ points="8100,8850 8100,9384 "
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend)"
+ id="polyline108"
+ transform="matrix(1,0,0,0.95854605,-604.69715,525.62477)" />
+ <!-- Arrowhead on XXXpoint 8100 8850 - 8100 9510-->
+ <!-- Line: box -->
+ <rect
+ x="6745.3027"
+ y="11021.704"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112" />
+ <!-- Line -->
+ <polyline
+ points="8100,10350 8100,10884 "
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend)"
+ id="polyline114"
+ transform="matrix(1,0,0,0.95854605,-604.69715,525.62477)" />
+ <!-- Arrowhead on XXXpoint 8100 10350 - 8100 11010-->
+ <!-- Line: box -->
+ <rect
+ x="762.34076"
+ y="5318.2324"
+ width="1800"
+ height="862.69141"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect118" />
+ <!-- Line: box -->
+ <rect
+ x="312.34076"
+ y="8337.6533"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect120" />
+ <!-- Line: box -->
+ <rect
+ x="3762.3408"
+ y="5318.2324"
+ width="1800"
+ height="862.69141"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect122" />
+ <!-- Line: box -->
+ <rect
+ x="4512.3408"
+ y="7187.3975"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect124" />
+ <!-- Line: box -->
+ <rect
+ x="3312.3408"
+ y="8337.6533"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect126" />
+ <!-- Line: box -->
+ <rect
+ x="2262.3408"
+ y="3592.8503"
+ width="1800"
+ height="862.69141"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect128" />
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <rect
+ x="1512.3407"
+ y="7187.3975"
+ width="1500"
+ height="862.69141"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect138" />
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7338.3037"
+ y="8614.0625"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text140"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7338.3037"
+ y="8907.7783"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text142"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_head</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7338.3037"
+ y="10082.644"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text144"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7338.3037"
+ y="10376.36"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text146"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_head</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7338.3037"
+ y="11551.224"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text148"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7338.3037"
+ y="11844.94"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text150"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_head</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5886.4043"
+ y="2788.5688"
+ font-style="normal"
+ font-weight="normal"
+ font-size="192"
+ id="text152"
+ style="font-style:normal;font-weight:normal;font-size:187.978302px;font-family:Helvetica;text-anchor:end;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_state</text>
+ <!-- Text -->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3096.1016"
+ y="3963.4336"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text156"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3096.1016"
+ y="4257.1494"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text158"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1627.5209"
+ y="5725.7305"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text160"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1627.5209"
+ y="6019.4463"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text162"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4564.6821"
+ y="6019.4463"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text164"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4564.6821"
+ y="5725.7305"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text166"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2214.9531"
+ y="7634.8848"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text168"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2214.9531"
+ y="7928.6011"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text170"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1040.0886"
+ y="8809.749"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text172"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1040.0886"
+ y="9103.4648"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text174"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5152.1138"
+ y="7634.8848"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text176"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5152.1138"
+ y="7928.6011"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text178"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3977.2495"
+ y="8809.749"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text180"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3977.2495"
+ y="9103.4648"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text182"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="452.6564"
+ y="3376.0012"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text184"
+ style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:start;fill:#000000;stroke-width:0.02447634in"
+ transform="scale(1.0213945,0.97905363)">struct rcu_state</text>
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Line -->
+ <polyline
+ points="5250,5850 5250,4864 "
+ style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline204"
+ transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" />
+ <!-- Arrowhead on XXXpoint 5250 5850 - 5250 4740-->
+ <path
+ style="fill:none;stroke:#000000;stroke-width:34.24744034;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker1177)"
+ d="m 6000.1472,7564.2558 c 1498.5508,0 1498.5508,0 1498.5508,0 v 520.0252"
+ id="path886"
+ inkscape:connector-curvature="0" />
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
new file mode 100644
index 000000000000..1b0aad184dd7
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
@@ -0,0 +1,1196 @@
+===================================================
+A Tour Through TREE_RCU's Data Structures [LWN.net]
+===================================================
+
+December 18, 2016
+
+This article was contributed by Paul E. McKenney
+
+Introduction
+============
+
+This document describes RCU's major data structures and their relationship
+to each other.
+
+Data-Structure Relationships
+============================
+
+RCU is for all intents and purposes a large state machine, and its
+data structures maintain the state in such a way as to allow RCU readers
+to execute extremely quickly, while also processing the RCU grace periods
+requested by updaters in an efficient and extremely scalable fashion.
+The efficiency and scalability of RCU updaters is provided primarily
+by a combining tree, as shown below:
+
+.. kernel-figure:: BigTreeClassicRCU.svg
+
+This diagram shows an enclosing ``rcu_state`` structure containing a tree
+of ``rcu_node`` structures. Each leaf node of the ``rcu_node`` tree has up
+to 16 ``rcu_data`` structures associated with it, so that there are
+``NR_CPUS`` number of ``rcu_data`` structures, one for each possible CPU.
+This structure is adjusted at boot time, if needed, to handle the common
+case where ``nr_cpu_ids`` is much less than ``NR_CPUs``.
+For example, a number of Linux distributions set ``NR_CPUs=4096``,
+which results in a three-level ``rcu_node`` tree.
+If the actual hardware has only 16 CPUs, RCU will adjust itself
+at boot time, resulting in an ``rcu_node`` tree with only a single node.
+
+The purpose of this combining tree is to allow per-CPU events
+such as quiescent states, dyntick-idle transitions,
+and CPU hotplug operations to be processed efficiently
+and scalably.
+Quiescent states are recorded by the per-CPU ``rcu_data`` structures,
+and other events are recorded by the leaf-level ``rcu_node``
+structures.
+All of these events are combined at each level of the tree until finally
+grace periods are completed at the tree's root ``rcu_node``
+structure.
+A grace period can be completed at the root once every CPU
+(or, in the case of ``CONFIG_PREEMPT_RCU``, task)
+has passed through a quiescent state.
+Once a grace period has completed, record of that fact is propagated
+back down the tree.
+
+As can be seen from the diagram, on a 64-bit system
+a two-level tree with 64 leaves can accommodate 1,024 CPUs, with a fanout
+of 64 at the root and a fanout of 16 at the leaves.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why isn't the fanout at the leaves also 64? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because there are more types of events that affect the leaf-level |
+| ``rcu_node`` structures than further up the tree. Therefore, if the |
+| leaf ``rcu_node`` structures have fanout of 64, the contention on |
+| these structures' ``->structures`` becomes excessive. Experimentation |
+| on a wide variety of systems has shown that a fanout of 16 works well |
+| for the leaves of the ``rcu_node`` tree. |
+| |
+| Of course, further experience with systems having hundreds or |
+| thousands of CPUs may demonstrate that the fanout for the non-leaf |
+| ``rcu_node`` structures must also be reduced. Such reduction can be |
+| easily carried out when and if it proves necessary. In the meantime, |
+| if you are using such a system and running into contention problems |
+| on the non-leaf ``rcu_node`` structures, you may use the |
+| ``CONFIG_RCU_FANOUT`` kernel configuration parameter to reduce the |
+| non-leaf fanout as needed. |
+| |
+| Kernels built for systems with strong NUMA characteristics might |
+| also need to adjust ``CONFIG_RCU_FANOUT`` so that the domains of |
+| the ``rcu_node`` structures align with hardware boundaries. |
+| However, there has thus far been no need for this. |
++-----------------------------------------------------------------------+
+
+If your system has more than 1,024 CPUs (or more than 512 CPUs on a
+32-bit system), then RCU will automatically add more levels to the tree.
+For example, if you are crazy enough to build a 64-bit system with
+65,536 CPUs, RCU would configure the ``rcu_node`` tree as follows:
+
+.. kernel-figure:: HugeTreeClassicRCU.svg
+
+RCU currently permits up to a four-level tree, which on a 64-bit system
+accommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for
+32-bit systems. On the other hand, you can set both
+``CONFIG_RCU_FANOUT`` and ``CONFIG_RCU_FANOUT_LEAF`` to be as small as
+2, which would result in a 16-CPU test using a 4-level tree. This can be
+useful for testing large-system capabilities on small test machines.
+
+This multi-level combining tree allows us to get most of the performance
+and scalability benefits of partitioning, even though RCU grace-period
+detection is inherently a global operation. The trick here is that only
+the last CPU to report a quiescent state into a given ``rcu_node``
+structure need advance to the ``rcu_node`` structure at the next level
+up the tree. This means that at the leaf-level ``rcu_node`` structure,
+only one access out of sixteen will progress up the tree. For the
+internal ``rcu_node`` structures, the situation is even more extreme:
+Only one access out of sixty-four will progress up the tree. Because the
+vast majority of the CPUs do not progress up the tree, the lock
+contention remains roughly constant up the tree. No matter how many CPUs
+there are in the system, at most 64 quiescent-state reports per grace
+period will progress all the way to the root ``rcu_node`` structure,
+thus ensuring that the lock contention on that root ``rcu_node``
+structure remains acceptably low.
+
+In effect, the combining tree acts like a big shock absorber, keeping
+lock contention under control at all tree levels regardless of the level
+of loading on the system.
+
+RCU updaters wait for normal grace periods by registering RCU callbacks,
+either directly via ``call_rcu()`` or indirectly via
+``synchronize_rcu()`` and friends. RCU callbacks are represented by
+``rcu_head`` structures, which are queued on ``rcu_data`` structures
+while they are waiting for a grace period to elapse, as shown in the
+following figure:
+
+.. kernel-figure:: BigTreePreemptRCUBHdyntickCB.svg
+
+This figure shows how ``TREE_RCU``'s and ``PREEMPT_RCU``'s major data
+structures are related. Lesser data structures will be introduced with
+the algorithms that make use of them.
+
+Note that each of the data structures in the above figure has its own
+synchronization:
+
+#. Each ``rcu_state`` structures has a lock and a mutex, and some fields
+ are protected by the corresponding root ``rcu_node`` structure's lock.
+#. Each ``rcu_node`` structure has a spinlock.
+#. The fields in ``rcu_data`` are private to the corresponding CPU,
+ although a few can be read and written by other CPUs.
+
+It is important to note that different data structures can have very
+different ideas about the state of RCU at any given time. For but one
+example, awareness of the start or end of a given RCU grace period
+propagates slowly through the data structures. This slow propagation is
+absolutely necessary for RCU to have good read-side performance. If this
+balkanized implementation seems foreign to you, one useful trick is to
+consider each instance of these data structures to be a different
+person, each having the usual slightly different view of reality.
+
+The general role of each of these data structures is as follows:
+
+#. ``rcu_state``: This structure forms the interconnection between the
+ ``rcu_node`` and ``rcu_data`` structures, tracks grace periods,
+ serves as short-term repository for callbacks orphaned by CPU-hotplug
+ events, maintains ``rcu_barrier()`` state, tracks expedited
+ grace-period state, and maintains state used to force quiescent
+ states when grace periods extend too long,
+#. ``rcu_node``: This structure forms the combining tree that propagates
+ quiescent-state information from the leaves to the root, and also
+ propagates grace-period information from the root to the leaves. It
+ provides local copies of the grace-period state in order to allow
+ this information to be accessed in a synchronized manner without
+ suffering the scalability limitations that would otherwise be imposed
+ by global locking. In ``CONFIG_PREEMPT_RCU`` kernels, it manages the
+ lists of tasks that have blocked while in their current RCU read-side
+ critical section. In ``CONFIG_PREEMPT_RCU`` with
+ ``CONFIG_RCU_BOOST``, it manages the per-\ ``rcu_node``
+ priority-boosting kernel threads (kthreads) and state. Finally, it
+ records CPU-hotplug state in order to determine which CPUs should be
+ ignored during a given grace period.
+#. ``rcu_data``: This per-CPU structure is the focus of quiescent-state
+ detection and RCU callback queuing. It also tracks its relationship
+ to the corresponding leaf ``rcu_node`` structure to allow
+ more-efficient propagation of quiescent states up the ``rcu_node``
+ combining tree. Like the ``rcu_node`` structure, it provides a local
+ copy of the grace-period information to allow for-free synchronized
+ access to this information from the corresponding CPU. Finally, this
+ structure records past dyntick-idle state for the corresponding CPU
+ and also tracks statistics.
+#. ``rcu_head``: This structure represents RCU callbacks, and is the
+ only structure allocated and managed by RCU users. The ``rcu_head``
+ structure is normally embedded within the RCU-protected data
+ structure.
+
+If all you wanted from this article was a general notion of how RCU's
+data structures are related, you are done. Otherwise, each of the
+following sections give more details on the ``rcu_state``, ``rcu_node``
+and ``rcu_data`` data structures.
+
+The ``rcu_state`` Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``rcu_state`` structure is the base structure that represents the
+state of RCU in the system. This structure forms the interconnection
+between the ``rcu_node`` and ``rcu_data`` structures, tracks grace
+periods, contains the lock used to synchronize with CPU-hotplug events,
+and maintains state used to force quiescent states when grace periods
+extend too long,
+
+A few of the ``rcu_state`` structure's fields are discussed, singly and
+in groups, in the following sections. The more specialized fields are
+covered in the discussion of their use.
+
+Relationship to rcu_node and rcu_data Structures
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+This portion of the ``rcu_state`` structure is declared as follows:
+
+::
+
+ 1 struct rcu_node node[NUM_RCU_NODES];
+ 2 struct rcu_node *level[NUM_RCU_LVLS + 1];
+ 3 struct rcu_data __percpu *rda;
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Wait a minute! You said that the ``rcu_node`` structures formed a |
+| tree, but they are declared as a flat array! What gives? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| The tree is laid out in the array. The first node In the array is the |
+| head, the next set of nodes in the array are children of the head |
+| node, and so on until the last set of nodes in the array are the |
+| leaves. |
+| See the following diagrams to see how this works. |
++-----------------------------------------------------------------------+
+
+The ``rcu_node`` tree is embedded into the ``->node[]`` array as shown
+in the following figure:
+
+.. kernel-figure:: TreeMapping.svg
+
+One interesting consequence of this mapping is that a breadth-first
+traversal of the tree is implemented as a simple linear scan of the
+array, which is in fact what the ``rcu_for_each_node_breadth_first()``
+macro does. This macro is used at the beginning and ends of grace
+periods.
+
+Each entry of the ``->level`` array references the first ``rcu_node``
+structure on the corresponding level of the tree, for example, as shown
+below:
+
+.. kernel-figure:: TreeMappingLevel.svg
+
+The zero\ :sup:`th` element of the array references the root
+``rcu_node`` structure, the first element references the first child of
+the root ``rcu_node``, and finally the second element references the
+first leaf ``rcu_node`` structure.
+
+For whatever it is worth, if you draw the tree to be tree-shaped rather
+than array-shaped, it is easy to draw a planar representation:
+
+.. kernel-figure:: TreeLevel.svg
+
+Finally, the ``->rda`` field references a per-CPU pointer to the
+corresponding CPU's ``rcu_data`` structure.
+
+All of these fields are constant once initialization is complete, and
+therefore need no protection.
+
+Grace-Period Tracking
+'''''''''''''''''''''
+
+This portion of the ``rcu_state`` structure is declared as follows:
+
+::
+
+ 1 unsigned long gp_seq;
+
+RCU grace periods are numbered, and the ``->gp_seq`` field contains the
+current grace-period sequence number. The bottom two bits are the state
+of the current grace period, which can be zero for not yet started or
+one for in progress. In other words, if the bottom two bits of
+``->gp_seq`` are zero, then RCU is idle. Any other value in the bottom
+two bits indicates that something is broken. This field is protected by
+the root ``rcu_node`` structure's ``->lock`` field.
+
+There are ``->gp_seq`` fields in the ``rcu_node`` and ``rcu_data``
+structures as well. The fields in the ``rcu_state`` structure represent
+the most current value, and those of the other structures are compared
+in order to detect the beginnings and ends of grace periods in a
+distributed fashion. The values flow from ``rcu_state`` to ``rcu_node``
+(down the tree from the root to the leaves) to ``rcu_data``.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Given that the root rcu_node structure has a gp_seq field, |
+| why does RCU maintain a separate gp_seq in the rcu_state structure? |
+| Why not just use the root rcu_node's gp_seq as the official record |
+| and update it directly when starting a new grace period? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| On single-node RCU trees (where the root node is also a leaf), |
+| updating the root node's gp_seq immediately would create unnecessary |
+| lock contention. Here's why: |
+| |
+| If we did rcu_seq_start() directly on the root node's gp_seq: |
+| |
+| 1. All CPUs would immediately see their node's gp_seq from their rdp's|
+| gp_seq, in rcu_pending(). They would all then invoke the RCU-core. |
+| 2. Which calls note_gp_changes() and try to acquire the node lock. |
+| 3. But rnp->qsmask isn't initialized yet (happens later in |
+| rcu_gp_init()) |
+| 4. So each CPU would acquire the lock, find it can't determine if it |
+| needs to report quiescent state (no qsmask), update rdp->gp_seq, |
+| and release the lock. |
+| 5. Result: Lots of lock acquisitions with no grace period progress |
+| |
+| By having a separate rcu_state.gp_seq, we can increment the official |
+| grace period counter without immediately affecting what CPUs see in |
+| their nodes. The hierarchical propagation in rcu_gp_init() then |
+| updates the root node's gp_seq and qsmask together under the same lock|
+| acquisition, avoiding this useless contention. |
++-----------------------------------------------------------------------+
+
+Miscellaneous
+'''''''''''''
+
+This portion of the ``rcu_state`` structure is declared as follows:
+
+::
+
+ 1 unsigned long gp_max;
+ 2 char abbr;
+ 3 char *name;
+
+The ``->gp_max`` field tracks the duration of the longest grace period
+in jiffies. It is protected by the root ``rcu_node``'s ``->lock``.
+
+The ``->name`` and ``->abbr`` fields distinguish between preemptible RCU
+(“rcu_preempt” and “p”) and non-preemptible RCU (“rcu_sched” and “s”).
+These fields are used for diagnostic and tracing purposes.
+
+The ``rcu_node`` Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``rcu_node`` structures form the combining tree that propagates
+quiescent-state information from the leaves to the root and also that
+propagates grace-period information from the root down to the leaves.
+They provides local copies of the grace-period state in order to allow
+this information to be accessed in a synchronized manner without
+suffering the scalability limitations that would otherwise be imposed by
+global locking. In ``CONFIG_PREEMPT_RCU`` kernels, they manage the lists
+of tasks that have blocked while in their current RCU read-side critical
+section. In ``CONFIG_PREEMPT_RCU`` with ``CONFIG_RCU_BOOST``, they
+manage the per-\ ``rcu_node`` priority-boosting kernel threads
+(kthreads) and state. Finally, they record CPU-hotplug state in order to
+determine which CPUs should be ignored during a given grace period.
+
+The ``rcu_node`` structure's fields are discussed, singly and in groups,
+in the following sections.
+
+Connection to Combining Tree
+''''''''''''''''''''''''''''
+
+This portion of the ``rcu_node`` structure is declared as follows:
+
+::
+
+ 1 struct rcu_node *parent;
+ 2 u8 level;
+ 3 u8 grpnum;
+ 4 unsigned long grpmask;
+ 5 int grplo;
+ 6 int grphi;
+
+The ``->parent`` pointer references the ``rcu_node`` one level up in the
+tree, and is ``NULL`` for the root ``rcu_node``. The RCU implementation
+makes heavy use of this field to push quiescent states up the tree. The
+``->level`` field gives the level in the tree, with the root being at
+level zero, its children at level one, and so on. The ``->grpnum`` field
+gives this node's position within the children of its parent, so this
+number can range between 0 and 31 on 32-bit systems and between 0 and 63
+on 64-bit systems. The ``->level`` and ``->grpnum`` fields are used only
+during initialization and for tracing. The ``->grpmask`` field is the
+bitmask counterpart of ``->grpnum``, and therefore always has exactly
+one bit set. This mask is used to clear the bit corresponding to this
+``rcu_node`` structure in its parent's bitmasks, which are described
+later. Finally, the ``->grplo`` and ``->grphi`` fields contain the
+lowest and highest numbered CPU served by this ``rcu_node`` structure,
+respectively.
+
+All of these fields are constant, and thus do not require any
+synchronization.
+
+Synchronization
+'''''''''''''''
+
+This field of the ``rcu_node`` structure is declared as follows:
+
+::
+
+ 1 raw_spinlock_t lock;
+
+This field is used to protect the remaining fields in this structure,
+unless otherwise stated. That said, all of the fields in this structure
+can be accessed without locking for tracing purposes. Yes, this can
+result in confusing traces, but better some tracing confusion than to be
+heisenbugged out of existence.
+
+.. _grace-period-tracking-1:
+
+Grace-Period Tracking
+'''''''''''''''''''''
+
+This portion of the ``rcu_node`` structure is declared as follows:
+
+::
+
+ 1 unsigned long gp_seq;
+ 2 unsigned long gp_seq_needed;
+
+The ``rcu_node`` structures' ``->gp_seq`` fields are the counterparts of
+the field of the same name in the ``rcu_state`` structure. They each may
+lag up to one step behind their ``rcu_state`` counterpart. If the bottom
+two bits of a given ``rcu_node`` structure's ``->gp_seq`` field is zero,
+then this ``rcu_node`` structure believes that RCU is idle.
+
+The ``>gp_seq`` field of each ``rcu_node`` structure is updated at the
+beginning and the end of each grace period.
+
+The ``->gp_seq_needed`` fields record the furthest-in-the-future grace
+period request seen by the corresponding ``rcu_node`` structure. The
+request is considered fulfilled when the value of the ``->gp_seq`` field
+equals or exceeds that of the ``->gp_seq_needed`` field.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Suppose that this ``rcu_node`` structure doesn't see a request for a |
+| very long time. Won't wrapping of the ``->gp_seq`` field cause |
+| problems? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| No, because if the ``->gp_seq_needed`` field lags behind the |
+| ``->gp_seq`` field, the ``->gp_seq_needed`` field will be updated at |
+| the end of the grace period. Modulo-arithmetic comparisons therefore |
+| will always get the correct answer, even with wrapping. |
++-----------------------------------------------------------------------+
+
+Quiescent-State Tracking
+''''''''''''''''''''''''
+
+These fields manage the propagation of quiescent states up the combining
+tree.
+
+This portion of the ``rcu_node`` structure has fields as follows:
+
+::
+
+ 1 unsigned long qsmask;
+ 2 unsigned long expmask;
+ 3 unsigned long qsmaskinit;
+ 4 unsigned long expmaskinit;
+
+The ``->qsmask`` field tracks which of this ``rcu_node`` structure's
+children still need to report quiescent states for the current normal
+grace period. Such children will have a value of 1 in their
+corresponding bit. Note that the leaf ``rcu_node`` structures should be
+thought of as having ``rcu_data`` structures as their children.
+Similarly, the ``->expmask`` field tracks which of this ``rcu_node``
+structure's children still need to report quiescent states for the
+current expedited grace period. An expedited grace period has the same
+conceptual properties as a normal grace period, but the expedited
+implementation accepts extreme CPU overhead to obtain much lower
+grace-period latency, for example, consuming a few tens of microseconds
+worth of CPU time to reduce grace-period duration from milliseconds to
+tens of microseconds. The ``->qsmaskinit`` field tracks which of this
+``rcu_node`` structure's children cover for at least one online CPU.
+This mask is used to initialize ``->qsmask``, and ``->expmaskinit`` is
+used to initialize ``->expmask`` and the beginning of the normal and
+expedited grace periods, respectively.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why are these bitmasks protected by locking? Come on, haven't you |
+| heard of atomic instructions??? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Lockless grace-period computation! Such a tantalizing possibility! |
+| But consider the following sequence of events: |
+| |
+| #. CPU 0 has been in dyntick-idle mode for quite some time. When it |
+| wakes up, it notices that the current RCU grace period needs it to |
+| report in, so it sets a flag where the scheduling clock interrupt |
+| will find it. |
+| #. Meanwhile, CPU 1 is running ``force_quiescent_state()``, and |
+| notices that CPU 0 has been in dyntick idle mode, which qualifies |
+| as an extended quiescent state. |
+| #. CPU 0's scheduling clock interrupt fires in the middle of an RCU |
+| read-side critical section, and notices that the RCU core needs |
+| something, so commences RCU softirq processing. |
+| #. CPU 0's softirq handler executes and is just about ready to report |
+| its quiescent state up the ``rcu_node`` tree. |
+| #. But CPU 1 beats it to the punch, completing the current grace |
+| period and starting a new one. |
+| #. CPU 0 now reports its quiescent state for the wrong grace period. |
+| That grace period might now end before the RCU read-side critical |
+| section. If that happens, disaster will ensue. |
+| |
+| So the locking is absolutely required in order to coordinate clearing |
+| of the bits with updating of the grace-period sequence number in |
+| ``->gp_seq``. |
++-----------------------------------------------------------------------+
+
+Blocked-Task Management
+'''''''''''''''''''''''
+
+``PREEMPT_RCU`` allows tasks to be preempted in the midst of their RCU
+read-side critical sections, and these tasks must be tracked explicitly.
+The details of exactly why and how they are tracked will be covered in a
+separate article on RCU read-side processing. For now, it is enough to
+know that the ``rcu_node`` structure tracks them.
+
+::
+
+ 1 struct list_head blkd_tasks;
+ 2 struct list_head *gp_tasks;
+ 3 struct list_head *exp_tasks;
+ 4 bool wait_blkd_tasks;
+
+The ``->blkd_tasks`` field is a list header for the list of blocked and
+preempted tasks. As tasks undergo context switches within RCU read-side
+critical sections, their ``task_struct`` structures are enqueued (via
+the ``task_struct``'s ``->rcu_node_entry`` field) onto the head of the
+``->blkd_tasks`` list for the leaf ``rcu_node`` structure corresponding
+to the CPU on which the outgoing context switch executed. As these tasks
+later exit their RCU read-side critical sections, they remove themselves
+from the list. This list is therefore in reverse time order, so that if
+one of the tasks is blocking the current grace period, all subsequent
+tasks must also be blocking that same grace period. Therefore, a single
+pointer into this list suffices to track all tasks blocking a given
+grace period. That pointer is stored in ``->gp_tasks`` for normal grace
+periods and in ``->exp_tasks`` for expedited grace periods. These last
+two fields are ``NULL`` if either there is no grace period in flight or
+if there are no blocked tasks preventing that grace period from
+completing. If either of these two pointers is referencing a task that
+removes itself from the ``->blkd_tasks`` list, then that task must
+advance the pointer to the next task on the list, or set the pointer to
+``NULL`` if there are no subsequent tasks on the list.
+
+For example, suppose that tasks T1, T2, and T3 are all hard-affinitied
+to the largest-numbered CPU in the system. Then if task T1 blocked in an
+RCU read-side critical section, then an expedited grace period started,
+then task T2 blocked in an RCU read-side critical section, then a normal
+grace period started, and finally task 3 blocked in an RCU read-side
+critical section, then the state of the last leaf ``rcu_node``
+structure's blocked-task list would be as shown below:
+
+.. kernel-figure:: blkd_task.svg
+
+Task T1 is blocking both grace periods, task T2 is blocking only the
+normal grace period, and task T3 is blocking neither grace period. Note
+that these tasks will not remove themselves from this list immediately
+upon resuming execution. They will instead remain on the list until they
+execute the outermost ``rcu_read_unlock()`` that ends their RCU
+read-side critical section.
+
+The ``->wait_blkd_tasks`` field indicates whether or not the current
+grace period is waiting on a blocked task.
+
+Sizing the ``rcu_node`` Array
+'''''''''''''''''''''''''''''
+
+The ``rcu_node`` array is sized via a series of C-preprocessor
+expressions as follows:
+
+::
+
+ 1 #ifdef CONFIG_RCU_FANOUT
+ 2 #define RCU_FANOUT CONFIG_RCU_FANOUT
+ 3 #else
+ 4 # ifdef CONFIG_64BIT
+ 5 # define RCU_FANOUT 64
+ 6 # else
+ 7 # define RCU_FANOUT 32
+ 8 # endif
+ 9 #endif
+ 10
+ 11 #ifdef CONFIG_RCU_FANOUT_LEAF
+ 12 #define RCU_FANOUT_LEAF CONFIG_RCU_FANOUT_LEAF
+ 13 #else
+ 14 # ifdef CONFIG_64BIT
+ 15 # define RCU_FANOUT_LEAF 64
+ 16 # else
+ 17 # define RCU_FANOUT_LEAF 32
+ 18 # endif
+ 19 #endif
+ 20
+ 21 #define RCU_FANOUT_1 (RCU_FANOUT_LEAF)
+ 22 #define RCU_FANOUT_2 (RCU_FANOUT_1 * RCU_FANOUT)
+ 23 #define RCU_FANOUT_3 (RCU_FANOUT_2 * RCU_FANOUT)
+ 24 #define RCU_FANOUT_4 (RCU_FANOUT_3 * RCU_FANOUT)
+ 25
+ 26 #if NR_CPUS <= RCU_FANOUT_1
+ 27 # define RCU_NUM_LVLS 1
+ 28 # define NUM_RCU_LVL_0 1
+ 29 # define NUM_RCU_NODES NUM_RCU_LVL_0
+ 30 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0 }
+ 31 # define RCU_NODE_NAME_INIT { "rcu_node_0" }
+ 32 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0" }
+ 33 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0" }
+ 34 #elif NR_CPUS <= RCU_FANOUT_2
+ 35 # define RCU_NUM_LVLS 2
+ 36 # define NUM_RCU_LVL_0 1
+ 37 # define NUM_RCU_LVL_1 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_1)
+ 38 # define NUM_RCU_NODES (NUM_RCU_LVL_0 + NUM_RCU_LVL_1)
+ 39 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0, NUM_RCU_LVL_1 }
+ 40 # define RCU_NODE_NAME_INIT { "rcu_node_0", "rcu_node_1" }
+ 41 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0", "rcu_node_fqs_1" }
+ 42 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0", "rcu_node_exp_1" }
+ 43 #elif NR_CPUS <= RCU_FANOUT_3
+ 44 # define RCU_NUM_LVLS 3
+ 45 # define NUM_RCU_LVL_0 1
+ 46 # define NUM_RCU_LVL_1 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_2)
+ 47 # define NUM_RCU_LVL_2 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_1)
+ 48 # define NUM_RCU_NODES (NUM_RCU_LVL_0 + NUM_RCU_LVL_1 + NUM_RCU_LVL_2)
+ 49 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0, NUM_RCU_LVL_1, NUM_RCU_LVL_2 }
+ 50 # define RCU_NODE_NAME_INIT { "rcu_node_0", "rcu_node_1", "rcu_node_2" }
+ 51 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0", "rcu_node_fqs_1", "rcu_node_fqs_2" }
+ 52 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0", "rcu_node_exp_1", "rcu_node_exp_2" }
+ 53 #elif NR_CPUS <= RCU_FANOUT_4
+ 54 # define RCU_NUM_LVLS 4
+ 55 # define NUM_RCU_LVL_0 1
+ 56 # define NUM_RCU_LVL_1 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_3)
+ 57 # define NUM_RCU_LVL_2 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_2)
+ 58 # define NUM_RCU_LVL_3 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_1)
+ 59 # define NUM_RCU_NODES (NUM_RCU_LVL_0 + NUM_RCU_LVL_1 + NUM_RCU_LVL_2 + NUM_RCU_LVL_3)
+ 60 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0, NUM_RCU_LVL_1, NUM_RCU_LVL_2, NUM_RCU_LVL_3 }
+ 61 # define RCU_NODE_NAME_INIT { "rcu_node_0", "rcu_node_1", "rcu_node_2", "rcu_node_3" }
+ 62 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0", "rcu_node_fqs_1", "rcu_node_fqs_2", "rcu_node_fqs_3" }
+ 63 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0", "rcu_node_exp_1", "rcu_node_exp_2", "rcu_node_exp_3" }
+ 64 #else
+ 65 # error "CONFIG_RCU_FANOUT insufficient for NR_CPUS"
+ 66 #endif
+
+The maximum number of levels in the ``rcu_node`` structure is currently
+limited to four, as specified by lines 21-24 and the structure of the
+subsequent “if” statement. For 32-bit systems, this allows
+16*32*32*32=524,288 CPUs, which should be sufficient for the next few
+years at least. For 64-bit systems, 16*64*64*64=4,194,304 CPUs is
+allowed, which should see us through the next decade or so. This
+four-level tree also allows kernels built with ``CONFIG_RCU_FANOUT=8``
+to support up to 4096 CPUs, which might be useful in very large systems
+having eight CPUs per socket (but please note that no one has yet shown
+any measurable performance degradation due to misaligned socket and
+``rcu_node`` boundaries). In addition, building kernels with a full four
+levels of ``rcu_node`` tree permits better testing of RCU's
+combining-tree code.
+
+The ``RCU_FANOUT`` symbol controls how many children are permitted at
+each non-leaf level of the ``rcu_node`` tree. If the
+``CONFIG_RCU_FANOUT`` Kconfig option is not specified, it is set based
+on the word size of the system, which is also the Kconfig default.
+
+The ``RCU_FANOUT_LEAF`` symbol controls how many CPUs are handled by
+each leaf ``rcu_node`` structure. Experience has shown that allowing a
+given leaf ``rcu_node`` structure to handle 64 CPUs, as permitted by the
+number of bits in the ``->qsmask`` field on a 64-bit system, results in
+excessive contention for the leaf ``rcu_node`` structures' ``->lock``
+fields. The number of CPUs per leaf ``rcu_node`` structure is therefore
+limited to 16 given the default value of ``CONFIG_RCU_FANOUT_LEAF``. If
+``CONFIG_RCU_FANOUT_LEAF`` is unspecified, the value selected is based
+on the word size of the system, just as for ``CONFIG_RCU_FANOUT``.
+Lines 11-19 perform this computation.
+
+Lines 21-24 compute the maximum number of CPUs supported by a
+single-level (which contains a single ``rcu_node`` structure),
+two-level, three-level, and four-level ``rcu_node`` tree, respectively,
+given the fanout specified by ``RCU_FANOUT`` and ``RCU_FANOUT_LEAF``.
+These numbers of CPUs are retained in the ``RCU_FANOUT_1``,
+``RCU_FANOUT_2``, ``RCU_FANOUT_3``, and ``RCU_FANOUT_4`` C-preprocessor
+variables, respectively.
+
+These variables are used to control the C-preprocessor ``#if`` statement
+spanning lines 26-66 that computes the number of ``rcu_node`` structures
+required for each level of the tree, as well as the number of levels
+required. The number of levels is placed in the ``NUM_RCU_LVLS``
+C-preprocessor variable by lines 27, 35, 44, and 54. The number of
+``rcu_node`` structures for the topmost level of the tree is always
+exactly one, and this value is unconditionally placed into
+``NUM_RCU_LVL_0`` by lines 28, 36, 45, and 55. The rest of the levels
+(if any) of the ``rcu_node`` tree are computed by dividing the maximum
+number of CPUs by the fanout supported by the number of levels from the
+current level down, rounding up. This computation is performed by
+lines 37, 46-47, and 56-58. Lines 31-33, 40-42, 50-52, and 62-63 create
+initializers for lockdep lock-class names. Finally, lines 64-66 produce
+an error if the maximum number of CPUs is too large for the specified
+fanout.
+
+The ``rcu_segcblist`` Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``rcu_segcblist`` structure maintains a segmented list of callbacks
+as follows:
+
+::
+
+ 1 #define RCU_DONE_TAIL 0
+ 2 #define RCU_WAIT_TAIL 1
+ 3 #define RCU_NEXT_READY_TAIL 2
+ 4 #define RCU_NEXT_TAIL 3
+ 5 #define RCU_CBLIST_NSEGS 4
+ 6
+ 7 struct rcu_segcblist {
+ 8 struct rcu_head *head;
+ 9 struct rcu_head **tails[RCU_CBLIST_NSEGS];
+ 10 unsigned long gp_seq[RCU_CBLIST_NSEGS];
+ 11 long len;
+ 12 long len_lazy;
+ 13 };
+
+The segments are as follows:
+
+#. ``RCU_DONE_TAIL``: Callbacks whose grace periods have elapsed. These
+ callbacks are ready to be invoked.
+#. ``RCU_WAIT_TAIL``: Callbacks that are waiting for the current grace
+ period. Note that different CPUs can have different ideas about which
+ grace period is current, hence the ``->gp_seq`` field.
+#. ``RCU_NEXT_READY_TAIL``: Callbacks waiting for the next grace period
+ to start.
+#. ``RCU_NEXT_TAIL``: Callbacks that have not yet been associated with a
+ grace period.
+
+The ``->head`` pointer references the first callback or is ``NULL`` if
+the list contains no callbacks (which is *not* the same as being empty).
+Each element of the ``->tails[]`` array references the ``->next``
+pointer of the last callback in the corresponding segment of the list,
+or the list's ``->head`` pointer if that segment and all previous
+segments are empty. If the corresponding segment is empty but some
+previous segment is not empty, then the array element is identical to
+its predecessor. Older callbacks are closer to the head of the list, and
+new callbacks are added at the tail. This relationship between the
+``->head`` pointer, the ``->tails[]`` array, and the callbacks is shown
+in this diagram:
+
+.. kernel-figure:: nxtlist.svg
+
+In this figure, the ``->head`` pointer references the first RCU callback
+in the list. The ``->tails[RCU_DONE_TAIL]`` array element references the
+``->head`` pointer itself, indicating that none of the callbacks is
+ready to invoke. The ``->tails[RCU_WAIT_TAIL]`` array element references
+callback CB 2's ``->next`` pointer, which indicates that CB 1 and CB 2
+are both waiting on the current grace period, give or take possible
+disagreements about exactly which grace period is the current one. The
+``->tails[RCU_NEXT_READY_TAIL]`` array element references the same RCU
+callback that ``->tails[RCU_WAIT_TAIL]`` does, which indicates that
+there are no callbacks waiting on the next RCU grace period. The
+``->tails[RCU_NEXT_TAIL]`` array element references CB 4's ``->next``
+pointer, indicating that all the remaining RCU callbacks have not yet
+been assigned to an RCU grace period. Note that the
+``->tails[RCU_NEXT_TAIL]`` array element always references the last RCU
+callback's ``->next`` pointer unless the callback list is empty, in
+which case it references the ``->head`` pointer.
+
+There is one additional important special case for the
+``->tails[RCU_NEXT_TAIL]`` array element: It can be ``NULL`` when this
+list is *disabled*. Lists are disabled when the corresponding CPU is
+offline or when the corresponding CPU's callbacks are offloaded to a
+kthread, both of which are described elsewhere.
+
+CPUs advance their callbacks from the ``RCU_NEXT_TAIL`` to the
+``RCU_NEXT_READY_TAIL`` to the ``RCU_WAIT_TAIL`` to the
+``RCU_DONE_TAIL`` list segments as grace periods advance.
+
+The ``->gp_seq[]`` array records grace-period numbers corresponding to
+the list segments. This is what allows different CPUs to have different
+ideas as to which is the current grace period while still avoiding
+premature invocation of their callbacks. In particular, this allows CPUs
+that go idle for extended periods to determine which of their callbacks
+are ready to be invoked after reawakening.
+
+The ``->len`` counter contains the number of callbacks in ``->head``,
+and the ``->len_lazy`` contains the number of those callbacks that are
+known to only free memory, and whose invocation can therefore be safely
+deferred.
+
+.. important::
+
+ It is the ``->len`` field that determines whether or
+ not there are callbacks associated with this ``rcu_segcblist``
+ structure, *not* the ``->head`` pointer. The reason for this is that all
+ the ready-to-invoke callbacks (that is, those in the ``RCU_DONE_TAIL``
+ segment) are extracted all at once at callback-invocation time
+ (``rcu_do_batch``), due to which ``->head`` may be set to NULL if there
+ are no not-done callbacks remaining in the ``rcu_segcblist``. If
+ callback invocation must be postponed, for example, because a
+ high-priority process just woke up on this CPU, then the remaining
+ callbacks are placed back on the ``RCU_DONE_TAIL`` segment and
+ ``->head`` once again points to the start of the segment. In short, the
+ head field can briefly be ``NULL`` even though the CPU has callbacks
+ present the entire time. Therefore, it is not appropriate to test the
+ ``->head`` pointer for ``NULL``.
+
+In contrast, the ``->len`` and ``->len_lazy`` counts are adjusted only
+after the corresponding callbacks have been invoked. This means that the
+``->len`` count is zero only if the ``rcu_segcblist`` structure really
+is devoid of callbacks. Of course, off-CPU sampling of the ``->len``
+count requires careful use of appropriate synchronization, for example,
+memory barriers. This synchronization can be a bit subtle, particularly
+in the case of ``rcu_barrier()``.
+
+The ``rcu_data`` Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``rcu_data`` maintains the per-CPU state for the RCU subsystem. The
+fields in this structure may be accessed only from the corresponding CPU
+(and from tracing) unless otherwise stated. This structure is the focus
+of quiescent-state detection and RCU callback queuing. It also tracks
+its relationship to the corresponding leaf ``rcu_node`` structure to
+allow more-efficient propagation of quiescent states up the ``rcu_node``
+combining tree. Like the ``rcu_node`` structure, it provides a local
+copy of the grace-period information to allow for-free synchronized
+access to this information from the corresponding CPU. Finally, this
+structure records past dyntick-idle state for the corresponding CPU and
+also tracks statistics.
+
+The ``rcu_data`` structure's fields are discussed, singly and in groups,
+in the following sections.
+
+Connection to Other Data Structures
+'''''''''''''''''''''''''''''''''''
+
+This portion of the ``rcu_data`` structure is declared as follows:
+
+::
+
+ 1 int cpu;
+ 2 struct rcu_node *mynode;
+ 3 unsigned long grpmask;
+ 4 bool beenonline;
+
+The ``->cpu`` field contains the number of the corresponding CPU and the
+``->mynode`` field references the corresponding ``rcu_node`` structure.
+The ``->mynode`` is used to propagate quiescent states up the combining
+tree. These two fields are constant and therefore do not require
+synchronization.
+
+The ``->grpmask`` field indicates the bit in the ``->mynode->qsmask``
+corresponding to this ``rcu_data`` structure, and is also used when
+propagating quiescent states. The ``->beenonline`` flag is set whenever
+the corresponding CPU comes online, which means that the debugfs tracing
+need not dump out any ``rcu_data`` structure for which this flag is not
+set.
+
+Quiescent-State and Grace-Period Tracking
+'''''''''''''''''''''''''''''''''''''''''
+
+This portion of the ``rcu_data`` structure is declared as follows:
+
+::
+
+ 1 unsigned long gp_seq;
+ 2 unsigned long gp_seq_needed;
+ 3 bool cpu_no_qs;
+ 4 bool core_needs_qs;
+ 5 bool gpwrap;
+
+The ``->gp_seq`` field is the counterpart of the field of the same name
+in the ``rcu_state`` and ``rcu_node`` structures. The
+``->gp_seq_needed`` field is the counterpart of the field of the same
+name in the rcu_node structure. They may each lag up to one behind their
+``rcu_node`` counterparts, but in ``CONFIG_NO_HZ_IDLE`` and
+``CONFIG_NO_HZ_FULL`` kernels can lag arbitrarily far behind for CPUs in
+dyntick-idle mode (but these counters will catch up upon exit from
+dyntick-idle mode). If the lower two bits of a given ``rcu_data``
+structure's ``->gp_seq`` are zero, then this ``rcu_data`` structure
+believes that RCU is idle.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| All this replication of the grace period numbers can only cause |
+| massive confusion. Why not just keep a global sequence number and be |
+| done with it??? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because if there was only a single global sequence numbers, there |
+| would need to be a single global lock to allow safely accessing and |
+| updating it. And if we are not going to have a single global lock, we |
+| need to carefully manage the numbers on a per-node basis. Recall from |
+| the answer to a previous Quick Quiz that the consequences of applying |
+| a previously sampled quiescent state to the wrong grace period are |
+| quite severe. |
++-----------------------------------------------------------------------+
+
+The ``->cpu_no_qs`` flag indicates that the CPU has not yet passed
+through a quiescent state, while the ``->core_needs_qs`` flag indicates
+that the RCU core needs a quiescent state from the corresponding CPU.
+The ``->gpwrap`` field indicates that the corresponding CPU has remained
+idle for so long that the ``gp_seq`` counter is in danger of overflow,
+which will cause the CPU to disregard the values of its counters on its
+next exit from idle.
+
+RCU Callback Handling
+'''''''''''''''''''''
+
+In the absence of CPU-hotplug events, RCU callbacks are invoked by the
+same CPU that registered them. This is strictly a cache-locality
+optimization: callbacks can and do get invoked on CPUs other than the
+one that registered them. After all, if the CPU that registered a given
+callback has gone offline before the callback can be invoked, there
+really is no other choice.
+
+This portion of the ``rcu_data`` structure is declared as follows:
+
+::
+
+ 1 struct rcu_segcblist cblist;
+ 2 long qlen_last_fqs_check;
+ 3 unsigned long n_cbs_invoked;
+ 4 unsigned long n_nocbs_invoked;
+ 5 unsigned long n_cbs_orphaned;
+ 6 unsigned long n_cbs_adopted;
+ 7 unsigned long n_force_qs_snap;
+ 8 long blimit;
+
+The ``->cblist`` structure is the segmented callback list described
+earlier. The CPU advances the callbacks in its ``rcu_data`` structure
+whenever it notices that another RCU grace period has completed. The CPU
+detects the completion of an RCU grace period by noticing that the value
+of its ``rcu_data`` structure's ``->gp_seq`` field differs from that of
+its leaf ``rcu_node`` structure. Recall that each ``rcu_node``
+structure's ``->gp_seq`` field is updated at the beginnings and ends of
+each grace period.
+
+The ``->qlen_last_fqs_check`` and ``->n_force_qs_snap`` coordinate the
+forcing of quiescent states from ``call_rcu()`` and friends when
+callback lists grow excessively long.
+
+The ``->n_cbs_invoked``, ``->n_cbs_orphaned``, and ``->n_cbs_adopted``
+fields count the number of callbacks invoked, sent to other CPUs when
+this CPU goes offline, and received from other CPUs when those other
+CPUs go offline. The ``->n_nocbs_invoked`` is used when the CPU's
+callbacks are offloaded to a kthread.
+
+Finally, the ``->blimit`` counter is the maximum number of RCU callbacks
+that may be invoked at a given time.
+
+Dyntick-Idle Handling
+'''''''''''''''''''''
+
+This portion of the ``rcu_data`` structure is declared as follows:
+
+::
+
+ 1 int watching_snap;
+ 2 unsigned long dynticks_fqs;
+
+The ``->watching_snap`` field is used to take a snapshot of the
+corresponding CPU's dyntick-idle state when forcing quiescent states,
+and is therefore accessed from other CPUs. Finally, the
+``->dynticks_fqs`` field is used to count the number of times this CPU
+is determined to be in dyntick-idle state, and is used for tracing and
+debugging purposes.
+
+This portion of the rcu_data structure is declared as follows:
+
+::
+
+ 1 long nesting;
+ 2 long nmi_nesting;
+ 3 atomic_t dynticks;
+ 4 bool rcu_need_heavy_qs;
+ 5 bool rcu_urgent_qs;
+
+These fields in the rcu_data structure maintain the per-CPU dyntick-idle
+state for the corresponding CPU. The fields may be accessed only from
+the corresponding CPU (and from tracing) unless otherwise stated.
+
+The ``->nesting`` field counts the nesting depth of process
+execution, so that in normal circumstances this counter has value zero
+or one. NMIs, irqs, and tracers are counted by the
+``->nmi_nesting`` field. Because NMIs cannot be masked, changes
+to this variable have to be undertaken carefully using an algorithm
+provided by Andy Lutomirski. The initial transition from idle adds one,
+and nested transitions add two, so that a nesting level of five is
+represented by a ``->nmi_nesting`` value of nine. This counter
+can therefore be thought of as counting the number of reasons why this
+CPU cannot be permitted to enter dyntick-idle mode, aside from
+process-level transitions.
+
+However, it turns out that when running in non-idle kernel context, the
+Linux kernel is fully capable of entering interrupt handlers that never
+exit and perhaps also vice versa. Therefore, whenever the
+``->nesting`` field is incremented up from zero, the
+``->nmi_nesting`` field is set to a large positive number, and
+whenever the ``->nesting`` field is decremented down to zero,
+the ``->nmi_nesting`` field is set to zero. Assuming that
+the number of misnested interrupts is not sufficient to overflow the
+counter, this approach corrects the ``->nmi_nesting`` field
+every time the corresponding CPU enters the idle loop from process
+context.
+
+The ``->dynticks`` field counts the corresponding CPU's transitions to
+and from either dyntick-idle or user mode, so that this counter has an
+even value when the CPU is in dyntick-idle mode or user mode and an odd
+value otherwise. The transitions to/from user mode need to be counted
+for user mode adaptive-ticks support (see Documentation/timers/no_hz.rst).
+
+The ``->rcu_need_heavy_qs`` field is used to record the fact that the
+RCU core code would really like to see a quiescent state from the
+corresponding CPU, so much so that it is willing to call for
+heavy-weight dyntick-counter operations. This flag is checked by RCU's
+context-switch and ``cond_resched()`` code, which provide a momentary
+idle sojourn in response.
+
+Finally, the ``->rcu_urgent_qs`` field is used to record the fact that
+the RCU core code would really like to see a quiescent state from the
+corresponding CPU, with the various other fields indicating just how
+badly RCU wants this quiescent state. This flag is checked by RCU's
+context-switch path (``rcu_note_context_switch``) and the cond_resched
+code.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why not simply combine the ``->nesting`` and |
+| ``->nmi_nesting`` counters into a single counter that just |
+| counts the number of reasons that the corresponding CPU is non-idle? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because this would fail in the presence of interrupts whose handlers |
+| never return and of handlers that manage to return from a made-up |
+| interrupt. |
++-----------------------------------------------------------------------+
+
+Additional fields are present for some special-purpose builds, and are
+discussed separately.
+
+The ``rcu_head`` Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each ``rcu_head`` structure represents an RCU callback. These structures
+are normally embedded within RCU-protected data structures whose
+algorithms use asynchronous grace periods. In contrast, when using
+algorithms that block waiting for RCU grace periods, RCU users need not
+provide ``rcu_head`` structures.
+
+The ``rcu_head`` structure has fields as follows:
+
+::
+
+ 1 struct rcu_head *next;
+ 2 void (*func)(struct rcu_head *head);
+
+The ``->next`` field is used to link the ``rcu_head`` structures
+together in the lists within the ``rcu_data`` structures. The ``->func``
+field is a pointer to the function to be called when the callback is
+ready to be invoked, and this function is passed a pointer to the
+``rcu_head`` structure. However, ``kfree_rcu()`` uses the ``->func``
+field to record the offset of the ``rcu_head`` structure within the
+enclosing RCU-protected data structure.
+
+Both of these fields are used internally by RCU. From the viewpoint of
+RCU users, this structure is an opaque “cookie”.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Given that the callback function ``->func`` is passed a pointer to |
+| the ``rcu_head`` structure, how is that function supposed to find the |
+| beginning of the enclosing RCU-protected data structure? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| In actual practice, there is a separate callback function per type of |
+| RCU-protected data structure. The callback function can therefore use |
+| the ``container_of()`` macro in the Linux kernel (or other |
+| pointer-manipulation facilities in other software environments) to |
+| find the beginning of the enclosing structure. |
++-----------------------------------------------------------------------+
+
+RCU-Specific Fields in the ``task_struct`` Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``CONFIG_PREEMPT_RCU`` implementation uses some additional fields in
+the ``task_struct`` structure:
+
+::
+
+ 1 #ifdef CONFIG_PREEMPT_RCU
+ 2 int rcu_read_lock_nesting;
+ 3 union rcu_special rcu_read_unlock_special;
+ 4 struct list_head rcu_node_entry;
+ 5 struct rcu_node *rcu_blocked_node;
+ 6 #endif /* #ifdef CONFIG_PREEMPT_RCU */
+ 7 #ifdef CONFIG_TASKS_RCU
+ 8 unsigned long rcu_tasks_nvcsw;
+ 9 bool rcu_tasks_holdout;
+ 10 struct list_head rcu_tasks_holdout_list;
+ 11 int rcu_tasks_idle_cpu;
+ 12 #endif /* #ifdef CONFIG_TASKS_RCU */
+
+The ``->rcu_read_lock_nesting`` field records the nesting level for RCU
+read-side critical sections, and the ``->rcu_read_unlock_special`` field
+is a bitmask that records special conditions that require
+``rcu_read_unlock()`` to do additional work. The ``->rcu_node_entry``
+field is used to form lists of tasks that have blocked within
+preemptible-RCU read-side critical sections and the
+``->rcu_blocked_node`` field references the ``rcu_node`` structure whose
+list this task is a member of, or ``NULL`` if it is not blocked within a
+preemptible-RCU read-side critical section.
+
+The ``->rcu_tasks_nvcsw`` field tracks the number of voluntary context
+switches that this task had undergone at the beginning of the current
+tasks-RCU grace period, ``->rcu_tasks_holdout`` is set if the current
+tasks-RCU grace period is waiting on this task,
+``->rcu_tasks_holdout_list`` is a list element enqueuing this task on
+the holdout list, and ``->rcu_tasks_idle_cpu`` tracks which CPU this
+idle task is running, but only if the task is currently running, that
+is, if the CPU is currently idle.
+
+Accessor Functions
+~~~~~~~~~~~~~~~~~~
+
+The following listing shows the ``rcu_get_root()``,
+``rcu_for_each_node_breadth_first`` and ``rcu_for_each_leaf_node()``
+function and macros:
+
+::
+
+ 1 static struct rcu_node *rcu_get_root(struct rcu_state *rsp)
+ 2 {
+ 3 return &rsp->node[0];
+ 4 }
+ 5
+ 6 #define rcu_for_each_node_breadth_first(rsp, rnp) \
+ 7 for ((rnp) = &(rsp)->node[0]; \
+ 8 (rnp) < &(rsp)->node[NUM_RCU_NODES]; (rnp)++)
+ 9
+ 10 #define rcu_for_each_leaf_node(rsp, rnp) \
+ 11 for ((rnp) = (rsp)->level[NUM_RCU_LVLS - 1]; \
+ 12 (rnp) < &(rsp)->node[NUM_RCU_NODES]; (rnp)++)
+
+The ``rcu_get_root()`` simply returns a pointer to the first element of
+the specified ``rcu_state`` structure's ``->node[]`` array, which is the
+root ``rcu_node`` structure.
+
+As noted earlier, the ``rcu_for_each_node_breadth_first()`` macro takes
+advantage of the layout of the ``rcu_node`` structures in the
+``rcu_state`` structure's ``->node[]`` array, performing a breadth-first
+traversal by simply traversing the array in order. Similarly, the
+``rcu_for_each_leaf_node()`` macro traverses only the last part of the
+array, thus traversing only the leaf ``rcu_node`` structures.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| What does ``rcu_for_each_leaf_node()`` do if the ``rcu_node`` tree |
+| contains only a single node? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| In the single-node case, ``rcu_for_each_leaf_node()`` traverses the |
+| single node. |
++-----------------------------------------------------------------------+
+
+Summary
+~~~~~~~
+
+So the state of RCU is represented by an ``rcu_state`` structure, which
+contains a combining tree of ``rcu_node`` and ``rcu_data`` structures.
+Finally, in ``CONFIG_NO_HZ_IDLE`` kernels, each CPU's dyntick-idle state
+is tracked by dynticks-related fields in the ``rcu_data`` structure. If
+you made it this far, you are well prepared to read the code
+walkthroughs in the other articles in this series.
+
+Acknowledgments
+~~~~~~~~~~~~~~~
+
+I owe thanks to Cyrill Gorcunov, Mathieu Desnoyers, Dhaval Giani, Paul
+Turner, Abhishek Srivastava, Matt Kowalczyk, and Serge Hallyn for
+helping me get this document into a more human-readable state.
+
+Legal Statement
+~~~~~~~~~~~~~~~
+
+This work represents the view of the author and does not necessarily
+represent the view of IBM.
+
+Linux is a registered trademark of Linus Torvalds.
+
+Other company, product, and service names may be trademarks or service
+marks of others.
diff --git a/Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg b/Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg
new file mode 100644
index 000000000000..2bf12b468206
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg
@@ -0,0 +1,939 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:37:22 2015 -->
+
+<!-- Magnification: 3.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="15.1in"
+ height="11.2in"
+ viewBox="-66 -66 18087 13407"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="HugeTreeClassicRCU.fig">
+ <metadata
+ id="metadata224">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs222">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Mend"
+ style="overflow:visible;">
+ <path
+ id="path3982"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;"
+ transform="scale(0.4) rotate(180) translate(10,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1134"
+ inkscape:window-height="789"
+ id="namedview220"
+ showgrid="false"
+ inkscape:zoom="0.60515873"
+ inkscape:cx="679.5"
+ inkscape:cy="504"
+ inkscape:window-x="786"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4" />
+ <g
+ style="stroke-width:.025in; fill:none"
+ id="g4">
+ <!-- Line: box -->
+ <rect
+ x="450"
+ y="0"
+ width="17100"
+ height="8325"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; "
+ id="rect6" />
+ <!-- Line: box -->
+ <rect
+ x="11025"
+ y="3600"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect8" />
+ <!-- Line: box -->
+ <rect
+ x="4275"
+ y="3600"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect10" />
+ <!-- Line: box -->
+ <rect
+ x="5400"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect12" />
+ <!-- Line: box -->
+ <rect
+ x="9900"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect14" />
+ <!-- Line: box -->
+ <rect
+ x="14400"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect16" />
+ <!-- Line: box -->
+ <rect
+ x="900"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect18" />
+ <!-- Line: box -->
+ <rect
+ x="7650"
+ y="900"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect20" />
+ <!-- Line -->
+ <polyline
+ points="3150,9225 3150,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline22" />
+ <!-- Arrowhead on XXXpoint 3150 9225 - 3150 7560-->
+ <!-- Circle -->
+ <circle
+ cx="8550"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle26" />
+ <!-- Circle -->
+ <circle
+ cx="9000"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle28" />
+ <!-- Circle -->
+ <circle
+ cx="9450"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle30" />
+ <!-- Line -->
+ <polyline
+ points="6750,6300 8250,5010 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline32" />
+ <!-- Arrowhead on XXXpoint 6750 6300 - 8391 4890-->
+ <!-- Line -->
+ <polyline
+ points="11250,6300 9747,5010 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline36" />
+ <!-- Arrowhead on XXXpoint 11250 6300 - 9606 4890-->
+ <!-- Circle -->
+ <circle
+ cx="13950"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle40" />
+ <!-- Circle -->
+ <circle
+ cx="13500"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle42" />
+ <!-- Circle -->
+ <circle
+ cx="13050"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle44" />
+ <!-- Circle -->
+ <circle
+ cx="9450"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle46" />
+ <!-- Circle -->
+ <circle
+ cx="9000"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle48" />
+ <!-- Circle -->
+ <circle
+ cx="8550"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle50" />
+ <!-- Circle -->
+ <circle
+ cx="4950"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle52" />
+ <!-- Circle -->
+ <circle
+ cx="4500"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle54" />
+ <!-- Circle -->
+ <circle
+ cx="4050"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle56" />
+ <!-- Circle -->
+ <circle
+ cx="1800"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle58" />
+ <!-- Circle -->
+ <circle
+ cx="2250"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle60" />
+ <!-- Circle -->
+ <circle
+ cx="2700"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle62" />
+ <!-- Circle -->
+ <circle
+ cx="15300"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle64" />
+ <!-- Circle -->
+ <circle
+ cx="15750"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle66" />
+ <!-- Circle -->
+ <circle
+ cx="16200"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle68" />
+ <!-- Circle -->
+ <circle
+ cx="10800"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle70" />
+ <!-- Circle -->
+ <circle
+ cx="11250"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle72" />
+ <!-- Circle -->
+ <circle
+ cx="11700"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle74" />
+ <!-- Circle -->
+ <circle
+ cx="6300"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle76" />
+ <!-- Circle -->
+ <circle
+ cx="6750"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle78" />
+ <!-- Circle -->
+ <circle
+ cx="7200"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle80" />
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="11475"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect82" />
+ <!-- Line: box -->
+ <rect
+ x="1800"
+ y="9225"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect84" />
+ <!-- Line: box -->
+ <rect
+ x="4500"
+ y="11475"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect86" />
+ <!-- Line: box -->
+ <rect
+ x="6300"
+ y="9270"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect88" />
+ <!-- Line: box -->
+ <rect
+ x="8955"
+ y="11475"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect90" />
+ <!-- Line: box -->
+ <rect
+ x="10755"
+ y="9270"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect92" />
+ <!-- Line: box -->
+ <rect
+ x="13455"
+ y="11475"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect94" />
+ <!-- Line: box -->
+ <rect
+ x="15255"
+ y="9270"
+ width="2700"
+ height="1800"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect96" />
+ <!-- Line -->
+ <polyline
+ points="11700,3600 10197,2310 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline98" />
+ <!-- Arrowhead on XXXpoint 11700 3600 - 10056 2190-->
+ <!-- Line -->
+ <polyline
+ points="6300,3600 7800,2310 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline102" />
+ <!-- Arrowhead on XXXpoint 6300 3600 - 7941 2190-->
+ <!-- Line -->
+ <polyline
+ points="3150,6300 4650,5010 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline106" />
+ <!-- Arrowhead on XXXpoint 3150 6300 - 4791 4890-->
+ <!-- Line -->
+ <polyline
+ points="14850,6300 13347,5010 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline110" />
+ <!-- Arrowhead on XXXpoint 14850 6300 - 13206 4890-->
+ <!-- Line -->
+ <polyline
+ points="1350,11475 1350,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline114" />
+ <!-- Arrowhead on XXXpoint 1350 11475 - 1350 7560-->
+ <!-- Line -->
+ <polyline
+ points="16650,9225 16650,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline118" />
+ <!-- Arrowhead on XXXpoint 16650 9225 - 16650 7560-->
+ <!-- Line -->
+ <polyline
+ points="14850,11475 14850,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline122" />
+ <!-- Arrowhead on XXXpoint 14850 11475 - 14850 7560-->
+ <!-- Line -->
+ <polyline
+ points="12150,9225 12150,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline126" />
+ <!-- Arrowhead on XXXpoint 12150 9225 - 12150 7560-->
+ <!-- Line -->
+ <polyline
+ points="10350,11475 10350,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline130" />
+ <!-- Arrowhead on XXXpoint 10350 11475 - 10350 7560-->
+ <!-- Line -->
+ <polyline
+ points="7650,9225 7650,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline134" />
+ <!-- Arrowhead on XXXpoint 7650 9225 - 7650 7560-->
+ <!-- Line -->
+ <polyline
+ points="5850,11475 5850,7746 "
+ style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline138" />
+ <!-- Arrowhead on XXXpoint 5850 11475 - 5850 7560-->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12375"
+ y="4500"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text142">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12375"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text144">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5625"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text146">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5625"
+ y="4500"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text148">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6750"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text150">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6750"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text152">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11250"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text154">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11250"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text156">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="15750"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text158">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="15750"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text160">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2250"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text162">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2250"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text164">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1350"
+ y="13050"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text166">CPU 0</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1350"
+ y="11925"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text168">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1350"
+ y="12375"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text170">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3150"
+ y="10800"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text172">CPU 15</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3150"
+ y="9675"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text174">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3150"
+ y="10125"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text176">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5850"
+ y="11925"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text178">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5850"
+ y="12375"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text180">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5850"
+ y="13050"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text182">CPU 21823</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7650"
+ y="10845"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text184">CPU 21839</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7650"
+ y="10170"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text186">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7650"
+ y="9720"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text188">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="10305"
+ y="11925"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text190">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="10305"
+ y="12375"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text192">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="10305"
+ y="13050"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text194">CPU 43679</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12105"
+ y="10845"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text196">CPU 43695</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12105"
+ y="10170"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text198">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12105"
+ y="9720"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text200">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="14805"
+ y="11925"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text202">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="14805"
+ y="12375"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text204">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="14805"
+ y="13050"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text206">CPU 65519</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="16605"
+ y="10845"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text208">CPU 65535</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="16605"
+ y="10170"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text210">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="16605"
+ y="9720"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text212">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="675"
+ y="450"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="start"
+ id="text214">struct rcu_state</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="9000"
+ y="1350"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text216">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="9000"
+ y="1800"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text218">rcu_node</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/TreeLevel.svg b/Documentation/RCU/Design/Data-Structures/TreeLevel.svg
new file mode 100644
index 000000000000..7a7eb3bac95c
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/TreeLevel.svg
@@ -0,0 +1,828 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:41:29 2015 -->
+
+<!-- Magnification: 3.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="17.7in"
+ height="10.4in"
+ viewBox="-66 -66 21237 12507"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeLevel.fig">
+ <metadata
+ id="metadata216">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs214">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Mend"
+ style="overflow:visible;">
+ <path
+ id="path3974"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;"
+ transform="scale(0.4) rotate(180) translate(10,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1023"
+ inkscape:window-height="1148"
+ id="namedview212"
+ showgrid="false"
+ inkscape:zoom="0.55869424"
+ inkscape:cx="796.50006"
+ inkscape:cy="467.99997"
+ inkscape:window-x="897"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4" />
+ <g
+ style="stroke-width:.025in; fill:none"
+ id="g4">
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="0"
+ width="20655"
+ height="8325"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; "
+ id="rect6" />
+ <!-- Line: box -->
+ <rect
+ x="14130"
+ y="3600"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect8" />
+ <!-- Line: box -->
+ <rect
+ x="7380"
+ y="3600"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect10" />
+ <!-- Line: box -->
+ <rect
+ x="8505"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect12" />
+ <!-- Line: box -->
+ <rect
+ x="13005"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect14" />
+ <!-- Line: box -->
+ <rect
+ x="17505"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect16" />
+ <!-- Line: box -->
+ <rect
+ x="4005"
+ y="6300"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect18" />
+ <!-- Line: box -->
+ <rect
+ x="10755"
+ y="900"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect20" />
+ <!-- Line -->
+ <polyline
+ points="6255,9225 6255,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline22" />
+ <!-- Arrowhead on XXXpoint 6255 9225 - 6255 7560-->
+ <!-- Circle -->
+ <circle
+ cx="11655"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle26" />
+ <!-- Circle -->
+ <circle
+ cx="12105"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle28" />
+ <!-- Circle -->
+ <circle
+ cx="12555"
+ cy="4275"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle30" />
+ <!-- Line -->
+ <polyline
+ points="9855,6300 11355,5010 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline32" />
+ <!-- Arrowhead on XXXpoint 9855 6300 - 11496 4890-->
+ <!-- Line -->
+ <polyline
+ points="14355,6300 12852,5010 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline36" />
+ <!-- Arrowhead on XXXpoint 14355 6300 - 12711 4890-->
+ <!-- Circle -->
+ <circle
+ cx="17055"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle40" />
+ <!-- Circle -->
+ <circle
+ cx="16605"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle42" />
+ <!-- Circle -->
+ <circle
+ cx="16155"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle44" />
+ <!-- Circle -->
+ <circle
+ cx="12555"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle46" />
+ <!-- Circle -->
+ <circle
+ cx="12105"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle48" />
+ <!-- Circle -->
+ <circle
+ cx="11655"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle50" />
+ <!-- Circle -->
+ <circle
+ cx="8055"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle52" />
+ <!-- Circle -->
+ <circle
+ cx="7605"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle54" />
+ <!-- Circle -->
+ <circle
+ cx="7155"
+ cy="6975"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle56" />
+ <!-- Circle -->
+ <circle
+ cx="4905"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle58" />
+ <!-- Circle -->
+ <circle
+ cx="5355"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle60" />
+ <!-- Circle -->
+ <circle
+ cx="5805"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle62" />
+ <!-- Circle -->
+ <circle
+ cx="18405"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle64" />
+ <!-- Circle -->
+ <circle
+ cx="18855"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle66" />
+ <!-- Circle -->
+ <circle
+ cx="19305"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle68" />
+ <!-- Circle -->
+ <circle
+ cx="13905"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle70" />
+ <!-- Circle -->
+ <circle
+ cx="14355"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle72" />
+ <!-- Circle -->
+ <circle
+ cx="14805"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle74" />
+ <!-- Circle -->
+ <circle
+ cx="9405"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle76" />
+ <!-- Circle -->
+ <circle
+ cx="9855"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle78" />
+ <!-- Circle -->
+ <circle
+ cx="10305"
+ cy="8775"
+ r="114"
+ style="fill:#000000;stroke:#000000;stroke-width:21;"
+ id="circle80" />
+ <!-- Line: box -->
+ <rect
+ x="225"
+ y="1125"
+ width="3150"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:21; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; "
+ id="rect82" />
+ <!-- Line: box -->
+ <rect
+ x="225"
+ y="2250"
+ width="3150"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:21; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; "
+ id="rect84" />
+ <!-- Line: box -->
+ <rect
+ x="225"
+ y="3375"
+ width="3150"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:21; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; "
+ id="rect86" />
+ <!-- Line -->
+ <polyline
+ points="14805,3600 13302,2310 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline88" />
+ <!-- Arrowhead on XXXpoint 14805 3600 - 13161 2190-->
+ <!-- Line -->
+ <polyline
+ points="9405,3600 10905,2310 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline92" />
+ <!-- Arrowhead on XXXpoint 9405 3600 - 11046 2190-->
+ <!-- Line -->
+ <polyline
+ points="6255,6300 7755,5010 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline96" />
+ <!-- Arrowhead on XXXpoint 6255 6300 - 7896 4890-->
+ <!-- Line -->
+ <polyline
+ points="17955,6300 16452,5010 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline100" />
+ <!-- Arrowhead on XXXpoint 17955 6300 - 16311 4890-->
+ <!-- Line -->
+ <polyline
+ points="4455,11025 4455,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline104" />
+ <!-- Arrowhead on XXXpoint 4455 11025 - 4455 7560-->
+ <!-- Line -->
+ <polyline
+ points="19755,9225 19755,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline108" />
+ <!-- Arrowhead on XXXpoint 19755 9225 - 19755 7560-->
+ <!-- Line -->
+ <polyline
+ points="17955,11025 17955,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline112" />
+ <!-- Arrowhead on XXXpoint 17955 11025 - 17955 7560-->
+ <!-- Line -->
+ <polyline
+ points="15255,9225 15255,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline116" />
+ <!-- Arrowhead on XXXpoint 15255 9225 - 15255 7560-->
+ <!-- Line -->
+ <polyline
+ points="13455,11025 13455,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline120" />
+ <!-- Arrowhead on XXXpoint 13455 11025 - 13455 7560-->
+ <!-- Line -->
+ <polyline
+ points="10755,9225 10755,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline124" />
+ <!-- Arrowhead on XXXpoint 10755 9225 - 10755 7560-->
+ <!-- Line -->
+ <polyline
+ points="8955,11025 8955,7746 "
+ style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline128" />
+ <!-- Arrowhead on XXXpoint 8955 11025 - 8955 7560-->
+ <!-- Line: box -->
+ <rect
+ x="12105"
+ y="11025"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect132" />
+ <!-- Line: box -->
+ <rect
+ x="13905"
+ y="9225"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect134" />
+ <!-- Line: box -->
+ <rect
+ x="16605"
+ y="11025"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect136" />
+ <!-- Line: box -->
+ <rect
+ x="18405"
+ y="9225"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect138" />
+ <!-- Line: box -->
+ <rect
+ x="9405"
+ y="9225"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect140" />
+ <!-- Line: box -->
+ <rect
+ x="7605"
+ y="11025"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect142" />
+ <!-- Line: box -->
+ <rect
+ x="4905"
+ y="9225"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect144" />
+ <!-- Line: box -->
+ <rect
+ x="3105"
+ y="11025"
+ width="2700"
+ height="1350"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect146" />
+ <!-- Line -->
+ <polyline
+ points="3375,1575 10701,1575 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline148" />
+ <!-- Arrowhead on XXXpoint 3375 1575 - 10890 1575-->
+ <!-- Line -->
+ <polyline
+ points="3375,3825 4050,3825 4050,5400 2700,5400 2700,6975 3951,6975 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline152" />
+ <!-- Arrowhead on XXXpoint 2700 6975 - 4140 6975-->
+ <!-- Line -->
+ <polyline
+ points="3375,2700 5175,2700 5175,4275 7326,4275 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline156" />
+ <!-- Arrowhead on XXXpoint 5175 4275 - 7515 4275-->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="15480"
+ y="4500"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text160">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="15480"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text162">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="8730"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text164">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="8730"
+ y="4500"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text166">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="9855"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text168">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="9855"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text170">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="14355"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text172">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="14355"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text174">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="18855"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text176">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="18855"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text178">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5355"
+ y="6750"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text180">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5355"
+ y="7200"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text182">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="450"
+ y="1800"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ text-anchor="start"
+ id="text184">-&gt;level[0]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="450"
+ y="2925"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ text-anchor="start"
+ id="text186">-&gt;level[1]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="450"
+ y="4050"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ text-anchor="start"
+ id="text188">-&gt;level[2]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12105"
+ y="1350"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text190">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="12105"
+ y="1800"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="middle"
+ id="text192">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6255"
+ y="10125"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text194">CPU 15</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4455"
+ y="11925"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text196">CPU 0</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="19755"
+ y="10125"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text198">CPU 65535</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="17955"
+ y="11925"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text200">CPU 65519</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="15255"
+ y="10125"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text202">CPU 43695</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="13455"
+ y="11925"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text204">CPU 43679</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="10755"
+ y="10125"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text206">CPU 21839</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="8955"
+ y="11925"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text208">CPU 21823</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="450"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="bold"
+ font-size="288"
+ text-anchor="start"
+ id="text210">struct rcu_state</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/TreeMapping.svg b/Documentation/RCU/Design/Data-Structures/TreeMapping.svg
new file mode 100644
index 000000000000..729cfa9e6cdb
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/TreeMapping.svg
@@ -0,0 +1,305 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:43:22 2015 -->
+
+<!-- Magnification: 1.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="3.1in"
+ height="0.9in"
+ viewBox="-12 -12 3699 1074"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeMapping.fig">
+ <metadata
+ id="metadata66">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs64">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow2Lend"
+ style="overflow:visible;">
+ <path
+ id="path3836"
+ style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+ d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+ transform="scale(1.1) rotate(180) translate(1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow2Mend"
+ style="overflow:visible;">
+ <path
+ id="path3842"
+ style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+ d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+ transform="scale(0.6) rotate(180) translate(0,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Mend"
+ style="overflow:visible;">
+ <path
+ id="path3824"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;"
+ transform="scale(0.4) rotate(180) translate(10,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="991"
+ inkscape:window-height="606"
+ id="namedview62"
+ showgrid="false"
+ inkscape:zoom="3.0752688"
+ inkscape:cx="139.5"
+ inkscape:cy="40.5"
+ inkscape:window-x="891"
+ inkscape:window-y="177"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4" />
+ <g
+ style="stroke-width:.025in; fill:none"
+ id="g4">
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="0"
+ width="3675"
+ height="1050"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; "
+ id="rect6" />
+ <!-- Line: box -->
+ <rect
+ x="75"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect8" />
+ <!-- Line: box -->
+ <rect
+ x="600"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect10" />
+ <!-- Line: box -->
+ <rect
+ x="1125"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect12" />
+ <!-- Line: box -->
+ <rect
+ x="1650"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect14" />
+ <!-- Line: box -->
+ <rect
+ x="2175"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect16" />
+ <!-- Line: box -->
+ <rect
+ x="3225"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect18" />
+ <!-- Line -->
+ <polyline
+ points="675,375 675,150 300,150 300,358 "
+ style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline20" />
+ <!-- Arrowhead on XXXpoint 300 150 - 300 390-->
+ <!-- Line -->
+ <polyline
+ points="1200,675 1200,900 300,900 300,691 "
+ style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline24" />
+ <!-- Arrowhead on XXXpoint 300 900 - 300 660-->
+ <!-- Line -->
+ <polyline
+ points="1725,375 1725,150 900,150 900,358 "
+ style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline28" />
+ <!-- Arrowhead on XXXpoint 900 150 - 900 390-->
+ <!-- Line -->
+ <polyline
+ points="2250,375 2250,75 825,75 825,358 "
+ style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline32" />
+ <!-- Arrowhead on XXXpoint 825 75 - 825 390-->
+ <!-- Line -->
+ <polyline
+ points="2775,675 2775,900 1425,900 1425,691 "
+ style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline36" />
+ <!-- Arrowhead on XXXpoint 1425 900 - 1425 660-->
+ <!-- Line -->
+ <polyline
+ points="3300,675 3300,975 1350,975 1350,691 "
+ style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline40" />
+ <!-- Arrowhead on XXXpoint 1350 975 - 1350 660-->
+ <!-- Line: box -->
+ <rect
+ x="2700"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect44" />
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="300"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text46">0:7 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1350"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text48">4:7 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1875"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text50">0:1 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2400"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text52">2:3 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2925"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text54">4:5 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3450"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text56">6:7 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="825"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text58">0:3 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3600"
+ y="150"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="end"
+ id="text60">struct rcu_state</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg b/Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg
new file mode 100644
index 000000000000..5b416a4b8453
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg
@@ -0,0 +1,380 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:45:19 2015 -->
+
+<!-- Magnification: 1.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="3.1in"
+ height="1.8in"
+ viewBox="-12 -12 3699 2124"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeMappingLevel.svg">
+ <metadata
+ id="metadata98">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs96">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow2Lend"
+ style="overflow:visible;">
+ <path
+ id="path3868"
+ style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+ d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+ transform="scale(1.1) rotate(180) translate(1,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1598"
+ inkscape:window-height="1211"
+ id="namedview94"
+ showgrid="false"
+ inkscape:zoom="5.2508961"
+ inkscape:cx="139.5"
+ inkscape:cy="81"
+ inkscape:window-x="840"
+ inkscape:window-y="122"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4" />
+ <g
+ style="stroke-width:.025in; fill:none"
+ id="g4">
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="0"
+ width="3675"
+ height="2100"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; "
+ id="rect6" />
+ <!-- Line: box -->
+ <rect
+ x="75"
+ y="1350"
+ width="750"
+ height="225"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect8" />
+ <!-- Line: box -->
+ <rect
+ x="75"
+ y="1575"
+ width="750"
+ height="225"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect10" />
+ <!-- Line: box -->
+ <rect
+ x="75"
+ y="1800"
+ width="750"
+ height="225"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect12" />
+ <!-- Arc -->
+ <path
+ style="stroke:#000000;stroke-width:7;stroke-linecap:butt;"
+ d="M 1800,900 A 118 118 0 0 0 1800 1125 "
+ id="path14" />
+ <!-- Arc -->
+ <path
+ style="stroke:#000000;stroke-width:7;stroke-linecap:butt;"
+ d="M 750,900 A 75 75 0 0 0 750 1050 "
+ id="path16" />
+ <!-- Line -->
+ <polyline
+ points="750,900 750,691 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline18" />
+ <!-- Arrowhead on XXXpoint 750 900 - 750 660-->
+ <!-- Line: box -->
+ <rect
+ x="75"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect22" />
+ <!-- Line: box -->
+ <rect
+ x="600"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect24" />
+ <!-- Line: box -->
+ <rect
+ x="1650"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect26" />
+ <!-- Line: box -->
+ <rect
+ x="2175"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect28" />
+ <!-- Line: box -->
+ <rect
+ x="3225"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect30" />
+ <!-- Line -->
+ <polyline
+ points="675,375 675,150 300,150 300,358 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline32" />
+ <!-- Arrowhead on XXXpoint 300 150 - 300 390-->
+ <!-- Line -->
+ <polyline
+ points="1725,375 1725,150 900,150 900,358 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline36" />
+ <!-- Arrowhead on XXXpoint 900 150 - 900 390-->
+ <!-- Line -->
+ <polyline
+ points="2250,375 2250,75 825,75 825,358 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline40" />
+ <!-- Arrowhead on XXXpoint 825 75 - 825 390-->
+ <!-- Line -->
+ <polyline
+ points="2775,675 2775,975 1425,975 1425,691 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline44" />
+ <!-- Arrowhead on XXXpoint 1425 975 - 1425 660-->
+ <!-- Line: box -->
+ <rect
+ x="2700"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect48" />
+ <!-- Line: box -->
+ <rect
+ x="1125"
+ y="375"
+ width="375"
+ height="300"
+ rx="0"
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; "
+ id="rect50" />
+ <!-- Line -->
+ <polyline
+ points="3300,675 3300,1050 1350,1050 1350,691 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline52" />
+ <!-- Arrowhead on XXXpoint 1350 1050 - 1350 660-->
+ <!-- Line -->
+ <polyline
+ points="825,1425 975,1425 975,1200 225,1200 225,691 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline56" />
+ <!-- Arrowhead on XXXpoint 225 1200 - 225 660-->
+ <!-- Line -->
+ <polyline
+ points="1200,675 1200,975 300,975 300,691 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline60" />
+ <!-- Arrowhead on XXXpoint 300 975 - 300 660-->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="150"
+ y="1500"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="108"
+ text-anchor="start"
+ id="text64">-&gt;level[0]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="150"
+ y="1725"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="108"
+ text-anchor="start"
+ id="text66">-&gt;level[1]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="150"
+ y="1950"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="108"
+ text-anchor="start"
+ id="text68">-&gt;level[2]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="300"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text70">0:7 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1350"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text72">4:7 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1875"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text74">0:1 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2400"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text76">2:3 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2925"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text78">4:5 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3450"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text80">6:7 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="825"
+ y="525"
+ fill="#000000"
+ font-family="Times"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="middle"
+ id="text82">0:3 </text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3600"
+ y="150"
+ fill="#000000"
+ font-family="Courier"
+ font-style="normal"
+ font-weight="normal"
+ font-size="96"
+ text-anchor="end"
+ id="text84">struct rcu_state</text>
+ <!-- Line -->
+ <polyline
+ points="825,1875 1800,1875 1800,1125 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:none"
+ id="polyline86" />
+ <!-- Line -->
+ <polyline
+ points="1800,900 1800,691 "
+ style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ id="polyline88" />
+ <!-- Arrowhead on XXXpoint 1800 900 - 1800 660-->
+ <!-- Line -->
+ <polyline
+ points="825,1650 1200,1650 1200,1125 750,1125 750,1050 "
+ style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="polyline92" />
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/blkd_task.svg b/Documentation/RCU/Design/Data-Structures/blkd_task.svg
new file mode 100644
index 000000000000..bed13e9ecab8
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/blkd_task.svg
@@ -0,0 +1,631 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="10.1in"
+ height="6.5999999in"
+ viewBox="-44 -44 12088 7895.4414"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.92.2pre0 (973e216, 2017-07-25)"
+ sodipodi:docname="blkd_task.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 Z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1920"
+ inkscape:window-height="1019"
+ id="namedview208"
+ showgrid="false"
+ inkscape:zoom="1.0495049"
+ inkscape:cx="456.40569"
+ inkscape:cy="348.88682"
+ inkscape:window-x="0"
+ inkscape:window-y="0"
+ inkscape:window-maximized="1"
+ inkscape:current-layer="g4"
+ showguides="false" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(0,-2393.6637)">
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790-->
+ <polyline
+ points="5714 6068 5704 5822 5598 6044 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline14"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140-->
+ <polyline
+ points="4514 7418 4506 7172 4396 7394 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline18"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140-->
+ <polyline
+ points="1504 7418 1496 7172 1386 7394 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline22"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940-->
+ <polyline
+ points="2704 6218 2696 5972 2586 6194 "
+ style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8"
+ id="polyline26"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Line: box -->
+ <rect
+ x="23.757858"
+ y="2635.7231"
+ width="6300"
+ height="7350"
+ rx="0"
+ style="fill:#ffffff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect28" />
+ <!-- Line: box -->
+ <rect
+ x="323.75787"
+ y="3235.7231"
+ width="5700"
+ height="3750"
+ rx="0"
+ style="fill:#ffff00;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect30" />
+ <!-- Line -->
+ <polyline
+ points="1350,3450 2350,2590 "
+ style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline32"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510-->
+ <!-- Line -->
+ <polyline
+ points="4950,3450 3948,2590 "
+ style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline36"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510-->
+ <!-- Line -->
+ <polyline
+ points="4050,6600 4050,4414 "
+ style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline40"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290-->
+ <!-- Line -->
+ <polyline
+ points="1050,6600 1050,4414 "
+ style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline44"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290-->
+ <!-- Line -->
+ <polyline
+ points="2250,5400 2250,4414 "
+ style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline48"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240-->
+ <!-- Circle -->
+ <circle
+ cx="2873.7581"
+ cy="6085.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle68" />
+ <!-- Circle -->
+ <circle
+ cx="3173.7581"
+ cy="6085.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle70" />
+ <!-- Circle -->
+ <circle
+ cx="3473.7581"
+ cy="6085.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle72" />
+ <!-- Circle -->
+ <circle
+ cx="1373.7578"
+ cy="7285.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle74" />
+ <!-- Circle -->
+ <circle
+ cx="1673.7578"
+ cy="7285.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle76" />
+ <!-- Circle -->
+ <circle
+ cx="1973.7578"
+ cy="7285.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle78" />
+ <!-- Circle -->
+ <circle
+ cx="4373.7578"
+ cy="7285.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle80" />
+ <!-- Circle -->
+ <circle
+ cx="4673.7578"
+ cy="7285.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle82" />
+ <!-- Circle -->
+ <circle
+ cx="4973.7578"
+ cy="7285.7236"
+ r="76"
+ style="fill:#000000;stroke:#000000;stroke-width:14"
+ id="circle84" />
+ <!-- Line: box -->
+ <rect
+ x="773.75781"
+ y="5635.7236"
+ width="1800"
+ height="900"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect86" />
+ <!-- Line: box -->
+ <rect
+ x="323.75787"
+ y="8785.7227"
+ width="1500"
+ height="900"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect88" />
+ <!-- Line: box -->
+ <rect
+ x="4523.7578"
+ y="7585.7236"
+ width="1500"
+ height="900"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect90" />
+ <!-- Line: box -->
+ <rect
+ x="3323.7581"
+ y="8785.7227"
+ width="1500"
+ height="900"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect92" />
+ <!-- Line: box -->
+ <rect
+ x="2273.7581"
+ y="3835.7231"
+ width="1800"
+ height="900"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect94" />
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <rect
+ x="1523.7578"
+ y="7585.7236"
+ width="1500"
+ height="900"
+ rx="0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect104" />
+ <!-- Line -->
+ <polygon
+ points="7350,2850 7350,5100 5550,4350 5550,3450 "
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:14;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:120, 120"
+ id="polygon106"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Line -->
+ <polyline
+ points="9300,3150 10734,3150 "
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline108"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150-->
+ <!-- Line: box -->
+ <rect
+ x="10823.758"
+ y="5035.7236"
+ width="1200"
+ height="750"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112" />
+ <!-- Line -->
+ <polyline
+ points="11400,3600 11400,4284 "
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline114"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410-->
+ <!-- Line: box -->
+ <rect
+ x="10823.758"
+ y="6535.7236"
+ width="1200"
+ height="750"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect118" />
+ <!-- Line -->
+ <polyline
+ points="11400,5100 11400,5784 "
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline120"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910-->
+ <!-- Line: box -->
+ <rect
+ x="10823.758"
+ y="8035.7236"
+ width="1200"
+ height="750"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect124" />
+ <!-- Line -->
+ <polyline
+ points="9300,3900 9900,3900 9900,4650 10734,4650 "
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline126"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650-->
+ <!-- Line -->
+ <polyline
+ points="9300,4650 9600,4650 9600,6150 10734,6150 "
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline130"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150-->
+ <!-- Text -->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3173.7581"
+ y="4135.7231"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text136"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3173.7581"
+ y="4435.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text138"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1673.7578"
+ y="5935.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text140"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1673.7578"
+ y="6235.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text142"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2273.7581"
+ y="7885.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text144"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="2273.7581"
+ y="8185.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text146"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1073.7578"
+ y="9085.7227"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text148"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="1073.7578"
+ y="9385.7227"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text150"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5273.7578"
+ y="7885.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text152"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="5273.7578"
+ y="8185.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text154"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4073.7578"
+ y="9085.7227"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text156"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4073.7578"
+ y="9385.7227"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text158"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="473.75784"
+ y="3535.7231"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text160"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">struct rcu_state</text>
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="6023.7578"
+ y="2935.7231"
+ font-style="normal"
+ font-weight="normal"
+ font-size="192"
+ id="text178"
+ style="font-style:normal;font-weight:normal;font-size:192px;font-family:Helvetica;text-anchor:end;fill:#000000">rcu_state</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11423.758"
+ y="5485.7236"
+ font-style="normal"
+ font-weight="normal"
+ font-size="216"
+ id="text180"
+ style="font-style:normal;font-weight:normal;font-size:216px;font-family:Helvetica;text-anchor:middle;fill:#000000">T3</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11423.758"
+ y="6985.7236"
+ font-style="normal"
+ font-weight="normal"
+ font-size="216"
+ id="text182"
+ style="font-style:normal;font-weight:normal;font-size:216px;font-family:Helvetica;text-anchor:middle;fill:#000000">T2</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11423.758"
+ y="8485.7227"
+ font-style="normal"
+ font-weight="normal"
+ font-size="216"
+ id="text184"
+ style="font-style:normal;font-weight:normal;font-size:216px;font-family:Helvetica;text-anchor:middle;fill:#000000">T1</text>
+ <!-- Line -->
+ <polyline
+ points="5250,5400 5250,4414 "
+ style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline186"
+ transform="translate(23.757862,2185.7233)" />
+ <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290-->
+ <!-- Line: box -->
+ <rect
+ x="3773.7581"
+ y="5635.7236"
+ width="1800"
+ height="900"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect190" />
+ <!-- Line: box -->
+ <rect
+ x="7373.7578"
+ y="5035.7236"
+ width="1950"
+ height="750"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect192" />
+ <!-- Line: box -->
+ <rect
+ x="7373.7578"
+ y="5785.7236"
+ width="1950"
+ height="750"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect194" />
+ <!-- Line: box -->
+ <rect
+ x="7373.7578"
+ y="6535.7236"
+ width="1950"
+ height="750"
+ rx="0"
+ style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect196" />
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4673.7578"
+ y="6235.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text198"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_node</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="4673.7578"
+ y="5935.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text200"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7523.7578"
+ y="5485.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">blkd_tasks</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7523.7578"
+ y="6235.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text204"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">gp_tasks</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="7523.7578"
+ y="6985.7236"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text206"
+ style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">exp_tasks</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/nxtlist.svg b/Documentation/RCU/Design/Data-Structures/nxtlist.svg
new file mode 100644
index 000000000000..0223e79c38e0
--- /dev/null
+++ b/Documentation/RCU/Design/Data-Structures/nxtlist.svg
@@ -0,0 +1,386 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:39:46 2015 -->
+
+<!-- Magnification: 3.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="10.4in"
+ height="10.4in"
+ viewBox="-66 -66 12507 12507"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="segcblist.svg">
+ <metadata
+ id="metadata94">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs92">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Mend"
+ style="overflow:visible;">
+ <path
+ id="path3852"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;"
+ transform="scale(0.4) rotate(180) translate(10,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="925"
+ inkscape:window-height="928"
+ id="namedview90"
+ showgrid="false"
+ inkscape:zoom="0.80021373"
+ inkscape:cx="467.99997"
+ inkscape:cy="467.99997"
+ inkscape:window-x="948"
+ inkscape:window-y="73"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4" />
+ <g
+ style="stroke-width:.025in; fill:none"
+ id="g4">
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="0"
+ width="7875"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; "
+ id="rect6" />
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="1125"
+ width="7875"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; "
+ id="rect8" />
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="2250"
+ width="7875"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; "
+ id="rect10" />
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="3375"
+ width="7875"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; "
+ id="rect12" />
+ <!-- Line: box -->
+ <rect
+ x="0"
+ y="4500"
+ width="7875"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; "
+ id="rect14" />
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="0"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect16" />
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="1125"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect18" />
+ <!-- Line -->
+ <polyline
+ points="11475,2250 11475,3276 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline20" />
+ <!-- Arrowhead on XXXpoint 11475 2250 - 11475 3465-->
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="6750"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect24" />
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="7875"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect26" />
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="10125"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect28" />
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="11250"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect30" />
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="3375"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect32" />
+ <!-- Line -->
+ <polyline
+ points="11475,5625 11475,6651 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline34" />
+ <!-- Arrowhead on XXXpoint 11475 5625 - 11475 6840-->
+ <!-- Line -->
+ <polyline
+ points="7875,225 10476,225 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline38" />
+ <!-- Arrowhead on XXXpoint 7875 225 - 10665 225-->
+ <!-- Line -->
+ <polyline
+ points="7875,1350 9675,1350 9675,675 7971,675 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline42" />
+ <!-- Arrowhead on XXXpoint 9675 675 - 7785 675-->
+ <!-- Line -->
+ <polyline
+ points="7875,2475 9675,2475 9675,4725 10476,4725 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline46" />
+ <!-- Arrowhead on XXXpoint 9675 4725 - 10665 4725-->
+ <!-- Line -->
+ <polyline
+ points="7875,3600 9225,3600 9225,5175 10476,5175 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline50" />
+ <!-- Arrowhead on XXXpoint 9225 5175 - 10665 5175-->
+ <!-- Line -->
+ <polyline
+ points="7875,4725 8775,4725 8775,11475 10476,11475 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline54" />
+ <!-- Arrowhead on XXXpoint 8775 11475 - 10665 11475-->
+ <!-- Line: box -->
+ <rect
+ x="10575"
+ y="4500"
+ width="1800"
+ height="1125"
+ rx="0"
+ style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; "
+ id="rect58" />
+ <!-- Line -->
+ <polyline
+ points="11475,9000 11475,10026 "
+ style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
+ id="polyline60" />
+ <!-- Arrowhead on XXXpoint 11475 9000 - 11475 10215-->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="675"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ id="text64"
+ style="font-size:324px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;head</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="1800"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ id="text66"
+ style="font-size:324px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;tails[RCU_DONE_TAIL]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="2925"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ id="text68"
+ style="font-size:324px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;tails[RCU_WAIT_TAIL]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="4050"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ id="text70"
+ style="font-size:324px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;tails[RCU_NEXT_READY_TAIL]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="225"
+ y="5175"
+ font-style="normal"
+ font-weight="bold"
+ font-size="324"
+ id="text72"
+ style="font-size:324px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;tails[RCU_NEXT_TAIL]</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="675"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text74">CB 1</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="1800"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text76">next</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="7425"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text78">CB 3</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="8550"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text80">next</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="10800"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text82">CB 4</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="11925"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text84">next</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="4050"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text86">CB 2</text>
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="11475"
+ y="5175"
+ fill="#000000"
+ font-family="Helvetica"
+ font-style="normal"
+ font-weight="normal"
+ font-size="324"
+ text-anchor="middle"
+ id="text88">next</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/ExpRCUFlow.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/ExpRCUFlow.svg
new file mode 100644
index 000000000000..7c6c90bd02c9
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/ExpRCUFlow.svg
@@ -0,0 +1,830 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:39:46 2015 -->
+
+<!-- Magnification: 3.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="952.6817"
+ height="1219.6219"
+ viewBox="-66 -66 12729.905 16296.808"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="ExpRCUFlow.svg">
+ <metadata
+ id="metadata94">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs92">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path4146"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3852"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend-9"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3852-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-6"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-16"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-8"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-160"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-5"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-78"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-66"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-8"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-56"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-19"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-89"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-85"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-3"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-73"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-55"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-88"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-198"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-22"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker5072"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path5074"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-87"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-63"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-26"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-51"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1090"
+ inkscape:window-height="1148"
+ id="namedview90"
+ showgrid="true"
+ inkscape:zoom="0.80021373"
+ inkscape:cx="462.49289"
+ inkscape:cy="623.19585"
+ inkscape:window-x="557"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4"
+ inkscape:snap-grids="false"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5"
+ fit-margin-left="5" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(23.312813,523.41305)">
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11475 2250 - 11475 3465-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11475 5625 - 11475 6840-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 7875 225 - 10665 225-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9675 675 - 7785 675-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9675 4725 - 10665 4725-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9225 5175 - 10665 5175-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 8775 11475 - 10665 11475-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11475 9000 - 11475 10215-->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <g
+ id="g4104"
+ transform="translate(-1068.9745,0)">
+ <rect
+ transform="matrix(-0.70710678,0.70710678,-0.70710678,-0.70710678,0,0)"
+ y="-7383.8755"
+ x="-6124.8989"
+ height="1966.2251"
+ width="1953.6969"
+ id="rect3032-1-0"
+ style="fill:#96ff96;fill-opacity:1;stroke:#000000;stroke-width:45.00382233;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4098"
+ y="818.40338"
+ x="8168.2671"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="818.40338"
+ x="8168.2671"
+ id="tspan4100"
+ sodipodi:role="line">Idle or</tspan><tspan
+ id="tspan4102"
+ y="1152.4579"
+ x="8168.2671"
+ sodipodi:role="line">offline?</tspan></text>
+ </g>
+ <g
+ id="g4114"
+ transform="translate(0,147.96969)">
+ <rect
+ id="rect6"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1475.6636"
+ width="4401.7612"
+ y="0"
+ x="0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110"
+ y="835.11212"
+ x="2206.4917"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="2206.4917"
+ id="tspan4112"
+ sodipodi:role="line">CPU N Start</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 4432.5052,897.4924 5684.8749,880.79414"
+ id="path4119"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 8503.0006,874.12161 9755.3703,857.42334"
+ id="path4119-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="8617.0977"
+ y="705.50983"
+ id="text4593"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595"
+ x="8617.0977"
+ y="705.50983">Y</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9"
+ transform="translate(9722.4732,131.27105)">
+ <rect
+ id="rect6-0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="0"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5"
+ y="835.11212"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="1460.1007"
+ id="tspan4112-9"
+ sodipodi:role="line">Done</tspan></text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-5"
+ transform="translate(0,3705.3456)">
+ <rect
+ id="rect6-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1475.6636"
+ width="4401.7612"
+ y="0"
+ x="0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-9"
+ y="835.11212"
+ x="2206.4917"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="2206.4917"
+ sodipodi:role="line"
+ id="tspan4776">Send IPI to CPU N</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 7102.5627,2263.5171 4430.8404,3682.8694"
+ id="path4119-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4104-1"
+ transform="translate(-1065.3349,6403.5782)">
+ <rect
+ transform="matrix(-0.70710678,0.70710678,-0.70710678,-0.70710678,0,0)"
+ y="-7383.8755"
+ x="-6124.8989"
+ height="1966.2251"
+ width="1953.6969"
+ id="rect3032-1-0-6"
+ style="fill:#96ff96;fill-opacity:1;stroke:#000000;stroke-width:45.00382233;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4098-3"
+ y="482.00006"
+ x="8168.2671"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ id="tspan4102-8"
+ y="482.00006"
+ x="8168.2671"
+ sodipodi:role="line">In RCU</tspan><tspan
+ y="816.05457"
+ x="8168.2671"
+ sodipodi:role="line"
+ id="tspan4833">read-side</tspan><tspan
+ y="1150.109"
+ x="8168.2671"
+ sodipodi:role="line"
+ id="tspan4835">critical</tspan><tspan
+ y="1484.1636"
+ x="8168.2671"
+ sodipodi:role="line"
+ id="tspan4837">section?</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:267.24362183px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6463.0864"
+ y="2285.6765"
+ id="text4593-0"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595-6"
+ x="6463.0864"
+ y="2285.6765">N</tspan></text>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654108, 80.17308215;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 2189.1897,5219.361 16.6983,1252.3697"
+ id="path4119-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-5-2"
+ transform="translate(0,6551.5479)">
+ <rect
+ id="rect6-1-7"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1475.6636"
+ width="4401.7612"
+ y="0"
+ x="0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-9-5"
+ y="835.11212"
+ x="2206.4917"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="2206.4917"
+ sodipodi:role="line"
+ id="tspan4776-5">IPI Handler</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="m 4432.5052,7297.9678 1252.3697,-16.6982"
+ id="path4119-2"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="m 8503.0013,7278.6595 1252.369,-16.6982"
+ id="path4119-8-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:267.24362183px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="8617.0977"
+ y="7110.0186"
+ id="text4593-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595-0"
+ x="8617.0977"
+ y="7110.0186">N</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3"
+ transform="translate(9722.4732,6535.809)">
+ <rect
+ id="rect6-0-7"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7"
+ y="503.71591"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="503.71591"
+ x="1460.1007"
+ id="tspan4112-9-0"
+ sodipodi:role="line">Report CPU</tspan><tspan
+ y="837.77039"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4923">Quiescent</tspan><tspan
+ y="1171.825"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925">State</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654335, 80.17308669;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 7102.5627,8725.7454 16.6983,1252.3697"
+ id="path4119-0-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:267.24362183px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6797.0522"
+ y="9018.6807"
+ id="text4593-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595-2"
+ x="6797.0522"
+ y="9018.6807">Y</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-8"
+ transform="translate(-80.17308,11381.108)">
+ <rect
+ id="rect6-0-7-5"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-6"
+ y="841.88086"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="841.88086"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-1">rcu_read_unlock()</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654562, 80.17309124;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 1362.6256,10071.26 16.6983,1252.369"
+ id="path4119-0-0-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 1362.6256,12883.919 16.6983,1252.369"
+ id="path4119-0-0-7-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-8-1"
+ transform="translate(9722.4732,11389.458)">
+ <rect
+ id="rect6-0-7-5-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-6-2"
+ y="841.88086"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="841.88086"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-1-2">Context Switch</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654789, 80.17309578;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 11165.272,10071.26 16.698,1252.369"
+ id="path4119-0-0-7-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-9"
+ transform="translate(-80.17308,14163.046)">
+ <rect
+ id="rect6-0-7-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-3"
+ y="503.71591"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="503.71591"
+ x="1460.1007"
+ id="tspan4112-9-0-4"
+ sodipodi:role="line">Report CPU</tspan><tspan
+ y="837.77039"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4923-3">and Task</tspan><tspan
+ y="1171.825"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-9">Quiescent States</tspan></text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-8-1-8"
+ transform="translate(5663.2978,11389.458)">
+ <rect
+ id="rect6-0-7-5-1-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-6-2-4"
+ y="841.88086"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="841.88086"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-1-2-4">Enqueue Task</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 9827.612,12141.988 8575.243,12125.29"
+ id="path4119-8-7-5"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 7106.0965,12818.962 16.6983,1252.369"
+ id="path4119-0-0-7-7-5"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-9-2"
+ transform="translate(5663.2978,14098.088)">
+ <rect
+ id="rect6-0-7-1-8"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-3-4"
+ y="503.71591"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="503.71591"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4923-3-2">Report CPU</tspan><tspan
+ y="837.77039"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-9-9">Quiescent</tspan><tspan
+ y="1171.825"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan5239">State</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654562, 80.17309124;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="M 5733.305,14095.542 2761.014,12809.774"
+ id="path4119-0-0-2"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654107, 80.17308214;stroke-dashoffset:0"
+ d="m 1353.3524,10079.499 9701.6916,0 100.189,-16.698"
+ id="path5265"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="ccc" />
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg
new file mode 100644
index 000000000000..6189ffcc6aff
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg
@@ -0,0 +1,830 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:39:46 2015 -->
+
+<!-- Magnification: 3.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="952.6817"
+ height="1425.6191"
+ viewBox="-66 -66 12729.905 19049.38"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="ExpSchedFlow.svg">
+ <metadata
+ id="metadata94">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs92">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path4146"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3852"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend-9"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3852-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-6"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-16"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-8"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-160"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-5"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-78"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-66"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-8"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-56"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-19"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-89"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-85"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-3"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-73"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-55"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-88"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-198"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-22"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker5072"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path5074"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-87"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-63"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-26"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path4146-51"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-58"
+ style="overflow:visible">
+ <path
+ id="path4146-61"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1090"
+ inkscape:window-height="1148"
+ id="namedview90"
+ showgrid="true"
+ inkscape:zoom="0.69092787"
+ inkscape:cx="476.34085"
+ inkscape:cy="712.80957"
+ inkscape:window-x="770"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4"
+ inkscape:snap-grids="false"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5"
+ fit-margin-left="5" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(23.312814,523.41265)">
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11475 2250 - 11475 3465-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11475 5625 - 11475 6840-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 7875 225 - 10665 225-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9675 675 - 7785 675-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9675 4725 - 10665 4725-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9225 5175 - 10665 5175-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 8775 11475 - 10665 11475-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11475 9000 - 11475 10215-->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <g
+ id="g4104"
+ transform="translate(-1068.9745,0)">
+ <rect
+ transform="matrix(-0.70710678,0.70710678,-0.70710678,-0.70710678,0,0)"
+ y="-7383.8755"
+ x="-6124.8989"
+ height="1966.2251"
+ width="1953.6969"
+ id="rect3032-1-0"
+ style="fill:#96ff96;fill-opacity:1;stroke:#000000;stroke-width:45.00382233;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4098"
+ y="818.40338"
+ x="8168.2671"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="818.40338"
+ x="8168.2671"
+ id="tspan4100"
+ sodipodi:role="line">Idle or</tspan><tspan
+ id="tspan4102"
+ y="1152.4579"
+ x="8168.2671"
+ sodipodi:role="line">offline?</tspan></text>
+ </g>
+ <g
+ id="g4114"
+ transform="translate(0,147.96969)">
+ <rect
+ id="rect6"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1475.6636"
+ width="4401.7612"
+ y="0"
+ x="0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110"
+ y="835.11212"
+ x="2206.4917"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="2206.4917"
+ id="tspan4112"
+ sodipodi:role="line">CPU N Start</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 4432.5052,897.4924 5684.8749,880.79414"
+ id="path4119"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 8503.0006,874.12161 9755.3703,857.42334"
+ id="path4119-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="8617.0977"
+ y="705.50983"
+ id="text4593"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595"
+ x="8617.0977"
+ y="705.50983">Y</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9"
+ transform="translate(9722.4732,131.27105)">
+ <rect
+ id="rect6-0"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="0"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5"
+ y="835.11212"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="1460.1007"
+ id="tspan4112-9"
+ sodipodi:role="line">Done</tspan></text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-5"
+ transform="translate(0,3705.3456)">
+ <rect
+ id="rect6-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1475.6636"
+ width="4401.7612"
+ y="0"
+ x="0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-9"
+ y="835.11212"
+ x="2206.4917"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="2206.4917"
+ sodipodi:role="line"
+ id="tspan4776">Send IPI to CPU N</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="M 7102.5627,2263.5171 4430.8404,3682.8694"
+ id="path4119-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4104-1"
+ transform="translate(-1065.3349,6403.5782)">
+ <rect
+ transform="matrix(-0.70710678,0.70710678,-0.70710678,-0.70710678,0,0)"
+ y="-7383.8755"
+ x="-6124.8989"
+ height="1966.2251"
+ width="1953.6969"
+ id="rect3032-1-0-6"
+ style="fill:#96ff96;fill-opacity:1;stroke:#000000;stroke-width:45.00382233;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4098-3"
+ y="985.4306"
+ x="8168.2671"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="985.4306"
+ x="8168.2671"
+ sodipodi:role="line"
+ id="tspan3109">CPU idle?</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:267.24362183px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6463.0864"
+ y="2285.6765"
+ id="text4593-0"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595-6"
+ x="6463.0864"
+ y="2285.6765">N</tspan></text>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654108, 80.17308215;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 2189.1897,5219.361 16.6983,1252.3697"
+ id="path4119-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-5-2"
+ transform="translate(0,6551.5479)">
+ <rect
+ id="rect6-1-7"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1475.6636"
+ width="4401.7612"
+ y="0"
+ x="0" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-9-5"
+ y="835.11212"
+ x="2206.4917"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="835.11212"
+ x="2206.4917"
+ sodipodi:role="line"
+ id="tspan4776-5">IPI Handler</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="m 4432.5052,7297.9678 1252.3697,-16.6982"
+ id="path4119-2"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow2Lend)"
+ d="m 8503.0013,7278.6595 1252.369,-16.6982"
+ id="path4119-8-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:267.24362183px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="8617.0977"
+ y="7110.0186"
+ id="text4593-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595-0"
+ x="8617.0977"
+ y="7110.0186">Y</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3"
+ transform="translate(9722.4732,6535.809)">
+ <rect
+ id="rect6-0-7"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7"
+ y="503.71591"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="503.71591"
+ x="1460.1007"
+ id="tspan4112-9-0"
+ sodipodi:role="line">Report CPU</tspan><tspan
+ y="837.77039"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4923">Quiescent</tspan><tspan
+ y="1171.825"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925">State</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654335, 80.17308669;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 7102.5627,11478.337 16.6983,1252.35"
+ id="path4119-0-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:267.24362183px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6797.0522"
+ y="9018.6807"
+ id="text4593-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4595-2"
+ x="6797.0522"
+ y="9018.6807">N</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-8"
+ transform="translate(-80.17308,14133.68)">
+ <rect
+ id="rect6-0-7-5"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-6"
+ y="841.88086"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="841.88086"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-1">Context Switch</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654562, 80.17309124;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 1362.6256,12823.832 16.6983,1252.369"
+ id="path4119-0-0-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 1362.6256,15636.491 16.6983,1252.369"
+ id="path4119-0-0-7-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-8-1"
+ transform="translate(9722.4732,14142.03)">
+ <rect
+ id="rect6-0-7-5-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-6-2"
+ y="841.88086"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="841.88086"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-1-2">CPU Offline</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654789, 80.17309578;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 11165.272,12823.832 16.698,1252.369"
+ id="path4119-0-0-7-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-9"
+ transform="translate(-80.17308,16915.618)">
+ <rect
+ id="rect6-0-7-1"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-3"
+ y="505.47754"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="505.47754"
+ x="1460.1007"
+ id="tspan4112-9-0-4"
+ sodipodi:role="line">Report CPU</tspan><tspan
+ y="839.53204"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-9">Quiescent</tspan><tspan
+ y="1173.5865"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan3168">State</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 11165.272,15571.534 16.698,1252.369"
+ id="path4119-0-0-7-7-5"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-9-2"
+ transform="translate(9722.4732,16850.66)">
+ <rect
+ id="rect6-0-7-1-8"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-3-4"
+ y="503.71591"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="503.71591"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4923-3-2">Report CPU</tspan><tspan
+ y="837.77039"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-9-9">Quiescent</tspan><tspan
+ y="1171.825"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan5239">State</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:40.08654107, 80.17308214;stroke-dashoffset:0"
+ d="m 1353.3524,12832.071 9701.6916,0 100.189,-16.698"
+ id="path5265"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="ccc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:40.08654022;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-end:url(#Arrow2Lend)"
+ d="m 7112.6465,8669.1867 16.6983,1252.369"
+ id="path4119-0-0-7-7-5-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4114-9-3-8-1-8-3"
+ transform="translate(5663.1399,9972.3627)">
+ <rect
+ id="rect6-0-7-5-1-1-9"
+ style="fill:#87cfff;stroke:#000000;stroke-width:45.00382233;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none"
+ rx="0"
+ height="1425.5687"
+ width="2748.6331"
+ y="29.467337"
+ x="80.17308" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text4110-5-7-6-2-4-0"
+ y="670.74316"
+ x="1460.1007"
+ style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="670.74316"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan4925-1-2-4-5">Request</tspan><tspan
+ y="1004.7976"
+ x="1460.1007"
+ sodipodi:role="line"
+ id="tspan3100">context switch</tspan></text>
+ </g>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
new file mode 100644
index 000000000000..414f8a2012d6
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
@@ -0,0 +1,521 @@
+=================================================
+A Tour Through TREE_RCU's Expedited Grace Periods
+=================================================
+
+Introduction
+============
+
+This document describes RCU's expedited grace periods.
+Unlike RCU's normal grace periods, which accept long latencies to attain
+high efficiency and minimal disturbance, expedited grace periods accept
+lower efficiency and significant disturbance to attain shorter latencies.
+
+There are two flavors of RCU (RCU-preempt and RCU-sched), with an earlier
+third RCU-bh flavor having been implemented in terms of the other two.
+Each of the two implementations is covered in its own section.
+
+Expedited Grace Period Design
+=============================
+
+The expedited RCU grace periods cannot be accused of being subtle,
+given that they for all intents and purposes hammer every CPU that
+has not yet provided a quiescent state for the current expedited
+grace period.
+The one saving grace is that the hammer has grown a bit smaller
+over time: The old call to ``try_stop_cpus()`` has been
+replaced with a set of calls to ``smp_call_function_single()``,
+each of which results in an IPI to the target CPU.
+The corresponding handler function checks the CPU's state, motivating
+a faster quiescent state where possible, and triggering a report
+of that quiescent state.
+As always for RCU, once everything has spent some time in a quiescent
+state, the expedited grace period has completed.
+
+The details of the ``smp_call_function_single()`` handler's
+operation depend on the RCU flavor, as described in the following
+sections.
+
+RCU-preempt Expedited Grace Periods
+===================================
+
+``CONFIG_PREEMPTION=y`` kernels implement RCU-preempt.
+The overall flow of the handling of a given CPU by an RCU-preempt
+expedited grace period is shown in the following diagram:
+
+.. kernel-figure:: ExpRCUFlow.svg
+
+The solid arrows denote direct action, for example, a function call.
+The dotted arrows denote indirect action, for example, an IPI
+or a state that is reached after some time.
+
+If a given CPU is offline or idle, ``synchronize_rcu_expedited()``
+will ignore it because idle and offline CPUs are already residing
+in quiescent states.
+Otherwise, the expedited grace period will use
+``smp_call_function_single()`` to send the CPU an IPI, which
+is handled by ``rcu_exp_handler()``.
+
+However, because this is preemptible RCU, ``rcu_exp_handler()``
+can check to see if the CPU is currently running in an RCU read-side
+critical section.
+If not, the handler can immediately report a quiescent state.
+Otherwise, it sets flags so that the outermost ``rcu_read_unlock()``
+invocation will provide the needed quiescent-state report.
+This flag-setting avoids the previous forced preemption of all
+CPUs that might have RCU read-side critical sections.
+In addition, this flag-setting is done so as to avoid increasing
+the overhead of the common-case fastpath through the scheduler.
+
+Again because this is preemptible RCU, an RCU read-side critical section
+can be preempted.
+When that happens, RCU will enqueue the task, which will the continue to
+block the current expedited grace period until it resumes and finds its
+outermost ``rcu_read_unlock()``.
+The CPU will report a quiescent state just after enqueuing the task because
+the CPU is no longer blocking the grace period.
+It is instead the preempted task doing the blocking.
+The list of blocked tasks is managed by ``rcu_preempt_ctxt_queue()``,
+which is called from ``rcu_preempt_note_context_switch()``, which
+in turn is called from ``rcu_note_context_switch()``, which in
+turn is called from the scheduler.
+
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why not just have the expedited grace period check the state of all |
+| the CPUs? After all, that would avoid all those real-time-unfriendly |
+| IPIs. |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because we want the RCU read-side critical sections to run fast, |
+| which means no memory barriers. Therefore, it is not possible to |
+| safely check the state from some other CPU. And even if it was |
+| possible to safely check the state, it would still be necessary to |
+| IPI the CPU to safely interact with the upcoming |
+| ``rcu_read_unlock()`` invocation, which means that the remote state |
+| testing would not help the worst-case latency that real-time |
+| applications care about. |
+| |
+| One way to prevent your real-time application from getting hit with |
+| these IPIs is to build your kernel with ``CONFIG_NO_HZ_FULL=y``. RCU |
+| would then perceive the CPU running your application as being idle, |
+| and it would be able to safely detect that state without needing to |
+| IPI the CPU. |
++-----------------------------------------------------------------------+
+
+Please note that this is just the overall flow: Additional complications
+can arise due to races with CPUs going idle or offline, among other
+things.
+
+RCU-sched Expedited Grace Periods
+---------------------------------
+
+``CONFIG_PREEMPTION=n`` kernels implement RCU-sched. The overall flow of
+the handling of a given CPU by an RCU-sched expedited grace period is
+shown in the following diagram:
+
+.. kernel-figure:: ExpSchedFlow.svg
+
+As with RCU-preempt, RCU-sched's ``synchronize_rcu_expedited()`` ignores
+offline and idle CPUs, again because they are in remotely detectable
+quiescent states. However, because the ``rcu_read_lock_sched()`` and
+``rcu_read_unlock_sched()`` leave no trace of their invocation, in
+general it is not possible to tell whether or not the current CPU is in
+an RCU read-side critical section. The best that RCU-sched's
+``rcu_exp_handler()`` can do is to check for idle, on the off-chance
+that the CPU went idle while the IPI was in flight. If the CPU is idle,
+then ``rcu_exp_handler()`` reports the quiescent state.
+
+Otherwise, the handler forces a future context switch by setting the
+NEED_RESCHED flag of the current task's thread flag and the CPU preempt
+counter. At the time of the context switch, the CPU reports the
+quiescent state. Should the CPU go offline first, it will report the
+quiescent state at that time.
+
+Expedited Grace Period and CPU Hotplug
+--------------------------------------
+
+The expedited nature of expedited grace periods require a much tighter
+interaction with CPU hotplug operations than is required for normal
+grace periods. In addition, attempting to IPI offline CPUs will result
+in splats, but failing to IPI online CPUs can result in too-short grace
+periods. Neither option is acceptable in production kernels.
+
+The interaction between expedited grace periods and CPU hotplug
+operations is carried out at several levels:
+
+#. The number of CPUs that have ever been online is tracked by the
+ ``rcu_state`` structure's ``->ncpus`` field. The ``rcu_state``
+ structure's ``->ncpus_snap`` field tracks the number of CPUs that
+ have ever been online at the beginning of an RCU expedited grace
+ period. Note that this number never decreases, at least in the
+ absence of a time machine.
+#. The identities of the CPUs that have ever been online is tracked by
+ the ``rcu_node`` structure's ``->expmaskinitnext`` field. The
+ ``rcu_node`` structure's ``->expmaskinit`` field tracks the
+ identities of the CPUs that were online at least once at the
+ beginning of the most recent RCU expedited grace period. The
+ ``rcu_state`` structure's ``->ncpus`` and ``->ncpus_snap`` fields are
+ used to detect when new CPUs have come online for the first time,
+ that is, when the ``rcu_node`` structure's ``->expmaskinitnext``
+ field has changed since the beginning of the last RCU expedited grace
+ period, which triggers an update of each ``rcu_node`` structure's
+ ``->expmaskinit`` field from its ``->expmaskinitnext`` field.
+#. Each ``rcu_node`` structure's ``->expmaskinit`` field is used to
+ initialize that structure's ``->expmask`` at the beginning of each
+ RCU expedited grace period. This means that only those CPUs that have
+ been online at least once will be considered for a given grace
+ period.
+#. Any CPU that goes offline will clear its bit in its leaf ``rcu_node``
+ structure's ``->qsmaskinitnext`` field, so any CPU with that bit
+ clear can safely be ignored. However, it is possible for a CPU coming
+ online or going offline to have this bit set for some time while
+ ``cpu_online`` returns ``false``.
+#. For each non-idle CPU that RCU believes is currently online, the
+ grace period invokes ``smp_call_function_single()``. If this
+ succeeds, the CPU was fully online. Failure indicates that the CPU is
+ in the process of coming online or going offline, in which case it is
+ necessary to wait for a short time period and try again. The purpose
+ of this wait (or series of waits, as the case may be) is to permit a
+ concurrent CPU-hotplug operation to complete.
+#. In the case of RCU-sched, one of the last acts of an outgoing CPU is
+ to invoke ``rcutree_report_cpu_dead()``, which reports a quiescent state for
+ that CPU. However, this is likely paranoia-induced redundancy.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why all the dancing around with multiple counters and masks tracking |
+| CPUs that were once online? Why not just have a single set of masks |
+| tracking the currently online CPUs and be done with it? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Maintaining single set of masks tracking the online CPUs *sounds* |
+| easier, at least until you try working out all the race conditions |
+| between grace-period initialization and CPU-hotplug operations. For |
+| example, suppose initialization is progressing down the tree while a |
+| CPU-offline operation is progressing up the tree. This situation can |
+| result in bits set at the top of the tree that have no counterparts |
+| at the bottom of the tree. Those bits will never be cleared, which |
+| will result in grace-period hangs. In short, that way lies madness, |
+| to say nothing of a great many bugs, hangs, and deadlocks. |
+| In contrast, the current multi-mask multi-counter scheme ensures that |
+| grace-period initialization will always see consistent masks up and |
+| down the tree, which brings significant simplifications over the |
+| single-mask method. |
+| |
+| This is an instance of `deferring work in order to avoid |
+| synchronization <http://www.cs.columbia.edu/~library/TR-repository/re |
+| ports/reports-1992/cucs-039-92.ps.gz>`__. |
+| Lazily recording CPU-hotplug events at the beginning of the next |
+| grace period greatly simplifies maintenance of the CPU-tracking |
+| bitmasks in the ``rcu_node`` tree. |
++-----------------------------------------------------------------------+
+
+Expedited Grace Period Refinements
+----------------------------------
+
+Idle-CPU Checks
+~~~~~~~~~~~~~~~
+
+Each expedited grace period checks for idle CPUs when initially forming
+the mask of CPUs to be IPIed and again just before IPIing a CPU (both
+checks are carried out by ``sync_rcu_exp_select_cpus()``). If the CPU is
+idle at any time between those two times, the CPU will not be IPIed.
+Instead, the task pushing the grace period forward will include the idle
+CPUs in the mask passed to ``rcu_report_exp_cpu_mult()``.
+
+For RCU-sched, there is an additional check: If the IPI has interrupted
+the idle loop, then ``rcu_exp_handler()`` invokes
+``rcu_report_exp_rdp()`` to report the corresponding quiescent state.
+
+For RCU-preempt, there is no specific check for idle in the IPI handler
+(``rcu_exp_handler()``), but because RCU read-side critical sections are
+not permitted within the idle loop, if ``rcu_exp_handler()`` sees that
+the CPU is within RCU read-side critical section, the CPU cannot
+possibly be idle. Otherwise, ``rcu_exp_handler()`` invokes
+``rcu_report_exp_rdp()`` to report the corresponding quiescent state,
+regardless of whether or not that quiescent state was due to the CPU
+being idle.
+
+In summary, RCU expedited grace periods check for idle when building the
+bitmask of CPUs that must be IPIed, just before sending each IPI, and
+(either explicitly or implicitly) within the IPI handler.
+
+Batching via Sequence Counter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If each grace-period request was carried out separately, expedited grace
+periods would have abysmal scalability and problematic high-load
+characteristics. Because each grace-period operation can serve an
+unlimited number of updates, it is important to *batch* requests, so
+that a single expedited grace-period operation will cover all requests
+in the corresponding batch.
+
+This batching is controlled by a sequence counter named
+``->expedited_sequence`` in the ``rcu_state`` structure. This counter
+has an odd value when there is an expedited grace period in progress and
+an even value otherwise, so that dividing the counter value by two gives
+the number of completed grace periods. During any given update request,
+the counter must transition from even to odd and then back to even, thus
+indicating that a grace period has elapsed. Therefore, if the initial
+value of the counter is ``s``, the updater must wait until the counter
+reaches at least the value ``(s+3)&~0x1``. This counter is managed by
+the following access functions:
+
+#. ``rcu_exp_gp_seq_start()``, which marks the start of an expedited
+ grace period.
+#. ``rcu_exp_gp_seq_end()``, which marks the end of an expedited grace
+ period.
+#. ``rcu_exp_gp_seq_snap()``, which obtains a snapshot of the counter.
+#. ``rcu_exp_gp_seq_done()``, which returns ``true`` if a full expedited
+ grace period has elapsed since the corresponding call to
+ ``rcu_exp_gp_seq_snap()``.
+
+Again, only one request in a given batch need actually carry out a
+grace-period operation, which means there must be an efficient way to
+identify which of many concurrent requests will initiate the grace
+period, and that there be an efficient way for the remaining requests to
+wait for that grace period to complete. However, that is the topic of
+the next section.
+
+Funnel Locking and Wait/Wakeup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The natural way to sort out which of a batch of updaters will initiate
+the expedited grace period is to use the ``rcu_node`` combining tree, as
+implemented by the ``exp_funnel_lock()`` function. The first updater
+corresponding to a given grace period arriving at a given ``rcu_node``
+structure records its desired grace-period sequence number in the
+``->exp_seq_rq`` field and moves up to the next level in the tree.
+Otherwise, if the ``->exp_seq_rq`` field already contains the sequence
+number for the desired grace period or some later one, the updater
+blocks on one of four wait queues in the ``->exp_wq[]`` array, using the
+second-from-bottom and third-from bottom bits as an index. An
+``->exp_lock`` field in the ``rcu_node`` structure synchronizes access
+to these fields.
+
+An empty ``rcu_node`` tree is shown in the following diagram, with the
+white cells representing the ``->exp_seq_rq`` field and the red cells
+representing the elements of the ``->exp_wq[]`` array.
+
+.. kernel-figure:: Funnel0.svg
+
+The next diagram shows the situation after the arrival of Task A and
+Task B at the leftmost and rightmost leaf ``rcu_node`` structures,
+respectively. The current value of the ``rcu_state`` structure's
+``->expedited_sequence`` field is zero, so adding three and clearing the
+bottom bit results in the value two, which both tasks record in the
+``->exp_seq_rq`` field of their respective ``rcu_node`` structures:
+
+.. kernel-figure:: Funnel1.svg
+
+Each of Tasks A and B will move up to the root ``rcu_node`` structure.
+Suppose that Task A wins, recording its desired grace-period sequence
+number and resulting in the state shown below:
+
+.. kernel-figure:: Funnel2.svg
+
+Task A now advances to initiate a new grace period, while Task B moves
+up to the root ``rcu_node`` structure, and, seeing that its desired
+sequence number is already recorded, blocks on ``->exp_wq[1]``.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why ``->exp_wq[1]``? Given that the value of these tasks' desired |
+| sequence number is two, so shouldn't they instead block on |
+| ``->exp_wq[2]``? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| No. |
+| Recall that the bottom bit of the desired sequence number indicates |
+| whether or not a grace period is currently in progress. It is |
+| therefore necessary to shift the sequence number right one bit |
+| position to obtain the number of the grace period. This results in |
+| ``->exp_wq[1]``. |
++-----------------------------------------------------------------------+
+
+If Tasks C and D also arrive at this point, they will compute the same
+desired grace-period sequence number, and see that both leaf
+``rcu_node`` structures already have that value recorded. They will
+therefore block on their respective ``rcu_node`` structures'
+``->exp_wq[1]`` fields, as shown below:
+
+.. kernel-figure:: Funnel3.svg
+
+Task A now acquires the ``rcu_state`` structure's ``->exp_mutex`` and
+initiates the grace period, which increments ``->expedited_sequence``.
+Therefore, if Tasks E and F arrive, they will compute a desired sequence
+number of 4 and will record this value as shown below:
+
+.. kernel-figure:: Funnel4.svg
+
+Tasks E and F will propagate up the ``rcu_node`` combining tree, with
+Task F blocking on the root ``rcu_node`` structure and Task E wait for
+Task A to finish so that it can start the next grace period. The
+resulting state is as shown below:
+
+.. kernel-figure:: Funnel5.svg
+
+Once the grace period completes, Task A starts waking up the tasks
+waiting for this grace period to complete, increments the
+``->expedited_sequence``, acquires the ``->exp_wake_mutex`` and then
+releases the ``->exp_mutex``. This results in the following state:
+
+.. kernel-figure:: Funnel6.svg
+
+Task E can then acquire ``->exp_mutex`` and increment
+``->expedited_sequence`` to the value three. If new tasks G and H arrive
+and moves up the combining tree at the same time, the state will be as
+follows:
+
+.. kernel-figure:: Funnel7.svg
+
+Note that three of the root ``rcu_node`` structure's waitqueues are now
+occupied. However, at some point, Task A will wake up the tasks blocked
+on the ``->exp_wq`` waitqueues, resulting in the following state:
+
+.. kernel-figure:: Funnel8.svg
+
+Execution will continue with Tasks E and H completing their grace
+periods and carrying out their wakeups.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| What happens if Task A takes so long to do its wakeups that Task E's |
+| grace period completes? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Then Task E will block on the ``->exp_wake_mutex``, which will also |
+| prevent it from releasing ``->exp_mutex``, which in turn will prevent |
+| the next grace period from starting. This last is important in |
+| preventing overflow of the ``->exp_wq[]`` array. |
++-----------------------------------------------------------------------+
+
+Use of Workqueues
+~~~~~~~~~~~~~~~~~
+
+In earlier implementations, the task requesting the expedited grace
+period also drove it to completion. This straightforward approach had
+the disadvantage of needing to account for POSIX signals sent to user
+tasks, so more recent implementations use the Linux kernel's
+workqueues (see Documentation/core-api/workqueue.rst).
+
+The requesting task still does counter snapshotting and funnel-lock
+processing, but the task reaching the top of the funnel lock does a
+``schedule_work()`` (from ``_synchronize_rcu_expedited()`` so that a
+workqueue kthread does the actual grace-period processing. Because
+workqueue kthreads do not accept POSIX signals, grace-period-wait
+processing need not allow for POSIX signals. In addition, this approach
+allows wakeups for the previous expedited grace period to be overlapped
+with processing for the next expedited grace period. Because there are
+only four sets of waitqueues, it is necessary to ensure that the
+previous grace period's wakeups complete before the next grace period's
+wakeups start. This is handled by having the ``->exp_mutex`` guard
+expedited grace-period processing and the ``->exp_wake_mutex`` guard
+wakeups. The key point is that the ``->exp_mutex`` is not released until
+the first wakeup is complete, which means that the ``->exp_wake_mutex``
+has already been acquired at that point. This approach ensures that the
+previous grace period's wakeups can be carried out while the current
+grace period is in process, but that these wakeups will complete before
+the next grace period starts. This means that only three waitqueues are
+required, guaranteeing that the four that are provided are sufficient.
+
+Stall Warnings
+~~~~~~~~~~~~~~
+
+Expediting grace periods does nothing to speed things up when RCU
+readers take too long, and therefore expedited grace periods check for
+stalls just as normal grace periods do.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But why not just let the normal grace-period machinery detect the |
+| stalls, given that a given reader must block both normal and |
+| expedited grace periods? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because it is quite possible that at a given time there is no normal |
+| grace period in progress, in which case the normal grace period |
+| cannot emit a stall warning. |
++-----------------------------------------------------------------------+
+
+The ``synchronize_sched_expedited_wait()`` function loops waiting for
+the expedited grace period to end, but with a timeout set to the current
+RCU CPU stall-warning time. If this time is exceeded, any CPUs or
+``rcu_node`` structures blocking the current grace period are printed.
+Each stall warning results in another pass through the loop, but the
+second and subsequent passes use longer stall times.
+
+Mid-boot operation
+~~~~~~~~~~~~~~~~~~
+
+The use of workqueues has the advantage that the expedited grace-period
+code need not worry about POSIX signals. Unfortunately, it has the
+corresponding disadvantage that workqueues cannot be used until they are
+initialized, which does not happen until some time after the scheduler
+spawns the first task. Given that there are parts of the kernel that
+really do want to execute grace periods during this mid-boot “dead
+zone”, expedited grace periods must do something else during this time.
+
+What they do is to fall back to the old practice of requiring that the
+requesting task drive the expedited grace period, as was the case before
+the use of workqueues. However, the requesting task is only required to
+drive the grace period during the mid-boot dead zone. Before mid-boot, a
+synchronous grace period is a no-op. Some time after mid-boot,
+workqueues are used.
+
+Non-expedited non-SRCU synchronous grace periods must also operate
+normally during mid-boot. This is handled by causing non-expedited grace
+periods to take the expedited code path during mid-boot.
+
+The current code assumes that there are no POSIX signals during the
+mid-boot dead zone. However, if an overwhelming need for POSIX signals
+somehow arises, appropriate adjustments can be made to the expedited
+stall-warning code. One such adjustment would reinstate the
+pre-workqueue stall-warning checks, but only during the mid-boot dead
+zone.
+
+With this refinement, synchronous grace periods can now be used from
+task context pretty much any time during the life of the kernel. That
+is, aside from some points in the suspend, hibernate, or shutdown code
+path.
+
+Summary
+~~~~~~~
+
+Expedited grace periods use a sequence-number approach to promote
+batching, so that a single grace-period operation can serve numerous
+requests. A funnel lock is used to efficiently identify the one task out
+of a concurrent group that will request the grace period. All members of
+the group will block on waitqueues provided in the ``rcu_node``
+structure. The actual grace-period processing is carried out by a
+workqueue.
+
+CPU-hotplug operations are noted lazily in order to prevent the need for
+tight synchronization between expedited grace periods and CPU-hotplug
+operations. The dyntick-idle counters are used to avoid sending IPIs to
+idle CPUs, at least in the common case. RCU-preempt and RCU-sched use
+different IPI handlers and different code to respond to the state
+changes carried out by those handlers, but otherwise use common code.
+
+Quiescent states are tracked using the ``rcu_node`` tree, and once all
+necessary quiescent states have been reported, all tasks waiting on this
+expedited grace period are awakened. A pair of mutexes are used to allow
+one grace period's wakeups to proceed concurrently with the next grace
+period's processing.
+
+This combination of mechanisms allows expedited grace periods to run
+reasonably efficiently. However, for non-time-critical tasks, normal
+grace periods should be used instead because their longer duration
+permits much higher degrees of batching, and thus much lower per-request
+overheads.
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg
new file mode 100644
index 000000000000..16b1ff0ad38c
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel0.svg
@@ -0,0 +1,275 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel0.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="201.06495"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="171"
+ inkscape:window-y="279"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 0</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.45404"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="145.45404"
+ y="360.25174"
+ style="font-size:10px">:0</tspan></text>
+ </g>
+ <g
+ id="g3997-7"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.45404"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.45404"
+ y="360.25174"
+ style="font-size:10px">:0</tspan></text>
+ </g>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg
new file mode 100644
index 000000000000..684a4b969725
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel1.svg
@@ -0,0 +1,275 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel1.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="201.06495"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="g3997-7"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="363"
+ inkscape:window-y="336"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 0</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">A:2</tspan></text>
+ </g>
+ <g
+ id="g3997-7"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">B:2</tspan></text>
+ </g>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg
new file mode 100644
index 000000000000..8fb2454d9544
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel2.svg
@@ -0,0 +1,287 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel2.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="g3997-7"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="363"
+ inkscape:window-y="336"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 0</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">:2</tspan></text>
+ </g>
+ <g
+ id="g3997-7"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">B:2</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">A:2</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg
new file mode 100644
index 000000000000..5d4f22d5662c
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel3.svg
@@ -0,0 +1,323 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel3.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="68"
+ inkscape:window-y="180"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 0 GP: A</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">:2</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.51051"
+ y="360.18094"
+ id="text3013-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6"
+ x="232.51051"
+ y="360.18094"
+ style="font-size:10px">C</tspan></text>
+ </g>
+ <g
+ id="g3019"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">:2</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.31764"
+ y="360.18582"
+ id="text3013-3-3-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6-5"
+ x="232.31764"
+ y="360.18582"
+ style="font-size:10px">D</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">:2</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="361.97092"
+ y="291.88705"
+ id="text3013-3-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7"
+ x="361.97092"
+ y="291.88705"
+ style="font-size:10px">B</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg
new file mode 100644
index 000000000000..b89b02869914
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel4.svg
@@ -0,0 +1,323 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel4.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="68"
+ inkscape:window-y="180"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 1 GP: A</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">E:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.51051"
+ y="360.18094"
+ id="text3013-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6"
+ x="232.51051"
+ y="360.18094"
+ style="font-size:10px">C</tspan></text>
+ </g>
+ <g
+ id="g3019"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">F:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.31764"
+ y="360.18582"
+ id="text3013-3-3-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6-5"
+ x="232.31764"
+ y="360.18582"
+ style="font-size:10px">D</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">:2</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="361.97092"
+ y="291.88705"
+ id="text3013-3-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7"
+ x="361.97092"
+ y="291.88705"
+ style="font-size:10px">B</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg
new file mode 100644
index 000000000000..90f1c77bea2f
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel5.svg
@@ -0,0 +1,335 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel5.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="68"
+ inkscape:window-y="180"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 1 GP: A,E</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.51051"
+ y="360.18094"
+ id="text3013-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6"
+ x="232.51051"
+ y="360.18094"
+ style="font-size:10px">C</tspan></text>
+ </g>
+ <g
+ id="g3019"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.31764"
+ y="360.18582"
+ id="text3013-3-3-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6-5"
+ x="232.31764"
+ y="360.18582"
+ style="font-size:10px">D</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="361.97092"
+ y="291.88705"
+ id="text3013-3-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7"
+ x="361.97092"
+ y="291.88705"
+ style="font-size:10px">B</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="405.40396"
+ y="291.88705"
+ id="text3013-3-36-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7-6"
+ x="405.40396"
+ y="291.88705"
+ style="font-size:10px">F</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg
new file mode 100644
index 000000000000..3e5651da031a
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel6.svg
@@ -0,0 +1,335 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel6.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="68"
+ inkscape:window-y="180"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 2 GP: E Wakeup: A</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.51051"
+ y="360.18094"
+ id="text3013-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6"
+ x="232.51051"
+ y="360.18094"
+ style="font-size:10px">C</tspan></text>
+ </g>
+ <g
+ id="g3019"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.31764"
+ y="360.18582"
+ id="text3013-3-3-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6-5"
+ x="232.31764"
+ y="360.18582"
+ style="font-size:10px">D</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="361.97092"
+ y="291.88705"
+ id="text3013-3-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7"
+ x="361.97092"
+ y="291.88705"
+ style="font-size:10px">B</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="405.40396"
+ y="291.88705"
+ id="text3013-3-36-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7-6"
+ x="405.40396"
+ y="291.88705"
+ style="font-size:10px">F</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg
new file mode 100644
index 000000000000..9483f08d345e
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel7.svg
@@ -0,0 +1,347 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel7.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="68"
+ inkscape:window-y="180"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 3 GP: E,H Wakeup: A</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">:4</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.51051"
+ y="360.18094"
+ id="text3013-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6"
+ x="232.51051"
+ y="360.18094"
+ style="font-size:10px">C</tspan></text>
+ </g>
+ <g
+ id="g3019"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">:6</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="232.31764"
+ y="360.18582"
+ id="text3013-3-3-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-6-5"
+ x="232.31764"
+ y="360.18582"
+ style="font-size:10px">D</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">:6</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="361.97092"
+ y="291.88705"
+ id="text3013-3-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7"
+ x="361.97092"
+ y="291.88705"
+ style="font-size:10px">B</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="405.40396"
+ y="291.88705"
+ id="text3013-3-36-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7-6"
+ x="405.40396"
+ y="291.88705"
+ style="font-size:10px">F</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="449.22031"
+ y="291.88217"
+ id="text3013-3-36-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7-6-6"
+ x="449.22031"
+ y="291.88217"
+ style="font-size:10px">G</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg
new file mode 100644
index 000000000000..1101ec30e604
--- /dev/null
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Funnel8.svg
@@ -0,0 +1,311 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="490.05093"
+ height="125.78741"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="Funnel8.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="114.01552"
+ inkscape:cy="-86.548414"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="68"
+ inkscape:window-y="180"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-117.08462,-249.92053)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="362.371"
+ y="262.51819"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="362.371"
+ y="262.51819">-&gt;expedited_sequence: 3 GP: E,H</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101"
+ width="43.158947"
+ height="26.33428"
+ x="253.55223"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3"
+ width="43.158947"
+ height="26.33428"
+ x="297.04141"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect3101-3-6"
+ width="43.158947"
+ height="26.33428"
+ x="427.509"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7"
+ width="43.158947"
+ height="26.33428"
+ x="384.01981"
+ y="275.07489" />
+ <rect
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1"
+ id="rect3101-3-6-7-5"
+ width="43.158947"
+ height="26.33428"
+ x="340.53061"
+ y="275.07489" />
+ <g
+ id="g3997"
+ transform="translate(-0.87295532,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2"
+ style="fill:#ff8282;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;fill-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="146.00092"
+ y="360.25174"
+ id="text3013"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015"
+ x="146.00092"
+ y="360.25174"
+ style="font-size:10px">:4</tspan></text>
+ </g>
+ <g
+ id="g3019"
+ transform="translate(260.06223,0)">
+ <rect
+ y="343.37366"
+ x="123.95757"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-35-0"
+ style="fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="167.44673"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-62-9"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="297.91437"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-9-3"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="254.42516"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-1-6"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <rect
+ y="343.37366"
+ x="210.93593"
+ height="26.33428"
+ width="43.158947"
+ id="rect3101-3-6-7-5-2-0"
+ style="fill:#ff8282;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="145.54926"
+ y="360.25174"
+ id="text3013-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6"
+ x="145.54926"
+ y="360.25174"
+ style="font-size:10px">:6</tspan></text>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="275.59558"
+ y="291.95297"
+ id="text3013-36"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-7"
+ x="275.59558"
+ y="291.95297"
+ style="font-size:10px">:6</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="405.40396"
+ y="291.88705"
+ id="text3013-3-36-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7-6"
+ x="405.40396"
+ y="291.88705"
+ style="font-size:10px">F</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:20px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="449.22031"
+ y="291.88217"
+ id="text3013-3-36-3-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3015-6-7-6-6"
+ x="449.22031"
+ y="291.88217"
+ style="font-size:10px">G</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
new file mode 100644
index 000000000000..1a5ff1a9f02e
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
@@ -0,0 +1,648 @@
+======================================================
+A Tour Through TREE_RCU's Grace-Period Memory Ordering
+======================================================
+
+August 8, 2017
+
+This article was contributed by Paul E. McKenney
+
+Introduction
+============
+
+This document gives a rough visual overview of how Tree RCU's
+grace-period memory ordering guarantee is provided.
+
+What Is Tree RCU's Grace Period Memory Ordering Guarantee?
+==========================================================
+
+RCU grace periods provide extremely strong memory-ordering guarantees
+for non-idle non-offline code.
+Any code that happens after the end of a given RCU grace period is guaranteed
+to see the effects of all accesses prior to the beginning of that grace
+period that are within RCU read-side critical sections.
+Similarly, any code that happens before the beginning of a given RCU grace
+period is guaranteed to not see the effects of all accesses following the end
+of that grace period that are within RCU read-side critical sections.
+
+Note well that RCU-sched read-side critical sections include any region
+of code for which preemption is disabled.
+Given that each individual machine instruction can be thought of as
+an extremely small region of preemption-disabled code, one can think of
+``synchronize_rcu()`` as ``smp_mb()`` on steroids.
+
+RCU updaters use this guarantee by splitting their updates into
+two phases, one of which is executed before the grace period and
+the other of which is executed after the grace period.
+In the most common use case, phase one removes an element from
+a linked RCU-protected data structure, and phase two frees that element.
+For this to work, any readers that have witnessed state prior to the
+phase-one update (in the common case, removal) must not witness state
+following the phase-two update (in the common case, freeing).
+
+The RCU implementation provides this guarantee using a network
+of lock-based critical sections, memory barriers, and per-CPU
+processing, as is described in the following sections.
+
+Tree RCU Grace Period Memory Ordering Building Blocks
+=====================================================
+
+The workhorse for RCU's grace-period memory ordering is the
+critical section for the ``rcu_node`` structure's
+``->lock``. These critical sections use helper functions for lock
+acquisition, including ``raw_spin_lock_rcu_node()``,
+``raw_spin_lock_irq_rcu_node()``, and ``raw_spin_lock_irqsave_rcu_node()``.
+Their lock-release counterparts are ``raw_spin_unlock_rcu_node()``,
+``raw_spin_unlock_irq_rcu_node()``, and
+``raw_spin_unlock_irqrestore_rcu_node()``, respectively.
+For completeness, a ``raw_spin_trylock_rcu_node()`` is also provided.
+The key point is that the lock-acquisition functions, including
+``raw_spin_trylock_rcu_node()``, all invoke ``smp_mb__after_unlock_lock()``
+immediately after successful acquisition of the lock.
+
+Therefore, for any given ``rcu_node`` structure, any access
+happening before one of the above lock-release functions will be seen
+by all CPUs as happening before any access happening after a later
+one of the above lock-acquisition functions.
+Furthermore, any access happening before one of the
+above lock-release function on any given CPU will be seen by all
+CPUs as happening before any access happening after a later one
+of the above lock-acquisition functions executing on that same CPU,
+even if the lock-release and lock-acquisition functions are operating
+on different ``rcu_node`` structures.
+Tree RCU uses these two ordering guarantees to form an ordering
+network among all CPUs that were in any way involved in the grace
+period, including any CPUs that came online or went offline during
+the grace period in question.
+
+The following litmus test exhibits the ordering effects of these
+lock-acquisition and lock-release functions::
+
+ 1 int x, y, z;
+ 2
+ 3 void task0(void)
+ 4 {
+ 5 raw_spin_lock_rcu_node(rnp);
+ 6 WRITE_ONCE(x, 1);
+ 7 r1 = READ_ONCE(y);
+ 8 raw_spin_unlock_rcu_node(rnp);
+ 9 }
+ 10
+ 11 void task1(void)
+ 12 {
+ 13 raw_spin_lock_rcu_node(rnp);
+ 14 WRITE_ONCE(y, 1);
+ 15 r2 = READ_ONCE(z);
+ 16 raw_spin_unlock_rcu_node(rnp);
+ 17 }
+ 18
+ 19 void task2(void)
+ 20 {
+ 21 WRITE_ONCE(z, 1);
+ 22 smp_mb();
+ 23 r3 = READ_ONCE(x);
+ 24 }
+ 25
+ 26 WARN_ON(r1 == 0 && r2 == 0 && r3 == 0);
+
+The ``WARN_ON()`` is evaluated at "the end of time",
+after all changes have propagated throughout the system.
+Without the ``smp_mb__after_unlock_lock()`` provided by the
+acquisition functions, this ``WARN_ON()`` could trigger, for example
+on PowerPC.
+The ``smp_mb__after_unlock_lock()`` invocations prevent this
+``WARN_ON()`` from triggering.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But the chain of rcu_node-structure lock acquisitions guarantees |
+| that new readers will see all of the updater's pre-grace-period |
+| accesses and also guarantees that the updater's post-grace-period |
+| accesses will see all of the old reader's accesses. So why do we |
+| need all of those calls to smp_mb__after_unlock_lock()? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because we must provide ordering for RCU's polling grace-period |
+| primitives, for example, get_state_synchronize_rcu() and |
+| poll_state_synchronize_rcu(). Consider this code:: |
+| |
+| CPU 0 CPU 1 |
+| ---- ---- |
+| WRITE_ONCE(X, 1) WRITE_ONCE(Y, 1) |
+| g = get_state_synchronize_rcu() smp_mb() |
+| while (!poll_state_synchronize_rcu(g)) r1 = READ_ONCE(X) |
+| continue; |
+| r0 = READ_ONCE(Y) |
+| |
+| RCU guarantees that the outcome r0 == 0 && r1 == 0 will not |
+| happen, even if CPU 1 is in an RCU extended quiescent state |
+| (idle or offline) and thus won't interact directly with the RCU |
+| core processing at all. |
++-----------------------------------------------------------------------+
+
+This approach must be extended to include idle CPUs, which need
+RCU's grace-period memory ordering guarantee to extend to any
+RCU read-side critical sections preceding and following the current
+idle sojourn.
+This case is handled by calls to the strongly ordered
+``atomic_add_return()`` read-modify-write atomic operation that
+is invoked within ``ct_kernel_exit_state()`` at idle-entry
+time and within ``ct_kernel_enter_state()`` at idle-exit time.
+The grace-period kthread invokes first ``ct_rcu_watching_cpu_acquire()``
+(preceded by a full memory barrier) and ``rcu_watching_snap_stopped_since()``
+(both of which rely on acquire semantics) to detect idle CPUs.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But what about CPUs that remain offline for the entire grace period? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Such CPUs will be offline at the beginning of the grace period, so |
+| the grace period won't expect quiescent states from them. Races |
+| between grace-period start and CPU-hotplug operations are mediated |
+| by the CPU's leaf ``rcu_node`` structure's ``->lock`` as described |
+| above. |
++-----------------------------------------------------------------------+
+
+The approach must be extended to handle one final case, that of waking a
+task blocked in ``synchronize_rcu()``. This task might be affined to
+a CPU that is not yet aware that the grace period has ended, and thus
+might not yet be subject to the grace period's memory ordering.
+Therefore, there is an ``smp_mb()`` after the return from
+``wait_for_completion()`` in the ``synchronize_rcu()`` code path.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| What? Where??? I don't see any ``smp_mb()`` after the return from |
+| ``wait_for_completion()``!!! |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| That would be because I spotted the need for that ``smp_mb()`` during |
+| the creation of this documentation, and it is therefore unlikely to |
+| hit mainline before v4.14. Kudos to Lance Roy, Will Deacon, Peter |
+| Zijlstra, and Jonathan Cameron for asking questions that sensitized |
+| me to the rather elaborate sequence of events that demonstrate the |
+| need for this memory barrier. |
++-----------------------------------------------------------------------+
+
+Tree RCU's grace--period memory-ordering guarantees rely most heavily on
+the ``rcu_node`` structure's ``->lock`` field, so much so that it is
+necessary to abbreviate this pattern in the diagrams in the next
+section. For example, consider the ``rcu_prepare_for_idle()`` function
+shown below, which is one of several functions that enforce ordering of
+newly arrived RCU callbacks against future grace periods:
+
+::
+
+ 1 static void rcu_prepare_for_idle(void)
+ 2 {
+ 3 bool needwake;
+ 4 struct rcu_data *rdp = this_cpu_ptr(&rcu_data);
+ 5 struct rcu_node *rnp;
+ 6 int tne;
+ 7
+ 8 lockdep_assert_irqs_disabled();
+ 9 if (rcu_rdp_is_offloaded(rdp))
+ 10 return;
+ 11
+ 12 /* Handle nohz enablement switches conservatively. */
+ 13 tne = READ_ONCE(tick_nohz_active);
+ 14 if (tne != rdp->tick_nohz_enabled_snap) {
+ 15 if (!rcu_segcblist_empty(&rdp->cblist))
+ 16 invoke_rcu_core(); /* force nohz to see update. */
+ 17 rdp->tick_nohz_enabled_snap = tne;
+ 18 return;
+ 19 }
+ 20 if (!tne)
+ 21 return;
+ 22
+ 23 /*
+ 24 * If we have not yet accelerated this jiffy, accelerate all
+ 25 * callbacks on this CPU.
+ 26 */
+ 27 if (rdp->last_accelerate == jiffies)
+ 28 return;
+ 29 rdp->last_accelerate = jiffies;
+ 30 if (rcu_segcblist_pend_cbs(&rdp->cblist)) {
+ 31 rnp = rdp->mynode;
+ 32 raw_spin_lock_rcu_node(rnp); /* irqs already disabled. */
+ 33 needwake = rcu_accelerate_cbs(rnp, rdp);
+ 34 raw_spin_unlock_rcu_node(rnp); /* irqs remain disabled. */
+ 35 if (needwake)
+ 36 rcu_gp_kthread_wake();
+ 37 }
+ 38 }
+
+But the only part of ``rcu_prepare_for_idle()`` that really matters for
+this discussion are lines 32–34. We will therefore abbreviate this
+function as follows:
+
+.. kernel-figure:: rcu_node-lock.svg
+
+The box represents the ``rcu_node`` structure's ``->lock`` critical
+section, with the double line on top representing the additional
+``smp_mb__after_unlock_lock()``.
+
+Tree RCU Grace Period Memory Ordering Components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tree RCU's grace-period memory-ordering guarantee is provided by a
+number of RCU components:
+
+#. `Callback Registry`_
+#. `Grace-Period Initialization`_
+#. `Self-Reported Quiescent States`_
+#. `Dynamic Tick Interface`_
+#. `CPU-Hotplug Interface`_
+#. `Forcing Quiescent States`_
+#. `Grace-Period Cleanup`_
+#. `Callback Invocation`_
+
+Each of the following section looks at the corresponding component in
+detail.
+
+Callback Registry
+^^^^^^^^^^^^^^^^^
+
+If RCU's grace-period guarantee is to mean anything at all, any access
+that happens before a given invocation of ``call_rcu()`` must also
+happen before the corresponding grace period. The implementation of this
+portion of RCU's grace period guarantee is shown in the following
+figure:
+
+.. kernel-figure:: TreeRCU-callback-registry.svg
+
+Because ``call_rcu()`` normally acts only on CPU-local state, it
+provides no ordering guarantees, either for itself or for phase one of
+the update (which again will usually be removal of an element from an
+RCU-protected data structure). It simply enqueues the ``rcu_head``
+structure on a per-CPU list, which cannot become associated with a grace
+period until a later call to ``rcu_accelerate_cbs()``, as shown in the
+diagram above.
+
+One set of code paths shown on the left invokes ``rcu_accelerate_cbs()``
+via ``note_gp_changes()``, either directly from ``call_rcu()`` (if the
+current CPU is inundated with queued ``rcu_head`` structures) or more
+likely from an ``RCU_SOFTIRQ`` handler. Another code path in the middle
+is taken only in kernels built with ``CONFIG_RCU_FAST_NO_HZ=y``, which
+invokes ``rcu_accelerate_cbs()`` via ``rcu_prepare_for_idle()``. The
+final code path on the right is taken only in kernels built with
+``CONFIG_HOTPLUG_CPU=y``, which invokes ``rcu_accelerate_cbs()`` via
+``rcu_advance_cbs()``, ``rcu_migrate_callbacks``,
+``rcutree_migrate_callbacks()``, and ``takedown_cpu()``, which in turn
+is invoked on a surviving CPU after the outgoing CPU has been completely
+offlined.
+
+There are a few other code paths within grace-period processing that
+opportunistically invoke ``rcu_accelerate_cbs()``. However, either way,
+all of the CPU's recently queued ``rcu_head`` structures are associated
+with a future grace-period number under the protection of the CPU's lead
+``rcu_node`` structure's ``->lock``. In all cases, there is full
+ordering against any prior critical section for that same ``rcu_node``
+structure's ``->lock``, and also full ordering against any of the
+current task's or CPU's prior critical sections for any ``rcu_node``
+structure's ``->lock``.
+
+The next section will show how this ordering ensures that any accesses
+prior to the ``call_rcu()`` (particularly including phase one of the
+update) happen before the start of the corresponding grace period.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But what about ``synchronize_rcu()``? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| The ``synchronize_rcu()`` passes ``call_rcu()`` to ``wait_rcu_gp()``, |
+| which invokes it. So either way, it eventually comes down to |
+| ``call_rcu()``. |
++-----------------------------------------------------------------------+
+
+Grace-Period Initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Grace-period initialization is carried out by the grace-period kernel
+thread, which makes several passes over the ``rcu_node`` tree within the
+``rcu_gp_init()`` function. This means that showing the full flow of
+ordering through the grace-period computation will require duplicating
+this tree. If you find this confusing, please note that the state of the
+``rcu_node`` changes over time, just like Heraclitus's river. However,
+to keep the ``rcu_node`` river tractable, the grace-period kernel
+thread's traversals are presented in multiple parts, starting in this
+section with the various phases of grace-period initialization.
+
+The first ordering-related grace-period initialization action is to
+advance the ``rcu_state`` structure's ``->gp_seq`` grace-period-number
+counter, as shown below:
+
+.. kernel-figure:: TreeRCU-gp-init-1.svg
+
+The actual increment is carried out using ``smp_store_release()``, which
+helps reject false-positive RCU CPU stall detection. Note that only the
+root ``rcu_node`` structure is touched.
+
+The first pass through the ``rcu_node`` tree updates bitmasks based on
+CPUs having come online or gone offline since the start of the previous
+grace period. In the common case where the number of online CPUs for
+this ``rcu_node`` structure has not transitioned to or from zero, this
+pass will scan only the leaf ``rcu_node`` structures. However, if the
+number of online CPUs for a given leaf ``rcu_node`` structure has
+transitioned from zero, ``rcu_init_new_rnp()`` will be invoked for the
+first incoming CPU. Similarly, if the number of online CPUs for a given
+leaf ``rcu_node`` structure has transitioned to zero,
+``rcu_cleanup_dead_rnp()`` will be invoked for the last outgoing CPU.
+The diagram below shows the path of ordering if the leftmost
+``rcu_node`` structure onlines its first CPU and if the next
+``rcu_node`` structure has no online CPUs (or, alternatively if the
+leftmost ``rcu_node`` structure offlines its last CPU and if the next
+``rcu_node`` structure has no online CPUs).
+
+.. kernel-figure:: TreeRCU-gp-init-2.svg
+
+The final ``rcu_gp_init()`` pass through the ``rcu_node`` tree traverses
+breadth-first, setting each ``rcu_node`` structure's ``->gp_seq`` field
+to the newly advanced value from the ``rcu_state`` structure, as shown
+in the following diagram.
+
+.. kernel-figure:: TreeRCU-gp-init-3.svg
+
+This change will also cause each CPU's next call to
+``__note_gp_changes()`` to notice that a new grace period has started,
+as described in the next section. But because the grace-period kthread
+started the grace period at the root (with the advancing of the
+``rcu_state`` structure's ``->gp_seq`` field) before setting each leaf
+``rcu_node`` structure's ``->gp_seq`` field, each CPU's observation of
+the start of the grace period will happen after the actual start of the
+grace period.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But what about the CPU that started the grace period? Why wouldn't it |
+| see the start of the grace period right when it started that grace |
+| period? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| In some deep philosophical and overly anthromorphized sense, yes, the |
+| CPU starting the grace period is immediately aware of having done so. |
+| However, if we instead assume that RCU is not self-aware, then even |
+| the CPU starting the grace period does not really become aware of the |
+| start of this grace period until its first call to |
+| ``__note_gp_changes()``. On the other hand, this CPU potentially gets |
+| early notification because it invokes ``__note_gp_changes()`` during |
+| its last ``rcu_gp_init()`` pass through its leaf ``rcu_node`` |
+| structure. |
++-----------------------------------------------------------------------+
+
+Self-Reported Quiescent States
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When all entities that might block the grace period have reported
+quiescent states (or as described in a later section, had quiescent
+states reported on their behalf), the grace period can end. Online
+non-idle CPUs report their own quiescent states, as shown in the
+following diagram:
+
+.. kernel-figure:: TreeRCU-qs.svg
+
+This is for the last CPU to report a quiescent state, which signals the
+end of the grace period. Earlier quiescent states would push up the
+``rcu_node`` tree only until they encountered an ``rcu_node`` structure
+that is waiting for additional quiescent states. However, ordering is
+nevertheless preserved because some later quiescent state will acquire
+that ``rcu_node`` structure's ``->lock``.
+
+Any number of events can lead up to a CPU invoking ``note_gp_changes``
+(or alternatively, directly invoking ``__note_gp_changes()``), at which
+point that CPU will notice the start of a new grace period while holding
+its leaf ``rcu_node`` lock. Therefore, all execution shown in this
+diagram happens after the start of the grace period. In addition, this
+CPU will consider any RCU read-side critical section that started before
+the invocation of ``__note_gp_changes()`` to have started before the
+grace period, and thus a critical section that the grace period must
+wait on.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But a RCU read-side critical section might have started after the |
+| beginning of the grace period (the advancing of ``->gp_seq`` from |
+| earlier), so why should the grace period wait on such a critical |
+| section? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| It is indeed not necessary for the grace period to wait on such a |
+| critical section. However, it is permissible to wait on it. And it is |
+| furthermore important to wait on it, as this lazy approach is far |
+| more scalable than a “big bang” all-at-once grace-period start could |
+| possibly be. |
++-----------------------------------------------------------------------+
+
+If the CPU does a context switch, a quiescent state will be noted by
+``rcu_note_context_switch()`` on the left. On the other hand, if the CPU
+takes a scheduler-clock interrupt while executing in usermode, a
+quiescent state will be noted by ``rcu_sched_clock_irq()`` on the right.
+Either way, the passage through a quiescent state will be noted in a
+per-CPU variable.
+
+The next time an ``RCU_SOFTIRQ`` handler executes on this CPU (for
+example, after the next scheduler-clock interrupt), ``rcu_core()`` will
+invoke ``rcu_check_quiescent_state()``, which will notice the recorded
+quiescent state, and invoke ``rcu_report_qs_rdp()``. If
+``rcu_report_qs_rdp()`` verifies that the quiescent state really does
+apply to the current grace period, it invokes ``rcu_report_rnp()`` which
+traverses up the ``rcu_node`` tree as shown at the bottom of the
+diagram, clearing bits from each ``rcu_node`` structure's ``->qsmask``
+field, and propagating up the tree when the result is zero.
+
+Note that traversal passes upwards out of a given ``rcu_node`` structure
+only if the current CPU is reporting the last quiescent state for the
+subtree headed by that ``rcu_node`` structure. A key point is that if a
+CPU's traversal stops at a given ``rcu_node`` structure, then there will
+be a later traversal by another CPU (or perhaps the same one) that
+proceeds upwards from that point, and the ``rcu_node`` ``->lock``
+guarantees that the first CPU's quiescent state happens before the
+remainder of the second CPU's traversal. Applying this line of thought
+repeatedly shows that all CPUs' quiescent states happen before the last
+CPU traverses through the root ``rcu_node`` structure, the “last CPU”
+being the one that clears the last bit in the root ``rcu_node``
+structure's ``->qsmask`` field.
+
+Dynamic Tick Interface
+^^^^^^^^^^^^^^^^^^^^^^
+
+Due to energy-efficiency considerations, RCU is forbidden from
+disturbing idle CPUs. CPUs are therefore required to notify RCU when
+entering or leaving idle state, which they do via fully ordered
+value-returning atomic operations on a per-CPU variable. The ordering
+effects are as shown below:
+
+.. kernel-figure:: TreeRCU-dyntick.svg
+
+The RCU grace-period kernel thread samples the per-CPU idleness variable
+while holding the corresponding CPU's leaf ``rcu_node`` structure's
+``->lock``. This means that any RCU read-side critical sections that
+precede the idle period (the oval near the top of the diagram above)
+will happen before the end of the current grace period. Similarly, the
+beginning of the current grace period will happen before any RCU
+read-side critical sections that follow the idle period (the oval near
+the bottom of the diagram above).
+
+Plumbing this into the full grace-period execution is described
+`below <Forcing Quiescent States_>`__.
+
+CPU-Hotplug Interface
+^^^^^^^^^^^^^^^^^^^^^
+
+RCU is also forbidden from disturbing offline CPUs, which might well be
+powered off and removed from the system completely. CPUs are therefore
+required to notify RCU of their comings and goings as part of the
+corresponding CPU hotplug operations. The ordering effects are shown
+below:
+
+.. kernel-figure:: TreeRCU-hotplug.svg
+
+Because CPU hotplug operations are much less frequent than idle
+transitions, they are heavier weight, and thus acquire the CPU's leaf
+``rcu_node`` structure's ``->lock`` and update this structure's
+``->qsmaskinitnext``. The RCU grace-period kernel thread samples this
+mask to detect CPUs having gone offline since the beginning of this
+grace period.
+
+Plumbing this into the full grace-period execution is described
+`below <Forcing Quiescent States_>`__.
+
+Forcing Quiescent States
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+As noted above, idle and offline CPUs cannot report their own quiescent
+states, and therefore the grace-period kernel thread must do the
+reporting on their behalf. This process is called “forcing quiescent
+states”, it is repeated every few jiffies, and its ordering effects are
+shown below:
+
+.. kernel-figure:: TreeRCU-gp-fqs.svg
+
+Each pass of quiescent state forcing is guaranteed to traverse the leaf
+``rcu_node`` structures, and if there are no new quiescent states due to
+recently idled and/or offlined CPUs, then only the leaves are traversed.
+However, if there is a newly offlined CPU as illustrated on the left or
+a newly idled CPU as illustrated on the right, the corresponding
+quiescent state will be driven up towards the root. As with
+self-reported quiescent states, the upwards driving stops once it
+reaches an ``rcu_node`` structure that has quiescent states outstanding
+from other CPUs.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| The leftmost drive to root stopped before it reached the root |
+| ``rcu_node`` structure, which means that there are still CPUs |
+| subordinate to that structure on which the current grace period is |
+| waiting. Given that, how is it possible that the rightmost drive to |
+| root ended the grace period? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Good analysis! It is in fact impossible in the absence of bugs in |
+| RCU. But this diagram is complex enough as it is, so simplicity |
+| overrode accuracy. You can think of it as poetic license, or you can |
+| think of it as misdirection that is resolved in the |
+| `stitched-together diagram <Putting It All Together_>`__. |
++-----------------------------------------------------------------------+
+
+Grace-Period Cleanup
+^^^^^^^^^^^^^^^^^^^^
+
+Grace-period cleanup first scans the ``rcu_node`` tree breadth-first
+advancing all the ``->gp_seq`` fields, then it advances the
+``rcu_state`` structure's ``->gp_seq`` field. The ordering effects are
+shown below:
+
+.. kernel-figure:: TreeRCU-gp-cleanup.svg
+
+As indicated by the oval at the bottom of the diagram, once grace-period
+cleanup is complete, the next grace period can begin.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But when precisely does the grace period end? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| There is no useful single point at which the grace period can be said |
+| to end. The earliest reasonable candidate is as soon as the last CPU |
+| has reported its quiescent state, but it may be some milliseconds |
+| before RCU becomes aware of this. The latest reasonable candidate is |
+| once the ``rcu_state`` structure's ``->gp_seq`` field has been |
+| updated, but it is quite possible that some CPUs have already |
+| completed phase two of their updates by that time. In short, if you |
+| are going to work with RCU, you need to learn to embrace uncertainty. |
++-----------------------------------------------------------------------+
+
+Callback Invocation
+^^^^^^^^^^^^^^^^^^^
+
+Once a given CPU's leaf ``rcu_node`` structure's ``->gp_seq`` field has
+been updated, that CPU can begin invoking its RCU callbacks that were
+waiting for this grace period to end. These callbacks are identified by
+``rcu_advance_cbs()``, which is usually invoked by
+``__note_gp_changes()``. As shown in the diagram below, this invocation
+can be triggered by the scheduling-clock interrupt
+(``rcu_sched_clock_irq()`` on the left) or by idle entry
+(``rcu_cleanup_after_idle()`` on the right, but only for kernels build
+with ``CONFIG_RCU_FAST_NO_HZ=y``). Either way, ``RCU_SOFTIRQ`` is
+raised, which results in ``rcu_do_batch()`` invoking the callbacks,
+which in turn allows those callbacks to carry out (either directly or
+indirectly via wakeup) the needed phase-two processing for each update.
+
+.. kernel-figure:: TreeRCU-callback-invocation.svg
+
+Please note that callback invocation can also be prompted by any number
+of corner-case code paths, for example, when a CPU notes that it has
+excessive numbers of callbacks queued. In all cases, the CPU acquires
+its leaf ``rcu_node`` structure's ``->lock`` before invoking callbacks,
+which preserves the required ordering against the newly completed grace
+period.
+
+However, if the callback function communicates to other CPUs, for
+example, doing a wakeup, then it is that function's responsibility to
+maintain ordering. For example, if the callback function wakes up a task
+that runs on some other CPU, proper ordering must in place in both the
+callback function and the task being awakened. To see why this is
+important, consider the top half of the `grace-period
+cleanup`_ diagram. The callback might be
+running on a CPU corresponding to the leftmost leaf ``rcu_node``
+structure, and awaken a task that is to run on a CPU corresponding to
+the rightmost leaf ``rcu_node`` structure, and the grace-period kernel
+thread might not yet have reached the rightmost leaf. In this case, the
+grace period's memory ordering might not yet have reached that CPU, so
+again the callback function and the awakened task must supply proper
+ordering.
+
+Putting It All Together
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A stitched-together diagram is here:
+
+.. kernel-figure:: TreeRCU-gp.svg
+
+Legal Statement
+~~~~~~~~~~~~~~~
+
+This work represents the view of the author and does not necessarily
+represent the view of IBM.
+
+Linux is a registered trademark of Linus Torvalds.
+
+Other company, product, and service names may be trademarks or service
+marks of others.
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg
new file mode 100644
index 000000000000..3fcf0c17cef2
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg
@@ -0,0 +1,486 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="592.12805"
+ height="469.83038"
+ viewBox="-44 -44 7874.1949 6244.9802"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-callback-invocation.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="1.2009216"
+ inkscape:cx="289.88715"
+ inkscape:cy="219.06265"
+ inkscape:window-x="713"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g3058"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3079"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="-116.00011px"
+ originy="-87.2081px" />
+ </sodipodi:namedview>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(-2296.0293,-2364.1166)">
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,2411.7612 0,4920.3076"
+ id="path3134-9-0-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,4672.443 -2393.6631,0.5116 0,1196.8316 2393.6631,-0.5116"
+ id="path3134-9-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,4672.443 2393.6631,0.5116 0,1196.8316 -2393.6631,-0.5116"
+ id="path3134-9-0-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240-->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150-->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <rect
+ x="2333.5203"
+ y="5109.5566"
+ width="2844.0974"
+ height="360.77411"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.0005789, 60.00115781;stroke-dashoffset:0"
+ id="rect118-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="2562.135"
+ y="5357.9937"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_sched_clock_irq()</text>
+ <rect
+ x="7069.6187"
+ y="5087.4678"
+ width="2975.115"
+ height="382.86298"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057902, 60.00115804;stroke-dashoffset:0"
+ id="rect118-36"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="7165.2524"
+ y="5333.4927"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_cleanup_after_idle()</text>
+ <g
+ id="g3058"
+ transform="translate(-53.192514,-2819.2063)">
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier"
+ id="text202"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="6532.0293"
+ x="5073.3374"
+ xml:space="preserve">rcu_advance_cbs()</text>
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="5650.2598"
+ x="4800.2563" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="5726.2852"
+ x="4800.2563" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="6961.395"
+ x="7220.106"
+ xml:space="preserve"><tspan
+ id="tspan3104-6-5"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="6321.9248"
+ x="5073.3374"
+ xml:space="preserve">__note_gp_changes()</text>
+ </g>
+ <g
+ id="g3049"
+ transform="translate(26.596257,6090.5512)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,1872.6808,-2726.4833)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-3"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-6"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1785.2073"
+ x="5717.4517"
+ xml:space="preserve"><tspan
+ id="tspan3104-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Phase Two</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-5"
+ y="2005.6624"
+ x="6119.668"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="2005.6624"
+ x="6119.668"
+ id="tspan3112-3"
+ sodipodi:role="line">of Update</tspan></text>
+ </g>
+ <rect
+ x="5097.8271"
+ y="6268.2183"
+ width="1994.7195"
+ height="664.90662"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057858, 60.00115716;stroke-dashoffset:0"
+ id="rect118-36-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="5363.7886"
+ y="6534.1812"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">RCU_SOFTIRQ</text>
+ <text
+ xml:space="preserve"
+ x="5363.7886"
+ y="6800.1436"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6-6-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_do_batch()</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg
new file mode 100644
index 000000000000..63eff867175a
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg
@@ -0,0 +1,646 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="816.04761"
+ height="636.55627"
+ viewBox="-44 -44 10851.906 8461.0989"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-callback-registry.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="1.2009216"
+ inkscape:cx="408.02381"
+ inkscape:cy="254.38856"
+ inkscape:window-x="713"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3079"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="5.2596966e-08px"
+ originy="-4.5963961e-06px" />
+ </sodipodi:namedview>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(-753.44492,-1306.6788)">
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,2411.7612 0,6117.1391"
+ id="path3134-9-0-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,3342.6302 -3856.4573,0 10.6979,5757.1962 2918.1436,-2e-4"
+ id="path3134-9-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,3342.6302 3856.4574,0 -12.188,5757.1963 -2918.1436,-3e-4"
+ id="path3134-9-0-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240-->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150-->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <rect
+ x="4544.7305"
+ y="4603.417"
+ width="3240.0088"
+ height="2650.6289"
+ rx="0"
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ id="rect118"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="5073.3374"
+ y="6372.4521"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">rcu_accelerate_cbs()</text>
+ <g
+ id="g3107"
+ transform="translate(2715.7065,4700.8888)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="4773.3452"
+ y="4825.2578"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_prepare_for_idle()</text>
+ <rect
+ x="790.93585"
+ y="4630.8252"
+ width="3240.0088"
+ height="2650.6289"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.0005789, 60.00115781;stroke-dashoffset:0"
+ id="rect118-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="1319.5447"
+ y="6639.2261"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_accelerate_cbs()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7"
+ transform="translate(-1038.0776,4728.2971)">
+ <rect
+ id="rect112-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="1019.5512"
+ y="4852.666"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">note_gp_changes()</text>
+ <text
+ xml:space="preserve"
+ x="1319.5447"
+ y="6376.6328"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_advance_cbs()</text>
+ <text
+ xml:space="preserve"
+ x="1340.6649"
+ y="6111.4473"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">__note_gp_changes()</text>
+ <rect
+ x="5422.6279"
+ y="3041.8311"
+ width="1480.4871"
+ height="379.24637"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.0005789, 60.00115794;stroke-dashoffset:0"
+ id="rect118-3-9"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="5607.2734"
+ y="3283.3892"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">call_rcu()</text>
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ id="path3084"
+ sodipodi:cx="319.379"
+ sodipodi:cy="345.54001"
+ sodipodi:rx="65.917107"
+ sodipodi:ry="39.550262"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ transform="matrix(13.298129,0,0,13.298129,1915.7286,4523.6528)" />
+ <text
+ xml:space="preserve"
+ x="5853.9238"
+ y="8902.3623"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104">Wake up</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6165.7158"
+ y="9122.8174"
+ id="text3110"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3112"
+ x="6165.7158"
+ y="9122.8174">grace-period</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6162.8716"
+ y="9364.3564"
+ id="text3114"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3116"
+ x="6162.8716"
+ y="9364.3564">kernel thread</tspan></text>
+ <rect
+ x="8239.8516"
+ y="4608.7363"
+ width="3240.0088"
+ height="2650.6289"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057902, 60.00115804;stroke-dashoffset:0"
+ id="rect118-36"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="8768.4678"
+ y="6484.1562"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-75"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_accelerate_cbs()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-3"
+ transform="translate(6410.833,4706.2127)">
+ <rect
+ id="rect112-56"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="8329.5352"
+ y="4830.5771"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">takedown_cpu()</text>
+ <text
+ xml:space="preserve"
+ x="8335.4873"
+ y="5094.127"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_migrate_callbacks()</text>
+ <text
+ xml:space="preserve"
+ x="8768.4678"
+ y="6224.9038"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_advance_cbs()</text>
+ <text
+ xml:space="preserve"
+ x="3467.9963"
+ y="6987.9912"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7220.106"
+ y="6961.395"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="10905.331"
+ y="6961.395"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-5">Leaf</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ id="path3084-3"
+ sodipodi:cx="319.379"
+ sodipodi:cy="345.54001"
+ sodipodi:rx="65.917107"
+ sodipodi:ry="39.550262"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ transform="matrix(13.298129,0,0,13.298129,1872.6808,-2726.4833)" />
+ <text
+ xml:space="preserve"
+ x="5717.4517"
+ y="1785.2073"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-7">Phase One</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6119.668"
+ y="2005.6624"
+ id="text3110-5"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3112-3"
+ x="6119.668"
+ y="2005.6624">of Update</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-dyntick.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-dyntick.svg
new file mode 100644
index 000000000000..3fbc19c48a58
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-dyntick.svg
@@ -0,0 +1,700 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="670.61804"
+ height="557.16394"
+ viewBox="-44 -44 8917.9652 7405.8166"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-dyntick.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-0"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-6"
+ style="overflow:visible">
+ <path
+ id="path3940-26"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-8"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-367"
+ style="overflow:visible">
+ <path
+ id="path3940-5"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-56"
+ style="overflow:visible">
+ <path
+ id="path3946-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3081"
+ style="overflow:visible">
+ <path
+ id="path3083"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3085"
+ style="overflow:visible">
+ <path
+ id="path3087"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3089"
+ style="overflow:visible">
+ <path
+ id="path3091"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093"
+ style="overflow:visible">
+ <path
+ id="path3095"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3097"
+ style="overflow:visible">
+ <path
+ id="path3099"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-9"
+ style="overflow:visible">
+ <path
+ id="path3940-1"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3675"
+ style="overflow:visible">
+ <path
+ id="path3940-3"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1148"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="1.4142136"
+ inkscape:cx="381.32663"
+ inkscape:cy="239.67141"
+ inkscape:window-x="833"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg2"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5"
+ inkscape:snap-global="false">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3154"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="-235.14935px"
+ originy="-709.25071px" />
+ </sodipodi:namedview>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3-5"
+ d="m 3754.1051,47.378296 -2.828,7173.860804"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3"
+ d="m 6681.1176,1435.1734 -2.828,1578.9586 -2861.3912,7.7159"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1"
+ d="m 3748.8929,3772.1176 2904.1747,-0.8434 26.8008,1842.1825"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ id="g3115"
+ transform="translate(-2341.8794,10827.399)">
+ <rect
+ ry="0"
+ id="rect118-3"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057923, 60.00115859;stroke-dashoffset:0"
+ rx="0"
+ height="2349.7295"
+ width="5308.7119"
+ y="-8909.5498"
+ x="2379.3704" />
+ <g
+ transform="translate(2576.8841,-9085.2783)"
+ id="g3107-7"
+ style="fill:none;stroke-width:0.025in">
+ <rect
+ x="2084.55"
+ y="949.37109"
+ width="2809.1992"
+ height="1370.8721"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-5" />
+ <rect
+ x="2084.55"
+ y="1025.3964"
+ width="2809.1992"
+ height="1294.8468"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-3-3" />
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-6-6-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-7356.375"
+ x="4769.4536"
+ xml:space="preserve">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-6825.5815"
+ x="7082.9585"
+ xml:space="preserve"><tspan
+ id="tspan3104-6"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-8652.5312"
+ x="2466.7822"
+ xml:space="preserve">rcu_watching_snap_save()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-2-0"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-8368.1475"
+ x="2463.3262"
+ xml:space="preserve">rcu_watching_snap_recheck()</text>
+ </g>
+ <g
+ id="g4504"
+ transform="translate(2063.5184,-16111.739)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3148-9-9"
+ transform="translate(2035.3087,6370.5796)">
+ <rect
+ x="3592.3828"
+ y="-4715.7246"
+ width="3164.783"
+ height="769.99048"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4418.6582"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">ct_kernel_exit_state()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4165.7954"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">atomic_add_return()</text>
+ </g>
+ <g
+ id="g3148-9-9-2"
+ transform="translate(2035.3089,9031.6839)">
+ <rect
+ x="3592.3828"
+ y="-4715.7246"
+ width="3164.783"
+ height="769.99048"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3-6"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4418.6582"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">ct_kernel_enter_state()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4165.7954"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">atomic_add_return()</text>
+ </g>
+ <g
+ id="g4504-7"
+ transform="translate(2082.3248,-10883.562)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-9"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-0"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-2"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-3"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-7"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-5"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-cleanup.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-cleanup.svg
new file mode 100644
index 000000000000..bf84fbab27ee
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-cleanup.svg
@@ -0,0 +1,1133 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1026.1281"
+ height="1246.2428"
+ viewBox="-44 -44 13645.583 16565.045"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-gp-cleanup.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-1"
+ style="overflow:visible">
+ <path
+ id="path3946-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3130"
+ style="overflow:visible">
+ <path
+ id="path3132"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3134"
+ style="overflow:visible">
+ <path
+ id="path3136"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3138"
+ style="overflow:visible">
+ <path
+ id="path3140"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3142"
+ style="overflow:visible">
+ <path
+ id="path3144"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3146"
+ style="overflow:visible">
+ <path
+ id="path3148"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-7"
+ style="overflow:visible">
+ <path
+ id="path3940-0"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36-7"
+ style="overflow:visible">
+ <path
+ id="path3940-7-4"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="0.78716603"
+ inkscape:cx="513.06403"
+ inkscape:cy="623.1214"
+ inkscape:window-x="102"
+ inkscape:window-y="38"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g3188-3"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3391"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="-1.7575793e-05px"
+ originy="70.717956px" />
+ </sodipodi:namedview>
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3"
+ d="m 6899.303,45.238347 -2.8276,2480.757053 -2316.0141,-1.687 -2.8276,2179.855 2321.1758,-0.844 -2.7042,-1843.237 2404.5142,-0.211 16.1022,1993.267 -7783.8345,-4.728 -16.7936,2120.3945 2033.1033,-23.5344 2.0128,-1866.5611 2051.9097,14.079 2.0128,1838.2983 1280.8475,-4.728 14.608,-1830.1043 1312.2492,12.923 14.608,1818.337 2000.0061,20.4217 -12.279,-1841.4117 1304.168,1.616 -12.279,2032.7057 -4638.6513,1.6154 19.5828,569.0378"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2450.4073,-11647.612)"
+ id="g3188">
+ <text
+ xml:space="preserve"
+ x="3145.9592"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3143">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ <g
+ id="g3107"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Root</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ rx="0"
+ height="14649.609"
+ width="13482.601"
+ y="403.13776"
+ x="37.490932" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="662.59283"
+ x="153.2673"
+ xml:space="preserve">rcu_gp_cleanup()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2329.9437,-11611.245)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5264.4731"
+ y="15428.84"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-5">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(3181.0244,-11647.612)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-9"
+ d="m 3710.957,19425.516 -20.9546,8604.655"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(-737.93887,7732.6672)"
+ id="g3188-3">
+ <g
+ id="g3107-62"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-1"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-7">Root</tspan></text>
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot3356"
+ style="font-size:12px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ transform="matrix(13.298129,0,0,13.298129,-2487.0857,3868.8376)"><flowRegion
+ id="flowRegion3358"><rect
+ id="rect3360"
+ width="373.35239"
+ height="63.63961"
+ x="332.34018"
+ y="681.87292" /></flowRegion><flowPara
+ id="flowPara3362" /></flowRoot> <text
+ xml:space="preserve"
+ x="3156.6121"
+ y="13317.754"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-0">rcu_seq_end(&amp;rsp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(-858.40227,7769.0342)"
+ id="g3147-9">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-2"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-02"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-5"
+ transform="translate(5205.6909,23741.476)">
+ <rect
+ id="rect112-7-1-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9710.0928"
+ y="26001.982"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-8">Leaf</tspan></text>
+ <g
+ transform="translate(-4830.8839,7769.0342)"
+ id="g3147-3-7"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-3"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-1"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ transform="translate(-3340.0639,7732.6672)"
+ id="g3153-2-9"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-3"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-9"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-4"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-7">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-6672.8049,7732.6672)"
+ id="g3153-20-8"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-4"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-6">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-10005.546,7732.6672)"
+ id="g3153-28-0"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-6">Leaf</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2285.411,21615.005 -582.9982,865.094"
+ id="path3414-5"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5094.193,21615.267 582.998,865.094"
+ id="path3414-9-5"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 334.77783,23828.182 -582.9982,865.094"
+ id="path3414-8-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7079.8249,23828.444 582.9999,865.094"
+ id="path3414-9-4-7"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 1751.2742,23828.182 0,846.288"
+ id="path3414-8-3-65"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5628.2495,23854.778 0,846.288"
+ id="path3414-8-3-6-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ x="7418.769"
+ y="17646.104"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-70"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-93">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ transform="translate(-1642.5377,-11611.245)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5274.1133"
+ y="15428.84"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ transform="translate(-151.71746,-11647.612)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-3484.4587,-11647.612)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7408.5918"
+ y="17619.504"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-9">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ transform="translate(-6817.1997,-11647.612)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7416.8003"
+ y="17619.504"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-56">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5473.757,2234.7264 -582.9982,865.094"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8282.5389,2234.9884 582.9982,865.094"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 3523.1239,4447.9034 -582.9982,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 10268.171,4448.1654 583,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4939.6203,4447.9034 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8816.5956,4474.4994 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4504-3-9"
+ transform="translate(4866.6205,-1197.2204)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16888.277"
+ x="4344.877"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Start of</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0"
+ y="17119.1"
+ x="4578.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17119.1"
+ x="4578.7886"
+ id="tspan3112-5-9"
+ sodipodi:role="line">Next Grace</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3"
+ y="17350.271"
+ x="4581.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17350.271"
+ x="4581.7886"
+ id="tspan3116-2-6"
+ sodipodi:role="line">Period</tspan></text>
+ </g>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-5"
+ d="m 6875.6003,15833.906 1595.7755,0"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send-36)" />
+ <text
+ xml:space="preserve"
+ x="7275.2612"
+ y="5971.8916"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-2">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg
new file mode 100644
index 000000000000..25c7acc8a4c2
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg
@@ -0,0 +1,1309 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1626.5847"
+ height="843.1416"
+ viewBox="-44 -44 21630.534 11207.028"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-gp-fqs.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-0"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-6"
+ style="overflow:visible">
+ <path
+ id="path3940-26"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-8"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-367"
+ style="overflow:visible">
+ <path
+ id="path3940-5"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-56"
+ style="overflow:visible">
+ <path
+ id="path3946-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3081"
+ style="overflow:visible">
+ <path
+ id="path3083"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3085"
+ style="overflow:visible">
+ <path
+ id="path3087"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3089"
+ style="overflow:visible">
+ <path
+ id="path3091"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093"
+ style="overflow:visible">
+ <path
+ id="path3095"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3097"
+ style="overflow:visible">
+ <path
+ id="path3099"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-9"
+ style="overflow:visible">
+ <path
+ id="path3940-1"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-91"
+ style="overflow:visible">
+ <path
+ id="path3940-27"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3082"
+ style="overflow:visible">
+ <path
+ id="path3084"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-09"
+ style="overflow:visible">
+ <path
+ id="path3940-3"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093-6"
+ style="overflow:visible">
+ <path
+ id="path3095-0"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3675"
+ style="overflow:visible">
+ <path
+ id="path3940-35"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="0.5"
+ inkscape:cx="843.3925"
+ inkscape:cy="528.22238"
+ inkscape:window-x="860"
+ inkscape:window-y="65"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg2"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5"
+ inkscape:snap-global="false">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3154"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="306.04964px"
+ originy="286.40704px" />
+ </sodipodi:namedview>
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1"
+ d="m 16000.705,7361.3625 3383.738,-0.8434 7.995,1860.9894"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3"
+ d="m 19393.687,5043.2247 -2.828,1541.346 -3303.342,-1.6876"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-6"
+ d="m 5568.2242,7353.9621 -3929.1209,17.9634 20.2153,2632.0515"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3-2"
+ d="m 1629.8598,3926.2473 12.2312,2669.7292 3867.5308,7.7168"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3"
+ d="m 10932.061,46.910528 -2.827,638.638602 -5325.0378,35.9259 -21.6339,7219.96837 2057.8863,-38.4562 -21.5106,-2087.7208 -491.6705,-0.211 -2.7042,-1993.689 1393.686,-4.728 39.6256,4057.454 2379.6691,32.779 14.608,-1848.911 1312.249,12.923 14.608,1818.337 2000.007,20.422 -12.28,-1841.412 1191.331,1.616 15.929,1289.8537 520.344,0.202 m 0,0 -15.641,-1570.1327 -2629.727,-18.604 3.166,-2124.92 -2385.245,19.007 21.973,-2444.6293 5551.053,37.8148 1.584,7165.3369 m 0,0 -5602.722,0.1016 19.583,813.521"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <rect
+ ry="0"
+ id="rect118"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057925, 60.0011585;stroke-dashoffset:0"
+ rx="0"
+ height="8254.9336"
+ width="14128.912"
+ y="443.33136"
+ x="4032.6365" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="720.02423"
+ x="4178.2354"
+ xml:space="preserve">rcu_gp_fqs()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(6381.5083,-10649.537)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5250.5327"
+ y="15512.733"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-35"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(7232.589,-10685.904)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(2409.0267,-10649.537)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5284.6885"
+ y="15500.379"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <g
+ transform="translate(3899.8472,-10685.904)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(567.10542,-10685.904)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-2765.6353,-10685.904)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7428.2939"
+ y="17707.271"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-75"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9525.3217,3196.4324 -582.9982,865.094"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 12334.103,3196.6944 582.999,865.094"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7574.6885,5409.6094 -582.9983,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 14319.735,5409.8714 583.001,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8991.1849,5409.6094 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 12868.16,5436.2054 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <rect
+ ry="0"
+ id="rect118-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057965, 60.00115916;stroke-dashoffset:0"
+ rx="0"
+ height="7164.1621"
+ width="13301.43"
+ y="984.91095"
+ x="4277.6021" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1236.326"
+ x="4409.96"
+ xml:space="preserve"
+ sodipodi:linespacing="125%">force_qs_rnp()<tspan
+ style="font-size:192px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3307" /></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1547.8876"
+ x="4417.6396"
+ xml:space="preserve">rcu_watching_snap_save()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(6501.9719,-10685.904)"
+ id="g3188">
+ <g
+ id="g3107"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3158.8521"
+ y="13313.027"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1858.8729"
+ x="4414.1836"
+ xml:space="preserve">rcu_watching_snap_recheck()</text>
+ <text
+ xml:space="preserve"
+ x="14659.87"
+ y="7002.561"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-62"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ <g
+ id="g4504"
+ transform="translate(14776.087,-12503.687)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3089"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3148-9-9"
+ transform="translate(14747.877,9978.6315)">
+ <rect
+ x="3592.3828"
+ y="-4715.7246"
+ width="3164.783"
+ height="769.99048"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4418.6582"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">ct_kernel_exit_state()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4165.7954"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">atomic_add_return()</text>
+ </g>
+ <g
+ id="g3148-9-9-2"
+ transform="translate(14747.877,12639.736)">
+ <rect
+ x="3592.3828"
+ y="-4715.7246"
+ width="3164.783"
+ height="769.99048"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3-6"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4418.6582"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">ct_kernel_enter_state()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4165.7954"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">atomic_add_return()</text>
+ </g>
+ <g
+ id="g4504-7"
+ transform="translate(14794.893,-7275.5109)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-9"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-0"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-2"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-3"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-7"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-5"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-6"
+ transform="translate(-2953.0872,-13662.506)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-1"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-9"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-2"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-0"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3148-9-9-3"
+ transform="translate(-3554.8919,9313.0075)">
+ <rect
+ x="3592.3828"
+ y="-4981.6865"
+ width="3728.9751"
+ height="2265.0989"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3-7"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4684.6201"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4431.7573"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_cleanup_dying_idle_cpu()</text>
+ <g
+ transform="translate(1783.3183,-5255.3491)"
+ id="g3107-7-5"
+ style="fill:none;stroke-width:0.025in">
+ <rect
+ x="2084.55"
+ y="949.37109"
+ width="2809.1992"
+ height="1370.8721"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-5-3" />
+ <rect
+ x="2084.55"
+ y="1025.3964"
+ width="2809.1992"
+ height="1294.8468"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-3-3-5" />
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-6-6-2-6"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-3526.4448"
+ x="4241.8574"
+ xml:space="preserve">-&gt;qsmaskinitnext</text>
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-2987.4167"
+ x="6305.1484"
+ xml:space="preserve"><tspan
+ id="tspan3104-6-9"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ </g>
+ <g
+ id="g4504-7-2"
+ transform="translate(-2934.2807,-6492.8204)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-9-2"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-2-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-0-9"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-2-7"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-3-3"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-7-6"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-5-1"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3206"
+ transform="translate(3999.5374,3999.1768)">
+ <rect
+ ry="0"
+ id="rect118-3-5-1-3-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00058007, 60.00116001;stroke-dashoffset:0"
+ rx="0"
+ height="2265.0989"
+ width="3728.9751"
+ y="3382.2036"
+ x="-3958.3845" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-6-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="3679.27"
+ x="-3804.9949"
+ xml:space="preserve">rcutree_report_cpu_starting()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7-5-0"
+ transform="translate(-5767.4491,3108.5424)">
+ <rect
+ id="rect112-5-3-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3-5-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="-3308.9099"
+ y="4837.4453"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ <text
+ xml:space="preserve"
+ x="-1245.6189"
+ y="5376.4731"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-2-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-9-6">Leaf</tspan></text>
+ </g>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3-6"
+ d="m 15475.193,7360.7089 467.332,8.6247"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-1.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-1.svg
new file mode 100644
index 000000000000..8c207550818f
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-1.svg
@@ -0,0 +1,658 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1039.3743"
+ height="677.72852"
+ viewBox="-44 -44 13821.733 9008.3597"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-gp-init-1.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="2.6330492"
+ inkscape:cx="524.82797"
+ inkscape:cy="519.31194"
+ inkscape:window-x="79"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g3188"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3059"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="1.6062488e-07px"
+ originy="10.7285px" />
+ </sodipodi:namedview>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3"
+ d="m 6871.027,46.883461 0,8777.144039"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2450.4075,-10679.115)"
+ id="g3188">
+ <text
+ xml:space="preserve"
+ x="3119.363"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3071">rcu_seq_start(rsp-&gt;gp_seq)</tspan></text>
+ <g
+ id="g3107"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Root</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ rx="0"
+ height="6844.4546"
+ width="13658.751"
+ y="1371.6335"
+ x="37.490932" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1631.0878"
+ x="153.26733"
+ xml:space="preserve">rcu_gp_init()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2329.9439,-10642.748)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(3181.0246,-10679.115)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-1642.5375,-10642.748)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ transform="translate(-151.71726,-10679.115)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-3484.4587,-10679.115)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-6817.1998,-10679.115)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5473.7572,3203.2219 -582.9982,865.094"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8282.5391,3203.4839 582.9982,865.094"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 3523.1241,5416.3989 -582.9982,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 10268.171,5416.6609 583,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4939.6205,5416.3989 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8816.5958,5442.9949 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ id="g4504-3-9"
+ transform="translate(4866.0367,-16425.339)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16888.277"
+ x="4344.877"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">End of</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0"
+ y="17119.1"
+ x="4578.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17119.1"
+ x="4578.7886"
+ id="tspan3112-5-9"
+ sodipodi:role="line">Last Grace</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3"
+ y="17350.271"
+ x="4581.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17350.271"
+ x="4581.7886"
+ id="tspan3116-2-6"
+ sodipodi:role="line">Period</tspan></text>
+ </g>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-5"
+ d="m 8546.5914,605.78414 -1595.7755,0"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send-36)" />
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-2.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-2.svg
new file mode 100644
index 000000000000..4d956a732685
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-2.svg
@@ -0,0 +1,656 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1037.9602"
+ height="666.38184"
+ viewBox="-44 -44 13802.928 8857.5401"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-gp-init-2.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="false"
+ inkscape:zoom="0.79710462"
+ inkscape:cx="564.27119"
+ inkscape:cy="397.32188"
+ inkscape:window-x="833"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg2"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3"
+ d="m 6861.6904,46.438525 -2.8276,1315.668775 -5343.8436,17.1194 -2.8276,6561.7446 2039.0799,17.963 -2.7042,-2144.1399 -491.6705,-0.2109 -2.7042,-1993.6887 1487.7179,-4.7279 -17.8,1812.453 2017.2374,-7.6434 4.9532,-2151.5723 -1405.5264,11.163 -10.919,-1891.1468 1739.2164,-2.7175 -13.2006,4234.2295 -1701.3595,1.3953 -8.7841,2107.7116 1702.6392,-4.8334 33.4144,-1867.7167 1312.2492,12.9229 14.608,1818.3367 2000.0063,20.4217 -12.279,-1841.4113 1304.168,1.6154 -12.279,2032.7059 -4638.6515,1.6154 19.5828,569.0378"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <rect
+ ry="0"
+ id="rect118"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ rx="0"
+ height="7653.1299"
+ width="13639.945"
+ y="555.69745"
+ x="37.490929" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="799.34259"
+ x="134.46091"
+ xml:space="preserve">rcu_gp_init()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2311.1375,-10650.009)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(3162.2182,-10686.376)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-1661.3439,-10650.009)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5398.415"
+ y="15310.093"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinit</text>
+ <text
+ xml:space="preserve"
+ x="5398.415"
+ y="15545.01"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-5-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ </g>
+ <g
+ transform="translate(-170.52359,-10686.376)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-3503.2651,-10686.376)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-6836.0062,-10686.376)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7699.7246"
+ y="17734.791"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-4"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinit</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5454.9508,3195.9607 -582.9982,865.094"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8263.7327,3196.2227 582.9982,865.094"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 3504.3177,5409.1377 -582.9982,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 10249.365,5409.3997 583,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4920.8141,5409.1377 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8797.7894,5435.7337 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <rect
+ ry="0"
+ id="rect118-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057923, 60.00115846;stroke-dashoffset:0"
+ rx="0"
+ height="4418.4302"
+ width="4932.5845"
+ y="1492.2119"
+ x="2087.8708" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1690.4336"
+ x="2223.3145"
+ xml:space="preserve"
+ sodipodi:linespacing="125%">rcu_init_new_rnp()<tspan
+ style="font-size:192px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3307"> or</tspan></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1958.5066"
+ x="2223.3145"
+ xml:space="preserve">rcu_cleanup_dead_rnp()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-6"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="2227.4531"
+ x="2226.1592"
+ xml:space="preserve"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:192px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3327">(optional)</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2431.6011,-10686.376)"
+ id="g3188">
+ <text
+ xml:space="preserve"
+ x="3305.5364"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;qsmaskinit</text>
+ <g
+ id="g3107"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3305.5364"
+ y="13490.509"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-3.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-3.svg
new file mode 100644
index 000000000000..d24d7d555dbc
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-3.svg
@@ -0,0 +1,636 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1039.3743"
+ height="594.19171"
+ viewBox="-44 -44 13821.733 7897.9895"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-gp-init-3.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="0.68224756"
+ inkscape:cx="617.89019"
+ inkscape:cy="625.84293"
+ inkscape:window-x="54"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g3153"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3090" />
+ </sodipodi:namedview>
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3"
+ d="m 6899.3032,45.520244 -2.8276,2480.757056 -2316.0141,-1.687 -2.8276,2179.8547 2321.1758,-0.8434 -2.7042,-1843.2376 2404.5142,-0.2109 16.1022,1993.2669 -7783.8345,-4.7279 -16.7936,2120.3946 2033.1033,-23.5344 2.0128,-1866.561 2051.9097,14.0785 2.0128,1838.2987 1280.8475,-4.728 14.608,-1830.1039 1312.2492,12.9229 14.608,1818.3367 2000.0059,20.4217 -12.279,-1841.4113 1304.168,1.6154 -12.279,2032.7059 -4638.6511,1.6154 19.5828,569.0378"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2450.4075,-11647.329)"
+ id="g3188">
+ <text
+ xml:space="preserve"
+ x="3145.9592"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ <g
+ id="g3107"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Root</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ rx="0"
+ height="6844.4546"
+ width="13658.751"
+ y="403.41983"
+ x="37.490932" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="662.8739"
+ x="153.26733"
+ xml:space="preserve">rcu_gp_init()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2329.9439,-11610.962)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5253.6904"
+ y="15407.032"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(3181.0246,-11647.329)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7415.4365"
+ y="17670.572"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ transform="translate(-1642.5375,-11610.962)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5258.0688"
+ y="15412.313"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ transform="translate(-151.71726,-11647.329)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-3484.4587,-11647.329)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7405.2607"
+ y="17670.572"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-35"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ transform="translate(-6817.1998,-11647.329)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7413.4688"
+ y="17670.566"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-75"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5473.7572,2235.0081 -582.9982,865.094"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8282.5391,2235.2701 582.9982,865.094"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 3523.1241,4448.1851 -582.9982,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 10268.171,4448.4471 583,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4939.6205,4448.1851 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8816.5958,4474.7811 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ x="7271.9297"
+ y="6023.2412"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-62"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg
new file mode 100644
index 000000000000..d05bc7b27edb
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg
@@ -0,0 +1,5135 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1626.5841"
+ height="6394.5298"
+ viewBox="-44 -44 21630.525 84996.019"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-gp.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-6"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3085"
+ style="overflow:visible">
+ <path
+ id="path3087"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3089"
+ style="overflow:visible">
+ <path
+ id="path3091"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093"
+ style="overflow:visible">
+ <path
+ id="path3095"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3097"
+ style="overflow:visible">
+ <path
+ id="path3099"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3101"
+ style="overflow:visible">
+ <path
+ id="path3103"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-7"
+ style="overflow:visible">
+ <path
+ id="path3940-5"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-79"
+ style="overflow:visible">
+ <path
+ id="path3940-20"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-37"
+ style="overflow:visible">
+ <path
+ id="path3946-5"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3081"
+ style="overflow:visible">
+ <path
+ id="path3083"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3085-9"
+ style="overflow:visible">
+ <path
+ id="path3087-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3089-2"
+ style="overflow:visible">
+ <path
+ id="path3091-8"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093-9"
+ style="overflow:visible">
+ <path
+ id="path3095-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3097-3"
+ style="overflow:visible">
+ <path
+ id="path3099-6"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-12"
+ style="overflow:visible">
+ <path
+ id="path3940-93"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-2"
+ style="overflow:visible">
+ <path
+ id="path3946-66"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3077"
+ style="overflow:visible">
+ <path
+ id="path3079"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3081-4"
+ style="overflow:visible">
+ <path
+ id="path3083-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3085-5"
+ style="overflow:visible">
+ <path
+ id="path3087-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3089-4"
+ style="overflow:visible">
+ <path
+ id="path3091-87"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093-1"
+ style="overflow:visible">
+ <path
+ id="path3095-72"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-72"
+ style="overflow:visible">
+ <path
+ id="path3940-26"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-6"
+ style="overflow:visible">
+ <path
+ id="path3940-25"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-8"
+ style="overflow:visible">
+ <path
+ id="path3946-62"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3179"
+ style="overflow:visible">
+ <path
+ id="path3181"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3183"
+ style="overflow:visible">
+ <path
+ id="path3185"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3187"
+ style="overflow:visible">
+ <path
+ id="path3189"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3191"
+ style="overflow:visible">
+ <path
+ id="path3193"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3195"
+ style="overflow:visible">
+ <path
+ id="path3197"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3199"
+ style="overflow:visible">
+ <path
+ id="path3201"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3203"
+ style="overflow:visible">
+ <path
+ id="path3205"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3207"
+ style="overflow:visible">
+ <path
+ id="path3209"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3211"
+ style="overflow:visible">
+ <path
+ id="path3213"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3215"
+ style="overflow:visible">
+ <path
+ id="path3217"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-5"
+ style="overflow:visible">
+ <path
+ id="path3940-52"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3150"
+ style="overflow:visible">
+ <path
+ id="path3152"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-9"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3156"
+ style="overflow:visible">
+ <path
+ id="path3158"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3160"
+ style="overflow:visible">
+ <path
+ id="path3162"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3164"
+ style="overflow:visible">
+ <path
+ id="path3166"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3168"
+ style="overflow:visible">
+ <path
+ id="path3170"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3172"
+ style="overflow:visible">
+ <path
+ id="path3174"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-8"
+ style="overflow:visible">
+ <path
+ id="path3940-7-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-17"
+ style="overflow:visible">
+ <path
+ id="path3940-8"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36-4"
+ style="overflow:visible">
+ <path
+ id="path3940-7-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-94"
+ style="overflow:visible">
+ <path
+ id="path3946-59"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3157"
+ style="overflow:visible">
+ <path
+ id="path3159"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3161"
+ style="overflow:visible">
+ <path
+ id="path3163"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3165"
+ style="overflow:visible">
+ <path
+ id="path3167"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3169"
+ style="overflow:visible">
+ <path
+ id="path3171"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3173"
+ style="overflow:visible">
+ <path
+ id="path3175"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3177"
+ style="overflow:visible">
+ <path
+ id="path3179"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3181"
+ style="overflow:visible">
+ <path
+ id="path3183"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3185"
+ style="overflow:visible">
+ <path
+ id="path3187"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3189"
+ style="overflow:visible">
+ <path
+ id="path3191"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3193"
+ style="overflow:visible">
+ <path
+ id="path3195"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3197"
+ style="overflow:visible">
+ <path
+ id="path3199"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-35"
+ style="overflow:visible">
+ <path
+ id="path3940-70"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3203-8"
+ style="overflow:visible">
+ <path
+ id="path3205-1"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-83"
+ style="overflow:visible">
+ <path
+ id="path3940-79"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3038"
+ style="overflow:visible">
+ <path
+ id="path3040"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3042"
+ style="overflow:visible">
+ <path
+ id="path3044"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="0.81932583"
+ inkscape:cx="840.45848"
+ inkscape:cy="5052.4242"
+ inkscape:window-x="787"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3079"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="413.99932px"
+ originy="5758.0031px" />
+ </sodipodi:namedview>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(4751.9713,-1307.071)">
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,2411.7612 0,6117.1391"
+ id="path3134-9-0-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,3342.6302 -3856.4573,0 10.6979,5757.1962 2918.1436,-2e-4"
+ id="path3134-9-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 6161.6776,3342.6302 3856.4574,0 -12.188,5757.1963 -2918.1436,-3e-4"
+ id="path3134-9-0-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240-->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150-->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <rect
+ x="4544.7305"
+ y="4603.417"
+ width="3240.0088"
+ height="2650.6289"
+ rx="0"
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ id="rect118"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="5073.3374"
+ y="6372.4521"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">rcu_accelerate_cbs()</text>
+ <g
+ id="g3107"
+ transform="translate(2715.7065,4700.8888)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="4773.3452"
+ y="4825.2578"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_prepare_for_idle()</text>
+ <rect
+ x="790.93585"
+ y="4630.8252"
+ width="3240.0088"
+ height="2650.6289"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.0005789, 60.00115781;stroke-dashoffset:0"
+ id="rect118-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="1319.5447"
+ y="6639.2261"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_accelerate_cbs()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7"
+ transform="translate(-1038.0776,4728.2971)">
+ <rect
+ id="rect112-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="1019.5512"
+ y="4852.666"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">note_gp_changes()</text>
+ <text
+ xml:space="preserve"
+ x="1319.5447"
+ y="6376.6328"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_advance_cbs()</text>
+ <text
+ xml:space="preserve"
+ x="1340.6649"
+ y="6111.4473"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">__note_gp_changes()</text>
+ <rect
+ x="5422.6279"
+ y="3041.8311"
+ width="1480.4871"
+ height="379.24637"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.0005789, 60.00115794;stroke-dashoffset:0"
+ id="rect118-3-9"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="5607.2734"
+ y="3283.3892"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">call_rcu()</text>
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ id="path3084"
+ sodipodi:cx="319.379"
+ sodipodi:cy="345.54001"
+ sodipodi:rx="65.917107"
+ sodipodi:ry="39.550262"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ transform="matrix(13.298129,0,0,13.298129,1915.7286,4523.6528)" />
+ <text
+ xml:space="preserve"
+ x="5853.9238"
+ y="8902.3623"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104">Wake up</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6165.7158"
+ y="9122.8174"
+ id="text3110"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3112"
+ x="6165.7158"
+ y="9122.8174">grace-period</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6162.8716"
+ y="9364.3564"
+ id="text3114"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3116"
+ x="6162.8716"
+ y="9364.3564">kernel thread</tspan></text>
+ <rect
+ x="8239.8516"
+ y="4608.7363"
+ width="3240.0088"
+ height="2650.6289"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057902, 60.00115804;stroke-dashoffset:0"
+ id="rect118-36"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="8768.4678"
+ y="6484.1562"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-75"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_accelerate_cbs()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-3"
+ transform="translate(6410.833,4706.2127)">
+ <rect
+ id="rect112-56"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="8329.5352"
+ y="4830.5771"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">takedown_cpu()</text>
+ <text
+ xml:space="preserve"
+ x="8335.4873"
+ y="5094.127"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_migrate_callbacks()</text>
+ <text
+ xml:space="preserve"
+ x="8768.4678"
+ y="6224.9038"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_advance_cbs()</text>
+ <text
+ xml:space="preserve"
+ x="3467.9963"
+ y="6987.9912"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7220.106"
+ y="6961.395"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="10905.331"
+ y="6961.395"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-5">Leaf</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ id="path3084-3"
+ sodipodi:cx="319.379"
+ sodipodi:cy="345.54001"
+ sodipodi:rx="65.917107"
+ sodipodi:ry="39.550262"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ transform="matrix(13.298129,0,0,13.298129,1872.6808,-2726.4833)" />
+ <text
+ xml:space="preserve"
+ x="5717.4517"
+ y="1785.2073"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-7">Phase One</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6119.668"
+ y="2005.6624"
+ id="text3110-5"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3112-3"
+ x="6119.668"
+ y="2005.6624">of Update</tspan></text>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-3"
+ d="m 6169.6477,11384.719 0,8777.145"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1749.0282,658.72243)"
+ id="g3188">
+ <g
+ id="g3107-62"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-1"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-7">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3137.9988"
+ y="13271.316"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-626"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3071">rcu_seq_start(rsp-&gt;gp_seq)</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118-0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057845, 60.00115689;stroke-dashoffset:0"
+ rx="0"
+ height="23612.516"
+ width="13607.611"
+ y="12709.474"
+ x="-663.88806" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-93"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="12968.928"
+ x="-548.11169"
+ xml:space="preserve">rcu_gp_init()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1628.5648,695.08943)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2479.6454,658.72243)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-2343.9166,695.08943)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ transform="translate(-853.09625,658.72243)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4185.8377,658.72243)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-7518.5789,658.72243)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4772.378,14541.058 -582.9982,865.094"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7581.1599,14541.32 582.9982,865.094"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2821.7449,16754.235 -582.9982,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9566.7916,16754.497 583.0014,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4238.2414,16754.235 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8115.2166,16780.831 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ id="g4504-3-9"
+ transform="translate(4164.6575,-5087.5013)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16888.277"
+ x="4344.877"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">End of</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0"
+ y="17119.1"
+ x="4578.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17119.1"
+ x="4578.7886"
+ id="tspan3112-5-9"
+ sodipodi:role="line">Last Grace</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3"
+ y="17350.271"
+ x="4581.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17350.271"
+ x="4581.7886"
+ id="tspan3116-2-6"
+ sodipodi:role="line">Period</tspan></text>
+ </g>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-5"
+ d="m 7845.2122,11943.62 -1595.7756,0"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send-36)" />
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ id="path3084-6"
+ sodipodi:cx="319.379"
+ sodipodi:cy="345.54001"
+ sodipodi:rx="65.917107"
+ sodipodi:ry="39.550262"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ transform="matrix(13.298129,0,0,13.298129,1915.7264,6279.0065)" />
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6165.6357"
+ y="10691.992"
+ id="text3110-0"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3112-6"
+ x="6165.6357"
+ y="10691.992">Grace-period</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6162.8696"
+ y="10947.994"
+ id="text3114-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3116-6"
+ x="6162.8696"
+ y="10947.994">kernel thread</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6165.3237"
+ y="11188.528"
+ id="text3114-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3116-8"
+ x="6165.3237"
+ y="11188.528">awakened</tspan></text>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-3-2"
+ d="m 6161.6774,9725.7319 0,531.9251"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1"
+ d="m 6169.1878,20208.525 -2.8277,1315.668 -5343.84363,17.12 -2.8276,6561.744 2039.08003,17.963 -2.7042,-2144.14 -491.6705,-0.211 -2.7042,-1993.689 1487.7179,-4.728 -17.7999,1812.453 2017.2372,-7.643 4.9533,-2151.572 -1405.5264,11.163 -10.9189,-1891.147 1739.2163,-2.718 -13.2006,4234.23 -1701.3596,1.395 -8.784,2107.712 1702.6392,-4.834 33.4144,-1867.716 1312.2491,12.923 14.608,1818.336 2000.0062,20.422 -12.279,-1841.411 1304.1668,1.615 -12.279,2032.706 -4638.6501,1.615 19.5828,569.038"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1618.635,9512.0768)"
+ id="g3147-7">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-8"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-4"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2469.7158,9475.7098)"
+ id="g3153-0">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-3"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-1"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-6">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-2353.8464,9512.0768)"
+ id="g3147-3-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-2"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5398.415"
+ y="15310.093"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinit</text>
+ <text
+ xml:space="preserve"
+ x="5398.415"
+ y="15545.01"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-5-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ </g>
+ <g
+ transform="translate(-863.02623,9475.7098)"
+ id="g3153-2-1"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-5"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-4"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-6">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4195.7676,9475.7098)"
+ id="g3153-20-5"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-4">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-7528.5086,9475.7098)"
+ id="g3153-28-5"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-4"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-4">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7699.7246"
+ y="17734.791"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-4"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinit</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="M 4762.4482,23358.047 4179.45,24223.141"
+ id="path3414-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7571.23,23358.309 582.9982,865.094"
+ id="path3414-9-3"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2811.8152,25571.224 -582.9982,865.094"
+ id="path3414-8-0"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9556.8622,25571.486 582.9988,865.094"
+ id="path3414-9-4-7"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4228.3115,25571.224 0,846.288"
+ id="path3414-8-3-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8105.2867,25597.82 0,846.288"
+ id="path3414-8-3-6-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <rect
+ ry="0"
+ id="rect118-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115756;stroke-dashoffset:0"
+ rx="0"
+ height="4418.4302"
+ width="4932.5845"
+ y="21654.297"
+ x="1395.3682" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="21852.52"
+ x="1530.812"
+ xml:space="preserve"
+ sodipodi:linespacing="125%">rcu_init_new_rnp()<tspan
+ style="font-size:192px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3307"> or</tspan></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="22120.592"
+ x="1530.812"
+ xml:space="preserve">rcu_cleanup_dead_rnp()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-6"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="22389.539"
+ x="1533.6567"
+ xml:space="preserve"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:192px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3327">(optional)</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1739.0986,9475.7098)"
+ id="g3188-8">
+ <text
+ xml:space="preserve"
+ x="3305.5364"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-84"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;qsmaskinit</text>
+ <g
+ id="g3107-31"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-4"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-9"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-20"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3305.5364"
+ y="13490.509"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-5-89"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ </g>
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-10"
+ d="m 6187.9943,28881.474 -2.8275,2480.757 -2316.0141,-1.687 -2.8276,2179.854 2321.1757,-0.843 -2.7041,-1843.237 2404.5141,-0.212 16.1022,1993.267 -7783.83443,-4.728 -16.7937,2120.395 2033.10343,-23.534 2.0128,-1866.562 2051.9098,14.079 2.0128,1838.299 1280.8474,-4.728 14.608,-1830.104 1312.2492,12.923 14.608,1818.336 2000.0057,20.422 -12.279,-1841.411 1304.167,1.615 -12.279,2032.706 -4638.6499,1.615 19.5828,569.038"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1739.0986,17188.625)"
+ id="g3188-6">
+ <g
+ id="g3107-5"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-94"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-90"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-1">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3147.9268"
+ y="13240.524"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1618.6352,17224.992)"
+ id="g3147-1">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-1"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-9"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5263.1094"
+ y="15411.646"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-92"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2469.7158,17188.625)"
+ id="g3153-7">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-67"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-36"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-63"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-94">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7417.4053"
+ y="17655.502"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-759"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ transform="translate(-2353.8462,17224.992)"
+ id="g3147-3-8"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-1"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-2"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-9"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5246.1548"
+ y="15411.648"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-87"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ transform="translate(-863.02613,17188.625)"
+ id="g3153-2-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-5">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4195.7673,17188.625)"
+ id="g3153-20-0"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-38"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-6">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7433.8257"
+ y="17682.098"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <g
+ transform="translate(-7528.5085,17188.625)"
+ id="g3153-28-1"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-1"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-59"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-4"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-8">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7415.4404"
+ y="17682.098"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4762.4484,31070.961 -582.9982,865.095"
+ id="path3414-0"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7571.2303,31071.223 582.9982,865.095"
+ id="path3414-9-30"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2811.8153,33284.138 -582.9982,865.094"
+ id="path3414-8-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9556.862,33284.401 582.999,865.093"
+ id="path3414-9-4-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4228.3118,33284.138 0,846.288"
+ id="path3414-8-3-4"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8105.287,33310.734 0,846.288"
+ id="path3414-8-3-6-4"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-8"
+ d="m 11248.729,43927.515 3383.749,-0.843 7.995,1860.989"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3"
+ d="m 14641.723,41609.377 -2.828,1541.346 -3303.353,-1.688"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-6"
+ d="m 816.24399,43920.114 -3929.12029,17.964 20.2152,2632.051"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3-2"
+ d="m -3122.1199,40492.4 12.2312,2669.729 3867.53038,7.717"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-4"
+ d="m 6180.0812,36613.063 -2.827,638.638 -5325.0381,35.926 -9.78989,7279.202 2659.62569,0 0,-2260.682 -1196.8316,0 0,-1861.738 1462.7942,0 0,2127.7 3723.476,0 0,1861.738 2035.5457,-11.246 -12.28,-1788.219 1191.3338,1.616 15.928,1289.854 520.347,0.202 m 0,0 -15.641,-1570.133 -2629.7318,-18.604 3.165,-2124.92 -2305.4983,-7.354 0,-2287.279 5319.2511,0 0,7180.99 m 0,0 0,19229.094 -4441.5746,0"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <rect
+ ry="0"
+ id="rect118-7"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ rx="0"
+ height="8254.9336"
+ width="14128.912"
+ y="37009.492"
+ x="-719.34235" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-24"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="37286.184"
+ x="-573.74298"
+ xml:space="preserve">rcu_gp_fqs()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1629.528,25916.616)"
+ id="g3147-0">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-62"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-90"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5250.5327"
+ y="15512.733"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-35-8"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2480.6088,25880.249)"
+ id="g3153-1">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-31"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-10"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-34"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-03"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-91">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-2342.9531,25916.616)"
+ id="g3147-3-9"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5284.6885"
+ y="15500.379"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-3"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <g
+ transform="translate(-852.13285,25880.249)"
+ id="g3153-2-8"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-0"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-56"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-4"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-0">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4184.8743,25880.249)"
+ id="g3153-20-04"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-62"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-67"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-7517.6112,25880.249)"
+ id="g3153-28-8"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-7"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-2"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-82"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-9">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7428.2939"
+ y="17707.271"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-75-6"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4773.3421,39762.585 -582.9986,865.094"
+ id="path3414-02"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7582.1232,39762.847 582.999,865.094"
+ id="path3414-9-7"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2822.7083,41975.762 -582.9982,865.094"
+ id="path3414-8-6"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9567.7542,41976.024 583.0018,865.094"
+ id="path3414-9-4-1"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4239.2048,41975.762 0,846.288"
+ id="path3414-8-3-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8116.1802,42002.358 0,846.288"
+ id="path3414-8-3-6-2"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <rect
+ ry="0"
+ id="rect118-1-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057924, 60.00115835;stroke-dashoffset:0"
+ rx="0"
+ height="7164.1621"
+ width="13301.43"
+ y="37551.07"
+ x="-474.37598" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-5"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="37802.488"
+ x="-342.01831"
+ xml:space="preserve"
+ sodipodi:linespacing="125%">force_qs_rnp()<tspan
+ style="font-size:192px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3307-9" /></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-9"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="38114.047"
+ x="-334.33856"
+ xml:space="preserve">rcu_watching_snap_save()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1749.9916,25880.249)"
+ id="g3188-1">
+ <g
+ id="g3107-4"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-91"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-58">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3158.8521"
+ y="13313.027"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-70"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="38425.035"
+ x="-337.79462"
+ xml:space="preserve">rcu_watching_snap_recheck()</text>
+ <text
+ xml:space="preserve"
+ x="9907.8887"
+ y="43568.723"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-62-4"
+ style="font-size:192.00001526px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ <g
+ id="g4504"
+ transform="translate(10024.106,24062.466)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3089"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-80"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-4"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-29"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-61"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-04"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-22"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3148-9-9"
+ transform="translate(9995.8972,46544.783)">
+ <rect
+ x="3592.3828"
+ y="-4715.7246"
+ width="3164.783"
+ height="769.99048"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4418.6582"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">ct_kernel_exit_state()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4165.7954"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">atomic_add_return()</text>
+ </g>
+ <g
+ id="g3148-9-9-2"
+ transform="translate(9995.8972,49205.888)">
+ <rect
+ x="3592.3828"
+ y="-4715.7246"
+ width="3164.783"
+ height="769.99048"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3-6"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4418.6582"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">ct_kernel_enter_state()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4165.7954"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">atomic_add_return()</text>
+ </g>
+ <g
+ id="g4504-7"
+ transform="translate(10042.913,29290.642)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-9"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-0"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-2"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-3-2"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-7"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-5"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-6"
+ transform="translate(-7705.0623,22903.647)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-1"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-7-0"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-9"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-2"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-0"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3148-9-9-3"
+ transform="translate(-8306.8632,45879.159)">
+ <rect
+ x="3592.3828"
+ y="-4981.6865"
+ width="3728.9751"
+ height="2265.0989"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3-7"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4684.6201"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4431.7573"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_cleanup_dying_idle_cpu()</text>
+ <g
+ transform="translate(1783.3183,-5255.3491)"
+ id="g3107-7-5"
+ style="fill:none;stroke-width:0.025in">
+ <rect
+ x="2084.55"
+ y="949.37109"
+ width="2809.1992"
+ height="1370.8721"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-5-3" />
+ <rect
+ x="2084.55"
+ y="1025.3964"
+ width="2809.1992"
+ height="1294.8468"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-3-3-5" />
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-6-6-2-6"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-3526.4448"
+ x="4241.8574"
+ xml:space="preserve">-&gt;qsmaskinitnext</text>
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-2987.4167"
+ x="6305.1484"
+ xml:space="preserve"><tspan
+ id="tspan3104-6-9"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ </g>
+ <g
+ id="g4504-7-2"
+ transform="translate(-7686.2563,30073.332)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-9-2"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-2-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-0-9"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-2-7"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-3-3"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-7-6"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-5-1"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3206"
+ transform="translate(-752.44253,40565.329)">
+ <rect
+ ry="0"
+ id="rect118-3-5-1-3-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00058007, 60.00116001;stroke-dashoffset:0"
+ rx="0"
+ height="2265.0989"
+ width="3728.9751"
+ y="3382.2036"
+ x="-3958.3845" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-6-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="3679.27"
+ x="-3804.9949"
+ xml:space="preserve">rcutree_report_cpu_starting()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7-5-0"
+ transform="translate(-5767.4491,3108.5424)">
+ <rect
+ id="rect112-5-3-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3-5-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="-3308.9099"
+ y="4837.4453"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ <text
+ xml:space="preserve"
+ x="-1245.6189"
+ y="5376.4731"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-2-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-9-6">Leaf</tspan></text>
+ </g>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3-6"
+ d="m 10723.215,43926.861 467.335,8.625"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send-8)"
+ d="m 4431.0572,60276.11 16.472,2346.582"
+ id="path3134-9-0-3-1-9-9"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(-59.697399,41012.242)"
+ id="g3188-83">
+ <text
+ xml:space="preserve"
+ x="3172.5554"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-80"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ <g
+ id="g3107-40"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-919"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-25"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-4">Root</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118-4"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057845, 60.00115689;stroke-dashoffset:0"
+ rx="0"
+ height="7164.1641"
+ width="13639.945"
+ y="52743.297"
+ x="-2453.8081" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-99"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="52950.113"
+ x="-2356.8381"
+ xml:space="preserve">rcu_report_rnp()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(-180.16099,41048.609)"
+ id="g3147-36">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-0"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-50"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-29"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(670.91971,41012.242)"
+ id="g3153-4">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-35"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-17"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-4"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-14">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4152.6419,41048.609)"
+ id="g3147-3-6"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-9"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-4"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5284.9155"
+ y="15386.685"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-3-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <g
+ transform="translate(-2661.8217,41012.242)"
+ id="g3153-2-6"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-4"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-88"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-5994.5632,41012.242)"
+ id="g3153-20-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-8"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-8"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-68"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-3">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-9327.3041,41012.242)"
+ id="g3153-28-83"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-3"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-80"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-47"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-6">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7422.3945"
+ y="17661.012"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-67"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2963.6526,54894.579 -582.9982,865.092"
+ id="path3414-89"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5772.4344,54894.841 582.9982,865.092"
+ id="path3414-9-0"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 1013.0193,57107.754 -582.99819,865.094"
+ id="path3414-8-68"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7758.0666,57108.016 583,865.094"
+ id="path3414-9-4-79"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2429.5159,57107.754 0,846.288"
+ id="path3414-8-3-0"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 6306.4911,57134.35 0,846.288"
+ id="path3414-8-3-6-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-33"
+ d="m 4421.0737,51833.378 -2.8276,1315.669 -5343.84362,17.119 -2.8276,6561.745 2039.08002,17.963 -2.7043,-2144.141 -491.67069,-0.211 -2.7042,-1993.689 1487.71819,-4.728 -17.8001,1812.453 2017.2374,-7.643 4.9532,-2151.571 -1405.5263,11.162 -10.9191,-1891.146 1739.2165,-2.718 0.1197,7086.03"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 4432.9209,44194.481 8.8008,4666.688 -2616.9163,17.119 15.9788,1446.406 2603.2718,-0.843 -29.6181,2086.665"
+ id="path3134-9-0-3-1-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccccc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:none"
+ d="m 4423.9777,48861.171 2616.9159,17.119 -15.979,1465.213 -2584.4649,-19.65"
+ id="path3134-9-0-3-1-9"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <g
+ transform="translate(-1706.1312,54634.242)"
+ id="g3115">
+ <rect
+ x="4485.6865"
+ y="-8571.0352"
+ width="3296.428"
+ height="2199.2754"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057923, 60.00115859;stroke-dashoffset:0"
+ id="rect118-3-3"
+ ry="0" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7-2"
+ transform="translate(2656.673,-8952.2968)">
+ <rect
+ id="rect112-5-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3-52"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="4714.3018"
+ y="-8349.1943"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">note_gp_changes()</text>
+ <text
+ xml:space="preserve"
+ x="5014.2954"
+ y="-7170.978"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rdp-&gt;gp_seq</text>
+ <text
+ xml:space="preserve"
+ x="5035.4155"
+ y="-7436.1636"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">__note_gp_changes()</text>
+ <text
+ xml:space="preserve"
+ x="7162.7471"
+ y="-6692.6006"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-79"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-6">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-3299.9731,54048.57)"
+ id="g3148">
+ <rect
+ ry="0"
+ id="rect118-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="412.66794"
+ width="3240.0085"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="3745.7725"
+ xml:space="preserve">rcu_note_context_switch()</text>
+ </g>
+ <g
+ transform="translate(1881.1886,54048.57)"
+ id="g3148-5">
+ <rect
+ ry="0"
+ id="rect118-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="412.66794"
+ width="3240.0085"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="3745.7725"
+ xml:space="preserve">rcu_sched_clock_irq()</text>
+ </g>
+ <g
+ transform="translate(-850.30204,55463.106)"
+ id="g3148-9">
+ <rect
+ ry="0"
+ id="rect118-3-5-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="864.02148"
+ width="3540.9114"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="3745.7725"
+ xml:space="preserve">rcu_core()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-0"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4165.7954"
+ x="3745.7725"
+ xml:space="preserve">rcu_check_quiescent_state()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-0-9"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-3914.085"
+ x="3745.7725"
+ xml:space="preserve">rcu__report_qs_rdp())</text>
+ </g>
+ <g
+ id="g4504-3"
+ transform="translate(3886.2577,30763.697)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-0"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-4"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-3-9-1"
+ transform="translate(3886.2577,34216.283)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1-0"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2-4"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7-8"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0-7"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5-9-0"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3-8"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-6-6"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-3-0"
+ transform="translate(-4075.0211,30763.697)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,228.84485,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-6"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-26"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-1"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-8"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5-7"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-9"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-3-9-0"
+ transform="translate(-4181.4064,34216.283)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1-2"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0-5"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5-9-9"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3-2"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-6-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:none"
+ d="m 8448.9566,48370.097 0,2393.663"
+ id="path3134-9-0-3-1-9-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:none"
+ d="m 390.28991,48370.097 0,2393.663"
+ id="path3134-9-0-3-1-9-8-9"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ id="g4504-2"
+ transform="translate(-143.72569,46137.076)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-4"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-79"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4273.4326"
+ xml:space="preserve"><tspan
+ id="tspan3104-3"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Wake up</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-92"
+ y="17055.541"
+ x="4585.2246"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4585.2246"
+ id="tspan3112-8"
+ sodipodi:role="line">grace-period</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-3"
+ y="17297.08"
+ x="4582.3804"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4582.3804"
+ id="tspan3116-0"
+ sodipodi:role="line">kernel thread</tspan></text>
+ </g>
+ <g
+ transform="translate(-707.64089,66256.889)"
+ id="g3148-2">
+ <rect
+ ry="0"
+ id="rect118-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="412.66794"
+ width="3240.0085"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="4064.9268"
+ xml:space="preserve">rcu_report_qs_rsp()</text>
+ </g>
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ id="path3084-6-9"
+ sodipodi:cx="319.379"
+ sodipodi:cy="345.54001"
+ sodipodi:rx="65.917107"
+ sodipodi:ry="39.550262"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ transform="matrix(13.298129,0,0,13.298129,2044.7501,59781.881)" />
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6294.6587"
+ y="64194.863"
+ id="text3110-0-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3112-6-5"
+ x="6294.6587"
+ y="64194.863">Grace-period</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6291.8931"
+ y="64450.863"
+ id="text3114-2-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3116-6-9"
+ x="6291.8931"
+ y="64450.863">kernel thread</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ x="6294.3472"
+ y="64691.398"
+ id="text3114-1-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan3116-8-5"
+ x="6294.3472"
+ y="64691.398">awakened</tspan></text>
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-3-2-7"
+ d="m 5310.5974,63210.805 984.0615,0 -3.9578,549.726"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-99"
+ d="m 6322.9337,64896.388 -2.8276,2480.757 -2316.0141,-1.687 -2.8276,2179.855 2321.1758,-0.844 -2.7042,-1843.237 2404.5142,-0.212 16.1023,1993.267 -7783.83452,-4.728 -16.79346,2120.395 2033.10318,-23.535 2.0128,-1866.561 2051.9096,14.08 2.0128,1838.298 1280.8474,-4.728 14.6081,-1830.105 1312.2491,12.923 14.608,1818.337 2000.0093,20.422 -12.279,-1841.412 1304.1722,1.616 -12.279,2032.706 -4638.6586,1.616 19.5827,569.037"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1874.038,53203.538)"
+ id="g3188-7">
+ <g
+ id="g3107-53"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112-49"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-02"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-19">Root</tspan></text>
+ <text
+ xml:space="preserve"
+ x="3175.896"
+ y="13240.11"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118-6"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057845, 60.00115689;stroke-dashoffset:0"
+ rx="0"
+ height="14649.609"
+ width="13482.601"
+ y="65254.539"
+ x="-538.87689" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-21"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="65513.996"
+ x="-423.10056"
+ xml:space="preserve">rcu_gp_cleanup()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1753.5744,53239.905)"
+ id="g3147-2">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-07"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-1"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5264.4829"
+ y="15411.231"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-5">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-1"
+ transform="translate(7817.6676,69212.346)">
+ <rect
+ id="rect112-7-1-90"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-56"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="12322.059"
+ y="71472.641"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-77"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-4">Leaf</tspan></text>
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-9"
+ d="m 6315.6122,72629.054 -20.9533,8108.684 1648.968,0"
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-62-6"
+ transform="translate(2814.6217,72520.234)">
+ <rect
+ id="rect112-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-1-4"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="7319.022"
+ y="74780.406"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-7-7">Root</tspan></text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(1746.2528,60972.572)"
+ id="g3147-9">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-2"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-02"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-5"
+ transform="translate(7810.3459,76945.013)">
+ <rect
+ id="rect112-7-1-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="12314.736"
+ y="79205.188"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-8">Leaf</tspan></text>
+ <g
+ transform="translate(-2226.2288,60972.572)"
+ id="g3147-3-7"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-3"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-6"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-1"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ transform="translate(-735.4075,60936.205)"
+ id="g3153-2-9"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-3"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-1-4"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-9"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-4-8"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-7">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4068.1496,60936.205)"
+ id="g3153-20-8"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-4"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-6-5">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-7400.8907,60936.205)"
+ id="g3153-28-0"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-3-8"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-6-2">Leaf</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4890.0661,74818.542 -582.9982,865.094"
+ id="path3414-5"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7698.8481,74818.804 582.998,865.094"
+ id="path3414-9-5"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2939.433,77031.719 -582.9982,865.094"
+ id="path3414-8-4-6"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9684.4834,77031.981 583.0036,865.094"
+ id="path3414-9-4-7-0"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4355.9293,77031.719 0,846.288"
+ id="path3414-8-3-65"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8232.9046,77058.315 0,846.288"
+ id="path3414-8-3-6-6-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ transform="translate(-2218.9069,53239.905)"
+ id="g3147-3-64"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6-62"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0-8"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6-96"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5274.1216"
+ y="15411.231"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-6">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ transform="translate(-728.08545,53203.538)"
+ id="g3153-2-0"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6-7"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1-01"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8-0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7-1"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9-3">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-4060.8278,53203.538)"
+ id="g3153-20-7"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2-7"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3-2"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5-4"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92-5">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7435.1987"
+ y="17708.281"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-1">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <g
+ transform="translate(-7393.5687,53203.538)"
+ id="g3153-28-02"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3-9"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6-94"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1-5">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7416.8125"
+ y="17708.281"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-35"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-62">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4897.3878,67085.876 -582.9982,865.094"
+ id="path3414-03"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 7706.1695,67086.138 582.9982,865.094"
+ id="path3414-9-78"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 2946.7546,69299.053 -582.9981,865.094"
+ id="path3414-8-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 9691.8054,69299.315 583.0036,865.094"
+ id="path3414-9-4-6"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4363.251,69299.053 0,846.288"
+ id="path3414-8-3-04"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8240.2262,69325.649 0,846.288"
+ id="path3414-8-3-6-67"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4504-3-9-6"
+ transform="translate(4290.2512,63653.93)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1-09"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16888.277"
+ x="4344.877"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7-5"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Start of</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0-9"
+ y="17119.1"
+ x="4578.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17119.1"
+ x="4578.7886"
+ id="tspan3112-5-9-7"
+ sodipodi:role="line">Next Grace</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3-85"
+ y="17350.271"
+ x="4581.7886"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17350.271"
+ x="4581.7886"
+ id="tspan3116-2-6-3"
+ sodipodi:role="line">Period</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 4406.3256,79248.348 -0.01,5813.579"
+ id="path3134-9-0-3-37"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 4406.3181,82402.301 -2393.663,0.512 0,1196.832 2393.663,-0.512"
+ id="path3134-9-0-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251251;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 4406.3181,82402.301 2393.6631,0.512 0,1196.832 -2393.6631,-0.512"
+ id="path3134-9-0-7-7"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <rect
+ x="578.16779"
+ y="82839.773"
+ width="2844.0972"
+ height="360.77411"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057845, 60.00115702;stroke-dashoffset:0"
+ id="rect118-3-4"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="806.7832"
+ y="83088.211"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-19"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_sched_clock_irq()</text>
+ <rect
+ x="5314.2671"
+ y="82817.688"
+ width="2975.115"
+ height="382.86298"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057858, 60.00115716;stroke-dashoffset:0"
+ id="rect118-36-0"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="5409.8989"
+ y="83063.711"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6-9"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_cleanup_after_idle()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-88"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="81443.047"
+ x="3264.7983"
+ xml:space="preserve">rcu_advance_cbs()</text>
+ <rect
+ id="rect112-58"
+ style="fill:none;stroke:#000000;stroke-width:29.99999809;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="80561.273"
+ x="2991.7173" />
+ <rect
+ id="rect112-3-4"
+ style="fill:none;stroke:#000000;stroke-width:29.99999809;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="80637.297"
+ x="2991.7173" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3-7-37"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="81872.406"
+ x="5411.5601"
+ xml:space="preserve"><tspan
+ id="tspan3104-6-5-13"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-3-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="81232.938"
+ x="3264.7983"
+ xml:space="preserve">__note_gp_changes()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3049"
+ transform="translate(-1728.7601,83820.41)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,1872.6808,-2726.4833)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-3-0"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-6-9"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="1785.2073"
+ x="5717.4517"
+ xml:space="preserve"><tspan
+ id="tspan3104-7-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Phase Two</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-5-9"
+ y="2005.6624"
+ x="6119.668"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="2005.6624"
+ x="6119.668"
+ id="tspan3112-3-9"
+ sodipodi:role="line">of Update</tspan></text>
+ </g>
+ <rect
+ x="3342.4805"
+ y="83998.438"
+ width="1994.7195"
+ height="664.90662"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057818, 60.00115636;stroke-dashoffset:0"
+ id="rect118-36-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3608.4419"
+ y="84264.398"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">RCU_SOFTIRQ</text>
+ <text
+ xml:space="preserve"
+ x="3608.4419"
+ y="84530.367"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-9-6-6-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_do_batch()</text>
+ <text
+ xml:space="preserve"
+ x="6698.9019"
+ y="70885.211"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-7">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ <text
+ xml:space="preserve"
+ x="10023.457"
+ y="70885.234"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-9">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>
+ <text
+ xml:space="preserve"
+ x="5023.3389"
+ y="74209.773"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-36-36"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan
+ style="font-size:172.87567139px"
+ id="tspan3166-0">rcu_seq_end(&amp;rsp-&gt;gp_seq)</tspan></text>
+ <text
+ xml:space="preserve"
+ x="6562.5884"
+ y="34870.727"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg
new file mode 100644
index 000000000000..a92356ce4011
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg
@@ -0,0 +1,775 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="613.22784"
+ height="707.07056"
+ viewBox="-44 -44 8154.7829 9398.3736"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-hotplug.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-0"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-6"
+ style="overflow:visible">
+ <path
+ id="path3940-26"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-8"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-367"
+ style="overflow:visible">
+ <path
+ id="path3940-5"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-56"
+ style="overflow:visible">
+ <path
+ id="path3946-2"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3081"
+ style="overflow:visible">
+ <path
+ id="path3083"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3085"
+ style="overflow:visible">
+ <path
+ id="path3087"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3089"
+ style="overflow:visible">
+ <path
+ id="path3091"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3093"
+ style="overflow:visible">
+ <path
+ id="path3095"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker3097"
+ style="overflow:visible">
+ <path
+ id="path3099"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-9"
+ style="overflow:visible">
+ <path
+ id="path3940-1"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3675"
+ style="overflow:visible">
+ <path
+ id="path3940-3"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1148"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="1.4142136"
+ inkscape:cx="325.41695"
+ inkscape:cy="364.94502"
+ inkscape:window-x="833"
+ inkscape:window-y="24"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg2"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5"
+ inkscape:snap-global="false">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3154"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true"
+ originx="65.610033px"
+ originy="-659.12429px" />
+ </sodipodi:namedview>
+ <path
+ sodipodi:nodetypes="cc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3-5"
+ d="m 5749.1555,47.151064 2.828,9167.338436"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1"
+ d="m 5746.8844,5080.2018 -4107.7813,-0.8434 20.2152,2632.0511"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <path
+ sodipodi:nodetypes="ccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3-1-3"
+ d="m 1629.8595,1633.6804 12.2312,2669.7294 4055.5945,7.7159"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ id="g3115"
+ transform="translate(1657.6576,12154.29)">
+ <rect
+ ry="0"
+ id="rect118-3"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057923, 60.00115859;stroke-dashoffset:0"
+ rx="0"
+ height="2349.7295"
+ width="3992.2642"
+ y="-8909.5498"
+ x="2379.3704" />
+ <g
+ transform="translate(582.16224,-9085.2783)"
+ id="g3107-7"
+ style="fill:none;stroke-width:0.025in">
+ <rect
+ x="2084.55"
+ y="949.37109"
+ width="2809.1992"
+ height="1370.8721"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-5" />
+ <rect
+ x="2084.55"
+ y="1025.3964"
+ width="2809.1992"
+ height="1294.8468"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-3-3" />
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-6-6-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-7356.375"
+ x="2774.7393"
+ xml:space="preserve">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-8652.5312"
+ x="2466.7822"
+ xml:space="preserve">rcu_watching_snap_save()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-2-7-2-0"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-8368.1475"
+ x="2463.3262"
+ xml:space="preserve">rcu_watching_snap_recheck()</text>
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-6817.3472"
+ x="5103.9922"
+ xml:space="preserve"><tspan
+ id="tspan3104-6"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ </g>
+ <g
+ id="g4504"
+ transform="translate(-2953.0872,-15955.072)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3148-9-9"
+ transform="translate(-3554.8919,7020.44)">
+ <rect
+ x="3592.3828"
+ y="-4981.6865"
+ width="3728.9751"
+ height="2265.0989"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ id="rect118-3-5-1-3"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4684.6201"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text>
+ <text
+ xml:space="preserve"
+ x="3745.7725"
+ y="-4431.7573"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-3-27-0-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_cleanup_dying_idle_cpu()</text>
+ <g
+ transform="translate(1783.3183,-5255.3491)"
+ id="g3107-7-5"
+ style="fill:none;stroke-width:0.025in">
+ <rect
+ x="2084.55"
+ y="949.37109"
+ width="2809.1992"
+ height="1370.8721"
+ rx="0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-5-3" />
+ <rect
+ x="2084.55"
+ y="1025.3964"
+ width="2809.1992"
+ height="1294.8468"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ id="rect112-3-3-5" />
+ </g>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-6-6-2-6"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-3526.4448"
+ x="4241.8574"
+ xml:space="preserve">-&gt;qsmaskinitnext</text>
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-3-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-2987.4167"
+ x="6305.1484"
+ xml:space="preserve"><tspan
+ id="tspan3104-6-9"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Leaf</tspan></text>
+ </g>
+ <g
+ id="g4504-7"
+ transform="translate(-2934.2808,-8785.3871)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-9"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-0"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-2"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-3"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-7"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-5"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g3206"
+ transform="translate(3999.537,1706.6099)">
+ <rect
+ ry="0"
+ id="rect118-3-5-1-3-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00058007, 60.00116001;stroke-dashoffset:0"
+ rx="0"
+ height="2265.0989"
+ width="3728.9751"
+ y="3382.2036"
+ x="-3958.3845" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-6-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="3679.27"
+ x="-3804.9949"
+ xml:space="preserve">rcutree_report_cpu_starting()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7-5-0"
+ transform="translate(-5767.4491,3108.5424)">
+ <rect
+ id="rect112-5-3-9"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3-5-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="-3308.9099"
+ y="4837.4453"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmaskinitnext</text>
+ <text
+ xml:space="preserve"
+ x="-1245.6189"
+ y="5376.4731"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-2-0"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-9-6">Leaf</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg
new file mode 100644
index 000000000000..7d6c5f7e505c
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg
@@ -0,0 +1,1095 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="1037.9601"
+ height="1373.2583"
+ viewBox="-44 -44 13802.927 18253.333"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="TreeRCU-qs.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3940"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutS"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutS"
+ style="overflow:visible">
+ <path
+ id="path4073"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.2,0.2)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="TriangleOutM"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="TriangleOutM"
+ style="overflow:visible">
+ <path
+ id="path4070"
+ d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="scale(0.4,0.4)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend"
+ style="overflow:visible">
+ <path
+ id="path3952"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3946"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Mend-7"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3952-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="scale(-0.6,-0.6)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-3"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-6"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-1"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-0"
+ style="overflow:visible">
+ <path
+ inkscape:connector-curvature="0"
+ id="path3940-9"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-3"
+ style="overflow:visible">
+ <path
+ id="path3946-1"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3946-7"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="marker4880"
+ style="overflow:visible">
+ <path
+ id="path4882"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-5"
+ style="overflow:visible">
+ <path
+ id="path3946-0"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-6"
+ style="overflow:visible">
+ <path
+ id="path3946-10"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-36"
+ style="overflow:visible">
+ <path
+ id="path3940-0"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-6"
+ style="overflow:visible">
+ <path
+ id="path3940-26"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send-8"
+ style="overflow:visible">
+ <path
+ id="path3940-7"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="true"
+ inkscape:zoom="0.96484375"
+ inkscape:cx="507.0191"
+ inkscape:cy="885.62207"
+ inkscape:window-x="47"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g3115"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5">
+ <inkscape:grid
+ type="xygrid"
+ id="grid3381" />
+ </sodipodi:namedview>
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send-8)"
+ d="m 6922.3555,14693.733 16.472,2346.582"
+ id="path3134-9-0-3-1-9-9"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2431.6011,-4570.136)"
+ id="g3188">
+ <text
+ xml:space="preserve"
+ x="3172.5554"
+ y="13255.592"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ <g
+ id="g3107"
+ transform="translate(947.90548,11584.029)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5452.3052"
+ y="13844.535"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5">Root</tspan></text>
+ </g>
+ <rect
+ ry="0"
+ id="rect118"
+ style="fill:none;stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ rx="0"
+ height="7164.1636"
+ width="13639.945"
+ y="7160.9038"
+ x="37.490932" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="7367.7192"
+ x="134.46094"
+ xml:space="preserve">rcu_report_rnp()</text>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(2311.1375,-4533.769)"
+ id="g3147">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ </g>
+ <g
+ style="fill:none;stroke-width:0.025in"
+ transform="translate(3162.2182,-4570.136)"
+ id="g3153">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-1661.3439,-4533.769)"
+ id="g3147-3"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-6"
+ transform="translate(3054.6101,13760.052)">
+ <rect
+ id="rect112-7-0"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="5284.9155"
+ y="15386.685"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <g
+ transform="translate(-170.52365,-4570.136)"
+ id="g3153-2"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-6"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-1"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-8"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-9">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-3503.2651,-4570.136)"
+ id="g3153-20"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-2"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-3"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-7"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-92">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-6836.0062,-4570.136)"
+ id="g3153-28"
+ style="fill:none;stroke-width:0.025in">
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-6-9-9"
+ transform="translate(5213.0126,16008.808)">
+ <rect
+ id="rect112-7-1-7"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-5-2-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="9717.4141"
+ y="18269.314"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3-7-35-7-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6-5-6-0-1">Leaf</tspan></text>
+ <text
+ xml:space="preserve"
+ x="7422.3945"
+ y="17661.012"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-67"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;qsmask &amp;= ~-&gt;grpmask</text>
+ </g>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 5454.9508,9312.2011 -582.9982,865.0929"
+ id="path3414"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8263.7327,9312.4631 582.9982,865.0929"
+ id="path3414-9"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812813px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 3504.3177,11525.377 -582.9982,865.094"
+ id="path3414-8"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 10249.365,11525.639 583,865.094"
+ id="path3414-9-4"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 4920.8141,11525.377 0,846.288"
+ id="path3414-8-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:13.29812717px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
+ d="m 8797.7894,11551.973 0,846.288"
+ id="path3414-8-3-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ sodipodi:nodetypes="cccccccccccccccc"
+ inkscape:connector-curvature="0"
+ id="path3134-9-0-3"
+ d="m 6912.3719,6251.0009 -2.8276,1315.669 -5343.8436,17.119 -2.8276,6561.7441 2039.08,17.963 -2.7042,-2144.14 -491.6706,-0.211 -2.7042,-1993.689 1487.718,-4.728 -17.8001,1812.453 2017.2374,-7.643 4.9532,-2151.5715 -1405.5263,11.1629 -10.9191,-1891.1465 1739.2165,-2.718 0.1141,7086.0301"
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)" />
+ <g
+ id="g4405"
+ transform="translate(1241.222,9051.8644)">
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send)"
+ d="m 5694.6259,-9006.994 -2.828,3233.9212 -2616.9163,17.1191 15.9788,1446.406 2603.2719,-0.8434 -29.6182,2086.6656"
+ id="path3134-9-0-3-1"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccccc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:none"
+ d="m 5674.0539,-5773.0705 2616.9163,17.1191 -15.9788,1465.2124 -2584.4655,-19.6498"
+ id="path3134-9-0-3-1-9"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cccc" />
+ <g
+ transform="translate(-456.05505,0)"
+ id="g3115">
+ <rect
+ x="4485.6865"
+ y="-8571.0352"
+ width="3296.428"
+ height="2199.2754"
+ rx="0"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057923, 60.00115859;stroke-dashoffset:0"
+ id="rect118-3"
+ ry="0" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g3107-7"
+ transform="translate(2656.673,-8952.2968)">
+ <rect
+ id="rect112-5"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="4714.3018"
+ y="-8349.1943"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">note_gp_changes()</text>
+ <text
+ xml:space="preserve"
+ x="5014.2954"
+ y="-7170.978"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rdp-&gt;gp_seq</text>
+ <text
+ xml:space="preserve"
+ x="5035.4155"
+ y="-7436.1636"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-6-6-2"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">__note_gp_changes()</text>
+ <text
+ xml:space="preserve"
+ x="7162.7471"
+ y="-6692.6006"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7-5-1-2-3"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ sodipodi:linespacing="125%"><tspan
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"
+ id="tspan3104-6">Leaf</tspan></text>
+ </g>
+ <g
+ transform="translate(-2049.897,-585.6713)"
+ id="g3148">
+ <rect
+ ry="0"
+ id="rect118-3-5"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="412.66794"
+ width="3240.0085"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="3745.7725"
+ xml:space="preserve">rcu_note_context_switch()</text>
+ </g>
+ <g
+ transform="translate(3131.2648,-585.6713)"
+ id="g3148-5">
+ <rect
+ ry="0"
+ id="rect118-3-5-6"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="412.66794"
+ width="3240.0085"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="3745.7725"
+ xml:space="preserve">rcu_sched_clock_irq()</text>
+ </g>
+ <g
+ transform="translate(399.7744,828.86448)"
+ id="g3148-9">
+ <rect
+ ry="0"
+ id="rect118-3-5-1"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="864.02148"
+ width="3540.9114"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="3745.7725"
+ xml:space="preserve">rcu_core()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-0"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4165.7954"
+ x="3745.7725"
+ xml:space="preserve">rcu_check_quiescent_state()</text>
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-27-0-9"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-3914.085"
+ x="3745.7725"
+ xml:space="preserve">rcu__report_qs_rdp())</text>
+ </g>
+ <g
+ id="g4504-3"
+ transform="translate(5136.3339,-23870.546)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-3-9"
+ transform="translate(5136.3339,-20417.959)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5-9"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-6"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-3-0"
+ transform="translate(-2824.9451,-23870.546)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,228.84485,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-6"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-26"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-1"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-8"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5-7"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-9"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <g
+ id="g4504-3-9-0"
+ transform="translate(-2931.3303,-20417.959)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084-6-1-2"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2-7-2-3"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4409.043"
+ xml:space="preserve"><tspan
+ id="tspan3104-5-7-7"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">RCU</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110-3-0-5"
+ y="17055.541"
+ x="4579.373"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4579.373"
+ id="tspan3112-5-9-9"
+ sodipodi:role="line">read-side</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114-6-3-2"
+ y="17297.08"
+ x="4584.8276"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4584.8276"
+ id="tspan3116-2-6-2"
+ sodipodi:role="line">critical section</tspan></text>
+ </g>
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:none"
+ d="m 9699.0326,-6264.1445 0,2393.6632"
+ id="path3134-9-0-3-1-9-8"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:none"
+ d="m 1640.3664,-6264.1445 0,2393.6632"
+ id="path3134-9-0-3-1-9-8-9"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ </g>
+ <g
+ id="g4504"
+ transform="translate(2347.5727,554.69889)">
+ <path
+ transform="matrix(13.298129,0,0,13.298129,335.22989,12456.379)"
+ d="m 385.2961,345.54001 c 0,21.84301 -29.51209,39.55026 -65.9171,39.55026 -36.40501,0 -65.91711,-17.70725 -65.91711,-39.55026 0,-21.84301 29.5121,-39.55026 65.91711,-39.55026 36.40501,0 65.9171,17.70725 65.9171,39.55026 z"
+ sodipodi:ry="39.550262"
+ sodipodi:rx="65.917107"
+ sodipodi:cy="345.54001"
+ sodipodi:cx="319.379"
+ id="path3084"
+ style="fill:#ffffa1;fill-opacity:0;stroke:#000000;stroke-width:2.25600004;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2.256, 4.512;stroke-dashoffset:0"
+ sodipodi:type="arc" />
+ <text
+ sodipodi:linespacing="125%"
+ style="font-size:192px;font-style:normal;font-weight:bold;line-height:125%;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-1-2"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="16835.086"
+ x="4273.4326"
+ xml:space="preserve"><tspan
+ id="tspan3104"
+ style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans">Wake up</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3110"
+ y="17055.541"
+ x="4585.2246"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17055.541"
+ x="4585.2246"
+ id="tspan3112"
+ sodipodi:role="line">grace-period</tspan></text>
+ <text
+ sodipodi:linespacing="125%"
+ id="text3114"
+ y="17297.08"
+ x="4582.3804"
+ style="font-size:159.57754517px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+ xml:space="preserve"><tspan
+ y="17297.08"
+ x="4582.3804"
+ id="tspan3116"
+ sodipodi:role="line">kernel thread</tspan></text>
+ </g>
+ <g
+ transform="translate(1783.6576,20674.512)"
+ id="g3148-2">
+ <rect
+ ry="0"
+ id="rect118-3-5-2"
+ style="fill:none;stroke:#000000;stroke-width:30.00057983;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057963, 60.00115926;stroke-dashoffset:0"
+ rx="0"
+ height="412.66794"
+ width="3240.0085"
+ y="-4640.499"
+ x="3517.1572" />
+ <text
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"
+ id="text202-7-5-3-8"
+ font-size="192"
+ font-weight="bold"
+ font-style="normal"
+ y="-4418.6582"
+ x="4064.9268"
+ xml:space="preserve">rcu_report_qs_rsp()</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Memory-Ordering/rcu_node-lock.svg b/Documentation/RCU/Design/Memory-Ordering/rcu_node-lock.svg
new file mode 100644
index 000000000000..94c96c595aed
--- /dev/null
+++ b/Documentation/RCU/Design/Memory-Ordering/rcu_node-lock.svg
@@ -0,0 +1,229 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2 Patchlevel 5e -->
+
+<!-- CreationDate: Wed Dec 9 17:35:03 2015 -->
+
+<!-- Magnification: 2.000 -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="303.54147"
+ height="211.57945"
+ viewBox="-44 -44 4036.5336 2812.3117"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="rcu_node-lock.svg">
+ <metadata
+ id="metadata212">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs210">
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3970"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1087"
+ inkscape:window-height="1144"
+ id="namedview208"
+ showgrid="false"
+ inkscape:zoom="1.0495049"
+ inkscape:cx="311.2033"
+ inkscape:cy="168.10913"
+ inkscape:window-x="833"
+ inkscape:window-y="28"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="g4"
+ fit-margin-top="5"
+ fit-margin-right="5"
+ fit-margin-left="5"
+ fit-margin-bottom="5" />
+ <g
+ style="fill:none;stroke-width:0.025in"
+ id="g4"
+ transform="translate(-1905.5784,-4568.3024)">
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240-->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Circle -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410-->
+ <!-- Line: box -->
+ <rect
+ x="1943.0693"
+ y="4603.417"
+ width="3873.5518"
+ height="2650.6289"
+ rx="0"
+ style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:30.00057884, 60.00115769;stroke-dashoffset:0"
+ id="rect118"
+ ry="0" />
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910-->
+ <!-- Line: box -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650-->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150-->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Line -->
+ <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290-->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Line: box -->
+ <!-- Text -->
+ <!-- Text -->
+ <!-- Text -->
+ <text
+ xml:space="preserve"
+ x="3105.219"
+ y="6425.6445"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">rcu_accelerate_cbs()</text>
+ <!-- Text -->
+ <!-- Text -->
+ <g
+ id="g3107"
+ transform="translate(747.5807,4700.8888)">
+ <rect
+ id="rect112"
+ style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1370.8721"
+ width="2809.1992"
+ y="949.37109"
+ x="2084.55" />
+ <rect
+ id="rect112-3"
+ style="fill:none;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter"
+ rx="0"
+ height="1294.8468"
+ width="2809.1992"
+ y="1025.3964"
+ x="2084.55" />
+ </g>
+ <text
+ xml:space="preserve"
+ x="2025.5763"
+ y="4825.2578"
+ font-style="normal"
+ font-weight="bold"
+ font-size="192"
+ id="text202-7"
+ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_prepare_for_idle()</text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg
new file mode 100644
index 000000000000..87851a8fac1e
--- /dev/null
+++ b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg
@@ -0,0 +1,374 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="447.99197"
+ height="428.19299"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.3.1 r9886"
+ sodipodi:docname="GPpartitionReaders1.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.6184291"
+ inkscape:cx="223.99599"
+ inkscape:cy="214.0965"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="979"
+ inkscape:window-height="836"
+ inkscape:window-x="571"
+ inkscape:window-y="335"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-28.441125,-185.60612)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991"></flowPara></flowRoot> <g
+ id="g4433"
+ transform="translate(2,0)">
+ <text
+ sodipodi:linespacing="125%"
+ id="text2993"
+ y="-261.66608"
+ x="412.12299"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ xml:space="preserve"
+ transform="matrix(0,1,-1,0,0,0)"><tspan
+ y="-261.66608"
+ x="412.12299"
+ id="tspan2995"
+ sodipodi:role="line">synchronize_rcu()</tspan></text>
+ <g
+ id="g4417"
+ transform="matrix(0,1,-1,0,730.90257,222.4928)">
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)"
+ d="m 97.580736,477.4048 183.140664,0"
+ id="path2997"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 96.752718,465.38398 0,22.62742"
+ id="path4397"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 281.54942,465.38397 0,22.62742"
+ id="path4397-5"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ </g>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.04738"
+ y="268.18076"
+ id="text4429"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431"
+ x="112.04738"
+ y="268.18076">WRITE_ONCE(a, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.04738"
+ y="439.13766"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="112.04738"
+ y="439.13766">WRITE_ONCE(b, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="255.60869"
+ y="309.29346"
+ id="text4445"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4447"
+ x="255.60869"
+ y="309.29346">r1 = READ_ONCE(a);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="255.14423"
+ y="520.61786"
+ id="text4449"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4451"
+ x="255.14423"
+ y="520.61786">WRITE_ONCE(c, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="384.71124"
+ id="text4453"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4455"
+ x="396.10254"
+ y="384.71124">r2 = READ_ONCE(b);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="582.13617"
+ id="text4457"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4459"
+ x="396.10254"
+ y="582.13617">r3 = READ_ONCE(c);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.08231"
+ y="213.91006"
+ id="text4461"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463"
+ x="112.08231"
+ y="213.91006">thread0()</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="252.34512"
+ y="213.91006"
+ id="text4461-6"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463-0"
+ x="252.34512"
+ y="213.91006">thread1()</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.42557"
+ y="213.91006"
+ id="text4461-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463-2"
+ x="396.42557"
+ y="213.91006">thread2()</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect4495"
+ width="436.28488"
+ height="416.4859"
+ x="34.648232"
+ y="191.10612" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ d="m 183.14066,191.10612 0,417.193 -0.70711,0"
+ id="path4497"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ d="m 325.13867,191.10612 0,417.193 -0.70711,0"
+ id="path4497-5"
+ inkscape:connector-curvature="0" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="111.75929"
+ y="251.53981"
+ id="text4429-8"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9"
+ x="111.75929"
+ y="251.53981">rcu_read_lock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="367.91556"
+ id="text4429-8-9"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4"
+ x="396.10254"
+ y="367.91556">rcu_read_lock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="597.40289"
+ id="text4429-8-9-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4-4"
+ x="396.10254"
+ y="597.40289">rcu_read_unlock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="111.75929"
+ y="453.15311"
+ id="text4429-8-9-3-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4-4-6"
+ x="111.75929"
+ y="453.15311">rcu_read_unlock();</tspan></text>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 33.941125,227.87568 436.284885,0 0,0.7071"
+ id="path4608"
+ inkscape:connector-curvature="0" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="394.94427"
+ y="345.66351"
+ id="text4648"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650"
+ x="394.94427"
+ y="345.66351">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(36.441125,199.60612)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.11968"
+ y="475.77856"
+ id="text4648-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-4"
+ x="112.11968"
+ y="475.77856">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-7"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(-246.38346,329.72117)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-7-7"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(-103.65246,202.90878)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="254.85066"
+ y="348.96619"
+ id="text4648-4-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-4-5"
+ x="254.85066"
+ y="348.96619">QS</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg
new file mode 100644
index 000000000000..e2a8af592bab
--- /dev/null
+++ b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg
@@ -0,0 +1,639 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="735.25"
+ height="516.21875"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.3.1 r9886"
+ sodipodi:docname="ReadersPartitionGP1.svg">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend"
+ style="overflow:visible">
+ <path
+ id="path3792"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart"
+ style="overflow:visible">
+ <path
+ id="path3789"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lstart"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lstart-4"
+ style="overflow:visible">
+ <path
+ id="path3789-9"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(1.1,0,0,1.1,1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Lend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow2Lend-4"
+ style="overflow:visible">
+ <path
+ id="path3792-4"
+ style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
+ d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+ transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.3670394"
+ inkscape:cx="367.26465"
+ inkscape:cy="258.46182"
+ inkscape:document-units="px"
+ inkscape:current-layer="g4433-6"
+ showgrid="false"
+ inkscape:window-width="1351"
+ inkscape:window-height="836"
+ inkscape:window-x="438"
+ inkscape:window-y="335"
+ inkscape:window-maximized="0"
+ fit-margin-top="5"
+ fit-margin-left="5"
+ fit-margin-right="5"
+ fit-margin-bottom="5" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-29.15625,-185.59375)">
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot2985"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"><flowRegion
+ id="flowRegion2987"><rect
+ id="rect2989"
+ width="82.85714"
+ height="11.428572"
+ x="240"
+ y="492.36218" /></flowRegion><flowPara
+ id="flowPara2991" /></flowRoot> <g
+ id="g4433"
+ transform="translate(2,-12)">
+ <text
+ sodipodi:linespacing="125%"
+ id="text2993"
+ y="-261.66608"
+ x="436.12299"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ xml:space="preserve"
+ transform="matrix(0,1,-1,0,0,0)"><tspan
+ y="-261.66608"
+ x="436.12299"
+ id="tspan2995"
+ sodipodi:role="line">synchronize_rcu()</tspan></text>
+ <g
+ id="g4417"
+ transform="matrix(0,1,-1,0,730.90257,222.4928)">
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)"
+ d="M 97.580736,477.4048 327.57913,476.09759"
+ id="path2997"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 96.752718,465.38398 0,22.62742"
+ id="path4397"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 328.40703,465.38397 0,22.62742"
+ id="path4397-5"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ </g>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.04738"
+ y="268.18076"
+ id="text4429"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431"
+ x="112.04738"
+ y="268.18076">WRITE_ONCE(a, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.04738"
+ y="487.13766"
+ id="text4441"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4443"
+ x="112.04738"
+ y="487.13766">WRITE_ONCE(b, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="255.60869"
+ y="297.29346"
+ id="text4445"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4447"
+ x="255.60869"
+ y="297.29346">r1 = READ_ONCE(a);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="255.14423"
+ y="554.61786"
+ id="text4449"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4451"
+ x="255.14423"
+ y="554.61786">WRITE_ONCE(c, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="370.71124"
+ id="text4453"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4455"
+ x="396.10254"
+ y="370.71124">WRITE_ONCE(d, 1);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="572.13617"
+ id="text4457"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4459"
+ x="396.10254"
+ y="572.13617">r2 = READ_ONCE(c);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.08231"
+ y="213.91006"
+ id="text4461"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463"
+ x="112.08231"
+ y="213.91006">thread0()</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="252.34512"
+ y="213.91006"
+ id="text4461-6"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463-0"
+ x="252.34512"
+ y="213.91006">thread1()</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.42557"
+ y="213.91006"
+ id="text4461-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463-2"
+ x="396.42557"
+ y="213.91006">thread2()</tspan></text>
+ <rect
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect4495"
+ width="724.25244"
+ height="505.21201"
+ x="34.648232"
+ y="191.10612" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ d="m 183.14066,191.10612 0,504.24243"
+ id="path4497"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ d="m 325.13867,191.10612 0,504.24243"
+ id="path4497-5"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="111.75929"
+ y="251.53981"
+ id="text4429-8"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9"
+ x="111.75929"
+ y="251.53981">rcu_read_lock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="353.91556"
+ id="text4429-8-9"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4"
+ x="396.10254"
+ y="353.91556">rcu_read_lock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="396.10254"
+ y="587.40289"
+ id="text4429-8-9-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4-4"
+ x="396.10254"
+ y="587.40289">rcu_read_unlock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="111.75929"
+ y="501.15311"
+ id="text4429-8-9-3-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4-4-6"
+ x="111.75929"
+ y="501.15311">rcu_read_unlock();</tspan></text>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 33.941125,227.87568 724.941765,0"
+ id="path4608"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="394.94427"
+ y="331.66351"
+ id="text4648"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650"
+ x="394.94427"
+ y="331.66351">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(36.441125,185.60612)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="112.11968"
+ y="523.77856"
+ id="text4648-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-4"
+ x="112.11968"
+ y="523.77856">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-7"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(-246.38346,377.72117)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-7-7"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(-103.65246,190.90878)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="254.85066"
+ y="336.96619"
+ id="text4648-4-3"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-4-5"
+ x="254.85066"
+ y="336.96619">QS</tspan></text>
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ d="m 470.93311,190.39903 0,504.24243"
+ id="path4497-5-6"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ d="m 616.22755,190.38323 0,504.24243"
+ id="path4497-5-2"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <g
+ id="g4433-6"
+ transform="translate(288.0964,78.32827)">
+ <text
+ sodipodi:linespacing="125%"
+ id="text2993-7"
+ y="-261.66608"
+ x="440.12299"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ xml:space="preserve"
+ transform="matrix(0,1,-1,0,0,0)"><tspan
+ y="-261.66608"
+ x="440.12299"
+ id="tspan2995-1"
+ sodipodi:role="line">synchronize_rcu()</tspan></text>
+ <g
+ id="g4417-1"
+ transform="matrix(0,1,-1,0,730.90257,222.4928)">
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)"
+ d="M 97.580736,477.4048 328.5624,477.07246"
+ id="path2997-2"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 96.752718,465.38398 0,22.62742"
+ id="path4397-3"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ <path
+ style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 329.39039,465.38397 0,22.62742"
+ id="path4397-5-4"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="cc" />
+ </g>
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="541.70508"
+ y="387.6217"
+ id="text4445-0"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4447-5"
+ x="541.70508"
+ y="387.6217">r3 = READ_ONCE(d);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="541.2406"
+ y="646.94611"
+ id="text4449-6"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4451-6"
+ x="541.2406"
+ y="646.94611">WRITE_ONCE(e, 1);</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-7-7-5"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(182.44393,281.23704)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="540.94702"
+ y="427.29443"
+ id="text4648-4-3-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-4-5-7"
+ x="540.94702"
+ y="427.29443">QS</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="686.27747"
+ y="461.83929"
+ id="text4453-7"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4455-1"
+ x="686.27747"
+ y="461.83929">r4 = READ_ONCE(b);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="686.27747"
+ y="669.26422"
+ id="text4457-9"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4459-2"
+ x="686.27747"
+ y="669.26422">r5 = READ_ONCE(e);</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="686.27747"
+ y="445.04358"
+ id="text4429-8-9-33"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4-2"
+ x="686.27747"
+ y="445.04358">rcu_read_lock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="686.27747"
+ y="684.53094"
+ id="text4429-8-9-3-8"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4431-9-4-4-5"
+ x="686.27747"
+ y="684.53094">rcu_read_unlock();</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="685.11914"
+ y="422.79153"
+ id="text4648-9"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-7"
+ x="685.11914"
+ y="422.79153">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-8"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(326.61602,276.73415)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="397.85934"
+ y="609.59003"
+ id="text4648-5"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-77"
+ x="397.85934"
+ y="609.59003">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-80"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(39.356201,463.53264)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="256.75986"
+ y="586.99133"
+ id="text4648-5-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4650-77-7"
+ x="256.75986"
+ y="586.99133">QS</tspan></text>
+ <path
+ sodipodi:type="arc"
+ style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path4652-80-5"
+ sodipodi:cx="358.85669"
+ sodipodi:cy="142.87541"
+ sodipodi:rx="10.960155"
+ sodipodi:ry="10.253048"
+ d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0"
+ transform="translate(-101.74328,440.93395)"
+ sodipodi:start="4.7135481"
+ sodipodi:end="10.994651"
+ sodipodi:open="true" />
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="546.22791"
+ y="213.91006"
+ id="text4461-2-5"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463-2-6"
+ x="546.22791"
+ y="213.91006">thread3()</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:monospace;-inkscape-font-specification:monospace"
+ x="684.00067"
+ y="213.91006"
+ id="text4461-2-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4463-2-0"
+ x="684.00067"
+ y="213.91006">thread4()</tspan></text>
+ </g>
+</svg>
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
new file mode 100644
index 000000000000..ba417a08b93d
--- /dev/null
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -0,0 +1,2866 @@
+=================================
+A Tour Through RCU's Requirements
+=================================
+
+Copyright IBM Corporation, 2015
+
+Author: Paul E. McKenney
+
+The initial version of this document appeared in the
+`LWN <https://lwn.net/>`_ on those articles:
+`part 1 <https://lwn.net/Articles/652156/>`_,
+`part 2 <https://lwn.net/Articles/652677/>`_, and
+`part 3 <https://lwn.net/Articles/653326/>`_.
+
+Introduction
+------------
+
+Read-copy update (RCU) is a synchronization mechanism that is often used
+as a replacement for reader-writer locking. RCU is unusual in that
+updaters do not block readers, which means that RCU's read-side
+primitives can be exceedingly fast and scalable. In addition, updaters
+can make useful forward progress concurrently with readers. However, all
+this concurrency between RCU readers and updaters does raise the
+question of exactly what RCU readers are doing, which in turn raises the
+question of exactly what RCU's requirements are.
+
+This document therefore summarizes RCU's requirements, and can be
+thought of as an informal, high-level specification for RCU. It is
+important to understand that RCU's specification is primarily empirical
+in nature; in fact, I learned about many of these requirements the hard
+way. This situation might cause some consternation, however, not only
+has this learning process been a lot of fun, but it has also been a
+great privilege to work with so many people willing to apply
+technologies in interesting new ways.
+
+All that aside, here are the categories of currently known RCU
+requirements:
+
+#. `Fundamental Requirements`_
+#. `Fundamental Non-Requirements`_
+#. `Parallelism Facts of Life`_
+#. `Quality-of-Implementation Requirements`_
+#. `Linux Kernel Complications`_
+#. `Software-Engineering Requirements`_
+#. `Other RCU Flavors`_
+#. `Possible Future Changes`_
+
+This is followed by a summary_, however, the answers to
+each quick quiz immediately follows the quiz. Select the big white space
+with your mouse to see the answer.
+
+Fundamental Requirements
+------------------------
+
+RCU's fundamental requirements are the closest thing RCU has to hard
+mathematical requirements. These are:
+
+#. `Grace-Period Guarantee`_
+#. `Publish/Subscribe Guarantee`_
+#. `Memory-Barrier Guarantees`_
+#. `RCU Primitives Guaranteed to Execute Unconditionally`_
+#. `Guaranteed Read-to-Write Upgrade`_
+
+Grace-Period Guarantee
+~~~~~~~~~~~~~~~~~~~~~~
+
+RCU's grace-period guarantee is unusual in being premeditated: Jack
+Slingwine and I had this guarantee firmly in mind when we started work
+on RCU (then called “rclock”) in the early 1990s. That said, the past
+two decades of experience with RCU have produced a much more detailed
+understanding of this guarantee.
+
+RCU's grace-period guarantee allows updaters to wait for the completion
+of all pre-existing RCU read-side critical sections. An RCU read-side
+critical section begins with the marker rcu_read_lock() and ends
+with the marker rcu_read_unlock(). These markers may be nested, and
+RCU treats a nested set as one big RCU read-side critical section.
+Production-quality implementations of rcu_read_lock() and
+rcu_read_unlock() are extremely lightweight, and in fact have
+exactly zero overhead in Linux kernels built for production use with
+``CONFIG_PREEMPTION=n``.
+
+This guarantee allows ordering to be enforced with extremely low
+overhead to readers, for example:
+
+ ::
+
+ 1 int x, y;
+ 2
+ 3 void thread0(void)
+ 4 {
+ 5 rcu_read_lock();
+ 6 r1 = READ_ONCE(x);
+ 7 r2 = READ_ONCE(y);
+ 8 rcu_read_unlock();
+ 9 }
+ 10
+ 11 void thread1(void)
+ 12 {
+ 13 WRITE_ONCE(x, 1);
+ 14 synchronize_rcu();
+ 15 WRITE_ONCE(y, 1);
+ 16 }
+
+Because the synchronize_rcu() on line 14 waits for all pre-existing
+readers, any instance of thread0() that loads a value of zero from
+``x`` must complete before thread1() stores to ``y``, so that
+instance must also load a value of zero from ``y``. Similarly, any
+instance of thread0() that loads a value of one from ``y`` must have
+started after the synchronize_rcu() started, and must therefore also
+load a value of one from ``x``. Therefore, the outcome:
+
+ ::
+
+ (r1 == 0 && r2 == 1)
+
+cannot happen.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Wait a minute! You said that updaters can make useful forward |
+| progress concurrently with readers, but pre-existing readers will |
+| block synchronize_rcu()!!! |
+| Just who are you trying to fool??? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| First, if updaters do not wish to be blocked by readers, they can use |
+| call_rcu() or kfree_rcu(), which will be discussed later. |
+| Second, even when using synchronize_rcu(), the other update-side |
+| code does run concurrently with readers, whether pre-existing or not. |
++-----------------------------------------------------------------------+
+
+This scenario resembles one of the first uses of RCU in
+`DYNIX/ptx <https://en.wikipedia.org/wiki/DYNIX>`__, which managed a
+distributed lock manager's transition into a state suitable for handling
+recovery from node failure, more or less as follows:
+
+ ::
+
+ 1 #define STATE_NORMAL 0
+ 2 #define STATE_WANT_RECOVERY 1
+ 3 #define STATE_RECOVERING 2
+ 4 #define STATE_WANT_NORMAL 3
+ 5
+ 6 int state = STATE_NORMAL;
+ 7
+ 8 void do_something_dlm(void)
+ 9 {
+ 10 int state_snap;
+ 11
+ 12 rcu_read_lock();
+ 13 state_snap = READ_ONCE(state);
+ 14 if (state_snap == STATE_NORMAL)
+ 15 do_something();
+ 16 else
+ 17 do_something_carefully();
+ 18 rcu_read_unlock();
+ 19 }
+ 20
+ 21 void start_recovery(void)
+ 22 {
+ 23 WRITE_ONCE(state, STATE_WANT_RECOVERY);
+ 24 synchronize_rcu();
+ 25 WRITE_ONCE(state, STATE_RECOVERING);
+ 26 recovery();
+ 27 WRITE_ONCE(state, STATE_WANT_NORMAL);
+ 28 synchronize_rcu();
+ 29 WRITE_ONCE(state, STATE_NORMAL);
+ 30 }
+
+The RCU read-side critical section in do_something_dlm() works with
+the synchronize_rcu() in start_recovery() to guarantee that
+do_something() never runs concurrently with recovery(), but with
+little or no synchronization overhead in do_something_dlm().
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why is the synchronize_rcu() on line 28 needed? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Without that extra grace period, memory reordering could result in |
+| do_something_dlm() executing do_something() concurrently with |
+| the last bits of recovery(). |
++-----------------------------------------------------------------------+
+
+In order to avoid fatal problems such as deadlocks, an RCU read-side
+critical section must not contain calls to synchronize_rcu().
+Similarly, an RCU read-side critical section must not contain anything
+that waits, directly or indirectly, on completion of an invocation of
+synchronize_rcu().
+
+Although RCU's grace-period guarantee is useful in and of itself, with
+`quite a few use cases <https://lwn.net/Articles/573497/>`__, it would
+be good to be able to use RCU to coordinate read-side access to linked
+data structures. For this, the grace-period guarantee is not sufficient,
+as can be seen in function add_gp_buggy() below. We will look at the
+reader's code later, but in the meantime, just think of the reader as
+locklessly picking up the ``gp`` pointer, and, if the value loaded is
+non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields.
+
+ ::
+
+ 1 bool add_gp_buggy(int a, int b)
+ 2 {
+ 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 4 if (!p)
+ 5 return -ENOMEM;
+ 6 spin_lock(&gp_lock);
+ 7 if (rcu_access_pointer(gp)) {
+ 8 spin_unlock(&gp_lock);
+ 9 return false;
+ 10 }
+ 11 p->a = a;
+ 12 p->b = a;
+ 13 gp = p; /* ORDERING BUG */
+ 14 spin_unlock(&gp_lock);
+ 15 return true;
+ 16 }
+
+The problem is that both the compiler and weakly ordered CPUs are within
+their rights to reorder this code as follows:
+
+ ::
+
+ 1 bool add_gp_buggy_optimized(int a, int b)
+ 2 {
+ 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 4 if (!p)
+ 5 return -ENOMEM;
+ 6 spin_lock(&gp_lock);
+ 7 if (rcu_access_pointer(gp)) {
+ 8 spin_unlock(&gp_lock);
+ 9 return false;
+ 10 }
+ 11 gp = p; /* ORDERING BUG */
+ 12 p->a = a;
+ 13 p->b = a;
+ 14 spin_unlock(&gp_lock);
+ 15 return true;
+ 16 }
+
+If an RCU reader fetches ``gp`` just after ``add_gp_buggy_optimized``
+executes line 11, it will see garbage in the ``->a`` and ``->b`` fields.
+And this is but one of many ways in which compiler and hardware
+optimizations could cause trouble. Therefore, we clearly need some way
+to prevent the compiler and the CPU from reordering in this manner,
+which brings us to the publish-subscribe guarantee discussed in the next
+section.
+
+Publish/Subscribe Guarantee
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+RCU's publish-subscribe guarantee allows data to be inserted into a
+linked data structure without disrupting RCU readers. The updater uses
+rcu_assign_pointer() to insert the new data, and readers use
+rcu_dereference() to access data, whether new or old. The following
+shows an example of insertion:
+
+ ::
+
+ 1 bool add_gp(int a, int b)
+ 2 {
+ 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 4 if (!p)
+ 5 return -ENOMEM;
+ 6 spin_lock(&gp_lock);
+ 7 if (rcu_access_pointer(gp)) {
+ 8 spin_unlock(&gp_lock);
+ 9 return false;
+ 10 }
+ 11 p->a = a;
+ 12 p->b = a;
+ 13 rcu_assign_pointer(gp, p);
+ 14 spin_unlock(&gp_lock);
+ 15 return true;
+ 16 }
+
+The rcu_assign_pointer() on line 13 is conceptually equivalent to a
+simple assignment statement, but also guarantees that its assignment
+will happen after the two assignments in lines 11 and 12, similar to the
+C11 ``memory_order_release`` store operation. It also prevents any
+number of “interesting” compiler optimizations, for example, the use of
+``gp`` as a scratch location immediately preceding the assignment.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But rcu_assign_pointer() does nothing to prevent the two |
+| assignments to ``p->a`` and ``p->b`` from being reordered. Can't that |
+| also cause problems? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| No, it cannot. The readers cannot see either of these two fields |
+| until the assignment to ``gp``, by which time both fields are fully |
+| initialized. So reordering the assignments to ``p->a`` and ``p->b`` |
+| cannot possibly cause any problems. |
++-----------------------------------------------------------------------+
+
+It is tempting to assume that the reader need not do anything special to
+control its accesses to the RCU-protected data, as shown in
+do_something_gp_buggy() below:
+
+ ::
+
+ 1 bool do_something_gp_buggy(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 p = gp; /* OPTIMIZATIONS GALORE!!! */
+ 5 if (p) {
+ 6 do_something(p->a, p->b);
+ 7 rcu_read_unlock();
+ 8 return true;
+ 9 }
+ 10 rcu_read_unlock();
+ 11 return false;
+ 12 }
+
+However, this temptation must be resisted because there are a
+surprisingly large number of ways that the compiler (or weak ordering
+CPUs like the DEC Alpha) can trip this code up. For but one example, if
+the compiler were short of registers, it might choose to refetch from
+``gp`` rather than keeping a separate copy in ``p`` as follows:
+
+ ::
+
+ 1 bool do_something_gp_buggy_optimized(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */
+ 5 do_something(gp->a, gp->b);
+ 6 rcu_read_unlock();
+ 7 return true;
+ 8 }
+ 9 rcu_read_unlock();
+ 10 return false;
+ 11 }
+
+If this function ran concurrently with a series of updates that replaced
+the current structure with a new one, the fetches of ``gp->a`` and
+``gp->b`` might well come from two different structures, which could
+cause serious confusion. To prevent this (and much else besides),
+do_something_gp() uses rcu_dereference() to fetch from ``gp``:
+
+ ::
+
+ 1 bool do_something_gp(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 p = rcu_dereference(gp);
+ 5 if (p) {
+ 6 do_something(p->a, p->b);
+ 7 rcu_read_unlock();
+ 8 return true;
+ 9 }
+ 10 rcu_read_unlock();
+ 11 return false;
+ 12 }
+
+The rcu_dereference() uses volatile casts and (for DEC Alpha) memory
+barriers in the Linux kernel. Should a |high-quality implementation of
+C11 memory_order_consume [PDF]|_
+ever appear, then rcu_dereference() could be implemented as a
+``memory_order_consume`` load. Regardless of the exact implementation, a
+pointer fetched by rcu_dereference() may not be used outside of the
+outermost RCU read-side critical section containing that
+rcu_dereference(), unless protection of the corresponding data
+element has been passed from RCU to some other synchronization
+mechanism, most commonly locking or reference counting
+(see ../../rcuref.rst).
+
+.. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF]
+.. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf
+
+In short, updaters use rcu_assign_pointer() and readers use
+rcu_dereference(), and these two RCU API elements work together to
+ensure that readers have a consistent view of newly added data elements.
+
+Of course, it is also necessary to remove elements from RCU-protected
+data structures, for example, using the following process:
+
+#. Remove the data element from the enclosing structure.
+#. Wait for all pre-existing RCU read-side critical sections to complete
+ (because only pre-existing readers can possibly have a reference to
+ the newly removed data element).
+#. At this point, only the updater has a reference to the newly removed
+ data element, so it can safely reclaim the data element, for example,
+ by passing it to kfree().
+
+This process is implemented by remove_gp_synchronous():
+
+ ::
+
+ 1 bool remove_gp_synchronous(void)
+ 2 {
+ 3 struct foo *p;
+ 4
+ 5 spin_lock(&gp_lock);
+ 6 p = rcu_access_pointer(gp);
+ 7 if (!p) {
+ 8 spin_unlock(&gp_lock);
+ 9 return false;
+ 10 }
+ 11 rcu_assign_pointer(gp, NULL);
+ 12 spin_unlock(&gp_lock);
+ 13 synchronize_rcu();
+ 14 kfree(p);
+ 15 return true;
+ 16 }
+
+This function is straightforward, with line 13 waiting for a grace
+period before line 14 frees the old data element. This waiting ensures
+that readers will reach line 7 of do_something_gp() before the data
+element referenced by ``p`` is freed. The rcu_access_pointer() on
+line 6 is similar to rcu_dereference(), except that:
+
+#. The value returned by rcu_access_pointer() cannot be
+ dereferenced. If you want to access the value pointed to as well as
+ the pointer itself, use rcu_dereference() instead of
+ rcu_access_pointer().
+#. The call to rcu_access_pointer() need not be protected. In
+ contrast, rcu_dereference() must either be within an RCU
+ read-side critical section or in a code segment where the pointer
+ cannot change, for example, in code protected by the corresponding
+ update-side lock.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Without the rcu_dereference() or the rcu_access_pointer(), |
+| what destructive optimizations might the compiler make use of? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Let's start with what happens to do_something_gp() if it fails to |
+| use rcu_dereference(). It could reuse a value formerly fetched |
+| from this same pointer. It could also fetch the pointer from ``gp`` |
+| in a byte-at-a-time manner, resulting in *load tearing*, in turn |
+| resulting a bytewise mash-up of two distinct pointer values. It might |
+| even use value-speculation optimizations, where it makes a wrong |
+| guess, but by the time it gets around to checking the value, an |
+| update has changed the pointer to match the wrong guess. Too bad |
+| about any dereferences that returned pre-initialization garbage in |
+| the meantime! |
+| For remove_gp_synchronous(), as long as all modifications to |
+| ``gp`` are carried out while holding ``gp_lock``, the above |
+| optimizations are harmless. However, ``sparse`` will complain if you |
+| define ``gp`` with ``__rcu`` and then access it without using either |
+| rcu_access_pointer() or rcu_dereference(). |
++-----------------------------------------------------------------------+
+
+In short, RCU's publish-subscribe guarantee is provided by the
+combination of rcu_assign_pointer() and rcu_dereference(). This
+guarantee allows data elements to be safely added to RCU-protected
+linked data structures without disrupting RCU readers. This guarantee
+can be used in combination with the grace-period guarantee to also allow
+data elements to be removed from RCU-protected linked data structures,
+again without disrupting RCU readers.
+
+This guarantee was only partially premeditated. DYNIX/ptx used an
+explicit memory barrier for publication, but had nothing resembling
+rcu_dereference() for subscription, nor did it have anything
+resembling the dependency-ordering barrier that was later subsumed
+into rcu_dereference() and later still into READ_ONCE(). The
+need for these operations made itself known quite suddenly at a
+late-1990s meeting with the DEC Alpha architects, back in the days when
+DEC was still a free-standing company. It took the Alpha architects a
+good hour to convince me that any sort of barrier would ever be needed,
+and it then took me a good *two* hours to convince them that their
+documentation did not make this point clear. More recent work with the C
+and C++ standards committees have provided much education on tricks and
+traps from the compiler. In short, compilers were much less tricky in
+the early 1990s, but in 2015, don't even think about omitting
+rcu_dereference()!
+
+Memory-Barrier Guarantees
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The previous section's simple linked-data-structure scenario clearly
+demonstrates the need for RCU's stringent memory-ordering guarantees on
+systems with more than one CPU:
+
+#. Each CPU that has an RCU read-side critical section that begins
+ before synchronize_rcu() starts is guaranteed to execute a full
+ memory barrier between the time that the RCU read-side critical
+ section ends and the time that synchronize_rcu() returns. Without
+ this guarantee, a pre-existing RCU read-side critical section might
+ hold a reference to the newly removed ``struct foo`` after the
+ kfree() on line 14 of remove_gp_synchronous().
+#. Each CPU that has an RCU read-side critical section that ends after
+ synchronize_rcu() returns is guaranteed to execute a full memory
+ barrier between the time that synchronize_rcu() begins and the
+ time that the RCU read-side critical section begins. Without this
+ guarantee, a later RCU read-side critical section running after the
+ kfree() on line 14 of remove_gp_synchronous() might later run
+ do_something_gp() and find the newly deleted ``struct foo``.
+#. If the task invoking synchronize_rcu() remains on a given CPU,
+ then that CPU is guaranteed to execute a full memory barrier sometime
+ during the execution of synchronize_rcu(). This guarantee ensures
+ that the kfree() on line 14 of remove_gp_synchronous() really
+ does execute after the removal on line 11.
+#. If the task invoking synchronize_rcu() migrates among a group of
+ CPUs during that invocation, then each of the CPUs in that group is
+ guaranteed to execute a full memory barrier sometime during the
+ execution of synchronize_rcu(). This guarantee also ensures that
+ the kfree() on line 14 of remove_gp_synchronous() really does
+ execute after the removal on line 11, but also in the case where the
+ thread executing the synchronize_rcu() migrates in the meantime.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Given that multiple CPUs can start RCU read-side critical sections at |
+| any time without any ordering whatsoever, how can RCU possibly tell |
+| whether or not a given RCU read-side critical section starts before a |
+| given instance of synchronize_rcu()? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| If RCU cannot tell whether or not a given RCU read-side critical |
+| section starts before a given instance of synchronize_rcu(), then |
+| it must assume that the RCU read-side critical section started first. |
+| In other words, a given instance of synchronize_rcu() can avoid |
+| waiting on a given RCU read-side critical section only if it can |
+| prove that synchronize_rcu() started first. |
+| A related question is “When rcu_read_lock() doesn't generate any |
+| code, why does it matter how it relates to a grace period?” The |
+| answer is that it is not the relationship of rcu_read_lock() |
+| itself that is important, but rather the relationship of the code |
+| within the enclosed RCU read-side critical section to the code |
+| preceding and following the grace period. If we take this viewpoint, |
+| then a given RCU read-side critical section begins before a given |
+| grace period when some access preceding the grace period observes the |
+| effect of some access within the critical section, in which case none |
+| of the accesses within the critical section may observe the effects |
+| of any access following the grace period. |
+| |
+| As of late 2016, mathematical models of RCU take this viewpoint, for |
+| example, see slides 62 and 63 of the `2016 LinuxCon |
+| EU <http://www2.rdrop.com/users/paulmck/scalability/paper/LinuxMM.201 |
+| 6.10.04c.LCE.pdf>`__ |
+| presentation. |
++-----------------------------------------------------------------------+
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| The first and second guarantees require unbelievably strict ordering! |
+| Are all these memory barriers *really* required? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Yes, they really are required. To see why the first guarantee is |
+| required, consider the following sequence of events: |
+| |
+| #. CPU 1: rcu_read_lock() |
+| #. CPU 1: ``q = rcu_dereference(gp); /* Very likely to return p. */`` |
+| #. CPU 0: ``list_del_rcu(p);`` |
+| #. CPU 0: synchronize_rcu() starts. |
+| #. CPU 1: ``do_something_with(q->a);`` |
+| ``/* No smp_mb(), so might happen after kfree(). */`` |
+| #. CPU 1: rcu_read_unlock() |
+| #. CPU 0: synchronize_rcu() returns. |
+| #. CPU 0: ``kfree(p);`` |
+| |
+| Therefore, there absolutely must be a full memory barrier between the |
+| end of the RCU read-side critical section and the end of the grace |
+| period. |
+| |
+| The sequence of events demonstrating the necessity of the second rule |
+| is roughly similar: |
+| |
+| #. CPU 0: ``list_del_rcu(p);`` |
+| #. CPU 0: synchronize_rcu() starts. |
+| #. CPU 1: rcu_read_lock() |
+| #. CPU 1: ``q = rcu_dereference(gp);`` |
+| ``/* Might return p if no memory barrier. */`` |
+| #. CPU 0: synchronize_rcu() returns. |
+| #. CPU 0: ``kfree(p);`` |
+| #. CPU 1: ``do_something_with(q->a); /* Boom!!! */`` |
+| #. CPU 1: rcu_read_unlock() |
+| |
+| And similarly, without a memory barrier between the beginning of the |
+| grace period and the beginning of the RCU read-side critical section, |
+| CPU 1 might end up accessing the freelist. |
+| |
+| The “as if” rule of course applies, so that any implementation that |
+| acts as if the appropriate memory barriers were in place is a correct |
+| implementation. That said, it is much easier to fool yourself into |
+| believing that you have adhered to the as-if rule than it is to |
+| actually adhere to it! |
++-----------------------------------------------------------------------+
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| You claim that rcu_read_lock() and rcu_read_unlock() generate |
+| absolutely no code in some kernel builds. This means that the |
+| compiler might arbitrarily rearrange consecutive RCU read-side |
+| critical sections. Given such rearrangement, if a given RCU read-side |
+| critical section is done, how can you be sure that all prior RCU |
+| read-side critical sections are done? Won't the compiler |
+| rearrangements make that impossible to determine? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| In cases where rcu_read_lock() and rcu_read_unlock() generate |
+| absolutely no code, RCU infers quiescent states only at special |
+| locations, for example, within the scheduler. Because calls to |
+| schedule() had better prevent calling-code accesses to shared |
+| variables from being rearranged across the call to schedule(), if |
+| RCU detects the end of a given RCU read-side critical section, it |
+| will necessarily detect the end of all prior RCU read-side critical |
+| sections, no matter how aggressively the compiler scrambles the code. |
+| Again, this all assumes that the compiler cannot scramble code across |
+| calls to the scheduler, out of interrupt handlers, into the idle |
+| loop, into user-mode code, and so on. But if your kernel build allows |
+| that sort of scrambling, you have broken far more than just RCU! |
++-----------------------------------------------------------------------+
+
+Note that these memory-barrier requirements do not replace the
+fundamental RCU requirement that a grace period wait for all
+pre-existing readers. On the contrary, the memory barriers called out in
+this section must operate in such a way as to *enforce* this fundamental
+requirement. Of course, different implementations enforce this
+requirement in different ways, but enforce it they must.
+
+RCU Primitives Guaranteed to Execute Unconditionally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The common-case RCU primitives are unconditional. They are invoked, they
+do their job, and they return, with no possibility of error, and no need
+to retry. This is a key RCU design philosophy.
+
+However, this philosophy is pragmatic rather than pigheaded. If someone
+comes up with a good justification for a particular conditional RCU
+primitive, it might well be implemented and added. After all, this
+guarantee was reverse-engineered, not premeditated. The unconditional
+nature of the RCU primitives was initially an accident of
+implementation, and later experience with synchronization primitives
+with conditional primitives caused me to elevate this accident to a
+guarantee. Therefore, the justification for adding a conditional
+primitive to RCU would need to be based on detailed and compelling use
+cases.
+
+Guaranteed Read-to-Write Upgrade
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As far as RCU is concerned, it is always possible to carry out an update
+within an RCU read-side critical section. For example, that RCU
+read-side critical section might search for a given data element, and
+then might acquire the update-side spinlock in order to update that
+element, all while remaining in that RCU read-side critical section. Of
+course, it is necessary to exit the RCU read-side critical section
+before invoking synchronize_rcu(), however, this inconvenience can
+be avoided through use of the call_rcu() and kfree_rcu() API
+members described later in this document.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But how does the upgrade-to-write operation exclude other readers? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| It doesn't, just like normal RCU updates, which also do not exclude |
+| RCU readers. |
++-----------------------------------------------------------------------+
+
+This guarantee allows lookup code to be shared between read-side and
+update-side code, and was premeditated, appearing in the earliest
+DYNIX/ptx RCU documentation.
+
+Fundamental Non-Requirements
+----------------------------
+
+RCU provides extremely lightweight readers, and its read-side
+guarantees, though quite useful, are correspondingly lightweight. It is
+therefore all too easy to assume that RCU is guaranteeing more than it
+really is. Of course, the list of things that RCU does not guarantee is
+infinitely long, however, the following sections list a few
+non-guarantees that have caused confusion. Except where otherwise noted,
+these non-guarantees were premeditated.
+
+#. `Readers Impose Minimal Ordering`_
+#. `Readers Do Not Exclude Updaters`_
+#. `Updaters Only Wait For Old Readers`_
+#. `Grace Periods Don't Partition Read-Side Critical Sections`_
+#. `Read-Side Critical Sections Don't Partition Grace Periods`_
+
+Readers Impose Minimal Ordering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Reader-side markers such as rcu_read_lock() and
+rcu_read_unlock() provide absolutely no ordering guarantees except
+through their interaction with the grace-period APIs such as
+synchronize_rcu(). To see this, consider the following pair of
+threads:
+
+ ::
+
+ 1 void thread0(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 WRITE_ONCE(x, 1);
+ 5 rcu_read_unlock();
+ 6 rcu_read_lock();
+ 7 WRITE_ONCE(y, 1);
+ 8 rcu_read_unlock();
+ 9 }
+ 10
+ 11 void thread1(void)
+ 12 {
+ 13 rcu_read_lock();
+ 14 r1 = READ_ONCE(y);
+ 15 rcu_read_unlock();
+ 16 rcu_read_lock();
+ 17 r2 = READ_ONCE(x);
+ 18 rcu_read_unlock();
+ 19 }
+
+After thread0() and thread1() execute concurrently, it is quite
+possible to have
+
+ ::
+
+ (r1 == 1 && r2 == 0)
+
+(that is, ``y`` appears to have been assigned before ``x``), which would
+not be possible if rcu_read_lock() and rcu_read_unlock() had
+much in the way of ordering properties. But they do not, so the CPU is
+within its rights to do significant reordering. This is by design: Any
+significant ordering constraints would slow down these fast-path APIs.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Can't the compiler also reorder this code? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| No, the volatile casts in READ_ONCE() and WRITE_ONCE() |
+| prevent the compiler from reordering in this particular case. |
++-----------------------------------------------------------------------+
+
+Readers Do Not Exclude Updaters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Neither rcu_read_lock() nor rcu_read_unlock() exclude updates.
+All they do is to prevent grace periods from ending. The following
+example illustrates this:
+
+ ::
+
+ 1 void thread0(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 r1 = READ_ONCE(y);
+ 5 if (r1) {
+ 6 do_something_with_nonzero_x();
+ 7 r2 = READ_ONCE(x);
+ 8 WARN_ON(!r2); /* BUG!!! */
+ 9 }
+ 10 rcu_read_unlock();
+ 11 }
+ 12
+ 13 void thread1(void)
+ 14 {
+ 15 spin_lock(&my_lock);
+ 16 WRITE_ONCE(x, 1);
+ 17 WRITE_ONCE(y, 1);
+ 18 spin_unlock(&my_lock);
+ 19 }
+
+If the thread0() function's rcu_read_lock() excluded the
+thread1() function's update, the WARN_ON() could never fire. But
+the fact is that rcu_read_lock() does not exclude much of anything
+aside from subsequent grace periods, of which thread1() has none, so
+the WARN_ON() can and does fire.
+
+Updaters Only Wait For Old Readers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It might be tempting to assume that after synchronize_rcu()
+completes, there are no readers executing. This temptation must be
+avoided because new readers can start immediately after
+synchronize_rcu() starts, and synchronize_rcu() is under no
+obligation to wait for these new readers.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Suppose that synchronize_rcu() did wait until *all* readers had |
+| completed instead of waiting only on pre-existing readers. For how |
+| long would the updater be able to rely on there being no readers? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| For no time at all. Even if synchronize_rcu() were to wait until |
+| all readers had completed, a new reader might start immediately after |
+| synchronize_rcu() completed. Therefore, the code following |
+| synchronize_rcu() can *never* rely on there being no readers. |
++-----------------------------------------------------------------------+
+
+Grace Periods Don't Partition Read-Side Critical Sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is tempting to assume that if any part of one RCU read-side critical
+section precedes a given grace period, and if any part of another RCU
+read-side critical section follows that same grace period, then all of
+the first RCU read-side critical section must precede all of the second.
+However, this just isn't the case: A single grace period does not
+partition the set of RCU read-side critical sections. An example of this
+situation can be illustrated as follows, where ``x``, ``y``, and ``z``
+are initially all zero:
+
+ ::
+
+ 1 void thread0(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 WRITE_ONCE(a, 1);
+ 5 WRITE_ONCE(b, 1);
+ 6 rcu_read_unlock();
+ 7 }
+ 8
+ 9 void thread1(void)
+ 10 {
+ 11 r1 = READ_ONCE(a);
+ 12 synchronize_rcu();
+ 13 WRITE_ONCE(c, 1);
+ 14 }
+ 15
+ 16 void thread2(void)
+ 17 {
+ 18 rcu_read_lock();
+ 19 r2 = READ_ONCE(b);
+ 20 r3 = READ_ONCE(c);
+ 21 rcu_read_unlock();
+ 22 }
+
+It turns out that the outcome:
+
+ ::
+
+ (r1 == 1 && r2 == 0 && r3 == 1)
+
+is entirely possible. The following figure show how this can happen,
+with each circled ``QS`` indicating the point at which RCU recorded a
+*quiescent state* for each thread, that is, a state in which RCU knows
+that the thread cannot be in the midst of an RCU read-side critical
+section that started before the current grace period:
+
+.. kernel-figure:: GPpartitionReaders1.svg
+
+If it is necessary to partition RCU read-side critical sections in this
+manner, it is necessary to use two grace periods, where the first grace
+period is known to end before the second grace period starts:
+
+ ::
+
+ 1 void thread0(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 WRITE_ONCE(a, 1);
+ 5 WRITE_ONCE(b, 1);
+ 6 rcu_read_unlock();
+ 7 }
+ 8
+ 9 void thread1(void)
+ 10 {
+ 11 r1 = READ_ONCE(a);
+ 12 synchronize_rcu();
+ 13 WRITE_ONCE(c, 1);
+ 14 }
+ 15
+ 16 void thread2(void)
+ 17 {
+ 18 r2 = READ_ONCE(c);
+ 19 synchronize_rcu();
+ 20 WRITE_ONCE(d, 1);
+ 21 }
+ 22
+ 23 void thread3(void)
+ 24 {
+ 25 rcu_read_lock();
+ 26 r3 = READ_ONCE(b);
+ 27 r4 = READ_ONCE(d);
+ 28 rcu_read_unlock();
+ 29 }
+
+Here, if ``(r1 == 1)``, then thread0()'s write to ``b`` must happen
+before the end of thread1()'s grace period. If in addition
+``(r4 == 1)``, then thread3()'s read from ``b`` must happen after
+the beginning of thread2()'s grace period. If it is also the case
+that ``(r2 == 1)``, then the end of thread1()'s grace period must
+precede the beginning of thread2()'s grace period. This mean that
+the two RCU read-side critical sections cannot overlap, guaranteeing
+that ``(r3 == 1)``. As a result, the outcome:
+
+ ::
+
+ (r1 == 1 && r2 == 1 && r3 == 0 && r4 == 1)
+
+cannot happen.
+
+This non-requirement was also non-premeditated, but became apparent when
+studying RCU's interaction with memory ordering.
+
+Read-Side Critical Sections Don't Partition Grace Periods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is also tempting to assume that if an RCU read-side critical section
+happens between a pair of grace periods, then those grace periods cannot
+overlap. However, this temptation leads nowhere good, as can be
+illustrated by the following, with all variables initially zero:
+
+ ::
+
+ 1 void thread0(void)
+ 2 {
+ 3 rcu_read_lock();
+ 4 WRITE_ONCE(a, 1);
+ 5 WRITE_ONCE(b, 1);
+ 6 rcu_read_unlock();
+ 7 }
+ 8
+ 9 void thread1(void)
+ 10 {
+ 11 r1 = READ_ONCE(a);
+ 12 synchronize_rcu();
+ 13 WRITE_ONCE(c, 1);
+ 14 }
+ 15
+ 16 void thread2(void)
+ 17 {
+ 18 rcu_read_lock();
+ 19 WRITE_ONCE(d, 1);
+ 20 r2 = READ_ONCE(c);
+ 21 rcu_read_unlock();
+ 22 }
+ 23
+ 24 void thread3(void)
+ 25 {
+ 26 r3 = READ_ONCE(d);
+ 27 synchronize_rcu();
+ 28 WRITE_ONCE(e, 1);
+ 29 }
+ 30
+ 31 void thread4(void)
+ 32 {
+ 33 rcu_read_lock();
+ 34 r4 = READ_ONCE(b);
+ 35 r5 = READ_ONCE(e);
+ 36 rcu_read_unlock();
+ 37 }
+
+In this case, the outcome:
+
+ ::
+
+ (r1 == 1 && r2 == 1 && r3 == 1 && r4 == 0 && r5 == 1)
+
+is entirely possible, as illustrated below:
+
+.. kernel-figure:: ReadersPartitionGP1.svg
+
+Again, an RCU read-side critical section can overlap almost all of a
+given grace period, just so long as it does not overlap the entire grace
+period. As a result, an RCU read-side critical section cannot partition
+a pair of RCU grace periods.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| How long a sequence of grace periods, each separated by an RCU |
+| read-side critical section, would be required to partition the RCU |
+| read-side critical sections at the beginning and end of the chain? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| In theory, an infinite number. In practice, an unknown number that is |
+| sensitive to both implementation details and timing considerations. |
+| Therefore, even in practice, RCU users must abide by the theoretical |
+| rather than the practical answer. |
++-----------------------------------------------------------------------+
+
+Parallelism Facts of Life
+-------------------------
+
+These parallelism facts of life are by no means specific to RCU, but the
+RCU implementation must abide by them. They therefore bear repeating:
+
+#. Any CPU or task may be delayed at any time, and any attempts to avoid
+ these delays by disabling preemption, interrupts, or whatever are
+ completely futile. This is most obvious in preemptible user-level
+ environments and in virtualized environments (where a given guest
+ OS's VCPUs can be preempted at any time by the underlying
+ hypervisor), but can also happen in bare-metal environments due to
+ ECC errors, NMIs, and other hardware events. Although a delay of more
+ than about 20 seconds can result in splats, the RCU implementation is
+ obligated to use algorithms that can tolerate extremely long delays,
+ but where “extremely long” is not long enough to allow wrap-around
+ when incrementing a 64-bit counter.
+#. Both the compiler and the CPU can reorder memory accesses. Where it
+ matters, RCU must use compiler directives and memory-barrier
+ instructions to preserve ordering.
+#. Conflicting writes to memory locations in any given cache line will
+ result in expensive cache misses. Greater numbers of concurrent
+ writes and more-frequent concurrent writes will result in more
+ dramatic slowdowns. RCU is therefore obligated to use algorithms that
+ have sufficient locality to avoid significant performance and
+ scalability problems.
+#. As a rough rule of thumb, only one CPU's worth of processing may be
+ carried out under the protection of any given exclusive lock. RCU
+ must therefore use scalable locking designs.
+#. Counters are finite, especially on 32-bit systems. RCU's use of
+ counters must therefore tolerate counter wrap, or be designed such
+ that counter wrap would take way more time than a single system is
+ likely to run. An uptime of ten years is quite possible, a runtime of
+ a century much less so. As an example of the latter, RCU's
+ dyntick-idle nesting counter allows 54 bits for interrupt nesting
+ level (this counter is 64 bits even on a 32-bit system). Overflowing
+ this counter requires 2\ :sup:`54` half-interrupts on a given CPU
+ without that CPU ever going idle. If a half-interrupt happened every
+ microsecond, it would take 570 years of runtime to overflow this
+ counter, which is currently believed to be an acceptably long time.
+#. Linux systems can have thousands of CPUs running a single Linux
+ kernel in a single shared-memory environment. RCU must therefore pay
+ close attention to high-end scalability.
+
+This last parallelism fact of life means that RCU must pay special
+attention to the preceding facts of life. The idea that Linux might
+scale to systems with thousands of CPUs would have been met with some
+skepticism in the 1990s, but these requirements would have otherwise
+have been unsurprising, even in the early 1990s.
+
+Quality-of-Implementation Requirements
+--------------------------------------
+
+These sections list quality-of-implementation requirements. Although an
+RCU implementation that ignores these requirements could still be used,
+it would likely be subject to limitations that would make it
+inappropriate for industrial-strength production use. Classes of
+quality-of-implementation requirements are as follows:
+
+#. `Specialization`_
+#. `Performance and Scalability`_
+#. `Forward Progress`_
+#. `Composability`_
+#. `Corner Cases`_
+
+These classes is covered in the following sections.
+
+Specialization
+~~~~~~~~~~~~~~
+
+RCU is and always has been intended primarily for read-mostly
+situations, which means that RCU's read-side primitives are optimized,
+often at the expense of its update-side primitives. Experience thus far
+is captured by the following list of situations:
+
+#. Read-mostly data, where stale and inconsistent data is not a problem:
+ RCU works great!
+#. Read-mostly data, where data must be consistent: RCU works well.
+#. Read-write data, where data must be consistent: RCU *might* work OK.
+ Or not.
+#. Write-mostly data, where data must be consistent: RCU is very
+ unlikely to be the right tool for the job, with the following
+ exceptions, where RCU can provide:
+
+ a. Existence guarantees for update-friendly mechanisms.
+ b. Wait-free read-side primitives for real-time use.
+
+This focus on read-mostly situations means that RCU must interoperate
+with other synchronization primitives. For example, the add_gp() and
+remove_gp_synchronous() examples discussed earlier use RCU to
+protect readers and locking to coordinate updaters. However, the need
+extends much farther, requiring that a variety of synchronization
+primitives be legal within RCU read-side critical sections, including
+spinlocks, sequence locks, atomic operations, reference counters, and
+memory barriers.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| What about sleeping locks? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| These are forbidden within Linux-kernel RCU read-side critical |
+| sections because it is not legal to place a quiescent state (in this |
+| case, voluntary context switch) within an RCU read-side critical |
+| section. However, sleeping locks may be used within userspace RCU |
+| read-side critical sections, and also within Linux-kernel sleepable |
+| RCU `(SRCU) <Sleepable RCU_>`__ read-side critical sections. In |
+| addition, the -rt patchset turns spinlocks into a sleeping locks so |
+| that the corresponding critical sections can be preempted, which also |
+| means that these sleeplockified spinlocks (but not other sleeping |
+| locks!) may be acquire within -rt-Linux-kernel RCU read-side critical |
+| sections. |
+| Note that it *is* legal for a normal RCU read-side critical section |
+| to conditionally acquire a sleeping locks (as in |
+| mutex_trylock()), but only as long as it does not loop |
+| indefinitely attempting to conditionally acquire that sleeping locks. |
+| The key point is that things like mutex_trylock() either return |
+| with the mutex held, or return an error indication if the mutex was |
+| not immediately available. Either way, mutex_trylock() returns |
+| immediately without sleeping. |
++-----------------------------------------------------------------------+
+
+It often comes as a surprise that many algorithms do not require a
+consistent view of data, but many can function in that mode, with
+network routing being the poster child. Internet routing algorithms take
+significant time to propagate updates, so that by the time an update
+arrives at a given system, that system has been sending network traffic
+the wrong way for a considerable length of time. Having a few threads
+continue to send traffic the wrong way for a few more milliseconds is
+clearly not a problem: In the worst case, TCP retransmissions will
+eventually get the data where it needs to go. In general, when tracking
+the state of the universe outside of the computer, some level of
+inconsistency must be tolerated due to speed-of-light delays if nothing
+else.
+
+Furthermore, uncertainty about external state is inherent in many cases.
+For example, a pair of veterinarians might use heartbeat to determine
+whether or not a given cat was alive. But how long should they wait
+after the last heartbeat to decide that the cat is in fact dead? Waiting
+less than 400 milliseconds makes no sense because this would mean that a
+relaxed cat would be considered to cycle between death and life more
+than 100 times per minute. Moreover, just as with human beings, a cat's
+heart might stop for some period of time, so the exact wait period is a
+judgment call. One of our pair of veterinarians might wait 30 seconds
+before pronouncing the cat dead, while the other might insist on waiting
+a full minute. The two veterinarians would then disagree on the state of
+the cat during the final 30 seconds of the minute following the last
+heartbeat.
+
+Interestingly enough, this same situation applies to hardware. When push
+comes to shove, how do we tell whether or not some external server has
+failed? We send messages to it periodically, and declare it failed if we
+don't receive a response within a given period of time. Policy decisions
+can usually tolerate short periods of inconsistency. The policy was
+decided some time ago, and is only now being put into effect, so a few
+milliseconds of delay is normally inconsequential.
+
+However, there are algorithms that absolutely must see consistent data.
+For example, the translation between a user-level SystemV semaphore ID
+to the corresponding in-kernel data structure is protected by RCU, but
+it is absolutely forbidden to update a semaphore that has just been
+removed. In the Linux kernel, this need for consistency is accommodated
+by acquiring spinlocks located in the in-kernel data structure from
+within the RCU read-side critical section, and this is indicated by the
+green box in the figure above. Many other techniques may be used, and
+are in fact used within the Linux kernel.
+
+In short, RCU is not required to maintain consistency, and other
+mechanisms may be used in concert with RCU when consistency is required.
+RCU's specialization allows it to do its job extremely well, and its
+ability to interoperate with other synchronization mechanisms allows the
+right mix of synchronization tools to be used for a given job.
+
+Performance and Scalability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Energy efficiency is a critical component of performance today, and
+Linux-kernel RCU implementations must therefore avoid unnecessarily
+awakening idle CPUs. I cannot claim that this requirement was
+premeditated. In fact, I learned of it during a telephone conversation
+in which I was given “frank and open” feedback on the importance of
+energy efficiency in battery-powered systems and on specific
+energy-efficiency shortcomings of the Linux-kernel RCU implementation.
+In my experience, the battery-powered embedded community will consider
+any unnecessary wakeups to be extremely unfriendly acts. So much so that
+mere Linux-kernel-mailing-list posts are insufficient to vent their ire.
+
+Memory consumption is not particularly important for in most situations,
+and has become decreasingly so as memory sizes have expanded and memory
+costs have plummeted. However, as I learned from Matt Mackall's
+`bloatwatch <http://elinux.org/Linux_Tiny-FAQ>`__ efforts, memory
+footprint is critically important on single-CPU systems with
+non-preemptible (``CONFIG_PREEMPTION=n``) kernels, and thus `tiny
+RCU <https://lore.kernel.org/r/20090113221724.GA15307@linux.vnet.ibm.com>`__
+was born. Josh Triplett has since taken over the small-memory banner
+with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__
+project, which resulted in `SRCU <Sleepable RCU_>`__ becoming optional
+for those kernels not needing it.
+
+The remaining performance requirements are, for the most part,
+unsurprising. For example, in keeping with RCU's read-side
+specialization, rcu_dereference() should have negligible overhead
+(for example, suppression of a few minor compiler optimizations).
+Similarly, in non-preemptible environments, rcu_read_lock() and
+rcu_read_unlock() should have exactly zero overhead.
+
+In preemptible environments, in the case where the RCU read-side
+critical section was not preempted (as will be the case for the
+highest-priority real-time process), rcu_read_lock() and
+rcu_read_unlock() should have minimal overhead. In particular, they
+should not contain atomic read-modify-write operations, memory-barrier
+instructions, preemption disabling, interrupt disabling, or backwards
+branches. However, in the case where the RCU read-side critical section
+was preempted, rcu_read_unlock() may acquire spinlocks and disable
+interrupts. This is why it is better to nest an RCU read-side critical
+section within a preempt-disable region than vice versa, at least in
+cases where that critical section is short enough to avoid unduly
+degrading real-time latencies.
+
+The synchronize_rcu() grace-period-wait primitive is optimized for
+throughput. It may therefore incur several milliseconds of latency in
+addition to the duration of the longest RCU read-side critical section.
+On the other hand, multiple concurrent invocations of
+synchronize_rcu() are required to use batching optimizations so that
+they can be satisfied by a single underlying grace-period-wait
+operation. For example, in the Linux kernel, it is not unusual for a
+single grace-period-wait operation to serve more than `1,000 separate
+invocations <https://www.usenix.org/conference/2004-usenix-annual-technical-conference/making-rcu-safe-deep-sub-millisecond-response>`__
+of synchronize_rcu(), thus amortizing the per-invocation overhead
+down to nearly zero. However, the grace-period optimization is also
+required to avoid measurable degradation of real-time scheduling and
+interrupt latencies.
+
+In some cases, the multi-millisecond synchronize_rcu() latencies are
+unacceptable. In these cases, synchronize_rcu_expedited() may be
+used instead, reducing the grace-period latency down to a few tens of
+microseconds on small systems, at least in cases where the RCU read-side
+critical sections are short. There are currently no special latency
+requirements for synchronize_rcu_expedited() on large systems, but,
+consistent with the empirical nature of the RCU specification, that is
+subject to change. However, there most definitely are scalability
+requirements: A storm of synchronize_rcu_expedited() invocations on
+4096 CPUs should at least make reasonable forward progress. In return
+for its shorter latencies, synchronize_rcu_expedited() is permitted
+to impose modest degradation of real-time latency on non-idle online
+CPUs. Here, “modest” means roughly the same latency degradation as a
+scheduling-clock interrupt.
+
+There are a number of situations where even
+synchronize_rcu_expedited()'s reduced grace-period latency is
+unacceptable. In these situations, the asynchronous call_rcu() can
+be used in place of synchronize_rcu() as follows:
+
+ ::
+
+ 1 struct foo {
+ 2 int a;
+ 3 int b;
+ 4 struct rcu_head rh;
+ 5 };
+ 6
+ 7 static void remove_gp_cb(struct rcu_head *rhp)
+ 8 {
+ 9 struct foo *p = container_of(rhp, struct foo, rh);
+ 10
+ 11 kfree(p);
+ 12 }
+ 13
+ 14 bool remove_gp_asynchronous(void)
+ 15 {
+ 16 struct foo *p;
+ 17
+ 18 spin_lock(&gp_lock);
+ 19 p = rcu_access_pointer(gp);
+ 20 if (!p) {
+ 21 spin_unlock(&gp_lock);
+ 22 return false;
+ 23 }
+ 24 rcu_assign_pointer(gp, NULL);
+ 25 call_rcu(&p->rh, remove_gp_cb);
+ 26 spin_unlock(&gp_lock);
+ 27 return true;
+ 28 }
+
+A definition of ``struct foo`` is finally needed, and appears on
+lines 1-5. The function remove_gp_cb() is passed to call_rcu()
+on line 25, and will be invoked after the end of a subsequent grace
+period. This gets the same effect as remove_gp_synchronous(), but
+without forcing the updater to wait for a grace period to elapse. The
+call_rcu() function may be used in a number of situations where
+neither synchronize_rcu() nor synchronize_rcu_expedited() would
+be legal, including within preempt-disable code, local_bh_disable()
+code, interrupt-disable code, and interrupt handlers. However, even
+call_rcu() is illegal within NMI handlers and from idle and offline
+CPUs. The callback function (remove_gp_cb() in this case) will be
+executed within softirq (software interrupt) environment within the
+Linux kernel, either within a real softirq handler or under the
+protection of local_bh_disable(). In both the Linux kernel and in
+userspace, it is bad practice to write an RCU callback function that
+takes too long. Long-running operations should be relegated to separate
+threads or (in the Linux kernel) workqueues.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why does line 19 use rcu_access_pointer()? After all, |
+| call_rcu() on line 25 stores into the structure, which would |
+| interact badly with concurrent insertions. Doesn't this mean that |
+| rcu_dereference() is required? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Presumably the ``->gp_lock`` acquired on line 18 excludes any |
+| changes, including any insertions that rcu_dereference() would |
+| protect against. Therefore, any insertions will be delayed until |
+| after ``->gp_lock`` is released on line 25, which in turn means that |
+| rcu_access_pointer() suffices. |
++-----------------------------------------------------------------------+
+
+However, all that remove_gp_cb() is doing is invoking kfree() on
+the data element. This is a common idiom, and is supported by
+kfree_rcu(), which allows “fire and forget” operation as shown
+below:
+
+ ::
+
+ 1 struct foo {
+ 2 int a;
+ 3 int b;
+ 4 struct rcu_head rh;
+ 5 };
+ 6
+ 7 bool remove_gp_faf(void)
+ 8 {
+ 9 struct foo *p;
+ 10
+ 11 spin_lock(&gp_lock);
+ 12 p = rcu_dereference(gp);
+ 13 if (!p) {
+ 14 spin_unlock(&gp_lock);
+ 15 return false;
+ 16 }
+ 17 rcu_assign_pointer(gp, NULL);
+ 18 kfree_rcu(p, rh);
+ 19 spin_unlock(&gp_lock);
+ 20 return true;
+ 21 }
+
+Note that remove_gp_faf() simply invokes kfree_rcu() and
+proceeds, without any need to pay any further attention to the
+subsequent grace period and kfree(). It is permissible to invoke
+kfree_rcu() from the same environments as for call_rcu().
+Interestingly enough, DYNIX/ptx had the equivalents of call_rcu()
+and kfree_rcu(), but not synchronize_rcu(). This was due to the
+fact that RCU was not heavily used within DYNIX/ptx, so the very few
+places that needed something like synchronize_rcu() simply
+open-coded it.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Earlier it was claimed that call_rcu() and kfree_rcu() |
+| allowed updaters to avoid being blocked by readers. But how can that |
+| be correct, given that the invocation of the callback and the freeing |
+| of the memory (respectively) must still wait for a grace period to |
+| elapse? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| We could define things this way, but keep in mind that this sort of |
+| definition would say that updates in garbage-collected languages |
+| cannot complete until the next time the garbage collector runs, which |
+| does not seem at all reasonable. The key point is that in most cases, |
+| an updater using either call_rcu() or kfree_rcu() can proceed |
+| to the next update as soon as it has invoked call_rcu() or |
+| kfree_rcu(), without having to wait for a subsequent grace |
+| period. |
++-----------------------------------------------------------------------+
+
+But what if the updater must wait for the completion of code to be
+executed after the end of the grace period, but has other tasks that can
+be carried out in the meantime? The polling-style
+get_state_synchronize_rcu() and cond_synchronize_rcu() functions
+may be used for this purpose, as shown below:
+
+ ::
+
+ 1 bool remove_gp_poll(void)
+ 2 {
+ 3 struct foo *p;
+ 4 unsigned long s;
+ 5
+ 6 spin_lock(&gp_lock);
+ 7 p = rcu_access_pointer(gp);
+ 8 if (!p) {
+ 9 spin_unlock(&gp_lock);
+ 10 return false;
+ 11 }
+ 12 rcu_assign_pointer(gp, NULL);
+ 13 spin_unlock(&gp_lock);
+ 14 s = get_state_synchronize_rcu();
+ 15 do_something_while_waiting();
+ 16 cond_synchronize_rcu(s);
+ 17 kfree(p);
+ 18 return true;
+ 19 }
+
+On line 14, get_state_synchronize_rcu() obtains a “cookie” from RCU,
+then line 15 carries out other tasks, and finally, line 16 returns
+immediately if a grace period has elapsed in the meantime, but otherwise
+waits as required. The need for ``get_state_synchronize_rcu`` and
+cond_synchronize_rcu() has appeared quite recently, so it is too
+early to tell whether they will stand the test of time.
+
+RCU thus provides a range of tools to allow updaters to strike the
+required tradeoff between latency, flexibility and CPU overhead.
+
+Forward Progress
+~~~~~~~~~~~~~~~~
+
+In theory, delaying grace-period completion and callback invocation is
+harmless. In practice, not only are memory sizes finite but also
+callbacks sometimes do wakeups, and sufficiently deferred wakeups can be
+difficult to distinguish from system hangs. Therefore, RCU must provide
+a number of mechanisms to promote forward progress.
+
+These mechanisms are not foolproof, nor can they be. For one simple
+example, an infinite loop in an RCU read-side critical section must by
+definition prevent later grace periods from ever completing. For a more
+involved example, consider a 64-CPU system built with
+``CONFIG_RCU_NOCB_CPU=y`` and booted with ``rcu_nocbs=1-63``, where
+CPUs 1 through 63 spin in tight loops that invoke call_rcu(). Even
+if these tight loops also contain calls to cond_resched() (thus
+allowing grace periods to complete), CPU 0 simply will not be able to
+invoke callbacks as fast as the other 63 CPUs can register them, at
+least not until the system runs out of memory. In both of these
+examples, the Spiderman principle applies: With great power comes great
+responsibility. However, short of this level of abuse, RCU is required
+to ensure timely completion of grace periods and timely invocation of
+callbacks.
+
+RCU takes the following steps to encourage timely completion of grace
+periods:
+
+#. If a grace period fails to complete within 100 milliseconds, RCU
+ causes future invocations of cond_resched() on the holdout CPUs
+ to provide an RCU quiescent state. RCU also causes those CPUs'
+ need_resched() invocations to return ``true``, but only after the
+ corresponding CPU's next scheduling-clock.
+#. CPUs mentioned in the ``nohz_full`` kernel boot parameter can run
+ indefinitely in the kernel without scheduling-clock interrupts, which
+ defeats the above need_resched() strategem. RCU will therefore
+ invoke resched_cpu() on any ``nohz_full`` CPUs still holding out
+ after 109 milliseconds.
+#. In kernels built with ``CONFIG_RCU_BOOST=y``, if a given task that
+ has been preempted within an RCU read-side critical section is
+ holding out for more than 500 milliseconds, RCU will resort to
+ priority boosting.
+#. If a CPU is still holding out 10 seconds into the grace period, RCU
+ will invoke resched_cpu() on it regardless of its ``nohz_full``
+ state.
+
+The above values are defaults for systems running with ``HZ=1000``. They
+will vary as the value of ``HZ`` varies, and can also be changed using
+the relevant Kconfig options and kernel boot parameters. RCU currently
+does not do much sanity checking of these parameters, so please use
+caution when changing them. Note that these forward-progress measures
+are provided only for RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks
+RCU`_.
+
+RCU takes the following steps in call_rcu() to encourage timely
+invocation of callbacks when any given non-\ ``rcu_nocbs`` CPU has
+10,000 callbacks, or has 10,000 more callbacks than it had the last time
+encouragement was provided:
+
+#. Starts a grace period, if one is not already in progress.
+#. Forces immediate checking for quiescent states, rather than waiting
+ for three milliseconds to have elapsed since the beginning of the
+ grace period.
+#. Immediately tags the CPU's callbacks with their grace period
+ completion numbers, rather than waiting for the ``RCU_SOFTIRQ``
+ handler to get around to it.
+#. Lifts callback-execution batch limits, which speeds up callback
+ invocation at the expense of degrading realtime response.
+
+Again, these are default values when running at ``HZ=1000``, and can be
+overridden. Again, these forward-progress measures are provided only for
+RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks
+RCU`_. Even for RCU, callback-invocation forward
+progress for ``rcu_nocbs`` CPUs is much less well-developed, in part
+because workloads benefiting from ``rcu_nocbs`` CPUs tend to invoke
+call_rcu() relatively infrequently. If workloads emerge that need
+both ``rcu_nocbs`` CPUs and high call_rcu() invocation rates, then
+additional forward-progress work will be required.
+
+Composability
+~~~~~~~~~~~~~
+
+Composability has received much attention in recent years, perhaps in
+part due to the collision of multicore hardware with object-oriented
+techniques designed in single-threaded environments for single-threaded
+use. And in theory, RCU read-side critical sections may be composed, and
+in fact may be nested arbitrarily deeply. In practice, as with all
+real-world implementations of composable constructs, there are
+limitations.
+
+Implementations of RCU for which rcu_read_lock() and
+rcu_read_unlock() generate no code, such as Linux-kernel RCU when
+``CONFIG_PREEMPTION=n``, can be nested arbitrarily deeply. After all, there
+is no overhead. Except that if all these instances of
+rcu_read_lock() and rcu_read_unlock() are visible to the
+compiler, compilation will eventually fail due to exhausting memory,
+mass storage, or user patience, whichever comes first. If the nesting is
+not visible to the compiler, as is the case with mutually recursive
+functions each in its own translation unit, stack overflow will result.
+If the nesting takes the form of loops, perhaps in the guise of tail
+recursion, either the control variable will overflow or (in the Linux
+kernel) you will get an RCU CPU stall warning. Nevertheless, this class
+of RCU implementations is one of the most composable constructs in
+existence.
+
+RCU implementations that explicitly track nesting depth are limited by
+the nesting-depth counter. For example, the Linux kernel's preemptible
+RCU limits nesting to ``INT_MAX``. This should suffice for almost all
+practical purposes. That said, a consecutive pair of RCU read-side
+critical sections between which there is an operation that waits for a
+grace period cannot be enclosed in another RCU read-side critical
+section. This is because it is not legal to wait for a grace period
+within an RCU read-side critical section: To do so would result either
+in deadlock or in RCU implicitly splitting the enclosing RCU read-side
+critical section, neither of which is conducive to a long-lived and
+prosperous kernel.
+
+It is worth noting that RCU is not alone in limiting composability. For
+example, many transactional-memory implementations prohibit composing a
+pair of transactions separated by an irrevocable operation (for example,
+a network receive operation). For another example, lock-based critical
+sections can be composed surprisingly freely, but only if deadlock is
+avoided.
+
+In short, although RCU read-side critical sections are highly
+composable, care is required in some situations, just as is the case for
+any other composable synchronization mechanism.
+
+Corner Cases
+~~~~~~~~~~~~
+
+A given RCU workload might have an endless and intense stream of RCU
+read-side critical sections, perhaps even so intense that there was
+never a point in time during which there was not at least one RCU
+read-side critical section in flight. RCU cannot allow this situation to
+block grace periods: As long as all the RCU read-side critical sections
+are finite, grace periods must also be finite.
+
+That said, preemptible RCU implementations could potentially result in
+RCU read-side critical sections being preempted for long durations,
+which has the effect of creating a long-duration RCU read-side critical
+section. This situation can arise only in heavily loaded systems, but
+systems using real-time priorities are of course more vulnerable.
+Therefore, RCU priority boosting is provided to help deal with this
+case. That said, the exact requirements on RCU priority boosting will
+likely evolve as more experience accumulates.
+
+Other workloads might have very high update rates. Although one can
+argue that such workloads should instead use something other than RCU,
+the fact remains that RCU must handle such workloads gracefully. This
+requirement is another factor driving batching of grace periods, but it
+is also the driving force behind the checks for large numbers of queued
+RCU callbacks in the call_rcu() code path. Finally, high update
+rates should not delay RCU read-side critical sections, although some
+small read-side delays can occur when using
+synchronize_rcu_expedited(), courtesy of this function's use of
+smp_call_function_single().
+
+Although all three of these corner cases were understood in the early
+1990s, a simple user-level test consisting of ``close(open(path))`` in a
+tight loop in the early 2000s suddenly provided a much deeper
+appreciation of the high-update-rate corner case. This test also
+motivated addition of some RCU code to react to high update rates, for
+example, if a given CPU finds itself with more than 10,000 RCU callbacks
+queued, it will cause RCU to take evasive action by more aggressively
+starting grace periods and more aggressively forcing completion of
+grace-period processing. This evasive action causes the grace period to
+complete more quickly, but at the cost of restricting RCU's batching
+optimizations, thus increasing the CPU overhead incurred by that grace
+period.
+
+Software-Engineering Requirements
+---------------------------------
+
+Between Murphy's Law and “To err is human”, it is necessary to guard
+against mishaps and misuse:
+
+#. It is all too easy to forget to use rcu_read_lock() everywhere
+ that it is needed, so kernels built with ``CONFIG_PROVE_RCU=y`` will
+ splat if rcu_dereference() is used outside of an RCU read-side
+ critical section. Update-side code can use
+ rcu_dereference_protected(), which takes a `lockdep
+ expression <https://lwn.net/Articles/371986/>`__ to indicate what is
+ providing the protection. If the indicated protection is not
+ provided, a lockdep splat is emitted.
+ Code shared between readers and updaters can use
+ rcu_dereference_check(), which also takes a lockdep expression,
+ and emits a lockdep splat if neither rcu_read_lock() nor the
+ indicated protection is in place. In addition,
+ rcu_dereference_raw() is used in those (hopefully rare) cases
+ where the required protection cannot be easily described. Finally,
+ rcu_read_lock_held() is provided to allow a function to verify
+ that it has been invoked within an RCU read-side critical section. I
+ was made aware of this set of requirements shortly after Thomas
+ Gleixner audited a number of RCU uses.
+#. A given function might wish to check for RCU-related preconditions
+ upon entry, before using any other RCU API. The
+ rcu_lockdep_assert() does this job, asserting the expression in
+ kernels having lockdep enabled and doing nothing otherwise.
+#. It is also easy to forget to use rcu_assign_pointer() and
+ rcu_dereference(), perhaps (incorrectly) substituting a simple
+ assignment. To catch this sort of error, a given RCU-protected
+ pointer may be tagged with ``__rcu``, after which sparse will
+ complain about simple-assignment accesses to that pointer. Arnd
+ Bergmann made me aware of this requirement, and also supplied the
+ needed `patch series <https://lwn.net/Articles/376011/>`__.
+#. Kernels built with ``CONFIG_DEBUG_OBJECTS_RCU_HEAD=y`` will splat if
+ a data element is passed to call_rcu() twice in a row, without a
+ grace period in between. (This error is similar to a double free.)
+ The corresponding ``rcu_head`` structures that are dynamically
+ allocated are automatically tracked, but ``rcu_head`` structures
+ allocated on the stack must be initialized with
+ init_rcu_head_on_stack() and cleaned up with
+ destroy_rcu_head_on_stack(). Similarly, statically allocated
+ non-stack ``rcu_head`` structures must be initialized with
+ init_rcu_head() and cleaned up with destroy_rcu_head().
+ Mathieu Desnoyers made me aware of this requirement, and also
+ supplied the needed
+ `patch <https://lore.kernel.org/r/20100319013024.GA28456@Krystal>`__.
+#. An infinite loop in an RCU read-side critical section will eventually
+ trigger an RCU CPU stall warning splat, with the duration of
+ “eventually” being controlled by the ``RCU_CPU_STALL_TIMEOUT``
+ ``Kconfig`` option, or, alternatively, by the
+ ``rcupdate.rcu_cpu_stall_timeout`` boot/sysfs parameter. However, RCU
+ is not obligated to produce this splat unless there is a grace period
+ waiting on that particular RCU read-side critical section.
+
+ Some extreme workloads might intentionally delay RCU grace periods,
+ and systems running those workloads can be booted with
+ ``rcupdate.rcu_cpu_stall_suppress`` to suppress the splats. This
+ kernel parameter may also be set via ``sysfs``. Furthermore, RCU CPU
+ stall warnings are counter-productive during sysrq dumps and during
+ panics. RCU therefore supplies the rcu_sysrq_start() and
+ rcu_sysrq_end() API members to be called before and after long
+ sysrq dumps. RCU also supplies the rcu_panic() notifier that is
+ automatically invoked at the beginning of a panic to suppress further
+ RCU CPU stall warnings.
+
+ This requirement made itself known in the early 1990s, pretty much
+ the first time that it was necessary to debug a CPU stall. That said,
+ the initial implementation in DYNIX/ptx was quite generic in
+ comparison with that of Linux.
+
+#. Although it would be very good to detect pointers leaking out of RCU
+ read-side critical sections, there is currently no good way of doing
+ this. One complication is the need to distinguish between pointers
+ leaking and pointers that have been handed off from RCU to some other
+ synchronization mechanism, for example, reference counting.
+#. In kernels built with ``CONFIG_RCU_TRACE=y``, RCU-related information
+ is provided via event tracing.
+#. Open-coded use of rcu_assign_pointer() and rcu_dereference()
+ to create typical linked data structures can be surprisingly
+ error-prone. Therefore, RCU-protected `linked
+ lists <https://lwn.net/Articles/609973/#RCU%20List%20APIs>`__ and,
+ more recently, RCU-protected `hash
+ tables <https://lwn.net/Articles/612100/>`__ are available. Many
+ other special-purpose RCU-protected data structures are available in
+ the Linux kernel and the userspace RCU library.
+#. Some linked structures are created at compile time, but still require
+ ``__rcu`` checking. The RCU_POINTER_INITIALIZER() macro serves
+ this purpose.
+#. It is not necessary to use rcu_assign_pointer() when creating
+ linked structures that are to be published via a single external
+ pointer. The RCU_INIT_POINTER() macro is provided for this task.
+
+This not a hard-and-fast list: RCU's diagnostic capabilities will
+continue to be guided by the number and type of usage bugs found in
+real-world RCU usage.
+
+Linux Kernel Complications
+--------------------------
+
+The Linux kernel provides an interesting environment for all kinds of
+software, including RCU. Some of the relevant points of interest are as
+follows:
+
+#. `Configuration`_
+#. `Firmware Interface`_
+#. `Early Boot`_
+#. `Interrupts and NMIs`_
+#. `Loadable Modules`_
+#. `Hotplug CPU`_
+#. `Scheduler and RCU`_
+#. `Tracing and RCU`_
+#. `Accesses to User Memory and RCU`_
+#. `Energy Efficiency`_
+#. `Scheduling-Clock Interrupts and RCU`_
+#. `Memory Efficiency`_
+#. `Performance, Scalability, Response Time, and Reliability`_
+
+This list is probably incomplete, but it does give a feel for the most
+notable Linux-kernel complications. Each of the following sections
+covers one of the above topics.
+
+Configuration
+~~~~~~~~~~~~~
+
+RCU's goal is automatic configuration, so that almost nobody needs to
+worry about RCU's ``Kconfig`` options. And for almost all users, RCU
+does in fact work well “out of the box.”
+
+However, there are specialized use cases that are handled by kernel boot
+parameters and ``Kconfig`` options. Unfortunately, the ``Kconfig``
+system will explicitly ask users about new ``Kconfig`` options, which
+requires almost all of them be hidden behind a ``CONFIG_RCU_EXPERT``
+``Kconfig`` option.
+
+This all should be quite obvious, but the fact remains that Linus
+Torvalds recently had to
+`remind <https://lore.kernel.org/r/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com>`__
+me of this requirement.
+
+Firmware Interface
+~~~~~~~~~~~~~~~~~~
+
+In many cases, kernel obtains information about the system from the
+firmware, and sometimes things are lost in translation. Or the
+translation is accurate, but the original message is bogus.
+
+For example, some systems' firmware overreports the number of CPUs,
+sometimes by a large factor. If RCU naively believed the firmware, as it
+used to do, it would create too many per-CPU kthreads. Although the
+resulting system will still run correctly, the extra kthreads needlessly
+consume memory and can cause confusion when they show up in ``ps``
+listings.
+
+RCU must therefore wait for a given CPU to actually come online before
+it can allow itself to believe that the CPU actually exists. The
+resulting “ghost CPUs” (which are never going to come online) cause a
+number of `interesting
+complications <https://paulmck.livejournal.com/37494.html>`__.
+
+Early Boot
+~~~~~~~~~~
+
+The Linux kernel's boot sequence is an interesting process, and RCU is
+used early, even before rcu_init() is invoked. In fact, a number of
+RCU's primitives can be used as soon as the initial task's
+``task_struct`` is available and the boot CPU's per-CPU variables are
+set up. The read-side primitives (rcu_read_lock(),
+rcu_read_unlock(), rcu_dereference(), and
+rcu_access_pointer()) will operate normally very early on, as will
+rcu_assign_pointer().
+
+Although call_rcu() may be invoked at any time during boot,
+callbacks are not guaranteed to be invoked until after all of RCU's
+kthreads have been spawned, which occurs at early_initcall() time.
+This delay in callback invocation is due to the fact that RCU does not
+invoke callbacks until it is fully initialized, and this full
+initialization cannot occur until after the scheduler has initialized
+itself to the point where RCU can spawn and run its kthreads. In theory,
+it would be possible to invoke callbacks earlier, however, this is not a
+panacea because there would be severe restrictions on what operations
+those callbacks could invoke.
+
+Perhaps surprisingly, synchronize_rcu() and
+synchronize_rcu_expedited(), will operate normally during very early
+boot, the reason being that there is only one CPU and preemption is
+disabled. This means that the call synchronize_rcu() (or friends)
+itself is a quiescent state and thus a grace period, so the early-boot
+implementation can be a no-op.
+
+However, once the scheduler has spawned its first kthread, this early
+boot trick fails for synchronize_rcu() (as well as for
+synchronize_rcu_expedited()) in ``CONFIG_PREEMPTION=y`` kernels. The
+reason is that an RCU read-side critical section might be preempted,
+which means that a subsequent synchronize_rcu() really does have to
+wait for something, as opposed to simply returning immediately.
+Unfortunately, synchronize_rcu() can't do this until all of its
+kthreads are spawned, which doesn't happen until some time during
+early_initcalls() time. But this is no excuse: RCU is nevertheless
+required to correctly handle synchronous grace periods during this time
+period. Once all of its kthreads are up and running, RCU starts running
+normally.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| How can RCU possibly handle grace periods before all of its kthreads |
+| have been spawned??? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Very carefully! |
+| During the “dead zone” between the time that the scheduler spawns the |
+| first task and the time that all of RCU's kthreads have been spawned, |
+| all synchronous grace periods are handled by the expedited |
+| grace-period mechanism. At runtime, this expedited mechanism relies |
+| on workqueues, but during the dead zone the requesting task itself |
+| drives the desired expedited grace period. Because dead-zone |
+| execution takes place within task context, everything works. Once the |
+| dead zone ends, expedited grace periods go back to using workqueues, |
+| as is required to avoid problems that would otherwise occur when a |
+| user task received a POSIX signal while driving an expedited grace |
+| period. |
+| |
+| And yes, this does mean that it is unhelpful to send POSIX signals to |
+| random tasks between the time that the scheduler spawns its first |
+| kthread and the time that RCU's kthreads have all been spawned. If |
+| there ever turns out to be a good reason for sending POSIX signals |
+| during that time, appropriate adjustments will be made. (If it turns |
+| out that POSIX signals are sent during this time for no good reason, |
+| other adjustments will be made, appropriate or otherwise.) |
++-----------------------------------------------------------------------+
+
+I learned of these boot-time requirements as a result of a series of
+system hangs.
+
+Interrupts and NMIs
+~~~~~~~~~~~~~~~~~~~
+
+The Linux kernel has interrupts, and RCU read-side critical sections are
+legal within interrupt handlers and within interrupt-disabled regions of
+code, as are invocations of call_rcu().
+
+Some Linux-kernel architectures can enter an interrupt handler from
+non-idle process context, and then just never leave it, instead
+stealthily transitioning back to process context. This trick is
+sometimes used to invoke system calls from inside the kernel. These
+“half-interrupts” mean that RCU has to be very careful about how it
+counts interrupt nesting levels. I learned of this requirement the hard
+way during a rewrite of RCU's dyntick-idle code.
+
+The Linux kernel has non-maskable interrupts (NMIs), and RCU read-side
+critical sections are legal within NMI handlers. Thankfully, RCU
+update-side primitives, including call_rcu(), are prohibited within
+NMI handlers.
+
+The name notwithstanding, some Linux-kernel architectures can have
+nested NMIs, which RCU must handle correctly. Andy Lutomirski `surprised
+me <https://lore.kernel.org/r/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com>`__
+with this requirement; he also kindly surprised me with `an
+algorithm <https://lore.kernel.org/r/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com>`__
+that meets this requirement.
+
+Furthermore, NMI handlers can be interrupted by what appear to RCU to be
+normal interrupts. One way that this can happen is for code that
+directly invokes ct_irq_enter() and ct_irq_exit() to be called
+from an NMI handler. This astonishing fact of life prompted the current
+code structure, which has ct_irq_enter() invoking
+ct_nmi_enter() and ct_irq_exit() invoking ct_nmi_exit().
+And yes, I also learned of this requirement the hard way.
+
+Loadable Modules
+~~~~~~~~~~~~~~~~
+
+The Linux kernel has loadable modules, and these modules can also be
+unloaded. After a given module has been unloaded, any attempt to call
+one of its functions results in a segmentation fault. The module-unload
+functions must therefore cancel any delayed calls to loadable-module
+functions, for example, any outstanding mod_timer() must be dealt
+with via timer_shutdown_sync() or similar.
+
+Unfortunately, there is no way to cancel an RCU callback; once you
+invoke call_rcu(), the callback function is eventually going to be
+invoked, unless the system goes down first. Because it is normally
+considered socially irresponsible to crash the system in response to a
+module unload request, we need some other way to deal with in-flight RCU
+callbacks.
+
+RCU therefore provides rcu_barrier(), which waits until all
+in-flight RCU callbacks have been invoked. If a module uses
+call_rcu(), its exit function should therefore prevent any future
+invocation of call_rcu(), then invoke rcu_barrier(). In theory,
+the underlying module-unload code could invoke rcu_barrier()
+unconditionally, but in practice this would incur unacceptable
+latencies.
+
+Nikita Danilov noted this requirement for an analogous
+filesystem-unmount situation, and Dipankar Sarma incorporated
+rcu_barrier() into RCU. The need for rcu_barrier() for module
+unloading became apparent later.
+
+.. important::
+
+ The rcu_barrier() function is not, repeat,
+ *not*, obligated to wait for a grace period. It is instead only required
+ to wait for RCU callbacks that have already been posted. Therefore, if
+ there are no RCU callbacks posted anywhere in the system,
+ rcu_barrier() is within its rights to return immediately. Even if
+ there are callbacks posted, rcu_barrier() does not necessarily need
+ to wait for a grace period.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Wait a minute! Each RCU callbacks must wait for a grace period to |
+| complete, and rcu_barrier() must wait for each pre-existing |
+| callback to be invoked. Doesn't rcu_barrier() therefore need to |
+| wait for a full grace period if there is even one callback posted |
+| anywhere in the system? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Absolutely not!!! |
+| Yes, each RCU callbacks must wait for a grace period to complete, but |
+| it might well be partly (or even completely) finished waiting by the |
+| time rcu_barrier() is invoked. In that case, rcu_barrier() |
+| need only wait for the remaining portion of the grace period to |
+| elapse. So even if there are quite a few callbacks posted, |
+| rcu_barrier() might well return quite quickly. |
+| |
+| So if you need to wait for a grace period as well as for all |
+| pre-existing callbacks, you will need to invoke both |
+| synchronize_rcu() and rcu_barrier(). If latency is a concern, |
+| you can always use workqueues to invoke them concurrently. |
++-----------------------------------------------------------------------+
+
+Hotplug CPU
+~~~~~~~~~~~
+
+The Linux kernel supports CPU hotplug, which means that CPUs can come
+and go. It is of course illegal to use any RCU API member from an
+offline CPU, with the exception of `SRCU <Sleepable RCU_>`__ read-side
+critical sections. This requirement was present from day one in
+DYNIX/ptx, but on the other hand, the Linux kernel's CPU-hotplug
+implementation is “interesting.”
+
+The Linux-kernel CPU-hotplug implementation has notifiers that are used
+to allow the various kernel subsystems (including RCU) to respond
+appropriately to a given CPU-hotplug operation. Most RCU operations may
+be invoked from CPU-hotplug notifiers, including even synchronous
+grace-period operations such as (synchronize_rcu() and
+synchronize_rcu_expedited()). However, these synchronous operations
+do block and therefore cannot be invoked from notifiers that execute via
+stop_machine(), specifically those between the ``CPUHP_AP_OFFLINE``
+and ``CPUHP_AP_ONLINE`` states.
+
+In addition, all-callback-wait operations such as rcu_barrier() may
+not be invoked from any CPU-hotplug notifier. This restriction is due
+to the fact that there are phases of CPU-hotplug operations where the
+outgoing CPU's callbacks will not be invoked until after the CPU-hotplug
+operation ends, which could also result in deadlock. Furthermore,
+rcu_barrier() blocks CPU-hotplug operations during its execution,
+which results in another type of deadlock when invoked from a CPU-hotplug
+notifier.
+
+Finally, RCU must avoid deadlocks due to interaction between hotplug,
+timers and grace period processing. It does so by maintaining its own set
+of books that duplicate the centrally maintained ``cpu_online_mask``,
+and also by reporting quiescent states explicitly when a CPU goes
+offline. This explicit reporting of quiescent states avoids any need
+for the force-quiescent-state loop (FQS) to report quiescent states for
+offline CPUs. However, as a debugging measure, the FQS loop does splat
+if offline CPUs block an RCU grace period for too long.
+
+An offline CPU's quiescent state will be reported either:
+
+1. As the CPU goes offline using RCU's hotplug notifier (rcutree_report_cpu_dead()).
+2. When grace period initialization (rcu_gp_init()) detects a
+ race either with CPU offlining or with a task unblocking on a leaf
+ ``rcu_node`` structure whose CPUs are all offline.
+
+The CPU-online path (rcutree_report_cpu_starting()) should never need to report
+a quiescent state for an offline CPU. However, as a debugging measure,
+it does emit a warning if a quiescent state was not already reported
+for that CPU.
+
+During the checking/modification of RCU's hotplug bookkeeping, the
+corresponding CPU's leaf node lock is held. This avoids race conditions
+between RCU's hotplug notifier hooks, the grace period initialization
+code, and the FQS loop, all of which refer to or modify this bookkeeping.
+
+Note that grace period initialization (rcu_gp_init()) must carefully sequence
+CPU hotplug scanning with grace period state changes. For example, the
+following race could occur in rcu_gp_init() if rcu_seq_start() were to happen
+after the CPU hotplug scanning::
+
+ CPU0 (rcu_gp_init) CPU1 CPU2
+ --------------------- ---- ----
+ // Hotplug scan first (WRONG ORDER)
+ rcu_for_each_leaf_node(rnp) {
+ rnp->qsmaskinit = rnp->qsmaskinitnext;
+ }
+ rcutree_report_cpu_starting()
+ rnp->qsmaskinitnext |= mask;
+ rcu_read_lock()
+ r0 = *X;
+ r1 = *X;
+ X = NULL;
+ cookie = get_state_synchronize_rcu();
+ // cookie = 8 (future GP)
+ rcu_seq_start(&rcu_state.gp_seq);
+ // gp_seq = 5
+
+ // CPU1 now invisible to this GP!
+ rcu_for_each_node_breadth_first() {
+ rnp->qsmask = rnp->qsmaskinit;
+ // CPU1 not included!
+ }
+
+ // GP completes without CPU1
+ rcu_seq_end(&rcu_state.gp_seq);
+ // gp_seq = 8
+ poll_state_synchronize_rcu(cookie);
+ // Returns true!
+ kfree(r1);
+ r2 = *r0; // USE-AFTER-FREE!
+
+By incrementing ``gp_seq`` first, CPU1's RCU read-side critical section
+is guaranteed to not be missed by CPU2.
+
+Concurrent Quiescent State Reporting for Offline CPUs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+RCU must ensure that CPUs going offline report quiescent states to avoid
+blocking grace periods. This requires careful synchronization to handle
+race conditions
+
+Race condition causing Offline CPU to hang GP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A race between CPU offlining and new GP initialization (gp_init()) may occur
+because rcu_report_qs_rnp() in rcutree_report_cpu_dead() must temporarily
+release the ``rcu_node`` lock to wake the RCU grace-period kthread::
+
+ CPU1 (going offline) CPU0 (GP kthread)
+ -------------------- -----------------
+ rcutree_report_cpu_dead()
+ rcu_report_qs_rnp()
+ // Must release rnp->lock to wake GP kthread
+ raw_spin_unlock_irqrestore_rcu_node()
+ // Wakes up and starts new GP
+ rcu_gp_init()
+ // First loop:
+ copies qsmaskinitnext->qsmaskinit
+ // CPU1 still in qsmaskinitnext!
+
+ // Second loop:
+ rnp->qsmask = rnp->qsmaskinit
+ mask = rnp->qsmask & ~rnp->qsmaskinitnext
+ // mask is 0! CPU1 still in both masks
+ // Reacquire lock (but too late)
+ rnp->qsmaskinitnext &= ~mask // Finally clears bit
+
+Without ``ofl_lock``, the new grace period includes the offline CPU and waits
+forever for its quiescent state causing a GP hang.
+
+A solution with ofl_lock
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``ofl_lock`` (offline lock) prevents rcu_gp_init() from running during
+the vulnerable window when rcu_report_qs_rnp() has released ``rnp->lock``::
+
+ CPU0 (rcu_gp_init) CPU1 (rcutree_report_cpu_dead)
+ ------------------ ------------------------------
+ rcu_for_each_leaf_node(rnp) {
+ arch_spin_lock(&ofl_lock) -----> arch_spin_lock(&ofl_lock) [BLOCKED]
+
+ // Safe: CPU1 can't interfere
+ rnp->qsmaskinit = rnp->qsmaskinitnext
+
+ arch_spin_unlock(&ofl_lock) ---> // Now CPU1 can proceed
+ } // But snapshot already taken
+
+Another race causing GP hangs in rcu_gpu_init(): Reporting QS for Now-offline CPUs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After the first loop takes an atomic snapshot of online CPUs, as shown above,
+the second loop in rcu_gp_init() detects CPUs that went offline between
+releasing ``ofl_lock`` and acquiring the per-node ``rnp->lock``.
+This detection is crucial because:
+
+1. The CPU might have gone offline after the snapshot but before the second loop
+2. The offline CPU cannot report its own QS if it's already dead
+3. Without this detection, the grace period would wait forever for CPUs that
+ are now offline.
+
+The second loop performs this detection safely::
+
+ rcu_for_each_node_breadth_first(rnp) {
+ raw_spin_lock_irqsave_rcu_node(rnp, flags);
+ rnp->qsmask = rnp->qsmaskinit; // Apply the snapshot
+
+ // Detect CPUs offline after snapshot
+ mask = rnp->qsmask & ~rnp->qsmaskinitnext;
+
+ if (mask && rcu_is_leaf_node(rnp))
+ rcu_report_qs_rnp(mask, ...) // Report QS for offline CPUs
+ }
+
+This approach ensures atomicity: quiescent state reporting for offline CPUs
+happens either in rcu_gp_init() (second loop) or in rcutree_report_cpu_dead(),
+never both and never neither. The ``rnp->lock`` held throughout the sequence
+prevents races - rcutree_report_cpu_dead() also acquires this lock when
+clearing ``qsmaskinitnext``, ensuring mutual exclusion.
+
+Scheduler and RCU
+~~~~~~~~~~~~~~~~~
+
+RCU makes use of kthreads, and it is necessary to avoid excessive CPU-time
+accumulation by these kthreads. This requirement was no surprise, but
+RCU's violation of it when running context-switch-heavy workloads when
+built with ``CONFIG_NO_HZ_FULL=y`` `did come as a surprise
+[PDF] <http://www.rdrop.com/users/paulmck/scalability/paper/BareMetal.2015.01.15b.pdf>`__.
+RCU has made good progress towards meeting this requirement, even for
+context-switch-heavy ``CONFIG_NO_HZ_FULL=y`` workloads, but there is
+room for further improvement.
+
+There is no longer any prohibition against holding any of
+scheduler's runqueue or priority-inheritance spinlocks across an
+rcu_read_unlock(), even if interrupts and preemption were enabled
+somewhere within the corresponding RCU read-side critical section.
+Therefore, it is now perfectly legal to execute rcu_read_lock()
+with preemption enabled, acquire one of the scheduler locks, and hold
+that lock across the matching rcu_read_unlock().
+
+Similarly, the RCU flavor consolidation has removed the need for negative
+nesting. The fact that interrupt-disabled regions of code act as RCU
+read-side critical sections implicitly avoids earlier issues that used
+to result in destructive recursion via interrupt handler's use of RCU.
+
+Tracing and RCU
+~~~~~~~~~~~~~~~
+
+It is possible to use tracing on RCU code, but tracing itself uses RCU.
+For this reason, rcu_dereference_raw_check() is provided for use
+by tracing, which avoids the destructive recursion that could otherwise
+ensue. This API is also used by virtualization in some architectures,
+where RCU readers execute in environments in which tracing cannot be
+used. The tracing folks both located the requirement and provided the
+needed fix, so this surprise requirement was relatively painless.
+
+Accesses to User Memory and RCU
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The kernel needs to access user-space memory, for example, to access data
+referenced by system-call parameters. The get_user() macro does this job.
+
+However, user-space memory might well be paged out, which means that
+get_user() might well page-fault and thus block while waiting for the
+resulting I/O to complete. It would be a very bad thing for the compiler to
+reorder a get_user() invocation into an RCU read-side critical section.
+
+For example, suppose that the source code looked like this:
+
+ ::
+
+ 1 rcu_read_lock();
+ 2 p = rcu_dereference(gp);
+ 3 v = p->value;
+ 4 rcu_read_unlock();
+ 5 get_user(user_v, user_p);
+ 6 do_something_with(v, user_v);
+
+The compiler must not be permitted to transform this source code into
+the following:
+
+ ::
+
+ 1 rcu_read_lock();
+ 2 p = rcu_dereference(gp);
+ 3 get_user(user_v, user_p); // BUG: POSSIBLE PAGE FAULT!!!
+ 4 v = p->value;
+ 5 rcu_read_unlock();
+ 6 do_something_with(v, user_v);
+
+If the compiler did make this transformation in a ``CONFIG_PREEMPTION=n`` kernel
+build, and if get_user() did page fault, the result would be a quiescent
+state in the middle of an RCU read-side critical section. This misplaced
+quiescent state could result in line 4 being a use-after-free access,
+which could be bad for your kernel's actuarial statistics. Similar examples
+can be constructed with the call to get_user() preceding the
+rcu_read_lock().
+
+Unfortunately, get_user() doesn't have any particular ordering properties,
+and in some architectures the underlying ``asm`` isn't even marked
+``volatile``. And even if it was marked ``volatile``, the above access to
+``p->value`` is not volatile, so the compiler would not have any reason to keep
+those two accesses in order.
+
+Therefore, the Linux-kernel definitions of rcu_read_lock() and
+rcu_read_unlock() must act as compiler barriers, at least for outermost
+instances of rcu_read_lock() and rcu_read_unlock() within a nested set
+of RCU read-side critical sections.
+
+Energy Efficiency
+~~~~~~~~~~~~~~~~~
+
+Interrupting idle CPUs is considered socially unacceptable, especially
+by people with battery-powered embedded systems. RCU therefore conserves
+energy by detecting which CPUs are idle, including tracking CPUs that
+have been interrupted from idle. This is a large part of the
+energy-efficiency requirement, so I learned of this via an irate phone
+call.
+
+Because RCU avoids interrupting idle CPUs, it is illegal to execute an
+RCU read-side critical section on an idle CPU. (Kernels built with
+``CONFIG_PROVE_RCU=y`` will splat if you try it.)
+
+It is similarly socially unacceptable to interrupt an ``nohz_full`` CPU
+running in userspace. RCU must therefore track ``nohz_full`` userspace
+execution. RCU must therefore be able to sample state at two points in
+time, and be able to determine whether or not some other CPU spent any
+time idle and/or executing in userspace.
+
+These energy-efficiency requirements have proven quite difficult to
+understand and to meet, for example, there have been more than five
+clean-sheet rewrites of RCU's energy-efficiency code, the last of which
+was finally able to demonstrate `real energy savings running on real
+hardware
+[PDF] <http://www.rdrop.com/users/paulmck/realtime/paper/AMPenergy.2013.04.19a.pdf>`__.
+As noted earlier, I learned of many of these requirements via angry
+phone calls: Flaming me on the Linux-kernel mailing list was apparently
+not sufficient to fully vent their ire at RCU's energy-efficiency bugs!
+
+Scheduling-Clock Interrupts and RCU
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The kernel transitions between in-kernel non-idle execution, userspace
+execution, and the idle loop. Depending on kernel configuration, RCU
+handles these states differently:
+
++-----------------+------------------+------------------+-----------------+
+| ``HZ`` Kconfig | In-Kernel | Usermode | Idle |
++=================+==================+==================+=================+
+| ``HZ_PERIODIC`` | Can rely on | Can rely on | Can rely on |
+| | scheduling-clock | scheduling-clock | RCU's |
+| | interrupt. | interrupt and | dyntick-idle |
+| | | its detection | detection. |
+| | | of interrupt | |
+| | | from usermode. | |
++-----------------+------------------+------------------+-----------------+
+| ``NO_HZ_IDLE`` | Can rely on | Can rely on | Can rely on |
+| | scheduling-clock | scheduling-clock | RCU's |
+| | interrupt. | interrupt and | dyntick-idle |
+| | | its detection | detection. |
+| | | of interrupt | |
+| | | from usermode. | |
++-----------------+------------------+------------------+-----------------+
+| ``NO_HZ_FULL`` | Can only | Can rely on | Can rely on |
+| | sometimes rely | RCU's | RCU's |
+| | on | dyntick-idle | dyntick-idle |
+| | scheduling-clock | detection. | detection. |
+| | interrupt. In | | |
+| | other cases, it | | |
+| | is necessary to | | |
+| | bound kernel | | |
+| | execution times | | |
+| | and/or use | | |
+| | IPIs. | | |
++-----------------+------------------+------------------+-----------------+
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| Why can't ``NO_HZ_FULL`` in-kernel execution rely on the |
+| scheduling-clock interrupt, just like ``HZ_PERIODIC`` and |
+| ``NO_HZ_IDLE`` do? |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| Because, as a performance optimization, ``NO_HZ_FULL`` does not |
+| necessarily re-enable the scheduling-clock interrupt on entry to each |
+| and every system call. |
++-----------------------------------------------------------------------+
+
+However, RCU must be reliably informed as to whether any given CPU is
+currently in the idle loop, and, for ``NO_HZ_FULL``, also whether that
+CPU is executing in usermode, as discussed
+`earlier <Energy Efficiency_>`__. It also requires that the
+scheduling-clock interrupt be enabled when RCU needs it to be:
+
+#. If a CPU is either idle or executing in usermode, and RCU believes it
+ is non-idle, the scheduling-clock tick had better be running.
+ Otherwise, you will get RCU CPU stall warnings. Or at best, very long
+ (11-second) grace periods, with a pointless IPI waking the CPU from
+ time to time.
+#. If a CPU is in a portion of the kernel that executes RCU read-side
+ critical sections, and RCU believes this CPU to be idle, you will get
+ random memory corruption. **DON'T DO THIS!!!**
+ This is one reason to test with lockdep, which will complain about
+ this sort of thing.
+#. If a CPU is in a portion of the kernel that is absolutely positively
+ no-joking guaranteed to never execute any RCU read-side critical
+ sections, and RCU believes this CPU to be idle, no problem. This
+ sort of thing is used by some architectures for light-weight
+ exception handlers, which can then avoid the overhead of
+ ct_irq_enter() and ct_irq_exit() at exception entry and
+ exit, respectively. Some go further and avoid the entireties of
+ irq_enter() and irq_exit().
+ Just make very sure you are running some of your tests with
+ ``CONFIG_PROVE_RCU=y``, just in case one of your code paths was in
+ fact joking about not doing RCU read-side critical sections.
+#. If a CPU is executing in the kernel with the scheduling-clock
+ interrupt disabled and RCU believes this CPU to be non-idle, and if
+ the CPU goes idle (from an RCU perspective) every few jiffies, no
+ problem. It is usually OK for there to be the occasional gap between
+ idle periods of up to a second or so.
+ If the gap grows too long, you get RCU CPU stall warnings.
+#. If a CPU is either idle or executing in usermode, and RCU believes it
+ to be idle, of course no problem.
+#. If a CPU is executing in the kernel, the kernel code path is passing
+ through quiescent states at a reasonable frequency (preferably about
+ once per few jiffies, but the occasional excursion to a second or so
+ is usually OK) and the scheduling-clock interrupt is enabled, of
+ course no problem.
+ If the gap between a successive pair of quiescent states grows too
+ long, you get RCU CPU stall warnings.
+
++-----------------------------------------------------------------------+
+| **Quick Quiz**: |
++-----------------------------------------------------------------------+
+| But what if my driver has a hardware interrupt handler that can run |
+| for many seconds? I cannot invoke schedule() from an hardware |
+| interrupt handler, after all! |
++-----------------------------------------------------------------------+
+| **Answer**: |
++-----------------------------------------------------------------------+
+| One approach is to do ``ct_irq_exit();ct_irq_enter();`` every so |
+| often. But given that long-running interrupt handlers can cause other |
+| problems, not least for response time, shouldn't you work to keep |
+| your interrupt handler's runtime within reasonable bounds? |
++-----------------------------------------------------------------------+
+
+But as long as RCU is properly informed of kernel state transitions
+between in-kernel execution, usermode execution, and idle, and as long
+as the scheduling-clock interrupt is enabled when RCU needs it to be,
+you can rest assured that the bugs you encounter will be in some other
+part of RCU or some other part of the kernel!
+
+Memory Efficiency
+~~~~~~~~~~~~~~~~~
+
+Although small-memory non-realtime systems can simply use Tiny RCU, code
+size is only one aspect of memory efficiency. Another aspect is the size
+of the ``rcu_head`` structure used by call_rcu() and
+kfree_rcu(). Although this structure contains nothing more than a
+pair of pointers, it does appear in many RCU-protected data structures,
+including some that are size critical. The ``page`` structure is a case
+in point, as evidenced by the many occurrences of the ``union`` keyword
+within that structure.
+
+This need for memory efficiency is one reason that RCU uses hand-crafted
+singly linked lists to track the ``rcu_head`` structures that are
+waiting for a grace period to elapse. It is also the reason why
+``rcu_head`` structures do not contain debug information, such as fields
+tracking the file and line of the call_rcu() or kfree_rcu() that
+posted them. Although this information might appear in debug-only kernel
+builds at some point, in the meantime, the ``->func`` field will often
+provide the needed debug information.
+
+However, in some cases, the need for memory efficiency leads to even
+more extreme measures. Returning to the ``page`` structure, the
+``rcu_head`` field shares storage with a great many other structures
+that are used at various points in the corresponding page's lifetime. In
+order to correctly resolve certain `race
+conditions <https://lore.kernel.org/r/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com>`__,
+the Linux kernel's memory-management subsystem needs a particular bit to
+remain zero during all phases of grace-period processing, and that bit
+happens to map to the bottom bit of the ``rcu_head`` structure's
+``->next`` field. RCU makes this guarantee as long as call_rcu() is
+used to post the callback, as opposed to kfree_rcu() or some future
+“lazy” variant of call_rcu() that might one day be created for
+energy-efficiency purposes.
+
+That said, there are limits. RCU requires that the ``rcu_head``
+structure be aligned to a two-byte boundary, and passing a misaligned
+``rcu_head`` structure to one of the call_rcu() family of functions
+will result in a splat. It is therefore necessary to exercise caution
+when packing structures containing fields of type ``rcu_head``. Why not
+a four-byte or even eight-byte alignment requirement? Because the m68k
+architecture provides only two-byte alignment, and thus acts as
+alignment's least common denominator.
+
+The reason for reserving the bottom bit of pointers to ``rcu_head``
+structures is to leave the door open to “lazy” callbacks whose
+invocations can safely be deferred. Deferring invocation could
+potentially have energy-efficiency benefits, but only if the rate of
+non-lazy callbacks decreases significantly for some important workload.
+In the meantime, reserving the bottom bit keeps this option open in case
+it one day becomes useful.
+
+Performance, Scalability, Response Time, and Reliability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Expanding on the `earlier
+discussion <Performance and Scalability_>`__, RCU is used heavily by
+hot code paths in performance-critical portions of the Linux kernel's
+networking, security, virtualization, and scheduling code paths. RCU
+must therefore use efficient implementations, especially in its
+read-side primitives. To that end, it would be good if preemptible RCU's
+implementation of rcu_read_lock() could be inlined, however, doing
+this requires resolving ``#include`` issues with the ``task_struct``
+structure.
+
+The Linux kernel supports hardware configurations with up to 4096 CPUs,
+which means that RCU must be extremely scalable. Algorithms that involve
+frequent acquisitions of global locks or frequent atomic operations on
+global variables simply cannot be tolerated within the RCU
+implementation. RCU therefore makes heavy use of a combining tree based
+on the ``rcu_node`` structure. RCU is required to tolerate all CPUs
+continuously invoking any combination of RCU's runtime primitives with
+minimal per-operation overhead. In fact, in many cases, increasing load
+must *decrease* the per-operation overhead, witness the batching
+optimizations for synchronize_rcu(), call_rcu(),
+synchronize_rcu_expedited(), and rcu_barrier(). As a general
+rule, RCU must cheerfully accept whatever the rest of the Linux kernel
+decides to throw at it.
+
+The Linux kernel is used for real-time workloads, especially in
+conjunction with the `-rt
+patchset <https://wiki.linuxfoundation.org/realtime/>`__. The
+real-time-latency response requirements are such that the traditional
+approach of disabling preemption across RCU read-side critical sections
+is inappropriate. Kernels built with ``CONFIG_PREEMPTION=y`` therefore use
+an RCU implementation that allows RCU read-side critical sections to be
+preempted. This requirement made its presence known after users made it
+clear that an earlier `real-time
+patch <https://lwn.net/Articles/107930/>`__ did not meet their needs, in
+conjunction with some `RCU
+issues <https://lore.kernel.org/r/20050318002026.GA2693@us.ibm.com>`__
+encountered by a very early version of the -rt patchset.
+
+In addition, RCU must make do with a sub-100-microsecond real-time
+latency budget. In fact, on smaller systems with the -rt patchset, the
+Linux kernel provides sub-20-microsecond real-time latencies for the
+whole kernel, including RCU. RCU's scalability and latency must
+therefore be sufficient for these sorts of configurations. To my
+surprise, the sub-100-microsecond real-time latency budget `applies to
+even the largest systems
+[PDF] <http://www.rdrop.com/users/paulmck/realtime/paper/bigrt.2013.01.31a.LCA.pdf>`__,
+up to and including systems with 4096 CPUs. This real-time requirement
+motivated the grace-period kthread, which also simplified handling of a
+number of race conditions.
+
+RCU must avoid degrading real-time response for CPU-bound threads,
+whether executing in usermode (which is one use case for
+``CONFIG_NO_HZ_FULL=y``) or in the kernel. That said, CPU-bound loops in
+the kernel must execute cond_resched() at least once per few tens of
+milliseconds in order to avoid receiving an IPI from RCU.
+
+Finally, RCU's status as a synchronization primitive means that any RCU
+failure can result in arbitrary memory corruption that can be extremely
+difficult to debug. This means that RCU must be extremely reliable,
+which in practice also means that RCU must have an aggressive
+stress-test suite. This stress-test suite is called ``rcutorture``.
+
+Although the need for ``rcutorture`` was no surprise, the current
+immense popularity of the Linux kernel is posing interesting—and perhaps
+unprecedented—validation challenges. To see this, keep in mind that
+there are well over one billion instances of the Linux kernel running
+today, given Android smartphones, Linux-powered televisions, and
+servers. This number can be expected to increase sharply with the advent
+of the celebrated Internet of Things.
+
+Suppose that RCU contains a race condition that manifests on average
+once per million years of runtime. This bug will be occurring about
+three times per *day* across the installed base. RCU could simply hide
+behind hardware error rates, given that no one should really expect
+their smartphone to last for a million years. However, anyone taking too
+much comfort from this thought should consider the fact that in most
+jurisdictions, a successful multi-year test of a given mechanism, which
+might include a Linux kernel, suffices for a number of types of
+safety-critical certifications. In fact, rumor has it that the Linux
+kernel is already being used in production for safety-critical
+applications. I don't know about you, but I would feel quite bad if a
+bug in RCU killed someone. Which might explain my recent focus on
+validation and verification.
+
+Other RCU Flavors
+-----------------
+
+One of the more surprising things about RCU is that there are now no
+fewer than five *flavors*, or API families. In addition, the primary
+flavor that has been the sole focus up to this point has two different
+implementations, non-preemptible and preemptible. The other four flavors
+are listed below, with requirements for each described in a separate
+section.
+
+#. `Bottom-Half Flavor (Historical)`_
+#. `Sched Flavor (Historical)`_
+#. `Sleepable RCU`_
+#. `Tasks RCU`_
+#. `Tasks Trace RCU`_
+
+Bottom-Half Flavor (Historical)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The RCU-bh flavor of RCU has since been expressed in terms of the other
+RCU flavors as part of a consolidation of the three flavors into a
+single flavor. The read-side API remains, and continues to disable
+softirq and to be accounted for by lockdep. Much of the material in this
+section is therefore strictly historical in nature.
+
+The softirq-disable (AKA “bottom-half”, hence the “_bh” abbreviations)
+flavor of RCU, or *RCU-bh*, was developed by Dipankar Sarma to provide a
+flavor of RCU that could withstand the network-based denial-of-service
+attacks researched by Robert Olsson. These attacks placed so much
+networking load on the system that some of the CPUs never exited softirq
+execution, which in turn prevented those CPUs from ever executing a
+context switch, which, in the RCU implementation of that time, prevented
+grace periods from ever ending. The result was an out-of-memory
+condition and a system hang.
+
+The solution was the creation of RCU-bh, which does
+local_bh_disable() across its read-side critical sections, and which
+uses the transition from one type of softirq processing to another as a
+quiescent state in addition to context switch, idle, user mode, and
+offline. This means that RCU-bh grace periods can complete even when
+some of the CPUs execute in softirq indefinitely, thus allowing
+algorithms based on RCU-bh to withstand network-based denial-of-service
+attacks.
+
+Because rcu_read_lock_bh() and rcu_read_unlock_bh() disable and
+re-enable softirq handlers, any attempt to start a softirq handlers
+during the RCU-bh read-side critical section will be deferred. In this
+case, rcu_read_unlock_bh() will invoke softirq processing, which can
+take considerable time. One can of course argue that this softirq
+overhead should be associated with the code following the RCU-bh
+read-side critical section rather than rcu_read_unlock_bh(), but the
+fact is that most profiling tools cannot be expected to make this sort
+of fine distinction. For example, suppose that a three-millisecond-long
+RCU-bh read-side critical section executes during a time of heavy
+networking load. There will very likely be an attempt to invoke at least
+one softirq handler during that three milliseconds, but any such
+invocation will be delayed until the time of the
+rcu_read_unlock_bh(). This can of course make it appear at first
+glance as if rcu_read_unlock_bh() was executing very slowly.
+
+The `RCU-bh
+API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
+includes rcu_read_lock_bh(), rcu_read_unlock_bh(), rcu_dereference_bh(),
+rcu_dereference_bh_check(), and rcu_read_lock_bh_held(). However, the
+old RCU-bh update-side APIs are now gone, replaced by synchronize_rcu(),
+synchronize_rcu_expedited(), call_rcu(), and rcu_barrier(). In addition,
+anything that disables bottom halves also marks an RCU-bh read-side
+critical section, including local_bh_disable() and local_bh_enable(),
+local_irq_save() and local_irq_restore(), and so on.
+
+Sched Flavor (Historical)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The RCU-sched flavor of RCU has since been expressed in terms of the
+other RCU flavors as part of a consolidation of the three flavors into a
+single flavor. The read-side API remains, and continues to disable
+preemption and to be accounted for by lockdep. Much of the material in
+this section is therefore strictly historical in nature.
+
+Before preemptible RCU, waiting for an RCU grace period had the side
+effect of also waiting for all pre-existing interrupt and NMI handlers.
+However, there are legitimate preemptible-RCU implementations that do
+not have this property, given that any point in the code outside of an
+RCU read-side critical section can be a quiescent state. Therefore,
+*RCU-sched* was created, which follows “classic” RCU in that an
+RCU-sched grace period waits for pre-existing interrupt and NMI
+handlers. In kernels built with ``CONFIG_PREEMPTION=n``, the RCU and
+RCU-sched APIs have identical implementations, while kernels built with
+``CONFIG_PREEMPTION=y`` provide a separate implementation for each.
+
+Note well that in ``CONFIG_PREEMPTION=y`` kernels,
+rcu_read_lock_sched() and rcu_read_unlock_sched() disable and
+re-enable preemption, respectively. This means that if there was a
+preemption attempt during the RCU-sched read-side critical section,
+rcu_read_unlock_sched() will enter the scheduler, with all the
+latency and overhead entailed. Just as with rcu_read_unlock_bh(),
+this can make it look as if rcu_read_unlock_sched() was executing
+very slowly. However, the highest-priority task won't be preempted, so
+that task will enjoy low-overhead rcu_read_unlock_sched()
+invocations.
+
+The `RCU-sched
+API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
+includes rcu_read_lock_sched(), rcu_read_unlock_sched(),
+rcu_read_lock_sched_notrace(), rcu_read_unlock_sched_notrace(),
+rcu_dereference_sched(), rcu_dereference_sched_check(), and
+rcu_read_lock_sched_held(). However, the old RCU-sched update-side APIs
+are now gone, replaced by synchronize_rcu(), synchronize_rcu_expedited(),
+call_rcu(), and rcu_barrier(). In addition, anything that disables
+preemption also marks an RCU-sched read-side critical section,
+including preempt_disable() and preempt_enable(), local_irq_save()
+and local_irq_restore(), and so on.
+
+Sleepable RCU
+~~~~~~~~~~~~~
+
+For well over a decade, someone saying “I need to block within an RCU
+read-side critical section” was a reliable indication that this someone
+did not understand RCU. After all, if you are always blocking in an RCU
+read-side critical section, you can probably afford to use a
+higher-overhead synchronization mechanism. However, that changed with
+the advent of the Linux kernel's notifiers, whose RCU read-side critical
+sections almost never sleep, but sometimes need to. This resulted in the
+introduction of `sleepable RCU <https://lwn.net/Articles/202847/>`__, or
+*SRCU*.
+
+SRCU allows different domains to be defined, with each such domain
+defined by an instance of an ``srcu_struct`` structure. A pointer to
+this structure must be passed in to each SRCU function, for example,
+``synchronize_srcu(&ss)``, where ``ss`` is the ``srcu_struct``
+structure. The key benefit of these domains is that a slow SRCU reader
+in one domain does not delay an SRCU grace period in some other domain.
+That said, one consequence of these domains is that read-side code must
+pass a “cookie” from srcu_read_lock() to srcu_read_unlock(), for
+example, as follows:
+
+ ::
+
+ 1 int idx;
+ 2
+ 3 idx = srcu_read_lock(&ss);
+ 4 do_something();
+ 5 srcu_read_unlock(&ss, idx);
+
+As noted above, it is legal to block within SRCU read-side critical
+sections, however, with great power comes great responsibility. If you
+block forever in one of a given domain's SRCU read-side critical
+sections, then that domain's grace periods will also be blocked forever.
+Of course, one good way to block forever is to deadlock, which can
+happen if any operation in a given domain's SRCU read-side critical
+section can wait, either directly or indirectly, for that domain's grace
+period to elapse. For example, this results in a self-deadlock:
+
+ ::
+
+ 1 int idx;
+ 2
+ 3 idx = srcu_read_lock(&ss);
+ 4 do_something();
+ 5 synchronize_srcu(&ss);
+ 6 srcu_read_unlock(&ss, idx);
+
+However, if line 5 acquired a mutex that was held across a
+synchronize_srcu() for domain ``ss``, deadlock would still be
+possible. Furthermore, if line 5 acquired a mutex that was held across a
+synchronize_srcu() for some other domain ``ss1``, and if an
+``ss1``-domain SRCU read-side critical section acquired another mutex
+that was held across as ``ss``-domain synchronize_srcu(), deadlock
+would again be possible. Such a deadlock cycle could extend across an
+arbitrarily large number of different SRCU domains. Again, with great
+power comes great responsibility, though lockdep is now able to detect
+this sort of deadlock.
+
+Unlike the other RCU flavors, SRCU read-side critical sections can run on
+idle and even offline CPUs, with the exception of srcu_read_lock_fast()
+and friends. This ability requires that srcu_read_lock() and
+srcu_read_unlock() contain memory barriers, which means that SRCU
+readers will run a bit slower than would RCU readers. It also motivates
+the smp_mb__after_srcu_read_unlock() API, which, in combination with
+srcu_read_unlock(), guarantees a full memory barrier.
+
+Also unlike other RCU flavors, synchronize_srcu() may **not** be
+invoked from CPU-hotplug notifiers, due to the fact that SRCU grace
+periods make use of timers and the possibility of timers being
+temporarily “stranded” on the outgoing CPU. This stranding of timers
+means that timers posted to the outgoing CPU will not fire until late in
+the CPU-hotplug process. The problem is that if a notifier is waiting on
+an SRCU grace period, that grace period is waiting on a timer, and that
+timer is stranded on the outgoing CPU, then the notifier will never be
+awakened, in other words, deadlock has occurred. This same situation of
+course also prohibits srcu_barrier() from being invoked from
+CPU-hotplug notifiers.
+
+SRCU also differs from other RCU flavors in that SRCU's expedited and
+non-expedited grace periods are implemented by the same mechanism. This
+means that in the current SRCU implementation, expediting a future grace
+period has the side effect of expediting all prior grace periods that
+have not yet completed. (But please note that this is a property of the
+current implementation, not necessarily of future implementations.) In
+addition, if SRCU has been idle for longer than the interval specified
+by the ``srcutree.exp_holdoff`` kernel boot parameter (25 microseconds
+by default), and if a synchronize_srcu() invocation ends this idle
+period, that invocation will be automatically expedited.
+
+As of v4.12, SRCU's callbacks are maintained per-CPU, eliminating a
+locking bottleneck present in prior kernel versions. Although this will
+allow users to put much heavier stress on call_srcu(), it is
+important to note that SRCU does not yet take any special steps to deal
+with callback flooding. So if you are posting (say) 10,000 SRCU
+callbacks per second per CPU, you are probably totally OK, but if you
+intend to post (say) 1,000,000 SRCU callbacks per second per CPU, please
+run some tests first. SRCU just might need a few adjustment to deal with
+that sort of load. Of course, your mileage may vary based on the speed
+of your CPUs and the size of your memory.
+
+The `SRCU API
+<https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
+includes srcu_read_lock(), srcu_read_unlock(),
+srcu_dereference(), srcu_dereference_check(), synchronize_srcu(),
+synchronize_srcu_expedited(), call_srcu(), srcu_barrier(),
+and srcu_read_lock_held(). It also includes DEFINE_SRCU(),
+DEFINE_STATIC_SRCU(), DEFINE_SRCU_FAST(), DEFINE_STATIC_SRCU_FAST(),
+init_srcu_struct(), and init_srcu_struct_fast() APIs for defining and
+initializing ``srcu_struct`` structures.
+
+More recently, the SRCU API has added polling interfaces:
+
+#. start_poll_synchronize_srcu() returns a cookie identifying
+ the completion of a future SRCU grace period and ensures
+ that this grace period will be started.
+#. poll_state_synchronize_srcu() returns ``true`` iff the
+ specified cookie corresponds to an already-completed
+ SRCU grace period.
+#. get_state_synchronize_srcu() returns a cookie just like
+ start_poll_synchronize_srcu() does, but differs in that
+ it does nothing to ensure that any future SRCU grace period
+ will be started.
+
+These functions are used to avoid unnecessary SRCU grace periods in
+certain types of buffer-cache algorithms having multi-stage age-out
+mechanisms. The idea is that by the time the block has aged completely
+from the cache, an SRCU grace period will be very likely to have elapsed.
+
+Tasks RCU
+~~~~~~~~~
+
+Some forms of tracing use “trampolines” to handle the binary rewriting
+required to install different types of probes. It would be good to be
+able to free old trampolines, which sounds like a job for some form of
+RCU. However, because it is necessary to be able to install a trace
+anywhere in the code, it is not possible to use read-side markers such
+as rcu_read_lock() and rcu_read_unlock(). In addition, it does
+not work to have these markers in the trampoline itself, because there
+would need to be instructions following rcu_read_unlock(). Although
+synchronize_rcu() would guarantee that execution reached the
+rcu_read_unlock(), it would not be able to guarantee that execution
+had completely left the trampoline. Worse yet, in some situations
+the trampoline's protection must extend a few instructions *prior* to
+execution reaching the trampoline. For example, these few instructions
+might calculate the address of the trampoline, so that entering the
+trampoline would be pre-ordained a surprisingly long time before execution
+actually reached the trampoline itself.
+
+The solution, in the form of `Tasks
+RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side
+critical sections that are delimited by voluntary context switches, that
+is, calls to schedule(), cond_resched(), and
+synchronize_rcu_tasks(). In addition, transitions to and from
+userspace execution also delimit tasks-RCU read-side critical sections.
+Idle tasks are ignored by Tasks RCU, and Tasks Rude RCU may be used to
+interact with them.
+
+Note well that involuntary context switches are *not* Tasks-RCU quiescent
+states. After all, in preemptible kernels, a task executing code in a
+trampoline might be preempted. In this case, the Tasks-RCU grace period
+clearly cannot end until that task resumes and its execution leaves that
+trampoline. This means, among other things, that cond_resched() does
+not provide a Tasks RCU quiescent state. (Instead, use rcu_softirq_qs()
+from softirq or rcu_tasks_classic_qs() otherwise.)
+
+The tasks-RCU API is quite compact, consisting only of
+call_rcu_tasks(), synchronize_rcu_tasks(), and
+rcu_barrier_tasks(). In ``CONFIG_PREEMPTION=n`` kernels, trampolines
+cannot be preempted, so these APIs map to call_rcu(),
+synchronize_rcu(), and rcu_barrier(), respectively. In
+``CONFIG_PREEMPTION=y`` kernels, trampolines can be preempted, and these
+three APIs are therefore implemented by separate functions that check
+for voluntary context switches.
+
+Tasks Rude RCU
+~~~~~~~~~~~~~~
+
+Some forms of tracing need to wait for all preemption-disabled regions
+of code running on any online CPU, including those executed when RCU is
+not watching. This means that synchronize_rcu() is insufficient, and
+Tasks Rude RCU must be used instead. This flavor of RCU does its work by
+forcing a workqueue to be scheduled on each online CPU, hence the "Rude"
+moniker. And this operation is considered to be quite rude by real-time
+workloads that don't want their ``nohz_full`` CPUs receiving IPIs and
+by battery-powered systems that don't want their idle CPUs to be awakened.
+
+Once kernel entry/exit and deep-idle functions have been properly tagged
+``noinstr``, Tasks RCU can start paying attention to idle tasks (except
+those that are idle from RCU's perspective) and then Tasks Rude RCU can
+be removed from the kernel.
+
+The tasks-rude-RCU API is also reader-marking-free and thus quite compact,
+consisting solely of synchronize_rcu_tasks_rude().
+
+Tasks Trace RCU
+~~~~~~~~~~~~~~~
+
+Some forms of tracing need to sleep in readers, but cannot tolerate
+SRCU's read-side overhead, which includes a full memory barrier in both
+srcu_read_lock() and srcu_read_unlock(). This need is handled by a
+Tasks Trace RCU that uses scheduler locking and IPIs to synchronize with
+readers. Real-time systems that cannot tolerate IPIs may build their
+kernels with ``CONFIG_TASKS_TRACE_RCU_READ_MB=y``, which avoids the IPIs at
+the expense of adding full memory barriers to the read-side primitives.
+
+The tasks-trace-RCU API is also reasonably compact,
+consisting of rcu_read_lock_trace(), rcu_read_unlock_trace(),
+rcu_read_lock_trace_held(), call_rcu_tasks_trace(),
+synchronize_rcu_tasks_trace(), and rcu_barrier_tasks_trace().
+
+Possible Future Changes
+-----------------------
+
+One of the tricks that RCU uses to attain update-side scalability is to
+increase grace-period latency with increasing numbers of CPUs. If this
+becomes a serious problem, it will be necessary to rework the
+grace-period state machine so as to avoid the need for the additional
+latency.
+
+RCU disables CPU hotplug in a few places, perhaps most notably in the
+rcu_barrier() operations. If there is a strong reason to use
+rcu_barrier() in CPU-hotplug notifiers, it will be necessary to
+avoid disabling CPU hotplug. This would introduce some complexity, so
+there had better be a *very* good reason.
+
+The tradeoff between grace-period latency on the one hand and
+interruptions of other CPUs on the other hand may need to be
+re-examined. The desire is of course for zero grace-period latency as
+well as zero interprocessor interrupts undertaken during an expedited
+grace period operation. While this ideal is unlikely to be achievable,
+it is quite possible that further improvements can be made.
+
+The multiprocessor implementations of RCU use a combining tree that
+groups CPUs so as to reduce lock contention and increase cache locality.
+However, this combining tree does not spread its memory across NUMA
+nodes nor does it align the CPU groups with hardware features such as
+sockets or cores. Such spreading and alignment is currently believed to
+be unnecessary because the hotpath read-side primitives do not access
+the combining tree, nor does call_rcu() in the common case. If you
+believe that your architecture needs such spreading and alignment, then
+your architecture should also benefit from the
+``rcutree.rcu_fanout_leaf`` boot parameter, which can be set to the
+number of CPUs in a socket, NUMA node, or whatever. If the number of
+CPUs is too large, use a fraction of the number of CPUs. If the number
+of CPUs is a large prime number, well, that certainly is an
+“interesting” architectural choice! More flexible arrangements might be
+considered, but only if ``rcutree.rcu_fanout_leaf`` has proven
+inadequate, and only if the inadequacy has been demonstrated by a
+carefully run and realistic system-level workload.
+
+Please note that arrangements that require RCU to remap CPU numbers will
+require extremely good demonstration of need and full exploration of
+alternatives.
+
+RCU's various kthreads are reasonably recent additions. It is quite
+likely that adjustments will be required to more gracefully handle
+extreme loads. It might also be necessary to be able to relate CPU
+utilization by RCU's kthreads and softirq handlers to the code that
+instigated this CPU utilization. For example, RCU callback overhead
+might be charged back to the originating call_rcu() instance, though
+probably not in production kernels.
+
+Additional work may be required to provide reasonable forward-progress
+guarantees under heavy load for grace periods and for callback
+invocation.
+
+Summary
+-------
+
+This document has presented more than two decade's worth of RCU
+requirements. Given that the requirements keep changing, this will not
+be the last word on this subject, but at least it serves to get an
+important subset of the requirements set forth.
+
+Acknowledgments
+---------------
+
+I am grateful to Steven Rostedt, Lai Jiangshan, Ingo Molnar, Oleg
+Nesterov, Borislav Petkov, Peter Zijlstra, Boqun Feng, and Andy
+Lutomirski for their help in rendering this article human readable, and
+to Michelle Rankin for her support of this effort. Other contributions
+are acknowledged in the Linux kernel's git archive.
diff --git a/Documentation/RCU/NMI-RCU.rst b/Documentation/RCU/NMI-RCU.rst
new file mode 100644
index 000000000000..dff60a80b386
--- /dev/null
+++ b/Documentation/RCU/NMI-RCU.rst
@@ -0,0 +1,123 @@
+.. _NMI_rcu_doc:
+
+Using RCU to Protect Dynamic NMI Handlers
+=========================================
+
+
+Although RCU is usually used to protect read-mostly data structures,
+it is possible to use RCU to provide dynamic non-maskable interrupt
+handlers, as well as dynamic irq handlers. This document describes
+how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer
+work in an old version of "arch/x86/kernel/traps.c".
+
+The relevant pieces of code are listed below, each followed by a
+brief explanation::
+
+ static int dummy_nmi_callback(struct pt_regs *regs, int cpu)
+ {
+ return 0;
+ }
+
+The dummy_nmi_callback() function is a "dummy" NMI handler that does
+nothing, but returns zero, thus saying that it did nothing, allowing
+the NMI handler to take the default machine-specific action::
+
+ static nmi_callback_t nmi_callback = dummy_nmi_callback;
+
+This nmi_callback variable is a global function pointer to the current
+NMI handler::
+
+ void do_nmi(struct pt_regs * regs, long error_code)
+ {
+ int cpu;
+
+ nmi_enter();
+
+ cpu = smp_processor_id();
+ ++nmi_count(cpu);
+
+ if (!rcu_dereference_sched(nmi_callback)(regs, cpu))
+ default_do_nmi(regs);
+
+ nmi_exit();
+ }
+
+The do_nmi() function processes each NMI. It first disables preemption
+in the same way that a hardware irq would, then increments the per-CPU
+count of NMIs. It then invokes the NMI handler stored in the nmi_callback
+function pointer. If this handler returns zero, do_nmi() invokes the
+default_do_nmi() function to handle a machine-specific NMI. Finally,
+preemption is restored.
+
+In theory, rcu_dereference_sched() is not needed, since this code runs
+only on i386, which in theory does not need rcu_dereference_sched()
+anyway. However, in practice it is a good documentation aid, particularly
+for anyone attempting to do something similar on Alpha or on systems
+with aggressive optimizing compilers.
+
+Quick Quiz:
+ Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_NMI>`
+
+Back to the discussion of NMI and RCU::
+
+ void set_nmi_callback(nmi_callback_t callback)
+ {
+ rcu_assign_pointer(nmi_callback, callback);
+ }
+
+The set_nmi_callback() function registers an NMI handler. Note that any
+data that is to be used by the callback must be initialized up -before-
+the call to set_nmi_callback(). On architectures that do not order
+writes, the rcu_assign_pointer() ensures that the NMI handler sees the
+initialized values::
+
+ void unset_nmi_callback(void)
+ {
+ rcu_assign_pointer(nmi_callback, dummy_nmi_callback);
+ }
+
+This function unregisters an NMI handler, restoring the original
+dummy_nmi_handler(). However, there may well be an NMI handler
+currently executing on some other CPU. We therefore cannot free
+up any data structures used by the old NMI handler until execution
+of it completes on all other CPUs.
+
+One way to accomplish this is via synchronize_rcu(), perhaps as
+follows::
+
+ unset_nmi_callback();
+ synchronize_rcu();
+ kfree(my_nmi_data);
+
+This works because (as of v4.20) synchronize_rcu() blocks until all
+CPUs complete any preemption-disabled segments of code that they were
+executing.
+Since NMI handlers disable preemption, synchronize_rcu() is guaranteed
+not to return until all ongoing NMI handlers exit. It is therefore safe
+to free up the handler's data as soon as synchronize_rcu() returns.
+
+Important note: for this to work, the architecture in question must
+invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.
+
+.. _answer_quick_quiz_NMI:
+
+Answer to Quick Quiz:
+ Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
+
+ The caller to set_nmi_callback() might well have
+ initialized some data that is to be used by the new NMI
+ handler. In this case, the rcu_dereference_sched() would
+ be needed, because otherwise a CPU that received an NMI
+ just after the new handler was set might see the pointer
+ to the new NMI handler, but the old pre-initialized
+ version of the handler's data.
+
+ This same sad story can happen on other CPUs when using
+ a compiler with aggressive pointer-value speculation
+ optimizations. (But please don't!)
+
+ More important, the rcu_dereference_sched() makes it
+ clear to someone reading the code that the pointer is
+ being protected by RCU-sched.
diff --git a/Documentation/RCU/NMI-RCU.txt b/Documentation/RCU/NMI-RCU.txt
deleted file mode 100644
index 687777f83b23..000000000000
--- a/Documentation/RCU/NMI-RCU.txt
+++ /dev/null
@@ -1,120 +0,0 @@
-Using RCU to Protect Dynamic NMI Handlers
-
-
-Although RCU is usually used to protect read-mostly data structures,
-it is possible to use RCU to provide dynamic non-maskable interrupt
-handlers, as well as dynamic irq handlers. This document describes
-how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer
-work in "arch/x86/oprofile/nmi_timer_int.c" and in
-"arch/x86/kernel/traps.c".
-
-The relevant pieces of code are listed below, each followed by a
-brief explanation.
-
- static int dummy_nmi_callback(struct pt_regs *regs, int cpu)
- {
- return 0;
- }
-
-The dummy_nmi_callback() function is a "dummy" NMI handler that does
-nothing, but returns zero, thus saying that it did nothing, allowing
-the NMI handler to take the default machine-specific action.
-
- static nmi_callback_t nmi_callback = dummy_nmi_callback;
-
-This nmi_callback variable is a global function pointer to the current
-NMI handler.
-
- void do_nmi(struct pt_regs * regs, long error_code)
- {
- int cpu;
-
- nmi_enter();
-
- cpu = smp_processor_id();
- ++nmi_count(cpu);
-
- if (!rcu_dereference_sched(nmi_callback)(regs, cpu))
- default_do_nmi(regs);
-
- nmi_exit();
- }
-
-The do_nmi() function processes each NMI. It first disables preemption
-in the same way that a hardware irq would, then increments the per-CPU
-count of NMIs. It then invokes the NMI handler stored in the nmi_callback
-function pointer. If this handler returns zero, do_nmi() invokes the
-default_do_nmi() function to handle a machine-specific NMI. Finally,
-preemption is restored.
-
-In theory, rcu_dereference_sched() is not needed, since this code runs
-only on i386, which in theory does not need rcu_dereference_sched()
-anyway. However, in practice it is a good documentation aid, particularly
-for anyone attempting to do something similar on Alpha or on systems
-with aggressive optimizing compilers.
-
-Quick Quiz: Why might the rcu_dereference_sched() be necessary on Alpha,
- given that the code referenced by the pointer is read-only?
-
-
-Back to the discussion of NMI and RCU...
-
- void set_nmi_callback(nmi_callback_t callback)
- {
- rcu_assign_pointer(nmi_callback, callback);
- }
-
-The set_nmi_callback() function registers an NMI handler. Note that any
-data that is to be used by the callback must be initialized up -before-
-the call to set_nmi_callback(). On architectures that do not order
-writes, the rcu_assign_pointer() ensures that the NMI handler sees the
-initialized values.
-
- void unset_nmi_callback(void)
- {
- rcu_assign_pointer(nmi_callback, dummy_nmi_callback);
- }
-
-This function unregisters an NMI handler, restoring the original
-dummy_nmi_handler(). However, there may well be an NMI handler
-currently executing on some other CPU. We therefore cannot free
-up any data structures used by the old NMI handler until execution
-of it completes on all other CPUs.
-
-One way to accomplish this is via synchronize_sched(), perhaps as
-follows:
-
- unset_nmi_callback();
- synchronize_sched();
- kfree(my_nmi_data);
-
-This works because synchronize_sched() blocks until all CPUs complete
-any preemption-disabled segments of code that they were executing.
-Since NMI handlers disable preemption, synchronize_sched() is guaranteed
-not to return until all ongoing NMI handlers exit. It is therefore safe
-to free up the handler's data as soon as synchronize_sched() returns.
-
-Important note: for this to work, the architecture in question must
-invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.
-
-
-Answer to Quick Quiz
-
- Why might the rcu_dereference_sched() be necessary on Alpha, given
- that the code referenced by the pointer is read-only?
-
- Answer: The caller to set_nmi_callback() might well have
- initialized some data that is to be used by the new NMI
- handler. In this case, the rcu_dereference_sched() would
- be needed, because otherwise a CPU that received an NMI
- just after the new handler was set might see the pointer
- to the new NMI handler, but the old pre-initialized
- version of the handler's data.
-
- This same sad story can happen on other CPUs when using
- a compiler with aggressive pointer-value speculation
- optimizations.
-
- More important, the rcu_dereference_sched() makes it
- clear to someone reading the code that the pointer is
- being protected by RCU-sched.
diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt
index f29bcbc463e7..8d4e8de4c460 100644
--- a/Documentation/RCU/RTFP.txt
+++ b/Documentation/RCU/RTFP.txt
@@ -176,13 +176,13 @@ a history of how Linux changed RCU more than RCU changed Linux
which Mathieu Desnoyers is now maintaining [MathieuDesnoyers2009URCU]
[MathieuDesnoyersPhD]. TINY_RCU [PaulEMcKenney2009BloatWatchRCU] made
its appearance, as did expedited RCU [PaulEMcKenney2009expeditedRCU].
-The problem of resizeable RCU-protected hash tables may now be on a path
+The problem of resizable RCU-protected hash tables may now be on a path
to a solution [JoshTriplett2009RPHash]. A few academic researchers are now
using RCU to solve their parallel problems [HariKannan2009DynamicAnalysisRCU].
2010 produced a simpler preemptible-RCU implementation
based on TREE_RCU [PaulEMcKenney2010SimpleOptRCU], lockdep-RCU
-[PaulEMcKenney2010LockdepRCU], another resizeable RCU-protected hash
+[PaulEMcKenney2010LockdepRCU], another resizable RCU-protected hash
table [HerbertXu2010RCUResizeHash] (this one consuming more memory,
but allowing arbitrary changes in hash function, as required for DoS
avoidance in the networking code), realization of the 2009 RCU-protected
@@ -193,7 +193,7 @@ the RCU API [PaulEMcKenney2010RCUAPI].
[LinusTorvalds2011Linux2:6:38:rc1:NPigginVFS], an RCU-protected red-black
tree using software transactional memory to protect concurrent updates
(strange, but true!) [PhilHoward2011RCUTMRBTree], yet another variant of
-RCU-protected resizeable hash tables [Triplett:2011:RPHash], the 3.0 RCU
+RCU-protected resizable hash tables [Triplett:2011:RPHash], the 3.0 RCU
trainwreck [PaulEMcKenney2011RCU3.0trainwreck], and Neil Brown's "Meet the
Lockers" LWN article [NeilBrown2011MeetTheLockers]. Some academic
work looked at debugging uses of RCU [Seyster:2011:RFA:2075416.2075425].
@@ -201,7 +201,7 @@ work looked at debugging uses of RCU [Seyster:2011:RFA:2075416.2075425].
In 2012, Josh Triplett received his Ph.D. with his dissertation
covering RCU-protected resizable hash tables and the relationship
between memory barriers and read-side traversal order: If the updater
-is making changes in the opposite direction from the read-side traveral
+is making changes in the opposite direction from the read-side traversal
order, the updater need only execute a memory-barrier instruction,
but if in the same direction, the updater needs to wait for a grace
period between the individual updates [JoshTriplettPhD]. Also in 2012,
@@ -641,7 +641,7 @@ Orran Krieger and Rusty Russell and Dipankar Sarma and Maneesh Soni"
,Month="July"
,Year="2001"
,note="Available:
-\url{http://www.linuxsymposium.org/2001/abstracts/readcopy.php}
+\url{https://kernel.org/doc/ols/2001/read-copy.pdf}
\url{http://www.rdrop.com/users/paulmck/RCU/rclock_OLS.2001.05.01c.pdf}
[Viewed June 23, 2004]"
,annotation={
@@ -683,7 +683,7 @@ Orran Krieger and Rusty Russell and Dipankar Sarma and Maneesh Soni"
,month="October"
,year="2001"
,note="Available:
-\url{http://lkml.org/lkml/2001/10/13/105}
+\url{https://lore.kernel.org/r/Pine.LNX.4.33.0110131015410.8707-100000@penguin.transmeta.com}
[Viewed August 21, 2004]"
,annotation={
}
@@ -826,7 +826,7 @@ Symposium on Distributed Computing}
,month="October"
,year="2002"
,note="Available:
-\url{https://lkml.org/lkml/2002/10/24/262}
+\url{https://lore.kernel.org/r/3DB86B05.447E7410@us.ibm.com}
[Viewed February 15, 2014]"
,annotation={
Mingming Cao's patch to introduce RCU to SysV IPC.
@@ -839,7 +839,7 @@ Symposium on Distributed Computing}
,month="March"
,year="2003"
,note="Available:
-\url{http://lkml.org/lkml/2003/3/9/205}
+\url{https://lore.kernel.org/r/Pine.LNX.4.44.0303091831560.2129-100000@home.transmeta.com}
[Viewed March 13, 2006]"
,annotation={
Linus suggests replacing brlock with RCU and/or seqlocks:
@@ -847,7 +847,7 @@ Symposium on Distributed Computing}
'It's entirely possible that the current user could be replaced
by RCU and/or seqlocks, and we could get rid of brlocks entirely.'
.
- Steve Hemminger responds by replacing them with RCU.
+ Stephen Hemminger responds by replacing them with RCU.
}
}
@@ -1036,15 +1036,15 @@ Add per-cpu batch counter"
,annotation={
RCU runs reasonably on a 512-CPU SGI using Manfred Spraul's patches,
which may be found at:
- https://lkml.org/lkml/2004/5/20/49 (split vars into cachelines)
- https://lkml.org/lkml/2004/5/22/114 (cpu_quiet() patch)
- https://lkml.org/lkml/2004/5/25/24 (0/5)
- https://lkml.org/lkml/2004/5/25/23 (1/5)
- https://lkml.org/lkml/2004/5/25/265 (works for Jack)
- https://lkml.org/lkml/2004/5/25/20 (2/5)
- https://lkml.org/lkml/2004/5/25/22 (3/5)
- https://lkml.org/lkml/2004/5/25/19 (4/5)
- https://lkml.org/lkml/2004/5/25/21 (5/5)
+ https://lore.kernel.org/r/40AC9823.6020709@colorfullife.com (split vars into cachelines)
+ https://lore.kernel.org/r/Pine.LNX.4.44.0405222141260.11106-100000@dbl.q-ag.de (cpu_quiet() patch)
+ https://lore.kernel.org/r/200405250535.i4P5ZJo8017583@dbl.q-ag.de (0/5)
+ https://lore.kernel.org/r/200405250535.i4P5ZKAQ017591@dbl.q-ag.de (1/5)
+ https://lore.kernel.org/r/20040525203215.GB5127@sgi.com (works for Jack)
+ https://lore.kernel.org/r/200405250535.i4P5ZLiR017599@dbl.q-ag.de (2/5)
+ https://lore.kernel.org/r/200405250535.i4P5ZMFt017607@dbl.q-ag.de (3/5)
+ https://lore.kernel.org/r/200405250535.i4P5ZN6g017615@dbl.q-ag.de (4/5)
+ https://lore.kernel.org/r/200405250535.i4P5ZO7I017623@dbl.q-ag.de (5/5)
}
}
@@ -1106,7 +1106,7 @@ Oregon Health and Sciences University"
,month="August"
,year="2004"
,note="Available:
-\url{http://lkml.org/lkml/2004/8/6/237}
+\url{https://lore.kernel.org/r/20040807192424.GF3936@in.ibm.com}
[Viewed June 8, 2010]"
,annotation={
Introduce rcu_dereference().
@@ -1119,7 +1119,7 @@ Oregon Health and Sciences University"
,month="August"
,year="2004"
,note="Available:
-\url{http://lkml.org/lkml/2004/8/30/87}
+\url{https://lore.kernel.org/r/1093873222.984.12.camel@new.localdomain}
[Viewed February 17, 2005]"
,annotation={
Uses active code in rcu_read_lock() and rcu_read_unlock() to
@@ -1186,7 +1186,7 @@ Oregon Health and Sciences University"
,month="October"
,year="2004"
,note="Available:
-\url{http://lkml.org/lkml/2004/10/23/241}
+\url{https://lore.kernel.org/r/20041023202723.GA1930@us.ibm.com}
[Viewed June 8, 2010]"
,annotation={
Introduce rcu_assign_pointer().
@@ -1203,7 +1203,7 @@ Oregon Health and Sciences University"
,annotation={
James Morris posts Kaigai Kohei's patch to LKML.
[Viewed December 10, 2004]
- Kaigai's patch is at https://lkml.org/lkml/2004/9/27/52
+ Kaigai's patch is at https://lore.kernel.org/r/200409271057.i8RAvcA1007873@mailsv.bs1.fc.nec.co.jp
}
}
@@ -1241,11 +1241,11 @@ Oregon Health and Sciences University"
,year="2005"
,day="17"
,note="Available:
-\url{http://lkml.org/lkml/2005/3/17/199}
+\url{https://lore.kernel.org/r/20050318002026.GA2693@us.ibm.com}
[Viewed September 5, 2005]"
,annotation={
First posting showing how RCU can be safely adapted for
- preemptable RCU read side critical sections.
+ preemptible RCU read side critical sections.
}
}
@@ -1256,7 +1256,7 @@ Oregon Health and Sciences University"
,year="2005"
,day="18"
,note="Available:
-\url{http://lkml.org/lkml/2005/3/18/122}
+\url{https://lore.kernel.org/r/Pine.OSF.4.05.10503181336310.2466-100000@da410.phys.au.dk}
[Viewed March 30, 2006]"
,annotation={
Esben Neilsen suggests read-side suppression of grace-period
@@ -1302,7 +1302,7 @@ Data Structures"
,month="May"
,year="2005"
,note="Available:
-\url{http://lkml.org/lkml/2005/5/9/185}
+\url{https://lore.kernel.org/r/20050510012444.GA3011@us.ibm.com}
[Viewed May 13, 2005]"
,annotation={
First publication of working lock-based deferred free patches
@@ -1385,7 +1385,7 @@ Data Structures"
,day="1"
,year="2005"
,note="Available:
-\url{http://lkml.org/lkml/2005/8/1/155}
+\url{https://lore.kernel.org/r/20050801171137.GA1754@us.ibm.com}
[Viewed March 14, 2006]"
,annotation={
First operating counter-based realtime RCU patch posted to LKML.
@@ -1399,7 +1399,7 @@ Data Structures"
,day="8"
,year="2005"
,note="Available:
-\url{http://lkml.org/lkml/2005/8/8/108}
+\url{https://lore.kernel.org/r/20050808144216.GA1307@us.ibm.com}
[Viewed March 14, 2006]"
,annotation={
First operating counter-based realtime RCU patch posted to LKML,
@@ -1415,7 +1415,7 @@ Data Structures"
,day="1"
,year="2005"
,note="Available:
-\url{http://lkml.org/lkml/2005/10/1/70}
+\url{https://lore.kernel.org/r/20051001182056.GA1613@us.ibm.com}
[Viewed March 14, 2006]"
,annotation={
First rcutorture patch.
@@ -1429,7 +1429,7 @@ Data Structures"
,day="6"
,year="2006"
,note="Available:
-\url{https://lkml.org/lkml/2006/1/7/22}
+\url{https://lore.kernel.org/r/20060106.231054.43576567.davem@davemloft.net}
[Viewed February 29, 2012]"
,annotation={
David Miller's view on hashed arrays of locks: used to really
@@ -1464,7 +1464,7 @@ Distributed Processing Symposium"
,day="20"
,year="2006"
,note="Available:
-\url{http://lkml.org/lkml/2006/6/20/238}
+\url{https://lore.kernel.org/r/20060408134707.22479.33814.sendpatchset@linux.site}
[Viewed March 25, 2008]"
,annotation={
RCU-protected radix tree.
@@ -1480,7 +1480,7 @@ Suparna Bhattacharya"
,Year="2006"
,pages="v2 123-138"
,note="Available:
-\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184}
+\url{https://kernel.org/doc/ols/2006/ols2006v2-pages-131-146.pdf}
\url{http://www.rdrop.com/users/paulmck/RCU/OLSrtRCU.2006.08.11a.pdf}
[Viewed January 1, 2007]"
,annotation={
@@ -1496,7 +1496,7 @@ Canis Rufus and Zoicon5 and Anome and Hal Eisen"
,month="July"
,day="8"
,year="2006"
-,note="\url{http://en.wikipedia.org/wiki/Read-copy-update}"
+,note="\url{https://en.wikipedia.org/wiki/Read-copy-update}"
,annotation={
Wikipedia RCU page as of July 8 2006.
[Viewed August 21, 2006]
@@ -1511,7 +1511,7 @@ Canis Rufus and Zoicon5 and Anome and Hal Eisen"
,Year="2006"
,pages="v2 249-254"
,note="Available:
-\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184}
+\url{https://kernel.org/doc/ols/2006/ols2006v2-pages-249-262.pdf}
[Viewed January 11, 2009]"
,annotation={
Uses RCU-protected radix tree for a lockless page cache.
@@ -1554,7 +1554,7 @@ Revised:
,day="28"
,year="2006"
,note="Available:
-\url{http://lkml.org/lkml/2006/9/28/160}
+\url{https://lore.kernel.org/r/20060928142616.GA20185@infradead.org}
[Viewed March 27, 2008]"
}
@@ -1593,7 +1593,7 @@ Revised:
,year="2006"
,day=26
,note="Available:
-\url{http://lkml.org/lkml/2006/10/26/73}
+\url{https://lore.kernel.org/r/20061026105731.GE11803@in.ibm.com}
[Viewed January 26, 2009]"
,annotation={
RCU-based reader-writer lock that allows readers to proceed with
@@ -1612,12 +1612,12 @@ Revised:
,year="2006"
,day=17
,note="Available:
-\url{http://lkml.org/lkml/2006/11/17/56}
+\url{https://lore.kernel.org/r/20061117092925.GT7164@kernel.dk}
[Viewed May 28, 2007]"
,annotation={
SRCU's grace periods are too slow for Jens, even after a
factor-of-three speedup.
- Sped-up version of SRCU at http://lkml.org/lkml/2006/11/17/359.
+ Sped-up version of SRCU at https://lore.kernel.org/r/20061118002845.GF2632@us.ibm.com.
}
}
@@ -1629,7 +1629,7 @@ Revised:
,year="2006"
,day=19
,note="Available:
-\url{http://lkml.org/lkml/2006/11/19/69}
+\url{https://lore.kernel.org/r/20061119190027.GA3676@oleg}
[Viewed May 28, 2007]"
,annotation={
First cut of QRCU. Expanded/corrected versions followed.
@@ -1644,7 +1644,7 @@ Revised:
,year="2006"
,day=30
,note="Available:
-\url{http://lkml.org/lkml/2006/11/29/330}
+\url{https://lore.kernel.org/r/20061130015714.GC1350@oleg}
[Viewed November 26, 2008]"
,annotation={
Expanded/corrected version of QRCU.
@@ -1709,7 +1709,7 @@ Revised:
,year="2007"
,day=3
,note="Available:
-\url{http://lkml.org/lkml/2007/1/3/112}
+\url{https://lore.kernel.org/r/20070103152738.GA16063@localdomain}
[Viewed May 28, 2007]"
,annotation={
Patch for list_splice_rcu().
@@ -1737,7 +1737,7 @@ Revised:
,year="2007"
,day=28
,note="Available:
-\url{http://lkml.org/lkml/2007/1/28/34}
+\url{https://lore.kernel.org/r/20070128120509.719287000@programming.kicks-ass.net}
[Viewed March 27, 2008]"
,annotation={
RCU-like implementation for frequent updaters and rare readers(!).
@@ -1767,7 +1767,7 @@ Revised:
,year="2007"
,day=24
,note="Available:
-\url{http://lkml.org/lkml/2007/2/25/18}
+\url{https://lore.kernel.org/r/20070225062349.GA17468@linux.vnet.ibm.com}
[Viewed March 27, 2008]"
,annotation={
Patch for QRCU supplying lock-free fast path.
@@ -1846,7 +1846,7 @@ Revised:
,annotation={
LWN article describing Promela and spin, and also using Oleg
Nesterov's QRCU as an example (with Paul McKenney's fastpath).
- Merged patch at: http://lkml.org/lkml/2007/2/25/18
+ Merged patch at: https://lore.kernel.org/r/20070225062349.GA17468@linux.vnet.ibm.com
}
}
@@ -1885,10 +1885,10 @@ Revised:
,day="10"
,year="2007"
,note="Available:
-\url{http://lkml.org/lkml/2007/9/10/213}
+\url{https://lore.kernel.org/r/20070910183004.GA3299@linux.vnet.ibm.com}
[Viewed October 25, 2007]"
,annotation={
- Final patch for preemptable RCU to -rt. (Later patches were
+ Final patch for preemptible RCU to -rt. (Later patches were
to mainline, eventually incorporated.)
}
}
@@ -1933,7 +1933,7 @@ Revised:
,day="20"
,year="2007"
,note="Available:
-\url{http://lkml.org/lkml/2007/12/20/244}
+\url{https://lore.kernel.org/r/20071220142540.GB22523@Krystal}
[Viewed March 27, 2008]"
,annotation={
Request for call_rcu_sched() and rcu_barrier_sched().
@@ -2013,7 +2013,7 @@ Revised:
,day="29"
,year="2008"
,note="Available:
-\url{http://lkml.org/lkml/2008/1/29/208}
+\url{https://lore.kernel.org/r/Pine.LNX.4.58.0801291113350.20371@gandalf.stny.rr.com}
[Viewed March 27, 2008]"
,annotation={
Patch that prevents preemptible RCU from unnecessarily waking
@@ -2028,7 +2028,7 @@ Revised:
,day="1"
,year="2008"
,note="Available:
-\url{http://lkml.org/lkml/2008/2/2/255}
+\url{https://lore.kernel.org/r/20080202214124.GA28612@linux.vnet.ibm.com}
[Viewed October 18, 2008]"
,annotation={
Explanation of compilers violating dependency ordering.
@@ -2088,7 +2088,7 @@ lot of {Linux} into your technology!!!"
,day="3"
,year="2008"
,note="Available:
-\url{http://lkml.org/lkml/2008/6/2/539}
+\url{https://lore.kernel.org/r/4844BE83.5010401@cn.fujitsu.com}
[Viewed December 10, 2008]"
,annotation={
Updated RCU classic algorithm. Introduced multi-tailed list
@@ -2122,7 +2122,7 @@ lot of {Linux} into your technology!!!"
,day="21"
,year="2008"
,note="Available:
-\url{http://lkml.org/lkml/2008/8/21/336}
+\url{https://lore.kernel.org/r/48AD8969.7060900@colorfullife.com}
[Viewed December 8, 2008]"
,annotation={
State-based RCU. One key thing that this patch does is to
@@ -2137,7 +2137,7 @@ lot of {Linux} into your technology!!!"
,day="6"
,year="2008"
,note="Available:
-\url{http://lkml.org/lkml/2008/9/6/86}
+\url{https://lore.kernel.org/r/48C2B1D2.5070801@colorfullife.com}
[Viewed December 8, 2008]"
,annotation={
Manfred notes a fix required to my attempt to separate irq
@@ -2183,7 +2183,7 @@ lot of {Linux} into your technology!!!"
,day="14"
,year="2009"
,note="Available:
-\url{http://lkml.org/lkml/2009/1/14/449}
+\url{https://lore.kernel.org/r/20090114202044.GJ6734@linux.vnet.ibm.com}
[Viewed January 15, 2009]"
,annotation={
Small-footprint implementation of RCU for uniprocessor
@@ -2218,7 +2218,7 @@ lot of {Linux} into your technology!!!"
git://lttng.org/userspace-rcu.git
http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git
http://lttng.org/urcu
- http://lkml.org/lkml/2009/2/5/572
+ https://lore.kernel.org/r/20090206030543.GB8560@Krystal
}
}
@@ -2258,7 +2258,7 @@ lot of {Linux} into your technology!!!"
,day="25"
,year="2009"
,note="Available:
-\url{http://lkml.org/lkml/2009/6/25/306}
+\url{https://lore.kernel.org/r/20090625160706.GA9467@linux.vnet.ibm.com}
[Viewed August 16, 2009]"
,annotation={
First posting of expedited RCU to be accepted into -tip.
@@ -2272,10 +2272,10 @@ lot of {Linux} into your technology!!!"
,day="23"
,year="2009"
,note="Available:
-\url{http://lkml.org/lkml/2009/7/23/294}
+\url{https://lore.kernel.org/r/20090724001429.GA17374@linux.vnet.ibm.com}
[Viewed August 15, 2009]"
,annotation={
- First posting of simple and fast preemptable RCU.
+ First posting of simple and fast preemptible RCU.
}
}
@@ -2350,7 +2350,7 @@ lot of {Linux} into your technology!!!"
,month="December"
,year="2009"
,note="Available:
-\url{http://lkml.org/lkml/2009/10/18/129}
+\url{https://lore.kernel.org/r/20091018232918.GA7385@Krystal}
[Viewed December 29, 2009]"
,annotation={
Mathieu proposed defer_rcu() with fixed-size per-thread pool
@@ -2518,7 +2518,7 @@ lot of {Linux} into your technology!!!"
,month="January"
,year="2011"
,note="Available:
-\url{https://lkml.org/lkml/2011/1/18/322}
+\url{https://lore.kernel.org/r/AANLkTimajU0x1v6y3rH2+jr-bZ=tNLs1S_agXdGGAa3S@mail.gmail.com}
[Viewed March 4, 2011]"
,annotation={
"The RCU-based name lookup is at the other end of the spectrum - the
@@ -2639,7 +2639,7 @@ lot of {Linux} into your technology!!!"
RCU-protected hash tables, barriers vs. read-side traversal order.
.
If the updater is making changes in the opposite direction from
- the read-side traveral order, the updater need only execute a
+ the read-side traversal order, the updater need only execute a
memory-barrier instruction, but if in the same direction, the
updater needs to wait for a grace period between the individual
updates.
diff --git a/Documentation/RCU/UP.rst b/Documentation/RCU/UP.rst
new file mode 100644
index 000000000000..4060d7a2f62a
--- /dev/null
+++ b/Documentation/RCU/UP.rst
@@ -0,0 +1,152 @@
+.. _up_doc:
+
+RCU on Uniprocessor Systems
+===========================
+
+A common misconception is that, on UP systems, the call_rcu() primitive
+may immediately invoke its function. The basis of this misconception
+is that since there is only one CPU, it should not be necessary to
+wait for anything else to get done, since there are no other CPUs for
+anything else to be happening on. Although this approach will *sort of*
+work a surprising amount of the time, it is a very bad idea in general.
+This document presents three examples that demonstrate exactly how bad
+an idea this is.
+
+Example 1: softirq Suicide
+--------------------------
+
+Suppose that an RCU-based algorithm scans a linked list containing
+elements A, B, and C in process context, and can delete elements from
+this same list in softirq context. Suppose that the process-context scan
+is referencing element B when it is interrupted by softirq processing,
+which deletes element B, and then invokes call_rcu() to free element B
+after a grace period.
+
+Now, if call_rcu() were to directly invoke its arguments, then upon return
+from softirq, the list scan would find itself referencing a newly freed
+element B. This situation can greatly decrease the life expectancy of
+your kernel.
+
+This same problem can occur if call_rcu() is invoked from a hardware
+interrupt handler.
+
+Example 2: Function-Call Fatality
+---------------------------------
+
+Of course, one could avert the suicide described in the preceding example
+by having call_rcu() directly invoke its arguments only if it was called
+from process context. However, this can fail in a similar manner.
+
+Suppose that an RCU-based algorithm again scans a linked list containing
+elements A, B, and C in process context, but that it invokes a function
+on each element as it is scanned. Suppose further that this function
+deletes element B from the list, then passes it to call_rcu() for deferred
+freeing. This may be a bit unconventional, but it is perfectly legal
+RCU usage, since call_rcu() must wait for a grace period to elapse.
+Therefore, in this case, allowing call_rcu() to immediately invoke
+its arguments would cause it to fail to make the fundamental guarantee
+underlying RCU, namely that call_rcu() defers invoking its arguments until
+all RCU read-side critical sections currently executing have completed.
+
+Quick Quiz #1:
+ Why is it *not* legal to invoke synchronize_rcu() in this case?
+
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
+
+Example 3: Death by Deadlock
+----------------------------
+
+Suppose that call_rcu() is invoked while holding a lock, and that the
+callback function must acquire this same lock. In this case, if
+call_rcu() were to directly invoke the callback, the result would
+be self-deadlock *even if* this invocation occurred from a later
+call_rcu() invocation a full grace period later.
+
+In some cases, it would possible to restructure to code so that
+the call_rcu() is delayed until after the lock is released. However,
+there are cases where this can be quite ugly:
+
+1. If a number of items need to be passed to call_rcu() within
+ the same critical section, then the code would need to create
+ a list of them, then traverse the list once the lock was
+ released.
+
+2. In some cases, the lock will be held across some kernel API,
+ so that delaying the call_rcu() until the lock is released
+ requires that the data item be passed up via a common API.
+ It is far better to guarantee that callbacks are invoked
+ with no locks held than to have to modify such APIs to allow
+ arbitrary data items to be passed back up through them.
+
+If call_rcu() directly invokes the callback, painful locking restrictions
+or API changes would be required.
+
+Quick Quiz #2:
+ What locking restriction must RCU callbacks respect?
+
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
+
+It is important to note that userspace RCU implementations *do*
+permit call_rcu() to directly invoke callbacks, but only if a full
+grace period has elapsed since those callbacks were queued. This is
+the case because some userspace environments are extremely constrained.
+Nevertheless, people writing userspace RCU implementations are strongly
+encouraged to avoid invoking callbacks from call_rcu(), thus obtaining
+the deadlock-avoidance benefits called out above.
+
+Summary
+-------
+
+Permitting call_rcu() to immediately invoke its arguments breaks RCU,
+even on a UP system. So do not do it! Even on a UP system, the RCU
+infrastructure *must* respect grace periods, and *must* invoke callbacks
+from a known environment in which no locks are held.
+
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
+
+Quick Quiz #3:
+ Why can't synchronize_rcu() return immediately on UP systems running
+ preemptible RCU?
+
+.. _answer_quick_quiz_up:
+
+Answer to Quick Quiz #1:
+ Why is it *not* legal to invoke synchronize_rcu() in this case?
+
+ Because the calling function is scanning an RCU-protected linked
+ list, and is therefore within an RCU read-side critical section.
+ Therefore, the called function has been invoked within an RCU
+ read-side critical section, and is not permitted to block.
+
+Answer to Quick Quiz #2:
+ What locking restriction must RCU callbacks respect?
+
+ Any lock that is acquired within an RCU callback must be acquired
+ elsewhere using an _bh variant of the spinlock primitive.
+ For example, if "mylock" is acquired by an RCU callback, then
+ a process-context acquisition of this lock must use something
+ like spin_lock_bh() to acquire the lock. Please note that
+ it is also OK to use _irq variants of spinlocks, for example,
+ spin_lock_irqsave().
+
+ If the process-context code were to simply use spin_lock(),
+ then, since RCU callbacks can be invoked from softirq context,
+ the callback might be called from a softirq that interrupted
+ the process-context critical section. This would result in
+ self-deadlock.
+
+ This restriction might seem gratuitous, since very few RCU
+ callbacks acquire locks directly. However, a great many RCU
+ callbacks do acquire locks *indirectly*, for example, via
+ the kfree() primitive.
+
+Answer to Quick Quiz #3:
+ Why can't synchronize_rcu() return immediately on UP systems
+ running preemptible RCU?
+
+ Because some other task might have been preempted in the middle
+ of an RCU read-side critical section. If synchronize_rcu()
+ simply immediately returned, it would prematurely signal the
+ end of the grace period, which would come as a nasty shock to
+ that other thread when it started running again.
diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
deleted file mode 100644
index 90ec5341ee98..000000000000
--- a/Documentation/RCU/UP.txt
+++ /dev/null
@@ -1,135 +0,0 @@
-RCU on Uniprocessor Systems
-
-
-A common misconception is that, on UP systems, the call_rcu() primitive
-may immediately invoke its function. The basis of this misconception
-is that since there is only one CPU, it should not be necessary to
-wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on. Although this approach will -sort- -of-
-work a surprising amount of the time, it is a very bad idea in general.
-This document presents three examples that demonstrate exactly how bad
-an idea this is.
-
-
-Example 1: softirq Suicide
-
-Suppose that an RCU-based algorithm scans a linked list containing
-elements A, B, and C in process context, and can delete elements from
-this same list in softirq context. Suppose that the process-context scan
-is referencing element B when it is interrupted by softirq processing,
-which deletes element B, and then invokes call_rcu() to free element B
-after a grace period.
-
-Now, if call_rcu() were to directly invoke its arguments, then upon return
-from softirq, the list scan would find itself referencing a newly freed
-element B. This situation can greatly decrease the life expectancy of
-your kernel.
-
-This same problem can occur if call_rcu() is invoked from a hardware
-interrupt handler.
-
-
-Example 2: Function-Call Fatality
-
-Of course, one could avert the suicide described in the preceding example
-by having call_rcu() directly invoke its arguments only if it was called
-from process context. However, this can fail in a similar manner.
-
-Suppose that an RCU-based algorithm again scans a linked list containing
-elements A, B, and C in process contexts, but that it invokes a function
-on each element as it is scanned. Suppose further that this function
-deletes element B from the list, then passes it to call_rcu() for deferred
-freeing. This may be a bit unconventional, but it is perfectly legal
-RCU usage, since call_rcu() must wait for a grace period to elapse.
-Therefore, in this case, allowing call_rcu() to immediately invoke
-its arguments would cause it to fail to make the fundamental guarantee
-underlying RCU, namely that call_rcu() defers invoking its arguments until
-all RCU read-side critical sections currently executing have completed.
-
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
- this case?
-
-
-Example 3: Death by Deadlock
-
-Suppose that call_rcu() is invoked while holding a lock, and that the
-callback function must acquire this same lock. In this case, if
-call_rcu() were to directly invoke the callback, the result would
-be self-deadlock.
-
-In some cases, it would possible to restructure to code so that
-the call_rcu() is delayed until after the lock is released. However,
-there are cases where this can be quite ugly:
-
-1. If a number of items need to be passed to call_rcu() within
- the same critical section, then the code would need to create
- a list of them, then traverse the list once the lock was
- released.
-
-2. In some cases, the lock will be held across some kernel API,
- so that delaying the call_rcu() until the lock is released
- requires that the data item be passed up via a common API.
- It is far better to guarantee that callbacks are invoked
- with no locks held than to have to modify such APIs to allow
- arbitrary data items to be passed back up through them.
-
-If call_rcu() directly invokes the callback, painful locking restrictions
-or API changes would be required.
-
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
-
-
-Summary
-
-Permitting call_rcu() to immediately invoke its arguments breaks RCU,
-even on a UP system. So do not do it! Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
-from a known environment in which no locks are held.
-
-It -is- safe for synchronize_sched() and synchronize_rcu_bh() to return
-immediately on an UP system. It is also safe for synchronize_rcu()
-to return immediately on UP systems, except when running preemptable
-RCU.
-
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
- UP systems running preemptable RCU?
-
-
-Answer to Quick Quiz #1:
- Why is it -not- legal to invoke synchronize_rcu() in this case?
-
- Because the calling function is scanning an RCU-protected linked
- list, and is therefore within an RCU read-side critical section.
- Therefore, the called function has been invoked within an RCU
- read-side critical section, and is not permitted to block.
-
-Answer to Quick Quiz #2:
- What locking restriction must RCU callbacks respect?
-
- Any lock that is acquired within an RCU callback must be
- acquired elsewhere using an _irq variant of the spinlock
- primitive. For example, if "mylock" is acquired by an
- RCU callback, then a process-context acquisition of this
- lock must use something like spin_lock_irqsave() to
- acquire the lock.
-
- If the process-context code were to simply use spin_lock(),
- then, since RCU callbacks can be invoked from softirq context,
- the callback might be called from a softirq that interrupted
- the process-context critical section. This would result in
- self-deadlock.
-
- This restriction might seem gratuitous, since very few RCU
- callbacks acquire locks directly. However, a great many RCU
- callbacks do acquire locks -indirectly-, for example, via
- the kfree() primitive.
-
-Answer to Quick Quiz #3:
- Why can't synchronize_rcu() return immediately on UP systems
- running preemptable RCU?
-
- Because some other task might have been preempted in the middle
- of an RCU read-side critical section. If synchronize_rcu()
- simply immediately returned, it would prematurely signal the
- end of the grace period, which would come as a nasty shock to
- that other thread when it started running again.
diff --git a/Documentation/RCU/arrayRCU.txt b/Documentation/RCU/arrayRCU.txt
deleted file mode 100644
index 453ebe6953ee..000000000000
--- a/Documentation/RCU/arrayRCU.txt
+++ /dev/null
@@ -1,141 +0,0 @@
-Using RCU to Protect Read-Mostly Arrays
-
-
-Although RCU is more commonly used to protect linked lists, it can
-also be used to protect arrays. Three situations are as follows:
-
-1. Hash Tables
-
-2. Static Arrays
-
-3. Resizeable Arrays
-
-Each of these situations are discussed below.
-
-
-Situation 1: Hash Tables
-
-Hash tables are often implemented as an array, where each array entry
-has a linked-list hash chain. Each hash chain can be protected by RCU
-as described in the listRCU.txt document. This approach also applies
-to other array-of-list situations, such as radix trees.
-
-
-Situation 2: Static Arrays
-
-Static arrays, where the data (rather than a pointer to the data) is
-located in each array element, and where the array is never resized,
-have not been used with RCU. Rik van Riel recommends using seqlock in
-this situation, which would also have minimal read-side overhead as long
-as updates are rare.
-
-Quick Quiz: Why is it so important that updates be rare when
- using seqlock?
-
-
-Situation 3: Resizeable Arrays
-
-Use of RCU for resizeable arrays is demonstrated by the grow_ary()
-function used by the System V IPC code. The array is used to map from
-semaphore, message-queue, and shared-memory IDs to the data structure
-that represents the corresponding IPC construct. The grow_ary()
-function does not acquire any locks; instead its caller must hold the
-ids->sem semaphore.
-
-The grow_ary() function, shown below, does some limit checks, allocates a
-new ipc_id_ary, copies the old to the new portion of the new, initializes
-the remainder of the new, updates the ids->entries pointer to point to
-the new array, and invokes ipc_rcu_putref() to free up the old array.
-Note that rcu_assign_pointer() is used to update the ids->entries pointer,
-which includes any memory barriers required on whatever architecture
-you are running on.
-
- static int grow_ary(struct ipc_ids* ids, int newsize)
- {
- struct ipc_id_ary* new;
- struct ipc_id_ary* old;
- int i;
- int size = ids->entries->size;
-
- if(newsize > IPCMNI)
- newsize = IPCMNI;
- if(newsize <= size)
- return newsize;
-
- new = ipc_rcu_alloc(sizeof(struct kern_ipc_perm *)*newsize +
- sizeof(struct ipc_id_ary));
- if(new == NULL)
- return size;
- new->size = newsize;
- memcpy(new->p, ids->entries->p,
- sizeof(struct kern_ipc_perm *)*size +
- sizeof(struct ipc_id_ary));
- for(i=size;i<newsize;i++) {
- new->p[i] = NULL;
- }
- old = ids->entries;
-
- /*
- * Use rcu_assign_pointer() to make sure the memcpyed
- * contents of the new array are visible before the new
- * array becomes visible.
- */
- rcu_assign_pointer(ids->entries, new);
-
- ipc_rcu_putref(old);
- return newsize;
- }
-
-The ipc_rcu_putref() function decrements the array's reference count
-and then, if the reference count has dropped to zero, uses call_rcu()
-to free the array after a grace period has elapsed.
-
-The array is traversed by the ipc_lock() function. This function
-indexes into the array under the protection of rcu_read_lock(),
-using rcu_dereference() to pick up the pointer to the array so
-that it may later safely be dereferenced -- memory barriers are
-required on the Alpha CPU. Since the size of the array is stored
-with the array itself, there can be no array-size mismatches, so
-a simple check suffices. The pointer to the structure corresponding
-to the desired IPC object is placed in "out", with NULL indicating
-a non-existent entry. After acquiring "out->lock", the "out->deleted"
-flag indicates whether the IPC object is in the process of being
-deleted, and, if not, the pointer is returned.
-
- struct kern_ipc_perm* ipc_lock(struct ipc_ids* ids, int id)
- {
- struct kern_ipc_perm* out;
- int lid = id % SEQ_MULTIPLIER;
- struct ipc_id_ary* entries;
-
- rcu_read_lock();
- entries = rcu_dereference(ids->entries);
- if(lid >= entries->size) {
- rcu_read_unlock();
- return NULL;
- }
- out = entries->p[lid];
- if(out == NULL) {
- rcu_read_unlock();
- return NULL;
- }
- spin_lock(&out->lock);
-
- /* ipc_rmid() may have already freed the ID while ipc_lock
- * was spinning: here verify that the structure is still valid
- */
- if (out->deleted) {
- spin_unlock(&out->lock);
- rcu_read_unlock();
- return NULL;
- }
- return out;
- }
-
-
-Answer to Quick Quiz:
-
- The reason that it is important that updates be rare when
- using seqlock is that frequent updates can livelock readers.
- One way to avoid this problem is to assign a seqlock for
- each array entry rather than to the entire array.
diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
new file mode 100644
index 000000000000..4b30f701225f
--- /dev/null
+++ b/Documentation/RCU/checklist.rst
@@ -0,0 +1,556 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Review Checklist for RCU Patches
+================================
+
+
+This document contains a checklist for producing and reviewing patches
+that make use of RCU. Violating any of the rules listed below will
+result in the same sorts of problems that leaving out a locking primitive
+would cause. This list is based on experiences reviewing such patches
+over a rather long period of time, but improvements are always welcome!
+
+0. Is RCU being applied to a read-mostly situation? If the data
+ structure is updated more than about 10% of the time, then you
+ should strongly consider some other approach, unless detailed
+ performance measurements show that RCU is nonetheless the right
+ tool for the job. Yes, RCU does reduce read-side overhead by
+ increasing write-side overhead, which is exactly why normal uses
+ of RCU will do much more reading than updating.
+
+ Another exception is where performance is not an issue, and RCU
+ provides a simpler implementation. An example of this situation
+ is the dynamic NMI code in the Linux 2.6 kernel, at least on
+ architectures where NMIs are rare.
+
+ Yet another exception is where the low real-time latency of RCU's
+ read-side primitives is critically important.
+
+ One final exception is where RCU readers are used to prevent
+ the ABA problem (https://en.wikipedia.org/wiki/ABA_problem)
+ for lockless updates. This does result in the mildly
+ counter-intuitive situation where rcu_read_lock() and
+ rcu_read_unlock() are used to protect updates, however, this
+ approach can provide the same simplifications to certain types
+ of lockless algorithms that garbage collectors do.
+
+1. Does the update code have proper mutual exclusion?
+
+ RCU does allow *readers* to run (almost) naked, but *writers* must
+ still use some sort of mutual exclusion, such as:
+
+ a. locking,
+ b. atomic operations, or
+ c. restricting updates to a single task.
+
+ If you choose #b, be prepared to describe how you have handled
+ memory barriers on weakly ordered machines (pretty much all of
+ them -- even x86 allows later loads to be reordered to precede
+ earlier stores), and be prepared to explain why this added
+ complexity is worthwhile. If you choose #c, be prepared to
+ explain how this single task does not become a major bottleneck
+ on large systems (for example, if the task is updating information
+ relating to itself that other tasks can read, there by definition
+ can be no bottleneck). Note that the definition of "large" has
+ changed significantly: Eight CPUs was "large" in the year 2000,
+ but a hundred CPUs was unremarkable in 2017.
+
+2. Do the RCU read-side critical sections make proper use of
+ rcu_read_lock() and friends? These primitives are needed
+ to prevent grace periods from ending prematurely, which
+ could result in data being unceremoniously freed out from
+ under your read-side code, which can greatly increase the
+ actuarial risk of your kernel.
+
+ As a rough rule of thumb, any dereference of an RCU-protected
+ pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(),
+ rcu_read_lock_sched(), or by the appropriate update-side lock.
+ Explicit disabling of preemption (preempt_disable(), for example)
+ can serve as rcu_read_lock_sched(), but is less readable and
+ prevents lockdep from detecting locking issues. Acquiring a
+ raw spinlock also enters an RCU read-side critical section.
+
+ The guard(rcu)() and scoped_guard(rcu) primitives designate
+ the remainder of the current scope or the next statement,
+ respectively, as the RCU read-side critical section. Use of
+ these guards can be less error-prone than rcu_read_lock(),
+ rcu_read_unlock(), and friends.
+
+ Please note that you *cannot* rely on code known to be built
+ only in non-preemptible kernels. Such code can and will break,
+ especially in kernels built with CONFIG_PREEMPT_COUNT=y.
+
+ Letting RCU-protected pointers "leak" out of an RCU read-side
+ critical section is every bit as bad as letting them leak out
+ from under a lock. Unless, of course, you have arranged some
+ other means of protection, such as a lock or a reference count
+ *before* letting them out of the RCU read-side critical section.
+
+3. Does the update code tolerate concurrent accesses?
+
+ The whole point of RCU is to permit readers to run without
+ any locks or atomic operations. This means that readers will
+ be running while updates are in progress. There are a number
+ of ways to handle this concurrency, depending on the situation:
+
+ a. Use the RCU variants of the list and hlist update
+ primitives to add, remove, and replace elements on
+ an RCU-protected list. Alternatively, use the other
+ RCU-protected data structures that have been added to
+ the Linux kernel.
+
+ This is almost always the best approach.
+
+ b. Proceed as in (a) above, but also maintain per-element
+ locks (that are acquired by both readers and writers)
+ that guard per-element state. Fields that the readers
+ refrain from accessing can be guarded by some other lock
+ acquired only by updaters, if desired.
+
+ This also works quite well.
+
+ c. Make updates appear atomic to readers. For example,
+ pointer updates to properly aligned fields will
+ appear atomic, as will individual atomic primitives.
+ Sequences of operations performed under a lock will *not*
+ appear to be atomic to RCU readers, nor will sequences
+ of multiple atomic primitives. One alternative is to
+ move multiple individual fields to a separate structure,
+ thus solving the multiple-field problem by imposing an
+ additional level of indirection.
+
+ This can work, but is starting to get a bit tricky.
+
+ d. Carefully order the updates and the reads so that readers
+ see valid data at all phases of the update. This is often
+ more difficult than it sounds, especially given modern
+ CPUs' tendency to reorder memory references. One must
+ usually liberally sprinkle memory-ordering operations
+ through the code, making it difficult to understand and
+ to test. Where it works, it is better to use things
+ like smp_store_release() and smp_load_acquire(), but in
+ some cases the smp_mb() full memory barrier is required.
+
+ As noted earlier, it is usually better to group the
+ changing data into a separate structure, so that the
+ change may be made to appear atomic by updating a pointer
+ to reference a new structure containing updated values.
+
+4. Weakly ordered CPUs pose special challenges. Almost all CPUs
+ are weakly ordered -- even x86 CPUs allow later loads to be
+ reordered to precede earlier stores. RCU code must take all of
+ the following measures to prevent memory-corruption problems:
+
+ a. Readers must maintain proper ordering of their memory
+ accesses. The rcu_dereference() primitive ensures that
+ the CPU picks up the pointer before it picks up the data
+ that the pointer points to. This really is necessary
+ on Alpha CPUs.
+
+ The rcu_dereference() primitive is also an excellent
+ documentation aid, letting the person reading the
+ code know exactly which pointers are protected by RCU.
+ Please note that compilers can also reorder code, and
+ they are becoming increasingly aggressive about doing
+ just that. The rcu_dereference() primitive therefore also
+ prevents destructive compiler optimizations. However,
+ with a bit of devious creativity, it is possible to
+ mishandle the return value from rcu_dereference().
+ Please see rcu_dereference.rst for more information.
+
+ The rcu_dereference() primitive is used by the
+ various "_rcu()" list-traversal primitives, such
+ as the list_for_each_entry_rcu(). Note that it is
+ perfectly legal (if redundant) for update-side code to
+ use rcu_dereference() and the "_rcu()" list-traversal
+ primitives. This is particularly useful in code that
+ is common to readers and updaters. However, lockdep
+ will complain if you access rcu_dereference() outside
+ of an RCU read-side critical section. See lockdep.rst
+ to learn what to do about this.
+
+ Of course, neither rcu_dereference() nor the "_rcu()"
+ list-traversal primitives can substitute for a good
+ concurrency design coordinating among multiple updaters.
+
+ b. If the list macros are being used, the list_add_tail_rcu()
+ and list_add_rcu() primitives must be used in order
+ to prevent weakly ordered machines from misordering
+ structure initialization and pointer planting.
+ Similarly, if the hlist macros are being used, the
+ hlist_add_head_rcu() primitive is required.
+
+ c. If the list macros are being used, the list_del_rcu()
+ primitive must be used to keep list_del()'s pointer
+ poisoning from inflicting toxic effects on concurrent
+ readers. Similarly, if the hlist macros are being used,
+ the hlist_del_rcu() primitive is required.
+
+ The list_replace_rcu() and hlist_replace_rcu() primitives
+ may be used to replace an old structure with a new one
+ in their respective types of RCU-protected lists.
+
+ d. Rules similar to (4b) and (4c) apply to the "hlist_nulls"
+ type of RCU-protected linked lists.
+
+ e. Updates must ensure that initialization of a given
+ structure happens before pointers to that structure are
+ publicized. Use the rcu_assign_pointer() primitive
+ when publicizing a pointer to a structure that can
+ be traversed by an RCU read-side critical section.
+
+5. If any of call_rcu(), call_srcu(), call_rcu_tasks(), or
+ call_rcu_tasks_trace() is used, the callback function may be
+ invoked from softirq context, and in any case with bottom halves
+ disabled. In particular, this callback function cannot block.
+ If you need the callback to block, run that code in a workqueue
+ handler scheduled from the callback. The queue_rcu_work()
+ function does this for you in the case of call_rcu().
+
+6. Since synchronize_rcu() can block, it cannot be called
+ from any sort of irq context. The same rule applies
+ for synchronize_srcu(), synchronize_rcu_expedited(),
+ synchronize_srcu_expedited(), synchronize_rcu_tasks(),
+ synchronize_rcu_tasks_rude(), and synchronize_rcu_tasks_trace().
+
+ The expedited forms of these primitives have the same semantics
+ as the non-expedited forms, but expediting is more CPU intensive.
+ Use of the expedited primitives should be restricted to rare
+ configuration-change operations that would not normally be
+ undertaken while a real-time workload is running. Note that
+ IPI-sensitive real-time workloads can use the rcupdate.rcu_normal
+ kernel boot parameter to completely disable expedited grace
+ periods, though this might have performance implications.
+
+ In particular, if you find yourself invoking one of the expedited
+ primitives repeatedly in a loop, please do everyone a favor:
+ Restructure your code so that it batches the updates, allowing
+ a single non-expedited primitive to cover the entire batch.
+ This will very likely be faster than the loop containing the
+ expedited primitive, and will be much much easier on the rest
+ of the system, especially to real-time workloads running on the
+ rest of the system. Alternatively, instead use asynchronous
+ primitives such as call_rcu().
+
+7. As of v4.20, a given kernel implements only one RCU flavor, which
+ is RCU-sched for PREEMPTION=n and RCU-preempt for PREEMPTION=y.
+ If the updater uses call_rcu() or synchronize_rcu(), then
+ the corresponding readers may use: (1) rcu_read_lock() and
+ rcu_read_unlock(), (2) any pair of primitives that disables
+ and re-enables softirq, for example, rcu_read_lock_bh() and
+ rcu_read_unlock_bh(), or (3) any pair of primitives that disables
+ and re-enables preemption, for example, rcu_read_lock_sched() and
+ rcu_read_unlock_sched(). If the updater uses synchronize_srcu()
+ or call_srcu(), then the corresponding readers must use
+ srcu_read_lock() and srcu_read_unlock(), and with the same
+ srcu_struct. The rules for the expedited RCU grace-period-wait
+ primitives are the same as for their non-expedited counterparts.
+
+ Similarly, it is necessary to correctly use the RCU Tasks flavors:
+
+ a. If the updater uses synchronize_rcu_tasks() or
+ call_rcu_tasks(), then the readers must refrain from
+ executing voluntary context switches, that is, from
+ blocking.
+
+ b. If the updater uses call_rcu_tasks_trace()
+ or synchronize_rcu_tasks_trace(), then the
+ corresponding readers must use rcu_read_lock_trace()
+ and rcu_read_unlock_trace().
+
+ c. If an updater uses synchronize_rcu_tasks_rude(),
+ then the corresponding readers must use anything that
+ disables preemption, for example, preempt_disable()
+ and preempt_enable().
+
+ Mixing things up will result in confusion and broken kernels, and
+ has even resulted in an exploitable security issue. Therefore,
+ when using non-obvious pairs of primitives, commenting is
+ of course a must. One example of non-obvious pairing is
+ the XDP feature in networking, which calls BPF programs from
+ network-driver NAPI (softirq) context. BPF relies heavily on RCU
+ protection for its data structures, but because the BPF program
+ invocation happens entirely within a single local_bh_disable()
+ section in a NAPI poll cycle, this usage is safe. The reason
+ that this usage is safe is that readers can use anything that
+ disables BH when updaters use call_rcu() or synchronize_rcu().
+
+8. Although synchronize_rcu() is slower than is call_rcu(),
+ it usually results in simpler code. So, unless update
+ performance is critically important, the updaters cannot block,
+ or the latency of synchronize_rcu() is visible from userspace,
+ synchronize_rcu() should be used in preference to call_rcu().
+ Furthermore, kfree_rcu() and kvfree_rcu() usually result
+ in even simpler code than does synchronize_rcu() without
+ synchronize_rcu()'s multi-millisecond latency. So please take
+ advantage of kfree_rcu()'s and kvfree_rcu()'s "fire and forget"
+ memory-freeing capabilities where it applies.
+
+ An especially important property of the synchronize_rcu()
+ primitive is that it automatically self-limits: if grace periods
+ are delayed for whatever reason, then the synchronize_rcu()
+ primitive will correspondingly delay updates. In contrast,
+ code using call_rcu() should explicitly limit update rate in
+ cases where grace periods are delayed, as failing to do so can
+ result in excessive realtime latencies or even OOM conditions.
+
+ Ways of gaining this self-limiting property when using call_rcu(),
+ kfree_rcu(), or kvfree_rcu() include:
+
+ a. Keeping a count of the number of data-structure elements
+ used by the RCU-protected data structure, including
+ those waiting for a grace period to elapse. Enforce a
+ limit on this number, stalling updates as needed to allow
+ previously deferred frees to complete. Alternatively,
+ limit only the number awaiting deferred free rather than
+ the total number of elements.
+
+ One way to stall the updates is to acquire the update-side
+ mutex. (Don't try this with a spinlock -- other CPUs
+ spinning on the lock could prevent the grace period
+ from ever ending.) Another way to stall the updates
+ is for the updates to use a wrapper function around
+ the memory allocator, so that this wrapper function
+ simulates OOM when there is too much memory awaiting an
+ RCU grace period. There are of course many other
+ variations on this theme.
+
+ b. Limiting update rate. For example, if updates occur only
+ once per hour, then no explicit rate limiting is
+ required, unless your system is already badly broken.
+ Older versions of the dcache subsystem take this approach,
+ guarding updates with a global lock, limiting their rate.
+
+ c. Trusted update -- if updates can only be done manually by
+ superuser or some other trusted user, then it might not
+ be necessary to automatically limit them. The theory
+ here is that superuser already has lots of ways to crash
+ the machine.
+
+ d. Periodically invoke rcu_barrier(), permitting a limited
+ number of updates per grace period.
+
+ The same cautions apply to call_srcu(), call_rcu_tasks(), and
+ call_rcu_tasks_trace(). This is why there is an srcu_barrier(),
+ rcu_barrier_tasks(), and rcu_barrier_tasks_trace(), respectively.
+
+ Note that although these primitives do take action to avoid
+ memory exhaustion when any given CPU has too many callbacks,
+ a determined user or administrator can still exhaust memory.
+ This is especially the case if a system with a large number of
+ CPUs has been configured to offload all of its RCU callbacks onto
+ a single CPU, or if the system has relatively little free memory.
+
+9. All RCU list-traversal primitives, which include
+ rcu_dereference(), list_for_each_entry_rcu(), and
+ list_for_each_safe_rcu(), must be either within an RCU read-side
+ critical section or must be protected by appropriate update-side
+ locks. RCU read-side critical sections are delimited by
+ rcu_read_lock() and rcu_read_unlock(), or by similar primitives
+ such as rcu_read_lock_bh() and rcu_read_unlock_bh(), in which
+ case the matching rcu_dereference() primitive must be used in
+ order to keep lockdep happy, in this case, rcu_dereference_bh().
+
+ The reason that it is permissible to use RCU list-traversal
+ primitives when the update-side lock is held is that doing so
+ can be quite helpful in reducing code bloat when common code is
+ shared between readers and updaters. Additional primitives
+ are provided for this case, as discussed in lockdep.rst.
+
+ One exception to this rule is when data is only ever added to
+ the linked data structure, and is never removed during any
+ time that readers might be accessing that structure. In such
+ cases, READ_ONCE() may be used in place of rcu_dereference()
+ and the read-side markers (rcu_read_lock() and rcu_read_unlock(),
+ for example) may be omitted.
+
+10. Conversely, if you are in an RCU read-side critical section,
+ and you don't hold the appropriate update-side lock, you *must*
+ use the "_rcu()" variants of the list macros. Failing to do so
+ will break Alpha, cause aggressive compilers to generate bad code,
+ and confuse people trying to understand your code.
+
+11. Any lock acquired by an RCU callback must be acquired elsewhere
+ with softirq disabled, e.g., via spin_lock_bh(). Failing to
+ disable softirq on a given acquisition of that lock will result
+ in deadlock as soon as the RCU softirq handler happens to run
+ your RCU callback while interrupting that acquisition's critical
+ section.
+
+12. RCU callbacks can be and are executed in parallel. In many cases,
+ the callback code simply wrappers around kfree(), so that this
+ is not an issue (or, more accurately, to the extent that it is
+ an issue, the memory-allocator locking handles it). However,
+ if the callbacks do manipulate a shared data structure, they
+ must use whatever locking or other synchronization is required
+ to safely access and/or modify that data structure.
+
+ Do not assume that RCU callbacks will be executed on the same
+ CPU that executed the corresponding call_rcu(), call_srcu(),
+ call_rcu_tasks(), or call_rcu_tasks_trace(). For example, if
+ a given CPU goes offline while having an RCU callback pending,
+ then that RCU callback will execute on some surviving CPU.
+ (If this was not the case, a self-spawning RCU callback would
+ prevent the victim CPU from ever going offline.) Furthermore,
+ CPUs designated by rcu_nocbs= might well *always* have their
+ RCU callbacks executed on some other CPUs, in fact, for some
+ real-time workloads, this is the whole point of using the
+ rcu_nocbs= kernel boot parameter.
+
+ In addition, do not assume that callbacks queued in a given order
+ will be invoked in that order, even if they all are queued on the
+ same CPU. Furthermore, do not assume that same-CPU callbacks will
+ be invoked serially. For example, in recent kernels, CPUs can be
+ switched between offloaded and de-offloaded callback invocation,
+ and while a given CPU is undergoing such a switch, its callbacks
+ might be concurrently invoked by that CPU's softirq handler and
+ that CPU's rcuo kthread. At such times, that CPU's callbacks
+ might be executed both concurrently and out of order.
+
+13. Unlike most flavors of RCU, it *is* permissible to block in an
+ SRCU read-side critical section (demarked by srcu_read_lock()
+ and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
+ As with RCU, guard(srcu)() and scoped_guard(srcu) forms are
+ available, and often provide greater ease of use. Please note
+ that if you don't need to sleep in read-side critical sections,
+ you should be using RCU rather than SRCU, because RCU is almost
+ always faster and easier to use than is SRCU.
+
+ Also unlike other forms of RCU, explicit initialization
+ and cleanup is required either at build time via
+ DEFINE_SRCU(), DEFINE_STATIC_SRCU(), DEFINE_SRCU_FAST(),
+ or DEFINE_STATIC_SRCU_FAST() or at runtime via either
+ init_srcu_struct() or init_srcu_struct_fast() and
+ cleanup_srcu_struct(). These last three are passed a
+ `struct srcu_struct` that defines the scope of a given
+ SRCU domain. Once initialized, the srcu_struct is passed
+ to srcu_read_lock(), srcu_read_unlock() synchronize_srcu(),
+ synchronize_srcu_expedited(), and call_srcu(). A given
+ synchronize_srcu() waits only for SRCU read-side critical
+ sections governed by srcu_read_lock() and srcu_read_unlock()
+ calls that have been passed the same srcu_struct. This property
+ is what makes sleeping read-side critical sections tolerable --
+ a given subsystem delays only its own updates, not those of other
+ subsystems using SRCU. Therefore, SRCU is less prone to OOM the
+ system than RCU would be if RCU's read-side critical sections
+ were permitted to sleep.
+
+ The ability to sleep in read-side critical sections does not
+ come for free. First, corresponding srcu_read_lock() and
+ srcu_read_unlock() calls must be passed the same srcu_struct.
+ Second, grace-period-detection overhead is amortized only
+ over those updates sharing a given srcu_struct, rather than
+ being globally amortized as they are for other forms of RCU.
+ Therefore, SRCU should be used in preference to rw_semaphore
+ only in extremely read-intensive situations, or in situations
+ requiring SRCU's read-side deadlock immunity or low read-side
+ realtime latency. You should also consider percpu_rw_semaphore
+ when you need lightweight readers.
+
+ SRCU's expedited primitive (synchronize_srcu_expedited())
+ never sends IPIs to other CPUs, so it is easier on
+ real-time workloads than is synchronize_rcu_expedited().
+
+ It is also permissible to sleep in RCU Tasks Trace read-side
+ critical section, which are delimited by rcu_read_lock_trace()
+ and rcu_read_unlock_trace(). However, this is a specialized
+ flavor of RCU, and you should not use it without first checking
+ with its current users. In most cases, you should instead
+ use SRCU. As with RCU and SRCU, guard(rcu_tasks_trace)() and
+ scoped_guard(rcu_tasks_trace) are available, and often provide
+ greater ease of use.
+
+ Note that rcu_assign_pointer() relates to SRCU just as it does to
+ other forms of RCU, but instead of rcu_dereference() you should
+ use srcu_dereference() in order to avoid lockdep splats.
+
+14. The whole point of call_rcu(), synchronize_rcu(), and friends
+ is to wait until all pre-existing readers have finished before
+ carrying out some otherwise-destructive operation. It is
+ therefore critically important to *first* remove any path
+ that readers can follow that could be affected by the
+ destructive operation, and *only then* invoke call_rcu(),
+ synchronize_rcu(), or friends.
+
+ Because these primitives only wait for pre-existing readers, it
+ is the caller's responsibility to guarantee that any subsequent
+ readers will execute safely.
+
+15. The various RCU read-side primitives do *not* necessarily contain
+ memory barriers. You should therefore plan for the CPU
+ and the compiler to freely reorder code into and out of RCU
+ read-side critical sections. It is the responsibility of the
+ RCU update-side primitives to deal with this.
+
+ For SRCU readers, you can use smp_mb__after_srcu_read_unlock()
+ immediately after an srcu_read_unlock() to get a full barrier.
+
+16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
+ __rcu sparse checks to validate your RCU code. These can help
+ find problems as follows:
+
+ CONFIG_PROVE_LOCKING:
+ check that accesses to RCU-protected data structures
+ are carried out under the proper RCU read-side critical
+ section, while holding the right combination of locks,
+ or whatever other conditions are appropriate.
+
+ CONFIG_DEBUG_OBJECTS_RCU_HEAD:
+ check that you don't pass the same object to call_rcu()
+ (or friends) before an RCU grace period has elapsed
+ since the last time that you passed that same object to
+ call_rcu() (or friends).
+
+ CONFIG_RCU_STRICT_GRACE_PERIOD:
+ combine with KASAN to check for pointers leaked out
+ of RCU read-side critical sections. This Kconfig
+ option is tough on both performance and scalability,
+ and so is limited to four-CPU systems.
+
+ __rcu sparse checks:
+ tag the pointer to the RCU-protected data structure
+ with __rcu, and sparse will warn you if you access that
+ pointer without the services of one of the variants
+ of rcu_dereference().
+
+ These debugging aids can help you find problems that are
+ otherwise extremely difficult to spot.
+
+17. If you pass a callback function defined within a module
+ to one of call_rcu(), call_srcu(), call_rcu_tasks(), or
+ call_rcu_tasks_trace(), then it is necessary to wait for all
+ pending callbacks to be invoked before unloading that module.
+ Note that it is absolutely *not* sufficient to wait for a grace
+ period! For example, synchronize_rcu() implementation is *not*
+ guaranteed to wait for callbacks registered on other CPUs via
+ call_rcu(). Or even on the current CPU if that CPU recently
+ went offline and came back online.
+
+ You instead need to use one of the barrier functions:
+
+ - call_rcu() -> rcu_barrier()
+ - call_srcu() -> srcu_barrier()
+ - call_rcu_tasks() -> rcu_barrier_tasks()
+ - call_rcu_tasks_trace() -> rcu_barrier_tasks_trace()
+
+ However, these barrier functions are absolutely *not* guaranteed
+ to wait for a grace period. For example, if there are no
+ call_rcu() callbacks queued anywhere in the system, rcu_barrier()
+ can and will return immediately.
+
+ So if you need to wait for both a grace period and for all
+ pre-existing callbacks, you will need to invoke both functions,
+ with the pair depending on the flavor of RCU:
+
+ - Either synchronize_rcu() or synchronize_rcu_expedited(),
+ together with rcu_barrier()
+ - Either synchronize_srcu() or synchronize_srcu_expedited(),
+ together with and srcu_barrier()
+ - synchronize_rcu_tasks() and rcu_barrier_tasks()
+ - synchronize_tasks_trace() and rcu_barrier_tasks_trace()
+
+ If necessary, you can use something like workqueues to execute
+ the requisite pair of functions concurrently.
+
+ See rcubarrier.rst for more information.
diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
deleted file mode 100644
index 877947130ebe..000000000000
--- a/Documentation/RCU/checklist.txt
+++ /dev/null
@@ -1,437 +0,0 @@
-Review Checklist for RCU Patches
-
-
-This document contains a checklist for producing and reviewing patches
-that make use of RCU. Violating any of the rules listed below will
-result in the same sorts of problems that leaving out a locking primitive
-would cause. This list is based on experiences reviewing such patches
-over a rather long period of time, but improvements are always welcome!
-
-0. Is RCU being applied to a read-mostly situation? If the data
- structure is updated more than about 10% of the time, then you
- should strongly consider some other approach, unless detailed
- performance measurements show that RCU is nonetheless the right
- tool for the job. Yes, RCU does reduce read-side overhead by
- increasing write-side overhead, which is exactly why normal uses
- of RCU will do much more reading than updating.
-
- Another exception is where performance is not an issue, and RCU
- provides a simpler implementation. An example of this situation
- is the dynamic NMI code in the Linux 2.6 kernel, at least on
- architectures where NMIs are rare.
-
- Yet another exception is where the low real-time latency of RCU's
- read-side primitives is critically important.
-
-1. Does the update code have proper mutual exclusion?
-
- RCU does allow -readers- to run (almost) naked, but -writers- must
- still use some sort of mutual exclusion, such as:
-
- a. locking,
- b. atomic operations, or
- c. restricting updates to a single task.
-
- If you choose #b, be prepared to describe how you have handled
- memory barriers on weakly ordered machines (pretty much all of
- them -- even x86 allows later loads to be reordered to precede
- earlier stores), and be prepared to explain why this added
- complexity is worthwhile. If you choose #c, be prepared to
- explain how this single task does not become a major bottleneck on
- big multiprocessor machines (for example, if the task is updating
- information relating to itself that other tasks can read, there
- by definition can be no bottleneck).
-
-2. Do the RCU read-side critical sections make proper use of
- rcu_read_lock() and friends? These primitives are needed
- to prevent grace periods from ending prematurely, which
- could result in data being unceremoniously freed out from
- under your read-side code, which can greatly increase the
- actuarial risk of your kernel.
-
- As a rough rule of thumb, any dereference of an RCU-protected
- pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(),
- rcu_read_lock_sched(), or by the appropriate update-side lock.
- Disabling of preemption can serve as rcu_read_lock_sched(), but
- is less readable.
-
-3. Does the update code tolerate concurrent accesses?
-
- The whole point of RCU is to permit readers to run without
- any locks or atomic operations. This means that readers will
- be running while updates are in progress. There are a number
- of ways to handle this concurrency, depending on the situation:
-
- a. Use the RCU variants of the list and hlist update
- primitives to add, remove, and replace elements on
- an RCU-protected list. Alternatively, use the other
- RCU-protected data structures that have been added to
- the Linux kernel.
-
- This is almost always the best approach.
-
- b. Proceed as in (a) above, but also maintain per-element
- locks (that are acquired by both readers and writers)
- that guard per-element state. Of course, fields that
- the readers refrain from accessing can be guarded by
- some other lock acquired only by updaters, if desired.
-
- This works quite well, also.
-
- c. Make updates appear atomic to readers. For example,
- pointer updates to properly aligned fields will
- appear atomic, as will individual atomic primitives.
- Sequences of perations performed under a lock will -not-
- appear to be atomic to RCU readers, nor will sequences
- of multiple atomic primitives.
-
- This can work, but is starting to get a bit tricky.
-
- d. Carefully order the updates and the reads so that
- readers see valid data at all phases of the update.
- This is often more difficult than it sounds, especially
- given modern CPUs' tendency to reorder memory references.
- One must usually liberally sprinkle memory barriers
- (smp_wmb(), smp_rmb(), smp_mb()) through the code,
- making it difficult to understand and to test.
-
- It is usually better to group the changing data into
- a separate structure, so that the change may be made
- to appear atomic by updating a pointer to reference
- a new structure containing updated values.
-
-4. Weakly ordered CPUs pose special challenges. Almost all CPUs
- are weakly ordered -- even x86 CPUs allow later loads to be
- reordered to precede earlier stores. RCU code must take all of
- the following measures to prevent memory-corruption problems:
-
- a. Readers must maintain proper ordering of their memory
- accesses. The rcu_dereference() primitive ensures that
- the CPU picks up the pointer before it picks up the data
- that the pointer points to. This really is necessary
- on Alpha CPUs. If you don't believe me, see:
-
- http://www.openvms.compaq.com/wizard/wiz_2637.html
-
- The rcu_dereference() primitive is also an excellent
- documentation aid, letting the person reading the
- code know exactly which pointers are protected by RCU.
- Please note that compilers can also reorder code, and
- they are becoming increasingly aggressive about doing
- just that. The rcu_dereference() primitive therefore also
- prevents destructive compiler optimizations. However,
- with a bit of devious creativity, it is possible to
- mishandle the return value from rcu_dereference().
- Please see rcu_dereference.txt in this directory for
- more information.
-
- The rcu_dereference() primitive is used by the
- various "_rcu()" list-traversal primitives, such
- as the list_for_each_entry_rcu(). Note that it is
- perfectly legal (if redundant) for update-side code to
- use rcu_dereference() and the "_rcu()" list-traversal
- primitives. This is particularly useful in code that
- is common to readers and updaters. However, lockdep
- will complain if you access rcu_dereference() outside
- of an RCU read-side critical section. See lockdep.txt
- to learn what to do about this.
-
- Of course, neither rcu_dereference() nor the "_rcu()"
- list-traversal primitives can substitute for a good
- concurrency design coordinating among multiple updaters.
-
- b. If the list macros are being used, the list_add_tail_rcu()
- and list_add_rcu() primitives must be used in order
- to prevent weakly ordered machines from misordering
- structure initialization and pointer planting.
- Similarly, if the hlist macros are being used, the
- hlist_add_head_rcu() primitive is required.
-
- c. If the list macros are being used, the list_del_rcu()
- primitive must be used to keep list_del()'s pointer
- poisoning from inflicting toxic effects on concurrent
- readers. Similarly, if the hlist macros are being used,
- the hlist_del_rcu() primitive is required.
-
- The list_replace_rcu() and hlist_replace_rcu() primitives
- may be used to replace an old structure with a new one
- in their respective types of RCU-protected lists.
-
- d. Rules similar to (4b) and (4c) apply to the "hlist_nulls"
- type of RCU-protected linked lists.
-
- e. Updates must ensure that initialization of a given
- structure happens before pointers to that structure are
- publicized. Use the rcu_assign_pointer() primitive
- when publicizing a pointer to a structure that can
- be traversed by an RCU read-side critical section.
-
-5. If call_rcu(), or a related primitive such as call_rcu_bh(),
- call_rcu_sched(), or call_srcu() is used, the callback function
- must be written to be called from softirq context. In particular,
- it cannot block.
-
-6. Since synchronize_rcu() can block, it cannot be called from
- any sort of irq context. The same rule applies for
- synchronize_rcu_bh(), synchronize_sched(), synchronize_srcu(),
- synchronize_rcu_expedited(), synchronize_rcu_bh_expedited(),
- synchronize_sched_expedite(), and synchronize_srcu_expedited().
-
- The expedited forms of these primitives have the same semantics
- as the non-expedited forms, but expediting is both expensive
- and unfriendly to real-time workloads. Use of the expedited
- primitives should be restricted to rare configuration-change
- operations that would not normally be undertaken while a real-time
- workload is running.
-
- In particular, if you find yourself invoking one of the expedited
- primitives repeatedly in a loop, please do everyone a favor:
- Restructure your code so that it batches the updates, allowing
- a single non-expedited primitive to cover the entire batch.
- This will very likely be faster than the loop containing the
- expedited primitive, and will be much much easier on the rest
- of the system, especially to real-time workloads running on
- the rest of the system.
-
- In addition, it is illegal to call the expedited forms from
- a CPU-hotplug notifier, or while holding a lock that is acquired
- by a CPU-hotplug notifier. Failing to observe this restriction
- will result in deadlock.
-
-7. If the updater uses call_rcu() or synchronize_rcu(), then the
- corresponding readers must use rcu_read_lock() and
- rcu_read_unlock(). If the updater uses call_rcu_bh() or
- synchronize_rcu_bh(), then the corresponding readers must
- use rcu_read_lock_bh() and rcu_read_unlock_bh(). If the
- updater uses call_rcu_sched() or synchronize_sched(), then
- the corresponding readers must disable preemption, possibly
- by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
- If the updater uses synchronize_srcu() or call_srcu(), then
- the corresponding readers must use srcu_read_lock() and
- srcu_read_unlock(), and with the same srcu_struct. The rules for
- the expedited primitives are the same as for their non-expedited
- counterparts. Mixing things up will result in confusion and
- broken kernels.
-
- One exception to this rule: rcu_read_lock() and rcu_read_unlock()
- may be substituted for rcu_read_lock_bh() and rcu_read_unlock_bh()
- in cases where local bottom halves are already known to be
- disabled, for example, in irq or softirq context. Commenting
- such cases is a must, of course! And the jury is still out on
- whether the increased speed is worth it.
-
-8. Although synchronize_rcu() is slower than is call_rcu(), it
- usually results in simpler code. So, unless update performance is
- critically important, the updaters cannot block, or the latency of
- synchronize_rcu() is visible from userspace, synchronize_rcu()
- should be used in preference to call_rcu(). Furthermore,
- kfree_rcu() usually results in even simpler code than does
- synchronize_rcu() without synchronize_rcu()'s multi-millisecond
- latency. So please take advantage of kfree_rcu()'s "fire and
- forget" memory-freeing capabilities where it applies.
-
- An especially important property of the synchronize_rcu()
- primitive is that it automatically self-limits: if grace periods
- are delayed for whatever reason, then the synchronize_rcu()
- primitive will correspondingly delay updates. In contrast,
- code using call_rcu() should explicitly limit update rate in
- cases where grace periods are delayed, as failing to do so can
- result in excessive realtime latencies or even OOM conditions.
-
- Ways of gaining this self-limiting property when using call_rcu()
- include:
-
- a. Keeping a count of the number of data-structure elements
- used by the RCU-protected data structure, including
- those waiting for a grace period to elapse. Enforce a
- limit on this number, stalling updates as needed to allow
- previously deferred frees to complete. Alternatively,
- limit only the number awaiting deferred free rather than
- the total number of elements.
-
- One way to stall the updates is to acquire the update-side
- mutex. (Don't try this with a spinlock -- other CPUs
- spinning on the lock could prevent the grace period
- from ever ending.) Another way to stall the updates
- is for the updates to use a wrapper function around
- the memory allocator, so that this wrapper function
- simulates OOM when there is too much memory awaiting an
- RCU grace period. There are of course many other
- variations on this theme.
-
- b. Limiting update rate. For example, if updates occur only
- once per hour, then no explicit rate limiting is
- required, unless your system is already badly broken.
- Older versions of the dcache subsystem take this approach,
- guarding updates with a global lock, limiting their rate.
-
- c. Trusted update -- if updates can only be done manually by
- superuser or some other trusted user, then it might not
- be necessary to automatically limit them. The theory
- here is that superuser already has lots of ways to crash
- the machine.
-
- d. Use call_rcu_bh() rather than call_rcu(), in order to take
- advantage of call_rcu_bh()'s faster grace periods. (This
- is only a partial solution, though.)
-
- e. Periodically invoke synchronize_rcu(), permitting a limited
- number of updates per grace period.
-
- The same cautions apply to call_rcu_bh(), call_rcu_sched(),
- call_srcu(), and kfree_rcu().
-
- Note that although these primitives do take action to avoid memory
- exhaustion when any given CPU has too many callbacks, a determined
- user could still exhaust memory. This is especially the case
- if a system with a large number of CPUs has been configured to
- offload all of its RCU callbacks onto a single CPU, or if the
- system has relatively little free memory.
-
-9. All RCU list-traversal primitives, which include
- rcu_dereference(), list_for_each_entry_rcu(), and
- list_for_each_safe_rcu(), must be either within an RCU read-side
- critical section or must be protected by appropriate update-side
- locks. RCU read-side critical sections are delimited by
- rcu_read_lock() and rcu_read_unlock(), or by similar primitives
- such as rcu_read_lock_bh() and rcu_read_unlock_bh(), in which
- case the matching rcu_dereference() primitive must be used in
- order to keep lockdep happy, in this case, rcu_dereference_bh().
-
- The reason that it is permissible to use RCU list-traversal
- primitives when the update-side lock is held is that doing so
- can be quite helpful in reducing code bloat when common code is
- shared between readers and updaters. Additional primitives
- are provided for this case, as discussed in lockdep.txt.
-
-10. Conversely, if you are in an RCU read-side critical section,
- and you don't hold the appropriate update-side lock, you -must-
- use the "_rcu()" variants of the list macros. Failing to do so
- will break Alpha, cause aggressive compilers to generate bad code,
- and confuse people trying to read your code.
-
-11. Note that synchronize_rcu() -only- guarantees to wait until
- all currently executing rcu_read_lock()-protected RCU read-side
- critical sections complete. It does -not- necessarily guarantee
- that all currently running interrupts, NMIs, preempt_disable()
- code, or idle loops will complete. Therefore, if your
- read-side critical sections are protected by something other
- than rcu_read_lock(), do -not- use synchronize_rcu().
-
- Similarly, disabling preemption is not an acceptable substitute
- for rcu_read_lock(). Code that attempts to use preemption
- disabling where it should be using rcu_read_lock() will break
- in real-time kernel builds.
-
- If you want to wait for interrupt handlers, NMI handlers, and
- code under the influence of preempt_disable(), you instead
- need to use synchronize_irq() or synchronize_sched().
-
- This same limitation also applies to synchronize_rcu_bh()
- and synchronize_srcu(), as well as to the asynchronous and
- expedited forms of the three primitives, namely call_rcu(),
- call_rcu_bh(), call_srcu(), synchronize_rcu_expedited(),
- synchronize_rcu_bh_expedited(), and synchronize_srcu_expedited().
-
-12. Any lock acquired by an RCU callback must be acquired elsewhere
- with softirq disabled, e.g., via spin_lock_irqsave(),
- spin_lock_bh(), etc. Failing to disable irq on a given
- acquisition of that lock will result in deadlock as soon as
- the RCU softirq handler happens to run your RCU callback while
- interrupting that acquisition's critical section.
-
-13. RCU callbacks can be and are executed in parallel. In many cases,
- the callback code simply wrappers around kfree(), so that this
- is not an issue (or, more accurately, to the extent that it is
- an issue, the memory-allocator locking handles it). However,
- if the callbacks do manipulate a shared data structure, they
- must use whatever locking or other synchronization is required
- to safely access and/or modify that data structure.
-
- RCU callbacks are -usually- executed on the same CPU that executed
- the corresponding call_rcu(), call_rcu_bh(), or call_rcu_sched(),
- but are by -no- means guaranteed to be. For example, if a given
- CPU goes offline while having an RCU callback pending, then that
- RCU callback will execute on some surviving CPU. (If this was
- not the case, a self-spawning RCU callback would prevent the
- victim CPU from ever going offline.)
-
-14. SRCU (srcu_read_lock(), srcu_read_unlock(), srcu_dereference(),
- synchronize_srcu(), synchronize_srcu_expedited(), and call_srcu())
- may only be invoked from process context. Unlike other forms of
- RCU, it -is- permissible to block in an SRCU read-side critical
- section (demarked by srcu_read_lock() and srcu_read_unlock()),
- hence the "SRCU": "sleepable RCU". Please note that if you
- don't need to sleep in read-side critical sections, you should be
- using RCU rather than SRCU, because RCU is almost always faster
- and easier to use than is SRCU.
-
- Also unlike other forms of RCU, explicit initialization
- and cleanup is required via init_srcu_struct() and
- cleanup_srcu_struct(). These are passed a "struct srcu_struct"
- that defines the scope of a given SRCU domain. Once initialized,
- the srcu_struct is passed to srcu_read_lock(), srcu_read_unlock()
- synchronize_srcu(), synchronize_srcu_expedited(), and call_srcu().
- A given synchronize_srcu() waits only for SRCU read-side critical
- sections governed by srcu_read_lock() and srcu_read_unlock()
- calls that have been passed the same srcu_struct. This property
- is what makes sleeping read-side critical sections tolerable --
- a given subsystem delays only its own updates, not those of other
- subsystems using SRCU. Therefore, SRCU is less prone to OOM the
- system than RCU would be if RCU's read-side critical sections
- were permitted to sleep.
-
- The ability to sleep in read-side critical sections does not
- come for free. First, corresponding srcu_read_lock() and
- srcu_read_unlock() calls must be passed the same srcu_struct.
- Second, grace-period-detection overhead is amortized only
- over those updates sharing a given srcu_struct, rather than
- being globally amortized as they are for other forms of RCU.
- Therefore, SRCU should be used in preference to rw_semaphore
- only in extremely read-intensive situations, or in situations
- requiring SRCU's read-side deadlock immunity or low read-side
- realtime latency.
-
- Note that, rcu_assign_pointer() relates to SRCU just as it does
- to other forms of RCU.
-
-15. The whole point of call_rcu(), synchronize_rcu(), and friends
- is to wait until all pre-existing readers have finished before
- carrying out some otherwise-destructive operation. It is
- therefore critically important to -first- remove any path
- that readers can follow that could be affected by the
- destructive operation, and -only- -then- invoke call_rcu(),
- synchronize_rcu(), or friends.
-
- Because these primitives only wait for pre-existing readers, it
- is the caller's responsibility to guarantee that any subsequent
- readers will execute safely.
-
-16. The various RCU read-side primitives do -not- necessarily contain
- memory barriers. You should therefore plan for the CPU
- and the compiler to freely reorder code into and out of RCU
- read-side critical sections. It is the responsibility of the
- RCU update-side primitives to deal with this.
-
-17. Use CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
- __rcu sparse checks (enabled by CONFIG_SPARSE_RCU_POINTER) to
- validate your RCU code. These can help find problems as follows:
-
- CONFIG_PROVE_RCU: check that accesses to RCU-protected data
- structures are carried out under the proper RCU
- read-side critical section, while holding the right
- combination of locks, or whatever other conditions
- are appropriate.
-
- CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the
- same object to call_rcu() (or friends) before an RCU
- grace period has elapsed since the last time that you
- passed that same object to call_rcu() (or friends).
-
- __rcu sparse checks: tag the pointer to the RCU-protected data
- structure with __rcu, and sparse will warn you if you
- access that pointer without the services of one of the
- variants of rcu_dereference().
-
- These debugging aids can help you find problems that are
- otherwise extremely difficult to spot.
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..ef26c78507d3
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _rcu_handbook:
+
+============
+RCU Handbook
+============
+
+.. toctree::
+ :maxdepth: 2
+
+ checklist
+ lockdep
+ lockdep-splat
+ rcubarrier
+ rcu_dereference
+ whatisRCU
+ rcu
+ rculist_nulls
+ rcuref
+ torture
+ stallwarn
+ listRCU
+ NMI-RCU
+ UP
+
+ Design/Memory-Ordering/Tree-RCU-Memory-Ordering
+ Design/Expedited-Grace-Periods/Expedited-Grace-Periods
+ Design/Requirements/Requirements
+ Design/Data-Structures/Data-Structures
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
new file mode 100644
index 000000000000..d8bb98623c12
--- /dev/null
+++ b/Documentation/RCU/listRCU.rst
@@ -0,0 +1,511 @@
+.. _list_rcu_doc:
+
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
+
+One of the most common uses of RCU is protecting read-mostly linked lists
+(``struct list_head`` in list.h). One big advantage of this approach is
+that all of the required memory ordering is provided by the list macros.
+This document describes several list-based RCU use cases.
+
+When iterating a list while holding the rcu_read_lock(), writers may
+modify the list. The reader is guaranteed to see all of the elements
+which were added to the list before they acquired the rcu_read_lock()
+and are still on the list when they drop the rcu_read_unlock().
+Elements which are added to, or removed from the list may or may not
+be seen. If the writer calls list_replace_rcu(), the reader may see
+either the old element or the new element; they will not see both,
+nor will they see neither.
+
+
+Example 1: Read-mostly list: Deferred Destruction
+-------------------------------------------------
+
+A widely used usecase for RCU lists in the kernel is lockless iteration over
+all processes in the system. ``task_struct::tasks`` represents the list node that
+links all the processes. The list can be traversed in parallel to any list
+additions or removals.
+
+The traversal of the list is done using ``for_each_process()`` which is defined
+by the 2 macros::
+
+ #define next_task(p) \
+ list_entry_rcu((p)->tasks.next, struct task_struct, tasks)
+
+ #define for_each_process(p) \
+ for (p = &init_task ; (p = next_task(p)) != &init_task ; )
+
+The code traversing the list of all processes typically looks like::
+
+ rcu_read_lock();
+ for_each_process(p) {
+ /* Do something with p */
+ }
+ rcu_read_unlock();
+
+The simplified and heavily inlined code for removing a process from a
+task list is::
+
+ void release_task(struct task_struct *p)
+ {
+ write_lock(&tasklist_lock);
+ list_del_rcu(&p->tasks);
+ write_unlock(&tasklist_lock);
+ call_rcu(&p->rcu, delayed_put_task_struct);
+ }
+
+When a process exits, ``release_task()`` calls ``list_del_rcu(&p->tasks)``
+via __exit_signal() and __unhash_process() under ``tasklist_lock``
+writer lock protection. The list_del_rcu() invocation removes
+the task from the list of all tasks. The ``tasklist_lock``
+prevents concurrent list additions/removals from corrupting the
+list. Readers using ``for_each_process()`` are not protected with the
+``tasklist_lock``. To prevent readers from noticing changes in the list
+pointers, the ``task_struct`` object is freed only after one or more
+grace periods elapse, with the help of call_rcu(), which is invoked via
+put_task_struct_rcu_user(). This deferring of destruction ensures that
+any readers traversing the list will see valid ``p->tasks.next`` pointers
+and deletion/freeing can happen in parallel with traversal of the list.
+This pattern is also called an **existence lock**, since RCU refrains
+from invoking the delayed_put_task_struct() callback function until
+all existing readers finish, which guarantees that the ``task_struct``
+object in question will remain in existence until after the completion
+of all RCU readers that might possibly have a reference to that object.
+
+
+Example 2: Read-Side Action Taken Outside of Lock: No In-Place Updates
+----------------------------------------------------------------------
+
+Some reader-writer locking use cases compute a value while holding
+the read-side lock, but continue to use that value after that lock is
+released. These use cases are often good candidates for conversion
+to RCU. One prominent example involves network packet routing.
+Because the packet-routing data tracks the state of equipment outside
+of the computer, it will at times contain stale data. Therefore, once
+the route has been computed, there is no need to hold the routing table
+static during transmission of the packet. After all, you can hold the
+routing table static all you want, but that won't keep the external
+Internet from changing, and it is the state of the external Internet
+that really matters. In addition, routing entries are typically added
+or deleted, rather than being modified in place. This is a rare example
+of the finite speed of light and the non-zero size of atoms actually
+helping make synchronization be lighter weight.
+
+A straightforward example of this type of RCU use case may be found in
+the system-call auditing support. For example, a reader-writer locked
+implementation of ``audit_filter_task()`` might be as follows::
+
+ static enum audit_state audit_filter_task(struct task_struct *tsk, char **key)
+ {
+ struct audit_entry *e;
+ enum audit_state state;
+
+ read_lock(&auditsc_lock);
+ /* Note: audit_filter_mutex held by caller. */
+ list_for_each_entry(e, &audit_tsklist, list) {
+ if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+ if (state == AUDIT_STATE_RECORD)
+ *key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
+ read_unlock(&auditsc_lock);
+ return state;
+ }
+ }
+ read_unlock(&auditsc_lock);
+ return AUDIT_BUILD_CONTEXT;
+ }
+
+Here the list is searched under the lock, but the lock is dropped before
+the corresponding value is returned. By the time that this value is acted
+on, the list may well have been modified. This makes sense, since if
+you are turning auditing off, it is OK to audit a few extra system calls.
+
+This means that RCU can be easily applied to the read side, as follows::
+
+ static enum audit_state audit_filter_task(struct task_struct *tsk, char **key)
+ {
+ struct audit_entry *e;
+ enum audit_state state;
+
+ rcu_read_lock();
+ /* Note: audit_filter_mutex held by caller. */
+ list_for_each_entry_rcu(e, &audit_tsklist, list) {
+ if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+ if (state == AUDIT_STATE_RECORD)
+ *key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
+ rcu_read_unlock();
+ return state;
+ }
+ }
+ rcu_read_unlock();
+ return AUDIT_BUILD_CONTEXT;
+ }
+
+The read_lock() and read_unlock() calls have become rcu_read_lock()
+and rcu_read_unlock(), respectively, and the list_for_each_entry()
+has become list_for_each_entry_rcu(). The **_rcu()** list-traversal
+primitives add READ_ONCE() and diagnostic checks for incorrect use
+outside of an RCU read-side critical section.
+
+The changes to the update side are also straightforward. A reader-writer lock
+might be used as follows for deletion and insertion in these simplified
+versions of audit_del_rule() and audit_add_rule()::
+
+ static inline int audit_del_rule(struct audit_rule *rule,
+ struct list_head *list)
+ {
+ struct audit_entry *e;
+
+ write_lock(&auditsc_lock);
+ list_for_each_entry(e, list, list) {
+ if (!audit_compare_rule(rule, &e->rule)) {
+ list_del(&e->list);
+ write_unlock(&auditsc_lock);
+ return 0;
+ }
+ }
+ write_unlock(&auditsc_lock);
+ return -EFAULT; /* No matching rule */
+ }
+
+ static inline int audit_add_rule(struct audit_entry *entry,
+ struct list_head *list)
+ {
+ write_lock(&auditsc_lock);
+ if (entry->rule.flags & AUDIT_PREPEND) {
+ entry->rule.flags &= ~AUDIT_PREPEND;
+ list_add(&entry->list, list);
+ } else {
+ list_add_tail(&entry->list, list);
+ }
+ write_unlock(&auditsc_lock);
+ return 0;
+ }
+
+Following are the RCU equivalents for these two functions::
+
+ static inline int audit_del_rule(struct audit_rule *rule,
+ struct list_head *list)
+ {
+ struct audit_entry *e;
+
+ /* No need to use the _rcu iterator here, since this is the only
+ * deletion routine. */
+ list_for_each_entry(e, list, list) {
+ if (!audit_compare_rule(rule, &e->rule)) {
+ list_del_rcu(&e->list);
+ call_rcu(&e->rcu, audit_free_rule);
+ return 0;
+ }
+ }
+ return -EFAULT; /* No matching rule */
+ }
+
+ static inline int audit_add_rule(struct audit_entry *entry,
+ struct list_head *list)
+ {
+ if (entry->rule.flags & AUDIT_PREPEND) {
+ entry->rule.flags &= ~AUDIT_PREPEND;
+ list_add_rcu(&entry->list, list);
+ } else {
+ list_add_tail_rcu(&entry->list, list);
+ }
+ return 0;
+ }
+
+Normally, the write_lock() and write_unlock() would be replaced by a
+spin_lock() and a spin_unlock(). But in this case, all callers hold
+``audit_filter_mutex``, so no additional locking is required. The
+auditsc_lock can therefore be eliminated, since use of RCU eliminates the
+need for writers to exclude readers.
+
+The list_del(), list_add(), and list_add_tail() primitives have been
+replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
+The **_rcu()** list-manipulation primitives add memory barriers that are
+needed on weakly ordered CPUs. The list_del_rcu() primitive omits the
+pointer poisoning debug-assist code that would otherwise cause concurrent
+readers to fail spectacularly.
+
+So, when readers can tolerate stale data and when entries are either added or
+deleted, without in-place modification, it is very easy to use RCU!
+
+
+Example 3: Handling In-Place Updates
+------------------------------------
+
+The system-call auditing code does not update auditing rules in place. However,
+if it did, the reader-writer-locked code to do so might look as follows
+(assuming only ``field_count`` is updated, otherwise, the added fields would
+need to be filled in)::
+
+ static inline int audit_upd_rule(struct audit_rule *rule,
+ struct list_head *list,
+ __u32 newaction,
+ __u32 newfield_count)
+ {
+ struct audit_entry *e;
+ struct audit_entry *ne;
+
+ write_lock(&auditsc_lock);
+ /* Note: audit_filter_mutex held by caller. */
+ list_for_each_entry(e, list, list) {
+ if (!audit_compare_rule(rule, &e->rule)) {
+ e->rule.action = newaction;
+ e->rule.field_count = newfield_count;
+ write_unlock(&auditsc_lock);
+ return 0;
+ }
+ }
+ write_unlock(&auditsc_lock);
+ return -EFAULT; /* No matching rule */
+ }
+
+The RCU version creates a copy, updates the copy, then replaces the old
+entry with the newly updated entry. This sequence of actions, allowing
+concurrent reads while making a copy to perform an update, is what gives
+RCU (*read-copy update*) its name.
+
+The RCU version of audit_upd_rule() is as follows::
+
+ static inline int audit_upd_rule(struct audit_rule *rule,
+ struct list_head *list,
+ __u32 newaction,
+ __u32 newfield_count)
+ {
+ struct audit_entry *e;
+ struct audit_entry *ne;
+
+ list_for_each_entry(e, list, list) {
+ if (!audit_compare_rule(rule, &e->rule)) {
+ ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
+ if (ne == NULL)
+ return -ENOMEM;
+ audit_copy_rule(&ne->rule, &e->rule);
+ ne->rule.action = newaction;
+ ne->rule.field_count = newfield_count;
+ list_replace_rcu(&e->list, &ne->list);
+ call_rcu(&e->rcu, audit_free_rule);
+ return 0;
+ }
+ }
+ return -EFAULT; /* No matching rule */
+ }
+
+Again, this assumes that the caller holds ``audit_filter_mutex``. Normally, the
+writer lock would become a spinlock in this sort of code.
+
+The update_lsm_rule() does something very similar, for those who would
+prefer to look at real Linux-kernel code.
+
+Another use of this pattern can be found in the openswitch driver's *connection
+tracking table* code in ``ct_limit_set()``. The table holds connection tracking
+entries and has a limit on the maximum entries. There is one such table
+per-zone and hence one *limit* per zone. The zones are mapped to their limits
+through a hashtable using an RCU-managed hlist for the hash chains. When a new
+limit is set, a new limit object is allocated and ``ct_limit_set()`` is called
+to replace the old limit object with the new one using list_replace_rcu().
+The old limit object is then freed after a grace period using kfree_rcu().
+
+
+Example 4: Eliminating Stale Data
+---------------------------------
+
+The auditing example above tolerates stale data, as do most algorithms
+that are tracking external state. After all, given there is a delay
+from the time the external state changes before Linux becomes aware
+of the change, and so as noted earlier, a small quantity of additional
+RCU-induced staleness is generally not a problem.
+
+However, there are many examples where stale data cannot be tolerated.
+One example in the Linux kernel is the System V IPC (see the shm_lock()
+function in ipc/shm.c). This code checks a *deleted* flag under a
+per-entry spinlock, and, if the *deleted* flag is set, pretends that the
+entry does not exist. For this to be helpful, the search function must
+return holding the per-entry spinlock, as shm_lock() does in fact do.
+
+.. _quick_quiz:
+
+Quick Quiz:
+ For the deleted-flag technique to be helpful, why is it necessary
+ to hold the per-entry lock while returning from the search function?
+
+:ref:`Answer to Quick Quiz <quick_quiz_answer>`
+
+If the system-call audit module were to ever need to reject stale data, one way
+to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to the
+``audit_entry`` structure, and modify audit_filter_task() as follows::
+
+ static struct audit_entry *audit_filter_task(struct task_struct *tsk, char **key)
+ {
+ struct audit_entry *e;
+ enum audit_state state;
+
+ rcu_read_lock();
+ list_for_each_entry_rcu(e, &audit_tsklist, list) {
+ if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+ spin_lock(&e->lock);
+ if (e->deleted) {
+ spin_unlock(&e->lock);
+ rcu_read_unlock();
+ return NULL;
+ }
+ rcu_read_unlock();
+ if (state == AUDIT_STATE_RECORD)
+ *key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
+ /* As long as e->lock is held, e is valid and
+ * its value is not stale */
+ return e;
+ }
+ }
+ rcu_read_unlock();
+ return NULL;
+ }
+
+The ``audit_del_rule()`` function would need to set the ``deleted`` flag under the
+spinlock as follows::
+
+ static inline int audit_del_rule(struct audit_rule *rule,
+ struct list_head *list)
+ {
+ struct audit_entry *e;
+
+ /* No need to use the _rcu iterator here, since this
+ * is the only deletion routine. */
+ list_for_each_entry(e, list, list) {
+ if (!audit_compare_rule(rule, &e->rule)) {
+ spin_lock(&e->lock);
+ list_del_rcu(&e->list);
+ e->deleted = 1;
+ spin_unlock(&e->lock);
+ call_rcu(&e->rcu, audit_free_rule);
+ return 0;
+ }
+ }
+ return -EFAULT; /* No matching rule */
+ }
+
+This too assumes that the caller holds ``audit_filter_mutex``.
+
+Note that this example assumes that entries are only added and deleted.
+Additional mechanism is required to deal correctly with the update-in-place
+performed by audit_upd_rule(). For one thing, audit_upd_rule() would
+need to hold the locks of both the old ``audit_entry`` and its replacement
+while executing the list_replace_rcu().
+
+
+Example 5: Skipping Stale Objects
+---------------------------------
+
+For some use cases, reader performance can be improved by skipping
+stale objects during read-side list traversal, where stale objects
+are those that will be removed and destroyed after one or more grace
+periods. One such example can be found in the timerfd subsystem. When a
+``CLOCK_REALTIME`` clock is reprogrammed (for example due to setting
+of the system time) then all programmed ``timerfds`` that depend on
+this clock get triggered and processes waiting on them are awakened in
+advance of their scheduled expiry. To facilitate this, all such timers
+are added to an RCU-managed ``cancel_list`` when they are setup in
+``timerfd_setup_cancel()``::
+
+ static void timerfd_setup_cancel(struct timerfd_ctx *ctx, int flags)
+ {
+ spin_lock(&ctx->cancel_lock);
+ if ((ctx->clockid == CLOCK_REALTIME ||
+ ctx->clockid == CLOCK_REALTIME_ALARM) &&
+ (flags & TFD_TIMER_ABSTIME) && (flags & TFD_TIMER_CANCEL_ON_SET)) {
+ if (!ctx->might_cancel) {
+ ctx->might_cancel = true;
+ spin_lock(&cancel_lock);
+ list_add_rcu(&ctx->clist, &cancel_list);
+ spin_unlock(&cancel_lock);
+ }
+ } else {
+ __timerfd_remove_cancel(ctx);
+ }
+ spin_unlock(&ctx->cancel_lock);
+ }
+
+When a timerfd is freed (fd is closed), then the ``might_cancel``
+flag of the timerfd object is cleared, the object removed from the
+``cancel_list`` and destroyed, as shown in this simplified and inlined
+version of timerfd_release()::
+
+ int timerfd_release(struct inode *inode, struct file *file)
+ {
+ struct timerfd_ctx *ctx = file->private_data;
+
+ spin_lock(&ctx->cancel_lock);
+ if (ctx->might_cancel) {
+ ctx->might_cancel = false;
+ spin_lock(&cancel_lock);
+ list_del_rcu(&ctx->clist);
+ spin_unlock(&cancel_lock);
+ }
+ spin_unlock(&ctx->cancel_lock);
+
+ if (isalarm(ctx))
+ alarm_cancel(&ctx->t.alarm);
+ else
+ hrtimer_cancel(&ctx->t.tmr);
+ kfree_rcu(ctx, rcu);
+ return 0;
+ }
+
+If the ``CLOCK_REALTIME`` clock is set, for example by a time server, the
+hrtimer framework calls ``timerfd_clock_was_set()`` which walks the
+``cancel_list`` and wakes up processes waiting on the timerfd. While iterating
+the ``cancel_list``, the ``might_cancel`` flag is consulted to skip stale
+objects::
+
+ void timerfd_clock_was_set(void)
+ {
+ ktime_t moffs = ktime_mono_to_real(0);
+ struct timerfd_ctx *ctx;
+ unsigned long flags;
+
+ rcu_read_lock();
+ list_for_each_entry_rcu(ctx, &cancel_list, clist) {
+ if (!ctx->might_cancel)
+ continue;
+ spin_lock_irqsave(&ctx->wqh.lock, flags);
+ if (ctx->moffs != moffs) {
+ ctx->moffs = KTIME_MAX;
+ ctx->ticks++;
+ wake_up_locked_poll(&ctx->wqh, EPOLLIN);
+ }
+ spin_unlock_irqrestore(&ctx->wqh.lock, flags);
+ }
+ rcu_read_unlock();
+ }
+
+The key point is that because RCU-protected traversal of the
+``cancel_list`` happens concurrently with object addition and removal,
+sometimes the traversal can access an object that has been removed from
+the list. In this example, a flag is used to skip such objects.
+
+
+Summary
+-------
+
+Read-mostly list-based data structures that can tolerate stale data are
+the most amenable to use of RCU. The simplest case is where entries are
+either added or deleted from the data structure (or atomically modified
+in place), but non-atomic in-place modifications can be handled by making
+a copy, updating the copy, then replacing the original with the copy.
+If stale data cannot be tolerated, then a *deleted* flag may be used
+in conjunction with a per-entry spinlock in order to allow the search
+function to reject newly deleted data.
+
+.. _quick_quiz_answer:
+
+Answer to Quick Quiz:
+ For the deleted-flag technique to be helpful, why is it necessary
+ to hold the per-entry lock while returning from the search function?
+
+ If the search function drops the per-entry lock before returning,
+ then the caller will be processing stale data in any case. If it
+ is really OK to be processing stale data, then you don't need a
+ *deleted* flag. If processing stale data really is a problem,
+ then you need to hold the per-entry lock across all of the code
+ that uses the value that was returned.
+
+:ref:`Back to Quick Quiz <quick_quiz>`
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
deleted file mode 100644
index adb5a3782846..000000000000
--- a/Documentation/RCU/listRCU.txt
+++ /dev/null
@@ -1,315 +0,0 @@
-Using RCU to Protect Read-Mostly Linked Lists
-
-
-One of the best applications of RCU is to protect read-mostly linked lists
-("struct list_head" in list.h). One big advantage of this approach
-is that all of the required memory barriers are included for you in
-the list macros. This document describes several applications of RCU,
-with the best fits first.
-
-
-Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
-
-The best applications are cases where, if reader-writer locking were
-used, the read-side lock would be dropped before taking any action
-based on the results of the search. The most celebrated example is
-the routing table. Because the routing table is tracking the state of
-equipment outside of the computer, it will at times contain stale data.
-Therefore, once the route has been computed, there is no need to hold
-the routing table static during transmission of the packet. After all,
-you can hold the routing table static all you want, but that won't keep
-the external Internet from changing, and it is the state of the external
-Internet that really matters. In addition, routing entries are typically
-added or deleted, rather than being modified in place.
-
-A straightforward example of this use of RCU may be found in the
-system-call auditing support. For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
-
- static enum audit_state audit_filter_task(struct task_struct *tsk)
- {
- struct audit_entry *e;
- enum audit_state state;
-
- read_lock(&auditsc_lock);
- /* Note: audit_netlink_sem held by caller. */
- list_for_each_entry(e, &audit_tsklist, list) {
- if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
- read_unlock(&auditsc_lock);
- return state;
- }
- }
- read_unlock(&auditsc_lock);
- return AUDIT_BUILD_CONTEXT;
- }
-
-Here the list is searched under the lock, but the lock is dropped before
-the corresponding value is returned. By the time that this value is acted
-on, the list may well have been modified. This makes sense, since if
-you are turning auditing off, it is OK to audit a few extra system calls.
-
-This means that RCU can be easily applied to the read side, as follows:
-
- static enum audit_state audit_filter_task(struct task_struct *tsk)
- {
- struct audit_entry *e;
- enum audit_state state;
-
- rcu_read_lock();
- /* Note: audit_netlink_sem held by caller. */
- list_for_each_entry_rcu(e, &audit_tsklist, list) {
- if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
- rcu_read_unlock();
- return state;
- }
- }
- rcu_read_unlock();
- return AUDIT_BUILD_CONTEXT;
- }
-
-The read_lock() and read_unlock() calls have become rcu_read_lock()
-and rcu_read_unlock(), respectively, and the list_for_each_entry() has
-become list_for_each_entry_rcu(). The _rcu() list-traversal primitives
-insert the read-side memory barriers that are required on DEC Alpha CPUs.
-
-The changes to the update side are also straightforward. A reader-writer
-lock might be used as follows for deletion and insertion:
-
- static inline int audit_del_rule(struct audit_rule *rule,
- struct list_head *list)
- {
- struct audit_entry *e;
-
- write_lock(&auditsc_lock);
- list_for_each_entry(e, list, list) {
- if (!audit_compare_rule(rule, &e->rule)) {
- list_del(&e->list);
- write_unlock(&auditsc_lock);
- return 0;
- }
- }
- write_unlock(&auditsc_lock);
- return -EFAULT; /* No matching rule */
- }
-
- static inline int audit_add_rule(struct audit_entry *entry,
- struct list_head *list)
- {
- write_lock(&auditsc_lock);
- if (entry->rule.flags & AUDIT_PREPEND) {
- entry->rule.flags &= ~AUDIT_PREPEND;
- list_add(&entry->list, list);
- } else {
- list_add_tail(&entry->list, list);
- }
- write_unlock(&auditsc_lock);
- return 0;
- }
-
-Following are the RCU equivalents for these two functions:
-
- static inline int audit_del_rule(struct audit_rule *rule,
- struct list_head *list)
- {
- struct audit_entry *e;
-
- /* Do not use the _rcu iterator here, since this is the only
- * deletion routine. */
- list_for_each_entry(e, list, list) {
- if (!audit_compare_rule(rule, &e->rule)) {
- list_del_rcu(&e->list);
- call_rcu(&e->rcu, audit_free_rule);
- return 0;
- }
- }
- return -EFAULT; /* No matching rule */
- }
-
- static inline int audit_add_rule(struct audit_entry *entry,
- struct list_head *list)
- {
- if (entry->rule.flags & AUDIT_PREPEND) {
- entry->rule.flags &= ~AUDIT_PREPEND;
- list_add_rcu(&entry->list, list);
- } else {
- list_add_tail_rcu(&entry->list, list);
- }
- return 0;
- }
-
-Normally, the write_lock() and write_unlock() would be replaced by
-a spin_lock() and a spin_unlock(), but in this case, all callers hold
-audit_netlink_sem, so no additional locking is required. The auditsc_lock
-can therefore be eliminated, since use of RCU eliminates the need for
-writers to exclude readers. Normally, the write_lock() calls would
-be converted into spin_lock() calls.
-
-The list_del(), list_add(), and list_add_tail() primitives have been
-replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
-The _rcu() list-manipulation primitives add memory barriers that are
-needed on weakly ordered CPUs (most of them!). The list_del_rcu()
-primitive omits the pointer poisoning debug-assist code that would
-otherwise cause concurrent readers to fail spectacularly.
-
-So, when readers can tolerate stale data and when entries are either added
-or deleted, without in-place modification, it is very easy to use RCU!
-
-
-Example 2: Handling In-Place Updates
-
-The system-call auditing code does not update auditing rules in place.
-However, if it did, reader-writer-locked code to do so might look as
-follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
-
- static inline int audit_upd_rule(struct audit_rule *rule,
- struct list_head *list,
- __u32 newaction,
- __u32 newfield_count)
- {
- struct audit_entry *e;
- struct audit_newentry *ne;
-
- write_lock(&auditsc_lock);
- /* Note: audit_netlink_sem held by caller. */
- list_for_each_entry(e, list, list) {
- if (!audit_compare_rule(rule, &e->rule)) {
- e->rule.action = newaction;
- e->rule.file_count = newfield_count;
- write_unlock(&auditsc_lock);
- return 0;
- }
- }
- write_unlock(&auditsc_lock);
- return -EFAULT; /* No matching rule */
- }
-
-The RCU version creates a copy, updates the copy, then replaces the old
-entry with the newly updated entry. This sequence of actions, allowing
-concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name. The RCU code is as follows:
-
- static inline int audit_upd_rule(struct audit_rule *rule,
- struct list_head *list,
- __u32 newaction,
- __u32 newfield_count)
- {
- struct audit_entry *e;
- struct audit_newentry *ne;
-
- list_for_each_entry(e, list, list) {
- if (!audit_compare_rule(rule, &e->rule)) {
- ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
- if (ne == NULL)
- return -ENOMEM;
- audit_copy_rule(&ne->rule, &e->rule);
- ne->rule.action = newaction;
- ne->rule.file_count = newfield_count;
- list_replace_rcu(&e->list, &ne->list);
- call_rcu(&e->rcu, audit_free_rule);
- return 0;
- }
- }
- return -EFAULT; /* No matching rule */
- }
-
-Again, this assumes that the caller holds audit_netlink_sem. Normally,
-the reader-writer lock would become a spinlock in this sort of code.
-
-
-Example 3: Eliminating Stale Data
-
-The auditing examples above tolerate stale data, as do most algorithms
-that are tracking external state. Because there is a delay from the
-time the external state changes before Linux becomes aware of the change,
-additional RCU-induced staleness is normally not a problem.
-
-However, there are many examples where stale data cannot be tolerated.
-One example in the Linux kernel is the System V IPC (see the ipc_lock()
-function in ipc/util.c). This code checks a "deleted" flag under a
-per-entry spinlock, and, if the "deleted" flag is set, pretends that the
-entry does not exist. For this to be helpful, the search function must
-return holding the per-entry spinlock, as ipc_lock() does in fact do.
-
-Quick Quiz: Why does the search function need to return holding the
- per-entry lock for this deleted-flag technique to be helpful?
-
-If the system-call audit module were to ever need to reject stale data,
-one way to accomplish this would be to add a "deleted" flag and a "lock"
-spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
-
- static enum audit_state audit_filter_task(struct task_struct *tsk)
- {
- struct audit_entry *e;
- enum audit_state state;
-
- rcu_read_lock();
- list_for_each_entry_rcu(e, &audit_tsklist, list) {
- if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
- spin_lock(&e->lock);
- if (e->deleted) {
- spin_unlock(&e->lock);
- rcu_read_unlock();
- return AUDIT_BUILD_CONTEXT;
- }
- rcu_read_unlock();
- return state;
- }
- }
- rcu_read_unlock();
- return AUDIT_BUILD_CONTEXT;
- }
-
-Note that this example assumes that entries are only added and deleted.
-Additional mechanism is required to deal correctly with the
-update-in-place performed by audit_upd_rule(). For one thing,
-audit_upd_rule() would need additional memory barriers to ensure
-that the list_add_rcu() was really executed before the list_del_rcu().
-
-The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
-
- static inline int audit_del_rule(struct audit_rule *rule,
- struct list_head *list)
- {
- struct audit_entry *e;
-
- /* Do not need to use the _rcu iterator here, since this
- * is the only deletion routine. */
- list_for_each_entry(e, list, list) {
- if (!audit_compare_rule(rule, &e->rule)) {
- spin_lock(&e->lock);
- list_del_rcu(&e->list);
- e->deleted = 1;
- spin_unlock(&e->lock);
- call_rcu(&e->rcu, audit_free_rule);
- return 0;
- }
- }
- return -EFAULT; /* No matching rule */
- }
-
-
-Summary
-
-Read-mostly list-based data structures that can tolerate stale data are
-the most amenable to use of RCU. The simplest case is where entries are
-either added or deleted from the data structure (or atomically modified
-in place), but non-atomic in-place modifications can be handled by making
-a copy, updating the copy, then replacing the original with the copy.
-If stale data cannot be tolerated, then a "deleted" flag may be used
-in conjunction with a per-entry spinlock in order to allow the search
-function to reject newly deleted data.
-
-
-Answer to Quick Quiz
- Why does the search function need to return holding the per-entry
- lock for this deleted-flag technique to be helpful?
-
- If the search function drops the per-entry lock before returning,
- then the caller will be processing stale data in any case. If it
- is really OK to be processing stale data, then you don't need a
- "deleted" flag. If processing stale data really is a problem,
- then you need to hold the per-entry lock across all of the code
- that uses the value that was returned.
diff --git a/Documentation/RCU/lockdep-splat.rst b/Documentation/RCU/lockdep-splat.rst
new file mode 100644
index 000000000000..bcbc4b3c88d7
--- /dev/null
+++ b/Documentation/RCU/lockdep-splat.rst
@@ -0,0 +1,115 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+Lockdep-RCU Splat
+=================
+
+Lockdep-RCU was added to the Linux kernel in early 2010
+(http://lwn.net/Articles/371986/). This facility checks for some common
+misuses of the RCU API, most notably using one of the rcu_dereference()
+family to access an RCU-protected pointer without the proper protection.
+When such misuse is detected, an lockdep-RCU splat is emitted.
+
+The usual cause of a lockdep-RCU splat is someone accessing an
+RCU-protected data structure without either (1) being in the right kind of
+RCU read-side critical section or (2) holding the right update-side lock.
+This problem can therefore be serious: it might result in random memory
+overwriting or worse. There can of course be false positives, this
+being the real world and all that.
+
+So let's look at an example RCU lockdep splat from 3.0-rc5, one that
+has long since been fixed::
+
+ =============================
+ WARNING: suspicious RCU usage
+ -----------------------------
+ block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
+
+other info that might help us debug this::
+
+ rcu_scheduler_active = 1, debug_locks = 0
+ 3 locks held by scsi_scan_6/1552:
+ #0: (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>]
+ scsi_scan_host_selected+0x5a/0x150
+ #1: (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>]
+ elevator_exit+0x22/0x60
+ #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>]
+ cfq_exit_queue+0x43/0x190
+
+ stack backtrace:
+ Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17
+ Call Trace:
+ [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0
+ [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120
+ [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190
+ [<ffffffff812a5046>] elevator_exit+0x36/0x60
+ [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60
+ [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10
+ [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0
+ [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10
+ [<ffffffff817da069>] ? error_exit+0x29/0xb0
+ [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80
+ [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680
+ [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c
+ [<ffffffff817da069>] ? error_exit+0x29/0xb0
+ [<ffffffff812bcc60>] ? kobject_del+0x40/0x40
+ [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0
+ [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150
+ [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90
+ [<ffffffff8145f170>] do_scan_async+0x20/0x160
+ [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90
+ [<ffffffff810975b6>] kthread+0xa6/0xb0
+ [<ffffffff817db154>] kernel_thread_helper+0x4/0x10
+ [<ffffffff81066430>] ? finish_task_switch+0x80/0x110
+ [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe
+ [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70
+ [<ffffffff817db150>] ? gs_change+0xb/0xb
+
+Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows::
+
+ if (rcu_dereference(ioc->ioc_data) == cic) {
+
+This form says that it must be in a plain vanilla RCU read-side critical
+section, but the "other info" list above shows that this is not the
+case. Instead, we hold three locks, one of which might be RCU related.
+And maybe that lock really does protect this reference. If so, the fix
+is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to
+take the struct request_queue "q" from cfq_exit_queue() as an argument,
+which would permit us to invoke rcu_dereference_protected as follows::
+
+ if (rcu_dereference_protected(ioc->ioc_data,
+ lockdep_is_held(&q->queue_lock)) == cic) {
+
+With this change, there would be no lockdep-RCU splat emitted if this
+code was invoked either from within an RCU read-side critical section
+or with the ->queue_lock held. In particular, this would have suppressed
+the above lockdep-RCU splat because ->queue_lock is held (see #2 in the
+list above).
+
+On the other hand, perhaps we really do need an RCU read-side critical
+section. In this case, the critical section must span the use of the
+return value from rcu_dereference(), or at least until there is some
+reference count incremented or some such. One way to handle this is to
+add rcu_read_lock() and rcu_read_unlock() as follows::
+
+ rcu_read_lock();
+ if (rcu_dereference(ioc->ioc_data) == cic) {
+ spin_lock(&ioc->lock);
+ rcu_assign_pointer(ioc->ioc_data, NULL);
+ spin_unlock(&ioc->lock);
+ }
+ rcu_read_unlock();
+
+With this change, the rcu_dereference() is always within an RCU
+read-side critical section, which again would have suppressed the
+above lockdep-RCU splat.
+
+But in this particular case, we don't actually dereference the pointer
+returned from rcu_dereference(). Instead, that pointer is just compared
+to the cic pointer, which means that the rcu_dereference() can be replaced
+by rcu_access_pointer() as follows::
+
+ if (rcu_access_pointer(ioc->ioc_data) == cic) {
+
+Because it is legal to invoke rcu_access_pointer() without protection,
+this change would also suppress the above lockdep-RCU splat.
diff --git a/Documentation/RCU/lockdep-splat.txt b/Documentation/RCU/lockdep-splat.txt
deleted file mode 100644
index bf9061142827..000000000000
--- a/Documentation/RCU/lockdep-splat.txt
+++ /dev/null
@@ -1,110 +0,0 @@
-Lockdep-RCU was added to the Linux kernel in early 2010
-(http://lwn.net/Articles/371986/). This facility checks for some common
-misuses of the RCU API, most notably using one of the rcu_dereference()
-family to access an RCU-protected pointer without the proper protection.
-When such misuse is detected, an lockdep-RCU splat is emitted.
-
-The usual cause of a lockdep-RCU slat is someone accessing an
-RCU-protected data structure without either (1) being in the right kind of
-RCU read-side critical section or (2) holding the right update-side lock.
-This problem can therefore be serious: it might result in random memory
-overwriting or worse. There can of course be false positives, this
-being the real world and all that.
-
-So let's look at an example RCU lockdep splat from 3.0-rc5, one that
-has long since been fixed:
-
-===============================
-[ INFO: suspicious RCU usage. ]
--------------------------------
-block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
-
-other info that might help us debug this:
-
-
-rcu_scheduler_active = 1, debug_locks = 0
-3 locks held by scsi_scan_6/1552:
- #0: (&shost->scan_mutex){+.+.+.}, at: [<ffffffff8145efca>]
-scsi_scan_host_selected+0x5a/0x150
- #1: (&eq->sysfs_lock){+.+...}, at: [<ffffffff812a5032>]
-elevator_exit+0x22/0x60
- #2: (&(&q->__queue_lock)->rlock){-.-...}, at: [<ffffffff812b6233>]
-cfq_exit_queue+0x43/0x190
-
-stack backtrace:
-Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17
-Call Trace:
- [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0
- [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120
- [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190
- [<ffffffff812a5046>] elevator_exit+0x36/0x60
- [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60
- [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10
- [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0
- [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10
- [<ffffffff817da069>] ? error_exit+0x29/0xb0
- [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80
- [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680
- [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c
- [<ffffffff817da069>] ? error_exit+0x29/0xb0
- [<ffffffff812bcc60>] ? kobject_del+0x40/0x40
- [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0
- [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150
- [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90
- [<ffffffff8145f170>] do_scan_async+0x20/0x160
- [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90
- [<ffffffff810975b6>] kthread+0xa6/0xb0
- [<ffffffff817db154>] kernel_thread_helper+0x4/0x10
- [<ffffffff81066430>] ? finish_task_switch+0x80/0x110
- [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe
- [<ffffffff81097510>] ? __init_kthread_worker+0x70/0x70
- [<ffffffff817db150>] ? gs_change+0xb/0xb
-
-Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows:
-
- if (rcu_dereference(ioc->ioc_data) == cic) {
-
-This form says that it must be in a plain vanilla RCU read-side critical
-section, but the "other info" list above shows that this is not the
-case. Instead, we hold three locks, one of which might be RCU related.
-And maybe that lock really does protect this reference. If so, the fix
-is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to
-take the struct request_queue "q" from cfq_exit_queue() as an argument,
-which would permit us to invoke rcu_dereference_protected as follows:
-
- if (rcu_dereference_protected(ioc->ioc_data,
- lockdep_is_held(&q->queue_lock)) == cic) {
-
-With this change, there would be no lockdep-RCU splat emitted if this
-code was invoked either from within an RCU read-side critical section
-or with the ->queue_lock held. In particular, this would have suppressed
-the above lockdep-RCU splat because ->queue_lock is held (see #2 in the
-list above).
-
-On the other hand, perhaps we really do need an RCU read-side critical
-section. In this case, the critical section must span the use of the
-return value from rcu_dereference(), or at least until there is some
-reference count incremented or some such. One way to handle this is to
-add rcu_read_lock() and rcu_read_unlock() as follows:
-
- rcu_read_lock();
- if (rcu_dereference(ioc->ioc_data) == cic) {
- spin_lock(&ioc->lock);
- rcu_assign_pointer(ioc->ioc_data, NULL);
- spin_unlock(&ioc->lock);
- }
- rcu_read_unlock();
-
-With this change, the rcu_dereference() is always within an RCU
-read-side critical section, which again would have suppressed the
-above lockdep-RCU splat.
-
-But in this particular case, we don't actually deference the pointer
-returned from rcu_dereference(). Instead, that pointer is just compared
-to the cic pointer, which means that the rcu_dereference() can be replaced
-by rcu_access_pointer() as follows:
-
- if (rcu_access_pointer(ioc->ioc_data) == cic) {
-
-Because it is legal to invoke rcu_access_pointer() without protection,
-this change would also suppress the above lockdep-RCU splat.
diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst
new file mode 100644
index 000000000000..741b157bbacb
--- /dev/null
+++ b/Documentation/RCU/lockdep.rst
@@ -0,0 +1,119 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+RCU and lockdep checking
+========================
+
+All flavors of RCU have lockdep checking available, so that lockdep is
+aware of when each task enters and leaves any flavor of RCU read-side
+critical section. Each flavor of RCU is tracked separately (but note
+that this is not the case in 2.6.32 and earlier). This allows lockdep's
+tracking to include RCU state, which can sometimes help when debugging
+deadlocks and the like.
+
+In addition, RCU provides the following primitives that check lockdep's
+state::
+
+ rcu_read_lock_held() for normal RCU.
+ rcu_read_lock_bh_held() for RCU-bh.
+ rcu_read_lock_sched_held() for RCU-sched.
+ rcu_read_lock_any_held() for any of normal RCU, RCU-bh, and RCU-sched.
+ srcu_read_lock_held() for SRCU.
+ rcu_read_lock_trace_held() for RCU Tasks Trace.
+
+These functions are conservative, and will therefore return 1 if they
+aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
+This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
+positives when lockdep is disabled.
+
+In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
+checking of rcu_dereference() primitives:
+
+ rcu_dereference(p):
+ Check for RCU read-side critical section.
+ rcu_dereference_bh(p):
+ Check for RCU-bh read-side critical section.
+ rcu_dereference_sched(p):
+ Check for RCU-sched read-side critical section.
+ srcu_dereference(p, sp):
+ Check for SRCU read-side critical section.
+ rcu_dereference_check(p, c):
+ Use explicit check expression "c" along with
+ rcu_read_lock_held(). This is useful in code that is
+ invoked by both RCU readers and updaters.
+ rcu_dereference_bh_check(p, c):
+ Use explicit check expression "c" along with
+ rcu_read_lock_bh_held(). This is useful in code that
+ is invoked by both RCU-bh readers and updaters.
+ rcu_dereference_sched_check(p, c):
+ Use explicit check expression "c" along with
+ rcu_read_lock_sched_held(). This is useful in code that
+ is invoked by both RCU-sched readers and updaters.
+ srcu_dereference_check(p, c):
+ Use explicit check expression "c" along with
+ srcu_read_lock_held(). This is useful in code that
+ is invoked by both SRCU readers and updaters.
+ rcu_dereference_raw(p):
+ Don't check. (Use sparingly, if at all.)
+ rcu_dereference_raw_check(p):
+ Don't do lockdep at all. (Use sparingly, if at all.)
+ rcu_dereference_protected(p, c):
+ Use explicit check expression "c", and omit all barriers
+ and compiler constraints. This is useful when the data
+ structure cannot change, for example, in code that is
+ invoked only by updaters.
+ rcu_access_pointer(p):
+ Return the value of the pointer and omit all barriers,
+ but retain the compiler constraints that prevent duplicating
+ or coalescing. This is useful when testing the
+ value of the pointer itself, for example, against NULL.
+
+The rcu_dereference_check() check expression can be any boolean
+expression, but would normally include a lockdep expression. For a
+moderately ornate example, consider the following::
+
+ file = rcu_dereference_check(fdt->fd[fd],
+ lockdep_is_held(&files->file_lock) ||
+ atomic_read(&files->count) == 1);
+
+This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
+and, if CONFIG_PROVE_RCU is configured, verifies that this expression
+is used in:
+
+1. An RCU read-side critical section (implicit), or
+2. with files->file_lock held, or
+3. on an unshared files_struct.
+
+In case (1), the pointer is picked up in an RCU-safe manner for vanilla
+RCU read-side critical sections, in case (2) the ->file_lock prevents
+any change from taking place, and finally, in case (3) the current task
+is the only task accessing the file_struct, again preventing any change
+from taking place. If the above statement was invoked only from updater
+code, it could instead be written as follows::
+
+ file = rcu_dereference_protected(fdt->fd[fd],
+ lockdep_is_held(&files->file_lock) ||
+ atomic_read(&files->count) == 1);
+
+This would verify cases #2 and #3 above, and furthermore lockdep would
+complain even if this was used in an RCU read-side critical section unless
+one of these two cases held. Because rcu_dereference_protected() omits
+all barriers and compiler constraints, it generates better code than do
+the other flavors of rcu_dereference(). On the other hand, it is illegal
+to use rcu_dereference_protected() if either the RCU-protected pointer
+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 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.
+
+For example, the workqueue for_each_pwq() macro is intended to be used
+either within an RCU read-side critical section or with wq->mutex held.
+It is thus implemented as follows::
+
+ #define for_each_pwq(pwq, wq)
+ list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
+ lock_is_held(&(wq->mutex).dep_map))
diff --git a/Documentation/RCU/lockdep.txt b/Documentation/RCU/lockdep.txt
deleted file mode 100644
index cd83d2348fef..000000000000
--- a/Documentation/RCU/lockdep.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-RCU and lockdep checking
-
-All flavors of RCU have lockdep checking available, so that lockdep is
-aware of when each task enters and leaves any flavor of RCU read-side
-critical section. Each flavor of RCU is tracked separately (but note
-that this is not the case in 2.6.32 and earlier). This allows lockdep's
-tracking to include RCU state, which can sometimes help when debugging
-deadlocks and the like.
-
-In addition, RCU provides the following primitives that check lockdep's
-state:
-
- rcu_read_lock_held() for normal RCU.
- rcu_read_lock_bh_held() for RCU-bh.
- rcu_read_lock_sched_held() for RCU-sched.
- srcu_read_lock_held() for SRCU.
-
-These functions are conservative, and will therefore return 1 if they
-aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set).
-This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false
-positives when lockdep is disabled.
-
-In addition, a separate kernel config parameter CONFIG_PROVE_RCU enables
-checking of rcu_dereference() primitives:
-
- rcu_dereference(p):
- Check for RCU read-side critical section.
- rcu_dereference_bh(p):
- Check for RCU-bh read-side critical section.
- rcu_dereference_sched(p):
- Check for RCU-sched read-side critical section.
- srcu_dereference(p, sp):
- Check for SRCU read-side critical section.
- rcu_dereference_check(p, c):
- Use explicit check expression "c" along with
- rcu_read_lock_held(). This is useful in code that is
- invoked by both RCU readers and updaters.
- rcu_dereference_bh_check(p, c):
- Use explicit check expression "c" along with
- rcu_read_lock_bh_held(). This is useful in code that
- is invoked by both RCU-bh readers and updaters.
- rcu_dereference_sched_check(p, c):
- Use explicit check expression "c" along with
- rcu_read_lock_sched_held(). This is useful in code that
- is invoked by both RCU-sched readers and updaters.
- srcu_dereference_check(p, c):
- Use explicit check expression "c" along with
- srcu_read_lock_held()(). This is useful in code that
- is invoked by both SRCU readers and updaters.
- rcu_dereference_index_check(p, c):
- Use explicit check expression "c", but the caller
- must supply one of the rcu_read_lock_held() functions.
- This is useful in code that uses RCU-protected arrays
- that is invoked by both RCU readers and updaters.
- rcu_dereference_raw(p):
- Don't check. (Use sparingly, if at all.)
- rcu_dereference_protected(p, c):
- Use explicit check expression "c", and omit all barriers
- and compiler constraints. This is useful when the data
- structure cannot change, for example, in code that is
- invoked only by updaters.
- rcu_access_pointer(p):
- Return the value of the pointer and omit all barriers,
- but retain the compiler constraints that prevent duplicating
- or coalescsing. This is useful when when testing the
- value of the pointer itself, for example, against NULL.
- rcu_access_index(idx):
- Return the value of the index and omit all barriers, but
- retain the compiler constraints that prevent duplicating
- or coalescsing. This is useful when when testing the
- value of the index itself, for example, against -1.
-
-The rcu_dereference_check() check expression can be any boolean
-expression, but would normally include a lockdep expression. However,
-any boolean expression can be used. For a moderately ornate example,
-consider the following:
-
- file = rcu_dereference_check(fdt->fd[fd],
- lockdep_is_held(&files->file_lock) ||
- atomic_read(&files->count) == 1);
-
-This expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner,
-and, if CONFIG_PROVE_RCU is configured, verifies that this expression
-is used in:
-
-1. An RCU read-side critical section (implicit), or
-2. with files->file_lock held, or
-3. on an unshared files_struct.
-
-In case (1), the pointer is picked up in an RCU-safe manner for vanilla
-RCU read-side critical sections, in case (2) the ->file_lock prevents
-any change from taking place, and finally, in case (3) the current task
-is the only task accessing the file_struct, again preventing any change
-from taking place. If the above statement was invoked only from updater
-code, it could instead be written as follows:
-
- file = rcu_dereference_protected(fdt->fd[fd],
- lockdep_is_held(&files->file_lock) ||
- atomic_read(&files->count) == 1);
-
-This would verify cases #2 and #3 above, and furthermore lockdep would
-complain if this was used in an RCU read-side critical section unless one
-of these two cases held. Because rcu_dereference_protected() omits all
-barriers and compiler constraints, it generates better code than do the
-other flavors of rcu_dereference(). On the other hand, it is illegal
-to use rcu_dereference_protected() if either the RCU-protected pointer
-or the RCU-protected data that it points to can change concurrently.
-
-There are currently only "universal" versions of the rcu_assign_pointer()
-and RCU list-/tree-traversal primitives, which do not (yet) check for
-being in an RCU read-side critical section. In the future, separate
-versions of these primitives might be created.
diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
new file mode 100644
index 000000000000..bf6617b330a7
--- /dev/null
+++ b/Documentation/RCU/rcu.rst
@@ -0,0 +1,93 @@
+.. _rcu_doc:
+
+RCU Concepts
+============
+
+The basic idea behind RCU (read-copy update) is to split destructive
+operations into two parts, one that prevents anyone from seeing the data
+item being destroyed, and one that actually carries out the destruction.
+A "grace period" must elapse between the two parts, and this grace period
+must be long enough that any readers accessing the item being deleted have
+since dropped their references. For example, an RCU-protected deletion
+from a linked list would first remove the item from the list, wait for
+a grace period to elapse, then free the element. See listRCU.rst for more
+information on using RCU with linked lists.
+
+Frequently Asked Questions
+--------------------------
+
+- Why would anyone want to use RCU?
+
+ The advantage of RCU's two-part approach is that RCU readers need
+ not acquire any locks, perform any atomic instructions, write to
+ shared memory, or (on CPUs other than Alpha) execute any memory
+ barriers. The fact that these operations are quite expensive
+ on modern CPUs is what gives RCU its performance advantages
+ in read-mostly situations. The fact that RCU readers need not
+ acquire locks can also greatly simplify deadlock-avoidance code.
+
+- How can the updater tell when a grace period has completed
+ if the RCU readers give no indication when they are done?
+
+ Just as with spinlocks, RCU readers are not permitted to
+ block, switch to user-mode execution, or enter the idle loop.
+ Therefore, as soon as a CPU is seen passing through any of these
+ three states, we know that that CPU has exited any previous RCU
+ read-side critical sections. So, if we remove an item from a
+ linked list, and then wait until all CPUs have switched context,
+ executed in user mode, or executed in the idle loop, we can
+ safely free up that item.
+
+ Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+ same effect, but require that the readers manipulate CPU-local
+ counters. These counters allow limited types of blocking within
+ RCU read-side critical sections. SRCU also uses CPU-local
+ counters, and permits general blocking within RCU read-side
+ critical sections. These variants of RCU detect grace periods
+ by sampling these counters.
+
+- If I am running on a uniprocessor kernel, which can only do one
+ thing at a time, why should I wait for a grace period?
+
+ See UP.rst for more information.
+
+- How can I see where RCU is currently used in the Linux kernel?
+
+ Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+ "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+ "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+ "synchronize_srcu", and the other RCU primitives. Or grab one
+ of the cscope databases from:
+
+ (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
+
+- What guidelines should I follow when writing code that uses RCU?
+
+ See checklist.rst.
+
+- Why the name "RCU"?
+
+ "RCU" stands for "read-copy update".
+ listRCU.rst has more information on where this name came from, search
+ for "read-copy update" to find it.
+
+- I hear that RCU is patented? What is with that?
+
+ Yes, it is. There are several known patents related to RCU,
+ search for the string "Patent" in Documentation/RCU/RTFP.txt to find them.
+ Of these, one was allowed to lapse by the assignee, and the
+ others have been contributed to the Linux kernel under GPL.
+ Many (but not all) have long since expired.
+ There are now also LGPL implementations of user-level RCU
+ available (https://liburcu.org/).
+
+- I hear that RCU needs work in order to support realtime kernels?
+
+ Realtime-friendly RCU are enabled via the CONFIG_PREEMPTION
+ kernel configuration parameter.
+
+- Where can I find more information on RCU?
+
+ See the Documentation/RCU/RTFP.txt file.
+ Or point your browser at (https://docs.google.com/document/d/1X0lThx8OK0ZgLMqVoXiR4ZrGURHrXK6NyLRbeXe3Xac/edit)
+ or (https://docs.google.com/document/d/1GCdQC8SDbb54W1shjEXqGZ0Rq8a6kIeYutdSIajfpLA/edit?usp=sharing).
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
deleted file mode 100644
index 745f429fda79..000000000000
--- a/Documentation/RCU/rcu.txt
+++ /dev/null
@@ -1,96 +0,0 @@
-RCU Concepts
-
-
-The basic idea behind RCU (read-copy update) is to split destructive
-operations into two parts, one that prevents anyone from seeing the data
-item being destroyed, and one that actually carries out the destruction.
-A "grace period" must elapse between the two parts, and this grace period
-must be long enough that any readers accessing the item being deleted have
-since dropped their references. For example, an RCU-protected deletion
-from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element. See the listRCU.txt
-file for more information on using RCU with linked lists.
-
-
-Frequently Asked Questions
-
-o Why would anyone want to use RCU?
-
- The advantage of RCU's two-part approach is that RCU readers need
- not acquire any locks, perform any atomic instructions, write to
- shared memory, or (on CPUs other than Alpha) execute any memory
- barriers. The fact that these operations are quite expensive
- on modern CPUs is what gives RCU its performance advantages
- in read-mostly situations. The fact that RCU readers need not
- acquire locks can also greatly simplify deadlock-avoidance code.
-
-o How can the updater tell when a grace period has completed
- if the RCU readers give no indication when they are done?
-
- Just as with spinlocks, RCU readers are not permitted to
- block, switch to user-mode execution, or enter the idle loop.
- Therefore, as soon as a CPU is seen passing through any of these
- three states, we know that that CPU has exited any previous RCU
- read-side critical sections. So, if we remove an item from a
- linked list, and then wait until all CPUs have switched context,
- executed in user mode, or executed in the idle loop, we can
- safely free up that item.
-
- Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
- same effect, but require that the readers manipulate CPU-local
- counters. These counters allow limited types of blocking within
- RCU read-side critical sections. SRCU also uses CPU-local
- counters, and permits general blocking within RCU read-side
- critical sections. These variants of RCU detect grace periods
- by sampling these counters.
-
-o If I am running on a uniprocessor kernel, which can only do one
- thing at a time, why should I wait for a grace period?
-
- See the UP.txt file in this directory.
-
-o How can I see where RCU is currently used in the Linux kernel?
-
- Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
- "rcu_read_lock_bh", "rcu_read_unlock_bh", "call_rcu_bh",
- "srcu_read_lock", "srcu_read_unlock", "synchronize_rcu",
- "synchronize_net", "synchronize_srcu", and the other RCU
- primitives. Or grab one of the cscope databases from:
-
- http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
-
-o What guidelines should I follow when writing code that uses RCU?
-
- See the checklist.txt file in this directory.
-
-o Why the name "RCU"?
-
- "RCU" stands for "read-copy update". The file listRCU.txt has
- more information on where this name came from, search for
- "read-copy update" to find it.
-
-o I hear that RCU is patented? What is with that?
-
- Yes, it is. There are several known patents related to RCU,
- search for the string "Patent" in RTFP.txt to find them.
- Of these, one was allowed to lapse by the assignee, and the
- others have been contributed to the Linux kernel under GPL.
- There are now also LGPL implementations of user-level RCU
- available (http://lttng.org/?q=node/18).
-
-o I hear that RCU needs work in order to support realtime kernels?
-
- This work is largely completed. Realtime-friendly RCU can be
- enabled via the CONFIG_PREEMPT_RCU kernel configuration
- parameter. However, work is in progress for enabling priority
- boosting of preempted RCU read-side critical sections. This is
- needed if you have CPU-bound realtime threads.
-
-o Where can I find more information on RCU?
-
- See the RTFP.txt file in this directory.
- Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
-
-o What are all these files in this directory?
-
- See 00-INDEX for the list.
diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
new file mode 100644
index 000000000000..2524dcdadde2
--- /dev/null
+++ b/Documentation/RCU/rcu_dereference.rst
@@ -0,0 +1,502 @@
+.. _rcu_dereference_doc:
+
+PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
+===============================================================
+
+Proper care and feeding of address and data dependencies is critically
+important to correct use of things like RCU. To this end, the pointers
+returned from the rcu_dereference() family of primitives carry address and
+data dependencies. These dependencies extend from the rcu_dereference()
+macro's load of the pointer to the later use of that pointer to compute
+either the address of a later memory access (representing an address
+dependency) or the value written by a later memory access (representing
+a data dependency).
+
+Most of the time, these dependencies are preserved, permitting you to
+freely use values from rcu_dereference(). For example, dereferencing
+(prefix "*"), field selection ("->"), assignment ("="), address-of
+("&"), casts, and addition or subtraction of constants all work quite
+naturally and safely. However, because current compilers do not take
+either address or data dependencies into account it is still possible
+to get into trouble.
+
+Follow these rules to preserve the address and data dependencies emanating
+from your calls to rcu_dereference() and friends, thus keeping your RCU
+readers working properly:
+
+- You must use one of the rcu_dereference() family of primitives
+ to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
+ will complain. Worse yet, your code can see random memory-corruption
+ bugs due to games that compilers and DEC Alpha can play.
+ Without one of the rcu_dereference() primitives, compilers
+ can reload the value, and won't your code have fun with two
+ different values for a single pointer! Without rcu_dereference(),
+ DEC Alpha can load a pointer, dereference that pointer, and
+ return data preceding initialization that preceded the store
+ of the pointer. (As noted later, in recent kernels READ_ONCE()
+ also prevents DEC Alpha from playing these tricks.)
+
+ In addition, the volatile cast in rcu_dereference() prevents the
+ compiler from deducing the resulting pointer value. Please see
+ the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"
+ for an example where the compiler can in fact deduce the exact
+ value of the pointer, and thus cause misordering.
+
+- In the special case where data is added but is never removed
+ while readers are accessing the structure, READ_ONCE() may be used
+ instead of rcu_dereference(). In this case, use of READ_ONCE()
+ takes on the role of the lockless_dereference() primitive that
+ was removed in v4.15.
+
+- You are only permitted to use rcu_dereference() on pointer values.
+ The compiler simply knows too much about integral values to
+ trust it to carry dependencies through integer operations.
+ There are a very few exceptions, namely that you can temporarily
+ cast the pointer to uintptr_t in order to:
+
+ - Set bits and clear bits down in the must-be-zero low-order
+ bits of that pointer. This clearly means that the pointer
+ must have alignment constraints, for example, this does
+ *not* work in general for char* pointers.
+
+ - XOR bits to translate pointers, as is done in some
+ classic buddy-allocator algorithms.
+
+ It is important to cast the value back to pointer before
+ doing much of anything else with it.
+
+- Avoid cancellation when using the "+" and "-" infix arithmetic
+ operators. For example, for a given variable "x", avoid
+ "(x-(uintptr_t)x)" for char* pointers. The compiler is within its
+ rights to substitute zero for this sort of expression, so that
+ subsequent accesses no longer depend on the rcu_dereference(),
+ again possibly resulting in bugs due to misordering.
+
+ Of course, if "p" is a pointer from rcu_dereference(), and "a"
+ and "b" are integers that happen to be equal, the expression
+ "p+a-b" is safe because its value still necessarily depends on
+ the rcu_dereference(), thus maintaining proper ordering.
+
+- If you are using RCU to protect JITed functions, so that the
+ "()" function-invocation operator is applied to a value obtained
+ (directly or indirectly) from rcu_dereference(), you may need to
+ interact directly with the hardware to flush instruction caches.
+ This issue arises on some systems when a newly JITed function is
+ using the same memory that was used by an earlier JITed function.
+
+- Do not use the results from relational operators ("==", "!=",
+ ">", ">=", "<", or "<=") when dereferencing. For example,
+ the following (quite strange) code is buggy::
+
+ int *p;
+ int *q;
+
+ ...
+
+ p = rcu_dereference(gp)
+ q = &global_q;
+ q += p > &oom_p;
+ r1 = *q; /* BUGGY!!! */
+
+ As before, the reason this is buggy is that relational operators
+ are often compiled using branches. And as before, although
+ weak-memory machines such as ARM or PowerPC do order stores
+ after such branches, but can speculate loads, which can again
+ result in misordering bugs.
+
+- Be very careful about comparing pointers obtained from
+ rcu_dereference() against non-NULL values. As Linus Torvalds
+ explained, if the two pointers are equal, the compiler could
+ substitute the pointer you are comparing against for the pointer
+ obtained from rcu_dereference(). For example::
+
+ p = rcu_dereference(gp);
+ if (p == &default_struct)
+ do_default(p->a);
+
+ Because the compiler now knows that the value of "p" is exactly
+ the address of the variable "default_struct", it is free to
+ transform this code into the following::
+
+ p = rcu_dereference(gp);
+ if (p == &default_struct)
+ do_default(default_struct.a);
+
+ On ARM and Power hardware, the load from "default_struct.a"
+ can now be speculated, such that it might happen before the
+ rcu_dereference(). This could result in bugs due to misordering.
+
+ However, comparisons are OK in the following cases:
+
+ - The comparison was against the NULL pointer. If the
+ compiler knows that the pointer is NULL, you had better
+ not be dereferencing it anyway. If the comparison is
+ non-equal, the compiler is none the wiser. Therefore,
+ it is safe to compare pointers from rcu_dereference()
+ against NULL pointers.
+
+ - The pointer is never dereferenced after being compared.
+ Since there are no subsequent dereferences, the compiler
+ cannot use anything it learned from the comparison
+ to reorder the non-existent subsequent dereferences.
+ This sort of comparison occurs frequently when scanning
+ RCU-protected circular linked lists.
+
+ Note that if the pointer comparison is done outside
+ of an RCU read-side critical section, and the pointer
+ is never dereferenced, rcu_access_pointer() should be
+ used in place of rcu_dereference(). In most cases,
+ it is best to avoid accidental dereferences by testing
+ the rcu_access_pointer() return value directly, without
+ assigning it to a variable.
+
+ Within an RCU read-side critical section, there is little
+ reason to use rcu_access_pointer().
+
+ - The comparison is against a pointer that references memory
+ that was initialized "a long time ago." The reason
+ this is safe is that even if misordering occurs, the
+ misordering will not affect the accesses that follow
+ the comparison. So exactly how long ago is "a long
+ time ago"? Here are some possibilities:
+
+ - Compile time.
+
+ - Boot time.
+
+ - Module-init time for module code.
+
+ - Prior to kthread creation for kthread code.
+
+ - During some prior acquisition of the lock that
+ we now hold.
+
+ - Before mod_timer() time for a timer handler.
+
+ There are many other possibilities involving the Linux
+ kernel's wide array of primitives that cause code to
+ be invoked at a later time.
+
+ - The pointer being compared against also came from
+ rcu_dereference(). In this case, both pointers depend
+ on one rcu_dereference() or another, so you get proper
+ ordering either way.
+
+ That said, this situation can make certain RCU usage
+ bugs more likely to happen. Which can be a good thing,
+ at least if they happen during testing. An example
+ of such an RCU usage bug is shown in the section titled
+ "EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
+
+ - All of the accesses following the comparison are stores,
+ so that a control dependency preserves the needed ordering.
+ That said, it is easy to get control dependencies wrong.
+ Please see the "CONTROL DEPENDENCIES" section of
+ Documentation/memory-barriers.txt for more details.
+
+ - The pointers are not equal *and* the compiler does
+ not have enough information to deduce the value of the
+ pointer. Note that the volatile cast in rcu_dereference()
+ will normally prevent the compiler from knowing too much.
+
+ However, please note that if the compiler knows that the
+ pointer takes on only one of two values, a not-equal
+ comparison will provide exactly the information that the
+ compiler needs to deduce the value of the pointer.
+
+- Disable any value-speculation optimizations that your compiler
+ might provide, especially if you are making use of feedback-based
+ optimizations that take data collected from prior runs. Such
+ value-speculation optimizations reorder operations by design.
+
+ There is one exception to this rule: Value-speculation
+ optimizations that leverage the branch-prediction hardware are
+ safe on strongly ordered systems (such as x86), but not on weakly
+ ordered systems (such as ARM or Power). Choose your compiler
+ command-line options wisely!
+
+
+EXAMPLE OF AMPLIFIED RCU-USAGE BUG
+----------------------------------
+
+Because updaters can run concurrently with RCU readers, RCU readers can
+see stale and/or inconsistent values. If RCU readers need fresh or
+consistent values, which they sometimes do, they need to take proper
+precautions. To see this, consider the following code fragment::
+
+ struct foo {
+ int a;
+ int b;
+ int c;
+ };
+ struct foo *gp1;
+ struct foo *gp2;
+
+ void updater(void)
+ {
+ struct foo *p;
+
+ p = kmalloc(...);
+ if (p == NULL)
+ deal_with_it();
+ p->a = 42; /* Each field in its own cache line. */
+ p->b = 43;
+ p->c = 44;
+ rcu_assign_pointer(gp1, p);
+ p->b = 143;
+ p->c = 144;
+ rcu_assign_pointer(gp2, p);
+ }
+
+ void reader(void)
+ {
+ struct foo *p;
+ struct foo *q;
+ int r1, r2;
+
+ rcu_read_lock();
+ p = rcu_dereference(gp2);
+ if (p == NULL)
+ return;
+ r1 = p->b; /* Guaranteed to get 143. */
+ q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
+ if (p == q) {
+ /* The compiler decides that q->c is same as p->c. */
+ r2 = p->c; /* Could get 44 on weakly order system. */
+ } else {
+ r2 = p->c - r1; /* Unconditional access to p->c. */
+ }
+ rcu_read_unlock();
+ do_something_with(r1, r2);
+ }
+
+You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
+but you should not be. After all, the updater might have been invoked
+a second time between the time reader() loaded into "r1" and the time
+that it loaded into "r2". The fact that this same result can occur due
+to some reordering from the compiler and CPUs is beside the point.
+
+But suppose that the reader needs a consistent view?
+
+Then one approach is to use locking, for example, as follows::
+
+ struct foo {
+ int a;
+ int b;
+ int c;
+ spinlock_t lock;
+ };
+ struct foo *gp1;
+ struct foo *gp2;
+
+ void updater(void)
+ {
+ struct foo *p;
+
+ p = kmalloc(...);
+ if (p == NULL)
+ deal_with_it();
+ spin_lock(&p->lock);
+ p->a = 42; /* Each field in its own cache line. */
+ p->b = 43;
+ p->c = 44;
+ spin_unlock(&p->lock);
+ rcu_assign_pointer(gp1, p);
+ spin_lock(&p->lock);
+ p->b = 143;
+ p->c = 144;
+ spin_unlock(&p->lock);
+ rcu_assign_pointer(gp2, p);
+ }
+
+ void reader(void)
+ {
+ struct foo *p;
+ struct foo *q;
+ int r1, r2;
+
+ rcu_read_lock();
+ p = rcu_dereference(gp2);
+ if (p == NULL)
+ return;
+ spin_lock(&p->lock);
+ r1 = p->b; /* Guaranteed to get 143. */
+ q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
+ if (p == q) {
+ /* The compiler decides that q->c is same as p->c. */
+ r2 = p->c; /* Locking guarantees r2 == 144. */
+ } else {
+ spin_lock(&q->lock);
+ r2 = q->c - r1;
+ spin_unlock(&q->lock);
+ }
+ rcu_read_unlock();
+ spin_unlock(&p->lock);
+ do_something_with(r1, r2);
+ }
+
+As always, use the right tool for the job!
+
+
+EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH
+-----------------------------------------
+
+If a pointer obtained from rcu_dereference() compares not-equal to some
+other pointer, the compiler normally has no clue what the value of the
+first pointer might be. This lack of knowledge prevents the compiler
+from carrying out optimizations that otherwise might destroy the ordering
+guarantees that RCU depends on. And the volatile cast in rcu_dereference()
+should prevent the compiler from guessing the value.
+
+But without rcu_dereference(), the compiler knows more than you might
+expect. Consider the following code fragment::
+
+ struct foo {
+ int a;
+ int b;
+ };
+ static struct foo variable1;
+ static struct foo variable2;
+ static struct foo *gp = &variable1;
+
+ void updater(void)
+ {
+ initialize_foo(&variable2);
+ rcu_assign_pointer(gp, &variable2);
+ /*
+ * The above is the only store to gp in this translation unit,
+ * and the address of gp is not exported in any way.
+ */
+ }
+
+ int reader(void)
+ {
+ struct foo *p;
+
+ p = gp;
+ barrier();
+ if (p == &variable1)
+ return p->a; /* Must be variable1.a. */
+ else
+ return p->b; /* Must be variable2.b. */
+ }
+
+Because the compiler can see all stores to "gp", it knows that the only
+possible values of "gp" are "variable1" on the one hand and "variable2"
+on the other. The comparison in reader() therefore tells the compiler
+the exact value of "p" even in the not-equals case. This allows the
+compiler to make the return values independent of the load from "gp",
+in turn destroying the ordering between this load and the loads of the
+return values. This can result in "p->b" returning pre-initialization
+garbage values on weakly ordered systems.
+
+In short, rcu_dereference() is *not* optional when you are going to
+dereference the resulting pointer.
+
+
+WHICH MEMBER OF THE rcu_dereference() FAMILY SHOULD YOU USE?
+------------------------------------------------------------
+
+First, please avoid using rcu_dereference_raw() and also please avoid
+using rcu_dereference_check() and rcu_dereference_protected() with a
+second argument with a constant value of 1 (or true, for that matter).
+With that caution out of the way, here is some guidance for which
+member of the rcu_dereference() to use in various situations:
+
+1. If the access needs to be within an RCU read-side critical
+ section, use rcu_dereference(). With the new consolidated
+ RCU flavors, an RCU read-side critical section is entered
+ using rcu_read_lock(), anything that disables bottom halves,
+ anything that disables interrupts, or anything that disables
+ preemption. Please note that spinlock critical sections
+ are also implied RCU read-side critical sections, even when
+ they are preemptible, as they are in kernels built with
+ CONFIG_PREEMPT_RT=y.
+
+2. If the access might be within an RCU read-side critical section
+ on the one hand, or protected by (say) my_lock on the other,
+ use rcu_dereference_check(), for example::
+
+ p1 = rcu_dereference_check(p->rcu_protected_pointer,
+ lockdep_is_held(&my_lock));
+
+
+3. If the access might be within an RCU read-side critical section
+ on the one hand, or protected by either my_lock or your_lock on
+ the other, again use rcu_dereference_check(), for example::
+
+ p1 = rcu_dereference_check(p->rcu_protected_pointer,
+ lockdep_is_held(&my_lock) ||
+ lockdep_is_held(&your_lock));
+
+4. If the access is on the update side, so that it is always protected
+ by my_lock, use rcu_dereference_protected()::
+
+ p1 = rcu_dereference_protected(p->rcu_protected_pointer,
+ lockdep_is_held(&my_lock));
+
+ This can be extended to handle multiple locks as in #3 above,
+ and both can be extended to check other conditions as well.
+
+5. If the protection is supplied by the caller, and is thus unknown
+ to this code, that is the rare case when rcu_dereference_raw()
+ is appropriate. In addition, rcu_dereference_raw() might be
+ appropriate when the lockdep expression would be excessively
+ complex, except that a better approach in that case might be to
+ take a long hard look at your synchronization design. Still,
+ there are data-locking cases where any one of a very large number
+ of locks or reference counters suffices to protect the pointer,
+ so rcu_dereference_raw() does have its place.
+
+ However, its place is probably quite a bit smaller than one
+ might expect given the number of uses in the current kernel.
+ Ditto for its synonym, rcu_dereference_check( ... , 1), and
+ its close relative, rcu_dereference_protected(... , 1).
+
+
+SPARSE CHECKING OF RCU-PROTECTED POINTERS
+-----------------------------------------
+
+The sparse static-analysis tool checks for non-RCU access to RCU-protected
+pointers, which can result in "interesting" bugs due to compiler
+optimizations involving invented loads and perhaps also load tearing.
+For example, suppose someone mistakenly does something like this::
+
+ p = q->rcu_protected_pointer;
+ do_something_with(p->a);
+ do_something_else_with(p->b);
+
+If register pressure is high, the compiler might optimize "p" out
+of existence, transforming the code to something like this::
+
+ do_something_with(q->rcu_protected_pointer->a);
+ do_something_else_with(q->rcu_protected_pointer->b);
+
+This could fatally disappoint your code if q->rcu_protected_pointer
+changed in the meantime. Nor is this a theoretical problem: Exactly
+this sort of bug cost Paul E. McKenney (and several of his innocent
+colleagues) a three-day weekend back in the early 1990s.
+
+Load tearing could of course result in dereferencing a mashup of a pair
+of pointers, which also might fatally disappoint your code.
+
+These problems could have been avoided simply by making the code instead
+read as follows::
+
+ p = rcu_dereference(q->rcu_protected_pointer);
+ do_something_with(p->a);
+ do_something_else_with(p->b);
+
+Unfortunately, these sorts of bugs can be extremely hard to spot during
+review. This is where the sparse tool comes into play, along with the
+"__rcu" marker. If you mark a pointer declaration, whether in a structure
+or as a formal parameter, with "__rcu", which tells sparse to complain if
+this pointer is accessed directly. It will also cause sparse to complain
+if a pointer not marked with "__rcu" is accessed using rcu_dereference()
+and friends. For example, ->rcu_protected_pointer might be declared as
+follows::
+
+ struct foo __rcu *rcu_protected_pointer;
+
+Use of "__rcu" is opt-in. If you choose not to use it, then you should
+ignore the sparse warnings.
diff --git a/Documentation/RCU/rcu_dereference.txt b/Documentation/RCU/rcu_dereference.txt
deleted file mode 100644
index ceb05da5a5ac..000000000000
--- a/Documentation/RCU/rcu_dereference.txt
+++ /dev/null
@@ -1,371 +0,0 @@
-PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
-
-Most of the time, you can use values from rcu_dereference() or one of
-the similar primitives without worries. Dereferencing (prefix "*"),
-field selection ("->"), assignment ("="), address-of ("&"), addition and
-subtraction of constants, and casts all work quite naturally and safely.
-
-It is nevertheless possible to get into trouble with other operations.
-Follow these rules to keep your RCU code working properly:
-
-o You must use one of the rcu_dereference() family of primitives
- to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
- will complain. Worse yet, your code can see random memory-corruption
- bugs due to games that compilers and DEC Alpha can play.
- Without one of the rcu_dereference() primitives, compilers
- can reload the value, and won't your code have fun with two
- different values for a single pointer! Without rcu_dereference(),
- DEC Alpha can load a pointer, dereference that pointer, and
- return data preceding initialization that preceded the store of
- the pointer.
-
- In addition, the volatile cast in rcu_dereference() prevents the
- compiler from deducing the resulting pointer value. Please see
- the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"
- for an example where the compiler can in fact deduce the exact
- value of the pointer, and thus cause misordering.
-
-o Do not use single-element RCU-protected arrays. The compiler
- is within its right to assume that the value of an index into
- such an array must necessarily evaluate to zero. The compiler
- could then substitute the constant zero for the computation, so
- that the array index no longer depended on the value returned
- by rcu_dereference(). If the array index no longer depends
- on rcu_dereference(), then both the compiler and the CPU
- are within their rights to order the array access before the
- rcu_dereference(), which can cause the array access to return
- garbage.
-
-o Avoid cancellation when using the "+" and "-" infix arithmetic
- operators. For example, for a given variable "x", avoid
- "(x-x)". There are similar arithmetic pitfalls from other
- arithmetic operatiors, such as "(x*0)", "(x/(x+1))" or "(x%1)".
- The compiler is within its rights to substitute zero for all of
- these expressions, so that subsequent accesses no longer depend
- on the rcu_dereference(), again possibly resulting in bugs due
- to misordering.
-
- Of course, if "p" is a pointer from rcu_dereference(), and "a"
- and "b" are integers that happen to be equal, the expression
- "p+a-b" is safe because its value still necessarily depends on
- the rcu_dereference(), thus maintaining proper ordering.
-
-o Avoid all-zero operands to the bitwise "&" operator, and
- similarly avoid all-ones operands to the bitwise "|" operator.
- If the compiler is able to deduce the value of such operands,
- it is within its rights to substitute the corresponding constant
- for the bitwise operation. Once again, this causes subsequent
- accesses to no longer depend on the rcu_dereference(), causing
- bugs due to misordering.
-
- Please note that single-bit operands to bitwise "&" can also
- be dangerous. At this point, the compiler knows that the
- resulting value can only take on one of two possible values.
- Therefore, a very small amount of additional information will
- allow the compiler to deduce the exact value, which again can
- result in misordering.
-
-o If you are using RCU to protect JITed functions, so that the
- "()" function-invocation operator is applied to a value obtained
- (directly or indirectly) from rcu_dereference(), you may need to
- interact directly with the hardware to flush instruction caches.
- This issue arises on some systems when a newly JITed function is
- using the same memory that was used by an earlier JITed function.
-
-o Do not use the results from the boolean "&&" and "||" when
- dereferencing. For example, the following (rather improbable)
- code is buggy:
-
- int a[2];
- int index;
- int force_zero_index = 1;
-
- ...
-
- r1 = rcu_dereference(i1)
- r2 = a[r1 && force_zero_index]; /* BUGGY!!! */
-
- The reason this is buggy is that "&&" and "||" are often compiled
- using branches. While weak-memory machines such as ARM or PowerPC
- do order stores after such branches, they can speculate loads,
- which can result in misordering bugs.
-
-o Do not use the results from relational operators ("==", "!=",
- ">", ">=", "<", or "<=") when dereferencing. For example,
- the following (quite strange) code is buggy:
-
- int a[2];
- int index;
- int flip_index = 0;
-
- ...
-
- r1 = rcu_dereference(i1)
- r2 = a[r1 != flip_index]; /* BUGGY!!! */
-
- As before, the reason this is buggy is that relational operators
- are often compiled using branches. And as before, although
- weak-memory machines such as ARM or PowerPC do order stores
- after such branches, but can speculate loads, which can again
- result in misordering bugs.
-
-o Be very careful about comparing pointers obtained from
- rcu_dereference() against non-NULL values. As Linus Torvalds
- explained, if the two pointers are equal, the compiler could
- substitute the pointer you are comparing against for the pointer
- obtained from rcu_dereference(). For example:
-
- p = rcu_dereference(gp);
- if (p == &default_struct)
- do_default(p->a);
-
- Because the compiler now knows that the value of "p" is exactly
- the address of the variable "default_struct", it is free to
- transform this code into the following:
-
- p = rcu_dereference(gp);
- if (p == &default_struct)
- do_default(default_struct.a);
-
- On ARM and Power hardware, the load from "default_struct.a"
- can now be speculated, such that it might happen before the
- rcu_dereference(). This could result in bugs due to misordering.
-
- However, comparisons are OK in the following cases:
-
- o The comparison was against the NULL pointer. If the
- compiler knows that the pointer is NULL, you had better
- not be dereferencing it anyway. If the comparison is
- non-equal, the compiler is none the wiser. Therefore,
- it is safe to compare pointers from rcu_dereference()
- against NULL pointers.
-
- o The pointer is never dereferenced after being compared.
- Since there are no subsequent dereferences, the compiler
- cannot use anything it learned from the comparison
- to reorder the non-existent subsequent dereferences.
- This sort of comparison occurs frequently when scanning
- RCU-protected circular linked lists.
-
- o The comparison is against a pointer that references memory
- that was initialized "a long time ago." The reason
- this is safe is that even if misordering occurs, the
- misordering will not affect the accesses that follow
- the comparison. So exactly how long ago is "a long
- time ago"? Here are some possibilities:
-
- o Compile time.
-
- o Boot time.
-
- o Module-init time for module code.
-
- o Prior to kthread creation for kthread code.
-
- o During some prior acquisition of the lock that
- we now hold.
-
- o Before mod_timer() time for a timer handler.
-
- There are many other possibilities involving the Linux
- kernel's wide array of primitives that cause code to
- be invoked at a later time.
-
- o The pointer being compared against also came from
- rcu_dereference(). In this case, both pointers depend
- on one rcu_dereference() or another, so you get proper
- ordering either way.
-
- That said, this situation can make certain RCU usage
- bugs more likely to happen. Which can be a good thing,
- at least if they happen during testing. An example
- of such an RCU usage bug is shown in the section titled
- "EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
-
- o All of the accesses following the comparison are stores,
- so that a control dependency preserves the needed ordering.
- That said, it is easy to get control dependencies wrong.
- Please see the "CONTROL DEPENDENCIES" section of
- Documentation/memory-barriers.txt for more details.
-
- o The pointers are not equal -and- the compiler does
- not have enough information to deduce the value of the
- pointer. Note that the volatile cast in rcu_dereference()
- will normally prevent the compiler from knowing too much.
-
-o Disable any value-speculation optimizations that your compiler
- might provide, especially if you are making use of feedback-based
- optimizations that take data collected from prior runs. Such
- value-speculation optimizations reorder operations by design.
-
- There is one exception to this rule: Value-speculation
- optimizations that leverage the branch-prediction hardware are
- safe on strongly ordered systems (such as x86), but not on weakly
- ordered systems (such as ARM or Power). Choose your compiler
- command-line options wisely!
-
-
-EXAMPLE OF AMPLIFIED RCU-USAGE BUG
-
-Because updaters can run concurrently with RCU readers, RCU readers can
-see stale and/or inconsistent values. If RCU readers need fresh or
-consistent values, which they sometimes do, they need to take proper
-precautions. To see this, consider the following code fragment:
-
- struct foo {
- int a;
- int b;
- int c;
- };
- struct foo *gp1;
- struct foo *gp2;
-
- void updater(void)
- {
- struct foo *p;
-
- p = kmalloc(...);
- if (p == NULL)
- deal_with_it();
- p->a = 42; /* Each field in its own cache line. */
- p->b = 43;
- p->c = 44;
- rcu_assign_pointer(gp1, p);
- p->b = 143;
- p->c = 144;
- rcu_assign_pointer(gp2, p);
- }
-
- void reader(void)
- {
- struct foo *p;
- struct foo *q;
- int r1, r2;
-
- p = rcu_dereference(gp2);
- if (p == NULL)
- return;
- r1 = p->b; /* Guaranteed to get 143. */
- q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
- if (p == q) {
- /* The compiler decides that q->c is same as p->c. */
- r2 = p->c; /* Could get 44 on weakly order system. */
- }
- do_something_with(r1, r2);
- }
-
-You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
-but you should not be. After all, the updater might have been invoked
-a second time between the time reader() loaded into "r1" and the time
-that it loaded into "r2". The fact that this same result can occur due
-to some reordering from the compiler and CPUs is beside the point.
-
-But suppose that the reader needs a consistent view?
-
-Then one approach is to use locking, for example, as follows:
-
- struct foo {
- int a;
- int b;
- int c;
- spinlock_t lock;
- };
- struct foo *gp1;
- struct foo *gp2;
-
- void updater(void)
- {
- struct foo *p;
-
- p = kmalloc(...);
- if (p == NULL)
- deal_with_it();
- spin_lock(&p->lock);
- p->a = 42; /* Each field in its own cache line. */
- p->b = 43;
- p->c = 44;
- spin_unlock(&p->lock);
- rcu_assign_pointer(gp1, p);
- spin_lock(&p->lock);
- p->b = 143;
- p->c = 144;
- spin_unlock(&p->lock);
- rcu_assign_pointer(gp2, p);
- }
-
- void reader(void)
- {
- struct foo *p;
- struct foo *q;
- int r1, r2;
-
- p = rcu_dereference(gp2);
- if (p == NULL)
- return;
- spin_lock(&p->lock);
- r1 = p->b; /* Guaranteed to get 143. */
- q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
- if (p == q) {
- /* The compiler decides that q->c is same as p->c. */
- r2 = p->c; /* Locking guarantees r2 == 144. */
- }
- spin_unlock(&p->lock);
- do_something_with(r1, r2);
- }
-
-As always, use the right tool for the job!
-
-
-EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH
-
-If a pointer obtained from rcu_dereference() compares not-equal to some
-other pointer, the compiler normally has no clue what the value of the
-first pointer might be. This lack of knowledge prevents the compiler
-from carrying out optimizations that otherwise might destroy the ordering
-guarantees that RCU depends on. And the volatile cast in rcu_dereference()
-should prevent the compiler from guessing the value.
-
-But without rcu_dereference(), the compiler knows more than you might
-expect. Consider the following code fragment:
-
- struct foo {
- int a;
- int b;
- };
- static struct foo variable1;
- static struct foo variable2;
- static struct foo *gp = &variable1;
-
- void updater(void)
- {
- initialize_foo(&variable2);
- rcu_assign_pointer(gp, &variable2);
- /*
- * The above is the only store to gp in this translation unit,
- * and the address of gp is not exported in any way.
- */
- }
-
- int reader(void)
- {
- struct foo *p;
-
- p = gp;
- barrier();
- if (p == &variable1)
- return p->a; /* Must be variable1.a. */
- else
- return p->b; /* Must be variable2.b. */
- }
-
-Because the compiler can see all stores to "gp", it knows that the only
-possible values of "gp" are "variable1" on the one hand and "variable2"
-on the other. The comparison in reader() therefore tells the compiler
-the exact value of "p" even in the not-equals case. This allows the
-compiler to make the return values independent of the load from "gp",
-in turn destroying the ordering between this load and the loads of the
-return values. This can result in "p->b" returning pre-initialization
-garbage values.
-
-In short, rcu_dereference() is -not- optional when you are going to
-dereference the resulting pointer.
diff --git a/Documentation/RCU/rcubarrier.rst b/Documentation/RCU/rcubarrier.rst
new file mode 100644
index 000000000000..12a7b059654f
--- /dev/null
+++ b/Documentation/RCU/rcubarrier.rst
@@ -0,0 +1,377 @@
+.. _rcu_barrier:
+
+RCU and Unloadable Modules
+==========================
+
+[Originally published in LWN Jan. 14, 2007: http://lwn.net/Articles/217484/]
+
+RCU updaters sometimes use call_rcu() to initiate an asynchronous wait for
+a grace period to elapse. This primitive takes a pointer to an rcu_head
+struct placed within the RCU-protected data structure and another pointer
+to a function that may be invoked later to free that structure. Code to
+delete an element p from the linked list from IRQ context might then be
+as follows::
+
+ list_del_rcu(p);
+ call_rcu(&p->rcu, p_callback);
+
+Since call_rcu() never blocks, this code can safely be used from within
+IRQ context. The function p_callback() might be defined as follows::
+
+ static void p_callback(struct rcu_head *rp)
+ {
+ struct pstruct *p = container_of(rp, struct pstruct, rcu);
+
+ kfree(p);
+ }
+
+
+Unloading Modules That Use call_rcu()
+-------------------------------------
+
+But what if the p_callback() function is defined in an unloadable module?
+
+If we unload the module while some RCU callbacks are pending,
+the CPUs executing these callbacks are going to be severely
+disappointed when they are later invoked, as fancifully depicted at
+http://lwn.net/images/ns/kernel/rcu-drop.jpg.
+
+We could try placing a synchronize_rcu() in the module-exit code path,
+but this is not sufficient. Although synchronize_rcu() does wait for a
+grace period to elapse, it does not wait for the callbacks to complete.
+
+One might be tempted to try several back-to-back synchronize_rcu()
+calls, but this is still not guaranteed to work. If there is a very
+heavy RCU-callback load, then some of the callbacks might be deferred in
+order to allow other processing to proceed. For but one example, such
+deferral is required in realtime kernels in order to avoid excessive
+scheduling latencies.
+
+
+rcu_barrier()
+-------------
+
+This situation can be handled by the rcu_barrier() primitive. Rather
+than waiting for a grace period to elapse, rcu_barrier() waits for all
+outstanding RCU callbacks to complete. Please note that rcu_barrier()
+does **not** imply synchronize_rcu(), in particular, if there are no RCU
+callbacks queued anywhere, rcu_barrier() is within its rights to return
+immediately, without waiting for anything, let alone a grace period.
+
+Pseudo-code using rcu_barrier() is as follows:
+
+ 1. Prevent any new RCU callbacks from being posted.
+ 2. Execute rcu_barrier().
+ 3. Allow the module to be unloaded.
+
+There is also an srcu_barrier() function for SRCU, and you of course
+must match the flavor of srcu_barrier() with that of call_srcu().
+If your module uses multiple srcu_struct structures, then it must also
+use multiple invocations of srcu_barrier() when unloading that module.
+For example, if it uses call_rcu(), call_srcu() on srcu_struct_1, and
+call_srcu() on srcu_struct_2, then the following three lines of code
+will be required when unloading::
+
+ 1 rcu_barrier();
+ 2 srcu_barrier(&srcu_struct_1);
+ 3 srcu_barrier(&srcu_struct_2);
+
+If latency is of the essence, workqueues could be used to run these
+three functions concurrently.
+
+An ancient version of the rcutorture module makes use of rcu_barrier()
+in its exit function as follows::
+
+ 1 static void
+ 2 rcu_torture_cleanup(void)
+ 3 {
+ 4 int i;
+ 5
+ 6 fullstop = 1;
+ 7 if (shuffler_task != NULL) {
+ 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task");
+ 9 kthread_stop(shuffler_task);
+ 10 }
+ 11 shuffler_task = NULL;
+ 12
+ 13 if (writer_task != NULL) {
+ 14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task");
+ 15 kthread_stop(writer_task);
+ 16 }
+ 17 writer_task = NULL;
+ 18
+ 19 if (reader_tasks != NULL) {
+ 20 for (i = 0; i < nrealreaders; i++) {
+ 21 if (reader_tasks[i] != NULL) {
+ 22 VERBOSE_PRINTK_STRING(
+ 23 "Stopping rcu_torture_reader task");
+ 24 kthread_stop(reader_tasks[i]);
+ 25 }
+ 26 reader_tasks[i] = NULL;
+ 27 }
+ 28 kfree(reader_tasks);
+ 29 reader_tasks = NULL;
+ 30 }
+ 31 rcu_torture_current = NULL;
+ 32
+ 33 if (fakewriter_tasks != NULL) {
+ 34 for (i = 0; i < nfakewriters; i++) {
+ 35 if (fakewriter_tasks[i] != NULL) {
+ 36 VERBOSE_PRINTK_STRING(
+ 37 "Stopping rcu_torture_fakewriter task");
+ 38 kthread_stop(fakewriter_tasks[i]);
+ 39 }
+ 40 fakewriter_tasks[i] = NULL;
+ 41 }
+ 42 kfree(fakewriter_tasks);
+ 43 fakewriter_tasks = NULL;
+ 44 }
+ 45
+ 46 if (stats_task != NULL) {
+ 47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task");
+ 48 kthread_stop(stats_task);
+ 49 }
+ 50 stats_task = NULL;
+ 51
+ 52 /* Wait for all RCU callbacks to fire. */
+ 53 rcu_barrier();
+ 54
+ 55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */
+ 56
+ 57 if (cur_ops->cleanup != NULL)
+ 58 cur_ops->cleanup();
+ 59 if (atomic_read(&n_rcu_torture_error))
+ 60 rcu_torture_print_module_parms("End of test: FAILURE");
+ 61 else
+ 62 rcu_torture_print_module_parms("End of test: SUCCESS");
+ 63 }
+
+Line 6 sets a global variable that prevents any RCU callbacks from
+re-posting themselves. This will not be necessary in most cases, since
+RCU callbacks rarely include calls to call_rcu(). However, the rcutorture
+module is an exception to this rule, and therefore needs to set this
+global variable.
+
+Lines 7-50 stop all the kernel tasks associated with the rcutorture
+module. Therefore, once execution reaches line 53, no more rcutorture
+RCU callbacks will be posted. The rcu_barrier() call on line 53 waits
+for any pre-existing callbacks to complete.
+
+Then lines 55-62 print status and do operation-specific cleanup, and
+then return, permitting the module-unload operation to be completed.
+
+.. _rcubarrier_quiz_1:
+
+Quick Quiz #1:
+ Is there any other situation where rcu_barrier() might
+ be required?
+
+:ref:`Answer to Quick Quiz #1 <answer_rcubarrier_quiz_1>`
+
+Your module might have additional complications. For example, if your
+module invokes call_rcu() from timers, you will need to first refrain
+from posting new timers, cancel (or wait for) all the already-posted
+timers, and only then invoke rcu_barrier() to wait for any remaining
+RCU callbacks to complete.
+
+Of course, if your module uses call_rcu(), you will need to invoke
+rcu_barrier() before unloading. Similarly, if your module uses
+call_srcu(), you will need to invoke srcu_barrier() before unloading,
+and on the same srcu_struct structure. If your module uses call_rcu()
+**and** call_srcu(), then (as noted above) you will need to invoke
+rcu_barrier() **and** srcu_barrier().
+
+
+Implementing rcu_barrier()
+--------------------------
+
+Dipankar Sarma's implementation of rcu_barrier() makes use of the fact
+that RCU callbacks are never reordered once queued on one of the per-CPU
+queues. His implementation queues an RCU callback on each of the per-CPU
+callback queues, and then waits until they have all started executing, at
+which point, all earlier RCU callbacks are guaranteed to have completed.
+
+The original code for rcu_barrier() was roughly as follows::
+
+ 1 void rcu_barrier(void)
+ 2 {
+ 3 BUG_ON(in_interrupt());
+ 4 /* Take cpucontrol mutex to protect against CPU hotplug */
+ 5 mutex_lock(&rcu_barrier_mutex);
+ 6 init_completion(&rcu_barrier_completion);
+ 7 atomic_set(&rcu_barrier_cpu_count, 1);
+ 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1);
+ 9 if (atomic_dec_and_test(&rcu_barrier_cpu_count))
+ 10 complete(&rcu_barrier_completion);
+ 11 wait_for_completion(&rcu_barrier_completion);
+ 12 mutex_unlock(&rcu_barrier_mutex);
+ 13 }
+
+Line 3 verifies that the caller is in process context, and lines 5 and 12
+use rcu_barrier_mutex to ensure that only one rcu_barrier() is using the
+global completion and counters at a time, which are initialized on lines
+6 and 7. Line 8 causes each CPU to invoke rcu_barrier_func(), which is
+shown below. Note that the final "1" in on_each_cpu()'s argument list
+ensures that all the calls to rcu_barrier_func() will have completed
+before on_each_cpu() returns. Line 9 removes the initial count from
+rcu_barrier_cpu_count, and if this count is now zero, line 10 finalizes
+the completion, which prevents line 11 from blocking. Either way,
+line 11 then waits (if needed) for the completion.
+
+.. _rcubarrier_quiz_2:
+
+Quick Quiz #2:
+ Why doesn't line 8 initialize rcu_barrier_cpu_count to zero,
+ thereby avoiding the need for lines 9 and 10?
+
+:ref:`Answer to Quick Quiz #2 <answer_rcubarrier_quiz_2>`
+
+This code was rewritten in 2008 and several times thereafter, but this
+still gives the general idea.
+
+The rcu_barrier_func() runs on each CPU, where it invokes call_rcu()
+to post an RCU callback, as follows::
+
+ 1 static void rcu_barrier_func(void *notused)
+ 2 {
+ 3 int cpu = smp_processor_id();
+ 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu);
+ 5 struct rcu_head *head;
+ 6
+ 7 head = &rdp->barrier;
+ 8 atomic_inc(&rcu_barrier_cpu_count);
+ 9 call_rcu(head, rcu_barrier_callback);
+ 10 }
+
+Lines 3 and 4 locate RCU's internal per-CPU rcu_data structure,
+which contains the struct rcu_head that needed for the later call to
+call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line
+8 increments the global counter. This counter will later be decremented
+by the callback. Line 9 then registers the rcu_barrier_callback() on
+the current CPU's queue.
+
+The rcu_barrier_callback() function simply atomically decrements the
+rcu_barrier_cpu_count variable and finalizes the completion when it
+reaches zero, as follows::
+
+ 1 static void rcu_barrier_callback(struct rcu_head *notused)
+ 2 {
+ 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count))
+ 4 complete(&rcu_barrier_completion);
+ 5 }
+
+.. _rcubarrier_quiz_3:
+
+Quick Quiz #3:
+ What happens if CPU 0's rcu_barrier_func() executes
+ immediately (thus incrementing rcu_barrier_cpu_count to the
+ value one), but the other CPU's rcu_barrier_func() invocations
+ are delayed for a full grace period? Couldn't this result in
+ rcu_barrier() returning prematurely?
+
+:ref:`Answer to Quick Quiz #3 <answer_rcubarrier_quiz_3>`
+
+The current rcu_barrier() implementation is more complex, due to the need
+to avoid disturbing idle CPUs (especially on battery-powered systems)
+and the need to minimally disturb non-idle CPUs in real-time systems.
+In addition, a great many optimizations have been applied. However,
+the code above illustrates the concepts.
+
+
+rcu_barrier() Summary
+---------------------
+
+The rcu_barrier() primitive is used relatively infrequently, since most
+code using RCU is in the core kernel rather than in modules. However, if
+you are using RCU from an unloadable module, you need to use rcu_barrier()
+so that your module may be safely unloaded.
+
+
+Answers to Quick Quizzes
+------------------------
+
+.. _answer_rcubarrier_quiz_1:
+
+Quick Quiz #1:
+ Is there any other situation where rcu_barrier() might
+ be required?
+
+Answer:
+ Interestingly enough, rcu_barrier() was not originally
+ implemented for module unloading. Nikita Danilov was using
+ RCU in a filesystem, which resulted in a similar situation at
+ filesystem-unmount time. Dipankar Sarma coded up rcu_barrier()
+ in response, so that Nikita could invoke it during the
+ filesystem-unmount process.
+
+ Much later, yours truly hit the RCU module-unload problem when
+ implementing rcutorture, and found that rcu_barrier() solves
+ this problem as well.
+
+:ref:`Back to Quick Quiz #1 <rcubarrier_quiz_1>`
+
+.. _answer_rcubarrier_quiz_2:
+
+Quick Quiz #2:
+ Why doesn't line 8 initialize rcu_barrier_cpu_count to zero,
+ thereby avoiding the need for lines 9 and 10?
+
+Answer:
+ Suppose that the on_each_cpu() function shown on line 8 was
+ delayed, so that CPU 0's rcu_barrier_func() executed and
+ the corresponding grace period elapsed, all before CPU 1's
+ rcu_barrier_func() started executing. This would result in
+ rcu_barrier_cpu_count being decremented to zero, so that line
+ 11's wait_for_completion() would return immediately, failing to
+ wait for CPU 1's callbacks to be invoked.
+
+ Note that this was not a problem when the rcu_barrier() code
+ was first added back in 2005. This is because on_each_cpu()
+ disables preemption, which acted as an RCU read-side critical
+ section, thus preventing CPU 0's grace period from completing
+ until on_each_cpu() had dealt with all of the CPUs.
+
+ However, with the RCU flavor consolidation around v4.20, this
+ possibility was once again ruled out, because the consolidated
+ RCU once again waits on nonpreemptible regions of code.
+
+ Nevertheless, that extra count might still be a good idea.
+ Relying on these sort of accidents of implementation can result
+ in later surprise bugs when the implementation changes.
+
+:ref:`Back to Quick Quiz #2 <rcubarrier_quiz_2>`
+
+.. _answer_rcubarrier_quiz_3:
+
+Quick Quiz #3:
+ What happens if CPU 0's rcu_barrier_func() executes
+ immediately (thus incrementing rcu_barrier_cpu_count to the
+ value one), but the other CPU's rcu_barrier_func() invocations
+ are delayed for a full grace period? Couldn't this result in
+ rcu_barrier() returning prematurely?
+
+Answer:
+ This cannot happen. The reason is that on_each_cpu() has its last
+ argument, the wait flag, set to "1". This flag is passed through
+ to smp_call_function() and further to smp_call_function_on_cpu(),
+ causing this latter to spin until the cross-CPU invocation of
+ rcu_barrier_func() has completed. This by itself would prevent
+ a grace period from completing on non-CONFIG_PREEMPTION kernels,
+ since each CPU must undergo a context switch (or other quiescent
+ state) before the grace period can complete. However, this is
+ of no use in CONFIG_PREEMPTION kernels.
+
+ Therefore, on_each_cpu() disables preemption across its call
+ to smp_call_function() and also across the local call to
+ rcu_barrier_func(). Because recent RCU implementations treat
+ preemption-disabled regions of code as RCU read-side critical
+ sections, this prevents grace periods from completing. This
+ means that all CPUs have executed rcu_barrier_func() before
+ the first rcu_barrier_callback() can possibly execute, in turn
+ preventing rcu_barrier_cpu_count from prematurely reaching zero.
+
+ But if on_each_cpu() ever decides to forgo disabling preemption,
+ as might well happen due to real-time latency considerations,
+ initializing rcu_barrier_cpu_count to one will save the day.
+
+:ref:`Back to Quick Quiz #3 <rcubarrier_quiz_3>`
diff --git a/Documentation/RCU/rcubarrier.txt b/Documentation/RCU/rcubarrier.txt
deleted file mode 100644
index b10cfe711e68..000000000000
--- a/Documentation/RCU/rcubarrier.txt
+++ /dev/null
@@ -1,321 +0,0 @@
-RCU and Unloadable Modules
-
-[Originally published in LWN Jan. 14, 2007: http://lwn.net/Articles/217484/]
-
-RCU (read-copy update) is a synchronization mechanism that can be thought
-of as a replacement for read-writer locking (among other things), but with
-very low-overhead readers that are immune to deadlock, priority inversion,
-and unbounded latency. RCU read-side critical sections are delimited
-by rcu_read_lock() and rcu_read_unlock(), which, in non-CONFIG_PREEMPT
-kernels, generate no code whatsoever.
-
-This means that RCU writers are unaware of the presence of concurrent
-readers, so that RCU updates to shared data must be undertaken quite
-carefully, leaving an old version of the data structure in place until all
-pre-existing readers have finished. These old versions are needed because
-such readers might hold a reference to them. RCU updates can therefore be
-rather expensive, and RCU is thus best suited for read-mostly situations.
-
-How can an RCU writer possibly determine when all readers are finished,
-given that readers might well leave absolutely no trace of their
-presence? There is a synchronize_rcu() primitive that blocks until all
-pre-existing readers have completed. An updater wishing to delete an
-element p from a linked list might do the following, while holding an
-appropriate lock, of course:
-
- list_del_rcu(p);
- synchronize_rcu();
- kfree(p);
-
-But the above code cannot be used in IRQ context -- the call_rcu()
-primitive must be used instead. This primitive takes a pointer to an
-rcu_head struct placed within the RCU-protected data structure and
-another pointer to a function that may be invoked later to free that
-structure. Code to delete an element p from the linked list from IRQ
-context might then be as follows:
-
- list_del_rcu(p);
- call_rcu(&p->rcu, p_callback);
-
-Since call_rcu() never blocks, this code can safely be used from within
-IRQ context. The function p_callback() might be defined as follows:
-
- static void p_callback(struct rcu_head *rp)
- {
- struct pstruct *p = container_of(rp, struct pstruct, rcu);
-
- kfree(p);
- }
-
-
-Unloading Modules That Use call_rcu()
-
-But what if p_callback is defined in an unloadable module?
-
-If we unload the module while some RCU callbacks are pending,
-the CPUs executing these callbacks are going to be severely
-disappointed when they are later invoked, as fancifully depicted at
-http://lwn.net/images/ns/kernel/rcu-drop.jpg.
-
-We could try placing a synchronize_rcu() in the module-exit code path,
-but this is not sufficient. Although synchronize_rcu() does wait for a
-grace period to elapse, it does not wait for the callbacks to complete.
-
-One might be tempted to try several back-to-back synchronize_rcu()
-calls, but this is still not guaranteed to work. If there is a very
-heavy RCU-callback load, then some of the callbacks might be deferred
-in order to allow other processing to proceed. Such deferral is required
-in realtime kernels in order to avoid excessive scheduling latencies.
-
-
-rcu_barrier()
-
-We instead need the rcu_barrier() primitive. Rather than waiting for
-a grace period to elapse, rcu_barrier() waits for all outstanding RCU
-callbacks to complete. Please note that rcu_barrier() does -not- imply
-synchronize_rcu(), in particular, if there are no RCU callbacks queued
-anywhere, rcu_barrier() is within its rights to return immediately,
-without waiting for a grace period to elapse.
-
-Pseudo-code using rcu_barrier() is as follows:
-
- 1. Prevent any new RCU callbacks from being posted.
- 2. Execute rcu_barrier().
- 3. Allow the module to be unloaded.
-
-There are also rcu_barrier_bh(), rcu_barrier_sched(), and srcu_barrier()
-functions for the other flavors of RCU, and you of course must match
-the flavor of rcu_barrier() with that of call_rcu(). If your module
-uses multiple flavors of call_rcu(), then it must also use multiple
-flavors of rcu_barrier() when unloading that module. For example, if
-it uses call_rcu_bh(), call_srcu() on srcu_struct_1, and call_srcu() on
-srcu_struct_2(), then the following three lines of code will be required
-when unloading:
-
- 1 rcu_barrier_bh();
- 2 srcu_barrier(&srcu_struct_1);
- 3 srcu_barrier(&srcu_struct_2);
-
-The rcutorture module makes use of rcu_barrier() in its exit function
-as follows:
-
- 1 static void
- 2 rcu_torture_cleanup(void)
- 3 {
- 4 int i;
- 5
- 6 fullstop = 1;
- 7 if (shuffler_task != NULL) {
- 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task");
- 9 kthread_stop(shuffler_task);
-10 }
-11 shuffler_task = NULL;
-12
-13 if (writer_task != NULL) {
-14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task");
-15 kthread_stop(writer_task);
-16 }
-17 writer_task = NULL;
-18
-19 if (reader_tasks != NULL) {
-20 for (i = 0; i < nrealreaders; i++) {
-21 if (reader_tasks[i] != NULL) {
-22 VERBOSE_PRINTK_STRING(
-23 "Stopping rcu_torture_reader task");
-24 kthread_stop(reader_tasks[i]);
-25 }
-26 reader_tasks[i] = NULL;
-27 }
-28 kfree(reader_tasks);
-29 reader_tasks = NULL;
-30 }
-31 rcu_torture_current = NULL;
-32
-33 if (fakewriter_tasks != NULL) {
-34 for (i = 0; i < nfakewriters; i++) {
-35 if (fakewriter_tasks[i] != NULL) {
-36 VERBOSE_PRINTK_STRING(
-37 "Stopping rcu_torture_fakewriter task");
-38 kthread_stop(fakewriter_tasks[i]);
-39 }
-40 fakewriter_tasks[i] = NULL;
-41 }
-42 kfree(fakewriter_tasks);
-43 fakewriter_tasks = NULL;
-44 }
-45
-46 if (stats_task != NULL) {
-47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task");
-48 kthread_stop(stats_task);
-49 }
-50 stats_task = NULL;
-51
-52 /* Wait for all RCU callbacks to fire. */
-53 rcu_barrier();
-54
-55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */
-56
-57 if (cur_ops->cleanup != NULL)
-58 cur_ops->cleanup();
-59 if (atomic_read(&n_rcu_torture_error))
-60 rcu_torture_print_module_parms("End of test: FAILURE");
-61 else
-62 rcu_torture_print_module_parms("End of test: SUCCESS");
-63 }
-
-Line 6 sets a global variable that prevents any RCU callbacks from
-re-posting themselves. This will not be necessary in most cases, since
-RCU callbacks rarely include calls to call_rcu(). However, the rcutorture
-module is an exception to this rule, and therefore needs to set this
-global variable.
-
-Lines 7-50 stop all the kernel tasks associated with the rcutorture
-module. Therefore, once execution reaches line 53, no more rcutorture
-RCU callbacks will be posted. The rcu_barrier() call on line 53 waits
-for any pre-existing callbacks to complete.
-
-Then lines 55-62 print status and do operation-specific cleanup, and
-then return, permitting the module-unload operation to be completed.
-
-Quick Quiz #1: Is there any other situation where rcu_barrier() might
- be required?
-
-Your module might have additional complications. For example, if your
-module invokes call_rcu() from timers, you will need to first cancel all
-the timers, and only then invoke rcu_barrier() to wait for any remaining
-RCU callbacks to complete.
-
-Of course, if you module uses call_rcu_bh(), you will need to invoke
-rcu_barrier_bh() before unloading. Similarly, if your module uses
-call_rcu_sched(), you will need to invoke rcu_barrier_sched() before
-unloading. If your module uses call_rcu(), call_rcu_bh(), -and-
-call_rcu_sched(), then you will need to invoke each of rcu_barrier(),
-rcu_barrier_bh(), and rcu_barrier_sched().
-
-
-Implementing rcu_barrier()
-
-Dipankar Sarma's implementation of rcu_barrier() makes use of the fact
-that RCU callbacks are never reordered once queued on one of the per-CPU
-queues. His implementation queues an RCU callback on each of the per-CPU
-callback queues, and then waits until they have all started executing, at
-which point, all earlier RCU callbacks are guaranteed to have completed.
-
-The original code for rcu_barrier() was as follows:
-
- 1 void rcu_barrier(void)
- 2 {
- 3 BUG_ON(in_interrupt());
- 4 /* Take cpucontrol mutex to protect against CPU hotplug */
- 5 mutex_lock(&rcu_barrier_mutex);
- 6 init_completion(&rcu_barrier_completion);
- 7 atomic_set(&rcu_barrier_cpu_count, 0);
- 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1);
- 9 wait_for_completion(&rcu_barrier_completion);
-10 mutex_unlock(&rcu_barrier_mutex);
-11 }
-
-Line 3 verifies that the caller is in process context, and lines 5 and 10
-use rcu_barrier_mutex to ensure that only one rcu_barrier() is using the
-global completion and counters at a time, which are initialized on lines
-6 and 7. Line 8 causes each CPU to invoke rcu_barrier_func(), which is
-shown below. Note that the final "1" in on_each_cpu()'s argument list
-ensures that all the calls to rcu_barrier_func() will have completed
-before on_each_cpu() returns. Line 9 then waits for the completion.
-
-This code was rewritten in 2008 to support rcu_barrier_bh() and
-rcu_barrier_sched() in addition to the original rcu_barrier().
-
-The rcu_barrier_func() runs on each CPU, where it invokes call_rcu()
-to post an RCU callback, as follows:
-
- 1 static void rcu_barrier_func(void *notused)
- 2 {
- 3 int cpu = smp_processor_id();
- 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu);
- 5 struct rcu_head *head;
- 6
- 7 head = &rdp->barrier;
- 8 atomic_inc(&rcu_barrier_cpu_count);
- 9 call_rcu(head, rcu_barrier_callback);
-10 }
-
-Lines 3 and 4 locate RCU's internal per-CPU rcu_data structure,
-which contains the struct rcu_head that needed for the later call to
-call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line
-8 increments a global counter. This counter will later be decremented
-by the callback. Line 9 then registers the rcu_barrier_callback() on
-the current CPU's queue.
-
-The rcu_barrier_callback() function simply atomically decrements the
-rcu_barrier_cpu_count variable and finalizes the completion when it
-reaches zero, as follows:
-
- 1 static void rcu_barrier_callback(struct rcu_head *notused)
- 2 {
- 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count))
- 4 complete(&rcu_barrier_completion);
- 5 }
-
-Quick Quiz #2: What happens if CPU 0's rcu_barrier_func() executes
- immediately (thus incrementing rcu_barrier_cpu_count to the
- value one), but the other CPU's rcu_barrier_func() invocations
- are delayed for a full grace period? Couldn't this result in
- rcu_barrier() returning prematurely?
-
-
-rcu_barrier() Summary
-
-The rcu_barrier() primitive has seen relatively little use, since most
-code using RCU is in the core kernel rather than in modules. However, if
-you are using RCU from an unloadable module, you need to use rcu_barrier()
-so that your module may be safely unloaded.
-
-
-Answers to Quick Quizzes
-
-Quick Quiz #1: Is there any other situation where rcu_barrier() might
- be required?
-
-Answer: Interestingly enough, rcu_barrier() was not originally
- implemented for module unloading. Nikita Danilov was using
- RCU in a filesystem, which resulted in a similar situation at
- filesystem-unmount time. Dipankar Sarma coded up rcu_barrier()
- in response, so that Nikita could invoke it during the
- filesystem-unmount process.
-
- Much later, yours truly hit the RCU module-unload problem when
- implementing rcutorture, and found that rcu_barrier() solves
- this problem as well.
-
-Quick Quiz #2: What happens if CPU 0's rcu_barrier_func() executes
- immediately (thus incrementing rcu_barrier_cpu_count to the
- value one), but the other CPU's rcu_barrier_func() invocations
- are delayed for a full grace period? Couldn't this result in
- rcu_barrier() returning prematurely?
-
-Answer: This cannot happen. The reason is that on_each_cpu() has its last
- argument, the wait flag, set to "1". This flag is passed through
- to smp_call_function() and further to smp_call_function_on_cpu(),
- causing this latter to spin until the cross-CPU invocation of
- rcu_barrier_func() has completed. This by itself would prevent
- a grace period from completing on non-CONFIG_PREEMPT kernels,
- since each CPU must undergo a context switch (or other quiescent
- state) before the grace period can complete. However, this is
- of no use in CONFIG_PREEMPT kernels.
-
- Therefore, on_each_cpu() disables preemption across its call
- to smp_call_function() and also across the local call to
- rcu_barrier_func(). This prevents the local CPU from context
- switching, again preventing grace periods from completing. This
- means that all CPUs have executed rcu_barrier_func() before
- the first rcu_barrier_callback() can possibly execute, in turn
- preventing rcu_barrier_cpu_count from prematurely reaching zero.
-
- Currently, -rt implementations of RCU keep but a single global
- queue for RCU callbacks, and thus do not suffer from this
- problem. However, when the -rt RCU eventually does have per-CPU
- callback queues, things will have to change. One simple change
- is to add an rcu_read_lock() before line 8 of rcu_barrier()
- and an rcu_read_unlock() after line 8 of this same function. If
- you can think of a better change, please let me know!
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
new file mode 100644
index 000000000000..21e40fcc08de
--- /dev/null
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -0,0 +1,215 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================================
+Using RCU hlist_nulls to protect list and objects
+=================================================
+
+This section describes how to use hlist_nulls to
+protect read-mostly linked lists and
+objects using SLAB_TYPESAFE_BY_RCU allocations.
+
+Please read the basics in listRCU.rst.
+
+Using 'nulls'
+=============
+
+Using special makers (called 'nulls') is a convenient way
+to solve following problem.
+
+Without 'nulls', a typical RCU linked list managing objects which are
+allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can use the following
+algorithms. Following examples assume 'obj' is a pointer to such
+objects, which is having below type.
+
+::
+
+ struct object {
+ struct hlist_node obj_node;
+ atomic_t refcnt;
+ unsigned int key;
+ };
+
+1) Lookup algorithm
+-------------------
+
+::
+
+ begin:
+ rcu_read_lock();
+ obj = lockless_lookup(key);
+ if (obj) {
+ if (!try_get_ref(obj)) { // might fail for free objects
+ rcu_read_unlock();
+ goto begin;
+ }
+ /*
+ * Because a writer could delete object, and a writer could
+ * reuse these object before the RCU grace period, we
+ * must check key after getting the reference on object
+ */
+ if (obj->key != key) { // not the object we expected
+ put_ref(obj);
+ rcu_read_unlock();
+ goto begin;
+ }
+ }
+ rcu_read_unlock();
+
+Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu()
+but a version with an additional memory barrier (smp_rmb())
+
+::
+
+ lockless_lookup(key)
+ {
+ struct hlist_node *node, *next;
+ for (pos = rcu_dereference((head)->first);
+ pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
+ ({ obj = hlist_entry(pos, typeof(*obj), obj_node); 1; });
+ pos = rcu_dereference(next))
+ if (obj->key == key)
+ return obj;
+ return NULL;
+ }
+
+And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb()::
+
+ struct hlist_node *node;
+ for (pos = rcu_dereference((head)->first);
+ pos && ({ prefetch(pos->next); 1; }) &&
+ ({ obj = hlist_entry(pos, typeof(*obj), obj_node); 1; });
+ pos = rcu_dereference(pos->next))
+ if (obj->key == key)
+ return obj;
+ return NULL;
+
+Quoting Corey Minyard::
+
+ "If the object is moved from one list to another list in-between the
+ time the hash is calculated and the next field is accessed, and the
+ object has moved to the end of a new list, the traversal will not
+ complete properly on the list it should have, since the object will
+ be on the end of the new list and there's not a way to tell it's on a
+ new list and restart the list traversal. I think that this can be
+ solved by pre-fetching the "next" field (with proper barriers) before
+ checking the key."
+
+2) Insertion algorithm
+----------------------
+
+We need to make sure a reader cannot read the new 'obj->obj_node.next' value
+and previous value of 'obj->key'. Otherwise, an item could be deleted
+from a chain, and inserted into another chain. If new chain was empty
+before the move, 'next' pointer is NULL, and lockless reader can not
+detect the fact that it missed following items in original chain.
+
+::
+
+ /*
+ * Please note that new inserts are done at the head of list,
+ * not in the middle or end.
+ */
+ obj = kmem_cache_alloc(...);
+ lock_chain(); // typically a spin_lock()
+ obj->key = key;
+ atomic_set_release(&obj->refcnt, 1); // key before refcnt
+ hlist_add_head_rcu(&obj->obj_node, list);
+ unlock_chain(); // typically a spin_unlock()
+
+
+3) Removal algorithm
+--------------------
+
+Nothing special here, we can use a standard RCU hlist deletion.
+But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
+very very fast (before the end of RCU grace period)
+
+::
+
+ if (put_last_reference_on(obj) {
+ lock_chain(); // typically a spin_lock()
+ hlist_del_init_rcu(&obj->obj_node);
+ unlock_chain(); // typically a spin_unlock()
+ kmem_cache_free(cachep, obj);
+ }
+
+
+
+--------------------------------------------------------------------------
+
+Avoiding extra smp_rmb()
+========================
+
+With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup().
+
+For example, if we choose to store the slot number as the 'nulls'
+end-of-list marker for each slot of the hash table, we can detect
+a race (some writer did a delete and/or a move of an object
+to another chain) checking the final 'nulls' value if
+the lookup met the end of chain. If final 'nulls' value
+is not the slot number, then we must restart the lookup at
+the beginning. If the object was moved to the same chain,
+then the reader doesn't care: It might occasionally
+scan the list again without harm.
+
+Note that using hlist_nulls means the type of 'obj_node' field of
+'struct object' becomes 'struct hlist_nulls_node'.
+
+
+1) lookup algorithm
+-------------------
+
+::
+
+ head = &table[slot];
+ begin:
+ rcu_read_lock();
+ hlist_nulls_for_each_entry_rcu(obj, node, head, obj_node) {
+ if (obj->key == key) {
+ if (!try_get_ref(obj)) { // might fail for free objects
+ rcu_read_unlock();
+ goto begin;
+ }
+ if (obj->key != key) { // not the object we expected
+ put_ref(obj);
+ rcu_read_unlock();
+ goto begin;
+ }
+ goto out;
+ }
+ }
+
+ // If the nulls value we got at the end of this lookup is
+ // not the expected one, we must restart lookup.
+ // We probably met an item that was moved to another chain.
+ if (get_nulls_value(node) != slot) {
+ put_ref(obj);
+ rcu_read_unlock();
+ goto begin;
+ }
+ obj = NULL;
+
+ out:
+ rcu_read_unlock();
+
+2) Insert algorithm
+-------------------
+
+Same to the above one, but uses hlist_nulls_add_head_rcu() instead of
+hlist_add_head_rcu().
+
+::
+
+ /*
+ * Please note that new inserts are done at the head of list,
+ * not in the middle or end.
+ */
+ obj = kmem_cache_alloc(cachep);
+ lock_chain(); // typically a spin_lock()
+ obj->key = key;
+ atomic_set_release(&obj->refcnt, 1); // key before refcnt
+ /*
+ * insert obj in RCU way (readers might be traversing chain)
+ */
+ hlist_nulls_add_head_rcu(&obj->obj_node, list);
+ unlock_chain(); // typically a spin_unlock()
diff --git a/Documentation/RCU/rculist_nulls.txt b/Documentation/RCU/rculist_nulls.txt
deleted file mode 100644
index 18f9651ff23d..000000000000
--- a/Documentation/RCU/rculist_nulls.txt
+++ /dev/null
@@ -1,172 +0,0 @@
-Using hlist_nulls to protect read-mostly linked lists and
-objects using SLAB_DESTROY_BY_RCU allocations.
-
-Please read the basics in Documentation/RCU/listRCU.txt
-
-Using special makers (called 'nulls') is a convenient way
-to solve following problem :
-
-A typical RCU linked list managing objects which are
-allocated with SLAB_DESTROY_BY_RCU kmem_cache can
-use following algos :
-
-1) Lookup algo
---------------
-rcu_read_lock()
-begin:
-obj = lockless_lookup(key);
-if (obj) {
- if (!try_get_ref(obj)) // might fail for free objects
- goto begin;
- /*
- * Because a writer could delete object, and a writer could
- * reuse these object before the RCU grace period, we
- * must check key after getting the reference on object
- */
- if (obj->key != key) { // not the object we expected
- put_ref(obj);
- goto begin;
- }
-}
-rcu_read_unlock();
-
-Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu()
-but a version with an additional memory barrier (smp_rmb())
-
-lockless_lookup(key)
-{
- struct hlist_node *node, *next;
- for (pos = rcu_dereference((head)->first);
- pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
- ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
- pos = rcu_dereference(next))
- if (obj->key == key)
- return obj;
- return NULL;
-
-And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb() :
-
- struct hlist_node *node;
- for (pos = rcu_dereference((head)->first);
- pos && ({ prefetch(pos->next); 1; }) &&
- ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
- pos = rcu_dereference(pos->next))
- if (obj->key == key)
- return obj;
- return NULL;
-}
-
-Quoting Corey Minyard :
-
-"If the object is moved from one list to another list in-between the
- time the hash is calculated and the next field is accessed, and the
- object has moved to the end of a new list, the traversal will not
- complete properly on the list it should have, since the object will
- be on the end of the new list and there's not a way to tell it's on a
- new list and restart the list traversal. I think that this can be
- solved by pre-fetching the "next" field (with proper barriers) before
- checking the key."
-
-2) Insert algo :
-----------------
-
-We need to make sure a reader cannot read the new 'obj->obj_next' value
-and previous value of 'obj->key'. Or else, an item could be deleted
-from a chain, and inserted into another chain. If new chain was empty
-before the move, 'next' pointer is NULL, and lockless reader can
-not detect it missed following items in original chain.
-
-/*
- * Please note that new inserts are done at the head of list,
- * not in the middle or end.
- */
-obj = kmem_cache_alloc(...);
-lock_chain(); // typically a spin_lock()
-obj->key = key;
-/*
- * we need to make sure obj->key is updated before obj->next
- * or obj->refcnt
- */
-smp_wmb();
-atomic_set(&obj->refcnt, 1);
-hlist_add_head_rcu(&obj->obj_node, list);
-unlock_chain(); // typically a spin_unlock()
-
-
-3) Remove algo
---------------
-Nothing special here, we can use a standard RCU hlist deletion.
-But thanks to SLAB_DESTROY_BY_RCU, beware a deleted object can be reused
-very very fast (before the end of RCU grace period)
-
-if (put_last_reference_on(obj) {
- lock_chain(); // typically a spin_lock()
- hlist_del_init_rcu(&obj->obj_node);
- unlock_chain(); // typically a spin_unlock()
- kmem_cache_free(cachep, obj);
-}
-
-
-
---------------------------------------------------------------------------
-With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
-and extra smp_wmb() in insert function.
-
-For example, if we choose to store the slot number as the 'nulls'
-end-of-list marker for each slot of the hash table, we can detect
-a race (some writer did a delete and/or a move of an object
-to another chain) checking the final 'nulls' value if
-the lookup met the end of chain. If final 'nulls' value
-is not the slot number, then we must restart the lookup at
-the beginning. If the object was moved to the same chain,
-then the reader doesn't care : It might eventually
-scan the list again without harm.
-
-
-1) lookup algo
-
- head = &table[slot];
- rcu_read_lock();
-begin:
- hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
- if (obj->key == key) {
- if (!try_get_ref(obj)) // might fail for free objects
- goto begin;
- if (obj->key != key) { // not the object we expected
- put_ref(obj);
- goto begin;
- }
- goto out;
- }
-/*
- * if the nulls value we got at the end of this lookup is
- * not the expected one, we must restart lookup.
- * We probably met an item that was moved to another chain.
- */
- if (get_nulls_value(node) != slot)
- goto begin;
- obj = NULL;
-
-out:
- rcu_read_unlock();
-
-2) Insert function :
---------------------
-
-/*
- * Please note that new inserts are done at the head of list,
- * not in the middle or end.
- */
-obj = kmem_cache_alloc(cachep);
-lock_chain(); // typically a spin_lock()
-obj->key = key;
-/*
- * changes to obj->key must be visible before refcnt one
- */
-smp_wmb();
-atomic_set(&obj->refcnt, 1);
-/*
- * insert obj in RCU way (readers might be traversing chain)
- */
-hlist_nulls_add_head_rcu(&obj->obj_node, list);
-unlock_chain(); // typically a spin_unlock()
diff --git a/Documentation/RCU/rcuref.rst b/Documentation/RCU/rcuref.rst
new file mode 100644
index 000000000000..b33aeb14fde3
--- /dev/null
+++ b/Documentation/RCU/rcuref.rst
@@ -0,0 +1,158 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================================================
+Reference-count design for elements of lists/arrays protected by RCU
+====================================================================
+
+
+Please note that the percpu-ref feature is likely your first
+stop if you need to combine reference counts and RCU. Please see
+include/linux/percpu-refcount.h for more information. However, in
+those unusual cases where percpu-ref would consume too much memory,
+please read on.
+
+------------------------------------------------------------------------
+
+Reference counting on elements of lists which are protected by traditional
+reader/writer spinlocks or semaphores are straightforward:
+
+CODE LISTING A::
+
+ 1. 2.
+ add() search_and_reference()
+ { {
+ alloc_object read_lock(&list_lock);
+ ... search_for_element
+ atomic_set(&el->rc, 1); atomic_inc(&el->rc);
+ write_lock(&list_lock); ...
+ add_element read_unlock(&list_lock);
+ ... ...
+ write_unlock(&list_lock); }
+ }
+
+ 3. 4.
+ release_referenced() delete()
+ { {
+ ... write_lock(&list_lock);
+ if(atomic_dec_and_test(&el->rc)) ...
+ kfree(el);
+ ... remove_element
+ } write_unlock(&list_lock);
+ ...
+ if (atomic_dec_and_test(&el->rc))
+ kfree(el);
+ ...
+ }
+
+If this list/array is made lock free using RCU as in changing the
+write_lock() in add() and delete() to spin_lock() and changing read_lock()
+in search_and_reference() to rcu_read_lock(), the atomic_inc() in
+search_and_reference() could potentially hold reference to an element which
+has already been deleted from the list/array. Use atomic_inc_not_zero()
+in this scenario as follows:
+
+CODE LISTING B::
+
+ 1. 2.
+ add() search_and_reference()
+ { {
+ alloc_object rcu_read_lock();
+ ... search_for_element
+ atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) {
+ spin_lock(&list_lock); rcu_read_unlock();
+ return FAIL;
+ add_element }
+ ... ...
+ spin_unlock(&list_lock); rcu_read_unlock();
+ } }
+ 3. 4.
+ release_referenced() delete()
+ { {
+ ... spin_lock(&list_lock);
+ if (atomic_dec_and_test(&el->rc)) ...
+ call_rcu(&el->head, el_free); remove_element
+ ... spin_unlock(&list_lock);
+ } ...
+ if (atomic_dec_and_test(&el->rc))
+ call_rcu(&el->head, el_free);
+ ...
+ }
+
+Sometimes, a reference to the element needs to be obtained in the
+update (write) stream. In such cases, atomic_inc_not_zero() might be
+overkill, since we hold the update-side spinlock. One might instead
+use atomic_inc() in such cases.
+
+It is not always convenient to deal with "FAIL" in the
+search_and_reference() code path. In such cases, the
+atomic_dec_and_test() may be moved from delete() to el_free()
+as follows:
+
+CODE LISTING C::
+
+ 1. 2.
+ add() search_and_reference()
+ { {
+ alloc_object rcu_read_lock();
+ ... search_for_element
+ atomic_set(&el->rc, 1); atomic_inc(&el->rc);
+ spin_lock(&list_lock); ...
+
+ add_element rcu_read_unlock();
+ ... }
+ spin_unlock(&list_lock); 4.
+ } delete()
+ 3. {
+ release_referenced() spin_lock(&list_lock);
+ { ...
+ ... remove_element
+ if (atomic_dec_and_test(&el->rc)) spin_unlock(&list_lock);
+ kfree(el); ...
+ ... call_rcu(&el->head, el_free);
+ } ...
+ 5. }
+ void el_free(struct rcu_head *rhp)
+ {
+ release_referenced();
+ }
+
+The key point is that the initial reference added by add() is not removed
+until after a grace period has elapsed following removal. This means that
+search_and_reference() cannot find this element, which means that the value
+of el->rc cannot increase. Thus, once it reaches zero, there are no
+readers that can or ever will be able to reference the element. The
+element can therefore safely be freed. This in turn guarantees that if
+any reader finds the element, that reader may safely acquire a reference
+without checking the value of the reference counter.
+
+A clear advantage of the RCU-based pattern in listing C over the one
+in listing B is that any call to search_and_reference() that locates
+a given object will succeed in obtaining a reference to that object,
+even given a concurrent invocation of delete() for that same object.
+Similarly, a clear advantage of both listings B and C over listing A is
+that a call to delete() is not delayed even if there are an arbitrarily
+large number of calls to search_and_reference() searching for the same
+object that delete() was invoked on. Instead, all that is delayed is
+the eventual invocation of kfree(), which is usually not a problem on
+modern computer systems, even the small ones.
+
+In cases where delete() can sleep, synchronize_rcu() can be called from
+delete(), so that el_free() can be subsumed into delete as follows::
+
+ 4.
+ delete()
+ {
+ spin_lock(&list_lock);
+ ...
+ remove_element
+ spin_unlock(&list_lock);
+ ...
+ synchronize_rcu();
+ if (atomic_dec_and_test(&el->rc))
+ kfree(el);
+ ...
+ }
+
+As additional examples in the kernel, the pattern in listing C is used by
+reference counting of struct pid, while the pattern in listing B is used by
+struct posix_acl.
diff --git a/Documentation/RCU/rcuref.txt b/Documentation/RCU/rcuref.txt
deleted file mode 100644
index 613033ff2b9b..000000000000
--- a/Documentation/RCU/rcuref.txt
+++ /dev/null
@@ -1,132 +0,0 @@
-Reference-count design for elements of lists/arrays protected by RCU.
-
-
-Please note that the percpu-ref feature is likely your first
-stop if you need to combine reference counts and RCU. Please see
-include/linux/percpu-refcount.h for more information. However, in
-those unusual cases where percpu-ref would consume too much memory,
-please read on.
-
-------------------------------------------------------------------------
-
-Reference counting on elements of lists which are protected by traditional
-reader/writer spinlocks or semaphores are straightforward:
-
-1. 2.
-add() search_and_reference()
-{ {
- alloc_object read_lock(&list_lock);
- ... search_for_element
- atomic_set(&el->rc, 1); atomic_inc(&el->rc);
- write_lock(&list_lock); ...
- add_element read_unlock(&list_lock);
- ... ...
- write_unlock(&list_lock); }
-}
-
-3. 4.
-release_referenced() delete()
-{ {
- ... write_lock(&list_lock);
- atomic_dec(&el->rc, relfunc) ...
- ... remove_element
-} write_unlock(&list_lock);
- ...
- if (atomic_dec_and_test(&el->rc))
- kfree(el);
- ...
- }
-
-If this list/array is made lock free using RCU as in changing the
-write_lock() in add() and delete() to spin_lock() and changing read_lock()
-in search_and_reference() to rcu_read_lock(), the atomic_inc() in
-search_and_reference() could potentially hold reference to an element which
-has already been deleted from the list/array. Use atomic_inc_not_zero()
-in this scenario as follows:
-
-1. 2.
-add() search_and_reference()
-{ {
- alloc_object rcu_read_lock();
- ... search_for_element
- atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) {
- spin_lock(&list_lock); rcu_read_unlock();
- return FAIL;
- add_element }
- ... ...
- spin_unlock(&list_lock); rcu_read_unlock();
-} }
-3. 4.
-release_referenced() delete()
-{ {
- ... spin_lock(&list_lock);
- if (atomic_dec_and_test(&el->rc)) ...
- call_rcu(&el->head, el_free); remove_element
- ... spin_unlock(&list_lock);
-} ...
- if (atomic_dec_and_test(&el->rc))
- call_rcu(&el->head, el_free);
- ...
- }
-
-Sometimes, a reference to the element needs to be obtained in the
-update (write) stream. In such cases, atomic_inc_not_zero() might be
-overkill, since we hold the update-side spinlock. One might instead
-use atomic_inc() in such cases.
-
-It is not always convenient to deal with "FAIL" in the
-search_and_reference() code path. In such cases, the
-atomic_dec_and_test() may be moved from delete() to el_free()
-as follows:
-
-1. 2.
-add() search_and_reference()
-{ {
- alloc_object rcu_read_lock();
- ... search_for_element
- atomic_set(&el->rc, 1); atomic_inc(&el->rc);
- spin_lock(&list_lock); ...
-
- add_element rcu_read_unlock();
- ... }
- spin_unlock(&list_lock); 4.
-} delete()
-3. {
-release_referenced() spin_lock(&list_lock);
-{ ...
- ... remove_element
- if (atomic_dec_and_test(&el->rc)) spin_unlock(&list_lock);
- kfree(el); ...
- ... call_rcu(&el->head, el_free);
-} ...
-5. }
-void el_free(struct rcu_head *rhp)
-{
- release_referenced();
-}
-
-The key point is that the initial reference added by add() is not removed
-until after a grace period has elapsed following removal. This means that
-search_and_reference() cannot find this element, which means that the value
-of el->rc cannot increase. Thus, once it reaches zero, there are no
-readers that can or ever will be able to reference the element. The
-element can therefore safely be freed. This in turn guarantees that if
-any reader finds the element, that reader may safely acquire a reference
-without checking the value of the reference counter.
-
-In cases where delete() can sleep, synchronize_rcu() can be called from
-delete(), so that el_free() can be subsumed into delete as follows:
-
-4.
-delete()
-{
- spin_lock(&list_lock);
- ...
- remove_element
- spin_unlock(&list_lock);
- ...
- synchronize_rcu();
- if (atomic_dec_and_test(&el->rc))
- kfree(el);
- ...
-}
diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
new file mode 100644
index 000000000000..d7c8eff63317
--- /dev/null
+++ b/Documentation/RCU/stallwarn.rst
@@ -0,0 +1,491 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Using RCU's CPU Stall Detector
+==============================
+
+This document first discusses what sorts of issues RCU's CPU stall
+detector can locate, and then discusses kernel parameters and Kconfig
+options that can be used to fine-tune the detector's operation. Finally,
+this document explains the stall detector's "splat" format.
+
+
+What Causes RCU CPU Stall Warnings?
+===================================
+
+So your kernel printed an RCU CPU stall warning. The next question is
+"What caused it?" The following problems can result in RCU CPU stall
+warnings:
+
+- A CPU looping in an RCU read-side critical section.
+
+- A CPU looping with interrupts disabled.
+
+- A CPU looping with preemption disabled.
+
+- A CPU looping with bottom halves disabled.
+
+- For !CONFIG_PREEMPTION kernels, a CPU looping anywhere in the
+ kernel without potentially invoking schedule(). If the looping
+ in the kernel is really expected and desirable behavior, you
+ might need to add some calls to cond_resched().
+
+- Booting Linux using a console connection that is too slow to
+ keep up with the boot-time console-message rate. For example,
+ a 115Kbaud serial console can be *way* too slow to keep up
+ with boot-time message rates, and will frequently result in
+ RCU CPU stall warning messages. Especially if you have added
+ debug printk()s.
+
+- Anything that prevents RCU's grace-period kthreads from running.
+ This can result in the "All QSes seen" console-log message.
+ This message will include information on when the kthread last
+ ran and how often it should be expected to run. It can also
+ result in the ``rcu_.*kthread starved for`` console-log message,
+ which will include additional debugging information.
+
+- A CPU-bound real-time task in a CONFIG_PREEMPTION kernel, which might
+ happen to preempt a low-priority task in the middle of an RCU
+ read-side critical section. This is especially damaging if
+ that low-priority task is not permitted to run on any other CPU,
+ in which case the next RCU grace period can never complete, which
+ will eventually cause the system to run out of memory and hang.
+ While the system is in the process of running itself out of
+ memory, you might see stall-warning messages.
+
+- A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
+ is running at a higher priority than the RCU softirq threads.
+ This will prevent RCU callbacks from ever being invoked,
+ and in a CONFIG_PREEMPT_RCU kernel will further prevent
+ RCU grace periods from ever completing. Either way, the
+ system will eventually run out of memory and hang. In the
+ CONFIG_PREEMPT_RCU case, you might see stall-warning
+ messages.
+
+ You can use the rcutree.kthread_prio kernel boot parameter to
+ increase the scheduling priority of RCU's kthreads, which can
+ help avoid this problem. However, please note that doing this
+ can increase your system's context-switch rate and thus degrade
+ performance.
+
+- A periodic interrupt whose handler takes longer than the time
+ interval between successive pairs of interrupts. This can
+ prevent RCU's kthreads and softirq handlers from running.
+ Note that certain high-overhead debugging options, for example
+ the function_graph tracer, can result in interrupt handler taking
+ considerably longer than normal, which can in turn result in
+ RCU CPU stall warnings.
+
+- Testing a workload on a fast system, tuning the stall-warning
+ timeout down to just barely avoid RCU CPU stall warnings, and then
+ running the same workload with the same stall-warning timeout on a
+ slow system. Note that thermal throttling and on-demand governors
+ can cause a single system to be sometimes fast and sometimes slow!
+
+- A hardware or software issue shuts off the scheduler-clock
+ interrupt on a CPU that is not in dyntick-idle mode. This
+ problem really has happened, and seems to be most likely to
+ result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels.
+
+- A hardware or software issue that prevents time-based wakeups
+ from occurring. These issues can range from misconfigured or
+ buggy timer hardware through bugs in the interrupt or exception
+ path (whether hardware, firmware, or software) through bugs
+ in Linux's timer subsystem through bugs in the scheduler, and,
+ yes, even including bugs in RCU itself. It can also result in
+ the ``rcu_.*timer wakeup didn't happen for`` console-log message,
+ which will include additional debugging information.
+
+- A timer issue causes time to appear to jump forward, so that RCU
+ believes that the RCU CPU stall-warning timeout has been exceeded
+ when in fact much less time has passed. This could be due to
+ timer hardware bugs, timer driver bugs, or even corruption of
+ the "jiffies" global variable. These sorts of timer hardware
+ and driver bugs are not uncommon when testing new hardware.
+
+- A low-level kernel issue that either fails to invoke one of the
+ variants of rcu_eqs_enter(true), rcu_eqs_exit(true), ct_idle_enter(),
+ ct_idle_exit(), ct_irq_enter(), or ct_irq_exit() on the one
+ hand, or that invokes one of them too many times on the other.
+ Historically, the most frequent issue has been an omission
+ of either irq_enter() or irq_exit(), which in turn invoke
+ ct_irq_enter() or ct_irq_exit(), respectively. Building your
+ kernel with CONFIG_RCU_EQS_DEBUG=y can help track down these types
+ of issues, which sometimes arise in architecture-specific code.
+
+- A bug in the RCU implementation.
+
+- A hardware failure. This is quite unlikely, but is not at all
+ 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 to the realization
+ that the CPU had failed.
+
+The RCU, RCU-sched, RCU-tasks, and RCU-tasks-trace implementations have
+CPU stall warning. Note that SRCU does *not* have CPU stall warnings.
+Please note that RCU only detects CPU stalls when there is a grace period
+in progress. No grace period, no CPU stall warnings.
+
+To diagnose the cause of the stall, inspect the stack traces.
+The offending function will usually be near the top of the stack.
+If you have a series of stall warnings from a single extended stall,
+comparing the stack traces can often help determine where the stall
+is occurring, which will usually be in the function nearest the top of
+that portion of the stack which remains the same from trace to trace.
+If you can reliably trigger the stall, ftrace can be quite helpful.
+
+RCU bugs can often be debugged with the help of CONFIG_RCU_TRACE
+and with RCU's event tracing. For information on RCU's event tracing,
+see include/trace/events/rcu.h.
+
+
+Fine-Tuning the RCU CPU Stall Detector
+======================================
+
+The rcuupdate.rcu_cpu_stall_suppress module parameter disables RCU's
+CPU stall detector, which detects conditions that unduly delay RCU grace
+periods. This module parameter enables CPU stall detection by default,
+but may be overridden via boot-time parameter or at runtime via sysfs.
+The stall detector's idea of what constitutes "unduly delayed" is
+controlled by a set of kernel configuration variables and cpp macros:
+
+CONFIG_RCU_CPU_STALL_TIMEOUT
+----------------------------
+
+ This kernel configuration parameter defines the period of time
+ that RCU will wait from the beginning of a grace period until it
+ issues an RCU CPU stall warning. This time period is normally
+ 21 seconds.
+
+ This configuration parameter may be changed at runtime via the
+ /sys/module/rcupdate/parameters/rcu_cpu_stall_timeout, however
+ this parameter is checked only at the beginning of a cycle.
+ So if you are 10 seconds into a 40-second stall, setting this
+ sysfs parameter to (say) five will shorten the timeout for the
+ *next* stall, or the following warning for the current stall
+ (assuming the stall lasts long enough). It will not affect the
+ timing of the next warning for the current stall.
+
+ Stall-warning messages may be enabled and disabled completely via
+ /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
+
+CONFIG_RCU_EXP_CPU_STALL_TIMEOUT
+--------------------------------
+
+ Same as the CONFIG_RCU_CPU_STALL_TIMEOUT parameter but only for
+ the expedited grace period. This parameter defines the period
+ of time that RCU will wait from the beginning of an expedited
+ grace period until it issues an RCU CPU stall warning. This time
+ period is normally 20 milliseconds on Android devices. A zero
+ value causes the CONFIG_RCU_CPU_STALL_TIMEOUT value to be used,
+ after conversion to milliseconds.
+
+ This configuration parameter may be changed at runtime via the
+ /sys/module/rcupdate/parameters/rcu_exp_cpu_stall_timeout, however
+ this parameter is checked only at the beginning of a cycle. If you
+ are in a current stall cycle, setting it to a new value will change
+ the timeout for the -next- stall.
+
+ Stall-warning messages may be enabled and disabled completely via
+ /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
+
+RCU_STALL_DELAY_DELTA
+---------------------
+
+ Although the lockdep facility is extremely useful, it does add
+ some overhead. Therefore, under CONFIG_PROVE_RCU, the
+ RCU_STALL_DELAY_DELTA macro allows five extra seconds before
+ giving an RCU CPU stall warning message. (This is a cpp
+ macro, not a kernel configuration parameter.)
+
+RCU_STALL_RAT_DELAY
+-------------------
+
+ The CPU stall detector tries to make the offending CPU print its
+ own warnings, as this often gives better-quality stack traces.
+ However, if the offending CPU does not detect its own stall in
+ the number of jiffies specified by RCU_STALL_RAT_DELAY, then
+ some other CPU will complain. This delay is normally set to
+ two jiffies. (This is a cpp macro, not a kernel configuration
+ parameter.)
+
+rcupdate.rcu_task_stall_timeout
+-------------------------------
+
+ This boot/sysfs parameter controls the RCU-tasks and
+ RCU-tasks-trace stall warning intervals. A value of zero or less
+ suppresses RCU-tasks stall warnings. A positive value sets the
+ stall-warning interval in seconds. An RCU-tasks stall warning
+ starts with the line:
+
+ INFO: rcu_tasks detected stalls on tasks:
+
+ And continues with the output of sched_show_task() for each
+ task stalling the current RCU-tasks grace period.
+
+ An RCU-tasks-trace stall warning starts (and continues) similarly:
+
+ INFO: rcu_tasks_trace detected stalls on tasks
+
+
+Interpreting RCU's CPU Stall-Detector "Splats"
+==============================================
+
+For non-RCU-tasks flavors of RCU, when a CPU detects that some other
+CPU is stalling, it will print a message similar to the following::
+
+ INFO: rcu_sched detected stalls on CPUs/tasks:
+ 2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0
+ 16-...: (0 ticks this GP) idle=81c/0/0 softirq=764/764 fqs=0
+ (detected by 32, t=2603 jiffies, g=7075, q=625)
+
+This message indicates that CPU 32 detected that CPUs 2 and 16 were both
+causing stalls, and that the stall was affecting RCU-sched. This message
+will normally be followed by stack dumps for each CPU. Please note that
+PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that
+the tasks will be indicated by PID, for example, "P3421". It is even
+possible for an rcu_state stall to be caused by both CPUs *and* tasks,
+in which case the offending CPUs and tasks will all be called out in the list.
+In some cases, CPUs will detect themselves stalling, which will result
+in a self-detected stall.
+
+CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with
+the RCU core for the past three grace periods. In contrast, CPU 16's "(0
+ticks this GP)" indicates that this CPU has not taken any scheduling-clock
+interrupts during the current stalled grace period.
+
+The "idle=" portion of the message prints the dyntick-idle state.
+The hex number before the first "/" is the low-order 16 bits of the
+dynticks counter, which will have an even-numbered value if the CPU
+is in dyntick-idle mode and an odd-numbered value otherwise. The hex
+number between the two "/"s is the value of the nesting, which will be
+a small non-negative number if in the idle loop (as shown above) and a
+very large positive number otherwise. The number following the final
+"/" is the NMI nesting, which will be a small non-negative number.
+
+The "softirq=" portion of the message tracks the number of RCU softirq
+handlers that the stalled CPU has executed. The number before the "/"
+is the number that had executed since boot at the time that this CPU
+last noted the beginning of a grace period, which might be the current
+(stalled) grace period, or it might be some earlier grace period (for
+example, if the CPU might have been in dyntick-idle mode for an extended
+time period). The number after the "/" is the number that have executed
+since boot until the current time. If this latter number stays constant
+across repeated stall-warning messages, it is possible that RCU's softirq
+handlers are no longer able to execute on this CPU. This can happen if
+the stalled CPU is spinning with interrupts are disabled, or, in -rt
+kernels, if a high-priority process is starving RCU's softirq handler.
+
+The "fqs=" shows the number of force-quiescent-state idle/offline
+detection passes that the grace-period kthread has made across this
+CPU since the last time that this CPU noted the beginning of a grace
+period.
+
+The "detected by" line indicates which CPU detected the stall (in this
+case, CPU 32), how many jiffies have elapsed since the start of the grace
+period (in this case 2603), the grace-period sequence number (7075), and
+an estimate of the total number of RCU callbacks queued across all CPUs
+(625 in this case).
+
+If the grace period ends just as the stall warning starts printing,
+there will be a spurious stall-warning message, which will include
+the following::
+
+ INFO: Stall ended before state dump start
+
+This is rare, but does happen from time to time in real life. It is also
+possible for a zero-jiffy stall to be flagged in this case, depending
+on how the stall warning and the grace-period initialization happen to
+interact. Please note that it is not possible to entirely eliminate this
+sort of false positive without resorting to things like stop_machine(),
+which is overkill for this sort of problem.
+
+If all CPUs and tasks have passed through quiescent states, but the
+grace period has nevertheless failed to end, the stall-warning splat
+will include something like the following::
+
+ All QSes seen, last rcu_preempt kthread activity 23807 (4297905177-4297881370), jiffies_till_next_fqs=3, root ->qsmask 0x0
+
+The "23807" indicates that it has been more than 23 thousand jiffies
+since the grace-period kthread ran. The "jiffies_till_next_fqs"
+indicates how frequently that kthread should run, giving the number
+of jiffies between force-quiescent-state scans, in this case three,
+which is way less than 23807. Finally, the root rcu_node structure's
+->qsmask field is printed, which will normally be zero.
+
+If the relevant grace-period kthread has been unable to run prior to
+the stall warning, as was the case in the "All QSes seen" line above,
+the following additional line is printed::
+
+ rcu_sched kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5
+ Unless rcu_sched kthread gets sufficient CPU time, OOM is now expected behavior.
+
+Starving the grace-period kthreads of CPU time can of course result
+in RCU CPU stall warnings even when all CPUs and tasks have passed
+through the required quiescent states. The "g" number shows the current
+grace-period sequence number, the "f" precedes the ->gp_flags command
+to the grace-period kthread, the "RCU_GP_WAIT_FQS" indicates that the
+kthread is waiting for a short timeout, the "state" precedes value of the
+task_struct ->state field, and the "cpu" indicates that the grace-period
+kthread last ran on CPU 5.
+
+If the relevant grace-period kthread does not wake from FQS wait in a
+reasonable time, then the following additional line is printed::
+
+ kthread timer wakeup didn't happen for 23804 jiffies! g7076 f0x0 RCU_GP_WAIT_FQS(5) ->state=0x402
+
+The "23804" indicates that kthread's timer expired more than 23 thousand
+jiffies ago. The rest of the line has meaning similar to the kthread
+starvation case.
+
+Additionally, the following line is printed::
+
+ Possible timer handling issue on cpu=4 timer-softirq=11142
+
+Here "cpu" indicates that the grace-period kthread last ran on CPU 4,
+where it queued the fqs timer. The number following the "timer-softirq"
+is the current ``TIMER_SOFTIRQ`` count on cpu 4. If this value does not
+change on successive RCU CPU stall warnings, there is further reason to
+suspect a timer problem.
+
+These messages are usually followed by stack dumps of the CPUs and tasks
+involved in the stall. These stack traces can help you locate the cause
+of the stall, keeping in mind that the CPU detecting the stall will have
+an interrupt frame that is mainly devoted to detecting the stall.
+
+
+Multiple Warnings From One Stall
+================================
+
+If a stall lasts long enough, multiple stall-warning messages will
+be printed for it. The second and subsequent messages are printed at
+longer intervals, so that the time between (say) the first and second
+message will be about three times the interval between the beginning
+of the stall and the first message. It can be helpful to compare the
+stack dumps for the different messages for the same stalled grace period.
+
+
+Stall Warnings for Expedited Grace Periods
+==========================================
+
+If an expedited grace period detects a stall, it will place a message
+like the following in dmesg::
+
+ INFO: rcu_sched detected expedited stalls on CPUs/tasks: { 7-... } 21119 jiffies s: 73 root: 0x2/.
+
+This indicates that CPU 7 has failed to respond to a reschedule IPI.
+The three periods (".") following the CPU number indicate that the CPU
+is online (otherwise the first period would instead have been "O"),
+that the CPU was online at the beginning of the expedited grace period
+(otherwise the second period would have instead been "o"), and that
+the CPU has been online at least once since boot (otherwise, the third
+period would instead have been "N"). The number before the "jiffies"
+indicates that the expedited grace period has been going on for 21,119
+jiffies. The number following the "s:" indicates that the expedited
+grace-period sequence counter is 73. The fact that this last value is
+odd indicates that an expedited grace period is in flight. The number
+following "root:" is a bitmask that indicates which children of the root
+rcu_node structure correspond to CPUs and/or tasks that are blocking the
+current expedited grace period. If the tree had more than one level,
+additional hex numbers would be printed for the states of the other
+rcu_node structures in the tree.
+
+As with normal grace periods, PREEMPT_RCU builds can be stalled by
+tasks as well as by CPUs, and that the tasks will be indicated by PID,
+for example, "P3421".
+
+It is entirely possible to see stall warnings from normal and from
+expedited grace periods at about the same time during the same run.
+
+RCU_CPU_STALL_CPUTIME
+=====================
+
+In kernels built with CONFIG_RCU_CPU_STALL_CPUTIME=y or booted with
+rcupdate.rcu_cpu_stall_cputime=1, the following additional information
+is supplied with each RCU CPU stall warning::
+
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 624 45 0
+ rcu: cputime: 69 1 2425 ==> 2500(ms)
+
+These statistics are collected during the sampling period. The values
+in row "number:" are the number of hard interrupts, number of soft
+interrupts, and number of context switches on the stalled CPU. The
+first three values in row "cputime:" indicate the CPU time in
+milliseconds consumed by hard interrupts, soft interrupts, and tasks
+on the stalled CPU. The last number is the measurement interval, again
+in milliseconds. Because user-mode tasks normally do not cause RCU CPU
+stalls, these tasks are typically kernel tasks, which is why only the
+system CPU time are considered.
+
+The sampling period is shown as follows::
+
+ |<------------first timeout---------->|<-----second timeout----->|
+ |<--half timeout-->|<--half timeout-->| |
+ | |<--first period-->| |
+ | |<-----------second sampling period---------->|
+ | | | |
+ snapshot time point 1st-stall 2nd-stall
+
+The following describes four typical scenarios:
+
+1. A CPU looping with interrupts disabled.
+
+ ::
+
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 0 0 0
+ rcu: cputime: 0 0 0 ==> 2500(ms)
+
+ Because interrupts have been disabled throughout the measurement
+ interval, there are no interrupts and no context switches.
+ Furthermore, because CPU time consumption was measured using interrupt
+ handlers, the system CPU consumption is misleadingly measured as zero.
+ This scenario will normally also have "(0 ticks this GP)" printed on
+ this CPU's summary line.
+
+2. A CPU looping with bottom halves disabled.
+
+ This is similar to the previous example, but with non-zero number of
+ and CPU time consumed by hard interrupts, along with non-zero CPU
+ time consumed by in-kernel execution::
+
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 624 0 0
+ rcu: cputime: 49 0 2446 ==> 2500(ms)
+
+ The fact that there are zero softirqs gives a hint that these were
+ disabled, perhaps via local_bh_disable(). It is of course possible
+ that there were no softirqs, perhaps because all events that would
+ result in softirq execution are confined to other CPUs. In this case,
+ the diagnosis should continue as shown in the next example.
+
+3. A CPU looping with preemption disabled.
+
+ Here, only the number of context switches is zero::
+
+ rcu: hardirqs softirqs csw/system
+ rcu: number: 624 45 0
+ rcu: cputime: 69 1 2425 ==> 2500(ms)
+
+ This situation hints that the stalled CPU was looping with preemption
+ disabled.
+
+4. No looping, but massive hard and soft interrupts.
+
+ ::
+
+ rcu: hardirqs softirqs csw/system
+ rcu: number: xx xx 0
+ rcu: cputime: xx xx 0 ==> 2500(ms)
+
+ Here, the number and CPU time of hard interrupts are all non-zero,
+ but the number of context switches and the in-kernel CPU time consumed
+ are zero. The number and cputime of soft interrupts will usually be
+ non-zero, but could be zero, for example, if the CPU was spinning
+ within a single hard interrupt handler.
+
+ If this type of RCU CPU stall warning can be reproduced, you can
+ narrow it down by looking at /proc/interrupts or by writing code to
+ trace each interrupt, for example, by referring to show_interrupts().
diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt
deleted file mode 100644
index b57c0c1cdac6..000000000000
--- a/Documentation/RCU/stallwarn.txt
+++ /dev/null
@@ -1,250 +0,0 @@
-Using RCU's CPU Stall Detector
-
-The rcu_cpu_stall_suppress module parameter enables RCU's CPU stall
-detector, which detects conditions that unduly delay RCU grace periods.
-This module parameter enables CPU stall detection by default, but
-may be overridden via boot-time parameter or at runtime via sysfs.
-The stall detector's idea of what constitutes "unduly delayed" is
-controlled by a set of kernel configuration variables and cpp macros:
-
-CONFIG_RCU_CPU_STALL_TIMEOUT
-
- This kernel configuration parameter defines the period of time
- that RCU will wait from the beginning of a grace period until it
- issues an RCU CPU stall warning. This time period is normally
- 21 seconds.
-
- This configuration parameter may be changed at runtime via the
- /sys/module/rcupdate/parameters/rcu_cpu_stall_timeout, however
- this parameter is checked only at the beginning of a cycle.
- So if you are 10 seconds into a 40-second stall, setting this
- sysfs parameter to (say) five will shorten the timeout for the
- -next- stall, or the following warning for the current stall
- (assuming the stall lasts long enough). It will not affect the
- timing of the next warning for the current stall.
-
- Stall-warning messages may be enabled and disabled completely via
- /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
-
-CONFIG_RCU_CPU_STALL_INFO
-
- This kernel configuration parameter causes the stall warning to
- print out additional per-CPU diagnostic information, including
- information on scheduling-clock ticks and RCU's idle-CPU tracking.
-
-RCU_STALL_DELAY_DELTA
-
- Although the lockdep facility is extremely useful, it does add
- some overhead. Therefore, under CONFIG_PROVE_RCU, the
- RCU_STALL_DELAY_DELTA macro allows five extra seconds before
- giving an RCU CPU stall warning message. (This is a cpp
- macro, not a kernel configuration parameter.)
-
-RCU_STALL_RAT_DELAY
-
- The CPU stall detector tries to make the offending CPU print its
- own warnings, as this often gives better-quality stack traces.
- However, if the offending CPU does not detect its own stall in
- the number of jiffies specified by RCU_STALL_RAT_DELAY, then
- some other CPU will complain. This delay is normally set to
- two jiffies. (This is a cpp macro, not a kernel configuration
- parameter.)
-
-rcupdate.rcu_task_stall_timeout
-
- This boot/sysfs parameter controls the RCU-tasks stall warning
- interval. A value of zero or less suppresses RCU-tasks stall
- warnings. A positive value sets the stall-warning interval
- in jiffies. An RCU-tasks stall warning starts wtih the line:
-
- INFO: rcu_tasks detected stalls on tasks:
-
- And continues with the output of sched_show_task() for each
- task stalling the current RCU-tasks grace period.
-
-For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling,
-it will print a message similar to the following:
-
-INFO: rcu_sched_state detected stall on CPU 5 (t=2500 jiffies)
-
-This message indicates that CPU 5 detected that it was causing a stall,
-and that the stall was affecting RCU-sched. This message will normally be
-followed by a stack dump of the offending CPU. On TREE_RCU kernel builds,
-RCU and RCU-sched are implemented by the same underlying mechanism,
-while on PREEMPT_RCU kernel builds, RCU is instead implemented
-by rcu_preempt_state.
-
-On the other hand, if the offending CPU fails to print out a stall-warning
-message quickly enough, some other CPU will print a message similar to
-the following:
-
-INFO: rcu_bh_state detected stalls on CPUs/tasks: { 3 5 } (detected by 2, 2502 jiffies)
-
-This message indicates that CPU 2 detected that CPUs 3 and 5 were both
-causing stalls, and that the stall was affecting RCU-bh. This message
-will normally be followed by stack dumps for each CPU. Please note that
-PREEMPT_RCU builds can be stalled by tasks as well as by CPUs,
-and that the tasks will be indicated by PID, for example, "P3421".
-It is even possible for a rcu_preempt_state stall to be caused by both
-CPUs -and- tasks, in which case the offending CPUs and tasks will all
-be called out in the list.
-
-Finally, if the grace period ends just as the stall warning starts
-printing, there will be a spurious stall-warning message:
-
-INFO: rcu_bh_state detected stalls on CPUs/tasks: { } (detected by 4, 2502 jiffies)
-
-This is rare, but does happen from time to time in real life. It is also
-possible for a zero-jiffy stall to be flagged in this case, depending
-on how the stall warning and the grace-period initialization happen to
-interact. Please note that it is not possible to entirely eliminate this
-sort of false positive without resorting to things like stop_machine(),
-which is overkill for this sort of problem.
-
-If the CONFIG_RCU_CPU_STALL_INFO kernel configuration parameter is set,
-more information is printed with the stall-warning message, for example:
-
- INFO: rcu_preempt detected stall on CPU
- 0: (63959 ticks this GP) idle=241/3fffffffffffffff/0 softirq=82/543
- (t=65000 jiffies)
-
-In kernels with CONFIG_RCU_FAST_NO_HZ, even more information is
-printed:
-
- INFO: rcu_preempt detected stall on CPU
- 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 nonlazy_posted: 25 .D
- (t=65000 jiffies)
-
-The "(64628 ticks this GP)" indicates that this CPU has taken more
-than 64,000 scheduling-clock interrupts during the current stalled
-grace period. If the CPU was not yet aware of the current grace
-period (for example, if it was offline), then this part of the message
-indicates how many grace periods behind the CPU is.
-
-The "idle=" portion of the message prints the dyntick-idle state.
-The hex number before the first "/" is the low-order 12 bits of the
-dynticks counter, which will have an even-numbered value if the CPU is
-in dyntick-idle mode and an odd-numbered value otherwise. The hex
-number between the two "/"s is the value of the nesting, which will
-be a small positive number if in the idle loop and a very large positive
-number (as shown above) otherwise.
-
-The "softirq=" portion of the message tracks the number of RCU softirq
-handlers that the stalled CPU has executed. The number before the "/"
-is the number that had executed since boot at the time that this CPU
-last noted the beginning of a grace period, which might be the current
-(stalled) grace period, or it might be some earlier grace period (for
-example, if the CPU might have been in dyntick-idle mode for an extended
-time period. The number after the "/" is the number that have executed
-since boot until the current time. If this latter number stays constant
-across repeated stall-warning messages, it is possible that RCU's softirq
-handlers are no longer able to execute on this CPU. This can happen if
-the stalled CPU is spinning with interrupts are disabled, or, in -rt
-kernels, if a high-priority process is starving RCU's softirq handler.
-
-For CONFIG_RCU_FAST_NO_HZ kernels, the "last_accelerate:" prints the
-low-order 16 bits (in hex) of the jiffies counter when this CPU last
-invoked rcu_try_advance_all_cbs() from rcu_needs_cpu() or last invoked
-rcu_accelerate_cbs() from rcu_prepare_for_idle(). The "nonlazy_posted:"
-prints the number of non-lazy callbacks posted since the last call to
-rcu_needs_cpu(). Finally, an "L" indicates that there are currently
-no non-lazy callbacks ("." is printed otherwise, as shown above) and
-"D" indicates that dyntick-idle processing is enabled ("." is printed
-otherwise, for example, if disabled via the "nohz=" kernel boot parameter).
-
-If the relevant grace-period kthread has been unable to run prior to
-the stall warning, the following additional line is printed:
-
- rcu_preempt kthread starved for 2023 jiffies!
-
-Starving the grace-period kthreads of CPU time can of course result in
-RCU CPU stall warnings even when all CPUs and tasks have passed through
-the required quiescent states.
-
-
-Multiple Warnings From One Stall
-
-If a stall lasts long enough, multiple stall-warning messages will be
-printed for it. The second and subsequent messages are printed at
-longer intervals, so that the time between (say) the first and second
-message will be about three times the interval between the beginning
-of the stall and the first message.
-
-
-What Causes RCU CPU Stall Warnings?
-
-So your kernel printed an RCU CPU stall warning. The next question is
-"What caused it?" The following problems can result in RCU CPU stall
-warnings:
-
-o A CPU looping in an RCU read-side critical section.
-
-o A CPU looping with interrupts disabled. This condition can
- result in RCU-sched and RCU-bh stalls.
-
-o A CPU looping with preemption disabled. This condition can
- result in RCU-sched stalls and, if ksoftirqd is in use, RCU-bh
- stalls.
-
-o A CPU looping with bottom halves disabled. This condition can
- result in RCU-sched and RCU-bh stalls.
-
-o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the
- kernel without invoking schedule(). Note that cond_resched()
- does not necessarily prevent RCU CPU stall warnings. Therefore,
- if the looping in the kernel is really expected and desirable
- behavior, you might need to replace some of the cond_resched()
- calls with calls to cond_resched_rcu_qs().
-
-o Anything that prevents RCU's grace-period kthreads from running.
- This can result in the "All QSes seen" console-log message.
- This message will include information on when the kthread last
- ran and how often it should be expected to run.
-
-o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
- happen to preempt a low-priority task in the middle of an RCU
- read-side critical section. This is especially damaging if
- that low-priority task is not permitted to run on any other CPU,
- in which case the next RCU grace period can never complete, which
- will eventually cause the system to run out of memory and hang.
- While the system is in the process of running itself out of
- memory, you might see stall-warning messages.
-
-o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
- is running at a higher priority than the RCU softirq threads.
- This will prevent RCU callbacks from ever being invoked,
- and in a CONFIG_PREEMPT_RCU kernel will further prevent
- RCU grace periods from ever completing. Either way, the
- system will eventually run out of memory and hang. In the
- CONFIG_PREEMPT_RCU case, you might see stall-warning
- messages.
-
-o A hardware or software issue shuts off the scheduler-clock
- interrupt on a CPU that is not in dyntick-idle mode. This
- problem really has happened, and seems to be most likely to
- result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels.
-
-o A bug in the RCU implementation.
-
-o A hardware failure. This is quite unlikely, but has occurred
- at least once in real life. 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 that the CPU had failed.
-
-The RCU, RCU-sched, RCU-bh, and RCU-tasks implementations have CPU stall
-warning. Note that SRCU does -not- have CPU stall warnings. Please note
-that RCU only detects CPU stalls when there is a grace period in progress.
-No grace period, no CPU stall warnings.
-
-To diagnose the cause of the stall, inspect the stack traces.
-The offending function will usually be near the top of the stack.
-If you have a series of stall warnings from a single extended stall,
-comparing the stack traces can often help determine where the stall
-is occurring, which will usually be in the function nearest the top of
-that portion of the stack which remains the same from trace to trace.
-If you can reliably trigger the stall, ftrace can be quite helpful.
-
-RCU bugs can often be debugged with the help of CONFIG_RCU_TRACE
-and with RCU's event tracing. For information on RCU's event tracing,
-see include/trace/events/rcu.h.
diff --git a/Documentation/RCU/torture.rst b/Documentation/RCU/torture.rst
new file mode 100644
index 000000000000..1ad5cc793811
--- /dev/null
+++ b/Documentation/RCU/torture.rst
@@ -0,0 +1,374 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+RCU Torture Test Operation
+==========================
+
+
+CONFIG_RCU_TORTURE_TEST
+=======================
+
+The CONFIG_RCU_TORTURE_TEST config option is available for all RCU
+implementations. It creates an rcutorture kernel module that can
+be loaded to run a torture test. The test periodically outputs
+status messages via printk(), which can be examined via the dmesg
+command (perhaps grepping for "torture"). The test is started
+when the module is loaded, and stops when the module is unloaded.
+
+Module parameters are prefixed by "rcutorture." in
+Documentation/admin-guide/kernel-parameters.txt.
+
+Output
+======
+
+The statistics output is as follows::
+
+ rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
+ rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767
+ rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0
+ rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0
+ rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0
+ rcu-torture:--- End of test: SUCCESS: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
+
+The command "dmesg | grep torture:" will extract this information on
+most systems. On more esoteric configurations, it may be necessary to
+use other commands to access the output of the printk()s used by
+the RCU torture test. The printk()s use KERN_ALERT, so they should
+be evident. ;-)
+
+The first and last lines show the rcutorture module parameters, and the
+last line shows either "SUCCESS" or "FAILURE", based on rcutorture's
+automatic determination as to whether RCU operated correctly.
+
+The entries are as follows:
+
+* "rtc": The hexadecimal address of the structure currently visible
+ to readers.
+
+* "ver": The number of times since boot that the RCU writer task
+ has changed the structure visible to readers.
+
+* "tfle": If non-zero, indicates that the "torture freelist"
+ containing structures to be placed into the "rtc" area is empty.
+ This condition is important, since it can fool you into thinking
+ that RCU is working when it is not. :-/
+
+* "rta": Number of structures allocated from the torture freelist.
+
+* "rtaf": Number of allocations from the torture freelist that have
+ failed due to the list being empty. It is not unusual for this
+ to be non-zero, but it is bad for it to be a large fraction of
+ the value indicated by "rta".
+
+* "rtf": Number of frees into the torture freelist.
+
+* "rtmbe": A non-zero value indicates that rcutorture believes that
+ rcu_assign_pointer() and rcu_dereference() are not working
+ correctly. This value should be zero.
+
+* "rtbe": A non-zero value indicates that one of the rcu_barrier()
+ family of functions is not working correctly.
+
+* "rtbke": rcutorture was unable to create the real-time kthreads
+ used to force RCU priority inversion. This value should be zero.
+
+* "rtbre": Although rcutorture successfully created the kthreads
+ used to force RCU priority inversion, it was unable to set them
+ to the real-time priority level of 1. This value should be zero.
+
+* "rtbf": The number of times that RCU priority boosting failed
+ to resolve RCU priority inversion.
+
+* "rtb": The number of times that rcutorture attempted to force
+ an RCU priority inversion condition. If you are testing RCU
+ priority boosting via the "test_boost" module parameter, this
+ value should be non-zero.
+
+* "nt": The number of times rcutorture ran RCU read-side code from
+ within a timer handler. This value should be non-zero only
+ if you specified the "irqreader" module parameter.
+
+* "Reader Pipe": Histogram of "ages" of structures seen by readers.
+ If any entries past the first two are non-zero, RCU is broken.
+ And rcutorture prints the error flag string "!!!" to make sure
+ you notice. The age of a newly allocated structure is zero,
+ it becomes one when removed from reader visibility, and is
+ incremented once per grace period subsequently -- and is freed
+ after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods.
+
+ The output displayed above was taken from a correctly working
+ RCU. If you want to see what it looks like when broken, break
+ it yourself. ;-)
+
+* "Reader Batch": Another histogram of "ages" of structures seen
+ by readers, but in terms of counter flips (or batches) rather
+ than in terms of grace periods. The legal number of non-zero
+ entries is again two. The reason for this separate view is that
+ it is sometimes easier to get the third entry to show up in the
+ "Reader Batch" list than in the "Reader Pipe" list.
+
+* "Free-Block Circulation": Shows the number of torture structures
+ that have reached a given point in the pipeline. The first element
+ should closely correspond to the number of structures allocated,
+ the second to the number that have been removed from reader view,
+ and all but the last remaining to the corresponding number of
+ passes through a grace period. The last entry should be zero,
+ as it is only incremented if a torture structure's counter
+ somehow gets incremented farther than it should.
+
+Different implementations of RCU can provide implementation-specific
+additional information. For example, Tree SRCU provides the following
+additional line::
+
+ srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6)
+
+This line shows the per-CPU counter state, in this case for Tree SRCU
+using a dynamically allocated srcu_struct (hence "srcud-" rather than
+"srcu-"). The numbers in parentheses are the values of the "old" and
+"current" counters for the corresponding CPU. The "idx" value maps the
+"old" and "current" values to the underlying array, and is useful for
+debugging. The final "T" entry contains the totals of the counters.
+
+Usage on Specific Kernel Builds
+===============================
+
+It is sometimes desirable to torture RCU on a specific kernel build,
+for example, when preparing to put that kernel build into production.
+In that case, the kernel should be built with CONFIG_RCU_TORTURE_TEST=m
+so that the test can be started using modprobe and terminated using rmmod.
+
+For example, the following script may be used to torture RCU::
+
+ #!/bin/sh
+
+ modprobe rcutorture
+ sleep 3600
+ rmmod rcutorture
+ dmesg | grep torture:
+
+The output can be manually inspected for the error flag of "!!!".
+One could of course create a more elaborate script that automatically
+checked for such errors. The "rmmod" command forces a "SUCCESS",
+"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first
+two are self-explanatory, while the last indicates that while there
+were no RCU failures, CPU-hotplug problems were detected.
+
+
+Usage on Mainline Kernels
+=========================
+
+When using rcutorture to test changes to RCU itself, it is often
+necessary to build a number of kernels in order to test that change
+across a broad range of combinations of the relevant Kconfig options
+and of the relevant kernel boot parameters. In this situation, use
+of modprobe and rmmod can be quite time-consuming and error-prone.
+
+Therefore, the tools/testing/selftests/rcutorture/bin/kvm.sh
+script is available for mainline testing for x86, arm64, and
+powerpc. By default, it will run the series of tests specified by
+tools/testing/selftests/rcutorture/configs/rcu/CFLIST, with each test
+running for 30 minutes within a guest OS using a minimal userspace
+supplied by an automatically generated initrd. After the tests are
+complete, the resulting build products and console output are analyzed
+for errors and the results of the runs are summarized.
+
+On larger systems, rcutorture testing can be accelerated by passing the
+--cpus argument to kvm.sh. For example, on a 64-CPU system, "--cpus 43"
+would use up to 43 CPUs to run tests concurrently, which as of v5.4 would
+complete all the scenarios in two batches, reducing the time to complete
+from about eight hours to about one hour (not counting the time to build
+the sixteen kernels). The "--dryrun sched" argument will not run tests,
+but rather tell you how the tests would be scheduled into batches. This
+can be useful when working out how many CPUs to specify in the --cpus
+argument.
+
+Not all changes require that all scenarios be run. For example, a change
+to Tree SRCU might run only the SRCU-N and SRCU-P scenarios using the
+--configs argument to kvm.sh as follows: "--configs 'SRCU-N SRCU-P'".
+Large systems can run multiple copies of the full set of scenarios,
+for example, a system with 448 hardware threads can run five instances
+of the full set concurrently. To make this happen::
+
+ kvm.sh --cpus 448 --configs '5*CFLIST'
+
+Alternatively, such a system can run 56 concurrent instances of a single
+eight-CPU scenario::
+
+ kvm.sh --cpus 448 --configs '56*TREE04'
+
+Or 28 concurrent instances of each of two eight-CPU scenarios::
+
+ kvm.sh --cpus 448 --configs '28*TREE03 28*TREE04'
+
+Of course, each concurrent instance will use memory, which can be
+limited using the --memory argument, which defaults to 512M. Small
+values for memory may require disabling the callback-flooding tests
+using the --bootargs parameter discussed below.
+
+Sometimes additional debugging is useful, and in such cases the --kconfig
+parameter to kvm.sh may be used, for example, ``--kconfig 'CONFIG_RCU_EQS_DEBUG=y'``.
+In addition, there are the --gdb, --kasan, and --kcsan parameters.
+Note that --gdb limits you to one scenario per kvm.sh run and requires
+that you have another window open from which to run ``gdb`` as instructed
+by the script.
+
+Kernel boot arguments can also be supplied, for example, to control
+rcutorture's module parameters. For example, to test a change to RCU's
+CPU stall-warning code, use "--bootargs 'rcutorture.stall_cpu=30'".
+This will of course result in the scripting reporting a failure, namely
+the resulting RCU CPU stall warning. As noted above, reducing memory may
+require disabling rcutorture's callback-flooding tests::
+
+ kvm.sh --cpus 448 --configs '56*TREE04' --memory 128M \
+ --bootargs 'rcutorture.fwd_progress=0'
+
+Sometimes all that is needed is a full set of kernel builds. This is
+what the --buildonly parameter does.
+
+The --duration parameter can override the default run time of 30 minutes.
+For example, ``--duration 2d`` would run for two days, ``--duration 3h``
+would run for three hours, ``--duration 5m`` would run for five minutes,
+and ``--duration 45s`` would run for 45 seconds. This last can be useful
+for tracking down rare boot-time failures.
+
+Finally, the --trust-make parameter allows each kernel build to reuse what
+it can from the previous kernel build. Please note that without the
+--trust-make parameter, your tags files may be demolished.
+
+There are additional more arcane arguments that are documented in the
+source code of the kvm.sh script.
+
+If a run contains failures, the number of buildtime and runtime failures
+is listed at the end of the kvm.sh output, which you really should redirect
+to a file. The build products and console output of each run is kept in
+tools/testing/selftests/rcutorture/res in timestamped directories. A
+given directory can be supplied to kvm-find-errors.sh in order to have
+it cycle you through summaries of errors and full error logs. For example::
+
+ tools/testing/selftests/rcutorture/bin/kvm-find-errors.sh \
+ tools/testing/selftests/rcutorture/res/2020.01.20-15.54.23
+
+However, it is often more convenient to access the files directly.
+Files pertaining to all scenarios in a run reside in the top-level
+directory (2020.01.20-15.54.23 in the example above), while per-scenario
+files reside in a subdirectory named after the scenario (for example,
+"TREE04"). If a given scenario ran more than once (as in "--configs
+'56*TREE04'" above), the directories corresponding to the second and
+subsequent runs of that scenario include a sequence number, for example,
+"TREE04.2", "TREE04.3", and so on.
+
+The most frequently used file in the top-level directory is testid.txt.
+If the test ran in a git repository, then this file contains the commit
+that was tested and any uncommitted changes in diff format.
+
+The most frequently used files in each per-scenario-run directory are:
+
+.config:
+ This file contains the Kconfig options.
+
+Make.out:
+ This contains build output for a specific scenario.
+
+console.log:
+ This contains the console output for a specific scenario.
+ This file may be examined once the kernel has booted, but
+ it might not exist if the build failed.
+
+vmlinux:
+ This contains the kernel, which can be useful with tools like
+ objdump and gdb.
+
+A number of additional files are available, but are less frequently used.
+Many are intended for debugging of rcutorture itself or of its scripting.
+
+As of v5.4, a successful run with the default set of scenarios produces
+the following summary at the end of the run on a 12-CPU system::
+
+ SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ]
+ SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ]
+ SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ]
+ SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ]
+ TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ]
+ TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ]
+ TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ]
+ TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198
+ TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631
+ TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ]
+ TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844
+ TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497
+ CPU count limited from 16 to 12
+ TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961
+ TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997
+ TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732
+ CPU count limited from 16 to 12
+ TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011
+
+
+Repeated Runs
+=============
+
+Suppose that you are chasing down a rare boot-time failure. Although you
+could use kvm.sh, doing so will rebuild the kernel on each run. If you
+need (say) 1,000 runs to have confidence that you have fixed the bug,
+these pointless rebuilds can become extremely annoying.
+
+This is why kvm-again.sh exists.
+
+Suppose that a previous kvm.sh run left its output in this directory::
+
+ tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28
+
+Then this run can be re-run without rebuilding as follow::
+
+ kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28
+
+A few of the original run's kvm.sh parameters may be overridden, perhaps
+most notably --duration and --bootargs. For example::
+
+ kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 \
+ --duration 45s
+
+would re-run the previous test, but for only 45 seconds, thus facilitating
+tracking down the aforementioned rare boot-time failure.
+
+
+Distributed Runs
+================
+
+Although kvm.sh is quite useful, its testing is confined to a single
+system. It is not all that hard to use your favorite framework to cause
+(say) 5 instances of kvm.sh to run on your 5 systems, but this will very
+likely unnecessarily rebuild kernels. In addition, manually distributing
+the desired rcutorture scenarios across the available systems can be
+painstaking and error-prone.
+
+And this is why the kvm-remote.sh script exists.
+
+If the following command works::
+
+ ssh system0 date
+
+and if it also works for system1, system2, system3, system4, and system5,
+and all of these systems have 64 CPUs, you can type::
+
+ kvm-remote.sh "system0 system1 system2 system3 system4 system5" \
+ --cpus 64 --duration 8h --configs "5*CFLIST"
+
+This will build each default scenario's kernel on the local system, then
+spread each of five instances of each scenario over the systems listed,
+running each scenario for eight hours. At the end of the runs, the
+results will be gathered, recorded, and printed. Most of the parameters
+that kvm.sh will accept can be passed to kvm-remote.sh, but the list of
+systems must come first.
+
+The kvm.sh ``--dryrun scenarios`` argument is useful for working out
+how many scenarios may be run in one batch across a group of systems.
+
+You can also re-run a previous remote run in a manner similar to kvm.sh::
+
+ kvm-remote.sh "system0 system1 system2 system3 system4 system5" \
+ tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28-remote \
+ --duration 24h
+
+In this case, most of the kvm-again.sh parameters may be supplied following
+the pathname of the old run-results directory.
diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
deleted file mode 100644
index dac02a6219b1..000000000000
--- a/Documentation/RCU/torture.txt
+++ /dev/null
@@ -1,334 +0,0 @@
-RCU Torture Test Operation
-
-
-CONFIG_RCU_TORTURE_TEST
-
-The CONFIG_RCU_TORTURE_TEST config option is available for all RCU
-implementations. It creates an rcutorture kernel module that can
-be loaded to run a torture test. The test periodically outputs
-status messages via printk(), which can be examined via the dmesg
-command (perhaps grepping for "torture"). The test is started
-when the module is loaded, and stops when the module is unloaded.
-
-CONFIG_RCU_TORTURE_TEST_RUNNABLE
-
-It is also possible to specify CONFIG_RCU_TORTURE_TEST=y, which will
-result in the tests being loaded into the base kernel. In this case,
-the CONFIG_RCU_TORTURE_TEST_RUNNABLE config option is used to specify
-whether the RCU torture tests are to be started immediately during
-boot or whether the /proc/sys/kernel/rcutorture_runnable file is used
-to enable them. This /proc file can be used to repeatedly pause and
-restart the tests, regardless of the initial state specified by the
-CONFIG_RCU_TORTURE_TEST_RUNNABLE config option.
-
-You will normally -not- want to start the RCU torture tests during boot
-(and thus the default is CONFIG_RCU_TORTURE_TEST_RUNNABLE=n), but doing
-this can sometimes be useful in finding boot-time bugs.
-
-
-MODULE PARAMETERS
-
-This module has the following parameters:
-
-fqs_duration Duration (in microseconds) of artificially induced bursts
- of force_quiescent_state() invocations. In RCU
- implementations having force_quiescent_state(), these
- bursts help force races between forcing a given grace
- period and that grace period ending on its own.
-
-fqs_holdoff Holdoff time (in microseconds) between consecutive calls
- to force_quiescent_state() within a burst.
-
-fqs_stutter Wait time (in seconds) between consecutive bursts
- of calls to force_quiescent_state().
-
-gp_normal Make the fake writers use normal synchronous grace-period
- primitives.
-
-gp_exp Make the fake writers use expedited synchronous grace-period
- primitives. If both gp_normal and gp_exp are set, or
- if neither gp_normal nor gp_exp are set, then randomly
- choose the primitive so that about 50% are normal and
- 50% expedited. By default, neither are set, which
- gives best overall test coverage.
-
-irqreader Says to invoke RCU readers from irq level. This is currently
- done via timers. Defaults to "1" for variants of RCU that
- permit this. (Or, more accurately, variants of RCU that do
- -not- permit this know to ignore this variable.)
-
-n_barrier_cbs If this is nonzero, RCU barrier testing will be conducted,
- in which case n_barrier_cbs specifies the number of
- RCU callbacks (and corresponding kthreads) to use for
- this testing. The value cannot be negative. If you
- specify this to be non-zero when torture_type indicates a
- synchronous RCU implementation (one for which a member of
- the synchronize_rcu() rather than the call_rcu() family is
- used -- see the documentation for torture_type below), an
- error will be reported and no testing will be carried out.
-
-nfakewriters This is the number of RCU fake writer threads to run. Fake
- writer threads repeatedly use the synchronous "wait for
- current readers" function of the interface selected by
- torture_type, with a delay between calls to allow for various
- different numbers of writers running in parallel.
- nfakewriters defaults to 4, which provides enough parallelism
- to trigger special cases caused by multiple writers, such as
- the synchronize_srcu() early return optimization.
-
-nreaders This is the number of RCU reading threads supported.
- The default is twice the number of CPUs. Why twice?
- To properly exercise RCU implementations with preemptible
- read-side critical sections.
-
-onoff_interval
- The number of seconds between each attempt to execute a
- randomly selected CPU-hotplug operation. Defaults to
- zero, which disables CPU hotplugging. In HOTPLUG_CPU=n
- kernels, rcutorture will silently refuse to do any
- CPU-hotplug operations regardless of what value is
- specified for onoff_interval.
-
-onoff_holdoff The number of seconds to wait until starting CPU-hotplug
- operations. This would normally only be used when
- rcutorture was built into the kernel and started
- automatically at boot time, in which case it is useful
- in order to avoid confusing boot-time code with CPUs
- coming and going.
-
-shuffle_interval
- The number of seconds to keep the test threads affinitied
- to a particular subset of the CPUs, defaults to 3 seconds.
- Used in conjunction with test_no_idle_hz.
-
-shutdown_secs The number of seconds to run the test before terminating
- the test and powering off the system. The default is
- zero, which disables test termination and system shutdown.
- This capability is useful for automated testing.
-
-stall_cpu The number of seconds that a CPU should be stalled while
- within both an rcu_read_lock() and a preempt_disable().
- This stall happens only once per rcutorture run.
- If you need multiple stalls, use modprobe and rmmod to
- repeatedly run rcutorture. The default for stall_cpu
- is zero, which prevents rcutorture from stalling a CPU.
-
- Note that attempts to rmmod rcutorture while the stall
- is ongoing will hang, so be careful what value you
- choose for this module parameter! In addition, too-large
- values for stall_cpu might well induce failures and
- warnings in other parts of the kernel. You have been
- warned!
-
-stall_cpu_holdoff
- The number of seconds to wait after rcutorture starts
- before stalling a CPU. Defaults to 10 seconds.
-
-stat_interval The number of seconds between output of torture
- statistics (via printk()). Regardless of the interval,
- statistics are printed when the module is unloaded.
- Setting the interval to zero causes the statistics to
- be printed -only- when the module is unloaded, and this
- is the default.
-
-stutter The length of time to run the test before pausing for this
- same period of time. Defaults to "stutter=5", so as
- to run and pause for (roughly) five-second intervals.
- Specifying "stutter=0" causes the test to run continuously
- without pausing, which is the old default behavior.
-
-test_boost Whether or not to test the ability of RCU to do priority
- boosting. Defaults to "test_boost=1", which performs
- RCU priority-inversion testing only if the selected
- RCU implementation supports priority boosting. Specifying
- "test_boost=0" never performs RCU priority-inversion
- testing. Specifying "test_boost=2" performs RCU
- priority-inversion testing even if the selected RCU
- implementation does not support RCU priority boosting,
- which can be used to test rcutorture's ability to
- carry out RCU priority-inversion testing.
-
-test_boost_interval
- The number of seconds in an RCU priority-inversion test
- cycle. Defaults to "test_boost_interval=7". It is
- usually wise for this value to be relatively prime to
- the value selected for "stutter".
-
-test_boost_duration
- The number of seconds to do RCU priority-inversion testing
- within any given "test_boost_interval". Defaults to
- "test_boost_duration=4".
-
-test_no_idle_hz Whether or not to test the ability of RCU to operate in
- a kernel that disables the scheduling-clock interrupt to
- idle CPUs. Boolean parameter, "1" to test, "0" otherwise.
- Defaults to omitting this test.
-
-torture_type The type of RCU to test, with string values as follows:
-
- "rcu": rcu_read_lock(), rcu_read_unlock() and call_rcu().
-
- "rcu_sync": rcu_read_lock(), rcu_read_unlock(), and
- synchronize_rcu().
-
- "rcu_expedited": rcu_read_lock(), rcu_read_unlock(), and
- synchronize_rcu_expedited().
-
- "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
- call_rcu_bh().
-
- "rcu_bh_sync": rcu_read_lock_bh(), rcu_read_unlock_bh(),
- and synchronize_rcu_bh().
-
- "rcu_bh_expedited": rcu_read_lock_bh(), rcu_read_unlock_bh(),
- and synchronize_rcu_bh_expedited().
-
- "srcu": srcu_read_lock(), srcu_read_unlock() and
- call_srcu().
-
- "srcu_sync": srcu_read_lock(), srcu_read_unlock() and
- synchronize_srcu().
-
- "srcu_expedited": srcu_read_lock(), srcu_read_unlock() and
- synchronize_srcu_expedited().
-
- "sched": preempt_disable(), preempt_enable(), and
- call_rcu_sched().
-
- "sched_sync": preempt_disable(), preempt_enable(), and
- synchronize_sched().
-
- "sched_expedited": preempt_disable(), preempt_enable(), and
- synchronize_sched_expedited().
-
- Defaults to "rcu".
-
-verbose Enable debug printk()s. Default is disabled.
-
-
-OUTPUT
-
-The statistics output is as follows:
-
- rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
- rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767
- rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0
- rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0
- rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0
- rcu-torture:--- End of test: SUCCESS: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
-
-The command "dmesg | grep torture:" will extract this information on
-most systems. On more esoteric configurations, it may be necessary to
-use other commands to access the output of the printk()s used by
-the RCU torture test. The printk()s use KERN_ALERT, so they should
-be evident. ;-)
-
-The first and last lines show the rcutorture module parameters, and the
-last line shows either "SUCCESS" or "FAILURE", based on rcutorture's
-automatic determination as to whether RCU operated correctly.
-
-The entries are as follows:
-
-o "rtc": The hexadecimal address of the structure currently visible
- to readers.
-
-o "ver": The number of times since boot that the RCU writer task
- has changed the structure visible to readers.
-
-o "tfle": If non-zero, indicates that the "torture freelist"
- containing structures to be placed into the "rtc" area is empty.
- This condition is important, since it can fool you into thinking
- that RCU is working when it is not. :-/
-
-o "rta": Number of structures allocated from the torture freelist.
-
-o "rtaf": Number of allocations from the torture freelist that have
- failed due to the list being empty. It is not unusual for this
- to be non-zero, but it is bad for it to be a large fraction of
- the value indicated by "rta".
-
-o "rtf": Number of frees into the torture freelist.
-
-o "rtmbe": A non-zero value indicates that rcutorture believes that
- rcu_assign_pointer() and rcu_dereference() are not working
- correctly. This value should be zero.
-
-o "rtbe": A non-zero value indicates that one of the rcu_barrier()
- family of functions is not working correctly.
-
-o "rtbke": rcutorture was unable to create the real-time kthreads
- used to force RCU priority inversion. This value should be zero.
-
-o "rtbre": Although rcutorture successfully created the kthreads
- used to force RCU priority inversion, it was unable to set them
- to the real-time priority level of 1. This value should be zero.
-
-o "rtbf": The number of times that RCU priority boosting failed
- to resolve RCU priority inversion.
-
-o "rtb": The number of times that rcutorture attempted to force
- an RCU priority inversion condition. If you are testing RCU
- priority boosting via the "test_boost" module parameter, this
- value should be non-zero.
-
-o "nt": The number of times rcutorture ran RCU read-side code from
- within a timer handler. This value should be non-zero only
- if you specified the "irqreader" module parameter.
-
-o "Reader Pipe": Histogram of "ages" of structures seen by readers.
- If any entries past the first two are non-zero, RCU is broken.
- And rcutorture prints the error flag string "!!!" to make sure
- you notice. The age of a newly allocated structure is zero,
- it becomes one when removed from reader visibility, and is
- incremented once per grace period subsequently -- and is freed
- after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods.
-
- The output displayed above was taken from a correctly working
- RCU. If you want to see what it looks like when broken, break
- it yourself. ;-)
-
-o "Reader Batch": Another histogram of "ages" of structures seen
- by readers, but in terms of counter flips (or batches) rather
- than in terms of grace periods. The legal number of non-zero
- entries is again two. The reason for this separate view is that
- it is sometimes easier to get the third entry to show up in the
- "Reader Batch" list than in the "Reader Pipe" list.
-
-o "Free-Block Circulation": Shows the number of torture structures
- that have reached a given point in the pipeline. The first element
- should closely correspond to the number of structures allocated,
- the second to the number that have been removed from reader view,
- and all but the last remaining to the corresponding number of
- passes through a grace period. The last entry should be zero,
- as it is only incremented if a torture structure's counter
- somehow gets incremented farther than it should.
-
-Different implementations of RCU can provide implementation-specific
-additional information. For example, SRCU provides the following
-additional line:
-
- srcu-torture: per-CPU(idx=1): 0(0,1) 1(0,1) 2(0,0) 3(0,1)
-
-This line shows the per-CPU counter state. The numbers in parentheses are
-the values of the "old" and "current" counters for the corresponding CPU.
-The "idx" value maps the "old" and "current" values to the underlying
-array, and is useful for debugging.
-
-
-USAGE
-
-The following script may be used to torture RCU:
-
- #!/bin/sh
-
- modprobe rcutorture
- sleep 3600
- rmmod rcutorture
- dmesg | grep torture:
-
-The output can be manually inspected for the error flag of "!!!".
-One could of course create a more elaborate script that automatically
-checked for such errors. The "rmmod" command forces a "SUCCESS",
-"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first
-two are self-explanatory, while the last indicates that while there
-were no RCU failures, CPU-hotplug problems were detected.
diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt
deleted file mode 100644
index 08651da15448..000000000000
--- a/Documentation/RCU/trace.txt
+++ /dev/null
@@ -1,554 +0,0 @@
-CONFIG_RCU_TRACE debugfs Files and Formats
-
-
-The rcutree and rcutiny implementations of RCU provide debugfs trace
-output that summarizes counters and state. This information is useful for
-debugging RCU itself, and can sometimes also help to debug abuses of RCU.
-The following sections describe the debugfs files and formats, first
-for rcutree and next for rcutiny.
-
-
-CONFIG_TREE_RCU and CONFIG_PREEMPT_RCU debugfs Files and Formats
-
-These implementations of RCU provide several debugfs directories under the
-top-level directory "rcu":
-
-rcu/rcu_bh
-rcu/rcu_preempt
-rcu/rcu_sched
-
-Each directory contains files for the corresponding flavor of RCU.
-Note that rcu/rcu_preempt is only present for CONFIG_PREEMPT_RCU.
-For CONFIG_TREE_RCU, the RCU flavor maps onto the RCU-sched flavor,
-so that activity for both appears in rcu/rcu_sched.
-
-In addition, the following file appears in the top-level directory:
-rcu/rcutorture. This file displays rcutorture test progress. The output
-of "cat rcu/rcutorture" looks as follows:
-
-rcutorture test sequence: 0 (test in progress)
-rcutorture update version number: 615
-
-The first line shows the number of rcutorture tests that have completed
-since boot. If a test is currently running, the "(test in progress)"
-string will appear as shown above. The second line shows the number of
-update cycles that the current test has started, or zero if there is
-no test in progress.
-
-
-Within each flavor directory (rcu/rcu_bh, rcu/rcu_sched, and possibly
-also rcu/rcu_preempt) the following files will be present:
-
-rcudata:
- Displays fields in struct rcu_data.
-rcuexp:
- Displays statistics for expedited grace periods.
-rcugp:
- Displays grace-period counters.
-rcuhier:
- Displays the struct rcu_node hierarchy.
-rcu_pending:
- Displays counts of the reasons rcu_pending() decided that RCU had
- work to do.
-rcuboost:
- Displays RCU boosting statistics. Only present if
- CONFIG_RCU_BOOST=y.
-
-The output of "cat rcu/rcu_preempt/rcudata" looks as follows:
-
- 0!c=30455 g=30456 pq=1/0 qp=1 dt=126535/140000000000000/0 df=2002 of=4 ql=0/0 qs=N... b=10 ci=74572 nci=0 co=1131 ca=716
- 1!c=30719 g=30720 pq=1/0 qp=0 dt=132007/140000000000000/0 df=1874 of=10 ql=0/0 qs=N... b=10 ci=123209 nci=0 co=685 ca=982
- 2!c=30150 g=30151 pq=1/1 qp=1 dt=138537/140000000000000/0 df=1707 of=8 ql=0/0 qs=N... b=10 ci=80132 nci=0 co=1328 ca=1458
- 3 c=31249 g=31250 pq=1/1 qp=0 dt=107255/140000000000000/0 df=1749 of=6 ql=0/450 qs=NRW. b=10 ci=151700 nci=0 co=509 ca=622
- 4!c=29502 g=29503 pq=1/0 qp=1 dt=83647/140000000000000/0 df=965 of=5 ql=0/0 qs=N... b=10 ci=65643 nci=0 co=1373 ca=1521
- 5 c=31201 g=31202 pq=1/0 qp=1 dt=70422/0/0 df=535 of=7 ql=0/0 qs=.... b=10 ci=58500 nci=0 co=764 ca=698
- 6!c=30253 g=30254 pq=1/0 qp=1 dt=95363/140000000000000/0 df=780 of=5 ql=0/0 qs=N... b=10 ci=100607 nci=0 co=1414 ca=1353
- 7 c=31178 g=31178 pq=1/0 qp=0 dt=91536/0/0 df=547 of=4 ql=0/0 qs=.... b=10 ci=109819 nci=0 co=1115 ca=969
-
-This file has one line per CPU, or eight for this 8-CPU system.
-The fields are as follows:
-
-o The number at the beginning of each line is the CPU number.
- CPUs numbers followed by an exclamation mark are offline,
- but have been online at least once since boot. There will be
- no output for CPUs that have never been online, which can be
- a good thing in the surprisingly common case where NR_CPUS is
- substantially larger than the number of actual CPUs.
-
-o "c" is the count of grace periods that this CPU believes have
- completed. Offlined CPUs and CPUs in dynticks idle mode may lag
- quite a ways behind, for example, CPU 4 under "rcu_sched" above,
- which has been offline through 16 RCU grace periods. It is not
- unusual to see offline CPUs lagging by thousands of grace periods.
- Note that although the grace-period number is an unsigned long,
- it is printed out as a signed long to allow more human-friendly
- representation near boot time.
-
-o "g" is the count of grace periods that this CPU believes have
- started. Again, offlined CPUs and CPUs in dynticks idle mode
- may lag behind. If the "c" and "g" values are equal, this CPU
- has already reported a quiescent state for the last RCU grace
- period that it is aware of, otherwise, the CPU believes that it
- owes RCU a quiescent state.
-
-o "pq" indicates that this CPU has passed through a quiescent state
- for the current grace period. It is possible for "pq" to be
- "1" and "c" different than "g", which indicates that although
- the CPU has passed through a quiescent state, either (1) this
- CPU has not yet reported that fact, (2) some other CPU has not
- yet reported for this grace period, or (3) both.
-
-o "qp" indicates that RCU still expects a quiescent state from
- this CPU. Offlined CPUs and CPUs in dyntick idle mode might
- well have qp=1, which is OK: RCU is still ignoring them.
-
-o "dt" is the current value of the dyntick counter that is incremented
- when entering or leaving idle, either due to a context switch or
- due to an interrupt. This number is even if the CPU is in idle
- from RCU's viewpoint and odd otherwise. The number after the
- first "/" is the interrupt nesting depth when in idle state,
- or a large number added to the interrupt-nesting depth when
- running a non-idle task. Some architectures do not accurately
- count interrupt nesting when running in non-idle kernel context,
- which can result in interesting anomalies such as negative
- interrupt-nesting levels. The number after the second "/"
- is the NMI nesting depth.
-
-o "df" is the number of times that some other CPU has forced a
- quiescent state on behalf of this CPU due to this CPU being in
- idle state.
-
-o "of" is the number of times that some other CPU has forced a
- quiescent state on behalf of this CPU due to this CPU being
- offline. In a perfect world, this might never happen, but it
- turns out that offlining and onlining a CPU can take several grace
- periods, and so there is likely to be an extended period of time
- when RCU believes that the CPU is online when it really is not.
- Please note that erring in the other direction (RCU believing a
- CPU is offline when it is really alive and kicking) is a fatal
- error, so it makes sense to err conservatively.
-
-o "ql" is the number of RCU callbacks currently residing on
- this CPU. The first number is the number of "lazy" callbacks
- that are known to RCU to only be freeing memory, and the number
- after the "/" is the total number of callbacks, lazy or not.
- These counters count callbacks regardless of what phase of
- grace-period processing that they are in (new, waiting for
- grace period to start, waiting for grace period to end, ready
- to invoke).
-
-o "qs" gives an indication of the state of the callback queue
- with four characters:
-
- "N" Indicates that there are callbacks queued that are not
- ready to be handled by the next grace period, and thus
- will be handled by the grace period following the next
- one.
-
- "R" Indicates that there are callbacks queued that are
- ready to be handled by the next grace period.
-
- "W" Indicates that there are callbacks queued that are
- waiting on the current grace period.
-
- "D" Indicates that there are callbacks queued that have
- already been handled by a prior grace period, and are
- thus waiting to be invoked. Note that callbacks in
- the process of being invoked are not counted here.
- Callbacks in the process of being invoked are those
- that have been removed from the rcu_data structures
- queues by rcu_do_batch(), but which have not yet been
- invoked.
-
- If there are no callbacks in a given one of the above states,
- the corresponding character is replaced by ".".
-
-o "b" is the batch limit for this CPU. If more than this number
- of RCU callbacks is ready to invoke, then the remainder will
- be deferred.
-
-o "ci" is the number of RCU callbacks that have been invoked for
- this CPU. Note that ci+nci+ql is the number of callbacks that have
- been registered in absence of CPU-hotplug activity.
-
-o "nci" is the number of RCU callbacks that have been offloaded from
- this CPU. This will always be zero unless the kernel was built
- with CONFIG_RCU_NOCB_CPU=y and the "rcu_nocbs=" kernel boot
- parameter was specified.
-
-o "co" is the number of RCU callbacks that have been orphaned due to
- this CPU going offline. These orphaned callbacks have been moved
- to an arbitrarily chosen online CPU.
-
-o "ca" is the number of RCU callbacks that have been adopted by this
- CPU due to other CPUs going offline. Note that ci+co-ca+ql is
- the number of RCU callbacks registered on this CPU.
-
-
-Kernels compiled with CONFIG_RCU_BOOST=y display the following from
-/debug/rcu/rcu_preempt/rcudata:
-
- 0!c=12865 g=12866 pq=1/0 qp=1 dt=83113/140000000000000/0 df=288 of=11 ql=0/0 qs=N... kt=0/O ktl=944 b=10 ci=60709 nci=0 co=748 ca=871
- 1 c=14407 g=14408 pq=1/0 qp=0 dt=100679/140000000000000/0 df=378 of=7 ql=0/119 qs=NRW. kt=0/W ktl=9b6 b=10 ci=109740 nci=0 co=589 ca=485
- 2 c=14407 g=14408 pq=1/0 qp=0 dt=105486/0/0 df=90 of=9 ql=0/89 qs=NRW. kt=0/W ktl=c0c b=10 ci=83113 nci=0 co=533 ca=490
- 3 c=14407 g=14408 pq=1/0 qp=0 dt=107138/0/0 df=142 of=8 ql=0/188 qs=NRW. kt=0/W ktl=b96 b=10 ci=121114 nci=0 co=426 ca=290
- 4 c=14405 g=14406 pq=1/0 qp=1 dt=50238/0/0 df=706 of=7 ql=0/0 qs=.... kt=0/W ktl=812 b=10 ci=34929 nci=0 co=643 ca=114
- 5!c=14168 g=14169 pq=1/0 qp=0 dt=45465/140000000000000/0 df=161 of=11 ql=0/0 qs=N... kt=0/O ktl=b4d b=10 ci=47712 nci=0 co=677 ca=722
- 6 c=14404 g=14405 pq=1/0 qp=0 dt=59454/0/0 df=94 of=6 ql=0/0 qs=.... kt=0/W ktl=e57 b=10 ci=55597 nci=0 co=701 ca=811
- 7 c=14407 g=14408 pq=1/0 qp=1 dt=68850/0/0 df=31 of=8 ql=0/0 qs=.... kt=0/W ktl=14bd b=10 ci=77475 nci=0 co=508 ca=1042
-
-This is similar to the output discussed above, but contains the following
-additional fields:
-
-o "kt" is the per-CPU kernel-thread state. The digit preceding
- the first slash is zero if there is no work pending and 1
- otherwise. The character between the first pair of slashes is
- as follows:
-
- "S" The kernel thread is stopped, in other words, all
- CPUs corresponding to this rcu_node structure are
- offline.
-
- "R" The kernel thread is running.
-
- "W" The kernel thread is waiting because there is no work
- for it to do.
-
- "O" The kernel thread is waiting because it has been
- forced off of its designated CPU or because its
- ->cpus_allowed mask permits it to run on other than
- its designated CPU.
-
- "Y" The kernel thread is yielding to avoid hogging CPU.
-
- "?" Unknown value, indicates a bug.
-
- The number after the final slash is the CPU that the kthread
- is actually running on.
-
- This field is displayed only for CONFIG_RCU_BOOST kernels.
-
-o "ktl" is the low-order 16 bits (in hexadecimal) of the count of
- the number of times that this CPU's per-CPU kthread has gone
- through its loop servicing invoke_rcu_cpu_kthread() requests.
-
- This field is displayed only for CONFIG_RCU_BOOST kernels.
-
-
-The output of "cat rcu/rcu_preempt/rcuexp" looks as follows:
-
-s=21872 d=21872 w=0 tf=0 wd1=0 wd2=0 n=0 sc=21872 dt=21872 dl=0 dx=21872
-
-These fields are as follows:
-
-o "s" is the starting sequence number.
-
-o "d" is the ending sequence number. When the starting and ending
- numbers differ, there is an expedited grace period in progress.
-
-o "w" is the number of times that the sequence numbers have been
- in danger of wrapping.
-
-o "tf" is the number of times that contention has resulted in a
- failure to begin an expedited grace period.
-
-o "wd1" and "wd2" are the number of times that an attempt to
- start an expedited grace period found that someone else had
- completed an expedited grace period that satisfies the
- attempted request. "Our work is done."
-
-o "n" is number of times that contention was so great that
- the request was demoted from an expedited grace period to
- a normal grace period.
-
-o "sc" is the number of times that the attempt to start a
- new expedited grace period succeeded.
-
-o "dt" is the number of times that we attempted to update
- the "d" counter.
-
-o "dl" is the number of times that we failed to update the "d"
- counter.
-
-o "dx" is the number of times that we succeeded in updating
- the "d" counter.
-
-
-The output of "cat rcu/rcu_preempt/rcugp" looks as follows:
-
-completed=31249 gpnum=31250 age=1 max=18
-
-These fields are taken from the rcu_state structure, and are as follows:
-
-o "completed" is the number of grace periods that have completed.
- It is comparable to the "c" field from rcu/rcudata in that a
- CPU whose "c" field matches the value of "completed" is aware
- that the corresponding RCU grace period has completed.
-
-o "gpnum" is the number of grace periods that have started. It is
- similarly comparable to the "g" field from rcu/rcudata in that
- a CPU whose "g" field matches the value of "gpnum" is aware that
- the corresponding RCU grace period has started.
-
- If these two fields are equal, then there is no grace period
- in progress, in other words, RCU is idle. On the other hand,
- if the two fields differ (as they are above), then an RCU grace
- period is in progress.
-
-o "age" is the number of jiffies that the current grace period
- has extended for, or zero if there is no grace period currently
- in effect.
-
-o "max" is the age in jiffies of the longest-duration grace period
- thus far.
-
-The output of "cat rcu/rcu_preempt/rcuhier" looks as follows:
-
-c=14407 g=14408 s=0 jfq=2 j=c863 nfqs=12040/nfqsng=0(12040) fqlh=1051 oqlen=0/0
-3/3 ..>. 0:7 ^0
-e/e ..>. 0:3 ^0 d/d ..>. 4:7 ^1
-
-The fields are as follows:
-
-o "c" is exactly the same as "completed" under rcu/rcu_preempt/rcugp.
-
-o "g" is exactly the same as "gpnum" under rcu/rcu_preempt/rcugp.
-
-o "s" is the current state of the force_quiescent_state()
- state machine.
-
-o "jfq" is the number of jiffies remaining for this grace period
- before force_quiescent_state() is invoked to help push things
- along. Note that CPUs in idle mode throughout the grace period
- will not report on their own, but rather must be check by some
- other CPU via force_quiescent_state().
-
-o "j" is the low-order four hex digits of the jiffies counter.
- Yes, Paul did run into a number of problems that turned out to
- be due to the jiffies counter no longer counting. Why do you ask?
-
-o "nfqs" is the number of calls to force_quiescent_state() since
- boot.
-
-o "nfqsng" is the number of useless calls to force_quiescent_state(),
- where there wasn't actually a grace period active. This can
- no longer happen due to grace-period processing being pushed
- into a kthread. The number in parentheses is the difference
- between "nfqs" and "nfqsng", or the number of times that
- force_quiescent_state() actually did some real work.
-
-o "fqlh" is the number of calls to force_quiescent_state() that
- exited immediately (without even being counted in nfqs above)
- due to contention on ->fqslock.
-
-o Each element of the form "3/3 ..>. 0:7 ^0" represents one rcu_node
- structure. Each line represents one level of the hierarchy,
- from root to leaves. It is best to think of the rcu_data
- structures as forming yet another level after the leaves.
- Note that there might be either one, two, three, or even four
- levels of rcu_node structures, depending on the relationship
- between CONFIG_RCU_FANOUT, CONFIG_RCU_FANOUT_LEAF (possibly
- adjusted using the rcu_fanout_leaf kernel boot parameter), and
- CONFIG_NR_CPUS (possibly adjusted using the nr_cpu_ids count of
- possible CPUs for the booting hardware).
-
- o The numbers separated by the "/" are the qsmask followed
- by the qsmaskinit. The qsmask will have one bit
- set for each entity in the next lower level that has
- not yet checked in for the current grace period ("e"
- indicating CPUs 5, 6, and 7 in the example above).
- The qsmaskinit will have one bit for each entity that is
- currently expected to check in during each grace period.
- The value of qsmaskinit is assigned to that of qsmask
- at the beginning of each grace period.
-
- o The characters separated by the ">" indicate the state
- of the blocked-tasks lists. A "G" preceding the ">"
- indicates that at least one task blocked in an RCU
- read-side critical section blocks the current grace
- period, while a "E" preceding the ">" indicates that
- at least one task blocked in an RCU read-side critical
- section blocks the current expedited grace period.
- A "T" character following the ">" indicates that at
- least one task is blocked within an RCU read-side
- critical section, regardless of whether any current
- grace period (expedited or normal) is inconvenienced.
- A "." character appears if the corresponding condition
- does not hold, so that "..>." indicates that no tasks
- are blocked. In contrast, "GE>T" indicates maximal
- inconvenience from blocked tasks. CONFIG_TREE_RCU
- builds of the kernel will always show "..>.".
-
- o The numbers separated by the ":" are the range of CPUs
- served by this struct rcu_node. This can be helpful
- in working out how the hierarchy is wired together.
-
- For example, the example rcu_node structure shown above
- has "0:7", indicating that it covers CPUs 0 through 7.
-
- o The number after the "^" indicates the bit in the
- next higher level rcu_node structure that this rcu_node
- structure corresponds to. For example, the "d/d ..>. 4:7
- ^1" has a "1" in this position, indicating that it
- corresponds to the "1" bit in the "3" shown in the
- "3/3 ..>. 0:7 ^0" entry on the next level up.
-
-
-The output of "cat rcu/rcu_sched/rcu_pending" looks as follows:
-
- 0!np=26111 qsp=29 rpq=5386 cbr=1 cng=570 gpc=3674 gps=577 nn=15903 ndw=0
- 1!np=28913 qsp=35 rpq=6097 cbr=1 cng=448 gpc=3700 gps=554 nn=18113 ndw=0
- 2!np=32740 qsp=37 rpq=6202 cbr=0 cng=476 gpc=4627 gps=546 nn=20889 ndw=0
- 3 np=23679 qsp=22 rpq=5044 cbr=1 cng=415 gpc=3403 gps=347 nn=14469 ndw=0
- 4!np=30714 qsp=4 rpq=5574 cbr=0 cng=528 gpc=3931 gps=639 nn=20042 ndw=0
- 5 np=28910 qsp=2 rpq=5246 cbr=0 cng=428 gpc=4105 gps=709 nn=18422 ndw=0
- 6!np=38648 qsp=5 rpq=7076 cbr=0 cng=840 gpc=4072 gps=961 nn=25699 ndw=0
- 7 np=37275 qsp=2 rpq=6873 cbr=0 cng=868 gpc=3416 gps=971 nn=25147 ndw=0
-
-The fields are as follows:
-
-o The leading number is the CPU number, with "!" indicating
- an offline CPU.
-
-o "np" is the number of times that __rcu_pending() has been invoked
- for the corresponding flavor of RCU.
-
-o "qsp" is the number of times that the RCU was waiting for a
- quiescent state from this CPU.
-
-o "rpq" is the number of times that the CPU had passed through
- a quiescent state, but not yet reported it to RCU.
-
-o "cbr" is the number of times that this CPU had RCU callbacks
- that had passed through a grace period, and were thus ready
- to be invoked.
-
-o "cng" is the number of times that this CPU needed another
- grace period while RCU was idle.
-
-o "gpc" is the number of times that an old grace period had
- completed, but this CPU was not yet aware of it.
-
-o "gps" is the number of times that a new grace period had started,
- but this CPU was not yet aware of it.
-
-o "ndw" is the number of times that a wakeup of an rcuo
- callback-offload kthread had to be deferred in order to avoid
- deadlock.
-
-o "nn" is the number of times that this CPU needed nothing.
-
-
-The output of "cat rcu/rcuboost" looks as follows:
-
-0:3 tasks=.... kt=W ntb=0 neb=0 nnb=0 j=c864 bt=c894
- balk: nt=0 egt=4695 bt=0 nb=0 ny=56 nos=0
-4:7 tasks=.... kt=W ntb=0 neb=0 nnb=0 j=c864 bt=c894
- balk: nt=0 egt=6541 bt=0 nb=0 ny=126 nos=0
-
-This information is output only for rcu_preempt. Each two-line entry
-corresponds to a leaf rcu_node structure. The fields are as follows:
-
-o "n:m" is the CPU-number range for the corresponding two-line
- entry. In the sample output above, the first entry covers
- CPUs zero through three and the second entry covers CPUs four
- through seven.
-
-o "tasks=TNEB" gives the state of the various segments of the
- rnp->blocked_tasks list:
-
- "T" This indicates that there are some tasks that blocked
- while running on one of the corresponding CPUs while
- in an RCU read-side critical section.
-
- "N" This indicates that some of the blocked tasks are preventing
- the current normal (non-expedited) grace period from
- completing.
-
- "E" This indicates that some of the blocked tasks are preventing
- the current expedited grace period from completing.
-
- "B" This indicates that some of the blocked tasks are in
- need of RCU priority boosting.
-
- Each character is replaced with "." if the corresponding
- condition does not hold.
-
-o "kt" is the state of the RCU priority-boosting kernel
- thread associated with the corresponding rcu_node structure.
- The state can be one of the following:
-
- "S" The kernel thread is stopped, in other words, all
- CPUs corresponding to this rcu_node structure are
- offline.
-
- "R" The kernel thread is running.
-
- "W" The kernel thread is waiting because there is no work
- for it to do.
-
- "Y" The kernel thread is yielding to avoid hogging CPU.
-
- "?" Unknown value, indicates a bug.
-
-o "ntb" is the number of tasks boosted.
-
-o "neb" is the number of tasks boosted in order to complete an
- expedited grace period.
-
-o "nnb" is the number of tasks boosted in order to complete a
- normal (non-expedited) grace period. When boosting a task
- that was blocking both an expedited and a normal grace period,
- it is counted against the expedited total above.
-
-o "j" is the low-order 16 bits of the jiffies counter in
- hexadecimal.
-
-o "bt" is the low-order 16 bits of the value that the jiffies
- counter will have when we next start boosting, assuming that
- the current grace period does not end beforehand. This is
- also in hexadecimal.
-
-o "balk: nt" counts the number of times we didn't boost (in
- other words, we balked) even though it was time to boost because
- there were no blocked tasks to boost. This situation occurs
- when there is one blocked task on one rcu_node structure and
- none on some other rcu_node structure.
-
-o "egt" counts the number of times we balked because although
- there were blocked tasks, none of them were blocking the
- current grace period, whether expedited or otherwise.
-
-o "bt" counts the number of times we balked because boosting
- had already been initiated for the current grace period.
-
-o "nb" counts the number of times we balked because there
- was at least one task blocking the current non-expedited grace
- period that never had blocked. If it is already running, it
- just won't help to boost its priority!
-
-o "ny" counts the number of times we balked because it was
- not yet time to start boosting.
-
-o "nos" counts the number of times we balked for other
- reasons, e.g., the grace period ended first.
-
-
-CONFIG_TINY_RCU debugfs Files and Formats
-
-These implementations of RCU provides a single debugfs file under the
-top-level directory RCU, namely rcu/rcudata, which displays fields in
-rcu_bh_ctrlblk and rcu_sched_ctrlblk.
-
-The output of "cat rcu/rcudata" is as follows:
-
-rcu_sched: qlen: 0
-rcu_bh: qlen: 0
-
-This is split into rcu_sched and rcu_bh sections. The field is as
-follows:
-
-o "qlen" is the number of RCU callbacks currently waiting either
- for an RCU grace period or waiting to be invoked. This is the
- only field present for rcu_sched and rcu_bh, due to the
- short-circuiting of grace period in those two cases.
diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
new file mode 100644
index 000000000000..a1582bd653d1
--- /dev/null
+++ b/Documentation/RCU/whatisRCU.rst
@@ -0,0 +1,1415 @@
+.. _whatisrcu_doc:
+
+What is RCU? -- "Read, Copy, Update"
+======================================
+
+Please note that the "What is RCU?" LWN series is an excellent place
+to start learning about RCU:
+
+| 1. What is RCU, Fundamentally? https://lwn.net/Articles/262464/
+| 2. What is RCU? Part 2: Usage https://lwn.net/Articles/263130/
+| 3. RCU part 3: the RCU API https://lwn.net/Articles/264090/
+| 4. The RCU API, 2010 Edition https://lwn.net/Articles/418853/
+| 2010 Big API Table https://lwn.net/Articles/419086/
+| 5. The RCU API, 2014 Edition https://lwn.net/Articles/609904/
+| 2014 Big API Table https://lwn.net/Articles/609973/
+| 6. The RCU API, 2019 Edition https://lwn.net/Articles/777036/
+| 2019 Big API Table https://lwn.net/Articles/777165/
+| 7. The RCU API, 2024 Edition https://lwn.net/Articles/988638/
+| 2024 Background Information https://lwn.net/Articles/988641/
+| 2024 Big API Table https://lwn.net/Articles/988666/
+
+For those preferring video:
+
+| 1. Unraveling RCU Mysteries: Fundamentals https://www.linuxfoundation.org/webinars/unraveling-rcu-usage-mysteries
+| 2. Unraveling RCU Mysteries: Additional Use Cases https://www.linuxfoundation.org/webinars/unraveling-rcu-usage-mysteries-additional-use-cases
+
+
+What is RCU?
+
+RCU is a synchronization mechanism that was added to the Linux kernel
+during the 2.5 development effort that is optimized for read-mostly
+situations. Although RCU is actually quite simple, making effective use
+of it requires you to think differently about your code. Another part
+of the problem is the mistaken assumption that there is "one true way" to
+describe and to use RCU. Instead, the experience has been that different
+people must take different paths to arrive at an understanding of RCU,
+depending on their experiences and use cases. This document provides
+several different paths, as follows:
+
+:ref:`1. RCU OVERVIEW <1_whatisRCU>`
+
+:ref:`2. WHAT IS RCU'S CORE API? <2_whatisRCU>`
+
+:ref:`3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API? <3_whatisRCU>`
+
+:ref:`4. WHAT IF MY UPDATING THREAD CANNOT BLOCK? <4_whatisRCU>`
+
+:ref:`5. WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU? <5_whatisRCU>`
+
+:ref:`6. ANALOGY WITH READER-WRITER LOCKING <6_whatisRCU>`
+
+:ref:`7. ANALOGY WITH REFERENCE COUNTING <7_whatisRCU>`
+
+:ref:`8. FULL LIST OF RCU APIs <8_whatisRCU>`
+
+:ref:`9. ANSWERS TO QUICK QUIZZES <9_whatisRCU>`
+
+People who prefer starting with a conceptual overview should focus on
+Section 1, though most readers will profit by reading this section at
+some point. People who prefer to start with an API that they can then
+experiment with should focus on Section 2. People who prefer to start
+with example uses should focus on Sections 3 and 4. People who need to
+understand the RCU implementation should focus on Section 5, then dive
+into the kernel source code. People who reason best by analogy should
+focus on Section 6 and 7. Section 8 serves as an index to the docbook
+API documentation, and Section 9 is the traditional answer key.
+
+So, start with the section that makes the most sense to you and your
+preferred method of learning. If you need to know everything about
+everything, feel free to read the whole thing -- but if you are really
+that type of person, you have perused the source code and will therefore
+never need this document anyway. ;-)
+
+.. _1_whatisRCU:
+
+1. RCU OVERVIEW
+----------------
+
+The basic idea behind RCU is to split updates into "removal" and
+"reclamation" phases. The removal phase removes references to data items
+within a data structure (possibly by replacing them with references to
+new versions of these data items), and can run concurrently with readers.
+The reason that it is safe to run the removal phase concurrently with
+readers is the semantics of modern CPUs guarantee that readers will see
+either the old or the new version of the data structure rather than a
+partially updated reference. The reclamation phase does the work of reclaiming
+(e.g., freeing) the data items removed from the data structure during the
+removal phase. Because reclaiming data items can disrupt any readers
+concurrently referencing those data items, the reclamation phase must
+not start until readers no longer hold references to those data items.
+
+Splitting the update into removal and reclamation phases permits the
+updater to perform the removal phase immediately, and to defer the
+reclamation phase until all readers active during the removal phase have
+completed, either by blocking until they finish or by registering a
+callback that is invoked after they finish. Only readers that are active
+during the removal phase need be considered, because any reader starting
+after the removal phase will be unable to gain a reference to the removed
+data items, and therefore cannot be disrupted by the reclamation phase.
+
+So the typical RCU update sequence goes something like the following:
+
+a. Remove pointers to a data structure, so that subsequent
+ readers cannot gain a reference to it.
+
+b. Wait for all previous readers to complete their RCU read-side
+ critical sections.
+
+c. At this point, there cannot be any readers who hold references
+ to the data structure, so it now may safely be reclaimed
+ (e.g., kfree()d).
+
+Step (b) above is the key idea underlying RCU's deferred destruction.
+The ability to wait until all readers are done allows RCU readers to
+use much lighter-weight synchronization, in some cases, absolutely no
+synchronization at all. In contrast, in more conventional lock-based
+schemes, readers must use heavy-weight synchronization in order to
+prevent an updater from deleting the data structure out from under them.
+This is because lock-based updaters typically update data items in place,
+and must therefore exclude readers. In contrast, RCU-based updaters
+typically take advantage of the fact that writes to single aligned
+pointers are atomic on modern CPUs, allowing atomic insertion, removal,
+and replacement of data items in a linked structure without disrupting
+readers. Concurrent RCU readers can then continue accessing the old
+versions, and can dispense with the atomic operations, memory barriers,
+and communications cache misses that are so expensive on present-day
+SMP computer systems, even in absence of lock contention.
+
+In the three-step procedure shown above, the updater is performing both
+the removal and the reclamation step, but it is often helpful for an
+entirely different thread to do the reclamation, as is in fact the case
+in the Linux kernel's directory-entry cache (dcache). Even if the same
+thread performs both the update step (step (a) above) and the reclamation
+step (step (c) above), it is often helpful to think of them separately.
+For example, RCU readers and updaters need not communicate at all,
+but RCU provides implicit low-overhead communication between readers
+and reclaimers, namely, in step (b) above.
+
+So how the heck can a reclaimer tell when a reader is done, given
+that readers are not doing any sort of synchronization operations???
+Read on to learn about how RCU's API makes this easy.
+
+.. _2_whatisRCU:
+
+2. WHAT IS RCU'S CORE API?
+---------------------------
+
+The core RCU API is quite small:
+
+a. rcu_read_lock()
+b. rcu_read_unlock()
+c. synchronize_rcu() / call_rcu()
+d. rcu_assign_pointer()
+e. rcu_dereference()
+
+There are many other members of the RCU API, but the rest can be
+expressed in terms of these five, though most implementations instead
+express synchronize_rcu() in terms of the call_rcu() callback API.
+
+The five core RCU APIs are described below, the other 18 will be enumerated
+later. See the kernel docbook documentation for more info, or look directly
+at the function header comments.
+
+rcu_read_lock()
+^^^^^^^^^^^^^^^
+ void rcu_read_lock(void);
+
+ This temporal primitive is used by a reader to inform the
+ reclaimer that the reader is entering an RCU read-side critical
+ section. It is illegal to block while in an RCU read-side
+ critical section, though kernels built with CONFIG_PREEMPT_RCU
+ can preempt RCU read-side critical sections. Any RCU-protected
+ data structure accessed during an RCU read-side critical section
+ is guaranteed to remain unreclaimed for the full duration of that
+ critical section. Reference counts may be used in conjunction
+ with RCU to maintain longer-term references to data structures.
+
+ Note that anything that disables bottom halves, preemption,
+ or interrupts also enters an RCU read-side critical section.
+ Acquiring a spinlock also enters an RCU read-side critical
+ sections, even for spinlocks that do not disable preemption,
+ as is the case in kernels built with CONFIG_PREEMPT_RT=y.
+ Sleeplocks do *not* enter RCU read-side critical sections.
+
+rcu_read_unlock()
+^^^^^^^^^^^^^^^^^
+ void rcu_read_unlock(void);
+
+ This temporal primitives is used by a reader to inform the
+ reclaimer that the reader is exiting an RCU read-side critical
+ section. Anything that enables bottom halves, preemption,
+ or interrupts also exits an RCU read-side critical section.
+ Releasing a spinlock also exits an RCU read-side critical section.
+
+ Note that RCU read-side critical sections may be nested and/or
+ overlapping.
+
+synchronize_rcu()
+^^^^^^^^^^^^^^^^^
+ void synchronize_rcu(void);
+
+ This temporal primitive marks the end of updater code and the
+ beginning of reclaimer code. It does this by blocking until
+ all pre-existing RCU read-side critical sections on all CPUs
+ have completed. Note that synchronize_rcu() will **not**
+ necessarily wait for any subsequent RCU read-side critical
+ sections to complete. For example, consider the following
+ sequence of events::
+
+ CPU 0 CPU 1 CPU 2
+ ----------------- ------------------------- ---------------
+ 1. rcu_read_lock()
+ 2. enters synchronize_rcu()
+ 3. rcu_read_lock()
+ 4. rcu_read_unlock()
+ 5. exits synchronize_rcu()
+ 6. rcu_read_unlock()
+
+ To reiterate, synchronize_rcu() waits only for ongoing RCU
+ read-side critical sections to complete, not necessarily for
+ any that begin after synchronize_rcu() is invoked.
+
+ Of course, synchronize_rcu() does not necessarily return
+ **immediately** after the last pre-existing RCU read-side critical
+ section completes. For one thing, there might well be scheduling
+ delays. For another thing, many RCU implementations process
+ requests in batches in order to improve efficiencies, which can
+ further delay synchronize_rcu().
+
+ Since synchronize_rcu() is the API that must figure out when
+ readers are done, its implementation is key to RCU. For RCU
+ to be useful in all but the most read-intensive situations,
+ synchronize_rcu()'s overhead must also be quite small.
+
+ The call_rcu() API is an asynchronous callback form of
+ synchronize_rcu(), and is described in more detail in a later
+ section. Instead of blocking, it registers a function and
+ argument which are invoked after all ongoing RCU read-side
+ critical sections have completed. This callback variant is
+ particularly useful in situations where it is illegal to block
+ or where update-side performance is critically important.
+
+ However, the call_rcu() API should not be used lightly, as use
+ of the synchronize_rcu() API generally results in simpler code.
+ In addition, the synchronize_rcu() API has the nice property
+ of automatically limiting update rate should grace periods
+ be delayed. This property results in system resilience in face
+ of denial-of-service attacks. Code using call_rcu() should limit
+ update rate in order to gain this same sort of resilience. See
+ checklist.rst for some approaches to limiting the update rate.
+
+rcu_assign_pointer()
+^^^^^^^^^^^^^^^^^^^^
+ void rcu_assign_pointer(p, typeof(p) v);
+
+ Yes, rcu_assign_pointer() **is** implemented as a macro, though
+ it would be cool to be able to declare a function in this manner.
+ (And there has been some discussion of adding overloaded functions
+ to the C language, so who knows?)
+
+ The updater uses this spatial macro to assign a new value to an
+ RCU-protected pointer, in order to safely communicate the change
+ in value from the updater to the reader. This is a spatial (as
+ opposed to temporal) macro. It does not evaluate to an rvalue,
+ but it does provide any compiler directives and memory-barrier
+ instructions required for a given compile or CPU architecture.
+ Its ordering properties are that of a store-release operation,
+ that is, any prior loads and stores required to initialize the
+ structure are ordered before the store that publishes the pointer
+ to that structure.
+
+ Perhaps just as important, rcu_assign_pointer() serves to document
+ (1) which pointers are protected by RCU and (2) the point at which
+ a given structure becomes accessible to other CPUs. That said,
+ rcu_assign_pointer() is most frequently used indirectly, via
+ the _rcu list-manipulation primitives such as list_add_rcu().
+
+rcu_dereference()
+^^^^^^^^^^^^^^^^^
+ typeof(p) rcu_dereference(p);
+
+ Like rcu_assign_pointer(), rcu_dereference() must be implemented
+ as a macro.
+
+ The reader uses the spatial rcu_dereference() macro to fetch
+ an RCU-protected pointer, which returns a value that may
+ then be safely dereferenced. Note that rcu_dereference()
+ does not actually dereference the pointer, instead, it
+ protects the pointer for later dereferencing. It also
+ executes any needed memory-barrier instructions for a given
+ CPU architecture. Currently, only Alpha needs memory barriers
+ within rcu_dereference() -- on other CPUs, it compiles to a
+ volatile load. However, no mainstream C compilers respect
+ address dependencies, so rcu_dereference() uses volatile casts,
+ which, in combination with the coding guidelines listed in
+ rcu_dereference.rst, prevent current compilers from breaking
+ these dependencies.
+
+ Common coding practice uses rcu_dereference() to copy an
+ RCU-protected pointer to a local variable, then dereferences
+ this local variable, for example as follows::
+
+ p = rcu_dereference(head.next);
+ return p->data;
+
+ However, in this case, one could just as easily combine these
+ into one statement::
+
+ return rcu_dereference(head.next)->data;
+
+ If you are going to be fetching multiple fields from the
+ RCU-protected structure, using the local variable is of
+ course preferred. Repeated rcu_dereference() calls look
+ ugly, do not guarantee that the same pointer will be returned
+ if an update happened while in the critical section, and incur
+ unnecessary overhead on Alpha CPUs.
+
+ Note that the value returned by rcu_dereference() is valid
+ only within the enclosing RCU read-side critical section [1]_.
+ For example, the following is **not** legal::
+
+ rcu_read_lock();
+ p = rcu_dereference(head.next);
+ rcu_read_unlock();
+ x = p->address; /* BUG!!! */
+ rcu_read_lock();
+ y = p->data; /* BUG!!! */
+ rcu_read_unlock();
+
+ Holding a reference from one RCU read-side critical section
+ to another is just as illegal as holding a reference from
+ one lock-based critical section to another! Similarly,
+ using a reference outside of the critical section in which
+ it was acquired is just as illegal as doing so with normal
+ locking.
+
+ As with rcu_assign_pointer(), an important function of
+ rcu_dereference() is to document which pointers are protected by
+ RCU, in particular, flagging a pointer that is subject to changing
+ at any time, including immediately after the rcu_dereference().
+ And, again like rcu_assign_pointer(), rcu_dereference() is
+ typically used indirectly, via the _rcu list-manipulation
+ primitives, such as list_for_each_entry_rcu() [2]_.
+
+.. [1] The variant rcu_dereference_protected() can be used outside
+ of an RCU read-side critical section as long as the usage is
+ protected by locks acquired by the update-side code. This variant
+ avoids the lockdep warning that would happen when using (for
+ example) rcu_dereference() without rcu_read_lock() protection.
+ Using rcu_dereference_protected() also has the advantage
+ of permitting compiler optimizations that rcu_dereference()
+ must prohibit. The rcu_dereference_protected() variant takes
+ a lockdep expression to indicate which locks must be acquired
+ by the caller. If the indicated protection is not provided,
+ a lockdep splat is emitted. See Design/Requirements/Requirements.rst
+ and the API's code comments for more details and example usage.
+
+.. [2] If the list_for_each_entry_rcu() instance might be used by
+ update-side code as well as by RCU readers, then an additional
+ lockdep expression can be added to its list of arguments.
+ For example, given an additional "lock_is_held(&mylock)" argument,
+ the RCU lockdep code would complain only if this instance was
+ invoked outside of an RCU read-side critical section and without
+ the protection of mylock.
+
+The following diagram shows how each API communicates among the
+reader, updater, and reclaimer.
+::
+
+
+ rcu_assign_pointer()
+ +--------+
+ +---------------------->| reader |---------+
+ | +--------+ |
+ | | |
+ | | | Protect:
+ | | | rcu_read_lock()
+ | | | rcu_read_unlock()
+ | rcu_dereference() | |
+ +---------+ | |
+ | updater |<----------------+ |
+ +---------+ V
+ | +-----------+
+ +----------------------------------->| reclaimer |
+ +-----------+
+ Defer:
+ synchronize_rcu() & call_rcu()
+
+
+The RCU infrastructure observes the temporal sequence of rcu_read_lock(),
+rcu_read_unlock(), synchronize_rcu(), and call_rcu() invocations in
+order to determine when (1) synchronize_rcu() invocations may return
+to their callers and (2) call_rcu() callbacks may be invoked. Efficient
+implementations of the RCU infrastructure make heavy use of batching in
+order to amortize their overhead over many uses of the corresponding APIs.
+The rcu_assign_pointer() and rcu_dereference() invocations communicate
+spatial changes via stores to and loads from the RCU-protected pointer in
+question.
+
+There are at least three flavors of RCU usage in the Linux kernel. The diagram
+above shows the most common one. On the updater side, the rcu_assign_pointer(),
+synchronize_rcu() and call_rcu() primitives used are the same for all three
+flavors. However for protection (on the reader side), the primitives used vary
+depending on the flavor:
+
+a. rcu_read_lock() / rcu_read_unlock()
+ rcu_dereference()
+
+b. rcu_read_lock_bh() / rcu_read_unlock_bh()
+ local_bh_disable() / local_bh_enable()
+ rcu_dereference_bh()
+
+c. rcu_read_lock_sched() / rcu_read_unlock_sched()
+ preempt_disable() / preempt_enable()
+ local_irq_save() / local_irq_restore()
+ hardirq enter / hardirq exit
+ NMI enter / NMI exit
+ rcu_dereference_sched()
+
+These three flavors are used as follows:
+
+a. RCU applied to normal data structures.
+
+b. RCU applied to networking data structures that may be subjected
+ to remote denial-of-service attacks.
+
+c. RCU applied to scheduler and interrupt/NMI-handler tasks.
+
+Again, most uses will be of (a). The (b) and (c) cases are important
+for specialized uses, but are relatively uncommon. The SRCU, RCU-Tasks,
+RCU-Tasks-Rude, and RCU-Tasks-Trace have similar relationships among
+their assorted primitives.
+
+.. _3_whatisRCU:
+
+3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
+-----------------------------------------------
+
+This section shows a simple use of the core RCU API to protect a
+global pointer to a dynamically allocated structure. More-typical
+uses of RCU may be found in listRCU.rst and NMI-RCU.rst.
+::
+
+ struct foo {
+ int a;
+ char b;
+ long c;
+ };
+ DEFINE_SPINLOCK(foo_mutex);
+
+ struct foo __rcu *gbl_foo;
+
+ /*
+ * Create a new struct foo that is the same as the one currently
+ * pointed to by gbl_foo, except that field "a" is replaced
+ * with "new_a". Points gbl_foo to the new structure, and
+ * frees up the old structure after a grace period.
+ *
+ * Uses rcu_assign_pointer() to ensure that concurrent readers
+ * see the initialized version of the new structure.
+ *
+ * Uses synchronize_rcu() to ensure that any readers that might
+ * have references to the old structure complete before freeing
+ * the old structure.
+ */
+ void foo_update_a(int new_a)
+ {
+ struct foo *new_fp;
+ struct foo *old_fp;
+
+ new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
+ spin_lock(&foo_mutex);
+ old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
+ *new_fp = *old_fp;
+ new_fp->a = new_a;
+ rcu_assign_pointer(gbl_foo, new_fp);
+ spin_unlock(&foo_mutex);
+ synchronize_rcu();
+ kfree(old_fp);
+ }
+
+ /*
+ * Return the value of field "a" of the current gbl_foo
+ * structure. Use rcu_read_lock() and rcu_read_unlock()
+ * to ensure that the structure does not get deleted out
+ * from under us, and use rcu_dereference() to ensure that
+ * we see the initialized version of the structure (important
+ * for DEC Alpha and for people reading the code).
+ */
+ int foo_get_a(void)
+ {
+ int retval;
+
+ rcu_read_lock();
+ retval = rcu_dereference(gbl_foo)->a;
+ rcu_read_unlock();
+ return retval;
+ }
+
+So, to sum up:
+
+- Use rcu_read_lock() and rcu_read_unlock() to guard RCU
+ read-side critical sections.
+
+- Within an RCU read-side critical section, use rcu_dereference()
+ to dereference RCU-protected pointers.
+
+- Use some solid design (such as locks or semaphores) to
+ keep concurrent updates from interfering with each other.
+
+- Use rcu_assign_pointer() to update an RCU-protected pointer.
+ This primitive protects concurrent readers from the updater,
+ **not** concurrent updates from each other! You therefore still
+ need to use locking (or something similar) to keep concurrent
+ rcu_assign_pointer() primitives from interfering with each other.
+
+- Use synchronize_rcu() **after** removing a data element from an
+ RCU-protected data structure, but **before** reclaiming/freeing
+ the data element, in order to wait for the completion of all
+ RCU read-side critical sections that might be referencing that
+ data item.
+
+See checklist.rst for additional rules to follow when using RCU.
+And again, more-typical uses of RCU may be found in listRCU.rst
+and NMI-RCU.rst.
+
+.. _4_whatisRCU:
+
+4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
+--------------------------------------------
+
+In the example above, foo_update_a() blocks until a grace period elapses.
+This is quite simple, but in some cases one cannot afford to wait so
+long -- there might be other high-priority work to be done.
+
+In such cases, one uses call_rcu() rather than synchronize_rcu().
+The call_rcu() API is as follows::
+
+ void call_rcu(struct rcu_head *head, rcu_callback_t func);
+
+This function invokes func(head) after a grace period has elapsed.
+This invocation might happen from either softirq or process context,
+so the function is not permitted to block. The foo struct needs to
+have an rcu_head structure added, perhaps as follows::
+
+ struct foo {
+ int a;
+ char b;
+ long c;
+ struct rcu_head rcu;
+ };
+
+The foo_update_a() function might then be written as follows::
+
+ /*
+ * Create a new struct foo that is the same as the one currently
+ * pointed to by gbl_foo, except that field "a" is replaced
+ * with "new_a". Points gbl_foo to the new structure, and
+ * frees up the old structure after a grace period.
+ *
+ * Uses rcu_assign_pointer() to ensure that concurrent readers
+ * see the initialized version of the new structure.
+ *
+ * Uses call_rcu() to ensure that any readers that might have
+ * references to the old structure complete before freeing the
+ * old structure.
+ */
+ void foo_update_a(int new_a)
+ {
+ struct foo *new_fp;
+ struct foo *old_fp;
+
+ new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
+ spin_lock(&foo_mutex);
+ old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
+ *new_fp = *old_fp;
+ new_fp->a = new_a;
+ rcu_assign_pointer(gbl_foo, new_fp);
+ spin_unlock(&foo_mutex);
+ call_rcu(&old_fp->rcu, foo_reclaim);
+ }
+
+The foo_reclaim() function might appear as follows::
+
+ void foo_reclaim(struct rcu_head *rp)
+ {
+ struct foo *fp = container_of(rp, struct foo, rcu);
+
+ foo_cleanup(fp->a);
+
+ kfree(fp);
+ }
+
+The container_of() primitive is a macro that, given a pointer into a
+struct, the type of the struct, and the pointed-to field within the
+struct, returns a pointer to the beginning of the struct.
+
+The use of call_rcu() permits the caller of foo_update_a() to
+immediately regain control, without needing to worry further about the
+old version of the newly updated element. It also clearly shows the
+RCU distinction between updater, namely foo_update_a(), and reclaimer,
+namely foo_reclaim().
+
+The summary of advice is the same as for the previous section, except
+that we are now using call_rcu() rather than synchronize_rcu():
+
+- Use call_rcu() **after** removing a data element from an
+ RCU-protected data structure in order to register a callback
+ function that will be invoked after the completion of all RCU
+ read-side critical sections that might be referencing that
+ data item.
+
+If the callback for call_rcu() is not doing anything more than calling
+kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
+to avoid having to write your own callback::
+
+ kfree_rcu(old_fp, rcu);
+
+If the occasional sleep is permitted, the single-argument form may
+be used, omitting the rcu_head structure from struct foo.
+
+ kfree_rcu_mightsleep(old_fp);
+
+This variant almost never blocks, but might do so by invoking
+synchronize_rcu() in response to memory-allocation failure.
+
+Again, see checklist.rst for additional rules governing the use of RCU.
+
+.. _5_whatisRCU:
+
+5. WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
+------------------------------------------------
+
+One of the nice things about RCU is that it has extremely simple "toy"
+implementations that are a good first step towards understanding the
+production-quality implementations in the Linux kernel. This section
+presents two such "toy" implementations of RCU, one that is implemented
+in terms of familiar locking primitives, and another that more closely
+resembles "classic" RCU. Both are way too simple for real-world use,
+lacking both functionality and performance. However, they are useful
+in getting a feel for how RCU works. See kernel/rcu/update.c for a
+production-quality implementation, and see:
+
+ https://docs.google.com/document/d/1X0lThx8OK0ZgLMqVoXiR4ZrGURHrXK6NyLRbeXe3Xac/edit
+
+for papers describing the Linux kernel RCU implementation. The OLS'01
+and OLS'02 papers are a good introduction, and the dissertation provides
+more details on the current implementation as of early 2004.
+
+
+5A. "TOY" IMPLEMENTATION #1: LOCKING
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This section presents a "toy" RCU implementation that is based on
+familiar locking primitives. Its overhead makes it a non-starter for
+real-life use, as does its lack of scalability. It is also unsuitable
+for realtime use, since it allows scheduling latency to "bleed" from
+one read-side critical section to another. It also assumes recursive
+reader-writer locks: If you try this with non-recursive locks, and
+you allow nested rcu_read_lock() calls, you can deadlock.
+
+However, it is probably the easiest implementation to relate to, so is
+a good starting point.
+
+It is extremely simple::
+
+ static DEFINE_RWLOCK(rcu_gp_mutex);
+
+ void rcu_read_lock(void)
+ {
+ read_lock(&rcu_gp_mutex);
+ }
+
+ void rcu_read_unlock(void)
+ {
+ read_unlock(&rcu_gp_mutex);
+ }
+
+ void synchronize_rcu(void)
+ {
+ write_lock(&rcu_gp_mutex);
+ smp_mb__after_spinlock();
+ write_unlock(&rcu_gp_mutex);
+ }
+
+[You can ignore rcu_assign_pointer() and rcu_dereference() without missing
+much. But here are simplified versions anyway. And whatever you do,
+don't forget about them when submitting patches making use of RCU!]::
+
+ #define rcu_assign_pointer(p, v) \
+ ({ \
+ smp_store_release(&(p), (v)); \
+ })
+
+ #define rcu_dereference(p) \
+ ({ \
+ typeof(p) _________p1 = READ_ONCE(p); \
+ (_________p1); \
+ })
+
+
+The rcu_read_lock() and rcu_read_unlock() primitive read-acquire
+and release a global reader-writer lock. The synchronize_rcu()
+primitive write-acquires this same lock, then releases it. This means
+that once synchronize_rcu() exits, all RCU read-side critical sections
+that were in progress before synchronize_rcu() was called are guaranteed
+to have completed -- there is no way that synchronize_rcu() would have
+been able to write-acquire the lock otherwise. The smp_mb__after_spinlock()
+promotes synchronize_rcu() to a full memory barrier in compliance with
+the "Memory-Barrier Guarantees" listed in:
+
+ Design/Requirements/Requirements.rst
+
+It is possible to nest rcu_read_lock(), since reader-writer locks may
+be recursively acquired. Note also that rcu_read_lock() is immune
+from deadlock (an important property of RCU). The reason for this is
+that the only thing that can block rcu_read_lock() is a synchronize_rcu().
+But synchronize_rcu() does not acquire any locks while holding rcu_gp_mutex,
+so there can be no deadlock cycle.
+
+.. _quiz_1:
+
+Quick Quiz #1:
+ Why is this argument naive? How could a deadlock
+ occur when using this algorithm in a real-world Linux
+ kernel? How could this deadlock be avoided?
+
+:ref:`Answers to Quick Quiz <9_whatisRCU>`
+
+5B. "TOY" EXAMPLE #2: CLASSIC RCU
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This section presents a "toy" RCU implementation that is based on
+"classic RCU". It is also short on performance (but only for updates) and
+on features such as hotplug CPU and the ability to run in CONFIG_PREEMPTION
+kernels. The definitions of rcu_dereference() and rcu_assign_pointer()
+are the same as those shown in the preceding section, so they are omitted.
+::
+
+ void rcu_read_lock(void) { }
+
+ void rcu_read_unlock(void) { }
+
+ void synchronize_rcu(void)
+ {
+ int cpu;
+
+ for_each_possible_cpu(cpu)
+ run_on(cpu);
+ }
+
+Note that rcu_read_lock() and rcu_read_unlock() do absolutely nothing.
+This is the great strength of classic RCU in a non-preemptive kernel:
+read-side overhead is precisely zero, at least on non-Alpha CPUs.
+And there is absolutely no way that rcu_read_lock() can possibly
+participate in a deadlock cycle!
+
+The implementation of synchronize_rcu() simply schedules itself on each
+CPU in turn. The run_on() primitive can be implemented straightforwardly
+in terms of the sched_setaffinity() primitive. Of course, a somewhat less
+"toy" implementation would restore the affinity upon completion rather
+than just leaving all tasks running on the last CPU, but when I said
+"toy", I meant **toy**!
+
+So how the heck is this supposed to work???
+
+Remember that it is illegal to block while in an RCU read-side critical
+section. Therefore, if a given CPU executes a context switch, we know
+that it must have completed all preceding RCU read-side critical sections.
+Once **all** CPUs have executed a context switch, then **all** preceding
+RCU read-side critical sections will have completed.
+
+So, suppose that we remove a data item from its structure and then invoke
+synchronize_rcu(). Once synchronize_rcu() returns, we are guaranteed
+that there are no RCU read-side critical sections holding a reference
+to that data item, so we can safely reclaim it.
+
+.. _quiz_2:
+
+Quick Quiz #2:
+ Give an example where Classic RCU's read-side
+ overhead is **negative**.
+
+:ref:`Answers to Quick Quiz <9_whatisRCU>`
+
+.. _quiz_3:
+
+Quick Quiz #3:
+ If it is illegal to block in an RCU read-side
+ critical section, what the heck do you do in
+ CONFIG_PREEMPT_RT, where normal spinlocks can block???
+
+:ref:`Answers to Quick Quiz <9_whatisRCU>`
+
+.. _6_whatisRCU:
+
+6. ANALOGY WITH READER-WRITER LOCKING
+--------------------------------------
+
+Although RCU can be used in many different ways, a very common use of
+RCU is analogous to reader-writer locking. The following unified
+diff shows how closely related RCU and reader-writer locking can be.
+::
+
+ @@ -5,5 +5,5 @@ struct el {
+ int data;
+ /* Other data fields */
+ };
+ -rwlock_t listmutex;
+ +spinlock_t listmutex;
+ struct el head;
+
+ @@ -13,15 +14,15 @@
+ struct list_head *lp;
+ struct el *p;
+
+ - read_lock(&listmutex);
+ - list_for_each_entry(p, head, lp) {
+ + rcu_read_lock();
+ + list_for_each_entry_rcu(p, head, lp) {
+ if (p->key == key) {
+ *result = p->data;
+ - read_unlock(&listmutex);
+ + rcu_read_unlock();
+ return 1;
+ }
+ }
+ - read_unlock(&listmutex);
+ + rcu_read_unlock();
+ return 0;
+ }
+
+ @@ -29,15 +30,16 @@
+ {
+ struct el *p;
+
+ - write_lock(&listmutex);
+ + spin_lock(&listmutex);
+ list_for_each_entry(p, head, lp) {
+ if (p->key == key) {
+ - list_del(&p->list);
+ - write_unlock(&listmutex);
+ + list_del_rcu(&p->list);
+ + spin_unlock(&listmutex);
+ + synchronize_rcu();
+ kfree(p);
+ return 1;
+ }
+ }
+ - write_unlock(&listmutex);
+ + spin_unlock(&listmutex);
+ return 0;
+ }
+
+Or, for those who prefer a side-by-side listing::
+
+ 1 struct el { 1 struct el {
+ 2 struct list_head list; 2 struct list_head list;
+ 3 long key; 3 long key;
+ 4 spinlock_t mutex; 4 spinlock_t mutex;
+ 5 int data; 5 int data;
+ 6 /* Other data fields */ 6 /* Other data fields */
+ 7 }; 7 };
+ 8 rwlock_t listmutex; 8 spinlock_t listmutex;
+ 9 struct el head; 9 struct el head;
+
+::
+
+ 1 int search(long key, int *result) 1 int search(long key, int *result)
+ 2 { 2 {
+ 3 struct list_head *lp; 3 struct list_head *lp;
+ 4 struct el *p; 4 struct el *p;
+ 5 5
+ 6 read_lock(&listmutex); 6 rcu_read_lock();
+ 7 list_for_each_entry(p, head, lp) { 7 list_for_each_entry_rcu(p, head, lp) {
+ 8 if (p->key == key) { 8 if (p->key == key) {
+ 9 *result = p->data; 9 *result = p->data;
+ 10 read_unlock(&listmutex); 10 rcu_read_unlock();
+ 11 return 1; 11 return 1;
+ 12 } 12 }
+ 13 } 13 }
+ 14 read_unlock(&listmutex); 14 rcu_read_unlock();
+ 15 return 0; 15 return 0;
+ 16 } 16 }
+
+::
+
+ 1 int delete(long key) 1 int delete(long key)
+ 2 { 2 {
+ 3 struct el *p; 3 struct el *p;
+ 4 4
+ 5 write_lock(&listmutex); 5 spin_lock(&listmutex);
+ 6 list_for_each_entry(p, head, lp) { 6 list_for_each_entry(p, head, lp) {
+ 7 if (p->key == key) { 7 if (p->key == key) {
+ 8 list_del(&p->list); 8 list_del_rcu(&p->list);
+ 9 write_unlock(&listmutex); 9 spin_unlock(&listmutex);
+ 10 synchronize_rcu();
+ 10 kfree(p); 11 kfree(p);
+ 11 return 1; 12 return 1;
+ 12 } 13 }
+ 13 } 14 }
+ 14 write_unlock(&listmutex); 15 spin_unlock(&listmutex);
+ 15 return 0; 16 return 0;
+ 16 } 17 }
+
+Either way, the differences are quite small. Read-side locking moves
+to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
+a reader-writer lock to a simple spinlock, and a synchronize_rcu()
+precedes the kfree().
+
+However, there is one potential catch: the read-side and update-side
+critical sections can now run concurrently. In many cases, this will
+not be a problem, but it is necessary to check carefully regardless.
+For example, if multiple independent list updates must be seen as
+a single atomic update, converting to RCU will require special care.
+
+Also, the presence of synchronize_rcu() means that the RCU version of
+delete() can now block. If this is a problem, there is a callback-based
+mechanism that never blocks, namely call_rcu() or kfree_rcu(), that can
+be used in place of synchronize_rcu().
+
+.. _7_whatisRCU:
+
+7. ANALOGY WITH REFERENCE COUNTING
+-----------------------------------
+
+The reader-writer analogy (illustrated by the previous section) is not
+always the best way to think about using RCU. Another helpful analogy
+considers RCU an effective reference count on everything which is
+protected by RCU.
+
+A reference count typically does not prevent the referenced object's
+values from changing, but does prevent changes to type -- particularly the
+gross change of type that happens when that object's memory is freed and
+re-allocated for some other purpose. Once a type-safe reference to the
+object is obtained, some other mechanism is needed to ensure consistent
+access to the data in the object. This could involve taking a spinlock,
+but with RCU the typical approach is to perform reads with SMP-aware
+operations such as smp_load_acquire(), to perform updates with atomic
+read-modify-write operations, and to provide the necessary ordering.
+RCU provides a number of support functions that embed the required
+operations and ordering, such as the list_for_each_entry_rcu() macro
+used in the previous section.
+
+A more focused view of the reference counting behavior is that,
+between rcu_read_lock() and rcu_read_unlock(), any reference taken with
+rcu_dereference() on a pointer marked as ``__rcu`` can be treated as
+though a reference-count on that object has been temporarily increased.
+This prevents the object from changing type. Exactly what this means
+will depend on normal expectations of objects of that type, but it
+typically includes that spinlocks can still be safely locked, normal
+reference counters can be safely manipulated, and ``__rcu`` pointers
+can be safely dereferenced.
+
+Some operations that one might expect to see on an object for
+which an RCU reference is held include:
+
+ - Copying out data that is guaranteed to be stable by the object's type.
+ - Using kref_get_unless_zero() or similar to get a longer-term
+ reference. This may fail of course.
+ - Acquiring a spinlock in the object, and checking if the object still
+ is the expected object and if so, manipulating it freely.
+
+The understanding that RCU provides a reference that only prevents a
+change of type is particularly visible with objects allocated from a
+slab cache marked ``SLAB_TYPESAFE_BY_RCU``. RCU operations may yield a
+reference to an object from such a cache that has been concurrently freed
+and the memory reallocated to a completely different object, though of
+the same type. In this case RCU doesn't even protect the identity of the
+object from changing, only its type. So the object found may not be the
+one expected, but it will be one where it is safe to take a reference
+(and then potentially acquiring a spinlock), allowing subsequent code
+to check whether the identity matches expectations. It is tempting
+to simply acquire the spinlock without first taking the reference, but
+unfortunately any spinlock in a ``SLAB_TYPESAFE_BY_RCU`` object must be
+initialized after each and every call to kmem_cache_alloc(), which renders
+reference-free spinlock acquisition completely unsafe. Therefore, when
+using ``SLAB_TYPESAFE_BY_RCU``, make proper use of a reference counter.
+If using refcount_t, the specialized refcount_{add|inc}_not_zero_acquire()
+and refcount_set_release() APIs should be used to ensure correct operation
+ordering when verifying object identity and when initializing newly
+allocated objects. Acquire fence in refcount_{add|inc}_not_zero_acquire()
+ensures that identity checks happen *after* reference count is taken.
+refcount_set_release() should be called after a newly allocated object is
+fully initialized and release fence ensures that new values are visible
+*before* refcount can be successfully taken by other users. Once
+refcount_set_release() is called, the object should be considered visible
+by other tasks.
+(Those willing to initialize their locks in a kmem_cache constructor
+may also use locking, including cache-friendly sequence locking.)
+
+With traditional reference counting -- such as that implemented by the
+kref library in Linux -- there is typically code that runs when the last
+reference to an object is dropped. With kref, this is the function
+passed to kref_put(). When RCU is being used, such finalization code
+must not be run until all ``__rcu`` pointers referencing the object have
+been updated, and then a grace period has passed. Every remaining
+globally visible pointer to the object must be considered to be a
+potential counted reference, and the finalization code is typically run
+using call_rcu() only after all those pointers have been changed.
+
+To see how to choose between these two analogies -- of RCU as a
+reader-writer lock and RCU as a reference counting system -- it is useful
+to reflect on the scale of the thing being protected. The reader-writer
+lock analogy looks at larger multi-part objects such as a linked list
+and shows how RCU can facilitate concurrency while elements are added
+to, and removed from, the list. The reference-count analogy looks at
+the individual objects and looks at how they can be accessed safely
+within whatever whole they are a part of.
+
+.. _8_whatisRCU:
+
+8. FULL LIST OF RCU APIs
+-------------------------
+
+The RCU APIs are documented in docbook-format header comments in the
+Linux-kernel source code, but it helps to have a full list of the
+APIs, since there does not appear to be a way to categorize them
+in docbook. Here is the list, by category.
+
+RCU list traversal::
+
+ list_entry_rcu
+ list_entry_lockless
+ list_first_entry_rcu
+ list_first_or_null_rcu
+ list_tail_rcu
+ list_next_rcu
+ list_next_or_null_rcu
+ list_for_each_entry_rcu
+ list_for_each_entry_continue_rcu
+ list_for_each_entry_from_rcu
+ list_for_each_entry_lockless
+ hlist_first_rcu
+ hlist_next_rcu
+ hlist_pprev_rcu
+ hlist_for_each_entry_rcu
+ hlist_for_each_entry_rcu_notrace
+ hlist_for_each_entry_rcu_bh
+ hlist_for_each_entry_from_rcu
+ hlist_for_each_entry_continue_rcu
+ hlist_for_each_entry_continue_rcu_bh
+ hlist_nulls_first_rcu
+ hlist_nulls_next_rcu
+ hlist_nulls_for_each_entry_rcu
+ hlist_nulls_for_each_entry_safe
+ hlist_bl_first_rcu
+ hlist_bl_for_each_entry_rcu
+
+RCU pointer/list update::
+
+ rcu_assign_pointer
+ rcu_replace_pointer
+ INIT_LIST_HEAD_RCU
+ list_add_rcu
+ list_add_tail_rcu
+ list_del_rcu
+ list_replace_rcu
+ list_splice_init_rcu
+ list_splice_tail_init_rcu
+ hlist_add_behind_rcu
+ hlist_add_before_rcu
+ hlist_add_head_rcu
+ hlist_add_tail_rcu
+ hlist_del_rcu
+ hlist_del_init_rcu
+ hlist_replace_rcu
+ hlist_nulls_del_init_rcu
+ hlist_nulls_del_rcu
+ hlist_nulls_add_head_rcu
+ hlist_nulls_add_tail_rcu
+ hlist_nulls_add_fake
+ hlists_swap_heads_rcu
+ hlist_bl_add_head_rcu
+ hlist_bl_del_rcu
+ hlist_bl_set_first_rcu
+
+RCU::
+
+ Critical sections Grace period Barrier
+
+ rcu_read_lock synchronize_net rcu_barrier
+ rcu_read_unlock synchronize_rcu
+ guard(rcu)() synchronize_rcu_expedited
+ scoped_guard(rcu) synchronize_rcu_mult
+ rcu_dereference call_rcu
+ rcu_dereference_check call_rcu_hurry
+ rcu_dereference_protected kfree_rcu
+ rcu_read_lock_held kvfree_rcu
+ rcu_read_lock_any_held kfree_rcu_mightsleep
+ rcu_pointer_handoff cond_synchronize_rcu
+ unrcu_pointer cond_synchronize_rcu_full
+ cond_synchronize_rcu_expedited
+ cond_synchronize_rcu_expedited_full
+ get_completed_synchronize_rcu
+ get_completed_synchronize_rcu_full
+ get_state_synchronize_rcu
+ get_state_synchronize_rcu_full
+ poll_state_synchronize_rcu
+ poll_state_synchronize_rcu_full
+ same_state_synchronize_rcu
+ same_state_synchronize_rcu_full
+ start_poll_synchronize_rcu
+ start_poll_synchronize_rcu_full
+ start_poll_synchronize_rcu_expedited
+ start_poll_synchronize_rcu_expedited_full
+
+bh::
+
+ Critical sections Grace period Barrier
+
+ rcu_read_lock_bh [Same as RCU] [Same as RCU]
+ rcu_read_unlock_bh
+ [local_bh_disable]
+ [and friends]
+ rcu_dereference_bh
+ rcu_dereference_bh_check
+ rcu_dereference_bh_protected
+ rcu_read_lock_bh_held
+
+sched::
+
+ Critical sections Grace period Barrier
+
+ rcu_read_lock_sched [Same as RCU] [Same as RCU]
+ rcu_read_unlock_sched
+ [preempt_disable]
+ [and friends]
+ rcu_read_lock_sched_notrace
+ rcu_read_unlock_sched_notrace
+ rcu_dereference_sched
+ rcu_dereference_sched_check
+ rcu_dereference_sched_protected
+ rcu_read_lock_sched_held
+
+
+RCU: Initialization/cleanup/ordering::
+
+ RCU_INIT_POINTER
+ RCU_INITIALIZER
+ RCU_POINTER_INITIALIZER
+ init_rcu_head
+ destroy_rcu_head
+ init_rcu_head_on_stack
+ destroy_rcu_head_on_stack
+ SLAB_TYPESAFE_BY_RCU
+
+
+RCU: Quiescents states and control::
+
+ cond_resched_tasks_rcu_qs
+ rcu_all_qs
+ rcu_softirq_qs_periodic
+ rcu_end_inkernel_boot
+ rcu_expedite_gp
+ rcu_gp_is_expedited
+ rcu_unexpedite_gp
+ rcu_cpu_stall_reset
+ rcu_head_after_call_rcu
+ rcu_is_watching
+
+
+RCU-sync primitive::
+
+ rcu_sync_is_idle
+ rcu_sync_init
+ rcu_sync_enter
+ rcu_sync_exit
+ rcu_sync_dtor
+
+
+RCU-Tasks::
+
+ Critical sections Grace period Barrier
+
+ N/A call_rcu_tasks rcu_barrier_tasks
+ synchronize_rcu_tasks
+
+
+RCU-Tasks-Rude::
+
+ Critical sections Grace period Barrier
+
+ N/A synchronize_rcu_tasks_rude rcu_barrier_tasks_rude
+ call_rcu_tasks_rude
+
+
+RCU-Tasks-Trace::
+
+ Critical sections Grace period Barrier
+
+ rcu_read_lock_trace call_rcu_tasks_trace rcu_barrier_tasks_trace
+ rcu_read_unlock_trace synchronize_rcu_tasks_trace
+ guard(rcu_tasks_trace)()
+ scoped_guard(rcu_tasks_trace)
+
+
+SRCU list traversal::
+ list_for_each_entry_srcu
+ hlist_for_each_entry_srcu
+
+
+SRCU::
+
+ Critical sections Grace period Barrier
+
+ srcu_read_lock call_srcu srcu_barrier
+ srcu_read_unlock synchronize_srcu
+ srcu_read_lock_fast synchronize_srcu_expedited
+ srcu_read_unlock_fast get_state_synchronize_srcu
+ srcu_read_lock_nmisafe start_poll_synchronize_srcu
+ srcu_read_unlock_nmisafe start_poll_synchronize_srcu_expedited
+ srcu_read_lock_notrace poll_state_synchronize_srcu
+ srcu_read_unlock_notrace
+ srcu_down_read
+ srcu_up_read
+ srcu_down_read_fast
+ srcu_up_read_fast
+ guard(srcu)()
+ scoped_guard(srcu)
+ srcu_read_lock_held
+ srcu_dereference
+ srcu_dereference_check
+ srcu_dereference_notrace
+ srcu_read_lock_held
+
+
+SRCU: Initialization/cleanup/ordering::
+
+ DEFINE_SRCU
+ DEFINE_STATIC_SRCU
+ DEFINE_SRCU_FAST // for srcu_read_lock_fast() and friends
+ DEFINE_STATIC_SRCU_FAST // for srcu_read_lock_fast() and friends
+ init_srcu_struct
+ init_srcu_struct_fast
+ cleanup_srcu_struct
+ smp_mb__after_srcu_read_unlock
+
+All: lockdep-checked RCU utility APIs::
+
+ RCU_LOCKDEP_WARN
+ rcu_sleep_check
+
+All: Unchecked RCU-protected pointer access::
+
+ rcu_dereference_raw
+
+All: Unchecked RCU-protected pointer access with dereferencing prohibited::
+
+ rcu_access_pointer
+
+See the comment headers in the source code (or the docbook generated
+from them) for more information.
+
+However, given that there are no fewer than four families of RCU APIs
+in the Linux kernel, how do you choose which one to use? The following
+list can be helpful:
+
+a. Will readers need to block? If so, you need SRCU.
+
+b. Will readers need to block and are you doing tracing, for
+ example, ftrace or BPF? If so, you need RCU-tasks,
+ RCU-tasks-rude, and/or RCU-tasks-trace.
+
+c. What about the -rt patchset? If readers would need to block in
+ an non-rt kernel, you need SRCU. If readers would block when
+ acquiring spinlocks in a -rt kernel, but not in a non-rt kernel,
+ SRCU is not necessary. (The -rt patchset turns spinlocks into
+ sleeplocks, hence this distinction.)
+
+d. Do you need to treat NMI handlers, hardirq handlers,
+ and code segments with preemption disabled (whether
+ via preempt_disable(), local_irq_save(), local_bh_disable(),
+ or some other mechanism) as if they were explicit RCU readers?
+ If so, RCU-sched readers are the only choice that will work
+ for you, but since about v4.20 you use can use the vanilla RCU
+ update primitives.
+
+e. Do you need RCU grace periods to complete even in the face of
+ softirq monopolization of one or more of the CPUs? For example,
+ is your code subject to network-based denial-of-service attacks?
+ If so, you should disable softirq across your readers, for
+ example, by using rcu_read_lock_bh(). Since about v4.20 you
+ use can use the vanilla RCU update primitives.
+
+f. Is your workload too update-intensive for normal use of
+ RCU, but inappropriate for other synchronization mechanisms?
+ If so, consider SLAB_TYPESAFE_BY_RCU (which was originally
+ named SLAB_DESTROY_BY_RCU). But please be careful!
+
+g. Do you need read-side critical sections that are respected even
+ on CPUs that are deep in the idle loop, during entry to or exit
+ from user-mode execution, or on an offlined CPU? If so, SRCU
+ and RCU Tasks Trace are the only choices that will work for you,
+ with SRCU being strongly preferred in almost all cases.
+
+h. Otherwise, use RCU.
+
+Of course, this all assumes that you have determined that RCU is in fact
+the right tool for your job.
+
+.. _9_whatisRCU:
+
+9. ANSWERS TO QUICK QUIZZES
+----------------------------
+
+Quick Quiz #1:
+ Why is this argument naive? How could a deadlock
+ occur when using this algorithm in a real-world Linux
+ kernel? [Referring to the lock-based "toy" RCU
+ algorithm.]
+
+Answer:
+ Consider the following sequence of events:
+
+ 1. CPU 0 acquires some unrelated lock, call it
+ "problematic_lock", disabling irq via
+ spin_lock_irqsave().
+
+ 2. CPU 1 enters synchronize_rcu(), write-acquiring
+ rcu_gp_mutex.
+
+ 3. CPU 0 enters rcu_read_lock(), but must wait
+ because CPU 1 holds rcu_gp_mutex.
+
+ 4. CPU 1 is interrupted, and the irq handler
+ attempts to acquire problematic_lock.
+
+ The system is now deadlocked.
+
+ One way to avoid this deadlock is to use an approach like
+ that of CONFIG_PREEMPT_RT, where all normal spinlocks
+ become blocking locks, and all irq handlers execute in
+ the context of special tasks. In this case, in step 4
+ above, the irq handler would block, allowing CPU 1 to
+ release rcu_gp_mutex, avoiding the deadlock.
+
+ Even in the absence of deadlock, this RCU implementation
+ allows latency to "bleed" from readers to other
+ readers through synchronize_rcu(). To see this,
+ consider task A in an RCU read-side critical section
+ (thus read-holding rcu_gp_mutex), task B blocked
+ attempting to write-acquire rcu_gp_mutex, and
+ task C blocked in rcu_read_lock() attempting to
+ read_acquire rcu_gp_mutex. Task A's RCU read-side
+ latency is holding up task C, albeit indirectly via
+ task B.
+
+ Realtime RCU implementations therefore use a counter-based
+ approach where tasks in RCU read-side critical sections
+ cannot be blocked by tasks executing synchronize_rcu().
+
+:ref:`Back to Quick Quiz #1 <quiz_1>`
+
+Quick Quiz #2:
+ Give an example where Classic RCU's read-side
+ overhead is **negative**.
+
+Answer:
+ Imagine a single-CPU system with a non-CONFIG_PREEMPTION
+ kernel where a routing table is used by process-context
+ code, but can be updated by irq-context code (for example,
+ by an "ICMP REDIRECT" packet). The usual way of handling
+ this would be to have the process-context code disable
+ interrupts while searching the routing table. Use of
+ RCU allows such interrupt-disabling to be dispensed with.
+ Thus, without RCU, you pay the cost of disabling interrupts,
+ and with RCU you don't.
+
+ One can argue that the overhead of RCU in this
+ case is negative with respect to the single-CPU
+ interrupt-disabling approach. Others might argue that
+ the overhead of RCU is merely zero, and that replacing
+ the positive overhead of the interrupt-disabling scheme
+ with the zero-overhead RCU scheme does not constitute
+ negative overhead.
+
+ In real life, of course, things are more complex. But
+ even the theoretical possibility of negative overhead for
+ a synchronization primitive is a bit unexpected. ;-)
+
+:ref:`Back to Quick Quiz #2 <quiz_2>`
+
+Quick Quiz #3:
+ If it is illegal to block in an RCU read-side
+ critical section, what the heck do you do in
+ CONFIG_PREEMPT_RT, where normal spinlocks can block???
+
+Answer:
+ Just as CONFIG_PREEMPT_RT permits preemption of spinlock
+ critical sections, it permits preemption of RCU
+ read-side critical sections. It also permits
+ spinlocks blocking while in RCU read-side critical
+ sections.
+
+ Why the apparent inconsistency? Because it is
+ possible to use priority boosting to keep the RCU
+ grace periods short if need be (for example, if running
+ short of memory). In contrast, if blocking waiting
+ for (say) network reception, there is no way to know
+ what should be boosted. Especially given that the
+ process we need to boost might well be a human being
+ who just went out for a pizza or something. And although
+ a computer-operated cattle prod might arouse serious
+ interest, it might also provoke serious objections.
+ Besides, how does the computer know what pizza parlor
+ the human being went to???
+
+:ref:`Back to Quick Quiz #3 <quiz_3>`
+
+ACKNOWLEDGEMENTS
+
+My thanks to the people who helped make this human-readable, including
+Jon Walpole, Josh Triplett, Serge Hallyn, Suzanne Wood, and Alan Stern.
+
+
+For more information, see http://www.rdrop.com/users/paulmck/RCU.
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
deleted file mode 100644
index 88dfce182f66..000000000000
--- a/Documentation/RCU/whatisRCU.txt
+++ /dev/null
@@ -1,1031 +0,0 @@
-Please note that the "What is RCU?" LWN series is an excellent place
-to start learning about RCU:
-
-1. What is RCU, Fundamentally? http://lwn.net/Articles/262464/
-2. What is RCU? Part 2: Usage http://lwn.net/Articles/263130/
-3. RCU part 3: the RCU API http://lwn.net/Articles/264090/
-4. The RCU API, 2010 Edition http://lwn.net/Articles/418853/
-
-
-What is RCU?
-
-RCU is a synchronization mechanism that was added to the Linux kernel
-during the 2.5 development effort that is optimized for read-mostly
-situations. Although RCU is actually quite simple once you understand it,
-getting there can sometimes be a challenge. Part of the problem is that
-most of the past descriptions of RCU have been written with the mistaken
-assumption that there is "one true way" to describe RCU. Instead,
-the experience has been that different people must take different paths
-to arrive at an understanding of RCU. This document provides several
-different paths, as follows:
-
-1. RCU OVERVIEW
-2. WHAT IS RCU'S CORE API?
-3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
-4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
-5. WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
-6. ANALOGY WITH READER-WRITER LOCKING
-7. FULL LIST OF RCU APIs
-8. ANSWERS TO QUICK QUIZZES
-
-People who prefer starting with a conceptual overview should focus on
-Section 1, though most readers will profit by reading this section at
-some point. People who prefer to start with an API that they can then
-experiment with should focus on Section 2. People who prefer to start
-with example uses should focus on Sections 3 and 4. People who need to
-understand the RCU implementation should focus on Section 5, then dive
-into the kernel source code. People who reason best by analogy should
-focus on Section 6. Section 7 serves as an index to the docbook API
-documentation, and Section 8 is the traditional answer key.
-
-So, start with the section that makes the most sense to you and your
-preferred method of learning. If you need to know everything about
-everything, feel free to read the whole thing -- but if you are really
-that type of person, you have perused the source code and will therefore
-never need this document anyway. ;-)
-
-
-1. RCU OVERVIEW
-
-The basic idea behind RCU is to split updates into "removal" and
-"reclamation" phases. The removal phase removes references to data items
-within a data structure (possibly by replacing them with references to
-new versions of these data items), and can run concurrently with readers.
-The reason that it is safe to run the removal phase concurrently with
-readers is the semantics of modern CPUs guarantee that readers will see
-either the old or the new version of the data structure rather than a
-partially updated reference. The reclamation phase does the work of reclaiming
-(e.g., freeing) the data items removed from the data structure during the
-removal phase. Because reclaiming data items can disrupt any readers
-concurrently referencing those data items, the reclamation phase must
-not start until readers no longer hold references to those data items.
-
-Splitting the update into removal and reclamation phases permits the
-updater to perform the removal phase immediately, and to defer the
-reclamation phase until all readers active during the removal phase have
-completed, either by blocking until they finish or by registering a
-callback that is invoked after they finish. Only readers that are active
-during the removal phase need be considered, because any reader starting
-after the removal phase will be unable to gain a reference to the removed
-data items, and therefore cannot be disrupted by the reclamation phase.
-
-So the typical RCU update sequence goes something like the following:
-
-a. Remove pointers to a data structure, so that subsequent
- readers cannot gain a reference to it.
-
-b. Wait for all previous readers to complete their RCU read-side
- critical sections.
-
-c. At this point, there cannot be any readers who hold references
- to the data structure, so it now may safely be reclaimed
- (e.g., kfree()d).
-
-Step (b) above is the key idea underlying RCU's deferred destruction.
-The ability to wait until all readers are done allows RCU readers to
-use much lighter-weight synchronization, in some cases, absolutely no
-synchronization at all. In contrast, in more conventional lock-based
-schemes, readers must use heavy-weight synchronization in order to
-prevent an updater from deleting the data structure out from under them.
-This is because lock-based updaters typically update data items in place,
-and must therefore exclude readers. In contrast, RCU-based updaters
-typically take advantage of the fact that writes to single aligned
-pointers are atomic on modern CPUs, allowing atomic insertion, removal,
-and replacement of data items in a linked structure without disrupting
-readers. Concurrent RCU readers can then continue accessing the old
-versions, and can dispense with the atomic operations, memory barriers,
-and communications cache misses that are so expensive on present-day
-SMP computer systems, even in absence of lock contention.
-
-In the three-step procedure shown above, the updater is performing both
-the removal and the reclamation step, but it is often helpful for an
-entirely different thread to do the reclamation, as is in fact the case
-in the Linux kernel's directory-entry cache (dcache). Even if the same
-thread performs both the update step (step (a) above) and the reclamation
-step (step (c) above), it is often helpful to think of them separately.
-For example, RCU readers and updaters need not communicate at all,
-but RCU provides implicit low-overhead communication between readers
-and reclaimers, namely, in step (b) above.
-
-So how the heck can a reclaimer tell when a reader is done, given
-that readers are not doing any sort of synchronization operations???
-Read on to learn about how RCU's API makes this easy.
-
-
-2. WHAT IS RCU'S CORE API?
-
-The core RCU API is quite small:
-
-a. rcu_read_lock()
-b. rcu_read_unlock()
-c. synchronize_rcu() / call_rcu()
-d. rcu_assign_pointer()
-e. rcu_dereference()
-
-There are many other members of the RCU API, but the rest can be
-expressed in terms of these five, though most implementations instead
-express synchronize_rcu() in terms of the call_rcu() callback API.
-
-The five core RCU APIs are described below, the other 18 will be enumerated
-later. See the kernel docbook documentation for more info, or look directly
-at the function header comments.
-
-rcu_read_lock()
-
- void rcu_read_lock(void);
-
- Used by a reader to inform the reclaimer that the reader is
- entering an RCU read-side critical section. It is illegal
- to block while in an RCU read-side critical section, though
- kernels built with CONFIG_PREEMPT_RCU can preempt RCU
- read-side critical sections. Any RCU-protected data structure
- accessed during an RCU read-side critical section is guaranteed to
- remain unreclaimed for the full duration of that critical section.
- Reference counts may be used in conjunction with RCU to maintain
- longer-term references to data structures.
-
-rcu_read_unlock()
-
- void rcu_read_unlock(void);
-
- Used by a reader to inform the reclaimer that the reader is
- exiting an RCU read-side critical section. Note that RCU
- read-side critical sections may be nested and/or overlapping.
-
-synchronize_rcu()
-
- void synchronize_rcu(void);
-
- Marks the end of updater code and the beginning of reclaimer
- code. It does this by blocking until all pre-existing RCU
- read-side critical sections on all CPUs have completed.
- Note that synchronize_rcu() will -not- necessarily wait for
- any subsequent RCU read-side critical sections to complete.
- For example, consider the following sequence of events:
-
- CPU 0 CPU 1 CPU 2
- ----------------- ------------------------- ---------------
- 1. rcu_read_lock()
- 2. enters synchronize_rcu()
- 3. rcu_read_lock()
- 4. rcu_read_unlock()
- 5. exits synchronize_rcu()
- 6. rcu_read_unlock()
-
- To reiterate, synchronize_rcu() waits only for ongoing RCU
- read-side critical sections to complete, not necessarily for
- any that begin after synchronize_rcu() is invoked.
-
- Of course, synchronize_rcu() does not necessarily return
- -immediately- after the last pre-existing RCU read-side critical
- section completes. For one thing, there might well be scheduling
- delays. For another thing, many RCU implementations process
- requests in batches in order to improve efficiencies, which can
- further delay synchronize_rcu().
-
- Since synchronize_rcu() is the API that must figure out when
- readers are done, its implementation is key to RCU. For RCU
- to be useful in all but the most read-intensive situations,
- synchronize_rcu()'s overhead must also be quite small.
-
- The call_rcu() API is a callback form of synchronize_rcu(),
- and is described in more detail in a later section. Instead of
- blocking, it registers a function and argument which are invoked
- after all ongoing RCU read-side critical sections have completed.
- This callback variant is particularly useful in situations where
- it is illegal to block or where update-side performance is
- critically important.
-
- However, the call_rcu() API should not be used lightly, as use
- of the synchronize_rcu() API generally results in simpler code.
- In addition, the synchronize_rcu() API has the nice property
- of automatically limiting update rate should grace periods
- be delayed. This property results in system resilience in face
- of denial-of-service attacks. Code using call_rcu() should limit
- update rate in order to gain this same sort of resilience. See
- checklist.txt for some approaches to limiting the update rate.
-
-rcu_assign_pointer()
-
- typeof(p) rcu_assign_pointer(p, typeof(p) v);
-
- Yes, rcu_assign_pointer() -is- implemented as a macro, though it
- would be cool to be able to declare a function in this manner.
- (Compiler experts will no doubt disagree.)
-
- The updater uses this function to assign a new value to an
- RCU-protected pointer, in order to safely communicate the change
- in value from the updater to the reader. This function returns
- the new value, and also executes any memory-barrier instructions
- required for a given CPU architecture.
-
- Perhaps just as important, it serves to document (1) which
- pointers are protected by RCU and (2) the point at which a
- given structure becomes accessible to other CPUs. That said,
- rcu_assign_pointer() is most frequently used indirectly, via
- the _rcu list-manipulation primitives such as list_add_rcu().
-
-rcu_dereference()
-
- typeof(p) rcu_dereference(p);
-
- Like rcu_assign_pointer(), rcu_dereference() must be implemented
- as a macro.
-
- The reader uses rcu_dereference() to fetch an RCU-protected
- pointer, which returns a value that may then be safely
- dereferenced. Note that rcu_deference() does not actually
- dereference the pointer, instead, it protects the pointer for
- later dereferencing. It also executes any needed memory-barrier
- instructions for a given CPU architecture. Currently, only Alpha
- needs memory barriers within rcu_dereference() -- on other CPUs,
- it compiles to nothing, not even a compiler directive.
-
- Common coding practice uses rcu_dereference() to copy an
- RCU-protected pointer to a local variable, then dereferences
- this local variable, for example as follows:
-
- p = rcu_dereference(head.next);
- return p->data;
-
- However, in this case, one could just as easily combine these
- into one statement:
-
- return rcu_dereference(head.next)->data;
-
- If you are going to be fetching multiple fields from the
- RCU-protected structure, using the local variable is of
- course preferred. Repeated rcu_dereference() calls look
- ugly and incur unnecessary overhead on Alpha CPUs.
-
- Note that the value returned by rcu_dereference() is valid
- only within the enclosing RCU read-side critical section.
- For example, the following is -not- legal:
-
- rcu_read_lock();
- p = rcu_dereference(head.next);
- rcu_read_unlock();
- x = p->address; /* BUG!!! */
- rcu_read_lock();
- y = p->data; /* BUG!!! */
- rcu_read_unlock();
-
- Holding a reference from one RCU read-side critical section
- to another is just as illegal as holding a reference from
- one lock-based critical section to another! Similarly,
- using a reference outside of the critical section in which
- it was acquired is just as illegal as doing so with normal
- locking.
-
- As with rcu_assign_pointer(), an important function of
- rcu_dereference() is to document which pointers are protected by
- RCU, in particular, flagging a pointer that is subject to changing
- at any time, including immediately after the rcu_dereference().
- And, again like rcu_assign_pointer(), rcu_dereference() is
- typically used indirectly, via the _rcu list-manipulation
- primitives, such as list_for_each_entry_rcu().
-
-The following diagram shows how each API communicates among the
-reader, updater, and reclaimer.
-
-
- rcu_assign_pointer()
- +--------+
- +---------------------->| reader |---------+
- | +--------+ |
- | | |
- | | | Protect:
- | | | rcu_read_lock()
- | | | rcu_read_unlock()
- | rcu_dereference() | |
- +---------+ | |
- | updater |<---------------------+ |
- +---------+ V
- | +-----------+
- +----------------------------------->| reclaimer |
- +-----------+
- Defer:
- synchronize_rcu() & call_rcu()
-
-
-The RCU infrastructure observes the time sequence of rcu_read_lock(),
-rcu_read_unlock(), synchronize_rcu(), and call_rcu() invocations in
-order to determine when (1) synchronize_rcu() invocations may return
-to their callers and (2) call_rcu() callbacks may be invoked. Efficient
-implementations of the RCU infrastructure make heavy use of batching in
-order to amortize their overhead over many uses of the corresponding APIs.
-
-There are no fewer than three RCU mechanisms in the Linux kernel; the
-diagram above shows the first one, which is by far the most commonly used.
-The rcu_dereference() and rcu_assign_pointer() primitives are used for
-all three mechanisms, but different defer and protect primitives are
-used as follows:
-
- Defer Protect
-
-a. synchronize_rcu() rcu_read_lock() / rcu_read_unlock()
- call_rcu() rcu_dereference()
-
-b. synchronize_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh()
- call_rcu_bh() rcu_dereference_bh()
-
-c. synchronize_sched() rcu_read_lock_sched() / rcu_read_unlock_sched()
- call_rcu_sched() preempt_disable() / preempt_enable()
- local_irq_save() / local_irq_restore()
- hardirq enter / hardirq exit
- NMI enter / NMI exit
- rcu_dereference_sched()
-
-These three mechanisms are used as follows:
-
-a. RCU applied to normal data structures.
-
-b. RCU applied to networking data structures that may be subjected
- to remote denial-of-service attacks.
-
-c. RCU applied to scheduler and interrupt/NMI-handler tasks.
-
-Again, most uses will be of (a). The (b) and (c) cases are important
-for specialized uses, but are relatively uncommon.
-
-
-3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
-
-This section shows a simple use of the core RCU API to protect a
-global pointer to a dynamically allocated structure. More-typical
-uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
-
- struct foo {
- int a;
- char b;
- long c;
- };
- DEFINE_SPINLOCK(foo_mutex);
-
- struct foo *gbl_foo;
-
- /*
- * Create a new struct foo that is the same as the one currently
- * pointed to by gbl_foo, except that field "a" is replaced
- * with "new_a". Points gbl_foo to the new structure, and
- * frees up the old structure after a grace period.
- *
- * Uses rcu_assign_pointer() to ensure that concurrent readers
- * see the initialized version of the new structure.
- *
- * Uses synchronize_rcu() to ensure that any readers that might
- * have references to the old structure complete before freeing
- * the old structure.
- */
- void foo_update_a(int new_a)
- {
- struct foo *new_fp;
- struct foo *old_fp;
-
- new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
- spin_lock(&foo_mutex);
- old_fp = gbl_foo;
- *new_fp = *old_fp;
- new_fp->a = new_a;
- rcu_assign_pointer(gbl_foo, new_fp);
- spin_unlock(&foo_mutex);
- synchronize_rcu();
- kfree(old_fp);
- }
-
- /*
- * Return the value of field "a" of the current gbl_foo
- * structure. Use rcu_read_lock() and rcu_read_unlock()
- * to ensure that the structure does not get deleted out
- * from under us, and use rcu_dereference() to ensure that
- * we see the initialized version of the structure (important
- * for DEC Alpha and for people reading the code).
- */
- int foo_get_a(void)
- {
- int retval;
-
- rcu_read_lock();
- retval = rcu_dereference(gbl_foo)->a;
- rcu_read_unlock();
- return retval;
- }
-
-So, to sum up:
-
-o Use rcu_read_lock() and rcu_read_unlock() to guard RCU
- read-side critical sections.
-
-o Within an RCU read-side critical section, use rcu_dereference()
- to dereference RCU-protected pointers.
-
-o Use some solid scheme (such as locks or semaphores) to
- keep concurrent updates from interfering with each other.
-
-o Use rcu_assign_pointer() to update an RCU-protected pointer.
- This primitive protects concurrent readers from the updater,
- -not- concurrent updates from each other! You therefore still
- need to use locking (or something similar) to keep concurrent
- rcu_assign_pointer() primitives from interfering with each other.
-
-o Use synchronize_rcu() -after- removing a data element from an
- RCU-protected data structure, but -before- reclaiming/freeing
- the data element, in order to wait for the completion of all
- RCU read-side critical sections that might be referencing that
- data item.
-
-See checklist.txt for additional rules to follow when using RCU.
-And again, more-typical uses of RCU may be found in listRCU.txt,
-arrayRCU.txt, and NMI-RCU.txt.
-
-
-4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
-
-In the example above, foo_update_a() blocks until a grace period elapses.
-This is quite simple, but in some cases one cannot afford to wait so
-long -- there might be other high-priority work to be done.
-
-In such cases, one uses call_rcu() rather than synchronize_rcu().
-The call_rcu() API is as follows:
-
- void call_rcu(struct rcu_head * head,
- void (*func)(struct rcu_head *head));
-
-This function invokes func(head) after a grace period has elapsed.
-This invocation might happen from either softirq or process context,
-so the function is not permitted to block. The foo struct needs to
-have an rcu_head structure added, perhaps as follows:
-
- struct foo {
- int a;
- char b;
- long c;
- struct rcu_head rcu;
- };
-
-The foo_update_a() function might then be written as follows:
-
- /*
- * Create a new struct foo that is the same as the one currently
- * pointed to by gbl_foo, except that field "a" is replaced
- * with "new_a". Points gbl_foo to the new structure, and
- * frees up the old structure after a grace period.
- *
- * Uses rcu_assign_pointer() to ensure that concurrent readers
- * see the initialized version of the new structure.
- *
- * Uses call_rcu() to ensure that any readers that might have
- * references to the old structure complete before freeing the
- * old structure.
- */
- void foo_update_a(int new_a)
- {
- struct foo *new_fp;
- struct foo *old_fp;
-
- new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
- spin_lock(&foo_mutex);
- old_fp = gbl_foo;
- *new_fp = *old_fp;
- new_fp->a = new_a;
- rcu_assign_pointer(gbl_foo, new_fp);
- spin_unlock(&foo_mutex);
- call_rcu(&old_fp->rcu, foo_reclaim);
- }
-
-The foo_reclaim() function might appear as follows:
-
- void foo_reclaim(struct rcu_head *rp)
- {
- struct foo *fp = container_of(rp, struct foo, rcu);
-
- foo_cleanup(fp->a);
-
- kfree(fp);
- }
-
-The container_of() primitive is a macro that, given a pointer into a
-struct, the type of the struct, and the pointed-to field within the
-struct, returns a pointer to the beginning of the struct.
-
-The use of call_rcu() permits the caller of foo_update_a() to
-immediately regain control, without needing to worry further about the
-old version of the newly updated element. It also clearly shows the
-RCU distinction between updater, namely foo_update_a(), and reclaimer,
-namely foo_reclaim().
-
-The summary of advice is the same as for the previous section, except
-that we are now using call_rcu() rather than synchronize_rcu():
-
-o Use call_rcu() -after- removing a data element from an
- RCU-protected data structure in order to register a callback
- function that will be invoked after the completion of all RCU
- read-side critical sections that might be referencing that
- data item.
-
-If the callback for call_rcu() is not doing anything more than calling
-kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
-to avoid having to write your own callback:
-
- kfree_rcu(old_fp, rcu);
-
-Again, see checklist.txt for additional rules governing the use of RCU.
-
-
-5. WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
-
-One of the nice things about RCU is that it has extremely simple "toy"
-implementations that are a good first step towards understanding the
-production-quality implementations in the Linux kernel. This section
-presents two such "toy" implementations of RCU, one that is implemented
-in terms of familiar locking primitives, and another that more closely
-resembles "classic" RCU. Both are way too simple for real-world use,
-lacking both functionality and performance. However, they are useful
-in getting a feel for how RCU works. See kernel/rcupdate.c for a
-production-quality implementation, and see:
-
- http://www.rdrop.com/users/paulmck/RCU
-
-for papers describing the Linux kernel RCU implementation. The OLS'01
-and OLS'02 papers are a good introduction, and the dissertation provides
-more details on the current implementation as of early 2004.
-
-
-5A. "TOY" IMPLEMENTATION #1: LOCKING
-
-This section presents a "toy" RCU implementation that is based on
-familiar locking primitives. Its overhead makes it a non-starter for
-real-life use, as does its lack of scalability. It is also unsuitable
-for realtime use, since it allows scheduling latency to "bleed" from
-one read-side critical section to another.
-
-However, it is probably the easiest implementation to relate to, so is
-a good starting point.
-
-It is extremely simple:
-
- static DEFINE_RWLOCK(rcu_gp_mutex);
-
- void rcu_read_lock(void)
- {
- read_lock(&rcu_gp_mutex);
- }
-
- void rcu_read_unlock(void)
- {
- read_unlock(&rcu_gp_mutex);
- }
-
- void synchronize_rcu(void)
- {
- write_lock(&rcu_gp_mutex);
- write_unlock(&rcu_gp_mutex);
- }
-
-[You can ignore rcu_assign_pointer() and rcu_dereference() without
-missing much. But here they are anyway. And whatever you do, don't
-forget about them when submitting patches making use of RCU!]
-
- #define rcu_assign_pointer(p, v) ({ \
- smp_wmb(); \
- (p) = (v); \
- })
-
- #define rcu_dereference(p) ({ \
- typeof(p) _________p1 = p; \
- smp_read_barrier_depends(); \
- (_________p1); \
- })
-
-
-The rcu_read_lock() and rcu_read_unlock() primitive read-acquire
-and release a global reader-writer lock. The synchronize_rcu()
-primitive write-acquires this same lock, then immediately releases
-it. This means that once synchronize_rcu() exits, all RCU read-side
-critical sections that were in progress before synchronize_rcu() was
-called are guaranteed to have completed -- there is no way that
-synchronize_rcu() would have been able to write-acquire the lock
-otherwise.
-
-It is possible to nest rcu_read_lock(), since reader-writer locks may
-be recursively acquired. Note also that rcu_read_lock() is immune
-from deadlock (an important property of RCU). The reason for this is
-that the only thing that can block rcu_read_lock() is a synchronize_rcu().
-But synchronize_rcu() does not acquire any locks while holding rcu_gp_mutex,
-so there can be no deadlock cycle.
-
-Quick Quiz #1: Why is this argument naive? How could a deadlock
- occur when using this algorithm in a real-world Linux
- kernel? How could this deadlock be avoided?
-
-
-5B. "TOY" EXAMPLE #2: CLASSIC RCU
-
-This section presents a "toy" RCU implementation that is based on
-"classic RCU". It is also short on performance (but only for updates) and
-on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
-kernels. The definitions of rcu_dereference() and rcu_assign_pointer()
-are the same as those shown in the preceding section, so they are omitted.
-
- void rcu_read_lock(void) { }
-
- void rcu_read_unlock(void) { }
-
- void synchronize_rcu(void)
- {
- int cpu;
-
- for_each_possible_cpu(cpu)
- run_on(cpu);
- }
-
-Note that rcu_read_lock() and rcu_read_unlock() do absolutely nothing.
-This is the great strength of classic RCU in a non-preemptive kernel:
-read-side overhead is precisely zero, at least on non-Alpha CPUs.
-And there is absolutely no way that rcu_read_lock() can possibly
-participate in a deadlock cycle!
-
-The implementation of synchronize_rcu() simply schedules itself on each
-CPU in turn. The run_on() primitive can be implemented straightforwardly
-in terms of the sched_setaffinity() primitive. Of course, a somewhat less
-"toy" implementation would restore the affinity upon completion rather
-than just leaving all tasks running on the last CPU, but when I said
-"toy", I meant -toy-!
-
-So how the heck is this supposed to work???
-
-Remember that it is illegal to block while in an RCU read-side critical
-section. Therefore, if a given CPU executes a context switch, we know
-that it must have completed all preceding RCU read-side critical sections.
-Once -all- CPUs have executed a context switch, then -all- preceding
-RCU read-side critical sections will have completed.
-
-So, suppose that we remove a data item from its structure and then invoke
-synchronize_rcu(). Once synchronize_rcu() returns, we are guaranteed
-that there are no RCU read-side critical sections holding a reference
-to that data item, so we can safely reclaim it.
-
-Quick Quiz #2: Give an example where Classic RCU's read-side
- overhead is -negative-.
-
-Quick Quiz #3: If it is illegal to block in an RCU read-side
- critical section, what the heck do you do in
- PREEMPT_RT, where normal spinlocks can block???
-
-
-6. ANALOGY WITH READER-WRITER LOCKING
-
-Although RCU can be used in many different ways, a very common use of
-RCU is analogous to reader-writer locking. The following unified
-diff shows how closely related RCU and reader-writer locking can be.
-
- @@ -13,15 +14,15 @@
- struct list_head *lp;
- struct el *p;
-
- - read_lock();
- - list_for_each_entry(p, head, lp) {
- + rcu_read_lock();
- + list_for_each_entry_rcu(p, head, lp) {
- if (p->key == key) {
- *result = p->data;
- - read_unlock();
- + rcu_read_unlock();
- return 1;
- }
- }
- - read_unlock();
- + rcu_read_unlock();
- return 0;
- }
-
- @@ -29,15 +30,16 @@
- {
- struct el *p;
-
- - write_lock(&listmutex);
- + spin_lock(&listmutex);
- list_for_each_entry(p, head, lp) {
- if (p->key == key) {
- - list_del(&p->list);
- - write_unlock(&listmutex);
- + list_del_rcu(&p->list);
- + spin_unlock(&listmutex);
- + synchronize_rcu();
- kfree(p);
- return 1;
- }
- }
- - write_unlock(&listmutex);
- + spin_unlock(&listmutex);
- return 0;
- }
-
-Or, for those who prefer a side-by-side listing:
-
- 1 struct el { 1 struct el {
- 2 struct list_head list; 2 struct list_head list;
- 3 long key; 3 long key;
- 4 spinlock_t mutex; 4 spinlock_t mutex;
- 5 int data; 5 int data;
- 6 /* Other data fields */ 6 /* Other data fields */
- 7 }; 7 };
- 8 spinlock_t listmutex; 8 spinlock_t listmutex;
- 9 struct el head; 9 struct el head;
-
- 1 int search(long key, int *result) 1 int search(long key, int *result)
- 2 { 2 {
- 3 struct list_head *lp; 3 struct list_head *lp;
- 4 struct el *p; 4 struct el *p;
- 5 5
- 6 read_lock(); 6 rcu_read_lock();
- 7 list_for_each_entry(p, head, lp) { 7 list_for_each_entry_rcu(p, head, lp) {
- 8 if (p->key == key) { 8 if (p->key == key) {
- 9 *result = p->data; 9 *result = p->data;
-10 read_unlock(); 10 rcu_read_unlock();
-11 return 1; 11 return 1;
-12 } 12 }
-13 } 13 }
-14 read_unlock(); 14 rcu_read_unlock();
-15 return 0; 15 return 0;
-16 } 16 }
-
- 1 int delete(long key) 1 int delete(long key)
- 2 { 2 {
- 3 struct el *p; 3 struct el *p;
- 4 4
- 5 write_lock(&listmutex); 5 spin_lock(&listmutex);
- 6 list_for_each_entry(p, head, lp) { 6 list_for_each_entry(p, head, lp) {
- 7 if (p->key == key) { 7 if (p->key == key) {
- 8 list_del(&p->list); 8 list_del_rcu(&p->list);
- 9 write_unlock(&listmutex); 9 spin_unlock(&listmutex);
- 10 synchronize_rcu();
-10 kfree(p); 11 kfree(p);
-11 return 1; 12 return 1;
-12 } 13 }
-13 } 14 }
-14 write_unlock(&listmutex); 15 spin_unlock(&listmutex);
-15 return 0; 16 return 0;
-16 } 17 }
-
-Either way, the differences are quite small. Read-side locking moves
-to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
-a reader-writer lock to a simple spinlock, and a synchronize_rcu()
-precedes the kfree().
-
-However, there is one potential catch: the read-side and update-side
-critical sections can now run concurrently. In many cases, this will
-not be a problem, but it is necessary to check carefully regardless.
-For example, if multiple independent list updates must be seen as
-a single atomic update, converting to RCU will require special care.
-
-Also, the presence of synchronize_rcu() means that the RCU version of
-delete() can now block. If this is a problem, there is a callback-based
-mechanism that never blocks, namely call_rcu() or kfree_rcu(), that can
-be used in place of synchronize_rcu().
-
-
-7. FULL LIST OF RCU APIs
-
-The RCU APIs are documented in docbook-format header comments in the
-Linux-kernel source code, but it helps to have a full list of the
-APIs, since there does not appear to be a way to categorize them
-in docbook. Here is the list, by category.
-
-RCU list traversal:
-
- list_entry_rcu
- list_first_entry_rcu
- list_next_rcu
- list_for_each_entry_rcu
- list_for_each_entry_continue_rcu
- hlist_first_rcu
- hlist_next_rcu
- hlist_pprev_rcu
- hlist_for_each_entry_rcu
- hlist_for_each_entry_rcu_bh
- hlist_for_each_entry_continue_rcu
- hlist_for_each_entry_continue_rcu_bh
- hlist_nulls_first_rcu
- hlist_nulls_for_each_entry_rcu
- hlist_bl_first_rcu
- hlist_bl_for_each_entry_rcu
-
-RCU pointer/list update:
-
- rcu_assign_pointer
- list_add_rcu
- list_add_tail_rcu
- list_del_rcu
- list_replace_rcu
- hlist_add_behind_rcu
- hlist_add_before_rcu
- hlist_add_head_rcu
- hlist_del_rcu
- hlist_del_init_rcu
- hlist_replace_rcu
- list_splice_init_rcu()
- hlist_nulls_del_init_rcu
- hlist_nulls_del_rcu
- hlist_nulls_add_head_rcu
- hlist_bl_add_head_rcu
- hlist_bl_del_init_rcu
- hlist_bl_del_rcu
- hlist_bl_set_first_rcu
-
-RCU: Critical sections Grace period Barrier
-
- rcu_read_lock synchronize_net rcu_barrier
- rcu_read_unlock synchronize_rcu
- rcu_dereference synchronize_rcu_expedited
- rcu_read_lock_held call_rcu
- rcu_dereference_check kfree_rcu
- rcu_dereference_protected
-
-bh: Critical sections Grace period Barrier
-
- rcu_read_lock_bh call_rcu_bh rcu_barrier_bh
- rcu_read_unlock_bh synchronize_rcu_bh
- rcu_dereference_bh synchronize_rcu_bh_expedited
- rcu_dereference_bh_check
- rcu_dereference_bh_protected
- rcu_read_lock_bh_held
-
-sched: Critical sections Grace period Barrier
-
- rcu_read_lock_sched synchronize_sched rcu_barrier_sched
- rcu_read_unlock_sched call_rcu_sched
- [preempt_disable] synchronize_sched_expedited
- [and friends]
- rcu_read_lock_sched_notrace
- rcu_read_unlock_sched_notrace
- rcu_dereference_sched
- rcu_dereference_sched_check
- rcu_dereference_sched_protected
- rcu_read_lock_sched_held
-
-
-SRCU: Critical sections Grace period Barrier
-
- srcu_read_lock synchronize_srcu srcu_barrier
- srcu_read_unlock call_srcu
- srcu_dereference synchronize_srcu_expedited
- srcu_dereference_check
- srcu_read_lock_held
-
-SRCU: Initialization/cleanup
- init_srcu_struct
- cleanup_srcu_struct
-
-All: lockdep-checked RCU-protected pointer access
-
- rcu_access_index
- rcu_access_pointer
- rcu_dereference_index_check
- rcu_dereference_raw
- rcu_lockdep_assert
- rcu_sleep_check
- RCU_NONIDLE
-
-See the comment headers in the source code (or the docbook generated
-from them) for more information.
-
-However, given that there are no fewer than four families of RCU APIs
-in the Linux kernel, how do you choose which one to use? The following
-list can be helpful:
-
-a. Will readers need to block? If so, you need SRCU.
-
-b. What about the -rt patchset? If readers would need to block
- in an non-rt kernel, you need SRCU. If readers would block
- in a -rt kernel, but not in a non-rt kernel, SRCU is not
- necessary.
-
-c. Do you need to treat NMI handlers, hardirq handlers,
- and code segments with preemption disabled (whether
- via preempt_disable(), local_irq_save(), local_bh_disable(),
- or some other mechanism) as if they were explicit RCU readers?
- If so, RCU-sched is the only choice that will work for you.
-
-d. Do you need RCU grace periods to complete even in the face
- of softirq monopolization of one or more of the CPUs? For
- example, is your code subject to network-based denial-of-service
- attacks? If so, you need RCU-bh.
-
-e. Is your workload too update-intensive for normal use of
- RCU, but inappropriate for other synchronization mechanisms?
- If so, consider SLAB_DESTROY_BY_RCU. But please be careful!
-
-f. Do you need read-side critical sections that are respected
- even though they are in the middle of the idle loop, during
- user-mode execution, or on an offlined CPU? If so, SRCU is the
- only choice that will work for you.
-
-g. Otherwise, use RCU.
-
-Of course, this all assumes that you have determined that RCU is in fact
-the right tool for your job.
-
-
-8. ANSWERS TO QUICK QUIZZES
-
-Quick Quiz #1: Why is this argument naive? How could a deadlock
- occur when using this algorithm in a real-world Linux
- kernel? [Referring to the lock-based "toy" RCU
- algorithm.]
-
-Answer: Consider the following sequence of events:
-
- 1. CPU 0 acquires some unrelated lock, call it
- "problematic_lock", disabling irq via
- spin_lock_irqsave().
-
- 2. CPU 1 enters synchronize_rcu(), write-acquiring
- rcu_gp_mutex.
-
- 3. CPU 0 enters rcu_read_lock(), but must wait
- because CPU 1 holds rcu_gp_mutex.
-
- 4. CPU 1 is interrupted, and the irq handler
- attempts to acquire problematic_lock.
-
- The system is now deadlocked.
-
- One way to avoid this deadlock is to use an approach like
- that of CONFIG_PREEMPT_RT, where all normal spinlocks
- become blocking locks, and all irq handlers execute in
- the context of special tasks. In this case, in step 4
- above, the irq handler would block, allowing CPU 1 to
- release rcu_gp_mutex, avoiding the deadlock.
-
- Even in the absence of deadlock, this RCU implementation
- allows latency to "bleed" from readers to other
- readers through synchronize_rcu(). To see this,
- consider task A in an RCU read-side critical section
- (thus read-holding rcu_gp_mutex), task B blocked
- attempting to write-acquire rcu_gp_mutex, and
- task C blocked in rcu_read_lock() attempting to
- read_acquire rcu_gp_mutex. Task A's RCU read-side
- latency is holding up task C, albeit indirectly via
- task B.
-
- Realtime RCU implementations therefore use a counter-based
- approach where tasks in RCU read-side critical sections
- cannot be blocked by tasks executing synchronize_rcu().
-
-Quick Quiz #2: Give an example where Classic RCU's read-side
- overhead is -negative-.
-
-Answer: Imagine a single-CPU system with a non-CONFIG_PREEMPT
- kernel where a routing table is used by process-context
- code, but can be updated by irq-context code (for example,
- by an "ICMP REDIRECT" packet). The usual way of handling
- this would be to have the process-context code disable
- interrupts while searching the routing table. Use of
- RCU allows such interrupt-disabling to be dispensed with.
- Thus, without RCU, you pay the cost of disabling interrupts,
- and with RCU you don't.
-
- One can argue that the overhead of RCU in this
- case is negative with respect to the single-CPU
- interrupt-disabling approach. Others might argue that
- the overhead of RCU is merely zero, and that replacing
- the positive overhead of the interrupt-disabling scheme
- with the zero-overhead RCU scheme does not constitute
- negative overhead.
-
- In real life, of course, things are more complex. But
- even the theoretical possibility of negative overhead for
- a synchronization primitive is a bit unexpected. ;-)
-
-Quick Quiz #3: If it is illegal to block in an RCU read-side
- critical section, what the heck do you do in
- PREEMPT_RT, where normal spinlocks can block???
-
-Answer: Just as PREEMPT_RT permits preemption of spinlock
- critical sections, it permits preemption of RCU
- read-side critical sections. It also permits
- spinlocks blocking while in RCU read-side critical
- sections.
-
- Why the apparent inconsistency? Because it is it
- possible to use priority boosting to keep the RCU
- grace periods short if need be (for example, if running
- short of memory). In contrast, if blocking waiting
- for (say) network reception, there is no way to know
- what should be boosted. Especially given that the
- process we need to boost might well be a human being
- who just went out for a pizza or something. And although
- a computer-operated cattle prod might arouse serious
- interest, it might also provoke serious objections.
- Besides, how does the computer know what pizza parlor
- the human being went to???
-
-
-ACKNOWLEDGEMENTS
-
-My thanks to the people who helped make this human-readable, including
-Jon Walpole, Josh Triplett, Serge Hallyn, Suzanne Wood, and Alan Stern.
-
-
-For more information, see http://www.rdrop.com/users/paulmck/RCU.
diff --git a/Documentation/SAK.txt b/Documentation/SAK.txt
deleted file mode 100644
index 74be14679ed8..000000000000
--- a/Documentation/SAK.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-Linux 2.4.2 Secure Attention Key (SAK) handling
-18 March 2001, Andrew Morton
-
-An operating system's Secure Attention Key is a security tool which is
-provided as protection against trojan password capturing programs. It
-is an undefeatable way of killing all programs which could be
-masquerading as login applications. Users need to be taught to enter
-this key sequence before they log in to the system.
-
-From the PC keyboard, Linux has two similar but different ways of
-providing SAK. One is the ALT-SYSRQ-K sequence. You shouldn't use
-this sequence. It is only available if the kernel was compiled with
-sysrq support.
-
-The proper way of generating a SAK is to define the key sequence using
-`loadkeys'. This will work whether or not sysrq support is compiled
-into the kernel.
-
-SAK works correctly when the keyboard is in raw mode. This means that
-once defined, SAK will kill a running X server. If the system is in
-run level 5, the X server will restart. This is what you want to
-happen.
-
-What key sequence should you use? Well, CTRL-ALT-DEL is used to reboot
-the machine. CTRL-ALT-BACKSPACE is magical to the X server. We'll
-choose CTRL-ALT-PAUSE.
-
-In your rc.sysinit (or rc.local) file, add the command
-
- echo "control alt keycode 101 = SAK" | /bin/loadkeys
-
-And that's it! Only the superuser may reprogram the SAK key.
-
-
-NOTES
-=====
-
-1: Linux SAK is said to be not a "true SAK" as is required by
- systems which implement C2 level security. This author does not
- know why.
-
-
-2: On the PC keyboard, SAK kills all applications which have
- /dev/console opened.
-
- Unfortunately this includes a number of things which you don't
- actually want killed. This is because these applications are
- incorrectly holding /dev/console open. Be sure to complain to your
- Linux distributor about this!
-
- You can identify processes which will be killed by SAK with the
- command
-
- # ls -l /proc/[0-9]*/fd/* | grep console
- l-wx------ 1 root root 64 Mar 18 00:46 /proc/579/fd/0 -> /dev/console
-
- Then:
-
- # ps aux|grep 579
- root 579 0.0 0.1 1088 436 ? S 00:43 0:00 gpm -t ps/2
-
- So `gpm' will be killed by SAK. This is a bug in gpm. It should
- be closing standard input. You can work around this by finding the
- initscript which launches gpm and changing it thusly:
-
- Old:
-
- daemon gpm
-
- New:
-
- daemon gpm < /dev/null
-
- Vixie cron also seems to have this problem, and needs the same treatment.
-
- Also, one prominent Linux distribution has the following three
- lines in its rc.sysinit and rc scripts:
-
- exec 3<&0
- exec 4>&1
- exec 5>&2
-
- These commands cause *all* daemons which are launched by the
- initscripts to have file descriptors 3, 4 and 5 attached to
- /dev/console. So SAK kills them all. A workaround is to simply
- delete these lines, but this may cause system management
- applications to malfunction - test everything well.
-
diff --git a/Documentation/SM501.txt b/Documentation/SM501.txt
deleted file mode 100644
index 561826f82093..000000000000
--- a/Documentation/SM501.txt
+++ /dev/null
@@ -1,71 +0,0 @@
- SM501 Driver
- ============
-
-Copyright 2006, 2007 Simtec Electronics
-
-The Silicon Motion SM501 multimedia companion chip is a multifunction device
-which may provide numerous interfaces including USB host controller USB gadget,
-asynchronous serial ports, audio functions, and a dual display video interface.
-The device may be connected by PCI or local bus with varying functions enabled.
-
-Core
-----
-
-The core driver in drivers/mfd provides common services for the
-drivers which manage the specific hardware blocks. These services
-include locking for common registers, clock control and resource
-management.
-
-The core registers drivers for both PCI and generic bus based
-chips via the platform device and driver system.
-
-On detection of a device, the core initialises the chip (which may
-be specified by the platform data) and then exports the selected
-peripheral set as platform devices for the specific drivers.
-
-The core re-uses the platform device system as the platform device
-system provides enough features to support the drivers without the
-need to create a new bus-type and the associated code to go with it.
-
-
-Resources
----------
-
-Each peripheral has a view of the device which is implicitly narrowed to
-the specific set of resources that peripheral requires in order to
-function correctly.
-
-The centralised memory allocation allows the driver to ensure that the
-maximum possible resource allocation can be made to the video subsystem
-as this is by-far the most resource-sensitive of the on-chip functions.
-
-The primary issue with memory allocation is that of moving the video
-buffers once a display mode is chosen. Indeed when a video mode change
-occurs the memory footprint of the video subsystem changes.
-
-Since video memory is difficult to move without changing the display
-(unless sufficient contiguous memory can be provided for the old and new
-modes simultaneously) the video driver fully utilises the memory area
-given to it by aligning fb0 to the start of the area and fb1 to the end
-of it. Any memory left over in the middle is used for the acceleration
-functions, which are transient and thus their location is less critical
-as it can be moved.
-
-
-Configuration
--------------
-
-The platform device driver uses a set of platform data to pass
-configurations through to the core and the subsidiary drivers
-so that there can be support for more than one system carrying
-an SM501 built into a single kernel image.
-
-The PCI driver assumes that the PCI card behaves as per the Silicon
-Motion reference design.
-
-There is an errata (AB-5) affecting the selection of the
-of the M1XCLK and M1CLK frequencies. These two clocks
-must be sourced from the same PLL, although they can then
-be divided down individually. If this is not set, then SM501 may
-lock and hang the whole system. The driver will refuse to
-attach if the PLL selection is different.
diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs
deleted file mode 100644
index a660d494c8ed..000000000000
--- a/Documentation/SecurityBugs
+++ /dev/null
@@ -1,38 +0,0 @@
-Linux kernel developers take security very seriously. As such, we'd
-like to know when a security bug is found so that it can be fixed and
-disclosed as quickly as possible. Please report security bugs to the
-Linux kernel security team.
-
-1) Contact
-
-The Linux kernel security team can be contacted by email at
-<security@kernel.org>. This is a private list of security officers
-who will help verify the bug report and develop and release a fix.
-It is possible that the security team will bring in extra help from
-area maintainers to understand and fix the security vulnerability.
-
-As it is with any bug, the more information provided the easier it
-will be to diagnose and fix. Please review the procedure outlined in
-REPORTING-BUGS if you are unclear about what information is helpful.
-Any exploit code is very helpful and will not be released without
-consent from the reporter unless it has already been made public.
-
-2) Disclosure
-
-The goal of the Linux kernel security team is to work with the
-bug submitter to bug resolution as well as disclosure. We prefer
-to fully disclose the bug as soon as possible. It is reasonable to
-delay disclosure when the bug or the fix is not yet fully understood,
-the solution is not well-tested or for vendor coordination. However, we
-expect these delays to be short, measurable in days, not weeks or months.
-A disclosure date is negotiated by the security team working with the
-bug submitter as well as vendors. However, the kernel security team
-holds the final say when setting a disclosure date. The timeframe for
-disclosure is from immediate (esp. if it's already publicly known)
-to a few weeks. As a basic default policy, we expect report date to
-disclosure date to be on the order of 7 days.
-
-3) Non-disclosure agreements
-
-The Linux kernel security team is not a formal body and therefore unable
-to enter any non-disclosure agreements.
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
deleted file mode 100644
index 2b7e32dfe00d..000000000000
--- a/Documentation/SubmitChecklist
+++ /dev/null
@@ -1,109 +0,0 @@
-Linux Kernel patch submission checklist
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Here are some basic things that developers should do if they want to see their
-kernel patch submissions accepted more quickly.
-
-These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches and elsewhere regarding submitting Linux
-kernel patches.
-
-
-1: If you use a facility then #include the file that defines/declares
- that facility. Don't depend on other header files pulling in ones
- that you use.
-
-2: Builds cleanly with applicable or modified CONFIG options =y, =m, and
- =n. No gcc warnings/errors, no linker warnings/errors.
-
-2b: Passes allnoconfig, allmodconfig
-
-2c: Builds successfully when using O=builddir
-
-3: Builds on multiple CPU architectures by using local cross-compile tools
- or some other build farm.
-
-4: ppc64 is a good architecture for cross-compilation checking because it
- tends to use `unsigned long' for 64-bit quantities.
-
-5: Check your patch for general style as detailed in
- Documentation/CodingStyle. Check for trivial violations with the
- patch style checker prior to submission (scripts/checkpatch.pl).
- You should be able to justify all violations that remain in
- your patch.
-
-6: Any new or modified CONFIG options don't muck up the config menu.
-
-7: All new Kconfig options have help text.
-
-8: Has been carefully reviewed with respect to relevant Kconfig
- combinations. This is very hard to get right with testing -- brainpower
- pays off here.
-
-9: Check cleanly with sparse.
-
-10: Use 'make checkstack' and 'make namespacecheck' and fix any problems
- that they find. Note: checkstack does not point out problems explicitly,
- but any one function that uses more than 512 bytes on the stack is a
- candidate for change.
-
-11: Include kernel-doc to document global kernel APIs. (Not required for
- static functions, but OK there also.) Use 'make htmldocs' or 'make
- mandocs' to check the kernel-doc and fix any issues.
-
-12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT,
- CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES,
- CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP, CONFIG_PROVE_RCU
- and CONFIG_DEBUG_OBJECTS_RCU_HEAD all simultaneously enabled.
-
-13: Has been build- and runtime tested with and without CONFIG_SMP and
- CONFIG_PREEMPT.
-
-14: If the patch affects IO/Disk, etc: has been tested with and without
- CONFIG_LBDAF.
-
-15: All codepaths have been exercised with all lockdep features enabled.
-
-16: All new /proc entries are documented under Documentation/
-
-17: All new kernel boot parameters are documented in
- Documentation/kernel-parameters.txt.
-
-18: All new module parameters are documented with MODULE_PARM_DESC()
-
-19: All new userspace interfaces are documented in Documentation/ABI/.
- See Documentation/ABI/README for more information.
- Patches that change userspace interfaces should be CCed to
- linux-api@vger.kernel.org.
-
-20: Check that it all passes `make headers_check'.
-
-21: Has been checked with injection of at least slab and page-allocation
- failures. See Documentation/fault-injection/.
-
- If the new code is substantial, addition of subsystem-specific fault
- injection might be appropriate.
-
-22: Newly-added code has been compiled with `gcc -W' (use "make
- EXTRA_CFLAGS=-W"). This will generate lots of noise, but is good for
- finding bugs like "warning: comparison between signed and unsigned".
-
-23: Tested after it has been merged into the -mm patchset to make sure
- that it still works with all of the other queued patches and various
- changes in the VM, VFS, and other subsystems.
-
-24: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the
- source code that explains the logic of what they are doing and why.
-
-25: If any ioctl's are added by the patch, then also update
- Documentation/ioctl/ioctl-number.txt.
-
-26: If your modified source code depends on or uses any of the kernel
- APIs or features that are related to the following kconfig symbols,
- then test multiple builds with the related kconfig symbols disabled
- and/or =m (if that option is available) [not all of these at the
- same time, just various/random combinations of them]:
-
- CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI,
- CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ,
- CONFIG_NET, CONFIG_INET=n (but latter with CONFIG_NET=y)
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
deleted file mode 100644
index 31d372609ac0..000000000000
--- a/Documentation/SubmittingDrivers
+++ /dev/null
@@ -1,163 +0,0 @@
-Submitting Drivers For The Linux Kernel
----------------------------------------
-
-This document is intended to explain how to submit device drivers to the
-various kernel trees. Note that if you are interested in video card drivers
-you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
-(http://x.org/) instead.
-
-Also read the Documentation/SubmittingPatches document.
-
-
-Allocating Device Numbers
--------------------------
-
-Major and minor numbers for block and character devices are allocated
-by the Linux assigned name and number authority (currently this is
-Torben Mathiasen). The site is http://www.lanana.org/. This
-also deals with allocating numbers for devices that are not going to
-be submitted to the mainstream kernel.
-See Documentation/devices.txt for more information on this.
-
-If you don't use assigned numbers then when your device is submitted it will
-be given an assigned number even if that is different from values you may
-have shipped to customers before.
-
-Who To Submit Drivers To
-------------------------
-
-Linux 2.0:
- No new drivers are accepted for this kernel tree.
-
-Linux 2.2:
- No new drivers are accepted for this kernel tree.
-
-Linux 2.4:
- If the code area has a general maintainer then please submit it to
- the maintainer listed in MAINTAINERS in the kernel file. If the
- maintainer does not respond or you cannot find the appropriate
- maintainer then please contact Willy Tarreau <w@1wt.eu>.
-
-Linux 2.6:
- The same rules apply as 2.4 except that you should follow linux-kernel
- to track changes in API's. The final contact point for Linux 2.6
- submissions is Andrew Morton.
-
-What Criteria Determine Acceptance
-----------------------------------
-
-Licensing: The code must be released to us under the
- GNU General Public License. We don't insist on any kind
- of exclusive GPL licensing, and if you wish the driver
- to be useful to other communities such as BSD you may well
- wish to release under multiple licenses.
- See accepted licenses at include/linux/module.h
-
-Copyright: The copyright owner must agree to use of GPL.
- It's best if the submitter and copyright owner
- are the same person/entity. If not, the name of
- the person/entity authorizing use of GPL should be
- listed in case it's necessary to verify the will of
- the copyright owner.
-
-Interfaces: If your driver uses existing interfaces and behaves like
- other drivers in the same class it will be much more likely
- to be accepted than if it invents gratuitous new ones.
- If you need to implement a common API over Linux and NT
- drivers do it in userspace.
-
-Code: Please use the Linux style of code formatting as documented
- in Documentation/CodingStyle. If you have sections of code
- that need to be in other formats, for example because they
- are shared with a windows driver kit and you want to
- maintain them just once separate them out nicely and note
- this fact.
-
-Portability: Pointers are not always 32bits, not all computers are little
- endian, people do not all have floating point and you
- shouldn't use inline x86 assembler in your driver without
- careful thought. Pure x86 drivers generally are not popular.
- If you only have x86 hardware it is hard to test portability
- but it is easy to make sure the code can easily be made
- portable.
-
-Clarity: It helps if anyone can see how to fix the driver. It helps
- you because you get patches not bug reports. If you submit a
- driver that intentionally obfuscates how the hardware works
- it will go in the bitbucket.
-
-PM support: Since Linux is used on many portable and desktop systems, your
- driver is likely to be used on such a system and therefore it
- should support basic power management by implementing, if
- necessary, the .suspend and .resume methods used during the
- system-wide suspend and resume transitions. You should verify
- that your driver correctly handles the suspend and resume, but
- if you are unable to ensure that, please at least define the
- .suspend method returning the -ENOSYS ("Function not
- implemented") error. You should also try to make sure that your
- driver uses as little power as possible when it's not doing
- anything. For the driver testing instructions see
- Documentation/power/drivers-testing.txt and for a relatively
- complete overview of the power management issues related to
- drivers see Documentation/power/devices.txt .
-
-Control: In general if there is active maintenance of a driver by
- the author then patches will be redirected to them unless
- they are totally obvious and without need of checking.
- If you want to be the contact and update point for the
- driver it is a good idea to state this in the comments,
- and include an entry in MAINTAINERS for your driver.
-
-What Criteria Do Not Determine Acceptance
------------------------------------------
-
-Vendor: Being the hardware vendor and maintaining the driver is
- often a good thing. If there is a stable working driver from
- other people already in the tree don't expect 'we are the
- vendor' to get your driver chosen. Ideally work with the
- existing driver author to build a single perfect driver.
-
-Author: It doesn't matter if a large Linux company wrote the driver,
- or you did. Nobody has any special access to the kernel
- tree. Anyone who tells you otherwise isn't telling the
- whole story.
-
-
-Resources
----------
-
-Linux kernel master tree:
- ftp.??.kernel.org:/pub/linux/kernel/...
- ?? == your country code, such as "us", "uk", "fr", etc.
-
- http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
-
-Linux kernel mailing list:
- linux-kernel@vger.kernel.org
- [mail majordomo@vger.kernel.org to subscribe]
-
-Linux Device Drivers, Third Edition (covers 2.6.10):
- http://lwn.net/Kernel/LDD3/ (free version)
-
-LWN.net:
- Weekly summary of kernel development activity - http://lwn.net/
- 2.6 API changes:
- http://lwn.net/Articles/2.6-kernel-api/
- Porting drivers from prior kernels to 2.6:
- http://lwn.net/Articles/driver-porting/
-
-KernelNewbies:
- Documentation and assistance for new kernel programmers
- http://kernelnewbies.org/
-
-Linux USB project:
- http://www.linux-usb.org/
-
-How to NOT write kernel driver by Arjan van de Ven:
- http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
-
-Kernel Janitor:
- http://kernelnewbies.org/KernelJanitors
-
-GIT, Fast Version Control System:
- http://git-scm.com/
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index b03a832a08e2..81455705e4a6 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -1,806 +1 @@
-
- How to Get Your Change Into the Linux Kernel
- or
- Care And Operation Of Your Linus Torvalds
-
-
-
-For a person or company who wishes to submit a change to the Linux
-kernel, the process can sometimes be daunting if you're not familiar
-with "the system." This text is a collection of suggestions which
-can greatly increase the chances of your change being accepted.
-
-This document contains a large number of suggestions in a relatively terse
-format. For detailed information on how the kernel development process
-works, see Documentation/development-process. Also, read
-Documentation/SubmitChecklist for a list of items to check before
-submitting code. If you are submitting a driver, also read
-Documentation/SubmittingDrivers; for device tree binding patches, read
-Documentation/devicetree/bindings/submitting-patches.txt.
-
-Many of these steps describe the default behavior of the git version
-control system; if you use git to prepare your patches, you'll find much
-of the mechanical work done for you, though you'll still need to prepare
-and document a sensible set of patches. In general, use of git will make
-your life as a kernel developer easier.
-
---------------------------------------------
-SECTION 1 - CREATING AND SENDING YOUR CHANGE
---------------------------------------------
-
-
-0) Obtain a current source tree
--------------------------------
-
-If you do not have a repository with the current kernel source handy, use
-git to obtain one. You'll want to start with the mainline repository,
-which can be grabbed with:
-
- git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-
-Note, however, that you may not want to develop against the mainline tree
-directly. Most subsystem maintainers run their own trees and want to see
-patches prepared against those trees. See the "T:" entry for the subsystem
-in the MAINTAINERS file to find that tree, or simply ask the maintainer if
-the tree is not listed there.
-
-It is still possible to download kernel releases via tarballs (as described
-in the next section), but that is the hard way to do kernel development.
-
-1) "diff -up"
-------------
-
-If you must generate your patches by hand, use "diff -up" or "diff -uprN"
-to create patches. Git generates patches in this form by default; if
-you're using git, you can skip this section entirely.
-
-All changes to the Linux kernel occur in the form of patches, as
-generated by diff(1). When creating your patch, make sure to create it
-in "unified diff" format, as supplied by the '-u' argument to diff(1).
-Also, please use the '-p' argument which shows which C function each
-change is in - that makes the resultant diff a lot easier to read.
-Patches should be based in the root kernel source directory,
-not in any lower subdirectory.
-
-To create a patch for a single file, it is often sufficient to do:
-
- SRCTREE= linux
- MYFILE= drivers/net/mydriver.c
-
- cd $SRCTREE
- cp $MYFILE $MYFILE.orig
- vi $MYFILE # make your change
- cd ..
- diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-To create a patch for multiple files, you should unpack a "vanilla",
-or unmodified kernel source tree, and generate a diff against your
-own source tree. For example:
-
- MYSRC= /devel/linux
-
- tar xvfz linux-3.19.tar.gz
- mv linux-3.19 linux-3.19-vanilla
- diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
- linux-3.19-vanilla $MYSRC > /tmp/patch
-
-"dontdiff" is a list of files which are generated by the kernel during
-the build process, and should be ignored in any diff(1)-generated
-patch.
-
-Make sure your patch does not include any extra files which do not
-belong in a patch submission. Make sure to review your patch -after-
-generated it with diff(1), to ensure accuracy.
-
-If your changes produce a lot of deltas, you need to split them into
-individual patches which modify things in logical stages; see section
-#3. This will facilitate easier reviewing by other kernel developers,
-very important if you want your patch accepted.
-
-If you're using git, "git rebase -i" can help you with this process. If
-you're not using git, quilt <http://savannah.nongnu.org/projects/quilt>
-is another popular alternative.
-
-
-
-2) Describe your changes.
--------------------------
-
-Describe your problem. Whether your patch is a one-line bug fix or
-5000 lines of a new feature, there must be an underlying problem that
-motivated you to do this work. Convince the reviewer that there is a
-problem worth fixing and that it makes sense for them to read past the
-first paragraph.
-
-Describe user-visible impact. Straight up crashes and lockups are
-pretty convincing, but not all bugs are that blatant. Even if the
-problem was spotted during code review, describe the impact you think
-it can have on users. Keep in mind that the majority of Linux
-installations run kernels from secondary stable trees or
-vendor/product-specific trees that cherry-pick only specific patches
-from upstream, so include anything that could help route your change
-downstream: provoking circumstances, excerpts from dmesg, crash
-descriptions, performance regressions, latency spikes, lockups, etc.
-
-Quantify optimizations and trade-offs. If you claim improvements in
-performance, memory consumption, stack footprint, or binary size,
-include numbers that back them up. But also describe non-obvious
-costs. Optimizations usually aren't free but trade-offs between CPU,
-memory, and readability; or, when it comes to heuristics, between
-different workloads. Describe the expected downsides of your
-optimization so that the reviewer can weigh costs against benefits.
-
-Once the problem is established, describe what you are actually doing
-about it in technical detail. It's important to describe the change
-in plain English for the reviewer to verify that the code is behaving
-as you intend it to.
-
-The maintainer will thank you if you write your patch description in a
-form which can be easily pulled into Linux's source code management
-system, git, as a "commit log". See #15, below.
-
-Solve only one problem per patch. If your description starts to get
-long, that's a sign that you probably need to split up your patch.
-See #3, next.
-
-When you submit or resubmit a patch or patch series, include the
-complete patch description and justification for it. Don't just
-say that this is version N of the patch (series). Don't expect the
-subsystem maintainer to refer back to earlier patch versions or referenced
-URLs to find the patch description and put that into the patch.
-I.e., the patch (series) and its description should be self-contained.
-This benefits both the maintainers and reviewers. Some reviewers
-probably didn't even receive earlier versions of the patch.
-
-Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
-instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
-to do frotz", as if you are giving orders to the codebase to change
-its behaviour.
-
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL. If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lkml.kernel.org/
-redirector with a Message-Id, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources. In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
-If you want to refer to a specific commit, don't just refer to the
-SHA-1 ID of the commit. Please also include the oneline summary of
-the commit, to make it easier for reviewers to know what it is about.
-Example:
-
- Commit e21d2170f36602ae2708 ("video: remove unnecessary
- platform_set_drvdata()") removed the unnecessary
- platform_set_drvdata(), but left the variable "dev" unused,
- delete it.
-
-You should also be sure to use at least the first twelve characters of the
-SHA-1 ID. The kernel repository holds a *lot* of objects, making
-collisions with shorter IDs a real possibility. Bear in mind that, even if
-there is no collision with your six-character ID now, that condition may
-change five years from now.
-
-If your patch fixes a bug in a specific commit, e.g. you found an issue using
-git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
-SHA-1 ID, and the one line summary. For example:
-
- Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
-
-The following git-config settings can be used to add a pretty format for
-outputting the above style in the git log or git show commands
-
- [core]
- abbrev = 12
- [pretty]
- fixes = Fixes: %h (\"%s\")
-
-3) Separate your changes.
--------------------------
-
-Separate each _logical change_ into a separate patch.
-
-For example, if your changes include both bug fixes and performance
-enhancements for a single driver, separate those changes into two
-or more patches. If your changes include an API update, and a new
-driver which uses that new API, separate those into two patches.
-
-On the other hand, if you make a single change to numerous files,
-group those changes into a single patch. Thus a single logical change
-is contained within a single patch.
-
-The point to remember is that each patch should make an easily understood
-change that can be verified by reviewers. Each patch should be justifiable
-on its own merits.
-
-If one patch depends on another patch in order for a change to be
-complete, that is OK. Simply note "this patch depends on patch X"
-in your patch description.
-
-When dividing your change into a series of patches, take special care to
-ensure that the kernel builds and runs properly after each patch in the
-series. Developers using "git bisect" to track down a problem can end up
-splitting your patch series at any point; they will not thank you if you
-introduce bugs in the middle.
-
-If you cannot condense your patch set into a smaller set of patches,
-then only post say 15 or so at a time and wait for review and integration.
-
-
-
-4) Style-check your changes.
-----------------------------
-
-Check your patch for basic style violations, details of which can be
-found in Documentation/CodingStyle. Failure to do so simply wastes
-the reviewers time and will get your patch rejected, probably
-without even being read.
-
-One significant exception is when moving code from one file to
-another -- in this case you should not modify the moved code at all in
-the same patch which moves it. This clearly delineates the act of
-moving the code and your changes. This greatly aids review of the
-actual differences and allows tools to better track the history of
-the code itself.
-
-Check your patches with the patch style checker prior to submission
-(scripts/checkpatch.pl). Note, though, that the style checker should be
-viewed as a guide, not as a replacement for human judgment. If your code
-looks better with a violation then its probably best left alone.
-
-The checker reports at three levels:
- - ERROR: things that are very likely to be wrong
- - WARNING: things requiring careful review
- - CHECK: things requiring thought
-
-You should be able to justify all violations that remain in your
-patch.
-
-
-5) Select the recipients for your patch.
-----------------------------------------
-
-You should always copy the appropriate subsystem maintainer(s) on any patch
-to code that they maintain; look through the MAINTAINERS file and the
-source code revision history to see who those maintainers are. The
-script scripts/get_maintainer.pl can be very useful at this step. If you
-cannot find a maintainer for the subsystem your are working on, Andrew
-Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
-
-You should also normally choose at least one mailing list to receive a copy
-of your patch set. linux-kernel@vger.kernel.org functions as a list of
-last resort, but the volume on that list has caused a number of developers
-to tune it out. Look in the MAINTAINERS file for a subsystem-specific
-list; your patch will probably get more attention there. Please do not
-spam unrelated lists, though.
-
-Many kernel-related lists are hosted on vger.kernel.org; you can find a
-list of them at http://vger.kernel.org/vger-lists.html. There are
-kernel-related lists hosted elsewhere as well, though.
-
-Do not send more than 15 patches at once to the vger mailing lists!!!
-
-Linus Torvalds is the final arbiter of all changes accepted into the
-Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
-He gets a lot of e-mail, and, at this point, very few patches go through
-Linus directly, so typically you should do your best to -avoid-
-sending him e-mail.
-
-If you have a patch that fixes an exploitable security bug, send that patch
-to security@kernel.org. For severe bugs, a short embargo may be considered
-to allow distrbutors to get the patch out to users; in such cases,
-obviously, the patch should not be sent to any public lists.
-
-Patches that fix a severe bug in a released kernel should be directed
-toward the stable maintainers by putting a line like this:
-
- Cc: stable@vger.kernel.org
-
-into your patch.
-
-Note, however, that some subsystem maintainers want to come to their own
-conclusions on which patches should go to the stable trees. The networking
-maintainer, in particular, would rather not see individual developers
-adding lines like the above to their patches.
-
-If changes affect userland-kernel interfaces, please send the MAN-PAGES
-maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
-least a notification of the change, so that some information makes its way
-into the manual pages. User-space API changes should also be copied to
-linux-api@vger.kernel.org.
-
-For small patches you may want to CC the Trivial Patch Monkey
-trivial@kernel.org which collects "trivial" patches. Have a look
-into the MAINTAINERS file for its current manager.
-Trivial patches must qualify for one of the following rules:
- Spelling fixes in documentation
- Spelling fixes for errors which could break grep(1)
- Warning fixes (cluttering with useless warnings is bad)
- Compilation fixes (only if they are actually correct)
- Runtime fixes (only if they actually fix things)
- Removing use of deprecated functions/macros
- Contact detail and documentation fixes
- Non-portable code replaced by portable code (even in arch-specific,
- since people copy, as long as it's trivial)
- Any fix by the author/maintainer of the file (ie. patch monkey
- in re-transmission mode)
-
-
-
-6) No MIME, no links, no compression, no attachments. Just plain text.
------------------------------------------------------------------------
-
-Linus and other kernel developers need to be able to read and comment
-on the changes you are submitting. It is important for a kernel
-developer to be able to "quote" your changes, using standard e-mail
-tools, so that they may comment on specific portions of your code.
-
-For this reason, all patches should be submitting e-mail "inline".
-WARNING: Be wary of your editor's word-wrap corrupting your patch,
-if you choose to cut-n-paste your patch.
-
-Do not attach the patch as a MIME attachment, compressed or not.
-Many popular e-mail applications will not always transmit a MIME
-attachment as plain text, making it impossible to comment on your
-code. A MIME attachment also takes Linus a bit more time to process,
-decreasing the likelihood of your MIME-attached change being accepted.
-
-Exception: If your mailer is mangling patches then someone may ask
-you to re-send them using MIME.
-
-See Documentation/email-clients.txt for hints about configuring
-your e-mail client so that it sends your patches untouched.
-
-7) E-mail size.
----------------
-
-Large changes are not appropriate for mailing lists, and some
-maintainers. If your patch, uncompressed, exceeds 300 kB in size,
-it is preferred that you store your patch on an Internet-accessible
-server, and provide instead a URL (link) pointing to your patch. But note
-that if your patch exceeds 300 kB, it almost certainly needs to be broken up
-anyway.
-
-8) Respond to review comments.
-------------------------------
-
-Your patch will almost certainly get comments from reviewers on ways in
-which the patch can be improved. You must respond to those comments;
-ignoring reviewers is a good way to get ignored in return. Review comments
-or questions that do not lead to a code change should almost certainly
-bring about a comment or changelog entry so that the next reviewer better
-understands what is going on.
-
-Be sure to tell the reviewers what changes you are making and to thank them
-for their time. Code review is a tiring and time-consuming process, and
-reviewers sometimes get grumpy. Even in that case, though, respond
-politely and address the problems they have pointed out.
-
-
-9) Don't get discouraged - or impatient.
-----------------------------------------
-
-After you have submitted your change, be patient and wait. Reviewers are
-busy people and may not get to your patch right away.
-
-Once upon a time, patches used to disappear into the void without comment,
-but the development process works more smoothly than that now. You should
-receive comments within a week or so; if that does not happen, make sure
-that you have sent your patches to the right place. Wait for a minimum of
-one week before resubmitting or pinging reviewers - possibly longer during
-busy times like merge windows.
-
-
-10) Include PATCH in the subject
---------------------------------
-
-Due to high e-mail traffic to Linus, and to linux-kernel, it is common
-convention to prefix your subject line with [PATCH]. This lets Linus
-and other kernel developers more easily distinguish patches from other
-e-mail discussions.
-
-
-
-11) Sign your work
-------------------
-
-To improve tracking of who did what, especially with patches that can
-percolate to their final resting place in the kernel through several
-layers of maintainers, we've introduced a "sign-off" procedure on
-patches that are being emailed around.
-
-The sign-off is a simple line at the end of the explanation for the
-patch, which certifies that you wrote it or otherwise have the right to
-pass it on as an open-source patch. The rules are pretty simple: if you
-can certify the below:
-
- Developer's Certificate of Origin 1.1
-
- By making a contribution to this project, I certify that:
-
- (a) The contribution was created in whole or in part by me and I
- have the right to submit it under the open source license
- indicated in the file; or
-
- (b) The contribution is based upon previous work that, to the best
- of my knowledge, is covered under an appropriate open source
- license and I have the right under that license to submit that
- work with modifications, whether created in whole or in part
- by me, under the same open source license (unless I am
- permitted to submit under a different license), as indicated
- in the file; or
-
- (c) The contribution was provided directly to me by some other
- person who certified (a), (b) or (c) and I have not modified
- it.
-
- (d) I understand and agree that this project and the contribution
- are public and that a record of the contribution (including all
- personal information I submit with it, including my sign-off) is
- maintained indefinitely and may be redistributed consistent with
- this project or the open source license(s) involved.
-
-then you just add a line saying
-
- Signed-off-by: Random J Developer <random@developer.example.org>
-
-using your real name (sorry, no pseudonyms or anonymous contributions.)
-
-Some people also put extra tags at the end. They'll just be ignored for
-now, but you can do this to mark internal company procedures or just
-point out some special detail about the sign-off.
-
-If you are a subsystem or branch maintainer, sometimes you need to slightly
-modify patches you receive in order to merge them, because the code is not
-exactly the same in your tree and the submitters'. If you stick strictly to
-rule (c), you should ask the submitter to rediff, but this is a totally
-counter-productive waste of time and energy. Rule (b) allows you to adjust
-the code, but then it is very impolite to change one submitter's code and
-make him endorse your bugs. To solve this problem, it is recommended that
-you add a line between the last Signed-off-by header and yours, indicating
-the nature of your changes. While there is nothing mandatory about this, it
-seems like prepending the description with your mail and/or name, all
-enclosed in square brackets, is noticeable enough to make it obvious that
-you are responsible for last-minute changes. Example :
-
- Signed-off-by: Random J Developer <random@developer.example.org>
- [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
- Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
-
-This practice is particularly helpful if you maintain a stable branch and
-want at the same time to credit the author, track changes, merge the fix,
-and protect the submitter from complaints. Note that under no circumstances
-can you change the author's identity (the From header), as it is the one
-which appears in the changelog.
-
-Special note to back-porters: It seems to be a common and useful practice
-to insert an indication of the origin of a patch at the top of the commit
-message (just after the subject line) to facilitate tracking. For instance,
-here's what we see in a 3.x-stable release:
-
-Date: Tue Oct 7 07:26:38 2014 -0400
-
- libata: Un-break ATA blacklist
-
- commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
-
-And here's what might appear in an older kernel once a patch is backported:
-
- Date: Tue May 13 22:12:27 2008 +0200
-
- wireless, airo: waitbusy() won't delay
-
- [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
-
-Whatever the format, this information provides a valuable help to people
-tracking your trees, and to people trying to troubleshoot bugs in your
-tree.
-
-
-12) When to use Acked-by: and Cc:
----------------------------------
-
-The Signed-off-by: tag indicates that the signer was involved in the
-development of the patch, or that he/she was in the patch's delivery path.
-
-If a person was not directly involved in the preparation or handling of a
-patch but wishes to signify and record their approval of it then they can
-ask to have an Acked-by: line added to the patch's changelog.
-
-Acked-by: is often used by the maintainer of the affected code when that
-maintainer neither contributed to nor forwarded the patch.
-
-Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
-has at least reviewed the patch and has indicated acceptance. Hence patch
-mergers will sometimes manually convert an acker's "yep, looks good to me"
-into an Acked-by: (but note that it is usually better to ask for an
-explicit ack).
-
-Acked-by: does not necessarily indicate acknowledgement of the entire patch.
-For example, if a patch affects multiple subsystems and has an Acked-by: from
-one subsystem maintainer then this usually indicates acknowledgement of just
-the part which affects that maintainer's code. Judgement should be used here.
-When in doubt people should refer to the original discussion in the mailing
-list archives.
-
-If a person has had the opportunity to comment on a patch, but has not
-provided such comments, you may optionally add a "Cc:" tag to the patch.
-This is the only tag which might be added without an explicit action by the
-person it names - but it should indicate that this person was copied on the
-patch. This tag documents that potentially interested parties
-have been included in the discussion.
-
-
-13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
---------------------------------------------------------------------------
-
-The Reported-by tag gives credit to people who find bugs and report them and it
-hopefully inspires them to help us again in the future. Please note that if
-the bug was reported in private, then ask for permission first before using the
-Reported-by tag.
-
-A Tested-by: tag indicates that the patch has been successfully tested (in
-some environment) by the person named. This tag informs maintainers that
-some testing has been performed, provides a means to locate testers for
-future patches, and ensures credit for the testers.
-
-Reviewed-by:, instead, indicates that the patch has been reviewed and found
-acceptable according to the Reviewer's Statement:
-
- Reviewer's statement of oversight
-
- By offering my Reviewed-by: tag, I state that:
-
- (a) I have carried out a technical review of this patch to
- evaluate its appropriateness and readiness for inclusion into
- the mainline kernel.
-
- (b) Any problems, concerns, or questions relating to the patch
- have been communicated back to the submitter. I am satisfied
- with the submitter's response to my comments.
-
- (c) While there may be things that could be improved with this
- submission, I believe that it is, at this time, (1) a
- worthwhile modification to the kernel, and (2) free of known
- issues which would argue against its inclusion.
-
- (d) While I have reviewed the patch and believe it to be sound, I
- do not (unless explicitly stated elsewhere) make any
- warranties or guarantees that it will achieve its stated
- purpose or function properly in any given situation.
-
-A Reviewed-by tag is a statement of opinion that the patch is an
-appropriate modification of the kernel without any remaining serious
-technical issues. Any interested reviewer (who has done the work) can
-offer a Reviewed-by tag for a patch. This tag serves to give credit to
-reviewers and to inform maintainers of the degree of review which has been
-done on the patch. Reviewed-by: tags, when supplied by reviewers known to
-understand the subject area and to perform thorough reviews, will normally
-increase the likelihood of your patch getting into the kernel.
-
-A Suggested-by: tag indicates that the patch idea is suggested by the person
-named and ensures credit to the person for the idea. Please note that this
-tag should not be added without the reporter's permission, especially if the
-idea was not posted in a public forum. That said, if we diligently credit our
-idea reporters, they will, hopefully, be inspired to help us again in the
-future.
-
-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
-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 #2 above for more details.
-
-
-14) The canonical patch format
-------------------------------
-
-This section describes how the patch itself should be formatted. Note
-that, if you have your patches stored in a git repository, proper patch
-formatting can be had with "git format-patch". The tools cannot create
-the necessary text, though, so read the instructions below anyway.
-
-The canonical patch subject line is:
-
- Subject: [PATCH 001/123] subsystem: summary phrase
-
-The canonical patch message body contains the following:
-
- - A "from" line specifying the patch author (only needed if the person
- sending the patch is not the author).
-
- - An empty line.
-
- - The body of the explanation, line wrapped at 75 columns, which will
- be copied to the permanent changelog to describe this patch.
-
- - The "Signed-off-by:" lines, described above, which will
- also go in the changelog.
-
- - A marker line containing simply "---".
-
- - Any additional comments not suitable for the changelog.
-
- - The actual patch (diff output).
-
-The Subject line format makes it very easy to sort the emails
-alphabetically by subject line - pretty much any email reader will
-support that - since because the sequence number is zero-padded,
-the numerical and alphabetic sort is the same.
-
-The "subsystem" in the email's Subject should identify which
-area or subsystem of the kernel is being patched.
-
-The "summary phrase" in the email's Subject should concisely
-describe the patch which that email contains. The "summary
-phrase" should not be a filename. Do not use the same "summary
-phrase" for every patch in a whole patch series (where a "patch
-series" is an ordered sequence of multiple, related patches).
-
-Bear in mind that the "summary phrase" of your email becomes a
-globally-unique identifier for that patch. It propagates all the way
-into the git changelog. The "summary phrase" may later be used in
-developer discussions which refer to the patch. People will want to
-google for the "summary phrase" to read discussion regarding that
-patch. It will also be the only thing that people may quickly see
-when, two or three months later, they are going through perhaps
-thousands of patches using tools such as "gitk" or "git log
---oneline".
-
-For these reasons, the "summary" must be no more than 70-75
-characters, and it must describe both what the patch changes, as well
-as why the patch might be necessary. It is challenging to be both
-succinct and descriptive, but that is what a well-written summary
-should do.
-
-The "summary phrase" may be prefixed by tags enclosed in square
-brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not
-considered part of the summary phrase, but describe how the patch
-should be treated. Common tags might include a version descriptor if
-the multiple versions of the patch have been sent out in response to
-comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
-comments. If there are four patches in a patch series the individual
-patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures
-that developers understand the order in which the patches should be
-applied and that they have reviewed or applied all of the patches in
-the patch series.
-
-A couple of example Subjects:
-
- Subject: [patch 2/5] ext2: improve scalability of bitmap searching
- Subject: [PATCHv2 001/207] x86: fix eflags tracking
-
-The "from" line must be the very first line in the message body,
-and has the form:
-
- From: Original Author <author@example.com>
-
-The "from" line specifies who will be credited as the author of the
-patch in the permanent changelog. If the "from" line is missing,
-then the "From:" line from the email header will be used to determine
-the patch author in the changelog.
-
-The explanation body will be committed to the permanent source
-changelog, so should make sense to a competent reader who has long
-since forgotten the immediate details of the discussion that might
-have led to this patch. Including symptoms of the failure which the
-patch addresses (kernel log messages, oops messages, etc.) is
-especially useful for people who might be searching the commit logs
-looking for the applicable patch. If a patch fixes a compile failure,
-it may not be necessary to include _all_ of the compile failures; just
-enough that it is likely that someone searching for the patch can find
-it. As in the "summary phrase", it is important to be both succinct as
-well as descriptive.
-
-The "---" marker line serves the essential purpose of marking for patch
-handling tools where the changelog message ends.
-
-One good use for the additional comments after the "---" marker is for
-a diffstat, to show what files have changed, and the number of
-inserted and deleted lines per file. A diffstat is especially useful
-on bigger patches. Other comments relevant only to the moment or the
-maintainer, not suitable for the permanent changelog, should also go
-here. A good example of such comments might be "patch changelogs"
-which describe what has changed between the v1 and v2 version of the
-patch.
-
-If you are going to include a diffstat after the "---" marker, please
-use diffstat options "-p 1 -w 70" so that filenames are listed from
-the top of the kernel source tree and don't use too much horizontal
-space (easily fit in 80 columns, maybe with some indentation). (git
-generates appropriate diffstats by default.)
-
-See more details on the proper patch format in the following
-references.
-
-
-15) Sending "git pull" requests
--------------------------------
-
-If you have a series of patches, it may be most convenient to have the
-maintainer pull them directly into the subsystem repository with a
-"git pull" operation. Note, however, that pulling patches from a developer
-requires a higher degree of trust than taking patches from a mailing list.
-As a result, many subsystem maintainers are reluctant to take pull
-requests, especially from new, unknown developers. If in doubt you can use
-the pull request as the cover letter for a normal posting of the patch
-series, giving the maintainer the option of using either.
-
-A pull request should have [GIT] or [PULL] in the subject line. The
-request itself should include the repository name and the branch of
-interest on a single line; it should look something like:
-
- Please pull from
-
- git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
-
- to get these changes:"
-
-A pull request should also include an overall message saying what will be
-included in the request, a "git shortlog" listing of the patches
-themselves, and a diffstat showing the overall effect of the patch series.
-The easiest way to get all this information together is, of course, to let
-git do it for you with the "git request-pull" command.
-
-Some maintainers (including Linus) want to see pull requests from signed
-commits; that increases their confidence that the request actually came
-from you. Linus, in particular, will not pull from public hosting sites
-like GitHub in the absence of a signed tag.
-
-The first step toward creating such tags is to make a GNUPG key and get it
-signed by one or more core kernel developers. This step can be hard for
-new developers, but there is no way around it. Attending conferences can
-be a good way to find developers who can sign your key.
-
-Once you have prepared a patch series in git that you wish to have somebody
-pull, create a signed tag with "git tag -s". This will create a new tag
-identifying the last commit in the series and containing a signature
-created with your private key. You will also have the opportunity to add a
-changelog-style message to the tag; this is an ideal place to describe the
-effects of the pull request as a whole.
-
-If the tree the maintainer will be pulling from is not the repository you
-are working from, don't forget to push the signed tag explicitly to the
-public tree.
-
-When generating your pull request, use the signed tag as the target. A
-command like this will do the trick:
-
- git request-pull master git://my.public.tree/linux.git my-signed-tag
-
-
-----------------------
-SECTION 2 - REFERENCES
-----------------------
-
-Andrew Morton, "The perfect patch" (tpp).
- <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
-
-Jeff Garzik, "Linux kernel patch submission format".
- <http://linux.yyz.us/patch-format.html>
-
-Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
- <http://www.kroah.com/log/linux/maintainer.html>
- <http://www.kroah.com/log/linux/maintainer-02.html>
- <http://www.kroah.com/log/linux/maintainer-03.html>
- <http://www.kroah.com/log/linux/maintainer-04.html>
- <http://www.kroah.com/log/linux/maintainer-05.html>
- <http://www.kroah.com/log/linux/maintainer-06.html>
-
-NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
- <https://lkml.org/lkml/2005/7/11/336>
-
-Kernel Documentation/CodingStyle:
- <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>
-
-Linus Torvalds's mail on the canonical patch format:
- <http://lkml.org/lkml/2005/4/7/183>
-
-Andi Kleen, "On submitting kernel patches"
- Some strategies to get difficult or controversial changes in.
- http://halobates.de/on-submitting-patches.pdf
-
---
+This file has moved to process/submitting-patches.rst
diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt
deleted file mode 100644
index 70acfbf399eb..000000000000
--- a/Documentation/VGA-softcursor.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Software cursor for VGA by Pavel Machek <pavel@atrey.karlin.mff.cuni.cz>
-======================= and Martin Mares <mj@atrey.karlin.mff.cuni.cz>
-
- Linux now has some ability to manipulate cursor appearance. Normally, you
-can set the size of hardware cursor (and also work around some ugly bugs in
-those miserable Trident cards--see #define TRIDENT_GLITCH in drivers/video/
-vgacon.c). You can now play a few new tricks: you can make your cursor look
-like a non-blinking red block, make it inverse background of the character it's
-over or to highlight that character and still choose whether the original
-hardware cursor should remain visible or not. There may be other things I have
-never thought of.
-
- The cursor appearance is controlled by a "<ESC>[?1;2;3c" escape sequence
-where 1, 2 and 3 are parameters described below. If you omit any of them,
-they will default to zeroes.
-
- Parameter 1 specifies cursor size (0=default, 1=invisible, 2=underline, ...,
-8=full block) + 16 if you want the software cursor to be applied + 32 if you
-want to always change the background color + 64 if you dislike having the
-background the same as the foreground. Highlights are ignored for the last two
-flags.
-
- The second parameter selects character attribute bits you want to change
-(by simply XORing them with the value of this parameter). On standard VGA,
-the high four bits specify background and the low four the foreground. In both
-groups, low three bits set color (as in normal color codes used by the console)
-and the most significant one turns on highlight (or sometimes blinking--it
-depends on the configuration of your VGA).
-
- The third parameter consists of character attribute bits you want to set.
-Bit setting takes place before bit toggling, so you can simply clear a bit by
-including it in both the set mask and the toggle mask.
-
-Examples:
-=========
-
-To get normal blinking underline, use: echo -e '\033[?2c'
-To get blinking block, use: echo -e '\033[?6c'
-To get red non-blinking block, use: echo -e '\033[?17;0;64c'
diff --git a/Documentation/accel/amdxdna/amdnpu.rst b/Documentation/accel/amdxdna/amdnpu.rst
new file mode 100644
index 000000000000..42e54904f9a8
--- /dev/null
+++ b/Documentation/accel/amdxdna/amdnpu.rst
@@ -0,0 +1,281 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+.. include:: <isonum.txt>
+
+=========
+ AMD NPU
+=========
+
+:Copyright: |copy| 2024 Advanced Micro Devices, Inc.
+:Author: Sonal Santan <sonal.santan@amd.com>
+
+Overview
+========
+
+AMD NPU (Neural Processing Unit) is a multi-user AI inference accelerator
+integrated into AMD client APU. NPU enables efficient execution of Machine
+Learning applications like CNN, LLM, etc. NPU is based on
+`AMD XDNA Architecture`_. NPU is managed by **amdxdna** driver.
+
+
+Hardware Description
+====================
+
+AMD NPU consists of the following hardware components:
+
+AMD XDNA Array
+--------------
+
+AMD XDNA Array comprises of 2D array of compute and memory tiles built with
+`AMD AI Engine Technology`_. Each column has 4 rows of compute tiles and 1
+row of memory tile. Each compute tile contains a VLIW processor with its own
+dedicated program and data memory. The memory tile acts as L2 memory. The 2D
+array can be partitioned at a column boundary creating a spatially isolated
+partition which can be bound to a workload context.
+
+Each column also has dedicated DMA engines to move data between host DDR and
+memory tile.
+
+AMD Phoenix and AMD Hawk Point client NPU have a 4x5 topology, i.e., 4 rows of
+compute tiles arranged into 5 columns. AMD Strix Point client APU have 4x8
+topology, i.e., 4 rows of compute tiles arranged into 8 columns.
+
+Shared L2 Memory
+----------------
+
+The single row of memory tiles create a pool of software managed on chip L2
+memory. DMA engines are used to move data between host DDR and memory tiles.
+AMD Phoenix and AMD Hawk Point NPUs have a total of 2560 KB of L2 memory.
+AMD Strix Point NPU has a total of 4096 KB of L2 memory.
+
+Microcontroller
+---------------
+
+A microcontroller runs NPU Firmware which is responsible for command processing,
+XDNA Array partition setup, XDNA Array configuration, workload context
+management and workload orchestration.
+
+NPU Firmware uses a dedicated instance of an isolated non-privileged context
+called ERT to service each workload context. ERT is also used to execute user
+provided ``ctrlcode`` associated with the workload context.
+
+NPU Firmware uses a single isolated privileged context called MERT to service
+management commands from the amdxdna driver.
+
+Mailboxes
+---------
+
+The microcontroller and amdxdna driver use a privileged channel for management
+tasks like setting up of contexts, telemetry, query, error handling, setting up
+user channel, etc. As mentioned before, privileged channel requests are
+serviced by MERT. The privileged channel is bound to a single mailbox.
+
+The microcontroller and amdxdna driver use a dedicated user channel per
+workload context. The user channel is primarily used for submitting work to
+the NPU. As mentioned before, a user channel requests are serviced by an
+instance of ERT. Each user channel is bound to its own dedicated mailbox.
+
+PCIe EP
+-------
+
+NPU is visible to the x86 host CPU as a PCIe device with multiple BARs and some
+MSI-X interrupt vectors. NPU uses a dedicated high bandwidth SoC level fabric
+for reading or writing into host memory. Each instance of ERT gets its own
+dedicated MSI-X interrupt. MERT gets a single instance of MSI-X interrupt.
+
+The number of PCIe BARs varies depending on the specific device. Based on their
+functions, PCIe BARs can generally be categorized into the following types.
+
+* PSP BAR: Expose the AMD PSP (Platform Security Processor) function
+* SMU BAR: Expose the AMD SMU (System Management Unit) function
+* SRAM BAR: Expose ring buffers for the mailbox
+* Mailbox BAR: Expose the mailbox control registers (head, tail and ISR
+ registers etc.)
+* Public Register BAR: Expose public registers
+
+On specific devices, the above-mentioned BAR type might be combined into a
+single physical PCIe BAR. Or a module might require two physical PCIe BARs to
+be fully functional. For example,
+
+* On AMD Phoenix device, PSP, SMU, Public Register BARs are on PCIe BAR index 0.
+* On AMD Strix Point device, Mailbox and Public Register BARs are on PCIe BAR
+ index 0. The PSP has some registers in PCIe BAR index 0 (Public Register BAR)
+ and PCIe BAR index 4 (PSP BAR).
+
+Process Isolation Hardware
+--------------------------
+
+As explained before, XDNA Array can be dynamically divided into isolated
+spatial partitions, each of which may have one or more columns. The spatial
+partition is setup by programming the column isolation registers by the
+microcontroller. Each spatial partition is associated with a PASID which is
+also programmed by the microcontroller. Hence multiple spatial partitions in
+the NPU can make concurrent host access protected by PASID.
+
+The NPU FW itself uses microcontroller MMU enforced isolated contexts for
+servicing user and privileged channel requests.
+
+
+Mixed Spatial and Temporal Scheduling
+=====================================
+
+AMD XDNA architecture supports mixed spatial and temporal (time sharing)
+scheduling of 2D array. This means that spatial partitions may be setup and
+torn down dynamically to accommodate various workloads. A *spatial* partition
+may be *exclusively* bound to one workload context while another partition may
+be *temporarily* bound to more than one workload contexts. The microcontroller
+updates the PASID for a temporarily shared partition to match the context that
+has been bound to the partition at any moment.
+
+Resource Solver
+---------------
+
+The Resource Solver component of the amdxdna driver manages the allocation
+of 2D array among various workloads. Every workload describes the number
+of columns required to run the NPU binary in its metadata. The Resource Solver
+component uses hints passed by the workload and its own heuristics to
+decide 2D array (re)partition strategy and mapping of workloads for spatial and
+temporal sharing of columns. The FW enforces the context-to-column(s) resource
+binding decisions made by the Resource Solver.
+
+AMD Phoenix and AMD Hawk Point client NPU can support 6 concurrent workload
+contexts. AMD Strix Point can support 16 concurrent workload contexts.
+
+
+Application Binaries
+====================
+
+A NPU application workload is comprised of two separate binaries which are
+generated by the NPU compiler.
+
+1. AMD XDNA Array overlay, which is used to configure a NPU spatial partition.
+ The overlay contains instructions for setting up the stream switch
+ configuration and ELF for the compute tiles. The overlay is loaded on the
+ spatial partition bound to the workload by the associated ERT instance.
+ Refer to the
+ `Versal Adaptive SoC AIE-ML Architecture Manual (AM020)`_ for more details.
+
+2. ``ctrlcode``, used for orchestrating the overlay loaded on the spatial
+ partition. ``ctrlcode`` is executed by the ERT running in protected mode on
+ the microcontroller in the context of the workload. ``ctrlcode`` is made up
+ of a sequence of opcodes named ``XAie_TxnOpcode``. Refer to the
+ `AI Engine Run Time`_ for more details.
+
+
+Special Host Buffers
+====================
+
+Per-context Instruction Buffer
+------------------------------
+
+Every workload context uses a host resident 64 MB buffer which is memory
+mapped into the ERT instance created to service the workload. The ``ctrlcode``
+used by the workload is copied into this special memory. This buffer is
+protected by PASID like all other input/output buffers used by that workload.
+Instruction buffer is also mapped into the user space of the workload.
+
+Global Privileged Buffer
+------------------------
+
+In addition, the driver also allocates a single buffer for maintenance tasks
+like recording errors from MERT. This global buffer uses the global IOMMU
+domain and is only accessible by MERT.
+
+
+High-level Use Flow
+===================
+
+Here are the steps to run a workload on AMD NPU:
+
+1. Compile the workload into an overlay and a ``ctrlcode`` binary.
+2. Userspace opens a context in the driver and provides the overlay.
+3. The driver checks with the Resource Solver for provisioning a set of columns
+ for the workload.
+4. The driver then asks MERT to create a context on the device with the desired
+ columns.
+5. MERT then creates an instance of ERT. MERT also maps the Instruction Buffer
+ into ERT memory.
+6. The userspace then copies the ``ctrlcode`` to the Instruction Buffer.
+7. Userspace then creates a command buffer with pointers to input, output, and
+ instruction buffer; it then submits command buffer with the driver and goes
+ to sleep waiting for completion.
+8. The driver sends the command over the Mailbox to ERT.
+9. ERT *executes* the ``ctrlcode`` in the instruction buffer.
+10. Execution of the ``ctrlcode`` kicks off DMAs to and from the host DDR while
+ AMD XDNA Array is running.
+11. When ERT reaches end of ``ctrlcode``, it raises an MSI-X to send completion
+ signal to the driver which then wakes up the waiting workload.
+
+
+Boot Flow
+=========
+
+amdxdna driver uses PSP to securely load signed NPU FW and kick off the boot
+of the NPU microcontroller. amdxdna driver then waits for the alive signal in
+a special location on BAR 0. The NPU is switched off during SoC suspend and
+turned on after resume where the NPU FW is reloaded, and the handshake is
+performed again.
+
+
+Userspace components
+====================
+
+Compiler
+--------
+
+Peano is an LLVM based open-source single core compiler for AMD XDNA Array
+compute tile. Peano is available at:
+https://github.com/Xilinx/llvm-aie
+
+IRON is an open-source array compiler for AMD XDNA Array based NPU which uses
+Peano underneath. IRON is available at:
+https://github.com/Xilinx/mlir-aie
+
+Usermode Driver (UMD)
+---------------------
+
+The open-source XRT runtime stack interfaces with amdxdna kernel driver. XRT
+can be found at:
+https://github.com/Xilinx/XRT
+
+The open-source XRT shim for NPU is can be found at:
+https://github.com/amd/xdna-driver
+
+
+DMA Operation
+=============
+
+DMA operation instructions are encoded in the ``ctrlcode`` as
+``XAIE_IO_BLOCKWRITE`` opcode. When ERT executes ``XAIE_IO_BLOCKWRITE``, DMA
+operations between host DDR and L2 memory are effected.
+
+
+Error Handling
+==============
+
+When MERT detects an error in AMD XDNA Array, it pauses execution for that
+workload context and sends an asynchronous message to the driver over the
+privileged channel. The driver then sends a buffer pointer to MERT to capture
+the register states for the partition bound to faulting workload context. The
+driver then decodes the error by reading the contents of the buffer pointer.
+
+
+Telemetry
+=========
+
+MERT can report various kinds of telemetry information like the following:
+
+* L1 interrupt counter
+* DMA counter
+* Deep Sleep counter
+* etc.
+
+
+References
+==========
+
+- `AMD XDNA Architecture <https://www.amd.com/en/technologies/xdna.html>`_
+- `AMD AI Engine Technology <https://www.xilinx.com/products/technology/ai-engine.html>`_
+- `Peano <https://github.com/Xilinx/llvm-aie>`_
+- `Versal Adaptive SoC AIE-ML Architecture Manual (AM020) <https://docs.amd.com/r/en-US/am020-versal-aie-ml>`_
+- `AI Engine Run Time <https://github.com/Xilinx/aie-rt/tree/release/main_aig>`_
diff --git a/Documentation/accel/amdxdna/index.rst b/Documentation/accel/amdxdna/index.rst
new file mode 100644
index 000000000000..38c16939f1fc
--- /dev/null
+++ b/Documentation/accel/amdxdna/index.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=====================================
+ accel/amdxdna NPU driver
+=====================================
+
+The accel/amdxdna driver supports the AMD NPU (Neural Processing Unit).
+
+.. toctree::
+
+ amdnpu
diff --git a/Documentation/accel/index.rst b/Documentation/accel/index.rst
new file mode 100644
index 000000000000..d8fa332d60a8
--- /dev/null
+++ b/Documentation/accel/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+Compute Accelerators
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ introduction
+ amdxdna/index
+ qaic/index
+ rocket/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/accel/introduction.rst b/Documentation/accel/introduction.rst
new file mode 100644
index 000000000000..ae3030136637
--- /dev/null
+++ b/Documentation/accel/introduction.rst
@@ -0,0 +1,110 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Introduction
+============
+
+The Linux compute accelerators subsystem is designed to expose compute
+accelerators in a common way to user-space and provide a common set of
+functionality.
+
+These devices can be either stand-alone ASICs or IP blocks inside an SoC/GPU.
+Although these devices are typically designed to accelerate
+Machine-Learning (ML) and/or Deep-Learning (DL) computations, the accel layer
+is not limited to handling these types of accelerators.
+
+Typically, a compute accelerator will belong to one of the following
+categories:
+
+- Edge AI - doing inference at an edge device. It can be an embedded ASIC/FPGA,
+ or an IP inside a SoC (e.g. laptop web camera). These devices
+ are typically configured using registers and can work with or without DMA.
+
+- Inference data-center - single/multi user devices in a large server. This
+ type of device can be stand-alone or an IP inside a SoC or a GPU. It will
+ have on-board DRAM (to hold the DL topology), DMA engines and
+ command submission queues (either kernel or user-space queues).
+ It might also have an MMU to manage multiple users and might also enable
+ virtualization (SR-IOV) to support multiple VMs on the same device. In
+ addition, these devices will usually have some tools, such as profiler and
+ debugger.
+
+- Training data-center - Similar to Inference data-center cards, but typically
+ have more computational power and memory b/w (e.g. HBM) and will likely have
+ a method of scaling-up/out, i.e. connecting to other training cards inside
+ the server or in other servers, respectively.
+
+All these devices typically have different runtime user-space software stacks,
+that are tailored-made to their h/w. In addition, they will also probably
+include a compiler to generate programs to their custom-made computational
+engines. Typically, the common layer in user-space will be the DL frameworks,
+such as PyTorch and TensorFlow.
+
+Sharing code with DRM
+=====================
+
+Because this type of devices can be an IP inside GPUs or have similar
+characteristics as those of GPUs, the accel subsystem will use the
+DRM subsystem's code and functionality. i.e. the accel core code will
+be part of the DRM subsystem and an accel device will be a new type of DRM
+device.
+
+This will allow us to leverage the extensive DRM code-base and
+collaborate with DRM developers that have experience with this type of
+devices. In addition, new features that will be added for the accelerator
+drivers can be of use to GPU drivers as well.
+
+Differentiation from GPUs
+=========================
+
+Because we want to prevent the extensive user-space graphic software stack
+from trying to use an accelerator as a GPU, the compute accelerators will be
+differentiated from GPUs by using a new major number and new device char files.
+
+Furthermore, the drivers will be located in a separate place in the kernel
+tree - drivers/accel/.
+
+The accelerator devices will be exposed to the user space with the dedicated
+261 major number and will have the following convention:
+
+- device char files - /dev/accel/accel\*
+- sysfs - /sys/class/accel/accel\*/
+- debugfs - /sys/kernel/debug/accel/\*/
+
+Getting Started
+===============
+
+First, read the DRM documentation at Documentation/gpu/index.rst.
+Not only it will explain how to write a new DRM driver but it will also
+contain all the information on how to contribute, the Code Of Conduct and
+what is the coding style/documentation. All of that is the same for the
+accel subsystem.
+
+Second, make sure the kernel is configured with CONFIG_DRM_ACCEL.
+
+To expose your device as an accelerator, two changes are needed to
+be done in your driver (as opposed to a standard DRM driver):
+
+- Add the DRIVER_COMPUTE_ACCEL feature flag in your drm_driver's
+ driver_features field. It is important to note that this driver feature is
+ mutually exclusive with DRIVER_RENDER and DRIVER_MODESET. Devices that want
+ to expose both graphics and compute device char files should be handled by
+ two drivers that are connected using the auxiliary bus framework.
+
+- Change the open callback in your driver fops structure to accel_open().
+ Alternatively, your driver can use DEFINE_DRM_ACCEL_FOPS macro to easily
+ set the correct function operations pointers structure.
+
+External References
+===================
+
+email threads
+-------------
+
+* `Initial discussion on the New subsystem for acceleration devices <https://lore.kernel.org/lkml/CAFCwf11=9qpNAepL7NL+YAV_QO=Wv6pnWPhKHKAepK3fNn+2Dg@mail.gmail.com/>`_ - Oded Gabbay (2022)
+* `patch-set to add the new subsystem <https://lore.kernel.org/lkml/20221022214622.18042-1-ogabbay@kernel.org/>`_ - Oded Gabbay (2022)
+
+Conference talks
+----------------
+
+* `LPC 2022 Accelerators BOF outcomes summary <https://airlied.blogspot.com/2022/09/accelerators-bof-outcomes-summary.html>`_ - Dave Airlie (2022)
diff --git a/Documentation/accel/qaic/aic080.rst b/Documentation/accel/qaic/aic080.rst
new file mode 100644
index 000000000000..d563771ea6ce
--- /dev/null
+++ b/Documentation/accel/qaic/aic080.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+===============================
+ Qualcomm Cloud AI 80 (AIC080)
+===============================
+
+Overview
+========
+
+The Qualcomm Cloud AI 80/AIC080 family of products are a derivative of AIC100.
+The number of NSPs and clock rates are reduced to fit within resource
+constrained solutions. The PCIe Product ID is 0xa080.
+
+As a derivative product, all AIC100 documentation applies.
diff --git a/Documentation/accel/qaic/aic100.rst b/Documentation/accel/qaic/aic100.rst
new file mode 100644
index 000000000000..41331cf580b1
--- /dev/null
+++ b/Documentation/accel/qaic/aic100.rst
@@ -0,0 +1,538 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+===============================
+ Qualcomm Cloud AI 100 (AIC100)
+===============================
+
+Overview
+========
+
+The Qualcomm Cloud AI 100/AIC100 family of products (including SA9000P - part of
+Snapdragon Ride) are PCIe adapter cards which contain a dedicated SoC ASIC for
+the purpose of efficiently running Artificial Intelligence (AI) Deep Learning
+inference workloads. They are AI accelerators.
+
+The PCIe interface of AIC100 is capable of PCIe Gen4 speeds over eight lanes
+(x8). An individual SoC on a card can have up to 16 NSPs for running workloads.
+Each SoC has an A53 management CPU. On card, there can be up to 32 GB of DDR.
+
+Multiple AIC100 cards can be hosted in a single system to scale overall
+performance. AIC100 cards are multi-user capable and able to execute workloads
+from multiple users in a concurrent manner.
+
+Hardware Description
+====================
+
+An AIC100 card consists of an AIC100 SoC, on-card DDR, and a set of misc
+peripherals (PMICs, etc).
+
+An AIC100 card can either be a PCIe HHHL form factor (a traditional PCIe card),
+or a Dual M.2 card. Both use PCIe to connect to the host system.
+
+As a PCIe endpoint/adapter, AIC100 uses the standard VendorID(VID)/
+DeviceID(DID) combination to uniquely identify itself to the host. AIC100
+uses the standard Qualcomm VID (0x17cb). All AIC100 SKUs use the same
+AIC100 DID (0xa100).
+
+AIC100 does not implement FLR (function level reset).
+
+AIC100 implements MSI but does not implement MSI-X. AIC100 prefers 17 MSIs to
+operate (1 for MHI, 16 for the DMA Bridge). Falling back to 1 MSI is possible in
+scenarios where reserving 32 MSIs isn't feasible.
+
+As a PCIe device, AIC100 utilizes BARs to provide host interfaces to the device
+hardware. AIC100 provides 3, 64-bit BARs.
+
+* The first BAR is 4K in size, and exposes the MHI interface to the host.
+
+* The second BAR is 2M in size, and exposes the DMA Bridge interface to the
+ host.
+
+* The third BAR is variable in size based on an individual AIC100's
+ configuration, but defaults to 64K. This BAR currently has no purpose.
+
+From the host perspective, AIC100 has several key hardware components -
+
+* MHI (Modem Host Interface)
+* QSM (QAIC Service Manager)
+* NSPs (Neural Signal Processor)
+* DMA Bridge
+* DDR
+
+MHI
+---
+
+AIC100 has one MHI interface over PCIe. MHI itself is documented at
+Documentation/mhi/index.rst MHI is the mechanism the host uses to communicate
+with the QSM. Except for workload data via the DMA Bridge, all interaction with
+the device occurs via MHI.
+
+QSM
+---
+
+QAIC Service Manager. This is an ARM A53 CPU that runs the primary
+firmware of the card and performs on-card management tasks. It also
+communicates with the host via MHI. Each AIC100 has one of
+these.
+
+NSP
+---
+
+Neural Signal Processor. Each AIC100 has up to 16 of these. These are
+the processors that run the workloads on AIC100. Each NSP is a Qualcomm Hexagon
+(Q6) DSP with HVX and HMX. Each NSP can only run one workload at a time, but
+multiple NSPs may be assigned to a single workload. Since each NSP can only run
+one workload, AIC100 is limited to 16 concurrent workloads. Workload
+"scheduling" is under the purview of the host. AIC100 does not automatically
+timeslice.
+
+DMA Bridge
+----------
+
+The DMA Bridge is custom DMA engine that manages the flow of data
+in and out of workloads. AIC100 has one of these. The DMA Bridge has 16
+channels, each consisting of a set of request/response FIFOs. Each active
+workload is assigned a single DMA Bridge channel. The DMA Bridge exposes
+hardware registers to manage the FIFOs (head/tail pointers), but requires host
+memory to store the FIFOs.
+
+DDR
+---
+
+AIC100 has on-card DDR. In total, an AIC100 can have up to 32 GB of DDR.
+This DDR is used to store workloads, data for the workloads, and is used by the
+QSM for managing the device. NSPs are granted access to sections of the DDR by
+the QSM. The host does not have direct access to the DDR, and must make
+requests to the QSM to transfer data to the DDR.
+
+High-level Use Flow
+===================
+
+AIC100 is a multi-user, programmable accelerator typically used for running
+neural networks in inferencing mode to efficiently perform AI operations.
+AIC100 is not intended for training neural networks. AIC100 can be utilized
+for generic compute workloads.
+
+Assuming a user wants to utilize AIC100, they would follow these steps:
+
+1. Compile the workload into an ELF targeting the NSP(s)
+2. Make requests to the QSM to load the workload and related artifacts into the
+ device DDR
+3. Make a request to the QSM to activate the workload onto a set of idle NSPs
+4. Make requests to the DMA Bridge to send input data to the workload to be
+ processed, and other requests to receive processed output data from the
+ workload.
+5. Once the workload is no longer required, make a request to the QSM to
+ deactivate the workload, thus putting the NSPs back into an idle state.
+6. Once the workload and related artifacts are no longer needed for future
+ sessions, make requests to the QSM to unload the data from DDR. This frees
+ the DDR to be used by other users.
+
+
+Boot Flow
+=========
+
+AIC100 uses a flashless boot flow, derived from Qualcomm MSMs.
+
+When AIC100 is first powered on, it begins executing PBL (Primary Bootloader)
+from ROM. PBL enumerates the PCIe link, and initializes the BHI (Boot Host
+Interface) component of MHI.
+
+Using BHI, the host points PBL to the location of the SBL (Secondary Bootloader)
+image. The PBL pulls the image from the host, validates it, and begins
+execution of SBL.
+
+SBL initializes MHI, and uses MHI to notify the host that the device has entered
+the SBL stage. SBL performs a number of operations:
+
+* SBL initializes the majority of hardware (anything PBL left uninitialized),
+ including DDR.
+* SBL offloads the bootlog to the host.
+* SBL synchronizes timestamps with the host for future logging.
+* SBL uses the Sahara protocol to obtain the runtime firmware images from the
+ host.
+
+Once SBL has obtained and validated the runtime firmware, it brings the NSPs out
+of reset, and jumps into the QSM.
+
+The QSM uses MHI to notify the host that the device has entered the QSM stage
+(AMSS in MHI terms). At this point, the AIC100 device is fully functional, and
+ready to process workloads.
+
+Userspace components
+====================
+
+Compiler
+--------
+
+An open compiler for AIC100 based on upstream LLVM can be found at:
+https://github.com/quic/software-kit-for-qualcomm-cloud-ai-100-cc
+
+Usermode Driver (UMD)
+---------------------
+
+An open UMD that interfaces with the qaic kernel driver can be found at:
+https://github.com/quic/software-kit-for-qualcomm-cloud-ai-100
+
+Sahara loader
+-------------
+
+An open implementation of the Sahara protocol called kickstart can be found at:
+https://github.com/andersson/qdl
+
+MHI Channels
+============
+
+AIC100 defines a number of MHI channels for different purposes. This is a list
+of the defined channels, and their uses.
+
++----------------+---------+----------+----------------------------------------+
+| Channel name | IDs | EEs | Purpose |
++================+=========+==========+========================================+
+| QAIC_LOOPBACK | 0 & 1 | AMSS | Any data sent to the device on this |
+| | | | channel is sent back to the host. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_SAHARA | 2 & 3 | SBL | Used by SBL to obtain the runtime |
+| | | | firmware from the host. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_DIAG | 4 & 5 | AMSS | Used to communicate with QSM via the |
+| | | | DIAG protocol. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_SSR | 6 & 7 | AMSS | Used to notify the host of subsystem |
+| | | | restart events, and to offload SSR |
+| | | | crashdumps. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_QDSS | 8 & 9 | AMSS | Used for the Qualcomm Debug Subsystem. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_CONTROL | 10 & 11 | AMSS | Used for the Neural Network Control |
+| | | | (NNC) protocol. This is the primary |
+| | | | channel between host and QSM for |
+| | | | managing workloads. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_LOGGING | 12 & 13 | SBL | Used by the SBL to send the bootlog to |
+| | | | the host. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_STATUS | 14 & 15 | AMSS | Used to notify the host of Reliability,|
+| | | | Accessibility, Serviceability (RAS) |
+| | | | events. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_TELEMETRY | 16 & 17 | AMSS | Used to get/set power/thermal/etc |
+| | | | attributes. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_DEBUG | 18 & 19 | AMSS | Not used. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_TIMESYNC | 20 & 21 | SBL | Used to synchronize timestamps in the |
+| | | | device side logs with the host time |
+| | | | source. |
++----------------+---------+----------+----------------------------------------+
+| QAIC_TIMESYNC | 22 & 23 | AMSS | Used to periodically synchronize |
+| _PERIODIC | | | timestamps in the device side logs with|
+| | | | the host time source. |
++----------------+---------+----------+----------------------------------------+
+| IPCR | 24 & 25 | AMSS | AF_QIPCRTR clients and servers. |
++----------------+---------+----------+----------------------------------------+
+
+DMA Bridge
+==========
+
+Overview
+--------
+
+The DMA Bridge is one of the main interfaces to the host from the device
+(the other being MHI). As part of activating a workload to run on NSPs, the QSM
+assigns that network a DMA Bridge channel. A workload's DMA Bridge channel
+(DBC for short) is solely for the use of that workload and is not shared with
+other workloads.
+
+Each DBC is a pair of FIFOs that manage data in and out of the workload. One
+FIFO is the request FIFO. The other FIFO is the response FIFO.
+
+Each DBC contains 4 registers in hardware:
+
+* Request FIFO head pointer (offset 0x0). Read only by the host. Indicates the
+ latest item in the FIFO the device has consumed.
+* Request FIFO tail pointer (offset 0x4). Read/write by the host. Host
+ increments this register to add new items to the FIFO.
+* Response FIFO head pointer (offset 0x8). Read/write by the host. Indicates
+ the latest item in the FIFO the host has consumed.
+* Response FIFO tail pointer (offset 0xc). Read only by the host. Device
+ increments this register to add new items to the FIFO.
+
+The values in each register are indexes in the FIFO. To get the location of the
+FIFO element pointed to by the register: FIFO base address + register * element
+size.
+
+DBC registers are exposed to the host via the second BAR. Each DBC consumes
+4KB of space in the BAR.
+
+The actual FIFOs are backed by host memory. When sending a request to the QSM
+to activate a network, the host must donate memory to be used for the FIFOs.
+Due to internal mapping limitations of the device, a single contiguous chunk of
+memory must be provided per DBC, which hosts both FIFOs. The request FIFO will
+consume the beginning of the memory chunk, and the response FIFO will consume
+the end of the memory chunk.
+
+Request FIFO
+------------
+
+A request FIFO element has the following structure:
+
+.. code-block:: c
+
+ struct request_elem {
+ u16 req_id;
+ u8 seq_id;
+ u8 pcie_dma_cmd;
+ u32 reserved;
+ u64 pcie_dma_source_addr;
+ u64 pcie_dma_dest_addr;
+ u32 pcie_dma_len;
+ u32 reserved;
+ u64 doorbell_addr;
+ u8 doorbell_attr;
+ u8 reserved;
+ u16 reserved;
+ u32 doorbell_data;
+ u32 sem_cmd0;
+ u32 sem_cmd1;
+ u32 sem_cmd2;
+ u32 sem_cmd3;
+ };
+
+Request field descriptions:
+
+req_id
+ request ID. A request FIFO element and a response FIFO element with
+ the same request ID refer to the same command.
+
+seq_id
+ sequence ID within a request. Ignored by the DMA Bridge.
+
+pcie_dma_cmd
+ describes the DMA element of this request.
+
+ * Bit(7) is the force msi flag, which overrides the DMA Bridge MSI logic
+ and generates a MSI when this request is complete, and QSM
+ configures the DMA Bridge to look at this bit.
+ * Bits(6:5) are reserved.
+ * Bit(4) is the completion code flag, and indicates that the DMA Bridge
+ shall generate a response FIFO element when this request is
+ complete.
+ * Bit(3) indicates if this request is a linked list transfer(0) or a bulk
+ transfer(1).
+ * Bit(2) is reserved.
+ * Bits(1:0) indicate the type of transfer. No transfer(0), to device(1),
+ from device(2). Value 3 is illegal.
+
+pcie_dma_source_addr
+ source address for a bulk transfer, or the address of the linked list.
+
+pcie_dma_dest_addr
+ destination address for a bulk transfer.
+
+pcie_dma_len
+ length of the bulk transfer. Note that the size of this field
+ limits transfers to 4G in size.
+
+doorbell_addr
+ address of the doorbell to ring when this request is complete.
+
+doorbell_attr
+ doorbell attributes.
+
+ * Bit(7) indicates if a write to a doorbell is to occur.
+ * Bits(6:2) are reserved.
+ * Bits(1:0) contain the encoding of the doorbell length. 0 is 32-bit,
+ 1 is 16-bit, 2 is 8-bit, 3 is reserved. The doorbell address
+ must be naturally aligned to the specified length.
+
+doorbell_data
+ data to write to the doorbell. Only the bits corresponding to
+ the doorbell length are valid.
+
+sem_cmdN
+ semaphore command.
+
+ * Bit(31) indicates this semaphore command is enabled.
+ * Bit(30) is the to-device DMA fence. Block this request until all
+ to-device DMA transfers are complete.
+ * Bit(29) is the from-device DMA fence. Block this request until all
+ from-device DMA transfers are complete.
+ * Bits(28:27) are reserved.
+ * Bits(26:24) are the semaphore command. 0 is NOP. 1 is init with the
+ specified value. 2 is increment. 3 is decrement. 4 is wait
+ until the semaphore is equal to the specified value. 5 is wait
+ until the semaphore is greater or equal to the specified value.
+ 6 is "P", wait until semaphore is greater than 0, then
+ decrement by 1. 7 is reserved.
+ * Bit(23) is reserved.
+ * Bit(22) is the semaphore sync. 0 is post sync, which means that the
+ semaphore operation is done after the DMA transfer. 1 is
+ presync, which gates the DMA transfer. Only one presync is
+ allowed per request.
+ * Bit(21) is reserved.
+ * Bits(20:16) is the index of the semaphore to operate on.
+ * Bits(15:12) are reserved.
+ * Bits(11:0) are the semaphore value to use in operations.
+
+Overall, a request is processed in 4 steps:
+
+1. If specified, the presync semaphore condition must be true
+2. If enabled, the DMA transfer occurs
+3. If specified, the postsync semaphore conditions must be true
+4. If enabled, the doorbell is written
+
+By using the semaphores in conjunction with the workload running on the NSPs,
+the data pipeline can be synchronized such that the host can queue multiple
+requests of data for the workload to process, but the DMA Bridge will only copy
+the data into the memory of the workload when the workload is ready to process
+the next input.
+
+Response FIFO
+-------------
+
+Once a request is fully processed, a response FIFO element is generated if
+specified in pcie_dma_cmd. The structure of a response FIFO element:
+
+.. code-block:: c
+
+ struct response_elem {
+ u16 req_id;
+ u16 completion_code;
+ };
+
+req_id
+ matches the req_id of the request that generated this element.
+
+completion_code
+ status of this request. 0 is success. Non-zero is an error.
+
+The DMA Bridge will generate a MSI to the host as a reaction to activity in the
+response FIFO of a DBC. The DMA Bridge hardware has an IRQ storm mitigation
+algorithm, where it will only generate a MSI when the response FIFO transitions
+from empty to non-empty (unless force MSI is enabled and triggered). In
+response to this MSI, the host is expected to drain the response FIFO, and must
+take care to handle any race conditions between draining the FIFO, and the
+device inserting elements into the FIFO.
+
+Neural Network Control (NNC) Protocol
+=====================================
+
+The NNC protocol is how the host makes requests to the QSM to manage workloads.
+It uses the QAIC_CONTROL MHI channel.
+
+Each NNC request is packaged into a message. Each message is a series of
+transactions. A passthrough type transaction can contain elements known as
+commands.
+
+QSM requires NNC messages be little endian encoded and the fields be naturally
+aligned. Since there are 64-bit elements in some NNC messages, 64-bit alignment
+must be maintained.
+
+A message contains a header and then a series of transactions. A message may be
+at most 4K in size from QSM to the host. From the host to the QSM, a message
+can be at most 64K (maximum size of a single MHI packet), but there is a
+continuation feature where message N+1 can be marked as a continuation of
+message N. This is used for exceedingly large DMA xfer transactions.
+
+Transaction descriptions
+------------------------
+
+passthrough
+ Allows userspace to send an opaque payload directly to the QSM.
+ This is used for NNC commands. Userspace is responsible for managing
+ the QSM message requirements in the payload.
+
+dma_xfer
+ DMA transfer. Describes an object that the QSM should DMA into the
+ device via address and size tuples.
+
+activate
+ Activate a workload onto NSPs. The host must provide memory to be
+ used by the DBC.
+
+deactivate
+ Deactivate an active workload and return the NSPs to idle.
+
+status
+ Query the QSM about it's NNC implementation. Returns the NNC version,
+ and if CRC is used.
+
+terminate
+ Release a user's resources.
+
+dma_xfer_cont
+ Continuation of a previous DMA transfer. If a DMA transfer
+ cannot be specified in a single message (highly fragmented), this
+ transaction can be used to specify more ranges.
+
+validate_partition
+ Query to QSM to determine if a partition identifier is valid.
+
+Each message is tagged with a user id, and a partition id. The user id allows
+QSM to track resources, and release them when the user goes away (eg the process
+crashes). A partition id identifies the resource partition that QSM manages,
+which this message applies to.
+
+Messages may have CRCs. Messages should have CRCs applied until the QSM
+reports via the status transaction that CRCs are not needed. The QSM on the
+SA9000P requires CRCs for black channel safing.
+
+Subsystem Restart (SSR)
+=======================
+
+SSR is the concept of limiting the impact of an error. An AIC100 device may
+have multiple users, each with their own workload running. If the workload of
+one user crashes, the fallout of that should be limited to that workload and not
+impact other workloads. SSR accomplishes this.
+
+If a particular workload crashes, QSM notifies the host via the QAIC_SSR MHI
+channel. This notification identifies the workload by its assigned DBC. A
+multi-stage recovery process is then used to cleanup both sides, and gets the
+DBC/NSPs into a working state.
+
+When SSR occurs, any state in the workload is lost. Any inputs that were in
+process, or queued by not yet serviced, are lost. The loaded artifacts will
+remain in on-card DDR, but the host will need to re-activate the workload if
+it desires to recover the workload.
+
+When SSR occurs for a specific NSP, the assigned DBC goes through the
+following state transactions in order:
+
+DBC_STATE_BEFORE_SHUTDOWN
+ Indicates that the affected NSP was found in an unrecoverable error
+ condition.
+DBC_STATE_AFTER_SHUTDOWN
+ Indicates that the NSP is under reset.
+DBC_STATE_BEFORE_POWER_UP
+ Indicates that the NSP's debug information has been collected, and is
+ ready to be collected by the host (if desired). At that stage the NSP
+ is restarted by QSM.
+DBC_STATE_AFTER_POWER_UP
+ Indicates that the NSP has been restarted, fully operational and is
+ in idle state.
+
+SSR also has an optional crashdump collection feature. If enabled, the host can
+collect the memory dump for the crashed NSP and dump it to the user space via
+the dev_coredump subsystem. The host can also decline the crashdump collection
+request from the device.
+
+Reliability, Accessibility, Serviceability (RAS)
+================================================
+
+AIC100 is expected to be deployed in server systems where RAS ideology is
+applied. Simply put, RAS is the concept of detecting, classifying, and
+reporting errors. While PCIe has AER (Advanced Error Reporting) which factors
+into RAS, AER does not allow for a device to report details about internal
+errors. Therefore, AIC100 implements a custom RAS mechanism. When a RAS event
+occurs, QSM will report the event with appropriate details via the QAIC_STATUS
+MHI channel. A sysadmin may determine that a particular device needs
+additional service based on RAS reports.
+
+Telemetry
+=========
+
+QSM has the ability to report various physical attributes of the device, and in
+some cases, to allow the host to control them. Examples include thermal limits,
+thermal readings, and power readings. These items are communicated via the
+QAIC_TELEMETRY MHI channel.
diff --git a/Documentation/accel/qaic/index.rst b/Documentation/accel/qaic/index.rst
new file mode 100644
index 000000000000..967b9dd8bace
--- /dev/null
+++ b/Documentation/accel/qaic/index.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=====================================
+ accel/qaic Qualcomm Cloud AI driver
+=====================================
+
+The accel/qaic driver supports the Qualcomm Cloud AI machine learning
+accelerator cards.
+
+.. toctree::
+
+ qaic
+ aic080
+ aic100
diff --git a/Documentation/accel/qaic/qaic.rst b/Documentation/accel/qaic/qaic.rst
new file mode 100644
index 000000000000..ef27e262cb91
--- /dev/null
+++ b/Documentation/accel/qaic/qaic.rst
@@ -0,0 +1,209 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=============
+ QAIC driver
+=============
+
+The QAIC driver is the Kernel Mode Driver (KMD) for the AIC100 family of AI
+accelerator products.
+
+Interrupts
+==========
+
+IRQ Storm Mitigation
+--------------------
+
+While the AIC100 DMA Bridge hardware implements an IRQ storm mitigation
+mechanism, it is still possible for an IRQ storm to occur. A storm can happen
+if the workload is particularly quick, and the host is responsive. If the host
+can drain the response FIFO as quickly as the device can insert elements into
+it, then the device will frequently transition the response FIFO from empty to
+non-empty and generate MSIs at a rate equivalent to the speed of the
+workload's ability to process inputs. The lprnet (license plate reader network)
+workload is known to trigger this condition, and can generate in excess of 100k
+MSIs per second. It has been observed that most systems cannot tolerate this
+for long, and will crash due to some form of watchdog due to the overhead of
+the interrupt controller interrupting the host CPU.
+
+To mitigate this issue, the QAIC driver implements specific IRQ handling. When
+QAIC receives an IRQ, it disables that line. This prevents the interrupt
+controller from interrupting the CPU. Then AIC drains the FIFO. Once the FIFO
+is drained, QAIC implements a "last chance" polling algorithm where QAIC will
+sleep for a time to see if the workload will generate more activity. The IRQ
+line remains disabled during this time. If no activity is detected, QAIC exits
+polling mode and reenables the IRQ line.
+
+This mitigation in QAIC is very effective. The same lprnet usecase that
+generates 100k IRQs per second (per /proc/interrupts) is reduced to roughly 64
+IRQs over 5 minutes while keeping the host system stable, and having the same
+workload throughput performance (within run-to-run noise variation).
+
+Single MSI Mode
+---------------
+
+MultiMSI is not well supported on all systems; virtualized ones even less so
+(circa 2023). Between hypervisors masking the PCIe MSI capability structure to
+large memory requirements for vIOMMUs (required for supporting MultiMSI), it is
+useful to be able to fall back to a single MSI when needed.
+
+To support this fallback, we allow the case where only one MSI is able to be
+allocated, and share that one MSI between MHI and the DBCs. The device detects
+when only one MSI has been configured and directs the interrupts for the DBCs
+to the interrupt normally used for MHI. Unfortunately, this means that the
+interrupt handlers for every DBC and MHI wake up for every interrupt that
+arrives; however, the DBC threaded irq handlers only are started when work to be
+done is detected (MHI will always start its threaded handler).
+
+If the DBC is configured to force MSI interrupts, this can circumvent the
+software IRQ storm mitigation mentioned above. Since the MSI is shared it is
+never disabled, allowing each new entry to the FIFO to trigger a new interrupt.
+
+
+Neural Network Control (NNC) Protocol
+=====================================
+
+The implementation of NNC is split between the KMD (QAIC) and UMD. In general,
+QAIC understands how to encode/decode NNC wire protocol, and elements of the
+protocol which requires kernel space knowledge to process (for example, mapping
+host memory to device IOVAs). QAIC understands the structure of a message, and
+all of the transactions. QAIC does not understand commands (the payload of a
+passthrough transaction).
+
+QAIC handles and enforces the required little endianness and 64-bit alignment,
+to the degree that it can. Since QAIC does not know the contents of a
+passthrough transaction, it relies on the UMD to satisfy the requirements.
+
+The terminate transaction is of particular use to QAIC. QAIC is not aware of
+the resources that are loaded onto a device since the majority of that activity
+occurs within NNC commands. As a result, QAIC does not have the means to
+roll back userspace activity. To ensure that a userspace client's resources
+are fully released in the case of a process crash, or a bug, QAIC uses the
+terminate command to let QSM know when a user has gone away, and the resources
+can be released.
+
+QSM can report a version number of the NNC protocol it supports. This is in the
+form of a Major number and a Minor number.
+
+Major number updates indicate changes to the NNC protocol which impact the
+message format, or transactions (impacts QAIC).
+
+Minor number updates indicate changes to the NNC protocol which impact the
+commands (does not impact QAIC).
+
+uAPI
+====
+
+QAIC creates an accel device per physical PCIe device. This accel device exists
+for as long as the PCIe device is known to Linux.
+
+The PCIe device may not be in the state to accept requests from userspace at
+all times. QAIC will trigger KOBJ_ONLINE/OFFLINE uevents to advertise when the
+device can accept requests (ONLINE) and when the device is no longer accepting
+requests (OFFLINE) because of a reset or other state transition.
+
+QAIC defines a number of driver specific IOCTLs as part of the userspace API.
+
+DRM_IOCTL_QAIC_MANAGE
+ This IOCTL allows userspace to send a NNC request to the QSM. The call will
+ block until a response is received, or the request has timed out.
+
+DRM_IOCTL_QAIC_CREATE_BO
+ This IOCTL allows userspace to allocate a buffer object (BO) which can send
+ or receive data from a workload. The call will return a GEM handle that
+ represents the allocated buffer. The BO is not usable until it has been
+ sliced (see DRM_IOCTL_QAIC_ATTACH_SLICE_BO).
+
+DRM_IOCTL_QAIC_MMAP_BO
+ This IOCTL allows userspace to prepare an allocated BO to be mmap'd into the
+ userspace process.
+
+DRM_IOCTL_QAIC_ATTACH_SLICE_BO
+ This IOCTL allows userspace to slice a BO in preparation for sending the BO
+ to the device. Slicing is the operation of describing what portions of a BO
+ get sent where to a workload. This requires a set of DMA transfers for the
+ DMA Bridge, and as such, locks the BO to a specific DBC.
+
+DRM_IOCTL_QAIC_EXECUTE_BO
+ This IOCTL allows userspace to submit a set of sliced BOs to the device. The
+ call is non-blocking. Success only indicates that the BOs have been queued
+ to the device, but does not guarantee they have been executed.
+
+DRM_IOCTL_QAIC_PARTIAL_EXECUTE_BO
+ This IOCTL operates like DRM_IOCTL_QAIC_EXECUTE_BO, but it allows userspace
+ to shrink the BOs sent to the device for this specific call. If a BO
+ typically has N inputs, but only a subset of those is available, this IOCTL
+ allows userspace to indicate that only the first M bytes of the BO should be
+ sent to the device to minimize data transfer overhead. This IOCTL dynamically
+ recomputes the slicing, and therefore has some processing overhead before the
+ BOs can be queued to the device.
+
+DRM_IOCTL_QAIC_WAIT_BO
+ This IOCTL allows userspace to determine when a particular BO has been
+ processed by the device. The call will block until either the BO has been
+ processed and can be re-queued to the device, or a timeout occurs.
+
+DRM_IOCTL_QAIC_PERF_STATS_BO
+ This IOCTL allows userspace to collect performance statistics on the most
+ recent execution of a BO. This allows userspace to construct an end to end
+ timeline of the BO processing for a performance analysis.
+
+DRM_IOCTL_QAIC_DETACH_SLICE_BO
+ This IOCTL allows userspace to remove the slicing information from a BO that
+ was originally provided by a call to DRM_IOCTL_QAIC_ATTACH_SLICE_BO. This
+ is the inverse of DRM_IOCTL_QAIC_ATTACH_SLICE_BO. The BO must be idle for
+ DRM_IOCTL_QAIC_DETACH_SLICE_BO to be called. After a successful detach slice
+ operation the BO may have new slicing information attached with a new call
+ to DRM_IOCTL_QAIC_ATTACH_SLICE_BO. After detach slice, the BO cannot be
+ executed until after a new attach slice operation. Combining attach slice
+ and detach slice calls allows userspace to use a BO with multiple workloads.
+
+Userspace Client Isolation
+==========================
+
+AIC100 supports multiple clients. Multiple DBCs can be consumed by a single
+client, and multiple clients can each consume one or more DBCs. Workloads
+may contain sensitive information therefore only the client that owns the
+workload should be allowed to interface with the DBC.
+
+Clients are identified by the instance associated with their open(). A client
+may only use memory they allocate, and DBCs that are assigned to their
+workloads. Attempts to access resources assigned to other clients will be
+rejected.
+
+Module parameters
+=================
+
+QAIC supports the following module parameters:
+
+**datapath_polling (bool)**
+
+Configures QAIC to use a polling thread for datapath events instead of relying
+on the device interrupts. Useful for platforms with broken multiMSI. Must be
+set at QAIC driver initialization. Default is 0 (off).
+
+**mhi_timeout_ms (unsigned int)**
+
+Sets the timeout value for MHI operations in milliseconds (ms). Must be set
+at the time the driver detects a device. Default is 2000 (2 seconds).
+
+**control_resp_timeout_s (unsigned int)**
+
+Sets the timeout value for QSM responses to NNC messages in seconds (s). Must
+be set at the time the driver is sending a request to QSM. Default is 60 (one
+minute).
+
+**wait_exec_default_timeout_ms (unsigned int)**
+
+Sets the default timeout for the wait_exec ioctl in milliseconds (ms). Must be
+set prior to the waic_exec ioctl call. A value specified in the ioctl call
+overrides this for that call. Default is 5000 (5 seconds).
+
+**datapath_poll_interval_us (unsigned int)**
+
+Sets the polling interval in microseconds (us) when datapath polling is active.
+Takes effect at the next polling interval. Default is 100 (100 us).
+
+**timesync_delay_ms (unsigned int)**
+
+Sets the time interval in milliseconds (ms) between two consecutive timesync
+operations. Default is 1000 (1000 ms).
diff --git a/Documentation/accel/rocket/index.rst b/Documentation/accel/rocket/index.rst
new file mode 100644
index 000000000000..70f97bccf100
--- /dev/null
+++ b/Documentation/accel/rocket/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=====================================
+ accel/rocket Rockchip NPU driver
+=====================================
+
+The accel/rocket driver supports the Neural Processing Units (NPUs) inside some
+Rockchip SoCs such as the RK3588. Rockchip calls it RKNN and sometimes RKNPU.
+
+The hardware is described in chapter 36 in the RK3588 TRM.
+
+This driver just powers the hardware on and off, allocates and maps buffers to
+the device and submits jobs to the frontend unit. Everything else is done in
+userspace, as a Gallium driver (also called rocket) that is part of the Mesa3D
+project.
+
+Hardware currently supported:
+
+* RK3588
diff --git a/Documentation/accounting/.gitignore b/Documentation/accounting/.gitignore
deleted file mode 100644
index 86485203c4ae..000000000000
--- a/Documentation/accounting/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-getdelays
diff --git a/Documentation/accounting/Makefile b/Documentation/accounting/Makefile
deleted file mode 100644
index 7e232cb6fd7d..000000000000
--- a/Documentation/accounting/Makefile
+++ /dev/null
@@ -1,7 +0,0 @@
-# List of programs to build
-hostprogs-y := getdelays
-
-# Tell kbuild to always build the programs
-always := $(hostprogs-y)
-
-HOSTCFLAGS_getdelays.o += -I$(objtree)/usr/include
diff --git a/Documentation/accounting/cgroupstats.rst b/Documentation/accounting/cgroupstats.rst
new file mode 100644
index 000000000000..85186e7d4035
--- /dev/null
+++ b/Documentation/accounting/cgroupstats.rst
@@ -0,0 +1,31 @@
+==================
+Control Groupstats
+==================
+
+Control Groupstats is inspired by the discussion at
+https://lore.kernel.org/r/461CF883.2030308@sw.ru and implements per cgroup statistics as
+suggested by Andrew Morton in https://lore.kernel.org/r/20070411114927.1277d7c9.akpm@linux-foundation.org.
+
+Per cgroup statistics infrastructure re-uses code from the taskstats
+interface. A new set of cgroup operations are registered with commands
+and attributes specific to cgroups. It should be very easy to
+extend per cgroup statistics, by adding members to the cgroupstats
+structure.
+
+The current model for cgroupstats is a pull, a push model (to post
+statistics on interesting events), should be very easy to add. Currently
+user space requests for statistics by passing the cgroup path.
+Statistics about the state of all the tasks in the cgroup is returned to
+user space.
+
+NOTE: We currently rely on delay accounting for extracting information
+about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
+information will not be available.
+
+To extract cgroup statistics a utility very similar to getdelays.c
+has been developed, the sample output of the utility is shown below::
+
+ ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
+ sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
+ ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
+ sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
diff --git a/Documentation/accounting/cgroupstats.txt b/Documentation/accounting/cgroupstats.txt
deleted file mode 100644
index d16a9849e60e..000000000000
--- a/Documentation/accounting/cgroupstats.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Control Groupstats is inspired by the discussion at
-http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
-suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
-
-Per cgroup statistics infrastructure re-uses code from the taskstats
-interface. A new set of cgroup operations are registered with commands
-and attributes specific to cgroups. It should be very easy to
-extend per cgroup statistics, by adding members to the cgroupstats
-structure.
-
-The current model for cgroupstats is a pull, a push model (to post
-statistics on interesting events), should be very easy to add. Currently
-user space requests for statistics by passing the cgroup path.
-Statistics about the state of all the tasks in the cgroup is returned to
-user space.
-
-NOTE: We currently rely on delay accounting for extracting information
-about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
-information will not be available.
-
-To extract cgroup statistics a utility very similar to getdelays.c
-has been developed, the sample output of the utility is shown below
-
-~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a"
-sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
-~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup"
-sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
diff --git a/Documentation/accounting/delay-accounting.rst b/Documentation/accounting/delay-accounting.rst
new file mode 100644
index 000000000000..86d7902a657f
--- /dev/null
+++ b/Documentation/accounting/delay-accounting.rst
@@ -0,0 +1,214 @@
+================
+Delay accounting
+================
+
+Tasks encounter delays in execution when they wait
+for some kernel resource to become available e.g. a
+runnable task may wait for a free CPU to run on.
+
+The per-task delay accounting functionality measures
+the delays experienced by a task while
+
+a) waiting for a CPU (while being runnable)
+b) completion of synchronous block I/O initiated by the task
+c) swapping in pages
+d) memory reclaim
+e) thrashing
+f) direct compact
+g) write-protect copy
+h) IRQ/SOFTIRQ
+
+and makes these statistics available to userspace through
+the taskstats interface.
+
+Such delays provide feedback for setting a task's cpu priority,
+io priority and rss limit values appropriately. Long delays for
+important tasks could be a trigger for raising its corresponding priority.
+
+The functionality, through its use of the taskstats interface, also provides
+delay statistics aggregated for all tasks (or threads) belonging to a
+thread group (corresponding to a traditional Unix process). This is a commonly
+needed aggregation that is more efficiently done by the kernel.
+
+Userspace utilities, particularly resource management applications, can also
+aggregate delay statistics into arbitrary groups. To enable this, delay
+statistics of a task are available both during its lifetime as well as on its
+exit, ensuring continuous and complete monitoring can be done.
+
+
+Interface
+---------
+
+Delay accounting uses the taskstats interface which is described
+in detail in a separate document in this directory. Taskstats returns a
+generic data structure to userspace corresponding to per-pid and per-tgid
+statistics. The delay accounting functionality populates specific fields of
+this structure. See
+
+ include/uapi/linux/taskstats.h
+
+for a description of the fields pertaining to delay accounting.
+It will generally be in the form of counters returning the cumulative
+delay seen for cpu, sync block I/O, swapin, memory reclaim, thrash page
+cache, direct compact, write-protect copy, IRQ/SOFTIRQ etc.
+
+Taking the difference of two successive readings of a given
+counter (say cpu_delay_total) for a task will give the delay
+experienced by the task waiting for the corresponding resource
+in that interval.
+
+When a task exits, records containing the per-task statistics
+are sent to userspace without requiring a command. If it is the last exiting
+task of a thread group, the per-tgid statistics are also sent. More details
+are given in the taskstats interface description.
+
+The getdelays.c userspace utility in tools/accounting directory allows simple
+commands to be run and the corresponding delay statistics to be displayed. It
+also serves as an example of using the taskstats interface.
+
+Usage
+-----
+
+Compile the kernel with::
+
+ CONFIG_TASK_DELAY_ACCT=y
+ CONFIG_TASKSTATS=y
+
+Delay accounting is disabled by default at boot up.
+To enable, add::
+
+ delayacct
+
+to the kernel boot options. The rest of the instructions below assume this has
+been done. Alternatively, use sysctl kernel.task_delayacct to switch the state
+at runtime. Note however that only tasks started after enabling it will have
+delayacct information.
+
+After the system has booted up, use a utility
+similar to getdelays.c to access the delays
+seen by a given task or a task group (tgid).
+The utility also allows a given command to be
+executed and the corresponding delays to be
+seen.
+
+General format of the getdelays command::
+
+ getdelays [-dilv] [-t tgid] [-p pid]
+
+Get delays, since system boot, for pid 10::
+
+ # ./getdelays -d -p 10
+ (output similar to next case)
+
+Get sum and peak of delays, since system boot, for all pids with tgid 242::
+
+ bash-4.4# ./getdelays -d -t 242
+ print delayacct stats ON
+ TGID 242
+
+
+ CPU count real total virtual total delay total delay average delay max delay min
+ 39 156000000 156576579 2111069 0.054ms 0.212296ms 0.031307ms
+ IO count delay total delay average delay max delay min
+ 0 0 0.000ms 0.000000ms 0.000000ms
+ SWAP count delay total delay average delay max delay min
+ 0 0 0.000ms 0.000000ms 0.000000ms
+ RECLAIM count delay total delay average delay max delay min
+ 0 0 0.000ms 0.000000ms 0.000000ms
+ THRASHING count delay total delay average delay max delay min
+ 0 0 0.000ms 0.000000ms 0.000000ms
+ COMPACT count delay total delay average delay max delay min
+ 0 0 0.000ms 0.000000ms 0.000000ms
+ WPCOPY count delay total delay average delay max delay min
+ 156 11215873 0.072ms 0.207403ms 0.033913ms
+ IRQ count delay total delay average delay max delay min
+ 0 0 0.000ms 0.000000ms 0.000000ms
+
+Get IO accounting for pid 1, it works only with -p::
+
+ # ./getdelays -i -p 1
+ printing IO accounting
+ linuxrc: read=65536, write=0, cancelled_write=0
+
+The above command can be used with -v to get more debug information.
+
+After the system starts, use `delaytop` to get the system-wide delay information,
+which includes system-wide PSI information and Top-N high-latency tasks.
+Note: PSI support requires `CONFIG_PSI=y` and `psi=1` for full functionality.
+
+`delaytop` is an interactive tool for monitoring system pressure and task delays.
+It supports multiple sorting options, display modes, and real-time keyboard controls.
+
+Basic usage with default settings (sorts by CPU delay, shows top 20 tasks, refreshes every 2 seconds)::
+
+ bash# ./delaytop
+ System Pressure Information: (avg10/avg60vg300/total)
+ CPU some: 0.0%/ 0.0%/ 0.0%/ 106137(ms)
+ CPU full: 0.0%/ 0.0%/ 0.0%/ 0(ms)
+ Memory full: 0.0%/ 0.0%/ 0.0%/ 0(ms)
+ Memory some: 0.0%/ 0.0%/ 0.0%/ 0(ms)
+ IO full: 0.0%/ 0.0%/ 0.0%/ 2240(ms)
+ IO some: 0.0%/ 0.0%/ 0.0%/ 2783(ms)
+ IRQ full: 0.0%/ 0.0%/ 0.0%/ 0(ms)
+ [o]sort [M]memverbose [q]quit
+ Top 20 processes (sorted by cpu delay):
+ PID TGID COMMAND CPU(ms) IO(ms) IRQ(ms) MEM(ms)
+ ------------------------------------------------------------------------
+ 110 110 kworker/15:0H-s 27.91 0.00 0.00 0.00
+ 57 57 cpuhp/7 3.18 0.00 0.00 0.00
+ 99 99 cpuhp/14 2.97 0.00 0.00 0.00
+ 51 51 cpuhp/6 0.90 0.00 0.00 0.00
+ 44 44 kworker/4:0H-sy 0.80 0.00 0.00 0.00
+ 60 60 ksoftirqd/7 0.74 0.00 0.00 0.00
+ 76 76 idle_inject/10 0.31 0.00 0.00 0.00
+ 100 100 idle_inject/14 0.30 0.00 0.00 0.00
+ 1309 1309 systemsettings 0.29 0.00 0.00 0.00
+ 45 45 cpuhp/5 0.22 0.00 0.00 0.00
+ 63 63 cpuhp/8 0.20 0.00 0.00 0.00
+ 87 87 cpuhp/12 0.18 0.00 0.00 0.00
+ 93 93 cpuhp/13 0.17 0.00 0.00 0.00
+ 1265 1265 acpid 0.17 0.00 0.00 0.00
+ 1552 1552 sshd 0.17 0.00 0.00 0.00
+ 2584 2584 sddm-helper 0.16 0.00 0.00 0.00
+ 1284 1284 rtkit-daemon 0.15 0.00 0.00 0.00
+ 1326 1326 nde-netfilter 0.14 0.00 0.00 0.00
+ 27 27 cpuhp/2 0.13 0.00 0.00 0.00
+ 631 631 kworker/11:2-rc 0.11 0.00 0.00 0.00
+
+Interactive keyboard controls during runtime::
+
+ o - Select sort field (CPU, IO, IRQ, Memory, etc.)
+ M - Toggle display mode (Default/Memory Verbose)
+ q - Quit
+
+Available sort fields(use -s/--sort or interactive command)::
+
+ cpu(c) - CPU delay
+ blkio(i) - I/O delay
+ irq(q) - IRQ delay
+ mem(m) - Total memory delay
+ swapin(s) - Swapin delay (memory verbose mode only)
+ freepages(r) - Freepages reclaim delay (memory verbose mode only)
+ thrashing(t) - Thrashing delay (memory verbose mode only)
+ compact(p) - Compaction delay (memory verbose mode only)
+ wpcopy(w) - Write page copy delay (memory verbose mode only)
+
+Advanced usage examples::
+
+ # ./delaytop -s blkio
+ Sorted by IO delay
+
+ # ./delaytop -s mem -M
+ Sorted by memory delay in memory verbose mode
+
+ # ./delaytop -p pid
+ Print delayacct stats
+
+ # ./delaytop -P num
+ Display the top N tasks
+
+ # ./delaytop -n num
+ Set delaytop refresh frequency (num times)
+
+ # ./delaytop -d secs
+ Specify refresh interval as secs
diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.txt
deleted file mode 100644
index 8a12f0730c94..000000000000
--- a/Documentation/accounting/delay-accounting.txt
+++ /dev/null
@@ -1,117 +0,0 @@
-Delay accounting
-----------------
-
-Tasks encounter delays in execution when they wait
-for some kernel resource to become available e.g. a
-runnable task may wait for a free CPU to run on.
-
-The per-task delay accounting functionality measures
-the delays experienced by a task while
-
-a) waiting for a CPU (while being runnable)
-b) completion of synchronous block I/O initiated by the task
-c) swapping in pages
-d) memory reclaim
-
-and makes these statistics available to userspace through
-the taskstats interface.
-
-Such delays provide feedback for setting a task's cpu priority,
-io priority and rss limit values appropriately. Long delays for
-important tasks could be a trigger for raising its corresponding priority.
-
-The functionality, through its use of the taskstats interface, also provides
-delay statistics aggregated for all tasks (or threads) belonging to a
-thread group (corresponding to a traditional Unix process). This is a commonly
-needed aggregation that is more efficiently done by the kernel.
-
-Userspace utilities, particularly resource management applications, can also
-aggregate delay statistics into arbitrary groups. To enable this, delay
-statistics of a task are available both during its lifetime as well as on its
-exit, ensuring continuous and complete monitoring can be done.
-
-
-Interface
----------
-
-Delay accounting uses the taskstats interface which is described
-in detail in a separate document in this directory. Taskstats returns a
-generic data structure to userspace corresponding to per-pid and per-tgid
-statistics. The delay accounting functionality populates specific fields of
-this structure. See
- include/linux/taskstats.h
-for a description of the fields pertaining to delay accounting.
-It will generally be in the form of counters returning the cumulative
-delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
-
-Taking the difference of two successive readings of a given
-counter (say cpu_delay_total) for a task will give the delay
-experienced by the task waiting for the corresponding resource
-in that interval.
-
-When a task exits, records containing the per-task statistics
-are sent to userspace without requiring a command. If it is the last exiting
-task of a thread group, the per-tgid statistics are also sent. More details
-are given in the taskstats interface description.
-
-The getdelays.c userspace utility in this directory allows simple commands to
-be run and the corresponding delay statistics to be displayed. It also serves
-as an example of using the taskstats interface.
-
-Usage
------
-
-Compile the kernel with
- CONFIG_TASK_DELAY_ACCT=y
- CONFIG_TASKSTATS=y
-
-Delay accounting is enabled by default at boot up.
-To disable, add
- nodelayacct
-to the kernel boot options. The rest of the instructions
-below assume this has not been done.
-
-After the system has booted up, use a utility
-similar to getdelays.c to access the delays
-seen by a given task or a task group (tgid).
-The utility also allows a given command to be
-executed and the corresponding delays to be
-seen.
-
-General format of the getdelays command
-
-getdelays [-t tgid] [-p pid] [-c cmd...]
-
-
-Get delays, since system boot, for pid 10
-# ./getdelays -p 10
-(output similar to next case)
-
-Get sum of delays, since system boot, for all pids with tgid 5
-# ./getdelays -t 5
-
-
-CPU count real total virtual total delay total
- 7876 92005750 100000000 24001500
-IO count delay total
- 0 0
-SWAP count delay total
- 0 0
-RECLAIM count delay total
- 0 0
-
-Get delays seen in executing a given simple command
-# ./getdelays -c ls /
-
-bin data1 data3 data5 dev home media opt root srv sys usr
-boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var
-
-
-CPU count real total virtual total delay total
- 6 4000250 4000000 0
-IO count delay total
- 0 0
-SWAP count delay total
- 0 0
-RECLAIM count delay total
- 0 0
diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c
deleted file mode 100644
index f40578026a04..000000000000
--- a/Documentation/accounting/getdelays.c
+++ /dev/null
@@ -1,546 +0,0 @@
-/* getdelays.c
- *
- * Utility to get per-pid and per-tgid delay accounting statistics
- * Also illustrates usage of the taskstats interface
- *
- * Copyright (C) Shailabh Nagar, IBM Corp. 2005
- * Copyright (C) Balbir Singh, IBM Corp. 2006
- * Copyright (c) Jay Lan, SGI. 2006
- *
- * Compile with
- * gcc -I/usr/src/linux/include getdelays.c -o getdelays
- */
-
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <unistd.h>
-#include <poll.h>
-#include <string.h>
-#include <fcntl.h>
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/wait.h>
-#include <signal.h>
-
-#include <linux/genetlink.h>
-#include <linux/taskstats.h>
-#include <linux/cgroupstats.h>
-
-/*
- * Generic macros for dealing with netlink sockets. Might be duplicated
- * elsewhere. It is recommended that commercial grade applications use
- * libnl or libnetlink and use the interfaces provided by the library
- */
-#define GENLMSG_DATA(glh) ((void *)(NLMSG_DATA(glh) + GENL_HDRLEN))
-#define GENLMSG_PAYLOAD(glh) (NLMSG_PAYLOAD(glh, 0) - GENL_HDRLEN)
-#define NLA_DATA(na) ((void *)((char*)(na) + NLA_HDRLEN))
-#define NLA_PAYLOAD(len) (len - NLA_HDRLEN)
-
-#define err(code, fmt, arg...) \
- do { \
- fprintf(stderr, fmt, ##arg); \
- exit(code); \
- } while (0)
-
-int done;
-int rcvbufsz;
-char name[100];
-int dbg;
-int print_delays;
-int print_io_accounting;
-int print_task_context_switch_counts;
-
-#define PRINTF(fmt, arg...) { \
- if (dbg) { \
- printf(fmt, ##arg); \
- } \
- }
-
-/* Maximum size of response requested or message sent */
-#define MAX_MSG_SIZE 1024
-/* Maximum number of cpus expected to be specified in a cpumask */
-#define MAX_CPUS 32
-
-struct msgtemplate {
- struct nlmsghdr n;
- struct genlmsghdr g;
- char buf[MAX_MSG_SIZE];
-};
-
-char cpumask[100+6*MAX_CPUS];
-
-static void usage(void)
-{
- fprintf(stderr, "getdelays [-dilv] [-w logfile] [-r bufsize] "
- "[-m cpumask] [-t tgid] [-p pid]\n");
- fprintf(stderr, " -d: print delayacct stats\n");
- fprintf(stderr, " -i: print IO accounting (works only with -p)\n");
- fprintf(stderr, " -l: listen forever\n");
- fprintf(stderr, " -v: debug on\n");
- fprintf(stderr, " -C: container path\n");
-}
-
-/*
- * Create a raw netlink socket and bind
- */
-static int create_nl_socket(int protocol)
-{
- int fd;
- struct sockaddr_nl local;
-
- fd = socket(AF_NETLINK, SOCK_RAW, protocol);
- if (fd < 0)
- return -1;
-
- if (rcvbufsz)
- if (setsockopt(fd, SOL_SOCKET, SO_RCVBUF,
- &rcvbufsz, sizeof(rcvbufsz)) < 0) {
- fprintf(stderr, "Unable to set socket rcv buf size to %d\n",
- rcvbufsz);
- goto error;
- }
-
- memset(&local, 0, sizeof(local));
- local.nl_family = AF_NETLINK;
-
- if (bind(fd, (struct sockaddr *) &local, sizeof(local)) < 0)
- goto error;
-
- return fd;
-error:
- close(fd);
- return -1;
-}
-
-
-static int send_cmd(int sd, __u16 nlmsg_type, __u32 nlmsg_pid,
- __u8 genl_cmd, __u16 nla_type,
- void *nla_data, int nla_len)
-{
- struct nlattr *na;
- struct sockaddr_nl nladdr;
- int r, buflen;
- char *buf;
-
- struct msgtemplate msg;
-
- msg.n.nlmsg_len = NLMSG_LENGTH(GENL_HDRLEN);
- msg.n.nlmsg_type = nlmsg_type;
- msg.n.nlmsg_flags = NLM_F_REQUEST;
- msg.n.nlmsg_seq = 0;
- msg.n.nlmsg_pid = nlmsg_pid;
- msg.g.cmd = genl_cmd;
- msg.g.version = 0x1;
- na = (struct nlattr *) GENLMSG_DATA(&msg);
- na->nla_type = nla_type;
- na->nla_len = nla_len + 1 + NLA_HDRLEN;
- memcpy(NLA_DATA(na), nla_data, nla_len);
- msg.n.nlmsg_len += NLMSG_ALIGN(na->nla_len);
-
- buf = (char *) &msg;
- buflen = msg.n.nlmsg_len ;
- memset(&nladdr, 0, sizeof(nladdr));
- nladdr.nl_family = AF_NETLINK;
- while ((r = sendto(sd, buf, buflen, 0, (struct sockaddr *) &nladdr,
- sizeof(nladdr))) < buflen) {
- if (r > 0) {
- buf += r;
- buflen -= r;
- } else if (errno != EAGAIN)
- return -1;
- }
- return 0;
-}
-
-
-/*
- * Probe the controller in genetlink to find the family id
- * for the TASKSTATS family
- */
-static int get_family_id(int sd)
-{
- struct {
- struct nlmsghdr n;
- struct genlmsghdr g;
- char buf[256];
- } ans;
-
- int id = 0, rc;
- struct nlattr *na;
- int rep_len;
-
- strcpy(name, TASKSTATS_GENL_NAME);
- rc = send_cmd(sd, GENL_ID_CTRL, getpid(), CTRL_CMD_GETFAMILY,
- CTRL_ATTR_FAMILY_NAME, (void *)name,
- strlen(TASKSTATS_GENL_NAME)+1);
- if (rc < 0)
- return 0; /* sendto() failure? */
-
- rep_len = recv(sd, &ans, sizeof(ans), 0);
- if (ans.n.nlmsg_type == NLMSG_ERROR ||
- (rep_len < 0) || !NLMSG_OK((&ans.n), rep_len))
- return 0;
-
- na = (struct nlattr *) GENLMSG_DATA(&ans);
- na = (struct nlattr *) ((char *) na + NLA_ALIGN(na->nla_len));
- if (na->nla_type == CTRL_ATTR_FAMILY_ID) {
- id = *(__u16 *) NLA_DATA(na);
- }
- return id;
-}
-
-#define average_ms(t, c) (t / 1000000ULL / (c ? c : 1))
-
-static void print_delayacct(struct taskstats *t)
-{
- printf("\n\nCPU %15s%15s%15s%15s%15s\n"
- " %15llu%15llu%15llu%15llu%15.3fms\n"
- "IO %15s%15s%15s\n"
- " %15llu%15llu%15llums\n"
- "SWAP %15s%15s%15s\n"
- " %15llu%15llu%15llums\n"
- "RECLAIM %12s%15s%15s\n"
- " %15llu%15llu%15llums\n",
- "count", "real total", "virtual total",
- "delay total", "delay average",
- (unsigned long long)t->cpu_count,
- (unsigned long long)t->cpu_run_real_total,
- (unsigned long long)t->cpu_run_virtual_total,
- (unsigned long long)t->cpu_delay_total,
- average_ms((double)t->cpu_delay_total, t->cpu_count),
- "count", "delay total", "delay average",
- (unsigned long long)t->blkio_count,
- (unsigned long long)t->blkio_delay_total,
- average_ms(t->blkio_delay_total, t->blkio_count),
- "count", "delay total", "delay average",
- (unsigned long long)t->swapin_count,
- (unsigned long long)t->swapin_delay_total,
- average_ms(t->swapin_delay_total, t->swapin_count),
- "count", "delay total", "delay average",
- (unsigned long long)t->freepages_count,
- (unsigned long long)t->freepages_delay_total,
- average_ms(t->freepages_delay_total, t->freepages_count));
-}
-
-static void task_context_switch_counts(struct taskstats *t)
-{
- printf("\n\nTask %15s%15s\n"
- " %15llu%15llu\n",
- "voluntary", "nonvoluntary",
- (unsigned long long)t->nvcsw, (unsigned long long)t->nivcsw);
-}
-
-static void print_cgroupstats(struct cgroupstats *c)
-{
- printf("sleeping %llu, blocked %llu, running %llu, stopped %llu, "
- "uninterruptible %llu\n", (unsigned long long)c->nr_sleeping,
- (unsigned long long)c->nr_io_wait,
- (unsigned long long)c->nr_running,
- (unsigned long long)c->nr_stopped,
- (unsigned long long)c->nr_uninterruptible);
-}
-
-
-static void print_ioacct(struct taskstats *t)
-{
- printf("%s: read=%llu, write=%llu, cancelled_write=%llu\n",
- t->ac_comm,
- (unsigned long long)t->read_bytes,
- (unsigned long long)t->write_bytes,
- (unsigned long long)t->cancelled_write_bytes);
-}
-
-int main(int argc, char *argv[])
-{
- int c, rc, rep_len, aggr_len, len2;
- int cmd_type = TASKSTATS_CMD_ATTR_UNSPEC;
- __u16 id;
- __u32 mypid;
-
- struct nlattr *na;
- int nl_sd = -1;
- int len = 0;
- pid_t tid = 0;
- pid_t rtid = 0;
-
- int fd = 0;
- int count = 0;
- int write_file = 0;
- int maskset = 0;
- char *logfile = NULL;
- int loop = 0;
- int containerset = 0;
- char *containerpath = NULL;
- int cfd = 0;
- int forking = 0;
- sigset_t sigset;
-
- struct msgtemplate msg;
-
- while (!forking) {
- c = getopt(argc, argv, "qdiw:r:m:t:p:vlC:c:");
- if (c < 0)
- break;
-
- switch (c) {
- case 'd':
- printf("print delayacct stats ON\n");
- print_delays = 1;
- break;
- case 'i':
- printf("printing IO accounting\n");
- print_io_accounting = 1;
- break;
- case 'q':
- printf("printing task/process context switch rates\n");
- print_task_context_switch_counts = 1;
- break;
- case 'C':
- containerset = 1;
- containerpath = optarg;
- break;
- case 'w':
- logfile = strdup(optarg);
- printf("write to file %s\n", logfile);
- write_file = 1;
- break;
- case 'r':
- rcvbufsz = atoi(optarg);
- printf("receive buf size %d\n", rcvbufsz);
- if (rcvbufsz < 0)
- err(1, "Invalid rcv buf size\n");
- break;
- case 'm':
- strncpy(cpumask, optarg, sizeof(cpumask));
- cpumask[sizeof(cpumask) - 1] = '\0';
- maskset = 1;
- printf("cpumask %s maskset %d\n", cpumask, maskset);
- break;
- case 't':
- tid = atoi(optarg);
- if (!tid)
- err(1, "Invalid tgid\n");
- cmd_type = TASKSTATS_CMD_ATTR_TGID;
- break;
- case 'p':
- tid = atoi(optarg);
- if (!tid)
- err(1, "Invalid pid\n");
- cmd_type = TASKSTATS_CMD_ATTR_PID;
- break;
- case 'c':
-
- /* Block SIGCHLD for sigwait() later */
- if (sigemptyset(&sigset) == -1)
- err(1, "Failed to empty sigset");
- if (sigaddset(&sigset, SIGCHLD))
- err(1, "Failed to set sigchld in sigset");
- sigprocmask(SIG_BLOCK, &sigset, NULL);
-
- /* fork/exec a child */
- tid = fork();
- if (tid < 0)
- err(1, "Fork failed\n");
- if (tid == 0)
- if (execvp(argv[optind - 1],
- &argv[optind - 1]) < 0)
- exit(-1);
-
- /* Set the command type and avoid further processing */
- cmd_type = TASKSTATS_CMD_ATTR_PID;
- forking = 1;
- break;
- case 'v':
- printf("debug on\n");
- dbg = 1;
- break;
- case 'l':
- printf("listen forever\n");
- loop = 1;
- break;
- default:
- usage();
- exit(-1);
- }
- }
-
- if (write_file) {
- fd = open(logfile, O_WRONLY | O_CREAT | O_TRUNC,
- S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH);
- if (fd == -1) {
- perror("Cannot open output file\n");
- exit(1);
- }
- }
-
- if ((nl_sd = create_nl_socket(NETLINK_GENERIC)) < 0)
- err(1, "error creating Netlink socket\n");
-
-
- mypid = getpid();
- id = get_family_id(nl_sd);
- if (!id) {
- fprintf(stderr, "Error getting family id, errno %d\n", errno);
- goto err;
- }
- PRINTF("family id %d\n", id);
-
- if (maskset) {
- rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET,
- TASKSTATS_CMD_ATTR_REGISTER_CPUMASK,
- &cpumask, strlen(cpumask) + 1);
- PRINTF("Sent register cpumask, retval %d\n", rc);
- if (rc < 0) {
- fprintf(stderr, "error sending register cpumask\n");
- goto err;
- }
- }
-
- if (tid && containerset) {
- fprintf(stderr, "Select either -t or -C, not both\n");
- goto err;
- }
-
- /*
- * If we forked a child, wait for it to exit. Cannot use waitpid()
- * as all the delicious data would be reaped as part of the wait
- */
- if (tid && forking) {
- int sig_received;
- sigwait(&sigset, &sig_received);
- }
-
- if (tid) {
- rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET,
- cmd_type, &tid, sizeof(__u32));
- PRINTF("Sent pid/tgid, retval %d\n", rc);
- if (rc < 0) {
- fprintf(stderr, "error sending tid/tgid cmd\n");
- goto done;
- }
- }
-
- if (containerset) {
- cfd = open(containerpath, O_RDONLY);
- if (cfd < 0) {
- perror("error opening container file");
- goto err;
- }
- rc = send_cmd(nl_sd, id, mypid, CGROUPSTATS_CMD_GET,
- CGROUPSTATS_CMD_ATTR_FD, &cfd, sizeof(__u32));
- if (rc < 0) {
- perror("error sending cgroupstats command");
- goto err;
- }
- }
- if (!maskset && !tid && !containerset) {
- usage();
- goto err;
- }
-
- do {
- rep_len = recv(nl_sd, &msg, sizeof(msg), 0);
- PRINTF("received %d bytes\n", rep_len);
-
- if (rep_len < 0) {
- fprintf(stderr, "nonfatal reply error: errno %d\n",
- errno);
- continue;
- }
- if (msg.n.nlmsg_type == NLMSG_ERROR ||
- !NLMSG_OK((&msg.n), rep_len)) {
- struct nlmsgerr *err = NLMSG_DATA(&msg);
- fprintf(stderr, "fatal reply error, errno %d\n",
- err->error);
- goto done;
- }
-
- PRINTF("nlmsghdr size=%zu, nlmsg_len=%d, rep_len=%d\n",
- sizeof(struct nlmsghdr), msg.n.nlmsg_len, rep_len);
-
-
- rep_len = GENLMSG_PAYLOAD(&msg.n);
-
- na = (struct nlattr *) GENLMSG_DATA(&msg);
- len = 0;
- while (len < rep_len) {
- len += NLA_ALIGN(na->nla_len);
- switch (na->nla_type) {
- case TASKSTATS_TYPE_AGGR_TGID:
- /* Fall through */
- case TASKSTATS_TYPE_AGGR_PID:
- aggr_len = NLA_PAYLOAD(na->nla_len);
- len2 = 0;
- /* For nested attributes, na follows */
- na = (struct nlattr *) NLA_DATA(na);
- done = 0;
- while (len2 < aggr_len) {
- switch (na->nla_type) {
- case TASKSTATS_TYPE_PID:
- rtid = *(int *) NLA_DATA(na);
- if (print_delays)
- printf("PID\t%d\n", rtid);
- break;
- case TASKSTATS_TYPE_TGID:
- rtid = *(int *) NLA_DATA(na);
- if (print_delays)
- printf("TGID\t%d\n", rtid);
- break;
- case TASKSTATS_TYPE_STATS:
- count++;
- if (print_delays)
- print_delayacct((struct taskstats *) NLA_DATA(na));
- if (print_io_accounting)
- print_ioacct((struct taskstats *) NLA_DATA(na));
- if (print_task_context_switch_counts)
- task_context_switch_counts((struct taskstats *) NLA_DATA(na));
- if (fd) {
- if (write(fd, NLA_DATA(na), na->nla_len) < 0) {
- err(1,"write error\n");
- }
- }
- if (!loop)
- goto done;
- break;
- default:
- fprintf(stderr, "Unknown nested"
- " nla_type %d\n",
- na->nla_type);
- break;
- }
- len2 += NLA_ALIGN(na->nla_len);
- na = (struct nlattr *) ((char *) na + len2);
- }
- break;
-
- case CGROUPSTATS_TYPE_CGROUP_STATS:
- print_cgroupstats(NLA_DATA(na));
- break;
- default:
- fprintf(stderr, "Unknown nla_type %d\n",
- na->nla_type);
- case TASKSTATS_TYPE_NULL:
- break;
- }
- na = (struct nlattr *) (GENLMSG_DATA(&msg) + len);
- }
- } while (loop);
-done:
- if (maskset) {
- rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET,
- TASKSTATS_CMD_ATTR_DEREGISTER_CPUMASK,
- &cpumask, strlen(cpumask) + 1);
- printf("Sent deregister mask, retval %d\n", rc);
- if (rc < 0)
- err(rc, "error sending deregister cpumask\n");
- }
-err:
- close(nl_sd);
- if (fd)
- close(fd);
- if (cfd)
- close(cfd);
- return 0;
-}
diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst
new file mode 100644
index 000000000000..9369d8bf32be
--- /dev/null
+++ b/Documentation/accounting/index.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========
+Accounting
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+ cgroupstats
+ delay-accounting
+ psi
+ taskstats
+ taskstats-struct
diff --git a/Documentation/accounting/psi.rst b/Documentation/accounting/psi.rst
new file mode 100644
index 000000000000..d455db3e5808
--- /dev/null
+++ b/Documentation/accounting/psi.rst
@@ -0,0 +1,188 @@
+.. _psi:
+
+================================
+PSI - Pressure Stall Information
+================================
+
+:Date: April, 2018
+:Author: Johannes Weiner <hannes@cmpxchg.org>
+
+When CPU, memory or IO devices are contended, workloads experience
+latency spikes, throughput losses, and run the risk of OOM kills.
+
+Without an accurate measure of such contention, users are forced to
+either play it safe and under-utilize their hardware resources, or
+roll the dice and frequently suffer the disruptions resulting from
+excessive overcommit.
+
+The psi feature identifies and quantifies the disruptions caused by
+such resource crunches and the time impact it has on complex workloads
+or even entire systems.
+
+Having an accurate measure of productivity losses caused by resource
+scarcity aids users in sizing workloads to hardware--or provisioning
+hardware according to workload demand.
+
+As psi aggregates this information in realtime, systems can be managed
+dynamically using techniques such as load shedding, migrating jobs to
+other systems or data centers, or strategically pausing or killing low
+priority or restartable batch jobs.
+
+This allows maximizing hardware utilization without sacrificing
+workload health or risking major disruptions such as OOM kills.
+
+Pressure interface
+==================
+
+Pressure information for each resource is exported through the
+respective file in /proc/pressure/ -- cpu, memory, and io.
+
+The format is as such::
+
+ some avg10=0.00 avg60=0.00 avg300=0.00 total=0
+ full avg10=0.00 avg60=0.00 avg300=0.00 total=0
+
+The "some" line indicates the share of time in which at least some
+tasks are stalled on a given resource.
+
+The "full" line indicates the share of time in which all non-idle
+tasks are stalled on a given resource simultaneously. In this state
+actual CPU cycles are going to waste, and a workload that spends
+extended time in this state is considered to be thrashing. This has
+severe impact on performance, and it's useful to distinguish this
+situation from a state where some tasks are stalled but the CPU is
+still doing productive work. As such, time spent in this subset of the
+stall state is tracked separately and exported in the "full" averages.
+
+CPU full is undefined at the system level, but has been reported
+since 5.13, so it is set to zero for backward compatibility.
+
+The ratios (in %) are tracked as recent trends over ten, sixty, and
+three hundred second windows, which gives insight into short term events
+as well as medium and long term trends. The total absolute stall time
+(in us) is tracked and exported as well, to allow detection of latency
+spikes which wouldn't necessarily make a dent in the time averages,
+or to average trends over custom time frames.
+
+Monitoring for pressure thresholds
+==================================
+
+Users can register triggers and use poll() to be woken up when resource
+pressure exceeds certain thresholds.
+
+A trigger describes the maximum cumulative stall time over a specific
+time window, e.g. 100ms of total stall time within any 500ms window to
+generate a wakeup event.
+
+To register a trigger user has to open psi interface file under
+/proc/pressure/ representing the resource to be monitored and write the
+desired threshold and time window. The open file descriptor should be
+used to wait for trigger events using select(), poll() or epoll().
+The following format is used::
+
+ <some|full> <stall amount in us> <time window in us>
+
+For example writing "some 150000 1000000" into /proc/pressure/memory
+would add 150ms threshold for partial memory stall measured within
+1sec time window. Writing "full 50000 1000000" into /proc/pressure/io
+would add 50ms threshold for full io stall measured within 1sec time window.
+
+Triggers can be set on more than one psi metric and more than one trigger
+for the same psi metric can be specified. However for each trigger a separate
+file descriptor is required to be able to poll it separately from others,
+therefore for each trigger a separate open() syscall should be made even
+when opening the same psi interface file. Write operations to a file descriptor
+with an already existing psi trigger will fail with EBUSY.
+
+Monitors activate only when system enters stall state for the monitored
+psi metric and deactivates upon exit from the stall state. While system is
+in the stall state psi signal growth is monitored at a rate of 10 times per
+tracking window.
+
+The kernel accepts window sizes ranging from 500ms to 10s, therefore min
+monitoring update interval is 50ms and max is 1s. Min limit is set to
+prevent overly frequent polling. Max limit is chosen as a high enough number
+after which monitors are most likely not needed and psi averages can be used
+instead.
+
+Unprivileged users can also create monitors, with the only limitation that the
+window size must be a multiple of 2s, in order to prevent excessive resource
+usage.
+
+When activated, psi monitor stays active for at least the duration of one
+tracking window to avoid repeated activations/deactivations when system is
+bouncing in and out of the stall state.
+
+Notifications to the userspace are rate-limited to one per tracking window.
+
+The trigger will de-register when the file descriptor used to define the
+trigger is closed.
+
+Userspace monitor usage example
+===============================
+
+::
+
+ #include <errno.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <poll.h>
+ #include <string.h>
+ #include <unistd.h>
+
+ /*
+ * Monitor memory partial stall with 1s tracking window size
+ * and 150ms threshold.
+ */
+ int main() {
+ const char trig[] = "some 150000 1000000";
+ struct pollfd fds;
+ int n;
+
+ fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK);
+ if (fds.fd < 0) {
+ printf("/proc/pressure/memory open error: %s\n",
+ strerror(errno));
+ return 1;
+ }
+ fds.events = POLLPRI;
+
+ if (write(fds.fd, trig, strlen(trig) + 1) < 0) {
+ printf("/proc/pressure/memory write error: %s\n",
+ strerror(errno));
+ return 1;
+ }
+
+ printf("waiting for events...\n");
+ while (1) {
+ n = poll(&fds, 1, -1);
+ if (n < 0) {
+ printf("poll error: %s\n", strerror(errno));
+ return 1;
+ }
+ if (fds.revents & POLLERR) {
+ printf("got POLLERR, event source is gone\n");
+ return 0;
+ }
+ if (fds.revents & POLLPRI) {
+ printf("event triggered!\n");
+ } else {
+ printf("unknown event received: 0x%x\n", fds.revents);
+ return 1;
+ }
+ }
+
+ return 0;
+ }
+
+Cgroup2 interface
+=================
+
+In a system with a CONFIG_CGROUPS=y kernel and the cgroup2 filesystem
+mounted, pressure stall information is also tracked for tasks grouped
+into cgroups. Each subdirectory in the cgroupfs mountpoint contains
+cpu.pressure, memory.pressure, and io.pressure files; the format is
+the same as the /proc/pressure/ files.
+
+Per-cgroup psi monitors can be specified and used the same way as
+system-wide ones.
diff --git a/Documentation/accounting/taskstats-struct.rst b/Documentation/accounting/taskstats-struct.rst
new file mode 100644
index 000000000000..acca51c34157
--- /dev/null
+++ b/Documentation/accounting/taskstats-struct.rst
@@ -0,0 +1,199 @@
+====================
+The struct taskstats
+====================
+
+This document contains an explanation of the struct taskstats fields.
+
+There are three different groups of fields in the struct taskstats:
+
+1) Common and basic accounting fields
+ If CONFIG_TASKSTATS is set, the taskstats interface is enabled and
+ the common fields and basic accounting fields are collected for
+ delivery at do_exit() of a task.
+2) Delay accounting fields
+ These fields are placed between::
+
+ /* Delay accounting fields start */
+
+ and::
+
+ /* Delay accounting fields end */
+
+ Their values are collected if CONFIG_TASK_DELAY_ACCT is set.
+3) Extended accounting fields
+ These fields are placed between::
+
+ /* Extended accounting fields start */
+
+ and::
+
+ /* Extended accounting fields end */
+
+ Their values are collected if CONFIG_TASK_XACCT is set.
+
+4) Per-task and per-thread context switch count statistics
+
+5) Time accounting for SMT machines
+
+6) Extended delay accounting fields for memory reclaim
+
+Future extension should add fields to the end of the taskstats struct, and
+should not change the relative position of each field within the struct.
+
+::
+
+ struct taskstats {
+
+1) Common and basic accounting fields::
+
+ /* The version number of this struct. This field is always set to
+ * TASKSTATS_VERSION, which is defined in <linux/taskstats.h>.
+ * Each time the struct is changed, the value should be incremented.
+ */
+ __u16 version;
+
+ /* The exit code of a task. */
+ __u32 ac_exitcode; /* Exit status */
+
+ /* The accounting flags of a task as defined in <linux/acct.h>
+ * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG.
+ */
+ __u8 ac_flag; /* Record flags */
+
+ /* The value of task_nice() of a task. */
+ __u8 ac_nice; /* task_nice */
+
+ /* The name of the command that started this task. */
+ char ac_comm[TS_COMM_LEN]; /* Command name */
+
+ /* The scheduling discipline as set in task->policy field. */
+ __u8 ac_sched; /* Scheduling discipline */
+
+ __u8 ac_pad[3];
+ __u32 ac_uid; /* User ID */
+ __u32 ac_gid; /* Group ID */
+ __u32 ac_pid; /* Process ID */
+ __u32 ac_ppid; /* Parent process ID */
+
+ /* The time when a task begins, in [secs] since 1970. */
+ __u32 ac_btime; /* Begin time [sec since 1970] */
+
+ /* The elapsed time of a task, in [usec]. */
+ __u64 ac_etime; /* Elapsed time [usec] */
+
+ /* The user CPU time of a task, in [usec]. */
+ __u64 ac_utime; /* User CPU time [usec] */
+
+ /* The system CPU time of a task, in [usec]. */
+ __u64 ac_stime; /* System CPU time [usec] */
+
+ /* The minor page fault count of a task, as set in task->min_flt. */
+ __u64 ac_minflt; /* Minor Page Fault Count */
+
+ /* The major page fault count of a task, as set in task->maj_flt. */
+ __u64 ac_majflt; /* Major Page Fault Count */
+
+
+2) Delay accounting fields::
+
+ /* Delay accounting fields start
+ *
+ * All values, until the comment "Delay accounting fields end" are
+ * available only if delay accounting is enabled, even though the last
+ * few fields are not delays
+ *
+ * xxx_count is the number of delay values recorded
+ * xxx_delay_total is the corresponding cumulative delay in nanoseconds
+ *
+ * xxx_delay_total wraps around to zero on overflow
+ * xxx_count incremented regardless of overflow
+ */
+
+ /* Delay waiting for cpu, while runnable
+ * count, delay_total NOT updated atomically
+ */
+ __u64 cpu_count;
+ __u64 cpu_delay_total;
+
+ /* Following four fields atomically updated using task->delays->lock */
+
+ /* Delay waiting for synchronous block I/O to complete
+ * does not account for delays in I/O submission
+ */
+ __u64 blkio_count;
+ __u64 blkio_delay_total;
+
+ /* Delay waiting for page fault I/O (swap in only) */
+ __u64 swapin_count;
+ __u64 swapin_delay_total;
+
+ /* cpu "wall-clock" running time
+ * On some architectures, value will adjust for cpu time stolen
+ * from the kernel in involuntary waits due to virtualization.
+ * Value is cumulative, in nanoseconds, without a corresponding count
+ * and wraps around to zero silently on overflow
+ */
+ __u64 cpu_run_real_total;
+
+ /* cpu "virtual" running time
+ * Uses time intervals seen by the kernel i.e. no adjustment
+ * for kernel's involuntary waits due to virtualization.
+ * Value is cumulative, in nanoseconds, without a corresponding count
+ * and wraps around to zero silently on overflow
+ */
+ __u64 cpu_run_virtual_total;
+ /* Delay accounting fields end */
+ /* version 1 ends here */
+
+
+3) Extended accounting fields::
+
+ /* Extended accounting fields start */
+
+ /* Accumulated RSS usage in duration of a task, in MBytes-usecs.
+ * The current rss usage is added to this counter every time
+ * a tick is charged to a task's system time. So, at the end we
+ * will have memory usage multiplied by system time. Thus an
+ * average usage per system time unit can be calculated.
+ */
+ __u64 coremem; /* accumulated RSS usage in MB-usec */
+
+ /* Accumulated virtual memory usage in duration of a task.
+ * Same as acct_rss_mem1 above except that we keep track of VM usage.
+ */
+ __u64 virtmem; /* accumulated VM usage in MB-usec */
+
+ /* High watermark of RSS usage in duration of a task, in KBytes. */
+ __u64 hiwater_rss; /* High-watermark of RSS usage */
+
+ /* High watermark of VM usage in duration of a task, in KBytes. */
+ __u64 hiwater_vm; /* High-water virtual memory usage */
+
+ /* The following four fields are I/O statistics of a task. */
+ __u64 read_char; /* bytes read */
+ __u64 write_char; /* bytes written */
+ __u64 read_syscalls; /* read syscalls */
+ __u64 write_syscalls; /* write syscalls */
+
+ /* Extended accounting fields end */
+
+4) Per-task and per-thread statistics::
+
+ __u64 nvcsw; /* Context voluntary switch counter */
+ __u64 nivcsw; /* Context involuntary switch counter */
+
+5) Time accounting for SMT machines::
+
+ __u64 ac_utimescaled; /* utime scaled on frequency etc */
+ __u64 ac_stimescaled; /* stime scaled on frequency etc */
+ __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */
+
+6) Extended delay accounting fields for memory reclaim::
+
+ /* Delay waiting for memory reclaim */
+ __u64 freepages_count;
+ __u64 freepages_delay_total;
+
+::
+
+ }
diff --git a/Documentation/accounting/taskstats-struct.txt b/Documentation/accounting/taskstats-struct.txt
deleted file mode 100644
index e7512c061c15..000000000000
--- a/Documentation/accounting/taskstats-struct.txt
+++ /dev/null
@@ -1,180 +0,0 @@
-The struct taskstats
---------------------
-
-This document contains an explanation of the struct taskstats fields.
-
-There are three different groups of fields in the struct taskstats:
-
-1) Common and basic accounting fields
- If CONFIG_TASKSTATS is set, the taskstats interface is enabled and
- the common fields and basic accounting fields are collected for
- delivery at do_exit() of a task.
-2) Delay accounting fields
- These fields are placed between
- /* Delay accounting fields start */
- and
- /* Delay accounting fields end */
- Their values are collected if CONFIG_TASK_DELAY_ACCT is set.
-3) Extended accounting fields
- These fields are placed between
- /* Extended accounting fields start */
- and
- /* Extended accounting fields end */
- Their values are collected if CONFIG_TASK_XACCT is set.
-
-4) Per-task and per-thread context switch count statistics
-
-5) Time accounting for SMT machines
-
-6) Extended delay accounting fields for memory reclaim
-
-Future extension should add fields to the end of the taskstats struct, and
-should not change the relative position of each field within the struct.
-
-
-struct taskstats {
-
-1) Common and basic accounting fields:
- /* The version number of this struct. This field is always set to
- * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>.
- * Each time the struct is changed, the value should be incremented.
- */
- __u16 version;
-
- /* The exit code of a task. */
- __u32 ac_exitcode; /* Exit status */
-
- /* The accounting flags of a task as defined in <linux/acct.h>
- * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG.
- */
- __u8 ac_flag; /* Record flags */
-
- /* The value of task_nice() of a task. */
- __u8 ac_nice; /* task_nice */
-
- /* The name of the command that started this task. */
- char ac_comm[TS_COMM_LEN]; /* Command name */
-
- /* The scheduling discipline as set in task->policy field. */
- __u8 ac_sched; /* Scheduling discipline */
-
- __u8 ac_pad[3];
- __u32 ac_uid; /* User ID */
- __u32 ac_gid; /* Group ID */
- __u32 ac_pid; /* Process ID */
- __u32 ac_ppid; /* Parent process ID */
-
- /* The time when a task begins, in [secs] since 1970. */
- __u32 ac_btime; /* Begin time [sec since 1970] */
-
- /* The elapsed time of a task, in [usec]. */
- __u64 ac_etime; /* Elapsed time [usec] */
-
- /* The user CPU time of a task, in [usec]. */
- __u64 ac_utime; /* User CPU time [usec] */
-
- /* The system CPU time of a task, in [usec]. */
- __u64 ac_stime; /* System CPU time [usec] */
-
- /* The minor page fault count of a task, as set in task->min_flt. */
- __u64 ac_minflt; /* Minor Page Fault Count */
-
- /* The major page fault count of a task, as set in task->maj_flt. */
- __u64 ac_majflt; /* Major Page Fault Count */
-
-
-2) Delay accounting fields:
- /* Delay accounting fields start
- *
- * All values, until the comment "Delay accounting fields end" are
- * available only if delay accounting is enabled, even though the last
- * few fields are not delays
- *
- * xxx_count is the number of delay values recorded
- * xxx_delay_total is the corresponding cumulative delay in nanoseconds
- *
- * xxx_delay_total wraps around to zero on overflow
- * xxx_count incremented regardless of overflow
- */
-
- /* Delay waiting for cpu, while runnable
- * count, delay_total NOT updated atomically
- */
- __u64 cpu_count;
- __u64 cpu_delay_total;
-
- /* Following four fields atomically updated using task->delays->lock */
-
- /* Delay waiting for synchronous block I/O to complete
- * does not account for delays in I/O submission
- */
- __u64 blkio_count;
- __u64 blkio_delay_total;
-
- /* Delay waiting for page fault I/O (swap in only) */
- __u64 swapin_count;
- __u64 swapin_delay_total;
-
- /* cpu "wall-clock" running time
- * On some architectures, value will adjust for cpu time stolen
- * from the kernel in involuntary waits due to virtualization.
- * Value is cumulative, in nanoseconds, without a corresponding count
- * and wraps around to zero silently on overflow
- */
- __u64 cpu_run_real_total;
-
- /* cpu "virtual" running time
- * Uses time intervals seen by the kernel i.e. no adjustment
- * for kernel's involuntary waits due to virtualization.
- * Value is cumulative, in nanoseconds, without a corresponding count
- * and wraps around to zero silently on overflow
- */
- __u64 cpu_run_virtual_total;
- /* Delay accounting fields end */
- /* version 1 ends here */
-
-
-3) Extended accounting fields
- /* Extended accounting fields start */
-
- /* Accumulated RSS usage in duration of a task, in MBytes-usecs.
- * The current rss usage is added to this counter every time
- * a tick is charged to a task's system time. So, at the end we
- * will have memory usage multiplied by system time. Thus an
- * average usage per system time unit can be calculated.
- */
- __u64 coremem; /* accumulated RSS usage in MB-usec */
-
- /* Accumulated virtual memory usage in duration of a task.
- * Same as acct_rss_mem1 above except that we keep track of VM usage.
- */
- __u64 virtmem; /* accumulated VM usage in MB-usec */
-
- /* High watermark of RSS usage in duration of a task, in KBytes. */
- __u64 hiwater_rss; /* High-watermark of RSS usage */
-
- /* High watermark of VM usage in duration of a task, in KBytes. */
- __u64 hiwater_vm; /* High-water virtual memory usage */
-
- /* The following four fields are I/O statistics of a task. */
- __u64 read_char; /* bytes read */
- __u64 write_char; /* bytes written */
- __u64 read_syscalls; /* read syscalls */
- __u64 write_syscalls; /* write syscalls */
-
- /* Extended accounting fields end */
-
-4) Per-task and per-thread statistics
- __u64 nvcsw; /* Context voluntary switch counter */
- __u64 nivcsw; /* Context involuntary switch counter */
-
-5) Time accounting for SMT machines
- __u64 ac_utimescaled; /* utime scaled on frequency etc */
- __u64 ac_stimescaled; /* stime scaled on frequency etc */
- __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */
-
-6) Extended delay accounting fields for memory reclaim
- /* Delay waiting for memory reclaim */
- __u64 freepages_count;
- __u64 freepages_delay_total;
-}
diff --git a/Documentation/accounting/taskstats.rst b/Documentation/accounting/taskstats.rst
new file mode 100644
index 000000000000..173c1e7bf5ef
--- /dev/null
+++ b/Documentation/accounting/taskstats.rst
@@ -0,0 +1,182 @@
+=============================
+Per-task statistics interface
+=============================
+
+
+Taskstats is a netlink-based interface for sending per-task and
+per-process statistics from the kernel to userspace.
+
+Taskstats was designed for the following benefits:
+
+- efficiently provide statistics during lifetime of a task and on its exit
+- unified interface for multiple accounting subsystems
+- extensibility for use by future accounting patches
+
+Terminology
+-----------
+
+"pid", "tid" and "task" are used interchangeably and refer to the standard
+Linux task defined by struct task_struct. per-pid stats are the same as
+per-task stats.
+
+"tgid", "process" and "thread group" are used interchangeably and refer to the
+tasks that share an mm_struct i.e. the traditional Unix process. Despite the
+use of tgid, there is no special treatment for the task that is thread group
+leader - a process is deemed alive as long as it has any task belonging to it.
+
+Usage
+-----
+
+To get statistics during a task's lifetime, userspace opens a unicast netlink
+socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
+The response contains statistics for a task (if pid is specified) or the sum of
+statistics for all tasks of the process (if tgid is specified).
+
+To obtain statistics for tasks which are exiting, the userspace listener
+sends a register command and specifies a cpumask. Whenever a task exits on
+one of the cpus in the cpumask, its per-pid statistics are sent to the
+registered listener. Using cpumasks allows the data received by one listener
+to be limited and assists in flow control over the netlink interface and is
+explained in more detail below.
+
+If the exiting task is the last thread exiting its thread group,
+an additional record containing the per-tgid stats is also sent to userspace.
+The latter contains the sum of per-pid stats for all threads in the thread
+group, both past and present.
+
+getdelays.c is a simple utility demonstrating usage of the taskstats interface
+for reporting delay accounting statistics. Users can register cpumasks,
+send commands and process responses, listen for per-tid/tgid exit data,
+write the data received to a file and do basic flow control by increasing
+receive buffer sizes.
+
+Interface
+---------
+
+The user-kernel interface is encapsulated in include/linux/taskstats.h
+
+To avoid this documentation becoming obsolete as the interface evolves, only
+an outline of the current version is given. taskstats.h always overrides the
+description here.
+
+struct taskstats is the common accounting structure for both per-pid and
+per-tgid data. It is versioned and can be extended by each accounting subsystem
+that is added to the kernel. The fields and their semantics are defined in the
+taskstats.h file.
+
+The data exchanged between user and kernel space is a netlink message belonging
+to the NETLINK_GENERIC family and using the netlink attributes interface.
+The messages are in the format::
+
+ +----------+- - -+-------------+-------------------+
+ | nlmsghdr | Pad | genlmsghdr | taskstats payload |
+ +----------+- - -+-------------+-------------------+
+
+
+The taskstats payload is one of the following three kinds:
+
+1. Commands: Sent from user to kernel. Commands to get data on
+ a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID,
+ containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes
+ the task/process for which userspace wants statistics.
+
+ Commands to register/deregister interest in exit data from a set of cpus
+ consist of one attribute, of type
+ TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the
+ attribute payload. The cpumask is specified as an ascii string of
+ comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8
+ the cpumask would be "1-3,5,7-8". If userspace forgets to deregister
+ interest in cpus before closing the listening socket, the kernel cleans up
+ its interest set over time. However, for the sake of efficiency, an explicit
+ deregistration is advisable.
+
+2. Response for a command: sent from the kernel in response to a userspace
+ command. The payload is a series of three attributes of type:
+
+ a) TASKSTATS_TYPE_AGGR_PID/TGID: attribute containing no payload but
+ indicates a pid/tgid will be followed by some stats.
+
+ b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose
+ stats are being returned.
+
+ c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The
+ same structure is used for both per-pid and per-tgid stats.
+
+3. New message sent by kernel whenever a task exits. The payload consists of a
+ series of attributes of the following type:
+
+ a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
+ b) TASKSTATS_TYPE_PID: contains exiting task's pid
+ c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
+ d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be
+ tgid+stats
+ e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
+ f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's
+ process
+
+
+per-tgid stats
+--------------
+
+Taskstats provides per-process stats, in addition to per-task stats, since
+resource management is often done at a process granularity and aggregating task
+stats in userspace alone is inefficient and potentially inaccurate (due to lack
+of atomicity).
+
+However, maintaining per-process, in addition to per-task stats, within the
+kernel has space and time overheads. To address this, the taskstats code
+accumulates each exiting task's statistics into a process-wide data structure.
+When the last task of a process exits, the process level data accumulated also
+gets sent to userspace (along with the per-task data).
+
+When a user queries to get per-tgid data, the sum of all other live threads in
+the group is added up and added to the accumulated total for previously exited
+threads of the same thread group.
+
+Extending taskstats
+-------------------
+
+There are two ways to extend the taskstats interface to export more
+per-task/process stats as patches to collect them get added to the kernel
+in future:
+
+1. Adding more fields to the end of the existing struct taskstats. Backward
+ compatibility is ensured by the version number within the
+ structure. Userspace will use only the fields of the struct that correspond
+ to the version its using.
+
+2. Defining separate statistic structs and using the netlink attributes
+ interface to return them. Since userspace processes each netlink attribute
+ independently, it can always ignore attributes whose type it does not
+ understand (because it is using an older version of the interface).
+
+
+Choosing between 1. and 2. is a matter of trading off flexibility and
+overhead. If only a few fields need to be added, then 1. is the preferable
+path since the kernel and userspace don't need to incur the overhead of
+processing new netlink attributes. But if the new fields expand the existing
+struct too much, requiring disparate userspace accounting utilities to
+unnecessarily receive large structures whose fields are of no interest, then
+extending the attributes structure would be worthwhile.
+
+Flow control for taskstats
+--------------------------
+
+When the rate of task exits becomes large, a listener may not be able to keep
+up with the kernel's rate of sending per-tid/tgid exit data leading to data
+loss. This possibility gets compounded when the taskstats structure gets
+extended and the number of cpus grows large.
+
+To avoid losing statistics, userspace should do one or more of the following:
+
+- increase the receive buffer sizes for the netlink sockets opened by
+ listeners to receive exit data.
+
+- create more listeners and reduce the number of cpus being listened to by
+ each listener. In the extreme case, there could be one listener for each cpu.
+ Users may also consider setting the cpu affinity of the listener to the subset
+ of cpus to which it listens, especially if they are listening to just one cpu.
+
+Despite these measures, if the userspace receives ENOBUFS error messages
+indicated overflow of receive buffers, it should take measures to handle the
+loss of data.
diff --git a/Documentation/accounting/taskstats.txt b/Documentation/accounting/taskstats.txt
deleted file mode 100644
index ff06b738bb88..000000000000
--- a/Documentation/accounting/taskstats.txt
+++ /dev/null
@@ -1,181 +0,0 @@
-Per-task statistics interface
------------------------------
-
-
-Taskstats is a netlink-based interface for sending per-task and
-per-process statistics from the kernel to userspace.
-
-Taskstats was designed for the following benefits:
-
-- efficiently provide statistics during lifetime of a task and on its exit
-- unified interface for multiple accounting subsystems
-- extensibility for use by future accounting patches
-
-Terminology
------------
-
-"pid", "tid" and "task" are used interchangeably and refer to the standard
-Linux task defined by struct task_struct. per-pid stats are the same as
-per-task stats.
-
-"tgid", "process" and "thread group" are used interchangeably and refer to the
-tasks that share an mm_struct i.e. the traditional Unix process. Despite the
-use of tgid, there is no special treatment for the task that is thread group
-leader - a process is deemed alive as long as it has any task belonging to it.
-
-Usage
------
-
-To get statistics during a task's lifetime, userspace opens a unicast netlink
-socket (NETLINK_GENERIC family) and sends commands specifying a pid or a tgid.
-The response contains statistics for a task (if pid is specified) or the sum of
-statistics for all tasks of the process (if tgid is specified).
-
-To obtain statistics for tasks which are exiting, the userspace listener
-sends a register command and specifies a cpumask. Whenever a task exits on
-one of the cpus in the cpumask, its per-pid statistics are sent to the
-registered listener. Using cpumasks allows the data received by one listener
-to be limited and assists in flow control over the netlink interface and is
-explained in more detail below.
-
-If the exiting task is the last thread exiting its thread group,
-an additional record containing the per-tgid stats is also sent to userspace.
-The latter contains the sum of per-pid stats for all threads in the thread
-group, both past and present.
-
-getdelays.c is a simple utility demonstrating usage of the taskstats interface
-for reporting delay accounting statistics. Users can register cpumasks,
-send commands and process responses, listen for per-tid/tgid exit data,
-write the data received to a file and do basic flow control by increasing
-receive buffer sizes.
-
-Interface
----------
-
-The user-kernel interface is encapsulated in include/linux/taskstats.h
-
-To avoid this documentation becoming obsolete as the interface evolves, only
-an outline of the current version is given. taskstats.h always overrides the
-description here.
-
-struct taskstats is the common accounting structure for both per-pid and
-per-tgid data. It is versioned and can be extended by each accounting subsystem
-that is added to the kernel. The fields and their semantics are defined in the
-taskstats.h file.
-
-The data exchanged between user and kernel space is a netlink message belonging
-to the NETLINK_GENERIC family and using the netlink attributes interface.
-The messages are in the format
-
- +----------+- - -+-------------+-------------------+
- | nlmsghdr | Pad | genlmsghdr | taskstats payload |
- +----------+- - -+-------------+-------------------+
-
-
-The taskstats payload is one of the following three kinds:
-
-1. Commands: Sent from user to kernel. Commands to get data on
-a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID,
-containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes
-the task/process for which userspace wants statistics.
-
-Commands to register/deregister interest in exit data from a set of cpus
-consist of one attribute, of type
-TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the
-attribute payload. The cpumask is specified as an ascii string of
-comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8
-the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest
-in cpus before closing the listening socket, the kernel cleans up its interest
-set over time. However, for the sake of efficiency, an explicit deregistration
-is advisable.
-
-2. Response for a command: sent from the kernel in response to a userspace
-command. The payload is a series of three attributes of type:
-
-a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates
-a pid/tgid will be followed by some stats.
-
-b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats
-are being returned.
-
-c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The
-same structure is used for both per-pid and per-tgid stats.
-
-3. New message sent by kernel whenever a task exits. The payload consists of a
- series of attributes of the following type:
-
-a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats
-b) TASKSTATS_TYPE_PID: contains exiting task's pid
-c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats
-d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats
-e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs
-f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process
-
-
-per-tgid stats
---------------
-
-Taskstats provides per-process stats, in addition to per-task stats, since
-resource management is often done at a process granularity and aggregating task
-stats in userspace alone is inefficient and potentially inaccurate (due to lack
-of atomicity).
-
-However, maintaining per-process, in addition to per-task stats, within the
-kernel has space and time overheads. To address this, the taskstats code
-accumulates each exiting task's statistics into a process-wide data structure.
-When the last task of a process exits, the process level data accumulated also
-gets sent to userspace (along with the per-task data).
-
-When a user queries to get per-tgid data, the sum of all other live threads in
-the group is added up and added to the accumulated total for previously exited
-threads of the same thread group.
-
-Extending taskstats
--------------------
-
-There are two ways to extend the taskstats interface to export more
-per-task/process stats as patches to collect them get added to the kernel
-in future:
-
-1. Adding more fields to the end of the existing struct taskstats. Backward
- compatibility is ensured by the version number within the
- structure. Userspace will use only the fields of the struct that correspond
- to the version its using.
-
-2. Defining separate statistic structs and using the netlink attributes
- interface to return them. Since userspace processes each netlink attribute
- independently, it can always ignore attributes whose type it does not
- understand (because it is using an older version of the interface).
-
-
-Choosing between 1. and 2. is a matter of trading off flexibility and
-overhead. If only a few fields need to be added, then 1. is the preferable
-path since the kernel and userspace don't need to incur the overhead of
-processing new netlink attributes. But if the new fields expand the existing
-struct too much, requiring disparate userspace accounting utilities to
-unnecessarily receive large structures whose fields are of no interest, then
-extending the attributes structure would be worthwhile.
-
-Flow control for taskstats
---------------------------
-
-When the rate of task exits becomes large, a listener may not be able to keep
-up with the kernel's rate of sending per-tid/tgid exit data leading to data
-loss. This possibility gets compounded when the taskstats structure gets
-extended and the number of cpus grows large.
-
-To avoid losing statistics, userspace should do one or more of the following:
-
-- increase the receive buffer sizes for the netlink sockets opened by
-listeners to receive exit data.
-
-- create more listeners and reduce the number of cpus being listened to by
-each listener. In the extreme case, there could be one listener for each cpu.
-Users may also consider setting the cpu affinity of the listener to the subset
-of cpus to which it listens, especially if they are listening to just one cpu.
-
-Despite these measures, if the userspace receives ENOBUFS error messages
-indicated overflow of receive buffers, it should take measures to handle the
-loss of data.
-
-----
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.txt
deleted file mode 100644
index e550c8b98139..000000000000
--- a/Documentation/acpi/apei/einj.txt
+++ /dev/null
@@ -1,177 +0,0 @@
- APEI Error INJection
- ~~~~~~~~~~~~~~~~~~~~
-
-EINJ provides a hardware error injection mechanism. It is very useful
-for debugging and testing APEI and RAS features in general.
-
-You need to check whether your BIOS supports EINJ first. For that, look
-for early boot messages similar to this one:
-
-ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
-
-which shows that the BIOS is exposing an EINJ table - it is the
-mechanism through which the injection is done.
-
-Alternatively, look in /sys/firmware/acpi/tables for an "EINJ" file,
-which is a different representation of the same thing.
-
-It doesn't necessarily mean that EINJ is not supported if those above
-don't exist: before you give up, go into BIOS setup to see if the BIOS
-has an option to enable error injection. Look for something called WHEA
-or similar. Often, you need to enable an ACPI5 support option prior, in
-order to see the APEI,EINJ,... functionality supported and exposed by
-the BIOS menu.
-
-To use EINJ, make sure the following are options enabled in your kernel
-configuration:
-
-CONFIG_DEBUG_FS
-CONFIG_ACPI_APEI
-CONFIG_ACPI_APEI_EINJ
-
-The EINJ user interface is in <debugfs mount point>/apei/einj.
-
-The following files belong to it:
-
-- available_error_type
-
- This file shows which error types are supported:
-
- Error Type Value Error Description
- ================ =================
- 0x00000001 Processor Correctable
- 0x00000002 Processor Uncorrectable non-fatal
- 0x00000004 Processor Uncorrectable fatal
- 0x00000008 Memory Correctable
- 0x00000010 Memory Uncorrectable non-fatal
- 0x00000020 Memory Uncorrectable fatal
- 0x00000040 PCI Express Correctable
- 0x00000080 PCI Express Uncorrectable fatal
- 0x00000100 PCI Express Uncorrectable non-fatal
- 0x00000200 Platform Correctable
- 0x00000400 Platform Uncorrectable non-fatal
- 0x00000800 Platform Uncorrectable fatal
-
- The format of the file contents are as above, except present are only
- the available error types.
-
-- error_type
-
- Set the value of the error type being injected. Possible error types
- are defined in the file available_error_type above.
-
-- error_inject
-
- Write any integer to this file to trigger the error injection. Make
- sure you have specified all necessary error parameters, i.e. this
- write should be the last step when injecting errors.
-
-- flags
-
- Present for kernel versions 3.13 and above. Used to specify which
- of param{1..4} are valid and should be used by the firmware during
- injection. Value is a bitmask as specified in ACPI5.0 spec for the
- SET_ERROR_TYPE_WITH_ADDRESS data structure:
-
- Bit 0 - Processor APIC field valid (see param3 below).
- Bit 1 - Memory address and mask valid (param1 and param2).
- Bit 2 - PCIe (seg,bus,dev,fn) valid (see param4 below).
-
- If set to zero, legacy behavior is mimicked where the type of
- injection specifies just one bit set, and param1 is multiplexed.
-
-- param1
-
- This file is used to set the first error parameter value. Its effect
- depends on the error type specified in error_type. For example, if
- error type is memory related type, the param1 should be a valid
- physical memory address. [Unless "flag" is set - see above]
-
-- param2
-
- Same use as param1 above. For example, if error type is of memory
- related type, then param2 should be a physical memory address mask.
- Linux requires page or narrower granularity, say, 0xfffffffffffff000.
-
-- param3
-
- Used when the 0x1 bit is set in "flags" to specify the APIC id
-
-- param4
- Used when the 0x4 bit is set in "flags" to specify target PCIe device
-
-- notrigger
-
- The error injection mechanism is a two-step process. First inject the
- error, then perform some actions to trigger it. Setting "notrigger"
- to 1 skips the trigger phase, which *may* allow the user to cause the
- error in some other context by a simple access to the CPU, memory
- location, or device that is the target of the error injection. Whether
- this actually works depends on what operations the BIOS actually
- includes in the trigger phase.
-
-BIOS versions based on the ACPI 4.0 specification have limited options
-in controlling where the errors are injected. Your BIOS may support an
-extension (enabled with the param_extension=1 module parameter, or boot
-command line einj.param_extension=1). This allows the address and mask
-for memory injections to be specified by the param1 and param2 files in
-apei/einj.
-
-BIOS versions based on the ACPI 5.0 specification have more control over
-the target of the injection. For processor-related errors (type 0x1, 0x2
-and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and
-param2 for bit 1) so that you have more information added to the error
-signature being injected. The actual data passed is this:
-
- memory_address = param1;
- memory_address_range = param2;
- apicid = param3;
- pcie_sbdf = param4;
-
-For memory errors (type 0x8, 0x10 and 0x20) the address is set using
-param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI
-express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and
-function are specified using param1:
-
- 31 24 23 16 15 11 10 8 7 0
- +-------------------------------------------------+
- | segment | bus | device | function | reserved |
- +-------------------------------------------------+
-
-Anyway, you get the idea, if there's doubt just take a look at the code
-in drivers/acpi/apei/einj.c.
-
-An ACPI 5.0 BIOS may also allow vendor-specific errors to be injected.
-In this case a file named vendor will contain identifying information
-from the BIOS that hopefully will allow an application wishing to use
-the vendor-specific extension to tell that they are running on a BIOS
-that supports it. All vendor extensions have the 0x80000000 bit set in
-error_type. A file vendor_flags controls the interpretation of param1
-and param2 (1 = PROCESSOR, 2 = MEMORY, 4 = PCI). See your BIOS vendor
-documentation for details (and expect changes to this API if vendors
-creativity in using this feature expands beyond our expectations).
-
-
-An error injection example:
-
-# cd /sys/kernel/debug/apei/einj
-# cat available_error_type # See which errors can be injected
-0x00000002 Processor Uncorrectable non-fatal
-0x00000008 Memory Correctable
-0x00000010 Memory Uncorrectable non-fatal
-# echo 0x12345000 > param1 # Set memory address for injection
-# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
-# echo 0x8 > error_type # Choose correctable memory error
-# echo 1 > error_inject # Inject now
-
-You should see something like this in dmesg:
-
-[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
-[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
-[22715.834759] EDAC sbridge MC3: TSC 0
-[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
-[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
-[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
-
-For more information about EINJ, please refer to ACPI specification
-version 4.0, section 17.5 and ACPI 5.0, section 18.6.
diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt
deleted file mode 100644
index 0c49c197c47a..000000000000
--- a/Documentation/acpi/apei/output_format.txt
+++ /dev/null
@@ -1,147 +0,0 @@
- APEI output format
- ~~~~~~~~~~~~~~~~~~
-
-APEI uses printk as hardware error reporting interface, the output
-format is as follow.
-
-<error record> :=
-APEI generic hardware error status
-severity: <integer>, <severity string>
-section: <integer>, severity: <integer>, <severity string>
-flags: <integer>
-<section flags strings>
-fru_id: <uuid string>
-fru_text: <string>
-section_type: <section type string>
-<section data>
-
-<severity string>* := recoverable | fatal | corrected | info
-
-<section flags strings># :=
-[primary][, containment warning][, reset][, threshold exceeded]\
-[, resource not accessible][, latent error]
-
-<section type string> := generic processor error | memory error | \
-PCIe error | unknown, <uuid string>
-
-<section data> :=
-<generic processor section data> | <memory section data> | \
-<pcie section data> | <null>
-
-<generic processor section data> :=
-[processor_type: <integer>, <proc type string>]
-[processor_isa: <integer>, <proc isa string>]
-[error_type: <integer>
-<proc error type strings>]
-[operation: <integer>, <proc operation string>]
-[flags: <integer>
-<proc flags strings>]
-[level: <integer>]
-[version_info: <integer>]
-[processor_id: <integer>]
-[target_address: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[IP: <integer>]
-
-<proc type string>* := IA32/X64 | IA64
-
-<proc isa string>* := IA32 | IA64 | X64
-
-<processor error type strings># :=
-[cache error][, TLB error][, bus error][, micro-architectural error]
-
-<proc operation string>* := unknown or generic | data read | data write | \
-instruction execution
-
-<proc flags strings># :=
-[restartable][, precise IP][, overflow][, corrected]
-
-<memory section data> :=
-[error_status: <integer>]
-[physical_address: <integer>]
-[physical_address_mask: <integer>]
-[node: <integer>]
-[card: <integer>]
-[module: <integer>]
-[bank: <integer>]
-[device: <integer>]
-[row: <integer>]
-[column: <integer>]
-[bit_position: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[target_id: <integer>]
-[error_type: <integer>, <mem error type string>]
-
-<mem error type string>* :=
-unknown | no error | single-bit ECC | multi-bit ECC | \
-single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
-target abort | parity error | watchdog timeout | invalid address | \
-mirror Broken | memory sparing | scrub corrected error | \
-scrub uncorrected error
-
-<pcie section data> :=
-[port_type: <integer>, <pcie port type string>]
-[version: <integer>.<integer>]
-[command: <integer>, status: <integer>]
-[device_id: <integer>:<integer>:<integer>.<integer>
-slot: <integer>
-secondary_bus: <integer>
-vendor_id: <integer>, device_id: <integer>
-class_code: <integer>]
-[serial number: <integer>, <integer>]
-[bridge: secondary_status: <integer>, control: <integer>]
-[aer_status: <integer>, aer_mask: <integer>
-<aer status string>
-[aer_uncor_severity: <integer>]
-aer_layer=<aer layer string>, aer_agent=<aer agent string>
-aer_tlp_header: <integer> <integer> <integer> <integer>]
-
-<pcie port type string>* := PCIe end point | legacy PCI end point | \
-unknown | unknown | root port | upstream switch port | \
-downstream switch port | PCIe to PCI/PCI-X bridge | \
-PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
-root complex event collector
-
-if section severity is fatal or recoverable
-<aer status string># :=
-unknown | unknown | unknown | unknown | Data Link Protocol | \
-unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
-Poisoned TLP | Flow Control Protocol | Completion Timeout | \
-Completer Abort | Unexpected Completion | Receiver Overflow | \
-Malformed TLP | ECRC | Unsupported Request
-else
-<aer status string># :=
-Receiver Error | unknown | unknown | unknown | unknown | unknown | \
-Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
-Replay Timer Timeout | Advisory Non-Fatal
-fi
-
-<aer layer string> :=
-Physical Layer | Data Link Layer | Transaction Layer
-
-<aer agent string> :=
-Receiver ID | Requester ID | Completer ID | Transmitter ID
-
-Where, [] designate corresponding content is optional
-
-All <field string> description with * has the following format:
-
-field: <integer>, <field string>
-
-Where value of <integer> should be the position of "string" in <field
-string> description. Otherwise, <field string> will be "unknown".
-
-All <field strings> description with # has the following format:
-
-field: <integer>
-<field strings>
-
-Where each string in <fields strings> corresponding to one set bit of
-<integer>. The bit position is the position of "string" in <field
-strings> description.
-
-For more detailed explanation of every field, please refer to UEFI
-specification version 2.3 or later, section Appendix N: Common
-Platform Error Record.
diff --git a/Documentation/acpi/debug.txt b/Documentation/acpi/debug.txt
deleted file mode 100644
index 65bf47c46b6d..000000000000
--- a/Documentation/acpi/debug.txt
+++ /dev/null
@@ -1,148 +0,0 @@
- ACPI Debug Output
-
-
-The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
-output. This document describes how to use this facility.
-
-Compile-time configuration
---------------------------
-
-ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config
-option is turned off, the debug messages are not even built into the
-kernel.
-
-Boot- and run-time configuration
---------------------------------
-
-When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
-you're interested in. At boot-time, use the acpi.debug_layer and
-acpi.debug_level kernel command line options. After boot, you can use the
-debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
-the debug messages.
-
-debug_layer (component)
------------------------
-
-The "debug_layer" is a mask that selects components of interest, e.g., a
-specific driver or part of the ACPI interpreter. To build the debug_layer
-bitmask, look for the "#define _COMPONENT" in an ACPI source file.
-
-You can set the debug_layer mask at boot-time using the acpi.debug_layer
-command line argument, and you can change it after boot by writing values
-to /sys/module/acpi/parameters/debug_layer.
-
-The possible components are defined in include/acpi/acoutput.h and
-include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer
-shows the supported mask values, currently these:
-
- ACPI_UTILITIES 0x00000001
- ACPI_HARDWARE 0x00000002
- ACPI_EVENTS 0x00000004
- ACPI_TABLES 0x00000008
- ACPI_NAMESPACE 0x00000010
- ACPI_PARSER 0x00000020
- ACPI_DISPATCHER 0x00000040
- ACPI_EXECUTER 0x00000080
- ACPI_RESOURCES 0x00000100
- ACPI_CA_DEBUGGER 0x00000200
- ACPI_OS_SERVICES 0x00000400
- ACPI_CA_DISASSEMBLER 0x00000800
- ACPI_COMPILER 0x00001000
- ACPI_TOOLS 0x00002000
- ACPI_BUS_COMPONENT 0x00010000
- ACPI_AC_COMPONENT 0x00020000
- ACPI_BATTERY_COMPONENT 0x00040000
- ACPI_BUTTON_COMPONENT 0x00080000
- ACPI_SBS_COMPONENT 0x00100000
- ACPI_FAN_COMPONENT 0x00200000
- ACPI_PCI_COMPONENT 0x00400000
- ACPI_POWER_COMPONENT 0x00800000
- ACPI_CONTAINER_COMPONENT 0x01000000
- ACPI_SYSTEM_COMPONENT 0x02000000
- ACPI_THERMAL_COMPONENT 0x04000000
- ACPI_MEMORY_DEVICE_COMPONENT 0x08000000
- ACPI_VIDEO_COMPONENT 0x10000000
- ACPI_PROCESSOR_COMPONENT 0x20000000
-
-debug_level
------------
-
-The "debug_level" is a mask that selects different types of messages, e.g.,
-those related to initialization, method execution, informational messages, etc.
-To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT()
-statement.
-
-The ACPI interpreter uses several different levels, but the Linux
-ACPI core and ACPI drivers generally only use ACPI_LV_INFO.
-
-You can set the debug_level mask at boot-time using the acpi.debug_level
-command line argument, and you can change it after boot by writing values
-to /sys/module/acpi/parameters/debug_level.
-
-The possible levels are defined in include/acpi/acoutput.h. Reading
-/sys/module/acpi/parameters/debug_level shows the supported mask values,
-currently these:
-
- ACPI_LV_INIT 0x00000001
- ACPI_LV_DEBUG_OBJECT 0x00000002
- ACPI_LV_INFO 0x00000004
- ACPI_LV_INIT_NAMES 0x00000020
- ACPI_LV_PARSE 0x00000040
- ACPI_LV_LOAD 0x00000080
- ACPI_LV_DISPATCH 0x00000100
- ACPI_LV_EXEC 0x00000200
- ACPI_LV_NAMES 0x00000400
- ACPI_LV_OPREGION 0x00000800
- ACPI_LV_BFIELD 0x00001000
- ACPI_LV_TABLES 0x00002000
- ACPI_LV_VALUES 0x00004000
- ACPI_LV_OBJECTS 0x00008000
- ACPI_LV_RESOURCES 0x00010000
- ACPI_LV_USER_REQUESTS 0x00020000
- ACPI_LV_PACKAGE 0x00040000
- ACPI_LV_ALLOCATIONS 0x00100000
- ACPI_LV_FUNCTIONS 0x00200000
- ACPI_LV_OPTIMIZATIONS 0x00400000
- ACPI_LV_MUTEX 0x01000000
- ACPI_LV_THREADS 0x02000000
- ACPI_LV_IO 0x04000000
- ACPI_LV_INTERRUPTS 0x08000000
- ACPI_LV_AML_DISASSEMBLE 0x10000000
- ACPI_LV_VERBOSE_INFO 0x20000000
- ACPI_LV_FULL_TABLES 0x40000000
- ACPI_LV_EVENTS 0x80000000
-
-Examples
---------
-
-For example, drivers/acpi/bus.c contains this:
-
- #define _COMPONENT ACPI_BUS_COMPONENT
- ...
- ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n"));
-
-To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer
-and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT
-statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
-definition.)
-
-Enable all AML "Debug" output (stores to the Debug object while interpreting
-AML) during boot:
-
- acpi.debug_layer=0xffffffff acpi.debug_level=0x2
-
-Enable PCI and PCI interrupt routing debug messages:
-
- acpi.debug_layer=0x400000 acpi.debug_level=0x4
-
-Enable all ACPI hardware-related messages:
-
- acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
-
-Enable all ACPI_DB_INFO messages after boot:
-
- # echo 0x4 > /sys/module/acpi/parameters/debug_level
-
-Show all valid component values:
-
- # cat /sys/module/acpi/parameters/debug_layer
diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/acpi/dsdt-override.txt
deleted file mode 100644
index 784841caa6e6..000000000000
--- a/Documentation/acpi/dsdt-override.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-Linux supports a method of overriding the BIOS DSDT:
-
-CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
-
-When to use this method is described in detail on the
-Linux/ACPI home page:
-https://01.org/linux-acpi/documentation/overriding-dsdt
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt
deleted file mode 100644
index 750401f91341..000000000000
--- a/Documentation/acpi/enumeration.txt
+++ /dev/null
@@ -1,361 +0,0 @@
-ACPI based device enumeration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
-SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
-devices behind serial bus controllers.
-
-In addition we are starting to see peripherals integrated in the
-SoC/Chipset to appear only in ACPI namespace. These are typically devices
-that are accessed through memory-mapped registers.
-
-In order to support this and re-use the existing drivers as much as
-possible we decided to do following:
-
- o Devices that have no bus connector resource are represented as
- platform devices.
-
- o Devices behind real busses where there is a connector resource
- are represented as struct spi_device or struct i2c_device
- (standard UARTs are not busses so there is no struct uart_device).
-
-As both ACPI and Device Tree represent a tree of devices (and their
-resources) this implementation follows the Device Tree way as much as
-possible.
-
-The ACPI implementation enumerates devices behind busses (platform, SPI and
-I2C), creates the physical devices and binds them to their ACPI handle in
-the ACPI namespace.
-
-This means that when ACPI_HANDLE(dev) returns non-NULL the device was
-enumerated from ACPI namespace. This handle can be used to extract other
-device-specific configuration. There is an example of this below.
-
-Platform bus support
-~~~~~~~~~~~~~~~~~~~~
-Since we are using platform devices to represent devices that are not
-connected to any physical bus we only need to implement a platform driver
-for the device and add supported ACPI IDs. If this same IP-block is used on
-some other non-ACPI platform, the driver might work out of the box or needs
-some minor changes.
-
-Adding ACPI support for an existing driver should be pretty
-straightforward. Here is the simplest example:
-
- #ifdef CONFIG_ACPI
- static struct acpi_device_id mydrv_acpi_match[] = {
- /* ACPI IDs here */
- { }
- };
- MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
- #endif
-
- static struct platform_driver my_driver = {
- ...
- .driver = {
- .acpi_match_table = ACPI_PTR(mydrv_acpi_match),
- },
- };
-
-If the driver needs to perform more complex initialization like getting and
-configuring GPIOs it can get its ACPI handle and extract this information
-from ACPI tables.
-
-DMA support
-~~~~~~~~~~~
-DMA controllers enumerated via ACPI should be registered in the system to
-provide generic access to their resources. For example, a driver that would
-like to be accessible to slave devices via generic API call
-dma_request_slave_channel() must register itself at the end of the probe
-function like this:
-
- err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
- /* Handle the error if it's not a case of !CONFIG_ACPI */
-
-and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
-is enough) which converts the FixedDMA resource provided by struct
-acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
-could look like:
-
- #ifdef CONFIG_ACPI
- struct filter_args {
- /* Provide necessary information for the filter_func */
- ...
- };
-
- static bool filter_func(struct dma_chan *chan, void *param)
- {
- /* Choose the proper channel */
- ...
- }
-
- static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
- struct acpi_dma *adma)
- {
- dma_cap_mask_t cap;
- struct filter_args args;
-
- /* Prepare arguments for filter_func */
- ...
- return dma_request_channel(cap, filter_func, &args);
- }
- #else
- static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
- struct acpi_dma *adma)
- {
- return NULL;
- }
- #endif
-
-dma_request_slave_channel() will call xlate_func() for each registered DMA
-controller. In the xlate function the proper channel must be chosen based on
-information in struct acpi_dma_spec and the properties of the controller
-provided by struct acpi_dma.
-
-Clients must call dma_request_slave_channel() with the string parameter that
-corresponds to a specific FixedDMA resource. By default "tx" means the first
-entry of the FixedDMA resource array, "rx" means the second entry. The table
-below shows a layout:
-
- Device (I2C0)
- {
- ...
- Method (_CRS, 0, NotSerialized)
- {
- Name (DBUF, ResourceTemplate ()
- {
- FixedDMA (0x0018, 0x0004, Width32bit, _Y48)
- FixedDMA (0x0019, 0x0005, Width32bit, )
- })
- ...
- }
- }
-
-So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in
-this example.
-
-In robust cases the client unfortunately needs to call
-acpi_dma_request_slave_chan_by_index() directly and therefore choose the
-specific FixedDMA resource by its index.
-
-SPI serial bus support
-~~~~~~~~~~~~~~~~~~~~~~
-Slave devices behind SPI bus have SpiSerialBus resource attached to them.
-This is extracted automatically by the SPI core and the slave devices are
-enumerated once spi_register_master() is called by the bus driver.
-
-Here is what the ACPI namespace for a SPI slave might look like:
-
- Device (EEP0)
- {
- Name (_ADR, 1)
- Name (_CID, Package() {
- "ATML0025",
- "AT25",
- })
- ...
- Method (_CRS, 0, NotSerialized)
- {
- SPISerialBus(1, PolarityLow, FourWireMode, 8,
- ControllerInitiated, 1000000, ClockPolarityLow,
- ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
- }
- ...
-
-The SPI device drivers only need to add ACPI IDs in a similar way than with
-the platform device drivers. Below is an example where we add ACPI support
-to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
-
- #ifdef CONFIG_ACPI
- static struct acpi_device_id at25_acpi_match[] = {
- { "AT25", 0 },
- { },
- };
- MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
- #endif
-
- static struct spi_driver at25_driver = {
- .driver = {
- ...
- .acpi_match_table = ACPI_PTR(at25_acpi_match),
- },
- };
-
-Note that this driver actually needs more information like page size of the
-eeprom etc. but at the time writing this there is no standard way of
-passing those. One idea is to return this in _DSM method like:
-
- Device (EEP0)
- {
- ...
- Method (_DSM, 4, NotSerialized)
- {
- Store (Package (6)
- {
- "byte-len", 1024,
- "addr-mode", 2,
- "page-size, 32
- }, Local0)
-
- // Check UUIDs etc.
-
- Return (Local0)
- }
-
-Then the at25 SPI driver can get this configuration by calling _DSM on its
-ACPI handle like:
-
- struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
- struct acpi_object_list input;
- acpi_status status;
-
- /* Fill in the input buffer */
-
- status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
- &input, &output);
- if (ACPI_FAILURE(status))
- /* Handle the error */
-
- /* Extract the data here */
-
- kfree(output.pointer);
-
-I2C serial bus support
-~~~~~~~~~~~~~~~~~~~~~~
-The slaves behind I2C bus controller only need to add the ACPI IDs like
-with the platform and SPI drivers. The I2C core automatically enumerates
-any slave devices behind the controller device once the adapter is
-registered.
-
-Below is an example of how to add ACPI support to the existing mpu3050
-input driver:
-
- #ifdef CONFIG_ACPI
- static struct acpi_device_id mpu3050_acpi_match[] = {
- { "MPU3050", 0 },
- { },
- };
- MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
- #endif
-
- static struct i2c_driver mpu3050_i2c_driver = {
- .driver = {
- .name = "mpu3050",
- .owner = THIS_MODULE,
- .pm = &mpu3050_pm,
- .of_match_table = mpu3050_of_match,
- .acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
- },
- .probe = mpu3050_probe,
- .remove = mpu3050_remove,
- .id_table = mpu3050_ids,
- };
-
-GPIO support
-~~~~~~~~~~~~
-ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
-and GpioInt. These resources are used be used to pass GPIO numbers used by
-the device to the driver. ACPI 5.1 extended this with _DSD (Device
-Specific Data) which made it possible to name the GPIOs among other things.
-
-For example:
-
-Device (DEV)
-{
- Method (_CRS, 0, NotSerialized)
- {
- Name (SBUF, ResourceTemplate()
- {
- ...
- // Used to power on/off the device
- GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
- IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
- 0x00, ResourceConsumer,,)
- {
- // Pin List
- 0x0055
- }
-
- // Interrupt for the device
- GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
- 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
- {
- // Pin list
- 0x0058
- }
-
- ...
-
- }
-
- Return (SBUF)
- }
-
- // ACPI 5.1 _DSD used for naming the GPIOs
- Name (_DSD, Package ()
- {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package ()
- {
- Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
- Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
- }
- })
- ...
-
-These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
-specifies the path to the controller. In order to use these GPIOs in Linux
-we need to translate them to the corresponding Linux GPIO descriptors.
-
-There is a standard GPIO API for that and is documented in
-Documentation/gpio/.
-
-In the above example we can get the corresponding two GPIO descriptors with
-a code like this:
-
- #include <linux/gpio/consumer.h>
- ...
-
- struct gpio_desc *irq_desc, *power_desc;
-
- irq_desc = gpiod_get(dev, "irq");
- if (IS_ERR(irq_desc))
- /* handle error */
-
- power_desc = gpiod_get(dev, "power");
- if (IS_ERR(power_desc))
- /* handle error */
-
- /* Now we can use the GPIO descriptors */
-
-There are also devm_* versions of these functions which release the
-descriptors once the device is released.
-
-See Documentation/acpi/gpio-properties.txt for more information about the
-_DSD binding related to GPIOs.
-
-MFD devices
-~~~~~~~~~~~
-The MFD devices register their children as platform devices. For the child
-devices there needs to be an ACPI handle that they can use to reference
-parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
-we provide two ways:
-
- o The children share the parent ACPI handle.
- o The MFD cell can specify the ACPI id of the device.
-
-For the first case, the MFD drivers do not need to do anything. The
-resulting child platform device will have its ACPI_COMPANION() set to point
-to the parent device.
-
-If the ACPI namespace has a device that we can match using an ACPI id,
-the id should be set like:
-
- static struct mfd_cell my_subdevice_cell = {
- .name = "my_subdevice",
- /* set the resources relative to the parent */
- .acpi_pnpid = "XYZ0001",
- };
-
-The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
-the MFD device and if found, that ACPI companion device is bound to the
-resulting child platform device.
diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt
deleted file mode 100644
index ae36fcf86dc7..000000000000
--- a/Documentation/acpi/gpio-properties.txt
+++ /dev/null
@@ -1,96 +0,0 @@
-_DSD Device Properties Related to GPIO
---------------------------------------
-
-With the release of ACPI 5.1 and the _DSD configuration objecte names
-can finally be given to GPIOs (and other things as well) returned by
-_CRS. Previously, we were only able to use an integer index to find
-the corresponding GPIO, which is pretty error prone (it depends on
-the _CRS output ordering, for example).
-
-With _DSD we can now query GPIOs using a name instead of an integer
-index, like the ASL example below shows:
-
- // Bluetooth device with reset and shutdown GPIOs
- Device (BTH)
- {
- Name (_HID, ...)
-
- Name (_CRS, ResourceTemplate ()
- {
- GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly,
- "\\_SB.GPO0", 0, ResourceConsumer) {15}
- GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly,
- "\\_SB.GPO0", 0, ResourceConsumer) {27, 31}
- })
-
- Name (_DSD, Package ()
- {
- ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
- Package ()
- {
- Package () {"reset-gpio", Package() {^BTH, 1, 1, 0 }},
- Package () {"shutdown-gpio", Package() {^BTH, 0, 0, 0 }},
- }
- })
- }
-
-The format of the supported GPIO property is:
-
- Package () { "name", Package () { ref, index, pin, active_low }}
-
- ref - The device that has _CRS containing GpioIo()/GpioInt() resources,
- typically this is the device itself (BTH in our case).
- index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
- pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
- active_low - If 1 the GPIO is marked as active_low.
-
-Since ACPI GpioIo() resource does not have a field saying whether it is
-active low or high, the "active_low" argument can be used here. Setting
-it to 1 marks the GPIO as active low.
-
-In our Bluetooth example the "reset-gpio" refers to the second GpioIo()
-resource, second pin in that resource with the GPIO number of 31.
-
-ACPI GPIO Mappings Provided by Drivers
---------------------------------------
-
-There are systems in which the ACPI tables do not contain _DSD but provide _CRS
-with GpioIo()/GpioInt() resources and device drivers still need to work with
-them.
-
-In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV,
-available to the driver can be used to identify the device and that is supposed
-to be sufficient to determine the meaning and purpose of all of the GPIO lines
-listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words,
-the driver is supposed to know what to use the GpioIo()/GpioInt() resources for
-once it has identified the device. Having done that, it can simply assign names
-to the GPIO lines it is going to use and provide the GPIO subsystem with a
-mapping between those names and the ACPI GPIO resources corresponding to them.
-
-To do that, the driver needs to define a mapping table as a NULL-terminated
-array of struct acpi_gpio_mapping objects that each contain a name, a pointer
-to an array of line data (struct acpi_gpio_params) objects and the size of that
-array. Each struct acpi_gpio_params object consists of three fields,
-crs_entry_index, line_index, active_low, representing the index of the target
-GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target
-line in that resource starting from zero, and the active-low flag for that line,
-respectively, in analogy with the _DSD GPIO property format specified above.
-
-For the example Bluetooth device discussed previously the data structures in
-question would look like this:
-
-static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
-static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
-
-static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
- { "reset-gpio", &reset_gpio, 1 },
- { "shutdown-gpio", &shutdown_gpio, 1 },
- { },
-};
-
-Next, the mapping table needs to be passed as the second argument to
-acpi_dev_add_driver_gpios() that will register it with the ACPI device object
-pointed to by its first argument. That should be done in the driver's .probe()
-routine. On removal, the driver should unregister its GPIO mapping table by
-calling acpi_dev_remove_driver_gpios() on the ACPI device object where that
-table was previously registered.
diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt
deleted file mode 100644
index 35c3f5415476..000000000000
--- a/Documentation/acpi/initrd_table_override.txt
+++ /dev/null
@@ -1,94 +0,0 @@
-Overriding ACPI tables via initrd
-=================================
-
-1) Introduction (What is this about)
-2) What is this for
-3) How does it work
-4) References (Where to retrieve userspace tools)
-
-1) What is this about
----------------------
-
-If the ACPI_INITRD_TABLE_OVERRIDE compile option is true, it is possible to
-override nearly any ACPI table provided by the BIOS with an instrumented,
-modified one.
-
-For a full list of ACPI tables that can be overridden, take a look at
-the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in drivers/acpi/osl.c
-All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
-be overridable, except:
- - ACPI_SIG_RSDP (has a signature of 6 bytes)
- - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
-Both could get implemented as well.
-
-
-2) What is this for
--------------------
-
-Please keep in mind that this is a debug option.
-ACPI tables should not get overridden for productive use.
-If BIOS ACPI tables are overridden the kernel will get tainted with the
-TAINT_OVERRIDDEN_ACPI_TABLE flag.
-Complain to your platform/BIOS vendor if you find a bug which is so sever
-that a workaround is not accepted in the Linux kernel.
-
-Still, it can and should be enabled in any kernel, because:
- - There is no functional change with not instrumented initrds
- - It provides a powerful feature to easily debug and test ACPI BIOS table
- compatibility with the Linux kernel.
-
-
-3) How does it work
--------------------
-
-# Extract the machine's ACPI tables:
-cd /tmp
-acpidump >acpidump
-acpixtract -a acpidump
-# Disassemble, modify and recompile them:
-iasl -d *.dat
-# For example add this statement into a _PRT (PCI Routing Table) function
-# of the DSDT:
-Store("HELLO WORLD", debug)
-iasl -sa dsdt.dsl
-# Add the raw ACPI tables to an uncompressed cpio archive.
-# They must be put into a /kernel/firmware/acpi directory inside the
-# cpio archive.
-# The uncompressed cpio archive must be the first.
-# Other, typically compressed cpio archives, must be
-# concatenated on top of the uncompressed one.
-mkdir -p kernel/firmware/acpi
-cp dsdt.aml kernel/firmware/acpi
-# A maximum of: #define ACPI_OVERRIDE_TABLES 10
-# tables are currently allowed (see osl.c):
-iasl -sa facp.dsl
-iasl -sa ssdt1.dsl
-cp facp.aml kernel/firmware/acpi
-cp ssdt1.aml kernel/firmware/acpi
-# Create the uncompressed cpio archive and concatenate the original initrd
-# on top:
-find kernel | cpio -H newc --create > /boot/instrumented_initrd
-cat /boot/initrd >>/boot/instrumented_initrd
-# reboot with increased acpi debug level, e.g. boot params:
-acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
-# and check your syslog:
-[ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
-[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
-
-iasl is able to disassemble and recompile quite a lot different,
-also static ACPI tables.
-
-
-4) Where to retrieve userspace tools
-------------------------------------
-
-iasl and acpixtract are part of Intel's ACPICA project:
-http://acpica.org/
-and should be packaged by distributions (for example in the acpica package
-on SUSE).
-
-acpidump can be found in Len Browns pmtools:
-ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
-This tool is also part of the acpica package on SUSE.
-Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
-/sys/firmware/acpi/tables
diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt
deleted file mode 100644
index 5f55373dd53b..000000000000
--- a/Documentation/acpi/method-customizing.txt
+++ /dev/null
@@ -1,73 +0,0 @@
-Linux ACPI Custom Control Method How To
-=======================================
-
-Written by Zhang Rui <rui.zhang@intel.com>
-
-
-Linux supports customizing ACPI control methods at runtime.
-
-Users can use this to
-1. override an existing method which may not work correctly,
- or just for debugging purposes.
-2. insert a completely new method in order to create a missing
- method such as _OFF, _ON, _STA, _INI, etc.
-For these cases, it is far simpler to dynamically install a single
-control method rather than override the entire DSDT, because kernel
-rebuild/reboot is not needed and test result can be got in minutes.
-
-Note: Only ACPI METHOD can be overridden, any other object types like
- "Device", "OperationRegion", are not recognized.
-Note: The same ACPI control method can be overridden for many times,
- and it's always the latest one that used by Linux/kernel.
-Note: To get the ACPI debug object output (Store (AAAA, Debug)),
- please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".
-
-1. override an existing method
- a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
- just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
- b) disassemble the table by running "iasl -d dsdt.dat".
- c) rewrite the ASL code of the method and save it in a new file,
- d) package the new file (psr.asl) to an ACPI table format.
- Here is an example of a customized \_SB._AC._PSR method,
-
- DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
- {
- External (ACON)
-
- Method (\_SB_.AC._PSR, 0, NotSerialized)
- {
- Store ("In AC _PSR", Debug)
- Return (ACON)
- }
- }
- Note that the full pathname of the method in ACPI namespace
- should be used.
- And remember to use "External" to declare external objects.
- e) assemble the file to generate the AML code of the method.
- e.g. "iasl psr.asl" (psr.aml is generated as a result)
- f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
- g) override the old method via the debugfs by running
- "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
-
-2. insert a new method
- This is easier than overriding an existing method.
- We just need to create the ASL code of the method we want to
- insert and then follow the step c) ~ g) in section 1.
-
-3. undo your changes
- The "undo" operation is not supported for a new inserted method
- right now, i.e. we can not remove a method currently.
- For an overrided method, in order to undo your changes, please
- save a copy of the method original ASL code in step c) section 1,
- and redo step c) ~ g) to override the method with the original one.
-
-
-Note: We can use a kernel with multiple custom ACPI method running,
- But each individual write to debugfs can implement a SINGLE
- method override. i.e. if we want to insert/override multiple
- ACPI methods, we need to redo step c) ~ g) for multiple times.
-
-Note: Be aware that root can mis-use this driver to modify arbitrary
- memory and gain additional rights, if root's privileges got
- restricted (for example if root is not allowed to load additional
- modules after boot).
diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
deleted file mode 100644
index f6efb1ea559a..000000000000
--- a/Documentation/acpi/method-tracing.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-/sys/module/acpi/parameters/:
-
-trace_method_name
- The AML method name that the user wants to trace
-
-trace_debug_layer
- The temporary debug_layer used when tracing the method.
- Using 0xffffffff by default if it is 0.
-
-trace_debug_level
- The temporary debug_level used when tracing the method.
- Using 0x00ffffff by default if it is 0.
-
-trace_state
- The status of the tracing feature.
-
- "enabled" means this feature is enabled
- and the AML method is traced every time it's executed.
-
- "1" means this feature is enabled and the AML method
- will only be traced during the next execution.
-
- "disabled" means this feature is disabled.
- Users can enable/disable this debug tracing feature by
- "echo string > /sys/module/acpi/parameters/trace_state".
- "string" should be one of "enable", "disable" and "1".
diff --git a/Documentation/acpi/namespace.txt b/Documentation/acpi/namespace.txt
deleted file mode 100644
index 1860cb3865c6..000000000000
--- a/Documentation/acpi/namespace.txt
+++ /dev/null
@@ -1,388 +0,0 @@
-ACPI Device Tree - Representation of ACPI Namespace
-
-Copyright (C) 2013, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-Abstract:
-
-The Linux ACPI subsystem converts ACPI namespace objects into a Linux
-device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
-receiving ACPI hotplug notification events. For each device object in this
-hierarchy there is a corresponding symbolic link in the
-/sys/bus/acpi/devices.
-This document illustrates the structure of the ACPI device tree.
-
-
-Credit:
-
-Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
-Wysocki <rafael.j.wysocki@intel.com>.
-
-
-1. ACPI Definition Blocks
-
- The ACPI firmware sets up RSDP (Root System Description Pointer) in the
- system memory address space pointing to the XSDT (Extended System
- Description Table). The XSDT always points to the FADT (Fixed ACPI
- Description Table) using its first entry, the data within the FADT
- includes various fixed-length entries that describe fixed ACPI features
- of the hardware. The FADT contains a pointer to the DSDT
- (Differentiated System Descripition Table). The XSDT also contains
- entries pointing to possibly multiple SSDTs (Secondary System
- Description Table).
-
- The DSDT and SSDT data is organized in data structures called definition
- blocks that contain definitions of various objects, including ACPI
- control methods, encoded in AML (ACPI Machine Language). The data block
- of the DSDT along with the contents of SSDTs represents a hierarchical
- data structure called the ACPI namespace whose topology reflects the
- structure of the underlying hardware platform.
-
- The relationships between ACPI System Definition Tables described above
- are illustrated in the following diagram.
-
- +---------+ +-------+ +--------+ +------------------------+
- | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
- +---------+ | +-------+ | +--------+ +-|->| DSDT | |
- | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
- +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
- | Pointer |-+ | ..... | | ...... | | +-------------------+ |
- +---------+ +-------+ +--------+ | +-------------------+ |
- | Entry |------------------|->| SSDT | |
- +- - - -+ | +-------------------| |
- | Entry | - - - - - - - -+ | | Definition Blocks | |
- +- - - -+ | | +-------------------+ |
- | | +- - - - - - - - - -+ |
- +-|->| SSDT | |
- | +-------------------+ |
- | | Definition Blocks | |
- | +- - - - - - - - - -+ |
- +------------------------+
- |
- OSPM Loading |
- \|/
- +----------------+
- | ACPI Namespace |
- +----------------+
-
- Figure 1. ACPI Definition Blocks
-
- NOTE: RSDP can also contain a pointer to the RSDT (Root System
- Description Table). Platforms provide RSDT to enable
- compatibility with ACPI 1.0 operating systems. The OS is expected
- to use XSDT, if present.
-
-
-2. Example ACPI Namespace
-
- All definition blocks are loaded into a single namespace. The namespace
- is a hierarchy of objects identified by names and paths.
- The following naming conventions apply to object names in the ACPI
- namespace:
- 1. All names are 32 bits long.
- 2. The first byte of a name must be one of 'A' - 'Z', '_'.
- 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
- - '9', '_'.
- 4. Names starting with '_' are reserved by the ACPI specification.
- 5. The '\' symbol represents the root of the namespace (i.e. names
- prepended with '\' are relative to the namespace root).
- 6. The '^' symbol represents the parent of the current namespace node
- (i.e. names prepended with '^' are relative to the parent of the
- current namespace node).
-
- The figure below shows an example ACPI namespace.
-
- +------+
- | \ | Root
- +------+
- |
- | +------+
- +-| _PR | Scope(_PR): the processor namespace
- | +------+
- | |
- | | +------+
- | +-| CPU0 | Processor(CPU0): the first processor
- | +------+
- |
- | +------+
- +-| _SB | Scope(_SB): the system bus namespace
- | +------+
- | |
- | | +------+
- | +-| LID0 | Device(LID0); the lid device
- | | +------+
- | | |
- | | | +------+
- | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID
- | | | +------+
- | | |
- | | | +------+
- | | +-| _STA | Method(_STA): the status control method
- | | +------+
- | |
- | | +------+
- | +-| PCI0 | Device(PCI0); the PCI root bridge
- | +------+
- | |
- | | +------+
- | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID
- | | +------+
- | |
- | | +------+
- | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID
- | | +------+
- | |
- | | +------+
- | +-| RP03 | Scope(RP03): the PCI0 power scope
- | | +------+
- | | |
- | | | +------+
- | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource
- | | +------+
- | |
- | | +------+
- | +-| GFX0 | Device(GFX0): the graphics adapter
- | +------+
- | |
- | | +------+
- | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address
- | | +------+
- | |
- | | +------+
- | +-| DD01 | Device(DD01): the LCD output device
- | +------+
- | |
- | | +------+
- | +-| _BCL | Method(_BCL): the backlight control method
- | +------+
- |
- | +------+
- +-| _TZ | Scope(_TZ): the thermal zone namespace
- | +------+
- | |
- | | +------+
- | +-| FN00 | PowerResource(FN00): the FAN0 power resource
- | | +------+
- | |
- | | +------+
- | +-| FAN0 | Device(FAN0): the FAN0 cooling device
- | | +------+
- | | |
- | | | +------+
- | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID
- | | +------+
- | |
- | | +------+
- | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone
- | +------+
- |
- | +------+
- +-| _GPE | Scope(_GPE): the GPE namespace
- +------+
-
- Figure 2. Example ACPI Namespace
-
-
-3. Linux ACPI Device Objects
-
- The Linux kernel's core ACPI subsystem creates struct acpi_device
- objects for ACPI namespace objects representing devices, power resources
- processors, thermal zones. Those objects are exported to user space via
- sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
- format of their names is <bus_id:instance>, where 'bus_id' refers to the
- ACPI namespace representation of the given object and 'instance' is used
- for distinguishing different object of the same 'bus_id' (it is
- two-digit decimal representation of an unsigned integer).
-
- The value of 'bus_id' depends on the type of the object whose name it is
- part of as listed in the table below.
-
- +---+-----------------+-------+----------+
- | | Object/Feature | Table | bus_id |
- +---+-----------------+-------+----------+
- | N | Root | xSDT | LNXSYSTM |
- +---+-----------------+-------+----------+
- | N | Device | xSDT | _HID |
- +---+-----------------+-------+----------+
- | N | Processor | xSDT | LNXCPU |
- +---+-----------------+-------+----------+
- | N | ThermalZone | xSDT | LNXTHERM |
- +---+-----------------+-------+----------+
- | N | PowerResource | xSDT | LNXPOWER |
- +---+-----------------+-------+----------+
- | N | Other Devices | xSDT | device |
- +---+-----------------+-------+----------+
- | F | PWR_BUTTON | FADT | LNXPWRBN |
- +---+-----------------+-------+----------+
- | F | SLP_BUTTON | FADT | LNXSLPBN |
- +---+-----------------+-------+----------+
- | M | Video Extension | xSDT | LNXVIDEO |
- +---+-----------------+-------+----------+
- | M | ATA Controller | xSDT | LNXIOBAY |
- +---+-----------------+-------+----------+
- | M | Docking Station | xSDT | LNXDOCK |
- +---+-----------------+-------+----------+
-
- Table 1. ACPI Namespace Objects Mapping
-
- The following rules apply when creating struct acpi_device objects on
- the basis of the contents of ACPI System Description Tables (as
- indicated by the letter in the first column and the notation in the
- second column of the table above):
- N:
- The object's source is an ACPI namespace node (as indicated by the
- named object's type in the second column). In that case the object's
- directory in sysfs will contain the 'path' attribute whose value is
- the full path to the node from the namespace root.
- F:
- The struct acpi_device object is created for a fixed hardware
- feature (as indicated by the fixed feature flag's name in the second
- column), so its sysfs directory will not contain the 'path'
- attribute.
- M:
- The struct acpi_device object is created for an ACPI namespace node
- with specific control methods (as indicated by the ACPI defined
- device's type in the second column). The 'path' attribute containing
- its namespace path will be present in its sysfs directory. For
- example, if the _BCL method is present for an ACPI namespace node, a
- struct acpi_device object with LNXVIDEO 'bus_id' will be created for
- it.
-
- The third column of the above table indicates which ACPI System
- Description Tables contain information used for the creation of the
- struct acpi_device objects represented by the given row (xSDT means DSDT
- or SSDT).
-
- The forth column of the above table indicates the 'bus_id' generation
- rule of the struct acpi_device object:
- _HID:
- _HID in the last column of the table means that the object's bus_id
- is derived from the _HID/_CID identification objects present under
- the corresponding ACPI namespace node. The object's sysfs directory
- will then contain the 'hid' and 'modalias' attributes that can be
- used to retrieve the _HID and _CIDs of that object.
- LNXxxxxx:
- The 'modalias' attribute is also present for struct acpi_device
- objects having bus_id of the "LNXxxxxx" form (pseudo devices), in
- which cases it contains the bus_id string itself.
- device:
- 'device' in the last column of the table indicates that the object's
- bus_id cannot be determined from _HID/_CID of the corresponding
- ACPI namespace node, although that object represents a device (for
- example, it may be a PCI device with _ADR defined and without _HID
- or _CID). In that case the string 'device' will be used as the
- object's bus_id.
-
-
-4. Linux ACPI Physical Device Glue
-
- ACPI device (i.e. struct acpi_device) objects may be linked to other
- objects in the Linux' device hierarchy that represent "physical" devices
- (for example, devices on the PCI bus). If that happens, it means that
- the ACPI device object is a "companion" of a device otherwise
- represented in a different way and is used (1) to provide configuration
- information on that device which cannot be obtained by other means and
- (2) to do specific things to the device with the help of its ACPI
- control methods. One ACPI device object may be linked this way to
- multiple "physical" devices.
-
- If an ACPI device object is linked to a "physical" device, its sysfs
- directory contains the "physical_node" symbolic link to the sysfs
- directory of the target device object. In turn, the target device's
- sysfs directory will then contain the "firmware_node" symbolic link to
- the sysfs directory of the companion ACPI device object.
- The linking mechanism relies on device identification provided by the
- ACPI namespace. For example, if there's an ACPI namespace object
- representing a PCI device (i.e. a device object under an ACPI namespace
- object representing a PCI bridge) whose _ADR returns 0x00020000 and the
- bus number of the parent PCI bridge is 0, the sysfs directory
- representing the struct acpi_device object created for that ACPI
- namespace object will contain the 'physical_node' symbolic link to the
- /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
- corresponding PCI device.
-
- The linking mechanism is generally bus-specific. The core of its
- implementation is located in the drivers/acpi/glue.c file, but there are
- complementary parts depending on the bus types in question located
- elsewhere. For example, the PCI-specific part of it is located in
- drivers/pci/pci-acpi.c.
-
-
-5. Example Linux ACPI Device Tree
-
- The sysfs hierarchy of struct acpi_device objects corresponding to the
- example ACPI namespace illustrated in Figure 2 with the addition of
- fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
-
- +--------------+---+-----------------+
- | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
- +--------------+---+-----------------+
- |
- | +-------------+-----+----------------+
- +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
- | +-------------+-----+----------------+
- |
- | +-------------+-----+----------------+
- +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
- | +-------------+-----+----------------+
- |
- | +-----------+------------+--------------+
- +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: |
- | +-----------+------------+--------------+
- |
- | +-------------+-------+----------------+
- +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: |
- | +-------------+-------+----------------+
- | |
- | | +- - - - - - - +- - - - - - +- - - - - - - -+
- | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: |
- | | +- - - - - - - +- - - - - - +- - - - - - - -+
- | |
- | | +------------+------------+-----------------------+
- | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: |
- | +------------+------------+-----------------------+
- | |
- | | +-----------+-----------------+-----+
- | +-| device:00 | \_SB_.PCI0.RP03 | N/A |
- | | +-----------+-----------------+-----+
- | | |
- | | | +-------------+----------------------+----------------+
- | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: |
- | | +-------------+----------------------+----------------+
- | |
- | | +-------------+-----------------+----------------+
- | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: |
- | +-------------+-----------------+----------------+
- | |
- | | +-----------+-----------------+-----+
- | +-| device:01 | \_SB_.PCI0.DD01 | N/A |
- | +-----------+-----------------+-----+
- |
- | +-------------+-------+----------------+
- +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: |
- +-------------+-------+----------------+
- |
- | +-------------+------------+----------------+
- +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: |
- | +-------------+------------+----------------+
- |
- | +------------+------------+---------------+
- +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: |
- | +------------+------------+---------------+
- |
- | +-------------+------------+----------------+
- +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: |
- +-------------+------------+----------------+
-
- Figure 3. Example Linux ACPI Device Tree
-
- NOTE: Each node is represented as "object/path/modalias", where:
- 1. 'object' is the name of the object's directory in sysfs.
- 2. 'path' is the ACPI namespace path of the corresponding
- ACPI namespace object, as returned by the object's 'path'
- sysfs attribute.
- 3. 'modalias' is the value of the object's 'modalias' sysfs
- attribute (as described earlier in this document).
- NOTE: N/A indicates the device object does not have the 'path' or the
- 'modalias' attribute.
diff --git a/Documentation/acpi/scan_handlers.txt b/Documentation/acpi/scan_handlers.txt
deleted file mode 100644
index 3246ccf15992..000000000000
--- a/Documentation/acpi/scan_handlers.txt
+++ /dev/null
@@ -1,77 +0,0 @@
-ACPI Scan Handlers
-
-Copyright (C) 2012, Intel Corporation
-Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
-
-During system initialization and ACPI-based device hot-add, the ACPI namespace
-is scanned in search of device objects that generally represent various pieces
-of hardware. This causes a struct acpi_device object to be created and
-registered with the driver core for every device object in the ACPI namespace
-and the hierarchy of those struct acpi_device objects reflects the namespace
-layout (i.e. parent device objects in the namespace are represented by parent
-struct acpi_device objects and analogously for their children). Those struct
-acpi_device objects are referred to as "device nodes" in what follows, but they
-should not be confused with struct device_node objects used by the Device Trees
-parsing code (although their role is analogous to the role of those objects).
-
-During ACPI-based device hot-remove device nodes representing pieces of hardware
-being removed are unregistered and deleted.
-
-The core ACPI namespace scanning code in drivers/acpi/scan.c carries out basic
-initialization of device nodes, such as retrieving common configuration
-information from the device objects represented by them and populating them with
-appropriate data, but some of them require additional handling after they have
-been registered. For example, if the given device node represents a PCI host
-bridge, its registration should cause the PCI bus under that bridge to be
-enumerated and PCI devices on that bus to be registered with the driver core.
-Similarly, if the device node represents a PCI interrupt link, it is necessary
-to configure that link so that the kernel can use it.
-
-Those additional configuration tasks usually depend on the type of the hardware
-component represented by the given device node which can be determined on the
-basis of the device node's hardware ID (HID). They are performed by objects
-called ACPI scan handlers represented by the following structure:
-
-struct acpi_scan_handler {
- const struct acpi_device_id *ids;
- struct list_head list_node;
- int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
- void (*detach)(struct acpi_device *dev);
-};
-
-where ids is the list of IDs of device nodes the given handler is supposed to
-take care of, list_node is the hook to the global list of ACPI scan handlers
-maintained by the ACPI core and the .attach() and .detach() callbacks are
-executed, respectively, after registration of new device nodes and before
-unregistration of device nodes the handler attached to previously.
-
-The namespace scanning function, acpi_bus_scan(), first registers all of the
-device nodes in the given namespace scope with the driver core. Then, it tries
-to match a scan handler against each of them using the ids arrays of the
-available scan handlers. If a matching scan handler is found, its .attach()
-callback is executed for the given device node. If that callback returns 1,
-that means that the handler has claimed the device node and is now responsible
-for carrying out any additional configuration tasks related to it. It also will
-be responsible for preparing the device node for unregistration in that case.
-The device node's handler field is then populated with the address of the scan
-handler that has claimed it.
-
-If the .attach() callback returns 0, it means that the device node is not
-interesting to the given scan handler and may be matched against the next scan
-handler in the list. If it returns a (negative) error code, that means that
-the namespace scan should be terminated due to a serious error. The error code
-returned should then reflect the type of the error.
-
-The namespace trimming function, acpi_bus_trim(), first executes .detach()
-callbacks from the scan handlers of all device nodes in the given namespace
-scope (if they have scan handlers). Next, it unregisters all of the device
-nodes in that scope.
-
-ACPI scan handlers can be added to the list maintained by the ACPI core with the
-help of the acpi_scan_add_handler() function taking a pointer to the new scan
-handler as an argument. The order in which scan handlers are added to the list
-is the order in which they are matched against device nodes during namespace
-scans.
-
-All scan handles must be added to the list before acpi_bus_scan() is run for the
-first time and they cannot be removed from it.
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt
deleted file mode 100644
index 78b32ac02466..000000000000
--- a/Documentation/acpi/video_extension.txt
+++ /dev/null
@@ -1,106 +0,0 @@
-ACPI video extensions
-~~~~~~~~~~~~~~~~~~~~~
-
-This driver implement the ACPI Extensions For Display Adapters for
-integrated graphics devices on motherboard, as specified in ACPI 2.0
-Specification, Appendix B, allowing to perform some basic control like
-defining the video POST device, retrieving EDID information or to
-setup a video output, etc. Note that this is an ref. implementation
-only. It may or may not work for your integrated video device.
-
-The ACPI video driver does 3 things regarding backlight control:
-
-1 Export a sysfs interface for user space to control backlight level
-
-If the ACPI table has a video device, and acpi_backlight=vendor kernel
-command line is not present, the driver will register a backlight device
-and set the required backlight operation structure for it for the sysfs
-interface control. For every registered class device, there will be a
-directory named acpi_videoX under /sys/class/backlight.
-
-The backlight sysfs interface has a standard definition here:
-Documentation/ABI/stable/sysfs-class-backlight.
-
-And what ACPI video driver does is:
-actual_brightness: on read, control method _BQC will be evaluated to
-get the brightness level the firmware thinks it is at;
-bl_power: not implemented, will set the current brightness instead;
-brightness: on write, control method _BCM will run to set the requested
-brightness level;
-max_brightness: Derived from the _BCL package(see below);
-type: firmware
-
-Note that ACPI video backlight driver will always use index for
-brightness, actual_brightness and max_brightness. So if we have
-the following _BCL package:
-
-Method (_BCL, 0, NotSerialized)
-{
- Return (Package (0x0C)
- {
- 0x64,
- 0x32,
- 0x0A,
- 0x14,
- 0x1E,
- 0x28,
- 0x32,
- 0x3C,
- 0x46,
- 0x50,
- 0x5A,
- 0x64
- })
-}
-
-The first two levels are for when laptop are on AC or on battery and are
-not used by Linux currently. The remaining 10 levels are supported levels
-that we can choose from. The applicable index values are from 0 (that
-corresponds to the 0x0A brightness value) to 9 (that corresponds to the
-0x64 brightness value) inclusive. Each of those index values is regarded
-as a "brightness level" indicator. Thus from the user space perspective
-the range of available brightness levels is from 0 to 9 (max_brightness)
-inclusive.
-
-2 Notify user space about hotkey event
-
-There are generally two cases for hotkey event reporting:
-i) For some laptops, when user presses the hotkey, a scancode will be
- generated and sent to user space through the input device created by
- the keyboard driver as a key type input event, with proper remap, the
- following key code will appear to user space:
-
- EV_KEY, KEY_BRIGHTNESSUP
- EV_KEY, KEY_BRIGHTNESSDOWN
- etc.
-
-For this case, ACPI video driver does not need to do anything(actually,
-it doesn't even know this happened).
-
-ii) For some laptops, the press of the hotkey will not generate the
- scancode, instead, firmware will notify the video device ACPI node
- about the event. The event value is defined in the ACPI spec. ACPI
- video driver will generate an key type input event according to the
- notify value it received and send the event to user space through the
- input device it created:
-
- event keycode
- 0x86 KEY_BRIGHTNESSUP
- 0x87 KEY_BRIGHTNESSDOWN
- etc.
-
-so this would lead to the same effect as case i) now.
-
-Once user space tool receives this event, it can modify the backlight
-level through the sysfs interface.
-
-3 Change backlight level in the kernel
-
-This works for machines covered by case ii) in Section 2. Once the driver
-received a notification, it will set the backlight level accordingly. This does
-not affect the sending of event to user space, they are always sent to user
-space regardless of whether or not the video module controls the backlight level
-directly. This behaviour can be controlled through the brightness_switch_enabled
-module parameter as documented in kernel-parameters.txt. It is recommended to
-disable this behaviour once a GUI environment starts up and wants to have full
-control of the backlight level.
diff --git a/Documentation/admin-guide/LSM/LoadPin.rst b/Documentation/admin-guide/LSM/LoadPin.rst
new file mode 100644
index 000000000000..dd3ca68b5df1
--- /dev/null
+++ b/Documentation/admin-guide/LSM/LoadPin.rst
@@ -0,0 +1,31 @@
+=======
+LoadPin
+=======
+
+LoadPin is a Linux Security Module that ensures all kernel-loaded files
+(modules, firmware, etc) all originate from the same filesystem, with
+the expectation that such a filesystem is backed by a read-only device
+such as dm-verity or CDROM. This allows systems that have a verified
+and/or unchangeable filesystem to enforce module and firmware loading
+restrictions without needing to sign the files individually.
+
+The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and
+can be controlled at boot-time with the kernel command line option
+"``loadpin.enforce``". By default, it is enabled, but can be disabled at
+boot ("``loadpin.enforce=0``").
+
+LoadPin starts pinning when it sees the first file loaded. If the
+block device backing the filesystem is not read-only, a sysctl is
+created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having
+a mutable filesystem means pinning is mutable too, but having the
+sysctl allows for easy testing on systems with a mutable filesystem.)
+
+It's also possible to exclude specific file types from LoadPin using kernel
+command line option "``loadpin.exclude``". By default, all files are
+included, but they can be excluded using kernel command line option such
+as "``loadpin.exclude=kernel-module,kexec-image``". This allows to use
+different mechanisms such as ``CONFIG_MODULE_SIG`` and
+``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while
+still use LoadPin to protect the integrity of other files kernel loads. The
+full list of valid file types can be found in ``kernel_read_file_str``
+defined in ``include/linux/kernel_read_file.h``.
diff --git a/Documentation/admin-guide/LSM/SELinux.rst b/Documentation/admin-guide/LSM/SELinux.rst
new file mode 100644
index 000000000000..cdd65164ca96
--- /dev/null
+++ b/Documentation/admin-guide/LSM/SELinux.rst
@@ -0,0 +1,44 @@
+=======
+SELinux
+=======
+
+Information about the SELinux kernel subsystem can be found at the
+following links:
+
+ https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/selinux.git/tree/README.md
+
+ https://github.com/selinuxproject/selinux-kernel/wiki
+
+Information about the SELinux userspace can be found at:
+
+ https://github.com/SELinuxProject/selinux/wiki
+
+If you want to use SELinux, chances are you will want
+to use the distro-provided policies, or install the
+latest reference policy release from
+
+ https://github.com/SELinuxProject/refpolicy
+
+However, if you want to install a dummy policy for
+testing, you can do using ``mdp`` provided under
+scripts/selinux. Note that this requires the selinux
+userspace to be installed - in particular you will
+need checkpolicy to compile a kernel, and setfiles and
+fixfiles to label the filesystem.
+
+ 1. Compile the kernel with selinux enabled.
+ 2. Type ``make`` to compile ``mdp``.
+ 3. Make sure that you are not running with
+ SELinux enabled and a real policy. If
+ you are, reboot with selinux disabled
+ before continuing.
+ 4. Run install_policy.sh::
+
+ cd scripts/selinux
+ sh install_policy.sh
+
+Step 4 will create a new dummy policy valid for your
+kernel, with a single selinux user, role, and type.
+It will compile the policy, will set your ``SELINUXTYPE`` to
+``dummy`` in ``/etc/selinux/config``, install the compiled policy
+as ``dummy``, and relabel your filesystem.
diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst
new file mode 100644
index 000000000000..6d439c987563
--- /dev/null
+++ b/Documentation/admin-guide/LSM/SafeSetID.rst
@@ -0,0 +1,118 @@
+=========
+SafeSetID
+=========
+SafeSetID is an LSM module that gates the setid family of syscalls to restrict
+UID/GID transitions from a given UID/GID to only those approved by a
+system-wide allowlist. These restrictions also prohibit the given UIDs/GIDs
+from obtaining auxiliary privileges associated with CAP_SET{U/G}ID, such as
+allowing a user to set up user namespace UID/GID mappings.
+
+
+Background
+==========
+In absence of file capabilities, processes spawned on a Linux system that need
+to switch to a different user must be spawned with CAP_SETUID privileges.
+CAP_SETUID is granted to programs running as root or those running as a non-root
+user that have been explicitly given the CAP_SETUID runtime capability. It is
+often preferable to use Linux runtime capabilities rather than file
+capabilities, since using file capabilities to run a program with elevated
+privileges opens up possible security holes since any user with access to the
+file can exec() that program to gain the elevated privileges.
+
+While it is possible to implement a tree of processes by giving full
+CAP_SET{U/G}ID capabilities, this is often at odds with the goals of running a
+tree of processes under non-root user(s) in the first place. Specifically,
+since CAP_SETUID allows changing to any user on the system, including the root
+user, it is an overpowered capability for what is needed in this scenario,
+especially since programs often only call setuid() to drop privileges to a
+lesser-privileged user -- not elevate privileges. Unfortunately, there is no
+generally feasible way in Linux to restrict the potential UIDs that a user can
+switch to through setuid() beyond allowing a switch to any user on the system.
+This SafeSetID LSM seeks to provide a solution for restricting setid
+capabilities in such a way.
+
+The main use case for this LSM is to allow a non-root program to transition to
+other untrusted uids without full blown CAP_SETUID capabilities. The non-root
+program would still need CAP_SETUID to do any kind of transition, but the
+additional restrictions imposed by this LSM would mean it is a "safer" version
+of CAP_SETUID since the non-root program cannot take advantage of CAP_SETUID to
+do any unapproved actions (e.g. setuid to uid 0 or create/enter new user
+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 it's undesirable to give the daemon a
+basically-root-equivalent CAP_SETUID.
+
+
+Other Approaches Considered
+===========================
+
+Solve this problem in userspace
+-------------------------------
+For candidate applications that would like to have restricted setid capabilities
+as implemented in this LSM, an alternative option would be to simply take away
+setid capabilities from the application completely and refactor the process
+spawning semantics in the application (e.g. by using a privileged helper program
+to do process spawning and UID/GID transitions). Unfortunately, there are a
+number of semantics around process spawning that would be affected by this, such
+as fork() calls where the program doesn't immediately call exec() after the
+fork(), parent processes specifying custom environment variables or command line
+args for spawned child processes, or inheritance of file handles across a
+fork()/exec(). Because of this, as solution that uses a privileged helper in
+userspace would likely be less appealing to incorporate into existing projects
+that rely on certain process-spawning semantics in Linux.
+
+Use user namespaces
+-------------------
+Another possible approach would be to run a given process tree in its own user
+namespace and give programs in the tree setid capabilities. In this way,
+programs in the tree could change to any desired UID/GID in the context of their
+own user namespace, and only approved UIDs/GIDs could be mapped back to the
+initial system user namespace, affectively preventing privilege escalation.
+Unfortunately, it is not generally feasible to use user namespaces in isolation,
+without pairing them with other namespace types, which is not always an option.
+Linux checks for capabilities based off of the user namespace that "owns" some
+entity. For example, Linux has the notion that network namespaces are owned by
+the user namespace in which they were created. A consequence of this is that
+capability checks for access to a given network namespace are done by checking
+whether a task has the given capability in the context of the user namespace
+that owns the network namespace -- not necessarily the user namespace under
+which the given task runs. Therefore spawning a process in a new user namespace
+effectively prevents it from accessing the network namespace owned by the
+initial namespace. This is a deal-breaker for any application that expects to
+retain the CAP_NET_ADMIN capability for the purpose of adjusting network
+configurations. Using user namespaces in isolation causes problems regarding
+other system interactions, including use of pid namespaces and device creation.
+
+Use an existing LSM
+-------------------
+None of the other in-tree LSMs have the capability to gate setid transitions, or
+even employ the security_task_fix_setuid hook at all. SELinux says of that hook:
+"Since setuid only affects the current process, and since the SELinux controls
+are not based on the Linux identity attributes, SELinux does not need to control
+this operation."
+
+
+Directions for use
+==================
+This LSM hooks the setid syscalls to make sure transitions are allowed if an
+applicable restriction policy is in place. Policies are configured through
+securityfs by writing to the safesetid/uid_allowlist_policy and
+safesetid/gid_allowlist_policy files at the location where securityfs is
+mounted. The format for adding a policy is '<UID>:<UID>' or '<GID>:<GID>',
+using literal numbers, and ending with a newline character such as '123:456\n'.
+Writing an empty string "" will flush the policy. Again, configuring a policy
+for a UID/GID will prevent that UID/GID from obtaining auxiliary setid
+privileges, such as allowing a user to set up user namespace UID/GID mappings.
+
+Note on GID policies and setgroups()
+====================================
+In v5.9 we are adding support for limiting CAP_SETGID privileges as was done
+previously for CAP_SETUID. However, for compatibility with common sandboxing
+related code conventions in userspace, we currently allow arbitrary
+setgroups() calls for processes with CAP_SETGID restrictions. Until we add
+support in a future release for restricting setgroups() calls, these GID
+policies add no meaningful security. setgroups() restrictions will be enforced
+once we have the policy checking code in place, which will rely on GID policy
+configuration code added in v5.9.
diff --git a/Documentation/admin-guide/LSM/Smack.rst b/Documentation/admin-guide/LSM/Smack.rst
new file mode 100644
index 000000000000..c5ed775f2d10
--- /dev/null
+++ b/Documentation/admin-guide/LSM/Smack.rst
@@ -0,0 +1,871 @@
+=====
+Smack
+=====
+
+
+ "Good for you, you've decided to clean the elevator!"
+ - The Elevator, from Dark Star
+
+Smack is the Simplified Mandatory Access Control Kernel.
+Smack is a kernel based implementation of mandatory access
+control that includes simplicity in its primary design goals.
+
+Smack is not the only Mandatory Access Control scheme
+available for Linux. Those new to Mandatory Access Control
+are encouraged to compare Smack with the other mechanisms
+available to determine which is best suited to the problem
+at hand.
+
+Smack consists of three major components:
+
+ - The kernel
+ - Basic utilities, which are helpful but not required
+ - Configuration data
+
+The kernel component of Smack is implemented as a Linux
+Security Modules (LSM) module. It requires netlabel and
+works best with file systems that support extended attributes,
+although xattr support is not strictly required.
+It is safe to run a Smack kernel under a "vanilla" distribution.
+
+Smack kernels use the CIPSO IP option. Some network
+configurations are intolerant of IP options and can impede
+access to systems that use them as Smack does.
+
+Smack is used in the Tizen operating system. Please
+go to http://wiki.tizen.org for information about how
+Smack is used in Tizen.
+
+The current git repository for Smack user space is:
+
+ git://github.com/smack-team/smack.git
+
+This should make and install on most modern distributions.
+There are five commands included in smackutil:
+
+chsmack:
+ display or set Smack extended attribute values
+
+smackctl:
+ load the Smack access rules
+
+smackaccess:
+ report if a process with one label has access
+ to an object with another
+
+These two commands are obsolete with the introduction of
+the smackfs/load2 and smackfs/cipso2 interfaces.
+
+smackload:
+ properly formats data for writing to smackfs/load
+
+smackcipso:
+ properly formats data for writing to smackfs/cipso
+
+In keeping with the intent of Smack, configuration data is
+minimal and not strictly required. The most important
+configuration step is mounting the smackfs pseudo filesystem.
+If smackutil is installed the startup script will take care
+of this, but it can be manually as well.
+
+Add this line to ``/etc/fstab``::
+
+ smackfs /sys/fs/smackfs smackfs defaults 0 0
+
+The ``/sys/fs/smackfs`` directory is created by the kernel.
+
+Smack uses extended attributes (xattrs) to store labels on filesystem
+objects. The attributes are stored in the extended attribute security
+name space. A process must have ``CAP_MAC_ADMIN`` to change any of these
+attributes.
+
+The extended attributes that Smack uses are:
+
+SMACK64
+ Used to make access control decisions. In almost all cases
+ the label given to a new filesystem object will be the label
+ of the process that created it.
+
+SMACK64EXEC
+ The Smack label of a process that execs a program file with
+ this attribute set will run with this attribute's value.
+
+SMACK64MMAP
+ Don't allow the file to be mmapped by a process whose Smack
+ label does not allow all of the access permitted to a process
+ with the label contained in this attribute. This is a very
+ specific use case for shared libraries.
+
+SMACK64TRANSMUTE
+ Can only have the value "TRUE". If this attribute is present
+ on a directory when an object is created in the directory and
+ the Smack rule (more below) that permitted the write access
+ to the directory includes the transmute ("t") mode the object
+ gets the label of the directory instead of the label of the
+ creating process. If the object being created is a directory
+ the SMACK64TRANSMUTE attribute is set as well.
+
+SMACK64IPIN
+ This attribute is only available on file descriptors for sockets.
+ Use the Smack label in this attribute for access control
+ decisions on packets being delivered to this socket.
+
+SMACK64IPOUT
+ This attribute is only available on file descriptors for sockets.
+ Use the Smack label in this attribute for access control
+ decisions on packets coming from this socket.
+
+There are multiple ways to set a Smack label on a file::
+
+ # attr -S -s SMACK64 -V "value" path
+ # chsmack -a value path
+
+A process can see the Smack label it is running with by
+reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN``
+can set the process Smack by writing there.
+
+Most Smack configuration is accomplished by writing to files
+in the smackfs filesystem. This pseudo-filesystem is mounted
+on ``/sys/fs/smackfs``.
+
+access
+ Provided for backward compatibility. The access2 interface
+ is preferred and should be used instead.
+ This interface reports whether a subject with the specified
+ Smack label has a particular access to an object with a
+ specified Smack label. Write a fixed format access rule to
+ this file. The next read will indicate whether the access
+ would be permitted. The text will be either "1" indicating
+ access, or "0" indicating denial.
+
+access2
+ This interface reports whether a subject with the specified
+ Smack label has a particular access to an object with a
+ specified Smack label. Write a long format access rule to
+ this file. The next read will indicate whether the access
+ would be permitted. The text will be either "1" indicating
+ access, or "0" indicating denial.
+
+ambient
+ This contains the Smack label applied to unlabeled network
+ packets.
+
+change-rule
+ This interface allows modification of existing access control rules.
+ The format accepted on write is::
+
+ "%s %s %s %s"
+
+ where the first string is the subject label, the second the
+ object label, the third the access to allow and the fourth the
+ access to deny. The access strings may contain only the characters
+ "rwxat-". If a rule for a given subject and object exists it will be
+ modified by enabling the permissions in the third string and disabling
+ those in the fourth string. If there is no such rule it will be
+ created using the access specified in the third and the fourth strings.
+
+cipso
+ Provided for backward compatibility. The cipso2 interface
+ is preferred and should be used instead.
+ This interface allows a specific CIPSO header to be assigned
+ to a Smack label. The format accepted on write is::
+
+ "%24s%4d%4d"["%4d"]...
+
+ The first string is a fixed Smack label. The first number is
+ the level to use. The second number is the number of categories.
+ The following numbers are the categories::
+
+ "level-3-cats-5-19 3 2 5 19"
+
+cipso2
+ This interface allows a specific CIPSO header to be assigned
+ to a Smack label. The format accepted on write is::
+
+ "%s%4d%4d"["%4d"]...
+
+ The first string is a long Smack label. The first number is
+ the level to use. The second number is the number of categories.
+ The following numbers are the categories::
+
+ "level-3-cats-5-19 3 2 5 19"
+
+direct
+ This contains the CIPSO level used for Smack direct label
+ representation in network packets.
+
+doi
+ This contains the CIPSO domain of interpretation used in
+ network packets.
+
+ipv6host
+ This interface allows specific IPv6 internet addresses to be
+ treated as single label hosts. Packets are sent to single
+ label hosts only from processes that have Smack write access
+ to the host label. All packets received from single label hosts
+ are given the specified label. The format accepted on write is::
+
+ "%h:%h:%h:%h:%h:%h:%h:%h label" or
+ "%h:%h:%h:%h:%h:%h:%h:%h/%d label".
+
+ The "::" address shortcut is not supported.
+ If label is "-DELETE" a matched entry will be deleted.
+
+load
+ Provided for backward compatibility. The load2 interface
+ is preferred and should be used instead.
+ This interface allows access control rules in addition to
+ the system defined rules to be specified. The format accepted
+ on write is::
+
+ "%24s%24s%5s"
+
+ where the first string is the subject label, the second the
+ object label, and the third the requested access. The access
+ string may contain only the characters "rwxat-", and specifies
+ which sort of access is allowed. The "-" is a placeholder for
+ permissions that are not allowed. The string "r-x--" would
+ specify read and execute access. Labels are limited to 23
+ characters in length.
+
+load2
+ This interface allows access control rules in addition to
+ the system defined rules to be specified. The format accepted
+ on write is::
+
+ "%s %s %s"
+
+ where the first string is the subject label, the second the
+ object label, and the third the requested access. The access
+ string may contain only the characters "rwxat-", and specifies
+ which sort of access is allowed. The "-" is a placeholder for
+ permissions that are not allowed. The string "r-x--" would
+ specify read and execute access.
+
+load-self
+ Provided for backward compatibility. The load-self2 interface
+ is preferred and should be used instead.
+ This interface allows process specific access rules to be
+ defined. These rules are only consulted if access would
+ otherwise be permitted, and are intended to provide additional
+ restrictions on the process. The format is the same as for
+ the load interface.
+
+load-self2
+ This interface allows process specific access rules to be
+ defined. These rules are only consulted if access would
+ otherwise be permitted, and are intended to provide additional
+ restrictions on the process. The format is the same as for
+ the load2 interface.
+
+logging
+ This contains the Smack logging state.
+
+mapped
+ This contains the CIPSO level used for Smack mapped label
+ representation in network packets.
+
+netlabel
+ This interface allows specific internet addresses to be
+ treated as single label hosts. Packets are sent to single
+ label hosts without CIPSO headers, but only from processes
+ that have Smack write access to the host label. All packets
+ received from single label hosts are given the specified
+ label. The format accepted on write is::
+
+ "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
+
+ If the label specified is "-CIPSO" the address is treated
+ as a host that supports CIPSO headers.
+
+onlycap
+ This contains labels processes must have for CAP_MAC_ADMIN
+ and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty
+ these capabilities are effective at for processes with any
+ label. The values are set by writing the desired labels, separated
+ by spaces, to the file or cleared by writing "-" to the file.
+
+ptrace
+ This is used to define the current ptrace policy
+
+ 0 - default:
+ this is the policy that relies on Smack access rules.
+ For the ``PTRACE_READ`` a subject needs to have a read access on
+ object. For the ``PTRACE_ATTACH`` a read-write access is required.
+
+ 1 - exact:
+ this is the policy that limits ``PTRACE_ATTACH``. Attach is
+ only allowed when subject's and object's labels are equal.
+ ``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``.
+
+ 2 - draconian:
+ this policy behaves like the 'exact' above with an
+ exception that it can't be overridden with ``CAP_SYS_PTRACE``.
+
+revoke-subject
+ Writing a Smack label here sets the access to '-' for all access
+ rules with that subject label.
+
+unconfined
+ If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP``
+ a process with ``CAP_MAC_ADMIN`` can write a label into this interface.
+ Thereafter, accesses that involve that label will be logged and
+ the access permitted if it wouldn't be otherwise. Note that this
+ is dangerous and can ruin the proper labeling of your system.
+ It should never be used in production.
+
+relabel-self
+ This interface contains a list of labels to which the process can
+ transition to, by writing to ``/proc/self/attr/current``.
+ Normally a process can change its own label to any legal value, but only
+ if it has ``CAP_MAC_ADMIN``. This interface allows a process without
+ ``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list.
+ A process without ``CAP_MAC_ADMIN`` can change its label only once. When it
+ does, this list will be cleared.
+ The values are set by writing the desired labels, separated
+ by spaces, to the file or cleared by writing "-" to the file.
+
+If you are using the smackload utility
+you can add access rules in ``/etc/smack/accesses``. They take the form::
+
+ subjectlabel objectlabel access
+
+access is a combination of the letters rwxatb which specify the
+kind of access permitted a subject with subjectlabel on an
+object with objectlabel. If there is no rule no access is allowed.
+
+Look for additional programs on http://schaufler-ca.com
+
+The Simplified Mandatory Access Control Kernel (Whitepaper)
+===========================================================
+
+Casey Schaufler
+casey@schaufler-ca.com
+
+Mandatory Access Control
+------------------------
+
+Computer systems employ a variety of schemes to constrain how information is
+shared among the people and services using the machine. Some of these schemes
+allow the program or user to decide what other programs or users are allowed
+access to pieces of data. These schemes are called discretionary access
+control mechanisms because the access control is specified at the discretion
+of the user. Other schemes do not leave the decision regarding what a user or
+program can access up to users or programs. These schemes are called mandatory
+access control mechanisms because you don't have a choice regarding the users
+or programs that have access to pieces of data.
+
+Bell & LaPadula
+---------------
+
+From the middle of the 1980's until the turn of the century Mandatory Access
+Control (MAC) was very closely associated with the Bell & LaPadula security
+model, a mathematical description of the United States Department of Defense
+policy for marking paper documents. MAC in this form enjoyed a following
+within the Capital Beltway and Scandinavian supercomputer centers but was
+often sited as failing to address general needs.
+
+Domain Type Enforcement
+-----------------------
+
+Around the turn of the century Domain Type Enforcement (DTE) became popular.
+This scheme organizes users, programs, and data into domains that are
+protected from each other. This scheme has been widely deployed as a component
+of popular Linux distributions. The administrative overhead required to
+maintain this scheme and the detailed understanding of the whole system
+necessary to provide a secure domain mapping leads to the scheme being
+disabled or used in limited ways in the majority of cases.
+
+Smack
+-----
+
+Smack is a Mandatory Access Control mechanism designed to provide useful MAC
+while avoiding the pitfalls of its predecessors. The limitations of Bell &
+LaPadula are addressed by providing a scheme whereby access can be controlled
+according to the requirements of the system and its purpose rather than those
+imposed by an arcane government policy. The complexity of Domain Type
+Enforcement and avoided by defining access controls in terms of the access
+modes already in use.
+
+Smack Terminology
+-----------------
+
+The jargon used to talk about Smack will be familiar to those who have dealt
+with other MAC systems and shouldn't be too difficult for the uninitiated to
+pick up. There are four terms that are used in a specific way and that are
+especially important:
+
+ Subject:
+ A subject is an active entity on the computer system.
+ On Smack a subject is a task, which is in turn the basic unit
+ of execution.
+
+ Object:
+ An object is a passive entity on the computer system.
+ On Smack files of all types, IPC, and tasks can be objects.
+
+ Access:
+ Any attempt by a subject to put information into or get
+ information from an object is an access.
+
+ Label:
+ Data that identifies the Mandatory Access Control
+ characteristics of a subject or an object.
+
+These definitions are consistent with the traditional use in the security
+community. There are also some terms from Linux that are likely to crop up:
+
+ Capability:
+ A task that possesses a capability has permission to
+ violate an aspect of the system security policy, as identified by
+ the specific capability. A task that possesses one or more
+ capabilities is a privileged task, whereas a task with no
+ capabilities is an unprivileged task.
+
+ Privilege:
+ A task that is allowed to violate the system security
+ policy is said to have privilege. As of this writing a task can
+ have privilege either by possessing capabilities or by having an
+ effective user of root.
+
+Smack Basics
+------------
+
+Smack is an extension to a Linux system. It enforces additional restrictions
+on what subjects can access which objects, based on the labels attached to
+each of the subject and the object.
+
+Labels
+~~~~~~
+
+Smack labels are ASCII character strings. They can be up to 255 characters
+long, but keeping them to twenty-three characters is recommended.
+Single character labels using special characters, that being anything
+other than a letter or digit, are reserved for use by the Smack development
+team. Smack labels are unstructured, case sensitive, and the only operation
+ever performed on them is comparison for equality. Smack labels cannot
+contain unprintable characters, the "/" (slash), the "\" (backslash), the "'"
+(quote) and '"' (double-quote) characters.
+Smack labels cannot begin with a '-'. This is reserved for special options.
+
+There are some predefined labels::
+
+ _ Pronounced "floor", a single underscore character.
+ ^ Pronounced "hat", a single circumflex character.
+ * Pronounced "star", a single asterisk character.
+ ? Pronounced "huh", a single question mark character.
+ @ Pronounced "web", a single at sign character.
+
+Every task on a Smack system is assigned a label. The Smack label
+of a process will usually be assigned by the system initialization
+mechanism.
+
+Access Rules
+~~~~~~~~~~~~
+
+Smack uses the traditional access modes of Linux. These modes are read,
+execute, write, and occasionally append. There are a few cases where the
+access mode may not be obvious. These include:
+
+ Signals:
+ A signal is a write operation from the subject task to
+ the object task.
+
+ Internet Domain IPC:
+ Transmission of a packet is considered a
+ write operation from the source task to the destination task.
+
+Smack restricts access based on the label attached to a subject and the label
+attached to the object it is trying to access. The rules enforced are, in
+order:
+
+ 1. Any access requested by a task labeled "*" is denied.
+ 2. A read or execute access requested by a task labeled "^"
+ is permitted.
+ 3. A read or execute access requested on an object labeled "_"
+ is permitted.
+ 4. Any access requested on an object labeled "*" is permitted.
+ 5. Any access requested by a task on an object with the same
+ label is permitted.
+ 6. Any access requested that is explicitly defined in the loaded
+ rule set is permitted.
+ 7. Any other access is denied.
+
+Smack Access Rules
+~~~~~~~~~~~~~~~~~~
+
+With the isolation provided by Smack access separation is simple. There are
+many interesting cases where limited access by subjects to objects with
+different labels is desired. One example is the familiar spy model of
+sensitivity, where a scientist working on a highly classified project would be
+able to read documents of lower classifications and anything she writes will
+be "born" highly classified. To accommodate such schemes Smack includes a
+mechanism for specifying rules allowing access between labels.
+
+Access Rule Format
+~~~~~~~~~~~~~~~~~~
+
+The format of an access rule is::
+
+ subject-label object-label access
+
+Where subject-label is the Smack label of the task, object-label is the Smack
+label of the thing being accessed, and access is a string specifying the sort
+of access allowed. The access specification is searched for letters that
+describe access modes:
+
+ a: indicates that append access should be granted.
+ r: indicates that read access should be granted.
+ w: indicates that write access should be granted.
+ x: indicates that execute access should be granted.
+ t: indicates that the rule requests transmutation.
+ b: indicates that the rule should be reported for bring-up.
+
+Uppercase values for the specification letters are allowed as well.
+Access mode specifications can be in any order. Examples of acceptable rules
+are::
+
+ TopSecret Secret rx
+ Secret Unclass R
+ Manager Game x
+ User HR w
+ Snap Crackle rwxatb
+ New Old rRrRr
+ Closed Off -
+
+Examples of unacceptable rules are::
+
+ Top Secret Secret rx
+ Ace Ace r
+ Odd spells waxbeans
+
+Spaces are not allowed in labels. Since a subject always has access to files
+with the same label specifying a rule for that case is pointless. Only
+valid letters (rwxatbRWXATB) and the dash ('-') character are allowed in
+access specifications. The dash is a placeholder, so "a-r" is the same
+as "ar". A lone dash is used to specify that no access should be allowed.
+
+Applying Access Rules
+~~~~~~~~~~~~~~~~~~~~~
+
+The developers of Linux rarely define new sorts of things, usually importing
+schemes and concepts from other systems. Most often, the other systems are
+variants of Unix. Unix has many endearing properties, but consistency of
+access control models is not one of them. Smack strives to treat accesses as
+uniformly as is sensible while keeping with the spirit of the underlying
+mechanism.
+
+File system objects including files, directories, named pipes, symbolic links,
+and devices require access permissions that closely match those used by mode
+bit access. To open a file for reading read access is required on the file. To
+search a directory requires execute access. Creating a file with write access
+requires both read and write access on the containing directory. Deleting a
+file requires read and write access to the file and to the containing
+directory. It is possible that a user may be able to see that a file exists
+but not any of its attributes by the circumstance of having read access to the
+containing directory but not to the differently labeled file. This is an
+artifact of the file name being data in the directory, not a part of the file.
+
+If a directory is marked as transmuting (SMACK64TRANSMUTE=TRUE) and the
+access rule that allows a process to create an object in that directory
+includes 't' access the label assigned to the new object will be that
+of the directory, not the creating process. This makes it much easier
+for two processes with different labels to share data without granting
+access to all of their files.
+
+IPC objects, message queues, semaphore sets, and memory segments exist in flat
+namespaces and access requests are only required to match the object in
+question.
+
+Process objects reflect tasks on the system and the Smack label used to access
+them is the same Smack label that the task would use for its own access
+attempts. Sending a signal via the kill() system call is a write operation
+from the signaler to the recipient. Debugging a process requires both reading
+and writing. Creating a new task is an internal operation that results in two
+tasks with identical Smack labels and requires no access checks.
+
+Sockets are data structures attached to processes and sending a packet from
+one process to another requires that the sender have write access to the
+receiver. The receiver is not required to have read access to the sender.
+
+Setting Access Rules
+~~~~~~~~~~~~~~~~~~~~
+
+The configuration file /etc/smack/accesses contains the rules to be set at
+system startup. The contents are written to the special file
+/sys/fs/smackfs/load2. Rules can be added at any time and take effect
+immediately. For any pair of subject and object labels there can be only
+one rule, with the most recently specified overriding any earlier
+specification.
+
+Task Attribute
+~~~~~~~~~~~~~~
+
+The Smack label of a process can be read from ``/proc/<pid>/attr/current``. A
+process can read its own Smack label from ``/proc/self/attr/current``. A
+privileged process can change its own Smack label by writing to
+``/proc/self/attr/current`` but not the label of another process.
+
+Format of writing is : only the label or the label followed by one of the
+3 trailers: ``\n`` (by common agreement for ``/proc/...`` interfaces),
+``\0`` (because some applications incorrectly include it),
+``\n\0`` (because we think some applications may incorrectly include it).
+
+File Attribute
+~~~~~~~~~~~~~~
+
+The Smack label of a filesystem object is stored as an extended attribute
+named SMACK64 on the file. This attribute is in the security namespace. It can
+only be changed by a process with privilege.
+
+Privilege
+~~~~~~~~~
+
+A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
+CAP_MAC_OVERRIDE allows the process access to objects it would
+be denied otherwise. CAP_MAC_ADMIN allows a process to change
+Smack data, including rules and attributes.
+
+Smack Networking
+~~~~~~~~~~~~~~~~
+
+As mentioned before, Smack enforces access control on network protocol
+transmissions. Every packet sent by a Smack process is tagged with its Smack
+label. This is done by adding a CIPSO tag to the header of the IP packet. Each
+packet received is expected to have a CIPSO tag that identifies the label and
+if it lacks such a tag the network ambient label is assumed. Before the packet
+is delivered a check is made to determine that a subject with the label on the
+packet has write access to the receiving process and if that is not the case
+the packet is dropped.
+
+CIPSO Configuration
+~~~~~~~~~~~~~~~~~~~
+
+It is normally unnecessary to specify the CIPSO configuration. The default
+values used by the system handle all internal cases. Smack will compose CIPSO
+label values to match the Smack labels being used without administrative
+intervention. Unlabeled packets that come into the system will be given the
+ambient label.
+
+Smack requires configuration in the case where packets from a system that is
+not Smack that speaks CIPSO may be encountered. Usually this will be a Trusted
+Solaris system, but there are other, less widely deployed systems out there.
+CIPSO provides 3 important values, a Domain Of Interpretation (DOI), a level,
+and a category set with each packet. The DOI is intended to identify a group
+of systems that use compatible labeling schemes, and the DOI specified on the
+Smack system must match that of the remote system or packets will be
+discarded. The DOI is 3 by default. The value can be read from
+/sys/fs/smackfs/doi and can be changed by writing to /sys/fs/smackfs/doi.
+
+The label and category set are mapped to a Smack label as defined in
+/etc/smack/cipso.
+
+A Smack/CIPSO mapping has the form::
+
+ smack level [category [category]*]
+
+Smack does not expect the level or category sets to be related in any
+particular way and does not assume or assign accesses based on them. Some
+examples of mappings::
+
+ TopSecret 7
+ TS:A,B 7 1 2
+ SecBDE 5 2 4 6
+ RAFTERS 7 12 26
+
+The ":" and "," characters are permitted in a Smack label but have no special
+meaning.
+
+The mapping of Smack labels to CIPSO values is defined by writing to
+/sys/fs/smackfs/cipso2.
+
+In addition to explicit mappings Smack supports direct CIPSO mappings. One
+CIPSO level is used to indicate that the category set passed in the packet is
+in fact an encoding of the Smack label. The level used is 250 by default. The
+value can be read from /sys/fs/smackfs/direct and changed by writing to
+/sys/fs/smackfs/direct.
+
+Socket Attributes
+~~~~~~~~~~~~~~~~~
+
+There are two attributes that are associated with sockets. These attributes
+can only be set by privileged tasks, but any task can read them for their own
+sockets.
+
+ SMACK64IPIN:
+ The Smack label of the task object. A privileged
+ program that will enforce policy may set this to the star label.
+
+ SMACK64IPOUT:
+ The Smack label transmitted with outgoing packets.
+ A privileged program may set this to match the label of another
+ task with which it hopes to communicate.
+
+UNIX domain socket (UDS) with a BSD address functions both as a file in a
+filesystem and as a socket. As a file, it carries the SMACK64 attribute. This
+attribute is not involved in Smack security enforcement and is immutably
+assigned the label "*".
+
+Smack Netlabel Exceptions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You will often find that your labeled application has to talk to the outside,
+unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
+where you can add some exceptions in the form of::
+
+ @IP1 LABEL1 or
+ @IP2/MASK LABEL2
+
+It means that your application will have unlabeled access to @IP1 if it has
+write access on LABEL1, and access to the subnet @IP2/MASK if it has write
+access on LABEL2.
+
+Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
+first, like in classless IPv4 routing.
+
+A special label '@' and an option '-CIPSO' can be used there::
+
+ @ means Internet, any application with any label has access to it
+ -CIPSO means standard CIPSO networking
+
+If you don't know what CIPSO is and don't plan to use it, you can just do::
+
+ echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
+ echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
+
+If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
+Internet access, you can have::
+
+ echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
+ echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
+ echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
+
+Writing Applications for Smack
+------------------------------
+
+There are three sorts of applications that will run on a Smack system. How an
+application interacts with Smack will determine what it will have to do to
+work properly under Smack.
+
+Smack Ignorant Applications
+---------------------------
+
+By far the majority of applications have no reason whatever to care about the
+unique properties of Smack. Since invoking a program has no impact on the
+Smack label associated with the process the only concern likely to arise is
+whether the process has execute access to the program.
+
+Smack Relevant Applications
+---------------------------
+
+Some programs can be improved by teaching them about Smack, but do not make
+any security decisions themselves. The utility ls(1) is one example of such a
+program.
+
+Smack Enforcing Applications
+----------------------------
+
+These are special programs that not only know about Smack, but participate in
+the enforcement of system policy. In most cases these are the programs that
+set up user sessions. There are also network services that provide information
+to processes running with various labels.
+
+File System Interfaces
+----------------------
+
+Smack maintains labels on file system objects using extended attributes. The
+Smack label of a file, directory, or other file system object can be obtained
+using getxattr(2)::
+
+ len = getxattr("/", "security.SMACK64", value, sizeof (value));
+
+will put the Smack label of the root directory into value. A privileged
+process can set the Smack label of a file system object with setxattr(2)::
+
+ len = strlen("Rubble");
+ rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
+
+will set the Smack label of /foo to "Rubble" if the program has appropriate
+privilege.
+
+Socket Interfaces
+-----------------
+
+The socket attributes can be read using fgetxattr(2).
+
+A privileged process can set the Smack label of outgoing packets with
+fsetxattr(2)::
+
+ len = strlen("Rubble");
+ rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
+
+will set the Smack label "Rubble" on packets going out from the socket if the
+program has appropriate privilege::
+
+ rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
+
+will set the Smack label "*" as the object label against which incoming
+packets will be checked if the program has appropriate privilege.
+
+Administration
+--------------
+
+Smack supports some mount options:
+
+ smackfsdef=label:
+ specifies the label to give files that lack
+ the Smack label extended attribute.
+
+ smackfsroot=label:
+ specifies the label to assign the root of the
+ file system if it lacks the Smack extended attribute.
+
+ smackfshat=label:
+ specifies a label that must have read access to
+ all labels set on the filesystem. Not yet enforced.
+
+ smackfsfloor=label:
+ specifies a label to which all labels set on the
+ filesystem must have read access. Not yet enforced.
+
+ smackfstransmute=label:
+ behaves exactly like smackfsroot except that it also
+ sets the transmute flag on the root of the mount
+
+These mount options apply to all file system types.
+
+Smack auditing
+--------------
+
+If you want Smack auditing of security events, you need to set CONFIG_AUDIT
+in your kernel configuration.
+By default, all denied events will be audited. You can change this behavior by
+writing a single character to the /sys/fs/smackfs/logging file::
+
+ 0 : no logging
+ 1 : log denied (default)
+ 2 : log accepted
+ 3 : log denied & accepted
+
+Events are logged as 'key=value' pairs, for each event you at least will get
+the subject, the object, the rights requested, the action, the kernel function
+that triggered the event, plus other pairs depending on the type of event
+audited.
+
+Bringup Mode
+------------
+
+Bringup mode provides logging features that can make application
+configuration and system bringup easier. Configure the kernel with
+CONFIG_SECURITY_SMACK_BRINGUP to enable these features. When bringup
+mode is enabled accesses that succeed due to rules marked with the "b"
+access mode will logged. When a new label is introduced for processes
+rules can be added aggressively, marked with the "b". The logging allows
+tracking of which rules actual get used for that label.
+
+Another feature of bringup mode is the "unconfined" option. Writing
+a label to /sys/fs/smackfs/unconfined makes subjects with that label
+able to access any object, and objects with that label accessible to
+all subjects. Any access that is granted because a label is unconfined
+is logged. This feature is dangerous, as files and directories may
+be created in places they couldn't if the policy were being enforced.
diff --git a/Documentation/admin-guide/LSM/Yama.rst b/Documentation/admin-guide/LSM/Yama.rst
new file mode 100644
index 000000000000..d9cd937ebd2d
--- /dev/null
+++ b/Documentation/admin-guide/LSM/Yama.rst
@@ -0,0 +1,75 @@
+====
+Yama
+====
+
+Yama is a Linux Security Module that collects system-wide DAC security
+protections that are not handled by the core kernel itself. This is
+selectable at build-time with ``CONFIG_SECURITY_YAMA``, and can be controlled
+at run-time through sysctls in ``/proc/sys/kernel/yama``:
+
+ptrace_scope
+============
+
+As Linux grows in popularity, it will become a larger target for
+malware. One particularly troubling weakness of the Linux process
+interfaces is that a single user is able to examine the memory and
+running state of any of their processes. For example, if one application
+(e.g. Pidgin) was compromised, it would be possible for an attacker to
+attach to other running processes (e.g. Firefox, SSH sessions, GPG agent,
+etc) to extract additional credentials and continue to expand the scope
+of their attack without resorting to user-assisted phishing.
+
+This is not a theoretical problem. `SSH session hijacking
+<https://www.blackhat.com/presentations/bh-usa-05/bh-us-05-boileau.pdf>`_
+and `arbitrary code injection
+<https://c-skills.blogspot.com/2007/05/injectso.html>`_ attacks already
+exist and remain possible if ptrace is allowed to operate as before.
+Since ptrace is not commonly used by non-developers and non-admins, system
+builders should be allowed the option to disable this debugging system.
+
+For a solution, some applications use ``prctl(PR_SET_DUMPABLE, ...)`` to
+specifically disallow such ptrace attachment (e.g. ssh-agent), but many
+do not. A more general solution is to only allow ptrace directly from a
+parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still
+work), or with ``CAP_SYS_PTRACE`` (i.e. "gdb --pid=PID", and "strace -p PID"
+still work as root).
+
+In mode 1, software that has defined application-specific relationships
+between a debugging process and its inferior (crash handlers, etc),
+``prctl(PR_SET_PTRACER, pid, ...)`` can be used. An inferior can declare which
+other process (and its descendants) are allowed to call ``PTRACE_ATTACH``
+against it. Only one such declared debugging process can exists for
+each inferior at a time. For example, this is used by KDE, Chromium, and
+Firefox's crash handlers, and by Wine for allowing only Wine processes
+to ptrace each other. If a process wishes to entirely disable these ptrace
+restrictions, it can call ``prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)``
+so that any otherwise allowed process (even those in external pid namespaces)
+may attach.
+
+The sysctl settings (writable only with ``CAP_SYS_PTRACE``) are:
+
+0 - classic ptrace permissions:
+ a process can ``PTRACE_ATTACH`` to any other
+ process running under the same uid, as long as it is dumpable (i.e.
+ did not transition uids, start privileged, or have called
+ ``prctl(PR_SET_DUMPABLE...)`` already). Similarly, ``PTRACE_TRACEME`` is
+ unchanged.
+
+1 - restricted ptrace:
+ a process must have a predefined relationship
+ with the inferior it wants to call ``PTRACE_ATTACH`` on. By default,
+ this relationship is that of only its descendants when the above
+ classic criteria is also met. To change the relationship, an
+ inferior can call ``prctl(PR_SET_PTRACER, debugger, ...)`` to declare
+ an allowed debugger PID to call ``PTRACE_ATTACH`` on the inferior.
+ Using ``PTRACE_TRACEME`` is unchanged.
+
+2 - admin-only attach:
+ only processes with ``CAP_SYS_PTRACE`` may use ptrace, either with
+ ``PTRACE_ATTACH`` or through children calling ``PTRACE_TRACEME``.
+
+3 - no attach:
+ no processes may use ptrace with ``PTRACE_ATTACH`` nor via
+ ``PTRACE_TRACEME``. Once set, this sysctl value cannot be changed.
+
+The original children-only logic was based on the restrictions in grsecurity.
diff --git a/Documentation/admin-guide/LSM/apparmor.rst b/Documentation/admin-guide/LSM/apparmor.rst
new file mode 100644
index 000000000000..47939ee89d74
--- /dev/null
+++ b/Documentation/admin-guide/LSM/apparmor.rst
@@ -0,0 +1,54 @@
+========
+AppArmor
+========
+
+What is AppArmor?
+=================
+
+AppArmor is MAC style security extension for the Linux kernel. It implements
+a task centered policy, with task "profiles" being created and loaded
+from user space. Tasks on the system that do not have a profile defined for
+them run in an unconfined state which is equivalent to standard Linux DAC
+permissions.
+
+How to enable/disable
+=====================
+
+set ``CONFIG_SECURITY_APPARMOR=y``
+
+If AppArmor should be selected as the default security module then set::
+
+ CONFIG_DEFAULT_SECURITY_APPARMOR=y
+
+The CONFIG_LSM parameter manages the order and selection of LSMs.
+Specify apparmor as the first "major" module (e.g. AppArmor, SELinux, Smack)
+in the list.
+
+Build the kernel
+
+If AppArmor is not the default security module it can be enabled by passing
+``security=apparmor`` on the kernel's command line.
+
+If AppArmor is the default security module it can be disabled by passing
+``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
+kernel's command line.
+
+For AppArmor to enforce any restrictions beyond standard Linux DAC permissions
+policy must be loaded into the kernel from user space (see the Documentation
+and tools links).
+
+Documentation
+=============
+
+Documentation can be found on the wiki, linked below.
+
+Links
+=====
+
+Mailing List - apparmor@lists.ubuntu.com
+
+Wiki - http://wiki.apparmor.net
+
+User space tools - https://gitlab.com/apparmor
+
+Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/linux-apparmor
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
new file mode 100644
index 000000000000..b44ef68f6e4d
--- /dev/null
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -0,0 +1,51 @@
+===========================
+Linux Security Module Usage
+===========================
+
+The Linux Security Module (LSM) framework provides a mechanism for
+various security checks to be hooked by new kernel extensions. The name
+"module" is a bit of a misnomer since these extensions are not actually
+loadable kernel modules. Instead, they are selectable at build-time via
+CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
+``"security=..."`` kernel command line argument, in the case where multiple
+LSMs were built into a given kernel.
+
+The primary users of the LSM interface are Mandatory Access Control
+(MAC) extensions which provide a comprehensive security policy. Examples
+include SELinux, Smack, Tomoyo, and AppArmor. In addition to the larger
+MAC extensions, other extensions can be built using the LSM to provide
+specific changes to system operation when these tweaks are not available
+in the core functionality of Linux itself.
+
+The Linux capabilities modules will always be included. This may be
+followed by any number of "minor" modules and at most one "major" module.
+For more details on capabilities, see ``capabilities(7)`` in the Linux
+man-pages project.
+
+A list of the active security modules can be found by reading
+``/sys/kernel/security/lsm``. This is a comma separated list, and
+will always include the capability module. The list reflects the
+order in which checks are made. The capability module will always
+be first, followed by any "minor" modules (e.g. Yama) and then
+the one "major" module (e.g. SELinux) if there is one configured.
+
+Process attributes associated with "major" security modules should
+be accessed and maintained using the special files in ``/proc/.../attr``.
+A security module may maintain a module specific subdirectory there,
+named after the module. ``/proc/.../attr/smack`` is provided by the Smack
+security module and contains all its special files. The files directly
+in ``/proc/.../attr`` remain as legacy interfaces for modules that provide
+subdirectories.
+
+.. toctree::
+ :maxdepth: 1
+
+ apparmor
+ LoadPin
+ SELinux
+ Smack
+ tomoyo
+ Yama
+ SafeSetID
+ ipe
+ landlock
diff --git a/Documentation/admin-guide/LSM/ipe.rst b/Documentation/admin-guide/LSM/ipe.rst
new file mode 100644
index 000000000000..a756d8158531
--- /dev/null
+++ b/Documentation/admin-guide/LSM/ipe.rst
@@ -0,0 +1,835 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Integrity Policy Enforcement (IPE)
+==================================
+
+.. NOTE::
+
+ This is the documentation for admins, system builders, or individuals
+ attempting to use IPE. If you're looking for more developer-focused
+ documentation about IPE please see :doc:`the design docs </security/ipe>`.
+
+Overview
+--------
+
+Integrity Policy Enforcement (IPE) is a Linux Security Module that takes a
+complementary approach to access control. Unlike traditional access control
+mechanisms that rely on labels and paths for decision-making, IPE focuses
+on the immutable security properties inherent to system components. These
+properties are fundamental attributes or features of a system component
+that cannot be altered, ensuring a consistent and reliable basis for
+security decisions.
+
+To elaborate, in the context of IPE, system components primarily refer to
+files or the devices these files reside on. However, this is just a
+starting point. The concept of system components is flexible and can be
+extended to include new elements as the system evolves. The immutable
+properties include the origin of a file, which remains constant and
+unchangeable over time. For example, IPE policies can be crafted to trust
+files originating from the initramfs. Since initramfs is typically verified
+by the bootloader, its files are deemed trustworthy; "file is from
+initramfs" becomes an immutable property under IPE's consideration.
+
+The immutable property concept extends to the security features enabled on
+a file's origin, such as dm-verity or fs-verity, which provide a layer of
+integrity and trust. For example, IPE allows the definition of policies
+that trust files from a dm-verity protected device. dm-verity ensures the
+integrity of an entire device by providing a verifiable and immutable state
+of its contents. Similarly, fs-verity offers filesystem-level integrity
+checks, allowing IPE to enforce policies that trust files protected by
+fs-verity. These two features cannot be turned off once established, so
+they are considered immutable properties. These examples demonstrate how
+IPE leverages immutable properties, such as a file's origin and its
+integrity protection mechanisms, to make access control decisions.
+
+For the IPE policy, specifically, it grants the ability to enforce
+stringent access controls by assessing security properties against
+reference values defined within the policy. This assessment can be based on
+the existence of a security property (e.g., verifying if a file originates
+from initramfs) or evaluating the internal state of an immutable security
+property. The latter includes checking the roothash of a dm-verity
+protected device, determining whether dm-verity possesses a valid
+signature, assessing the digest of a fs-verity protected file, or
+determining whether fs-verity possesses a valid built-in signature. This
+nuanced approach to policy enforcement enables a highly secure and
+customizable system defense mechanism, tailored to specific security
+requirements and trust models.
+
+To enable IPE, ensure that ``CONFIG_SECURITY_IPE`` (under
+:menuselection:`Security -> Integrity Policy Enforcement (IPE)`) config
+option is enabled.
+
+Use Cases
+---------
+
+IPE works best in fixed-function devices: devices in which their purpose
+is clearly defined and not supposed to be changed (e.g. network firewall
+device in a data center, an IoT device, etcetera), where all software and
+configuration is built and provisioned by the system owner.
+
+IPE is a long-way off for use in general-purpose computing: the Linux
+community as a whole tends to follow a decentralized trust model (known as
+the web of trust), which IPE has no support for it yet. Instead, IPE
+supports PKI (public key infrastructure), which generally designates a
+set of trusted entities that provide a measure of absolute trust.
+
+Additionally, while most packages are signed today, the files inside
+the packages (for instance, the executables), tend to be unsigned. This
+makes it difficult to utilize IPE in systems where a package manager is
+expected to be functional, without major changes to the package manager
+and ecosystem behind it.
+
+The digest_cache LSM [#digest_cache_lsm]_ is a system that when combined with IPE,
+could be used to enable and support general-purpose computing use cases.
+
+Known Limitations
+-----------------
+
+IPE cannot verify the integrity of anonymous executable memory, such as
+the trampolines created by gcc closures and libffi (<3.4.2), or JIT'd code.
+Unfortunately, as this is dynamically generated code, there is no way
+for IPE to ensure the integrity of this code to form a trust basis.
+
+IPE cannot verify the integrity of programs written in interpreted
+languages when these scripts are invoked by passing these program files
+to the interpreter. This is because the way interpreters execute these
+files; the scripts themselves are not evaluated as executable code
+through one of IPE's hooks, but they are merely text files that are read
+(as opposed to compiled executables). However, with the introduction of the
+``AT_EXECVE_CHECK`` flag (:doc:`AT_EXECVE_CHECK </userspace-api/check_exec>`),
+interpreters can use it to signal the kernel that a script file will be executed,
+and request the kernel to perform LSM security checks on it.
+
+IPE's EXECUTE operation enforcement differs between compiled executables and
+interpreted scripts: For compiled executables, enforcement is triggered
+automatically by the kernel during ``execve()``, ``execveat()``, ``mmap()``
+and ``mprotect()`` syscalls when loading executable content. For interpreted
+scripts, enforcement requires explicit interpreter integration using
+``execveat()`` with ``AT_EXECVE_CHECK`` flag. Unlike exec syscalls that IPE
+intercepts during the execution process, this mechanism needs the interpreter
+to take the initiative, and existing interpreters won't be automatically
+supported unless the signal call is added.
+
+Threat Model
+------------
+
+IPE specifically targets the risk of tampering with user-space executable
+code after the kernel has initially booted, including the kernel modules
+loaded from userspace via ``modprobe`` or ``insmod``.
+
+To illustrate, consider a scenario where an untrusted binary, possibly
+malicious, is downloaded along with all necessary dependencies, including a
+loader and libc. The primary function of IPE in this context is to prevent
+the execution of such binaries and their dependencies.
+
+IPE achieves this by verifying the integrity and authenticity of all
+executable code before allowing them to run. It conducts a thorough
+check to ensure that the code's integrity is intact and that they match an
+authorized reference value (digest, signature, etc) as per the defined
+policy. If a binary does not pass this verification process, either
+because its integrity has been compromised or it does not meet the
+authorization criteria, IPE will deny its execution. Additionally, IPE
+generates audit logs which may be utilized to detect and analyze failures
+resulting from policy violation.
+
+Tampering threat scenarios include modification or replacement of
+executable code by a range of actors including:
+
+- Actors with physical access to the hardware
+- Actors with local network access to the system
+- Actors with access to the deployment system
+- Compromised internal systems under external control
+- Malicious end users of the system
+- Compromised end users of the system
+- Remote (external) compromise of the system
+
+IPE does not mitigate threats arising from malicious but authorized
+developers (with access to a signing certificate), or compromised
+developer tools used by them (i.e. return-oriented programming attacks).
+Additionally, IPE draws hard security boundary between userspace and
+kernelspace. As a result, kernel-level exploits are considered outside
+the scope of IPE and mitigation is left to other mechanisms.
+
+Policy
+------
+
+IPE policy is a plain-text [#devdoc]_ policy composed of multiple statements
+over several lines. There is one required line, at the top of the
+policy, indicating the policy name, and the policy version, for
+instance::
+
+ policy_name=Ex_Policy policy_version=0.0.0
+
+The policy name is a unique key identifying this policy in a human
+readable name. This is used to create nodes under securityfs as well as
+uniquely identify policies to deploy new policies vs update existing
+policies.
+
+The policy version indicates the current version of the policy (NOT the
+policy syntax version). This is used to prevent rollback of policy to
+potentially insecure previous versions of the policy.
+
+The next portion of IPE policy are rules. Rules are formed by key=value
+pairs, known as properties. IPE rules require two properties: ``action``,
+which determines what IPE does when it encounters a match against the
+rule, and ``op``, which determines when the rule should be evaluated.
+The ordering is significant, a rule must start with ``op``, and end with
+``action``. Thus, a minimal rule is::
+
+ op=EXECUTE action=ALLOW
+
+This example will allow any execution. Additional properties are used to
+assess immutable security properties about the files being evaluated.
+These properties are intended to be descriptions of systems within the
+kernel that can provide a measure of integrity verification, such that IPE
+can determine the trust of the resource based on the value of the property.
+
+Rules are evaluated top-to-bottom. As a result, any revocation rules,
+or denies should be placed early in the file to ensure that these rules
+are evaluated before a rule with ``action=ALLOW``.
+
+IPE policy supports comments. The character '#' will function as a
+comment, ignoring all characters to the right of '#' until the newline.
+
+The default behavior of IPE evaluations can also be expressed in policy,
+through the ``DEFAULT`` statement. This can be done at a global level,
+or a per-operation level::
+
+ # Global
+ DEFAULT action=ALLOW
+
+ # Operation Specific
+ DEFAULT op=EXECUTE action=ALLOW
+
+A default must be set for all known operations in IPE. If you want to
+preserve older policies being compatible with newer kernels that can introduce
+new operations, set a global default of ``ALLOW``, then override the
+defaults on a per-operation basis (as above).
+
+With configurable policy-based LSMs, there's several issues with
+enforcing the configurable policies at startup, around reading and
+parsing the policy:
+
+1. The kernel *should* not read files from userspace, so directly reading
+ the policy file is prohibited.
+2. The kernel command line has a character limit, and one kernel module
+ should not reserve the entire character limit for its own
+ configuration.
+3. There are various boot loaders in the kernel ecosystem, so handing
+ off a memory block would be costly to maintain.
+
+As a result, IPE has addressed this problem through a concept of a "boot
+policy". A boot policy is a minimal policy which is compiled into the
+kernel. This policy is intended to get the system to a state where
+userspace is set up and ready to receive commands, at which point a more
+complex policy can be deployed via securityfs. The boot policy can be
+specified via ``SECURITY_IPE_BOOT_POLICY`` config option, which accepts
+a path to a plain-text version of the IPE policy to apply. This policy
+will be compiled into the kernel. If not specified, IPE will be disabled
+until a policy is deployed and activated through securityfs.
+
+Deploying Policies
+~~~~~~~~~~~~~~~~~~
+
+Policies can be deployed from userspace through securityfs. These policies
+are signed through the PKCS#7 message format to enforce some level of
+authorization of the policies (prohibiting an attacker from gaining
+unconstrained root, and deploying an "allow all" policy). These
+policies must be signed by a certificate that chains to the
+``SYSTEM_TRUSTED_KEYRING``, or to the secondary and/or platform keyrings if
+``CONFIG_IPE_POLICY_SIG_SECONDARY_KEYRING`` and/or
+``CONFIG_IPE_POLICY_SIG_PLATFORM_KEYRING`` are enabled, respectively.
+With openssl, the policy can be signed by::
+
+ openssl smime -sign \
+ -in "$MY_POLICY" \
+ -signer "$MY_CERTIFICATE" \
+ -inkey "$MY_PRIVATE_KEY" \
+ -noattr \
+ -nodetach \
+ -nosmimecap \
+ -outform der \
+ -out "$MY_POLICY.p7b"
+
+Deploying the policies is done through securityfs, through the
+``new_policy`` node. To deploy a policy, simply cat the file into the
+securityfs node::
+
+ cat "$MY_POLICY.p7b" > /sys/kernel/security/ipe/new_policy
+
+Upon success, this will create one subdirectory under
+``/sys/kernel/security/ipe/policies/``. The subdirectory will be the
+``policy_name`` field of the policy deployed, so for the example above,
+the directory will be ``/sys/kernel/security/ipe/policies/Ex_Policy``.
+Within this directory, there will be seven files: ``pkcs7``, ``policy``,
+``name``, ``version``, ``active``, ``update``, and ``delete``.
+
+The ``pkcs7`` file is read-only. Reading it returns the raw PKCS#7 data
+that was provided to the kernel, representing the policy. If the policy being
+read is the boot policy, this will return ``ENOENT``, as it is not signed.
+
+The ``policy`` file is read only. Reading it returns the PKCS#7 inner
+content of the policy, which will be the plain text policy.
+
+The ``active`` file is used to set a policy as the currently active policy.
+This file is rw, and accepts a value of ``"1"`` to set the policy as active.
+Since only a single policy can be active at one time, all other policies
+will be marked inactive. The policy being marked active must have a policy
+version greater or equal to the currently-running version.
+
+The ``update`` file is used to update a policy that is already present
+in the kernel. This file is write-only and accepts a PKCS#7 signed
+policy. Two checks will always be performed on this policy: First, the
+``policy_names`` must match with the updated version and the existing
+version. Second the updated policy must have a policy version greater than
+the currently-running version. This is to prevent rollback attacks.
+
+The ``delete`` file is used to remove a policy that is no longer needed.
+This file is write-only and accepts a value of ``1`` to delete the policy.
+On deletion, the securityfs node representing the policy will be removed.
+However, delete the current active policy is not allowed and will return
+an operation not permitted error.
+
+Similarly, writing to both ``update`` and ``new_policy`` could result in
+bad message(policy syntax error) or file exists error. The latter error happens
+when trying to deploy a policy with a ``policy_name`` while the kernel already
+has a deployed policy with the same ``policy_name``.
+
+Deploying a policy will *not* cause IPE to start enforcing the policy. IPE will
+only enforce the policy marked active. Note that only one policy can be active
+at a time.
+
+Once deployment is successful, the policy can be activated, by writing file
+``/sys/kernel/security/ipe/policies/$policy_name/active``.
+For example, the ``Ex_Policy`` can be activated by::
+
+ echo 1 > "/sys/kernel/security/ipe/policies/Ex_Policy/active"
+
+From above point on, ``Ex_Policy`` is now the enforced policy on the
+system.
+
+IPE also provides a way to delete policies. This can be done via the
+``delete`` securityfs node,
+``/sys/kernel/security/ipe/policies/$policy_name/delete``.
+Writing ``1`` to that file deletes the policy::
+
+ echo 1 > "/sys/kernel/security/ipe/policies/$policy_name/delete"
+
+There is only one requirement to delete a policy: the policy being deleted
+must be inactive.
+
+.. NOTE::
+
+ If a traditional MAC system is enabled (SELinux, apparmor, smack), all
+ writes to ipe's securityfs nodes require ``CAP_MAC_ADMIN``.
+
+Modes
+~~~~~
+
+IPE supports two modes of operation: permissive (similar to SELinux's
+permissive mode) and enforced. In permissive mode, all events are
+checked and policy violations are logged, but the policy is not really
+enforced. This allows users to test policies before enforcing them.
+
+The default mode is enforce, and can be changed via the kernel command
+line parameter ``ipe.enforce=(0|1)``, or the securityfs node
+``/sys/kernel/security/ipe/enforce``.
+
+.. NOTE::
+
+ If a traditional MAC system is enabled (SELinux, apparmor, smack, etcetera),
+ all writes to ipe's securityfs nodes require ``CAP_MAC_ADMIN``.
+
+Audit Events
+~~~~~~~~~~~~
+
+1420 AUDIT_IPE_ACCESS
+^^^^^^^^^^^^^^^^^^^^^
+Event Examples::
+
+ type=1420 audit(1653364370.067:61): ipe_op=EXECUTE ipe_hook=MMAP enforcing=1 pid=2241 comm="ld-linux.so" path="/deny/lib/libc.so.6" dev="sda2" ino=14549020 rule="DEFAULT action=DENY"
+ type=1300 audit(1653364370.067:61): SYSCALL arch=c000003e syscall=9 success=no exit=-13 a0=7f1105a28000 a1=195000 a2=5 a3=812 items=0 ppid=2219 pid=2241 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=2 comm="ld-linux.so" exe="/tmp/ipe-test/lib/ld-linux.so" subj=unconfined key=(null)
+ type=1327 audit(1653364370.067:61): 707974686F6E3300746573742F6D61696E2E7079002D6E00
+
+ type=1420 audit(1653364735.161:64): ipe_op=EXECUTE ipe_hook=MMAP enforcing=1 pid=2472 comm="mmap_test" path=? dev=? ino=? rule="DEFAULT action=DENY"
+ type=1300 audit(1653364735.161:64): SYSCALL arch=c000003e syscall=9 success=no exit=-13 a0=0 a1=1000 a2=4 a3=21 items=0 ppid=2219 pid=2472 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=2 comm="mmap_test" exe="/root/overlake_test/upstream_test/vol_fsverity/bin/mmap_test" subj=unconfined key=(null)
+ type=1327 audit(1653364735.161:64): 707974686F6E3300746573742F6D61696E2E7079002D6E00
+
+This event indicates that IPE made an access control decision; the IPE
+specific record (1420) is always emitted in conjunction with a
+``AUDITSYSCALL`` record.
+
+Determining whether IPE is in permissive or enforced mode can be derived
+from ``success`` property and exit code of the ``AUDITSYSCALL`` record.
+
+
+Field descriptions:
+
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| Field | Value Type | Optional? | Description of Value |
++===========+============+===========+=================================================================================+
+| ipe_op | string | No | The IPE operation name associated with the log |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| ipe_hook | string | No | The name of the LSM hook that triggered the IPE event |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| enforcing | integer | No | The current IPE enforcing state 1 is in enforcing mode, 0 is in permissive mode |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| pid | integer | No | The pid of the process that triggered the IPE event. |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| comm | string | No | The command line program name of the process that triggered the IPE event |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| path | string | Yes | The absolute path to the evaluated file |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| ino | integer | Yes | The inode number of the evaluated file |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| dev | string | Yes | The device name of the evaluated file, e.g. vda |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+| rule | string | No | The matched policy rule |
++-----------+------------+-----------+---------------------------------------------------------------------------------+
+
+1421 AUDIT_IPE_CONFIG_CHANGE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Event Example::
+
+ type=1421 audit(1653425583.136:54): old_active_pol_name="Allow_All" old_active_pol_version=0.0.0 old_policy_digest=sha256:E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 new_active_pol_name="boot_verified" new_active_pol_version=0.0.0 new_policy_digest=sha256:820EEA5B40CA42B51F68962354BA083122A20BB846F26765076DD8EED7B8F4DB auid=4294967295 ses=4294967295 lsm=ipe res=1
+ type=1300 audit(1653425583.136:54): SYSCALL arch=c000003e syscall=1 success=yes exit=2 a0=3 a1=5596fcae1fb0 a2=2 a3=2 items=0 ppid=184 pid=229 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=4294967295 comm="python3" exe="/usr/bin/python3.10" key=(null)
+ type=1327 audit(1653425583.136:54): PROCTITLE proctitle=707974686F6E3300746573742F6D61696E2E7079002D66002E2
+
+This event indicates that IPE switched the active poliy from one to another
+along with the version and the hash digest of the two policies.
+Note IPE can only have one policy active at a time, all access decision
+evaluation is based on the current active policy.
+The normal procedure to deploy a new policy is loading the policy to deploy
+into the kernel first, then switch the active policy to it.
+
+This record will always be emitted in conjunction with a ``AUDITSYSCALL`` record for the ``write`` syscall.
+
+Field descriptions:
+
++------------------------+------------+-----------+---------------------------------------------------+
+| Field | Value Type | Optional? | Description of Value |
++========================+============+===========+===================================================+
+| old_active_pol_name | string | Yes | The name of previous active policy |
++------------------------+------------+-----------+---------------------------------------------------+
+| old_active_pol_version | string | Yes | The version of previous active policy |
++------------------------+------------+-----------+---------------------------------------------------+
+| old_policy_digest | string | Yes | The hash of previous active policy |
++------------------------+------------+-----------+---------------------------------------------------+
+| new_active_pol_name | string | No | The name of current active policy |
++------------------------+------------+-----------+---------------------------------------------------+
+| new_active_pol_version | string | No | The version of current active policy |
++------------------------+------------+-----------+---------------------------------------------------+
+| new_policy_digest | string | No | The hash of current active policy |
++------------------------+------------+-----------+---------------------------------------------------+
+| auid | integer | No | The login user ID |
++------------------------+------------+-----------+---------------------------------------------------+
+| ses | integer | No | The login session ID |
++------------------------+------------+-----------+---------------------------------------------------+
+| lsm | string | No | The lsm name associated with the event |
++------------------------+------------+-----------+---------------------------------------------------+
+| res | integer | No | The result of the audited operation(success/fail) |
++------------------------+------------+-----------+---------------------------------------------------+
+
+1422 AUDIT_IPE_POLICY_LOAD
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Event Example::
+
+ type=1422 audit(1653425529.927:53): policy_name="boot_verified" policy_version=0.0.0 policy_digest=sha256:820EEA5B40CA42B51F68962354BA083122A20BB846F26765076DD8EED7B8F4DB auid=4294967295 ses=4294967295 lsm=ipe res=1 errno=0
+ type=1300 audit(1653425529.927:53): arch=c000003e syscall=1 success=yes exit=2567 a0=3 a1=5596fcae1fb0 a2=a07 a3=2 items=0 ppid=184 pid=229 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts0 ses=4294967295 comm="python3" exe="/usr/bin/python3.10" key=(null)
+ type=1327 audit(1653425529.927:53): PROCTITLE proctitle=707974686F6E3300746573742F6D61696E2E7079002D66002E2E
+
+This record indicates a new policy has been loaded into the kernel with the policy name, policy version and policy hash.
+
+This record will always be emitted in conjunction with a ``AUDITSYSCALL`` record for the ``write`` syscall.
+
+Field descriptions:
+
++----------------+------------+-----------+-------------------------------------------------------------+
+| Field | Value Type | Optional? | Description of Value |
++================+============+===========+=============================================================+
+| policy_name | string | Yes | The policy_name |
++----------------+------------+-----------+-------------------------------------------------------------+
+| policy_version | string | Yes | The policy_version |
++----------------+------------+-----------+-------------------------------------------------------------+
+| policy_digest | string | Yes | The policy hash |
++----------------+------------+-----------+-------------------------------------------------------------+
+| auid | integer | No | The login user ID |
++----------------+------------+-----------+-------------------------------------------------------------+
+| ses | integer | No | The login session ID |
++----------------+------------+-----------+-------------------------------------------------------------+
+| lsm | string | No | The lsm name associated with the event |
++----------------+------------+-----------+-------------------------------------------------------------+
+| res | integer | No | The result of the audited operation(success/fail) |
++----------------+------------+-----------+-------------------------------------------------------------+
+| errno | integer | No | Error code from policy loading operations (see table below) |
++----------------+------------+-----------+-------------------------------------------------------------+
+
+Policy error codes (errno):
+
+The following table lists the error codes that may appear in the errno field while loading or updating the policy:
+
++----------------+--------------------------------------------------------+
+| Error Code | Description |
++================+========================================================+
+| 0 | Success |
++----------------+--------------------------------------------------------+
+| -EPERM | Insufficient permission |
++----------------+--------------------------------------------------------+
+| -EEXIST | Same name policy already deployed |
++----------------+--------------------------------------------------------+
+| -EBADMSG | Policy is invalid |
++----------------+--------------------------------------------------------+
+| -ENOMEM | Out of memory (OOM) |
++----------------+--------------------------------------------------------+
+| -ERANGE | Policy version number overflow |
++----------------+--------------------------------------------------------+
+| -EINVAL | Policy version parsing error |
++----------------+--------------------------------------------------------+
+| -ENOKEY | Key used to sign the IPE policy not found in keyring |
++----------------+--------------------------------------------------------+
+| -EKEYREJECTED | Policy signature verification failed |
++----------------+--------------------------------------------------------+
+| -ESTALE | Attempting to update an IPE policy with older version |
++----------------+--------------------------------------------------------+
+| -ENOENT | Policy was deleted while updating |
++----------------+--------------------------------------------------------+
+
+1404 AUDIT_MAC_STATUS
+^^^^^^^^^^^^^^^^^^^^^
+
+Event Examples::
+
+ type=1404 audit(1653425689.008:55): enforcing=0 old_enforcing=1 auid=4294967295 ses=4294967295 enabled=1 old-enabled=1 lsm=ipe res=1
+ type=1300 audit(1653425689.008:55): arch=c000003e syscall=1 success=yes exit=2 a0=1 a1=55c1065e5c60 a2=2 a3=0 items=0 ppid=405 pid=441 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=)
+ type=1327 audit(1653425689.008:55): proctitle="-bash"
+
+ type=1404 audit(1653425689.008:55): enforcing=1 old_enforcing=0 auid=4294967295 ses=4294967295 enabled=1 old-enabled=1 lsm=ipe res=1
+ type=1300 audit(1653425689.008:55): arch=c000003e syscall=1 success=yes exit=2 a0=1 a1=55c1065e5c60 a2=2 a3=0 items=0 ppid=405 pid=441 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=)
+ type=1327 audit(1653425689.008:55): proctitle="-bash"
+
+This record will always be emitted in conjunction with a ``AUDITSYSCALL`` record for the ``write`` syscall.
+
+Field descriptions:
+
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| Field | Value Type | Optional? | Description of Value |
++===============+============+===========+=================================================================================================+
+| enforcing | integer | No | The enforcing state IPE is being switched to, 1 is in enforcing mode, 0 is in permissive mode |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| old_enforcing | integer | No | The enforcing state IPE is being switched from, 1 is in enforcing mode, 0 is in permissive mode |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| auid | integer | No | The login user ID |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| ses | integer | No | The login session ID |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| enabled | integer | No | The new TTY audit enabled setting |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| old-enabled | integer | No | The old TTY audit enabled setting |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| lsm | string | No | The lsm name associated with the event |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+| res | integer | No | The result of the audited operation(success/fail) |
++---------------+------------+-----------+-------------------------------------------------------------------------------------------------+
+
+
+Success Auditing
+^^^^^^^^^^^^^^^^
+
+IPE supports success auditing. When enabled, all events that pass IPE
+policy and are not blocked will emit an audit event. This is disabled by
+default, and can be enabled via the kernel command line
+``ipe.success_audit=(0|1)`` or
+``/sys/kernel/security/ipe/success_audit`` securityfs file.
+
+This is *very* noisy, as IPE will check every userspace binary on the
+system, but is useful for debugging policies.
+
+.. NOTE::
+
+ If a traditional MAC system is enabled (SELinux, apparmor, smack, etcetera),
+ all writes to ipe's securityfs nodes require ``CAP_MAC_ADMIN``.
+
+Properties
+----------
+
+As explained above, IPE properties are ``key=value`` pairs expressed in IPE
+policy. Two properties are built-into the policy parser: 'op' and 'action'.
+The other properties are used to restrict immutable security properties
+about the files being evaluated. Currently those properties are:
+'``boot_verified``', '``dmverity_signature``', '``dmverity_roothash``',
+'``fsverity_signature``', '``fsverity_digest``'. A description of all
+properties supported by IPE are listed below:
+
+op
+~~
+
+Indicates the operation for a rule to apply to. Must be in every rule,
+as the first token. IPE supports the following operations:
+
+ ``EXECUTE``
+
+ Pertains to any file attempting to be executed, or loaded as an
+ executable.
+
+ ``FIRMWARE``:
+
+ Pertains to firmware being loaded via the firmware_class interface.
+ This covers both the preallocated buffer and the firmware file
+ itself.
+
+ ``KMODULE``:
+
+ Pertains to loading kernel modules via ``modprobe`` or ``insmod``.
+
+ ``KEXEC_IMAGE``:
+
+ Pertains to kernel images loading via ``kexec``.
+
+ ``KEXEC_INITRAMFS``
+
+ Pertains to initrd images loading via ``kexec --initrd``.
+
+ ``POLICY``:
+
+ Controls loading policies via reading a kernel-space initiated read.
+
+ An example of such is loading IMA policies by writing the path
+ to the policy file to ``$securityfs/ima/policy``
+
+ ``X509_CERT``:
+
+ Controls loading IMA certificates through the Kconfigs,
+ ``CONFIG_IMA_X509_PATH`` and ``CONFIG_EVM_X509_PATH``.
+
+action
+~~~~~~
+
+ Determines what IPE should do when a rule matches. Must be in every
+ rule, as the final clause. Can be one of:
+
+ ``ALLOW``:
+
+ If the rule matches, explicitly allow access to the resource to proceed
+ without executing any more rules.
+
+ ``DENY``:
+
+ If the rule matches, explicitly prohibit access to the resource to
+ proceed without executing any more rules.
+
+boot_verified
+~~~~~~~~~~~~~
+
+ This property can be utilized for authorization of files from initramfs.
+ The format of this property is::
+
+ boot_verified=(TRUE|FALSE)
+
+
+ .. WARNING::
+
+ This property will trust files from initramfs(rootfs). It should
+ only be used during early booting stage. Before mounting the real
+ rootfs on top of the initramfs, initramfs script will recursively
+ remove all files and directories on the initramfs. This is typically
+ implemented by using switch_root(8) [#switch_root]_. Therefore the
+ initramfs will be empty and not accessible after the real
+ rootfs takes over. It is advised to switch to a different policy
+ that doesn't rely on the property after this point.
+ This ensures that the trust policies remain relevant and effective
+ throughout the system's operation.
+
+dmverity_roothash
+~~~~~~~~~~~~~~~~~
+
+ This property can be utilized for authorization or revocation of
+ specific dm-verity volumes, identified via their root hashes. It has a
+ dependency on the DM_VERITY module. This property is controlled by
+ the ``IPE_PROP_DM_VERITY`` config option, it will be automatically
+ selected when ``SECURITY_IPE`` and ``DM_VERITY`` are all enabled.
+ The format of this property is::
+
+ dmverity_roothash=DigestName:HexadecimalString
+
+ The supported DigestNames for dmverity_roothash are [#dmveritydigests]_
+
+ + blake2b-512
+ + blake2s-256
+ + sha256
+ + sha384
+ + sha512
+ + sha3-224
+ + sha3-256
+ + sha3-384
+ + sha3-512
+ + sm3
+ + rmd160
+
+dmverity_signature
+~~~~~~~~~~~~~~~~~~
+
+ This property can be utilized for authorization of all dm-verity
+ volumes that have a signed roothash that validated by a keyring
+ specified by dm-verity's configuration, either the system trusted
+ keyring, or the secondary keyring. It depends on
+ ``DM_VERITY_VERIFY_ROOTHASH_SIG`` config option and is controlled by
+ the ``IPE_PROP_DM_VERITY_SIGNATURE`` config option, it will be automatically
+ selected when ``SECURITY_IPE``, ``DM_VERITY`` and
+ ``DM_VERITY_VERIFY_ROOTHASH_SIG`` are all enabled.
+ The format of this property is::
+
+ dmverity_signature=(TRUE|FALSE)
+
+fsverity_digest
+~~~~~~~~~~~~~~~
+
+ This property can be utilized for authorization of specific fsverity
+ enabled files, identified via their fsverity digests.
+ It depends on ``FS_VERITY`` config option and is controlled by
+ the ``IPE_PROP_FS_VERITY`` config option, it will be automatically
+ selected when ``SECURITY_IPE`` and ``FS_VERITY`` are all enabled.
+ The format of this property is::
+
+ fsverity_digest=DigestName:HexadecimalString
+
+ The supported DigestNames for fsverity_digest are [#fsveritydigest]_
+
+ + sha256
+ + sha512
+
+fsverity_signature
+~~~~~~~~~~~~~~~~~~
+
+ This property is used to authorize all fs-verity enabled files that have
+ been verified by fs-verity's built-in signature mechanism. The signature
+ verification relies on a key stored within the ".fs-verity" keyring. It
+ depends on ``FS_VERITY_BUILTIN_SIGNATURES`` config option and
+ it is controlled by the ``IPE_PROP_FS_VERITY`` config option,
+ it will be automatically selected when ``SECURITY_IPE``, ``FS_VERITY``
+ and ``FS_VERITY_BUILTIN_SIGNATURES`` are all enabled.
+ The format of this property is::
+
+ fsverity_signature=(TRUE|FALSE)
+
+Policy Examples
+---------------
+
+Allow all
+~~~~~~~~~
+
+::
+
+ policy_name=Allow_All policy_version=0.0.0
+ DEFAULT action=ALLOW
+
+Allow only initramfs
+~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ policy_name=Allow_Initramfs policy_version=0.0.0
+ DEFAULT action=DENY
+
+ op=EXECUTE boot_verified=TRUE action=ALLOW
+
+Allow any signed and validated dm-verity volume and the initramfs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ policy_name=Allow_Signed_DMV_And_Initramfs policy_version=0.0.0
+ DEFAULT action=DENY
+
+ op=EXECUTE boot_verified=TRUE action=ALLOW
+ op=EXECUTE dmverity_signature=TRUE action=ALLOW
+
+Prohibit execution from a specific dm-verity volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ policy_name=Deny_DMV_By_Roothash policy_version=0.0.0
+ DEFAULT action=DENY
+
+ op=EXECUTE dmverity_roothash=sha256:cd2c5bae7c6c579edaae4353049d58eb5f2e8be0244bf05345bc8e5ed257baff action=DENY
+
+ op=EXECUTE boot_verified=TRUE action=ALLOW
+ op=EXECUTE dmverity_signature=TRUE action=ALLOW
+
+Allow only a specific dm-verity volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ policy_name=Allow_DMV_By_Roothash policy_version=0.0.0
+ DEFAULT action=DENY
+
+ op=EXECUTE dmverity_roothash=sha256:401fcec5944823ae12f62726e8184407a5fa9599783f030dec146938 action=ALLOW
+
+Allow any fs-verity file with a valid built-in signature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ policy_name=Allow_Signed_And_Validated_FSVerity policy_version=0.0.0
+ DEFAULT action=DENY
+
+ op=EXECUTE fsverity_signature=TRUE action=ALLOW
+
+Allow execution of a specific fs-verity file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ policy_name=ALLOW_FSV_By_Digest policy_version=0.0.0
+ DEFAULT action=DENY
+
+ op=EXECUTE fsverity_digest=sha256:fd88f2b8824e197f850bf4c5109bea5cf0ee38104f710843bb72da796ba5af9e action=ALLOW
+
+Additional Information
+----------------------
+
+- `Github Repository <https://github.com/microsoft/ipe>`_
+- :doc:`Developer and design docs for IPE </security/ipe>`
+
+FAQ
+---
+
+Q:
+ What's the difference between other LSMs which provide a measure of
+ trust-based access control?
+
+A:
+
+ In general, there's two other LSMs that can provide similar functionality:
+ IMA, and Loadpin.
+
+ IMA and IPE are functionally very similar. The significant difference between
+ the two is the policy. [#devdoc]_
+
+ Loadpin and IPE differ fairly dramatically, as Loadpin only covers the IPE's
+ kernel read operations, whereas IPE is capable of controlling execution
+ on top of kernel read. The trust model is also different; Loadpin roots its
+ trust in the initial super-block, whereas trust in IPE is stemmed from kernel
+ itself (via ``SYSTEM_TRUSTED_KEYS``).
+
+-----------
+
+.. [#digest_cache_lsm] https://lore.kernel.org/lkml/20240415142436.2545003-1-roberto.sassu@huaweicloud.com/
+
+.. [#devdoc] Please see :doc:`the design docs </security/ipe>` for more on
+ this topic.
+
+.. [#switch_root] https://man7.org/linux/man-pages/man8/switch_root.8.html
+
+.. [#dmveritydigests] These hash algorithms are based on values accepted by
+ the Linux crypto API; IPE does not impose any
+ restrictions on the digest algorithm itself;
+ thus, this list may be out of date.
+
+.. [#fsveritydigest] These hash algorithms are based on values accepted by the
+ kernel's fsverity support; IPE does not impose any
+ restrictions on the digest algorithm itself;
+ thus, this list may be out of date.
diff --git a/Documentation/admin-guide/LSM/landlock.rst b/Documentation/admin-guide/LSM/landlock.rst
new file mode 100644
index 000000000000..9e61607def08
--- /dev/null
+++ b/Documentation/admin-guide/LSM/landlock.rst
@@ -0,0 +1,158 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. Copyright © 2025 Microsoft Corporation
+
+================================
+Landlock: system-wide management
+================================
+
+:Author: Mickaël Salaün
+:Date: March 2025
+
+Landlock can leverage the audit framework to log events.
+
+User space documentation can be found here:
+Documentation/userspace-api/landlock.rst.
+
+Audit
+=====
+
+Denied access requests are logged by default for a sandboxed program if `audit`
+is enabled. This default behavior can be changed with the
+sys_landlock_restrict_self() flags (cf.
+Documentation/userspace-api/landlock.rst). Landlock logs can also be masked
+thanks to audit rules. Landlock can generate 2 audit record types.
+
+Record types
+------------
+
+AUDIT_LANDLOCK_ACCESS
+ This record type identifies a denied access request to a kernel resource.
+ The ``domain`` field indicates the ID of the domain that blocked the
+ request. The ``blockers`` field indicates the cause(s) of this denial
+ (separated by a comma), and the following fields identify the kernel object
+ (similar to SELinux). There may be more than one of this record type per
+ audit event.
+
+ Example with a file link request generating two records in the same event::
+
+ domain=195ba459b blockers=fs.refer path="/usr/bin" dev="vda2" ino=351
+ domain=195ba459b blockers=fs.make_reg,fs.refer path="/usr/local" dev="vda2" ino=365
+
+AUDIT_LANDLOCK_DOMAIN
+ This record type describes the status of a Landlock domain. The ``status``
+ field can be either ``allocated`` or ``deallocated``.
+
+ The ``allocated`` status is part of the same audit event and follows
+ the first logged ``AUDIT_LANDLOCK_ACCESS`` record of a domain. It identifies
+ Landlock domain information at the time of the sys_landlock_restrict_self()
+ call with the following fields:
+
+ - the ``domain`` ID
+ - the enforcement ``mode``
+ - the domain creator's ``pid``
+ - the domain creator's ``uid``
+ - the domain creator's executable path (``exe``)
+ - the domain creator's command line (``comm``)
+
+ Example::
+
+ domain=195ba459b status=allocated mode=enforcing pid=300 uid=0 exe="/root/sandboxer" comm="sandboxer"
+
+ The ``deallocated`` status is an event on its own and it identifies a
+ Landlock domain release. After such event, it is guarantee that the
+ related domain ID will never be reused during the lifetime of the system.
+ The ``domain`` field indicates the ID of the domain which is released, and
+ the ``denials`` field indicates the total number of denied access request,
+ which might not have been logged according to the audit rules and
+ sys_landlock_restrict_self()'s flags.
+
+ Example::
+
+ domain=195ba459b status=deallocated denials=3
+
+
+Event samples
+--------------
+
+Here are two examples of log events (see serial numbers).
+
+In this example a sandboxed program (``kill``) tries to send a signal to the
+init process, which is denied because of the signal scoping restriction
+(``LL_SCOPED=s``)::
+
+ $ LL_FS_RO=/ LL_FS_RW=/ LL_SCOPED=s LL_FORCE_LOG=1 ./sandboxer kill 1
+
+This command generates two events, each identified with a unique serial
+number following a timestamp (``msg=audit(1729738800.268:30)``). The first
+event (serial ``30``) contains 4 records. The first record
+(``type=LANDLOCK_ACCESS``) shows an access denied by the domain `1a6fdc66f`.
+The cause of this denial is signal scopping restriction
+(``blockers=scope.signal``). The process that would have receive this signal
+is the init process (``opid=1 ocomm="systemd"``).
+
+The second record (``type=LANDLOCK_DOMAIN``) describes (``status=allocated``)
+domain `1a6fdc66f`. This domain was created by process ``286`` executing the
+``/root/sandboxer`` program launched by the root user.
+
+The third record (``type=SYSCALL``) describes the syscall, its provided
+arguments, its result (``success=no exit=-1``), and the process that called it.
+
+The fourth record (``type=PROCTITLE``) shows the command's name as an
+hexadecimal value. This can be translated with ``python -c
+'print(bytes.fromhex("6B696C6C0031"))'``.
+
+Finally, the last record (``type=LANDLOCK_DOMAIN``) is also the only one from
+the second event (serial ``31``). It is not tied to a direct user space action
+but an asynchronous one to free resources tied to a Landlock domain
+(``status=deallocated``). This can be useful to know that the following logs
+will not concern the domain ``1a6fdc66f`` anymore. This record also summarize
+the number of requests this domain denied (``denials=1``), whether they were
+logged or not.
+
+.. code-block::
+
+ type=LANDLOCK_ACCESS msg=audit(1729738800.268:30): domain=1a6fdc66f blockers=scope.signal opid=1 ocomm="systemd"
+ type=LANDLOCK_DOMAIN msg=audit(1729738800.268:30): domain=1a6fdc66f status=allocated mode=enforcing pid=286 uid=0 exe="/root/sandboxer" comm="sandboxer"
+ type=SYSCALL msg=audit(1729738800.268:30): arch=c000003e syscall=62 success=no exit=-1 [..] ppid=272 pid=286 auid=0 uid=0 gid=0 [...] comm="kill" [...]
+ type=PROCTITLE msg=audit(1729738800.268:30): proctitle=6B696C6C0031
+ type=LANDLOCK_DOMAIN msg=audit(1729738800.324:31): domain=1a6fdc66f status=deallocated denials=1
+
+Here is another example showcasing filesystem access control::
+
+ $ LL_FS_RO=/ LL_FS_RW=/tmp LL_FORCE_LOG=1 ./sandboxer sh -c "echo > /etc/passwd"
+
+The related audit logs contains 8 records from 3 different events (serials 33,
+34 and 35) created by the same domain `1a6fdc679`::
+
+ type=LANDLOCK_ACCESS msg=audit(1729738800.221:33): domain=1a6fdc679 blockers=fs.write_file path="/dev/tty" dev="devtmpfs" ino=9
+ type=LANDLOCK_DOMAIN msg=audit(1729738800.221:33): domain=1a6fdc679 status=allocated mode=enforcing pid=289 uid=0 exe="/root/sandboxer" comm="sandboxer"
+ type=SYSCALL msg=audit(1729738800.221:33): arch=c000003e syscall=257 success=no exit=-13 [...] ppid=272 pid=289 auid=0 uid=0 gid=0 [...] comm="sh" [...]
+ type=PROCTITLE msg=audit(1729738800.221:33): proctitle=7368002D63006563686F203E202F6574632F706173737764
+ type=LANDLOCK_ACCESS msg=audit(1729738800.221:34): domain=1a6fdc679 blockers=fs.write_file path="/etc/passwd" dev="vda2" ino=143821
+ type=SYSCALL msg=audit(1729738800.221:34): arch=c000003e syscall=257 success=no exit=-13 [...] ppid=272 pid=289 auid=0 uid=0 gid=0 [...] comm="sh" [...]
+ type=PROCTITLE msg=audit(1729738800.221:34): proctitle=7368002D63006563686F203E202F6574632F706173737764
+ type=LANDLOCK_DOMAIN msg=audit(1729738800.261:35): domain=1a6fdc679 status=deallocated denials=2
+
+
+Event filtering
+---------------
+
+If you get spammed with audit logs related to Landlock, this is either an
+attack attempt or a bug in the security policy. We can put in place some
+filters to limit noise with two complementary ways:
+
+- with sys_landlock_restrict_self()'s flags if we can fix the sandboxed
+ programs,
+- or with audit rules (see :manpage:`auditctl(8)`).
+
+Additional documentation
+========================
+
+* `Linux Audit Documentation`_
+* Documentation/userspace-api/landlock.rst
+* Documentation/security/landlock.rst
+* https://landlock.io
+
+.. Links
+.. _Linux Audit Documentation:
+ https://github.com/linux-audit/audit-documentation/wiki
diff --git a/Documentation/admin-guide/LSM/tomoyo.rst b/Documentation/admin-guide/LSM/tomoyo.rst
new file mode 100644
index 000000000000..bdb2c2e2a1b2
--- /dev/null
+++ b/Documentation/admin-guide/LSM/tomoyo.rst
@@ -0,0 +1,52 @@
+======
+TOMOYO
+======
+
+What is TOMOYO?
+===============
+
+TOMOYO is a name-based MAC extension (LSM module) for the Linux kernel.
+
+LiveCD-based tutorials are available at
+
+https://tomoyo.sourceforge.net/1.8/ubuntu12.04-live.html
+https://tomoyo.sourceforge.net/1.8/centos6-live.html
+
+Though these tutorials use non-LSM version of TOMOYO, they are useful for you
+to know what TOMOYO is.
+
+How to enable TOMOYO?
+=====================
+
+Build the kernel with ``CONFIG_SECURITY_TOMOYO=y`` and pass ``security=tomoyo`` on
+kernel's command line.
+
+Please see https://tomoyo.sourceforge.net/2.6/ for details.
+
+Where is documentation?
+=======================
+
+User <-> Kernel interface documentation is available at
+https://tomoyo.sourceforge.net/2.6/policy-specification/index.html .
+
+Materials we prepared for seminars and symposiums are available at
+https://sourceforge.net/projects/tomoyo/files/docs/ .
+Below lists are chosen from three aspects.
+
+What is TOMOYO?
+ TOMOYO Linux Overview
+ https://sourceforge.net/projects/tomoyo/files/docs/lca2009-takeda.pdf
+ TOMOYO Linux: pragmatic and manageable security for Linux
+ https://sourceforge.net/projects/tomoyo/files/docs/freedomhectaipei-tomoyo.pdf
+ TOMOYO Linux: A Practical Method to Understand and Protect Your Own Linux Box
+ https://sourceforge.net/projects/tomoyo/files/docs/PacSec2007-en-no-demo.pdf
+
+What can TOMOYO do?
+ Deep inside TOMOYO Linux
+ https://sourceforge.net/projects/tomoyo/files/docs/lca2009-kumaneko.pdf
+ The role of "pathname based access control" in security.
+ https://sourceforge.net/projects/tomoyo/files/docs/lfj2008-bof.pdf
+
+History of TOMOYO?
+ Realities of Mainlining
+ https://sourceforge.net/projects/tomoyo/files/docs/lfj2008.pdf
diff --git a/Documentation/admin-guide/RAS/address-translation.rst b/Documentation/admin-guide/RAS/address-translation.rst
new file mode 100644
index 000000000000..f0ca17b43cd3
--- /dev/null
+++ b/Documentation/admin-guide/RAS/address-translation.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Address translation
+===================
+
+x86 AMD
+-------
+
+Zen-based AMD systems include a Data Fabric that manages the layout of
+physical memory. Devices attached to the Fabric, like memory controllers,
+I/O, etc., may not have a complete view of the system physical memory map.
+These devices may provide a "normalized", i.e. device physical, address
+when reporting memory errors. Normalized addresses must be translated to
+a system physical address for the kernel to action on the memory.
+
+AMD Address Translation Library (CONFIG_AMD_ATL) provides translation for
+this case.
+
+Glossary of acronyms used in address translation for Zen-based systems
+
+* CCM = Cache Coherent Moderator
+* COD = Cluster-on-Die
+* COH_ST = Coherent Station
+* DF = Data Fabric
diff --git a/Documentation/admin-guide/RAS/error-decoding.rst b/Documentation/admin-guide/RAS/error-decoding.rst
new file mode 100644
index 000000000000..26a72f3fe5de
--- /dev/null
+++ b/Documentation/admin-guide/RAS/error-decoding.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Error decoding
+==============
+
+x86
+---
+
+Error decoding on AMD systems should be done using the rasdaemon tool:
+https://github.com/mchehab/rasdaemon/
+
+While the daemon is running, it would automatically log and decode
+errors. If not, one can still decode such errors by supplying the
+hardware information from the error::
+
+ $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca
+
+Also, the user can pass particular family and model to decode the error
+string::
+
+ $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca --family <CPU Family> --model <CPU Model> --bank <BANK_NUM>
diff --git a/Documentation/admin-guide/RAS/index.rst b/Documentation/admin-guide/RAS/index.rst
new file mode 100644
index 000000000000..f4087040a7c0
--- /dev/null
+++ b/Documentation/admin-guide/RAS/index.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. toctree::
+ :maxdepth: 2
+
+ main
+ error-decoding
+ address-translation
diff --git a/Documentation/admin-guide/RAS/main.rst b/Documentation/admin-guide/RAS/main.rst
new file mode 100644
index 000000000000..5a45db32c49b
--- /dev/null
+++ b/Documentation/admin-guide/RAS/main.rst
@@ -0,0 +1,1087 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==================================================
+Reliability, Availability and Serviceability (RAS)
+==================================================
+
+This documents different aspects of the RAS functionality present in the
+kernel.
+
+RAS concepts
+************
+
+Reliability, Availability and Serviceability (RAS) is a concept used on
+servers meant to measure their robustness.
+
+Reliability
+ is the probability that a system will produce correct outputs.
+
+ * Generally measured as Mean Time Between Failures (MTBF)
+ * Enhanced by features that help to avoid, detect and repair hardware faults
+
+Availability
+ is the probability that a system is operational at a given time
+
+ * Generally measured as a percentage of downtime per a period of time
+ * Often uses mechanisms to detect and correct hardware faults in
+ runtime;
+
+Serviceability (or maintainability)
+ is the simplicity and speed with which a system can be repaired or
+ maintained
+
+ * Generally measured on Mean Time Between Repair (MTBR)
+
+Improving RAS
+-------------
+
+In order to reduce systems downtime, a system should be capable of detecting
+hardware errors, and, when possible correcting them in runtime. It should
+also provide mechanisms to detect hardware degradation, in order to warn
+the system administrator to take the action of replacing a component before
+it causes data loss or system downtime.
+
+Among the monitoring measures, the most usual ones include:
+
+* CPU – detect errors at instruction execution and at L1/L2/L3 caches;
+* Memory – add error correction logic (ECC) to detect and correct errors;
+* I/O – add CRC checksums for transferred data;
+* Storage – RAID, journal file systems, checksums,
+ Self-Monitoring, Analysis and Reporting Technology (SMART).
+
+By monitoring the number of occurrences of error detections, it is possible
+to identify if the probability of hardware errors is increasing, and, on such
+case, do a preventive maintenance to replace a degraded component while
+those errors are correctable.
+
+Types of errors
+---------------
+
+Most mechanisms used on modern systems use technologies like Hamming
+Codes that allow error correction when the number of errors on a bit packet
+is below a threshold. If the number of errors is above, those mechanisms
+can indicate with a high degree of confidence that an error happened, but
+they can't correct.
+
+Also, sometimes an error occur on a component that it is not used. For
+example, a part of the memory that it is not currently allocated.
+
+That defines some categories of errors:
+
+* **Correctable Error (CE)** - the error detection mechanism detected and
+ corrected the error. Such errors are usually not fatal, although some
+ Kernel mechanisms allow the system administrator to consider them as fatal.
+
+* **Uncorrected Error (UE)** - the amount of errors happened above the error
+ correction threshold, and the system was unable to auto-correct.
+
+* **Fatal Error** - when an UE error happens on a critical component of the
+ system (for example, a piece of the Kernel got corrupted by an UE), the
+ only reliable way to avoid data corruption is to hang or reboot the machine.
+
+* **Non-fatal Error** - when an UE error happens on an unused component,
+ like a CPU in power down state or an unused memory bank, the system may
+ still run, eventually replacing the affected hardware by a hot spare,
+ if available.
+
+ Also, when an error happens on a userspace process, it is also possible to
+ kill such process and let userspace restart it.
+
+The mechanism for handling non-fatal errors is usually complex and may
+require the help of some userspace application, in order to apply the
+policy desired by the system administrator.
+
+Identifying a bad hardware component
+------------------------------------
+
+Just detecting a hardware flaw is usually not enough, as the system needs
+to pinpoint to the minimal replaceable unit (MRU) that should be exchanged
+to make the hardware reliable again.
+
+So, it requires not only error logging facilities, but also mechanisms that
+will translate the error message to the silkscreen or component label for
+the MRU.
+
+Typically, it is very complex for memory, as modern CPUs interlace memory
+from different memory modules, in order to provide a better performance. The
+DMI BIOS usually have a list of memory module labels, with can be obtained
+using the ``dmidecode`` tool. For example, on a desktop machine, it shows::
+
+ Memory Device
+ Total Width: 64 bits
+ Data Width: 64 bits
+ Size: 16384 MB
+ Form Factor: SODIMM
+ Set: None
+ Locator: ChannelA-DIMM0
+ Bank Locator: BANK 0
+ Type: DDR4
+ Type Detail: Synchronous
+ Speed: 2133 MHz
+ Rank: 2
+ Configured Clock Speed: 2133 MHz
+
+On the above example, a DDR4 SO-DIMM memory module is located at the
+system's memory labeled as "BANK 0", as given by the *bank locator* field.
+Please notice that, on such system, the *total width* is equal to the
+*data width*. It means that such memory module doesn't have error
+detection/correction mechanisms.
+
+Unfortunately, not all systems use the same field to specify the memory
+bank. On this example, from an older server, ``dmidecode`` shows::
+
+ Memory Device
+ Array Handle: 0x1000
+ Error Information Handle: Not Provided
+ Total Width: 72 bits
+ Data Width: 64 bits
+ Size: 8192 MB
+ Form Factor: DIMM
+ Set: 1
+ Locator: DIMM_A1
+ Bank Locator: Not Specified
+ Type: DDR3
+ Type Detail: Synchronous Registered (Buffered)
+ Speed: 1600 MHz
+ Rank: 2
+ Configured Clock Speed: 1600 MHz
+
+There, the DDR3 RDIMM memory module is located at the system's memory labeled
+as "DIMM_A1", as given by the *locator* field. Please notice that this
+memory module has 64 bits of *data width* and 72 bits of *total width*. So,
+it has 8 extra bits to be used by error detection and correction mechanisms.
+Such kind of memory is called Error-correcting code memory (ECC memory).
+
+To make things even worse, it is not uncommon that systems with different
+labels on their system's board to use exactly the same BIOS, meaning that
+the labels provided by the BIOS won't match the real ones.
+
+ECC memory
+----------
+
+As mentioned in the previous section, ECC memory has extra bits to be
+used for error correction. In the above example, a memory module has
+64 bits of *data width*, and 72 bits of *total width*. The extra 8
+bits which are used for the error detection and correction mechanisms
+are referred to as the *syndrome*\ [#f1]_\ [#f2]_.
+
+So, when the cpu requests the memory controller to write a word with
+*data width*, the memory controller calculates the *syndrome* in real time,
+using Hamming code, or some other error correction code, like SECDED+,
+producing a code with *total width* size. Such code is then written
+on the memory modules.
+
+At read, the *total width* bits code is converted back, using the same
+ECC code used on write, producing a word with *data width* and a *syndrome*.
+The word with *data width* is sent to the CPU, even when errors happen.
+
+The memory controller also looks at the *syndrome* in order to check if
+there was an error, and if the ECC code was able to fix such error.
+If the error was corrected, a Corrected Error (CE) happened. If not, an
+Uncorrected Error (UE) happened.
+
+The information about the CE/UE errors is stored on some special registers
+at the memory controller and can be accessed by reading such registers,
+either by BIOS, by some special CPUs or by Linux EDAC driver. On x86 64
+bit CPUs, such errors can also be retrieved via the Machine Check
+Architecture (MCA)\ [#f3]_.
+
+.. [#f1] Please notice that several memory controllers allow operation on a
+ mode called "Lock-Step", where it groups two memory modules together,
+ doing 128-bit reads/writes. That gives 16 bits for error correction, with
+ significantly improves the error correction mechanism, at the expense
+ that, when an error happens, there's no way to know what memory module is
+ to blame. So, it has to blame both memory modules.
+
+.. [#f2] Some memory controllers also allow using memory in mirror mode.
+ On such mode, the same data is written to two memory modules. At read,
+ the system checks both memory modules, in order to check if both provide
+ identical data. On such configuration, when an error happens, there's no
+ way to know what memory module is to blame. So, it has to blame both
+ memory modules (or 4 memory modules, if the system is also on Lock-step
+ mode).
+
+.. [#f3] For more details about the Machine Check Architecture (MCA),
+ please read Documentation/arch/x86/x86_64/machinecheck.rst at the Kernel tree.
+
+EDAC - Error Detection And Correction
+*************************************
+
+.. note::
+
+ "bluesmoke" was the name for this device driver subsystem when it
+ was "out-of-tree" and maintained at http://bluesmoke.sourceforge.net.
+ That site is mostly archaic now and can be used only for historical
+ purposes.
+
+ When the subsystem was pushed upstream for the first time, on
+ Kernel 2.6.16, it was renamed to ``EDAC``.
+
+Purpose
+-------
+
+The ``edac`` kernel module's goal is to detect and report hardware errors
+that occur within the computer system running under linux.
+
+Memory
+------
+
+Memory Correctable Errors (CE) and Uncorrectable Errors (UE) are the
+primary errors being harvested. These types of errors are harvested by
+the ``edac_mc`` device.
+
+Detecting CE events, then harvesting those events and reporting them,
+**can** but must not necessarily be a predictor of future UE events. With
+CE events only, the system can and will continue to operate as no data
+has been damaged yet.
+
+However, preventive maintenance and proactive part replacement of memory
+modules exhibiting CEs can reduce the likelihood of the dreaded UE events
+and system panics.
+
+Other hardware elements
+-----------------------
+
+A new feature for EDAC, the ``edac_device`` class of device, was added in
+the 2.6.23 version of the kernel.
+
+This new device type allows for non-memory type of ECC hardware detectors
+to have their states harvested and presented to userspace via the sysfs
+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 an edac_device device probably can be constructed to
+harvest and present that to userspace.
+
+
+PCI bus scanning
+----------------
+
+In addition, PCI devices are scanned for PCI Bus Parity and SERR Errors
+in order to determine if errors are occurring during data transfers.
+
+The presence of PCI Parity errors must be examined with a grain of salt.
+There are several add-in adapters that do **not** follow the PCI specification
+with regards to Parity generation and reporting. The specification says
+the vendor should tie the parity status bits to 0 if they do not intend
+to generate parity. Some vendors do not do this, and thus the parity bit
+can "float" giving false positives.
+
+There is a PCI device attribute located in sysfs that is checked by
+the EDAC PCI scanning code. If that attribute is set, PCI parity/error
+scanning is skipped for that device. The attribute is::
+
+ broken_parity_status
+
+and is located in ``/sys/devices/pci<XXX>/0000:XX:YY.Z`` directories for
+PCI devices.
+
+
+Versioning
+----------
+
+EDAC is composed of a "core" module (``edac_core.ko``) and several Memory
+Controller (MC) driver modules. On a given system, the CORE is loaded
+and one MC driver will be loaded. Both the CORE and the MC driver (or
+``edac_device`` driver) have individual versions that reflect current
+release level of their respective modules.
+
+Thus, to "report" on what version a system is running, one must report
+both the CORE's and the MC driver's versions.
+
+
+Loading
+-------
+
+If ``edac`` was statically linked with the kernel then no loading
+is necessary. If ``edac`` was built as modules then simply modprobe
+the ``edac`` pieces that you need. You should be able to modprobe
+hardware-specific modules and have the dependencies load the necessary
+core modules.
+
+Example::
+
+ $ modprobe amd76x_edac
+
+loads both the ``amd76x_edac.ko`` memory controller module and the
+``edac_mc.ko`` core module.
+
+
+Sysfs interface
+---------------
+
+EDAC presents a ``sysfs`` interface for control and reporting purposes. It
+lives in the /sys/devices/system/edac directory.
+
+Within this directory there currently reside 2 components:
+
+ ======= ==============================
+ mc memory controller(s) system
+ pci PCI control and status system
+ ======= ==============================
+
+
+
+Memory Controller (mc) Model
+----------------------------
+
+Each ``mc`` device controls a set of memory modules [#f4]_. These modules
+are laid out in a Chip-Select Row (``csrowX``) and Channel table (``chX``).
+There can be multiple csrows and multiple channels.
+
+.. [#f4] Nowadays, the term DIMM (Dual In-line Memory Module) is widely
+ used to refer to a memory module, although there are other memory
+ packaging alternatives, like SO-DIMM, SIMM, etc. The UEFI
+ specification (Version 2.7) defines a memory module in the Common
+ Platform Error Record (CPER) section to be an SMBIOS Memory Device
+ (Type 17). Along this document, and inside the EDAC subsystem, the term
+ "dimm" is used for all memory modules, even when they use a
+ different kind of packaging.
+
+Memory controllers allow for several csrows, with 8 csrows being a
+typical value. Yet, the actual number of csrows depends on the layout of
+a given motherboard, memory controller and memory module characteristics.
+
+Dual channels allow for dual data length (e. g. 128 bits, on 64 bit systems)
+data transfers to/from the CPU from/to memory. Some newer chipsets allow
+for more than 2 channels, like Fully Buffered DIMMs (FB-DIMMs) memory
+controllers. The following example will assume 2 channels:
+
+ +------------+-----------------------+
+ | CS Rows | Channels |
+ +------------+-----------+-----------+
+ | | ``ch0`` | ``ch1`` |
+ +============+===========+===========+
+ | |**DIMM_A0**|**DIMM_B0**|
+ +------------+-----------+-----------+
+ | ``csrow0`` | rank0 | rank0 |
+ +------------+-----------+-----------+
+ | ``csrow1`` | rank1 | rank1 |
+ +------------+-----------+-----------+
+ | |**DIMM_A1**|**DIMM_B1**|
+ +------------+-----------+-----------+
+ | ``csrow2`` | rank0 | rank0 |
+ +------------+-----------+-----------+
+ | ``csrow3`` | rank1 | rank1 |
+ +------------+-----------+-----------+
+
+In the above example, there are 4 physical slots on the motherboard
+for memory DIMMs:
+
+ +---------+---------+
+ | DIMM_A0 | DIMM_B0 |
+ +---------+---------+
+ | DIMM_A1 | DIMM_B1 |
+ +---------+---------+
+
+Labels for these slots are usually silk-screened on the motherboard.
+Slots labeled ``A`` are channel 0 in this example. Slots labeled ``B`` are
+channel 1. Notice that there are two csrows possible on a physical DIMM.
+These csrows are allocated their csrow assignment based on the slot into
+which the memory DIMM is placed. Thus, when 1 DIMM is placed in each
+Channel, the csrows cross both DIMMs.
+
+Memory DIMMs come single or dual "ranked". A rank is a populated csrow.
+In the example above 2 dual ranked DIMMs are similarly placed. Thus,
+both csrow0 and csrow1 are populated. On the other hand, when 2 single
+ranked DIMMs are placed in slots DIMM_A0 and DIMM_B0, then they will
+have just one csrow (csrow0) and csrow1 will be empty. The pattern
+repeats itself for csrow2 and csrow3. Also note that some memory
+controllers don't have any logic to identify the memory module, see
+``rankX`` directories below.
+
+The representation of the above is reflected in the directory
+tree in EDAC's sysfs interface. Starting in directory
+``/sys/devices/system/edac/mc``, each memory controller will be
+represented by its own ``mcX`` directory, where ``X`` is the
+index of the MC::
+
+ ..../edac/mc/
+ |
+ |->mc0
+ |->mc1
+ |->mc2
+ ....
+
+Within each of the ``mcX`` directory are several EDAC control and
+attribute files.
+
+``mcX`` directories
+-------------------
+
+In ``mcX`` directories are EDAC control and attribute files for
+this ``X`` instance of the memory controllers.
+
+For a description of the sysfs API, please see:
+
+ Documentation/ABI/testing/sysfs-devices-edac
+
+
+``dimmX`` or ``rankX`` directories
+----------------------------------
+
+The recommended way to use the EDAC subsystem is to look at the information
+provided by the ``dimmX`` or ``rankX`` directories [#f5]_.
+
+A typical EDAC system has the following structure under
+``/sys/devices/system/edac/``\ [#f6]_::
+
+ /sys/devices/system/edac/
+ ├── mc
+ │   ├── mc0
+ │   │   ├── ce_count
+ │   │   ├── ce_noinfo_count
+ │   │   ├── dimm0
+ │   │   │   ├── dimm_ce_count
+ │   │   │   ├── dimm_dev_type
+ │   │   │   ├── dimm_edac_mode
+ │   │   │   ├── dimm_label
+ │   │   │   ├── dimm_location
+ │   │   │   ├── dimm_mem_type
+ │   │   │   ├── dimm_ue_count
+ │   │   │   ├── size
+ │   │   │   └── uevent
+ │   │   ├── max_location
+ │   │   ├── mc_name
+ │   │   ├── reset_counters
+ │   │   ├── seconds_since_reset
+ │   │   ├── size_mb
+ │   │   ├── ue_count
+ │   │   ├── ue_noinfo_count
+ │   │   └── uevent
+ │   ├── mc1
+ │   │   ├── ce_count
+ │   │   ├── ce_noinfo_count
+ │   │   ├── dimm0
+ │   │   │   ├── dimm_ce_count
+ │   │   │   ├── dimm_dev_type
+ │   │   │   ├── dimm_edac_mode
+ │   │   │   ├── dimm_label
+ │   │   │   ├── dimm_location
+ │   │   │   ├── dimm_mem_type
+ │   │   │   ├── dimm_ue_count
+ │   │   │   ├── size
+ │   │   │   └── uevent
+ │   │   ├── max_location
+ │   │   ├── mc_name
+ │   │   ├── reset_counters
+ │   │   ├── seconds_since_reset
+ │   │   ├── size_mb
+ │   │   ├── ue_count
+ │   │   ├── ue_noinfo_count
+ │   │   └── uevent
+ │   └── uevent
+ └── uevent
+
+In the ``dimmX`` directories are EDAC control and attribute files for
+this ``X`` memory module:
+
+- ``size`` - Total memory managed by this csrow attribute file
+
+ This attribute file displays, in count of megabytes, the memory
+ that this csrow contains.
+
+- ``dimm_ue_count`` - Uncorrectable Errors count attribute file
+
+ This attribute file displays the total count of uncorrectable
+ errors that have occurred on this DIMM. If panic_on_ue is set
+ this counter will not have a chance to increment, since EDAC
+ will panic the system.
+
+- ``dimm_ce_count`` - Correctable Errors count attribute file
+
+ This attribute file displays the total count of correctable
+ errors that have occurred on this DIMM. This count is very
+ important to examine. CEs provide early indications that a
+ DIMM is beginning to fail. This count field should be
+ monitored for non-zero values and report such information
+ to the system administrator.
+
+- ``dimm_dev_type`` - Device type attribute file
+
+ This attribute file will display what type of DRAM device is
+ being utilized on this DIMM.
+ Examples:
+
+ - x1
+ - x2
+ - x4
+ - x8
+
+- ``dimm_edac_mode`` - EDAC Mode of operation attribute file
+
+ This attribute file will display what type of Error detection
+ and correction is being utilized.
+
+- ``dimm_label`` - memory module label control file
+
+ This control file allows this DIMM to have a label assigned
+ to it. With this label in the module, when errors occur
+ the output can provide the DIMM label in the system log.
+ This becomes vital for panic events to isolate the
+ cause of the UE event.
+
+ DIMM Labels must be assigned after booting, with information
+ that correctly identifies the physical slot with its
+ silk screen label. This information is currently very
+ motherboard specific and determination of this information
+ must occur in userland at this time.
+
+- ``dimm_location`` - location of the memory module
+
+ The location can have up to 3 levels, and describe how the
+ memory controller identifies the location of a memory module.
+ Depending on the type of memory and memory controller, it
+ can be:
+
+ - *csrow* and *channel* - used when the memory controller
+ doesn't identify a single DIMM - e. g. in ``rankX`` dir;
+ - *branch*, *channel*, *slot* - typically used on FB-DIMM memory
+ controllers;
+ - *channel*, *slot* - used on Nehalem and newer Intel drivers.
+
+- ``dimm_mem_type`` - Memory Type attribute file
+
+ This attribute file will display what type of memory is currently
+ on this csrow. Normally, either buffered or unbuffered memory.
+ Examples:
+
+ - Registered-DDR
+ - Unbuffered-DDR
+
+.. [#f5] On some systems, the memory controller doesn't have any logic
+ to identify the memory module. On such systems, the directory is called ``rankX``.
+ On modern Intel memory controllers, the memory controller identifies the
+ memory modules directly. On such systems, the directory is called ``dimmX``.
+
+.. [#f6] There are also some ``power`` directories and ``subsystem``
+ symlinks inside the sysfs mapping that are automatically created by
+ the sysfs subsystem. Currently, they serve no purpose.
+
+
+System Logging
+--------------
+
+If logging for UEs and CEs is enabled, then system logs will contain
+information indicating that errors have been detected::
+
+ EDAC MC0: CE page 0x283, offset 0xce0, grain 8, syndrome 0x6ec3, row 0, channel 1 "DIMM_B1": amd76x_edac
+ EDAC MC0: CE page 0x1e5, offset 0xfb0, grain 8, syndrome 0xb741, row 0, channel 1 "DIMM_B1": amd76x_edac
+
+
+The structure of the message is:
+
+ +---------------------------------------+-------------+
+ | Content | Example |
+ +=======================================+=============+
+ | The memory controller | MC0 |
+ +---------------------------------------+-------------+
+ | Error type | CE |
+ +---------------------------------------+-------------+
+ | Memory page | 0x283 |
+ +---------------------------------------+-------------+
+ | Offset in the page | 0xce0 |
+ +---------------------------------------+-------------+
+ | The byte granularity | grain 8 |
+ | or resolution of the error | |
+ +---------------------------------------+-------------+
+ | The error syndrome | 0xb741 |
+ +---------------------------------------+-------------+
+ | Memory row | row 0 |
+ +---------------------------------------+-------------+
+ | Memory channel | channel 1 |
+ +---------------------------------------+-------------+
+ | DIMM label, if set prior | DIMM B1 |
+ +---------------------------------------+-------------+
+ | And then an optional, driver-specific | |
+ | message that may have additional | |
+ | information. | |
+ +---------------------------------------+-------------+
+
+Both UEs and CEs with no info will lack all but memory controller, error
+type, a notice of "no info" and then an optional, driver-specific error
+message.
+
+
+PCI Bus Parity Detection
+------------------------
+
+On Header Type 00 devices, the primary status is looked at for any
+parity error regardless of whether parity is enabled on the device or
+not. (The spec indicates parity is generated in some cases). On Header
+Type 01 bridges, the secondary status register is also looked at to see
+if parity occurred on the bus on the other side of the bridge.
+
+
+Sysfs configuration
+-------------------
+
+Under ``/sys/devices/system/edac/pci`` are control and attribute files as
+follows:
+
+
+- ``check_pci_parity`` - Enable/Disable PCI Parity checking control file
+
+ This control file enables or disables the PCI Bus Parity scanning
+ operation. Writing a 1 to this file enables the scanning. Writing
+ a 0 to this file disables the scanning.
+
+ Enable::
+
+ echo "1" >/sys/devices/system/edac/pci/check_pci_parity
+
+ Disable::
+
+ echo "0" >/sys/devices/system/edac/pci/check_pci_parity
+
+
+- ``pci_parity_count`` - Parity Count
+
+ This attribute file will display the number of parity errors that
+ have been detected.
+
+
+Module parameters
+-----------------
+
+- ``edac_mc_panic_on_ue`` - Panic on UE control file
+
+ An uncorrectable error will cause a machine panic. This is usually
+ desirable. It is a bad idea to continue when an uncorrectable error
+ occurs - it is indeterminate what was uncorrected and the operating
+ system context might be so mangled that continuing will lead to further
+ corruption. If the kernel has MCE configured, then EDAC will never
+ notice the UE.
+
+ LOAD TIME::
+
+ module/kernel parameter: edac_mc_panic_on_ue=[0|1]
+
+ RUN TIME::
+
+ echo "1" > /sys/module/edac_core/parameters/edac_mc_panic_on_ue
+
+
+- ``edac_mc_log_ue`` - Log UE control file
+
+
+ Generate kernel messages describing uncorrectable errors. These errors
+ are reported through the system message log system. UE statistics
+ will be accumulated even when UE logging is disabled.
+
+ LOAD TIME::
+
+ module/kernel parameter: edac_mc_log_ue=[0|1]
+
+ RUN TIME::
+
+ echo "1" > /sys/module/edac_core/parameters/edac_mc_log_ue
+
+
+- ``edac_mc_log_ce`` - Log CE control file
+
+
+ Generate kernel messages describing correctable errors. These
+ errors are reported through the system message log system.
+ CE statistics will be accumulated even when CE logging is disabled.
+
+ LOAD TIME::
+
+ module/kernel parameter: edac_mc_log_ce=[0|1]
+
+ RUN TIME::
+
+ echo "1" > /sys/module/edac_core/parameters/edac_mc_log_ce
+
+
+- ``edac_mc_poll_msec`` - Polling period control file
+
+
+ The time period, in milliseconds, for polling for error information.
+ Too small a value wastes resources. Too large a value might delay
+ necessary handling of errors and might loose valuable information for
+ locating the error. 1000 milliseconds (once each second) is the current
+ default. Systems which require all the bandwidth they can get, may
+ increase this.
+
+ LOAD TIME::
+
+ module/kernel parameter: edac_mc_poll_msec=[0|1]
+
+ RUN TIME::
+
+ echo "1000" > /sys/module/edac_core/parameters/edac_mc_poll_msec
+
+
+- ``panic_on_pci_parity`` - Panic on PCI PARITY Error
+
+
+ This control file enables or disables panicking when a parity
+ error has been detected.
+
+
+ module/kernel parameter::
+
+ edac_panic_on_pci_pe=[0|1]
+
+ Enable::
+
+ echo "1" > /sys/module/edac_core/parameters/edac_panic_on_pci_pe
+
+ Disable::
+
+ echo "0" > /sys/module/edac_core/parameters/edac_panic_on_pci_pe
+
+
+
+EDAC device type
+----------------
+
+In the header file, edac_pci.h, there is a series of edac_device structures
+and APIs for the EDAC_DEVICE.
+
+User space access to an edac_device is through the sysfs interface.
+
+At the location ``/sys/devices/system/edac`` (sysfs) new edac_device devices
+will appear.
+
+There is a three level tree beneath the above ``edac`` directory. For example,
+the ``test_device_edac`` device (found at the http://bluesmoke.sourceforget.net
+website) installs itself as::
+
+ /sys/devices/system/edac/test-instance
+
+in this directory are various controls, a symlink and one or more ``instance``
+directories.
+
+The standard default controls are:
+
+ ============== =======================================================
+ log_ce boolean to log CE events
+ log_ue boolean to log UE events
+ panic_on_ue boolean to ``panic`` the system if an UE is encountered
+ (default off, can be set true via startup script)
+ poll_msec time period between POLL cycles for events
+ ============== =======================================================
+
+The test_device_edac device adds at least one of its own custom control:
+
+ ============== ==================================================
+ test_bits which in the current test driver does nothing but
+ show how it is installed. A ported driver can
+ add one or more such controls and/or attributes
+ for specific uses.
+ One out-of-tree driver uses controls here to allow
+ for ERROR INJECTION operations to hardware
+ injection registers
+ ============== ==================================================
+
+The symlink points to the 'struct dev' that is registered for this edac_device.
+
+Instances
+---------
+
+One or more instance directories are present. For the ``test_device_edac``
+case:
+
+ +----------------+
+ | test-instance0 |
+ +----------------+
+
+
+In this directory there are two default counter attributes, which are totals of
+counter in deeper subdirectories.
+
+ ============== ====================================
+ ce_count total of CE events of subdirectories
+ ue_count total of UE events of subdirectories
+ ============== ====================================
+
+Blocks
+------
+
+At the lowest directory level is the ``block`` directory. There can be 0, 1
+or more blocks specified in each instance:
+
+ +-------------+
+ | test-block0 |
+ +-------------+
+
+In this directory the default attributes are:
+
+ ============== ================================================
+ ce_count which is counter of CE events for this ``block``
+ of hardware being monitored
+ ue_count which is counter of UE events for this ``block``
+ of hardware being monitored
+ ============== ================================================
+
+
+The ``test_device_edac`` device adds 4 attributes and 1 control:
+
+ ================== ====================================================
+ test-block-bits-0 for every POLL cycle this counter
+ is incremented
+ test-block-bits-1 every 10 cycles, this counter is bumped once,
+ and test-block-bits-0 is set to 0
+ test-block-bits-2 every 100 cycles, this counter is bumped once,
+ and test-block-bits-1 is set to 0
+ test-block-bits-3 every 1000 cycles, this counter is bumped once,
+ and test-block-bits-2 is set to 0
+ ================== ====================================================
+
+
+ ================== ====================================================
+ reset-counters writing ANY thing to this control will
+ reset all the above counters.
+ ================== ====================================================
+
+
+Use of the ``test_device_edac`` driver should enable any others to create their own
+unique drivers for their hardware systems.
+
+The ``test_device_edac`` sample driver is located at the
+http://bluesmoke.sourceforge.net project site for EDAC.
+
+
+Usage of EDAC APIs on Nehalem and newer Intel CPUs
+--------------------------------------------------
+
+On older Intel architectures, the memory controller was part of the North
+Bridge chipset. Nehalem, Sandy Bridge, Ivy Bridge, Haswell, Sky Lake and
+newer Intel architectures integrated an enhanced version of the memory
+controller (MC) inside the CPUs.
+
+This chapter will cover the differences of the enhanced memory controllers
+found on newer Intel CPUs, such as ``i7core_edac``, ``sb_edac`` and
+``sbx_edac`` drivers.
+
+.. note::
+
+ The Xeon E7 processor families use a separate chip for the memory
+ controller, called Intel Scalable Memory Buffer. This section doesn't
+ apply for such families.
+
+1) There is one Memory Controller per Quick Patch Interconnect
+ (QPI). At the driver, the term "socket" means one QPI. This is
+ associated with a physical CPU socket.
+
+ Each MC have 3 physical read channels, 3 physical write channels and
+ 3 logic channels. The driver currently sees it as just 3 channels.
+ Each channel can have up to 3 DIMMs.
+
+ The minimum known unity is DIMMs. There are no information about csrows.
+ As EDAC API maps the minimum unity is csrows, the driver sequentially
+ maps channel/DIMM into different csrows.
+
+ For example, supposing the following layout::
+
+ Ch0 phy rd0, wr0 (0x063f4031): 2 ranks, UDIMMs
+ dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400
+ dimm 1 1024 Mb offset: 4, bank: 8, rank: 1, row: 0x4000, col: 0x400
+ Ch1 phy rd1, wr1 (0x063f4031): 2 ranks, UDIMMs
+ dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400
+ Ch2 phy rd3, wr3 (0x063f4031): 2 ranks, UDIMMs
+ dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400
+
+ The driver will map it as::
+
+ csrow0: channel 0, dimm0
+ csrow1: channel 0, dimm1
+ csrow2: channel 1, dimm0
+ csrow3: channel 2, dimm0
+
+ exports one DIMM per csrow.
+
+ Each QPI is exported as a different memory controller.
+
+2) The MC has the ability to inject errors to test drivers. The drivers
+ implement this functionality via some error injection nodes:
+
+ For injecting a memory error, there are some sysfs nodes, under
+ ``/sys/devices/system/edac/mc/mc?/``:
+
+ - ``inject_addrmatch/*``:
+ Controls the error injection mask register. It is possible to specify
+ several characteristics of the address to match an error code::
+
+ dimm = the affected dimm. Numbers are relative to a channel;
+ rank = the memory rank;
+ channel = the channel that will generate an error;
+ bank = the affected bank;
+ page = the page address;
+ column (or col) = the address column.
+
+ each of the above values can be set to "any" to match any valid value.
+
+ At driver init, all values are set to any.
+
+ For example, to generate an error at rank 1 of dimm 2, for any channel,
+ any bank, any page, any column::
+
+ echo 2 >/sys/devices/system/edac/mc/mc0/inject_addrmatch/dimm
+ echo 1 >/sys/devices/system/edac/mc/mc0/inject_addrmatch/rank
+
+ To return to the default behaviour of matching any, you can do::
+
+ echo any >/sys/devices/system/edac/mc/mc0/inject_addrmatch/dimm
+ echo any >/sys/devices/system/edac/mc/mc0/inject_addrmatch/rank
+
+ - ``inject_eccmask``:
+ specifies what bits will have troubles,
+
+ - ``inject_section``:
+ specifies what ECC cache section will get the error::
+
+ 3 for both
+ 2 for the highest
+ 1 for the lowest
+
+ - ``inject_type``:
+ specifies the type of error, being a combination of the following bits::
+
+ bit 0 - repeat
+ bit 1 - ecc
+ bit 2 - parity
+
+ - ``inject_enable``:
+ starts the error generation when something different than 0 is written.
+
+ All inject vars can be read. root permission is needed for write.
+
+ Datasheet states that the error will only be generated after a write on an
+ address that matches inject_addrmatch. It seems, however, that reading will
+ also produce an error.
+
+ For example, the following code will generate an error for any write access
+ at socket 0, on any DIMM/address on channel 2::
+
+ echo 2 >/sys/devices/system/edac/mc/mc0/inject_addrmatch/channel
+ echo 2 >/sys/devices/system/edac/mc/mc0/inject_type
+ echo 64 >/sys/devices/system/edac/mc/mc0/inject_eccmask
+ echo 3 >/sys/devices/system/edac/mc/mc0/inject_section
+ echo 1 >/sys/devices/system/edac/mc/mc0/inject_enable
+ dd if=/dev/mem of=/dev/null seek=16k bs=4k count=1 >& /dev/null
+
+ For socket 1, it is needed to replace "mc0" by "mc1" at the above
+ commands.
+
+ The generated error message will look like::
+
+ EDAC MC0: UE row 0, channel-a= 0 channel-b= 0 labels "-": NON_FATAL (addr = 0x0075b980, socket=0, Dimm=0, Channel=2, syndrome=0x00000040, count=1, Err=8c0000400001009f:4000080482 (read error: read ECC error))
+
+3) Corrected Error memory register counters
+
+ Those newer MCs have some registers to count memory errors. The driver
+ uses those registers to report Corrected Errors on devices with Registered
+ DIMMs.
+
+ However, those counters don't work with Unregistered DIMM. As the chipset
+ offers some counters that also work with UDIMMs (but with a worse level of
+ granularity than the default ones), the driver exposes those registers for
+ UDIMM memories.
+
+ They can be read by looking at the contents of ``all_channel_counts/``::
+
+ $ for i in /sys/devices/system/edac/mc/mc0/all_channel_counts/*; do echo $i; cat $i; done
+ /sys/devices/system/edac/mc/mc0/all_channel_counts/udimm0
+ 0
+ /sys/devices/system/edac/mc/mc0/all_channel_counts/udimm1
+ 0
+ /sys/devices/system/edac/mc/mc0/all_channel_counts/udimm2
+ 0
+
+ What happens here is that errors on different csrows, but at the same
+ dimm number will increment the same counter.
+ So, in this memory mapping::
+
+ csrow0: channel 0, dimm0
+ csrow1: channel 0, dimm1
+ csrow2: channel 1, dimm0
+ csrow3: channel 2, dimm0
+
+ The hardware will increment udimm0 for an error at the first dimm at either
+ csrow0, csrow2 or csrow3;
+
+ The hardware will increment udimm1 for an error at the second dimm at either
+ csrow0, csrow2 or csrow3;
+
+ The hardware will increment udimm2 for an error at the third dimm at either
+ csrow0, csrow2 or csrow3;
+
+4) Standard error counters
+
+ The standard error counters are generated when an mcelog error is received
+ by the driver. Since, with UDIMM, this is counted by software, it is
+ possible that some errors could be lost. With RDIMM's, they display the
+ contents of the registers
+
+Reference documents used on ``amd64_edac``
+------------------------------------------
+
+``amd64_edac`` module is based on the following documents
+(available from http://support.amd.com/en-us/search/tech-docs):
+
+1. :Title: BIOS and Kernel Developer's Guide for AMD Athlon 64 and AMD
+ Opteron Processors
+ :AMD publication #: 26094
+ :Revision: 3.26
+ :Link: http://support.amd.com/TechDocs/26094.PDF
+
+2. :Title: BIOS and Kernel Developer's Guide for AMD NPT Family 0Fh
+ Processors
+ :AMD publication #: 32559
+ :Revision: 3.00
+ :Issue Date: May 2006
+ :Link: http://support.amd.com/TechDocs/32559.pdf
+
+3. :Title: BIOS and Kernel Developer's Guide (BKDG) For AMD Family 10h
+ Processors
+ :AMD publication #: 31116
+ :Revision: 3.00
+ :Issue Date: September 07, 2007
+ :Link: http://support.amd.com/TechDocs/31116.pdf
+
+4. :Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 15h
+ Models 30h-3Fh Processors
+ :AMD publication #: 49125
+ :Revision: 3.06
+ :Issue Date: 2/12/2015 (latest release)
+ :Link: http://support.amd.com/TechDocs/49125_15h_Models_30h-3Fh_BKDG.pdf
+
+5. :Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 15h
+ Models 60h-6Fh Processors
+ :AMD publication #: 50742
+ :Revision: 3.01
+ :Issue Date: 7/23/2015 (latest release)
+ :Link: http://support.amd.com/TechDocs/50742_15h_Models_60h-6Fh_BKDG.pdf
+
+6. :Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 16h
+ Models 00h-0Fh Processors
+ :AMD publication #: 48751
+ :Revision: 3.03
+ :Issue Date: 2/23/2015 (latest release)
+ :Link: http://support.amd.com/TechDocs/48751_16h_bkdg.pdf
+
+Credits
+=======
+
+* Written by Doug Thompson <dougthompson@xmission.com>
+
+ - 7 Dec 2005
+ - 17 Jul 2007 Updated
+
+* |copy| Mauro Carvalho Chehab
+
+ - 05 Aug 2009 Nehalem interface
+ - 26 Oct 2016 Converted to ReST and cleanups at the Nehalem section
+
+* EDAC authors/maintainers:
+
+ - Doug Thompson, Dave Jiang, Dave Peterson et al,
+ - Mauro Carvalho Chehab
+ - Borislav Petkov
+ - original author: Thayne Harbaugh
diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst
new file mode 100644
index 000000000000..05301f03b717
--- /dev/null
+++ b/Documentation/admin-guide/README.rst
@@ -0,0 +1,360 @@
+.. _readme:
+
+Linux kernel release 6.x <http://kernel.org/>
+=============================================
+
+These are the release notes for Linux version 6. Read them carefully,
+as they tell you what this is all about, explain how to install the
+kernel, and what to do if something goes wrong.
+
+What is Linux?
+--------------
+
+ Linux is a clone of the operating system Unix, written from scratch by
+ Linus Torvalds with assistance from a loosely-knit team of hackers across
+ the Net. It aims towards POSIX and Single UNIX Specification compliance.
+
+ It has all the features you would expect in a modern fully-fledged Unix,
+ including true multitasking, virtual memory, shared libraries, demand
+ loading, shared copy-on-write executables, proper memory management,
+ and multistack networking including IPv4 and IPv6.
+
+ It is distributed under the GNU General Public License v2 - see the
+ accompanying COPYING file for more details.
+
+On what hardware does it run?
+-----------------------------
+
+ Although originally developed first for 32-bit x86-based PCs (386 or higher),
+ today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and
+ UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell,
+ IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64 Xtensa, and
+ ARC architectures.
+
+ Linux is easily portable to most general-purpose 32- or 64-bit architectures
+ as long as they have a paged memory management unit (PMMU) and a port of the
+ GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has
+ also been ported to a number of architectures without a PMMU, although
+ functionality is then obviously somewhat limited.
+ Linux has also been ported to itself. You can now run the kernel as a
+ userspace application - this is called UserMode Linux (UML).
+
+Documentation
+-------------
+
+ - There is a lot of documentation available both in electronic form on
+ the Internet and in books, both Linux-specific and pertaining to
+ general UNIX questions. I'd recommend looking into the documentation
+ subdirectories on any Linux FTP site for the LDP (Linux Documentation
+ Project) books. This README is not meant to be documentation on the
+ system: there are much better sources available.
+
+ - There are various README files in the Documentation/ subdirectory:
+ these typically contain kernel-specific installation notes for some
+ drivers for example. Please read the
+ :ref:`Documentation/process/changes.rst <changes>` file, as it
+ contains information about the problems, which may result by upgrading
+ your kernel.
+
+Installing the kernel source
+----------------------------
+
+ - If you install the full sources, put the kernel tarball in a
+ directory where you have permissions (e.g. your home directory) and
+ unpack it::
+
+ xz -cd linux-6.x.tar.xz | tar xvf -
+
+ Replace "X" with the version number of the latest kernel.
+
+ Do NOT use the /usr/src/linux area! This area has a (usually
+ incomplete) set of kernel headers that are used by the library header
+ files. They should match the library, and not get messed up by
+ whatever the kernel-du-jour happens to be.
+
+ - You can also upgrade between 6.x releases by patching. Patches are
+ distributed in the xz format. To install by patching, get all the
+ newer patch files, enter the top level directory of the kernel source
+ (linux-6.x) and execute::
+
+ xz -cd ../patch-6.x.xz | patch -p1
+
+ Replace "x" for all versions bigger than the version "x" of your current
+ source tree, **in_order**, and you should be ok. You may want to remove
+ the backup files (some-file-name~ or some-file-name.orig), and make sure
+ that there are no failed patches (some-file-name# or some-file-name.rej).
+ If there are, either you or I have made a mistake.
+
+ Unlike patches for the 6.x kernels, patches for the 6.x.y kernels
+ (also known as the -stable kernels) are not incremental but instead apply
+ directly to the base 6.x kernel. For example, if your base kernel is 6.0
+ and you want to apply the 6.0.3 patch, you must not first apply the 6.0.1
+ and 6.0.2 patches. Similarly, if you are running kernel version 6.0.2 and
+ want to jump to 6.0.3, you must first reverse the 6.0.2 patch (that is,
+ patch -R) **before** applying the 6.0.3 patch. You can read more on this in
+ :ref:`Documentation/process/applying-patches.rst <applying_patches>`.
+
+ Alternatively, the script patch-kernel can be used to automate this
+ process. It determines the current kernel version and applies any
+ patches found::
+
+ linux/scripts/patch-kernel linux
+
+ The first argument in the command above is the location of the
+ kernel source. Patches are applied from the current directory, but
+ an alternative directory can be specified as the second argument.
+
+ - Make sure you have no stale .o files and dependencies lying around::
+
+ cd linux
+ make mrproper
+
+ You should now have the sources correctly installed.
+
+Software requirements
+---------------------
+
+ Compiling and running the 6.x kernels requires up-to-date
+ versions of various software packages. Consult
+ :ref:`Documentation/process/changes.rst <changes>` for the minimum version numbers
+ required and how to get updates for these packages. Beware that using
+ excessively old versions of these packages can cause indirect
+ errors that are very difficult to track down, so don't assume that
+ you can just update packages when obvious problems arise during
+ build or operation.
+
+Build directory for the kernel
+------------------------------
+
+ When compiling the kernel, all output files will per default be
+ stored together with the kernel source code.
+ Using the option ``make O=output/dir`` allows you to specify an alternate
+ place for the output files (including .config).
+ Example::
+
+ kernel source code: /usr/src/linux-6.x
+ build directory: /home/name/build/kernel
+
+ To configure and build the kernel, use::
+
+ cd /usr/src/linux-6.x
+ make O=/home/name/build/kernel menuconfig
+ make O=/home/name/build/kernel
+ sudo make O=/home/name/build/kernel modules_install install
+
+ Please note: If the ``O=output/dir`` option is used, then it must be
+ used for all invocations of make.
+
+Configuring the kernel
+----------------------
+
+ Do not skip this step even if you are only upgrading one minor
+ version. New configuration options are added in each release, and
+ odd problems will turn up if the configuration files are not set up
+ as expected. If you want to carry your existing configuration to a
+ new version with minimal work, use ``make oldconfig``, which will
+ only ask you for the answers to new questions.
+
+ - Alternative configuration commands are::
+
+ "make config" Plain text interface.
+
+ "make menuconfig" Text based color menus, radiolists & dialogs.
+
+ "make nconfig" Enhanced text based color menus.
+
+ "make xconfig" Qt based configuration tool.
+
+ "make gconfig" GTK based configuration tool.
+
+ "make oldconfig" Default all questions based on the contents of
+ your existing ./.config file and asking about
+ new config symbols.
+
+ "make olddefconfig"
+ Like above, but sets new symbols to their default
+ values without prompting.
+
+ "make defconfig" Create a ./.config file by using the default
+ symbol values from either arch/$ARCH/configs/defconfig
+ or arch/$ARCH/configs/${PLATFORM}_defconfig,
+ depending on the architecture.
+
+ "make ${PLATFORM}_defconfig"
+ Create a ./.config file by using the default
+ symbol values from
+ arch/$ARCH/configs/${PLATFORM}_defconfig.
+ Use "make help" to get a list of all available
+ platforms of your architecture.
+
+ "make allyesconfig"
+ Create a ./.config file by setting symbol
+ values to 'y' as much as possible.
+
+ "make allmodconfig"
+ Create a ./.config file by setting symbol
+ values to 'm' as much as possible.
+
+ "make allnoconfig" Create a ./.config file by setting symbol
+ values to 'n' as much as possible.
+
+ "make randconfig" Create a ./.config file by setting symbol
+ values to random values.
+
+ "make localmodconfig" Create a config based on current config and
+ loaded modules (lsmod). Disables any module
+ option that is not needed for the loaded modules.
+
+ To create a localmodconfig for another machine,
+ store the lsmod of that machine into a file
+ and pass it in as a LSMOD parameter.
+
+ Also, you can preserve modules in certain folders
+ or kconfig files by specifying their paths in
+ parameter LMC_KEEP.
+
+ target$ lsmod > /tmp/mylsmod
+ target$ scp /tmp/mylsmod host:/tmp
+
+ host$ make LSMOD=/tmp/mylsmod \
+ LMC_KEEP="drivers/usb:drivers/gpu:fs" \
+ localmodconfig
+
+ The above also works when cross compiling.
+
+ "make localyesconfig" Similar to localmodconfig, except it will convert
+ all module options to built in (=y) options. You can
+ also preserve modules by LMC_KEEP.
+
+ "make kvm_guest.config" Enable additional options for kvm guest kernel
+ support.
+
+ "make xen.config" Enable additional options for xen dom0 guest kernel
+ support.
+
+ "make tinyconfig" Configure the tiniest possible kernel.
+
+ You can find more information on using the Linux kernel config tools
+ in Documentation/kbuild/kconfig.rst.
+
+ - NOTES on ``make config``:
+
+ - Having unnecessary drivers will make the kernel bigger, and can
+ under some circumstances lead to problems: probing for a
+ nonexistent controller card may confuse your other controllers.
+
+ - A kernel with math-emulation compiled in will still use the
+ coprocessor if one is present: the math emulation will just
+ never get used in that case. The kernel will be slightly larger,
+ but will work on different machines regardless of whether they
+ have a math coprocessor or not.
+
+ - The "kernel hacking" configuration details usually result in a
+ bigger or slower kernel (or both), and can even make the kernel
+ less stable by configuring some routines to actively try to
+ break bad code to find kernel problems (kmalloc()). Thus you
+ should probably answer 'n' to the questions for "development",
+ "experimental", or "debugging" features.
+
+Compiling the kernel
+--------------------
+
+ - Make sure you have at least gcc 8.1 available.
+ For more information, refer to :ref:`Documentation/process/changes.rst <changes>`.
+
+ - Do a ``make`` to create a compressed kernel image. It is also possible to do
+ ``make install`` if you have lilo installed or if your distribution has an
+ install script recognised by the kernel's installer. Most popular
+ distributions will have a recognized install script. You may want to
+ check your distribution's setup first.
+
+ To do the actual install, you have to be root, but none of the normal
+ build should require that. Don't take the name of root in vain.
+
+ - If you configured any of the parts of the kernel as ``modules``, you
+ will also have to do ``make modules_install``.
+
+ - Verbose kernel compile/build output:
+
+ Normally, the kernel build system runs in a fairly quiet mode (but not
+ totally silent). However, sometimes you or other kernel developers need
+ to see compile, link, or other commands exactly as they are executed.
+ For this, use "verbose" build mode. This is done by passing
+ ``V=1`` to the ``make`` command, e.g.::
+
+ make V=1 all
+
+ To have the build system also tell the reason for the rebuild of each
+ target, use ``V=2``. The default is ``V=0``.
+
+ - Keep a backup kernel handy in case something goes wrong. This is
+ especially true for the development releases, since each new release
+ contains new code which has not been debugged. Make sure you keep a
+ backup of the modules corresponding to that kernel, as well. If you
+ are installing a new kernel with the same version number as your
+ working kernel, make a backup of your modules directory before you
+ do a ``make modules_install``.
+
+ Alternatively, before compiling, use the kernel config option
+ "LOCALVERSION" to append a unique suffix to the regular kernel version.
+ LOCALVERSION can be set in the "General Setup" menu.
+
+ - In order to boot your new kernel, you'll need to copy the kernel
+ image (e.g. .../linux/arch/x86/boot/bzImage after compilation)
+ to the place where your regular bootable kernel is found.
+
+ - Booting a kernel directly from a storage device without the assistance
+ of a bootloader such as LILO or GRUB, is no longer supported in BIOS
+ (non-EFI systems). On UEFI/EFI systems, however, you can use EFISTUB
+ which allows the motherboard to boot directly to the kernel.
+ On modern workstations and desktops, it's generally recommended to use a
+ bootloader as difficulties can arise with multiple kernels and secure boot.
+ For more details on EFISTUB,
+ see "Documentation/admin-guide/efi-stub.rst".
+
+ - It's important to note that as of 2016 LILO (LInux LOader) is no longer in
+ active development, though as it was extremely popular, it often comes up
+ in documentation. Popular alternatives include GRUB2, rEFInd, Syslinux,
+ systemd-boot, or EFISTUB. For various reasons, it's not recommended to use
+ software that's no longer in active development.
+
+ - Chances are your distribution includes an install script and running
+ ``make install`` will be all that's needed. Should that not be the case
+ you'll have to identify your bootloader and reference its documentation or
+ configure your EFI.
+
+Legacy LILO Instructions
+------------------------
+
+
+ - If you use LILO the kernel images are specified in the file /etc/lilo.conf.
+ The kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
+ /boot/bzImage. To use the new kernel, save a copy of the old image and copy
+ the new image over the old one. Then, you MUST RERUN LILO to update the
+ loading map! If you don't, you won't be able to boot the new kernel image.
+
+ - Reinstalling LILO is usually a matter of running /sbin/lilo. You may wish
+ to edit /etc/lilo.conf to specify an entry for your old kernel image
+ (say, /vmlinux.old) in case the new one does not work. See the LILO docs
+ for more information.
+
+ - After reinstalling LILO, you should be all set. Shutdown the system,
+ reboot, and enjoy!
+
+ - If you ever need to change the default root device, video mode, etc. in the
+ kernel image, use your bootloader's boot options where appropriate. No need
+ to recompile the kernel to change these parameters.
+
+ - Reboot with the new kernel and enjoy.
+
+
+If something goes wrong
+-----------------------
+
+If you have problems that seem to be due to kernel bugs, please follow the
+instructions at 'Documentation/admin-guide/reporting-issues.rst'.
+
+Hints on understanding kernel bug reports are in
+'Documentation/admin-guide/bug-hunting.rst'. More on debugging the kernel
+with gdb is in 'Documentation/process/debugging/gdb-kernel-debugging.rst' and
+'Documentation/process/debugging/kgdb.rst'.
diff --git a/Documentation/admin-guide/abi-obsolete-files.rst b/Documentation/admin-guide/abi-obsolete-files.rst
new file mode 100644
index 000000000000..3061a916b4b5
--- /dev/null
+++ b/Documentation/admin-guide/abi-obsolete-files.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Obsolete ABI Files
+==================
+
+.. kernel-abi:: obsolete
+ :no-symbols:
diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
new file mode 100644
index 000000000000..640f3903e847
--- /dev/null
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+ABI obsolete symbols
+====================
+
+Documents interfaces that are still remaining in the kernel, but are
+marked to be removed at some later point in time.
+
+The description of the interface will document the reason why it is
+obsolete and when it can be expected to be removed.
+
+.. kernel-abi:: obsolete
+ :no-files:
diff --git a/Documentation/admin-guide/abi-removed-files.rst b/Documentation/admin-guide/abi-removed-files.rst
new file mode 100644
index 000000000000..f1bdfadd2ec4
--- /dev/null
+++ b/Documentation/admin-guide/abi-removed-files.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Removed ABI Files
+=================
+
+.. kernel-abi:: removed
+ :no-symbols:
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
new file mode 100644
index 000000000000..88832d3eacd6
--- /dev/null
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+ABI removed symbols
+===================
+
+.. kernel-abi:: removed
+ :no-files:
diff --git a/Documentation/admin-guide/abi-stable-files.rst b/Documentation/admin-guide/abi-stable-files.rst
new file mode 100644
index 000000000000..f867738fc178
--- /dev/null
+++ b/Documentation/admin-guide/abi-stable-files.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Stable ABI Files
+================
+
+.. kernel-abi:: stable
+ :no-symbols:
diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
new file mode 100644
index 000000000000..528c68401f4b
--- /dev/null
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+ABI stable symbols
+==================
+
+Documents the interfaces that the developer has defined to be stable.
+
+Userspace programs are free to use these interfaces with no
+restrictions, and backward compatibility for them will be guaranteed
+for at least 2 years.
+
+Most interfaces (like syscalls) are expected to never change and always
+be available.
+
+.. kernel-abi:: stable
+ :no-files:
diff --git a/Documentation/admin-guide/abi-testing-files.rst b/Documentation/admin-guide/abi-testing-files.rst
new file mode 100644
index 000000000000..1da868e42fdb
--- /dev/null
+++ b/Documentation/admin-guide/abi-testing-files.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Testing ABI Files
+=================
+
+.. kernel-abi:: testing
+ :no-symbols:
diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst
new file mode 100644
index 000000000000..6153ebd38e2d
--- /dev/null
+++ b/Documentation/admin-guide/abi-testing.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+ABI testing symbols
+===================
+
+Documents interfaces that are felt to be stable,
+as the main development of this interface has been completed.
+
+The interface can be changed to add new features, but the
+current interface will not break by doing this, unless grave
+errors or security problems are found in them.
+
+Userspace programs can start to rely on these interfaces, but they must
+be aware of changes that can occur before these interfaces move to
+be marked stable.
+
+Programs that use these interfaces are strongly encouraged to add their
+name to the description of these interfaces, so that the kernel
+developers can easily notify them if any changes occur.
+
+.. kernel-abi:: testing
+ :no-files:
diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst
new file mode 100644
index 000000000000..c6039359e585
--- /dev/null
+++ b/Documentation/admin-guide/abi.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+Linux ABI description
+=====================
+
+.. kernel-abi:: README
+
+ABI symbols
+-----------
+
+.. toctree::
+ :maxdepth: 2
+
+ abi-stable
+ abi-testing
+ abi-obsolete
+ abi-removed
+
+ABI files
+---------
+
+.. toctree::
+ :maxdepth: 2
+
+ abi-stable-files
+ abi-testing-files
+ abi-obsolete-files
+ abi-removed-files
diff --git a/Documentation/admin-guide/acpi/cppc_sysfs.rst b/Documentation/admin-guide/acpi/cppc_sysfs.rst
new file mode 100644
index 000000000000..36981c667823
--- /dev/null
+++ b/Documentation/admin-guide/acpi/cppc_sysfs.rst
@@ -0,0 +1,78 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================================
+Collaborative Processor Performance Control (CPPC)
+==================================================
+
+.. _cppc_sysfs:
+
+CPPC
+====
+
+CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
+performance of a logical processor on a contiguous and abstract performance
+scale. CPPC exposes a set of registers to describe abstract performance scale,
+to request performance levels and to measure per-cpu delivered performance.
+
+For more details on CPPC please refer to the ACPI specification at:
+
+http://uefi.org/specifications
+
+Some of the CPPC registers are exposed via sysfs under::
+
+ /sys/devices/system/cpu/cpuX/acpi_cppc/
+
+for each cpu X::
+
+ $ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
+ /sys/devices/system/cpu/cpu0/acpi_cppc/:
+ total 0
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
+ -r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
+
+* highest_perf : Highest performance of this processor (abstract scale).
+* nominal_perf : Highest sustained performance of this processor
+ (abstract scale).
+* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear
+ power savings (abstract scale).
+* lowest_perf : Lowest performance of this processor (abstract scale).
+
+* lowest_freq : CPU frequency corresponding to lowest_perf (in MHz).
+* nominal_freq : CPU frequency corresponding to nominal_perf (in MHz).
+ The above frequencies should only be used to report processor performance in
+ frequency instead of abstract scale. These values should not be used for any
+ functional decisions.
+
+* feedback_ctrs : Includes both Reference and delivered performance counter.
+ Reference counter ticks up proportional to processor's reference performance.
+ Delivered counter ticks up proportional to processor's delivered performance.
+* wraparound_time: Minimum time for the feedback counters to wraparound
+ (seconds).
+* reference_perf : Performance level at which reference performance counter
+ accumulates (abstract scale).
+
+
+Computing Average Delivered Performance
+=======================================
+
+Below describes the steps to compute the average performance delivered by
+taking two different snapshots of feedback counters at time T1 and T2.
+
+ T1: Read feedback_ctrs as fbc_t1
+ Wait or run some workload
+
+ T2: Read feedback_ctrs as fbc_t2
+
+::
+
+ delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
+ reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
+
+ delivered_perf = (reference_perf x delivered_counter_delta) / reference_counter_delta
diff --git a/Documentation/admin-guide/acpi/fan_performance_states.rst b/Documentation/admin-guide/acpi/fan_performance_states.rst
new file mode 100644
index 000000000000..b9e4b4d146c1
--- /dev/null
+++ b/Documentation/admin-guide/acpi/fan_performance_states.rst
@@ -0,0 +1,90 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+ACPI Fan Performance States
+===========================
+
+When the optional _FPS object is present under an ACPI device representing a
+fan (for example, PNP0C0B or INT3404), the ACPI fan driver creates additional
+"state*" attributes in the sysfs directory of the ACPI device in question.
+These attributes list properties of fan performance states.
+
+For more information on _FPS refer to the ACPI specification at:
+
+http://uefi.org/specifications
+
+For instance, the contents of the INT3404 ACPI device sysfs directory
+may look as follows::
+
+ $ ls -l /sys/bus/acpi/devices/INT3404:00/
+ total 0
+ ...
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state0
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state1
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state10
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state11
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state2
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state3
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state4
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state5
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state6
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state7
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state8
+ -r--r--r-- 1 root root 4096 Dec 13 20:38 state9
+ -r--r--r-- 1 root root 4096 Dec 13 01:00 status
+ ...
+
+where each of the "state*" files represents one performance state of the fan
+and contains a colon-separated list of 5 integer numbers (fields) with the
+following interpretation::
+
+ control_percent:trip_point_index:speed_rpm:noise_level_mdb:power_mw
+
+* ``control_percent``: The percent value to be used to set the fan speed to a
+ specific level using the _FSL object (0-100).
+
+* ``trip_point_index``: The active cooling trip point number that corresponds
+ to this performance state (0-9).
+
+* ``speed_rpm``: Speed of the fan in rotations per minute.
+
+* ``noise_level_mdb``: Audible noise emitted by the fan in this state in
+ millidecibels.
+
+* ``power_mw``: Power draw of the fan in this state in milliwatts.
+
+For example::
+
+ $cat /sys/bus/acpi/devices/INT3404:00/state1
+ 25:0:3200:12500:1250
+
+When a given field is not populated or its value provided by the platform
+firmware is invalid, the "not-defined" string is shown instead of the value.
+
+ACPI Fan Fine Grain Control
+=============================
+
+When _FIF object specifies support for fine grain control, then fan speed
+can be set from 0 to 100% with the recommended minimum "step size" via
+_FSL object. User can adjust fan speed using thermal sysfs cooling device.
+
+Here use can look at fan performance states for a reference speed (speed_rpm)
+and set it by changing cooling device cur_state. If the fine grain control
+is supported then user can also adjust to some other speeds which are
+not defined in the performance states.
+
+The support of fine grain control is presented via sysfs attribute
+"fine_grain_control". If fine grain control is present, this attribute
+will show "1" otherwise "0".
+
+This sysfs attribute is presented in the same directory as performance states.
+
+ACPI Fan Performance Feedback
+=============================
+
+The optional _FST object provides status information for the fan device.
+This includes field to provide current fan speed in revolutions per minute
+at which the fan is rotating.
+
+This speed is presented in the sysfs using the attribute "fan_speed_rpm",
+in the same directory as performance states.
diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
new file mode 100644
index 000000000000..b078fdb8f4c9
--- /dev/null
+++ b/Documentation/admin-guide/acpi/index.rst
@@ -0,0 +1,14 @@
+============
+ACPI Support
+============
+
+Here we document in detail how to interact with various mechanisms in
+the Linux ACPI support.
+
+.. toctree::
+ :maxdepth: 1
+
+ initrd_table_override
+ ssdt-overlays
+ cppc_sysfs
+ fan_performance_states
diff --git a/Documentation/admin-guide/acpi/initrd_table_override.rst b/Documentation/admin-guide/acpi/initrd_table_override.rst
new file mode 100644
index 000000000000..bb24fa6b5fbe
--- /dev/null
+++ b/Documentation/admin-guide/acpi/initrd_table_override.rst
@@ -0,0 +1,115 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Upgrading ACPI tables via initrd
+================================
+
+What is this about
+==================
+
+If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
+upgrade the ACPI execution environment that is defined by the ACPI tables
+via upgrading the ACPI tables provided by the BIOS with an instrumented,
+modified, more recent version one, or installing brand new ACPI tables.
+
+When building initrd with kernel in a single image, option
+ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
+feature to work.
+
+For a full list of ACPI tables that can be upgraded/installed, take a look
+at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in
+drivers/acpi/tables.c.
+
+All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
+be overridable, except:
+
+ - ACPI_SIG_RSDP (has a signature of 6 bytes)
+ - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
+
+Both could get implemented as well.
+
+
+What is this for
+================
+
+Complain to your platform/BIOS vendor if you find a bug which is so severe
+that a workaround is not accepted in the Linux kernel. And this facility
+allows you to upgrade the buggy tables before your platform/BIOS vendor
+releases an upgraded BIOS binary.
+
+This facility can be used by platform/BIOS vendors to provide a Linux
+compatible environment without modifying the underlying platform firmware.
+
+This facility also provides a powerful feature to easily debug and test
+ACPI BIOS table compatibility with the Linux kernel by modifying old
+platform provided ACPI tables or inserting new ACPI tables.
+
+It can and should be enabled in any kernel because there is no functional
+change with not instrumented initrds.
+
+
+How does it work
+================
+::
+
+ # Extract the machine's ACPI tables:
+ cd /tmp
+ acpidump >acpidump
+ acpixtract -a acpidump
+ # Disassemble, modify and recompile them:
+ iasl -d *.dat
+ # For example add this statement into a _PRT (PCI Routing Table) function
+ # of the DSDT:
+ Store("HELLO WORLD", debug)
+ # And increase the OEM Revision. For example, before modification:
+ DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
+ # After modification:
+ DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
+ iasl -sa dsdt.dsl
+ # Add the raw ACPI tables to an uncompressed cpio archive.
+ # They must be put into a /kernel/firmware/acpi directory inside the cpio
+ # archive. Note that if the table put here matches a platform table
+ # (similar Table Signature, and similar OEMID, and similar OEM Table ID)
+ # with a more recent OEM Revision, the platform table will be upgraded by
+ # this table. If the table put here doesn't match a platform table
+ # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
+ # ID), this table will be appended.
+ mkdir -p kernel/firmware/acpi
+ cp dsdt.aml kernel/firmware/acpi
+ # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
+ # (see osl.c):
+ iasl -sa facp.dsl
+ iasl -sa ssdt1.dsl
+ cp facp.aml kernel/firmware/acpi
+ cp ssdt1.aml kernel/firmware/acpi
+ # The uncompressed cpio archive must be the first. Other, typically
+ # compressed cpio archives, must be concatenated on top of the uncompressed
+ # one. Following command creates the uncompressed cpio archive and
+ # concatenates the original initrd on top:
+ find kernel | cpio -H newc --create > /boot/instrumented_initrd
+ cat /boot/initrd >>/boot/instrumented_initrd
+ # reboot with increased acpi debug level, e.g. boot params:
+ acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
+ # and check your syslog:
+ [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
+ [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
+
+iasl is able to disassemble and recompile quite a lot different,
+also static ACPI tables.
+
+
+Where to retrieve userspace tools
+=================================
+
+iasl and acpixtract are part of Intel's ACPICA project:
+https://acpica.org/
+
+and should be packaged by distributions (for example in the acpica package
+on SUSE).
+
+acpidump can be found in Len Browns pmtools:
+ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
+
+This tool is also part of the acpica package on SUSE.
+Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
+/sys/firmware/acpi/tables
diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst
new file mode 100644
index 000000000000..5ea9f4a3b76e
--- /dev/null
+++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst
@@ -0,0 +1,181 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+SSDT Overlays
+=============
+
+In order to support ACPI open-ended hardware configurations (e.g. development
+boards) we need a way to augment the ACPI configuration provided by the firmware
+image. A common example is connecting sensors on I2C / SPI buses on development
+boards.
+
+Although this can be accomplished by creating a kernel platform driver or
+recompiling the firmware image with updated ACPI tables, neither is practical:
+the former proliferates board specific kernel code while the latter requires
+access to firmware tools which are often not publicly available.
+
+Because ACPI supports external references in AML code a more practical
+way to augment firmware ACPI configuration is by dynamically loading
+user defined SSDT tables that contain the board specific information.
+
+For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
+Minnowboard MAX development board exposed via the LSE connector [1], the
+following ASL code can be used::
+
+ DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
+ {
+ External (\_SB.I2C6, DeviceObj)
+
+ Scope (\_SB.I2C6)
+ {
+ Device (STAC)
+ {
+ Name (_HID, "BMA222E")
+ Name (RBUF, ResourceTemplate ()
+ {
+ I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
+ AddressingMode7Bit, "\\_SB.I2C6", 0x00,
+ ResourceConsumer, ,)
+ GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
+ "\\_SB.GPO2", 0x00, ResourceConsumer, , )
+ { // Pin list
+ 0
+ }
+ })
+
+ Method (_CRS, 0, Serialized)
+ {
+ Return (RBUF)
+ }
+ }
+ }
+ }
+
+which can then be compiled to AML binary format::
+
+ $ iasl minnowmax.asl
+
+ Intel ACPI Component Architecture
+ ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
+ Copyright (c) 2000 - 2014 Intel Corporation
+
+ ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
+ AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
+
+[1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29
+
+The resulting AML code can then be loaded by the kernel using one of the methods
+below.
+
+Loading ACPI SSDTs from initrd
+==============================
+
+This option allows loading of user defined SSDTs from initrd and it is useful
+when the system does not support EFI or when there is not enough EFI storage.
+
+It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
+AML code must be placed in the first, uncompressed, initrd under the
+"kernel/firmware/acpi" path. Multiple files can be used and this will translate
+in loading multiple tables. Only SSDT and OEM tables are allowed. See
+initrd_table_override.txt for more details.
+
+Here is an example::
+
+ # Add the raw ACPI tables to an uncompressed cpio archive.
+ # They must be put into a /kernel/firmware/acpi directory inside the
+ # cpio archive.
+ # The uncompressed cpio archive must be the first.
+ # Other, typically compressed cpio archives, must be
+ # concatenated on top of the uncompressed one.
+ mkdir -p kernel/firmware/acpi
+ cp ssdt.aml kernel/firmware/acpi
+
+ # Create the uncompressed cpio archive and concatenate the original initrd
+ # on top:
+ find kernel | cpio -H newc --create > /boot/instrumented_initrd
+ cat /boot/initrd >>/boot/instrumented_initrd
+
+Loading ACPI SSDTs from EFI variables
+=====================================
+
+This is the preferred method, when EFI is supported on the platform, because it
+allows a persistent, OS independent way of storing the user defined SSDTs. There
+is also work underway to implement EFI support for loading user defined SSDTs
+and using this method will make it easier to convert to the EFI loading
+mechanism when that will arrive. To enable it, the
+CONFIG_EFI_CUSTOM_SSDT_OVERLAYS should be chosen to y.
+
+In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel
+command line parameter can be used (the name has a limitation of 16 characters).
+The argument for the option is the variable name to use. If there are multiple
+variables with the same name but with different vendor GUIDs, all of them will
+be loaded.
+
+In order to store the AML code in an EFI variable the efivarfs filesystem can be
+used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
+recent distribution.
+
+Creating a new file in /sys/firmware/efi/efivars will automatically create a new
+EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
+variable. Please note that the file name needs to be specially formatted as
+"Name-GUID" and that the first 4 bytes in the file (little-endian format)
+represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
+include/linux/efi.h). Writing to the file must also be done with one write
+operation.
+
+For example, you can use the following bash script to create/update an EFI
+variable with the content from a given file::
+
+ #!/bin/sh -e
+
+ while [ -n "$1" ]; do
+ case "$1" in
+ "-f") filename="$2"; shift;;
+ "-g") guid="$2"; shift;;
+ *) name="$1";;
+ esac
+ shift
+ done
+
+ usage()
+ {
+ echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
+ exit 1
+ }
+
+ [ -n "$name" -a -f "$filename" ] || usage
+
+ EFIVARFS="/sys/firmware/efi/efivars"
+
+ [ -d "$EFIVARFS" ] || exit 2
+
+ if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
+ mount -t efivarfs none $EFIVARFS
+ fi
+
+ # try to pick up an existing GUID
+ [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
+
+ # use a randomly generated GUID
+ [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
+
+ # efivarfs expects all of the data in one write
+ tmp=$(mktemp)
+ /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
+ dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
+ rm $tmp
+
+Loading ACPI SSDTs from configfs
+================================
+
+This option allows loading of user defined SSDTs from user space via the configfs
+interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
+mounted. In the following examples, we assume that configfs has been mounted in
+/sys/kernel/config.
+
+New tables can be loading by creating new directories in /sys/kernel/config/acpi/table
+and writing the SSDT AML code in the aml attribute::
+
+ cd /sys/kernel/config/acpi/table
+ mkdir my_ssdt
+ cat ~/ssdt.aml > my_ssdt/aml
diff --git a/Documentation/admin-guide/aoe/aoe.rst b/Documentation/admin-guide/aoe/aoe.rst
new file mode 100644
index 000000000000..a05e751363a0
--- /dev/null
+++ b/Documentation/admin-guide/aoe/aoe.rst
@@ -0,0 +1,150 @@
+Introduction
+============
+
+ATA over Ethernet is a network protocol that provides simple access to
+block storage on the LAN.
+
+ http://support.coraid.com/documents/AoEr11.txt
+
+The EtherDrive (R) HOWTO for 2.6 and 3.x kernels is found at ...
+
+ http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO.html
+
+It has many tips and hints! Please see, especially, recommended
+tunings for virtual memory:
+
+ http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO-5.html#ss5.19
+
+The aoetools are userland programs that are designed to work with this
+driver. The aoetools are on sourceforge.
+
+ http://aoetools.sourceforge.net/
+
+The scripts in this Documentation/admin-guide/aoe directory are intended to
+document the use of the driver and are not necessary if you install
+the aoetools.
+
+
+Creating Device Nodes
+=====================
+
+ Users of udev should find the block device nodes created
+ automatically, but to create all the necessary device nodes, use the
+ udev configuration rules provided in udev.txt (in this directory).
+
+ There is a udev-install.sh script that shows how to install these
+ rules on your system.
+
+ There is also an autoload script that shows how to edit
+ /etc/modprobe.d/aoe.conf to ensure that the aoe module is loaded when
+ necessary. Preloading the aoe module is preferable to autoloading,
+ however, because AoE discovery takes a few seconds. It can be
+ confusing when an AoE device is not present the first time the a
+ command is run but appears a second later.
+
+Using Device Nodes
+==================
+
+ "cat /dev/etherd/err" blocks, waiting for error diagnostic output,
+ like any retransmitted packets.
+
+ "echo eth2 eth4 > /dev/etherd/interfaces" tells the aoe driver to
+ limit ATA over Ethernet traffic to eth2 and eth4. AoE traffic from
+ untrusted networks should be ignored as a matter of security. See
+ also the aoe_iflist driver option described below.
+
+ "echo > /dev/etherd/discover" tells the driver to find out what AoE
+ devices are available.
+
+ In the future these character devices may disappear and be replaced
+ by sysfs counterparts. Using the commands in aoetools insulates
+ users from these implementation details.
+
+ The block devices are named like this::
+
+ e{shelf}.{slot}
+ e{shelf}.{slot}p{part}
+
+ ... so that "e0.2" is the third blade from the left (slot 2) in the
+ first shelf (shelf address zero). That's the whole disk. The first
+ partition on that disk would be "e0.2p1".
+
+Using sysfs
+===========
+
+ Each aoe block device in /sys/block has the extra attributes of
+ state, mac, and netif. The state attribute is "up" when the device
+ is ready for I/O and "down" if detected but unusable. The
+ "down,closewait" state shows that the device is still open and
+ cannot come up again until it has been closed.
+
+ The mac attribute is the ethernet address of the remote AoE device.
+ The netif attribute is the network interface on the localhost
+ through which we are communicating with the remote AoE device.
+
+ There is a script in this directory that formats this information in
+ a convenient way. Users with aoetools should use the aoe-stat
+ command::
+
+ root@makki root# sh Documentation/admin-guide/aoe/status.sh
+ e10.0 eth3 up
+ e10.1 eth3 up
+ e10.2 eth3 up
+ e10.3 eth3 up
+ e10.4 eth3 up
+ e10.5 eth3 up
+ e10.6 eth3 up
+ e10.7 eth3 up
+ e10.8 eth3 up
+ e10.9 eth3 up
+ e4.0 eth1 up
+ e4.1 eth1 up
+ e4.2 eth1 up
+ e4.3 eth1 up
+ e4.4 eth1 up
+ e4.5 eth1 up
+ e4.6 eth1 up
+ e4.7 eth1 up
+ e4.8 eth1 up
+ e4.9 eth1 up
+
+ Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver
+ option discussed below) instead of /dev/etherd/interfaces to limit
+ AoE traffic to the network interfaces in the given
+ whitespace-separated list. Unlike the old character device, the
+ sysfs entry can be read from as well as written to.
+
+ It's helpful to trigger discovery after setting the list of allowed
+ interfaces. The aoetools package provides an aoe-discover script
+ for this purpose. You can also directly use the
+ /dev/etherd/discover special file described above.
+
+Driver Options
+==============
+
+ There is a boot option for the built-in aoe driver and a
+ corresponding module parameter, aoe_iflist. Without this option,
+ all network interfaces may be used for ATA over Ethernet. Here is a
+ usage example for the module parameter::
+
+ modprobe aoe_iflist="eth1 eth3"
+
+ The aoe_deadsecs module parameter determines the maximum number of
+ seconds that the driver will wait for an AoE device to provide a
+ response to an AoE command. After aoe_deadsecs seconds have
+ elapsed, the AoE device will be marked as "down". A value of zero
+ is supported for testing purposes and makes the aoe driver keep
+ trying AoE commands forever.
+
+ The aoe_maxout module parameter has a default of 128. This is the
+ maximum number of unresponded packets that will be sent to an AoE
+ target at one time.
+
+ The aoe_dyndevs module parameter defaults to 1, meaning that the
+ driver will assign a block device minor number to a discovered AoE
+ target based on the order of its discovery. With dynamic minor
+ device numbers in use, a greater range of AoE shelf and slot
+ addresses can be supported. Users with udev will never have to
+ think about minor numbers. Using aoe_dyndevs=0 allows device nodes
+ to be pre-created using a static minor-number scheme with the
+ aoe-mkshelf script in the aoetools.
diff --git a/Documentation/aoe/autoload.sh b/Documentation/admin-guide/aoe/autoload.sh
index 815dff4691c9..815dff4691c9 100644
--- a/Documentation/aoe/autoload.sh
+++ b/Documentation/admin-guide/aoe/autoload.sh
diff --git a/Documentation/admin-guide/aoe/examples.rst b/Documentation/admin-guide/aoe/examples.rst
new file mode 100644
index 000000000000..91f3198e52c1
--- /dev/null
+++ b/Documentation/admin-guide/aoe/examples.rst
@@ -0,0 +1,23 @@
+Example of udev rules
+---------------------
+
+ .. include:: udev.txt
+ :literal:
+
+Example of udev install rules script
+------------------------------------
+
+ .. literalinclude:: udev-install.sh
+ :language: shell
+
+Example script to get status
+----------------------------
+
+ .. literalinclude:: status.sh
+ :language: shell
+
+Example of AoE autoload script
+------------------------------
+
+ .. literalinclude:: autoload.sh
+ :language: shell
diff --git a/Documentation/admin-guide/aoe/index.rst b/Documentation/admin-guide/aoe/index.rst
new file mode 100644
index 000000000000..d71c5df15922
--- /dev/null
+++ b/Documentation/admin-guide/aoe/index.rst
@@ -0,0 +1,17 @@
+=======================
+ATA over Ethernet (AoE)
+=======================
+
+.. toctree::
+ :maxdepth: 1
+
+ aoe
+ todo
+ examples
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/aoe/status.sh b/Documentation/admin-guide/aoe/status.sh
index eeec7baae57a..eeec7baae57a 100644
--- a/Documentation/aoe/status.sh
+++ b/Documentation/admin-guide/aoe/status.sh
diff --git a/Documentation/admin-guide/aoe/todo.rst b/Documentation/admin-guide/aoe/todo.rst
new file mode 100644
index 000000000000..dea8db5a33e1
--- /dev/null
+++ b/Documentation/admin-guide/aoe/todo.rst
@@ -0,0 +1,17 @@
+TODO
+====
+
+There is a potential for deadlock when allocating a struct sk_buff for
+data that needs to be written out to aoe storage. If the data is
+being written from a dirty page in order to free that page, and if
+there are no other pages available, then deadlock may occur when a
+free page is needed for the sk_buff allocation. This situation has
+not been observed, but it would be nice to eliminate any potential for
+deadlock under memory pressure.
+
+Because ATA over Ethernet is not fragmented by the kernel's IP code,
+the destructor member of the struct sk_buff is available to the aoe
+driver. By using a mempool for allocating all but the first few
+sk_buffs, and by registering a destructor, we should be able to
+efficiently allocate sk_buffs without introducing any potential for
+deadlock.
diff --git a/Documentation/aoe/udev-install.sh b/Documentation/admin-guide/aoe/udev-install.sh
index 15e86f58c036..15e86f58c036 100644
--- a/Documentation/aoe/udev-install.sh
+++ b/Documentation/admin-guide/aoe/udev-install.sh
diff --git a/Documentation/admin-guide/aoe/udev.txt b/Documentation/admin-guide/aoe/udev.txt
new file mode 100644
index 000000000000..d55ecb411c21
--- /dev/null
+++ b/Documentation/admin-guide/aoe/udev.txt
@@ -0,0 +1,26 @@
+# These rules tell udev what device nodes to create for aoe support.
+# 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
+# /etc/udev/udev.conf
+# bash# grep udev_rules= /etc/udev/udev.conf
+# udev_rules="/etc/udev/rules.d/"
+# bash# ls /etc/udev/rules.d/
+# 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"
+SUBSYSTEM=="aoe", KERNEL=="err", NAME="etherd/%k", GROUP="disk", MODE="0440"
+SUBSYSTEM=="aoe", KERNEL=="interfaces", NAME="etherd/%k", GROUP="disk", MODE="0220"
+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
+KERNEL=="etherd*", GROUP="disk"
diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
new file mode 100644
index 000000000000..da385d851acc
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
@@ -0,0 +1,98 @@
+===================================
+cfag12864b LCD Driver Documentation
+===================================
+
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda <ojeda@kernel.org>
+:Date: 2006-10-27
+
+
+
+.. INDEX
+
+ 1. DRIVER INFORMATION
+ 2. DEVICE INFORMATION
+ 3. WIRING
+ 4. USERSPACE PROGRAMMING
+
+1. Driver Information
+---------------------
+
+This driver supports a cfag12864b LCD.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer: Crystalfontz
+:Device Name: Crystalfontz 12864b LCD Series
+:Device Code: cfag12864b
+:Webpage: http://www.crystalfontz.com
+:Device Webpage: http://www.crystalfontz.com/products/12864b/
+:Type: LCD (Liquid Crystal Display)
+:Width: 128
+:Height: 64
+:Colors: 2 (B/N)
+:Controller: ks0108
+:Controllers: 2
+:Pages: 8 each controller
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
+
+
+3. Wiring
+---------
+
+The cfag12864b LCD Series don't have official wiring.
+
+The common wiring is done to the parallel port as shown::
+
+ Parallel Port cfag12864b
+
+ Name Pin# Pin# Name
+
+ Strobe ( 1)------------------------------(17) Enable
+ Data 0 ( 2)------------------------------( 4) Data 0
+ Data 1 ( 3)------------------------------( 5) Data 1
+ Data 2 ( 4)------------------------------( 6) Data 2
+ Data 3 ( 5)------------------------------( 7) Data 3
+ Data 4 ( 6)------------------------------( 8) Data 4
+ Data 5 ( 7)------------------------------( 9) Data 5
+ Data 6 ( 8)------------------------------(10) Data 6
+ Data 7 ( 9)------------------------------(11) Data 7
+ (10) [+5v]---( 1) Vdd
+ (11) [GND]---( 2) Ground
+ (12) [+5v]---(14) Reset
+ (13) [GND]---(15) Read / Write
+ Line (14)------------------------------(13) Controller Select 1
+ (15)
+ Init (16)------------------------------(12) Controller Select 2
+ Select (17)------------------------------(16) Data / Instruction
+ Ground (18)---[GND] [+5v]---(19) LED +
+ Ground (19)---[GND]
+ Ground (20)---[GND] E A Values:
+ Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
+ Ground (22)---[GND] | - P1 = Preset = 10 Kohm
+ Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
+ Ground (24)---[GND] | |
+ Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
+
+
+4. Userspace Programming
+------------------------
+
+The cfag12864bfb describes a framebuffer device (/dev/fbX).
+
+It has a size of 1024 bytes = 1 Kbyte.
+Each bit represents one pixel. If the bit is high, the pixel will
+turn on. If the pixel is low, the pixel will turn off.
+
+You can use the framebuffer as a file: fopen, fwrite, fclose...
+Although the LCD won't get updated until the next refresh time arrives.
+
+Also, you can mmap the framebuffer: open & mmap, munmap & close...
+which is the best option for most uses.
+
+Check samples/auxdisplay/cfag12864b-example.c
+for a real working userspace complete program with usage examples.
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
new file mode 100644
index 000000000000..e466f0595248
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -0,0 +1,16 @@
+=========================
+Auxiliary Display Support
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ ks0108.rst
+ cfag12864b.rst
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst
new file mode 100644
index 000000000000..a7d3fe509373
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/ks0108.rst
@@ -0,0 +1,50 @@
+==========================================
+ks0108 LCD Controller Driver Documentation
+==========================================
+
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda <ojeda@kernel.org>
+:Date: 2006-10-27
+
+
+
+.. INDEX
+
+ 1. DRIVER INFORMATION
+ 2. DEVICE INFORMATION
+ 3. WIRING
+
+
+1. Driver Information
+---------------------
+
+This driver supports the ks0108 LCD controller.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer: Samsung
+:Device Name: KS0108 LCD Controller
+:Device Code: ks0108
+:Webpage: -
+:Device Webpage: -
+:Type: LCD Controller (Liquid Crystal Display Controller)
+:Width: 64
+:Height: 64
+:Colors: 2 (B/N)
+:Pages: 8
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 8 * 64 * 1 = 512 bytes
+
+
+3. Wiring
+---------
+
+The driver supports data parallel port wiring.
+
+If you aren't building LCD related hardware, you should check
+your LCD specific wiring information in the same folder.
+
+For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst
diff --git a/Documentation/admin-guide/bcache.rst b/Documentation/admin-guide/bcache.rst
new file mode 100644
index 000000000000..f71f349553e4
--- /dev/null
+++ b/Documentation/admin-guide/bcache.rst
@@ -0,0 +1,644 @@
+============================
+A block layer cache (bcache)
+============================
+
+Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
+nice if you could use them as cache... Hence bcache.
+
+The bcache wiki can be found at:
+ https://bcache.evilpiepirate.org
+
+This is the git repository of bcache-tools:
+ https://git.kernel.org/pub/scm/linux/kernel/git/colyli/bcache-tools.git/
+
+The latest bcache kernel code can be found from mainline Linux kernel:
+ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
+
+It's designed around the performance characteristics of SSDs - it only allocates
+in erase block sized buckets, and it uses a hybrid btree/log to track cached
+extents (which can be anywhere from a single sector to the bucket size). It's
+designed to avoid random writes at all costs.
+
+Both writethrough and writeback caching are supported. Writeback defaults to
+off, but can be switched on and off arbitrarily at runtime. Bcache goes to
+great lengths to protect your data - it reliably handles unclean shutdown. (It
+doesn't even have a notion of a clean shutdown; bcache simply doesn't return
+writes as completed until they're on stable storage).
+
+Writeback caching can use most of the cache for buffering writes - writing
+dirty data to the backing device is always done sequentially, scanning from the
+start to the end of the index.
+
+Since random IO is what SSDs excel at, there generally won't be much benefit
+to caching large sequential IO. Bcache detects sequential IO and skips it;
+it also keeps a rolling average of the IO sizes per task, and as long as the
+average is above the cutoff it will skip all IO from that task - instead of
+caching the first 512k after every seek. Backups and large file copies should
+thus entirely bypass the cache.
+
+In the event of a data IO error on the flash it will try to recover by reading
+from disk or invalidating cache entries. For unrecoverable errors (meta data
+or dirty data), caching is automatically disabled; if dirty data was present
+in the cache it first disables writeback caching and waits for all dirty data
+to be flushed.
+
+Getting started:
+You'll need bcache util from the bcache-tools repository. Both the cache device
+and backing device must be formatted before use::
+
+ bcache make -B /dev/sdb
+ bcache make -C /dev/sdc
+
+`bcache make` has the ability to format multiple devices at the same time - if
+you format your backing devices and cache device at the same time, you won't
+have to manually attach::
+
+ bcache make -B /dev/sda /dev/sdb -C /dev/sdc
+
+If your bcache-tools is not updated to latest version and does not have the
+unified `bcache` utility, you may use the legacy `make-bcache` utility to format
+bcache device with same -B and -C parameters.
+
+bcache-tools now ships udev rules, and bcache devices are known to the kernel
+immediately. Without udev, you can manually register devices like this::
+
+ echo /dev/sdb > /sys/fs/bcache/register
+ echo /dev/sdc > /sys/fs/bcache/register
+
+Registering the backing device makes the bcache device show up in /dev; you can
+now format it and use it as normal. But the first time using a new bcache
+device, it'll be running in passthrough mode until you attach it to a cache.
+If you are thinking about using bcache later, it is recommended to setup all your
+slow devices as bcache backing devices without a cache, and you can choose to add
+a caching device later.
+See 'ATTACHING' section below.
+
+The devices show up as::
+
+ /dev/bcache<N>
+
+As well as (with udev)::
+
+ /dev/bcache/by-uuid/<uuid>
+ /dev/bcache/by-label/<label>
+
+To get started::
+
+ mkfs.ext4 /dev/bcache0
+ mount /dev/bcache0 /mnt
+
+You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
+You can also control them through /sys/fs//bcache/<cset-uuid>/ .
+
+Cache devices are managed as sets; multiple caches per set isn't supported yet
+but will allow for mirroring of metadata and dirty data in the future. Your new
+cache set shows up as /sys/fs/bcache/<UUID>
+
+Attaching
+---------
+
+After your cache device and backing device are registered, the backing device
+must be attached to your cache set to enable caching. Attaching a backing
+device to a cache set is done thusly, with the UUID of the cache set in
+/sys/fs/bcache::
+
+ echo <CSET-UUID> > /sys/block/bcache0/bcache/attach
+
+This only has to be done once. The next time you reboot, just reregister all
+your bcache devices. If a backing device has data in a cache somewhere, the
+/dev/bcache<N> device won't be created until the cache shows up - particularly
+important if you have writeback caching turned on.
+
+If you're booting up and your cache device is gone and never coming back, you
+can force run the backing device::
+
+ echo 1 > /sys/block/sdb/bcache/running
+
+(You need to use /sys/block/sdb (or whatever your backing device is called), not
+/sys/block/bcache0, because bcache0 doesn't exist yet. If you're using a
+partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)
+
+The backing device will still use that cache set if it shows up in the future,
+but all the cached data will be invalidated. If there was dirty data in the
+cache, don't expect the filesystem to be recoverable - you will have massive
+filesystem corruption, though ext4's fsck does work miracles.
+
+Error Handling
+--------------
+
+Bcache tries to transparently handle IO errors to/from the cache device without
+affecting normal operation; if it sees too many errors (the threshold is
+configurable, and defaults to 0) it shuts down the cache device and switches all
+the backing devices to passthrough mode.
+
+ - For reads from the cache, if they error we just retry the read from the
+ backing device.
+
+ - For writethrough writes, if the write to the cache errors we just switch to
+ invalidating the data at that lba in the cache (i.e. the same thing we do for
+ a write that bypasses the cache)
+
+ - For writeback writes, we currently pass that error back up to the
+ filesystem/userspace. This could be improved - we could retry it as a write
+ that skips the cache so we don't have to error the write.
+
+ - When we detach, we first try to flush any dirty data (if we were running in
+ writeback mode). It currently doesn't do anything intelligent if it fails to
+ read some of the dirty data, though.
+
+
+Howto/cookbook
+--------------
+
+A) Starting a bcache with a missing caching device
+
+If registering the backing device doesn't help, it's already there, you just need
+to force it to run without the cache::
+
+ host:~# echo /dev/sdb1 > /sys/fs/bcache/register
+ [ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
+
+Next, you try to register your caching device if it's present. However
+if it's absent, or registration fails for some reason, you can still
+start your bcache without its cache, like so::
+
+ host:/sys/block/sdb/sdb1/bcache# echo 1 > running
+
+Note that this may cause data loss if you were running in writeback mode.
+
+
+B) Bcache does not find its cache::
+
+ host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
+ [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
+ [ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8
+ [ 1933.478179] : cache set not found
+
+In this case, the caching device was simply not registered at boot
+or disappeared and came back, and needs to be (re-)registered::
+
+ host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
+
+
+C) Corrupt bcache crashes the kernel at device registration time:
+
+This should never happen. If it does happen, then you have found a bug!
+Please report it to the bcache development list: linux-bcache@vger.kernel.org
+
+Be sure to provide as much information that you can including kernel dmesg
+output if available so that we may assist.
+
+
+D) Recovering data without bcache:
+
+If bcache is not available in the kernel, a filesystem on the backing
+device is still available at an 8KiB offset. So either via a loopdev
+of the backing device created with --offset 8K, or any value defined by
+--data-offset when you originally formatted bcache with `bcache make`.
+
+For example::
+
+ losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
+
+This should present your unmodified backing device data in /dev/loop0
+
+If your cache is in writethrough mode, then you can safely discard the
+cache device without losing data.
+
+
+E) Wiping a cache device
+
+::
+
+ host:~# wipefs -a /dev/sdh2
+ 16 bytes were erased at offset 0x1018 (bcache)
+ they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
+
+After you boot back with bcache enabled, you recreate the cache and attach it::
+
+ host:~# bcache make -C /dev/sdh2
+ UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
+ Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
+ version: 0
+ nbuckets: 106874
+ block_size: 1
+ bucket_size: 1024
+ nr_in_set: 1
+ nr_this_dev: 0
+ first_bucket: 1
+ [ 650.511912] bcache: run_cache_set() invalidating existing data
+ [ 650.549228] bcache: register_cache() registered cache device sdh2
+
+start backing device with missing cache::
+
+ host:/sys/block/md5/bcache# echo 1 > running
+
+attach new cache::
+
+ host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
+ [ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
+
+
+F) Remove or replace a caching device::
+
+ host:/sys/block/sda/sda7/bcache# echo 1 > detach
+ [ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
+
+ host:~# wipefs -a /dev/nvme0n1p4
+ wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
+ Ooops, it's disabled, but not unregistered, so it's still protected
+
+We need to go and unregister it::
+
+ host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
+ lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
+ host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
+ kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
+
+Now we can wipe it::
+
+ host:~# wipefs -a /dev/nvme0n1p4
+ /dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
+
+
+G) dm-crypt and bcache
+
+First setup bcache unencrypted and then install dmcrypt on top of
+/dev/bcache<N> This will work faster than if you dmcrypt both the backing
+and caching devices and then install bcache on top. [benchmarks?]
+
+
+H) Stop/free a registered bcache to wipe and/or recreate it
+
+Suppose that you need to free up all bcache references so that you can
+fdisk run and re-register a changed partition table, which won't work
+if there are any active backing or caching devices left on it:
+
+1) Is it present in /dev/bcache* ? (there are times where it won't be)
+
+ If so, it's easy::
+
+ host:/sys/block/bcache0/bcache# echo 1 > stop
+
+2) But if your backing device is gone, this won't work::
+
+ host:/sys/block/bcache0# cd bcache
+ bash: cd: bcache: No such file or directory
+
+ In this case, you may have to unregister the dmcrypt block device that
+ references this bcache to free it up::
+
+ host:~# dmsetup remove oldds1
+ bcache: bcache_device_free() bcache0 stopped
+ bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
+
+ This causes the backing bcache to be removed from /sys/fs/bcache and
+ then it can be reused. This would be true of any block device stacking
+ where bcache is a lower device.
+
+3) In other cases, you can also look in /sys/fs/bcache/::
+
+ host:/sys/fs/bcache# ls -l */{cache?,bdev?}
+ lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
+ lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
+ lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
+
+ The device names will show which UUID is relevant, cd in that directory
+ and stop the cache::
+
+ host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
+
+ This will free up bcache references and let you reuse the partition for
+ other purposes.
+
+
+
+Troubleshooting performance
+---------------------------
+
+Bcache has a bunch of config options and tunables. The defaults are intended to
+be reasonable for typical desktop and server workloads, but they're not what you
+want for getting the best possible numbers when benchmarking.
+
+ - Backing device alignment
+
+ The default metadata size in bcache is 8k. If your backing device is
+ RAID based, then be sure to align this by a multiple of your stride
+ width using `bcache make --data-offset`. If you intend to expand your
+ disk array in the future, then multiply a series of primes by your
+ raid stripe size to get the disk multiples that you would like.
+
+ For example: If you have a 64k stripe size, then the following offset
+ would provide alignment for many common RAID5 data spindle counts::
+
+ 64k * 2*2*2*3*3*5*7 bytes = 161280k
+
+ That space is wasted, but for only 157.5MB you can grow your RAID 5
+ volume to the following data-spindle counts without re-aligning::
+
+ 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
+
+ - Bad write performance
+
+ If write performance is not what you expected, you probably wanted to be
+ running in writeback mode, which isn't the default (not due to a lack of
+ maturity, but simply because in writeback mode you'll lose data if something
+ happens to your SSD)::
+
+ # echo writeback > /sys/block/bcache0/bcache/cache_mode
+
+ - Bad performance, or traffic not going to the SSD that you'd expect
+
+ By default, bcache doesn't cache everything. It tries to skip sequential IO -
+ because you really want to be caching the random IO, and if you copy a 10
+ gigabyte file you probably don't want that pushing 10 gigabytes of randomly
+ accessed data out of your cache.
+
+ But if you want to benchmark reads from cache, and you start out with fio
+ writing an 8 gigabyte test file - so you want to disable that::
+
+ # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
+
+ To set it back to the default (4 mb), do::
+
+ # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
+
+ - Traffic's still going to the spindle/still getting cache misses
+
+ In the real world, SSDs don't always keep up with disks - particularly with
+ slower SSDs, many disks being cached by one SSD, or mostly sequential IO. So
+ you want to avoid being bottlenecked by the SSD and having it slow everything
+ down.
+
+ To avoid that bcache tracks latency to the cache device, and gradually
+ throttles traffic if the latency exceeds a threshold (it does this by
+ cranking down the sequential bypass).
+
+ You can disable this if you need to by setting the thresholds to 0::
+
+ # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
+ # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
+
+ The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.
+
+ - Still getting cache misses, of the same data
+
+ One last issue that sometimes trips people up is actually an old bug, due to
+ the way cache coherency is handled for cache misses. If a btree node is full,
+ a cache miss won't be able to insert a key for the new data and the data
+ won't be written to the cache.
+
+ In practice this isn't an issue because as soon as a write comes along it'll
+ cause the btree node to be split, and you need almost no write traffic for
+ this to not show up enough to be noticeable (especially since bcache's btree
+ nodes are huge and index large regions of the device). But when you're
+ benchmarking, if you're trying to warm the cache by reading a bunch of data
+ and there's no other traffic - that can be a problem.
+
+ Solution: warm the cache by doing writes, or use the testing branch (there's
+ a fix for the issue there).
+
+
+Sysfs - backing device
+----------------------
+
+Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
+(if attached) /sys/fs/bcache/<cset-uuid>/bdev*
+
+attach
+ Echo the UUID of a cache set to this file to enable caching.
+
+cache_mode
+ Can be one of either writethrough, writeback, writearound or none.
+
+clear_stats
+ Writing to this file resets the running total stats (not the day/hour/5 minute
+ decaying versions).
+
+detach
+ Write to this file to detach from a cache set. If there is dirty data in the
+ cache, it will be flushed first.
+
+dirty_data
+ Amount of dirty data for this backing device in the cache. Continuously
+ updated unlike the cache set's version, but may be slightly off.
+
+label
+ Name of underlying device.
+
+readahead
+ Size of readahead that should be performed. Defaults to 0. If set to e.g.
+ 1M, it will round cache miss reads up to that size, but without overlapping
+ existing cache entries.
+
+running
+ 1 if bcache is running (i.e. whether the /dev/bcache device exists, whether
+ it's in passthrough mode or caching).
+
+sequential_cutoff
+ A sequential IO will bypass the cache once it passes this threshold; the
+ most recent 128 IOs are tracked so sequential IO can be detected even when
+ it isn't all done at once.
+
+sequential_merge
+ If non zero, bcache keeps a list of the last 128 requests submitted to compare
+ against all new requests to determine which new requests are sequential
+ continuations of previous requests for the purpose of determining sequential
+ cutoff. This is necessary if the sequential cutoff value is greater than the
+ maximum acceptable sequential size for any single request.
+
+state
+ The backing device can be in one of four different states:
+
+ no cache: Has never been attached to a cache set.
+
+ clean: Part of a cache set, and there is no cached dirty data.
+
+ dirty: Part of a cache set, and there is cached dirty data.
+
+ inconsistent: The backing device was forcibly run by the user when there was
+ dirty data cached but the cache set was unavailable; whatever data was on the
+ backing device has likely been corrupted.
+
+stop
+ Write to this file to shut down the bcache device and close the backing
+ device.
+
+writeback_delay
+ When dirty data is written to the cache and it previously did not contain
+ any, waits some number of seconds before initiating writeback. Defaults to
+ 30.
+
+writeback_percent
+ If nonzero, bcache tries to keep around this percentage of the cache dirty by
+ throttling background writeback and using a PD controller to smoothly adjust
+ the rate.
+
+writeback_rate
+ Rate in sectors per second - if writeback_percent is nonzero, background
+ writeback is throttled to this rate. Continuously adjusted by bcache but may
+ also be set by the user.
+
+writeback_running
+ If off, writeback of dirty data will not take place at all. Dirty data will
+ still be added to the cache until it is mostly full; only meant for
+ benchmarking. Defaults to on.
+
+Sysfs - backing device stats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are directories with these numbers for a running total, as well as
+versions that decay over the past day, hour and 5 minutes; they're also
+aggregated in the cache set directory as well.
+
+bypassed
+ Amount of IO (both reads and writes) that has bypassed the cache
+
+cache_hits, cache_misses, cache_hit_ratio
+ Hits and misses are counted per individual IO as bcache sees them; a
+ partial hit is counted as a miss.
+
+cache_bypass_hits, cache_bypass_misses
+ Hits and misses for IO that is intended to skip the cache are still counted,
+ but broken out here.
+
+cache_miss_collisions
+ Counts instances where data was going to be inserted into the cache from a
+ cache miss, but raced with a write and data was already present (usually 0
+ since the synchronization for cache misses was rewritten)
+
+Sysfs - cache set
+~~~~~~~~~~~~~~~~~
+
+Available at /sys/fs/bcache/<cset-uuid>
+
+average_key_size
+ Average data per key in the btree.
+
+bdev<0..n>
+ Symlink to each of the attached backing devices.
+
+block_size
+ Block size of the cache devices.
+
+btree_cache_size
+ Amount of memory currently used by the btree cache
+
+bucket_size
+ Size of buckets
+
+cache<0..n>
+ Symlink to each of the cache devices comprising this cache set.
+
+cache_available_percent
+ Percentage of cache device which doesn't contain dirty data, and could
+ potentially be used for writeback. This doesn't mean this space isn't used
+ for clean cached data; the unused statistic (in priority_stats) is typically
+ much lower.
+
+clear_stats
+ Clears the statistics associated with this cache
+
+dirty_data
+ Amount of dirty data is in the cache (updated when garbage collection runs).
+
+flash_vol_create
+ Echoing a size to this file (in human readable units, k/M/G) creates a thinly
+ provisioned volume backed by the cache set.
+
+io_error_halflife, io_error_limit
+ These determines how many errors we accept before disabling the cache.
+ Each error is decayed by the half life (in # ios). If the decaying count
+ reaches io_error_limit dirty data is written out and the cache is disabled.
+
+journal_delay_ms
+ Journal writes will delay for up to this many milliseconds, unless a cache
+ flush happens sooner. Defaults to 100.
+
+root_usage_percent
+ Percentage of the root btree node in use. If this gets too high the node
+ will split, increasing the tree depth.
+
+stop
+ Write to this file to shut down the cache set - waits until all attached
+ backing devices have been shut down.
+
+tree_depth
+ Depth of the btree (A single node btree has depth 0).
+
+unregister
+ Detaches all backing devices and closes the cache devices; if dirty data is
+ present it will disable writeback caching and wait for it to be flushed.
+
+Sysfs - cache set internal
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This directory also exposes timings for a number of internal operations, with
+separate files for average duration, average frequency, last occurrence and max
+duration: garbage collection, btree read, btree node sorts and btree splits.
+
+active_journal_entries
+ Number of journal entries that are newer than the index.
+
+btree_nodes
+ Total nodes in the btree.
+
+btree_used_percent
+ Average fraction of btree in use.
+
+bset_tree_stats
+ Statistics about the auxiliary search trees
+
+btree_cache_max_chain
+ Longest chain in the btree node cache's hash table
+
+cache_read_races
+ Counts instances where while data was being read from the cache, the bucket
+ was reused and invalidated - i.e. where the pointer was stale after the read
+ completed. When this occurs the data is reread from the backing device.
+
+trigger_gc
+ Writing to this file forces garbage collection to run.
+
+Sysfs - Cache device
+~~~~~~~~~~~~~~~~~~~~
+
+Available at /sys/block/<cdev>/bcache
+
+block_size
+ Minimum granularity of writes - should match hardware sector size.
+
+btree_written
+ Sum of all btree writes, in (kilo/mega/giga) bytes
+
+bucket_size
+ Size of buckets
+
+cache_replacement_policy
+ One of either lru, fifo or random.
+
+freelist_percent
+ Size of the freelist as a percentage of nbuckets. Can be written to to
+ increase the number of buckets kept on the freelist, which lets you
+ artificially reduce the size of the cache at runtime. Mostly for testing
+ purposes (i.e. testing how different size caches affect your hit rate).
+
+io_errors
+ Number of errors that have occurred, decayed by io_error_halflife.
+
+metadata_written
+ Sum of all non data writes (btree writes and all other metadata).
+
+nbuckets
+ Total buckets in this cache
+
+priority_stats
+ Statistics about how recently data in the cache has been accessed.
+ This can reveal your working set size. Unused is the percentage of
+ the cache that doesn't contain any data. Metadata is bcache's
+ metadata overhead. Average is the average priority of cache buckets.
+ Next is a list of quantiles with the priority threshold of each.
+
+written
+ Sum of all data that has been written to the cache; comparison with
+ btree_written gives the amount of write inflation in bcache.
diff --git a/Documentation/admin-guide/binderfs.rst b/Documentation/admin-guide/binderfs.rst
new file mode 100644
index 000000000000..41a4db00df8d
--- /dev/null
+++ b/Documentation/admin-guide/binderfs.rst
@@ -0,0 +1,87 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+The Android binderfs Filesystem
+===============================
+
+Android binderfs is a filesystem for the Android binder IPC mechanism. It
+allows to dynamically add and remove binder devices at runtime. Binder devices
+located in a new binderfs instance are independent of binder devices located in
+other binderfs instances. Mounting a new binderfs instance makes it possible
+to get a set of private binder devices.
+
+Mounting binderfs
+-----------------
+
+Android binderfs can be mounted with::
+
+ mkdir /dev/binderfs
+ mount -t binder binder /dev/binderfs
+
+at which point a new instance of binderfs will show up at ``/dev/binderfs``.
+In a fresh instance of binderfs no binder devices will be present. There will
+only be a ``binder-control`` device which serves as the request handler for
+binderfs. Mounting another binderfs instance at a different location will
+create a new and separate instance from all other binderfs mounts. This is
+identical to the behavior of e.g. ``devpts`` and ``tmpfs``. The Android
+binderfs filesystem can be mounted in user namespaces.
+
+Options
+-------
+max
+ binderfs instances can be mounted with a limit on the number of binder
+ devices that can be allocated. The ``max=<count>`` mount option serves as
+ a per-instance limit. If ``max=<count>`` is set then only ``<count>`` number
+ of binder devices can be allocated in this binderfs instance.
+
+stats
+ Using ``stats=global`` enables global binder statistics.
+ ``stats=global`` is only available for a binderfs instance mounted in the
+ initial user namespace. An attempt to use the option to mount a binderfs
+ instance in another user namespace will return a permission error.
+
+Allocating binder Devices
+-------------------------
+
+.. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
+
+To allocate a new binder device in a binderfs instance a request needs to be
+sent through the ``binder-control`` device node. A request is sent in the form
+of an `ioctl() <ioctl_>`_.
+
+What a program needs to do is to open the ``binder-control`` device node and
+send a ``BINDER_CTL_ADD`` request to the kernel. Users of binderfs need to
+tell the kernel which name the new binder device should get. By default a name
+can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
+zero byte.
+
+Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
+binder_device`` with the name to the kernel it will allocate a new binder
+device and return the major and minor number of the new device in the struct
+(This is necessary because binderfs allocates a major device number
+dynamically.). After the `ioctl() <ioctl_>`_ returns there will be a new
+binder device located under /dev/binderfs with the chosen name.
+
+Deleting binder Devices
+-----------------------
+
+.. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
+.. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
+
+Binderfs binder devices can be deleted via `unlink() <unlink_>`_. This means
+that the `rm() <rm_>`_ tool can be used to delete them. Note that the
+``binder-control`` device cannot be deleted since this would make the binderfs
+instance unusable. The ``binder-control`` device will be deleted when the
+binderfs instance is unmounted and all references to it have been dropped.
+
+Binder features
+---------------
+
+Assuming an instance of binderfs has been mounted at ``/dev/binderfs``, the
+features supported by the binder driver can be located under
+``/dev/binderfs/features/``. The presence of individual files can be tested
+to determine whether a particular feature is supported by the driver.
+
+Example::
+
+ cat /dev/binderfs/features/oneway_spam_detection
+ 1
diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst
new file mode 100644
index 000000000000..59cd902e3549
--- /dev/null
+++ b/Documentation/admin-guide/binfmt-misc.rst
@@ -0,0 +1,151 @@
+Kernel Support for miscellaneous Binary Formats (binfmt_misc)
+=============================================================
+
+This Kernel feature allows you to invoke almost (for restrictions see below)
+every program by simply typing its name in the shell.
+This includes for example compiled Java(TM), Python or Emacs programs.
+
+To achieve this you must tell binfmt_misc which interpreter has to be invoked
+with which binary. Binfmt_misc recognises the binary-type by matching some bytes
+at the beginning of the file with a magic byte sequence (masking out specified
+bits) you have supplied. Binfmt_misc can also recognise a filename extension
+aka ``.com`` or ``.exe``.
+
+First you must mount binfmt_misc::
+
+ mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
+
+To actually register a new binary type, you have to set up a string looking like
+``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the
+``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``.
+
+Here is what the fields mean:
+
+- ``name``
+ is an identifier string. A new /proc file will be created with this
+ name below ``/proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for
+ obvious reasons.
+- ``type``
+ is the type of recognition. Give ``M`` for magic and ``E`` for extension.
+- ``offset``
+ is the offset of the magic/mask in the file, counted in bytes. This
+ defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``).
+ Ignored when using filename extension matching.
+- ``magic``
+ is the byte sequence binfmt_misc is matching for. The magic string
+ may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you
+ must escape any NUL bytes; parsing halts at the first one. In a shell
+ environment you might have to write ``\\x0a`` to prevent the shell from
+ eating your ``\``.
+ If you chose filename extension matching, this is the extension to be
+ recognised (without the ``.``, the ``\x0a`` specials are not allowed).
+ Extension matching is case sensitive, and slashes ``/`` are not allowed!
+- ``mask``
+ is an (optional, defaults to all 0xff) mask. You can mask out some
+ bits from matching by supplying a string like magic and as long as magic.
+ The mask is anded with the byte sequence of the file. Note that you must
+ escape any NUL bytes; parsing halts at the first one. Ignored when using
+ filename extension matching.
+- ``interpreter``
+ is the program that should be invoked with the binary as first
+ argument (specify the full path)
+- ``flags``
+ is an optional field that controls several aspects of the invocation
+ of the interpreter. It is a string of capital letters, each controls a
+ certain aspect. The following flags are supported:
+
+ ``P`` - preserve-argv[0]
+ Legacy behavior of binfmt_misc is to overwrite
+ the original argv[0] with the full path to the binary. When this
+ flag is included, binfmt_misc will add an argument to the argument
+ vector for this purpose, thus preserving the original ``argv[0]``.
+ e.g. If your interp is set to ``/bin/foo`` and you run ``blah``
+ (which is in ``/usr/local/bin``), then the kernel will execute
+ ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can
+ execute ``/usr/local/bin/blah``
+ with ``argv[]`` set to ``["blah"]``.
+ ``O`` - open-binary
+ Legacy behavior of binfmt_misc is to pass the full path
+ of the binary to the interpreter as an argument. When this flag is
+ included, binfmt_misc will open the file for reading and pass its
+ descriptor as an argument, instead of the full path, thus allowing
+ the interpreter to execute non-readable binaries. This feature
+ should be used with care - the interpreter has to be trusted not to
+ emit the contents of the non-readable binary.
+ ``C`` - credentials
+ Currently, the behavior of binfmt_misc is to calculate
+ the credentials and security token of the new process according to
+ the interpreter. When this flag is included, these attributes are
+ calculated according to the binary. It also implies the ``O`` flag.
+ This feature should be used with care as the interpreter
+ will run with root permissions when a setuid binary owned by root
+ is run with binfmt_misc.
+ ``F`` - fix binary
+ The usual behaviour of binfmt_misc is to spawn the
+ binary lazily when the misc format file is invoked. However,
+ this doesn't work very well in the face of mount namespaces and
+ changeroots, so the ``F`` mode opens the binary as soon as the
+ emulation is installed and uses the opened image to spawn the
+ emulator, meaning it is always available once installed,
+ regardless of how the environment changes.
+
+
+There are some restrictions:
+
+ - the whole register string may not exceed 1920 characters
+ - the magic must reside in the first 128 bytes of the file, i.e.
+ offset+size(magic) has to be less than 128
+ - the interpreter string may not exceed 127 characters
+
+To use binfmt_misc you have to mount it first. You can mount it with
+``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add
+a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your
+``/etc/fstab`` so it auto mounts on boot.
+
+You may want to add the binary formats in one of your ``/etc/rc`` scripts during
+boot-up. Read the manual of your init program to figure out how to do this
+right.
+
+Think about the order of adding entries! Later added entries are matched first!
+
+
+A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``):
+
+- enable support for em86 (like binfmt_em86, for Alpha AXP only)::
+
+ echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
+ echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
+
+- enable support for packed DOS applications (pre-configured dosemu hdimages)::
+
+ echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register
+
+- enable support for Windows executables using wine::
+
+ echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register
+
+For java support see Documentation/admin-guide/java.rst
+
+
+You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable)
+or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or
+``/proc/.../the_name``.
+Catting the file tells you the current status of ``binfmt_misc/the_entry``.
+
+You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name``
+or ``/proc/sys/fs/binfmt_misc/status``.
+
+
+Hints
+-----
+
+If you want to pass special arguments to your interpreter, you can
+write a wrapper script for it.
+See :doc:`Documentation/admin-guide/java.rst <./java>` for an example.
+
+Your interpreter should NOT look in the PATH for the filename; the kernel
+passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can
+cause unexpected behaviour and can be a security hazard.
+
+
+Richard Günther <rguenth@tat.physik.uni-tuebingen.de>
diff --git a/Documentation/blockdev/drbd/DRBD-8.3-data-packets.svg b/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg
index f87cfa0dc2fb..f87cfa0dc2fb 100644
--- a/Documentation/blockdev/drbd/DRBD-8.3-data-packets.svg
+++ b/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg
diff --git a/Documentation/blockdev/drbd/DRBD-data-packets.svg b/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg
index 48a1e2165fec..48a1e2165fec 100644
--- a/Documentation/blockdev/drbd/DRBD-data-packets.svg
+++ b/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg
diff --git a/Documentation/blockdev/drbd/conn-states-8.dot b/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot
index 025e8cf5e64a..025e8cf5e64a 100644
--- a/Documentation/blockdev/drbd/conn-states-8.dot
+++ b/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot
diff --git a/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst b/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst
new file mode 100644
index 000000000000..66036b901644
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst
@@ -0,0 +1,42 @@
+================================
+kernel data structure for DRBD-9
+================================
+
+This describes the in kernel data structure for DRBD-9. Starting with
+Linux v3.14 we are reorganizing DRBD to use this data structure.
+
+Basic Data Structure
+====================
+
+A node has a number of DRBD resources. Each such resource has a number of
+devices (aka volumes) and connections to other nodes ("peer nodes"). Each DRBD
+device is represented by a block device locally.
+
+The DRBD objects are interconnected to form a matrix as depicted below; a
+drbd_peer_device object sits at each intersection between a drbd_device and a
+drbd_connection::
+
+ /--------------+---------------+.....+---------------\
+ | resource | device | | device |
+ +--------------+---------------+.....+---------------+
+ | connection | peer_device | | peer_device |
+ +--------------+---------------+.....+---------------+
+ : : : : :
+ : : : : :
+ +--------------+---------------+.....+---------------+
+ | connection | peer_device | | peer_device |
+ \--------------+---------------+.....+---------------/
+
+In this table, horizontally, devices can be accessed from resources by their
+volume number. Likewise, peer_devices can be accessed from connections by
+their volume number. Objects in the vertical direction are connected by double
+linked lists. There are back pointers from peer_devices to their connections a
+devices, and from connections and devices to their resource.
+
+All resources are in the drbd_resources double-linked list. In addition, all
+devices can be accessed by their minor device number via the drbd_devices idr.
+
+The drbd_resource, drbd_connection, and drbd_device objects are reference
+counted. The peer_device objects only serve to establish the links between
+devices and connections; their lifetime is determined by the lifetime of the
+device and connection which they reference.
diff --git a/Documentation/blockdev/drbd/disk-states-8.dot b/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot
index d06cfb46fb98..d06cfb46fb98 100644
--- a/Documentation/blockdev/drbd/disk-states-8.dot
+++ b/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot
diff --git a/Documentation/blockdev/drbd/drbd-connection-state-overview.dot b/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot
index 6d9cf0a7b11d..6d9cf0a7b11d 100644
--- a/Documentation/blockdev/drbd/drbd-connection-state-overview.dot
+++ b/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot
diff --git a/Documentation/admin-guide/blockdev/drbd/figures.rst b/Documentation/admin-guide/blockdev/drbd/figures.rst
new file mode 100644
index 000000000000..9f73253ea353
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/figures.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. The here included files are intended to help understand the implementation
+
+Data flows that Relate some functions, and write packets
+========================================================
+
+.. kernel-figure:: DRBD-8.3-data-packets.svg
+ :alt: DRBD-8.3-data-packets.svg
+ :align: center
+
+.. kernel-figure:: DRBD-data-packets.svg
+ :alt: DRBD-data-packets.svg
+ :align: center
+
+
+Sub graphs of DRBD's state transitions
+======================================
+
+.. kernel-figure:: conn-states-8.dot
+ :alt: conn-states-8.dot
+ :align: center
+
+.. kernel-figure:: disk-states-8.dot
+ :alt: disk-states-8.dot
+ :align: center
+
+.. kernel-figure:: peer-states-8.dot
+ :alt: peer-states-8.dot
+ :align: center
diff --git a/Documentation/admin-guide/blockdev/drbd/index.rst b/Documentation/admin-guide/blockdev/drbd/index.rst
new file mode 100644
index 000000000000..561fd1e35917
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/index.rst
@@ -0,0 +1,19 @@
+==========================================
+Distributed Replicated Block Device - DRBD
+==========================================
+
+Description
+===========
+
+ DRBD is a shared-nothing, synchronously replicated block device. It
+ is designed to serve as a building block for high availability
+ clusters and in this context, is a "drop-in" replacement for shared
+ storage. Simplistically, you could see it as a network RAID 1.
+
+ Please visit https://www.drbd.org to find out more.
+
+.. toctree::
+ :maxdepth: 1
+
+ data-structure-v9
+ figures
diff --git a/Documentation/admin-guide/blockdev/drbd/peer-states-8.dot b/Documentation/admin-guide/blockdev/drbd/peer-states-8.dot
new file mode 100644
index 000000000000..6dc3954954d6
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/drbd/peer-states-8.dot
@@ -0,0 +1,8 @@
+digraph peer_states {
+ Secondary -> Primary [ label = "recv state packet" ]
+ Primary -> Secondary [ label = "recv state packet" ]
+ Primary -> Unknown [ label = "connection lost" ]
+ Secondary -> Unknown [ label = "connection lost" ]
+ Unknown -> Primary [ label = "connected" ]
+ Unknown -> Secondary [ label = "connected" ]
+}
diff --git a/Documentation/admin-guide/blockdev/floppy.rst b/Documentation/admin-guide/blockdev/floppy.rst
new file mode 100644
index 000000000000..0328438ebe2c
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/floppy.rst
@@ -0,0 +1,255 @@
+=============
+Floppy Driver
+=============
+
+FAQ list:
+=========
+
+A FAQ list may be found in the fdutils package (see below), and also
+at <https://fdutils.linux.lu/faq.html>.
+
+
+LILO configuration options (Thinkpad users, read this)
+======================================================
+
+The floppy driver is configured using the 'floppy=' option in
+lilo. This option can be typed at the boot prompt, or entered in the
+lilo configuration file.
+
+Example: If your kernel is called linux-2.6.9, type the following line
+at the lilo boot prompt (if you have a thinkpad)::
+
+ linux-2.6.9 floppy=thinkpad
+
+You may also enter the following line in /etc/lilo.conf, in the description
+of linux-2.6.9::
+
+ append = "floppy=thinkpad"
+
+Several floppy related options may be given, example::
+
+ linux-2.6.9 floppy=daring floppy=two_fdc
+ append = "floppy=daring floppy=two_fdc"
+
+If you give options both in the lilo config file and on the boot
+prompt, the option strings of both places are concatenated, the boot
+prompt options coming last. That's why there are also options to
+restore the default behavior.
+
+
+Module configuration options
+============================
+
+If you use the floppy driver as a module, use the following syntax::
+
+ modprobe floppy floppy="<options>"
+
+Example::
+
+ modprobe floppy floppy="omnibook messages"
+
+If you need certain options enabled every time you load the floppy driver,
+you can put::
+
+ options floppy floppy="omnibook messages"
+
+in a configuration file in /etc/modprobe.d/.
+
+
+The floppy driver related options are:
+
+ floppy=asus_pci
+ Sets the bit mask to allow only units 0 and 1. (default)
+
+ floppy=daring
+ Tells the floppy driver that you have a well behaved floppy controller.
+ This allows more efficient and smoother operation, but may fail on
+ certain controllers. This may speed up certain operations.
+
+ floppy=0,daring
+ Tells the floppy driver that your floppy controller should be used
+ with caution.
+
+ floppy=one_fdc
+ Tells the floppy driver that you have only one floppy controller.
+ (default)
+
+ floppy=two_fdc / floppy=<address>,two_fdc
+ Tells the floppy driver that you have two floppy controllers.
+ The second floppy controller is assumed to be at <address>.
+ This option is not needed if the second controller is at address
+ 0x370, and if you use the 'cmos' option.
+
+ floppy=thinkpad
+ Tells the floppy driver that you have a Thinkpad. Thinkpads use an
+ inverted convention for the disk change line.
+
+ floppy=0,thinkpad
+ Tells the floppy driver that you don't have a Thinkpad.
+
+ floppy=omnibook / floppy=nodma
+ Tells the floppy driver not to use Dma for data transfers.
+ This is needed on HP Omnibooks, which don't have a workable
+ DMA channel for the floppy driver. This option is also useful
+ if you frequently get "Unable to allocate DMA memory" messages.
+ Indeed, dma memory needs to be continuous in physical memory,
+ and is thus harder to find, whereas non-dma buffers may be
+ allocated in virtual memory. However, I advise against this if
+ you have an FDC without a FIFO (8272A or 82072). 82072A and
+ later are OK. You also need at least a 486 to use nodma.
+ If you use nodma mode, I suggest you also set the FIFO
+ threshold to 10 or lower, in order to limit the number of data
+ transfer interrupts.
+
+ If you have a FIFO-able FDC, the floppy driver automatically
+ falls back on non DMA mode if no DMA-able memory can be found.
+ If you want to avoid this, explicitly ask for 'yesdma'.
+
+ floppy=yesdma
+ Tells the floppy driver that a workable DMA channel is available.
+ (default)
+
+ floppy=nofifo
+ Disables the FIFO entirely. This is needed if you get "Bus
+ master arbitration error" messages from your Ethernet card (or
+ from other devices) while accessing the floppy.
+
+ floppy=usefifo
+ Enables the FIFO. (default)
+
+ floppy=<threshold>,fifo_depth
+ Sets the FIFO threshold. This is mostly relevant in DMA
+ mode. If this is higher, the floppy driver tolerates more
+ interrupt latency, but it triggers more interrupts (i.e. it
+ imposes more load on the rest of the system). If this is
+ lower, the interrupt latency should be lower too (faster
+ processor). The benefit of a lower threshold is less
+ interrupts.
+
+ To tune the fifo threshold, switch on over/underrun messages
+ using 'floppycontrol --messages'. Then access a floppy
+ disk. If you get a huge amount of "Over/Underrun - retrying"
+ messages, then the fifo threshold is too low. Try with a
+ higher value, until you only get an occasional Over/Underrun.
+ It is a good idea to compile the floppy driver as a module
+ when doing this tuning. Indeed, it allows to try different
+ fifo values without rebooting the machine for each test. Note
+ that you need to do 'floppycontrol --messages' every time you
+ re-insert the module.
+
+ Usually, tuning the fifo threshold should not be needed, as
+ the default (0xa) is reasonable.
+
+ floppy=<drive>,<type>,cmos
+ Sets the CMOS type of <drive> to <type>. This is mandatory if
+ you have more than two floppy drives (only two can be
+ described in the physical CMOS), or if your BIOS uses
+ non-standard CMOS types. The CMOS types are:
+
+ == ==================================
+ 0 Use the value of the physical CMOS
+ 1 5 1/4 DD
+ 2 5 1/4 HD
+ 3 3 1/2 DD
+ 4 3 1/2 HD
+ 5 3 1/2 ED
+ 6 3 1/2 ED
+ 16 unknown or not installed
+ == ==================================
+
+ (Note: there are two valid types for ED drives. This is because 5 was
+ initially chosen to represent floppy *tapes*, and 6 for ED drives.
+ AMI ignored this, and used 5 for ED drives. That's why the floppy
+ driver handles both.)
+
+ floppy=unexpected_interrupts
+ Print a warning message when an unexpected interrupt is received.
+ (default)
+
+ floppy=no_unexpected_interrupts / floppy=L40SX
+ Don't print a message when an unexpected interrupt is received. This
+ is needed on IBM L40SX laptops in certain video modes. (There seems
+ to be an interaction between video and floppy. The unexpected
+ interrupts affect only performance, and can be safely ignored.)
+
+ floppy=broken_dcl
+ Don't use the disk change line, but assume that the disk was
+ changed whenever the device node is reopened. Needed on some
+ boxes where the disk change line is broken or unsupported.
+ This should be regarded as a stopgap measure, indeed it makes
+ floppy operation less efficient due to unneeded cache
+ flushings, and slightly more unreliable. Please verify your
+ cable, connection and jumper settings if you have any DCL
+ problems. However, some older drives, and also some laptops
+ are known not to have a DCL.
+
+ floppy=debug
+ Print debugging messages.
+
+ floppy=messages
+ Print informational messages for some operations (disk change
+ notifications, warnings about over and underruns, and about
+ autodetection).
+
+ floppy=silent_dcl_clear
+ Uses a less noisy way to clear the disk change line (which
+ doesn't involve seeks). Implied by 'daring' option.
+
+ floppy=<nr>,irq
+ Sets the floppy IRQ to <nr> instead of 6.
+
+ floppy=<nr>,dma
+ Sets the floppy DMA channel to <nr> instead of 2.
+
+ floppy=slow
+ Use PS/2 stepping rate::
+
+ PS/2 floppies have much slower step rates than regular floppies.
+ It's been recommended that take about 1/4 of the default speed
+ in some more extreme cases.
+
+
+Supporting utilities and additional documentation:
+==================================================
+
+Additional parameters of the floppy driver can be configured at
+runtime. Utilities which do this can be found in the fdutils package.
+This package also contains a new version of mtools which allows to
+access high capacity disks (up to 1992K on a high density 3 1/2 disk!).
+It also contains additional documentation about the floppy driver.
+
+The latest version can be found at fdutils homepage:
+
+ https://fdutils.linux.lu
+
+The fdutils releases can be found at:
+
+ https://fdutils.linux.lu/download.html
+
+ http://www.tux.org/pub/knaff/fdutils/
+
+ ftp://metalab.unc.edu/pub/Linux/utils/disk-management/
+
+Reporting problems about the floppy driver
+==========================================
+
+If you have a question or a bug report about the floppy driver, mail
+me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
+comp.os.linux.hardware. As the volume in these groups is rather high,
+be sure to include the word "floppy" (or "FLOPPY") in the subject
+line. If the reported problem happens when mounting floppy disks, be
+sure to mention also the type of the filesystem in the subject line.
+
+Be sure to read the FAQ before mailing/posting any bug reports!
+
+Alain
+
+Changelog
+=========
+
+10-30-2004 :
+ Cleanup, updating, add reference to module configuration.
+ James Nelson <james4765@gmail.com>
+
+6-3-2000 :
+ Original Document
diff --git a/Documentation/admin-guide/blockdev/index.rst b/Documentation/admin-guide/blockdev/index.rst
new file mode 100644
index 000000000000..3262397ebe8f
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+Block Devices
+=============
+
+.. toctree::
+ :maxdepth: 1
+
+ floppy
+ nbd
+ paride
+ ramdisk
+ zoned_loop
+ zram
+
+ drbd/index
diff --git a/Documentation/admin-guide/blockdev/nbd.rst b/Documentation/admin-guide/blockdev/nbd.rst
new file mode 100644
index 000000000000..faf2ac4b1509
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/nbd.rst
@@ -0,0 +1,31 @@
+==================================
+Network Block Device (TCP version)
+==================================
+
+1) Overview
+-----------
+
+What is it: With this compiled in the kernel (or as a module), Linux
+can use a remote server as one of its block devices. So every time
+the client computer wants to read, e.g., /dev/nb0, it sends a
+request over TCP to the server, which will reply with the data read.
+This can be used for stations with low disk space (or even diskless)
+to borrow disk space from another computer.
+Unlike NFS, it is possible to put any filesystem on it, etc.
+
+For more information, or to download the nbd-client and nbd-server
+tools, go to https://github.com/NetworkBlockDevice/nbd.
+
+The nbd kernel module need only be installed on the client
+system, as the nbd-server is completely in userspace. In fact,
+the nbd-server has been successfully ported to other operating
+systems, including Windows.
+
+A) NBD parameters
+-----------------
+
+max_part
+ Number of partitions per device (default: 0).
+
+nbds_max
+ Number of block devices that should be initialized (default: 16).
diff --git a/Documentation/admin-guide/blockdev/paride.rst b/Documentation/admin-guide/blockdev/paride.rst
new file mode 100644
index 000000000000..b2f627d4c2f8
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/paride.rst
@@ -0,0 +1,207 @@
+===================================
+Linux and parallel port IDE devices
+===================================
+
+PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net>
+PATA_PARPORT (c) 2023 Ondrej Zary
+
+1. Introduction
+===============
+
+Owing to the simplicity and near universality of the parallel port interface
+to personal computers, many external devices such as portable hard-disk,
+CD-ROM, LS-120 and tape drives use the parallel port to connect to their
+host computer. While some devices (notably scanners) use ad-hoc methods
+to pass commands and data through the parallel port interface, most
+external devices are actually identical to an internal model, but with
+a parallel-port adapter chip added in. Some of the original parallel port
+adapters were little more than mechanisms for multiplexing a SCSI bus.
+(The Iomega PPA-3 adapter used in the ZIP drives is an example of this
+approach). Most current designs, however, take a different approach.
+The adapter chip reproduces a small ISA or IDE bus in the external device
+and the communication protocol provides operations for reading and writing
+device registers, as well as data block transfer functions. Sometimes,
+the device being addressed via the parallel cable is a standard SCSI
+controller like an NCR 5380. The "ditto" family of external tape
+drives use the ISA replicator to interface a floppy disk controller,
+which is then connected to a floppy-tape mechanism. The vast majority
+of external parallel port devices, however, are now based on standard
+IDE type devices, which require no intermediate controller. If one
+were to open up a parallel port CD-ROM drive, for instance, one would
+find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
+that interconnected a standard PC parallel port cable and a standard
+IDE cable. It is usually possible to exchange the CD-ROM device with
+any other device using the IDE interface.
+
+The document describes the support in Linux for parallel port IDE
+devices. It does not cover parallel port SCSI devices, "ditto" tape
+drives or scanners. Many different devices are supported by the
+parallel port IDE subsystem, including:
+
+ - MicroSolutions backpack CD-ROM
+ - MicroSolutions backpack PD/CD
+ - MicroSolutions backpack hard-drives
+ - MicroSolutions backpack 8000t tape drive
+ - SyQuest EZ-135, EZ-230 & SparQ drives
+ - Avatar Shark
+ - Imation Superdisk LS-120
+ - Maxell Superdisk LS-120
+ - FreeCom Power CD
+ - Hewlett-Packard 5GB and 8GB tape drives
+ - Hewlett-Packard 7100 and 7200 CD-RW drives
+
+as well as most of the clone and no-name products on the market.
+
+To support such a wide range of devices, pata_parport is actually structured
+in two parts. There is a base pata_parport module which provides an interface
+to kernel libata subsystem, registry and some common methods for accessing
+the parallel ports.
+
+The second component is a set of low-level protocol drivers for each of the
+parallel port IDE adapter chips. Thanks to the interest and encouragement of
+Linux users from many parts of the world, support is available for almost all
+known adapter protocols:
+
+ ==== ====================================== ====
+ aten ATEN EH-100 (HK)
+ bpck Microsolutions backpack (US)
+ comm DataStor (old-type) "commuter" adapter (TW)
+ dstr DataStor EP-2000 (TW)
+ epat Shuttle EPAT (UK)
+ epia Shuttle EPIA (UK)
+ fit2 FIT TD-2000 (US)
+ fit3 FIT TD-3000 (US)
+ friq Freecom IQ cable (DE)
+ frpw Freecom Power (DE)
+ kbic KingByte KBIC-951A and KBIC-971A (TW)
+ ktti KT Technology PHd adapter (SG)
+ on20 OnSpec 90c20 (US)
+ on26 OnSpec 90c26 (US)
+ ==== ====================================== ====
+
+
+2. Using pata_parport subsystem
+===============================
+
+While configuring the Linux kernel, you may choose either to build
+the pata_parport drivers into your kernel, or to build them as modules.
+
+In either case, you will need to select "Parallel port IDE device support"
+and at least one of the parallel port communication protocols.
+If you do not know what kind of parallel port adapter is used in your drive,
+you could begin by checking the file names and any text files on your DOS
+installation floppy. Alternatively, you can look at the markings on
+the adapter chip itself. That's usually sufficient to identify the
+correct device.
+
+You can actually select all the protocol modules, and allow the pata_parport
+subsystem to try them all for you.
+
+For the "brand-name" products listed above, here are the protocol
+and high-level drivers that you would use:
+
+ ================ ============ ========
+ Manufacturer Model Protocol
+ ================ ============ ========
+ MicroSolutions CD-ROM bpck
+ MicroSolutions PD drive bpck
+ MicroSolutions hard-drive bpck
+ MicroSolutions 8000t tape bpck
+ SyQuest EZ, SparQ epat
+ Imation Superdisk epat
+ Maxell Superdisk friq
+ Avatar Shark epat
+ FreeCom CD-ROM frpw
+ Hewlett-Packard 5GB Tape epat
+ Hewlett-Packard 7200e (CD) epat
+ Hewlett-Packard 7200e (CD-R) epat
+ ================ ============ ========
+
+All parports and all protocol drivers are probed automatically unless probe=0
+parameter is used. So just "modprobe epat" is enough for an Imation SuperDisk
+drive to work.
+
+Manual device creation::
+
+ # echo "port protocol mode unit delay" >/sys/bus/pata_parport/new_device
+
+where:
+
+ ======== ================================================
+ port parport name (or "auto" for all parports)
+ protocol protocol name (or "auto" for all protocols)
+ mode mode number (protocol-specific) or -1 for probe
+ unit unit number (for backpack only, see below)
+ delay I/O delay (see troubleshooting section below)
+ ======== ================================================
+
+If you happen to be using a MicroSolutions backpack device, you will
+also need to know the unit ID number for each drive. This is usually
+the last two digits of the drive's serial number (but read MicroSolutions'
+documentation about this).
+
+If you omit the parameters from the end, defaults will be used, e.g.:
+
+Probe all parports with all protocols::
+
+ # echo auto >/sys/bus/pata_parport/new_device
+
+Probe parport0 using protocol epat and mode 4 (EPP-16)::
+
+ # echo "parport0 epat 4" >/sys/bus/pata_parport/new_device
+
+Probe parport0 using all protocols::
+
+ # echo "parport0 auto" >/sys/bus/pata_parport/new_device
+
+Probe all parports using protoocol epat::
+
+ # echo "auto epat" >/sys/bus/pata_parport/new_device
+
+Deleting devices::
+
+ # echo pata_parport.0 >/sys/bus/pata_parport/delete_device
+
+
+3. Troubleshooting
+==================
+
+3.1 Use EPP mode if you can
+----------------------------
+
+The most common problems that people report with the pata_parport drivers
+concern the parallel port CMOS settings. At this time, none of the
+protocol modules support ECP mode, or any ECP combination modes.
+If you are able to do so, please set your parallel port into EPP mode
+using your CMOS setup procedure.
+
+3.2 Check the port delay
+-------------------------
+
+Some parallel ports cannot reliably transfer data at full speed. To
+offset the errors, the protocol modules introduce a "port
+delay" between each access to the i/o ports. Each protocol sets
+a default value for this delay. In most cases, the user can override
+the default and set it to 0 - resulting in somewhat higher transfer
+rates. In some rare cases (especially with older 486 systems) the
+default delays are not long enough. if you experience corrupt data
+transfers, or unexpected failures, you may wish to increase the
+port delay.
+
+3.3 Some drives need a printer reset
+-------------------------------------
+
+There appear to be a number of "noname" external drives on the market
+that do not always power up correctly. We have noticed this with some
+drives based on OnSpec and older Freecom adapters. In these rare cases,
+the adapter can often be reinitialised by issuing a "printer reset" on
+the parallel port. As the reset operation is potentially disruptive in
+multiple device environments, the pata_parport drivers will not do it
+automatically. You can however, force a printer reset by doing::
+
+ insmod lp reset=1
+ rmmod lp
+
+If you have one of these marginal cases, you should probably build
+your pata_parport drivers as modules, and arrange to do the printer reset
+before loading the pata_parport drivers.
diff --git a/Documentation/admin-guide/blockdev/ramdisk.rst b/Documentation/admin-guide/blockdev/ramdisk.rst
new file mode 100644
index 000000000000..9ce6101e8dd9
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/ramdisk.rst
@@ -0,0 +1,153 @@
+==========================================
+Using the RAM disk block device with Linux
+==========================================
+
+.. Contents:
+
+ 1) Overview
+ 2) Kernel Command Line Parameters
+ 3) Using "rdev"
+ 4) An Example of Creating a Compressed RAM Disk
+
+
+1) Overview
+-----------
+
+The RAM disk driver is a way to use main system memory as a block device. It
+is required for initrd, an initial filesystem used if you need to load modules
+in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can
+also be used for a temporary filesystem for crypto work, since the contents
+are erased on reboot.
+
+The RAM disk dynamically grows as more space is required. It does this by using
+RAM from the buffer cache. The driver marks the buffers it is using as dirty
+so that the VM subsystem does not try to reclaim them later.
+
+The RAM disk supports up to 16 RAM disks by default, and can be reconfigured
+to support an unlimited number of RAM disks (at your own risk). Just change
+the configuration symbol BLK_DEV_RAM_COUNT in the Block drivers config menu
+and (re)build the kernel.
+
+To use RAM disk support with your system, run './MAKEDEV ram' from the /dev
+directory. RAM disks are all major number 1, and start with minor number 0
+for /dev/ram0, etc. If used, modern kernels use /dev/ram0 for an initrd.
+
+The new RAM disk also has the ability to load compressed RAM disk images,
+allowing one to squeeze more programs onto an average installation or
+rescue floppy disk.
+
+
+2) Parameters
+---------------------------------
+
+2a) Kernel Command Line Parameters
+
+ ramdisk_size=N
+ Size of the ramdisk.
+
+This parameter tells the RAM disk driver to set up RAM disks of N k size. The
+default is 4096 (4 MB).
+
+2b) Module parameters
+
+ rd_nr
+ /dev/ramX devices created.
+
+ max_part
+ Maximum partition number.
+
+ rd_size
+ See ramdisk_size.
+
+3) Using "rdev"
+---------------
+
+"rdev" is an obsolete, deprecated, antiquated utility that could be used
+to set the boot device in a Linux kernel image.
+
+Instead of using rdev, just place the boot device information on the
+kernel command line and pass it to the kernel from the bootloader.
+
+You can also pass arguments to the kernel by setting FDARGS in
+arch/x86/boot/Makefile and specify in initrd image by setting FDINITRD in
+arch/x86/boot/Makefile.
+
+Some of the kernel command line boot options that may apply here are::
+
+ ramdisk_start=N
+ ramdisk_size=M
+
+If you make a boot disk that has LILO, then for the above, you would use::
+
+ append = "ramdisk_start=N ramdisk_size=M"
+
+4) An Example of Creating a Compressed RAM Disk
+-----------------------------------------------
+
+To create a RAM disk image, you will need a spare block device to
+construct it on. This can be the RAM disk device itself, or an
+unused disk partition (such as an unmounted swap partition). For this
+example, we will use the RAM disk device, "/dev/ram0".
+
+Note: This technique should not be done on a machine with less than 8 MB
+of RAM. If using a spare disk partition instead of /dev/ram0, then this
+restriction does not apply.
+
+a) Decide on the RAM disk size that you want. Say 2 MB for this example.
+ Create it by writing to the RAM disk device. (This step is not currently
+ required, but may be in the future.) It is wise to zero out the
+ area (esp. for disks) so that maximal compression is achieved for
+ the unused blocks of the image that you are about to create::
+
+ dd if=/dev/zero of=/dev/ram0 bs=1k count=2048
+
+b) Make a filesystem on it. Say ext2fs for this example::
+
+ mke2fs -vm0 /dev/ram0 2048
+
+c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
+ and unmount it again.
+
+d) Compress the contents of the RAM disk. The level of compression
+ will be approximately 50% of the space used by the files. Unused
+ space on the RAM disk will compress to almost nothing::
+
+ dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz
+
+e) Put the kernel onto the floppy::
+
+ dd if=zImage of=/dev/fd0 bs=1k
+
+f) Put the RAM disk image onto the floppy, after the kernel. Use an offset
+ that is slightly larger than the kernel, so that you can put another
+ (possibly larger) kernel onto the same floppy later without overlapping
+ the RAM disk image. An offset of 400 kB for kernels about 350 kB in
+ size would be reasonable. Make sure offset+size of ram_image.gz is
+ not larger than the total space on your floppy (usually 1440 kB)::
+
+ dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400
+
+g) Make sure that you have already specified the boot information in
+ FDARGS and FDINITRD or that you use a bootloader to pass kernel
+ command line boot options to the kernel.
+
+That is it. You now have your boot/root compressed RAM disk floppy. Some
+users may wish to combine steps (d) and (f) by using a pipe.
+
+
+ Paul Gortmaker 12/95
+
+Changelog:
+----------
+
+SEPT-2020 :
+
+ Removed usage of "rdev"
+
+10-22-04 :
+ Updated to reflect changes in command line options, remove
+ obsolete references, general cleanup.
+ James Nelson (james4765@gmail.com)
+
+12-95 :
+ Original Document
diff --git a/Documentation/admin-guide/blockdev/zoned_loop.rst b/Documentation/admin-guide/blockdev/zoned_loop.rst
new file mode 100644
index 000000000000..806adde664db
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/zoned_loop.rst
@@ -0,0 +1,182 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+Zoned Loop Block Device
+=======================
+
+.. Contents:
+
+ 1) Overview
+ 2) Creating a Zoned Device
+ 3) Deleting a Zoned Device
+ 4) Example
+
+
+1) Overview
+-----------
+
+The zoned loop block device driver (zloop) allows a user to create a zoned block
+device using one regular file per zone as backing storage. This driver does not
+directly control any hardware and uses read, write and truncate operations to
+regular files of a file system to emulate a zoned block device.
+
+Using zloop, zoned block devices with a configurable capacity, zone size and
+number of conventional zones can be created. The storage for each zone of the
+device is implemented using a regular file with a maximum size equal to the zone
+size. The size of a file backing a conventional zone is always equal to the zone
+size. The size of a file backing a sequential zone indicates the amount of data
+sequentially written to the file, that is, the size of the file directly
+indicates the position of the write pointer of the zone.
+
+When resetting a sequential zone, its backing file size is truncated to zero.
+Conversely, for a zone finish operation, the backing file is truncated to the
+zone size. With this, the maximum capacity of a zloop zoned block device created
+can be larger configured to be larger than the storage space available on the
+backing file system. Of course, for such configuration, writing more data than
+the storage space available on the backing file system will result in write
+errors.
+
+The zoned loop block device driver implements a complete zone transition state
+machine. That is, zones can be empty, implicitly opened, explicitly opened,
+closed or full. The current implementation does not support any limits on the
+maximum number of open and active zones.
+
+No user tools are necessary to create and delete zloop devices.
+
+2) Creating a Zoned Device
+--------------------------
+
+Once the zloop module is loaded (or if zloop is compiled in the kernel), the
+character device file /dev/zloop-control can be used to add a zloop device.
+This is done by writing an "add" command directly to the /dev/zloop-control
+device::
+
+ $ modprobe zloop
+ $ ls -l /dev/zloop*
+ crw-------. 1 root root 10, 123 Jan 6 19:18 /dev/zloop-control
+
+ $ mkdir -p <base directory/<device ID>
+ $ echo "add [options]" > /dev/zloop-control
+
+The options available for the add command can be listed by reading the
+/dev/zloop-control device::
+
+ $ cat /dev/zloop-control
+ add id=%d,capacity_mb=%u,zone_size_mb=%u,zone_capacity_mb=%u,conv_zones=%u,base_dir=%s,nr_queues=%u,queue_depth=%u,buffered_io
+ remove id=%d
+
+In more details, the options that can be used with the "add" command are as
+follows.
+
+=================== =========================================================
+id Device number (the X in /dev/zloopX).
+ Default: automatically assigned.
+capacity_mb Device total capacity in MiB. This is always rounded up
+ to the nearest higher multiple of the zone size.
+ Default: 16384 MiB (16 GiB).
+zone_size_mb Device zone size in MiB. Default: 256 MiB.
+zone_capacity_mb Device zone capacity (must always be equal to or lower
+ than the zone size. Default: zone size.
+conv_zones Total number of conventioanl zones starting from
+ sector 0
+ Default: 8
+base_dir Path to the base directory where to create the directory
+ containing the zone files of the device.
+ Default=/var/local/zloop.
+ The device directory containing the zone files is always
+ named with the device ID. E.g. the default zone file
+ directory for /dev/zloop0 is /var/local/zloop/0.
+nr_queues Number of I/O queues of the zoned block device. This
+ value is always capped by the number of online CPUs
+ Default: 1
+queue_depth Maximum I/O queue depth per I/O queue.
+ Default: 64
+buffered_io Do buffered IOs instead of direct IOs (default: false)
+zone_append Enable or disable a zloop device native zone append
+ support.
+ Default: 1 (enabled).
+ If native zone append support is disabled, the block layer
+ will emulate this operation using regular write
+ operations.
+ordered_zone_append Enable zloop mitigation of zone append reordering.
+ Default: disabled.
+ This is useful for testing file systems file data mapping
+ (extents), as when enabled, this can significantly reduce
+ the number of data extents needed to for a file data
+ mapping.
+=================== =========================================================
+
+3) Deleting a Zoned Device
+--------------------------
+
+Deleting an unused zoned loop block device is done by issuing the "remove"
+command to /dev/zloop-control, specifying the ID of the device to remove::
+
+ $ echo "remove id=X" > /dev/zloop-control
+
+The remove command does not have any option.
+
+A zoned device that was removed can be re-added again without any change to the
+state of the device zones: the device zones are restored to their last state
+before the device was removed. Adding again a zoned device after it was removed
+must always be done using the same configuration as when the device was first
+added. If a zone configuration change is detected, an error will be returned and
+the zoned device will not be created.
+
+To fully delete a zoned device, after executing the remove operation, the device
+base directory containing the backing files of the device zones must be deleted.
+
+4) Example
+----------
+
+The following sequence of commands creates a 2GB zoned device with zones of 64
+MB and a zone capacity of 63 MB::
+
+ $ modprobe zloop
+ $ mkdir -p /var/local/zloop/0
+ $ echo "add capacity_mb=2048,zone_size_mb=64,zone_capacity=63MB" > /dev/zloop-control
+
+For the device created (/dev/zloop0), the zone backing files are all created
+under the default base directory (/var/local/zloop)::
+
+ $ ls -l /var/local/zloop/0
+ total 0
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000000
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000001
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000002
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000003
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000004
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000005
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000006
+ -rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000007
+ -rw-------. 1 root root 0 Jan 6 22:23 seq-000008
+ -rw-------. 1 root root 0 Jan 6 22:23 seq-000009
+ ...
+
+The zoned device created (/dev/zloop0) can then be used normally::
+
+ $ lsblk -z
+ NAME ZONED ZONE-SZ ZONE-NR ZONE-AMAX ZONE-OMAX ZONE-APP ZONE-WGRAN
+ zloop0 host-managed 64M 32 0 0 1M 4K
+ $ blkzone report /dev/zloop0
+ start: 0x000000000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x000020000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x000040000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x000060000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x000080000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x0000a0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x0000c0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x0000e0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
+ start: 0x000100000, len 0x020000, cap 0x01f800, wptr 0x000000 reset:0 non-seq:0, zcond: 1(em) [type: 2(SEQ_WRITE_REQUIRED)]
+ start: 0x000120000, len 0x020000, cap 0x01f800, wptr 0x000000 reset:0 non-seq:0, zcond: 1(em) [type: 2(SEQ_WRITE_REQUIRED)]
+ ...
+
+Deleting this device is done using the command::
+
+ $ echo "remove id=0" > /dev/zloop-control
+
+The removed device can be re-added again using the same "add" command as when
+the device was first created. To fully delete a zoned device, its backing files
+should also be deleted after executing the remove command::
+
+ $ rm -r /var/local/zloop/0
diff --git a/Documentation/admin-guide/blockdev/zram.rst b/Documentation/admin-guide/blockdev/zram.rst
new file mode 100644
index 000000000000..3e273c1bb749
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/zram.rst
@@ -0,0 +1,569 @@
+========================================
+zram: Compressed RAM-based block devices
+========================================
+
+Introduction
+============
+
+The zram module creates RAM-based block devices named /dev/zram<id>
+(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
+in memory itself. These disks allow very fast I/O and compression provides
+good amounts of memory savings. Some of the use cases include /tmp storage,
+use as swap disks, various caches under /var and maybe many more. :)
+
+Statistics for individual zram devices are exported through sysfs nodes at
+/sys/block/zram<id>/
+
+Usage
+=====
+
+There are several ways to configure and manage zram device(-s):
+
+a) using zram and zram_control sysfs attributes
+b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org).
+
+In this document we will describe only 'manual' zram configuration steps,
+IOW, zram and zram_control sysfs attributes.
+
+In order to get a better idea about zramctl please consult util-linux
+documentation, zramctl man-page or `zramctl --help`. Please be informed
+that zram maintainers do not develop/maintain util-linux or zramctl, should
+you have any questions please contact util-linux@vger.kernel.org
+
+Following shows a typical sequence of steps for using zram.
+
+WARNING
+=======
+
+For the sake of simplicity we skip error checking parts in most of the
+examples below. However, it is your sole responsibility to handle errors.
+
+zram sysfs attributes always return negative values in case of errors.
+The list of possible return codes:
+
+======== =============================================================
+-EBUSY an attempt to modify an attribute that cannot be changed once
+ the device has been initialised. Please reset device first.
+-ENOMEM zram was not able to allocate enough memory to fulfil your
+ needs.
+-EINVAL invalid input has been provided.
+-EAGAIN re-try operation later (e.g. when attempting to run recompress
+ and writeback simultaneously).
+======== =============================================================
+
+If you use 'echo', the returned value is set by the 'echo' utility,
+and, in general case, something like::
+
+ echo foo > /sys/block/zram0/comp_algorithm
+ if [ $? -ne 0 ]; then
+ handle_error
+ fi
+
+should suffice.
+
+1) Load Module
+==============
+
+::
+
+ modprobe zram num_devices=4
+
+This creates 4 devices: /dev/zram{0,1,2,3}
+
+num_devices parameter is optional and tells zram how many devices should be
+pre-created. Default: 1.
+
+2) Select compression algorithm
+===============================
+
+Using comp_algorithm device attribute one can see available and
+currently selected (shown in square brackets) compression algorithms,
+or change the selected compression algorithm (once the device is initialised
+there is no way to change compression algorithm).
+
+Examples::
+
+ #show supported compression algorithms
+ cat /sys/block/zram0/comp_algorithm
+ lzo [lz4]
+
+ #select lzo compression algorithm
+ echo lzo > /sys/block/zram0/comp_algorithm
+
+For the time being, the `comp_algorithm` content shows only compression
+algorithms that are supported by zram.
+
+3) Set compression algorithm parameters: Optional
+=================================================
+
+Compression algorithms may support specific parameters which can be
+tweaked for particular dataset. ZRAM has an `algorithm_params` device
+attribute which provides a per-algorithm params configuration.
+
+For example, several compression algorithms support `level` parameter.
+In addition, certain compression algorithms support pre-trained dictionaries,
+which significantly change algorithms' characteristics. In order to configure
+compression algorithm to use external pre-trained dictionary, pass full
+path to the `dict` along with other parameters::
+
+ #pass path to pre-trained zstd dictionary
+ echo "algo=zstd dict=/etc/dictionary" > /sys/block/zram0/algorithm_params
+
+ #same, but using algorithm priority
+ echo "priority=1 dict=/etc/dictionary" > \
+ /sys/block/zram0/algorithm_params
+
+ #pass path to pre-trained zstd dictionary and compression level
+ echo "algo=zstd level=8 dict=/etc/dictionary" > \
+ /sys/block/zram0/algorithm_params
+
+Parameters are algorithm specific: not all algorithms support pre-trained
+dictionaries, not all algorithms support `level`. Furthermore, for certain
+algorithms `level` controls the compression level (the higher the value the
+better the compression ratio, it even can take negatives values for some
+algorithms), for other algorithms `level` is acceleration level (the higher
+the value the lower the compression ratio).
+
+4) Set Disksize
+===============
+
+Set disk size by writing the value to sysfs node 'disksize'.
+The value can be either in bytes or you can use mem suffixes.
+Examples::
+
+ # Initialize /dev/zram0 with 50MB disksize
+ echo $((50*1024*1024)) > /sys/block/zram0/disksize
+
+ # Using mem suffixes
+ echo 256K > /sys/block/zram0/disksize
+ echo 512M > /sys/block/zram0/disksize
+ echo 1G > /sys/block/zram0/disksize
+
+Note:
+There is little point creating a zram of greater than twice the size of memory
+since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the
+size of the disk when not in use so a huge zram is wasteful.
+
+5) Set memory limit: Optional
+=============================
+
+Set memory limit by writing the value to sysfs node 'mem_limit'.
+The value can be either in bytes or you can use mem suffixes.
+In addition, you could change the value in runtime.
+Examples::
+
+ # limit /dev/zram0 with 50MB memory
+ echo $((50*1024*1024)) > /sys/block/zram0/mem_limit
+
+ # Using mem suffixes
+ echo 256K > /sys/block/zram0/mem_limit
+ echo 512M > /sys/block/zram0/mem_limit
+ echo 1G > /sys/block/zram0/mem_limit
+
+ # To disable memory limit
+ echo 0 > /sys/block/zram0/mem_limit
+
+6) Activate
+===========
+
+::
+
+ mkswap /dev/zram0
+ swapon /dev/zram0
+
+ mkfs.ext4 /dev/zram1
+ mount /dev/zram1 /tmp
+
+7) Add/remove zram devices
+==========================
+
+zram provides a control interface, which enables dynamic (on-demand) device
+addition and removal.
+
+In order to add a new /dev/zramX device, perform a read operation on the hot_add
+attribute. This will return either the new device's device id (meaning that you
+can use /dev/zram<id>) or an error code.
+
+Example::
+
+ cat /sys/class/zram-control/hot_add
+ 1
+
+To remove the existing /dev/zramX device (where X is a device id)
+execute::
+
+ echo X > /sys/class/zram-control/hot_remove
+
+8) Stats
+========
+
+Per-device statistics are exported as various nodes under /sys/block/zram<id>/
+
+A brief description of exported device attributes follows. For more details
+please read Documentation/ABI/testing/sysfs-block-zram.
+
+====================== ====== ===============================================
+Name access description
+====================== ====== ===============================================
+disksize RW show and set the device's disk size
+initstate RO shows the initialization state of the device
+reset WO trigger device reset
+mem_used_max WO reset the `mem_used_max` counter (see later)
+mem_limit WO specifies the maximum amount of memory ZRAM can
+ use to store the compressed data
+writeback_limit WO specifies the maximum amount of write IO zram
+ can write out to backing device as 4KB unit
+writeback_limit_enable RW show and set writeback_limit feature
+comp_algorithm RW show and change the compression algorithm
+algorithm_params WO setup compression algorithm parameters
+compact WO trigger memory compaction
+debug_stat RO this file is used for zram debugging purposes
+backing_dev RW set up backend storage for zram to write out
+idle WO mark allocated slot as idle
+====================== ====== ===============================================
+
+
+User space is advised to use the following files to read the device statistics.
+
+File /sys/block/zram<id>/stat
+
+Represents block layer statistics. Read Documentation/block/stat.rst for
+details.
+
+File /sys/block/zram<id>/io_stat
+
+The stat file represents device's I/O statistics not accounted by block
+layer and, thus, not available in zram<id>/stat file. It consists of a
+single line of text and contains the following stats separated by
+whitespace:
+
+ ============= =============================================================
+ failed_reads The number of failed reads
+ failed_writes The number of failed writes
+ invalid_io The number of non-page-size-aligned I/O requests
+ notify_free Depending on device usage scenario it may account
+
+ a) the number of pages freed because of swap slot free
+ notifications
+ b) the number of pages freed because of
+ REQ_OP_DISCARD requests sent by bio. The former ones are
+ sent to a swap block device when a swap slot is freed,
+ which implies that this disk is being used as a swap disk.
+
+ The latter ones are sent by filesystem mounted with
+ discard option, whenever some data blocks are getting
+ discarded.
+ ============= =============================================================
+
+File /sys/block/zram<id>/mm_stat
+
+The mm_stat file represents the device's mm statistics. It consists of a single
+line of text and contains the following stats separated by whitespace:
+
+ ================ =============================================================
+ orig_data_size uncompressed size of data stored in this disk.
+ Unit: bytes
+ compr_data_size compressed size of data stored in this disk
+ mem_used_total the amount of memory allocated for this disk. This
+ includes allocator fragmentation and metadata overhead,
+ allocated for this disk. So, allocator space efficiency
+ can be calculated using compr_data_size and this statistic.
+ Unit: bytes
+ mem_limit the maximum amount of memory ZRAM can use to store
+ the compressed data
+ mem_used_max the maximum amount of memory zram has consumed to
+ store the data
+ same_pages the number of same element filled pages written to this disk.
+ No memory is allocated for such pages.
+ pages_compacted the number of pages freed during compaction
+ huge_pages the number of incompressible pages
+ huge_pages_since the number of incompressible pages since zram set up
+ ================ =============================================================
+
+File /sys/block/zram<id>/bd_stat
+
+The bd_stat file represents a device's backing device statistics. It consists of
+a single line of text and contains the following stats separated by whitespace:
+
+ ============== =============================================================
+ bd_count size of data written in backing device.
+ Unit: 4K bytes
+ bd_reads the number of reads from backing device
+ Unit: 4K bytes
+ bd_writes the number of writes to backing device
+ Unit: 4K bytes
+ ============== =============================================================
+
+9) Deactivate
+==============
+
+::
+
+ swapoff /dev/zram0
+ umount /dev/zram1
+
+10) Reset
+=========
+
+ Write any positive value to 'reset' sysfs node::
+
+ echo 1 > /sys/block/zram0/reset
+ echo 1 > /sys/block/zram1/reset
+
+ This frees all the memory allocated for the given device and
+ resets the disksize to zero. You must set the disksize again
+ before reusing the device.
+
+Optional Feature
+================
+
+IDLE pages tracking
+-------------------
+
+zram has built-in support for idle pages tracking (that is, allocated but
+not used pages). This feature is useful for e.g. zram writeback and
+recompression. In order to mark pages as idle, execute the following command::
+
+ echo all > /sys/block/zramX/idle
+
+This will mark all allocated zram pages as idle. The idle mark will be
+removed only when the page (block) is accessed (e.g. overwritten or freed).
+Additionally, when CONFIG_ZRAM_TRACK_ENTRY_ACTIME is enabled, pages can be
+marked as idle based on how many seconds have passed since the last access to
+a particular zram page::
+
+ echo 86400 > /sys/block/zramX/idle
+
+In this example, all pages which haven't been accessed in more than 86400
+seconds (one day) will be marked idle.
+
+writeback
+---------
+
+With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page
+to backing storage rather than keeping it in memory.
+To use the feature, admin should set up backing device via::
+
+ echo /dev/sda5 > /sys/block/zramX/backing_dev
+
+before disksize setting. It supports only partitions at this moment.
+If admin wants to use incompressible page writeback, they could do it via::
+
+ echo huge > /sys/block/zramX/writeback
+
+Admin can request writeback of idle pages at right timing via::
+
+ echo idle > /sys/block/zramX/writeback
+
+With the command, zram will writeback idle pages from memory to the storage.
+
+Additionally, if a user choose to writeback only huge and idle pages
+this can be accomplished with::
+
+ echo huge_idle > /sys/block/zramX/writeback
+
+If a user chooses to writeback only incompressible pages (pages that none of
+algorithms can compress) this can be accomplished with::
+
+ echo incompressible > /sys/block/zramX/writeback
+
+If an admin wants to write a specific page in zram device to the backing device,
+they could write a page index into the interface::
+
+ echo "page_index=1251" > /sys/block/zramX/writeback
+
+In Linux 6.16 this interface underwent some rework. First, the interface
+now supports `key=value` format for all of its parameters (`type=huge_idle`,
+etc.) Second, the support for `page_indexes` was introduced, which specify
+`LOW-HIGH` range (or ranges) of pages to be written-back. This reduces the
+number of syscalls, but more importantly this enables optimal post-processing
+target selection strategy. Usage example::
+
+ echo "type=idle" > /sys/block/zramX/writeback
+ echo "page_indexes=1-100 page_indexes=200-300" > \
+ /sys/block/zramX/writeback
+
+We also now permit multiple page_index params per call and a mix of
+single pages and page ranges::
+
+ echo page_index=42 page_index=99 page_indexes=100-200 \
+ page_indexes=500-700 > /sys/block/zramX/writeback
+
+If there are lots of write IO with flash device, potentially, it has
+flash wearout problem so that admin needs to design write limitation
+to guarantee storage health for entire product life.
+
+To overcome the concern, zram supports "writeback_limit" feature.
+The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
+any writeback. IOW, if admin wants to apply writeback budget, they should
+enable writeback_limit_enable via::
+
+ $ echo 1 > /sys/block/zramX/writeback_limit_enable
+
+Once writeback_limit_enable is set, zram doesn't allow any writeback
+until admin sets the budget via /sys/block/zramX/writeback_limit.
+
+(If admin doesn't enable writeback_limit_enable, writeback_limit's value
+assigned via /sys/block/zramX/writeback_limit is meaningless.)
+
+If admin wants to limit writeback as per-day 400M, they could do it
+like below::
+
+ $ MB_SHIFT=20
+ $ 4K_SHIFT=12
+ $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
+ /sys/block/zram0/writeback_limit.
+ $ echo 1 > /sys/block/zram0/writeback_limit_enable
+
+If admins want to allow further write again once the budget is exhausted,
+they could do it like below::
+
+ $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
+ /sys/block/zram0/writeback_limit
+
+If an admin wants to see the remaining writeback budget since last set::
+
+ $ cat /sys/block/zramX/writeback_limit
+
+If an admin wants to disable writeback limit, they could do::
+
+ $ echo 0 > /sys/block/zramX/writeback_limit_enable
+
+The writeback_limit count will reset whenever you reset zram (e.g.,
+system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
+writeback happened until you reset the zram to allocate extra writeback
+budget in next setting is user's job.
+
+If admin wants to measure writeback count in a certain period, they could
+know it via /sys/block/zram0/bd_stat's 3rd column.
+
+recompression
+-------------
+
+With CONFIG_ZRAM_MULTI_COMP, zram can recompress pages using alternative
+(secondary) compression algorithms. The basic idea is that alternative
+compression algorithm can provide better compression ratio at a price of
+(potentially) slower compression/decompression speeds. Alternative compression
+algorithm can, for example, be more successful compressing huge pages (those
+that default algorithm failed to compress). Another application is idle pages
+recompression - pages that are cold and sit in the memory can be recompressed
+using more effective algorithm and, hence, reduce zsmalloc memory usage.
+
+With CONFIG_ZRAM_MULTI_COMP, zram supports up to 4 compression algorithms:
+one primary and up to 3 secondary ones. Primary zram compressor is explained
+in "3) Select compression algorithm", secondary algorithms are configured
+using recomp_algorithm device attribute.
+
+Example:::
+
+ #show supported recompression algorithms
+ cat /sys/block/zramX/recomp_algorithm
+ #1: lzo lzo-rle lz4 lz4hc [zstd]
+ #2: lzo lzo-rle lz4 [lz4hc] zstd
+
+Alternative compression algorithms are sorted by priority. In the example
+above, zstd is used as the first alternative algorithm, which has priority
+of 1, while lz4hc is configured as a compression algorithm with priority 2.
+Alternative compression algorithm's priority is provided during algorithms
+configuration:::
+
+ #select zstd recompression algorithm, priority 1
+ echo "algo=zstd priority=1" > /sys/block/zramX/recomp_algorithm
+
+ #select deflate recompression algorithm, priority 2
+ echo "algo=deflate priority=2" > /sys/block/zramX/recomp_algorithm
+
+Another device attribute that CONFIG_ZRAM_MULTI_COMP enables is recompress,
+which controls recompression.
+
+Examples:::
+
+ #IDLE pages recompression is activated by `idle` mode
+ echo "type=idle" > /sys/block/zramX/recompress
+
+ #HUGE pages recompression is activated by `huge` mode
+ echo "type=huge" > /sys/block/zram0/recompress
+
+ #HUGE_IDLE pages recompression is activated by `huge_idle` mode
+ echo "type=huge_idle" > /sys/block/zramX/recompress
+
+The number of idle pages can be significant, so user-space can pass a size
+threshold (in bytes) to the recompress knob: zram will recompress only pages
+of equal or greater size:::
+
+ #recompress all pages larger than 3000 bytes
+ echo "threshold=3000" > /sys/block/zramX/recompress
+
+ #recompress idle pages larger than 2000 bytes
+ echo "type=idle threshold=2000" > /sys/block/zramX/recompress
+
+It is also possible to limit the number of pages zram re-compression will
+attempt to recompress:::
+
+ echo "type=huge_idle max_pages=42" > /sys/block/zramX/recompress
+
+During re-compression for every page, that matches re-compression criteria,
+ZRAM iterates the list of registered alternative compression algorithms in
+order of their priorities. ZRAM stops either when re-compression was
+successful (re-compressed object is smaller in size than the original one)
+and matches re-compression criteria (e.g. size threshold) or when there are
+no secondary algorithms left to try. If none of the secondary algorithms can
+successfully re-compressed the page such a page is marked as incompressible,
+so ZRAM will not attempt to re-compress it in the future.
+
+This re-compression behaviour, when it iterates through the list of
+registered compression algorithms, increases our chances of finding the
+algorithm that successfully compresses a particular page. Sometimes, however,
+it is convenient (and sometimes even necessary) to limit recompression to
+only one particular algorithm so that it will not try any other algorithms.
+This can be achieved by providing a `algo` or `priority` parameter:::
+
+ #use zstd algorithm only (if registered)
+ echo "type=huge algo=zstd" > /sys/block/zramX/recompress
+
+ #use zstd algorithm only (if zstd was registered under priority 1)
+ echo "type=huge priority=1" > /sys/block/zramX/recompress
+
+memory tracking
+===============
+
+With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the
+zram block. It could be useful to catch cold or incompressible
+pages of the process with*pagemap.
+
+If you enable the feature, you could see block state via
+/sys/kernel/debug/zram/zram0/block_state". The output is as follows::
+
+ 300 75.033841 .wh...
+ 301 63.806904 s.....
+ 302 63.806919 ..hi..
+ 303 62.801919 ....r.
+ 304 146.781902 ..hi.n
+
+First column
+ zram's block index.
+Second column
+ access time since the system was booted
+Third column
+ state of the block:
+
+ s:
+ same page
+ w:
+ written page to backing store
+ h:
+ huge page
+ i:
+ idle page
+ r:
+ recompressed page (secondary compression algorithm)
+ n:
+ none (including secondary) of algorithms could compress it
+
+First line of above example says 300th block is accessed at 75.033841sec
+and the block's state is huge so it is written back to the backing
+storage. It's a debugging feature so anyone shouldn't rely on it to work
+properly.
+
+Nitin Gupta
+ngupta@vflare.org
diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
new file mode 100644
index 000000000000..7a86042c9b6d
--- /dev/null
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -0,0 +1,327 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _bootconfig:
+
+==================
+Boot Configuration
+==================
+
+:Author: Masami Hiramatsu <mhiramat@kernel.org>
+
+Overview
+========
+
+The boot configuration expands the current kernel command line to support
+additional key-value data when booting the kernel in an efficient way.
+This allows administrators to pass a structured-Key config file.
+
+Config File Syntax
+==================
+
+The boot config syntax is a simple structured key-value. Each key consists
+of dot-connected-words, and key and value are connected by ``=``. The value
+has to be terminated by semi-colon (``;``) or newline (``\n``).
+For array value, array entries are separated by comma (``,``). ::
+
+ KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
+
+Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
+
+Each key word must contain only alphabets, numbers, dash (``-``) or underscore
+(``_``). And each value only contains printable characters or spaces except
+for delimiters such as semi-colon (``;``), new-line (``\n``), comma (``,``),
+hash (``#``) and closing brace (``}``).
+
+If you want to use those delimiters in a value, you can use either double-
+quotes (``"VALUE"``) or single-quotes (``'VALUE'``) to quote it. Note that
+you can not escape these quotes.
+
+There can be a key which doesn't have value or has an empty value. Those keys
+are used for checking if the key exists or not (like a boolean).
+
+Key-Value Syntax
+----------------
+
+The boot config file syntax allows user to merge partially same word keys
+by brace. For example::
+
+ foo.bar.baz = value1
+ foo.bar.qux.quux = value2
+
+These can be written also in::
+
+ foo.bar {
+ baz = value1
+ qux.quux = value2
+ }
+
+Or more shorter, written as following::
+
+ foo.bar { baz = value1; qux.quux = value2 }
+
+In both styles, same key words are automatically merged when parsing it
+at boot time. So you can append similar trees or key-values.
+
+Same-key Values
+---------------
+
+It is prohibited that two or more values or arrays share a same-key.
+For example,::
+
+ foo = bar, baz
+ foo = qux # !ERROR! we can not re-define same key
+
+If you want to update the value, you must use the override operator
+``:=`` explicitly. For example::
+
+ foo = bar, baz
+ foo := qux
+
+then, the ``qux`` is assigned to ``foo`` key. This is useful for
+overriding the default value by adding (partial) custom bootconfigs
+without parsing the default bootconfig.
+
+If you want to append the value to existing key as an array member,
+you can use ``+=`` operator. For example::
+
+ foo = bar, baz
+ foo += qux
+
+In this case, the key ``foo`` has ``bar``, ``baz`` and ``qux``.
+
+Moreover, sub-keys and a value can coexist under a parent key.
+For example, following config is allowed.::
+
+ foo = value1
+ foo.bar = value2
+ foo := value3 # This will update foo's value.
+
+Note, since there is no syntax to put a raw value directly under a
+structured key, you have to define it outside of the brace. For example::
+
+ foo {
+ bar = value1
+ bar {
+ baz = value2
+ qux = value3
+ }
+ }
+
+Also, the order of the value node under a key is fixed. If there
+are a value and subkeys, the value is always the first child node
+of the key. Thus if user specifies subkeys first, e.g.::
+
+ foo.bar = value1
+ foo = value2
+
+In the program (and /proc/bootconfig), it will be shown as below::
+
+ foo = value2
+ foo.bar = value1
+
+Comments
+--------
+
+The config syntax accepts shell-script style comments. The comments starting
+with hash ("#") until newline ("\n") will be ignored.
+
+::
+
+ # comment line
+ foo = value # value is set to foo.
+ bar = 1, # 1st element
+ 2, # 2nd element
+ 3 # 3rd element
+
+This is parsed as below::
+
+ foo = value
+ bar = 1, 2, 3
+
+Note that you can not put a comment between value and delimiter(``,`` or
+``;``). This means following config has a syntax error ::
+
+ key = 1 # comment
+ ,2
+
+
+/proc/bootconfig
+================
+
+/proc/bootconfig is a user-space interface of the boot config.
+Unlike /proc/cmdline, this file shows the key-value style list.
+Each key-value pair is shown in each line with following style::
+
+ KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...]
+
+
+Boot Kernel With a Boot Config
+==============================
+
+There are two options to boot the kernel with bootconfig: attaching the
+bootconfig to the initrd image or embedding it in the kernel itself.
+
+Attaching a Boot Config to Initrd
+---------------------------------
+
+Since the boot configuration file is loaded with initrd by default,
+it will be added to the end of the initrd (initramfs) image file with
+padding, size, checksum and 12-byte magic word as below.
+
+[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n]
+
+The size and checksum fields are unsigned 32bit little endian value.
+
+When the boot configuration is added to the initrd image, the total
+file size is aligned to 4 bytes. To fill the gap, null characters
+(``\0``) will be added. Thus the ``size`` is the length of the bootconfig
+file + padding bytes.
+
+The Linux kernel decodes the last part of the initrd image in memory to
+get the boot configuration data.
+Because of this "piggyback" method, there is no need to change or
+update the boot loader and the kernel image itself as long as the boot
+loader passes the correct initrd file size. If by any chance, the boot
+loader passes a longer size, the kernel fails to find the bootconfig data.
+
+To do this operation, Linux kernel provides ``bootconfig`` command under
+tools/bootconfig, which allows admin to apply or delete the config file
+to/from initrd image. You can build it by the following command::
+
+ # make -C tools/bootconfig
+
+To add your boot config file to initrd image, run bootconfig as below
+(Old data is removed automatically if exists)::
+
+ # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
+
+To remove the config from the image, you can use -d option as below::
+
+ # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
+
+Then add "bootconfig" on the normal kernel command line to tell the
+kernel to look for the bootconfig at the end of the initrd file.
+Alternatively, build your kernel with the ``CONFIG_BOOT_CONFIG_FORCE``
+Kconfig option selected.
+
+Embedding a Boot Config into Kernel
+-----------------------------------
+
+If you can not use initrd, you can also embed the bootconfig file in the
+kernel by Kconfig options. In this case, you need to recompile the kernel
+with the following configs::
+
+ CONFIG_BOOT_CONFIG_EMBED=y
+ CONFIG_BOOT_CONFIG_EMBED_FILE="/PATH/TO/BOOTCONFIG/FILE"
+
+``CONFIG_BOOT_CONFIG_EMBED_FILE`` requires an absolute path or a relative
+path to the bootconfig file from source tree or object tree.
+The kernel will embed it as the default bootconfig.
+
+Just as when attaching the bootconfig to the initrd, you need ``bootconfig``
+option on the kernel command line to enable the embedded bootconfig, or,
+alternatively, build your kernel with the ``CONFIG_BOOT_CONFIG_FORCE``
+Kconfig option selected.
+
+Note that even if you set this option, you can override the embedded
+bootconfig by another bootconfig which attached to the initrd.
+
+Kernel parameters via Boot Config
+=================================
+
+In addition to the kernel command line, the boot config can be used for
+passing the kernel parameters. All the key-value pairs under ``kernel``
+key will be passed to kernel cmdline directly. Moreover, the key-value
+pairs under ``init`` will be passed to init process via the cmdline.
+The parameters are concatenated with user-given kernel cmdline string
+as the following order, so that the command line parameter can override
+bootconfig parameters (this depends on how the subsystem handles parameters
+but in general, earlier parameter will be overwritten by later one.)::
+
+ [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params]
+
+Here is an example of the bootconfig file for kernel/init parameters.::
+
+ kernel {
+ root = 01234567-89ab-cdef-0123-456789abcd
+ }
+ init {
+ splash
+ }
+
+This will be copied into the kernel cmdline string as the following::
+
+ root="01234567-89ab-cdef-0123-456789abcd" -- splash
+
+If user gives some other command line like,::
+
+ ro bootconfig -- quiet
+
+The final kernel cmdline will be the following::
+
+ root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet
+
+
+Config File Limitation
+======================
+
+Currently the maximum config size is 32KB and the total key-words (not
+key-value entries) must be under 1024 nodes.
+Note: this is not the number of entries but nodes, an entry must consume
+more than 2 nodes (a key-word and a value). So theoretically, it will be
+up to 512 key-value pairs. If keys contains 3 words in average, it can
+contain 256 key-value pairs. In most cases, the number of config items
+will be under 100 entries and smaller than 8KB, so it would be enough.
+If the node number exceeds 1024, parser returns an error even if the file
+size is smaller than 32KB. (Note that this maximum size is not including
+the padding null characters.)
+Anyway, since bootconfig command verifies it when appending a boot config
+to initrd image, user can notice it before boot.
+
+
+Bootconfig APIs
+===============
+
+User can query or loop on key-value pairs, also it is possible to find
+a root (prefix) key node and find key-values under that node.
+
+If you have a key string, you can query the value directly with the key
+using xbc_find_value(). If you want to know what keys exist in the boot
+config, you can use xbc_for_each_key_value() to iterate key-value pairs.
+Note that you need to use xbc_array_for_each_value() for accessing
+each array's value, e.g.::
+
+ vnode = NULL;
+ xbc_find_value("key.word", &vnode);
+ if (vnode && xbc_node_is_array(vnode))
+ xbc_array_for_each_value(vnode, value) {
+ printk("%s ", value);
+ }
+
+If you want to focus on keys which have a prefix string, you can use
+xbc_find_node() to find a node by the prefix string, and iterate
+keys under the prefix node with xbc_node_for_each_key_value().
+
+But the most typical usage is to get the named value under prefix
+or get the named array under prefix as below::
+
+ root = xbc_find_node("key.prefix");
+ value = xbc_node_find_value(root, "option", &vnode);
+ ...
+ xbc_node_for_each_array_value(root, "array-option", value, anode) {
+ ...
+ }
+
+This accesses a value of "key.prefix.option" and an array of
+"key.prefix.array-option".
+
+Locking is not needed, since after initialization, the config becomes
+read-only. All data and keys must be copied if you need to modify it.
+
+
+Functions and structures
+========================
+
+.. kernel-doc:: include/linux/bootconfig.h
+.. kernel-doc:: lib/bootconfig.c
+
diff --git a/Documentation/admin-guide/braille-console.rst b/Documentation/admin-guide/braille-console.rst
new file mode 100644
index 000000000000..153472e93cae
--- /dev/null
+++ b/Documentation/admin-guide/braille-console.rst
@@ -0,0 +1,38 @@
+Linux Braille Console
+=====================
+
+To get early boot messages on a braille device (before userspace screen
+readers can start), you first need to compile the support for the usual serial
+console (see :ref:`Documentation/admin-guide/serial-console.rst <serial_console>`), and
+for braille device
+(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`).
+
+Then you need to specify a ``console=brl``, option on the kernel command line, the
+format is::
+
+ console=brl,serial_options...
+
+where ``serial_options...`` are the same as described in
+:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`.
+
+So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to
+override the baud rate to 115200, etc.
+
+By default, the braille device will just show the last kernel message (console
+mode). To review previous messages, press the Insert key to switch to the VT
+review mode. In review mode, the arrow keys permit to browse in the VT content,
+`PAGE-UP`/`PAGE-DOWN` keys go at the top/bottom of the screen, and
+the `HOME` key goes back
+to the cursor, hence providing very basic screen reviewing facility.
+
+Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel
+parameter.
+
+For simplicity, only one braille console can be enabled, other uses of
+``console=brl,...`` will be discarded. Also note that it does not interfere with
+the console selection mechanism described in
+:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`.
+
+For now, only the VisioBraille device is supported.
+
+Samuel Thibault <samuel.thibault@ens-lyon.org>
diff --git a/Documentation/admin-guide/btmrvl.rst b/Documentation/admin-guide/btmrvl.rst
new file mode 100644
index 000000000000..ec57740ead0c
--- /dev/null
+++ b/Documentation/admin-guide/btmrvl.rst
@@ -0,0 +1,124 @@
+=============
+btmrvl driver
+=============
+
+All commands are used via debugfs interface.
+
+Set/get driver configurations
+=============================
+
+Path: /debug/btmrvl/config/
+
+gpiogap=[n], hscfgcmd
+ These commands are used to configure the host sleep parameters::
+ bit 8:0 -- Gap
+ bit 16:8 -- GPIO
+
+ where GPIO is the pin number of GPIO used to wake up the host.
+ It could be any valid GPIO pin# (e.g. 0-7) or 0xff (SDIO interface
+ wakeup will be used instead).
+
+ where Gap is the gap in milli seconds between wakeup signal and
+ wakeup event, or 0xff for special host sleep setting.
+
+ Usage::
+
+ # Use SDIO interface to wake up the host and set GAP to 0x80:
+ echo 0xff80 > /debug/btmrvl/config/gpiogap
+ echo 1 > /debug/btmrvl/config/hscfgcmd
+
+ # Use GPIO pin #3 to wake up the host and set GAP to 0xff:
+ echo 0x03ff > /debug/btmrvl/config/gpiogap
+ echo 1 > /debug/btmrvl/config/hscfgcmd
+
+psmode=[n], pscmd
+ These commands are used to enable/disable auto sleep mode
+
+ where the option is::
+
+ 1 -- Enable auto sleep mode
+ 0 -- Disable auto sleep mode
+
+ Usage::
+
+ # Enable auto sleep mode
+ echo 1 > /debug/btmrvl/config/psmode
+ echo 1 > /debug/btmrvl/config/pscmd
+
+ # Disable auto sleep mode
+ echo 0 > /debug/btmrvl/config/psmode
+ echo 1 > /debug/btmrvl/config/pscmd
+
+
+hsmode=[n], hscmd
+ These commands are used to enable host sleep or wake up firmware
+
+ where the option is::
+
+ 1 -- Enable host sleep
+ 0 -- Wake up firmware
+
+ Usage::
+
+ # Enable host sleep
+ echo 1 > /debug/btmrvl/config/hsmode
+ echo 1 > /debug/btmrvl/config/hscmd
+
+ # Wake up firmware
+ echo 0 > /debug/btmrvl/config/hsmode
+ echo 1 > /debug/btmrvl/config/hscmd
+
+
+Get driver status
+=================
+
+Path: /debug/btmrvl/status/
+
+Usage::
+
+ cat /debug/btmrvl/status/<args>
+
+where the args are:
+
+curpsmode
+ This command displays current auto sleep status.
+
+psstate
+ This command display the power save state.
+
+hsstate
+ This command display the host sleep state.
+
+txdnldrdy
+ This command displays the value of Tx download ready flag.
+
+Issuing a raw hci command
+=========================
+
+Use hcitool to issue raw hci command, refer to hcitool manual
+
+Usage::
+
+ Hcitool cmd <ogf> <ocf> [Parameters]
+
+Interface Control Command::
+
+ hcitool cmd 0x3f 0x5b 0xf5 0x01 0x00 --Enable All interface
+ hcitool cmd 0x3f 0x5b 0xf5 0x01 0x01 --Enable Wlan interface
+ hcitool cmd 0x3f 0x5b 0xf5 0x01 0x02 --Enable BT interface
+ hcitool cmd 0x3f 0x5b 0xf5 0x00 0x00 --Disable All interface
+ hcitool cmd 0x3f 0x5b 0xf5 0x00 0x01 --Disable Wlan interface
+ hcitool cmd 0x3f 0x5b 0xf5 0x00 0x02 --Disable BT interface
+
+SD8688 firmware
+===============
+
+Images:
+
+- /lib/firmware/sd8688_helper.bin
+- /lib/firmware/sd8688.bin
+
+
+The images can be downloaded from:
+
+git.infradead.org/users/dwmw2/linux-firmware.git/libertas/
diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
new file mode 100644
index 000000000000..f4f867cabb17
--- /dev/null
+++ b/Documentation/admin-guide/bug-bisect.rst
@@ -0,0 +1,165 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
+.. [see the bottom of this file for redistribution information]
+
+======================
+Bisecting a regression
+======================
+
+This document describes how to use a ``git bisect`` to find the source code
+change that broke something -- for example when some functionality stopped
+working after upgrading from Linux 6.0 to 6.1.
+
+The text focuses on the gist of the process. If you are new to bisecting the
+kernel, better follow Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
+instead: it depicts everything from start to finish while covering multiple
+aspects even kernel developers occasionally forget. This includes detecting
+situations early where a bisection would be a waste of time, as nobody would
+care about the result -- for example, because the problem happens after the
+kernel marked itself as 'tainted', occurs in an abandoned version, was already
+fixed, or is caused by a .config change you or your Linux distributor performed.
+
+Finding the change causing a kernel issue using a bisection
+===========================================================
+
+*Note: the following process assumes you prepared everything for a bisection.
+This includes having a Git clone with the appropriate sources, installing the
+software required to build and install kernels, as well as a .config file stored
+in a safe place (the following example assumes '~/prepared_kernel_.config') to
+use as pristine base at each bisection step; ideally, you have also worked out
+a fully reliable and straight-forward way to reproduce the regression, too.*
+
+* Preparation: start the bisection and tell Git about the points in the history
+ you consider to be working and broken, which Git calls 'good' and 'bad'::
+
+ git bisect start
+ git bisect good v6.0
+ git bisect bad v6.1
+
+ Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.
+
+1. Copy your prepared .config into the build directory and adjust it to the
+ needs of the codebase Git checked out for testing::
+
+ cp ~/prepared_kernel_.config .config
+ make olddefconfig
+
+2. Now build, install, and boot a kernel. This might fail for unrelated reasons,
+ for example, when a compile error happens at the current stage of the
+ bisection a later change resolves. In such cases run ``git bisect skip`` and
+ go back to step 1.
+
+3. Check if the functionality that regressed works in the kernel you just built.
+
+ If it works, execute::
+
+ git bisect good
+
+ If it is broken, run::
+
+ git bisect bad
+
+ Note, getting this wrong just once will send the rest of the bisection
+ totally off course. To prevent having to start anew later you thus want to
+ ensure what you tell Git is correct; it is thus often wise to spend a few
+ minutes more on testing in case your reproducer is unreliable.
+
+ After issuing one of these two commands, Git will usually check out another
+ bisection point and print something like 'Bisecting: 675 revisions left to
+ test after this (roughly 10 steps)'. In that case go back to step 1.
+
+ If Git instead prints something like 'cafecaca0c0dacafecaca0c0dacafecaca0c0da
+ is the first bad commit', then you have finished the bisection. In that case
+ move to the next point below. Note, right after displaying that line Git will
+ show some details about the culprit including its patch description; this can
+ easily fill your terminal, so you might need to scroll up to see the message
+ mentioning the culprit's commit-id.
+
+ In case you missed Git's output, you can always run ``git bisect log`` to
+ print the status: it will show how many steps remain or mention the result of
+ the bisection.
+
+* Recommended complementary task: put the bisection log and the current .config
+ file aside for the bug report; furthermore tell Git to reset the sources to
+ the state before the bisection::
+
+ git bisect log > ~/bisection-log
+ cp .config ~/bisection-config-culprit
+ git bisect reset
+
+* Recommended optional task: try reverting the culprit on top of the latest
+ codebase and check if that fixes your bug; if that is the case, it validates
+ the bisection and enables developers to resolve the regression through a
+ revert.
+
+ To try this, update your clone and check out latest mainline. Then tell Git
+ to revert the change by specifying its commit-id::
+
+ git revert --no-edit cafec0cacaca0
+
+ Git might reject this, for example when the bisection landed on a merge
+ commit. In that case, abandon the attempt. Do the same, if Git fails to revert
+ the culprit on its own because later changes depend on it -- at least unless
+ you bisected a stable or longterm kernel series, in which case you want to
+ check out its latest codebase and try a revert there.
+
+ If a revert succeeds, build and test another kernel to check if reverting
+ resolved your regression.
+
+With that the process is complete. Now report the regression as described by
+Documentation/admin-guide/reporting-issues.rst.
+
+Bisecting linux-next
+--------------------
+
+If you face a problem only happening in linux-next, bisect between the
+linux-next branches 'stable' and 'master'. The following commands will start
+the process for a linux-next tree you added as a remote called 'next'::
+
+ git bisect start
+ git bisect good next/stable
+ git bisect bad next/master
+
+The 'stable' branch refers to the state of linux-mainline that the current
+linux-next release (found in the 'master' branch) is based on -- the former
+thus should be free of any problems that show up in -next, but not in Linus'
+tree.
+
+This will bisect across a wide range of changes, some of which you might have
+used in earlier linux-next releases without problems. Sadly there is no simple
+way to avoid checking them: bisecting from one linux-next release to a later
+one (say between 'next-20241020' and 'next-20241021') is impossible, as they
+share no common history.
+
+Additional reading material
+---------------------------
+
+* The `man page for 'git bisect' <https://git-scm.com/docs/git-bisect>`_ and
+ `fighting regressions with 'git bisect' <https://git-scm.com/docs/git-bisect-lk2009.html>`_
+ in the Git documentation.
+* `Working with git bisect <https://nathanchance.dev/posts/working-with-git-bisect/>`_
+ from kernel developer Nathan Chancellor.
+* `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_.
+* `Fully automated bisecting with 'git bisect run' <https://lwn.net/Articles/317154>`_.
+
+..
+ end-of-content
+..
+ This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If
+ you spot a typo or small mistake, feel free to let him know directly and
+ he'll fix it. You are free to do the same in a mostly informal way if you
+ want to contribute changes to the text -- but for copyright reasons please CC
+ linux-doc@vger.kernel.org and 'sign-off' your contribution as
+ Documentation/process/submitting-patches.rst explains in the section 'Sign
+ your work - the Developer's Certificate of Origin'.
+..
+ This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
+ of the file. If you want to distribute this text under CC-BY-4.0 only,
+ please use 'The Linux kernel development community' for author attribution
+ and link this as source:
+ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/bug-bisect.rst
+
+..
+ Note: Only the content of this RST file as found in the Linux kernel sources
+ is available under CC-BY-4.0, as versions of this text that were processed
+ (for example by the kernel's build system) might contain content taken from
+ files which use a more restrictive license.
diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
new file mode 100644
index 000000000000..7da0504388ec
--- /dev/null
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -0,0 +1,370 @@
+Bug hunting
+===========
+
+Kernel bug reports often come with a stack dump like the one below::
+
+ ------------[ cut here ]------------
+ WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70
+ Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core]
+ CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1
+ Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009
+ 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6
+ c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10
+ f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617
+ Call Trace:
+ [<c12ba080>] ? dump_stack+0x44/0x64
+ [<c103ed6a>] ? __warn+0xfa/0x120
+ [<c109e8a7>] ? module_put+0x57/0x70
+ [<c109e8a7>] ? module_put+0x57/0x70
+ [<c103ee33>] ? warn_slowpath_null+0x23/0x30
+ [<c109e8a7>] ? module_put+0x57/0x70
+ [<f80ca4d0>] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk]
+ [<c109f617>] ? symbol_put_addr+0x27/0x50
+ [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb]
+ [<f80bb3bf>] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb]
+ [<c13d03bc>] ? usb_disable_endpoint+0x7c/0xb0
+ [<f80bb48a>] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb]
+ [<c13d2882>] ? usb_unbind_interface+0x62/0x250
+ [<c136b514>] ? __pm_runtime_idle+0x44/0x70
+ [<c13620d8>] ? __device_release_driver+0x78/0x120
+ [<c1362907>] ? driver_detach+0x87/0x90
+ [<c1361c48>] ? bus_remove_driver+0x38/0x90
+ [<c13d1c18>] ? usb_deregister+0x58/0xb0
+ [<c109fbb0>] ? SyS_delete_module+0x130/0x1f0
+ [<c1055654>] ? task_work_run+0x64/0x80
+ [<c1000fa5>] ? exit_to_usermode_loop+0x85/0x90
+ [<c10013f0>] ? do_fast_syscall_32+0x80/0x130
+ [<c1549f43>] ? sysenter_past_esp+0x40/0x6a
+ ---[ end trace 6ebc60ef3981792f ]---
+
+Such stack traces provide enough information to identify the line inside the
+Kernel's source code where the bug happened. Depending on the severity of
+the issue, it may also contain the word **Oops**, as on this one::
+
+ BUG: unable to handle kernel NULL pointer dereference at (null)
+ IP: [<c06969d4>] iret_exc+0x7d0/0xa59
+ *pdpt = 000000002258a001 *pde = 0000000000000000
+ Oops: 0002 [#1] PREEMPT SMP
+ ...
+
+Despite being an **Oops** or some other sort of stack trace, the offended
+line is usually required to identify and handle the bug. Along this chapter,
+we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.
+
+If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
+quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
+
+Modules linked in
+-----------------
+
+Modules that are tainted or are being loaded or unloaded are marked with
+"(...)", where the taint flags are described in
+file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
+annotated with "+", and "being unloaded" is annotated with "-".
+
+
+Where is the Oops message is located?
+-------------------------------------
+
+Normally the Oops text is read from the kernel buffers by klogd and
+handed to ``syslogd`` which writes it to a syslog file, typically
+``/var/log/messages`` (depends on ``/etc/syslog.conf``). On systems with
+systemd, it may also be stored by the ``journald`` daemon, and accessed
+by running ``journalctl`` command.
+
+Sometimes ``klogd`` dies, in which case you can run ``dmesg > file`` to
+read the data from the kernel buffers and save it. Or you can
+``cat /proc/kmsg > file``, however you have to break in to stop the transfer,
+since ``kmsg`` is a "never ending file".
+
+If the machine has crashed so badly that you cannot enter commands or
+the disk is not available then you have three options:
+
+(1) Hand copy the text from the screen and type it in after the machine
+ has restarted. Messy but it is the only option if you have not
+ planned for a crash. Alternatively, you can take a picture of
+ the screen with a digital camera - not nice, but better than
+ nothing. If the messages scroll off the top of the console, you
+ may find that booting with a higher resolution (e.g., ``vga=791``)
+ will allow you to read more of the text. (Caveat: This needs ``vesafb``,
+ so won't help for 'early' oopses.)
+
+(2) Boot with a serial console (see
+ :ref:`Documentation/admin-guide/serial-console.rst <serial_console>`),
+ run a null modem to a second machine and capture the output there
+ using your favourite communication program. Minicom works well.
+
+(3) Use Kdump (see Documentation/admin-guide/kdump/kdump.rst),
+ extract the kernel ring buffer from old memory with using dmesg
+ gdbmacro in Documentation/admin-guide/kdump/gdbmacros.txt.
+
+Finding the bug's location
+--------------------------
+
+Reporting a bug works best if you point the location of the bug at the
+Kernel source file. There are two methods for doing that. Usually, using
+``gdb`` is easier, but the Kernel should be pre-compiled with debug info.
+
+gdb
+^^^
+
+The GNU debugger (``gdb``) is the best way to figure out the exact file and line
+number of the OOPS from the ``vmlinux`` file.
+
+The usage of gdb works best on a kernel compiled with ``CONFIG_DEBUG_INFO``.
+This can be set by running::
+
+ $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO
+
+On a kernel compiled with ``CONFIG_DEBUG_INFO``, you can simply copy the
+EIP value from the OOPS::
+
+ EIP: 0060:[<c021e50e>] Not tainted VLI
+
+And use GDB to translate that to human-readable form::
+
+ $ gdb vmlinux
+ (gdb) l *0xc021e50e
+
+If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function
+offset from the OOPS::
+
+ EIP is at vt_ioctl+0xda8/0x1482
+
+And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled::
+
+ $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO
+ $ make vmlinux
+ $ gdb vmlinux
+ (gdb) l *vt_ioctl+0xda8
+ 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293).
+ 288 {
+ 289 struct vc_data *vc = NULL;
+ 290 int ret = 0;
+ 291
+ 292 console_lock();
+ 293 if (VT_BUSY(vc_num))
+ 294 ret = -EBUSY;
+ 295 else if (vc_num)
+ 296 vc = vc_deallocate(vc_num);
+ 297 console_unlock();
+
+or, if you want to be more verbose::
+
+ (gdb) p vt_ioctl
+ $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 <vt_ioctl>
+ (gdb) l *0xae0+0xda8
+
+You could, instead, use the object file::
+
+ $ make drivers/tty/
+ $ gdb drivers/tty/vt/vt_ioctl.o
+ (gdb) l *vt_ioctl+0xda8
+
+If you have a call trace, such as::
+
+ Call Trace:
+ [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
+ [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
+ [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
+ ...
+
+this shows the problem likely is in the :jbd: module. You can load that module
+in gdb and list the relevant code::
+
+ $ gdb fs/jbd/jbd.ko
+ (gdb) l *log_wait_commit+0xa3
+
+.. note::
+
+ You can also do the same for any function call at the stack trace,
+ like this one::
+
+ [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb]
+
+ The position where the above call happened can be seen with::
+
+ $ gdb drivers/media/usb/dvb-usb/dvb-usb.o
+ (gdb) l *dvb_usb_adapter_frontend_exit+0x3a
+
+objdump
+^^^^^^^
+
+To debug a kernel, use objdump and look for the hex offset from the crash
+output to find the valid line of code/assembler. Without debug symbols, you
+will see the assembler code for the routine shown, but if your kernel has
+debug symbols the C code will also be available. (Debug symbols can be enabled
+in the kernel hacking menu of the menu configuration.) For example::
+
+ $ objdump -r -S -l --disassemble net/ipv4/tcp.o
+
+.. note::
+
+ You need to be at the top level of the kernel tree for this to pick up
+ your C files.
+
+If you don't have access to the source code you can still debug some crash
+dumps using the following method (example crash dump output as shown by
+Dave Miller)::
+
+ EIP is at +0x14/0x4c0
+ ...
+ Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
+ 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
+ <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
+
+ Put the bytes into a "foo.s" file like this:
+
+ .text
+ .globl foo
+ foo:
+ .byte .... /* bytes from Code: part of OOPS dump */
+
+ Compile it with "gcc -c -o foo.o foo.s" then look at the output of
+ "objdump --disassemble foo.o".
+
+ Output:
+
+ ip_queue_xmit:
+ push %ebp
+ push %edi
+ push %esi
+ push %ebx
+ sub $0xbc, %esp
+ mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
+ mov 0x8(%ebp), %ebx ! %ebx = skb->sk
+ mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
+
+file:`scripts/decodecode` can be used to automate most of this, depending
+on what CPU architecture is being debugged.
+
+Reporting the bug
+-----------------
+
+Once you find where the bug happened, by inspecting its location,
+you could either try to fix it yourself or report it upstream.
+
+In order to report it upstream, you should identify the bug tracker, if any, or
+mailing list used for the development of the affected code. This can be done by
+using the ``get_maintainer.pl`` script.
+
+For example, if you find a bug at the gspca's sonixj.c file, you can get
+its maintainers with::
+
+ $ ./scripts/get_maintainer.pl --bug -f drivers/media/usb/gspca/sonixj.c
+ Hans Verkuil <hverkuil@kernel.org> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%)
+ Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%)
+ Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%)
+ Bhaktipriya Shridhar <bhaktipriya96@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%)
+ linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER)
+ linux-kernel@vger.kernel.org (open list)
+
+Please notice that it will point to:
+
+- The last developers that touched the source code (if this is done inside
+ a git tree). On the above example, Tejun and Bhaktipriya (in this
+ specific case, none really involved on the development of this file);
+- The driver maintainer (Hans Verkuil);
+- The subsystem maintainer (Mauro Carvalho Chehab);
+- The driver and/or subsystem mailing list (linux-media@vger.kernel.org);
+- The Linux Kernel mailing list (linux-kernel@vger.kernel.org);
+- The bug reporting URIs for the driver/subsystem (none in the above example).
+
+If the listing contains bug reporting URIs at the end, please prefer them over
+email. Otherwise, please report bugs to the mailing list used for the
+development of the code (linux-media ML) copying the driver maintainer (Hans).
+
+If you are totally stumped as to whom to send the report, and
+``get_maintainer.pl`` didn't provide you anything useful, send it to
+linux-kernel@vger.kernel.org.
+
+Thanks for your help in making Linux as stable as humanly possible.
+
+Fixing the bug
+--------------
+
+If you know programming, you could help us by not only reporting the bug,
+but also providing us with a solution. After all, open source is about
+sharing what you do and don't you want to be recognised for your genius?
+
+If you decide to take this way, once you have worked out a fix please submit
+it upstream.
+
+Please do read
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
+to help your code get accepted.
+
+
+---------------------------------------------------------------------------
+
+Notes on Oops tracing with ``klogd``
+------------------------------------
+
+In order to help Linus and the other kernel developers there has been
+substantial support incorporated into ``klogd`` for processing protection
+faults. In order to have full support for address resolution at least
+version 1.3-pl3 of the ``sysklogd`` package should be used.
+
+When a protection fault occurs the ``klogd`` daemon automatically
+translates important addresses in the kernel log messages to their
+symbolic equivalents. This translated kernel message is then
+forwarded through whatever reporting mechanism ``klogd`` is using. The
+protection fault message can be simply cut out of the message files
+and forwarded to the kernel developers.
+
+Two types of address resolution are performed by ``klogd``. The first is
+static translation and the second is dynamic translation.
+Static translation uses the System.map file.
+In order to do static translation the ``klogd`` daemon
+must be able to find a system map file at daemon initialization time.
+See the klogd man page for information on how ``klogd`` searches for map
+files.
+
+Dynamic address translation is important when kernel loadable modules
+are being used. Since memory for kernel modules is allocated from the
+kernel's dynamic memory pools there are no fixed locations for either
+the start of the module or for functions and symbols in the module.
+
+The kernel supports system calls which allow a program to determine
+which modules are loaded and their location in memory. Using these
+system calls the klogd daemon builds a symbol table which can be used
+to debug a protection fault which occurs in a loadable kernel module.
+
+At the very minimum klogd will provide the name of the module which
+generated the protection fault. There may be additional symbolic
+information available if the developer of the loadable module chose to
+export symbol information from the module.
+
+Since the kernel module environment can be dynamic there must be a
+mechanism for notifying the ``klogd`` daemon when a change in module
+environment occurs. There are command line options available which
+allow klogd to signal the currently executing daemon that symbol
+information should be refreshed. See the ``klogd`` manual page for more
+information.
+
+A patch is included with the sysklogd distribution which modifies the
+``modules-2.0.0`` package to automatically signal klogd whenever a module
+is loaded or unloaded. Applying this patch provides essentially
+seamless support for debugging protection faults which occur with
+kernel loadable modules.
+
+The following is an example of a protection fault in a loadable module
+processed by ``klogd``::
+
+ Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc
+ Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000
+ Aug 29 09:51:01 blizard kernel: *pde = 00000000
+ Aug 29 09:51:01 blizard kernel: Oops: 0002
+ Aug 29 09:51:01 blizard kernel: CPU: 0
+ Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868]
+ Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212
+ Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c
+ Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c
+ Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018
+ Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000)
+ Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001
+ Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00
+ Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036
+ Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128]
+ Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3
+
diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
new file mode 100644
index 000000000000..dabb80cdd25a
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
@@ -0,0 +1,301 @@
+===================
+Block IO Controller
+===================
+
+Overview
+========
+cgroup subsys "blkio" implements the block io controller. There seems to be
+a need of various kinds of IO control policies (like proportional BW, max BW)
+both at leaf nodes as well as at intermediate nodes in a storage hierarchy.
+Plan is to use the same cgroup based management interface for blkio controller
+and based on user options switch IO policies in the background.
+
+One IO control policy is throttling policy which can be used to
+specify upper IO rate limits on devices. This policy is implemented in
+generic block layer and can be used on leaf nodes as well as higher
+level logical devices like device mapper.
+
+HOWTO
+=====
+
+Throttling/Upper Limit policy
+-----------------------------
+Enable Block IO controller::
+
+ CONFIG_BLK_CGROUP=y
+
+Enable throttling in block layer::
+
+ CONFIG_BLK_DEV_THROTTLING=y
+
+Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::
+
+ mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
+
+Specify a bandwidth rate on particular device for root group. The format
+for policy is "<major>:<minor> <bytes_per_second>"::
+
+ echo "8:16 1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device
+
+This will put a limit of 1MB/second on reads happening for root group
+on device having major/minor number 8:16.
+
+Run dd to read a file and see if rate is throttled to 1MB/s or not::
+
+ # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024
+ 1024+0 records in
+ 1024+0 records out
+ 4194304 bytes (4.2 MB) copied, 4.0001 s, 1.0 MB/s
+
+Limits for writes can be put using blkio.throttle.write_bps_device file.
+
+Hierarchical Cgroups
+====================
+
+Throttling implements hierarchy support; however,
+throttling's hierarchy support is enabled iff "sane_behavior" is
+enabled from cgroup side, which currently is a development option and
+not publicly available.
+
+If somebody created a hierarchy like as follows::
+
+ root
+ / \
+ test1 test2
+ |
+ test3
+
+Throttling with "sane_behavior" will handle the
+hierarchy correctly. For throttling, all limits apply
+to the whole subtree while all statistics are local to the IOs
+directly generated by tasks in that cgroup.
+
+Throttling without "sane_behavior" enabled from cgroup side will
+practically treat all groups at same level as if it looks like the
+following::
+
+ pivot
+ / / \ \
+ root test1 test2 test3
+
+Various user visible config options
+===================================
+
+ CONFIG_BLK_CGROUP
+ Block IO controller.
+
+ CONFIG_BFQ_CGROUP_DEBUG
+ Debug help. Right now some additional stats file show up in cgroup
+ if this option is enabled.
+
+ CONFIG_BLK_DEV_THROTTLING
+ Enable block device throttling support in block layer.
+
+Details of cgroup files
+=======================
+
+Proportional weight policy files
+--------------------------------
+
+ blkio.bfq.weight
+ Specifies per cgroup weight. This is default weight of the group
+ on all the devices until and unless overridden by per device rule
+ (see `blkio.bfq.weight_device` below).
+
+ Currently allowed range of weights is from 1 to 1000. For more details,
+ see Documentation/block/bfq-iosched.rst.
+
+ blkio.bfq.weight_device
+ Specifies per cgroup per device weights, overriding the default group
+ weight. For more details, see Documentation/block/bfq-iosched.rst.
+
+ Following is the format::
+
+ # echo dev_maj:dev_minor weight > blkio.bfq.weight_device
+
+ Configure weight=300 on /dev/sdb (8:16) in this cgroup::
+
+ # echo 8:16 300 > blkio.bfq.weight_device
+ # cat blkio.bfq.weight_device
+ dev weight
+ 8:16 300
+
+ Configure weight=500 on /dev/sda (8:0) in this cgroup::
+
+ # echo 8:0 500 > blkio.bfq.weight_device
+ # cat blkio.bfq.weight_device
+ dev weight
+ 8:0 500
+ 8:16 300
+
+ Remove specific weight for /dev/sda in this cgroup::
+
+ # echo 8:0 0 > blkio.bfq.weight_device
+ # cat blkio.bfq.weight_device
+ dev weight
+ 8:16 300
+
+ blkio.time
+ Disk time allocated to cgroup per device in milliseconds. First
+ two fields specify the major and minor number of the device and
+ third field specifies the disk time allocated to group in
+ milliseconds.
+
+ blkio.sectors
+ Number of sectors transferred to/from disk by the group. First
+ two fields specify the major and minor number of the device and
+ third field specifies the number of sectors transferred by the
+ group to/from the device.
+
+ blkio.io_service_bytes
+ Number of bytes transferred to/from the disk by the group. These
+ are further divided by the type of operation - read or write, sync
+ or async. First two fields specify the major and minor number of the
+ device, third field specifies the operation type and the fourth field
+ specifies the number of bytes.
+
+ blkio.io_serviced
+ Number of IOs (bio) issued to the disk by the group. These
+ are further divided by the type of operation - read or write, sync
+ or async. First two fields specify the major and minor number of the
+ device, third field specifies the operation type and the fourth field
+ specifies the number of IOs.
+
+ blkio.io_service_time
+ Total amount of time between request dispatch and request completion
+ for the IOs done by this cgroup. This is in nanoseconds to make it
+ meaningful for flash devices too. For devices with queue depth of 1,
+ this time represents the actual service time. When queue_depth > 1,
+ that is no longer true as requests may be served out of order. This
+ may cause the service time for a given IO to include the service time
+ of multiple IOs when served out of order which may result in total
+ io_service_time > actual time elapsed. This time is further divided by
+ the type of operation - read or write, sync or async. First two fields
+ specify the major and minor number of the device, third field
+ specifies the operation type and the fourth field specifies the
+ io_service_time in ns.
+
+ blkio.io_wait_time
+ Total amount of time the IOs for this cgroup spent waiting in the
+ scheduler queues for service. This can be greater than the total time
+ elapsed since it is cumulative io_wait_time for all IOs. It is not a
+ measure of total time the cgroup spent waiting but rather a measure of
+ the wait_time for its individual IOs. For devices with queue_depth > 1
+ this metric does not include the time spent waiting for service once
+ the IO is dispatched to the device but till it actually gets serviced
+ (there might be a time lag here due to re-ordering of requests by the
+ device). This is in nanoseconds to make it meaningful for flash
+ devices too. This time is further divided by the type of operation -
+ read or write, sync or async. First two fields specify the major and
+ minor number of the device, third field specifies the operation type
+ and the fourth field specifies the io_wait_time in ns.
+
+ blkio.io_merged
+ Total number of bios/requests merged into requests belonging to this
+ cgroup. This is further divided by the type of operation - read or
+ write, sync or async.
+
+ blkio.io_queued
+ Total number of requests queued up at any given instant for this
+ cgroup. This is further divided by the type of operation - read or
+ write, sync or async.
+
+ blkio.avg_queue_size
+ Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
+ The average queue size for this cgroup over the entire time of this
+ cgroup's existence. Queue size samples are taken each time one of the
+ queues of this cgroup gets a timeslice.
+
+ blkio.group_wait_time
+ Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
+ This is the amount of time the cgroup had to wait since it became busy
+ (i.e., went from 0 to 1 request queued) to get a timeslice for one of
+ its queues. This is different from the io_wait_time which is the
+ cumulative total of the amount of time spent by each IO in that cgroup
+ waiting in the scheduler queue. This is in nanoseconds. If this is
+ read when the cgroup is in a waiting (for timeslice) state, the stat
+ will only report the group_wait_time accumulated till the last time it
+ got a timeslice and will not include the current delta.
+
+ blkio.empty_time
+ Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
+ This is the amount of time a cgroup spends without any pending
+ requests when not being served, i.e., it does not include any time
+ spent idling for one of the queues of the cgroup. This is in
+ nanoseconds. If this is read when the cgroup is in an empty state,
+ the stat will only report the empty_time accumulated till the last
+ time it had a pending request and will not include the current delta.
+
+ blkio.idle_time
+ Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y.
+ This is the amount of time spent by the IO scheduler idling for a
+ given cgroup in anticipation of a better request than the existing ones
+ from other queues/cgroups. This is in nanoseconds. If this is read
+ when the cgroup is in an idling state, the stat will only report the
+ idle_time accumulated till the last idle period and will not include
+ the current delta.
+
+ blkio.dequeue
+ Debugging aid only enabled if CONFIG_BFQ_CGROUP_DEBUG=y. This
+ gives the statistics about how many a times a group was dequeued
+ from service tree of the device. First two fields specify the major
+ and minor number of the device and third field specifies the number
+ of times a group was dequeued from a particular device.
+
+ blkio.*_recursive
+ Recursive version of various stats. These files show the
+ same information as their non-recursive counterparts but
+ include stats from all the descendant cgroups.
+
+Throttling/Upper limit policy files
+-----------------------------------
+ blkio.throttle.read_bps_device
+ Specifies upper limit on READ rate from the device. IO rate is
+ specified in bytes per second. Rules are per device. Following is
+ the format::
+
+ echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
+
+ blkio.throttle.write_bps_device
+ Specifies upper limit on WRITE rate to the device. IO rate is
+ specified in bytes per second. Rules are per device. Following is
+ the format::
+
+ echo "<major>:<minor> <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
+
+ blkio.throttle.read_iops_device
+ Specifies upper limit on READ rate from the device. IO rate is
+ specified in IO per second. Rules are per device. Following is
+ the format::
+
+ echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
+
+ blkio.throttle.write_iops_device
+ Specifies upper limit on WRITE rate to the device. IO rate is
+ specified in io per second. Rules are per device. Following is
+ the format::
+
+ echo "<major>:<minor> <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
+
+ Note: If both BW and IOPS rules are specified for a device, then IO is
+ subjected to both the constraints.
+
+ blkio.throttle.io_serviced
+ Number of IOs (bio) issued to the disk by the group. These
+ are further divided by the type of operation - read or write, sync
+ or async. First two fields specify the major and minor number of the
+ device, third field specifies the operation type and the fourth field
+ specifies the number of IOs.
+
+ blkio.throttle.io_service_bytes
+ Number of bytes transferred to/from the disk by the group. These
+ are further divided by the type of operation - read or write, sync
+ or async. First two fields specify the major and minor number of the
+ device, third field specifies the operation type and the fourth field
+ specifies the number of bytes.
+
+Common files among various policies
+-----------------------------------
+ blkio.reset_stats
+ Writing an int to this file will result in resetting all the stats
+ for that cgroup.
diff --git a/Documentation/admin-guide/cgroup-v1/cgroups.rst b/Documentation/admin-guide/cgroup-v1/cgroups.rst
new file mode 100644
index 000000000000..463f98453323
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/cgroups.rst
@@ -0,0 +1,697 @@
+==============
+Control Groups
+==============
+
+Written by Paul Menage <menage@google.com> based on
+Documentation/admin-guide/cgroup-v1/cpusets.rst
+
+Original copyright statements from cpusets.txt:
+
+Portions Copyright (C) 2004 BULL SA.
+
+Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
+
+Modified by Paul Jackson <pj@sgi.com>
+
+Modified by Christoph Lameter <cl@gentwo.org>
+
+.. CONTENTS:
+
+ 1. Control Groups
+ 1.1 What are cgroups ?
+ 1.2 Why are cgroups needed ?
+ 1.3 How are cgroups implemented ?
+ 1.4 What does notify_on_release do ?
+ 1.5 What does clone_children do ?
+ 1.6 How do I use cgroups ?
+ 2. Usage Examples and Syntax
+ 2.1 Basic Usage
+ 2.2 Attaching processes
+ 2.3 Mounting hierarchies by name
+ 3. Kernel API
+ 3.1 Overview
+ 3.2 Synchronization
+ 3.3 Subsystem API
+ 4. Extended attributes usage
+ 5. Questions
+
+1. Control Groups
+=================
+
+1.1 What are cgroups ?
+----------------------
+
+Control Groups provide a mechanism for aggregating/partitioning sets of
+tasks, and all their future children, into hierarchical groups with
+specialized behaviour.
+
+Definitions:
+
+A *cgroup* associates a set of tasks with a set of parameters for one
+or more subsystems.
+
+A *subsystem* is a module that makes use of the task grouping
+facilities provided by cgroups to treat groups of tasks in
+particular ways. A subsystem is typically a "resource controller" that
+schedules a resource or applies per-cgroup limits, but it may be
+anything that wants to act on a group of processes, e.g. a
+virtualization subsystem.
+
+A *hierarchy* is a set of cgroups arranged in a tree, such that
+every task in the system is in exactly one of the cgroups in the
+hierarchy, and a set of subsystems; each subsystem has system-specific
+state attached to each cgroup in the hierarchy. Each hierarchy has
+an instance of the cgroup virtual filesystem associated with it.
+
+At any one time there may be multiple active hierarchies of task
+cgroups. Each hierarchy is a partition of all tasks in the system.
+
+User-level code may create and destroy cgroups by name in an
+instance of the cgroup virtual file system, specify and query to
+which cgroup a task is assigned, and list the task PIDs assigned to
+a cgroup. Those creations and assignments only affect the hierarchy
+associated with that instance of the cgroup file system.
+
+On their own, the only use for cgroups is for simple job
+tracking. The intention is that other subsystems hook into the generic
+cgroup support to provide new attributes for cgroups, such as
+accounting/limiting the resources which processes in a cgroup can
+access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rst) allow
+you to associate a set of CPUs and a set of memory nodes with the
+tasks in each cgroup.
+
+.. _cgroups-why-needed:
+
+1.2 Why are cgroups needed ?
+----------------------------
+
+There are multiple efforts to provide process aggregations in the
+Linux kernel, mainly for resource-tracking purposes. Such efforts
+include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server
+namespaces. These all require the basic notion of a
+grouping/partitioning of processes, with newly forked processes ending
+up in the same group (cgroup) as their parent process.
+
+The kernel cgroup patch provides the minimum essential kernel
+mechanisms required to efficiently implement such groups. It has
+minimal impact on the system fast paths, and provides hooks for
+specific subsystems such as cpusets to provide additional behaviour as
+desired.
+
+Multiple hierarchy support is provided to allow for situations where
+the division of tasks into cgroups is distinctly different for
+different subsystems - having parallel hierarchies allows each
+hierarchy to be a natural division of tasks, without having to handle
+complex combinations of tasks that would be present if several
+unrelated subsystems needed to be forced into the same tree of
+cgroups.
+
+At one extreme, each resource controller or subsystem could be in a
+separate hierarchy; at the other extreme, all subsystems
+would be attached to the same hierarchy.
+
+As an example of a scenario (originally proposed by vatsa@in.ibm.com)
+that can benefit from multiple hierarchies, consider a large
+university server with various users - students, professors, system
+tasks etc. The resource planning for this server could be along the
+following lines::
+
+ CPU : "Top cpuset"
+ / \
+ CPUSet1 CPUSet2
+ | |
+ (Professors) (Students)
+
+ In addition (system tasks) are attached to topcpuset (so
+ that they can run anywhere) with a limit of 20%
+
+ Memory : Professors (50%), Students (30%), system (20%)
+
+ Disk : Professors (50%), Students (30%), system (20%)
+
+ Network : WWW browsing (20%), Network File System (60%), others (20%)
+ / \
+ Professors (15%) students (5%)
+
+Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes
+into the NFS network class.
+
+At the same time Firefox/Lynx will share an appropriate CPU/Memory class
+depending on who launched it (prof/student).
+
+With the ability to classify tasks differently for different resources
+(by putting those resource subsystems in different hierarchies),
+the admin can easily set up a script which receives exec notifications
+and depending on who is launching the browser he can::
+
+ # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks
+
+With only a single hierarchy, he now would potentially have to create
+a separate cgroup for every browser launched and associate it with
+appropriate network and other resource class. This may lead to
+proliferation of such cgroups.
+
+Also let's say that the administrator would like to give enhanced network
+access temporarily to a student's browser (since it is night and the user
+wants to do online gaming :)) OR give one of the student's simulation
+apps enhanced CPU power.
+
+With ability to write PIDs directly to resource classes, it's just a
+matter of::
+
+ # echo pid > /sys/fs/cgroup/network/<new_class>/tasks
+ (after some time)
+ # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks
+
+Without this ability, the administrator would have to split the cgroup into
+multiple separate ones and then associate the new cgroups with the
+new resource classes.
+
+
+
+1.3 How are cgroups implemented ?
+---------------------------------
+
+Control Groups extends the kernel as follows:
+
+ - Each task in the system has a reference-counted pointer to a
+ css_set.
+
+ - A css_set contains a set of reference-counted pointers to
+ cgroup_subsys_state objects, one for each cgroup subsystem
+ registered in the system. There is no direct link from a task to
+ the cgroup of which it's a member in each hierarchy, but this
+ can be determined by following pointers through the
+ cgroup_subsys_state objects. This is because accessing the
+ subsystem state is something that's expected to happen frequently
+ and in performance-critical code, whereas operations that require a
+ task's actual cgroup assignments (in particular, moving between
+ cgroups) are less common. A linked list runs through the cg_list
+ field of each task_struct using the css_set, anchored at
+ css_set->tasks.
+
+ - A cgroup hierarchy filesystem can be mounted for browsing and
+ manipulation from user space.
+
+ - You can list all the tasks (by PID) attached to any cgroup.
+
+The implementation of cgroups requires a few, simple hooks
+into the rest of the kernel, none in performance-critical paths:
+
+ - in init/main.c, to initialize the root cgroups and initial
+ css_set at system boot.
+
+ - in fork and exit, to attach and detach a task from its css_set.
+
+In addition, a new file system of type "cgroup" may be mounted, to
+enable browsing and modifying the cgroups presently known to the
+kernel. When mounting a cgroup hierarchy, you may specify a
+comma-separated list of subsystems to mount as the filesystem mount
+options. By default, mounting the cgroup filesystem attempts to
+mount a hierarchy containing all registered subsystems.
+
+If an active hierarchy with exactly the same set of subsystems already
+exists, it will be reused for the new mount. If no existing hierarchy
+matches, and any of the requested subsystems are in use in an existing
+hierarchy, the mount will fail with -EBUSY. Otherwise, a new hierarchy
+is activated, associated with the requested subsystems.
+
+It's not currently possible to bind a new subsystem to an active
+cgroup hierarchy, or to unbind a subsystem from an active cgroup
+hierarchy. This may be possible in future, but is fraught with nasty
+error-recovery issues.
+
+When a cgroup filesystem is unmounted, if there are any
+child cgroups created below the top-level cgroup, that hierarchy
+will remain active even though unmounted; if there are no
+child cgroups then the hierarchy will be deactivated.
+
+No new system calls are added for cgroups - all support for
+querying and modifying cgroups is via this cgroup file system.
+
+Each task under /proc has an added file named 'cgroup' displaying,
+for each active hierarchy, the subsystem names and the cgroup name
+as the path relative to the root of the cgroup file system.
+
+Each cgroup is represented by a directory in the cgroup file system
+containing the following files describing that cgroup:
+
+ - tasks: list of tasks (by PID) attached to that cgroup. This list
+ is not guaranteed to be sorted. Writing a thread ID into this file
+ moves the thread into this cgroup.
+ - cgroup.procs: list of thread group IDs in the cgroup. This list is
+ not guaranteed to be sorted or free of duplicate TGIDs, and userspace
+ should sort/uniquify the list if this property is required.
+ Writing a thread group ID into this file moves all threads in that
+ group into this cgroup.
+ - notify_on_release flag: run the release agent on exit?
+ - release_agent: the path to use for release notifications (this file
+ exists in the top cgroup only)
+
+Other subsystems such as cpusets may add additional files in each
+cgroup dir.
+
+New cgroups are created using the mkdir system call or shell
+command. The properties of a cgroup, such as its flags, are
+modified by writing to the appropriate file in that cgroups
+directory, as listed above.
+
+The named hierarchical structure of nested cgroups allows partitioning
+a large system into nested, dynamically changeable, "soft-partitions".
+
+The attachment of each task, automatically inherited at fork by any
+children of that task, to a cgroup allows organizing the work load
+on a system into related sets of tasks. A task may be re-attached to
+any other cgroup, if allowed by the permissions on the necessary
+cgroup file system directories.
+
+When a task is moved from one cgroup to another, it gets a new
+css_set pointer - if there's an already existing css_set with the
+desired collection of cgroups then that group is reused, otherwise a new
+css_set is allocated. The appropriate existing css_set is located by
+looking into a hash table.
+
+To allow access from a cgroup to the css_sets (and hence tasks)
+that comprise it, a set of cg_cgroup_link objects form a lattice;
+each cg_cgroup_link is linked into a list of cg_cgroup_links for
+a single cgroup on its cgrp_link_list field, and a list of
+cg_cgroup_links for a single css_set on its cg_link_list.
+
+Thus the set of tasks in a cgroup can be listed by iterating over
+each css_set that references the cgroup, and sub-iterating over
+each css_set's task set.
+
+The use of a Linux virtual file system (vfs) to represent the
+cgroup hierarchy provides for a familiar permission and name space
+for cgroups, with a minimum of additional kernel code.
+
+1.4 What does notify_on_release do ?
+------------------------------------
+
+If the notify_on_release flag is enabled (1) in a cgroup, then
+whenever the last task in the cgroup leaves (exits or attaches to
+some other cgroup) and the last child cgroup of that cgroup
+is removed, then the kernel runs the command specified by the contents
+of the "release_agent" file in that hierarchy's root directory,
+supplying the pathname (relative to the mount point of the cgroup
+file system) of the abandoned cgroup. This enables automatic
+removal of abandoned cgroups. The default value of
+notify_on_release in the root cgroup at system boot is disabled
+(0). The default value of other cgroups at creation is the current
+value of their parents' notify_on_release settings. The default value of
+a cgroup hierarchy's release_agent path is empty.
+
+1.5 What does clone_children do ?
+---------------------------------
+
+This flag only affects the cpuset controller. If the clone_children
+flag is enabled (1) in a cgroup, a new cpuset cgroup will copy its
+configuration from the parent during initialization.
+
+1.6 How do I use cgroups ?
+--------------------------
+
+To start a new job that is to be contained within a cgroup, using
+the "cpuset" cgroup subsystem, the steps are something like::
+
+ 1) mount -t tmpfs cgroup_root /sys/fs/cgroup
+ 2) mkdir /sys/fs/cgroup/cpuset
+ 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
+ 4) Create the new cgroup by doing mkdir's and write's (or echo's) in
+ the /sys/fs/cgroup/cpuset virtual file system.
+ 5) Start a task that will be the "founding father" of the new job.
+ 6) Attach that task to the new cgroup by writing its PID to the
+ /sys/fs/cgroup/cpuset tasks file for that cgroup.
+ 7) fork, exec or clone the job tasks from this founding father task.
+
+For example, the following sequence of commands will setup a cgroup
+named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
+and then start a subshell 'sh' in that cgroup::
+
+ mount -t tmpfs cgroup_root /sys/fs/cgroup
+ mkdir /sys/fs/cgroup/cpuset
+ mount -t cgroup cpuset -ocpuset /sys/fs/cgroup/cpuset
+ cd /sys/fs/cgroup/cpuset
+ mkdir Charlie
+ cd Charlie
+ /bin/echo 2-3 > cpuset.cpus
+ /bin/echo 1 > cpuset.mems
+ /bin/echo $$ > tasks
+ sh
+ # The subshell 'sh' is now running in cgroup Charlie
+ # The next line should display '/Charlie'
+ cat /proc/self/cgroup
+
+2. Usage Examples and Syntax
+============================
+
+2.1 Basic Usage
+---------------
+
+Creating, modifying, using cgroups can be done through the cgroup
+virtual filesystem.
+
+To mount a cgroup hierarchy with all available subsystems, type::
+
+ # mount -t cgroup xxx /sys/fs/cgroup
+
+The "xxx" is not interpreted by the cgroup code, but will appear in
+/proc/mounts so may be any useful identifying string that you like.
+
+Note: Some subsystems do not work without some user input first. For instance,
+if cpusets are enabled the user will have to populate the cpus and mems files
+for each new cgroup created before that group can be used.
+
+As explained in section `1.2 Why are cgroups needed?` you should create
+different hierarchies of cgroups for each single resource or group of
+resources you want to control. Therefore, you should mount a tmpfs on
+/sys/fs/cgroup and create directories for each cgroup resource or resource
+group::
+
+ # mount -t tmpfs cgroup_root /sys/fs/cgroup
+ # mkdir /sys/fs/cgroup/rg1
+
+To mount a cgroup hierarchy with just the cpuset and memory
+subsystems, type::
+
+ # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1
+
+While remounting cgroups is currently supported, it is not recommend
+to use it. Remounting allows changing bound subsystems and
+release_agent. Rebinding is hardly useful as it only works when the
+hierarchy is empty and release_agent itself should be replaced with
+conventional fsnotify. The support for remounting will be removed in
+the future.
+
+To Specify a hierarchy's release_agent::
+
+ # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
+ xxx /sys/fs/cgroup/rg1
+
+Note that specifying 'release_agent' more than once will return failure.
+
+Note that changing the set of subsystems is currently only supported
+when the hierarchy consists of a single (root) cgroup. Supporting
+the ability to arbitrarily bind/unbind subsystems from an existing
+cgroup hierarchy is intended to be implemented in the future.
+
+Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
+tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
+is the cgroup that holds the whole system.
+
+If you want to change the value of release_agent::
+
+ # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent
+
+It can also be changed via remount.
+
+If you want to create a new cgroup under /sys/fs/cgroup/rg1::
+
+ # cd /sys/fs/cgroup/rg1
+ # mkdir my_cgroup
+
+Now you want to do something with this cgroup:
+
+ # cd my_cgroup
+
+In this directory you can find several files::
+
+ # ls
+ cgroup.procs notify_on_release tasks
+ (plus whatever files added by the attached subsystems)
+
+Now attach your shell to this cgroup::
+
+ # /bin/echo $$ > tasks
+
+You can also create cgroups inside your cgroup by using mkdir in this
+directory::
+
+ # mkdir my_sub_cs
+
+To remove a cgroup, just use rmdir::
+
+ # rmdir my_sub_cs
+
+This will fail if the cgroup is in use (has cgroups inside, or
+has processes attached, or is held alive by other subsystem-specific
+reference).
+
+2.2 Attaching processes
+-----------------------
+
+::
+
+ # /bin/echo PID > tasks
+
+Note that it is PID, not PIDs. You can only attach ONE task at a time.
+If you have several tasks to attach, you have to do it one after another::
+
+ # /bin/echo PID1 > tasks
+ # /bin/echo PID2 > tasks
+ ...
+ # /bin/echo PIDn > tasks
+
+You can attach the current shell task by echoing 0::
+
+ # echo 0 > tasks
+
+You can use the cgroup.procs file instead of the tasks file to move all
+threads in a threadgroup at once. Echoing the PID of any task in a
+threadgroup to cgroup.procs causes all tasks in that threadgroup to be
+attached to the cgroup. Writing 0 to cgroup.procs moves all tasks
+in the writing task's threadgroup.
+
+Note: Since every task is always a member of exactly one cgroup in each
+mounted hierarchy, to remove a task from its current cgroup you must
+move it into a new cgroup (possibly the root cgroup) by writing to the
+new cgroup's tasks file.
+
+Note: Due to some restrictions enforced by some cgroup subsystems, moving
+a process to another cgroup can fail.
+
+2.3 Mounting hierarchies by name
+--------------------------------
+
+Passing the name=<x> option when mounting a cgroups hierarchy
+associates the given name with the hierarchy. This can be used when
+mounting a pre-existing hierarchy, in order to refer to it by name
+rather than by its set of active subsystems. Each hierarchy is either
+nameless, or has a unique name.
+
+The name should match [\w.-]+
+
+When passing a name=<x> option for a new hierarchy, you need to
+specify subsystems manually; the legacy behaviour of mounting all
+subsystems when none are explicitly specified is not supported when
+you give a subsystem a name.
+
+The name of the subsystem appears as part of the hierarchy description
+in /proc/mounts and /proc/<pid>/cgroups.
+
+
+3. Kernel API
+=============
+
+3.1 Overview
+------------
+
+Each kernel subsystem that wants to hook into the generic cgroup
+system needs to create a cgroup_subsys object. This contains
+various methods, which are callbacks from the cgroup system, along
+with a subsystem ID which will be assigned by the cgroup system.
+
+Other fields in the cgroup_subsys object include:
+
+- subsys_id: a unique array index for the subsystem, indicating which
+ entry in cgroup->subsys[] this subsystem should be managing.
+
+- name: should be initialized to a unique subsystem name. Should be
+ no longer than MAX_CGROUP_TYPE_NAMELEN.
+
+- early_init: indicate if the subsystem needs early initialization
+ at system boot.
+
+Each cgroup object created by the system has an array of pointers,
+indexed by subsystem ID; this pointer is entirely managed by the
+subsystem; the generic cgroup code will never touch this pointer.
+
+3.2 Synchronization
+-------------------
+
+There is a global mutex, cgroup_mutex, used by the cgroup
+system. This should be taken by anything that wants to modify a
+cgroup. It may also be taken to prevent cgroups from being
+modified, but more specific locks may be more appropriate in that
+situation.
+
+See kernel/cgroup.c for more details.
+
+Subsystems can take/release the cgroup_mutex via the functions
+cgroup_lock()/cgroup_unlock().
+
+Accessing a task's cgroup pointer may be done in the following ways:
+- while holding cgroup_mutex
+- while holding the task's alloc_lock (via task_lock())
+- inside an rcu_read_lock() section via rcu_dereference()
+
+3.3 Subsystem API
+-----------------
+
+Each subsystem should:
+
+- add an entry in linux/cgroup_subsys.h
+- define a cgroup_subsys object called <name>_cgrp_subsys
+
+Each subsystem may export the following methods. The only mandatory
+methods are css_alloc/free. Any others that are null are presumed to
+be successful no-ops.
+
+``struct cgroup_subsys_state *css_alloc(struct cgroup *cgrp)``
+(cgroup_mutex held by caller)
+
+Called to allocate a subsystem state object for a cgroup. The
+subsystem should allocate its subsystem state object for the passed
+cgroup, returning a pointer to the new object on success or a
+ERR_PTR() value. On success, the subsystem pointer should point to
+a structure of type cgroup_subsys_state (typically embedded in a
+larger subsystem-specific object), which will be initialized by the
+cgroup system. Note that this will be called at initialization to
+create the root subsystem state for this subsystem; this case can be
+identified by the passed cgroup object having a NULL parent (since
+it's the root of the hierarchy) and may be an appropriate place for
+initialization code.
+
+``int css_online(struct cgroup *cgrp)``
+(cgroup_mutex held by caller)
+
+Called after @cgrp successfully completed all allocations and made
+visible to cgroup_for_each_child/descendant_*() iterators. The
+subsystem may choose to fail creation by returning -errno. This
+callback can be used to implement reliable state sharing and
+propagation along the hierarchy. See the comment on
+cgroup_for_each_live_descendant_pre() for details.
+
+``void css_offline(struct cgroup *cgrp);``
+(cgroup_mutex held by caller)
+
+This is the counterpart of css_online() and called iff css_online()
+has succeeded on @cgrp. This signifies the beginning of the end of
+@cgrp. @cgrp is being removed and the subsystem should start dropping
+all references it's holding on @cgrp. When all references are dropped,
+cgroup removal will proceed to the next step - css_free(). After this
+callback, @cgrp should be considered dead to the subsystem.
+
+``void css_free(struct cgroup *cgrp)``
+(cgroup_mutex held by caller)
+
+The cgroup system is about to free @cgrp; the subsystem should free
+its subsystem state object. By the time this method is called, @cgrp
+is completely unused; @cgrp->parent is still valid. (Note - can also
+be called for a newly-created cgroup if an error occurs after this
+subsystem's create() method has been called for the new cgroup).
+
+``int can_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
+(cgroup_mutex held by caller)
+
+Called prior to moving one or more tasks into a cgroup; if the
+subsystem returns an error, this will abort the attach operation.
+@tset contains the tasks to be attached and is guaranteed to have at
+least one task in it.
+
+If there are multiple tasks in the taskset, then:
+ - it's guaranteed that all are from the same thread group
+ - @tset contains all tasks from the thread group whether or not
+ they're switching cgroups
+ - the first task is the leader
+
+Each @tset entry also contains the task's old cgroup and tasks which
+aren't switching cgroup can be skipped easily using the
+cgroup_taskset_for_each() iterator. Note that this isn't called on a
+fork. If this method returns 0 (success) then this should remain valid
+while the caller holds cgroup_mutex and it is ensured that either
+attach() or cancel_attach() will be called in future.
+
+``void css_reset(struct cgroup_subsys_state *css)``
+(cgroup_mutex held by caller)
+
+An optional operation which should restore @css's configuration to the
+initial state. This is currently only used on the unified hierarchy
+when a subsystem is disabled on a cgroup through
+"cgroup.subtree_control" but should remain enabled because other
+subsystems depend on it. cgroup core makes such a css invisible by
+removing the associated interface files and invokes this callback so
+that the hidden subsystem can return to the initial neutral state.
+This prevents unexpected resource control from a hidden css and
+ensures that the configuration is in the initial state when it is made
+visible again later.
+
+``void cancel_attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
+(cgroup_mutex held by caller)
+
+Called when a task attach operation has failed after can_attach() has succeeded.
+A subsystem whose can_attach() has some side-effects should provide this
+function, so that the subsystem can implement a rollback. If not, not necessary.
+This will be called only about subsystems whose can_attach() operation have
+succeeded. The parameters are identical to can_attach().
+
+``void attach(struct cgroup *cgrp, struct cgroup_taskset *tset)``
+(cgroup_mutex held by caller)
+
+Called after the task has been attached to the cgroup, to allow any
+post-attachment activity that requires memory allocations or blocking.
+The parameters are identical to can_attach().
+
+``void fork(struct task_struct *task)``
+
+Called when a task is forked into a cgroup.
+
+``void exit(struct task_struct *task)``
+
+Called during task exit.
+
+``void free(struct task_struct *task)``
+
+Called when the task_struct is freed.
+
+``void bind(struct cgroup *root)``
+(cgroup_mutex held by caller)
+
+Called when a cgroup subsystem is rebound to a different hierarchy
+and root cgroup. Currently this will only involve movement between
+the default hierarchy (which never has sub-cgroups) and a hierarchy
+that is being created/destroyed (and hence has no sub-cgroups).
+
+4. Extended attribute usage
+===========================
+
+cgroup filesystem supports certain types of extended attributes in its
+directories and files. The current supported types are:
+
+ - Trusted (XATTR_TRUSTED)
+ - Security (XATTR_SECURITY)
+
+Both require CAP_SYS_ADMIN capability to set.
+
+Like in tmpfs, the extended attributes in cgroup filesystem are stored
+using kernel memory and it's advised to keep the usage at minimum. This
+is the reason why user defined extended attributes are not supported, since
+any user can do it and there's no limit in the value size.
+
+The current known users for this feature are SELinux to limit cgroup usage
+in containers and systemd for assorted meta data like main PID in a cgroup
+(systemd creates a cgroup per service).
+
+5. Questions
+============
+
+::
+
+ Q: what's up with this '/bin/echo' ?
+ A: bash's builtin 'echo' command does not check calls to write() against
+ errors. If you use it in the cgroup file system, you won't be
+ able to tell whether a command succeeded or failed.
+
+ Q: When I attach processes, only the first of the line gets really attached !
+ A: We can only return one error code per call to write(). So you should also
+ put only ONE PID.
diff --git a/Documentation/admin-guide/cgroup-v1/cpuacct.rst b/Documentation/admin-guide/cgroup-v1/cpuacct.rst
new file mode 100644
index 000000000000..d30ed81d2ad7
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/cpuacct.rst
@@ -0,0 +1,50 @@
+=========================
+CPU Accounting Controller
+=========================
+
+The CPU accounting controller is used to group tasks using cgroups and
+account the CPU usage of these groups of tasks.
+
+The CPU accounting controller supports multi-hierarchy groups. An accounting
+group accumulates the CPU usage of all of its child groups and the tasks
+directly present in its group.
+
+Accounting groups can be created by first mounting the cgroup filesystem::
+
+ # mount -t cgroup -ocpuacct none /sys/fs/cgroup
+
+With the above step, the initial or the parent accounting group becomes
+visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
+the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
+/sys/fs/cgroup/cpuacct.usage gives the CPU time (in nanoseconds) obtained
+by this group which is essentially the CPU time obtained by all the tasks
+in the system.
+
+New accounting groups can be created under the parent group /sys/fs/cgroup::
+
+ # cd /sys/fs/cgroup
+ # mkdir g1
+ # echo $$ > g1/tasks
+
+The above steps create a new group g1 and move the current shell
+process (bash) into it. CPU time consumed by this bash and its children
+can be obtained from g1/cpuacct.usage and the same is accumulated in
+/sys/fs/cgroup/cpuacct.usage also.
+
+cpuacct.stat file lists a few statistics which further divide the
+CPU time obtained by the cgroup into user and system times. Currently
+the following statistics are supported:
+
+user: Time spent by tasks of the cgroup in user mode.
+system: Time spent by tasks of the cgroup in kernel mode.
+
+user and system are in USER_HZ unit.
+
+cpuacct controller uses percpu_counter interface to collect user and
+system times. This has two side effects:
+
+- It is theoretically possible to see wrong values for user and system times.
+ This is because percpu_counter_read() on 32bit systems isn't safe
+ against concurrent writes.
+- It is possible to see slightly outdated values for user and system times
+ due to the batch processing nature of percpu_counter.
diff --git a/Documentation/admin-guide/cgroup-v1/cpusets.rst b/Documentation/admin-guide/cgroup-v1/cpusets.rst
new file mode 100644
index 000000000000..c7909e5ac136
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/cpusets.rst
@@ -0,0 +1,884 @@
+.. _cpusets:
+
+=======
+CPUSETS
+=======
+
+Copyright (C) 2004 BULL SA.
+
+Written by Simon.Derr@bull.net
+
+- Portions Copyright (c) 2004-2006 Silicon Graphics, Inc.
+- Modified by Paul Jackson <pj@sgi.com>
+- Modified by Christoph Lameter <cl@gentwo.org>
+- Modified by Paul Menage <menage@google.com>
+- Modified by Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com>
+
+.. CONTENTS:
+
+ 1. Cpusets
+ 1.1 What are cpusets ?
+ 1.2 Why are cpusets needed ?
+ 1.3 How are cpusets implemented ?
+ 1.4 What are exclusive cpusets ?
+ 1.5 What is memory_pressure ?
+ 1.6 What is memory spread ?
+ 1.7 What is sched_load_balance ?
+ 1.8 What is sched_relax_domain_level ?
+ 1.9 How do I use cpusets ?
+ 2. Usage Examples and Syntax
+ 2.1 Basic Usage
+ 2.2 Adding/removing cpus
+ 2.3 Setting flags
+ 2.4 Attaching processes
+ 3. Questions
+ 4. Contact
+
+1. Cpusets
+==========
+
+1.1 What are cpusets ?
+----------------------
+
+Cpusets provide a mechanism for assigning a set of CPUs and Memory
+Nodes to a set of tasks. In this document "Memory Node" refers to
+an on-line node that contains memory.
+
+Cpusets constrain the CPU and Memory placement of tasks to only
+the resources within a task's current cpuset. They form a nested
+hierarchy visible in a virtual file system. These are the essential
+hooks, beyond what is already present, required to manage dynamic
+job placement on large systems.
+
+Cpusets use the generic cgroup subsystem described in
+Documentation/admin-guide/cgroup-v1/cgroups.rst.
+
+Requests by a task, using the sched_setaffinity(2) system call to
+include CPUs in its CPU affinity mask, and using the mbind(2) and
+set_mempolicy(2) system calls to include Memory Nodes in its memory
+policy, are both filtered through that task's cpuset, filtering out any
+CPUs or Memory Nodes not in that cpuset. The scheduler will not
+schedule a task on a CPU that is not allowed in its cpus_allowed
+vector, and the kernel page allocator will not allocate a page on a
+node that is not allowed in the requesting task's mems_allowed vector.
+
+User level code may create and destroy cpusets by name in the cgroup
+virtual file system, manage the attributes and permissions of these
+cpusets and which CPUs and Memory Nodes are assigned to each cpuset,
+specify and query to which cpuset a task is assigned, and list the
+task pids assigned to a cpuset.
+
+
+1.2 Why are cpusets needed ?
+----------------------------
+
+The management of large computer systems, with many processors (CPUs),
+complex memory cache hierarchies and multiple Memory Nodes having
+non-uniform access times (NUMA) presents additional challenges for
+the efficient scheduling and memory placement of processes.
+
+Frequently more modest sized systems can be operated with adequate
+efficiency just by letting the operating system automatically share
+the available CPU and Memory resources amongst the requesting tasks.
+
+But larger systems, which benefit more from careful processor and
+memory placement to reduce memory access times and contention,
+and which typically represent a larger investment for the customer,
+can benefit from explicitly placing jobs on properly sized subsets of
+the system.
+
+This can be especially valuable on:
+
+ * Web Servers running multiple instances of the same web application,
+ * Servers running different applications (for instance, a web server
+ and a database), or
+ * NUMA systems running large HPC applications with demanding
+ performance characteristics.
+
+These subsets, or "soft partitions" must be able to be dynamically
+adjusted, as the job mix changes, without impacting other concurrently
+executing jobs. The location of the running jobs pages may also be moved
+when the memory locations are changed.
+
+The kernel cpuset patch provides the minimum essential kernel
+mechanisms required to efficiently implement such subsets. It
+leverages existing CPU and Memory Placement facilities in the Linux
+kernel to avoid any additional impact on the critical scheduler or
+memory allocator code.
+
+
+1.3 How are cpusets implemented ?
+---------------------------------
+
+Cpusets provide a Linux kernel mechanism to constrain which CPUs and
+Memory Nodes are used by a process or set of processes.
+
+The Linux kernel already has a pair of mechanisms to specify on which
+CPUs a task may be scheduled (sched_setaffinity) and on which Memory
+Nodes it may obtain memory (mbind, set_mempolicy).
+
+Cpusets extends these two mechanisms as follows:
+
+ - Cpusets are sets of allowed CPUs and Memory Nodes, known to the
+ kernel.
+ - Each task in the system is attached to a cpuset, via a pointer
+ in the task structure to a reference counted cgroup structure.
+ - Calls to sched_setaffinity are filtered to just those CPUs
+ allowed in that task's cpuset.
+ - Calls to mbind and set_mempolicy are filtered to just
+ those Memory Nodes allowed in that task's cpuset.
+ - The root cpuset contains all the systems CPUs and Memory
+ Nodes.
+ - For any cpuset, one can define child cpusets containing a subset
+ of the parents CPU and Memory Node resources.
+ - The hierarchy of cpusets can be mounted at /dev/cpuset, for
+ browsing and manipulation from user space.
+ - A cpuset may be marked exclusive, which ensures that no other
+ cpuset (except direct ancestors and descendants) may contain
+ any overlapping CPUs or Memory Nodes.
+ - You can list all the tasks (by pid) attached to any cpuset.
+
+The implementation of cpusets requires a few, simple hooks
+into the rest of the kernel, none in performance critical paths:
+
+ - in init/main.c, to initialize the root cpuset at system boot.
+ - in fork and exit, to attach and detach a task from its cpuset.
+ - in sched_setaffinity, to mask the requested CPUs by what's
+ allowed in that task's cpuset.
+ - in sched.c migrate_live_tasks(), to keep migrating tasks within
+ the CPUs allowed by their cpuset, if possible.
+ - in the mbind and set_mempolicy system calls, to mask the requested
+ Memory Nodes by what's allowed in that task's cpuset.
+ - in page_alloc.c, to restrict memory to allowed nodes.
+ - in vmscan.c, to restrict page recovery to the current cpuset.
+
+You should mount the "cgroup" filesystem type in order to enable
+browsing and modifying the cpusets presently known to the kernel. No
+new system calls are added for cpusets - all support for querying and
+modifying cpusets is via this cpuset file system.
+
+The /proc/<pid>/status file for each task has four added lines,
+displaying the task's cpus_allowed (on which CPUs it may be scheduled)
+and mems_allowed (on which Memory Nodes it may obtain memory),
+in the two formats seen in the following example::
+
+ Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff
+ Cpus_allowed_list: 0-127
+ Mems_allowed: ffffffff,ffffffff
+ Mems_allowed_list: 0-63
+
+Each cpuset is represented by a directory in the cgroup file system
+containing (on top of the standard cgroup files) the following
+files describing that cpuset:
+
+ - cpuset.cpus: list of CPUs in that cpuset
+ - cpuset.mems: list of Memory Nodes in that cpuset
+ - cpuset.memory_migrate flag: if set, move pages to cpusets nodes
+ - cpuset.cpu_exclusive flag: is cpu placement exclusive?
+ - cpuset.mem_exclusive flag: is memory placement exclusive?
+ - cpuset.mem_hardwall flag: is memory allocation hardwalled
+ - cpuset.memory_pressure: measure of how much paging pressure in cpuset
+ - cpuset.memory_spread_page flag: if set, spread page cache evenly on allowed nodes
+ - cpuset.memory_spread_slab flag: OBSOLETE. Doesn't have any function.
+ - cpuset.sched_load_balance flag: if set, load balance within CPUs on that cpuset
+ - cpuset.sched_relax_domain_level: the searching range when migrating tasks
+
+In addition, only the root cpuset has the following file:
+
+ - cpuset.memory_pressure_enabled flag: compute memory_pressure?
+
+New cpusets are created using the mkdir system call or shell
+command. The properties of a cpuset, such as its flags, allowed
+CPUs and Memory Nodes, and attached tasks, are modified by writing
+to the appropriate file in that cpusets directory, as listed above.
+
+The named hierarchical structure of nested cpusets allows partitioning
+a large system into nested, dynamically changeable, "soft-partitions".
+
+The attachment of each task, automatically inherited at fork by any
+children of that task, to a cpuset allows organizing the work load
+on a system into related sets of tasks such that each set is constrained
+to using the CPUs and Memory Nodes of a particular cpuset. A task
+may be re-attached to any other cpuset, if allowed by the permissions
+on the necessary cpuset file system directories.
+
+Such management of a system "in the large" integrates smoothly with
+the detailed placement done on individual tasks and memory regions
+using the sched_setaffinity, mbind and set_mempolicy system calls.
+
+The following rules apply to each cpuset:
+
+ - Its CPUs and Memory Nodes must be a subset of its parents.
+ - It can't be marked exclusive unless its parent is.
+ - If its cpu or memory is exclusive, they may not overlap any sibling.
+
+These rules, and the natural hierarchy of cpusets, enable efficient
+enforcement of the exclusive guarantee, without having to scan all
+cpusets every time any of them change to ensure nothing overlaps a
+exclusive cpuset. Also, the use of a Linux virtual file system (vfs)
+to represent the cpuset hierarchy provides for a familiar permission
+and name space for cpusets, with a minimum of additional kernel code.
+
+The cpus and mems files in the root (top_cpuset) cpuset are
+read-only. The cpus file automatically tracks the value of
+cpu_online_mask using a CPU hotplug notifier, and the mems file
+automatically tracks the value of node_states[N_MEMORY]--i.e.,
+nodes with memory--using the cpuset_track_online_nodes() hook.
+
+The cpuset.effective_cpus and cpuset.effective_mems files are
+normally read-only copies of cpuset.cpus and cpuset.mems files
+respectively. If the cpuset cgroup filesystem is mounted with the
+special "cpuset_v2_mode" option, the behavior of these files will become
+similar to the corresponding files in cpuset v2. In other words, hotplug
+events will not change cpuset.cpus and cpuset.mems. Those events will
+only affect cpuset.effective_cpus and cpuset.effective_mems which show
+the actual cpus and memory nodes that are currently used by this cpuset.
+See Documentation/admin-guide/cgroup-v2.rst for more information about
+cpuset v2 behavior.
+
+
+1.4 What are exclusive cpusets ?
+--------------------------------
+
+If a cpuset is cpu or mem exclusive, no other cpuset, other than
+a direct ancestor or descendant, may share any of the same CPUs or
+Memory Nodes.
+
+A cpuset that is cpuset.mem_exclusive *or* cpuset.mem_hardwall is "hardwalled",
+i.e. it restricts kernel allocations for page, buffer and other data
+commonly shared by the kernel across multiple users. All cpusets,
+whether hardwalled or not, restrict allocations of memory for user
+space. This enables configuring a system so that several independent
+jobs can share common kernel data, such as file system pages, while
+isolating each job's user allocation in its own cpuset. To do this,
+construct a large mem_exclusive cpuset to hold all the jobs, and
+construct child, non-mem_exclusive cpusets for each individual job.
+Only a small amount of typical kernel memory, such as requests from
+interrupt handlers, is allowed to be taken outside even a
+mem_exclusive cpuset.
+
+
+1.5 What is memory_pressure ?
+-----------------------------
+The memory_pressure of a cpuset provides a simple per-cpuset metric
+of the rate that the tasks in a cpuset are attempting to free up in
+use memory on the nodes of the cpuset to satisfy additional memory
+requests.
+
+This enables batch managers monitoring jobs running in dedicated
+cpusets to efficiently detect what level of memory pressure that job
+is causing.
+
+This is useful both on tightly managed systems running a wide mix of
+submitted jobs, which may choose to terminate or re-prioritize jobs that
+are trying to use more memory than allowed on the nodes assigned to them,
+and with tightly coupled, long running, massively parallel scientific
+computing jobs that will dramatically fail to meet required performance
+goals if they start to use more memory than allowed to them.
+
+This mechanism provides a very economical way for the batch manager
+to monitor a cpuset for signs of memory pressure. It's up to the
+batch manager or other user code to decide what to do about it and
+take action.
+
+==>
+ Unless this feature is enabled by writing "1" to the special file
+ /dev/cpuset/memory_pressure_enabled, the hook in the rebalance
+ code of __alloc_pages() for this metric reduces to simply noticing
+ that the cpuset_memory_pressure_enabled flag is zero. So only
+ systems that enable this feature will compute the metric.
+
+Why a per-cpuset, running average:
+
+ Because this meter is per-cpuset, rather than per-task or mm,
+ the system load imposed by a batch scheduler monitoring this
+ metric is sharply reduced on large systems, because a scan of
+ the tasklist can be avoided on each set of queries.
+
+ Because this meter is a running average, instead of an accumulating
+ counter, a batch scheduler can detect memory pressure with a
+ single read, instead of having to read and accumulate results
+ for a period of time.
+
+ Because this meter is per-cpuset rather than per-task or mm,
+ the batch scheduler can obtain the key information, memory
+ pressure in a cpuset, with a single read, rather than having to
+ query and accumulate results over all the (dynamically changing)
+ set of tasks in the cpuset.
+
+A per-cpuset simple digital filter (requires a spinlock and 3 words
+of data per-cpuset) is kept, and updated by any task attached to that
+cpuset, if it enters the synchronous (direct) page reclaim code.
+
+A per-cpuset file provides an integer number representing the recent
+(half-life of 10 seconds) rate of direct page reclaims caused by
+the tasks in the cpuset, in units of reclaims attempted per second,
+times 1000.
+
+
+1.6 What is memory spread ?
+---------------------------
+There are two boolean flag files per cpuset that control where the
+kernel allocates pages for the file system buffers and related in
+kernel data structures. They are called 'cpuset.memory_spread_page' and
+'cpuset.memory_spread_slab'.
+
+If the per-cpuset boolean flag file 'cpuset.memory_spread_page' is set, then
+the kernel will spread the file system buffers (page cache) evenly
+over all the nodes that the faulting task is allowed to use, instead
+of preferring to put those pages on the node where the task is running.
+
+If the per-cpuset boolean flag file 'cpuset.memory_spread_slab' is set,
+then the kernel will spread some file system related slab caches,
+such as for inodes and dentries evenly over all the nodes that the
+faulting task is allowed to use, instead of preferring to put those
+pages on the node where the task is running.
+
+The setting of these flags does not affect anonymous data segment or
+stack segment pages of a task.
+
+By default, both kinds of memory spreading are off, and memory
+pages are allocated on the node local to where the task is running,
+except perhaps as modified by the task's NUMA mempolicy or cpuset
+configuration, so long as sufficient free memory pages are available.
+
+When new cpusets are created, they inherit the memory spread settings
+of their parent.
+
+Setting memory spreading causes allocations for the affected page
+or slab caches to ignore the task's NUMA mempolicy and be spread
+instead. Tasks using mbind() or set_mempolicy() calls to set NUMA
+mempolicies will not notice any change in these calls as a result of
+their containing task's memory spread settings. If memory spreading
+is turned off, then the currently specified NUMA mempolicy once again
+applies to memory page allocations.
+
+Both 'cpuset.memory_spread_page' and 'cpuset.memory_spread_slab' are boolean flag
+files. By default they contain "0", meaning that the feature is off
+for that cpuset. If a "1" is written to that file, then that turns
+the named feature on.
+
+The implementation is simple.
+
+Setting the flag 'cpuset.memory_spread_page' turns on a per-process flag
+PFA_SPREAD_PAGE for each task that is in that cpuset or subsequently
+joins that cpuset. The page allocation calls for the page cache
+is modified to perform an inline check for this PFA_SPREAD_PAGE task
+flag, and if set, a call to a new routine cpuset_mem_spread_node()
+returns the node to prefer for the allocation.
+
+Similarly, setting 'cpuset.memory_spread_slab' turns on the flag
+PFA_SPREAD_SLAB, and appropriately marked slab caches will allocate
+pages from the node returned by cpuset_mem_spread_node().
+
+The cpuset_mem_spread_node() routine is also simple. It uses the
+value of a per-task rotor cpuset_mem_spread_rotor to select the next
+node in the current task's mems_allowed to prefer for the allocation.
+
+This memory placement policy is also known (in other contexts) as
+round-robin or interleave.
+
+This policy can provide substantial improvements for jobs that need
+to place thread local data on the corresponding node, but that need
+to access large file system data sets that need to be spread across
+the several nodes in the jobs cpuset in order to fit. Without this
+policy, especially for jobs that might have one thread reading in the
+data set, the memory allocation across the nodes in the jobs cpuset
+can become very uneven.
+
+1.7 What is sched_load_balance ?
+--------------------------------
+
+The kernel scheduler (kernel/sched/core.c) automatically load balances
+tasks. If one CPU is underutilized, kernel code running on that
+CPU will look for tasks on other more overloaded CPUs and move those
+tasks to itself, within the constraints of such placement mechanisms
+as cpusets and sched_setaffinity.
+
+The algorithmic cost of load balancing and its impact on key shared
+kernel data structures such as the task list increases more than
+linearly with the number of CPUs being balanced. So the scheduler
+has support to partition the systems CPUs into a number of sched
+domains such that it only load balances within each sched domain.
+Each sched domain covers some subset of the CPUs in the system;
+no two sched domains overlap; some CPUs might not be in any sched
+domain and hence won't be load balanced.
+
+Put simply, it costs less to balance between two smaller sched domains
+than one big one, but doing so means that overloads in one of the
+two domains won't be load balanced to the other one.
+
+By default, there is one sched domain covering all CPUs, including those
+marked isolated using the kernel boot time "isolcpus=" argument. However,
+the isolated CPUs will not participate in load balancing, and will not
+have tasks running on them unless explicitly assigned.
+
+This default load balancing across all CPUs is not well suited for
+the following two situations:
+
+ 1) On large systems, load balancing across many CPUs is expensive.
+ If the system is managed using cpusets to place independent jobs
+ on separate sets of CPUs, full load balancing is unnecessary.
+ 2) Systems supporting realtime on some CPUs need to minimize
+ system overhead on those CPUs, including avoiding task load
+ balancing if that is not needed.
+
+When the per-cpuset flag "cpuset.sched_load_balance" is enabled (the default
+setting), it requests that all the CPUs in that cpusets allowed 'cpuset.cpus'
+be contained in a single sched domain, ensuring that load balancing
+can move a task (not otherwised pinned, as by sched_setaffinity)
+from any CPU in that cpuset to any other.
+
+When the per-cpuset flag "cpuset.sched_load_balance" is disabled, then the
+scheduler will avoid load balancing across the CPUs in that cpuset,
+--except-- in so far as is necessary because some overlapping cpuset
+has "sched_load_balance" enabled.
+
+So, for example, if the top cpuset has the flag "cpuset.sched_load_balance"
+enabled, then the scheduler will have one sched domain covering all
+CPUs, and the setting of the "cpuset.sched_load_balance" flag in any other
+cpusets won't matter, as we're already fully load balancing.
+
+Therefore in the above two situations, the top cpuset flag
+"cpuset.sched_load_balance" should be disabled, and only some of the smaller,
+child cpusets have this flag enabled.
+
+When doing this, you don't usually want to leave any unpinned tasks in
+the top cpuset that might use non-trivial amounts of CPU, as such tasks
+may be artificially constrained to some subset of CPUs, depending on
+the particulars of this flag setting in descendant cpusets. Even if
+such a task could use spare CPU cycles in some other CPUs, the kernel
+scheduler might not consider the possibility of load balancing that
+task to that underused CPU.
+
+Of course, tasks pinned to a particular CPU can be left in a cpuset
+that disables "cpuset.sched_load_balance" as those tasks aren't going anywhere
+else anyway.
+
+There is an impedance mismatch here, between cpusets and sched domains.
+Cpusets are hierarchical and nest. Sched domains are flat; they don't
+overlap and each CPU is in at most one sched domain.
+
+It is necessary for sched domains to be flat because load balancing
+across partially overlapping sets of CPUs would risk unstable dynamics
+that would be beyond our understanding. So if each of two partially
+overlapping cpusets enables the flag 'cpuset.sched_load_balance', then we
+form a single sched domain that is a superset of both. We won't move
+a task to a CPU outside its cpuset, but the scheduler load balancing
+code might waste some compute cycles considering that possibility.
+
+This mismatch is why there is not a simple one-to-one relation
+between which cpusets have the flag "cpuset.sched_load_balance" enabled,
+and the sched domain configuration. If a cpuset enables the flag, it
+will get balancing across all its CPUs, but if it disables the flag,
+it will only be assured of no load balancing if no other overlapping
+cpuset enables the flag.
+
+If two cpusets have partially overlapping 'cpuset.cpus' allowed, and only
+one of them has this flag enabled, then the other may find its
+tasks only partially load balanced, just on the overlapping CPUs.
+This is just the general case of the top_cpuset example given a few
+paragraphs above. In the general case, as in the top cpuset case,
+don't leave tasks that might use non-trivial amounts of CPU in
+such partially load balanced cpusets, as they may be artificially
+constrained to some subset of the CPUs allowed to them, for lack of
+load balancing to the other CPUs.
+
+CPUs in "cpuset.isolcpus" were excluded from load balancing by the
+isolcpus= kernel boot option, and will never be load balanced regardless
+of the value of "cpuset.sched_load_balance" in any cpuset.
+
+1.7.1 sched_load_balance implementation details.
+------------------------------------------------
+
+The per-cpuset flag 'cpuset.sched_load_balance' defaults to enabled (contrary
+to most cpuset flags.) When enabled for a cpuset, the kernel will
+ensure that it can load balance across all the CPUs in that cpuset
+(makes sure that all the CPUs in the cpus_allowed of that cpuset are
+in the same sched domain.)
+
+If two overlapping cpusets both have 'cpuset.sched_load_balance' enabled,
+then they will be (must be) both in the same sched domain.
+
+If, as is the default, the top cpuset has 'cpuset.sched_load_balance' enabled,
+then by the above that means there is a single sched domain covering
+the whole system, regardless of any other cpuset settings.
+
+The kernel commits to user space that it will avoid load balancing
+where it can. It will pick as fine a granularity partition of sched
+domains as it can while still providing load balancing for any set
+of CPUs allowed to a cpuset having 'cpuset.sched_load_balance' enabled.
+
+The internal kernel cpuset to scheduler interface passes from the
+cpuset code to the scheduler code a partition of the load balanced
+CPUs in the system. This partition is a set of subsets (represented
+as an array of struct cpumask) of CPUs, pairwise disjoint, that cover
+all the CPUs that must be load balanced.
+
+The cpuset code builds a new such partition and passes it to the
+scheduler sched domain setup code, to have the sched domains rebuilt
+as necessary, whenever:
+
+ - the 'cpuset.sched_load_balance' flag of a cpuset with non-empty CPUs changes,
+ - or CPUs come or go from a cpuset with this flag enabled,
+ - or 'cpuset.sched_relax_domain_level' value of a cpuset with non-empty CPUs
+ and with this flag enabled changes,
+ - or a cpuset with non-empty CPUs and with this flag enabled is removed,
+ - or a cpu is offlined/onlined.
+
+This partition exactly defines what sched domains the scheduler should
+setup - one sched domain for each element (struct cpumask) in the
+partition.
+
+The scheduler remembers the currently active sched domain partitions.
+When the scheduler routine partition_sched_domains() is invoked from
+the cpuset code to update these sched domains, it compares the new
+partition requested with the current, and updates its sched domains,
+removing the old and adding the new, for each change.
+
+
+1.8 What is sched_relax_domain_level ?
+--------------------------------------
+
+In sched domain, the scheduler migrates tasks in 2 ways; periodic load
+balance on tick, and at time of some schedule events.
+
+When a task is woken up, scheduler try to move the task on idle CPU.
+For example, if a task A running on CPU X activates another task B
+on the same CPU X, and if CPU Y is X's sibling and performing idle,
+then scheduler migrate task B to CPU Y so that task B can start on
+CPU Y without waiting task A on CPU X.
+
+And if a CPU run out of tasks in its runqueue, the CPU try to pull
+extra tasks from other busy CPUs to help them before it is going to
+be idle.
+
+Of course it takes some searching cost to find movable tasks and/or
+idle CPUs, the scheduler might not search all CPUs in the domain
+every time. In fact, in some architectures, the searching ranges on
+events are limited in the same socket or node where the CPU locates,
+while the load balance on tick searches all.
+
+For example, assume CPU Z is relatively far from CPU X. Even if CPU Z
+is idle while CPU X and the siblings are busy, scheduler can't migrate
+woken task B from X to Z since it is out of its searching range.
+As the result, task B on CPU X need to wait task A or wait load balance
+on the next tick. For some applications in special situation, waiting
+1 tick may be too long.
+
+The 'cpuset.sched_relax_domain_level' file allows you to request changing
+this searching range as you like. This file takes int value which
+indicates size of searching range in levels approximately as follows,
+otherwise initial value -1 that indicates the cpuset has no request.
+
+====== ===========================================================
+ -1 no request. use system default or follow request of others.
+ 0 no search.
+ 1 search siblings (hyperthreads in a core).
+ 2 search cores in a package.
+ 3 search cpus in a node [= system wide on non-NUMA system]
+ 4 search nodes in a chunk of node [on NUMA system]
+ 5 search system wide [on NUMA system]
+====== ===========================================================
+
+Not all levels can be present and values can change depending on the
+system architecture and kernel configuration. Check
+/sys/kernel/debug/sched/domains/cpu*/domain*/ for system-specific
+details.
+
+The system default is architecture dependent. The system default
+can be changed using the relax_domain_level= boot parameter.
+
+This file is per-cpuset and affect the sched domain where the cpuset
+belongs to. Therefore if the flag 'cpuset.sched_load_balance' of a cpuset
+is disabled, then 'cpuset.sched_relax_domain_level' have no effect since
+there is no sched domain belonging the cpuset.
+
+If multiple cpusets are overlapping and hence they form a single sched
+domain, the largest value among those is used. Be careful, if one
+requests 0 and others are -1 then 0 is used.
+
+Note that modifying this file will have both good and bad effects,
+and whether it is acceptable or not depends on your situation.
+Don't modify this file if you are not sure.
+
+If your situation is:
+
+ - The migration costs between each cpu can be assumed considerably
+ small(for you) due to your special application's behavior or
+ special hardware support for CPU cache etc.
+ - The searching cost doesn't have impact(for you) or you can make
+ the searching cost enough small by managing cpuset to compact etc.
+ - The latency is required even it sacrifices cache hit rate etc.
+ then increasing 'sched_relax_domain_level' would benefit you.
+
+
+1.9 How do I use cpusets ?
+--------------------------
+
+In order to minimize the impact of cpusets on critical kernel
+code, such as the scheduler, and due to the fact that the kernel
+does not support one task updating the memory placement of another
+task directly, the impact on a task of changing its cpuset CPU
+or Memory Node placement, or of changing to which cpuset a task
+is attached, is subtle.
+
+If a cpuset has its Memory Nodes modified, then for each task attached
+to that cpuset, the next time that the kernel attempts to allocate
+a page of memory for that task, the kernel will notice the change
+in the task's cpuset, and update its per-task memory placement to
+remain within the new cpusets memory placement. If the task was using
+mempolicy MPOL_BIND, and the nodes to which it was bound overlap with
+its new cpuset, then the task will continue to use whatever subset
+of MPOL_BIND nodes are still allowed in the new cpuset. If the task
+was using MPOL_BIND and now none of its MPOL_BIND nodes are allowed
+in the new cpuset, then the task will be essentially treated as if it
+was MPOL_BIND bound to the new cpuset (even though its NUMA placement,
+as queried by get_mempolicy(), doesn't change). If a task is moved
+from one cpuset to another, then the kernel will adjust the task's
+memory placement, as above, the next time that the kernel attempts
+to allocate a page of memory for that task.
+
+If a cpuset has its 'cpuset.cpus' modified, then each task in that cpuset
+will have its allowed CPU placement changed immediately. Similarly,
+if a task's pid is written to another cpuset's 'tasks' file, then its
+allowed CPU placement is changed immediately. If such a task had been
+bound to some subset of its cpuset using the sched_setaffinity() call,
+the task will be allowed to run on any CPU allowed in its new cpuset,
+negating the effect of the prior sched_setaffinity() call.
+
+In summary, the memory placement of a task whose cpuset is changed is
+updated by the kernel, on the next allocation of a page for that task,
+and the processor placement is updated immediately.
+
+Normally, once a page is allocated (given a physical page
+of main memory) then that page stays on whatever node it
+was allocated, so long as it remains allocated, even if the
+cpusets memory placement policy 'cpuset.mems' subsequently changes.
+If the cpuset flag file 'cpuset.memory_migrate' is set true, then when
+tasks are attached to that cpuset, any pages that task had
+allocated to it on nodes in its previous cpuset are migrated
+to the task's new cpuset. The relative placement of the page within
+the cpuset is preserved during these migration operations if possible.
+For example if the page was on the second valid node of the prior cpuset
+then the page will be placed on the second valid node of the new cpuset.
+
+Also if 'cpuset.memory_migrate' is set true, then if that cpuset's
+'cpuset.mems' file is modified, pages allocated to tasks in that
+cpuset, that were on nodes in the previous setting of 'cpuset.mems',
+will be moved to nodes in the new setting of 'mems.'
+Pages that were not in the task's prior cpuset, or in the cpuset's
+prior 'cpuset.mems' setting, will not be moved.
+
+There is an exception to the above. If hotplug functionality is used
+to remove all the CPUs that are currently assigned to a cpuset,
+then all the tasks in that cpuset will be moved to the nearest ancestor
+with non-empty cpus. But the moving of some (or all) tasks might fail if
+cpuset is bound with another cgroup subsystem which has some restrictions
+on task attaching. In this failing case, those tasks will stay
+in the original cpuset, and the kernel will automatically update
+their cpus_allowed to allow all online CPUs. When memory hotplug
+functionality for removing Memory Nodes is available, a similar exception
+is expected to apply there as well. In general, the kernel prefers to
+violate cpuset placement, over starving a task that has had all
+its allowed CPUs or Memory Nodes taken offline.
+
+There is a second exception to the above. GFP_ATOMIC requests are
+kernel internal allocations that must be satisfied, immediately.
+The kernel may drop some request, in rare cases even panic, if a
+GFP_ATOMIC alloc fails. If the request cannot be satisfied within
+the current task's cpuset, then we relax the cpuset, and look for
+memory anywhere we can find it. It's better to violate the cpuset
+than stress the kernel.
+
+To start a new job that is to be contained within a cpuset, the steps are:
+
+ 1) mkdir /sys/fs/cgroup/cpuset
+ 2) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
+ 3) Create the new cpuset by doing mkdir's and write's (or echo's) in
+ the /sys/fs/cgroup/cpuset virtual file system.
+ 4) Start a task that will be the "founding father" of the new job.
+ 5) Attach that task to the new cpuset by writing its pid to the
+ /sys/fs/cgroup/cpuset tasks file for that cpuset.
+ 6) fork, exec or clone the job tasks from this founding father task.
+
+For example, the following sequence of commands will setup a cpuset
+named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
+and then start a subshell 'sh' in that cpuset::
+
+ mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
+ cd /sys/fs/cgroup/cpuset
+ mkdir Charlie
+ cd Charlie
+ /bin/echo 2-3 > cpuset.cpus
+ /bin/echo 1 > cpuset.mems
+ /bin/echo $$ > tasks
+ sh
+ # The subshell 'sh' is now running in cpuset Charlie
+ # The next line should display '/Charlie'
+ cat /proc/self/cpuset
+
+There are ways to query or modify cpusets:
+
+ - via the cpuset file system directly, using the various cd, mkdir, echo,
+ cat, rmdir commands from the shell, or their equivalent from C.
+ - via the C library libcpuset.
+ - via the C library libcgroup.
+ (https://github.com/libcgroup/libcgroup/)
+ - via the python application cset.
+ (http://code.google.com/p/cpuset/)
+
+The sched_setaffinity calls can also be done at the shell prompt using
+SGI's runon or Robert Love's taskset. The mbind and set_mempolicy
+calls can be done at the shell prompt using the numactl command
+(part of Andi Kleen's numa package).
+
+2. Usage Examples and Syntax
+============================
+
+2.1 Basic Usage
+---------------
+
+Creating, modifying, using the cpusets can be done through the cpuset
+virtual filesystem.
+
+To mount it, type:
+# mount -t cgroup -o cpuset cpuset /sys/fs/cgroup/cpuset
+
+Then under /sys/fs/cgroup/cpuset you can find a tree that corresponds to the
+tree of the cpusets in the system. For instance, /sys/fs/cgroup/cpuset
+is the cpuset that holds the whole system.
+
+If you want to create a new cpuset under /sys/fs/cgroup/cpuset::
+
+ # cd /sys/fs/cgroup/cpuset
+ # mkdir my_cpuset
+
+Now you want to do something with this cpuset::
+
+ # cd my_cpuset
+
+In this directory you can find several files::
+
+ # ls
+ cgroup.clone_children cpuset.memory_pressure
+ cgroup.event_control cpuset.memory_spread_page
+ cgroup.procs cpuset.memory_spread_slab
+ cpuset.cpu_exclusive cpuset.mems
+ cpuset.cpus cpuset.sched_load_balance
+ cpuset.mem_exclusive cpuset.sched_relax_domain_level
+ cpuset.mem_hardwall notify_on_release
+ cpuset.memory_migrate tasks
+
+Reading them will give you information about the state of this cpuset:
+the CPUs and Memory Nodes it can use, the processes that are using
+it, its properties. By writing to these files you can manipulate
+the cpuset.
+
+Set some flags::
+
+ # /bin/echo 1 > cpuset.cpu_exclusive
+
+Add some cpus::
+
+ # /bin/echo 0-7 > cpuset.cpus
+
+Add some mems::
+
+ # /bin/echo 0-7 > cpuset.mems
+
+Now attach your shell to this cpuset::
+
+ # /bin/echo $$ > tasks
+
+You can also create cpusets inside your cpuset by using mkdir in this
+directory::
+
+ # mkdir my_sub_cs
+
+To remove a cpuset, just use rmdir::
+
+ # rmdir my_sub_cs
+
+This will fail if the cpuset is in use (has cpusets inside, or has
+processes attached).
+
+Note that for legacy reasons, the "cpuset" filesystem exists as a
+wrapper around the cgroup filesystem.
+
+The command::
+
+ mount -t cpuset X /sys/fs/cgroup/cpuset
+
+is equivalent to::
+
+ mount -t cgroup -ocpuset,noprefix X /sys/fs/cgroup/cpuset
+ echo "/sbin/cpuset_release_agent" > /sys/fs/cgroup/cpuset/release_agent
+
+2.2 Adding/removing cpus
+------------------------
+
+This is the syntax to use when writing in the cpus or mems files
+in cpuset directories::
+
+ # /bin/echo 1-4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
+ # /bin/echo 1,2,3,4 > cpuset.cpus -> set cpus list to cpus 1,2,3,4
+
+To add a CPU to a cpuset, write the new list of CPUs including the
+CPU to be added. To add 6 to the above cpuset::
+
+ # /bin/echo 1-4,6 > cpuset.cpus -> set cpus list to cpus 1,2,3,4,6
+
+Similarly to remove a CPU from a cpuset, write the new list of CPUs
+without the CPU to be removed.
+
+To remove all the CPUs::
+
+ # /bin/echo "" > cpuset.cpus -> clear cpus list
+
+2.3 Setting flags
+-----------------
+
+The syntax is very simple::
+
+ # /bin/echo 1 > cpuset.cpu_exclusive -> set flag 'cpuset.cpu_exclusive'
+ # /bin/echo 0 > cpuset.cpu_exclusive -> unset flag 'cpuset.cpu_exclusive'
+
+2.4 Attaching processes
+-----------------------
+
+::
+
+ # /bin/echo PID > tasks
+
+Note that it is PID, not PIDs. You can only attach ONE task at a time.
+If you have several tasks to attach, you have to do it one after another::
+
+ # /bin/echo PID1 > tasks
+ # /bin/echo PID2 > tasks
+ ...
+ # /bin/echo PIDn > tasks
+
+
+3. Questions
+============
+
+Q:
+ what's up with this '/bin/echo' ?
+
+A:
+ bash's builtin 'echo' command does not check calls to write() against
+ errors. If you use it in the cpuset file system, you won't be
+ able to tell whether a command succeeded or failed.
+
+Q:
+ When I attach processes, only the first of the line gets really attached !
+
+A:
+ We can only return one error code per call to write(). So you should also
+ put only ONE pid.
+
+4. Contact
+==========
+
+Web: http://www.bullopensource.org/cpuset
diff --git a/Documentation/admin-guide/cgroup-v1/devices.rst b/Documentation/admin-guide/cgroup-v1/devices.rst
new file mode 100644
index 000000000000..e1886783961e
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/devices.rst
@@ -0,0 +1,132 @@
+===========================
+Device Whitelist Controller
+===========================
+
+1. Description
+==============
+
+Implement a cgroup to track and enforce open and mknod restrictions
+on device files. A device cgroup associates a device access
+whitelist with each cgroup. A whitelist entry has 4 fields.
+'type' is a (all), c (char), or b (block). 'all' means it applies
+to all types and all major and minor numbers. Major and minor are
+either an integer or * for all. Access is a composition of r
+(read), w (write), and m (mknod).
+
+The root device cgroup starts with rwm to 'all'. A child device
+cgroup gets a copy of the parent. Administrators can then remove
+devices from the whitelist or add new entries. A child cgroup can
+never receive a device access which is denied by its parent.
+
+2. User Interface
+=================
+
+An entry is added using devices.allow, and removed using
+devices.deny. For instance::
+
+ echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
+
+allows cgroup 1 to read and mknod the device usually known as
+/dev/null. Doing::
+
+ echo a > /sys/fs/cgroup/1/devices.deny
+
+will remove the default 'a *:* rwm' entry. Doing::
+
+ echo a > /sys/fs/cgroup/1/devices.allow
+
+will add the 'a *:* rwm' entry to the whitelist.
+
+3. Security
+===========
+
+Any task can move itself between cgroups. This clearly won't
+suffice, but we can decide the best way to adequately restrict
+movement as people get some experience with this. We may just want
+to require CAP_SYS_ADMIN, which at least is a separate bit from
+CAP_MKNOD. We may want to just refuse moving to a cgroup which
+isn't a descendant of the current one. Or we may want to use
+CAP_MAC_ADMIN, since we really are trying to lock down root.
+
+CAP_SYS_ADMIN is needed to modify the whitelist or move another
+task to a new cgroup. (Again we'll probably want to change that).
+
+A cgroup may not be granted more permissions than the cgroup's
+parent has.
+
+4. Hierarchy
+============
+
+device cgroups maintain hierarchy by making sure a cgroup never has more
+access permissions than its parent. Every time an entry is written to
+a cgroup's devices.deny file, all its children will have that entry removed
+from their whitelist and all the locally set whitelist entries will be
+re-evaluated. In case one of the locally set whitelist entries would provide
+more access than the cgroup's parent, it'll be removed from the whitelist.
+
+Example::
+
+ A
+ / \
+ B
+
+ group behavior exceptions
+ A allow "b 8:* rwm", "c 116:1 rw"
+ B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
+
+If a device is denied in group A::
+
+ # echo "c 116:* r" > A/devices.deny
+
+it'll propagate down and after revalidating B's entries, the whitelist entry
+"c 116:2 rwm" will be removed::
+
+ group whitelist entries denied devices
+ A all "b 8:* rwm", "c 116:* rw"
+ B "c 1:3 rwm", "b 3:* rwm" all the rest
+
+In case parent's exceptions change and local exceptions are not allowed
+anymore, they'll be deleted.
+
+Notice that new whitelist entries will not be propagated::
+
+ A
+ / \
+ B
+
+ group whitelist entries denied devices
+ A "c 1:3 rwm", "c 1:5 r" all the rest
+ B "c 1:3 rwm", "c 1:5 r" all the rest
+
+when adding ``c *:3 rwm``::
+
+ # echo "c *:3 rwm" >A/devices.allow
+
+the result::
+
+ group whitelist entries denied devices
+ A "c *:3 rwm", "c 1:5 r" all the rest
+ B "c 1:3 rwm", "c 1:5 r" all the rest
+
+but now it'll be possible to add new entries to B::
+
+ # echo "c 2:3 rwm" >B/devices.allow
+ # echo "c 50:3 r" >B/devices.allow
+
+or even::
+
+ # echo "c *:3 rwm" >B/devices.allow
+
+Allowing or denying all by writing 'a' to devices.allow or devices.deny will
+not be possible once the device cgroups has children.
+
+4.1 Hierarchy (internal implementation)
+---------------------------------------
+
+device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
+list of exceptions. The internal state is controlled using the same user
+interface to preserve compatibility with the previous whitelist-only
+implementation. Removal or addition of exceptions that will reduce the access
+to devices will be propagated down the hierarchy.
+For every propagated exception, the effective rules will be re-evaluated based
+on current parent's access rules.
diff --git a/Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst b/Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst
new file mode 100644
index 000000000000..a964aff373b1
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst
@@ -0,0 +1,131 @@
+==============
+Cgroup Freezer
+==============
+
+The cgroup freezer is useful to batch job management system which start
+and stop sets of tasks in order to schedule the resources of a machine
+according to the desires of a system administrator. This sort of program
+is often used on HPC clusters to schedule access to the cluster as a
+whole. The cgroup freezer uses cgroups to describe the set of tasks to
+be started/stopped by the batch job management system. It also provides
+a means to start and stop the tasks composing the job.
+
+The cgroup freezer will also be useful for checkpointing running groups
+of tasks. The freezer allows the checkpoint code to obtain a consistent
+image of the tasks by attempting to force the tasks in a cgroup into a
+quiescent state. Once the tasks are quiescent another task can
+walk /proc or invoke a kernel interface to gather information about the
+quiesced tasks. Checkpointed tasks can be restarted later should a
+recoverable error occur. This also allows the checkpointed tasks to be
+migrated between nodes in a cluster by copying the gathered information
+to another node and restarting the tasks there.
+
+Sequences of SIGSTOP and SIGCONT are not always sufficient for stopping
+and resuming tasks in userspace. Both of these signals are observable
+from within the tasks we wish to freeze. While SIGSTOP cannot be caught,
+blocked, or ignored it can be seen by waiting or ptracing parent tasks.
+SIGCONT is especially unsuitable since it can be caught by the task. Any
+programs designed to watch for SIGSTOP and SIGCONT could be broken by
+attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can
+demonstrate this problem using nested bash shells::
+
+ $ echo $$
+ 16644
+ $ bash
+ $ echo $$
+ 16690
+
+ From a second, unrelated bash shell:
+ $ kill -SIGSTOP 16690
+ $ kill -SIGCONT 16690
+
+ <at this point 16690 exits and causes 16644 to exit too>
+
+This happens because bash can observe both signals and choose how it
+responds to them.
+
+Another example of a program which catches and responds to these
+signals is gdb. In fact any program designed to use ptrace is likely to
+have a problem with this method of stopping and resuming tasks.
+
+In contrast, the cgroup freezer uses the kernel freezer code to
+prevent the freeze/unfreeze cycle from becoming visible to the tasks
+being frozen. This allows the bash example above and gdb to run as
+expected.
+
+The cgroup freezer is hierarchical. Freezing a cgroup freezes all
+tasks belonging to the cgroup and all its descendant cgroups. Each
+cgroup has its own state (self-state) and the state inherited from the
+parent (parent-state). Iff both states are THAWED, the cgroup is
+THAWED.
+
+The following cgroupfs files are created by cgroup freezer.
+
+* freezer.state: Read-write.
+
+ When read, returns the effective state of the cgroup - "THAWED",
+ "FREEZING" or "FROZEN". This is the combined self and parent-states.
+ If any is freezing, the cgroup is freezing (FREEZING or FROZEN).
+
+ FREEZING cgroup transitions into FROZEN state when all tasks
+ belonging to the cgroup and its descendants become frozen. Note that
+ a cgroup reverts to FREEZING from FROZEN after a new task is added
+ to the cgroup or one of its descendant cgroups until the new task is
+ frozen.
+
+ When written, sets the self-state of the cgroup. Two values are
+ allowed - "FROZEN" and "THAWED". If FROZEN is written, the cgroup,
+ if not already freezing, enters FREEZING state along with all its
+ descendant cgroups.
+
+ If THAWED is written, the self-state of the cgroup is changed to
+ THAWED. Note that the effective state may not change to THAWED if
+ the parent-state is still freezing. If a cgroup's effective state
+ becomes THAWED, all its descendants which are freezing because of
+ the cgroup also leave the freezing state.
+
+* freezer.self_freezing: Read only.
+
+ Shows the self-state. 0 if the self-state is THAWED; otherwise, 1.
+ This value is 1 iff the last write to freezer.state was "FROZEN".
+
+* freezer.parent_freezing: Read only.
+
+ Shows the parent-state. 0 if none of the cgroup's ancestors is
+ frozen; otherwise, 1.
+
+The root cgroup is non-freezable and the above interface files don't
+exist.
+
+* Examples of usage::
+
+ # mkdir /sys/fs/cgroup/freezer
+ # mount -t cgroup -ofreezer freezer /sys/fs/cgroup/freezer
+ # mkdir /sys/fs/cgroup/freezer/0
+ # echo $some_pid > /sys/fs/cgroup/freezer/0/tasks
+
+to get status of the freezer subsystem::
+
+ # cat /sys/fs/cgroup/freezer/0/freezer.state
+ THAWED
+
+to freeze all tasks in the container::
+
+ # echo FROZEN > /sys/fs/cgroup/freezer/0/freezer.state
+ # cat /sys/fs/cgroup/freezer/0/freezer.state
+ FREEZING
+ # cat /sys/fs/cgroup/freezer/0/freezer.state
+ FROZEN
+
+to unfreeze all tasks in the container::
+
+ # echo THAWED > /sys/fs/cgroup/freezer/0/freezer.state
+ # cat /sys/fs/cgroup/freezer/0/freezer.state
+ THAWED
+
+This is the basic mechanism which should do the right thing for user space task
+in a simple scenario.
+
+This freezer implementation is affected by shortcomings (see commit
+76f969e8948d8 ("cgroup: cgroup v2 freezer")) and cgroup v2 freezer is
+recommended.
diff --git a/Documentation/admin-guide/cgroup-v1/hugetlb.rst b/Documentation/admin-guide/cgroup-v1/hugetlb.rst
new file mode 100644
index 000000000000..493a8e386700
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/hugetlb.rst
@@ -0,0 +1,139 @@
+==================
+HugeTLB Controller
+==================
+
+HugeTLB controller can be created by first mounting the cgroup filesystem.
+
+# mount -t cgroup -o hugetlb none /sys/fs/cgroup
+
+With the above step, the initial or the parent HugeTLB group becomes
+visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
+the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
+
+New groups can be created under the parent group /sys/fs/cgroup::
+
+ # cd /sys/fs/cgroup
+ # mkdir g1
+ # echo $$ > g1/tasks
+
+The above steps create a new group g1 and move the current shell
+process (bash) into it.
+
+Brief summary of control files::
+
+ hugetlb.<hugepagesize>.rsvd.limit_in_bytes # set/show limit of "hugepagesize" hugetlb reservations
+ hugetlb.<hugepagesize>.rsvd.max_usage_in_bytes # show max "hugepagesize" hugetlb reservations and no-reserve faults
+ hugetlb.<hugepagesize>.rsvd.usage_in_bytes # show current reservations and no-reserve faults for "hugepagesize" hugetlb
+ hugetlb.<hugepagesize>.rsvd.failcnt # show the number of allocation failure due to HugeTLB reservation limit
+ hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb faults
+ hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded
+ hugetlb.<hugepagesize>.usage_in_bytes # show current usage for "hugepagesize" hugetlb
+ hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB usage limit
+ hugetlb.<hugepagesize>.numa_stat # show the numa information of the hugetlb memory charged to this cgroup
+
+For a system supporting three hugepage sizes (64k, 32M and 1G), the control
+files include::
+
+ hugetlb.1GB.limit_in_bytes
+ hugetlb.1GB.max_usage_in_bytes
+ hugetlb.1GB.numa_stat
+ hugetlb.1GB.usage_in_bytes
+ hugetlb.1GB.failcnt
+ hugetlb.1GB.rsvd.limit_in_bytes
+ hugetlb.1GB.rsvd.max_usage_in_bytes
+ hugetlb.1GB.rsvd.usage_in_bytes
+ hugetlb.1GB.rsvd.failcnt
+ hugetlb.64KB.limit_in_bytes
+ hugetlb.64KB.max_usage_in_bytes
+ hugetlb.64KB.numa_stat
+ hugetlb.64KB.usage_in_bytes
+ hugetlb.64KB.failcnt
+ hugetlb.64KB.rsvd.limit_in_bytes
+ hugetlb.64KB.rsvd.max_usage_in_bytes
+ hugetlb.64KB.rsvd.usage_in_bytes
+ hugetlb.64KB.rsvd.failcnt
+ hugetlb.32MB.limit_in_bytes
+ hugetlb.32MB.max_usage_in_bytes
+ hugetlb.32MB.numa_stat
+ hugetlb.32MB.usage_in_bytes
+ hugetlb.32MB.failcnt
+ hugetlb.32MB.rsvd.limit_in_bytes
+ hugetlb.32MB.rsvd.max_usage_in_bytes
+ hugetlb.32MB.rsvd.usage_in_bytes
+ hugetlb.32MB.rsvd.failcnt
+
+
+1. Page fault accounting
+
+::
+
+ hugetlb.<hugepagesize>.limit_in_bytes
+ hugetlb.<hugepagesize>.max_usage_in_bytes
+ hugetlb.<hugepagesize>.usage_in_bytes
+ hugetlb.<hugepagesize>.failcnt
+
+The HugeTLB controller allows users to limit the HugeTLB usage (page fault) per
+control group and enforces the limit during page fault. Since HugeTLB
+doesn't support page reclaim, enforcing the limit at page fault time implies
+that, the application will get SIGBUS signal if it tries to fault in HugeTLB
+pages beyond its limit. Therefore the application needs to know exactly how many
+HugeTLB pages it uses before hand, and the sysadmin needs to make sure that
+there are enough available on the machine for all the users to avoid processes
+getting SIGBUS.
+
+
+2. Reservation accounting
+
+::
+
+ hugetlb.<hugepagesize>.rsvd.limit_in_bytes
+ hugetlb.<hugepagesize>.rsvd.max_usage_in_bytes
+ hugetlb.<hugepagesize>.rsvd.usage_in_bytes
+ hugetlb.<hugepagesize>.rsvd.failcnt
+
+The HugeTLB controller allows to limit the HugeTLB reservations per control
+group and enforces the controller limit at reservation time and at the fault of
+HugeTLB memory for which no reservation exists. Since reservation limits are
+enforced at reservation time (on mmap or shget), reservation limits never causes
+the application to get SIGBUS signal if the memory was reserved before hand. For
+MAP_NORESERVE allocations, the reservation limit behaves the same as the fault
+limit, enforcing memory usage at fault time and causing the application to
+receive a SIGBUS if it's crossing its limit.
+
+Reservation limits are superior to page fault limits described above, since
+reservation limits are enforced at reservation time (on mmap or shget), and
+never causes the application to get SIGBUS signal if the memory was reserved
+before hand. This allows for easier fallback to alternatives such as
+non-HugeTLB memory for example. In the case of page fault accounting, it's very
+hard to avoid processes getting SIGBUS since the sysadmin needs precisely know
+the HugeTLB usage of all the tasks in the system and make sure there is enough
+pages to satisfy all requests. Avoiding tasks getting SIGBUS on overcommited
+systems is practically impossible with page fault accounting.
+
+
+3. Caveats with shared memory
+
+For shared HugeTLB memory, both HugeTLB reservation and page faults are charged
+to the first task that causes the memory to be reserved or faulted, and all
+subsequent uses of this reserved or faulted memory is done without charging.
+
+Shared HugeTLB memory is only uncharged when it is unreserved or deallocated.
+This is usually when the HugeTLB file is deleted, and not when the task that
+caused the reservation or fault has exited.
+
+
+4. Caveats with HugeTLB cgroup offline.
+
+When a HugeTLB cgroup goes offline with some reservations or faults still
+charged to it, the behavior is as follows:
+
+- The fault charges are charged to the parent HugeTLB cgroup (reparented),
+- the reservation charges remain on the offline HugeTLB cgroup.
+
+This means that if a HugeTLB cgroup gets offlined while there is still HugeTLB
+reservations charged to it, that cgroup persists as a zombie until all HugeTLB
+reservations are uncharged. HugeTLB reservations behave in this manner to match
+the memory controller whose cgroups also persist as zombie until all charged
+memory is uncharged. Also, the tracking of HugeTLB reservations is a bit more
+complex compared to the tracking of HugeTLB faults, so it is significantly
+harder to reparent reservations at offline time.
diff --git a/Documentation/admin-guide/cgroup-v1/index.rst b/Documentation/admin-guide/cgroup-v1/index.rst
new file mode 100644
index 000000000000..99fbc8a64ba9
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/index.rst
@@ -0,0 +1,31 @@
+.. _cgroup-v1:
+
+========================
+Control Groups version 1
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ cgroups
+
+ blkio-controller
+ cpuacct
+ cpusets
+ devices
+ freezer-subsystem
+ hugetlb
+ memcg_test
+ memory
+ misc
+ net_cls
+ net_prio
+ pids
+ rdma
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/cgroup-v1/memcg_test.rst b/Documentation/admin-guide/cgroup-v1/memcg_test.rst
new file mode 100644
index 000000000000..9f8e27355cba
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/memcg_test.rst
@@ -0,0 +1,344 @@
+=====================================================
+Memory Resource Controller(Memcg) Implementation Memo
+=====================================================
+
+Last Updated: 2010/2
+
+Base Kernel Version: based on 2.6.33-rc7-mm(candidate for 34).
+
+Because VM is getting complex (one of reasons is memcg...), memcg's behavior
+is complex. This is a document for memcg's internal behavior.
+Please note that implementation details can be changed.
+
+(*) Topics on API should be in Documentation/admin-guide/cgroup-v1/memory.rst)
+
+0. How to record usage ?
+========================
+
+ 2 objects are used.
+
+ page_cgroup ....an object per page.
+
+ Allocated at boot or memory hotplug. Freed at memory hot removal.
+
+ swap_cgroup ... an entry per swp_entry.
+
+ Allocated at swapon(). Freed at swapoff().
+
+ The page_cgroup has USED bit and double count against a page_cgroup never
+ occurs. swap_cgroup is used only when a charged page is swapped-out.
+
+1. Charge
+=========
+
+ a page/swp_entry may be charged (usage += PAGE_SIZE) at
+
+ mem_cgroup_try_charge()
+
+2. Uncharge
+===========
+
+ a page/swp_entry may be uncharged (usage -= PAGE_SIZE) by
+
+ mem_cgroup_uncharge()
+ Called when a page's refcount goes down to 0.
+
+ mem_cgroup_uncharge_swap()
+ Called when swp_entry's refcnt goes down to 0. A charge against swap
+ disappears.
+
+3. charge-commit-cancel
+=======================
+
+ Memcg pages are charged in two steps:
+
+ - mem_cgroup_try_charge()
+ - mem_cgroup_commit_charge() or mem_cgroup_cancel_charge()
+
+ At try_charge(), there are no flags to say "this page is charged".
+ at this point, usage += PAGE_SIZE.
+
+ At commit(), the page is associated with the memcg.
+
+ At cancel(), simply usage -= PAGE_SIZE.
+
+Under below explanation, we assume CONFIG_SWAP=y.
+
+4. Anonymous
+============
+
+ Anonymous page is newly allocated at
+ - page fault into MAP_ANONYMOUS mapping.
+ - Copy-On-Write.
+
+ 4.1 Swap-in.
+ At swap-in, the page is taken from swap-cache. There are 2 cases.
+
+ (a) If the SwapCache is newly allocated and read, it has no charges.
+ (b) If the SwapCache has been mapped by processes, it has been
+ charged already.
+
+ 4.2 Swap-out.
+ At swap-out, typical state transition is below.
+
+ (a) add to swap cache. (marked as SwapCache)
+ swp_entry's refcnt += 1.
+ (b) fully unmapped.
+ swp_entry's refcnt += # of ptes.
+ (c) write back to swap.
+ (d) delete from swap cache. (remove from SwapCache)
+ swp_entry's refcnt -= 1.
+
+
+ Finally, at task exit,
+ (e) zap_pte() is called and swp_entry's refcnt -=1 -> 0.
+
+5. Page Cache
+=============
+
+ Page Cache is charged at
+ - filemap_add_folio().
+
+ The logic is very clear. (About migration, see below)
+
+ Note:
+ __filemap_remove_folio() is called by filemap_remove_folio()
+ and __remove_mapping().
+
+6. Shmem(tmpfs) Page Cache
+===========================
+
+ The best way to understand shmem's page state transition is to read
+ mm/shmem.c.
+
+ But brief explanation of the behavior of memcg around shmem will be
+ helpful to understand the logic.
+
+ Shmem's page (just leaf page, not direct/indirect block) can be on
+
+ - radix-tree of shmem's inode.
+ - SwapCache.
+ - Both on radix-tree and SwapCache. This happens at swap-in
+ and swap-out,
+
+ It's charged when...
+
+ - A new page is added to shmem's radix-tree.
+ - A swp page is read. (move a charge from swap_cgroup to page_cgroup)
+
+7. Page Migration
+=================
+
+ mem_cgroup_migrate()
+
+8. LRU
+======
+ Each memcg has its own vector of LRUs (inactive anon, active anon,
+ inactive file, active file, unevictable) of pages from each node,
+ each LRU handled under a single lru_lock for that memcg and node.
+
+9. Typical Tests.
+=================
+
+ Tests for racy cases.
+
+9.1 Small limit to memcg.
+-------------------------
+
+ When you do test to do racy case, it's good test to set memcg's limit
+ to be very small rather than GB. Many races found in the test under
+ xKB or xxMB limits.
+
+ (Memory behavior under GB and Memory behavior under MB shows very
+ different situation.)
+
+9.2 Shmem
+---------
+
+ Historically, memcg's shmem handling was poor and we saw some amount
+ of troubles here. This is because shmem is page-cache but can be
+ SwapCache. Test with shmem/tmpfs is always good test.
+
+9.3 Migration
+-------------
+
+ For NUMA, migration is an another special case. To do easy test, cpuset
+ is useful. Following is a sample script to do migration::
+
+ mount -t cgroup -o cpuset none /opt/cpuset
+
+ mkdir /opt/cpuset/01
+ echo 1 > /opt/cpuset/01/cpuset.cpus
+ echo 0 > /opt/cpuset/01/cpuset.mems
+ echo 1 > /opt/cpuset/01/cpuset.memory_migrate
+ mkdir /opt/cpuset/02
+ echo 1 > /opt/cpuset/02/cpuset.cpus
+ echo 1 > /opt/cpuset/02/cpuset.mems
+ echo 1 > /opt/cpuset/02/cpuset.memory_migrate
+
+ In above set, when you moves a task from 01 to 02, page migration to
+ node 0 to node 1 will occur. Following is a script to migrate all
+ under cpuset.::
+
+ --
+ move_task()
+ {
+ for pid in $1
+ do
+ /bin/echo $pid >$2/tasks 2>/dev/null
+ echo -n $pid
+ echo -n " "
+ done
+ echo END
+ }
+
+ G1_TASK=`cat ${G1}/tasks`
+ G2_TASK=`cat ${G2}/tasks`
+ move_task "${G1_TASK}" ${G2} &
+ --
+
+9.4 Memory hotplug
+------------------
+
+ memory hotplug test is one of good test.
+
+ to offline memory, do following::
+
+ # echo offline > /sys/devices/system/memory/memoryXXX/state
+
+ (XXX is the place of memory)
+
+ This is an easy way to test page migration, too.
+
+9.5 nested cgroups
+------------------
+
+ Use tests like the following for testing nested cgroups::
+
+ mkdir /opt/cgroup/01/child_a
+ mkdir /opt/cgroup/01/child_b
+
+ set limit to 01.
+ add limit to 01/child_b
+ run jobs under child_a and child_b
+
+ create/delete following groups at random while jobs are running::
+
+ /opt/cgroup/01/child_a/child_aa
+ /opt/cgroup/01/child_b/child_bb
+ /opt/cgroup/01/child_c
+
+ running new jobs in new group is also good.
+
+9.6 Mount with other subsystems
+-------------------------------
+
+ Mounting with other subsystems is a good test because there is a
+ race and lock dependency with other cgroup subsystems.
+
+ example::
+
+ # mount -t cgroup none /cgroup -o cpuset,memory,cpu,devices
+
+ and do task move, mkdir, rmdir etc...under this.
+
+9.7 swapoff
+-----------
+
+ Besides management of swap is one of complicated parts of memcg,
+ call path of swap-in at swapoff is not same as usual swap-in path..
+ It's worth to be tested explicitly.
+
+ For example, test like following is good:
+
+ (Shell-A)::
+
+ # mount -t cgroup none /cgroup -o memory
+ # mkdir /cgroup/test
+ # echo 40M > /cgroup/test/memory.limit_in_bytes
+ # echo 0 > /cgroup/test/tasks
+
+ Run malloc(100M) program under this. You'll see 60M of swaps.
+
+ (Shell-B)::
+
+ # move all tasks in /cgroup/test to /cgroup
+ # /sbin/swapoff -a
+ # rmdir /cgroup/test
+ # kill malloc task.
+
+ Of course, tmpfs v.s. swapoff test should be tested, too.
+
+9.8 OOM-Killer
+--------------
+
+ Out-of-memory caused by memcg's limit will kill tasks under
+ the memcg. When hierarchy is used, a task under hierarchy
+ will be killed by the kernel.
+
+ In this case, panic_on_oom shouldn't be invoked and tasks
+ in other groups shouldn't be killed.
+
+ It's not difficult to cause OOM under memcg as following.
+
+ Case A) when you can swapoff::
+
+ #swapoff -a
+ #echo 50M > /memory.limit_in_bytes
+
+ run 51M of malloc
+
+ Case B) when you use mem+swap limitation::
+
+ #echo 50M > memory.limit_in_bytes
+ #echo 50M > memory.memsw.limit_in_bytes
+
+ run 51M of malloc
+
+9.9 Move charges at task migration
+----------------------------------
+
+ Charges associated with a task can be moved along with task migration.
+
+ (Shell-A)::
+
+ #mkdir /cgroup/A
+ #echo $$ >/cgroup/A/tasks
+
+ run some programs which uses some amount of memory in /cgroup/A.
+
+ (Shell-B)::
+
+ #mkdir /cgroup/B
+ #echo 1 >/cgroup/B/memory.move_charge_at_immigrate
+ #echo "pid of the program running in group A" >/cgroup/B/tasks
+
+ You can see charges have been moved by reading ``*.usage_in_bytes`` or
+ memory.stat of both A and B.
+
+ See 8.2 of Documentation/admin-guide/cgroup-v1/memory.rst to see what value should
+ be written to move_charge_at_immigrate.
+
+9.10 Memory thresholds
+----------------------
+
+ Memory controller implements memory thresholds using cgroups notification
+ API. You can use tools/cgroup/cgroup_event_listener.c to test it.
+
+ (Shell-A) Create cgroup and run event listener::
+
+ # mkdir /cgroup/A
+ # ./cgroup_event_listener /cgroup/A/memory.usage_in_bytes 5M
+
+ (Shell-B) Add task to cgroup and try to allocate and free memory::
+
+ # echo $$ >/cgroup/A/tasks
+ # a="$(dd if=/dev/zero bs=1M count=10)"
+ # a=
+
+ You will see message from cgroup_event_listener every time you cross
+ the thresholds.
+
+ Use /cgroup/A/memory.memsw.usage_in_bytes to test memsw thresholds.
+
+ It's good idea to test root cgroup as well.
diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
new file mode 100644
index 000000000000..d6b1db8cc7eb
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/memory.rst
@@ -0,0 +1,964 @@
+==========================
+Memory Resource Controller
+==========================
+
+.. caution::
+ This document is hopelessly outdated and it asks for a complete
+ rewrite. It still contains a useful information so we are keeping it
+ here but make sure to check the current code if you need a deeper
+ understanding.
+
+.. note::
+ The Memory Resource Controller has generically been referred to as the
+ memory controller in this document. Do not confuse memory controller
+ used here with the memory controller that is used in hardware.
+
+.. hint::
+ When we mention a cgroup (cgroupfs's directory) with memory controller,
+ we call it "memory cgroup". When you see git-log and source code, you'll
+ see patch's title and function names tend to use "memcg".
+ In this document, we avoid using it.
+
+Benefits and Purpose of the memory controller
+=============================================
+
+The memory controller isolates the memory behaviour of a group of tasks
+from the rest of the system. The article on LWN [12]_ mentions some probable
+uses of the memory controller. The memory controller can be used to
+
+a. Isolate an application or a group of applications
+ Memory-hungry applications can be isolated and limited to a smaller
+ amount of memory.
+b. Create a cgroup with a limited amount of memory; this can be used
+ as a good alternative to booting with mem=XXXX.
+c. Virtualization solutions can control the amount of memory they want
+ to assign to a virtual machine instance.
+d. A CD/DVD burner could control the amount of memory used by the
+ rest of the system to ensure that burning does not fail due to lack
+ of available memory.
+e. There are several other use cases; find one or use the controller just
+ for fun (to learn and hack on the VM subsystem).
+
+Current Status: linux-2.6.34-mmotm(development version of 2010/April)
+
+Features:
+
+ - accounting anonymous pages, file caches, swap caches usage and limiting them.
+ - pages are linked to per-memcg LRU exclusively, and there is no global LRU.
+ - optionally, memory+swap usage can be accounted and limited.
+ - hierarchical accounting
+ - soft limit
+ - moving (recharging) account at moving a task is selectable.
+ - usage threshold notifier
+ - memory pressure notifier
+ - oom-killer disable knob and oom-notifier
+ - Root cgroup has no limit controls.
+
+ Kernel memory support is a work in progress, and the current version provides
+ basically functionality. (See :ref:`section 2.7
+ <cgroup-v1-memory-kernel-extension>`)
+
+Brief summary of control files.
+
+==================================== ==========================================
+ tasks attach a task(thread) and show list of
+ threads
+ cgroup.procs show list of processes
+ cgroup.event_control an interface for event_fd()
+ This knob is not available on CONFIG_PREEMPT_RT systems.
+ memory.usage_in_bytes show current usage for memory
+ (See 5.5 for details)
+ memory.memsw.usage_in_bytes show current usage for memory+Swap
+ (See 5.5 for details)
+ memory.limit_in_bytes set/show limit of memory usage
+ memory.memsw.limit_in_bytes set/show limit of memory+Swap usage
+ memory.failcnt show the number of memory usage hits limits
+ memory.memsw.failcnt show the number of memory+Swap hits limits
+ memory.max_usage_in_bytes show max memory usage recorded
+ memory.memsw.max_usage_in_bytes show max memory+Swap usage recorded
+ memory.soft_limit_in_bytes set/show soft limit of memory usage
+ This knob is not available on CONFIG_PREEMPT_RT systems.
+ This knob is deprecated and shouldn't be
+ used.
+ memory.stat show various statistics
+ memory.use_hierarchy set/show hierarchical account enabled
+ This knob is deprecated and shouldn't be
+ used.
+ memory.force_empty trigger forced page reclaim
+ memory.pressure_level set memory pressure notifications
+ This knob is deprecated and shouldn't be
+ used.
+ memory.swappiness set/show swappiness parameter of vmscan
+ (See sysctl's vm.swappiness)
+ Per memcg knob does not exist in cgroup v2.
+ memory.move_charge_at_immigrate This knob is deprecated.
+ memory.oom_control set/show oom controls.
+ This knob is deprecated and shouldn't be
+ used.
+ memory.numa_stat show the number of memory usage per numa
+ node
+ memory.kmem.limit_in_bytes Deprecated knob to set and read the kernel
+ memory hard limit. Kernel hard limit is not
+ supported since 5.16. Writing any value to
+ do file will not have any effect same as if
+ nokmem kernel parameter was specified.
+ Kernel memory is still charged and reported
+ by memory.kmem.usage_in_bytes.
+ memory.kmem.usage_in_bytes show current kernel memory allocation
+ memory.kmem.failcnt show the number of kernel memory usage
+ hits limits
+ memory.kmem.max_usage_in_bytes show max kernel memory usage recorded
+
+ memory.kmem.tcp.limit_in_bytes set/show hard limit for tcp buf memory
+ This knob is deprecated and shouldn't be
+ used.
+ memory.kmem.tcp.usage_in_bytes show current tcp buf memory allocation
+ This knob is deprecated and shouldn't be
+ used.
+ memory.kmem.tcp.failcnt show the number of tcp buf memory usage
+ hits limits
+ This knob is deprecated and shouldn't be
+ used.
+ memory.kmem.tcp.max_usage_in_bytes show max tcp buf memory usage recorded
+ This knob is deprecated and shouldn't be
+ used.
+==================================== ==========================================
+
+1. History
+==========
+
+The memory controller has a long history. A request for comments for the memory
+controller was posted by Balbir Singh [1]_. At the time the RFC was posted
+there were several implementations for memory control. The goal of the
+RFC was to build consensus and agreement for the minimal features required
+for memory control. The first RSS controller was posted by Balbir Singh [2]_
+in Feb 2007. Pavel Emelianov [3]_ [4]_ [5]_ has since posted three versions
+of the RSS controller. At OLS, at the resource management BoF, everyone
+suggested that we handle both page cache and RSS together. Another request was
+raised to allow user space handling of OOM. The current memory controller is
+at version 6; it combines both mapped (RSS) and unmapped Page
+Cache Control [11]_.
+
+2. Memory Control
+=================
+
+Memory is a unique resource in the sense that it is present in a limited
+amount. If a task requires a lot of CPU processing, the task can spread
+its processing over a period of hours, days, months or years, but with
+memory, the same physical memory needs to be reused to accomplish the task.
+
+The memory controller implementation has been divided into phases. These
+are:
+
+1. Memory controller
+2. mlock(2) controller
+3. Kernel user memory accounting and slab control
+4. user mappings length controller
+
+The memory controller is the first controller developed.
+
+2.1. Design
+-----------
+
+The core of the design is a counter called the page_counter. The
+page_counter tracks the current memory usage and limit of the group of
+processes associated with the controller. Each cgroup has a memory controller
+specific data structure (mem_cgroup) associated with it.
+
+2.2. Accounting
+---------------
+
+.. code-block::
+ :caption: Figure 1: Hierarchy of Accounting
+
+ +--------------------+
+ | mem_cgroup |
+ | (page_counter) |
+ +--------------------+
+ / ^ \
+ / | \
+ +---------------+ | +---------------+
+ | mm_struct | |.... | mm_struct |
+ | | | | |
+ +---------------+ | +---------------+
+ |
+ + --------------+
+ |
+ +---------------+ +------+--------+
+ | page +----------> page_cgroup|
+ | | | |
+ +---------------+ +---------------+
+
+
+
+Figure 1 shows the important aspects of the controller
+
+1. Accounting happens per cgroup
+2. Each mm_struct knows about which cgroup it belongs to
+3. Each page has a pointer to the page_cgroup, which in turn knows the
+ cgroup it belongs to
+
+The accounting is done as follows: mem_cgroup_charge_common() is invoked to
+set up the necessary data structures and check if the cgroup that is being
+charged is over its limit. If it is, then reclaim is invoked on the cgroup.
+More details can be found in the reclaim section of this document.
+If everything goes well, a page meta-data-structure called page_cgroup is
+updated. page_cgroup has its own LRU on cgroup.
+(*) page_cgroup structure is allocated at boot/memory-hotplug time.
+
+2.2.1 Accounting details
+------------------------
+
+All mapped anon pages (RSS) and cache pages (Page Cache) are accounted.
+Some pages which are never reclaimable and will not be on the LRU
+are not accounted. We just account pages under usual VM management.
+
+RSS pages are accounted at page_fault unless they've already been accounted
+for earlier. A file page will be accounted for as Page Cache when it's
+inserted into inode (xarray). While it's mapped into the page tables of
+processes, duplicate accounting is carefully avoided.
+
+An RSS page is unaccounted when it's fully unmapped. A PageCache page is
+unaccounted when it's removed from xarray. Even if RSS pages are fully
+unmapped (by kswapd), they may exist as SwapCache in the system until they
+are really freed. Such SwapCaches are also accounted.
+A swapped-in page is accounted after adding into swapcache.
+
+Note: The kernel does swapin-readahead and reads multiple swaps at once.
+Since page's memcg recorded into swap whatever memsw enabled, the page will
+be accounted after swapin.
+
+At page migration, accounting information is kept.
+
+Note: we just account pages-on-LRU because our purpose is to control amount
+of used pages; not-on-LRU pages tend to be out-of-control from VM view.
+
+2.3 Shared Page Accounting
+--------------------------
+
+Shared pages are accounted on the basis of the first touch approach. The
+cgroup that first touches a page is accounted for the page. The principle
+behind this approach is that a cgroup that aggressively uses a shared
+page will eventually get charged for it (once it is uncharged from
+the cgroup that brought it in -- this will happen on memory pressure).
+
+2.4 Swap Extension
+--------------------------------------
+
+Swap usage is always recorded for each of cgroup. Swap Extension allows you to
+read and limit it.
+
+When CONFIG_SWAP is enabled, following files are added.
+
+ - memory.memsw.usage_in_bytes.
+ - memory.memsw.limit_in_bytes.
+
+memsw means memory+swap. Usage of memory+swap is limited by
+memsw.limit_in_bytes.
+
+Example: Assume a system with 4G of swap. A task which allocates 6G of memory
+(by mistake) under 2G memory limitation will use all swap.
+In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
+By using the memsw limit, you can avoid system OOM which can be caused by swap
+shortage.
+
+2.4.1 why 'memory+swap' rather than swap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The global LRU(kswapd) can swap out arbitrary pages. Swap-out means
+to move account from memory to swap...there is no change in usage of
+memory+swap. In other words, when we want to limit the usage of swap without
+affecting global LRU, memory+swap limit is better than just limiting swap from
+an OS point of view.
+
+2.4.2. What happens when a cgroup hits memory.memsw.limit_in_bytes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out
+in this cgroup. Then, swap-out will not be done by cgroup routine and file
+caches are dropped. But as mentioned above, global LRU can do swapout memory
+from it for sanity of the system's memory management state. You can't forbid
+it by cgroup.
+
+2.5 Reclaim
+-----------
+
+Each cgroup maintains a per cgroup LRU which has the same structure as
+global VM. When a cgroup goes over its limit, we first try
+to reclaim memory from the cgroup so as to make space for the new
+pages that the cgroup has touched. If the reclaim is unsuccessful,
+an OOM routine is invoked to select and kill the bulkiest task in the
+cgroup. (See :ref:`10. OOM Control <cgroup-v1-memory-oom-control>` below.)
+
+The reclaim algorithm has not been modified for cgroups, except that
+pages that are selected for reclaiming come from the per-cgroup LRU
+list.
+
+.. note::
+ Reclaim does not work for the root cgroup, since we cannot set any
+ limits on the root cgroup.
+
+.. note::
+ When panic_on_oom is set to "2", the whole system will panic.
+
+When oom event notifier is registered, event will be delivered.
+(See :ref:`oom_control <cgroup-v1-memory-oom-control>` section)
+
+2.6 Locking
+-----------
+
+Lock order is as follows::
+
+ folio_lock
+ mm->page_table_lock or split pte_lock
+ folio_memcg_lock (memcg->move_lock)
+ mapping->i_pages lock
+ lruvec->lru_lock.
+
+Per-node-per-memcgroup LRU (cgroup's private LRU) is guarded by
+lruvec->lru_lock; the folio LRU flag is cleared before
+isolating a page from its LRU under lruvec->lru_lock.
+
+.. _cgroup-v1-memory-kernel-extension:
+
+2.7 Kernel Memory Extension
+-----------------------------------------------
+
+With the Kernel memory extension, the Memory Controller is able to limit
+the amount of kernel memory used by the system. Kernel memory is fundamentally
+different than user memory, since it can't be swapped out, which makes it
+possible to DoS the system by consuming too much of this precious resource.
+
+Kernel memory accounting is enabled for all memory cgroups by default. But
+it can be disabled system-wide by passing cgroup.memory=nokmem to the kernel
+at boot time. In this case, kernel memory will not be accounted at all.
+
+Kernel memory limits are not imposed for the root cgroup. Usage for the root
+cgroup may or may not be accounted. The memory used is accumulated into
+memory.kmem.usage_in_bytes, or in a separate counter when it makes sense.
+(currently only for tcp).
+
+The main "kmem" counter is fed into the main counter, so kmem charges will
+also be visible from the user counter.
+
+Currently no soft limit is implemented for kernel memory. It is future work
+to trigger slab reclaim when those limits are reached.
+
+2.7.1 Current Kernel Memory resources accounted
+-----------------------------------------------
+
+stack pages:
+ every process consumes some stack pages. By accounting into
+ kernel memory, we prevent new processes from being created when the kernel
+ memory usage is too high.
+
+slab pages:
+ pages allocated by the SLAB or SLUB allocator are tracked. A copy
+ of each kmem_cache is created every time the cache is touched by the first time
+ from inside the memcg. The creation is done lazily, so some objects can still be
+ skipped while the cache is being created. All objects in a slab page should
+ belong to the same memcg. This only fails to hold when a task is migrated to a
+ different memcg during the page allocation by the cache.
+
+sockets memory pressure:
+ some sockets protocols have memory pressure
+ thresholds. The Memory Controller allows them to be controlled individually
+ per cgroup, instead of globally.
+
+tcp memory pressure:
+ sockets memory pressure for the tcp protocol.
+
+2.7.2 Common use cases
+----------------------
+
+Because the "kmem" counter is fed to the main user counter, kernel memory can
+never be limited completely independently of user memory. Say "U" is the user
+limit, and "K" the kernel limit. There are three possible ways limits can be
+set:
+
+U != 0, K = unlimited:
+ This is the standard memcg limitation mechanism already present before kmem
+ accounting. Kernel memory is completely ignored.
+
+U != 0, K < U:
+ Kernel memory is a subset of the user memory. This setup is useful in
+ deployments where the total amount of memory per-cgroup is overcommitted.
+ Overcommitting kernel memory limits is definitely not recommended, since the
+ box can still run out of non-reclaimable memory.
+ In this case, the admin could set up K so that the sum of all groups is
+ never greater than the total memory, and freely set U at the cost of his
+ QoS.
+
+ .. warning::
+ In the current implementation, memory reclaim will NOT be triggered for
+ a cgroup when it hits K while staying below U, which makes this setup
+ impractical.
+
+U != 0, K >= U:
+ Since kmem charges will also be fed to the user counter and reclaim will be
+ triggered for the cgroup for both kinds of memory. This setup gives the
+ admin a unified view of memory, and it is also useful for people who just
+ want to track kernel memory usage.
+
+3. User Interface
+=================
+
+To use the user interface:
+
+1. Enable CONFIG_CGROUPS and CONFIG_MEMCG options
+2. Prepare the cgroups (see :ref:`Why are cgroups needed?
+ <cgroups-why-needed>` for the background information)::
+
+ # mount -t tmpfs none /sys/fs/cgroup
+ # mkdir /sys/fs/cgroup/memory
+ # mount -t cgroup none /sys/fs/cgroup/memory -o memory
+
+3. Make the new group and move bash into it::
+
+ # mkdir /sys/fs/cgroup/memory/0
+ # echo $$ > /sys/fs/cgroup/memory/0/tasks
+
+4. Since now we're in the 0 cgroup, we can alter the memory limit::
+
+ # echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes
+
+ The limit can now be queried::
+
+ # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
+ 4194304
+
+.. note::
+ We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
+ mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes,
+ Gibibytes.)
+
+.. note::
+ We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``.
+
+.. note::
+ We cannot set limits on the root cgroup any more.
+
+
+We can check the usage::
+
+ # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
+ 1216512
+
+A successful write to this file does not guarantee a successful setting of
+this limit to the value written into the file. This can be due to a
+number of factors, such as rounding up to page boundaries or the total
+availability of memory on the system. The user is required to re-read
+this file after a write to guarantee the value committed by the kernel::
+
+ # echo 1 > memory.limit_in_bytes
+ # cat memory.limit_in_bytes
+ 4096
+
+The memory.failcnt field gives the number of times that the cgroup limit was
+exceeded.
+
+The memory.stat file gives accounting information. Now, the number of
+caches, RSS and Active pages/Inactive pages are shown.
+
+4. Testing
+==========
+
+For testing features and implementation, see memcg_test.txt.
+
+Performance test is also important. To see pure memory controller's overhead,
+testing on tmpfs will give you good numbers of small overheads.
+Example: do kernel make on tmpfs.
+
+Page-fault scalability is also important. At measuring parallel
+page fault test, multi-process test may be better than multi-thread
+test because it has noise of shared objects/status.
+
+But the above two are testing extreme situations.
+Trying usual test under memory controller is always helpful.
+
+.. _cgroup-v1-memory-test-troubleshoot:
+
+4.1 Troubleshooting
+-------------------
+
+Sometimes a user might find that the application under a cgroup is
+terminated by the OOM killer. There are several causes for this:
+
+1. The cgroup limit is too low (just too low to do anything useful)
+2. The user is using anonymous memory and swap is turned off or too low
+
+A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
+some of the pages cached in the cgroup (page cache pages).
+
+To know what happens, disabling OOM_Kill as per :ref:`"10. OOM Control"
+<cgroup-v1-memory-oom-control>` (below) and seeing what happens will be
+helpful.
+
+.. _cgroup-v1-memory-test-task-migration:
+
+4.2 Task migration
+------------------
+
+When a task migrates from one cgroup to another, its charge is not
+carried forward by default. The pages allocated from the original cgroup still
+remain charged to it, the charge is dropped when the page is freed or
+reclaimed.
+
+You can move charges of a task along with task migration.
+See :ref:`8. "Move charges at task migration" <cgroup-v1-memory-move-charges>`
+
+4.3 Removing a cgroup
+---------------------
+
+A cgroup can be removed by rmdir, but as discussed in :ref:`sections 4.1
+<cgroup-v1-memory-test-troubleshoot>` and :ref:`4.2
+<cgroup-v1-memory-test-task-migration>`, a cgroup might have some charge
+associated with it, even though all tasks have migrated away from it. (because
+we charge against pages, not against tasks.)
+
+We move the stats to parent, and no change on the charge except uncharging
+from the child.
+
+Charges recorded in swap information is not updated at removal of cgroup.
+Recorded information is discarded and a cgroup which uses swap (swapcache)
+will be charged as a new owner of it.
+
+5. Misc. interfaces
+===================
+
+5.1 force_empty
+---------------
+ memory.force_empty interface is provided to make cgroup's memory usage empty.
+ When writing anything to this::
+
+ # echo 0 > memory.force_empty
+
+ the cgroup will be reclaimed and as many pages reclaimed as possible.
+
+ The typical use case for this interface is before calling rmdir().
+ Though rmdir() offlines memcg, but the memcg may still stay there due to
+ charged file caches. Some out-of-use page caches may keep charged until
+ memory pressure happens. If you want to avoid that, force_empty will be useful.
+
+5.2 stat file
+-------------
+
+memory.stat file includes following statistics:
+
+ * per-memory cgroup local status
+
+ =============== ===============================================================
+ cache # of bytes of page cache memory.
+ rss # of bytes of anonymous and swap cache memory (includes
+ transparent hugepages).
+ rss_huge # of bytes of anonymous transparent hugepages.
+ mapped_file # of bytes of mapped file (includes tmpfs/shmem)
+ pgpgin # of charging events to the memory cgroup. The charging
+ event happens each time a page is accounted as either mapped
+ anon page(RSS) or cache page(Page Cache) to the cgroup.
+ pgpgout # of uncharging events to the memory cgroup. The uncharging
+ event happens each time a page is unaccounted from the
+ cgroup.
+ swap # of bytes of swap usage
+ swapcached # of bytes of swap cached in memory
+ dirty # of bytes that are waiting to get written back to the disk.
+ writeback # of bytes of file/anon cache that are queued for syncing to
+ disk.
+ inactive_anon # of bytes of anonymous and swap cache memory on inactive
+ LRU list.
+ active_anon # of bytes of anonymous and swap cache memory on active
+ LRU list.
+ inactive_file # of bytes of file-backed memory and MADV_FREE anonymous
+ memory (LazyFree pages) on inactive LRU list.
+ active_file # of bytes of file-backed memory on active LRU list.
+ unevictable # of bytes of memory that cannot be reclaimed (mlocked etc).
+ =============== ===============================================================
+
+ * status considering hierarchy (see memory.use_hierarchy settings):
+
+ ========================= ===================================================
+ hierarchical_memory_limit # of bytes of memory limit with regard to
+ hierarchy
+ under which the memory cgroup is
+ hierarchical_memsw_limit # of bytes of memory+swap limit with regard to
+ hierarchy under which memory cgroup is.
+
+ total_<counter> # hierarchical version of <counter>, which in
+ addition to the cgroup's own value includes the
+ sum of all hierarchical children's values of
+ <counter>, i.e. total_cache
+ ========================= ===================================================
+
+ * additional vm parameters (depends on CONFIG_DEBUG_VM):
+
+ ========================= ========================================
+ recent_rotated_anon VM internal parameter. (see mm/vmscan.c)
+ recent_rotated_file VM internal parameter. (see mm/vmscan.c)
+ recent_scanned_anon VM internal parameter. (see mm/vmscan.c)
+ recent_scanned_file VM internal parameter. (see mm/vmscan.c)
+ ========================= ========================================
+
+.. hint::
+ recent_rotated means recent frequency of LRU rotation.
+ recent_scanned means recent # of scans to LRU.
+ showing for better debug please see the code for meanings.
+
+.. note::
+ Only anonymous and swap cache memory is listed as part of 'rss' stat.
+ This should not be confused with the true 'resident set size' or the
+ amount of physical memory used by the cgroup.
+
+ 'rss + mapped_file" will give you resident set size of cgroup.
+
+ Note that some kernel configurations might account complete larger
+ allocations (e.g., THP) towards 'rss' and 'mapped_file', even if
+ only some, but not all that memory is mapped.
+
+ (Note: file and shmem may be shared among other cgroups. In that case,
+ mapped_file is accounted only when the memory cgroup is owner of page
+ cache.)
+
+5.3 swappiness
+--------------
+
+Overrides /proc/sys/vm/swappiness for the particular group. The tunable
+in the root cgroup corresponds to the global swappiness setting.
+
+Please note that unlike during the global reclaim, limit reclaim
+enforces that 0 swappiness really prevents from any swapping even if
+there is a swap storage available. This might lead to memcg OOM killer
+if there are no file pages to reclaim.
+
+5.4 failcnt
+-----------
+
+A memory cgroup provides memory.failcnt and memory.memsw.failcnt files.
+This failcnt(== failure count) shows the number of times that a usage counter
+hit its limit. When a memory cgroup hits a limit, failcnt increases and
+memory under it will be reclaimed.
+
+You can reset failcnt by writing 0 to failcnt file::
+
+ # echo 0 > .../memory.failcnt
+
+5.5 usage_in_bytes
+------------------
+
+For efficiency, as other kernel components, memory cgroup uses some optimization
+to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the
+method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz
+value for efficient access. (Of course, when necessary, it's synchronized.)
+If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)
+value in memory.stat(see 5.2).
+
+5.6 numa_stat
+-------------
+
+This is similar to numa_maps but operates on a per-memcg basis. This is
+useful for providing visibility into the numa locality information within
+an memcg since the pages are allowed to be allocated from any physical
+node. One of the use cases is evaluating application performance by
+combining this information with the application's CPU allocation.
+
+Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable"
+per-node page counts including "hierarchical_<counter>" which sums up all
+hierarchical children's values in addition to the memcg's own value.
+
+The output format of memory.numa_stat is::
+
+ total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
+ hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ...
+
+The "total" count is sum of file + anon + unevictable.
+
+6. Hierarchy support
+====================
+
+The memory controller supports a deep hierarchy and hierarchical accounting.
+The hierarchy is created by creating the appropriate cgroups in the
+cgroup filesystem. Consider for example, the following cgroup filesystem
+hierarchy::
+
+ root
+ / | \
+ / | \
+ a b c
+ | \
+ | \
+ d e
+
+In the diagram above, with hierarchical accounting enabled, all memory
+usage of e, is accounted to its ancestors up until the root (i.e, c and root).
+If one of the ancestors goes over its limit, the reclaim algorithm reclaims
+from the tasks in the ancestor and the children of the ancestor.
+
+6.1 Hierarchical accounting and reclaim
+---------------------------------------
+
+Hierarchical accounting is enabled by default. Disabling the hierarchical
+accounting is deprecated. An attempt to do it will result in a failure
+and a warning printed to dmesg.
+
+For compatibility reasons writing 1 to memory.use_hierarchy will always pass::
+
+ # echo 1 > memory.use_hierarchy
+
+7. Soft limits (DEPRECATED)
+===========================
+
+THIS IS DEPRECATED!
+
+Soft limits allow for greater sharing of memory. The idea behind soft limits
+is to allow control groups to use as much of the memory as needed, provided
+
+a. There is no memory contention
+b. They do not exceed their hard limit
+
+When the system detects memory contention or low memory, control groups
+are pushed back to their soft limits. If the soft limit of each control
+group is very high, they are pushed back as much as possible to make
+sure that one control group does not starve the others of memory.
+
+Please note that soft limits is a best-effort feature; it comes with
+no guarantees, but it does its best to make sure that when memory is
+heavily contended for, memory is allocated based on the soft limit
+hints/setup. Currently soft limit based reclaim is set up such that
+it gets invoked from balance_pgdat (kswapd).
+
+7.1 Interface
+-------------
+
+Soft limits can be setup by using the following commands (in this example we
+assume a soft limit of 256 MiB)::
+
+ # echo 256M > memory.soft_limit_in_bytes
+
+If we want to change this to 1G, we can at any time use::
+
+ # echo 1G > memory.soft_limit_in_bytes
+
+.. note::
+ Soft limits take effect over a long period of time, since they involve
+ reclaiming memory for balancing between memory cgroups
+
+.. note::
+ It is recommended to set the soft limit always below the hard limit,
+ otherwise the hard limit will take precedence.
+
+.. _cgroup-v1-memory-move-charges:
+
+8. Move charges at task migration (DEPRECATED!)
+===============================================
+
+THIS IS DEPRECATED!
+
+Reading memory.move_charge_at_immigrate will always return 0 and writing
+to it will always return -EINVAL.
+
+9. Memory thresholds
+====================
+
+Memory cgroup implements memory thresholds using the cgroups notification
+API (see cgroups.txt). It allows to register multiple memory and memsw
+thresholds and gets notifications when it crosses.
+
+To register a threshold, an application must:
+
+- create an eventfd using eventfd(2);
+- open memory.usage_in_bytes or memory.memsw.usage_in_bytes;
+- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to
+ cgroup.event_control.
+
+Application will be notified through eventfd when memory usage crosses
+threshold in any direction.
+
+It's applicable for root and non-root cgroup.
+
+.. _cgroup-v1-memory-oom-control:
+
+10. OOM Control (DEPRECATED)
+============================
+
+THIS IS DEPRECATED!
+
+memory.oom_control file is for OOM notification and other controls.
+
+Memory cgroup implements OOM notifier using the cgroup notification
+API (See cgroups.txt). It allows to register multiple OOM notification
+delivery and gets notification when OOM happens.
+
+To register a notifier, an application must:
+
+ - create an eventfd using eventfd(2)
+ - open memory.oom_control file
+ - write string like "<event_fd> <fd of memory.oom_control>" to
+ cgroup.event_control
+
+The application will be notified through eventfd when OOM happens.
+OOM notification doesn't work for the root cgroup.
+
+You can disable the OOM-killer by writing "1" to memory.oom_control file, as:
+
+ #echo 1 > memory.oom_control
+
+If OOM-killer is disabled, tasks under cgroup will hang/sleep
+in memory cgroup's OOM-waitqueue when they request accountable memory.
+
+For running them, you have to relax the memory cgroup's OOM status by
+
+ * enlarge limit or reduce usage.
+
+To reduce usage,
+
+ * kill some tasks.
+ * move some tasks to other group with account migration.
+ * remove some files (on tmpfs?)
+
+Then, stopped tasks will work again.
+
+At reading, current status of OOM is shown.
+
+ - oom_kill_disable 0 or 1
+ (if 1, oom-killer is disabled)
+ - under_oom 0 or 1
+ (if 1, the memory cgroup is under OOM, tasks may be stopped.)
+ - oom_kill integer counter
+ The number of processes belonging to this cgroup killed by any
+ kind of OOM killer.
+
+11. Memory Pressure (DEPRECATED)
+================================
+
+THIS IS DEPRECATED!
+
+The pressure level notifications can be used to monitor the memory
+allocation cost; based on the pressure, applications can implement
+different strategies of managing their memory resources. The pressure
+levels are defined as following:
+
+The "low" level means that the system is reclaiming memory for new
+allocations. Monitoring this reclaiming activity might be useful for
+maintaining cache level. Upon notification, the program (typically
+"Activity Manager") might analyze vmstat and act in advance (i.e.
+prematurely shutdown unimportant services).
+
+The "medium" level means that the system is experiencing medium memory
+pressure, the system might be making swap, paging out active file caches,
+etc. Upon this event applications may decide to further analyze
+vmstat/zoneinfo/memcg or internal memory usage statistics and free any
+resources that can be easily reconstructed or re-read from a disk.
+
+The "critical" level means that the system is actively thrashing, it is
+about to out of memory (OOM) or even the in-kernel OOM killer is on its
+way to trigger. Applications should do whatever they can to help the
+system. It might be too late to consult with vmstat or any other
+statistics, so it's advisable to take an immediate action.
+
+By default, events are propagated upward until the event is handled, i.e. the
+events are not pass-through. For example, you have three cgroups: A->B->C. Now
+you set up an event listener on cgroups A, B and C, and suppose group C
+experiences some pressure. In this situation, only group C will receive the
+notification, i.e. groups A and B will not receive it. This is done to avoid
+excessive "broadcasting" of messages, which disturbs the system and which is
+especially bad if we are low on memory or thrashing. Group B, will receive
+notification only if there are no event listeners for group C.
+
+There are three optional modes that specify different propagation behavior:
+
+ - "default": this is the default behavior specified above. This mode is the
+ same as omitting the optional mode parameter, preserved by backwards
+ compatibility.
+
+ - "hierarchy": events always propagate up to the root, similar to the default
+ behavior, except that propagation continues regardless of whether there are
+ event listeners at each level, with the "hierarchy" mode. In the above
+ example, groups A, B, and C will receive notification of memory pressure.
+
+ - "local": events are pass-through, i.e. they only receive notifications when
+ memory pressure is experienced in the memcg for which the notification is
+ registered. In the above example, group C will receive notification if
+ registered for "local" notification and the group experiences memory
+ pressure. However, group B will never receive notification, regardless if
+ there is an event listener for group C or not, if group B is registered for
+ local notification.
+
+The level and event notification mode ("hierarchy" or "local", if necessary) are
+specified by a comma-delimited string, i.e. "low,hierarchy" specifies
+hierarchical, pass-through, notification for all ancestor memcgs. Notification
+that is the default, non pass-through behavior, does not specify a mode.
+"medium,local" specifies pass-through notification for the medium level.
+
+The file memory.pressure_level is only used to setup an eventfd. To
+register a notification, an application must:
+
+- create an eventfd using eventfd(2);
+- open memory.pressure_level;
+- write string as "<event_fd> <fd of memory.pressure_level> <level[,mode]>"
+ to cgroup.event_control.
+
+Application will be notified through eventfd when memory pressure is at
+the specific level (or higher). Read/write operations to
+memory.pressure_level are no implemented.
+
+Test:
+
+ Here is a small script example that makes a new cgroup, sets up a
+ memory limit, sets up a notification in the cgroup and then makes child
+ cgroup experience a critical pressure::
+
+ # cd /sys/fs/cgroup/memory/
+ # mkdir foo
+ # cd foo
+ # cgroup_event_listener memory.pressure_level low,hierarchy &
+ # echo 8000000 > memory.limit_in_bytes
+ # echo 8000000 > memory.memsw.limit_in_bytes
+ # echo $$ > tasks
+ # dd if=/dev/zero | read x
+
+ (Expect a bunch of notifications, and eventually, the oom-killer will
+ trigger.)
+
+12. TODO
+========
+
+1. Make per-cgroup scanner reclaim not-shared pages first
+2. Teach controller to account for shared-pages
+3. Start reclamation in the background when the limit is
+ not yet hit but the usage is getting closer
+
+Summary
+=======
+
+Overall, the memory controller has been a stable controller and has been
+commented and discussed quite extensively in the community.
+
+References
+==========
+
+.. [1] Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
+.. [2] Singh, Balbir. Memory Controller (RSS Control),
+ http://lwn.net/Articles/222762/
+.. [3] Emelianov, Pavel. Resource controllers based on process cgroups
+ https://lore.kernel.org/r/45ED7DEC.7010403@sw.ru
+.. [4] Emelianov, Pavel. RSS controller based on process cgroups (v2)
+ https://lore.kernel.org/r/461A3010.90403@sw.ru
+.. [5] Emelianov, Pavel. RSS controller based on process cgroups (v3)
+ https://lore.kernel.org/r/465D9739.8070209@openvz.org
+
+6. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/
+7. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control
+ subsystem (v3), http://lwn.net/Articles/235534/
+8. Singh, Balbir. RSS controller v2 test results (lmbench),
+ https://lore.kernel.org/r/464C95D4.7070806@linux.vnet.ibm.com
+9. Singh, Balbir. RSS controller v2 AIM9 results
+ https://lore.kernel.org/r/464D267A.50107@linux.vnet.ibm.com
+10. Singh, Balbir. Memory controller v6 test results,
+ https://lore.kernel.org/r/20070819094658.654.84837.sendpatchset@balbir-laptop
+
+.. [11] Singh, Balbir. Memory controller introduction (v6),
+ https://lore.kernel.org/r/20070817084228.26003.12568.sendpatchset@balbir-laptop
+.. [12] Corbet, Jonathan, Controlling memory use in cgroups,
+ http://lwn.net/Articles/243795/
diff --git a/Documentation/admin-guide/cgroup-v1/misc.rst b/Documentation/admin-guide/cgroup-v1/misc.rst
new file mode 100644
index 000000000000..661614c24df3
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/misc.rst
@@ -0,0 +1,4 @@
+===============
+Misc controller
+===============
+Please refer "Misc" documentation in Documentation/admin-guide/cgroup-v2.rst
diff --git a/Documentation/admin-guide/cgroup-v1/net_cls.rst b/Documentation/admin-guide/cgroup-v1/net_cls.rst
new file mode 100644
index 000000000000..a2cf272af7a0
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/net_cls.rst
@@ -0,0 +1,44 @@
+=========================
+Network classifier cgroup
+=========================
+
+The Network classifier cgroup provides an interface to
+tag network packets with a class identifier (classid).
+
+The Traffic Controller (tc) can be used to assign
+different priorities to packets from different cgroups.
+Also, Netfilter (iptables) can use this tag to perform
+actions on such packets.
+
+Creating a net_cls cgroups instance creates a net_cls.classid file.
+This net_cls.classid value is initialized to 0.
+
+You can write hexadecimal values to net_cls.classid; the format for these
+values is 0xAAAABBBB; AAAA is the major handle number and BBBB
+is the minor handle number.
+Reading net_cls.classid yields a decimal result.
+
+Example::
+
+ mkdir /sys/fs/cgroup/net_cls
+ mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls
+ mkdir /sys/fs/cgroup/net_cls/0
+ echo 0x100001 > /sys/fs/cgroup/net_cls/0/net_cls.classid
+
+- setting a 10:1 handle::
+
+ cat /sys/fs/cgroup/net_cls/0/net_cls.classid
+ 1048577
+
+- configuring tc::
+
+ tc qdisc add dev eth0 root handle 10: htb
+ tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit
+
+- creating traffic class 10:1::
+
+ tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup
+
+configuring iptables, basic example::
+
+ iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
diff --git a/Documentation/admin-guide/cgroup-v1/net_prio.rst b/Documentation/admin-guide/cgroup-v1/net_prio.rst
new file mode 100644
index 000000000000..b40905871c64
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/net_prio.rst
@@ -0,0 +1,57 @@
+=======================
+Network priority cgroup
+=======================
+
+The Network priority cgroup provides an interface to allow an administrator to
+dynamically set the priority of network traffic generated by various
+applications
+
+Nominally, an application would set the priority of its traffic via the
+SO_PRIORITY socket option. This however, is not always possible because:
+
+1) The application may not have been coded to set this value
+2) The priority of application traffic is often a site-specific administrative
+ decision rather than an application defined one.
+
+This cgroup allows an administrator to assign a process to a group which defines
+the priority of egress traffic on a given interface. Network priority groups can
+be created by first mounting the cgroup filesystem::
+
+ # mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
+
+With the above step, the initial group acting as the parent accounting group
+becomes visible at '/sys/fs/cgroup/net_prio'. This group includes all tasks in
+the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup.
+
+Each net_prio cgroup contains two files that are subsystem specific
+
+net_prio.prioidx
+ This file is read-only, and is simply informative. It contains a unique
+ integer value that the kernel uses as an internal representation of this
+ cgroup.
+
+net_prio.ifpriomap
+ This file contains a map of the priorities assigned to traffic originating
+ from processes in this group and egressing the system on various interfaces.
+ It contains a list of tuples in the form <ifname priority>. Contents of this
+ file can be modified by echoing a string into the file using the same tuple
+ format. For example::
+
+ echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap
+
+This command would force any traffic originating from processes belonging to the
+iscsi net_prio cgroup and egressing on interface eth0 to have the priority of
+said traffic set to the value 5. The parent accounting group also has a
+writeable 'net_prio.ifpriomap' file that can be used to set a system default
+priority.
+
+Priorities are set immediately prior to queueing a frame to the device
+queueing discipline (qdisc) so priorities will be assigned prior to the hardware
+queue selection being made.
+
+One usage for the net_prio cgroup is with mqprio qdisc allowing application
+traffic to be steered to hardware/driver based traffic classes. These mappings
+can then be managed by administrators or other networking protocols such as
+DCBX.
+
+A new net_prio cgroup inherits the parent's configuration.
diff --git a/Documentation/admin-guide/cgroup-v1/pids.rst b/Documentation/admin-guide/cgroup-v1/pids.rst
new file mode 100644
index 000000000000..0f9f9a7b1f6c
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/pids.rst
@@ -0,0 +1,93 @@
+=========================
+Process Number Controller
+=========================
+
+Abstract
+--------
+
+The process number controller is used to allow a cgroup hierarchy to stop any
+new tasks from being fork()'d or clone()'d after a certain limit is reached.
+
+Since it is trivial to hit the task limit without hitting any kmemcg limits in
+place, PIDs are a fundamental resource. As such, PID exhaustion must be
+preventable in the scope of a cgroup hierarchy by allowing resource limiting of
+the number of tasks in a cgroup.
+
+Usage
+-----
+
+In order to use the `pids` controller, set the maximum number of tasks in
+pids.max (this is not available in the root cgroup for obvious reasons). The
+number of processes currently in the cgroup is given by pids.current.
+
+Organisational operations are not blocked by cgroup policies, so it is possible
+to have pids.current > pids.max. This can be done by either setting the limit to
+be smaller than pids.current, or attaching enough processes to the cgroup such
+that pids.current > pids.max. However, it is not possible to violate a cgroup
+policy through fork() or clone(). fork() and clone() will return -EAGAIN if the
+creation of a new process would cause a cgroup policy to be violated.
+
+To set a cgroup to have no limit, set pids.max to "max". This is the default for
+all new cgroups (N.B. that PID limits are hierarchical, so the most stringent
+limit in the hierarchy is followed).
+
+pids.current tracks all child cgroup hierarchies, so parent/pids.current is a
+superset of parent/child/pids.current.
+
+The pids.events file contains event counters:
+
+ - max: Number of times fork failed in the cgroup because limit was hit in
+ self or ancestors.
+
+Example
+-------
+
+First, we mount the pids controller::
+
+ # mkdir -p /sys/fs/cgroup/pids
+ # mount -t cgroup -o pids none /sys/fs/cgroup/pids
+
+Then we create a hierarchy, set limits and attach processes to it::
+
+ # mkdir -p /sys/fs/cgroup/pids/parent/child
+ # echo 2 > /sys/fs/cgroup/pids/parent/pids.max
+ # echo $$ > /sys/fs/cgroup/pids/parent/cgroup.procs
+ # cat /sys/fs/cgroup/pids/parent/pids.current
+ 2
+ #
+
+It should be noted that attempts to overcome the set limit (2 in this case) will
+fail::
+
+ # cat /sys/fs/cgroup/pids/parent/pids.current
+ 2
+ # ( /bin/echo "Here's some processes for you." | cat )
+ sh: fork: Resource temporary unavailable
+ #
+
+Even if we migrate to a child cgroup (which doesn't have a set limit), we will
+not be able to overcome the most stringent limit in the hierarchy (in this case,
+parent's)::
+
+ # echo $$ > /sys/fs/cgroup/pids/parent/child/cgroup.procs
+ # cat /sys/fs/cgroup/pids/parent/pids.current
+ 2
+ # cat /sys/fs/cgroup/pids/parent/child/pids.current
+ 2
+ # cat /sys/fs/cgroup/pids/parent/child/pids.max
+ max
+ # ( /bin/echo "Here's some processes for you." | cat )
+ sh: fork: Resource temporary unavailable
+ #
+
+We can set a limit that is smaller than pids.current, which will stop any new
+processes from being forked at all (note that the shell itself counts towards
+pids.current)::
+
+ # echo 1 > /sys/fs/cgroup/pids/parent/pids.max
+ # /bin/echo "We can't even spawn a single process now."
+ sh: fork: Resource temporary unavailable
+ # echo 0 > /sys/fs/cgroup/pids/parent/pids.max
+ # /bin/echo "We can't even spawn a single process now."
+ sh: fork: Resource temporary unavailable
+ #
diff --git a/Documentation/admin-guide/cgroup-v1/rdma.rst b/Documentation/admin-guide/cgroup-v1/rdma.rst
new file mode 100644
index 000000000000..e69369b7252e
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v1/rdma.rst
@@ -0,0 +1,117 @@
+===============
+RDMA Controller
+===============
+
+.. Contents
+
+ 1. Overview
+ 1-1. What is RDMA controller?
+ 1-2. Why RDMA controller needed?
+ 1-3. How is RDMA controller implemented?
+ 2. Usage Examples
+
+1. Overview
+===========
+
+1-1. What is RDMA controller?
+-----------------------------
+
+RDMA controller allows user to limit RDMA/IB specific resources that a given
+set of processes can use. These processes are grouped using RDMA controller.
+
+RDMA controller defines two resources which can be limited for processes of a
+cgroup.
+
+1-2. Why RDMA controller needed?
+--------------------------------
+
+Currently user space applications can easily take away all the rdma verb
+specific resources such as AH, CQ, QP, MR etc. Due to which other applications
+in other cgroup or kernel space ULPs may not even get chance to allocate any
+rdma resources. This can lead to service unavailability.
+
+Therefore RDMA controller is needed through which resource consumption
+of processes can be limited. Through this controller different rdma
+resources can be accounted.
+
+1-3. How is RDMA controller implemented?
+----------------------------------------
+
+RDMA cgroup allows limit configuration of resources. Rdma cgroup maintains
+resource accounting per cgroup, per device using resource pool structure.
+Each such resource pool is limited up to 64 resources in given resource pool
+by rdma cgroup, which can be extended later if required.
+
+This resource pool object is linked to the cgroup css. Typically there
+are 0 to 4 resource pool instances per cgroup, per device in most use cases.
+But nothing limits to have it more. At present hundreds of RDMA devices per
+single cgroup may not be handled optimally, however there is no
+known use case or requirement for such configuration either.
+
+Since RDMA resources can be allocated from any process and can be freed by any
+of the child processes which shares the address space, rdma resources are
+always owned by the creator cgroup css. This allows process migration from one
+to other cgroup without major complexity of transferring resource ownership;
+because such ownership is not really present due to shared nature of
+rdma resources. Linking resources around css also ensures that cgroups can be
+deleted after processes migrated. This allow progress migration as well with
+active resources, even though that is not a primary use case.
+
+Whenever RDMA resource charging occurs, owner rdma cgroup is returned to
+the caller. Same rdma cgroup should be passed while uncharging the resource.
+This also allows process migrated with active RDMA resource to charge
+to new owner cgroup for new resource. It also allows to uncharge resource of
+a process from previously charged cgroup which is migrated to new cgroup,
+even though that is not a primary use case.
+
+Resource pool object is created in following situations.
+(a) User sets the limit and no previous resource pool exist for the device
+of interest for the cgroup.
+(b) No resource limits were configured, but IB/RDMA stack tries to
+charge the resource. So that it correctly uncharge them when applications are
+running without limits and later on when limits are enforced during uncharging,
+otherwise usage count will drop to negative.
+
+Resource pool is destroyed if all the resource limits are set to max and
+it is the last resource getting deallocated.
+
+User should set all the limit to max value if it intents to remove/unconfigure
+the resource pool for a particular device.
+
+IB stack honors limits enforced by the rdma controller. When application
+query about maximum resource limits of IB device, it returns minimum of
+what is configured by user for a given cgroup and what is supported by
+IB device.
+
+Following resources can be accounted by rdma controller.
+
+ ========== =============================
+ hca_handle Maximum number of HCA Handles
+ hca_object Maximum number of HCA Objects
+ ========== =============================
+
+2. Usage Examples
+=================
+
+(a) Configure resource limit::
+
+ echo mlx4_0 hca_handle=2 hca_object=2000 > /sys/fs/cgroup/rdma/1/rdma.max
+ echo ocrdma1 hca_handle=3 > /sys/fs/cgroup/rdma/2/rdma.max
+
+(b) Query resource limit::
+
+ cat /sys/fs/cgroup/rdma/2/rdma.max
+ #Output:
+ mlx4_0 hca_handle=2 hca_object=2000
+ ocrdma1 hca_handle=3 hca_object=max
+
+(c) Query current usage::
+
+ cat /sys/fs/cgroup/rdma/2/rdma.current
+ #Output:
+ mlx4_0 hca_handle=1 hca_object=20
+ ocrdma1 hca_handle=1 hca_object=23
+
+(d) Delete resource limit::
+
+ echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
new file mode 100644
index 000000000000..7f5b59d95fce
--- /dev/null
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -0,0 +1,3430 @@
+.. _cgroup-v2:
+
+================
+Control Group v2
+================
+
+:Date: October, 2015
+:Author: Tejun Heo <tj@kernel.org>
+
+This is the authoritative documentation on the design, interface and
+conventions of cgroup v2. It describes all userland-visible aspects
+of cgroup including core and specific controller behaviors. All
+future changes must be reflected in this document. Documentation for
+v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgroup-v1>`.
+
+.. CONTENTS
+
+ [Whenever any new section is added to this document, please also add
+ an entry here.]
+
+ 1. Introduction
+ 1-1. Terminology
+ 1-2. What is cgroup?
+ 2. Basic Operations
+ 2-1. Mounting
+ 2-2. Organizing Processes and Threads
+ 2-2-1. Processes
+ 2-2-2. Threads
+ 2-3. [Un]populated Notification
+ 2-4. Controlling Controllers
+ 2-4-1. Availability
+ 2-4-2. Enabling and Disabling
+ 2-4-3. Top-down Constraint
+ 2-4-4. No Internal Process Constraint
+ 2-5. Delegation
+ 2-5-1. Model of Delegation
+ 2-5-2. Delegation Containment
+ 2-6. Guidelines
+ 2-6-1. Organize Once and Control
+ 2-6-2. Avoid Name Collisions
+ 3. Resource Distribution Models
+ 3-1. Weights
+ 3-2. Limits
+ 3-3. Protections
+ 3-4. Allocations
+ 4. Interface Files
+ 4-1. Format
+ 4-2. Conventions
+ 4-3. Core Interface Files
+ 5. Controllers
+ 5-1. CPU
+ 5-1-1. CPU Interface Files
+ 5-2. Memory
+ 5-2-1. Memory Interface Files
+ 5-2-2. Usage Guidelines
+ 5-2-3. Reclaim Protection
+ 5-2-4. Memory Ownership
+ 5-3. IO
+ 5-3-1. IO Interface Files
+ 5-3-2. Writeback
+ 5-3-3. IO Latency
+ 5-3-3-1. How IO Latency Throttling Works
+ 5-3-3-2. IO Latency Interface Files
+ 5-3-4. IO Priority
+ 5-4. PID
+ 5-4-1. PID Interface Files
+ 5-5. Cpuset
+ 5.5-1. Cpuset Interface Files
+ 5-6. Device controller
+ 5-7. RDMA
+ 5-7-1. RDMA Interface Files
+ 5-8. DMEM
+ 5-8-1. DMEM Interface Files
+ 5-9. HugeTLB
+ 5.9-1. HugeTLB Interface Files
+ 5-10. Misc
+ 5.10-1 Misc Interface Files
+ 5.10-2 Migration and Ownership
+ 5-11. Others
+ 5-11-1. perf_event
+ 5-N. Non-normative information
+ 5-N-1. CPU controller root cgroup process behaviour
+ 5-N-2. IO controller root cgroup process behaviour
+ 6. Namespace
+ 6-1. Basics
+ 6-2. The Root and Views
+ 6-3. Migration and setns(2)
+ 6-4. Interaction with Other Namespaces
+ P. Information on Kernel Programming
+ P-1. Filesystem Support for Writeback
+ D. Deprecated v1 Core Features
+ R. Issues with v1 and Rationales for v2
+ R-1. Multiple Hierarchies
+ R-2. Thread Granularity
+ R-3. Competition Between Inner Nodes and Threads
+ R-4. Other Interface Issues
+ R-5. Controller Issues and Remedies
+ R-5-1. Memory
+
+
+Introduction
+============
+
+Terminology
+-----------
+
+"cgroup" stands for "control group" and is never capitalized. The
+singular form is used to designate the whole feature and also as a
+qualifier as in "cgroup controllers". When explicitly referring to
+multiple individual control groups, the plural form "cgroups" is used.
+
+
+What is cgroup?
+---------------
+
+cgroup is a mechanism to organize processes hierarchically and
+distribute system resources along the hierarchy in a controlled and
+configurable manner.
+
+cgroup is largely composed of two parts - the core and controllers.
+cgroup core is primarily responsible for hierarchically organizing
+processes. A cgroup controller is usually responsible for
+distributing a specific type of system resource along the hierarchy
+although there are utility controllers which serve purposes other than
+resource distribution.
+
+cgroups form a tree structure and every process in the system belongs
+to one and only one cgroup. All threads of a process belong to the
+same cgroup. On creation, all processes are put in the cgroup that
+the parent process belongs to at the time. A process can be migrated
+to another cgroup. Migration of a process doesn't affect already
+existing descendant processes.
+
+Following certain structural constraints, controllers may be enabled or
+disabled selectively on a cgroup. All controller behaviors are
+hierarchical - if a controller is enabled on a cgroup, it affects all
+processes which belong to the cgroups consisting the inclusive
+sub-hierarchy of the cgroup. When a controller is enabled on a nested
+cgroup, it always restricts the resource distribution further. The
+restrictions set closer to the root in the hierarchy can not be
+overridden from further away.
+
+
+Basic Operations
+================
+
+Mounting
+--------
+
+Unlike v1, cgroup v2 has only single hierarchy. The cgroup v2
+hierarchy can be mounted with the following mount command::
+
+ # mount -t cgroup2 none $MOUNT_POINT
+
+cgroup2 filesystem has the magic number 0x63677270 ("cgrp"). All
+controllers which support v2 and are not bound to a v1 hierarchy are
+automatically bound to the v2 hierarchy and show up at the root.
+Controllers which are not in active use in the v2 hierarchy can be
+bound to other hierarchies. This allows mixing v2 hierarchy with the
+legacy v1 multiple hierarchies in a fully backward compatible way.
+
+A controller can be moved across hierarchies only after the controller
+is no longer referenced in its current hierarchy. Because per-cgroup
+controller states are destroyed asynchronously and controllers may
+have lingering references, a controller may not show up immediately on
+the v2 hierarchy after the final umount of the previous hierarchy.
+Similarly, a controller should be fully disabled to be moved out of
+the unified hierarchy and it may take some time for the disabled
+controller to become available for other hierarchies; furthermore, due
+to inter-controller dependencies, other controllers may need to be
+disabled too.
+
+While useful for development and manual configurations, moving
+controllers dynamically between the v2 and other hierarchies is
+strongly discouraged for production use. It is recommended to decide
+the hierarchies and controller associations before starting using the
+controllers after system boot.
+
+During transition to v2, system management software might still
+automount the v1 cgroup filesystem and so hijack all controllers
+during boot, before manual intervention is possible. To make testing
+and experimenting easier, the kernel parameter cgroup_no_v1= allows
+disabling controllers in v1 and make them always available in v2.
+
+cgroup v2 currently supports the following mount options.
+
+ nsdelegate
+ Consider cgroup namespaces as delegation boundaries. This
+ option is system wide and can only be set on mount or modified
+ through remount from the init namespace. The mount option is
+ ignored on non-init namespace mounts. Please refer to the
+ Delegation section for details.
+
+ favordynmods
+ Reduce the latencies of dynamic cgroup modifications such as
+ task migrations and controller on/offs at the cost of making
+ hot path operations such as forks and exits more expensive.
+ The static usage pattern of creating a cgroup, enabling
+ controllers, and then seeding it with CLONE_INTO_CGROUP is
+ not affected by this option.
+
+ memory_localevents
+ Only populate memory.events with data for the current cgroup,
+ and not any subtrees. This is legacy behaviour, the default
+ behaviour without this option is to include subtree counts.
+ This option is system wide and can only be set on mount or
+ modified through remount from the init namespace. The mount
+ option is ignored on non-init namespace mounts.
+
+ memory_recursiveprot
+ Recursively apply memory.min and memory.low protection to
+ entire subtrees, without requiring explicit downward
+ propagation into leaf cgroups. This allows protecting entire
+ subtrees from one another, while retaining free competition
+ within those subtrees. This should have been the default
+ behavior but is a mount-option to avoid regressing setups
+ relying on the original semantics (e.g. specifying bogusly
+ high 'bypass' protection values at higher tree levels).
+
+ memory_hugetlb_accounting
+ Count HugeTLB memory usage towards the cgroup's overall
+ memory usage for the memory controller (for the purpose of
+ statistics reporting and memory protetion). This is a new
+ behavior that could regress existing setups, so it must be
+ explicitly opted in with this mount option.
+
+ A few caveats to keep in mind:
+
+ * There is no HugeTLB pool management involved in the memory
+ controller. The pre-allocated pool does not belong to anyone.
+ Specifically, when a new HugeTLB folio is allocated to
+ the pool, it is not accounted for from the perspective of the
+ memory controller. It is only charged to a cgroup when it is
+ actually used (for e.g at page fault time). Host memory
+ overcommit management has to consider this when configuring
+ hard limits. In general, HugeTLB pool management should be
+ done via other mechanisms (such as the HugeTLB controller).
+ * Failure to charge a HugeTLB folio to the memory controller
+ results in SIGBUS. This could happen even if the HugeTLB pool
+ still has pages available (but the cgroup limit is hit and
+ reclaim attempt fails).
+ * Charging HugeTLB memory towards the memory controller affects
+ memory protection and reclaim dynamics. Any userspace tuning
+ (of low, min limits for e.g) needs to take this into account.
+ * HugeTLB pages utilized while this option is not selected
+ will not be tracked by the memory controller (even if cgroup
+ v2 is remounted later on).
+
+ pids_localevents
+ The option restores v1-like behavior of pids.events:max, that is only
+ local (inside cgroup proper) fork failures are counted. Without this
+ option pids.events.max represents any pids.max enforcemnt across
+ cgroup's subtree.
+
+
+
+Organizing Processes and Threads
+--------------------------------
+
+Processes
+~~~~~~~~~
+
+Initially, only the root cgroup exists to which all processes belong.
+A child cgroup can be created by creating a sub-directory::
+
+ # mkdir $CGROUP_NAME
+
+A given cgroup may have multiple child cgroups forming a tree
+structure. Each cgroup has a read-writable interface file
+"cgroup.procs". When read, it lists the PIDs of all processes which
+belong to the cgroup one-per-line. The PIDs are not ordered and the
+same PID may show up more than once if the process got moved to
+another cgroup and then back or the PID got recycled while reading.
+
+A process can be migrated into a cgroup by writing its PID to the
+target cgroup's "cgroup.procs" file. Only one process can be migrated
+on a single write(2) call. If a process is composed of multiple
+threads, writing the PID of any thread migrates all threads of the
+process.
+
+When a process forks a child process, the new process is born into the
+cgroup that the forking process belongs to at the time of the
+operation. After exit, a process stays associated with the cgroup
+that it belonged to at the time of exit until it's reaped; however, a
+zombie process does not appear in "cgroup.procs" and thus can't be
+moved to another cgroup.
+
+A cgroup which doesn't have any children or live processes can be
+destroyed by removing the directory. Note that a cgroup which doesn't
+have any children and is associated only with zombie processes is
+considered empty and can be removed::
+
+ # rmdir $CGROUP_NAME
+
+"/proc/$PID/cgroup" lists a process's cgroup membership. If legacy
+cgroup is in use in the system, this file may contain multiple lines,
+one for each hierarchy. The entry for cgroup v2 is always in the
+format "0::$PATH"::
+
+ # cat /proc/842/cgroup
+ ...
+ 0::/test-cgroup/test-cgroup-nested
+
+If the process becomes a zombie and the cgroup it was associated with
+is removed subsequently, " (deleted)" is appended to the path::
+
+ # cat /proc/842/cgroup
+ ...
+ 0::/test-cgroup/test-cgroup-nested (deleted)
+
+
+Threads
+~~~~~~~
+
+cgroup v2 supports thread granularity for a subset of controllers to
+support use cases requiring hierarchical resource distribution across
+the threads of a group of processes. By default, all threads of a
+process belong to the same cgroup, which also serves as the resource
+domain to host resource consumptions which are not specific to a
+process or thread. The thread mode allows threads to be spread across
+a subtree while still maintaining the common resource domain for them.
+
+Controllers which support thread mode are called threaded controllers.
+The ones which don't are called domain controllers.
+
+Marking a cgroup threaded makes it join the resource domain of its
+parent as a threaded cgroup. The parent may be another threaded
+cgroup whose resource domain is further up in the hierarchy. The root
+of a threaded subtree, that is, the nearest ancestor which is not
+threaded, is called threaded domain or thread root interchangeably and
+serves as the resource domain for the entire subtree.
+
+Inside a threaded subtree, threads of a process can be put in
+different cgroups and are not subject to the no internal process
+constraint - threaded controllers can be enabled on non-leaf cgroups
+whether they have threads in them or not.
+
+As the threaded domain cgroup hosts all the domain resource
+consumptions of the subtree, it is considered to have internal
+resource consumptions whether there are processes in it or not and
+can't have populated child cgroups which aren't threaded. Because the
+root cgroup is not subject to no internal process constraint, it can
+serve both as a threaded domain and a parent to domain cgroups.
+
+The current operation mode or type of the cgroup is shown in the
+"cgroup.type" file which indicates whether the cgroup is a normal
+domain, a domain which is serving as the domain of a threaded subtree,
+or a threaded cgroup.
+
+On creation, a cgroup is always a domain cgroup and can be made
+threaded by writing "threaded" to the "cgroup.type" file. The
+operation is single direction::
+
+ # echo threaded > cgroup.type
+
+Once threaded, the cgroup can't be made a domain again. To enable the
+thread mode, the following conditions must be met.
+
+- As the cgroup will join the parent's resource domain. The parent
+ must either be a valid (threaded) domain or a threaded cgroup.
+
+- When the parent is an unthreaded domain, it must not have any domain
+ controllers enabled or populated domain children. The root is
+ exempt from this requirement.
+
+Topology-wise, a cgroup can be in an invalid state. Please consider
+the following topology::
+
+ A (threaded domain) - B (threaded) - C (domain, just created)
+
+C is created as a domain but isn't connected to a parent which can
+host child domains. C can't be used until it is turned into a
+threaded cgroup. "cgroup.type" file will report "domain (invalid)" in
+these cases. Operations which fail due to invalid topology use
+EOPNOTSUPP as the errno.
+
+A domain cgroup is turned into a threaded domain when one of its child
+cgroup becomes threaded or threaded controllers are enabled in the
+"cgroup.subtree_control" file while there are processes in the cgroup.
+A threaded domain reverts to a normal domain when the conditions
+clear.
+
+When read, "cgroup.threads" contains the list of the thread IDs of all
+threads in the cgroup. Except that the operations are per-thread
+instead of per-process, "cgroup.threads" has the same format and
+behaves the same way as "cgroup.procs". While "cgroup.threads" can be
+written to in any cgroup, as it can only move threads inside the same
+threaded domain, its operations are confined inside each threaded
+subtree.
+
+The threaded domain cgroup serves as the resource domain for the whole
+subtree, and, while the threads can be scattered across the subtree,
+all the processes are considered to be in the threaded domain cgroup.
+"cgroup.procs" in a threaded domain cgroup contains the PIDs of all
+processes in the subtree and is not readable in the subtree proper.
+However, "cgroup.procs" can be written to from anywhere in the subtree
+to migrate all threads of the matching process to the cgroup.
+
+Only threaded controllers can be enabled in a threaded subtree. When
+a threaded controller is enabled inside a threaded subtree, it only
+accounts for and controls resource consumptions associated with the
+threads in the cgroup and its descendants. All consumptions which
+aren't tied to a specific thread belong to the threaded domain cgroup.
+
+Because a threaded subtree is exempt from no internal process
+constraint, a threaded controller must be able to handle competition
+between threads in a non-leaf cgroup and its child cgroups. Each
+threaded controller defines how such competitions are handled.
+
+Currently, the following controllers are threaded and can be enabled
+in a threaded cgroup::
+
+- cpu
+- cpuset
+- perf_event
+- pids
+
+[Un]populated Notification
+--------------------------
+
+Each non-root cgroup has a "cgroup.events" file which contains
+"populated" field indicating whether the cgroup's sub-hierarchy has
+live processes in it. Its value is 0 if there is no live process in
+the cgroup and its descendants; otherwise, 1. poll and [id]notify
+events are triggered when the value changes. This can be used, for
+example, to start a clean-up operation after all processes of a given
+sub-hierarchy have exited. The populated state updates and
+notifications are recursive. Consider the following sub-hierarchy
+where the numbers in the parentheses represent the numbers of processes
+in each cgroup::
+
+ A(4) - B(0) - C(1)
+ \ D(0)
+
+A, B and C's "populated" fields would be 1 while D's 0. After the one
+process in C exits, B and C's "populated" fields would flip to "0" and
+file modified events will be generated on the "cgroup.events" files of
+both cgroups.
+
+
+Controlling Controllers
+-----------------------
+
+Availability
+~~~~~~~~~~~~
+
+A controller is available in a cgroup when it is supported by the kernel (i.e.,
+compiled in, not disabled and not attached to a v1 hierarchy) and listed in the
+"cgroup.controllers" file. Availability means the controller's interface files
+are exposed in the cgroup’s directory, allowing the distribution of the target
+resource to be observed or controlled within that cgroup.
+
+Enabling and Disabling
+~~~~~~~~~~~~~~~~~~~~~~
+
+Each cgroup has a "cgroup.controllers" file which lists all
+controllers available for the cgroup to enable::
+
+ # cat cgroup.controllers
+ cpu io memory
+
+No controller is enabled by default. Controllers can be enabled and
+disabled by writing to the "cgroup.subtree_control" file::
+
+ # echo "+cpu +memory -io" > cgroup.subtree_control
+
+Only controllers which are listed in "cgroup.controllers" can be
+enabled. When multiple operations are specified as above, either they
+all succeed or fail. If multiple operations on the same controller
+are specified, the last one is effective.
+
+Enabling a controller in a cgroup indicates that the distribution of
+the target resource across its immediate children will be controlled.
+Consider the following sub-hierarchy. The enabled controllers are
+listed in parentheses::
+
+ A(cpu,memory) - B(memory) - C()
+ \ D()
+
+As A has "cpu" and "memory" enabled, A will control the distribution
+of CPU cycles and memory to its children, in this case, B. As B has
+"memory" enabled but not "CPU", C and D will compete freely on CPU
+cycles but their division of memory available to B will be controlled.
+
+As a controller regulates the distribution of the target resource to
+the cgroup's children, enabling it creates the controller's interface
+files in the child cgroups. In the above example, enabling "cpu" on B
+would create the "cpu." prefixed controller interface files in C and
+D. Likewise, disabling "memory" from B would remove the "memory."
+prefixed controller interface files from C and D. This means that the
+controller interface files - anything which doesn't start with
+"cgroup." are owned by the parent rather than the cgroup itself.
+
+
+Top-down Constraint
+~~~~~~~~~~~~~~~~~~~
+
+Resources are distributed top-down and a cgroup can further distribute
+a resource only if the resource has been distributed to it from the
+parent. This means that all non-root "cgroup.subtree_control" files
+can only contain controllers which are enabled in the parent's
+"cgroup.subtree_control" file. A controller can be enabled only if
+the parent has the controller enabled and a controller can't be
+disabled if one or more children have it enabled.
+
+
+No Internal Process Constraint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Non-root cgroups can distribute domain resources to their children
+only when they don't have any processes of their own. In other words,
+only domain cgroups which don't contain any processes can have domain
+controllers enabled in their "cgroup.subtree_control" files.
+
+This guarantees that, when a domain controller is looking at the part
+of the hierarchy which has it enabled, processes are always only on
+the leaves. This rules out situations where child cgroups compete
+against internal processes of the parent.
+
+The root cgroup is exempt from this restriction. Root contains
+processes and anonymous resource consumption which can't be associated
+with any other cgroups and requires special treatment from most
+controllers. How resource consumption in the root cgroup is governed
+is up to each controller (for more information on this topic please
+refer to the Non-normative information section in the Controllers
+chapter).
+
+Note that the restriction doesn't get in the way if there is no
+enabled controller in the cgroup's "cgroup.subtree_control". This is
+important as otherwise it wouldn't be possible to create children of a
+populated cgroup. To control resource distribution of a cgroup, the
+cgroup must create children and transfer all its processes to the
+children before enabling controllers in its "cgroup.subtree_control"
+file.
+
+
+Delegation
+----------
+
+Model of Delegation
+~~~~~~~~~~~~~~~~~~~
+
+A cgroup can be delegated in two ways. First, to a less privileged
+user by granting write access of the directory and its "cgroup.procs",
+"cgroup.threads" and "cgroup.subtree_control" files to the user.
+Second, if the "nsdelegate" mount option is set, automatically to a
+cgroup namespace on namespace creation.
+
+Because the resource control interface files in a given directory
+control the distribution of the parent's resources, the delegatee
+shouldn't be allowed to write to them. For the first method, this is
+achieved by not granting access to these files. For the second, files
+outside the namespace should be hidden from the delegatee by the means
+of at least mount namespacing, and the kernel rejects writes to all
+files on a namespace root from inside the cgroup namespace, except for
+those files listed in "/sys/kernel/cgroup/delegate" (including
+"cgroup.procs", "cgroup.threads", "cgroup.subtree_control", etc.).
+
+The end results are equivalent for both delegation types. Once
+delegated, the user can build sub-hierarchy under the directory,
+organize processes inside it as it sees fit and further distribute the
+resources it received from the parent. The limits and other settings
+of all resource controllers are hierarchical and regardless of what
+happens in the delegated sub-hierarchy, nothing can escape the
+resource restrictions imposed by the parent.
+
+Currently, cgroup doesn't impose any restrictions on the number of
+cgroups in or nesting depth of a delegated sub-hierarchy; however,
+this may be limited explicitly in the future.
+
+
+Delegation Containment
+~~~~~~~~~~~~~~~~~~~~~~
+
+A delegated sub-hierarchy is contained in the sense that processes
+can't be moved into or out of the sub-hierarchy by the delegatee.
+
+For delegations to a less privileged user, this is achieved by
+requiring the following conditions for a process with a non-root euid
+to migrate a target process into a cgroup by writing its PID to the
+"cgroup.procs" file.
+
+- The writer must have write access to the "cgroup.procs" file.
+
+- The writer must have write access to the "cgroup.procs" file of the
+ common ancestor of the source and destination cgroups.
+
+The above two constraints ensure that while a delegatee may migrate
+processes around freely in the delegated sub-hierarchy it can't pull
+in from or push out to outside the sub-hierarchy.
+
+For an example, let's assume cgroups C0 and C1 have been delegated to
+user U0 who created C00, C01 under C0 and C10 under C1 as follows and
+all processes under C0 and C1 belong to U0::
+
+ ~~~~~~~~~~~~~ - C0 - C00
+ ~ cgroup ~ \ C01
+ ~ hierarchy ~
+ ~~~~~~~~~~~~~ - C1 - C10
+
+Let's also say U0 wants to write the PID of a process which is
+currently in C10 into "C00/cgroup.procs". U0 has write access to the
+file; however, the common ancestor of the source cgroup C10 and the
+destination cgroup C00 is above the points of delegation and U0 would
+not have write access to its "cgroup.procs" files and thus the write
+will be denied with -EACCES.
+
+For delegations to namespaces, containment is achieved by requiring
+that both the source and destination cgroups are reachable from the
+namespace of the process which is attempting the migration. If either
+is not reachable, the migration is rejected with -ENOENT.
+
+
+Guidelines
+----------
+
+Organize Once and Control
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Migrating a process across cgroups is a relatively expensive operation
+and stateful resources such as memory are not moved together with the
+process. This is an explicit design decision as there often exist
+inherent trade-offs between migration and various hot paths in terms
+of synchronization cost.
+
+As such, migrating processes across cgroups frequently as a means to
+apply different resource restrictions is discouraged. A workload
+should be assigned to a cgroup according to the system's logical and
+resource structure once on start-up. Dynamic adjustments to resource
+distribution can be made by changing controller configuration through
+the interface files.
+
+
+Avoid Name Collisions
+~~~~~~~~~~~~~~~~~~~~~
+
+Interface files for a cgroup and its children cgroups occupy the same
+directory and it is possible to create children cgroups which collide
+with interface files.
+
+All cgroup core interface files are prefixed with "cgroup." and each
+controller's interface files are prefixed with the controller name and
+a dot. A controller's name is composed of lower case alphabets and
+'_'s but never begins with an '_' so it can be used as the prefix
+character for collision avoidance. Also, interface file names won't
+start or end with terms which are often used in categorizing workloads
+such as job, service, slice, unit or workload.
+
+cgroup doesn't do anything to prevent name collisions and it's the
+user's responsibility to avoid them.
+
+
+Resource Distribution Models
+============================
+
+cgroup controllers implement several resource distribution schemes
+depending on the resource type and expected use cases. This section
+describes major schemes in use along with their expected behaviors.
+
+
+Weights
+-------
+
+A parent's resource is distributed by adding up the weights of all
+active children and giving each the fraction matching the ratio of its
+weight against the sum. As only children which can make use of the
+resource at the moment participate in the distribution, this is
+work-conserving. Due to the dynamic nature, this model is usually
+used for stateless resources.
+
+All weights are in the range [1, 10000] with the default at 100. This
+allows symmetric multiplicative biases in both directions at fine
+enough granularity while staying in the intuitive range.
+
+As long as the weight is in range, all configuration combinations are
+valid and there is no reason to reject configuration changes or
+process migrations.
+
+"cpu.weight" proportionally distributes CPU cycles to active children
+and is an example of this type.
+
+
+.. _cgroupv2-limits-distributor:
+
+Limits
+------
+
+A child can only consume up to the configured amount of the resource.
+Limits can be over-committed - the sum of the limits of children can
+exceed the amount of resource available to the parent.
+
+Limits are in the range [0, max] and defaults to "max", which is noop.
+
+As limits can be over-committed, all configuration combinations are
+valid and there is no reason to reject configuration changes or
+process migrations.
+
+"io.max" limits the maximum BPS and/or IOPS that a cgroup can consume
+on an IO device and is an example of this type.
+
+.. _cgroupv2-protections-distributor:
+
+Protections
+-----------
+
+A cgroup is protected up to the configured amount of the resource
+as long as the usages of all its ancestors are under their
+protected levels. Protections can be hard guarantees or best effort
+soft boundaries. Protections can also be over-committed in which case
+only up to the amount available to the parent is protected among
+children.
+
+Protections are in the range [0, max] and defaults to 0, which is
+noop.
+
+As protections can be over-committed, all configuration combinations
+are valid and there is no reason to reject configuration changes or
+process migrations.
+
+"memory.low" implements best-effort memory protection and is an
+example of this type.
+
+
+Allocations
+-----------
+
+A cgroup is exclusively allocated a certain amount of a finite
+resource. Allocations can't be over-committed - the sum of the
+allocations of children can not exceed the amount of resource
+available to the parent.
+
+Allocations are in the range [0, max] and defaults to 0, which is no
+resource.
+
+As allocations can't be over-committed, some configuration
+combinations are invalid and should be rejected. Also, if the
+resource is mandatory for execution of processes, process migrations
+may be rejected.
+
+"cpu.rt.max" hard-allocates realtime slices and is an example of this
+type.
+
+
+Interface Files
+===============
+
+Format
+------
+
+All interface files should be in one of the following formats whenever
+possible::
+
+ New-line separated values
+ (when only one value can be written at once)
+
+ VAL0\n
+ VAL1\n
+ ...
+
+ Space separated values
+ (when read-only or multiple values can be written at once)
+
+ VAL0 VAL1 ...\n
+
+ Flat keyed
+
+ KEY0 VAL0\n
+ KEY1 VAL1\n
+ ...
+
+ Nested keyed
+
+ KEY0 SUB_KEY0=VAL00 SUB_KEY1=VAL01...
+ KEY1 SUB_KEY0=VAL10 SUB_KEY1=VAL11...
+ ...
+
+For a writable file, the format for writing should generally match
+reading; however, controllers may allow omitting later fields or
+implement restricted shortcuts for most common use cases.
+
+For both flat and nested keyed files, only the values for a single key
+can be written at a time. For nested keyed files, the sub key pairs
+may be specified in any order and not all pairs have to be specified.
+
+
+Conventions
+-----------
+
+- Settings for a single feature should be contained in a single file.
+
+- The root cgroup should be exempt from resource control and thus
+ shouldn't have resource control interface files.
+
+- The default time unit is microseconds. If a different unit is ever
+ used, an explicit unit suffix must be present.
+
+- A parts-per quantity should use a percentage decimal with at least
+ two digit fractional part - e.g. 13.40.
+
+- If a controller implements weight based resource distribution, its
+ interface file should be named "weight" and have the range [1,
+ 10000] with 100 as the default. The values are chosen to allow
+ enough and symmetric bias in both directions while keeping it
+ intuitive (the default is 100%).
+
+- If a controller implements an absolute resource guarantee and/or
+ limit, the interface files should be named "min" and "max"
+ respectively. If a controller implements best effort resource
+ guarantee and/or limit, the interface files should be named "low"
+ and "high" respectively.
+
+ In the above four control files, the special token "max" should be
+ used to represent upward infinity for both reading and writing.
+
+- If a setting has a configurable default value and keyed specific
+ overrides, the default entry should be keyed with "default" and
+ appear as the first entry in the file.
+
+ The default value can be updated by writing either "default $VAL" or
+ "$VAL".
+
+ When writing to update a specific override, "default" can be used as
+ the value to indicate removal of the override. Override entries
+ with "default" as the value must not appear when read.
+
+ For example, a setting which is keyed by major:minor device numbers
+ with integer values may look like the following::
+
+ # cat cgroup-example-interface-file
+ default 150
+ 8:0 300
+
+ The default value can be updated by::
+
+ # echo 125 > cgroup-example-interface-file
+
+ or::
+
+ # echo "default 125" > cgroup-example-interface-file
+
+ An override can be set by::
+
+ # echo "8:16 170" > cgroup-example-interface-file
+
+ and cleared by::
+
+ # echo "8:0 default" > cgroup-example-interface-file
+ # cat cgroup-example-interface-file
+ default 125
+ 8:16 170
+
+- For events which are not very high frequency, an interface file
+ "events" should be created which lists event key value pairs.
+ Whenever a notifiable event happens, file modified event should be
+ generated on the file.
+
+
+Core Interface Files
+--------------------
+
+All cgroup core files are prefixed with "cgroup."
+
+ cgroup.type
+ A read-write single value file which exists on non-root
+ cgroups.
+
+ When read, it indicates the current type of the cgroup, which
+ can be one of the following values.
+
+ - "domain" : A normal valid domain cgroup.
+
+ - "domain threaded" : A threaded domain cgroup which is
+ serving as the root of a threaded subtree.
+
+ - "domain invalid" : A cgroup which is in an invalid state.
+ It can't be populated or have controllers enabled. It may
+ be allowed to become a threaded cgroup.
+
+ - "threaded" : A threaded cgroup which is a member of a
+ threaded subtree.
+
+ A cgroup can be turned into a threaded cgroup by writing
+ "threaded" to this file.
+
+ cgroup.procs
+ A read-write new-line separated values file which exists on
+ all cgroups.
+
+ When read, it lists the PIDs of all processes which belong to
+ the cgroup one-per-line. The PIDs are not ordered and the
+ same PID may show up more than once if the process got moved
+ to another cgroup and then back or the PID got recycled while
+ reading.
+
+ A PID can be written to migrate the process associated with
+ the PID to the cgroup. The writer should match all of the
+ following conditions.
+
+ - It must have write access to the "cgroup.procs" file.
+
+ - It must have write access to the "cgroup.procs" file of the
+ common ancestor of the source and destination cgroups.
+
+ When delegating a sub-hierarchy, write access to this file
+ should be granted along with the containing directory.
+
+ In a threaded cgroup, reading this file fails with EOPNOTSUPP
+ as all the processes belong to the thread root. Writing is
+ supported and moves every thread of the process to the cgroup.
+
+ cgroup.threads
+ A read-write new-line separated values file which exists on
+ all cgroups.
+
+ When read, it lists the TIDs of all threads which belong to
+ the cgroup one-per-line. The TIDs are not ordered and the
+ same TID may show up more than once if the thread got moved to
+ another cgroup and then back or the TID got recycled while
+ reading.
+
+ A TID can be written to migrate the thread associated with the
+ TID to the cgroup. The writer should match all of the
+ following conditions.
+
+ - It must have write access to the "cgroup.threads" file.
+
+ - The cgroup that the thread is currently in must be in the
+ same resource domain as the destination cgroup.
+
+ - It must have write access to the "cgroup.procs" file of the
+ common ancestor of the source and destination cgroups.
+
+ When delegating a sub-hierarchy, write access to this file
+ should be granted along with the containing directory.
+
+ cgroup.controllers
+ A read-only space separated values file which exists on all
+ cgroups.
+
+ It shows space separated list of all controllers available to
+ the cgroup. The controllers are not ordered.
+
+ cgroup.subtree_control
+ A read-write space separated values file which exists on all
+ cgroups. Starts out empty.
+
+ When read, it shows space separated list of the controllers
+ which are enabled to control resource distribution from the
+ cgroup to its children.
+
+ Space separated list of controllers prefixed with '+' or '-'
+ can be written to enable or disable controllers. A controller
+ name prefixed with '+' enables the controller and '-'
+ disables. If a controller appears more than once on the list,
+ the last one is effective. When multiple enable and disable
+ operations are specified, either all succeed or all fail.
+
+ cgroup.events
+ A read-only flat-keyed file which exists on non-root cgroups.
+ The following entries are defined. Unless specified
+ otherwise, a value change in this file generates a file
+ modified event.
+
+ populated
+ 1 if the cgroup or its descendants contains any live
+ processes; otherwise, 0.
+ frozen
+ 1 if the cgroup is frozen; otherwise, 0.
+
+ cgroup.max.descendants
+ A read-write single value files. The default is "max".
+
+ Maximum allowed number of descent cgroups.
+ If the actual number of descendants is equal or larger,
+ an attempt to create a new cgroup in the hierarchy will fail.
+
+ cgroup.max.depth
+ A read-write single value files. The default is "max".
+
+ Maximum allowed descent depth below the current cgroup.
+ If the actual descent depth is equal or larger,
+ an attempt to create a new child cgroup will fail.
+
+ cgroup.stat
+ A read-only flat-keyed file with the following entries:
+
+ nr_descendants
+ Total number of visible descendant cgroups.
+
+ nr_dying_descendants
+ Total number of dying descendant cgroups. A cgroup becomes
+ dying after being deleted by a user. The cgroup will remain
+ in dying state for some time undefined time (which can depend
+ on system load) before being completely destroyed.
+
+ A process can't enter a dying cgroup under any circumstances,
+ a dying cgroup can't revive.
+
+ A dying cgroup can consume system resources not exceeding
+ limits, which were active at the moment of cgroup deletion.
+
+ nr_subsys_<cgroup_subsys>
+ Total number of live cgroup subsystems (e.g memory
+ cgroup) at and beneath the current cgroup.
+
+ nr_dying_subsys_<cgroup_subsys>
+ Total number of dying cgroup subsystems (e.g. memory
+ cgroup) at and beneath the current cgroup.
+
+ cgroup.stat.local
+ A read-only flat-keyed file which exists in non-root cgroups.
+ The following entry is defined:
+
+ frozen_usec
+ Cumulative time that this cgroup has spent between freezing and
+ thawing, regardless of whether by self or ancestor groups.
+ NB: (not) reaching "frozen" state is not accounted here.
+
+ Using the following ASCII representation of a cgroup's freezer
+ state, ::
+
+ 1 _____
+ frozen 0 __/ \__
+ ab cd
+
+ the duration being measured is the span between a and c.
+
+ cgroup.freeze
+ A read-write single value file which exists on non-root cgroups.
+ Allowed values are "0" and "1". The default is "0".
+
+ Writing "1" to the file causes freezing of the cgroup and all
+ descendant cgroups. This means that all belonging processes will
+ be stopped and will not run until the cgroup will be explicitly
+ unfrozen. Freezing of the cgroup may take some time; when this action
+ is completed, the "frozen" value in the cgroup.events control file
+ will be updated to "1" and the corresponding notification will be
+ issued.
+
+ A cgroup can be frozen either by its own settings, or by settings
+ of any ancestor cgroups. If any of ancestor cgroups is frozen, the
+ cgroup will remain frozen.
+
+ Processes in the frozen cgroup can be killed by a fatal signal.
+ They also can enter and leave a frozen cgroup: either by an explicit
+ move by a user, or if freezing of the cgroup races with fork().
+ If a process is moved to a frozen cgroup, it stops. If a process is
+ moved out of a frozen cgroup, it becomes running.
+
+ Frozen status of a cgroup doesn't affect any cgroup tree operations:
+ it's possible to delete a frozen (and empty) cgroup, as well as
+ create new sub-cgroups.
+
+ cgroup.kill
+ A write-only single value file which exists in non-root cgroups.
+ The only allowed value is "1".
+
+ Writing "1" to the file causes the cgroup and all descendant cgroups to
+ be killed. This means that all processes located in the affected cgroup
+ tree will be killed via SIGKILL.
+
+ Killing a cgroup tree will deal with concurrent forks appropriately and
+ is protected against migrations.
+
+ In a threaded cgroup, writing this file fails with EOPNOTSUPP as
+ killing cgroups is a process directed operation, i.e. it affects
+ the whole thread-group.
+
+ cgroup.pressure
+ A read-write single value file that allowed values are "0" and "1".
+ The default is "1".
+
+ Writing "0" to the file will disable the cgroup PSI accounting.
+ Writing "1" to the file will re-enable the cgroup PSI accounting.
+
+ This control attribute is not hierarchical, so disable or enable PSI
+ accounting in a cgroup does not affect PSI accounting in descendants
+ and doesn't need pass enablement via ancestors from root.
+
+ The reason this control attribute exists is that PSI accounts stalls for
+ each cgroup separately and aggregates it at each level of the hierarchy.
+ This may cause non-negligible overhead for some workloads when under
+ deep level of the hierarchy, in which case this control attribute can
+ be used to disable PSI accounting in the non-leaf cgroups.
+
+ irq.pressure
+ A read-write nested-keyed file.
+
+ Shows pressure stall information for IRQ/SOFTIRQ. See
+ :ref:`Documentation/accounting/psi.rst <psi>` for details.
+
+Controllers
+===========
+
+.. _cgroup-v2-cpu:
+
+CPU
+---
+
+The "cpu" controllers regulates distribution of CPU cycles. This
+controller implements weight and absolute bandwidth limit models for
+normal scheduling policy and absolute bandwidth allocation model for
+realtime scheduling policy.
+
+In all the above models, cycles distribution is defined only on a temporal
+base and it does not account for the frequency at which tasks are executed.
+The (optional) utilization clamping support allows to hint the schedutil
+cpufreq governor about the minimum desired frequency which should always be
+provided by a CPU, as well as the maximum desired frequency, which should not
+be exceeded by a CPU.
+
+WARNING: cgroup2 cpu controller doesn't yet support the (bandwidth) control of
+realtime processes. For a kernel built with the CONFIG_RT_GROUP_SCHED option
+enabled for group scheduling of realtime processes, the cpu controller can only
+be enabled when all RT processes are in the root cgroup. Be aware that system
+management software may already have placed RT processes into non-root cgroups
+during the system boot process, and these processes may need to be moved to the
+root cgroup before the cpu controller can be enabled with a
+CONFIG_RT_GROUP_SCHED enabled kernel.
+
+With CONFIG_RT_GROUP_SCHED disabled, this limitation does not apply and some of
+the interface files either affect realtime processes or account for them. See
+the following section for details. Only the cpu controller is affected by
+CONFIG_RT_GROUP_SCHED. Other controllers can be used for the resource control of
+realtime processes irrespective of CONFIG_RT_GROUP_SCHED.
+
+
+CPU Interface Files
+~~~~~~~~~~~~~~~~~~~
+
+The interaction of a process with the cpu controller depends on its scheduling
+policy and the underlying scheduler. From the point of view of the cpu controller,
+processes can be categorized as follows:
+
+* Processes under the fair-class scheduler
+* Processes under a BPF scheduler with the ``cgroup_set_weight`` callback
+* Everything else: ``SCHED_{FIFO,RR,DEADLINE}`` and processes under a BPF scheduler
+ without the ``cgroup_set_weight`` callback
+
+For details on when a process is under the fair-class scheduler or a BPF scheduler,
+check out :ref:`Documentation/scheduler/sched-ext.rst <sched-ext>`.
+
+For each of the following interface files, the above categories
+will be referred to. All time durations are in microseconds.
+
+ cpu.stat
+ A read-only flat-keyed file.
+ This file exists whether the controller is enabled or not.
+
+ It always reports the following three stats, which account for all the
+ processes in the cgroup:
+
+ - usage_usec
+ - user_usec
+ - system_usec
+
+ and the following five when the controller is enabled, which account for
+ only the processes under the fair-class scheduler:
+
+ - nr_periods
+ - nr_throttled
+ - throttled_usec
+ - nr_bursts
+ - burst_usec
+
+ cpu.weight
+ A read-write single value file which exists on non-root
+ cgroups. The default is "100".
+
+ For non idle groups (cpu.idle = 0), the weight is in the
+ range [1, 10000].
+
+ If the cgroup has been configured to be SCHED_IDLE (cpu.idle = 1),
+ then the weight will show as a 0.
+
+ This file affects only processes under the fair-class scheduler and a BPF
+ scheduler with the ``cgroup_set_weight`` callback depending on what the
+ callback actually does.
+
+ cpu.weight.nice
+ A read-write single value file which exists on non-root
+ cgroups. The default is "0".
+
+ The nice value is in the range [-20, 19].
+
+ This interface file is an alternative interface for
+ "cpu.weight" and allows reading and setting weight using the
+ same values used by nice(2). Because the range is smaller and
+ granularity is coarser for the nice values, the read value is
+ the closest approximation of the current weight.
+
+ This file affects only processes under the fair-class scheduler and a BPF
+ scheduler with the ``cgroup_set_weight`` callback depending on what the
+ callback actually does.
+
+ cpu.max
+ A read-write two value file which exists on non-root cgroups.
+ The default is "max 100000".
+
+ The maximum bandwidth limit. It's in the following format::
+
+ $MAX $PERIOD
+
+ which indicates that the group may consume up to $MAX in each
+ $PERIOD duration. "max" for $MAX indicates no limit. If only
+ one number is written, $MAX is updated.
+
+ This file affects only processes under the fair-class scheduler.
+
+ cpu.max.burst
+ A read-write single value file which exists on non-root
+ cgroups. The default is "0".
+
+ The burst in the range [0, $MAX].
+
+ This file affects only processes under the fair-class scheduler.
+
+ cpu.pressure
+ A read-write nested-keyed file.
+
+ Shows pressure stall information for CPU. See
+ :ref:`Documentation/accounting/psi.rst <psi>` for details.
+
+ This file accounts for all the processes in the cgroup.
+
+ cpu.uclamp.min
+ A read-write single value file which exists on non-root cgroups.
+ The default is "0", i.e. no utilization boosting.
+
+ The requested minimum utilization (protection) as a percentage
+ rational number, e.g. 12.34 for 12.34%.
+
+ This interface allows reading and setting minimum utilization clamp
+ values similar to the sched_setattr(2). This minimum utilization
+ value is used to clamp the task specific minimum utilization clamp,
+ including those of realtime processes.
+
+ The requested minimum utilization (protection) is always capped by
+ the current value for the maximum utilization (limit), i.e.
+ `cpu.uclamp.max`.
+
+ This file affects all the processes in the cgroup.
+
+ cpu.uclamp.max
+ A read-write single value file which exists on non-root cgroups.
+ The default is "max". i.e. no utilization capping
+
+ The requested maximum utilization (limit) as a percentage rational
+ number, e.g. 98.76 for 98.76%.
+
+ This interface allows reading and setting maximum utilization clamp
+ values similar to the sched_setattr(2). This maximum utilization
+ value is used to clamp the task specific maximum utilization clamp,
+ including those of realtime processes.
+
+ This file affects all the processes in the cgroup.
+
+ cpu.idle
+ A read-write single value file which exists on non-root cgroups.
+ The default is 0.
+
+ This is the cgroup analog of the per-task SCHED_IDLE sched policy.
+ Setting this value to a 1 will make the scheduling policy of the
+ cgroup SCHED_IDLE. The threads inside the cgroup will retain their
+ own relative priorities, but the cgroup itself will be treated as
+ very low priority relative to its peers.
+
+ This file affects only processes under the fair-class scheduler.
+
+Memory
+------
+
+The "memory" controller regulates distribution of memory. Memory is
+stateful and implements both limit and protection models. Due to the
+intertwining between memory usage and reclaim pressure and the
+stateful nature of memory, the distribution model is relatively
+complex.
+
+While not completely water-tight, all major memory usages by a given
+cgroup are tracked so that the total memory consumption can be
+accounted and controlled to a reasonable extent. Currently, the
+following types of memory usages are tracked.
+
+- Userland memory - page cache and anonymous memory.
+
+- Kernel data structures such as dentries and inodes.
+
+- TCP socket buffers.
+
+The above list may expand in the future for better coverage.
+
+
+Memory Interface Files
+~~~~~~~~~~~~~~~~~~~~~~
+
+All memory amounts are in bytes. If a value which is not aligned to
+PAGE_SIZE is written, the value may be rounded up to the closest
+PAGE_SIZE multiple when read back.
+
+ memory.current
+ A read-only single value file which exists on non-root
+ cgroups.
+
+ The total amount of memory currently being used by the cgroup
+ and its descendants.
+
+ memory.min
+ A read-write single value file which exists on non-root
+ cgroups. The default is "0".
+
+ Hard memory protection. If the memory usage of a cgroup
+ is within its effective min boundary, the cgroup's memory
+ won't be reclaimed under any conditions. If there is no
+ unprotected reclaimable memory available, OOM killer
+ is invoked. Above the effective min boundary (or
+ effective low boundary if it is higher), pages are reclaimed
+ proportionally to the overage, reducing reclaim pressure for
+ smaller overages.
+
+ Effective min boundary is limited by memory.min values of
+ ancestor cgroups. If there is memory.min overcommitment
+ (child cgroup or cgroups are requiring more protected memory
+ than parent will allow), then each child cgroup will get
+ the part of parent's protection proportional to its
+ actual memory usage below memory.min.
+
+ Putting more memory than generally available under this
+ protection is discouraged and may lead to constant OOMs.
+
+ memory.low
+ A read-write single value file which exists on non-root
+ cgroups. The default is "0".
+
+ Best-effort memory protection. If the memory usage of a
+ cgroup is within its effective low boundary, the cgroup's
+ memory won't be reclaimed unless there is no reclaimable
+ memory available in unprotected cgroups.
+ Above the effective low boundary (or
+ effective min boundary if it is higher), pages are reclaimed
+ proportionally to the overage, reducing reclaim pressure for
+ smaller overages.
+
+ Effective low boundary is limited by memory.low values of
+ ancestor cgroups. If there is memory.low overcommitment
+ (child cgroup or cgroups are requiring more protected memory
+ than parent will allow), then each child cgroup will get
+ the part of parent's protection proportional to its
+ actual memory usage below memory.low.
+
+ Putting more memory than generally available under this
+ protection is discouraged.
+
+ memory.high
+ A read-write single value file which exists on non-root
+ cgroups. The default is "max".
+
+ Memory usage throttle limit. If a cgroup's usage goes
+ over the high boundary, the processes of the cgroup are
+ throttled and put under heavy reclaim pressure.
+
+ Going over the high limit never invokes the OOM killer and
+ under extreme conditions the limit may be breached. The high
+ limit should be used in scenarios where an external process
+ monitors the limited cgroup to alleviate heavy reclaim
+ pressure.
+
+ If memory.high is opened with O_NONBLOCK then the synchronous
+ reclaim is bypassed. This is useful for admin processes that
+ need to dynamically adjust the job's memory limits without
+ expending their own CPU resources on memory reclamation. The
+ job will trigger the reclaim and/or get throttled on its
+ next charge request.
+
+ Please note that with O_NONBLOCK, there is a chance that the
+ target memory cgroup may take indefinite amount of time to
+ reduce usage below the limit due to delayed charge request or
+ busy-hitting its memory to slow down reclaim.
+
+ memory.max
+ A read-write single value file which exists on non-root
+ cgroups. The default is "max".
+
+ Memory usage hard limit. This is the main mechanism to limit
+ memory usage of a cgroup. If a cgroup's memory usage reaches
+ this limit and can't be reduced, the OOM killer is invoked in
+ the cgroup. Under certain circumstances, the usage may go
+ over the limit temporarily.
+
+ In default configuration regular 0-order allocations always
+ succeed unless OOM killer chooses current task as a victim.
+
+ Some kinds of allocations don't invoke the OOM killer.
+ Caller could retry them differently, return into userspace
+ as -ENOMEM or silently ignore in cases like disk readahead.
+
+ If memory.max is opened with O_NONBLOCK, then the synchronous
+ reclaim and oom-kill are bypassed. This is useful for admin
+ processes that need to dynamically adjust the job's memory limits
+ without expending their own CPU resources on memory reclamation.
+ The job will trigger the reclaim and/or oom-kill on its next
+ charge request.
+
+ Please note that with O_NONBLOCK, there is a chance that the
+ target memory cgroup may take indefinite amount of time to
+ reduce usage below the limit due to delayed charge request or
+ busy-hitting its memory to slow down reclaim.
+
+ memory.reclaim
+ A write-only nested-keyed file which exists for all cgroups.
+
+ This is a simple interface to trigger memory reclaim in the
+ target cgroup.
+
+ Example::
+
+ echo "1G" > memory.reclaim
+
+ Please note that the kernel can over or under reclaim from
+ the target cgroup. If less bytes are reclaimed than the
+ specified amount, -EAGAIN is returned.
+
+ Please note that the proactive reclaim (triggered by this
+ interface) is not meant to indicate memory pressure on the
+ memory cgroup. Therefore socket memory balancing triggered by
+ the memory reclaim normally is not exercised in this case.
+ This means that the networking layer will not adapt based on
+ reclaim induced by memory.reclaim.
+
+The following nested keys are defined.
+
+ ========== ================================
+ swappiness Swappiness value to reclaim with
+ ========== ================================
+
+ Specifying a swappiness value instructs the kernel to perform
+ the reclaim with that swappiness value. Note that this has the
+ same semantics as vm.swappiness applied to memcg reclaim with
+ all the existing limitations and potential future extensions.
+
+ The valid range for swappiness is [0-200, max], setting
+ swappiness=max exclusively reclaims anonymous memory.
+
+ memory.peak
+ A read-write single value file which exists on non-root cgroups.
+
+ The max memory usage recorded for the cgroup and its descendants since
+ either the creation of the cgroup or the most recent reset for that FD.
+
+ A write of any non-empty string to this file resets it to the
+ current memory usage for subsequent reads through the same
+ file descriptor.
+
+ memory.oom.group
+ A read-write single value file which exists on non-root
+ cgroups. The default value is "0".
+
+ Determines whether the cgroup should be treated as
+ an indivisible workload by the OOM killer. If set,
+ all tasks belonging to the cgroup or to its descendants
+ (if the memory cgroup is not a leaf cgroup) are killed
+ together or not at all. This can be used to avoid
+ partial kills to guarantee workload integrity.
+
+ Tasks with the OOM protection (oom_score_adj set to -1000)
+ are treated as an exception and are never killed.
+
+ If the OOM killer is invoked in a cgroup, it's not going
+ to kill any tasks outside of this cgroup, regardless
+ memory.oom.group values of ancestor cgroups.
+
+ memory.events
+ A read-only flat-keyed file which exists on non-root cgroups.
+ The following entries are defined. Unless specified
+ otherwise, a value change in this file generates a file
+ modified event.
+
+ Note that all fields in this file are hierarchical and the
+ file modified event can be generated due to an event down the
+ hierarchy. For the local events at the cgroup level see
+ memory.events.local.
+
+ low
+ The number of times the cgroup is reclaimed due to
+ high memory pressure even though its usage is under
+ the low boundary. This usually indicates that the low
+ boundary is over-committed.
+
+ high
+ The number of times processes of the cgroup are
+ throttled and routed to perform direct memory reclaim
+ because the high memory boundary was exceeded. For a
+ cgroup whose memory usage is capped by the high limit
+ rather than global memory pressure, this event's
+ occurrences are expected.
+
+ max
+ The number of times the cgroup's memory usage was
+ about to go over the max boundary. If direct reclaim
+ fails to bring it down, the cgroup goes to OOM state.
+
+ oom
+ The number of time the cgroup's memory usage was
+ reached the limit and allocation was about to fail.
+
+ This event is not raised if the OOM killer is not
+ considered as an option, e.g. for failed high-order
+ allocations or if caller asked to not retry attempts.
+
+ oom_kill
+ The number of processes belonging to this cgroup
+ killed by any kind of OOM killer.
+
+ oom_group_kill
+ The number of times a group OOM has occurred.
+
+ sock_throttled
+ The number of times network sockets associated with
+ this cgroup are throttled.
+
+ memory.events.local
+ Similar to memory.events but the fields in the file are local
+ to the cgroup i.e. not hierarchical. The file modified event
+ generated on this file reflects only the local events.
+
+ memory.stat
+ A read-only flat-keyed file which exists on non-root cgroups.
+
+ This breaks down the cgroup's memory footprint into different
+ types of memory, type-specific details, and other information
+ on the state and past events of the memory management system.
+
+ All memory amounts are in bytes.
+
+ The entries are ordered to be human readable, and new entries
+ can show up in the middle. Don't rely on items remaining in a
+ fixed position; use the keys to look up specific values!
+
+ If the entry has no per-node counter (or not show in the
+ memory.numa_stat). We use 'npn' (non-per-node) as the tag
+ to indicate that it will not show in the memory.numa_stat.
+
+ anon
+ Amount of memory used in anonymous mappings such as
+ brk(), sbrk(), and mmap(MAP_ANONYMOUS). Note that
+ some kernel configurations might account complete larger
+ allocations (e.g., THP) if only some, but not all the
+ memory of such an allocation is mapped anymore.
+
+ file
+ Amount of memory used to cache filesystem data,
+ including tmpfs and shared memory.
+
+ kernel (npn)
+ Amount of total kernel memory, including
+ (kernel_stack, pagetables, percpu, vmalloc, slab) in
+ addition to other kernel memory use cases.
+
+ kernel_stack
+ Amount of memory allocated to kernel stacks.
+
+ pagetables
+ Amount of memory allocated for page tables.
+
+ sec_pagetables
+ Amount of memory allocated for secondary page tables,
+ this currently includes KVM mmu allocations on x86
+ and arm64 and IOMMU page tables.
+
+ percpu (npn)
+ Amount of memory used for storing per-cpu kernel
+ data structures.
+
+ sock (npn)
+ Amount of memory used in network transmission buffers
+
+ vmalloc (npn)
+ Amount of memory used for vmap backed memory.
+
+ shmem
+ Amount of cached filesystem data that is swap-backed,
+ such as tmpfs, shm segments, shared anonymous mmap()s
+
+ zswap
+ Amount of memory consumed by the zswap compression backend.
+
+ zswapped
+ Amount of application memory swapped out to zswap.
+
+ file_mapped
+ Amount of cached filesystem data mapped with mmap(). Note
+ that some kernel configurations might account complete
+ larger allocations (e.g., THP) if only some, but not
+ not all the memory of such an allocation is mapped.
+
+ file_dirty
+ Amount of cached filesystem data that was modified but
+ not yet written back to disk
+
+ file_writeback
+ Amount of cached filesystem data that was modified and
+ is currently being written back to disk
+
+ swapcached
+ Amount of swap cached in memory. The swapcache is accounted
+ against both memory and swap usage.
+
+ anon_thp
+ Amount of memory used in anonymous mappings backed by
+ transparent hugepages
+
+ file_thp
+ Amount of cached filesystem data backed by transparent
+ hugepages
+
+ shmem_thp
+ Amount of shm, tmpfs, shared anonymous mmap()s backed by
+ transparent hugepages
+
+ inactive_anon, active_anon, inactive_file, active_file, unevictable
+ Amount of memory, swap-backed and filesystem-backed,
+ on the internal memory management lists used by the
+ page reclaim algorithm.
+
+ As these represent internal list state (eg. shmem pages are on anon
+ memory management lists), inactive_foo + active_foo may not be equal to
+ the value for the foo counter, since the foo counter is type-based, not
+ list-based.
+
+ slab_reclaimable
+ Part of "slab" that might be reclaimed, such as
+ dentries and inodes.
+
+ slab_unreclaimable
+ Part of "slab" that cannot be reclaimed on memory
+ pressure.
+
+ slab (npn)
+ Amount of memory used for storing in-kernel data
+ structures.
+
+ workingset_refault_anon
+ Number of refaults of previously evicted anonymous pages.
+
+ workingset_refault_file
+ Number of refaults of previously evicted file pages.
+
+ workingset_activate_anon
+ Number of refaulted anonymous pages that were immediately
+ activated.
+
+ workingset_activate_file
+ Number of refaulted file pages that were immediately activated.
+
+ workingset_restore_anon
+ Number of restored anonymous pages which have been detected as
+ an active workingset before they got reclaimed.
+
+ workingset_restore_file
+ Number of restored file pages which have been detected as an
+ active workingset before they got reclaimed.
+
+ workingset_nodereclaim
+ Number of times a shadow node has been reclaimed
+
+ pswpin (npn)
+ Number of pages swapped into memory
+
+ pswpout (npn)
+ Number of pages swapped out of memory
+
+ pgscan (npn)
+ Amount of scanned pages (in an inactive LRU list)
+
+ pgsteal (npn)
+ Amount of reclaimed pages
+
+ pgscan_kswapd (npn)
+ Amount of scanned pages by kswapd (in an inactive LRU list)
+
+ pgscan_direct (npn)
+ Amount of scanned pages directly (in an inactive LRU list)
+
+ pgscan_khugepaged (npn)
+ Amount of scanned pages by khugepaged (in an inactive LRU list)
+
+ pgscan_proactive (npn)
+ Amount of scanned pages proactively (in an inactive LRU list)
+
+ pgsteal_kswapd (npn)
+ Amount of reclaimed pages by kswapd
+
+ pgsteal_direct (npn)
+ Amount of reclaimed pages directly
+
+ pgsteal_khugepaged (npn)
+ Amount of reclaimed pages by khugepaged
+
+ pgsteal_proactive (npn)
+ Amount of reclaimed pages proactively
+
+ pgfault (npn)
+ Total number of page faults incurred
+
+ pgmajfault (npn)
+ Number of major page faults incurred
+
+ pgrefill (npn)
+ Amount of scanned pages (in an active LRU list)
+
+ pgactivate (npn)
+ Amount of pages moved to the active LRU list
+
+ pgdeactivate (npn)
+ Amount of pages moved to the inactive LRU list
+
+ pglazyfree (npn)
+ Amount of pages postponed to be freed under memory pressure
+
+ pglazyfreed (npn)
+ Amount of reclaimed lazyfree pages
+
+ swpin_zero
+ Number of pages swapped into memory and filled with zero, where I/O
+ was optimized out because the page content was detected to be zero
+ during swapout.
+
+ swpout_zero
+ Number of zero-filled pages swapped out with I/O skipped due to the
+ content being detected as zero.
+
+ zswpin
+ Number of pages moved in to memory from zswap.
+
+ zswpout
+ Number of pages moved out of memory to zswap.
+
+ zswpwb
+ Number of pages written from zswap to swap.
+
+ thp_fault_alloc (npn)
+ Number of transparent hugepages which were allocated to satisfy
+ a page fault. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE
+ is not set.
+
+ thp_collapse_alloc (npn)
+ Number of transparent hugepages which were allocated to allow
+ collapsing an existing range of pages. This counter is not
+ present when CONFIG_TRANSPARENT_HUGEPAGE is not set.
+
+ thp_swpout (npn)
+ Number of transparent hugepages which are swapout in one piece
+ without splitting.
+
+ thp_swpout_fallback (npn)
+ Number of transparent hugepages which were split before swapout.
+ Usually because failed to allocate some continuous swap space
+ for the huge page.
+
+ numa_pages_migrated (npn)
+ Number of pages migrated by NUMA balancing.
+
+ numa_pte_updates (npn)
+ Number of pages whose page table entries are modified by
+ NUMA balancing to produce NUMA hinting faults on access.
+
+ numa_hint_faults (npn)
+ Number of NUMA hinting faults.
+
+ pgdemote_kswapd
+ Number of pages demoted by kswapd.
+
+ pgdemote_direct
+ Number of pages demoted directly.
+
+ pgdemote_khugepaged
+ Number of pages demoted by khugepaged.
+
+ pgdemote_proactive
+ Number of pages demoted by proactively.
+
+ hugetlb
+ Amount of memory used by hugetlb pages. This metric only shows
+ up if hugetlb usage is accounted for in memory.current (i.e.
+ cgroup is mounted with the memory_hugetlb_accounting option).
+
+ memory.numa_stat
+ A read-only nested-keyed file which exists on non-root cgroups.
+
+ This breaks down the cgroup's memory footprint into different
+ types of memory, type-specific details, and other information
+ per node on the state of the memory management system.
+
+ This is useful for providing visibility into the NUMA locality
+ information within an memcg since the pages are allowed to be
+ allocated from any physical node. One of the use case is evaluating
+ application performance by combining this information with the
+ application's CPU allocation.
+
+ All memory amounts are in bytes.
+
+ The output format of memory.numa_stat is::
+
+ type N0=<bytes in node 0> N1=<bytes in node 1> ...
+
+ The entries are ordered to be human readable, and new entries
+ can show up in the middle. Don't rely on items remaining in a
+ fixed position; use the keys to look up specific values!
+
+ The entries can refer to the memory.stat.
+
+ memory.swap.current
+ A read-only single value file which exists on non-root
+ cgroups.
+
+ The total amount of swap currently being used by the cgroup
+ and its descendants.
+
+ memory.swap.high
+ A read-write single value file which exists on non-root
+ cgroups. The default is "max".
+
+ Swap usage throttle limit. If a cgroup's swap usage exceeds
+ this limit, all its further allocations will be throttled to
+ allow userspace to implement custom out-of-memory procedures.
+
+ This limit marks a point of no return for the cgroup. It is NOT
+ designed to manage the amount of swapping a workload does
+ during regular operation. Compare to memory.swap.max, which
+ prohibits swapping past a set amount, but lets the cgroup
+ continue unimpeded as long as other memory can be reclaimed.
+
+ Healthy workloads are not expected to reach this limit.
+
+ memory.swap.peak
+ A read-write single value file which exists on non-root cgroups.
+
+ The max swap usage recorded for the cgroup and its descendants since
+ the creation of the cgroup or the most recent reset for that FD.
+
+ A write of any non-empty string to this file resets it to the
+ current memory usage for subsequent reads through the same
+ file descriptor.
+
+ memory.swap.max
+ A read-write single value file which exists on non-root
+ cgroups. The default is "max".
+
+ Swap usage hard limit. If a cgroup's swap usage reaches this
+ limit, anonymous memory of the cgroup will not be swapped out.
+
+ memory.swap.events
+ A read-only flat-keyed file which exists on non-root cgroups.
+ The following entries are defined. Unless specified
+ otherwise, a value change in this file generates a file
+ modified event.
+
+ high
+ The number of times the cgroup's swap usage was over
+ the high threshold.
+
+ max
+ The number of times the cgroup's swap usage was about
+ to go over the max boundary and swap allocation
+ failed.
+
+ fail
+ The number of times swap allocation failed either
+ because of running out of swap system-wide or max
+ limit.
+
+ When reduced under the current usage, the existing swap
+ entries are reclaimed gradually and the swap usage may stay
+ higher than the limit for an extended period of time. This
+ reduces the impact on the workload and memory management.
+
+ memory.zswap.current
+ A read-only single value file which exists on non-root
+ cgroups.
+
+ The total amount of memory consumed by the zswap compression
+ backend.
+
+ memory.zswap.max
+ A read-write single value file which exists on non-root
+ cgroups. The default is "max".
+
+ Zswap usage hard limit. If a cgroup's zswap pool reaches this
+ limit, it will refuse to take any more stores before existing
+ entries fault back in or are written out to disk.
+
+ memory.zswap.writeback
+ A read-write single value file. The default value is "1".
+ Note that this setting is hierarchical, i.e. the writeback would be
+ implicitly disabled for child cgroups if the upper hierarchy
+ does so.
+
+ When this is set to 0, all swapping attempts to swapping devices
+ are disabled. This included both zswap writebacks, and swapping due
+ to zswap store failures. If the zswap store failures are recurring
+ (for e.g if the pages are incompressible), users can observe
+ reclaim inefficiency after disabling writeback (because the same
+ pages might be rejected again and again).
+
+ Note that this is subtly different from setting memory.swap.max to
+ 0, as it still allows for pages to be written to the zswap pool.
+ This setting has no effect if zswap is disabled, and swapping
+ is allowed unless memory.swap.max is set to 0.
+
+ memory.pressure
+ A read-only nested-keyed file.
+
+ Shows pressure stall information for memory. See
+ :ref:`Documentation/accounting/psi.rst <psi>` for details.
+
+
+Usage Guidelines
+~~~~~~~~~~~~~~~~
+
+"memory.high" is the main mechanism to control memory usage.
+Over-committing on high limit (sum of high limits > available memory)
+and letting global memory pressure to distribute memory according to
+usage is a viable strategy.
+
+Because breach of the high limit doesn't trigger the OOM killer but
+throttles the offending cgroup, a management agent has ample
+opportunities to monitor and take appropriate actions such as granting
+more memory or terminating the workload.
+
+Determining whether a cgroup has enough memory is not trivial as
+memory usage doesn't indicate whether the workload can benefit from
+more memory. For example, a workload which writes data received from
+network to a file can use all available memory but can also operate as
+performant with a small amount of memory. A measure of memory
+pressure - how much the workload is being impacted due to lack of
+memory - is necessary to determine whether a workload needs more
+memory; unfortunately, memory pressure monitoring mechanism isn't
+implemented yet.
+
+Reclaim Protection
+~~~~~~~~~~~~~~~~~~
+
+The protection configured with "memory.low" or "memory.min" applies relatively
+to the target of the reclaim (i.e. any of memory cgroup limits, proactive
+memory.reclaim or global reclaim apparently located in the root cgroup).
+The protection value configured for B applies unchanged to the reclaim
+targeting A (i.e. caused by competition with the sibling E)::
+
+ root - ... - A - B - C
+ \ ` D
+ ` E
+
+When the reclaim targets ancestors of A, the effective protection of B is
+capped by the protection value configured for A (and any other intermediate
+ancestors between A and the target).
+
+To express indifference about relative sibling protection, it is suggested to
+use memory_recursiveprot. Configuring all descendants of a parent with finite
+protection to "max" works but it may unnecessarily skew memory.events:low
+field.
+
+Memory Ownership
+~~~~~~~~~~~~~~~~
+
+A memory area is charged to the cgroup which instantiated it and stays
+charged to the cgroup until the area is released. Migrating a process
+to a different cgroup doesn't move the memory usages that it
+instantiated while in the previous cgroup to the new cgroup.
+
+A memory area may be used by processes belonging to different cgroups.
+To which cgroup the area will be charged is in-deterministic; however,
+over time, the memory area is likely to end up in a cgroup which has
+enough memory allowance to avoid high reclaim pressure.
+
+If a cgroup sweeps a considerable amount of memory which is expected
+to be accessed repeatedly by other cgroups, it may make sense to use
+POSIX_FADV_DONTNEED to relinquish the ownership of memory areas
+belonging to the affected files to ensure correct memory ownership.
+
+
+IO
+--
+
+The "io" controller regulates the distribution of IO resources. This
+controller implements both weight based and absolute bandwidth or IOPS
+limit distribution; however, weight based distribution is available
+only if cfq-iosched is in use and neither scheme is available for
+blk-mq devices.
+
+
+IO Interface Files
+~~~~~~~~~~~~~~~~~~
+
+ io.stat
+ A read-only nested-keyed file.
+
+ Lines are keyed by $MAJ:$MIN device numbers and not ordered.
+ The following nested keys are defined.
+
+ ====== =====================
+ rbytes Bytes read
+ wbytes Bytes written
+ rios Number of read IOs
+ wios Number of write IOs
+ dbytes Bytes discarded
+ dios Number of discard IOs
+ ====== =====================
+
+ An example read output follows::
+
+ 8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353 dbytes=0 dios=0
+ 8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252 dbytes=50331648 dios=3021
+
+ io.cost.qos
+ A read-write nested-keyed file which exists only on the root
+ cgroup.
+
+ This file configures the Quality of Service of the IO cost
+ model based controller (CONFIG_BLK_CGROUP_IOCOST) which
+ currently implements "io.weight" proportional control. Lines
+ are keyed by $MAJ:$MIN device numbers and not ordered. The
+ line for a given device is populated on the first write for
+ the device on "io.cost.qos" or "io.cost.model". The following
+ nested keys are defined.
+
+ ====== =====================================
+ enable Weight-based control enable
+ ctrl "auto" or "user"
+ rpct Read latency percentile [0, 100]
+ rlat Read latency threshold
+ wpct Write latency percentile [0, 100]
+ wlat Write latency threshold
+ min Minimum scaling percentage [1, 10000]
+ max Maximum scaling percentage [1, 10000]
+ ====== =====================================
+
+ The controller is disabled by default and can be enabled by
+ setting "enable" to 1. "rpct" and "wpct" parameters default
+ to zero and the controller uses internal device saturation
+ state to adjust the overall IO rate between "min" and "max".
+
+ When a better control quality is needed, latency QoS
+ parameters can be configured. For example::
+
+ 8:16 enable=1 ctrl=auto rpct=95.00 rlat=75000 wpct=95.00 wlat=150000 min=50.00 max=150.0
+
+ shows that on sdb, the controller is enabled, will consider
+ the device saturated if the 95th percentile of read completion
+ latencies is above 75ms or write 150ms, and adjust the overall
+ IO issue rate between 50% and 150% accordingly.
+
+ The lower the saturation point, the better the latency QoS at
+ the cost of aggregate bandwidth. The narrower the allowed
+ adjustment range between "min" and "max", the more conformant
+ to the cost model the IO behavior. Note that the IO issue
+ base rate may be far off from 100% and setting "min" and "max"
+ blindly can lead to a significant loss of device capacity or
+ control quality. "min" and "max" are useful for regulating
+ devices which show wide temporary behavior changes - e.g. a
+ ssd which accepts writes at the line speed for a while and
+ then completely stalls for multiple seconds.
+
+ When "ctrl" is "auto", the parameters are controlled by the
+ kernel and may change automatically. Setting "ctrl" to "user"
+ or setting any of the percentile and latency parameters puts
+ it into "user" mode and disables the automatic changes. The
+ automatic mode can be restored by setting "ctrl" to "auto".
+
+ io.cost.model
+ A read-write nested-keyed file which exists only on the root
+ cgroup.
+
+ This file configures the cost model of the IO cost model based
+ controller (CONFIG_BLK_CGROUP_IOCOST) which currently
+ implements "io.weight" proportional control. Lines are keyed
+ by $MAJ:$MIN device numbers and not ordered. The line for a
+ given device is populated on the first write for the device on
+ "io.cost.qos" or "io.cost.model". The following nested keys
+ are defined.
+
+ ===== ================================
+ ctrl "auto" or "user"
+ model The cost model in use - "linear"
+ ===== ================================
+
+ When "ctrl" is "auto", the kernel may change all parameters
+ dynamically. When "ctrl" is set to "user" or any other
+ parameters are written to, "ctrl" become "user" and the
+ automatic changes are disabled.
+
+ When "model" is "linear", the following model parameters are
+ defined.
+
+ ============= ========================================
+ [r|w]bps The maximum sequential IO throughput
+ [r|w]seqiops The maximum 4k sequential IOs per second
+ [r|w]randiops The maximum 4k random IOs per second
+ ============= ========================================
+
+ From the above, the builtin linear model determines the base
+ costs of a sequential and random IO and the cost coefficient
+ for the IO size. While simple, this model can cover most
+ common device classes acceptably.
+
+ The IO cost model isn't expected to be accurate in absolute
+ sense and is scaled to the device behavior dynamically.
+
+ If needed, tools/cgroup/iocost_coef_gen.py can be used to
+ generate device-specific coefficients.
+
+ io.weight
+ A read-write flat-keyed file which exists on non-root cgroups.
+ The default is "default 100".
+
+ The first line is the default weight applied to devices
+ without specific override. The rest are overrides keyed by
+ $MAJ:$MIN device numbers and not ordered. The weights are in
+ the range [1, 10000] and specifies the relative amount IO time
+ the cgroup can use in relation to its siblings.
+
+ The default weight can be updated by writing either "default
+ $WEIGHT" or simply "$WEIGHT". Overrides can be set by writing
+ "$MAJ:$MIN $WEIGHT" and unset by writing "$MAJ:$MIN default".
+
+ An example read output follows::
+
+ default 100
+ 8:16 200
+ 8:0 50
+
+ io.max
+ A read-write nested-keyed file which exists on non-root
+ cgroups.
+
+ BPS and IOPS based IO limit. Lines are keyed by $MAJ:$MIN
+ device numbers and not ordered. The following nested keys are
+ defined.
+
+ ===== ==================================
+ rbps Max read bytes per second
+ wbps Max write bytes per second
+ riops Max read IO operations per second
+ wiops Max write IO operations per second
+ ===== ==================================
+
+ When writing, any number of nested key-value pairs can be
+ specified in any order. "max" can be specified as the value
+ to remove a specific limit. If the same key is specified
+ multiple times, the outcome is undefined.
+
+ BPS and IOPS are measured in each IO direction and IOs are
+ delayed if limit is reached. Temporary bursts are allowed.
+
+ Setting read limit at 2M BPS and write at 120 IOPS for 8:16::
+
+ echo "8:16 rbps=2097152 wiops=120" > io.max
+
+ Reading returns the following::
+
+ 8:16 rbps=2097152 wbps=max riops=max wiops=120
+
+ Write IOPS limit can be removed by writing the following::
+
+ echo "8:16 wiops=max" > io.max
+
+ Reading now returns the following::
+
+ 8:16 rbps=2097152 wbps=max riops=max wiops=max
+
+ io.pressure
+ A read-only nested-keyed file.
+
+ Shows pressure stall information for IO. See
+ :ref:`Documentation/accounting/psi.rst <psi>` for details.
+
+
+Writeback
+~~~~~~~~~
+
+Page cache is dirtied through buffered writes and shared mmaps and
+written asynchronously to the backing filesystem by the writeback
+mechanism. Writeback sits between the memory and IO domains and
+regulates the proportion of dirty memory by balancing dirtying and
+write IOs.
+
+The io controller, in conjunction with the memory controller,
+implements control of page cache writeback IOs. The memory controller
+defines the memory domain that dirty memory ratio is calculated and
+maintained for and the io controller defines the io domain which
+writes out dirty pages for the memory domain. Both system-wide and
+per-cgroup dirty memory states are examined and the more restrictive
+of the two is enforced.
+
+cgroup writeback requires explicit support from the underlying
+filesystem. Currently, cgroup writeback is implemented on ext2, ext4,
+btrfs, f2fs, and xfs. On other filesystems, all writeback IOs are
+attributed to the root cgroup.
+
+There are inherent differences in memory and writeback management
+which affects how cgroup ownership is tracked. Memory is tracked per
+page while writeback per inode. For the purpose of writeback, an
+inode is assigned to a cgroup and all IO requests to write dirty pages
+from the inode are attributed to that cgroup.
+
+As cgroup ownership for memory is tracked per page, there can be pages
+which are associated with different cgroups than the one the inode is
+associated with. These are called foreign pages. The writeback
+constantly keeps track of foreign pages and, if a particular foreign
+cgroup becomes the majority over a certain period of time, switches
+the ownership of the inode to that cgroup.
+
+While this model is enough for most use cases where a given inode is
+mostly dirtied by a single cgroup even when the main writing cgroup
+changes over time, use cases where multiple cgroups write to a single
+inode simultaneously are not supported well. In such circumstances, a
+significant portion of IOs are likely to be attributed incorrectly.
+As memory controller assigns page ownership on the first use and
+doesn't update it until the page is released, even if writeback
+strictly follows page ownership, multiple cgroups dirtying overlapping
+areas wouldn't work as expected. It's recommended to avoid such usage
+patterns.
+
+The sysctl knobs which affect writeback behavior are applied to cgroup
+writeback as follows.
+
+ vm.dirty_background_ratio, vm.dirty_ratio
+ These ratios apply the same to cgroup writeback with the
+ amount of available memory capped by limits imposed by the
+ memory controller and system-wide clean memory.
+
+ vm.dirty_background_bytes, vm.dirty_bytes
+ For cgroup writeback, this is calculated into ratio against
+ total available memory and applied the same way as
+ vm.dirty[_background]_ratio.
+
+
+IO Latency
+~~~~~~~~~~
+
+This is a cgroup v2 controller for IO workload protection. You provide a group
+with a latency target, and if the average latency exceeds that target the
+controller will throttle any peers that have a lower latency target than the
+protected workload.
+
+The limits are only applied at the peer level in the hierarchy. This means that
+in the diagram below, only groups A, B, and C will influence each other, and
+groups D and F will influence each other. Group G will influence nobody::
+
+ [root]
+ / | \
+ A B C
+ / \ |
+ D F G
+
+
+So the ideal way to configure this is to set io.latency in groups A, B, and C.
+Generally you do not want to set a value lower than the latency your device
+supports. Experiment to find the value that works best for your workload.
+Start at higher than the expected latency for your device and watch the
+avg_lat value in io.stat for your workload group to get an idea of the
+latency you see during normal operation. Use the avg_lat value as a basis for
+your real setting, setting at 10-15% higher than the value in io.stat.
+
+How IO Latency Throttling Works
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+io.latency is work conserving; so as long as everybody is meeting their latency
+target the controller doesn't do anything. Once a group starts missing its
+target it begins throttling any peer group that has a higher target than itself.
+This throttling takes 2 forms:
+
+- Queue depth throttling. This is the number of outstanding IO's a group is
+ allowed to have. We will clamp down relatively quickly, starting at no limit
+ and going all the way down to 1 IO at a time.
+
+- Artificial delay induction. There are certain types of IO that cannot be
+ throttled without possibly adversely affecting higher priority groups. This
+ includes swapping and metadata IO. These types of IO are allowed to occur
+ normally, however they are "charged" to the originating group. If the
+ originating group is being throttled you will see the use_delay and delay
+ fields in io.stat increase. The delay value is how many microseconds that are
+ being added to any process that runs in this group. Because this number can
+ grow quite large if there is a lot of swapping or metadata IO occurring we
+ limit the individual delay events to 1 second at a time.
+
+Once the victimized group starts meeting its latency target again it will start
+unthrottling any peer groups that were throttled previously. If the victimized
+group simply stops doing IO the global counter will unthrottle appropriately.
+
+IO Latency Interface Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ io.latency
+ This takes a similar format as the other controllers.
+
+ "MAJOR:MINOR target=<target time in microseconds>"
+
+ io.stat
+ If the controller is enabled you will see extra stats in io.stat in
+ addition to the normal ones.
+
+ depth
+ This is the current queue depth for the group.
+
+ avg_lat
+ This is an exponential moving average with a decay rate of 1/exp
+ bound by the sampling interval. The decay rate interval can be
+ calculated by multiplying the win value in io.stat by the
+ corresponding number of samples based on the win value.
+
+ win
+ The sampling window size in milliseconds. This is the minimum
+ duration of time between evaluation events. Windows only elapse
+ with IO activity. Idle periods extend the most recent window.
+
+IO Priority
+~~~~~~~~~~~
+
+A single attribute controls the behavior of the I/O priority cgroup policy,
+namely the io.prio.class attribute. The following values are accepted for
+that attribute:
+
+ no-change
+ Do not modify the I/O priority class.
+
+ promote-to-rt
+ For requests that have a non-RT I/O priority class, change it into RT.
+ Also change the priority level of these requests to 4. Do not modify
+ the I/O priority of requests that have priority class RT.
+
+ restrict-to-be
+ For requests that do not have an I/O priority class or that have I/O
+ priority class RT, change it into BE. Also change the priority level
+ of these requests to 0. Do not modify the I/O priority class of
+ requests that have priority class IDLE.
+
+ idle
+ Change the I/O priority class of all requests into IDLE, the lowest
+ I/O priority class.
+
+ none-to-rt
+ Deprecated. Just an alias for promote-to-rt.
+
+The following numerical values are associated with the I/O priority policies:
+
++----------------+---+
+| no-change | 0 |
++----------------+---+
+| promote-to-rt | 1 |
++----------------+---+
+| restrict-to-be | 2 |
++----------------+---+
+| idle | 3 |
++----------------+---+
+
+The numerical value that corresponds to each I/O priority class is as follows:
+
++-------------------------------+---+
+| IOPRIO_CLASS_NONE | 0 |
++-------------------------------+---+
+| IOPRIO_CLASS_RT (real-time) | 1 |
++-------------------------------+---+
+| IOPRIO_CLASS_BE (best effort) | 2 |
++-------------------------------+---+
+| IOPRIO_CLASS_IDLE | 3 |
++-------------------------------+---+
+
+The algorithm to set the I/O priority class for a request is as follows:
+
+- If I/O priority class policy is promote-to-rt, change the request I/O
+ priority class to IOPRIO_CLASS_RT and change the request I/O priority
+ level to 4.
+- If I/O priority class policy is not promote-to-rt, translate the I/O priority
+ class policy into a number, then change the request I/O priority class
+ into the maximum of the I/O priority class policy number and the numerical
+ I/O priority class.
+
+PID
+---
+
+The process number controller is used to allow a cgroup to stop any
+new tasks from being fork()'d or clone()'d after a specified limit is
+reached.
+
+The number of tasks in a cgroup can be exhausted in ways which other
+controllers cannot prevent, thus warranting its own controller. For
+example, a fork bomb is likely to exhaust the number of tasks before
+hitting memory restrictions.
+
+Note that PIDs used in this controller refer to TIDs, process IDs as
+used by the kernel.
+
+
+PID Interface Files
+~~~~~~~~~~~~~~~~~~~
+
+ pids.max
+ A read-write single value file which exists on non-root
+ cgroups. The default is "max".
+
+ Hard limit of number of processes.
+
+ pids.current
+ A read-only single value file which exists on non-root cgroups.
+
+ The number of processes currently in the cgroup and its
+ descendants.
+
+ pids.peak
+ A read-only single value file which exists on non-root cgroups.
+
+ The maximum value that the number of processes in the cgroup and its
+ descendants has ever reached.
+
+ pids.events
+ A read-only flat-keyed file which exists on non-root cgroups. Unless
+ specified otherwise, a value change in this file generates a file
+ modified event. The following entries are defined.
+
+ max
+ The number of times the cgroup's total number of processes hit the pids.max
+ limit (see also pids_localevents).
+
+ pids.events.local
+ Similar to pids.events but the fields in the file are local
+ to the cgroup i.e. not hierarchical. The file modified event
+ generated on this file reflects only the local events.
+
+Organisational operations are not blocked by cgroup policies, so it is
+possible to have pids.current > pids.max. This can be done by either
+setting the limit to be smaller than pids.current, or attaching enough
+processes to the cgroup such that pids.current is larger than
+pids.max. However, it is not possible to violate a cgroup PID policy
+through fork() or clone(). These will return -EAGAIN if the creation
+of a new process would cause a cgroup policy to be violated.
+
+
+Cpuset
+------
+
+The "cpuset" controller provides a mechanism for constraining
+the CPU and memory node placement of tasks to only the resources
+specified in the cpuset interface files in a task's current cgroup.
+This is especially valuable on large NUMA systems where placing jobs
+on properly sized subsets of the systems with careful processor and
+memory placement to reduce cross-node memory access and contention
+can improve overall system performance.
+
+The "cpuset" controller is hierarchical. That means the controller
+cannot use CPUs or memory nodes not allowed in its parent.
+
+
+Cpuset Interface Files
+~~~~~~~~~~~~~~~~~~~~~~
+
+ cpuset.cpus
+ A read-write multiple values file which exists on non-root
+ cpuset-enabled cgroups.
+
+ It lists the requested CPUs to be used by tasks within this
+ cgroup. The actual list of CPUs to be granted, however, is
+ subjected to constraints imposed by its parent and can differ
+ from the requested CPUs.
+
+ The CPU numbers are comma-separated numbers or ranges.
+ For example::
+
+ # cat cpuset.cpus
+ 0-4,6,8-10
+
+ An empty value indicates that the cgroup is using the same
+ setting as the nearest cgroup ancestor with a non-empty
+ "cpuset.cpus" or all the available CPUs if none is found.
+
+ The value of "cpuset.cpus" stays constant until the next update
+ and won't be affected by any CPU hotplug events.
+
+ cpuset.cpus.effective
+ A read-only multiple values file which exists on all
+ cpuset-enabled cgroups.
+
+ It lists the onlined CPUs that are actually granted to this
+ cgroup by its parent. These CPUs are allowed to be used by
+ tasks within the current cgroup.
+
+ If "cpuset.cpus" is empty, the "cpuset.cpus.effective" file shows
+ all the CPUs from the parent cgroup that can be available to
+ be used by this cgroup. Otherwise, it should be a subset of
+ "cpuset.cpus" unless none of the CPUs listed in "cpuset.cpus"
+ can be granted. In this case, it will be treated just like an
+ empty "cpuset.cpus".
+
+ Its value will be affected by CPU hotplug events.
+
+ cpuset.mems
+ A read-write multiple values file which exists on non-root
+ cpuset-enabled cgroups.
+
+ It lists the requested memory nodes to be used by tasks within
+ this cgroup. The actual list of memory nodes granted, however,
+ is subjected to constraints imposed by its parent and can differ
+ from the requested memory nodes.
+
+ The memory node numbers are comma-separated numbers or ranges.
+ For example::
+
+ # cat cpuset.mems
+ 0-1,3
+
+ An empty value indicates that the cgroup is using the same
+ setting as the nearest cgroup ancestor with a non-empty
+ "cpuset.mems" or all the available memory nodes if none
+ is found.
+
+ The value of "cpuset.mems" stays constant until the next update
+ and won't be affected by any memory nodes hotplug events.
+
+ Setting a non-empty value to "cpuset.mems" causes memory of
+ tasks within the cgroup to be migrated to the designated nodes if
+ they are currently using memory outside of the designated nodes.
+
+ There is a cost for this memory migration. The migration
+ may not be complete and some memory pages may be left behind.
+ So it is recommended that "cpuset.mems" should be set properly
+ before spawning new tasks into the cpuset. Even if there is
+ a need to change "cpuset.mems" with active tasks, it shouldn't
+ be done frequently.
+
+ cpuset.mems.effective
+ A read-only multiple values file which exists on all
+ cpuset-enabled cgroups.
+
+ It lists the onlined memory nodes that are actually granted to
+ this cgroup by its parent. These memory nodes are allowed to
+ be used by tasks within the current cgroup.
+
+ If "cpuset.mems" is empty, it shows all the memory nodes from the
+ parent cgroup that will be available to be used by this cgroup.
+ Otherwise, it should be a subset of "cpuset.mems" unless none of
+ the memory nodes listed in "cpuset.mems" can be granted. In this
+ case, it will be treated just like an empty "cpuset.mems".
+
+ Its value will be affected by memory nodes hotplug events.
+
+ cpuset.cpus.exclusive
+ A read-write multiple values file which exists on non-root
+ cpuset-enabled cgroups.
+
+ It lists all the exclusive CPUs that are allowed to be used
+ to create a new cpuset partition. Its value is not used
+ unless the cgroup becomes a valid partition root. See the
+ "cpuset.cpus.partition" section below for a description of what
+ a cpuset partition is.
+
+ When the cgroup becomes a partition root, the actual exclusive
+ CPUs that are allocated to that partition are listed in
+ "cpuset.cpus.exclusive.effective" which may be different
+ from "cpuset.cpus.exclusive". If "cpuset.cpus.exclusive"
+ has previously been set, "cpuset.cpus.exclusive.effective"
+ is always a subset of it.
+
+ Users can manually set it to a value that is different from
+ "cpuset.cpus". One constraint in setting it is that the list of
+ CPUs must be exclusive with respect to "cpuset.cpus.exclusive"
+ of its sibling. If "cpuset.cpus.exclusive" of a sibling cgroup
+ isn't set, its "cpuset.cpus" value, if set, cannot be a subset
+ of it to leave at least one CPU available when the exclusive
+ CPUs are taken away.
+
+ For a parent cgroup, any one of its exclusive CPUs can only
+ be distributed to at most one of its child cgroups. Having an
+ exclusive CPU appearing in two or more of its child cgroups is
+ not allowed (the exclusivity rule). A value that violates the
+ exclusivity rule will be rejected with a write error.
+
+ The root cgroup is a partition root and all its available CPUs
+ are in its exclusive CPU set.
+
+ cpuset.cpus.exclusive.effective
+ A read-only multiple values file which exists on all non-root
+ cpuset-enabled cgroups.
+
+ This file shows the effective set of exclusive CPUs that
+ can be used to create a partition root. The content
+ of this file will always be a subset of its parent's
+ "cpuset.cpus.exclusive.effective" if its parent is not the root
+ cgroup. It will also be a subset of "cpuset.cpus.exclusive"
+ if it is set. If "cpuset.cpus.exclusive" is not set, it is
+ treated to have an implicit value of "cpuset.cpus" in the
+ formation of local partition.
+
+ cpuset.cpus.isolated
+ A read-only and root cgroup only multiple values file.
+
+ This file shows the set of all isolated CPUs used in existing
+ isolated partitions. It will be empty if no isolated partition
+ is created.
+
+ cpuset.cpus.partition
+ A read-write single value file which exists on non-root
+ cpuset-enabled cgroups. This flag is owned by the parent cgroup
+ and is not delegatable.
+
+ It accepts only the following input values when written to.
+
+ ========== =====================================
+ "member" Non-root member of a partition
+ "root" Partition root
+ "isolated" Partition root without load balancing
+ ========== =====================================
+
+ A cpuset partition is a collection of cpuset-enabled cgroups with
+ a partition root at the top of the hierarchy and its descendants
+ except those that are separate partition roots themselves and
+ their descendants. A partition has exclusive access to the
+ set of exclusive CPUs allocated to it. Other cgroups outside
+ of that partition cannot use any CPUs in that set.
+
+ There are two types of partitions - local and remote. A local
+ partition is one whose parent cgroup is also a valid partition
+ root. A remote partition is one whose parent cgroup is not a
+ valid partition root itself. Writing to "cpuset.cpus.exclusive"
+ is optional for the creation of a local partition as its
+ "cpuset.cpus.exclusive" file will assume an implicit value that
+ is the same as "cpuset.cpus" if it is not set. Writing the
+ proper "cpuset.cpus.exclusive" values down the cgroup hierarchy
+ before the target partition root is mandatory for the creation
+ of a remote partition.
+
+ Currently, a remote partition cannot be created under a local
+ partition. All the ancestors of a remote partition root except
+ the root cgroup cannot be a partition root.
+
+ The root cgroup is always a partition root and its state cannot
+ be changed. All other non-root cgroups start out as "member".
+
+ When set to "root", the current cgroup is the root of a new
+ partition or scheduling domain. The set of exclusive CPUs is
+ determined by the value of its "cpuset.cpus.exclusive.effective".
+
+ When set to "isolated", the CPUs in that partition will be in
+ an isolated state without any load balancing from the scheduler
+ and excluded from the unbound workqueues. Tasks placed in such
+ a partition with multiple CPUs should be carefully distributed
+ and bound to each of the individual CPUs for optimal performance.
+
+ A partition root ("root" or "isolated") can be in one of the
+ two possible states - valid or invalid. An invalid partition
+ root is in a degraded state where some state information may
+ be retained, but behaves more like a "member".
+
+ All possible state transitions among "member", "root" and
+ "isolated" are allowed.
+
+ On read, the "cpuset.cpus.partition" file can show the following
+ values.
+
+ ============================= =====================================
+ "member" Non-root member of a partition
+ "root" Partition root
+ "isolated" Partition root without load balancing
+ "root invalid (<reason>)" Invalid partition root
+ "isolated invalid (<reason>)" Invalid isolated partition root
+ ============================= =====================================
+
+ In the case of an invalid partition root, a descriptive string on
+ why the partition is invalid is included within parentheses.
+
+ For a local partition root to be valid, the following conditions
+ must be met.
+
+ 1) The parent cgroup is a valid partition root.
+ 2) The "cpuset.cpus.exclusive.effective" file cannot be empty,
+ though it may contain offline CPUs.
+ 3) The "cpuset.cpus.effective" cannot be empty unless there is
+ no task associated with this partition.
+
+ For a remote partition root to be valid, all the above conditions
+ except the first one must be met.
+
+ External events like hotplug or changes to "cpuset.cpus" or
+ "cpuset.cpus.exclusive" can cause a valid partition root to
+ become invalid and vice versa. Note that a task cannot be
+ moved to a cgroup with empty "cpuset.cpus.effective".
+
+ A valid non-root parent partition may distribute out all its CPUs
+ to its child local partitions when there is no task associated
+ with it.
+
+ Care must be taken to change a valid partition root to "member"
+ as all its child local partitions, if present, will become
+ invalid causing disruption to tasks running in those child
+ partitions. These inactivated partitions could be recovered if
+ their parent is switched back to a partition root with a proper
+ value in "cpuset.cpus" or "cpuset.cpus.exclusive".
+
+ Poll and inotify events are triggered whenever the state of
+ "cpuset.cpus.partition" changes. That includes changes caused
+ by write to "cpuset.cpus.partition", cpu hotplug or other
+ changes that modify the validity status of the partition.
+ This will allow user space agents to monitor unexpected changes
+ to "cpuset.cpus.partition" without the need to do continuous
+ polling.
+
+ A user can pre-configure certain CPUs to an isolated state
+ with load balancing disabled at boot time with the "isolcpus"
+ kernel boot command line option. If those CPUs are to be put
+ into a partition, they have to be used in an isolated partition.
+
+
+Device controller
+-----------------
+
+Device controller manages access to device files. It includes both
+creation of new device files (using mknod), and access to the
+existing device files.
+
+Cgroup v2 device controller has no interface files and is implemented
+on top of cgroup BPF. To control access to device files, a user may
+create bpf programs of type BPF_PROG_TYPE_CGROUP_DEVICE and attach
+them to cgroups with BPF_CGROUP_DEVICE flag. On an attempt to access a
+device file, corresponding BPF programs will be executed, and depending
+on the return value the attempt will succeed or fail with -EPERM.
+
+A BPF_PROG_TYPE_CGROUP_DEVICE program takes a pointer to the
+bpf_cgroup_dev_ctx structure, which describes the device access attempt:
+access type (mknod/read/write) and device (type, major and minor numbers).
+If the program returns 0, the attempt fails with -EPERM, otherwise it
+succeeds.
+
+An example of BPF_PROG_TYPE_CGROUP_DEVICE program may be found in
+tools/testing/selftests/bpf/progs/dev_cgroup.c in the kernel source tree.
+
+
+RDMA
+----
+
+The "rdma" controller regulates the distribution and accounting of
+RDMA resources.
+
+RDMA Interface Files
+~~~~~~~~~~~~~~~~~~~~
+
+ rdma.max
+ A readwrite nested-keyed file that exists for all the cgroups
+ except root that describes current configured resource limit
+ for a RDMA/IB device.
+
+ Lines are keyed by device name and are not ordered.
+ Each line contains space separated resource name and its configured
+ limit that can be distributed.
+
+ The following nested keys are defined.
+
+ ========== =============================
+ hca_handle Maximum number of HCA Handles
+ hca_object Maximum number of HCA Objects
+ ========== =============================
+
+ An example for mlx4 and ocrdma device follows::
+
+ mlx4_0 hca_handle=2 hca_object=2000
+ ocrdma1 hca_handle=3 hca_object=max
+
+ rdma.current
+ A read-only file that describes current resource usage.
+ It exists for all the cgroup except root.
+
+ An example for mlx4 and ocrdma device follows::
+
+ mlx4_0 hca_handle=1 hca_object=20
+ ocrdma1 hca_handle=1 hca_object=23
+
+DMEM
+----
+
+The "dmem" controller regulates the distribution and accounting of
+device memory regions. Because each memory region may have its own page size,
+which does not have to be equal to the system page size, the units are always bytes.
+
+DMEM Interface Files
+~~~~~~~~~~~~~~~~~~~~
+
+ dmem.max, dmem.min, dmem.low
+ A readwrite nested-keyed file that exists for all the cgroups
+ except root that describes current configured resource limit
+ for a region.
+
+ An example for xe follows::
+
+ drm/0000:03:00.0/vram0 1073741824
+ drm/0000:03:00.0/stolen max
+
+ The semantics are the same as for the memory cgroup controller, and are
+ calculated in the same way.
+
+ dmem.capacity
+ A read-only file that describes maximum region capacity.
+ It only exists on the root cgroup. Not all memory can be
+ allocated by cgroups, as the kernel reserves some for
+ internal use.
+
+ An example for xe follows::
+
+ drm/0000:03:00.0/vram0 8514437120
+ drm/0000:03:00.0/stolen 67108864
+
+ dmem.current
+ A read-only file that describes current resource usage.
+ It exists for all the cgroup except root.
+
+ An example for xe follows::
+
+ drm/0000:03:00.0/vram0 12550144
+ drm/0000:03:00.0/stolen 8650752
+
+HugeTLB
+-------
+
+The HugeTLB controller allows to limit the HugeTLB usage per control group and
+enforces the controller limit during page fault.
+
+HugeTLB Interface Files
+~~~~~~~~~~~~~~~~~~~~~~~
+
+ hugetlb.<hugepagesize>.current
+ Show current usage for "hugepagesize" hugetlb. It exists for all
+ the cgroup except root.
+
+ hugetlb.<hugepagesize>.max
+ Set/show the hard limit of "hugepagesize" hugetlb usage.
+ The default value is "max". It exists for all the cgroup except root.
+
+ hugetlb.<hugepagesize>.events
+ A read-only flat-keyed file which exists on non-root cgroups.
+
+ max
+ The number of allocation failure due to HugeTLB limit
+
+ hugetlb.<hugepagesize>.events.local
+ Similar to hugetlb.<hugepagesize>.events but the fields in the file
+ are local to the cgroup i.e. not hierarchical. The file modified event
+ generated on this file reflects only the local events.
+
+ hugetlb.<hugepagesize>.numa_stat
+ Similar to memory.numa_stat, it shows the numa information of the
+ hugetlb pages of <hugepagesize> in this cgroup. Only active in
+ use hugetlb pages are included. The per-node values are in bytes.
+
+Misc
+----
+
+The Miscellaneous cgroup provides the resource limiting and tracking
+mechanism for the scalar resources which cannot be abstracted like the other
+cgroup resources. Controller is enabled by the CONFIG_CGROUP_MISC config
+option.
+
+A resource can be added to the controller via enum misc_res_type{} in the
+include/linux/misc_cgroup.h file and the corresponding name via misc_res_name[]
+in the kernel/cgroup/misc.c file. Provider of the resource must set its
+capacity prior to using the resource by calling misc_cg_set_capacity().
+
+Once a capacity is set then the resource usage can be updated using charge and
+uncharge APIs. All of the APIs to interact with misc controller are in
+include/linux/misc_cgroup.h.
+
+Misc Interface Files
+~~~~~~~~~~~~~~~~~~~~
+
+Miscellaneous controller provides 3 interface files. If two misc resources (res_a and res_b) are registered then:
+
+ misc.capacity
+ A read-only flat-keyed file shown only in the root cgroup. It shows
+ miscellaneous scalar resources available on the platform along with
+ their quantities::
+
+ $ cat misc.capacity
+ res_a 50
+ res_b 10
+
+ misc.current
+ A read-only flat-keyed file shown in the all cgroups. It shows
+ the current usage of the resources in the cgroup and its children.::
+
+ $ cat misc.current
+ res_a 3
+ res_b 0
+
+ misc.peak
+ A read-only flat-keyed file shown in all cgroups. It shows the
+ historical maximum usage of the resources in the cgroup and its
+ children.::
+
+ $ cat misc.peak
+ res_a 10
+ res_b 8
+
+ misc.max
+ A read-write flat-keyed file shown in the non root cgroups. Allowed
+ maximum usage of the resources in the cgroup and its children.::
+
+ $ cat misc.max
+ res_a max
+ res_b 4
+
+ Limit can be set by::
+
+ # echo res_a 1 > misc.max
+
+ Limit can be set to max by::
+
+ # echo res_a max > misc.max
+
+ Limits can be set higher than the capacity value in the misc.capacity
+ file.
+
+ misc.events
+ A read-only flat-keyed file which exists on non-root cgroups. The
+ following entries are defined. Unless specified otherwise, a value
+ change in this file generates a file modified event. All fields in
+ this file are hierarchical.
+
+ max
+ The number of times the cgroup's resource usage was
+ about to go over the max boundary.
+
+ misc.events.local
+ Similar to misc.events but the fields in the file are local to the
+ cgroup i.e. not hierarchical. The file modified event generated on
+ this file reflects only the local events.
+
+Migration and Ownership
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A miscellaneous scalar resource is charged to the cgroup in which it is used
+first, and stays charged to that cgroup until that resource is freed. Migrating
+a process to a different cgroup does not move the charge to the destination
+cgroup where the process has moved.
+
+Others
+------
+
+perf_event
+~~~~~~~~~~
+
+perf_event controller, if not mounted on a legacy hierarchy, is
+automatically enabled on the v2 hierarchy so that perf events can
+always be filtered by cgroup v2 path. The controller can still be
+moved to a legacy hierarchy after v2 hierarchy is populated.
+
+
+Non-normative information
+-------------------------
+
+This section contains information that isn't considered to be a part of
+the stable kernel API and so is subject to change.
+
+
+CPU controller root cgroup process behaviour
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When distributing CPU cycles in the root cgroup each thread in this
+cgroup is treated as if it was hosted in a separate child cgroup of the
+root cgroup. This child cgroup weight is dependent on its thread nice
+level.
+
+For details of this mapping see sched_prio_to_weight array in
+kernel/sched/core.c file (values from this array should be scaled
+appropriately so the neutral - nice 0 - value is 100 instead of 1024).
+
+
+IO controller root cgroup process behaviour
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Root cgroup processes are hosted in an implicit leaf child node.
+When distributing IO resources this implicit child node is taken into
+account as if it was a normal child cgroup of the root cgroup with a
+weight value of 200.
+
+
+Namespace
+=========
+
+Basics
+------
+
+cgroup namespace provides a mechanism to virtualize the view of the
+"/proc/$PID/cgroup" file and cgroup mounts. The CLONE_NEWCGROUP clone
+flag can be used with clone(2) and unshare(2) to create a new cgroup
+namespace. The process running inside the cgroup namespace will have
+its "/proc/$PID/cgroup" output restricted to cgroupns root. The
+cgroupns root is the cgroup of the process at the time of creation of
+the cgroup namespace.
+
+Without cgroup namespace, the "/proc/$PID/cgroup" file shows the
+complete path of the cgroup of a process. In a container setup where
+a set of cgroups and namespaces are intended to isolate processes the
+"/proc/$PID/cgroup" file may leak potential system level information
+to the isolated processes. For example::
+
+ # cat /proc/self/cgroup
+ 0::/batchjobs/container_id1
+
+The path '/batchjobs/container_id1' can be considered as system-data
+and undesirable to expose to the isolated processes. cgroup namespace
+can be used to restrict visibility of this path. For example, before
+creating a cgroup namespace, one would see::
+
+ # ls -l /proc/self/ns/cgroup
+ lrwxrwxrwx 1 root root 0 2014-07-15 10:37 /proc/self/ns/cgroup -> cgroup:[4026531835]
+ # cat /proc/self/cgroup
+ 0::/batchjobs/container_id1
+
+After unsharing a new namespace, the view changes::
+
+ # ls -l /proc/self/ns/cgroup
+ lrwxrwxrwx 1 root root 0 2014-07-15 10:35 /proc/self/ns/cgroup -> cgroup:[4026532183]
+ # cat /proc/self/cgroup
+ 0::/
+
+When some thread from a multi-threaded process unshares its cgroup
+namespace, the new cgroupns gets applied to the entire process (all
+the threads). This is natural for the v2 hierarchy; however, for the
+legacy hierarchies, this may be unexpected.
+
+A cgroup namespace is alive as long as there are processes inside or
+mounts pinning it. When the last usage goes away, the cgroup
+namespace is destroyed. The cgroupns root and the actual cgroups
+remain.
+
+
+The Root and Views
+------------------
+
+The 'cgroupns root' for a cgroup namespace is the cgroup in which the
+process calling unshare(2) is running. For example, if a process in
+/batchjobs/container_id1 cgroup calls unshare, cgroup
+/batchjobs/container_id1 becomes the cgroupns root. For the
+init_cgroup_ns, this is the real root ('/') cgroup.
+
+The cgroupns root cgroup does not change even if the namespace creator
+process later moves to a different cgroup::
+
+ # ~/unshare -c # unshare cgroupns in some cgroup
+ # cat /proc/self/cgroup
+ 0::/
+ # mkdir sub_cgrp_1
+ # echo 0 > sub_cgrp_1/cgroup.procs
+ # cat /proc/self/cgroup
+ 0::/sub_cgrp_1
+
+Each process gets its namespace-specific view of "/proc/$PID/cgroup"
+
+Processes running inside the cgroup namespace will be able to see
+cgroup paths (in /proc/self/cgroup) only inside their root cgroup.
+From within an unshared cgroupns::
+
+ # sleep 100000 &
+ [1] 7353
+ # echo 7353 > sub_cgrp_1/cgroup.procs
+ # cat /proc/7353/cgroup
+ 0::/sub_cgrp_1
+
+From the initial cgroup namespace, the real cgroup path will be
+visible::
+
+ $ cat /proc/7353/cgroup
+ 0::/batchjobs/container_id1/sub_cgrp_1
+
+From a sibling cgroup namespace (that is, a namespace rooted at a
+different cgroup), the cgroup path relative to its own cgroup
+namespace root will be shown. For instance, if PID 7353's cgroup
+namespace root is at '/batchjobs/container_id2', then it will see::
+
+ # cat /proc/7353/cgroup
+ 0::/../container_id2/sub_cgrp_1
+
+Note that the relative path always starts with '/' to indicate that
+its relative to the cgroup namespace root of the caller.
+
+
+Migration and setns(2)
+----------------------
+
+Processes inside a cgroup namespace can move into and out of the
+namespace root if they have proper access to external cgroups. For
+example, from inside a namespace with cgroupns root at
+/batchjobs/container_id1, and assuming that the global hierarchy is
+still accessible inside cgroupns::
+
+ # cat /proc/7353/cgroup
+ 0::/sub_cgrp_1
+ # echo 7353 > batchjobs/container_id2/cgroup.procs
+ # cat /proc/7353/cgroup
+ 0::/../container_id2
+
+Note that this kind of setup is not encouraged. A task inside cgroup
+namespace should only be exposed to its own cgroupns hierarchy.
+
+setns(2) to another cgroup namespace is allowed when:
+
+(a) the process has CAP_SYS_ADMIN against its current user namespace
+(b) the process has CAP_SYS_ADMIN against the target cgroup
+ namespace's userns
+
+No implicit cgroup changes happen with attaching to another cgroup
+namespace. It is expected that the someone moves the attaching
+process under the target cgroup namespace root.
+
+
+Interaction with Other Namespaces
+---------------------------------
+
+Namespace specific cgroup hierarchy can be mounted by a process
+running inside a non-init cgroup namespace::
+
+ # mount -t cgroup2 none $MOUNT_POINT
+
+This will mount the unified cgroup hierarchy with cgroupns root as the
+filesystem root. The process needs CAP_SYS_ADMIN against its user and
+mount namespaces.
+
+The virtualization of /proc/self/cgroup file combined with restricting
+the view of cgroup hierarchy by namespace-private cgroupfs mount
+provides a properly isolated cgroup view inside the container.
+
+
+Information on Kernel Programming
+=================================
+
+This section contains kernel programming information in the areas
+where interacting with cgroup is necessary. cgroup core and
+controllers are not covered.
+
+
+Filesystem Support for Writeback
+--------------------------------
+
+A filesystem can support cgroup writeback by updating
+address_space_operations->writepages() to annotate bio's using the
+following two functions.
+
+ wbc_init_bio(@wbc, @bio)
+ Should be called for each bio carrying writeback data and
+ associates the bio with the inode's owner cgroup and the
+ corresponding request queue. This must be called after
+ a queue (device) has been associated with the bio and
+ before submission.
+
+ wbc_account_cgroup_owner(@wbc, @folio, @bytes)
+ Should be called for each data segment being written out.
+ While this function doesn't care exactly when it's called
+ during the writeback session, it's the easiest and most
+ natural to call it as data segments are added to a bio.
+
+With writeback bio's annotated, cgroup support can be enabled per
+super_block by setting SB_I_CGROUPWB in ->s_iflags. This allows for
+selective disabling of cgroup writeback support which is helpful when
+certain filesystem features, e.g. journaled data mode, are
+incompatible.
+
+wbc_init_bio() binds the specified bio to its cgroup. Depending on
+the configuration, the bio may be executed at a lower priority and if
+the writeback session is holding shared resources, e.g. a journal
+entry, may lead to priority inversion. There is no one easy solution
+for the problem. Filesystems can try to work around specific problem
+cases by skipping wbc_init_bio() and using bio_associate_blkg()
+directly.
+
+
+Deprecated v1 Core Features
+===========================
+
+- Multiple hierarchies including named ones are not supported.
+
+- All v1 mount options are not supported.
+
+- The "tasks" file is removed and "cgroup.procs" is not sorted.
+
+- "cgroup.clone_children" is removed.
+
+- /proc/cgroups is meaningless for v2. Use "cgroup.controllers" or
+ "cgroup.stat" files at the root instead.
+
+
+Issues with v1 and Rationales for v2
+====================================
+
+Multiple Hierarchies
+--------------------
+
+cgroup v1 allowed an arbitrary number of hierarchies and each
+hierarchy could host any number of controllers. While this seemed to
+provide a high level of flexibility, it wasn't useful in practice.
+
+For example, as there is only one instance of each controller, utility
+type controllers such as freezer which can be useful in all
+hierarchies could only be used in one. The issue is exacerbated by
+the fact that controllers couldn't be moved to another hierarchy once
+hierarchies were populated. Another issue was that all controllers
+bound to a hierarchy were forced to have exactly the same view of the
+hierarchy. It wasn't possible to vary the granularity depending on
+the specific controller.
+
+In practice, these issues heavily limited which controllers could be
+put on the same hierarchy and most configurations resorted to putting
+each controller on its own hierarchy. Only closely related ones, such
+as the cpu and cpuacct controllers, made sense to be put on the same
+hierarchy. This often meant that userland ended up managing multiple
+similar hierarchies repeating the same steps on each hierarchy
+whenever a hierarchy management operation was necessary.
+
+Furthermore, support for multiple hierarchies came at a steep cost.
+It greatly complicated cgroup core implementation but more importantly
+the support for multiple hierarchies restricted how cgroup could be
+used in general and what controllers was able to do.
+
+There was no limit on how many hierarchies there might be, which meant
+that a thread's cgroup membership couldn't be described in finite
+length. The key might contain any number of entries and was unlimited
+in length, which made it highly awkward to manipulate and led to
+addition of controllers which existed only to identify membership,
+which in turn exacerbated the original problem of proliferating number
+of hierarchies.
+
+Also, as a controller couldn't have any expectation regarding the
+topologies of hierarchies other controllers might be on, each
+controller had to assume that all other controllers were attached to
+completely orthogonal hierarchies. This made it impossible, or at
+least very cumbersome, for controllers to cooperate with each other.
+
+In most use cases, putting controllers on hierarchies which are
+completely orthogonal to each other isn't necessary. What usually is
+called for is the ability to have differing levels of granularity
+depending on the specific controller. In other words, hierarchy may
+be collapsed from leaf towards root when viewed from specific
+controllers. For example, a given configuration might not care about
+how memory is distributed beyond a certain level while still wanting
+to control how CPU cycles are distributed.
+
+
+Thread Granularity
+------------------
+
+cgroup v1 allowed threads of a process to belong to different cgroups.
+This didn't make sense for some controllers and those controllers
+ended up implementing different ways to ignore such situations but
+much more importantly it blurred the line between API exposed to
+individual applications and system management interface.
+
+Generally, in-process knowledge is available only to the process
+itself; thus, unlike service-level organization of processes,
+categorizing threads of a process requires active participation from
+the application which owns the target process.
+
+cgroup v1 had an ambiguously defined delegation model which got abused
+in combination with thread granularity. cgroups were delegated to
+individual applications so that they can create and manage their own
+sub-hierarchies and control resource distributions along them. This
+effectively raised cgroup to the status of a syscall-like API exposed
+to lay programs.
+
+First of all, cgroup has a fundamentally inadequate interface to be
+exposed this way. For a process to access its own knobs, it has to
+extract the path on the target hierarchy from /proc/self/cgroup,
+construct the path by appending the name of the knob to the path, open
+and then read and/or write to it. This is not only extremely clunky
+and unusual but also inherently racy. There is no conventional way to
+define transaction across the required steps and nothing can guarantee
+that the process would actually be operating on its own sub-hierarchy.
+
+cgroup controllers implemented a number of knobs which would never be
+accepted as public APIs because they were just adding control knobs to
+system-management pseudo filesystem. cgroup ended up with interface
+knobs which were not properly abstracted or refined and directly
+revealed kernel internal details. These knobs got exposed to
+individual applications through the ill-defined delegation mechanism
+effectively abusing cgroup as a shortcut to implementing public APIs
+without going through the required scrutiny.
+
+This was painful for both userland and kernel. Userland ended up with
+misbehaving and poorly abstracted interfaces and kernel exposing and
+locked into constructs inadvertently.
+
+
+Competition Between Inner Nodes and Threads
+-------------------------------------------
+
+cgroup v1 allowed threads to be in any cgroups which created an
+interesting problem where threads belonging to a parent cgroup and its
+children cgroups competed for resources. This was nasty as two
+different types of entities competed and there was no obvious way to
+settle it. Different controllers did different things.
+
+The cpu controller considered threads and cgroups as equivalents and
+mapped nice levels to cgroup weights. This worked for some cases but
+fell flat when children wanted to be allocated specific ratios of CPU
+cycles and the number of internal threads fluctuated - the ratios
+constantly changed as the number of competing entities fluctuated.
+There also were other issues. The mapping from nice level to weight
+wasn't obvious or universal, and there were various other knobs which
+simply weren't available for threads.
+
+The io controller implicitly created a hidden leaf node for each
+cgroup to host the threads. The hidden leaf had its own copies of all
+the knobs with ``leaf_`` prefixed. While this allowed equivalent
+control over internal threads, it was with serious drawbacks. It
+always added an extra layer of nesting which wouldn't be necessary
+otherwise, made the interface messy and significantly complicated the
+implementation.
+
+The memory controller didn't have a way to control what happened
+between internal tasks and child cgroups and the behavior was not
+clearly defined. There were attempts to add ad-hoc behaviors and
+knobs to tailor the behavior to specific workloads which would have
+led to problems extremely difficult to resolve in the long term.
+
+Multiple controllers struggled with internal tasks and came up with
+different ways to deal with it; unfortunately, all the approaches were
+severely flawed and, furthermore, the widely different behaviors
+made cgroup as a whole highly inconsistent.
+
+This clearly is a problem which needs to be addressed from cgroup core
+in a uniform way.
+
+
+Other Interface Issues
+----------------------
+
+cgroup v1 grew without oversight and developed a large number of
+idiosyncrasies and inconsistencies. One issue on the cgroup core side
+was how an empty cgroup was notified - a userland helper binary was
+forked and executed for each event. The event delivery wasn't
+recursive or delegatable. The limitations of the mechanism also led
+to in-kernel event delivery filtering mechanism further complicating
+the interface.
+
+Controller interfaces were problematic too. An extreme example is
+controllers completely ignoring hierarchical organization and treating
+all cgroups as if they were all located directly under the root
+cgroup. Some controllers exposed a large amount of inconsistent
+implementation details to userland.
+
+There also was no consistency across controllers. When a new cgroup
+was created, some controllers defaulted to not imposing extra
+restrictions while others disallowed any resource usage until
+explicitly configured. Configuration knobs for the same type of
+control used widely differing naming schemes and formats. Statistics
+and information knobs were named arbitrarily and used different
+formats and units even in the same controller.
+
+cgroup v2 establishes common conventions where appropriate and updates
+controllers so that they expose minimal and consistent interfaces.
+
+
+Controller Issues and Remedies
+------------------------------
+
+Memory
+~~~~~~
+
+The original lower boundary, the soft limit, is defined as a limit
+that is per default unset. As a result, the set of cgroups that
+global reclaim prefers is opt-in, rather than opt-out. The costs for
+optimizing these mostly negative lookups are so high that the
+implementation, despite its enormous size, does not even provide the
+basic desirable behavior. First off, the soft limit has no
+hierarchical meaning. All configured groups are organized in a global
+rbtree and treated like equal peers, regardless where they are located
+in the hierarchy. This makes subtree delegation impossible. Second,
+the soft limit reclaim pass is so aggressive that it not just
+introduces high allocation latencies into the system, but also impacts
+system performance due to overreclaim, to the point where the feature
+becomes self-defeating.
+
+The memory.low boundary on the other hand is a top-down allocated
+reserve. A cgroup enjoys reclaim protection when it's within its
+effective low, which makes delegation of subtrees possible. It also
+enjoys having reclaim pressure proportional to its overage when
+above its effective low.
+
+The original high boundary, the hard limit, is defined as a strict
+limit that can not budge, even if the OOM killer has to be called.
+But this generally goes against the goal of making the most out of the
+available memory. The memory consumption of workloads varies during
+runtime, and that requires users to overcommit. But doing that with a
+strict upper limit requires either a fairly accurate prediction of the
+working set size or adding slack to the limit. Since working set size
+estimation is hard and error prone, and getting it wrong results in
+OOM kills, most users tend to err on the side of a looser limit and
+end up wasting precious resources.
+
+The memory.high boundary on the other hand can be set much more
+conservatively. When hit, it throttles allocations by forcing them
+into direct reclaim to work off the excess, but it never invokes the
+OOM killer. As a result, a high boundary that is chosen too
+aggressively will not terminate the processes, but instead it will
+lead to gradual performance degradation. The user can monitor this
+and make corrections until the minimal memory footprint that still
+gives acceptable performance is found.
+
+In extreme cases, with many concurrent allocations and a complete
+breakdown of reclaim progress within the group, the high boundary can
+be exceeded. But even then it's mostly better to satisfy the
+allocation from the slack available in other groups or the rest of the
+system than killing the group. Otherwise, memory.max is there to
+limit this type of spillover and ultimately contain buggy or even
+malicious applications.
+
+Setting the original memory.limit_in_bytes below the current usage was
+subject to a race condition, where concurrent charges could cause the
+limit setting to fail. memory.max on the other hand will first set the
+limit to prevent new charges, and then reclaim and OOM kill until the
+new limit is met - or the task writing to memory.max is killed.
+
+The combined memory+swap accounting and limiting is replaced by real
+control over swap space.
+
+The main argument for a combined memory+swap facility in the original
+cgroup design was that global or parental pressure would always be
+able to swap all anonymous memory of a child group, regardless of the
+child's own (possibly untrusted) configuration. However, untrusted
+groups can sabotage swapping by other means - such as referencing its
+anonymous memory in a tight loop - and an admin can not assume full
+swappability when overcommitting untrusted jobs.
+
+For trusted jobs, on the other hand, a combined counter is not an
+intuitive userspace interface, and it flies in the face of the idea
+that cgroup controllers should account and limit specific physical
+resources. Swap space is a resource like all others in the system,
+and that's why unified hierarchy allows distributing it separately.
diff --git a/Documentation/admin-guide/cifs/authors.rst b/Documentation/admin-guide/cifs/authors.rst
new file mode 100644
index 000000000000..5c1d2f0fa7d1
--- /dev/null
+++ b/Documentation/admin-guide/cifs/authors.rst
@@ -0,0 +1,69 @@
+=======
+Authors
+=======
+
+Original Author
+---------------
+
+Steve French (smfrench@gmail.com, sfrench@samba.org)
+
+The author wishes to express his appreciation and thanks to:
+Andrew Tridgell (Samba team) for his early suggestions about SMB/CIFS VFS
+improvements. Thanks to IBM for allowing me time and test resources to pursue
+this project, to Jim McDonough from IBM (and the Samba Team) for his help, to
+the IBM Linux JFS team for explaining many esoteric Linux filesystem features.
+Jeremy Allison of the Samba team has done invaluable work in adding the server
+side of the original CIFS Unix extensions and reviewing and implementing
+portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
+Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
+for proving years ago that very good smb/cifs clients could be done on Unix-like
+operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
+Newbigin and others for their work on the Linux smbfs module. Thanks to
+the other members of the Storage Network Industry Association CIFS Technical
+Workgroup for their work specifying this highly complex protocol and finally
+thanks to the Samba team for their technical advice and encouragement.
+
+Patch Contributors
+------------------
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara (for some excellent work in DFS, and in booting from SMB3)
+- Long Li (some great work on RDMA, SMB Direct)
+
+
+Test case and Bug Report contributors
+-------------------------------------
+Thanks to those in the community who have submitted detailed bug reports
+and debug of problems they have found: Jochen Dolze, David Blaine,
+Rene Scharfe, Martin Josefsson, Alexander Wild, Anthony Liguori,
+Lars Muller, Urban Widmark, Massimiliano Ferrero, Howard Owen,
+Olaf Kirch, Kieron Briggs, Nick Millington and others. Also special
+mention to the Stanford Checker (SWAT) which pointed out many minor
+bugs in error paths. Valuable suggestions also have come from Al Viro
+and Dave Miller.
+
+And thanks to the IBM LTC and Power test teams and SuSE and Citrix and RedHat testers for finding multiple bugs during excellent stress test runs.
diff --git a/Documentation/admin-guide/cifs/changes.rst b/Documentation/admin-guide/cifs/changes.rst
new file mode 100644
index 000000000000..8c42c4de510b
--- /dev/null
+++ b/Documentation/admin-guide/cifs/changes.rst
@@ -0,0 +1,9 @@
+=======
+Changes
+=======
+
+See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
+information about fixes/improvements to CIFS/SMB2/SMB3 support (changes
+to cifs.ko module) by kernel version (and cifs internal module version).
+This may be easier to read than parsing the output of
+"git log fs/smb/client" by release.
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
new file mode 100644
index 000000000000..fad5268635f5
--- /dev/null
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction
+ usage
+ todo
+ changes
+ authors
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/cifs/introduction.rst b/Documentation/admin-guide/cifs/introduction.rst
new file mode 100644
index 000000000000..ffc6e2564dd5
--- /dev/null
+++ b/Documentation/admin-guide/cifs/introduction.rst
@@ -0,0 +1,53 @@
+============
+Introduction
+============
+
+ This is the client VFS module for the SMB3 NAS protocol as well
+ as for older dialects such as the Common Internet File System (CIFS)
+ protocol which was the successor to the Server Message Block
+ (SMB) protocol, the native file sharing mechanism for most early
+ PC operating systems. New and improved versions of CIFS are now
+ called SMB2 and SMB3. Use of SMB3 (and later, including SMB3.1.1
+ the most current dialect) is strongly preferred over using older
+ dialects like CIFS due to security reasons. All modern dialects,
+ including the most recent, SMB3.1.1, are supported by the CIFS VFS
+ module. The SMB3 protocol is implemented and supported by all major
+ file servers such as Windows (including Windows 2019 Server), as
+ well as by Samba (which provides excellent CIFS/SMB2/SMB3 server
+ support and tools for Linux and many other operating systems).
+ Apple systems also support SMB3 well, as do most Network Attached
+ Storage vendors, so this network filesystem client can mount to a
+ wide variety of systems. It also supports mounting to the cloud
+ (for example Microsoft Azure), including the necessary security
+ features.
+
+ The intent of this module is to provide the most advanced network
+ file system function for SMB3 compliant servers, including advanced
+ security features, excellent parallelized high performance i/o, better
+ POSIX compliance, secure per-user session establishment, encryption,
+ high performance safe distributed caching (leases/oplocks), optional packet
+ signing, large files, Unicode support and other internationalization
+ improvements. Since both Samba server and this filesystem client support the
+ CIFS Unix extensions, and the Linux client also supports SMB3 POSIX extensions,
+ the combination can provide a reasonable alternative to other network and
+ cluster file systems for fileserving in some Linux to Linux environments,
+ not just in Linux to Windows (or Linux to Mac) environments.
+
+ This filesystem has a mount utility (mount.cifs) and various user space
+ tools (including smbinfo and setcifsacl) that can be obtained from
+
+ https://git.samba.org/?p=cifs-utils.git
+
+ or
+
+ git://git.samba.org/cifs-utils.git
+
+ mount.cifs should be installed in the directory with the other mount helpers.
+
+ For more information on the module see the project wiki page at
+
+ https://wiki.samba.org/index.php/LinuxCIFS
+
+ and
+
+ https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/admin-guide/cifs/todo.rst b/Documentation/admin-guide/cifs/todo.rst
new file mode 100644
index 000000000000..9a65c670774e
--- /dev/null
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -0,0 +1,133 @@
+====
+TODO
+====
+
+As of 6.7 kernel. See https://wiki.samba.org/index.php/LinuxCIFSKernel
+for list of features added by release
+
+A Partial List of Missing Features
+==================================
+
+Contributions are welcome. There are plenty of opportunities
+for visible, important contributions to this module. Here
+is a partial list of the known problems and missing features:
+
+a) SMB3 (and SMB3.1.1) missing optional features:
+ multichannel performance optimizations, algorithmic channel selection,
+ directory leases optimizations,
+ support for faster packet signing (GMAC),
+ support for compression over the network,
+ T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
+ are currently the only two server side copy mechanisms supported)
+
+b) Better optimized compounding and error handling for sparse file support,
+ perhaps addition of new optional SMB3.1.1 fsctls to make collapse range
+ and insert range more atomic
+
+c) Support for SMB3.1.1 over QUIC (and perhaps other socket based protocols
+ like SCTP)
+
+d) quota support (needs minor kernel change since quota calls otherwise
+ won't make it to network filesystems or deviceless filesystems).
+
+e) Additional use cases can be optimized to use "compounding" (e.g.
+ open/query/close and open/setinfo/close) to reduce the number of
+ roundtrips to the server and improve performance. Various cases
+ (stat, statfs, create, unlink, mkdir, xattrs) already have been improved by
+ using compounding but more can be done. In addition we could
+ significantly reduce redundant opens by using deferred close (with
+ handle caching leases) and better using reference counters on file
+ handles.
+
+f) Finish inotify support so kde and gnome file list windows
+ will autorefresh (partially complete by Asser). Needs minor kernel
+ vfs change to support removing D_NOTIFY on a file.
+
+g) Add GUI tool to configure /proc/fs/cifs settings and for display of
+ the CIFS statistics (started)
+
+h) implement support for security and trusted categories of xattrs
+ (requires minor protocol extension) to enable better support for SELINUX
+
+i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
+ feature (may be especially useful for virtualization).
+
+j) Create UID mapping facility so server UIDs can be mapped on a per
+ mount or a per server basis to client UIDs or nobody if no mapping
+ exists. Also better integration with winbind for resolving SID owners
+
+k) Add tools to take advantage of more smb3 specific ioctls and features
+ (passthrough ioctl/fsctl is now implemented in cifs.ko to allow
+ sending various SMB3 fsctls and query info and set info calls
+ directly from user space) Add tools to make setting various non-POSIX
+ metadata attributes easier from tools (e.g. extending what was done
+ in smb-info tool).
+
+l) encrypted file support (currently the attribute showing the file is
+ encrypted on the server is reported, but changing the attribute is not
+ supported).
+
+m) improved stats gathering tools (perhaps integration with nfsometer?)
+ to extend and make easier to use what is currently in /proc/fs/cifs/Stats
+
+n) Add support for claims based ACLs ("DAC")
+
+o) mount helper GUI (to simplify the various configuration options on mount)
+
+p) Expand support for witness protocol to allow for notification of share
+ move, and server network adapter changes. Currently only notifications by
+ the witness protocol for server move is supported by the Linux client.
+
+q) Allow mount.cifs to be more verbose in reporting errors with dialect
+ or unsupported feature errors. This would now be easier due to the
+ implementation of the new mount API.
+
+r) updating cifs documentation, and user guide.
+
+s) Addressing bugs found by running a broader set of xfstests in standard
+ file system xfstest suite.
+
+t) split cifs and smb3 support into separate modules so legacy (and less
+ secure) CIFS dialect can be disabled in environments that don't need it
+ and simplify the code.
+
+v) Additional testing of POSIX Extensions for SMB3.1.1
+
+w) Support for the Mac SMB3.1.1 extensions to improve interop with Apple servers
+
+x) Support for additional authentication options (e.g. IAKERB, peer-to-peer
+ Kerberos, SCRAM and others supported by existing servers)
+
+y) Improved tracing, more eBPF trace points, better scripts for performance
+ analysis
+
+Known Bugs
+==========
+
+See https://bugzilla.samba.org - search on product "CifsVFS" for
+current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
+and xfstest results e.g. https://wiki.samba.org/index.php/Xfstest-results-smb3
+
+Misc testing to do
+==================
+1) check out max path names and max path name components against various server
+ types. Try nested symlinks (8 deep). Return max path name in stat -f information
+
+2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
+ cifs/smb3 better
+
+3) Additional performance testing and optimization using iozone and similar -
+ there are some easy changes that can be done to parallelize sequential writes,
+ and when signing is disabled to request larger read sizes (larger than
+ negotiated size) and send larger write sizes to modern servers.
+
+4) More exhaustively test against less common servers
+
+5) Continue to extend the smb3 "buildbot" which does automated xfstesting
+ against Windows, Samba and Azure currently - to add additional tests and
+ to allow the buildbot to execute the tests faster. The URL for the
+ buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+
+6) Address various coverity warnings (most are not bugs per-se, but
+ the more warnings are addressed, the easier it is to spot real
+ problems that static analyzers will point out in the future).
diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst
new file mode 100644
index 000000000000..d989ae5778ba
--- /dev/null
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -0,0 +1,864 @@
+=====
+Usage
+=====
+
+This module supports the SMB3 family of advanced network protocols (as well
+as older dialects, originally called "CIFS" or SMB1).
+
+The CIFS VFS module for Linux supports many advanced network filesystem
+features such as hierarchical DFS like namespace, hardlinks, locking and more.
+It was designed to comply with the SNIA CIFS Technical Reference (which
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent
+servers. This code was developed in participation with the Protocol Freedom
+Information Foundation. CIFS and now SMB3 has now become a defacto
+standard for interoperating between Macs and Windows and major NAS appliances.
+
+Please see
+MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
+or https://samba.org/samba/PFIF/
+for more details.
+
+
+For questions or bug reports please contact:
+
+ smfrench@gmail.com
+
+See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
+
+Build instructions
+==================
+
+For Linux:
+
+1) Download the kernel (e.g. from https://www.kernel.org)
+ and change directory into the top of the kernel directory tree
+ (e.g. /usr/src/linux-2.5.73)
+2) make menuconfig (or make xconfig)
+3) select cifs from within the network filesystem choices
+4) save and exit
+5) make
+
+
+Installation instructions
+=========================
+
+If you have built the CIFS vfs as module (successfully) simply
+type ``make modules_install`` (or if you prefer, manually copy the file to
+the modules directory e.g. /lib/modules/6.3.0-060300-generic/kernel/fs/smb/client/cifs.ko).
+
+If you have built the CIFS vfs into the kernel itself, follow the instructions
+for your distribution on how to install a new kernel (usually you
+would simply type ``make install``).
+
+If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
+the CIFS VFS web site) copy it to the same directory in which mount helpers
+reside (usually /sbin). Although the helper software is not
+required, mount.cifs is recommended. Most distros include a ``cifs-utils``
+package that includes this utility so it is recommended to install this.
+
+Note that running the Winbind pam/nss module (logon service) on all of your
+Linux clients is useful in mapping Uids and Gids consistently across the
+domain to the proper network user. The mount.cifs mount helper can be
+found at cifs-utils.git on git.samba.org
+
+If cifs is built as a module, then the size and number of network buffers
+and maximum number of simultaneous requests to one server can be configured.
+Changing these from their defaults is not recommended. By executing modinfo::
+
+ modinfo <path to cifs.ko>
+
+on kernel/fs/smb/client/cifs.ko the list of configuration changes that can be made
+at module initialization time (by running insmod cifs.ko) can be seen.
+
+Recommendations
+===============
+
+To improve security the SMB2.1 dialect or later (usually will get SMB3.1.1) is now
+the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
+on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is
+much older and less secure than the default dialect SMB3 which includes
+many advanced security features such as downgrade attack detection
+and encrypted shares and stronger signing and authentication algorithms.
+There are additional mount options that may be helpful for SMB3 to get
+improved POSIX behavior (NB: can use vers=3 to force SMB3 or later, never 2.1):
+
+ ``mfsymlinks`` and either ``cifsacl`` or ``modefromsid`` (usually with ``idsfromsid``)
+
+Allowing User Mounts
+====================
+
+To permit users to mount and unmount over directories they own is possible
+with the cifs vfs. A way to enable such mounting is to mark the mount.cifs
+utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to
+umount shares they mount requires
+
+1) mount.cifs version 1.4 or later
+2) an entry for the share in /etc/fstab indicating that a user may
+ unmount it e.g.::
+
+ //server/usersharename /mnt/username cifs user 0 0
+
+Note that when the mount.cifs utility is run suid (allowing user mounts),
+in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to
+disallow execution of an suid program mounted on the remote target.
+When mount is executed as root, nosuid is not passed in by default,
+and execution of suid programs on the remote target would be enabled
+by default. This can be changed, as with nfs and other filesystems,
+by simply specifying ``nosuid`` among the mount options. For user mounts
+though to be able to pass the suid flag to mount requires rebuilding
+mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
+
+There is a corresponding manual page for cifs mounting in the Samba 3.0 and
+later source tree in docs/manpages/mount.cifs.8
+
+Allowing User Unmounts
+======================
+
+To permit users to unmount directories that they have user mounted (see above),
+the utility umount.cifs may be used. It may be invoked directly, or if
+umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
+(at least for most versions of the umount utility) for umount of cifs
+mounts, unless umount is invoked with -i (which will avoid invoking a umount
+helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
+as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions
+allow adding entries to a file to the /etc/permissions file to achieve the
+equivalent suid effect). For this utility to succeed the target path
+must be a cifs mount, and the uid of the current user must match the uid
+of the user who mounted the resource.
+
+Also note that the customary way of allowing user mounts and unmounts is
+(instead of using mount.cifs and unmount.cifs as suid) to add a line
+to the file /etc/fstab for each //server/share you wish to mount, but
+this can become unwieldy when potential mount targets include many
+or unpredictable UNC names.
+
+Samba Considerations
+====================
+
+Most current servers support SMB2.1 and SMB3 which are more secure,
+but there are useful protocol extensions for the older less secure CIFS
+dialect, so to get the maximum benefit if mounting using the older dialect
+(CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
+Unix Extensions standard (e.g. almost any version of Samba ie version
+2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
+Note that uid, gid and file permissions will display default values if you do
+not have a server that supports the Unix extensions for CIFS (such as Samba
+2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
+the line::
+
+ unix extensions = yes
+
+to your smb.conf file on the server. Note that the following smb.conf settings
+are also useful (on the Samba server) when the majority of clients are Unix or
+Linux::
+
+ case sensitive = yes
+ delete readonly = yes
+ ea support = yes
+
+Note that server ea support is required for supporting xattrs from the Linux
+cifs client, and that EA support is present in later versions of Samba (e.g.
+3.0.6 and later (also EA support works in all versions of Windows, at least to
+shares on NTFS filesystems). Extended Attribute (xattr) support is an optional
+feature of most Linux filesystems which may require enabling via
+make menuconfig. Client support for extended attributes (user xattr) can be
+disabled on a per-mount basis by specifying ``nouser_xattr`` on mount.
+
+The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
+version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
+then POSIX support in the CIFS configuration options when building the cifs
+module. POSIX ACL support can be disabled on a per mount basic by specifying
+``noacl`` on mount.
+
+Some administrators may want to change Samba's smb.conf ``map archive`` and
+``create mask`` parameters from the default. Unless the create mask is changed
+newly created files can end up with an unnecessarily restrictive default mode,
+which may not be what you want, although if the CIFS Unix extensions are
+enabled on the server and client, subsequent setattr calls (e.g. chmod) can
+fix the mode. Note that creating special devices (mknod) remotely
+may require specifying a mkdev function to Samba if you are not using
+Samba 3.0.6 or later. For more information on these see the manual pages
+(``man smb.conf``) on the Samba server system. Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system
+(the few optional settings are passed in on mount via -o parameters instead).
+Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
+open files (required for strict POSIX compliance). Windows Servers already
+supported this feature. Samba server does not allow symlinks that refer to files
+outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
+files with absolute paths (ie beginning with slash) such as::
+
+ ln -s /mnt/foo bar
+
+would be forbidden. Samba 3.0.6 server or later includes the ability to create
+such symlinks safely by converting unsafe symlinks (ie symlinks to server
+files that are outside of the share) to a samba specific format on the server
+that is ignored by local server applications and non-cifs clients and that will
+not be traversed by the Samba server). This is opaque to the Linux client
+application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
+later, but only for remote clients using the CIFS Unix extensions, and will
+be invisible to Windows clients and typically will not affect local
+applications running on the same server as Samba.
+
+Use instructions
+================
+
+Once the CIFS VFS support is built into the kernel or installed as a module
+(cifs.ko), you can use mount syntax like the following to access Samba or
+Mac or Windows servers::
+
+ mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
+
+Before -o the option -v may be specified to make the mount.cifs
+mount helper display the mount steps more verbosely.
+After -o the following commonly used cifs vfs specific options
+are supported::
+
+ username=<username>
+ password=<password>
+ domain=<domain name>
+
+Other cifs mount options are described below. Use of TCP names (in addition to
+ip addresses) is available if the mount helper (mount.cifs) is installed. If
+you do not trust the server to which are mounted, or if you do not have
+cifs signing enabled (and the physical network is insecure), consider use
+of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of
+running an altered binary on your local system (downloaded from a hostile server
+or altered by a hostile router).
+
+Although mounting using format corresponding to the CIFS URL specification is
+not possible in mount.cifs yet, it is possible to use an alternate format
+for the server and sharename (which is somewhat similar to NFS style mount
+syntax) instead of the more widely used UNC format (i.e. \\server\share)::
+
+ mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
+
+When using the mount helper mount.cifs, passwords may be specified via alternate
+mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax
+on the command line:
+1) By including it in a credential file. Specify credentials=filename as one
+of the mount options. Credential files contain two lines::
+
+ username=someuser
+ password=your_password
+
+2) By specifying the password in the PASSWD environment variable (similarly
+ the user name can be taken from the USER environment variable).
+3) By specifying the password in a file by name via PASSWD_FILE
+4) By specifying the password in a file by file descriptor via PASSWD_FD
+
+If no password is provided, mount.cifs will prompt for password entry
+
+Restrictions
+============
+
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
+1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
+problem as most servers support this.
+
+Valid filenames differ between Windows and Linux. Windows typically restricts
+filenames which contain certain reserved characters (e.g.the character :
+which is used to delimit the beginning of a stream name by Windows), while
+Linux allows a slightly wider set of valid characters in filenames. Windows
+servers can remap such characters when an explicit mapping is specified in
+the Server's registry. Samba starting with version 3.10 will allow such
+filenames (ie those which contain valid Linux characters, which normally
+would be forbidden for Windows/CIFS semantics) as long as the server is
+configured for Unix Extensions (and the client has not disabled
+/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
+``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
+illegal Windows/NTFS/SMB characters to a remap range (this mount parameter
+is the default for SMB3). This remap (``mapposix``) range is also
+compatible with Mac (and "Services for Mac" on some older Windows).
+When POSIX Extensions for SMB 3.1.1 are negotiated, remapping is automatically
+disabled.
+
+CIFS VFS Mount Options
+======================
+A partial list of the supported mount options follows:
+
+ username
+ The user name to use when trying to establish
+ the CIFS session.
+ password
+ The user password. If the mount helper is
+ installed, the user will be prompted for password
+ if not supplied.
+ ip
+ The ip address of the target server
+ unc
+ The target server Universal Network Name (export) to
+ mount.
+ domain
+ Set the SMB/CIFS workgroup name prepended to the
+ username during CIFS session establishment
+ forceuid
+ Set the default uid for inodes to the uid
+ passed in on mount. For mounts to servers
+ which do support the CIFS Unix extensions, such as a
+ properly configured Samba server, the server provides
+ the uid, gid and mode so this parameter should not be
+ specified unless the server and clients uid and gid
+ numbering differ. If the server and client are in the
+ same domain (e.g. running winbind or nss_ldap) and
+ the server supports the Unix Extensions then the uid
+ and gid can be retrieved from the server (and uid
+ and gid would not have to be specified on the mount.
+ For servers which do not support the CIFS Unix
+ extensions, the default uid (and gid) returned on lookup
+ of existing files will be the uid (gid) of the person
+ who executed the mount (root, except when mount.cifs
+ is configured setuid for user mounts) unless the ``uid=``
+ (gid) mount option is specified. Also note that permission
+ checks (authorization checks) on accesses to a file occur
+ at the server, but there are cases in which an administrator
+ may want to restrict at the client as well. For those
+ servers which do not report a uid/gid owner
+ (such as Windows), permissions can also be checked at the
+ client, and a crude form of client side permission checking
+ can be enabled by specifying file_mode and dir_mode on
+ the client. (default)
+ forcegid
+ (similar to above but for the groupid instead of uid) (default)
+ noforceuid
+ Fill in file owner information (uid) by requesting it from
+ the server if possible. With this option, the value given in
+ the uid= option (on mount) will only be used if the server
+ can not support returning uids on inodes.
+ noforcegid
+ (similar to above but for the group owner, gid, instead of uid)
+ uid
+ Set the default uid for inodes, and indicate to the
+ cifs kernel driver which local user mounted. If the server
+ supports the unix extensions the default uid is
+ not used to fill in the owner fields of inodes (files)
+ unless the ``forceuid`` parameter is specified.
+ gid
+ Set the default gid for inodes (similar to above).
+ file_mode
+ If CIFS Unix extensions are not supported by the server
+ this overrides the default mode for file inodes.
+ fsc
+ Enable local disk caching using FS-Cache (off by default). This
+ option could be useful to improve performance on a slow link,
+ heavily loaded server and/or network where reading from the
+ disk is faster than reading from the server (over the network).
+ This could also impact scalability positively as the
+ number of calls to the server are reduced. However, local
+ caching is not suitable for all workloads for e.g. read-once
+ type workloads. So, you need to consider carefully your
+ workload/scenario before using this option. Currently, local
+ disk caching is functional for CIFS files opened as read-only.
+ dir_mode
+ If CIFS Unix extensions are not supported by the server
+ this overrides the default mode for directory inodes.
+ port
+ attempt to contact the server on this tcp port, before
+ trying the usual ports (port 445, then 139).
+ iocharset
+ Codepage used to convert local path names to and from
+ Unicode. Unicode is used by default for network path
+ names if the server supports it. If iocharset is
+ not specified then the nls_default specified
+ during the local client kernel build will be used.
+ If server does not support Unicode, this parameter is
+ unused.
+ rsize
+ default read size (usually 16K). The client currently
+ can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
+ defaults to 16K and may be changed (from 8K to the maximum
+ kmalloc size allowed by your kernel) at module install time
+ for cifs.ko. Setting CIFSMaxBufSize to a very large value
+ will cause cifs to use more memory and may reduce performance
+ in some cases. To use rsize greater than 127K (the original
+ cifs protocol maximum) also requires that the server support
+ a new Unix Capability flag (for very large read) which some
+ newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
+ set from a minimum of 2048 to a maximum of 130048 (127K or
+ CIFSMaxBufSize, whichever is smaller)
+ wsize
+ default write size (default 57344)
+ maximum wsize currently allowed by CIFS is 57344 (fourteen
+ 4096 byte pages)
+ actimeo=n
+ attribute cache timeout in seconds (default 1 second).
+ After this timeout, the cifs client requests fresh attribute
+ information from the server. This option allows to tune the
+ attribute cache timeout to suit the workload needs. Shorter
+ timeouts mean better the cache coherency, but increased number
+ of calls to the server. Longer timeouts mean reduced number
+ of calls to the server at the expense of less stricter cache
+ coherency checks (i.e. incorrect attribute cache for a short
+ period of time).
+ rw
+ mount the network share read-write (note that the
+ server may still consider the share read-only)
+ ro
+ mount network share read-only
+ version
+ used to distinguish different versions of the
+ mount helper utility (not typically needed)
+ sep
+ if first mount option (after the -o), overrides
+ the comma as the separator between the mount
+ parameters. e.g.::
+
+ -o user=myname,password=mypassword,domain=mydom
+
+ could be passed instead with period as the separator by::
+
+ -o sep=.user=myname.password=mypassword.domain=mydom
+
+ this might be useful when comma is contained within username
+ or password or domain. This option is less important
+ when the cifs mount helper cifs.mount (version 1.1 or later)
+ is used.
+ nosuid
+ Do not allow remote executables with the suid bit
+ program to be executed. This is only meaningful for mounts
+ to servers such as Samba which support the CIFS Unix Extensions.
+ If you do not trust the servers in your network (your mount
+ targets) it is recommended that you specify this option for
+ greater security.
+ exec
+ Permit execution of binaries on the mount.
+ noexec
+ Do not permit execution of binaries on the mount.
+ dev
+ Recognize block devices on the remote mount.
+ nodev
+ Do not recognize devices on the remote mount.
+ suid
+ Allow remote files on this mountpoint with suid enabled to
+ be executed (default for mounts when executed as root,
+ nosuid is default for user mounts).
+ credentials
+ Although ignored by the cifs kernel component, it is used by
+ the mount helper, mount.cifs. When mount.cifs is installed it
+ opens and reads the credential file specified in order
+ to obtain the userid and password arguments which are passed to
+ the cifs vfs.
+ guest
+ Although ignored by the kernel component, the mount.cifs
+ mount helper will not prompt the user for a password
+ if guest is specified on the mount options. If no
+ password is specified a null password will be used.
+ perm
+ Client does permission checks (vfs_permission check of uid
+ and gid of the file against the mode and desired operation),
+ Note that this is in addition to the normal ACL check on the
+ target machine done by the server software.
+ Client permission checking is enabled by default.
+ noperm
+ Client does not do permission checks. This can expose
+ files on this mount to access by other users on the local
+ client system. It is typically only needed when the server
+ supports the CIFS Unix Extensions but the UIDs/GIDs on the
+ client and server system do not match closely enough to allow
+ access by the user doing the mount, but it may be useful with
+ non CIFS Unix Extension mounts for cases in which the default
+ mode is specified on the mount but is not to be enforced on the
+ client (e.g. perhaps when MultiUserMount is enabled)
+ Note that this does not affect the normal ACL check on the
+ target machine done by the server software (of the server
+ ACL against the user name provided at mount time).
+ serverino
+ Use server's inode numbers instead of generating automatically
+ incrementing inode numbers on the client. Although this will
+ make it easier to spot hardlinked files (as they will have
+ the same inode numbers) and inode numbers may be persistent,
+ note that the server does not guarantee that the inode numbers
+ are unique if multiple server side mounts are exported under a
+ single share (since inode numbers on the servers might not
+ be unique if multiple filesystems are mounted under the same
+ shared higher level directory). Note that some older
+ (e.g. pre-Windows 2000) do not support returning UniqueIDs
+ or the CIFS Unix Extensions equivalent and for those
+ this mount option will have no effect. Exporting cifs mounts
+ under nfsd requires this mount option on the cifs mount.
+ This is now the default if server supports the
+ required network operation.
+ noserverino
+ Client generates inode numbers (rather than using the actual one
+ from the server). These inode numbers will vary after
+ unmount or reboot which can confuse some applications,
+ but not all server filesystems support unique inode
+ numbers.
+ setuids
+ If the CIFS Unix extensions are negotiated with the server
+ the client will attempt to set the effective uid and gid of
+ the local process on newly created files, directories, and
+ devices (create, mkdir, mknod). If the CIFS Unix Extensions
+ are not negotiated, for newly created files and directories
+ instead of using the default uid and gid specified on
+ the mount, cache the new file's uid and gid locally which means
+ that the uid for the file can change when the inode is
+ reloaded (or the user remounts the share).
+ nosetuids
+ The client will not attempt to set the uid and gid on
+ on newly created files, directories, and devices (create,
+ mkdir, mknod) which will result in the server setting the
+ uid and gid to the default (usually the server uid of the
+ user who mounted the share). Letting the server (rather than
+ the client) set the uid and gid is the default. If the CIFS
+ Unix Extensions are not negotiated then the uid and gid for
+ new files will appear to be the uid (gid) of the mounter or the
+ uid (gid) parameter specified on the mount.
+ netbiosname
+ When mounting to servers via port 139, specifies the RFC1001
+ source name to use to represent the client netbios machine
+ name when doing the RFC1001 netbios session initialize.
+ direct
+ Do not do inode data caching on files opened on this mount.
+ This precludes mmapping files on this mount. In some cases
+ with fast networks and little or no caching benefits on the
+ client (e.g. when the application is doing large sequential
+ reads bigger than page size without rereading the same data)
+ this can provide better performance than the default
+ behavior which caches reads (readahead) and writes
+ (writebehind) through the local Linux client pagecache
+ if oplock (caching token) is granted and held. Note that
+ direct allows write operations larger than page size
+ to be sent to the server.
+ strictcache
+ Use for switching on strict cache mode. In this mode the
+ client read from the cache all the time it has Oplock Level II,
+ otherwise - read from the server. All written data are stored
+ in the cache, but if the client doesn't have Exclusive Oplock,
+ it writes the data to the server.
+ rwpidforward
+ Forward pid of a process who opened a file to any read or write
+ operation on that file. This prevent applications like WINE
+ from failing on read and write if we use mandatory brlock style.
+ acl
+ Allow setfacl and getfacl to manage posix ACLs if server
+ supports them. (default)
+ noacl
+ Do not allow setfacl and getfacl calls on this mount
+ user_xattr
+ Allow getting and setting user xattrs (those attributes whose
+ name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended
+ attributes) to the server. This allows support of the
+ setfattr and getfattr utilities. (default)
+ nouser_xattr
+ Do not allow getfattr/setfattr to get/set/list xattrs
+ mapchars
+ Translate six of the seven reserved characters (not backslash)::
+
+ *?<>|:
+
+ to the remap range (above 0xF000), which also
+ allows the CIFS client to recognize files created with
+ such characters by Windows's POSIX emulation. This can
+ also be useful when mounting to most versions of Samba
+ (which also forbids creating and opening files
+ whose names contain any of these seven characters).
+ This has no effect if the server does not support
+ Unicode on the wire.
+ nomapchars
+ Do not translate any of these seven characters (default).
+ nocase
+ Request case insensitive path name matching (case
+ sensitive is the default if the server supports it).
+ (mount option ``ignorecase`` is identical to ``nocase``)
+ posixpaths
+ If CIFS Unix extensions are supported, attempt to
+ negotiate posix path name support which allows certain
+ characters forbidden in typical CIFS filenames, without
+ requiring remapping. (default)
+ noposixpaths
+ If CIFS Unix extensions are supported, do not request
+ posix path name support (this may cause servers to
+ reject creatingfile with certain reserved characters).
+ nounix
+ Disable the CIFS Unix Extensions for this mount (tree
+ connection). This is rarely needed, but it may be useful
+ in order to turn off multiple settings all at once (ie
+ posix acls, posix locks, posix paths, symlink support
+ and retrieving uids/gids/mode from the server) or to
+ work around a bug in server which implement the Unix
+ Extensions.
+ nobrl
+ Do not send byte range lock requests to the server.
+ This is necessary for certain applications that break
+ with cifs style mandatory byte range locks (and most
+ cifs servers do not yet support requesting advisory
+ byte range locks).
+ forcemandatorylock
+ Even if the server supports posix (advisory) byte range
+ locking, send only mandatory lock requests. For some
+ (presumably rare) applications, originally coded for
+ DOS/Windows, which require Windows style mandatory byte range
+ locking, they may be able to take advantage of this option,
+ forcing the cifs client to only send mandatory locks
+ even if the cifs server would support posix advisory locks.
+ ``forcemand`` is accepted as a shorter form of this mount
+ option.
+ nostrictsync
+ If this mount option is set, when an application does an
+ fsync call then the cifs client does not send an SMB Flush
+ to the server (to force the server to write all dirty data
+ for this file immediately to disk), although cifs still sends
+ all dirty (cached) file data to the server and waits for the
+ server to respond to the write. Since SMB Flush can be
+ very slow, and some servers may be reliable enough (to risk
+ delaying slightly flushing the data to disk on the server),
+ turning on this option may be useful to improve performance for
+ applications that fsync too much, at a small risk of server
+ crash. If this mount option is not set, by default cifs will
+ send an SMB flush request (and wait for a response) on every
+ fsync call.
+ nodfs
+ Disable DFS (global name space support) even if the
+ server claims to support it. This can help work around
+ a problem with parsing of DFS paths with Samba server
+ versions 3.0.24 and 3.0.25.
+ remount
+ remount the share (often used to change from ro to rw mounts
+ or vice versa)
+ cifsacl
+ Report mode bits (e.g. on stat) based on the Windows ACL for
+ the file. (EXPERIMENTAL)
+ servern
+ Specify the server 's netbios name (RFC1001 name) to use
+ when attempting to setup a session to the server.
+ This is needed for mounting to some older servers (such
+ as OS/2 or Windows 98 and Windows ME) since they do not
+ support a default server name. A server name can be up
+ to 15 characters long and is usually uppercased.
+ sfu
+ When the CIFS Unix Extensions are not negotiated, attempt to
+ create device files and fifos in a format compatible with
+ Services for Unix (SFU). In addition retrieve bits 10-12
+ of the mode via the SETFILEBITS extended attribute (as
+ SFU does). In the future the bottom 9 bits of the
+ mode also will be emulated using queries of the security
+ descriptor (ACL).
+ mfsymlinks
+ Enable support for Minshall+French symlinks
+ (see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
+ This option is ignored when specified together with the
+ 'sfu' option. Minshall+French symlinks are used even if
+ the server supports the CIFS Unix Extensions.
+ sign
+ Must use packet signing (helps avoid unwanted data modification
+ by intermediate systems in the route). Note that signing
+ does not work with lanman or plaintext authentication.
+ seal
+ Must seal (encrypt) all data on this mounted share before
+ sending on the network. Requires support for Unix Extensions.
+ Note that this differs from the sign mount option in that it
+ causes encryption of data sent over this mounted share but other
+ shares mounted to the same server are unaffected.
+ locallease
+ This option is rarely needed. Fcntl F_SETLEASE is
+ used by some applications such as Samba and NFSv4 server to
+ check to see whether a file is cacheable. CIFS has no way
+ to explicitly request a lease, but can check whether a file
+ is cacheable (oplocked). Unfortunately, even if a file
+ is not oplocked, it could still be cacheable (ie cifs client
+ could grant fcntl leases if no other local processes are using
+ the file) for cases for example such as when the server does not
+ support oplocks and the user is sure that the only updates to
+ the file will be from this client. Specifying this mount option
+ will allow the cifs client to check for leases (only) locally
+ for files which are not oplocked instead of denying leases
+ in that case. (EXPERIMENTAL)
+ sec
+ Security mode. Allowed values are:
+
+ none
+ attempt to connection as a null user (no name)
+ krb5
+ Use Kerberos version 5 authentication
+ krb5i
+ Use Kerberos authentication and packet signing
+ ntlm
+ Use NTLM password hashing (default)
+ ntlmi
+ Use NTLM password hashing with signing (if
+ /proc/fs/cifs/PacketSigningEnabled on or if
+ server requires signing also can be the default)
+ ntlmv2
+ Use NTLMv2 password hashing
+ ntlmv2i
+ Use NTLMv2 password hashing with packet signing
+ lanman
+ (if configured in kernel config) use older
+ lanman hash
+ hard
+ Retry file operations if server is not responding
+ soft
+ Limit retries to unresponsive servers (usually only
+ one retry) before returning an error. (default)
+
+The mount.cifs mount helper also accepts a few mount options before -o
+including:
+
+=============== ===============================================================
+ -S take password from stdin (equivalent to setting the environment
+ variable ``PASSWD_FD=0``
+ -V print mount.cifs version
+ -? display simple usage information
+=============== ===============================================================
+
+With most 2.6 kernel versions of modutils, the version of the cifs kernel
+module can be displayed via modinfo.
+
+Misc /proc/fs/cifs Flags and Debug Info
+=======================================
+
+Informational pseudo-files:
+
+======================= =======================================================
+DebugData Displays information about active CIFS sessions and
+ shares, features enabled as well as the cifs.ko
+ version.
+Stats Lists summary resource usage information as well as per
+ share statistics.
+open_files List all the open file handles on all active SMB sessions.
+mount_params List of all mount parameters available for the module
+======================= =======================================================
+
+Configuration pseudo-files:
+
+======================= =======================================================
+SecurityFlags Flags which control security negotiation and
+ also packet signing. Authentication (may/must)
+ flags (e.g. for NTLMv2) may be combined with
+ the signing flags. Specifying two different password
+ hashing mechanisms (as "must use") on the other hand
+ does not make much sense. Default flags are::
+
+ 0x00C5
+
+ (NTLMv2 and packet signing allowed). Some SecurityFlags
+ may require enabling a corresponding menuconfig option.
+
+ may use packet signing 0x00001
+ must use packet signing 0x01001
+ may use NTLMv2 0x00004
+ must use NTLMv2 0x04004
+ may use Kerberos security (krb5) 0x00008
+ must use Kerberos 0x08008
+ may use NTLMSSP 0x00080
+ must use NTLMSSP 0x80080
+ seal (packet encryption) 0x00040
+ must seal 0x40040
+
+cifsFYI If set to non-zero value, additional debug information
+ will be logged to the system error log. This field
+ contains three flags controlling different classes of
+ debugging entries. The maximum value it can be set
+ to is 7 which enables all debugging points (default 0).
+ Some debugging statements are not compiled into the
+ cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
+ kernel configuration. cifsFYI may be set to one or
+ more of the following flags (7 sets them all)::
+
+ +-----------------------------------------------+------+
+ | log cifs informational messages | 0x01 |
+ +-----------------------------------------------+------+
+ | log return codes from cifs entry points | 0x02 |
+ +-----------------------------------------------+------+
+ | log slow responses | 0x04 |
+ | (ie which take longer than 1 second) | |
+ | | |
+ | CONFIG_CIFS_STATS2 must be enabled in .config | |
+ +-----------------------------------------------+------+
+
+traceSMB If set to one, debug information is logged to the
+ system error log with the start of smb requests
+ and responses (default 0)
+LookupCacheEnable If set to one, inode information is kept cached
+ for one second improving performance of lookups
+ (default 1)
+LinuxExtensionsEnabled If set to one then the client will attempt to
+ use the CIFS "UNIX" extensions which are optional
+ protocol enhancements that allow CIFS servers
+ to return accurate UID/GID information as well
+ as support symbolic links. If you use servers
+ such as Samba that support the CIFS Unix
+ extensions but do not want to use symbolic link
+ support and want to map the uid and gid fields
+ to values supplied at mount (rather than the
+ actual values, then set this to zero. (default 1)
+dfscache List the content of the DFS cache.
+ If set to 0, the client will clear the cache.
+======================= =======================================================
+
+These experimental features and tracing can be enabled by changing flags in
+/proc/fs/cifs (after the cifs module has been installed or built into the
+kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
+tracing to the kernel message log type::
+
+ echo 7 > /proc/fs/cifs/cifsFYI
+
+cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
+logging of various informational messages. 2 enables logging of non-zero
+SMB return codes while 4 enables logging of requests that take longer
+than one second to complete (except for byte range lock requests).
+Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
+(.config). Setting it to seven enables all three. Finally, tracing
+the start of smb requests and responses can be enabled via::
+
+ echo 1 > /proc/fs/cifs/traceSMB
+
+Per share (per client mount) statistics are available in /proc/fs/cifs/Stats.
+Additional information is available if CONFIG_CIFS_STATS2 is enabled in the
+kernel configuration (.config). The statistics returned include counters which
+represent the number of attempted and failed (ie non-zero return code from the
+server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.).
+Also recorded is the total bytes read and bytes written to the server for
+that share. Note that due to client caching effects this can be less than the
+number of bytes read and written by the application running on the client.
+Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be
+useful if comparing performance of two different scenarios.
+
+Also note that ``cat /proc/fs/cifs/DebugData`` will display information about
+the active sessions and the shares that are mounted.
+
+Enabling Kerberos (extended security) works but requires version 1.2 or later
+of the helper program cifs.upcall to be present and to be configured in the
+/etc/request-key.conf file. The cifs.upcall helper program is from the Samba
+project(https://www.samba.org). NTLM and NTLMv2 and LANMAN support do not
+require this helper. Note that NTLMv2 security (which does not require the
+cifs.upcall helper program), instead of using Kerberos, is sufficient for
+some use cases.
+
+DFS support allows transparent redirection to shares in an MS-DFS name space.
+In addition, DFS support for target shares which are specified as UNC
+names which begin with host names (rather than IP addresses) requires
+a user space helper (such as cifs.upcall) to be present in order to
+translate host names to ip address, and the user space helper must also
+be configured in the file /etc/request-key.conf. Samba, Windows servers and
+many NAS appliances support DFS as a way of constructing a global name
+space to ease network configuration and improve reliability.
+
+To use cifs Kerberos and DFS support, the Linux keyutils package should be
+installed and something like the following lines should be added to the
+/etc/request-key.conf file::
+
+ create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
+ create dns_resolver * * /usr/local/sbin/cifs.upcall %k
+
+CIFS kernel module parameters
+=============================
+These module parameters can be specified or modified either during the time of
+module loading or during the runtime by using the interface::
+
+ /sys/module/cifs/parameters/<param>
+
+i.e.::
+
+ echo "value" > /sys/module/cifs/parameters/<param>
+
+More detailed descriptions of the available module parameters and their values
+can be seen by doing:
+
+ modinfo cifs (or modinfo smb3)
+
+================= ==========================================================
+1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default.
+ [Y/y/1]. To disable use any of [N/n/0].
+================= ==========================================================
diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
index 322a9c833f23..993186beea20 100755
--- a/Documentation/filesystems/cifs/winucase_convert.pl
+++ b/Documentation/admin-guide/cifs/winucase_convert.pl
@@ -16,7 +16,7 @@
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
-# along with this program. If not, see <http://www.gnu.org/licenses/>.
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
#
while(<>) {
diff --git a/Documentation/admin-guide/clearing-warn-once.rst b/Documentation/admin-guide/clearing-warn-once.rst
new file mode 100644
index 000000000000..211fd926cf00
--- /dev/null
+++ b/Documentation/admin-guide/clearing-warn-once.rst
@@ -0,0 +1,9 @@
+Clearing WARN_ONCE
+------------------
+
+WARN_ONCE / WARN_ON_ONCE / printk_once only emit a message once.
+
+echo 1 > /sys/kernel/debug/clear_warn_once
+
+clears the state and allows the warnings to print once again.
+This can be useful after test suite runs to reproduce problems.
diff --git a/Documentation/admin-guide/cpu-load.rst b/Documentation/admin-guide/cpu-load.rst
new file mode 100644
index 000000000000..21a984337080
--- /dev/null
+++ b/Documentation/admin-guide/cpu-load.rst
@@ -0,0 +1,117 @@
+========
+CPU load
+========
+
+Linux exports various bits of information via ``/proc/stat`` and
+``/proc/uptime`` that userland tools, such as top(1), use to calculate
+the average time system spent in a particular state, for example::
+
+ $ iostat
+ Linux 2.6.18.3-exp (linmac) 02/20/2007
+
+ avg-cpu: %user %nice %system %iowait %steal %idle
+ 10.01 0.00 2.92 5.44 0.00 81.63
+
+ ...
+
+Here the system thinks that over the default sampling period the
+system spent 10.01% of the time doing work in user space, 2.92% in the
+kernel, and was overall 81.63% of the time idle.
+
+In most cases the ``/proc/stat`` information reflects the reality quite
+closely, however due to the nature of how/when the kernel collects
+this data sometimes it can not be trusted at all.
+
+So how is this information collected? Whenever timer interrupt is
+signalled the kernel looks what kind of task was running at this
+moment and increments the counter that corresponds to this tasks
+kind/state. The problem with this is that the system could have
+switched between various states multiple times between two timer
+interrupts yet the counter is incremented only for the last state.
+
+
+Example
+-------
+
+If we imagine the system with one task that periodically burns cycles
+in the following manner::
+
+ time line between two timer interrupts
+ |--------------------------------------|
+ ^ ^
+ |_ something begins working |
+ |_ something goes to sleep
+ (only to be awaken quite soon)
+
+In the above situation the system will be 0% loaded according to the
+``/proc/stat`` (since the timer interrupt will always happen when the
+system is executing the idle handler), but in reality the load is
+closer to 99%.
+
+One can imagine many more situations where this behavior of the kernel
+will lead to quite erratic information inside ``/proc/stat``::
+
+
+ /* gcc -o hog smallhog.c */
+ #include <time.h>
+ #include <limits.h>
+ #include <signal.h>
+ #include <sys/time.h>
+ #define HIST 10
+
+ static volatile sig_atomic_t stop;
+
+ static void sighandler(int signr)
+ {
+ (void) signr;
+ stop = 1;
+ }
+
+ static unsigned long hog (unsigned long niters)
+ {
+ stop = 0;
+ while (!stop && --niters);
+ return niters;
+ }
+
+ int main (void)
+ {
+ int i;
+ struct itimerval it = {
+ .it_interval = { .tv_sec = 0, .tv_usec = 1 },
+ .it_value = { .tv_sec = 0, .tv_usec = 1 } };
+ sigset_t set;
+ unsigned long v[HIST];
+ double tmp = 0.0;
+ unsigned long n;
+ signal(SIGALRM, &sighandler);
+ setitimer(ITIMER_REAL, &it, NULL);
+
+ hog (ULONG_MAX);
+ for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog(ULONG_MAX);
+ for (i = 0; i < HIST; ++i) tmp += v[i];
+ tmp /= HIST;
+ n = tmp - (tmp / 3.0);
+
+ sigemptyset(&set);
+ sigaddset(&set, SIGALRM);
+
+ for (;;) {
+ hog(n);
+ sigwait(&set, &i);
+ }
+ return 0;
+ }
+
+
+References
+----------
+
+- https://lore.kernel.org/r/loom.20070212T063225-663@post.gmane.org
+- Documentation/filesystems/proc.rst (1.8)
+
+
+Thanks
+------
+
+Con Kolivas, Pavel Machek
diff --git a/Documentation/admin-guide/cputopology.rst b/Documentation/admin-guide/cputopology.rst
new file mode 100644
index 000000000000..d29cacc9b3c3
--- /dev/null
+++ b/Documentation/admin-guide/cputopology.rst
@@ -0,0 +1,101 @@
+===========================================
+How CPU topology info is exported via sysfs
+===========================================
+
+CPU topology info is exported via sysfs. Items (attributes) are similar
+to /proc/cpuinfo output of some architectures. They reside in
+/sys/devices/system/cpu/cpuX/topology/. Please refer to the ABI file:
+Documentation/ABI/stable/sysfs-devices-system-cpu.
+
+Architecture-neutral, drivers/base/topology.c, exports these attributes.
+However the die, cluster, book, and drawer hierarchy related sysfs files will
+only be created if an architecture provides the related macros as described
+below.
+
+For an architecture to support this feature, it must define some of
+these macros in include/asm-XXX/topology.h::
+
+ #define topology_physical_package_id(cpu)
+ #define topology_die_id(cpu)
+ #define topology_cluster_id(cpu)
+ #define topology_core_id(cpu)
+ #define topology_book_id(cpu)
+ #define topology_drawer_id(cpu)
+ #define topology_sibling_cpumask(cpu)
+ #define topology_core_cpumask(cpu)
+ #define topology_cluster_cpumask(cpu)
+ #define topology_die_cpumask(cpu)
+ #define topology_book_cpumask(cpu)
+ #define topology_drawer_cpumask(cpu)
+
+The type of ``**_id macros`` is int.
+The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
+correspond with appropriate ``**_siblings`` sysfs attributes (except for
+topology_sibling_cpumask() which corresponds with thread_siblings).
+
+To be consistent on all architectures, include/linux/topology.h
+provides default definitions for any of the above macros that are
+not defined by include/asm-XXX/topology.h:
+
+1) topology_physical_package_id: -1
+2) topology_die_id: -1
+3) topology_cluster_id: -1
+4) topology_core_id: 0
+5) topology_book_id: -1
+6) topology_drawer_id: -1
+7) topology_sibling_cpumask: just the given CPU
+8) topology_core_cpumask: just the given CPU
+9) topology_cluster_cpumask: just the given CPU
+10) topology_die_cpumask: just the given CPU
+11) topology_book_cpumask: just the given CPU
+12) topology_drawer_cpumask: just the given CPU
+
+Additionally, CPU topology information is provided under
+/sys/devices/system/cpu and includes these files. The internal
+source for the output is in brackets ("[]").
+
+ =========== ==========================================================
+ kernel_max: the maximum CPU index allowed by the kernel configuration.
+ [NR_CPUS-1]
+
+ offline: CPUs that are not online because they have been
+ HOTPLUGGED off or exceed the limit of CPUs allowed by the
+ kernel configuration (kernel_max above).
+ [~cpu_online_mask + cpus >= NR_CPUS]
+
+ online: CPUs that are online and being scheduled [cpu_online_mask]
+
+ possible: CPUs that have been allocated resources and can be
+ brought online if they are present. [cpu_possible_mask]
+
+ present: CPUs that have been identified as being present in the
+ system. [cpu_present_mask]
+ =========== ==========================================================
+
+The format for the above output is compatible with cpulist_parse()
+[see <linux/cpumask.h>]. Some examples follow.
+
+In this example, there are 64 CPUs in the system but cpus 32-63 exceed
+the kernel max which is limited to 0..31 by the NR_CPUS config option
+being 32. Note also that CPUs 2 and 4-31 are not online but could be
+brought online as they are both present and possible::
+
+ kernel_max: 31
+ offline: 2,4-31,32-63
+ online: 0-1,3
+ possible: 0-31
+ present: 0-31
+
+In this example, the NR_CPUS config option is 128, but the kernel was
+started with possible_cpus=144. There are 4 CPUs in the system and cpu2
+was manually taken offline (and is the only CPU that can be brought
+online.)::
+
+ kernel_max: 127
+ offline: 2,4-127,128-143
+ online: 0-1,3
+ possible: 0-127
+ present: 0-3
+
+See Documentation/core-api/cpu_hotplug.rst for the possible_cpus=NUM
+kernel start parameter as well as more information on the various cpumasks.
diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst
new file mode 100644
index 000000000000..2196caf1b939
--- /dev/null
+++ b/Documentation/admin-guide/dell_rbu.rst
@@ -0,0 +1,128 @@
+=========================================
+Dell Remote BIOS Update driver (dell_rbu)
+=========================================
+
+Purpose
+=======
+
+Document demonstrating the use of the Dell Remote BIOS Update driver
+for updating BIOS images on Dell servers and desktops.
+
+Scope
+=====
+
+This document discusses the functionality of the rbu driver only.
+It does not cover the support needed from applications to enable the BIOS to
+update itself with the image downloaded in to the memory.
+
+Overview
+========
+
+This driver works with Dell OpenManage or Dell Update Packages for updating
+the BIOS on Dell servers (starting from servers sold since 1999), desktops
+and notebooks (starting from those sold in 2005).
+
+Please go to http://support.dell.com register and you can find info on
+OpenManage and Dell Update packages (DUP).
+
+Libsmbios can also be used to update BIOS on Dell systems go to
+https://linux.dell.com/libsmbios/ for details.
+
+Dell_RBU driver supports BIOS update using the monolithic image and packetized
+image methods. In case of monolithic the driver allocates a contiguous chunk
+of physical pages having the BIOS image. In case of packetized the app
+using the driver breaks the image in to packets of fixed sizes and the driver
+would place each packet in contiguous physical memory. The driver also
+maintains a link list of packets for reading them back.
+
+If the dell_rbu driver is unloaded all the allocated memory is freed.
+
+The rbu driver needs to have an application (as mentioned above) which will
+inform the BIOS to enable the update in the next system reboot.
+
+The user should not unload the rbu driver after downloading the BIOS image
+or updating.
+
+The driver load creates the following directories under the /sys file system::
+
+ /sys/class/firmware/dell_rbu/loading
+ /sys/class/firmware/dell_rbu/data
+ /sys/devices/platform/dell_rbu/image_type
+ /sys/devices/platform/dell_rbu/data
+ /sys/devices/platform/dell_rbu/packet_size
+
+The driver supports two types of update mechanism; monolithic and packetized.
+These update mechanism depends upon the BIOS currently running on the system.
+Most of the Dell systems support a monolithic update where the BIOS image is
+copied to a single contiguous block of physical memory.
+
+In case of packet mechanism the single memory can be broken in smaller chunks
+of contiguous memory and the BIOS image is scattered in these packets.
+
+By default the driver uses monolithic memory for the update type. This can be
+changed to packets during the driver load time by specifying the load
+parameter image_type=packet. This can also be changed later as below::
+
+ echo packet > /sys/devices/platform/dell_rbu/image_type
+
+In packet update mode the packet size has to be given before any packets can
+be downloaded. It is done as below::
+
+ echo XXXX > /sys/devices/platform/dell_rbu/packet_size
+
+In the packet update mechanism, the user needs to create a new file having
+packets of data arranged back to back. It can be done as follows:
+The user creates packets header, gets the chunk of the BIOS image and
+places it next to the packetheader; now, the packetheader + BIOS image chunk
+added together should match the specified packet_size. This makes one
+packet, the user needs to create more such packets out of the entire BIOS
+image file and then arrange all these packets back to back in to one single
+file.
+
+This file is then copied to /sys/class/firmware/dell_rbu/data.
+Once this file gets to the driver, the driver extracts packet_size data from
+the file and spreads it across the physical memory in contiguous packet_sized
+space.
+
+This method makes sure that all the packets get to the driver in a single operation.
+
+In monolithic update the user simply get the BIOS image (.hdr file) and copies
+to the data file as is without any change to the BIOS image itself.
+
+Do the steps below to download the BIOS image.
+
+1) echo 1 > /sys/class/firmware/dell_rbu/loading
+2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data
+3) echo 0 > /sys/class/firmware/dell_rbu/loading
+
+The /sys/class/firmware/dell_rbu/ entries will remain till the following is
+done.
+
+::
+
+ echo -1 > /sys/class/firmware/dell_rbu/loading
+
+Until this step is completed the driver cannot be unloaded.
+
+Also echoing either mono, packet or init in to image_type will free up the
+memory allocated by the driver.
+
+If a user by accident executes steps 1 and 3 above without executing step 2;
+it will make the /sys/class/firmware/dell_rbu/ entries disappear.
+
+The entries can be recreated by doing the following::
+
+ echo init > /sys/devices/platform/dell_rbu/image_type
+
+.. note:: echoing init in image_type does not change its original value.
+
+Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to
+read back the image downloaded.
+
+.. note::
+
+ After updating the BIOS image a user mode application needs to execute
+ code which sends the BIOS update request to the BIOS. So on the next reboot
+ the BIOS knows about the new image downloaded and it updates itself.
+ Also don't unload the rbu driver if the image has to be updated.
+
diff --git a/Documentation/admin-guide/device-mapper/cache-policies.rst b/Documentation/admin-guide/device-mapper/cache-policies.rst
new file mode 100644
index 000000000000..13da4d831d46
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/cache-policies.rst
@@ -0,0 +1,131 @@
+=============================
+Guidance for writing policies
+=============================
+
+Try to keep transactionality out of it. The core is careful to
+avoid asking about anything that is migrating. This is a pain, but
+makes it easier to write the policies.
+
+Mappings are loaded into the policy at construction time.
+
+Every bio that is mapped by the target is referred to the policy.
+The policy can return a simple HIT or MISS or issue a migration.
+
+Currently there's no way for the policy to issue background work,
+e.g. to start writing back dirty blocks that are going to be evicted
+soon.
+
+Because we map bios, rather than requests it's easy for the policy
+to get fooled by many small bios. For this reason the core target
+issues periodic ticks to the policy. It's suggested that the policy
+doesn't update states (eg, hit counts) for a block more than once
+for each tick. The core ticks by watching bios complete, and so
+trying to see when the io scheduler has let the ios run.
+
+
+Overview of supplied cache replacement policies
+===============================================
+
+multiqueue (mq)
+---------------
+
+This policy is now an alias for smq (see below).
+
+The following tunables are accepted, but have no effect::
+
+ 'sequential_threshold <#nr_sequential_ios>'
+ 'random_threshold <#nr_random_ios>'
+ 'read_promote_adjustment <value>'
+ 'write_promote_adjustment <value>'
+ 'discard_promote_adjustment <value>'
+
+Stochastic multiqueue (smq)
+---------------------------
+
+This policy is the default.
+
+The stochastic multi-queue (smq) policy addresses some of the problems
+with the multiqueue (mq) policy.
+
+The smq policy (vs mq) offers the promise of less memory utilization,
+improved performance and increased adaptability in the face of changing
+workloads. smq also does not have any cumbersome tuning knobs.
+
+Users may switch from "mq" to "smq" simply by appropriately reloading a
+DM table that is using the cache target. Doing so will cause all of the
+mq policy's hints to be dropped. Also, performance of the cache may
+degrade slightly until smq recalculates the origin device's hotspots
+that should be cached.
+
+Memory usage
+^^^^^^^^^^^^
+
+The mq policy used a lot of memory; 88 bytes per cache block on a 64
+bit machine.
+
+smq uses 28bit indexes to implement its data structures rather than
+pointers. It avoids storing an explicit hit count for each block. It
+has a 'hotspot' queue, rather than a pre-cache, which uses a quarter of
+the entries (each hotspot block covers a larger area than a single
+cache block).
+
+All this means smq uses ~25bytes per cache block. Still a lot of
+memory, but a substantial improvement nonetheless.
+
+Level balancing
+^^^^^^^^^^^^^^^
+
+mq placed entries in different levels of the multiqueue structures
+based on their hit count (~ln(hit count)). This meant the bottom
+levels generally had the most entries, and the top ones had very
+few. Having unbalanced levels like this reduced the efficacy of the
+multiqueue.
+
+smq does not maintain a hit count, instead it swaps hit entries with
+the least recently used entry from the level above. The overall
+ordering being a side effect of this stochastic process. With this
+scheme we can decide how many entries occupy each multiqueue level,
+resulting in better promotion/demotion decisions.
+
+Adaptability:
+The mq policy maintained a hit count for each cache block. For a
+different block to get promoted to the cache its hit count has to
+exceed the lowest currently in the cache. This meant it could take a
+long time for the cache to adapt between varying IO patterns.
+
+smq doesn't maintain hit counts, so a lot of this problem just goes
+away. In addition it tracks performance of the hotspot queue, which
+is used to decide which blocks to promote. If the hotspot queue is
+performing badly then it starts moving entries more quickly between
+levels. This lets it adapt to new IO patterns very quickly.
+
+Performance
+^^^^^^^^^^^
+
+Testing smq shows substantially better performance than mq.
+
+cleaner
+-------
+
+The cleaner writes back all dirty blocks in a cache to decommission it.
+
+Examples
+========
+
+The syntax for a table is::
+
+ cache <metadata dev> <cache dev> <origin dev> <block size>
+ <#feature_args> [<feature arg>]*
+ <policy> <#policy_args> [<policy arg>]*
+
+The syntax to send a message using the dmsetup command is::
+
+ dmsetup message <mapped device> 0 sequential_threshold 1024
+ dmsetup message <mapped device> 0 random_threshold 8
+
+Using dmsetup::
+
+ dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \
+ /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8"
+ creates a 128GB large mapped device named 'blah' with the
+ sequential threshold set to 1024 and the random_threshold set to 8.
diff --git a/Documentation/admin-guide/device-mapper/cache.rst b/Documentation/admin-guide/device-mapper/cache.rst
new file mode 100644
index 000000000000..f15e5254d05b
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/cache.rst
@@ -0,0 +1,337 @@
+=====
+Cache
+=====
+
+Introduction
+============
+
+dm-cache is a device mapper target written by Joe Thornber, Heinz
+Mauelshagen, and Mike Snitzer.
+
+It aims to improve performance of a block device (eg, a spindle) by
+dynamically migrating some of its data to a faster, smaller device
+(eg, an SSD).
+
+This device-mapper solution allows us to insert this caching at
+different levels of the dm stack, for instance above the data device for
+a thin-provisioning pool. Caching solutions that are integrated more
+closely with the virtual memory system should give better performance.
+
+The target reuses the metadata library used in the thin-provisioning
+library.
+
+The decision as to what data to migrate and when is left to a plug-in
+policy module. Several of these have been written as we experiment,
+and we hope other people will contribute others for specific io
+scenarios (eg. a vm image server).
+
+Glossary
+========
+
+ Migration
+ Movement of the primary copy of a logical block from one
+ device to the other.
+ Promotion
+ Migration from slow device to fast device.
+ Demotion
+ Migration from fast device to slow device.
+
+The origin device always contains a copy of the logical block, which
+may be out of date or kept in sync with the copy on the cache device
+(depending on policy).
+
+Design
+======
+
+Sub-devices
+-----------
+
+The target is constructed by passing three devices to it (along with
+other parameters detailed later):
+
+1. An origin device - the big, slow one.
+
+2. A cache device - the small, fast one.
+
+3. A small metadata device - records which blocks are in the cache,
+ which are dirty, and extra hints for use by the policy object.
+ This information could be put on the cache device, but having it
+ separate allows the volume manager to configure it differently,
+ e.g. as a mirror for extra robustness. This metadata device may only
+ be used by a single cache device.
+
+Fixed block size
+----------------
+
+The origin is divided up into blocks of a fixed size. This block size
+is configurable when you first create the cache. Typically we've been
+using block sizes of 256KB - 1024KB. The block size must be between 64
+sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB).
+
+Having a fixed block size simplifies the target a lot. But it is
+something of a compromise. For instance, a small part of a block may be
+getting hit a lot, yet the whole block will be promoted to the cache.
+So large block sizes are bad because they waste cache space. And small
+block sizes are bad because they increase the amount of metadata (both
+in core and on disk).
+
+Cache operating modes
+---------------------
+
+The cache has three operating modes: writeback, writethrough and
+passthrough.
+
+If writeback, the default, is selected then a write to a block that is
+cached will go only to the cache and the block will be marked dirty in
+the metadata.
+
+If writethrough is selected then a write to a cached block will not
+complete until it has hit both the origin and cache devices. Clean
+blocks should remain clean.
+
+If passthrough is selected, useful when the cache contents are not known
+to be coherent with the origin device, then all reads are served from
+the origin device (all reads miss the cache) and all writes are
+forwarded to the origin device; additionally, write hits cause cache
+block invalidates. To enable passthrough mode the cache must be clean.
+Passthrough mode allows a cache device to be activated without having to
+worry about coherency. Coherency that exists is maintained, although
+the cache will gradually cool as writes take place. If the coherency of
+the cache can later be verified, or established through use of the
+"invalidate_cblocks" message, the cache device can be transitioned to
+writethrough or writeback mode while still warm. Otherwise, the cache
+contents can be discarded prior to transitioning to the desired
+operating mode.
+
+A simple cleaner policy is provided, which will clean (write back) all
+dirty blocks in a cache. Useful for decommissioning a cache or when
+shrinking a cache. Shrinking the cache's fast device requires all cache
+blocks, in the area of the cache being removed, to be clean. If the
+area being removed from the cache still contains dirty blocks the resize
+will fail. Care must be taken to never reduce the volume used for the
+cache's fast device until the cache is clean. This is of particular
+importance if writeback mode is used. Writethrough and passthrough
+modes already maintain a clean cache. Future support to partially clean
+the cache, above a specified threshold, will allow for keeping the cache
+warm and in writeback mode during resize.
+
+Migration throttling
+--------------------
+
+Migrating data between the origin and cache device uses bandwidth.
+The user can set a throttle to prevent more than a certain amount of
+migration occurring at any one time. Currently we're not taking any
+account of normal io traffic going to the devices. More work needs
+doing here to avoid migrating during those peak io moments.
+
+For the time being, a message "migration_threshold <#sectors>"
+can be used to set the maximum number of sectors being migrated,
+the default being 2048 sectors (1MB).
+
+Updating on-disk metadata
+-------------------------
+
+On-disk metadata is committed every time a FLUSH or FUA bio is written.
+If no such requests are made then commits will occur every second. This
+means the cache behaves like a physical disk that has a volatile write
+cache. If power is lost you may lose some recent writes. The metadata
+should always be consistent in spite of any crash.
+
+The 'dirty' state for a cache block changes far too frequently for us
+to keep updating it on the fly. So we treat it as a hint. In normal
+operation it will be written when the dm device is suspended. If the
+system crashes all cache blocks will be assumed dirty when restarted.
+
+Per-block policy hints
+----------------------
+
+Policy plug-ins can store a chunk of data per cache block. It's up to
+the policy how big this chunk is, but it should be kept small. Like the
+dirty flags this data is lost if there's a crash so a safe fallback
+value should always be possible.
+
+Policy hints affect performance, not correctness.
+
+Policy messaging
+----------------
+
+Policies will have different tunables, specific to each one, so we
+need a generic way of getting and setting these. Device-mapper
+messages are used. Refer to cache-policies.txt.
+
+Discard bitset resolution
+-------------------------
+
+We can avoid copying data during migration if we know the block has
+been discarded. A prime example of this is when mkfs discards the
+whole block device. We store a bitset tracking the discard state of
+blocks. However, we allow this bitset to have a different block size
+from the cache blocks. This is because we need to track the discard
+state for all of the origin device (compare with the dirty bitset
+which is just for the smaller cache device).
+
+Target interface
+================
+
+Constructor
+-----------
+
+ ::
+
+ cache <metadata dev> <cache dev> <origin dev> <block size>
+ <#feature args> [<feature arg>]*
+ <policy> <#policy args> [policy args]*
+
+ ================ =======================================================
+ metadata dev fast device holding the persistent metadata
+ cache dev fast device holding cached data blocks
+ origin dev slow device holding original data blocks
+ block size cache unit size in sectors
+
+ #feature args number of feature arguments passed
+ feature args writethrough or passthrough (The default is writeback.)
+
+ policy the replacement policy to use
+ #policy args an even number of arguments corresponding to
+ key/value pairs passed to the policy
+ policy args key/value pairs passed to the policy
+ E.g. 'sequential_threshold 1024'
+ See cache-policies.txt for details.
+ ================ =======================================================
+
+Optional feature arguments are:
+
+
+ ==================== ========================================================
+ writethrough write through caching that prohibits cache block
+ content from being different from origin block content.
+ Without this argument, the default behaviour is to write
+ back cache block contents later for performance reasons,
+ so they may differ from the corresponding origin blocks.
+
+ passthrough a degraded mode useful for various cache coherency
+ situations (e.g., rolling back snapshots of
+ underlying storage). Reads and writes always go to
+ the origin. If a write goes to a cached origin
+ block, then the cache block is invalidated.
+ To enable passthrough mode the cache must be clean.
+
+ metadata2 use version 2 of the metadata. This stores the dirty
+ bits in a separate btree, which improves speed of
+ shutting down the cache.
+
+ no_discard_passdown disable passing down discards from the cache
+ to the origin's data device.
+ ==================== ========================================================
+
+A policy called 'default' is always registered. This is an alias for
+the policy we currently think is giving best all round performance.
+
+As the default policy could vary between kernels, if you are relying on
+the characteristics of a specific policy, always request it by name.
+
+Status
+------
+
+::
+
+ <metadata block size> <#used metadata blocks>/<#total metadata blocks>
+ <cache block size> <#used cache blocks>/<#total cache blocks>
+ <#read hits> <#read misses> <#write hits> <#write misses>
+ <#demotions> <#promotions> <#dirty> <#features> <features>*
+ <#core args> <core args>* <policy name> <#policy args> <policy args>*
+ <cache metadata mode>
+
+
+========================= =====================================================
+metadata block size Fixed block size for each metadata block in
+ sectors
+#used metadata blocks Number of metadata blocks used
+#total metadata blocks Total number of metadata blocks
+cache block size Configurable block size for the cache device
+ in sectors
+#used cache blocks Number of blocks resident in the cache
+#total cache blocks Total number of cache blocks
+#read hits Number of times a READ bio has been mapped
+ to the cache
+#read misses Number of times a READ bio has been mapped
+ to the origin
+#write hits Number of times a WRITE bio has been mapped
+ to the cache
+#write misses Number of times a WRITE bio has been
+ mapped to the origin
+#demotions Number of times a block has been removed
+ from the cache
+#promotions Number of times a block has been moved to
+ the cache
+#dirty Number of blocks in the cache that differ
+ from the origin
+#feature args Number of feature args to follow
+feature args 'writethrough' (optional)
+#core args Number of core arguments (must be even)
+core args Key/value pairs for tuning the core
+ e.g. migration_threshold
+policy name Name of the policy
+#policy args Number of policy arguments to follow (must be even)
+policy args Key/value pairs e.g. sequential_threshold
+cache metadata mode ro if read-only, rw if read-write
+
+ In serious cases where even a read-only mode is
+ deemed unsafe no further I/O will be permitted and
+ the status will just contain the string 'Fail'.
+ The userspace recovery tools should then be used.
+needs_check 'needs_check' if set, '-' if not set
+ A metadata operation has failed, resulting in the
+ needs_check flag being set in the metadata's
+ superblock. The metadata device must be
+ deactivated and checked/repaired before the
+ cache can be made fully operational again.
+ '-' indicates needs_check is not set.
+========================= =====================================================
+
+Messages
+--------
+
+Policies will have different tunables, specific to each one, so we
+need a generic way of getting and setting these. Device-mapper
+messages are used. (A sysfs interface would also be possible.)
+
+The message format is::
+
+ <key> <value>
+
+E.g.::
+
+ dmsetup message my_cache 0 sequential_threshold 1024
+
+
+Invalidation is removing an entry from the cache without writing it
+back. Cache blocks can be invalidated via the invalidate_cblocks
+message, which takes an arbitrary number of cblock ranges. Each cblock
+range's end value is "one past the end", meaning 5-10 expresses a range
+of values from 5 to 9. Each cblock must be expressed as a decimal
+value, in the future a variant message that takes cblock ranges
+expressed in hexadecimal may be needed to better support efficient
+invalidation of larger caches. The cache must be in passthrough mode
+when invalidate_cblocks is used::
+
+ invalidate_cblocks [<cblock>|<cblock begin>-<cblock end>]*
+
+E.g.::
+
+ dmsetup message my_cache 0 invalidate_cblocks 2345 3456-4567 5678-6789
+
+Examples
+========
+
+The test suite can be found here:
+
+https://github.com/jthornber/device-mapper-test-suite
+
+::
+
+ dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
+ /dev/mapper/ssd /dev/mapper/origin 512 1 writeback default 0'
+ dmsetup create my_cache --table '0 41943040 cache /dev/mapper/metadata \
+ /dev/mapper/ssd /dev/mapper/origin 1024 1 writeback \
+ mq 4 sequential_threshold 1024 random_threshold 8'
diff --git a/Documentation/admin-guide/device-mapper/delay.rst b/Documentation/admin-guide/device-mapper/delay.rst
new file mode 100644
index 000000000000..a1e673c0e782
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/delay.rst
@@ -0,0 +1,54 @@
+========
+dm-delay
+========
+
+Device-Mapper's "delay" target delays reads and/or writes
+and/or flushes and optionally maps them to different devices.
+
+Arguments::
+
+ <device> <offset> <delay> [<write_device> <write_offset> <write_delay>
+ [<flush_device> <flush_offset> <flush_delay>]]
+
+Table line has to either have 3, 6 or 9 arguments:
+
+3: apply offset and delay to read, write and flush operations on device
+
+6: apply offset and delay to device, also apply write_offset and write_delay
+ 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 explicitly
+ on/with optionally different flush_device/flush_offset.
+
+Offsets are specified in sectors.
+
+Delays are specified in milliseconds.
+
+
+Example scripts
+===============
+
+::
+ #!/bin/sh
+ #
+ # Create mapped device named "delayed" delaying read, write and flush operations for 500ms.
+ #
+ dmsetup create delayed --table "0 `blockdev --getsz $1` delay $1 0 500"
+
+::
+ #!/bin/sh
+ #
+ # Create mapped device delaying write and flush operations for 400ms and
+ # 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"
+
+::
+ #!/bin/sh
+ #
+ # 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-clone.rst b/Documentation/admin-guide/device-mapper/dm-clone.rst
new file mode 100644
index 000000000000..b43a34c1430a
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-clone.rst
@@ -0,0 +1,333 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+========
+dm-clone
+========
+
+Introduction
+============
+
+dm-clone is a device mapper target which produces a one-to-one copy of an
+existing, read-only source device into a writable destination device: It
+presents a virtual block device which makes all data appear immediately, and
+redirects reads and writes accordingly.
+
+The main use case of dm-clone is to clone a potentially remote, high-latency,
+read-only, archival-type block device into a writable, fast, primary-type device
+for fast, low-latency I/O. The cloned device is visible/mountable immediately
+and the copy of the source device to the destination device happens in the
+background, in parallel with user I/O.
+
+For example, one could restore an application backup from a read-only copy,
+accessible through a network storage protocol (NBD, Fibre Channel, iSCSI, AoE,
+etc.), into a local SSD or NVMe device, and start using the device immediately,
+without waiting for the restore to complete.
+
+When the cloning completes, the dm-clone table can be removed altogether and be
+replaced, e.g., by a linear table, mapping directly to the destination device.
+
+The dm-clone target reuses the metadata library used by the thin-provisioning
+target.
+
+Glossary
+========
+
+ Hydration
+ The process of filling a region of the destination device with data from
+ the same region of the source device, i.e., copying the region from the
+ source to the destination device.
+
+Once a region gets hydrated we redirect all I/O regarding it to the destination
+device.
+
+Design
+======
+
+Sub-devices
+-----------
+
+The target is constructed by passing three devices to it (along with other
+parameters detailed later):
+
+1. A source device - the read-only device that gets cloned and source of the
+ hydration.
+
+2. A destination device - the destination of the hydration, which will become a
+ clone of the source device.
+
+3. A small metadata device - it records which regions are already valid in the
+ destination device, i.e., which regions have already been hydrated, or have
+ been written to directly, via user I/O.
+
+The size of the destination device must be at least equal to the size of the
+source device.
+
+Regions
+-------
+
+dm-clone divides the source and destination devices in fixed sized regions.
+Regions are the unit of hydration, i.e., the minimum amount of data copied from
+the source to the destination device.
+
+The region size is configurable when you first create the dm-clone device. The
+recommended region size is the same as the file system block size, which usually
+is 4KB. The region size must be between 8 sectors (4KB) and 2097152 sectors
+(1GB) and a power of two.
+
+Reads and writes from/to hydrated regions are serviced from the destination
+device.
+
+A read to a not yet hydrated region is serviced directly from the source device.
+
+A write to a not yet hydrated region will be delayed until the corresponding
+region has been hydrated and the hydration of the region starts immediately.
+
+Note that a write request with size equal to region size will skip copying of
+the corresponding region from the source device and overwrite the region of the
+destination device directly.
+
+Discards
+--------
+
+dm-clone interprets a discard request to a range that hasn't been hydrated yet
+as a hint to skip hydration of the regions covered by the request, i.e., it
+skips copying the region's data from the source to the destination device, and
+only updates its metadata.
+
+If the destination device supports discards, then by default dm-clone will pass
+down discard requests to it.
+
+Background Hydration
+--------------------
+
+dm-clone copies continuously from the source to the destination device, until
+all of the device has been copied.
+
+Copying data from the source to the destination device uses bandwidth. The user
+can set a throttle to prevent more than a certain amount of copying occurring at
+any one time. Moreover, dm-clone takes into account user I/O traffic going to
+the devices and pauses the background hydration when there is I/O in-flight.
+
+A message `hydration_threshold <#regions>` can be used to set the maximum number
+of regions being copied, the default being 1 region.
+
+dm-clone employs dm-kcopyd for copying portions of the source device to the
+destination device. By default, we issue copy requests of size equal to the
+region size. A message `hydration_batch_size <#regions>` can be used to tune the
+size of these copy requests. Increasing the hydration batch size results in
+dm-clone trying to batch together contiguous regions, so we copy the data in
+batches of this many regions.
+
+When the hydration of the destination device finishes, a dm event will be sent
+to user space.
+
+Updating on-disk metadata
+-------------------------
+
+On-disk metadata is committed every time a FLUSH or FUA bio is written. If no
+such requests are made then commits will occur every second. This means the
+dm-clone device behaves like a physical disk that has a volatile write cache. If
+power is lost you may lose some recent writes. The metadata should always be
+consistent in spite of any crash.
+
+Target Interface
+================
+
+Constructor
+-----------
+
+ ::
+
+ clone <metadata dev> <destination dev> <source dev> <region size>
+ [<#feature args> [<feature arg>]* [<#core args> [<core arg>]*]]
+
+ ================ ==============================================================
+ metadata dev Fast device holding the persistent metadata
+ destination dev The destination device, where the source will be cloned
+ source dev Read only device containing the data that gets cloned
+ region size The size of a region in sectors
+
+ #feature args Number of feature arguments passed
+ feature args no_hydration or no_discard_passdown
+
+ #core args An even number of arguments corresponding to key/value pairs
+ passed to dm-clone
+ core args Key/value pairs passed to dm-clone, e.g. `hydration_threshold
+ 256`
+ ================ ==============================================================
+
+Optional feature arguments are:
+
+ ==================== =========================================================
+ no_hydration Create a dm-clone instance with background hydration
+ disabled
+ no_discard_passdown Disable passing down discards to the destination device
+ ==================== =========================================================
+
+Optional core arguments are:
+
+ ================================ ==============================================
+ hydration_threshold <#regions> Maximum number of regions being copied from
+ the source to the destination device at any
+ one time, during background hydration.
+ hydration_batch_size <#regions> During background hydration, try to batch
+ together contiguous regions, so we copy data
+ from the source to the destination device in
+ batches of this many regions.
+ ================================ ==============================================
+
+Status
+------
+
+ ::
+
+ <metadata block size> <#used metadata blocks>/<#total metadata blocks>
+ <region size> <#hydrated regions>/<#total regions> <#hydrating regions>
+ <#feature args> <feature args>* <#core args> <core args>*
+ <clone metadata mode>
+
+ ======================= =======================================================
+ metadata block size Fixed block size for each metadata block in sectors
+ #used metadata blocks Number of metadata blocks used
+ #total metadata blocks Total number of metadata blocks
+ region size Configurable region size for the device in sectors
+ #hydrated regions Number of regions that have finished hydrating
+ #total regions Total number of regions to hydrate
+ #hydrating regions Number of regions currently hydrating
+ #feature args Number of feature arguments to follow
+ feature args Feature arguments, e.g. `no_hydration`
+ #core args Even number of core arguments to follow
+ core args Key/value pairs for tuning the core, e.g.
+ `hydration_threshold 256`
+ clone metadata mode ro if read-only, rw if read-write
+
+ In serious cases where even a read-only mode is deemed
+ unsafe no further I/O will be permitted and the status
+ will just contain the string 'Fail'. If the metadata
+ mode changes, a dm event will be sent to user space.
+ ======================= =======================================================
+
+Messages
+--------
+
+ `disable_hydration`
+ Disable the background hydration of the destination device.
+
+ `enable_hydration`
+ Enable the background hydration of the destination device.
+
+ `hydration_threshold <#regions>`
+ Set background hydration threshold.
+
+ `hydration_batch_size <#regions>`
+ Set background hydration batch size.
+
+Examples
+========
+
+Clone a device containing a file system
+---------------------------------------
+
+1. Create the dm-clone device.
+
+ ::
+
+ dmsetup create clone --table "0 1048576000 clone $metadata_dev $dest_dev \
+ $source_dev 8 1 no_hydration"
+
+2. Mount the device and trim the file system. dm-clone interprets the discards
+ sent by the file system and it will not hydrate the unused space.
+
+ ::
+
+ mount /dev/mapper/clone /mnt/cloned-fs
+ fstrim /mnt/cloned-fs
+
+3. Enable background hydration of the destination device.
+
+ ::
+
+ dmsetup message clone 0 enable_hydration
+
+4. When the hydration finishes, we can replace the dm-clone table with a linear
+ table.
+
+ ::
+
+ dmsetup suspend clone
+ dmsetup load clone --table "0 1048576000 linear $dest_dev 0"
+ dmsetup resume clone
+
+ The metadata device is no longer needed and can be safely discarded or reused
+ for other purposes.
+
+Known issues
+============
+
+1. We redirect reads, to not-yet-hydrated regions, to the source device. If
+ reading the source device has high latency and the user repeatedly reads from
+ the same regions, this behaviour could degrade performance. We should use
+ these reads as hints to hydrate the relevant regions sooner. Currently, we
+ rely on the page cache to cache these regions, so we hopefully don't end up
+ reading them multiple times from the source device.
+
+2. Release in-core resources, i.e., the bitmaps tracking which regions are
+ hydrated, after the hydration has finished.
+
+3. During background hydration, if we fail to read the source or write to the
+ destination device, we print an error message, but the hydration process
+ continues indefinitely, until it succeeds. We should stop the background
+ hydration after a number of failures and emit a dm event for user space to
+ notice.
+
+Why not...?
+===========
+
+We explored the following alternatives before implementing dm-clone:
+
+1. Use dm-cache with cache size equal to the source device and implement a new
+ cloning policy:
+
+ * The resulting cache device is not a one-to-one mirror of the source device
+ and thus we cannot remove the cache device once cloning completes.
+
+ * dm-cache writes to the source device, which violates our requirement that
+ the source device must be treated as read-only.
+
+ * Caching is semantically different from cloning.
+
+2. Use dm-snapshot with a COW device equal to the source device:
+
+ * dm-snapshot stores its metadata in the COW device, so the resulting device
+ is not a one-to-one mirror of the source device.
+
+ * No background copying mechanism.
+
+ * dm-snapshot needs to commit its metadata whenever a pending exception
+ completes, to ensure snapshot consistency. In the case of cloning, we don't
+ need to be so strict and can rely on committing metadata every time a FLUSH
+ or FUA bio is written, or periodically, like dm-thin and dm-cache do. This
+ improves the performance significantly.
+
+3. Use dm-mirror: The mirror target has a background copying/mirroring
+ mechanism, but it writes to all mirrors, thus violating our requirement that
+ the source device must be treated as read-only.
+
+4. Use dm-thin's external snapshot functionality. This approach is the most
+ promising among all alternatives, as the thinly-provisioned volume is a
+ one-to-one mirror of the source device and handles reads and writes to
+ un-provisioned/not-yet-cloned areas the same way as dm-clone does.
+
+ Still:
+
+ * There is no background copying mechanism, though one could be implemented.
+
+ * Most importantly, we want to support arbitrary block devices as the
+ destination of the cloning process and not restrict ourselves to
+ thinly-provisioned volumes. Thin-provisioning has an inherent metadata
+ overhead, for maintaining the thin volume mappings, which significantly
+ degrades performance.
+
+ Moreover, cloning a device shouldn't force the use of thin-provisioning. On
+ the other hand, if we wish to use thin provisioning, we can just use a thin
+ LV as dm-clone's destination device.
diff --git a/Documentation/admin-guide/device-mapper/dm-crypt.rst b/Documentation/admin-guide/device-mapper/dm-crypt.rst
new file mode 100644
index 000000000000..4467f6d4b632
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-crypt.rst
@@ -0,0 +1,212 @@
+========
+dm-crypt
+========
+
+Device-Mapper's "crypt" target provides transparent encryption of block devices
+using the kernel crypto API.
+
+For a more detailed description of supported parameters see:
+https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
+
+Parameters::
+
+ <cipher> <key> <iv_offset> <device path> \
+ <offset> [<#opt_params> <opt_params>]
+
+<cipher>
+ Encryption cipher, encryption mode and Initial Vector (IV) generator.
+
+ The cipher specifications format is::
+
+ cipher[:keycount]-chainmode-ivmode[:ivopts]
+
+ Examples::
+
+ aes-cbc-essiv:sha256
+ aes-xts-plain64
+ serpent-xts-plain64
+
+ Cipher format also supports direct specification with kernel crypt API
+ format (selected by capi: prefix). The IV specification is the same
+ as for the first format type.
+ This format is mainly used for specification of authenticated modes.
+
+ The crypto API cipher specifications format is::
+
+ capi:cipher_api_spec-ivmode[:ivopts]
+
+ Examples::
+
+ capi:cbc(aes)-essiv:sha256
+ capi:xts(aes)-plain64
+
+ Examples of authenticated modes::
+
+ capi:gcm(aes)-random
+ capi:authenc(hmac(sha256),xts(aes))-random
+ capi:rfc7539(chacha20,poly1305)-random
+
+ The /proc/crypto contains a list of currently loaded crypto modes.
+
+<key>
+ Key used for encryption. It is encoded either as a hexadecimal number
+ or it can be passed as <key_string> prefixed with single colon
+ character (':') for keys residing in kernel keyring service.
+ You can only use key sizes that are valid for the selected cipher
+ in combination with the selected iv mode.
+ Note that for some iv modes the key string can contain additional
+ keys (for example IV seed) so the key contains more parts concatenated
+ into a single string.
+
+<key_string>
+ The kernel keyring key is identified by string in following format:
+ <key_size>:<key_type>:<key_description>.
+
+<key_size>
+ The encryption key size in bytes. The kernel key payload size must match
+ the value passed in <key_size>.
+
+<key_type>
+ Either 'logon', 'user', 'encrypted' or 'trusted' kernel key type.
+
+<key_description>
+ The kernel keyring key description crypt target should look for
+ when loading key of <key_type>.
+
+<keycount>
+ Multi-key compatibility mode. You can define <keycount> keys and
+ then sectors are encrypted according to their offsets (sector 0 uses key0;
+ sector 1 uses key1 etc.). <keycount> must be a power of two.
+
+<iv_offset>
+ The IV offset is a sector count that is added to the sector number
+ before creating the IV.
+
+<device path>
+ This is the device that is going to be used as backend and contains the
+ encrypted data. You can specify it as a path like /dev/xxx or a device
+ number <major>:<minor>.
+
+<offset>
+ Starting sector within the device where the encrypted data begins.
+
+<#opt_params>
+ Number of optional parameters. If there are no optional parameters,
+ the optional parameters section can be skipped or #opt_params can be zero.
+ Otherwise #opt_params is the number of following arguments.
+
+ Example of optional parameters section:
+ 3 allow_discards same_cpu_crypt submit_from_crypt_cpus
+
+allow_discards
+ Block discard requests (a.k.a. TRIM) are passed through the crypt device.
+ The default is to ignore discard requests.
+
+ WARNING: Assess the specific security risks carefully before enabling this
+ option. For example, allowing discards on encrypted devices may lead to
+ the leak of information about the ciphertext device (filesystem type,
+ used space etc.) if the discarded blocks can be located easily on the
+ device later.
+
+same_cpu_crypt
+ Perform encryption using the same cpu that IO was submitted on.
+ The default is to use an unbound workqueue so that encryption work
+ is automatically balanced between available CPUs.
+
+high_priority
+ Set dm-crypt workqueues and the writer thread to high priority. This
+ improves throughput and latency of dm-crypt while degrading general
+ responsiveness of the system.
+
+submit_from_crypt_cpus
+ Disable offloading writes to a separate thread after encryption.
+ There are some situations where offloading write bios from the
+ encryption threads to a single thread degrades performance
+ significantly. The default is to offload write bios to the same
+ thread because it benefits CFQ to have writes submitted using the
+ same context.
+
+no_read_workqueue
+ Bypass dm-crypt internal workqueue and process read requests synchronously.
+
+no_write_workqueue
+ Bypass dm-crypt internal workqueue and process write requests synchronously.
+ This option is automatically enabled for host-managed zoned block devices
+ (e.g. host-managed SMR hard-disks).
+
+integrity:<bytes>:<type>
+ The device requires additional <bytes> metadata per-sector stored
+ in per-bio integrity structure. This metadata must by provided
+ by underlying dm-integrity target.
+
+ The <type> can be "none" if metadata is used only for persistent IV.
+
+ For Authenticated Encryption with Additional Data (AEAD)
+ the <type> is "aead". An AEAD mode additionally calculates and verifies
+ integrity for the encrypted device. The additional space is then
+ used for storing authentication tag (and persistent IV if needed).
+
+integrity_key_size:<bytes>
+ Optionally set the integrity key size if it differs from the digest size.
+ It allows the use of wrapped key algorithms where the key size is
+ independent of the cryptographic key size.
+
+sector_size:<bytes>
+ Use <bytes> as the encryption unit instead of 512 bytes sectors.
+ This option can be in range 512 - 4096 bytes and must be power of two.
+ Virtual device will announce this size as a minimal IO and logical sector.
+
+iv_large_sectors
+ IV generators will use sector number counted in <sector_size> units
+ instead of default 512 bytes sectors.
+
+ For example, if <sector_size> is 4096 bytes, plain64 IV for the second
+ sector will be 8 (without flag) and 1 if iv_large_sectors is present.
+ The <iv_offset> must be multiple of <sector_size> (in 512 bytes units)
+ if this flag is specified.
+
+integrity_key_size:<bytes>
+ Use an integrity key of <bytes> size instead of using an integrity key size
+ of the digest size of the used HMAC algorithm.
+
+
+Module parameters::
+ max_read_size
+ Maximum size of read requests. When a request larger than this size
+ is received, dm-crypt will split the request. The splitting improves
+ concurrency (the split requests could be encrypted in parallel by multiple
+ cores), but it also causes overhead. The user should tune this parameters to
+ fit the actual workload.
+
+ max_write_size
+ Maximum size of write requests. When a request larger than this size
+ is received, dm-crypt will split the request. The splitting improves
+ concurrency (the split requests could be encrypted in parallel by multiple
+ cores), but it also causes overhead. The user should tune this parameters to
+ fit the actual workload.
+
+
+Example scripts
+===============
+LUKS (Linux Unified Key Setup) is now the preferred way to set up disk
+encryption with dm-crypt using the 'cryptsetup' utility, see
+https://gitlab.com/cryptsetup/cryptsetup
+
+::
+
+ #!/bin/sh
+ # Create a crypt device using dmsetup
+ dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0"
+
+::
+
+ #!/bin/sh
+ # Create a crypt device using dmsetup when encryption key is stored in keyring service
+ dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0"
+
+::
+
+ #!/bin/sh
+ # Create a crypt device using cryptsetup and LUKS header with default cipher
+ cryptsetup luksFormat $1
+ cryptsetup luksOpen $1 crypt1
diff --git a/Documentation/admin-guide/device-mapper/dm-dust.rst b/Documentation/admin-guide/device-mapper/dm-dust.rst
new file mode 100644
index 000000000000..e35ec8cd2f88
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-dust.rst
@@ -0,0 +1,305 @@
+dm-dust
+=======
+
+This target emulates the behavior of bad sectors at arbitrary
+locations, and the ability to enable the emulation of the failures
+at an arbitrary time.
+
+This target behaves similarly to a linear target. At a given time,
+the user can send a message to the target to start failing read
+requests on specific blocks (to emulate the behavior of a hard disk
+drive with bad sectors).
+
+When the failure behavior is enabled (i.e.: when the output of
+"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks
+in the "bad block list" will fail with EIO ("Input/output error").
+
+Writes of blocks in the "bad block list will result in the following:
+
+1. Remove the block from the "bad block list".
+2. Successfully complete the write.
+
+This emulates the "remapped sector" behavior of a drive with bad
+sectors.
+
+Normally, a drive that is encountering bad sectors will most likely
+encounter more bad sectors, at an unknown time or location.
+With dm-dust, the user can use the "addbadblock" and "removebadblock"
+messages to add arbitrary bad blocks at new locations, and the
+"enable" and "disable" messages to modulate the state of whether the
+configured "bad blocks" will be treated as bad, or bypassed.
+This allows the pre-writing of test data and metadata prior to
+simulating a "failure" event where bad sectors start to appear.
+
+Table parameters
+----------------
+<device_path> <offset> <blksz>
+
+Mandatory parameters:
+ <device_path>:
+ Path to the block device.
+
+ <offset>:
+ Offset to data area from start of device_path
+
+ <blksz>:
+ Block size in bytes
+
+ (minimum 512, maximum 1073741824, must be a power of 2)
+
+Usage instructions
+------------------
+
+First, find the size (in 512-byte sectors) of the device to be used::
+
+ $ sudo blockdev --getsz /dev/vdb1
+ 33552384
+
+Create the dm-dust device:
+(For a device with a block size of 512 bytes)
+
+::
+
+ $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512'
+
+(For a device with a block size of 4096 bytes)
+
+::
+
+ $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096'
+
+Check the status of the read behavior ("bypass" indicates that all I/O
+will be passed through to the underlying device; "verbose" indicates that
+bad block additions, removals, and remaps will be verbosely logged)::
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 bypass verbose
+
+ $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
+ 128+0 records in
+ 128+0 records out
+
+ $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
+ 128+0 records in
+ 128+0 records out
+
+Adding and removing bad blocks
+------------------------------
+
+At any time (i.e.: whether the device has the "bad block" emulation
+enabled or disabled), bad blocks may be added or removed from the
+device via the "addbadblock" and "removebadblock" messages::
+
+ $ sudo dmsetup message dust1 0 addbadblock 60
+ kernel: device-mapper: dust: badblock added at block 60
+
+ $ sudo dmsetup message dust1 0 addbadblock 67
+ kernel: device-mapper: dust: badblock added at block 67
+
+ $ sudo dmsetup message dust1 0 addbadblock 72
+ kernel: device-mapper: dust: badblock added at block 72
+
+These bad blocks will be stored in the "bad block list".
+While the device is in "bypass" mode, reads and writes will succeed::
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 bypass
+
+Enabling block read failures
+----------------------------
+
+To enable the "fail read on bad block" behavior, send the "enable" message::
+
+ $ sudo dmsetup message dust1 0 enable
+ kernel: device-mapper: dust: enabling read failures on bad sectors
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 fail_read_on_bad_block
+
+With the device in "fail read on bad block" mode, attempting to read a
+block will encounter an "Input/output error"::
+
+ $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct
+ dd: error reading '/dev/mapper/dust1': Input/output error
+ 0+0 records in
+ 0+0 records out
+ 0 bytes copied, 0.00040651 s, 0.0 kB/s
+
+...and writing to the bad blocks will remove the blocks from the list,
+therefore emulating the "remap" behavior of hard disk drives::
+
+ $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
+ 128+0 records in
+ 128+0 records out
+
+ kernel: device-mapper: dust: block 60 removed from badblocklist by write
+ kernel: device-mapper: dust: block 67 removed from badblocklist by write
+ kernel: device-mapper: dust: block 72 removed from badblocklist by write
+ kernel: device-mapper: dust: block 87 removed from badblocklist by write
+
+Bad block add/remove error handling
+-----------------------------------
+
+Attempting to add a bad block that already exists in the list will
+result in an "Invalid argument" error, as well as a helpful message::
+
+ $ sudo dmsetup message dust1 0 addbadblock 88
+ device-mapper: message ioctl on dust1 failed: Invalid argument
+ kernel: device-mapper: dust: block 88 already in badblocklist
+
+Attempting to remove a bad block that doesn't exist in the list will
+result in an "Invalid argument" error, as well as a helpful message::
+
+ $ sudo dmsetup message dust1 0 removebadblock 87
+ device-mapper: message ioctl on dust1 failed: Invalid argument
+ kernel: device-mapper: dust: block 87 not found in badblocklist
+
+Counting the number of bad blocks in the bad block list
+-------------------------------------------------------
+
+To count the number of bad blocks configured in the device, run the
+following message command::
+
+ $ sudo dmsetup message dust1 0 countbadblocks
+
+A message will print with the number of bad blocks currently
+configured on the device::
+
+ countbadblocks: 895 badblock(s) found
+
+Querying for specific bad blocks
+--------------------------------
+
+To find out if a specific block is in the bad block list, run the
+following message command::
+
+ $ sudo dmsetup message dust1 0 queryblock 72
+
+The following message will print if the block is in the list::
+
+ dust_query_block: block 72 found in badblocklist
+
+The following message will print if the block is not in the list::
+
+ dust_query_block: block 72 not found in badblocklist
+
+The "queryblock" message command will work in both the "enabled"
+and "disabled" modes, allowing the verification of whether a block
+will be treated as "bad" without having to issue I/O to the device,
+or having to "enable" the bad block emulation.
+
+Clearing the bad block list
+---------------------------
+
+To clear the bad block list (without needing to individually run
+a "removebadblock" message command for every block), run the
+following message command::
+
+ $ sudo dmsetup message dust1 0 clearbadblocks
+
+After clearing the bad block list, the following message will appear::
+
+ dust_clear_badblocks: badblocks cleared
+
+If there were no bad blocks to clear, the following message will
+appear::
+
+ dust_clear_badblocks: no badblocks found
+
+Listing the bad block list
+--------------------------
+
+To list all bad blocks in the bad block list (using an example device
+with blocks 1 and 2 in the bad block list), run the following message
+command::
+
+ $ sudo dmsetup message dust1 0 listbadblocks
+ 1
+ 2
+
+If there are no bad blocks in the bad block list, the command will
+execute with no output::
+
+ $ sudo dmsetup message dust1 0 listbadblocks
+
+Message commands list
+---------------------
+
+Below is a list of the messages that can be sent to a dust device:
+
+Operations on blocks (requires a <blknum> argument)::
+
+ addbadblock <blknum>
+ queryblock <blknum>
+ removebadblock <blknum>
+
+...where <blknum> is a block number within range of the device
+(corresponding to the block size of the device.)
+
+Single argument message commands::
+
+ countbadblocks
+ clearbadblocks
+ listbadblocks
+ disable
+ enable
+ quiet
+
+Device removal
+--------------
+
+When finished, remove the device via the "dmsetup remove" command::
+
+ $ sudo dmsetup remove dust1
+
+Quiet mode
+----------
+
+On test runs with many bad blocks, it may be desirable to avoid
+excessive logging (from bad blocks added, removed, or "remapped").
+This can be done by enabling "quiet mode" via the following message::
+
+ $ sudo dmsetup message dust1 0 quiet
+
+This will suppress log messages from add / remove / removed by write
+operations. Log messages from "countbadblocks" or "queryblock"
+message commands will still print in quiet mode.
+
+The status of quiet mode can be seen by running "dmsetup status"::
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 fail_read_on_bad_block quiet
+
+To disable quiet mode, send the "quiet" message again::
+
+ $ sudo dmsetup message dust1 0 quiet
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 fail_read_on_bad_block verbose
+
+(The presence of "verbose" indicates normal logging.)
+
+"Why not...?"
+-------------
+
+scsi_debug has a "medium error" mode that can fail reads on one
+specified sector (sector 0x1234, hardcoded in the source code), but
+it uses RAM for the persistent storage, which drastically decreases
+the potential device size.
+
+dm-flakey fails all I/O from all block locations at a specified time
+frequency, and not a given point in time.
+
+When a bad sector occurs on a hard disk drive, reads to that sector
+are failed by the device, usually resulting in an error code of EIO
+("I/O error") or ENODATA ("No data available"). However, a write to
+the sector may succeed, and result in the sector becoming readable
+after the device controller no longer experiences errors reading the
+sector (or after a reallocation of the sector). However, there may
+be bad sectors that occur on the device in the future, in a different,
+unpredictable location.
+
+This target seeks to provide a device that can exhibit the behavior
+of a bad sector at a known sector location, at a known time, based
+on a large storage device (at least tens of gigabytes, not occupying
+system memory).
diff --git a/Documentation/admin-guide/device-mapper/dm-ebs.rst b/Documentation/admin-guide/device-mapper/dm-ebs.rst
new file mode 100644
index 000000000000..c09f66db5621
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-ebs.rst
@@ -0,0 +1,51 @@
+======
+dm-ebs
+======
+
+
+This target is similar to the linear target except that it emulates
+a smaller logical block size on a device with a larger logical block
+size. Its main purpose is to provide emulation of 512 byte sectors on
+devices that do not provide this emulation (i.e. 4K native disks).
+
+Supported emulated logical block sizes 512, 1024, 2048 and 4096.
+
+Underlying block size can be set to > 4K to test buffering larger units.
+
+
+Table parameters
+----------------
+ <dev path> <offset> <emulated sectors> [<underlying sectors>]
+
+Mandatory parameters:
+
+ <dev path>:
+ Full pathname to the underlying block-device,
+ or a "major:minor" device-number.
+ <offset>:
+ Starting sector within the device;
+ has to be a multiple of <emulated sectors>.
+ <emulated sectors>:
+ Number of sectors defining the logical block size to be emulated;
+ 1, 2, 4, 8 sectors of 512 bytes supported.
+
+Optional parameter:
+
+ <underlying sectors>:
+ Number of sectors defining the logical block size of <dev path>.
+ 2^N supported, e.g. 8 = emulate 8 sectors of 512 bytes = 4KiB.
+ If not provided, the logical block size of <dev path> will be used.
+
+
+Examples:
+
+Emulate 1 sector = 512 bytes logical block size on /dev/sda starting at
+offset 1024 sectors with underlying devices block size automatically set:
+
+ebs /dev/sda 1024 1
+
+Emulate 2 sector = 1KiB logical block size on /dev/sda starting at
+offset 128 sectors, enforce 2KiB underlying device block size.
+This presumes 2KiB logical blocksize on /dev/sda or less to work:
+
+ebs /dev/sda 128 2 4
diff --git a/Documentation/admin-guide/device-mapper/dm-flakey.rst b/Documentation/admin-guide/device-mapper/dm-flakey.rst
new file mode 100644
index 000000000000..f967c5fea219
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-flakey.rst
@@ -0,0 +1,88 @@
+=========
+dm-flakey
+=========
+
+This target is the same as the linear target except that it exhibits
+unreliable behaviour periodically. It's been found useful in simulating
+failing devices for testing purposes.
+
+Starting from the time the table is loaded, the device is available for
+<up interval> seconds, then exhibits unreliable behaviour for <down
+interval> seconds, and then this cycle repeats.
+
+Also, consider using this in combination with the dm-delay target too,
+which can delay reads and writes and/or send them to different
+underlying devices.
+
+Table parameters
+----------------
+
+::
+
+ <dev path> <offset> <up interval> <down interval> \
+ [<num_features> [<feature arguments>]]
+
+Mandatory parameters:
+
+ <dev path>:
+ Full pathname to the underlying block-device, or a
+ "major:minor" device-number.
+ <offset>:
+ Starting sector within the device.
+ <up interval>:
+ Number of seconds device is available.
+ <down interval>:
+ Number of seconds device returns errors.
+
+Optional feature parameters:
+
+ If no feature parameters are present, during the periods of
+ unreliability, all I/O returns errors.
+
+ error_reads:
+ All read I/O is failed with an error signalled.
+ Write I/O is handled correctly.
+
+ drop_writes:
+ All write I/O is silently ignored.
+ Read I/O is handled correctly.
+
+ error_writes:
+ All write I/O is failed with an error signalled.
+ Read I/O is handled correctly.
+
+ corrupt_bio_byte <Nth_byte> <direction> <value> <flags>:
+ During <down interval>, replace <Nth_byte> of the data of
+ each matching bio with <value>.
+
+ <Nth_byte>:
+ The offset of the byte to replace.
+ Counting starts at 1, to replace the first byte.
+ <direction>:
+ Either 'r' to corrupt reads or 'w' to corrupt writes.
+ 'w' is incompatible with drop_writes.
+ <value>:
+ The value (from 0-255) to write.
+ <flags>:
+ Perform the replacement only if bio->bi_opf has all the
+ selected flags set.
+
+ random_read_corrupt <probability>
+ During <down interval>, replace random byte in a read bio
+ with a random value. probability is an integer between
+ 0 and 1000000000 meaning 0% to 100% probability of corruption.
+
+ random_write_corrupt <probability>
+ During <down interval>, replace random byte in a write bio
+ with a random value. probability is an integer between
+ 0 and 1000000000 meaning 0% to 100% probability of corruption.
+
+Examples:
+
+Replaces the 32nd byte of READ bios with the value 1::
+
+ corrupt_bio_byte 32 r 1 0
+
+Replaces the 224th byte of REQ_META (=32) bios with the value 0::
+
+ corrupt_bio_byte 224 w 0 32
diff --git a/Documentation/admin-guide/device-mapper/dm-ima.rst b/Documentation/admin-guide/device-mapper/dm-ima.rst
new file mode 100644
index 000000000000..a4aa50a828e0
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-ima.rst
@@ -0,0 +1,715 @@
+======
+dm-ima
+======
+
+For a given system, various external services/infrastructure tools
+(including the attestation service) interact with it - both during the
+setup and during rest of the system run-time. They share sensitive data
+and/or execute critical workload on that system. The external services
+may want to verify the current run-time state of the relevant kernel
+subsystems before fully trusting the system with business-critical
+data/workload.
+
+Device mapper plays a critical role on a given system by providing
+various important functionalities to the block devices using various
+target types like crypt, verity, integrity etc. Each of these target
+types’ functionalities can be configured with various attributes.
+The attributes chosen to configure these target types can significantly
+impact the security profile of the block device, and in-turn, of the
+system itself. For instance, the type of encryption algorithm and the
+key size determines the strength of encryption for a given block device.
+
+Therefore, verifying the current state of various block devices as well
+as their various target attributes is crucial for external services before
+fully trusting the system with business-critical data/workload.
+
+IMA kernel subsystem provides the necessary functionality for
+device mapper to measure the state and configuration of
+various block devices -
+
+- by device mapper itself, from within the kernel,
+- in a tamper resistant way,
+- and re-measured - triggered on state/configuration change.
+
+Setting the IMA Policy:
+=======================
+For IMA to measure the data on a given system, the IMA policy on the
+system needs to be updated to have following line, and the system needs
+to be restarted for the measurements to take effect.
+
+::
+
+ /etc/ima/ima-policy
+ measure func=CRITICAL_DATA label=device-mapper template=ima-buf
+
+The measurements will be reflected in the IMA logs, which are located at:
+
+::
+
+ /sys/kernel/security/integrity/ima/ascii_runtime_measurements
+ /sys/kernel/security/integrity/ima/binary_runtime_measurements
+
+Then IMA ASCII measurement log has the following format:
+
+::
+
+ <PCR> <TEMPLATE_DATA_DIGEST> <TEMPLATE_NAME> <TEMPLATE_DATA>
+
+ PCR := Platform Configuration Register, in which the values are registered.
+ This is applicable if TPM chip is in use.
+
+ TEMPLATE_DATA_DIGEST := Template data digest of the IMA record.
+ TEMPLATE_NAME := Template name that registered the integrity value (e.g. ima-buf).
+
+ TEMPLATE_DATA := <ALG> ":" <EVENT_DIGEST> <EVENT_NAME> <EVENT_DATA>
+ It contains data for the specific event to be measured,
+ in a given template data format.
+
+ ALG := Algorithm to compute event digest
+ EVENT_DIGEST := Digest of the event data
+ EVENT_NAME := Description of the event (e.g. 'dm_table_load').
+ EVENT_DATA := The event data to be measured.
+
+|
+
+| *NOTE #1:*
+| The DM target data measured by IMA subsystem can alternatively
+ be queried from userspace by setting DM_IMA_MEASUREMENT_FLAG with
+ DM_TABLE_STATUS_CMD.
+
+|
+
+| *NOTE #2:*
+| The Kernel configuration CONFIG_IMA_DISABLE_HTABLE allows measurement of duplicate records.
+| To support recording duplicate IMA events in the IMA log, the Kernel needs to be configured with
+ CONFIG_IMA_DISABLE_HTABLE=y.
+
+Supported Device States:
+========================
+Following device state changes will trigger IMA measurements:
+
+ 1. Table load
+ #. Device resume
+ #. Device remove
+ #. Table clear
+ #. Device rename
+
+1. Table load:
+---------------
+When a new table is loaded in a device's inactive table slot,
+the device information and target specific details from the
+targets in the table are measured.
+
+The IMA measurement log has the following format for 'dm_table_load':
+
+::
+
+ EVENT_NAME := "dm_table_load"
+ EVENT_DATA := <dm_version_str> ";" <device_metadata> ";" <table_load_data>
+
+ dm_version_str := "dm_version=" <N> "." <N> "." <N>
+ Same as Device Mapper driver version.
+ device_metadata := <device_name> "," <device_uuid> "," <device_major> "," <device_minor> ","
+ <minor_count> "," <num_device_targets> ";"
+
+ device_name := "name=" <dm-device-name>
+ device_uuid := "uuid=" <dm-device-uuid>
+ device_major := "major=" <N>
+ device_minor := "minor=" <N>
+ minor_count := "minor_count=" <N>
+ num_device_targets := "num_targets=" <N>
+ dm-device-name := Name of the device. If it contains special characters like '\', ',', ';',
+ they are prefixed with '\'.
+ dm-device-uuid := UUID of the device. If it contains special characters like '\', ',', ';',
+ they are prefixed with '\'.
+
+ table_load_data := <target_data>
+ Represents the data (as name=value pairs) from various targets in the table,
+ which is being loaded into the DM device's inactive table slot.
+ target_data := <target_data_row> | <target_data><target_data_row>
+
+ target_data_row := <target_index> "," <target_begin> "," <target_len> "," <target_name> ","
+ <target_version> "," <target_attributes> ";"
+ target_index := "target_index=" <N>
+ Represents nth target in the table (from 0 to N-1 targets specified in <num_device_targets>)
+ If all the data for N targets doesn't fit in the given buffer - then the data that fits
+ in the buffer (say from target 0 to x) is measured in a given IMA event.
+ The remaining data from targets x+1 to N-1 is measured in the subsequent IMA events,
+ with the same format as that of 'dm_table_load'
+ i.e. <dm_version_str> ";" <device_metadata> ";" <table_load_data>.
+
+ target_begin := "target_begin=" <N>
+ target_len := "target_len=" <N>
+ target_name := Name of the target. 'linear', 'crypt', 'integrity' etc.
+ The targets that are supported for IMA measurements are documented below in the
+ 'Supported targets' section.
+ target_version := "target_version=" <N> "." <N> "." <N>
+ target_attributes := Data containing comma separated list of name=value pairs of target specific attributes.
+
+ For instance, if a linear device is created with the following table entries,
+ # dmsetup create linear1
+ 0 2 linear /dev/loop0 512
+ 2 2 linear /dev/loop0 512
+ 4 2 linear /dev/loop0 512
+ 6 2 linear /dev/loop0 512
+
+ Then IMA ASCII measurement log will have the following entry:
+ (converted from ASCII to text for readability)
+
+ 10 a8c5ff755561c7a28146389d1514c318592af49a ima-buf sha256:4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72
+ dm_table_load
+ dm_version=4.45.0;
+ name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4;
+ target_index=0,target_begin=0,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512;
+ target_index=1,target_begin=2,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512;
+ target_index=2,target_begin=4,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512;
+ target_index=3,target_begin=6,target_len=2,target_name=linear,target_version=1.4.0,device_name=7:0,start=512;
+
+2. Device resume:
+------------------
+When a suspended device is resumed, the device information and the hash of the
+data from previous load of an active table are measured.
+
+The IMA measurement log has the following format for 'dm_device_resume':
+
+::
+
+ EVENT_NAME := "dm_device_resume"
+ EVENT_DATA := <dm_version_str> ";" <device_metadata> ";" <active_table_hash> ";" <current_device_capacity> ";"
+
+ dm_version_str := As described in the 'Table load' section above.
+ device_metadata := As described in the 'Table load' section above.
+ active_table_hash := "active_table_hash=" <table_hash_alg> ":" <table_hash>
+ Rerpresents the hash of the IMA data being measured for the
+ active table for the device.
+ table_hash_alg := Algorithm used to compute the hash.
+ table_hash := Hash of the (<dm_version_str> ";" <device_metadata> ";" <table_load_data> ";")
+ as described in the 'dm_table_load' above.
+ Note: If the table_load data spans across multiple IMA 'dm_table_load'
+ events for a given device, the hash is computed combining all the event data
+ i.e. (<dm_version_str> ";" <device_metadata> ";" <table_load_data> ";")
+ across all those events.
+ current_device_capacity := "current_device_capacity=" <N>
+
+ For instance, if a linear device is resumed with the following command,
+ #dmsetup resume linear1
+
+ then IMA ASCII measurement log will have an entry with:
+ (converted from ASCII to text for readability)
+
+ 10 56c00cc062ffc24ccd9ac2d67d194af3282b934e ima-buf sha256:e7d12c03b958b4e0e53e7363a06376be88d98a1ac191fdbd3baf5e4b77f329b6
+ dm_device_resume
+ dm_version=4.45.0;
+ name=linear1,uuid=,major=253,minor=0,minor_count=1,num_targets=4;
+ active_table_hash=sha256:4d73481ecce5eadba8ab084640d85bb9ca899af4d0a122989252a76efadc5b72;current_device_capacity=8;
+
+3. Device remove:
+------------------
+When a device is removed, the device information and a sha256 hash of the
+data from an active and inactive table are measured.
+
+The IMA measurement log has the following format for 'dm_device_remove':
+
+::
+
+ EVENT_NAME := "dm_device_remove"
+ EVENT_DATA := <dm_version_str> ";" <device_active_metadata> ";" <device_inactive_metadata> ";"
+ <active_table_hash> "," <inactive_table_hash> "," <remove_all> ";" <current_device_capacity> ";"
+
+ dm_version_str := As described in the 'Table load' section above.
+ device_active_metadata := Device metadata that reflects the currently loaded active table.
+ The format is same as 'device_metadata' described in the 'Table load' section above.
+ device_inactive_metadata := Device metadata that reflects the inactive table.
+ The format is same as 'device_metadata' described in the 'Table load' section above.
+ active_table_hash := Hash of the currently loaded active table.
+ The format is same as 'active_table_hash' described in the 'Device resume' section above.
+ inactive_table_hash := Hash of the inactive table.
+ The format is same as 'active_table_hash' described in the 'Device resume' section above.
+ remove_all := "remove_all=" <yes_no>
+ yes_no := "y" | "n"
+ current_device_capacity := "current_device_capacity=" <N>
+
+ For instance, if a linear device is removed with the following command,
+ #dmsetup remove l1
+
+ then IMA ASCII measurement log will have the following entry:
+ (converted from ASCII to text for readability)
+
+ 10 790e830a3a7a31590824ac0642b3b31c2d0e8b38 ima-buf sha256:ab9f3c959367a8f5d4403d6ce9c3627dadfa8f9f0e7ec7899299782388de3840
+ dm_device_remove
+ dm_version=4.45.0;
+ device_active_metadata=name=l1,uuid=,major=253,minor=2,minor_count=1,num_targets=2;
+ device_inactive_metadata=name=l1,uuid=,major=253,minor=2,minor_count=1,num_targets=1;
+ active_table_hash=sha256:4a7e62efaebfc86af755831998b7db6f59b60d23c9534fb16a4455907957953a,
+ inactive_table_hash=sha256:9d79c175bc2302d55a183e8f50ad4bafd60f7692fd6249e5fd213e2464384b86,remove_all=n;
+ current_device_capacity=2048;
+
+4. Table clear:
+----------------
+When an inactive table is cleared from the device, the device information and a sha256 hash of the
+data from an inactive table are measured.
+
+The IMA measurement log has the following format for 'dm_table_clear':
+
+::
+
+ EVENT_NAME := "dm_table_clear"
+ EVENT_DATA := <dm_version_str> ";" <device_inactive_metadata> ";" <inactive_table_hash> ";" <current_device_capacity> ";"
+
+ dm_version_str := As described in the 'Table load' section above.
+ device_inactive_metadata := Device metadata that was captured during the load time inactive table being cleared.
+ The format is same as 'device_metadata' described in the 'Table load' section above.
+ inactive_table_hash := Hash of the inactive table being cleared from the device.
+ The format is same as 'active_table_hash' described in the 'Device resume' section above.
+ current_device_capacity := "current_device_capacity=" <N>
+
+ For instance, if a linear device's inactive table is cleared,
+ #dmsetup clear l1
+
+ then IMA ASCII measurement log will have an entry with:
+ (converted from ASCII to text for readability)
+
+ 10 77d347408f557f68f0041acb0072946bb2367fe5 ima-buf sha256:42f9ca22163fdfa548e6229dece2959bc5ce295c681644240035827ada0e1db5
+ dm_table_clear
+ dm_version=4.45.0;
+ name=l1,uuid=,major=253,minor=2,minor_count=1,num_targets=1;
+ inactive_table_hash=sha256:75c0dc347063bf474d28a9907037eba060bfe39d8847fc0646d75e149045d545;current_device_capacity=1024;
+
+5. Device rename:
+------------------
+When an device's NAME or UUID is changed, the device information and the new NAME and UUID
+are measured.
+
+The IMA measurement log has the following format for 'dm_device_rename':
+
+::
+
+ EVENT_NAME := "dm_device_rename"
+ EVENT_DATA := <dm_version_str> ";" <device_active_metadata> ";" <new_device_name> "," <new_device_uuid> ";" <current_device_capacity> ";"
+
+ dm_version_str := As described in the 'Table load' section above.
+ device_active_metadata := Device metadata that reflects the currently loaded active table.
+ The format is same as 'device_metadata' described in the 'Table load' section above.
+ new_device_name := "new_name=" <dm-device-name>
+ dm-device-name := Same as <dm-device-name> described in 'Table load' section above
+ new_device_uuid := "new_uuid=" <dm-device-uuid>
+ dm-device-uuid := Same as <dm-device-uuid> described in 'Table load' section above
+ current_device_capacity := "current_device_capacity=" <N>
+
+ E.g 1: if a linear device's name is changed with the following command,
+ #dmsetup rename linear1 --setuuid 1234-5678
+
+ then IMA ASCII measurement log will have an entry with:
+ (converted from ASCII to text for readability)
+
+ 10 8b0423209b4c66ac1523f4c9848c9b51ee332f48 ima-buf sha256:6847b7258134189531db593e9230b257c84f04038b5a18fd2e1473860e0569ac
+ dm_device_rename
+ dm_version=4.45.0;
+ name=linear1,uuid=,major=253,minor=2,minor_count=1,num_targets=1;new_name=linear1,new_uuid=1234-5678;
+ current_device_capacity=1024;
+
+ E.g 2: if a linear device's name is changed with the following command,
+ # dmsetup rename linear1 linear=2
+
+ then IMA ASCII measurement log will have an entry with:
+ (converted from ASCII to text for readability)
+
+ 10 bef70476b99c2bdf7136fae033aa8627da1bf76f ima-buf sha256:8c6f9f53b9ef9dc8f92a2f2cca8910e622543d0f0d37d484870cb16b95111402
+ dm_device_rename
+ dm_version=4.45.0;
+ name=linear1,uuid=1234-5678,major=253,minor=2,minor_count=1,num_targets=1;
+ new_name=linear\=2,new_uuid=1234-5678;
+ current_device_capacity=1024;
+
+Supported targets:
+==================
+
+Following targets are supported to measure their data using IMA:
+
+ 1. cache
+ #. crypt
+ #. integrity
+ #. linear
+ #. mirror
+ #. multipath
+ #. raid
+ #. snapshot
+ #. striped
+ #. verity
+
+1. cache
+---------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'cache' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <metadata_mode> "," <cache_metadata_device> ","
+ <cache_device> "," <cache_origin_device> "," <writethrough> "," <writeback> ","
+ <passthrough> "," <no_discard_passdown> ";"
+
+ target_name := "target_name=cache"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ metadata_mode := "metadata_mode=" <cache_metadata_mode>
+ cache_metadata_mode := "fail" | "ro" | "rw"
+ cache_device := "cache_device=" <cache_device_name_string>
+ cache_origin_device := "cache_origin_device=" <cache_origin_device_string>
+ writethrough := "writethrough=" <yes_no>
+ writeback := "writeback=" <yes_no>
+ passthrough := "passthrough=" <yes_no>
+ no_discard_passdown := "no_discard_passdown=" <yes_no>
+ yes_no := "y" | "n"
+
+ E.g.
+ When a 'cache' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'cache' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;name=cache1,uuid=cache_uuid,major=253,minor=2,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=28672,target_name=cache,target_version=2.2.0,metadata_mode=rw,
+ cache_metadata_device=253:4,cache_device=253:3,cache_origin_device=253:5,writethrough=y,writeback=n,
+ passthrough=n,metadata2=y,no_discard_passdown=n;
+
+
+2. crypt
+---------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'crypt' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <allow_discards> "," <same_cpu_crypt> ","
+ <submit_from_crypt_cpus> "," <no_read_workqueue> "," <no_write_workqueue> ","
+ <iv_large_sectors> "," <iv_large_sectors> "," [<integrity_tag_size> ","] [<cipher_auth> ","]
+ [<sector_size> ","] [<cipher_string> ","] <key_size> "," <key_parts> ","
+ <key_extra_size> "," <key_mac_size> ";"
+
+ target_name := "target_name=crypt"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ allow_discards := "allow_discards=" <yes_no>
+ same_cpu_crypt := "same_cpu_crypt=" <yes_no>
+ submit_from_crypt_cpus := "submit_from_crypt_cpus=" <yes_no>
+ no_read_workqueue := "no_read_workqueue=" <yes_no>
+ no_write_workqueue := "no_write_workqueue=" <yes_no>
+ iv_large_sectors := "iv_large_sectors=" <yes_no>
+ integrity_tag_size := "integrity_tag_size=" <N>
+ cipher_auth := "cipher_auth=" <string>
+ sector_size := "sector_size=" <N>
+ cipher_string := "cipher_string="
+ key_size := "key_size=" <N>
+ key_parts := "key_parts=" <N>
+ key_extra_size := "key_extra_size=" <N>
+ key_mac_size := "key_mac_size=" <N>
+ yes_no := "y" | "n"
+
+ E.g.
+ When a 'crypt' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'crypt' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=crypt1,uuid=crypt_uuid1,major=253,minor=0,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=1953125,target_name=crypt,target_version=1.23.0,
+ allow_discards=y,same_cpu=n,submit_from_crypt_cpus=n,no_read_workqueue=n,no_write_workqueue=n,
+ iv_large_sectors=n,cipher_string=aes-xts-plain64,key_size=32,key_parts=1,key_extra_size=0,key_mac_size=0;
+
+3. integrity
+-------------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'integrity' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <dev_name> "," <start>
+ <tag_size> "," <mode> "," [<meta_device> ","] [<block_size> ","] <recalculate> ","
+ <allow_discards> "," <fix_padding> "," <fix_hmac> "," <legacy_recalculate> ","
+ <journal_sectors> "," <interleave_sectors> "," <buffer_sectors> ";"
+
+ target_name := "target_name=integrity"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ dev_name := "dev_name=" <device_name_str>
+ start := "start=" <N>
+ tag_size := "tag_size=" <N>
+ mode := "mode=" <integrity_mode_str>
+ integrity_mode_str := "J" | "B" | "D" | "R"
+ meta_device := "meta_device=" <meta_device_str>
+ block_size := "block_size=" <N>
+ recalculate := "recalculate=" <yes_no>
+ allow_discards := "allow_discards=" <yes_no>
+ fix_padding := "fix_padding=" <yes_no>
+ fix_hmac := "fix_hmac=" <yes_no>
+ legacy_recalculate := "legacy_recalculate=" <yes_no>
+ journal_sectors := "journal_sectors=" <N>
+ interleave_sectors := "interleave_sectors=" <N>
+ buffer_sectors := "buffer_sectors=" <N>
+ yes_no := "y" | "n"
+
+ E.g.
+ When a 'integrity' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'integrity' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=integrity1,uuid=,major=253,minor=1,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=7856,target_name=integrity,target_version=1.10.0,
+ dev_name=253:0,start=0,tag_size=32,mode=J,recalculate=n,allow_discards=n,fix_padding=n,
+ fix_hmac=n,legacy_recalculate=n,journal_sectors=88,interleave_sectors=32768,buffer_sectors=128;
+
+
+4. linear
+----------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'linear' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <device_name> <,> <start> ";"
+
+ target_name := "target_name=linear"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ device_name := "device_name=" <linear_device_name_str>
+ start := "start=" <N>
+
+ E.g.
+ When a 'linear' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'linear' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=linear1,uuid=linear_uuid1,major=253,minor=2,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=28672,target_name=linear,target_version=1.4.0,
+ device_name=253:1,start=2048;
+
+5. mirror
+----------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'mirror' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <nr_mirrors> ","
+ <mirror_device_data> "," <handle_errors> "," <keep_log> "," <log_type_status> ";"
+
+ target_name := "target_name=mirror"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ nr_mirrors := "nr_mirrors=" <NR>
+ mirror_device_data := <mirror_device_row> | <mirror_device_data><mirror_device_row>
+ mirror_device_row is repeated <NR> times - for <NR> described in <nr_mirrors>.
+ mirror_device_row := <mirror_device_name> "," <mirror_device_status>
+ mirror_device_name := "mirror_device_" <X> "=" <mirror_device_name_str>
+ where <X> ranges from 0 to (<NR> -1) - for <NR> described in <nr_mirrors>.
+ mirror_device_status := "mirror_device_" <X> "_status=" <mirror_device_status_char>
+ where <X> ranges from 0 to (<NR> -1) - for <NR> described in <nr_mirrors>.
+ mirror_device_status_char := "A" | "F" | "D" | "S" | "R" | "U"
+ handle_errors := "handle_errors=" <yes_no>
+ keep_log := "keep_log=" <yes_no>
+ log_type_status := "log_type_status=" <log_type_status_str>
+ yes_no := "y" | "n"
+
+ E.g.
+ When a 'mirror' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'mirror' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=mirror1,uuid=mirror_uuid1,major=253,minor=6,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=2048,target_name=mirror,target_version=1.14.0,nr_mirrors=2,
+ mirror_device_0=253:4,mirror_device_0_status=A,
+ mirror_device_1=253:5,mirror_device_1_status=A,
+ handle_errors=y,keep_log=n,log_type_status=;
+
+6. multipath
+-------------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'multipath' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <nr_priority_groups>
+ ["," <pg_state> "," <priority_groups> "," <priority_group_paths>] ";"
+
+ target_name := "target_name=multipath"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ nr_priority_groups := "nr_priority_groups=" <NPG>
+ priority_groups := <priority_groups_row>|<priority_groups_row><priority_groups>
+ priority_groups_row := "pg_state_" <X> "=" <pg_state_str> "," "nr_pgpaths_" <X> "=" <NPGP> ","
+ "path_selector_name_" <X> "=" <string> "," <priority_group_paths>
+ where <X> ranges from 0 to (<NPG> -1) - for <NPG> described in <nr_priority_groups>.
+ pg_state_str := "E" | "A" | "D"
+ <priority_group_paths> := <priority_group_paths_row> | <priority_group_paths_row><priority_group_paths>
+ priority_group_paths_row := "path_name_" <X> "_" <Y> "=" <string> "," "is_active_" <X> "_" <Y> "=" <is_active_str>
+ "fail_count_" <X> "_" <Y> "=" <N> "," "path_selector_status_" <X> "_" <Y> "=" <path_selector_status_str>
+ where <X> ranges from 0 to (<NPG> -1) - for <NPG> described in <nr_priority_groups>,
+ and <Y> ranges from 0 to (<NPGP> -1) - for <NPGP> described in <priority_groups_row>.
+ is_active_str := "A" | "F"
+
+ E.g.
+ When a 'multipath' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'multipath' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=mp,uuid=,major=253,minor=0,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=2097152,target_name=multipath,target_version=1.14.0,nr_priority_groups=2,
+ pg_state_0=E,nr_pgpaths_0=2,path_selector_name_0=queue-length,
+ path_name_0_0=8:16,is_active_0_0=A,fail_count_0_0=0,path_selector_status_0_0=,
+ path_name_0_1=8:32,is_active_0_1=A,fail_count_0_1=0,path_selector_status_0_1=,
+ pg_state_1=E,nr_pgpaths_1=2,path_selector_name_1=queue-length,
+ path_name_1_0=8:48,is_active_1_0=A,fail_count_1_0=0,path_selector_status_1_0=,
+ path_name_1_1=8:64,is_active_1_1=A,fail_count_1_1=0,path_selector_status_1_1=;
+
+7. raid
+--------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'raid' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <raid_type> "," <raid_disks> "," <raid_state>
+ <raid_device_status> ["," journal_dev_mode] ";"
+
+ target_name := "target_name=raid"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ raid_type := "raid_type=" <raid_type_str>
+ raid_disks := "raid_disks=" <NRD>
+ raid_state := "raid_state=" <raid_state_str>
+ raid_state_str := "frozen" | "reshape" |"resync" | "check" | "repair" | "recover" | "idle" |"undef"
+ raid_device_status := <raid_device_status_row> | <raid_device_status_row><raid_device_status>
+ <raid_device_status_row> is repeated <NRD> times - for <NRD> described in <raid_disks>.
+ raid_device_status_row := "raid_device_" <X> "_status=" <raid_device_status_str>
+ where <X> ranges from 0 to (<NRD> -1) - for <NRD> described in <raid_disks>.
+ raid_device_status_str := "A" | "D" | "a" | "-"
+ journal_dev_mode := "journal_dev_mode=" <journal_dev_mode_str>
+ journal_dev_mode_str := "writethrough" | "writeback" | "invalid"
+
+ E.g.
+ When a 'raid' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'raid' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=raid_LV1,uuid=uuid_raid_LV1,major=253,minor=12,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=2048,target_name=raid,target_version=1.15.1,
+ raid_type=raid10,raid_disks=4,raid_state=idle,
+ raid_device_0_status=A,
+ raid_device_1_status=A,
+ raid_device_2_status=A,
+ raid_device_3_status=A;
+
+
+8. snapshot
+------------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'snapshot' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <snap_origin_name> ","
+ <snap_cow_name> "," <snap_valid> "," <snap_merge_failed> "," <snapshot_overflowed> ";"
+
+ target_name := "target_name=snapshot"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ snap_origin_name := "snap_origin_name=" <string>
+ snap_cow_name := "snap_cow_name=" <string>
+ snap_valid := "snap_valid=" <yes_no>
+ snap_merge_failed := "snap_merge_failed=" <yes_no>
+ snapshot_overflowed := "snapshot_overflowed=" <yes_no>
+ yes_no := "y" | "n"
+
+ E.g.
+ When a 'snapshot' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'snapshot' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=snap1,uuid=snap_uuid1,major=253,minor=13,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=4096,target_name=snapshot,target_version=1.16.0,
+ snap_origin_name=253:11,snap_cow_name=253:12,snap_valid=y,snap_merge_failed=n,snapshot_overflowed=n;
+
+9. striped
+-----------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'striped' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <stripes> "," <chunk_size> ","
+ <stripe_data> ";"
+
+ target_name := "target_name=striped"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ stripes := "stripes=" <NS>
+ chunk_size := "chunk_size=" <N>
+ stripe_data := <stripe_data_row>|<stripe_data><stripe_data_row>
+ stripe_data_row := <stripe_device_name> "," <stripe_physical_start> "," <stripe_status>
+ stripe_device_name := "stripe_" <X> "_device_name=" <stripe_device_name_str>
+ where <X> ranges from 0 to (<NS> -1) - for <NS> described in <stripes>.
+ stripe_physical_start := "stripe_" <X> "_physical_start=" <N>
+ where <X> ranges from 0 to (<NS> -1) - for <NS> described in <stripes>.
+ stripe_status := "stripe_" <X> "_status=" <stripe_status_str>
+ where <X> ranges from 0 to (<NS> -1) - for <NS> described in <stripes>.
+ stripe_status_str := "D" | "A"
+
+ E.g.
+ When a 'striped' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'striped' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=striped1,uuid=striped_uuid1,major=253,minor=5,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=640,target_name=striped,target_version=1.6.0,stripes=2,chunk_size=64,
+ stripe_0_device_name=253:0,stripe_0_physical_start=2048,stripe_0_status=A,
+ stripe_1_device_name=253:3,stripe_1_physical_start=2048,stripe_1_status=A;
+
+10. verity
+----------
+The 'target_attributes' (described as part of EVENT_DATA in 'Table load'
+section above) has the following data format for 'verity' target.
+
+::
+
+ target_attributes := <target_name> "," <target_version> "," <hash_failed> "," <verity_version> ","
+ <data_device_name> "," <hash_device_name> "," <verity_algorithm> "," <root_digest> ","
+ <salt> "," <ignore_zero_blocks> "," <check_at_most_once> ["," <root_hash_sig_key_desc>]
+ ["," <verity_mode>] ";"
+
+ target_name := "target_name=verity"
+ target_version := "target_version=" <N> "." <N> "." <N>
+ hash_failed := "hash_failed=" <hash_failed_str>
+ hash_failed_str := "C" | "V"
+ verity_version := "verity_version=" <verity_version_str>
+ data_device_name := "data_device_name=" <data_device_name_str>
+ hash_device_name := "hash_device_name=" <hash_device_name_str>
+ verity_algorithm := "verity_algorithm=" <verity_algorithm_str>
+ root_digest := "root_digest=" <root_digest_str>
+ salt := "salt=" <salt_str>
+ salt_str := "-" <verity_salt_str>
+ ignore_zero_blocks := "ignore_zero_blocks=" <yes_no>
+ check_at_most_once := "check_at_most_once=" <yes_no>
+ root_hash_sig_key_desc := "root_hash_sig_key_desc="
+ verity_mode := "verity_mode=" <verity_mode_str>
+ verity_mode_str := "ignore_corruption" | "restart_on_corruption" | "panic_on_corruption" | "invalid"
+ yes_no := "y" | "n"
+
+ E.g.
+ When a 'verity' target is loaded, then IMA ASCII measurement log will have an entry
+ similar to the following, depicting what 'verity' attributes are measured in EVENT_DATA
+ for 'dm_table_load' event.
+ (converted from ASCII to text for readability)
+
+ dm_version=4.45.0;
+ name=test-verity,uuid=,major=253,minor=2,minor_count=1,num_targets=1;
+ target_index=0,target_begin=0,target_len=1953120,target_name=verity,target_version=1.8.0,hash_failed=V,
+ verity_version=1,data_device_name=253:1,hash_device_name=253:0,verity_algorithm=sha256,
+ root_digest=29cb87e60ce7b12b443ba6008266f3e41e93e403d7f298f8e3f316b29ff89c5e,
+ salt=e48da609055204e89ae53b655ca2216dd983cf3cb829f34f63a297d106d53e2d,
+ ignore_zero_blocks=n,check_at_most_once=n;
diff --git a/Documentation/admin-guide/device-mapper/dm-init.rst b/Documentation/admin-guide/device-mapper/dm-init.rst
new file mode 100644
index 000000000000..981d6a907699
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-init.rst
@@ -0,0 +1,133 @@
+================================
+Early creation of mapped devices
+================================
+
+It is possible to configure a device-mapper device to act as the root device for
+your system in two ways.
+
+The first is to build an initial ramdisk which boots to a minimal userspace
+which configures the device, then pivot_root(8) in to it.
+
+The second is to create one or more device-mappers using the module parameter
+"dm-mod.create=" through the kernel boot command line argument.
+
+The format is specified as a string of data separated by commas and optionally
+semi-colons, where:
+
+ - a comma is used to separate fields like name, uuid, flags and table
+ (specifies one device)
+ - a semi-colon is used to separate devices.
+
+So the format will look like this::
+
+ dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+]
+
+Where::
+
+ <name> ::= The device name.
+ <uuid> ::= xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | ""
+ <minor> ::= The device minor number | ""
+ <flags> ::= "ro" | "rw"
+ <table> ::= <start_sector> <num_sectors> <target_type> <target_args>
+ <target_type> ::= "verity" | "linear" | ... (see list below)
+
+The dm line should be equivalent to the one used by the dmsetup tool with the
+`--concise` argument.
+
+Target types
+============
+
+Not all target types are available as there are serious risks in allowing
+activation of certain DM targets without first using userspace tools to check
+the validity of associated metadata.
+
+======================= =======================================================
+`cache` constrained, userspace should verify cache device
+`crypt` allowed
+`delay` allowed
+`era` constrained, userspace should verify metadata device
+`flakey` constrained, meant for test
+`linear` allowed
+`log-writes` constrained, userspace should verify metadata device
+`mirror` constrained, userspace should verify main/mirror device
+`raid` constrained, userspace should verify metadata device
+`snapshot` constrained, userspace should verify src/dst device
+`snapshot-origin` allowed
+`snapshot-merge` constrained, userspace should verify src/dst device
+`striped` allowed
+`switch` constrained, userspace should verify dev path
+`thin` constrained, requires dm target message from userspace
+`thin-pool` constrained, requires dm target message from userspace
+`verity` allowed
+`writecache` constrained, userspace should verify cache device
+`zero` constrained, not meant for rootfs
+======================= =======================================================
+
+If the target is not listed above, it is constrained by default (not tested).
+
+Examples
+========
+An example of booting to a linear array made up of user-mode linux block
+devices::
+
+ dm-mod.create="lroot,,,rw, 0 4096 linear 98:16 0, 4096 4096 linear 98:32 0" root=/dev/dm-0
+
+This will boot to a rw dm-linear target of 8192 sectors split across two block
+devices identified by their major:minor numbers. After boot, udev will rename
+this target to /dev/mapper/lroot (depending on the rules). No uuid was assigned.
+
+An example of multiple device-mappers, with the dm-mod.create="..." contents
+is shown here split on multiple lines for readability::
+
+ dm-linear,,1,rw,
+ 0 32768 linear 8:1 0,
+ 32768 1024000 linear 8:2 0;
+ dm-verity,,3,ro,
+ 0 1638400 verity 1 /dev/sdc1 /dev/sdc2 4096 4096 204800 1 sha256
+ ac87db56303c9c1da433d7209b5a6ef3e4779df141200cbd7c157dcb8dd89c42
+ 5ebfe87f7df3235b80a117ebc4078e44f55045487ad4a96581d1adb564615b51
+
+Other examples (per target):
+
+"crypt"::
+
+ dm-crypt,,8,ro,
+ 0 1048576 crypt aes-xts-plain64
+ babebabebabebabebabebabebabebabebabebabebabebabebabebabebabebabe 0
+ /dev/sda 0 1 allow_discards
+
+"delay"::
+
+ dm-delay,,4,ro,0 409600 delay /dev/sda1 0 500
+
+"linear"::
+
+ dm-linear,,,rw,
+ 0 32768 linear /dev/sda1 0,
+ 32768 1024000 linear /dev/sda2 0,
+ 1056768 204800 linear /dev/sda3 0,
+ 1261568 512000 linear /dev/sda4 0
+
+"snapshot-origin"::
+
+ dm-snap-orig,,4,ro,0 409600 snapshot-origin 8:2
+
+"striped"::
+
+ dm-striped,,4,ro,0 1638400 striped 4 4096
+ /dev/sda1 0 /dev/sda2 0 /dev/sda3 0 /dev/sda4 0
+
+"verity"::
+
+ dm-verity,,4,ro,
+ 0 1638400 verity 1 8:1 8:2 4096 4096 204800 1 sha256
+ fb1a5a0f00deb908d8b53cb270858975e76cf64105d412ce764225d53b8f3cfd
+ 51934789604d1b92399c52e7cb149d1b3a1b74bbbcb103b2a0aaacbed5c08584
+
+For setups using device-mapper on top of asynchronously probed block
+devices (MMC, USB, ..), it may be necessary to tell dm-init to
+explicitly wait for them to become available before setting up the
+device-mapper tables. This can be done with the "dm-mod.waitfor="
+module parameter, which takes a list of devices to wait for::
+
+ dm-mod.waitfor=<device1>[,..,<deviceN>]
diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst
new file mode 100644
index 000000000000..c2e18ecc065c
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst
@@ -0,0 +1,308 @@
+============
+dm-integrity
+============
+
+The dm-integrity target emulates a block device that has additional
+per-sector tags that can be used for storing integrity information.
+
+A general problem with storing integrity tags with every sector is that
+writing the sector and the integrity tag must be atomic - i.e. in case of
+crash, either both sector and integrity tag or none of them is written.
+
+To guarantee write atomicity, the dm-integrity target uses journal, it
+writes sector data and integrity tags into a journal, commits the journal
+and then copies the data and integrity tags to their respective location.
+
+The dm-integrity target can be used with the dm-crypt target - in this
+situation the dm-crypt target creates the integrity data and passes them
+to the dm-integrity target via bio_integrity_payload attached to the bio.
+In this mode, the dm-crypt and dm-integrity targets provide authenticated
+disk encryption - if the attacker modifies the encrypted device, an I/O
+error is returned instead of random data.
+
+The dm-integrity target can also be used as a standalone target, in this
+mode it calculates and verifies the integrity tag internally. In this
+mode, the dm-integrity target can be used to detect silent data
+corruption on the disk or in the I/O path.
+
+There's an alternate mode of operation where dm-integrity uses a bitmap
+instead of a journal. If a bit in the bitmap is 1, the corresponding
+region's data and integrity tags are not synchronized - if the machine
+crashes, the unsynchronized regions will be recalculated. The bitmap mode
+is faster than the journal mode, because we don't have to write the data
+twice, but it is also less reliable, because if data corruption happens
+when the machine crashes, it may not be detected.
+
+When loading the target for the first time, the kernel driver will format
+the device. But it will only format the device if the superblock contains
+zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
+target can't be loaded.
+
+Accesses to the on-disk metadata area containing checksums (aka tags) are
+buffered using dm-bufio. When an access to any given metadata area
+occurs, each unique metadata area gets its own buffer(s). The buffer size
+is capped at the size of the metadata area, but may be smaller, thereby
+requiring multiple buffers to represent the full metadata area. A smaller
+buffer size will produce a smaller resulting read/write operation to the
+metadata area for small reads/writes. The metadata is still read even in
+a full write to the data covered by a single buffer.
+
+To use the target for the first time:
+
+1. overwrite the superblock with zeroes
+2. load the dm-integrity target with one-sector size, the kernel driver
+ will format the device
+3. unload the dm-integrity target
+4. read the "provided_data_sectors" value from the superblock
+5. load the dm-integrity target with the target size
+ "provided_data_sectors"
+6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target
+ with the size "provided_data_sectors"
+
+
+Target arguments:
+
+1. the underlying block device
+
+2. the number of reserved sector at the beginning of the device - the
+ dm-integrity won't read of write these sectors
+
+3. the size of the integrity tag (if "-" is used, the size is taken from
+ the internal-hash algorithm)
+
+4. mode:
+
+ D - direct writes (without journal)
+ in this mode, journaling is
+ not used and data sectors and integrity tags are written
+ separately. In case of crash, it is possible that the data
+ and integrity tag doesn't match.
+ J - journaled writes
+ data and integrity tags are written to the
+ journal and atomicity is guaranteed. In case of crash,
+ either both data and tag or none of them are written. The
+ journaled mode degrades write throughput twice because the
+ data have to be written twice.
+ B - bitmap mode - data and metadata are written without any
+ synchronization, the driver maintains a bitmap of dirty
+ regions where data and metadata don't match. This mode can
+ only be used with internal hash.
+ R - recovery mode - in this mode, journal is not replayed,
+ checksums are not checked and writes to the device are not
+ allowed. This mode is useful for data recovery if the
+ device cannot be activated in any of the other standard
+ modes.
+ I - inline mode - in this mode, dm-integrity will store integrity
+ data directly in the underlying device sectors.
+ The underlying device must have an integrity profile that
+ allows storing user integrity data and provides enough
+ space for the selected integrity tag.
+
+5. the number of additional arguments
+
+Additional arguments:
+
+journal_sectors:number
+ The size of journal, this argument is used only if formatting the
+ device. If the device is already formatted, the value from the
+ superblock is used.
+
+interleave_sectors:number (default 32768)
+ The number of interleaved sectors. This values is rounded down to
+ a power of two. If the device is already formatted, the value from
+ the superblock is used.
+
+meta_device:device
+ Don't interleave the data and metadata on the device. Use a
+ separate device for metadata.
+
+buffer_sectors:number (default 128)
+ The number of sectors in one metadata buffer. The value is rounded
+ down to a power of two.
+
+journal_watermark:number (default 50)
+ The journal watermark in percents. When the size of the journal
+ exceeds this watermark, the thread that flushes the journal will
+ be started.
+
+commit_time:number (default 10000)
+ Commit time in milliseconds. When this time passes, the journal is
+ written. The journal is also written immediately if the FLUSH
+ request is received.
+
+internal_hash:algorithm(:key) (the key is optional)
+ Use internal hash or crc.
+ When this argument is used, the dm-integrity target won't accept
+ integrity tags from the upper target, but it will automatically
+ generate and verify the integrity tags.
+
+ You can use a crc algorithm (such as crc32), then integrity target
+ will protect the data against accidental corruption.
+ You can also use a hmac algorithm (for example
+ "hmac(sha256):0123456789abcdef"), in this mode it will provide
+ cryptographic authentication of the data without encryption.
+
+ When this argument is not used, the integrity tags are accepted
+ from an upper layer target, such as dm-crypt. The upper layer
+ target should check the validity of the integrity tags.
+
+recalculate
+ Recalculate the integrity tags automatically. It is only valid
+ when using internal hash.
+
+journal_crypt:algorithm(:key) (the key is optional)
+ Encrypt the journal using given algorithm to make sure that the
+ attacker can't read the journal. You can use a block cipher here
+ (such as "cbc(aes)") or a stream cipher (for example "chacha20"
+ or "ctr(aes)").
+
+ The journal contains history of last writes to the block device,
+ an attacker reading the journal could see the last sector numbers
+ that were written. From the sector numbers, the attacker can infer
+ the size of files that were written. To protect against this
+ situation, you can encrypt the journal.
+
+journal_mac:algorithm(:key) (the key is optional)
+ Protect sector numbers in the journal from accidental or malicious
+ modification. To protect against accidental modification, use a
+ crc algorithm, to protect against malicious modification, use a
+ hmac algorithm with a key.
+
+ This option is not needed when using internal-hash because in this
+ mode, the integrity of journal entries is checked when replaying
+ the journal. Thus, modified sector number would be detected at
+ this stage.
+
+block_size:number (default 512)
+ The size of a data block in bytes. The larger the block size the
+ less overhead there is for per-block integrity metadata.
+ Supported values are 512, 1024, 2048 and 4096 bytes.
+
+sectors_per_bit:number
+ In the bitmap mode, this parameter specifies the number of
+ 512-byte sectors that corresponds to one bitmap bit.
+
+bitmap_flush_interval:number
+ The bitmap flush interval in milliseconds. The metadata buffers
+ are synchronized when this interval expires.
+
+allow_discards
+ Allow block discard requests (a.k.a. TRIM) for the integrity device.
+ Discards are only allowed to devices using internal hash.
+
+fix_padding
+ Use a smaller padding of the tag area that is more
+ space-efficient. If this option is not present, large padding is
+ used - that is for compatibility with older kernels.
+
+fix_hmac
+ Improve security of internal_hash and journal_mac:
+
+ - the section number is mixed to the mac, so that an attacker can't
+ copy sectors from one journal section to another journal section
+ - the superblock is protected by journal_mac
+ - a 16-byte salt stored in the superblock is mixed to the mac, so
+ that the attacker can't detect that two disks have the same hmac
+ key and also to disallow the attacker to move sectors from one
+ disk to another
+
+legacy_recalculate
+ Allow recalculating of volumes with HMAC keys. This is disabled by
+ default for security reasons - an attacker could modify the volume,
+ set recalc_sector to zero, and the kernel would not detect the
+ modification.
+
+The journal mode (D/J), buffer_sectors, journal_watermark, commit_time and
+allow_discards can be changed when reloading the target (load an inactive
+table and swap the tables with suspend and resume). The other arguments
+should not be changed when reloading the target because the layout of disk
+data depend on them and the reloaded target would be non-functional.
+
+For example, on a device using the default interleave_sectors of 32768, a
+block_size of 512, and an internal_hash of crc32c with a tag size of 4
+bytes, it will take 128 KiB of tags to track a full data area, requiring
+256 sectors of metadata per data area. With the default buffer_sectors of
+128, that means there will be 2 buffers per metadata area, or 2 buffers
+per 16 MiB of data.
+
+Status line:
+
+1. the number of integrity mismatches
+2. provided data sectors - that is the number of sectors that the user
+ could use
+3. the current recalculating position (or '-' if we didn't recalculate)
+
+
+The layout of the formatted block device:
+
+* reserved sectors
+ (they are not used by this target, they can be used for
+ storing LUKS metadata or for other purpose), the size of the reserved
+ area is specified in the target arguments
+
+* superblock (4kiB)
+ * magic string - identifies that the device was formatted
+ * version
+ * log2(interleave sectors)
+ * integrity tag size
+ * the number of journal sections
+ * provided data sectors - the number of sectors that this target
+ provides (i.e. the size of the device minus the size of all
+ metadata and padding). The user of this target should not send
+ bios that access data beyond the "provided data sectors" limit.
+ * flags
+ SB_FLAG_HAVE_JOURNAL_MAC
+ - a flag is set if journal_mac is used
+ SB_FLAG_RECALCULATING
+ - recalculating is in progress
+ SB_FLAG_DIRTY_BITMAP
+ - journal area contains the bitmap of dirty
+ blocks
+ * log2(sectors per block)
+ * a position where recalculating finished
+* journal
+ The journal is divided into sections, each section contains:
+
+ * metadata area (4kiB), it contains journal entries
+
+ - every journal entry contains:
+
+ * logical sector (specifies where the data and tag should
+ be written)
+ * last 8 bytes of data
+ * integrity tag (the size is specified in the superblock)
+
+ - every metadata sector ends with
+
+ * mac (8-bytes), all the macs in 8 metadata sectors form a
+ 64-byte value. It is used to store hmac of sector
+ numbers in the journal section, to protect against a
+ possibility that the attacker tampers with sector
+ numbers in the journal.
+ * commit id
+
+ * data area (the size is variable; it depends on how many journal
+ entries fit into the metadata area)
+
+ - every sector in the data area contains:
+
+ * data (504 bytes of data, the last 8 bytes are stored in
+ the journal entry)
+ * commit id
+
+ To test if the whole journal section was written correctly, every
+ 512-byte sector of the journal ends with 8-byte commit id. If the
+ commit id matches on all sectors in a journal section, then it is
+ assumed that the section was written correctly. If the commit id
+ doesn't match, the section was written partially and it should not
+ be replayed.
+
+* one or more runs of interleaved tags and data.
+ Each run contains:
+
+ * tag area - it contains integrity tags. There is one tag for each
+ sector in the data area. The size of this area is always 4KiB or
+ greater.
+ * data area - it contains data sectors. The number of data sectors
+ in one run must be a power of two. log2 of this value is stored
+ in the superblock.
diff --git a/Documentation/admin-guide/device-mapper/dm-io.rst b/Documentation/admin-guide/device-mapper/dm-io.rst
new file mode 100644
index 000000000000..d2492917a1f5
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-io.rst
@@ -0,0 +1,75 @@
+=====
+dm-io
+=====
+
+Dm-io provides synchronous and asynchronous I/O services. There are three
+types of I/O services available, and each type has a sync and an async
+version.
+
+The user must set up an io_region structure to describe the desired location
+of the I/O. Each io_region indicates a block-device along with the starting
+sector and size of the region::
+
+ struct io_region {
+ struct block_device *bdev;
+ sector_t sector;
+ sector_t count;
+ };
+
+Dm-io can read from one io_region or write to one or more io_regions. Writes
+to multiple regions are specified by an array of io_region structures.
+
+The first I/O service type takes a list of memory pages as the data buffer for
+the I/O, along with an offset into the first page::
+
+ struct page_list {
+ struct page_list *next;
+ struct page *page;
+ };
+
+ int dm_io_sync(unsigned int num_regions, struct io_region *where, int rw,
+ struct page_list *pl, unsigned int offset,
+ unsigned long *error_bits);
+ int dm_io_async(unsigned int num_regions, struct io_region *where, int rw,
+ struct page_list *pl, unsigned int offset,
+ io_notify_fn fn, void *context);
+
+The second I/O service type takes an array of bio vectors as the data buffer
+for the I/O. This service can be handy if the caller has a pre-assembled bio,
+but wants to direct different portions of the bio to different devices::
+
+ int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where,
+ int rw, struct bio_vec *bvec,
+ unsigned long *error_bits);
+ int dm_io_async_bvec(unsigned int num_regions, struct io_region *where,
+ int rw, struct bio_vec *bvec,
+ io_notify_fn fn, void *context);
+
+The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
+data buffer for the I/O. This service can be handy if the caller needs to do
+I/O to a large region but doesn't want to allocate a large number of individual
+memory pages::
+
+ int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw,
+ void *data, unsigned long *error_bits);
+ int dm_io_async_vm(unsigned int num_regions, struct io_region *where, int rw,
+ void *data, io_notify_fn fn, void *context);
+
+Callers of the asynchronous I/O services must include the name of a completion
+callback routine and a pointer to some context data for the I/O::
+
+ typedef void (*io_notify_fn)(unsigned long error, void *context);
+
+The "error" parameter in this callback, as well as the `*error` parameter in
+all of the synchronous versions, is a bitset (instead of a simple error value).
+In the case of an write-I/O to multiple regions, this bitset allows dm-io to
+indicate success or failure on each individual region.
+
+Before using any of the dm-io services, the user should call dm_io_get()
+and specify the number of pages they expect to perform I/O on concurrently.
+Dm-io will attempt to resize its mempool to make sure enough pages are
+always available in order to avoid unnecessary waiting while performing I/O.
+
+When the user is finished using the dm-io services, they should call
+dm_io_put() and specify the same number of pages that were given on the
+dm_io_get() call.
diff --git a/Documentation/admin-guide/device-mapper/dm-log.rst b/Documentation/admin-guide/device-mapper/dm-log.rst
new file mode 100644
index 000000000000..ba4fce39bc27
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-log.rst
@@ -0,0 +1,57 @@
+=====================
+Device-Mapper Logging
+=====================
+The device-mapper logging code is used by some of the device-mapper
+RAID targets to track regions of the disk that are not consistent.
+A region (or portion of the address space) of the disk may be
+inconsistent because a RAID stripe is currently being operated on or
+a machine died while the region was being altered. In the case of
+mirrors, a region would be considered dirty/inconsistent while you
+are writing to it because the writes need to be replicated for all
+the legs of the mirror and may not reach the legs at the same time.
+Once all writes are complete, the region is considered clean again.
+
+There is a generic logging interface that the device-mapper RAID
+implementations use to perform logging operations (see
+dm_dirty_log_type in include/linux/dm-dirty-log.h). Various different
+logging implementations are available and provide different
+capabilities. The list includes:
+
+============== ==============================================================
+Type Files
+============== ==============================================================
+disk drivers/md/dm-log.c
+core drivers/md/dm-log.c
+userspace drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h
+============== ==============================================================
+
+The "disk" log type
+-------------------
+This log implementation commits the log state to disk. This way, the
+logging state survives reboots/crashes.
+
+The "core" log type
+-------------------
+This log implementation keeps the log state in memory. The log state
+will not survive a reboot or crash, but there may be a small boost in
+performance. This method can also be used if no storage device is
+available for storing log state.
+
+The "userspace" log type
+------------------------
+This log type simply provides a way to export the log API to userspace,
+so log implementations can be done there. This is done by forwarding most
+logging requests to userspace, where a daemon receives and processes the
+request.
+
+The structure used for communication between kernel and userspace are
+located in include/linux/dm-log-userspace.h. Due to the frequency,
+diversity, and 2-way communication nature of the exchanges between
+kernel and userspace, 'connector' is used as the interface for
+communication.
+
+There are currently two userspace log implementations that leverage this
+framework - "clustered-disk" and "clustered-core". These implementations
+provide a cluster-coherent log for shared-storage. Device-mapper mirroring
+can be used in a shared-storage environment when the cluster log implementations
+are employed.
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/dm-queue-length.rst b/Documentation/admin-guide/device-mapper/dm-queue-length.rst
new file mode 100644
index 000000000000..d8e381c1cb02
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-queue-length.rst
@@ -0,0 +1,48 @@
+===============
+dm-queue-length
+===============
+
+dm-queue-length is a path selector module for device-mapper targets,
+which selects a path with the least number of in-flight I/Os.
+The path selector name is 'queue-length'.
+
+Table parameters for each path: [<repeat_count>]
+
+::
+
+ <repeat_count>: The number of I/Os to dispatch using the selected
+ path before switching to the next path.
+ If not given, internal default is used. To check
+ the default value, see the activated table.
+
+Status for each path: <status> <fail-count> <in-flight>
+
+::
+
+ <status>: 'A' if the path is active, 'F' if the path is failed.
+ <fail-count>: The number of path failures.
+ <in-flight>: The number of in-flight I/Os on the path.
+
+
+Algorithm
+=========
+
+dm-queue-length increments/decrements 'in-flight' when an I/O is
+dispatched/completed respectively.
+dm-queue-length selects a path with the minimum 'in-flight'.
+
+
+Examples
+========
+In case that 2 paths (sda and sdb) are used with repeat_count == 128.
+
+::
+
+ # echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \
+ dmsetup create test
+ #
+ # dmsetup table
+ test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128
+ #
+ # dmsetup status
+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
diff --git a/Documentation/admin-guide/device-mapper/dm-raid.rst b/Documentation/admin-guide/device-mapper/dm-raid.rst
new file mode 100644
index 000000000000..bb17e26e3c1b
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-raid.rst
@@ -0,0 +1,423 @@
+=======
+dm-raid
+=======
+
+The device-mapper RAID (dm-raid) target provides a bridge from DM to MD.
+It allows the MD RAID drivers to be accessed using a device-mapper
+interface.
+
+
+Mapping Table Interface
+-----------------------
+The target is named "raid" and it accepts the following parameters::
+
+ <raid_type> <#raid_params> <raid_params> \
+ <#raid_devs> <metadata_dev0> <dev0> [.. <metadata_devN> <devN>]
+
+<raid_type>:
+
+ ============= ===============================================================
+ raid0 RAID0 striping (no resilience)
+ raid1 RAID1 mirroring
+ raid4 RAID4 with dedicated last parity disk
+ raid5_n RAID5 with dedicated last parity disk supporting takeover
+ Same as raid4
+
+ - Transitory layout
+ raid5_la RAID5 left asymmetric
+
+ - rotating parity 0 with data continuation
+ raid5_ra RAID5 right asymmetric
+
+ - rotating parity N with data continuation
+ raid5_ls RAID5 left symmetric
+
+ - rotating parity 0 with data restart
+ raid5_rs RAID5 right symmetric
+
+ - rotating parity N with data restart
+ raid6_zr RAID6 zero restart
+
+ - rotating parity zero (left-to-right) with data restart
+ raid6_nr RAID6 N restart
+
+ - rotating parity N (right-to-left) with data restart
+ raid6_nc RAID6 N continue
+
+ - rotating parity N (right-to-left) with data continuation
+ raid6_n_6 RAID6 with dedicate parity disks
+
+ - parity and Q-syndrome on the last 2 disks;
+ layout for takeover from/to raid4/raid5_n
+ raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk
+
+ - layout for takeover from raid5_la from/to raid6
+ raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk
+
+ - layout for takeover from raid5_ra from/to raid6
+ raid6_ls_6 Same as "raid5_ls" dedicated last Q-syndrome disk
+
+ - layout for takeover from raid5_ls from/to raid6
+ raid6_rs_6 Same as "raid5_rs" dedicated last Q-syndrome disk
+
+ - layout for takeover from raid5_rs from/to raid6
+ raid10 Various RAID10 inspired algorithms chosen by additional params
+ (see raid10_format and raid10_copies below)
+
+ - RAID10: Striped Mirrors (aka 'Striping on top of mirrors')
+ - RAID1E: Integrated Adjacent Stripe Mirroring
+ - RAID1E: Integrated Offset Stripe Mirroring
+ - and other similar RAID10 variants
+ ============= ===============================================================
+
+ Reference: Chapter 4 of
+ https://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf
+
+<#raid_params>: The number of parameters that follow.
+
+<raid_params> consists of
+
+ Mandatory parameters:
+ <chunk_size>:
+ Chunk size in sectors. This parameter is often known as
+ "stripe size". It is the only mandatory parameter and
+ is placed first.
+
+ followed by optional parameters (in any order):
+ [sync|nosync]
+ Force or prevent RAID initialization.
+
+ [rebuild <idx>]
+ Rebuild drive number 'idx' (first drive is 0).
+
+ [daemon_sleep <ms>]
+ Interval between runs of the bitmap daemon that
+ clear bits. A longer interval means less bitmap I/O but
+ resyncing after a failure is likely to take longer.
+
+ [min_recovery_rate <kB/sec/disk>]
+ Throttle RAID initialization
+ [max_recovery_rate <kB/sec/disk>]
+ Throttle RAID initialization
+ [write_mostly <idx>]
+ Mark drive index 'idx' write-mostly.
+ [max_write_behind <sectors>]
+ See '--write-behind=' (man mdadm)
+ [stripe_cache <sectors>]
+ Stripe cache size (RAID 4/5/6 only)
+ [region_size <sectors>]
+ The region_size multiplied by the number of regions is the
+ logical size of the array. The bitmap records the device
+ synchronisation state for each region.
+
+ [raid10_copies <# copies>], [raid10_format <near|far|offset>]
+ These two options are used to alter the default layout of
+ a RAID10 configuration. The number of copies is can be
+ specified, but the default is 2. There are also three
+ variations to how the copies are laid down - the default
+ is "near". Near copies are what most people think of with
+ respect to mirroring. If these options are left unspecified,
+ or 'raid10_copies 2' and/or 'raid10_format near' are given,
+ then the layouts for 2, 3 and 4 devices are:
+
+ ======== ========== ==============
+ 2 drives 3 drives 4 drives
+ ======== ========== ==============
+ A1 A1 A1 A1 A2 A1 A1 A2 A2
+ A2 A2 A2 A3 A3 A3 A3 A4 A4
+ A3 A3 A4 A4 A5 A5 A5 A6 A6
+ A4 A4 A5 A6 A6 A7 A7 A8 A8
+ .. .. .. .. .. .. .. .. ..
+ ======== ========== ==============
+
+ The 2-device layout is equivalent 2-way RAID1. The 4-device
+ layout is what a traditional RAID10 would look like. The
+ 3-device layout is what might be called a 'RAID1E - Integrated
+ Adjacent Stripe Mirroring'.
+
+ If 'raid10_copies 2' and 'raid10_format far', then the layouts
+ for 2, 3 and 4 devices are:
+
+ ======== ============ ===================
+ 2 drives 3 drives 4 drives
+ ======== ============ ===================
+ A1 A2 A1 A2 A3 A1 A2 A3 A4
+ A3 A4 A4 A5 A6 A5 A6 A7 A8
+ A5 A6 A7 A8 A9 A9 A10 A11 A12
+ .. .. .. .. .. .. .. .. ..
+ A2 A1 A3 A1 A2 A2 A1 A4 A3
+ A4 A3 A6 A4 A5 A6 A5 A8 A7
+ A6 A5 A9 A7 A8 A10 A9 A12 A11
+ .. .. .. .. .. .. .. .. ..
+ ======== ============ ===================
+
+ If 'raid10_copies 2' and 'raid10_format offset', then the
+ layouts for 2, 3 and 4 devices are:
+
+ ======== ========== ================
+ 2 drives 3 drives 4 drives
+ ======== ========== ================
+ A1 A2 A1 A2 A3 A1 A2 A3 A4
+ A2 A1 A3 A1 A2 A2 A1 A4 A3
+ A3 A4 A4 A5 A6 A5 A6 A7 A8
+ A4 A3 A6 A4 A5 A6 A5 A8 A7
+ A5 A6 A7 A8 A9 A9 A10 A11 A12
+ A6 A5 A9 A7 A8 A10 A9 A12 A11
+ .. .. .. .. .. .. .. .. ..
+ ======== ========== ================
+
+ Here we see layouts closely akin to 'RAID1E - Integrated
+ Offset Stripe Mirroring'.
+
+ [delta_disks <N>]
+ The delta_disks option value (-251 < N < +251) triggers
+ device removal (negative value) or device addition (positive
+ value) to any reshape supporting raid levels 4/5/6 and 10.
+ RAID levels 4/5/6 allow for addition of devices (metadata
+ and data device tuple), raid10_near and raid10_offset only
+ allow for device addition. raid10_far does not support any
+ reshaping at all.
+ A minimum of devices have to be kept to enforce resilience,
+ which is 3 devices for raid4/5 and 4 devices for raid6.
+
+ [data_offset <sectors>]
+ This option value defines the offset into each data device
+ where the data starts. This is used to provide out-of-place
+ reshaping space to avoid writing over data while
+ changing the layout of stripes, hence an interruption/crash
+ may happen at any time without the risk of losing data.
+ E.g. when adding devices to an existing raid set during
+ forward reshaping, the out-of-place space will be allocated
+ at the beginning of each raid device. The kernel raid4/5/6/10
+ MD personalities supporting such device addition will read the data from
+ the existing first stripes (those with smaller number of stripes)
+ starting at data_offset to fill up a new stripe with the larger
+ number of stripes, calculate the redundancy blocks (CRC/Q-syndrome)
+ and write that new stripe to offset 0. Same will be applied to all
+ N-1 other new stripes. This out-of-place scheme is used to change
+ the RAID type (i.e. the allocation algorithm) as well, e.g.
+ changing from raid5_ls to raid5_n.
+
+ [journal_dev <dev>]
+ This option adds a journal device to raid4/5/6 raid sets and
+ uses it to close the 'write hole' caused by the non-atomic updates
+ to the component devices which can cause data loss during recovery.
+ The journal device is used as writethrough thus causing writes to
+ be throttled versus non-journaled raid4/5/6 sets.
+ Takeover/reshape is not possible with a raid4/5/6 journal device;
+ it has to be deconfigured before requesting these.
+
+ [journal_mode <mode>]
+ This option sets the caching mode on journaled raid4/5/6 raid sets
+ (see 'journal_dev <dev>' above) to 'writethrough' or 'writeback'.
+ If 'writeback' is selected the journal device has to be resilient
+ and must not suffer from the 'write hole' problem itself (e.g. use
+ raid1 or raid10) to avoid a single point of failure.
+
+<#raid_devs>: The number of devices composing the array.
+ Each device consists of two entries. The first is the device
+ containing the metadata (if any); the second is the one containing the
+ data. A Maximum of 64 metadata/data device entries are supported
+ up to target version 1.8.0.
+ 1.9.0 supports up to 253 which is enforced by the used MD kernel runtime.
+
+ If a drive has failed or is missing at creation time, a '-' can be
+ given for both the metadata and data drives for a given position.
+
+
+Example Tables
+--------------
+
+::
+
+ # RAID4 - 4 data drives, 1 parity (no metadata devices)
+ # No metadata devices specified to hold superblock/bitmap info
+ # Chunk size of 1MiB
+ # (Lines separated for easy reading)
+
+ 0 1960893648 raid \
+ raid4 1 2048 \
+ 5 - 8:17 - 8:33 - 8:49 - 8:65 - 8:81
+
+ # RAID4 - 4 data drives, 1 parity (with metadata devices)
+ # Chunk size of 1MiB, force RAID initialization,
+ # min recovery rate at 20 kiB/sec/disk
+
+ 0 1960893648 raid \
+ raid4 4 2048 sync min_recovery_rate 20 \
+ 5 8:17 8:18 8:33 8:34 8:49 8:50 8:65 8:66 8:81 8:82
+
+
+Status Output
+-------------
+'dmsetup table' displays the table used to construct the mapping.
+The optional parameters are always printed in the order listed
+above with "sync" or "nosync" always output ahead of the other
+arguments, regardless of the order used when originally loading the table.
+Arguments that can be repeated are ordered by value.
+
+
+'dmsetup status' yields information on the state and health of the array.
+The output is as follows (normally a single line, but expanded here for
+clarity)::
+
+ 1: <s> <l> raid \
+ 2: <raid_type> <#devices> <health_chars> \
+ 3: <sync_ratio> <sync_action> <mismatch_cnt>
+
+Line 1 is the standard output produced by device-mapper.
+
+Line 2 & 3 are produced by the raid target and are best explained by example::
+
+ 0 1960893648 raid raid4 5 AAAAA 2/490221568 init 0
+
+Here we can see the RAID type is raid4, there are 5 devices - all of
+which are 'A'live, and the array is 2/490221568 complete with its initial
+recovery. Here is a fuller description of the individual fields:
+
+ =============== =========================================================
+ <raid_type> Same as the <raid_type> used to create the array.
+ <health_chars> One char for each device, indicating:
+
+ - 'A' = alive and in-sync
+ - 'a' = alive but not in-sync
+ - 'D' = dead/failed.
+ <sync_ratio> The ratio indicating how much of the array has undergone
+ the process described by 'sync_action'. If the
+ 'sync_action' is "check" or "repair", then the process
+ of "resync" or "recover" can be considered complete.
+ <sync_action> One of the following possible states:
+
+ idle
+ - No synchronization action is being performed.
+ frozen
+ - The current action has been halted.
+ resync
+ - Array is undergoing its initial synchronization
+ or is resynchronizing after an unclean shutdown
+ (possibly aided by a bitmap).
+ recover
+ - A device in the array is being rebuilt or
+ replaced.
+ check
+ - A user-initiated full check of the array is
+ being performed. All blocks are read and
+ checked for consistency. The number of
+ discrepancies found are recorded in
+ <mismatch_cnt>. No changes are made to the
+ array by this action.
+ repair
+ - The same as "check", but discrepancies are
+ corrected.
+ reshape
+ - The array is undergoing a reshape.
+ <mismatch_cnt> The number of discrepancies found between mirror copies
+ in RAID1/10 or wrong parity values found in RAID4/5/6.
+ This value is valid only after a "check" of the array
+ is performed. A healthy array has a 'mismatch_cnt' of 0.
+ <data_offset> The current data offset to the start of the user data on
+ each component device of a raid set (see the respective
+ raid parameter to support out-of-place reshaping).
+ <journal_char> - 'A' - active write-through journal device.
+ - 'a' - active write-back journal device.
+ - 'D' - dead journal device.
+ - '-' - no journal device.
+ =============== =========================================================
+
+
+Message Interface
+-----------------
+The dm-raid target will accept certain actions through the 'message' interface.
+('man dmsetup' for more information on the message interface.) These actions
+include:
+
+ ========= ================================================
+ "idle" Halt the current sync action.
+ "frozen" Freeze the current sync action.
+ "resync" Initiate/continue a resync.
+ "recover" Initiate/continue a recover process.
+ "check" Initiate a check (i.e. a "scrub") of the array.
+ "repair" Initiate a repair of the array.
+ ========= ================================================
+
+
+Discard Support
+---------------
+The implementation of discard support among hardware vendors varies.
+When a block is discarded, some storage devices will return zeroes when
+the block is read. These devices set the 'discard_zeroes_data'
+attribute. Other devices will return random data. Confusingly, some
+devices that advertise 'discard_zeroes_data' will not reliably return
+zeroes when discarded blocks are read! Since RAID 4/5/6 uses blocks
+from a number of devices to calculate parity blocks and (for performance
+reasons) relies on 'discard_zeroes_data' being reliable, it is important
+that the devices be consistent. Blocks may be discarded in the middle
+of a RAID 4/5/6 stripe and if subsequent read results are not
+consistent, the parity blocks may be calculated differently at any time;
+making the parity blocks useless for redundancy. It is important to
+understand how your hardware behaves with discards if you are going to
+enable discards with RAID 4/5/6.
+
+Since the behavior of storage devices is unreliable in this respect,
+even when reporting 'discard_zeroes_data', by default RAID 4/5/6
+discard support is disabled -- this ensures data integrity at the
+expense of losing some performance.
+
+Storage devices that properly support 'discard_zeroes_data' are
+increasingly whitelisted in the kernel and can thus be trusted.
+
+For trusted devices, the following dm-raid module parameter can be set
+to safely enable discard support for RAID 4/5/6:
+
+ 'devices_handle_discards_safely'
+
+
+Version History
+---------------
+
+::
+
+ 1.0.0 Initial version. Support for RAID 4/5/6
+ 1.1.0 Added support for RAID 1
+ 1.2.0 Handle creation of arrays that contain failed devices.
+ 1.3.0 Added support for RAID 10
+ 1.3.1 Allow device replacement/rebuild for RAID 10
+ 1.3.2 Fix/improve redundancy checking for RAID10
+ 1.4.0 Non-functional change. Removes arg from mapping function.
+ 1.4.1 RAID10 fix redundancy validation checks (commit 55ebbb5).
+ 1.4.2 Add RAID10 "far" and "offset" algorithm support.
+ 1.5.0 Add message interface to allow manipulation of the sync_action.
+ New status (STATUSTYPE_INFO) fields: sync_action and mismatch_cnt.
+ 1.5.1 Add ability to restore transiently failed devices on resume.
+ 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check".
+ 1.6.0 Add discard support (and devices_handle_discard_safely module param).
+ 1.7.0 Add support for MD RAID0 mappings.
+ 1.8.0 Explicitly check for compatible flags in the superblock metadata
+ and reject to start the raid set if any are set by a newer
+ target version, thus avoiding data corruption on a raid set
+ with a reshape in progress.
+ 1.9.0 Add support for RAID level takeover/reshape/region size
+ and set size reduction.
+ 1.9.1 Fix activation of existing RAID 4/10 mapped devices
+ 1.9.2 Don't emit '- -' on the status table line in case the constructor
+ fails reading a superblock. Correctly emit 'maj:min1 maj:min2' and
+ 'D' on the status line. If '- -' is passed into the constructor, emit
+ '- -' on the table line and '-' as the status line health character.
+ 1.10.0 Add support for raid4/5/6 journal device
+ 1.10.1 Fix data corruption on reshape request
+ 1.11.0 Fix table line argument order
+ (wrong raid10_copies/raid10_format sequence)
+ 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option
+ 1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available
+ 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A')
+ 1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an
+ state races.
+ 1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen
+ 1.14.0 Fix reshape race on small devices. Fix stripe adding reshape
+ deadlock/potential data corruption. Update superblock when
+ specific devices are requested via rebuild. Fix RAID leg
+ rebuild errors.
+ 1.15.0 Fix size extensions not being synchronized in case of new MD bitmap
+ pages allocated; also fix those not occurring after previous reductions
+ 1.15.1 Fix argument count and arguments for rebuild/write_mostly/journal_(dev|mode)
+ on the status line.
diff --git a/Documentation/admin-guide/device-mapper/dm-service-time.rst b/Documentation/admin-guide/device-mapper/dm-service-time.rst
new file mode 100644
index 000000000000..facf277fc13c
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-service-time.rst
@@ -0,0 +1,101 @@
+===============
+dm-service-time
+===============
+
+dm-service-time is a path selector module for device-mapper targets,
+which selects a path with the shortest estimated service time for
+the incoming I/O.
+
+The service time for each path is estimated by dividing the total size
+of in-flight I/Os on a path with the performance value of the path.
+The performance value is a relative throughput value among all paths
+in a path-group, and it can be specified as a table argument.
+
+The path selector name is 'service-time'.
+
+Table parameters for each path:
+
+ [<repeat_count> [<relative_throughput>]]
+ <repeat_count>:
+ The number of I/Os to dispatch using the selected
+ path before switching to the next path.
+ If not given, internal default is used. To check
+ the default value, see the activated table.
+ <relative_throughput>:
+ The relative throughput value of the path
+ among all paths in the path-group.
+ The valid range is 0-100.
+ If not given, minimum value '1' is used.
+ If '0' is given, the path isn't selected while
+ other paths having a positive value are available.
+
+Status for each path:
+
+ <status> <fail-count> <in-flight-size> <relative_throughput>
+ <status>:
+ 'A' if the path is active, 'F' if the path is failed.
+ <fail-count>:
+ The number of path failures.
+ <in-flight-size>:
+ The size of in-flight I/Os on the path.
+ <relative_throughput>:
+ The relative throughput value of the path
+ among all paths in the path-group.
+
+
+Algorithm
+=========
+
+dm-service-time adds the I/O size to 'in-flight-size' when the I/O is
+dispatched and subtracts when completed.
+Basically, dm-service-time selects a path having minimum service time
+which is calculated by::
+
+ ('in-flight-size' + 'size-of-incoming-io') / 'relative_throughput'
+
+However, some optimizations below are used to reduce the calculation
+as much as possible.
+
+ 1. If the paths have the same 'relative_throughput', skip
+ the division and just compare the 'in-flight-size'.
+
+ 2. If the paths have the same 'in-flight-size', skip the division
+ and just compare the 'relative_throughput'.
+
+ 3. If some paths have non-zero 'relative_throughput' and others
+ have zero 'relative_throughput', ignore those paths with zero
+ 'relative_throughput'.
+
+If such optimizations can't be applied, calculate service time, and
+compare service time.
+If calculated service time is equal, the path having maximum
+'relative_throughput' may be better. So compare 'relative_throughput'
+then.
+
+
+Examples
+========
+In case that 2 paths (sda and sdb) are used with repeat_count == 128
+and sda has an average throughput 1GB/s and sdb has 4GB/s,
+'relative_throughput' value may be '1' for sda and '4' for sdb::
+
+ # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4" \
+ dmsetup create test
+ #
+ # dmsetup table
+ test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 1 8:16 128 4
+ #
+ # dmsetup status
+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 1 8:16 A 0 0 4
+
+
+Or '2' for sda and '8' for sdb would be also true::
+
+ # echo "0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8" \
+ dmsetup create test
+ #
+ # dmsetup table
+ test: 0 10 multipath 0 0 1 1 service-time 0 2 2 8:0 128 2 8:16 128 8
+ #
+ # dmsetup status
+ test: 0 10 multipath 2 0 0 0 1 1 E 0 2 2 8:0 A 0 0 2 8:16 A 0 0 8
diff --git a/Documentation/admin-guide/device-mapper/dm-uevent.rst b/Documentation/admin-guide/device-mapper/dm-uevent.rst
new file mode 100644
index 000000000000..4a8ee8d069c9
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-uevent.rst
@@ -0,0 +1,110 @@
+====================
+device-mapper uevent
+====================
+
+The device-mapper uevent code adds the capability to device-mapper to create
+and send kobject uevents (uevents). Previously device-mapper events were only
+available through the ioctl interface. The advantage of the uevents interface
+is the event contains environment attributes providing increased context for
+the event avoiding the need to query the state of the device-mapper device after
+the event is received.
+
+There are two functions currently for device-mapper events. The first function
+listed creates the event and the second function sends the event(s)::
+
+ void dm_path_uevent(enum dm_uevent_type event_type, struct dm_target *ti,
+ const char *path, unsigned nr_valid_paths)
+
+ void dm_send_uevents(struct list_head *events, struct kobject *kobj)
+
+
+The variables added to the uevent environment are:
+
+Variable Name: DM_TARGET
+------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description:
+:Value: Name of device-mapper target that generated the event.
+
+Variable Name: DM_ACTION
+------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description:
+:Value: Device-mapper specific action that caused the uevent action.
+ PATH_FAILED - A path has failed;
+ PATH_REINSTATED - A path has been reinstated.
+
+Variable Name: DM_SEQNUM
+------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: unsigned integer
+:Description: A sequence number for this specific device-mapper device.
+:Value: Valid unsigned integer range.
+
+Variable Name: DM_PATH
+----------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description: Major and minor number of the path device pertaining to this
+ event.
+:Value: Path name in the form of "Major:Minor"
+
+Variable Name: DM_NR_VALID_PATHS
+--------------------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: unsigned integer
+:Description:
+:Value: Valid unsigned integer range.
+
+Variable Name: DM_NAME
+----------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description: Name of the device-mapper device.
+:Value: Name
+
+Variable Name: DM_UUID
+----------------------
+:Uevent Action(s): KOBJ_CHANGE
+:Type: string
+:Description: UUID of the device-mapper device.
+:Value: UUID. (Empty string if there isn't one.)
+
+An example of the uevents generated as captured by udevmonitor is shown
+below
+
+1.) Path failure::
+
+ UEVENT[1192521009.711215] change@/block/dm-3
+ ACTION=change
+ DEVPATH=/block/dm-3
+ SUBSYSTEM=block
+ DM_TARGET=multipath
+ DM_ACTION=PATH_FAILED
+ DM_SEQNUM=1
+ DM_PATH=8:32
+ DM_NR_VALID_PATHS=0
+ DM_NAME=mpath2
+ DM_UUID=mpath-35333333000002328
+ MINOR=3
+ MAJOR=253
+ SEQNUM=1130
+
+2.) Path reinstate::
+
+ UEVENT[1192521132.989927] change@/block/dm-3
+ ACTION=change
+ DEVPATH=/block/dm-3
+ SUBSYSTEM=block
+ DM_TARGET=multipath
+ DM_ACTION=PATH_REINSTATED
+ DM_SEQNUM=2
+ DM_PATH=8:32
+ DM_NR_VALID_PATHS=1
+ DM_NAME=mpath2
+ DM_UUID=mpath-35333333000002328
+ MINOR=3
+ MAJOR=253
+ SEQNUM=1131
diff --git a/Documentation/admin-guide/device-mapper/dm-zoned.rst b/Documentation/admin-guide/device-mapper/dm-zoned.rst
new file mode 100644
index 000000000000..932383fe6e88
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst
@@ -0,0 +1,194 @@
+========
+dm-zoned
+========
+
+The dm-zoned device mapper target exposes a zoned block device (ZBC and
+ZAC compliant devices) as a regular block device without any write
+pattern constraints. In effect, it implements a drive-managed zoned
+block device which hides from the user (a file system or an application
+doing raw block device accesses) the sequential write constraints of
+host-managed zoned block devices and can mitigate the potential
+device-side performance degradation due to excessive random writes on
+host-aware zoned block devices.
+
+For a more detailed description of the zoned block device models and
+their constraints see (for SCSI devices):
+
+https://www.t10.org/drafts.htm#ZBC_Family
+
+and (for ATA devices):
+
+http://www.t13.org/Documents/UploadedDocuments/docs2015/di537r05-Zoned_Device_ATA_Command_Set_ZAC.pdf
+
+The dm-zoned implementation is simple and minimizes system overhead (CPU
+and memory usage as well as storage capacity loss). For a 10TB
+host-managed disk with 256 MB zones, dm-zoned memory usage per disk
+instance is at most 4.5 MB and as little as 5 zones will be used
+internally for storing metadata and performing reclaim operations.
+
+dm-zoned target devices are formatted and checked using the dmzadm
+utility available at:
+
+https://github.com/hgst/dm-zoned-tools
+
+Algorithm
+=========
+
+dm-zoned implements an on-disk buffering scheme to handle non-sequential
+write accesses to the sequential zones of a zoned block device.
+Conventional zones are used for caching as well as for storing internal
+metadata. It can also use a regular block device together with the zoned
+block device; in that case the regular block device will be split logically
+in zones with the same size as the zoned block device. These zones will be
+placed in front of the zones from the zoned block device and will be handled
+just like conventional zones.
+
+The zones of the device(s) are separated into 2 types:
+
+1) Metadata zones: these are conventional zones used to store metadata.
+Metadata zones are not reported as usable capacity to the user.
+
+2) Data zones: all remaining zones, the vast majority of which will be
+sequential zones used exclusively to store user data. The conventional
+zones of the device may be used also for buffering user random writes.
+Data in these zones may be directly mapped to the conventional zone, but
+later moved to a sequential zone so that the conventional zone can be
+reused for buffering incoming random writes.
+
+dm-zoned exposes a logical device with a sector size of 4096 bytes,
+irrespective of the physical sector size of the backend zoned block
+device being used. This allows reducing the amount of metadata needed to
+manage valid blocks (blocks written).
+
+The on-disk metadata format is as follows:
+
+1) The first block of the first conventional zone found contains the
+super block which describes the on disk amount and position of metadata
+blocks.
+
+2) Following the super block, a set of blocks is used to describe the
+mapping of the logical device blocks. The mapping is done per chunk of
+blocks, with the chunk size equal to the zoned block device size. The
+mapping table is indexed by chunk number and each mapping entry
+indicates the zone number of the device storing the chunk of data. Each
+mapping entry may also indicate if the zone number of a conventional
+zone used to buffer random modification to the data zone.
+
+3) A set of blocks used to store bitmaps indicating the validity of
+blocks in the data zones follows the mapping table. A valid block is
+defined as a block that was written and not discarded. For a buffered
+data chunk, a block is always valid only in the data zone mapping the
+chunk or in the buffer zone of the chunk.
+
+For a logical chunk mapped to a conventional zone, all write operations
+are processed by directly writing to the zone. If the mapping zone is a
+sequential zone, the write operation is processed directly only if the
+write offset within the logical chunk is equal to the write pointer
+offset within of the sequential data zone (i.e. the write operation is
+aligned on the zone write pointer). Otherwise, write operations are
+processed indirectly using a buffer zone. In that case, an unused
+conventional zone is allocated and assigned to the chunk being
+accessed. Writing a block to the buffer zone of a chunk will
+automatically invalidate the same block in the sequential zone mapping
+the chunk. If all blocks of the sequential zone become invalid, the zone
+is freed and the chunk buffer zone becomes the primary zone mapping the
+chunk, resulting in native random write performance similar to a regular
+block device.
+
+Read operations are processed according to the block validity
+information provided by the bitmaps. Valid blocks are read either from
+the sequential zone mapping a chunk, or if the chunk is buffered, from
+the buffer zone assigned. If the accessed chunk has no mapping, or the
+accessed blocks are invalid, the read buffer is zeroed and the read
+operation terminated.
+
+After some time, the limited number of conventional zones available may
+be exhausted (all used to map chunks or buffer sequential zones) and
+unaligned writes to unbuffered chunks become impossible. To avoid this
+situation, a reclaim process regularly scans used conventional zones and
+tries to reclaim the least recently used zones by copying the valid
+blocks of the buffer zone to a free sequential zone. Once the copy
+completes, the chunk mapping is updated to point to the sequential zone
+and the buffer zone freed for reuse.
+
+Metadata Protection
+===================
+
+To protect metadata against corruption in case of sudden power loss or
+system crash, 2 sets of metadata zones are used. One set, the primary
+set, is used as the main metadata region, while the secondary set is
+used as a staging area. Modified metadata is first written to the
+secondary set and validated by updating the super block in the secondary
+set, a generation counter is used to indicate that this set contains the
+newest metadata. Once this operation completes, in place of metadata
+block updates can be done in the primary metadata set. This ensures that
+one of the set is always consistent (all modifications committed or none
+at all). Flush operations are used as a commit point. Upon reception of
+a flush request, metadata modification activity is temporarily blocked
+(for both incoming BIO processing and reclaim process) and all dirty
+metadata blocks are staged and updated. Normal operation is then
+resumed. Flushing metadata thus only temporarily delays write and
+discard requests. Read requests can be processed concurrently while
+metadata flush is being executed.
+
+If a regular device is used in conjunction with the zoned block device,
+a third set of metadata (without the zone bitmaps) is written to the
+start of the zoned block device. This metadata has a generation counter of
+'0' and will never be updated during normal operation; it just serves for
+identification purposes. The first and second copy of the metadata
+are located at the start of the regular block device.
+
+Usage
+=====
+
+A zoned block device must first be formatted using the dmzadm tool. This
+will analyze the device zone configuration, determine where to place the
+metadata sets on the device and initialize the metadata sets.
+
+Ex::
+
+ dmzadm --format /dev/sdxx
+
+
+If two drives are to be used, both devices must be specified, with the
+regular block device as the first device.
+
+Ex::
+
+ dmzadm --format /dev/sdxx /dev/sdyy
+
+
+Formatted device(s) can be started with the dmzadm utility, too.:
+
+Ex::
+
+ dmzadm --start /dev/sdxx /dev/sdyy
+
+
+Information about the internal layout and current usage of the zones can
+be obtained with the 'status' callback from dmsetup:
+
+Ex::
+
+ dmsetup status /dev/dm-X
+
+will return a line
+
+ 0 <size> zoned <nr_zones> zones <nr_unmap_rnd>/<nr_rnd> random <nr_unmap_seq>/<nr_seq> sequential
+
+where <nr_zones> is the total number of zones, <nr_unmap_rnd> is the number
+of unmapped (ie free) random zones, <nr_rnd> the total number of zones,
+<nr_unmap_seq> the number of unmapped sequential zones, and <nr_seq> the
+total number of sequential zones.
+
+Normally the reclaim process will be started once there are less than 50
+percent free random zones. In order to start the reclaim process manually
+even before reaching this threshold the 'dmsetup message' function can be
+used:
+
+Ex::
+
+ dmsetup message /dev/dm-X 0 reclaim
+
+will start the reclaim process and random zones will be moved to sequential
+zones.
diff --git a/Documentation/admin-guide/device-mapper/era.rst b/Documentation/admin-guide/device-mapper/era.rst
new file mode 100644
index 000000000000..90dd5c670b9f
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/era.rst
@@ -0,0 +1,116 @@
+======
+dm-era
+======
+
+Introduction
+============
+
+dm-era is a target that behaves similar to the linear target. In
+addition it keeps track of which blocks were written within a user
+defined period of time called an 'era'. Each era target instance
+maintains the current era as a monotonically increasing 32-bit
+counter.
+
+Use cases include tracking changed blocks for backup software, and
+partially invalidating the contents of a cache to restore cache
+coherency after rolling back a vendor snapshot.
+
+Constructor
+===========
+
+era <metadata dev> <origin dev> <block size>
+
+ ================ ======================================================
+ metadata dev fast device holding the persistent metadata
+ origin dev device holding data blocks that may change
+ block size block size of origin data device, granularity that is
+ tracked by the target
+ ================ ======================================================
+
+Messages
+========
+
+None of the dm messages take any arguments.
+
+checkpoint
+----------
+
+Possibly move to a new era. You shouldn't assume the era has
+incremented. After sending this message, you should check the
+current era via the status line.
+
+take_metadata_snap
+------------------
+
+Create a clone of the metadata, to allow a userland process to read it.
+
+drop_metadata_snap
+------------------
+
+Drop the metadata snapshot.
+
+Status
+======
+
+<metadata block size> <#used metadata blocks>/<#total metadata blocks>
+<current era> <held metadata root | '-'>
+
+========================= ==============================================
+metadata block size Fixed block size for each metadata block in
+ sectors
+#used metadata blocks Number of metadata blocks used
+#total metadata blocks Total number of metadata blocks
+current era The current era
+held metadata root The location, in blocks, of the metadata root
+ that has been 'held' for userspace read
+ access. '-' indicates there is no held root
+========================= ==============================================
+
+Detailed use case
+=================
+
+The scenario of invalidating a cache when rolling back a vendor
+snapshot was the primary use case when developing this target:
+
+Taking a vendor snapshot
+------------------------
+
+- Send a checkpoint message to the era target
+- Make a note of the current era in its status line
+- Take vendor snapshot (the era and snapshot should be forever
+ associated now).
+
+Rolling back to an vendor snapshot
+----------------------------------
+
+- Cache enters passthrough mode (see: dm-cache's docs in cache.txt)
+- Rollback vendor storage
+- Take metadata snapshot
+- Ascertain which blocks have been written since the snapshot was taken
+ by checking each block's era
+- Invalidate those blocks in the caching software
+- Cache returns to writeback/writethrough mode
+
+Memory usage
+============
+
+The target uses a bitset to record writes in the current era. It also
+has a spare bitset ready for switching over to a new era. Other than
+that it uses a few 4k blocks for updating metadata::
+
+ (4 * nr_blocks) bytes + buffers
+
+Resilience
+==========
+
+Metadata is updated on disk before a write to a previously unwritten
+block is performed. As such dm-era should not be effected by a hard
+crash such as power failure.
+
+Userland tools
+==============
+
+Userland tools are found in the increasingly poorly named
+thin-provisioning-tools project:
+
+ https://github.com/jthornber/thin-provisioning-tools
diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst
new file mode 100644
index 000000000000..f1c1f4b824ba
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -0,0 +1,49 @@
+=============
+Device Mapper
+=============
+
+.. toctree::
+ :maxdepth: 1
+
+ cache-policies
+ cache
+ delay
+ dm-clone
+ dm-crypt
+ dm-dust
+ dm-ebs
+ dm-flakey
+ dm-ima
+ dm-init
+ dm-integrity
+ dm-io
+ dm-log
+ dm-pcache
+ dm-queue-length
+ dm-raid
+ dm-service-time
+ dm-uevent
+ dm-zoned
+ era
+ kcopyd
+ linear
+ log-writes
+ persistent-data
+ snapshot
+ statistics
+ striped
+ switch
+ thin-provisioning
+ unstriped
+ vdo-design
+ vdo
+ verity
+ writecache
+ zero
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/device-mapper/kcopyd.rst b/Documentation/admin-guide/device-mapper/kcopyd.rst
new file mode 100644
index 000000000000..7651d395127f
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/kcopyd.rst
@@ -0,0 +1,47 @@
+======
+kcopyd
+======
+
+Kcopyd provides the ability to copy a range of sectors from one block-device
+to one or more other block-devices, with an asynchronous completion
+notification. It is used by dm-snapshot and dm-mirror.
+
+Users of kcopyd must first create a client and indicate how many memory pages
+to set aside for their copy jobs. This is done with a call to
+kcopyd_client_create()::
+
+ int kcopyd_client_create(unsigned int num_pages,
+ struct kcopyd_client **result);
+
+To start a copy job, the user must set up io_region structures to describe
+the source and destinations of the copy. Each io_region indicates a
+block-device along with the starting sector and size of the region. The source
+of the copy is given as one io_region structure, and the destinations of the
+copy are given as an array of io_region structures::
+
+ struct io_region {
+ struct block_device *bdev;
+ sector_t sector;
+ sector_t count;
+ };
+
+To start the copy, the user calls kcopyd_copy(), passing in the client
+pointer, pointers to the source and destination io_regions, the name of a
+completion callback routine, and a pointer to some context data for the copy::
+
+ int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
+ unsigned int num_dests, struct io_region *dests,
+ unsigned int flags, kcopyd_notify_fn fn, void *context);
+
+ typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err,
+ void *context);
+
+When the copy completes, kcopyd will call the user's completion routine,
+passing back the user's context pointer. It will also indicate if a read or
+write error occurred during the copy.
+
+When a user is done with all their copy jobs, they should call
+kcopyd_client_destroy() to delete the kcopyd client, which will release the
+associated memory pages::
+
+ void kcopyd_client_destroy(struct kcopyd_client *kc);
diff --git a/Documentation/admin-guide/device-mapper/linear.rst b/Documentation/admin-guide/device-mapper/linear.rst
new file mode 100644
index 000000000000..9d17fc6e64a9
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/linear.rst
@@ -0,0 +1,63 @@
+=========
+dm-linear
+=========
+
+Device-Mapper's "linear" target maps a linear range of the Device-Mapper
+device onto a linear range of another device. This is the basic building
+block of logical volume managers.
+
+Parameters: <dev path> <offset>
+ <dev path>:
+ Full pathname to the underlying block-device, or a
+ "major:minor" device-number.
+ <offset>:
+ Starting sector within the device.
+
+
+Example scripts
+===============
+
+::
+
+ #!/bin/sh
+ # Create an identity mapping for a device
+ echo "0 `blockdev --getsz $1` linear $1 0" | dmsetup create identity
+
+::
+
+ #!/bin/sh
+ # Join 2 devices together
+ size1=`blockdev --getsz $1`
+ size2=`blockdev --getsz $2`
+ echo "0 $size1 linear $1 0
+ $size1 $size2 linear $2 0" | dmsetup create joined
+
+::
+
+ #!/usr/bin/perl -w
+ # Split a device into 4M chunks and then join them together in reverse order.
+
+ my $name = "reverse";
+ my $extent_size = 4 * 1024 * 2;
+ my $dev = $ARGV[0];
+ my $table = "";
+ my $count = 0;
+
+ if (!defined($dev)) {
+ die("Please specify a device.\n");
+ }
+
+ my $dev_size = `blockdev --getsz $dev`;
+ my $extents = int($dev_size / $extent_size) -
+ (($dev_size % $extent_size) ? 1 : 0);
+
+ while ($extents > 0) {
+ my $this_start = $count * $extent_size;
+ $extents--;
+ $count++;
+ my $this_offset = $extents * $extent_size;
+
+ $table .= "$this_start $extent_size linear $dev $this_offset\n";
+ }
+
+ `echo \"$table\" | dmsetup create $name`;
diff --git a/Documentation/admin-guide/device-mapper/log-writes.rst b/Documentation/admin-guide/device-mapper/log-writes.rst
new file mode 100644
index 000000000000..23141f2ffb7c
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/log-writes.rst
@@ -0,0 +1,145 @@
+=============
+dm-log-writes
+=============
+
+This target takes 2 devices, one to pass all IO to normally, and one to log all
+of the write operations to. This is intended for file system developers wishing
+to verify the integrity of metadata or data as the file system is written to.
+There is a log_write_entry written for every WRITE request and the target is
+able to take arbitrary data from userspace to insert into the log. The data
+that is in the WRITE requests is copied into the log to make the replay happen
+exactly as it happened originally.
+
+Log Ordering
+============
+
+We log things in order of completion once we are sure the write is no longer in
+cache. This means that normal WRITE requests are not actually logged until the
+next REQ_PREFLUSH request. This is to make it easier for userspace to replay
+the log in a way that correlates to what is on disk and not what is in cache,
+to make it easier to detect improper waiting/flushing.
+
+This works by attaching all WRITE requests to a list once the write completes.
+Once we see a REQ_PREFLUSH request we splice this list onto the request and once
+the FLUSH request completes we log all of the WRITEs and then the FLUSH. Only
+completed WRITEs, at the time the REQ_PREFLUSH is issued, are added in order to
+simulate the worst case scenario with regard to power failures. Consider the
+following example (W means write, C means complete):
+
+ W1,W2,W3,C3,C2,Wflush,C1,Cflush
+
+The log would show the following:
+
+ W3,W2,flush,W1....
+
+Again this is to simulate what is actually on disk, this allows us to detect
+cases where a power failure at a particular point in time would create an
+inconsistent file system.
+
+Any REQ_FUA requests bypass this flushing mechanism and are logged as soon as
+they complete as those requests will obviously bypass the device cache.
+
+Any REQ_OP_DISCARD requests are treated like WRITE requests. Otherwise we would
+have all the DISCARD requests, and then the WRITE requests and then the FLUSH
+request. Consider the following example:
+
+ WRITE block 1, DISCARD block 1, FLUSH
+
+If we logged DISCARD when it completed, the replay would look like this:
+
+ DISCARD 1, WRITE 1, FLUSH
+
+which isn't quite what happened and wouldn't be caught during the log replay.
+
+Target interface
+================
+
+i) Constructor
+
+ log-writes <dev_path> <log_dev_path>
+
+ ============= ==============================================
+ dev_path Device that all of the IO will go to normally.
+ log_dev_path Device where the log entries are written to.
+ ============= ==============================================
+
+ii) Status
+
+ <#logged entries> <highest allocated sector>
+
+ =========================== ========================
+ #logged entries Number of logged entries
+ highest allocated sector Highest allocated sector
+ =========================== ========================
+
+iii) Messages
+
+ mark <description>
+
+ You can use a dmsetup message to set an arbitrary mark in a log.
+ For example say you want to fsck a file system after every
+ write, but first you need to replay up to the mkfs to make sure
+ we're fsck'ing something reasonable, you would do something like
+ this::
+
+ mkfs.btrfs -f /dev/mapper/log
+ dmsetup message log 0 mark mkfs
+ <run test>
+
+ This would allow you to replay the log up to the mkfs mark and
+ then replay from that point on doing the fsck check in the
+ interval that you want.
+
+ Every log has a mark at the end labeled "dm-log-writes-end".
+
+Userspace component
+===================
+
+There is a userspace tool that will replay the log for you in various ways.
+It can be found here: https://github.com/josefbacik/log-writes
+
+Example usage
+=============
+
+Say you want to test fsync on your file system. You would do something like
+this::
+
+ TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
+ dmsetup create log --table "$TABLE"
+ mkfs.btrfs -f /dev/mapper/log
+ dmsetup message log 0 mark mkfs
+
+ mount /dev/mapper/log /mnt/btrfs-test
+ <some test that does fsync at the end>
+ dmsetup message log 0 mark fsync
+ md5sum /mnt/btrfs-test/foo
+ umount /mnt/btrfs-test
+
+ dmsetup remove log
+ replay-log --log /dev/sdc --replay /dev/sdb --end-mark fsync
+ mount /dev/sdb /mnt/btrfs-test
+ md5sum /mnt/btrfs-test/foo
+ <verify md5sum's are correct>
+
+ Another option is to do a complicated file system operation and verify the file
+ system is consistent during the entire operation. You could do this with:
+
+ TABLE="0 $(blockdev --getsz /dev/sdb) log-writes /dev/sdb /dev/sdc"
+ dmsetup create log --table "$TABLE"
+ mkfs.btrfs -f /dev/mapper/log
+ dmsetup message log 0 mark mkfs
+
+ mount /dev/mapper/log /mnt/btrfs-test
+ <fsstress to dirty the fs>
+ btrfs filesystem balance /mnt/btrfs-test
+ umount /mnt/btrfs-test
+ dmsetup remove log
+
+ replay-log --log /dev/sdc --replay /dev/sdb --end-mark mkfs
+ btrfsck /dev/sdb
+ replay-log --log /dev/sdc --replay /dev/sdb --start-mark mkfs \
+ --fsck "btrfsck /dev/sdb" --check fua
+
+And that will replay the log until it sees a FUA request, run the fsck command
+and if the fsck passes it will replay to the next FUA, until it is completed or
+the fsck command exists abnormally.
diff --git a/Documentation/admin-guide/device-mapper/persistent-data.rst b/Documentation/admin-guide/device-mapper/persistent-data.rst
new file mode 100644
index 000000000000..2065c3c5a091
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/persistent-data.rst
@@ -0,0 +1,88 @@
+===============
+Persistent data
+===============
+
+Introduction
+============
+
+The more-sophisticated device-mapper targets require complex metadata
+that is managed in kernel. In late 2010 we were seeing that various
+different targets were rolling their own data structures, for example:
+
+- Mikulas Patocka's multisnap implementation
+- Heinz Mauelshagen's thin provisioning target
+- Another btree-based caching target posted to dm-devel
+- Another multi-snapshot target based on a design of Daniel Phillips
+
+Maintaining these data structures takes a lot of work, so if possible
+we'd like to reduce the number.
+
+The persistent-data library is an attempt to provide a re-usable
+framework for people who want to store metadata in device-mapper
+targets. It's currently used by the thin-provisioning target and an
+upcoming hierarchical storage target.
+
+Overview
+========
+
+The main documentation is in the header files which can all be found
+under drivers/md/persistent-data.
+
+The block manager
+-----------------
+
+dm-block-manager.[hc]
+
+This provides access to the data on disk in fixed sized-blocks. There
+is a read/write locking interface to prevent concurrent accesses, and
+keep data that is being used in the cache.
+
+Clients of persistent-data are unlikely to use this directly.
+
+The transaction manager
+-----------------------
+
+dm-transaction-manager.[hc]
+
+This restricts access to blocks and enforces copy-on-write semantics.
+The only way you can get hold of a writable block through the
+transaction manager is by shadowing an existing block (ie. doing
+copy-on-write) or allocating a fresh one. Shadowing is elided within
+the same transaction so performance is reasonable. The commit method
+ensures that all data is flushed before it writes the superblock.
+On power failure your metadata will be as it was when last committed.
+
+The Space Maps
+--------------
+
+dm-space-map.h
+dm-space-map-metadata.[hc]
+dm-space-map-disk.[hc]
+
+On-disk data structures that keep track of reference counts of blocks.
+Also acts as the allocator of new blocks. Currently two
+implementations: a simpler one for managing blocks on a different
+device (eg. thinly-provisioned data blocks); and one for managing
+the metadata space. The latter is complicated by the need to store
+its own data within the space it's managing.
+
+The data structures
+-------------------
+
+dm-btree.[hc]
+dm-btree-remove.c
+dm-btree-spine.c
+dm-btree-internal.h
+
+Currently there is only one data structure, a hierarchical btree.
+There are plans to add more. For example, something with an
+array-like interface would see a lot of use.
+
+The btree is 'hierarchical' in that you can define it to be composed
+of nested btrees, and take multiple keys. For example, the
+thin-provisioning target uses a btree with two levels of nesting.
+The first maps a device id to a mapping tree, and that in turn maps a
+virtual block to a physical block.
+
+Values stored in the btrees can have arbitrary size. Keys are always
+64bits, although nesting allows you to use multiple keys.
diff --git a/Documentation/admin-guide/device-mapper/snapshot.rst b/Documentation/admin-guide/device-mapper/snapshot.rst
new file mode 100644
index 000000000000..ccdd8b587a74
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/snapshot.rst
@@ -0,0 +1,196 @@
+==============================
+Device-mapper snapshot support
+==============================
+
+Device-mapper allows you, without massive data copying:
+
+- To create snapshots of any block device i.e. mountable, saved states of
+ the block device which are also writable without interfering with the
+ original content;
+- To create device "forks", i.e. multiple different versions of the
+ same data stream.
+- To merge a snapshot of a block device back into the snapshot's origin
+ device.
+
+In the first two cases, dm copies only the chunks of data that get
+changed and uses a separate copy-on-write (COW) block device for
+storage.
+
+For snapshot merge the contents of the COW storage are merged back into
+the origin device.
+
+
+There are three dm targets available:
+snapshot, snapshot-origin, and snapshot-merge.
+
+- snapshot-origin <origin>
+
+which will normally have one or more snapshots based on it.
+Reads will be mapped directly to the backing device. For each write, the
+original data will be saved in the <COW device> of each snapshot to keep
+its visible content unchanged, at least until the <COW device> fills up.
+
+
+- snapshot <origin> <COW device> <persistent?> <chunksize>
+ [<# feature args> [<arg>]*]
+
+A snapshot of the <origin> block device is created. Changed chunks of
+<chunksize> sectors will be stored on the <COW device>. Writes will
+only go to the <COW device>. Reads will come from the <COW device> or
+from <origin> for unchanged data. <COW device> will often be
+smaller than the origin and if it fills up the snapshot will become
+useless and be disabled, returning errors. So it is important to monitor
+the amount of free space and expand the <COW device> before it fills up.
+
+<persistent?> is P (Persistent) or N (Not persistent - will not survive
+after reboot). O (Overflow) can be added as a persistent store option
+to allow userspace to advertise its support for seeing "Overflow" in the
+snapshot status. So supported store types are "P", "PO" and "N".
+
+The difference between persistent and transient is with transient
+snapshots less metadata must be saved on disk - they can be kept in
+memory by the kernel.
+
+When loading or unloading the snapshot target, the corresponding
+snapshot-origin or snapshot-merge target must be suspended. A failure to
+suspend the origin target could result in data corruption.
+
+Optional features:
+
+ discard_zeroes_cow - a discard issued to the snapshot device that
+ maps to entire chunks to will zero the corresponding exception(s) in
+ the snapshot's exception store.
+
+ discard_passdown_origin - a discard to the snapshot device is passed
+ down to the snapshot-origin's underlying device. This doesn't cause
+ copy-out to the snapshot exception store because the snapshot-origin
+ target is bypassed.
+
+ The discard_passdown_origin feature depends on the discard_zeroes_cow
+ feature being enabled.
+
+
+- snapshot-merge <origin> <COW device> <persistent> <chunksize>
+ [<# feature args> [<arg>]*]
+
+takes the same table arguments as the snapshot target except it only
+works with persistent snapshots. This target assumes the role of the
+"snapshot-origin" target and must not be loaded if the "snapshot-origin"
+is still present for <origin>.
+
+Creates a merging snapshot that takes control of the changed chunks
+stored in the <COW device> of an existing snapshot, through a handover
+procedure, and merges these chunks back into the <origin>. Once merging
+has started (in the background) the <origin> may be opened and the merge
+will continue while I/O is flowing to it. Changes to the <origin> are
+deferred until the merging snapshot's corresponding chunk(s) have been
+merged. Once merging has started the snapshot device, associated with
+the "snapshot" target, will return -EIO when accessed.
+
+
+How snapshot is used by LVM2
+============================
+When you create the first LVM2 snapshot of a volume, four dm devices are used:
+
+1) a device containing the original mapping table of the source volume;
+2) a device used as the <COW device>;
+3) a "snapshot" device, combining #1 and #2, which is the visible snapshot
+ volume;
+4) the "original" volume (which uses the device number used by the original
+ source volume), whose table is replaced by a "snapshot-origin" mapping
+ from device #1.
+
+A fixed naming scheme is used, so with the following commands::
+
+ lvcreate -L 1G -n base volumeGroup
+ lvcreate -L 100M --snapshot -n snap volumeGroup/base
+
+we'll have this situation (with volumes in above order)::
+
+ # dmsetup table|grep volumeGroup
+
+ volumeGroup-base-real: 0 2097152 linear 8:19 384
+ volumeGroup-snap-cow: 0 204800 linear 8:19 2097536
+ volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16
+ volumeGroup-base: 0 2097152 snapshot-origin 254:11
+
+ # ls -lL /dev/mapper/volumeGroup-*
+ brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
+ brw------- 1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow
+ brw------- 1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap
+ brw------- 1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base
+
+
+How snapshot-merge is used by LVM2
+==================================
+A merging snapshot assumes the role of the "snapshot-origin" while
+merging. As such the "snapshot-origin" is replaced with
+"snapshot-merge". The "-real" device is not changed and the "-cow"
+device is renamed to <origin name>-cow to aid LVM2's cleanup of the
+merging snapshot after it completes. The "snapshot" that hands over its
+COW device to the "snapshot-merge" is deactivated (unless using lvchange
+--refresh); but if it is left active it will simply return I/O errors.
+
+A snapshot will merge into its origin with the following command::
+
+ lvconvert --merge volumeGroup/snap
+
+we'll now have this situation::
+
+ # dmsetup table|grep volumeGroup
+
+ volumeGroup-base-real: 0 2097152 linear 8:19 384
+ volumeGroup-base-cow: 0 204800 linear 8:19 2097536
+ volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16
+
+ # ls -lL /dev/mapper/volumeGroup-*
+ brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
+ brw------- 1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow
+ brw------- 1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base
+
+
+How to determine when a merging is complete
+===========================================
+The snapshot-merge and snapshot status lines end with:
+
+ <sectors_allocated>/<total_sectors> <metadata_sectors>
+
+Both <sectors_allocated> and <total_sectors> include both data and metadata.
+During merging, the number of sectors allocated gets smaller and
+smaller. Merging has finished when the number of sectors holding data
+is zero, in other words <sectors_allocated> == <metadata_sectors>.
+
+Here is a practical example (using a hybrid of lvm and dmsetup commands)::
+
+ # lvs
+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
+ base volumeGroup owi-a- 4.00g
+ snap volumeGroup swi-a- 1.00g base 18.97
+
+ # dmsetup status volumeGroup-snap
+ 0 8388608 snapshot 397896/2097152 1560
+ ^^^^ metadata sectors
+
+ # lvconvert --merge -b volumeGroup/snap
+ Merging of volume snap started.
+
+ # lvs volumeGroup/snap
+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
+ base volumeGroup Owi-a- 4.00g 17.23
+
+ # dmsetup status volumeGroup-base
+ 0 8388608 snapshot-merge 281688/2097152 1104
+
+ # dmsetup status volumeGroup-base
+ 0 8388608 snapshot-merge 180480/2097152 712
+
+ # dmsetup status volumeGroup-base
+ 0 8388608 snapshot-merge 16/2097152 16
+
+Merging has finished.
+
+::
+
+ # lvs
+ LV VG Attr LSize Origin Snap% Move Log Copy% Convert
+ base volumeGroup owi-a- 4.00g
diff --git a/Documentation/admin-guide/device-mapper/statistics.rst b/Documentation/admin-guide/device-mapper/statistics.rst
new file mode 100644
index 000000000000..41ded0bc5933
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/statistics.rst
@@ -0,0 +1,225 @@
+=============
+DM statistics
+=============
+
+Device Mapper supports the collection of I/O statistics on user-defined
+regions of a DM device. If no regions are defined no statistics are
+collected so there isn't any performance impact. Only bio-based DM
+devices are currently supported.
+
+Each user-defined region specifies a starting sector, length and step.
+Individual statistics will be collected for each step-sized area within
+the range specified.
+
+The I/O statistics counters for each step-sized area of a region are
+in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
+Documentation/admin-guide/iostats.rst). But two extra counters (12 and 13) are
+provided: total time spent reading and writing. When the histogram
+argument is used, the 14th parameter is reported that represents the
+histogram of latencies. All these counters may be accessed by sending
+the @stats_print message to the appropriate DM device via dmsetup.
+
+The reported times are in milliseconds and the granularity depends on
+the kernel ticks. When the option precise_timestamps is used, the
+reported times are in nanoseconds.
+
+Each region has a corresponding unique identifier, which we call a
+region_id, that is assigned when the region is created. The region_id
+must be supplied when querying statistics about the region, deleting the
+region, etc. Unique region_ids enable multiple userspace programs to
+request and process statistics for the same DM device without stepping
+on each other's data.
+
+The creation of DM statistics will allocate memory via kmalloc or
+fallback to using vmalloc space. At most, 1/4 of the overall system
+memory may be allocated by DM statistics. The admin can see how much
+memory is used by reading:
+
+ /sys/module/dm_mod/parameters/stats_current_allocated_bytes
+
+Messages
+========
+
+ @stats_create <range> <step> [<number_of_optional_arguments> <optional_arguments>...] [<program_id> [<aux_data>]]
+ Create a new region and return the region_id.
+
+ <range>
+ "-"
+ whole device
+ "<start_sector>+<length>"
+ a range of <length> 512-byte sectors
+ starting with <start_sector>.
+
+ <step>
+ "<area_size>"
+ the range is subdivided into areas each containing
+ <area_size> sectors.
+ "/<number_of_areas>"
+ the range is subdivided into the specified
+ number of areas.
+
+ <number_of_optional_arguments>
+ The number of optional arguments
+
+ <optional_arguments>
+ The following optional arguments are supported:
+
+ precise_timestamps
+ use precise timer with nanosecond resolution
+ instead of the "jiffies" variable. When this argument is
+ used, the resulting times are in nanoseconds instead of
+ milliseconds. Precise timestamps are a little bit slower
+ to obtain than jiffies-based timestamps.
+ histogram:n1,n2,n3,n4,...
+ collect histogram of latencies. The
+ numbers n1, n2, etc are times that represent the boundaries
+ of the histogram. If precise_timestamps is not used, the
+ times are in milliseconds, otherwise they are in
+ nanoseconds. For each range, the kernel will report the
+ number of requests that completed within this range. For
+ example, if we use "histogram:10,20,30", the kernel will
+ report four numbers a:b:c:d. a is the number of requests
+ that took 0-10 ms to complete, b is the number of requests
+ that took 10-20 ms to complete, c is the number of requests
+ that took 20-30 ms to complete and d is the number of
+ requests that took more than 30 ms to complete.
+
+ <program_id>
+ An optional parameter. A name that uniquely identifies
+ the userspace owner of the range. This groups ranges together
+ so that userspace programs can identify the ranges they
+ created and ignore those created by others.
+ The kernel returns this string back in the output of
+ @stats_list message, but it doesn't use it for anything else.
+ If we omit the number of optional arguments, program id must not
+ be a number, otherwise it would be interpreted as the number of
+ optional arguments.
+
+ <aux_data>
+ An optional parameter. A word that provides auxiliary data
+ that is useful to the client program that created the range.
+ The kernel returns this string back in the output of
+ @stats_list message, but it doesn't use this value for anything.
+
+ @stats_delete <region_id>
+ Delete the region with the specified id.
+
+ <region_id>
+ region_id returned from @stats_create
+
+ @stats_clear <region_id>
+ Clear all the counters except the in-flight i/o counters.
+
+ <region_id>
+ region_id returned from @stats_create
+
+ @stats_list [<program_id>]
+ List all regions registered with @stats_create.
+
+ <program_id>
+ An optional parameter.
+ If this parameter is specified, only matching regions
+ are returned.
+ If it is not specified, all regions are returned.
+
+ Output format:
+ <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
+ precise_timestamps histogram:n1,n2,n3,...
+
+ The strings "precise_timestamps" and "histogram" are printed only
+ if they were specified when creating the region.
+
+ @stats_print <region_id> [<starting_line> <number_of_lines>]
+ Print counters for each step-sized area of a region.
+
+ <region_id>
+ region_id returned from @stats_create
+
+ <starting_line>
+ The index of the starting line in the output.
+ If omitted, all lines are returned.
+
+ <number_of_lines>
+ The number of lines to include in the output.
+ If omitted, all lines are returned.
+
+ Output format for each step-sized area of a region:
+
+ <start_sector>+<length>
+ counters
+
+ The first 11 counters have the same meaning as
+ `/sys/block/*/stat or /proc/diskstats`.
+
+ Please refer to Documentation/admin-guide/iostats.rst for details.
+
+ 1. the number of reads completed
+ 2. the number of reads merged
+ 3. the number of sectors read
+ 4. the number of milliseconds spent reading
+ 5. the number of writes completed
+ 6. the number of writes merged
+ 7. the number of sectors written
+ 8. the number of milliseconds spent writing
+ 9. the number of I/Os currently in progress
+ 10. the number of milliseconds spent doing I/Os
+ 11. the weighted number of milliseconds spent doing I/Os
+
+ Additional counters:
+
+ 12. the total time spent reading in milliseconds
+ 13. the total time spent writing in milliseconds
+
+ @stats_print_clear <region_id> [<starting_line> <number_of_lines>]
+ Atomically print and then clear all the counters except the
+ in-flight i/o counters. Useful when the client consuming the
+ statistics does not want to lose any statistics (those updated
+ between printing and clearing).
+
+ <region_id>
+ region_id returned from @stats_create
+
+ <starting_line>
+ The index of the starting line in the output.
+ If omitted, all lines are printed and then cleared.
+
+ <number_of_lines>
+ The number of lines to process.
+ If omitted, all lines are printed and then cleared.
+
+ @stats_set_aux <region_id> <aux_data>
+ Store auxiliary data aux_data for the specified region.
+
+ <region_id>
+ region_id returned from @stats_create
+
+ <aux_data>
+ The string that identifies data which is useful to the client
+ program that created the range. The kernel returns this
+ string back in the output of @stats_list message, but it
+ doesn't use this value for anything.
+
+Examples
+========
+
+Subdivide the DM device 'vol' into 100 pieces and start collecting
+statistics on them::
+
+ dmsetup message vol 0 @stats_create - /100
+
+Set the auxiliary data string to "foo bar baz" (the escape for each
+space must also be escaped, otherwise the shell will consume them)::
+
+ dmsetup message vol 0 @stats_set_aux 0 foo\\ bar\\ baz
+
+List the statistics::
+
+ dmsetup message vol 0 @stats_list
+
+Print the statistics::
+
+ dmsetup message vol 0 @stats_print 0
+
+Delete the statistics::
+
+ dmsetup message vol 0 @stats_delete 0
diff --git a/Documentation/admin-guide/device-mapper/striped.rst b/Documentation/admin-guide/device-mapper/striped.rst
new file mode 100644
index 000000000000..e9a8da192ae1
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/striped.rst
@@ -0,0 +1,61 @@
+=========
+dm-stripe
+=========
+
+Device-Mapper's "striped" target is used to create a striped (i.e. RAID-0)
+device across one or more underlying devices. Data is written in "chunks",
+with consecutive chunks rotating among the underlying devices. This can
+potentially provide improved I/O throughput by utilizing several physical
+devices in parallel.
+
+Parameters: <num devs> <chunk size> [<dev path> <offset>]+
+ <num devs>:
+ Number of underlying devices.
+ <chunk size>:
+ Size of each chunk of data. Must be at least as
+ large as the system's PAGE_SIZE.
+ <dev path>:
+ Full pathname to the underlying block-device, or a
+ "major:minor" device-number.
+ <offset>:
+ Starting sector within the device.
+
+One or more underlying devices can be specified. The striped device size must
+be a multiple of the chunk size multiplied by the number of underlying devices.
+
+
+Example scripts
+===============
+
+::
+
+ #!/usr/bin/perl -w
+ # Create a striped device across any number of underlying devices. The device
+ # will be called "stripe_dev" and have a chunk-size of 128k.
+
+ my $chunk_size = 128 * 2;
+ my $dev_name = "stripe_dev";
+ my $num_devs = @ARGV;
+ my @devs = @ARGV;
+ my ($min_dev_size, $stripe_dev_size, $i);
+
+ if (!$num_devs) {
+ die("Specify at least one device\n");
+ }
+
+ $min_dev_size = `blockdev --getsz $devs[0]`;
+ for ($i = 1; $i < $num_devs; $i++) {
+ my $this_size = `blockdev --getsz $devs[$i]`;
+ $min_dev_size = ($min_dev_size < $this_size) ?
+ $min_dev_size : $this_size;
+ }
+
+ $stripe_dev_size = $min_dev_size * $num_devs;
+ $stripe_dev_size -= $stripe_dev_size % ($chunk_size * $num_devs);
+
+ $table = "0 $stripe_dev_size striped $num_devs $chunk_size";
+ for ($i = 0; $i < $num_devs; $i++) {
+ $table .= " $devs[$i] 0";
+ }
+
+ `echo $table | dmsetup create $dev_name`;
diff --git a/Documentation/admin-guide/device-mapper/switch.rst b/Documentation/admin-guide/device-mapper/switch.rst
new file mode 100644
index 000000000000..7dde06be1a4f
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/switch.rst
@@ -0,0 +1,141 @@
+=========
+dm-switch
+=========
+
+The device-mapper switch target creates a device that supports an
+arbitrary mapping of fixed-size regions of I/O across a fixed set of
+paths. The path used for any specific region can be switched
+dynamically by sending the target a message.
+
+It maps I/O to underlying block devices efficiently when there is a large
+number of fixed-sized address regions but there is no simple pattern
+that would allow for a compact representation of the mapping such as
+dm-stripe.
+
+Background
+----------
+
+Dell EqualLogic and some other iSCSI storage arrays use a distributed
+frameless architecture. In this architecture, the storage group
+consists of a number of distinct storage arrays ("members") each having
+independent controllers, disk storage and network adapters. When a LUN
+is created it is spread across multiple members. The details of the
+spreading are hidden from initiators connected to this storage system.
+The storage group exposes a single target discovery portal, no matter
+how many members are being used. When iSCSI sessions are created, each
+session is connected to an eth port on a single member. Data to a LUN
+can be sent on any iSCSI session, and if the blocks being accessed are
+stored on another member the I/O will be forwarded as required. This
+forwarding is invisible to the initiator. The storage layout is also
+dynamic, and the blocks stored on disk may be moved from member to
+member as needed to balance the load.
+
+This architecture simplifies the management and configuration of both
+the storage group and initiators. In a multipathing configuration, it
+is possible to set up multiple iSCSI sessions to use multiple network
+interfaces on both the host and target to take advantage of the
+increased network bandwidth. An initiator could use a simple round
+robin algorithm to send I/O across all paths and let the storage array
+members forward it as necessary, but there is a performance advantage to
+sending data directly to the correct member.
+
+A device-mapper table already lets you map different regions of a
+device onto different targets. However in this architecture the LUN is
+spread with an address region size on the order of 10s of MBs, which
+means the resulting table could have more than a million entries and
+consume far too much memory.
+
+Using this device-mapper switch target we can now build a two-layer
+device hierarchy:
+
+ Upper Tier - Determine which array member the I/O should be sent to.
+ Lower Tier - Load balance amongst paths to a particular member.
+
+The lower tier consists of a single dm multipath device for each member.
+Each of these multipath devices contains the set of paths directly to
+the array member in one priority group, and leverages existing path
+selectors to load balance amongst these paths. We also build a
+non-preferred priority group containing paths to other array members for
+failover reasons.
+
+The upper tier consists of a single dm-switch device. This device uses
+a bitmap to look up the location of the I/O and choose the appropriate
+lower tier device to route the I/O. By using a bitmap we are able to
+use 4 bits for each address range in a 16 member group (which is very
+large for us). This is a much denser representation than the dm table
+b-tree can achieve.
+
+Construction Parameters
+=======================
+
+ <num_paths> <region_size> <num_optional_args> [<optional_args>...] [<dev_path> <offset>]+
+ <num_paths>
+ The number of paths across which to distribute the I/O.
+
+ <region_size>
+ The number of 512-byte sectors in a region. Each region can be redirected
+ to any of the available paths.
+
+ <num_optional_args>
+ The number of optional arguments. Currently, no optional arguments
+ are supported and so this must be zero.
+
+ <dev_path>
+ The block device that represents a specific path to the device.
+
+ <offset>
+ The offset of the start of data on the specific <dev_path> (in units
+ of 512-byte sectors). This number is added to the sector number when
+ forwarding the request to the specific path. Typically it is zero.
+
+Messages
+========
+
+set_region_mappings <index>:<path_nr> [<index>]:<path_nr> [<index>]:<path_nr>...
+
+Modify the region table by specifying which regions are redirected to
+which paths.
+
+<index>
+ The region number (region size was specified in constructor parameters).
+ If index is omitted, the next region (previous index + 1) is used.
+ Expressed in hexadecimal (WITHOUT any prefix like 0x).
+
+<path_nr>
+ The path number in the range 0 ... (<num_paths> - 1).
+ Expressed in hexadecimal (WITHOUT any prefix like 0x).
+
+R<n>,<m>
+ This parameter allows repetitive patterns to be loaded quickly. <n> and <m>
+ are hexadecimal numbers. The last <n> mappings are repeated in the next <m>
+ slots.
+
+Status
+======
+
+No status line is reported.
+
+Example
+=======
+
+Assume that you have volumes vg1/switch0 vg1/switch1 vg1/switch2 with
+the same size.
+
+Create a switch device with 64kB region size::
+
+ dmsetup create switch --table "0 `blockdev --getsz /dev/vg1/switch0`
+ switch 3 128 0 /dev/vg1/switch0 0 /dev/vg1/switch1 0 /dev/vg1/switch2 0"
+
+Set mappings for the first 7 entries to point to devices switch0, switch1,
+switch2, switch0, switch1, switch2, switch1::
+
+ dmsetup message switch 0 set_region_mappings 0:0 :1 :2 :0 :1 :2 :1
+
+Set repetitive mapping. This command::
+
+ dmsetup message switch 0 set_region_mappings 1000:1 :2 R2,10
+
+is equivalent to::
+
+ dmsetup message switch 0 set_region_mappings 1000:1 :2 :1 :2 :1 :2 :1 :2 \
+ :1 :2 :1 :2 :1 :2 :1 :2 :1 :2
diff --git a/Documentation/admin-guide/device-mapper/thin-provisioning.rst b/Documentation/admin-guide/device-mapper/thin-provisioning.rst
new file mode 100644
index 000000000000..b2fa49a5608a
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/thin-provisioning.rst
@@ -0,0 +1,427 @@
+=================
+Thin provisioning
+=================
+
+Introduction
+============
+
+This document describes a collection of device-mapper targets that
+between them implement thin-provisioning and snapshots.
+
+The main highlight of this implementation, compared to the previous
+implementation of snapshots, is that it allows many virtual devices to
+be stored on the same data volume. This simplifies administration and
+allows the sharing of data between volumes, thus reducing disk usage.
+
+Another significant feature is support for an arbitrary depth of
+recursive snapshots (snapshots of snapshots of snapshots ...). The
+previous implementation of snapshots did this by chaining together
+lookup tables, and so performance was O(depth). This new
+implementation uses a single data structure to avoid this degradation
+with depth. Fragmentation may still be an issue, however, in some
+scenarios.
+
+Metadata is stored on a separate device from data, giving the
+administrator some freedom, for example to:
+
+- Improve metadata resilience by storing metadata on a mirrored volume
+ but data on a non-mirrored one.
+
+- Improve performance by storing the metadata on SSD.
+
+Status
+======
+
+These targets are considered safe for production use. But different use
+cases will have different performance characteristics, for example due
+to fragmentation of the data volume.
+
+If you find this software is not performing as expected please mail
+dm-devel@redhat.com with details and we'll try our best to improve
+things for you.
+
+Userspace tools for checking and repairing the metadata have been fully
+developed and are available as 'thin_check' and 'thin_repair'. The name
+of the package that provides these utilities varies by distribution (on
+a Red Hat distribution it is named 'device-mapper-persistent-data').
+
+Cookbook
+========
+
+This section describes some quick recipes for using thin provisioning.
+They use the dmsetup program to control the device-mapper driver
+directly. End users will be advised to use a higher-level volume
+manager such as LVM2 once support has been added.
+
+Pool device
+-----------
+
+The pool device ties together the metadata volume and the data volume.
+It maps I/O linearly to the data volume and updates the metadata via
+two mechanisms:
+
+- Function calls from the thin targets
+
+- Device-mapper 'messages' from userspace which control the creation of new
+ virtual devices amongst other things.
+
+Setting up a fresh pool device
+------------------------------
+
+Setting up a pool device requires a valid metadata device, and a
+data device. If you do not have an existing metadata device you can
+make one by zeroing the first 4k to indicate empty metadata.
+
+ dd if=/dev/zero of=$metadata_dev bs=4096 count=1
+
+The amount of metadata you need will vary according to how many blocks
+are shared between thin devices (i.e. through snapshots). If you have
+less sharing than average you'll need a larger-than-average metadata device.
+
+As a guide, we suggest you calculate the number of bytes to use in the
+metadata device as 48 * $data_dev_size / $data_block_size but round it up
+to 2MiB if the answer is smaller. If you're creating large numbers of
+snapshots which are recording large amounts of change, you may find you
+need to increase this.
+
+The largest size supported is 16GiB: If the device is larger,
+a warning will be issued and the excess space will not be used.
+
+Reloading a pool table
+----------------------
+
+You may reload a pool's table, indeed this is how the pool is resized
+if it runs out of space. (N.B. While specifying a different metadata
+device when reloading is not forbidden at the moment, things will go
+wrong if it does not route I/O to exactly the same on-disk location as
+previously.)
+
+Using an existing pool device
+-----------------------------
+
+::
+
+ dmsetup create pool \
+ --table "0 20971520 thin-pool $metadata_dev $data_dev \
+ $data_block_size $low_water_mark"
+
+$data_block_size gives the smallest unit of disk space that can be
+allocated at a time expressed in units of 512-byte sectors.
+$data_block_size must be between 128 (64KiB) and 2097152 (1GiB) and a
+multiple of 128 (64KiB). $data_block_size cannot be changed after the
+thin-pool is created. People primarily interested in thin provisioning
+may want to use a value such as 1024 (512KiB). People doing lots of
+snapshotting may want a smaller value such as 128 (64KiB). If you are
+not zeroing newly-allocated data, a larger $data_block_size in the
+region of 262144 (128MiB) is suggested.
+
+$low_water_mark is expressed in blocks of size $data_block_size. If
+free space on the data device drops below this level then a dm event
+will be triggered which a userspace daemon should catch allowing it to
+extend the pool device. Only one such event will be sent.
+
+No special event is triggered if a just resumed device's free space is below
+the low water mark. However, resuming a device always triggers an
+event; a userspace daemon should verify that free space exceeds the low
+water mark when handling this event.
+
+A low water mark for the metadata device is maintained in the kernel and
+will trigger a dm event if free space on the metadata device drops below
+it.
+
+Updating on-disk metadata
+-------------------------
+
+On-disk metadata is committed every time a FLUSH or FUA bio is written.
+If no such requests are made then commits will occur every second. This
+means the thin-provisioning target behaves like a physical disk that has
+a volatile write cache. If power is lost you may lose some recent
+writes. The metadata should always be consistent in spite of any crash.
+
+If data space is exhausted the pool will either error or queue IO
+according to the configuration (see: error_if_no_space). If metadata
+space is exhausted or a metadata operation fails: the pool will error IO
+until the pool is taken offline and repair is performed to 1) fix any
+potential inconsistencies and 2) clear the flag that imposes repair.
+Once the pool's metadata device is repaired it may be resized, which
+will allow the pool to return to normal operation. Note that if a pool
+is flagged as needing repair, the pool's data and metadata devices
+cannot be resized until repair is performed. It should also be noted
+that when the pool's metadata space is exhausted the current metadata
+transaction is aborted. Given that the pool will cache IO whose
+completion may have already been acknowledged to upper IO layers
+(e.g. filesystem) it is strongly suggested that consistency checks
+(e.g. fsck) be performed on those layers when repair of the pool is
+required.
+
+Thin provisioning
+-----------------
+
+i) Creating a new thinly-provisioned volume.
+
+ To create a new thinly- provisioned volume you must send a message to an
+ active pool device, /dev/mapper/pool in this example::
+
+ dmsetup message /dev/mapper/pool 0 "create_thin 0"
+
+ Here '0' is an identifier for the volume, a 24-bit number. It's up
+ to the caller to allocate and manage these identifiers. If the
+ identifier is already in use, the message will fail with -EEXIST.
+
+ii) Using a thinly-provisioned volume.
+
+ Thinly-provisioned volumes are activated using the 'thin' target::
+
+ dmsetup create thin --table "0 2097152 thin /dev/mapper/pool 0"
+
+ The last parameter is the identifier for the thinp device.
+
+Internal snapshots
+------------------
+
+i) Creating an internal snapshot.
+
+ Snapshots are created with another message to the pool.
+
+ N.B. If the origin device that you wish to snapshot is active, you
+ must suspend it before creating the snapshot to avoid corruption.
+ This is NOT enforced at the moment, so please be careful!
+
+ ::
+
+ dmsetup suspend /dev/mapper/thin
+ dmsetup message /dev/mapper/pool 0 "create_snap 1 0"
+ dmsetup resume /dev/mapper/thin
+
+ Here '1' is the identifier for the volume, a 24-bit number. '0' is the
+ identifier for the origin device.
+
+ii) Using an internal snapshot.
+
+ Once created, the user doesn't have to worry about any connection
+ between the origin and the snapshot. Indeed the snapshot is no
+ different from any other thinly-provisioned device and can be
+ snapshotted itself via the same method. It's perfectly legal to
+ have only one of them active, and there's no ordering requirement on
+ activating or removing them both. (This differs from conventional
+ device-mapper snapshots.)
+
+ Activate it exactly the same way as any other thinly-provisioned volume::
+
+ dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 1"
+
+External snapshots
+------------------
+
+You can use an external **read only** device as an origin for a
+thinly-provisioned volume. Any read to an unprovisioned area of the
+thin device will be passed through to the origin. Writes trigger
+the allocation of new blocks as usual.
+
+One use case for this is VM hosts that want to run guests on
+thinly-provisioned volumes but have the base image on another device
+(possibly shared between many VMs).
+
+You must not write to the origin device if you use this technique!
+Of course, you may write to the thin device and take internal snapshots
+of the thin volume.
+
+i) Creating a snapshot of an external device
+
+ This is the same as creating a thin device.
+ You don't mention the origin at this stage.
+
+ ::
+
+ dmsetup message /dev/mapper/pool 0 "create_thin 0"
+
+ii) Using a snapshot of an external device.
+
+ Append an extra parameter to the thin target specifying the origin::
+
+ dmsetup create snap --table "0 2097152 thin /dev/mapper/pool 0 /dev/image"
+
+ N.B. All descendants (internal snapshots) of this snapshot require the
+ same extra origin parameter.
+
+Deactivation
+------------
+
+All devices using a pool must be deactivated before the pool itself
+can be.
+
+::
+
+ dmsetup remove thin
+ dmsetup remove snap
+ dmsetup remove pool
+
+Reference
+=========
+
+'thin-pool' target
+------------------
+
+i) Constructor
+
+ ::
+
+ thin-pool <metadata dev> <data dev> <data block size (sectors)> \
+ <low water mark (blocks)> [<number of feature args> [<arg>]*]
+
+ Optional feature arguments:
+
+ skip_block_zeroing:
+ Skip the zeroing of newly-provisioned blocks.
+
+ ignore_discard:
+ Disable discard support.
+
+ no_discard_passdown:
+ Don't pass discards down to the underlying
+ data device, but just remove the mapping.
+
+ read_only:
+ Don't allow any changes to be made to the pool
+ metadata. This mode is only available after the
+ thin-pool has been created and first used in full
+ read/write mode. It cannot be specified on initial
+ thin-pool creation.
+
+ error_if_no_space:
+ Error IOs, instead of queueing, if no space.
+
+ Data block size must be between 64KiB (128 sectors) and 1GiB
+ (2097152 sectors) inclusive.
+
+
+ii) Status
+
+ ::
+
+ <transaction id> <used metadata blocks>/<total metadata blocks>
+ <used data blocks>/<total data blocks> <held metadata root>
+ ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space
+ needs_check|- metadata_low_watermark
+
+ transaction id:
+ A 64-bit number used by userspace to help synchronise with metadata
+ from volume managers.
+
+ used data blocks / total data blocks
+ If the number of free blocks drops below the pool's low water mark a
+ dm event will be sent to userspace. This event is edge-triggered and
+ it will occur only once after each resume so volume manager writers
+ should register for the event and then check the target's status.
+
+ held metadata root:
+ The location, in blocks, of the metadata root that has been
+ 'held' for userspace read access. '-' indicates there is no
+ held root.
+
+ discard_passdown|no_discard_passdown
+ Whether or not discards are actually being passed down to the
+ underlying device. When this is enabled when loading the table,
+ it can get disabled if the underlying device doesn't support it.
+
+ ro|rw|out_of_data_space
+ If the pool encounters certain types of device failures it will
+ drop into a read-only metadata mode in which no changes to
+ the pool metadata (like allocating new blocks) are permitted.
+
+ In serious cases where even a read-only mode is deemed unsafe
+ no further I/O will be permitted and the status will just
+ contain the string 'Fail'. The userspace recovery tools
+ should then be used.
+
+ error_if_no_space|queue_if_no_space
+ If the pool runs out of data or metadata space, the pool will
+ either queue or error the IO destined to the data device. The
+ default is to queue the IO until more space is added or the
+ 'no_space_timeout' expires. The 'no_space_timeout' dm-thin-pool
+ module parameter can be used to change this timeout -- it
+ defaults to 60 seconds but may be disabled using a value of 0.
+
+ needs_check
+ A metadata operation has failed, resulting in the needs_check
+ flag being set in the metadata's superblock. The metadata
+ device must be deactivated and checked/repaired before the
+ thin-pool can be made fully operational again. '-' indicates
+ needs_check is not set.
+
+ metadata_low_watermark:
+ Value of metadata low watermark in blocks. The kernel sets this
+ value internally but userspace needs to know this value to
+ determine if an event was caused by crossing this threshold.
+
+iii) Messages
+
+ create_thin <dev id>
+ Create a new thinly-provisioned device.
+ <dev id> is an arbitrary unique 24-bit identifier chosen by
+ the caller.
+
+ create_snap <dev id> <origin id>
+ Create a new snapshot of another thinly-provisioned device.
+ <dev id> is an arbitrary unique 24-bit identifier chosen by
+ the caller.
+ <origin id> is the identifier of the thinly-provisioned device
+ of which the new device will be a snapshot.
+
+ delete <dev id>
+ Deletes a thin device. Irreversible.
+
+ set_transaction_id <current id> <new id>
+ Userland volume managers, such as LVM, need a way to
+ synchronise their external metadata with the internal metadata of the
+ pool target. The thin-pool target offers to store an
+ arbitrary 64-bit transaction id and return it on the target's
+ status line. To avoid races you must provide what you think
+ the current transaction id is when you change it with this
+ compare-and-swap message.
+
+ reserve_metadata_snap
+ Reserve a copy of the data mapping btree for use by userland.
+ This allows userland to inspect the mappings as they were when
+ this message was executed. Use the pool's status command to
+ get the root block associated with the metadata snapshot.
+
+ release_metadata_snap
+ Release a previously reserved copy of the data mapping btree.
+
+'thin' target
+-------------
+
+i) Constructor
+
+ ::
+
+ thin <pool dev> <dev id> [<external origin dev>]
+
+ pool dev:
+ the thin-pool device, e.g. /dev/mapper/my_pool or 253:0
+
+ dev id:
+ the internal device identifier of the device to be
+ activated.
+
+ external origin dev:
+ an optional block device outside the pool to be treated as a
+ read-only snapshot origin: reads to unprovisioned areas of the
+ thin target will be mapped to this device.
+
+The pool doesn't store any size against the thin devices. If you
+load a thin target that is smaller than you've been using previously,
+then you'll have no access to blocks mapped beyond the end. If you
+load a target that is bigger than before, then extra blocks will be
+provisioned as and when needed.
+
+ii) Status
+
+ <nr mapped sectors> <highest mapped sector>
+ If the pool has encountered device errors and failed, the status
+ will just contain the string 'Fail'. The userspace recovery
+ tools should then be used.
+
+ In the case where <nr mapped sectors> is 0, there is no highest
+ mapped sector and the value of <highest mapped sector> is unspecified.
diff --git a/Documentation/admin-guide/device-mapper/unstriped.rst b/Documentation/admin-guide/device-mapper/unstriped.rst
new file mode 100644
index 000000000000..5772ccdd1f5f
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/unstriped.rst
@@ -0,0 +1,135 @@
+================================
+Device-mapper "unstriped" target
+================================
+
+Introduction
+============
+
+The device-mapper "unstriped" target provides a transparent mechanism to
+unstripe a device-mapper "striped" target to access the underlying disks
+without having to touch the true backing block-device. It can also be
+used to unstripe a hardware RAID-0 to access backing disks.
+
+Parameters:
+<number of stripes> <chunk size> <stripe #> <dev_path> <offset>
+
+<number of stripes>
+ The number of stripes in the RAID 0.
+
+<chunk size>
+ The amount of 512B sectors in the chunk striping.
+
+<dev_path>
+ The block device you wish to unstripe.
+
+<stripe #>
+ The stripe number within the device that corresponds to physical
+ drive you wish to unstripe. This must be 0 indexed.
+
+
+Why use this module?
+====================
+
+An example of undoing an existing dm-stripe
+-------------------------------------------
+
+This small bash script will setup 4 loop devices and use the existing
+striped target to combine the 4 devices into one. It then will use
+the unstriped target on top of the striped device to access the
+individual backing loop devices. We write data to the newly exposed
+unstriped devices and verify the data written matches the correct
+underlying device on the striped array::
+
+ #!/bin/bash
+
+ MEMBER_SIZE=$((128 * 1024 * 1024))
+ NUM=4
+ SEQ_END=$((${NUM}-1))
+ CHUNK=256
+ BS=4096
+
+ RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512))
+ DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}"
+ COUNT=$((${MEMBER_SIZE} / ${BS}))
+
+ for i in $(seq 0 ${SEQ_END}); do
+ dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct
+ losetup /dev/loop${i} member-${i}
+ DM_PARMS+=" /dev/loop${i} 0"
+ done
+
+ echo $DM_PARMS | dmsetup create raid0
+ for i in $(seq 0 ${SEQ_END}); do
+ echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i}
+ done;
+
+ for i in $(seq 0 ${SEQ_END}); do
+ dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct
+ diff /dev/mapper/set-${i} member-${i}
+ done;
+
+ for i in $(seq 0 ${SEQ_END}); do
+ dmsetup remove set-${i}
+ done
+
+ dmsetup remove raid0
+
+ for i in $(seq 0 ${SEQ_END}); do
+ losetup -d /dev/loop${i}
+ rm -f member-${i}
+ done
+
+Another example
+---------------
+
+Intel NVMe drives contain two cores on the physical device.
+Each core of the drive has segregated access to its LBA range.
+The current LBA model has a RAID 0 128k chunk on each core, resulting
+in a 256k stripe across the two cores::
+
+ Core 0: Core 1:
+ __________ __________
+ | LBA 512| | LBA 768|
+ | LBA 0 | | LBA 256|
+ ---------- ----------
+
+The purpose of this unstriping is to provide better QoS in noisy
+neighbor environments. When two partitions are created on the
+aggregate drive without this unstriping, reads on one partition
+can affect writes on another partition. This is because the partitions
+are striped across the two cores. When we unstripe this hardware RAID 0
+and make partitions on each new exposed device the two partitions are now
+physically separated.
+
+With the dm-unstriped target we're able to segregate an fio script that
+has read and write jobs that are independent of each other. Compared to
+when we run the test on a combined drive with partitions, we were able
+to get a 92% reduction in read latency using this device mapper target.
+
+
+Example dmsetup usage
+=====================
+
+unstriped on top of Intel NVMe device that has 2 cores
+------------------------------------------------------
+
+::
+
+ dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0'
+ dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0'
+
+There will now be two devices that expose Intel NVMe core 0 and 1
+respectively::
+
+ /dev/mapper/nvmset0
+ /dev/mapper/nvmset1
+
+unstriped on top of striped with 4 drives using 128K chunk size
+---------------------------------------------------------------
+
+::
+
+ dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0'
+ dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0'
+ dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0'
+ dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0'
diff --git a/Documentation/admin-guide/device-mapper/vdo-design.rst b/Documentation/admin-guide/device-mapper/vdo-design.rst
new file mode 100644
index 000000000000..faa0ecd4a5ae
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/vdo-design.rst
@@ -0,0 +1,633 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+================
+Design of dm-vdo
+================
+
+The dm-vdo (virtual data optimizer) target provides inline deduplication,
+compression, zero-block elimination, and thin provisioning. A dm-vdo target
+can be backed by up to 256TB of storage, and can present a logical size of
+up to 4PB. This target was originally developed at Permabit Technology
+Corp. starting in 2009. It was first released in 2013 and has been used in
+production environments ever since. It was made open-source in 2017 after
+Permabit was acquired by Red Hat. This document describes the design of
+dm-vdo. For usage, see vdo.rst in the same directory as this file.
+
+Because deduplication rates fall drastically as the block size increases, a
+vdo target has a maximum block size of 4K. However, it can achieve
+deduplication rates of 254:1, i.e. up to 254 copies of a given 4K block can
+reference a single 4K of actual storage. It can achieve compression rates
+of 14:1. All zero blocks consume no storage at all.
+
+Theory of Operation
+===================
+
+The design of dm-vdo is based on the idea that deduplication is a two-part
+problem. The first is to recognize duplicate data. The second is to avoid
+storing multiple copies of those duplicates. Therefore, dm-vdo has two main
+parts: a deduplication index (called UDS) that is used to discover
+duplicate data, and a data store with a reference counted block map that
+maps from logical block addresses to the actual storage location of the
+data.
+
+Zones and Threading
+-------------------
+
+Due to the complexity of data optimization, the number of metadata
+structures involved in a single write operation to a vdo target is larger
+than most other targets. Furthermore, because vdo must operate on small
+block sizes in order to achieve good deduplication rates, acceptable
+performance can only be achieved through parallelism. Therefore, vdo's
+design attempts to be lock-free.
+
+Most of a vdo's main data structures are designed to be easily divided into
+"zones" such that any given bio must only access a single zone of any zoned
+structure. Safety with minimal locking is achieved by ensuring that during
+normal operation, each zone is assigned to a specific thread, and only that
+thread will access the portion of the data structure in that zone.
+Associated with each thread is a work queue. Each bio is associated with a
+request object (the "data_vio") which will be added to a work queue when
+the next phase of its operation requires access to the structures in the
+zone associated with that queue.
+
+Another way of thinking about this arrangement is that the work queue for
+each zone has an implicit lock on the structures it manages for all its
+operations, because vdo guarantees that no other thread will alter those
+structures.
+
+Although each structure is divided into zones, this division is not
+reflected in the on-disk representation of each data structure. Therefore,
+the number of zones for each structure, and hence the number of threads,
+can be reconfigured each time a vdo target is started.
+
+The Deduplication Index
+-----------------------
+
+In order to identify duplicate data efficiently, vdo was designed to
+leverage some common characteristics of duplicate data. From empirical
+observations, we gathered two key insights. The first is that in most data
+sets with significant amounts of duplicate data, the duplicates tend to
+have temporal locality. When a duplicate appears, it is more likely that
+other duplicates will be detected, and that those duplicates will have been
+written at about the same time. This is why the index keeps records in
+temporal order. The second insight is that new data is more likely to
+duplicate recent data than it is to duplicate older data and in general,
+there are diminishing returns to looking further back in time. Therefore,
+when the index is full, it should cull its oldest records to make space for
+new ones. Another important idea behind the design of the index is that the
+ultimate goal of deduplication is to reduce storage costs. Since there is a
+trade-off between the storage saved and the resources expended to achieve
+those savings, vdo does not attempt to find every last duplicate block. It
+is sufficient to find and eliminate most of the redundancy.
+
+Each block of data is hashed to produce a 16-byte block name. An index
+record consists of this block name paired with the presumed location of
+that data on the underlying storage. However, it is not possible to
+guarantee that the index is accurate. In the most common case, this occurs
+because it is too costly to update the index when a block is over-written
+or discarded. Doing so would require either storing the block name along
+with the blocks, which is difficult to do efficiently in block-based
+storage, or reading and rehashing each block before overwriting it.
+Inaccuracy can also result from a hash collision where two different blocks
+have the same name. In practice, this is extremely unlikely, but because
+vdo does not use a cryptographic hash, a malicious workload could be
+constructed. Because of these inaccuracies, vdo treats the locations in the
+index as hints, and reads each indicated block to verify that it is indeed
+a duplicate before sharing the existing block with a new one.
+
+Records are collected into groups called chapters. New records are added to
+the newest chapter, called the open chapter. This chapter is stored in a
+format optimized for adding and modifying records, and the content of the
+open chapter is not finalized until it runs out of space for new records.
+When the open chapter fills up, it is closed and a new open chapter is
+created to collect new records.
+
+Closing a chapter converts it to a different format which is optimized for
+reading. The records are written to a series of record pages based on the
+order in which they were received. This means that records with temporal
+locality should be on a small number of pages, reducing the I/O required to
+retrieve them. The chapter also compiles an index that indicates which
+record page contains any given name. This index means that a request for a
+name can determine exactly which record page may contain that record,
+without having to load the entire chapter from storage. This index uses
+only a subset of the block name as its key, so it cannot guarantee that an
+index entry refers to the desired block name. It can only guarantee that if
+there is a record for this name, it will be on the indicated page. Closed
+chapters are read-only structures and their contents are never altered in
+any way.
+
+Once enough records have been written to fill up all the available index
+space, the oldest chapter is removed to make space for new chapters. Any
+time a request finds a matching record in the index, that record is copied
+into the open chapter. This ensures that useful block names remain available
+in the index, while unreferenced block names are forgotten over time.
+
+In order to find records in older chapters, the index also maintains a
+higher level structure called the volume index, which contains entries
+mapping each block name to the chapter containing its newest record. This
+mapping is updated as records for the block name are copied or updated,
+ensuring that only the newest record for a given block name can be found.
+An older record for a block name will no longer be found even though it has
+not been deleted from its chapter. Like the chapter index, the volume index
+uses only a subset of the block name as its key and can not definitively
+say that a record exists for a name. It can only say which chapter would
+contain the record if a record exists. The volume index is stored entirely
+in memory and is saved to storage only when the vdo target is shut down.
+
+From the viewpoint of a request for a particular block name, it will first
+look up the name in the volume index. This search will either indicate that
+the name is new, or which chapter to search. If it returns a chapter, the
+request looks up its name in the chapter index. This will indicate either
+that the name is new, or which record page to search. Finally, if it is not
+new, the request will look for its name in the indicated record page.
+This process may require up to two page reads per request (one for the
+chapter index page and one for the request page). However, recently
+accessed pages are cached so that these page reads can be amortized across
+many block name requests.
+
+The volume index and the chapter indexes are implemented using a
+memory-efficient structure called a delta index. Instead of storing the
+entire block name (the key) for each entry, the entries are sorted by name
+and only the difference between adjacent keys (the delta) is stored.
+Because we expect the hashes to be randomly distributed, the size of the
+deltas follows an exponential distribution. Because of this distribution,
+the deltas are expressed using a Huffman code to take up even less space.
+The entire sorted list of keys is called a delta list. This structure
+allows the index to use many fewer bytes per entry than a traditional hash
+table, but it is slightly more expensive to look up entries, because a
+request must read every entry in a delta list to add up the deltas in order
+to find the record it needs. The delta index reduces this lookup cost by
+splitting its key space into many sub-lists, each starting at a fixed key
+value, so that each individual list is short.
+
+The default index size can hold 64 million records, corresponding to about
+256GB of data. This means that the index can identify duplicate data if the
+original data was written within the last 256GB of writes. This range is
+called the deduplication window. If new writes duplicate data that is older
+than that, the index will not be able to find it because the records of the
+older data have been removed. This means that if an application writes a
+200 GB file to a vdo target and then immediately writes it again, the two
+copies will deduplicate perfectly. Doing the same with a 500 GB file will
+result in no deduplication, because the beginning of the file will no
+longer be in the index by the time the second write begins (assuming there
+is no duplication within the file itself).
+
+If an application anticipates a data workload that will see useful
+deduplication beyond the 256GB threshold, vdo can be configured to use a
+larger index with a correspondingly larger deduplication window. (This
+configuration can only be set when the target is created, not altered
+later. It is important to consider the expected workload for a vdo target
+before configuring it.) There are two ways to do this.
+
+One way is to increase the memory size of the index, which also increases
+the amount of backing storage required. Doubling the size of the index will
+double the length of the deduplication window at the expense of doubling
+the storage size and the memory requirements.
+
+The other option is to enable sparse indexing. Sparse indexing increases
+the deduplication window by a factor of 10, at the expense of also
+increasing the storage size by a factor of 10. However with sparse
+indexing, the memory requirements do not increase. The trade-off is
+slightly more computation per request and a slight decrease in the amount
+of deduplication detected. For most workloads with significant amounts of
+duplicate data, sparse indexing will detect 97-99% of the deduplication
+that a standard index will detect.
+
+The vio and data_vio Structures
+-------------------------------
+
+A vio (short for Vdo I/O) is conceptually similar to a bio, with additional
+fields and data to track vdo-specific information. A struct vio maintains a
+pointer to a bio but also tracks other fields specific to the operation of
+vdo. The vio is kept separate from its related bio because there are many
+circumstances where vdo completes the bio but must continue to do work
+related to deduplication or compression.
+
+Metadata reads and writes, and other writes that originate within vdo, use
+a struct vio directly. Application reads and writes use a larger structure
+called a data_vio to track information about their progress. A struct
+data_vio contain a struct vio and also includes several other fields
+related to deduplication and other vdo features. The data_vio is the
+primary unit of application work in vdo. Each data_vio proceeds through a
+set of steps to handle the application data, after which it is reset and
+returned to a pool of data_vios for reuse.
+
+There is a fixed pool of 2048 data_vios. This number was chosen to bound
+the amount of work that is required to recover from a crash. In addition,
+benchmarks have indicated that increasing the size of the pool does not
+significantly improve performance.
+
+The Data Store
+--------------
+
+The data store is implemented by three main data structures, all of which
+work in concert to reduce or amortize metadata updates across as many data
+writes as possible.
+
+*The Slab Depot*
+
+Most of the vdo volume belongs to the slab depot. The depot contains a
+collection of slabs. The slabs can be up to 32GB, and are divided into
+three sections. Most of a slab consists of a linear sequence of 4K blocks.
+These blocks are used either to store data, or to hold portions of the
+block map (see below). In addition to the data blocks, each slab has a set
+of reference counters, using 1 byte for each data block. Finally each slab
+has a journal.
+
+Reference updates are written to the slab journal. Slab journal blocks are
+written out either when they are full, or when the recovery journal
+requests they do so in order to allow the main recovery journal (see below)
+to free up space. The slab journal is used both to ensure that the main
+recovery journal can regularly free up space, and also to amortize the cost
+of updating individual reference blocks. The reference counters are kept in
+memory and are written out, a block at a time in oldest-dirtied-order, only
+when there is a need to reclaim slab journal space. The write operations
+are performed in the background as needed so they do not add latency to
+particular I/O operations.
+
+Each slab is independent of every other. They are assigned to "physical
+zones" in round-robin fashion. If there are P physical zones, then slab n
+is assigned to zone n mod P.
+
+The slab depot maintains an additional small data structure, the "slab
+summary," which is used to reduce the amount of work needed to come back
+online after a crash. The slab summary maintains an entry for each slab
+indicating whether or not the slab has ever been used, whether all of its
+reference count updates have been persisted to storage, and approximately
+how full it is. During recovery, each physical zone will attempt to recover
+at least one slab, stopping whenever it has recovered a slab which has some
+free blocks. Once each zone has some space, or has determined that none is
+available, the target can resume normal operation in a degraded mode. Read
+and write requests can be serviced, perhaps with degraded performance,
+while the remainder of the dirty slabs are recovered.
+
+*The Block Map*
+
+The block map contains the logical to physical mapping. It can be thought
+of as an array with one entry per logical address. Each entry is 5 bytes,
+36 bits of which contain the physical block number which holds the data for
+the given logical address. The other 4 bits are used to indicate the nature
+of the mapping. Of the 16 possible states, one represents a logical address
+which is unmapped (i.e. it has never been written, or has been discarded),
+one represents an uncompressed block, and the other 14 states are used to
+indicate that the mapped data is compressed, and which of the compression
+slots in the compressed block contains the data for this logical address.
+
+In practice, the array of mapping entries is divided into "block map
+pages," each of which fits in a single 4K block. Each block map page
+consists of a header and 812 mapping entries. Each mapping page is actually
+a leaf of a radix tree which consists of block map pages at each level.
+There are 60 radix trees which are assigned to "logical zones" in round
+robin fashion. (If there are L logical zones, tree n will belong to zone n
+mod L.) At each level, the trees are interleaved, so logical addresses
+0-811 belong to tree 0, logical addresses 812-1623 belong to tree 1, and so
+on. The interleaving is maintained all the way up to the 60 root nodes.
+Choosing 60 trees results in an evenly distributed number of trees per zone
+for a large number of possible logical zone counts. The storage for the 60
+tree roots is allocated at format time. All other block map pages are
+allocated out of the slabs as needed. This flexible allocation avoids the
+need to pre-allocate space for the entire set of logical mappings and also
+makes growing the logical size of a vdo relatively easy.
+
+In operation, the block map maintains two caches. It is prohibitive to keep
+the entire leaf level of the trees in memory, so each logical zone
+maintains its own cache of leaf pages. The size of this cache is
+configurable at target start time. The second cache is allocated at start
+time, and is large enough to hold all the non-leaf pages of the entire
+block map. This cache is populated as pages are needed.
+
+*The Recovery Journal*
+
+The recovery journal is used to amortize updates across the block map and
+slab depot. Each write request causes an entry to be made in the journal.
+Entries are either "data remappings" or "block map remappings." For a data
+remapping, the journal records the logical address affected and its old and
+new physical mappings. For a block map remapping, the journal records the
+block map page number and the physical block allocated for it. Block map
+pages are never reclaimed or repurposed, so the old mapping is always 0.
+
+Each journal entry is an intent record summarizing the metadata updates
+that are required for a data_vio. The recovery journal issues a flush
+before each journal block write to ensure that the physical data for the
+new block mappings in that block are stable on storage, and journal block
+writes are all issued with the FUA bit set to ensure the recovery journal
+entries themselves are stable. The journal entry and the data write it
+represents must be stable on disk before the other metadata structures may
+be updated to reflect the operation. These entries allow the vdo device to
+reconstruct the logical to physical mappings after an unexpected
+interruption such as a loss of power.
+
+*Write Path*
+
+All write I/O to vdo is asynchronous. Each bio will be acknowledged as soon
+as vdo has done enough work to guarantee that it can complete the write
+eventually. Generally, the data for acknowledged but unflushed write I/O
+can be treated as though it is cached in memory. If an application
+requires data to be stable on storage, it must issue a flush or write the
+data with the FUA bit set like any other asynchronous I/O. Shutting down
+the vdo target will also flush any remaining I/O.
+
+Application write bios follow the steps outlined below.
+
+1. A data_vio is obtained from the data_vio pool and associated with the
+ application bio. If there are no data_vios available, the incoming bio
+ will block until a data_vio is available. This provides back pressure
+ to the application. The data_vio pool is protected by a spin lock.
+
+ The newly acquired data_vio is reset and the bio's data is copied into
+ the data_vio if it is a write and the data is not all zeroes. The data
+ must be copied because the application bio can be acknowledged before
+ the data_vio processing is complete, which means later processing steps
+ will no longer have access to the application bio. The application bio
+ may also be smaller than 4K, in which case the data_vio will have
+ already read the underlying block and the data is instead copied over
+ the relevant portion of the larger block.
+
+2. The data_vio places a claim (the "logical lock") on the logical address
+ of the bio. It is vital to prevent simultaneous modifications of the
+ same logical address, because deduplication involves sharing blocks.
+ This claim is implemented as an entry in a hashtable where the key is
+ the logical address and the value is a pointer to the data_vio
+ currently handling that address.
+
+ If a data_vio looks in the hashtable and finds that another data_vio is
+ already operating on that logical address, it waits until the previous
+ operation finishes. It also sends a message to inform the current
+ lock holder that it is waiting. Most notably, a new data_vio waiting
+ for a logical lock will flush the previous lock holder out of the
+ compression packer (step 8d) rather than allowing it to continue
+ waiting to be packed.
+
+ This stage requires the data_vio to get an implicit lock on the
+ appropriate logical zone to prevent concurrent modifications of the
+ hashtable. This implicit locking is handled by the zone divisions
+ described above.
+
+3. The data_vio traverses the block map tree to ensure that all the
+ necessary internal tree nodes have been allocated, by trying to find
+ the leaf page for its logical address. If any interior tree page is
+ missing, it is allocated at this time out of the same physical storage
+ pool used to store application data.
+
+ a. If any page-node in the tree has not yet been allocated, it must be
+ allocated before the write can continue. This step requires the
+ data_vio to lock the page-node that needs to be allocated. This
+ lock, like the logical block lock in step 2, is a hashtable entry
+ that causes other data_vios to wait for the allocation process to
+ complete.
+
+ The implicit logical zone lock is released while the allocation is
+ happening, in order to allow other operations in the same logical
+ zone to proceed. The details of allocation are the same as in
+ step 4. Once a new node has been allocated, that node is added to
+ the tree using a similar process to adding a new data block mapping.
+ The data_vio journals the intent to add the new node to the block
+ map tree (step 10), updates the reference count of the new block
+ (step 11), and reacquires the implicit logical zone lock to add the
+ new mapping to the parent tree node (step 12). Once the tree is
+ updated, the data_vio proceeds down the tree. Any other data_vios
+ waiting on this allocation also proceed.
+
+ b. In the steady-state case, the block map tree nodes will already be
+ allocated, so the data_vio just traverses the tree until it finds
+ the required leaf node. The location of the mapping (the "block map
+ slot") is recorded in the data_vio so that later steps do not need
+ to traverse the tree again. The data_vio then releases the implicit
+ logical zone lock.
+
+4. If the block is a zero block, skip to step 9. Otherwise, an attempt is
+ made to allocate a free data block. This allocation ensures that the
+ data_vio can write its data somewhere even if deduplication and
+ compression are not possible. This stage gets an implicit lock on a
+ physical zone to search for free space within that zone.
+
+ The data_vio will search each slab in a zone until it finds a free
+ block or decides there are none. If the first zone has no free space,
+ it will proceed to search the next physical zone by taking the implicit
+ lock for that zone and releasing the previous one until it finds a
+ free block or runs out of zones to search. The data_vio will acquire a
+ struct pbn_lock (the "physical block lock") on the free block. The
+ struct pbn_lock also has several fields to record the various kinds of
+ claims that data_vios can have on physical blocks. The pbn_lock is
+ added to a hashtable like the logical block locks in step 2. This
+ hashtable is also covered by the implicit physical zone lock. The
+ reference count of the free block is updated to prevent any other
+ data_vio from considering it free. The reference counters are a
+ sub-component of the slab and are thus also covered by the implicit
+ physical zone lock.
+
+5. If an allocation was obtained, the data_vio has all the resources it
+ needs to complete the write. The application bio can safely be
+ acknowledged at this point. The acknowledgment happens on a separate
+ thread to prevent the application callback from blocking other data_vio
+ operations.
+
+ If an allocation could not be obtained, the data_vio continues to
+ attempt to deduplicate or compress the data, but the bio is not
+ acknowledged because the vdo device may be out of space.
+
+6. At this point vdo must determine where to store the application data.
+ The data_vio's data is hashed and the hash (the "record name") is
+ recorded in the data_vio.
+
+7. The data_vio reserves or joins a struct hash_lock, which manages all of
+ the data_vios currently writing the same data. Active hash locks are
+ tracked in a hashtable similar to the way logical block locks are
+ tracked in step 2. This hashtable is covered by the implicit lock on
+ the hash zone.
+
+ If there is no existing hash lock for this data_vio's record_name, the
+ data_vio obtains a hash lock from the pool, adds it to the hashtable,
+ and sets itself as the new hash lock's "agent." The hash_lock pool is
+ also covered by the implicit hash zone lock. The hash lock agent will
+ do all the work to decide where the application data will be
+ written. If a hash lock for the data_vio's record_name already exists,
+ and the data_vio's data is the same as the agent's data, the new
+ data_vio will wait for the agent to complete its work and then share
+ its result.
+
+ In the rare case that a hash lock exists for the data_vio's hash but
+ the data does not match the hash lock's agent, the data_vio skips to
+ step 8h and attempts to write its data directly. This can happen if two
+ different data blocks produce the same hash, for example.
+
+8. The hash lock agent attempts to deduplicate or compress its data with
+ the following steps.
+
+ a. The agent initializes and sends its embedded deduplication request
+ (struct uds_request) to the deduplication index. This does not
+ require the data_vio to get any locks because the index components
+ manage their own locking. The data_vio waits until it either gets a
+ response from the index or times out.
+
+ b. If the deduplication index returns advice, the data_vio attempts to
+ obtain a physical block lock on the indicated physical address, in
+ order to read the data and verify that it is the same as the
+ data_vio's data, and that it can accept more references. If the
+ physical address is already locked by another data_vio, the data at
+ that address may soon be overwritten so it is not safe to use the
+ address for deduplication.
+
+ c. If the data matches and the physical block can add references, the
+ agent and any other data_vios waiting on it will record this
+ physical block as their new physical address and proceed to step 9
+ to record their new mapping. If there are more data_vios in the hash
+ lock than there are references available, one of the remaining
+ data_vios becomes the new agent and continues to step 8d as if no
+ valid advice was returned.
+
+ d. If no usable duplicate block was found, the agent first checks that
+ it has an allocated physical block (from step 3) that it can write
+ to. If the agent does not have an allocation, some other data_vio in
+ the hash lock that does have an allocation takes over as agent. If
+ none of the data_vios have an allocated physical block, these writes
+ are out of space, so they proceed to step 13 for cleanup.
+
+ e. The agent attempts to compress its data. If the data does not
+ compress, the data_vio will continue to step 8h to write its data
+ directly.
+
+ If the compressed size is small enough, the agent will release the
+ implicit hash zone lock and go to the packer (struct packer) where
+ it will be placed in a bin (struct packer_bin) along with other
+ data_vios. All compression operations require the implicit lock on
+ the packer zone.
+
+ The packer can combine up to 14 compressed blocks in a single 4k
+ data block. Compression is only helpful if vdo can pack at least 2
+ data_vios into a single data block. This means that a data_vio may
+ wait in the packer for an arbitrarily long time for other data_vios
+ to fill out the compressed block. There is a mechanism for vdo to
+ evict waiting data_vios when continuing to wait would cause
+ problems. Circumstances causing an eviction include an application
+ flush, device shutdown, or a subsequent data_vio trying to overwrite
+ the same logical block address. A data_vio may also be evicted from
+ the packer if it cannot be paired with any other compressed block
+ before more compressible blocks need to use its bin. An evicted
+ data_vio will proceed to step 8h to write its data directly.
+
+ f. If the agent fills a packer bin, either because all 14 of its slots
+ are used or because it has no remaining space, it is written out
+ using the allocated physical block from one of its data_vios. Step
+ 8d has already ensured that an allocation is available.
+
+ g. Each data_vio sets the compressed block as its new physical address.
+ The data_vio obtains an implicit lock on the physical zone and
+ acquires the struct pbn_lock for the compressed block, which is
+ modified to be a shared lock. Then it releases the implicit physical
+ zone lock and proceeds to step 8i.
+
+ h. Any data_vio evicted from the packer will have an allocation from
+ step 3. It will write its data to that allocated physical block.
+
+ i. After the data is written, if the data_vio is the agent of a hash
+ lock, it will reacquire the implicit hash zone lock and share its
+ physical address with as many other data_vios in the hash lock as
+ possible. Each data_vio will then proceed to step 9 to record its
+ new mapping.
+
+ j. If the agent actually wrote new data (whether compressed or not),
+ the deduplication index is updated to reflect the location of the
+ new data. The agent then releases the implicit hash zone lock.
+
+9. The data_vio determines the previous mapping of the logical address.
+ There is a cache for block map leaf pages (the "block map cache"),
+ because there are usually too many block map leaf nodes to store
+ entirely in memory. If the desired leaf page is not in the cache, the
+ data_vio will reserve a slot in the cache and load the desired page
+ into it, possibly evicting an older cached page. The data_vio then
+ finds the current physical address for this logical address (the "old
+ physical mapping"), if any, and records it. This step requires a lock
+ on the block map cache structures, covered by the implicit logical zone
+ lock.
+
+10. The data_vio makes an entry in the recovery journal containing the
+ logical block address, the old physical mapping, and the new physical
+ mapping. Making this journal entry requires holding the implicit
+ recovery journal lock. The data_vio will wait in the journal until all
+ recovery blocks up to the one containing its entry have been written
+ and flushed to ensure the transaction is stable on storage.
+
+11. Once the recovery journal entry is stable, the data_vio makes two slab
+ journal entries: an increment entry for the new mapping, and a
+ decrement entry for the old mapping. These two operations each require
+ holding a lock on the affected physical slab, covered by its implicit
+ physical zone lock. For correctness during recovery, the slab journal
+ entries in any given slab journal must be in the same order as the
+ corresponding recovery journal entries. Therefore, if the two entries
+ are in different zones, they are made concurrently, and if they are in
+ the same zone, the increment is always made before the decrement in
+ order to avoid underflow. After each slab journal entry is made in
+ memory, the associated reference count is also updated in memory.
+
+12. Once both of the reference count updates are done, the data_vio
+ acquires the implicit logical zone lock and updates the
+ logical-to-physical mapping in the block map to point to the new
+ physical block. At this point the write operation is complete.
+
+13. If the data_vio has a hash lock, it acquires the implicit hash zone
+ lock and releases its hash lock to the pool.
+
+ The data_vio then acquires the implicit physical zone lock and releases
+ the struct pbn_lock it holds for its allocated block. If it had an
+ allocation that it did not use, it also sets the reference count for
+ that block back to zero to free it for use by subsequent data_vios.
+
+ The data_vio then acquires the implicit logical zone lock and releases
+ the logical block lock acquired in step 2.
+
+ The application bio is then acknowledged if it has not previously been
+ acknowledged, and the data_vio is returned to the pool.
+
+*Read Path*
+
+An application read bio follows a much simpler set of steps. It does steps
+1 and 2 in the write path to obtain a data_vio and lock its logical
+address. If there is already a write data_vio in progress for that logical
+address that is guaranteed to complete, the read data_vio will copy the
+data from the write data_vio and return it. Otherwise, it will look up the
+logical-to-physical mapping by traversing the block map tree as in step 3,
+and then read and possibly decompress the indicated data at the indicated
+physical block address. A read data_vio will not allocate block map tree
+nodes if they are missing. If the interior block map nodes do not exist
+yet, the logical block map address must still be unmapped and the read
+data_vio will return all zeroes. A read data_vio handles cleanup and
+acknowledgment as in step 13, although it only needs to release the logical
+lock and return itself to the pool.
+
+*Small Writes*
+
+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 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.
+
+*Recovery*
+
+When a vdo is restarted after a crash, it will attempt to recover from the
+recovery journal. During the pre-resume phase of the next start, the
+recovery journal is read. The increment portion of valid entries are played
+into the block map. Next, valid entries are played, in order as required,
+into the slab journals. Finally, each physical zone attempts to replay at
+least one slab journal to reconstruct the reference counts of one slab.
+Once each zone has some free space (or has determined that it has none),
+the vdo comes back online, while the remainder of the slab journals are
+used to reconstruct the rest of the reference counts in the background.
+
+*Read-only Rebuild*
+
+If a vdo encounters an unrecoverable error, it will enter read-only mode.
+This mode indicates that some previously acknowledged data may have been
+lost. The vdo may be instructed to rebuild as best it can in order to
+return to a writable state. However, this is never done automatically due
+to the possibility that data has been lost. During a read-only rebuild, the
+block map is recovered from the recovery journal as before. However, the
+reference counts are not rebuilt from the slab journals. Instead, the
+reference counts are zeroed, the entire block map is traversed, and the
+reference counts are updated from the block mappings. While this may lose
+some data, it ensures that the block map and reference counts are
+consistent with each other. This allows vdo to resume normal operation and
+accept further writes.
diff --git a/Documentation/admin-guide/device-mapper/vdo.rst b/Documentation/admin-guide/device-mapper/vdo.rst
new file mode 100644
index 000000000000..8a67b320a97b
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/vdo.rst
@@ -0,0 +1,413 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+======
+dm-vdo
+======
+
+The dm-vdo (virtual data optimizer) device mapper target provides
+block-level deduplication, compression, and thin provisioning. As a device
+mapper target, it can add these features to the storage stack, compatible
+with any file system. The vdo target does not protect against data
+corruption, relying instead on integrity protection of the storage below
+it. It is strongly recommended that lvm be used to manage vdo volumes. See
+lvmvdo(7).
+
+Userspace component
+===================
+
+Formatting a vdo volume requires the use of the 'vdoformat' tool, available
+at:
+
+https://github.com/dm-vdo/vdo/
+
+In most cases, a vdo target will recover from a crash automatically the
+next time it is started. In cases where it encountered an unrecoverable
+error (either during normal operation or crash recovery) the target will
+enter or come up in read-only mode. Because read-only mode is indicative of
+data-loss, a positive action must be taken to bring vdo out of read-only
+mode. The 'vdoforcerebuild' tool, available from the same repo, is used to
+prepare a read-only vdo to exit read-only mode. After running this tool,
+the vdo target will rebuild its metadata the next time it is
+started. Although some data may be lost, the rebuilt vdo's metadata will be
+internally consistent and the target will be writable again.
+
+The repo also contains additional userspace tools which can be used to
+inspect a vdo target's on-disk metadata. Fortunately, these tools are
+rarely needed except by dm-vdo developers.
+
+Metadata requirements
+=====================
+
+Each vdo volume reserves 3GB of space for metadata, or more depending on
+its configuration. It is helpful to check that the space saved by
+deduplication and compression is not cancelled out by the metadata
+requirements. An estimation of the space saved for a specific dataset can
+be computed with the vdo estimator tool, which is available at:
+
+https://github.com/dm-vdo/vdoestimator/
+
+Target interface
+================
+
+Table line
+----------
+
+::
+
+ <offset> <logical device size> vdo V4 <storage device>
+ <storage device size> <minimum I/O size> <block map cache size>
+ <block map era length> [optional arguments]
+
+
+Required parameters:
+
+ offset:
+ The offset, in sectors, at which the vdo volume's logical
+ space begins.
+
+ logical device size:
+ The size of the device which the vdo volume will service,
+ in sectors. Must match the current logical size of the vdo
+ volume.
+
+ storage device:
+ The device holding the vdo volume's data and metadata.
+
+ storage device size:
+ The size of the device holding the vdo volume, as a number
+ of 4096-byte blocks. Must match the current size of the vdo
+ volume.
+
+ minimum I/O size:
+ The minimum I/O size for this vdo volume to accept, in
+ bytes. Valid values are 512 or 4096. The recommended value
+ is 4096.
+
+ block map cache size:
+ The size of the block map cache, as a number of 4096-byte
+ blocks. The minimum and recommended value is 32768 blocks.
+ If the logical thread count is non-zero, the cache size
+ must be at least 4096 blocks per logical thread.
+
+ block map era length:
+ The speed with which the block map cache writes out
+ modified block map pages. A smaller era length is likely to
+ reduce the amount of time spent rebuilding, at the cost of
+ increased block map writes during normal operation. The
+ maximum and recommended value is 16380; the minimum value
+ is 1.
+
+Optional parameters:
+--------------------
+Some or all of these parameters may be specified as <key> <value> pairs.
+
+Thread related parameters:
+
+Different categories of work are assigned to separate thread groups, and
+the number of threads in each group can be configured separately.
+
+If <hash>, <logical>, and <physical> are all set to 0, the work handled by
+all three thread types will be handled by a single thread. If any of these
+values are non-zero, all of them must be non-zero.
+
+ ack:
+ The number of threads used to complete bios. Since
+ completing a bio calls an arbitrary completion function
+ outside the vdo volume, threads of this type allow the vdo
+ volume to continue processing requests even when bio
+ completion is slow. The default is 1.
+
+ bio:
+ The number of threads used to issue bios to the underlying
+ storage. Threads of this type allow the vdo volume to
+ continue processing requests even when bio submission is
+ slow. The default is 4.
+
+ bioRotationInterval:
+ The number of bios to enqueue on each bio thread before
+ switching to the next thread. The value must be greater
+ than 0 and not more than 1024; the default is 64.
+
+ cpu:
+ The number of threads used to do CPU-intensive work, such
+ as hashing and compression. The default is 1.
+
+ hash:
+ The number of threads used to manage data comparisons for
+ deduplication based on the hash value of data blocks. The
+ default is 0.
+
+ logical:
+ The number of threads used to manage caching and locking
+ based on the logical address of incoming bios. The default
+ is 0; the maximum is 60.
+
+ physical:
+ The number of threads used to manage administration of the
+ underlying storage device. At format time, a slab size for
+ the vdo is chosen; the vdo storage device must be large
+ enough to have at least 1 slab per physical thread. The
+ default is 0; the maximum is 16.
+
+Miscellaneous parameters:
+
+ maxDiscard:
+ The maximum size of discard bio accepted, in 4096-byte
+ blocks. I/O requests to a vdo volume are normally split
+ into 4096-byte blocks, and processed up to 2048 at a time.
+ However, discard requests to a vdo volume can be
+ automatically split to a larger size, up to <maxDiscard>
+ 4096-byte blocks in a single bio, and are limited to 1500
+ at a time. Increasing this value may provide better overall
+ performance, at the cost of increased latency for the
+ individual discard requests. The default and minimum is 1;
+ the maximum is UINT_MAX / 4096.
+
+ deduplication:
+ Whether deduplication is enabled. The default is 'on'; the
+ acceptable values are 'on' and 'off'.
+
+ compression:
+ Whether compression is enabled. The default is 'off'; the
+ acceptable values are 'on' and 'off'.
+
+Device modification
+-------------------
+
+A modified table may be loaded into a running, non-suspended vdo volume.
+The modifications will take effect when the device is next resumed. The
+modifiable parameters are <logical device size>, <physical device size>,
+<maxDiscard>, <compression>, and <deduplication>.
+
+If the logical device size or physical device size are changed, upon
+successful resume vdo will store the new values and require them on future
+startups. These two parameters may not be decreased. The logical device
+size may not exceed 4 PB. The physical device size must increase by at
+least 32832 4096-byte blocks if at all, and must not exceed the size of the
+underlying storage device. Additionally, when formatting the vdo device, a
+slab size is chosen: the physical device size may never increase above the
+size which provides 8192 slabs, and each increase must be large enough to
+add at least one new slab.
+
+Examples:
+
+Start a previously-formatted vdo volume with 1 GB logical space and 1 GB
+physical space, storing to /dev/dm-1 which has more than 1 GB of space.
+
+::
+
+ dmsetup create vdo0 --table \
+ "0 2097152 vdo V4 /dev/dm-1 262144 4096 32768 16380"
+
+Grow the logical size to 4 GB.
+
+::
+
+ dmsetup reload vdo0 --table \
+ "0 8388608 vdo V4 /dev/dm-1 262144 4096 32768 16380"
+ dmsetup resume vdo0
+
+Grow the physical size to 2 GB.
+
+::
+
+ dmsetup reload vdo0 --table \
+ "0 8388608 vdo V4 /dev/dm-1 524288 4096 32768 16380"
+ dmsetup resume vdo0
+
+Grow the physical size by 1 GB more and increase max discard sectors.
+
+::
+
+ dmsetup reload vdo0 --table \
+ "0 10485760 vdo V4 /dev/dm-1 786432 4096 32768 16380 maxDiscard 8"
+ dmsetup resume vdo0
+
+Stop the vdo volume.
+
+::
+
+ dmsetup remove vdo0
+
+Start the vdo volume again. Note that the logical and physical device sizes
+must still match, but other parameters can change.
+
+::
+
+ dmsetup create vdo1 --table \
+ "0 10485760 vdo V4 /dev/dm-1 786432 512 65550 5000 hash 1 logical 3 physical 2"
+
+Messages
+--------
+All vdo devices accept messages in the form:
+
+::
+
+ dmsetup message <target-name> 0 <message-name> <message-parameters>
+
+The messages are:
+
+ stats:
+ Outputs the current view of the vdo statistics. Mostly used
+ by the vdostats userspace program to interpret the output
+ buffer.
+
+ config:
+ Outputs useful vdo configuration information. Mostly used
+ by users who want to recreate a similar VDO volume and
+ want to know the creation configuration used.
+
+ dump:
+ Dumps many internal structures to the system log. This is
+ not always safe to run, so it should only be used to debug
+ a hung vdo. Optional parameters to specify structures to
+ dump are:
+
+ viopool: The pool of I/O requests incoming bios
+ pools: A synonym of 'viopool'
+ vdo: Most of the structures managing on-disk data
+ queues: Basic information about each vdo thread
+ threads: A synonym of 'queues'
+ default: Equivalent to 'queues vdo'
+ all: All of the above.
+
+ dump-on-shutdown:
+ Perform a default dump next time vdo shuts down.
+
+
+Status
+------
+
+::
+
+ <device> <operating mode> <in recovery> <index state>
+ <compression state> <physical blocks used> <total physical blocks>
+
+ device:
+ The name of the vdo volume.
+
+ operating mode:
+ The current operating mode of the vdo volume; values may be
+ 'normal', 'recovering' (the volume has detected an issue
+ with its metadata and is attempting to repair itself), and
+ 'read-only' (an error has occurred that forces the vdo
+ volume to only support read operations and not writes).
+
+ in recovery:
+ Whether the vdo volume is currently in recovery mode;
+ values may be 'recovering' or '-' which indicates not
+ recovering.
+
+ index state:
+ The current state of the deduplication index in the vdo
+ volume; values may be 'closed', 'closing', 'error',
+ 'offline', 'online', 'opening', and 'unknown'.
+
+ compression state:
+ The current state of compression in the vdo volume; values
+ may be 'offline' and 'online'.
+
+ used physical blocks:
+ The number of physical blocks in use by the vdo volume.
+
+ total physical blocks:
+ The total number of physical blocks the vdo volume may use;
+ the difference between this value and the
+ <used physical blocks> is the number of blocks the vdo
+ volume has left before being full.
+
+Memory Requirements
+===================
+
+A vdo target requires a fixed 38 MB of RAM along with the following amounts
+that scale with the target:
+
+- 1.15 MB of RAM for each 1 MB of configured block map cache size. The
+ block map cache requires a minimum of 150 MB.
+- 1.6 MB of RAM for each 1 TB of logical space.
+- 268 MB of RAM for each 1 TB of physical storage managed by the volume.
+
+The deduplication index requires additional memory which scales with the
+size of the deduplication window. For dense indexes, the index requires 1
+GB of RAM per 1 TB of window. For sparse indexes, the index requires 1 GB
+of RAM per 10 TB of window. The index configuration is set when the target
+is formatted and may not be modified.
+
+Module Parameters
+=================
+
+The vdo driver has a numeric parameter 'log_level' which controls the
+verbosity of logging from the driver. The default setting is 6
+(LOGLEVEL_INFO and more severe messages).
+
+Run-time Usage
+==============
+
+When using dm-vdo, it is important to be aware of the ways in which its
+behavior differs from other storage targets.
+
+- There is no guarantee that over-writes of existing blocks will succeed.
+ Because the underlying storage may be multiply referenced, over-writing
+ an existing block generally requires a vdo to have a free block
+ available.
+
+- When blocks are no longer in use, sending a discard request for those
+ blocks lets the vdo release references for those blocks. If the vdo is
+ thinly provisioned, discarding unused blocks is essential to prevent the
+ target from running out of space. However, due to the sharing of
+ duplicate blocks, no discard request for any given logical block is
+ guaranteed to reclaim space.
+
+- Assuming the underlying storage properly implements flush requests, vdo
+ is resilient against crashes, however, unflushed writes may or may not
+ persist after a crash.
+
+- Each write to a vdo target entails a significant amount of processing.
+ However, much of the work is paralellizable. Therefore, vdo targets
+ achieve better throughput at higher I/O depths, and can support up 2048
+ requests in parallel.
+
+Tuning
+======
+
+The vdo device has many options, and it can be difficult to make optimal
+choices without perfect knowledge of the workload. Additionally, most
+configuration options must be set when a vdo target is started, and cannot
+be changed without shutting it down completely; the configuration cannot be
+changed while the target is active. Ideally, tuning with simulated
+workloads should be performed before deploying vdo in production
+environments.
+
+The most important value to adjust is the block map cache size. In order to
+service a request for any logical address, a vdo must load the portion of
+the block map which holds the relevant mapping. These mappings are cached.
+Performance will suffer when the working set does not fit in the cache. By
+default, a vdo allocates 128 MB of metadata cache in RAM to support
+efficient access to 100 GB of logical space at a time. It should be scaled
+up proportionally for larger working sets.
+
+The logical and physical thread counts should also be adjusted. A logical
+thread controls a disjoint section of the block map, so additional logical
+threads increase parallelism and can increase throughput. Physical threads
+control a disjoint section of the data blocks, so additional physical
+threads can also increase throughput. However, excess threads can waste
+resources and increase contention.
+
+Bio submission threads control the parallelism involved in sending I/O to
+the underlying storage; fewer threads mean there is more opportunity to
+reorder I/O requests for performance benefit, but also that each I/O
+request has to wait longer before being submitted.
+
+Bio acknowledgment threads are used for finishing I/O requests. This is
+done on dedicated threads since the amount of work required to execute a
+bio's callback can not be controlled by the vdo itself. Usually one thread
+is sufficient but additional threads may be beneficial, particularly when
+bios have CPU-heavy callbacks.
+
+CPU threads are used for hashing and for compression; in workloads with
+compression enabled, more threads may result in higher throughput.
+
+Hash threads are used to sort active requests by hash and determine whether
+they should deduplicate; the most CPU intensive actions done by these
+threads are comparison of 4096-byte data blocks. In most cases, a single
+hash thread is sufficient.
diff --git a/Documentation/admin-guide/device-mapper/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst
new file mode 100644
index 000000000000..8c3f1f967a3c
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/verity.rst
@@ -0,0 +1,265 @@
+=========
+dm-verity
+=========
+
+Device-Mapper's "verity" target provides transparent integrity checking of
+block devices using a cryptographic digest provided by the kernel crypto API.
+This target is read-only.
+
+Construction Parameters
+=======================
+
+::
+
+ <version> <dev> <hash_dev>
+ <data_block_size> <hash_block_size>
+ <num_data_blocks> <hash_start_block>
+ <algorithm> <digest> <salt>
+ [<#opt_params> <opt_params>]
+
+<version>
+ This is the type of the on-disk hash format.
+
+ 0 is the original format used in the Chromium OS.
+ The salt is appended when hashing, digests are stored continuously and
+ the rest of the block is padded with zeroes.
+
+ 1 is the current format that should be used for new devices.
+ The salt is prepended when hashing and each digest is
+ padded with zeroes to the power of two.
+
+<dev>
+ This is the device containing data, the integrity of which needs to be
+ checked. It may be specified as a path, like /dev/sdaX, or a device number,
+ <major>:<minor>.
+
+<hash_dev>
+ This is the device that supplies the hash tree data. It may be
+ specified similarly to the device path and may be the same device. If the
+ same device is used, the hash_start should be outside the configured
+ dm-verity device.
+
+<data_block_size>
+ The block size on a data device in bytes.
+ Each block corresponds to one digest on the hash device.
+
+<hash_block_size>
+ The size of a hash block in bytes.
+
+<num_data_blocks>
+ The number of data blocks on the data device. Additional blocks are
+ inaccessible. You can place hashes to the same partition as data, in this
+ case hashes are placed after <num_data_blocks>.
+
+<hash_start_block>
+ This is the offset, in <hash_block_size>-blocks, from the start of hash_dev
+ to the root block of the hash tree.
+
+<algorithm>
+ The cryptographic hash algorithm used for this device. This should
+ be the name of the algorithm, like "sha1".
+
+<digest>
+ The hexadecimal encoding of the cryptographic hash of the root hash block
+ and the salt. This hash should be trusted as there is no other authenticity
+ beyond this point.
+
+<salt>
+ The hexadecimal encoding of the salt value.
+
+<#opt_params>
+ Number of optional parameters. If there are no optional parameters,
+ the optional parameters section can be skipped or #opt_params can be zero.
+ Otherwise #opt_params is the number of following arguments.
+
+ Example of optional parameters section:
+ 1 ignore_corruption
+
+ignore_corruption
+ Log corrupted blocks, but allow read operations to proceed normally.
+
+restart_on_corruption
+ Restart the system when a corrupted block is discovered. This option is
+ not compatible with ignore_corruption and requires user space support to
+ avoid restart loops.
+
+panic_on_corruption
+ Panic the device when a corrupted block is discovered. This option is
+ not compatible with ignore_corruption and restart_on_corruption.
+
+restart_on_error
+ Restart the system when an I/O error is detected.
+ This option can be combined with the restart_on_corruption option.
+
+panic_on_error
+ Panic the device when an I/O error is detected. This option is
+ not compatible with the restart_on_error option but can be combined
+ with the panic_on_corruption option.
+
+ignore_zero_blocks
+ Do not verify blocks that are expected to contain zeroes and always return
+ zeroes instead. This may be useful if the partition contains unused blocks
+ that are not guaranteed to contain zeroes.
+
+use_fec_from_device <fec_dev>
+ Use forward error correction (FEC) to recover from corruption if hash
+ verification fails. Use encoding data from the specified device. This
+ may be the same device where data and hash blocks reside, in which case
+ fec_start must be outside data and hash areas.
+
+ If the encoding data covers additional metadata, it must be accessible
+ on the hash device after the hash blocks.
+
+ Note: block sizes for data and hash devices must match. Also, if the
+ verity <dev> is encrypted the <fec_dev> should be too.
+
+fec_roots <num>
+ Number of generator roots. This equals to the number of parity bytes in
+ the encoding data. For example, in RS(M, N) encoding, the number of roots
+ is M-N.
+
+fec_blocks <num>
+ The number of encoding data blocks on the FEC device. The block size for
+ the FEC device is <data_block_size>.
+
+fec_start <offset>
+ This is the offset, in <data_block_size> blocks, from the start of the
+ FEC device to the beginning of the encoding data.
+
+check_at_most_once
+ Verify data blocks only the first time they are read from the data device,
+ rather than every time. This reduces the overhead of dm-verity so that it
+ can be used on systems that are memory and/or CPU constrained. However, it
+ provides a reduced level of security because only offline tampering of the
+ data device's content will be detected, not online tampering.
+
+ Hash blocks are still verified each time they are read from the hash device,
+ since verification of hash blocks is less performance critical than data
+ blocks, and a hash block will not be verified any more after all the data
+ blocks it covers have been verified anyway.
+
+root_hash_sig_key_desc <key_description>
+ This is the description of the USER_KEY that the kernel will lookup to get
+ the pkcs7 signature of the roothash. The pkcs7 signature is used to validate
+ the root hash during the creation of the device mapper block device.
+ Verification of roothash depends on the config DM_VERITY_VERIFY_ROOTHASH_SIG
+ being set in the kernel. The signatures are checked against the builtin
+ trusted keyring by default, or the secondary trusted keyring if
+ DM_VERITY_VERIFY_ROOTHASH_SIG_SECONDARY_KEYRING is set. The secondary
+ trusted keyring includes by default the builtin trusted keyring, and it can
+ also gain new certificates at run time if they are signed by a certificate
+ already in the secondary trusted keyring.
+
+try_verify_in_tasklet
+ If verity hashes are in cache and the IO size does not exceed the limit,
+ verify data blocks in bottom half instead of workqueue. This option can
+ reduce IO latency. The size limits can be configured via
+ /sys/module/dm_verity/parameters/use_bh_bytes. The four parameters
+ correspond to limits for IOPRIO_CLASS_NONE, IOPRIO_CLASS_RT,
+ IOPRIO_CLASS_BE and IOPRIO_CLASS_IDLE in turn.
+ For example:
+ <none>,<rt>,<be>,<idle>
+ 4096,4096,4096,4096
+
+Theory of operation
+===================
+
+dm-verity is meant to be set up as part of a verified boot path. This
+may be anything ranging from a boot using tboot or trustedgrub to just
+booting from a known-good device (like a USB drive or CD).
+
+When a dm-verity device is configured, it is expected that the caller
+has been authenticated in some way (cryptographic signatures, etc).
+After instantiation, all hashes will be verified on-demand during
+disk access. If they cannot be verified up to the root node of the
+tree, the root hash, then the I/O will fail. This should detect
+tampering with any data on the device and the hash data.
+
+Cryptographic hashes are used to assert the integrity of the device on a
+per-block basis. This allows for a lightweight hash computation on first read
+into the page cache. Block hashes are stored linearly, aligned to the nearest
+block size.
+
+If forward error correction (FEC) support is enabled any recovery of
+corrupted data will be verified using the cryptographic hash of the
+corresponding data. This is why combining error correction with
+integrity checking is essential.
+
+Hash Tree
+---------
+
+Each node in the tree is a cryptographic hash. If it is a leaf node, the hash
+of some data block on disk is calculated. If it is an intermediary node,
+the hash of a number of child nodes is calculated.
+
+Each entry in the tree is a collection of neighboring nodes that fit in one
+block. The number is determined based on block_size and the size of the
+selected cryptographic digest algorithm. The hashes are linearly-ordered in
+this entry and any unaligned trailing space is ignored but included when
+calculating the parent node.
+
+The tree looks something like:
+
+ alg = sha256, num_blocks = 32768, block_size = 4096
+
+::
+
+ [ root ]
+ / . . . \
+ [entry_0] [entry_1]
+ / . . . \ . . . \
+ [entry_0_0] . . . [entry_0_127] . . . . [entry_1_127]
+ / ... \ / . . . \ / \
+ blk_0 ... blk_127 blk_16256 blk_16383 blk_32640 . . . blk_32767
+
+
+On-disk format
+==============
+
+The verity kernel code does not read the verity metadata on-disk header.
+It only reads the hash blocks which directly follow the header.
+It is expected that a user-space tool will verify the integrity of the
+verity header.
+
+Alternatively, the header can be omitted and the dmsetup parameters can
+be passed via the kernel command-line in a rooted chain of trust where
+the command-line is verified.
+
+Directly following the header (and with sector number padded to the next hash
+block boundary) are the hash blocks which are stored a depth at a time
+(starting from the root), sorted in order of increasing index.
+
+The full specification of kernel parameters and on-disk metadata format
+is available at the cryptsetup project's wiki page
+
+ https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity
+
+Status
+======
+V (for Valid) is returned if every check performed so far was valid.
+If any check failed, C (for Corruption) is returned.
+
+Example
+=======
+Set up a device::
+
+ # dmsetup create vroot --readonly --table \
+ "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
+ "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
+ "1234000000000000000000000000000000000000000000000000000000000000"
+
+A command line tool veritysetup is available to compute or verify
+the hash tree or activate the kernel device. This is available from
+the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/
+(as a libcryptsetup extension).
+
+Create hash on the device::
+
+ # veritysetup format /dev/sda1 /dev/sda2
+ ...
+ Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
+
+Activate the device::
+
+ # veritysetup create vroot /dev/sda1 /dev/sda2 \
+ 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
diff --git a/Documentation/admin-guide/device-mapper/writecache.rst b/Documentation/admin-guide/device-mapper/writecache.rst
new file mode 100644
index 000000000000..60c16b7fd5ac
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/writecache.rst
@@ -0,0 +1,114 @@
+=================
+Writecache target
+=================
+
+The writecache target caches writes on persistent memory or on SSD. It
+doesn't cache reads because reads are supposed to be cached in page cache
+in normal RAM.
+
+When the device is constructed, the first sector should be zeroed or the
+first sector should contain valid superblock from previous invocation.
+
+Constructor parameters:
+
+1. type of the cache device - "p" or "s"
+ - p - persistent memory
+ - s - SSD
+2. the underlying device that will be cached
+3. the cache device
+4. block size (4096 is recommended; the maximum block size is the page
+ size)
+5. the number of optional parameters (the parameters with an argument
+ count as two)
+
+ start_sector n (default: 0)
+ offset from the start of cache device in 512-byte sectors
+ high_watermark n (default: 50)
+ start writeback when the number of used blocks reach this
+ watermark
+ low_watermark x (default: 45)
+ stop writeback when the number of used blocks drops below
+ this watermark
+ writeback_jobs n (default: unlimited)
+ limit the number of blocks that are in flight during
+ writeback. Setting this value reduces writeback
+ throughput, but it may improve latency of read requests
+ autocommit_blocks n (default: 64 for pmem, 65536 for ssd)
+ when the application writes this amount of blocks without
+ issuing the FLUSH request, the blocks are automatically
+ committed
+ autocommit_time ms (default: 1000)
+ autocommit time in milliseconds. The data is automatically
+ committed if this time passes and no FLUSH request is
+ received
+ fua (by default on)
+ applicable only to persistent memory - use the FUA flag
+ when writing data from persistent memory back to the
+ underlying device
+ nofua
+ applicable only to persistent memory - don't use the FUA
+ flag when writing back data and send the FLUSH request
+ afterwards
+
+ - some underlying devices perform better with fua, some
+ with nofua. The user should test it
+ cleaner
+ when this option is activated (either in the constructor
+ arguments or by a message), the cache will not promote
+ new writes (however, writes to already cached blocks are
+ promoted, to avoid data corruption due to misordered
+ writes) and it will gradually writeback any cached
+ data. The userspace can then monitor the cleaning
+ process with "dmsetup status". When the number of cached
+ blocks drops to zero, userspace can unload the
+ dm-writecache target and replace it with dm-linear or
+ other targets.
+ max_age n
+ specifies the maximum age of a block in milliseconds. If
+ a block is stored in the cache for too long, it will be
+ written to the underlying device and cleaned up.
+ metadata_only
+ only metadata is promoted to the cache. This option
+ improves performance for heavier REQ_META workloads.
+ pause_writeback n (default: 3000)
+ pause writeback if there was some write I/O redirected to
+ the origin volume in the last n milliseconds
+
+Status:
+
+1. error indicator - 0 if there was no error, otherwise error number
+2. the number of blocks
+3. the number of free blocks
+4. the number of blocks under writeback
+5. the number of read blocks
+6. the number of read blocks that hit the cache
+7. the number of write blocks
+8. the number of write blocks that hit uncommitted block
+9. the number of write blocks that hit committed block
+10. the number of write blocks that bypass the cache
+11. the number of write blocks that are allocated in the cache
+12. the number of write requests that are blocked on the freelist
+13. the number of flush requests
+14. the number of discarded blocks
+
+Messages:
+ flush
+ Flush the cache device. The message returns successfully
+ if the cache device was flushed without an error
+ flush_on_suspend
+ Flush the cache device on next suspend. Use this message
+ when you are going to remove the cache device. The proper
+ sequence for removing the cache device is:
+
+ 1. send the "flush_on_suspend" message
+ 2. load an inactive table with a linear target that maps
+ to the underlying device
+ 3. suspend the device
+ 4. ask for status and verify that there are no errors
+ 5. resume the device, so that it will use the linear
+ target
+ 6. the cache device is now inactive and it can be deleted
+ cleaner
+ See above "cleaner" constructor documentation.
+ clear_stats
+ Clear the statistics that are reported on the status line
diff --git a/Documentation/admin-guide/device-mapper/zero.rst b/Documentation/admin-guide/device-mapper/zero.rst
new file mode 100644
index 000000000000..11fb5cf4597c
--- /dev/null
+++ b/Documentation/admin-guide/device-mapper/zero.rst
@@ -0,0 +1,37 @@
+=======
+dm-zero
+=======
+
+Device-Mapper's "zero" target provides a block-device that always returns
+zero'd data on reads and silently drops writes. This is similar behavior to
+/dev/zero, but as a block-device instead of a character-device.
+
+Dm-zero has no target-specific parameters.
+
+One very interesting use of dm-zero is for creating "sparse" devices in
+conjunction with dm-snapshot. A sparse device reports a device-size larger
+than the amount of actual storage space available for that device. A user can
+write data anywhere within the sparse device and read it back like a normal
+device. Reads to previously unwritten areas will return a zero'd buffer. When
+enough data has been written to fill up the actual storage space, the sparse
+device is deactivated. This can be very useful for testing device and
+filesystem limitations.
+
+To create a sparse device, start by creating a dm-zero device that's the
+desired size of the sparse device. For this example, we'll assume a 10TB
+sparse device::
+
+ TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2` # 10 TB in sectors
+ echo "0 $TEN_TERABYTES zero" | dmsetup create zero1
+
+Then create a snapshot of the zero device, using any available block-device as
+the COW device. The size of the COW device will determine the amount of real
+space available to the sparse device. For this example, we'll assume /dev/sdb1
+is an available 10GB partition::
+
+ echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \
+ dmsetup create sparse1
+
+This will create a 10TB sparse device called /dev/mapper/sparse1 that has
+10GB of actual storage space available. If more than 10GB of data is written
+to this device, it will start returning I/O errors.
diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst
new file mode 100644
index 000000000000..e3776d77374b
--- /dev/null
+++ b/Documentation/admin-guide/devices.rst
@@ -0,0 +1,268 @@
+.. _admin_devices:
+
+Linux allocated devices (4.x+ version)
+======================================
+
+This list is the Linux Device List, the official registry of allocated
+device numbers and ``/dev`` directory nodes for the Linux operating
+system.
+
+The version of this document at lanana.org is no longer maintained. This
+version in the mainline Linux kernel is the master document. Updates
+shall be sent as patches to the kernel maintainers (see the
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).
+Specifically explore the sections titled "CHAR and MISC DRIVERS", and
+"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers
+to involve for character and block devices.
+
+This document is included by reference into the Filesystem Hierarchy
+Standard (FHS). The FHS is available from https://www.pathname.com/fhs/.
+
+Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga
+platform only. Allocations marked (68k/Atari) apply to Linux/68k on
+the Atari platform only.
+
+This document is in the public domain. The authors requests, however,
+that semantically altered versions are not distributed without
+permission of the authors, assuming the authors can be contacted without
+an unreasonable effort.
+
+
+.. attention::
+
+ DEVICE DRIVERS AUTHORS PLEASE READ THIS
+
+ Linux now has extensive support for dynamic allocation of device numbering
+ and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs.
+ There are still some exceptions in the serial and boot device area. Before
+ asking for a device number make sure you actually need one.
+
+ To have a major number allocated, or a minor number in situations
+ where that applies (e.g. busmice), please submit a patch and send to
+ the authors as indicated above.
+
+ Keep the description of the device *in the same format
+ as this list*. The reason for this is that it is the only way we have
+ found to ensure we have all the requisite information to publish your
+ device and avoid conflicts.
+
+ Finally, sometimes we have to play "namespace police." Please don't be
+ offended. We often get submissions for ``/dev`` names that would be bound
+ to cause conflicts down the road. We are trying to avoid getting in a
+ situation where we would have to suffer an incompatible forward
+ change. Therefore, please consult with us **before** you make your
+ device names and numbers in any way public, at least to the point
+ where it would be at all difficult to get them changed.
+
+ Your cooperation is appreciated.
+
+.. include:: devices.txt
+ :literal:
+
+Additional ``/dev/`` directory entries
+--------------------------------------
+
+This section details additional entries that should or may exist in
+the /dev directory. It is preferred that symbolic links use the same
+form (absolute or relative) as is indicated here. Links are
+classified as "hard" or "symbolic" depending on the preferred type of
+link; if possible, the indicated type of link should be used.
+
+Compulsory links
+++++++++++++++++
+
+These links should exist on all systems:
+
+=============== =============== =============== ===============================
+/dev/fd /proc/self/fd symbolic File descriptors
+/dev/stdin fd/0 symbolic stdin file descriptor
+/dev/stdout fd/1 symbolic stdout file descriptor
+/dev/stderr fd/2 symbolic stderr file descriptor
+/dev/nfsd socksys symbolic Required by iBCS-2
+/dev/X0R null symbolic Required by iBCS-2
+=============== =============== =============== ===============================
+
+Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>.
+
+Recommended links
++++++++++++++++++
+
+It is recommended that these links exist on all systems:
+
+
+=============== =============== =============== ===============================
+/dev/core /proc/kcore symbolic Backward compatibility
+/dev/ramdisk ram0 symbolic Backward compatibility
+/dev/ftape qft0 symbolic Backward compatibility
+/dev/bttv0 video0 symbolic Backward compatibility
+/dev/radio radio0 symbolic Backward compatibility
+/dev/i2o* /dev/i2o/* symbolic Backward compatibility
+/dev/scd? sr? hard Alternate SCSI CD-ROM name
+=============== =============== =============== ===============================
+
+Locally defined links
++++++++++++++++++++++
+
+The following links may be established locally to conform to the
+configuration of the system. This is merely a tabulation of existing
+practice, and does not constitute a recommendation. However, if they
+exist, they should have the following uses.
+
+=============== =============== =============== ===============================
+/dev/mouse mouse port symbolic Current mouse device
+/dev/tape tape device symbolic Current tape device
+/dev/cdrom CD-ROM device symbolic Current CD-ROM device
+/dev/cdwriter CD-writer symbolic Current CD-writer device
+/dev/scanner scanner symbolic Current scanner device
+/dev/modem modem port symbolic Current dialout device
+/dev/root root device symbolic Current root filesystem
+/dev/swap swap device symbolic Current swap device
+=============== =============== =============== ===============================
+
+``/dev/modem`` should not be used for a modem which supports dialin as
+well as dialout, as it tends to cause lock file problems. If it
+exists, ``/dev/modem`` should point to the appropriate primary TTY device
+(the use of the alternate callout devices is deprecated).
+
+For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the
+*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas
+``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic
+SCSI devices (/dev/sg*).
+
+``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
+device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).
+
+Sockets and pipes
++++++++++++++++++
+
+Non-transient sockets and named pipes may exist in /dev. Common entries are:
+
+=============== =============== ===============================================
+/dev/printer socket lpd local socket
+/dev/log socket syslog local socket
+/dev/gpmdata socket gpm mouse multiplexer
+=============== =============== ===============================================
+
+Mount points
+++++++++++++
+
+The following names are reserved for mounting special filesystems
+under /dev. These special filesystems provide kernel interfaces that
+cannot be provided with standard device nodes.
+
+=============== =============== ===============================================
+/dev/pts devpts PTY slave filesystem
+/dev/shm tmpfs POSIX shared memory maintenance access
+=============== =============== ===============================================
+
+Terminal devices
+----------------
+
+Terminal, or TTY devices are a special class of character devices. A
+terminal device is any device that could act as a controlling terminal
+for a session; this includes virtual consoles, serial ports, and
+pseudoterminals (PTYs).
+
+All terminal devices share a common set of capabilities known as line
+disciplines; these include the common terminal line discipline as well
+as SLIP and PPP modes.
+
+All terminal devices are named similarly; this section explains the
+naming and use of the various types of TTYs. Note that the naming
+conventions include several historical warts; some of these are
+Linux-specific, some were inherited from other systems, and some
+reflect Linux outgrowing a borrowed convention.
+
+A hash mark (``#``) in a device name is used here to indicate a decimal
+number without leading zeroes.
+
+Virtual consoles and the console device
++++++++++++++++++++++++++++++++++++++++
+
+Virtual consoles are full-screen terminal displays on the system video
+monitor. Virtual consoles are named ``/dev/tty#``, with numbering
+starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console.
+``/dev/tty0`` is the device that should be used to access the system video
+card on those architectures for which the frame buffer devices
+(``/dev/fb*``) are not applicable. Do not use ``/dev/console``
+for this purpose.
+
+The console device, ``/dev/console``, is the device to which system
+messages should be sent, and on which logins should be permitted in
+single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed
+by the kernel; for previous versions it should be a symbolic link to
+either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to
+a serial port primary (``tty*``, not ``cu*``) device, depending on the
+configuration of the system.
+
+Serial ports
+++++++++++++
+
+Serial ports are RS-232 serial ports and any device which simulates
+one, either in hardware (such as internal modems) or in software (such
+as the ISDN driver.) Under Linux, each serial ports has two device
+names, the primary or callin device and the alternate or callout one.
+Each kind of device is indicated by a different letter. For any
+letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,
+respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``
+correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be
+expected that multiple letters will be used; all letters will be upper
+case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the
+"cu" device (e.g. ``/dev/cudp#``).
+
+The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.
+
+The alternate devices provide for kernel-based exclusion and somewhat
+different defaults than the primary devices. Their main purpose is to
+allow the use of serial ports with programs with no inherent or broken
+support for serial ports. Their use is deprecated, and they may be
+removed from a future version of Linux.
+
+Arbitration of serial ports is provided by the use of lock files with
+the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should
+be the PID of the locking process as an ASCII number.
+
+It is common practice to install links such as /dev/modem
+which point to serial ports. In order to ensure proper locking in the
+presence of these links, it is recommended that software chase
+symlinks and lock all possible names; additionally, it is recommended
+that a lock file be installed with the corresponding alternate
+device. In order to avoid deadlocks, it is recommended that the locks
+are acquired in the following order, and released in the reverse:
+
+ 1. The symbolic link name, if any (``/var/lock/LCK..modem``)
+ 2. The "tty" name (``/var/lock/LCK..ttyS2``)
+ 3. The alternate device name (``/var/lock/LCK..cua2``)
+
+In the case of nested symbolic links, the lock files should be
+installed in the order the symlinks are resolved.
+
+Under no circumstances should an application hold a lock while waiting
+for another to be released. In addition, applications which attempt
+to create lock files for the corresponding alternate device names
+should take into account the possibility of being used on a non-serial
+port TTY, for which no alternate device would exist.
+
+Pseudoterminals (PTYs)
+++++++++++++++++++++++
+
+Pseudoterminals, or PTYs, are used to create login sessions or provide
+other capabilities requiring a TTY line discipline (including SLIP or
+PPP capability) to arbitrary data-generation processes. Each PTY has
+a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named
+``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by
+allowing each master side to be opened only once.
+
+Once the master side has been opened, the corresponding slave device
+can be used in the same manner as any TTY device. The master and
+slave devices are connected by the kernel, generating the equivalent
+of a bidirectional pipe with TTY capabilities.
+
+Recent versions of the Linux kernels and GNU libc contain support for
+the System V/Unix98 naming scheme for PTYs, which assigns a common
+device, ``/dev/ptmx``, to all the masters (opening it will automatically
+give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,
+for the slaves; the slaves are named with decimal integers (``/dev/pts/#``
+in our notation). This removes the problem of exhausting the
+namespace and enables the kernel to automatically create the device
+nodes for the slaves on demand using the "devpts" filesystem.
diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt
new file mode 100644
index 000000000000..94c98be1329a
--- /dev/null
+++ b/Documentation/admin-guide/devices.txt
@@ -0,0 +1,3082 @@
+ 0 Unnamed devices (e.g. non-device mounts)
+ 0 = reserved as null device number
+ See block major 144, 145, 146 for expansion areas.
+
+ 1 char Memory devices
+ 1 = /dev/mem Physical memory access
+ 2 = /dev/kmem OBSOLETE - replaced by /proc/kcore
+ 3 = /dev/null Null device
+ 4 = /dev/port I/O port access
+ 5 = /dev/zero Null byte source
+ 6 = /dev/core OBSOLETE - replaced by /proc/kcore
+ 7 = /dev/full Returns ENOSPC on write
+ 8 = /dev/random Nondeterministic random number gen.
+ 9 = /dev/urandom Faster, less secure random number gen.
+ 10 = /dev/aio Asynchronous I/O notification interface
+ 11 = /dev/kmsg Writes to this come out as printk's, reads
+ export the buffered printk records.
+ 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore
+
+ 1 block RAM disk
+ 0 = /dev/ram0 First RAM disk
+ 1 = /dev/ram1 Second RAM disk
+ ...
+ 250 = /dev/initrd Initial RAM disk
+
+ Older kernels had /dev/ramdisk (1, 1) here.
+ /dev/initrd refers to a RAM disk which was preloaded
+ by the boot loader; newer kernels use /dev/ram0 for
+ the initrd.
+
+ 2 char Pseudo-TTY masters
+ 0 = /dev/ptyp0 First PTY master
+ 1 = /dev/ptyp1 Second PTY master
+ ...
+ 255 = /dev/ptyef 256th PTY master
+
+ Pseudo-tty's are named as follows:
+ * Masters are "pty", slaves are "tty";
+ * the fourth letter is one of pqrstuvwxyzabcde indicating
+ the 1st through 16th series of 16 pseudo-ttys each, and
+ * the fifth letter is one of 0123456789abcdef indicating
+ the position within the series.
+
+ These are the old-style (BSD) PTY devices; Unix98
+ devices are on major 128 and above and use the PTY
+ master multiplex (/dev/ptmx) to acquire a PTY on
+ demand.
+
+ 2 block Floppy disks
+ 0 = /dev/fd0 Controller 0, drive 0, autodetect
+ 1 = /dev/fd1 Controller 0, drive 1, autodetect
+ 2 = /dev/fd2 Controller 0, drive 2, autodetect
+ 3 = /dev/fd3 Controller 0, drive 3, autodetect
+ 128 = /dev/fd4 Controller 1, drive 0, autodetect
+ 129 = /dev/fd5 Controller 1, drive 1, autodetect
+ 130 = /dev/fd6 Controller 1, drive 2, autodetect
+ 131 = /dev/fd7 Controller 1, drive 3, autodetect
+
+ To specify format, add to the autodetect device number:
+ 0 = /dev/fd? Autodetect format
+ 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1)
+ 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1)
+ 48 = /dev/fd?h410 5.25" 410K in a 1200K drive
+ 64 = /dev/fd?h420 5.25" 420K in a 1200K drive
+ 24 = /dev/fd?h720 5.25" 720K in a 1200K drive
+ 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1)
+ 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1)
+ 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1)
+ 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive
+ 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive
+ 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1)
+
+ 12 = /dev/fd?u360 3.5" 360K Double Density(2)
+ 16 = /dev/fd?u720 3.5" 720K Double Density(1)
+ 120 = /dev/fd?u800 3.5" 800K Double Density(2)
+ 52 = /dev/fd?u820 3.5" 820K Double Density
+ 68 = /dev/fd?u830 3.5" 830K Double Density
+ 84 = /dev/fd?u1040 3.5" 1040K Double Density(1)
+ 88 = /dev/fd?u1120 3.5" 1120K Double Density(1)
+ 28 = /dev/fd?u1440 3.5" 1440K High Density(1)
+ 124 = /dev/fd?u1600 3.5" 1600K High Density(1)
+ 44 = /dev/fd?u1680 3.5" 1680K High Density(3)
+ 60 = /dev/fd?u1722 3.5" 1722K High Density
+ 76 = /dev/fd?u1743 3.5" 1743K High Density
+ 96 = /dev/fd?u1760 3.5" 1760K High Density
+ 116 = /dev/fd?u1840 3.5" 1840K High Density(3)
+ 100 = /dev/fd?u1920 3.5" 1920K High Density(1)
+ 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1)
+ 104 = /dev/fd?u3200 3.5" 3200K Extra Density
+ 108 = /dev/fd?u3520 3.5" 3520K Extra Density
+ 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1)
+
+ 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete?
+
+ (1) Autodetectable format
+ (2) Autodetectable format in a Double Density (720K) drive only
+ (3) Autodetectable format in a High Density (1440K) drive only
+
+ NOTE: The letter in the device name (d, q, h or u)
+ signifies the type of drive: 5.25" Double Density (d),
+ 5.25" Quad Density (q), 5.25" High Density (h) or 3.5"
+ (any model, u). The use of the capital letters D, H
+ and E for the 3.5" models have been deprecated, since
+ the drive type is insignificant for these devices.
+
+ 3 char Pseudo-TTY slaves
+ 0 = /dev/ttyp0 First PTY slave
+ 1 = /dev/ttyp1 Second PTY slave
+ ...
+ 255 = /dev/ttyef 256th PTY slave
+
+ These are the old-style (BSD) PTY devices; Unix98
+ devices are on major 136 and above.
+
+ 3 block First MFM, RLL and IDE hard disk/CD-ROM interface
+ 0 = /dev/hda Master: whole disk (or CD-ROM)
+ 64 = /dev/hdb Slave: whole disk (or CD-ROM)
+
+ For partitions, add to the whole disk device number:
+ 0 = /dev/hd? Whole disk
+ 1 = /dev/hd?1 First partition
+ 2 = /dev/hd?2 Second partition
+ ...
+ 63 = /dev/hd?63 63rd partition
+
+ For Linux/i386, partitions 1-4 are the primary
+ partitions, and 5 and above are logical partitions.
+ Other versions of Linux use partitioning schemes
+ appropriate to their respective architectures.
+
+ 4 char TTY devices
+ 0 = /dev/tty0 Current virtual console
+
+ 1 = /dev/tty1 First virtual console
+ ...
+ 63 = /dev/tty63 63rd virtual console
+ 64 = /dev/ttyS0 First UART serial port
+ ...
+ 255 = /dev/ttyS191 192nd UART serial port
+
+ UART serial ports refer to 8250/16450/16550 series devices.
+
+ Older versions of the Linux kernel used this major
+ number for BSD PTY devices. As of Linux 2.1.115, this
+ is no longer supported. Use major numbers 2 and 3.
+
+ 4 block Aliases for dynamically allocated major devices to be used
+ when its not possible to create the real device nodes
+ because the root filesystem is mounted read-only.
+
+ 0 = /dev/root
+
+ 5 char Alternate TTY devices
+ 0 = /dev/tty Current TTY device
+ 1 = /dev/console System console
+ 2 = /dev/ptmx PTY master multiplex
+ 3 = /dev/ttyprintk User messages via printk TTY device
+ 64 = /dev/cua0 Callout device for ttyS0
+ ...
+ 255 = /dev/cua191 Callout device for ttyS191
+
+ (5,1) is /dev/console starting with Linux 2.1.71. See
+ the section on terminal devices for more information
+ on /dev/console.
+
+ 6 char Parallel printer devices
+ 0 = /dev/lp0 Parallel printer on parport0
+ 1 = /dev/lp1 Parallel printer on parport1
+ ...
+
+ Current Linux kernels no longer have a fixed mapping
+ between parallel ports and I/O addresses. Instead,
+ they are redirected through the parport multiplex layer.
+
+ 7 char Virtual console capture devices
+ 0 = /dev/vcs Current vc text (glyph) contents
+ 1 = /dev/vcs1 tty1 text (glyph) contents
+ ...
+ 63 = /dev/vcs63 tty63 text (glyph) contents
+ 64 = /dev/vcsu Current vc text (unicode) contents
+ 65 = /dev/vcsu1 tty1 text (unicode) contents
+ ...
+ 127 = /dev/vcsu63 tty63 text (unicode) contents
+ 128 = /dev/vcsa Current vc text/attribute (glyph) contents
+ 129 = /dev/vcsa1 tty1 text/attribute (glyph) contents
+ ...
+ 191 = /dev/vcsa63 tty63 text/attribute (glyph) contents
+
+ NOTE: These devices permit both read and write access.
+
+ 7 block Loopback devices
+ 0 = /dev/loop0 First loop device
+ 1 = /dev/loop1 Second loop device
+ ...
+
+ The loop devices are used to mount filesystems not
+ associated with block devices. The binding to the
+ loop devices is handled by mount(8) or losetup(8).
+
+ 8 block SCSI disk devices (0-15)
+ 0 = /dev/sda First SCSI disk whole disk
+ 16 = /dev/sdb Second SCSI disk whole disk
+ 32 = /dev/sdc Third SCSI disk whole disk
+ ...
+ 240 = /dev/sdp Sixteenth SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 9 char SCSI tape devices
+ 0 = /dev/st0 First SCSI tape, mode 0
+ 1 = /dev/st1 Second SCSI tape, mode 0
+ ...
+ 32 = /dev/st0l First SCSI tape, mode 1
+ 33 = /dev/st1l Second SCSI tape, mode 1
+ ...
+ 64 = /dev/st0m First SCSI tape, mode 2
+ 65 = /dev/st1m Second SCSI tape, mode 2
+ ...
+ 96 = /dev/st0a First SCSI tape, mode 3
+ 97 = /dev/st1a Second SCSI tape, mode 3
+ ...
+ 128 = /dev/nst0 First SCSI tape, mode 0, no rewind
+ 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind
+ ...
+ 160 = /dev/nst0l First SCSI tape, mode 1, no rewind
+ 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind
+ ...
+ 192 = /dev/nst0m First SCSI tape, mode 2, no rewind
+ 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind
+ ...
+ 224 = /dev/nst0a First SCSI tape, mode 3, no rewind
+ 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind
+ ...
+
+ "No rewind" refers to the omission of the default
+ automatic rewind on device close. The MTREW or MTOFFL
+ ioctl()'s can be used to rewind the tape regardless of
+ the device used to access it.
+
+ 9 block Metadisk (RAID) devices
+ 0 = /dev/md0 First metadisk group
+ 1 = /dev/md1 Second metadisk group
+ ...
+
+ The metadisk driver is used to span a
+ filesystem across multiple physical disks.
+
+ 10 char Non-serial mice, misc features
+ 0 = /dev/logibm Logitech bus mouse
+ 1 = /dev/psaux PS/2-style mouse port
+ 2 = /dev/inportbm Microsoft Inport bus mouse
+ 3 = /dev/atibm ATI XL bus mouse
+ 4 = /dev/jbm J-mouse
+ 4 = /dev/amigamouse Amiga mouse (68k/Amiga)
+ 5 = /dev/atarimouse Atari mouse
+ 6 = /dev/sunmouse Sun mouse
+ 7 = /dev/amigamouse1 Second Amiga mouse
+ 8 = /dev/smouse Simple serial mouse driver
+ 9 = /dev/pc110pad IBM PC-110 digitizer pad
+ 10 = /dev/adbmouse Apple Desktop Bus mouse
+ 11 = /dev/vrtpanel Vr41xx embedded touch panel
+ 13 = /dev/vpcmouse Connectix Virtual PC Mouse
+ 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen
+ 15 = /dev/touchscreen/mk712 MK712 touchscreen
+ 128 = /dev/beep Fancy beep device
+ 129 =
+ 130 = /dev/watchdog Watchdog timer port
+ 131 = /dev/temperature Machine internal temperature
+ 132 = /dev/hwtrap Hardware fault trap
+ 133 = /dev/exttrp External device trap
+ 134 = /dev/apm_bios Advanced Power Management BIOS
+ 135 = /dev/rtc Real Time Clock
+ 137 = /dev/vhci Bluetooth virtual HCI driver
+ 139 = /dev/openprom SPARC OpenBoot PROM
+ 140 = /dev/relay8 Berkshire Products Octal relay card
+ 141 = /dev/relay16 Berkshire Products ISO-16 relay card
+ 142 =
+ 143 = /dev/pciconf PCI configuration space
+ 144 = /dev/nvram Non-volatile configuration RAM
+ 145 = /dev/hfmodem Soundcard shortwave modem control
+ 146 = /dev/graphics Linux/SGI graphics device
+ 147 = /dev/opengl Linux/SGI OpenGL pipe
+ 148 = /dev/gfx Linux/SGI graphics effects device
+ 149 = /dev/input/mouse Linux/SGI Irix emulation mouse
+ 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard
+ 151 = /dev/led Front panel LEDs
+ 152 = /dev/kpoll Kernel Poll Driver
+ 153 = /dev/mergemem Memory merge device
+ 154 = /dev/pmu Macintosh PowerBook power manager
+ 155 =
+ 156 = /dev/lcd Front panel LCD display
+ 157 = /dev/ac Applicom Intl Profibus card
+ 158 = /dev/nwbutton Netwinder external button
+ 159 = /dev/nwdebug Netwinder debug interface
+ 160 = /dev/nwflash Netwinder flash memory
+ 161 = /dev/userdma User-space DMA access
+ 162 = /dev/smbus System Management Bus
+ 163 = /dev/lik Logitech Internet Keyboard
+ 164 = /dev/ipmo Intel Intelligent Platform Management
+ 165 = /dev/vmmon VMware virtual machine monitor
+ 166 = /dev/i2o/ctl I2O configuration manager
+ 167 = /dev/specialix_sxctl Specialix serial control
+ 168 = /dev/tcldrv Technology Concepts serial control
+ 169 = /dev/specialix_rioctl Specialix RIO serial control
+ 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices
+ 171 = /dev/srripc QNX4 API IPC manager
+ 172 = /dev/usemaclone Semaphore clone device
+ 173 = /dev/ipmikcs Intelligent Platform Management
+ 174 = /dev/uctrl SPARCbook 3 microcontroller
+ 175 = /dev/agpgart AGP Graphics Address Remapping Table
+ 176 = /dev/gtrsc Gorgy Timing radio clock
+ 177 = /dev/cbm Serial CBM bus
+ 178 = /dev/jsflash JavaStation OS flash SIMM
+ 179 = /dev/xsvc High-speed shared-mem/semaphore service
+ 180 = /dev/vrbuttons Vr41xx button input device
+ 181 = /dev/toshiba Toshiba laptop SMM support
+ 182 = /dev/perfctr Performance-monitoring counters
+ 183 = /dev/hwrng Generic random number generator
+ 184 = /dev/cpu/microcode CPU microcode update interface
+ 186 = /dev/atomicps Atomic snapshot of process state data
+ 187 = /dev/irnet IrNET device
+ 188 = /dev/smbusbios SMBus BIOS
+ 189 = /dev/ussp_ctl User space serial port control
+ 190 = /dev/crash Mission Critical Linux crash dump facility
+ 191 = /dev/pcl181 <information missing>
+ 192 = /dev/nas_xbus NAS xbus LCD/buttons access
+ 193 = /dev/d7s SPARC 7-segment display
+ 194 = /dev/zkshim Zero-Knowledge network shim control
+ 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201
+ 196 = /dev/vfio/vfio VFIO userspace driver interface
+ 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver
+ 198 = /dev/sexec Signed executable interface
+ 199 = /dev/scanners/cuecat :CueCat barcode scanner
+ 200 = /dev/net/tun TAP/TUN network device
+ 201 = /dev/button/gulpb Transmeta GULP-B buttons
+ 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control
+ 203 = /dev/cuse Cuse (character device in user-space)
+ 204 = /dev/video/em8300 EM8300 DVD decoder control
+ 205 = /dev/video/em8300_mv EM8300 DVD decoder video
+ 206 = /dev/video/em8300_ma EM8300 DVD decoder audio
+ 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture
+ 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller
+ 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver
+ 210 = /dev/impi/bt IMPI coprocessor block transfer
+ 211 = /dev/impi/smic IMPI coprocessor stream interface
+ 212 = /dev/watchdogs/0 First watchdog device
+ 213 = /dev/watchdogs/1 Second watchdog device
+ 214 = /dev/watchdogs/2 Third watchdog device
+ 215 = /dev/watchdogs/3 Fourth watchdog device
+ 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel
+ 217 = /dev/ni/natmotn National Instruments Motion
+ 218 = /dev/kchuid Inter-process chuid control
+ 219 = /dev/modems/mwave MWave modem firmware upload
+ 220 = /dev/mptctl Message passing technology (MPT) control
+ 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver
+ 222 = /dev/mvista/hasi Montavista PICMG high availability
+ 223 = /dev/input/uinput User level driver support for input
+ 224 = /dev/tpm TCPA TPM driver
+ 225 = /dev/pps Pulse Per Second driver
+ 226 = /dev/systrace Systrace device
+ 227 = /dev/mcelog X86_64 Machine Check Exception driver
+ 228 = /dev/hpet HPET driver
+ 229 = /dev/fuse Fuse (virtual filesystem in user-space)
+ 230 = /dev/midishare MidiShare driver
+ 231 = /dev/snapshot System memory snapshot device
+ 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions)
+ 233 = /dev/kmview View-OS A process with a view
+ 234 = /dev/btrfs-control Btrfs control device
+ 235 = /dev/autofs Autofs control device
+ 236 = /dev/mapper/control Device-Mapper control device
+ 237 = /dev/loop-control Loopback control device
+ 238 = /dev/vhost-net Host kernel accelerator for virtio net
+ 239 = /dev/uhid User-space I/O driver support for HID subsystem
+ 240 = /dev/userio Serio driver testing device
+ 241 = /dev/vhost-vsock Host kernel driver for virtio vsock
+ 242 = /dev/rfkill Turning off radio transmissions (rfkill)
+
+ 243-254 Reserved for local use
+ 255 Reserved for MISC_DYNAMIC_MINOR
+
+ 11 char Raw keyboard device (Linux/SPARC only)
+ 0 = /dev/kbd Raw keyboard device
+
+ 11 char Serial Mux device (Linux/PA-RISC only)
+ 0 = /dev/ttyB0 First mux port
+ 1 = /dev/ttyB1 Second mux port
+ ...
+
+ 11 block SCSI CD-ROM devices
+ 0 = /dev/scd0 First SCSI CD-ROM
+ 1 = /dev/scd1 Second SCSI CD-ROM
+ ...
+
+ The prefix /dev/sr (instead of /dev/scd) has been deprecated.
+
+ 12 char QIC-02 tape
+ 2 = /dev/ntpqic11 QIC-11, no rewind-on-close
+ 3 = /dev/tpqic11 QIC-11, rewind-on-close
+ 4 = /dev/ntpqic24 QIC-24, no rewind-on-close
+ 5 = /dev/tpqic24 QIC-24, rewind-on-close
+ 6 = /dev/ntpqic120 QIC-120, no rewind-on-close
+ 7 = /dev/tpqic120 QIC-120, rewind-on-close
+ 8 = /dev/ntpqic150 QIC-150, no rewind-on-close
+ 9 = /dev/tpqic150 QIC-150, rewind-on-close
+
+ The device names specified are proposed -- if there
+ are "standard" names for these devices, please let me know.
+
+ 12 block
+
+ 13 char Input core
+ 0 = /dev/input/js0 First joystick
+ 1 = /dev/input/js1 Second joystick
+ ...
+ 32 = /dev/input/mouse0 First mouse
+ 33 = /dev/input/mouse1 Second mouse
+ ...
+ 63 = /dev/input/mice Unified mouse
+ 64 = /dev/input/event0 First event queue
+ 65 = /dev/input/event1 Second event queue
+ ...
+
+ Each device type has 5 bits (32 minors).
+
+ 13 block Previously used for the XT disk (/dev/xdN)
+ Deleted in kernel v3.9.
+
+ 14 char Open Sound System (OSS)
+ 0 = /dev/mixer Mixer control
+ 1 = /dev/sequencer Audio sequencer
+ 2 = /dev/midi00 First MIDI port
+ 3 = /dev/dsp Digital audio
+ 4 = /dev/audio Sun-compatible digital audio
+ 6 =
+ 7 = /dev/audioctl SPARC audio control device
+ 8 = /dev/sequencer2 Sequencer -- alternate device
+ 16 = /dev/mixer1 Second soundcard mixer control
+ 17 = /dev/patmgr0 Sequencer patch manager
+ 18 = /dev/midi01 Second MIDI port
+ 19 = /dev/dsp1 Second soundcard digital audio
+ 20 = /dev/audio1 Second soundcard Sun digital audio
+ 33 = /dev/patmgr1 Sequencer patch manager
+ 34 = /dev/midi02 Third MIDI port
+ 50 = /dev/midi03 Fourth MIDI port
+
+ 14 block
+
+ 15 char Joystick
+ 0 = /dev/js0 First analog joystick
+ 1 = /dev/js1 Second analog joystick
+ ...
+ 128 = /dev/djs0 First digital joystick
+ 129 = /dev/djs1 Second digital joystick
+ ...
+ 15 block Sony CDU-31A/CDU-33A CD-ROM
+ 0 = /dev/sonycd Sony CDU-31a CD-ROM
+
+ 16 char Non-SCSI scanners
+ 0 = /dev/gs4500 Genius 4500 handheld scanner
+
+ 16 block GoldStar CD-ROM
+ 0 = /dev/gscd GoldStar CD-ROM
+
+ 17 char OBSOLETE (was Chase serial card)
+ 0 = /dev/ttyH0 First Chase port
+ 1 = /dev/ttyH1 Second Chase port
+ ...
+ 17 block Optics Storage CD-ROM
+ 0 = /dev/optcd Optics Storage CD-ROM
+
+ 18 char OBSOLETE (was Chase serial card - alternate devices)
+ 0 = /dev/cuh0 Callout device for ttyH0
+ 1 = /dev/cuh1 Callout device for ttyH1
+ ...
+ 18 block Sanyo CD-ROM
+ 0 = /dev/sjcd Sanyo CD-ROM
+
+ 19 block "Double" compressed disk
+ 0 = /dev/double0 First compressed disk
+ ...
+ 7 = /dev/double7 Eighth compressed disk
+ 128 = /dev/cdouble0 Mirror of first compressed disk
+ ...
+ 135 = /dev/cdouble7 Mirror of eighth compressed disk
+
+ See the Double documentation for the meaning of the
+ mirror devices.
+
+ 20 block Hitachi CD-ROM (under development)
+ 0 = /dev/hitcd Hitachi CD-ROM
+
+ 21 char Generic SCSI access
+ 0 = /dev/sg0 First generic SCSI device
+ 1 = /dev/sg1 Second generic SCSI device
+ ...
+
+ Most distributions name these /dev/sga, /dev/sgb...;
+ this sets an unnecessary limit of 26 SCSI devices in
+ the system and is counter to standard Linux
+ device-naming practice.
+
+ 21 block Acorn MFM hard drive interface
+ 0 = /dev/mfma First MFM drive whole disk
+ 64 = /dev/mfmb Second MFM drive whole disk
+
+ This device is used on the ARM-based Acorn RiscPC.
+ Partitions are handled the same way as for IDE disks
+ (see major number 3).
+
+ 22 char Digiboard serial card
+ 0 = /dev/ttyD0 First Digiboard port
+ 1 = /dev/ttyD1 Second Digiboard port
+ ...
+ 22 block Second IDE hard disk/CD-ROM interface
+ 0 = /dev/hdc Master: whole disk (or CD-ROM)
+ 64 = /dev/hdd Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 23 char Digiboard serial card - alternate devices
+ 0 = /dev/cud0 Callout device for ttyD0
+ 1 = /dev/cud1 Callout device for ttyD1
+ ...
+ 23 block Mitsumi proprietary CD-ROM
+ 0 = /dev/mcd Mitsumi CD-ROM
+
+ 24 char Stallion serial card
+ 0 = /dev/ttyE0 Stallion port 0 card 0
+ 1 = /dev/ttyE1 Stallion port 1 card 0
+ ...
+ 64 = /dev/ttyE64 Stallion port 0 card 1
+ 65 = /dev/ttyE65 Stallion port 1 card 1
+ ...
+ 128 = /dev/ttyE128 Stallion port 0 card 2
+ 129 = /dev/ttyE129 Stallion port 1 card 2
+ ...
+ 192 = /dev/ttyE192 Stallion port 0 card 3
+ 193 = /dev/ttyE193 Stallion port 1 card 3
+ ...
+ 24 block Sony CDU-535 CD-ROM
+ 0 = /dev/cdu535 Sony CDU-535 CD-ROM
+
+ 25 char Stallion serial card - alternate devices
+ 0 = /dev/cue0 Callout device for ttyE0
+ 1 = /dev/cue1 Callout device for ttyE1
+ ...
+ 64 = /dev/cue64 Callout device for ttyE64
+ 65 = /dev/cue65 Callout device for ttyE65
+ ...
+ 128 = /dev/cue128 Callout device for ttyE128
+ 129 = /dev/cue129 Callout device for ttyE129
+ ...
+ 192 = /dev/cue192 Callout device for ttyE192
+ 193 = /dev/cue193 Callout device for ttyE193
+ ...
+ 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM
+ 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0
+ 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1
+ 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2
+ 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3
+
+ 26 char
+
+ 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM
+ 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0
+ 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1
+ 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2
+ 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3
+
+ 27 char QIC-117 tape
+ 0 = /dev/qft0 Unit 0, rewind-on-close
+ 1 = /dev/qft1 Unit 1, rewind-on-close
+ 2 = /dev/qft2 Unit 2, rewind-on-close
+ 3 = /dev/qft3 Unit 3, rewind-on-close
+ 4 = /dev/nqft0 Unit 0, no rewind-on-close
+ 5 = /dev/nqft1 Unit 1, no rewind-on-close
+ 6 = /dev/nqft2 Unit 2, no rewind-on-close
+ 7 = /dev/nqft3 Unit 3, no rewind-on-close
+ 16 = /dev/zqft0 Unit 0, rewind-on-close, compression
+ 17 = /dev/zqft1 Unit 1, rewind-on-close, compression
+ 18 = /dev/zqft2 Unit 2, rewind-on-close, compression
+ 19 = /dev/zqft3 Unit 3, rewind-on-close, compression
+ 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression
+ 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression
+ 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression
+ 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression
+ 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks
+ 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks
+ 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks
+ 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks
+ 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks
+ 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks
+ 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks
+ 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks
+
+ 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM
+ 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0
+ 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1
+ 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2
+ 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3
+
+ 28 char Stallion serial card - card programming
+ 0 = /dev/staliomem0 First Stallion card I/O memory
+ 1 = /dev/staliomem1 Second Stallion card I/O memory
+ 2 = /dev/staliomem2 Third Stallion card I/O memory
+ 3 = /dev/staliomem3 Fourth Stallion card I/O memory
+
+ 28 char Atari SLM ACSI laser printer (68k/Atari)
+ 0 = /dev/slm0 First SLM laser printer
+ 1 = /dev/slm1 Second SLM laser printer
+ ...
+ 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM
+ 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0
+ 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1
+ 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2
+ 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3
+
+ 28 block ACSI disk (68k/Atari)
+ 0 = /dev/ada First ACSI disk whole disk
+ 16 = /dev/adb Second ACSI disk whole disk
+ 32 = /dev/adc Third ACSI disk whole disk
+ ...
+ 240 = /dev/adp 16th ACSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15, like SCSI.
+
+ 29 char Universal frame buffer
+ 0 = /dev/fb0 First frame buffer
+ 1 = /dev/fb1 Second frame buffer
+ ...
+ 31 = /dev/fb31 32nd frame buffer
+
+ 29 block Aztech/Orchid/Okano/Wearnes CD-ROM
+ 0 = /dev/aztcd Aztech CD-ROM
+
+ 30 char iBCS-2 compatibility devices
+ 0 = /dev/socksys Socket access
+ 1 = /dev/spx SVR3 local X interface
+ 32 = /dev/inet/ip Network access
+ 33 = /dev/inet/icmp
+ 34 = /dev/inet/ggp
+ 35 = /dev/inet/ipip
+ 36 = /dev/inet/tcp
+ 37 = /dev/inet/egp
+ 38 = /dev/inet/pup
+ 39 = /dev/inet/udp
+ 40 = /dev/inet/idp
+ 41 = /dev/inet/rawip
+
+ Additionally, iBCS-2 requires the following links:
+
+ /dev/ip -> /dev/inet/ip
+ /dev/icmp -> /dev/inet/icmp
+ /dev/ggp -> /dev/inet/ggp
+ /dev/ipip -> /dev/inet/ipip
+ /dev/tcp -> /dev/inet/tcp
+ /dev/egp -> /dev/inet/egp
+ /dev/pup -> /dev/inet/pup
+ /dev/udp -> /dev/inet/udp
+ /dev/idp -> /dev/inet/idp
+ /dev/rawip -> /dev/inet/rawip
+ /dev/inet/arp -> /dev/inet/udp
+ /dev/inet/rip -> /dev/inet/udp
+ /dev/nfsd -> /dev/socksys
+ /dev/X0R -> /dev/null (? apparently not required ?)
+
+ 30 block Philips LMS CM-205 CD-ROM
+ 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM
+
+ /dev/lmscd is an older name for this device. This
+ driver does not work with the CM-205MS CD-ROM.
+
+ 31 char MPU-401 MIDI
+ 0 = /dev/mpu401data MPU-401 data port
+ 1 = /dev/mpu401stat MPU-401 status port
+
+ 31 block ROM/flash memory card
+ 0 = /dev/rom0 First ROM card (rw)
+ ...
+ 7 = /dev/rom7 Eighth ROM card (rw)
+ 8 = /dev/rrom0 First ROM card (ro)
+ ...
+ 15 = /dev/rrom7 Eighth ROM card (ro)
+ 16 = /dev/flash0 First flash memory card (rw)
+ ...
+ 23 = /dev/flash7 Eighth flash memory card (rw)
+ 24 = /dev/rflash0 First flash memory card (ro)
+ ...
+ 31 = /dev/rflash7 Eighth flash memory card (ro)
+
+ The read-write (rw) devices support back-caching
+ written data in RAM, as well as writing to flash RAM
+ devices. The read-only devices (ro) support reading
+ only.
+
+ 32 char Specialix serial card
+ 0 = /dev/ttyX0 First Specialix port
+ 1 = /dev/ttyX1 Second Specialix port
+ ...
+ 32 block Philips LMS CM-206 CD-ROM
+ 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM
+
+ 33 char Specialix serial card - alternate devices
+ 0 = /dev/cux0 Callout device for ttyX0
+ 1 = /dev/cux1 Callout device for ttyX1
+ ...
+ 33 block Third IDE hard disk/CD-ROM interface
+ 0 = /dev/hde Master: whole disk (or CD-ROM)
+ 64 = /dev/hdf Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 34 char Z8530 HDLC driver
+ 0 = /dev/scc0 First Z8530, first port
+ 1 = /dev/scc1 First Z8530, second port
+ 2 = /dev/scc2 Second Z8530, first port
+ 3 = /dev/scc3 Second Z8530, second port
+ ...
+
+ In a previous version these devices were named
+ /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so
+ on.
+
+ 34 block Fourth IDE hard disk/CD-ROM interface
+ 0 = /dev/hdg Master: whole disk (or CD-ROM)
+ 64 = /dev/hdh Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 35 char tclmidi MIDI driver
+ 0 = /dev/midi0 First MIDI port, kernel timed
+ 1 = /dev/midi1 Second MIDI port, kernel timed
+ 2 = /dev/midi2 Third MIDI port, kernel timed
+ 3 = /dev/midi3 Fourth MIDI port, kernel timed
+ 64 = /dev/rmidi0 First MIDI port, untimed
+ 65 = /dev/rmidi1 Second MIDI port, untimed
+ 66 = /dev/rmidi2 Third MIDI port, untimed
+ 67 = /dev/rmidi3 Fourth MIDI port, untimed
+ 128 = /dev/smpte0 First MIDI port, SMPTE timed
+ 129 = /dev/smpte1 Second MIDI port, SMPTE timed
+ 130 = /dev/smpte2 Third MIDI port, SMPTE timed
+ 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed
+
+ 35 block Slow memory ramdisk
+ 0 = /dev/slram Slow memory ramdisk
+
+ 36 char Netlink support
+ 0 = /dev/route Routing, device updates, kernel to user
+ 1 = /dev/skip enSKIP security cache control
+ 3 = /dev/fwmonitor Firewall packet copies
+ 16 = /dev/tap0 First Ethertap device
+ ...
+ 31 = /dev/tap15 16th Ethertap device
+
+ 36 block OBSOLETE (was MCA ESDI hard disk)
+
+ 37 char IDE tape
+ 0 = /dev/ht0 First IDE tape
+ 1 = /dev/ht1 Second IDE tape
+ ...
+ 128 = /dev/nht0 First IDE tape, no rewind-on-close
+ 129 = /dev/nht1 Second IDE tape, no rewind-on-close
+ ...
+
+ Currently, only one IDE tape drive is supported.
+
+ 37 block Zorro II ramdisk
+ 0 = /dev/z2ram Zorro II ramdisk
+
+ 38 char Myricom PCI Myrinet board
+ 0 = /dev/mlanai0 First Myrinet board
+ 1 = /dev/mlanai1 Second Myrinet board
+ ...
+
+ This device is used for status query, board control
+ and "user level packet I/O." This board is also
+ accessible as a standard networking "eth" device.
+
+ 38 block OBSOLETE (was Linux/AP+)
+
+ 39 char ML-16P experimental I/O board
+ 0 = /dev/ml16pa-a0 First card, first analog channel
+ 1 = /dev/ml16pa-a1 First card, second analog channel
+ ...
+ 15 = /dev/ml16pa-a15 First card, 16th analog channel
+ 16 = /dev/ml16pa-d First card, digital lines
+ 17 = /dev/ml16pa-c0 First card, first counter/timer
+ 18 = /dev/ml16pa-c1 First card, second counter/timer
+ 19 = /dev/ml16pa-c2 First card, third counter/timer
+ 32 = /dev/ml16pb-a0 Second card, first analog channel
+ 33 = /dev/ml16pb-a1 Second card, second analog channel
+ ...
+ 47 = /dev/ml16pb-a15 Second card, 16th analog channel
+ 48 = /dev/ml16pb-d Second card, digital lines
+ 49 = /dev/ml16pb-c0 Second card, first counter/timer
+ 50 = /dev/ml16pb-c1 Second card, second counter/timer
+ 51 = /dev/ml16pb-c2 Second card, third counter/timer
+ ...
+ 39 block
+
+ 40 char
+
+ 40 block
+
+ 41 char Yet Another Micro Monitor
+ 0 = /dev/yamm Yet Another Micro Monitor
+
+ 41 block
+
+ 42 char Demo/sample use
+
+ 42 block Demo/sample use
+
+ This number is intended for use in sample code, as
+ well as a general "example" device number. It
+ should never be used for a device driver that is being
+ distributed; either obtain an official number or use
+ the local/experimental range. The sudden addition or
+ removal of a driver with this number should not cause
+ ill effects to the system (bugs excepted.)
+
+ IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A
+ DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT.
+
+ 43 char isdn4linux virtual modem
+ 0 = /dev/ttyI0 First virtual modem
+ ...
+ 63 = /dev/ttyI63 64th virtual modem
+
+ 43 block Network block devices
+ 0 = /dev/nb0 First network block device
+ 1 = /dev/nb1 Second network block device
+ ...
+
+ Network Block Device is somehow similar to loopback
+ devices: If you read from it, it sends packet across
+ network asking server for data. If you write to it, it
+ sends packet telling server to write. It could be used
+ to mounting filesystems over the net, swapping over
+ the net, implementing block device in userland etc.
+
+ 44 char isdn4linux virtual modem - alternate devices
+ 0 = /dev/cui0 Callout device for ttyI0
+ ...
+ 63 = /dev/cui63 Callout device for ttyI63
+
+ 44 block Flash Translation Layer (FTL) filesystems
+ 0 = /dev/ftla FTL on first Memory Technology Device
+ 16 = /dev/ftlb FTL on second Memory Technology Device
+ 32 = /dev/ftlc FTL on third Memory Technology Device
+ ...
+ 240 = /dev/ftlp FTL on 16th Memory Technology Device
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the partition
+ limit is 15 rather than 63 per disk (same as SCSI.)
+
+ 45 char isdn4linux ISDN BRI driver
+ 0 = /dev/isdn0 First virtual B channel raw data
+ ...
+ 63 = /dev/isdn63 64th virtual B channel raw data
+ 64 = /dev/isdnctrl0 First channel control/debug
+ ...
+ 127 = /dev/isdnctrl63 64th channel control/debug
+
+ 128 = /dev/ippp0 First SyncPPP device
+ ...
+ 191 = /dev/ippp63 64th SyncPPP device
+
+ 255 = /dev/isdninfo ISDN monitor interface
+
+ 45 block Parallel port IDE disk devices
+ 0 = /dev/pda First parallel port IDE disk
+ 16 = /dev/pdb Second parallel port IDE disk
+ 32 = /dev/pdc Third parallel port IDE disk
+ 48 = /dev/pdd Fourth parallel port IDE disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the partition
+ limit is 15 rather than 63 per disk.
+
+ 46 char Comtrol Rocketport serial card
+ 0 = /dev/ttyR0 First Rocketport port
+ 1 = /dev/ttyR1 Second Rocketport port
+ ...
+ 46 block Parallel port ATAPI CD-ROM devices
+ 0 = /dev/pcd0 First parallel port ATAPI CD-ROM
+ 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM
+ 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM
+ 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM
+
+ 47 char Comtrol Rocketport serial card - alternate devices
+ 0 = /dev/cur0 Callout device for ttyR0
+ 1 = /dev/cur1 Callout device for ttyR1
+ ...
+ 47 block Parallel port ATAPI disk devices
+ 0 = /dev/pf0 First parallel port ATAPI disk
+ 1 = /dev/pf1 Second parallel port ATAPI disk
+ 2 = /dev/pf2 Third parallel port ATAPI disk
+ 3 = /dev/pf3 Fourth parallel port ATAPI disk
+
+ This driver is intended for floppy disks and similar
+ devices and hence does not support partitioning.
+
+ 48 char SDL RISCom serial card
+ 0 = /dev/ttyL0 First RISCom port
+ 1 = /dev/ttyL1 Second RISCom port
+ ...
+ 48 block Mylex DAC960 PCI RAID controller; first controller
+ 0 = /dev/rd/c0d0 First disk, whole disk
+ 8 = /dev/rd/c0d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c0d31 32nd disk, whole disk
+
+ For partitions add:
+ 0 = /dev/rd/c?d? Whole disk
+ 1 = /dev/rd/c?d?p1 First partition
+ ...
+ 7 = /dev/rd/c?d?p7 Seventh partition
+
+ 49 char SDL RISCom serial card - alternate devices
+ 0 = /dev/cul0 Callout device for ttyL0
+ 1 = /dev/cul1 Callout device for ttyL1
+ ...
+ 49 block Mylex DAC960 PCI RAID controller; second controller
+ 0 = /dev/rd/c1d0 First disk, whole disk
+ 8 = /dev/rd/c1d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c1d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 50 char Reserved for GLINT
+
+ 50 block Mylex DAC960 PCI RAID controller; third controller
+ 0 = /dev/rd/c2d0 First disk, whole disk
+ 8 = /dev/rd/c2d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c2d31 32nd disk, whole disk
+
+ 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem
+ 0 = /dev/bc0 First Baycom radio modem
+ 1 = /dev/bc1 Second Baycom radio modem
+ ...
+ 51 block Mylex DAC960 PCI RAID controller; fourth controller
+ 0 = /dev/rd/c3d0 First disk, whole disk
+ 8 = /dev/rd/c3d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c3d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 52 char Spellcaster DataComm/BRI ISDN card
+ 0 = /dev/dcbri0 First DataComm card
+ 1 = /dev/dcbri1 Second DataComm card
+ 2 = /dev/dcbri2 Third DataComm card
+ 3 = /dev/dcbri3 Fourth DataComm card
+
+ 52 block Mylex DAC960 PCI RAID controller; fifth controller
+ 0 = /dev/rd/c4d0 First disk, whole disk
+ 8 = /dev/rd/c4d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c4d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 53 char BDM interface for remote debugging MC683xx microcontrollers
+ 0 = /dev/pd_bdm0 PD BDM interface on lp0
+ 1 = /dev/pd_bdm1 PD BDM interface on lp1
+ 2 = /dev/pd_bdm2 PD BDM interface on lp2
+ 4 = /dev/icd_bdm0 ICD BDM interface on lp0
+ 5 = /dev/icd_bdm1 ICD BDM interface on lp1
+ 6 = /dev/icd_bdm2 ICD BDM interface on lp2
+
+ This device is used for the interfacing to the MC683xx
+ microcontrollers via Background Debug Mode by use of a
+ Parallel Port interface. PD is the Motorola Public
+ Domain Interface and ICD is the commercial interface
+ by P&E.
+
+ 53 block Mylex DAC960 PCI RAID controller; sixth controller
+ 0 = /dev/rd/c5d0 First disk, whole disk
+ 8 = /dev/rd/c5d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c5d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 54 char Electrocardiognosis Holter serial card
+ 0 = /dev/holter0 First Holter port
+ 1 = /dev/holter1 Second Holter port
+ 2 = /dev/holter2 Third Holter port
+
+ A custom serial card used by Electrocardiognosis SRL
+ <mseritan@ottonel.pub.ro> to transfer data from Holter
+ 24-hour heart monitoring equipment.
+
+ 54 block Mylex DAC960 PCI RAID controller; seventh controller
+ 0 = /dev/rd/c6d0 First disk, whole disk
+ 8 = /dev/rd/c6d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c6d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 55 char DSP56001 digital signal processor
+ 0 = /dev/dsp56k First DSP56001
+
+ 55 block Mylex DAC960 PCI RAID controller; eighth controller
+ 0 = /dev/rd/c7d0 First disk, whole disk
+ 8 = /dev/rd/c7d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c7d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 56 char Apple Desktop Bus
+ 0 = /dev/adb ADB bus control
+
+ Additional devices will be added to this number, all
+ starting with /dev/adb.
+
+ 56 block Fifth IDE hard disk/CD-ROM interface
+ 0 = /dev/hdi Master: whole disk (or CD-ROM)
+ 64 = /dev/hdj Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 57 char Hayes ESP serial card
+ 0 = /dev/ttyP0 First ESP port
+ 1 = /dev/ttyP1 Second ESP port
+ ...
+
+ 57 block Sixth IDE hard disk/CD-ROM interface
+ 0 = /dev/hdk Master: whole disk (or CD-ROM)
+ 64 = /dev/hdl Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 58 char Hayes ESP serial card - alternate devices
+ 0 = /dev/cup0 Callout device for ttyP0
+ 1 = /dev/cup1 Callout device for ttyP1
+ ...
+
+ 58 block Reserved for logical volume manager
+
+ 59 char sf firewall package
+ 0 = /dev/firewall Communication with sf kernel module
+
+ 59 block Generic PDA filesystem device
+ 0 = /dev/pda0 First PDA device
+ 1 = /dev/pda1 Second PDA device
+ ...
+
+ The pda devices are used to mount filesystems on
+ remote pda's (basically slow handheld machines with
+ proprietary OS's and limited memory and storage
+ running small fs translation drivers) through serial /
+ IRDA / parallel links.
+
+ NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc
+
+ 60-63 char LOCAL/EXPERIMENTAL USE
+
+ 60-63 block LOCAL/EXPERIMENTAL USE
+ Allocated for local/experimental use. For devices not
+ assigned official numbers, these ranges should be
+ used in order to avoid conflicting with future assignments.
+
+ 64 char ENskip kernel encryption package
+ 0 = /dev/enskip Communication with ENskip kernel module
+
+ 64 block Scramdisk/DriveCrypt encrypted devices
+ 0 = /dev/scramdisk/master Master node for ioctls
+ 1 = /dev/scramdisk/1 First encrypted device
+ 2 = /dev/scramdisk/2 Second encrypted device
+ ...
+ 255 = /dev/scramdisk/255 255th encrypted device
+
+ The filename of the encrypted container and the passwords
+ are sent via ioctls (using the sdmount tool) to the master
+ node which then activates them via one of the
+ /dev/scramdisk/x nodes for loop mounting (all handled
+ through the sdmount tool).
+
+ Requested by: andy@scramdisklinux.org
+
+ 65 char Sundance "plink" Transputer boards (obsolete, unused)
+ 0 = /dev/plink0 First plink device
+ 1 = /dev/plink1 Second plink device
+ 2 = /dev/plink2 Third plink device
+ 3 = /dev/plink3 Fourth plink device
+ 64 = /dev/rplink0 First plink device, raw
+ 65 = /dev/rplink1 Second plink device, raw
+ 66 = /dev/rplink2 Third plink device, raw
+ 67 = /dev/rplink3 Fourth plink device, raw
+ 128 = /dev/plink0d First plink device, debug
+ 129 = /dev/plink1d Second plink device, debug
+ 130 = /dev/plink2d Third plink device, debug
+ 131 = /dev/plink3d Fourth plink device, debug
+ 192 = /dev/rplink0d First plink device, raw, debug
+ 193 = /dev/rplink1d Second plink device, raw, debug
+ 194 = /dev/rplink2d Third plink device, raw, debug
+ 195 = /dev/rplink3d Fourth plink device, raw, debug
+
+ This is a commercial driver; contact James Howes
+ <jth@prosig.demon.co.uk> for information.
+
+ 65 block SCSI disk devices (16-31)
+ 0 = /dev/sdq 17th SCSI disk whole disk
+ 16 = /dev/sdr 18th SCSI disk whole disk
+ 32 = /dev/sds 19th SCSI disk whole disk
+ ...
+ 240 = /dev/sdaf 32nd SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 66 char YARC PowerPC PCI coprocessor card
+ 0 = /dev/yppcpci0 First YARC card
+ 1 = /dev/yppcpci1 Second YARC card
+ ...
+
+ 66 block SCSI disk devices (32-47)
+ 0 = /dev/sdag 33th SCSI disk whole disk
+ 16 = /dev/sdah 34th SCSI disk whole disk
+ 32 = /dev/sdai 35th SCSI disk whole disk
+ ...
+ 240 = /dev/sdav 48nd SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 67 char Coda network file system
+ 0 = /dev/cfs0 Coda cache manager
+
+ See http://www.coda.cs.cmu.edu for information about Coda.
+
+ 67 block SCSI disk devices (48-63)
+ 0 = /dev/sdaw 49th SCSI disk whole disk
+ 16 = /dev/sdax 50th SCSI disk whole disk
+ 32 = /dev/sday 51st SCSI disk whole disk
+ ...
+ 240 = /dev/sdbl 64th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 68 char CAPI 2.0 interface
+ 0 = /dev/capi20 Control device
+ 1 = /dev/capi20.00 First CAPI 2.0 application
+ 2 = /dev/capi20.01 Second CAPI 2.0 application
+ ...
+ 20 = /dev/capi20.19 19th CAPI 2.0 application
+
+ ISDN CAPI 2.0 driver for use with CAPI 2.0
+ applications; currently supports the AVM B1 card.
+
+ 68 block SCSI disk devices (64-79)
+ 0 = /dev/sdbm 65th SCSI disk whole disk
+ 16 = /dev/sdbn 66th SCSI disk whole disk
+ 32 = /dev/sdbo 67th SCSI disk whole disk
+ ...
+ 240 = /dev/sdcb 80th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 69 char MA16 numeric accelerator card
+ 0 = /dev/ma16 Board memory access
+
+ 69 block SCSI disk devices (80-95)
+ 0 = /dev/sdcc 81st SCSI disk whole disk
+ 16 = /dev/sdcd 82nd SCSI disk whole disk
+ 32 = /dev/sdce 83th SCSI disk whole disk
+ ...
+ 240 = /dev/sdcr 96th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 70 char SpellCaster Protocol Services Interface
+ 0 = /dev/apscfg Configuration interface
+ 1 = /dev/apsauth Authentication interface
+ 2 = /dev/apslog Logging interface
+ 3 = /dev/apsdbg Debugging interface
+ 64 = /dev/apsisdn ISDN command interface
+ 65 = /dev/apsasync Async command interface
+ 128 = /dev/apsmon Monitor interface
+
+ 70 block SCSI disk devices (96-111)
+ 0 = /dev/sdcs 97th SCSI disk whole disk
+ 16 = /dev/sdct 98th SCSI disk whole disk
+ 32 = /dev/sdcu 99th SCSI disk whole disk
+ ...
+ 240 = /dev/sddh 112nd SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 71 char Computone IntelliPort II serial card
+ 0 = /dev/ttyF0 IntelliPort II board 0, port 0
+ 1 = /dev/ttyF1 IntelliPort II board 0, port 1
+ ...
+ 63 = /dev/ttyF63 IntelliPort II board 0, port 63
+ 64 = /dev/ttyF64 IntelliPort II board 1, port 0
+ 65 = /dev/ttyF65 IntelliPort II board 1, port 1
+ ...
+ 127 = /dev/ttyF127 IntelliPort II board 1, port 63
+ 128 = /dev/ttyF128 IntelliPort II board 2, port 0
+ 129 = /dev/ttyF129 IntelliPort II board 2, port 1
+ ...
+ 191 = /dev/ttyF191 IntelliPort II board 2, port 63
+ 192 = /dev/ttyF192 IntelliPort II board 3, port 0
+ 193 = /dev/ttyF193 IntelliPort II board 3, port 1
+ ...
+ 255 = /dev/ttyF255 IntelliPort II board 3, port 63
+
+ 71 block SCSI disk devices (112-127)
+ 0 = /dev/sddi 113th SCSI disk whole disk
+ 16 = /dev/sddj 114th SCSI disk whole disk
+ 32 = /dev/sddk 115th SCSI disk whole disk
+ ...
+ 240 = /dev/sddx 128th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 72 char Computone IntelliPort II serial card - alternate devices
+ 0 = /dev/cuf0 Callout device for ttyF0
+ 1 = /dev/cuf1 Callout device for ttyF1
+ ...
+ 63 = /dev/cuf63 Callout device for ttyF63
+ 64 = /dev/cuf64 Callout device for ttyF64
+ 65 = /dev/cuf65 Callout device for ttyF65
+ ...
+ 127 = /dev/cuf127 Callout device for ttyF127
+ 128 = /dev/cuf128 Callout device for ttyF128
+ 129 = /dev/cuf129 Callout device for ttyF129
+ ...
+ 191 = /dev/cuf191 Callout device for ttyF191
+ 192 = /dev/cuf192 Callout device for ttyF192
+ 193 = /dev/cuf193 Callout device for ttyF193
+ ...
+ 255 = /dev/cuf255 Callout device for ttyF255
+
+ 72 block Compaq Intelligent Drive Array, first controller
+ 0 = /dev/ida/c0d0 First logical drive whole disk
+ 16 = /dev/ida/c0d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c0d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 73 char Computone IntelliPort II serial card - control devices
+ 0 = /dev/ip2ipl0 Loadware device for board 0
+ 1 = /dev/ip2stat0 Status device for board 0
+ 4 = /dev/ip2ipl1 Loadware device for board 1
+ 5 = /dev/ip2stat1 Status device for board 1
+ 8 = /dev/ip2ipl2 Loadware device for board 2
+ 9 = /dev/ip2stat2 Status device for board 2
+ 12 = /dev/ip2ipl3 Loadware device for board 3
+ 13 = /dev/ip2stat3 Status device for board 3
+
+ 73 block Compaq Intelligent Drive Array, second controller
+ 0 = /dev/ida/c1d0 First logical drive whole disk
+ 16 = /dev/ida/c1d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c1d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 74 char SCI bridge
+ 0 = /dev/SCI/0 SCI device 0
+ 1 = /dev/SCI/1 SCI device 1
+ ...
+
+ Currently for Dolphin Interconnect Solutions' PCI-SCI
+ bridge.
+
+ 74 block Compaq Intelligent Drive Array, third controller
+ 0 = /dev/ida/c2d0 First logical drive whole disk
+ 16 = /dev/ida/c2d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c2d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 75 char Specialix IO8+ serial card
+ 0 = /dev/ttyW0 First IO8+ port, first card
+ 1 = /dev/ttyW1 Second IO8+ port, first card
+ ...
+ 8 = /dev/ttyW8 First IO8+ port, second card
+ ...
+
+ 75 block Compaq Intelligent Drive Array, fourth controller
+ 0 = /dev/ida/c3d0 First logical drive whole disk
+ 16 = /dev/ida/c3d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c3d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 76 char Specialix IO8+ serial card - alternate devices
+ 0 = /dev/cuw0 Callout device for ttyW0
+ 1 = /dev/cuw1 Callout device for ttyW1
+ ...
+ 8 = /dev/cuw8 Callout device for ttyW8
+ ...
+
+ 76 block Compaq Intelligent Drive Array, fifth controller
+ 0 = /dev/ida/c4d0 First logical drive whole disk
+ 16 = /dev/ida/c4d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c4d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+
+ 77 char ComScire Quantum Noise Generator
+ 0 = /dev/qng ComScire Quantum Noise Generator
+
+ 77 block Compaq Intelligent Drive Array, sixth controller
+ 0 = /dev/ida/c5d0 First logical drive whole disk
+ 16 = /dev/ida/c5d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c5d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 78 char PAM Software's multimodem boards
+ 0 = /dev/ttyM0 First PAM modem
+ 1 = /dev/ttyM1 Second PAM modem
+ ...
+
+ 78 block Compaq Intelligent Drive Array, seventh controller
+ 0 = /dev/ida/c6d0 First logical drive whole disk
+ 16 = /dev/ida/c6d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c6d15 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 79 char PAM Software's multimodem boards - alternate devices
+ 0 = /dev/cum0 Callout device for ttyM0
+ 1 = /dev/cum1 Callout device for ttyM1
+ ...
+
+ 79 block Compaq Intelligent Drive Array, eighth controller
+ 0 = /dev/ida/c7d0 First logical drive whole disk
+ 16 = /dev/ida/c7d1 Second logical drive whole disk
+ ...
+ 240 = /dev/ida/c715 16th logical drive whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 80 char Photometrics AT200 CCD camera
+ 0 = /dev/at200 Photometrics AT200 CCD camera
+
+ 80 block I2O hard disk
+ 0 = /dev/i2o/hda First I2O hard disk, whole disk
+ 16 = /dev/i2o/hdb Second I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 81 char video4linux
+ 0 = /dev/video0 Video capture/overlay device
+ ...
+ 63 = /dev/video63 Video capture/overlay device
+ 64 = /dev/radio0 Radio device
+ ...
+ 127 = /dev/radio63 Radio device
+ 128 = /dev/swradio0 Software Defined Radio device
+ ...
+ 191 = /dev/swradio63 Software Defined Radio device
+ 224 = /dev/vbi0 Vertical blank interrupt
+ ...
+ 255 = /dev/vbi31 Vertical blank interrupt
+
+ Minor numbers are allocated dynamically unless
+ CONFIG_VIDEO_FIXED_MINOR_RANGES (default n)
+ configuration option is set.
+
+ 81 block I2O hard disk
+ 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk
+ 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 82 char WiNRADiO communications receiver card
+ 0 = /dev/winradio0 First WiNRADiO card
+ 1 = /dev/winradio1 Second WiNRADiO card
+ ...
+
+ The driver and documentation may be obtained from
+ https://www.winradio.com/
+
+ 82 block I2O hard disk
+ 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk
+ 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 83 char Matrox mga_vid video driver
+ 0 = /dev/mga_vid0 1st video card
+ 1 = /dev/mga_vid1 2nd video card
+ 2 = /dev/mga_vid2 3rd video card
+ ...
+ 15 = /dev/mga_vid15 16th video card
+
+ 83 block I2O hard disk
+ 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk
+ 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 84 char Ikon 1011[57] Versatec Greensheet Interface
+ 0 = /dev/ihcp0 First Greensheet port
+ 1 = /dev/ihcp1 Second Greensheet port
+
+ 84 block I2O hard disk
+ 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk
+ 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 85 char Linux/SGI shared memory input queue
+ 0 = /dev/shmiq Master shared input queue
+ 1 = /dev/qcntl0 First device pushed
+ 2 = /dev/qcntl1 Second device pushed
+ ...
+
+ 85 block I2O hard disk
+ 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk
+ 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 86 char SCSI media changer
+ 0 = /dev/sch0 First SCSI media changer
+ 1 = /dev/sch1 Second SCSI media changer
+ ...
+
+ 86 block I2O hard disk
+ 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk
+ 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 87 char Sony Control-A1 stereo control bus
+ 0 = /dev/controla0 First device on chain
+ 1 = /dev/controla1 Second device on chain
+ ...
+
+ 87 block I2O hard disk
+ 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk
+ 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk
+ ...
+ 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 88 char COMX synchronous serial card
+ 0 = /dev/comx0 COMX channel 0
+ 1 = /dev/comx1 COMX channel 1
+ ...
+
+ 88 block Seventh IDE hard disk/CD-ROM interface
+ 0 = /dev/hdm Master: whole disk (or CD-ROM)
+ 64 = /dev/hdn Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 89 char I2C bus interface
+ 0 = /dev/i2c-0 First I2C adapter
+ 1 = /dev/i2c-1 Second I2C adapter
+ ...
+
+ 89 block Eighth IDE hard disk/CD-ROM interface
+ 0 = /dev/hdo Master: whole disk (or CD-ROM)
+ 64 = /dev/hdp Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 90 char Memory Technology Device (RAM, ROM, Flash)
+ 0 = /dev/mtd0 First MTD (rw)
+ 1 = /dev/mtdr0 First MTD (ro)
+ ...
+ 30 = /dev/mtd15 16th MTD (rw)
+ 31 = /dev/mtdr15 16th MTD (ro)
+
+ 90 block Ninth IDE hard disk/CD-ROM interface
+ 0 = /dev/hdq Master: whole disk (or CD-ROM)
+ 64 = /dev/hdr Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 91 char CAN-Bus devices
+ 0 = /dev/can0 First CAN-Bus controller
+ 1 = /dev/can1 Second CAN-Bus controller
+ ...
+
+ 91 block Tenth IDE hard disk/CD-ROM interface
+ 0 = /dev/hds Master: whole disk (or CD-ROM)
+ 64 = /dev/hdt Slave: whole disk (or CD-ROM)
+
+ Partitions are handled the same way as for the first
+ interface (see major number 3).
+
+ 92 char Reserved for ith Kommunikationstechnik MIC ISDN card
+
+ 92 block PPDD encrypted disk driver
+ 0 = /dev/ppdd0 First encrypted disk
+ 1 = /dev/ppdd1 Second encrypted disk
+ ...
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 93 char
+
+ 93 block NAND Flash Translation Layer filesystem
+ 0 = /dev/nftla First NFTL layer
+ 16 = /dev/nftlb Second NFTL layer
+ ...
+ 240 = /dev/nftlp 16th NTFL layer
+
+ 94 char
+
+ 94 block IBM S/390 DASD block storage
+ 0 = /dev/dasda First DASD device, major
+ 1 = /dev/dasda1 First DASD device, block 1
+ 2 = /dev/dasda2 First DASD device, block 2
+ 3 = /dev/dasda3 First DASD device, block 3
+ 4 = /dev/dasdb Second DASD device, major
+ 5 = /dev/dasdb1 Second DASD device, block 1
+ 6 = /dev/dasdb2 Second DASD device, block 2
+ 7 = /dev/dasdb3 Second DASD device, block 3
+ ...
+
+ 95 char IP filter
+ 0 = /dev/ipl Filter control device/log file
+ 1 = /dev/ipnat NAT control device/log file
+ 2 = /dev/ipstate State information log file
+ 3 = /dev/ipauth Authentication control device/log file
+ ...
+
+ 96 char Parallel port ATAPI tape devices
+ 0 = /dev/pt0 First parallel port ATAPI tape
+ 1 = /dev/pt1 Second parallel port ATAPI tape
+ ...
+ 128 = /dev/npt0 First p.p. ATAPI tape, no rewind
+ 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind
+ ...
+
+ 96 block Inverse NAND Flash Translation Layer
+ 0 = /dev/inftla First INFTL layer
+ 16 = /dev/inftlb Second INFTL layer
+ ...
+ 240 = /dev/inftlp 16th INTFL layer
+
+ 97 char Parallel port generic ATAPI interface
+ 0 = /dev/pg0 First parallel port ATAPI device
+ 1 = /dev/pg1 Second parallel port ATAPI device
+ 2 = /dev/pg2 Third parallel port ATAPI device
+ 3 = /dev/pg3 Fourth parallel port ATAPI device
+
+ These devices support the same API as the generic SCSI
+ devices.
+
+ 98 char Control and Measurement Device (comedi)
+ 0 = /dev/comedi0 First comedi device
+ 1 = /dev/comedi1 Second comedi device
+ ...
+ 47 = /dev/comedi47 48th comedi device
+
+ Minors 48 to 255 are reserved for comedi subdevices with
+ pathnames of the form "/dev/comediX_subdY", where "X" is the
+ minor number of the associated comedi device and "Y" is the
+ subdevice number. These subdevice minors are assigned
+ dynamically, so there is no fixed mapping from subdevice
+ pathnames to minor numbers.
+
+ See https://www.comedi.org/ for information about the Comedi
+ project.
+
+ 98 block User-mode virtual block device
+ 0 = /dev/ubda First user-mode block device
+ 16 = /dev/ubdb Second user-mode block device
+ ...
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ This device is used by the user-mode virtual kernel port.
+
+ 99 char Raw parallel ports
+ 0 = /dev/parport0 First parallel port
+ 1 = /dev/parport1 Second parallel port
+ ...
+
+ 99 block JavaStation flash disk
+ 0 = /dev/jsfd JavaStation flash disk
+
+ 100 char Telephony for Linux
+ 0 = /dev/phone0 First telephony device
+ 1 = /dev/phone1 Second telephony device
+ ...
+
+ 101 char Motorola DSP 56xxx board
+ 0 = /dev/mdspstat Status information
+ 1 = /dev/mdsp1 First DSP board I/O controls
+ ...
+ 16 = /dev/mdsp16 16th DSP board I/O controls
+
+ 101 block AMI HyperDisk RAID controller
+ 0 = /dev/amiraid/ar0 First array whole disk
+ 16 = /dev/amiraid/ar1 Second array whole disk
+ ...
+ 240 = /dev/amiraid/ar15 16th array whole disk
+
+ For each device, partitions are added as:
+ 0 = /dev/amiraid/ar? Whole disk
+ 1 = /dev/amiraid/ar?p1 First partition
+ 2 = /dev/amiraid/ar?p2 Second partition
+ ...
+ 15 = /dev/amiraid/ar?p15 15th partition
+
+ 102 char
+
+ 102 block Compressed block device
+ 0 = /dev/cbd/a First compressed block device, whole device
+ 16 = /dev/cbd/b Second compressed block device, whole device
+ ...
+ 240 = /dev/cbd/p 16th compressed block device, whole device
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 103 char Arla network file system
+ 0 = /dev/nnpfs0 First NNPFS device
+ 1 = /dev/nnpfs1 Second NNPFS device
+
+ Arla is a free clone of the Andrew File System, AFS.
+ The NNPFS device gives user mode filesystem
+ implementations a kernel presence for caching and easy
+ mounting. For more information about the project,
+ write to <arla-drinkers@stacken.kth.se> or see
+ https://www.stacken.kth.se/project/arla/
+
+ 103 block Audit device
+ 0 = /dev/audit Audit device
+
+ 104 char Flash BIOS support
+
+ 104 block Compaq Next Generation Drive Array, first controller
+ 0 = /dev/cciss/c0d0 First logical drive, whole disk
+ 16 = /dev/cciss/c0d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c0d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 105 char Comtrol VS-1000 serial controller
+ 0 = /dev/ttyV0 First VS-1000 port
+ 1 = /dev/ttyV1 Second VS-1000 port
+ ...
+
+ 105 block Compaq Next Generation Drive Array, second controller
+ 0 = /dev/cciss/c1d0 First logical drive, whole disk
+ 16 = /dev/cciss/c1d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c1d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 106 char Comtrol VS-1000 serial controller - alternate devices
+ 0 = /dev/cuv0 First VS-1000 port
+ 1 = /dev/cuv1 Second VS-1000 port
+ ...
+
+ 106 block Compaq Next Generation Drive Array, third controller
+ 0 = /dev/cciss/c2d0 First logical drive, whole disk
+ 16 = /dev/cciss/c2d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c2d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 107 char 3Dfx Voodoo Graphics device
+ 0 = /dev/3dfx Primary 3Dfx graphics device
+
+ 107 block Compaq Next Generation Drive Array, fourth controller
+ 0 = /dev/cciss/c3d0 First logical drive, whole disk
+ 16 = /dev/cciss/c3d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c3d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 108 char Device independent PPP interface
+ 0 = /dev/ppp Device independent PPP interface
+
+ 108 block Compaq Next Generation Drive Array, fifth controller
+ 0 = /dev/cciss/c4d0 First logical drive, whole disk
+ 16 = /dev/cciss/c4d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c4d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 109 char Reserved for logical volume manager
+
+ 109 block Compaq Next Generation Drive Array, sixth controller
+ 0 = /dev/cciss/c5d0 First logical drive, whole disk
+ 16 = /dev/cciss/c5d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c5d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 110 char miroMEDIA Surround board
+ 0 = /dev/srnd0 First miroMEDIA Surround board
+ 1 = /dev/srnd1 Second miroMEDIA Surround board
+ ...
+
+ 110 block Compaq Next Generation Drive Array, seventh controller
+ 0 = /dev/cciss/c6d0 First logical drive, whole disk
+ 16 = /dev/cciss/c6d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c6d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 111 char
+
+ 111 block Compaq Next Generation Drive Array, eighth controller
+ 0 = /dev/cciss/c7d0 First logical drive, whole disk
+ 16 = /dev/cciss/c7d1 Second logical drive, whole disk
+ ...
+ 240 = /dev/cciss/c7d15 16th logical drive, whole disk
+
+ Partitions are handled the same way as for Mylex
+ DAC960 (see major number 48) except that the limit on
+ partitions is 15.
+
+ 112 char ISI serial card
+ 0 = /dev/ttyM0 First ISI port
+ 1 = /dev/ttyM1 Second ISI port
+ ...
+
+ There is currently a device-naming conflict between
+ these and PAM multimodems (major 78).
+
+ 112 block IBM iSeries virtual disk
+ 0 = /dev/iseries/vda First virtual disk, whole disk
+ 8 = /dev/iseries/vdb Second virtual disk, whole disk
+ ...
+ 200 = /dev/iseries/vdz 26th virtual disk, whole disk
+ 208 = /dev/iseries/vdaa 27th virtual disk, whole disk
+ ...
+ 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 7.
+
+ 113 char ISI serial card - alternate devices
+ 0 = /dev/cum0 Callout device for ttyM0
+ 1 = /dev/cum1 Callout device for ttyM1
+ ...
+
+ 113 block IBM iSeries virtual CD-ROM
+ 0 = /dev/iseries/vcda First virtual CD-ROM
+ 1 = /dev/iseries/vcdb Second virtual CD-ROM
+ ...
+
+ 114 char Picture Elements ISE board
+ 0 = /dev/ise0 First ISE board
+ 1 = /dev/ise1 Second ISE board
+ ...
+ 128 = /dev/isex0 Control node for first ISE board
+ 129 = /dev/isex1 Control node for second ISE board
+ ...
+
+ The ISE board is an embedded computer, optimized for
+ image processing. The /dev/iseN nodes are the general
+ I/O access to the board, the /dev/isex0 nodes command
+ nodes used to control the board.
+
+ 114 block IDE BIOS powered software RAID interfaces such as the
+ Promise Fastrak
+
+ 0 = /dev/ataraid/d0
+ 1 = /dev/ataraid/d0p1
+ 2 = /dev/ataraid/d0p2
+ ...
+ 16 = /dev/ataraid/d1
+ 17 = /dev/ataraid/d1p1
+ 18 = /dev/ataraid/d1p2
+ ...
+ 255 = /dev/ataraid/d15p15
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 115 char TI link cable devices (115 was formerly the console driver speaker)
+ 0 = /dev/tipar0 Parallel cable on first parallel port
+ ...
+ 7 = /dev/tipar7 Parallel cable on seventh parallel port
+
+ 8 = /dev/tiser0 Serial cable on first serial port
+ ...
+ 15 = /dev/tiser7 Serial cable on seventh serial port
+
+ 16 = /dev/tiusb0 First USB cable
+ ...
+ 47 = /dev/tiusb31 32nd USB cable
+
+ 115 block NetWare (NWFS) Devices (0-255)
+
+ The NWFS (NetWare) devices are used to present a
+ collection of NetWare Mirror Groups or NetWare
+ Partitions as a logical storage segment for
+ use in mounting NetWare volumes. A maximum of
+ 256 NetWare volumes can be supported in a single
+ machine.
+
+ http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/
+
+ 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume
+ 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume
+ 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume
+ ...
+ 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume
+
+ 116 char Advanced Linux Sound Driver (ALSA)
+
+ 116 block MicroMemory battery backed RAM adapter (NVRAM)
+ Supports 16 boards, 15 partitions each.
+ Requested by neilb at cse.unsw.edu.au.
+
+ 0 = /dev/umem/d0 Whole of first board
+ 1 = /dev/umem/d0p1 First partition of first board
+ 2 = /dev/umem/d0p2 Second partition of first board
+ 15 = /dev/umem/d0p15 15th partition of first board
+
+ 16 = /dev/umem/d1 Whole of second board
+ 17 = /dev/umem/d1p1 First partition of second board
+ ...
+ 255= /dev/umem/d15p15 15th partition of 16th board.
+
+ 117 char [REMOVED] COSA/SRP synchronous serial card
+ 0 = /dev/cosa0c0 1st board, 1st channel
+ 1 = /dev/cosa0c1 1st board, 2nd channel
+ ...
+ 16 = /dev/cosa1c0 2nd board, 1st channel
+ 17 = /dev/cosa1c1 2nd board, 2nd channel
+ ...
+
+ 117 block Enterprise Volume Management System (EVMS)
+
+ The EVMS driver uses a layered, plug-in model to provide
+ unparalleled flexibility and extensibility in managing
+ storage. This allows for easy expansion or customization
+ of various levels of volume management. Requested by
+ Mark Peloquin (peloquin at us.ibm.com).
+
+ Note: EVMS populates and manages all the devnodes in
+ /dev/evms.
+
+ http://sf.net/projects/evms
+
+ 0 = /dev/evms/block_device EVMS block device
+ 1 = /dev/evms/legacyname1 First EVMS legacy device
+ 2 = /dev/evms/legacyname2 Second EVMS legacy device
+ ...
+ Both ranges can grow (down or up) until they meet.
+ ...
+ 254 = /dev/evms/EVMSname2 Second EVMS native device
+ 255 = /dev/evms/EVMSname1 First EVMS native device
+
+ Note: legacyname(s) are derived from the normal legacy
+ device names. For example, /dev/hda5 would become
+ /dev/evms/hda5.
+
+ 118 char IBM Cryptographic Accelerator
+ 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators
+ 1 = /dev/ica0 IBMCA Device 0
+ 2 = /dev/ica1 IBMCA Device 1
+ ...
+
+ 119 char VMware virtual network control
+ 0 = /dev/vnet0 1st virtual network
+ 1 = /dev/vnet1 2nd virtual network
+ ...
+
+ 120-127 char LOCAL/EXPERIMENTAL USE
+
+ 120-127 block LOCAL/EXPERIMENTAL USE
+ Allocated for local/experimental use. For devices not
+ assigned official numbers, these ranges should be
+ used in order to avoid conflicting with future assignments.
+
+ 128-135 char Unix98 PTY masters
+
+ These devices should not have corresponding device
+ nodes; instead they should be accessed through the
+ /dev/ptmx cloning interface.
+
+ 128 block SCSI disk devices (128-143)
+ 0 = /dev/sddy 129th SCSI disk whole disk
+ 16 = /dev/sddz 130th SCSI disk whole disk
+ 32 = /dev/sdea 131th SCSI disk whole disk
+ ...
+ 240 = /dev/sden 144th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 129 block SCSI disk devices (144-159)
+ 0 = /dev/sdeo 145th SCSI disk whole disk
+ 16 = /dev/sdep 146th SCSI disk whole disk
+ 32 = /dev/sdeq 147th SCSI disk whole disk
+ ...
+ 240 = /dev/sdfd 160th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 130 char (Misc devices)
+
+ 130 block SCSI disk devices (160-175)
+ 0 = /dev/sdfe 161st SCSI disk whole disk
+ 16 = /dev/sdff 162nd SCSI disk whole disk
+ 32 = /dev/sdfg 163rd SCSI disk whole disk
+ ...
+ 240 = /dev/sdft 176th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 131 block SCSI disk devices (176-191)
+ 0 = /dev/sdfu 177th SCSI disk whole disk
+ 16 = /dev/sdfv 178th SCSI disk whole disk
+ 32 = /dev/sdfw 179th SCSI disk whole disk
+ ...
+ 240 = /dev/sdgj 192nd SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 132 block SCSI disk devices (192-207)
+ 0 = /dev/sdgk 193rd SCSI disk whole disk
+ 16 = /dev/sdgl 194th SCSI disk whole disk
+ 32 = /dev/sdgm 195th SCSI disk whole disk
+ ...
+ 240 = /dev/sdgz 208th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 133 block SCSI disk devices (208-223)
+ 0 = /dev/sdha 209th SCSI disk whole disk
+ 16 = /dev/sdhb 210th SCSI disk whole disk
+ 32 = /dev/sdhc 211th SCSI disk whole disk
+ ...
+ 240 = /dev/sdhp 224th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 134 block SCSI disk devices (224-239)
+ 0 = /dev/sdhq 225th SCSI disk whole disk
+ 16 = /dev/sdhr 226th SCSI disk whole disk
+ 32 = /dev/sdhs 227th SCSI disk whole disk
+ ...
+ 240 = /dev/sdif 240th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 135 block SCSI disk devices (240-255)
+ 0 = /dev/sdig 241st SCSI disk whole disk
+ 16 = /dev/sdih 242nd SCSI disk whole disk
+ 32 = /dev/sdih 243rd SCSI disk whole disk
+ ...
+ 240 = /dev/sdiv 256th SCSI disk whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 136-143 char Unix98 PTY slaves
+ 0 = /dev/pts/0 First Unix98 pseudo-TTY
+ 1 = /dev/pts/1 Second Unix98 pseudo-TTY
+ ...
+
+ These device nodes are automatically generated with
+ the proper permissions and modes by mounting the
+ devpts filesystem onto /dev/pts with the appropriate
+ mount options (distribution dependent, however, on
+ *most* distributions the appropriate options are
+ "mode=0620,gid=<gid of the "tty" group>".)
+
+ 136 block Mylex DAC960 PCI RAID controller; ninth controller
+ 0 = /dev/rd/c8d0 First disk, whole disk
+ 8 = /dev/rd/c8d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c8d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 137 block Mylex DAC960 PCI RAID controller; tenth controller
+ 0 = /dev/rd/c9d0 First disk, whole disk
+ 8 = /dev/rd/c9d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c9d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 138 block Mylex DAC960 PCI RAID controller; eleventh controller
+ 0 = /dev/rd/c10d0 First disk, whole disk
+ 8 = /dev/rd/c10d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c10d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 139 block Mylex DAC960 PCI RAID controller; twelfth controller
+ 0 = /dev/rd/c11d0 First disk, whole disk
+ 8 = /dev/rd/c11d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c11d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 140 block Mylex DAC960 PCI RAID controller; thirteenth controller
+ 0 = /dev/rd/c12d0 First disk, whole disk
+ 8 = /dev/rd/c12d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c12d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 141 block Mylex DAC960 PCI RAID controller; fourteenth controller
+ 0 = /dev/rd/c13d0 First disk, whole disk
+ 8 = /dev/rd/c13d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c13d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 142 block Mylex DAC960 PCI RAID controller; fifteenth controller
+ 0 = /dev/rd/c14d0 First disk, whole disk
+ 8 = /dev/rd/c14d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c14d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 143 block Mylex DAC960 PCI RAID controller; sixteenth controller
+ 0 = /dev/rd/c15d0 First disk, whole disk
+ 8 = /dev/rd/c15d1 Second disk, whole disk
+ ...
+ 248 = /dev/rd/c15d31 32nd disk, whole disk
+
+ Partitions are handled as for major 48.
+
+ 144 char Encapsulated PPP
+ 0 = /dev/pppox0 First PPP over Ethernet
+ ...
+ 63 = /dev/pppox63 64th PPP over Ethernet
+
+ This is primarily used for ADSL.
+
+ The SST 5136-DN DeviceNet interface driver has been
+ relocated to major 183 due to an unfortunate conflict.
+
+ 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts
+ 0 = mounted device 256
+ 255 = mounted device 511
+
+ 145 char SAM9407-based soundcard
+ 0 = /dev/sam0_mixer
+ 1 = /dev/sam0_sequencer
+ 2 = /dev/sam0_midi00
+ 3 = /dev/sam0_dsp
+ 4 = /dev/sam0_audio
+ 6 = /dev/sam0_sndstat
+ 18 = /dev/sam0_midi01
+ 34 = /dev/sam0_midi02
+ 50 = /dev/sam0_midi03
+ 64 = /dev/sam1_mixer
+ ...
+ 128 = /dev/sam2_mixer
+ ...
+ 192 = /dev/sam3_mixer
+ ...
+
+ Device functions match OSS, but offer a number of
+ addons, which are sam9407 specific. OSS can be
+ operated simultaneously, taking care of the codec.
+
+ 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts
+ 0 = mounted device 512
+ 255 = mounted device 767
+
+ 146 char SYSTRAM SCRAMNet mirrored-memory network
+ 0 = /dev/scramnet0 First SCRAMNet device
+ 1 = /dev/scramnet1 Second SCRAMNet device
+ ...
+
+ 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts
+ 0 = mounted device 768
+ 255 = mounted device 1023
+
+ 147 char Aureal Semiconductor Vortex Audio device
+ 0 = /dev/aureal0 First Aureal Vortex
+ 1 = /dev/aureal1 Second Aureal Vortex
+ ...
+
+ 147 block Distributed Replicated Block Device (DRBD)
+ 0 = /dev/drbd0 First DRBD device
+ 1 = /dev/drbd1 Second DRBD device
+ ...
+
+ 148 char Technology Concepts serial card
+ 0 = /dev/ttyT0 First TCL port
+ 1 = /dev/ttyT1 Second TCL port
+ ...
+
+ 149 char Technology Concepts serial card - alternate devices
+ 0 = /dev/cut0 Callout device for ttyT0
+ 1 = /dev/cut0 Callout device for ttyT1
+ ...
+
+ 150 char Real-Time Linux FIFOs
+ 0 = /dev/rtf0 First RTLinux FIFO
+ 1 = /dev/rtf1 Second RTLinux FIFO
+ ...
+
+ 151 char DPT I2O SmartRaid V controller
+ 0 = /dev/dpti0 First DPT I2O adapter
+ 1 = /dev/dpti1 Second DPT I2O adapter
+ ...
+
+ 152 char EtherDrive Control Device
+ 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive
+ 1 = /dev/etherd/err Monitor errors
+ 2 = /dev/etherd/raw Raw AoE packet monitor
+
+ 152 block EtherDrive Block Devices
+ 0 = /dev/etherd/0 EtherDrive 0
+ ...
+ 255 = /dev/etherd/255 EtherDrive 255
+
+ 153 char SPI Bus Interface (sometimes referred to as MicroWire)
+ 0 = /dev/spi0 First SPI device on the bus
+ 1 = /dev/spi1 Second SPI device on the bus
+ ...
+ 15 = /dev/spi15 Sixteenth SPI device on the bus
+
+ 153 block Enhanced Metadisk RAID (EMD) storage units
+ 0 = /dev/emd/0 First unit
+ 1 = /dev/emd/0p1 Partition 1 on First unit
+ 2 = /dev/emd/0p2 Partition 2 on First unit
+ ...
+ 15 = /dev/emd/0p15 Partition 15 on First unit
+
+ 16 = /dev/emd/1 Second unit
+ 32 = /dev/emd/2 Third unit
+ ...
+ 240 = /dev/emd/15 Sixteenth unit
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 154 char Specialix RIO serial card
+ 0 = /dev/ttySR0 First RIO port
+ ...
+ 255 = /dev/ttySR255 256th RIO port
+
+ 155 char Specialix RIO serial card - alternate devices
+ 0 = /dev/cusr0 Callout device for ttySR0
+ ...
+ 255 = /dev/cusr255 Callout device for ttySR255
+
+ 156 char Specialix RIO serial card
+ 0 = /dev/ttySR256 257th RIO port
+ ...
+ 255 = /dev/ttySR511 512th RIO port
+
+ 157 char Specialix RIO serial card - alternate devices
+ 0 = /dev/cusr256 Callout device for ttySR256
+ ...
+ 255 = /dev/cusr511 Callout device for ttySR511
+
+ 158 char Dialogic GammaLink fax driver
+ 0 = /dev/gfax0 GammaLink channel 0
+ 1 = /dev/gfax1 GammaLink channel 1
+ ...
+
+ 159 char RESERVED
+
+ 159 block RESERVED
+
+ 160 char General Purpose Instrument Bus (GPIB)
+ 0 = /dev/gpib0 First GPIB bus
+ 1 = /dev/gpib1 Second GPIB bus
+ ...
+
+ 160 block Carmel 8-port SATA Disks on First Controller
+ 0 = /dev/carmel/0 SATA disk 0 whole disk
+ 1 = /dev/carmel/0p1 SATA disk 0 partition 1
+ ...
+ 31 = /dev/carmel/0p31 SATA disk 0 partition 31
+
+ 32 = /dev/carmel/1 SATA disk 1 whole disk
+ 64 = /dev/carmel/2 SATA disk 2 whole disk
+ ...
+ 224 = /dev/carmel/7 SATA disk 7 whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 31.
+
+ 161 char IrCOMM devices (IrDA serial/parallel emulation)
+ 0 = /dev/ircomm0 First IrCOMM device
+ 1 = /dev/ircomm1 Second IrCOMM device
+ ...
+ 16 = /dev/irlpt0 First IrLPT device
+ 17 = /dev/irlpt1 Second IrLPT device
+ ...
+
+ 161 block Carmel 8-port SATA Disks on Second Controller
+ 0 = /dev/carmel/8 SATA disk 8 whole disk
+ 1 = /dev/carmel/8p1 SATA disk 8 partition 1
+ ...
+ 31 = /dev/carmel/8p31 SATA disk 8 partition 31
+
+ 32 = /dev/carmel/9 SATA disk 9 whole disk
+ 64 = /dev/carmel/10 SATA disk 10 whole disk
+ ...
+ 224 = /dev/carmel/15 SATA disk 15 whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 31.
+
+ 162 char Used for (now removed) raw block device interface
+
+ 163 char
+
+ 164 char Chase Research AT/PCI-Fast serial card
+ 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0
+ ...
+ 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15
+ 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0
+ ...
+ 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15
+ 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0
+ ...
+ 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15
+ 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0
+ ...
+ 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15
+
+ 165 char Chase Research AT/PCI-Fast serial card - alternate devices
+ 0 = /dev/cuch0 Callout device for ttyCH0
+ ...
+ 63 = /dev/cuch63 Callout device for ttyCH63
+
+ 166 char ACM USB modems
+ 0 = /dev/ttyACM0 First ACM modem
+ 1 = /dev/ttyACM1 Second ACM modem
+ ...
+
+ 167 char ACM USB modems - alternate devices
+ 0 = /dev/cuacm0 Callout device for ttyACM0
+ 1 = /dev/cuacm1 Callout device for ttyACM1
+ ...
+
+ 168 char Eracom CSA7000 PCI encryption adaptor
+ 0 = /dev/ecsa0 First CSA7000
+ 1 = /dev/ecsa1 Second CSA7000
+ ...
+
+ 169 char Eracom CSA8000 PCI encryption adaptor
+ 0 = /dev/ecsa8-0 First CSA8000
+ 1 = /dev/ecsa8-1 Second CSA8000
+ ...
+
+ 170 char AMI MegaRAC remote access controller
+ 0 = /dev/megarac0 First MegaRAC card
+ 1 = /dev/megarac1 Second MegaRAC card
+ ...
+
+ 171 char Reserved for IEEE 1394 (Firewire)
+
+ 172 char Moxa Intellio serial card
+ 0 = /dev/ttyMX0 First Moxa port
+ 1 = /dev/ttyMX1 Second Moxa port
+ ...
+ 127 = /dev/ttyMX127 128th Moxa port
+ 128 = /dev/moxactl Moxa control port
+
+ 173 char Moxa Intellio serial card - alternate devices
+ 0 = /dev/cumx0 Callout device for ttyMX0
+ 1 = /dev/cumx1 Callout device for ttyMX1
+ ...
+ 127 = /dev/cumx127 Callout device for ttyMX127
+
+ 174 char SmartIO serial card
+ 0 = /dev/ttySI0 First SmartIO port
+ 1 = /dev/ttySI1 Second SmartIO port
+ ...
+
+ 175 char SmartIO serial card - alternate devices
+ 0 = /dev/cusi0 Callout device for ttySI0
+ 1 = /dev/cusi1 Callout device for ttySI1
+ ...
+
+ 176 char nCipher nFast PCI crypto accelerator
+ 0 = /dev/nfastpci0 First nFast PCI device
+ 1 = /dev/nfastpci1 First nFast PCI device
+ ...
+
+ 177 char TI PCILynx memory spaces
+ 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card
+ ...
+ 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card
+ 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card
+ ...
+ 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card
+ 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card
+ ...
+ 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card
+
+ 178 char Giganet cLAN1xxx virtual interface adapter
+ 0 = /dev/clanvi0 First cLAN adapter
+ 1 = /dev/clanvi1 Second cLAN adapter
+ ...
+
+ 179 block MMC block devices
+ 0 = /dev/mmcblk0 First SD/MMC card
+ 1 = /dev/mmcblk0p1 First partition on first MMC card
+ 8 = /dev/mmcblk1 Second SD/MMC card
+ ...
+
+ The start of next SD/MMC card can be configured with
+ CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe
+ time using the mmcblk.perdev_minors option. That would
+ bump the offset between each card to be the configured
+ value instead of the default 8.
+
+ 179 char CCube DVXChip-based PCI products
+ 0 = /dev/dvxirq0 First DVX device
+ 1 = /dev/dvxirq1 Second DVX device
+ ...
+
+ 180 char USB devices
+ 0 = /dev/usb/lp0 First USB printer
+ ...
+ 15 = /dev/usb/lp15 16th USB printer
+ 48 = /dev/usb/scanner0 First USB scanner
+ ...
+ 63 = /dev/usb/scanner15 16th USB scanner
+ 64 = /dev/usb/rio500 Diamond Rio 500
+ 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de)
+ 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD)
+ 96 = /dev/usb/hiddev0 1st USB HID device
+ ...
+ 111 = /dev/usb/hiddev15 16th USB HID device
+ 112 = /dev/usb/auer0 1st auerswald ISDN device
+ ...
+ 127 = /dev/usb/auer15 16th auerswald ISDN device
+ 128 = /dev/usb/brlvgr0 First Braille Voyager device
+ ...
+ 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device
+ 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device
+ 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device
+ ...
+ 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device
+ 144 = /dev/usb/lcd USB LCD device
+ 160 = /dev/usb/legousbtower0 1st USB Legotower device
+ ...
+ 175 = /dev/usb/legousbtower15 16th USB Legotower device
+ 176 = /dev/usb/usbtmc1 First USB TMC device
+ ...
+ 191 = /dev/usb/usbtmc16 16th USB TMC device
+ 192 = /dev/usb/yurex1 First USB Yurex device
+ ...
+ 209 = /dev/usb/yurex16 16th USB Yurex device
+
+ 180 block USB block devices
+ 0 = /dev/uba First USB block device
+ 8 = /dev/ubb Second USB block device
+ 16 = /dev/ubc Third USB block device
+ ...
+
+ 181 char Conrad Electronic parallel port radio clocks
+ 0 = /dev/pcfclock0 First Conrad radio clock
+ 1 = /dev/pcfclock1 Second Conrad radio clock
+ ...
+
+ 182 char Picture Elements THR2 binarizer
+ 0 = /dev/pethr0 First THR2 board
+ 1 = /dev/pethr1 Second THR2 board
+ ...
+
+ 183 char SST 5136-DN DeviceNet interface
+ 0 = /dev/ss5136dn0 First DeviceNet interface
+ 1 = /dev/ss5136dn1 Second DeviceNet interface
+ ...
+
+ This device used to be assigned to major number 144.
+ It had to be moved due to an unfortunate conflict.
+
+ 184 char Picture Elements' video simulator/sender
+ 0 = /dev/pevss0 First sender board
+ 1 = /dev/pevss1 Second sender board
+ ...
+
+ 185 char InterMezzo high availability file system
+ 0 = /dev/intermezzo0 First cache manager
+ 1 = /dev/intermezzo1 Second cache manager
+ ...
+
+ See http://web.archive.org/web/20080115195241/
+ http://inter-mezzo.org/index.html
+
+ 186 char Object-based storage control device
+ 0 = /dev/obd0 First obd control device
+ 1 = /dev/obd1 Second obd control device
+ ...
+
+ See ftp://ftp.lustre.org/pub/obd for code and information.
+
+ 187 char DESkey hardware encryption device
+ 0 = /dev/deskey0 First DES key
+ 1 = /dev/deskey1 Second DES key
+ ...
+
+ 188 char USB serial converters
+ 0 = /dev/ttyUSB0 First USB serial converter
+ 1 = /dev/ttyUSB1 Second USB serial converter
+ ...
+
+ 189 char USB serial converters - alternate devices
+ 0 = /dev/cuusb0 Callout device for ttyUSB0
+ 1 = /dev/cuusb1 Callout device for ttyUSB1
+ ...
+
+ 190 char Kansas City tracker/tuner card
+ 0 = /dev/kctt0 First KCT/T card
+ 1 = /dev/kctt1 Second KCT/T card
+ ...
+
+ 191 char Reserved for PCMCIA
+
+ 192 char Kernel profiling interface
+ 0 = /dev/profile Profiling control device
+ 1 = /dev/profile0 Profiling device for CPU 0
+ 2 = /dev/profile1 Profiling device for CPU 1
+ ...
+
+ 193 char Kernel event-tracing interface
+ 0 = /dev/trace Tracing control device
+ 1 = /dev/trace0 Tracing device for CPU 0
+ 2 = /dev/trace1 Tracing device for CPU 1
+ ...
+
+ 194 char linVideoStreams (LINVS)
+ 0 = /dev/mvideo/status0 Video compression status
+ 1 = /dev/mvideo/stream0 Video stream
+ 2 = /dev/mvideo/frame0 Single compressed frame
+ 3 = /dev/mvideo/rawframe0 Raw uncompressed frame
+ 4 = /dev/mvideo/codec0 Direct codec access
+ 5 = /dev/mvideo/video4linux0 Video4Linux compatibility
+
+ 16 = /dev/mvideo/status1 Second device
+ ...
+ 32 = /dev/mvideo/status2 Third device
+ ...
+ ...
+ 240 = /dev/mvideo/status15 16th device
+ ...
+
+ 195 char Nvidia graphics devices
+ 0 = /dev/nvidia0 First Nvidia card
+ 1 = /dev/nvidia1 Second Nvidia card
+ ...
+ 255 = /dev/nvidiactl Nvidia card control device
+
+ 196 char Tormenta T1 card
+ 0 = /dev/tor/0 Master control channel for all cards
+ 1 = /dev/tor/1 First DS0
+ 2 = /dev/tor/2 Second DS0
+ ...
+ 48 = /dev/tor/48 48th DS0
+ 49 = /dev/tor/49 First pseudo-channel
+ 50 = /dev/tor/50 Second pseudo-channel
+ ...
+
+ 197 char OpenTNF tracing facility
+ 0 = /dev/tnf/t0 Trace 0 data extraction
+ 1 = /dev/tnf/t1 Trace 1 data extraction
+ ...
+ 128 = /dev/tnf/status Tracing facility status
+ 130 = /dev/tnf/trace Tracing device
+
+ 198 char Total Impact TPMP2 quad coprocessor PCI card
+ 0 = /dev/tpmp2/0 First card
+ 1 = /dev/tpmp2/1 Second card
+ ...
+
+ 199 char Veritas volume manager (VxVM) volumes
+ 0 = /dev/vx/rdsk/*/* First volume
+ 1 = /dev/vx/rdsk/*/* Second volume
+ ...
+
+ 199 block Veritas volume manager (VxVM) volumes
+ 0 = /dev/vx/dsk/*/* First volume
+ 1 = /dev/vx/dsk/*/* Second volume
+ ...
+
+ The namespace in these directories is maintained by
+ the user space VxVM software.
+
+ 200 char Veritas VxVM configuration interface
+ 0 = /dev/vx/config Configuration access node
+ 1 = /dev/vx/trace Volume i/o trace access node
+ 2 = /dev/vx/iod Volume i/o daemon access node
+ 3 = /dev/vx/info Volume information access node
+ 4 = /dev/vx/task Volume tasks access node
+ 5 = /dev/vx/taskmon Volume tasks monitor daemon
+
+ 201 char Veritas VxVM dynamic multipathing driver
+ 0 = /dev/vx/rdmp/* First multipath device
+ 1 = /dev/vx/rdmp/* Second multipath device
+ ...
+ 201 block Veritas VxVM dynamic multipathing driver
+ 0 = /dev/vx/dmp/* First multipath device
+ 1 = /dev/vx/dmp/* Second multipath device
+ ...
+
+ The namespace in these directories is maintained by
+ the user space VxVM software.
+
+ 202 char CPU model-specific registers
+ 0 = /dev/cpu/0/msr MSRs on CPU 0
+ 1 = /dev/cpu/1/msr MSRs on CPU 1
+ ...
+
+ 202 block Xen Virtual Block Device
+ 0 = /dev/xvda First Xen VBD whole disk
+ 16 = /dev/xvdb Second Xen VBD whole disk
+ 32 = /dev/xvdc Third Xen VBD whole disk
+ ...
+ 240 = /dev/xvdp Sixteenth Xen VBD whole disk
+
+ Partitions are handled in the same way as for IDE
+ disks (see major number 3) except that the limit on
+ partitions is 15.
+
+ 203 char CPU CPUID information
+ 0 = /dev/cpu/0/cpuid CPUID on CPU 0
+ 1 = /dev/cpu/1/cpuid CPUID on CPU 1
+ ...
+
+ 204 char Low-density serial ports
+ 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0
+ 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1
+ 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2
+ 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3
+ 4 = /dev/ttyFB0 Intel Footbridge (ARM)
+ 5 = /dev/ttySA0 StrongARM builtin serial port 0
+ 6 = /dev/ttySA1 StrongARM builtin serial port 1
+ 7 = /dev/ttySA2 StrongARM builtin serial port 2
+ 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0
+ 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1
+ 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2
+ 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3
+ 12 = /dev/ttyFW0 Firmware console - port 0
+ 13 = /dev/ttyFW1 Firmware console - port 1
+ 14 = /dev/ttyFW2 Firmware console - port 2
+ 15 = /dev/ttyFW3 Firmware console - port 3
+ 16 = /dev/ttyAM0 ARM "AMBA" serial port 0
+ ...
+ 31 = /dev/ttyAM15 ARM "AMBA" serial port 15
+ 32 = /dev/ttyDB0 DataBooster serial port 0
+ ...
+ 39 = /dev/ttyDB7 DataBooster serial port 7
+ 40 = /dev/ttySG0 SGI Altix console port
+ 41 = /dev/ttySMX0 Motorola i.MX - port 0
+ 42 = /dev/ttySMX1 Motorola i.MX - port 1
+ 43 = /dev/ttySMX2 Motorola i.MX - port 2
+ 44 = /dev/ttyMM0 Marvell MPSC - port 0 (obsolete unused)
+ 45 = /dev/ttyMM1 Marvell MPSC - port 1 (obsolete unused)
+ 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0
+ ...
+ 51 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5
+ 82 = /dev/ttyVR0 NEC VR4100 series SIU
+ 83 = /dev/ttyVR1 NEC VR4100 series DSIU
+ 148 = /dev/ttyPSC0 PPC PSC - port 0
+ ...
+ 153 = /dev/ttyPSC5 PPC PSC - port 5
+ 154 = /dev/ttyAT0 ATMEL serial port 0
+ ...
+ 169 = /dev/ttyAT15 ATMEL serial port 15
+ 170 = /dev/ttyNX0 Hilscher netX serial port 0
+ ...
+ 185 = /dev/ttyNX15 Hilscher netX serial port 15
+ 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation
+
+ If maximum number of uartlite serial ports is more than 4, then the driver
+ uses dynamic allocation instead of static allocation for major number.
+ 187 = /dev/ttyUL0 Xilinx uartlite - port 0
+ ...
+ 190 = /dev/ttyUL3 Xilinx uartlite - port 3
+ 191 = /dev/xvc0 Xen virtual console - port 0
+ 192 = /dev/ttyPZ0 pmac_zilog - port 0
+ ...
+ 195 = /dev/ttyPZ3 pmac_zilog - port 3
+ 196 = /dev/ttyTX0 TX39/49 serial port 0
+ ...
+ 204 = /dev/ttyTX7 TX39/49 serial port 7
+ 205 = /dev/ttySC0 SC26xx serial port 0
+ 206 = /dev/ttySC1 SC26xx serial port 1
+ 207 = /dev/ttySC2 SC26xx serial port 2
+ 208 = /dev/ttySC3 SC26xx serial port 3
+ 209 = /dev/ttyMAX0 MAX3100 serial port 0
+ 210 = /dev/ttyMAX1 MAX3100 serial port 1
+ 211 = /dev/ttyMAX2 MAX3100 serial port 2
+ 212 = /dev/ttyMAX3 MAX3100 serial port 3
+
+ 205 char Low-density serial ports (alternate device)
+ 0 = /dev/culu0 Callout device for ttyLU0
+ 1 = /dev/culu1 Callout device for ttyLU1
+ 2 = /dev/culu2 Callout device for ttyLU2
+ 3 = /dev/culu3 Callout device for ttyLU3
+ 4 = /dev/cufb0 Callout device for ttyFB0
+ 5 = /dev/cusa0 Callout device for ttySA0
+ 6 = /dev/cusa1 Callout device for ttySA1
+ 7 = /dev/cusa2 Callout device for ttySA2
+ 8 = /dev/cusc0 Callout device for ttySC0
+ 9 = /dev/cusc1 Callout device for ttySC1
+ 10 = /dev/cusc2 Callout device for ttySC2
+ 11 = /dev/cusc3 Callout device for ttySC3
+ 12 = /dev/cufw0 Callout device for ttyFW0
+ 13 = /dev/cufw1 Callout device for ttyFW1
+ 14 = /dev/cufw2 Callout device for ttyFW2
+ 15 = /dev/cufw3 Callout device for ttyFW3
+ 16 = /dev/cuam0 Callout device for ttyAM0
+ ...
+ 31 = /dev/cuam15 Callout device for ttyAM15
+ 32 = /dev/cudb0 Callout device for ttyDB0
+ ...
+ 39 = /dev/cudb7 Callout device for ttyDB7
+ 40 = /dev/cusg0 Callout device for ttySG0
+ 41 = /dev/ttycusmx0 Callout device for ttySMX0
+ 42 = /dev/ttycusmx1 Callout device for ttySMX1
+ 43 = /dev/ttycusmx2 Callout device for ttySMX2
+ 46 = /dev/cucpm0 Callout device for ttyCPM0
+ ...
+ 51 = /dev/cucpm5 Callout device for ttyCPM5
+ 82 = /dev/cuvr0 Callout device for ttyVR0
+ 83 = /dev/cuvr1 Callout device for ttyVR1
+
+ 206 char OnStream SC-x0 tape devices
+ 0 = /dev/osst0 First OnStream SCSI tape, mode 0
+ 1 = /dev/osst1 Second OnStream SCSI tape, mode 0
+ ...
+ 32 = /dev/osst0l First OnStream SCSI tape, mode 1
+ 33 = /dev/osst1l Second OnStream SCSI tape, mode 1
+ ...
+ 64 = /dev/osst0m First OnStream SCSI tape, mode 2
+ 65 = /dev/osst1m Second OnStream SCSI tape, mode 2
+ ...
+ 96 = /dev/osst0a First OnStream SCSI tape, mode 3
+ 97 = /dev/osst1a Second OnStream SCSI tape, mode 3
+ ...
+ 128 = /dev/nosst0 No rewind version of /dev/osst0
+ 129 = /dev/nosst1 No rewind version of /dev/osst1
+ ...
+ 160 = /dev/nosst0l No rewind version of /dev/osst0l
+ 161 = /dev/nosst1l No rewind version of /dev/osst1l
+ ...
+ 192 = /dev/nosst0m No rewind version of /dev/osst0m
+ 193 = /dev/nosst1m No rewind version of /dev/osst1m
+ ...
+ 224 = /dev/nosst0a No rewind version of /dev/osst0a
+ 225 = /dev/nosst1a No rewind version of /dev/osst1a
+ ...
+
+ The OnStream SC-x0 SCSI tapes do not support the
+ standard SCSI SASD command set and therefore need
+ their own driver "osst". Note that the IDE, USB (and
+ maybe ParPort) versions may be driven via ide-scsi or
+ usb-storage SCSI emulation and this osst device and
+ driver as well. The ADR-x0 drives are QIC-157
+ compliant and don't need osst.
+
+ 207 char Compaq ProLiant health feature indicate
+ 0 = /dev/cpqhealth/cpqw Redirector interface
+ 1 = /dev/cpqhealth/crom EISA CROM
+ 2 = /dev/cpqhealth/cdt Data Table
+ 3 = /dev/cpqhealth/cevt Event Log
+ 4 = /dev/cpqhealth/casr Automatic Server Recovery
+ 5 = /dev/cpqhealth/cecc ECC Memory
+ 6 = /dev/cpqhealth/cmca Machine Check Architecture
+ 7 = /dev/cpqhealth/ccsm Deprecated CDT
+ 8 = /dev/cpqhealth/cnmi NMI Handling
+ 9 = /dev/cpqhealth/css Sideshow Management
+ 10 = /dev/cpqhealth/cram CMOS interface
+ 11 = /dev/cpqhealth/cpci PCI IRQ interface
+
+ 208 char User space serial ports
+ 0 = /dev/ttyU0 First user space serial port
+ 1 = /dev/ttyU1 Second user space serial port
+ ...
+
+ 209 char User space serial ports (alternate devices)
+ 0 = /dev/cuu0 Callout device for ttyU0
+ 1 = /dev/cuu1 Callout device for ttyU1
+ ...
+
+ 210 char SBE, Inc. sync/async serial card
+ 0 = /dev/sbei/wxcfg0 Configuration device for board 0
+ 1 = /dev/sbei/dld0 Download device for board 0
+ 2 = /dev/sbei/wan00 WAN device, port 0, board 0
+ 3 = /dev/sbei/wan01 WAN device, port 1, board 0
+ 4 = /dev/sbei/wan02 WAN device, port 2, board 0
+ 5 = /dev/sbei/wan03 WAN device, port 3, board 0
+ 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0
+ 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0
+ 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0
+ 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0
+ 10 = /dev/sbei/wxcfg1 Configuration device for board 1
+ 11 = /dev/sbei/dld1 Download device for board 1
+ 12 = /dev/sbei/wan10 WAN device, port 0, board 1
+ 13 = /dev/sbei/wan11 WAN device, port 1, board 1
+ 14 = /dev/sbei/wan12 WAN device, port 2, board 1
+ 15 = /dev/sbei/wan13 WAN device, port 3, board 1
+ 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1
+ 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1
+ 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1
+ 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1
+ ...
+
+ Yes, each board is really spaced 10 (decimal) apart.
+
+ 211 char Addinum CPCI1500 digital I/O card
+ 0 = /dev/addinum/cpci1500/0 First CPCI1500 card
+ 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card
+ ...
+
+ 212 char LinuxTV.org DVB driver subsystem
+ 0 = /dev/dvb/adapter0/video0 first video decoder of first card
+ 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card
+ 2 = /dev/dvb/adapter0/sec0 (obsolete/unused)
+ 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card
+ 4 = /dev/dvb/adapter0/demux0 first demux device of first card
+ 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card
+ 6 = /dev/dvb/adapter0/ca0 first common access port of first card
+ 7 = /dev/dvb/adapter0/net0 first network device of first card
+ 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card
+ 9 = /dev/dvb/adapter0/video1 second video decoder of first card
+ ...
+ 64 = /dev/dvb/adapter1/video0 first video decoder of second card
+ ...
+ 128 = /dev/dvb/adapter2/video0 first video decoder of third card
+ ...
+ 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card
+
+ 216 char Bluetooth RFCOMM TTY devices
+ 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device
+ 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device
+ ...
+
+ 217 char Bluetooth RFCOMM TTY devices (alternate devices)
+ 0 = /dev/curf0 Callout device for rfcomm0
+ 1 = /dev/curf1 Callout device for rfcomm1
+ ...
+
+ 218 char The Logical Company bus Unibus/Qbus adapters
+ 0 = /dev/logicalco/bci/0 First bus adapter
+ 1 = /dev/logicalco/bci/1 First bus adapter
+ ...
+
+ 219 char The Logical Company DCI-1300 digital I/O card
+ 0 = /dev/logicalco/dci1300/0 First DCI-1300 card
+ 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card
+ ...
+
+ 220 char Myricom Myrinet "GM" board
+ 0 = /dev/myricom/gm0 First Myrinet GM board
+ 1 = /dev/myricom/gmp0 First board "root access"
+ 2 = /dev/myricom/gm1 Second Myrinet GM board
+ 3 = /dev/myricom/gmp1 Second board "root access"
+ ...
+
+ 221 char VME bus
+ 0 = /dev/bus/vme/m0 First master image
+ 1 = /dev/bus/vme/m1 Second master image
+ 2 = /dev/bus/vme/m2 Third master image
+ 3 = /dev/bus/vme/m3 Fourth master image
+ 4 = /dev/bus/vme/s0 First slave image
+ 5 = /dev/bus/vme/s1 Second slave image
+ 6 = /dev/bus/vme/s2 Third slave image
+ 7 = /dev/bus/vme/s3 Fourth slave image
+ 8 = /dev/bus/vme/ctl Control
+
+ It is expected that all VME bus drivers will use the
+ same interface. For interface documentation see
+ http://www.vmelinux.org/.
+
+ 224 char A2232 serial card
+ 0 = /dev/ttyY0 First A2232 port
+ 1 = /dev/ttyY1 Second A2232 port
+ ...
+
+ 225 char A2232 serial card (alternate devices)
+ 0 = /dev/cuy0 Callout device for ttyY0
+ 1 = /dev/cuy1 Callout device for ttyY1
+ ...
+
+ 226 char Direct Rendering Infrastructure (DRI)
+ 0 = /dev/dri/card0 First graphics card
+ 1 = /dev/dri/card1 Second graphics card
+ ...
+
+ 227 char IBM 3270 terminal Unix tty access
+ 1 = /dev/3270/tty1 First 3270 terminal
+ 2 = /dev/3270/tty2 Seconds 3270 terminal
+ ...
+
+ 228 char IBM 3270 terminal block-mode access
+ 0 = /dev/3270/tub Controlling interface
+ 1 = /dev/3270/tub1 First 3270 terminal
+ 2 = /dev/3270/tub2 Second 3270 terminal
+ ...
+
+ 229 char IBM iSeries/pSeries virtual console
+ 0 = /dev/hvc0 First console port
+ 1 = /dev/hvc1 Second console port
+ ...
+
+ 230 char IBM iSeries virtual tape
+ 0 = /dev/iseries/vt0 First virtual tape, mode 0
+ 1 = /dev/iseries/vt1 Second virtual tape, mode 0
+ ...
+ 32 = /dev/iseries/vt0l First virtual tape, mode 1
+ 33 = /dev/iseries/vt1l Second virtual tape, mode 1
+ ...
+ 64 = /dev/iseries/vt0m First virtual tape, mode 2
+ 65 = /dev/iseries/vt1m Second virtual tape, mode 2
+ ...
+ 96 = /dev/iseries/vt0a First virtual tape, mode 3
+ 97 = /dev/iseries/vt1a Second virtual tape, mode 3
+ ...
+ 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind
+ 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind
+ ...
+ 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind
+ 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind
+ ...
+ 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind
+ 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind
+ ...
+ 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind
+ 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind
+ ...
+
+ "No rewind" refers to the omission of the default
+ automatic rewind on device close. The MTREW or MTOFFL
+ ioctl()'s can be used to rewind the tape regardless of
+ the device used to access it.
+
+ 231 char InfiniBand
+ 0 = /dev/infiniband/umad0
+ 1 = /dev/infiniband/umad1
+ ...
+ 63 = /dev/infiniband/umad63 63rd InfiniBandMad device
+ 64 = /dev/infiniband/issm0 First InfiniBand IsSM device
+ 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device
+ ...
+ 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device
+ 192 = /dev/infiniband/uverbs0 First InfiniBand verbs device
+ 193 = /dev/infiniband/uverbs1 Second InfiniBand verbs device
+ ...
+ 223 = /dev/infiniband/uverbs31 31st InfiniBand verbs device
+
+ 232 char Biometric Devices
+ 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device
+ 1 = /dev/biometric/sensor0/iris first iris sensor on first device
+ 2 = /dev/biometric/sensor0/retina first retina sensor on first device
+ 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device
+ 4 = /dev/biometric/sensor0/facial first facial sensor on first device
+ 5 = /dev/biometric/sensor0/hand first hand sensor on first device
+ ...
+ 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device
+ ...
+ 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device
+ ...
+
+ 233 char PathScale InfiniPath interconnect
+ 0 = /dev/ipath Primary device for programs (any unit)
+ 1 = /dev/ipath0 Access specifically to unit 0
+ 2 = /dev/ipath1 Access specifically to unit 1
+ ...
+ 4 = /dev/ipath3 Access specifically to unit 3
+ 129 = /dev/ipath_sma Device used by Subnet Management Agent
+ 130 = /dev/ipath_diag Device used by diagnostics programs
+
+ 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT
+ Character devices that request a dynamic allocation of major number will
+ take numbers starting from 254 and downward.
+
+ 240-254 block LOCAL/EXPERIMENTAL USE
+ Allocated for local/experimental use. For devices not
+ assigned official numbers, these ranges should be
+ used in order to avoid conflicting with future assignments.
+
+ 255 char RESERVED
+
+ 255 block RESERVED
+
+ This major is reserved to assist the expansion to a
+ larger number space. No device nodes with this major
+ should ever be created on the filesystem.
+ (This is probably not true anymore, but I'll leave it
+ for now /Torben)
+
+ ---LARGE MAJORS!!!!!---
+
+ 256 char Equinox SST multi-port serial boards
+ 0 = /dev/ttyEQ0 First serial port on first Equinox SST board
+ 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board
+ 128 = /dev/ttyEQ128 First serial port on second Equinox SST board
+ ...
+ 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board
+
+ 256 block Resident Flash Disk Flash Translation Layer
+ 0 = /dev/rfda First RFD FTL layer
+ 16 = /dev/rfdb Second RFD FTL layer
+ ...
+ 240 = /dev/rfdp 16th RFD FTL layer
+
+ 257 char Phoenix Technologies Cryptographic Services Driver
+ 0 = /dev/ptlsec Crypto Services Driver
+
+ 257 block SSFDC Flash Translation Layer filesystem
+ 0 = /dev/ssfdca First SSFDC layer
+ 8 = /dev/ssfdcb Second SSFDC layer
+ 16 = /dev/ssfdcc Third SSFDC layer
+ 24 = /dev/ssfdcd 4th SSFDC layer
+ 32 = /dev/ssfdce 5th SSFDC layer
+ 40 = /dev/ssfdcf 6th SSFDC layer
+ 48 = /dev/ssfdcg 7th SSFDC layer
+ 56 = /dev/ssfdch 8th SSFDC layer
+
+ 258 block ROM/Flash read-only translation layer
+ 0 = /dev/blockrom0 First ROM card's translation layer interface
+ 1 = /dev/blockrom1 Second ROM card's translation layer interface
+ ...
+
+ 259 block Block Extended Major
+ Used dynamically to hold additional partition minor
+ numbers and allow large numbers of partitions per device
+
+ 259 char FPGA configuration interfaces
+ 0 = /dev/icap0 First Xilinx internal configuration
+ 1 = /dev/icap1 Second Xilinx internal configuration
+
+ 260 char OSD (Object-based-device) SCSI Device
+ 0 = /dev/osd0 First OSD Device
+ 1 = /dev/osd1 Second OSD Device
+ ...
+ 255 = /dev/osd255 256th OSD Device
+
+ 261 char Compute Acceleration Devices
+ 0 = /dev/accel/accel0 First acceleration device
+ 1 = /dev/accel/accel1 Second acceleration device
+ ...
+
+ 384-511 char RESERVED FOR DYNAMIC ASSIGNMENT
+ Character devices that request a dynamic allocation of major
+ number will take numbers starting from 511 and downward,
+ once the 234-254 range is full.
diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
new file mode 100644
index 000000000000..095a63892257
--- /dev/null
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -0,0 +1,383 @@
+Dynamic debug
++++++++++++++
+
+
+Introduction
+============
+
+Dynamic debug allows you to dynamically enable/disable kernel
+debug-print code to obtain additional kernel information.
+
+If ``/proc/dynamic_debug/control`` exists, your kernel has dynamic
+debug. You'll need root access (sudo su) to use this.
+
+Dynamic debug provides:
+
+ * a Catalog of all *prdbgs* in your kernel.
+ ``cat /proc/dynamic_debug/control`` to see them.
+
+ * a Simple query/command language to alter *prdbgs* by selecting on
+ any combination of 0 or 1 of:
+
+ - source filename
+ - function name
+ - line number (including ranges of line numbers)
+ - module name
+ - format string
+ - class name (as known/declared by each module)
+
+NOTE: To actually get the debug-print output on the console, you may
+need to adjust the kernel ``loglevel=``, or use ``ignore_loglevel``.
+Read about these kernel parameters in
+Documentation/admin-guide/kernel-parameters.rst.
+
+Viewing Dynamic Debug Behaviour
+===============================
+
+You can view the currently configured behaviour in the *prdbg* catalog::
+
+ :#> head -n7 /proc/dynamic_debug/control
+ # filename:lineno [module]function flags format
+ init/main.c:1179 [main]initcall_blacklist =_ "blacklisting initcall %s\012
+ init/main.c:1218 [main]initcall_blacklisted =_ "initcall %s blacklisted\012"
+ init/main.c:1424 [main]run_init_process =_ " with arguments:\012"
+ init/main.c:1426 [main]run_init_process =_ " %s\012"
+ init/main.c:1427 [main]run_init_process =_ " with environment:\012"
+ init/main.c:1429 [main]run_init_process =_ " %s\012"
+
+The 3rd space-delimited column shows the current flags, preceded by
+a ``=`` for easy use with grep/cut. ``=p`` shows enabled callsites.
+
+Controlling dynamic debug Behaviour
+===================================
+
+The behaviour of *prdbg* sites are controlled by writing
+query/commands to the control file. Example::
+
+ # grease the interface
+ :#> alias ddcmd='echo $* > /proc/dynamic_debug/control'
+
+ :#> ddcmd '-p; module main func run* +p'
+ :#> grep =p /proc/dynamic_debug/control
+ init/main.c:1424 [main]run_init_process =p " with arguments:\012"
+ init/main.c:1426 [main]run_init_process =p " %s\012"
+ init/main.c:1427 [main]run_init_process =p " with environment:\012"
+ init/main.c:1429 [main]run_init_process =p " %s\012"
+
+Error messages go to console/syslog::
+
+ :#> ddcmd mode foo +p
+ dyndbg: unknown keyword "mode"
+ dyndbg: query parse failed
+ bash: echo: write error: Invalid argument
+
+If debugfs is also enabled and mounted, ``dynamic_debug/control`` is
+also under the mount-dir, typically ``/sys/kernel/debug/``.
+
+Command Language Reference
+==========================
+
+At the basic lexical level, a command is a sequence of words separated
+by spaces or tabs. So these are all equivalent::
+
+ :#> ddcmd file svcsock.c line 1603 +p
+ :#> ddcmd "file svcsock.c line 1603 +p"
+ :#> ddcmd ' file svcsock.c line 1603 +p '
+
+Command submissions are bounded by a write() system call.
+Multiple commands can be written together, separated by ``;`` or ``\n``::
+
+ :#> ddcmd "func pnpacpi_get_resources +p; func pnp_assign_mem +p"
+ :#> ddcmd <<"EOC"
+ func pnpacpi_get_resources +p
+ func pnp_assign_mem +p
+ EOC
+ :#> cat query-batch-file > /proc/dynamic_debug/control
+
+You can also use wildcards in each query term. The match rule supports
+``*`` (matches zero or more characters) and ``?`` (matches exactly one
+character). For example, you can match all usb drivers::
+
+ :#> ddcmd file "drivers/usb/*" +p # "" to suppress shell expansion
+
+Syntactically, a command is pairs of keyword values, followed by a
+flags change or setting::
+
+ command ::= match-spec* flags-spec
+
+The match-spec's select *prdbgs* from the catalog, upon which to apply
+the flags-spec, all constraints are ANDed together. An absent keyword
+is the same as keyword "*".
+
+
+A match specification is a keyword, which selects the attribute of
+the callsite to be compared, and a value to compare against. Possible
+keywords are:::
+
+ match-spec ::= 'func' string |
+ 'file' string |
+ 'module' string |
+ 'format' string |
+ 'class' string |
+ 'line' line-range
+
+ line-range ::= lineno |
+ '-'lineno |
+ lineno'-' |
+ lineno'-'lineno
+
+ lineno ::= unsigned-int
+
+.. note::
+
+ ``line-range`` cannot contain space, e.g.
+ "1-30" is valid range but "1 - 30" is not.
+
+
+The meanings of each keyword are:
+
+func
+ The given string is compared against the function name
+ of each callsite. Example::
+
+ func svc_tcp_accept
+ func *recv* # in rfcomm, bluetooth, ping, tcp
+
+file
+ The given string is compared against either the src-root relative
+ pathname, or the basename of the source file of each callsite.
+ Examples::
+
+ file svcsock.c
+ file kernel/freezer.c # ie column 1 of control file
+ file drivers/usb/* # all callsites under it
+ file inode.c:start_* # parse :tail as a func (above)
+ file inode.c:1-100 # parse :tail as a line-range (above)
+
+module
+ The given string is compared against the module name
+ of each callsite. The module name is the string as
+ seen in ``lsmod``, i.e. without the directory or the ``.ko``
+ suffix and with ``-`` changed to ``_``. Examples::
+
+ module sunrpc
+ module nfsd
+ module drm* # both drm, drm_kms_helper
+
+format
+ The given string is searched for in the dynamic debug format
+ string. Note that the string does not need to match the
+ entire format, only some part. Whitespace and other
+ special characters can be escaped using C octal character
+ escape ``\ooo`` notation, e.g. the space character is ``\040``.
+ Alternatively, the string can be enclosed in double quote
+ characters (``"``) or single quote characters (``'``).
+ Examples::
+
+ format svcrdma: // many of the NFS/RDMA server pr_debugs
+ format readahead // some pr_debugs in the readahead cache
+ format nfsd:\040SETATTR // one way to match a format with whitespace
+ format "nfsd: SETATTR" // a neater way to match a format with whitespace
+ format 'nfsd: SETATTR' // yet another way to match a format with whitespace
+
+class
+ The given class_name is validated against each module, which may
+ have declared a list of known class_names. If the class_name is
+ found for a module, callsite & class matching and adjustment
+ proceeds. Examples::
+
+ class DRM_UT_KMS # a DRM.debug category
+ class JUNK # silent non-match
+ // class TLD_* # NOTICE: no wildcard in class names
+
+line
+ The given line number or range of line numbers is compared
+ against the line number of each ``pr_debug()`` callsite. A single
+ line number matches the callsite line number exactly. A
+ range of line numbers matches any callsite between the first
+ and last line number inclusive. An empty first number means
+ the first line in the file, an empty last line number means the
+ last line number in the file. Examples::
+
+ line 1603 // exactly line 1603
+ line 1600-1605 // the six lines from line 1600 to line 1605
+ line -1605 // the 1605 lines from line 1 to line 1605
+ line 1600- // all lines from line 1600 to the end of the file
+
+The flags specification comprises a change operation followed
+by one or more flag characters. The change operation is one
+of the characters::
+
+ - remove the given flags
+ + add the given flags
+ = set the flags to the given flags
+
+The flags are::
+
+ p enables the pr_debug() callsite.
+ _ enables no flags.
+
+ Decorator flags add to the message-prefix, in order:
+ t Include thread ID, or <intr>
+ m Include module name
+ f Include the function name
+ s Include the source file name
+ l Include line number
+ d Include call trace
+
+For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only
+the ``p`` flag has meaning, other flags are ignored.
+
+Note the regexp ``^[-+=][fslmptd_]+$`` matches a flags specification.
+To clear all flags at once, use ``=_`` or ``-fslmptd``.
+
+
+Debug messages during Boot Process
+==================================
+
+To activate debug messages for core code and built-in modules during
+the boot process, even before userspace and debugfs exists, use
+``dyndbg="QUERY"`` or ``module.dyndbg="QUERY"``. QUERY follows
+the syntax described above, but must not exceed 1023 characters. Your
+bootloader may impose lower limits.
+
+These ``dyndbg`` params are processed just after the ddebug tables are
+processed, as part of the early_initcall. Thus you can enable debug
+messages in all code run after this early_initcall via this boot
+parameter.
+
+On an x86 system for example ACPI enablement is a subsys_initcall and::
+
+ dyndbg="file ec.c +p"
+
+will show early Embedded Controller transactions during ACPI setup if
+your machine (typically a laptop) has an Embedded Controller.
+PCI (or other devices) initialization also is a hot candidate for using
+this boot parameter for debugging purposes.
+
+If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at
+boot time, without effect, but will be reprocessed when module is
+loaded later. Bare ``dyndbg=`` is only processed at boot.
+
+
+Debug Messages at Module Initialization Time
+============================================
+
+When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for
+``foo.params``, strips ``foo.``, and passes them to the kernel along with
+params given in modprobe args or ``/etc/modprobe.d/*.conf`` files,
+in the following order:
+
+1. parameters given via ``/etc/modprobe.d/*.conf``::
+
+ options foo dyndbg=+pt
+ options foo dyndbg # defaults to +p
+
+2. ``foo.dyndbg`` as given in boot args, ``foo.`` is stripped and passed::
+
+ foo.dyndbg=" func bar +p; func buz +mp"
+
+3. args to modprobe::
+
+ modprobe foo dyndbg==pmf # override previous settings
+
+These ``dyndbg`` queries are applied in order, with last having final say.
+This allows boot args to override or modify those from ``/etc/modprobe.d``
+(sensible, since 1 is system wide, 2 is kernel or boot specific), and
+modprobe args to override both.
+
+In the ``foo.dyndbg="QUERY"`` form, the query must exclude ``module foo``.
+``foo`` is extracted from the param-name, and applied to each query in
+``QUERY``, and only 1 match-spec of each type is allowed.
+
+The ``dyndbg`` option is a "fake" module parameter, which means:
+
+- modules do not need to define it explicitly
+- every module gets it tacitly, whether they use pr_debug or not
+- it doesn't appear in ``/sys/module/$module/parameters/``
+ To see it, grep the control file, or inspect ``/proc/cmdline.``
+
+For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or
+enabled by ``-DDEBUG`` flag during compilation) can be disabled later via
+the debugfs interface if the debug messages are no longer needed::
+
+ echo "module module_name -p" > /proc/dynamic_debug/control
+
+Examples
+========
+
+::
+
+ // enable the message at line 1603 of file svcsock.c
+ :#> ddcmd 'file svcsock.c line 1603 +p'
+
+ // enable all the messages in file svcsock.c
+ :#> ddcmd 'file svcsock.c +p'
+
+ // enable all the messages in the NFS server module
+ :#> ddcmd 'module nfsd +p'
+
+ // enable all 12 messages in the function svc_process()
+ :#> ddcmd 'func svc_process +p'
+
+ // disable all 12 messages in the function svc_process()
+ :#> ddcmd 'func svc_process -p'
+
+ // enable messages for NFS calls READ, READLINK, READDIR and READDIR+.
+ :#> ddcmd 'format "nfsd: READ" +p'
+
+ // enable messages in files of which the paths include string "usb"
+ :#> ddcmd 'file *usb* +p'
+
+ // enable all messages
+ :#> ddcmd '+p'
+
+ // add module, function to all enabled messages
+ :#> ddcmd '+mf'
+
+ // boot-args example, with newlines and comments for readability
+ Kernel command line: ...
+ // see what's going on in dyndbg=value processing
+ dynamic_debug.verbose=3
+ // enable pr_debugs in the btrfs module (can be builtin or loadable)
+ btrfs.dyndbg="+p"
+ // enable pr_debugs in all files under init/
+ // and the function parse_one, #cmt is stripped
+ dyndbg="file init/* +p #cmt ; func parse_one +p"
+ // enable pr_debugs in 2 functions in a module loaded later
+ pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p"
+
+Kernel Configuration
+====================
+
+Dynamic Debug is enabled via kernel config items::
+
+ CONFIG_DYNAMIC_DEBUG=y # build catalog, enables CORE
+ CONFIG_DYNAMIC_DEBUG_CORE=y # enable mechanics only, skip catalog
+
+If you do not want to enable dynamic debug globally (i.e. in some embedded
+system), you may set ``CONFIG_DYNAMIC_DEBUG_CORE`` as basic support of dynamic
+debug and add ``ccflags := -DDYNAMIC_DEBUG_MODULE`` into the Makefile of any
+modules which you'd like to dynamically debug later.
+
+
+Kernel *prdbg* API
+==================
+
+The following functions are cataloged and controllable when dynamic
+debug is enabled::
+
+ pr_debug()
+ dev_dbg()
+ print_hex_dump_debug()
+ print_hex_dump_bytes()
+
+Otherwise, they are off by default; ``ccflags += -DDEBUG`` or
+``#define DEBUG`` in a source file will enable them appropriately.
+
+If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is
+just a shortcut for ``print_hex_dump(KERN_DEBUG)``.
+
+For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is
+its ``prefix_str`` argument, if it is constant string; or ``hexdump``
+in case ``prefix_str`` is built dynamically.
diff --git a/Documentation/admin-guide/edid.rst b/Documentation/admin-guide/edid.rst
new file mode 100644
index 000000000000..1a9b965aa486
--- /dev/null
+++ b/Documentation/admin-guide/edid.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+EDID
+====
+
+In the good old days when graphics parameters were configured explicitly
+in a file called xorg.conf, even broken hardware could be managed.
+
+Today, with the advent of Kernel Mode Setting, a graphics board is
+either correctly working because all components follow the standards -
+or the computer is unusable, because the screen remains dark after
+booting or it displays the wrong area. Cases when this happens are:
+
+- The graphics board does not recognize the monitor.
+- The graphics board is unable to detect any EDID data.
+- The graphics board incorrectly forwards EDID data to the driver.
+- The monitor sends no or bogus EDID data.
+- A KVM sends its own EDID data instead of querying the connected monitor.
+
+Adding the kernel parameter "nomodeset" helps in most cases, but causes
+restrictions later on.
+
+As a remedy for such situations, the kernel configuration item
+CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an
+individually prepared or corrected EDID data set in the /lib/firmware
+directory from where it is loaded via the firmware interface.
diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst
new file mode 100644
index 000000000000..f8e7407698bd
--- /dev/null
+++ b/Documentation/admin-guide/efi-stub.rst
@@ -0,0 +1,103 @@
+=================
+The EFI Boot Stub
+=================
+
+On the x86 and ARM platforms, a kernel zImage/bzImage can masquerade
+as a PE/COFF image, thereby convincing EFI firmware loaders to load
+it as an EFI executable. The code that modifies the bzImage header,
+along with the EFI-specific entry point that the firmware loader
+jumps to are collectively known as the "EFI boot stub", and live in
+arch/x86/boot/header.S and drivers/firmware/efi/libstub/x86-stub.c,
+respectively. For ARM the EFI stub is implemented in
+arch/arm/boot/compressed/efi-header.S and
+drivers/firmware/efi/libstub/arm32-stub.c. EFI stub code that is shared
+between architectures is in drivers/firmware/efi/libstub.
+
+For arm64, there is no compressed kernel support, so the Image itself
+masquerades as a PE/COFF image and the EFI stub is linked into the
+kernel. The arm64 EFI stub lives in drivers/firmware/efi/libstub/arm64.c
+and drivers/firmware/efi/libstub/arm64-stub.c.
+
+By using the EFI boot stub it's possible to boot a Linux kernel
+without the use of a conventional EFI boot loader, such as grub or
+elilo. Since the EFI boot stub performs the jobs of a boot loader, in
+a certain sense it *IS* the boot loader.
+
+The EFI boot stub is enabled with the CONFIG_EFI_STUB kernel option.
+
+
+How to install bzImage.efi
+--------------------------
+
+The bzImage located in arch/x86/boot/bzImage must be copied to the EFI
+System Partition (ESP) and renamed with the extension ".efi". Without
+the extension the EFI firmware loader will refuse to execute it. It's
+not possible to execute bzImage.efi from the usual Linux file systems
+because EFI firmware doesn't have support for them. For ARM the
+arch/arm/boot/zImage should be copied to the system partition, and it
+may not need to be renamed. Similarly for arm64, arch/arm64/boot/Image
+should be copied but not necessarily renamed.
+
+
+Passing kernel parameters from the EFI shell
+--------------------------------------------
+
+Arguments to the kernel can be passed after bzImage.efi, e.g.::
+
+ fs0:> bzImage.efi console=ttyS0 root=/dev/sda4
+
+
+The "initrd=" option
+--------------------
+
+Like most boot loaders, the EFI stub allows the user to specify
+multiple initrd files using the "initrd=" option. This is the only EFI
+stub-specific command line parameter, everything else is passed to the
+kernel when it boots.
+
+The path to the initrd file must be an absolute path from the
+beginning of the ESP, relative path names do not work. Also, the path
+is an EFI-style path and directory elements must be separated with
+backslashes (\). For example, given the following directory layout::
+
+ fs0:>
+ Kernels\
+ bzImage.efi
+ initrd-large.img
+
+ Ramdisks\
+ initrd-small.img
+ initrd-medium.img
+
+to boot with the initrd-large.img file if the current working
+directory is fs0:\Kernels, the following command must be used::
+
+ fs0:\Kernels> bzImage.efi initrd=\Kernels\initrd-large.img
+
+Notice how bzImage.efi can be specified with a relative path. That's
+because the image we're executing is interpreted by the EFI shell,
+which understands relative paths, whereas the rest of the command line
+is passed to bzImage.efi.
+
+.. hint::
+ It is also possible to provide an initrd using a Linux-specific UEFI
+ protocol at boot time. See :ref:`pe-coff-entry-point` for details.
+
+The "dtb=" option
+-----------------
+
+For the ARM and arm64 architectures, a device tree must be provided to
+the kernel. Normally firmware shall supply the device tree via the
+EFI CONFIGURATION TABLE. However, the "dtb=" command line option can
+be used to override the firmware supplied device tree, or to supply
+one when firmware is unable to.
+
+Please note: Firmware adds runtime configuration information to the
+device tree before booting the kernel. If dtb= is used to override
+the device tree, then any runtime data provided by firmware will be
+lost. The dtb= option should only be used either as a debug tool, or
+as a last resort when a device tree is not provided in the EFI
+CONFIGURATION TABLE.
+
+"dtb=" is processed in the same manner as the "initrd=" option that is
+described above.
diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
new file mode 100644
index 000000000000..ac0c709ea9e7
--- /dev/null
+++ b/Documentation/admin-guide/ext4.rst
@@ -0,0 +1,613 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+ext4 General Information
+========================
+
+Ext4 is an advanced level of the ext3 filesystem which incorporates
+scalability and reliability enhancements for supporting large filesystems
+(64 bit) in keeping with increasing disk capacities and state-of-the-art
+feature requirements.
+
+Mailing list: linux-ext4@vger.kernel.org
+Web site: http://ext4.wiki.kernel.org
+
+
+Quick usage instructions
+========================
+
+Note: More extensive information for getting started with ext4 can be
+found at the ext4 wiki site at the URL:
+http://ext4.wiki.kernel.org/index.php/Ext4_Howto
+
+ - The latest version of e2fsprogs can be found at:
+
+ https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/
+
+ or
+
+ http://sourceforge.net/project/showfiles.php?group_id=2406
+
+ or grab the latest git repository from:
+
+ https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git
+
+ - Create a new filesystem using the ext4 filesystem type:
+
+ # mke2fs -t ext4 /dev/hda1
+
+ Or to configure an existing ext3 filesystem to support extents:
+
+ # tune2fs -O extents /dev/hda1
+
+ If the filesystem was created with 128 byte inodes, it can be
+ converted to use 256 byte for greater efficiency via:
+
+ # tune2fs -I 256 /dev/hda1
+
+ - Mounting:
+
+ # mount -t ext4 /dev/hda1 /wherever
+
+ - When comparing performance with other filesystems, it's always
+ important to try multiple workloads; very often a subtle change in a
+ workload parameter can completely change the ranking of which
+ filesystems do well compared to others. When comparing versus ext3,
+ note that ext4 enables write barriers by default, while ext3 does
+ not enable write barriers by default. So it is useful to use
+ explicitly specify whether barriers are enabled or not when via the
+ '-o barriers=[0|1]' mount option for both ext3 and ext4 filesystems
+ for a fair comparison. When tuning ext3 for best benchmark numbers,
+ it is often worthwhile to try changing the data journaling mode; '-o
+ data=writeback' can be faster for some workloads. (Note however that
+ running mounted with data=writeback can potentially leave stale data
+ exposed in recently written files in case of an unclean shutdown,
+ which could be a security exposure in some situations.) Configuring
+ the filesystem with a large journal can also be helpful for
+ metadata-intensive workloads.
+
+Features
+========
+
+Currently Available
+-------------------
+
+* ability to use filesystems > 16TB (e2fsprogs support not available yet)
+* extent format reduces metadata overhead (RAM, IO for access, transactions)
+* extent format more robust in face of on-disk corruption due to magics,
+* internal redundancy in tree
+* improved file allocation (multi-block alloc)
+* lift 32000 subdirectory limit imposed by i_links_count[1]
+* nsec timestamps for mtime, atime, ctime, create time
+* inode version field on disk (NFSv4, Lustre)
+* reduced e2fsck time via uninit_bg feature
+* journal checksumming for robustness, performance
+* persistent file preallocation (e.g for streaming media, databases)
+* ability to pack bitmaps and inode tables into larger virtual groups via the
+ flex_bg feature
+* large file support
+* inode allocation using large virtual block groups via flex_bg
+* delayed allocation
+* large block (up to pagesize) support
+* efficient new ordered mode in JBD2 and ext4 (avoid using buffer head to force
+ the ordering)
+* Case-insensitive file name lookups
+* file-based encryption support (fscrypt)
+* file-based verity support (fsverity)
+
+[1] Filesystems with a block size of 1k may see a limit imposed by the
+directory hash tree having a maximum depth of two.
+
+case-insensitive file name lookups
+======================================================
+
+The case-insensitive file name lookup feature is supported on a
+per-directory basis, allowing the user to mix case-insensitive and
+case-sensitive directories in the same filesystem. It is enabled by
+flipping the +F inode attribute of an empty directory. The
+case-insensitive string match operation is only defined when we know how
+text in encoded in a byte sequence. For that reason, in order to enable
+case-insensitive directories, the filesystem must have the
+casefold feature, which stores the filesystem-wide encoding
+model used. By default, the charset adopted is the latest version of
+Unicode (12.1.0, by the time of this writing), encoded in the UTF-8
+form. The comparison algorithm is implemented by normalizing the
+strings to the Canonical decomposition form, as defined by Unicode,
+followed by a byte per byte comparison.
+
+The case-awareness is name-preserving on the disk, meaning that the file
+name provided by userspace is a byte-per-byte match to what is actually
+written in the disk. The Unicode normalization format used by the
+kernel is thus an internal representation, and not exposed to the
+userspace nor to the disk, with the important exception of disk hashes,
+used on large case-insensitive directories with DX feature. On DX
+directories, the hash must be calculated using the casefolded version of
+the filename, meaning that the normalization format used actually has an
+impact on where the directory entry is stored.
+
+When we change from viewing filenames as opaque byte sequences to seeing
+them as encoded strings we need to address what happens when a program
+tries to create a file with an invalid name. The Unicode subsystem
+within the kernel leaves the decision of what to do in this case to the
+filesystem, which select its preferred behavior by enabling/disabling
+the strict mode. When Ext4 encounters one of those strings and the
+filesystem did not require strict mode, it falls back to considering the
+entire string as an opaque byte sequence, which still allows the user to
+operate on that file, but the case-insensitive lookups won't work.
+
+Options
+=======
+
+When mounting an ext4 filesystem, the following option are accepted:
+(*) == default
+
+ ro
+ Mount filesystem read only. Note that ext4 will replay the journal (and
+ thus write to the partition) even when mounted "read only". The mount
+ options "ro,noload" can be used to prevent writes to the filesystem.
+
+ journal_checksum
+ Enable checksumming of the journal transactions. This will allow the
+ recovery code in e2fsck and the kernel to detect corruption in the
+ kernel. It is a compatible change and will be ignored by older
+ kernels.
+
+ journal_async_commit
+ Commit block can be written to disk without waiting for descriptor
+ blocks. If enabled older kernels cannot mount the device. This will
+ enable 'journal_checksum' internally.
+
+ journal_path=path, journal_dev=devnum
+ When the external journal device's major/minor numbers have changed,
+ these options allow the user to specify the new journal location. The
+ journal device is identified through either its new major/minor numbers
+ encoded in devnum, or via a path to the device.
+
+ norecovery, noload
+ Don't load the journal on mounting. Note that if the filesystem was
+ not unmounted cleanly, skipping the journal replay will lead to the
+ filesystem containing inconsistencies that can lead to any number of
+ problems.
+
+ data=journal
+ All data are committed into the journal prior to being written into the
+ main file system. Enabling this mode will disable delayed allocation
+ and O_DIRECT support.
+
+ data=ordered (*)
+ All data are forced directly out to the main file system prior to its
+ metadata being committed to the journal.
+
+ data=writeback
+ Data ordering is not preserved, data may be written into the main file
+ system after its metadata has been committed to the journal.
+
+ commit=nrsec (*)
+ This setting limits the maximum age of the running transaction to
+ 'nrsec' seconds. The default value is 5 seconds. This means that if
+ you lose your power, you will lose as much as the latest 5 seconds of
+ metadata changes (your filesystem will not be damaged though, thanks
+ to the journaling). This default value (or any low value) will hurt
+ performance, but it's good for data-safety. Setting it to 0 will have
+ the same effect as leaving it at the default (5 seconds). Setting it
+ to very large values will improve performance. Note that due to
+ delayed allocation even older data can be lost on power failure since
+ writeback of those data begins only after time set in
+ /proc/sys/vm/dirty_expire_centisecs.
+
+ barrier=<0|1(*)>, barrier(*), nobarrier
+ This enables/disables the use of write barriers in the jbd code.
+ barrier=0 disables, barrier=1 enables. This also requires an IO stack
+ which can support barriers, and if jbd gets an error on a barrier
+ write, it will disable again with a warning. Write barriers enforce
+ proper on-disk ordering of journal commits, making volatile disk write
+ caches safe to use, at some performance penalty. If your disks are
+ battery-backed in one way or another, disabling barriers may safely
+ improve performance. The mount options "barrier" and "nobarrier" can
+ also be used to enable or disable barriers, for consistency with other
+ ext4 mount options.
+
+ inode_readahead_blks=n
+ This tuning parameter controls the maximum number of inode table blocks
+ that ext4's inode table readahead algorithm will pre-read into the
+ buffer cache. The default value is 32 blocks.
+
+ bsddf (*)
+ Make 'df' act like BSD.
+
+ minixdf
+ Make 'df' act like Minix.
+
+ debug
+ Extra debugging information is sent to syslog.
+
+ abort
+ Simulate the effects of calling ext4_abort() for debugging purposes.
+ This is normally used while remounting a filesystem which is already
+ mounted.
+
+ errors=remount-ro
+ Remount the filesystem read-only on an error.
+
+ errors=continue
+ Keep going on a filesystem error.
+
+ errors=panic
+ Panic and halt the machine if an error occurs. (These mount options
+ override the errors behavior specified in the superblock, which can be
+ configured using tune2fs)
+
+ data_err=ignore(*)
+ Just print an error message if an error occurs in a file data buffer.
+
+ data_err=abort
+ Abort the journal if an error occurs in a file data buffer.
+
+ grpid | bsdgroups
+ New objects have the group ID of their parent.
+
+ nogrpid (*) | sysvgroups
+ New objects have the group ID of their creator.
+
+ resgid=n
+ The group ID which may use the reserved blocks.
+
+ resuid=n
+ The user ID which may use the reserved blocks.
+
+ sb=
+ Use alternate superblock at this location.
+
+ quota, noquota, grpquota, usrquota
+ These options are ignored by the filesystem. They are used only by
+ quota tools to recognize volumes where quota should be turned on. See
+ documentation in the quota-tools package for more details
+ (http://sourceforge.net/projects/linuxquota).
+
+ jqfmt=<quota type>, usrjquota=<file>, grpjquota=<file>
+ These options tell filesystem details about quota so that quota
+ information can be properly updated during journal replay. They replace
+ the above quota options. See documentation in the quota-tools package
+ for more details (http://sourceforge.net/projects/linuxquota).
+
+ stripe=n
+ Number of filesystem blocks that mballoc will try to use for allocation
+ size and alignment. For RAID5/6 systems this should be the number of
+ data disks * RAID chunk size in file system blocks.
+
+ delalloc (*)
+ Defer block allocation until just before ext4 writes out the block(s)
+ in question. This allows ext4 to better allocation decisions more
+ efficiently.
+
+ nodelalloc
+ Disable delayed allocation. Blocks are allocated when the data is
+ copied from userspace to the page cache, either via the write(2) system
+ call or when an mmap'ed page which was previously unallocated is
+ written for the first time.
+
+ max_batch_time=usec
+ Maximum amount of time ext4 should wait for additional filesystem
+ operations to be batch together with a synchronous write operation.
+ Since a synchronous write operation is going to force a commit and then
+ a wait for the I/O complete, it doesn't cost much, and can be a huge
+ throughput win, we wait for a small amount of time to see if any other
+ transactions can piggyback on the synchronous write. The algorithm
+ used is designed to automatically tune for the speed of the disk, by
+ measuring the amount of time (on average) that it takes to finish
+ committing a transaction. Call this time the "commit time". If the
+ time that the transaction has been running is less than the commit
+ time, ext4 will try sleeping for the commit time to see if other
+ operations will join the transaction. The commit time is capped by
+ the max_batch_time, which defaults to 15000us (15ms). This
+ optimization can be turned off entirely by setting max_batch_time to 0.
+
+ min_batch_time=usec
+ This parameter sets the commit time (as described above) to be at least
+ min_batch_time. It defaults to zero microseconds. Increasing this
+ parameter may improve the throughput of multi-threaded, synchronous
+ workloads on very fast disks, at the cost of increasing latency.
+
+ journal_ioprio=prio
+ The I/O priority (from 0 to 7, where 0 is the highest priority) which
+ should be used for I/O operations submitted by kjournald2 during a
+ commit operation. This defaults to 3, which is a slightly higher
+ priority than the default I/O priority.
+
+ auto_da_alloc(*), noauto_da_alloc
+ Many broken applications don't use fsync() when replacing existing
+ files via patterns such as fd = open("foo.new")/write(fd,..)/close(fd)/
+ rename("foo.new", "foo"), or worse yet, fd = open("foo",
+ O_TRUNC)/write(fd,..)/close(fd). If auto_da_alloc is enabled, ext4
+ will detect the replace-via-rename and replace-via-truncate patterns
+ and force that any delayed allocation blocks are allocated such that at
+ the next journal commit, in the default data=ordered mode, the data
+ blocks of the new file are forced to disk before the rename() operation
+ is committed. This provides roughly the same level of guarantees as
+ ext3, and avoids the "zero-length" problem that can happen when a
+ system crashes before the delayed allocation blocks are forced to disk.
+
+ noinit_itable
+ Do not initialize any uninitialized inode table blocks in the
+ background. This feature may be used by installation CD's so that the
+ install process can complete as quickly as possible; the inode table
+ initialization process would then be deferred until the next time the
+ file system is unmounted.
+
+ init_itable=n
+ The lazy itable init code will wait n times the number of milliseconds
+ it took to zero out the previous block group's inode table. This
+ minimizes the impact on the system performance while file system's
+ inode table is being initialized.
+
+ discard, nodiscard(*)
+ Controls whether ext4 should issue discard/TRIM commands to the
+ underlying block device when blocks are freed. This is useful for SSD
+ devices and sparse/thinly-provisioned LUNs, but it is off by default
+ until sufficient testing has been done.
+
+ nouid32
+ Disables 32-bit UIDs and GIDs. This is for interoperability with
+ older kernels which only store and expect 16-bit values.
+
+ block_validity(*), noblock_validity
+ These options enable or disable the in-kernel facility for tracking
+ filesystem metadata blocks within internal data structures. This
+ allows multi- block allocator and other routines to notice bugs or
+ corrupted allocation bitmaps which cause blocks to be allocated which
+ overlap with filesystem metadata blocks.
+
+ dioread_lock, dioread_nolock
+ Controls whether or not ext4 should use the DIO read locking. If the
+ dioread_nolock option is specified ext4 will allocate uninitialized
+ extent before buffer write and convert the extent to initialized after
+ IO completes. This approach allows ext4 code to avoid using inode
+ mutex, which improves scalability on high speed storages. However this
+ does not work with data journaling and dioread_nolock option will be
+ ignored with kernel warning. Note that dioread_nolock code path is only
+ used for extent-based files. Because of the restrictions this options
+ comprises it is off by default (e.g. dioread_lock).
+
+ max_dir_size_kb=n
+ This limits the size of directories so that any attempt to expand them
+ beyond the specified limit in kilobytes will cause an ENOSPC error.
+ This is useful in memory constrained environments, where a very large
+ directory can cause severe performance problems or even provoke the Out
+ Of Memory killer. (For example, if there is only 512mb memory
+ available, a 176mb directory may seriously cramp the system's style.)
+
+ i_version
+ Enable 64-bit inode version support. This option is off by default.
+
+ dax
+ Use direct access (no page cache). See
+ Documentation/filesystems/dax.rst. Note that this option is
+ incompatible with data=journal.
+
+ inlinecrypt
+ When possible, encrypt/decrypt the contents of encrypted files using the
+ blk-crypto framework rather than filesystem-layer encryption. This
+ allows the use of inline encryption hardware. The on-disk format is
+ unaffected. For more details, see
+ Documentation/block/inline-encryption.rst.
+
+Data Mode
+=========
+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 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.
+
+* ordered mode
+
+ In data=ordered mode, ext4 only officially journals metadata, but it logically
+ groups metadata information related to data changes with the data blocks into
+ a single unit called a transaction. When it's time to write the new metadata
+ out to disk, the associated data blocks are written first. In general, this
+ mode performs slightly slower than writeback but significantly faster than
+ journal mode.
+
+* journal mode
+
+ data=journal mode provides full data and metadata journaling. All new data is
+ written to the journal first, and then to its final location. In the event of
+ a crash, the journal can be replayed, bringing both data and metadata into a
+ consistent state. This mode is the slowest except when data needs to be read
+ from and written to disk at the same time where it outperforms all others
+ modes. Enabling this mode will disable delayed allocation and O_DIRECT
+ support.
+
+/proc entries
+=============
+
+Information about mounted ext4 file systems can be found in
+/proc/fs/ext4. Each mounted filesystem will have a directory in
+/proc/fs/ext4 based on its device name (i.e., /proc/fs/ext4/hdc or
+/proc/fs/ext4/dm-0). The files in each per-device directory are shown
+in table below.
+
+Files in /proc/fs/ext4/<devname>
+
+ mb_groups
+ details of multiblock allocator buddy cache of free blocks
+
+/sys entries
+============
+
+Information about mounted ext4 file systems can be found in
+/sys/fs/ext4. Each mounted filesystem will have a directory in
+/sys/fs/ext4 based on its device name (i.e., /sys/fs/ext4/hdc or
+/sys/fs/ext4/dm-0). The files in each per-device directory are shown
+in table below.
+
+Files in /sys/fs/ext4/<devname>:
+
+(see also Documentation/ABI/testing/sysfs-fs-ext4)
+
+ delayed_allocation_blocks
+ This file is read-only and shows the number of blocks that are dirty in
+ the page cache, but which do not have their location in the filesystem
+ allocated yet.
+
+ inode_goal
+ Tuning parameter which (if non-zero) controls the goal inode used by
+ the inode allocator in preference to all other allocation heuristics.
+ This is intended for debugging use only, and should be 0 on production
+ systems.
+
+ inode_readahead_blks
+ Tuning parameter which controls the maximum number of inode table
+ blocks that ext4's inode table readahead algorithm will pre-read into
+ the buffer cache.
+
+ lifetime_write_kbytes
+ This file is read-only and shows the number of kilobytes of data that
+ have been written to this filesystem since it was created.
+
+ max_writeback_mb_bump
+ The maximum number of megabytes the writeback code will try to write
+ out before move on to another inode.
+
+ mb_group_prealloc
+ The multiblock allocator will round up allocation requests to a
+ multiple of this tuning parameter if the stripe size is not set in the
+ ext4 superblock
+
+ mb_max_to_scan
+ The maximum number of extents the multiblock allocator will search to
+ find the best extent.
+
+ mb_min_to_scan
+ The minimum number of extents the multiblock allocator will search to
+ find the best extent.
+
+ mb_order2_req
+ Tuning parameter which controls the minimum size for requests (as a
+ power of 2) where the buddy cache is used.
+
+ mb_stats
+ Controls whether the multiblock allocator should collect statistics,
+ which are shown during the unmount. 1 means to collect statistics, 0
+ means not to collect statistics.
+
+ mb_stream_req
+ Files which have fewer blocks than this tunable parameter will have
+ their blocks allocated out of a block group specific preallocation
+ pool, so that small files are packed closely together. Each large file
+ will have its blocks allocated out of its own unique preallocation
+ pool.
+
+ session_write_kbytes
+ This file is read-only and shows the number of kilobytes of data that
+ have been written to this filesystem since it was mounted.
+
+ reserved_clusters
+ This is RW file and contains number of reserved clusters in the file
+ system which will be used in the specific situations to avoid costly
+ zeroout, unexpected ENOSPC, or possible data loss. The default is 2% or
+ 4096 clusters, whichever is smaller and this can be changed however it
+ can never exceed number of clusters in the file system. If there is not
+ enough space for the reserved space when mounting the file mount will
+ _not_ fail.
+
+Ioctls
+======
+
+Ext4 implements various ioctls which can be used by applications to access
+ext4-specific functionality. An incomplete list of these ioctls is shown in the
+table below. This list includes truly ext4-specific ioctls (``EXT4_IOC_*``) as
+well as ioctls that may have been ext4-specific originally but are now supported
+by some other filesystem(s) too (``FS_IOC_*``).
+
+Table of Ext4 ioctls
+
+ FS_IOC_GETFLAGS
+ Get additional attributes associated with inode. The ioctl argument is
+ an integer bitfield, with bit values described in ext4.h.
+
+ FS_IOC_SETFLAGS
+ Set additional attributes associated with inode. The ioctl argument is
+ an integer bitfield, with bit values described in ext4.h.
+
+ EXT4_IOC_GETVERSION, EXT4_IOC_GETVERSION_OLD
+ Get the inode i_generation number stored for each inode. The
+ i_generation number is normally changed only when new inode is created
+ and it is particularly useful for network filesystems. The '_OLD'
+ version of this ioctl is an alias for FS_IOC_GETVERSION.
+
+ EXT4_IOC_SETVERSION, EXT4_IOC_SETVERSION_OLD
+ Set the inode i_generation number stored for each inode. The '_OLD'
+ version of this ioctl is an alias for FS_IOC_SETVERSION.
+
+ EXT4_IOC_GROUP_EXTEND
+ This ioctl has the same purpose as the resize mount option. It allows
+ to resize filesystem to the end of the last existing block group,
+ further resize has to be done with resize2fs, either online, or
+ offline. The argument points to the unsigned logn number representing
+ the filesystem new block count.
+
+ EXT4_IOC_MOVE_EXT
+ Move the block extents from orig_fd (the one this ioctl is pointing to)
+ to the donor_fd (the one specified in move_extent structure passed as
+ an argument to this ioctl). Then, exchange inode metadata between
+ orig_fd and donor_fd. This is especially useful for online
+ defragmentation, because the allocator has the opportunity to allocate
+ moved blocks better, ideally into one contiguous extent.
+
+ EXT4_IOC_GROUP_ADD
+ Add a new group descriptor to an existing or new group descriptor
+ block. The new group descriptor is described by ext4_new_group_input
+ structure, which is passed as an argument to this ioctl. This is
+ especially useful in conjunction with EXT4_IOC_GROUP_EXTEND, which
+ allows online resize of the filesystem to the end of the last existing
+ block group. Those two ioctls combined is used in userspace online
+ resize tool (e.g. resize2fs).
+
+ EXT4_IOC_MIGRATE
+ This ioctl operates on the filesystem itself. It converts (migrates)
+ ext3 indirect block mapped inode to ext4 extent mapped inode by walking
+ through indirect block mapping of the original inode and converting
+ contiguous block ranges into ext4 extents of the temporary inode. Then,
+ inodes are swapped. This ioctl might help, when migrating from ext3 to
+ ext4 filesystem, however suggestion is to create fresh ext4 filesystem
+ and copy data from the backup. Note, that filesystem has to support
+ extents for this ioctl to work.
+
+ EXT4_IOC_ALLOC_DA_BLKS
+ Force all of the delay allocated blocks to be allocated to preserve
+ application-expected ext3 behaviour. Note that this will also start
+ triggering a write of the data blocks, but this behaviour may change in
+ the future as it is not necessary and has been done this way only for
+ sake of simplicity.
+
+ EXT4_IOC_RESIZE_FS
+ Resize the filesystem to a new size. The number of blocks of resized
+ filesystem is passed in via 64 bit integer argument. The kernel
+ allocates bitmaps and inode table, the userspace tool thus just passes
+ the new number of blocks.
+
+ EXT4_IOC_SWAP_BOOT
+ Swap i_blocks and associated attributes (like i_blocks, i_size,
+ i_flags, ...) from the specified inode with inode EXT4_BOOT_LOADER_INO
+ (#5). This is typically used to store a boot loader in a secure part of
+ the filesystem, where it can't be changed by a normal user by accident.
+ The data blocks of the previous boot loader will be associated with the
+ given inode.
+
+References
+==========
+
+kernel source: <file:fs/ext4/>
+ <file:fs/jbd2/>
+
+programs: http://e2fsprogs.sourceforge.net/
+
+useful links: https://fedoraproject.org/wiki/ext3-devel
+ http://www.bullopensource.org/ext4/
+ http://ext4.wiki.kernel.org/index.php/Main_Page
+ https://fedoraproject.org/wiki/Features/Ext4
diff --git a/Documentation/admin-guide/features.rst b/Documentation/admin-guide/features.rst
new file mode 100644
index 000000000000..7651eca38227
--- /dev/null
+++ b/Documentation/admin-guide/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: features
diff --git a/Documentation/admin-guide/filesystem-monitoring.rst b/Documentation/admin-guide/filesystem-monitoring.rst
new file mode 100644
index 000000000000..ab8dba76283c
--- /dev/null
+++ b/Documentation/admin-guide/filesystem-monitoring.rst
@@ -0,0 +1,78 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+File system Monitoring with fanotify
+====================================
+
+File system Error Reporting
+===========================
+
+Fanotify supports the FAN_FS_ERROR event type for file system-wide error
+reporting. It is meant to be used by file system health monitoring
+daemons, which listen for these events and take actions (notify
+sysadmin, start recovery) when a file system problem is detected.
+
+By design, a FAN_FS_ERROR notification exposes sufficient information
+for a monitoring tool to know a problem in the file system has happened.
+It doesn't necessarily provide a user space application with semantics
+to verify an IO operation was successfully executed. That is out of
+scope for this feature. Instead, it is only meant as a framework for
+early file system problem detection and reporting recovery tools.
+
+When a file system operation fails, it is common for dozens of kernel
+errors to cascade after the initial failure, hiding the original failure
+log, which is usually the most useful debug data to troubleshoot the
+problem. For this reason, FAN_FS_ERROR tries to report only the first
+error that occurred for a file system since the last notification, and
+it simply counts additional errors. This ensures that the most
+important pieces of information are never lost.
+
+FAN_FS_ERROR requires the fanotify group to be setup with the
+FAN_REPORT_FID flag.
+
+At the time of this writing, the only file system that emits FAN_FS_ERROR
+notifications is Ext4.
+
+A FAN_FS_ERROR Notification has the following format::
+
+ ::
+
+ [ Notification Metadata (Mandatory) ]
+ [ Generic Error Record (Mandatory) ]
+ [ FID record (Mandatory) ]
+
+The order of records is not guaranteed, and new records might be added
+in the future. Therefore, applications must not rely on the order and
+must be prepared to skip over unknown records. Please refer to
+``samples/fanotify/fs-monitor.c`` for an example parser.
+
+Generic error record
+--------------------
+
+The generic error record provides enough information for a file system
+agnostic tool to learn about a problem in the file system, without
+providing any additional details about the problem. This record is
+identified by ``struct fanotify_event_info_header.info_type`` being set
+to FAN_EVENT_INFO_TYPE_ERROR.
+
+ ::
+
+ struct fanotify_event_info_error {
+ struct fanotify_event_info_header hdr;
+ __s32 error;
+ __u32 error_count;
+ };
+
+The `error` field identifies the type of error using errno values.
+`error_count` tracks the number of errors that occurred and were
+suppressed to preserve the original error information, since the last
+notification.
+
+FID record
+----------
+
+The FID record can be used to uniquely identify the inode that triggered
+the error through the combination of fsid and file handle. A file system
+specific application can use that information to attempt a recovery
+procedure. Errors that are not related to an inode are reported with an
+empty file handle of type FILEID_INVALID.
diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst
new file mode 100644
index 000000000000..8374a9df9105
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst
@@ -0,0 +1,218 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+GPIO Aggregator
+===============
+
+The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as
+a new gpio_chip. This supports the following use cases.
+
+
+Aggregating GPIOs using Sysfs
+-----------------------------
+
+GPIO controllers are exported to userspace using /dev/gpiochip* character
+devices. Access control to these devices is provided by standard UNIX file
+system permissions, on an all-or-nothing basis: either a GPIO controller is
+accessible for a user, or it is not.
+
+The GPIO Aggregator provides access control for a set of one or more GPIOs, by
+aggregating them into a new gpio_chip, which can be assigned to a group or user
+using standard UNIX file ownership and permissions. Furthermore, this
+simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just
+grab the full GPIO controller, and no longer needs to care about which GPIOs to
+grab and which not, reducing the attack surface.
+
+Aggregated GPIO controllers are instantiated and destroyed by writing to
+write-only attribute files in sysfs.
+
+ /sys/bus/platform/drivers/gpio-aggregator/
+
+ "new_device" ...
+ Userspace may ask the kernel to instantiate an aggregated GPIO
+ controller by writing a string describing the GPIOs to
+ aggregate to the "new_device" file, using the format
+
+ .. code-block:: none
+
+ [<gpioA>] [<gpiochipB> <offsets>] ...
+
+ Where:
+
+ "<gpioA>" ...
+ is a GPIO line name,
+
+ "<gpiochipB>" ...
+ is a GPIO chip label, and
+
+ "<offsets>" ...
+ is a comma-separated list of GPIO offsets and/or
+ GPIO offset ranges denoted by dashes.
+
+ Example: Instantiate a new GPIO aggregator by aggregating GPIO
+ line 19 of "e6052000.gpio" and GPIO lines 20-21 of
+ "e6050000.gpio" into a new gpio_chip:
+
+ .. code-block:: sh
+
+ $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device
+
+ "delete_device" ...
+ Userspace may ask the kernel to destroy an aggregated GPIO
+ controller after use by writing its device name to the
+ "delete_device" file.
+
+ Example: Destroy the previously-created aggregated GPIO
+ controller, assumed to be "gpio-aggregator.0":
+
+ .. code-block:: sh
+
+ $ echo gpio-aggregator.0 > delete_device
+
+
+Aggregating GPIOs using Configfs
+--------------------------------
+
+**Group:** ``/config/gpio-aggregator``
+
+ This is the root directory of the gpio-aggregator configfs tree.
+
+**Group:** ``/config/gpio-aggregator/<example-name>``
+
+ This directory represents a GPIO aggregator device. You can assign any
+ name to ``<example-name>`` (e.g. ``agg0``), except names starting with
+ ``_sysfs`` prefix, which are reserved for auto-generated configfs
+ entries corresponding to devices created via Sysfs.
+
+**Attribute:** ``/config/gpio-aggregator/<example-name>/live``
+
+ The ``live`` attribute allows to trigger the actual creation of the device
+ once it's fully configured. Accepted values are:
+
+ * ``1``, ``yes``, ``true`` : enable the virtual device
+ * ``0``, ``no``, ``false`` : disable the virtual device
+
+**Attribute:** ``/config/gpio-aggregator/<example-name>/dev_name``
+
+ The read-only ``dev_name`` attribute exposes the name of the device as it
+ will appear in the system on the platform bus (e.g. ``gpio-aggregator.0``).
+ This is useful for identifying a character device for the newly created
+ aggregator. If it's ``gpio-aggregator.0``,
+ ``/sys/devices/platform/gpio-aggregator.0/gpiochipX`` path tells you that the
+ GPIO device id is ``X``.
+
+You must create subdirectories for each virtual line you want to
+instantiate, named exactly as ``line0``, ``line1``, ..., ``lineY``, when
+you want to instantiate ``Y+1`` (Y >= 0) lines. Configure all lines before
+activating the device by setting ``live`` to 1.
+
+**Group:** ``/config/gpio-aggregator/<example-name>/<lineY>/``
+
+ This directory represents a GPIO line to include in the aggregator.
+
+**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/key``
+
+**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/offset``
+
+ The default values after creating the ``<lineY>`` directory are:
+
+ * ``key`` : <empty>
+ * ``offset`` : -1
+
+ ``key`` must always be explicitly configured, while ``offset`` depends.
+ Two configuration patterns exist for each ``<lineY>``:
+
+ (a). For lookup by GPIO line name:
+
+ * Set ``key`` to the line name.
+ * Ensure ``offset`` remains -1 (the default).
+
+ (b). For lookup by GPIO chip name and the line offset within the chip:
+
+ * Set ``key`` to the chip name.
+ * Set ``offset`` to the line offset (0 <= ``offset`` < 65535).
+
+**Attribute:** ``/config/gpio-aggregator/<example-name>/<lineY>/name``
+
+ The ``name`` attribute sets a custom name for lineY. If left unset, the
+ line will remain unnamed.
+
+Once the configuration is done, the ``'live'`` attribute must be set to 1
+in order to instantiate the aggregator device. It can be set back to 0 to
+destroy the virtual device. The module will synchronously wait for the new
+aggregator device to be successfully probed and if this doesn't happen, writing
+to ``'live'`` will result in an error. This is a different behaviour from the
+case when you create it using sysfs ``new_device`` interface.
+
+.. note::
+
+ For aggregators created via Sysfs, the configfs entries are
+ auto-generated and appear as ``/config/gpio-aggregator/_sysfs.<N>/``. You
+ cannot add or remove line directories with mkdir(2)/rmdir(2). To modify
+ lines, you must use the "delete_device" interface to tear down the
+ existing device and reconfigure it from scratch. However, you can still
+ toggle the aggregator with the ``live`` attribute and adjust the
+ ``key``, ``offset``, and ``name`` attributes for each line when ``live``
+ is set to 0 by hand (i.e. it's not waiting for deferred probe).
+
+Sample configuration commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: sh
+
+ # Create a directory for an aggregator device
+ $ mkdir /sys/kernel/config/gpio-aggregator/agg0
+
+ # Configure each line
+ $ mkdir /sys/kernel/config/gpio-aggregator/agg0/line0
+ $ echo gpiochip0 > /sys/kernel/config/gpio-aggregator/agg0/line0/key
+ $ echo 6 > /sys/kernel/config/gpio-aggregator/agg0/line0/offset
+ $ echo test0 > /sys/kernel/config/gpio-aggregator/agg0/line0/name
+ $ mkdir /sys/kernel/config/gpio-aggregator/agg0/line1
+ $ echo gpiochip0 > /sys/kernel/config/gpio-aggregator/agg0/line1/key
+ $ echo 7 > /sys/kernel/config/gpio-aggregator/agg0/line1/offset
+ $ echo test1 > /sys/kernel/config/gpio-aggregator/agg0/line1/name
+
+ # Activate the aggregator device
+ $ echo 1 > /sys/kernel/config/gpio-aggregator/agg0/live
+
+
+Generic GPIO Driver
+-------------------
+
+The GPIO Aggregator can also be used as a generic driver for a simple
+GPIO-operated device described in DT, without a dedicated in-kernel driver.
+This is useful in industrial control, and is not unlike e.g. spidev, which
+allows the user to communicate with an SPI device from userspace.
+
+Binding a device to the GPIO Aggregator is performed either by modifying the
+gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.
+
+Example: If "door" is a GPIO-operated device described in DT, using its own
+compatible value::
+
+ door {
+ compatible = "myvendor,mydoor";
+
+ gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>,
+ <&gpio2 20 GPIO_ACTIVE_LOW>;
+ gpio-line-names = "open", "lock";
+ };
+
+it can be bound to the GPIO Aggregator by either:
+
+1. Adding its compatible value to ``gpio_aggregator_dt_ids[]``,
+2. Binding manually using "driver_override":
+
+.. code-block:: sh
+
+ $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
+ $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
+
+After that, a new gpiochip "door" has been created:
+
+.. code-block:: sh
+
+ $ gpioinfo door
+ gpiochip12 - 2 lines:
+ line 0: "open" unused input active-high
+ line 1: "lock" unused input active-high
diff --git a/Documentation/admin-guide/gpio/gpio-mockup.rst b/Documentation/admin-guide/gpio/gpio-mockup.rst
new file mode 100644
index 000000000000..d6e7438a7550
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-mockup.rst
@@ -0,0 +1,59 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+GPIO Testing Driver
+===================
+
+.. note::
+
+ This module has been obsoleted by the more flexible gpio-sim.rst.
+ New developments should use that API and existing developments are
+ encouraged to migrate as soon as possible.
+ This module will continue to be maintained but no new features will be
+ added.
+
+The GPIO Testing Driver (gpio-mockup) provides a way to create simulated GPIO
+chips for testing purposes. The lines exposed by these chips can be accessed
+using the standard GPIO character device interface as well as manipulated
+using the dedicated debugfs directory structure.
+
+Creating simulated chips using module params
+--------------------------------------------
+
+When loading the gpio-mockup driver a number of parameters can be passed to the
+module.
+
+ gpio_mockup_ranges
+
+ This parameter takes an argument in the form of an array of integer
+ pairs. Each pair defines the base GPIO number (non-negative integer)
+ and the first number after the last of this chip. If the base GPIO
+ is -1, the gpiolib will assign it automatically. while the following
+ parameter is the number of lines exposed by the chip.
+
+ Example: gpio_mockup_ranges=-1,8,-1,16,405,409
+
+ The line above creates three chips. The first one will expose 8 lines,
+ the second 16 and the third 4. The base GPIO for the third chip is set
+ to 405 while for two first chips it will be assigned automatically.
+
+ gpio_mockup_named_lines
+
+ This parameter doesn't take any arguments. It lets the driver know that
+ GPIO lines exposed by it should be named.
+
+ The name format is: gpio-mockup-X-Y where X is mockup chip's ID
+ and Y is the line offset.
+
+Manipulating simulated lines
+----------------------------
+
+Each mockup chip creates its own subdirectory in /sys/kernel/debug/gpio-mockup/.
+The directory is named after the chip's label. A symlink is also created, named
+after the chip's name, which points to the label directory.
+
+Inside each subdirectory, there's a separate attribute for each GPIO line. The
+name of the attribute represents the line's offset in the chip.
+
+Reading from a line attribute returns the current value. Writing to it (0 or 1)
+changes the configuration of the simulated pull-up/pull-down resistor
+(1 - pull-up, 0 - pull-down).
diff --git a/Documentation/admin-guide/gpio/gpio-sim.rst b/Documentation/admin-guide/gpio/gpio-sim.rst
new file mode 100644
index 000000000000..f5135a14ef2e
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-sim.rst
@@ -0,0 +1,137 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Configfs GPIO Simulator
+=======================
+
+The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO
+chips for testing purposes. The lines exposed by these chips can be accessed
+using the standard GPIO character device interface as well as manipulated
+using sysfs attributes.
+
+Creating simulated chips
+------------------------
+
+The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For
+details of the configfs filesystem, please refer to the configfs documentation.
+
+The user can create a hierarchy of configfs groups and items as well as modify
+values of exposed attributes. Once the chip is instantiated, this hierarchy
+will be translated to appropriate device properties. The general structure is:
+
+**Group:** ``/config/gpio-sim``
+
+This is the top directory of the gpio-sim configfs tree.
+
+**Group:** ``/config/gpio-sim/gpio-device``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/dev_name``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/live``
+
+This is a directory representing a GPIO platform device. The ``'dev_name'``
+attribute is read-only and allows the user-space to read the platform device
+name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the
+actual creation of the device once it's fully configured. The accepted values
+are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear
+it down.
+
+**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines``
+
+This group represents a bank of GPIOs under the top platform device. The
+``'chip_name'`` attribute is read-only and allows the user-space to read the
+device name of the bank device. The ``'num_lines'`` attribute allows to specify
+the number of lines exposed by this bank.
+
+**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/valid``
+
+This group represents a single line at the offset Y. The ``valid`` attribute
+indicates whether the line can be used as GPIO. The ``name`` attribute allows
+to set the line name as represented by the 'gpio-line-names' property.
+
+**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name``
+
+**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction``
+
+This item makes the gpio-sim module hog the associated line. The ``'name'``
+attribute specifies the in-kernel consumer name to use. The ``'direction'``
+attribute specifies the hog direction and must be one of: ``'input'``,
+``'output-high'`` and ``'output-low'``.
+
+Inside each bank directory, there's a set of attributes that can be used to
+configure the new chip. Additionally the user can ``mkdir()`` subdirectories
+inside the chip's directory that allow to pass additional configuration for
+specific lines. The name of those subdirectories must take the form of:
+``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be
+used by the module to assign the config to the specific line at given offset.
+
+Once the configuration is complete, the ``'live'`` attribute must be set to 1 in
+order to instantiate the chip. It can be set back to 0 to destroy the simulated
+chip. The module will synchronously wait for the new simulated device to be
+successfully probed and if this doesn't happen, writing to ``'live'`` will
+result in an error.
+
+Simulated GPIO chips can also be defined in device-tree. The compatible string
+must be: ``"gpio-simulator"``. Supported properties are:
+
+ ``"gpio-sim,label"`` - chip label
+
+Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or
+``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for
+details.
+
+An example device-tree code defining a GPIO simulator:
+
+.. code-block :: none
+
+ gpio-sim {
+ compatible = "gpio-simulator";
+
+ bank0 {
+ gpio-controller;
+ #gpio-cells = <2>;
+ ngpios = <16>;
+ gpio-sim,label = "dt-bank0";
+ gpio-line-names = "", "sim-foo", "", "sim-bar";
+ };
+
+ bank1 {
+ gpio-controller;
+ #gpio-cells = <2>;
+ ngpios = <8>;
+ gpio-sim,label = "dt-bank1";
+
+ line3 {
+ gpio-hog;
+ gpios = <3 0>;
+ output-high;
+ line-name = "sim-hog-from-dt";
+ };
+ };
+ };
+
+Manipulating simulated lines
+----------------------------
+
+Each simulated GPIO chip creates a separate sysfs group under its device
+directory for each exposed line
+(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group
+is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each
+group there are two attributes:
+
+ ``pull`` - allows to read and set the current simulated pull setting for
+ every line, when writing the value must be one of: ``'pull-up'``,
+ ``'pull-down'``
+
+ ``value`` - allows to read the current value of the line which may be
+ different from the pull if the line is being driven from
+ user-space
diff --git a/Documentation/admin-guide/gpio/gpio-virtuser.rst b/Documentation/admin-guide/gpio/gpio-virtuser.rst
new file mode 100644
index 000000000000..7e7c0df51640
--- /dev/null
+++ b/Documentation/admin-guide/gpio/gpio-virtuser.rst
@@ -0,0 +1,177 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Virtual GPIO Consumer
+=====================
+
+The virtual GPIO Consumer module allows users to instantiate virtual devices
+that request GPIOs and then control their behavior over debugfs. Virtual
+consumer devices can be instantiated from device-tree or over configfs.
+
+A virtual consumer uses the driver-facing GPIO APIs and allows to cover it with
+automated tests driven by user-space. The GPIOs are requested using
+``gpiod_get_array()`` and so we support multiple GPIOs per connector ID.
+
+Creating GPIO consumers
+-----------------------
+
+The gpio-consumer module registers a configfs subsystem called
+``'gpio-virtuser'``. For details of the configfs filesystem, please refer to
+the configfs documentation.
+
+The user can create a hierarchy of configfs groups and items as well as modify
+values of exposed attributes. Once the consumer is instantiated, this hierarchy
+will be translated to appropriate device properties. The general structure is:
+
+**Group:** ``/config/gpio-virtuser``
+
+This is the top directory of the gpio-consumer configfs tree.
+
+**Group:** ``/config/gpio-consumer/example-name``
+
+**Attribute:** ``/config/gpio-consumer/example-name/live``
+
+**Attribute:** ``/config/gpio-consumer/example-name/dev_name``
+
+This is a directory representing a GPIO consumer device.
+
+The read-only ``dev_name`` attribute exposes the name of the device as it will
+appear in the system on the platform bus. This is useful for locating the
+associated debugfs directory under
+``/sys/kernel/debug/gpio-virtuser/$dev_name``.
+
+The ``'live'`` attribute allows to trigger the actual creation of the device
+once it's fully configured. The accepted values are: ``'1'`` to enable the
+virtual device and ``'0'`` to disable and tear it down.
+
+Creating GPIO lookup tables
+---------------------------
+
+Users can create a number of configfs groups under the device group:
+
+**Group:** ``/config/gpio-consumer/example-name/con_id``
+
+The ``'con_id'`` directory represents a single GPIO lookup and its value maps
+to the ``'con_id'`` argument of the ``gpiod_get()`` function. For example:
+``con_id`` == ``'reset'`` maps to the ``reset-gpios`` device property.
+
+Users can assign a number of GPIOs to each lookup. Each GPIO is a sub-directory
+with a user-defined name under the ``'con_id'`` group.
+
+**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/key``
+
+**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/offset``
+
+**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/drive``
+
+**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/pull``
+
+**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/active_low``
+
+**Attribute:** ``/config/gpio-consumer/example-name/con_id/0/transitory``
+
+This is a group describing a single GPIO in the ``con_id-gpios`` property.
+
+For virtual consumers created using configfs we use machine lookup tables so
+this group can be considered as a mapping between the filesystem and the fields
+of a single entry in ``'struct gpiod_lookup'``.
+
+The ``'key'`` attribute represents either the name of the chip this GPIO
+belongs to or the GPIO line name. This depends on the value of the ``'offset'``
+attribute: if its value is >= 0, then ``'key'`` represents the label of the
+chip to lookup while ``'offset'`` represents the offset of the line in that
+chip. If ``'offset'`` is < 0, then ``'key'`` represents the name of the line.
+
+The remaining attributes map to the ``'flags'`` field of the GPIO lookup
+struct. The first two take string values as arguments:
+
+**``'drive'``:** ``'push-pull'``, ``'open-drain'``, ``'open-source'``
+**``'pull'``:** ``'pull-up'``, ``'pull-down'``, ``'pull-disabled'``, ``'as-is'``
+
+``'active_low'`` and ``'transitory'`` are boolean attributes.
+
+Activating GPIO consumers
+-------------------------
+
+Once the configuration is complete, the ``'live'`` attribute must be set to 1 in
+order to instantiate the consumer. It can be set back to 0 to destroy the
+virtual device. The module will synchronously wait for the new simulated device
+to be successfully probed and if this doesn't happen, writing to ``'live'`` will
+result in an error.
+
+Device-tree
+-----------
+
+Virtual GPIO consumers can also be defined in device-tree. The compatible string
+must be: ``"gpio-virtuser"`` with at least one property following the
+standardized GPIO pattern.
+
+An example device-tree code defining a virtual GPIO consumer:
+
+.. code-block :: none
+
+ gpio-virt-consumer {
+ compatible = "gpio-virtuser";
+
+ foo-gpios = <&gpio0 5 GPIO_ACTIVE_LOW>, <&gpio1 2 0>;
+ bar-gpios = <&gpio0 6 0>;
+ };
+
+Controlling virtual GPIO consumers
+----------------------------------
+
+Once active, the device will export debugfs attributes for controlling GPIO
+arrays as well as each requested GPIO line separately. Let's consider the
+following device property: ``foo-gpios = <&gpio0 0 0>, <&gpio0 4 0>;``.
+
+The following debugfs attribute groups will be created:
+
+**Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/``
+
+This is the group that will contain the attributes for the entire GPIO array.
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values``
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo/values_atomic``
+
+Both attributes allow to read and set arrays of GPIO values. User must pass
+exactly the number of values that the array contains in the form of a string
+containing zeroes and ones representing inactive and active GPIO states
+respectively. In this example: ``echo 11 > values``.
+
+The ``values_atomic`` attribute works the same as ``values`` but the kernel
+will execute the GPIO driver callbacks in interrupt context.
+
+**Group:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/``
+
+This is a group that represents a single GPIO with ``$index`` being its offset
+in the array.
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/consumer``
+
+Allows to set and read the consumer label of the GPIO line.
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/debounce``
+
+Allows to set and read the debounce period of the GPIO line.
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction``
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/direction_atomic``
+
+These two attributes allow to set the direction of the GPIO line. They accept
+"input" and "output" as values. The atomic variant executes the driver callback
+in interrupt context.
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/interrupts``
+
+If the line is requested in input mode, writing ``1`` to this attribute will
+make the module listen for edge interrupts on the GPIO. Writing ``0`` disables
+the monitoring. Reading this attribute returns the current number of registered
+interrupts (both edges).
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value``
+
+**Attribute:** ``/sys/kernel/debug/gpio-virtuser/$dev_name/gpiod:foo:$index/value_atomic``
+
+Both attributes allow to read and set values of individual requested GPIO lines.
+They accept the following values: ``1`` and ``0``.
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
new file mode 100644
index 000000000000..712f379731cb
--- /dev/null
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+GPIO
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ Character Device Userspace API <../../userspace-api/gpio/chardev>
+ gpio-aggregator
+ gpio-sim
+ gpio-virtuser
+ Obsolete APIs <obsolete>
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/admin-guide/gpio/obsolete.rst
new file mode 100644
index 000000000000..5adbff02d61f
--- /dev/null
+++ b/Documentation/admin-guide/gpio/obsolete.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+Obsolete GPIO APIs
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1>
+ Sysfs Interface <../../userspace-api/gpio/sysfs>
+ Mockup Testing Module <gpio-mockup>
+
diff --git a/Documentation/admin-guide/hw-vuln/attack_vector_controls.rst b/Documentation/admin-guide/hw-vuln/attack_vector_controls.rst
new file mode 100644
index 000000000000..d0bdbd81dcf9
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/attack_vector_controls.rst
@@ -0,0 +1,236 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Attack Vector Controls
+======================
+
+Attack vector controls provide a simple method to configure only the mitigations
+for CPU vulnerabilities which are relevant given the intended use of a system.
+Administrators are encouraged to consider which attack vectors are relevant and
+disable all others in order to recoup system performance.
+
+When new relevant CPU vulnerabilities are found, they will be added to these
+attack vector controls so administrators will likely not need to reconfigure
+their command line parameters as mitigations will continue to be correctly
+applied based on the chosen attack vector controls.
+
+Attack Vectors
+--------------
+
+There are 5 sets of attack-vector mitigations currently supported by the kernel:
+
+#. :ref:`user_kernel`
+#. :ref:`user_user`
+#. :ref:`guest_host`
+#. :ref:`guest_guest`
+#. :ref:`smt`
+
+To control the enabled attack vectors, see :ref:`cmdline`.
+
+.. _user_kernel:
+
+User-to-Kernel
+^^^^^^^^^^^^^^
+
+The user-to-kernel attack vector involves a malicious userspace program
+attempting to leak kernel data into userspace by exploiting a CPU vulnerability.
+The kernel data involved might be limited to certain kernel memory, or include
+all memory in the system, depending on the vulnerability exploited.
+
+If no untrusted userspace applications are being run, such as with single-user
+systems, consider disabling user-to-kernel mitigations.
+
+Note that the CPU vulnerabilities mitigated by Linux have generally not been
+shown to be exploitable from browser-based sandboxes. User-to-kernel
+mitigations are therefore mostly relevant if unknown userspace applications may
+be run by untrusted users.
+
+*user-to-kernel mitigations are enabled by default*
+
+.. _user_user:
+
+User-to-User
+^^^^^^^^^^^^
+
+The user-to-user attack vector involves a malicious userspace program attempting
+to influence the behavior of another unsuspecting userspace program in order to
+exfiltrate data. The vulnerability of a userspace program is based on the
+program itself and the interfaces it provides.
+
+If no untrusted userspace applications are being run, consider disabling
+user-to-user mitigations.
+
+Note that because the Linux kernel contains a mapping of all physical memory,
+preventing a malicious userspace program from leaking data from another
+userspace program requires mitigating user-to-kernel attacks as well for
+complete protection.
+
+*user-to-user mitigations are enabled by default*
+
+.. _guest_host:
+
+Guest-to-Host
+^^^^^^^^^^^^^
+
+The guest-to-host attack vector involves a malicious VM attempting to leak
+hypervisor data into the VM. The data involved may be limited, or may
+potentially include all memory in the system, depending on the vulnerability
+exploited.
+
+If no untrusted VMs are being run, consider disabling guest-to-host mitigations.
+
+*guest-to-host mitigations are enabled by default if KVM support is present*
+
+.. _guest_guest:
+
+Guest-to-Guest
+^^^^^^^^^^^^^^
+
+The guest-to-guest attack vector involves a malicious VM attempting to influence
+the behavior of another unsuspecting VM in order to exfiltrate data. The
+vulnerability of a VM is based on the code inside the VM itself and the
+interfaces it provides.
+
+If no untrusted VMs, or only a single VM is being run, consider disabling
+guest-to-guest mitigations.
+
+Similar to the user-to-user attack vector, preventing a malicious VM from
+leaking data from another VM requires mitigating guest-to-host attacks as well
+due to the Linux kernel phys map.
+
+*guest-to-guest mitigations are enabled by default if KVM support is present*
+
+.. _smt:
+
+Cross-Thread
+^^^^^^^^^^^^
+
+The cross-thread attack vector involves a malicious userspace program or
+malicious VM either observing or attempting to influence the behavior of code
+running on the SMT sibling thread in order to exfiltrate data.
+
+Many cross-thread attacks can only be mitigated if SMT is disabled, which will
+result in reduced CPU core count and reduced performance.
+
+If cross-thread mitigations are fully enabled ('auto,nosmt'), all mitigations
+for cross-thread attacks will be enabled. SMT may be disabled depending on
+which vulnerabilities are present in the CPU.
+
+If cross-thread mitigations are partially enabled ('auto'), mitigations for
+cross-thread attacks will be enabled but SMT will not be disabled.
+
+If cross-thread mitigations are disabled, no mitigations for cross-thread
+attacks will be enabled.
+
+Cross-thread mitigation may not be required if core-scheduling or similar
+techniques are used to prevent untrusted workloads from running on SMT siblings.
+
+*cross-thread mitigations default to partially enabled*
+
+.. _cmdline:
+
+Command Line Controls
+---------------------
+
+Attack vectors are controlled through the mitigations= command line option. The
+value provided begins with a global option and then may optionally include one
+or more options to disable various attack vectors.
+
+Format:
+ | ``mitigations=[global]``
+ | ``mitigations=[global],[attack vectors]``
+
+Global options:
+
+============ =============================================================
+Option Description
+============ =============================================================
+'off' All attack vectors disabled.
+'auto' All attack vectors enabled, partial cross-thread mitigations.
+'auto,nosmt' All attack vectors enabled, full cross-thread mitigations.
+============ =============================================================
+
+Attack vector options:
+
+================= =======================================
+Option Description
+================= =======================================
+'no_user_kernel' Disables user-to-kernel mitigations.
+'no_user_user' Disables user-to-user mitigations.
+'no_guest_host' Disables guest-to-host mitigations.
+'no_guest_guest' Disables guest-to-guest mitigations
+'no_cross_thread' Disables all cross-thread mitigations.
+================= =======================================
+
+Multiple attack vector options may be specified in a comma-separated list. If
+the global option is not specified, it defaults to 'auto'. The global option
+'off' is equivalent to disabling all attack vectors.
+
+Examples:
+ | ``mitigations=auto,no_user_kernel``
+
+ Enable all attack vectors except user-to-kernel. Partial cross-thread
+ mitigations.
+
+ | ``mitigations=auto,nosmt,no_guest_host,no_guest_guest``
+
+ Enable all attack vectors and cross-thread mitigations except for
+ guest-to-host and guest-to-guest mitigations.
+
+ | ``mitigations=,no_cross_thread``
+
+ Enable all attack vectors but not cross-thread mitigations.
+
+Interactions with command-line options
+--------------------------------------
+
+Vulnerability-specific controls (e.g. "retbleed=off") take precedence over all
+attack vector controls. Mitigations for individual vulnerabilities may be
+turned on or off via their command-line options regardless of the attack vector
+controls.
+
+Summary of attack-vector mitigations
+------------------------------------
+
+When a vulnerability is mitigated due to an attack-vector control, the default
+mitigation option for that particular vulnerability is used. To use a different
+mitigation, please use the vulnerability-specific command line option.
+
+The table below summarizes which vulnerabilities are mitigated when different
+attack vectors are enabled and assuming the CPU is vulnerable.
+
+=============== ============== ============ ============= ============== ============ ========
+Vulnerability User-to-Kernel User-to-User Guest-to-Host Guest-to-Guest Cross-Thread Notes
+=============== ============== ============ ============= ============== ============ ========
+BHI X X
+ITS X X
+GDS X X X X * (Note 1)
+L1TF X X * (Note 2)
+MDS X X X X * (Note 2)
+MMIO X X X X * (Note 2)
+Meltdown X
+Retbleed X X * (Note 3)
+RFDS X X X X
+Spectre_v1 X
+Spectre_v2 X X
+Spectre_v2_user X X * (Note 1)
+SRBDS X X X X
+SRSO X X X X
+SSB X
+TAA X X X X * (Note 2)
+TSA X X X X
+VMSCAPE X
+=============== ============== ============ ============= ============== ============ ========
+
+Notes:
+ 1 -- Can be mitigated without disabling SMT.
+
+ 2 -- Disables SMT if cross-thread mitigations are fully enabled and the CPU
+ is vulnerable
+
+ 3 -- Disables SMT if cross-thread mitigations are fully enabled, the CPU is
+ vulnerable, and STIBP is not supported
+
+When an attack-vector is disabled, all mitigations for the vulnerabilities
+listed in the above table are disabled, unless mitigation is required for a
+different enabled attack-vector or a mitigation is explicitly selected via a
+vulnerability-specific command line option.
diff --git a/Documentation/admin-guide/hw-vuln/core-scheduling.rst b/Documentation/admin-guide/hw-vuln/core-scheduling.rst
new file mode 100644
index 000000000000..a92e10ec402e
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/core-scheduling.rst
@@ -0,0 +1,226 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Core Scheduling
+===============
+Core scheduling support allows userspace to define groups of tasks that can
+share a core. These groups can be specified either for security usecases (one
+group of tasks don't trust another), or for performance usecases (some
+workloads may benefit from running on the same core as they don't need the same
+hardware resources of the shared core, or may prefer different cores if they
+do share hardware resource needs). This document only describes the security
+usecase.
+
+Security usecase
+----------------
+A cross-HT attack involves the attacker and victim running on different Hyper
+Threads of the same core. MDS and L1TF are examples of such attacks. The only
+full mitigation of cross-HT attacks is to disable Hyper Threading (HT). Core
+scheduling is a scheduler feature that can mitigate some (not all) cross-HT
+attacks. It allows HT to be turned on safely by ensuring that only tasks in a
+user-designated trusted group can share a core. This increase in core sharing
+can also improve performance, however it is not guaranteed that performance
+will always improve, though that is seen to be the case with a number of real
+world workloads. In theory, core scheduling aims to perform at least as good as
+when Hyper Threading is disabled. In practice, this is mostly the case though
+not always: as synchronizing scheduling decisions across 2 or more CPUs in a
+core involves additional overhead - especially when the system is lightly
+loaded. When ``total_threads <= N_CPUS/2``, the extra overhead may cause core
+scheduling to perform more poorly compared to SMT-disabled, where N_CPUS is the
+total number of CPUs. Please measure the performance of your workloads always.
+
+Usage
+-----
+Core scheduling support is enabled via the ``CONFIG_SCHED_CORE`` config option.
+Using this feature, userspace defines groups of tasks that can be co-scheduled
+on the same core. The core scheduler uses this information to make sure that
+tasks that are not in the same group never run simultaneously on a core, while
+doing its best to satisfy the system's scheduling requirements.
+
+Core scheduling can be enabled via the ``PR_SCHED_CORE`` prctl interface.
+This interface provides support for the creation of core scheduling groups, as
+well as admission and removal of tasks from created groups::
+
+ #include <sys/prctl.h>
+
+ int prctl(int option, unsigned long arg2, unsigned long arg3,
+ unsigned long arg4, unsigned long arg5);
+
+option:
+ ``PR_SCHED_CORE``
+
+arg2:
+ Command for operation, must be one off:
+
+ - ``PR_SCHED_CORE_GET`` -- get core_sched cookie of ``pid``.
+ - ``PR_SCHED_CORE_CREATE`` -- create a new unique cookie for ``pid``.
+ - ``PR_SCHED_CORE_SHARE_TO`` -- push core_sched cookie to ``pid``.
+ - ``PR_SCHED_CORE_SHARE_FROM`` -- pull core_sched cookie from ``pid``.
+
+arg3:
+ ``pid`` of the task for which the operation applies.
+
+arg4:
+ ``pid_type`` for which the operation applies. It is one of
+ ``PR_SCHED_CORE_SCOPE_``-prefixed macro constants. For example, if arg4
+ is ``PR_SCHED_CORE_SCOPE_THREAD_GROUP``, then the operation of this command
+ will be performed for all tasks in the task group of ``pid``.
+
+arg5:
+ userspace pointer to an unsigned long long for storing the cookie returned
+ by ``PR_SCHED_CORE_GET`` command. Should be 0 for all other commands.
+
+In order for a process to push a cookie to, or pull a cookie from a process, it
+is required to have the ptrace access mode: `PTRACE_MODE_READ_REALCREDS` to the
+process.
+
+Building hierarchies of tasks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The simplest way to build hierarchies of threads/processes which share a
+cookie and thus a core is to rely on the fact that the core-sched cookie is
+inherited across forks/clones and execs, thus setting a cookie for the
+'initial' script/executable/daemon will place every spawned child in the
+same core-sched group.
+
+Cookie Transferral
+~~~~~~~~~~~~~~~~~~
+Transferring a cookie between the current and other tasks is possible using
+PR_SCHED_CORE_SHARE_FROM and PR_SCHED_CORE_SHARE_TO to inherit a cookie from a
+specified task or a share a cookie with a task. In combination this allows a
+simple helper program to pull a cookie from a task in an existing core
+scheduling group and share it with already running tasks.
+
+Design/Implementation
+---------------------
+Each task that is tagged is assigned a cookie internally in the kernel. As
+mentioned in `Usage`_, tasks with the same cookie value are assumed to trust
+each other and share a core.
+
+The basic idea is that, every schedule event tries to select tasks for all the
+siblings of a core such that all the selected tasks running on a core are
+trusted (same cookie) at any point in time. Kernel threads are assumed trusted.
+The idle task is considered special, as it trusts everything and everything
+trusts it.
+
+During a schedule() event on any sibling of a core, the highest priority task on
+the sibling's core is picked and assigned to the sibling calling schedule(), if
+the sibling has the task enqueued. For rest of the siblings in the core,
+highest priority task with the same cookie is selected if there is one runnable
+in their individual run queues. If a task with same cookie is not available,
+the idle task is selected. Idle task is globally trusted.
+
+Once a task has been selected for all the siblings in the core, an IPI is sent to
+siblings for whom a new task was selected. Siblings on receiving the IPI will
+switch to the new task immediately. If an idle task is selected for a sibling,
+then the sibling is considered to be in a `forced idle` state. I.e., it may
+have tasks on its on runqueue to run, however it will still have to run idle.
+More on this in the next section.
+
+Forced-idling of hyperthreads
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The scheduler tries its best to find tasks that trust each other such that all
+tasks selected to be scheduled are of the highest priority in a core. However,
+it is possible that some runqueues had tasks that were incompatible with the
+highest priority ones in the core. Favoring security over fairness, one or more
+siblings could be forced to select a lower priority task if the highest
+priority task is not trusted with respect to the core wide highest priority
+task. If a sibling does not have a trusted task to run, it will be forced idle
+by the scheduler (idle thread is scheduled to run).
+
+When the highest priority task is selected to run, a reschedule-IPI is sent to
+the sibling to force it into idle. This results in 4 cases which need to be
+considered depending on whether a VM or a regular usermode process was running
+on either HT::
+
+ HT1 (attack) HT2 (victim)
+ A idle -> user space user space -> idle
+ B idle -> user space guest -> idle
+ C idle -> guest user space -> idle
+ D idle -> guest guest -> idle
+
+Note that for better performance, we do not wait for the destination CPU
+(victim) to enter idle mode. This is because the sending of the IPI would bring
+the destination CPU immediately into kernel mode from user space, or VMEXIT
+in the case of guests. At best, this would only leak some scheduler metadata
+which may not be worth protecting. It is also possible that the IPI is received
+too late on some architectures, but this has not been observed in the case of
+x86.
+
+Trust model
+~~~~~~~~~~~
+Core scheduling maintains trust relationships amongst groups of tasks by
+assigning them a tag that is the same cookie value.
+When a system with core scheduling boots, all tasks are considered to trust
+each other. This is because the core scheduler does not have information about
+trust relationships until userspace uses the above mentioned interfaces, to
+communicate them. In other words, all tasks have a default cookie value of 0.
+and are considered system-wide trusted. The forced-idling of siblings running
+cookie-0 tasks is also avoided.
+
+Once userspace uses the above mentioned interfaces to group sets of tasks, tasks
+within such groups are considered to trust each other, but do not trust those
+outside. Tasks outside the group also don't trust tasks within.
+
+Limitations of core-scheduling
+------------------------------
+Core scheduling tries to guarantee that only trusted tasks run concurrently on a
+core. But there could be small window of time during which untrusted tasks run
+concurrently or kernel could be running concurrently with a task not trusted by
+kernel.
+
+IPI processing delays
+~~~~~~~~~~~~~~~~~~~~~
+Core scheduling selects only trusted tasks to run together. IPI is used to notify
+the siblings to switch to the new task. But there could be hardware delays in
+receiving of the IPI on some arch (on x86, this has not been observed). This may
+cause an attacker task to start running on a CPU before its siblings receive the
+IPI. Even though cache is flushed on entry to user mode, victim tasks on siblings
+may populate data in the cache and micro architectural buffers after the attacker
+starts to run and this is a possibility for data leak.
+
+Open cross-HT issues that core scheduling does not solve
+--------------------------------------------------------
+1. For MDS
+~~~~~~~~~~
+Core scheduling cannot protect against MDS attacks between the siblings
+running in user mode and the others running in kernel mode. Even though all
+siblings run tasks which trust each other, when the kernel is executing
+code on behalf of a task, it cannot trust the code running in the
+sibling. Such attacks are possible for any combination of sibling CPU modes
+(host or guest mode).
+
+2. For L1TF
+~~~~~~~~~~~
+Core scheduling cannot protect against an L1TF guest attacker exploiting a
+guest or host victim. This is because the guest attacker can craft invalid
+PTEs which are not inverted due to a vulnerable guest kernel. The only
+solution is to disable EPT (Extended Page Tables).
+
+For both MDS and L1TF, if the guest vCPU is configured to not trust each
+other (by tagging separately), then the guest to guest attacks would go away.
+Or it could be a system admin policy which considers guest to guest attacks as
+a guest problem.
+
+Another approach to resolve these would be to make every untrusted task on the
+system to not trust every other untrusted task. While this could reduce
+parallelism of the untrusted tasks, it would still solve the above issues while
+allowing system processes (trusted tasks) to share a core.
+
+3. Protecting the kernel (IRQ, syscall, VMEXIT)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unfortunately, core scheduling does not protect kernel contexts running on
+sibling hyperthreads from one another. Prototypes of mitigations have been posted
+to LKML to solve this, but it is debatable whether such windows are practically
+exploitable, and whether the performance overhead of the prototypes are worth
+it (not to mention, the added code complexity).
+
+Other Use cases
+---------------
+The main use case for Core scheduling is mitigating the cross-HT vulnerabilities
+with SMT enabled. There are other use cases where this feature could be used:
+
+- Isolating tasks that needs a whole core: Examples include realtime tasks, tasks
+ that uses SIMD instructions etc.
+- Gang scheduling: Requirements for a group of tasks that needs to be scheduled
+ together could also be realized using core scheduling. One example is vCPUs of
+ a VM.
diff --git a/Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst b/Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst
new file mode 100644
index 000000000000..875616d675fe
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst
@@ -0,0 +1,91 @@
+
+.. SPDX-License-Identifier: GPL-2.0
+
+Cross-Thread Return Address Predictions
+=======================================
+
+Certain AMD and Hygon processors are subject to a cross-thread return address
+predictions vulnerability. When running in SMT mode and one sibling thread
+transitions out of C0 state, the other sibling thread could use return target
+predictions from the sibling thread that transitioned out of C0.
+
+The Spectre v2 mitigations protect the Linux kernel, as it fills the return
+address prediction entries with safe targets when context switching to the idle
+thread. However, KVM does allow a VMM to prevent exiting guest mode when
+transitioning out of C0. This could result in a guest-controlled return target
+being consumed by the sibling thread.
+
+Affected processors
+-------------------
+
+The following CPUs are vulnerable:
+
+ - AMD Family 17h processors
+ - Hygon Family 18h processors
+
+Related CVEs
+------------
+
+The following CVE entry is related to this issue:
+
+ ============== =======================================
+ CVE-2022-27672 Cross-Thread Return Address Predictions
+ ============== =======================================
+
+Problem
+-------
+
+Affected SMT-capable processors support 1T and 2T modes of execution when SMT
+is enabled. In 2T mode, both threads in a core are executing code. For the
+processor core to enter 1T mode, it is required that one of the threads
+requests to transition out of the C0 state. This can be communicated with the
+HLT instruction or with an MWAIT instruction that requests non-C0.
+When the thread re-enters the C0 state, the processor transitions back
+to 2T mode, assuming the other thread is also still in C0 state.
+
+In affected processors, the return address predictor (RAP) is partitioned
+depending on the SMT mode. For instance, in 2T mode each thread uses a private
+16-entry RAP, but in 1T mode, the active thread uses a 32-entry RAP. Upon
+transition between 1T/2T mode, the RAP contents are not modified but the RAP
+pointers (which control the next return target to use for predictions) may
+change. This behavior may result in return targets from one SMT thread being
+used by RET predictions in the sibling thread following a 1T/2T switch. In
+particular, a RET instruction executed immediately after a transition to 1T may
+use a return target from the thread that just became idle. In theory, this
+could lead to information disclosure if the return targets used do not come
+from trustworthy code.
+
+Attack scenarios
+----------------
+
+An attack can be mounted on affected processors by performing a series of CALL
+instructions with targeted return locations and then transitioning out of C0
+state.
+
+Mitigation mechanism
+--------------------
+
+Before entering idle state, the kernel context switches to the idle thread. The
+context switch fills the RAP entries (referred to as the RSB in Linux) with safe
+targets by performing a sequence of CALL instructions.
+
+Prevent a guest VM from directly putting the processor into an idle state by
+intercepting HLT and MWAIT instructions.
+
+Both mitigations are required to fully address this issue.
+
+Mitigation control on the kernel command line
+---------------------------------------------
+
+Use existing Spectre v2 mitigations that will fill the RSB on context switch.
+
+Mitigation control for KVM - module parameter
+---------------------------------------------
+
+By default, the KVM hypervisor mitigates this issue by intercepting guest
+attempts to transition out of C0. A VMM can use the KVM_CAP_X86_DISABLE_EXITS
+capability to override those interceptions, but since this is not common, the
+mitigation that covers this path is not enabled by default.
+
+The mitigation for the KVM_CAP_X86_DISABLE_EXITS capability can be turned on
+using the boolean module parameter mitigate_smt_rsb, e.g. ``kvm.mitigate_smt_rsb=1``.
diff --git a/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
new file mode 100644
index 000000000000..264bfa937f7d
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
@@ -0,0 +1,109 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+GDS - Gather Data Sampling
+==========================
+
+Gather Data Sampling is a hardware vulnerability which allows unprivileged
+speculative access to data which was previously stored in vector registers.
+
+Problem
+-------
+When a gather instruction performs loads from memory, different data elements
+are merged into the destination vector register. However, when a gather
+instruction that is transiently executed encounters a fault, stale data from
+architectural or internal vector registers may get transiently forwarded to the
+destination vector register instead. This will allow a malicious attacker to
+infer stale data using typical side channel techniques like cache timing
+attacks. GDS is a purely sampling-based attack.
+
+The attacker uses gather instructions to infer the stale vector register data.
+The victim does not need to do anything special other than use the vector
+registers. The victim does not need to use gather instructions to be
+vulnerable.
+
+Because the buffers are shared between Hyper-Threads cross Hyper-Thread attacks
+are possible.
+
+Attack scenarios
+----------------
+Without mitigation, GDS can infer stale data across virtually all
+permission boundaries:
+
+ Non-enclaves can infer SGX enclave data
+ Userspace can infer kernel data
+ Guests can infer data from hosts
+ Guest can infer guest from other guests
+ Users can infer data from other users
+
+Because of this, it is important to ensure that the mitigation stays enabled in
+lower-privilege contexts like guests and when running outside SGX enclaves.
+
+The hardware enforces the mitigation for SGX. Likewise, VMMs should ensure
+that guests are not allowed to disable the GDS mitigation. If a host erred and
+allowed this, a guest could theoretically disable GDS mitigation, mount an
+attack, and re-enable it.
+
+Mitigation mechanism
+--------------------
+This issue is mitigated in microcode. The microcode defines the following new
+bits:
+
+ ================================ === ============================
+ IA32_ARCH_CAPABILITIES[GDS_CTRL] R/O Enumerates GDS vulnerability
+ and mitigation support.
+ IA32_ARCH_CAPABILITIES[GDS_NO] R/O Processor is not vulnerable.
+ IA32_MCU_OPT_CTRL[GDS_MITG_DIS] R/W Disables the mitigation
+ 0 by default.
+ IA32_MCU_OPT_CTRL[GDS_MITG_LOCK] R/W Locks GDS_MITG_DIS=0. Writes
+ to GDS_MITG_DIS are ignored
+ Can't be cleared once set.
+ ================================ === ============================
+
+GDS can also be mitigated on systems that don't have updated microcode by
+disabling AVX. This can be done by setting gather_data_sampling="force" or
+"clearcpuid=avx" on the kernel command-line.
+
+If used, these options will disable AVX use by turning off XSAVE YMM support.
+However, the processor will still enumerate AVX support. Userspace that
+does not follow proper AVX enumeration to check both AVX *and* XSAVE YMM
+support will break.
+
+Mitigation control on the kernel command line
+---------------------------------------------
+The mitigation can be disabled by setting "gather_data_sampling=off" or
+"mitigations=off" on the kernel command line. Not specifying either will default
+to the mitigation being enabled. Specifying "gather_data_sampling=force" will
+use the microcode mitigation when available or disable AVX on affected systems
+where the microcode hasn't been updated to include the mitigation.
+
+GDS System Information
+------------------------
+The kernel provides vulnerability status information through sysfs. For
+GDS this can be accessed by the following sysfs file:
+
+/sys/devices/system/cpu/vulnerabilities/gather_data_sampling
+
+The possible values contained in this file are:
+
+ ============================== =============================================
+ Not affected Processor not vulnerable.
+ Vulnerable Processor vulnerable and mitigation disabled.
+ Vulnerable: No microcode Processor vulnerable and microcode is missing
+ mitigation.
+ Mitigation: AVX disabled,
+ no microcode Processor is vulnerable and microcode is missing
+ mitigation. AVX disabled as mitigation.
+ Mitigation: Microcode Processor is vulnerable and mitigation is in
+ effect.
+ Mitigation: Microcode (locked) Processor is vulnerable and mitigation is in
+ effect and cannot be disabled.
+ Unknown: Dependent on
+ hypervisor status Running on a virtual guest processor that is
+ affected but with no way to know if host
+ processor is mitigated or vulnerable.
+ ============================== =============================================
+
+GDS Default mitigation
+----------------------
+The updated microcode will enable the mitigation by default. The kernel's
+default action is to leave the mitigation enabled.
diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst
new file mode 100644
index 000000000000..55d747511f83
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/index.rst
@@ -0,0 +1,29 @@
+========================
+Hardware vulnerabilities
+========================
+
+This section describes CPU vulnerabilities and provides an overview of the
+possible mitigations along with guidance for selecting mitigations if they
+are configurable at compile, boot or run time.
+
+.. toctree::
+ :maxdepth: 1
+
+ attack_vector_controls
+ spectre
+ l1tf
+ mds
+ tsx_async_abort
+ multihit
+ special-register-buffer-data-sampling
+ core-scheduling
+ l1d_flush
+ processor_mmio_stale_data
+ cross-thread-rsb
+ srso
+ gather_data_sampling
+ reg-file-data-sampling
+ rsb
+ old_microcode
+ indirect-target-selection
+ vmscape
diff --git a/Documentation/admin-guide/hw-vuln/indirect-target-selection.rst b/Documentation/admin-guide/hw-vuln/indirect-target-selection.rst
new file mode 100644
index 000000000000..d9ca64108d23
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/indirect-target-selection.rst
@@ -0,0 +1,168 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Indirect Target Selection (ITS)
+===============================
+
+ITS is a vulnerability in some Intel CPUs that support Enhanced IBRS and were
+released before Alder Lake. ITS may allow an attacker to control the prediction
+of indirect branches and RETs located in the lower half of a cacheline.
+
+ITS is assigned CVE-2024-28956 with a CVSS score of 4.7 (Medium).
+
+Scope of Impact
+---------------
+- **eIBRS Guest/Host Isolation**: Indirect branches in KVM/kernel may still be
+ predicted with unintended target corresponding to a branch in the guest.
+
+- **Intra-Mode BTI**: In-kernel training such as through cBPF or other native
+ gadgets.
+
+- **Indirect Branch Prediction Barrier (IBPB)**: After an IBPB, indirect
+ branches may still be predicted with targets corresponding to direct branches
+ executed prior to the IBPB. This is fixed by the IPU 2025.1 microcode, which
+ should be available via distro updates. Alternatively microcode can be
+ obtained from Intel's github repository [#f1]_.
+
+Affected CPUs
+-------------
+Below is the list of ITS affected CPUs [#f2]_ [#f3]_:
+
+ ======================== ============ ==================== ===============
+ Common name Family_Model eIBRS Intra-mode BTI
+ Guest/Host Isolation
+ ======================== ============ ==================== ===============
+ SKYLAKE_X (step >= 6) 06_55H Affected Affected
+ ICELAKE_X 06_6AH Not affected Affected
+ ICELAKE_D 06_6CH Not affected Affected
+ ICELAKE_L 06_7EH Not affected Affected
+ TIGERLAKE_L 06_8CH Not affected Affected
+ TIGERLAKE 06_8DH Not affected Affected
+ KABYLAKE_L (step >= 12) 06_8EH Affected Affected
+ KABYLAKE (step >= 13) 06_9EH Affected Affected
+ COMETLAKE 06_A5H Affected Affected
+ COMETLAKE_L 06_A6H Affected Affected
+ ROCKETLAKE 06_A7H Not affected Affected
+ ======================== ============ ==================== ===============
+
+- All affected CPUs enumerate Enhanced IBRS feature.
+- IBPB isolation is affected on all ITS affected CPUs, and need a microcode
+ update for mitigation.
+- None of the affected CPUs enumerate BHI_CTRL which was introduced in Golden
+ Cove (Alder Lake and Sapphire Rapids). This can help guests to determine the
+ host's affected status.
+- Intel Atom CPUs are not affected by ITS.
+
+Mitigation
+----------
+As only the indirect branches and RETs that have their last byte of instruction
+in the lower half of the cacheline are vulnerable to ITS, the basic idea behind
+the mitigation is to not allow indirect branches in the lower half.
+
+This is achieved by relying on existing retpoline support in the kernel, and in
+compilers. ITS-vulnerable retpoline sites are runtime patched to point to newly
+added ITS-safe thunks. These safe thunks consists of indirect branch in the
+second half of the cacheline. Not all retpoline sites are patched to thunks, if
+a retpoline site is evaluated to be ITS-safe, it is replaced with an inline
+indirect branch.
+
+Dynamic thunks
+~~~~~~~~~~~~~~
+From a dynamically allocated pool of safe-thunks, each vulnerable site is
+replaced with a new thunk, such that they get a unique address. This could
+improve the branch prediction accuracy. Also, it is a defense-in-depth measure
+against aliasing.
+
+Note, for simplicity, indirect branches in eBPF programs are always replaced
+with a jump to a static thunk in __x86_indirect_its_thunk_array. If required,
+in future this can be changed to use dynamic thunks.
+
+All vulnerable RETs are replaced with a static thunk, they do not use dynamic
+thunks. This is because RETs get their prediction from RSB mostly that does not
+depend on source address. RETs that underflow RSB may benefit from dynamic
+thunks. But, RETs significantly outnumber indirect branches, and any benefit
+from a unique source address could be outweighed by the increased icache
+footprint and iTLB pressure.
+
+Retpoline
+~~~~~~~~~
+Retpoline sequence also mitigates ITS-unsafe indirect branches. For this
+reason, when retpoline is enabled, ITS mitigation only relocates the RETs to
+safe thunks. Unless user requested the RSB-stuffing mitigation.
+
+RSB Stuffing
+~~~~~~~~~~~~
+RSB-stuffing via Call Depth Tracking is a mitigation for Retbleed RSB-underflow
+attacks. And it also mitigates RETs that are vulnerable to ITS.
+
+Mitigation in guests
+^^^^^^^^^^^^^^^^^^^^
+All guests deploy ITS mitigation by default, irrespective of eIBRS enumeration
+and Family/Model of the guest. This is because eIBRS feature could be hidden
+from a guest. One exception to this is when a guest enumerates BHI_DIS_S, which
+indicates that the guest is running on an unaffected host.
+
+To prevent guests from unnecessarily deploying the mitigation on unaffected
+platforms, Intel has defined ITS_NO bit(62) in MSR IA32_ARCH_CAPABILITIES. When
+a guest sees this bit set, it should not enumerate the ITS bug. Note, this bit
+is not set by any hardware, but is **intended for VMMs to synthesize** it for
+guests as per the host's affected status.
+
+Mitigation options
+^^^^^^^^^^^^^^^^^^
+The ITS mitigation can be controlled using the "indirect_target_selection"
+kernel parameter. The available options are:
+
+ ======== ===================================================================
+ on (default) Deploy the "Aligned branch/return thunks" mitigation.
+ If spectre_v2 mitigation enables retpoline, aligned-thunks are only
+ deployed for the affected RET instructions. Retpoline mitigates
+ indirect branches.
+
+ off Disable ITS mitigation.
+
+ vmexit Equivalent to "=on" if the CPU is affected by guest/host isolation
+ part of ITS. Otherwise, mitigation is not deployed. This option is
+ useful when host userspace is not in the threat model, and only
+ attacks from guest to host are considered.
+
+ stuff Deploy RSB-fill mitigation when retpoline is also deployed.
+ Otherwise, deploy the default mitigation. When retpoline mitigation
+ is enabled, RSB-stuffing via Call-Depth-Tracking also mitigates
+ ITS.
+
+ force Force the ITS bug and deploy the default mitigation.
+ ======== ===================================================================
+
+Sysfs reporting
+---------------
+
+The sysfs file showing ITS mitigation status is:
+
+ /sys/devices/system/cpu/vulnerabilities/indirect_target_selection
+
+Note, microcode mitigation status is not reported in this file.
+
+The possible values in this file are:
+
+.. list-table::
+
+ * - Not affected
+ - The processor is not vulnerable.
+ * - Vulnerable
+ - System is vulnerable and no mitigation has been applied.
+ * - Vulnerable, KVM: Not affected
+ - System is vulnerable to intra-mode BTI, but not affected by eIBRS
+ guest/host isolation.
+ * - Mitigation: Aligned branch/return thunks
+ - The mitigation is enabled, affected indirect branches and RETs are
+ relocated to safe thunks.
+ * - Mitigation: Retpolines, Stuffing RSB
+ - The mitigation is enabled using retpoline and RSB stuffing.
+
+References
+----------
+.. [#f1] Microcode repository - https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files
+
+.. [#f2] Affected Processors list - https://www.intel.com/content/www/us/en/developer/topic-technology/software-security-guidance/processors-affected-consolidated-product-cpu-model.html
+
+.. [#f3] Affected Processors list (machine readable) - https://github.com/intel/Intel-affected-processor-list
diff --git a/Documentation/admin-guide/hw-vuln/l1d_flush.rst b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
new file mode 100644
index 000000000000..35dc25159b28
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
@@ -0,0 +1,69 @@
+L1D Flushing
+============
+
+With an increasing number of vulnerabilities being reported around data
+leaks from the Level 1 Data cache (L1D) the kernel provides an opt-in
+mechanism to flush the L1D cache on context switch.
+
+This mechanism can be used to address e.g. CVE-2020-0550. For applications
+the mechanism keeps them safe from vulnerabilities, related to leaks
+(snooping of) from the L1D cache.
+
+
+Related CVEs
+------------
+The following CVEs can be addressed by this
+mechanism
+
+ ============= ======================== ==================
+ CVE-2020-0550 Improper Data Forwarding OS related aspects
+ ============= ======================== ==================
+
+Usage Guidelines
+----------------
+
+Please see document: :ref:`Documentation/userspace-api/spec_ctrl.rst
+<set_spec_ctrl>` for details.
+
+**NOTE**: The feature is disabled by default, applications need to
+specifically opt into the feature to enable it.
+
+Mitigation
+----------
+
+When PR_SPEC_L1D_FLUSH is enabled for a task a flush of the L1D cache is
+performed when the task is scheduled out and the incoming task belongs to a
+different process and therefore to a different address space.
+
+If the underlying CPU supports L1D flushing in hardware, the hardware
+mechanism is used, software fallback for the mitigation, is not supported.
+
+Mitigation control on the kernel command line
+---------------------------------------------
+
+The kernel command line allows to control the L1D flush mitigations at boot
+time with the option "l1d_flush=". The valid arguments for this option are:
+
+ ============ =============================================================
+ on Enables the prctl interface, applications trying to use
+ the prctl() will fail with an error if l1d_flush is not
+ enabled
+ ============ =============================================================
+
+By default the mechanism is disabled.
+
+Limitations
+-----------
+
+The mechanism does not mitigate L1D data leaks between tasks belonging to
+different processes which are concurrently executing on sibling threads of
+a physical CPU core when SMT is enabled on the system.
+
+This can be addressed by controlled placement of processes on physical CPU
+cores or by disabling SMT. See the relevant chapter in the L1TF mitigation
+document: :ref:`Documentation/admin-guide/hw-vuln/l1tf.rst <smt_control>`.
+
+**NOTE** : The opt-in of a task for L1D flushing works only when the task's
+affinity is limited to cores running in non-SMT mode. If a task which
+requested L1D flushing is scheduled on a SMT-enabled core the kernel sends
+a SIGBUS to the task.
diff --git a/Documentation/admin-guide/hw-vuln/l1tf.rst b/Documentation/admin-guide/hw-vuln/l1tf.rst
new file mode 100644
index 000000000000..3eeeb488d955
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/l1tf.rst
@@ -0,0 +1,615 @@
+L1TF - L1 Terminal Fault
+========================
+
+L1 Terminal Fault is a hardware vulnerability which allows unprivileged
+speculative access to data which is available in the Level 1 Data Cache
+when the page table entry controlling the virtual address, which is used
+for the access, has the Present bit cleared or other reserved bits set.
+
+Affected processors
+-------------------
+
+This vulnerability affects a wide range of Intel processors. The
+vulnerability is not present on:
+
+ - Processors from AMD, Centaur and other non Intel vendors
+
+ - Older processor models, where the CPU family is < 6
+
+ - A range of Intel ATOM processors (Cedarview, Cloverview, Lincroft,
+ Penwell, Pineview, Silvermont, Airmont, Merrifield)
+
+ - The Intel XEON PHI family
+
+ - Intel processors which have the ARCH_CAP_RDCL_NO bit set in the
+ IA32_ARCH_CAPABILITIES MSR. If the bit is set the CPU is not affected
+ by the Meltdown vulnerability either. These CPUs should become
+ available by end of 2018.
+
+Whether a processor is affected or not can be read out from the L1TF
+vulnerability file in sysfs. See :ref:`l1tf_sys_info`.
+
+Related CVEs
+------------
+
+The following CVE entries are related to the L1TF vulnerability:
+
+ ============= ================= ==============================
+ CVE-2018-3615 L1 Terminal Fault SGX related aspects
+ CVE-2018-3620 L1 Terminal Fault OS, SMM related aspects
+ CVE-2018-3646 L1 Terminal Fault Virtualization related aspects
+ ============= ================= ==============================
+
+Problem
+-------
+
+If an instruction accesses a virtual address for which the relevant page
+table entry (PTE) has the Present bit cleared or other reserved bits set,
+then speculative execution ignores the invalid PTE and loads the referenced
+data if it is present in the Level 1 Data Cache, as if the page referenced
+by the address bits in the PTE was still present and accessible.
+
+While this is a purely speculative mechanism and the instruction will raise
+a page fault when it is retired eventually, the pure act of loading the
+data and making it available to other speculative instructions opens up the
+opportunity for side channel attacks to unprivileged malicious code,
+similar to the Meltdown attack.
+
+While Meltdown breaks the user space to kernel space protection, L1TF
+allows to attack any physical memory address in the system and the attack
+works across all protection domains. It allows an attack of SGX and also
+works from inside virtual machines because the speculation bypasses the
+extended page table (EPT) protection mechanism.
+
+
+Attack scenarios
+----------------
+
+1. Malicious user space
+^^^^^^^^^^^^^^^^^^^^^^^
+
+ Operating Systems store arbitrary information in the address bits of a
+ PTE which is marked non present. This allows a malicious user space
+ application to attack the physical memory to which these PTEs resolve.
+ In some cases user-space can maliciously influence the information
+ encoded in the address bits of the PTE, thus making attacks more
+ deterministic and more practical.
+
+ The Linux kernel contains a mitigation for this attack vector, PTE
+ inversion, which is permanently enabled and has no performance
+ impact. The kernel ensures that the address bits of PTEs, which are not
+ marked present, never point to cacheable physical memory space.
+
+ A system with an up to date kernel is protected against attacks from
+ malicious user space applications.
+
+2. Malicious guest in a virtual machine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The fact that L1TF breaks all domain protections allows malicious guest
+ OSes, which can control the PTEs directly, and malicious guest user
+ space applications, which run on an unprotected guest kernel lacking the
+ PTE inversion mitigation for L1TF, to attack physical host memory.
+
+ A special aspect of L1TF in the context of virtualization is symmetric
+ multi threading (SMT). The Intel implementation of SMT is called
+ HyperThreading. The fact that Hyperthreads on the affected processors
+ share the L1 Data Cache (L1D) is important for this. As the flaw allows
+ only to attack data which is present in L1D, a malicious guest running
+ on one Hyperthread can attack the data which is brought into the L1D by
+ the context which runs on the sibling Hyperthread of the same physical
+ core. This context can be host OS, host user space or a different guest.
+
+ If the processor does not support Extended Page Tables, the attack is
+ only possible, when the hypervisor does not sanitize the content of the
+ effective (shadow) page tables.
+
+ While solutions exist to mitigate these attack vectors fully, these
+ mitigations are not enabled by default in the Linux kernel because they
+ can affect performance significantly. The kernel provides several
+ mechanisms which can be utilized to address the problem depending on the
+ deployment scenario. The mitigations, their protection scope and impact
+ are described in the next sections.
+
+ The default mitigations and the rationale for choosing them are explained
+ at the end of this document. See :ref:`default_mitigations`.
+
+.. _l1tf_sys_info:
+
+L1TF system information
+-----------------------
+
+The Linux kernel provides a sysfs interface to enumerate the current L1TF
+status of the system: whether the system is vulnerable, and which
+mitigations are active. The relevant sysfs file is:
+
+/sys/devices/system/cpu/vulnerabilities/l1tf
+
+The possible values in this file are:
+
+ =========================== ===============================
+ 'Not affected' The processor is not vulnerable
+ 'Mitigation: PTE Inversion' The host protection is active
+ =========================== ===============================
+
+If KVM/VMX is enabled and the processor is vulnerable then the following
+information is appended to the 'Mitigation: PTE Inversion' part:
+
+ - SMT status:
+
+ ===================== ================
+ 'VMX: SMT vulnerable' SMT is enabled
+ 'VMX: SMT disabled' SMT is disabled
+ ===================== ================
+
+ - L1D Flush mode:
+
+ ================================ ====================================
+ 'L1D vulnerable' L1D flushing is disabled
+
+ 'L1D conditional cache flushes' L1D flush is conditionally enabled
+
+ 'L1D cache flushes' L1D flush is unconditionally enabled
+ ================================ ====================================
+
+The resulting grade of protection is discussed in the following sections.
+
+
+Host mitigation mechanism
+-------------------------
+
+The kernel is unconditionally protected against L1TF attacks from malicious
+user space running on the host.
+
+
+Guest mitigation mechanisms
+---------------------------
+
+.. _l1d_flush:
+
+1. L1D flush on VMENTER
+^^^^^^^^^^^^^^^^^^^^^^^
+
+ To make sure that a guest cannot attack data which is present in the L1D
+ the hypervisor flushes the L1D before entering the guest.
+
+ Flushing the L1D evicts not only the data which should not be accessed
+ by a potentially malicious guest, it also flushes the guest
+ data. Flushing the L1D has a performance impact as the processor has to
+ bring the flushed guest data back into the L1D. Depending on the
+ frequency of VMEXIT/VMENTER and the type of computations in the guest
+ performance degradation in the range of 1% to 50% has been observed. For
+ scenarios where guest VMEXIT/VMENTER are rare the performance impact is
+ minimal. Virtio and mechanisms like posted interrupts are designed to
+ confine the VMEXITs to a bare minimum, but specific configurations and
+ application scenarios might still suffer from a high VMEXIT rate.
+
+ The kernel provides two L1D flush modes:
+ - conditional ('cond')
+ - unconditional ('always')
+
+ The conditional mode avoids L1D flushing after VMEXITs which execute
+ only audited code paths before the corresponding VMENTER. These code
+ paths have been verified that they cannot expose secrets or other
+ interesting data to an attacker, but they can leak information about the
+ address space layout of the hypervisor.
+
+ Unconditional mode flushes L1D on all VMENTER invocations and provides
+ maximum protection. It has a higher overhead than the conditional
+ mode. The overhead cannot be quantified correctly as it depends on the
+ workload scenario and the resulting number of VMEXITs.
+
+ The general recommendation is to enable L1D flush on VMENTER. The kernel
+ defaults to conditional mode on affected processors.
+
+ **Note**, that L1D flush does not prevent the SMT problem because the
+ sibling thread will also bring back its data into the L1D which makes it
+ attackable again.
+
+ L1D flush can be controlled by the administrator via the kernel command
+ line and sysfs control files. See :ref:`mitigation_control_command_line`
+ and :ref:`mitigation_control_kvm`.
+
+.. _guest_confinement:
+
+2. Guest VCPU confinement to dedicated physical cores
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ To address the SMT problem, it is possible to make a guest or a group of
+ guests affine to one or more physical cores. The proper mechanism for
+ that is to utilize exclusive cpusets to ensure that no other guest or
+ host tasks can run on these cores.
+
+ If only a single guest or related guests run on sibling SMT threads on
+ the same physical core then they can only attack their own memory and
+ restricted parts of the host memory.
+
+ Host memory is attackable, when one of the sibling SMT threads runs in
+ host OS (hypervisor) context and the other in guest context. The amount
+ of valuable information from the host OS context depends on the context
+ which the host OS executes, i.e. interrupts, soft interrupts and kernel
+ threads. The amount of valuable data from these contexts cannot be
+ declared as non-interesting for an attacker without deep inspection of
+ the code.
+
+ **Note**, that assigning guests to a fixed set of physical cores affects
+ the ability of the scheduler to do load balancing and might have
+ negative effects on CPU utilization depending on the hosting
+ scenario. Disabling SMT might be a viable alternative for particular
+ scenarios.
+
+ For further information about confining guests to a single or to a group
+ of cores consult the cpusets documentation:
+
+ https://www.kernel.org/doc/Documentation/admin-guide/cgroup-v1/cpusets.rst
+
+.. _interrupt_isolation:
+
+3. Interrupt affinity
+^^^^^^^^^^^^^^^^^^^^^
+
+ Interrupts can be made affine to logical CPUs. This is not universally
+ true because there are types of interrupts which are truly per CPU
+ interrupts, e.g. the local timer interrupt. Aside of that multi queue
+ devices affine their interrupts to single CPUs or groups of CPUs per
+ queue without allowing the administrator to control the affinities.
+
+ Moving the interrupts, which can be affinity controlled, away from CPUs
+ which run untrusted guests, reduces the attack vector space.
+
+ Whether the interrupts with are affine to CPUs, which run untrusted
+ guests, provide interesting data for an attacker depends on the system
+ configuration and the scenarios which run on the system. While for some
+ of the interrupts it can be assumed that they won't expose interesting
+ information beyond exposing hints about the host OS memory layout, there
+ is no way to make general assumptions.
+
+ Interrupt affinity can be controlled by the administrator via the
+ /proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
+ available at:
+
+ https://www.kernel.org/doc/Documentation/core-api/irq/irq-affinity.rst
+
+.. _smt_control:
+
+4. SMT control
+^^^^^^^^^^^^^^
+
+ To prevent the SMT issues of L1TF it might be necessary to disable SMT
+ completely. Disabling SMT can have a significant performance impact, but
+ the impact depends on the hosting scenario and the type of workloads.
+ The impact of disabling SMT needs also to be weighted against the impact
+ of other mitigation solutions like confining guests to dedicated cores.
+
+ The kernel provides a sysfs interface to retrieve the status of SMT and
+ to control it. It also provides a kernel command line interface to
+ control SMT.
+
+ The kernel command line interface consists of the following options:
+
+ =========== ==========================================================
+ nosmt Affects the bring up of the secondary CPUs during boot. The
+ kernel tries to bring all present CPUs online during the
+ boot process. "nosmt" makes sure that from each physical
+ core only one - the so called primary (hyper) thread is
+ activated. Due to a design flaw of Intel processors related
+ to Machine Check Exceptions the non primary siblings have
+ to be brought up at least partially and are then shut down
+ again. "nosmt" can be undone via the sysfs interface.
+
+ nosmt=force Has the same effect as "nosmt" but it does not allow to
+ undo the SMT disable via the sysfs interface.
+ =========== ==========================================================
+
+ The sysfs interface provides two files:
+
+ - /sys/devices/system/cpu/smt/control
+ - /sys/devices/system/cpu/smt/active
+
+ /sys/devices/system/cpu/smt/control:
+
+ This file allows to read out the SMT control state and provides the
+ ability to disable or (re)enable SMT. The possible states are:
+
+ ============== ===================================================
+ on SMT is supported by the CPU and enabled. All
+ logical CPUs can be onlined and offlined without
+ restrictions.
+
+ off SMT is supported by the CPU and disabled. Only
+ the so called primary SMT threads can be onlined
+ and offlined without restrictions. An attempt to
+ online a non-primary sibling is rejected
+
+ forceoff Same as 'off' but the state cannot be controlled.
+ Attempts to write to the control file are rejected.
+
+ notsupported The processor does not support SMT. It's therefore
+ not affected by the SMT implications of L1TF.
+ Attempts to write to the control file are rejected.
+ ============== ===================================================
+
+ The possible states which can be written into this file to control SMT
+ state are:
+
+ - on
+ - off
+ - forceoff
+
+ /sys/devices/system/cpu/smt/active:
+
+ This file reports whether SMT is enabled and active, i.e. if on any
+ physical core two or more sibling threads are online.
+
+ SMT control is also possible at boot time via the l1tf kernel command
+ line parameter in combination with L1D flush control. See
+ :ref:`mitigation_control_command_line`.
+
+5. Disabling EPT
+^^^^^^^^^^^^^^^^
+
+ Disabling EPT for virtual machines provides full mitigation for L1TF even
+ with SMT enabled, because the effective page tables for guests are
+ managed and sanitized by the hypervisor. Though disabling EPT has a
+ significant performance impact especially when the Meltdown mitigation
+ KPTI is enabled.
+
+ EPT can be disabled in the hypervisor via the 'kvm-intel.ept' parameter.
+
+There is ongoing research and development for new mitigation mechanisms to
+address the performance impact of disabling SMT or EPT.
+
+.. _mitigation_control_command_line:
+
+Mitigation control on the kernel command line
+---------------------------------------------
+
+The kernel command line allows to control the L1TF mitigations at boot
+time with the option "l1tf=". The valid arguments for this option are:
+
+ ============ =============================================================
+ full Provides all available mitigations for the L1TF
+ vulnerability. Disables SMT and enables all mitigations in
+ the hypervisors, i.e. unconditional L1D flushing
+
+ SMT control and L1D flush control via the sysfs interface
+ is still possible after boot. Hypervisors will issue a
+ warning when the first VM is started in a potentially
+ insecure configuration, i.e. SMT enabled or L1D flush
+ disabled.
+
+ full,force Same as 'full', but disables SMT and L1D flush runtime
+ control. Implies the 'nosmt=force' command line option.
+ (i.e. sysfs control of SMT is disabled.)
+
+ flush Leaves SMT enabled and enables the default hypervisor
+ mitigation, i.e. conditional L1D flushing
+
+ SMT control and L1D flush control via the sysfs interface
+ is still possible after boot. Hypervisors will issue a
+ warning when the first VM is started in a potentially
+ insecure configuration, i.e. SMT enabled or L1D flush
+ disabled.
+
+ flush,nosmt Disables SMT and enables the default hypervisor mitigation,
+ i.e. conditional L1D flushing.
+
+ SMT control and L1D flush control via the sysfs interface
+ is still possible after boot. Hypervisors will issue a
+ warning when the first VM is started in a potentially
+ insecure configuration, i.e. SMT enabled or L1D flush
+ disabled.
+
+ flush,nowarn Same as 'flush', but hypervisors will not warn when a VM is
+ started in a potentially insecure configuration.
+
+ off Disables hypervisor mitigations and doesn't emit any
+ warnings.
+ It also drops the swap size and available RAM limit restrictions
+ on both hypervisor and bare metal.
+
+ ============ =============================================================
+
+The default is 'flush'. For details about L1D flushing see :ref:`l1d_flush`.
+
+
+.. _mitigation_control_kvm:
+
+Mitigation control for KVM - module parameter
+-------------------------------------------------------------
+
+The KVM hypervisor mitigation mechanism, flushing the L1D cache when
+entering a guest, can be controlled with a module parameter.
+
+The option/parameter is "kvm-intel.vmentry_l1d_flush=". It takes the
+following arguments:
+
+ ============ ==============================================================
+ always L1D cache flush on every VMENTER.
+
+ cond Flush L1D on VMENTER only when the code between VMEXIT and
+ VMENTER can leak host memory which is considered
+ interesting for an attacker. This still can leak host memory
+ which allows e.g. to determine the hosts address space layout.
+
+ never Disables the mitigation
+ ============ ==============================================================
+
+The parameter can be provided on the kernel command line, as a module
+parameter when loading the modules and at runtime modified via the sysfs
+file:
+
+/sys/module/kvm_intel/parameters/vmentry_l1d_flush
+
+The default is 'cond'. If 'l1tf=full,force' is given on the kernel command
+line, then 'always' is enforced and the kvm-intel.vmentry_l1d_flush
+module parameter is ignored and writes to the sysfs file are rejected.
+
+.. _mitigation_selection:
+
+Mitigation selection guide
+--------------------------
+
+1. No virtualization in use
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The system is protected by the kernel unconditionally and no further
+ action is required.
+
+2. Virtualization with trusted guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ If the guest comes from a trusted source and the guest OS kernel is
+ guaranteed to have the L1TF mitigations in place the system is fully
+ protected against L1TF and no further action is required.
+
+ To avoid the overhead of the default L1D flushing on VMENTER the
+ administrator can disable the flushing via the kernel command line and
+ sysfs control files. See :ref:`mitigation_control_command_line` and
+ :ref:`mitigation_control_kvm`.
+
+
+3. Virtualization with untrusted guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+3.1. SMT not supported or disabled
+""""""""""""""""""""""""""""""""""
+
+ If SMT is not supported by the processor or disabled in the BIOS or by
+ the kernel, it's only required to enforce L1D flushing on VMENTER.
+
+ Conditional L1D flushing is the default behaviour and can be tuned. See
+ :ref:`mitigation_control_command_line` and :ref:`mitigation_control_kvm`.
+
+3.2. EPT not supported or disabled
+""""""""""""""""""""""""""""""""""
+
+ If EPT is not supported by the processor or disabled in the hypervisor,
+ the system is fully protected. SMT can stay enabled and L1D flushing on
+ VMENTER is not required.
+
+ EPT can be disabled in the hypervisor via the 'kvm-intel.ept' parameter.
+
+3.3. SMT and EPT supported and active
+"""""""""""""""""""""""""""""""""""""
+
+ If SMT and EPT are supported and active then various degrees of
+ mitigations can be employed:
+
+ - L1D flushing on VMENTER:
+
+ L1D flushing on VMENTER is the minimal protection requirement, but it
+ is only potent in combination with other mitigation methods.
+
+ Conditional L1D flushing is the default behaviour and can be tuned. See
+ :ref:`mitigation_control_command_line` and :ref:`mitigation_control_kvm`.
+
+ - Guest confinement:
+
+ Confinement of guests to a single or a group of physical cores which
+ are not running any other processes, can reduce the attack surface
+ significantly, but interrupts, soft interrupts and kernel threads can
+ still expose valuable data to a potential attacker. See
+ :ref:`guest_confinement`.
+
+ - Interrupt isolation:
+
+ Isolating the guest CPUs from interrupts can reduce the attack surface
+ further, but still allows a malicious guest to explore a limited amount
+ of host physical memory. This can at least be used to gain knowledge
+ about the host address space layout. The interrupts which have a fixed
+ affinity to the CPUs which run the untrusted guests can depending on
+ the scenario still trigger soft interrupts and schedule kernel threads
+ which might expose valuable information. See
+ :ref:`interrupt_isolation`.
+
+The above three mitigation methods combined can provide protection to a
+certain degree, but the risk of the remaining attack surface has to be
+carefully analyzed. For full protection the following methods are
+available:
+
+ - Disabling SMT:
+
+ Disabling SMT and enforcing the L1D flushing provides the maximum
+ amount of protection. This mitigation is not depending on any of the
+ above mitigation methods.
+
+ SMT control and L1D flushing can be tuned by the command line
+ parameters 'nosmt', 'l1tf', 'kvm-intel.vmentry_l1d_flush' and at run
+ time with the matching sysfs control files. See :ref:`smt_control`,
+ :ref:`mitigation_control_command_line` and
+ :ref:`mitigation_control_kvm`.
+
+ - Disabling EPT:
+
+ Disabling EPT provides the maximum amount of protection as well. It is
+ not depending on any of the above mitigation methods. SMT can stay
+ enabled and L1D flushing is not required, but the performance impact is
+ significant.
+
+ EPT can be disabled in the hypervisor via the 'kvm-intel.ept'
+ parameter.
+
+3.4. Nested virtual machines
+""""""""""""""""""""""""""""
+
+When nested virtualization is in use, three operating systems are involved:
+the bare metal hypervisor, the nested hypervisor and the nested virtual
+machine. VMENTER operations from the nested hypervisor into the nested
+guest will always be processed by the bare metal hypervisor. If KVM is the
+bare metal hypervisor it will:
+
+ - Flush the L1D cache on every switch from the nested hypervisor to the
+ nested virtual machine, so that the nested hypervisor's secrets are not
+ exposed to the nested virtual machine;
+
+ - Flush the L1D cache on every switch from the nested virtual machine to
+ the nested hypervisor; this is a complex operation, and flushing the L1D
+ cache avoids that the bare metal hypervisor's secrets are exposed to the
+ nested virtual machine;
+
+ - Instruct the nested hypervisor to not perform any L1D cache flush. This
+ is an optimization to avoid double L1D flushing.
+
+
+.. _default_mitigations:
+
+Default mitigations
+-------------------
+
+ The kernel default mitigations for vulnerable processors are:
+
+ - PTE inversion to protect against malicious user space. This is done
+ unconditionally and cannot be controlled. The swap storage is limited
+ to ~16TB.
+
+ - L1D conditional flushing on VMENTER when EPT is enabled for
+ a guest.
+
+ The kernel does not by default enforce the disabling of SMT, which leaves
+ SMT systems vulnerable when running untrusted guests with EPT enabled.
+
+ The rationale for this choice is:
+
+ - Force disabling SMT can break existing setups, especially with
+ unattended updates.
+
+ - If regular users run untrusted guests on their machine, then L1TF is
+ just an add on to other malware which might be embedded in an untrusted
+ guest, e.g. spam-bots or attacks on the local network.
+
+ There is no technical way to prevent a user from running untrusted code
+ on their machines blindly.
+
+ - It's technically extremely unlikely and from today's knowledge even
+ impossible that L1TF can be exploited via the most popular attack
+ mechanisms like JavaScript because these mechanisms have no way to
+ control PTEs. If this would be possible and not other mitigation would
+ be possible, then the default might be different.
+
+ - The administrators of cloud and hosting setups have to carefully
+ analyze the risk for their scenarios and make the appropriate
+ mitigation choices, which might even vary across their deployed
+ machines and also result in other changes of their overall setup.
+ There is no way for the kernel to provide a sensible default for this
+ kind of scenarios.
diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst
new file mode 100644
index 000000000000..754679db0ce8
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/mds.rst
@@ -0,0 +1,303 @@
+MDS - Microarchitectural Data Sampling
+======================================
+
+Microarchitectural Data Sampling is a hardware vulnerability which allows
+unprivileged speculative access to data which is available in various CPU
+internal buffers.
+
+Affected processors
+-------------------
+
+This vulnerability affects a wide range of Intel processors. The
+vulnerability is not present on:
+
+ - Processors from AMD, Centaur and other non Intel vendors
+
+ - Older processor models, where the CPU family is < 6
+
+ - Some Atoms (Bonnell, Saltwell, Goldmont, GoldmontPlus)
+
+ - Intel processors which have the ARCH_CAP_MDS_NO bit set in the
+ IA32_ARCH_CAPABILITIES MSR.
+
+Whether a processor is affected or not can be read out from the MDS
+vulnerability file in sysfs. See :ref:`mds_sys_info`.
+
+Not all processors are affected by all variants of MDS, but the mitigation
+is identical for all of them so the kernel treats them as a single
+vulnerability.
+
+Related CVEs
+------------
+
+The following CVE entries are related to the MDS vulnerability:
+
+ ============== ===== ===================================================
+ CVE-2018-12126 MSBDS Microarchitectural Store Buffer Data Sampling
+ CVE-2018-12130 MFBDS Microarchitectural Fill Buffer Data Sampling
+ CVE-2018-12127 MLPDS Microarchitectural Load Port Data Sampling
+ CVE-2019-11091 MDSUM Microarchitectural Data Sampling Uncacheable Memory
+ ============== ===== ===================================================
+
+Problem
+-------
+
+When performing store, load, L1 refill operations, processors write data
+into temporary microarchitectural structures (buffers). The data in the
+buffer can be forwarded to load operations as an optimization.
+
+Under certain conditions, usually a fault/assist caused by a load
+operation, data unrelated to the load memory address can be speculatively
+forwarded from the buffers. Because the load operation causes a fault or
+assist and its result will be discarded, the forwarded data will not cause
+incorrect program execution or state changes. But a malicious operation
+may be able to forward this speculative data to a disclosure gadget which
+allows in turn to infer the value via a cache side channel attack.
+
+Because the buffers are potentially shared between Hyper-Threads cross
+Hyper-Thread attacks are possible.
+
+Deeper technical information is available in the MDS specific x86
+architecture section: :ref:`Documentation/arch/x86/mds.rst <mds>`.
+
+
+Attack scenarios
+----------------
+
+Attacks against the MDS vulnerabilities can be mounted from malicious non-
+privileged user space applications running on hosts or guest. Malicious
+guest OSes can obviously mount attacks as well.
+
+Contrary to other speculation based vulnerabilities the MDS vulnerability
+does not allow the attacker to control the memory target address. As a
+consequence the attacks are purely sampling based, but as demonstrated with
+the TLBleed attack samples can be postprocessed successfully.
+
+Web-Browsers
+^^^^^^^^^^^^
+
+ It's unclear whether attacks through Web-Browsers are possible at
+ all. The exploitation through Java-Script is considered very unlikely,
+ but other widely used web technologies like Webassembly could possibly be
+ abused.
+
+
+.. _mds_sys_info:
+
+MDS system information
+-----------------------
+
+The Linux kernel provides a sysfs interface to enumerate the current MDS
+status of the system: whether the system is vulnerable, and which
+mitigations are active. The relevant sysfs file is:
+
+/sys/devices/system/cpu/vulnerabilities/mds
+
+The possible values in this file are:
+
+ .. list-table::
+
+ * - 'Not affected'
+ - The processor is not vulnerable
+ * - 'Vulnerable'
+ - The processor is vulnerable, but no mitigation enabled
+ * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
+ - The processor is vulnerable but microcode is not updated. The
+ mitigation is enabled on a best effort basis.
+
+ If the processor is vulnerable but the availability of the microcode
+ based mitigation mechanism is not advertised via CPUID, the kernel
+ selects a best effort mitigation mode. This mode invokes the mitigation
+ instructions without a guarantee that they clear the CPU buffers.
+
+ This is done to address virtualization scenarios where the host has the
+ microcode update applied, but the hypervisor is not yet updated to
+ expose the CPUID to the guest. If the host has updated microcode the
+ protection takes effect; otherwise a few CPU cycles are wasted
+ pointlessly.
+ * - 'Mitigation: Clear CPU buffers'
+ - The processor is vulnerable and the CPU buffer clearing mitigation is
+ enabled.
+
+If the processor is vulnerable then the following information is appended
+to the above information:
+
+ ======================== ============================================
+ 'SMT vulnerable' SMT is enabled
+ 'SMT mitigated' SMT is enabled and mitigated
+ 'SMT disabled' SMT is disabled
+ 'SMT Host state unknown' Kernel runs in a VM, Host SMT state unknown
+ ======================== ============================================
+
+Mitigation mechanism
+-------------------------
+
+The kernel detects the affected CPUs and the presence of the microcode
+which is required.
+
+If a CPU is affected and the microcode is available, then the kernel
+enables the mitigation by default. The mitigation can be controlled at boot
+time via a kernel command line option. See
+:ref:`mds_mitigation_control_command_line`.
+
+.. _cpu_buffer_clear:
+
+CPU buffer clearing
+^^^^^^^^^^^^^^^^^^^
+
+ The mitigation for MDS clears the affected CPU buffers on return to user
+ space and when entering a guest.
+
+ If SMT is enabled it also clears the buffers on idle entry when the CPU
+ is only affected by MSBDS and not any other MDS variant, because the
+ other variants cannot be protected against cross Hyper-Thread attacks.
+
+ For CPUs which are only affected by MSBDS the user space, guest and idle
+ transition mitigations are sufficient and SMT is not affected.
+
+.. _virt_mechanism:
+
+Virtualization mitigation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The protection for host to guest transition depends on the L1TF
+ vulnerability of the CPU:
+
+ - CPU is affected by L1TF:
+
+ If the L1D flush mitigation is enabled and up to date microcode is
+ available, the L1D flush mitigation is automatically protecting the
+ guest transition.
+
+ If the L1D flush mitigation is disabled then the MDS mitigation is
+ invoked explicit when the host MDS mitigation is enabled.
+
+ For details on L1TF and virtualization see:
+ :ref:`Documentation/admin-guide/hw-vuln//l1tf.rst <mitigation_control_kvm>`.
+
+ - CPU is not affected by L1TF:
+
+ CPU buffers are flushed before entering the guest when the host MDS
+ mitigation is enabled.
+
+ The resulting MDS protection matrix for the host to guest transition:
+
+ ============ ===== ============= ============ =================
+ L1TF MDS VMX-L1FLUSH Host MDS MDS-State
+
+ Don't care No Don't care N/A Not affected
+
+ Yes Yes Disabled Off Vulnerable
+
+ Yes Yes Disabled Full Mitigated
+
+ Yes Yes Enabled Don't care Mitigated
+
+ No Yes N/A Off Vulnerable
+
+ No Yes N/A Full Mitigated
+ ============ ===== ============= ============ =================
+
+ This only covers the host to guest transition, i.e. prevents leakage from
+ host to guest, but does not protect the guest internally. Guests need to
+ have their own protections.
+
+.. _xeon_phi:
+
+XEON PHI specific considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The XEON PHI processor family is affected by MSBDS which can be exploited
+ cross Hyper-Threads when entering idle states. Some XEON PHI variants allow
+ to use MWAIT in user space (Ring 3) which opens an potential attack vector
+ for malicious user space. The exposure can be disabled on the kernel
+ 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 an idle state. As XEON PHI is not affected by L1TF
+ either disabling SMT is not required for full protection.
+
+.. _mds_smt_control:
+
+SMT control
+^^^^^^^^^^^
+
+ All MDS variants except MSBDS can be attacked cross Hyper-Threads. That
+ means on CPUs which are affected by MFBDS or MLPDS it is necessary to
+ disable SMT for full protection. These are most of the affected CPUs; the
+ exception is XEON PHI, see :ref:`xeon_phi`.
+
+ Disabling SMT can have a significant performance impact, but the impact
+ depends on the type of workloads.
+
+ See the relevant chapter in the L1TF mitigation documentation for details:
+ :ref:`Documentation/admin-guide/hw-vuln/l1tf.rst <smt_control>`.
+
+
+.. _mds_mitigation_control_command_line:
+
+Mitigation control on the kernel command line
+---------------------------------------------
+
+The kernel command line allows to control the MDS mitigations at boot
+time with the option "mds=". The valid arguments for this option are:
+
+ ============ =============================================================
+ full If the CPU is vulnerable, enable all available mitigations
+ for the MDS vulnerability, CPU buffer clearing on exit to
+ userspace and when entering a VM. Idle transitions are
+ protected as well if SMT is enabled.
+
+ It does not automatically disable SMT.
+
+ full,nosmt The same as mds=full, with SMT disabled on vulnerable
+ CPUs. This is the complete mitigation.
+
+ off Disables MDS mitigations completely.
+
+ ============ =============================================================
+
+Not specifying this option is equivalent to "mds=full". For processors
+that are affected by both TAA (TSX Asynchronous Abort) and MDS,
+specifying just "mds=off" without an accompanying "tsx_async_abort=off"
+will have no effect as the same mitigation is used for both
+vulnerabilities.
+
+Mitigation selection guide
+--------------------------
+
+1. Trusted userspace
+^^^^^^^^^^^^^^^^^^^^
+
+ If all userspace applications are from a trusted source and do not
+ execute untrusted code which is supplied externally, then the mitigation
+ can be disabled.
+
+
+2. Virtualization with trusted guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The same considerations as above versus trusted user space apply.
+
+3. Virtualization with untrusted guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The protection depends on the state of the L1TF mitigations.
+ See :ref:`virt_mechanism`.
+
+ If the MDS mitigation is enabled and SMT is disabled, guest to host and
+ guest to guest attacks are prevented.
+
+.. _mds_default_mitigations:
+
+Default mitigations
+-------------------
+
+ The kernel default mitigations for vulnerable processors are:
+
+ - Enable CPU buffer clearing
+
+ The kernel does not by default enforce the disabling of SMT, which leaves
+ SMT systems vulnerable when running untrusted code. The same rationale as
+ for L1TF applies.
+ See :ref:`Documentation/admin-guide/hw-vuln//l1tf.rst <default_mitigations>`.
diff --git a/Documentation/admin-guide/hw-vuln/multihit.rst b/Documentation/admin-guide/hw-vuln/multihit.rst
new file mode 100644
index 000000000000..140e4cec38c3
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/multihit.rst
@@ -0,0 +1,167 @@
+iTLB multihit
+=============
+
+iTLB multihit is an erratum where some processors may incur a machine check
+error, possibly resulting in an unrecoverable CPU lockup, when an
+instruction fetch hits multiple entries in the instruction TLB. This can
+occur when the page size is changed along with either the physical address
+or cache type. A malicious guest running on a virtualized system can
+exploit this erratum to perform a denial of service attack.
+
+
+Affected processors
+-------------------
+
+Variations of this erratum are present on most Intel Core and Xeon processor
+models. The erratum is not present on:
+
+ - non-Intel processors
+
+ - Some Atoms (Airmont, Bonnell, Goldmont, GoldmontPlus, Saltwell, Silvermont)
+
+ - Intel processors that have the PSCHANGE_MC_NO bit set in the
+ IA32_ARCH_CAPABILITIES MSR.
+
+
+Related CVEs
+------------
+
+The following CVE entry is related to this issue:
+
+ ============== =================================================
+ CVE-2018-12207 Machine Check Error Avoidance on Page Size Change
+ ============== =================================================
+
+
+Problem
+-------
+
+Privileged software, including OS and virtual machine managers (VMM), are in
+charge of memory management. A key component in memory management is the control
+of the page tables. Modern processors use virtual memory, a technique that creates
+the illusion of a very large memory for processors. This virtual space is split
+into pages of a given size. Page tables translate virtual addresses to physical
+addresses.
+
+To reduce latency when performing a virtual to physical address translation,
+processors include a structure, called TLB, that caches recent translations.
+There are separate TLBs for instruction (iTLB) and data (dTLB).
+
+Under this errata, instructions are fetched from a linear address translated
+using a 4 KB translation cached in the iTLB. Privileged software modifies the
+paging structure so that the same linear address using large page size (2 MB, 4
+MB, 1 GB) with a different physical address or memory type. After the page
+structure modification but before the software invalidates any iTLB entries for
+the linear address, a code fetch that happens on the same linear address may
+cause a machine-check error which can result in a system hang or shutdown.
+
+
+Attack scenarios
+----------------
+
+Attacks against the iTLB multihit erratum can be mounted from malicious
+guests in a virtualized system.
+
+
+iTLB multihit system information
+--------------------------------
+
+The Linux kernel provides a sysfs interface to enumerate the current iTLB
+multihit status of the system:whether the system is vulnerable and which
+mitigations are active. The relevant sysfs file is:
+
+/sys/devices/system/cpu/vulnerabilities/itlb_multihit
+
+The possible values in this file are:
+
+.. list-table::
+
+ * - Not affected
+ - The processor is not vulnerable.
+ * - KVM: Mitigation: Split huge pages
+ - Software changes mitigate this issue.
+ * - KVM: Mitigation: VMX unsupported
+ - KVM is not vulnerable because Virtual Machine Extensions (VMX) is not supported.
+ * - KVM: Mitigation: VMX disabled
+ - KVM is not vulnerable because Virtual Machine Extensions (VMX) is disabled.
+ * - KVM: Vulnerable
+ - The processor is vulnerable, but no mitigation enabled
+
+
+Enumeration of the erratum
+--------------------------------
+
+A new bit has been allocated in the IA32_ARCH_CAPABILITIES (PSCHANGE_MC_NO) msr
+and will be set on CPU's which are mitigated against this issue.
+
+ ======================================= =========== ===============================
+ IA32_ARCH_CAPABILITIES MSR Not present Possibly vulnerable,check model
+ IA32_ARCH_CAPABILITIES[PSCHANGE_MC_NO] '0' Likely vulnerable,check model
+ IA32_ARCH_CAPABILITIES[PSCHANGE_MC_NO] '1' Not vulnerable
+ ======================================= =========== ===============================
+
+
+Mitigation mechanism
+-------------------------
+
+This erratum can be mitigated by restricting the use of large page sizes to
+non-executable pages. This forces all iTLB entries to be 4K, and removes
+the possibility of multiple hits.
+
+In order to mitigate the vulnerability, KVM initially marks all huge pages
+as non-executable. If the guest attempts to execute in one of those pages,
+the page is broken down into 4K pages, which are then marked executable.
+
+If EPT is disabled or not available on the host, KVM is in control of TLB
+flushes and the problematic situation cannot happen. However, the shadow
+EPT paging mechanism used by nested virtualization is vulnerable, because
+the nested guest can trigger multiple iTLB hits by modifying its own
+(non-nested) page tables. For simplicity, KVM will make large pages
+non-executable in all shadow paging modes.
+
+Mitigation control on the kernel command line and KVM - module parameter
+------------------------------------------------------------------------
+
+The KVM hypervisor mitigation mechanism for marking huge pages as
+non-executable can be controlled with a module parameter "nx_huge_pages=".
+The kernel command line allows to control the iTLB multihit mitigations at
+boot time with the option "kvm.nx_huge_pages=".
+
+The valid arguments for these options are:
+
+ ========== ================================================================
+ force Mitigation is enabled. In this case, the mitigation implements
+ non-executable huge pages in Linux kernel KVM module. All huge
+ pages in the EPT are marked as non-executable.
+ If a guest attempts to execute in one of those pages, the page is
+ broken down into 4K pages, which are then marked executable.
+
+ off Mitigation is disabled.
+
+ auto Enable mitigation only if the platform is affected and the kernel
+ was not booted with the "mitigations=off" command line parameter.
+ This is the default option.
+ ========== ================================================================
+
+
+Mitigation selection guide
+--------------------------
+
+1. No virtualization in use
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The system is protected by the kernel unconditionally and no further
+ action is required.
+
+2. Virtualization with trusted guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ If the guest comes from a trusted source, you may assume that the guest will
+ not attempt to maliciously exploit these errata and no further action is
+ required.
+
+3. Virtualization with untrusted guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ If the guest comes from an untrusted source, the guest host kernel will need
+ to apply iTLB multihit mitigation via the kernel command line or kvm
+ module parameter.
diff --git a/Documentation/admin-guide/hw-vuln/old_microcode.rst b/Documentation/admin-guide/hw-vuln/old_microcode.rst
new file mode 100644
index 000000000000..6ded8f86b8d0
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/old_microcode.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+Old Microcode
+=============
+
+The kernel keeps a table of released microcode. Systems that had
+microcode older than this at boot will say "Vulnerable". This means
+that the system was vulnerable to some known CPU issue. It could be
+security or functional, the kernel does not know or care.
+
+You should update the CPU microcode to mitigate any exposure. This is
+usually accomplished by updating the files in
+/lib/firmware/intel-ucode/ via normal distribution updates. Intel also
+distributes these files in a github repo:
+
+ https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files.git
+
+Just like all the other hardware vulnerabilities, exposure is
+determined at boot. Runtime microcode updates do not change the status
+of this vulnerability.
diff --git a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
new file mode 100644
index 000000000000..6dba18dbb9ab
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
@@ -0,0 +1,269 @@
+=========================================
+Processor MMIO Stale Data Vulnerabilities
+=========================================
+
+Processor MMIO Stale Data Vulnerabilities are a class of memory-mapped I/O
+(MMIO) vulnerabilities that can expose data. The sequences of operations for
+exposing data range from simple to very complex. Because most of the
+vulnerabilities require the attacker to have access to MMIO, many environments
+are not affected. System environments using virtualization where MMIO access is
+provided to untrusted guests may need mitigation. These vulnerabilities are
+not transient execution attacks. However, these vulnerabilities may propagate
+stale data into core fill buffers where the data can subsequently be inferred
+by an unmitigated transient execution attack. Mitigation for these
+vulnerabilities includes a combination of microcode update and software
+changes, depending on the platform and usage model. Some of these mitigations
+are similar to those used to mitigate Microarchitectural Data Sampling (MDS) or
+those used to mitigate Special Register Buffer Data Sampling (SRBDS).
+
+Data Propagators
+================
+Propagators are operations that result in stale data being copied or moved from
+one microarchitectural buffer or register to another. Processor MMIO Stale Data
+Vulnerabilities are operations that may result in stale data being directly
+read into an architectural, software-visible state or sampled from a buffer or
+register.
+
+Fill Buffer Stale Data Propagator (FBSDP)
+-----------------------------------------
+Stale data may propagate from fill buffers (FB) into the non-coherent portion
+of the uncore on some non-coherent writes. Fill buffer propagation by itself
+does not make stale data architecturally visible. Stale data must be propagated
+to a location where it is subject to reading or sampling.
+
+Sideband Stale Data Propagator (SSDP)
+-------------------------------------
+The sideband stale data propagator (SSDP) is limited to the client (including
+Intel Xeon server E3) uncore implementation. The sideband response buffer is
+shared by all client cores. For non-coherent reads that go to sideband
+destinations, the uncore logic returns 64 bytes of data to the core, including
+both requested data and unrequested stale data, from a transaction buffer and
+the sideband response buffer. As a result, stale data from the sideband
+response and transaction buffers may now reside in a core fill buffer.
+
+Primary Stale Data Propagator (PSDP)
+------------------------------------
+The primary stale data propagator (PSDP) is limited to the client (including
+Intel Xeon server E3) uncore implementation. Similar to the sideband response
+buffer, the primary response buffer is shared by all client cores. For some
+processors, MMIO primary reads will return 64 bytes of data to the core fill
+buffer including both requested data and unrequested stale data. This is
+similar to the sideband stale data propagator.
+
+Vulnerabilities
+===============
+Device Register Partial Write (DRPW) (CVE-2022-21166)
+-----------------------------------------------------
+Some endpoint MMIO registers incorrectly handle writes that are smaller than
+the register size. Instead of aborting the write or only copying the correct
+subset of bytes (for example, 2 bytes for a 2-byte write), more bytes than
+specified by the write transaction may be written to the register. On
+processors affected by FBSDP, this may expose stale data from the fill buffers
+of the core that created the write transaction.
+
+Shared Buffers Data Sampling (SBDS) (CVE-2022-21125)
+----------------------------------------------------
+After propagators may have moved data around the uncore and copied stale data
+into client core fill buffers, processors affected by MFBDS can leak data from
+the fill buffer. It is limited to the client (including Intel Xeon server E3)
+uncore implementation.
+
+Shared Buffers Data Read (SBDR) (CVE-2022-21123)
+------------------------------------------------
+It is similar to Shared Buffer Data Sampling (SBDS) except that the data is
+directly read into the architectural software-visible state. It is limited to
+the client (including Intel Xeon server E3) uncore implementation.
+
+Affected Processors
+===================
+Not all the CPUs are affected by all the variants. For instance, most
+processors for the server market (excluding Intel Xeon E3 processors) are
+impacted by only Device Register Partial Write (DRPW).
+
+Below is the list of affected Intel processors [#f1]_:
+
+ =================== ============ =========
+ Common name Family_Model Steppings
+ =================== ============ =========
+ HASWELL_X 06_3FH 2,4
+ SKYLAKE_L 06_4EH 3
+ BROADWELL_X 06_4FH All
+ SKYLAKE_X 06_55H 3,4,6,7,11
+ BROADWELL_D 06_56H 3,4,5
+ SKYLAKE 06_5EH 3
+ ICELAKE_X 06_6AH 4,5,6
+ ICELAKE_D 06_6CH 1
+ ICELAKE_L 06_7EH 5
+ ATOM_TREMONT_D 06_86H All
+ LAKEFIELD 06_8AH 1
+ KABYLAKE_L 06_8EH 9 to 12
+ ATOM_TREMONT 06_96H 1
+ ATOM_TREMONT_L 06_9CH 0
+ KABYLAKE 06_9EH 9 to 13
+ COMETLAKE 06_A5H 2,3,5
+ COMETLAKE_L 06_A6H 0,1
+ ROCKETLAKE 06_A7H 1
+ =================== ============ =========
+
+If a CPU is in the affected processor list, but not affected by a variant, it
+is indicated by new bits in MSR IA32_ARCH_CAPABILITIES. As described in a later
+section, mitigation largely remains the same for all the variants, i.e. to
+clear the CPU fill buffers via VERW instruction.
+
+New bits in MSRs
+================
+Newer processors and microcode update on existing affected processors added new
+bits to IA32_ARCH_CAPABILITIES MSR. These bits can be used to enumerate
+specific variants of Processor MMIO Stale Data vulnerabilities and mitigation
+capability.
+
+MSR IA32_ARCH_CAPABILITIES
+--------------------------
+Bit 13 - SBDR_SSDP_NO - When set, processor is not affected by either the
+ Shared Buffers Data Read (SBDR) vulnerability or the sideband stale
+ data propagator (SSDP).
+Bit 14 - FBSDP_NO - When set, processor is not affected by the Fill Buffer
+ Stale Data Propagator (FBSDP).
+Bit 15 - PSDP_NO - When set, processor is not affected by Primary Stale Data
+ Propagator (PSDP).
+Bit 17 - FB_CLEAR - When set, VERW instruction will overwrite CPU fill buffer
+ values as part of MD_CLEAR operations. Processors that do not
+ enumerate MDS_NO (meaning they are affected by MDS) but that do
+ enumerate support for both L1D_FLUSH and MD_CLEAR implicitly enumerate
+ FB_CLEAR as part of their MD_CLEAR support.
+Bit 18 - FB_CLEAR_CTRL - Processor supports read and write to MSR
+ IA32_MCU_OPT_CTRL[FB_CLEAR_DIS]. On such processors, the FB_CLEAR_DIS
+ bit can be set to cause the VERW instruction to not perform the
+ FB_CLEAR action. Not all processors that support FB_CLEAR will support
+ FB_CLEAR_CTRL.
+
+MSR IA32_MCU_OPT_CTRL
+---------------------
+Bit 3 - FB_CLEAR_DIS - When set, VERW instruction does not perform the FB_CLEAR
+action. This may be useful to reduce the performance impact of FB_CLEAR in
+cases where system software deems it warranted (for example, when performance
+is more critical, or the untrusted software has no MMIO access). Note that
+FB_CLEAR_DIS has no impact on enumeration (for example, it does not change
+FB_CLEAR or MD_CLEAR enumeration) and it may not be supported on all processors
+that enumerate FB_CLEAR.
+
+Mitigation
+==========
+Like MDS, all variants of Processor MMIO Stale Data vulnerabilities have the
+same mitigation strategy to force the CPU to clear the affected buffers before
+an attacker can extract the secrets.
+
+This is achieved by using the otherwise unused and obsolete VERW instruction in
+combination with a microcode update. The microcode clears the affected CPU
+buffers when the VERW instruction is executed.
+
+Kernel does the buffer clearing with x86_clear_cpu_buffers().
+
+On MDS affected CPUs, the kernel already invokes CPU buffer clear on
+kernel/userspace, hypervisor/guest and C-state (idle) transitions. No
+additional mitigation is needed on such CPUs.
+
+For CPUs not affected by MDS or TAA, mitigation is needed only for the attacker
+with MMIO capability. Therefore, VERW is not required for kernel/userspace. For
+virtualization case, VERW is only needed at VMENTER for a guest with MMIO
+capability.
+
+Mitigation points
+-----------------
+Return to user space
+^^^^^^^^^^^^^^^^^^^^
+Same mitigation as MDS when affected by MDS/TAA, otherwise no mitigation
+needed.
+
+C-State transition
+^^^^^^^^^^^^^^^^^^
+Control register writes by CPU during C-state transition can propagate data
+from fill buffer to uncore buffers. Execute VERW before C-state transition to
+clear CPU fill buffers.
+
+Guest entry point
+^^^^^^^^^^^^^^^^^
+Same mitigation as MDS when processor is also affected by MDS/TAA, otherwise
+execute VERW at VMENTER only for MMIO capable guests. On CPUs not affected by
+MDS/TAA, guest without MMIO access cannot extract secrets using Processor MMIO
+Stale Data vulnerabilities, so there is no need to execute VERW for such guests.
+
+Mitigation control on the kernel command line
+---------------------------------------------
+The kernel command line allows to control the Processor MMIO Stale Data
+mitigations at boot time with the option "mmio_stale_data=". The valid
+arguments for this option are:
+
+ ========== =================================================================
+ full If the CPU is vulnerable, enable mitigation; CPU buffer clearing
+ on exit to userspace and when entering a VM. Idle transitions are
+ protected as well. It does not automatically disable SMT.
+ full,nosmt Same as full, with SMT disabled on vulnerable CPUs. This is the
+ complete mitigation.
+ off Disables mitigation completely.
+ ========== =================================================================
+
+If the CPU is affected and mmio_stale_data=off is not supplied on the kernel
+command line, then the kernel selects the appropriate mitigation.
+
+Mitigation status information
+-----------------------------
+The Linux kernel provides a sysfs interface to enumerate the current
+vulnerability status of the system: whether the system is vulnerable, and
+which mitigations are active. The relevant sysfs file is:
+
+ /sys/devices/system/cpu/vulnerabilities/mmio_stale_data
+
+The possible values in this file are:
+
+ .. list-table::
+
+ * - 'Not affected'
+ - The processor is not vulnerable
+ * - 'Vulnerable'
+ - The processor is vulnerable, but no mitigation enabled
+ * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
+ - The processor is vulnerable but microcode is not updated. The
+ mitigation is enabled on a best effort basis.
+
+ If the processor is vulnerable but the availability of the microcode
+ based mitigation mechanism is not advertised via CPUID, the kernel
+ selects a best effort mitigation mode. This mode invokes the mitigation
+ instructions without a guarantee that they clear the CPU buffers.
+
+ This is done to address virtualization scenarios where the host has the
+ microcode update applied, but the hypervisor is not yet updated to
+ expose the CPUID to the guest. If the host has updated microcode the
+ protection takes effect; otherwise a few CPU cycles are wasted
+ pointlessly.
+ * - 'Mitigation: Clear CPU buffers'
+ - The processor is vulnerable and the CPU buffer clearing mitigation is
+ enabled.
+ * - 'Unknown: No mitigations'
+ - The processor vulnerability status is unknown because it is
+ out of Servicing period. Mitigation is not attempted.
+
+Definitions:
+------------
+
+Servicing period: The process of providing functional and security updates to
+Intel processors or platforms, utilizing the Intel Platform Update (IPU)
+process or other similar mechanisms.
+
+End of Servicing Updates (ESU): ESU is the date at which Intel will no
+longer provide Servicing, such as through IPU or other similar update
+processes. ESU dates will typically be aligned to end of quarter.
+
+If the processor is vulnerable then the following information is appended to
+the above information:
+
+ ======================== ===========================================
+ 'SMT vulnerable' SMT is enabled
+ 'SMT disabled' SMT is disabled
+ 'SMT Host state unknown' Kernel runs in a VM, Host SMT state unknown
+ ======================== ===========================================
+
+References
+----------
+.. [#f1] Affected Processors
+ https://www.intel.com/content/www/us/en/developer/topic-technology/software-security-guidance/processors-affected-consolidated-product-cpu-model.html
diff --git a/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst b/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
new file mode 100644
index 000000000000..ad15417d39f9
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
@@ -0,0 +1,96 @@
+==================================
+Register File Data Sampling (RFDS)
+==================================
+
+Register File Data Sampling (RFDS) is a microarchitectural vulnerability that
+only affects Intel Atom parts(also branded as E-cores). RFDS may allow
+a malicious actor to infer data values previously used in floating point
+registers, vector registers, or integer registers. RFDS does not provide the
+ability to choose which data is inferred. CVE-2023-28746 is assigned to RFDS.
+
+Affected Processors
+===================
+Below is the list of affected Intel processors [#f1]_:
+
+ =================== ============
+ Common name Family_Model
+ =================== ============
+ ATOM_GOLDMONT 06_5CH
+ ATOM_GOLDMONT_D 06_5FH
+ ATOM_GOLDMONT_PLUS 06_7AH
+ ATOM_TREMONT_D 06_86H
+ ATOM_TREMONT 06_96H
+ ALDERLAKE 06_97H
+ ALDERLAKE_L 06_9AH
+ ATOM_TREMONT_L 06_9CH
+ RAPTORLAKE 06_B7H
+ RAPTORLAKE_P 06_BAH
+ ATOM_GRACEMONT 06_BEH
+ RAPTORLAKE_S 06_BFH
+ =================== ============
+
+Mitigation
+==========
+Intel released a microcode update that enables software to clear sensitive
+information using the VERW instruction. Like MDS, RFDS deploys the same
+mitigation strategy to force the CPU to clear the affected buffers before an
+attacker can extract the secrets. This is achieved by using the otherwise
+unused and obsolete VERW instruction in combination with a microcode update.
+The microcode clears the affected CPU buffers when the VERW instruction is
+executed.
+
+Mitigation points
+-----------------
+VERW is executed by the kernel before returning to user space, and by KVM
+before VMentry. None of the affected cores support SMT, so VERW is not required
+at C-state transitions.
+
+New bits in IA32_ARCH_CAPABILITIES
+----------------------------------
+Newer processors and microcode update on existing affected processors added new
+bits to IA32_ARCH_CAPABILITIES MSR. These bits can be used to enumerate
+vulnerability and mitigation capability:
+
+- Bit 27 - RFDS_NO - When set, processor is not affected by RFDS.
+- Bit 28 - RFDS_CLEAR - When set, processor is affected by RFDS, and has the
+ microcode that clears the affected buffers on VERW execution.
+
+Mitigation control on the kernel command line
+---------------------------------------------
+The kernel command line allows to control RFDS mitigation at boot time with the
+parameter "reg_file_data_sampling=". The valid arguments are:
+
+ ========== =================================================================
+ on If the CPU is vulnerable, enable mitigation; CPU buffer clearing
+ on exit to userspace and before entering a VM.
+ off Disables mitigation.
+ ========== =================================================================
+
+Mitigation default is selected by CONFIG_MITIGATION_RFDS.
+
+Mitigation status information
+-----------------------------
+The Linux kernel provides a sysfs interface to enumerate the current
+vulnerability status of the system: whether the system is vulnerable, and
+which mitigations are active. The relevant sysfs file is:
+
+ /sys/devices/system/cpu/vulnerabilities/reg_file_data_sampling
+
+The possible values in this file are:
+
+ .. list-table::
+
+ * - 'Not affected'
+ - The processor is not vulnerable
+ * - 'Vulnerable'
+ - The processor is vulnerable, but no mitigation enabled
+ * - 'Vulnerable: No microcode'
+ - The processor is vulnerable but microcode is not updated.
+ * - 'Mitigation: Clear Register File'
+ - The processor is vulnerable and the CPU buffer clearing mitigation is
+ enabled.
+
+References
+----------
+.. [#f1] Affected Processors
+ https://www.intel.com/content/www/us/en/developer/topic-technology/software-security-guidance/processors-affected-consolidated-product-cpu-model.html
diff --git a/Documentation/admin-guide/hw-vuln/rsb.rst b/Documentation/admin-guide/hw-vuln/rsb.rst
new file mode 100644
index 000000000000..21dbf9cf25f8
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/rsb.rst
@@ -0,0 +1,268 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+RSB-related mitigations
+=======================
+
+.. warning::
+ Please keep this document up-to-date, otherwise you will be
+ volunteered to update it and convert it to a very long comment in
+ bugs.c!
+
+Since 2018 there have been many Spectre CVEs related to the Return Stack
+Buffer (RSB) (sometimes referred to as the Return Address Stack (RAS) or
+Return Address Predictor (RAP) on AMD).
+
+Information about these CVEs and how to mitigate them is scattered
+amongst a myriad of microarchitecture-specific documents.
+
+This document attempts to consolidate all the relevant information in
+once place and clarify the reasoning behind the current RSB-related
+mitigations. It's meant to be as concise as possible, focused only on
+the current kernel mitigations: what are the RSB-related attack vectors
+and how are they currently being mitigated?
+
+It's *not* meant to describe how the RSB mechanism operates or how the
+exploits work. More details about those can be found in the references
+below.
+
+Rather, this is basically a glorified comment, but too long to actually
+be one. So when the next CVE comes along, a kernel developer can
+quickly refer to this as a refresher to see what we're actually doing
+and why.
+
+At a high level, there are two classes of RSB attacks: RSB poisoning
+(Intel and AMD) and RSB underflow (Intel only). They must each be
+considered individually for each attack vector (and microarchitecture
+where applicable).
+
+----
+
+RSB poisoning (Intel and AMD)
+=============================
+
+SpectreRSB
+~~~~~~~~~~
+
+RSB poisoning is a technique used by SpectreRSB [#spectre-rsb]_ where
+an attacker poisons an RSB entry to cause a victim's return instruction
+to speculate to an attacker-controlled address. This can happen when
+there are unbalanced CALLs/RETs after a context switch or VMEXIT.
+
+* All attack vectors can potentially be mitigated by flushing out any
+ poisoned RSB entries using an RSB filling sequence
+ [#intel-rsb-filling]_ [#amd-rsb-filling]_ when transitioning between
+ untrusted and trusted domains. But this has a performance impact and
+ should be avoided whenever possible.
+
+ .. DANGER::
+ **FIXME**: Currently we're flushing 32 entries. However, some CPU
+ models have more than 32 entries. The loop count needs to be
+ increased for those. More detailed information is needed about RSB
+ sizes.
+
+* On context switch, the user->user mitigation requires ensuring the
+ RSB gets filled or cleared whenever IBPB gets written [#cond-ibpb]_
+ during a context switch:
+
+ * AMD:
+ On Zen 4+, IBPB (or SBPB [#amd-sbpb]_ if used) clears the RSB.
+ This is indicated by IBPB_RET in CPUID [#amd-ibpb-rsb]_.
+
+ On Zen < 4, the RSB filling sequence [#amd-rsb-filling]_ must be
+ always be done in addition to IBPB [#amd-ibpb-no-rsb]_. This is
+ indicated by X86_BUG_IBPB_NO_RET.
+
+ * Intel:
+ IBPB always clears the RSB:
+
+ "Software that executed before the IBPB command cannot control
+ the predicted targets of indirect branches executed after the
+ command on the same logical processor. The term indirect branch
+ in this context includes near return instructions, so these
+ predicted targets may come from the RSB." [#intel-ibpb-rsb]_
+
+* On context switch, user->kernel attacks are prevented by SMEP. User
+ space can only insert user space addresses into the RSB. Even
+ non-canonical addresses can't be inserted due to the page gap at the
+ end of the user canonical address space reserved by TASK_SIZE_MAX.
+ A SMEP #PF at instruction fetch prevents the kernel from speculatively
+ executing user space.
+
+ * AMD:
+ "Finally, branches that are predicted as 'ret' instructions get
+ their predicted targets from the Return Address Predictor (RAP).
+ AMD recommends software use a RAP stuffing sequence (mitigation
+ V2-3 in [2]) and/or Supervisor Mode Execution Protection (SMEP)
+ to ensure that the addresses in the RAP are safe for
+ speculation. Collectively, we refer to these mitigations as "RAP
+ Protection"." [#amd-smep-rsb]_
+
+ * Intel:
+ "On processors with enhanced IBRS, an RSB overwrite sequence may
+ not suffice to prevent the predicted target of a near return
+ from using an RSB entry created in a less privileged predictor
+ mode. Software can prevent this by enabling SMEP (for
+ transitions from user mode to supervisor mode) and by having
+ IA32_SPEC_CTRL.IBRS set during VM exits." [#intel-smep-rsb]_
+
+* On VMEXIT, guest->host attacks are mitigated by eIBRS (and PBRSB
+ mitigation if needed):
+
+ * AMD:
+ "When Automatic IBRS is enabled, the internal return address
+ stack used for return address predictions is cleared on VMEXIT."
+ [#amd-eibrs-vmexit]_
+
+ * Intel:
+ "On processors with enhanced IBRS, an RSB overwrite sequence may
+ not suffice to prevent the predicted target of a near return
+ from using an RSB entry created in a less privileged predictor
+ mode. Software can prevent this by enabling SMEP (for
+ transitions from user mode to supervisor mode) and by having
+ IA32_SPEC_CTRL.IBRS set during VM exits. Processors with
+ enhanced IBRS still support the usage model where IBRS is set
+ only in the OS/VMM for OSes that enable SMEP. To do this, such
+ processors will ensure that guest behavior cannot control the
+ RSB after a VM exit once IBRS is set, even if IBRS was not set
+ at the time of the VM exit." [#intel-eibrs-vmexit]_
+
+ Note that some Intel CPUs are susceptible to Post-barrier Return
+ Stack Buffer Predictions (PBRSB) [#intel-pbrsb]_, where the last
+ CALL from the guest can be used to predict the first unbalanced RET.
+ In this case the PBRSB mitigation is needed in addition to eIBRS.
+
+AMD RETBleed / SRSO / Branch Type Confusion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On AMD, poisoned RSB entries can also be created by the AMD RETBleed
+variant [#retbleed-paper]_ [#amd-btc]_ or by Speculative Return Stack
+Overflow [#amd-srso]_ (Inception [#inception-paper]_). The kernel
+protects itself by replacing every RET in the kernel with a branch to a
+single safe RET.
+
+----
+
+RSB underflow (Intel only)
+==========================
+
+RSB Alternate (RSBA) ("Intel Retbleed")
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some Intel Skylake-generation CPUs are susceptible to the Intel variant
+of RETBleed [#retbleed-paper]_ (Return Stack Buffer Underflow
+[#intel-rsbu]_). If a RET is executed when the RSB buffer is empty due
+to mismatched CALLs/RETs or returning from a deep call stack, the branch
+predictor can fall back to using the Branch Target Buffer (BTB). If a
+user forces a BTB collision then the RET can speculatively branch to a
+user-controlled address.
+
+* Note that RSB filling doesn't fully mitigate this issue. If there
+ are enough unbalanced RETs, the RSB may still underflow and fall back
+ to using a poisoned BTB entry.
+
+* On context switch, user->user underflow attacks are mitigated by the
+ conditional IBPB [#cond-ibpb]_ on context switch which effectively
+ clears the BTB:
+
+ * "The indirect branch predictor barrier (IBPB) is an indirect branch
+ control mechanism that establishes a barrier, preventing software
+ that executed before the barrier from controlling the predicted
+ targets of indirect branches executed after the barrier on the same
+ logical processor." [#intel-ibpb-btb]_
+
+* On context switch and VMEXIT, user->kernel and guest->host RSB
+ underflows are mitigated by IBRS or eIBRS:
+
+ * "Enabling IBRS (including enhanced IBRS) will mitigate the "RSBU"
+ attack demonstrated by the researchers. As previously documented,
+ Intel recommends the use of enhanced IBRS, where supported. This
+ includes any processor that enumerates RRSBA but not RRSBA_DIS_S."
+ [#intel-rsbu]_
+
+ However, note that eIBRS and IBRS do not mitigate intra-mode attacks.
+ Like RRSBA below, this is mitigated by clearing the BHB on kernel
+ entry.
+
+ As an alternative to classic IBRS, call depth tracking (combined with
+ retpolines) can be used to track kernel returns and fill the RSB when
+ it gets close to being empty.
+
+Restricted RSB Alternate (RRSBA)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some newer Intel CPUs have Restricted RSB Alternate (RRSBA) behavior,
+which, similar to RSBA described above, also falls back to using the BTB
+on RSB underflow. The only difference is that the predicted targets are
+restricted to the current domain when eIBRS is enabled:
+
+* "Restricted RSB Alternate (RRSBA) behavior allows alternate branch
+ predictors to be used by near RET instructions when the RSB is
+ empty. When eIBRS is enabled, the predicted targets of these
+ alternate predictors are restricted to those belonging to the
+ indirect branch predictor entries of the current prediction domain.
+ [#intel-eibrs-rrsba]_
+
+When a CPU with RRSBA is vulnerable to Branch History Injection
+[#bhi-paper]_ [#intel-bhi]_, an RSB underflow could be used for an
+intra-mode BTI attack. This is mitigated by clearing the BHB on
+kernel entry.
+
+However if the kernel uses retpolines instead of eIBRS, it needs to
+disable RRSBA:
+
+* "Where software is using retpoline as a mitigation for BHI or
+ intra-mode BTI, and the processor both enumerates RRSBA and
+ enumerates RRSBA_DIS controls, it should disable this behavior."
+ [#intel-retpoline-rrsba]_
+
+----
+
+References
+==========
+
+.. [#spectre-rsb] `Spectre Returns! Speculation Attacks using the Return Stack Buffer <https://arxiv.org/pdf/1807.07940.pdf>`_
+
+.. [#intel-rsb-filling] "Empty RSB Mitigation on Skylake-generation" in `Retpoline: A Branch Target Injection Mitigation <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/retpoline-branch-target-injection-mitigation.html#inpage-nav-5-1>`_
+
+.. [#amd-rsb-filling] "Mitigation V2-3" in `Software Techniques for Managing Speculation <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/software-techniques-for-managing-speculation.pdf>`_
+
+.. [#cond-ibpb] Whether IBPB is written depends on whether the prev and/or next task is protected from Spectre attacks. It typically requires opting in per task or system-wide. For more details see the documentation for the ``spectre_v2_user`` cmdline option in Documentation/admin-guide/kernel-parameters.txt.
+
+.. [#amd-sbpb] IBPB without flushing of branch type predictions. Only exists for AMD.
+
+.. [#amd-ibpb-rsb] "Function 8000_0008h -- Processor Capacity Parameters and Extended Feature Identification" in `AMD64 Architecture Programmer's Manual Volume 3: General-Purpose and System Instructions <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24594.pdf>`_. SBPB behaves the same way according to `this email <https://lore.kernel.org/5175b163a3736ca5fd01cedf406735636c99a>`_.
+
+.. [#amd-ibpb-no-rsb] `Spectre Attacks: Exploiting Speculative Execution <https://comsec.ethz.ch/wp-content/files/ibpb_sp25.pdf>`_
+
+.. [#intel-ibpb-rsb] "Introduction" in `Post-barrier Return Stack Buffer Predictions / CVE-2022-26373 / INTEL-SA-00706 <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/advisory-guidance/post-barrier-return-stack-buffer-predictions.html>`_
+
+.. [#amd-smep-rsb] "Existing Mitigations" in `Technical Guidance for Mitigating Branch Type Confusion <https://www.amd.com/content/dam/amd/en/documents/resources/technical-guidance-for-mitigating-branch-type-confusion.pdf>`_
+
+.. [#intel-smep-rsb] "Enhanced IBRS" in `Indirect Branch Restricted Speculation <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/indirect-branch-restricted-speculation.html>`_
+
+.. [#amd-eibrs-vmexit] "Extended Feature Enable Register (EFER)" in `AMD64 Architecture Programmer's Manual Volume 2: System Programming <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_
+
+.. [#intel-eibrs-vmexit] "Enhanced IBRS" in `Indirect Branch Restricted Speculation <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/indirect-branch-restricted-speculation.html>`_
+
+.. [#intel-pbrsb] `Post-barrier Return Stack Buffer Predictions / CVE-2022-26373 / INTEL-SA-00706 <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/advisory-guidance/post-barrier-return-stack-buffer-predictions.html>`_
+
+.. [#retbleed-paper] `RETBleed: Arbitrary Speculative Code Execution with Return Instruction <https://comsec.ethz.ch/wp-content/files/retbleed_sec22.pdf>`_
+
+.. [#amd-btc] `Technical Guidance for Mitigating Branch Type Confusion <https://www.amd.com/content/dam/amd/en/documents/resources/technical-guidance-for-mitigating-branch-type-confusion.pdf>`_
+
+.. [#amd-srso] `Technical Update Regarding Speculative Return Stack Overflow <https://www.amd.com/content/dam/amd/en/documents/corporate/cr/speculative-return-stack-overflow-whitepaper.pdf>`_
+
+.. [#inception-paper] `Inception: Exposing New Attack Surfaces with Training in Transient Execution <https://comsec.ethz.ch/wp-content/files/inception_sec23.pdf>`_
+
+.. [#intel-rsbu] `Return Stack Buffer Underflow / Return Stack Buffer Underflow / CVE-2022-29901, CVE-2022-28693 / INTEL-SA-00702 <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/advisory-guidance/return-stack-buffer-underflow.html>`_
+
+.. [#intel-ibpb-btb] `Indirect Branch Predictor Barrier' <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/indirect-branch-predictor-barrier.html>`_
+
+.. [#intel-eibrs-rrsba] "Guidance for RSBU" in `Return Stack Buffer Underflow / Return Stack Buffer Underflow / CVE-2022-29901, CVE-2022-28693 / INTEL-SA-00702 <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/advisory-guidance/return-stack-buffer-underflow.html>`_
+
+.. [#bhi-paper] `Branch History Injection: On the Effectiveness of Hardware Mitigations Against Cross-Privilege Spectre-v2 Attacks <http://download.vusec.net/papers/bhi-spectre-bhb_sec22.pdf>`_
+
+.. [#intel-bhi] `Branch History Injection and Intra-mode Branch Target Injection / CVE-2022-0001, CVE-2022-0002 / INTEL-SA-00598 <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/branch-history-injection.html>`_
+
+.. [#intel-retpoline-rrsba] "Retpoline" in `Branch History Injection and Intra-mode Branch Target Injection / CVE-2022-0001, CVE-2022-0002 / INTEL-SA-00598 <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/branch-history-injection.html>`_
diff --git a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
new file mode 100644
index 000000000000..966c9b3296ea
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
@@ -0,0 +1,150 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+SRBDS - Special Register Buffer Data Sampling
+=============================================
+
+SRBDS is a hardware vulnerability that allows MDS
+Documentation/admin-guide/hw-vuln/mds.rst techniques to
+infer values returned from special register accesses. Special register
+accesses are accesses to off core registers. According to Intel's evaluation,
+the special register reads that have a security expectation of privacy are
+RDRAND, RDSEED and SGX EGETKEY.
+
+When RDRAND, RDSEED and EGETKEY instructions are used, the data is moved
+to the core through the special register mechanism that is susceptible
+to MDS attacks.
+
+Affected processors
+-------------------
+Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may
+be affected.
+
+A processor is affected by SRBDS if its Family_Model and stepping is
+in the following list, with the exception of the listed processors
+exporting MDS_NO while Intel TSX is available yet not enabled. The
+latter class of processors are only affected when Intel TSX is enabled
+by software using TSX_CTRL_MSR otherwise they are not affected.
+
+ ============= ============ ========
+ common name Family_Model Stepping
+ ============= ============ ========
+ IvyBridge 06_3AH All
+
+ Haswell 06_3CH All
+ Haswell_L 06_45H All
+ Haswell_G 06_46H All
+
+ Broadwell_G 06_47H All
+ Broadwell 06_3DH All
+
+ Skylake_L 06_4EH All
+ Skylake 06_5EH All
+
+ Kabylake_L 06_8EH <= 0xC
+ Kabylake 06_9EH <= 0xD
+ ============= ============ ========
+
+Related CVEs
+------------
+
+The following CVE entry is related to this SRBDS issue:
+
+ ============== ===== =====================================
+ CVE-2020-0543 SRBDS Special Register Buffer Data Sampling
+ ============== ===== =====================================
+
+Attack scenarios
+----------------
+An unprivileged user can extract values returned from RDRAND and RDSEED
+executed on another core or sibling thread using MDS techniques.
+
+
+Mitigation mechanism
+--------------------
+Intel will release microcode updates that modify the RDRAND, RDSEED, and
+EGETKEY instructions to overwrite secret special register data in the shared
+staging buffer before the secret data can be accessed by another logical
+processor.
+
+During execution of the RDRAND, RDSEED, or EGETKEY instructions, off-core
+accesses from other logical processors will be delayed until the special
+register read is complete and the secret data in the shared staging buffer is
+overwritten.
+
+This has three effects on performance:
+
+#. RDRAND, RDSEED, or EGETKEY instructions have higher latency.
+
+#. Executing RDRAND at the same time on multiple logical processors will be
+ serialized, resulting in an overall reduction in the maximum RDRAND
+ bandwidth.
+
+#. Executing RDRAND, RDSEED or EGETKEY will delay memory accesses from other
+ logical processors that miss their core caches, with an impact similar to
+ legacy locked cache-line-split accesses.
+
+The microcode updates provide an opt-out mechanism (RNGDS_MITG_DIS) to disable
+the mitigation for RDRAND and RDSEED instructions executed outside of Intel
+Software Guard Extensions (Intel SGX) enclaves. On logical processors that
+disable the mitigation using this opt-out mechanism, RDRAND and RDSEED do not
+take longer to execute and do not impact performance of sibling logical
+processors memory accesses. The opt-out mechanism does not affect Intel SGX
+enclaves (including execution of RDRAND or RDSEED inside an enclave, as well
+as EGETKEY execution).
+
+IA32_MCU_OPT_CTRL MSR Definition
+--------------------------------
+Along with the mitigation for this issue, Intel added a new thread-scope
+IA32_MCU_OPT_CTRL MSR, (address 0x123). The presence of this MSR and
+RNGDS_MITG_DIS (bit 0) is enumerated by CPUID.(EAX=07H,ECX=0).EDX[SRBDS_CTRL =
+9]==1. This MSR is introduced through the microcode update.
+
+Setting IA32_MCU_OPT_CTRL[0] (RNGDS_MITG_DIS) to 1 for a logical processor
+disables the mitigation for RDRAND and RDSEED executed outside of an Intel SGX
+enclave on that logical processor. Opting out of the mitigation for a
+particular logical processor does not affect the RDRAND and RDSEED mitigations
+for other logical processors.
+
+Note that inside of an Intel SGX enclave, the mitigation is applied regardless
+of the value of RNGDS_MITG_DS.
+
+Mitigation control on the kernel command line
+---------------------------------------------
+The kernel command line allows control over the SRBDS mitigation at boot time
+with the option "srbds=". The option for this is:
+
+ ============= =============================================================
+ off This option disables SRBDS mitigation for RDRAND and RDSEED on
+ affected platforms.
+ ============= =============================================================
+
+SRBDS System Information
+------------------------
+The Linux kernel provides vulnerability status information through sysfs. For
+SRBDS this can be accessed by the following sysfs file:
+/sys/devices/system/cpu/vulnerabilities/srbds
+
+The possible values contained in this file are:
+
+ ============================== =============================================
+ Not affected Processor not vulnerable
+ Vulnerable Processor vulnerable and mitigation disabled
+ Vulnerable: No microcode Processor vulnerable and microcode is missing
+ mitigation
+ Mitigation: Microcode Processor is vulnerable and mitigation is in
+ effect.
+ Mitigation: TSX disabled Processor is only vulnerable when TSX is
+ enabled while this system was booted with TSX
+ disabled.
+ Unknown: Dependent on
+ hypervisor status Running on virtual guest processor that is
+ affected but with no way to know if host
+ processor is mitigated or vulnerable.
+ ============================== =============================================
+
+SRBDS Default mitigation
+------------------------
+This new microcode serializes processor access during execution of RDRAND,
+RDSEED ensures that the shared buffer is overwritten before it is released for
+reuse. Use the "srbds=off" kernel command line to disable the mitigation for
+RDRAND and RDSEED.
diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst
new file mode 100644
index 000000000000..4bb8549bee82
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/spectre.rst
@@ -0,0 +1,725 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Spectre Side Channels
+=====================
+
+Spectre is a class of side channel attacks that exploit branch prediction
+and speculative execution on modern CPUs to read memory, possibly
+bypassing access controls. Speculative execution side channel exploits
+do not modify memory but attempt to infer privileged data in the memory.
+
+This document covers Spectre variant 1 and Spectre variant 2.
+
+Affected processors
+-------------------
+
+Speculative execution side channel methods affect a wide range of modern
+high performance processors, since most modern high speed processors
+use branch prediction and speculative execution.
+
+The following CPUs are vulnerable:
+
+ - Intel Core, Atom, Pentium, and Xeon processors
+
+ - AMD Phenom, EPYC, and Zen processors
+
+ - IBM POWER and zSeries processors
+
+ - Higher end ARM processors
+
+ - Apple CPUs
+
+ - Higher end MIPS CPUs
+
+ - Likely most other high performance CPUs. Contact your CPU vendor for details.
+
+Whether a processor is affected or not can be read out from the Spectre
+vulnerability files in sysfs. See :ref:`spectre_sys_info`.
+
+Related CVEs
+------------
+
+The following CVE entries describe Spectre variants:
+
+ ============= ======================= ==========================
+ CVE-2017-5753 Bounds check bypass Spectre variant 1
+ CVE-2017-5715 Branch target injection Spectre variant 2
+ CVE-2019-1125 Spectre v1 swapgs Spectre variant 1 (swapgs)
+ ============= ======================= ==========================
+
+Problem
+-------
+
+CPUs use speculative operations to improve performance. That may leave
+traces of memory accesses or computations in the processor's caches,
+buffers, and branch predictors. Malicious software may be able to
+influence the speculative execution paths, and then use the side effects
+of the speculative execution in the CPUs' caches and buffers to infer
+privileged data touched during the speculative execution.
+
+Spectre variant 1 attacks take advantage of speculative execution of
+conditional branches, while Spectre variant 2 attacks use speculative
+execution of indirect branches to leak privileged memory.
+See :ref:`[1] <spec_ref1>` :ref:`[5] <spec_ref5>` :ref:`[6] <spec_ref6>`
+:ref:`[7] <spec_ref7>` :ref:`[10] <spec_ref10>` :ref:`[11] <spec_ref11>`.
+
+Spectre variant 1 (Bounds Check Bypass)
+---------------------------------------
+
+The bounds check bypass attack :ref:`[2] <spec_ref2>` takes advantage
+of speculative execution that bypasses conditional branch instructions
+used for memory access bounds check (e.g. checking if the index of an
+array results in memory access within a valid range). This results in
+memory accesses to invalid memory (with out-of-bound index) that are
+done speculatively before validation checks resolve. Such speculative
+memory accesses can leave side effects, creating side channels which
+leak information to the attacker.
+
+There are some extensions of Spectre variant 1 attacks for reading data
+over the network, see :ref:`[12] <spec_ref12>`. However such attacks
+are difficult, low bandwidth, fragile, and are considered low risk.
+
+Note that, despite "Bounds Check Bypass" name, Spectre variant 1 is not
+only about user-controlled array bounds checks. It can affect any
+conditional checks. The kernel entry code interrupt, exception, and NMI
+handlers all have conditional swapgs checks. Those may be problematic
+in the context of Spectre v1, as kernel code can speculatively run with
+a user GS.
+
+Spectre variant 2 (Branch Target Injection)
+-------------------------------------------
+
+The branch target injection attack takes advantage of speculative
+execution of indirect branches :ref:`[3] <spec_ref3>`. The indirect
+branch predictors inside the processor used to guess the target of
+indirect branches can be influenced by an attacker, causing gadget code
+to be speculatively executed, thus exposing sensitive data touched by
+the victim. The side effects left in the CPU's caches during speculative
+execution can be measured to infer data values.
+
+.. _poison_btb:
+
+In Spectre variant 2 attacks, the attacker can steer speculative indirect
+branches in the victim to gadget code by poisoning the branch target
+buffer of a CPU used for predicting indirect branch addresses. Such
+poisoning could be done by indirect branching into existing code,
+with the address offset of the indirect branch under the attacker's
+control. Since the branch prediction on impacted hardware does not
+fully disambiguate branch address and uses the offset for prediction,
+this could cause privileged code's indirect branch to jump to a gadget
+code with the same offset.
+
+The most useful gadgets take an attacker-controlled input parameter (such
+as a register value) so that the memory read can be controlled. Gadgets
+without input parameters might be possible, but the attacker would have
+very little control over what memory can be read, reducing the risk of
+the attack revealing useful data.
+
+One other variant 2 attack vector is for the attacker to poison the
+return stack buffer (RSB) :ref:`[13] <spec_ref13>` to cause speculative
+subroutine return instruction execution to go to a gadget. An attacker's
+imbalanced subroutine call instructions might "poison" entries in the
+return stack buffer which are later consumed by a victim's subroutine
+return instructions. This attack can be mitigated by flushing the return
+stack buffer on context switch, or virtual machine (VM) exit.
+
+On systems with simultaneous multi-threading (SMT), attacks are possible
+from the sibling thread, as level 1 cache and branch target buffer
+(BTB) may be shared between hardware threads in a CPU core. A malicious
+program running on the sibling thread may influence its peer's BTB to
+steer its indirect branch speculations to gadget code, and measure the
+speculative execution's side effects left in level 1 cache to infer the
+victim's data.
+
+Yet another variant 2 attack vector is for the attacker to poison the
+Branch History Buffer (BHB) to speculatively steer an indirect branch
+to a specific Branch Target Buffer (BTB) entry, even if the entry isn't
+associated with the source address of the indirect branch. Specifically,
+the BHB might be shared across privilege levels even in the presence of
+Enhanced IBRS.
+
+Previously the only known real-world BHB attack vector was via unprivileged
+eBPF. Further research has found attacks that don't require unprivileged eBPF.
+For a full mitigation against BHB attacks it is recommended to set BHI_DIS_S or
+use the BHB clearing sequence.
+
+Attack scenarios
+----------------
+
+The following list of attack scenarios have been anticipated, but may
+not cover all possible attack vectors.
+
+1. A user process attacking the kernel
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Spectre variant 1
+~~~~~~~~~~~~~~~~~
+
+ The attacker passes a parameter to the kernel via a register or
+ via a known address in memory during a syscall. Such parameter may
+ be used later by the kernel as an index to an array or to derive
+ a pointer for a Spectre variant 1 attack. The index or pointer
+ is invalid, but bound checks are bypassed in the code branch taken
+ for speculative execution. This could cause privileged memory to be
+ accessed and leaked.
+
+ For kernel code that has been identified where data pointers could
+ potentially be influenced for Spectre attacks, new "nospec" accessor
+ macros are used to prevent speculative loading of data.
+
+Spectre variant 1 (swapgs)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ An attacker can train the branch predictor to speculatively skip the
+ swapgs path for an interrupt or exception. If they initialize
+ the GS register to a user-space value, if the swapgs is speculatively
+ skipped, subsequent GS-related percpu accesses in the speculation
+ window will be done with the attacker-controlled GS value. This
+ could cause privileged memory to be accessed and leaked.
+
+ For example:
+
+ ::
+
+ if (coming from user space)
+ swapgs
+ mov %gs:<percpu_offset>, %reg
+ mov (%reg), %reg1
+
+ When coming from user space, the CPU can speculatively skip the
+ swapgs, and then do a speculative percpu load using the user GS
+ value. So the user can speculatively force a read of any kernel
+ value. If a gadget exists which uses the percpu value as an address
+ in another load/store, then the contents of the kernel value may
+ become visible via an L1 side channel attack.
+
+ A similar attack exists when coming from kernel space. The CPU can
+ speculatively do the swapgs, causing the user GS to get used for the
+ rest of the speculative window.
+
+Spectre variant 2
+~~~~~~~~~~~~~~~~~
+
+ A spectre variant 2 attacker can :ref:`poison <poison_btb>` the branch
+ target buffer (BTB) before issuing syscall to launch an attack.
+ After entering the kernel, the kernel could use the poisoned branch
+ target buffer on indirect jump and jump to gadget code in speculative
+ execution.
+
+ If an attacker tries to control the memory addresses leaked during
+ speculative execution, he would also need to pass a parameter to the
+ gadget, either through a register or a known address in memory. After
+ the gadget has executed, he can measure the side effect.
+
+ The kernel can protect itself against consuming poisoned branch
+ target buffer entries by using return trampolines (also known as
+ "retpoline") :ref:`[3] <spec_ref3>` :ref:`[9] <spec_ref9>` for all
+ indirect branches. Return trampolines trap speculative execution paths
+ to prevent jumping to gadget code during speculative execution.
+ x86 CPUs with Enhanced Indirect Branch Restricted Speculation
+ (Enhanced IBRS) available in hardware should use the feature to
+ mitigate Spectre variant 2 instead of retpoline. Enhanced IBRS is
+ more efficient than retpoline.
+
+ There may be gadget code in firmware which could be exploited with
+ Spectre variant 2 attack by a rogue user process. To mitigate such
+ attacks on x86, Indirect Branch Restricted Speculation (IBRS) feature
+ is turned on before the kernel invokes any firmware code.
+
+2. A user process attacking another user process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ A malicious user process can try to attack another user process,
+ either via a context switch on the same hardware thread, or from the
+ sibling hyperthread sharing a physical processor core on simultaneous
+ multi-threading (SMT) system.
+
+ Spectre variant 1 attacks generally require passing parameters
+ between the processes, which needs a data passing relationship, such
+ as remote procedure calls (RPC). Those parameters are used in gadget
+ code to derive invalid data pointers accessing privileged memory in
+ the attacked process.
+
+ Spectre variant 2 attacks can be launched from a rogue process by
+ :ref:`poisoning <poison_btb>` the branch target buffer. This can
+ influence the indirect branch targets for a victim process that either
+ runs later on the same hardware thread, or running concurrently on
+ a sibling hardware thread sharing the same physical core.
+
+ A user process can protect itself against Spectre variant 2 attacks
+ by using the prctl() syscall to disable indirect branch speculation
+ for itself. An administrator can also cordon off an unsafe process
+ from polluting the branch target buffer by disabling the process's
+ indirect branch speculation. This comes with a performance cost
+ from not using indirect branch speculation and clearing the branch
+ target buffer. When SMT is enabled on x86, for a process that has
+ indirect branch speculation disabled, Single Threaded Indirect Branch
+ Predictors (STIBP) :ref:`[4] <spec_ref4>` are turned on to prevent the
+ sibling thread from controlling branch target buffer. In addition,
+ the Indirect Branch Prediction Barrier (IBPB) is issued to clear the
+ branch target buffer when context switching to and from such process.
+
+ On x86, the return stack buffer is stuffed on context switch.
+ This prevents the branch target buffer from being used for branch
+ prediction when the return stack buffer underflows while switching to
+ a deeper call stack. Any poisoned entries in the return stack buffer
+ left by the previous process will also be cleared.
+
+ User programs should use address space randomization to make attacks
+ more difficult (Set /proc/sys/kernel/randomize_va_space = 1 or 2).
+
+3. A virtualized guest attacking the host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ The attack mechanism is similar to how user processes attack the
+ kernel. The kernel is entered via hyper-calls or other virtualization
+ exit paths.
+
+ For Spectre variant 1 attacks, rogue guests can pass parameters
+ (e.g. in registers) via hyper-calls to derive invalid pointers to
+ speculate into privileged memory after entering the kernel. For places
+ where such kernel code has been identified, nospec accessor macros
+ are used to stop speculative memory access.
+
+ For Spectre variant 2 attacks, rogue guests can :ref:`poison
+ <poison_btb>` the branch target buffer or return stack buffer, causing
+ the kernel to jump to gadget code in the speculative execution paths.
+
+ To mitigate variant 2, the host kernel can use return trampolines
+ for indirect branches to bypass the poisoned branch target buffer,
+ and flushing the return stack buffer on VM exit. This prevents rogue
+ guests from affecting indirect branching in the host kernel.
+
+ To protect host processes from rogue guests, host processes can have
+ indirect branch speculation disabled via prctl(). The branch target
+ buffer is cleared before context switching to such processes.
+
+4. A virtualized guest attacking other guest
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ A rogue guest may attack another guest to get data accessible by the
+ other guest.
+
+ Spectre variant 1 attacks are possible if parameters can be passed
+ between guests. This may be done via mechanisms such as shared memory
+ or message passing. Such parameters could be used to derive data
+ pointers to privileged data in guest. The privileged data could be
+ accessed by gadget code in the victim's speculation paths.
+
+ Spectre variant 2 attacks can be launched from a rogue guest by
+ :ref:`poisoning <poison_btb>` the branch target buffer or the return
+ stack buffer. Such poisoned entries could be used to influence
+ speculation execution paths in the victim guest.
+
+ Linux kernel mitigates attacks to other guests running in the same
+ CPU hardware thread by flushing the return stack buffer on VM exit,
+ and clearing the branch target buffer before switching to a new guest.
+
+ If SMT is used, Spectre variant 2 attacks from an untrusted guest
+ in the sibling hyperthread can be mitigated by the administrator,
+ by turning off the unsafe guest's indirect branch speculation via
+ prctl(). A guest can also protect itself by turning on microcode
+ based mitigations (such as IBPB or STIBP on x86) within the guest.
+
+.. _spectre_sys_info:
+
+Spectre system information
+--------------------------
+
+The Linux kernel provides a sysfs interface to enumerate the current
+mitigation status of the system for Spectre: whether the system is
+vulnerable, and which mitigations are active.
+
+The sysfs file showing Spectre variant 1 mitigation status is:
+
+ /sys/devices/system/cpu/vulnerabilities/spectre_v1
+
+The possible values in this file are:
+
+ .. list-table::
+
+ * - 'Not affected'
+ - The processor is not vulnerable.
+ * - 'Vulnerable: __user pointer sanitization and usercopy barriers only; no swapgs barriers'
+ - The swapgs protections are disabled; otherwise it has
+ protection in the kernel on a case by case base with explicit
+ pointer sanitation and usercopy LFENCE barriers.
+ * - 'Mitigation: usercopy/swapgs barriers and __user pointer sanitization'
+ - Protection in the kernel on a case by case base with explicit
+ pointer sanitation, usercopy LFENCE barriers, and swapgs LFENCE
+ barriers.
+
+However, the protections are put in place on a case by case basis,
+and there is no guarantee that all possible attack vectors for Spectre
+variant 1 are covered.
+
+The spectre_v2 kernel file reports if the kernel has been compiled with
+retpoline mitigation or if the CPU has hardware mitigation, and if the
+CPU has support for additional process-specific mitigation.
+
+This file also reports CPU features enabled by microcode to mitigate
+attack between user processes:
+
+1. Indirect Branch Prediction Barrier (IBPB) to add additional
+ isolation between processes of different users.
+2. Single Thread Indirect Branch Predictors (STIBP) to add additional
+ isolation between CPU threads running on the same core.
+
+These CPU features may impact performance when used and can be enabled
+per process on a case-by-case base.
+
+The sysfs file showing Spectre variant 2 mitigation status is:
+
+ /sys/devices/system/cpu/vulnerabilities/spectre_v2
+
+The possible values in this file are:
+
+ - Kernel status:
+
+ ======================================== =================================
+ 'Not affected' The processor is not vulnerable
+ 'Mitigation: None' Vulnerable, no mitigation
+ 'Mitigation: Retpolines' Use Retpoline thunks
+ 'Mitigation: LFENCE' Use LFENCE instructions
+ 'Mitigation: Enhanced IBRS' Hardware-focused mitigation
+ 'Mitigation: Enhanced IBRS + Retpolines' Hardware-focused + Retpolines
+ 'Mitigation: Enhanced IBRS + LFENCE' Hardware-focused + LFENCE
+ ======================================== =================================
+
+ - Firmware status: Show if Indirect Branch Restricted Speculation (IBRS) is
+ used to protect against Spectre variant 2 attacks when calling firmware (x86 only).
+
+ ========== =============================================================
+ 'IBRS_FW' Protection against user program attacks when calling firmware
+ ========== =============================================================
+
+ - Indirect branch prediction barrier (IBPB) status for protection between
+ processes of different users. This feature can be controlled through
+ prctl() per process, or through kernel command line options. This is
+ an x86 only feature. For more details see below.
+
+ =================== ========================================================
+ 'IBPB: disabled' IBPB unused
+ 'IBPB: always-on' Use IBPB on all tasks
+ 'IBPB: conditional' Use IBPB on SECCOMP or indirect branch restricted tasks
+ =================== ========================================================
+
+ - Single threaded indirect branch prediction (STIBP) status for protection
+ between different hyper threads. This feature can be controlled through
+ prctl per process, or through kernel command line options. This is an x86
+ only feature. For more details see below.
+
+ ==================== ========================================================
+ 'STIBP: disabled' STIBP unused
+ 'STIBP: forced' Use STIBP on all tasks
+ 'STIBP: conditional' Use STIBP on SECCOMP or indirect branch restricted tasks
+ ==================== ========================================================
+
+ - Return stack buffer (RSB) protection status:
+
+ ============= ===========================================
+ 'RSB filling' Protection of RSB on context switch enabled
+ ============= ===========================================
+
+ - EIBRS Post-barrier Return Stack Buffer (PBRSB) protection status:
+
+ =========================== =======================================================
+ 'PBRSB-eIBRS: SW sequence' CPU is affected and protection of RSB on VMEXIT enabled
+ 'PBRSB-eIBRS: Vulnerable' CPU is vulnerable
+ 'PBRSB-eIBRS: Not affected' CPU is not affected by PBRSB
+ =========================== =======================================================
+
+ - Branch History Injection (BHI) protection status:
+
+.. list-table::
+
+ * - BHI: Not affected
+ - System is not affected
+ * - BHI: Retpoline
+ - System is protected by retpoline
+ * - BHI: BHI_DIS_S
+ - System is protected by BHI_DIS_S
+ * - BHI: SW loop, KVM SW loop
+ - System is protected by software clearing sequence
+ * - BHI: Vulnerable
+ - System is vulnerable to BHI
+ * - BHI: Vulnerable, KVM: SW loop
+ - System is vulnerable; KVM is protected by software clearing sequence
+
+Full mitigation might require a microcode update from the CPU
+vendor. When the necessary microcode is not available, the kernel will
+report vulnerability.
+
+Turning on mitigation for Spectre variant 1 and Spectre variant 2
+-----------------------------------------------------------------
+
+1. Kernel mitigation
+^^^^^^^^^^^^^^^^^^^^
+
+Spectre variant 1
+~~~~~~~~~~~~~~~~~
+
+ For the Spectre variant 1, vulnerable kernel code (as determined
+ by code audit or scanning tools) is annotated on a case by case
+ basis to use nospec accessor macros for bounds clipping :ref:`[2]
+ <spec_ref2>` to avoid any usable disclosure gadgets. However, it may
+ not cover all attack vectors for Spectre variant 1.
+
+ Copy-from-user code has an LFENCE barrier to prevent the access_ok()
+ check from being mis-speculated. The barrier is done by the
+ barrier_nospec() macro.
+
+ For the swapgs variant of Spectre variant 1, LFENCE barriers are
+ added to interrupt, exception and NMI entry where needed. These
+ barriers are done by the FENCE_SWAPGS_KERNEL_ENTRY and
+ FENCE_SWAPGS_USER_ENTRY macros.
+
+Spectre variant 2
+~~~~~~~~~~~~~~~~~
+
+ For Spectre variant 2 mitigation, the compiler turns indirect calls or
+ jumps in the kernel into equivalent return trampolines (retpolines)
+ :ref:`[3] <spec_ref3>` :ref:`[9] <spec_ref9>` to go to the target
+ addresses. Speculative execution paths under retpolines are trapped
+ in an infinite loop to prevent any speculative execution jumping to
+ a gadget.
+
+ To turn on retpoline mitigation on a vulnerable CPU, the kernel
+ needs to be compiled with a gcc compiler that supports the
+ -mindirect-branch=thunk-extern -mindirect-branch-register options.
+ If the kernel is compiled with a Clang compiler, the compiler needs
+ to support -mretpoline-external-thunk option. The kernel config
+ CONFIG_MITIGATION_RETPOLINE needs to be turned on, and the CPU needs
+ to run with the latest updated microcode.
+
+ On Intel Skylake-era systems the mitigation covers most, but not all,
+ cases. See :ref:`[3] <spec_ref3>` for more details.
+
+ On CPUs with hardware mitigation for Spectre variant 2 (e.g. IBRS
+ or enhanced IBRS on x86), retpoline is automatically disabled at run time.
+
+ Systems which support enhanced IBRS (eIBRS) enable IBRS protection once at
+ boot, by setting the IBRS bit, and they're automatically protected against
+ some Spectre v2 variant attacks. The BHB can still influence the choice of
+ indirect branch predictor entry, and although branch predictor entries are
+ isolated between modes when eIBRS is enabled, the BHB itself is not isolated
+ between modes. Systems which support BHI_DIS_S will set it to protect against
+ BHI attacks.
+
+ On Intel's enhanced IBRS systems, this includes cross-thread branch target
+ injections on SMT systems (STIBP). In other words, Intel eIBRS enables
+ STIBP, too.
+
+ AMD Automatic IBRS does not protect userspace, and Legacy IBRS systems clear
+ the IBRS bit on exit to userspace, therefore both explicitly enable STIBP.
+
+ The retpoline mitigation is turned on by default on vulnerable
+ CPUs. It can be forced on or off by the administrator
+ via the kernel command line and sysfs control files. See
+ :ref:`spectre_mitigation_control_command_line`.
+
+ On x86, indirect branch restricted speculation is turned on by default
+ before invoking any firmware code to prevent Spectre variant 2 exploits
+ using the firmware.
+
+ Using kernel address space randomization (CONFIG_RANDOMIZE_BASE=y
+ and CONFIG_SLAB_FREELIST_RANDOM=y in the kernel configuration) makes
+ attacks on the kernel generally more difficult.
+
+2. User program mitigation
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ User programs can mitigate Spectre variant 1 using LFENCE or "bounds
+ clipping". For more details see :ref:`[2] <spec_ref2>`.
+
+ For Spectre variant 2 mitigation, individual user programs
+ can be compiled with return trampolines for indirect branches.
+ This protects them from consuming poisoned entries in the branch
+ target buffer left by malicious software.
+
+ On legacy IBRS systems, at return to userspace, implicit STIBP is disabled
+ because the kernel clears the IBRS bit. In this case, the userspace programs
+ can disable indirect branch speculation via prctl() (See
+ :ref:`Documentation/userspace-api/spec_ctrl.rst <set_spec_ctrl>`).
+ On x86, this will turn on STIBP to guard against attacks from the
+ sibling thread when the user program is running, and use IBPB to
+ flush the branch target buffer when switching to/from the program.
+
+ Restricting indirect branch speculation on a user program will
+ also prevent the program from launching a variant 2 attack
+ on x86. Administrators can change that behavior via the kernel
+ command line and sysfs control files.
+ See :ref:`spectre_mitigation_control_command_line`.
+
+ Programs that disable their indirect branch speculation will have
+ more overhead and run slower.
+
+ User programs should use address space randomization
+ (/proc/sys/kernel/randomize_va_space = 1 or 2) to make attacks more
+ difficult.
+
+3. VM mitigation
+^^^^^^^^^^^^^^^^
+
+ Within the kernel, Spectre variant 1 attacks from rogue guests are
+ mitigated on a case by case basis in VM exit paths. Vulnerable code
+ uses nospec accessor macros for "bounds clipping", to avoid any
+ usable disclosure gadgets. However, this may not cover all variant
+ 1 attack vectors.
+
+ For Spectre variant 2 attacks from rogue guests to the kernel, the
+ Linux kernel uses retpoline or Enhanced IBRS to prevent consumption of
+ poisoned entries in branch target buffer left by rogue guests. It also
+ flushes the return stack buffer on every VM exit to prevent a return
+ stack buffer underflow so poisoned branch target buffer could be used,
+ or attacker guests leaving poisoned entries in the return stack buffer.
+
+ To mitigate guest-to-guest attacks in the same CPU hardware thread,
+ the branch target buffer is sanitized by flushing before switching
+ to a new guest on a CPU.
+
+ The above mitigations are turned on by default on vulnerable CPUs.
+
+ To mitigate guest-to-guest attacks from sibling thread when SMT is
+ in use, an untrusted guest running in the sibling thread can have
+ its indirect branch speculation disabled by administrator via prctl().
+
+ The kernel also allows guests to use any microcode based mitigation
+ they choose to use (such as IBPB or STIBP on x86) to protect themselves.
+
+.. _spectre_mitigation_control_command_line:
+
+Mitigation control on the kernel command line
+---------------------------------------------
+
+In general the kernel selects reasonable default mitigations for the
+current CPU.
+
+Spectre default mitigations can be disabled or changed at the kernel
+command line with the following options:
+
+ - nospectre_v1
+ - nospectre_v2
+ - spectre_v2={option}
+ - spectre_v2_user={option}
+ - spectre_bhi={option}
+
+For more details on the available options, refer to Documentation/admin-guide/kernel-parameters.txt
+
+Mitigation selection guide
+--------------------------
+
+1. Trusted userspace
+^^^^^^^^^^^^^^^^^^^^
+
+ If all userspace applications are from trusted sources and do not
+ execute externally supplied untrusted code, then the mitigations can
+ be disabled.
+
+2. Protect sensitive programs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ For security-sensitive programs that have secrets (e.g. crypto
+ keys), protection against Spectre variant 2 can be put in place by
+ disabling indirect branch speculation when the program is running
+ (See :ref:`Documentation/userspace-api/spec_ctrl.rst <set_spec_ctrl>`).
+
+3. Sandbox untrusted programs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Untrusted programs that could be a source of attacks can be cordoned
+ off by disabling their indirect branch speculation when they are run
+ (See :ref:`Documentation/userspace-api/spec_ctrl.rst <set_spec_ctrl>`).
+ This prevents untrusted programs from polluting the branch target
+ buffer. This behavior can be changed via the kernel command line
+ and sysfs control files. See
+ :ref:`spectre_mitigation_control_command_line`.
+
+3. High security mode
+^^^^^^^^^^^^^^^^^^^^^
+
+ All Spectre variant 2 mitigations can be forced on
+ at boot time for all programs (See the "on" option in
+ :ref:`spectre_mitigation_control_command_line`). This will add
+ overhead as indirect branch speculations for all programs will be
+ restricted.
+
+ On x86, branch target buffer will be flushed with IBPB when switching
+ to a new program. STIBP is left on all the time to protect programs
+ against variant 2 attacks originating from programs running on
+ sibling threads.
+
+ Alternatively, STIBP can be used only when running programs
+ whose indirect branch speculation is explicitly disabled,
+ while IBPB is still used all the time when switching to a new
+ program to clear the branch target buffer (See "ibpb" option in
+ :ref:`spectre_mitigation_control_command_line`). This "ibpb" option
+ has less performance cost than the "on" option, which leaves STIBP
+ on all the time.
+
+References on Spectre
+---------------------
+
+Intel white papers:
+
+.. _spec_ref1:
+
+[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:
+
+[2] `Bounds check bypass <https://software.intel.com/security-software-guidance/software-guidance/bounds-check-bypass>`_.
+
+.. _spec_ref3:
+
+[3] `Deep dive: Retpoline: A branch target injection mitigation <https://software.intel.com/security-software-guidance/insights/deep-dive-retpoline-branch-target-injection-mitigation>`_.
+
+.. _spec_ref4:
+
+[4] `Deep Dive: Single Thread Indirect Branch Predictors <https://software.intel.com/security-software-guidance/insights/deep-dive-single-thread-indirect-branch-predictors>`_.
+
+AMD white papers:
+
+.. _spec_ref5:
+
+[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:
+
+[6] `Software techniques for managing speculation on AMD processors <https://developer.amd.com/wp-content/resources/Managing-Speculation-on-AMD-Processors.pdf>`_.
+
+ARM white papers:
+
+.. _spec_ref7:
+
+[7] `Cache speculation side-channels <https://developer.arm.com/support/arm-security-updates/speculative-processor-vulnerability/download-the-whitepaper>`_.
+
+.. _spec_ref8:
+
+[8] `Cache speculation issues update <https://developer.arm.com/support/arm-security-updates/speculative-processor-vulnerability/latest-updates/cache-speculation-issues-update>`_.
+
+Google white paper:
+
+.. _spec_ref9:
+
+[9] `Retpoline: a software construct for preventing branch-target-injection <https://support.google.com/faqs/answer/7625886>`_.
+
+MIPS white paper:
+
+.. _spec_ref10:
+
+[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:
+
+.. _spec_ref11:
+
+[11] `Spectre Attacks: Exploiting Speculative Execution <https://spectreattack.com/spectre.pdf>`_.
+
+.. _spec_ref12:
+
+[12] `NetSpectre: Read Arbitrary Memory over Network <https://arxiv.org/abs/1807.10535>`_.
+
+.. _spec_ref13:
+
+[13] `Spectre Returns! Speculation Attacks using the Return Stack Buffer <https://www.usenix.org/system/files/conference/woot18/woot18-paper-koruyeh.pdf>`_.
diff --git a/Documentation/admin-guide/hw-vuln/srso.rst b/Documentation/admin-guide/hw-vuln/srso.rst
new file mode 100644
index 000000000000..66af95251a3d
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/srso.rst
@@ -0,0 +1,242 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Speculative Return Stack Overflow (SRSO)
+========================================
+
+This is a mitigation for the speculative return stack overflow (SRSO)
+vulnerability found on AMD processors. The mechanism is by now the well
+known scenario of poisoning CPU functional units - the Branch Target
+Buffer (BTB) and Return Address Predictor (RAP) in this case - and then
+tricking the elevated privilege domain (the kernel) into leaking
+sensitive data.
+
+AMD CPUs predict RET instructions using a Return Address Predictor (aka
+Return Address Stack/Return Stack Buffer). In some cases, a non-architectural
+CALL instruction (i.e., an instruction predicted to be a CALL but is
+not actually a CALL) can create an entry in the RAP which may be used
+to predict the target of a subsequent RET instruction.
+
+The specific circumstances that lead to this varies by microarchitecture
+but the concern is that an attacker can mis-train the CPU BTB to predict
+non-architectural CALL instructions in kernel space and use this to
+control the speculative target of a subsequent kernel RET, potentially
+leading to information disclosure via a speculative side-channel.
+
+The issue is tracked under CVE-2023-20569.
+
+Affected processors
+-------------------
+
+AMD Zen, generations 1-4. That is, all families 0x17 and 0x19. Older
+processors have not been investigated.
+
+System information and options
+------------------------------
+
+First of all, it is required that the latest microcode be loaded for
+mitigations to be effective.
+
+The sysfs file showing SRSO mitigation status is:
+
+ /sys/devices/system/cpu/vulnerabilities/spec_rstack_overflow
+
+The possible values in this file are:
+
+ * 'Not affected':
+
+ The processor is not vulnerable
+
+* 'Vulnerable':
+
+ The processor is vulnerable and no mitigations have been applied.
+
+ * 'Vulnerable: No microcode':
+
+ The processor is vulnerable, no microcode extending IBPB
+ functionality to address the vulnerability has been applied.
+
+ * 'Vulnerable: Safe RET, no microcode':
+
+ The "Safe RET" mitigation (see below) has been applied to protect the
+ kernel, but the IBPB-extending microcode has not been applied. User
+ space tasks may still be vulnerable.
+
+ * 'Vulnerable: Microcode, no safe RET':
+
+ Extended IBPB functionality microcode patch has been applied. It does
+ not address User->Kernel and Guest->Host transitions protection but it
+ does address User->User and VM->VM attack vectors.
+
+ Note that User->User mitigation is controlled by how the IBPB aspect in
+ the Spectre v2 mitigation is selected:
+
+ * conditional IBPB:
+
+ where each process can select whether it needs an IBPB issued
+ around it PR_SPEC_DISABLE/_ENABLE etc, see :doc:`spectre`
+
+ * strict:
+
+ i.e., always on - by supplying spectre_v2_user=on on the kernel
+ command line
+
+ (spec_rstack_overflow=microcode)
+
+ * 'Mitigation: Safe RET':
+
+ Combined microcode/software mitigation. It complements the
+ extended IBPB microcode patch functionality by addressing
+ User->Kernel and Guest->Host transitions protection.
+
+ Selected by default or by spec_rstack_overflow=safe-ret
+
+ * 'Mitigation: IBPB':
+
+ Similar protection as "safe RET" above but employs an IBPB barrier on
+ privilege domain crossings (User->Kernel, Guest->Host).
+
+ (spec_rstack_overflow=ibpb)
+
+ * 'Mitigation: IBPB on VMEXIT':
+
+ Mitigation addressing the cloud provider scenario - the Guest->Host
+ transitions only.
+
+ (spec_rstack_overflow=ibpb-vmexit)
+
+ * 'Mitigation: Reduced Speculation':
+
+ This mitigation gets automatically enabled when the above one "IBPB on
+ VMEXIT" has been selected and the CPU supports the BpSpecReduce bit.
+
+ It gets automatically enabled on machines which have the
+ SRSO_USER_KERNEL_NO=1 CPUID bit. In that case, the code logic is to switch
+ to the above =ibpb-vmexit mitigation because the user/kernel boundary is
+ not affected anymore and thus "safe RET" is not needed.
+
+ After enabling the IBPB on VMEXIT mitigation option, the BpSpecReduce bit
+ is detected (functionality present on all such machines) and that
+ practically overrides IBPB on VMEXIT as it has a lot less performance
+ impact and takes care of the guest->host attack vector too.
+
+In order to exploit vulnerability, an attacker needs to:
+
+ - gain local access on the machine
+
+ - break kASLR
+
+ - find gadgets in the running kernel in order to use them in the exploit
+
+ - potentially create and pin an additional workload on the sibling
+ thread, depending on the microarchitecture (not necessary on fam 0x19)
+
+ - run the exploit
+
+Considering the performance implications of each mitigation type, the
+default one is 'Mitigation: safe RET' which should take care of most
+attack vectors, including the local User->Kernel one.
+
+As always, the user is advised to keep her/his system up-to-date by
+applying software updates regularly.
+
+The default setting will be reevaluated when needed and especially when
+new attack vectors appear.
+
+As one can surmise, 'Mitigation: safe RET' does come at the cost of some
+performance depending on the workload. If one trusts her/his userspace
+and does not want to suffer the performance impact, one can always
+disable the mitigation with spec_rstack_overflow=off.
+
+Similarly, 'Mitigation: IBPB' is another full mitigation type employing
+an indirect branch prediction barrier after having applied the required
+microcode patch for one's system. This mitigation comes also at
+a performance cost.
+
+Mitigation: Safe RET
+--------------------
+
+The mitigation works by ensuring all RET instructions speculate to
+a controlled location, similar to how speculation is controlled in the
+retpoline sequence. To accomplish this, the __x86_return_thunk forces
+the CPU to mispredict every function return using a 'safe return'
+sequence.
+
+To ensure the safety of this mitigation, the kernel must ensure that the
+safe return sequence is itself free from attacker interference. In Zen3
+and Zen4, this is accomplished by creating a BTB alias between the
+untraining function srso_alias_untrain_ret() and the safe return
+function srso_alias_safe_ret() which results in evicting a potentially
+poisoned BTB entry and using that safe one for all function returns.
+
+In older Zen1 and Zen2, this is accomplished using a reinterpretation
+technique similar to Retbleed one: srso_untrain_ret() and
+srso_safe_ret().
+
+Checking the safe RET mitigation actually works
+-----------------------------------------------
+
+In case one wants to validate whether the SRSO safe RET mitigation works
+on a kernel, one could use two performance counters
+
+* PMC_0xc8 - Count of RET/RET lw retired
+* PMC_0xc9 - Count of RET/RET lw retired mispredicted
+
+and compare the number of RETs retired properly vs those retired
+mispredicted, in kernel mode. Another way of specifying those events
+is::
+
+ # perf list ex_ret_near_ret
+
+ List of pre-defined events (to be used in -e or -M):
+
+ core:
+ ex_ret_near_ret
+ [Retired Near Returns]
+ ex_ret_near_ret_mispred
+ [Retired Near Returns Mispredicted]
+
+Either the command using the event mnemonics::
+
+ # perf stat -e ex_ret_near_ret:k -e ex_ret_near_ret_mispred:k sleep 10s
+
+or using the raw PMC numbers::
+
+ # perf stat -e cpu/event=0xc8,umask=0/k -e cpu/event=0xc9,umask=0/k sleep 10s
+
+should give the same amount. I.e., every RET retired should be
+mispredicted::
+
+ [root@brent: ~/kernel/linux/tools/perf> ./perf stat -e cpu/event=0xc8,umask=0/k -e cpu/event=0xc9,umask=0/k sleep 10s
+
+ Performance counter stats for 'sleep 10s':
+
+ 137,167 cpu/event=0xc8,umask=0/k
+ 137,173 cpu/event=0xc9,umask=0/k
+
+ 10.004110303 seconds time elapsed
+
+ 0.000000000 seconds user
+ 0.004462000 seconds sys
+
+vs the case when the mitigation is disabled (spec_rstack_overflow=off)
+or not functioning properly, showing usually a lot smaller number of
+mispredicted retired RETs vs the overall count of retired RETs during
+a workload::
+
+ [root@brent: ~/kernel/linux/tools/perf> ./perf stat -e cpu/event=0xc8,umask=0/k -e cpu/event=0xc9,umask=0/k sleep 10s
+
+ Performance counter stats for 'sleep 10s':
+
+ 201,627 cpu/event=0xc8,umask=0/k
+ 4,074 cpu/event=0xc9,umask=0/k
+
+ 10.003267252 seconds time elapsed
+
+ 0.002729000 seconds user
+ 0.000000000 seconds sys
+
+Also, there is a selftest which performs the above, go to
+tools/testing/selftests/x86/ and do::
+
+ make srso
+ ./srso
diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
new file mode 100644
index 000000000000..444f84e22a91
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
@@ -0,0 +1,270 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+TAA - TSX Asynchronous Abort
+======================================
+
+TAA is a hardware vulnerability that allows unprivileged speculative access to
+data which is available in various CPU internal buffers by using asynchronous
+aborts within an Intel TSX transactional region.
+
+Affected processors
+-------------------
+
+This vulnerability only affects Intel processors that support Intel
+Transactional Synchronization Extensions (TSX) when the TAA_NO bit (bit 8)
+is 0 in the IA32_ARCH_CAPABILITIES MSR. On processors where the MDS_NO bit
+(bit 5) is 0 in the IA32_ARCH_CAPABILITIES MSR, the existing MDS mitigations
+also mitigate against TAA.
+
+Whether a processor is affected or not can be read out from the TAA
+vulnerability file in sysfs. See :ref:`tsx_async_abort_sys_info`.
+
+Related CVEs
+------------
+
+The following CVE entry is related to this TAA issue:
+
+ ============== ===== ===================================================
+ CVE-2019-11135 TAA TSX Asynchronous Abort (TAA) condition on some
+ microprocessors utilizing speculative execution may
+ allow an authenticated user to potentially enable
+ information disclosure via a side channel with
+ local access.
+ ============== ===== ===================================================
+
+Problem
+-------
+
+When performing store, load or L1 refill operations, processors write
+data into temporary microarchitectural structures (buffers). The data in
+those buffers can be forwarded to load operations as an optimization.
+
+Intel TSX is an extension to the x86 instruction set architecture that adds
+hardware transactional memory support to improve performance of multi-threaded
+software. TSX lets the processor expose and exploit concurrency hidden in an
+application due to dynamically avoiding unnecessary synchronization.
+
+TSX supports atomic memory transactions that are either committed (success) or
+aborted. During an abort, operations that happened within the transactional region
+are rolled back. An asynchronous abort takes place, among other options, when a
+different thread accesses a cache line that is also used within the transactional
+region when that access might lead to a data race.
+
+Immediately after an uncompleted asynchronous abort, certain speculatively
+executed loads may read data from those internal buffers and pass it to dependent
+operations. This can be then used to infer the value via a cache side channel
+attack.
+
+Because the buffers are potentially shared between Hyper-Threads cross
+Hyper-Thread attacks are possible.
+
+The victim of a malicious actor does not need to make use of TSX. Only the
+attacker needs to begin a TSX transaction and raise an asynchronous abort
+which in turn potentially leaks data stored in the buffers.
+
+More detailed technical information is available in the TAA specific x86
+architecture section: :ref:`Documentation/arch/x86/tsx_async_abort.rst <tsx_async_abort>`.
+
+
+Attack scenarios
+----------------
+
+Attacks against the TAA vulnerability can be implemented from unprivileged
+applications running on hosts or guests.
+
+As for MDS, the attacker has no control over the memory addresses that can
+be leaked. Only the victim is responsible for bringing data to the CPU. As
+a result, the malicious actor has to sample as much data as possible and
+then postprocess it to try to infer any useful information from it.
+
+A potential attacker only has read access to the data. Also, there is no direct
+privilege escalation by using this technique.
+
+
+.. _tsx_async_abort_sys_info:
+
+TAA system information
+-----------------------
+
+The Linux kernel provides a sysfs interface to enumerate the current TAA status
+of mitigated systems. The relevant sysfs file is:
+
+/sys/devices/system/cpu/vulnerabilities/tsx_async_abort
+
+The possible values in this file are:
+
+.. list-table::
+
+ * - 'Vulnerable'
+ - The CPU is affected by this vulnerability and the microcode and kernel mitigation are not applied.
+ * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
+ - The processor is vulnerable but microcode is not updated. The
+ mitigation is enabled on a best effort basis.
+
+ If the processor is vulnerable but the availability of the microcode
+ based mitigation mechanism is not advertised via CPUID, the kernel
+ selects a best effort mitigation mode. This mode invokes the mitigation
+ instructions without a guarantee that they clear the CPU buffers.
+
+ This is done to address virtualization scenarios where the host has the
+ microcode update applied, but the hypervisor is not yet updated to
+ expose the CPUID to the guest. If the host has updated microcode the
+ protection takes effect; otherwise a few CPU cycles are wasted
+ pointlessly.
+ * - 'Mitigation: Clear CPU buffers'
+ - The microcode has been updated to clear the buffers. TSX is still enabled.
+ * - 'Mitigation: TSX disabled'
+ - TSX is disabled.
+ * - 'Not affected'
+ - The CPU is not affected by this issue.
+
+Mitigation mechanism
+--------------------
+
+The kernel detects the affected CPUs and the presence of the microcode which is
+required. If a CPU is affected and the microcode is available, then the kernel
+enables the mitigation by default.
+
+
+The mitigation can be controlled at boot time via a kernel command line option.
+See :ref:`taa_mitigation_control_command_line`.
+
+Virtualization mitigation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Affected systems where the host has TAA microcode and TAA is mitigated by
+having disabled TSX previously, are not vulnerable regardless of the status
+of the VMs.
+
+In all other cases, if the host either does not have the TAA microcode or
+the kernel is not mitigated, the system might be vulnerable.
+
+
+.. _taa_mitigation_control_command_line:
+
+Mitigation control on the kernel command line
+---------------------------------------------
+
+The kernel command line allows to control the TAA mitigations at boot time with
+the option "tsx_async_abort=". The valid arguments for this option are:
+
+ ============ =============================================================
+ off This option disables the TAA mitigation on affected platforms.
+ If the system has TSX enabled (see next parameter) and the CPU
+ is affected, the system is vulnerable.
+
+ full TAA mitigation is enabled. If TSX is enabled, on an affected
+ system it will clear CPU buffers on ring transitions. On
+ systems which are MDS-affected and deploy MDS mitigation,
+ TAA is also mitigated. Specifying this option on those
+ systems will have no effect.
+
+ full,nosmt The same as tsx_async_abort=full, with SMT disabled on
+ vulnerable CPUs that have TSX enabled. This is the complete
+ mitigation. When TSX is disabled, SMT is not disabled because
+ CPU is not vulnerable to cross-thread TAA attacks.
+ ============ =============================================================
+
+Not specifying this option is equivalent to "tsx_async_abort=full". For
+processors that are affected by both TAA and MDS, specifying just
+"tsx_async_abort=off" without an accompanying "mds=off" will have no
+effect as the same mitigation is used for both vulnerabilities.
+
+The kernel command line also allows to control the TSX feature using the
+parameter "tsx=" on CPUs which support TSX control. MSR_IA32_TSX_CTRL is used
+to control the TSX feature and the enumeration of the TSX feature bits (RTM
+and HLE) in CPUID.
+
+The valid options are:
+
+ ============ =============================================================
+ off Disables TSX on the system.
+
+ Note that this option takes effect only on newer CPUs which are
+ not vulnerable to MDS, i.e., have MSR_IA32_ARCH_CAPABILITIES.MDS_NO=1
+ and which get the new IA32_TSX_CTRL MSR through a microcode
+ update. This new MSR allows for the reliable deactivation of
+ the TSX functionality.
+
+ on Enables TSX.
+
+ Although there are mitigations for all known security
+ vulnerabilities, TSX has been known to be an accelerator for
+ several previous speculation-related CVEs, and so there may be
+ unknown security risks associated with leaving it enabled.
+
+ auto Disables TSX if X86_BUG_TAA is present, otherwise enables TSX
+ on the system.
+ ============ =============================================================
+
+Not specifying this option is equivalent to "tsx=off".
+
+The following combinations of the "tsx_async_abort" and "tsx" are possible. For
+affected platforms tsx=auto is equivalent to tsx=off and the result will be:
+
+ ========= ========================== =========================================
+ tsx=on tsx_async_abort=full The system will use VERW to clear CPU
+ buffers. Cross-thread attacks are still
+ possible on SMT machines.
+ tsx=on tsx_async_abort=full,nosmt As above, cross-thread attacks on SMT
+ mitigated.
+ tsx=on tsx_async_abort=off The system is vulnerable.
+ tsx=off tsx_async_abort=full TSX might be disabled if microcode
+ provides a TSX control MSR. If so,
+ system is not vulnerable.
+ tsx=off tsx_async_abort=full,nosmt Ditto
+ tsx=off tsx_async_abort=off ditto
+ ========= ========================== =========================================
+
+
+For unaffected platforms "tsx=on" and "tsx_async_abort=full" does not clear CPU
+buffers. For platforms without TSX control (MSR_IA32_ARCH_CAPABILITIES.MDS_NO=0)
+"tsx" command line argument has no effect.
+
+For the affected platforms below table indicates the mitigation status for the
+combinations of CPUID bit MD_CLEAR and IA32_ARCH_CAPABILITIES MSR bits MDS_NO
+and TSX_CTRL_MSR.
+
+ ======= ========= ============= ========================================
+ MDS_NO MD_CLEAR TSX_CTRL_MSR Status
+ ======= ========= ============= ========================================
+ 0 0 0 Vulnerable (needs microcode)
+ 0 1 0 MDS and TAA mitigated via VERW
+ 1 1 0 MDS fixed, TAA vulnerable if TSX enabled
+ because MD_CLEAR has no meaning and
+ VERW is not guaranteed to clear buffers
+ 1 X 1 MDS fixed, TAA can be mitigated by
+ VERW or TSX_CTRL_MSR
+ ======= ========= ============= ========================================
+
+Mitigation selection guide
+--------------------------
+
+1. Trusted userspace and guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If all user space applications are from a trusted source and do not execute
+untrusted code which is supplied externally, then the mitigation can be
+disabled. The same applies to virtualized environments with trusted guests.
+
+
+2. Untrusted userspace and guests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If there are untrusted applications or guests on the system, enabling TSX
+might allow a malicious actor to leak data from the host or from other
+processes running on the same physical core.
+
+If the microcode is available and the TSX is disabled on the host, attacks
+are prevented in a virtualized environment as well, even if the VMs do not
+explicitly enable the mitigation.
+
+
+.. _taa_default_mitigations:
+
+Default mitigations
+-------------------
+
+The kernel's default action for vulnerable processors is:
+
+ - Deploy TSX disable mitigation (tsx_async_abort=full tsx=off).
diff --git a/Documentation/admin-guide/hw-vuln/vmscape.rst b/Documentation/admin-guide/hw-vuln/vmscape.rst
new file mode 100644
index 000000000000..d9b9a2b6c114
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/vmscape.rst
@@ -0,0 +1,110 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+VMSCAPE
+=======
+
+VMSCAPE is a vulnerability that may allow a guest to influence the branch
+prediction in host userspace. It particularly affects hypervisors like QEMU.
+
+Even if a hypervisor may not have any sensitive data like disk encryption keys,
+guest-userspace may be able to attack the guest-kernel using the hypervisor as
+a confused deputy.
+
+Affected processors
+-------------------
+
+The following CPU families are affected by VMSCAPE:
+
+**Intel processors:**
+ - Skylake generation (Parts without Enhanced-IBRS)
+ - Cascade Lake generation - (Parts affected by ITS guest/host separation)
+ - Alder Lake and newer (Parts affected by BHI)
+
+Note that, BHI affected parts that use BHB clearing software mitigation e.g.
+Icelake are not vulnerable to VMSCAPE.
+
+**AMD processors:**
+ - Zen series (families 0x17, 0x19, 0x1a)
+
+** Hygon processors:**
+ - Family 0x18
+
+Mitigation
+----------
+
+Conditional IBPB
+----------------
+
+Kernel tracks when a CPU has run a potentially malicious guest and issues an
+IBPB before the first exit to userspace after VM-exit. If userspace did not run
+between VM-exit and the next VM-entry, no IBPB is issued.
+
+Note that the existing userspace mitigation against Spectre-v2 is effective in
+protecting the userspace. They are insufficient to protect the userspace VMMs
+from a malicious guest. This is because Spectre-v2 mitigations are applied at
+context switch time, while the userspace VMM can run after a VM-exit without a
+context switch.
+
+Vulnerability enumeration and mitigation is not applied inside a guest. This is
+because nested hypervisors should already be deploying IBPB to isolate
+themselves from nested guests.
+
+SMT considerations
+------------------
+
+When Simultaneous Multi-Threading (SMT) is enabled, hypervisors can be
+vulnerable to cross-thread attacks. For complete protection against VMSCAPE
+attacks in SMT environments, STIBP should be enabled.
+
+The kernel will issue a warning if SMT is enabled without adequate STIBP
+protection. Warning is not issued when:
+
+- SMT is disabled
+- STIBP is enabled system-wide
+- Intel eIBRS is enabled (which implies STIBP protection)
+
+System information and options
+------------------------------
+
+The sysfs file showing VMSCAPE mitigation status is:
+
+ /sys/devices/system/cpu/vulnerabilities/vmscape
+
+The possible values in this file are:
+
+ * 'Not affected':
+
+ The processor is not vulnerable to VMSCAPE attacks.
+
+ * 'Vulnerable':
+
+ The processor is vulnerable and no mitigation has been applied.
+
+ * 'Mitigation: IBPB before exit to userspace':
+
+ Conditional IBPB mitigation is enabled. The kernel tracks when a CPU has
+ run a potentially malicious guest and issues an IBPB before the first
+ exit to userspace after VM-exit.
+
+ * 'Mitigation: IBPB on VMEXIT':
+
+ IBPB is issued on every VM-exit. This occurs when other mitigations like
+ RETBLEED or SRSO are already issuing IBPB on VM-exit.
+
+Mitigation control on the kernel command line
+----------------------------------------------
+
+The mitigation can be controlled via the ``vmscape=`` command line parameter:
+
+ * ``vmscape=off``:
+
+ Disable the VMSCAPE mitigation.
+
+ * ``vmscape=ibpb``:
+
+ Enable conditional IBPB mitigation (default when CONFIG_MITIGATION_VMSCAPE=y).
+
+ * ``vmscape=force``:
+
+ Force vulnerability detection and mitigation even on processors that are
+ not known to be affected.
diff --git a/Documentation/admin-guide/hw_random.rst b/Documentation/admin-guide/hw_random.rst
new file mode 100644
index 000000000000..bfc39f1cf470
--- /dev/null
+++ b/Documentation/admin-guide/hw_random.rst
@@ -0,0 +1,104 @@
+=================================
+Hardware random number generators
+=================================
+
+Introduction
+============
+
+The hw_random framework is software that makes use of a
+special hardware feature on your CPU or motherboard,
+a Random Number Generator (RNG). The software has two parts:
+a core providing the /dev/hwrng character device and its
+sysfs support, plus a hardware-specific driver that plugs
+into that core.
+
+To make the most effective use of these mechanisms, you
+should download the support software as well. Download the
+latest version of the "rng-tools" package from:
+
+ https://github.com/nhorman/rng-tools
+
+Those tools use /dev/hwrng to fill the kernel entropy pool,
+which is used internally and exported by the /dev/urandom and
+/dev/random special files.
+
+Theory of operation
+===================
+
+CHARACTER DEVICE. Using the standard open()
+and read() system calls, you can read random data from
+the hardware RNG device. This data is NOT CHECKED by any
+fitness tests, and could potentially be bogus (if the
+hardware is faulty or has been tampered with). Data is only
+output if the hardware "has-data" flag is set, but nevertheless
+a security-conscious person would run fitness tests on the
+data before assuming it is truly random.
+
+The rng-tools package uses such tests in "rngd", and lets you
+run them by hand with a "rngtest" utility.
+
+/dev/hwrng is char device major 10, minor 183.
+
+CLASS DEVICE. There is a /sys/class/misc/hw_random node with
+two unique attributes, "rng_available" and "rng_current". The
+"rng_available" attribute lists the hardware-specific drivers
+available, while "rng_current" lists the one which is currently
+connected to /dev/hwrng. If your system has more than one
+RNG available, you may change the one used by writing a name from
+the list in "rng_available" into "rng_current".
+
+==========================================================================
+
+
+Hardware driver for Intel/AMD/VIA Random Number Generators (RNG)
+ - Copyright 2000,2001 Jeff Garzik <jgarzik@pobox.com>
+ - Copyright 2000,2001 Philipp Rumpf <prumpf@mandrakesoft.com>
+
+
+About the Intel RNG hardware, from the firmware hub datasheet
+=============================================================
+
+The Firmware Hub integrates a Random Number Generator (RNG)
+using thermal noise generated from inherently random quantum
+mechanical properties of silicon. When not generating new random
+bits the RNG circuitry will enter a low power state. Intel will
+provide a binary software driver to give third party software
+access to our RNG for use as a security feature. At this time,
+the RNG is only to be used with a system in an OS-present state.
+
+Intel RNG Driver notes
+======================
+
+FIXME: support poll(2)
+
+.. note::
+
+ request_mem_region was removed, for three reasons:
+
+ 1) Only one RNG is supported by this driver;
+ 2) The location used by the RNG is a fixed location in
+ MMIO-addressable memory;
+ 3) users with properly working BIOS e820 handling will always
+ have the region in which the RNG is located reserved, so
+ request_mem_region calls always fail for proper setups.
+ However, for people who use mem=XX, BIOS e820 information is
+ **not** in /proc/iomem, and request_mem_region(RNG_ADDR) can
+ succeed.
+
+Driver details
+==============
+
+Based on:
+ Intel 82802AB/82802AC Firmware Hub (FWH) Datasheet
+ May 1999 Order Number: 290658-002 R
+
+Intel 82802 Firmware Hub:
+ Random Number Generator
+ Programmer's Reference Manual
+ December 1999 Order Number: 298029-001 R
+
+Intel 82802 Firmware HUB Random Number Generator Driver
+ Copyright (c) 2000 Matt Sottek <msottek@quiknet.com>
+
+Special thanks to Matt Sottek. I did the "guts", he
+did the "brains" and all the testing.
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
new file mode 100644
index 000000000000..259d79fbeb94
--- /dev/null
+++ b/Documentation/admin-guide/index.rst
@@ -0,0 +1,198 @@
+=================================================
+The Linux kernel user's and administrator's guide
+=================================================
+
+The following is a collection of user-oriented documents that have been
+added to the kernel over time. There is, as yet, little overall order or
+organization here — this material was not written to be a single, coherent
+document! With luck things will improve quickly over time.
+
+General guides to kernel administration
+---------------------------------------
+
+This initial section contains overall information, including the README
+file describing the kernel as a whole, documentation on kernel parameters,
+etc.
+
+.. toctree::
+ :maxdepth: 1
+
+ README
+ devices
+
+ features
+
+A big part of the kernel's administrative interface is the /proc and sysfs
+virtual filesystems; these documents describe how to interact with tem
+
+.. toctree::
+ :maxdepth: 1
+
+ sysfs-rules
+ sysctl/index
+ cputopology
+ abi
+
+Security-related documentation:
+
+.. toctree::
+ :maxdepth: 1
+
+ hw-vuln/index
+ LSM/index
+ perf-security
+
+Booting the kernel
+------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ bootconfig
+ kernel-parameters
+ efi-stub
+ initrd
+
+
+Tracking down and identifying problems
+--------------------------------------
+
+Here is a set of documents aimed at users who are trying to track down
+problems and bugs in particular.
+
+.. toctree::
+ :maxdepth: 1
+
+ reporting-issues
+ reporting-regressions
+ quickly-build-trimmed-linux
+ verify-bugs-and-bisect-regressions
+ bug-hunting
+ bug-bisect
+ tainted-kernels
+ ramoops
+ dynamic-debug-howto
+ init
+ kdump/index
+ perf/index
+ pstore-blk
+ clearing-warn-once
+ kernel-per-CPU-kthreads
+ lockup-watchdogs
+ RAS/index
+ sysrq
+
+
+Core-kernel subsystems
+----------------------
+
+These documents describe core-kernel administration interfaces that are
+likely to be of interest on almost any system.
+
+.. toctree::
+ :maxdepth: 1
+
+ cgroup-v2
+ cgroup-v1/index
+ cpu-load
+ mm/index
+ module-signing
+ namespaces/index
+ numastat
+ pm/index
+ syscall-user-dispatch
+
+Support for non-native binary formats. Note that some of these
+documents are ... old ...
+
+.. toctree::
+ :maxdepth: 1
+
+ binfmt-misc
+ java
+ mono
+
+
+Block-layer and filesystem administration
+-----------------------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ bcache
+ binderfs
+ blockdev/index
+ cifs/index
+ device-mapper/index
+ ext4
+ filesystem-monitoring
+ nfs/index
+ iostats
+ jfs
+ md
+ ufs
+ xfs
+
+Device-specific guides
+----------------------
+
+How to configure your hardware within your Linux system.
+
+.. toctree::
+ :maxdepth: 1
+
+ acpi/index
+ aoe/index
+ auxdisplay/index
+ braille-console
+ btmrvl
+ dell_rbu
+ edid
+ gpio/index
+ hw_random
+ laptops/index
+ lcd-panel-cgram
+ media/index
+ nvme-multipath
+ parport
+ pnp
+ rapidio
+ rtc
+ serial-console
+ svga
+ thermal/index
+ thunderbolt
+ vga-softcursor
+ video-output
+
+Workload analysis
+-----------------
+
+This is the beginning of a section with information of interest to
+application developers and system integrators doing analysis of the
+Linux kernel for safety critical applications. Documents supporting
+analysis of kernel interactions with applications, and key kernel
+subsystems expectations will be found here.
+
+.. toctree::
+ :maxdepth: 1
+
+ workload-tracing
+
+Everything else
+---------------
+
+A few hard-to-categorize and generally obsolete documents.
+
+.. toctree::
+ :maxdepth: 1
+
+ ldm
+ unicode
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/init.rst b/Documentation/admin-guide/init.rst
new file mode 100644
index 000000000000..41f06a09152e
--- /dev/null
+++ b/Documentation/admin-guide/init.rst
@@ -0,0 +1,48 @@
+Explaining the "No working init found." boot hang message
+=========================================================
+:Authors: Andreas Mohr <andi at lisas period de>
+ Cristian Souza <cristianmsbr at gmail period com>
+
+This document provides some high-level reasons for failure
+(listed roughly in order of execution) to load the init binary.
+
+1) **Unable to mount root FS**: Set "debug" kernel parameter (in bootloader
+ config file or CONFIG_CMDLINE) to get more detailed kernel messages.
+
+2) **init binary doesn't exist on rootfs**: Make sure you have the correct
+ root FS type (and ``root=`` kernel parameter points to the correct
+ partition), required drivers such as storage hardware (such as SCSI or
+ USB!) and filesystem (ext3, jffs2, etc.) are builtin (alternatively as
+ modules, to be pre-loaded by an initrd).
+
+3) **Broken console device**: Possibly a conflict in ``console= setup``
+ --> initial console unavailable. E.g. some serial consoles are unreliable
+ due to serial IRQ issues (e.g. missing interrupt-based configuration).
+ Try using a different ``console= device`` or e.g. ``netconsole=``.
+
+4) **Binary exists but dependencies not available**: E.g. required library
+ dependencies of the init binary such as ``/lib/ld-linux.so.2`` missing or
+ broken. Use ``readelf -d <INIT>|grep NEEDED`` to find out which libraries
+ are required.
+
+5) **Binary cannot be loaded**: Make sure the binary's architecture matches
+ your hardware. E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM
+ hardware. In case you tried loading a non-binary file here (shell script?),
+ you should make sure that the script specifies an interpreter in its
+ shebang header line (``#!/...``) that is fully working (including its
+ library dependencies). And before tackling scripts, better first test a
+ simple non-script binary such as ``/bin/sh`` and confirm its successful
+ execution. To find out more, add code ``to init/main.c`` to display
+ kernel_execve()s return values.
+
+Please extend this explanation whenever you find new failure causes
+(after all loading the init binary is a CRITICAL and hard transition step
+which needs to be made as painless as possible), then submit a patch to LKML.
+Further TODOs:
+
+- Implement the various ``run_init_process()`` invocations via a struct array
+ which can then store the ``kernel_execve()`` result value and on failure
+ log it all by iterating over **all** results (very important usability fix).
+- Try to make the implementation itself more helpful in general, e.g. by
+ providing additional error messages at affected places.
+
diff --git a/Documentation/admin-guide/initrd.rst b/Documentation/admin-guide/initrd.rst
new file mode 100644
index 000000000000..67bbad8806e8
--- /dev/null
+++ b/Documentation/admin-guide/initrd.rst
@@ -0,0 +1,383 @@
+Using the initial RAM disk (initrd)
+===================================
+
+Written 1996,2000 by Werner Almesberger <werner.almesberger@epfl.ch> and
+Hans Lermen <lermen@fgan.de>
+
+
+initrd provides the capability to load a RAM disk by the boot loader.
+This RAM disk can then be mounted as the root file system and programs
+can be run from it. Afterwards, a new root file system can be mounted
+from a different device. The previous root (from initrd) is then moved
+to a directory and can be subsequently unmounted.
+
+initrd is mainly designed to allow system startup to occur in two phases,
+where the kernel comes up with a minimum set of compiled-in drivers, and
+where additional modules are loaded from initrd.
+
+This document gives a brief overview of the use of initrd. A more detailed
+discussion of the boot process can be found in [#f1]_.
+
+
+Operation
+---------
+
+When using initrd, the system typically boots as follows:
+
+ 1) the boot loader loads the kernel and the initial RAM disk
+ 2) the kernel converts initrd into a "normal" RAM disk and
+ frees the memory used by initrd
+ 3) if the root device is not ``/dev/ram0``, the old (deprecated)
+ change_root procedure is followed. see the "Obsolete root change
+ mechanism" section below.
+ 4) root device is mounted. if it is ``/dev/ram0``, the initrd image is
+ then mounted as root
+ 5) /sbin/init is executed (this can be any valid executable, including
+ shell scripts; it is run with uid 0 and can do basically everything
+ init can do).
+ 6) init mounts the "real" root file system
+ 7) init places the root file system at the root directory using the
+ pivot_root system call
+ 8) init execs the ``/sbin/init`` on the new root filesystem, performing
+ the usual boot sequence
+ 9) the initrd file system is removed
+
+Note that changing the root directory does not involve unmounting it.
+It is therefore possible to leave processes running on initrd during that
+procedure. Also note that file systems mounted under initrd continue to
+be accessible.
+
+
+Boot command-line options
+-------------------------
+
+initrd adds the following new options::
+
+ initrd=<path> (e.g. LOADLIN)
+
+ Loads the specified file as the initial RAM disk. When using LILO, you
+ have to specify the RAM disk image file in /etc/lilo.conf, using the
+ INITRD configuration variable.
+
+ noinitrd
+
+ initrd data is preserved but it is not converted to a RAM disk and
+ the "normal" root file system is mounted. initrd data can be read
+ from /dev/initrd. Note that the data in initrd can have any structure
+ in this case and doesn't necessarily have to be a file system image.
+ This option is used mainly for debugging.
+
+ Note: /dev/initrd is read-only and it can only be used once. As soon
+ as the last process has closed it, all data is freed and /dev/initrd
+ can't be opened anymore.
+
+ root=/dev/ram0
+
+ initrd is mounted as root, and the normal boot procedure is followed,
+ with the RAM disk mounted as root.
+
+Compressed cpio images
+----------------------
+
+Recent kernels have support for populating a ramdisk from a compressed cpio
+archive. On such systems, the creation of a ramdisk image doesn't need to
+involve special block devices or loopbacks; you merely create a directory on
+disk with the desired initrd content, cd to that directory, and run (as an
+example)::
+
+ find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img
+
+Examining the contents of an existing image file is just as simple::
+
+ mkdir /tmp/imagefile
+ cd /tmp/imagefile
+ gzip -cd /boot/imagefile.img | cpio -imd --quiet
+
+Installation
+------------
+
+First, a directory for the initrd file system has to be created on the
+"normal" root file system, e.g.::
+
+ # mkdir /initrd
+
+The name is not relevant. More details can be found on the
+:manpage:`pivot_root(2)` man page.
+
+If the root file system is created during the boot procedure (i.e. if
+you're building an install floppy), the root file system creation
+procedure should create the ``/initrd`` directory.
+
+If initrd will not be mounted in some cases, its content is still
+accessible if the following device has been created::
+
+ # mknod /dev/initrd b 1 250
+ # chmod 400 /dev/initrd
+
+Second, the kernel has to be compiled with RAM disk support and with
+support for the initial RAM disk enabled. Also, at least all components
+needed to execute programs from initrd (e.g. executable format and file
+system) must be compiled into the kernel.
+
+Third, you have to create the RAM disk image. This is done by creating a
+file system on a block device, copying files to it as needed, and then
+copying the content of the block device to the initrd file. With recent
+kernels, at least three types of devices are suitable for that:
+
+ - a floppy disk (works everywhere but it's painfully slow)
+ - a RAM disk (fast, but allocates physical memory)
+ - a loopback device (the most elegant solution)
+
+We'll describe the loopback device method:
+
+ 1) make sure loopback block devices are configured into the kernel
+ 2) create an empty file system of the appropriate size, e.g.::
+
+ # dd if=/dev/zero of=initrd bs=300k count=1
+ # mke2fs -F -m0 initrd
+
+ (if space is critical, you may want to use the Minix FS instead of Ext2)
+ 3) mount the file system, e.g.::
+
+ # mount -t ext2 -o loop initrd /mnt
+
+ 4) create the console device::
+
+ # mkdir /mnt/dev
+ # mknod /mnt/dev/console c 5 1
+
+ 5) copy all the files that are needed to properly use the initrd
+ environment. Don't forget the most important file, ``/sbin/init``
+
+ .. note:: ``/sbin/init`` permissions must include "x" (execute).
+
+ 6) correct operation the initrd environment can frequently be tested
+ even without rebooting with the command::
+
+ # chroot /mnt /sbin/init
+
+ This is of course limited to initrds that do not interfere with the
+ general system state (e.g. by reconfiguring network interfaces,
+ overwriting mounted devices, trying to start already running demons,
+ etc. Note however that it is usually possible to use pivot_root in
+ such a chroot'ed initrd environment.)
+ 7) unmount the file system::
+
+ # umount /mnt
+
+ 8) the initrd is now in the file "initrd". Optionally, it can now be
+ compressed::
+
+ # gzip -9 initrd
+
+For experimenting with initrd, you may want to take a rescue floppy and
+only add a symbolic link from ``/sbin/init`` to ``/bin/sh``. Alternatively, you
+can try the experimental newlib environment [#f2]_ to create a small
+initrd.
+
+Finally, you have to boot the kernel and load initrd. Almost all Linux
+boot loaders support initrd. Since the boot process is still compatible
+with an older mechanism, the following boot command line parameters
+have to be given::
+
+ root=/dev/ram0 rw
+
+(rw is only necessary if writing to the initrd file system.)
+
+With LOADLIN, you simply execute::
+
+ LOADLIN <kernel> initrd=<disk_image>
+
+e.g.::
+
+ LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw
+
+With LILO, you add the option ``INITRD=<path>`` to either the global section
+or to the section of the respective kernel in ``/etc/lilo.conf``, and pass
+the options using APPEND, e.g.::
+
+ image = /bzImage
+ initrd = /boot/initrd.gz
+ append = "root=/dev/ram0 rw"
+
+and run ``/sbin/lilo``
+
+For other boot loaders, please refer to the respective documentation.
+
+Now you can boot and enjoy using initrd.
+
+
+Changing the root device
+------------------------
+
+When finished with its duties, init typically changes the root device
+and proceeds with starting the Linux system on the "real" root device.
+
+The procedure involves the following steps:
+ - mounting the new root file system
+ - turning it into the root file system
+ - removing all accesses to the old (initrd) root file system
+ - unmounting the initrd file system and de-allocating the RAM disk
+
+Mounting the new root file system is easy: it just needs to be mounted on
+a directory under the current root. Example::
+
+ # mkdir /new-root
+ # mount -o ro /dev/hda1 /new-root
+
+The root change is accomplished with the pivot_root system call, which
+is also available via the ``pivot_root`` utility (see :manpage:`pivot_root(8)`
+man page; ``pivot_root`` is distributed with util-linux version 2.10h or higher
+[#f3]_). ``pivot_root`` moves the current root to a directory under the new
+root, and puts the new root at its place. The directory for the old root
+must exist before calling ``pivot_root``. Example::
+
+ # cd /new-root
+ # mkdir initrd
+ # pivot_root . initrd
+
+Now, the init process may still access the old root via its
+executable, shared libraries, standard input/output/error, and its
+current root directory. All these references are dropped by the
+following command::
+
+ # exec chroot . what-follows <dev/console >dev/console 2>&1
+
+Where what-follows is a program under the new root, e.g. ``/sbin/init``
+If the new root file system will be used with udev and has no valid
+``/dev`` directory, udev must be initialized before invoking chroot in order
+to provide ``/dev/console``.
+
+Note: implementation details of pivot_root may change with time. In order
+to ensure compatibility, the following points should be observed:
+
+ - before calling pivot_root, the current directory of the invoking
+ process should point to the new root directory
+ - use . as the first argument, and the _relative_ path of the directory
+ for the old root as the second argument
+ - a chroot program must be available under the old and the new root
+ - chroot to the new root afterwards
+ - use relative paths for dev/console in the exec command
+
+Now, the initrd can be unmounted and the memory allocated by the RAM
+disk can be freed::
+
+ # umount /initrd
+ # blockdev --flushbufs /dev/ram0
+
+It is also possible to use initrd with an NFS-mounted root, see the
+:manpage:`pivot_root(8)` man page for details.
+
+
+Usage scenarios
+---------------
+
+The main motivation for implementing initrd was to allow for modular
+kernel configuration at system installation. The procedure would work
+as follows:
+
+ 1) system boots from floppy or other media with a minimal kernel
+ (e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and
+ loads initrd
+ 2) ``/sbin/init`` determines what is needed to (1) mount the "real" root FS
+ (i.e. device type, device drivers, file system) and (2) the
+ distribution media (e.g. CD-ROM, network, tape, ...). This can be
+ done by asking the user, by auto-probing, or by using a hybrid
+ approach.
+ 3) ``/sbin/init`` loads the necessary kernel modules
+ 4) ``/sbin/init`` creates and populates the root file system (this doesn't
+ have to be a very usable system yet)
+ 5) ``/sbin/init`` invokes ``pivot_root`` to change the root file system and
+ execs - via chroot - a program that continues the installation
+ 6) the boot loader is installed
+ 7) the boot loader is configured to load an initrd with the set of
+ modules that was used to bring up the system (e.g. ``/initrd`` can be
+ modified, then unmounted, and finally, the image is written from
+ ``/dev/ram0`` or ``/dev/rd/0`` to a file)
+ 8) now the system is bootable and additional installation tasks can be
+ performed
+
+The key role of initrd here is to re-use the configuration data during
+normal system operation without requiring the use of a bloated "generic"
+kernel or re-compiling or re-linking the kernel.
+
+A second scenario is for installations where Linux runs on systems with
+different hardware configurations in a single administrative domain. In
+such cases, it is desirable to generate only a small set of kernels
+(ideally only one) and to keep the system-specific part of configuration
+information as small as possible. In this case, a common initrd could be
+generated with all the necessary modules. Then, only ``/sbin/init`` or a file
+read by it would have to be different.
+
+A third scenario is more convenient recovery disks, because information
+like the location of the root FS partition doesn't have to be provided at
+boot time, but the system loaded from initrd can invoke a user-friendly
+dialog and it can also perform some sanity checks (or even some form of
+auto-detection).
+
+Last not least, CD-ROM distributors may use it for better installation
+from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk
+via initrd from CD; or by booting via a loader like ``LOADLIN`` or directly
+from the CD-ROM, and loading the RAM disk from CD without need of
+floppies.
+
+
+Obsolete root change mechanism
+------------------------------
+
+The following mechanism was used before the introduction of pivot_root.
+Current kernels still support it, but you should _not_ rely on its
+continued availability.
+
+It works by mounting the "real" root device (i.e. the one set with rdev
+in the kernel image or with root=... at the boot command line) as the
+root file system when linuxrc exits. The initrd file system is then
+unmounted, or, if it is still busy, moved to a directory ``/initrd``, if
+such a directory exists on the new root file system.
+
+In order to use this mechanism, you do not have to specify the boot
+command options root, init, or rw. (If specified, they will affect
+the real root file system, not the initrd environment.)
+
+If /proc is mounted, the "real" root device can be changed from within
+linuxrc by writing the number of the new root FS device to the special
+file /proc/sys/kernel/real-root-dev, e.g.::
+
+ # echo 0x301 >/proc/sys/kernel/real-root-dev
+
+Note that the mechanism is incompatible with NFS and similar file
+systems.
+
+This old, deprecated mechanism is commonly called ``change_root``, while
+the new, supported mechanism is called ``pivot_root``.
+
+
+Mixed change_root and pivot_root mechanism
+------------------------------------------
+
+In case you did not want to use ``root=/dev/ram0`` to trigger the pivot_root
+mechanism, you may create both ``/linuxrc`` and ``/sbin/init`` in your initrd
+image.
+
+``/linuxrc`` would contain only the following::
+
+ #! /bin/sh
+ mount -n -t proc proc /proc
+ echo 0x0100 >/proc/sys/kernel/real-root-dev
+ umount -n /proc
+
+Once linuxrc exited, the kernel would mount again your initrd as root,
+this time executing ``/sbin/init``. Again, it would be the duty of this init
+to build the right environment (maybe using the ``root= device`` passed on
+the cmdline) before the final execution of the real ``/sbin/init``.
+
+
+Resources
+---------
+
+.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future"
+ https://www.almesberger.net/cv/papers/ols2k-9.ps.gz
+.. [#f2] newlib package (experimental), with initrd example
+ https://www.sourceware.org/newlib/
+.. [#f3] util-linux: Miscellaneous utilities for Linux
+ https://www.kernel.org/pub/linux/utils/util-linux/
diff --git a/Documentation/admin-guide/iostats.rst b/Documentation/admin-guide/iostats.rst
new file mode 100644
index 000000000000..9453196ade51
--- /dev/null
+++ b/Documentation/admin-guide/iostats.rst
@@ -0,0 +1,187 @@
+=====================
+I/O statistics fields
+=====================
+
+The kernel exposes disk statistics via ``/proc/diskstats`` and
+``/sys/block/<device>/stat``. These stats are usually accessed via tools
+such as ``sar`` and ``iostat``.
+
+Here are examples using a disk with two partitions::
+
+ /proc/diskstats:
+ 259 0 nvme0n1 255999 814 12369153 47919 996852 81 36123024 425995 0 301795 580470 0 0 0 0 60602 106555
+ 259 1 nvme0n1p1 492 813 17572 96 848 81 108288 210 0 76 307 0 0 0 0 0 0
+ 259 2 nvme0n1p2 255401 1 12343477 47799 996004 0 36014736 425784 0 344336 473584 0 0 0 0 0 0
+
+ /sys/block/nvme0n1/stat:
+ 255999 814 12369153 47919 996858 81 36123056 426009 0 301809 580491 0 0 0 0 60605 106562
+
+ /sys/block/nvme0n1/nvme0n1p1/stat:
+ 492 813 17572 96 848 81 108288 210 0 76 307 0 0 0 0 0 0
+
+Both files contain the same 17 statistics. ``/sys/block/<device>/stat``
+contains the fields for ``<device>``. In ``/proc/diskstats`` the fields
+are prefixed with the major and minor device numbers and the device
+name. In the example above, the first stat value for ``nvme0n1`` is
+255999 in both files.
+
+The sysfs ``stat`` file is efficient for monitoring a small, known set
+of disks. If you're tracking a large number of devices,
+``/proc/diskstats`` is often the better choice since it avoids the
+overhead of opening and closing multiple files for each snapshot.
+
+All fields are cumulative, monotonic counters, except for field 9, which
+resets to zero as I/Os complete. The remaining fields reset at boot, on
+device reattachment or reinitialization, or when the underlying counter
+overflows. Applications reading these counters should detect and handle
+resets when comparing stat snapshots.
+
+Each set of stats only applies to the indicated device; if you want
+system-wide stats you'll have to find all the devices and sum them all up.
+
+Field 1 -- # of reads completed (unsigned long)
+ This is the total number of reads completed successfully.
+
+Field 2 -- # of reads merged, field 6 -- # of writes merged (unsigned long)
+ Reads and writes which are adjacent to each other may be merged for
+ efficiency. Thus two 4K reads may become one 8K read before it is
+ ultimately handed to the disk, and so it will be counted (and queued)
+ as only one I/O. This field lets you know how often this was done.
+
+Field 3 -- # of sectors read (unsigned long)
+ This is the total number of sectors read successfully.
+
+Field 4 -- # of milliseconds spent reading (unsigned int)
+ This is the total number of milliseconds spent by all reads (as
+ measured from blk_mq_alloc_request() to __blk_mq_end_request()).
+
+Field 5 -- # of writes completed (unsigned long)
+ This is the total number of writes completed successfully.
+
+Field 6 -- # of writes merged (unsigned long)
+ See the description of field 2.
+
+Field 7 -- # of sectors written (unsigned long)
+ This is the total number of sectors written successfully.
+
+Field 8 -- # of milliseconds spent writing (unsigned int)
+ This is the total number of milliseconds spent by all writes (as
+ measured from blk_mq_alloc_request() to __blk_mq_end_request()).
+
+Field 9 -- # of I/Os currently in progress (unsigned int)
+ The only field that should go to zero. Incremented as requests are
+ given to appropriate struct request_queue and decremented as they finish.
+
+Field 10 -- # of milliseconds spent doing I/Os (unsigned int)
+ This field increases so long as field 9 is nonzero.
+
+ Since 5.0 this field counts jiffies when at least one request was
+ started or completed. If request runs more than 2 jiffies then some
+ I/O time might be not accounted in case of concurrent requests.
+
+Field 11 -- weighted # of milliseconds spent doing I/Os (unsigned int)
+ This field is incremented at each I/O start, I/O completion, I/O
+ merge, or read of these stats by the number of I/Os in progress
+ (field 9) times the number of milliseconds spent doing I/O since the
+ last update of this field. This can provide an easy measure of both
+ I/O completion time and the backlog that may be accumulating.
+
+Field 12 -- # of discards completed (unsigned long)
+ This is the total number of discards completed successfully.
+
+Field 13 -- # of discards merged (unsigned long)
+ See the description of field 2
+
+Field 14 -- # of sectors discarded (unsigned long)
+ This is the total number of sectors discarded successfully.
+
+Field 15 -- # of milliseconds spent discarding (unsigned int)
+ This is the total number of milliseconds spent by all discards (as
+ measured from blk_mq_alloc_request() to __blk_mq_end_request()).
+
+Field 16 -- # of flush requests completed
+ This is the total number of flush requests completed successfully.
+
+ Block layer combines flush requests and executes at most one at a time.
+ This counts flush requests executed by disk. Not tracked for partitions.
+
+Field 17 -- # of milliseconds spent flushing
+ This is the total number of milliseconds spent by all flush requests.
+
+To avoid introducing performance bottlenecks, no locks are held while
+modifying these counters. This implies that minor inaccuracies may be
+introduced when changes collide, so (for instance) adding up all the
+read I/Os issued per partition should equal those made to the disks ...
+but due to the lack of locking it may only be very close.
+
+In 2.6+, there are counters for each CPU, which make the lack of locking
+almost a non-issue. When the statistics are read, the per-CPU counters
+are summed (possibly overflowing the unsigned long variable they are
+summed to) and the result given to the user. There is no convenient
+user interface for accessing the per-CPU counters themselves.
+
+Since 4.19 request times are measured with nanoseconds precision and
+truncated to milliseconds before showing in this interface.
+
+Disks vs Partitions
+-------------------
+
+There were significant changes between 2.4 and 2.6+ in the I/O subsystem.
+As a result, some statistic information disappeared. The translation from
+a disk address relative to a partition to the disk address relative to
+the host disk happens much earlier. All merges and timings now happen
+at the disk level rather than at both the disk and partition level as
+in 2.4. Consequently, you'll see a different statistics output on 2.6+ for
+partitions from that for disks. There are only *four* fields available
+for partitions on 2.6+ machines. This is reflected in the examples above.
+
+Field 1 -- # of reads issued
+ This is the total number of reads issued to this partition.
+
+Field 2 -- # of sectors read
+ This is the total number of sectors requested to be read from this
+ partition.
+
+Field 3 -- # of writes issued
+ This is the total number of writes issued to this partition.
+
+Field 4 -- # of sectors written
+ This is the total number of sectors requested to be written to
+ this partition.
+
+Note that since the address is translated to a disk-relative one, and no
+record of the partition-relative address is kept, the subsequent success
+or failure of the read cannot be attributed to the partition. In other
+words, the number of reads for partitions is counted slightly before time
+of queuing for partitions, and at completion for whole disks. This is
+a subtle distinction that is probably uninteresting for most cases.
+
+More significant is the error induced by counting the numbers of
+reads/writes before merges for partitions and after for disks. Since a
+typical workload usually contains a lot of successive and adjacent requests,
+the number of reads/writes issued can be several times higher than the
+number of reads/writes completed.
+
+In 2.6.25, the full statistic set is again available for partitions and
+disk and partition statistics are consistent again. Since we still don't
+keep record of the partition-relative address, an operation is attributed to
+the partition which contains the first sector of the request after the
+eventual merges. As requests can be merged across partition, this could lead
+to some (probably insignificant) inaccuracy.
+
+Additional notes
+----------------
+
+In 2.6+, sysfs is not mounted by default. If your distribution of
+Linux hasn't added it already, here's the line you'll want to add to
+your ``/etc/fstab``::
+
+ none /sys sysfs defaults 0 0
+
+
+In 2.6+, all disk statistics were removed from ``/proc/stat``. In 2.4, they
+appear in both ``/proc/partitions`` and ``/proc/stat``, although the ones in
+``/proc/stat`` take a very different format from those in ``/proc/partitions``
+(see proc(5), if your system has it.)
+
+-- ricklind@us.ibm.com
diff --git a/Documentation/admin-guide/java.rst b/Documentation/admin-guide/java.rst
new file mode 100644
index 000000000000..8744e272e6f8
--- /dev/null
+++ b/Documentation/admin-guide/java.rst
@@ -0,0 +1,423 @@
+Java(tm) Binary Kernel Support for Linux v1.03
+----------------------------------------------
+
+Linux beats them ALL! While all other OS's are TALKING about direct
+support of Java Binaries in the OS, Linux is doing it!
+
+You can execute Java applications and Java Applets just like any
+other program after you have done the following:
+
+1) You MUST FIRST install the Java Developers Kit for Linux.
+ The Java on Linux HOWTO gives the details on getting and
+ installing this. This HOWTO can be found at:
+
+ ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/Java-HOWTO
+
+ You should also set up a reasonable CLASSPATH environment
+ variable to use Java applications that make use of any
+ nonstandard classes (not included in the same directory
+ as the application itself).
+
+2) You have to compile BINFMT_MISC either as a module or into
+ the kernel (``CONFIG_BINFMT_MISC``) and set it up properly.
+ If you choose to compile it as a module, you will have
+ to insert it manually with modprobe/insmod, as kmod
+ cannot easily be supported with binfmt_misc.
+ Read the file 'binfmt_misc.txt' in this directory to know
+ more about the configuration process.
+
+3) Add the following configuration items to binfmt_misc
+ (you should really have read ``binfmt_misc.txt`` now):
+ support for Java applications::
+
+ ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:'
+
+ support for executable Jar files::
+
+ ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:'
+
+ support for Java Applets::
+
+ ':Applet:E::html::/usr/bin/appletviewer:'
+
+ or the following, if you want to be more selective::
+
+ ':Applet:M::<!--applet::/usr/bin/appletviewer:'
+
+ Of course you have to fix the path names. The path/file names given in this
+ document match the Debian 2.1 system. (i.e. jdk installed in ``/usr``,
+ custom wrappers from this document in ``/usr/local``)
+
+ Note, that for the more selective applet support you have to modify
+ existing html-files to contain ``<!--applet-->`` in the first line
+ (``<`` has to be the first character!) to let this work!
+
+ For the compiled Java programs you need a wrapper script like the
+ following (this is because Java is broken in case of the filename
+ handling), again fix the path names, both in the script and in the
+ above given configuration string.
+
+ You, too, need the little program after the script. Compile like::
+
+ gcc -O2 -o javaclassname javaclassname.c
+
+ and stick it to ``/usr/local/bin``.
+
+ Both the javawrapper shellscript and the javaclassname program
+ were supplied by Colin J. Watson <cjw44@cam.ac.uk>.
+
+Javawrapper shell script:
+
+.. code-block:: sh
+
+ #!/bin/bash
+ # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java
+
+ if [ -z "$1" ]; then
+ exec 1>&2
+ echo Usage: $0 class-file
+ exit 1
+ fi
+
+ CLASS=$1
+ FQCLASS=`/usr/local/bin/javaclassname $1`
+ FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'`
+ FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'`
+
+ # for example:
+ # CLASS=Test.class
+ # FQCLASS=foo.bar.Test
+ # FQCLASSN=Test
+ # FQCLASSP=foo/bar
+
+ unset CLASSBASE
+
+ declare -i LINKLEVEL=0
+
+ while :; do
+ if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then
+ # See if this directory works straight off
+ cd -L `dirname $CLASS`
+ CLASSDIR=$PWD
+ cd $OLDPWD
+ if echo $CLASSDIR | grep -q "$FQCLASSP$"; then
+ CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."`
+ break;
+ fi
+ # Try dereferencing the directory name
+ cd -P `dirname $CLASS`
+ CLASSDIR=$PWD
+ cd $OLDPWD
+ if echo $CLASSDIR | grep -q "$FQCLASSP$"; then
+ CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."`
+ break;
+ fi
+ # If no other possible filename exists
+ if [ ! -L $CLASS ]; then
+ exec 1>&2
+ echo $0:
+ echo " $CLASS should be in a" \
+ "directory tree called $FQCLASSP"
+ exit 1
+ fi
+ fi
+ if [ ! -L $CLASS ]; then break; fi
+ # Go down one more level of symbolic links
+ let LINKLEVEL+=1
+ if [ $LINKLEVEL -gt 5 ]; then
+ exec 1>&2
+ echo $0:
+ echo " Too many symbolic links encountered"
+ exit 1
+ fi
+ CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'`
+ done
+
+ if [ -z "$CLASSBASE" ]; then
+ if [ -z "$FQCLASSP" ]; then
+ GOODNAME=$FQCLASSN.class
+ else
+ GOODNAME=$FQCLASSP/$FQCLASSN.class
+ fi
+ exec 1>&2
+ echo $0:
+ echo " $FQCLASS should be in a file called $GOODNAME"
+ exit 1
+ fi
+
+ if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then
+ # class is not in CLASSPATH, so prepend dir of class to CLASSPATH
+ if [ -z "${CLASSPATH}" ] ; then
+ export CLASSPATH=$CLASSBASE
+ else
+ export CLASSPATH=$CLASSBASE:$CLASSPATH
+ fi
+ fi
+
+ shift
+ /usr/bin/java $FQCLASS "$@"
+
+javaclassname.c:
+
+.. code-block:: c
+
+ /* javaclassname.c
+ *
+ * Extracts the class name from a Java class file; intended for use in a Java
+ * wrapper of the type supported by the binfmt_misc option in the Linux kernel.
+ *
+ * Copyright (C) 1999 Colin J. Watson <cjw44@cam.ac.uk>.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <stdarg.h>
+ #include <sys/types.h>
+
+ /* From Sun's Java VM Specification, as tag entries in the constant pool. */
+
+ #define CP_UTF8 1
+ #define CP_INTEGER 3
+ #define CP_FLOAT 4
+ #define CP_LONG 5
+ #define CP_DOUBLE 6
+ #define CP_CLASS 7
+ #define CP_STRING 8
+ #define CP_FIELDREF 9
+ #define CP_METHODREF 10
+ #define CP_INTERFACEMETHODREF 11
+ #define CP_NAMEANDTYPE 12
+ #define CP_METHODHANDLE 15
+ #define CP_METHODTYPE 16
+ #define CP_INVOKEDYNAMIC 18
+
+ /* Define some commonly used error messages */
+
+ #define seek_error() error("%s: Cannot seek\n", program)
+ #define corrupt_error() error("%s: Class file corrupt\n", program)
+ #define eof_error() error("%s: Unexpected end of file\n", program)
+ #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program);
+
+ char *program;
+
+ long *pool;
+
+ u_int8_t read_8(FILE *classfile);
+ u_int16_t read_16(FILE *classfile);
+ void skip_constant(FILE *classfile, u_int16_t *cur);
+ void error(const char *format, ...);
+ int main(int argc, char **argv);
+
+ /* Reads in an unsigned 8-bit integer. */
+ u_int8_t read_8(FILE *classfile)
+ {
+ int b = fgetc(classfile);
+ if(b == EOF)
+ eof_error();
+ return (u_int8_t)b;
+ }
+
+ /* Reads in an unsigned 16-bit integer. */
+ u_int16_t read_16(FILE *classfile)
+ {
+ int b1, b2;
+ b1 = fgetc(classfile);
+ if(b1 == EOF)
+ eof_error();
+ b2 = fgetc(classfile);
+ if(b2 == EOF)
+ eof_error();
+ return (u_int16_t)((b1 << 8) | b2);
+ }
+
+ /* Reads in a value from the constant pool. */
+ void skip_constant(FILE *classfile, u_int16_t *cur)
+ {
+ u_int16_t len;
+ int seekerr = 1;
+ pool[*cur] = ftell(classfile);
+ switch(read_8(classfile))
+ {
+ case CP_UTF8:
+ len = read_16(classfile);
+ seekerr = fseek(classfile, len, SEEK_CUR);
+ break;
+ case CP_CLASS:
+ case CP_STRING:
+ case CP_METHODTYPE:
+ seekerr = fseek(classfile, 2, SEEK_CUR);
+ break;
+ case CP_METHODHANDLE:
+ seekerr = fseek(classfile, 3, SEEK_CUR);
+ break;
+ case CP_INTEGER:
+ case CP_FLOAT:
+ case CP_FIELDREF:
+ case CP_METHODREF:
+ case CP_INTERFACEMETHODREF:
+ case CP_NAMEANDTYPE:
+ case CP_INVOKEDYNAMIC:
+ seekerr = fseek(classfile, 4, SEEK_CUR);
+ break;
+ case CP_LONG:
+ case CP_DOUBLE:
+ seekerr = fseek(classfile, 8, SEEK_CUR);
+ ++(*cur);
+ break;
+ default:
+ corrupt_error();
+ }
+ if(seekerr)
+ seek_error();
+ }
+
+ void error(const char *format, ...)
+ {
+ va_list ap;
+ va_start(ap, format);
+ vfprintf(stderr, format, ap);
+ va_end(ap);
+ exit(1);
+ }
+
+ int main(int argc, char **argv)
+ {
+ FILE *classfile;
+ u_int16_t cp_count, i, this_class, classinfo_ptr;
+ u_int8_t length;
+
+ program = argv[0];
+
+ if(!argv[1])
+ error("%s: Missing input file\n", program);
+ classfile = fopen(argv[1], "rb");
+ if(!classfile)
+ error("%s: Error opening %s\n", program, argv[1]);
+
+ if(fseek(classfile, 8, SEEK_SET)) /* skip magic and version numbers */
+ seek_error();
+ cp_count = read_16(classfile);
+ pool = calloc(cp_count, sizeof(long));
+ if(!pool)
+ error("%s: Out of memory for constant pool\n", program);
+
+ for(i = 1; i < cp_count; ++i)
+ skip_constant(classfile, &i);
+ if(fseek(classfile, 2, SEEK_CUR)) /* skip access flags */
+ seek_error();
+
+ this_class = read_16(classfile);
+ if(this_class < 1 || this_class >= cp_count)
+ corrupt_error();
+ if(!pool[this_class] || pool[this_class] == -1)
+ corrupt_error();
+ if(fseek(classfile, pool[this_class] + 1, SEEK_SET))
+ seek_error();
+
+ classinfo_ptr = read_16(classfile);
+ if(classinfo_ptr < 1 || classinfo_ptr >= cp_count)
+ corrupt_error();
+ if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1)
+ corrupt_error();
+ if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET))
+ seek_error();
+
+ length = read_16(classfile);
+ for(i = 0; i < length; ++i)
+ {
+ u_int8_t x = read_8(classfile);
+ if((x & 0x80) || !x)
+ {
+ if((x & 0xE0) == 0xC0)
+ {
+ u_int8_t y = read_8(classfile);
+ if((y & 0xC0) == 0x80)
+ {
+ int c = ((x & 0x1f) << 6) + (y & 0x3f);
+ if(c) putchar(c);
+ else utf8_error();
+ }
+ else utf8_error();
+ }
+ else utf8_error();
+ }
+ else if(x == '/') putchar('.');
+ else putchar(x);
+ }
+ putchar('\n');
+ free(pool);
+ fclose(classfile);
+ return 0;
+ }
+
+jarwrapper::
+
+ #!/bin/bash
+ # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar
+
+ java -jar $1
+
+
+Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you
+want to execute.
+
+To add a Java program to your path best put a symbolic link to the main
+.class file into /usr/bin (or another place you like) omitting the .class
+extension. The directory containing the original .class file will be
+added to your CLASSPATH during execution.
+
+
+To test your new setup, enter in the following simple Java app, and name
+it "HelloWorld.java":
+
+.. code-block:: java
+
+ class HelloWorld {
+ public static void main(String args[]) {
+ System.out.println("Hello World!");
+ }
+ }
+
+Now compile the application with::
+
+ javac HelloWorld.java
+
+Set the executable permissions of the binary file, with::
+
+ chmod 755 HelloWorld.class
+
+And then execute it::
+
+ ./HelloWorld.class
+
+
+To execute Java Jar files, simple chmod the ``*.jar`` files to include
+the execution bit, then just do::
+
+ ./Application.jar
+
+
+To execute Java Applets, simple chmod the ``*.html`` files to include
+the execution bit, then just do::
+
+ ./Applet.html
+
+
+originally by Brian A. Lantz, brian@lantz.com
+heavily edited for binfmt_misc by Richard Günther
+new scripts by Colin J. Watson <cjw44@cam.ac.uk>
+added executable Jar file support by Kurt Huwig <kurt@iku-netz.de>
diff --git a/Documentation/admin-guide/jfs.rst b/Documentation/admin-guide/jfs.rst
new file mode 100644
index 000000000000..9e12d936bc90
--- /dev/null
+++ b/Documentation/admin-guide/jfs.rst
@@ -0,0 +1,66 @@
+===========================================
+IBM's Journaled File System (JFS) for Linux
+===========================================
+
+JFS Homepage: http://jfs.sourceforge.net/
+
+The following mount options are supported:
+
+(*) == default
+
+iocharset=name
+ Character set to use for converting from Unicode to
+ ASCII. The default is to do no conversion. Use
+ iocharset=utf8 for UTF-8 translations. This requires
+ CONFIG_NLS_UTF8 to be set in the kernel .config file.
+ iocharset=none specifies the default behavior explicitly.
+
+resize=value
+ Resize the volume to <value> blocks. JFS only supports
+ growing a volume, not shrinking it. This option is only
+ valid during a remount, when the volume is mounted
+ read-write. The resize keyword with no value will grow
+ the volume to the full size of the partition.
+
+nointegrity
+ Do not write to the journal. The primary use of this option
+ is to allow for higher performance when restoring a volume
+ from backup media. The integrity of the volume is not
+ guaranteed if the system abnormally abends.
+
+integrity(*)
+ Commit metadata changes to the journal. Use this option to
+ remount a volume where the nointegrity option was
+ previously specified in order to restore normal behavior.
+
+errors=continue
+ Keep going on a filesystem error.
+errors=remount-ro(*)
+ Remount the filesystem read-only on an error.
+errors=panic
+ Panic and halt the machine if an error occurs.
+
+uid=value
+ Override on-disk uid with specified value
+gid=value
+ Override on-disk gid with specified value
+umask=value
+ Override on-disk umask with specified octal value. For
+ directories, the execute bit will be set if the corresponding
+ read bit is set.
+
+discard=minlen, discard/nodiscard(*)
+ This enables/disables the use of discard/TRIM commands.
+ The discard/TRIM commands are sent to the underlying
+ block device when blocks are freed. This is useful for SSD
+ devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl
+ command is also available together with the nodiscard option.
+ The value of minlen specifies the minimum blockcount, when
+ a TRIM command to the block device is considered useful.
+ When no value is given to the discard option, it defaults to
+ 64 blocks, which means 256KiB in JFS.
+ The minlen value of discard overrides the minlen value given
+ on an FITRIM ioctl().
+
+The JFS mailing list can be subscribed to by using the link labeled
+"Mail list Subscribe" at our web page http://jfs.sourceforge.net/
diff --git a/Documentation/admin-guide/kdump/gdbmacros.txt b/Documentation/admin-guide/kdump/gdbmacros.txt
new file mode 100644
index 000000000000..030de95e3e6b
--- /dev/null
+++ b/Documentation/admin-guide/kdump/gdbmacros.txt
@@ -0,0 +1,323 @@
+#
+# This file contains a few gdb macros (user defined commands) to extract
+# useful information from kernel crashdump (kdump) like stack traces of
+# all the processes or a particular process and trapinfo.
+#
+# These macros can be used by copying this file in .gdbinit (put in home
+# directory or current directory) or by invoking gdb command with
+# --command=<command-file-name> option
+#
+# Credits:
+# Alexander Nyberg <alexn@telia.com>
+# V Srivatsa <vatsa@in.ibm.com>
+# Maneesh Soni <maneesh@in.ibm.com>
+#
+
+define bttnobp
+ set $tasks_off=((size_t)&((struct task_struct *)0)->tasks)
+ set $pid_off=((size_t)&((struct task_struct *)0)->thread_group.next)
+ set $init_t=&init_task
+ set $next_t=(((char *)($init_t->tasks).next) - $tasks_off)
+ set var $stacksize = sizeof(union thread_union)
+ while ($next_t != $init_t)
+ set $next_t=(struct task_struct *)$next_t
+ printf "\npid %d; comm %s:\n", $next_t.pid, $next_t.comm
+ printf "===================\n"
+ set var $stackp = $next_t.thread.sp
+ set var $stack_top = ($stackp & ~($stacksize - 1)) + $stacksize
+
+ while ($stackp < $stack_top)
+ if (*($stackp) > _stext && *($stackp) < _sinittext)
+ info symbol *($stackp)
+ end
+ set $stackp += 4
+ end
+ set $next_th=(((char *)$next_t->thread_group.next) - $pid_off)
+ while ($next_th != $next_t)
+ set $next_th=(struct task_struct *)$next_th
+ printf "\npid %d; comm %s:\n", $next_t.pid, $next_t.comm
+ printf "===================\n"
+ set var $stackp = $next_t.thread.sp
+ set var $stack_top = ($stackp & ~($stacksize - 1)) + stacksize
+
+ while ($stackp < $stack_top)
+ if (*($stackp) > _stext && *($stackp) < _sinittext)
+ info symbol *($stackp)
+ end
+ set $stackp += 4
+ end
+ set $next_th=(((char *)$next_th->thread_group.next) - $pid_off)
+ end
+ set $next_t=(char *)($next_t->tasks.next) - $tasks_off
+ end
+end
+document bttnobp
+ dump all thread stack traces on a kernel compiled with !CONFIG_FRAME_POINTER
+end
+
+define btthreadstack
+ set var $pid_task = $arg0
+
+ printf "\npid %d; comm %s:\n", $pid_task.pid, $pid_task.comm
+ printf "task struct: "
+ print $pid_task
+ printf "===================\n"
+ set var $stackp = $pid_task.thread.sp
+ set var $stacksize = sizeof(union thread_union)
+ set var $stack_top = ($stackp & ~($stacksize - 1)) + $stacksize
+ set var $stack_bot = ($stackp & ~($stacksize - 1))
+
+ set $stackp = *((unsigned long *) $stackp)
+ while (($stackp < $stack_top) && ($stackp > $stack_bot))
+ set var $addr = *(((unsigned long *) $stackp) + 1)
+ info symbol $addr
+ set $stackp = *((unsigned long *) $stackp)
+ end
+end
+document btthreadstack
+ dump a thread stack using the given task structure pointer
+end
+
+
+define btt
+ set $tasks_off=((size_t)&((struct task_struct *)0)->tasks)
+ set $pid_off=((size_t)&((struct task_struct *)0)->thread_group.next)
+ set $init_t=&init_task
+ set $next_t=(((char *)($init_t->tasks).next) - $tasks_off)
+ while ($next_t != $init_t)
+ set $next_t=(struct task_struct *)$next_t
+ btthreadstack $next_t
+
+ set $next_th=(((char *)$next_t->thread_group.next) - $pid_off)
+ while ($next_th != $next_t)
+ set $next_th=(struct task_struct *)$next_th
+ btthreadstack $next_th
+ set $next_th=(((char *)$next_th->thread_group.next) - $pid_off)
+ end
+ set $next_t=(char *)($next_t->tasks.next) - $tasks_off
+ end
+end
+document btt
+ dump all thread stack traces on a kernel compiled with CONFIG_FRAME_POINTER
+end
+
+define btpid
+ set var $pid = $arg0
+ set $tasks_off=((size_t)&((struct task_struct *)0)->tasks)
+ set $pid_off=((size_t)&((struct task_struct *)0)->thread_group.next)
+ set $init_t=&init_task
+ set $next_t=(((char *)($init_t->tasks).next) - $tasks_off)
+ set var $pid_task = 0
+
+ while ($next_t != $init_t)
+ set $next_t=(struct task_struct *)$next_t
+
+ if ($next_t.pid == $pid)
+ set $pid_task = $next_t
+ end
+
+ set $next_th=(((char *)$next_t->thread_group.next) - $pid_off)
+ while ($next_th != $next_t)
+ set $next_th=(struct task_struct *)$next_th
+ if ($next_th.pid == $pid)
+ set $pid_task = $next_th
+ end
+ set $next_th=(((char *)$next_th->thread_group.next) - $pid_off)
+ end
+ set $next_t=(char *)($next_t->tasks.next) - $tasks_off
+ end
+
+ btthreadstack $pid_task
+end
+document btpid
+ backtrace of pid
+end
+
+
+define trapinfo
+ set var $pid = $arg0
+ set $tasks_off=((size_t)&((struct task_struct *)0)->tasks)
+ set $pid_off=((size_t)&((struct task_struct *)0)->thread_group.next)
+ set $init_t=&init_task
+ set $next_t=(((char *)($init_t->tasks).next) - $tasks_off)
+ set var $pid_task = 0
+
+ while ($next_t != $init_t)
+ set $next_t=(struct task_struct *)$next_t
+
+ if ($next_t.pid == $pid)
+ set $pid_task = $next_t
+ end
+
+ set $next_th=(((char *)$next_t->thread_group.next) - $pid_off)
+ while ($next_th != $next_t)
+ set $next_th=(struct task_struct *)$next_th
+ if ($next_th.pid == $pid)
+ set $pid_task = $next_th
+ end
+ set $next_th=(((char *)$next_th->thread_group.next) - $pid_off)
+ end
+ set $next_t=(char *)($next_t->tasks.next) - $tasks_off
+ end
+
+ printf "Trapno %ld, cr2 0x%lx, error_code %ld\n", $pid_task.thread.trap_no, \
+ $pid_task.thread.cr2, $pid_task.thread.error_code
+
+end
+document trapinfo
+ Run info threads and lookup pid of thread #1
+ 'trapinfo <pid>' will tell you by which trap & possibly
+ address the kernel panicked.
+end
+
+define dump_record
+ set var $desc = $arg0
+ set var $info = $arg1
+ if ($argc > 2)
+ set var $prev_flags = $arg2
+ else
+ set var $prev_flags = 0
+ end
+
+ set var $prefix = 1
+ set var $newline = 1
+
+ set var $begin = $desc->text_blk_lpos.begin % (1U << prb->text_data_ring.size_bits)
+ set var $next = $desc->text_blk_lpos.next % (1U << prb->text_data_ring.size_bits)
+
+ # handle data-less record
+ if ($begin & 1)
+ set var $text_len = 0
+ set var $log = ""
+ else
+ # handle wrapping data block
+ if ($begin > $next)
+ set var $begin = 0
+ end
+
+ # skip over descriptor id
+ set var $begin = $begin + sizeof(long)
+
+ # handle truncated message
+ if ($next - $begin < $info->text_len)
+ set var $text_len = $next - $begin
+ else
+ set var $text_len = $info->text_len
+ end
+
+ set var $log = &prb->text_data_ring.data[$begin]
+ end
+
+ # prev & LOG_CONT && !(info->flags & LOG_PREIX)
+ if (($prev_flags & 8) && !($info->flags & 4))
+ set var $prefix = 0
+ end
+
+ # info->flags & LOG_CONT
+ if ($info->flags & 8)
+ # (prev & LOG_CONT && !(prev & LOG_NEWLINE))
+ if (($prev_flags & 8) && !($prev_flags & 2))
+ set var $prefix = 0
+ end
+ # (!(info->flags & LOG_NEWLINE))
+ if (!($info->flags & 2))
+ set var $newline = 0
+ end
+ end
+
+ if ($prefix)
+ printf "[%5lu.%06lu] ", $info->ts_nsec / 1000000000, $info->ts_nsec % 1000000000
+ end
+ if ($text_len)
+ eval "printf \"%%%d.%ds\", $log", $text_len, $text_len
+ end
+ if ($newline)
+ printf "\n"
+ end
+
+ # handle dictionary data
+
+ set var $dict = &$info->dev_info.subsystem[0]
+ set var $dict_len = sizeof($info->dev_info.subsystem)
+ if ($dict[0] != '\0')
+ printf " SUBSYSTEM="
+ set var $idx = 0
+ while ($idx < $dict_len)
+ set var $c = $dict[$idx]
+ if ($c == '\0')
+ loop_break
+ else
+ if ($c < ' ' || $c >= 127 || $c == '\\')
+ printf "\\x%02x", $c
+ else
+ printf "%c", $c
+ end
+ end
+ set var $idx = $idx + 1
+ end
+ printf "\n"
+ end
+
+ set var $dict = &$info->dev_info.device[0]
+ set var $dict_len = sizeof($info->dev_info.device)
+ if ($dict[0] != '\0')
+ printf " DEVICE="
+ set var $idx = 0
+ while ($idx < $dict_len)
+ set var $c = $dict[$idx]
+ if ($c == '\0')
+ loop_break
+ else
+ if ($c < ' ' || $c >= 127 || $c == '\\')
+ printf "\\x%02x", $c
+ else
+ printf "%c", $c
+ end
+ end
+ set var $idx = $idx + 1
+ end
+ printf "\n"
+ end
+end
+document dump_record
+ Dump a single record. The first parameter is the descriptor,
+ the second parameter is the info, the third parameter is
+ optional and specifies the previous record's flags, used for
+ properly formatting continued lines.
+end
+
+define dmesg
+ # definitions from kernel/printk/printk_ringbuffer.h
+ set var $desc_committed = 1
+ set var $desc_finalized = 2
+ set var $desc_sv_bits = sizeof(long) * 8
+ set var $desc_flags_shift = $desc_sv_bits - 2
+ set var $desc_flags_mask = 3 << $desc_flags_shift
+ set var $id_mask = ~$desc_flags_mask
+
+ set var $desc_count = 1U << prb->desc_ring.count_bits
+ set var $prev_flags = 0
+
+ set var $id = prb->desc_ring.tail_id.counter
+ set var $end_id = prb->desc_ring.head_id.counter
+
+ while (1)
+ set var $desc = &prb->desc_ring.descs[$id % $desc_count]
+ set var $info = &prb->desc_ring.infos[$id % $desc_count]
+
+ # skip non-committed record
+ set var $state = 3 & ($desc->state_var.counter >> $desc_flags_shift)
+ if ($state == $desc_committed || $state == $desc_finalized)
+ dump_record $desc $info $prev_flags
+ set var $prev_flags = $info->flags
+ end
+
+ if ($id == $end_id)
+ loop_break
+ end
+ set var $id = ($id + 1) & $id_mask
+ end
+end
+document dmesg
+ print the kernel ring buffer
+end
diff --git a/Documentation/admin-guide/kdump/index.rst b/Documentation/admin-guide/kdump/index.rst
new file mode 100644
index 000000000000..8e2ebd0383cd
--- /dev/null
+++ b/Documentation/admin-guide/kdump/index.rst
@@ -0,0 +1,20 @@
+
+================================================================
+Documentation for Kdump - The kexec-based Crash Dumping Solution
+================================================================
+
+This document includes overview, setup and installation, and analysis
+information.
+
+.. toctree::
+ :maxdepth: 1
+
+ kdump
+ vmcoreinfo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst
new file mode 100644
index 000000000000..7b011eb116a7
--- /dev/null
+++ b/Documentation/admin-guide/kdump/kdump.rst
@@ -0,0 +1,612 @@
+================================================================
+Documentation for Kdump - The kexec-based Crash Dumping Solution
+================================================================
+
+This document includes overview, setup, installation, and analysis
+information.
+
+Overview
+========
+
+Kdump uses kexec to quickly boot to a dump-capture kernel whenever a
+dump of the system kernel's memory needs to be taken (for example, when
+the system panics). The system kernel's memory image is preserved across
+the reboot and is accessible to the dump-capture kernel.
+
+You can use common commands, such as cp, scp or makedumpfile to copy
+the memory image to a dump file on the local disk, or across the network
+to a remote system.
+
+Kdump and kexec are currently supported on the x86, x86_64, ppc64,
+s390x, arm and arm64 architectures.
+
+When the system kernel boots, it reserves a small section of memory for
+the dump-capture kernel. This ensures that ongoing Direct Memory Access
+(DMA) from the system kernel does not corrupt the dump-capture kernel.
+The kexec -p command loads the dump-capture kernel into this reserved
+memory.
+
+On x86 machines, the first 640 KB of physical memory is needed for boot,
+regardless of where the kernel loads. For simpler handling, the whole
+low 1M is reserved to avoid any later kernel or device driver writing
+data into this area. Like this, the low 1M can be reused as system RAM
+by kdump kernel without extra handling.
+
+On PPC64 machines first 32KB of physical memory is needed for booting
+regardless of where the kernel is loaded and to support 64K page size
+kexec backs up the first 64KB memory.
+
+For s390x, when kdump is triggered, the crashkernel region is exchanged
+with the region [0, crashkernel region size] and then the kdump kernel
+runs in [0, crashkernel region size]. Therefore no relocatable kernel is
+needed for s390x.
+
+All of the necessary information about the system kernel's core image is
+encoded in the ELF format, and stored in a reserved area of memory
+before a crash. The physical address of the start of the ELF header is
+passed to the dump-capture kernel through the elfcorehdr= boot
+parameter. Optionally the size of the ELF header can also be passed
+when using the elfcorehdr=[size[KMG]@]offset[KMG] syntax.
+
+With the dump-capture kernel, you can access the memory image through
+/proc/vmcore. This exports the dump as an ELF-format file that you can
+write out using file copy commands such as cp or scp. You can also use
+makedumpfile utility to analyze and write out filtered contents with
+options, e.g with '-d 31' it will only write out kernel data. Further,
+you can use analysis tools such as the GNU Debugger (GDB) and the Crash
+tool to debug the dump file. This method ensures that the dump pages are
+correctly ordered.
+
+Setup and Installation
+======================
+
+Install kexec-tools
+-------------------
+
+1) Login as the root user.
+
+2) Download the kexec-tools user-space package from the following URL:
+
+http://kernel.org/pub/linux/utils/kernel/kexec/kexec-tools.tar.gz
+
+This is a symlink to the latest version.
+
+The latest kexec-tools git tree is available at:
+
+- git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+
+There is also a gitweb interface available at
+http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
+
+More information about kexec-tools can be found at
+http://horms.net/projects/kexec/
+
+3) Unpack the tarball with the tar command, as follows::
+
+ tar xvpzf kexec-tools.tar.gz
+
+4) Change to the kexec-tools directory, as follows::
+
+ cd kexec-tools-VERSION
+
+5) Configure the package, as follows::
+
+ ./configure
+
+6) Compile the package, as follows::
+
+ make
+
+7) Install the package, as follows::
+
+ make install
+
+
+Build the system and dump-capture kernels
+-----------------------------------------
+There are two possible methods of using Kdump.
+
+1) Build a separate custom dump-capture kernel for capturing the
+ kernel core dump.
+
+2) Or use the system kernel binary itself as dump-capture kernel and there is
+ no need to build a separate dump-capture kernel. This is possible
+ only with the architectures which support a relocatable kernel. As
+ of today, i386, x86_64, ppc64, arm and arm64 architectures support
+ relocatable kernel.
+
+Building a relocatable kernel is advantageous from the point of view that
+one does not have to build a second kernel for capturing the dump. But
+at the same time one might want to build a custom dump capture kernel
+suitable to his needs.
+
+Following are the configuration setting required for system and
+dump-capture kernels for enabling kdump support.
+
+System kernel config options
+----------------------------
+
+1) Enable "kexec system call" or "kexec file based system call" in
+ "Processor type and features."::
+
+ CONFIG_KEXEC=y or CONFIG_KEXEC_FILE=y
+
+ And both of them will select KEXEC_CORE::
+
+ CONFIG_KEXEC_CORE=y
+
+2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
+ filesystems." This is usually enabled by default::
+
+ CONFIG_SYSFS=y
+
+ Note that "sysfs file system support" might not appear in the "Pseudo
+ filesystems" menu if "Configure standard kernel features (expert users)"
+ is not enabled in "General Setup." In this case, check the .config file
+ itself to ensure that sysfs is turned on, as follows::
+
+ grep 'CONFIG_SYSFS' .config
+
+3) Enable "Compile the kernel with debug info" in "Kernel hacking."::
+
+ CONFIG_DEBUG_INFO=Y
+
+ This causes the kernel to be built with debug symbols. The dump
+ analysis tools require a vmlinux with debug symbols in order to read
+ and analyze a dump file.
+
+Dump-capture kernel config options (Arch Independent)
+-----------------------------------------------------
+
+1) Enable "kernel crash dumps" support under "Processor type and
+ features"::
+
+ CONFIG_CRASH_DUMP=y
+
+ And this will select VMCORE_INFO and CRASH_RESERVE::
+ CONFIG_VMCORE_INFO=y
+ CONFIG_CRASH_RESERVE=y
+
+2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems"::
+
+ CONFIG_PROC_VMCORE=y
+
+ (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
+
+Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
+--------------------------------------------------------------------
+
+1) On i386, enable high memory support under "Processor type and
+ features"::
+
+ CONFIG_HIGHMEM4G
+
+2) With CONFIG_SMP=y, usually nr_cpus=1 need specified on the kernel
+ command line when loading the dump-capture kernel because one
+ CPU is enough for kdump kernel to dump vmcore on most of systems.
+
+ However, you can also specify nr_cpus=X to enable multiple processors
+ in kdump kernel.
+
+ With CONFIG_SMP=n, the above things are not related.
+
+3) A relocatable kernel is suggested to be built by default. If not yet,
+ enable "Build a relocatable kernel" support under "Processor type and
+ features"::
+
+ CONFIG_RELOCATABLE=y
+
+4) Use a suitable value for "Physical address where the kernel is
+ loaded" (under "Processor type and features"). This only appears when
+ "kernel crash dumps" is enabled. A suitable value depends upon
+ whether kernel is relocatable or not.
+
+ If you are using a relocatable kernel use CONFIG_PHYSICAL_START=0x100000
+ This will compile the kernel for physical address 1MB, but given the fact
+ kernel is relocatable, it can be run from any physical address hence
+ kexec boot loader will load it in memory region reserved for dump-capture
+ kernel.
+
+ Otherwise it should be the start of memory region reserved for
+ second kernel using boot parameter "crashkernel=Y@X". Here X is
+ start of memory region reserved for dump-capture kernel.
+ Generally X is 16MB (0x1000000). So you can set
+ CONFIG_PHYSICAL_START=0x1000000
+
+5) Make and install the kernel and its modules. DO NOT add this kernel
+ to the boot loader configuration files.
+
+Dump-capture kernel config options (Arch Dependent, ppc64)
+----------------------------------------------------------
+
+1) Enable "Build a kdump crash kernel" support under "Kernel" options::
+
+ CONFIG_CRASH_DUMP=y
+
+2) Enable "Build a relocatable kernel" support::
+
+ CONFIG_RELOCATABLE=y
+
+ Make and install the kernel and its modules.
+
+Dump-capture kernel config options (Arch Dependent, arm)
+----------------------------------------------------------
+
+- To use a relocatable kernel,
+ Enable "AUTO_ZRELADDR" support under "Boot" options::
+
+ AUTO_ZRELADDR=y
+
+Dump-capture kernel config options (Arch Dependent, arm64)
+----------------------------------------------------------
+
+- Please note that kvm of the dump-capture kernel will not be enabled
+ on non-VHE systems even if it is configured. This is because the CPU
+ will not be reset to EL2 on panic.
+
+crashkernel syntax
+===========================
+1) crashkernel=size@offset
+
+ Here 'size' specifies how much memory to reserve for the dump-capture kernel
+ and 'offset' specifies the beginning of this reserved memory. For example,
+ "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory
+ starting at physical address 0x01000000 (16MB) for the dump-capture kernel.
+
+ The crashkernel region can be automatically placed by the system
+ kernel at run time. This is done by specifying the base address as 0,
+ or omitting it all together::
+
+ crashkernel=256M@0
+
+ or::
+
+ crashkernel=256M
+
+ If the start address is specified, note that the start address of the
+ kernel will be aligned to a value (which is Arch dependent), so if the
+ start address is not then any space below the alignment point will be
+ wasted.
+
+2) range1:size1[,range2:size2,...][@offset]
+
+ While the "crashkernel=size[@offset]" syntax is sufficient for most
+ configurations, sometimes it's handy to have the reserved memory dependent
+ on the value of System RAM -- that's mostly for distributors that pre-setup
+ the kernel command line to avoid a unbootable system after some memory has
+ been removed from the machine.
+
+ The syntax is::
+
+ crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
+ range=start-[end]
+
+ For example::
+
+ crashkernel=512M-2G:64M,2G-:128M
+
+ This would mean:
+
+ 1) if the RAM is smaller than 512M, then don't reserve anything
+ (this is the "rescue" case)
+ 2) if the RAM size is between 512M and 2G (exclusive), then reserve 64M
+ 3) if the RAM size is larger than 2G, then reserve 128M
+
+3) crashkernel=size,high and crashkernel=size,low
+
+ If memory above 4G is preferred, crashkernel=size,high can be used to
+ fulfill that. With it, physical memory is allowed to be allocated from top,
+ so could be above 4G if system has more than 4G RAM installed. Otherwise,
+ memory region will be allocated below 4G if available.
+
+ When crashkernel=X,high is passed, kernel could allocate physical memory
+ region above 4G, low memory under 4G is needed in this case. There are
+ three ways to get low memory:
+
+ 1) Kernel will allocate at least 256M memory below 4G automatically
+ if crashkernel=Y,low is not specified.
+ 2) Let user specify low memory size instead.
+ 3) Specified value 0 will disable low memory allocation::
+
+ crashkernel=0,low
+
+4) crashkernel=size,cma
+
+ Reserve additional crash kernel memory from CMA. This reservation is
+ usable by the first system's userspace memory and kernel movable
+ allocations (memory balloon, zswap). Pages allocated from this memory
+ range will not be included in the vmcore so this should not be used if
+ dumping of userspace memory is intended and it has to be expected that
+ some movable kernel pages may be missing from the dump.
+
+ A standard crashkernel reservation, as described above, is still needed
+ to hold the crash kernel and initrd.
+
+ This option increases the risk of a kdump failure: DMA transfers
+ configured by the first kernel may end up corrupting the second
+ kernel's memory.
+
+ This reservation method is intended for systems that can't afford to
+ sacrifice enough memory for standard crashkernel reservation and where
+ less reliable and possibly incomplete kdump is preferable to no kdump at
+ all.
+
+Boot into System Kernel
+-----------------------
+1) Update the boot loader (such as grub, yaboot, or lilo) configuration
+ files as necessary.
+
+2) Boot the system kernel with the boot parameter "crashkernel=Y@X".
+
+ On x86 and x86_64, use "crashkernel=Y[@X]". Most of the time, the
+ start address 'X' is not necessary, kernel will search a suitable
+ area. Unless an explicit start address is expected.
+
+ On ppc64, use "crashkernel=128M@32M".
+
+ On s390x, typically use "crashkernel=xxM". The value of xx is dependent
+ on the memory consumption of the kdump system. In general this is not
+ dependent on the memory size of the production system.
+
+ On arm, the use of "crashkernel=Y@X" is no longer necessary; the
+ kernel will automatically locate the crash kernel image within the
+ first 512MB of RAM if X is not given.
+
+ On arm64, use "crashkernel=Y[@X]". Note that the start address of
+ the kernel, X if explicitly specified, must be aligned to 2MiB (0x200000).
+
+Load the Dump-capture Kernel
+============================
+
+After booting to the system kernel, dump-capture kernel needs to be
+loaded.
+
+Based on the architecture and type of image (relocatable or not), one
+can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
+of dump-capture kernel. Following is the summary.
+
+For i386 and x86_64:
+
+ - Use bzImage/vmlinuz if kernel is relocatable.
+ - Use vmlinux if kernel is not relocatable.
+
+For ppc64:
+
+ - Use vmlinux
+
+For s390x:
+
+ - Use image or bzImage
+
+For arm:
+
+ - Use zImage
+
+For arm64:
+
+ - Use vmlinux or Image
+
+If you are using an uncompressed vmlinux image then use following command
+to load dump-capture kernel::
+
+ kexec -p <dump-capture-kernel-vmlinux-image> \
+ --initrd=<initrd-for-dump-capture-kernel> --args-linux \
+ --append="root=<root-dev> <arch-specific-options>"
+
+If you are using a compressed bzImage/vmlinuz, then use following command
+to load dump-capture kernel::
+
+ kexec -p <dump-capture-kernel-bzImage> \
+ --initrd=<initrd-for-dump-capture-kernel> \
+ --append="root=<root-dev> <arch-specific-options>"
+
+If you are using a compressed zImage, then use following command
+to load dump-capture kernel::
+
+ kexec --type zImage -p <dump-capture-kernel-bzImage> \
+ --initrd=<initrd-for-dump-capture-kernel> \
+ --dtb=<dtb-for-dump-capture-kernel> \
+ --append="root=<root-dev> <arch-specific-options>"
+
+If you are using an uncompressed Image, then use following command
+to load dump-capture kernel::
+
+ kexec -p <dump-capture-kernel-Image> \
+ --initrd=<initrd-for-dump-capture-kernel> \
+ --append="root=<root-dev> <arch-specific-options>"
+
+Following are the arch specific command line options to be used while
+loading dump-capture kernel.
+
+For i386 and x86_64:
+
+ "1 irqpoll nr_cpus=1 reset_devices"
+
+For ppc64:
+
+ "1 maxcpus=1 noirqdistrib reset_devices"
+
+For s390x:
+
+ "1 nr_cpus=1 cgroup_disable=memory"
+
+For arm:
+
+ "1 maxcpus=1 reset_devices"
+
+For arm64:
+
+ "1 nr_cpus=1 reset_devices"
+
+Notes on loading the dump-capture kernel:
+
+* By default, the ELF headers are stored in ELF64 format to support
+ systems with more than 4GB memory. On i386, kexec automatically checks if
+ the physical RAM size exceeds the 4 GB limit and if not, uses ELF32.
+ So, on non-PAE systems, ELF32 is always used.
+
+ The --elf32-core-headers option can be used to force the generation of ELF32
+ headers. This is necessary because GDB currently cannot open vmcore files
+ with ELF64 headers on 32-bit systems.
+
+* The "irqpoll" boot parameter reduces driver initialization failures
+ due to shared interrupts in the dump-capture kernel.
+
+* You must specify <root-dev> in the format corresponding to the root
+ device name in the output of mount command.
+
+* Boot parameter "1" boots the dump-capture kernel into single-user
+ mode without networking. If you want networking, use "3".
+
+* We generally don't have to bring up a SMP kernel just to capture the
+ dump. Hence generally it is useful either to build a UP dump-capture
+ kernel or specify maxcpus=1 option while loading dump-capture kernel.
+ Note, though maxcpus always works, you had better replace it with
+ nr_cpus to save memory if supported by the current ARCH, such as x86.
+
+* You should enable multi-cpu support in dump-capture kernel if you intend
+ to use multi-thread programs with it, such as parallel dump feature of
+ makedumpfile. Otherwise, the multi-thread program may have a great
+ 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 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
+ second mode has the advantage that for CPU and memory hotplug, kdump has
+ not to be reloaded with kexec_load().
+
+* For s390x systems with many attached devices the "cio_ignore" kernel
+ parameter should be used for the kdump kernel in order to prevent allocation
+ of kernel memory for devices that are not relevant for kdump. The same
+ applies to systems that use SCSI/FCP devices. In that case the
+ "allow_lun_scan" zfcp module parameter should be set to zero before
+ setting FCP devices online.
+
+Kernel Panic
+============
+
+After successfully loading the dump-capture kernel as previously
+described, the system will reboot into the dump-capture kernel if a
+system crash is triggered. Trigger points are located in panic(),
+die(), die_nmi() and in the sysrq handler (ALT-SysRq-c).
+
+The following conditions will execute a crash trigger point:
+
+If a hard lockup is detected and "NMI watchdog" is configured, the system
+will boot into the dump-capture kernel ( die_nmi() ).
+
+If die() is called, and it happens to be a thread with pid 0 or 1, or die()
+is called inside interrupt context or die() is called and panic_on_oops is set,
+the system will boot into the dump-capture kernel.
+
+On powerpc systems when a soft-reset is generated, die() is called by all cpus
+and the system will boot into the dump-capture kernel.
+
+For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
+"echo c > /proc/sysrq-trigger" or write a module to force the panic.
+
+Write Out the Dump File
+=======================
+
+After the dump-capture kernel is booted, write out the dump file with
+the following command::
+
+ cp /proc/vmcore <dump-file>
+
+or use scp to write out the dump file between hosts on a network, e.g::
+
+ scp /proc/vmcore remote_username@remote_ip:<dump-file>
+
+You can also use makedumpfile utility to write out the dump file
+with specified options to filter out unwanted contents, e.g::
+
+ makedumpfile -l --message-level 1 -d 31 /proc/vmcore <dump-file>
+
+Analysis
+========
+
+Before analyzing the dump image, you should reboot into a stable kernel.
+
+You can do limited analysis using GDB on the dump file copied out of
+/proc/vmcore. Use the debug vmlinux built with -g and run the following
+command::
+
+ gdb vmlinux <dump-file>
+
+Stack trace for the task on processor 0, register display, and memory
+display work fine.
+
+Note: GDB cannot analyze core files generated in ELF64 format for x86.
+On systems with a maximum of 4GB of memory, you can generate
+ELF32-format headers using the --elf32-core-headers kernel option on the
+dump kernel.
+
+You can also use the Crash utility to analyze dump files in Kdump
+format. Crash is available at the following URL:
+
+ https://github.com/crash-utility/crash
+
+Crash document can be found at:
+ https://crash-utility.github.io/
+
+Trigger Kdump on WARN()
+=======================
+
+The kernel parameter, panic_on_warn, calls panic() in all WARN() paths. This
+will cause a kdump to occur at the panic() call. In cases where a user wants
+to specify this during runtime, /proc/sys/kernel/panic_on_warn can be set to 1
+to achieve the same behaviour.
+
+Trigger Kdump on add_taint()
+============================
+
+The kernel parameter panic_on_taint facilitates a conditional call to panic()
+from within add_taint() whenever the value set in this bitmask matches with the
+bit flag being set by add_taint().
+This will cause a kdump to occur at the add_taint()->panic() call.
+
+Write the dump file to encrypted disk volume
+============================================
+
+CONFIG_CRASH_DM_CRYPT can be enabled to support saving the dump file to an
+encrypted disk volume (only x86_64 supported for now). User space can interact
+with /sys/kernel/config/crash_dm_crypt_keys for setup,
+
+1. Tell the first kernel what logon keys are needed to unlock the disk volumes,
+ # Add key #1
+ mkdir /sys/kernel/config/crash_dm_crypt_keys/7d26b7b4-e342-4d2d-b660-7426b0996720
+ # Add key #1's description
+ echo cryptsetup:7d26b7b4-e342-4d2d-b660-7426b0996720 > /sys/kernel/config/crash_dm_crypt_keys/description
+
+ # how many keys do we have now?
+ cat /sys/kernel/config/crash_dm_crypt_keys/count
+ 1
+
+ # Add key #2 in the same way
+
+ # how many keys do we have now?
+ cat /sys/kernel/config/crash_dm_crypt_keys/count
+ 2
+
+ # To support CPU/memory hot-plugging, re-use keys already saved to reserved
+ # memory
+ echo true > /sys/kernel/config/crash_dm_crypt_key/reuse
+
+2. Load the dump-capture kernel
+
+3. After the dump-capture kerne get booted, restore the keys to user keyring
+ echo yes >when set
-
-Existing signal numbers for the DB8500 ASIC. Unless specified, the signals are
-bidirectional, i.e. the same for RX and TX operations:
-
-0: SPI controller 0
-1: SD/MMC controller 0 (unused)
-2: SD/MMC controller 1 (unused)
-3: SD/MMC controller 2 (unused)
-4: I2C port 1
-5: I2C port 3
-6: I2C port 2
-7: I2C port 4
-8: Synchronous Serial Port SSP0
-9: Synchronous Serial Port SSP1
-10: Multi-Channel Display Engine MCDE RX
-11: UART port 2
-12: UART port 1
-13: UART port 0
-14: Multirate Serial Port MSP2
-15: I2C port 0
-16: USB OTG in/out endpoints 7 & 15
-17: USB OTG in/out endpoints 6 & 14
-18: USB OTG in/out endpoints 5 & 13
-19: USB OTG in/out endpoints 4 & 12
-20: SLIMbus or HSI channel 0
-21: SLIMbus or HSI channel 1
-22: SLIMbus or HSI channel 2
-23: SLIMbus or HSI channel 3
-24: Multimedia DSP SXA0
-25: Multimedia DSP SXA1
-26: Multimedia DSP SXA2
-27: Multimedia DSP SXA3
-28: SD/MM controller 2
-29: SD/MM controller 0
-30: MSP port 1 on DB8500 v1, MSP port 3 on DB8500 v2
-31: MSP port 0 or SLIMbus channel 0
-32: SD/MM controller 1
-33: SPI controller 2
-34: i2c3 RX2 TX2
-35: SPI controller 1
-36: USB OTG in/out endpoints 3 & 11
-37: USB OTG in/out endpoints 2 & 10
-38: USB OTG in/out endpoints 1 & 9
-39: USB OTG in/out endpoints 8
-40: SPI controller 3
-41: SD/MM controller 3
-42: SD/MM controller 4
-43: SD/MM controller 5
-44: Multimedia DSP SXA4
-45: Multimedia DSP SXA5
-46: SLIMbus channel 8 or Multimedia DSP SXA6
-47: SLIMbus channel 9 or Multimedia DSP SXA7
-48: Crypto Accelerator 1
-49: Crypto Accelerator 1 TX or Hash Accelerator 1 TX
-50: Hash Accelerator 1 TX
-51: memcpy TX (to be used by the DMA driver for memcpy operations)
-52: SLIMbus or HSI channel 4
-53: SLIMbus or HSI channel 5
-54: SLIMbus or HSI channel 6
-55: SLIMbus or HSI channel 7
-56: memcpy (to be used by the DMA driver for memcpy operations)
-57: memcpy (to be used by the DMA driver for memcpy operations)
-58: memcpy (to be used by the DMA driver for memcpy operations)
-59: memcpy (to be used by the DMA driver for memcpy operations)
-60: memcpy (to be used by the DMA driver for memcpy operations)
-61: Crypto Accelerator 0
-62: Crypto Accelerator 0 TX or Hash Accelerator 0 TX
-63: Hash Accelerator 0 TX
-
-Example:
-
- uart@80120000 {
- compatible = "arm,pl011", "arm,primecell";
- reg = <0x80120000 0x1000>;
- interrupts = <0 11 0x4>;
-
- dmas = <&dma 13 0 0x2>, /* Logical - DevToMem */
- <&dma 13 0 0x0>; /* Logical - MemToDev */
- dma-names = "rx", "rx";
-
- };
diff --git a/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml b/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml
new file mode 100644
index 000000000000..8b42d9880400
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/stericsson,dma40.yaml
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/stericsson,dma40.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST-Ericsson DMA40 DMA Engine
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+allOf:
+ - $ref: dma-controller.yaml#
+
+properties:
+ "#dma-cells":
+ const: 3
+ description: |
+ The first cell is the unique device channel number as indicated by this
+ table for DB8500 which is the only ASIC known to use DMA40:
+
+ 0: SPI controller 0
+ 1: SD/MMC controller 0 (unused)
+ 2: SD/MMC controller 1 (unused)
+ 3: SD/MMC controller 2 (unused)
+ 4: I2C port 1
+ 5: I2C port 3
+ 6: I2C port 2
+ 7: I2C port 4
+ 8: Synchronous Serial Port SSP0
+ 9: Synchronous Serial Port SSP1
+ 10: Multi-Channel Display Engine MCDE RX
+ 11: UART port 2
+ 12: UART port 1
+ 13: UART port 0
+ 14: Multirate Serial Port MSP2
+ 15: I2C port 0
+ 16: USB OTG in/out endpoints 7 & 15
+ 17: USB OTG in/out endpoints 6 & 14
+ 18: USB OTG in/out endpoints 5 & 13
+ 19: USB OTG in/out endpoints 4 & 12
+ 20: SLIMbus or HSI channel 0
+ 21: SLIMbus or HSI channel 1
+ 22: SLIMbus or HSI channel 2
+ 23: SLIMbus or HSI channel 3
+ 24: Multimedia DSP SXA0
+ 25: Multimedia DSP SXA1
+ 26: Multimedia DSP SXA2
+ 27: Multimedia DSP SXA3
+ 28: SD/MMC controller 2
+ 29: SD/MMC controller 0
+ 30: MSP port 1 on DB8500 v1, MSP port 3 on DB8500 v2
+ 31: MSP port 0 or SLIMbus channel 0
+ 32: SD/MMC controller 1
+ 33: SPI controller 2
+ 34: i2c3 RX2 TX2
+ 35: SPI controller 1
+ 36: USB OTG in/out endpoints 3 & 11
+ 37: USB OTG in/out endpoints 2 & 10
+ 38: USB OTG in/out endpoints 1 & 9
+ 39: USB OTG in/out endpoints 8
+ 40: SPI controller 3
+ 41: SD/MMC controller 3
+ 42: SD/MMC controller 4
+ 43: SD/MMC controller 5
+ 44: Multimedia DSP SXA4
+ 45: Multimedia DSP SXA5
+ 46: SLIMbus channel 8 or Multimedia DSP SXA6
+ 47: SLIMbus channel 9 or Multimedia DSP SXA7
+ 48: Crypto Accelerator 1
+ 49: Crypto Accelerator 1 TX or Hash Accelerator 1 TX
+ 50: Hash Accelerator 1 TX
+ 51: memcpy TX (to be used by the DMA driver for memcpy operations)
+ 52: SLIMbus or HSI channel 4
+ 53: SLIMbus or HSI channel 5
+ 54: SLIMbus or HSI channel 6
+ 55: SLIMbus or HSI channel 7
+ 56: memcpy (to be used by the DMA driver for memcpy operations)
+ 57: memcpy (to be used by the DMA driver for memcpy operations)
+ 58: memcpy (to be used by the DMA driver for memcpy operations)
+ 59: memcpy (to be used by the DMA driver for memcpy operations)
+ 60: memcpy (to be used by the DMA driver for memcpy operations)
+ 61: Crypto Accelerator 0
+ 62: Crypto Accelerator 0 TX or Hash Accelerator 0 TX
+ 63: Hash Accelerator 0 TX
+
+ The second cell is the DMA request line number. This is only used when
+ a fixed channel is allocated, and indicated by setting bit 3 in the
+ flags field (see below).
+
+ The third cell is a 32bit flags bitfield with the following possible
+ bits set:
+ 0x00000001 (bit 0) - mode:
+ Logical channel when unset
+ Physical channel when set
+ 0x00000002 (bit 1) - direction:
+ Memory to Device when unset
+ Device to Memory when set
+ 0x00000004 (bit 2) - endianness:
+ Little endian when unset
+ Big endian when set
+ 0x00000008 (bit 3) - use fixed channel:
+ Use automatic channel selection when unset
+ Use DMA request line number when set
+ 0x00000010 (bit 4) - set channel as high priority:
+ Normal priority when unset
+ High priority when set
+
+ compatible:
+ items:
+ - const: stericsson,db8500-dma40
+ - const: stericsson,dma40
+
+ reg:
+ oneOf:
+ - items:
+ - description: DMA40 memory base
+ - items:
+ - description: DMA40 memory base
+ - description: LCPA memory base, deprecated, use eSRAM pool instead
+ deprecated: true
+
+ reg-names:
+ oneOf:
+ - items:
+ - const: base
+ - items:
+ - const: base
+ - const: lcpa
+ deprecated: true
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ sram:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ description: A phandle array with inner size 1 (no arg cells).
+ First phandle is the LCPA (Logical Channel Parameter Address) memory.
+ Second phandle is the LCLA (Logical Channel Link base Address) memory.
+ maxItems: 2
+ items:
+ maxItems: 1
+
+ memcpy-channels:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: Array of u32 elements indicating which channels on the DMA
+ engine are eligible for memcpy transfers
+
+required:
+ - "#dma-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - sram
+ - memcpy-channels
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/mfd/dbx500-prcmu.h>
+ dma-controller@801c0000 {
+ compatible = "stericsson,db8500-dma40", "stericsson,dma40";
+ reg = <0x801c0000 0x1000>;
+ reg-names = "base";
+ sram = <&lcpa>, <&lcla>;
+ interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>;
+ #dma-cells = <3>;
+ memcpy-channels = <56 57 58 59 60>;
+ clocks = <&prcmu_clk PRCMU_DMACLK>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml
index 2a5325f480f6..598903354196 100644
--- a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml
+++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: http://devicetree.org/schemas/dma/st,stm32-dma.yaml#
+$id: http://devicetree.org/schemas/dma/stm32/st,stm32-dma.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 DMA Controller bindings
+title: STMicroelectronics STM32 DMA Controller
description: |
The STM32 DMA is a general-purpose direct memory access controller capable of
@@ -40,13 +40,19 @@ description: |
0x0: FIFO mode with threshold selectable with bit 0-1
0x1: Direct mode: each DMA request immediately initiates a transfer
from/to the memory, FIFO is bypassed.
-
+ -bit 4: alternative DMA request/acknowledge protocol
+ 0x0: Use standard DMA ACK management, where ACK signal is maintained
+ up to the removal of request and transfer completion
+ 0x1: Use alternative DMA ACK management, where ACK de-assertion does
+ not wait for the de-assertion of the REQuest, ACK is only managed
+ by transfer completion. This must only be used on channels
+ managing transfers for STM32 USART/UART.
maintainers:
- - Amelie Delaunay <amelie.delaunay@st.com>
+ - Amelie Delaunay <amelie.delaunay@foss.st.com>
allOf:
- - $ref: "dma-controller.yaml#"
+ - $ref: /schemas/dma/dma-controller.yaml#
properties:
"#dma-cells":
@@ -75,6 +81,10 @@ properties:
description: if defined, it indicates that the controller
supports memory-to-memory transfer
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dma3.yaml b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dma3.yaml
new file mode 100644
index 000000000000..36f9fe860eb9
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dma3.yaml
@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/stm32/st,stm32-dma3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STM32 DMA3 Controller
+
+description: |
+ The STM32 DMA3 is a direct memory access controller with different features
+ depending on its hardware configuration.
+ It is either called LPDMA (Low Power), GPDMA (General Purpose) or HPDMA (High
+ Performance).
+ Its hardware configuration registers allow to dynamically expose its features.
+
+ GPDMA and HPDMA support 16 independent DMA channels, while only 4 for LPDMA.
+ GPDMA and HPDMA support 256 DMA requests from peripherals, 8 for LPDMA.
+
+ Bindings are generic for these 3 STM32 DMA3 configurations.
+
+ DMA clients connected to the STM32 DMA3 controller must use the format
+ described in "#dma-cells" property description below, using a three-cell
+ specifier for each channel.
+
+maintainers:
+ - Amelie Delaunay <amelie.delaunay@foss.st.com>
+
+allOf:
+ - $ref: /schemas/dma/dma-controller.yaml#
+
+properties:
+ compatible:
+ const: st,stm32mp25-dma3
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 4
+ maxItems: 16
+ description:
+ Should contain all of the per-channel DMA interrupts in ascending order
+ with respect to the DMA channel index.
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ "#dma-cells":
+ const: 3
+ description: |
+ Specifies the number of cells needed to provide DMA controller specific
+ information.
+ The first cell is the request line number.
+ The second cell is a 32-bit mask specifying the DMA channel requirements:
+ -bit 0-1: The priority level
+ 0x0: low priority, low weight
+ 0x1: low priority, mid weight
+ 0x2: low priority, high weight
+ 0x3: high priority
+ -bit 4-7: The FIFO requirement for queuing source/destination transfers
+ 0x0: no FIFO requirement/any channel can fit
+ 0x2: FIFO of 8 bytes (2^2+1)
+ 0x4: FIFO of 32 bytes (2^4+1)
+ 0x6: FIFO of 128 bytes (2^6+1)
+ 0x7: FIFO of 256 bytes (2^7+1)
+ The third cell is a 32-bit mask specifying the DMA transfer requirements:
+ -bit 0: The source incrementing burst
+ 0x0: fixed burst
+ 0x1: contiguously incremented burst
+ -bit 1: The source allocated port
+ 0x0: port 0 is allocated to the source transfer
+ 0x1: port 1 is allocated to the source transfer
+ -bit 4: The destination incrementing burst
+ 0x0: fixed burst
+ 0x1: contiguously incremented burst
+ -bit 5: The destination allocated port
+ 0x0: port 0 is allocated to the destination transfer
+ 0x1: port 1 is allocated to the destination transfer
+ -bit 8: The type of hardware request
+ 0x0: burst
+ 0x1: block
+ -bit 9: The control mode
+ 0x0: DMA controller control mode
+ 0x1: peripheral control mode
+ -bit 12-13: The transfer complete event mode
+ 0x0: at block level, transfer complete event is generated at the end
+ of a block
+ 0x2: at LLI level, the transfer complete event is generated at the end
+ of the LLI transfer
+ including the update of the LLI if any
+ 0x3: at channel level, the transfer complete event is generated at the
+ end of the last LLI
+ -bit 16: Prevent packing/unpacking mode
+ 0x0: pack/unpack enabled when source data width/burst != destination data width/burst
+ 0x1: memory data width/burst forced to peripheral data width/burst to prevent pack/unpack
+ -bit 17: Prevent additional transfers due to linked-list refactoring
+ 0x0: don't prevent additional transfers for optimal performance
+ 0x1: prevent additional transfer to accommodate user constraints such as single transfer
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - "#dma-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/st,stm32mp25-rcc.h>
+ dma-controller@40400000 {
+ compatible = "st,stm32mp25-dma3";
+ reg = <0x40400000 0x1000>;
+ interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 45 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 46 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 47 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&rcc CK_BUS_HPDMA1>;
+ #dma-cells = <3>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
new file mode 100644
index 000000000000..b7bca1a83769
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/stm32/st,stm32-dmamux.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STM32 DMA MUX (DMA request router)
+
+maintainers:
+ - Amelie Delaunay <amelie.delaunay@foss.st.com>
+
+allOf:
+ - $ref: /schemas/dma/dma-router.yaml#
+
+properties:
+ "#dma-cells":
+ const: 3
+ description: |
+ Each cell represents the following:
+ 1. The mux input number/line for the request
+ 2. Bitfield representing DMA channel configuration that is passed
+ to the real DMA controller
+ 3. Bitfield representing device dependent DMA features passed to
+ the real DMA controller
+
+ For bitfield definitions of cells 2 and 3, see the associated
+ bindings doc for the actual DMA controller in st,stm32-dma.yaml.
+
+ compatible:
+ const: st,stm32h7-dmamux
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+ - reg
+ - dma-masters
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stm32mp1-clks.h>
+ #include <dt-bindings/reset/stm32mp1-resets.h>
+ dma-router@40020800 {
+ compatible = "st,stm32h7-dmamux";
+ reg = <0x40020800 0x3c>;
+ #dma-cells = <3>;
+ dma-requests = <128>;
+ dma-channels = <16>;
+ dma-masters = <&dma1>, <&dma2>;
+ clocks = <&timer_clk>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/dma/st,stm32-mdma.yaml b/Documentation/devicetree/bindings/dma/stm32/st,stm32-mdma.yaml
index c30be840be1c..45fe91db11db 100644
--- a/Documentation/devicetree/bindings/dma/st,stm32-mdma.yaml
+++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-mdma.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: http://devicetree.org/schemas/dma/st,stm32-mdma.yaml#
+$id: http://devicetree.org/schemas/dma/stm32/st,stm32-mdma.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 MDMA Controller bindings
+title: STMicroelectronics STM32 MDMA Controller
description: |
The STM32 MDMA is a general-purpose direct memory access controller capable of
@@ -50,10 +50,10 @@ description: |
if no HW ack signal is used by the MDMA client
maintainers:
- - Amelie Delaunay <amelie.delaunay@st.com>
+ - Amelie Delaunay <amelie.delaunay@foss.st.com>
allOf:
- - $ref: "dma-controller.yaml#"
+ - $ref: /schemas/dma/dma-controller.yaml#
properties:
"#dma-cells":
@@ -104,4 +104,3 @@ examples:
};
...
-
diff --git a/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt b/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt
index b849a1ed389d..1f9831540c97 100644
--- a/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt
+++ b/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt
@@ -4,7 +4,7 @@ Required properties:
- compatible: "ti,dra7-dma-crossbar" for DRA7xx DMA crossbar
"ti,am335x-edma-crossbar" for AM335x and AM437x
- reg: Memory map for accessing module
-- #dma-cells: Should be set to to match with the DMA controller's dma-cells
+- #dma-cells: Should be set to match with the DMA controller's dma-cells
for ti,dra7-dma-crossbar and <3> for ti,am335x-edma-crossbar.
- dma-requests: Number of DMA requests the crossbar can receive
- dma-masters: phandle pointing to the DMA controller
@@ -20,7 +20,7 @@ Optional properties:
memcpy channels in eDMA.
Notes:
-When requesting channel via ti,dra7-dma-crossbar, the DMA clinet must request
+When requesting channel via ti,dra7-dma-crossbar, the DMA client must request
the DMA event number as crossbar ID (input to the DMA crossbar).
For ti,am335x-edma-crossbar: the meaning of parameters of dmas for clients:
diff --git a/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml
index df29d59d13a8..b5bc842c5a0e 100644
--- a/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml
+++ b/Documentation/devicetree/bindings/dma/ti/k3-bcdma.yaml
@@ -6,7 +6,7 @@
$id: http://devicetree.org/schemas/dma/ti/k3-bcdma.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Texas Instruments K3 DMSS BCDMA Device Tree Bindings
+title: Texas Instruments K3 DMSS BCDMA
maintainers:
- Peter Ujfalusi <peter.ujfalusi@gmail.com>
@@ -28,12 +28,21 @@ description: |
PDMAs can be configured via BCDMA split channel's peer registers to match with
the configuration of the legacy peripheral.
-allOf:
- - $ref: /schemas/dma/dma-controller.yaml#
-
properties:
compatible:
- const: ti,am64-dmss-bcdma
+ enum:
+ - ti,am62a-dmss-bcdma-csirx
+ - ti,am64-dmss-bcdma
+ - ti,j721s2-dmss-bcdma-csi
+ - ti,j722s-dmss-bcdma-csi
+
+ reg:
+ minItems: 3
+ maxItems: 9
+
+ reg-names:
+ minItems: 3
+ maxItems: 9
"#dma-cells":
const: 3
@@ -64,19 +73,13 @@ properties:
cell 3: ASEL value for the channel
- reg:
- maxItems: 5
-
- reg-names:
- items:
- - const: gcfg
- - const: bchanrt
- - const: rchanrt
- - const: tchanrt
- - const: ringrt
-
msi-parent: true
+ power-domains:
+ description:
+ Power domain if available
+ maxItems: 1
+
ti,asel:
$ref: /schemas/types.yaml#/definitions/uint32
description: ASEL value for non slave channels
@@ -122,10 +125,102 @@ required:
- msi-parent
- ti,sci
- ti,sci-dev-id
- - ti,sci-rm-range-bchan
- - ti,sci-rm-range-tchan
- ti,sci-rm-range-rchan
+allOf:
+ - $ref: /schemas/dma/dma-controller.yaml#
+ - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,am62a-dmss-bcdma-csirx
+ then:
+ properties:
+ ti,sci-rm-range-bchan: false
+ ti,sci-rm-range-tchan: false
+
+ reg:
+ items:
+ - description: BCDMA Control /Status Registers region
+ - description: RX Channel Realtime Registers region
+ - description: Ring Realtime Registers region
+
+ reg-names:
+ items:
+ - const: gcfg
+ - const: rchanrt
+ - const: ringrt
+
+ required:
+ - power-domains
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,am64-dmss-bcdma
+ then:
+ properties:
+ reg:
+ minItems: 5
+ items:
+ - description: BCDMA Control /Status Registers region
+ - description: Block Copy Channel Realtime Registers region
+ - description: RX Channel Realtime Registers region
+ - description: TX Channel Realtime Registers region
+ - description: Ring Realtime Registers region
+ - description: Ring Configuration Registers region
+ - description: TX Channel Configuration Registers region
+ - description: RX Channel Configuration Registers region
+ - description: Block Copy Channel Configuration Registers region
+
+ reg-names:
+ minItems: 5
+ items:
+ - const: gcfg
+ - const: bchanrt
+ - const: rchanrt
+ - const: tchanrt
+ - const: ringrt
+ - const: ring
+ - const: tchan
+ - const: rchan
+ - const: bchan
+
+ required:
+ - ti,sci-rm-range-bchan
+ - ti,sci-rm-range-tchan
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,j721s2-dmss-bcdma-csi
+ - ti,j722s-dmss-bcdma-csi
+ then:
+ properties:
+ ti,sci-rm-range-bchan: false
+
+ reg:
+ items:
+ - description: BCDMA Control /Status Registers region
+ - description: RX Channel Realtime Registers region
+ - description: TX Channel Realtime Registers region
+ - description: Ring Realtime Registers region
+
+ reg-names:
+ items:
+ - const: gcfg
+ - const: rchanrt
+ - const: tchanrt
+ - const: ringrt
+
+ required:
+ - ti,sci-rm-range-tchan
+
unevaluatedProperties: false
examples:
@@ -150,8 +245,13 @@ examples:
<0x0 0x4c000000 0x0 0x20000>,
<0x0 0x4a820000 0x0 0x20000>,
<0x0 0x4aa40000 0x0 0x20000>,
- <0x0 0x4bc00000 0x0 0x100000>;
- reg-names = "gcfg", "bchanrt", "rchanrt", "tchanrt", "ringrt";
+ <0x0 0x4bc00000 0x0 0x100000>,
+ <0x0 0x48600000 0x0 0x8000>,
+ <0x0 0x484a4000 0x0 0x2000>,
+ <0x0 0x484c2000 0x0 0x2000>,
+ <0x0 0x48420000 0x0 0x2000>;
+ reg-names = "gcfg", "bchanrt", "rchanrt", "tchanrt", "ringrt",
+ "ring", "tchan", "rchan", "bchan";
msi-parent = <&inta_main_dmss>;
#dma-cells = <3>;
diff --git a/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml
index ea19d12a9337..11e064c02994 100644
--- a/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml
+++ b/Documentation/devicetree/bindings/dma/ti/k3-pktdma.yaml
@@ -6,7 +6,7 @@
$id: http://devicetree.org/schemas/dma/ti/k3-pktdma.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Texas Instruments K3 DMSS PKTDMA Device Tree Bindings
+title: Texas Instruments K3 DMSS PKTDMA
maintainers:
- Peter Ujfalusi <peter.ujfalusi@gmail.com>
@@ -25,6 +25,7 @@ description: |
allOf:
- $ref: /schemas/dma/dma-controller.yaml#
+ - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml#
properties:
compatible:
@@ -44,14 +45,28 @@ properties:
The second cell is the ASEL value for the channel
reg:
- maxItems: 4
+ minItems: 4
+ items:
+ - description: Packet DMA Control /Status Registers region
+ - description: RX Channel Realtime Registers region
+ - description: TX Channel Realtime Registers region
+ - description: Ring Realtime Registers region
+ - description: Ring Configuration Registers region
+ - description: TX Configuration Registers region
+ - description: RX Configuration Registers region
+ - description: RX Flow Configuration Registers region
reg-names:
+ minItems: 4
items:
- const: gcfg
- const: rchanrt
- const: tchanrt
- const: ringrt
+ - const: ring
+ - const: tchan
+ - const: rchan
+ - const: rflow
msi-parent: true
@@ -135,8 +150,14 @@ examples:
reg = <0x0 0x485c0000 0x0 0x100>,
<0x0 0x4a800000 0x0 0x20000>,
<0x0 0x4aa00000 0x0 0x40000>,
- <0x0 0x4b800000 0x0 0x400000>;
- reg-names = "gcfg", "rchanrt", "tchanrt", "ringrt";
+ <0x0 0x4b800000 0x0 0x400000>,
+ <0x0 0x485e0000 0x0 0x20000>,
+ <0x0 0x484a0000 0x0 0x4000>,
+ <0x0 0x484c0000 0x0 0x2000>,
+ <0x0 0x48430000 0x0 0x4000>;
+ reg-names = "gcfg", "rchanrt", "tchanrt", "ringrt",
+ "ring", "tchan", "rchan", "rflow";
+
msi-parent = <&inta_main_dmss>;
#dma-cells = <2>;
diff --git a/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml b/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml
index 6a09bbf83d46..b18cf2bfdb5b 100644
--- a/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml
+++ b/Documentation/devicetree/bindings/dma/ti/k3-udma.yaml
@@ -6,7 +6,7 @@
$id: http://devicetree.org/schemas/dma/ti/k3-udma.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Texas Instruments K3 NAVSS Unified DMA Device Tree Bindings
+title: Texas Instruments K3 NAVSS Unified DMA
maintainers:
- Peter Ujfalusi <peter.ujfalusi@gmail.com>
@@ -43,7 +43,8 @@ description: |
configuration of the legacy peripheral.
allOf:
- - $ref: "../dma-controller.yaml#"
+ - $ref: ../dma-controller.yaml#
+ - $ref: /schemas/arm/keystone/ti,k3-sci-common.yaml#
properties:
"#dma-cells":
@@ -68,24 +69,27 @@ properties:
- ti,j721e-navss-mcu-udmap
reg:
- maxItems: 3
+ minItems: 3
+ items:
+ - description: UDMA-P Control /Status Registers region
+ - description: RX Channel Realtime Registers region
+ - description: TX Channel Realtime Registers region
+ - description: TX Configuration Registers region
+ - description: RX Configuration Registers region
+ - description: RX Flow Configuration Registers region
reg-names:
+ minItems: 3
items:
- const: gcfg
- const: rchanrt
- const: tchanrt
+ - const: tchan
+ - const: rchan
+ - const: rflow
msi-parent: true
- ti,sci:
- description: phandle to TI-SCI compatible System controller node
- $ref: /schemas/types.yaml#/definitions/phandle
-
- ti,sci-dev-id:
- description: TI-SCI device id of UDMAP
- $ref: /schemas/types.yaml#/definitions/uint32
-
ti,ringacc:
description: phandle to the ring accelerator node
$ref: /schemas/types.yaml#/definitions/phandle
@@ -165,8 +169,11 @@ examples:
compatible = "ti,am654-navss-main-udmap";
reg = <0x0 0x31150000 0x0 0x100>,
<0x0 0x34000000 0x0 0x100000>,
- <0x0 0x35000000 0x0 0x100000>;
- reg-names = "gcfg", "rchanrt", "tchanrt";
+ <0x0 0x35000000 0x0 0x100000>,
+ <0x0 0x30b00000 0x0 0x20000>,
+ <0x0 0x30c00000 0x0 0x8000>,
+ <0x0 0x30d00000 0x0 0x4000>;
+ reg-names = "gcfg", "rchanrt", "tchanrt", "tchan", "rchan", "rflow";
#dma-cells = <1>;
ti,ringacc = <&ringacc>;
diff --git a/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt b/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt
index 325aca52cd43..b567107270cb 100644
--- a/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt
+++ b/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt
@@ -49,6 +49,12 @@ Optional properties for AXI DMA and MCDMA:
register as configured in h/w. Takes values {8...26}. If the property
is missing or invalid then the default value 23 is used. This is the
maximum value that is supported by all IP versions.
+
+Optional properties for AXI DMA:
+- xlnx,axistream-connected: Tells whether DMA is connected to AXI stream IP.
+- xlnx,irq-delay: Tells the interrupt delay timeout value. Valid range is from
+ 0-255. Setting this value to zero disables the delay timer interrupt.
+ 1 timeout interval = 125 * clock period of SG clock.
Optional properties for VDMA:
- xlnx,flush-fsync: Tells which channel to Flush on Frame sync.
It takes following values:
@@ -103,22 +109,3 @@ axi_vdma_0: axivdma@40030000 {
xlnx,datawidth = <0x40>;
} ;
} ;
-
-
-* DMA client
-
-Required properties:
-- dmas: a list of <[Video DMA device phandle] [Channel ID]> pairs,
- where Channel ID is '0' for write/tx and '1' for read/rx
- channel.
-- dma-names: a list of DMA channel names, one per "dmas" entry
-
-Example:
-++++++++
-
-vdmatest_0: vdmatest@0 {
- compatible ="xlnx,axi-vdma-test-1.00.a";
- dmas = <&axi_vdma_0 0
- &axi_vdma_0 1>;
- dma-names = "vdma0", "vdma1";
-} ;
diff --git a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml
new file mode 100644
index 000000000000..2da86037ad79
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/xilinx/xlnx,zynqmp-dma-1.0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx ZynqMP DMA Engine
+
+description: |
+ The Xilinx ZynqMP DMA engine supports memory to memory transfers,
+ memory to device and device to memory transfers. It also has flow
+ control and rate control support for slave/peripheral dma access.
+
+maintainers:
+ - Michael Tretter <m.tretter@pengutronix.de>
+ - Harini Katakam <harini.katakam@amd.com>
+ - Radhey Shyam Pandey <radhey.shyam.pandey@amd.com>
+
+allOf:
+ - $ref: ../dma-controller.yaml#
+
+properties:
+ "#dma-cells":
+ const: 1
+
+ compatible:
+ enum:
+ - amd,versal2-dma-1.0
+ - xlnx,zynqmp-dma-1.0
+
+ reg:
+ description: memory map for gdma/adma module access
+ maxItems: 1
+
+ interrupts:
+ description: DMA channel interrupt
+ maxItems: 1
+
+ clocks:
+ description: input clocks
+ minItems: 2
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: clk_main
+ - const: clk_apb
+
+ xlnx,bus-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 64
+ - 128
+ description: AXI bus width in bits
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ dma-coherent: true
+
+required:
+ - "#dma-cells"
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - xlnx,bus-width
+
+additionalProperties: false
+
+examples:
+ - |
+
+ fpd_dma_chan1: dma-controller@fd500000 {
+ compatible = "xlnx,zynqmp-dma-1.0";
+ reg = <0xfd500000 0x1000>;
+ interrupt-parent = <&gic>;
+ interrupts = <0 117 0x4>;
+ #dma-cells = <1>;
+ clock-names = "clk_main", "clk_apb";
+ clocks = <&zynqmp_clk 19>, <&zynqmp_clk 31>;
+ xlnx,bus-width = <128>;
+ dma-coherent;
+ };
diff --git a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml
index 2a595b18ff6c..2128f4645c98 100644
--- a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml
+++ b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/dma/xilinx/xlnx,zynqmp-dpdma.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Xilinx ZynqMP DisplayPort DMA Controller Device Tree Bindings
+title: Xilinx ZynqMP DisplayPort DMA Controller
description: |
These bindings describe the DMA engine included in the Xilinx ZynqMP
@@ -16,7 +16,7 @@ maintainers:
- Laurent Pinchart <laurent.pinchart@ideasonboard.com>
allOf:
- - $ref: "../dma-controller.yaml#"
+ - $ref: ../dma-controller.yaml#
properties:
"#dma-cells":
@@ -41,6 +41,9 @@ properties:
clock-names:
const: axi_clk
+ power-domains:
+ maxItems: 1
+
required:
- "#dma-cells"
- compatible
@@ -48,12 +51,14 @@ required:
- interrupts
- clocks
- clock-names
+ - power-domains
additionalProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/xlnx-zynqmp-power.h>
dma: dma-controller@fd4c0000 {
compatible = "xlnx,zynqmp-dpdma";
@@ -63,6 +68,7 @@ examples:
clocks = <&dpdma_clk>;
clock-names = "axi_clk";
#dma-cells = <1>;
+ power-domains = <&zynqmp_firmware PD_DP>;
};
...
diff --git a/Documentation/devicetree/bindings/dma/xilinx/zynqmp_dma.txt b/Documentation/devicetree/bindings/dma/xilinx/zynqmp_dma.txt
deleted file mode 100644
index 07a5a7aa9ea0..000000000000
--- a/Documentation/devicetree/bindings/dma/xilinx/zynqmp_dma.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Xilinx ZynqMP DMA engine, it does support memory to memory transfers,
-memory to device and device to memory transfers. It also has flow
-control and rate control support for slave/peripheral dma access.
-
-Required properties:
-- compatible : Should be "xlnx,zynqmp-dma-1.0"
-- reg : Memory map for gdma/adma module access.
-- interrupts : Should contain DMA channel interrupt.
-- xlnx,bus-width : Axi buswidth in bits. Should contain 128 or 64
-- clock-names : List of input clocks "clk_main", "clk_apb"
- (see clock bindings for details)
-
-Optional properties:
-- dma-coherent : Present if dma operations are coherent.
-
-Example:
-++++++++
-fpd_dma_chan1: dma@fd500000 {
- compatible = "xlnx,zynqmp-dma-1.0";
- reg = <0x0 0xFD500000 0x1000>;
- interrupt-parent = <&gic>;
- interrupts = <0 117 4>;
- clock-names = "clk_main", "clk_apb";
- xlnx,bus-width = <128>;
- dma-coherent;
-};
diff --git a/Documentation/devicetree/bindings/dpll/dpll-device.yaml b/Documentation/devicetree/bindings/dpll/dpll-device.yaml
new file mode 100644
index 000000000000..fb8d7a9a3693
--- /dev/null
+++ b/Documentation/devicetree/bindings/dpll/dpll-device.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dpll/dpll-device.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Digital Phase-Locked Loop (DPLL) Device
+
+maintainers:
+ - Ivan Vecera <ivecera@redhat.com>
+
+description:
+ Digital Phase-Locked Loop (DPLL) device is used for precise clock
+ synchronization in networking and telecom hardware. The device can
+ have one or more channels (DPLLs) and one or more physical input and
+ output pins. Each DPLL channel can either produce pulse-per-clock signal
+ or drive ethernet equipment clock. The type of each channel can be
+ indicated by dpll-types property.
+
+properties:
+ $nodename:
+ pattern: "^dpll(@.*)?$"
+
+ "#address-cells":
+ const: 0
+
+ "#size-cells":
+ const: 0
+
+ dpll-types:
+ description: List of DPLL channel types, one per DPLL instance.
+ $ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ items:
+ enum: [pps, eec]
+
+ input-pins:
+ type: object
+ description: DPLL input pins
+ unevaluatedProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^pin@[0-9a-f]+$":
+ $ref: /schemas/dpll/dpll-pin.yaml
+ unevaluatedProperties: false
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+ output-pins:
+ type: object
+ description: DPLL output pins
+ unevaluatedProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^pin@[0-9]+$":
+ $ref: /schemas/dpll/dpll-pin.yaml
+ unevaluatedProperties: false
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/dpll/dpll-pin.yaml b/Documentation/devicetree/bindings/dpll/dpll-pin.yaml
new file mode 100644
index 000000000000..51db93b77306
--- /dev/null
+++ b/Documentation/devicetree/bindings/dpll/dpll-pin.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dpll/dpll-pin.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DPLL Pin
+
+maintainers:
+ - Ivan Vecera <ivecera@redhat.com>
+
+description: |
+ The DPLL pin is either a physical input or output pin that is provided
+ by a DPLL( Digital Phase-Locked Loop) device. The pin is identified by
+ its physical order number that is stored in reg property and can have
+ an additional set of properties like supported (allowed) frequencies,
+ label, type and may support embedded sync.
+
+ Note that the pin in this context has nothing to do with pinctrl.
+
+properties:
+ reg:
+ description: Hardware index of the DPLL pin.
+ maxItems: 1
+
+ connection-type:
+ description: Connection type of the pin
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ext, gnss, int, mux, synce]
+
+ esync-control:
+ description: Indicates whether the pin supports embedded sync functionality.
+ type: boolean
+
+ label:
+ description: String exposed as the pin board label
+ $ref: /schemas/types.yaml#/definitions/string
+
+ supported-frequencies-hz:
+ description: List of supported frequencies for this pin, expressed in Hz.
+
+required:
+ - reg
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/dpll/microchip,zl30731.yaml b/Documentation/devicetree/bindings/dpll/microchip,zl30731.yaml
new file mode 100644
index 000000000000..17747f754b84
--- /dev/null
+++ b/Documentation/devicetree/bindings/dpll/microchip,zl30731.yaml
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dpll/microchip,zl30731.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip Azurite DPLL device
+
+maintainers:
+ - Ivan Vecera <ivecera@redhat.com>
+
+description:
+ Microchip Azurite DPLL (ZL3073x) is a family of DPLL devices that
+ provides up to 5 independent DPLL channels, up to 10 differential or
+ single-ended inputs and 10 differential or 20 single-ended outputs.
+ These devices support both I2C and SPI interfaces.
+
+properties:
+ compatible:
+ enum:
+ - microchip,zl30731
+ - microchip,zl30732
+ - microchip,zl30733
+ - microchip,zl30734
+ - microchip,zl30735
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/dpll/dpll-device.yaml#
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dpll@70 {
+ compatible = "microchip,zl30732";
+ reg = <0x70>;
+ dpll-types = "pps", "eec";
+
+ input-pins {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pin@0 { /* REF0P */
+ reg = <0>;
+ connection-type = "ext";
+ label = "Input 0";
+ supported-frequencies-hz = /bits/ 64 <1 1000>;
+ };
+ };
+
+ output-pins {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pin@3 { /* OUT1N */
+ reg = <3>;
+ connection-type = "gnss";
+ esync-control;
+ label = "Output 1";
+ supported-frequencies-hz = /bits/ 64 <1 10000>;
+ };
+ };
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dpll@70 {
+ compatible = "microchip,zl30731";
+ reg = <0x70>;
+ spi-max-frequency = <12500000>;
+
+ dpll-types = "pps";
+
+ input-pins {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pin@0 { /* REF0P */
+ reg = <0>;
+ connection-type = "ext";
+ label = "Input 0";
+ supported-frequencies-hz = /bits/ 64 <1 1000>;
+ };
+ };
+
+ output-pins {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pin@3 { /* OUT1N */
+ reg = <3>;
+ connection-type = "gnss";
+ esync-control;
+ label = "Output 1";
+ supported-frequencies-hz = /bits/ 64 <1 10000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml
index 7afc9f2be13a..e610b7636a08 100644
--- a/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml
+++ b/Documentation/devicetree/bindings/dsp/fsl,dsp.yaml
@@ -8,6 +8,7 @@ title: NXP i.MX8 DSP core
maintainers:
- Daniel Baluta <daniel.baluta@nxp.com>
+ - Shengjiu Wang <shengjiu.wang@nxp.com>
description: |
Some boards from i.MX8 family contain a DSP core used for
@@ -19,6 +20,11 @@ properties:
- fsl,imx8qxp-dsp
- fsl,imx8qm-dsp
- fsl,imx8mp-dsp
+ - fsl,imx8ulp-dsp
+ - fsl,imx8qxp-hifi4
+ - fsl,imx8qm-hifi4
+ - fsl,imx8mp-hifi4
+ - fsl,imx8ulp-hifi4
reg:
maxItems: 1
@@ -28,36 +34,64 @@ properties:
- description: ipg clock
- description: ocram clock
- description: core clock
+ - description: debug interface clock
+ - description: message unit clock
+ minItems: 3
clock-names:
items:
- const: ipg
- const: ocram
- const: core
+ - const: debug
+ - const: mu
+ minItems: 3
power-domains:
description:
List of phandle and PM domain specifier as documented in
Documentation/devicetree/bindings/power/power_domain.txt
+ minItems: 1
maxItems: 4
mboxes:
description:
List of <&phandle type channel> - 2 channels for TXDB, 2 channels for RXDB
+ or - 1 channel for TX, 1 channel for RX, 1 channel for RXDB
(see mailbox/fsl,mu.txt)
+ minItems: 3
maxItems: 4
mbox-names:
- items:
- - const: txdb0
- - const: txdb1
- - const: rxdb0
- - const: rxdb1
+ minItems: 3
+ maxItems: 4
memory-region:
description:
phandle to a node describing reserved memory (System RAM memory)
used by DSP (see bindings/reserved-memory/reserved-memory.txt)
+ minItems: 1
+ maxItems: 4
+
+ firmware-name:
+ description: |
+ Default name of the firmware to load to the remote processor.
+
+ fsl,dsp-ctrl:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle to syscon block which provide access for processor enablement
+
+ resets:
+ minItems: 1
+
+ reset-names:
+ minItems: 1
+ items:
+ - const: runstall
+ - const: softreset
+
+ access-controllers:
maxItems: 1
required:
@@ -70,6 +104,90 @@ required:
- mbox-names
- memory-region
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8qxp-dsp
+ - fsl,imx8qxp-hifi4
+ then:
+ properties:
+ power-domains:
+ minItems: 2
+ maxItems: 2
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8qm-dsp
+ - fsl,imx8qm-hifi4
+ then:
+ properties:
+ power-domains:
+ minItems: 4
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8mp-dsp
+ - fsl,imx8mp-hifi4
+ - fsl,imx8ulp-dsp
+ - fsl,imx8ulp-hifi4
+ then:
+ properties:
+ power-domains:
+ maxItems: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8qxp-hifi4
+ - fsl,imx8qm-hifi4
+ - fsl,imx8mp-hifi4
+ - fsl,imx8ulp-hifi4
+ then:
+ properties:
+ memory-region:
+ minItems: 4
+ mboxes:
+ maxItems: 3
+ mbox-names:
+ items:
+ - const: tx
+ - const: rx
+ - const: rxdb
+ else:
+ properties:
+ memory-region:
+ maxItems: 1
+ mboxes:
+ minItems: 4
+ mbox-names:
+ items:
+ - const: txdb0
+ - const: txdb1
+ - const: rxdb0
+ - const: rxdb1
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8mp-dsp
+ - fsl,imx8mp-hifi4
+ then:
+ required:
+ - resets
+ - reset-names
+
additionalProperties: false
examples:
@@ -83,11 +201,49 @@ examples:
<&adma_lpcg IMX_ADMA_LPCG_OCRAM_IPG_CLK>,
<&adma_lpcg IMX_ADMA_LPCG_DSP_CORE_CLK>;
clock-names = "ipg", "ocram", "core";
- power-domains = <&pd IMX_SC_R_MU_13A>,
- <&pd IMX_SC_R_MU_13B>,
- <&pd IMX_SC_R_DSP>,
- <&pd IMX_SC_R_DSP_RAM>;
+ power-domains = <&pd IMX_SC_R_MU_13B>,
+ <&pd IMX_SC_R_MU_2A>;
mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1";
mboxes = <&lsio_mu13 2 0>, <&lsio_mu13 2 1>, <&lsio_mu13 3 0>, <&lsio_mu13 3 1>;
memory-region = <&dsp_reserved>;
};
+ - |
+ #include <dt-bindings/clock/imx8mp-clock.h>
+ #include <dt-bindings/reset/imx8mp-reset-audiomix.h>
+ dsp_reserved: dsp@92400000 {
+ reg = <0x92400000 0x1000000>;
+ no-map;
+ };
+ dsp_vdev0vring0: vdev0vring0@942f0000 {
+ reg = <0x942f0000 0x8000>;
+ no-map;
+ };
+ dsp_vdev0vring1: vdev0vring1@942f8000 {
+ reg = <0x942f8000 0x8000>;
+ no-map;
+ };
+ dsp_vdev0buffer: vdev0buffer@94300000 {
+ compatible = "shared-dma-pool";
+ reg = <0x94300000 0x100000>;
+ no-map;
+ };
+
+ dsp: dsp@3b6e8000 {
+ compatible = "fsl,imx8mp-hifi4";
+ reg = <0x3b6e8000 0x88000>;
+ clocks = <&audio_blk_ctrl IMX8MP_CLK_AUDIOMIX_DSP_ROOT>,
+ <&audio_blk_ctrl IMX8MP_CLK_AUDIOMIX_OCRAMA_IPG>,
+ <&audio_blk_ctrl IMX8MP_CLK_AUDIOMIX_DSP_ROOT>,
+ <&audio_blk_ctrl IMX8MP_CLK_AUDIOMIX_DSPDBG_ROOT>;
+ clock-names = "ipg", "ocram", "core", "debug";
+ firmware-name = "imx/dsp/hifi4.bin";
+ power-domains = <&audiomix_pd>;
+ mbox-names = "tx", "rx", "rxdb";
+ mboxes = <&mu2 0 0>,
+ <&mu2 1 0>,
+ <&mu2 3 0>;
+ memory-region = <&dsp_vdev0buffer>, <&dsp_vdev0vring0>,
+ <&dsp_vdev0vring1>, <&dsp_reserved>;
+ resets = <&audio_blk_ctrl IMX8MP_AUDIOMIX_DSP_RUNSTALL>;
+ reset-names = "runstall";
+ };
diff --git a/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml b/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml
new file mode 100644
index 000000000000..88575da1e6d5
--- /dev/null
+++ b/Documentation/devicetree/bindings/dsp/mediatek,mt8186-dsp.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dsp/mediatek,mt8186-dsp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek mt8186 DSP core
+
+maintainers:
+ - Tinghan Shen <tinghan.shen@mediatek.com>
+
+description: |
+ MediaTek mt8186 SoC contains a DSP core used for
+ advanced pre- and post- audio processing.
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt8186-dsp
+ - mediatek,mt8188-dsp
+
+ reg:
+ items:
+ - description: Address and size of the DSP config registers
+ - description: Address and size of the DSP SRAM
+ - description: Address and size of the DSP secure registers
+ - description: Address and size of the DSP bus registers
+
+ reg-names:
+ items:
+ - const: cfg
+ - const: sram
+ - const: sec
+ - const: bus
+
+ clocks:
+ items:
+ - description: mux for audio dsp clock
+ - description: mux for audio dsp local bus
+
+ clock-names:
+ items:
+ - const: audiodsp
+ - const: adsp_bus
+
+ power-domains:
+ maxItems: 1
+
+ mboxes:
+ items:
+ - description: mailbox for receiving audio DSP requests.
+ - description: mailbox for transmitting requests to audio DSP.
+
+ mbox-names:
+ items:
+ - const: rx
+ - const: tx
+
+ memory-region:
+ items:
+ - description: dma buffer between host and DSP.
+ - description: DSP system memory.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - power-domains
+ - mbox-names
+ - mboxes
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8186-clk.h>
+ dsp@10680000 {
+ compatible = "mediatek,mt8186-dsp";
+ reg = <0x10680000 0x2000>,
+ <0x10800000 0x100000>,
+ <0x1068b000 0x100>,
+ <0x1068f000 0x1000>;
+ reg-names = "cfg", "sram", "sec", "bus";
+ clocks = <&topckgen CLK_TOP_AUDIODSP>,
+ <&topckgen CLK_TOP_ADSP_BUS>;
+ clock-names = "audiodsp",
+ "adsp_bus";
+ power-domains = <&spm 6>;
+ mbox-names = "rx", "tx";
+ mboxes = <&adsp_mailbox0>, <&adsp_mailbox1>;
+ };
diff --git a/Documentation/devicetree/bindings/dsp/mediatek,mt8195-dsp.yaml b/Documentation/devicetree/bindings/dsp/mediatek,mt8195-dsp.yaml
new file mode 100644
index 000000000000..abc52978be7a
--- /dev/null
+++ b/Documentation/devicetree/bindings/dsp/mediatek,mt8195-dsp.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dsp/mediatek,mt8195-dsp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek mt8195 DSP core
+
+maintainers:
+ - YC Hung <yc.hung@mediatek.com>
+
+description: |
+ Some boards from mt8195 contain a DSP core used for
+ advanced pre- and post- audio processing.
+
+properties:
+ compatible:
+ const: mediatek,mt8195-dsp
+
+ reg:
+ items:
+ - description: Address and size of the DSP Cfg registers
+ - description: Address and size of the DSP SRAM
+
+ reg-names:
+ items:
+ - const: cfg
+ - const: sram
+
+ clocks:
+ items:
+ - description: mux for audio dsp clock
+ - description: 26M clock
+ - description: mux for audio dsp local bus
+ - description: default audio dsp local bus clock source
+ - description: clock gate for audio dsp clock
+ - description: mux for audio dsp access external bus
+
+ clock-names:
+ items:
+ - const: adsp_sel
+ - const: clk26m_ck
+ - const: audio_local_bus
+ - const: mainpll_d7_d2
+ - const: scp_adsp_audiodsp
+ - const: audio_h
+
+ power-domains:
+ maxItems: 1
+
+ mboxes:
+ items:
+ - description: mailbox for receiving audio DSP requests.
+ - description: mailbox for transmitting requests to audio DSP.
+
+ mbox-names:
+ items:
+ - const: rx
+ - const: tx
+
+ memory-region:
+ items:
+ - description: dma buffer between host and DSP.
+ - description: DSP system memory.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - memory-region
+ - power-domains
+ - mbox-names
+ - mboxes
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ dsp@10803000 {
+ compatible = "mediatek,mt8195-dsp";
+ reg = <0x10803000 0x1000>,
+ <0x10840000 0x40000>;
+ reg-names = "cfg", "sram";
+ clocks = <&topckgen 10>, //CLK_TOP_ADSP
+ <&clk26m>,
+ <&topckgen 107>, //CLK_TOP_AUDIO_LOCAL_BUS
+ <&topckgen 136>, //CLK_TOP_MAINPLL_D7_D2
+ <&scp_adsp 0>, //CLK_SCP_ADSP_AUDIODSP
+ <&topckgen 34>; //CLK_TOP_AUDIO_H
+ clock-names = "adsp_sel",
+ "clk26m_ck",
+ "audio_local_bus",
+ "mainpll_d7_d2",
+ "scp_adsp_audiodsp",
+ "audio_h";
+ memory-region = <&adsp_dma_mem_reserved>,
+ <&adsp_mem_reserved>;
+ power-domains = <&spm 6>; //MT8195_POWER_DOMAIN_ADSP
+ mbox-names = "rx", "tx";
+ mboxes = <&adsp_mailbox0>, <&adsp_mailbox1>;
+ };
diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
new file mode 100644
index 000000000000..4a02ea60cbbe
--- /dev/null
+++ b/Documentation/devicetree/bindings/dts-coding-style.rst
@@ -0,0 +1,213 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================================
+Devicetree Sources (DTS) Coding Style
+=====================================
+
+When writing Devicetree Sources (DTS) please observe below guidelines. They
+should be considered complementary to any rules expressed already in
+the Devicetree Specification and the dtc compiler (including W=1 and W=2
+builds).
+
+Individual architectures and subarchitectures can define additional rules,
+making the coding style stricter.
+
+Naming and Valid Characters
+---------------------------
+
+The Devicetree Specification allows a broad range of characters in node
+and property names, but this coding style narrows the range down to achieve
+better code readability.
+
+1. Node and property names can use only the following characters:
+
+ * Lowercase characters: [a-z]
+ * Digits: [0-9]
+ * Dash: -
+
+2. Labels can use only the following characters:
+
+ * Lowercase characters: [a-z]
+ * Digits: [0-9]
+ * Underscore: _
+
+3. Unless a bus defines differently, unit addresses shall use lowercase
+ hexadecimal digits, without leading zeros (padding).
+
+4. Hex values in properties, e.g. "reg", shall use lowercase hex. The address
+ part can be padded with leading zeros.
+
+Example::
+
+ gpi_dma2: dma-controller@a00000 {
+ compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma";
+ reg = <0x0 0x00a00000 0x0 0x60000>;
+ }
+
+Order of Nodes
+--------------
+
+1. Nodes on any bus, thus using unit addresses for children, shall be
+ ordered by unit address in ascending order.
+ Alternatively for some subarchitectures, nodes of the same type can be
+ grouped together, e.g. all I2C controllers one after another even if this
+ breaks unit address ordering.
+
+2. Nodes without unit addresses shall be ordered alpha-numerically by the node
+ name. For a few node types, they can be ordered by the main property, e.g.
+ pin configuration states ordered by value of "pins" property.
+
+3. When extending nodes in the board DTS via &label, the entries shall be
+ ordered either alpha-numerically or by keeping the order from DTSI, where
+ the choice depends on the subarchitecture.
+
+The above-described ordering rules are easy to enforce during review, reduce
+chances of conflicts for simultaneous additions of new nodes to a file and help
+in navigating through the DTS source.
+
+Example::
+
+ /* SoC DTSI */
+
+ / {
+ cpus {
+ /* ... */
+ };
+
+ psci {
+ /* ... */
+ };
+
+ soc@0 {
+ dma: dma-controller@10000 {
+ /* ... */
+ };
+
+ clk: clock-controller@80000 {
+ /* ... */
+ };
+ };
+ };
+
+ /* Board DTS - alphabetical order */
+
+ &clk {
+ /* ... */
+ };
+
+ &dma {
+ /* ... */
+ };
+
+ /* Board DTS - alternative order, keep as DTSI */
+
+ &dma {
+ /* ... */
+ };
+
+ &clk {
+ /* ... */
+ };
+
+Order of Properties in Device Node
+----------------------------------
+
+The following order of properties in device nodes is preferred:
+
+1. "compatible"
+2. "reg"
+3. "ranges"
+4. Standard/common properties (defined by common bindings, e.g. without
+ vendor-prefixes)
+5. Vendor-specific properties
+6. "status" (if applicable), preceded by a blank line if there is content
+ before the property
+7. Child nodes, where each node is preceded with a blank line
+
+The "status" property is by default "okay", thus it can be omitted.
+
+The above-described ordering follows this approach:
+
+1. Most important properties start the node: compatible then bus addressing to
+ match unit address.
+2. Each node will have common properties in similar place.
+3. Status is the last information to annotate that device node is or is not
+ finished (board resources are needed).
+
+The individual properties inside each group shall use natural sort order by
+the property name.
+
+Example::
+
+ /* SoC DTSI */
+
+ device_node: device-class@6789abc {
+ compatible = "vendor,device";
+ reg = <0x0 0x06789abc 0x0 0xa123>;
+ ranges = <0x0 0x0 0x06789abc 0x1000>;
+ #dma-cells = <1>;
+ clocks = <&clock_controller 0>, <&clock_controller 1>;
+ clock-names = "bus", "host";
+ #address-cells = <1>;
+ #size-cells = <1>;
+ vendor,custom-property = <2>;
+
+ status = "disabled";
+
+ child_node: child-class@100 {
+ reg = <0x100 0x200>;
+ /* ... */
+ };
+ };
+
+ /* Board DTS */
+
+ &device_node {
+ vdd-0v9-supply = <&board_vreg1>;
+ vdd-1v8-supply = <&board_vreg4>;
+ vdd-3v3-supply = <&board_vreg2>;
+ vdd-12v-supply = <&board_vreg3>;
+
+ status = "okay";
+ }
+
+Indentation and wrapping
+------------------------
+
+1. Use indentation and wrap lines according to
+ Documentation/process/coding-style.rst.
+2. Each entry in arrays with multiple cells, e.g. "reg" with two IO addresses,
+ shall be enclosed in <>.
+3. For arrays spanning across lines, it is preferred to split on item boundary
+ and align the continued entries with opening < from the first line.
+ Usually avoid splitting individual items unless they significantly exceed
+ line wrap limit.
+
+Example::
+
+ thermal-sensor@c271000 {
+ compatible = "qcom,sm8550-tsens", "qcom,tsens-v2";
+ reg = <0x0 0x0c271000 0x0 0x1000>,
+ <0x0 0x0c222000 0x0 0x1000>;
+ /* Lines exceeding coding style line wrap limit: */
+ interconnects = <&aggre1_noc MASTER_USB3_0 0 &mc_virt SLAVE_EBI1 0>,
+ <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_USB3_0 0>;
+ };
+
+Organizing DTSI and DTS
+-----------------------
+
+The DTSI and DTS files shall be organized in a way representing the common,
+reusable parts of hardware. Typically, this means organizing DTSI and DTS files
+into several files:
+
+1. DTSI with contents of the entire SoC, without nodes for hardware not present
+ on the SoC.
+2. If applicable: DTSI with common or re-usable parts of the hardware, e.g.
+ entire System-on-Module.
+3. DTS representing the board.
+
+Hardware components that are present on the board shall be placed in the
+board DTS, not in the SoC or SoM DTSI. A partial exception is a common
+external reference SoC input clock, which could be coded as a fixed-clock in
+the SoC DTSI with its frequency provided by each board DTS.
diff --git a/Documentation/devicetree/bindings/dvfs/performance-domain.yaml b/Documentation/devicetree/bindings/dvfs/performance-domain.yaml
index c8b91207f34d..cc930660b794 100644
--- a/Documentation/devicetree/bindings/dvfs/performance-domain.yaml
+++ b/Documentation/devicetree/bindings/dvfs/performance-domain.yaml
@@ -42,8 +42,7 @@ properties:
enum: [ 0, 1 ]
performance-domains:
- $ref: '/schemas/types.yaml#/definitions/phandle-array'
- maxItems: 1
+ $ref: /schemas/types.yaml#/definitions/phandle-array
description:
A phandle and performance domain specifier as defined by bindings of the
performance controller/provider specified by phandle.
@@ -52,10 +51,16 @@ additionalProperties: true
examples:
- |
- performance: performance-controller@12340000 {
- compatible = "qcom,cpufreq-hw";
- reg = <0x12340000 0x1000>;
- #performance-domain-cells = <1>;
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ performance: performance-controller@11bc00 {
+ compatible = "mediatek,cpufreq-hw";
+ reg = <0 0x0011bc10 0 0x120>, <0 0x0011bd30 0 0x120>;
+
+ #performance-domain-cells = <1>;
+ };
};
// The node above defines a performance controller that is a performance
diff --git a/Documentation/devicetree/bindings/edac/altr,socfpga-ecc-manager.yaml b/Documentation/devicetree/bindings/edac/altr,socfpga-ecc-manager.yaml
new file mode 100644
index 000000000000..136e8fccd429
--- /dev/null
+++ b/Documentation/devicetree/bindings/edac/altr,socfpga-ecc-manager.yaml
@@ -0,0 +1,324 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (C) 2025 Altera Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/edac/altr,socfpga-ecc-manager.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera SoCFPGA ECC Manager
+
+maintainers:
+ - Niravkumar L Rabara <niravkumarlaxmidas.rabara@altera.com>
+
+description:
+ This binding describes the device tree nodes required for the Altera SoCFPGA
+ ECC Manager for the Cyclone5, Arria5, Arria10, Stratix10, and Agilex chip
+ families.
+
+properties:
+
+ compatible:
+ oneOf:
+ - items:
+ - const: altr,socfpga-s10-ecc-manager
+ - const: altr,socfpga-a10-ecc-manager
+ - const: altr,socfpga-a10-ecc-manager
+ - const: altr,socfpga-ecc-manager
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ ranges: true
+
+ altr,sysmgr-syscon:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to Stratix10 System Manager Block with the ECC manager registers
+
+ sdramedac:
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ enum:
+ - altr,sdram-edac
+ - altr,sdram-edac-a10
+ - altr,sdram-edac-s10
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ altr,sdr-syscon:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to SDRAM parent
+
+ required:
+ - compatible
+ - interrupts
+ - altr,sdr-syscon
+
+patternProperties:
+ "^ocram-ecc@[a-f0-9]+$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: altr,socfpga-s10-ocram-ecc
+ - const: altr,socfpga-a10-ocram-ecc
+ - const: altr,socfpga-a10-ocram-ecc
+ - const: altr,socfpga-ocram-ecc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ iram:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to OCRAM parent
+
+ altr,ecc-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to OCRAM parent
+
+ required:
+ - compatible
+ - reg
+ - interrupts
+
+ "^usb[0-9]-ecc@[a-f0-9]+$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: altr,socfpga-s10-usb-ecc
+ - const: altr,socfpga-usb-ecc
+ - const: altr,socfpga-usb-ecc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ altr,ecc-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to USB parent
+
+ required:
+ - compatible
+ - reg
+ - interrupts
+ - altr,ecc-parent
+
+ "^emac[0-9]-[t,r]x-ecc@[a-f0-9]+$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: altr,socfpga-s10-eth-mac-ecc
+ - const: altr,socfpga-eth-mac-ecc
+ - const: altr,socfpga-eth-mac-ecc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ altr,ecc-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to ethernet parent
+
+ required:
+ - compatible
+ - reg
+ - interrupts
+ - altr,ecc-parent
+
+ "^sdmmc[a-f]-ecc@[a-f0-9]+$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: altr,socfpga-s10-sdmmc-ecc
+ - const: altr,socfpga-sdmmc-ecc
+ - const: altr,socfpga-sdmmc-ecc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 2
+ maxItems: 4
+
+ altr,ecc-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to SD/MMC parent
+
+ required:
+ - compatible
+ - reg
+ - interrupts
+ - altr,ecc-parent
+
+ "^l2-ecc@[a-f0-9]+$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ enum:
+ - altr,socfpga-a10-l2-ecc
+ - altr,socfpga-l2-ecc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 2
+
+ required:
+ - compatible
+ - reg
+ - interrupts
+
+ "^dma-ecc@[a-f0-9]+$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ const: altr,socfpga-dma-ecc
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 2
+
+ altr,ecc-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to SD/MMC parent
+
+ required:
+ - compatible
+ - reg
+ - interrupts
+ - altr,ecc-parent
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: altr,socfpga-ecc-manager
+then:
+ required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
+
+else:
+ required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+ - ranges
+ - altr,sysmgr-syscon
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ eccmgr {
+ compatible = "altr,socfpga-s10-ecc-manager",
+ "altr,socfpga-a10-ecc-manager";
+ altr,sysmgr-syscon = <&sysmgr>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ ranges;
+
+ sdramedac {
+ compatible = "altr,sdram-edac-s10";
+ altr,sdr-syscon = <&sdr>;
+ interrupts = <16 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ ocram-ecc@ff8cc000 {
+ compatible = "altr,socfpga-s10-ocram-ecc",
+ "altr,socfpga-a10-ocram-ecc";
+ reg = <0xff8cc000 0x100>;
+ altr,ecc-parent = <&ocram>;
+ interrupts = <1 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ usb0-ecc@ff8c4000 {
+ compatible = "altr,socfpga-s10-usb-ecc",
+ "altr,socfpga-usb-ecc";
+ reg = <0xff8c4000 0x100>;
+ altr,ecc-parent = <&usb0>;
+ interrupts = <2 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ emac0-rx-ecc@ff8c0000 {
+ compatible = "altr,socfpga-s10-eth-mac-ecc",
+ "altr,socfpga-eth-mac-ecc";
+ reg = <0xff8c0000 0x100>;
+ altr,ecc-parent = <&gmac0>;
+ interrupts = <4 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ emac0-tx-ecc@ff8c0400 {
+ compatible = "altr,socfpga-s10-eth-mac-ecc",
+ "altr,socfpga-eth-mac-ecc";
+ reg = <0xff8c0400 0x100>;
+ altr,ecc-parent = <&gmac0>;
+ interrupts = <5 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ sdmmca-ecc@ff8c8c00 {
+ compatible = "altr,socfpga-s10-sdmmc-ecc",
+ "altr,socfpga-sdmmc-ecc";
+ reg = <0xff8c8c00 0x100>;
+ altr,ecc-parent = <&mmc>;
+ interrupts = <14 IRQ_TYPE_LEVEL_HIGH>,
+ <15 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/edac/apm,xgene-edac.yaml b/Documentation/devicetree/bindings/edac/apm,xgene-edac.yaml
new file mode 100644
index 000000000000..9637df7af3c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/edac/apm,xgene-edac.yaml
@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/edac/apm,xgene-edac.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: APM X-Gene SoC EDAC
+
+maintainers:
+ - Khuong Dinh <khuong@os.amperecomputing.com>
+
+description: >
+ EDAC node is defined to describe on-chip error detection and correction.
+
+ The following error types are supported:
+
+ memory controller - Memory controller
+ PMD (L1/L2) - Processor module unit (PMD) L1/L2 cache
+ L3 - L3 cache controller
+ SoC - SoC IPs such as Ethernet, SATA, etc
+
+properties:
+ compatible:
+ const: apm,xgene-edac
+
+ reg:
+ items:
+ - description: CPU bus (PCP) resource
+
+ '#address-cells':
+ const: 2
+
+ '#size-cells':
+ const: 2
+
+ ranges: true
+
+ interrupts:
+ description: Interrupt-specifier for MCU, PMD, L3, or SoC error IRQ(s).
+ items:
+ - description: MCU error IRQ
+ - description: PMD error IRQ
+ - description: L3 error IRQ
+ - description: SoC error IRQ
+ minItems: 1
+
+ regmap-csw:
+ description: Regmap of the CPU switch fabric (CSW) resource.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ regmap-mcba:
+ description: Regmap of the MCB-A (memory bridge) resource.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ regmap-mcbb:
+ description: Regmap of the MCB-B (memory bridge) resource.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ regmap-efuse:
+ description: Regmap of the PMD efuse resource.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ regmap-rb:
+ description: Regmap of the register bus resource (optional for compatibility).
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+required:
+ - compatible
+ - regmap-csw
+ - regmap-mcba
+ - regmap-mcbb
+ - regmap-efuse
+ - reg
+ - interrupts
+
+# Child-node bindings
+patternProperties:
+ '^edacmc@':
+ description: Memory controller subnode
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ const: apm,xgene-edac-mc
+
+ reg:
+ maxItems: 1
+
+ memory-controller:
+ description: Instance number of the memory controller.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 3
+
+ required:
+ - compatible
+ - reg
+ - memory-controller
+
+ '^edacpmd@':
+ description: PMD subnode
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ const: apm,xgene-edac-pmd
+
+ reg:
+ maxItems: 1
+
+ pmd-controller:
+ description: Instance number of the PMD controller.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 3
+
+ required:
+ - compatible
+ - reg
+ - pmd-controller
+
+ '^edacl3@':
+ description: L3 subnode
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ enum:
+ - apm,xgene-edac-l3
+ - apm,xgene-edac-l3-v2
+
+ reg:
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+
+ '^edacsoc@':
+ description: SoC subnode
+ type: object
+ additionalProperties: false
+
+ properties:
+ compatible:
+ enum:
+ - apm,xgene-edac-soc
+ - apm,xgene-edac-soc-v1
+
+ reg:
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ edac@78800000 {
+ compatible = "apm,xgene-edac";
+ reg = <0x0 0x78800000 0x0 0x100>;
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges;
+ interrupts = <0x0 0x20 0x4>, <0x0 0x21 0x4>, <0x0 0x27 0x4>;
+
+ regmap-csw = <&csw>;
+ regmap-mcba = <&mcba>;
+ regmap-mcbb = <&mcbb>;
+ regmap-efuse = <&efuse>;
+ regmap-rb = <&rb>;
+
+ edacmc@7e800000 {
+ compatible = "apm,xgene-edac-mc";
+ reg = <0x0 0x7e800000 0x0 0x1000>;
+ memory-controller = <0>;
+ };
+
+ edacpmd@7c000000 {
+ compatible = "apm,xgene-edac-pmd";
+ reg = <0x0 0x7c000000 0x0 0x200000>;
+ pmd-controller = <0>;
+ };
+
+ edacl3@7e600000 {
+ compatible = "apm,xgene-edac-l3";
+ reg = <0x0 0x7e600000 0x0 0x1000>;
+ };
+
+ edacsoc@7e930000 {
+ compatible = "apm,xgene-edac-soc-v1";
+ reg = <0x0 0x7e930000 0x0 0x1000>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt b/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt
deleted file mode 100644
index 1006b0489464..000000000000
--- a/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-* APM X-Gene SoC EDAC node
-
-EDAC node is defined to describe on-chip error detection and correction.
-The follow error types are supported:
-
- memory controller - Memory controller
- PMD (L1/L2) - Processor module unit (PMD) L1/L2 cache
- L3 - L3 cache controller
- SoC - SoC IP's such as Ethernet, SATA, and etc
-
-The following section describes the EDAC DT node binding.
-
-Required properties:
-- compatible : Shall be "apm,xgene-edac".
-- regmap-csw : Regmap of the CPU switch fabric (CSW) resource.
-- regmap-mcba : Regmap of the MCB-A (memory bridge) resource.
-- regmap-mcbb : Regmap of the MCB-B (memory bridge) resource.
-- regmap-efuse : Regmap of the PMD efuse resource.
-- regmap-rb : Regmap of the register bus resource. This property
- is optional only for compatibility. If the RB
- error conditions are not cleared, it will
- continuously generate interrupt.
-- reg : First resource shall be the CPU bus (PCP) resource.
-- interrupts : Interrupt-specifier for MCU, PMD, L3, or SoC error
- IRQ(s).
-
-Required properties for memory controller subnode:
-- compatible : Shall be "apm,xgene-edac-mc".
-- reg : First resource shall be the memory controller unit
- (MCU) resource.
-- memory-controller : Instance number of the memory controller.
-
-Required properties for PMD subnode:
-- compatible : Shall be "apm,xgene-edac-pmd" or
- "apm,xgene-edac-pmd-v2".
-- reg : First resource shall be the PMD resource.
-- pmd-controller : Instance number of the PMD controller.
-
-Required properties for L3 subnode:
-- compatible : Shall be "apm,xgene-edac-l3" or
- "apm,xgene-edac-l3-v2".
-- reg : First resource shall be the L3 EDAC resource.
-
-Required properties for SoC subnode:
-- compatible : Shall be "apm,xgene-edac-soc-v1" for revision 1 or
- "apm,xgene-edac-l3-soc" for general value reporting
- only.
-- reg : First resource shall be the SoC EDAC resource.
-
-Example:
- csw: csw@7e200000 {
- compatible = "apm,xgene-csw", "syscon";
- reg = <0x0 0x7e200000 0x0 0x1000>;
- };
-
- mcba: mcba@7e700000 {
- compatible = "apm,xgene-mcb", "syscon";
- reg = <0x0 0x7e700000 0x0 0x1000>;
- };
-
- mcbb: mcbb@7e720000 {
- compatible = "apm,xgene-mcb", "syscon";
- reg = <0x0 0x7e720000 0x0 0x1000>;
- };
-
- efuse: efuse@1054a000 {
- compatible = "apm,xgene-efuse", "syscon";
- reg = <0x0 0x1054a000 0x0 0x20>;
- };
-
- rb: rb@7e000000 {
- compatible = "apm,xgene-rb", "syscon";
- reg = <0x0 0x7e000000 0x0 0x10>;
- };
-
- edac@78800000 {
- compatible = "apm,xgene-edac";
- #address-cells = <2>;
- #size-cells = <2>;
- ranges;
- regmap-csw = <&csw>;
- regmap-mcba = <&mcba>;
- regmap-mcbb = <&mcbb>;
- regmap-efuse = <&efuse>;
- regmap-rb = <&rb>;
- reg = <0x0 0x78800000 0x0 0x100>;
- interrupts = <0x0 0x20 0x4>,
- <0x0 0x21 0x4>,
- <0x0 0x27 0x4>;
-
- edacmc@7e800000 {
- compatible = "apm,xgene-edac-mc";
- reg = <0x0 0x7e800000 0x0 0x1000>;
- memory-controller = <0>;
- };
-
- edacpmd@7c000000 {
- compatible = "apm,xgene-edac-pmd";
- reg = <0x0 0x7c000000 0x0 0x200000>;
- pmd-controller = <0>;
- };
-
- edacl3@7e600000 {
- compatible = "apm,xgene-edac-l3";
- reg = <0x0 0x7e600000 0x0 0x1000>;
- };
-
- edacsoc@7e930000 {
- compatible = "apm,xgene-edac-soc-v1";
- reg = <0x0 0x7e930000 0x0 0x1000>;
- };
- };
diff --git a/Documentation/devicetree/bindings/edac/aspeed,ast2400-sdram-edac.yaml b/Documentation/devicetree/bindings/edac/aspeed,ast2400-sdram-edac.yaml
new file mode 100644
index 000000000000..09735826d707
--- /dev/null
+++ b/Documentation/devicetree/bindings/edac/aspeed,ast2400-sdram-edac.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/edac/aspeed,ast2400-sdram-edac.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed BMC SoC SDRAM EDAC controller
+
+maintainers:
+ - Stefan Schaeckeler <sschaeck@cisco.com>
+
+description: >
+ The Aspeed BMC SoC supports DDR3 and DDR4 memory with and without ECC (error
+ correction check).
+
+ The memory controller supports SECDED (single bit error correction, double bit
+ error detection) and single bit error auto scrubbing by reserving 8 bits for
+ every 64 bit word (effectively reducing available memory to 8/9).
+
+ Note, the bootloader must configure ECC mode in the memory controller.
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-sdram-edac
+ - aspeed,ast2500-sdram-edac
+ - aspeed,ast2600-sdram-edac
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ sdram@1e6e0000 {
+ compatible = "aspeed,ast2500-sdram-edac";
+ reg = <0x1e6e0000 0x174>;
+ interrupts = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt
deleted file mode 100644
index 8ca9e0a049d8..000000000000
--- a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Aspeed BMC SoC EDAC node
-
-The Aspeed BMC SoC supports DDR3 and DDR4 memory with and without ECC (error
-correction check).
-
-The memory controller supports SECDED (single bit error correction, double bit
-error detection) and single bit error auto scrubbing by reserving 8 bits for
-every 64 bit word (effectively reducing available memory to 8/9).
-
-Note, the bootloader must configure ECC mode in the memory controller.
-
-
-Required properties:
-- compatible: should be one of
- - "aspeed,ast2400-sdram-edac"
- - "aspeed,ast2500-sdram-edac"
- - "aspeed,ast2600-sdram-edac"
-- reg: sdram controller register set should be <0x1e6e0000 0x174>
-- interrupts: should be AVIC interrupt #0
-
-
-Example:
-
- edac: sdram@1e6e0000 {
- compatible = "aspeed,ast2500-sdram-edac";
- reg = <0x1e6e0000 0x174>;
- interrupts = <0>;
- };
diff --git a/Documentation/devicetree/bindings/edac/dmc-520.yaml b/Documentation/devicetree/bindings/edac/dmc-520.yaml
index 3b6842e92d1b..84db3966662a 100644
--- a/Documentation/devicetree/bindings/edac/dmc-520.yaml
+++ b/Documentation/devicetree/bindings/edac/dmc-520.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/edac/dmc-520.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: ARM DMC-520 EDAC bindings
+title: ARM DMC-520 EDAC
maintainers:
- Lei Wang <lewan@microsoft.com>
diff --git a/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt b/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt
deleted file mode 100644
index 8f52206cfd2a..000000000000
--- a/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt
+++ /dev/null
@@ -1,383 +0,0 @@
-Altera SoCFPGA ECC Manager
-This driver uses the EDAC framework to implement the SOCFPGA ECC Manager.
-The ECC Manager counts and corrects single bit errors and counts/handles
-double bit errors which are uncorrectable.
-
-Cyclone5 and Arria5 ECC Manager
-Required Properties:
-- compatible : Should be "altr,socfpga-ecc-manager"
-- #address-cells: must be 1
-- #size-cells: must be 1
-- ranges : standard definition, should translate from local addresses
-
-Subcomponents:
-
-L2 Cache ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-l2-ecc"
-- reg : Address and size for ECC error interrupt clear registers.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt. Note the rising edge type.
-
-On Chip RAM ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-ocram-ecc"
-- reg : Address and size for ECC error interrupt clear registers.
-- iram : phandle to On-Chip RAM definition.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt. Note the rising edge type.
-
-Example:
-
- eccmgr: eccmgr@ffd08140 {
- compatible = "altr,socfpga-ecc-manager";
- #address-cells = <1>;
- #size-cells = <1>;
- ranges;
-
- l2-ecc@ffd08140 {
- compatible = "altr,socfpga-l2-ecc";
- reg = <0xffd08140 0x4>;
- interrupts = <0 36 1>, <0 37 1>;
- };
-
- ocram-ecc@ffd08144 {
- compatible = "altr,socfpga-ocram-ecc";
- reg = <0xffd08144 0x4>;
- iram = <&ocram>;
- interrupts = <0 178 1>, <0 179 1>;
- };
- };
-
-Arria10 SoCFPGA ECC Manager
-The Arria10 SoC ECC Manager handles the IRQs for each peripheral
-in a shared register instead of individual IRQs like the Cyclone5
-and Arria5. Therefore the device tree is different as well.
-
-Required Properties:
-- compatible : Should be "altr,socfpga-a10-ecc-manager"
-- altr,sysgr-syscon : phandle to Arria10 System Manager Block
- containing the ECC manager registers.
-- #address-cells: must be 1
-- #size-cells: must be 1
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt.
-- interrupt-controller : boolean indicator that ECC Manager is an interrupt controller
-- #interrupt-cells : must be set to 2.
-- ranges : standard definition, should translate from local addresses
-
-Subcomponents:
-
-L2 Cache ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-a10-l2-ecc"
-- reg : Address and size for ECC error interrupt clear registers.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-On-Chip RAM ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-a10-ocram-ecc"
-- reg : Address and size for ECC block registers.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-Ethernet FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-eth-mac-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent Ethernet node.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-NAND FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-nand-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent NAND node.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-DMA FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-dma-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent DMA node.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-USB FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-usb-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent USB node.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-QSPI FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-qspi-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent QSPI node.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order.
-
-SDMMC FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-sdmmc-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent SD/MMC node.
-- interrupts : Should be single bit error interrupt, then double bit error
- interrupt, in this order for port A, and then single bit error interrupt,
- then double bit error interrupt in this order for port B.
-
-Example:
-
- eccmgr: eccmgr@ffd06000 {
- compatible = "altr,socfpga-a10-ecc-manager";
- altr,sysmgr-syscon = <&sysmgr>;
- #address-cells = <1>;
- #size-cells = <1>;
- interrupts = <0 2 IRQ_TYPE_LEVEL_HIGH>,
- <0 0 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-controller;
- #interrupt-cells = <2>;
- ranges;
-
- l2-ecc@ffd06010 {
- compatible = "altr,socfpga-a10-l2-ecc";
- reg = <0xffd06010 0x4>;
- interrupts = <0 IRQ_TYPE_LEVEL_HIGH>,
- <32 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- ocram-ecc@ff8c3000 {
- compatible = "altr,socfpga-a10-ocram-ecc";
- reg = <0xff8c3000 0x90>;
- interrupts = <1 IRQ_TYPE_LEVEL_HIGH>,
- <33 IRQ_TYPE_LEVEL_HIGH> ;
- };
-
- emac0-rx-ecc@ff8c0800 {
- compatible = "altr,socfpga-eth-mac-ecc";
- reg = <0xff8c0800 0x400>;
- altr,ecc-parent = <&gmac0>;
- interrupts = <4 IRQ_TYPE_LEVEL_HIGH>,
- <36 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- emac0-tx-ecc@ff8c0c00 {
- compatible = "altr,socfpga-eth-mac-ecc";
- reg = <0xff8c0c00 0x400>;
- altr,ecc-parent = <&gmac0>;
- interrupts = <5 IRQ_TYPE_LEVEL_HIGH>,
- <37 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- nand-buf-ecc@ff8c2000 {
- compatible = "altr,socfpga-nand-ecc";
- reg = <0xff8c2000 0x400>;
- altr,ecc-parent = <&nand>;
- interrupts = <11 IRQ_TYPE_LEVEL_HIGH>,
- <43 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- nand-rd-ecc@ff8c2400 {
- compatible = "altr,socfpga-nand-ecc";
- reg = <0xff8c2400 0x400>;
- altr,ecc-parent = <&nand>;
- interrupts = <13 IRQ_TYPE_LEVEL_HIGH>,
- <45 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- nand-wr-ecc@ff8c2800 {
- compatible = "altr,socfpga-nand-ecc";
- reg = <0xff8c2800 0x400>;
- altr,ecc-parent = <&nand>;
- interrupts = <12 IRQ_TYPE_LEVEL_HIGH>,
- <44 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- dma-ecc@ff8c8000 {
- compatible = "altr,socfpga-dma-ecc";
- reg = <0xff8c8000 0x400>;
- altr,ecc-parent = <&pdma>;
- interrupts = <10 IRQ_TYPE_LEVEL_HIGH>,
- <42 IRQ_TYPE_LEVEL_HIGH>;
-
- usb0-ecc@ff8c8800 {
- compatible = "altr,socfpga-usb-ecc";
- reg = <0xff8c8800 0x400>;
- altr,ecc-parent = <&usb0>;
- interrupts = <2 IRQ_TYPE_LEVEL_HIGH>,
- <34 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- qspi-ecc@ff8c8400 {
- compatible = "altr,socfpga-qspi-ecc";
- reg = <0xff8c8400 0x400>;
- altr,ecc-parent = <&qspi>;
- interrupts = <14 IRQ_TYPE_LEVEL_HIGH>,
- <46 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- sdmmc-ecc@ff8c2c00 {
- compatible = "altr,socfpga-sdmmc-ecc";
- reg = <0xff8c2c00 0x400>;
- altr,ecc-parent = <&mmc>;
- interrupts = <15 IRQ_TYPE_LEVEL_HIGH>,
- <47 IRQ_TYPE_LEVEL_HIGH>,
- <16 IRQ_TYPE_LEVEL_HIGH>,
- <48 IRQ_TYPE_LEVEL_HIGH>;
- };
- };
-
-Stratix10 SoCFPGA ECC Manager (ARM64)
-The Stratix10 SoC ECC Manager handles the IRQs for each peripheral
-in a shared register similar to the Arria10. However, Stratix10 ECC
-requires access to registers that can only be read from Secure Monitor
-with SMC calls. Therefore the device tree is slightly different. Note
-that only 1 interrupt is sent in Stratix10 because the double bit errors
-are treated as SErrors in ARM64 instead of IRQs in ARM32.
-
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-ecc-manager"
-- altr,sysgr-syscon : phandle to Stratix10 System Manager Block
- containing the ECC manager registers.
-- interrupts : Should be single bit error interrupt.
-- interrupt-controller : boolean indicator that ECC Manager is an interrupt controller
-- #interrupt-cells : must be set to 2.
-- #address-cells: must be 1
-- #size-cells: must be 1
-- ranges : standard definition, should translate from local addresses
-
-Subcomponents:
-
-SDRAM ECC
-Required Properties:
-- compatible : Should be "altr,sdram-edac-s10"
-- interrupts : Should be single bit error interrupt.
-
-On-Chip RAM ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-ocram-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent OCRAM node.
-- interrupts : Should be single bit error interrupt.
-
-Ethernet FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-eth-mac-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent Ethernet node.
-- interrupts : Should be single bit error interrupt.
-
-NAND FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-nand-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent NAND node.
-- interrupts : Should be single bit error interrupt.
-
-DMA FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-dma-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent DMA node.
-- interrupts : Should be single bit error interrupt.
-
-USB FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-usb-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent USB node.
-- interrupts : Should be single bit error interrupt.
-
-SDMMC FIFO ECC
-Required Properties:
-- compatible : Should be "altr,socfpga-s10-sdmmc-ecc"
-- reg : Address and size for ECC block registers.
-- altr,ecc-parent : phandle to parent SD/MMC node.
-- interrupts : Should be single bit error interrupt for port A
- and then single bit error interrupt for port B.
-
-Example:
-
- eccmgr {
- compatible = "altr,socfpga-s10-ecc-manager";
- altr,sysmgr-syscon = <&sysmgr>;
- #address-cells = <1>;
- #size-cells = <1>;
- interrupts = <0 15 4>;
- interrupt-controller;
- #interrupt-cells = <2>;
- ranges;
-
- sdramedac {
- compatible = "altr,sdram-edac-s10";
- interrupts = <16 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- ocram-ecc@ff8cc000 {
- compatible = "altr,socfpga-s10-ocram-ecc";
- reg = <ff8cc000 0x100>;
- altr,ecc-parent = <&ocram>;
- interrupts = <1 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- emac0-rx-ecc@ff8c0000 {
- compatible = "altr,socfpga-s10-eth-mac-ecc";
- reg = <0xff8c0000 0x100>;
- altr,ecc-parent = <&gmac0>;
- interrupts = <4 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- emac0-tx-ecc@ff8c0400 {
- compatible = "altr,socfpga-s10-eth-mac-ecc";
- reg = <0xff8c0400 0x100>;
- altr,ecc-parent = <&gmac0>;
- interrupts = <5 IRQ_TYPE_LEVEL_HIGH>'
- };
-
- nand-buf-ecc@ff8c8000 {
- compatible = "altr,socfpga-s10-nand-ecc";
- reg = <0xff8c8000 0x100>;
- altr,ecc-parent = <&nand>;
- interrupts = <11 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- nand-rd-ecc@ff8c8400 {
- compatible = "altr,socfpga-s10-nand-ecc";
- reg = <0xff8c8400 0x100>;
- altr,ecc-parent = <&nand>;
- interrupts = <13 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- nand-wr-ecc@ff8c8800 {
- compatible = "altr,socfpga-s10-nand-ecc";
- reg = <0xff8c8800 0x100>;
- altr,ecc-parent = <&nand>;
- interrupts = <12 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- dma-ecc@ff8c9000 {
- compatible = "altr,socfpga-s10-dma-ecc";
- reg = <0xff8c9000 0x100>;
- altr,ecc-parent = <&pdma>;
- interrupts = <10 IRQ_TYPE_LEVEL_HIGH>;
-
- usb0-ecc@ff8c4000 {
- compatible = "altr,socfpga-s10-usb-ecc";
- reg = <0xff8c4000 0x100>;
- altr,ecc-parent = <&usb0>;
- interrupts = <2 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- sdmmc-ecc@ff8c8c00 {
- compatible = "altr,socfpga-s10-sdmmc-ecc";
- reg = <0xff8c8c00 0x100>;
- altr,ecc-parent = <&mmc>;
- interrupts = <14 IRQ_TYPE_LEVEL_HIGH>,
- <15 IRQ_TYPE_LEVEL_HIGH>;
- };
- };
diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt
deleted file mode 100644
index c94acbb8cb0c..000000000000
--- a/Documentation/devicetree/bindings/eeprom/at24.txt
+++ /dev/null
@@ -1 +0,0 @@
-This file has been moved to at24.yaml.
diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml
index 914a423ec449..c21282634780 100644
--- a/Documentation/devicetree/bindings/eeprom/at24.yaml
+++ b/Documentation/devicetree/bindings/eeprom/at24.yaml
@@ -2,19 +2,25 @@
# Copyright 2019 BayLibre SAS
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/eeprom/at24.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/eeprom/at24.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: I2C EEPROMs compatible with Atmel's AT24
maintainers:
- Bartosz Golaszewski <bgolaszewski@baylibre.com>
+allOf:
+ - $ref: /schemas/nvmem/nvmem.yaml
+ - $ref: /schemas/nvmem/nvmem-deprecated-cells.yaml
+
select:
properties:
compatible:
contains:
- pattern: "^atmel,(24(c|cs|mac)[0-9]+|spd)$"
+ anyOf:
+ - pattern: "^atmel,(24(c|cs|mac)[0-9]+|spd)$"
+ - enum: ["microchip,24aa025e48", "microchip,24aa025e64"]
required:
- compatible
@@ -87,6 +93,10 @@ properties:
- items:
pattern: cs1024$
- items:
+ pattern: c1025$
+ - items:
+ pattern: cs1025$
+ - items:
pattern: c2048$
- items:
pattern: cs2048$
@@ -95,26 +105,55 @@ properties:
# These are special cases that don't conform to the above pattern.
# Each requires a standard at24 model as fallback.
- items:
- - const: nxp,se97b
- - const: atmel,24c02
+ - enum:
+ - rohm,br24g01
+ - rohm,br24t01
+ - const: atmel,24c01
- items:
- - const: renesas,r1ex24002
+ - enum:
+ - nxp,se97b
+ - renesas,r1ex24002
- const: atmel,24c02
- items:
- - const: renesas,r1ex24016
+ - enum:
+ - giantec,gt24c04a
+ - onnn,cat24c04
+ - onnn,cat24c05
+ - rohm,br24g04
+ - const: atmel,24c04
+ - items:
+ - enum:
+ - belling,bl24c16a
+ - renesas,r1ex24016
- const: atmel,24c16
- items:
- const: giantec,gt24c32a
- const: atmel,24c32
- items:
- - const: renesas,r1ex24128
+ - enum:
+ - belling,bl24s64
+ - onnn,n24s64b
+ - puya,p24c64f
+ - const: atmel,24c64
+ - items:
+ - enum:
+ - giantec,gt24p128e
+ - giantec,gt24p128f
+ - renesas,r1ex24128
+ - samsung,s524ad0xd1
- const: atmel,24c128
- items:
- - const: rohm,br24g01
- - const: atmel,24c01
+ - enum:
+ - giantec,gt24c256c
+ - puya,p24c256c
+ - const: atmel,24c256
- items:
- - const: rohm,br24t01
- - const: atmel,24c01
+ - const: microchip,24aa025e48
+ - items:
+ - const: microchip,24aa025e64
+ - items:
+ - const: st,24256e-wl
+ - pattern: '^atmel,24c(32|64)d-wl$' # Actual vendor is st
label:
description: Descriptive name of the EEPROM.
@@ -174,7 +213,7 @@ required:
- compatible
- reg
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/eeprom/at25.yaml b/Documentation/devicetree/bindings/eeprom/at25.yaml
index fbf99e346966..e1599ce10916 100644
--- a/Documentation/devicetree/bindings/eeprom/at25.yaml
+++ b/Documentation/devicetree/bindings/eeprom/at25.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/eeprom/at25.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/eeprom/at25.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: SPI EEPROMs or FRAMs compatible with Atmel's AT25
@@ -25,14 +25,17 @@ properties:
oneOf:
- items:
- enum:
+ - anvo,anv32c81w
- anvo,anv32e61w
- atmel,at25256B
- fujitsu,mb85rs1mt
+ - fujitsu,mb85rs256
- fujitsu,mb85rs64
- microchip,at25160bn
- microchip,25lc040
- st,m95m02
- st,m95256
+ - st,m95640
- cypress,fm25
- const: atmel,at25
@@ -44,8 +47,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
pagesize:
$ref: /schemas/types.yaml#/definitions/uint32
enum: [1, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072]
@@ -56,6 +57,7 @@ properties:
$ref: /schemas/types.yaml#/definitions/uint32
description:
Total eeprom size in bytes.
+ Also used for FRAMs without device ID where the size cannot be detected.
address-width:
$ref: /schemas/types.yaml#/definitions/uint32
@@ -105,6 +107,8 @@ required:
- spi-max-frequency
allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - $ref: /schemas/nvmem/nvmem.yaml
- if:
properties:
compatible:
@@ -117,12 +121,12 @@ allOf:
- size
- address-width
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -144,4 +148,11 @@ examples:
reg = <1>;
spi-max-frequency = <40000000>;
};
+
+ fram@2 {
+ compatible = "cypress,fm25", "atmel,at25";
+ reg = <2>;
+ spi-max-frequency = <20000000>;
+ size = <2048>;
+ };
};
diff --git a/Documentation/devicetree/bindings/eeprom/microchip,93lc46b.yaml b/Documentation/devicetree/bindings/eeprom/microchip,93lc46b.yaml
new file mode 100644
index 000000000000..144e86ce5c0a
--- /dev/null
+++ b/Documentation/devicetree/bindings/eeprom/microchip,93lc46b.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/eeprom/microchip,93lc46b.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip 93xx46 SPI compatible EEPROM family
+
+maintainers:
+ - Cory Tusar <cory.tusar@pid1solutions.com>
+
+properties:
+ compatible:
+ enum:
+ - atmel,at93c46
+ - atmel,at93c46d
+ - atmel,at93c56
+ - atmel,at93c66
+ - eeprom-93xx46
+ - microchip,93lc46b
+
+ data-size:
+ description: number of data bits per word
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [8, 16]
+
+ reg:
+ description: chip select of EEPROM
+ maxItems: 1
+
+ read-only:
+ description:
+ parameter-less property which disables writes to the EEPROM
+ type: boolean
+
+ select-gpios:
+ description:
+ specifies the GPIO that needs to be asserted prior to each access
+ of EEPROM (e.g. for SPI bus multiplexing)
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - data-size
+ - spi-max-frequency
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - $ref: /schemas/nvmem/nvmem.yaml
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@0 {
+ compatible = "eeprom-93xx46";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cs-high;
+ data-size = <8>;
+ select-gpios = <&gpio4 4 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml b/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
new file mode 100644
index 000000000000..0a0820e9d11f
--- /dev/null
+++ b/Documentation/devicetree/bindings/eeprom/st,m24lr.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/eeprom/st,m24lr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics M24LR NFC/RFID EEPROM
+
+maintainers:
+ - Abd-Alrhman Masalkhi <abd.masalkhi@gmail.com>
+
+description:
+ STMicroelectronics M24LR series are dual-interface (RF + I2C)
+ EEPROM chips. These devices support I2C-based access to both
+ memory and a system area that controls authentication and configuration.
+ They expose two I2C addresses, one for the system parameter sector and
+ one for the EEPROM.
+
+allOf:
+ - $ref: /schemas/nvmem/nvmem.yaml#
+
+properties:
+ compatible:
+ enum:
+ - st,m24lr04e-r
+ - st,m24lr16e-r
+ - st,m24lr64e-r
+
+ reg:
+ items:
+ - description: I2C address used for control/system registers
+ - description: I2C address used for EEPROM memory access
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@57 {
+ compatible = "st,m24lr04e-r";
+ reg = <0x57>, /* primary-device */
+ <0x53>; /* secondary-device */
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/embedded-controller/acer,aspire1-ec.yaml b/Documentation/devicetree/bindings/embedded-controller/acer,aspire1-ec.yaml
new file mode 100644
index 000000000000..01ee61768527
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/acer,aspire1-ec.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/acer,aspire1-ec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Acer Aspire 1 Embedded Controller
+
+maintainers:
+ - Nikita Travkin <nikita@trvn.ru>
+
+description:
+ The Acer Aspire 1 laptop uses an embedded controller to control battery
+ and charging as well as to provide a set of misc features such as the
+ laptop lid status and HPD events for the USB Type-C DP alt mode.
+
+properties:
+ compatible:
+ const: acer,aspire1-ec
+
+ reg:
+ const: 0x76
+
+ interrupts:
+ maxItems: 1
+
+ connector:
+ $ref: /schemas/connector/usb-connector.yaml#
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ embedded-controller@76 {
+ compatible = "acer,aspire1-ec";
+ reg = <0x76>;
+
+ interrupts-extended = <&tlmm 30 IRQ_TYPE_LEVEL_LOW>;
+
+ connector {
+ compatible = "usb-c-connector";
+
+ port {
+ ec_dp_in: endpoint {
+ remote-endpoint = <&mdss_dp_out>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/embedded-controller/google,cros-ec.yaml b/Documentation/devicetree/bindings/embedded-controller/google,cros-ec.yaml
new file mode 100644
index 000000000000..3ab5737c9a8f
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/google,cros-ec.yaml
@@ -0,0 +1,326 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/google,cros-ec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ChromeOS Embedded Controller
+
+maintainers:
+ - Benson Leung <bleung@chromium.org>
+ - Guenter Roeck <groeck@chromium.org>
+
+description:
+ Google's ChromeOS EC is a microcontroller which talks to the AP and
+ implements various functions such as keyboard and battery charging.
+ The EC can be connected through various interfaces (I2C, SPI, and others)
+ and the compatible string specifies which interface is being used.
+
+properties:
+ compatible:
+ oneOf:
+ - description:
+ For implementations of the EC connected through I2C.
+ const: google,cros-ec-i2c
+ - description:
+ For implementations of the EC connected through SPI.
+ const: google,cros-ec-spi
+ - description:
+ For implementations of the FPMCU connected through SPI.
+ items:
+ - const: google,cros-ec-fp
+ - const: google,cros-ec-spi
+ - description:
+ For implementations of the EC connected through RPMSG.
+ const: google,cros-ec-rpmsg
+ - description:
+ For implementations of the EC connected through UART.
+ const: google,cros-ec-uart
+
+ controller-data: true
+
+ google,cros-ec-spi-pre-delay:
+ description:
+ This property specifies the delay in usecs between the
+ assertion of the CS and the first clock pulse.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+
+ google,cros-ec-spi-msg-delay:
+ description:
+ This property specifies the delay in usecs between messages.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+
+ google,has-vbc-nvram:
+ description:
+ Some implementations of the EC include a small nvram space used to
+ store verified boot context data. This boolean flag is used to specify
+ whether this nvram is present or not.
+ type: boolean
+
+ mediatek,rpmsg-name:
+ description:
+ Must be defined if the cros-ec is a rpmsg device for a Mediatek
+ ARM Cortex M4 Co-processor. Contains the name of the rpmsg
+ device. Used to match the subnode to the rpmsg device announced by
+ the SCP.
+ $ref: /schemas/types.yaml#/definitions/string
+
+ spi-max-frequency: true
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ boot0-gpios:
+ maxItems: 1
+ description: Assert for bootloader mode.
+
+ vdd-supply: true
+
+ wakeup-source:
+ description: Button can wake-up the system.
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+ typec:
+ $ref: /schemas/chrome/google,cros-ec-typec.yaml#
+
+ ec-pwm:
+ $ref: /schemas/pwm/google,cros-ec-pwm.yaml#
+ deprecated: true
+
+ pwm:
+ $ref: /schemas/pwm/google,cros-ec-pwm.yaml#
+
+ keyboard-controller:
+ $ref: /schemas/input/google,cros-ec-keyb.yaml#
+
+ proximity:
+ $ref: /schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml#
+
+ codecs:
+ type: object
+ additionalProperties: false
+
+ properties:
+ '#address-cells':
+ const: 2
+
+ '#size-cells':
+ const: 1
+
+ patternProperties:
+ "^ec-codec@[a-f0-9]+$":
+ type: object
+ $ref: /schemas/sound/google,cros-ec-codec.yaml#
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+ cbas:
+ type: object
+
+ description:
+ This device is used to signal when a detachable base is attached
+ to a Chrome OS tablet. This device cannot be detected at runtime.
+
+ properties:
+ compatible:
+ const: google,cros-cbas
+
+ required:
+ - compatible
+
+ additionalProperties: false
+
+patternProperties:
+ "^i2c-tunnel[0-9]*$":
+ type: object
+ $ref: /schemas/i2c/google,cros-ec-i2c-tunnel.yaml#
+
+ "^regulator@[0-9]+$":
+ type: object
+ $ref: /schemas/regulator/google,cros-ec-regulator.yaml#
+
+ "^extcon[0-9]*$":
+ type: object
+ $ref: /schemas/extcon/extcon-usbc-cros-ec.yaml#
+
+required:
+ - compatible
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ const: google,cros-ec-spi
+ then:
+ properties:
+ controller-data: false
+ google,cros-ec-spi-pre-delay: false
+ google,cros-ec-spi-msg-delay: false
+ spi-max-frequency: false
+ else:
+ $ref: /schemas/spi/spi-peripheral-props.yaml
+
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ const: google,cros-ec-rpmsg
+ then:
+ properties:
+ mediatek,rpmsg-name: false
+
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - google,cros-ec-rpmsg
+ - google,cros-ec-uart
+ then:
+ required:
+ - reg
+ - interrupts
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: google,cros-ec-fp
+ then:
+ properties:
+ '#address-cells': false
+ '#size-cells': false
+ typec: false
+ ec-pwm: false
+ kbd-led-backlight: false
+ keyboard-controller: false
+ proximity: false
+ codecs: false
+ cbas: false
+
+ patternProperties:
+ "^i2c-tunnel[0-9]*$": false
+ "^regulator@[0-9]+$": false
+ "^extcon[0-9]*$": false
+
+ # Using additionalProperties: false here and
+ # listing true properties doesn't work
+
+ required:
+ - reset-gpios
+ - boot0-gpios
+ - vdd-supply
+ else:
+ properties:
+ reset-gpios: false
+ boot0-gpios: false
+ vdd-supply: false
+
+additionalProperties: false
+
+examples:
+ # Example for I2C
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ cros-ec@1e {
+ compatible = "google,cros-ec-i2c";
+ reg = <0x1e>;
+ interrupts = <6 0>;
+ interrupt-parent = <&gpio0>;
+ };
+ };
+
+ # Example for SPI
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ cros-ec@0 {
+ compatible = "google,cros-ec-spi";
+ reg = <0x0>;
+ google,cros-ec-spi-msg-delay = <30>;
+ google,cros-ec-spi-pre-delay = <10>;
+ interrupts = <99 0>;
+ interrupt-parent = <&gpio7>;
+ spi-max-frequency = <5000000>;
+ #gpio-cells = <2>;
+ gpio-controller;
+
+ proximity {
+ compatible = "google,cros-ec-mkbp-proximity";
+ };
+
+ cbas {
+ compatible = "google,cros-cbas";
+ };
+ };
+ };
+
+ # Example for RPMSG
+ - |
+ scp0 {
+ cros-ec {
+ compatible = "google,cros-ec-rpmsg";
+ };
+ };
+
+ # Example for FPMCU
+ - |
+ spi {
+ #address-cells = <0x1>;
+ #size-cells = <0x0>;
+
+ ec@0 {
+ compatible = "google,cros-ec-fp", "google,cros-ec-spi";
+ reg = <0x0>;
+ interrupt-parent = <&gpio_controller>;
+ interrupts = <4 IRQ_TYPE_LEVEL_LOW>;
+ spi-max-frequency = <3000000>;
+ reset-gpios = <&gpio_controller 5 GPIO_ACTIVE_LOW>;
+ boot0-gpios = <&gpio_controller 10 GPIO_ACTIVE_HIGH>;
+ vdd-supply = <&pp3300_fp_mcu>;
+ };
+ };
+
+ # Example for UART
+ - |
+ serial {
+ cros-ec {
+ compatible = "google,cros-ec-uart";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/embedded-controller/gw,gsc.yaml b/Documentation/devicetree/bindings/embedded-controller/gw,gsc.yaml
new file mode 100644
index 000000000000..82d4b2dadbae
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/gw,gsc.yaml
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/gw,gsc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Gateworks System Controller
+
+description: |
+ The Gateworks System Controller (GSC) is a device present across various
+ Gateworks product families that provides a set of system related features
+ such as the following (refer to the board hardware user manuals to see what
+ features are present)
+ - Watchdog Timer
+ - GPIO
+ - Pushbutton controller
+ - Hardware monitor with ADC's for temperature and voltage rails and
+ fan controller
+
+maintainers:
+ - Tim Harvey <tharvey@gateworks.com>
+
+properties:
+ $nodename:
+ pattern: "gsc@[0-9a-f]{1,2}"
+ compatible:
+ const: gw,gsc
+
+ reg:
+ description: I2C device address
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ adc:
+ type: object
+ additionalProperties: false
+ description: Optional hardware monitoring module
+
+ properties:
+ compatible:
+ const: gw,gsc-adc
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^channel@[0-9a-f]+$":
+ type: object
+ additionalProperties: false
+ description: |
+ Properties for a single ADC which can report cooked values
+ (i.e. temperature sensor based on thermister), raw values
+ (i.e. voltage rail with a pre-scaling resistor divider).
+
+ properties:
+ reg:
+ description: Register of the ADC
+ maxItems: 1
+
+ label:
+ description: Name of the ADC input
+
+ gw,mode:
+ description: |
+ conversion mode:
+ 0 - temperature, in C*10
+ 1 - pre-scaled 24-bit voltage value
+ 2 - scaled voltage based on an optional resistor divider
+ and optional offset
+ 3 - pre-scaled 16-bit voltage value
+ 4 - fan tach input to report RPM's
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3, 4]
+
+ gw,voltage-divider-ohms:
+ description: Values of resistors for divider on raw ADC input
+ maxItems: 2
+ items:
+ minimum: 1000
+ maximum: 1000000
+
+ gw,voltage-offset-microvolt:
+ description: |
+ A positive voltage offset to apply to a raw ADC
+ (i.e. to compensate for a diode drop).
+ minimum: 0
+ maximum: 1000000
+
+ required:
+ - gw,mode
+ - reg
+ - label
+
+ required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+
+patternProperties:
+ "^fan-controller@[0-9a-f]+$":
+ type: object
+ additionalProperties: false
+ description: Optional fan controller
+
+ properties:
+ compatible:
+ const: gw,gsc-fan
+
+ reg:
+ description: The fan controller base address
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gsc@20 {
+ compatible = "gw,gsc";
+ reg = <0x20>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <4 IRQ_TYPE_LEVEL_LOW>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc {
+ compatible = "gw,gsc-adc";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 { /* A0: Board Temperature */
+ reg = <0x00>;
+ label = "temp";
+ gw,mode = <0>;
+ };
+
+ channel@2 { /* A1: Input Voltage (raw ADC) */
+ reg = <0x02>;
+ label = "vdd_vin";
+ gw,mode = <1>;
+ gw,voltage-divider-ohms = <22100 1000>;
+ gw,voltage-offset-microvolt = <800000>;
+ };
+
+ channel@b { /* A2: Battery voltage */
+ reg = <0x0b>;
+ label = "vdd_bat";
+ gw,mode = <1>;
+ };
+ };
+
+ fan-controller@2c {
+ compatible = "gw,gsc-fan";
+ reg = <0x2c>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/embedded-controller/huawei,gaokun3-ec.yaml b/Documentation/devicetree/bindings/embedded-controller/huawei,gaokun3-ec.yaml
new file mode 100644
index 000000000000..cd9e65b6c2ea
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/huawei,gaokun3-ec.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/huawei,gaokun3-ec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Huawei Matebook E Go Embedded Controller
+
+maintainers:
+ - Pengyu Luo <mitltlatltl@gmail.com>
+
+description:
+ Different from other Qualcomm Snapdragon sc8180x and sc8280xp-based
+ machines, the Huawei Matebook E Go tablets use embedded controllers
+ while others use a system called PMIC GLink which handles battery,
+ UCSI, USB Type-C DP Alt Mode. In addition, Huawei's implementation
+ also handles additional features, such as charging thresholds, FN
+ lock, smart charging, tablet lid status, thermal sensors, and more.
+
+properties:
+ compatible:
+ enum:
+ - huawei,gaokun3-ec
+
+ reg:
+ const: 0x38
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+patternProperties:
+ '^connector@[01]$':
+ $ref: /schemas/connector/usb-connector.yaml#
+
+ properties:
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ embedded-controller@38 {
+ compatible = "huawei,gaokun3-ec";
+ reg = <0x38>;
+
+ interrupts-extended = <&tlmm 107 IRQ_TYPE_LEVEL_LOW>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ connector@0 {
+ compatible = "usb-c-connector";
+ reg = <0>;
+ power-role = "dual";
+ data-role = "dual";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ ucsi0_ss_in: endpoint {
+ remote-endpoint = <&usb_0_qmpphy_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ ucsi0_sbu: endpoint {
+ remote-endpoint = <&usb0_sbu_mux>;
+ };
+ };
+ };
+ };
+
+ connector@1 {
+ compatible = "usb-c-connector";
+ reg = <1>;
+ power-role = "dual";
+ data-role = "dual";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ ucsi1_ss_in: endpoint {
+ remote-endpoint = <&usb_1_qmpphy_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ ucsi1_sbu: endpoint {
+ remote-endpoint = <&usb1_sbu_mux>;
+ };
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mfd/kontron,sl28cpld.yaml b/Documentation/devicetree/bindings/embedded-controller/kontron,sl28cpld.yaml
index eb3b43547cb6..a77e67f6cb82 100644
--- a/Documentation/devicetree/bindings/mfd/kontron,sl28cpld.yaml
+++ b/Documentation/devicetree/bindings/embedded-controller/kontron,sl28cpld.yaml
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: http://devicetree.org/schemas/mfd/kontron,sl28cpld.yaml#
+$id: http://devicetree.org/schemas/embedded-controller/kontron,sl28cpld.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Kontron's sl28cpld board management controller
@@ -16,7 +16,12 @@ description: |
properties:
compatible:
- const: kontron,sl28cpld
+ oneOf:
+ - items:
+ - enum:
+ - kontron,sa67mcu
+ - const: kontron,sl28cpld
+ - const: kontron,sl28cpld
reg:
description:
@@ -39,19 +44,19 @@ properties:
patternProperties:
"^gpio(@[0-9a-f]+)?$":
- $ref: ../gpio/kontron,sl28cpld-gpio.yaml
+ $ref: /schemas/gpio/kontron,sl28cpld-gpio.yaml
"^hwmon(@[0-9a-f]+)?$":
- $ref: ../hwmon/kontron,sl28cpld-hwmon.yaml
+ $ref: /schemas/hwmon/kontron,sl28cpld-hwmon.yaml
"^interrupt-controller(@[0-9a-f]+)?$":
- $ref: ../interrupt-controller/kontron,sl28cpld-intc.yaml
+ $ref: /schemas/interrupt-controller/kontron,sl28cpld-intc.yaml
"^pwm(@[0-9a-f]+)?$":
- $ref: ../pwm/kontron,sl28cpld-pwm.yaml
+ $ref: /schemas/pwm/kontron,sl28cpld-pwm.yaml
"^watchdog(@[0-9a-f]+)?$":
- $ref: ../watchdog/kontron,sl28cpld-wdt.yaml
+ $ref: /schemas/watchdog/kontron,sl28cpld-wdt.yaml
required:
- "#address-cells"
diff --git a/Documentation/devicetree/bindings/embedded-controller/lenovo,thinkpad-t14s-ec.yaml b/Documentation/devicetree/bindings/embedded-controller/lenovo,thinkpad-t14s-ec.yaml
new file mode 100644
index 000000000000..c87ccb5b3086
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/lenovo,thinkpad-t14s-ec.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/lenovo,thinkpad-t14s-ec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lenovo Thinkpad T14s Embedded Controller
+
+maintainers:
+ - Sebastian Reichel <sre@kernel.org>
+
+description:
+ The Qualcomm Snapdragon-based Lenovo Thinkpad T14s has an Embedded Controller
+ (EC) which handles things such as keyboard backlight, LEDs or non-standard
+ keys.
+
+properties:
+ compatible:
+ const: lenovo,thinkpad-t14s-ec
+
+ reg:
+ const: 0x28
+
+ interrupts:
+ maxItems: 1
+
+ wakeup-source: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |+
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ embedded-controller@28 {
+ compatible = "lenovo,thinkpad-t14s-ec";
+ reg = <0x28>;
+ interrupts-extended = <&tlmm 66 IRQ_TYPE_LEVEL_LOW>;
+ wakeup-source;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/embedded-controller/lenovo,yoga-c630-ec.yaml b/Documentation/devicetree/bindings/embedded-controller/lenovo,yoga-c630-ec.yaml
new file mode 100644
index 000000000000..a029b38e8dc0
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/lenovo,yoga-c630-ec.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/lenovo,yoga-c630-ec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lenovo Yoga C630 Embedded Controller.
+
+maintainers:
+ - Bjorn Andersson <andersson@kernel.org>
+
+description:
+ The Qualcomm Snapdragon-based Lenovo Yoga C630 has an Embedded Controller
+ (EC) which handles things such as battery and USB Type-C. This binding
+ describes the interface, on an I2C bus, to this EC.
+
+properties:
+ compatible:
+ const: lenovo,yoga-c630-ec
+
+ reg:
+ const: 0x70
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+patternProperties:
+ '^connector@[01]$':
+ $ref: /schemas/connector/usb-connector.yaml#
+
+ properties:
+ reg:
+ maxItems: 1
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |+
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c1 {
+ clock-frequency = <400000>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ embedded-controller@70 {
+ compatible = "lenovo,yoga-c630-ec";
+ reg = <0x70>;
+
+ interrupts-extended = <&tlmm 20 IRQ_TYPE_LEVEL_HIGH>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ connector@0 {
+ compatible = "usb-c-connector";
+ reg = <0>;
+ power-role = "source";
+ data-role = "host";
+ };
+
+ connector@1 {
+ compatible = "usb-c-connector";
+ reg = <1>;
+ power-role = "source";
+ data-role = "host";
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/embedded-controller/microsoft,surface-sam.yaml b/Documentation/devicetree/bindings/embedded-controller/microsoft,surface-sam.yaml
new file mode 100644
index 000000000000..9202cfca0b35
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/microsoft,surface-sam.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/microsoft,surface-sam.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Surface System Aggregator Module (SAM, SSAM)
+
+maintainers:
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description: |
+ Surface devices use a standardized embedded controller to let the
+ operating system interface with various hardware functions. The
+ specific functionalities are modeled as subdevices and matched on
+ five levels: domain, category, target, instance and function.
+
+properties:
+ compatible:
+ const: microsoft,surface-sam
+
+ interrupts:
+ maxItems: 1
+
+ current-speed: true
+
+required:
+ - compatible
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ uart {
+ embedded-controller {
+ compatible = "microsoft,surface-sam";
+
+ interrupts-extended = <&tlmm 91 IRQ_TYPE_EDGE_RISING>;
+
+ pinctrl-0 = <&ssam_state>;
+ pinctrl-names = "default";
+
+ current-speed = <4000000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/embedded-controller/traverse,ten64-controller.yaml b/Documentation/devicetree/bindings/embedded-controller/traverse,ten64-controller.yaml
new file mode 100644
index 000000000000..08d02c4df873
--- /dev/null
+++ b/Documentation/devicetree/bindings/embedded-controller/traverse,ten64-controller.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/embedded-controller/traverse,ten64-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Traverse Ten64 board microcontroller
+
+maintainers:
+ - Mathew McBride <matt@traverse.com.au>
+
+description: |
+ The board microcontroller on the Ten64 board family is responsible for
+ management of power sources on the board, as well as signalling the SoC
+ to power on and reset.
+
+properties:
+ compatible:
+ const: traverse,ten64-controller
+
+ reg:
+ const: 0x7e
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ board-controller@7e {
+ compatible = "traverse,ten64-controller";
+ reg = <0x7e>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml
index ff6ec65145cf..b04f3cc4312c 100644
--- a/Documentation/devicetree/bindings/example-schema.yaml
+++ b/Documentation/devicetree/bindings/example-schema.yaml
@@ -11,7 +11,7 @@ $id: http://devicetree.org/schemas/example-schema.yaml#
# $schema is the meta-schema this schema should be validated with.
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: An example schema annotated with jsonschema details
+title: An Example Device
maintainers:
- Rob Herring <robh@kernel.org>
@@ -52,8 +52,7 @@ properties:
- vendor,soc4-ip
- vendor,soc3-ip
- vendor,soc2-ip
- - enum:
- - vendor,soc1-ip
+ - const: vendor,soc1-ip
# additionalItems being false is implied
# minItems/maxItems equal to 2 is implied
- items:
@@ -85,6 +84,9 @@ properties:
discouraged.
clock-names:
+ # For single-entry lists in clocks, resets etc., the xxx-names often do not
+ # bring any value, especially if they copy the IP block name. In such case
+ # just skip the xxx-names.
items:
- const: bus
@@ -119,7 +121,7 @@ properties:
# valid for this binding.
clock-frequency:
- # The type is set in the core schema. Per device schema only need to set
+ # The type is set in the core schema. Per-device schema only need to set
# constraints on the possible values.
minimum: 100
maximum: 400000
@@ -133,24 +135,24 @@ properties:
# *-supply is always a single phandle, so nothing more to define.
foo-supply: true
- # Vendor specific properties
+ # Vendor-specific properties
#
- # Vendor specific properties have slightly different schema requirements than
+ # Vendor-specific properties have slightly different schema requirements than
# common properties. They must have at least a type definition and
# 'description'.
vendor,int-property:
- description: Vendor specific properties must have a description
+ description: Vendor-specific properties must have a description
$ref: /schemas/types.yaml#/definitions/uint32
enum: [2, 4, 6, 8, 10]
vendor,bool-property:
- description: Vendor specific properties must have a description. Boolean
+ description: Vendor-specific properties must have a description. Boolean
properties are one case where the json-schema 'type' keyword can be used
directly.
type: boolean
vendor,string-array-property:
- description: Vendor specific properties should reference a type in the
+ description: Vendor-specific properties should reference a type in the
core schema.
$ref: /schemas/types.yaml#/definitions/string-array
items:
@@ -158,14 +160,28 @@ properties:
- enum: [baz, boo]
vendor,property-in-standard-units-microvolt:
- description: Vendor specific properties having a standard unit suffix
+ description: Vendor-specific properties having a standard unit suffix
don't need a type.
enum: [ 100, 200, 300 ]
+ vendor,int-array-variable-length-and-constrained-values:
+ description: Array might define what type of elements might be used (e.g.
+ their range).
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 2
+ maxItems: 3
+ items:
+ minimum: 0
+ maximum: 8
+
child-node:
description: Child nodes are just another property from a json-schema
perspective.
type: object # DT nodes are json objects
+ # Child nodes also need additionalProperties or unevaluatedProperties, where
+ # 'false' should be used in most cases (see 'child-node-with-own-schema'
+ # below).
+ additionalProperties: false
properties:
vendor,a-child-node-property:
description: Child node properties have all the same schema
@@ -175,6 +191,17 @@ properties:
required:
- vendor,a-child-node-property
+ child-node-with-own-schema:
+ description: |
+ Child node with their own compatible and device schema which ends in
+ 'additionalProperties: false' or 'unevaluatedProperties: false' can
+ mention only the compatible and use here 'additionalProperties: true'.
+ type: object
+ additionalProperties: true
+ properties:
+ compatible:
+ const: vendor,sub-device
+
# Describe the relationship between different properties
dependencies:
# 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
@@ -196,7 +223,7 @@ required:
#
# For multiple 'if' schema, group them under an 'allOf'.
#
-# If the conditionals become too unweldy, then it may be better to just split
+# If the conditionals become too unwieldy, then it may be better to just split
# the binding into separate schema documents.
allOf:
- if:
@@ -207,6 +234,10 @@ allOf:
then:
required:
- foo-supply
+ else:
+ # If otherwise the property is not allowed:
+ properties:
+ foo-supply: false
# Altering schema depending on presence of properties is usually done by
# dependencies (see above), however some adjustments might require if:
- if:
@@ -235,13 +266,14 @@ examples:
# be overridden or an appropriate parent bus node should be shown (such as on
# i2c buses).
#
- # Any includes used have to be explicitly included.
+ # Any includes used have to be explicitly included. Use 4-space indentation.
- |
node@1000 {
- compatible = "vendor,soc4-ip", "vendor,soc1-ip";
- reg = <0x1000 0x80>,
- <0x3000 0x80>;
- reg-names = "core", "aux";
- interrupts = <10>;
- interrupt-controller;
+ compatible = "vendor,soc4-ip", "vendor,soc1-ip";
+ reg = <0x1000 0x80>,
+ <0x3000 0x80>;
+ reg-names = "core", "aux";
+ interrupts = <10>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
diff --git a/Documentation/devicetree/bindings/extcon/extcon-ptn5150.yaml b/Documentation/devicetree/bindings/extcon/extcon-ptn5150.yaml
index d5cfa32ea52d..072b3c0c5fd0 100644
--- a/Documentation/devicetree/bindings/extcon/extcon-ptn5150.yaml
+++ b/Documentation/devicetree/bindings/extcon/extcon-ptn5150.yaml
@@ -37,6 +37,11 @@ properties:
GPIO pin (output) used to control VBUS. If skipped, no such control
takes place.
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ A port node to link the usb controller for the dual role switch.
+
required:
- compatible
- interrupts
@@ -58,5 +63,11 @@ examples:
interrupt-parent = <&msmgpio>;
interrupts = <78 IRQ_TYPE_LEVEL_HIGH>;
vbus-gpios = <&msmgpio 148 GPIO_ACTIVE_HIGH>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&usb1_drd_sw>;
+ };
+ };
};
};
diff --git a/Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt b/Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt
deleted file mode 100644
index cfcf455ad4de..000000000000
--- a/Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-
-* Richtek RT8973A - Micro USB Switch device
-
-The Richtek RT8973A is Micro USB Switch with OVP and I2C interface. The RT8973A
-is a USB port accessory detector and switch that is optimized to protect low
-voltage system from abnormal high input voltage (up to 28V) and supports high
-speed USB operation. Also, RT8973A support 'auto-configuration' mode.
-If auto-configuration mode is enabled, RT8973A would control internal h/w patch
-for USB D-/D+ switching.
-
-Required properties:
-- compatible: Should be "richtek,rt8973a-muic"
-- reg: Specifies the I2C slave address of the MUIC block. It should be 0x14
-- interrupts: Interrupt specifiers for detection interrupt sources.
-
-Example:
-
- rt8973a@14 {
- compatible = "richtek,rt8973a-muic";
- interrupt-parent = <&gpx1>;
- interrupts = <5 0>;
- reg = <0x14>;
- };
diff --git a/Documentation/devicetree/bindings/extcon/extcon-usb-gpio.txt b/Documentation/devicetree/bindings/extcon/extcon-usb-gpio.txt
deleted file mode 100644
index dfc14f71e81f..000000000000
--- a/Documentation/devicetree/bindings/extcon/extcon-usb-gpio.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-USB GPIO Extcon device
-
-This is a virtual device used to generate USB cable states from the USB ID pin
-connected to a GPIO pin.
-
-Required properties:
-- compatible: Should be "linux,extcon-usb-gpio"
-
-Either one of id-gpio or vbus-gpio must be present. Both can be present as well.
-- id-gpio: gpio for USB ID pin. See gpio binding.
-- vbus-gpio: gpio for USB VBUS pin.
-
-Example: Examples of extcon-usb-gpio node in dra7-evm.dts as listed below:
- extcon_usb1 {
- compatible = "linux,extcon-usb-gpio";
- id-gpio = <&gpio6 1 GPIO_ACTIVE_HIGH>;
- }
-
- &omap_dwc3_1 {
- extcon = <&extcon_usb1>;
- };
diff --git a/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml b/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml
index 20e1ccfc8630..e00c8072bae9 100644
--- a/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml
+++ b/Documentation/devicetree/bindings/extcon/extcon-usbc-cros-ec.yaml
@@ -8,7 +8,6 @@ title: ChromeOS EC USB Type-C cable and accessories detection
maintainers:
- Benson Leung <bleung@chromium.org>
- - Enric Balletbo i Serra <enric.balletbo@collabora.com>
description: |
On ChromeOS systems with USB Type C ports, the ChromeOS Embedded Controller is
@@ -35,12 +34,13 @@ additionalProperties: false
examples:
- |
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
cros-ec@0 {
compatible = "google,cros-ec-spi";
reg = <0>;
+ interrupts = <44 0>;
usbc_extcon0: extcon0 {
compatible = "google,extcon-usbc-cros-ec";
diff --git a/Documentation/devicetree/bindings/extcon/extcon-usbc-tusb320.yaml b/Documentation/devicetree/bindings/extcon/extcon-usbc-tusb320.yaml
index 9875b4d5c356..126107dd57b1 100644
--- a/Documentation/devicetree/bindings/extcon/extcon-usbc-tusb320.yaml
+++ b/Documentation/devicetree/bindings/extcon/extcon-usbc-tusb320.yaml
@@ -11,7 +11,9 @@ maintainers:
properties:
compatible:
- const: ti,tusb320
+ enum:
+ - ti,tusb320
+ - ti,tusb320l
reg:
maxItems: 1
@@ -28,7 +30,7 @@ additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
tusb320@61 {
diff --git a/Documentation/devicetree/bindings/extcon/linux,extcon-usb-gpio.yaml b/Documentation/devicetree/bindings/extcon/linux,extcon-usb-gpio.yaml
new file mode 100644
index 000000000000..8f29d333602b
--- /dev/null
+++ b/Documentation/devicetree/bindings/extcon/linux,extcon-usb-gpio.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/extcon/linux,extcon-usb-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: USB GPIO Extcon device
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description:
+ This is a virtual device used to generate USB cable states from the USB ID pin
+ connected to a GPIO pin.
+
+properties:
+ compatible:
+ const: linux,extcon-usb-gpio
+
+ id-gpios:
+ description: gpio for USB ID pin. See gpio binding.
+ vbus-gpios:
+ description: gpio for USB VBUS pin.
+
+required:
+ - compatible
+
+anyOf:
+ - required:
+ - id-gpios
+ - required:
+ - vbus-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ extcon_usb1 {
+ compatible = "linux,extcon-usb-gpio";
+ id-gpios = <&gpio6 1 GPIO_ACTIVE_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/extcon/maxim,max14526.yaml b/Documentation/devicetree/bindings/extcon/maxim,max14526.yaml
new file mode 100644
index 000000000000..7eb5918df1c2
--- /dev/null
+++ b/Documentation/devicetree/bindings/extcon/maxim,max14526.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/extcon/maxim,max14526.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX14526 MicroUSB Integrated Circuit (MUIC)
+
+maintainers:
+ - Svyatoslav Ryhel <clamor95@gmail.com>
+
+properties:
+ compatible:
+ const: maxim,max14526
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ connector:
+ $ref: /schemas/connector/usb-connector.yaml#
+
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - connector
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ muic@44 {
+ compatible = "maxim,max14526";
+ reg = <0x44>;
+
+ interrupt-parent = <&gpio>;
+ interrupts = <72 IRQ_TYPE_EDGE_FALLING>;
+
+ connector {
+ compatible = "usb-b-connector";
+ label = "micro-USB";
+ type = "micro";
+ };
+
+ port {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ muic_to_charger: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&charger_input>;
+ };
+
+ muic_to_usb: endpoint@1 {
+ reg = <1>;
+ remote-endpoint = <&usb_input>;
+ };
+
+ muic_to_mhl: endpoint@2 {
+ reg = <2>;
+ remote-endpoint = <&mhl_input>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml b/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml
new file mode 100644
index 000000000000..55800fb0221d
--- /dev/null
+++ b/Documentation/devicetree/bindings/extcon/maxim,max77843.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/extcon/maxim,max77843.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX77843 MicroUSB and Companion Power Management IC Extcon
+
+maintainers:
+ - Chanwoo Choi <cw00.choi@samsung.com>
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ This is a part of device tree bindings for Maxim MAX77843 MicroUSB
+ Integrated Circuit (MUIC).
+
+ See also Documentation/devicetree/bindings/mfd/maxim,max77843.yaml for
+ additional information and example.
+
+properties:
+ compatible:
+ const: maxim,max77843-muic
+
+ connector:
+ $ref: /schemas/connector/usb-connector.yaml#
+ unevaluatedProperties: false
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ description:
+ Any connector to the data bus of this controller should be modelled using
+ the OF graph bindings specified
+ properties:
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+
+required:
+ - compatible
+ - connector
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml
index 6a9c96f0352a..6b80518cbf62 100644
--- a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml
+++ b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm Technologies, Inc. PM8941 USB ID Extcon device
maintainers:
- - Guru Das Srinagesh <gurus@codeaurora.org>
+ - Guru Das Srinagesh <quic_gurus@quicinc.com>
description: |
Some Qualcomm PMICs have a "misc" module that can be used to detect when
@@ -27,10 +27,14 @@ properties:
interrupt-names:
minItems: 1
- items:
- - const: usb_id
- - const: usb_vbus
-
+ anyOf:
+ - items:
+ - const: usb_id
+ - const: usb_vbus
+ - items:
+ - const: usb_id
+ - items:
+ - const: usb_vbus
required:
- compatible
- reg
@@ -49,7 +53,7 @@ examples:
interrupt-controller;
#interrupt-cells = <4>;
- usb_id: misc@900 {
+ usb_id: usb-detect@900 {
compatible = "qcom,pm8941-misc";
reg = <0x900>;
interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>;
diff --git a/Documentation/devicetree/bindings/extcon/richtek,rt8973a-muic.yaml b/Documentation/devicetree/bindings/extcon/richtek,rt8973a-muic.yaml
new file mode 100644
index 000000000000..f9e0d816c025
--- /dev/null
+++ b/Documentation/devicetree/bindings/extcon/richtek,rt8973a-muic.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/extcon/richtek,rt8973a-muic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Richtek RT8973A MUIC
+
+maintainers:
+ - Chanwoo Choi <cw00.choi@samsung.com>
+
+description:
+ The Richtek RT8973A is Micro USB Switch with OVP and I2C interface. The RT8973A
+ is a USB port accessory detector and switch that is optimized to protect low
+ voltage system from abnormal high input voltage (up to 28V) and supports high
+ speed USB operation. Also, RT8973A support 'auto-configuration' mode.
+ If auto-configuration mode is enabled, RT8973A would control internal h/w patch
+ for USB D-/D+ switching.
+
+properties:
+ compatible:
+ const: richtek,rt8973a-muic
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ usb-switch@14 {
+ compatible = "richtek,rt8973a-muic";
+ reg = <0x14>;
+ interrupt-parent = <&gpio>;
+ interrupts = <1 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml b/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml
index fd2e55088888..7ef2d9bef72d 100644
--- a/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml
+++ b/Documentation/devicetree/bindings/extcon/siliconmitus,sm5502-muic.yaml
@@ -20,11 +20,16 @@ properties:
enum:
- siliconmitus,sm5502-muic
- siliconmitus,sm5504-muic
+ - siliconmitus,sm5703-muic
reg:
maxItems: 1
- description: I2C slave address of the device. Usually 0x25 for SM5502,
- 0x14 for SM5504.
+ description: I2C slave address of the device. Usually 0x25 for SM5502
+ and SM5703, 0x14 for SM5504.
+
+ connector:
+ $ref: /schemas/connector/usb-connector.yaml#
+ unevaluatedProperties: false
interrupts:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/extcon/wlf,arizona.yaml b/Documentation/devicetree/bindings/extcon/wlf,arizona.yaml
index efdf59abb2e1..351b202d0e10 100644
--- a/Documentation/devicetree/bindings/extcon/wlf,arizona.yaml
+++ b/Documentation/devicetree/bindings/extcon/wlf,arizona.yaml
@@ -23,7 +23,7 @@ properties:
headphone detect mode to HPDETL, ARIZONA_ACCDET_MODE_HPR/2 sets it
to HPDETR. If this node is not included or if the value is unknown,
then headphone detection mode is set to HPDETL.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 1
maximum: 2
@@ -51,7 +51,7 @@ properties:
description:
Additional software microphone detection debounce specified in
milliseconds.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
wlf,micd-pol-gpio:
description:
@@ -63,7 +63,7 @@ properties:
description:
Time allowed for MICBIAS to startup prior to performing microphone
detection, specified as per the ARIZONA_MICD_TIME_XXX defines.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 12
@@ -71,7 +71,7 @@ properties:
description:
Delay between successive microphone detection measurements, specified
as per the ARIZONA_MICD_TIME_XXX defines.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 12
@@ -79,7 +79,7 @@ properties:
description:
Microphone detection hardware debounces specified as the number of
measurements to take.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
enum: [2, 4]
wlf,micd-timeout-ms:
@@ -97,7 +97,7 @@ properties:
CTIA / OMTP headsets), the field can be of variable length but
should always be a multiple of 3 cells long, each three cell group
represents one polarity configuration.
- $ref: "/schemas/types.yaml#/definitions/uint32-matrix"
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
items:
items:
- description:
@@ -119,7 +119,7 @@ properties:
description:
Settings for the general purpose switch, set as one of the
ARIZONA_GPSW_XXX defines.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 3
diff --git a/Documentation/devicetree/bindings/firmware/amlogic,meson-gxbb-sm.yaml b/Documentation/devicetree/bindings/firmware/amlogic,meson-gxbb-sm.yaml
new file mode 100644
index 000000000000..8f50e698760e
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/amlogic,meson-gxbb-sm.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/amlogic,meson-gxbb-sm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic Secure Monitor (SM)
+
+description:
+ In the Amlogic SoCs the Secure Monitor code is used to provide access to the
+ NVMEM, enable JTAG, set USB boot, etc...
+
+maintainers:
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+properties:
+ compatible:
+ oneOf:
+ - const: amlogic,meson-gxbb-sm
+ - items:
+ - const: amlogic,meson-gx-sm
+ - const: amlogic,meson-gxbb-sm
+
+ power-controller:
+ type: object
+ $ref: /schemas/power/amlogic,meson-sec-pwrc.yaml#
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ firmware {
+ secure-monitor {
+ compatible = "amlogic,meson-gxbb-sm";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml
index cebf6ffe70d5..be817fd9cc34 100644
--- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml
+++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml
@@ -5,7 +5,7 @@
$id: http://devicetree.org/schemas/firmware/arm,scmi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: System Control and Management Interface (SCMI) Message Protocol bindings
+title: System Control and Management Interface (SCMI) Message Protocol
maintainers:
- Sudeep Holla <sudeep.holla@arm.com>
@@ -22,9 +22,12 @@ description: |
[0] https://developer.arm.com/documentation/den0056/latest
+anyOf:
+ - $ref: /schemas/firmware/nxp,imx95-scmi.yaml
+
properties:
$nodename:
- const: scmi
+ pattern: '^scmi(-[0-9]+)?$'
compatible:
oneOf:
@@ -34,6 +37,20 @@ properties:
- description: SCMI compliant firmware with ARM SMC/HVC transport
items:
- const: arm,scmi-smc
+ - description: SCMI compliant firmware with ARM SMC/HVC transport
+ with shmem address(4KB-page, offset) as parameters
+ items:
+ - const: arm,scmi-smc-param
+ - description: SCMI compliant firmware with Qualcomm SMC/HVC transport
+ items:
+ - const: qcom,scmi-smc
+ - description: SCMI compliant firmware with SCMI Virtio transport.
+ The virtio transport only supports a single device.
+ items:
+ - const: arm,scmi-virtio
+ - description: SCMI compliant firmware with OP-TEE transport
+ items:
+ - const: linaro,scmi-optee
interrupts:
description:
@@ -49,17 +66,42 @@ properties:
description:
Specifies the mailboxes used to communicate with SCMI compliant
firmware.
- items:
- - const: tx
- - const: rx
+ oneOf:
+ - items:
+ - const: tx
+ - const: rx
+ minItems: 1
+ - items:
+ - const: tx
+ - const: tx_reply
+ - const: rx
+ - const: rx_reply
+ minItems: 2
mboxes:
description:
List of phandle and mailbox channel specifiers. It should contain
- exactly one or two mailboxes, one for transmitting messages("tx")
- and another optional for receiving the notifications("rx") if supported.
+ exactly one, two, three or four mailboxes; the first one or two for
+ transmitting messages ("tx") and another optional ("rx") for receiving
+ notifications and delayed responses, if supported by the platform.
+ The optional ("rx_reply") is for notifications completion interrupt,
+ if supported by the platform.
+ The number of mailboxes needed for transmitting messages depends on the
+ type of channels exposed by the specific underlying mailbox controller;
+ one single channel descriptor is enough if such channel is bidirectional,
+ while two channel descriptors are needed to represent the SCMI ("tx")
+ channel if the underlying mailbox channels are of unidirectional type.
+ The effective combination in numbers of mboxes and shmem descriptors let
+ the SCMI subsystem determine unambiguosly which type of SCMI channels are
+ made available by the underlying mailbox controller and how to use them.
+ 1 mbox / 1 shmem => SCMI TX over 1 mailbox bidirectional channel
+ 2 mbox / 2 shmem => SCMI TX and RX over 2 mailbox bidirectional channels
+ 2 mbox / 1 shmem => SCMI TX over 2 mailbox unidirectional channels
+ 3 mbox / 2 shmem => SCMI TX and RX over 3 mailbox unidirectional channels
+ 4 mbox / 2 shmem => SCMI TX and RX over 4 mailbox unidirectional channels
+ Any other combination of mboxes and shmem is invalid.
minItems: 1
- maxItems: 2
+ maxItems: 4
shmem:
description:
@@ -74,13 +116,50 @@ properties:
'#size-cells':
const: 0
+ atomic-threshold-us:
+ description:
+ An optional time value, expressed in microseconds, representing, on this
+ platform, the threshold above which any SCMI command, advertised to have
+ an higher-than-threshold execution latency, should not be considered for
+ atomic mode of operation, even if requested.
+ default: 0
+
+ arm,max-rx-timeout-ms:
+ description:
+ An optional time value, expressed in milliseconds, representing the
+ transport maximum timeout value for the receive channel. The value should
+ be a non-zero value if set.
+ minimum: 1
+
+ arm,max-msg-size:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ An optional value, expressed in bytes, representing the maximum size
+ allowed for the payload of messages transmitted on this transport.
+
+ arm,max-msg:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ An optional value representing the maximum number of concurrent in-flight
+ messages allowed by this transport; this number represents the maximum
+ number of concurrently outstanding messages that the server can handle on
+ this platform. If set, the value should be non-zero.
+ minimum: 1
+
arm,smc-id:
$ref: /schemas/types.yaml#/definitions/uint32
description:
SMC id required when using smc or hvc transports
+ linaro,optee-channel-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Channel specifier required when using OP-TEE transport.
+
protocol@11:
- type: object
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
properties:
reg:
const: 0x11
@@ -91,8 +170,18 @@ properties:
required:
- '#power-domain-cells'
+ protocol@12:
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0x12
+
protocol@13:
- type: object
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
properties:
reg:
const: 0x13
@@ -100,11 +189,20 @@ properties:
'#clock-cells':
const: 1
- required:
- - '#clock-cells'
+ '#power-domain-cells':
+ const: 1
+
+ oneOf:
+ - required:
+ - '#clock-cells'
+
+ - required:
+ - '#power-domain-cells'
protocol@14:
- type: object
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
properties:
reg:
const: 0x14
@@ -116,7 +214,9 @@ properties:
- '#clock-cells'
protocol@15:
- type: object
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
properties:
reg:
const: 0x15
@@ -128,7 +228,9 @@ properties:
- '#thermal-sensor-cells'
protocol@16:
- type: object
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
properties:
reg:
const: 0x16
@@ -140,20 +242,31 @@ properties:
- '#reset-cells'
protocol@17:
- type: object
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
properties:
reg:
const: 0x17
regulators:
type: object
+ additionalProperties: false
description:
The list of all regulators provided by this SCMI controller.
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
patternProperties:
- '^regulators@[0-9a-f]+$':
+ '^regulator@[0-9a-f]+$':
type: object
- $ref: "../regulator/regulator.yaml#"
+ $ref: /schemas/regulator/regulator.yaml#
+ unevaluatedProperties: false
properties:
reg:
@@ -163,39 +276,93 @@ properties:
required:
- reg
-additionalProperties: false
+ protocol@18:
+ $ref: '#/$defs/protocol-node'
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0x18
+
+ protocol@19:
+ type: object
+ allOf:
+ - $ref: '#/$defs/protocol-node'
+ - anyOf:
+ - $ref: /schemas/pinctrl/pinctrl.yaml
+ - $ref: /schemas/firmware/nxp,imx95-scmi-pinctrl.yaml
+
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0x19
+
+ patternProperties:
+ '-pins$':
+ type: object
+ allOf:
+ - $ref: /schemas/pinctrl/pincfg-node.yaml#
+ - $ref: /schemas/pinctrl/pinmux-node.yaml#
+ unevaluatedProperties: false
+
+ description:
+ A pin multiplexing sub-node describes how to configure a
+ set of pins in some desired function.
+ A single sub-node may define several pin configurations.
+ This sub-node is using the default pinctrl bindings to configure
+ pin multiplexing and using SCMI protocol to apply a specified
+ configuration.
+
+ required:
+ - reg
-patternProperties:
- '^protocol@[0-9a-f]+$':
+unevaluatedProperties: false
+
+$defs:
+ protocol-node:
type: object
description:
Each sub-node represents a protocol supported. If the platform
supports a dedicated communication channel for a particular protocol,
then the corresponding transport properties must be present.
+ The virtio transport does not support a dedicated communication channel.
properties:
reg:
maxItems: 1
mbox-names:
- items:
- - const: tx
- - const: rx
+ oneOf:
+ - items:
+ - const: tx
+ - const: rx
+ minItems: 1
+ - items:
+ - const: tx
+ - const: tx_reply
+ - const: rx
+ minItems: 2
mboxes:
minItems: 1
- maxItems: 2
+ maxItems: 3
shmem:
minItems: 1
maxItems: 2
+ linaro,optee-channel-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Channel specifier required when using OP-TEE transport and
+ protocol has a dedicated communication channel.
+
required:
- reg
required:
- compatible
- - shmem
if:
properties:
@@ -209,16 +376,31 @@ then:
required:
- mboxes
+ - shmem
else:
if:
properties:
compatible:
contains:
- const: arm,scmi-smc
+ enum:
+ - arm,scmi-smc
+ - arm,scmi-smc-param
+ - qcom,scmi-smc
then:
required:
- arm,smc-id
+ - shmem
+
+ else:
+ if:
+ properties:
+ compatible:
+ contains:
+ const: linaro,scmi-optee
+ then:
+ required:
+ - linaro,optee-channel-id
examples:
- |
@@ -234,6 +416,8 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
+ atomic-threshold-us = <10000>;
+
scmi_devpd: protocol@11 {
reg = <0x11>;
#power-domain-cells = <1>;
@@ -241,7 +425,7 @@ examples:
scmi_dvfs: protocol@13 {
reg = <0x13>;
- #clock-cells = <1>;
+ #power-domain-cells = <1>;
mboxes = <&mhuB 1 0>,
<&mhuB 1 1>;
@@ -283,6 +467,29 @@ examples:
};
};
};
+
+ scmi_powercap: protocol@18 {
+ reg = <0x18>;
+ };
+
+ scmi_pinctrl: protocol@19 {
+ reg = <0x19>;
+
+ i2c2-pins {
+ groups = "g_i2c2_a", "g_i2c2_b";
+ function = "f_i2c2";
+ };
+
+ mdio-pins {
+ groups = "g_avb_mdio";
+ drive-strength = <24>;
+ };
+
+ keys_pins: keys-pins {
+ pins = "gpio_5_17", "gpio_5_20", "gpio_5_22", "gpio_2_1";
+ bias-pull-up;
+ };
+ };
};
};
@@ -324,7 +531,7 @@ examples:
firmware {
scmi {
compatible = "arm,scmi-smc";
- shmem = <&cpu_scp_lpri0 &cpu_scp_lpri1>;
+ shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
arm,smc-id = <0xc3000001>;
#address-cells = <1>;
@@ -334,7 +541,48 @@ examples:
reg = <0x11>;
#power-domain-cells = <1>;
};
+ };
+ };
+ - |
+ firmware {
+ scmi {
+ compatible = "linaro,scmi-optee";
+ linaro,optee-channel-id = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ scmi_dvfs1: protocol@13 {
+ reg = <0x13>;
+ linaro,optee-channel-id = <1>;
+ shmem = <&cpu_optee_lpri0>;
+ #power-domain-cells = <1>;
+ };
+
+ scmi_clk0: protocol@14 {
+ reg = <0x14>;
+ #clock-cells = <1>;
+ };
+ };
+ };
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ sram@51000000 {
+ compatible = "mmio-sram";
+ reg = <0x0 0x51000000 0x0 0x10000>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0 0x0 0x51000000 0x10000>;
+
+ cpu_optee_lpri0: optee-sram-section@0 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x80>;
+ };
};
};
diff --git a/Documentation/devicetree/bindings/firmware/arm,scpi.yaml b/Documentation/devicetree/bindings/firmware/arm,scpi.yaml
index d7113b06454b..241317239ffc 100644
--- a/Documentation/devicetree/bindings/firmware/arm,scpi.yaml
+++ b/Documentation/devicetree/bindings/firmware/arm,scpi.yaml
@@ -5,7 +5,7 @@
$id: http://devicetree.org/schemas/firmware/arm,scpi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: System Control and Power Interface (SCPI) Message Protocol bindings
+title: System Control and Power Interface (SCPI) Message Protocol
maintainers:
- Sudeep Holla <sudeep.holla@arm.com>
@@ -43,6 +43,7 @@ properties:
by remote SCP firmware for use by SCPI message protocol should be
specified in any order.
minItems: 1
+ maxItems: 4
shmem:
description:
@@ -51,6 +52,7 @@ properties:
be any memory reserved for the purpose of this communication between the
processors.
minItems: 1
+ maxItems: 4
power-controller:
type: object
@@ -131,9 +133,9 @@ properties:
properties:
compatible:
- oneOf:
- - const: arm,scpi-dvfs-clocks
- - const: arm,scpi-variable-clocks
+ enum:
+ - arm,scpi-dvfs-clocks
+ - arm,scpi-variable-clocks
'#clock-cells':
const: 1
@@ -235,8 +237,8 @@ examples:
firmware {
scpi {
compatible = "amlogic,meson-gxbb-scpi", "arm,scpi-pre-1.0";
- mboxes = <&mailbox 1 &mailbox 2>;
- shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
+ mboxes = <&mailbox 1>, <&mailbox 2>;
+ shmem = <&cpu_scp_lpri>, <&cpu_scp_hpri>;
scpi_sensors1: sensors {
compatible = "amlogic,meson-gxbb-scpi-sensors", "arm,scpi-sensors";
diff --git a/Documentation/devicetree/bindings/firmware/brcm,kona-smc.yaml b/Documentation/devicetree/bindings/firmware/brcm,kona-smc.yaml
new file mode 100644
index 000000000000..684b15ba9ad0
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/brcm,kona-smc.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/brcm,kona-smc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom Kona family Secure Monitor bounce buffer
+
+description:
+ A bounce buffer used for non-secure to secure communications.
+
+maintainers:
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm11351-smc
+ - brcm,bcm21664-smc
+ - brcm,bcm23550-smc
+ - const: brcm,kona-smc
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ smc@3404c000 {
+ compatible = "brcm,bcm11351-smc", "brcm,kona-smc";
+ reg = <0x3404c000 0x400>; /* 1 KiB in SRAM */
+ };
+...
diff --git a/Documentation/devicetree/bindings/firmware/cznic,turris-omnia-mcu.yaml b/Documentation/devicetree/bindings/firmware/cznic,turris-omnia-mcu.yaml
new file mode 100644
index 000000000000..af9249695ef5
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/cznic,turris-omnia-mcu.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/cznic,turris-omnia-mcu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: CZ.NIC's Turris Omnia MCU
+
+maintainers:
+ - Marek Behún <kabel@kernel.org>
+
+description:
+ The MCU on Turris Omnia acts as a system controller providing additional
+ GPIOs, interrupts, watchdog, system power off and wakeup configuration.
+
+properties:
+ compatible:
+ const: cznic,turris-omnia-mcu
+
+ reg:
+ description: MCU I2C slave address
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description: |
+ The first cell specifies the interrupt number (0 to 63), the second cell
+ specifies interrupt type (which can be one of IRQ_TYPE_EDGE_RISING,
+ IRQ_TYPE_EDGE_FALLING or IRQ_TYPE_EDGE_BOTH).
+ The interrupt numbers correspond sequentially to GPIO numbers, taking the
+ GPIO banks into account:
+ IRQ number GPIO bank GPIO pin within bank
+ 0 - 15 0 0 - 15
+ 16 - 47 1 0 - 31
+ 48 - 63 2 0 - 15
+ There are several exceptions:
+ IRQ number meaning
+ 11 LED panel brightness changed by button press
+ 13 TRNG entropy ready
+ 14 ECDSA message signature computation done
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 3
+ description:
+ The first cell is bank number (0, 1 or 2), the second cell is pin number
+ within the bank (0 to 15 for banks 0 and 2, 0 to 31 for bank 1), and the
+ third cell specifies consumer flags.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - gpio-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ system-controller@2a {
+ compatible = "cznic,turris-omnia-mcu";
+ reg = <0x2a>;
+
+ interrupt-parent = <&gpio1>;
+ interrupts = <11 IRQ_TYPE_NONE>;
+
+ gpio-controller;
+ #gpio-cells = <3>;
+
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/firmware/fsl,scu.yaml b/Documentation/devicetree/bindings/firmware/fsl,scu.yaml
new file mode 100644
index 000000000000..f9ba18f06369
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/fsl,scu.yaml
@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/fsl,scu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX System Controller Firmware (SCFW)
+
+maintainers:
+ - Dong Aisheng <aisheng.dong@nxp.com>
+
+description:
+ The System Controller Firmware (SCFW) is a low-level system function
+ which runs on a dedicated Cortex-M core to provide power, clock, and
+ resource management. It exists on some i.MX8 processors. e.g. i.MX8QM
+ (QM, QP), and i.MX8QX (QXP, DX).
+ The AP communicates with the SC using a multi-ported MU module found
+ in the LSIO subsystem. The current definition of this MU module provides
+ 5 remote AP connections to the SC to support up to 5 execution environments
+ (TZ, HV, standard Linux, etc.). The SC side of this MU module interfaces
+ with the LSIO DSC IP bus. The SC firmware will communicate with this MU
+ using the MSI bus.
+
+properties:
+ compatible:
+ const: fsl,imx-scu
+
+ clock-controller:
+ description:
+ Clock controller node that provides the clocks controlled by the SCU
+ $ref: /schemas/clock/fsl,scu-clk.yaml
+
+ gpio:
+ description:
+ Control the GPIO PINs on SCU domain over the firmware APIs
+ $ref: /schemas/gpio/fsl,imx8qxp-sc-gpio.yaml
+
+ ocotp:
+ description:
+ OCOTP controller node provided by the SCU
+ $ref: /schemas/nvmem/fsl,scu-ocotp.yaml
+
+ keys:
+ description:
+ Keys provided by the SCU
+ $ref: /schemas/input/fsl,scu-key.yaml
+
+ reset-controller:
+ type: object
+ properties:
+ compatible:
+ const: fsl,imx-scu-reset
+ '#reset-cells':
+ const: 1
+ required:
+ - compatible
+ - '#reset-cells'
+ additionalProperties: false
+
+ mboxes:
+ description:
+ A list of phandles of TX MU channels followed by a list of phandles of
+ RX MU channels. The list may include at the end one more optional MU
+ channel for general interrupt. The number of expected tx and rx
+ channels is 1 TX and 1 RX channels if MU instance is "fsl,imx8-mu-scu"
+ compatible, 4 TX and 4 RX channels otherwise. All MU channels must be
+ within the same MU instance. Cross instances are not allowed. The MU
+ instance can only be one of LSIO MU0~M4 for imx8qxp and imx8qm. Users
+ need to ensure that one is used that does not conflict with other
+ execution environments such as ATF.
+ oneOf:
+ - items:
+ - description: TX0 MU channel
+ - description: RX0 MU channel
+ - items:
+ - description: TX0 MU channel
+ - description: RX0 MU channel
+ - description: optional MU channel for general interrupt
+ - items:
+ - description: TX0 MU channel
+ - description: TX1 MU channel
+ - description: TX2 MU channel
+ - description: TX3 MU channel
+ - description: RX0 MU channel
+ - description: RX1 MU channel
+ - description: RX2 MU channel
+ - description: RX3 MU channel
+ - items:
+ - description: TX0 MU channel
+ - description: TX1 MU channel
+ - description: TX2 MU channel
+ - description: TX3 MU channel
+ - description: RX0 MU channel
+ - description: RX1 MU channel
+ - description: RX2 MU channel
+ - description: RX3 MU channel
+ - description: optional MU channel for general interrupt
+
+ mbox-names:
+ oneOf:
+ - items:
+ - const: tx0
+ - const: rx0
+ - items:
+ - const: tx0
+ - const: rx0
+ - const: gip3
+ - items:
+ - const: tx0
+ - const: tx1
+ - const: tx2
+ - const: tx3
+ - const: rx0
+ - const: rx1
+ - const: rx2
+ - const: rx3
+ - items:
+ - const: tx0
+ - const: tx1
+ - const: tx2
+ - const: tx3
+ - const: rx0
+ - const: rx1
+ - const: rx2
+ - const: rx3
+ - const: gip3
+
+ pinctrl:
+ description:
+ Pin controller provided by the SCU
+ $ref: /schemas/pinctrl/fsl,scu-pinctrl.yaml
+
+ power-controller:
+ description:
+ Power domains controller node that provides the power domains
+ controlled by the SCU
+ $ref: /schemas/power/fsl,scu-pd.yaml
+
+ rtc:
+ description:
+ RTC controller provided by the SCU
+ $ref: /schemas/rtc/fsl,scu-rtc.yaml
+
+ thermal-sensor:
+ description:
+ Thermal sensor provided by the SCU
+ $ref: /schemas/thermal/fsl,scu-thermal.yaml
+
+ watchdog:
+ description:
+ Watchdog controller provided by the SCU
+ $ref: /schemas/watchdog/fsl,scu-wdt.yaml
+
+required:
+ - compatible
+ - mbox-names
+ - mboxes
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/firmware/imx/rsrc.h>
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/pinctrl/pads-imx8qxp.h>
+
+ firmware {
+ system-controller {
+ compatible = "fsl,imx-scu";
+ mbox-names = "tx0", "tx1", "tx2", "tx3",
+ "rx0", "rx1", "rx2", "rx3",
+ "gip3";
+ mboxes = <&lsio_mu1 0 0 &lsio_mu1 0 1 &lsio_mu1 0 2 &lsio_mu1 0 3
+ &lsio_mu1 1 0 &lsio_mu1 1 1 &lsio_mu1 1 2 &lsio_mu1 1 3
+ &lsio_mu1 3 3>;
+
+ clock-controller {
+ compatible = "fsl,imx8qxp-clk", "fsl,scu-clk";
+ #clock-cells = <2>;
+ };
+
+ pinctrl {
+ compatible = "fsl,imx8qxp-iomuxc";
+
+ pinctrl_lpuart0: lpuart0grp {
+ fsl,pins = <
+ IMX8QXP_UART0_RX_ADMA_UART0_RX 0x06000020
+ IMX8QXP_UART0_TX_ADMA_UART0_TX 0x06000020
+ >;
+ };
+ };
+
+ ocotp {
+ compatible = "fsl,imx8qxp-scu-ocotp";
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ fec_mac0: mac@2c4 {
+ reg = <0x2c4 6>;
+ };
+ };
+
+ power-controller {
+ compatible = "fsl,imx8qxp-scu-pd", "fsl,scu-pd";
+ #power-domain-cells = <1>;
+ };
+
+ rtc {
+ compatible = "fsl,imx8qxp-sc-rtc";
+ };
+
+ keys {
+ compatible = "fsl,imx8qxp-sc-key", "fsl,imx-sc-key";
+ linux,keycodes = <KEY_POWER>;
+ };
+
+ watchdog {
+ compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt";
+ timeout-sec = <60>;
+ };
+
+ thermal-sensor {
+ compatible = "fsl,imx8qxp-sc-thermal", "fsl,imx-sc-thermal";
+ #thermal-sensor-cells = <1>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/firmware/google,gs101-acpm-ipc.yaml b/Documentation/devicetree/bindings/firmware/google,gs101-acpm-ipc.yaml
new file mode 100644
index 000000000000..d3bca6088d12
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/google,gs101-acpm-ipc.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2024 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/google,gs101-acpm-ipc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos ACPM mailbox protocol
+
+maintainers:
+ - Tudor Ambarus <tudor.ambarus@linaro.org>
+
+description: |
+ ACPM (Alive Clock and Power Manager) is a firmware that operates on the
+ APM (Active Power Management) module that handles overall power management
+ activities. ACPM and masters regard each other as independent hardware
+ component and communicate with each other using mailbox messages and
+ shared memory.
+
+ This binding is intended to define the interface the firmware implementing
+ ACPM provides for OSPM in the device tree.
+
+properties:
+ compatible:
+ const: google,gs101-acpm-ipc
+
+ "#clock-cells":
+ const: 1
+ description:
+ Clocks that are variable and index based. These clocks don't provide
+ an entire range of values between the limits but only discrete points
+ within the range. The firmware also manages the voltage scaling
+ appropriately with the clock scaling. The argument is the ID of the
+ clock contained by the firmware messages.
+
+ mboxes:
+ maxItems: 1
+
+ pmic:
+ description: Child node describing the main PMIC.
+ type: object
+ additionalProperties: true
+
+ properties:
+ compatible:
+ const: samsung,s2mpg10-pmic
+
+ shmem:
+ description:
+ List of phandle pointing to the shared memory (SHM) area. The memory
+ contains channels configuration data and the TX/RX ring buffers that
+ are used for passing messages to/from the ACPM firmware.
+ maxItems: 1
+
+required:
+ - compatible
+ - "#clock-cells"
+ - mboxes
+ - shmem
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ power-management {
+ compatible = "google,gs101-acpm-ipc";
+ #clock-cells = <1>;
+ mboxes = <&ap2apm_mailbox>;
+ shmem = <&apm_sram>;
+
+ pmic {
+ compatible = "samsung,s2mpg10-pmic";
+ interrupts-extended = <&gpa0 6 IRQ_TYPE_LEVEL_LOW>;
+
+ regulators {
+ LDO1 {
+ regulator-name = "vdd_ldo1";
+ regulator-min-microvolt = <700000>;
+ regulator-max-microvolt = <1300000>;
+ regulator-always-on;
+ };
+
+ // ...
+
+ BUCK1 {
+ regulator-name = "vdd_mif";
+ regulator-min-microvolt = <450000>;
+ regulator-max-microvolt = <1300000>;
+ regulator-always-on;
+ regulator-boot-on;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml b/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml
index c435c9f369a4..50f1f08744a1 100644
--- a/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml
+++ b/Documentation/devicetree/bindings/firmware/intel,ixp4xx-network-processing-engine.yaml
@@ -2,8 +2,8 @@
# Copyright 2019 Linaro Ltd.
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/firmware/intel,ixp4xx-network-processing-engine.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/firmware/intel,ixp4xx-network-processing-engine.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Intel IXP4xx Network Processing Engine
@@ -37,6 +37,20 @@ properties:
should be named with the instance number of the NPE engine used for
the crypto engine.
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ hss@[0-9]+$:
+ $ref: /schemas/net/intel,ixp4xx-hss.yaml#
+ type: object
+ description: Optional node for the High Speed Serial link (HSS), the
+ node should be named with the instance number of the NPE engine
+ used for the HSS.
+
required:
- compatible
- reg
@@ -45,15 +59,36 @@ additionalProperties: false
examples:
- |
+ #include <dt-bindings/gpio/gpio.h>
+
npe: npe@c8006000 {
- compatible = "intel,ixp4xx-network-processing-engine";
- reg = <0xc8006000 0x1000>, <0xc8007000 0x1000>, <0xc8008000 0x1000>;
-
- crypto {
- compatible = "intel,ixp4xx-crypto";
- intel,npe-handle = <&npe 2>;
- queue-rx = <&qmgr 30>;
- queue-txready = <&qmgr 29>;
- };
+ compatible = "intel,ixp4xx-network-processing-engine";
+ reg = <0xc8006000 0x1000>, <0xc8007000 0x1000>, <0xc8008000 0x1000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hss@0 {
+ compatible = "intel,ixp4xx-hss";
+ reg = <0>;
+ intel,npe-handle = <&npe 0>;
+ intel,queue-chl-rxtrig = <&qmgr 12>;
+ intel,queue-chl-txready = <&qmgr 34>;
+ intel,queue-pkt-rx = <&qmgr 13>;
+ intel,queue-pkt-tx = <&qmgr 14>, <&qmgr 15>, <&qmgr 16>, <&qmgr 17>;
+ intel,queue-pkt-rxfree = <&qmgr 18>, <&qmgr 19>, <&qmgr 20>, <&qmgr 21>;
+ intel,queue-pkt-txdone = <&qmgr 22>;
+ cts-gpios = <&gpio0 10 GPIO_ACTIVE_LOW>;
+ rts-gpios = <&gpio0 14 GPIO_ACTIVE_LOW>;
+ dcd-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>;
+ dtr-gpios = <&gpio_74 2 GPIO_ACTIVE_LOW>;
+ clk-internal-gpios = <&gpio_74 0 GPIO_ACTIVE_HIGH>;
+ };
+
+ crypto {
+ compatible = "intel,ixp4xx-crypto";
+ intel,npe-handle = <&npe 2>;
+ queue-rx = <&qmgr 30>;
+ queue-txready = <&qmgr 29>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt b/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt
deleted file mode 100644
index 6eff1afd8daf..000000000000
--- a/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt
+++ /dev/null
@@ -1,57 +0,0 @@
-Intel Service Layer Driver for Stratix10 SoC
-============================================
-Intel Stratix10 SoC is composed of a 64 bit quad-core ARM Cortex A53 hard
-processor system (HPS) and Secure Device Manager (SDM). When the FPGA is
-configured from HPS, there needs to be a way for HPS to notify SDM the
-location and size of the configuration data. Then SDM will get the
-configuration data from that location and perform the FPGA configuration.
-
-To meet the whole system security needs and support virtual machine requesting
-communication with SDM, only the secure world of software (EL3, Exception
-Layer 3) can interface with SDM. All software entities running on other
-exception layers must channel through the EL3 software whenever it needs
-service from SDM.
-
-Intel Stratix10 service layer driver, running at privileged exception level
-(EL1, Exception Layer 1), interfaces with the service providers and provides
-the services for FPGA configuration, QSPI, Crypto and warm reset. Service layer
-driver also manages secure monitor call (SMC) to communicate with secure monitor
-code running in EL3.
-
-Required properties:
--------------------
-The svc node has the following mandatory properties, must be located under
-the firmware node.
-
-- compatible: "intel,stratix10-svc" or "intel,agilex-svc"
-- method: smc or hvc
- smc - Secure Monitor Call
- hvc - Hypervisor Call
-- memory-region:
- phandle to the reserved memory node. See
- Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
- for details
-
-Example:
--------
-
- reserved-memory {
- #address-cells = <2>;
- #size-cells = <2>;
- ranges;
-
- service_reserved: svcbuffer@0 {
- compatible = "shared-dma-pool";
- reg = <0x0 0x0 0x0 0x1000000>;
- alignment = <0x1000>;
- no-map;
- };
- };
-
- firmware {
- svc {
- compatible = "intel,stratix10-svc";
- method = "smc";
- memory-region = <&service_reserved>;
- };
- };
diff --git a/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.yaml b/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.yaml
new file mode 100644
index 000000000000..b42cfa78b28b
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/intel,stratix10-svc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intel Service Layer Driver for Stratix10 SoC
+
+maintainers:
+ - Dinh Nguyen <dinguyen@kernel.org>
+ - Mahesh Rao <mahesh.rao@altera.com>
+
+description: >
+ Intel Stratix10 SoC is composed of a 64 bit quad-core ARM Cortex A53 hard
+ processor system (HPS) and Secure Device Manager (SDM). When the FPGA is
+ configured from HPS, there needs to be a way for HPS to notify SDM the
+ location and size of the configuration data. Then SDM will get the
+ configuration data from that location and perform the FPGA configuration.
+
+ To meet the whole system security needs and support virtual machine requesting
+ communication with SDM, only the secure world of software (EL3, Exception
+ Layer 3) can interface with SDM. All software entities running on other
+ exception layers must channel through the EL3 software whenever it needs
+ service from SDM.
+
+ Intel Stratix10 service layer driver, running at privileged exception level
+ (EL1, Exception Layer 1), interfaces with the service providers and provides
+ the services for FPGA configuration, QSPI, Crypto and warm reset. Service layer
+ driver also manages secure monitor call (SMC) to communicate with secure monitor
+ code running in EL3.
+
+properties:
+ compatible:
+ enum:
+ - intel,stratix10-svc
+ - intel,agilex-svc
+ - intel,agilex5-svc
+
+ method:
+ description: |
+ Supervisory call method to be used to communicate with the
+ secure service layer.
+ Permitted values are:
+ - "smc" : SMC #0, following the SMCCC
+ - "hvc" : HVC #0, following the SMCCC
+
+ $ref: /schemas/types.yaml#/definitions/string-array
+ enum:
+ - smc
+ - hvc
+
+ memory-region:
+ maxItems: 1
+ description:
+ reserved memory region for the service layer driver to
+ communicate with the secure device manager.
+
+ iommus:
+ maxItems: 1
+
+ fpga-mgr:
+ $ref: /schemas/fpga/intel,stratix10-soc-fpga-mgr.yaml
+ description: Optional child node for fpga manager to perform fabric configuration.
+
+required:
+ - compatible
+ - method
+ - memory-region
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - intel,agilex5-svc
+ then:
+ required:
+ - iommus
+
+additionalProperties: false
+
+examples:
+ - |
+ reserved-memory {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ service_reserved: svcbuffer@0 {
+ compatible = "shared-dma-pool";
+ reg = <0x0 0x0 0x0 0x1000000>;
+ alignment = <0x1000>;
+ no-map;
+ };
+ };
+
+ firmware {
+ svc {
+ compatible = "intel,stratix10-svc";
+ method = "smc";
+ memory-region = <&service_reserved>;
+
+ fpga-mgr {
+ compatible = "intel,stratix10-soc-fpga-mgr";
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/firmware/meson/meson_sm.txt b/Documentation/devicetree/bindings/firmware/meson/meson_sm.txt
deleted file mode 100644
index c248cd44f727..000000000000
--- a/Documentation/devicetree/bindings/firmware/meson/meson_sm.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-* Amlogic Secure Monitor
-
-In the Amlogic SoCs the Secure Monitor code is used to provide access to the
-NVMEM, enable JTAG, set USB boot, etc...
-
-Required properties for the secure monitor node:
-- compatible: Should be "amlogic,meson-gxbb-sm"
-
-Example:
-
- firmware {
- sm: secure-monitor {
- compatible = "amlogic,meson-gxbb-sm";
- };
- };
diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt
deleted file mode 100644
index e44a13bc06ed..000000000000
--- a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt
+++ /dev/null
@@ -1,107 +0,0 @@
-NVIDIA Tegra Boot and Power Management Processor (BPMP)
-
-The BPMP is a specific processor in Tegra chip, which is designed for
-booting process handling and offloading the power management, clock
-management, and reset control tasks from the CPU. The binding document
-defines the resources that would be used by the BPMP firmware driver,
-which can create the interprocessor communication (IPC) between the CPU
-and BPMP.
-
-Required properties:
-- compatible
- Array of strings
- One of:
- - "nvidia,tegra186-bpmp"
-- mboxes : The phandle of mailbox controller and the mailbox specifier.
-- shmem : List of the phandle of the TX and RX shared memory area that
- the IPC between CPU and BPMP is based on.
-- #clock-cells : Should be 1.
-- #power-domain-cells : Should be 1.
-- #reset-cells : Should be 1.
-
-This node is a mailbox consumer. See the following files for details of
-the mailbox subsystem, and the specifiers implemented by the relevant
-provider(s):
-
-- .../mailbox/mailbox.txt
-- .../mailbox/nvidia,tegra186-hsp.txt
-
-This node is a clock, power domain, and reset provider. See the following
-files for general documentation of those features, and the specifiers
-implemented by this node:
-
-- .../clock/clock-bindings.txt
-- <dt-bindings/clock/tegra186-clock.h>
-- ../power/power-domain.yaml
-- <dt-bindings/power/tegra186-powergate.h>
-- .../reset/reset.txt
-- <dt-bindings/reset/tegra186-reset.h>
-
-The BPMP implements some services which must be represented by separate nodes.
-For example, it can provide access to certain I2C controllers, and the I2C
-bindings represent each I2C controller as a device tree node. Such nodes should
-be nested directly inside the main BPMP node.
-
-Software can determine whether a child node of the BPMP node represents a device
-by checking for a compatible property. Any node with a compatible property
-represents a device that can be instantiated. Nodes without a compatible
-property may be used to provide configuration information regarding the BPMP
-itself, although no such configuration nodes are currently defined by this
-binding.
-
-The BPMP firmware defines no single global name-/numbering-space for such
-services. Put another way, the numbering scheme for I2C buses is distinct from
-the numbering scheme for any other service the BPMP may provide (e.g. a future
-hypothetical SPI bus service). As such, child device nodes will have no reg
-property, and the BPMP node will have no #address-cells or #size-cells property.
-
-The shared memory bindings for BPMP
------------------------------------
-
-The shared memory area for the IPC TX and RX between CPU and BPMP are
-predefined and work on top of sysram, which is an SRAM inside the chip.
-
-See ".../sram/sram.txt" for the bindings.
-
-Example:
-
-hsp_top0: hsp@3c00000 {
- ...
- #mbox-cells = <2>;
-};
-
-sysram@30000000 {
- compatible = "nvidia,tegra186-sysram", "mmio-sram";
- reg = <0x0 0x30000000 0x0 0x50000>;
- #address-cells = <2>;
- #size-cells = <2>;
- ranges = <0 0x0 0x0 0x30000000 0x0 0x50000>;
-
- cpu_bpmp_tx: shmem@4e000 {
- compatible = "nvidia,tegra186-bpmp-shmem";
- reg = <0x0 0x4e000 0x0 0x1000>;
- label = "cpu-bpmp-tx";
- pool;
- };
-
- cpu_bpmp_rx: shmem@4f000 {
- compatible = "nvidia,tegra186-bpmp-shmem";
- reg = <0x0 0x4f000 0x0 0x1000>;
- label = "cpu-bpmp-rx";
- pool;
- };
-};
-
-bpmp {
- compatible = "nvidia,tegra186-bpmp";
- mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_BPMP>;
- shmem = <&cpu_bpmp_tx &cpu_bpmp_rx>;
- #clock-cells = <1>;
- #power-domain-cells = <1>;
- #reset-cells = <1>;
-
- i2c {
- compatible = "...";
- ...
- };
-};
diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml
new file mode 100644
index 000000000000..3c44fe607e12
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.yaml
@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/nvidia,tegra186-bpmp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra Boot and Power Management Processor (BPMP)
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+description: |
+ The BPMP is a specific processor in Tegra chip, which is designed for
+ booting process handling and offloading the power management, clock
+ management, and reset control tasks from the CPU. The binding document
+ defines the resources that would be used by the BPMP firmware driver,
+ which can create the interprocessor communication (IPC) between the
+ CPU and BPMP.
+
+ This node is a mailbox consumer. See the following files for details
+ of the mailbox subsystem, and the specifiers implemented by the
+ relevant provider(s):
+
+ - .../mailbox/mailbox.txt
+ - .../mailbox/nvidia,tegra186-hsp.yaml
+
+ This node is a clock, power domain, and reset provider. See the
+ following files for general documentation of those features, and the
+ specifiers implemented by this node:
+
+ - .../clock/clock-bindings.txt
+ - <dt-bindings/clock/tegra186-clock.h>
+ - ../power/power-domain.yaml
+ - <dt-bindings/power/tegra186-powergate.h>
+ - .../reset/reset.txt
+ - <dt-bindings/reset/tegra186-reset.h>
+
+ The BPMP implements some services which must be represented by
+ separate nodes. For example, it can provide access to certain I2C
+ controllers, and the I2C bindings represent each I2C controller as a
+ device tree node. Such nodes should be nested directly inside the main
+ BPMP node.
+
+ Software can determine whether a child node of the BPMP node
+ represents a device by checking for a compatible property. Any node
+ with a compatible property represents a device that can be
+ instantiated. Nodes without a compatible property may be used to
+ provide configuration information regarding the BPMP itself, although
+ no such configuration nodes are currently defined by this binding.
+
+ The BPMP firmware defines no single global name-/numbering-space for
+ such services. Put another way, the numbering scheme for I2C buses is
+ distinct from the numbering scheme for any other service the BPMP may
+ provide (e.g. a future hypothetical SPI bus service). As such, child
+ device nodes will have no reg property, and the BPMP node will have no
+ "#address-cells" or "#size-cells" property.
+
+ The shared memory area for the IPC TX and RX between CPU and BPMP are
+ predefined and work on top of either sysram, which is an SRAM inside the
+ chip, or in normal SDRAM.
+ See ".../sram/sram.yaml" for the bindings for the SRAM case.
+ See "../reserved-memory/nvidia,tegra264-bpmp-shmem.yaml" for bindings for
+ the SDRAM case.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - nvidia,tegra194-bpmp
+ - nvidia,tegra234-bpmp
+ - nvidia,tegra264-bpmp
+ - const: nvidia,tegra186-bpmp
+ - const: nvidia,tegra186-bpmp
+
+ mboxes:
+ description: A phandle and channel specifier for the mailbox used to
+ communicate with the BPMP.
+ maxItems: 1
+
+ shmem:
+ description: List of the phandle to the TX and RX shared memory area
+ that the IPC between CPU and BPMP is based on.
+ minItems: 2
+ maxItems: 2
+
+ memory-region:
+ description: phandle to reserved memory region used for IPC between
+ CPU-NS and BPMP.
+ maxItems: 1
+
+ "#clock-cells":
+ const: 1
+
+ "#power-domain-cells":
+ const: 1
+
+ "#reset-cells":
+ const: 1
+
+ interconnects:
+ items:
+ - description: memory read client
+ - description: memory write client
+ - description: DMA read client
+ - description: DMA write client
+
+ interconnect-names:
+ items:
+ - const: read
+ - const: write
+ - const: dma-mem # dma-read
+ - const: dma-write
+
+ iommus:
+ maxItems: 1
+
+ i2c:
+ type: object
+
+ thermal:
+ type: object
+
+additionalProperties: false
+
+oneOf:
+ - required:
+ - memory-region
+ - required:
+ - shmem
+
+required:
+ - compatible
+ - mboxes
+ - "#clock-cells"
+ - "#power-domain-cells"
+ - "#reset-cells"
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/mailbox/tegra186-hsp.h>
+ #include <dt-bindings/memory/tegra186-mc.h>
+
+ hsp_top0: hsp@3c00000 {
+ compatible = "nvidia,tegra186-hsp";
+ reg = <0x03c00000 0xa0000>;
+ interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "doorbell";
+ #mbox-cells = <2>;
+ };
+
+ sram@30000000 {
+ compatible = "nvidia,tegra186-sysram", "mmio-sram";
+ reg = <0x30000000 0x50000>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0x0 0x30000000 0x50000>;
+
+ cpu_bpmp_tx: sram@4e000 {
+ reg = <0x4e000 0x1000>;
+ label = "cpu-bpmp-tx";
+ pool;
+ };
+
+ cpu_bpmp_rx: sram@4f000 {
+ reg = <0x4f000 0x1000>;
+ label = "cpu-bpmp-rx";
+ pool;
+ };
+ };
+
+ bpmp {
+ compatible = "nvidia,tegra186-bpmp";
+ interconnects = <&mc TEGRA186_MEMORY_CLIENT_BPMPR &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_BPMPW &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAR &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAW &emc>;
+ interconnect-names = "read", "write", "dma-mem", "dma-write";
+ iommus = <&smmu TEGRA186_SID_BPMP>;
+ mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_BPMP>;
+ shmem = <&cpu_bpmp_tx>, <&cpu_bpmp_rx>;
+ #clock-cells = <1>;
+ #power-domain-cells = <1>;
+ #reset-cells = <1>;
+
+ i2c {
+ compatible = "nvidia,tegra186-bpmp-i2c";
+ nvidia,bpmp-bus-id = <5>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+
+ thermal {
+ compatible = "nvidia,tegra186-bpmp-thermal";
+ #thermal-sensor-cells = <1>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/mailbox/tegra186-hsp.h>
+
+ bpmp {
+ compatible = "nvidia,tegra186-bpmp";
+ interconnects = <&mc TEGRA186_MEMORY_CLIENT_BPMPR &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_BPMPW &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAR &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_BPMPDMAW &emc>;
+ interconnect-names = "read", "write", "dma-mem", "dma-write";
+ mboxes = <&hsp_top1 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_BPMP>;
+ memory-region = <&dram_cpu_bpmp_mail>;
+ #clock-cells = <1>;
+ #power-domain-cells = <1>;
+ #reset-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/firmware/nxp,imx95-scmi-pinctrl.yaml b/Documentation/devicetree/bindings/firmware/nxp,imx95-scmi-pinctrl.yaml
new file mode 100644
index 000000000000..a96fc6cce502
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/nxp,imx95-scmi-pinctrl.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2024 NXP
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/nxp,imx95-scmi-pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX System Control and Management Interface (SCMI) Pinctrl Protocol
+
+maintainers:
+ - Peng Fan <peng.fan@nxp.com>
+
+allOf:
+ - $ref: /schemas/pinctrl/pinctrl.yaml
+
+patternProperties:
+ 'grp$':
+ type: object
+ description:
+ Pinctrl node's client devices use subnodes for desired pin configuration.
+ Client device subnodes use below standard properties.
+
+ unevaluatedProperties: false
+
+ properties:
+ fsl,pins:
+ description:
+ each entry consists of 6 integers and represents the mux and config
+ setting for one pin. The first 5 integers <mux_reg conf_reg input_reg
+ mux_val input_val> are specified using a PIN_FUNC_ID macro, which can
+ be found in <arch/arm64/boot/dts/freescale/imx95-pinfunc.h>. The last
+ integer CONFIG is the pad setting value like pull-up on this pin.
+ Please refer to i.MX95 Reference Manual for detailed CONFIG settings.
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ items:
+ items:
+ - description: |
+ "mux_reg" indicates the offset of mux register.
+ - description: |
+ "conf_reg" indicates the offset of pad configuration register.
+ - description: |
+ "input_reg" indicates the offset of select input register.
+ - description: |
+ "mux_val" indicates the mux value to be applied.
+ - description: |
+ "input_val" indicates the select input value to be applied.
+ - description: |
+ "pad_setting" indicates the pad configuration value to be applied.
+
+ required:
+ - fsl,pins
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/firmware/nxp,imx95-scmi.yaml b/Documentation/devicetree/bindings/firmware/nxp,imx95-scmi.yaml
new file mode 100644
index 000000000000..7a5a02da2719
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/nxp,imx95-scmi.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2024 NXP
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/nxp,imx95-scmi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX95 System Control and Management Interface(SCMI) Vendor Protocols Extension
+
+maintainers:
+ - Peng Fan <peng.fan@nxp.com>
+
+properties:
+ protocol@80:
+ description:
+ SCMI LMM protocol which is for boot, shutdown, and reset of other logical
+ machines (LM). It is usually used to allow one LM to manage another used
+ as an offload or accelerator engine.
+ $ref: '/schemas/firmware/arm,scmi.yaml#/$defs/protocol-node'
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0x80
+
+ protocol@81:
+ type: object
+ allOf:
+ - $ref: '/schemas/firmware/arm,scmi.yaml#/$defs/protocol-node'
+ - $ref: /schemas/input/input.yaml#
+ additionalProperties: false
+
+ properties:
+ reg:
+ const: 0x81
+
+ linux,code:
+ default: 116 # KEY_POWER
+
+ protocol@82:
+ description:
+ SCMI CPU Protocol which allows an agent to start or stop a CPU. It is
+ used to manage auxiliary CPUs in a LM.
+ $ref: '/schemas/firmware/arm,scmi.yaml#/$defs/protocol-node'
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0x82
+
+ protocol@84:
+ $ref: '/schemas/firmware/arm,scmi.yaml#/$defs/protocol-node'
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0x84
+
+ nxp,ctrl-ids:
+ description:
+ Each entry consists of 2 integers, represents the ctrl id and the value
+ items:
+ items:
+ - description: the ctrl id index
+ enum: [0, 1, 2, 3, 4, 5, 6, 7, 0x8000, 0x8001, 0x8002, 0x8003,
+ 0x8004, 0x8005, 0x8006, 0x8007]
+ - description: the value assigned to the ctrl id
+ minItems: 1
+ maxItems: 16
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt
deleted file mode 100644
index a7333ad938d2..000000000000
--- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-QCOM Secure Channel Manager (SCM)
-
-Qualcomm processors include an interface to communicate to the secure firmware.
-This interface allows for clients to request different types of actions. These
-can include CPU power up/down, HDCP requests, loading of firmware, and other
-assorted actions.
-
-Required properties:
-- compatible: must contain one of the following:
- * "qcom,scm-apq8064"
- * "qcom,scm-apq8084"
- * "qcom,scm-ipq4019"
- * "qcom,scm-ipq806x"
- * "qcom,scm-ipq8074"
- * "qcom,scm-mdm9607"
- * "qcom,scm-msm8660"
- * "qcom,scm-msm8916"
- * "qcom,scm-msm8960"
- * "qcom,scm-msm8974"
- * "qcom,scm-msm8994"
- * "qcom,scm-msm8996"
- * "qcom,scm-msm8998"
- * "qcom,scm-sc7180"
- * "qcom,scm-sc7280"
- * "qcom,scm-sdm845"
- * "qcom,scm-sdx55"
- * "qcom,scm-sm8150"
- * "qcom,scm-sm8250"
- * "qcom,scm-sm8350"
- and:
- * "qcom,scm"
-- clocks: Specifies clocks needed by the SCM interface, if any:
- * core clock required for "qcom,scm-apq8064", "qcom,scm-msm8660" and
- "qcom,scm-msm8960"
- * core, iface and bus clocks required for "qcom,scm-apq8084",
- "qcom,scm-msm8916" and "qcom,scm-msm8974"
-- clock-names: Must contain "core" for the core clock, "iface" for the interface
- clock and "bus" for the bus clock per the requirements of the compatible.
-- qcom,dload-mode: phandle to the TCSR hardware block and offset of the
- download mode control register (optional)
-
-Example for MSM8916:
-
- firmware {
- scm {
- compatible = "qcom,msm8916", "qcom,scm";
- clocks = <&gcc GCC_CRYPTO_CLK> ,
- <&gcc GCC_CRYPTO_AXI_CLK>,
- <&gcc GCC_CRYPTO_AHB_CLK>;
- clock-names = "core", "bus", "iface";
- };
- };
diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml
new file mode 100644
index 000000000000..d66459f1d84e
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml
@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/qcom,scm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: QCOM Secure Channel Manager (SCM)
+
+description: |
+ Qualcomm processors include an interface to communicate to the secure firmware.
+ This interface allows for clients to request different types of actions.
+ These can include CPU power up/down, HDCP requests, loading of firmware,
+ and other assorted actions.
+
+maintainers:
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+ - Robert Marko <robimarko@gmail.com>
+ - Guru Das Srinagesh <quic_gurus@quicinc.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - qcom,scm-apq8064
+ - qcom,scm-apq8084
+ - qcom,scm-glymur
+ - qcom,scm-ipq4019
+ - qcom,scm-ipq5018
+ - qcom,scm-ipq5332
+ - qcom,scm-ipq5424
+ - qcom,scm-ipq6018
+ - qcom,scm-ipq806x
+ - qcom,scm-ipq8074
+ - qcom,scm-ipq9574
+ - qcom,scm-kaanapali
+ - qcom,scm-mdm9607
+ - qcom,scm-milos
+ - qcom,scm-msm8226
+ - qcom,scm-msm8660
+ - qcom,scm-msm8916
+ - qcom,scm-msm8937
+ - qcom,scm-msm8953
+ - qcom,scm-msm8960
+ - qcom,scm-msm8974
+ - qcom,scm-msm8976
+ - qcom,scm-msm8994
+ - qcom,scm-msm8996
+ - qcom,scm-msm8998
+ - qcom,scm-qcm2290
+ - qcom,scm-qcs615
+ - qcom,scm-qcs8300
+ - qcom,scm-qdu1000
+ - qcom,scm-sa8255p
+ - qcom,scm-sa8775p
+ - qcom,scm-sar2130p
+ - qcom,scm-sc7180
+ - qcom,scm-sc7280
+ - qcom,scm-sc8180x
+ - qcom,scm-sc8280xp
+ - qcom,scm-sdm670
+ - qcom,scm-sdm845
+ - qcom,scm-sdx55
+ - qcom,scm-sdx65
+ - qcom,scm-sdx75
+ - qcom,scm-sm6115
+ - qcom,scm-sm6125
+ - qcom,scm-sm6350
+ - qcom,scm-sm6375
+ - qcom,scm-sm7150
+ - qcom,scm-sm8150
+ - qcom,scm-sm8250
+ - qcom,scm-sm8350
+ - qcom,scm-sm8450
+ - qcom,scm-sm8550
+ - qcom,scm-sm8650
+ - qcom,scm-sm8750
+ - qcom,scm-qcs404
+ - qcom,scm-x1e80100
+ - const: qcom,scm
+
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ minItems: 1
+ maxItems: 3
+
+ dma-coherent: true
+
+ interconnects:
+ maxItems: 1
+
+ interconnect-names:
+ maxItems: 1
+
+ '#reset-cells':
+ const: 1
+
+ interrupts:
+ description:
+ The wait-queue interrupt that firmware raises as part of handshake
+ protocol to handle sleeping SCM calls.
+ maxItems: 1
+
+ memory-region:
+ description:
+ Phandle to the memory region reserved for the shared memory bridge to TZ.
+ maxItems: 1
+
+ qcom,sdi-enabled:
+ description:
+ Indicates that the SDI (Secure Debug Image) has been enabled by TZ
+ by default and it needs to be disabled.
+ If not disabled WDT assertion or reboot will cause the board to hang
+ in the debug mode.
+ type: boolean
+
+ qcom,dload-mode:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to TCSR hardware block
+ - description: offset of the download mode control register
+ description: TCSR hardware block
+
+allOf:
+ # Clocks
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,scm-apq8064
+ - qcom,scm-apq8084
+ - qcom,scm-mdm9607
+ - qcom,scm-msm8226
+ - qcom,scm-msm8660
+ - qcom,scm-msm8916
+ - qcom,scm-msm8937
+ - qcom,scm-msm8953
+ - qcom,scm-msm8960
+ - qcom,scm-msm8974
+ - qcom,scm-msm8976
+ - qcom,scm-qcm2290
+ - qcom,scm-sm6375
+ then:
+ required:
+ - clocks
+ - clock-names
+ else:
+ properties:
+ clock-names: false
+ clocks: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,scm-apq8064
+ - qcom,scm-msm8660
+ - qcom,scm-msm8960
+ - qcom,scm-qcm2290
+ - qcom,scm-sm6375
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: core
+
+ clocks:
+ maxItems: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,scm-apq8084
+ - qcom,scm-mdm9607
+ - qcom,scm-msm8226
+ - qcom,scm-msm8916
+ - qcom,scm-msm8937
+ - qcom,scm-msm8953
+ - qcom,scm-msm8974
+ - qcom,scm-msm8976
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: core
+ - const: bus
+ - const: iface
+
+ clocks:
+ minItems: 3
+ maxItems: 3
+
+ # Interrupts
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,scm-kaanapali
+ - qcom,scm-milos
+ - qcom,scm-sm8450
+ - qcom,scm-sm8550
+ - qcom,scm-sm8650
+ - qcom,scm-sm8750
+ then:
+ properties:
+ interrupts: false
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,scm-sa8255p
+ - qcom,scm-sa8775p
+ then:
+ properties:
+ memory-region: false
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-msm8916.h>
+
+ firmware {
+ scm {
+ compatible = "qcom,scm-msm8916", "qcom,scm";
+ clocks = <&gcc GCC_CRYPTO_CLK>,
+ <&gcc GCC_CRYPTO_AXI_CLK>,
+ <&gcc GCC_CRYPTO_AHB_CLK>;
+ clock-names = "core", "bus", "iface";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml b/Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml
new file mode 100644
index 000000000000..c6fc1d6e25da
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/qemu,fw-cfg-mmio.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/qemu,fw-cfg-mmio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: QEMU Firmware Configuration
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+description: |
+ Various QEMU emulation / virtualization targets provide the following
+ Firmware Configuration interface on the "virt" machine type:
+
+ - A write-only, 16-bit wide selector (or control) register,
+ - a read-write, 64-bit wide data register.
+
+ QEMU exposes the control and data register to guests as memory mapped
+ registers; their location is communicated to the guest's UEFI firmware in the
+ DTB that QEMU places at the bottom of the guest's DRAM.
+
+ The authoritative guest-side hardware interface documentation to the fw_cfg
+ device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree.
+
+properties:
+ compatible:
+ const: qemu,fw-cfg-mmio
+
+ reg:
+ maxItems: 1
+ description: |
+ * Bytes 0x0 to 0x7 cover the data register.
+ * Bytes 0x8 to 0x9 cover the selector register.
+ * Further registers may be appended to the region in case of future interface
+ revisions / feature bits.
+
+ dma-coherent: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+
+ fw-cfg@9020000 {
+ compatible = "qemu,fw-cfg-mmio";
+ reg = <0x9020000 0xa>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml b/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
new file mode 100644
index 000000000000..3365124c7fd4
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/thead,th1520-aon.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: T-HEAD TH1520 AON (Always-On) Firmware
+
+description: |
+ The Always-On (AON) subsystem in the TH1520 SoC is responsible for managing
+ low-power states, system wakeup events, and power management tasks. It is
+ designed to operate independently in a dedicated power domain, allowing it to
+ remain functional even during the SoC's deep sleep states.
+
+ At the heart of the AON subsystem is the E902, a low-power core that executes
+ firmware responsible for coordinating tasks such as power domain control,
+ clock management, and system wakeup signaling. Communication between the main
+ SoC and the AON subsystem is handled through a mailbox interface, which
+ enables message-based interactions with the AON firmware.
+
+maintainers:
+ - Michal Wilczynski <m.wilczynski@samsung.com>
+
+properties:
+ compatible:
+ const: thead,th1520-aon
+
+ mboxes:
+ maxItems: 1
+
+ mbox-names:
+ items:
+ - const: aon
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: gpu-clkgen
+
+ "#power-domain-cells":
+ const: 1
+
+required:
+ - compatible
+ - mboxes
+ - mbox-names
+ - "#power-domain-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ aon: aon {
+ compatible = "thead,th1520-aon";
+ mboxes = <&mbox_910t 1>;
+ mbox-names = "aon";
+ #power-domain-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt
deleted file mode 100644
index 18c3aea90df2..000000000000
--- a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt
+++ /dev/null
@@ -1,44 +0,0 @@
------------------------------------------------------------------
-Device Tree Bindings for the Xilinx Zynq MPSoC Firmware Interface
------------------------------------------------------------------
-
-The zynqmp-firmware node describes the interface to platform firmware.
-ZynqMP has an interface to communicate with secure firmware. Firmware
-driver provides an interface to firmware APIs. Interface APIs can be
-used by any driver to communicate to PMUFW(Platform Management Unit).
-These requests include clock management, pin control, device control,
-power management service, FPGA service and other platform management
-services.
-
-Required properties:
- - compatible: Must contain any of below:
- "xlnx,zynqmp-firmware" for Zynq Ultrascale+ MPSoC
- "xlnx,versal-firmware" for Versal
- - method: The method of calling the PM-API firmware layer.
- Permitted values are:
- - "smc" : SMC #0, following the SMCCC
- - "hvc" : HVC #0, following the SMCCC
-
--------
-Example
--------
-
-Zynq Ultrascale+ MPSoC
-----------------------
-firmware {
- zynqmp_firmware: zynqmp-firmware {
- compatible = "xlnx,zynqmp-firmware";
- method = "smc";
- ...
- };
-};
-
-Versal
-------
-firmware {
- versal_firmware: versal-firmware {
- compatible = "xlnx,versal-firmware";
- method = "smc";
- ...
- };
-};
diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml
new file mode 100644
index 000000000000..ab8f32c440df
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/xilinx/xlnx,zynqmp-firmware.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx firmware driver
+
+maintainers:
+ - Nava kishore Manne <nava.kishore.manne@amd.com>
+
+description: The zynqmp-firmware node describes the interface to platform
+ firmware. ZynqMP has an interface to communicate with secure firmware.
+ Firmware driver provides an interface to firmware APIs. Interface APIs
+ can be used by any driver to communicate to PMUFW(Platform Management Unit).
+ These requests include clock management, pin control, device control,
+ power management service, FPGA service and other platform management
+ services.
+
+properties:
+ compatible:
+ oneOf:
+ - description: For implementations complying for Zynq Ultrascale+ MPSoC.
+ const: xlnx,zynqmp-firmware
+
+ - description: For implementations complying for Versal.
+ const: xlnx,versal-firmware
+
+ - description: For implementations complying for Versal NET.
+ items:
+ - enum:
+ - xlnx,versal-net-firmware
+ - const: xlnx,versal-firmware
+
+ method:
+ description: |
+ The method of calling the PM-API firmware layer.
+ Permitted values are.
+ - "smc" : SMC #0, following the SMCCC
+ - "hvc" : HVC #0, following the SMCCC
+
+ $ref: /schemas/types.yaml#/definitions/string-array
+ enum:
+ - smc
+ - hvc
+
+ "#power-domain-cells":
+ const: 1
+
+ clock-controller:
+ $ref: /schemas/clock/xlnx,versal-clk.yaml#
+ description: The clock controller is a hardware block of Xilinx versal
+ clock tree. It reads required input clock frequencies from the devicetree
+ and acts as clock provider for all clock consumers of PS clocks.list of
+ clock specifiers which are external input clocks to the given clock
+ controller.
+ type: object
+
+ gpio:
+ $ref: /schemas/gpio/xlnx,zynqmp-gpio-modepin.yaml#
+ description: The gpio node describes connect to PS_MODE pins via firmware
+ interface.
+ type: object
+
+ soc-nvmem:
+ $ref: /schemas/nvmem/xlnx,zynqmp-nvmem.yaml#
+ description: The ZynqMP MPSoC provides access to the hardware related data
+ like SOC revision, IDCODE and specific purpose efuses.
+ type: object
+
+ pcap:
+ $ref: /schemas/fpga/xlnx,zynqmp-pcap-fpga.yaml
+ description: The ZynqMP SoC uses the PCAP (Processor Configuration Port) to
+ configure the Programmable Logic (PL). The configuration uses the
+ firmware interface.
+ type: object
+
+ pinctrl:
+ $ref: /schemas/pinctrl/xlnx,zynqmp-pinctrl.yaml#
+ description: The pinctrl node provides access to pinconfig and pincontrol
+ functionality available in firmware.
+ type: object
+
+ power-management:
+ $ref: /schemas/power/reset/xlnx,zynqmp-power.yaml#
+ description: The zynqmp-power node describes the power management
+ configurations. It will control remote suspend/shutdown interfaces.
+ type: object
+
+ reset-controller:
+ $ref: /schemas/reset/xlnx,zynqmp-reset.yaml#
+ description: The reset-controller node describes connection to the reset
+ functionality via firmware interface.
+ type: object
+
+ versal-fpga:
+ $ref: /schemas/fpga/xlnx,versal-fpga.yaml#
+ description: Compatible of the FPGA device.
+ type: object
+
+ zynqmp-aes:
+ $ref: /schemas/crypto/xlnx,zynqmp-aes.yaml#
+ description: The ZynqMP AES-GCM hardened cryptographic accelerator is
+ used to encrypt or decrypt the data with provided key and initialization
+ vector.
+ type: object
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/power/xlnx-zynqmp-power.h>
+ firmware {
+ zynqmp_firmware: zynqmp-firmware {
+ #power-domain-cells = <1>;
+ soc-nvmem {
+ compatible = "xlnx,zynqmp-nvmem-fw";
+ nvmem-layout {
+ compatible = "fixed-layout";
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ soc_revision: soc-revision@0 {
+ reg = <0x0 0x4>;
+ };
+ };
+ };
+ gpio {
+ compatible = "xlnx,zynqmp-gpio-modepin";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+ pcap {
+ compatible = "xlnx,zynqmp-pcap-fpga";
+ };
+ pinctrl {
+ compatible = "xlnx,zynqmp-pinctrl";
+ };
+ power-management {
+ compatible = "xlnx,zynqmp-power";
+ interrupts = <0 35 4>;
+ };
+ reset-controller {
+ compatible = "xlnx,zynqmp-reset";
+ #reset-cells = <1>;
+ };
+ };
+ };
+
+ sata {
+ power-domains = <&zynqmp_firmware PD_SATA>;
+ };
+
+ versal-firmware {
+ compatible = "xlnx,versal-firmware";
+ method = "smc";
+
+ versal_fpga: versal-fpga {
+ compatible = "xlnx,versal-fpga";
+ };
+
+ xlnx_aes: zynqmp-aes {
+ compatible = "xlnx,zynqmp-aes";
+ };
+
+ versal_clk: clock-controller {
+ #clock-cells = <1>;
+ compatible = "xlnx,versal-clk";
+ clocks = <&ref>, <&pl_alt_ref>;
+ clock-names = "ref", "pl_alt_ref";
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
deleted file mode 100644
index 5dd0ff0f7b4e..000000000000
--- a/Documentation/devicetree/bindings/fpga/altera-fpga2sdram-bridge.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-Altera FPGA To SDRAM Bridge Driver
-
-Required properties:
-- compatible : Should contain "altr,socfpga-fpga2sdram-bridge"
-
-See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
-
-Example:
- fpga_bridge3: fpga-bridge@ffc25080 {
- compatible = "altr,socfpga-fpga2sdram-bridge";
- reg = <0xffc25080 0x4>;
- bridge-enable = <0>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt
deleted file mode 100644
index 8b26fbcff3c6..000000000000
--- a/Documentation/devicetree/bindings/fpga/altera-freeze-bridge.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Altera Freeze Bridge Controller Driver
-
-The Altera Freeze Bridge Controller manages one or more freeze bridges.
-The controller can freeze/disable the bridges which prevents signal
-changes from passing through the bridge. The controller can also
-unfreeze/enable the bridges which allows traffic to pass through the
-bridge normally.
-
-Required properties:
-- compatible : Should contain "altr,freeze-bridge-controller"
-- regs : base address and size for freeze bridge module
-
-See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
-
-Example:
- freeze-controller@100000450 {
- compatible = "altr,freeze-bridge-controller";
- regs = <0x1000 0x10>;
- bridge-enable = <0>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
deleted file mode 100644
index 68cce3945b10..000000000000
--- a/Documentation/devicetree/bindings/fpga/altera-hps2fpga-bridge.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-Altera FPGA/HPS Bridge Driver
-
-Required properties:
-- regs : base address and size for AXI bridge module
-- compatible : Should contain one of:
- "altr,socfpga-lwhps2fpga-bridge",
- "altr,socfpga-hps2fpga-bridge", or
- "altr,socfpga-fpga2hps-bridge"
-- resets : Phandle and reset specifier for this bridge's reset
-- clocks : Clocks used by this module.
-
-See Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
-
-Example:
- fpga_bridge0: fpga-bridge@ff400000 {
- compatible = "altr,socfpga-lwhps2fpga-bridge";
- reg = <0xff400000 0x100000>;
- resets = <&rst LWHPS2FPGA_RESET>;
- clocks = <&l4_main_clk>;
- bridge-enable = <0>;
- };
-
- fpga_bridge1: fpga-bridge@ff500000 {
- compatible = "altr,socfpga-hps2fpga-bridge";
- reg = <0xff500000 0x10000>;
- resets = <&rst HPS2FPGA_RESET>;
- clocks = <&l4_main_clk>;
- bridge-enable = <1>;
- };
-
- fpga_bridge2: fpga-bridge@ff600000 {
- compatible = "altr,socfpga-fpga2hps-bridge";
- reg = <0xff600000 0x100000>;
- resets = <&rst FPGA2HPS_RESET>;
- clocks = <&l4_main_clk>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/altera-passive-serial.txt b/Documentation/devicetree/bindings/fpga/altera-passive-serial.txt
deleted file mode 100644
index 48478bc07e29..000000000000
--- a/Documentation/devicetree/bindings/fpga/altera-passive-serial.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-Altera Passive Serial SPI FPGA Manager
-
-Altera FPGAs support a method of loading the bitstream over what is
-referred to as "passive serial".
-The passive serial link is not technically SPI, and might require extra
-circuits in order to play nicely with other SPI slaves on the same bus.
-
-See https://www.altera.com/literature/hb/cyc/cyc_c51013.pdf
-
-Required properties:
-- compatible: Must be one of the following:
- "altr,fpga-passive-serial",
- "altr,fpga-arria10-passive-serial"
-- reg: SPI chip select of the FPGA
-- nconfig-gpios: config pin (referred to as nCONFIG in the manual)
-- nstat-gpios: status pin (referred to as nSTATUS in the manual)
-
-Optional properties:
-- confd-gpios: confd pin (referred to as CONF_DONE in the manual)
-
-Example:
- fpga: fpga@0 {
- compatible = "altr,fpga-passive-serial";
- spi-max-frequency = <20000000>;
- reg = <0>;
- nconfig-gpios = <&gpio4 9 GPIO_ACTIVE_LOW>;
- nstat-gpios = <&gpio4 11 GPIO_ACTIVE_LOW>;
- confd-gpios = <&gpio4 12 GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/altr,fpga-passive-serial.yaml b/Documentation/devicetree/bindings/fpga/altr,fpga-passive-serial.yaml
new file mode 100644
index 000000000000..ffb7cc54556f
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altr,fpga-passive-serial.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/altr,fpga-passive-serial.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera Passive Serial SPI FPGA Manager
+
+maintainers:
+ - Fabio Estevam <festevam@denx.de>
+
+description: |
+ Altera FPGAs support a method of loading the bitstream over what is
+ referred to as "passive serial".
+ The passive serial link is not technically SPI, and might require extra
+ circuits in order to play nicely with other SPI slaves on the same bus.
+
+ See https://www.altera.com/literature/hb/cyc/cyc_c51013.pdf
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - altr,fpga-passive-serial
+ - altr,fpga-arria10-passive-serial
+
+ spi-max-frequency:
+ maximum: 20000000
+
+ reg:
+ maxItems: 1
+
+ nconfig-gpios:
+ description:
+ Config pin (referred to as nCONFIG in the manual).
+ maxItems: 1
+
+ nstat-gpios:
+ description:
+ Status pin (referred to as nSTATUS in the manual).
+ maxItems: 1
+
+ confd-gpios:
+ description:
+ confd pin (referred to as CONF_DONE in the manual)
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - nconfig-gpios
+ - nstat-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fpga@0 {
+ compatible = "altr,fpga-passive-serial";
+ reg = <0>;
+ nconfig-gpios = <&gpio4 18 GPIO_ACTIVE_LOW>;
+ nstat-gpios = <&gpio4 19 GPIO_ACTIVE_LOW>;
+ confd-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/fpga/altr,freeze-bridge-controller.yaml b/Documentation/devicetree/bindings/fpga/altr,freeze-bridge-controller.yaml
new file mode 100644
index 000000000000..fccffeebb256
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altr,freeze-bridge-controller.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/altr,freeze-bridge-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera Freeze Bridge Controller
+
+description:
+ The Altera Freeze Bridge Controller manages one or more freeze bridges.
+ The controller can freeze/disable the bridges which prevents signal
+ changes from passing through the bridge. The controller can also
+ unfreeze/enable the bridges which allows traffic to pass through the bridge
+ normally.
+
+maintainers:
+ - Xu Yilun <yilun.xu@intel.com>
+
+allOf:
+ - $ref: fpga-bridge.yaml#
+
+properties:
+ compatible:
+ const: altr,freeze-bridge-controller
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ fpga-bridge@100000450 {
+ compatible = "altr,freeze-bridge-controller";
+ reg = <0x1000 0x10>;
+ bridge-enable = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/altr,socfpga-fpga2sdram-bridge.yaml b/Documentation/devicetree/bindings/fpga/altr,socfpga-fpga2sdram-bridge.yaml
new file mode 100644
index 000000000000..22b58453c5ff
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altr,socfpga-fpga2sdram-bridge.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/altr,socfpga-fpga2sdram-bridge.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera FPGA To SDRAM Bridge
+
+maintainers:
+ - Xu Yilun <yilun.xu@intel.com>
+
+allOf:
+ - $ref: fpga-bridge.yaml#
+
+properties:
+ compatible:
+ const: altr,socfpga-fpga2sdram-bridge
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ fpga-bridge@ffc25080 {
+ compatible = "altr,socfpga-fpga2sdram-bridge";
+ reg = <0xffc25080 0x4>;
+ bridge-enable = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/altr,socfpga-hps2fpga-bridge.yaml b/Documentation/devicetree/bindings/fpga/altr,socfpga-hps2fpga-bridge.yaml
new file mode 100644
index 000000000000..d19c6660d6c9
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altr,socfpga-hps2fpga-bridge.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/altr,socfpga-hps2fpga-bridge.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera FPGA/HPS Bridge
+
+maintainers:
+ - Xu Yilun <yilun.xu@intel.com>
+
+allOf:
+ - $ref: fpga-bridge.yaml#
+
+properties:
+ compatible:
+ enum:
+ - altr,socfpga-lwhps2fpga-bridge
+ - altr,socfpga-hps2fpga-bridge
+ - altr,socfpga-fpga2hps-bridge
+
+ reg:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - resets
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/reset/altr,rst-mgr.h>
+
+ fpga-bridge@ff400000 {
+ compatible = "altr,socfpga-lwhps2fpga-bridge";
+ reg = <0xff400000 0x100000>;
+ bridge-enable = <0>;
+ clocks = <&l4_main_clk>;
+ resets = <&rst LWHPS2FPGA_RESET>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/fpga-bridge.txt b/Documentation/devicetree/bindings/fpga/fpga-bridge.txt
deleted file mode 100644
index 72e06917288a..000000000000
--- a/Documentation/devicetree/bindings/fpga/fpga-bridge.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-FPGA Bridge Device Tree Binding
-
-Optional properties:
-- bridge-enable : 0 if driver should disable bridge at startup
- 1 if driver should enable bridge at startup
- Default is to leave bridge in current state.
-
-Example:
- fpga_bridge3: fpga-bridge@ffc25080 {
- compatible = "altr,socfpga-fpga2sdram-bridge";
- reg = <0xffc25080 0x4>;
- bridge-enable = <0>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/fpga-bridge.yaml b/Documentation/devicetree/bindings/fpga/fpga-bridge.yaml
new file mode 100644
index 000000000000..1ccb2aa18726
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/fpga-bridge.yaml
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/fpga-bridge.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: FPGA Bridge
+
+maintainers:
+ - Michal Simek <michal.simek@amd.com>
+
+properties:
+ $nodename:
+ pattern: "^fpga-bridge(@.*|-([0-9]|[1-9][0-9]+))?$"
+
+ bridge-enable:
+ description: |
+ 0 if driver should disable bridge at startup
+ 1 if driver should enable bridge at startup
+ Default is to leave bridge in current state.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 0, 1 ]
+
+additionalProperties: true
+
+examples:
+ - |
+ fpga-bridge {
+ bridge-enable = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt
deleted file mode 100644
index 7d3515264838..000000000000
--- a/Documentation/devicetree/bindings/fpga/fpga-region.txt
+++ /dev/null
@@ -1,479 +0,0 @@
-FPGA Region Device Tree Binding
-
-Alan Tull 2016
-
- CONTENTS
- - Introduction
- - Terminology
- - Sequence
- - FPGA Region
- - Supported Use Models
- - Device Tree Examples
- - Constraints
-
-
-Introduction
-============
-
-FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
-the Device Tree. FPGA Regions provide a way to program FPGAs under device tree
-control.
-
-This device tree binding document hits some of the high points of FPGA usage and
-attempts to include terminology used by both major FPGA manufacturers. This
-document isn't a replacement for any manufacturers specifications for FPGA
-usage.
-
-
-Terminology
-===========
-
-Full Reconfiguration
- * The entire FPGA is programmed.
-
-Partial Reconfiguration (PR)
- * A section of an FPGA is reprogrammed while the rest of the FPGA is not
- affected.
- * Not all FPGA's support PR.
-
-Partial Reconfiguration Region (PRR)
- * Also called a "reconfigurable partition"
- * A PRR is a specific section of an FPGA reserved for reconfiguration.
- * A base (or static) FPGA image may create a set of PRR's that later may
- be independently reprogrammed many times.
- * The size and specific location of each PRR is fixed.
- * The connections at the edge of each PRR are fixed. The image that is loaded
- into a PRR must fit and must use a subset of the region's connections.
- * The busses within the FPGA are split such that each region gets its own
- branch that may be gated independently.
-
-Persona
- * Also called a "partial bit stream"
- * An FPGA image that is designed to be loaded into a PRR. There may be
- any number of personas designed to fit into a PRR, but only one at at time
- may be loaded.
- * A persona may create more regions.
-
-FPGA Bridge
- * FPGA Bridges gate bus signals between a host and FPGA.
- * FPGA Bridges should be disabled while the FPGA is being programmed to
- prevent spurious signals on the cpu bus and to the soft logic.
- * FPGA bridges may be actual hardware or soft logic on an FPGA.
- * During Full Reconfiguration, hardware bridges between the host and FPGA
- will be disabled.
- * During Partial Reconfiguration of a specific region, that region's bridge
- will be used to gate the busses. Traffic to other regions is not affected.
- * In some implementations, the FPGA Manager transparantly handles gating the
- buses, eliminating the need to show the hardware FPGA bridges in the
- device tree.
- * An FPGA image may create a set of reprogrammable regions, each having its
- own bridge and its own split of the busses in the FPGA.
-
-FPGA Manager
- * An FPGA Manager is a hardware block that programs an FPGA under the control
- of a host processor.
-
-Base Image
- * Also called the "static image"
- * An FPGA image that is designed to do full reconfiguration of the FPGA.
- * A base image may set up a set of partial reconfiguration regions that may
- later be reprogrammed.
-
- ---------------- ----------------------------------
- | Host CPU | | FPGA |
- | | | |
- | ----| | ----------- -------- |
- | | H | | |==>| Bridge0 |<==>| PRR0 | |
- | | W | | | ----------- -------- |
- | | | | | |
- | | B |<=====>|<==| ----------- -------- |
- | | R | | |==>| Bridge1 |<==>| PRR1 | |
- | | I | | | ----------- -------- |
- | | D | | | |
- | | G | | | ----------- -------- |
- | | E | | |==>| Bridge2 |<==>| PRR2 | |
- | ----| | ----------- -------- |
- | | | |
- ---------------- ----------------------------------
-
-Figure 1: An FPGA set up with a base image that created three regions. Each
-region (PRR0-2) gets its own split of the busses that is independently gated by
-a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be
-reprogrammed independently while the rest of the system continues to function.
-
-
-Sequence
-========
-
-When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
-do the following:
-
- 1. Disable appropriate FPGA bridges.
- 2. Program the FPGA using the FPGA manager.
- 3. Enable the FPGA bridges.
- 4. The Device Tree overlay is accepted into the live tree.
- 5. Child devices are populated.
-
-When the overlay is removed, the child nodes will be removed and the FPGA Region
-will disable the bridges.
-
-
-FPGA Region
-===========
-
-FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA
-Region brings together the elements needed to program on a running system and
-add the child devices:
-
- * FPGA Manager
- * FPGA Bridges
- * image-specific information needed to to the programming.
- * child nodes
-
-The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
-FPGA while an operating system is running.
-
-An FPGA Region that exists in the live Device Tree reflects the current state.
-If the live tree shows a "firmware-name" property or child nodes under an FPGA
-Region, the FPGA already has been programmed. A DTO that targets an FPGA Region
-and adds the "firmware-name" property is taken as a request to reprogram the
-FPGA. After reprogramming is successful, the overlay is accepted into the live
-tree.
-
-The base FPGA Region in the device tree represents the FPGA and supports full
-reconfiguration. It must include a phandle to an FPGA Manager. The base
-FPGA region will be the child of one of the hardware bridges (the bridge that
-allows register access) between the cpu and the FPGA. If there are more than
-one bridge to control during FPGA programming, the region will also contain a
-list of phandles to the additional hardware FPGA Bridges.
-
-For partial reconfiguration (PR), each PR region will have an FPGA Region.
-These FPGA regions are children of FPGA bridges which are then children of the
-base FPGA region. The "Full Reconfiguration to add PRR's" example below shows
-this.
-
-If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
-Manager specified by its ancestor FPGA Region. This supports both the case
-where the same FPGA Manager is used for all of an FPGA as well the case where
-a different FPGA Manager is used for each region.
-
-FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents
-shutting down bridges that are upstream from the other active regions while one
-region is getting reconfigured (see Figure 1 above). During PR, the FPGA's
-hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges
-within the static image of the FPGA.
-
-Required properties:
-- compatible : should contain "fpga-region"
-- fpga-mgr : should contain a phandle to an FPGA Manager. Child FPGA Regions
- inherit this property from their ancestor regions. An fpga-mgr property
- in a region will override any inherited FPGA manager.
-- #address-cells, #size-cells, ranges : must be present to handle address space
- mapping for child nodes.
-
-Optional properties:
-- firmware-name : should contain the name of an FPGA image file located on the
- firmware search path. If this property shows up in a live device tree
- it indicates that the FPGA has already been programmed with this image.
- If this property is in an overlay targeting an FPGA region, it is a
- request to program the FPGA with that image.
-- fpga-bridges : should contain a list of phandles to FPGA Bridges that must be
- controlled during FPGA programming along with the parent FPGA bridge.
- This property is optional if the FPGA Manager handles the bridges.
- If the fpga-region is the child of an fpga-bridge, the list should not
- contain the parent bridge.
-- partial-fpga-config : boolean, set if partial reconfiguration is to be done,
- otherwise full reconfiguration is done.
-- external-fpga-config : boolean, set if the FPGA has already been configured
- prior to OS boot up.
-- encrypted-fpga-config : boolean, set if the bitstream is encrypted
-- region-unfreeze-timeout-us : The maximum time in microseconds to wait for
- bridges to successfully become enabled after the region has been
- programmed.
-- region-freeze-timeout-us : The maximum time in microseconds to wait for
- bridges to successfully become disabled before the region has been
- programmed.
-- config-complete-timeout-us : The maximum time in microseconds time for the
- FPGA to go to operating mode after the region has been programmed.
-- child nodes : devices in the FPGA after programming.
-
-In the example below, when an overlay is applied targeting fpga-region0,
-fpga_mgr is used to program the FPGA. Two bridges are controlled during
-programming: the parent fpga_bridge0 and fpga_bridge1. Because the region is
-the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the
-fpga-bridges property. During programming, these bridges are disabled, the
-firmware specified in the overlay is loaded to the FPGA using the FPGA manager
-specified in the region. If FPGA programming succeeds, the bridges are
-reenabled and the overlay makes it into the live device tree. The child devices
-are then populated. If FPGA programming fails, the bridges are left disabled
-and the overlay is rejected. The overlay's ranges property maps the lwhps
-bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by
-the two child devices.
-
-Example:
-Base tree contains:
-
- fpga_mgr: fpga-mgr@ff706000 {
- compatible = "altr,socfpga-fpga-mgr";
- reg = <0xff706000 0x1000
- 0xffb90000 0x20>;
- interrupts = <0 175 4>;
- };
-
- fpga_bridge0: fpga-bridge@ff400000 {
- compatible = "altr,socfpga-lwhps2fpga-bridge";
- reg = <0xff400000 0x100000>;
- resets = <&rst LWHPS2FPGA_RESET>;
- clocks = <&l4_main_clk>;
-
- #address-cells = <1>;
- #size-cells = <1>;
- ranges;
-
- fpga_region0: fpga-region0 {
- compatible = "fpga-region";
- fpga-mgr = <&fpga_mgr>;
- };
- };
-
- fpga_bridge1: fpga-bridge@ff500000 {
- compatible = "altr,socfpga-hps2fpga-bridge";
- reg = <0xff500000 0x10000>;
- resets = <&rst HPS2FPGA_RESET>;
- clocks = <&l4_main_clk>;
- };
-
-Overlay contains:
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region0 {
- #address-cells = <1>;
- #size-cells = <1>;
-
- firmware-name = "soc_system.rbf";
- fpga-bridges = <&fpga_bridge1>;
- ranges = <0x20000 0xff200000 0x100000>,
- <0x0 0xc0000000 0x20000000>;
-
- gpio@10040 {
- compatible = "altr,pio-1.0";
- reg = <0x10040 0x20>;
- altr,ngpio = <4>;
- #gpio-cells = <2>;
- clocks = <2>;
- gpio-controller;
- };
-
- onchip-memory {
- device_type = "memory";
- compatible = "altr,onchipmem-15.1";
- reg = <0x0 0x10000>;
- };
-};
-
-
-Supported Use Models
-====================
-
-In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
-a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some
-uses are specific to an FPGA device.
-
- * No FPGA Bridges
- In this case, the FPGA Manager which programs the FPGA also handles the
- bridges behind the scenes. No FPGA Bridge devices are needed for full
- reconfiguration.
-
- * Full reconfiguration with hardware bridges
- In this case, there are hardware bridges between the processor and FPGA that
- need to be controlled during full reconfiguration. Before the overlay is
- applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
- FPGA Region. The FPGA Region is the child of the bridge that allows
- register access to the FPGA. Additional bridges may be listed in a
- fpga-bridges property in the FPGA region or in the device tree overlay.
-
- * Partial reconfiguration with bridges in the FPGA
- In this case, the FPGA will have one or more PRR's that may be programmed
- separately while the rest of the FPGA can remain active. To manage this,
- bridges need to exist in the FPGA that can gate the buses going to each FPGA
- region while the buses are enabled for other sections. Before any partial
- reconfiguration can be done, a base FPGA image must be loaded which includes
- PRR's with FPGA bridges. The device tree should have an FPGA region for each
- PRR.
-
-Device Tree Examples
-====================
-
-The intention of this section is to give some simple examples, focusing on
-the placement of the elements detailed above, especially:
- * FPGA Manager
- * FPGA Bridges
- * FPGA Region
- * ranges
- * target-path or target
-
-For the purposes of this section, I'm dividing the Device Tree into two parts,
-each with its own requirements. The two parts are:
- * The live DT prior to the overlay being added
- * The DT overlay
-
-The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA
-Bridges. The FPGA Region's "fpga-mgr" property specifies the manager by phandle
-to handle programming the FPGA. If the FPGA Region is the child of another FPGA
-Region, the parent's FPGA Manager is used. If FPGA Bridges need to be involved,
-they are specified in the FPGA Region by the "fpga-bridges" property. During
-FPGA programming, the FPGA Region will disable the bridges that are in its
-"fpga-bridges" list and will re-enable them after FPGA programming has
-succeeded.
-
-The Device Tree Overlay will contain:
- * "target-path" or "target"
- The insertion point where the the contents of the overlay will go into the
- live tree. target-path is a full path, while target is a phandle.
- * "ranges"
- The address space mapping from processor to FPGA bus(ses).
- * "firmware-name"
- Specifies the name of the FPGA image file on the firmware search
- path. The search path is described in the firmware class documentation.
- * "partial-fpga-config"
- This binding is a boolean and should be present if partial reconfiguration
- is to be done.
- * child nodes corresponding to hardware that will be loaded in this region of
- the FPGA.
-
-Device Tree Example: Full Reconfiguration without Bridges
-=========================================================
-
-Live Device Tree contains:
- fpga_mgr0: fpga-mgr@f8007000 {
- compatible = "xlnx,zynq-devcfg-1.0";
- reg = <0xf8007000 0x100>;
- interrupt-parent = <&intc>;
- interrupts = <0 8 4>;
- clocks = <&clkc 12>;
- clock-names = "ref_clk";
- syscon = <&slcr>;
- };
-
- fpga_region0: fpga-region0 {
- compatible = "fpga-region";
- fpga-mgr = <&fpga_mgr0>;
- #address-cells = <0x1>;
- #size-cells = <0x1>;
- ranges;
- };
-
-DT Overlay contains:
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region0 {
- #address-cells = <1>;
- #size-cells = <1>;
-
- firmware-name = "zynq-gpio.bin";
-
- gpio1: gpio@40000000 {
- compatible = "xlnx,xps-gpio-1.00.a";
- reg = <0x40000000 0x10000>;
- gpio-controller;
- #gpio-cells = <0x2>;
- xlnx,gpio-width= <0x6>;
- };
-};
-
-Device Tree Example: Full Reconfiguration to add PRR's
-======================================================
-
-The base FPGA Region is specified similar to the first example above.
-
-This example programs the FPGA to have two regions that can later be partially
-configured. Each region has its own bridge in the FPGA fabric.
-
-DT Overlay contains:
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region0 {
- #address-cells = <1>;
- #size-cells = <1>;
-
- firmware-name = "base.rbf";
-
- fpga-bridge@4400 {
- compatible = "altr,freeze-bridge-controller";
- reg = <0x4400 0x10>;
-
- fpga_region1: fpga-region1 {
- compatible = "fpga-region";
- #address-cells = <0x1>;
- #size-cells = <0x1>;
- ranges;
- };
- };
-
- fpga-bridge@4420 {
- compatible = "altr,freeze-bridge-controller";
- reg = <0x4420 0x10>;
-
- fpga_region2: fpga-region2 {
- compatible = "fpga-region";
- #address-cells = <0x1>;
- #size-cells = <0x1>;
- ranges;
- };
- };
-};
-
-Device Tree Example: Partial Reconfiguration
-============================================
-
-This example reprograms one of the PRR's set up in the previous example.
-
-The sequence that occurs when this overlay is similar to the above, the only
-differences are that the FPGA is partially reconfigured due to the
-"partial-fpga-config" boolean and the only bridge that is controlled during
-programming is the FPGA based bridge of fpga_region1.
-
-/dts-v1/;
-/plugin/;
-
-&fpga_region1 {
- #address-cells = <1>;
- #size-cells = <1>;
-
- firmware-name = "soc_image2.rbf";
- partial-fpga-config;
-
- gpio@10040 {
- compatible = "altr,pio-1.0";
- reg = <0x10040 0x20>;
- clocks = <0x2>;
- altr,ngpio = <0x4>;
- #gpio-cells = <0x2>;
- gpio-controller;
- };
-};
-
-Constraints
-===========
-
-It is beyond the scope of this document to fully describe all the FPGA design
-constraints required to make partial reconfiguration work[1] [2] [3], but a few
-deserve quick mention.
-
-A persona must have boundary connections that line up with those of the partion
-or region it is designed to go into.
-
-During programming, transactions through those connections must be stopped and
-the connections must be held at a fixed logic level. This can be achieved by
-FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
-
---
-[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf
-[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
-[3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf
diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.yaml b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
new file mode 100644
index 000000000000..55acf0ecfa3f
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/fpga-region.yaml
@@ -0,0 +1,354 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/fpga-region.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: FPGA Region
+
+maintainers:
+ - Michal Simek <michal.simek@amd.com>
+
+description: |
+ CONTENTS
+ - Introduction
+ - Terminology
+ - Sequence
+ - FPGA Region
+ - Supported Use Models
+ - Constraints
+
+ Introduction
+ ============
+
+ FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in
+ the Device Tree. FPGA Regions provide a way to program FPGAs under device tree
+ control.
+
+ The documentation hits some of the high points of FPGA usage and
+ attempts to include terminology used by both major FPGA manufacturers. This
+ document isn't a replacement for any manufacturers specifications for FPGA
+ usage.
+
+ Terminology
+ ===========
+
+ Full Reconfiguration
+ * The entire FPGA is programmed.
+
+ Partial Reconfiguration (PR)
+ * A section of an FPGA is reprogrammed while the rest of the FPGA is not
+ affected.
+ * Not all FPGA's support PR.
+
+ Partial Reconfiguration Region (PRR)
+ * Also called a "reconfigurable partition"
+ * A PRR is a specific section of an FPGA reserved for reconfiguration.
+ * A base (or static) FPGA image may create a set of PRR's that later may
+ be independently reprogrammed many times.
+ * The size and specific location of each PRR is fixed.
+ * The connections at the edge of each PRR are fixed. The image that is loaded
+ into a PRR must fit and must use a subset of the region's connections.
+ * The busses within the FPGA are split such that each region gets its own
+ branch that may be gated independently.
+
+ Persona
+ * Also called a "partial bit stream"
+ * An FPGA image that is designed to be loaded into a PRR. There may be
+ any number of personas designed to fit into a PRR, but only one at a time
+ may be loaded.
+ * A persona may create more regions.
+
+ FPGA Bridge
+ * FPGA Bridges gate bus signals between a host and FPGA.
+ * FPGA Bridges should be disabled while the FPGA is being programmed to
+ prevent spurious signals on the cpu bus and to the soft logic.
+ * FPGA bridges may be actual hardware or soft logic on an FPGA.
+ * During Full Reconfiguration, hardware bridges between the host and FPGA
+ will be disabled.
+ * During Partial Reconfiguration of a specific region, that region's bridge
+ will be used to gate the busses. Traffic to other regions is not affected.
+ * In some implementations, the FPGA Manager transparently handles gating the
+ buses, eliminating the need to show the hardware FPGA bridges in the
+ device tree.
+ * An FPGA image may create a set of reprogrammable regions, each having its
+ own bridge and its own split of the busses in the FPGA.
+
+ FPGA Manager
+ * An FPGA Manager is a hardware block that programs an FPGA under the control
+ of a host processor.
+
+ Base Image
+ * Also called the "static image"
+ * An FPGA image that is designed to do full reconfiguration of the FPGA.
+ * A base image may set up a set of partial reconfiguration regions that may
+ later be reprogrammed.
+
+ ---------------- ----------------------------------
+ | Host CPU | | FPGA |
+ | | | |
+ | ----| | ----------- -------- |
+ | | H | | |==>| Bridge0 |<==>| PRR0 | |
+ | | W | | | ----------- -------- |
+ | | | | | |
+ | | B |<=====>|<==| ----------- -------- |
+ | | R | | |==>| Bridge1 |<==>| PRR1 | |
+ | | I | | | ----------- -------- |
+ | | D | | | |
+ | | G | | | ----------- -------- |
+ | | E | | |==>| Bridge2 |<==>| PRR2 | |
+ | ----| | ----------- -------- |
+ | | | |
+ ---------------- ----------------------------------
+
+ Figure 1: An FPGA set up with a base image that created three regions. Each
+ region (PRR0-2) gets its own split of the busses that is independently gated by
+ a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be
+ reprogrammed independently while the rest of the system continues to function.
+
+ Sequence
+ ========
+
+ When a DT overlay that targets an FPGA Region is applied, the FPGA Region will
+ do the following:
+
+ 1. Disable appropriate FPGA bridges.
+ 2. Program the FPGA using the FPGA manager.
+ 3. Enable the FPGA bridges.
+ 4. The Device Tree overlay is accepted into the live tree.
+ 5. Child devices are populated.
+
+ When the overlay is removed, the child nodes will be removed and the FPGA Region
+ will disable the bridges.
+
+ FPGA Region
+ ===========
+
+ FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA
+ Region brings together the elements needed to program on a running system and
+ add the child devices:
+
+ * FPGA Manager
+ * FPGA Bridges
+ * image-specific information needed to the programming.
+ * child nodes
+
+ The intended use is that a Device Tree overlay (DTO) can be used to reprogram an
+ FPGA while an operating system is running.
+
+ An FPGA Region that exists in the live Device Tree reflects the current state.
+ If the live tree shows a "firmware-name" property or child nodes under an FPGA
+ Region, the FPGA already has been programmed. A DTO that targets an FPGA Region
+ and adds the "firmware-name" property is taken as a request to reprogram the
+ FPGA. After reprogramming is successful, the overlay is accepted into the live
+ tree.
+
+ The base FPGA Region in the device tree represents the FPGA and supports full
+ reconfiguration. It must include a phandle to an FPGA Manager. The base
+ FPGA region will be the child of one of the hardware bridges (the bridge that
+ allows register access) between the cpu and the FPGA. If there are more than
+ one bridge to control during FPGA programming, the region will also contain a
+ list of phandles to the additional hardware FPGA Bridges.
+
+ For partial reconfiguration (PR), each PR region will have an FPGA Region.
+ These FPGA regions are children of FPGA bridges which are then children of the
+ base FPGA region. The "Full Reconfiguration to add PRR's" example below shows
+ this.
+
+ If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA
+ Manager specified by its ancestor FPGA Region. This supports both the case
+ where the same FPGA Manager is used for all of an FPGA as well the case where
+ a different FPGA Manager is used for each region.
+
+ FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents
+ shutting down bridges that are upstream from the other active regions while one
+ region is getting reconfigured (see Figure 1 above). During PR, the FPGA's
+ hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges
+ within the static image of the FPGA.
+
+ Supported Use Models
+ ====================
+
+ In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and
+ a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some
+ uses are specific to an FPGA device.
+
+ * No FPGA Bridges
+ In this case, the FPGA Manager which programs the FPGA also handles the
+ bridges behind the scenes. No FPGA Bridge devices are needed for full
+ reconfiguration.
+
+ * Full reconfiguration with hardware bridges
+ In this case, there are hardware bridges between the processor and FPGA that
+ need to be controlled during full reconfiguration. Before the overlay is
+ applied, the live DT must include the FPGA Manager, FPGA Bridges, and a
+ FPGA Region. The FPGA Region is the child of the bridge that allows
+ register access to the FPGA. Additional bridges may be listed in a
+ fpga-bridges property in the FPGA region or in the device tree overlay.
+
+ * Partial reconfiguration with bridges in the FPGA
+ In this case, the FPGA will have one or more PRR's that may be programmed
+ separately while the rest of the FPGA can remain active. To manage this,
+ bridges need to exist in the FPGA that can gate the buses going to each FPGA
+ region while the buses are enabled for other sections. Before any partial
+ reconfiguration can be done, a base FPGA image must be loaded which includes
+ PRR's with FPGA bridges. The device tree should have an FPGA region for each
+ PRR.
+
+ Constraints
+ ===========
+
+ It is beyond the scope of this document to fully describe all the FPGA design
+ constraints required to make partial reconfiguration work[1] [2] [3], but a few
+ deserve quick mention.
+
+ A persona must have boundary connections that line up with those of the partition
+ or region it is designed to go into.
+
+ During programming, transactions through those connections must be stopped and
+ the connections must be held at a fixed logic level. This can be achieved by
+ FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration.
+
+ --
+ [1] https://www.intel.com/programmable/technical-pdfs/683404.pdf
+ [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf
+ [3] https://docs.amd.com/v/u/en-US/ug702
+
+properties:
+ $nodename:
+ pattern: "^fpga-region(@.*|-([0-9]|[1-9][0-9]+))?$"
+
+ compatible:
+ const: fpga-region
+
+ reg:
+ maxItems: 1
+
+ ranges: true
+ "#address-cells": true
+ "#size-cells": true
+
+ config-complete-timeout-us:
+ description:
+ The maximum time in microseconds time for the FPGA to go to operating
+ mode after the region has been programmed.
+
+ encrypted-fpga-config:
+ type: boolean
+ description:
+ Set if the bitstream is encrypted.
+
+ external-fpga-config:
+ type: boolean
+ description:
+ Set if the FPGA has already been configured prior to OS boot up.
+
+ firmware-name:
+ maxItems: 1
+ description:
+ Should contain the name of an FPGA image file located on the firmware
+ search path. If this property shows up in a live device tree it indicates
+ that the FPGA has already been programmed with this image.
+ If this property is in an overlay targeting an FPGA region, it is
+ a request to program the FPGA with that image.
+
+ fpga-bridges:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ description:
+ Should contain a list of phandles to FPGA Bridges that must be
+ controlled during FPGA programming along with the parent FPGA bridge.
+ This property is optional if the FPGA Manager handles the bridges.
+ If the fpga-region is the child of an fpga-bridge, the list should not
+ contain the parent bridge.
+
+ fpga-mgr:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Should contain a phandle to an FPGA Manager. Child FPGA Regions
+ inherit this property from their ancestor regions. An fpga-mgr property
+ in a region will override any inherited FPGA manager.
+
+ partial-fpga-config:
+ type: boolean
+ description:
+ Set if partial reconfiguration is to be done, otherwise full
+ reconfiguration is done.
+
+ region-freeze-timeout-us:
+ description:
+ The maximum time in microseconds to wait for bridges to successfully
+ become disabled before the region has been programmed.
+
+ region-unfreeze-timeout-us:
+ description:
+ The maximum time in microseconds to wait for bridges to successfully
+ become enabled after the region has been programmed.
+
+required:
+ - compatible
+ - fpga-mgr
+
+additionalProperties:
+ type: object
+
+examples:
+ - |
+ /*
+ * Full Reconfiguration without Bridges with DT overlay
+ */
+ fpga_region0: fpga-region@0 {
+ compatible = "fpga-region";
+ reg = <0 0>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ fpga-mgr = <&fpga_mgr0>;
+ ranges = <0x10000000 0x20000000 0x10000000>;
+
+ /* DT Overlay contains: &fpga_region0 */
+ firmware-name = "zynq-gpio.bin";
+ gpio@40000000 {
+ compatible = "xlnx,xps-gpio-1.00.a";
+ reg = <0x40000000 0x10000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ clocks = <&clk>;
+ };
+ };
+
+ - |
+ /*
+ * Partial reconfiguration with bridge
+ */
+ fpga_region1: fpga-region@0 {
+ compatible = "fpga-region";
+ reg = <0 0>;
+ ranges;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ fpga-mgr = <&fpga_mgr1>;
+ fpga-bridges = <&fpga_bridge1>;
+ partial-fpga-config;
+
+ /* DT Overlay contains: &fpga_region1 */
+ firmware-name = "zynq-gpio-partial.bin";
+ clk: clock {
+ compatible = "fixed-factor-clock";
+ clocks = <&parentclk>;
+ #clock-cells = <0>;
+ clock-div = <2>;
+ clock-mult = <1>;
+ };
+ axi {
+ compatible = "simple-bus";
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+ gpio@40000000 {
+ compatible = "xlnx,xps-gpio-1.00.a";
+ reg = <0x40000000 0x10000>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ clocks = <&clk>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fpga/intel,stratix10-soc-fpga-mgr.yaml b/Documentation/devicetree/bindings/fpga/intel,stratix10-soc-fpga-mgr.yaml
new file mode 100644
index 000000000000..6e536d6b28a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/intel,stratix10-soc-fpga-mgr.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/intel,stratix10-soc-fpga-mgr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intel Stratix10 SoC FPGA Manager
+
+maintainers:
+ - Mahesh Rao <mahesh.rao@altera.com>
+ - Adrian Ng Ho Yin <adrian.ho.yin.ng@altera.com>
+ - Niravkumar L Rabara <nirav.rabara@altera.com>
+
+description:
+ The Intel Stratix10 SoC consists of a 64-bit quad-core ARM Cortex A53 hard
+ processor system (HPS) and a Secure Device Manager (SDM). The Stratix10
+ SoC FPGA Manager driver is used to configure/reconfigure the FPGA fabric
+ on the die.The driver communicates with SDM/ATF via the stratix10-svc
+ platform driver for performing its operations.
+
+properties:
+ compatible:
+ enum:
+ - intel,stratix10-soc-fpga-mgr
+ - intel,agilex-soc-fpga-mgr
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ fpga-mgr {
+ compatible = "intel,stratix10-soc-fpga-mgr";
+ };
diff --git a/Documentation/devicetree/bindings/fpga/intel-stratix10-soc-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/intel-stratix10-soc-fpga-mgr.txt
deleted file mode 100644
index 0f874137ca46..000000000000
--- a/Documentation/devicetree/bindings/fpga/intel-stratix10-soc-fpga-mgr.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-Intel Stratix10 SoC FPGA Manager
-
-Required properties:
-The fpga_mgr node has the following mandatory property, must be located under
-firmware/svc node.
-
-- compatible : should contain "intel,stratix10-soc-fpga-mgr" or
- "intel,agilex-soc-fpga-mgr"
-
-Example:
-
- firmware {
- svc {
- fpga_mgr: fpga-mgr {
- compatible = "intel,stratix10-soc-fpga-mgr";
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/fpga/lattice,ice40-fpga-mgr.yaml b/Documentation/devicetree/bindings/fpga/lattice,ice40-fpga-mgr.yaml
new file mode 100644
index 000000000000..5121c6120785
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/lattice,ice40-fpga-mgr.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/lattice,ice40-fpga-mgr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lattice iCE40 FPGA Manager
+
+maintainers:
+ - Joel Holdsworth <joel@airwebreathe.org.uk>
+
+properties:
+ compatible:
+ const: lattice,ice40-fpga-mgr
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ minimum: 1000000
+ maximum: 25000000
+
+ cdone-gpios:
+ maxItems: 1
+ description: GPIO input connected to CDONE pin
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ Active-low GPIO output connected to CRESET_B pin. Note that unless the
+ GPIO is held low during startup, the FPGA will enter Master SPI mode and
+ drive SCK with a clock signal potentially jamming other devices on the bus
+ until the firmware is loaded.
+
+required:
+ - compatible
+ - reg
+ - spi-max-frequency
+ - cdone-gpios
+ - reset-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fpga@0 {
+ compatible = "lattice,ice40-fpga-mgr";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ cdone-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio 22 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fpga/lattice,sysconfig.yaml b/Documentation/devicetree/bindings/fpga/lattice,sysconfig.yaml
new file mode 100644
index 000000000000..164331eb6275
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/lattice,sysconfig.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/lattice,sysconfig.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lattice Slave SPI sysCONFIG FPGA manager
+
+maintainers:
+ - Vladimir Georgiev <v.georgiev@metrotek.ru>
+
+description: |
+ Lattice sysCONFIG port, which is used for FPGA configuration, among others,
+ have Slave Serial Peripheral Interface. Only full reconfiguration is
+ supported.
+
+ Programming of ECP5 is done by writing uncompressed bitstream image in .bit
+ format into FPGA's SRAM configuration memory.
+
+properties:
+ compatible:
+ enum:
+ - lattice,sysconfig-ecp5
+
+ reg:
+ maxItems: 1
+
+ program-gpios:
+ description:
+ A GPIO line connected to PROGRAMN (active low) pin of the device.
+ Initiates configuration sequence.
+ maxItems: 1
+
+ init-gpios:
+ description:
+ A GPIO line connected to INITN (active low) pin of the device.
+ Indicates that the FPGA is ready to be configured.
+ maxItems: 1
+
+ done-gpios:
+ description:
+ A GPIO line connected to DONE (active high) pin of the device.
+ Indicates that the configuration sequence is complete.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: lattice,sysconfig-ecp5
+ then:
+ properties:
+ spi-max-frequency:
+ maximum: 60000000
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fpga-mgr@0 {
+ compatible = "lattice,sysconfig-ecp5";
+ reg = <0>;
+ spi-max-frequency = <20000000>;
+ program-gpios = <&gpio3 4 GPIO_ACTIVE_LOW>;
+ init-gpios = <&gpio3 3 GPIO_ACTIVE_LOW>;
+ done-gpios = <&gpio3 2 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt
deleted file mode 100644
index 4dc412437b08..000000000000
--- a/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Lattice iCE40 FPGA Manager
-
-Required properties:
-- compatible: Should contain "lattice,ice40-fpga-mgr"
-- reg: SPI chip select
-- spi-max-frequency: Maximum SPI frequency (>=1000000, <=25000000)
-- cdone-gpios: GPIO input connected to CDONE pin
-- reset-gpios: Active-low GPIO output connected to CRESET_B pin. Note
- that unless the GPIO is held low during startup, the
- FPGA will enter Master SPI mode and drive SCK with a
- clock signal potentially jamming other devices on the
- bus until the firmware is loaded.
-
-Example:
- fpga: fpga@0 {
- compatible = "lattice,ice40-fpga-mgr";
- reg = <0>;
- spi-max-frequency = <1000000>;
- cdone-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>;
- reset-gpios = <&gpio 22 GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/microchip,mpf-spi-fpga-mgr.yaml b/Documentation/devicetree/bindings/fpga/microchip,mpf-spi-fpga-mgr.yaml
new file mode 100644
index 000000000000..a157eecfb5fc
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/microchip,mpf-spi-fpga-mgr.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/microchip,mpf-spi-fpga-mgr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip Polarfire FPGA manager.
+
+maintainers:
+ - Vladimir Georgiev <v.georgiev@metrotek.ru>
+
+description:
+ Device Tree Bindings for Microchip Polarfire FPGA Manager using slave SPI to
+ load the bitstream in .dat format.
+
+properties:
+ compatible:
+ enum:
+ - microchip,mpf-spi-fpga-mgr
+
+ reg:
+ description: SPI chip select
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fpga_mgr@0 {
+ compatible = "microchip,mpf-spi-fpga-mgr";
+ spi-max-frequency = <20000000>;
+ reg = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
deleted file mode 100644
index 0acdfa6d62a4..000000000000
--- a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt
+++ /dev/null
@@ -1,54 +0,0 @@
-Xilinx LogiCORE Partial Reconfig Decoupler Softcore
-
-The Xilinx LogiCORE Partial Reconfig Decoupler manages one or more
-decouplers / fpga bridges.
-The controller can decouple/disable the bridges which prevents signal
-changes from passing through the bridge. The controller can also
-couple / enable the bridges which allows traffic to pass through the
-bridge normally.
-
-Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager
-Softcore is compatible with the Xilinx LogiCORE pr-decoupler.
-
-The Dynamic Function eXchange AXI shutdown manager prevents AXI traffic
-from passing through the bridge. The controller safely handles AXI4MM
-and AXI4-Lite interfaces on a Reconfigurable Partition when it is
-undergoing dynamic reconfiguration, preventing the system deadlock
-that can occur if AXI transactions are interrupted by DFX
-
-The Driver supports only MMIO handling. A PR region can have multiple
-PR Decouplers which can be handled independently or chained via decouple/
-decouple_status signals.
-
-Required properties:
-- compatible : Should contain "xlnx,pr-decoupler-1.00" followed by
- "xlnx,pr-decoupler" or
- "xlnx,dfx-axi-shutdown-manager-1.00" followed by
- "xlnx,dfx-axi-shutdown-manager"
-- regs : base address and size for decoupler module
-- clocks : input clock to IP
-- clock-names : should contain "aclk"
-
-See Documentation/devicetree/bindings/fpga/fpga-region.txt and
-Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings.
-
-Example:
-Partial Reconfig Decoupler:
- fpga-bridge@100000450 {
- compatible = "xlnx,pr-decoupler-1.00",
- "xlnx-pr-decoupler";
- regs = <0x10000045 0x10>;
- clocks = <&clkc 15>;
- clock-names = "aclk";
- bridge-enable = <0>;
- };
-
-Dynamic Function eXchange AXI shutdown manager:
- fpga-bridge@100000450 {
- compatible = "xlnx,dfx-axi-shutdown-manager-1.00",
- "xlnx,dfx-axi-shutdown-manager";
- regs = <0x10000045 0x10>;
- clocks = <&clkc 15>;
- clock-names = "aclk";
- bridge-enable = <0>;
- };
diff --git a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
deleted file mode 100644
index 5ef659c1394d..000000000000
--- a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-Xilinx Slave Serial SPI FPGA Manager
-
-Xilinx Spartan-6 and 7 Series FPGAs support a method of loading the
-bitstream over what is referred to as "slave serial" interface.
-The slave serial link is not technically SPI, and might require extra
-circuits in order to play nicely with other SPI slaves on the same bus.
-
-See:
-- https://www.xilinx.com/support/documentation/user_guides/ug380.pdf
-- https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf
-- https://www.xilinx.com/support/documentation/application_notes/xapp583-fpga-configuration.pdf
-
-Required properties:
-- compatible: should contain "xlnx,fpga-slave-serial"
-- reg: spi chip select of the FPGA
-- prog_b-gpios: config pin (referred to as PROGRAM_B in the manual)
-- done-gpios: config status pin (referred to as DONE in the manual)
-
-Optional properties:
-- init-b-gpios: initialization status and configuration error pin
- (referred to as INIT_B in the manual)
-
-Example for full FPGA configuration:
-
- fpga-region0 {
- compatible = "fpga-region";
- fpga-mgr = <&fpga_mgr_spi>;
- #address-cells = <0x1>;
- #size-cells = <0x1>;
- };
-
- spi1: spi@10680 {
- compatible = "marvell,armada-xp-spi", "marvell,orion-spi";
- pinctrl-0 = <&spi0_pins>;
- pinctrl-names = "default";
- #address-cells = <1>;
- #size-cells = <0>;
- cell-index = <1>;
- interrupts = <92>;
- clocks = <&coreclk 0>;
-
- fpga_mgr_spi: fpga-mgr@0 {
- compatible = "xlnx,fpga-slave-serial";
- spi-max-frequency = <60000000>;
- spi-cpha;
- reg = <0>;
- prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>;
- init-b-gpios = <&gpio0 28 GPIO_ACTIVE_LOW>;
- done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>;
- };
- };
diff --git a/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.yaml b/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.yaml
index 29daca4be47f..04dcadc2c20e 100644
--- a/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.yaml
+++ b/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/fpga/xilinx-zynq-fpga-mgr.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Xilinx Zynq FPGA Manager Device Tree Bindings
+title: Xilinx Zynq FPGA Manager
maintainers:
- - Michal Simek <michal.simek@xilinx.com>
+ - Michal Simek <michal.simek@amd.com>
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/fpga/xlnx,fpga-selectmap.yaml b/Documentation/devicetree/bindings/fpga/xlnx,fpga-selectmap.yaml
new file mode 100644
index 000000000000..05775746fd70
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/xlnx,fpga-selectmap.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/xlnx,fpga-selectmap.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx SelectMAP FPGA interface
+
+maintainers:
+ - Charles Perry <charles.perry@savoirfairelinux.com>
+
+description: |
+ Xilinx 7 Series FPGAs support a method of loading the bitstream over a
+ parallel port named the SelectMAP interface in the documentation. Only
+ the x8 mode is supported where data is loaded at one byte per rising edge of
+ the clock, with the MSB of each byte presented to the D0 pin.
+
+ Datasheets:
+ https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf
+
+allOf:
+ - $ref: /schemas/memory-controllers/mc-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - xlnx,fpga-xc7s-selectmap
+ - xlnx,fpga-xc7a-selectmap
+ - xlnx,fpga-xc7k-selectmap
+ - xlnx,fpga-xc7v-selectmap
+
+ reg:
+ description:
+ At least 1 byte of memory mapped IO
+ maxItems: 1
+
+ prog-gpios:
+ description:
+ config pin (referred to as PROGRAM_B in the manual)
+ maxItems: 1
+
+ done-gpios:
+ description:
+ config status pin (referred to as DONE in the manual)
+ maxItems: 1
+
+ init-gpios:
+ description:
+ initialization status and configuration error pin
+ (referred to as INIT_B in the manual)
+ maxItems: 1
+
+ csi-gpios:
+ description:
+ chip select pin (referred to as CSI_B in the manual)
+ Optional gpio for if the bus controller does not provide a chip select.
+ maxItems: 1
+
+ rdwr-gpios:
+ description:
+ read/write select pin (referred to as RDWR_B in the manual)
+ Optional gpio for if the bus controller does not provide this pin.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - prog-gpios
+ - done-gpios
+ - init-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ fpga-mgr@8000000 {
+ compatible = "xlnx,fpga-xc7s-selectmap";
+ reg = <0x8000000 0x4>;
+ prog-gpios = <&gpio5 5 GPIO_ACTIVE_LOW>;
+ init-gpios = <&gpio5 8 GPIO_ACTIVE_LOW>;
+ done-gpios = <&gpio2 30 GPIO_ACTIVE_HIGH>;
+ csi-gpios = <&gpio3 19 GPIO_ACTIVE_LOW>;
+ rdwr-gpios = <&gpio3 10 GPIO_ACTIVE_LOW>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/fpga/xlnx,fpga-slave-serial.yaml b/Documentation/devicetree/bindings/fpga/xlnx,fpga-slave-serial.yaml
new file mode 100644
index 000000000000..614d86ad825f
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/xlnx,fpga-slave-serial.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/xlnx,fpga-slave-serial.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx Slave Serial SPI FPGA
+
+maintainers:
+ - Nava kishore Manne <nava.kishore.manne@amd.com>
+
+description: |
+ Xilinx Spartan-6 and 7 Series FPGAs support a method of loading the bitstream
+ over what is referred to as slave serial interface.The slave serial link is
+ not technically SPI, and might require extra circuits in order to play nicely
+ with other SPI slaves on the same bus.
+
+ Datasheets:
+ https://www.xilinx.com/support/documentation/user_guides/ug380.pdf
+ https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf
+ https://www.xilinx.com/support/documentation/application_notes/xapp583-fpga-configuration.pdf
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - xlnx,fpga-slave-serial
+
+ spi-cpha: true
+
+ spi-max-frequency:
+ maximum: 60000000
+
+ reg:
+ maxItems: 1
+
+ prog_b-gpios:
+ description:
+ config pin (referred to as PROGRAM_B in the manual)
+ maxItems: 1
+
+ done-gpios:
+ description:
+ config status pin (referred to as DONE in the manual)
+ maxItems: 1
+
+ init-b-gpios:
+ description:
+ initialization status and configuration error pin
+ (referred to as INIT_B in the manual)
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - prog_b-gpios
+ - done-gpios
+ - init-b-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ fpga_mgr_spi: fpga-mgr@0 {
+ compatible = "xlnx,fpga-slave-serial";
+ spi-max-frequency = <60000000>;
+ spi-cpha;
+ reg = <0>;
+ prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>;
+ init-b-gpios = <&gpio0 28 GPIO_ACTIVE_LOW>;
+ done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml b/Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml
new file mode 100644
index 000000000000..5bf731f9d99a
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/xlnx,pr-decoupler.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/xlnx,pr-decoupler.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx LogiCORE Partial Reconfig Decoupler/AXI shutdown manager Softcore
+
+maintainers:
+ - Nava kishore Manne <nava.kishore.manne@amd.com>
+
+allOf:
+ - $ref: fpga-bridge.yaml#
+
+description: |
+ The Xilinx LogiCORE Partial Reconfig(PR) Decoupler manages one or more
+ decouplers/fpga bridges. The controller can decouple/disable the bridges
+ which prevents signal changes from passing through the bridge. The controller
+ can also couple / enable the bridges which allows traffic to pass through the
+ bridge normally.
+ Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager Softcore
+ is compatible with the Xilinx LogiCORE pr-decoupler. The Dynamic Function
+ eXchange AXI shutdown manager prevents AXI traffic from passing through the
+ bridge. The controller safely handles AXI4MM and AXI4-Lite interfaces on a
+ Reconfigurable Partition when it is undergoing dynamic reconfiguration,
+ preventing the system deadlock that can occur if AXI transactions are
+ interrupted by DFX.
+ Please refer to fpga-region.txt and fpga-bridge.txt in this directory for
+ common binding part and usage.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: xlnx,pr-decoupler-1.00
+ - const: xlnx,pr-decoupler
+ - items:
+ - const: xlnx,dfx-axi-shutdown-manager-1.00
+ - const: xlnx,dfx-axi-shutdown-manager
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: aclk
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ fpga-bridge@100000450 {
+ compatible = "xlnx,pr-decoupler-1.00", "xlnx,pr-decoupler";
+ reg = <0x10000045 0x10>;
+ clocks = <&clkc 15>;
+ clock-names = "aclk";
+ };
+...
diff --git a/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml b/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml
new file mode 100644
index 000000000000..41b368d54557
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/xlnx,versal-fpga.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx Versal FPGA driver.
+
+maintainers:
+ - Nava kishore Manne <nava.kishore.manne@amd.com>
+
+description: |
+ Device Tree Versal FPGA bindings for the Versal SoC, controlled
+ using firmware interface.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - xlnx,versal-fpga
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ versal_fpga: versal-fpga {
+ compatible = "xlnx,versal-fpga";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt b/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt
deleted file mode 100644
index 3052bf619dd5..000000000000
--- a/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-Devicetree bindings for Zynq Ultrascale MPSoC FPGA Manager.
-The ZynqMP SoC uses the PCAP (Processor configuration Port) to configure the
-Programmable Logic (PL). The configuration uses the firmware interface.
-
-Required properties:
-- compatible: should contain "xlnx,zynqmp-pcap-fpga"
-
-Example for full FPGA configuration:
-
- fpga-region0 {
- compatible = "fpga-region";
- fpga-mgr = <&zynqmp_pcap>;
- #address-cells = <0x1>;
- #size-cells = <0x1>;
- };
-
- firmware {
- zynqmp_firmware: zynqmp-firmware {
- compatible = "xlnx,zynqmp-firmware";
- method = "smc";
- zynqmp_pcap: pcap {
- compatible = "xlnx,zynqmp-pcap-fpga";
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml b/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml
new file mode 100644
index 000000000000..1390ae103b0b
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/xlnx,zynqmp-pcap-fpga.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fpga/xlnx,zynqmp-pcap-fpga.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx Zynq Ultrascale MPSoC FPGA Manager
+
+maintainers:
+ - Nava kishore Manne <nava.kishore.manne@amd.com>
+
+description: |
+ Device Tree Bindings for Zynq Ultrascale MPSoC FPGA Manager.
+ The ZynqMP SoC uses the PCAP (Processor Configuration Port) to
+ configure the Programmable Logic (PL). The configuration uses the
+ firmware interface.
+
+properties:
+ compatible:
+ const: xlnx,zynqmp-pcap-fpga
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ firmware {
+ zynqmp_firmware: zynqmp-firmware {
+ zynqmp_pcap: pcap {
+ compatible = "xlnx,zynqmp-pcap-fpga";
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/fsi/aspeed,ast2400-cf-fsi-master.yaml b/Documentation/devicetree/bindings/fsi/aspeed,ast2400-cf-fsi-master.yaml
new file mode 100644
index 000000000000..690b6c936f18
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/aspeed,ast2400-cf-fsi-master.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/aspeed,ast2400-cf-fsi-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASpeed ColdFire offloaded GPIO-based FSI master
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+allOf:
+ - $ref: /schemas/fsi/fsi-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-cf-fsi-master
+ - aspeed,ast2500-cf-fsi-master
+
+ clock-gpios:
+ maxItems: 1
+ description: GPIO for FSI clock
+
+ data-gpios:
+ maxItems: 1
+ description: GPIO for FSI data signal
+
+ enable-gpios:
+ maxItems: 1
+ description: GPIO for enable signal
+
+ trans-gpios:
+ maxItems: 1
+ description: GPIO for voltage translator enable
+
+ mux-gpios:
+ maxItems: 1
+ description:
+ GPIO for pin multiplexing with other functions (eg, external FSI masters)
+
+ memory-region:
+ maxItems: 1
+ description:
+ Reference to the reserved memory for the ColdFire. Must be 2M aligned on
+ AST2400 and 1M aligned on AST2500.
+
+ aspeed,cvic:
+ description: Reference to the CVIC node.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ aspeed,sram:
+ description: Reference to the SRAM node.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+required:
+ - compatible
+ - clock-gpios
+ - data-gpios
+ - enable-gpios
+ - trans-gpios
+ - mux-gpios
+ - memory-region
+ - aspeed,cvic
+ - aspeed,sram
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ fsi-master {
+ compatible = "aspeed,ast2500-cf-fsi-master";
+ clock-gpios = <&gpio 0>;
+ data-gpios = <&gpio 1>;
+ enable-gpios = <&gpio 2>;
+ trans-gpios = <&gpio 3>;
+ mux-gpios = <&gpio 4>;
+ memory-region = <&coldfire_memory>;
+ aspeed,cvic = <&cvic>;
+ aspeed,sram = <&sram>;
+ };
diff --git a/Documentation/devicetree/bindings/fsi/aspeed,ast2600-fsi-master.yaml b/Documentation/devicetree/bindings/fsi/aspeed,ast2600-fsi-master.yaml
new file mode 100644
index 000000000000..dfcc2fafa68d
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/aspeed,ast2600-fsi-master.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/aspeed,ast2600-fsi-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed FSI master
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The AST2600 and later contain two identical FSI masters. They share a
+ clock and have a separate interrupt line and output pins.
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2600-fsi-master
+ - aspeed,ast2700-fsi-master
+
+ clocks:
+ maxItems: 1
+
+ cfam-reset-gpios:
+ maxItems: 1
+ description:
+ Output GPIO pin for CFAM reset
+
+ fsi-routing-gpios:
+ maxItems: 1
+ description:
+ Output GPIO pin for setting the FSI mux (internal or cabled)
+
+ fsi-mux-gpios:
+ maxItems: 1
+ description:
+ Input GPIO pin for detecting the desired FSI mux state
+
+ interrupts:
+ maxItems: 1
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - aspeed,ast2600-fsi-master
+then:
+ properties:
+ reg:
+ maxItems: 1
+else:
+ properties:
+ reg:
+ minItems: 1
+ items:
+ - description: OPB control registers
+ - description: FSI controller registers
+ - description: FSI link address space
+ reg-names:
+ items:
+ - const: opb
+ - const: ctrl
+ - const: fsi
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+allOf:
+ - $ref: fsi-controller.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/ast2600-clock.h>
+ #include <dt-bindings/gpio/aspeed-gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ fsi-master@1e79b000 {
+ compatible = "aspeed,ast2600-fsi-master";
+ reg = <0x1e79b000 0x94>;
+ #address-cells = <2>;
+ #size-cells = <0>;
+ interrupts = <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_fsi1_default>;
+ clocks = <&syscon ASPEED_CLK_GATE_FSICLK>;
+ fsi-routing-gpios = <&gpio0 ASPEED_GPIO(Q, 7) GPIO_ACTIVE_HIGH>;
+ fsi-mux-gpios = <&gpio0 ASPEED_GPIO(B, 0) GPIO_ACTIVE_HIGH>;
+ cfam-reset-gpios = <&gpio0 ASPEED_GPIO(Q, 0) GPIO_ACTIVE_LOW>;
+
+ cfam@0,0 {
+ reg = <0 0>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ chip-id = <0>;
+ };
+ };
+ - |
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ fsi-master@21800000 {
+ compatible = "aspeed,ast2700-fsi-master";
+ reg = <0x0 0x21800000 0x0 0x100>,
+ <0x0 0x21000000 0x0 0x1000>,
+ <0x0 0x20000000 0x0 0x1000000>;
+ reg-names = "opb", "ctrl", "fsi";
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ interrupts-extended = <&intc 6>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_fsi0_default>;
+ clocks = <&syscon 40>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fsi/fsi-controller.yaml b/Documentation/devicetree/bindings/fsi/fsi-controller.yaml
new file mode 100644
index 000000000000..ffe191921b26
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/fsi-controller.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/fsi-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: FSI Controller Common Properties
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ FSI (FRU (Field Replaceable Unit) Service Interface) is a two wire bus. The
+ FSI bus is connected to a CFAM (Common FRU Access Macro) which contains
+ various engines such as I2C controllers, SPI controllers, etc.
+
+properties:
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 0
+
+ '#interrupt-cells':
+ const: 1
+
+ bus-frequency:
+ minimum: 1
+ maximum: 200000000
+
+ interrupt-controller: true
+
+ no-scan-on-init:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ The FSI controller cannot scan the bus during initialization.
+
+patternProperties:
+ "cfam@[0-9a-f],[0-9a-f]":
+ type: object
+ properties:
+ chip-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Processor index, a global unique chip ID which is used to identify
+ the physical location of the chip in a system specific way.
+
+ bus-frequency:
+ minimum: 1
+ maximum: 100000000
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+ required:
+ - reg
+
+ additionalProperties: true
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/fsi/fsi-master-aspeed.txt b/Documentation/devicetree/bindings/fsi/fsi-master-aspeed.txt
deleted file mode 100644
index 9853fefff5d8..000000000000
--- a/Documentation/devicetree/bindings/fsi/fsi-master-aspeed.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-Device-tree bindings for AST2600 FSI master
--------------------------------------------
-
-The AST2600 contains two identical FSI masters. They share a clock and have a
-separate interrupt line and output pins.
-
-Required properties:
- - compatible: "aspeed,ast2600-fsi-master"
- - reg: base address and length
- - clocks: phandle and clock number
- - interrupts: platform dependent interrupt description
- - pinctrl-0: phandle to pinctrl node
- - pinctrl-names: pinctrl state
-
-Optional properties:
- - cfam-reset-gpios: GPIO for CFAM reset
-
- - fsi-routing-gpios: GPIO for setting the FSI mux (internal or cabled)
- - fsi-mux-gpios: GPIO for detecting the desired FSI mux state
-
-
-Examples:
-
- fsi-master {
- compatible = "aspeed,ast2600-fsi-master", "fsi-master";
- reg = <0x1e79b000 0x94>;
- interrupts = <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>;
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_fsi1_default>;
- clocks = <&syscon ASPEED_CLK_GATE_FSICLK>;
-
- fsi-routing-gpios = <&gpio0 ASPEED_GPIO(Q, 7) GPIO_ACTIVE_HIGH>;
- fsi-mux-gpios = <&gpio0 ASPEED_GPIO(B, 0) GPIO_ACTIVE_HIGH>;
-
- cfam-reset-gpios = <&gpio0 ASPEED_GPIO(Q, 0) GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/fsi/fsi-master-ast-cf.txt b/Documentation/devicetree/bindings/fsi/fsi-master-ast-cf.txt
deleted file mode 100644
index 3dc752db748b..000000000000
--- a/Documentation/devicetree/bindings/fsi/fsi-master-ast-cf.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-Device-tree bindings for ColdFire offloaded gpio-based FSI master driver
-------------------------------------------------------------------------
-
-Required properties:
- - compatible =
- "aspeed,ast2400-cf-fsi-master" for an AST2400 based system
- or
- "aspeed,ast2500-cf-fsi-master" for an AST2500 based system
-
- - clock-gpios = <gpio-descriptor>; : GPIO for FSI clock
- - data-gpios = <gpio-descriptor>; : GPIO for FSI data signal
- - enable-gpios = <gpio-descriptor>; : GPIO for enable signal
- - trans-gpios = <gpio-descriptor>; : GPIO for voltage translator enable
- - mux-gpios = <gpio-descriptor>; : GPIO for pin multiplexing with other
- functions (eg, external FSI masters)
- - memory-region = <phandle>; : Reference to the reserved memory for
- the ColdFire. Must be 2M aligned on
- AST2400 and 1M aligned on AST2500
- - aspeed,sram = <phandle>; : Reference to the SRAM node.
- - aspeed,cvic = <phandle>; : Reference to the CVIC node.
-
-Examples:
-
- fsi-master {
- compatible = "aspeed,ast2500-cf-fsi-master", "fsi-master";
-
- clock-gpios = <&gpio 0>;
- data-gpios = <&gpio 1>;
- enable-gpios = <&gpio 2>;
- trans-gpios = <&gpio 3>;
- mux-gpios = <&gpio 4>;
-
- memory-region = <&coldfire_memory>;
- aspeed,sram = <&sram>;
- aspeed,cvic = <&cvic>;
- }
diff --git a/Documentation/devicetree/bindings/fsi/fsi-master-gpio.txt b/Documentation/devicetree/bindings/fsi/fsi-master-gpio.txt
deleted file mode 100644
index 1e442450747f..000000000000
--- a/Documentation/devicetree/bindings/fsi/fsi-master-gpio.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Device-tree bindings for gpio-based FSI master driver
------------------------------------------------------
-
-Required properties:
- - compatible = "fsi-master-gpio";
- - clock-gpios = <gpio-descriptor>; : GPIO for FSI clock
- - data-gpios = <gpio-descriptor>; : GPIO for FSI data signal
-
-Optional properties:
- - enable-gpios = <gpio-descriptor>; : GPIO for enable signal
- - trans-gpios = <gpio-descriptor>; : GPIO for voltage translator enable
- - mux-gpios = <gpio-descriptor>; : GPIO for pin multiplexing with other
- functions (eg, external FSI masters)
- - no-gpio-delays; : Don't add extra delays between GPIO
- accesses. This is useful when the HW
- GPIO block is running at a low enough
- frequency.
-
-Examples:
-
- fsi-master {
- compatible = "fsi-master-gpio", "fsi-master";
- clock-gpios = <&gpio 0>;
- data-gpios = <&gpio 1>;
- enable-gpios = <&gpio 2>;
- trans-gpios = <&gpio 3>;
- mux-gpios = <&gpio 4>;
- }
diff --git a/Documentation/devicetree/bindings/fsi/fsi-master-gpio.yaml b/Documentation/devicetree/bindings/fsi/fsi-master-gpio.yaml
new file mode 100644
index 000000000000..21bfbad595b3
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/fsi-master-gpio.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/fsi-master-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: fsi-master-gpio
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+allOf:
+ - $ref: /schemas/fsi/fsi-controller.yaml
+
+properties:
+ compatible:
+ items:
+ - const: fsi-master-gpio
+
+ clock-gpios:
+ description: GPIO for FSI clock
+ maxItems: 1
+
+ data-gpios:
+ description: GPIO for FSI data signal
+ maxItems: 1
+
+ enable-gpios:
+ description: GPIO for enable signal
+ maxItems: 1
+
+ trans-gpios:
+ description: GPIO for voltage translator enable
+ maxItems: 1
+
+ mux-gpios:
+ description: GPIO for pin multiplexing with other functions (eg, external
+ FSI masters)
+ maxItems: 1
+
+ no-gpio-delays:
+ description:
+ Don't add extra delays between GPIO accesses. This is useful when the HW
+ GPIO block is running at a low enough frequency.
+ type: boolean
+
+required:
+ - compatible
+ - clock-gpios
+ - data-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ fsi-master {
+ compatible = "fsi-master-gpio";
+ clock-gpios = <&gpio 0>;
+ data-gpios = <&gpio 1>;
+ enable-gpios = <&gpio 2>;
+ trans-gpios = <&gpio 3>;
+ mux-gpios = <&gpio 4>;
+ };
diff --git a/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml b/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml
index e425278653f5..ad5c83f48425 100644
--- a/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml
+++ b/Documentation/devicetree/bindings/fsi/ibm,fsi2spi.yaml
@@ -9,22 +9,31 @@ title: IBM FSI-attached SPI controllers
maintainers:
- Eddie James <eajames@linux.ibm.com>
-description: |
+description:
This binding describes an FSI CFAM engine called the FSI2SPI. Therefore this
- node will always be a child of an FSI CFAM node; see fsi.txt for details on
- FSI slave and CFAM nodes. This FSI2SPI engine provides access to a number of
- SPI controllers.
+ node will always be a child of an FSI CFAM node. This FSI2SPI engine provides
+ access to a number of SPI controllers.
properties:
compatible:
enum:
- ibm,fsi2spi
- - ibm,fsi2spi-restricted
reg:
items:
- description: FSI slave address
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^spi@[0-9a-f]+$":
+ type: object
+ $ref: /schemas/spi/ibm,spi-fsi.yaml
+
required:
- compatible
- reg
@@ -36,4 +45,22 @@ examples:
fsi2spi@1c00 {
compatible = "ibm,fsi2spi";
reg = <0x1c00 0x400>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ spi@0 {
+ compatible = "ibm,spi-fsi";
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@0 {
+ compatible = "atmel,at25";
+ reg = <0>;
+ address-width = <24>;
+ pagesize = <256>;
+ size = <0x80000>;
+ spi-max-frequency = <1000000>;
+ };
+ };
};
diff --git a/Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml b/Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml
new file mode 100644
index 000000000000..e49ace3ca339
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/ibm,i2cr-fsi-master.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/ibm,i2cr-fsi-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM I2C Responder virtual FSI master
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description: |
+ The I2C Responder (I2CR) is a an I2C device that's connected to an FSI CFAM
+ (see fsi.txt). The I2CR translates I2C bus operations to FSI CFAM reads and
+ writes or SCOM operations, thereby acting as an FSI master.
+
+properties:
+ compatible:
+ enum:
+ - ibm,i2cr-fsi-master
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: fsi-controller.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2cr@20 {
+ compatible = "ibm,i2cr-fsi-master";
+ reg = <0x20>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fsi/ibm,p9-fsi-controller.yaml b/Documentation/devicetree/bindings/fsi/ibm,p9-fsi-controller.yaml
new file mode 100644
index 000000000000..29ea80ff915e
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/ibm,p9-fsi-controller.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/ibm,p9-fsi-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM FSI-attached FSI Hub Controller
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The FSI Hub Controller is an FSI controller, providing a number of FSI links,
+ located on a CFAM. Therefore this node will always be a child of an FSI CFAM
+ node.
+
+properties:
+ compatible:
+ enum:
+ - ibm,p9-fsi-controller
+
+ reg:
+ items:
+ - description: FSI slave address
+
+allOf:
+ - $ref: fsi-controller.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ fsi@3400 {
+ compatible = "ibm,p9-fsi-controller";
+ reg = <0x3400 0x400>;
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ cfam@0,0 {
+ reg = <0 0>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ chip-id = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fsi/ibm,p9-occ.txt b/Documentation/devicetree/bindings/fsi/ibm,p9-occ.txt
deleted file mode 100644
index e73358075a90..000000000000
--- a/Documentation/devicetree/bindings/fsi/ibm,p9-occ.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-Device-tree bindings for FSI-attached POWER9/POWER10 On-Chip Controller (OCC)
------------------------------------------------------------------------------
-
-This is the binding for the P9 or P10 On-Chip Controller accessed over FSI from
-a service processor. See fsi.txt for details on bindings for FSI slave and CFAM
-nodes. The OCC is not an FSI slave device itself, rather it is accessed
-through the SBE FIFO.
-
-Required properties:
- - compatible = "ibm,p9-occ" or "ibm,p10-occ"
-
-Examples:
-
- occ {
- compatible = "ibm,p9-occ";
- };
diff --git a/Documentation/devicetree/bindings/fsi/ibm,p9-occ.yaml b/Documentation/devicetree/bindings/fsi/ibm,p9-occ.yaml
new file mode 100644
index 000000000000..537eac70447c
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/ibm,p9-occ.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/ibm,p9-occ.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM FSI-attached On-Chip Controller (OCC)
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The POWER processor On-Chip Controller (OCC) helps manage power and
+ thermals for the system, accessed through the FSI-attached SBEFIFO
+ from a service processor.
+
+properties:
+ compatible:
+ enum:
+ - ibm,p9-occ
+ - ibm,p10-occ
+
+ hwmon:
+ type: object
+ $ref: /schemas/hwmon/ibm,occ-hwmon.yaml
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ occ {
+ compatible = "ibm,p9-occ";
+
+ hwmon {
+ compatible = "ibm,p9-occ-hwmon";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fsi/ibm,p9-sbefifo.yaml b/Documentation/devicetree/bindings/fsi/ibm,p9-sbefifo.yaml
new file mode 100644
index 000000000000..3cd966fb3c0d
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/ibm,p9-sbefifo.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/ibm,p9-sbefifo.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM FSI-attached SBEFIFO engine
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The SBEFIFO is an FSI CFAM engine that provides an interface to the
+ POWER processor Self Boot Engine (SBE). This node will always be a child
+ of an FSI CFAM node.
+
+properties:
+ compatible:
+ enum:
+ - ibm,p9-sbefifo
+ - ibm,odyssey-sbefifo
+
+ reg:
+ items:
+ - description: FSI slave address
+
+ occ:
+ type: object
+ $ref: ibm,p9-occ.yaml#
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ fsi-slave-engine@2400 {
+ compatible = "ibm,p9-sbefifo";
+ reg = <0x2400 0x400>;
+
+ occ {
+ compatible = "ibm,p9-occ";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/fsi/ibm,p9-scom.yaml b/Documentation/devicetree/bindings/fsi/ibm,p9-scom.yaml
new file mode 100644
index 000000000000..b106f5212ea9
--- /dev/null
+++ b/Documentation/devicetree/bindings/fsi/ibm,p9-scom.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fsi/ibm,p9-scom.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM FSI-attached SCOM engine
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The SCOM engine is an interface to the POWER processor PIB (Pervasive
+ Interconnect Bus). This node will always be a child of an FSI CFAM node.
+
+properties:
+ compatible:
+ enum:
+ - ibm,fsi2pib
+ - ibm,p9-scom
+ - ibm,i2cr-scom
+
+ reg:
+ items:
+ - description: FSI slave address
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ scom@1000 {
+ compatible = "ibm,p9-scom";
+ reg = <0x1000 0x400>;
+ };
diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt
deleted file mode 100644
index b109911669e4..000000000000
--- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt
+++ /dev/null
@@ -1,42 +0,0 @@
-NVIDIA Tegra20/Tegra30/Tegr114/Tegra124 fuse block.
-
-Required properties:
-- compatible : For Tegra20, must contain "nvidia,tegra20-efuse". For Tegra30,
- must contain "nvidia,tegra30-efuse". For Tegra114, must contain
- "nvidia,tegra114-efuse". For Tegra124, must contain "nvidia,tegra124-efuse".
- For Tegra132 must contain "nvidia,tegra132-efuse", "nvidia,tegra124-efuse".
- For Tegra210 must contain "nvidia,tegra210-efuse". For Tegra186 must contain
- "nvidia,tegra186-efuse". For Tegra194 must contain "nvidia,tegra194-efuse".
- For Tegra234 must contain "nvidia,tegra234-efuse".
- Details:
- nvidia,tegra20-efuse: Tegra20 requires using APB DMA to read the fuse data
- due to a hardware bug. Tegra20 also lacks certain information which is
- available in later generations such as fab code, lot code, wafer id,..
- nvidia,tegra30-efuse, nvidia,tegra114-efuse and nvidia,tegra124-efuse:
- The differences between these SoCs are the size of the efuse array,
- the location of the spare (OEM programmable) bits and the location of
- the speedo data.
-- reg: Should contain 1 entry: the entry gives the physical address and length
- of the fuse registers.
-- clocks: Must contain an entry for each entry in clock-names.
- See ../clocks/clock-bindings.txt for details.
-- clock-names: Must include the following entries:
- - fuse
-- resets: Must contain an entry for each entry in reset-names.
- See ../reset/reset.txt for details.
-- reset-names: Must include the following entries:
- - fuse
-
-Example:
-
- fuse@7000f800 {
- compatible = "nvidia,tegra20-efuse";
- reg = <0x7000f800 0x400>,
- <0x70000000 0x400>;
- clocks = <&tegra_car TEGRA20_CLK_FUSE>;
- clock-names = "fuse";
- resets = <&tegra_car 39>;
- reset-names = "fuse";
- };
-
-
diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml
new file mode 100644
index 000000000000..02f0b0462377
--- /dev/null
+++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/fuse/nvidia,tegra20-fuse.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra FUSE block
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - nvidia,tegra20-efuse
+ - nvidia,tegra30-efuse
+ - nvidia,tegra114-efuse
+ - nvidia,tegra124-efuse
+ - nvidia,tegra210-efuse
+ - nvidia,tegra186-efuse
+ - nvidia,tegra194-efuse
+ - nvidia,tegra234-efuse
+
+ - items:
+ - const: nvidia,tegra132-efuse
+ - const: nvidia,tegra124-efuse
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: fuse
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: fuse
+
+ operating-points-v2: true
+
+ power-domains:
+ items:
+ - description: phandle to the core power domain
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra20-efuse
+ - nvidia,tegra30-efuse
+ - nvidia,tegra114-efuse
+ - nvidia,tegra124-efuse
+ - nvidia,tegra132-efuse
+ - nvidia,tegra210-efuse
+then:
+ required:
+ - resets
+ - reset-names
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra20-car.h>
+
+ fuse@7000f800 {
+ compatible = "nvidia,tegra20-efuse";
+ reg = <0x7000f800 0x400>;
+ clocks = <&tegra_car TEGRA20_CLK_FUSE>;
+ clock-names = "fuse";
+ resets = <&tegra_car 39>;
+ reset-names = "fuse";
+ };
diff --git a/Documentation/devicetree/bindings/gnss/brcm,bcm4751.yaml b/Documentation/devicetree/bindings/gnss/brcm,bcm4751.yaml
new file mode 100644
index 000000000000..089166089498
--- /dev/null
+++ b/Documentation/devicetree/bindings/gnss/brcm,bcm4751.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gnss/brcm,bcm4751.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM4751 family GNSS Receiver
+
+maintainers:
+ - Johan Hovold <johan@kernel.org>
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description:
+ Broadcom GPS chips can be used over the UART or I2C bus. The UART
+ bus requires CTS/RTS support. The number of the capsule is more
+ elaborate than the compatibles BCM4751 may be printed
+ BCM4751IFBG for example.
+
+allOf:
+ - $ref: gnss-common.yaml#
+ - $ref: /schemas/serial/serial-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm4751
+ - brcm,bcm4752
+ - brcm,bcm4753
+
+ reg:
+ description:
+ The I2C Address, not required on UART buses.
+
+ vdd-auxin-supply:
+ description:
+ Main voltage supply, pin name VDD_AUXIN, typically connected
+ directly to a battery such as LiIon 3.8V battery or a 2.6V supply.
+
+ vddio-supply:
+ description:
+ IO voltage supply, pin name VDDIO, typically 1.8V
+
+ reset-gpios:
+ maxItems: 1
+ description: An optional active low reset line, should be flagged with
+ GPIO_ACTIVE_LOW.
+
+ enable-gpios:
+ description: Enable GPIO line, connected to pins named REGPU or NSTANDBY.
+ If the line is active low such as NSTANDBY, it should be tagged
+ GPIO_ACTIVE_LOW.
+
+required:
+ - compatible
+ - enable-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ serial {
+ gnss {
+ compatible = "brcm,bcm4751";
+ vdd-auxin-supply = <&vbat>;
+ reset-gpios = <&gpio0 15 GPIO_ACTIVE_LOW>;
+ enable-gpios = <&gpio0 16 GPIO_ACTIVE_HIGH>;
+ current-speed = <38400>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gnss/gnss-common.yaml b/Documentation/devicetree/bindings/gnss/gnss-common.yaml
new file mode 100644
index 000000000000..354c0524089c
--- /dev/null
+++ b/Documentation/devicetree/bindings/gnss/gnss-common.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gnss/gnss-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common Properties for Global Navigation Satellite Systems (GNSS)
+ receiver devices
+
+maintainers:
+ - Johan Hovold <johan@kernel.org>
+
+description: |
+ This document defines device tree properties common to Global Navigation
+ Satellite System receivers.
+
+properties:
+ $nodename:
+ pattern: "^gnss(@.*)?$"
+
+ lna-supply:
+ description: A separate regulator supplying power for the Low Noise
+ Amplifier (LNA). This is an amplifier connected between the GNSS
+ device and the receiver antenna.
+
+ enable-gpios:
+ description: A GPIO line that will enable the GNSS receiver when
+ asserted. If this line is active low, the GPIO phandle should
+ consequently be tagged with the GPIO_ACTIVE_LOW flag so the operating
+ system can rely on asserting the line to enable the GNSS device.
+ maxItems: 1
+
+ timepulse-gpios:
+ description: Timepulse signal
+ maxItems: 1
+
+additionalProperties: true
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ serial {
+ gnss {
+ compatible = "u-blox,neo-8";
+ vcc-supply = <&gnss_reg>;
+ timepulse-gpios = <&gpio0 16 GPIO_ACTIVE_HIGH>;
+ current-speed = <4800>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gnss/gnss.txt b/Documentation/devicetree/bindings/gnss/gnss.txt
deleted file mode 100644
index d6dc9c0d8249..000000000000
--- a/Documentation/devicetree/bindings/gnss/gnss.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-GNSS Receiver DT binding
-
-This documents the binding structure and common properties for GNSS receiver
-devices.
-
-A GNSS receiver node is a node named "gnss" and typically resides on a serial
-bus (e.g. UART, I2C or SPI).
-
-Please refer to the following documents for generic properties:
-
- Documentation/devicetree/bindings/serial/serial.yaml
- Documentation/devicetree/bindings/spi/spi-bus.txt
-
-Required properties:
-
-- compatible : A string reflecting the vendor and specific device the node
- represents
-
-Optional properties:
-- lna-supply : Separate supply for an LNA
-- enable-gpios : GPIO used to enable the device
-- timepulse-gpios : Time pulse GPIO
-
-Example:
-
-serial@1234 {
- compatible = "ns16550a";
-
- gnss {
- compatible = "u-blox,neo-8";
-
- vcc-supply = <&gnss_reg>;
- timepulse-gpios = <&gpio0 16 GPIO_ACTIVE_HIGH>;
-
- current-speed = <4800>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gnss/mediatek.txt b/Documentation/devicetree/bindings/gnss/mediatek.txt
deleted file mode 100644
index 80cb802813c5..000000000000
--- a/Documentation/devicetree/bindings/gnss/mediatek.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-Mediatek-based GNSS Receiver DT binding
-
-Mediatek chipsets are used in GNSS-receiver modules produced by several
-vendors and can use a UART interface.
-
-Please see Documentation/devicetree/bindings/gnss/gnss.txt for generic
-properties.
-
-Required properties:
-
-- compatible : Must be
-
- "globaltop,pa6h"
-
-- vcc-supply : Main voltage regulator (pin name: VCC)
-
-Optional properties:
-
-- current-speed : Default UART baud rate
-- gnss-fix-gpios : GPIO used to determine device position fix state
- (pin name: FIX, 3D_FIX)
-- reset-gpios : GPIO used to reset the device (pin name: RESET, NRESET)
-- timepulse-gpios : Time pulse GPIO (pin name: PPS1, 1PPS)
-- vbackup-supply : Backup voltage regulator (pin name: VBAT, VBACKUP)
-
-Example:
-
-serial@1234 {
- compatible = "ns16550a";
-
- gnss {
- compatible = "globaltop,pa6h";
- vcc-supply = <&vcc_3v3>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gnss/mediatek.yaml b/Documentation/devicetree/bindings/gnss/mediatek.yaml
new file mode 100644
index 000000000000..2b9e5be4ebf3
--- /dev/null
+++ b/Documentation/devicetree/bindings/gnss/mediatek.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gnss/mediatek.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek GNSS Receiver
+
+maintainers:
+ - Johan Hovold <johan@kernel.org>
+
+description:
+ Mediatek chipsets are used in GNSS-receiver modules produced by several
+ vendors and can use a UART interface.
+
+allOf:
+ - $ref: gnss-common.yaml#
+ - $ref: /schemas/serial/serial-peripheral-props.yaml#
+
+properties:
+ compatible:
+ const: globaltop,pa6h
+
+ vcc-supply:
+ description:
+ Main voltage regulator, pin name VCC.
+
+ reset-gpios:
+ maxItems: 1
+ description: An optional reset line, with names such as RESET or NRESET.
+ If the line is active low it should be flagged with GPIO_ACTIVE_LOW.
+
+ timepulse-gpios:
+ description: Comes with pin names such as PPS1 or 1PPS.
+
+ gnss-fix-gpios:
+ maxItems: 1
+ description: GPIO used to determine device position fix state, pin names
+ FIX or 3D_FIX.
+
+ vbackup-supply:
+ description:
+ Regulator providing backup voltage, pin names such as VBAT or VBACKUP.
+
+required:
+ - compatible
+ - vcc-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ serial {
+ gnss {
+ compatible = "globaltop,pa6h";
+ vcc-supply = <&vcc_3v3>;
+ reset-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gnss/sirfstar.txt b/Documentation/devicetree/bindings/gnss/sirfstar.txt
deleted file mode 100644
index f4252b6b660b..000000000000
--- a/Documentation/devicetree/bindings/gnss/sirfstar.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-SiRFstar-based GNSS Receiver DT binding
-
-SiRFstar chipsets are used in GNSS-receiver modules produced by several
-vendors and can use UART, SPI or I2C interfaces.
-
-Please see Documentation/devicetree/bindings/gnss/gnss.txt for generic
-properties.
-
-Required properties:
-
-- compatible : Must be one of
-
- "fastrax,uc430"
- "linx,r4"
- "wi2wi,w2sg0004"
- "wi2wi,w2sg0008i"
- "wi2wi,w2sg0084i"
-
-- vcc-supply : Main voltage regulator (pin name: 3V3_IN, VCC, VDD)
-
-Required properties (I2C):
-- reg : I2C slave address
-
-Required properties (SPI):
-- reg : SPI chip select address
-
-Optional properties:
-
-- sirf,onoff-gpios : GPIO used to power on and off device (pin name: ON_OFF)
-- sirf,wakeup-gpios : GPIO used to determine device power state
- (pin name: RFPWRUP, WAKEUP)
-- timepulse-gpios : Time pulse GPIO (pin name: 1PPS, TM)
-
-Example:
-
-serial@1234 {
- compatible = "ns16550a";
-
- gnss {
- compatible = "wi2wi,w2sg0084i";
-
- vcc-supply = <&gnss_reg>;
- sirf,onoff-gpios = <&gpio0 16 GPIO_ACTIVE_HIGH>;
- sirf,wakeup-gpios = <&gpio0 17 GPIO_ACTIVE_HIGH>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gnss/sirfstar.yaml b/Documentation/devicetree/bindings/gnss/sirfstar.yaml
new file mode 100644
index 000000000000..7e5da89a5ad7
--- /dev/null
+++ b/Documentation/devicetree/bindings/gnss/sirfstar.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gnss/sirfstar.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SiRFstar GNSS Receiver
+
+maintainers:
+ - Johan Hovold <johan@kernel.org>
+
+description:
+ The SiRFstar GNSS receivers have incarnated over the years in different
+ chips, starting from the SiRFstarIII which was a chip that was introduced in
+ 2004 and used in a lot of dedicated GPS devices. In 2009 SiRF was acquired
+ by CSR (Cambridge Silicon Radio) and in 2012 the CSR GPS business was
+ acquired by Samsung, while some products remained with CSR. In 2014 CSR
+ was acquired by Qualcomm who still sell some of the SiRF products.
+
+ SiRF chips can be used over UART, I2C or SPI buses.
+
+allOf:
+ - $ref: gnss-common.yaml#
+ - $ref: /schemas/serial/serial-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - csr,gsd4t
+ - csr,csrg05ta03-icje-r
+ - fastrax,uc430
+ - linx,r4
+ - wi2wi,w2sg0004
+ - wi2wi,w2sg0008i
+ - wi2wi,w2sg0084i
+
+ reg:
+ description:
+ The I2C Address, SPI chip select address. Not required on UART buses.
+
+ vcc-supply:
+ description:
+ Main voltage regulator, pin names such as 3V3_IN, VCC, VDD.
+
+ reset-gpios:
+ maxItems: 1
+ description: An optional active low reset line, should be flagged with
+ GPIO_ACTIVE_LOW.
+
+ sirf,onoff-gpios:
+ maxItems: 1
+ description: GPIO used to power on and off device, pin name ON_OFF.
+
+ sirf,wakeup-gpios:
+ maxItems: 1
+ description: GPIO used to determine device power state, pin names such
+ as RFPWRUP, WAKEUP.
+
+required:
+ - compatible
+ - vcc-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ serial {
+ gnss {
+ compatible = "wi2wi,w2sg0084i";
+ vcc-supply = <&gnss_vcc_reg>;
+ reset-gpios = <&gpio0 15 GPIO_ACTIVE_LOW>;
+ sirf,onoff-gpios = <&gpio0 16 GPIO_ACTIVE_HIGH>;
+ sirf,wakeup-gpios = <&gpio0 17 GPIO_ACTIVE_HIGH>;
+ current-speed = <38400>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gnss/u-blox,neo-6m.yaml b/Documentation/devicetree/bindings/gnss/u-blox,neo-6m.yaml
new file mode 100644
index 000000000000..b349b7bc0412
--- /dev/null
+++ b/Documentation/devicetree/bindings/gnss/u-blox,neo-6m.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gnss/u-blox,neo-6m.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: u-blox GNSS receiver
+
+allOf:
+ - $ref: gnss-common.yaml#
+ - $ref: /schemas/serial/serial-peripheral-props.yaml#
+
+maintainers:
+ - Johan Hovold <johan@kernel.org>
+
+description: >
+ The u-blox GNSS receivers can use UART, DDC (I2C), SPI and USB interfaces.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - u-blox,neo-6m
+ - u-blox,neo-8
+ - u-blox,neo-m8
+ - items:
+ - const: u-blox,neo-m9
+ - const: u-blox,neo-m8
+
+ reg:
+ description: >
+ The DDC Slave Address, SPI chip select address, the number of the USB hub
+ port or the USB host-controller port to which this device is attached,
+ depending on the bus used. Required for the DDC, SPI or USB busses.
+
+ reset-gpios:
+ maxItems: 1
+
+ safeboot-gpios:
+ maxItems: 1
+
+ vcc-supply:
+ description: >
+ Main voltage regulator
+
+ u-blox,extint-gpios:
+ maxItems: 1
+ description: >
+ GPIO connected to the "external interrupt" input pin
+
+ v-bckp-supply:
+ description: >
+ Backup voltage regulator
+
+required:
+ - compatible
+ - vcc-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ serial {
+ gnss {
+ compatible = "u-blox,neo-8";
+ v-bckp-supply = <&gnss_v_bckp_reg>;
+ vcc-supply = <&gnss_vcc_reg>;
+ reset-gpios = <&gpio 1 (GPIO_ACTIVE_LOW | GPIO_OPEN_DRAIN)>;
+ safeboot-gpios = <&gpio 2 (GPIO_ACTIVE_LOW | GPIO_OPEN_DRAIN)>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gnss/u-blox.txt b/Documentation/devicetree/bindings/gnss/u-blox.txt
deleted file mode 100644
index 7cdefd058fe0..000000000000
--- a/Documentation/devicetree/bindings/gnss/u-blox.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-u-blox GNSS Receiver DT binding
-
-The u-blox GNSS receivers can use UART, DDC (I2C), SPI and USB interfaces.
-
-Please see Documentation/devicetree/bindings/gnss/gnss.txt for generic
-properties.
-
-Required properties:
-
-- compatible : Must be one of
-
- "u-blox,neo-6m"
- "u-blox,neo-8"
- "u-blox,neo-m8"
-
-- vcc-supply : Main voltage regulator
-
-Required properties (DDC):
-- reg : DDC (I2C) slave address
-
-Required properties (SPI):
-- reg : SPI chip select address
-
-Required properties (USB):
-- reg : Number of the USB hub port or the USB host-controller port
- to which this device is attached
-
-Optional properties:
-
-- timepulse-gpios : Time pulse GPIO
-- u-blox,extint-gpios : GPIO connected to the "external interrupt" input pin
-- v-bckp-supply : Backup voltage regulator
-
-Example:
-
-serial@1234 {
- compatible = "ns16550a";
-
- gnss {
- compatible = "u-blox,neo-8";
-
- v-bckp-supply = <&gnss_v_bckp_reg>;
- vcc-supply = <&gnss_vcc_reg>;
- };
-};
diff --git a/Documentation/devicetree/bindings/goldfish/pipe.txt b/Documentation/devicetree/bindings/goldfish/pipe.txt
index e417a31a1ee3..5637ce701788 100644
--- a/Documentation/devicetree/bindings/goldfish/pipe.txt
+++ b/Documentation/devicetree/bindings/goldfish/pipe.txt
@@ -1,6 +1,6 @@
Android Goldfish QEMU Pipe
-Andorid pipe virtual device generated by android emulator.
+Android pipe virtual device generated by android emulator.
Required properties:
diff --git a/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt b/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt
deleted file mode 100644
index 973362eb3f1e..000000000000
--- a/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-GPIO controllers on MPC8xxx SoCs
-
-This is for the non-QE/CPM/GUTs GPIO controllers as found on
-8349, 8572, 8610 and compatible.
-
-Every GPIO controller node must have #gpio-cells property defined,
-this information will be used to translate gpio-specifiers.
-See bindings/gpio/gpio.txt for details of how to specify GPIO
-information for devices.
-
-The GPIO module usually is connected to the SoC's internal interrupt
-controller, see bindings/interrupt-controller/interrupts.txt (the
-interrupt client nodes section) for details how to specify this GPIO
-module's interrupt.
-
-The GPIO module may serve as another interrupt controller (cascaded to
-the SoC's internal interrupt controller). See the interrupt controller
-nodes section in bindings/interrupt-controller/interrupts.txt for
-details.
-
-Required properties:
-- compatible: "fsl,<chip>-gpio" followed by "fsl,mpc8349-gpio"
- for 83xx, "fsl,mpc8572-gpio" for 85xx, or
- "fsl,mpc8610-gpio" for 86xx.
-- #gpio-cells: Should be two. The first cell is the pin number
- and the second cell is used to specify optional
- parameters (currently unused).
-- interrupts: Interrupt mapping for GPIO IRQ.
-- gpio-controller: Marks the port as GPIO controller.
-
-Optional properties:
-- interrupt-controller: Empty boolean property which marks the GPIO
- module as an IRQ controller.
-- #interrupt-cells: Should be two. Defines the number of integer
- cells required to specify an interrupt within
- this interrupt controller. The first cell
- defines the pin number, the second cell
- defines additional flags (trigger type,
- trigger polarity). Note that the available
- set of trigger conditions supported by the
- GPIO module depends on the actual SoC.
-
-Example of gpio-controller nodes for a MPC8347 SoC:
-
- gpio1: gpio-controller@c00 {
- #gpio-cells = <2>;
- compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio";
- reg = <0xc00 0x100>;
- interrupt-parent = <&ipic>;
- interrupts = <74 0x8>;
- gpio-controller;
- interrupt-controller;
- #interrupt-cells = <2>;
- };
-
- gpio2: gpio-controller@d00 {
- #gpio-cells = <2>;
- compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio";
- reg = <0xd00 0x100>;
- interrupt-parent = <&ipic>;
- interrupts = <75 0x8>;
- gpio-controller;
- };
-
-Example of a peripheral using the GPIO module as an IRQ controller:
-
- funkyfpga@0 {
- compatible = "funky-fpga";
- ...
- interrupt-parent = <&gpio1>;
- interrupts = <4 3>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt
deleted file mode 100644
index ce19c5660aca..000000000000
--- a/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-* Abilis TB10x GPIO controller
-
-Required Properties:
-- compatible: Should be "abilis,tb10x-gpio"
-- reg: Address and length of the register set for the device
-- gpio-controller: Marks the device node as a gpio controller.
-- #gpio-cells: Should be <2>. The first cell is the pin number and the
- second cell is used to specify optional parameters:
- - bit 0 specifies polarity (0 for normal, 1 for inverted).
-- abilis,ngpio: the number of GPIO pins this driver controls.
-
-Optional Properties:
-- interrupt-controller: Marks the device node as an interrupt controller.
-- #interrupt-cells: Should be <1>. Interrupts are triggered on both edges.
-- interrupts: Defines the interrupt line connecting this GPIO controller to
- its parent interrupt controller.
-
-GPIO ranges are specified as described in
-Documentation/devicetree/bindings/gpio/gpio.txt
-
-Example:
-
- gpioa: gpio@ff140000 {
- compatible = "abilis,tb10x-gpio";
- interrupt-controller;
- #interrupt-cells = <1>;
- interrupt-parent = <&tb10x_ictl>;
- interrupts = <27 2>;
- reg = <0xFF140000 0x1000>;
- gpio-controller;
- #gpio-cells = <2>;
- abilis,ngpio = <3>;
- gpio-ranges = <&iomux 0 0 0>;
- gpio-ranges-group-names = "gpioa_pins";
- };
diff --git a/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.yaml b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.yaml
new file mode 100644
index 000000000000..c93ec0f16bcd
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/abilis,tb10x-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Abilis TB10x GPIO controller
+
+maintainers:
+ - Christian Ruppert <christian.ruppert@abilis.com>
+
+properties:
+ compatible:
+ const: abilis,tb10x-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-ranges: true
+
+ gpio-ranges-group-names: true
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+ description: Interrupts are triggered on both edges
+
+ interrupts:
+ maxItems: 1
+
+ abilis,ngpio:
+ description: Number of GPIO pins this driver controls
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - abilis,ngpio
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@ff140000 {
+ compatible = "abilis,tb10x-gpio";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <27 2>;
+ reg = <0xff140000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ abilis,ngpio = <3>;
+ gpio-ranges = <&iomux 0 0 0>;
+ gpio-ranges-group-names = "gpioa_pins";
+ };
diff --git a/Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml b/Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml
new file mode 100644
index 000000000000..25b3198c4d3e
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/adi,ds4520-gpio.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/adi,ds4520-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DS4520 I2C GPIO expander
+
+maintainers:
+ - Okan Sahin <okan.sahin@analog.com>
+
+properties:
+ compatible:
+ enum:
+ - adi,ds4520-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ ngpios:
+ minimum: 1
+ maximum: 9
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - ngpios
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@50 {
+ compatible = "adi,ds4520-gpio";
+ reg = <0x50>;
+ ngpios = <9>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gpio/airoha,en7523-gpio.yaml b/Documentation/devicetree/bindings/gpio/airoha,en7523-gpio.yaml
new file mode 100644
index 000000000000..7c41d8e814cd
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/airoha,en7523-gpio.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/airoha,en7523-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Airoha EN7523 GPIO controller
+
+maintainers:
+ - John Crispin <john@phrozen.org>
+
+description: |
+ Airoha's GPIO controller on their ARM EN7523 SoCs consists of two banks of 32
+ GPIOs.
+
+properties:
+ $nodename:
+ pattern: "^gpio@[0-9a-f]+$"
+
+ compatible:
+ items:
+ - const: airoha,en7523-gpio
+
+ reg:
+ description: |
+ The first tuple points to the input register.
+ The second and third tuple point to the direction registers
+ The fourth tuple points to the output register
+ maxItems: 4
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+required:
+ - compatible
+ - reg
+ - "#gpio-cells"
+ - gpio-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio0: gpio@1fbf0200 {
+ compatible = "airoha,en7523-gpio";
+ reg = <0x1fbf0204 0x4>,
+ <0x1fbf0200 0x4>,
+ <0x1fbf0220 0x4>,
+ <0x1fbf0214 0x4>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ gpio1: gpio@1fbf0270 {
+ compatible = "airoha,en7523-gpio";
+ reg = <0x1fbf0270 0x4>,
+ <0x1fbf0260 0x4>,
+ <0x1fbf0264 0x4>,
+ <0x1fbf0278 0x4>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/altr-pio-1.0.yaml b/Documentation/devicetree/bindings/gpio/altr-pio-1.0.yaml
new file mode 100644
index 000000000000..18afed324198
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/altr-pio-1.0.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/altr-pio-1.0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera GPIO controller
+
+maintainers:
+ - Dinh Nguyen <dinguyen@kernel.org>
+ - Marek Vasut <marex@denx.de>
+ - Mathieu Malaterre <malat@debian.org>
+ - Tien Hock Loh <thloh@altera.com>
+
+properties:
+ compatible:
+ const: altr,pio-1.0
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description:
+ First cell is the GPIO offset number. Second cell is reserved and
+ currently unused.
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ altr,ngpio:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Width of the GPIO bank.
+ default: 32
+
+ altr,interrupt-type:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: >
+ Specifies the interrupt trigger type synthesized by hardware.
+ Values defined in <dt-bindings/interrupt-controller/irq.h>.
+ enum: [1, 2, 3, 4]
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpio@ff200000 {
+ compatible = "altr,pio-1.0";
+ reg = <0xff200000 0x10>;
+ interrupts = <45 4>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ altr,ngpio = <32>;
+ altr,interrupt-type = <IRQ_TYPE_EDGE_RISING>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/apm,xgene-gpio-sb.yaml b/Documentation/devicetree/bindings/gpio/apm,xgene-gpio-sb.yaml
new file mode 100644
index 000000000000..d205dd7b492c
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/apm,xgene-gpio-sb.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/apm,xgene-gpio-sb.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: APM X-Gene Standby GPIO controller
+
+maintainers:
+ - Khuong Dinh <khuong@os.amperecomputing.com>
+
+description: |
+ This is a gpio controller in the standby domain. It also supports interrupt in
+ some particular pins which are sourced to its parent interrupt controller
+ as diagram below:
+ +-----------------+
+ | X-Gene standby |
+ | GPIO controller +------ GPIO_0
+ +------------+ | | ...
+ | Parent IRQ | EXT_INT_0 | +------ GPIO_8/EXT_INT_0
+ | controller | (SPI40) | | ...
+ | (GICv2) +--------------+ +------ GPIO_[N+8]/EXT_INT_N
+ | | ... | |
+ | | EXT_INT_N | +------ GPIO_[N+9]
+ | | (SPI[40 + N])| | ...
+ | +--------------+ +------ GPIO_MAX
+ +------------+ +-----------------+
+
+properties:
+ compatible:
+ const: apm,xgene-gpio-sb
+
+ reg:
+ maxItems: 1
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+ interrupts:
+ description:
+ List of interrupt specifiers for EXT_INT_0 through EXT_INT_N. The first
+ entry must correspond to EXT_INT_0.
+
+ '#interrupt-cells':
+ const: 2
+ description:
+ First cell selects EXT_INT_N (0-N), second cell specifies flags
+
+ interrupt-controller: true
+
+ apm,nr-gpios:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of GPIO pins
+
+ apm,nr-irqs:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of interrupt pins
+
+ apm,irq-start:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Lowest GPIO pin supporting interrupts
+
+required:
+ - compatible
+ - reg
+ - '#gpio-cells'
+ - gpio-controller
+ - interrupts
+ - '#interrupt-cells'
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@17001000 {
+ compatible = "apm,xgene-gpio-sb";
+ reg = <0x17001000 0x400>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ interrupts = <0x0 0x28 0x1>,
+ <0x0 0x29 0x1>,
+ <0x0 0x2a 0x1>,
+ <0x0 0x2b 0x1>,
+ <0x0 0x2c 0x1>,
+ <0x0 0x2d 0x1>;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ apm,nr-gpios = <22>;
+ apm,nr-irqs = <6>;
+ apm,irq-start = <8>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/apple,smc-gpio.yaml b/Documentation/devicetree/bindings/gpio/apple,smc-gpio.yaml
new file mode 100644
index 000000000000..42b1bc0a10c9
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/apple,smc-gpio.yaml
@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/apple,smc-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple Mac System Management Controller GPIO
+
+maintainers:
+ - Sven Peter <sven@kernel.org>
+
+description:
+ Apple Mac System Management Controller GPIO block.
+
+properties:
+ compatible:
+ const: apple,smc-gpio
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+required:
+ - compatible
+ - gpio-controller
+ - '#gpio-cells'
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/gpio/aspeed,ast2400-gpio.yaml b/Documentation/devicetree/bindings/gpio/aspeed,ast2400-gpio.yaml
new file mode 100644
index 000000000000..b16273e69dfe
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/aspeed,ast2400-gpio.yaml
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/aspeed,ast2400-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed GPIO controller
+
+maintainers:
+ - Andrew Jeffery <andrew@codeconstruct.com.au>
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-gpio
+ - aspeed,ast2500-gpio
+ - aspeed,ast2600-gpio
+ - aspeed,ast2700-gpio
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description: The clock to use for debounce timings
+
+ gpio-controller: true
+ gpio-line-names:
+ minItems: 12
+ maxItems: 232
+
+ gpio-ranges: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ ngpios:
+ minimum: 12
+ maximum: 232
+
+patternProperties:
+ "-hog(-[0-9]+)?$":
+ type: object
+ required:
+ - gpio-hog
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+ - gpio-controller
+ - "#gpio-cells"
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: aspeed,ast2400-gpio
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 220
+ maxItems: 220
+ ngpios:
+ const: 220
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: aspeed,ast2500-gpio
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 232
+ maxItems: 232
+ ngpios:
+ const: 232
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: aspeed,ast2600-gpio
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 36
+ maxItems: 208
+ ngpios:
+ enum: [ 36, 208 ]
+ required:
+ - ngpios
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: aspeed,ast2700-gpio
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 12
+ maxItems: 216
+ ngpios:
+ enum: [ 12, 216 ]
+ required:
+ - ngpios
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@1e780000 {
+ compatible = "aspeed,ast2400-gpio";
+ reg = <0x1e780000 0x1000>;
+ interrupts = <20>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+ - |
+ gpio: gpio@1e780000 {
+ compatible = "aspeed,ast2500-gpio";
+ reg = <0x1e780000 0x200>;
+ interrupts = <20>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pinctrl 0 0 232>;
+ };
+ - |
+ #include <dt-bindings/clock/ast2600-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ gpio0: gpio@1e780000 {
+ compatible = "aspeed,ast2600-gpio";
+ reg = <0x1e780000 0x400>;
+ clocks = <&syscon ASPEED_CLK_APB2>;
+ interrupts = <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ gpio-ranges = <&pinctrl 0 0 208>;
+ ngpios = <208>;
+ };
+ gpio1: gpio@1e780800 {
+ compatible = "aspeed,ast2600-gpio";
+ reg = <0x1e780800 0x800>;
+ clocks = <&syscon ASPEED_CLK_APB1>;
+ interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pinctrl 0 208 36>;
+ ngpios = <36>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml b/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml
new file mode 100644
index 000000000000..1046f0331c09
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/aspeed,sgpio.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/aspeed,sgpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed SGPIO controller
+
+maintainers:
+ - Andrew Jeffery <andrew@aj.id.au>
+
+description:
+ This SGPIO controller is for ASPEED AST2400, AST2500 and AST2600 SoC,
+ AST2600 have two sgpio master one with 128 pins another one with 80 pins,
+ AST2500/AST2400 have one sgpio master with 80 pins. Each of the Serial
+ GPIO pins can be programmed to support the following options
+ - Support interrupt option for each input port and various interrupt
+ sensitivity option (level-high, level-low, edge-high, edge-low)
+ - Support reset tolerance option for each output port
+ - Directly connected to APB bus and its shift clock is from APB bus clock
+ divided by a programmable value.
+ - Co-work with external signal-chained TTL components (74LV165/74LV595)
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-sgpio
+ - aspeed,ast2500-sgpio
+ - aspeed,ast2600-sgpiom
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ # Each SGPIO is represented as a pair of input and output GPIOs
+ gpio-line-names:
+ minItems: 160
+ maxItems: 256
+
+ '#gpio-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ clocks:
+ maxItems: 1
+
+ ngpios: true
+
+ bus-frequency: true
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - interrupts
+ - interrupt-controller
+ - '#interrupt-cells'
+ - ngpios
+ - clocks
+ - bus-frequency
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/aspeed-clock.h>
+ sgpio: sgpio@1e780200 {
+ #gpio-cells = <2>;
+ compatible = "aspeed,ast2500-sgpio";
+ gpio-controller;
+ interrupts = <40>;
+ reg = <0x1e780200 0x0100>;
+ clocks = <&syscon ASPEED_CLK_APB>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ ngpios = <80>;
+ bus-frequency = <12000000>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml b/Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml
new file mode 100644
index 000000000000..d810043b56b6
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/atmel,at91rm9200-gpio.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/atmel,at91rm9200-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip GPIO controller (PIO)
+
+maintainers:
+ - Manikandan Muralidharan <manikandan.m@microchip.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - atmel,at91sam9x5-gpio
+ - microchip,sam9x60-gpio
+ - const: atmel,at91rm9200-gpio
+ - items:
+ - enum:
+ - microchip,sam9x7-gpio
+ - const: microchip,sam9x60-gpio
+ - const: atmel,at91rm9200-gpio
+ - items:
+ - const: atmel,at91rm9200-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ gpio-controller: true
+ gpio-line-names: true
+
+ "#gpio-cells":
+ const: 2
+
+ clocks:
+ maxItems: 1
+
+ "#gpio-lines":
+ description:
+ Number of gpio, 32 by default if absent
+ maxItems: 1
+ default: 32
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+ - gpio-controller
+ - "#gpio-cells"
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/at91.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpio@fffff400 {
+ compatible = "atmel,at91rm9200-gpio";
+ reg = <0xfffff400 0x200>;
+ interrupts = <2 IRQ_TYPE_LEVEL_HIGH 1>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ clocks = <&pmc PMC_TYPE_PERIPHERAL 2>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/blaize,blzp1600-gpio.yaml b/Documentation/devicetree/bindings/gpio/blaize,blzp1600-gpio.yaml
new file mode 100644
index 000000000000..a05f6ea619c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/blaize,blzp1600-gpio.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/blaize,blzp1600-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Blaize BLZP1600 GPIO controller
+
+description:
+ Blaize BLZP1600 GPIO controller is an implementation of the VeriSilicon
+ APB GPIO v0.2 IP block. It has 32 ports each of which are intended to be
+ represented as child nodes with the generic GPIO-controller properties
+ as described in this binding's file.
+
+maintainers:
+ - Nikolaos Pasaloukos <nikolaos.pasaloukos@blaize.com>
+ - James Cowgill <james.cowgill@blaize.com>
+ - Matt Redfearn <matt.redfearn@blaize.com>
+ - Neil Jones <neil.jones@blaize.com>
+
+properties:
+ $nodename:
+ pattern: "^gpio@[0-9a-f]+$"
+
+ compatible:
+ enum:
+ - blaize,blzp1600-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ ngpios:
+ default: 32
+ minimum: 1
+ maximum: 32
+
+ interrupts:
+ maxItems: 1
+
+ gpio-line-names: true
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+
+dependencies:
+ interrupt-controller: [ interrupts ]
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpio: gpio@4c0000 {
+ compatible = "blaize,blzp1600-gpio";
+ reg = <0x004c0000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ ngpios = <32>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
deleted file mode 100644
index 4d69f79df859..000000000000
--- a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
+++ /dev/null
@@ -1,86 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/gpio/brcm,bcm6345-gpio.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Broadcom BCM6345 GPIO controller
-
-maintainers:
- - Álvaro Fernández Rojas <noltari@gmail.com>
- - Jonas Gorski <jonas.gorski@gmail.com>
-
-description: |+
- Bindings for Broadcom's BCM63xx memory-mapped GPIO controllers.
-
- These bindings can be used on any BCM63xx SoC. However, BCM6338 and BCM6345
- are the only ones which don't need a pinctrl driver.
-
- BCM6338 have 8-bit data and dirout registers, where GPIO state can be read
- and/or written, and the direction changed from input to output.
- BCM6345 have 16-bit data and dirout registers, where GPIO state can be read
- and/or written, and the direction changed from input to output.
- BCM6318, BCM6328, BCM6358, BCM6362, BCM6368 and BCM63268 have 32-bit data
- and dirout registers, where GPIO state can be read and/or written, and the
- direction changed from input to output.
-
-properties:
- compatible:
- enum:
- - brcm,bcm6318-gpio
- - brcm,bcm6328-gpio
- - brcm,bcm6345-gpio
- - brcm,bcm6358-gpio
- - brcm,bcm6362-gpio
- - brcm,bcm6368-gpio
- - brcm,bcm63268-gpio
-
- gpio-controller: true
-
- "#gpio-cells":
- const: 2
-
- gpio-ranges:
- maxItems: 1
-
- native-endian: true
-
- reg:
- maxItems: 2
-
- reg-names:
- items:
- - const: dirout
- - const: dat
-
-required:
- - compatible
- - reg
- - reg-names
- - gpio-controller
- - '#gpio-cells'
-
-additionalProperties: false
-
-examples:
- - |
- gpio@fffe0406 {
- compatible = "brcm,bcm6345-gpio";
- reg-names = "dirout", "dat";
- reg = <0xfffe0406 2>, <0xfffe040a 2>;
- native-endian;
-
- gpio-controller;
- #gpio-cells = <2>;
- };
-
- - |
- gpio@0 {
- compatible = "brcm,bcm63268-gpio";
- reg-names = "dirout", "dat";
- reg = <0x0 0x8>, <0x8 0x8>;
-
- gpio-controller;
- gpio-ranges = <&pinctrl 0 0 52>;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
new file mode 100644
index 000000000000..62fcc2bd5d80
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/brcm,bcm63xx-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM63xx GPIO controller
+
+maintainers:
+ - Álvaro Fernández Rojas <noltari@gmail.com>
+ - Jonas Gorski <jonas.gorski@gmail.com>
+
+description: |+
+ Bindings for Broadcom's BCM63xx memory-mapped GPIO controllers.
+
+ These bindings can be used on any BCM63xx SoC. However, BCM6338 and BCM6345
+ are the only ones which don't need a pinctrl driver.
+
+ BCM6338 have 8-bit data and dirout registers, where GPIO state can be read
+ and/or written, and the direction changed from input to output.
+ BCM6318, BCM6328, BCM6358, BCM6362, BCM6368 and BCM63268 have 32-bit data
+ and dirout registers, where GPIO state can be read and/or written, and the
+ direction changed from input to output.
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm6318-gpio
+ - brcm,bcm6328-gpio
+ - brcm,bcm6358-gpio
+ - brcm,bcm6362-gpio
+ - brcm,bcm6368-gpio
+ - brcm,bcm63268-gpio
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-ranges:
+ maxItems: 1
+
+ native-endian: true
+
+ reg:
+ maxItems: 2
+
+ reg-names:
+ items:
+ - const: dirout
+ - const: dat
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - gpio-controller
+ - '#gpio-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@0 {
+ compatible = "brcm,bcm63268-gpio";
+ reg-names = "dirout", "dat";
+ reg = <0x0 0x8>, <0x8 0x8>;
+
+ gpio-controller;
+ gpio-ranges = <&pinctrl 0 0 52>;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.txt b/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.txt
deleted file mode 100644
index 5d468ecd1809..000000000000
--- a/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.txt
+++ /dev/null
@@ -1,83 +0,0 @@
-Broadcom STB "UPG GIO" GPIO controller
-
-The controller's registers are organized as sets of eight 32-bit
-registers with each set controlling a bank of up to 32 pins. A single
-interrupt is shared for all of the banks handled by the controller.
-
-Required properties:
-
-- compatible:
- Must be "brcm,brcmstb-gpio"
-
-- reg:
- Define the base and range of the I/O address space containing
- the brcmstb GPIO controller registers
-
-- #gpio-cells:
- Should be <2>. The first cell is the pin number (within the controller's
- pin space), and the second is used for the following:
- bit[0]: polarity (0 for active-high, 1 for active-low)
-
-- gpio-controller:
- Specifies that the node is a GPIO controller.
-
-- brcm,gpio-bank-widths:
- Number of GPIO lines for each bank. Number of elements must
- correspond to number of banks suggested by the 'reg' property.
-
-Optional properties:
-
-- interrupts:
- The interrupt shared by all GPIO lines for this controller.
-
-- interrupts-extended:
- Alternate form of specifying interrupts and parents that allows for
- multiple parents. This takes precedence over 'interrupts' and
- 'interrupt-parent'. Wakeup-capable GPIO controllers often route their
- wakeup interrupt lines through a different interrupt controller than the
- primary interrupt line, making this property necessary.
-
-- #interrupt-cells:
- Should be <2>. The first cell is the GPIO number, the second should specify
- flags. The following subset of flags is supported:
- - bits[3:0] trigger type and level flags
- 1 = low-to-high edge triggered
- 2 = high-to-low edge triggered
- 4 = active high level-sensitive
- 8 = active low level-sensitive
- Valid combinations are 1, 2, 3, 4, 8.
- See also Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-
-- interrupt-controller:
- Marks the device node as an interrupt controller
-
-- wakeup-source:
- GPIOs for this controller can be used as a wakeup source
-
-Example:
- upg_gio: gpio@f040a700 {
- #gpio-cells = <2>;
- #interrupt-cells = <2>;
- compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio";
- gpio-controller;
- interrupt-controller;
- reg = <0xf040a700 0x80>;
- interrupt-parent = <&irq0_intc>;
- interrupts = <0x6>;
- brcm,gpio-bank-widths = <32 32 32 24>;
- };
-
- upg_gio_aon: gpio@f04172c0 {
- #gpio-cells = <2>;
- #interrupt-cells = <2>;
- compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio";
- gpio-controller;
- interrupt-controller;
- reg = <0xf04172c0 0x40>;
- interrupt-parent = <&irq0_aon_intc>;
- interrupts = <0x6>;
- interrupts-extended = <&irq0_aon_intc 0x6>,
- <&aon_pm_l2_intc 0x5>;
- wakeup-source;
- brcm,gpio-bank-widths = <18 4>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml
new file mode 100644
index 000000000000..fbd69b4cecc7
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/brcm,brcmstb-gpio.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/brcm,brcmstb-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom STB "UPG GIO" GPIO controller
+
+description: >
+ The controller's registers are organized as sets of eight 32-bit
+ registers with each set controlling a bank of up to 32 pins. A single
+ interrupt is shared for all of the banks handled by the controller.
+
+maintainers:
+ - Doug Berger <opendmb@gmail.com>
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm7445-gpio
+ - const: brcm,brcmstb-gpio
+
+ reg:
+ maxItems: 1
+ description: >
+ Define the base and range of the I/O address space containing
+ the brcmstb GPIO controller registers
+
+ "#gpio-cells":
+ const: 2
+ description: >
+ The first cell is the pin number (within the controller's
+ pin space), and the second is used for the following:
+ bit[0]: polarity (0 for active-high, 1 for active-low)
+
+ gpio-controller: true
+
+ brcm,gpio-bank-widths:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: >
+ Number of GPIO lines for each bank. Number of elements must
+ correspond to number of banks suggested by the 'reg' property.
+
+ interrupts:
+ maxItems: 1
+ description: >
+ The interrupt shared by all GPIO lines for this controller.
+
+ "#interrupt-cells":
+ const: 2
+ description: |
+ The first cell is the GPIO number, the second should specify
+ flags. The following subset of flags is supported:
+ - bits[3:0] trigger type and level flags
+ 1 = low-to-high edge triggered
+ 2 = high-to-low edge triggered
+ 4 = active high level-sensitive
+ 8 = active low level-sensitive
+ Valid combinations are 1, 2, 3, 4, 8.
+
+ interrupt-controller: true
+
+ gpio-ranges: true
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 128
+
+ wakeup-source:
+ type: boolean
+ description: >
+ GPIOs for this controller can be used as a wakeup source
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - brcm,gpio-bank-widths
+
+additionalProperties: false
+
+examples:
+ - |
+ upg_gio: gpio@f040a700 {
+ #gpio-cells = <2>;
+ #interrupt-cells = <2>;
+ compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio";
+ gpio-controller;
+ interrupt-controller;
+ reg = <0xf040a700 0x80>;
+ interrupt-parent = <&irq0_intc>;
+ interrupts = <0x6>;
+ brcm,gpio-bank-widths = <32 32 32 24>;
+ gpio-ranges = <&pinctrl 0 0 120>;
+ };
+
+ upg_gio_aon: gpio@f04172c0 {
+ #gpio-cells = <2>;
+ #interrupt-cells = <2>;
+ compatible = "brcm,bcm7445-gpio", "brcm,brcmstb-gpio";
+ gpio-controller;
+ interrupt-controller;
+ reg = <0xf04172c0 0x40>;
+ interrupt-parent = <&irq0_aon_intc>;
+ interrupts = <0x6>;
+ wakeup-source;
+ brcm,gpio-bank-widths = <18 4>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt b/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt
deleted file mode 100644
index 4a63bc96b687..000000000000
--- a/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-Broadcom Kona Family GPIO
-=========================
-
-This GPIO driver is used in the following Broadcom SoCs:
- BCM11130, BCM11140, BCM11351, BCM28145, BCM28155
-
-The Broadcom GPIO Controller IP can be configured prior to synthesis to
-support up to 8 banks of 32 GPIOs where each bank has its own IRQ. The
-GPIO controller only supports edge, not level, triggering of interrupts.
-
-Required properties
--------------------
-
-- compatible: "brcm,bcm11351-gpio", "brcm,kona-gpio"
-- reg: Physical base address and length of the controller's registers.
-- interrupts: The interrupt outputs from the controller. There is one GPIO
- interrupt per GPIO bank. The number of interrupts listed depends on the
- number of GPIO banks on the SoC. The interrupts must be ordered by bank,
- starting with bank 0. There is always a 1:1 mapping between banks and
- IRQs.
-- #gpio-cells: Should be <2>. The first cell is the pin number, the second
- cell is used to specify optional parameters:
- - bit 0 specifies polarity (0 for normal, 1 for inverted)
- See also "gpio-specifier" in .../devicetree/bindings/gpio/gpio.txt.
-- #interrupt-cells: Should be <2>. The first cell is the GPIO number. The
- second cell is used to specify flags. The following subset of flags is
- supported:
- - trigger type (bits[1:0]):
- 1 = low-to-high edge triggered.
- 2 = high-to-low edge triggered.
- 3 = low-to-high or high-to-low edge triggered
- Valid values are 1, 2, 3
- See also .../devicetree/bindings/interrupt-controller/interrupts.txt.
-- gpio-controller: Marks the device node as a GPIO controller.
-- interrupt-controller: Marks the device node as an interrupt controller.
-
-Example:
- gpio: gpio@35003000 {
- compatible = "brcm,bcm11351-gpio", "brcm,kona-gpio";
- reg = <0x35003000 0x800>;
- interrupts =
- <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH
- GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH
- GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH
- GIC_SPI 113 IRQ_TYPE_LEVEL_HIGH
- GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH
- GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>;
- #gpio-cells = <2>;
- #interrupt-cells = <2>;
- gpio-controller;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml
new file mode 100644
index 000000000000..296fdd6b8f38
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/brcm,kona-gpio.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/brcm,kona-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom Kona family GPIO controller
+
+description:
+ The Broadcom GPIO Controller IP can be configured prior to synthesis to
+ support up to 8 banks of 32 GPIOs where each bank has its own IRQ. The
+ GPIO controller only supports edge, not level, triggering of interrupts.
+
+maintainers:
+ - Ray Jui <rjui@broadcom.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm11351-gpio
+ - brcm,bcm21664-gpio
+ - brcm,bcm23550-gpio
+ - const: brcm,kona-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 4
+ maxItems: 6
+ description:
+ The interrupt outputs from the controller. There is one GPIO interrupt
+ per GPIO bank. The number of interrupts listed depends on the number of
+ GPIO banks on the SoC. The interrupts must be ordered by bank, starting
+ with bank 0. There is always a 1:1 mapping between banks and IRQs.
+
+ '#gpio-cells':
+ const: 2
+
+ '#interrupt-cells':
+ const: 2
+
+ gpio-controller: true
+
+ interrupt-controller: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#gpio-cells'
+ - '#interrupt-cells'
+ - gpio-controller
+ - interrupt-controller
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,bcm11351-gpio
+ then:
+ properties:
+ interrupts:
+ minItems: 6
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - brcm,bcm21664-gpio
+ - brcm,bcm23550-gpio
+ then:
+ properties:
+ interrupts:
+ maxItems: 4
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpio@35003000 {
+ compatible = "brcm,bcm11351-gpio", "brcm,kona-gpio";
+ reg = <0x35003000 0x800>;
+ interrupts = <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 113 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 112 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>;
+ #gpio-cells = <2>;
+ #interrupt-cells = <2>;
+ gpio-controller;
+ interrupt-controller;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml
index c213cb9ddb9f..5cfefbbea6ca 100644
--- a/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/brcm,xgs-iproc-gpio.yaml
@@ -66,5 +66,4 @@ examples:
interrupts = <GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>;
};
-
...
diff --git a/Documentation/devicetree/bindings/gpio/cavium,octeon-3860-gpio.yaml b/Documentation/devicetree/bindings/gpio/cavium,octeon-3860-gpio.yaml
new file mode 100644
index 000000000000..35155b900655
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/cavium,octeon-3860-gpio.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/cavium,octeon-3860-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cavium Octeon 3860 GPIO controller
+
+maintainers:
+ - Bartosz Golaszewski <brgl@bgdev.pl>
+
+properties:
+ compatible:
+ const: cavium,octeon-3860-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 16
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ gpio@1070000000800 {
+ compatible = "cavium,octeon-3860-gpio";
+ reg = <0x10700 0x00000800 0x0 0x100>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ /* The GPIO pin connect to 16 consecutive CUI bits */
+ interrupts = <0 16>, <0 17>, <0 18>, <0 19>,
+ <0 20>, <0 21>, <0 22>, <0 23>,
+ <0 24>, <0 25>, <0 26>, <0 27>,
+ <0 28>, <0 29>, <0 30>, <0 31>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gpio/cavium-octeon-gpio.txt b/Documentation/devicetree/bindings/gpio/cavium-octeon-gpio.txt
deleted file mode 100644
index 9d6dcd3fe7f9..000000000000
--- a/Documentation/devicetree/bindings/gpio/cavium-octeon-gpio.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* General Purpose Input Output (GPIO) bus.
-
-Properties:
-- compatible: "cavium,octeon-3860-gpio"
-
- Compatibility with all cn3XXX, cn5XXX and cn6XXX SOCs.
-
-- reg: The base address of the GPIO unit's register bank.
-
-- gpio-controller: This is a GPIO controller.
-
-- #gpio-cells: Must be <2>. The first cell is the GPIO pin.
-
-- interrupt-controller: The GPIO controller is also an interrupt
- controller, many of its pins may be configured as an interrupt
- source.
-
-- #interrupt-cells: Must be <2>. The first cell is the GPIO pin
- connected to the interrupt source. The second cell is the interrupt
- triggering protocol and may have one of four values:
- 1 - edge triggered on the rising edge.
- 2 - edge triggered on the falling edge
- 4 - level triggered active high.
- 8 - level triggered active low.
-
-- interrupts: Interrupt routing for each pin.
-
-Example:
-
- gpio-controller@1070000000800 {
- #gpio-cells = <2>;
- compatible = "cavium,octeon-3860-gpio";
- reg = <0x10700 0x00000800 0x0 0x100>;
- gpio-controller;
- /* Interrupts are specified by two parts:
- * 1) GPIO pin number (0..15)
- * 2) Triggering (1 - edge rising
- * 2 - edge falling
- * 4 - level active high
- * 8 - level active low)
- */
- interrupt-controller;
- #interrupt-cells = <2>;
- /* The GPIO pin connect to 16 consecutive CUI bits */
- interrupts = <0 16>, <0 17>, <0 18>, <0 19>,
- <0 20>, <0 21>, <0 22>, <0 23>,
- <0 24>, <0 25>, <0 26>, <0 27>,
- <0 28>, <0 29>, <0 30>, <0 31>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/cdns,gpio.txt b/Documentation/devicetree/bindings/gpio/cdns,gpio.txt
deleted file mode 100644
index 706ef00f5c64..000000000000
--- a/Documentation/devicetree/bindings/gpio/cdns,gpio.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-Cadence GPIO controller bindings
-
-Required properties:
-- compatible: should be "cdns,gpio-r1p02".
-- reg: the register base address and size.
-- #gpio-cells: should be 2.
- * first cell is the GPIO number.
- * second cell specifies the GPIO flags, as defined in
- <dt-bindings/gpio/gpio.h>. Only the GPIO_ACTIVE_HIGH
- and GPIO_ACTIVE_LOW flags are supported.
-- gpio-controller: marks the device as a GPIO controller.
-- clocks: should contain one entry referencing the peripheral clock driving
- the GPIO controller.
-
-Optional properties:
-- ngpios: integer number of gpio lines supported by this controller, up to 32.
-- interrupts: interrupt specifier for the controllers interrupt.
-- interrupt-controller: marks the device as an interrupt controller. When
- defined, interrupts, interrupt-parent and #interrupt-cells
- are required.
-- interrupt-cells: should be 2.
- * first cell is the GPIO number you want to use as an IRQ source.
- * second cell specifies the IRQ type, as defined in
- <dt-bindings/interrupt-controller/irq.h>.
- Currently only level sensitive IRQs are supported.
-
-
-Example:
- gpio0: gpio-controller@fd060000 {
- compatible = "cdns,gpio-r1p02";
- reg =<0xfd060000 0x1000>;
-
- clocks = <&gpio_clk>;
-
- interrupt-parent = <&gic>;
- interrupts = <0 5 IRQ_TYPE_LEVEL_HIGH>;
-
- gpio-controller;
- #gpio-cells = <2>;
-
- interrupt-controller;
- #interrupt-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/cdns,gpio.yaml b/Documentation/devicetree/bindings/gpio/cdns,gpio.yaml
new file mode 100644
index 000000000000..a84d60b39459
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/cdns,gpio.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/cdns,gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cadence GPIO Controller
+
+maintainers:
+ - Jan Kotas <jank@cadence.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: cdns,gpio-r1p02
+ - items:
+ - enum:
+ - axiado,ax3000-gpio
+ - const: cdns,gpio-r1p02
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ ngpios:
+ minimum: 1
+ maximum: 32
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description: |
+ - First cell is the GPIO line number.
+ - Second cell is flags as defined in <dt-bindings/gpio/gpio.h>,
+ only GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW supported.
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+ description: |
+ - First cell is the GPIO line number used as IRQ.
+ - Second cell is the trigger type, as defined in
+ <dt-bindings/interrupt-controller/irq.h>.
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - gpio-controller
+ - "#gpio-cells"
+
+if:
+ required: [interrupt-controller]
+then:
+ required:
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ gpio0: gpio-controller@fd060000 {
+ compatible = "cdns,gpio-r1p02";
+ reg = <0xfd060000 0x1000>;
+ clocks = <&gpio_clk>;
+
+ interrupt-parent = <&gic>;
+ interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt
deleted file mode 100644
index fd42e7280f72..000000000000
--- a/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-* ARM Cirrus Logic CLPS711X SYSFLG1 MCTRL GPIOs
-
-Required properties:
-- compatible: Should contain "cirrus,ep7209-mctrl-gpio".
-- gpio-controller: Marks the device node as a gpio controller.
-- #gpio-cells: Should be two. The first cell is the pin number and
- the second cell is used to specify the gpio polarity:
- 0 = Active high,
- 1 = Active low.
-
-Example:
- sysgpio: sysgpio {
- compatible = "cirrus,ep7312-mctrl-gpio",
- "cirrus,ep7209-mctrl-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.yaml b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.yaml
new file mode 100644
index 000000000000..bdffca817f1b
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/cirrus,clps711x-mctrl-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Cirrus Logic CLPS711X SYSFLG1 MCTRL GPIOs
+
+maintainers:
+ - Alexander Shiyan <shc_work@mail.ru>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: cirrus,ep7312-mctrl-gpio
+ - const: cirrus,ep7209-mctrl-gpio
+ - const: cirrus,ep7209-mctrl-gpio
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ gpio,syscon-dev:
+ description:
+ Phandle and offset of device's specific registers within the syscon state
+ control registers
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to syscon
+ - description: register offset within state control registers
+
+required:
+ - compatible
+ - gpio-controller
+ - '#gpio-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ sysgpio: sysgpio {
+ compatible = "cirrus,ep7312-mctrl-gpio",
+ "cirrus,ep7209-mctrl-gpio";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/delta,tn48m-gpio.yaml b/Documentation/devicetree/bindings/gpio/delta,tn48m-gpio.yaml
new file mode 100644
index 000000000000..e3e668a12091
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/delta,tn48m-gpio.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/delta,tn48m-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Delta Networks TN48M CPLD GPIO controller
+
+maintainers:
+ - Robert Marko <robert.marko@sartura.hr>
+
+description: |
+ This module is part of the Delta TN48M multi-function device. For more
+ details see ../mfd/delta,tn48m-cpld.yaml.
+
+ Delta TN48M has an onboard Lattice CPLD that is used as an GPIO expander.
+ It provides 12 pins in total, they are input-only or ouput-only type.
+
+properties:
+ compatible:
+ enum:
+ - delta,tn48m-gpo
+ - delta,tn48m-gpi
+
+ reg:
+ maxItems: 1
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+required:
+ - compatible
+ - reg
+ - "#gpio-cells"
+ - gpio-controller
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/gpio/exar,xra1403.yaml b/Documentation/devicetree/bindings/gpio/exar,xra1403.yaml
new file mode 100644
index 000000000000..053134faf475
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/exar,xra1403.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/exar,xra1403.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: XRA1403 16-bit GPIO Expander with Reset Input
+
+maintainers:
+ - Nandor Han <nandor.han@ge.com>
+
+description: >
+ The XRA1403 is an 16-bit GPIO expander with an SPI interface. Features
+ available:
+
+ - Individually programmable inputs:
+ - Internal pull-up resistors
+ - Polarity inversion
+ - Individual interrupt enable
+ - Rising edge and/or Falling edge interrupt
+ - Input filter
+ - Individually programmable outputs:
+ - Output Level Control
+ - Output Three-State Control
+
+properties:
+ compatible:
+ const: exar,xra1403
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ reset-gpios:
+ description: Control line for the device reset.
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@2 {
+ compatible = "exar,xra1403";
+ reg = <2>;
+ spi-max-frequency = <1000000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ reset-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml b/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml
index 5fe19fa5f67c..23410aeca300 100644
--- a/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml
+++ b/Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml
@@ -6,6 +6,22 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Generic 8-bit shift register
+description: |
+ NOTE: These chips nominally don't have a chip select pin. They do however
+ have a rising-edge triggered latch clock (or storage register clock) pin,
+ which behaves like an active-low chip select.
+
+ After the bits are shifted into the shift register, CS# is driven high, which
+ the 74HC595 sees as a rising edge on the latch clock that results in a
+ transfer of the bits from the shift register to the storage register and thus
+ to the output pins.
+ _ _ _ _
+ shift clock ____| |_| |_..._| |_| |_________
+
+ latch clock * trigger
+ ___ ________
+ chip select# |___________________|
+
maintainers:
- Maxime Ripard <mripard@kernel.org>
@@ -26,30 +42,18 @@ properties:
const: 2
registers-number:
+ $ref: /schemas/types.yaml#/definitions/uint32
description: Number of daisy-chained shift registers
enable-gpios:
description: GPIO connected to the OE (Output Enable) pin.
maxItems: 1
- spi-max-frequency: true
-
patternProperties:
"^(hog-[0-9]+|.+-hog(-[0-9]+)?)$":
type: object
-
- properties:
- gpio-hog: true
- gpios: true
- output-high: true
- output-low: true
- line-name: true
-
required:
- gpio-hog
- - gpios
-
- additionalProperties: false
required:
- compatible
@@ -58,20 +62,23 @@ required:
- '#gpio-cells'
- registers-number
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
spi {
- #address-cells = <1>;
- #size-cells = <0>;
-
- gpio5: gpio5@0 {
- compatible = "fairchild,74hc595";
- reg = <0>;
- gpio-controller;
- #gpio-cells = <2>;
- registers-number = <4>;
- spi-max-frequency = <100000>;
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio5@0 {
+ compatible = "fairchild,74hc595";
+ reg = <0>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ registers-number = <4>;
+ spi-max-frequency = <100000>;
+ };
};
diff --git a/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.txt b/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.txt
deleted file mode 100644
index d04236558619..000000000000
--- a/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Faraday Technology FTGPIO010 GPIO Controller
-
-Required properties:
-
-- compatible : Should be one of
- "cortina,gemini-gpio", "faraday,ftgpio010"
- "moxa,moxart-gpio", "faraday,ftgpio010"
- "faraday,ftgpio010"
-- reg : Should contain registers location and length
-- interrupts : Should contain the interrupt line for the GPIO block
-- gpio-controller : marks this as a GPIO controller
-- #gpio-cells : Should be 2, see gpio/gpio.txt
-- interrupt-controller : marks this as an interrupt controller
-- #interrupt-cells : a standard two-cell interrupt flag, see
- interrupt-controller/interrupts.txt
-
-Example:
-
-gpio@4d000000 {
- compatible = "cortina,gemini-gpio", "faraday,ftgpio010";
- reg = <0x4d000000 0x100>;
- interrupts = <22 IRQ_TYPE_LEVEL_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.yaml b/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.yaml
new file mode 100644
index 000000000000..640da5b9b0cc
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/faraday,ftgpio010.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Faraday Technology FTGPIO010 GPIO Controller
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: cortina,gemini-gpio
+ - const: faraday,ftgpio010
+ - items:
+ - const: moxa,moxart-gpio
+ - const: faraday,ftgpio010
+ - const: faraday,ftgpio010
+
+ reg:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+ description: Should contain the interrupt line for the GPIO block
+
+ gpio-controller: true
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+ "#interrupt-cells":
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#gpio-cells"
+ - interrupt-controller
+ - "#interrupt-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ gpio@4d000000 {
+ compatible = "cortina,gemini-gpio", "faraday,ftgpio010";
+ reg = <0x4d000000 0x100>;
+ interrupts = <22 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/fsl,imx8qxp-sc-gpio.yaml b/Documentation/devicetree/bindings/gpio/fsl,imx8qxp-sc-gpio.yaml
new file mode 100644
index 000000000000..b7b32220935d
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/fsl,imx8qxp-sc-gpio.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/fsl,imx8qxp-sc-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO driver over IMX SCU firmware API
+
+maintainers:
+ - Shenwei Wang <shenwei.wang@nxp.com>
+
+description: |
+ This module provides the standard interface to control the
+ resource pins in SCU domain on i.MX8 platforms.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx8qxp-sc-gpio
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+required:
+ - compatible
+ - "#gpio-cells"
+ - gpio-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio0: gpio {
+ compatible = "fsl,imx8qxp-sc-gpio";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml b/Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml
new file mode 100644
index 000000000000..4cb2a6b9fabf
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/fsl,qoriq-gpio.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/fsl,qoriq-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MPC512x/MPC8xxx/QorIQ/Layerscape GPIO controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - fsl,mpc5121-gpio
+ - fsl,mpc5125-gpio
+ - fsl,mpc8314-gpio
+ - fsl,mpc8349-gpio
+ - fsl,mpc8572-gpio
+ - fsl,mpc8610-gpio
+ - fsl,pq3-gpio
+ - items:
+ - enum:
+ - fsl,ls1021a-gpio
+ - fsl,ls1028a-gpio
+ - fsl,ls1043a-gpio
+ - fsl,ls1046a-gpio
+ - fsl,ls1088a-gpio
+ - fsl,ls2080a-gpio
+ - const: fsl,qoriq-gpio
+ - items:
+ - enum:
+ - fsl,mpc8308-gpio
+ - fsl,mpc8377-gpio
+ - fsl,mpc8378-gpio
+ - fsl,mpc8379-gpio
+ - const: fsl,mpc8349-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 32
+
+ little-endian:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ GPIO registers are used as little endian. If not
+ present registers are used as big endian by default.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#gpio-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@1100 {
+ compatible = "fsl,mpc5125-gpio";
+ reg = <0x1100 0x080>;
+ interrupts = <78 0x8>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ gpio@2300000 {
+ compatible = "fsl,ls2080a-gpio", "fsl,qoriq-gpio";
+ reg = <0x2300000 0x10000>;
+ interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>;
+ little-endian;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml b/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml
index f57d22d1ebd6..6b06609c649e 100644
--- a/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml
@@ -7,7 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale i.MX/MXC GPIO controller
maintainers:
- - Anson Huang <Anson.Huang@nxp.com>
+ - Shawn Guo <shawnguo@kernel.org>
+ - Sascha Hauer <s.hauer@pengutronix.de>
+ - Fabio Estevam <festevam@gmail.com>
properties:
compatible:
@@ -19,10 +21,18 @@ properties:
- fsl,imx35-gpio
- fsl,imx7d-gpio
- items:
+ - enum:
+ - fsl,imx27-gpio
+ - const: fsl,imx21-gpio
+ - items:
- const: fsl,imx35-gpio
- const: fsl,imx31-gpio
- items:
- enum:
+ - fsl,imx25-gpio
+ - const: fsl,imx35-gpio
+ - items:
+ - enum:
- fsl,imx50-gpio
- fsl,imx51-gpio
- fsl,imx53-gpio
@@ -32,11 +42,15 @@ properties:
- fsl,imx6sx-gpio
- fsl,imx6ul-gpio
- fsl,imx7d-gpio
+ - fsl,imx8dxl-gpio
- fsl,imx8mm-gpio
- fsl,imx8mn-gpio
- fsl,imx8mp-gpio
- fsl,imx8mq-gpio
+ - fsl,imx8qm-gpio
- fsl,imx8qxp-gpio
+ - fsl,imxrt1050-gpio
+ - fsl,imxrt1170-gpio
- const: fsl,imx35-gpio
reg:
@@ -71,19 +85,8 @@ properties:
patternProperties:
"^(hog-[0-9]+|.+-hog(-[0-9]+)?)$":
type: object
- properties:
- gpio-hog: true
- gpios: true
- input: true
- output-high: true
- output-low: true
- line-name: true
-
required:
- gpio-hog
- - gpios
-
- additionalProperties: false
required:
- compatible
diff --git a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt
deleted file mode 100644
index bef353f370d8..000000000000
--- a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Fujitsu MB86S7x GPIO Controller
--------------------------------
-
-Required properties:
-- compatible: Should be "fujitsu,mb86s70-gpio"
-- reg: Base address and length of register space
-- clocks: Specify the clock
-- gpio-controller: Marks the device node as a gpio controller.
-- #gpio-cells: Should be <2>. The first cell is the pin number and the
- second cell is used to specify optional parameters:
- - bit 0 specifies polarity (0 for normal, 1 for inverted).
-
-Examples:
- gpio0: gpio@31000000 {
- compatible = "fujitsu,mb86s70-gpio";
- reg = <0 0x31000000 0x10000>;
- gpio-controller;
- #gpio-cells = <2>;
- clocks = <&clk 0 2 1>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml
new file mode 100644
index 000000000000..d18d95285465
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/fujitsu,mb86s70-gpio.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/fujitsu,mb86s70-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fujitsu MB86S7x GPIO Controller
+
+maintainers:
+ - Jassi Brar <jaswinder.singh@linaro.org>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: socionext,synquacer-gpio
+ - const: fujitsu,mb86s70-gpio
+ - const: fujitsu,mb86s70-gpio
+
+ reg:
+ maxItems: 1
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+ gpio-line-names: true
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - '#gpio-cells'
+ - gpio-controller
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@31000000 {
+ compatible = "fujitsu,mb86s70-gpio";
+ reg = <0x31000000 0x10000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ clocks = <&clk 0 2 1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt b/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt
deleted file mode 100644
index 6e81f8b755c5..000000000000
--- a/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Gateworks PLD GPIO controller bindings
-
-The GPIO controller should be a child node on an I2C bus,
-see: i2c/i2c.txt for details.
-
-Required properties:
-- compatible: Should be "gateworks,pld-gpio"
-- reg: I2C slave address
-- gpio-controller: Marks the device node as a GPIO controller.
-- #gpio-cells: Should be <2>. The first cell is the gpio number and
- the second cell is used to specify optional parameters.
-
-Example:
-
-pld@56 {
- compatible = "gateworks,pld-gpio";
- reg = <0x56>;
- gpio-controller;
- #gpio-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt b/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt
deleted file mode 100644
index 7bb1a9d60133..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-* 74XX MMIO GPIO driver
-
-Required properties:
-- compatible: Should contain one of the following:
- "ti,741g125": for 741G125 (1-bit Input),
- "ti,741g174": for 741G74 (1-bit Output),
- "ti,742g125": for 742G125 (2-bit Input),
- "ti,7474" : for 7474 (2-bit Output),
- "ti,74125" : for 74125 (4-bit Input),
- "ti,74175" : for 74175 (4-bit Output),
- "ti,74365" : for 74365 (6-bit Input),
- "ti,74174" : for 74174 (6-bit Output),
- "ti,74244" : for 74244 (8-bit Input),
- "ti,74273" : for 74273 (8-bit Output),
- "ti,741624" : for 741624 (16-bit Input),
- "ti,7416374": for 7416374 (16-bit Output).
-- reg: Physical base address and length where IC resides.
-- gpio-controller: Marks the device node as a gpio controller.
-- #gpio-cells: Should be two. The first cell is the pin number and
- the second cell is used to specify the GPIO polarity:
- 0 = Active High,
- 1 = Active Low.
-
-Example:
- ctrl: gpio@30008004 {
- compatible = "ti,74174";
- reg = <0x30008004 0x1>;
- gpio-controller;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-altera.txt b/Documentation/devicetree/bindings/gpio/gpio-altera.txt
deleted file mode 100644
index 146e554b3c67..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-altera.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-Altera GPIO controller bindings
-
-Required properties:
-- compatible:
- - "altr,pio-1.0"
-- reg: Physical base address and length of the controller's registers.
-- #gpio-cells : Should be 2
- - The first cell is the gpio offset number.
- - The second cell is reserved and is currently unused.
-- gpio-controller : Marks the device node as a GPIO controller.
-- interrupt-controller: Mark the device node as an interrupt controller
-- #interrupt-cells : Should be 1. The interrupt type is fixed in the hardware.
- - The first cell is the GPIO offset number within the GPIO controller.
-- interrupts: Specify the interrupt.
-- altr,interrupt-type: Specifies the interrupt trigger type the GPIO
- hardware is synthesized. This field is required if the Altera GPIO controller
- used has IRQ enabled as the interrupt type is not software controlled,
- but hardware synthesized. Required if GPIO is used as an interrupt
- controller. The value is defined in <dt-bindings/interrupt-controller/irq.h>
- Only the following flags are supported:
- IRQ_TYPE_EDGE_RISING
- IRQ_TYPE_EDGE_FALLING
- IRQ_TYPE_EDGE_BOTH
- IRQ_TYPE_LEVEL_HIGH
-
-Optional properties:
-- altr,ngpio: Width of the GPIO bank. This defines how many pins the
- GPIO device has. Ranges between 1-32. Optional and defaults to 32 if not
- specified.
-
-Example:
-
-gpio_altr: gpio@ff200000 {
- compatible = "altr,pio-1.0";
- reg = <0xff200000 0x10>;
- interrupts = <0 45 4>;
- altr,ngpio = <32>;
- altr,interrupt-type = <IRQ_TYPE_EDGE_RISING>;
- #gpio-cells = <2>;
- gpio-controller;
- #interrupt-cells = <1>;
- interrupt-controller;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt
deleted file mode 100644
index b2033fc3a71a..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Aspeed GPIO controller Device Tree Bindings
--------------------------------------------
-
-Required properties:
-- compatible : Either "aspeed,ast2400-gpio", "aspeed,ast2500-gpio",
- or "aspeed,ast2600-gpio".
-
-- #gpio-cells : Should be two
- - First cell is the GPIO line number
- - Second cell is used to specify optional
- parameters (unused)
-
-- reg : Address and length of the register set for the device
-- gpio-controller : Marks the device node as a GPIO controller.
-- interrupts : Interrupt specifier (see interrupt bindings for
- details)
-- interrupt-controller : Mark the GPIO controller as an interrupt-controller
-
-Optional properties:
-
-- clocks : A phandle to the clock to use for debounce timings
-- ngpios : Number of GPIOs controlled by this controller. Should be set
- when there are multiple GPIO controllers on a SoC (ast2600).
-
-The gpio and interrupt properties are further described in their respective
-bindings documentation:
-
-- Documentation/devicetree/bindings/gpio/gpio.txt
-- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-
- Example:
- gpio@1e780000 {
- #gpio-cells = <2>;
- compatible = "aspeed,ast2400-gpio";
- gpio-controller;
- interrupts = <20>;
- reg = <0x1e780000 0x1000>;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-ath79.txt b/Documentation/devicetree/bindings/gpio/gpio-ath79.txt
deleted file mode 100644
index cf71f3ec969d..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-ath79.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-Binding for Qualcomm Atheros AR7xxx/AR9xxx GPIO controller
-
-Required properties:
-- compatible: has to be "qca,<soctype>-gpio" and one of the following
- fallbacks:
- - "qca,ar7100-gpio"
- - "qca,ar9340-gpio"
-- reg: Base address and size of the controllers memory area
-- gpio-controller : Marks the device node as a GPIO controller.
-- #gpio-cells : Should be two. The first cell is the pin number and the
- second cell is used to specify optional parameters.
-- ngpios: Should be set to the number of GPIOs available on the SoC.
-
-Optional properties:
-- interrupts: Interrupt specifier for the controllers interrupt.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode interrupt
- source, should be 2
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-Example:
-
- gpio@18040000 {
- compatible = "qca,ar9132-gpio", "qca,ar7100-gpio";
- reg = <0x18040000 0x30>;
- interrupts = <2>;
-
- ngpios = <22>;
-
- gpio-controller;
- #gpio-cells = <2>;
-
- interrupt-controller;
- #interrupt-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt
deleted file mode 100644
index fc42b2caa06d..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt
+++ /dev/null
@@ -1,75 +0,0 @@
-AXP209 GPIO & pinctrl controller
-
-This driver follows the usual GPIO bindings found in
-Documentation/devicetree/bindings/gpio/gpio.txt
-
-This driver follows the usual pinctrl bindings found in
-Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
-
-This driver employs the per-pin muxing pattern.
-
-Required properties:
-- compatible: Should be one of:
- - "x-powers,axp209-gpio"
- - "x-powers,axp813-gpio"
-- #gpio-cells: Should be two. The first cell is the pin number and the
- second is the GPIO flags.
-- gpio-controller: Marks the device node as a GPIO controller.
-
-This node must be a subnode of the axp20x PMIC, documented in
-Documentation/devicetree/bindings/mfd/axp20x.txt
-
-Example:
-
-axp209: pmic@34 {
- compatible = "x-powers,axp209";
- reg = <0x34>;
- interrupt-parent = <&nmi_intc>;
- interrupts = <0 IRQ_TYPE_LEVEL_LOW>;
- interrupt-controller;
- #interrupt-cells = <1>;
-
- axp_gpio: gpio {
- compatible = "x-powers,axp209-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- };
-};
-
-The GPIOs can be muxed to other functions and therefore, must be a subnode of
-axp_gpio.
-
-Example:
-
-&axp_gpio {
- gpio0_adc: gpio0-adc {
- pins = "GPIO0";
- function = "adc";
- };
-};
-
-&example_node {
- pinctrl-names = "default";
- pinctrl-0 = <&gpio0_adc>;
-};
-
-GPIOs and their functions
--------------------------
-
-Each GPIO is independent from the other (i.e. GPIO0 in gpio_in function does
-not force GPIO1 and GPIO2 to be in gpio_in function as well).
-
-axp209
-------
-GPIO | Functions
-------------------------
-GPIO0 | gpio_in, gpio_out, ldo, adc
-GPIO1 | gpio_in, gpio_out, ldo, adc
-GPIO2 | gpio_in, gpio_out
-
-axp813
-------
-GPIO | Functions
-------------------------
-GPIO0 | gpio_in, gpio_out, ldo, adc
-GPIO1 | gpio_in, gpio_out, ldo
diff --git a/Documentation/devicetree/bindings/gpio/gpio-clps711x.txt b/Documentation/devicetree/bindings/gpio/gpio-clps711x.txt
deleted file mode 100644
index 0a304ad29d81..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-clps711x.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Cirrus Logic CLPS711X GPIO controller
-
-Required properties:
-- compatible: Should be "cirrus,ep7209-gpio"
-- reg: Physical base GPIO controller registers location and length.
- There should be two registers, first is DATA register, the second
- is DIRECTION.
-- gpio-controller: Marks the device node as a gpio controller.
-- #gpio-cells: Should be two. The first cell is the pin number and
- the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-
-Note: Each GPIO port should have an alias correctly numbered in "aliases"
-node.
-
-Example:
-
-aliases {
- gpio0 = &porta;
-};
-
-porta: gpio@80000000 {
- compatible = "cirrus,ep7312-gpio","cirrus,ep7209-gpio";
- reg = <0x80000000 0x1>, <0x80000040 0x1>;
- gpio-controller;
- #gpio-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-consumer-common.yaml b/Documentation/devicetree/bindings/gpio/gpio-consumer-common.yaml
new file mode 100644
index 000000000000..40d0be31e200
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-consumer-common.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-consumer-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common GPIO lines
+
+maintainers:
+ - Bartosz Golaszewski <brgl@bgdev.pl>
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description:
+ Pay attention to using proper GPIO flag (e.g. GPIO_ACTIVE_LOW) for the GPIOs
+ using inverted signal (e.g. RESETN).
+
+select: true
+
+properties:
+ enable-gpios:
+ maxItems: 1
+ description:
+ GPIO connected to the enable control pin.
+
+ reset-gpios:
+ description:
+ GPIO (or GPIOs for power sequence) connected to the device reset pin
+ (e.g. RESET or RESETN).
+
+ powerdown-gpios:
+ maxItems: 1
+ description:
+ GPIO connected to the power down pin (hardware power down or power cut,
+ e.g. PD or PWDN).
+
+ pwdn-gpios:
+ maxItems: 1
+ description: Use powerdown-gpios
+ deprecated: true
+
+ wakeup-gpios:
+ maxItems: 1
+ description:
+ GPIO connected to the pin waking up the device from suspend or other
+ power-saving modes.
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mmc-pwrseq-simple
+ then:
+ properties:
+ reset-gpios:
+ minItems: 1
+ maxItems: 32
+ else:
+ properties:
+ reset-gpios:
+ maxItems: 1
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml b/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml
index f32e09ef937c..1434d08f8b74 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml
+++ b/Documentation/devicetree/bindings/gpio/gpio-davinci.yaml
@@ -32,10 +32,12 @@ properties:
gpio-ranges: true
+ gpio-reserved-ranges: true
+
gpio-line-names:
description: strings describing the names of each gpio line.
minItems: 1
- maxItems: 100
+ maxItems: 144
"#gpio-cells":
const: 2
diff --git a/Documentation/devicetree/bindings/gpio/gpio-delay.yaml b/Documentation/devicetree/bindings/gpio/gpio-delay.yaml
new file mode 100644
index 000000000000..1cebc4058e27
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-delay.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-delay.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO delay controller
+
+maintainers:
+ - Alexander Stein <linux@ew.tq-group.com>
+
+description: |
+ This binding describes an electrical setup where setting an GPIO output
+ is delayed by some external setup, e.g. RC circuit.
+
+ +----------+ +-----------+
+ | | VCC_B | |
+ | | | | |
+ | | VCC_A _ | |
+ | GPIO | | | R | Consumer |
+ |controller| ___ |_| | |
+ | | | | | | |
+ | [IOx|-------| |--+-----|-----+ |
+ | | |___| | | input |
+ | | | | |
+ +----------+ --- C +-----------+
+ ---
+ |
+ -
+ GND
+
+ If the input on the consumer is controlled by an open-drain signal
+ attached to an RC circuit the ramp-up delay is not under control
+ of the GPIO controller.
+
+properties:
+ compatible:
+ const: gpio-delay
+
+ "#gpio-cells":
+ description: |
+ Specifies the pin, ramp-up and ramp-down delays. The
+ delays are specified in microseconds.
+ const: 3
+
+ gpios:
+ description: Array of GPIOs which output signal change is delayed
+ minItems: 1
+ maxItems: 32
+
+ gpio-controller: true
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 32
+
+required:
+ - compatible
+ - "#gpio-cells"
+ - gpio-controller
+ - gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ enable_delay: enable-delay {
+ compatible = "gpio-delay";
+ #gpio-cells = <3>;
+ gpio-controller;
+ gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
+ <&gpio3 1 GPIO_ACTIVE_HIGH>;
+ };
+
+ consumer {
+ enable-gpios = <&enable_delay 0 130000 30000>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt b/Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt
deleted file mode 100644
index 0423699d74c7..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Keystone 2 DSP GPIO controller bindings
-
-HOST OS userland running on ARM can send interrupts to DSP cores using
-the DSP GPIO controller IP. It provides 28 IRQ signals per each DSP core.
-This is one of the component used by the IPC mechanism used on Keystone SOCs.
-
-For example TCI6638K2K SoC has 8 DSP GPIO controllers:
- - 8 for C66x CorePacx CPUs 0-7
-
-Keystone 2 DSP GPIO controller has specific features:
-- each GPIO can be configured only as output pin;
-- setting GPIO value to 1 causes IRQ generation on target DSP core;
-- reading pin value returns 0 - if IRQ was handled or 1 - IRQ is still
- pending.
-
-Required Properties:
-- compatible: should be "ti,keystone-dsp-gpio"
-- ti,syscon-dev: phandle/offset pair. The phandle to syscon used to
- access device state control registers and the offset of device's specific
- registers within device state control registers range.
-- gpio-controller: Marks the device node as a gpio controller.
-- #gpio-cells: Should be 2.
-
-Please refer to gpio.txt in this directory for details of the common GPIO
-bindings used by client devices.
-
-Example:
- dspgpio0: keystone_dsp_gpio@2620240 {
- compatible = "ti,keystone-dsp-gpio";
- ti,syscon-dev = <&devctrl 0x240>;
- gpio-controller;
- #gpio-cells = <2>;
- };
-
- dsp0: dsp0 {
- compatible = "linux,rproc-user";
- ...
- kick-gpio = <&dspgpio0 27>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt
deleted file mode 100644
index 54040a2bfe3a..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt
+++ /dev/null
@@ -1,97 +0,0 @@
-Spreadtrum EIC controller bindings
-
-The EIC is the abbreviation of external interrupt controller, which can
-be used only in input mode. The Spreadtrum platform has 2 EIC controllers,
-one is in digital chip, and another one is in PMIC. The digital chip EIC
-controller contains 4 sub-modules: EIC-debounce, EIC-latch, EIC-async and
-EIC-sync. But the PMIC EIC controller contains only one EIC-debounce sub-
-module.
-
-The EIC-debounce sub-module provides up to 8 source input signal
-connections. A debounce mechanism is used to capture the input signals'
-stable status (millisecond resolution) and a single-trigger mechanism
-is introduced into this sub-module to enhance the input event detection
-reliability. In addition, this sub-module's clock can be shut off
-automatically to reduce power dissipation. Moreover the debounce range
-is from 1ms to 4s with a step size of 1ms. The input signal will be
-ignored if it is asserted for less than 1 ms.
-
-The EIC-latch sub-module is used to latch some special power down signals
-and generate interrupts, since the EIC-latch does not depend on the APB
-clock to capture signals.
-
-The EIC-async sub-module uses a 32kHz clock to capture the short signals
-(microsecond resolution) to generate interrupts by level or edge trigger.
-
-The EIC-sync is similar with GPIO's input function, which is a synchronized
-signal input register. It can generate interrupts by level or edge trigger
-when detecting input signals.
-
-Required properties:
-- compatible: Should be one of the following:
- "sprd,sc9860-eic-debounce",
- "sprd,sc9860-eic-latch",
- "sprd,sc9860-eic-async",
- "sprd,sc9860-eic-sync",
- "sprd,sc2731-eic".
-- reg: Define the base and range of the I/O address space containing
- the GPIO controller registers.
-- gpio-controller: Marks the device node as a GPIO controller.
-- #gpio-cells: Should be <2>. The first cell is the gpio number and
- the second cell is used to specify optional parameters.
-- interrupt-controller: Marks the device node as an interrupt controller.
-- #interrupt-cells: Should be <2>. Specifies the number of cells needed
- to encode interrupt source.
-- interrupts: Should be the port interrupt shared by all the gpios.
-
-Example:
- eic_debounce: gpio@40210000 {
- compatible = "sprd,sc9860-eic-debounce";
- reg = <0 0x40210000 0 0x80>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- eic_latch: gpio@40210080 {
- compatible = "sprd,sc9860-eic-latch";
- reg = <0 0x40210080 0 0x20>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- eic_async: gpio@402100a0 {
- compatible = "sprd,sc9860-eic-async";
- reg = <0 0x402100a0 0 0x20>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- eic_sync: gpio@402100c0 {
- compatible = "sprd,sc9860-eic-sync";
- reg = <0 0x402100c0 0 0x20>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- pmic_eic: gpio@300 {
- compatible = "sprd,sc2731-eic";
- reg = <0x300>;
- interrupt-parent = <&sc2731_pmic>;
- interrupts = <5 IRQ_TYPE_LEVEL_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-ep9301.yaml b/Documentation/devicetree/bindings/gpio/gpio-ep9301.yaml
new file mode 100644
index 000000000000..3a1079d6ee20
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-ep9301.yaml
@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-ep9301.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: EP93xx GPIO controller
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+ - Bartosz Golaszewski <brgl@bgdev.pl>
+ - Nikita Shubin <nikita.shubin@maquefel.me>
+
+properties:
+ compatible:
+ oneOf:
+ - const: cirrus,ep9301-gpio
+ - items:
+ - enum:
+ - cirrus,ep9302-gpio
+ - cirrus,ep9307-gpio
+ - cirrus,ep9312-gpio
+ - cirrus,ep9315-gpio
+ - const: cirrus,ep9301-gpio
+
+ reg:
+ minItems: 2
+ items:
+ - description: data register
+ - description: direction register
+ - description: interrupt registers base
+
+ reg-names:
+ minItems: 2
+ items:
+ - const: data
+ - const: dir
+ - const: intr
+
+ gpio-controller: true
+
+ gpio-ranges: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ interrupts:
+ oneOf:
+ - maxItems: 1
+ - description: port F has dedicated irq line for each gpio line
+ maxItems: 8
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@80840000 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840000 0x04>,
+ <0x80840010 0x04>,
+ <0x80840090 0x1c>;
+ reg-names = "data", "dir", "intr";
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&vic1>;
+ interrupts = <27>;
+ };
+
+ gpio@80840004 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840004 0x04>,
+ <0x80840014 0x04>,
+ <0x808400ac 0x1c>;
+ reg-names = "data", "dir", "intr";
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&vic1>;
+ interrupts = <27>;
+ };
+
+ gpio@80840008 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840008 0x04>,
+ <0x80840018 0x04>;
+ reg-names = "data", "dir";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ gpio@8084000c {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x8084000c 0x04>,
+ <0x8084001c 0x04>;
+ reg-names = "data", "dir";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ gpio@80840020 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840020 0x04>,
+ <0x80840024 0x04>;
+ reg-names = "data", "dir";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ gpio@80840030 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840030 0x04>,
+ <0x80840034 0x04>,
+ <0x8084004c 0x1c>;
+ reg-names = "data", "dir", "intr";
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts-extended = <&vic0 19>, <&vic0 20>,
+ <&vic0 21>, <&vic0 22>,
+ <&vic1 15>, <&vic1 16>,
+ <&vic1 17>, <&vic1 18>;
+ };
+
+ gpio@80840038 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840038 0x04>,
+ <0x8084003c 0x04>;
+ reg-names = "data", "dir";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ gpio@80840040 {
+ compatible = "cirrus,ep9301-gpio";
+ reg = <0x80840040 0x04>,
+ <0x80840044 0x04>;
+ reg-names = "data", "dir";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/gpio-latch.yaml b/Documentation/devicetree/bindings/gpio/gpio-latch.yaml
new file mode 100644
index 000000000000..1ed82a2cebda
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-latch.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-latch.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO latch controller
+
+maintainers:
+ - Sascha Hauer <s.hauer@pengutronix.de>
+
+description: |
+ This binding describes a GPIO multiplexer based on latches connected to
+ other GPIOs, like this:
+
+ CLK0 ----------------------. ,--------.
+ CLK1 -------------------. `--------|> #0 |
+ | | |
+ OUT0 ----------------+--|-----------|D0 Q0|-----|<
+ OUT1 --------------+-|--|-----------|D1 Q1|-----|<
+ OUT2 ------------+-|-|--|-----------|D2 Q2|-----|<
+ OUT3 ----------+-|-|-|--|-----------|D3 Q3|-----|<
+ OUT4 --------+-|-|-|-|--|-----------|D4 Q4|-----|<
+ OUT5 ------+-|-|-|-|-|--|-----------|D5 Q5|-----|<
+ OUT6 ----+-|-|-|-|-|-|--|-----------|D6 Q6|-----|<
+ OUT7 --+-|-|-|-|-|-|-|--|-----------|D7 Q7|-----|<
+ | | | | | | | | | `--------'
+ | | | | | | | | |
+ | | | | | | | | | ,--------.
+ | | | | | | | | `-----------|> #1 |
+ | | | | | | | | | |
+ | | | | | | | `--------------|D0 Q0|-----|<
+ | | | | | | `----------------|D1 Q1|-----|<
+ | | | | | `------------------|D2 Q2|-----|<
+ | | | | `--------------------|D3 Q3|-----|<
+ | | | `----------------------|D4 Q4|-----|<
+ | | `------------------------|D5 Q5|-----|<
+ | `--------------------------|D6 Q6|-----|<
+ `----------------------------|D7 Q7|-----|<
+ `--------'
+
+ The number of clk-gpios and latched-gpios is not fixed. The actual number
+ of number of latches and the number of inputs per latch is derived from
+ the number of GPIOs given in the corresponding device tree properties.
+
+properties:
+ compatible:
+ const: gpio-latch
+ "#gpio-cells":
+ const: 2
+
+ clk-gpios:
+ description: Array of GPIOs to be used to clock a latch
+
+ latched-gpios:
+ description: Array of GPIOs to be used as inputs per latch
+
+ setup-duration-ns:
+ description: Delay in nanoseconds to wait after the latch inputs have been
+ set up
+
+ clock-duration-ns:
+ description: Delay in nanoseconds to wait between clock output changes
+
+ gpio-controller: true
+
+ gpio-line-names: true
+
+required:
+ - compatible
+ - "#gpio-cells"
+ - gpio-controller
+ - clk-gpios
+ - latched-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio-latch {
+ #gpio-cells = <2>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_di_do_leds>;
+ compatible = "gpio-latch";
+ gpio-controller;
+ setup-duration-ns = <100>;
+ clock-duration-ns = <100>;
+
+ clk-gpios = <&gpio3 7 0>, <&gpio3 8 0>;
+ latched-gpios = <&gpio3 21 0>, <&gpio3 22 0>,
+ <&gpio3 23 0>, <&gpio3 24 0>,
+ <&gpio3 25 0>, <&gpio3 26 0>,
+ <&gpio3 27 0>, <&gpio3 28 0>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-lp3943.txt b/Documentation/devicetree/bindings/gpio/gpio-lp3943.txt
deleted file mode 100644
index 80fcb7d70e13..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-lp3943.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-TI/National Semiconductor LP3943 GPIO controller
-
-Required properties:
- - compatible: "ti,lp3943-gpio"
- - gpio-controller: Marks the device node as a GPIO controller.
- - #gpio-cells: Should be 2. See gpio.txt in this directory for a
- description of the cells format.
-
-Example:
-Simple LED controls with LP3943 GPIO controller
-
-&i2c4 {
- lp3943@60 {
- compatible = "ti,lp3943";
- reg = <0x60>;
-
- gpioex: gpio {
- compatible = "ti,lp3943-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- };
- };
-};
-
-leds {
- compatible = "gpio-leds";
- indicator1 {
- label = "indi1";
- gpios = <&gpioex 9 GPIO_ACTIVE_LOW>;
- };
-
- indicator2 {
- label = "indi2";
- gpios = <&gpioex 10 GPIO_ACTIVE_LOW>;
- default-state = "off";
- };
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-max3191x.txt b/Documentation/devicetree/bindings/gpio/gpio-max3191x.txt
deleted file mode 100644
index b3a6444b8f45..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-max3191x.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-GPIO driver for Maxim MAX3191x industrial serializer
-
-Required properties:
- - compatible: Must be one of:
- "maxim,max31910"
- "maxim,max31911"
- "maxim,max31912"
- "maxim,max31913"
- "maxim,max31953"
- "maxim,max31963"
- - reg: Chip select number.
- - gpio-controller: Marks the device node as a GPIO controller.
- - #gpio-cells: Should be two. For consumer use see gpio.txt.
-
-Optional properties:
- - #daisy-chained-devices:
- Number of chips in the daisy-chain (default is 1).
- - maxim,modesel-gpios: GPIO pins to configure modesel of each chip.
- The number of GPIOs must equal "#daisy-chained-devices"
- (if each chip is driven by a separate pin) or 1
- (if all chips are wired to the same pin).
- - maxim,fault-gpios: GPIO pins to read fault of each chip.
- The number of GPIOs must equal "#daisy-chained-devices"
- or 1.
- - maxim,db0-gpios: GPIO pins to configure debounce of each chip.
- The number of GPIOs must equal "#daisy-chained-devices"
- or 1.
- - maxim,db1-gpios: GPIO pins to configure debounce of each chip.
- The number of GPIOs must equal "maxim,db0-gpios".
- - maxim,modesel-8bit: Boolean whether the modesel pin of the chips is
- pulled high (8-bit mode). Use this if the modesel pin
- is hardwired and consequently "maxim,modesel-gpios"
- cannot be specified. By default if neither this nor
- "maxim,modesel-gpios" is given, the driver assumes
- that modesel is pulled low (16-bit mode).
- - maxim,ignore-undervoltage:
- Boolean whether to ignore undervoltage alarms signaled
- by the "maxim,fault-gpios" or by the status byte
- (in 16-bit mode). Use this if the chips are powered
- through 5VOUT instead of VCC24V, in which case they
- will constantly signal undervoltage.
-
-For other required and optional properties of SPI slave nodes please refer to
-../spi/spi-bus.txt.
-
-Example:
- gpio@0 {
- compatible = "maxim,max31913";
- reg = <0>;
- gpio-controller;
- #gpio-cells = <2>;
-
- maxim,modesel-gpios = <&gpio2 23>;
- maxim,fault-gpios = <&gpio2 24 GPIO_ACTIVE_LOW>;
- maxim,db0-gpios = <&gpio2 25>;
- maxim,db1-gpios = <&gpio2 26>;
-
- spi-max-frequency = <25000000>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-max77620.txt b/Documentation/devicetree/bindings/gpio/gpio-max77620.txt
deleted file mode 100644
index 410e716fd3d2..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-max77620.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-GPIO driver for MAX77620 Power management IC from Maxim Semiconductor.
-
-Device has 8 GPIO pins which can be configured as GPIO as well as the
-special IO functions.
-
-Required properties:
--------------------
-- gpio-controller : Marks the device node as a gpio controller.
-- #gpio-cells : Should be two. The first cell is the pin number and
- the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-For more details, please refer generic GPIO DT binding document
-<devicetree/bindings/gpio/gpio.txt>.
-
-Example:
---------
-#include <dt-bindings/mfd/max77620.h>
-...
-max77620@3c {
- compatible = "maxim,max77620";
-
- gpio-controller;
- #gpio-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mm-lantiq.txt b/Documentation/devicetree/bindings/gpio/gpio-mm-lantiq.txt
deleted file mode 100644
index f93d51478d5a..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-mm-lantiq.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-Lantiq SoC External Bus memory mapped GPIO controller
-
-By attaching hardware latches to the EBU it is possible to create output
-only gpios. This driver configures a special memory address, which when
-written to outputs 16 bit to the latches.
-
-The node describing the memory mapped GPIOs needs to be a child of the node
-describing the "lantiq,localbus".
-
-Required properties:
-- compatible : Should be "lantiq,gpio-mm-lantiq"
-- reg : Address and length of the register set for the device
-- #gpio-cells : Should be two. The first cell is the pin number and
- the second cell is used to specify optional parameters (currently
- unused).
-- gpio-controller : Marks the device node as a gpio controller.
-
-Optional properties:
-- lantiq,shadow : The default value that we shall assume as already set on the
- shift register cascade.
-
-Example:
-
-localbus@0 {
- #address-cells = <2>;
- #size-cells = <1>;
- ranges = <0 0 0x0 0x3ffffff /* addrsel0 */
- 1 0 0x4000000 0x4000010>; /* addsel1 */
- compatible = "lantiq,localbus", "simple-bus";
-
- gpio_mm0: gpio@4000000 {
- compatible = "lantiq,gpio-mm";
- reg = <1 0x0 0x10>;
- gpio-controller;
- #gpio-cells = <2>;
- lantiq,shadow = <0x77f>
- };
-}
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mmio.yaml b/Documentation/devicetree/bindings/gpio/gpio-mmio.yaml
new file mode 100644
index 000000000000..b4d55bf6a285
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-mmio.yaml
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-mmio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic MMIO GPIO
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+ - Bartosz Golaszewski <brgl@bgdev.pl>
+
+description:
+ Some simple GPIO controllers may consist of a single data register or a pair
+ of set/clear-bit registers. Such controllers are common for glue logic in
+ FPGAs or ASICs. Commonly, these controllers are accessed over memory-mapped
+ NAND-style parallel busses.
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm6345-gpio
+ - ni,169445-nand-gpio
+ - wd,mbl-gpio # Western Digital MyBook Live memory-mapped GPIO controller
+ - intel,ixp4xx-expansion-bus-mmio-gpio
+
+ big-endian: true
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+ little-endian: true
+
+ reg:
+ minItems: 1
+ description:
+ A list of registers in the controller. The width of each register is
+ determined by its size. All registers must have the same width. The number
+ of GPIOs is set by the width, with bit 0 corresponding to GPIO 0, unless
+ the ngpios property further restricts the number of used lines.
+ items:
+ - description:
+ Register to READ the value of the GPIO lines. If GPIO line is high,
+ the bit will be set. If the GPIO line is low, the bit will be cleared.
+ This register may also be used to drive GPIOs if the SET register is
+ omitted.
+ - description:
+ Register to SET the value of the GPIO lines. Setting a bit in this
+ register will drive the GPIO line high.
+ - description:
+ Register to CLEAR the value of the GPIO lines. Setting a bit in this
+ register will drive the GPIO line low. If this register is omitted,
+ the SET register will be used to clear the GPIO lines as well, by
+ actively writing the line with 0.
+ - description:
+ Register to set the line as OUTPUT. Setting a bit in this register
+ will turn that line into an output line. Conversely, clearing a bit
+ will turn that line into an input.
+ - description:
+ Register to set this line as INPUT. Setting a bit in this register
+ will turn that line into an input line. Conversely, clearing a bit
+ will turn that line into an output.
+
+ reg-names:
+ minItems: 1
+ maxItems: 5
+ items:
+ enum:
+ - dat
+ - set
+ - clr
+ - dirout
+ - dirin
+
+ native-endian: true
+
+ ngpios:
+ minimum: 1
+ maximum: 63
+ description:
+ If this property is present the number of usable GPIO lines are restricted
+ to the first 0 .. ngpios lines. This is useful when the GPIO MMIO register
+ has 32 bits for GPIO but only the first 12 are actually connected to
+ real electronics, and then we set ngpios to 12.
+
+ no-output:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ If this property is present, the controller cannot drive the GPIO lines.
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: intel,ixp4xx-expansion-bus-mmio-gpio
+then:
+ $ref: /schemas/memory-controllers/intel,ixp4xx-expansion-peripheral-props.yaml#
+
+patternProperties:
+ "^.+-hog(-[0-9]+)?$":
+ type: object
+ required:
+ - gpio-hog
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - '#gpio-cells'
+ - gpio-controller
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ gpio@1f300010 {
+ compatible = "ni,169445-nand-gpio";
+ reg = <0x1f300010 0x4>;
+ reg-names = "dat";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ gpio@e0100000 {
+ compatible = "wd,mbl-gpio";
+ reg-names = "dat";
+ reg = <0xe0100000 0x1>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ no-output;
+ };
+
+ gpio@fffe0406 {
+ compatible = "brcm,bcm6345-gpio";
+ reg-names = "dirout", "dat";
+ reg = <0xfffe0406 2>, <0xfffe040a 2>;
+ ngpios = <15>;
+ native-endian;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
+
+ bus@c4000000 {
+ compatible = "intel,ixp42x-expansion-bus-controller", "syscon";
+ reg = <0xc4000000 0x30>;
+ native-endian;
+ #address-cells = <2>;
+ #size-cells = <1>;
+ ranges = <0 0x0 0x50000000 0x01000000>;
+ dma-ranges = <0 0x0 0x50000000 0x01000000>;
+ gpio@1,0 {
+ compatible = "intel,ixp4xx-expansion-bus-mmio-gpio";
+ gpio-controller;
+ #gpio-cells = <2>;
+ big-endian;
+ reg = <1 0x00000000 0x2>;
+ reg-names = "dat";
+ intel,ixp4xx-eb-write-enable = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt b/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt
deleted file mode 100644
index 410759de9f09..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-moxtet.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-Turris Mox Moxtet GPIO expander via Moxtet bus
-
-Required properties:
- - compatible : Should be "cznic,moxtet-gpio".
- - gpio-controller : Marks the device node as a GPIO controller.
- - #gpio-cells : Should be two. For consumer use see gpio.txt.
-
-Other properties are required for a Moxtet bus device, please refer to
-Documentation/devicetree/bindings/bus/moxtet.txt.
-
-Example:
-
- moxtet_sfp: gpio@0 {
- compatible = "cznic,moxtet-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- reg = <0>;
- }
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt
deleted file mode 100644
index cd28e932bf50..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-* Freescale MPC512x/MPC8xxx/QorIQ/Layerscape GPIO controller
-
-Required properties:
-- compatible : Should be "fsl,<soc>-gpio"
- The following <soc>s are known to be supported:
- mpc5121, mpc5125, mpc8349, mpc8572, mpc8610, pq3, qoriq,
- ls1021a, ls1043a, ls2080a, ls1028a, ls1088a.
-- reg : Address and length of the register set for the device
-- interrupts : Should be the port interrupt shared by all 32 pins.
-- #gpio-cells : Should be two. The first cell is the pin number and
- the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-
-Optional properties:
-- little-endian : GPIO registers are used as little endian. If not
- present registers are used as big endian by default.
-
-Example of gpio-controller node for a mpc5125 SoC:
-
-gpio0: gpio@1100 {
- compatible = "fsl,mpc5125-gpio";
- #gpio-cells = <2>;
- reg = <0x1100 0x080>;
- interrupts = <78 0x8>;
-};
-
-Example of gpio-controller node for a ls2080a SoC:
-
-gpio0: gpio@2300000 {
- compatible = "fsl,ls2080a-gpio", "fsl,qoriq-gpio";
- reg = <0x0 0x2300000 0x0 0x10000>;
- interrupts = <0 36 0x4>; /* Level high type */
- gpio-controller;
- little-endian;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
-
-
-Example of gpio-controller node for a ls1028a/ls1088a SoC:
-
-gpio1: gpio@2300000 {
- compatible = "fsl,ls1028a-gpio", "fsl,ls1088a-gpio", "fsl,qoriq-gpio";
- reg = <0x0 0x2300000 0x0 0x10000>;
- interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- little-endian;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
deleted file mode 100644
index 0fc6700ed800..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-* Marvell EBU GPIO controller
-
-Required properties:
-
-- compatible : Should be "marvell,orion-gpio", "marvell,mv78200-gpio",
- "marvell,armadaxp-gpio" or "marvell,armada-8k-gpio".
-
- "marvell,orion-gpio" should be used for Orion, Kirkwood, Dove,
- Discovery (except MV78200) and Armada 370. "marvell,mv78200-gpio"
- should be used for the Discovery MV78200.
-
- "marvel,armadaxp-gpio" should be used for all Armada XP SoCs
- (MV78230, MV78260, MV78460).
-
- "marvell,armada-8k-gpio" should be used for the Armada 7K and 8K
- SoCs (either from AP or CP), see
- Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt
- for specific details about the offset property.
-
-- reg: Address and length of the register set for the device. Only one
- entry is expected, except for the "marvell,armadaxp-gpio" variant
- for which two entries are expected: one for the general registers,
- one for the per-cpu registers. Not used for marvell,armada-8k-gpio.
-
-- interrupts: The list of interrupts that are used for all the pins
- managed by this GPIO bank. There can be more than one interrupt
- (example: 1 interrupt per 8 pins on Armada XP, which means 4
- interrupts per bank of 32 GPIOs).
-
-- interrupt-controller: identifies the node as an interrupt controller
-
-- #interrupt-cells: specifies the number of cells needed to encode an
- interrupt source. Should be two.
- The first cell is the GPIO number.
- The second cell is used to specify flags:
- bits[3:0] trigger type and level flags:
- 1 = low-to-high edge triggered.
- 2 = high-to-low edge triggered.
- 4 = active high level-sensitive.
- 8 = active low level-sensitive.
-
-- gpio-controller: marks the device node as a gpio controller
-
-- ngpios: number of GPIOs this controller has
-
-- #gpio-cells: Should be two. The first cell is the pin number. The
- second cell is reserved for flags, unused at the moment.
-
-Optional properties:
-
-In order to use the GPIO lines in PWM mode, some additional optional
-properties are required.
-
-- compatible: Must contain "marvell,armada-370-gpio"
-
-- reg: an additional register set is needed, for the GPIO Blink
- Counter on/off registers.
-
-- reg-names: Must contain an entry "pwm" corresponding to the
- additional register range needed for PWM operation.
-
-- #pwm-cells: Should be two. The first cell is the GPIO line number. The
- second cell is the period in nanoseconds.
-
-- clocks: Must be a phandle to the clock for the GPIO controller.
-
-Example:
-
- gpio0: gpio@d0018100 {
- compatible = "marvell,armadaxp-gpio";
- reg = <0xd0018100 0x40>,
- <0xd0018800 0x30>;
- ngpios = <32>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <16>, <17>, <18>, <19>;
- };
-
- gpio1: gpio@18140 {
- compatible = "marvell,armada-370-gpio";
- reg = <0x18140 0x40>, <0x181c8 0x08>;
- reg-names = "gpio", "pwm";
- ngpios = <17>;
- gpio-controller;
- #gpio-cells = <2>;
- #pwm-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <87>, <88>, <89>;
- clocks = <&coreclk 0>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
new file mode 100644
index 000000000000..7ed5f9c4dde9
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-mvebu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell EBU GPIO controller
+
+maintainers:
+ - Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
+ - Andrew Lunn <andrew@lunn.ch>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - marvell,armada-8k-gpio
+ - marvell,orion-gpio
+
+ - items:
+ - enum:
+ - marvell,mv78200-gpio
+ - marvell,armada-370-gpio
+ - const: marvell,orion-gpio
+
+ - description: Deprecated binding
+ items:
+ - const: marvell,armadaxp-gpio
+ - const: marvell,orion-gpio
+ deprecated: true
+
+ reg:
+ description: |
+ Address and length of the register set for the device. Not used for
+ marvell,armada-8k-gpio.
+
+ A second entry can be provided, for the PWM function using the GPIO Blink
+ Counter on/off registers.
+ minItems: 1
+ maxItems: 2
+
+ reg-names:
+ items:
+ - const: gpio
+ - const: pwm
+ minItems: 1
+
+ offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Offset in the register map for the gpio registers (in bytes)
+
+ interrupts:
+ description: |
+ The list of interrupts that are used for all the pins managed by this
+ GPIO bank. There can be more than one interrupt (example: 1 interrupt
+ per 8 pins on Armada XP, which means 4 interrupts per bank of 32
+ GPIOs).
+ minItems: 1
+ maxItems: 4
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ gpio-controller: true
+
+ ngpios:
+ minimum: 1
+ maximum: 32
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-ranges:
+ maxItems: 1
+
+ marvell,pwm-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Offset in the register map for the pwm registers (in bytes)
+
+ "#pwm-cells":
+ description:
+ The first cell is the GPIO line number. The second cell is the period
+ in nanoseconds.
+ const: 2
+
+ clocks:
+ description:
+ Clock(s) used for PWM function.
+ items:
+ - description: Core clock
+ - description: AXI bus clock
+ minItems: 1
+
+ clock-names:
+ items:
+ - const: core
+ - const: axi
+ minItems: 1
+
+patternProperties:
+ "^(.+-hog(-[0-9]+)?)$":
+ type: object
+
+ required:
+ - gpio-hog
+
+required:
+ - compatible
+ - gpio-controller
+ - ngpios
+ - "#gpio-cells"
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: marvell,armada-8k-gpio
+ then:
+ required:
+ - offset
+ else:
+ required:
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ gpio@d0018100 {
+ compatible = "marvell,armadaxp-gpio", "marvell,orion-gpio";
+ reg = <0xd0018100 0x40>, <0xd0018800 0x30>;
+ ngpios = <32>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <16>, <17>, <18>, <19>;
+ };
+
+ - |
+ gpio@18140 {
+ compatible = "marvell,armada-370-gpio", "marvell,orion-gpio";
+ reg = <0x18140 0x40>, <0x181c8 0x08>;
+ reg-names = "gpio", "pwm";
+ ngpios = <17>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ #pwm-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <87>, <88>, <89>;
+ clocks = <&coreclk 0>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml b/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml
index dfa1133f8c5e..fed1b06495ad 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml
+++ b/Documentation/devicetree/bindings/gpio/gpio-mxs.yaml
@@ -8,7 +8,6 @@ title: Freescale MXS GPIO controller
maintainers:
- Shawn Guo <shawnguo@kernel.org>
- - Anson Huang <Anson.Huang@nxp.com>
description: |
The Freescale MXS GPIO controller is part of MXS PIN controller.
@@ -19,12 +18,17 @@ description: |
properties:
compatible:
- enum:
- - fsl,imx23-pinctrl
- - fsl,imx28-pinctrl
+ items:
+ - enum:
+ - fsl,imx23-pinctrl
+ - fsl,imx28-pinctrl
+ # Over 10 years old devices, driver use simple-bus to probe child gpio
+ # Devices. Keep it as it to be compatible existed dts files.
+ - const: simple-bus
'#address-cells':
const: 1
+
'#size-cells':
const: 0
@@ -32,7 +36,65 @@ properties:
maxItems: 1
patternProperties:
- "gpio@[0-9]+$":
+ '^(?!gpio@)[^@]+@[0-9]+$':
+ type: object
+ properties:
+ fsl,pinmux-ids:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: |
+ An integer array. Each integer in the array specify a pin
+ with given mux function, with bank, pin and mux packed as below.
+
+ [15..12] : bank number
+ [11..4] : pin number
+ [3..0] : mux selection
+
+ This integer with mux selection packed is used as an entity by both group
+ and config nodes to identify a pin. The mux selection in the integer takes
+ effects only on group node, and will get ignored by driver with config node,
+ since config node is only meant to set up pin configurations.
+
+ Valid values for these integers are listed below.
+
+ reg:
+ items:
+ - description: |
+ pin group index. NOTE: it is supposed wrong use reg property
+ here. But it is over 10 years devices. Just keep it as it.
+
+ fsl,drive-strength:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ description: |
+ 0: MXS_DRIVE_4mA
+ 1: MXS_DRIVE_8mA
+ 2: MXS_DRIVE_12mA
+ 3: MXS_DRIVE_16mA
+
+ fsl,voltage:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description: |
+ 0: MXS_VOLTAGE_LOW - 1.8 V
+ 1: MXS_VOLTAGE_HIGH - 3.3 V
+
+ fsl,pull-up:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description: |
+ 0: MXS_PULL_DISABLE - Disable the internal pull-up
+ 1: MXS_PULL_ENABLE - Enable the internal pull-up
+
+ Note that when enabling the pull-up, the internal pad keeper gets disabled.
+ Also, some pins doesn't have a pull up, in that case, setting the fsl,pull-up
+ will only disable the internal pad keeper.
+
+ required:
+ - fsl,pinmux-ids
+
+ additionalProperties: false
+
+ '^gpio@[0-9]+$':
type: object
properties:
compatible:
@@ -49,10 +111,10 @@ patternProperties:
interrupt-controller: true
- "#interrupt-cells":
+ '#interrupt-cells':
const: 2
- "#gpio-cells":
+ '#gpio-cells':
const: 2
gpio-controller: true
@@ -62,8 +124,8 @@ patternProperties:
- reg
- interrupts
- interrupt-controller
- - "#interrupt-cells"
- - "#gpio-cells"
+ - '#interrupt-cells'
+ - '#gpio-cells'
- gpio-controller
additionalProperties: false
@@ -81,56 +143,64 @@ examples:
pinctrl@80018000 {
#address-cells = <1>;
#size-cells = <0>;
- compatible = "fsl,imx28-pinctrl";
+ compatible = "fsl,imx28-pinctrl", "simple-bus";
reg = <0x80018000 0x2000>;
gpio@0 {
- compatible = "fsl,imx28-gpio";
- reg = <0>;
- interrupts = <127>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "fsl,imx28-gpio";
+ reg = <0>;
+ interrupts = <127>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
gpio@1 {
- compatible = "fsl,imx28-gpio";
- reg = <1>;
- interrupts = <126>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "fsl,imx28-gpio";
+ reg = <1>;
+ interrupts = <126>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
gpio@2 {
- compatible = "fsl,imx28-gpio";
- reg = <2>;
- interrupts = <125>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "fsl,imx28-gpio";
+ reg = <2>;
+ interrupts = <125>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
gpio@3 {
- compatible = "fsl,imx28-gpio";
- reg = <3>;
- interrupts = <124>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "fsl,imx28-gpio";
+ reg = <3>;
+ interrupts = <124>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
gpio@4 {
- compatible = "fsl,imx28-gpio";
- reg = <4>;
- interrupts = <123>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "fsl,imx28-gpio";
+ reg = <4>;
+ interrupts = <123>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+
+ lcdif-apx4@5 {
+ reg = <5>;
+ fsl,pinmux-ids = <0x1181 0x1191>;
+ fsl,drive-strength = <0>;
+ fsl,voltage = <0>;
+ fsl,pull-up = <0>;
};
};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-nmk.txt b/Documentation/devicetree/bindings/gpio/gpio-nmk.txt
deleted file mode 100644
index 8315ac7780ef..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-nmk.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-Nomadik GPIO controller
-
-Required properties:
-- compatible : Should be "st,nomadik-gpio".
-- reg : Physical base address and length of the controller's registers.
-- interrupts : The interrupt outputs from the controller.
-- #gpio-cells : Should be two:
- The first cell is the pin number.
- The second cell is used to specify optional parameters:
- - bits[3:0] trigger type and level flags:
- 1 = low-to-high edge triggered.
- 2 = high-to-low edge triggered.
- 4 = active high level-sensitive.
- 8 = active low level-sensitive.
-- gpio-controller : Marks the device node as a GPIO controller.
-- interrupt-controller : Marks the device node as an interrupt controller.
-- gpio-bank : Specifies which bank a controller owns.
-- st,supports-sleepmode : Specifies whether controller can sleep or not
-
-Example:
-
- gpio1: gpio@8012e080 {
- compatible = "st,nomadik-gpio";
- reg = <0x8012e080 0x80>;
- interrupts = <0 120 0x4>;
- #gpio-cells = <2>;
- gpio-controller;
- interrupt-controller;
- st,supports-sleepmode;
- gpio-bank = <1>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-palmas.txt b/Documentation/devicetree/bindings/gpio/gpio-palmas.txt
deleted file mode 100644
index 08b5b52a3ae0..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-palmas.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Palmas GPIO controller bindings
-
-Required properties:
-- compatible:
- - "ti,palams-gpio" for palma series of the GPIO controller
- - "ti,tps80036-gpio" for Palma series device TPS80036.
- - "ti,tps65913-gpio" for palma series device TPS65913.
- - "ti,tps65914-gpio" for palma series device TPS65914.
-- #gpio-cells : Should be two.
- - first cell is the gpio pin number
- - second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-- gpio-controller : Marks the device node as a GPIO controller.
-
-Note: This gpio node will be sub node of palmas node.
-
-Example:
- palmas: tps65913@58 {
- :::::::::::
- palmas_gpio: palmas_gpio {
- compatible = "ti,palmas-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- };
- :::::::::::
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml
deleted file mode 100644
index 338c5312a106..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml
+++ /dev/null
@@ -1,47 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/gpio/gpio-pca9570.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: PCA9570 I2C GPO expander
-
-maintainers:
- - Sungbo Eo <mans0n@gorani.run>
-
-properties:
- compatible:
- enum:
- - nxp,pca9570
-
- reg:
- maxItems: 1
-
- gpio-controller: true
-
- '#gpio-cells':
- const: 2
-
-required:
- - compatible
- - reg
- - gpio-controller
- - "#gpio-cells"
-
-additionalProperties: false
-
-examples:
- - |
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- gpio@24 {
- compatible = "nxp,pca9570";
- reg = <0x24>;
- gpio-controller;
- #gpio-cells = <2>;
- };
- };
-
-...
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml
index b6a6e742b66d..12134c737ad8 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml
+++ b/Documentation/devicetree/bindings/gpio/gpio-pca95xx.yaml
@@ -15,51 +15,65 @@ description: |+
properties:
compatible:
- enum:
- - exar,xra1202
- - maxim,max7310
- - maxim,max7312
- - maxim,max7313
- - maxim,max7315
- - maxim,max7319
- - maxim,max7320
- - maxim,max7321
- - maxim,max7322
- - maxim,max7323
- - maxim,max7324
- - maxim,max7325
- - maxim,max7326
- - maxim,max7327
- - nxp,pca6416
- - nxp,pca9505
- - nxp,pca9506
- - nxp,pca9534
- - nxp,pca9535
- - nxp,pca9536
- - nxp,pca9537
- - nxp,pca9538
- - nxp,pca9539
- - nxp,pca9554
- - nxp,pca9555
- - nxp,pca9556
- - nxp,pca9557
- - nxp,pca9574
- - nxp,pca9575
- - nxp,pca9698
- - nxp,pcal6416
- - nxp,pcal6524
- - nxp,pcal9535
- - nxp,pcal9554b
- - nxp,pcal9555a
- - onnn,cat9554
- - onnn,pca9654
- - ti,pca6107
- - ti,pca9536
- - ti,tca6408
- - ti,tca6416
- - ti,tca6424
- - ti,tca9539
- - ti,tca9554
+ oneOf:
+ - items:
+ - const: toradex,ecgpiol16
+ - const: nxp,pcal6416
+ - items:
+ - const: diodes,pi4ioe5v6534q
+ - const: nxp,pcal6534
+ - items:
+ - enum:
+ - exar,xra1202
+ - maxim,max7310
+ - maxim,max7312
+ - maxim,max7313
+ - maxim,max7315
+ - maxim,max7319
+ - maxim,max7320
+ - maxim,max7321
+ - maxim,max7322
+ - maxim,max7323
+ - maxim,max7324
+ - maxim,max7325
+ - maxim,max7326
+ - maxim,max7327
+ - nxp,pca6408
+ - nxp,pca6416
+ - nxp,pca9505
+ - nxp,pca9506
+ - nxp,pca9534
+ - nxp,pca9535
+ - nxp,pca9536
+ - nxp,pca9537
+ - nxp,pca9538
+ - nxp,pca9539
+ - nxp,pca9554
+ - nxp,pca9555
+ - nxp,pca9556
+ - nxp,pca9557
+ - nxp,pca9574
+ - nxp,pca9575
+ - nxp,pca9698
+ - nxp,pcal6408
+ - nxp,pcal6416
+ - nxp,pcal6524
+ - nxp,pcal6534
+ - nxp,pcal9535
+ - nxp,pcal9554b
+ - nxp,pcal9555a
+ - onnn,cat9554
+ - onnn,pca9654
+ - ti,pca6107
+ - ti,pca9536
+ - ti,tca6408
+ - ti,tca6416
+ - ti,tca6418
+ - ti,tca6424
+ - ti,tca9535
+ - ti,tca9538
+ - ti,tca9539
+ - ti,tca9554
reg:
maxItems: 1
@@ -97,19 +111,8 @@ properties:
patternProperties:
"^(hog-[0-9]+|.+-hog(-[0-9]+)?)$":
type: object
- properties:
- gpio-hog: true
- gpios: true
- input: true
- output-high: true
- output-low: true
- line-name: true
-
required:
- gpio-hog
- - gpios
-
- additionalProperties: false
required:
- compatible
@@ -133,6 +136,7 @@ allOf:
- maxim,max7325
- maxim,max7326
- maxim,max7327
+ - toradex,ecgpiol16
then:
properties:
reset-gpios: false
@@ -143,7 +147,7 @@ examples:
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -169,7 +173,7 @@ examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- i2c1 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -190,20 +194,12 @@ examples:
"chg-status+red", "green", "blue", "en-esata",
"fault1", "p26", "p27";
};
-
- ts3a227@3b {
- compatible = "ti,ts3a227e";
- reg = <0x3b>;
- interrupt-parent = <&gpio99>;
- interrupts = <14 IRQ_TYPE_EDGE_RISING>;
- ti,micbias = <0>; /* 2.1V */
- };
};
- |
#include <dt-bindings/interrupt-controller/irq.h>
- i2c2 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -221,7 +217,7 @@ examples:
};
- |
- i2c3 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pisosr.txt b/Documentation/devicetree/bindings/gpio/gpio-pisosr.txt
deleted file mode 100644
index 414a01cdf715..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-pisosr.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-Generic Parallel-in/Serial-out Shift Register GPIO Driver
-
-This binding describes generic parallel-in/serial-out shift register
-devices that can be used for GPI (General Purpose Input). This includes
-SN74165 serial-out shift registers and the SN65HVS88x series of
-industrial serializers.
-
-Required properties:
- - compatible : Should be "pisosr-gpio".
- - gpio-controller : Marks the device node as a GPIO controller.
- - #gpio-cells : Should be two. For consumer use see gpio.txt.
-
-Optional properties:
- - ngpios : Number of used GPIO lines (0..n-1), default is 8.
- - load-gpios : GPIO pin specifier attached to load enable, this
- pin is pulsed before reading from the device to
- load input pin values into the the device.
-
-For other required and optional properties of SPI slave
-nodes please refer to ../spi/spi-bus.txt.
-
-Example:
-
- gpio@0 {
- compatible = "ti,sn65hvs882", "pisosr-gpio";
- gpio-controller;
- #gpio-cells = <2>;
-
- load-gpios = <&gpio2 23 GPIO_ACTIVE_LOW>;
-
- reg = <0>;
- spi-max-frequency = <1000000>;
- spi-cpol;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt b/Documentation/devicetree/bindings/gpio/gpio-samsung.txt
deleted file mode 100644
index 5375625e8cd2..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Samsung Exynos4 GPIO Controller
-
-Required properties:
-- compatible: Compatible property value should be "samsung,exynos4-gpio>".
-
-- reg: Physical base address of the controller and length of memory mapped
- region.
-
-- #gpio-cells: Should be 4. The syntax of the gpio specifier used by client nodes
- should be the following with values derived from the SoC user manual.
- <[phandle of the gpio controller node]
- [pin number within the gpio controller]
- [mux function]
- [flags and pull up/down]
- [drive strength]>
-
- Values for gpio specifier:
- - Pin number: is a value between 0 to 7.
- - Flags and Pull Up/Down: 0 - Pull Up/Down Disabled.
- 1 - Pull Down Enabled.
- 3 - Pull Up Enabled.
- Bit 16 (0x00010000) - Input is active low.
- - Drive Strength: 0 - 1x,
- 1 - 3x,
- 2 - 2x,
- 3 - 4x
-
-- gpio-controller: Specifies that the node is a gpio controller.
-- #address-cells: should be 1.
-- #size-cells: should be 1.
-
-Example:
-
- gpa0: gpio-controller@11400000 {
- #address-cells = <1>;
- #size-cells = <1>;
- compatible = "samsung,exynos4-gpio";
- reg = <0x11400000 0x20>;
- #gpio-cells = <4>;
- gpio-controller;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-sprd.txt
deleted file mode 100644
index eca97d45388f..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-sprd.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Spreadtrum GPIO controller bindings
-
-The controller's registers are organized as sets of sixteen 16-bit
-registers with each set controlling a bank of up to 16 pins. A single
-interrupt is shared for all of the banks handled by the controller.
-
-Required properties:
-- compatible: Should be "sprd,sc9860-gpio".
-- reg: Define the base and range of the I/O address space containing
-the GPIO controller registers.
-- gpio-controller: Marks the device node as a GPIO controller.
-- #gpio-cells: Should be <2>. The first cell is the gpio number and
-the second cell is used to specify optional parameters.
-- interrupt-controller: Marks the device node as an interrupt controller.
-- #interrupt-cells: Should be <2>. Specifies the number of cells needed
-to encode interrupt source.
-- interrupts: Should be the port interrupt shared by all the gpios.
-
-Example:
- ap_gpio: gpio@40280000 {
- compatible = "sprd,sc9860-gpio";
- reg = <0 0x40280000 0 0x1000>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-stmpe.txt b/Documentation/devicetree/bindings/gpio/gpio-stmpe.txt
deleted file mode 100644
index a0e4cf885213..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-stmpe.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-STMPE gpio
-----------
-
-Required properties:
- - compatible: "st,stmpe-gpio"
-
-Optional properties:
- - st,norequest-mask: bitmask specifying which GPIOs should _not_ be requestable
- due to different usage (e.g. touch, keypad)
-
-Node name must be stmpe_gpio and should be child node of stmpe node to which it
-belongs.
-
-Example:
- stmpe_gpio {
- compatible = "st,stmpe-gpio";
- st,norequest-mask = <0x20>; //gpio 5 can't be used
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-tpic2810.txt b/Documentation/devicetree/bindings/gpio/gpio-tpic2810.txt
deleted file mode 100644
index 1afc2de7a537..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-tpic2810.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-TPIC2810 GPIO controller bindings
-
-Required properties:
- - compatible : Should be "ti,tpic2810".
- - reg : The I2C address of the device
- - gpio-controller : Marks the device node as a GPIO controller.
- - #gpio-cells : Should be two. For consumer use see gpio.txt.
-
-Example:
-
- gpio@60 {
- compatible = "ti,tpic2810";
- reg = <0x60>;
- gpio-controller;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-ts4800.txt b/Documentation/devicetree/bindings/gpio/gpio-ts4800.txt
deleted file mode 100644
index 92ea9c8f6399..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-ts4800.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-* TS-4800 FPGA's GPIO controller bindings
-
-Required properties:
-- compatible: Must be "technologic,ts4800-gpio".
-- #gpio-cells: Should be two. The first cell is the pin number.
-- reg: Physical base address of the controller and length
- of memory mapped region.
-
-Optional property:
-- ngpios: See "gpio.txt"
-
-Example:
-
-gpio1: gpio {
- compatible = "technologic,ts4800-gpio";
- reg = <0x10020 0x6>;
- ngpios = <8>;
- gpio-controller;
- #gpio-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-ts4900.txt b/Documentation/devicetree/bindings/gpio/gpio-ts4900.txt
deleted file mode 100644
index 3f8e71b1ab2a..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-ts4900.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-* Technologic Systems I2C-FPGA's GPIO controller bindings
-
-This bindings describes the GPIO controller for Technologic's FPGA core.
-TS-4900's FPGA encodes the GPIO state on 3 bits, whereas the TS-7970's FPGA
-uses 2 bits: it doesn't use a dedicated input bit.
-
-Required properties:
-- compatible: Should be one of the following
- "technologic,ts4900-gpio"
- "technologic,ts7970-gpio"
-- reg: Physical base address of the controller and length
- of memory mapped region.
-- #gpio-cells: Should be two. The first cell is the pin number.
-- gpio-controller: Marks the device node as a gpio controller.
-
-Optional property:
-- ngpios: Number of GPIOs this controller is instantiated with,
- the default is 32. See gpio.txt for more details.
-
-Example:
-
-&i2c2 {
- gpio8: gpio@28 {
- compatible = "technologic,ts4900-gpio";
- reg = <0x28>;
- #gpio-cells = <2>;
- gpio-controller;
- ngpios = <32>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt b/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt
deleted file mode 100644
index 66788fda1db3..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-twl4030 GPIO controller bindings
-
-Required properties:
-- compatible:
- - "ti,twl4030-gpio" for twl4030 GPIO controller
-- #gpio-cells : Should be two.
- - first cell is the pin number
- - second cell is used to specify optional parameters (unused)
-- gpio-controller : Marks the device node as a GPIO controller.
-- #interrupt-cells : Should be 2.
-- interrupt-controller: Mark the device node as an interrupt controller
- The first cell is the GPIO number.
- The second cell is not used.
-- ti,use-leds : Enables LEDA and LEDB outputs if set
-- ti,debounce : if n-th bit is set, debounces GPIO-n
-- ti,mmc-cd : if n-th bit is set, GPIO-n controls VMMC(n+1)
-- ti,pullups : if n-th bit is set, set a pullup on GPIO-n
-- ti,pulldowns : if n-th bit is set, set a pulldown on GPIO-n
-
-Example:
-
-twl_gpio: gpio {
- compatible = "ti,twl4030-gpio";
- #gpio-cells = <2>;
- gpio-controller;
- #interrupt-cells = <2>;
- interrupt-controller;
- ti,use-leds;
-};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml
index 19738a457a58..a31f64b6d40b 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml
+++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml
@@ -20,18 +20,27 @@ description: |
properties:
compatible:
oneOf:
+ - const: fsl,imx8ulp-gpio
- const: fsl,vf610-gpio
- items:
- const: fsl,imx7ulp-gpio
- const: fsl,vf610-gpio
+ - items:
+ - enum:
+ - fsl,imx93-gpio
+ - fsl,imx94-gpio
+ - fsl,imx95-gpio
+ - const: fsl,imx8ulp-gpio
reg:
- description: The first reg tuple represents the PORT module, the second tuple
- represents the GPIO module.
+ minItems: 1
maxItems: 2
interrupts:
- maxItems: 1
+ items:
+ - description: GPIO Trustzone non-secure interrupt number
+ - description: GPIO Trustzone secure interrupt number
+ minItems: 1
interrupt-controller: true
@@ -43,6 +52,10 @@ properties:
gpio-controller: true
+ gpio-line-names:
+ minItems: 1
+ maxItems: 32
+
clocks:
items:
- description: SoC GPIO clock
@@ -54,7 +67,22 @@ properties:
- const: port
gpio-ranges:
- maxItems: 1
+ minItems: 1
+ maxItems: 4
+
+ gpio-reserved-ranges: true
+
+ ngpios:
+ minimum: 1
+ maximum: 32
+ default: 32
+
+patternProperties:
+ "^.+-hog(-[0-9]+)?$":
+ type: object
+
+ required:
+ - gpio-hog
required:
- compatible
@@ -65,6 +93,30 @@ required:
- "#gpio-cells"
- gpio-controller
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,vf610-gpio
+ - fsl,imx7ulp-gpio
+ then:
+ properties:
+ interrupts:
+ maxItems: 1
+ reg:
+ items:
+ - description: PORT register base address
+ - description: GPIO register base address
+ else:
+ properties:
+ interrupts:
+ minItems: 2
+ reg:
+ items:
+ - description: GPIO register base address
+
additionalProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/gpio/gpio-virtio.yaml b/Documentation/devicetree/bindings/gpio/gpio-virtio.yaml
new file mode 100644
index 000000000000..601d85754577
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-virtio.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/gpio-virtio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Virtio GPIO controller
+
+maintainers:
+ - Viresh Kumar <viresh.kumar@linaro.org>
+
+allOf:
+ - $ref: /schemas/virtio/virtio-device.yaml#
+
+description:
+ Virtio GPIO controller, see /schemas/virtio/virtio-device.yaml for more
+ details.
+
+properties:
+ $nodename:
+ const: gpio
+
+ compatible:
+ const: virtio,device29
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+required:
+ - compatible
+ - gpio-controller
+ - "#gpio-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ virtio@3000 {
+ compatible = "virtio,mmio";
+ reg = <0x3000 0x100>;
+ interrupts = <41>;
+
+ gpio {
+ compatible = "virtio,device29";
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt
deleted file mode 100644
index e90fb987e25f..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-APM X-Gene Standby GPIO controller bindings
-
-This is a gpio controller in the standby domain. It also supports interrupt in
-some particular pins which are sourced to its parent interrupt controller
-as diagram below:
- +-----------------+
- | X-Gene standby |
- | GPIO controller +------ GPIO_0
-+------------+ | | ...
-| Parent IRQ | EXT_INT_0 | +------ GPIO_8/EXT_INT_0
-| controller | (SPI40) | | ...
-| (GICv2) +--------------+ +------ GPIO_[N+8]/EXT_INT_N
-| | ... | |
-| | EXT_INT_N | +------ GPIO_[N+9]
-| | (SPI[40 + N])| | ...
-| +--------------+ +------ GPIO_MAX
-+------------+ +-----------------+
-
-Required properties:
-- compatible: "apm,xgene-gpio-sb" for the X-Gene Standby GPIO controller
-- reg: Physical base address and size of the controller's registers
-- #gpio-cells: Should be two.
- - first cell is the pin number
- - second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-- gpio-controller: Marks the device node as a GPIO controller.
-- interrupts: The EXT_INT_0 parent interrupt resource must be listed first.
-- interrupt-cells: Should be two.
- - first cell is 0-N coresponding for EXT_INT_0 to EXT_INT_N.
- - second cell is used to specify flags.
-- interrupt-controller: Marks the device node as an interrupt controller.
-- apm,nr-gpios: Optional, specify number of gpios pin.
-- apm,nr-irqs: Optional, specify number of interrupt pins.
-- apm,irq-start: Optional, specify lowest gpio pin support interrupt.
-
-Example:
- sbgpio: gpio@17001000{
- compatible = "apm,xgene-gpio-sb";
- reg = <0x0 0x17001000 0x0 0x400>;
- #gpio-cells = <2>;
- gpio-controller;
- interrupts = <0x0 0x28 0x1>,
- <0x0 0x29 0x1>,
- <0x0 0x2a 0x1>,
- <0x0 0x2b 0x1>,
- <0x0 0x2c 0x1>,
- <0x0 0x2d 0x1>;
- interrupt-parent = <&gic>;
- #interrupt-cells = <2>;
- interrupt-controller;
- apm,nr-gpios = <22>;
- apm,nr-irqs = <6>;
- apm,irq-start = <8>;
- };
-
- testuser {
- compatible = "example,testuser";
- /* Use the GPIO_13/EXT_INT_5 line as an active high triggered
- * level interrupt
- */
- interrupts = <5 4>;
- interrupt-parent = <&sbgpio>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-xgene.txt b/Documentation/devicetree/bindings/gpio/gpio-xgene.txt
deleted file mode 100644
index 86dbb05e7758..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-xgene.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-APM X-Gene SoC GPIO controller bindings
-
-This is a gpio controller that is part of the flash controller.
-This gpio controller controls a total of 48 gpios.
-
-Required properties:
-- compatible: "apm,xgene-gpio" for X-Gene GPIO controller
-- reg: Physical base address and size of the controller's registers
-- #gpio-cells: Should be two.
- - first cell is the pin number
- - second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-- gpio-controller: Marks the device node as a GPIO controller.
-
-Example:
- gpio0: gpio0@1701c000 {
- compatible = "apm,xgene-gpio";
- reg = <0x0 0x1701c000 0x0 0x40>;
- gpio-controller;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt b/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt
deleted file mode 100644
index e506f30e1a95..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-xilinx.txt
+++ /dev/null
@@ -1,48 +0,0 @@
-Xilinx plb/axi GPIO controller
-
-Dual channel GPIO controller with configurable number of pins
-(from 1 to 32 per channel). Every pin can be configured as
-input/output/tristate. Both channels share the same global IRQ but
-local interrupts can be enabled on channel basis.
-
-Required properties:
-- compatible : Should be "xlnx,xps-gpio-1.00.a"
-- reg : Address and length of the register set for the device
-- #gpio-cells : Should be two. The first cell is the pin number and the
- second cell is used to specify optional parameters (currently unused).
-- gpio-controller : Marks the device node as a GPIO controller.
-
-Optional properties:
-- clocks : Input clock specifier. Refer to common clock bindings.
-- interrupts : Interrupt mapping for GPIO IRQ.
-- xlnx,all-inputs : if n-th bit is setup, GPIO-n is input
-- xlnx,dout-default : if n-th bit is 1, GPIO-n default value is 1
-- xlnx,gpio-width : gpio width
-- xlnx,tri-default : if n-th bit is 1, GPIO-n is in tristate mode
-- xlnx,is-dual : if 1, controller also uses the second channel
-- xlnx,all-inputs-2 : as above but for the second channel
-- xlnx,dout-default-2 : as above but the second channel
-- xlnx,gpio2-width : as above but for the second channel
-- xlnx,tri-default-2 : as above but for the second channel
-
-
-Example:
-gpio: gpio@40000000 {
- #gpio-cells = <2>;
- compatible = "xlnx,xps-gpio-1.00.a";
- clocks = <&clkc25>;
- gpio-controller ;
- interrupt-parent = <&microblaze_0_intc>;
- interrupts = < 6 2 >;
- reg = < 0x40000000 0x10000 >;
- xlnx,all-inputs = <0x0>;
- xlnx,all-inputs-2 = <0x0>;
- xlnx,dout-default = <0x0>;
- xlnx,dout-default-2 = <0x0>;
- xlnx,gpio-width = <0x2>;
- xlnx,gpio2-width = <0x2>;
- xlnx,interrupt-present = <0x1>;
- xlnx,is-dual = <0x1>;
- xlnx,tri-default = <0xffffffff>;
- xlnx,tri-default-2 = <0xffffffff>;
-} ;
diff --git a/Documentation/devicetree/bindings/gpio/gpio-xlp.txt b/Documentation/devicetree/bindings/gpio/gpio-xlp.txt
deleted file mode 100644
index 47fc64922fe0..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-xlp.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-Netlogic XLP Family GPIO
-========================
-
-This GPIO driver is used for following Netlogic XLP SoCs:
- XLP832, XLP316, XLP208, XLP980, XLP532
-This GPIO driver is also compatible with GPIO controller found on
-Broadcom Vulcan ARM64.
-
-Required properties:
--------------------
-
-- compatible: Should be one of the following:
- - "netlogic,xlp832-gpio": For Netlogic XLP832
- - "netlogic,xlp316-gpio": For Netlogic XLP316
- - "netlogic,xlp208-gpio": For Netlogic XLP208
- - "netlogic,xlp980-gpio": For Netlogic XLP980
- - "netlogic,xlp532-gpio": For Netlogic XLP532
- - "brcm,vulcan-gpio": For Broadcom Vulcan ARM64
-- reg: Physical base address and length of the controller's registers.
-- #gpio-cells: Should be two. The first cell is the pin number and the second
- cell is used to specify optional parameters (currently unused).
-- gpio-controller: Marks the device node as a GPIO controller.
-- nr-gpios: Number of GPIO pins supported by the controller.
-- interrupt-cells: Should be two. The first cell is the GPIO Number. The
- second cell is used to specify flags. The following subset of flags is
- supported:
- - trigger type:
- 1 = low to high edge triggered.
- 2 = high to low edge triggered.
- 4 = active high level-sensitive.
- 8 = active low level-sensitive.
-- interrupts: Interrupt number for this device.
-- interrupt-controller: Identifies the node as an interrupt controller.
-
-Example:
-
- gpio: xlp_gpio@34000 {
- compatible = "netlogic,xlp316-gpio";
- reg = <0 0x34100 0x1000
- 0 0x35100 0x1000>;
- #gpio-cells = <2>;
- gpio-controller;
- nr-gpios = <57>;
-
- #interrupt-cells = <2>;
- interrupt-parent = <&pic>;
- interrupts = <39>;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-xra1403.txt b/Documentation/devicetree/bindings/gpio/gpio-xra1403.txt
deleted file mode 100644
index e13cc399b363..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-xra1403.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-GPIO Driver for XRA1403 16-BIT GPIO Expander With Reset Input from EXAR
-
-The XRA1403 is an 16-bit GPIO expander with an SPI interface. Features available:
- - Individually programmable inputs:
- - Internal pull-up resistors
- - Polarity inversion
- - Individual interrupt enable
- - Rising edge and/or Falling edge interrupt
- - Input filter
- - Individually programmable outputs
- - Output Level Control
- - Output Three-State Control
-
-Properties
-----------
-Check documentation for SPI and GPIO controllers regarding properties needed to configure the node.
-
- - compatible = "exar,xra1403".
- - reg - SPI id of the device.
- - gpio-controller - marks the node as gpio.
- - #gpio-cells - should be two where the first cell is the pin number
- and the second one is used for optional parameters.
-
-Optional properties:
--------------------
- - reset-gpios: in case available used to control the device reset line.
- - interrupt-controller - marks the node as interrupt controller.
- - #interrupt-cells - should be two and represents the number of cells
- needed to encode interrupt source.
-
-Example
---------
-
- gpioxra0: gpio@2 {
- compatible = "exar,xra1403";
- reg = <2>;
-
- gpio-controller;
- #gpio-cells = <2>;
-
- interrupt-controller;
- #interrupt-cells = <2>;
-
- reset-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>;
- spi-max-frequency = <1000000>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-zevio.txt b/Documentation/devicetree/bindings/gpio/gpio-zevio.txt
deleted file mode 100644
index a37bd9ae2730..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-zevio.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-Zevio GPIO controller
-
-Required properties:
-- compatible: Should be "lsi,zevio-gpio"
-- reg: Address and length of the register set for the device
-- #gpio-cells: Should be two. The first cell is the pin number and the
- second cell is used to specify optional parameters (currently unused).
-- gpio-controller: Marks the device node as a GPIO controller.
-
-Example:
- gpio: gpio@90000000 {
- compatible = "lsi,zevio-gpio";
- reg = <0x90000000 0x1000>;
- gpio-controller;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml b/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml
index 378da2649e66..5e2496379a3c 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml
+++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.yaml
@@ -4,14 +4,18 @@
$id: http://devicetree.org/schemas/gpio/gpio-zynq.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Xilinx Zynq GPIO controller Device Tree Bindings
+title: Xilinx Zynq GPIO controller
maintainers:
- - Michal Simek <michal.simek@xilinx.com>
+ - Michal Simek <michal.simek@amd.com>
properties:
compatible:
- const: xlnx,zynq-gpio-1.0
+ enum:
+ - xlnx,zynq-gpio-1.0
+ - xlnx,zynqmp-gpio-1.0
+ - xlnx,versal-gpio-1.0
+ - xlnx,pmc-gpio-1.0
reg:
maxItems: 1
@@ -24,6 +28,11 @@ properties:
gpio-controller: true
+ gpio-line-names:
+ description: strings describing the names of each gpio line
+ minItems: 58
+ maxItems: 174
+
interrupt-controller: true
"#interrupt-cells":
@@ -32,6 +41,54 @@ properties:
clocks:
maxItems: 1
+ power-domains:
+ maxItems: 1
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - xlnx,zynqmp-gpio-1.0
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 174
+ maxItems: 174
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - xlnx,zynq-gpio-1.0
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 118
+ maxItems: 118
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - xlnx,versal-gpio-1.0
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 58
+ maxItems: 58
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - xlnx,pmc-gpio-1.0
+ then:
+ properties:
+ gpio-line-names:
+ minItems: 116
+ maxItems: 116
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index a8895d339bfe..b37dbb1edc62 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -35,8 +35,8 @@ and bit-banged data signals:
<&gpio1 15 0>;
In the above example, &gpio1 uses 2 cells to specify a gpio. The first cell is
-a local offset to the GPIO line and the second cell represent consumer flags,
-such as if the consumer desire the line to be active low (inverted) or open
+a local offset to the GPIO line and the second cell represents consumer flags,
+such as if the consumer desires the line to be active low (inverted) or open
drain. This is the recommended practice.
The exact meaning of each specifier cell is controller specific, and must be
@@ -59,7 +59,7 @@ GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
Optional standard bitfield specifiers for the last cell:
- Bit 0: 0 means active high, 1 means active low
-- Bit 1: 0 mean push-pull wiring, see:
+- Bit 1: 0 means push-pull wiring, see:
https://en.wikipedia.org/wiki/Push-pull_output
1 means single-ended wiring, see:
https://en.wikipedia.org/wiki/Single-ended_triode
@@ -154,18 +154,35 @@ of the GPIOs that can't be used.
Optionally, a GPIO controller may have a "gpio-line-names" property. This is
an array of strings defining the names of the GPIO lines going out of the
-GPIO controller. This name should be the most meaningful producer name
-for the system, such as a rail name indicating the usage. Package names
-such as pin name are discouraged: such lines have opaque names (since they
-are by definition generic purpose) and such names are usually not very
-helpful. For example "MMC-CD", "Red LED Vdd" and "ethernet reset" are
-reasonable line names as they describe what the line is used for. "GPIO0"
-is not a good name to give to a GPIO line. Placeholders are discouraged:
-rather use the "" (blank string) if the use of the GPIO line is undefined
-in your design. The names are assigned starting from line offset 0 from
-left to right from the passed array. An incomplete array (where the number
-of passed named are less than ngpios) will still be used up until the last
-provided valid line index.
+GPIO controller.
+
+For lines which are routed to on-board devices, this name should be
+the most meaningful producer name for the system, such as a rail name
+indicating the usage. Package names, such as a pin name, are discouraged:
+such lines have opaque names (since they are by definition general-purpose)
+and such names are usually not very helpful. For example "MMC-CD", "Red LED
+Vdd" and "ethernet reset" are reasonable line names as they describe what
+the line is used for. "GPIO0" is not a good name to give to a GPIO line
+that is hard-wired to a specific device.
+
+However, in the case of lines that are routed to a general purpose header
+(e.g. the Raspberry Pi 40-pin header), and therefore are not hard-wired to
+specific devices, using a pin number or the names on the header is fine
+provided these are real (preferably unique) names. Using an SoC's pad name
+or package name, or names made up from kernel-internal software constructs,
+are strongly discouraged. For example "pin8 [gpio14/uart0_txd]" is fine
+if the board's documentation labels pin 8 as such. However "PortB_24" (an
+example of a name from an SoC's reference manual) would not be desirable.
+
+In either case placeholders are discouraged: rather use the "" (blank
+string) if the use of the GPIO line is undefined in your design. Ideally,
+try to add comments to the dts file describing the naming convention
+you have chosen, and specifying from where the names are derived.
+
+The names are assigned starting from line offset 0, from left to right,
+from the passed array. An incomplete array (where the number of passed
+names is less than ngpios) will be used up until the last provided valid
+line index.
Example:
@@ -213,7 +230,7 @@ Example of two SOC GPIO banks defined as gpio-controller nodes:
gpio-controller;
#gpio-cells = <2>;
- line_b {
+ line_b-hog {
gpio-hog;
gpios = <6 0>;
output-low;
@@ -287,7 +304,7 @@ pins 50..69.
It is also possible to use pin groups for gpio ranges when pin groups are the
easiest and most convenient mapping.
-Both both <pinctrl-base> and <count> must set to 0 when using named pin groups
+Both <pinctrl-base> and <count> must be set to 0 when using named pin groups
names.
The property gpio-ranges-group-names must contain exactly one string for each
@@ -296,7 +313,7 @@ range.
Elements of gpio-ranges-group-names must contain the name of a pin group
defined in the respective pin controller. The number of pins/GPIO lines in the
range is the number of pins in that pin group. The number of pins of that
-group is defined int the implementation and not in the device tree.
+group is defined in the implementation and not in the device tree.
If numerical and named pin groups are mixed, the string corresponding to a
numerical pin range in gpio-ranges-group-names must be empty.
diff --git a/Documentation/devicetree/bindings/gpio/gpio_atmel.txt b/Documentation/devicetree/bindings/gpio/gpio_atmel.txt
deleted file mode 100644
index 29416f9c3220..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio_atmel.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-* Atmel GPIO controller (PIO)
-
-Required properties:
-- compatible: "atmel,<chip>-gpio", where <chip> is at91rm9200 or at91sam9x5.
-- reg: Should contain GPIO controller registers location and length
-- interrupts: Should be the port interrupt shared by all the pins.
-- #gpio-cells: Should be two. The first cell is the pin number and
- the second cell is used to specify optional parameters to declare if the GPIO
- is active high or low. See gpio.txt.
-- gpio-controller: Marks the device node as a GPIO controller.
-- interrupt-controller: Marks the device node as an interrupt controller.
-- #interrupt-cells: Should be two. The first cell is the pin number and the
- second cell is used to specify irq type flags, see the two cell description
- in interrupt-controller/interrupts.txt for details.
-
-optional properties:
-- #gpio-lines: Number of gpio if absent 32.
-
-
-Example:
- pioA: gpio@fffff200 {
- compatible = "atmel,at91rm9200-gpio";
- reg = <0xfffff200 0x100>;
- interrupts = <2 4>;
- #gpio-cells = <2>;
- gpio-controller;
- #gpio-lines = <19>;
- interrupt-controller;
- #interrupt-cells = <2>;
- };
-
diff --git a/Documentation/devicetree/bindings/gpio/gpio_lpc32xx.txt b/Documentation/devicetree/bindings/gpio/gpio_lpc32xx.txt
deleted file mode 100644
index 49819367a011..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio_lpc32xx.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-NXP LPC32xx SoC GPIO controller
-
-Required properties:
-- compatible: must be "nxp,lpc3220-gpio"
-- reg: Physical base address and length of the controller's registers.
-- gpio-controller: Marks the device node as a GPIO controller.
-- #gpio-cells: Should be 3:
- 1) bank:
- 0: GPIO P0
- 1: GPIO P1
- 2: GPIO P2
- 3: GPIO P3
- 4: GPI P3
- 5: GPO P3
- 2) pin number
- 3) optional parameters:
- - bit 0 specifies polarity (0 for normal, 1 for inverted)
-- reg: Index of the GPIO group
-
-Example:
-
- gpio: gpio@40028000 {
- compatible = "nxp,lpc3220-gpio";
- reg = <0x40028000 0x1000>;
- gpio-controller;
- #gpio-cells = <3>; /* bank, pin, flags */
- };
-
- leds {
- compatible = "gpio-leds";
-
- led0 {
- gpios = <&gpio 5 1 1>; /* GPO_P3 1, active low */
- linux,default-trigger = "heartbeat";
- default-state = "off";
- };
-
- led1 {
- gpios = <&gpio 5 14 1>; /* GPO_P3 14, active low */
- linux,default-trigger = "timer";
- default-state = "off";
- };
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio_oxnas.txt b/Documentation/devicetree/bindings/gpio/gpio_oxnas.txt
deleted file mode 100644
index 966514744df4..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio_oxnas.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-* Oxford Semiconductor OXNAS SoC GPIO Controller
-
-Please refer to gpio.txt for generic information regarding GPIO bindings.
-
-Required properties:
- - compatible: "oxsemi,ox810se-gpio" or "oxsemi,ox820-gpio"
- - reg: Base address and length for the device.
- - interrupts: The port interrupt shared by all pins.
- - gpio-controller: Marks the port as GPIO controller.
- - #gpio-cells: Two. The first cell is the pin number and
- the second cell is used to specify the gpio polarity as defined in
- defined in <dt-bindings/gpio/gpio.h>:
- 0 = GPIO_ACTIVE_HIGH
- 1 = GPIO_ACTIVE_LOW
- - interrupt-controller: Marks the device node as an interrupt controller.
- - #interrupt-cells: Two. The first cell is the GPIO number and second cell
- is used to specify the trigger type as defined in
- <dt-bindings/interrupt-controller/irq.h>:
- IRQ_TYPE_EDGE_RISING
- IRQ_TYPE_EDGE_FALLING
- IRQ_TYPE_EDGE_BOTH
- - gpio-ranges: Interaction with the PINCTRL subsystem, it also specifies the
- gpio base and count, should be in the format of numeric-gpio-range as
- specified in the gpio.txt file.
-
-Example:
-
-gpio0: gpio@0 {
- compatible = "oxsemi,ox810se-gpio";
- reg = <0x000000 0x100000>;
- interrupts = <21>;
- #gpio-cells = <2>;
- gpio-controller;
- interrupt-controller;
- #interrupt-cells = <2>;
- gpio-ranges = <&pinctrl 0 0 32>;
-};
-
-keys {
- ...
-
- button-esc {
- label = "ESC";
- linux,code = <1>;
- gpios = <&gpio0 12 0>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml b/Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml
new file mode 100644
index 000000000000..735d97d645a0
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/hisilicon,ascend910-gpio.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/hisilicon,ascend910-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HiSilicon common GPIO controller
+
+maintainers:
+ - Jay Fang <f.fangjian@huawei.com>
+
+description:
+ The HiSilicon common GPIO controller can be used for many different
+ types of SoC such as Huawei Ascend AI series chips.
+
+properties:
+ compatible:
+ const: hisilicon,ascend910-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ ngpios:
+ minimum: 1
+ maximum: 32
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - gpio-controller
+ - "#gpio-cells"
+ - ngpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpio@840d0000 {
+ compatible = "hisilicon,ascend910-gpio";
+ reg = <0x840d0000 0x1000>;
+ ngpios = <32>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/ibm,ppc4xx-gpio.txt b/Documentation/devicetree/bindings/gpio/ibm,ppc4xx-gpio.txt
deleted file mode 100644
index d58b3958f3ea..000000000000
--- a/Documentation/devicetree/bindings/gpio/ibm,ppc4xx-gpio.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-* IBM/AMCC/APM GPIO Controller for PowerPC 4XX series and compatible SoCs
-
-All GPIOs are pin-shared with other functions. DCRs control whether a
-particular pin that has GPIO capabilities acts as a GPIO or is used for
-another purpose. GPIO outputs are separately programmable to emulate
-an open-drain driver.
-
-Required properties:
- - compatible: must be "ibm,ppc4xx-gpio"
- - reg: address and length of the register set for the device
- - #gpio-cells: must be set to 2. The first cell is the pin number
- and the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
- - gpio-controller: marks the device node as a gpio controller.
-
-Example:
-
-GPIO0: gpio@ef600b00 {
- compatible = "ibm,ppc4xx-gpio";
- reg = <0xef600b00 0x00000048>;
- #gpio-cells = <2>;
- gpio-controller;
-};
diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt
deleted file mode 100644
index 8dc41ed99685..000000000000
--- a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-Intel IXP4xx XScale Networking Processors GPIO
-
-This GPIO controller is found in the Intel IXP4xx processors.
-It supports 16 GPIO lines.
-
-The interrupt portions of the GPIO controller is hierarchical:
-the synchronous edge detector is part of the GPIO block, but the
-actual enabling/disabling of the interrupt line is done in the
-main IXP4xx interrupt controller which has a 1:1 mapping for
-the first 12 GPIO lines to 12 system interrupts.
-
-The remaining 4 GPIO lines can not be used for receiving
-interrupts.
-
-The interrupt parent of this GPIO controller must be the
-IXP4xx interrupt controller.
-
-Required properties:
-
-- compatible : Should be
- "intel,ixp4xx-gpio"
-- reg : Should contain registers location and length
-- gpio-controller : marks this as a GPIO controller
-- #gpio-cells : Should be 2, see gpio/gpio.txt
-- interrupt-controller : marks this as an interrupt controller
-- #interrupt-cells : a standard two-cell interrupt, see
- interrupt-controller/interrupts.txt
-
-Example:
-
-gpio0: gpio@c8004000 {
- compatible = "intel,ixp4xx-gpio";
- reg = <0xc8004000 0x1000>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml
new file mode 100644
index 000000000000..bfcb1f364c3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/intel,ixp4xx-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intel IXP4xx XScale Networking Processors GPIO Controller
+
+description: |
+ This GPIO controller is found in the Intel IXP4xx
+ processors. It supports 16 GPIO lines.
+ The interrupt portions of the GPIO controller is hierarchical.
+ The synchronous edge detector is part of the GPIO block, but the
+ actual enabling/disabling of the interrupt line is done in the
+ main IXP4xx interrupt controller which has a 1-to-1 mapping for
+ the first 12 GPIO lines to 12 system interrupts.
+ The remaining 4 GPIO lines can not be used for receiving
+ interrupts.
+ The interrupt parent of this GPIO controller must be the
+ IXP4xx interrupt controller.
+ GPIO 14 and 15 can be used as clock outputs rather than GPIO,
+ and this can be enabled by a special flag.
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+properties:
+ compatible:
+ const: intel,ixp4xx-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ intel,ixp4xx-gpio14-clkout:
+ description: If defined, enables clock output on GPIO 14
+ instead of GPIO.
+ type: boolean
+
+ intel,ixp4xx-gpio15-clkout:
+ description: If defined, enables clock output on GPIO 15
+ instead of GPIO.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - "#gpio-cells"
+ - interrupt-controller
+ - "#interrupt-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ gpio@c8004000 {
+ compatible = "intel,ixp4xx-gpio";
+ reg = <0xc8004000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml b/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml
index b032471831e7..02663d67eac7 100644
--- a/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/kontron,sl28cpld-gpio.yaml
@@ -11,7 +11,7 @@ maintainers:
description: |
This module is part of the sl28cpld multi-function device. For more
- details see ../mfd/kontron,sl28cpld.yaml.
+ details see ../embedded-controller/kontron,sl28cpld.yaml.
There are three flavors of the GPIO controller, one full featured
input/output with interrupt support (kontron,sl28cpld-gpio), one
diff --git a/Documentation/devicetree/bindings/gpio/lacie,netxbig-gpio-ext.yaml b/Documentation/devicetree/bindings/gpio/lacie,netxbig-gpio-ext.yaml
new file mode 100644
index 000000000000..42021ee14125
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/lacie,netxbig-gpio-ext.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/lacie,netxbig-gpio-ext.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NetxBig GPIO extension bus
+
+maintainers:
+ - Simon Guinot <simon.guinot@sequanux.org>
+
+description: >
+ GPIO extension bus found on some LaCie/Seagate boards
+ (Example: 2Big/5Big Network v2, 2Big NAS).
+
+properties:
+ compatible:
+ items:
+ - const: lacie,netxbig-gpio-ext
+
+ addr-gpios:
+ description: GPIOs representing the address register (LSB->MSB).
+ items:
+ - description: bit 0 (LSB)
+ - description: bit 1
+ - description: bit 2 (MSB)
+
+ data-gpios:
+ description: GPIOs representing the data register (LSB->MSB).
+ items:
+ - description: bit 0 (LSB)
+ - description: bit 1
+ - description: bit 2 (MSB)
+
+ enable-gpio:
+ description: Latches the new configuration (address, data) on raising edge.
+ maxItems: 1
+
+required:
+ - compatible
+ - addr-gpios
+ - data-gpios
+ - enable-gpio
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ gpio {
+ compatible = "lacie,netxbig-gpio-ext";
+ addr-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH
+ &gpio1 16 GPIO_ACTIVE_HIGH
+ &gpio1 17 GPIO_ACTIVE_HIGH>;
+ data-gpios = <&gpio1 12 GPIO_ACTIVE_HIGH
+ &gpio1 13 GPIO_ACTIVE_HIGH
+ &gpio1 14 GPIO_ACTIVE_HIGH>;
+ enable-gpio = <&gpio0 29 GPIO_ACTIVE_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/lantiq,gpio-mm-lantiq.yaml b/Documentation/devicetree/bindings/gpio/lantiq,gpio-mm-lantiq.yaml
new file mode 100644
index 000000000000..eaf53a89542a
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/lantiq,gpio-mm-lantiq.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/lantiq,gpio-mm-lantiq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lantiq SoC External Bus memory mapped GPIO controller
+
+maintainers:
+ - John Crispin <john@phrozen.org>
+
+description: |
+ By attaching hardware latches to the EBU it is possible to create output
+ only gpios. This driver configures a special memory address, which when
+ written to outputs 16 bit to the latches.
+
+ The node describing the memory mapped GPIOs needs to be a child of the node
+ describing the "lantiq,localbus".
+
+properties:
+ compatible:
+ enum:
+ - lantiq,gpio-mm-lantiq
+ - lantiq,gpio-mm
+
+ reg:
+ maxItems: 1
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+ lantiq,shadow:
+ description: The default value that we shall assume as already set on the shift register cascade.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - '#gpio-cells'
+ - gpio-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@4000000 {
+ compatible = "lantiq,gpio-mm-lantiq";
+ reg = <0x4000000 0x10>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ lantiq,shadow = <0x77f>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml b/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml
new file mode 100644
index 000000000000..69852444df23
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/loongson,ls-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson GPIO controller.
+
+maintainers:
+ - Yinbo Zhu <zhuyinbo@loongson.cn>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - loongson,ls2k-gpio
+ - loongson,ls2k0300-gpio
+ - loongson,ls2k0500-gpio0
+ - loongson,ls2k0500-gpio1
+ - loongson,ls2k2000-gpio0
+ - loongson,ls2k2000-gpio1
+ - loongson,ls2k2000-gpio2
+ - loongson,ls3a5000-gpio
+ - loongson,ls3a6000-gpio # Loongson-3A6000 node GPIO
+ - loongson,ls7a-gpio
+ - loongson,ls7a2000-gpio1 # LS7A2000 chipset GPIO
+ - loongson,ls7a2000-gpio2 # LS7A2000 ACPI GPIO
+ - items:
+ - const: loongson,ls2k1000-gpio
+ - const: loongson,ls2k-gpio
+ - items:
+ - const: loongson,ls7a1000-gpio
+ - const: loongson,ls7a-gpio
+
+ reg:
+ maxItems: 1
+
+ ngpios:
+ minimum: 1
+ maximum: 128
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+ gpio-ranges: true
+
+ interrupts:
+ minItems: 1
+ maxItems: 64
+
+ "#interrupt-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - ngpios
+ - "#gpio-cells"
+ - gpio-controller
+ - gpio-ranges
+ - interrupts
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: loongson,ls2k0300-gpio
+ then:
+ required:
+ - "#interrupt-cells"
+ - interrupt-controller
+ - resets
+ else:
+ properties:
+ "#interrupts-cells": false
+ interrupt-controller: false
+ resets: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpio0: gpio@1fe00500 {
+ compatible = "loongson,ls2k1000-gpio", "loongson,ls2k-gpio";
+ reg = <0x1fe00500 0x38>;
+ ngpios = <64>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ gpio-ranges = <&pctrl 0 0 15>,
+ <&pctrl 16 16 15>,
+ <&pctrl 32 32 10>,
+ <&pctrl 44 44 20>;
+ interrupt-parent = <&liointc1>;
+ interrupts = <28 IRQ_TYPE_LEVEL_LOW>,
+ <29 IRQ_TYPE_LEVEL_LOW>,
+ <30 IRQ_TYPE_LEVEL_LOW>,
+ <30 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <26 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <>,
+ <>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>,
+ <27 IRQ_TYPE_LEVEL_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml b/Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml
new file mode 100644
index 000000000000..e9e201a489e5
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/lsi,zevio-gpio.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/lsi,zevio-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Zevio GPIO controller
+
+maintainers:
+ - Pratik Farkase <pratikfarkase94@gmail.com>
+
+properties:
+ compatible:
+ items:
+ - const: lsi,zevio-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+required:
+ - compatible
+ - reg
+ - "#gpio-cells"
+ - gpio-controller
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ gpio@90000000 {
+ compatible = "lsi,zevio-gpio";
+ reg = <0x90000000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/maxim,max31910.yaml b/Documentation/devicetree/bindings/gpio/maxim,max31910.yaml
new file mode 100644
index 000000000000..4d200f9dffd5
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/maxim,max31910.yaml
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/maxim,max31910.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX3191x GPIO serializer
+
+maintainers:
+ - Lukas Wunner <lukas@wunner.de>
+
+properties:
+ compatible:
+ enum:
+ - maxim,max31910
+ - maxim,max31911
+ - maxim,max31912
+ - maxim,max31913
+ - maxim,max31953
+ - maxim,max31963
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ '#daisy-chained-devices':
+ description: Number of chips in the daisy-chain.
+ default: 1
+
+ maxim,modesel-gpios:
+ description:
+ GPIO pins to configure modesel of each chip. The number of GPIOs must
+ equal "#daisy-chained-devices" (if each chip is driven by a separate pin)
+ or 1 (if all chips are wired to the same pin).
+
+ maxim,fault-gpios:
+ description:
+ GPIO pins to read fault of each chip. The number of GPIOs must equal
+ "#daisy-chained-devices" or 1.
+
+ maxim,db0-gpios:
+ description:
+ GPIO pins to configure debounce of each chip. The number of GPIOs must
+ equal "#daisy-chained-devices" or 1.
+
+ maxim,db1-gpios:
+ description:
+ GPIO pins to configure debounce of each chip. The number of GPIOs must
+ equal "maxim,db0-gpios".
+
+ maxim,modesel-8bit:
+ description:
+ Boolean whether the modesel pin of the chips is pulled high (8-bit mode).
+ Use this if the modesel pin is hardwired and consequently
+ "maxim,modesel-gpios" cannot be specified. By default if neither this nor
+ "maxim,modesel-gpios" is given, the driver assumes that modesel is pulled
+ low (16-bit mode).
+ type: boolean
+
+ maxim,ignore-undervoltage:
+ description:
+ Boolean whether to ignore undervoltage alarms signaled by the
+ "maxim,fault-gpios" or by the status byte (in 16-bit mode). Use this if
+ the chips are powered through 5VOUT instead of VCC24V, in which case they
+ will constantly signal undervoltage.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@0 {
+ compatible = "maxim,max31913";
+ reg = <0>;
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ maxim,modesel-gpios = <&gpio2 23>;
+ maxim,fault-gpios = <&gpio2 24 GPIO_ACTIVE_LOW>;
+ maxim,db0-gpios = <&gpio2 25>;
+ maxim,db1-gpios = <&gpio2 26>;
+
+ spi-max-frequency = <25000000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gpio/maxim,max7360-gpio.yaml b/Documentation/devicetree/bindings/gpio/maxim,max7360-gpio.yaml
new file mode 100644
index 000000000000..c5c3fc4c816f
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/maxim,max7360-gpio.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/maxim,max7360-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX7360 GPIO controller
+
+maintainers:
+ - Kamel Bouhara <kamel.bouhara@bootlin.com>
+ - Mathieu Dubois-Briand <mathieu.dubois-briand@bootlin.com>
+
+description: |
+ Maxim MAX7360 GPIO controller, in MAX7360 chipset
+ https://www.analog.com/en/products/max7360.html
+
+ The device provides two series of GPIOs, referred here as GPIOs and GPOs.
+
+ PORT0 to PORT7 pins can be used as GPIOs, with support for interrupts and
+ constant-current mode. These pins will also be used by the rotary encoder and
+ PWM functionalities.
+
+ COL2 to COL7 pins can be used as GPOs, there is no input capability. COL pins
+ will be partitioned, with the first pins being affected to the keypad
+ functionality and the last ones as GPOs.
+
+properties:
+ compatible:
+ enum:
+ - maxim,max7360-gpio
+ - maxim,max7360-gpo
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ maxim,constant-current-disable:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Bit field, each bit disables constant-current output of the associated
+ GPIO, starting from the least significant bit for the first GPIO.
+ maximum: 0xff
+
+required:
+ - compatible
+ - gpio-controller
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - maxim,max7360-gpio
+ ngpios: false
+ then:
+ required:
+ - interrupt-controller
+ else:
+ properties:
+ interrupt-controller: false
+ maxim,constant-current-disable: false
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio {
+ compatible = "maxim,max7360-gpio";
+
+ gpio-controller;
+ #gpio-cells = <2>;
+ maxim,constant-current-disable = <0x06>;
+
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/maxim,max77759-gpio.yaml b/Documentation/devicetree/bindings/gpio/maxim,max77759-gpio.yaml
new file mode 100644
index 000000000000..55734190d5eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/maxim,max77759-gpio.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/maxim,max77759-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim Integrated MAX77759 GPIO
+
+maintainers:
+ - André Draszik <andre.draszik@linaro.org>
+
+description: |
+ This module is part of the MAX77759 PMIC. For additional information, see
+ Documentation/devicetree/bindings/mfd/maxim,max77759.yaml.
+
+ The MAX77759 is a PMIC integrating, amongst others, a GPIO controller
+ including interrupt support for 2 GPIO lines.
+
+properties:
+ compatible:
+ const: maxim,max77759-gpio
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 2
+
+ "#interrupt-cells":
+ const: 2
+
+ interrupt-controller: true
+
+required:
+ - compatible
+ - "#gpio-cells"
+ - gpio-controller
+ - "#interrupt-cells"
+ - interrupt-controller
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/gpio/microchip,mpfs-gpio.yaml b/Documentation/devicetree/bindings/gpio/microchip,mpfs-gpio.yaml
new file mode 100644
index 000000000000..184432d24ea1
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/microchip,mpfs-gpio.yaml
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/microchip,mpfs-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MPFS GPIO Controller
+
+maintainers:
+ - Conor Dooley <conor.dooley@microchip.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: microchip,pic64gx-gpio
+ - const: microchip,mpfs-gpio
+ - enum:
+ - microchip,mpfs-gpio
+ - microchip,coregpio-rtl-v3
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Interrupt mapping, one per GPIO. Maximum 32 GPIOs.
+ minItems: 1
+ maxItems: 32
+
+ interrupt-controller: true
+
+ clocks:
+ maxItems: 1
+
+ "#gpio-cells":
+ const: 2
+
+ "#interrupt-cells":
+ const: 1
+
+ ngpios:
+ description:
+ The number of GPIOs available.
+ minimum: 1
+ maximum: 32
+ default: 32
+
+ gpio-controller: true
+ gpio-line-names: true
+
+patternProperties:
+ "^.+-hog(-[0-9]+)?$":
+ type: object
+ required:
+ - gpio-hog
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: microchip,mpfs-gpio
+ then:
+ required:
+ - interrupts
+ - "#interrupt-cells"
+ - interrupt-controller
+
+required:
+ - compatible
+ - reg
+ - "#gpio-cells"
+ - gpio-controller
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@20122000 {
+ compatible = "microchip,mpfs-gpio";
+ reg = <0x20122000 0x1000>;
+ clocks = <&clkcfg 25>;
+ interrupt-parent = <&plic>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>,
+ <53>, <53>, <53>, <53>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/microchip,pic32-gpio.txt b/Documentation/devicetree/bindings/gpio/microchip,pic32-gpio.txt
deleted file mode 100644
index dd031fc93b55..000000000000
--- a/Documentation/devicetree/bindings/gpio/microchip,pic32-gpio.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* Microchip PIC32 GPIO devices (PIO).
-
-Required properties:
- - compatible: "microchip,pic32mzda-gpio"
- - reg: Base address and length for the device.
- - interrupts: The port interrupt shared by all pins.
- - gpio-controller: Marks the port as GPIO controller.
- - #gpio-cells: Two. The first cell is the pin number and
- the second cell is used to specify the gpio polarity as defined in
- defined in <dt-bindings/gpio/gpio.h>:
- 0 = GPIO_ACTIVE_HIGH
- 1 = GPIO_ACTIVE_LOW
- 2 = GPIO_OPEN_DRAIN
- - interrupt-controller: Marks the device node as an interrupt controller.
- - #interrupt-cells: Two. The first cell is the GPIO number and second cell
- is used to specify the trigger type as defined in
- <dt-bindings/interrupt-controller/irq.h>:
- IRQ_TYPE_EDGE_RISING
- IRQ_TYPE_EDGE_FALLING
- IRQ_TYPE_EDGE_BOTH
- - clocks: Clock specifier (see clock bindings for details).
- - microchip,gpio-bank: Specifies which bank a controller owns.
- - gpio-ranges: Interaction with the PINCTRL subsystem.
-
-Example:
-
-/* PORTA */
-gpio0: gpio0@1f860000 {
- compatible = "microchip,pic32mzda-gpio";
- reg = <0x1f860000 0x100>;
- interrupts = <118 IRQ_TYPE_LEVEL_HIGH>;
- #gpio-cells = <2>;
- gpio-controller;
- interrupt-controller;
- #interrupt-cells = <2>;
- clocks = <&rootclk PB4CLK>;
- microchip,gpio-bank = <0>;
- gpio-ranges = <&pic32_pinctrl 0 0 16>;
-};
-
-keys {
- ...
-
- button@sw1 {
- label = "ESC";
- linux,code = <1>;
- gpios = <&gpio0 12 0>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpio/microchip,pic32mzda-gpio.yaml b/Documentation/devicetree/bindings/gpio/microchip,pic32mzda-gpio.yaml
new file mode 100644
index 000000000000..d8d932c86697
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/microchip,pic32mzda-gpio.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/microchip,pic32mzda-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip PIC32 GPIO controller
+
+maintainers:
+ - Joshua Henderson <joshua.henderson@microchip.com>
+ - Purna Chandra Mandal <purna.mandal@microchip.com>
+
+properties:
+ compatible:
+ const: microchip,pic32mzda-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ gpio-ranges: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ clocks:
+ maxItems: 1
+
+ microchip,gpio-bank:
+ description: Bank index owned by the controller
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - gpio-ranges
+ - "#gpio-cells"
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+ - clocks
+ - microchip,gpio-bank
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpio@1f860000 {
+ compatible = "microchip,pic32mzda-gpio";
+ reg = <0x1f860000 0x100>;
+ interrupts = <118 IRQ_TYPE_LEVEL_HIGH>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ clocks = <&rootclk 11>;
+ microchip,gpio-bank = <0>;
+ gpio-ranges = <&pic32_pinctrl 0 0 16>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml
index 9cf6137dd524..65155bb701a9 100644
--- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml
@@ -9,7 +9,7 @@ title: Marvell PXA GPIO controller
maintainers:
- Linus Walleij <linus.walleij@linaro.org>
- Bartosz Golaszewski <bgolaszewski@baylibre.com>
- - Rob Herring <robh+dt@kernel.org>
+ - Rob Herring <robh@kernel.org>
allOf:
- if:
diff --git a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml
index fe1e1c63ffe3..18fe90387b87 100644
--- a/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/mstar,msc313-gpio.yaml
@@ -14,7 +14,9 @@ properties:
pattern: "^gpio@[0-9a-f]+$"
compatible:
- const: mstar,msc313-gpio
+ enum:
+ - mstar,msc313-gpio
+ - sstar,ssd20xd-gpio
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/gpio/netxbig-gpio-ext.txt b/Documentation/devicetree/bindings/gpio/netxbig-gpio-ext.txt
deleted file mode 100644
index 50ec2e690701..000000000000
--- a/Documentation/devicetree/bindings/gpio/netxbig-gpio-ext.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Binding for the GPIO extension bus found on some LaCie/Seagate boards
-(Example: 2Big/5Big Network v2, 2Big NAS).
-
-Required properties:
-- compatible: "lacie,netxbig-gpio-ext".
-- addr-gpios: GPIOs representing the address register (LSB -> MSB).
-- data-gpios: GPIOs representing the data register (LSB -> MSB).
-- enable-gpio: latches the new configuration (address, data) on raising edge.
-
-Example:
-
-netxbig_gpio_ext: netxbig-gpio-ext {
- compatible = "lacie,netxbig-gpio-ext";
-
- addr-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH
- &gpio1 16 GPIO_ACTIVE_HIGH
- &gpio1 17 GPIO_ACTIVE_HIGH>;
- data-gpios = <&gpio1 12 GPIO_ACTIVE_HIGH
- &gpio1 13 GPIO_ACTIVE_HIGH
- &gpio1 14 GPIO_ACTIVE_HIGH>;
- enable-gpio = <&gpio0 29 GPIO_ACTIVE_HIGH>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt b/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt
deleted file mode 100644
index ca2f8c745a27..000000000000
--- a/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-Bindings for the National Instruments 169445 GPIO NAND controller
-
-The 169445 GPIO NAND controller has two memory mapped GPIO registers, one
-for input (the ready signal) and one for output (control signals). It is
-intended to be used with the GPIO NAND driver.
-
-Required properties:
- - compatible: should be "ni,169445-nand-gpio"
- - reg-names: must contain
- "dat" - data register
- - reg: address + size pairs describing the GPIO register sets;
- order must correspond with the order of entries in reg-names
- - #gpio-cells: must be set to 2. The first cell is the pin number and
- the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
- - gpio-controller: Marks the device node as a gpio controller.
-
-Optional properties:
- - no-output: disables driving output on the pins
-
-Examples:
- gpio1: nand-gpio-out@1f300010 {
- compatible = "ni,169445-nand-gpio";
- reg = <0x1f300010 0x4>;
- reg-names = "dat";
- gpio-controller;
- #gpio-cells = <2>;
- };
-
- gpio2: nand-gpio-in@1f300014 {
- compatible = "ni,169445-nand-gpio";
- reg = <0x1f300014 0x4>;
- reg-names = "dat";
- gpio-controller;
- #gpio-cells = <2>;
- no-output;
- };
diff --git a/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt b/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt
deleted file mode 100644
index df63da46309c..000000000000
--- a/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Nintendo Wii (Hollywood) GPIO controller
-
-Required properties:
-- compatible: "nintendo,hollywood-gpio"
-- reg: Physical base address and length of the controller's registers.
-- gpio-controller: Marks the device node as a GPIO controller.
-- #gpio-cells: Should be <2>. The first cell is the pin number and the
- second cell is used to specify optional parameters:
- - bit 0 specifies polarity (0 for normal, 1 for inverted).
-
-Optional properties:
-- ngpios: see Documentation/devicetree/bindings/gpio/gpio.txt
-- interrupt-controller: Marks the device node as an interrupt controller.
-- #interrupt-cells: Should be two.
-- interrupts: Interrupt specifier for the controller's Broadway (PowerPC)
- interrupt.
-
-Example:
-
- GPIO: gpio@d8000c0 {
- #gpio-cells = <2>;
- compatible = "nintendo,hollywood-gpio";
- reg = <0x0d8000c0 0x40>;
- gpio-controller;
- ngpios = <24>;
- }
diff --git a/Documentation/devicetree/bindings/gpio/nuvoton,sgpio.yaml b/Documentation/devicetree/bindings/gpio/nuvoton,sgpio.yaml
new file mode 100644
index 000000000000..9e32e54aeb24
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/nuvoton,sgpio.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/nuvoton,sgpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton SGPIO controller
+
+maintainers:
+ - Jim LIU <JJLIU0@nuvoton.com>
+
+description: |
+ This SGPIO controller is for NUVOTON NPCM7xx and NPCM8xx SoC and detailed
+ information is in the NPCM7XX/8XX SERIAL I/O EXPANSION INTERFACE section.
+ Nuvoton NPCM7xx SGPIO module is combines a serial to parallel IC (HC595)
+ and a parallel to serial IC (HC165).
+ Clock is a division of the APB3 clock.
+ This interface has 4 pins (D_out , D_in, S_CLK, LDSH).
+ NPCM7xx/NPCM8xx have two sgpio modules. Each module can support up
+ to 64 output pins, and up to 64 input pins, the pin is only for GPI or GPO.
+ GPIO pins can be programmed to support the following options
+ - Support interrupt option for each input port and various interrupt
+ sensitivity options (level-high, level-low, edge-high, edge-low)
+ - ngpios is number of nuvoton,input-ngpios GPIO lines and nuvoton,output-ngpios GPIO lines.
+ nuvoton,input-ngpios GPIO lines is only for GPI.
+ nuvoton,output-ngpios GPIO lines is only for GPO.
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,npcm750-sgpio
+ - nuvoton,npcm845-sgpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ nuvoton,input-ngpios:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The numbers of GPIO's exposed. GPIO lines are only for GPI.
+ minimum: 0
+ maximum: 64
+
+ nuvoton,output-ngpios:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The numbers of GPIO's exposed. GPIO lines are only for GPO.
+ minimum: 0
+ maximum: 64
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - interrupts
+ - nuvoton,input-ngpios
+ - nuvoton,output-ngpios
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/nuvoton,npcm7xx-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ gpio8: gpio@101000 {
+ compatible = "nuvoton,npcm750-sgpio";
+ reg = <0x101000 0x200>;
+ clocks = <&clk NPCM7XX_CLK_APB3>;
+ interrupts = <GIC_SPI 19 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ nuvoton,input-ngpios = <64>;
+ nuvoton,output-ngpios = <64>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt
deleted file mode 100644
index adff16c71d21..000000000000
--- a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt
+++ /dev/null
@@ -1,165 +0,0 @@
-NVIDIA Tegra186 GPIO controllers
-
-Tegra186 contains two GPIO controllers; a main controller and an "AON"
-controller. This binding document applies to both controllers. The register
-layouts for the controllers share many similarities, but also some significant
-differences. Hence, this document describes closely related but different
-bindings and compatible values.
-
-The Tegra186 GPIO controller allows software to set the IO direction of, and
-read/write the value of, numerous GPIO signals. Routing of GPIO signals to
-package balls is under the control of a separate pin controller HW block. Two
-major sets of registers exist:
-
-a) Security registers, which allow configuration of allowed access to the GPIO
-register set. These registers exist in a single contiguous block of physical
-address space. The size of this block, and the security features available,
-varies between the different GPIO controllers.
-
-Access to this set of registers is not necessary in all circumstances. Code
-that wishes to configure access to the GPIO registers needs access to these
-registers to do so. Code which simply wishes to read or write GPIO data does not
-need access to these registers.
-
-b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO
-controllers, these registers are exposed via multiple "physical aliases" in
-address space, each of which access the same underlying state. See the hardware
-documentation for rationale. Any particular GPIO client is expected to access
-just one of these physical aliases.
-
-Tegra HW documentation describes a unified naming convention for all GPIOs
-implemented by the SoC. Each GPIO is assigned to a port, and a port may control
-a number of GPIOs. Thus, each GPIO is named according to an alphabetical port
-name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6,
-or GPIO_PCC3.
-
-The number of ports implemented by each GPIO controller varies. The number of
-implemented GPIOs within each port varies. GPIO registers within a controller
-are grouped and laid out according to the port they affect.
-
-The mapping from port name to the GPIO controller that implements that port, and
-the mapping from port name to register offset within a controller, are both
-extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h>
-describes the port-level mapping. In that file, the naming convention for ports
-matches the HW documentation. The values chosen for the names are alphabetically
-sorted within a particular controller. Drivers need to map between the DT GPIO
-IDs and HW register offsets using a lookup table.
-
-Each GPIO controller can generate a number of interrupt signals. Each signal
-represents the aggregate status for all GPIOs within a set of ports. Thus, the
-number of interrupt signals generated by a controller varies as a rough function
-of the number of ports it implements. Note that the HW documentation refers to
-both the overall controller HW module and the sets-of-ports as "controllers".
-
-Each GPIO controller in fact generates multiple interrupts signals for each set
-of ports. Each GPIO may be configured to feed into a specific one of the
-interrupt signals generated by a set-of-ports. The intent is for each generated
-signal to be routed to a different CPU, thus allowing different CPUs to each
-handle subsets of the interrupts within a port. The status of each of these
-per-port-set signals is reported via a separate register. Thus, a driver needs
-to know which status register to observe. This binding currently defines no
-configuration mechanism for this. By default, drivers should use register
-GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
-define a property to configure this.
-
-Required properties:
-- compatible
- Array of strings.
- One of:
- - "nvidia,tegra186-gpio".
- - "nvidia,tegra186-gpio-aon".
- - "nvidia,tegra194-gpio".
- - "nvidia,tegra194-gpio-aon".
-- reg-names
- Array of strings.
- Contains a list of names for the register spaces described by the reg
- property. May contain the following entries, in any order:
- - "gpio": Mandatory. GPIO control registers. This may cover either:
- a) The single physical alias that this OS should use.
- b) All physical aliases that exist in the controller. This is
- appropriate when the OS is responsible for managing assignment of
- the physical aliases.
- - "security": Optional. Security configuration registers.
- Users of this binding MUST look up entries in the reg property by name,
- using this reg-names property to do so.
-- reg
- Array of (physical base address, length) tuples.
- Must contain one entry per entry in the reg-names property, in a matching
- order.
-- interrupts
- Array of interrupt specifiers.
- The interrupt outputs from the HW block, one per set of ports, in the
- order the HW manual describes them. The number of entries required varies
- depending on compatible value:
- - "nvidia,tegra186-gpio": 6 entries.
- - "nvidia,tegra186-gpio-aon": 1 entry.
- - "nvidia,tegra194-gpio": 6 entries.
- - "nvidia,tegra194-gpio-aon": 1 entry.
-- gpio-controller
- Boolean.
- Marks the device node as a GPIO controller/provider.
-- #gpio-cells
- Single-cell integer.
- Must be <2>.
- Indicates how many cells are used in a consumer's GPIO specifier.
- In the specifier:
- - The first cell is the pin number.
- See <dt-bindings/gpio/tegra186-gpio.h>.
- - The second cell contains flags:
- - Bit 0 specifies polarity
- - 0: Active-high (normal).
- - 1: Active-low (inverted).
-- interrupt-controller
- Boolean.
- Marks the device node as an interrupt controller/provider.
-- #interrupt-cells
- Single-cell integer.
- Must be <2>.
- Indicates how many cells are used in a consumer's interrupt specifier.
- In the specifier:
- - The first cell is the GPIO number.
- See <dt-bindings/gpio/tegra186-gpio.h>.
- - The second cell is contains flags:
- - Bits [3:0] indicate trigger type and level:
- - 1: Low-to-high edge triggered.
- - 2: High-to-low edge triggered.
- - 4: Active high level-sensitive.
- - 8: Active low level-sensitive.
- Valid combinations are 1, 2, 3, 4, 8.
-
-Example:
-
-#include <dt-bindings/interrupt-controller/irq.h>
-
-gpio@2200000 {
- compatible = "nvidia,tegra186-gpio";
- reg-names = "security", "gpio";
- reg =
- <0x0 0x2200000 0x0 0x10000>,
- <0x0 0x2210000 0x0 0x10000>;
- interrupts =
- <0 47 IRQ_TYPE_LEVEL_HIGH>,
- <0 50 IRQ_TYPE_LEVEL_HIGH>,
- <0 53 IRQ_TYPE_LEVEL_HIGH>,
- <0 56 IRQ_TYPE_LEVEL_HIGH>,
- <0 59 IRQ_TYPE_LEVEL_HIGH>,
- <0 180 IRQ_TYPE_LEVEL_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
-
-gpio@c2f0000 {
- compatible = "nvidia,tegra186-gpio-aon";
- reg-names = "security", "gpio";
- reg =
- <0x0 0xc2f0000 0x0 0x1000>,
- <0x0 0xc2f1000 0x0 0x1000>;
- interrupts =
- <0 60 IRQ_TYPE_LEVEL_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml
new file mode 100644
index 000000000000..2bd620a1099b
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml
@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra GPIO Controller (Tegra186 and later)
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+description: |
+ Tegra186 contains two GPIO controllers; a main controller and an "AON"
+ controller. This binding document applies to both controllers. The register
+ layouts for the controllers share many similarities, but also some
+ significant differences. Hence, this document describes closely related but
+ different bindings and compatible values.
+
+ The Tegra186 GPIO controller allows software to set the IO direction of,
+ and read/write the value of, numerous GPIO signals. Routing of GPIO signals
+ to package balls is under the control of a separate pin controller hardware
+ block. Two major sets of registers exist:
+
+ a) Security registers, which allow configuration of allowed access to the
+ GPIO register set. These registers exist in a single contiguous block
+ of physical address space. The size of this block, and the security
+ features available, varies between the different GPIO controllers.
+
+ Access to this set of registers is not necessary in all circumstances.
+ Code that wishes to configure access to the GPIO registers needs access
+ to these registers to do so. Code which simply wishes to read or write
+ GPIO data does not need access to these registers.
+
+ b) GPIO registers, which allow manipulation of the GPIO signals. In some
+ GPIO controllers, these registers are exposed via multiple "physical
+ aliases" in address space, each of which access the same underlying
+ state. See the hardware documentation for rationale. Any particular
+ GPIO client is expected to access just one of these physical aliases.
+
+ Tegra HW documentation describes a unified naming convention for all GPIOs
+ implemented by the SoC. Each GPIO is assigned to a port, and a port may
+ control a number of GPIOs. Thus, each GPIO is named according to an
+ alphabetical port name and an integer GPIO name within the port. For
+ example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3.
+
+ The number of ports implemented by each GPIO controller varies. The number
+ of implemented GPIOs within each port varies. GPIO registers within a
+ controller are grouped and laid out according to the port they affect.
+
+ The mapping from port name to the GPIO controller that implements that
+ port, and the mapping from port name to register offset within a
+ controller, are both extremely non-linear. The header file
+ <dt-bindings/gpio/tegra186-gpio.h> describes the port-level mapping. In
+ that file, the naming convention for ports matches the HW documentation.
+ The values chosen for the names are alphabetically sorted within a
+ particular controller. Drivers need to map between the DT GPIO IDs and HW
+ register offsets using a lookup table.
+
+ Each GPIO controller can generate a number of interrupt signals. Each
+ signal represents the aggregate status for all GPIOs within a set of
+ ports. Thus, the number of interrupt signals generated by a controller
+ varies as a rough function of the number of ports it implements. Note
+ that the HW documentation refers to both the overall controller HW
+ module and the sets-of-ports as "controllers".
+
+ Each GPIO controller in fact generates multiple interrupts signals for
+ each set of ports. Each GPIO may be configured to feed into a specific
+ one of the interrupt signals generated by a set-of-ports. The intent is
+ for each generated signal to be routed to a different CPU, thus allowing
+ different CPUs to each handle subsets of the interrupts within a port.
+ The status of each of these per-port-set signals is reported via a
+ separate register. Thus, a driver needs to know which status register to
+ observe. This binding currently defines no configuration mechanism for
+ this. By default, drivers should use register
+ GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
+ define a property to configure this.
+
+properties:
+ compatible:
+ enum:
+ - nvidia,tegra186-gpio
+ - nvidia,tegra186-gpio-aon
+ - nvidia,tegra194-gpio
+ - nvidia,tegra194-gpio-aon
+ - nvidia,tegra234-gpio
+ - nvidia,tegra234-gpio-aon
+ - nvidia,tegra256-gpio
+
+ reg-names:
+ items:
+ - const: security
+ - const: gpio
+ minItems: 1
+
+ reg:
+ items:
+ - description: Security configuration registers.
+ - description: |
+ GPIO control registers. This may cover either:
+
+ a) The single physical alias that this OS should use.
+ b) All physical aliases that exist in the controller. This is
+ appropriate when the OS is responsible for managing assignment
+ of the physical aliases.
+ minItems: 1
+
+ interrupts:
+ description: The interrupt outputs from the HW block, one per set of
+ ports, in the order the HW manual describes them. The number of entries
+ required varies depending on compatible value.
+
+ gpio-controller: true
+
+ gpio-ranges:
+ maxItems: 1
+
+ "#gpio-cells":
+ description: |
+ Indicates how many cells are used in a consumer's GPIO specifier. In the
+ specifier:
+
+ - The first cell is the pin number.
+ See <dt-bindings/gpio/tegra186-gpio.h>.
+ - The second cell contains flags:
+ - Bit 0 specifies polarity
+ - 0: Active-high (normal).
+ - 1: Active-low (inverted).
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ description: |
+ Indicates how many cells are used in a consumer's interrupt specifier.
+ In the specifier:
+
+ - The first cell is the GPIO number.
+ See <dt-bindings/gpio/tegra186-gpio.h>.
+ - The second cell is contains flags:
+ - Bits [3:0] indicate trigger type and level:
+ - 1: Low-to-high edge triggered.
+ - 2: High-to-low edge triggered.
+ - 4: Active high level-sensitive.
+ - 8: Active low level-sensitive.
+
+ Valid combinations are 1, 2, 3, 4, 8.
+ const: 2
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra186-gpio
+ - nvidia,tegra194-gpio
+ - nvidia,tegra234-gpio
+ - nvidia,tegra256-gpio
+ then:
+ properties:
+ interrupts:
+ minItems: 6
+ maxItems: 48
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra186-gpio-aon
+ - nvidia,tegra194-gpio-aon
+ - nvidia,tegra234-gpio-aon
+ then:
+ properties:
+ interrupts:
+ minItems: 1
+ maxItems: 4
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpio@2200000 {
+ compatible = "nvidia,tegra186-gpio";
+ reg-names = "security", "gpio";
+ reg = <0x2200000 0x10000>,
+ <0x2210000 0x10000>;
+ interrupts = <0 47 IRQ_TYPE_LEVEL_HIGH>,
+ <0 50 IRQ_TYPE_LEVEL_HIGH>,
+ <0 53 IRQ_TYPE_LEVEL_HIGH>,
+ <0 56 IRQ_TYPE_LEVEL_HIGH>,
+ <0 59 IRQ_TYPE_LEVEL_HIGH>,
+ <0 180 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+
+ gpio@c2f0000 {
+ compatible = "nvidia,tegra186-gpio-aon";
+ reg-names = "security", "gpio";
+ reg = <0xc2f0000 0x1000>,
+ <0xc2f1000 0x1000>;
+ interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt
deleted file mode 100644
index 023c9526e5f8..000000000000
--- a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-NVIDIA Tegra GPIO controller
-
-Required properties:
-- compatible : "nvidia,tegra<chip>-gpio"
-- reg : Physical base address and length of the controller's registers.
-- interrupts : The interrupt outputs from the controller. For Tegra20,
- there should be 7 interrupts specified, and for Tegra30, there should
- be 8 interrupts specified.
-- #gpio-cells : Should be two. The first cell is the pin number and the
- second cell is used to specify optional parameters:
- - bit 0 specifies polarity (0 for normal, 1 for inverted)
-- gpio-controller : Marks the device node as a GPIO controller.
-- #interrupt-cells : Should be 2.
- The first cell is the GPIO number.
- The second cell is used to specify flags:
- bits[3:0] trigger type and level flags:
- 1 = low-to-high edge triggered.
- 2 = high-to-low edge triggered.
- 4 = active high level-sensitive.
- 8 = active low level-sensitive.
- Valid combinations are 1, 2, 3, 4, 8.
-- interrupt-controller : Marks the device node as an interrupt controller.
-
-Example:
-
-gpio: gpio@6000d000 {
- compatible = "nvidia,tegra20-gpio";
- reg = < 0x6000d000 0x1000 >;
- interrupts = < 0 32 0x04
- 0 33 0x04
- 0 34 0x04
- 0 35 0x04
- 0 55 0x04
- 0 87 0x04
- 0 89 0x04 >;
- #gpio-cells = <2>;
- gpio-controller;
- #interrupt-cells = <2>;
- interrupt-controller;
-};
diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml
new file mode 100644
index 000000000000..94b51749ee76
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra20-gpio.yaml
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/nvidia,tegra20-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra GPIO Controller (Tegra20 - Tegra210)
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - nvidia,tegra20-gpio
+ - nvidia,tegra30-gpio
+
+ - items:
+ - enum:
+ - nvidia,tegra114-gpio
+ - nvidia,tegra124-gpio
+ - nvidia,tegra210-gpio
+ - const: nvidia,tegra30-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description: The interrupt outputs from the controller. For Tegra20,
+ there should be 7 interrupts specified, and for Tegra30, there should
+ be 8 interrupts specified.
+
+ "#gpio-cells":
+ description: The first cell is the pin number and the second cell is used
+ to specify the GPIO polarity (0 = active high, 1 = active low).
+ const: 2
+
+ gpio-controller: true
+
+ gpio-ranges:
+ maxItems: 1
+
+ "#interrupt-cells":
+ description: |
+ Should be 2. The first cell is the GPIO number. The second cell is
+ used to specify flags:
+
+ bits[3:0] trigger type and level flags:
+ 1 = low-to-high edge triggered.
+ 2 = high-to-low edge triggered.
+ 4 = active high level-sensitive.
+ 8 = active low level-sensitive.
+
+ Valid combinations are 1, 2, 3, 4, 8.
+ const: 2
+
+ interrupt-controller: true
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: nvidia,tegra30-gpio
+ then:
+ properties:
+ interrupts:
+ minItems: 8
+ maxItems: 8
+ else:
+ properties:
+ interrupts:
+ minItems: 7
+ maxItems: 7
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#gpio-cells"
+ - gpio-controller
+ - "#interrupt-cells"
+ - interrupt-controller
+
+additionalProperties:
+ type: object
+ required:
+ - gpio-hog
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpio: gpio@6000d000 {
+ compatible = "nvidia,tegra20-gpio";
+ reg = <0x6000d000 0x1000>;
+ interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt b/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt
deleted file mode 100644
index 627efc78ecf2..000000000000
--- a/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-NXP LPC18xx/43xx GPIO controller Device Tree Bindings
------------------------------------------------------
-
-Required properties:
-- compatible : Should be "nxp,lpc1850-gpio"
-- reg : List of addresses and lengths of the GPIO controller
- register sets
-- reg-names : Should be "gpio", "gpio-pin-ic", "gpio-group0-ic" and
- "gpio-gpoup1-ic"
-- clocks : Phandle and clock specifier pair for GPIO controller
-- resets : Phandle and reset specifier pair for GPIO controller
-- gpio-controller : Marks the device node as a GPIO controller
-- #gpio-cells : Should be two:
- - The first cell is the GPIO line number
- - The second cell is used to specify polarity
-- interrupt-controller : Marks the device node as an interrupt controller
-- #interrupt-cells : Should be two:
- - The first cell is an interrupt number within
- 0..9 range, for GPIO pin interrupts it is equal
- to 'nxp,gpio-pin-interrupt' property value of
- GPIO pin configuration, 8 is for GPIO GROUP0
- interrupt, 9 is for GPIO GROUP1 interrupt
- - The second cell is used to specify interrupt type
-
-Optional properties:
-- gpio-ranges : Mapping between GPIO and pinctrl
-
-Example:
-#define LPC_GPIO(port, pin) (port * 32 + pin)
-#define LPC_PIN(port, pin) (0x##port * 32 + pin)
-
-gpio: gpio@400f4000 {
- compatible = "nxp,lpc1850-gpio";
- reg = <0x400f4000 0x4000>, <0x40087000 0x1000>,
- <0x40088000 0x1000>, <0x40089000 0x1000>;
- reg-names = "gpio", "gpio-pin-ic",
- "gpio-group0-ic", "gpio-gpoup1-ic";
- clocks = <&ccu1 CLK_CPU_GPIO>;
- resets = <&rgu 28>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- gpio-ranges = <&pinctrl LPC_GPIO(0,0) LPC_PIN(0,0) 2>,
- ...
- <&pinctrl LPC_GPIO(7,19) LPC_PIN(f,5) 7>;
-};
-
-gpio_joystick {
- compatible = "gpio-keys";
- ...
-
- button0 {
- ...
- interrupt-parent = <&gpio>;
- interrupts = <1 IRQ_TYPE_EDGE_BOTH>;
- gpios = <&gpio LPC_GPIO(4,8) GPIO_ACTIVE_LOW>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.yaml b/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.yaml
new file mode 100644
index 000000000000..0ef5f90f69ff
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/nxp,lpc1850-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP LPC18xx/43xx GPIO controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: nxp,lpc1850-gpio
+
+ reg:
+ minItems: 1
+ maxItems: 4
+
+ reg-names:
+ minItems: 1
+ items:
+ - const: gpio
+ - const: gpio-pin-ic
+ - const: gpio-group0-ic
+ - const: gpio-gpoup1-ic
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description: |
+ - The first cell is an interrupt number within
+ 0..9 range, for GPIO pin interrupts it is equal
+ to 'nxp,gpio-pin-interrupt' property value of
+ GPIO pin configuration, 8 is for GPIO GROUP0
+ interrupt, 9 is for GPIO GROUP1 interrupt
+ - The second cell is used to specify interrupt type
+
+ gpio-ranges: true
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - gpio-controller
+ - '#gpio-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/lpc18xx-ccu.h>
+
+ gpio@400f4000 {
+ compatible = "nxp,lpc1850-gpio";
+ reg = <0x400f4000 0x4000>, <0x40087000 0x1000>,
+ <0x40088000 0x1000>, <0x40089000 0x1000>;
+ reg-names = "gpio", "gpio-pin-ic", "gpio-group0-ic", "gpio-gpoup1-ic";
+ clocks = <&ccu1 CLK_CPU_GPIO>;
+ resets = <&rgu 28>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+
diff --git a/Documentation/devicetree/bindings/gpio/nxp,lpc3220-gpio.yaml b/Documentation/devicetree/bindings/gpio/nxp,lpc3220-gpio.yaml
new file mode 100644
index 000000000000..25b5494393cc
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/nxp,lpc3220-gpio.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/nxp,lpc3220-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP LPC3220 SoC GPIO controller
+
+maintainers:
+ - Animesh Agarwal <animeshagarwal28@gmail.com>
+
+properties:
+ compatible:
+ const: nxp,lpc3220-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 3
+ description: |
+ 1) bank:
+ 0: GPIO P0
+ 1: GPIO P1
+ 2: GPIO P2
+ 3: GPIO P3
+ 4: GPI P3
+ 5: GPO P3
+ 2) pin number
+ 3) flags:
+ - bit 0 specifies polarity (0 for normal, 1 for inverted)
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@40028000 {
+ compatible = "nxp,lpc3220-gpio";
+ reg = <0x40028000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <3>; /* bank, pin, flags */
+ };
diff --git a/Documentation/devicetree/bindings/gpio/nxp,pcf8575.yaml b/Documentation/devicetree/bindings/gpio/nxp,pcf8575.yaml
index f0ff66c4c74e..5a6ecaa7b44b 100644
--- a/Documentation/devicetree/bindings/gpio/nxp,pcf8575.yaml
+++ b/Documentation/devicetree/bindings/gpio/nxp,pcf8575.yaml
@@ -39,6 +39,10 @@ properties:
reg:
maxItems: 1
+ gpio-line-names:
+ minItems: 1
+ maxItems: 16
+
gpio-controller: true
'#gpio-cells':
@@ -69,6 +73,43 @@ properties:
wakeup-source: true
+ reset-gpios:
+ maxItems: 1
+ description:
+ GPIO controlling the (reset active LOW) RESET# pin.
+
+ The active polarity of the GPIO must translate to the low state of the
+ RESET# pin on the IC, i.e. if a GPIO is directly routed to the RESET# pin
+ without any inverter, GPIO_ACTIVE_LOW is expected.
+
+ Performing a reset makes all lines initialized to their input (pulled-up)
+ state.
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - nxp,pca9670
+ - nxp,pca9671
+ - nxp,pca9672
+ - nxp,pca9673
+ then:
+ properties:
+ reset-gpios: false
+
+ # lines-initial-states XOR reset-gpios
+ # Performing a reset reinitializes all lines to a known state which
+ # may not match passed lines-initial-states
+ - if:
+ required:
+ - lines-initial-states
+ then:
+ properties:
+ reset-gpios: false
+
patternProperties:
"^(.+-hog(-[0-9]+)?)$":
type: object
@@ -87,17 +128,17 @@ additionalProperties: false
examples:
- |
i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- pcf8575: gpio@20 {
- compatible = "nxp,pcf8575";
- reg = <0x20>;
- interrupt-parent = <&irqpin2>;
- interrupts = <3 0>;
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@20 {
+ compatible = "nxp,pcf8575";
+ reg = <0x20>;
+ interrupt-parent = <&irqpin2>;
+ interrupts = <3 0>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
};
diff --git a/Documentation/devicetree/bindings/gpio/pisosr-gpio.yaml b/Documentation/devicetree/bindings/gpio/pisosr-gpio.yaml
new file mode 100644
index 000000000000..db98ba413fb6
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/pisosr-gpio.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/pisosr-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic Parallel-in/Serial-out Shift Register GPIO Driver
+
+description:
+ This binding describes generic parallel-in/serial-out shift register
+ devices that can be used for GPI (General Purpose Input). This includes
+ SN74165 serial-out shift registers and the SN65HVS88x series of
+ industrial serializers.
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - pisosr-gpio
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ ngpios:
+ maximum: 32
+ default: 8
+
+ load-gpios:
+ description:
+ GPIO pin specifier attached to load enable, this
+ pin is pulsed before reading from the device to
+ load input pin values into the device.
+
+ spi-cpol: true
+
+required:
+ - compatible
+ - gpio-controller
+ - '#gpio-cells'
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio@0 {
+ compatible = "pisosr-gpio";
+ reg = <0>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ load-gpios = <&gpio2 23 GPIO_ACTIVE_LOW>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/gpio/pl061-gpio.yaml b/Documentation/devicetree/bindings/gpio/pl061-gpio.yaml
index bd35cbf7fa09..c51e10680c0a 100644
--- a/Documentation/devicetree/bindings/gpio/pl061-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/pl061-gpio.yaml
@@ -60,9 +60,6 @@ properties:
required:
- compatible
- reg
- - interrupts
- - interrupt-controller
- - "#interrupt-cells"
- clocks
- "#gpio-cells"
- gpio-controller
diff --git a/Documentation/devicetree/bindings/gpio/qca,ar7100-gpio.yaml b/Documentation/devicetree/bindings/gpio/qca,ar7100-gpio.yaml
new file mode 100644
index 000000000000..519c4c2158f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/qca,ar7100-gpio.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/qca,ar7100-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Atheros AR7xxx/AR9xxx GPIO controller
+
+maintainers:
+ - Alban Bedel <albeu@free.fr>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: qca,ar9132-gpio
+ - const: qca,ar7100-gpio
+ - enum:
+ - qca,ar7100-gpio
+ - qca,ar9340-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ ngpios: true
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - ngpios
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@18040000 {
+ compatible = "qca,ar9132-gpio", "qca,ar7100-gpio";
+ reg = <0x18040000 0x30>;
+ interrupts = <2>;
+ ngpios = <22>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt b/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt
deleted file mode 100644
index ce97265e23ba..000000000000
--- a/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Raspberry Pi GPIO expander
-
-The Raspberry Pi 3 GPIO expander is controlled by the VC4 firmware. The
-firmware exposes a mailbox interface that allows the ARM core to control the
-GPIO lines on the expander.
-
-The Raspberry Pi GPIO expander node must be a child node of the Raspberry Pi
-firmware node.
-
-Required properties:
-
-- compatible : Should be "raspberrypi,firmware-gpio"
-- gpio-controller : Marks the device node as a gpio controller
-- #gpio-cells : Should be two. The first cell is the pin number, and
- the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
-
-Example:
-
-firmware: firmware-rpi {
- compatible = "raspberrypi,bcm2835-firmware";
- mboxes = <&mailbox>;
-
- expgpio: gpio {
- compatible = "raspberrypi,firmware-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- };
-};
diff --git a/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml b/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml
index 100f20cebd76..728099c65824 100644
--- a/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/realtek,otto-gpio.yaml
@@ -28,10 +28,11 @@ properties:
- enum:
- realtek,rtl8380-gpio
- realtek,rtl8390-gpio
+ - realtek,rtl9300-gpio
+ - realtek,rtl9310-gpio
- const: realtek,otto-gpio
- reg:
- maxItems: 1
+ reg: true
"#gpio-cells":
const: 2
@@ -50,6 +51,23 @@ properties:
interrupts:
maxItems: 1
+if:
+ properties:
+ compatible:
+ contains:
+ const: realtek,rtl9300-gpio
+then:
+ properties:
+ reg:
+ items:
+ - description: GPIO and interrupt control
+ - description: interrupt CPU map
+else:
+ properties:
+ reg:
+ items:
+ - description: GPIO and interrupt control
+
required:
- compatible
- reg
@@ -63,7 +81,7 @@ dependencies:
examples:
- |
- gpio@3500 {
+ gpio@3500 {
compatible = "realtek,rtl8380-gpio", "realtek,otto-gpio";
reg = <0x3500 0x1c>;
gpio-controller;
@@ -73,6 +91,18 @@ examples:
#interrupt-cells = <2>;
interrupt-parent = <&rtlintc>;
interrupts = <23>;
- };
+ };
+ - |
+ gpio@3300 {
+ compatible = "realtek,rtl9300-gpio", "realtek,otto-gpio";
+ reg = <0x3300 0x1c>, <0x3338 0x8>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ ngpios = <24>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&rtlintc>;
+ interrupts = <13>;
+ };
...
diff --git a/Documentation/devicetree/bindings/gpio/realtek,rtd-gpio.yaml b/Documentation/devicetree/bindings/gpio/realtek,rtd-gpio.yaml
new file mode 100644
index 000000000000..dd768db37a98
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/realtek,rtd-gpio.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2023 Realtek Semiconductor Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/realtek,rtd-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek DHC GPIO controller
+
+maintainers:
+ - Tzuyi Chang <tychang@realtek.com>
+
+description:
+ The GPIO controller is designed for the Realtek DHC (Digital Home Center)
+ RTD series SoC family, which are high-definition media processor SoCs.
+
+properties:
+ compatible:
+ enum:
+ - realtek,rtd1295-misc-gpio
+ - realtek,rtd1295-iso-gpio
+ - realtek,rtd1315e-iso-gpio
+ - realtek,rtd1319-iso-gpio
+ - realtek,rtd1319d-iso-gpio
+ - realtek,rtd1395-iso-gpio
+ - realtek,rtd1619-iso-gpio
+ - realtek,rtd1619b-iso-gpio
+
+ reg:
+ items:
+ - description: GPIO controller registers
+ - description: GPIO interrupt registers
+
+ interrupts:
+ items:
+ - description: Interrupt number of the assert GPIO interrupt, which is
+ triggered when there is a rising edge.
+ - description: Interrupt number of the deassert GPIO interrupt, which is
+ triggered when there is a falling edge.
+
+ gpio-ranges: true
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - gpio-ranges
+ - gpio-controller
+ - "#gpio-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@100 {
+ compatible = "realtek,rtd1319d-iso-gpio";
+ reg = <0x100 0x100>,
+ <0x0 0xb0>;
+ interrupt-parent = <&iso_irq_mux>;
+ interrupts = <19>, <20>;
+ gpio-ranges = <&pinctrl 0 0 82>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/renesas,em-gio.yaml b/Documentation/devicetree/bindings/gpio/renesas,em-gio.yaml
index 8bdef812c87c..49fb8f613ead 100644
--- a/Documentation/devicetree/bindings/gpio/renesas,em-gio.yaml
+++ b/Documentation/devicetree/bindings/gpio/renesas,em-gio.yaml
@@ -57,14 +57,14 @@ examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
gpio0: gpio@e0050000 {
- compatible = "renesas,em-gio";
- reg = <0xe0050000 0x2c>, <0xe0050040 0x20>;
- interrupts = <GIC_SPI 67 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 68 IRQ_TYPE_LEVEL_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
- gpio-ranges = <&pfc 0 0 32>;
- ngpios = <32>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "renesas,em-gio";
+ reg = <0xe0050000 0x2c>, <0xe0050040 0x20>;
+ interrupts = <GIC_SPI 67 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 68 IRQ_TYPE_LEVEL_HIGH>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pfc 0 0 32>;
+ ngpios = <32>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
diff --git a/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml b/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml
index f2541739ee3b..d32e103a64aa 100644
--- a/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml
@@ -49,7 +49,12 @@ properties:
- const: renesas,rcar-gen3-gpio # R-Car Gen3 or RZ/G2
- items:
- - const: renesas,gpio-r8a779a0 # R-Car V3U
+ - enum:
+ - renesas,gpio-r8a779a0 # R-Car V3U
+ - renesas,gpio-r8a779f0 # R-Car S4-8
+ - renesas,gpio-r8a779g0 # R-Car V4H
+ - renesas,gpio-r8a779h0 # R-Car V4M
+ - const: renesas,rcar-gen4-gpio # R-Car Gen4
reg:
maxItems: 1
@@ -133,16 +138,16 @@ examples:
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/power/r8a77470-sysc.h>
gpio3: gpio@e6053000 {
- compatible = "renesas,gpio-r8a77470", "renesas,rcar-gen2-gpio";
- reg = <0xe6053000 0x50>;
- interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 909>;
- power-domains = <&sysc R8A77470_PD_ALWAYS_ON>;
- resets = <&cpg 909>;
- gpio-controller;
- #gpio-cells = <2>;
- gpio-ranges = <&pfc 0 96 30>;
- gpio-reserved-ranges = <17 10>;
- interrupt-controller;
- #interrupt-cells = <2>;
+ compatible = "renesas,gpio-r8a77470", "renesas,rcar-gen2-gpio";
+ reg = <0xe6053000 0x50>;
+ interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 909>;
+ power-domains = <&sysc R8A77470_PD_ALWAYS_ON>;
+ resets = <&cpg 909>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio-ranges = <&pfc 0 96 30>;
+ gpio-reserved-ranges = <17 10>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
};
diff --git a/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml b/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml
index d993e002cebe..bdd83f42615c 100644
--- a/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml
+++ b/Documentation/devicetree/bindings/gpio/rockchip,gpio-bank.yaml
@@ -22,10 +22,17 @@ properties:
maxItems: 1
clocks:
- maxItems: 1
+ minItems: 1
+ items:
+ - description: APB interface clock source
+ - description: GPIO debounce reference clock source
+
+ gpio-ranges: true
gpio-controller: true
+ gpio-line-names: true
+
"#gpio-cells":
const: 2
@@ -34,6 +41,16 @@ properties:
"#interrupt-cells":
const: 2
+ power-domains:
+ maxItems: 1
+
+patternProperties:
+ "^.+-hog(-[0-9]+)?$":
+ type: object
+
+ required:
+ - gpio-hog
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/gpio/rockchip,rk3328-grf-gpio.yaml b/Documentation/devicetree/bindings/gpio/rockchip,rk3328-grf-gpio.yaml
deleted file mode 100644
index d8cce73ea0ae..000000000000
--- a/Documentation/devicetree/bindings/gpio/rockchip,rk3328-grf-gpio.yaml
+++ /dev/null
@@ -1,50 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/gpio/rockchip,rk3328-grf-gpio.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Rockchip RK3328 General Register Files GPIO controller
-
-description:
- The Rockchip RK3328 General Register File (GRF) outputs only the
- GPIO_MUTE pin, originally for codec mute control, but it can also be used
- for general purpose. It is manipulated by the GRF_SOC_CON10 register.
- If needed in the future support for the HDMI pins can also be added.
- The GPIO node should be declared as the child of the GRF node.
-
- The GPIO_MUTE pin is referred to in the format
-
- <&grf_gpio 0 GPIO_ACTIVE_LOW>
-
- The first cell is the pin number and
- the second cell is used to specify the GPIO polarity
- 0 = Active high
- 1 = Active low
-
-maintainers:
- - Heiko Stuebner <heiko@sntech.de>
-
-properties:
- compatible:
- const: rockchip,rk3328-grf-gpio
-
- gpio-controller: true
-
- "#gpio-cells":
- const: 2
-
-required:
- - compatible
- - gpio-controller
- - "#gpio-cells"
-
-additionalProperties: false
-
-examples:
- - |
- grf_gpio: gpio {
- compatible = "rockchip,rk3328-grf-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt
deleted file mode 100644
index be329ea4794f..000000000000
--- a/Documentation/devicetree/bindings/gpio/sgpio-aspeed.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-Aspeed SGPIO controller Device Tree Bindings
---------------------------------------------
-
-This SGPIO controller is for ASPEED AST2500 SoC, it supports up to 80 full
-featured Serial GPIOs. Each of the Serial GPIO pins can be programmed to
-support the following options:
-- Support interrupt option for each input port and various interrupt
- sensitivity option (level-high, level-low, edge-high, edge-low)
-- Support reset tolerance option for each output port
-- Directly connected to APB bus and its shift clock is from APB bus clock
- divided by a programmable value.
-- Co-work with external signal-chained TTL components (74LV165/74LV595)
-
-Required properties:
-
-- compatible : Should be one of
- "aspeed,ast2400-sgpio", "aspeed,ast2500-sgpio"
-- #gpio-cells : Should be 2, see gpio.txt
-- reg : Address and length of the register set for the device
-- gpio-controller : Marks the device node as a GPIO controller
-- interrupts : Interrupt specifier, see interrupt-controller/interrupts.txt
-- interrupt-controller : Mark the GPIO controller as an interrupt-controller
-- ngpios : number of *hardware* GPIO lines, see gpio.txt. This will expose
- 2 software GPIOs per hardware GPIO: one for hardware input, one for hardware
- output. Up to 80 pins, must be a multiple of 8.
-- clocks : A phandle to the APB clock for SGPM clock division
-- bus-frequency : SGPM CLK frequency
-
-The sgpio and interrupt properties are further described in their respective
-bindings documentation:
-
-- Documentation/devicetree/bindings/gpio/gpio.txt
-- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-
- Example:
- sgpio: sgpio@1e780200 {
- #gpio-cells = <2>;
- compatible = "aspeed,ast2500-sgpio";
- gpio-controller;
- interrupts = <40>;
- reg = <0x1e780200 0x0100>;
- clocks = <&syscon ASPEED_CLK_APB>;
- interrupt-controller;
- ngpios = <8>;
- bus-frequency = <12000000>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml
index c2902aac2514..4bdc201b719e 100644
--- a/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/sifive,gpio.yaml
@@ -7,7 +7,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: SiFive GPIO controller
maintainers:
- - Yash Shah <yash.shah@sifive.com>
- Paul Walmsley <paul.walmsley@sifive.com>
properties:
@@ -47,6 +46,10 @@ properties:
maximum: 32
default: 16
+ gpio-line-names:
+ minItems: 1
+ maxItems: 32
+
gpio-controller: true
required:
@@ -73,17 +76,18 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/clock/sifive-fu540-prci.h>
- gpio@10060000 {
+ #include <dt-bindings/clock/sifive-fu540-prci.h>
+ gpio@10060000 {
compatible = "sifive,fu540-c000-gpio", "sifive,gpio0";
interrupt-parent = <&plic>;
- interrupts = <7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22>;
+ interrupts = <7>, <8>, <9>, <10>, <11>, <12>, <13>, <14>, <15>, <16>,
+ <17>, <18>, <19>, <20>, <21>, <22>;
reg = <0x10060000 0x1000>;
- clocks = <&tlclk PRCI_CLK_TLCLK>;
+ clocks = <&tlclk FU540_PRCI_CLK_TLCLK>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
- };
+ };
...
diff --git a/Documentation/devicetree/bindings/gpio/snps,creg-gpio.txt b/Documentation/devicetree/bindings/gpio/snps,creg-gpio.txt
deleted file mode 100644
index 1b30812b015b..000000000000
--- a/Documentation/devicetree/bindings/gpio/snps,creg-gpio.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Synopsys GPIO via CREG (Control REGisters) driver
-
-Required properties:
-- compatible : "snps,creg-gpio-hsdk" or "snps,creg-gpio-axs10x".
-- reg : Exactly one register range with length 0x4.
-- #gpio-cells : Since the generic GPIO binding is used, the
- amount of cells must be specified as 2. The first cell is the
- pin number, the second cell is used to specify optional parameters:
- See "gpio-specifier" in .../devicetree/bindings/gpio/gpio.txt.
-- gpio-controller : Marks the device node as a GPIO controller.
-- ngpios: Number of GPIO pins.
-
-Example:
-
-gpio: gpio@f00014b0 {
- compatible = "snps,creg-gpio-hsdk";
- reg = <0xf00014b0 0x4>;
- gpio-controller;
- #gpio-cells = <2>;
- ngpios = <2>;
-};
diff --git a/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml b/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml
index b391cc1b4590..bba6f5b6606f 100644
--- a/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/snps,dw-apb-gpio.yaml
@@ -9,7 +9,7 @@ title: Synopsys DesignWare APB GPIO controller
description: |
Synopsys DesignWare GPIO controllers have a configurable number of ports,
each of which are intended to be represented as child nodes with the generic
- GPIO-controller properties as desribed in this bindings file.
+ GPIO-controller properties as described in this bindings file.
maintainers:
- Hoan Tran <hoan@os.amperecomputing.com>
@@ -61,6 +61,12 @@ patternProperties:
'#gpio-cells':
const: 2
+ gpio-line-names:
+ minItems: 1
+ maxItems: 32
+
+ gpio-ranges: true
+
ngpios:
default: 32
minimum: 1
@@ -105,8 +111,8 @@ additionalProperties: false
required:
- compatible
- reg
- - "#address-cells"
- - "#size-cells"
+ - '#address-cells'
+ - '#size-cells'
examples:
- |
diff --git a/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml b/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml
index bcafa494ed7a..36f5a0610471 100644
--- a/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/socionext,uniphier-gpio.yaml
@@ -52,6 +52,12 @@ properties:
<child-interrupt-base parent-interrupt-base length> triplets.
$ref: /schemas/types.yaml#/definitions/uint32-matrix
+patternProperties:
+ "^.+-hog(-[0-9]+)?$":
+ type: object
+ required:
+ - gpio-hog
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/gpio/spacemit,k1-gpio.yaml b/Documentation/devicetree/bindings/gpio/spacemit,k1-gpio.yaml
new file mode 100644
index 000000000000..83e0b2d14c9f
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/spacemit,k1-gpio.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/spacemit,k1-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SpacemiT K1 GPIO controller
+
+maintainers:
+ - Yixun Lan <dlan@gentoo.org>
+
+description:
+ The controller's registers are organized as sets of eight 32-bit
+ registers with each set of port controlling 32 pins. A single
+ interrupt line is shared for all of the pins by the controller.
+
+properties:
+ $nodename:
+ pattern: "^gpio@[0-9a-f]+$"
+
+ compatible:
+ const: spacemit,k1-gpio
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: GPIO Core Clock
+ - description: GPIO Bus Clock
+
+ clock-names:
+ items:
+ - const: core
+ - const: bus
+
+ resets:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 3
+ description:
+ The first two cells are the GPIO bank index and offset inside the bank,
+ the third cell should specify GPIO flag.
+
+ gpio-ranges: true
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 3
+ description:
+ The first two cells are the GPIO bank index and offset inside the bank,
+ the third cell should specify interrupt flag. The controller does not
+ support level interrupts, so flags of IRQ_TYPE_LEVEL_HIGH,
+ IRQ_TYPE_LEVEL_LOW should not be used.
+ Refer <dt-bindings/interrupt-controller/irq.h> for valid flags.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - gpio-controller
+ - "#gpio-cells"
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+ - gpio-ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@d4019000 {
+ compatible = "spacemit,k1-gpio";
+ reg = <0xd4019000 0x800>;
+ clocks = <&ccu 9>, <&ccu 61>;
+ clock-names = "core", "bus";
+ gpio-controller;
+ #gpio-cells = <3>;
+ interrupts = <58>;
+ interrupt-controller;
+ interrupt-parent = <&plic>;
+ #interrupt-cells = <3>;
+ gpio-ranges = <&pinctrl 0 0 0 32>,
+ <&pinctrl 1 0 32 32>,
+ <&pinctrl 2 0 64 32>,
+ <&pinctrl 3 0 96 32>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/spear_spics.txt b/Documentation/devicetree/bindings/gpio/spear_spics.txt
deleted file mode 100644
index dd04d96e6ff1..000000000000
--- a/Documentation/devicetree/bindings/gpio/spear_spics.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-=== ST Microelectronics SPEAr SPI CS Driver ===
-
-SPEAr platform provides a provision to control chipselects of ARM PL022 Prime
-Cell spi controller through its system registers, which otherwise remains under
-PL022 control. If chipselect remain under PL022 control then they would be
-released as soon as transfer is over and TxFIFO becomes empty. This is not
-desired by some of the device protocols above spi which expect (multiple)
-transfers without releasing their chipselects.
-
-Chipselects can be controlled by software by turning them as GPIOs. SPEAr
-provides another interface through system registers through which software can
-directly control each PL022 chipselect. Hence, it is natural for SPEAr to export
-the control of this interface as gpio.
-
-Required properties:
-
- * compatible: should be defined as "st,spear-spics-gpio"
- * reg: mentioning address range of spics controller
- * st-spics,peripcfg-reg: peripheral configuration register offset
- * st-spics,sw-enable-bit: bit offset to enable sw control
- * st-spics,cs-value-bit: bit offset to drive chipselect low or high
- * st-spics,cs-enable-mask: chip select number bit mask
- * st-spics,cs-enable-shift: chip select number program offset
- * gpio-controller: Marks the device node as gpio controller
- * #gpio-cells: should be 1 and will mention chip select number
-
-All the above bit offsets are within peripcfg register.
-
-Example:
--------
-spics: spics@e0700000{
- compatible = "st,spear-spics-gpio";
- reg = <0xe0700000 0x1000>;
- st-spics,peripcfg-reg = <0x3b0>;
- st-spics,sw-enable-bit = <12>;
- st-spics,cs-value-bit = <11>;
- st-spics,cs-enable-mask = <3>;
- st-spics,cs-enable-shift = <8>;
- gpio-controller;
- #gpio-cells = <2>;
-};
-
-
-spi0: spi@e0100000 {
- num-cs = <3>;
- cs-gpios = <&gpio1 7 0>, <&spics 0>,
- <&spics 1>;
- ...
-}
diff --git a/Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml b/Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml
new file mode 100644
index 000000000000..99fcf970773a
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/sprd,gpio-eic.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2022 Unisoc Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/sprd,gpio-eic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Unisoc EIC controller
+
+maintainers:
+ - Orson Zhai <orsonzhai@gmail.com>
+ - Baolin Wang <baolin.wang7@gmail.com>
+ - Chunyan Zhang <zhang.lyra@gmail.com>
+
+description: |
+ The EIC is the abbreviation of external interrupt controller, which can
+ be used only in input mode. The Spreadtrum platform has 2 EIC controllers,
+ one is in digital chip, and another one is in PMIC. The digital chip EIC
+ controller contains 4 sub-modules, i.e. EIC-debounce, EIC-latch, EIC-async and
+ EIC-sync. But the PMIC EIC controller contains only one EIC-debounce sub-
+ module.
+
+ The EIC-debounce sub-module provides up to 8 source input signal
+ connections. A debounce mechanism is used to capture the input signals'
+ stable status (millisecond resolution) and a single-trigger mechanism
+ is introduced into this sub-module to enhance the input event detection
+ reliability. In addition, this sub-module's clock can be shut off
+ automatically to reduce power dissipation. Moreover the debounce range
+ is from 1ms to 4s with a step size of 1ms. The input signal will be
+ ignored if it is asserted for less than 1 ms.
+
+ The EIC-latch sub-module is used to latch some special power down signals
+ and generate interrupts, since the EIC-latch does not depend on the APB
+ clock to capture signals.
+
+ The EIC-async sub-module uses a 32kHz clock to capture the short signals
+ (microsecond resolution) to generate interrupts by level or edge trigger.
+
+ The EIC-sync is similar with GPIO's input function, which is a synchronized
+ signal input register. It can generate interrupts by level or edge trigger
+ when detecting input signals.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - sprd,sc9860-eic-debounce
+ - sprd,sc9860-eic-latch
+ - sprd,sc9860-eic-async
+ - sprd,sc9860-eic-sync
+ - sprd,sc2731-eic
+ - items:
+ - enum:
+ - sprd,ums512-eic-debounce
+ - const: sprd,sc9860-eic-debounce
+ - items:
+ - enum:
+ - sprd,ums512-eic-latch
+ - const: sprd,sc9860-eic-latch
+ - items:
+ - enum:
+ - sprd,ums512-eic-async
+ - const: sprd,sc9860-eic-async
+ - items:
+ - enum:
+ - sprd,ums512-eic-sync
+ - const: sprd,sc9860-eic-sync
+ - items:
+ - enum:
+ - sprd,sc2730-eic
+ - const: sprd,sc2731-eic
+
+ reg:
+ minItems: 1
+ maxItems: 3
+ description:
+ EIC controller can support maximum 3 banks which has its own
+ address base.
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ interrupts:
+ maxItems: 1
+ description:
+ The interrupt shared by all GPIO lines for this controller.
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ eic_debounce: gpio@40210000 {
+ compatible = "sprd,sc9860-eic-debounce";
+ reg = <0 0x40210000 0 0x80>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/sprd,gpio.yaml b/Documentation/devicetree/bindings/gpio/sprd,gpio.yaml
new file mode 100644
index 000000000000..483168838128
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/sprd,gpio.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2022 Unisoc Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/sprd,gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Unisoc GPIO controller
+
+maintainers:
+ - Orson Zhai <orsonzhai@gmail.com>
+ - Baolin Wang <baolin.wang7@gmail.com>
+ - Chunyan Zhang <zhang.lyra@gmail.com>
+
+description: |
+ The controller's registers are organized as sets of sixteen 16-bit
+ registers with each set controlling a bank of up to 16 pins. A single
+ interrupt is shared for all of the banks handled by the controller.
+
+properties:
+ compatible:
+ oneOf:
+ - const: sprd,sc9860-gpio
+ - items:
+ - enum:
+ - sprd,ums512-gpio
+ - const: sprd,sc9860-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ interrupts:
+ maxItems: 1
+ description: The interrupt shared by all GPIO lines for this controller.
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - "#gpio-cells"
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ ap_gpio: gpio@40280000 {
+ compatible = "sprd,sc9860-gpio";
+ reg = <0 0x40280000 0 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpio/st,nomadik-gpio.yaml b/Documentation/devicetree/bindings/gpio/st,nomadik-gpio.yaml
new file mode 100644
index 000000000000..b3e8951959b5
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/st,nomadik-gpio.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/st,nomadik-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nomadik GPIO controller
+
+description:
+ The Nomadik GPIO driver handles Nomadik SoC GPIO blocks. This block has also
+ been called ST STA2X11. On the Nomadik platform, this driver is intertwined
+ with pinctrl-nomadik.
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+properties:
+ $nodename:
+ pattern: "^gpio@[0-9a-f]+$"
+
+ compatible:
+ enum:
+ - st,nomadik-gpio
+ - mobileye,eyeq5-gpio
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#gpio-cells":
+ const: 2
+
+ gpio-controller: true
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ gpio-bank:
+ description: System-wide GPIO bank index.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ st,supports-sleepmode:
+ description: Whether the controller can sleep or not.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ clocks:
+ maxItems: 1
+
+ gpio-ranges:
+ maxItems: 1
+
+ ngpios:
+ minimum: 0
+ maximum: 32
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#gpio-cells"
+ - gpio-controller
+ - interrupt-controller
+ - gpio-bank
+
+unevaluatedProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mobileye,eyeq5-gpio
+ then:
+ properties:
+ st,supports-sleepmode: false
+
+examples:
+ - |
+ gpio@8012e080 {
+ compatible = "st,nomadik-gpio";
+ reg = <0x8012e080 0x80>;
+ interrupts = <0 120 0x4>;
+ #gpio-cells = <2>;
+ gpio-controller;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ st,supports-sleepmode;
+ gpio-bank = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/st,spear-spics-gpio.yaml b/Documentation/devicetree/bindings/gpio/st,spear-spics-gpio.yaml
new file mode 100644
index 000000000000..3b0d2112da79
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/st,spear-spics-gpio.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/st,spear-spics-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST Microelectronics SPEAr SPI CS GPIO Controller
+
+maintainers:
+ - Viresh Kumar <vireshk@kernel.org>
+
+description: >
+ SPEAr platform provides a provision to control chipselects of ARM PL022 Prime
+ Cell spi controller through its system registers, which otherwise remains
+ under PL022 control. If chipselect remain under PL022 control then they would
+ be released as soon as transfer is over and TxFIFO becomes empty. This is not
+ desired by some of the device protocols above spi which expect (multiple)
+ transfers without releasing their chipselects.
+
+ Chipselects can be controlled by software by turning them as GPIOs. SPEAr
+ provides another interface through system registers through which software can
+ directly control each PL022 chipselect. Hence, it is natural for SPEAr to
+ export the control of this interface as gpio.
+
+properties:
+ compatible:
+ const: st,spear-spics-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ st-spics,peripcfg-reg:
+ description: Offset of the peripcfg register.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ st-spics,sw-enable-bit:
+ description: Bit offset to enable software chipselect control.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ st-spics,cs-value-bit:
+ description: Bit offset to drive chipselect low or high.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ st-spics,cs-enable-mask:
+ description: Bitmask selecting which chipselects to enable.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ st-spics,cs-enable-shift:
+ description: Bit shift for programming chipselect number.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - st-spics,peripcfg-reg
+ - st-spics,sw-enable-bit
+ - st-spics,cs-value-bit
+ - st-spics,cs-enable-mask
+ - st-spics,cs-enable-shift
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@e0700000 {
+ compatible = "st,spear-spics-gpio";
+ reg = <0xe0700000 0x1000>;
+ st-spics,peripcfg-reg = <0x3b0>;
+ st-spics,sw-enable-bit = <12>;
+ st-spics,cs-value-bit = <11>;
+ st-spics,cs-enable-mask = <3>;
+ st-spics,cs-enable-shift = <8>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml b/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml
new file mode 100644
index 000000000000..4555f1644a4d
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/st,stmpe-gpio.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/st,stmpe-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectonics Port Expander (STMPE) GPIO Block
+
+description:
+ STMicroelectronics Port Expander (STMPE) is a series of slow
+ bus controllers for various expanded peripherals such as GPIO, keypad,
+ touchscreen, ADC, PWM or rotator. It can contain one or several different
+ peripherals connected to SPI or I2C. These bindings pertain to the
+ GPIO portions of these expanders.
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+properties:
+ compatible:
+ const: st,stmpe-gpio
+
+ "#gpio-cells":
+ const: 2
+
+ "#interrupt-cells":
+ const: 2
+
+ gpio-controller: true
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 24
+
+ interrupt-controller: true
+
+ st,norequest-mask:
+ description:
+ A bitmask of GPIO lines that cannot be requested because for
+ for example not being connected to anything on the system
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+patternProperties:
+ "^.+-hog(-[0-9]+)?$":
+ type: object
+
+ required:
+ - gpio-hog
+
+additionalProperties: false
+
+required:
+ - compatible
+ - "#gpio-cells"
+ - "#interrupt-cells"
+ - gpio-controller
+ - interrupt-controller
diff --git a/Documentation/devicetree/bindings/gpio/ti,keystone-dsp-gpio.yaml b/Documentation/devicetree/bindings/gpio/ti,keystone-dsp-gpio.yaml
new file mode 100644
index 000000000000..59f81621408b
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/ti,keystone-dsp-gpio.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/ti,keystone-dsp-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Keystone 2 DSP GPIO controller
+
+maintainers:
+ - Grygorii Strashko <grygorii.strashko@ti.com>
+
+description: |
+ HOST OS userland running on ARM can send interrupts to DSP cores using
+ the DSP GPIO controller IP. It provides 28 IRQ signals per each DSP core.
+ This is one of the component used by the IPC mechanism used on Keystone SOCs.
+
+ For example TCI6638K2K SoC has 8 DSP GPIO controllers:
+ - 8 for C66x CorePacx CPUs 0-7
+
+ Keystone 2 DSP GPIO controller has specific features:
+ - each GPIO can be configured only as output pin;
+ - setting GPIO value to 1 causes IRQ generation on target DSP core;
+ - reading pin value returns 0 - if IRQ was handled or 1 - IRQ is still
+ pending.
+
+properties:
+ compatible:
+ const: ti,keystone-dsp-gpio
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ '#gpio-cells':
+ const: 2
+
+ gpio,syscon-dev:
+ description:
+ Phandle and offset of device's specific registers within the syscon state
+ control registers
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to syscon
+ - description: register offset within state control registers
+
+required:
+ - compatible
+ - reg
+ - gpio-controller
+ - '#gpio-cells'
+ - gpio,syscon-dev
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@240 {
+ compatible = "ti,keystone-dsp-gpio";
+ reg = <0x240 0x4>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ gpio,syscon-dev = <&devctrl 0x240>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml b/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml
index 7087e4a5013f..7b75d2f92f1b 100644
--- a/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/ti,omap-gpio.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/gpio/ti,omap-gpio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: OMAP GPIO controller bindings
+title: OMAP GPIO controller
maintainers:
- Grygorii Strashko <grygorii.strashko@ti.com>
@@ -58,14 +58,14 @@ properties:
deprecated: true
description:
Name of the hwmod associated with the GPIO. Needed on some legacy OMAP
- SoCs which have not been converted to the ti,sysc interconnect hierarachy.
+ SoCs which have not been converted to the ti,sysc interconnect hierarchy.
ti,no-reset-on-init:
$ref: /schemas/types.yaml#/definitions/flag
deprecated: true
description:
Do not reset on init. Used with ti,hwmods on some legacy OMAP SoCs which
- have not been converted to the ti,sysc interconnect hierarachy.
+ have not been converted to the ti,sysc interconnect hierarchy.
patternProperties:
"^(.+-hog(-[0-9]+)?)$":
diff --git a/Documentation/devicetree/bindings/gpio/ti,twl4030-gpio.yaml b/Documentation/devicetree/bindings/gpio/ti,twl4030-gpio.yaml
new file mode 100644
index 000000000000..96d50d14c071
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/ti,twl4030-gpio.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/ti,twl4030-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI TWL4030 GPIO controller
+
+maintainers:
+ - Aaro Koskinen <aaro.koskinen@iki.fi>
+ - Andreas Kemnade <andreas@kemnade.info>
+ - Kevin Hilman <khilman@baylibre.com>
+ - Roger Quadros <rogerq@kernel.org>
+ - Tony Lindgren <tony@atomide.com>
+
+properties:
+ compatible:
+ const: ti,twl4030-gpio
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupt-controller: true
+
+ ti,debounce:
+ description: Debounce control bits. Each bit corresponds to a GPIO pin.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ ti,mmc-cd:
+ description: MMC card detect control bits. Each bit corresponds to a GPIO pin for VMMC(n+1).
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ ti,pullups:
+ description: Pull-up control bits. Each bit corresponds to a GPIO pin.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ ti,pulldowns:
+ description: Pull-down control bits. Each bit corresponds to a GPIO pin.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ ti,use-leds:
+ type: boolean
+ description: Enables LEDA and LEDB outputs if set
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio {
+ compatible = "ti,twl4030-gpio";
+ #gpio-cells = <2>;
+ gpio-controller;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ ti,use-leds;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml b/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml
index 9ad470e01953..712063417bc8 100644
--- a/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml
+++ b/Documentation/devicetree/bindings/gpio/toshiba,gpio-visconti.yaml
@@ -43,28 +43,27 @@ required:
- gpio-controller
- interrupt-controller
- "#interrupt-cells"
- - interrupt-parent
additionalProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/irq.h>
- #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
- soc {
+ soc {
#address-cells = <2>;
#size-cells = <2>;
gpio: gpio@28020000 {
- compatible = "toshiba,gpio-tmpv7708";
- reg = <0 0x28020000 0 0x1000>;
- #gpio-cells = <0x2>;
- gpio-ranges = <&pmux 0 0 32>;
- gpio-controller;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupt-parent = <&gic>;
+ compatible = "toshiba,gpio-tmpv7708";
+ reg = <0 0x28020000 0 0x1000>;
+ #gpio-cells = <0x2>;
+ gpio-ranges = <&pmux 0 0 32>;
+ gpio-controller;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&gic>;
};
- };
+ };
...
diff --git a/Documentation/devicetree/bindings/gpio/trivial-gpio.yaml b/Documentation/devicetree/bindings/gpio/trivial-gpio.yaml
new file mode 100644
index 000000000000..3f4bbd57fc52
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/trivial-gpio.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/trivial-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Trivial 2-cell GPIO controllers
+
+maintainers:
+ - Bartosz Golaszewski <brgl@bgdev.pl>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - cirrus,ep7312-gpio
+ - const: cirrus,ep7209-gpio
+ - enum:
+ - apm,xgene-gpio
+ - cirrus,ep7209-gpio
+ - cznic,moxtet-gpio
+ - dlg,slg7xl45106
+ - fcs,fxl6408
+ - fsl,ls1046aqds-fpga-gpio-stat-pres2
+ - fsl,lx2160ardb-fpga-gpio-sfp
+ - gateworks,pld-gpio
+ - ibm,ppc4xx-gpio
+ - loongson,ls1x-gpio
+ - maxim,max77620
+ - nintendo,hollywood-gpio
+ - nxp,pca9570
+ - nxp,pca9571
+ - rockchip,rk3328-grf-gpio
+ - snps,creg-gpio-hsdk
+ - technologic,ts4800-gpio
+ - technologic,ts4900-gpio
+ - technologic,ts7970-gpio
+ - ti,741g125 # for 741G125 (1-bit Input),
+ - ti,741g174 # for 741G74 (1-bit Output),
+ - ti,742g125 # for 742G125 (2-bit Input),
+ - ti,7474 # for 7474 (2-bit Output),
+ - ti,74125 # for 74125 (4-bit Input),
+ - ti,74175 # for 74175 (4-bit Output),
+ - ti,74365 # for 74365 (6-bit Input),
+ - ti,74174 # for 74174 (6-bit Output),
+ - ti,74244 # for 74244 (8-bit Input),
+ - ti,74273 # for 74273 (8-bit Output),
+ - ti,741624 # for 741624 (16-bit Input),
+ - ti,7416374 # for 7416374 (16-bit Output).
+ - ti,lp3943-gpio
+ - ti,palmas-gpio
+ - ti,tpic2810
+ - ti,tps80036-gpio
+ - ti,tps65913-gpio
+ - ti,tps65914-gpio
+
+ reg:
+ maxItems: 1
+
+ '#gpio-cells':
+ const: 2
+
+ gpio-controller: true
+
+ gpio-line-names: true
+
+ ngpios: true
+
+ # Don't add more properties
+
+patternProperties:
+ "^(hog-[0-9]+|.+-hog(-[0-9]+)?)$":
+ type: object
+ required:
+ - gpio-hog
+
+required:
+ - compatible
+ - '#gpio-cells'
+ - gpio-controller
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - maxim,max77620
+ - rockchip,rk3328-grf-gpio
+ - ti,lp3943-gpio
+ - ti,palmas-gpio
+ - ti,tps80036-gpio
+ - ti,tps65913-gpio
+ - ti,tps65914-gpio
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio@1701c000 {
+ compatible = "apm,xgene-gpio";
+ reg = <0x1701c000 0x40>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt b/Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt
deleted file mode 100644
index 038c3a6a1f4d..000000000000
--- a/Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-Bindings for the Western Digital's MyBook Live memory-mapped GPIO controllers.
-
-The Western Digital MyBook Live has two memory-mapped GPIO controllers.
-Both GPIO controller only have a single 8-bit data register, where GPIO
-state can be read and/or written.
-
-Required properties:
- - compatible: should be "wd,mbl-gpio"
- - reg-names: must contain
- "dat" - data register
- - reg: address + size pairs describing the GPIO register sets;
- order must correspond with the order of entries in reg-names
- - #gpio-cells: must be set to 2. The first cell is the pin number and
- the second cell is used to specify the gpio polarity:
- 0 = active high
- 1 = active low
- - gpio-controller: Marks the device node as a gpio controller.
-
-Optional properties:
- - no-output: GPIOs are read-only.
-
-Examples:
- gpio0: gpio0@e0000000 {
- compatible = "wd,mbl-gpio";
- reg-names = "dat";
- reg = <0xe0000000 0x1>;
- #gpio-cells = <2>;
- gpio-controller;
- };
-
- gpio1: gpio1@e0100000 {
- compatible = "wd,mbl-gpio";
- reg-names = "dat";
- reg = <0xe0100000 0x1>;
- #gpio-cells = <2>;
- gpio-controller;
- no-output;
- };
diff --git a/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml b/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml
new file mode 100644
index 000000000000..5eeb29bcdd21
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/x-powers,axp209-gpio.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/x-powers,axp209-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: X-Powers AXP209 GPIO
+
+maintainers:
+ - Chen-Yu Tsai <wens@csie.org>
+
+properties:
+ "#gpio-cells":
+ const: 2
+ description: >
+ The first cell is the pin number and the second is the GPIO flags.
+
+ compatible:
+ oneOf:
+ - enum:
+ - x-powers,axp209-gpio
+ - x-powers,axp221-gpio
+ - x-powers,axp813-gpio
+ - items:
+ - enum:
+ - x-powers,axp223-gpio
+ - x-powers,axp809-gpio
+ - const: x-powers,axp221-gpio
+ - items:
+ - const: x-powers,axp803-gpio
+ - const: x-powers,axp813-gpio
+
+ gpio-controller: true
+
+patternProperties:
+ "^.*-pins?$":
+ $ref: /schemas/pinctrl/pinmux-node.yaml#
+ additionalProperties: false
+
+ properties:
+ pins:
+ items:
+ enum:
+ - GPIO0
+ - GPIO1
+ - GPIO2
+ - GPIO3
+
+ function:
+ enum:
+ - adc
+ - ldo
+ - gpio_in
+ - gpio_out
+
+required:
+ - compatible
+ - "#gpio-cells"
+ - gpio-controller
+
+additionalProperties: false
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/xlnx,gpio-xilinx.yaml b/Documentation/devicetree/bindings/gpio/xlnx,gpio-xilinx.yaml
new file mode 100644
index 000000000000..7af4eb2d1858
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/xlnx,gpio-xilinx.yaml
@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/xlnx,gpio-xilinx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx AXI GPIO controller
+
+maintainers:
+ - Neeli Srinivas <srinivas.neeli@amd.com>
+
+description:
+ The AXI GPIO design provides a general purpose input/output interface
+ to an AXI4-Lite interface. The AXI GPIO can be configured as either
+ a single or a dual-channel device. The width of each channel is
+ independently configurable. The channels can be configured to
+ generate an interrupt when a transition on any of their inputs occurs.
+
+properties:
+ compatible:
+ enum:
+ - xlnx,xps-gpio-1.00.a
+
+ reg:
+ maxItems: 1
+
+ "#gpio-cells":
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ gpio-controller: true
+
+ gpio-line-names:
+ description: strings describing the names of each gpio line
+ minItems: 1
+ maxItems: 64
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ clocks:
+ maxItems: 1
+
+ interrupt-names: true
+
+ xlnx,all-inputs:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This option sets this GPIO channel1 bits in input mode.
+
+ xlnx,all-inputs-2:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This option sets this GPIO channel2 bits in input mode.
+
+ xlnx,all-outputs:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This option sets this GPIO channel1 bits in output mode.
+
+ xlnx,all-outputs-2:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This option sets this GPIO channel2 bits in output mode.
+
+ xlnx,dout-default:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Sets the default value of all the enabled bits of
+ channel1.
+ default: 0
+
+ xlnx,dout-default-2:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Sets the default value of all the enabled bits of
+ channel2.
+ default: 0
+
+ xlnx,gpio-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The value defines the bit width of the GPIO channel1.
+ minimum: 1
+ maximum: 32
+ default: 32
+
+ xlnx,gpio2-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The value defines the bit width of the GPIO channel2.
+ minimum: 1
+ maximum: 32
+ default: 32
+
+ xlnx,interrupt-present:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This parameter enables interrupt control logic
+ and interrupt registers in GPIO module.
+ minimum: 0
+ maximum: 1
+ default: 0
+
+ xlnx,is-dual:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This parameter enables a second GPIO channel (GPIO2).
+ minimum: 0
+ maximum: 1
+ default: 0
+
+ xlnx,tri-default:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This value configures the input or output mode
+ of each bit of GPIO channel1.
+
+ xlnx,tri-default-2:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: This value configures the input or output mode
+ of each bit of GPIO channel2.
+
+required:
+ - reg
+ - compatible
+ - clocks
+ - gpio-controller
+ - "#gpio-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpio@a0020000 {
+ compatible = "xlnx,xps-gpio-1.00.a";
+ reg = <0xa0020000 0x10000>;
+ #gpio-cells = <2>;
+ #interrupt-cells = <0x2>;
+ clocks = <&zynqmp_clk 71>;
+ gpio-controller;
+ interrupt-controller;
+ interrupt-names = "ip2intc_irpt";
+ interrupt-parent = <&gic>;
+ interrupts = <0 89 4>;
+ xlnx,all-inputs = <0x0>;
+ xlnx,all-inputs-2 = <0x0>;
+ xlnx,all-outputs = <0x0>;
+ xlnx,all-outputs-2 = <0x0>;
+ xlnx,dout-default = <0x0>;
+ xlnx,dout-default-2 = <0x0>;
+ xlnx,gpio-width = <0x20>;
+ xlnx,gpio2-width = <0x20>;
+ xlnx,interrupt-present = <0x1>;
+ xlnx,is-dual = <0x1>;
+ xlnx,tri-default = <0xFFFFFFFF>;
+ xlnx,tri-default-2 = <0xFFFFFFFF>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml b/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml
new file mode 100644
index 000000000000..e13e9d6dd148
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpio/xlnx,zynqmp-gpio-modepin.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ZynqMP Mode Pin GPIO controller
+
+description:
+ PS_MODE is 4-bits boot mode pins sampled on POR deassertion. Mode Pin
+ GPIO controller with configurable from numbers of pins (from 0 to 3 per
+ PS_MODE). Every pin can be configured as input/output.
+
+maintainers:
+ - Radhey Shyam Pandey <radhey.shyam.pandey@amd.com>
+
+properties:
+ compatible:
+ const: xlnx,zynqmp-gpio-modepin
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+
+ label: true
+
+required:
+ - compatible
+ - gpio-controller
+ - "#gpio-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ zynqmp-firmware {
+ gpio {
+ compatible = "xlnx,zynqmp-gpio-modepin";
+ gpio-controller;
+ #gpio-cells = <2>;
+ label = "modepin";
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml b/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml
index a36aec27069c..59c79a6943ec 100644
--- a/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml
+++ b/Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml
@@ -2,8 +2,8 @@
# Copyright 2019 Bootlin
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/gpio/xylon,logicvc-gpio.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/gpio/xylon,logicvc-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Xylon LogiCVC GPIO controller
diff --git a/Documentation/devicetree/bindings/gpu/apple,agx.yaml b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
new file mode 100644
index 000000000000..05af942ad174
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/apple,agx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple SoC GPU
+
+maintainers:
+ - Sasha Finkelstein <fnkl.kernel@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - apple,agx-g13g
+ - apple,agx-g13s
+ - apple,agx-g14g
+ - apple,agx-g14s
+ - items:
+ - enum:
+ - apple,agx-g13c
+ - apple,agx-g13d
+ - const: apple,agx-g13s
+ - items:
+ - enum:
+ - apple,agx-g14c
+ - apple,agx-g14d
+ - const: apple,agx-g14s
+
+ reg:
+ items:
+ - description: GPU coprocessor control registers
+ - description: GPU block MMIO registers
+
+ reg-names:
+ items:
+ - const: asc
+ - const: sgx
+
+ power-domains:
+ maxItems: 1
+
+ mboxes:
+ maxItems: 1
+
+ memory-region:
+ items:
+ - description: Region containing GPU MMU TTBs
+ - description: Region containing GPU MMU page tables
+ - description:
+ Region containing a shared handoff structure for VM
+ management coordination
+ - description: Calibration blob. Mostly power-related configuration
+ - description: Calibration blob. Mostly GPU-related configuration
+ - description: Shared global variables with GPU firmware
+
+ memory-region-names:
+ items:
+ - const: ttbs
+ - const: pagetables
+ - const: handoff
+ - const: hw-cal-a
+ - const: hw-cal-b
+ - const: globals
+
+ apple,firmware-abi:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 3
+ description:
+ macOS version the current firmware is paired with, used to pick
+ the version of firmware ABI to be used.
+ Bootloader will overwrite this
+
+required:
+ - compatible
+ - reg
+ - mboxes
+ - memory-region
+ - apple,firmware-abi
+
+additionalProperties: false
+
+examples:
+ - |
+ gpu@6400000 {
+ compatible = "apple,agx-g13g";
+ reg = <0x6400000 0x40000>,
+ <0x4000000 0x1000000>;
+ reg-names = "asc", "sgx";
+ mboxes = <&agx_mbox>;
+ power-domains = <&ps_gfx>;
+ memory-region = <&uat_ttbs>, <&uat_pagetables>, <&uat_handoff>,
+ <&gpu_hw_cal_a>, <&gpu_hw_cal_b>, <&gpu_globals>;
+ memory-region-names = "ttbs", "pagetables", "handoff",
+ "hw-cal-a", "hw-cal-b", "globals";
+
+ apple,firmware-abi = <0 0 0>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml
index 0f73f436bea7..db49b8ff8c74 100644
--- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml
@@ -14,31 +14,63 @@ properties:
pattern: '^gpu@[a-f0-9]+$'
compatible:
- items:
- - enum:
- - amlogic,meson-g12a-mali
- - mediatek,mt8183-mali
- - realtek,rtd1619-mali
- - rockchip,px30-mali
- - const: arm,mali-bifrost # Mali Bifrost GPU model/revision is fully discoverable
+ oneOf:
+ - items:
+ - enum:
+ - allwinner,sun50i-h616-mali
+ - amlogic,meson-g12a-mali
+ - mediatek,mt8183-mali
+ - mediatek,mt8183b-mali
+ - mediatek,mt8186-mali
+ - mediatek,mt8365-mali
+ - realtek,rtd1619-mali
+ - renesas,r9a07g044-mali
+ - renesas,r9a07g054-mali
+ - renesas,r9a09g047-mali
+ - renesas,r9a09g056-mali
+ - renesas,r9a09g057-mali
+ - rockchip,px30-mali
+ - rockchip,rk3562-mali
+ - rockchip,rk3568-mali
+ - rockchip,rk3576-mali
+ - const: arm,mali-bifrost # Mali Bifrost GPU model/revision is fully discoverable
+ - items:
+ - enum:
+ - mediatek,mt8195-mali
+ - const: mediatek,mt8192-mali
+ - const: arm,mali-valhall-jm # Mali Valhall GPU model/revision is fully discoverable
+ - items:
+ - enum:
+ - allwinner,sun55i-a523-mali
+ - mediatek,mt8188-mali
+ - mediatek,mt8192-mali
+ - mediatek,mt8370-mali
+ - const: arm,mali-valhall-jm # Mali Valhall GPU model/revision is fully discoverable
reg:
maxItems: 1
interrupts:
+ minItems: 3
items:
- description: Job interrupt
- description: MMU interrupt
- description: GPU interrupt
+ - description: Event interrupt
interrupt-names:
+ minItems: 3
items:
- const: job
- const: mmu
- const: gpu
+ - const: event
clocks:
- maxItems: 1
+ minItems: 1
+ maxItems: 3
+
+ clock-names: true
mali-supply: true
@@ -48,16 +80,23 @@ properties:
power-domains:
minItems: 1
- maxItems: 3
+ maxItems: 5
+
+ power-domain-names:
+ minItems: 2
+ maxItems: 5
resets:
- maxItems: 2
+ minItems: 1
+ maxItems: 3
+
+ reset-names: true
"#cooling-cells":
const: 2
dynamic-power-coefficient:
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description:
A u32 value that represents the running time dynamic
power coefficient in units of uW/MHz/V^2. The
@@ -75,6 +114,13 @@ properties:
dma-coherent: true
+ nvmem-cell-names:
+ items:
+ - const: speed-bin
+
+ nvmem-cells:
+ maxItems: 1
+
required:
- compatible
- reg
@@ -91,8 +137,50 @@ allOf:
contains:
const: amlogic,meson-g12a-mali
then:
+ properties:
+ power-domains:
+ maxItems: 1
+ power-domain-names: false
+ required:
+ - resets
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r9a07g044-mali
+ - renesas,r9a07g054-mali
+ - renesas,r9a09g047-mali
+ - renesas,r9a09g056-mali
+ - renesas,r9a09g057-mali
+ then:
+ properties:
+ interrupts:
+ minItems: 4
+ interrupt-names:
+ minItems: 4
+ clocks:
+ minItems: 3
+ clock-names:
+ items:
+ - const: gpu
+ - const: bus
+ - const: bus_ace
+ power-domains:
+ maxItems: 1
+ power-domain-names: false
+ resets:
+ minItems: 3
+ reset-names:
+ items:
+ - const: rst
+ - const: axi_rst
+ - const: ace_rst
required:
+ - clock-names
+ - power-domains
- resets
+ - reset-names
- if:
properties:
compatible:
@@ -102,6 +190,7 @@ allOf:
properties:
power-domains:
minItems: 3
+ maxItems: 3
power-domain-names:
items:
- const: core0
@@ -114,9 +203,83 @@ allOf:
- power-domain-names
else:
properties:
+ sram-supply: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8183b-mali
+ - mediatek,mt8188-mali
+ then:
+ properties:
+ power-domains:
+ minItems: 3
+ maxItems: 3
+ power-domain-names:
+ items:
+ - const: core0
+ - const: core1
+ - const: core2
+ required:
+ - power-domains
+ - power-domain-names
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8186-mali
+ - mediatek,mt8370-mali
+ then:
+ properties:
+ power-domains:
+ minItems: 2
+ maxItems: 2
+ power-domain-names:
+ items:
+ - const: core0
+ - const: core1
+ required:
+ - power-domains
+ - power-domain-names
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8192-mali
+ then:
+ properties:
+ power-domains:
+ minItems: 5
+ power-domain-names:
+ items:
+ - const: core0
+ - const: core1
+ - const: core2
+ - const: core3
+ - const: core4
+ required:
+ - power-domains
+ - power-domain-names
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: rockchip,rk3568-mali
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ clock-names:
+ items:
+ - const: gpu
+ - const: bus
power-domains:
maxItems: 1
- sram-supply: false
+ power-domain-names: false
+ required:
+ - clock-names
examples:
- |
@@ -136,7 +299,7 @@ examples:
resets = <&reset 0>, <&reset 1>;
};
- gpu_opp_table: opp_table0 {
+ gpu_opp_table: opp-table {
compatible = "operating-points-v2";
opp-533000000 {
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml
index 696c17aedbbe..a7192622e120 100644
--- a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml
@@ -42,11 +42,21 @@ properties:
- const: arm,mali-t760
- items:
- enum:
+ - samsung,exynos7-mali
+ - const: samsung,exynos5433-mali
+ - const: arm,mali-t760
+ - items:
+ - enum:
+ - samsung,exynos7870-mali
+ - const: arm,mali-t830
+ - items:
+ - enum:
- rockchip,rk3399-mali
- const: arm,mali-t860
-
- # "arm,mali-t830"
- # "arm,mali-t880"
+ - items:
+ - enum:
+ - samsung,exynos8890-mali
+ - const: arm,mali-t880
reg:
maxItems: 1
@@ -74,7 +84,8 @@ properties:
- const: bus
mali-supply: true
- opp-table: true
+ opp-table:
+ type: object
power-domains:
maxItems: 1
@@ -91,7 +102,7 @@ properties:
dma-coherent: true
dynamic-power-coefficient:
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description:
A u32 value that represents the running time dynamic
power coefficient in units of uW/MHz/V^2. The
@@ -160,7 +171,7 @@ examples:
#cooling-cells = <2>;
};
- gpu_opp_table: opp_table0 {
+ gpu_opp_table: opp-table {
compatible = "operating-points-v2";
opp-533000000 {
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml
index eceaa176bd57..c8d0d9192d92 100644
--- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.yaml
@@ -29,10 +29,13 @@ properties:
- allwinner,sun50i-a64-mali
- rockchip,rk3036-mali
- rockchip,rk3066-mali
+ - rockchip,rk3128-mali
- rockchip,rk3188-mali
- rockchip,rk3228-mali
- samsung,exynos4210-mali
+ - st,stih410-mali
- stericsson,db8500-mali
+ - xlnx,zynqmp-mali
- const: arm,mali-400
- items:
- enum:
@@ -44,6 +47,7 @@ properties:
- hisilicon,hi6220-mali
- mediatek,mt7623-mali
- rockchip,rk3328-mali
+ - rockchip,rk3528-mali
- const: arm,mali-450
# "arm,mali-300"
@@ -101,7 +105,8 @@ properties:
mali-supply: true
- opp-table: true
+ opp-table:
+ type: object
power-domains:
maxItems: 1
@@ -144,6 +149,7 @@ allOf:
- rockchip,rk3188-mali
- rockchip,rk3228-mali
- rockchip,rk3328-mali
+ - rockchip,rk3528-mali
then:
required:
- resets
diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-valhall-csf.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-valhall-csf.yaml
new file mode 100644
index 000000000000..bee9faf1d3f8
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/arm,mali-valhall-csf.yaml
@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/arm,mali-valhall-csf.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali Valhall GPU
+
+maintainers:
+ - Liviu Dudau <liviu.dudau@arm.com>
+ - Boris Brezillon <boris.brezillon@collabora.com>
+
+properties:
+ $nodename:
+ pattern: '^gpu@[a-f0-9]+$'
+
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - mediatek,mt8196-mali
+ - nxp,imx95-mali # G310
+ - rockchip,rk3588-mali
+ - const: arm,mali-valhall-csf # Mali Valhall GPU model/revision is fully discoverable
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: Job interrupt
+ - description: MMU interrupt
+ - description: GPU interrupt
+
+ interrupt-names:
+ items:
+ - const: job
+ - const: mmu
+ - const: gpu
+
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: core
+ - enum:
+ - coregroup
+ - stacks
+ - const: stacks
+
+ mali-supply: true
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+ power-domains:
+ minItems: 1
+ maxItems: 5
+
+ power-domain-names:
+ minItems: 1
+ maxItems: 5
+
+ sram-supply: true
+
+ "#cooling-cells":
+ const: 2
+
+ dynamic-power-coefficient:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ A u32 value that represents the running time dynamic
+ power coefficient in units of uW/MHz/V^2. The
+ coefficient can either be calculated from power
+ measurements or derived by analysis.
+
+ The dynamic power consumption of the GPU is
+ proportional to the square of the Voltage (V) and
+ the clock frequency (f). The coefficient is used to
+ calculate the dynamic power as below -
+
+ Pdyn = dynamic-power-coefficient * V^2 * f
+
+ where voltage is in V, frequency is in MHz.
+
+ dma-coherent: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: rockchip,rk3588-mali
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ power-domains:
+ maxItems: 1
+ power-domain-names: false
+ required:
+ - mali-supply
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8196-mali
+ then:
+ properties:
+ mali-supply: false
+ sram-supply: false
+ operating-points-v2: false
+ power-domains:
+ maxItems: 1
+ power-domain-names: false
+ clocks:
+ maxItems: 2
+ clock-names:
+ items:
+ - const: core
+ - const: stacks
+ required:
+ - power-domains
+
+examples:
+ - |
+ #include <dt-bindings/clock/rockchip,rk3588-cru.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/rk3588-power.h>
+
+ gpu: gpu@fb000000 {
+ compatible = "rockchip,rk3588-mali", "arm,mali-valhall-csf";
+ reg = <0xfb000000 0x200000>;
+ interrupts = <GIC_SPI 92 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 93 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH 0>;
+ interrupt-names = "job", "mmu", "gpu";
+ clock-names = "core", "coregroup", "stacks";
+ clocks = <&cru CLK_GPU>, <&cru CLK_GPU_COREGROUP>,
+ <&cru CLK_GPU_STACKS>;
+ power-domains = <&power RK3588_PD_GPU>;
+ operating-points-v2 = <&gpu_opp_table>;
+ mali-supply = <&vdd_gpu_s0>;
+ sram-supply = <&vdd_gpu_mem_s0>;
+
+ gpu_opp_table: opp-table {
+ compatible = "operating-points-v2";
+ opp-300000000 {
+ opp-hz = /bits/ 64 <300000000>;
+ opp-microvolt = <675000 675000 850000>;
+ };
+ opp-400000000 {
+ opp-hz = /bits/ 64 <400000000>;
+ opp-microvolt = <675000 675000 850000>;
+ };
+ };
+ };
+ - |
+ gpu@48000000 {
+ compatible = "mediatek,mt8196-mali", "arm,mali-valhall-csf";
+ reg = <0x48000000 0x480000>;
+ clocks = <&gpufreq 0>, <&gpufreq 1>;
+ clock-names = "core", "stacks";
+ interrupts = <GIC_SPI 606 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 605 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 604 IRQ_TYPE_LEVEL_HIGH 0>;
+ interrupt-names = "job", "mmu", "gpu";
+ power-domains = <&gpufreq>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/gpu/aspeed,ast2400-gfx.yaml b/Documentation/devicetree/bindings/gpu/aspeed,ast2400-gfx.yaml
new file mode 100644
index 000000000000..20a4e00086ee
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/aspeed,ast2400-gfx.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/aspeed,ast2400-gfx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED GFX Display Controller
+
+maintainers:
+ - Joel Stanley <joel@jms.id.au>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - aspeed,ast2400-gfx
+ - aspeed,ast2500-gfx
+ - aspeed,ast2600-gfx
+ - const: syscon
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ memory-region:
+ maxItems: 1
+ description:
+ a reserved-memory region to use for the framebuffer.
+
+ syscon:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: Phandle to SCU
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - resets
+ - memory-region
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/aspeed-clock.h>
+
+ display@1e6e6000 {
+ compatible = "aspeed,ast2500-gfx", "syscon";
+ reg = <0x1e6e6000 0x1000>;
+ clocks = <&syscon ASPEED_CLK_GATE_D1CLK>;
+ resets = <&syscon ASPEED_RESET_CRT1>;
+ interrupts = <0x19>;
+ memory-region = <&gfx_memory>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/aspeed-gfx.txt b/Documentation/devicetree/bindings/gpu/aspeed-gfx.txt
deleted file mode 100644
index 958bdf962339..000000000000
--- a/Documentation/devicetree/bindings/gpu/aspeed-gfx.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Device tree configuration for the GFX display device on the ASPEED SoCs
-
-Required properties:
- - compatible
- * Must be one of the following:
- + aspeed,ast2500-gfx
- + aspeed,ast2400-gfx
- * In addition, the ASPEED pinctrl bindings require the 'syscon' property to
- be present
-
- - reg: Physical base address and length of the GFX registers
-
- - interrupts: interrupt number for the GFX device
-
- - clocks: clock number used to generate the pixel clock
-
- - resets: reset line that must be released to use the GFX device
-
- - memory-region:
- Phandle to a memory region to allocate from, as defined in
- Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
-
-
-Example:
-
-gfx: display@1e6e6000 {
- compatible = "aspeed,ast2500-gfx", "syscon";
- reg = <0x1e6e6000 0x1000>;
- reg-io-width = <4>;
- clocks = <&syscon ASPEED_CLK_GATE_D1CLK>;
- resets = <&syscon ASPEED_RESET_CRT1>;
- interrupts = <0x19>;
- memory-region = <&gfx_memory>;
-};
-
-gfx_memory: framebuffer {
- size = <0x01000000>;
- alignment = <0x01000000>;
- compatible = "shared-dma-pool";
- reusable;
-};
diff --git a/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.yaml b/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.yaml
index e6485f7b046f..43c6d2d72456 100644
--- a/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.yaml
+++ b/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/gpu/brcm,bcm-v3d.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Broadcom V3D GPU Bindings
+title: Broadcom V3D GPU
maintainers:
- - Eric Anholt <eric@anholt.net>
+ - Maíra Canal <mcanal@igalia.com>
- Nicolas Saenz Julienne <nsaenzjulienne@suse.de>
properties:
@@ -16,24 +16,18 @@ properties:
compatible:
enum:
+ - brcm,2711-v3d
+ - brcm,2712-v3d
- brcm,7268-v3d
- brcm,7278-v3d
reg:
- items:
- - description: hub register (required)
- - description: core0 register (required)
- - description: GCA cache controller register (if GCA controller present)
- - description: bridge register (if no external reset controller)
minItems: 2
+ maxItems: 4
reg-names:
- items:
- - const: hub
- - const: core0
- - enum: [ bridge, gca ]
- - enum: [ bridge, gca ]
minItems: 2
+ maxItems: 4
interrupts:
items:
@@ -56,6 +50,76 @@ required:
- reg-names
- interrupts
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,2711-v3d
+ then:
+ properties:
+ reg:
+ items:
+ - description: hub register
+ - description: core0 register
+ reg-names:
+ items:
+ - const: hub
+ - const: core0
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,2712-v3d
+ then:
+ properties:
+ reg:
+ items:
+ - description: hub register
+ - description: core0 register
+ - description: SMS state manager register
+ reg-names:
+ items:
+ - const: hub
+ - const: core0
+ - const: sms
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,7268-v3d
+ then:
+ properties:
+ reg:
+ items:
+ - description: hub register
+ - description: core0 register
+ - description: GCA cache controller register
+ - description: bridge register
+ reg-names:
+ items:
+ - const: hub
+ - const: core0
+ - const: gca
+ - const: bridge
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,7278-v3d
+ then:
+ properties:
+ reg:
+ items:
+ - description: hub register
+ - description: core0 register
+ - description: bridge register
+ reg-names:
+ items:
+ - const: hub
+ - const: core0
+ - const: bridge
+
additionalProperties: false
examples:
@@ -64,9 +128,9 @@ examples:
compatible = "brcm,7268-v3d";
reg = <0xf1200000 0x4000>,
<0xf1208000 0x4000>,
- <0xf1204000 0x100>,
- <0xf1204100 0x100>;
- reg-names = "hub", "core0", "bridge", "gca";
+ <0xf1204100 0x100>,
+ <0xf1204000 0x100>;
+ reg-names = "hub", "core0", "gca", "bridge";
interrupts = <0 78 4>,
<0 77 4>;
};
diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvdec.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvdec.yaml
new file mode 100644
index 000000000000..ba4c6473ff92
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvdec.yaml
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/host1x/nvidia,tegra210-nvdec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra NVDEC
+
+description: |
+ NVDEC is the hardware video decoder present on NVIDIA Tegra210
+ and newer chips. It is located on the Host1x bus and typically
+ programmed through Host1x channels.
+
+maintainers:
+ - Thierry Reding <treding@gmail.com>
+ - Mikko Perttunen <mperttunen@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^nvdec@[0-9a-f]*$"
+
+ compatible:
+ enum:
+ - nvidia,tegra210-nvdec
+ - nvidia,tegra186-nvdec
+ - nvidia,tegra194-nvdec
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: nvdec
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: nvdec
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ dma-coherent: true
+
+ interconnects:
+ items:
+ - description: DMA read memory client
+ - description: DMA read 2 memory client
+ - description: DMA write memory client
+
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: read-1
+ - const: write
+
+ nvidia,host1x-class:
+ description: |
+ Host1x class of the engine, used to specify the targeted engine
+ when programming the engine through Host1x channels or when
+ configuring engine-specific behavior in Host1x.
+ default: 0xf0
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - power-domains
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra186-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/memory/tegra186-mc.h>
+ #include <dt-bindings/power/tegra186-powergate.h>
+ #include <dt-bindings/reset/tegra186-reset.h>
+
+ nvdec@15480000 {
+ compatible = "nvidia,tegra186-nvdec";
+ reg = <0x15480000 0x40000>;
+ clocks = <&bpmp TEGRA186_CLK_NVDEC>;
+ clock-names = "nvdec";
+ resets = <&bpmp TEGRA186_RESET_NVDEC>;
+ reset-names = "nvdec";
+
+ power-domains = <&bpmp TEGRA186_POWER_DOMAIN_NVDEC>;
+ interconnects = <&mc TEGRA186_MEMORY_CLIENT_NVDECSRD &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_NVDECSRD1 &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_NVDECSWR &emc>;
+ interconnect-names = "dma-mem", "read-1", "write";
+ iommus = <&smmu TEGRA186_SID_NVDEC>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml
new file mode 100644
index 000000000000..c23dae713eb8
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvenc.yaml
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/host1x/nvidia,tegra210-nvenc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra NVENC
+
+description: |
+ NVENC is the hardware video encoder present on NVIDIA Tegra210
+ and newer chips. It is located on the Host1x bus and typically
+ programmed through Host1x channels.
+
+maintainers:
+ - Thierry Reding <treding@gmail.com>
+ - Mikko Perttunen <mperttunen@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^nvenc@[0-9a-f]*$"
+
+ compatible:
+ enum:
+ - nvidia,tegra210-nvenc
+ - nvidia,tegra186-nvenc
+ - nvidia,tegra194-nvenc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: nvenc
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: nvenc
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ dma-coherent: true
+
+ interconnects:
+ minItems: 2
+ maxItems: 3
+
+ interconnect-names:
+ minItems: 2
+ maxItems: 3
+
+ nvidia,host1x-class:
+ description: |
+ Host1x class of the engine, used to specify the targeted engine
+ when programming the engine through Host1x channels or when
+ configuring engine-specific behavior in Host1x.
+ default: 0x21
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - power-domains
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - nvidia,tegra210-nvenc
+ - nvidia,tegra186-nvenc
+ then:
+ properties:
+ interconnects:
+ items:
+ - description: DMA read memory client
+ - description: DMA write memory client
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: write
+ - if:
+ properties:
+ compatible:
+ enum:
+ - nvidia,tegra194-nvenc
+ then:
+ properties:
+ interconnects:
+ items:
+ - description: DMA read memory client
+ - description: DMA read 2 memory client
+ - description: DMA write memory client
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: read-1
+ - const: write
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra186-clock.h>
+ #include <dt-bindings/memory/tegra186-mc.h>
+ #include <dt-bindings/power/tegra186-powergate.h>
+ #include <dt-bindings/reset/tegra186-reset.h>
+
+ nvenc@154c0000 {
+ compatible = "nvidia,tegra186-nvenc";
+ reg = <0x154c0000 0x40000>;
+ clocks = <&bpmp TEGRA186_CLK_NVENC>;
+ clock-names = "nvenc";
+ resets = <&bpmp TEGRA186_RESET_NVENC>;
+ reset-names = "nvenc";
+
+ power-domains = <&bpmp TEGRA186_POWER_DOMAIN_MPE>;
+ interconnects = <&mc TEGRA186_MEMORY_CLIENT_NVENCSRD &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_NVENCSWR &emc>;
+ interconnect-names = "dma-mem", "write";
+ iommus = <&smmu TEGRA186_SID_NVENC>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml
new file mode 100644
index 000000000000..99a33a5eac3f
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra210-nvjpg.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/host1x/nvidia,tegra210-nvjpg.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra NVJPG
+
+description: |
+ NVJPG is the hardware JPEG decoder and encoder present on NVIDIA Tegra210
+ and newer chips. It is located on the Host1x bus and typically programmed
+ through Host1x channels.
+
+maintainers:
+ - Thierry Reding <treding@gmail.com>
+ - Mikko Perttunen <mperttunen@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^nvjpg@[0-9a-f]*$"
+
+ compatible:
+ enum:
+ - nvidia,tegra210-nvjpg
+ - nvidia,tegra186-nvjpg
+ - nvidia,tegra194-nvjpg
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: nvjpg
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: nvjpg
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ dma-coherent: true
+
+ interconnects:
+ items:
+ - description: DMA read memory client
+ - description: DMA write memory client
+
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: write
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - power-domains
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra186-clock.h>
+ #include <dt-bindings/memory/tegra186-mc.h>
+ #include <dt-bindings/power/tegra186-powergate.h>
+ #include <dt-bindings/reset/tegra186-reset.h>
+
+ nvjpg@15380000 {
+ compatible = "nvidia,tegra186-nvjpg";
+ reg = <0x15380000 0x40000>;
+ clocks = <&bpmp TEGRA186_CLK_NVJPG>;
+ clock-names = "nvjpg";
+ resets = <&bpmp TEGRA186_RESET_NVJPG>;
+ reset-names = "nvjpg";
+
+ power-domains = <&bpmp TEGRA186_POWER_DOMAIN_NVJPG>;
+ interconnects = <&mc TEGRA186_MEMORY_CLIENT_NVJPGSRD &emc>,
+ <&mc TEGRA186_MEMORY_CLIENT_NVJPGSWR &emc>;
+ interconnect-names = "dma-mem", "write";
+ iommus = <&smmu TEGRA186_SID_NVJPG>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml
new file mode 100644
index 000000000000..0b7561c8b9bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/host1x/nvidia,tegra234-nvdec.yaml
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/host1x/nvidia,tegra234-nvdec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra234 NVDEC
+
+description: |
+ NVDEC is the hardware video decoder present on NVIDIA Tegra210
+ and newer chips. It is located on the Host1x bus and typically
+ programmed through Host1x channels.
+
+maintainers:
+ - Thierry Reding <treding@gmail.com>
+ - Mikko Perttunen <mperttunen@nvidia.com>
+
+properties:
+ $nodename:
+ pattern: "^nvdec@[0-9a-f]*$"
+
+ compatible:
+ enum:
+ - nvidia,tegra234-nvdec
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 3
+
+ clock-names:
+ items:
+ - const: nvdec
+ - const: fuse
+ - const: tsec_pka
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: nvdec
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ dma-coherent: true
+
+ interconnects:
+ items:
+ - description: DMA read memory client
+ - description: DMA write memory client
+
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: write
+
+ nvidia,memory-controller:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ phandle to the memory controller for determining information for the NVDEC
+ firmware secure carveout. This carveout is configured by the bootloader and
+ not accessible to CPU.
+
+ nvidia,bl-manifest-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Offset to bootloader manifest from beginning of firmware that was configured by
+ the bootloader.
+
+ nvidia,bl-code-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Offset to bootloader code section from beginning of firmware that was configured by
+ the bootloader.
+
+ nvidia,bl-data-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Offset to bootloader data section from beginning of firmware that was configured by
+ the bootloader.
+
+ nvidia,os-manifest-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Offset to operating system manifest from beginning of firmware that was configured by
+ the bootloader.
+
+ nvidia,os-code-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Offset to operating system code section from beginning of firmware that was configured by
+ the bootloader.
+
+ nvidia,os-data-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Offset to operating system data section from beginning of firmware that was configured
+ by the bootloader.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - power-domains
+ - nvidia,memory-controller
+ - nvidia,bl-manifest-offset
+ - nvidia,bl-code-offset
+ - nvidia,bl-data-offset
+ - nvidia,os-manifest-offset
+ - nvidia,os-code-offset
+ - nvidia,os-data-offset
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra234-clock.h>
+ #include <dt-bindings/memory/tegra234-mc.h>
+ #include <dt-bindings/power/tegra234-powergate.h>
+ #include <dt-bindings/reset/tegra234-reset.h>
+
+ nvdec@15480000 {
+ compatible = "nvidia,tegra234-nvdec";
+ reg = <0x15480000 0x00040000>;
+ clocks = <&bpmp TEGRA234_CLK_NVDEC>,
+ <&bpmp TEGRA234_CLK_FUSE>,
+ <&bpmp TEGRA234_CLK_TSEC_PKA>;
+ clock-names = "nvdec", "fuse", "tsec_pka";
+ resets = <&bpmp TEGRA234_RESET_NVDEC>;
+ reset-names = "nvdec";
+ power-domains = <&bpmp TEGRA234_POWER_DOMAIN_NVDEC>;
+ interconnects = <&mc TEGRA234_MEMORY_CLIENT_NVDECSRD &emc>,
+ <&mc TEGRA234_MEMORY_CLIENT_NVDECSWR &emc>;
+ interconnect-names = "dma-mem", "write";
+ iommus = <&smmu_niso1 TEGRA234_SID_NVDEC>;
+ dma-coherent;
+
+ nvidia,memory-controller = <&mc>;
+
+ /* Placeholder values, to be replaced with values from overlay */
+ nvidia,bl-manifest-offset = <0>;
+ nvidia,bl-data-offset = <0>;
+ nvidia,bl-code-offset = <0>;
+ nvidia,os-manifest-offset = <0>;
+ nvidia,os-data-offset = <0>;
+ nvidia,os-code-offset = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml b/Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml
new file mode 100644
index 000000000000..225a6e1b7fcd
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml
@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2023 Imagination Technologies Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/img,powervr-rogue.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Imagination Technologies PowerVR and IMG Rogue GPUs
+
+maintainers:
+ - Frank Binns <frank.binns@imgtec.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,r8a7796-gpu
+ - renesas,r8a77961-gpu
+ - const: img,img-gx6250
+ - const: img,img-rogue
+ - items:
+ - const: renesas,r8a77965-gpu
+ - const: img,img-ge7800
+ - const: img,img-rogue
+ - items:
+ - enum:
+ - ti,am62-gpu
+ - const: img,img-axe-1-16m
+ # This deprecated element must be kept around to allow old kernels to
+ # work with newer dts.
+ - const: img,img-axe
+ - const: img,img-rogue
+ - items:
+ - enum:
+ - thead,th1520-gpu
+ - const: img,img-bxm-4-64
+ - const: img,img-rogue
+ - items:
+ - enum:
+ - ti,j721s2-gpu
+ - const: img,img-bxs-4-64
+ - const: img,img-rogue
+
+ # This legacy combination of compatible strings was introduced early on
+ # before the more specific GPU identifiers were used.
+ - items:
+ - enum:
+ - ti,am62-gpu
+ - const: img,img-axe
+ deprecated: true
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ items:
+ - const: core
+ - const: mem
+ - const: sys
+ minItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ power-domains:
+ minItems: 1
+ maxItems: 2
+
+ power-domain-names:
+ items:
+ - const: a
+ - const: b
+ minItems: 1
+
+ dma-coherent: true
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,am62-gpu
+ - ti,j721s2-gpu
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - img,img-ge7800
+ - img,img-gx6250
+ - thead,th1520-gpu
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ clock-names:
+ minItems: 3
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: img,img-axe-1-16m
+ then:
+ properties:
+ power-domains:
+ maxItems: 1
+ power-domain-names:
+ maxItems: 1
+ required:
+ - power-domains
+ - power-domain-names
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - img,img-bxs-4-64
+ - img,img-ge7800
+ - img,img-gx6250
+ then:
+ properties:
+ power-domains:
+ minItems: 2
+ power-domain-names:
+ minItems: 2
+ required:
+ - power-domains
+ - power-domain-names
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: thead,th1520-gpu
+ then:
+ properties:
+ power-domains:
+ items:
+ - description: The single, unified power domain for the GPU on the
+ TH1520 SoC, integrating all internal IP power domains.
+ power-domain-names: false
+ required:
+ - power-domains
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+
+ gpu@fd00000 {
+ compatible = "ti,am62-gpu", "img,img-axe-1-16m", "img,img-axe",
+ "img,img-rogue";
+ reg = <0x0fd00000 0x20000>;
+ clocks = <&k3_clks 187 0>;
+ clock-names = "core";
+ interrupts = <GIC_SPI 86 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&k3_pds 187 TI_SCI_PD_EXCLUSIVE>;
+ power-domain-names = "a";
+ };
diff --git a/Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml b/Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml
new file mode 100644
index 000000000000..f5898b04381c
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml
@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2023 Imagination Technologies Ltd.
+# Copyright (C) 2024 Texas Instruments Incorporated - https://www.ti.com/
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/img,powervr-sgx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Imagination Technologies PowerVR SGX GPUs
+
+maintainers:
+ - Frank Binns <frank.binns@imgtec.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - ti,omap3430-gpu # Rev 121
+ - ti,omap3630-gpu # Rev 125
+ - const: img,powervr-sgx530
+ - items:
+ - enum:
+ - ingenic,jz4780-gpu # Rev 130
+ - ti,omap4430-gpu # Rev 120
+ - const: img,powervr-sgx540
+ - items:
+ - enum:
+ - allwinner,sun6i-a31-gpu # MP2 Rev 115
+ - ti,omap4470-gpu # MP1 Rev 112
+ - ti,omap5432-gpu # MP2 Rev 105
+ - ti,am5728-gpu # MP2 Rev 116
+ - ti,am6548-gpu # MP1 Rev 117
+ - const: img,powervr-sgx544
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: core
+ - const: mem
+ - const: sys
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,am6548-gpu
+ then:
+ required:
+ - power-domains
+ else:
+ properties:
+ power-domains: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - allwinner,sun6i-a31-gpu
+ - ingenic,jz4780-gpu
+ then:
+ required:
+ - clocks
+ - clock-names
+ else:
+ properties:
+ clocks: false
+ clock-names: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: allwinner,sun6i-a31-gpu
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ maxItems: 2
+ clock-names:
+ minItems: 2
+ maxItems: 2
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ingenic,jz4780-gpu
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ maxItems: 1
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+
+ gpu@7000000 {
+ compatible = "ti,am6548-gpu", "img,powervr-sgx544";
+ reg = <0x7000000 0x10000>;
+ interrupts = <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&k3_pds 65 TI_SCI_PD_EXCLUSIVE>;
+ };
+
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ gpu: gpu@1c40000 {
+ compatible = "allwinner,sun6i-a31-gpu", "img,powervr-sgx544";
+ reg = <0x01c40000 0x10000>;
+ interrupts = <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu 1>, <&ccu 2>;
+ clock-names = "core", "mem";
+ };
diff --git a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt
deleted file mode 100644
index cc6ce5221a38..000000000000
--- a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt
+++ /dev/null
@@ -1,115 +0,0 @@
-NVIDIA Tegra Graphics Processing Units
-
-Required properties:
-- compatible: "nvidia,<gpu>"
- Currently recognized values:
- - nvidia,gk20a
- - nvidia,gm20b
- - nvidia,gp10b
- - nvidia,gv11b
-- reg: Physical base address and length of the controller's registers.
- Must contain two entries:
- - first entry for bar0
- - second entry for bar1
-- interrupts: Must contain an entry for each entry in interrupt-names.
- See ../interrupt-controller/interrupts.txt for details.
-- interrupt-names: Must include the following entries:
- - stall
- - nonstall
-- vdd-supply: regulator for supply voltage. Only required for GPUs not using
- power domains.
-- clocks: Must contain an entry for each entry in clock-names.
- See ../clocks/clock-bindings.txt for details.
-- clock-names: Must include the following entries:
- - gpu
- - pwr
-If the compatible string is "nvidia,gm20b", then the following clock
-is also required:
- - ref
-If the compatible string is "nvidia,gv11b", then the following clock is also
-required:
- - fuse
-- resets: Must contain an entry for each entry in reset-names.
- See ../reset/reset.txt for details.
-- reset-names: Must include the following entries:
- - gpu
-- power-domains: GPUs that make use of power domains can define this property
- instead of vdd-supply. Currently "nvidia,gp10b" makes use of this.
-
-Optional properties:
-- iommus: A reference to the IOMMU. See ../iommu/iommu.txt for details.
-
-Example for GK20A:
-
- gpu@57000000 {
- compatible = "nvidia,gk20a";
- reg = <0x0 0x57000000 0x0 0x01000000>,
- <0x0 0x58000000 0x0 0x01000000>;
- interrupts = <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 158 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "stall", "nonstall";
- vdd-supply = <&vdd_gpu>;
- clocks = <&tegra_car TEGRA124_CLK_GPU>,
- <&tegra_car TEGRA124_CLK_PLL_P_OUT5>;
- clock-names = "gpu", "pwr";
- resets = <&tegra_car 184>;
- reset-names = "gpu";
- iommus = <&mc TEGRA_SWGROUP_GPU>;
- };
-
-Example for GM20B:
-
- gpu@57000000 {
- compatible = "nvidia,gm20b";
- reg = <0x0 0x57000000 0x0 0x01000000>,
- <0x0 0x58000000 0x0 0x01000000>;
- interrupts = <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 158 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "stall", "nonstall";
- clocks = <&tegra_car TEGRA210_CLK_GPU>,
- <&tegra_car TEGRA210_CLK_PLL_P_OUT5>,
- <&tegra_car TEGRA210_CLK_PLL_G_REF>;
- clock-names = "gpu", "pwr", "ref";
- resets = <&tegra_car 184>;
- reset-names = "gpu";
- iommus = <&mc TEGRA_SWGROUP_GPU>;
- };
-
-Example for GP10B:
-
- gpu@17000000 {
- compatible = "nvidia,gp10b";
- reg = <0x0 0x17000000 0x0 0x1000000>,
- <0x0 0x18000000 0x0 0x1000000>;
- interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH
- GIC_SPI 71 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "stall", "nonstall";
- clocks = <&bpmp TEGRA186_CLK_GPCCLK>,
- <&bpmp TEGRA186_CLK_GPU>;
- clock-names = "gpu", "pwr";
- resets = <&bpmp TEGRA186_RESET_GPU>;
- reset-names = "gpu";
- power-domains = <&bpmp TEGRA186_POWER_DOMAIN_GPU>;
- iommus = <&smmu TEGRA186_SID_GPU>;
- };
-
-Example for GV11B:
-
- gpu@17000000 {
- compatible = "nvidia,gv11b";
- reg = <0x17000000 0x1000000>,
- <0x18000000 0x1000000>;
- interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 71 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "stall", "nonstall";
- clocks = <&bpmp TEGRA194_CLK_GPCCLK>,
- <&bpmp TEGRA194_CLK_GPU_PWR>,
- <&bpmp TEGRA194_CLK_FUSE>;
- clock-names = "gpu", "pwr", "fuse";
- resets = <&bpmp TEGRA194_RESET_GPU>;
- reset-names = "gpu";
- dma-coherent;
-
- power-domains = <&bpmp TEGRA194_POWER_DOMAIN_GPU>;
- iommus = <&smmu TEGRA194_SID_GPU>;
- };
diff --git a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.yaml b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.yaml
new file mode 100644
index 000000000000..4d856a8b674c
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.yaml
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/nvidia,gk20a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra Graphics Processing Units
+
+maintainers:
+ - Alexandre Courbot <acourbot@nvidia.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Thierry Reding <treding@nvidia.com>
+
+properties:
+ compatible:
+ enum:
+ - nvidia,gk20a
+ - nvidia,gm20b
+ - nvidia,gp10b
+ - nvidia,gv11b
+
+ reg:
+ items:
+ - description: Bar0 register window
+ - description: Bar1 register window
+
+ interrupts:
+ items:
+ - description: Stall interrupt
+ - description: Nonstall interrupt
+
+ interrupt-names:
+ items:
+ - const: stall
+ - const: nonstall
+
+ vdd-supply:
+ description:
+ Regulator for GPU supply voltage
+
+ clocks:
+ minItems: 2
+ items:
+ - description: GPU clock
+ - description: Power clock
+ - description: Reference or fuse clock
+
+ clock-names:
+ minItems: 2
+ items:
+ - const: gpu
+ - const: pwr
+ - enum: [ ref, fuse ]
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ items:
+ - const: gpu
+
+ power-domains:
+ maxItems: 1
+
+ interconnects:
+ minItems: 4
+ maxItems: 12
+
+ interconnect-names:
+ minItems: 4
+ maxItems: 12
+
+ iommus:
+ maxItems: 1
+
+ dma-coherent: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,gp10b
+ - nvidia,gv11b
+ then:
+ required:
+ - power-domains
+ else:
+ properties:
+ interconnects: false
+ interconnect-names: false
+
+ required:
+ - vdd-supply
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,gp10b
+ then:
+ properties:
+ interconnects:
+ maxItems: 4
+
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: write-0
+ - const: read-1
+ - const: write-1
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,gv11b
+ then:
+ properties:
+ interconnects:
+ minItems: 12
+
+ interconnect-names:
+ items:
+ - const: dma-mem
+ - const: read-0-hp
+ - const: write-0
+ - const: read-1
+ - const: read-1-hp
+ - const: write-1
+ - const: read-2
+ - const: read-2-hp
+ - const: write-2
+ - const: read-3
+ - const: read-3-hp
+ - const: write-3
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/tegra124-car-common.h>
+ #include <dt-bindings/memory/tegra124-mc.h>
+
+ gpu@57000000 {
+ compatible = "nvidia,gk20a";
+ reg = <0x57000000 0x01000000>,
+ <0x58000000 0x01000000>;
+ interrupts = <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 158 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "stall", "nonstall";
+ vdd-supply = <&vdd_gpu>;
+ clocks = <&tegra_car TEGRA124_CLK_GPU>,
+ <&tegra_car TEGRA124_CLK_PLL_P_OUT5>;
+ clock-names = "gpu", "pwr";
+ resets = <&tegra_car 184>;
+ reset-names = "gpu";
+ iommus = <&mc TEGRA_SWGROUP_GPU>;
+ };
diff --git a/Documentation/devicetree/bindings/gpu/samsung-g2d.yaml b/Documentation/devicetree/bindings/gpu/samsung-g2d.yaml
index e7daae862578..132aaa49597b 100644
--- a/Documentation/devicetree/bindings/gpu/samsung-g2d.yaml
+++ b/Documentation/devicetree/bindings/gpu/samsung-g2d.yaml
@@ -22,36 +22,20 @@ properties:
interrupts:
maxItems: 1
- clocks: {}
- clock-names: {}
- iommus: {}
- power-domains: {}
-
-if:
- properties:
- compatible:
- contains:
- const: samsung,exynos5250-g2d
-
-then:
- properties:
- clocks:
- items:
- - description: fimg2d clock
- clock-names:
- items:
- - const: fimg2d
-
-else:
- properties:
- clocks:
- items:
- - description: sclk_fimg2d clock
- - description: fimg2d clock
- clock-names:
- items:
- - const: sclk_fimg2d
- - const: fimg2d
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+
+ iommus:
+ minItems: 1
+ maxItems: 2
+
+ power-domains:
+ maxItems: 1
required:
- compatible
@@ -60,6 +44,33 @@ required:
- clocks
- clock-names
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: samsung,exynos5250-g2d
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: fimg2d clock
+ clock-names:
+ items:
+ - const: fimg2d
+
+ else:
+ properties:
+ clocks:
+ items:
+ - description: sclk_fimg2d clock
+ - description: fimg2d clock
+ clock-names:
+ items:
+ - const: sclk_fimg2d
+ - const: fimg2d
+
additionalProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/gpu/samsung-rotator.yaml b/Documentation/devicetree/bindings/gpu/samsung-rotator.yaml
index 62486f55177d..18bf44e06e8f 100644
--- a/Documentation/devicetree/bindings/gpu/samsung-rotator.yaml
+++ b/Documentation/devicetree/bindings/gpu/samsung-rotator.yaml
@@ -12,10 +12,11 @@ maintainers:
properties:
compatible:
enum:
- - "samsung,s5pv210-rotator"
- - "samsung,exynos4210-rotator"
- - "samsung,exynos4212-rotator"
- - "samsung,exynos5250-rotator"
+ - samsung,s5pv210-rotator
+ - samsung,exynos4210-rotator
+ - samsung,exynos4212-rotator
+ - samsung,exynos5250-rotator
+
reg:
maxItems: 1
@@ -53,4 +54,3 @@ examples:
clocks = <&clock 278>;
clock-names = "rotator";
};
-
diff --git a/Documentation/devicetree/bindings/gpu/samsung-scaler.yaml b/Documentation/devicetree/bindings/gpu/samsung-scaler.yaml
index 5317ac64426a..9fb530e65d0e 100644
--- a/Documentation/devicetree/bindings/gpu/samsung-scaler.yaml
+++ b/Documentation/devicetree/bindings/gpu/samsung-scaler.yaml
@@ -21,40 +21,20 @@ properties:
interrupts:
maxItems: 1
- clocks: {}
- clock-names: {}
- iommus: {}
- power-domains: {}
-
-if:
- properties:
- compatible:
- contains:
- const: samsung,exynos5420-scaler
-
-then:
- properties:
- clocks:
- items:
- - description: mscl clock
-
- clock-names:
- items:
- - const: mscl
-
-else:
- properties:
- clocks:
- items:
- - description: pclk clock
- - description: aclk clock
- - description: aclk_xiu clock
-
- clock-names:
- items:
- - const: pclk
- - const: aclk
- - const: aclk_xiu
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ minItems: 1
+ maxItems: 3
+
+ iommus:
+ minItems: 1
+ maxItems: 2
+
+ power-domains:
+ maxItems: 1
required:
- compatible
@@ -63,6 +43,39 @@ required:
- clocks
- clock-names
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: samsung,exynos5420-scaler
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: mscl clock
+ clock-names:
+ items:
+ - const: mscl
+ iommus:
+ minItems: 2
+
+ else:
+ properties:
+ clocks:
+ items:
+ - description: pclk clock
+ - description: aclk clock
+ - description: aclk_xiu clock
+ clock-names:
+ items:
+ - const: pclk
+ - const: aclk
+ - const: aclk_xiu
+ iommus:
+ maxItems: 1
+
additionalProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/gpu/vivante,gc.yaml b/Documentation/devicetree/bindings/gpu/vivante,gc.yaml
index 93e7244cdc0e..b1b10ea70ad9 100644
--- a/Documentation/devicetree/bindings/gpu/vivante,gc.yaml
+++ b/Documentation/devicetree/bindings/gpu/vivante,gc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/gpu/vivante,gc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Vivante GPU Bindings
+title: Vivante GPU
description: Vivante GPU core devices
diff --git a/Documentation/devicetree/bindings/h8300/cpu.txt b/Documentation/devicetree/bindings/h8300/cpu.txt
deleted file mode 100644
index 70cd58608f4b..000000000000
--- a/Documentation/devicetree/bindings/h8300/cpu.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-* H8/300 CPU bindings
-
-Required properties:
-
-- compatible: Compatible property value should be "renesas,h8300".
-- clock-frequency: Contains the clock frequency for CPU, in Hz.
-
-Example:
-
- cpu@0 {
- compatible = "renesas,h8300";
- clock-frequency = <20000000>;
- };
diff --git a/Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml b/Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml
new file mode 100644
index 000000000000..9d0c36ec1982
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwinfo/loongson,ls2k-chipid.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwinfo/loongson,ls2k-chipid.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson-2 SoC ChipID
+
+maintainers:
+ - Yinbo Zhu <zhuyinbo@loongson.cn>
+
+description: |
+ Loongson-2 SoC contains many groups of global utilities register
+ blocks, of which the ChipID group registers record SoC version,
+ feature, vendor and id information.
+
+properties:
+ compatible:
+ const: loongson,ls2k-chipid
+
+ reg:
+ maxItems: 1
+
+ little-endian: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ chipid: chipid@1fe00000 {
+ compatible = "loongson,ls2k-chipid";
+ reg = <0x1fe00000 0x3ffc>;
+ little-endian;
+ };
diff --git a/Documentation/devicetree/bindings/arm/renesas,prr.yaml b/Documentation/devicetree/bindings/hwinfo/renesas,prr.yaml
index 1f80767da38b..792f371cec03 100644
--- a/Documentation/devicetree/bindings/arm/renesas,prr.yaml
+++ b/Documentation/devicetree/bindings/hwinfo/renesas,prr.yaml
@@ -1,7 +1,7 @@
-# SPDX-License-Identifier: GPL-2.0
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: http://devicetree.org/schemas/arm/renesas,prr.yaml#
+$id: http://devicetree.org/schemas/hwinfo/renesas,prr.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Renesas Product Register
diff --git a/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml b/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml
new file mode 100644
index 000000000000..b9cdfe52b62f
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwinfo/samsung,exynos-chipid.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwinfo/samsung,exynos-chipid.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos SoC series Chipid driver
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - samsung,exynos4210-chipid
+ - samsung,exynos850-chipid
+ - items:
+ - enum:
+ - samsung,exynos5433-chipid
+ - samsung,exynos7-chipid
+ - samsung,exynos7870-chipid
+ - samsung,exynos8890-chipid
+ - const: samsung,exynos4210-chipid
+ - items:
+ - enum:
+ - samsung,exynos2200-chipid
+ - samsung,exynos7885-chipid
+ - samsung,exynos8895-chipid
+ - samsung,exynos9610-chipid
+ - samsung,exynos9810-chipid
+ - samsung,exynos990-chipid
+ - samsung,exynosautov9-chipid
+ - samsung,exynosautov920-chipid
+ - const: samsung,exynos850-chipid
+
+ reg:
+ maxItems: 1
+
+ samsung,asv-bin:
+ description:
+ Adaptive Supply Voltage bin selection. This can be used
+ to determine the ASV bin of an SoC if respective information
+ is missing in the CHIPID registers or in the OTP memory.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ chipid@10000000 {
+ compatible = "samsung,exynos4210-chipid";
+ reg = <0x10000000 0x100>;
+ samsung,asv-bin = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/hwinfo/samsung,s5pv210-chipid.yaml b/Documentation/devicetree/bindings/hwinfo/samsung,s5pv210-chipid.yaml
new file mode 100644
index 000000000000..563ded4fca83
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwinfo/samsung,s5pv210-chipid.yaml
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwinfo/samsung,s5pv210-chipid.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5PV210 SoC ChipID
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ const: samsung,s5pv210-chipid
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ chipid@e0000000 {
+ compatible = "samsung,s5pv210-chipid";
+ reg = <0xe0000000 0x1000>;
+ };
diff --git a/Documentation/devicetree/bindings/hwinfo/ti,k3-socinfo.yaml b/Documentation/devicetree/bindings/hwinfo/ti,k3-socinfo.yaml
new file mode 100644
index 000000000000..dada28b47ea0
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwinfo/ti,k3-socinfo.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwinfo/ti,k3-socinfo.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments K3 Multicore SoC platforms chipid module
+
+maintainers:
+ - Tero Kristo <t-kristo@ti.com>
+ - Nishanth Menon <nm@ti.com>
+
+description: |
+ Texas Instruments (ARM64) K3 Multicore SoC platforms chipid module is
+ represented by CTRLMMR_xxx_JTAGID register which contains information about
+ SoC id and revision.
+
+properties:
+ $nodename:
+ pattern: "^chipid@[0-9a-f]+$"
+
+ compatible:
+ items:
+ - const: ti,am654-chipid
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ chipid@43000014 {
+ compatible = "ti,am654-chipid";
+ reg = <0x43000014 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/hwinfo/via,vt8500-scc-id.yaml b/Documentation/devicetree/bindings/hwinfo/via,vt8500-scc-id.yaml
new file mode 100644
index 000000000000..b0f425a4a882
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwinfo/via,vt8500-scc-id.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwinfo/via,vt8500-scc-id.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: VIA/WonderMedia SoC system configuration information
+
+maintainers:
+ - Alexey Charkov <alchark@gmail.com>
+
+description:
+ The system configuration controller on VIA/WonderMedia SoC's contains a chip
+ identifier and revision used to differentiate between different hardware
+ versions of on-chip IP blocks having their own peculiarities which may or
+ may not be captured by their respective DT compatible strings
+
+properties:
+ compatible:
+ items:
+ - const: via,vt8500-scc-id
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ chipid@d8120000 {
+ compatible = "via,vt8500-scc-id";
+ reg = <0xd8120000 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml
index 10e5a53e447b..584cce3211c0 100644
--- a/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml
+++ b/Documentation/devicetree/bindings/hwlock/allwinner,sun6i-a31-hwspinlock.yaml
@@ -1,4 +1,4 @@
-# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwlock/allwinner,sun6i-a31-hwspinlock.yaml#
@@ -26,11 +26,15 @@ properties:
resets:
maxItems: 1
+ '#hwlock-cells':
+ const: 1
+
required:
- compatible
- reg
- clocks
- resets
+ - "#hwlock-cells"
additionalProperties: false
@@ -44,5 +48,6 @@ examples:
reg = <0x01c18000 0x1000>;
clocks = <&ccu CLK_BUS_SPINLOCK>;
resets = <&ccu RST_BUS_SPINLOCK>;
+ #hwlock-cells = <1>;
};
...
diff --git a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml
index 1c7149f7d171..ee2726149cf3 100644
--- a/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml
+++ b/Documentation/devicetree/bindings/hwlock/qcom-hwspinlock.yaml
@@ -15,9 +15,22 @@ description:
properties:
compatible:
- enum:
- - qcom,sfpb-mutex
- - qcom,tcsr-mutex
+ oneOf:
+ - enum:
+ - qcom,sfpb-mutex
+ - qcom,tcsr-mutex
+ - items:
+ - enum:
+ - qcom,apq8084-tcsr-mutex
+ - qcom,ipq6018-tcsr-mutex
+ - qcom,msm8226-tcsr-mutex
+ - qcom,msm8994-tcsr-mutex
+ - const: qcom,tcsr-mutex
+ - items:
+ - enum:
+ - qcom,msm8974-tcsr-mutex
+ - const: qcom,tcsr-mutex
+ - const: syscon
reg:
maxItems: 1
@@ -34,9 +47,9 @@ additionalProperties: false
examples:
- |
- tcsr_mutex: hwlock@1f40000 {
- compatible = "qcom,tcsr-mutex";
- reg = <0x01f40000 0x40000>;
- #hwlock-cells = <1>;
- };
+ hwlock@1f40000 {
+ compatible = "qcom,tcsr-mutex";
+ reg = <0x01f40000 0x40000>;
+ #hwlock-cells = <1>;
+ };
...
diff --git a/Documentation/devicetree/bindings/hwlock/sprd,hwspinlock-r3p0.yaml b/Documentation/devicetree/bindings/hwlock/sprd,hwspinlock-r3p0.yaml
new file mode 100644
index 000000000000..abe11df25761
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwlock/sprd,hwspinlock-r3p0.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwlock/sprd,hwspinlock-r3p0.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Spreadtrum hardware spinlock
+
+maintainers:
+ - Orson Zhai <orsonzhai@gmail.com>
+ - Baolin Wang <baolin.wang7@gmail.com>
+ - Chunyan Zhang <zhang.lyra@gmail.com>
+
+properties:
+ compatible:
+ const: sprd,hwspinlock-r3p0
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: enable
+
+ '#hwlock-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - '#hwlock-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/sprd,sc9860-clk.h>
+
+ hwlock@40500000 {
+ compatible = "sprd,hwspinlock-r3p0";
+ reg = <0x40500000 0x1000>;
+ clocks = <&aon_gate CLK_SPLK_EB>;
+ clock-names = "enable";
+ #hwlock-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwlock/sprd-hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/sprd-hwspinlock.txt
deleted file mode 100644
index 581db9d941ba..000000000000
--- a/Documentation/devicetree/bindings/hwlock/sprd-hwspinlock.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-SPRD Hardware Spinlock Device Binding
--------------------------------------
-
-Required properties :
-- compatible : should be "sprd,hwspinlock-r3p0".
-- reg : the register address of hwspinlock.
-- #hwlock-cells : hwlock users only use the hwlock id to represent a specific
- hwlock, so the number of cells should be <1> here.
-- clock-names : Must contain "enable".
-- clocks : Must contain a phandle entry for the clock in clock-names, see the
- common clock bindings.
-
-Please look at the generic hwlock binding for usage information for consumers,
-"Documentation/devicetree/bindings/hwlock/hwlock.txt"
-
-Example of hwlock provider:
- hwspinlock@40500000 {
- compatible = "sprd,hwspinlock-r3p0";
- reg = <0 0x40500000 0 0x1000>;
- #hwlock-cells = <1>;
- clock-names = "enable";
- clocks = <&clk_aon_apb_gates0 22>;
- };
diff --git a/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.yaml
index 47cf9c8d97e9..829d1fdf4c67 100644
--- a/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.yaml
+++ b/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.yaml
@@ -4,11 +4,10 @@
$id: http://devicetree.org/schemas/hwlock/st,stm32-hwspinlock.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 Hardware Spinlock bindings
+title: STMicroelectronics STM32 Hardware Spinlock
maintainers:
- - Benjamin Gaignard <benjamin.gaignard@st.com>
- - Fabien Dessenne <fabien.dessenne@st.com>
+ - Fabien Dessenne <fabien.dessenne@foss.st.com>
properties:
"#hwlock-cells":
diff --git a/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml b/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml
index ae1b37dbee75..5ba60d532fcd 100644
--- a/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml
+++ b/Documentation/devicetree/bindings/hwlock/ti,omap-hwspinlock.yaml
@@ -1,4 +1,4 @@
-# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwlock/ti,omap-hwspinlock.yaml#
@@ -39,39 +39,8 @@ additionalProperties: false
examples:
- |
- /* OMAP4 SoCs */
- hwspinlock: spinlock@4a0f6000 {
+ spinlock@4a0f6000 {
compatible = "ti,omap4-hwspinlock";
reg = <0x4a0f6000 0x1000>;
#hwlock-cells = <1>;
};
-
- - |
- / {
- /* K3 AM65x SoCs */
- model = "Texas Instruments K3 AM654 SoC";
- compatible = "ti,am654-evm", "ti,am654";
- #address-cells = <2>;
- #size-cells = <2>;
-
- bus@100000 {
- compatible = "simple-bus";
- #address-cells = <2>;
- #size-cells = <2>;
- ranges = <0x00 0x00100000 0x00 0x00100000 0x00 0x00020000>, /* ctrl mmr */
- <0x00 0x30800000 0x00 0x30800000 0x00 0x0bc00000>; /* Main NavSS */
-
- bus@30800000 {
- compatible = "simple-mfd";
- #address-cells = <2>;
- #size-cells = <2>;
- ranges = <0x00 0x30800000 0x00 0x30800000 0x00 0x0bc00000>;
-
- spinlock@30e00000 {
- compatible = "ti,am654-hwspinlock";
- reg = <0x00 0x30e00000 0x00 0x1000>;
- #hwlock-cells = <1>;
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/hwmon/adc128d818.txt b/Documentation/devicetree/bindings/hwmon/adc128d818.txt
deleted file mode 100644
index d0ae46d7bac3..000000000000
--- a/Documentation/devicetree/bindings/hwmon/adc128d818.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-TI ADC128D818 ADC System Monitor With Temperature Sensor
---------------------------------------------------------
-
-Operation modes:
-
- - Mode 0: 7 single-ended voltage readings (IN0-IN6),
- 1 temperature reading (internal)
- - Mode 1: 8 single-ended voltage readings (IN0-IN7),
- no temperature
- - Mode 2: 4 pseudo-differential voltage readings
- (IN0-IN1, IN3-IN2, IN4-IN5, IN7-IN6),
- 1 temperature reading (internal)
- - Mode 3: 4 single-ended voltage readings (IN0-IN3),
- 2 pseudo-differential voltage readings
- (IN4-IN5, IN7-IN6),
- 1 temperature reading (internal)
-
-If no operation mode is configured via device tree, the driver keeps the
-currently active chip operation mode (default is mode 0).
-
-
-Required node properties:
-
- - compatible: must be set to "ti,adc128d818"
- - reg: I2C address of the device
-
-Optional node properties:
-
- - ti,mode: Operation mode (u8) (see above).
-
-
-Example (operation mode 2):
-
- adc128d818@1d {
- compatible = "ti,adc128d818";
- reg = <0x1d>;
- ti,mode = /bits/ 8 <2>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/adi,ad741x.yaml b/Documentation/devicetree/bindings/hwmon/adi,ad741x.yaml
index ce7f8ce9da0a..236d8b52ef85 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,ad741x.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,ad741x.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/adi,ad741x.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml
index 154bee851139..be7e9e91a3a8 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,adm1177.yaml
@@ -8,7 +8,6 @@ title: Analog Devices ADM1177 Hot Swap Controller and Digital Power Monitor
maintainers:
- Michael Hennerich <michael.hennerich@analog.com>
- - Beniamin Bia <beniamin.bia@analog.com>
description: |
Analog Devices ADM1177 Hot Swap Controller and Digital Power Monitor
@@ -28,7 +27,7 @@ properties:
shunt-resistor-micro-ohms:
description:
- The value of curent sense resistor in microohms. If not provided,
+ The value of current sense resistor in microohms. If not provided,
the current reading and overcurrent alert is disabled.
adi,shutdown-threshold-microamp:
@@ -47,22 +46,25 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: hwmon-common.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
pwmon@5a {
- compatible = "adi,adm1177";
- reg = <0x5a>;
- shunt-resistor-micro-ohms = <50000>; /* 50 mOhm */
- adi,shutdown-threshold-microamp = <1059000>; /* 1.059 A */
- adi,vrange-high-enable;
+ compatible = "adi,adm1177";
+ reg = <0x5a>;
+ shunt-resistor-micro-ohms = <50000>; /* 50 mOhm */
+ adi,shutdown-threshold-microamp = <1059000>; /* 1.059 A */
+ adi,vrange-high-enable;
};
};
...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml
index 43b4f4f57b49..fe87a592de45 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,adm1266.yaml
@@ -8,7 +8,7 @@ title: Analog Devices ADM1266 Cascadable Super Sequencer with Margin
Control and Fault Recording
maintainers:
- - Alexandru Tachici <alexandru.tachici@analog.com>
+ - Cedric Encarnacion <cedricjustine.encarnacion@analog.com>
description: |
Analog Devices ADM1266 Cascadable Super Sequencer with Margin
@@ -39,13 +39,13 @@ additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
adm1266@40 {
- compatible = "adi,adm1266";
- reg = <0x40>;
+ compatible = "adi,adm1266";
+ reg = <0x40>;
};
};
...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml b/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml
index 223393d7cafd..d6a7517f2a50 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,adm1275.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/adi,adm1275.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Analog Devices ADM1075/ADM127x/ADM129x digital power monitors
+title: Analog Devices ADM1075/ADM127x/ADM1281/ADM129x digital power monitors
maintainers:
- Krzysztof Kozlowski <krzk@kernel.org>
@@ -19,29 +18,105 @@ description: |
Datasheets:
https://www.analog.com/en/products/adm1294.html
+ The SQ24905C is also a Hot-swap controller compatibility to the ADM1278,
+ the PMBUS_MFR_MODEL is MC09C
+
+ Datasheets:
+ https://www.silergy.com/
+ download/downloadFile?id=5669&type=product&ftype=note
+
properties:
compatible:
enum:
- adi,adm1075
- adi,adm1272
+ - adi,adm1273
- adi,adm1275
- adi,adm1276
- adi,adm1278
+ - adi,adm1281
- adi,adm1293
- adi,adm1294
+ - silergy,mc09c
reg:
maxItems: 1
- shunt-resistor-micro-ohms:
- description:
- Shunt resistor value in micro-Ohm.
+ adi,volt-curr-sample-average:
+ description: |
+ Number of samples to be used to report voltage and current values.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4, 8, 16, 32, 64, 128]
+
+ adi,power-sample-average:
+ description: |
+ Number of samples to be used to report power values.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4, 8, 16, 32, 64, 128]
+
+allOf:
+ - $ref: hwmon-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adm1075
+ - adi,adm1276
+ then:
+ properties:
+ adi,volt-curr-sample-average:
+ default: 128
+ adi,power-sample-average: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adm1275
+ then:
+ properties:
+ adi,volt-curr-sample-average:
+ default: 16
+ adi,power-sample-average: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adm1272
+ - adi,adm1273
+ then:
+ properties:
+ adi,volt-curr-sample-average:
+ default: 128
+ adi,power-sample-average:
+ default: 128
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adm1278
+ - adi,adm1281
+ - adi,adm1293
+ - adi,adm1294
+ - silergy,mc09c
+ then:
+ properties:
+ adi,volt-curr-sample-average:
+ default: 128
+ adi,power-sample-average:
+ default: 1
required:
- compatible
- reg
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
@@ -53,5 +128,7 @@ examples:
compatible = "adi,adm1272";
reg = <0x10>;
shunt-resistor-micro-ohms = <500>;
+ adi,volt-curr-sample-average = <128>;
+ adi,power-sample-average = <128>;
};
};
diff --git a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml
index 6747b870f297..6751f9b643b4 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,axi-fan-control.yaml
@@ -5,13 +5,13 @@
$id: http://devicetree.org/schemas/hwmon/adi,axi-fan-control.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Analog Devices AXI FAN Control Device Tree Bindings
+title: Analog Devices AXI FAN Control
maintainers:
- Nuno Sá <nuno.sa@analog.com>
description: |+
- Bindings for the Analog Devices AXI FAN Control driver. Spefications of the
+ Bindings for the Analog Devices AXI FAN Control driver. Specifications of the
core can be found in:
https://wiki.analog.com/resources/fpga/docs/axi_fan_control
@@ -49,15 +49,15 @@ additionalProperties: false
examples:
- |
fpga_axi: fpga-axi {
- #address-cells = <0x2>;
- #size-cells = <0x1>;
-
- axi_fan_control: axi-fan-control@80000000 {
- compatible = "adi,axi-fan-control-1.00.a";
- reg = <0x0 0x80000000 0x10000>;
- clocks = <&clk 71>;
- interrupts = <0 110 0>;
- pulses-per-revolution = <2>;
- };
+ #address-cells = <0x2>;
+ #size-cells = <0x1>;
+
+ axi_fan_control: axi-fan-control@80000000 {
+ compatible = "adi,axi-fan-control-1.00.a";
+ reg = <0x0 0x80000000 0x10000>;
+ clocks = <&clk 71>;
+ interrupts = <0 110 0>;
+ pulses-per-revolution = <2>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml
new file mode 100644
index 000000000000..6401b0a9aff4
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2945.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/adi,ltc2945.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LTC2945 wide range i2c power monitor
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+
+description: |
+ Analog Devices LTC2945 wide range i2c power monitor over I2C.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/LTC2945.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ltc2945
+
+ reg:
+ maxItems: 1
+
+ shunt-resistor-micro-ohms:
+ description:
+ Shunt resistor value in micro-Ohms
+ default: 1000
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: hwmon-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ power-monitor@6e {
+ compatible = "adi,ltc2945";
+ reg = <0x6e>;
+ /* 10 milli-Ohm shunt resistor */
+ shunt-resistor-micro-ohms = <10000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml
index bf04151b63d2..3e3f49cf2f52 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2947.yaml
@@ -81,21 +81,20 @@ required:
- compatible
- reg
-
additionalProperties: false
examples:
- |
spi {
- #address-cells = <1>;
- #size-cells = <0>;
-
- ltc2947_spi: ltc2947@0 {
- compatible = "adi,ltc2947";
- reg = <0>;
- /* accumulation takes place always for energ1/charge1. */
- /* accumulation only on positive current for energy2/charge2. */
- adi,accumulator-ctl-pol = <0 1>;
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ltc2947_spi: ltc2947@0 {
+ compatible = "adi,ltc2947";
+ reg = <0>;
+ /* accumulation takes place always for energ1/charge1. */
+ /* accumulation only on positive current for energy2/charge2. */
+ adi,accumulator-ctl-pol = <0 1>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml
new file mode 100644
index 000000000000..1ff44cb22ef4
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/adi,ltc2991.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LTC2991 Octal I2C Voltage, Current and Temperature Monitor
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ The LTC2991 is used to monitor system temperatures, voltages and currents.
+ Through the I2C serial interface, the eight monitors can individually measure
+ supply voltages and can be paired for differential measurements of current
+ sense resistors or temperature sensing transistors.
+
+ Datasheet:
+ https://www.analog.com/en/products/ltc2991.html
+
+properties:
+ compatible:
+ const: adi,ltc2991
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ vcc-supply: true
+
+patternProperties:
+ "^channel@[0-3]$":
+ type: object
+ description:
+ Represents the differential/temperature channels.
+
+ properties:
+ reg:
+ description:
+ The channel number. LTC2991 can monitor 4 currents/temperatures.
+ items:
+ minimum: 0
+ maximum: 3
+
+ shunt-resistor-micro-ohms:
+ description:
+ The value of curent sense resistor in micro ohms. Pin configuration is
+ set for differential input pair.
+
+ adi,temperature-enable:
+ description:
+ Enables temperature readings. Pin configuration is set for remote
+ diode temperature measurement.
+ type: boolean
+
+ required:
+ - reg
+
+ allOf:
+ - if:
+ required:
+ - shunt-resistor-micro-ohms
+ then:
+ properties:
+ adi,temperature-enable: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon@48 {
+ compatible = "adi,ltc2991";
+ reg = <0x48>;
+ vcc-supply = <&vcc>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon@48 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ compatible = "adi,ltc2991";
+ reg = <0x48>;
+ vcc-supply = <&vcc>;
+
+ channel@0 {
+ reg = <0x0>;
+ shunt-resistor-micro-ohms = <100000>;
+ };
+
+ channel@1 {
+ reg = <0x1>;
+ shunt-resistor-micro-ohms = <100000>;
+ };
+
+ channel@2 {
+ reg = <0x2>;
+ adi,temperature-enable;
+ };
+
+ channel@3 {
+ reg = <0x3>;
+ adi,temperature-enable;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml
index 64a8fcb7bc46..38a8f3a14c02 100644
--- a/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2992.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Linear Technology 2992 Power Monitor
maintainers:
- - Alexandru Tachici <alexandru.tachici@analog.com>
+ - Cedric Encarnacion <cedricjustine.encarnacion@analog.com>
description: |
Linear Technology 2992 Dual Wide Range Power Monitor
@@ -32,6 +32,7 @@ properties:
patternProperties:
"^channel@([0-1])$":
type: object
+ additionalProperties: false
description: |
Represents the two supplies to be monitored.
@@ -45,7 +46,7 @@ patternProperties:
shunt-resistor-micro-ohms:
description:
- The value of curent sense resistor in microohms.
+ The value of current sense resistor in microohms.
required:
- compatible
@@ -55,26 +56,26 @@ additionalProperties: false
examples:
- |
- i2c1 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
- ltc2992@6F {
- #address-cells = <1>;
- #size-cells = <0>;
+ ltc2992@6f {
+ #address-cells = <1>;
+ #size-cells = <0>;
- compatible = "adi,ltc2992";
- reg = <0x6F>;
+ compatible = "adi,ltc2992";
+ reg = <0x6f>;
- channel@0 {
- reg = <0x0>;
- shunt-resistor-micro-ohms = <10000>;
- };
+ channel@0 {
+ reg = <0x0>;
+ shunt-resistor-micro-ohms = <10000>;
+ };
- channel@1 {
- reg = <0x1>;
- shunt-resistor-micro-ohms = <10000>;
- };
+ channel@1 {
+ reg = <0x1>;
+ shunt-resistor-micro-ohms = <10000>;
+ };
};
};
...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml
new file mode 100644
index 000000000000..4854b95a93e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/adi,ltc4282.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LTC4282 I2C High Current Hot Swap Controller over I2C
+
+maintainers:
+ - Nuno Sa <nuno.sa@analog.com>
+
+description: |
+ Analog Devices LTC4282 I2C High Current Hot Swap Controller over I2C.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ltc4282.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ltc4282
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ clocks:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 0
+
+ adi,rsense-nano-ohms:
+ description: Value of the sense resistor.
+
+ adi,vin-mode-microvolt:
+ description:
+ Selects operating range for the Undervoltage, Overvoltage and Foldback
+ pins. Also for the ADC. Should be set to the nominal input voltage.
+ enum: [3300000, 5000000, 12000000, 24000000]
+ default: 12000000
+
+ adi,fet-bad-timeout-ms:
+ description:
+ From the moment a FET bad conditions is present, this property selects the
+ wait time/timeout for a FET-bad fault to be signaled. Setting this to 0,
+ disables FET bad faults to be reported.
+ default: 255
+ maximum: 255
+
+ adi,overvoltage-dividers:
+ description: |
+ Select which dividers to use for VDD Overvoltage detection. Note that
+ when the internal dividers are used the threshold is referenced to VDD.
+ The percentages in the datasheet are misleading since the actual values
+ to look for are in the "Absolute Maximum Ratings" table in the
+ "Comparator Inputs" section. In there there's a line for each of the 5%,
+ 10% and 15% settings with the actual min, typical and max tolerances.
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [external, vdd_5_percent, vdd_10_percent, vdd_15_percent]
+ default: external
+
+ adi,undervoltage-dividers:
+ description: |
+ Select which dividers to use for VDD Overvoltage detection. Note that
+ when the internal dividers are used the threshold is referenced to VDD.
+ The percentages in the datasheet are misleading since the actual values
+ to look for are in the "Absolute Maximum Ratings" table in the
+ "Comparator Inputs" section. In there there's a line for each of the 5%,
+ 10% and 15% settings with the actual min, typical and max tolerances.
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [external, vdd_5_percent, vdd_10_percent, vdd_15_percent]
+ default: external
+
+ adi,current-limit-sense-microvolt:
+ description:
+ The current limit sense voltage of the chip is adjustable between
+ 12.5mV and 34.4mV in 3.1mV steps. This effectively limits the current
+ on the load.
+ enum: [12500, 15625, 18750, 21875, 25000, 28125, 31250, 34375]
+ default: 25000
+
+ adi,overcurrent-retry:
+ description:
+ If set, enables the chip to auto-retry 256 timer cycles after an
+ Overcurrent fault.
+ type: boolean
+
+ adi,overvoltage-retry-disable:
+ description:
+ If set, disables the chip to auto-retry 50ms after an Overvoltage fault.
+ It's enabled by default.
+ type: boolean
+
+ adi,undervoltage-retry-disable:
+ description:
+ If set, disables the chip to auto-retry 50ms after an Undervoltage fault.
+ It's enabled by default.
+ type: boolean
+
+ adi,fault-log-enable:
+ description:
+ If set, enables the FAULT_LOG and ADC_ALERT_LOG registers to be written
+ to the EEPROM when a fault bit transitions high and hence, will be
+ available after a power cycle (the chip loads the contents of
+ the EE_FAULT_LOG register - the one in EEPROM - into FAULT_LOG at boot).
+ type: boolean
+
+ adi,gpio1-mode:
+ description: Defines the function of the Pin. It can indicate that power is
+ good (PULL the pin low when power is not good) or that power is bad (Go
+ into high-z when power is not good).
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [power_bad, power_good]
+ default: power_good
+
+ adi,gpio2-mode:
+ description: Defines the function of the Pin. It can be set as the input for
+ the ADC or indicating that the MOSFET is in stress (dissipating power).
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [adc_input, stress_fet]
+ default: adc_input
+
+ adi,gpio3-monitor-enable:
+ description: If set, gpio3 is set as input for the ADC instead of gpio2.
+ type: boolean
+
+allOf:
+ - if:
+ required:
+ - adi,gpio3-monitor-enable
+ then:
+ properties:
+ adi,gpio2-mode:
+ const: stress_fet
+
+required:
+ - compatible
+ - reg
+ - adi,rsense-nano-ohms
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon@50 {
+ compatible = "adi,ltc4282";
+ reg = <0x50>;
+ adi,rsense-nano-ohms = <500>;
+
+ adi,gpio1-mode = "power_good";
+ adi,gpio2-mode = "adc_input";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/adi,max31760.yaml b/Documentation/devicetree/bindings/hwmon/adi,max31760.yaml
new file mode 100644
index 000000000000..9f2d08d7b978
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/adi,max31760.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/adi,max31760.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices MAX31760 Fan-Speed Controller
+
+maintainers:
+ - Ibrahim Tilki <Ibrahim.Tilki@analog.com>
+
+description: |
+ Analog Devices MAX31760 Fan-Speed Controller
+ https://datasheets.maximintegrated.com/en/ds/MAX31760.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,max31760
+
+ reg:
+ description: I2C address of slave device.
+ minimum: 0x50
+ maximum: 0x57
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fan-controller@50 {
+ reg = <0x50>;
+ compatible = "adi,max31760";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml b/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml
new file mode 100644
index 000000000000..c2f7c6ee1a37
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/adi,max31827.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices MAX31827, MAX31828, MAX31829 Low-Power Temperature Switch
+
+maintainers:
+ - Daniel Matyas <daniel.matyas@analog.com>
+
+description: |
+ Analog Devices MAX31827, MAX31828, MAX31829 Low-Power Temperature Switch with
+ I2C Interface
+ https://www.analog.com/media/en/technical-documentation/data-sheets/MAX31827-MAX31829.pdf
+
+properties:
+ compatible:
+ oneOf:
+ - const: adi,max31827
+ - items:
+ - enum:
+ - adi,max31828
+ - adi,max31829
+ - const: adi,max31827
+
+ reg:
+ maxItems: 1
+
+ vref-supply:
+ description:
+ Must have values in the interval (1.6V; 3.6V) in order for the device to
+ function correctly.
+
+ adi,comp-int:
+ description:
+ If present interrupt mode is used. If not present comparator mode is used
+ (default).
+ type: boolean
+
+ adi,alarm-pol:
+ description:
+ Sets the alarms active state.
+ - 0 = active low
+ - 1 = active high
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+
+ adi,fault-q:
+ description:
+ Select how many consecutive temperature faults must occur before
+ overtemperature or undertemperature faults are indicated in the
+ corresponding status bits.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4, 8]
+
+ adi,timeout-enable:
+ description:
+ Enables timeout. Bus timeout resets the I2C-compatible interface when SCL
+ is low for more than 30ms (nominal).
+ type: boolean
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,max31829
+
+ then:
+ properties:
+ adi,alarm-pol:
+ default: 1
+
+ else:
+ properties:
+ adi,alarm-pol:
+ default: 0
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,max31827
+
+ then:
+ properties:
+ adi,fault-q:
+ default: 1
+
+ else:
+ properties:
+ adi,fault-q:
+ default: 4
+
+required:
+ - compatible
+ - reg
+ - vref-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@42 {
+ compatible = "adi,max31827";
+ reg = <0x42>;
+ vref-supply = <&reg_vdd>;
+ adi,comp-int;
+ adi,alarm-pol = <0>;
+ adi,fault-q = <1>;
+ adi,timeout-enable;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/adt7475.yaml b/Documentation/devicetree/bindings/hwmon/adt7475.yaml
index ad0ec9f35bd8..43e9fe225870 100644
--- a/Documentation/devicetree/bindings/hwmon/adt7475.yaml
+++ b/Documentation/devicetree/bindings/hwmon/adt7475.yaml
@@ -39,28 +39,74 @@ properties:
reg:
maxItems: 1
-patternProperties:
- "^adi,bypass-attenuator-in[0-4]$":
- description: |
- Configures bypassing the individual voltage input attenuator. If
- set to 1 the attenuator is bypassed if set to 0 the attenuator is
- not bypassed. If the property is absent then the attenuator
- retains it's configuration from the bios/bootloader.
- $ref: /schemas/types.yaml#/definitions/uint32
- enum: [0, 1]
-
- "^adi,pwm-active-state$":
+ adi,pwm-active-state:
description: |
Integer array, represents the active state of the pwm outputs If set to 0
the pwm uses a logic low output for 100% duty cycle. If set to 1 the pwm
uses a logic high output for 100% duty cycle.
$ref: /schemas/types.yaml#/definitions/uint32-array
+ deprecated: true
minItems: 3
maxItems: 3
items:
enum: [0, 1]
default: 1
+ "#pwm-cells":
+ oneOf:
+ - const: 3
+ - const: 4
+ deprecated: true
+ description: |
+ Number of cells in a PWM specifier.
+ - 0: The PWM channel
+ - 1: The PWM period in nanoseconds
+ - 90909091 (11 Hz)
+ - 71428571 (14 Hz)
+ - 45454545 (22 Hz)
+ - 34482759 (29 Hz)
+ - 28571429 (35 Hz)
+ - 22727273 (44 Hz)
+ - 17241379 (58 Hz)
+ - 11363636 (88 Hz)
+ - 44444 (22 kHz)
+ - 2: PWM flags 0 or PWM_POLARITY_INVERTED
+ - 3: The default PWM duty cycle in nanoseconds, defaults to period.
+
+patternProperties:
+ "^adi,bypass-attenuator-in[0-4]$":
+ description: |
+ Configures bypassing the individual voltage input attenuator. If
+ set to 1 the attenuator is bypassed if set to 0 the attenuator is
+ not bypassed. If the property is absent then the attenuator
+ retains its configuration from the bios/bootloader.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+
+ "^adi,pin(5|10)-function$":
+ description: |
+ Configures the function for pin 5 on the adi,adt7473 and adi,adt7475. Or
+ pin 10 on the adi,adt7476 and adi,adt7490.
+ $ref: /schemas/types.yaml#/definitions/string
+ enum:
+ - pwm2
+ - smbalert#
+
+ "^adi,pin(9|14)-function$":
+ description: |
+ Configures the function for pin 9 on the adi,adt7473 and adi,adt7475. Or
+ pin 14 on the adi,adt7476 and adi,adt7490
+ $ref: /schemas/types.yaml#/definitions/string
+ enum:
+ - tach4
+ - therm#
+ - smbalert#
+ - gpio
+
+ "^fan-[0-9]+$":
+ $ref: fan-common.yaml#
+ unevaluatedProperties: false
+
required:
- compatible
- reg
@@ -69,16 +115,27 @@ additionalProperties: false
examples:
- |
+ #include <dt-bindings/pwm/pwm.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
- hwmon@2e {
+ pwm: hwmon@2e {
compatible = "adi,adt7476";
reg = <0x2e>;
adi,bypass-attenuator-in0 = <1>;
adi,bypass-attenuator-in1 = <0>;
- adi,pwm-active-state = <1 0 1>;
+ adi,pin10-function = "smbalert#";
+ adi,pin14-function = "tach4";
+ #pwm-cells = <3>;
+
+ /* PWMs at 22.5 kHz frequency */
+ fan-0 {
+ pwms = <&pwm 0 44444 0>;
+ };
+
+ fan-1 {
+ pwms = <&pwm 2 44444 0>;
+ };
};
};
-
diff --git a/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml b/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml
new file mode 100644
index 000000000000..353d81d89bf5
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/amd,sbrmi.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/amd,sbrmi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: >
+ Sideband Remote Management Interface (SB-RMI) compliant
+ AMD SoC power device.
+
+maintainers:
+ - Akshay Gupta <Akshay.Gupta@amd.com>
+
+description: |
+ SB Remote Management Interface (SB-RMI) is an SMBus compatible
+ interface that reports AMD SoC's Power (normalized Power) using,
+ Mailbox Service Request and resembles a typical 8-pin remote power
+ sensor's I2C interface to BMC. The power attributes in hwmon
+ reports power in microwatts.
+
+properties:
+ compatible:
+ enum:
+ - amd,sbrmi
+
+ reg:
+ maxItems: 1
+ description: |
+ I2C bus address of the device as specified in Section SBI SMBus Address
+ of the SoC register reference. The SB-RMI address is normally 78h for
+ socket 0 and 70h for socket 1, but it could vary based on hardware
+ address select pins.
+ \[open source SoC register reference\]
+ https://www.amd.com/en/support/tech-docs?keyword=55898
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sbrmi@3c {
+ compatible = "amd,sbrmi";
+ reg = <0x3c>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml b/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml
index 446b09f1ce94..75088244a274 100644
--- a/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml
+++ b/Documentation/devicetree/bindings/hwmon/amd,sbtsi.yaml
@@ -42,13 +42,13 @@ additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
sbtsi@4c {
- compatible = "amd,sbtsi";
- reg = <0x4c>;
+ compatible = "amd,sbtsi";
+ reg = <0x4c>;
};
};
...
diff --git a/Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml b/Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml
new file mode 100644
index 000000000000..17351fdbefce
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/amphenol,chipcap2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ChipCap 2 humidity and temperature iio sensor
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+description: |
+ Relative humidity and temperature sensor on I2C bus.
+
+ Datasheets:
+ https://www.amphenol-sensors.com/en/telaire/humidity/527-humidity-sensors/3095-chipcap-2
+
+properties:
+ compatible:
+ oneOf:
+ - const: amphenol,cc2d23
+ - items:
+ - enum:
+ - amphenol,cc2d23s
+ - amphenol,cc2d25
+ - amphenol,cc2d25s
+ - amphenol,cc2d33
+ - amphenol,cc2d33s
+ - amphenol,cc2d35
+ - amphenol,cc2d35s
+ - const: amphenol,cc2d23
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: measurement ready indicator
+ - description: low humidity alarm
+ - description: high humidity alarm
+
+ interrupt-names:
+ items:
+ - const: ready
+ - const: low
+ - const: high
+
+ vdd-supply:
+ description:
+ Dedicated, controllable supply-regulator to reset the device and
+ enter in command mode.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ humidity@28 {
+ compatible = "amphenol,cc2d23s", "amphenol,cc2d23";
+ reg = <0x28>;
+ interrupt-parent = <&gpio>;
+ interrupts = <4 IRQ_TYPE_EDGE_RISING>,
+ <5 IRQ_TYPE_EDGE_RISING>,
+ <6 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "ready", "low", "high";
+ vdd-supply = <&reg_vdd>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/apm,xgene-slimpro-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/apm,xgene-slimpro-hwmon.yaml
new file mode 100644
index 000000000000..58c51626a9ce
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/apm,xgene-slimpro-hwmon.yaml
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/apm,xgene-slimpro-hwmon.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: APM X-Gene SLIMpro hwmon
+
+maintainers:
+ - Khuong Dinh <khuong@os.amperecomputing.com>
+
+properties:
+ compatible:
+ const: apm,xgene-slimpro-hwmon
+
+ mboxes:
+ maxItems: 1
+
+required:
+ - compatible
+ - mboxes
+
+additionalProperties: false
+
+examples:
+ - |
+ hwmon {
+ compatible = "apm,xgene-slimpro-hwmon";
+ mboxes = <&mailbox 7>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/apm-xgene-hwmon.txt b/Documentation/devicetree/bindings/hwmon/apm-xgene-hwmon.txt
deleted file mode 100644
index 59b38557f1bb..000000000000
--- a/Documentation/devicetree/bindings/hwmon/apm-xgene-hwmon.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-APM X-Gene hwmon driver
-
-APM X-Gene SOC sensors are accessed over the "SLIMpro" mailbox.
-
-Required properties :
- - compatible : should be "apm,xgene-slimpro-hwmon"
- - mboxes : use the label reference for the mailbox as the first parameter.
- The second parameter is the channel number.
-
-Example :
- hwmonslimpro {
- compatible = "apm,xgene-slimpro-hwmon";
- mboxes = <&mailbox 7>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/as370.txt b/Documentation/devicetree/bindings/hwmon/as370.txt
deleted file mode 100644
index d102fe765124..000000000000
--- a/Documentation/devicetree/bindings/hwmon/as370.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-Bindings for Synaptics AS370 PVT sensors
-
-Required properties:
-- compatible : "syna,as370-hwmon"
-- reg : address and length of the register set.
-
-Example:
- hwmon@ea0810 {
- compatible = "syna,as370-hwmon";
- reg = <0xea0810 0xc>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/aspeed,g6-pwm-tach.yaml b/Documentation/devicetree/bindings/hwmon/aspeed,g6-pwm-tach.yaml
new file mode 100644
index 000000000000..851fb16ec7fa
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/aspeed,g6-pwm-tach.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2023 Aspeed, Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/aspeed,g6-pwm-tach.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED G6 PWM and Fan Tach controller
+
+maintainers:
+ - Billy Tsai <billy_tsai@aspeedtech.com>
+
+description: |
+ The ASPEED PWM controller can support up to 16 PWM outputs.
+ The ASPEED Fan Tacho controller can support up to 16 fan tach input.
+ They are independent hardware blocks, which are different from the
+ previous version of the ASPEED chip.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: aspeed,ast2700-pwm-tach
+ - const: aspeed,ast2600-pwm-tach
+ - const: aspeed,ast2600-pwm-tach
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ "#pwm-cells":
+ const: 3
+
+patternProperties:
+ "^fan-[0-9]+$":
+ $ref: fan-common.yaml#
+ unevaluatedProperties: false
+ required:
+ - tach-ch
+
+required:
+ - reg
+ - clocks
+ - resets
+ - "#pwm-cells"
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/aspeed-clock.h>
+ pwm_tach: pwm-tach-controller@1e610000 {
+ compatible = "aspeed,ast2600-pwm-tach";
+ reg = <0x1e610000 0x100>;
+ clocks = <&syscon ASPEED_CLK_AHB>;
+ resets = <&syscon ASPEED_RESET_PWM>;
+ #pwm-cells = <3>;
+
+ fan-0 {
+ tach-ch = /bits/ 8 <0x0>;
+ pwms = <&pwm_tach 0 40000 0>;
+ };
+
+ fan-1 {
+ tach-ch = /bits/ 8 <0x1 0x2>;
+ pwms = <&pwm_tach 1 40000 0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt
index 3ac02988a1a5..8645cd3b867a 100644
--- a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt
+++ b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt
@@ -45,7 +45,7 @@ Required properties for each child node:
- aspeed,fan-tach-ch : should specify the Fan tach input channel.
integer value in the range 0 through 15, with 0 indicating
Fan tach channel 0 and 15 indicating Fan tach channel 15.
- Atleast one Fan tach input channel is required.
+ At least one Fan tach input channel is required.
Examples:
diff --git a/Documentation/devicetree/bindings/hwmon/dps650ab.txt b/Documentation/devicetree/bindings/hwmon/dps650ab.txt
deleted file mode 100644
index 76780e795899..000000000000
--- a/Documentation/devicetree/bindings/hwmon/dps650ab.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-Bindings for Delta Electronics DPS-650-AB power supply
-
-Required properties:
-- compatible : "delta,dps650ab"
-- reg : I2C address, one of 0x58, 0x59.
-
-Example:
- dps650ab@58 {
- compatible = "delta,dps650ab";
- reg = <0x58>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/fan-common.yaml b/Documentation/devicetree/bindings/hwmon/fan-common.yaml
new file mode 100644
index 000000000000..0fb738081699
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/fan-common.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/fan-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common Fan Properties
+
+maintainers:
+ - Naresh Solanki <naresh.solanki@9elements.com>
+ - Billy Tsai <billy_tsai@aspeedtech.com>
+
+properties:
+ max-rpm:
+ description:
+ Max RPM supported by fan.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 100000
+
+ min-rpm:
+ description:
+ Min RPM supported by fan.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 1000
+
+ pulses-per-revolution:
+ description:
+ The number of pulse from fan sensor per revolution.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 4
+
+ tach-div:
+ description:
+ Divisor for the tach sampling clock, which determines the sensitivity of the tach pin.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ target-rpm:
+ description:
+ The default desired fan speed in RPM.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ fan-driving-mode:
+ description:
+ Select the driving mode of the fan.(DC, PWM and so on)
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ dc, pwm ]
+
+ pwms:
+ description:
+ PWM provider.
+ maxItems: 1
+
+ "#cooling-cells":
+ const: 2
+
+ cooling-levels:
+ description:
+ The control value which correspond to thermal cooling states.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ tach-ch:
+ description:
+ The tach channel used for the fan.
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+
+ label:
+ description:
+ Optional fan label
+
+ fan-supply:
+ description:
+ Power supply for fan.
+
+ reg:
+ maxItems: 1
+
+additionalProperties: true
+
+...
diff --git a/Documentation/devicetree/bindings/hwmon/g762.txt b/Documentation/devicetree/bindings/hwmon/g762.txt
deleted file mode 100644
index 6d154c4923de..000000000000
--- a/Documentation/devicetree/bindings/hwmon/g762.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-GMT G762/G763 PWM Fan controller
-
-Required node properties:
-
- - "compatible": must be either "gmt,g762" or "gmt,g763"
- - "reg": I2C bus address of the device
- - "clocks": a fixed clock providing input clock frequency
- on CLK pin of the chip.
-
-Optional properties:
-
- - "fan_startv": fan startup voltage. Accepted values are 0, 1, 2 and 3.
- The higher the more.
-
- - "pwm_polarity": pwm polarity. Accepted values are 0 (positive duty)
- and 1 (negative duty).
-
- - "fan_gear_mode": fan gear mode. Supported values are 0, 1 and 2.
-
-If an optional property is not set in .dts file, then current value is kept
-unmodified (e.g. u-boot installed value).
-
-Additional information on operational parameters for the device is available
-in Documentation/hwmon/g762.rst. A detailed datasheet for the device is available
-at http://natisbad.org/NAS/refs/GMT_EDS-762_763-080710-0.2.pdf.
-
-Example g762 node:
-
- clocks {
- #address-cells = <1>;
- #size-cells = <0>;
-
- g762_clk: fixedclk {
- compatible = "fixed-clock";
- #clock-cells = <0>;
- clock-frequency = <8192>;
- }
- }
-
- g762: g762@3e {
- compatible = "gmt,g762";
- reg = <0x3e>;
- clocks = <&g762_clk>
- fan_gear_mode = <0>; /* chip default */
- fan_startv = <1>; /* chip default */
- pwm_polarity = <0>; /* chip default */
- };
diff --git a/Documentation/devicetree/bindings/hwmon/gmt,g762.yaml b/Documentation/devicetree/bindings/hwmon/gmt,g762.yaml
new file mode 100644
index 000000000000..8e1bffd252e6
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/gmt,g762.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/gmt,g762.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GMT G761/G762/G763 PWM Fan controller
+
+maintainers:
+ - Christian Marangi <ansuelsmth@gmail.com>
+
+description: |
+ GMT G761/G762/G763 PWM Fan controller.
+
+ G761 supports an internal-clock hence the clocks property is optional.
+ If not defined, internal-clock will be used. (31KHz is the clock of
+ the internal crystal oscillator)
+
+ If an optional property is not set in DT, then current value is kept
+ unmodified (e.g. bootloader installed value).
+
+ Additional information on operational parameters for the device is available
+ in Documentation/hwmon/g762.rst. A detailed datasheet for the device is available
+ at http://natisbad.org/NAS/refs/GMT_EDS-762_763-080710-0.2.pdf.
+
+properties:
+ compatible:
+ enum:
+ - gmt,g761
+ - gmt,g762
+ - gmt,g763
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: a fixed clock providing input clock frequency on CLK
+ pin of the chip.
+ maxItems: 1
+
+ fan_startv:
+ description: Fan startup voltage step
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+ pwm_polarity:
+ description: PWM polarity (positive or negative duty)
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+
+ fan_gear_mode:
+ description: FAN gear mode. Configure High speed fan setting factor
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+
+required:
+ - compatible
+ - reg
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - gmt,g762
+ - gmt,g763
+then:
+ required:
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ g762@3e {
+ compatible = "gmt,g762";
+ reg = <0x3e>;
+ clocks = <&g762_clk>;
+ fan_gear_mode = <0>;
+ fan_startv = <1>;
+ pwm_polarity = <0>;
+ };
+
+ g761@1e {
+ compatible = "gmt,g761";
+ reg = <0x1e>;
+ fan_gear_mode = <0>;
+ fan_startv = <1>;
+ pwm_polarity = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt
deleted file mode 100644
index f4cfa350f6a1..000000000000
--- a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Bindings for fan connected to GPIO lines
-
-Required properties:
-- compatible : "gpio-fan"
-
-Optional properties:
-- gpios: Specifies the pins that map to bits in the control value,
- ordered MSB-->LSB.
-- gpio-fan,speed-map: A mapping of possible fan RPM speeds and the
- control value that should be set to achieve them. This array
- must have the RPM values in ascending order.
-- alarm-gpios: This pin going active indicates something is wrong with
- the fan, and a udev event will be fired.
-- #cooling-cells: If used as a cooling device, must be <2>
- Also see:
- Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml
- min and max states are derived from the speed-map of the fan.
-
-Note: At least one the "gpios" or "alarm-gpios" properties must be set.
-
-Examples:
-
- gpio_fan {
- compatible = "gpio-fan";
- gpios = <&gpio1 14 1
- &gpio1 13 1>;
- gpio-fan,speed-map = <0 0
- 3000 1
- 6000 2>;
- alarm-gpios = <&gpio1 15 1>;
- };
- gpio_fan_cool: gpio_fan {
- compatible = "gpio-fan";
- gpios = <&gpio2 14 1
- &gpio2 13 1>;
- gpio-fan,speed-map = <0 0>,
- <3000 1>,
- <6000 2>;
- alarm-gpios = <&gpio2 15 1>;
- #cooling-cells = <2>; /* min followed by max */
- };
diff --git a/Documentation/devicetree/bindings/hwmon/gpio-fan.yaml b/Documentation/devicetree/bindings/hwmon/gpio-fan.yaml
new file mode 100644
index 000000000000..4faebbb4c7ab
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/gpio-fan.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/gpio-fan.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fan connected to GPIO lines
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+properties:
+ compatible:
+ const: gpio-fan
+
+ gpios:
+ description: |
+ Specifies the pins that map to bits in the control value,
+ ordered MSB-->LSB.
+ minItems: 1
+ maxItems: 7
+
+ alarm-gpios:
+ maxItems: 1
+
+ fan-supply:
+ description: Power supply for fan
+
+ gpio-fan,speed-map:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ minItems: 2
+ maxItems: 127
+ items:
+ items:
+ - description: fan speed in RPMs
+ - description: control value
+ description: |
+ A mapping of possible fan RPM speeds and the
+ control value that should be set to achieve them. This array
+ must have the RPM values in ascending order.
+
+ '#cooling-cells':
+ const: 2
+
+required:
+ - compatible
+ - gpios
+ - gpio-fan,speed-map
+
+additionalProperties: false
+
+examples:
+ - |
+ gpio-fan {
+ compatible = "gpio-fan";
+ gpios = <&gpio2 14 1
+ &gpio2 13 1>;
+ gpio-fan,speed-map = < 0 0>,
+ <3000 1>,
+ <6000 2>;
+ alarm-gpios = <&gpio2 15 1>;
+ #cooling-cells = <2>; /* min followed by max */
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/hih6130.txt b/Documentation/devicetree/bindings/hwmon/hih6130.txt
deleted file mode 100644
index 2c43837af4c2..000000000000
--- a/Documentation/devicetree/bindings/hwmon/hih6130.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-Honeywell Humidicon HIH-6130 humidity/temperature sensor
---------------------------------------------------------
-
-Requires node properties:
-- compatible : "honeywell,hi6130"
-- reg : the I2C address of the device. This is 0x27.
-
-Example:
- hih6130@27 {
- compatible = "honeywell,hih6130";
- reg = <0x27>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml b/Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml
new file mode 100644
index 000000000000..4a52aac6be72
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/hpe,gxp-fan-ctrl.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/hpe,gxp-fan-ctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HPE GXP Fan Controller
+
+maintainers:
+ - Nick Hawkins <nick.hawkins@hpe.com>
+
+description: |
+ The HPE GXP fan controller controls the fans through an external CPLD
+ device that connects to the fans.
+
+properties:
+ compatible:
+ const: hpe,gxp-fan-ctrl
+
+ reg:
+ items:
+ - description: Fan controller PWM
+ - description: Programmable logic
+ - description: Function 2
+
+ reg-names:
+ items:
+ - const: base
+ - const: pl
+ - const: fn2
+
+required:
+ - compatible
+ - reg
+ - reg-names
+
+additionalProperties: false
+
+examples:
+ - |
+ fan-controller@1000c00 {
+ compatible = "hpe,gxp-fan-ctrl";
+ reg = <0x1000c00 0x200>, <0xd1000000 0xff>, <0x80200000 0x100000>;
+ reg-names = "base", "pl", "fn2";
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/hwmon-common.yaml b/Documentation/devicetree/bindings/hwmon/hwmon-common.yaml
new file mode 100644
index 000000000000..dc86b5c72cf2
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/hwmon-common.yaml
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/hwmon-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Hardware Monitoring Devices Common Properties
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+
+properties:
+ label:
+ description: A descriptive name for this device.
+
+ shunt-resistor-micro-ohms:
+ description: The value of current sense resistor.
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt b/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt
deleted file mode 100644
index d9a2719f9243..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ibm,cffps1.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Device-tree bindings for IBM Common Form Factor Power Supply Versions 1 and 2
------------------------------------------------------------------------------
-
-Required properties:
- - compatible : Must be one of the following:
- "ibm,cffps1"
- "ibm,cffps2"
- or "ibm,cffps" if the system
- must support any version of the
- power supply
- - reg = < I2C bus address >; : Address of the power supply on the
- I2C bus.
-
-Example:
-
- i2c-bus@100 {
- #address-cells = <1>;
- #size-cells = <0>;
- #interrupt-cells = <1>;
- < more properties >
-
- power-supply@68 {
- compatible = "ibm,cffps1";
- reg = <0x68>;
- };
- };
diff --git a/Documentation/devicetree/bindings/hwmon/ibm,occ-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/ibm,occ-hwmon.yaml
new file mode 100644
index 000000000000..3dbdc5af2804
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ibm,occ-hwmon.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ibm,occ-hwmon.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM On-Chip Controller (OCC) accessed from a service processor
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description: |
+ The POWER processor On-Chip Controller (OCC) helps manage power and
+ thermals for the system. A service processor or baseboard management
+ controller can query the OCC for it's power and thermal data to report
+ through hwmon.
+
+properties:
+ compatible:
+ enum:
+ - ibm,p9-occ-hwmon
+ - ibm,p10-occ-hwmon
+
+ ibm,no-poll-on-init:
+ description: This property describes whether or not the OCC should
+ be polled during driver initialization.
+ type: boolean
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ hwmon {
+ compatible = "ibm,p10-occ-hwmon";
+ ibm,no-poll-on-init;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ibm,opal-sensor.yaml b/Documentation/devicetree/bindings/hwmon/ibm,opal-sensor.yaml
new file mode 100644
index 000000000000..376ee7f1cdb7
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ibm,opal-sensor.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ibm,opal-sensor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM POWERNV platform sensors
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - ibm,opal-sensor-cooling-fan
+ - ibm,opal-sensor-amb-temp
+ - ibm,opal-sensor-power-supply
+ - ibm,opal-sensor-power
+
+ sensor-id:
+ description:
+ An opaque id provided by the firmware to the kernel, identifies a
+ given sensor and its attribute data.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - sensor-id
+
+additionalProperties: false
+
+examples:
+ - |
+ sensor {
+ compatible = "ibm,opal-sensor-cooling-fan";
+ sensor-id = <0x7052107>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ibmpowernv.txt b/Documentation/devicetree/bindings/hwmon/ibmpowernv.txt
deleted file mode 100644
index f93242be60a1..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ibmpowernv.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-IBM POWERNV platform sensors
-----------------------------
-
-Required node properties:
-- compatible: must be one of
- "ibm,opal-sensor-cooling-fan"
- "ibm,opal-sensor-amb-temp"
- "ibm,opal-sensor-power-supply"
- "ibm,opal-sensor-power"
-- sensor-id: an opaque id provided by the firmware to the kernel, identifies a
- given sensor and its attribute data
-
-Example sensors node:
-
-cooling-fan#8-data {
- sensor-id = <0x7052107>;
- compatible = "ibm,opal-sensor-cooling-fan";
-};
-
-amb-temp#1-thrs {
- sensor-id = <0x5096000>;
- compatible = "ibm,opal-sensor-amb-temp";
-};
diff --git a/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml
new file mode 100644
index 000000000000..be5c7d4579bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/iio-hwmon.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/iio-hwmon.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADC-attached Hardware Sensor
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: >
+ Bindings for hardware monitoring devices connected to ADC controllers
+ supporting the Industrial I/O bindings.
+
+properties:
+ compatible:
+ const: iio-hwmon
+
+ io-channels:
+ minItems: 1
+ maxItems: 51 # Should be enough
+ description: >
+ List of phandles to ADC channels to read the monitoring values
+
+required:
+ - compatible
+ - io-channels
+
+additionalProperties: false
+
+examples:
+ - |
+ iio-hwmon {
+ compatible = "iio-hwmon";
+ io-channels = <&adc 1>, <&adc 2>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ina3221.txt b/Documentation/devicetree/bindings/hwmon/ina3221.txt
deleted file mode 100644
index fa63b6171407..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ina3221.txt
+++ /dev/null
@@ -1,54 +0,0 @@
-Texas Instruments INA3221 Device Tree Bindings
-
-1) ina3221 node
- Required properties:
- - compatible: Must be "ti,ina3221"
- - reg: I2C address
-
- Optional properties:
- - ti,single-shot: This chip has two power modes: single-shot (chip takes one
- measurement and then shuts itself down) and continuous (
- chip takes continuous measurements). The continuous mode is
- more reliable and suitable for hardware monitor type device,
- but the single-shot mode is more power-friendly and useful
- for battery-powered device which cares power consumptions
- while still needs some measurements occasionally.
- If this property is present, the single-shot mode will be
- used, instead of the default continuous one for monitoring.
-
- = The node contains optional child nodes for three channels =
- = Each child node describes the information of input source =
-
- - #address-cells: Required only if a child node is present. Must be 1.
- - #size-cells: Required only if a child node is present. Must be 0.
-
-2) child nodes
- Required properties:
- - reg: Must be 0, 1 or 2, corresponding to IN1, IN2 or IN3 port of INA3221
-
- Optional properties:
- - label: Name of the input source
- - shunt-resistor-micro-ohms: Shunt resistor value in micro-Ohm
-
-Example:
-
-ina3221@40 {
- compatible = "ti,ina3221";
- reg = <0x40>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- input@0 {
- reg = <0x0>;
- status = "disabled";
- };
- input@1 {
- reg = <0x1>;
- shunt-resistor-micro-ohms = <5000>;
- };
- input@2 {
- reg = <0x2>;
- label = "VDD_5V";
- shunt-resistor-micro-ohms = <5000>;
- };
-};
diff --git a/Documentation/devicetree/bindings/hwmon/jc42.txt b/Documentation/devicetree/bindings/hwmon/jc42.txt
deleted file mode 100644
index f569db58f64a..000000000000
--- a/Documentation/devicetree/bindings/hwmon/jc42.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-Properties for Jedec JC-42.4 compatible temperature sensors
-
-Required properties:
-- compatible: May include a device-specific string consisting of the
- manufacturer and the name of the chip. A list of supported
- chip names follows.
- Must include "jedec,jc-42.4-temp" for any Jedec JC-42.4
- compatible temperature sensor.
-
- Supported chip names:
- adi,adt7408
- atmel,at30ts00
- atmel,at30tse004
- onnn,cat6095
- onnn,cat34ts02
- maxim,max6604
- microchip,mcp9804
- microchip,mcp9805
- microchip,mcp9808
- microchip,mcp98243
- microchip,mcp98244
- microchip,mcp9843
- nxp,se97
- nxp,se98
- st,stts2002
- st,stts2004
- st,stts3000
- st,stts424
- st,stts424e
- idt,tse2002
- idt,tse2004
- idt,ts3000
- idt,ts3001
-
-- reg: I2C address
-
-Optional properties:
-- smbus-timeout-disable: When set, the smbus timeout function will be disabled.
- This is not supported on all chips.
-
-Example:
-
-temp-sensor@1a {
- compatible = "jedec,jc-42.4-temp";
- reg = <0x1a>;
-};
diff --git a/Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml b/Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml
new file mode 100644
index 000000000000..bf3332153ad8
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/jedec,jc42.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/jedec,jc42.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Jedec JC-42.4 compatible temperature sensors
+
+maintainers:
+ - Jean Delvare <jdelvare@suse.com>
+ - Guenter Roeck <linux@roeck-us.net>
+
+select:
+ properties:
+ compatible:
+ const: jedec,jc-42.4-temp
+
+ required:
+ - compatible
+
+properties:
+ compatible:
+ oneOf:
+ - const: jedec,jc-42.4-temp
+ - items:
+ - enum:
+ - adi,adt7408
+ - atmel,at30ts00
+ - atmel,at30tse004
+ - idt,tse2002
+ - idt,tse2004
+ - idt,ts3000
+ - idt,ts3001
+ - maxim,max6604
+ - microchip,mcp9804
+ - microchip,mcp9805
+ - microchip,mcp9808
+ - microchip,mcp98243
+ - microchip,mcp98244
+ - microchip,mcp9843
+ - nxp,se97
+ - nxp,se97b
+ - nxp,se98
+ - onnn,cat6095
+ - onnn,cat34ts02
+ - st,stts2002
+ - st,stts2004
+ - st,stts3000
+ - st,stts424
+ - st,stts424e
+ - const: jedec,jc-42.4-temp
+
+ reg:
+ maxItems: 1
+
+ smbus-timeout-disable:
+ description: |
+ When set, the smbus timeout function will be disabled. This is not
+ supported on all chips.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temp-sensor@1a {
+ compatible = "jedec,jc-42.4-temp";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/kontron,sl28cpld-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/kontron,sl28cpld-hwmon.yaml
index 010333cb25c0..966b221b6caa 100644
--- a/Documentation/devicetree/bindings/hwmon/kontron,sl28cpld-hwmon.yaml
+++ b/Documentation/devicetree/bindings/hwmon/kontron,sl28cpld-hwmon.yaml
@@ -11,11 +11,12 @@ maintainers:
description: |
This module is part of the sl28cpld multi-function device. For more
- details see ../mfd/kontron,sl28cpld.yaml.
+ details see ../embedded-controller/kontron,sl28cpld.yaml.
properties:
compatible:
enum:
+ - kontron,sa67mcu-hwmon
- kontron,sl28cpld-fan
reg:
diff --git a/Documentation/devicetree/bindings/hwmon/lantiq,cputemp.yaml b/Documentation/devicetree/bindings/hwmon/lantiq,cputemp.yaml
new file mode 100644
index 000000000000..9419b481ff35
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/lantiq,cputemp.yaml
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/lantiq,cputemp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lantiq cpu temperature sensor
+
+maintainers:
+ - Florian Eckert <fe@dev.tdt.de>
+
+properties:
+ compatible:
+ const: lantiq,cputemp
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ cputemp@103040 {
+ compatible = "lantiq,cputemp";
+ reg = <0x103040 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/lltc,ltc2978.yaml b/Documentation/devicetree/bindings/hwmon/lltc,ltc2978.yaml
new file mode 100644
index 000000000000..ea8b1553a3e9
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/lltc,ltc2978.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/lltc,ltc2978.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Octal Digital Power-supply monitor/supervisor/sequencer/margin controller.
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - lltc,lt7170
+ - lltc,lt7171
+ - lltc,ltc2972
+ - lltc,ltc2974
+ - lltc,ltc2975
+ - lltc,ltc2977
+ - lltc,ltc2978
+ - lltc,ltc2979
+ - lltc,ltc2980
+ - lltc,ltc3880
+ - lltc,ltc3882
+ - lltc,ltc3883
+ - lltc,ltc3884
+ - lltc,ltc3886
+ - lltc,ltc3887
+ - lltc,ltc3889
+ - lltc,ltc7132
+ - lltc,ltc7841
+ - lltc,ltc7880
+ - lltc,ltm2987
+ - lltc,ltm4664
+ - lltc,ltm4673
+ - lltc,ltm4675
+ - lltc,ltm4676
+ - lltc,ltm4677
+ - lltc,ltm4678
+ - lltc,ltm4680
+ - lltc,ltm4686
+ - lltc,ltm4700
+
+ reg:
+ maxItems: 1
+
+ regulators:
+ type: object
+ description: |
+ list of regulators provided by this controller.
+ Valid names of regulators depend on number of supplies supported per device:
+ * lt7170, lt7171 : vout0
+ * ltc2972 vout0 - vout1
+ * ltc2974, ltc2975 : vout0 - vout3
+ * ltc2977, ltc2979, ltc2980, ltm2987 : vout0 - vout7
+ * ltc2978 : vout0 - vout7
+ * ltc3880, ltc3882, ltc3884, ltc3886, ltc3887, ltc3889 : vout0 - vout1
+ * ltc7132 : vout0 - vout1
+ * ltc7841 : vout0
+ * ltc7880 : vout0 - vout1
+ * ltc3883 : vout0
+ * ltm4664 : vout0 - vout1
+ * ltm4673 : vout0 - vout3
+ * ltm4675, ltm4676, ltm4677, ltm4678 : vout0 - vout1
+ * ltm4680, ltm4686 : vout0 - vout1
+ * ltm4700 : vout0 - vout1
+
+ patternProperties:
+ "^vout[0-7]$":
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ regulator@5e {
+ compatible = "lltc,ltc2978";
+ reg = <0x5e>;
+
+ regulators {
+ vout0 {
+ regulator-name = "FPGA-2.5V";
+ };
+ vout2 {
+ regulator-name = "FPGA-1.5V";
+ };
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml b/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml
new file mode 100644
index 000000000000..8f0095bb7f6e
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/lltc,ltc4151.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/lltc,ltc4151.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LTC4151 High Voltage I2C Current and Voltage Monitor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ const: lltc,ltc4151
+
+ reg:
+ maxItems: 1
+
+ shunt-resistor-micro-ohms:
+ description:
+ Shunt resistor value in micro-Ohms
+ default: 1000
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: hwmon-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@6e {
+ compatible = "lltc,ltc4151";
+ reg = <0x6e>;
+ shunt-resistor-micro-ohms = <1500>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/lltc,ltc4286.yaml b/Documentation/devicetree/bindings/hwmon/lltc,ltc4286.yaml
new file mode 100644
index 000000000000..853df9fef6c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/lltc,ltc4286.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/lltc,ltc4286.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LTC4286 power monitors
+
+maintainers:
+ - Delphine CC Chiu <Delphine_CC_Chiu@Wiwynn.com>
+
+properties:
+ compatible:
+ enum:
+ - lltc,ltc4286
+ - lltc,ltc4287
+
+ reg:
+ maxItems: 1
+
+ adi,vrange-low-enable:
+ description:
+ This property is a bool parameter to represent the
+ voltage range is 25.6 volts or 102.4 volts for this chip.
+ The default is 102.4 volts.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: hwmon-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ power-monitor@40 {
+ compatible = "lltc,ltc4286";
+ reg = <0x40>;
+ adi,vrange-low-enable;
+ shunt-resistor-micro-ohms = <300>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/lm70.txt b/Documentation/devicetree/bindings/hwmon/lm70.txt
deleted file mode 100644
index ea417a0d32af..000000000000
--- a/Documentation/devicetree/bindings/hwmon/lm70.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-* LM70/TMP121/LM71/LM74 thermometer.
-
-Required properties:
-- compatible: one of
- "ti,lm70"
- "ti,tmp121"
- "ti,tmp122"
- "ti,lm71"
- "ti,lm74"
-
-See Documentation/devicetree/bindings/spi/spi-bus.txt for more required and
-optional properties.
-
-Example:
-
-spi_master {
- temperature-sensor@0 {
- compatible = "ti,lm70";
- reg = <0>;
- spi-max-frequency = <1000000>;
- };
-};
diff --git a/Documentation/devicetree/bindings/hwmon/lm75.yaml b/Documentation/devicetree/bindings/hwmon/lm75.yaml
index 72980d083c21..0b9fda81e3ec 100644
--- a/Documentation/devicetree/bindings/hwmon/lm75.yaml
+++ b/Documentation/devicetree/bindings/hwmon/lm75.yaml
@@ -1,4 +1,4 @@
-# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/hwmon/lm75.yaml#
@@ -14,6 +14,8 @@ properties:
compatible:
enum:
- adi,adt75
+ - ams,as6200
+ - atmel,at30ts74
- dallas,ds1775
- dallas,ds75
- dallas,ds7505
@@ -26,6 +28,8 @@ properties:
- maxim,max31725
- maxim,max31726
- maxim,mcp980x
+ - nxp,p3t1750
+ - nxp,p3t1755
- nxp,pct2075
- st,stds75
- st,stlm75
@@ -47,11 +51,31 @@ properties:
vs-supply:
description: phandle to the regulator that provides the +VS supply
+ interrupts:
+ maxItems: 1
+
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: hwmon-common.yaml#
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ams,as6200
+ - ti,tmp100
+ - ti,tmp101
+ - ti,tmp112
+ - ti,tmp75
+ then:
+ properties:
+ interrupts: false
+
+unevaluatedProperties: false
examples:
- |
@@ -65,3 +89,17 @@ examples:
vs-supply = <&vs>;
};
};
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@48 {
+ compatible = "ams,as6200";
+ reg = <0x48>;
+ vs-supply = <&vs>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <17 IRQ_TYPE_EDGE_BOTH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/lm87.txt b/Documentation/devicetree/bindings/hwmon/lm87.txt
deleted file mode 100644
index e1b79903f204..000000000000
--- a/Documentation/devicetree/bindings/hwmon/lm87.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-*LM87 hwmon sensor.
-
-Required properties:
-- compatible: Should be
- "ti,lm87"
-
-- reg: I2C address
-
-optional properties:
-- has-temp3: This configures pins 18 and 19 to be used as a second
- remote temperature sensing channel. By default the pins
- are configured as voltage input pins in0 and in5.
-
-- has-in6: When set, pin 5 is configured to be used as voltage input
- in6. Otherwise the pin is set as FAN1 input.
-
-- has-in7: When set, pin 6 is configured to be used as voltage input
- in7. Otherwise the pin is set as FAN2 input.
-
-- vcc-supply: a Phandle for the regulator supplying power, can be
- cofigured to measure 5.0V power supply. Default is 3.3V.
-
-Example:
-
-lm87@2e {
- compatible = "ti,lm87";
- reg = <0x2e>;
- has-temp3;
- vcc-supply = <&reg_5v0>;
-};
diff --git a/Documentation/devicetree/bindings/hwmon/lm90.txt b/Documentation/devicetree/bindings/hwmon/lm90.txt
deleted file mode 100644
index 398dcb965751..000000000000
--- a/Documentation/devicetree/bindings/hwmon/lm90.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-* LM90 series thermometer.
-
-Required node properties:
-- compatible: manufacturer and chip name, one of
- "adi,adm1032"
- "adi,adt7461"
- "adi,adt7461a"
- "gmt,g781"
- "national,lm90"
- "national,lm86"
- "national,lm89"
- "national,lm99"
- "dallas,max6646"
- "dallas,max6647"
- "dallas,max6649"
- "dallas,max6657"
- "dallas,max6658"
- "dallas,max6659"
- "dallas,max6680"
- "dallas,max6681"
- "dallas,max6695"
- "dallas,max6696"
- "onnn,nct1008"
- "winbond,w83l771"
- "nxp,sa56004"
- "ti,tmp451"
-
-- reg: I2C bus address of the device
-
-- vcc-supply: vcc regulator for the supply voltage.
-
-Optional properties:
-- interrupts: Contains a single interrupt specifier which describes the
- LM90 "-ALERT" pin output.
- See interrupt-controller/interrupts.txt for the format.
-
-- #thermal-sensor-cells: should be set to 1. See thermal/thermal-sensor.yaml
- for details. See <include/dt-bindings/thermal/lm90.h> for the
- definition of the local, remote and 2nd remote sensor index
- constants.
-
-Example LM90 node:
-
-temp-sensor {
- compatible = "onnn,nct1008";
- reg = <0x4c>;
- vcc-supply = <&palmas_ldo6_reg>;
- interrupt-parent = <&gpio>;
- interrupts = <TEGRA_GPIO(O, 4) IRQ_TYPE_LEVEL_LOW>;
- #thermal-sensor-cells = <1>;
-}
diff --git a/Documentation/devicetree/bindings/hwmon/ltc2978.txt b/Documentation/devicetree/bindings/hwmon/ltc2978.txt
deleted file mode 100644
index 4e7f6215a453..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ltc2978.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-ltc2978
-
-Required properties:
-- compatible: should contain one of:
- * "lltc,ltc2972"
- * "lltc,ltc2974"
- * "lltc,ltc2975"
- * "lltc,ltc2977"
- * "lltc,ltc2978"
- * "lltc,ltc2979"
- * "lltc,ltc2980"
- * "lltc,ltc3880"
- * "lltc,ltc3882"
- * "lltc,ltc3883"
- * "lltc,ltc3884"
- * "lltc,ltc3886"
- * "lltc,ltc3887"
- * "lltc,ltc3889"
- * "lltc,ltc7880"
- * "lltc,ltm2987"
- * "lltc,ltm4664"
- * "lltc,ltm4675"
- * "lltc,ltm4676"
- * "lltc,ltm4677"
- * "lltc,ltm4678"
- * "lltc,ltm4680"
- * "lltc,ltm4686"
- * "lltc,ltm4700"
-- reg: I2C slave address
-
-Optional properties:
-- regulators: A node that houses a sub-node for each regulator controlled by
- the device. Each sub-node is identified using the node's name, with valid
- values listed below. The content of each sub-node is defined by the
- standard binding for regulators; see regulator.txt.
-
-Valid names of regulators depend on number of supplies supported per device:
- * ltc2972 vout0 - vout1
- * ltc2974, ltc2975 : vout0 - vout3
- * ltc2977, ltc2979, ltc2980, ltm2987 : vout0 - vout7
- * ltc2978 : vout0 - vout7
- * ltc3880, ltc3882, ltc3884, ltc3886, ltc3887, ltc3889 : vout0 - vout1
- * ltc7880 : vout0 - vout1
- * ltc3883 : vout0
- * ltm4664 : vout0 - vout1
- * ltm4675, ltm4676, ltm4677, ltm4678 : vout0 - vout1
- * ltm4680, ltm4686 : vout0 - vout1
- * ltm4700 : vout0 - vout1
-
-Example:
-ltc2978@5e {
- compatible = "lltc,ltc2978";
- reg = <0x5e>;
- regulators {
- vout0 {
- regulator-name = "FPGA-2.5V";
- };
- vout2 {
- regulator-name = "FPGA-1.5V";
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/hwmon/ltc4151.txt b/Documentation/devicetree/bindings/hwmon/ltc4151.txt
deleted file mode 100644
index d008a5ef525a..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ltc4151.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-LTC4151 High Voltage I2C Current and Voltage Monitor
-
-Required properties:
-- compatible: Must be "lltc,ltc4151"
-- reg: I2C address
-
-Optional properties:
-- shunt-resistor-micro-ohms
- Shunt resistor value in micro-Ohms
- Defaults to <1000> if unset.
-
-Example:
-
-ltc4151@6e {
- compatible = "lltc,ltc4151";
- reg = <0x6e>;
- shunt-resistor-micro-ohms = <1500>;
-};
diff --git a/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt b/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt
deleted file mode 100644
index 33fd00a987c7..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ltq-cputemp.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-Lantiq cpu temperatur sensor
-
-Requires node properties:
-- compatible value :
- "lantiq,cputemp"
-
-Example:
- cputemp@0 {
- compatible = "lantiq,cputemp";
- };
diff --git a/Documentation/devicetree/bindings/hwmon/max1619.txt b/Documentation/devicetree/bindings/hwmon/max1619.txt
deleted file mode 100644
index c70dbbe1e56f..000000000000
--- a/Documentation/devicetree/bindings/hwmon/max1619.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-Bindings for MAX1619 Temperature Sensor
-
-Required properties:
-- compatible : "maxim,max1619"
-- reg : I2C address, one of 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, 0x4c, or
- 0x4d, 0x4e
-
-Example:
- temp@4c {
- compatible = "maxim,max1619";
- reg = <0x4c>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/max31785.txt b/Documentation/devicetree/bindings/hwmon/max31785.txt
deleted file mode 100644
index 106e08c56aaa..000000000000
--- a/Documentation/devicetree/bindings/hwmon/max31785.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Bindings for the Maxim MAX31785 Intelligent Fan Controller
-==========================================================
-
-Reference:
-
-https://datasheets.maximintegrated.com/en/ds/MAX31785.pdf
-
-The Maxim MAX31785 is a PMBus device providing closed-loop, multi-channel fan
-management with temperature and remote voltage sensing. Various fan control
-features are provided, including PWM frequency control, temperature hysteresis,
-dual tachometer measurements, and fan health monitoring.
-
-Required properties:
-- compatible : One of "maxim,max31785" or "maxim,max31785a"
-- reg : I2C address, one of 0x52, 0x53, 0x54, 0x55.
-
-Example:
-
- fans@52 {
- compatible = "maxim,max31785";
- reg = <0x52>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/max6650.txt b/Documentation/devicetree/bindings/hwmon/max6650.txt
deleted file mode 100644
index f6bd87d8e284..000000000000
--- a/Documentation/devicetree/bindings/hwmon/max6650.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Bindings for MAX6651 and MAX6650 I2C fan controllers
-
-Reference:
-[1] https://datasheets.maximintegrated.com/en/ds/MAX6650-MAX6651.pdf
-
-Required properties:
-- compatible : One of "maxim,max6650" or "maxim,max6651"
-- reg : I2C address, one of 0x1b, 0x1f, 0x4b, 0x48.
-
-Optional properties, default is to retain the chip's current setting:
-- maxim,fan-microvolt : The supply voltage of the fan, either 5000000 uV or
- 12000000 uV.
-- maxim,fan-prescale : Pre-scaling value, as per datasheet [1]. Lower values
- allow more fine-grained control of slower fans.
- Valid: 1, 2, 4, 8, 16.
-- maxim,fan-target-rpm: Initial requested fan rotation speed. If specified, the
- driver selects closed-loop mode and the requested speed.
- This ensures the fan is already running before userspace
- takes over.
-
-Example:
- fan-max6650: max6650@1b {
- reg = <0x1b>;
- compatible = "maxim,max6650";
- maxim,fan-microvolt = <12000000>;
- maxim,fan-prescale = <4>;
- maxim,fan-target-rpm = <1200>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/maxim,max20730.yaml b/Documentation/devicetree/bindings/hwmon/maxim,max20730.yaml
index 93e86e3b4602..8588d97ba6ec 100644
--- a/Documentation/devicetree/bindings/hwmon/maxim,max20730.yaml
+++ b/Documentation/devicetree/bindings/hwmon/maxim,max20730.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/maxim,max20730.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
@@ -26,6 +25,7 @@ description: |
properties:
compatible:
enum:
+ - maxim,max20710
- maxim,max20730
- maxim,max20734
- maxim,max20743
diff --git a/Documentation/devicetree/bindings/hwmon/maxim,max31790.yaml b/Documentation/devicetree/bindings/hwmon/maxim,max31790.yaml
new file mode 100644
index 000000000000..558cbd251b0f
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/maxim,max31790.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/maxim,max31790.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: The Maxim MAX31790 Fan Controller
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+ - Chanh Nguyen <chanh@os.amperecomputing.com>
+
+description: >
+ The MAX31790 controls the speeds of up to six fans using six
+ independent PWM outputs. The desired fan speeds (or PWM duty cycles)
+ are written through the I2C interface.
+
+ Datasheets:
+ https://datasheets.maximintegrated.com/en/ds/MAX31790.pdf
+
+properties:
+ compatible:
+ enum:
+ - maxim,max31785
+ - maxim,max31785a
+ - maxim,max31785b
+ - maxim,max31790
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ "#pwm-cells":
+ const: 1
+
+patternProperties:
+ "^fan@[0-9]+$":
+ $ref: fan-common.yaml#
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pwm_provider: fan-controller@20 {
+ compatible = "maxim,max31790";
+ reg = <0x20>;
+ clocks = <&sys_clk>;
+ resets = <&reset 0>;
+ #address-cells = <1>;
+ #pwm-cells = <1>;
+ #size-cells = <0>;
+
+ fan@0 {
+ reg = <0x0>;
+ pwms = <&pwm_provider 1>;
+ };
+
+ fan@1 {
+ reg = <0x1>;
+ pwms = <&pwm_provider 2>;
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml b/Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml
new file mode 100644
index 000000000000..139a95e00fe5
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/maxim,max6639.yaml
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/maxim,max6639.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim max6639
+
+maintainers:
+ - Naresh Solanki <naresh.solanki@9elements.com>
+
+description: |
+ The MAX6639 is a 2-channel temperature monitor with dual, automatic, PWM
+ fan-speed controller. It monitors its own temperature and one external
+ diode-connected transistor or the temperatures of two external diode-connected
+ transistors, typically available in CPUs, FPGAs, or GPUs.
+
+ Datasheets:
+ https://datasheets.maximintegrated.com/en/ds/MAX6639-MAX6639F.pdf
+
+properties:
+ compatible:
+ enum:
+ - maxim,max6639
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ '#pwm-cells':
+ const: 3
+
+required:
+ - compatible
+ - reg
+
+patternProperties:
+ "^fan@[0-1]$":
+ type: object
+ description:
+ Represents the two fans and their specific configuration.
+
+ $ref: fan-common.yaml#
+
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description:
+ The fan number.
+
+ required:
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fan1: fan-controller@10 {
+ compatible = "maxim,max6639";
+ reg = <0x10>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #pwm-cells = <3>;
+
+ fan@0 {
+ reg = <0x0>;
+ pulses-per-revolution = <2>;
+ max-rpm = <4000>;
+ target-rpm = <1000>;
+ pwms = <&fan1 0 25000 0>;
+ };
+
+ fan@1 {
+ reg = <0x1>;
+ pulses-per-revolution = <2>;
+ max-rpm = <8000>;
+ pwms = <&fan1 1 25000 0>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/maxim,max6650.yaml b/Documentation/devicetree/bindings/hwmon/maxim,max6650.yaml
new file mode 100644
index 000000000000..24c7697fdc1a
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/maxim,max6650.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/maxim,max6650.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX6650 and MAX6651 I2C Fan Controllers
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+description: |
+ The MAX6650 and MAX6651 regulate and monitor the speed
+ of 5VDC/12VDC burshless fans with built-in tachometers.
+
+ Datasheets:
+ https://datasheets.maximintegrated.com/en/ds/MAX6650-MAX6651.pdf
+
+properties:
+ compatible:
+ enum:
+ - maxim,max6650
+ - maxim,max6651
+
+ reg:
+ maxItems: 1
+
+ maxim,fan-microvolt:
+ description:
+ The supply voltage of the fan, either 5000000 uV or
+ 12000000 uV.
+ enum: [5000000, 12000000]
+
+ maxim,fan-prescale:
+ description:
+ Pre-scaling value, as per datasheet. Lower values
+ allow more fine-grained control of slower fans.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4, 8, 16]
+
+ maxim,fan-target-rpm:
+ description:
+ Initial requested fan rotation speed. If specified, the
+ driver selects closed-loop mode and the requested speed.
+ This ensures the fan is already running before userspace
+ takes over.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 30000
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fan-controller@1b {
+ compatible = "maxim,max6650";
+ reg = <0x1b>;
+ maxim,fan-microvolt = <12000000>;
+ maxim,fan-prescale = <4>;
+ maxim,fan-target-rpm = <1200>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/mcp3021.txt b/Documentation/devicetree/bindings/hwmon/mcp3021.txt
deleted file mode 100644
index 294318ba6914..000000000000
--- a/Documentation/devicetree/bindings/hwmon/mcp3021.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-mcp3021 properties
-
-Required properties:
-- compatible: Must be one of the following:
- - "microchip,mcp3021" for mcp3021
- - "microchip,mcp3221" for mcp3221
-- reg: I2C address
-
-Optional properties:
-
-- reference-voltage-microvolt
- Reference voltage in microvolt (uV)
-
-Example:
-
-mcp3021@4d {
- compatible = "microchip,mcp3021";
- reg = <0x4d>;
-
- reference-voltage-microvolt = <4500000>; /* 4.5 V */
-};
diff --git a/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml b/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
new file mode 100644
index 000000000000..d3f06ebc19fa
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/microchip,emc2305.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip EMC2305 SMBus compliant PWM fan controller
+
+maintainers:
+ - Michael Shych <michaelsh@nvidia.com>
+
+description:
+ Microchip EMC2301/2/3/5 pwm controller which supports up to five programmable
+ fan control circuits.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - microchip,emc2305
+ - items:
+ - enum:
+ - microchip,emc2303
+ - microchip,emc2302
+ - microchip,emc2301
+ - const: microchip,emc2305
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ '#pwm-cells':
+ const: 3
+ description: |
+ Number of cells in a PWM specifier.
+ - cell 0: The PWM frequency
+ - cell 1: The PWM polarity: 0 or PWM_POLARITY_INVERTED
+ - cell 2: The PWM output config:
+ - 0 (Open-Drain)
+ - 1 (Push-Pull)
+
+patternProperties:
+ '^fan@[0-4]$':
+ $ref: fan-common.yaml#
+ unevaluatedProperties: false
+ properties:
+ reg:
+ description:
+ The fan number used to determine the associated PWM channel.
+ maxItems: 1
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/pwm/pwm.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fan_controller: fan-controller@2f {
+ compatible = "microchip,emc2305";
+ reg = <0x2f>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #pwm-cells = <3>;
+
+ fan@0 {
+ reg = <0x0>;
+ pwms = <&fan_controller 26000 PWM_POLARITY_INVERTED 1>;
+ #cooling-cells = <2>;
+ };
+
+ fan@1 {
+ reg = <0x1>;
+ pwms = <&fan_controller 26000 0 1>;
+ #cooling-cells = <2>;
+ };
+
+ fan@2 {
+ reg = <0x2>;
+ pwms = <&fan_controller 26000 0 1>;
+ #cooling-cells = <2>;
+ };
+
+ fan@3 {
+ reg = <0x3>;
+ pwms = <&fan_controller 26000 0 1>;
+ #cooling-cells = <2>;
+ };
+
+ fan@4 {
+ reg = <0x4>;
+ pwms = <&fan_controller 26000 0 1>;
+ #cooling-cells = <2>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/microchip,lan966x.yaml b/Documentation/devicetree/bindings/hwmon/microchip,lan966x.yaml
new file mode 100644
index 000000000000..390dd6755ff5
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/microchip,lan966x.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/microchip,lan966x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip LAN966x Hardware Monitor
+
+maintainers:
+ - Michael Walle <michael@walle.cc>
+
+description: |
+ Microchip LAN966x temperature monitor and fan controller
+
+properties:
+ compatible:
+ enum:
+ - microchip,lan9668-hwmon
+
+ reg:
+ items:
+ - description: PVT registers
+ - description: FAN registers
+
+ reg-names:
+ items:
+ - const: pvt
+ - const: fan
+
+ clocks:
+ maxItems: 1
+
+ '#thermal-sensor-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ hwmon: hwmon@e2010180 {
+ compatible = "microchip,lan9668-hwmon";
+ reg = <0xe2010180 0xc>,
+ <0xe20042a8 0xc>;
+ reg-names = "pvt", "fan";
+ clocks = <&sys_clk>;
+ #thermal-sensor-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml b/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml
new file mode 100644
index 000000000000..f5e104c1b0d0
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/microchip,mcp3021.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/microchip,mcp3021.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MCP3021 A/D converter
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - microchip,mcp3021
+ - microchip,mcp3221
+
+ reg:
+ maxItems: 1
+
+ reference-voltage-microvolt:
+ description:
+ VDD supply power and reference voltage
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@4d {
+ compatible = "microchip,mcp3021";
+ reg = <0x4d>;
+
+ reference-voltage-microvolt = <4500000>; /* 4.5 V */
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml
index 76be625d5646..51e8619dbf3c 100644
--- a/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml
+++ b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml
@@ -22,7 +22,7 @@ properties:
clocks:
items:
- - description: AHB reference clock
+ - description: System reference clock
'#thermal-sensor-cells':
const: 0
@@ -40,5 +40,5 @@ examples:
compatible = "microchip,sparx5-temp";
reg = <0x10508110 0xc>;
#thermal-sensor-cells = <0>;
- clocks = <&ahb_clk>;
+ clocks = <&sys_clk>;
};
diff --git a/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml b/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml
index b79f069a04c2..56db2292f062 100644
--- a/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml
+++ b/Documentation/devicetree/bindings/hwmon/moortec,mr75203.yaml
@@ -4,11 +4,37 @@
$id: http://devicetree.org/schemas/hwmon/moortec,mr75203.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Moortec Semiconductor MR75203 PVT Controller bindings
+title: Moortec Semiconductor MR75203 PVT Controller
maintainers:
- Rahul Tanwar <rtanwar@maxlinear.com>
+description: |
+ A Moortec PVT (Process, Voltage, Temperature) monitoring logic design can
+ include many different units.
+ Such a design will usually consists of several Moortec's embedded analog IPs,
+ and a single Moortec controller (mr75203) to configure and control the IPs.
+
+ Some of the Moortec's analog hard IPs that can be used in a design:
+ *) Temperature Sensor (TS) - used to monitor core temperature (e.g. mr74137).
+ *) Voltage Monitor (VM) - used to monitor voltage levels (e.g. mr74138).
+ *) Process Detector (PD) - used to assess silicon speed (e.g. mr74139).
+ *) Delay Chain - ring oscillator connected to the PD, used to measure IO
+ based transistors (e.g. mr76008 ring oscillator at 1.1V, mr76007 ring
+ oscillator at 1.8V).
+ *) Pre Scaler - provides divide-by-X scaling of input voltage, which can then
+ be presented for VM for measurement within its range (e.g. mr76006 -
+ divide by 2 pre-scaler).
+
+ TS, VM & PD also include a digital interface, which consists of configuration
+ inputs and measurement outputs.
+
+ Some of the units have number of series, each series can have slightly
+ different characteristics.
+
+ The mr75203 binding describes configuration for the controller unit, but also
+ for some of the analog IPs.
+
properties:
compatible:
const: moortec,mr75203
@@ -16,7 +42,7 @@ properties:
reg:
items:
- description: PVT common registers
- - description: PVT temprature sensor registers
+ - description: PVT temperature sensor registers
- description: PVT process detector registers
- description: PVT voltage monitor registers
@@ -44,13 +70,76 @@ properties:
"#thermal-sensor-cells":
const: 1
+ moortec,vm-active-channels:
+ description:
+ Defines the number of channels per VM that are actually used and are
+ connected to some input source.
+ Maximum number of items - number of VMs.
+ Maximum value of each item - number of channels.
+ Minimum value of each item - 0 (which means entire VM sensor is not used).
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+
+ moortec,vm-pre-scaler-x2:
+ description:
+ Defines the channels that use a mr76006 pre-scaler to divide the input
+ source by 2.
+ The pre-scaler is used for input sources that exceed the VM input range.
+ The driver uses this information to present to the user with the actual
+ value of the voltage source.
+ For channels that are not listed, no pre-scaler is assumed.
+ Maximum number of items - total number of channels in all VMs.
+ Each channel should not appear more than once.
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+
+ moortec,ts-series:
+ description:
+ Definition of the temperature equation and coefficients that shall be
+ used to convert the digital output to value in milli-Celsius.
+ minimum: 5
+ maximum: 6
+ default: 5
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ moortec,ts-coeff-g:
+ description:
+ G coefficient for temperature equation.
+ Default for series 5 = 60000
+ Default for series 6 = 57400
+ multipleOf: 100
+ minimum: 1000
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ moortec,ts-coeff-h:
+ description:
+ H coefficient for temperature equation.
+ Default for series 5 = 200000
+ Default for series 6 = 249400
+ multipleOf: 100
+ minimum: 1000
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ moortec,ts-coeff-cal5:
+ description:
+ cal5 coefficient for temperature equation.
+ Default for series 5 = 4094
+ Default for series 6 = 4096
+ minimum: 1
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ moortec,ts-coeff-j:
+ description:
+ J coefficient for temperature equation.
+ Default for series 5 = -100
+ Default for series 6 = 0
+ multipleOf: 100
+ maximum: 0
+ $ref: /schemas/types.yaml#/definitions/int32
+
required:
- compatible
- reg
- reg-names
- - intel,vm-map
- clocks
- - resets
- "#thermal-sensor-cells"
additionalProperties: false
@@ -67,5 +156,9 @@ examples:
intel,vm-map = [03 01 04 ff ff];
clocks = <&osc0>;
resets = <&rcu0 0x40 7>;
+ moortec,vm-active-channels = /bits/ 8 <0x10 0x05>;
+ moortec,vm-pre-scaler-x2 = /bits/ 8 <5 6 20>;
+ moortec,ts-coeff-g = <61400>;
+ moortec,ts-coeff-h = <253700>;
#thermal-sensor-cells = <1>;
};
diff --git a/Documentation/devicetree/bindings/hwmon/national,lm90.yaml b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml
new file mode 100644
index 000000000000..164068ba069d
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/national,lm90.yaml
@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/national,lm90.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LM90 series thermometer
+
+maintainers:
+ - Jean Delvare <jdelvare@suse.com>
+ - Guenter Roeck <linux@roeck-us.net>
+
+properties:
+ compatible:
+ enum:
+ - adi,adm1032
+ - adi,adt7461
+ - adi,adt7461a
+ - adi,adt7481
+ - dallas,max6646
+ - dallas,max6647
+ - dallas,max6649
+ - dallas,max6654
+ - dallas,max6657
+ - dallas,max6658
+ - dallas,max6659
+ - dallas,max6680
+ - dallas,max6681
+ - dallas,max6695
+ - dallas,max6696
+ - gmt,g781
+ - national,lm86
+ - national,lm89
+ - national,lm90
+ - national,lm99
+ - nuvoton,nct7716
+ - nuvoton,nct7717
+ - nuvoton,nct7718
+ - nxp,sa56004
+ - onnn,nct72
+ - onnn,nct214
+ - onnn,nct218
+ - onnn,nct1008
+ - ti,tmp451
+ - ti,tmp461
+ - winbond,w83l771
+
+ interrupts:
+ items:
+ - description: |
+ Single interrupt specifier which describes the LM90 "-ALERT" pin
+ output.
+
+ reg:
+ maxItems: 1
+
+ "#thermal-sensor-cells":
+ const: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ vcc-supply:
+ description: phandle to the regulator that provides the +VCC supply
+
+ ti,extended-range-enable:
+ description: Set to enable extended range temperature.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+patternProperties:
+ "^channel@([0-2])$":
+ type: object
+ description: Represents channels of the device and their specific configuration.
+
+ properties:
+ reg:
+ description: The channel number. 0 is local channel, 1-2 are remote channels.
+ items:
+ minimum: 0
+ maximum: 2
+
+ label:
+ description: A descriptive name for this channel, like "ambient" or "psu".
+
+ temperature-offset-millicelsius:
+ description: Temperature offset to be added to or subtracted from remote temperature measurements.
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+allOf:
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adt7461
+ - adi,adt7461a
+ - adi,adt7481
+ - ti,tmp451
+ - ti,tmp461
+ then:
+ properties:
+ ti,extended-range-enable: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - dallas,max6646
+ - dallas,max6647
+ - dallas,max6649
+ - dallas,max6654
+ - dallas,max6657
+ - dallas,max6658
+ - dallas,max6659
+ - dallas,max6695
+ - dallas,max6696
+ - nuvoton,nct7716
+ - nuvoton,nct7717
+ then:
+ patternProperties:
+ "^channel@([0-2])$":
+ properties:
+ temperature-offset-millicelsius: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adt7461
+ - adi,adt7461a
+ - adi,adt7481
+ - onnn,nct72
+ - onnn,nct214
+ - onnn,nct218
+ - onnn,nct1008
+ then:
+ patternProperties:
+ "^channel@([0-2])$":
+ properties:
+ temperature-offset-millicelsius:
+ maximum: 127750
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adm1032
+ - dallas,max6680
+ - dallas,max6681
+ - gmt,g781
+ - national,lm86
+ - national,lm89
+ - national,lm90
+ - national,lm99
+ - nuvoton,nct7718
+ - nxp,sa56004
+ - winbond,w83l771
+ then:
+ patternProperties:
+ "^channel@([0-2])$":
+ properties:
+ temperature-offset-millicelsius:
+ maximum: 127875
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,tmp451
+ - ti,tmp461
+ then:
+ patternProperties:
+ "^channel@([0-2])$":
+ properties:
+ temperature-offset-millicelsius:
+ maximum: 127937
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4c {
+ compatible = "onnn,nct1008";
+ reg = <0x4c>;
+ vcc-supply = <&palmas_ldo6_reg>;
+ interrupts = <4 IRQ_TYPE_LEVEL_LOW>;
+ #thermal-sensor-cells = <1>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4c {
+ compatible = "adi,adt7481";
+ reg = <0x4c>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0x0>;
+ label = "local";
+ };
+
+ channel@1 {
+ reg = <0x1>;
+ label = "front";
+ temperature-offset-millicelsius = <4000>;
+ };
+
+ channel@2 {
+ reg = <0x2>;
+ label = "back";
+ temperature-offset-millicelsius = <750>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt
index 28f43e929f6d..18095ba87a5a 100644
--- a/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt
+++ b/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt
@@ -1,12 +1,16 @@
-Nuvoton NPCM7xx PWM and Fan Tacho controller device
+Nuvoton NPCM PWM and Fan Tacho controller device
The Nuvoton BMC NPCM7XX supports 8 Pulse-width modulation (PWM)
controller outputs and 16 Fan tachometer controller inputs.
+The Nuvoton BMC NPCM8XX supports 12 Pulse-width modulation (PWM)
+controller outputs and 16 Fan tachometer controller inputs.
+
Required properties for pwm-fan node
- #address-cells : should be 1.
- #size-cells : should be 0.
- compatible : "nuvoton,npcm750-pwm-fan" for Poleg NPCM7XX.
+ : "nuvoton,npcm845-pwm-fan" for Arbel NPCM8XX.
- reg : specifies physical base address and size of the registers.
- reg-names : must contain:
* "pwm" for the PWM registers.
@@ -23,7 +27,7 @@ Required properties for pwm-fan node
fan subnode format:
===================
Under fan subnode can be upto 8 child nodes, each child node representing a fan.
-Each fan subnode must have one PWM channel and atleast one Fan tach channel.
+Each fan subnode must have one PWM channel and at least one Fan tach channel.
For PWM channel can be configured cooling-levels to create cooling device.
Cooling device could be bound to a thermal zone for the thermal control.
diff --git a/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml
new file mode 100644
index 000000000000..dc8bc4c6df34
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ntc-thermistor.yaml
@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+---
+$id: http://devicetree.org/schemas/hwmon/ntc-thermistor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NTC thermistor temperature sensors
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description: |
+ Thermistors with negative temperature coefficient (NTC) are resistors that
+ vary in resistance in an often non-linear way in relation to temperature.
+ The negative temperature coefficient means that the resistance decreases
+ as the temperature rises. Since the relationship between resistance and
+ temperature is non-linear, software drivers most often need to use a look
+ up table and interpolation to get from resistance to temperature.
+
+ When used in practice, a thermistor is often connected between ground, a
+ pull-up resistor or/and a pull-down resistor and a fixed voltage like this:
+
+ + e.g. 5V = pull-up voltage (puv)
+ |
+ +-+
+ | |
+ | | Pull-up resistor
+ | | (puo)
+ +-+
+ |-------------------------o
+ +-+ | ^
+ | |/ |
+ | / |
+ |/| Thermistor | Measured voltage (mv)
+ / | | "connected ground"
+ /| | |
+ +-+ |
+ |-------------------------o
+ +-+ ^
+ | | |
+ | | Pull-down resistor | Measured voltage (mv)
+ | | (pdo) | "connected positive"
+ +-+ |
+ | |
+ | v
+ + GND GND
+
+ The arrangements of where we measure the voltage over the thermistor are
+ called "connected ground" and "connected positive" and shall be understood as
+ the cases when either pull-up or pull-down resistance is zero.
+
+ If the pull-up resistance is 0 one end of the thermistor is connected to the
+ positive voltage and we get the thermistor on top of a pull-down resistor
+ and we take the measure between the thermistor and the pull-down resistor.
+
+ Conversely if the pull-down resistance is zero, one end of the thermistor is
+ connected to ground and we get the thermistor under the pull-up resistor
+ and we take the measure between the pull-up resistor and the thermistor.
+
+ We can use both pull-up and pull-down resistors at the same time, and then
+ the figure illustrates where the voltage will be measured for the "connected
+ ground" and "connected positive" cases.
+
+properties:
+ $nodename:
+ pattern: "^thermistor(.*)?$"
+
+ compatible:
+ oneOf:
+ - const: epcos,b57330v2103
+ - const: epcos,b57891s0103
+ - const: murata,ncp15wb473
+ - const: murata,ncp18wb473
+ - const: murata,ncp21wb473
+ - const: murata,ncp03wb473
+ - const: murata,ncp15wl333
+ - const: murata,ncp03wf104
+ - const: murata,ncp15xh103
+ - const: murata,ncp18wm474
+ - const: samsung,1404-001221
+ # Deprecated "ntc," compatible strings
+ - const: ntc,ncp15wb473
+ deprecated: true
+ - const: ntc,ncp18wb473
+ deprecated: true
+ - const: ntc,ncp21wb473
+ deprecated: true
+ - const: ntc,ncp03wb473
+ deprecated: true
+ - const: ntc,ncp15wl333
+ deprecated: true
+
+ "#thermal-sensor-cells":
+ description: Thermal sensor cells if used for thermal sensoring.
+ const: 0
+
+ pullup-uv:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Pull-up voltage in micro volts. Must always be specified.
+
+ pullup-ohm:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Pull-up resistance in ohms. Must always be specified, even
+ if zero.
+
+ pulldown-ohm:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Pull-down resistance in ohms. Must always be specified, even
+ if zero.
+
+ connected-positive:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: Indicates how the thermistor is connected in series with
+ a pull-up and/or a pull-down resistor. See the description above for
+ an illustration. If this flag is NOT specified, the thermistor is assumed
+ to be connected-ground, which usually means a pull-down resistance of
+ zero but complex arrangements are possible.
+
+ # See /schemas/iio/adc/adc.yaml
+ io-channels:
+ maxItems: 1
+ description: IIO ADC channel to read the voltage over the resistor. Must
+ always be specified.
+
+required:
+ - compatible
+ - pullup-uv
+ - pullup-ohm
+ - pulldown-ohm
+ - io-channels
+
+additionalProperties: false
+
+examples:
+ - |
+ thermistor {
+ compatible = "murata,ncp18wb473";
+ io-channels = <&gpadc 0x06>;
+ pullup-uv = <1800000>;
+ pullup-ohm = <220000>;
+ pulldown-ohm = <0>;
+ #thermal-sensor-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt
deleted file mode 100644
index 4c5c3712970e..000000000000
--- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-NTC Thermistor hwmon sensors
--------------------------------
-
-Requires node properties:
-- "compatible" value : one of
- "epcos,b57330v2103"
- "epcos,b57891s0103"
- "murata,ncp15wb473"
- "murata,ncp18wb473"
- "murata,ncp21wb473"
- "murata,ncp03wb473"
- "murata,ncp15wl333"
- "murata,ncp03wf104"
- "murata,ncp15xh103"
-
-/* Usage of vendor name "ntc" is deprecated */
-<DEPRECATED> "ntc,ncp15wb473"
-<DEPRECATED> "ntc,ncp18wb473"
-<DEPRECATED> "ntc,ncp21wb473"
-<DEPRECATED> "ntc,ncp03wb473"
-<DEPRECATED> "ntc,ncp15wl333"
-
-- "pullup-uv" Pull up voltage in micro volts
-- "pullup-ohm" Pull up resistor value in ohms
-- "pulldown-ohm" Pull down resistor value in ohms
-- "connected-positive" Always ON, If not specified.
- Status change is possible.
-- "io-channels" Channel node of ADC to be used for
- conversion.
-
-Optional node properties:
-- "#thermal-sensor-cells" Used to expose itself to thermal fw.
-
-Read more about iio bindings at
- https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/
-
-Example:
- ncp15wb473@0 {
- compatible = "murata,ncp15wb473";
- pullup-uv = <1800000>;
- pullup-ohm = <47000>;
- pulldown-ohm = <0>;
- io-channels = <&adc 3>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/nuvoton,nct6775.yaml b/Documentation/devicetree/bindings/hwmon/nuvoton,nct6775.yaml
new file mode 100644
index 000000000000..244470282890
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/nuvoton,nct6775.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/nuvoton,nct6775.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton NCT6775 and compatible Super I/O chips
+
+maintainers:
+ - Zev Weiss <zev@bewilderbeest.net>
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,nct6106
+ - nuvoton,nct6116
+ - nuvoton,nct6775
+ - nuvoton,nct6776
+ - nuvoton,nct6779
+ - nuvoton,nct6791
+ - nuvoton,nct6792
+ - nuvoton,nct6793
+ - nuvoton,nct6795
+ - nuvoton,nct6796
+ - nuvoton,nct6797
+ - nuvoton,nct6798
+ - nuvoton,nct6799
+
+ reg:
+ maxItems: 1
+
+ nuvoton,tsi-channel-mask:
+ description:
+ Bitmask indicating which TSI temperature sensor channels are
+ active. LSB is TSI0, bit 1 is TSI1, etc.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 0xff
+ default: 0
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ superio@4d {
+ compatible = "nuvoton,nct6779";
+ reg = <0x4d>;
+ nuvoton,tsi-channel-mask = <0x03>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/nuvoton,nct7363.yaml b/Documentation/devicetree/bindings/hwmon/nuvoton,nct7363.yaml
new file mode 100644
index 000000000000..625fcf5d3b54
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/nuvoton,nct7363.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/nuvoton,nct7363.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton NCT7363Y Hardware Monitoring IC
+
+maintainers:
+ - Ban Feng <kcfeng0@nuvoton.com>
+
+description: |
+ The NCT7363Y is a fan controller which provides up to 16 independent
+ FAN input monitors, and up to 16 independent PWM outputs with SMBus interface.
+
+ Datasheets: Available from Nuvoton upon request
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,nct7363
+ - nuvoton,nct7362
+
+ reg:
+ maxItems: 1
+
+ "#pwm-cells":
+ const: 2
+
+patternProperties:
+ "^fan-[0-9]+$":
+ $ref: fan-common.yaml#
+ unevaluatedProperties: false
+ required:
+ - pwms
+ - tach-ch
+
+required:
+ - compatible
+ - reg
+ - "#pwm-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon: hwmon@22 {
+ compatible = "nuvoton,nct7363";
+ reg = <0x22>;
+ #pwm-cells = <2>;
+
+ fan-0 {
+ pwms = <&hwmon 0 50000>;
+ tach-ch = /bits/ 8 <0x00>;
+ };
+ fan-1 {
+ pwms = <&hwmon 1 50000>;
+ tach-ch = /bits/ 8 <0x01>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml b/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml
new file mode 100644
index 000000000000..c16a33227e94
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/nuvoton,nct7802.yaml
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/nuvoton,nct7802.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton NCT7802Y Hardware Monitoring IC
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+
+description: |
+ The NCT7802Y is a hardware monitor IC which supports one on-die and up to
+ 5 remote temperature sensors with SMBus interface.
+
+ Datasheets:
+ https://www.nuvoton.com/export/resource-files/Nuvoton_NCT7802Y_Datasheet_V12.pdf
+
+additionalProperties: false
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,nct7802
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^channel@[0-3]$":
+ type: object
+
+ additionalProperties: false
+
+ properties:
+ reg:
+ items:
+ - enum:
+ - 0 # Local Temperature Sensor ("LTD")
+ - 1 # Remote Temperature Sensor or Voltage Sensor 1 ("RTD1")
+ - 2 # Remote Temperature Sensor or Voltage Sensor 2 ("RTD2")
+ - 3 # Remote Temperature Sensor or Voltage Sensor 3 ("RTD3")
+
+ sensor-type:
+ items:
+ - enum:
+ - temperature
+ - voltage
+
+ temperature-mode:
+ items:
+ - enum:
+ - thermistor
+ - thermal-diode
+
+ required:
+ - reg
+
+ allOf:
+ # For channels RTD1, RTD2 and RTD3, require sensor-type to be set.
+ # Otherwise (for all other channels), do not allow temperature-mode to be
+ # set.
+ - if:
+ properties:
+ reg:
+ items:
+ - enum:
+ - 1
+ - 2
+ - 3
+ then:
+ required:
+ - sensor-type
+ else:
+ not:
+ required:
+ - sensor-type
+
+ # For channels RTD1 and RTD2 and if sensor-type is "temperature", require
+ # temperature-mode to be set. Otherwise (for all other channels or
+ # sensor-type settings), do not allow temperature-mode to be set
+ - if:
+ properties:
+ reg:
+ items:
+ - enum:
+ - 1
+ - 2
+ sensor-type:
+ items:
+ - enum:
+ - temperature
+ then:
+ required:
+ - temperature-mode
+ else:
+ not:
+ required:
+ - temperature-mode
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ nct7802@28 {
+ compatible = "nuvoton,nct7802";
+ reg = <0x28>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 { /* LTD */
+ reg = <0>;
+ };
+
+ channel@1 { /* RTD1 */
+ reg = <1>;
+ sensor-type = "voltage";
+ };
+
+ channel@2 { /* RTD2 */
+ reg = <2>;
+ sensor-type = "temperature";
+ temperature-mode = "thermal-diode";
+ };
+
+ channel@3 { /* RTD3 */
+ reg = <3>;
+ sensor-type = "temperature";
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml b/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml
new file mode 100644
index 000000000000..48d654e52114
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/nxp,mc34vr500.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/nxp,mc34vr500.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP MC34VR500 hwmon sensor
+
+maintainers:
+ - Mario Kicherer <dev@kicherer.org>
+
+properties:
+ compatible:
+ enum:
+ - nxp,mc34vr500
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pmic@8 {
+ compatible = "nxp,mc34vr500";
+ reg = <0x08>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/adi,adp1050.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/adi,adp1050.yaml
new file mode 100644
index 000000000000..af7530093942
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/adi,adp1050.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pmbus/adi,adp1050.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADP1050 digital controller with PMBus interface
+
+maintainers:
+ - Radu Sabau <radu.sabau@analog.com>
+
+description: |
+ The ADP1050 and similar devices are used to monitor system voltages,
+ currents, power, and temperatures.
+
+ Through the PMBus interface, the ADP1050 targets isolated power supplies
+ and has four individual monitors for input/output voltage, input current
+ and temperature.
+ Datasheet:
+ https://www.analog.com/en/products/adp1050.html
+ https://www.analog.com/en/products/adp1051.html
+ https://www.analog.com/en/products/adp1055.html
+ https://www.analog.com/en/products/ltp8800-1a.html
+ https://www.analog.com/en/products/ltp8800-2.html
+ https://www.analog.com/en/products/ltp8800-4a.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adp1050
+ - adi,adp1051
+ - adi,adp1055
+ - adi,ltp8800
+
+ reg:
+ maxItems: 1
+
+ vcc-supply: true
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clock-frequency = <100000>;
+
+ hwmon@70 {
+ compatible = "adi,adp1050";
+ reg = <0x70>;
+ vcc-supply = <&vcc>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/adi,lt3074.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/adi,lt3074.yaml
new file mode 100644
index 000000000000..bf028a8718f1
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/adi,lt3074.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pmbus/adi,lt3074.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LT3074 voltage regulator
+
+maintainers:
+ - Cedric Encarnacion <cedricjustine.encarnacion@analog.com>
+
+description: |
+ The LT3074 is a low voltage, ultra-low noise and ultra-fast transient
+ response linear regulator. It allows telemetry for input/output voltage,
+ output current and temperature through the PMBus serial interface.
+
+ Datasheet:
+ https://www.analog.com/en/products/lt3074.html
+
+allOf:
+ - $ref: /schemas/regulator/regulator.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,lt3074
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ regulator@6d {
+ compatible = "adi,lt3074";
+ reg = <0x6d>;
+ regulator-name = "vout";
+ regulator-max-microvolt = <1250000>;
+ regulator-min-microvolt = <1150000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/adi,max17616.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/adi,max17616.yaml
new file mode 100644
index 000000000000..fa48af81e083
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/adi,max17616.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pmbus/adi,max17616.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices MAX17616/MAX17616A Current-Limiter with PMBus Interface
+
+maintainers:
+ - Kim Seer Paller <kimseer.paller@analog.com>
+
+description: |
+ The MAX17616/MAX17616A is a 3V to 80V, 7A current-limiter with overvoltage,
+ surge, undervoltage, reverse polarity, and loss of ground protection. It allows
+ monitoring of input/output voltage, output current and temperature through the
+ PMBus serial interface.
+ Datasheet:
+ https://www.analog.com/en/products/max17616.html
+
+properties:
+ compatible:
+ const: adi,max17616
+
+ reg:
+ maxItems: 1
+
+ vcc-supply: true
+
+ interrupts:
+ description: Fault condition signal provided on SMBALERT pin.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon@16 {
+ compatible = "adi,max17616";
+ reg = <0x16>;
+ vcc-supply = <&vcc>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml
new file mode 100644
index 000000000000..5c4e52b472ad
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/hwmon/pmbus/infineon,tda38640.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Infineon TDA38640 Synchronous Buck Regulator with SVID and I2C
+
+maintainers:
+ - Naresh Solanki <naresh.solanki@9elements.com>
+
+description: |
+ The Infineon TDA38640 is a 40A Single-voltage Synchronous Buck
+ Regulator with SVID and I2C designed for Industrial use.
+
+ Datasheet: https://www.infineon.com/dgdl/Infineon-TDA38640-0000-DataSheet-v02_04-EN.pdf?fileId=8ac78c8c80027ecd018042f2337f00c9
+
+properties:
+ compatible:
+ enum:
+ - infineon,tda38640
+
+ reg:
+ maxItems: 1
+
+ infineon,en-pin-fixed-level:
+ description:
+ Indicates that the chip EN pin is at fixed level or left
+ unconnected(has internal pull-down).
+ type: boolean
+
+ interrupts:
+ maxItems: 1
+
+ regulators:
+ type: object
+ description:
+ list of regulators provided by this controller.
+
+ properties:
+ vout:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ tda38640@40 {
+ compatible = "infineon,tda38640";
+ reg = <0x40>;
+
+ interrupt-parent = <&smb_pex_cpu0_event>;
+ interrupts = <10 IRQ_TYPE_LEVEL_LOW>;
+
+ regulators {
+ pvnn_main_cpu0: vout {
+ regulator-name = "pvnn_main_cpu0";
+ regulator-enable-ramp-delay = <200>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/isil,isl68137.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/isil,isl68137.yaml
new file mode 100644
index 000000000000..ae23a05375cb
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/isil,isl68137.yaml
@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/hwmon/pmbus/isil,isl68137.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas Digital Multiphase Voltage Regulators with PMBus
+
+maintainers:
+ - Grant Peltier <grant.peltier.jg@renesas.com>
+
+description: |
+ Renesas digital multiphase voltage regulators with PMBus.
+ https://www.renesas.com/en/products/power-management/multiphase-power/multiphase-dcdc-switching-controllers
+
+properties:
+ compatible:
+ enum:
+ - isil,isl68137
+ - renesas,isl68220
+ - renesas,isl68221
+ - renesas,isl68222
+ - renesas,isl68223
+ - renesas,isl68224
+ - renesas,isl68225
+ - renesas,isl68226
+ - renesas,isl68227
+ - renesas,isl68229
+ - renesas,isl68233
+ - renesas,isl68239
+ - renesas,isl69222
+ - renesas,isl69223
+ - renesas,isl69224
+ - renesas,isl69225
+ - renesas,isl69227
+ - renesas,isl69228
+ - renesas,isl69234
+ - renesas,isl69236
+ - renesas,isl69239
+ - renesas,isl69242
+ - renesas,isl69243
+ - renesas,isl69247
+ - renesas,isl69248
+ - renesas,isl69254
+ - renesas,isl69255
+ - renesas,isl69256
+ - renesas,isl69259
+ - isil,isl69260
+ - renesas,isl69268
+ - isil,isl69269
+ - renesas,isl69298
+ - renesas,raa228000
+ - renesas,raa228004
+ - renesas,raa228006
+ - renesas,raa228228
+ - renesas,raa228244
+ - renesas,raa228246
+ - renesas,raa229001
+ - renesas,raa229004
+ - renesas,raa229621
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@([0-3])$":
+ type: object
+ description:
+ Container for properties specific to a particular channel (rail).
+
+ properties:
+ reg:
+ description: The channel (rail) index.
+ items:
+ minimum: 0
+ maximum: 3
+
+ vout-voltage-divider:
+ description: |
+ Resistances of a voltage divider placed between Vout and the voltage
+ sense (Vsense) pin for the given channel (rail). It has two numbers
+ representing the resistances of the voltage divider provided as
+ <Rout Rtotal> which yields an adjusted Vout as
+ Vout_adj = Vout * Rtotal / Rout given the original Vout as reported
+ by the Vsense pin. Given a circuit configuration similar to the one
+ below, Rtotal = R1 + Rout.
+
+ Vout ----.
+ |
+ .-----.
+ | R1 |
+ '-----'
+ |
+ +---- Vsense
+ |
+ .-----.
+ | Rout|
+ '-----'
+ |
+ GND
+
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 2
+ maxItems: 2
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ isl68239@60 {
+ compatible = "isil,isl68137";
+ reg = <0x60>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ isl68239@60 {
+ compatible = "renesas,isl68239";
+ reg = <0x60>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ vout-voltage-divider = <1000 2000>; // Reported Vout/Pout would be scaled by 2
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/mps,mp2975.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/mps,mp2975.yaml
new file mode 100644
index 000000000000..f7bc4f077929
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/mps,mp2975.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pmbus/mps,mp2975.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MPS MP2975 Synchronous Buck Regulator
+
+maintainers:
+ - Naresh Solanki <naresh.solanki@9elements.com>
+
+description:
+ The MPS MP2971, MP2973 & MP2975 is a multi-phase voltage regulator
+ designed for use in high-performance computing and server
+ applications. It supports I2C/PMBus for control and monitoring.
+
+properties:
+ compatible:
+ enum:
+ - mps,mp2971
+ - mps,mp2973
+ - mps,mp2975
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ regulators:
+ type: object
+ description:
+ List of regulators provided by this controller.
+
+ patternProperties:
+ "^vout[0-1]$":
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ regulator@58 {
+ compatible = "mps,mp2973";
+ reg = <0x58>;
+
+ interrupt-parent = <&smb_pex_cpu1_event>;
+ interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
+
+ regulators {
+ vout0 {
+ regulator-name = "pvccin_cpu1";
+ regulator-enable-ramp-delay = <200>;
+ };
+ vout1 {
+ regulator-name = "pvccfa_ehv_fivra_cpu1";
+ regulator-enable-ramp-delay = <200>;
+ };
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/mps,mpq8785.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/mps,mpq8785.yaml
new file mode 100644
index 000000000000..90970a0433e9
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/mps,mpq8785.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pmbus/mps,mpq8785.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Monolithic Power Systems Multiphase Voltage Regulators with PMBus
+
+maintainers:
+ - Charles Hsu <ythsu0511@gmail.com>
+
+description:
+ Monolithic Power Systems digital multiphase voltage regulators with PMBus.
+
+properties:
+ compatible:
+ enum:
+ - mps,mpm3695
+ - mps,mpm3695-25
+ - mps,mpm82504
+ - mps,mpq8785
+
+ reg:
+ maxItems: 1
+
+ mps,vout-fb-divider-ratio-permille:
+ description:
+ The feedback resistor divider ratio, expressed in permille
+ (Vfb / Vout * 1000). This value is written to the PMBUS_VOUT_SCALE_LOOP
+ register and is required for correct output voltage presentation.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 4095
+ default: 706
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - mps,mpm3695
+ - mps,mpm82504
+ then:
+ properties:
+ mps,vout-fb-divider-ratio-permille:
+ maximum: 1023
+
+ - if:
+ properties:
+ compatible:
+ const: mps,mpq8785
+ then:
+ properties:
+ mps,vout-fb-divider-ratio-permille:
+ maximum: 2047
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pmic@30 {
+ compatible = "mps,mpm82504";
+ reg = <0x30>;
+ mps,vout-fb-divider-ratio-permille = <600>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/ti,lm25066.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/ti,lm25066.yaml
new file mode 100644
index 000000000000..a20f140dc79a
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/ti,lm25066.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/hwmon/pmbus/ti,lm25066.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: National Semiconductor/Texas Instruments LM250x6/LM506x power-management ICs
+
+maintainers:
+ - Zev Weiss <zev@bewilderbeest.net>
+
+description: |
+ The LM25066 family of power-management ICs (a.k.a. hot-swap
+ controllers or eFuses in various contexts) are PMBus devices that
+ offer temperature, current, voltage, and power monitoring.
+
+ Datasheet: https://www.ti.com/lit/ds/symlink/lm25066.pdf
+
+properties:
+ compatible:
+ enum:
+ - ti,lm25056
+ - ti,lm25066
+ - ti,lm5064
+ - ti,lm5066
+ - ti,lm5066i
+
+ reg:
+ maxItems: 1
+
+ shunt-resistor-micro-ohms:
+ description:
+ Shunt (sense) resistor value in micro-Ohms
+ default: 1000
+
+ regulators:
+ type: object
+
+ properties:
+ vout:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/hwmon/hwmon-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pmic@40 {
+ compatible = "ti,lm25066";
+ reg = <0x40>;
+ shunt-resistor-micro-ohms = <675>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/ti,tps25990.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/ti,tps25990.yaml
new file mode 100644
index 000000000000..f4115870e450
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/ti,tps25990.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/hwmon/pmbus/ti,tps25990.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TPS25990 Stackable eFuse
+
+maintainers:
+ - Jerome Brunet <jbrunet@baylibre.com>
+
+description:
+ The TI TPS25990 is an integrated, high-current circuit
+ protection and power management device with PMBUS interface
+
+properties:
+ compatible:
+ const: ti,tps25990
+
+ reg:
+ maxItems: 1
+
+ ti,rimon-micro-ohms:
+ description:
+ micro Ohms value of the resistance installed between the Imon pin
+ and the ground reference.
+
+ interrupts:
+ description: PMBUS SMB Alert Interrupt.
+ maxItems: 1
+
+ regulators:
+ type: object
+ description:
+ list of regulators provided by this controller.
+
+ properties:
+ vout:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+
+ gpdac1:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+
+ gpdac2:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - ti,rimon-micro-ohms
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hw-monitor@46 {
+ compatible = "ti,tps25990";
+ reg = <0x46>;
+
+ interrupt-parent = <&gpio>;
+ interrupts = <42 IRQ_TYPE_LEVEL_LOW>;
+ ti,rimon-micro-ohms = <1370000000>;
+
+ regulators {
+ cpu0_vout: vout {
+ regulator-name = "main_cpu0";
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml
index e8feee38c76c..8f9ce00079df 100644
--- a/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/ti,ucd90320.yaml
@@ -23,11 +23,26 @@ description: |
properties:
compatible:
enum:
+ - ti,ucd9000
+ - ti,ucd9090
+ - ti,ucd90120
+ - ti,ucd90124
+ - ti,ucd90160
- ti,ucd90320
+ - ti,ucd90910
reg:
maxItems: 1
+ gpio-controller: true
+
+ gpio-line-names:
+ minItems: 84
+ maxItems: 84
+
+ '#gpio-cells':
+ const: 1
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/vicor,pli1209bc.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/vicor,pli1209bc.yaml
new file mode 100644
index 000000000000..4aa62d67e1a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pmbus/vicor,pli1209bc.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pmbus/vicor,pli1209bc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Vicor PLI1209BC Power Regulator
+
+maintainers:
+ - Marcello Sylvester Bauer <sylv@sylv.io>
+ - Naresh Solanki <naresh.solanki@9elements.com>
+
+description:
+ The Vicor PLI1209BC is a Digital Supervisor with Isolation for use
+ with BCM Bus Converter Modules.
+
+properties:
+ compatible:
+ enum:
+ - vicor,pli1209bc
+
+ reg:
+ maxItems: 1
+
+ regulators:
+ type: object
+ description:
+ List of regulators provided by this controller.
+
+ properties:
+ vout2:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ regulator@5f {
+ compatible = "vicor,pli1209bc";
+ reg = <0x5f>;
+
+ regulators {
+ p12v_d: vout2 {
+ regulator-name = "bcm3";
+ regulator-boot-on;
+ };
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt
deleted file mode 100644
index 4509e688623a..000000000000
--- a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-Bindings for a fan connected to the PWM lines
-
-Required properties:
-- compatible : "pwm-fan"
-- pwms : the PWM that is used to control the PWM fan
-- cooling-levels : PWM duty cycle values in a range from 0 to 255
- which correspond to thermal cooling states
-
-Optional properties:
-- fan-supply : phandle to the regulator that provides power to the fan
-- interrupts : This contains an interrupt specifier for each fan
- tachometer output connected to an interrupt source.
- The output signal must generate a defined number of
- interrupts per fan revolution, which require that
- it must be self resetting edge interrupts. See
- interrupt-controller/interrupts.txt for the format.
-- pulses-per-revolution : define the number of pulses per fan revolution for
- each tachometer input as an integer (default is 2
- interrupts per revolution). The value must be
- greater than zero.
-
-Example:
- fan0: pwm-fan {
- compatible = "pwm-fan";
- #cooling-cells = <2>;
- pwms = <&pwm 0 10000 0>;
- cooling-levels = <0 102 170 230>;
- };
-
- thermal-zones {
- cpu_thermal: cpu-thermal {
- thermal-sensors = <&tmu 0>;
- polling-delay-passive = <0>;
- polling-delay = <0>;
- trips {
- cpu_alert1: cpu-alert1 {
- temperature = <100000>; /* millicelsius */
- hysteresis = <2000>; /* millicelsius */
- type = "passive";
- };
- };
- cooling-maps {
- map0 {
- trip = <&cpu_alert1>;
- cooling-device = <&fan0 0 1>;
- };
- };
- };
-
-Example 2:
- fan0: pwm-fan {
- compatible = "pwm-fan";
- pwms = <&pwm 0 40000 0>;
- fan-supply = <&reg_fan>;
- interrupt-parent = <&gpio5>;
- interrupts = <1 IRQ_TYPE_EDGE_FALLING>;
- pulses-per-revolution = <2>;
- };
-
-Example 3:
- fan0: pwm-fan {
- compatible = "pwm-fan";
- pwms = <&pwm1 0 25000 0>;
- interrupts-extended = <&gpio1 1 IRQ_TYPE_EDGE_FALLING>,
- <&gpio2 5 IRQ_TYPE_EDGE_FALLING>;
- pulses-per-revolution = <2>, <1>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/pwm-fan.yaml b/Documentation/devicetree/bindings/hwmon/pwm-fan.yaml
new file mode 100644
index 000000000000..a84cc3a4cfdc
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/pwm-fan.yaml
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/pwm-fan.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fan connected to PWM lines
+
+maintainers:
+ - Jean Delvare <jdelvare@suse.com>
+ - Guenter Roeck <linux@roeck-us.net>
+
+properties:
+ compatible:
+ const: pwm-fan
+
+ cooling-levels:
+ description: PWM duty cycle values corresponding to thermal cooling states.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ maximum: 255
+
+ fan-supply:
+ description: Phandle to the regulator that provides power to the fan.
+
+ interrupts:
+ description:
+ This contains an interrupt specifier for each fan tachometer output
+ connected to an interrupt source. The output signal must generate a
+ defined number of interrupts per fan revolution, which require that
+ it must be self resetting edge interrupts.
+ maxItems: 1
+
+ fan-shutdown-percent:
+ description:
+ Fan RPM in percent set during shutdown. This is used to keep the fan
+ running at fixed RPM after the kernel shut down, which is useful on
+ hardware that does keep heating itself even after the kernel did shut
+ down, for example from some sort of management core.
+ minimum: 0
+ maximum: 100
+
+ fan-stop-to-start-percent:
+ description:
+ Minimum fan RPM in percent to start when stopped.
+ minimum: 0
+ maximum: 100
+
+ fan-stop-to-start-us:
+ description:
+ Time to wait in microseconds after start when stopped.
+
+ pulses-per-revolution:
+ description:
+ Define the number of pulses per fan revolution for each tachometer
+ input as an integer.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 4
+ default: 2
+
+ pwms:
+ description: The PWM that is used to control the fan.
+ maxItems: 1
+
+ "#cooling-cells": true
+
+required:
+ - compatible
+ - pwms
+
+additionalProperties: false
+
+examples:
+ - |
+ pwm-fan {
+ compatible = "pwm-fan";
+ cooling-levels = <0 102 170 230>;
+ pwms = <&pwm 0 10000 0>;
+ #cooling-cells = <2>;
+ };
+
+ thermal-zones {
+ cpu_thermal: cpu-thermal {
+ thermal-sensors = <&tmu 0>;
+ polling-delay-passive = <0>;
+ polling-delay = <0>;
+
+ trips {
+ cpu_alert1: cpu-alert1 {
+ temperature = <100000>; /* millicelsius */
+ hysteresis = <2000>; /* millicelsius */
+ type = "passive";
+ };
+ };
+
+ cooling-maps {
+ map0 {
+ trip = <&cpu_alert1>;
+ cooling-device = <&fan0 0 1>;
+ };
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ pwm-fan {
+ compatible = "pwm-fan";
+ pwms = <&pwm 0 40000 0>;
+ fan-supply = <&reg_fan>;
+ interrupt-parent = <&gpio5>;
+ interrupts = <1 IRQ_TYPE_EDGE_FALLING>;
+ pulses-per-revolution = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/renesas,isl28022.yaml b/Documentation/devicetree/bindings/hwmon/renesas,isl28022.yaml
new file mode 100644
index 000000000000..dd82a80e4115
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/renesas,isl28022.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/renesas,isl28022.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas ISL28022 power monitor
+
+maintainers:
+ - Carsten Spieß <mail@carsten-spiess.de>
+
+description: |
+ The ISL28022 is a power monitor with I2C interface. The device monitors
+ voltage, current via shunt resistor and calculated power.
+
+ Datasheets:
+ https://www.renesas.com/us/en/www/doc/datasheet/isl28022.pdf
+
+properties:
+ compatible:
+ const: renesas,isl28022
+
+ reg:
+ maxItems: 1
+
+ shunt-resistor-micro-ohms:
+ description:
+ Shunt resistor value in micro-Ohm
+ minimum: 800
+ default: 10000
+
+ renesas,shunt-range-microvolt:
+ description:
+ Maximal shunt voltage range of +/- 40 mV, 80 mV, 160 mV or 320 mV
+ default: 320000
+ enum: [40000, 80000, 160000, 320000]
+
+ renesas,average-samples:
+ description:
+ Number of samples to be used to report voltage, current and power values.
+ default: 1
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4, 8, 16, 32, 64, 128]
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ power-monitor@40 {
+ compatible = "renesas,isl28022";
+ reg = <0x40>;
+ shunt-resistor-micro-ohms = <8000>;
+ renesas,shunt-range-microvolt = <40000>;
+ renesas,average-samples = <128>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml b/Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml
new file mode 100644
index 000000000000..14ac783c9a5f
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/sensirion,sht15.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/sensirion,sht15.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sensirion SHT15 humidity and temperature sensor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ const: sensirion,sht15
+
+ clk-gpios:
+ maxItems: 1
+
+ data-gpios:
+ maxItems: 1
+
+ vcc-supply:
+ description: regulator that drives the VCC pin
+
+required:
+ - compatible
+ - clk-gpios
+ - data-gpios
+ - vcc-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ sensor {
+ compatible = "sensirion,sht15";
+ clk-gpios = <&gpio4 12 0>;
+ data-gpios = <&gpio4 13 0>;
+ vcc-supply = <&reg_sht15>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_sensor>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml b/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml
index 7d49478d9668..3d14d5fc96c5 100644
--- a/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml
+++ b/Documentation/devicetree/bindings/hwmon/sensirion,shtc1.yaml
@@ -10,10 +10,10 @@ maintainers:
- Christopher Ruehl chris.ruehl@gtsys.com.hk
description: |
- The SHTC1, SHTW1 and SHTC3 are digital humidity and temperature sensor
+ The SHTC1, SHTW1 and SHTC3 are digital humidity and temperature sensors
designed especially for battery-driven high-volume consumer electronics
applications.
- For further information refere to Documentation/hwmon/shtc1.rst
+ For further information refer to Documentation/hwmon/shtc1.rst
This binding document describes the binding for the hardware monitor
portion of the driver.
@@ -31,13 +31,13 @@ properties:
sensirion,blocking-io:
$ref: /schemas/types.yaml#/definitions/flag
description:
- If set, the driver hold the i2c bus until measurement is finished.
+ If set, the driver holds the i2c bus until the measurement is finished.
sensirion,low-precision:
$ref: /schemas/types.yaml#/definitions/flag
description:
- If set, the sensor aquire data with low precision (not recommended).
- The driver aquire data with high precision by default.
+ If set, the sensor acquires data with low precision (not recommended).
+ The driver acquires data with high precision by default.
required:
- compatible
diff --git a/Documentation/devicetree/bindings/hwmon/sht15.txt b/Documentation/devicetree/bindings/hwmon/sht15.txt
deleted file mode 100644
index 6a80277cc426..000000000000
--- a/Documentation/devicetree/bindings/hwmon/sht15.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-Sensirion SHT15 Humidity and Temperature Sensor
-
-Required properties:
-
- - "compatible": must be "sensirion,sht15".
- - "data-gpios": GPIO connected to the data line.
- - "clk-gpios": GPIO connected to the clock line.
- - "vcc-supply": regulator that drives the VCC pin.
-
-Example:
-
- sensor {
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_sensor>;
- compatible = "sensirion,sht15";
- clk-gpios = <&gpio4 12 0>;
- data-gpios = <&gpio4 13 0>;
- vcc-supply = <&reg_sht15>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/sophgo,sg2042-hwmon-mcu.yaml b/Documentation/devicetree/bindings/hwmon/sophgo,sg2042-hwmon-mcu.yaml
new file mode 100644
index 000000000000..b76805d39427
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/sophgo,sg2042-hwmon-mcu.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/sophgo,sg2042-hwmon-mcu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sophgo SG2042 onboard MCU support
+
+maintainers:
+ - Inochi Amaoto <inochiama@outlook.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: sophgo,sg2044-hwmon-mcu
+ - const: sophgo,sg2042-hwmon-mcu
+ - const: sophgo,sg2042-hwmon-mcu
+
+ reg:
+ maxItems: 1
+
+ "#thermal-sensor-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - "#thermal-sensor-cells"
+
+allOf:
+ - $ref: /schemas/thermal/thermal-sensor.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon@17 {
+ compatible = "sophgo,sg2042-hwmon-mcu";
+ reg = <0x17>;
+ #thermal-sensor-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/st,stts751.yaml b/Documentation/devicetree/bindings/hwmon/st,stts751.yaml
new file mode 100644
index 000000000000..9c825adbed58
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/st,stts751.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/st,stts751.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STTS751 Thermometer
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+properties:
+ compatible:
+ const: st,stts751
+
+ reg:
+ maxItems: 1
+
+ smbus-timeout-disable:
+ description:
+ When set, the smbus timeout function will be disabled.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ thermometer@48 {
+ compatible = "st,stts751";
+ reg = <0x48>;
+ smbus-timeout-disable;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/st,tsc1641.yaml b/Documentation/devicetree/bindings/hwmon/st,tsc1641.yaml
new file mode 100644
index 000000000000..aaf244790663
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/st,tsc1641.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/st,tsc1641.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST Microelectronics TSC1641 I2C power monitor
+
+maintainers:
+ - Igor Reznichenko <igor@reznichenko.net>
+
+description: |
+ TSC1641 is a 60 V, 16-bit high-precision power monitor with I2C and
+ MIPI I3C interface
+
+ Datasheets:
+ https://www.st.com/resource/en/datasheet/tsc1641.pdf
+
+properties:
+ compatible:
+ const: st,tsc1641
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description: Optional alert interrupt.
+ maxItems: 1
+
+ shunt-resistor-micro-ohms:
+ description: Shunt resistor value in micro-ohms. Since device has internal
+ 16-bit RSHUNT register with 10 uOhm LSB, the maximum value is capped at
+ 655.35 mOhm.
+ minimum: 100
+ default: 1000
+ maximum: 655350
+
+ st,alert-polarity-active-high:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: Default value is 0 which configures the normal polarity of the
+ ALERT pin, being active low open-drain. Setting this to 1 configures the
+ polarity of the ALERT pin to be inverted and active high open-drain.
+ Specify this property to set the alert polarity to active-high.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ power-sensor@40 {
+ compatible = "st,tsc1641";
+ reg = <0x40>;
+ shunt-resistor-micro-ohms = <1000>;
+ st,alert-polarity-active-high;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml b/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml
new file mode 100644
index 000000000000..733cba780186
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/starfive,jh71x0-temp.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/starfive,jh71x0-temp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: StarFive JH71x0 Temperature Sensor
+
+maintainers:
+ - Emil Renner Berthing <kernel@esmil.dk>
+
+description: |
+ StarFive Technology Co. JH71x0 embedded temperature sensor
+
+properties:
+ compatible:
+ enum:
+ - starfive,jh7100-temp
+ - starfive,jh7110-temp
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 2
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: sense
+ - const: bus
+
+ '#thermal-sensor-cells':
+ const: 0
+
+ resets:
+ minItems: 2
+ maxItems: 2
+
+ reset-names:
+ items:
+ - const: sense
+ - const: bus
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/starfive-jh7100.h>
+ #include <dt-bindings/reset/starfive-jh7100.h>
+
+ temperature-sensor@124a0000 {
+ compatible = "starfive,jh7100-temp";
+ reg = <0x124a0000 0x10000>;
+ clocks = <&clkgen JH7100_CLK_TEMP_SENSE>,
+ <&clkgen JH7100_CLK_TEMP_APB>;
+ clock-names = "sense", "bus";
+ #thermal-sensor-cells = <0>;
+ resets = <&rstgen JH7100_RSTN_TEMP_SENSE>,
+ <&rstgen JH7100_RSTN_TEMP_APB>;
+ reset-names = "sense", "bus";
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/stts751.txt b/Documentation/devicetree/bindings/hwmon/stts751.txt
deleted file mode 100644
index 3ee1dc30e72f..000000000000
--- a/Documentation/devicetree/bindings/hwmon/stts751.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-* STTS751 thermometer.
-
-Required node properties:
-- compatible: "stts751"
-- reg: I2C bus address of the device
-
-Optional properties:
-- smbus-timeout-disable: when set, the smbus timeout function will be disabled
-
-Example stts751 node:
-
-temp-sensor {
- compatible = "stts751";
- reg = <0x48>;
-}
diff --git a/Documentation/devicetree/bindings/hwmon/syna,as370.yaml b/Documentation/devicetree/bindings/hwmon/syna,as370.yaml
new file mode 100644
index 000000000000..1f7005f55247
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/syna,as370.yaml
@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/syna,as370.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synaptics AS370 PVT sensors
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+properties:
+ compatible:
+ const: syna,as370-hwmon
+
+ reg:
+ description:
+ Address and length of the register set.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ sensor@ea0810 {
+ compatible = "syna,as370-hwmon";
+ reg = <0xea0810 0xc>;
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,adc128d818.yaml b/Documentation/devicetree/bindings/hwmon/ti,adc128d818.yaml
new file mode 100644
index 000000000000..78e3d97e2ae5
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,adc128d818.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,adc128d818.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments ADC128D818 ADC System Monitor With Temperature Sensor
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+description: |
+ The ADC128D818 is a 12-Bit, 8-Channel Analog to Digital Converter (ADC)
+ with a temperature sensor and an I2C interface.
+
+ Datasheets:
+ https://www.ti.com/product/ADC128D818
+
+properties:
+ compatible:
+ const: ti,adc128d818
+
+ reg:
+ maxItems: 1
+
+ ti,mode:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: |
+ Operation mode.
+ Mode 0 - 7 single-ended voltage readings (IN0-IN6), 1 temperature
+ reading (internal).
+ Mode 1 - 8 single-ended voltage readings (IN0-IN7), no temperature.
+ Mode 2 - 4 pseudo-differential voltage readings
+ (IN0-IN1, IN3-IN2, IN4-IN5, IN7-IN6), 1 temperature reading (internal).
+ Mode 3 - 4 single-ended voltage readings (IN0-IN3), 2 pseudo-differential
+ voltage readings (IN4-IN5, IN7-IN6), 1 temperature reading (internal).
+ default: 0
+
+ vref-supply:
+ description:
+ The regulator to use as an external reference. If it does not exist, the
+ internal reference will be used.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@1d {
+ compatible = "ti,adc128d818";
+ reg = <0x1d>;
+ vref-supply = <&vref>;
+ ti,mode = /bits/ 8 <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml b/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml
index 926be9a29044..fb80456120e1 100644
--- a/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml
+++ b/Documentation/devicetree/bindings/hwmon/ti,ads7828.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/ti,ads7828.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
diff --git a/Documentation/devicetree/bindings/hwmon/ti,amc6821.yaml b/Documentation/devicetree/bindings/hwmon/ti,amc6821.yaml
new file mode 100644
index 000000000000..eb00756988be
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,amc6821.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,amc6821.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AMC6821 Intelligent Temperature Monitor and PWM Fan Controller
+
+maintainers:
+ - Farouk Bouabid <farouk.bouabid@cherry.de>
+ - Quentin Schulz <quentin.schulz@cherry.de>
+
+description:
+ Intelligent temperature monitor and pulse-width modulation (PWM) fan
+ controller.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: tsd,mule
+ - const: ti,amc6821
+ - const: ti,amc6821
+
+ reg:
+ maxItems: 1
+
+ i2c-mux:
+ type: object
+
+ fan:
+ $ref: fan-common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ cooling-levels:
+ description: PWM duty cycle values corresponding to thermal cooling states.
+ items:
+ maximum: 255
+
+ "#pwm-cells":
+ const: 2
+ description: |
+ Number of cells in a PWM specifier.
+ - cell 0: PWM period in nanoseconds
+ - cell 1: PWM polarity: 0 or PWM_POLARITY_INVERTED
+
+required:
+ - compatible
+ - reg
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: tsd,mule
+
+then:
+ required:
+ - i2c-mux
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fan_controller: fan@18 {
+ compatible = "ti,amc6821";
+ reg = <0x18>;
+ #pwm-cells = <2>;
+
+ fan {
+ pwms = <&fan_controller 40000 0>;
+ };
+ };
+ };
+
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fan@18 {
+ compatible = "tsd,mule", "ti,amc6821";
+ reg = <0x18>;
+
+ i2c-mux {
+ compatible = "tsd,mule-i2c-mux";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c@0 {
+ reg = <0x0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ rtc@6f {
+ compatible = "isil,isl1208";
+ reg = <0x6f>;
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml
index 6f0443322a36..d3cde8936686 100644
--- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml
+++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/ti,ina2xx.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
@@ -20,26 +19,140 @@ description: |
properties:
compatible:
enum:
+ - silergy,sq52206
+ - silergy,sy24655
- ti,ina209
- ti,ina219
- ti,ina220
- ti,ina226
+ - ti,ina228
- ti,ina230
- ti,ina231
+ - ti,ina233
+ - ti,ina237
+ - ti,ina238
+ - ti,ina260
+ - ti,ina700
+ - ti,ina780
reg:
maxItems: 1
+ "#io-channel-cells":
+ const: 1
+
shunt-resistor:
description:
Shunt resistor value in micro-Ohm.
$ref: /schemas/types.yaml#/definitions/uint32
+ ti,shunt-gain:
+ description: |
+ Programmable gain divisor for the shunt voltage accuracy and range. This
+ property only applies to devices that have configurable PGA/ADCRANGE. The
+ gain value is used configure the gain and to convert the shunt voltage,
+ current and power register values when reading measurements from the
+ device.
+
+ For devices that have a configurable PGA (e.g. INA209, INA219, INA220),
+ the gain value maps directly with the PG bits of the config register.
+
+ For devices that have ADCRANGE configuration (e.g. INA238) a shunt-gain
+ value of 1 maps to ADCRANGE=1 where no gain divisor is applied to the
+ shunt voltage, and a value of 4 maps to ADCRANGE=0 such that a wider
+ voltage range is used.
+
+ For SQ52206,the shunt-gain value 1 mapps to ADCRANGE=10/11, the value 2
+ mapps to ADCRANGE=01, and the value 4 mapps to ADCRANGE=00.
+
+ The default value is device dependent, and is defined by the reset value
+ of PGA/ADCRANGE in the respective configuration registers.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4, 8]
+
+ vs-supply:
+ description: phandle to the regulator that provides the VS supply typically
+ in range from 2.7 V to 5.5 V.
+
+ ti,alert-polarity-active-high:
+ description: Alert pin is asserted based on the value of Alert polarity Bit
+ of Mask/Enable register. Default value is Normal (0 which maps to
+ active-low open collector). The other value is Inverted
+ (1 which maps to active-high open collector). Specify this property to set
+ the alert polarity to active-high.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ ti,maximum-expected-current-microamp:
+ description: |
+ This value indicates the maximum current in microamps that you can
+ expect to measure with ina233 in your circuit.
+
+ This value will be used to calculate the Current_LSB and current/power
+ coefficient for the pmbus and to calibrate the IC.
+ minimum: 32768
+ maximum: 4294967295
+ default: 32768000
+
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: hwmon-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - silergy,sq52206
+ - silergy,sy24655
+ - ti,ina209
+ - ti,ina219
+ - ti,ina220
+ - ti,ina226
+ - ti,ina228
+ - ti,ina230
+ - ti,ina231
+ - ti,ina237
+ - ti,ina238
+ - ti,ina260
+ - ti,ina700
+ - ti,ina780
+ then:
+ properties:
+ ti,maximum-expected-current-microamp: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - silergy,sy24655
+ - ti,ina209
+ - ti,ina219
+ - ti,ina220
+ - ti,ina226
+ - ti,ina230
+ - ti,ina231
+ - ti,ina260
+ - ti,ina700
+ - ti,ina780
+ then:
+ properties:
+ ti,shunt-gain: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,ina700
+ - ti,ina780
+ then:
+ properties:
+ shunt-resistor: false
+
+unevaluatedProperties: false
examples:
- |
@@ -50,6 +163,10 @@ examples:
power-sensor@44 {
compatible = "ti,ina220";
reg = <0x44>;
+ #io-channel-cells = <1>;
+ label = "vdd_3v0";
shunt-resistor = <1000>;
+ vs-supply = <&vdd_3v0>;
+ ti,alert-polarity-active-high;
};
};
diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml
new file mode 100644
index 000000000000..5f10f1207d69
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,ina3221.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments INA3221 Current and Voltage Monitor
+
+maintainers:
+ - Jean Delvare <jdelvare@suse.com>
+ - Guenter Roeck <linux@roeck-us.net>
+
+properties:
+ compatible:
+ const: ti,ina3221
+
+ reg:
+ maxItems: 1
+
+ ti,single-shot:
+ description: |
+ This chip has two power modes: single-shot (chip takes one measurement
+ and then shuts itself down) and continuous (chip takes continuous
+ measurements). The continuous mode is more reliable and suitable for
+ hardware monitor type device, but the single-shot mode is more power-
+ friendly and useful for battery-powered device which cares power
+ consumptions while still needs some measurements occasionally.
+
+ If this property is present, the single-shot mode will be used, instead
+ of the default continuous one for monitoring.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ "#address-cells":
+ description: Required only if a child node is present.
+ const: 1
+
+ "#size-cells":
+ description: Required only if a child node is present.
+ const: 0
+
+patternProperties:
+ "^input@[0-2]$":
+ description: The node contains optional child nodes for three channels.
+ Each child node describes the information of input source. Input channels
+ default to enabled in the chip. Unless channels are explicitly disabled
+ in device-tree, input channels will be enabled.
+ type: object
+ additionalProperties: false
+ properties:
+ reg:
+ description: Must be 0, 1 and 2, corresponding to the IN1, IN2 or IN3
+ ports of the INA3221, respectively.
+ enum: [ 0, 1, 2 ]
+
+ label:
+ description: name of the input source
+
+ shunt-resistor-micro-ohms:
+ description: shunt resistor value in micro-Ohm
+
+ ti,summation-disable:
+ description: |
+ The INA3221 has a critical alert pin that can be controlled by the
+ summation control function. This function adds the single
+ shunt-voltage conversions for the desired channels in order to
+ compare the combined sum to the programmed limit. The Shunt-Voltage
+ Sum Limit register contains the programmed value that is compared
+ to the value in the Shunt-Voltage Sum register in order to
+ determine if the total summed limit is exceeded. If the
+ shunt-voltage sum limit value is exceeded, the critical alert pin
+ is asserted.
+
+ For the summation limit to have a meaningful value, it is necessary
+ to use the same shunt-resistor value on all enabled channels. If
+ this is not the case or if a channel should not be used for
+ triggering the critical alert pin, then this property can be used
+ exclude specific channels from the summation control function.
+ type: boolean
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ power-sensor@40 {
+ compatible = "ti,ina3221";
+ reg = <0x40>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ input@0 {
+ reg = <0x0>;
+ /*
+ * Input channels are enabled by default in the device and so
+ * to disable, must be explicitly disabled in device-tree.
+ */
+ status = "disabled";
+ };
+
+ input@1 {
+ reg = <0x1>;
+ shunt-resistor-micro-ohms = <5000>;
+ };
+
+ input@2 {
+ reg = <0x2>;
+ label = "VDD_5V";
+ shunt-resistor-micro-ohms = <5000>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,lm87.yaml b/Documentation/devicetree/bindings/hwmon/ti,lm87.yaml
new file mode 100644
index 000000000000..5c0cdc0091b5
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,lm87.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,lm87.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments LM87 Hardware Monitor
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+description: |
+ The LM87 is a serial interface system hardware monitor
+ with remote diode temperature sensing.
+
+ Datasheets:
+ https://www.ti.com/product/LM87
+
+properties:
+ compatible:
+ enum:
+ - adi,adm1024
+ - ti,lm87
+
+ reg:
+ maxItems: 1
+
+ has-temp3:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ This configures pins 18 and 19 to be used as a second
+ remote temperature sensing channel. By default the pins
+ are configured as voltage input pins in0 and in5.
+
+ has-in6:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ When set, pin 5 is configured to be used as voltage input
+ in6. Otherwise the pin is set as FAN1 input.
+
+ has-in7:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ When set, pin 6 is configured to be used as voltage input
+ in7. Otherwise the pin is set as FAN2 input.
+
+ vcc-supply:
+ description:
+ Regulator supplying power, can be configured to measure
+ 5.0V power supply. Default is 3.3V.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hwmon@2e {
+ compatible = "ti,lm87";
+ reg = <0x2e>;
+ has-temp3;
+ vcc-supply = <&reg_5v0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml
new file mode 100644
index 000000000000..96b2e4969f78
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp102.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,tmp102.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TMP102 temperature sensor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - ti,tmp102
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ label:
+ description:
+ A descriptive name for this channel, like "ambient" or "psu".
+
+ "#thermal-sensor-cells":
+ const: 1
+
+ vcc-supply:
+ description: Power supply for tmp102
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@48 {
+ compatible = "ti,tmp102";
+ reg = <0x48>;
+ interrupt-parent = <&gpio7>;
+ interrupts = <16 IRQ_TYPE_LEVEL_LOW>;
+ label = "somelabel";
+ vcc-supply = <&supply>;
+ #thermal-sensor-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml
new file mode 100644
index 000000000000..a6f9319e068d
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp108.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,tmp108.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TMP108/P3T1085(NXP) temperature sensor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ The TMP108/P3T1085(NXP) is a digital-output temperature sensor with a
+ dynamically-programmable limit window, and under- and overtemperature
+ alert functions.
+
+ P3T1085(NXP) support I3C.
+
+ Datasheets:
+ https://www.ti.com/product/TMP108
+ https://www.nxp.com/docs/en/data-sheet/P3T1085UK.pdf
+
+properties:
+ compatible:
+ enum:
+ - nxp,p3t1085
+ - ti,tmp108
+
+ interrupts:
+ items:
+ - description: alert interrupt
+
+ reg:
+ maxItems: 1
+
+ "#thermal-sensor-cells":
+ const: 0
+
+ vcc-supply:
+ description: phandle to the regulator that provides the V+ supply
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@48 {
+ compatible = "ti,tmp108";
+ reg = <0x48>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <7 IRQ_TYPE_LEVEL_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&tmp_alrt>;
+ vcc-supply = <&supply>;
+ #thermal-sensor-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml
new file mode 100644
index 000000000000..0e8ddf0ad789
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp401.yaml
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,tmp401.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TMP401, TPM411 and TMP43x temperature sensor
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+
+description: |
+ ±1°C Remote and Local temperature sensor
+
+ Datasheets:
+ https://www.ti.com/lit/ds/symlink/tmp401.pdf
+ https://www.ti.com/lit/ds/symlink/tmp411.pdf
+ https://www.ti.com/lit/ds/symlink/tmp431.pdf
+ https://www.ti.com/lit/ds/symlink/tmp435.pdf
+
+properties:
+ compatible:
+ enum:
+ - ti,tmp401
+ - ti,tmp411
+ - ti,tmp431
+ - ti,tmp432
+ - ti,tmp435
+
+ reg:
+ maxItems: 1
+
+ ti,extended-range-enable:
+ description:
+ When set, this sensor measures over extended temperature range.
+ type: boolean
+
+ ti,n-factor:
+ description:
+ value to be used for converting remote channel measurements to
+ temperature.
+ $ref: /schemas/types.yaml#/definitions/int32
+ minimum: -128
+ maximum: 127
+
+ ti,beta-compensation:
+ description:
+ value to select beta correction range.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,tmp401
+ then:
+ properties:
+ ti,n-factor: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - ti,tmp401
+ - ti,tmp411
+ then:
+ properties:
+ ti,beta-compensation: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4c {
+ compatible = "ti,tmp401";
+ reg = <0x4c>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4c {
+ compatible = "ti,tmp431";
+ reg = <0x4c>;
+ ti,extended-range-enable;
+ ti,n-factor = <0x3b>;
+ ti,beta-compensation = <0x7>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp421.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp421.yaml
new file mode 100644
index 000000000000..a6f1fa75a67c
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp421.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,tmp421.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TMP42x/TMP44x temperature sensor
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+
+description: |
+ ±1°C Remote and Local temperature sensor
+ https://www.ti.com/lit/ds/symlink/tmp422.pdf
+
+properties:
+ compatible:
+ enum:
+ - ti,tmp421
+ - ti,tmp422
+ - ti,tmp423
+ - ti,tmp441
+ - ti,tmp442
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+patternProperties:
+ "^channel@([0-3])$":
+ type: object
+ description: |
+ Represents channels of the device and their specific configuration.
+
+ properties:
+ reg:
+ description: |
+ The channel number. 0 is local channel, 1-3 are remote channels
+ items:
+ minimum: 0
+ maximum: 3
+
+ label:
+ description: |
+ A descriptive name for this channel, like "ambient" or "psu".
+
+ ti,n-factor:
+ description: |
+ The value (two's complement) to be programmed in the channel specific N correction register.
+ For remote channels only.
+ $ref: /schemas/types.yaml#/definitions/int32
+ minimum: -128
+ maximum: 127
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4c {
+ compatible = "ti,tmp422";
+ reg = <0x4c>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4c {
+ compatible = "ti,tmp422";
+ reg = <0x4c>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0x0>;
+ ti,n-factor = <0x1>;
+ label = "local";
+ };
+
+ channel@1 {
+ reg = <0x1>;
+ ti,n-factor = <0x0>;
+ label = "somelabel";
+ };
+
+ channel@2 {
+ reg = <0x2>;
+ status = "disabled";
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml
new file mode 100644
index 000000000000..f9c00cbb2806
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp464.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/ti,tmp464.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TMP464 and TMP468 temperature sensors
+
+maintainers:
+ - Guenter Roeck <linux@roeck-us.net>
+
+description: |
+ ±0.0625°C Remote and Local temperature sensor
+ https://www.ti.com/lit/ds/symlink/tmp464.pdf
+ https://www.ti.com/lit/ds/symlink/tmp468.pdf
+
+properties:
+ compatible:
+ enum:
+ - ti,tmp464
+ - ti,tmp468
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+patternProperties:
+ "^channel@([0-8])$":
+ type: object
+ description: |
+ Represents channels of the device and their specific configuration.
+
+ properties:
+ reg:
+ description: |
+ The channel number. 0 is local channel, 1-8 are remote channels.
+ items:
+ minimum: 0
+ maximum: 8
+
+ label:
+ description: |
+ A descriptive name for this channel, like "ambient" or "psu".
+
+ ti,n-factor:
+ description: |
+ The value (two's complement) to be programmed in the channel specific N correction register.
+ For remote channels only.
+ $ref: /schemas/types.yaml#/definitions/int32
+ minimum: -128
+ maximum: 127
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4b {
+ compatible = "ti,tmp464";
+ reg = <0x4b>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@4b {
+ compatible = "ti,tmp464";
+ reg = <0x4b>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0x0>;
+ label = "local";
+ };
+
+ channel@1 {
+ reg = <0x1>;
+ ti,n-factor = <(-10)>;
+ label = "external";
+ };
+
+ channel@2 {
+ reg = <0x2>;
+ ti,n-factor = <0x10>;
+ label = "somelabel";
+ };
+
+ channel@3 {
+ reg = <0x3>;
+ status = "disabled";
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
index 1502b22c77cc..0fe6ea190f60 100644
--- a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
+++ b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/ti,tmp513.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
@@ -21,7 +20,6 @@ description: |
https://www.ti.com/lit/gpn/tmp513
https://www.ti.com/lit/gpn/tmp512
-
properties:
compatible:
enum:
@@ -33,7 +31,7 @@ properties:
shunt-resistor-micro-ohms:
description: |
- If 0, the calibration process will be skiped and the current and power
+ If 0, the calibration process will be skipped and the current and power
measurement engine will not work. Temperature and voltage measurement
will continue to work. The shunt value also need to respect:
rshunt <= pga-gain * 40 * 1000 * 1000.
@@ -72,20 +70,23 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: hwmon-common.yaml#
+
+unevaluatedProperties: false
examples:
- |
i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- tmp513@5c {
- compatible = "ti,tmp513";
- reg = <0x5C>;
- shunt-resistor-micro-ohms = <330000>;
- ti,bus-range-microvolt = <32000000>;
- ti,pga-gain = <8>;
- ti,nfactor = <0x1 0xF3 0x00>;
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ tmp513@5c {
+ compatible = "ti,tmp513";
+ reg = <0x5c>;
+ shunt-resistor-micro-ohms = <330000>;
+ ti,bus-range-microvolt = <32000000>;
+ ti,pga-gain = <8>;
+ ti,nfactor = <0x1 0xf3 0x00>;
+ };
};
diff --git a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml
index 3bc8e73dfbf0..d57e4bf8f65f 100644
--- a/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml
+++ b/Documentation/devicetree/bindings/hwmon/ti,tps23861.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/hwmon/ti,tps23861.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
@@ -16,7 +15,6 @@ description: |
Datasheets:
https://www.ti.com/lit/gpn/tps23861
-
properties:
compatible:
enum:
@@ -26,7 +24,7 @@ properties:
maxItems: 1
shunt-resistor-micro-ohms:
- description: The value of curent sense resistor in microohms.
+ description: The value of current sense resistor in microohms.
default: 255000
minimum: 250000
maximum: 255000
@@ -35,17 +33,20 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: hwmon-common.yaml#
+
+unevaluatedProperties: false
examples:
- |
i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- tps23861@30 {
- compatible = "ti,tps23861";
- reg = <0x30>;
- shunt-resistor-micro-ohms = <255000>;
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ tps23861@30 {
+ compatible = "ti,tps23861";
+ reg = <0x30>;
+ shunt-resistor-micro-ohms = <255000>;
+ };
};
diff --git a/Documentation/devicetree/bindings/hwmon/tmp108.txt b/Documentation/devicetree/bindings/hwmon/tmp108.txt
deleted file mode 100644
index 54d4beed4ee5..000000000000
--- a/Documentation/devicetree/bindings/hwmon/tmp108.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-TMP108 temperature sensor
--------------------------
-
-This device supports I2C only.
-
-Requires node properties:
-- compatible : "ti,tmp108"
-- reg : the I2C address of the device. This is 0x48, 0x49, 0x4a, or 0x4b.
-
-Optional properties:
-- interrupts: Reference to the TMP108 alert interrupt.
-- #thermal-sensor-cells: should be set to 0.
-
-Example:
- tmp108@48 {
- compatible = "ti,tmp108";
- reg = <0x48>;
- };
diff --git a/Documentation/devicetree/bindings/hwmon/vexpress.txt b/Documentation/devicetree/bindings/hwmon/vexpress.txt
index 9c27ed694bbb..4a4df4ffc460 100644
--- a/Documentation/devicetree/bindings/hwmon/vexpress.txt
+++ b/Documentation/devicetree/bindings/hwmon/vexpress.txt
@@ -9,7 +9,7 @@ Requires node properties:
"arm,vexpress-power"
"arm,vexpress-energy"
- "arm,vexpress-sysreg,func" when controlled via vexpress-sysreg
- (see Documentation/devicetree/bindings/arm/vexpress-sysreg.txt
+ (see Documentation/devicetree/bindings/arm/vexpress-config.yaml
for more details)
Optional node properties:
diff --git a/Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml b/Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml
new file mode 100644
index 000000000000..6971ecb314eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/winbond,w83781d.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/hwmon/winbond,w83781d.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Winbond W83781 and compatible hardware monitor IC
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+properties:
+ compatible:
+ enum:
+ - winbond,w83781d
+ - winbond,w83781g
+ - winbond,w83782d
+ - winbond,w83783s
+ - asus,as99127f
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@28 {
+ compatible = "winbond,w83781d";
+ reg = <0x28>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml b/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml
index 6097e8ac46c1..5a799246a373 100644
--- a/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml
+++ b/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i2c/allwinner,sun6i-a31-p2wi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A31 P2WI (Push/Pull 2 Wires Interface) Device Tree Bindings
+title: Allwinner A31 P2WI (Push/Pull 2 Wires Interface)
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -55,7 +55,7 @@ examples:
#size-cells = <0>;
axp221: pmic@68 {
- compatible = "x-powers,axp221";
+ /* compatible = "x-powers,axp221"; */
reg = <0x68>;
};
};
diff --git a/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml b/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml
index 6ecb0270d88d..c4cc8af18280 100644
--- a/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/amlogic,meson6-i2c.yaml
@@ -2,13 +2,13 @@
# Copyright 2019 BayLibre, SAS
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/i2c/amlogic,meson6-i2c.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/i2c/amlogic,meson6-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Amlogic Meson I2C Controller
maintainers:
- - Neil Armstrong <narmstrong@baylibre.com>
+ - Neil Armstrong <neil.armstrong@linaro.org>
- Beniamino Galvani <b.galvani@gmail.com>
allOf:
@@ -30,6 +30,9 @@ properties:
clocks:
minItems: 1
+ power-domains:
+ maxItems: 1
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/i2c/apm,xgene-slimpro-i2c.yaml b/Documentation/devicetree/bindings/i2c/apm,xgene-slimpro-i2c.yaml
new file mode 100644
index 000000000000..9460c64071f2
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/apm,xgene-slimpro-i2c.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/apm,xgene-slimpro-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: APM X-Gene SLIMpro Mailbox I2C
+
+maintainers:
+ - Khuong Dinh <khuong@os.amperecomputing.com>
+
+description:
+ An I2C controller accessed over the "SLIMpro" mailbox.
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: apm,xgene-slimpro-i2c
+
+ mboxes:
+ maxItems: 1
+
+required:
+ - compatible
+ - mboxes
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ compatible = "apm,xgene-slimpro-i2c";
+ mboxes = <&mailbox 0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/apple,i2c.yaml b/Documentation/devicetree/bindings/i2c/apple,i2c.yaml
new file mode 100644
index 000000000000..500a965bdb7a
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/apple,i2c.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/apple,i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple/PASemi I2C controller
+
+maintainers:
+ - Sven Peter <sven@svenpeter.dev>
+
+description: |
+ Apple SoCs such as the M1 come with a I2C controller based on the one found
+ in machines with P. A. Semi's PWRficient processors.
+ The bus is used to communicate with e.g. USB PD chips or the speaker
+ amp.
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: apple,t6020-i2c
+ - const: apple,t8103-i2c
+ - items:
+ - enum:
+ # Do not add additional SoC to this list.
+ - apple,s5l8960x-i2c
+ - apple,t7000-i2c
+ - apple,s8000-i2c
+ - apple,t8010-i2c
+ - apple,t8015-i2c
+ - apple,t8103-i2c
+ - apple,t8112-i2c
+ - apple,t6000-i2c
+ - const: apple,i2c
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: I2C bus reference clock
+
+ interrupts:
+ maxItems: 1
+
+ clock-frequency:
+ description: |
+ Desired I2C bus clock frequency in Hz. If not specified, 100 kHz will be
+ used. This frequency is generated by dividing the reference clock.
+ Allowed values are between ref_clk/(16*4) and ref_clk/(16*255).
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@35010000 {
+ compatible = "apple,t8103-i2c", "apple,i2c";
+ reg = <0x35010000 0x4000>;
+ interrupt-parent = <&aic>;
+ interrupts = <0 627 4>;
+ clocks = <&ref_clk>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/arm,i2c-versatile.yaml b/Documentation/devicetree/bindings/i2c/arm,i2c-versatile.yaml
new file mode 100644
index 000000000000..e58465d1b0c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/arm,i2c-versatile.yaml
@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/arm,i2c-versatile.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: I2C Controller on ARM Ltd development platforms
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: arm,versatile-i2c
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+...
+
diff --git a/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml b/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml
index ea643e6c3ef5..5b9bd2feda3b 100644
--- a/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/aspeed,i2c.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i2c/aspeed,i2c.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: ASPEED I2C on the AST24XX, AST25XX, and AST26XX SoCs Device Tree Bindings
+title: ASPEED I2C on the AST24XX, AST25XX, and AST26XX SoCs
maintainers:
- Rayn Chen <rayn_chen@aspeedtech.com>
@@ -44,11 +44,6 @@ properties:
description: frequency of the bus clock in Hz defaults to 100 kHz when not
specified
- multi-master:
- type: boolean
- description:
- states that there is another master active on this bus
-
required:
- reg
- compatible
@@ -60,10 +55,9 @@ unevaluatedProperties: false
examples:
- |
#include <dt-bindings/clock/aspeed-clock.h>
- i2c0: i2c-bus@40 {
+ i2c@40 {
#address-cells = <1>;
#size-cells = <0>;
- #interrupt-cells = <1>;
compatible = "aspeed,ast2500-i2c-bus";
reg = <0x40 0x40>;
clocks = <&syscon ASPEED_CLK_APB>;
diff --git a/Documentation/devicetree/bindings/i2c/atmel,at91sam-i2c.yaml b/Documentation/devicetree/bindings/i2c/atmel,at91sam-i2c.yaml
new file mode 100644
index 000000000000..e61cdb5b16ef
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/atmel,at91sam-i2c.yaml
@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2022 Microchip Technology, Inc. and its subsidiaries
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/atmel,at91sam-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: I2C for Atmel/Microchip platforms
+
+maintainers:
+ - Alexandre Belloni <alexandre.belloni@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - atmel,at91rm9200-i2c
+ - atmel,at91sam9261-i2c
+ - atmel,at91sam9260-i2c
+ - atmel,at91sam9g20-i2c
+ - atmel,at91sam9g10-i2c
+ - atmel,at91sam9x5-i2c
+ - atmel,sama5d4-i2c
+ - atmel,sama5d2-i2c
+ - microchip,sam9x60-i2c
+ - items:
+ - enum:
+ - microchip,sama7d65-i2c
+ - microchip,sama7g5-i2c
+ - microchip,sam9x7-i2c
+ - const: microchip,sam9x60-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ default: 100000
+
+ dmas:
+ items:
+ - description: TX DMA Channel Specifier
+ - description: RX DMA Channel Specifier
+
+ dma-names:
+ items:
+ - const: tx
+ - const: rx
+
+ atmel,fifo-size:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Maximum number of data the RX and TX FIFOs can store for
+ FIFO capable I2C controllers.
+
+ scl-gpios: true
+
+ sda-gpios: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - atmel,sama5d4-i2c
+ - atmel,sama5d2-i2c
+ - microchip,sam9x60-i2c
+ - microchip,sama7d65-i2c
+ - microchip,sama7g5-i2c
+ then:
+ properties:
+ i2c-sda-hold-time-ns:
+ description:
+ TWD hold time
+ maxItems: 1
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/dma/at91.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c0: i2c@fff84000 {
+ compatible = "atmel,at91sam9g20-i2c";
+ reg = <0xfff84000 0x100>;
+ interrupts = <12 IRQ_TYPE_LEVEL_HIGH 6>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&twi0_clk>;
+ clock-frequency = <400000>;
+
+ eeprom@50 {
+ compatible = "atmel,24c512";
+ reg = <0x50>;
+ pagesize = <128>;
+ };
+ };
+
+ i2c1: i2c@f8034600 {
+ compatible = "atmel,sama5d2-i2c";
+ reg = <0xf8034600 0x100>;
+ interrupts = <19 IRQ_TYPE_LEVEL_HIGH 7>;
+ dmas = <&dma0
+ (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1))
+ AT91_XDMAC_DT_PERID(11)>,
+ <&dma0
+ (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1))
+ AT91_XDMAC_DT_PERID(12)>;
+ dma-names = "tx", "rx";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&flx0>;
+ atmel,fifo-size = <16>;
+ i2c-sda-hold-time-ns = <336>;
+ pinctrl-names = "default", "gpio";
+ pinctrl-0 = <&pinctrl_i2c0>;
+ pinctrl-1 = <&pinctrl_i2c0_gpio>;
+ sda-gpios = <&pioA 30 GPIO_ACTIVE_HIGH>;
+ scl-gpios = <&pioA 31 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
+
+ eeprom@54 {
+ compatible = "atmel,24c02";
+ reg = <0x54>;
+ pagesize = <16>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt
deleted file mode 100644
index a8a35df41951..000000000000
--- a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Broadcom BCM2835 I2C controller
-
-Required properties:
-- compatible : Should be one of:
- "brcm,bcm2711-i2c"
- "brcm,bcm2835-i2c"
-- reg: Should contain register location and length.
-- interrupts: Should contain interrupt.
-- clocks : The clock feeding the I2C controller.
-
-Recommended properties:
-- clock-frequency : desired I2C bus clock frequency in Hz.
-
-Example:
-
-i2c@7e205000 {
- compatible = "brcm,bcm2835-i2c";
- reg = <0x7e205000 0x1000>;
- interrupts = <2 21>;
- clocks = <&clk_i2c>;
- clock-frequency = <100000>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml
new file mode 100644
index 000000000000..8256490a7af2
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/brcm,bcm2835-i2c.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/brcm,bcm2835-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM2835 I2C controller
+
+maintainers:
+ - Stephen Warren <swarren@wwwdotorg.org>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - brcm,bcm2835-i2c
+ - items:
+ - const: brcm,bcm2711-i2c
+ - const: brcm,bcm2835-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clock-names:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@7e205000 {
+ compatible = "brcm,bcm2835-i2c";
+ reg = <0x7e205000 0x1000>;
+ interrupts = <2 21>;
+ clocks = <&clk_i2c>;
+ clock-frequency = <100000>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/brcm,brcmstb-i2c.yaml b/Documentation/devicetree/bindings/i2c/brcm,brcmstb-i2c.yaml
index 7070c04469ed..ac9ddf228c82 100644
--- a/Documentation/devicetree/bindings/i2c/brcm,brcmstb-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/brcm,brcmstb-i2c.yaml
@@ -76,21 +76,21 @@ else:
examples:
- |
- bsca: i2c@f0406200 {
- clock-frequency = <390000>;
- compatible = "brcm,brcmstb-i2c";
- interrupt-parent = <&irq0_intc>;
- reg = <0xf0406200 0x58>;
- interrupts = <0x18>;
- interrupt-names = "upg_bsca";
- };
+ bsca: i2c@f0406200 {
+ compatible = "brcm,brcmstb-i2c";
+ reg = <0xf0406200 0x58>;
+ clock-frequency = <390000>;
+ interrupt-parent = <&irq0_intc>;
+ interrupts = <0x18>;
+ interrupt-names = "upg_bsca";
+ };
- |
- ddc0: i2c@7ef04500 {
- compatible = "brcm,bcm2711-hdmi-i2c";
- reg = <0x7ef04500 0x100>, <0x7ef00b00 0x300>;
- reg-names = "bsc", "auto-i2c";
- clock-frequency = <390000>;
- };
+ ddc0: i2c@7ef04500 {
+ compatible = "brcm,bcm2711-hdmi-i2c";
+ reg = <0x7ef04500 0x100>, <0x7ef00b00 0x300>;
+ reg-names = "bsc", "auto-i2c";
+ clock-frequency = <390000>;
+ };
...
diff --git a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt
deleted file mode 100644
index d12cc33cca6c..000000000000
--- a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-Broadcom iProc I2C controller
-
-Required properties:
-
-- compatible:
- Must be "brcm,iproc-i2c" or "brcm,iproc-nic-i2c"
-
-- reg:
- Define the base and range of the I/O address space that contain the iProc
- I2C controller registers
-
-- clock-frequency:
- This is the I2C bus clock. Need to be either 100000 or 400000
-
-- #address-cells:
- Always 1 (for I2C addresses)
-
-- #size-cells:
- Always 0
-
-Optional properties:
-
-- interrupts:
- Should contain the I2C interrupt. For certain revisions of the I2C
- controller, I2C interrupt is unwired to the interrupt controller. In such
- case, this property should be left unspecified, and driver will fall back
- to polling mode
-
-- brcm,ape-hsls-addr-mask:
- Required for "brcm,iproc-nic-i2c". Host view of address mask into the
- 'APE' co-processor. Value must be unsigned, 32-bit
-
-Example:
- i2c0: i2c@18008000 {
- compatible = "brcm,iproc-i2c";
- reg = <0x18008000 0x100>;
- #address-cells = <1>;
- #size-cells = <0>;
- interrupts = <GIC_SPI 85 IRQ_TYPE_NONE>;
- clock-frequency = <100000>;
-
- codec: wm8750@1a {
- compatible = "wlf,wm8750";
- reg = <0x1a>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml
new file mode 100644
index 000000000000..2aa75b7add7b
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/brcm,iproc-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom iProc I2C controller
+
+maintainers:
+ - Rafał Miłecki <rafal@milecki.pl>
+
+properties:
+ compatible:
+ enum:
+ - brcm,iproc-i2c
+ - brcm,iproc-nic-i2c
+
+ reg:
+ maxItems: 1
+
+ clock-frequency:
+ enum: [ 100000, 400000 ]
+
+ interrupts:
+ description: |
+ Should contain the I2C interrupt. For certain revisions of the I2C
+ controller, I2C interrupt is unwired to the interrupt controller. In such
+ case, this property should be left unspecified, and driver will fall back
+ to polling mode
+ maxItems: 1
+
+ brcm,ape-hsls-addr-mask:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Host view of address mask into the 'APE' co-processor
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,iproc-nic-i2c
+ then:
+ required:
+ - brcm,ape-hsls-addr-mask
+
+unevaluatedProperties: false
+
+required:
+ - reg
+ - clock-frequency
+ - '#address-cells'
+ - '#size-cells'
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c@18008000 {
+ compatible = "brcm,iproc-i2c";
+ reg = <0x18008000 0x100>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ interrupts = <GIC_SPI 85 IRQ_TYPE_NONE>;
+ clock-frequency = <100000>;
+
+ wm8750@1a {
+ compatible = "wlf,wm8750";
+ reg = <0x1a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/brcm,kona-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,kona-i2c.txt
deleted file mode 100644
index 1b87b741fa8e..000000000000
--- a/Documentation/devicetree/bindings/i2c/brcm,kona-i2c.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-Broadcom Kona Family I2C
-=========================
-
-This I2C controller is used in the following Broadcom SoCs:
-
- BCM11130
- BCM11140
- BCM11351
- BCM28145
- BCM28155
-
-Required Properties
--------------------
-- compatible: "brcm,bcm11351-i2c", "brcm,kona-i2c"
-- reg: Physical base address and length of controller registers
-- interrupts: The interrupt number used by the controller
-- clocks: clock specifier for the kona i2c external clock
-- clock-frequency: The I2C bus frequency in Hz
-- #address-cells: Should be <1>
-- #size-cells: Should be <0>
-
-Refer to clocks/clock-bindings.txt for generic clock consumer
-properties.
-
-Example:
-
-i2c@3e016000 {
- compatible = "brcm,bcm11351-i2c","brcm,kona-i2c";
- reg = <0x3e016000 0x80>;
- interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&bsc1_clk>;
- clock-frequency = <400000>;
- #address-cells = <1>;
- #size-cells = <0>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/brcm,kona-i2c.yaml b/Documentation/devicetree/bindings/i2c/brcm,kona-i2c.yaml
new file mode 100644
index 000000000000..7a694af90fc6
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/brcm,kona-i2c.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/brcm,kona-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom Kona family I2C controller
+
+maintainers:
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm11351-i2c
+ - brcm,bcm21664-i2c
+ - brcm,bcm23550-i2c
+ - const: brcm,kona-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ enum: [ 100000, 400000, 1000000, 3400000 ]
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-frequency
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c@3e016000 {
+ compatible = "brcm,bcm11351-i2c", "brcm,kona-i2c";
+ reg = <0x3e016000 0x80>;
+ interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&bsc1_clk>;
+ clock-frequency = <400000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml b/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml
index 1ca1cd19bd1d..9f1d35ce1fe8 100644
--- a/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml
+++ b/Documentation/devicetree/bindings/i2c/cdns,i2c-r1p10.yaml
@@ -1,13 +1,13 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/i2c/cdns,i2c-r1p10.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/i2c/cdns,i2c-r1p10.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Cadence I2C controller Device Tree Bindings
+title: Cadence I2C controller
maintainers:
- - Michal Simek <michal.simek@xilinx.com>
+ - Michal Simek <michal.simek@amd.com>
allOf:
- $ref: /schemas/i2c/i2c-controller.yaml#
@@ -24,6 +24,9 @@ properties:
clocks:
minItems: 1
+ resets:
+ maxItems: 1
+
interrupts:
maxItems: 1
@@ -38,6 +41,16 @@ properties:
description: |
Input clock name.
+ fifo-depth:
+ description:
+ Size of the data FIFO in bytes.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 16
+ enum: [2, 4, 8, 16, 32, 64, 128, 256]
+
+ power-domains:
+ maxItems: 1
+
required:
- compatible
- reg
@@ -52,9 +65,11 @@ examples:
i2c@e0004000 {
compatible = "cdns,i2c-r1p10";
clocks = <&clkc 38>;
+ resets = <&rstc 288>;
interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>;
reg = <0xe0004000 0x1000>;
clock-frequency = <400000>;
#address-cells = <1>;
#size-cells = <0>;
+ fifo-depth = <8>;
};
diff --git a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml
index b386e4128a79..580003cdfff5 100644
--- a/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml
+++ b/Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml
@@ -10,7 +10,6 @@ title: I2C bus that tunnels through the ChromeOS EC (cros-ec)
maintainers:
- Doug Anderson <dianders@chromium.org>
- Benson Leung <bleung@chromium.org>
- - Enric Balletbo i Serra <enric.balletbo@collabora.com>
description: |
On some ChromeOS board designs we've got a connection to the EC
@@ -22,7 +21,7 @@ description: |
google,cros-ec-spi or google,cros-ec-i2c.
allOf:
- - $ref: i2c-controller.yaml#
+ - $ref: /schemas/i2c/i2c-controller.yaml#
properties:
compatible:
@@ -40,7 +39,7 @@ unevaluatedProperties: false
examples:
- |
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -48,6 +47,7 @@ examples:
compatible = "google,cros-ec-spi";
reg = <0>;
spi-max-frequency = <5000000>;
+ interrupts = <99 0>;
i2c-tunnel {
compatible = "google,cros-ec-i2c-tunnel";
diff --git a/Documentation/devicetree/bindings/i2c/hisilicon,ascend910-i2c.yaml b/Documentation/devicetree/bindings/i2c/hisilicon,ascend910-i2c.yaml
new file mode 100644
index 000000000000..7d7a8de7bcd8
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/hisilicon,ascend910-i2c.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/hisilicon,ascend910-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HiSilicon common I2C controller
+
+maintainers:
+ - Yicong Yang <yangyicong@hisilicon.com>
+
+description:
+ The HiSilicon common I2C controller can be used for many different
+ types of SoC such as Huawei Ascend AI series chips.
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: hisilicon,ascend910-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ default: 400000
+
+ i2c-sda-falling-time-ns:
+ default: 343
+
+ i2c-scl-falling-time-ns:
+ default: 203
+
+ i2c-sda-hold-time-ns:
+ default: 830
+
+ i2c-scl-rising-time-ns:
+ default: 365
+
+ i2c-digital-filter-width-ns:
+ default: 0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c@38b0000 {
+ compatible = "hisilicon,ascend910-i2c";
+ reg = <0x38b0000 0x10000>;
+ interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>;
+ i2c-sda-falling-time-ns = <56>;
+ i2c-scl-falling-time-ns = <56>;
+ i2c-sda-hold-time-ns = <56>;
+ i2c-scl-rising-time-ns = <56>;
+ i2c-digital-filter;
+ i2c-digital-filter-width-ns = <0x0>;
+ clocks = <&alg_clk>;
+ clock-frequency = <400000>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/hisilicon,hix5hd2-i2c.yaml b/Documentation/devicetree/bindings/i2c/hisilicon,hix5hd2-i2c.yaml
new file mode 100644
index 000000000000..3faa7954e411
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/hisilicon,hix5hd2-i2c.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/hisilicon,hix5hd2-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+title: I2C for HiSilicon hix5hd2 chipset platform
+
+maintainers:
+ - Wei Yan <sledge.yanwei@huawei.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - hisilicon,hix5hd2-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ description: Desired I2C bus frequency in Hz
+ default: 100000
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/hix5hd2-clock.h>
+
+ i2c@f8b10000 {
+ compatible = "hisilicon,hix5hd2-i2c";
+ reg = <0xf8b10000 0x1000>;
+ interrupts = <0 38 4>;
+ clocks = <&clock HIX5HD2_I2C0_RST>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/hpe,gxp-i2c.yaml b/Documentation/devicetree/bindings/i2c/hpe,gxp-i2c.yaml
new file mode 100644
index 000000000000..6604dcd47251
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/hpe,gxp-i2c.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/hpe,gxp-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HPE GXP SoC I2C Controller
+
+maintainers:
+ - Nick Hawkins <nick.hawkins@hpe.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: hpe,gxp-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clock-frequency:
+ default: 100000
+
+ hpe,sysreg:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle to the global status and enable interrupt registers shared
+ between each I2C engine controller instance. It enables the I2C
+ engine controller to act as both a master or slave by being able to
+ arm and respond to interrupts from its engine. Each bit in the
+ registers represent the respective bit position.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@2600 {
+ compatible = "hpe,gxp-i2c";
+ reg = <0x2500 0x70>;
+ interrupts = <9>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ hpe,sysreg = <&sysreg_system_controller>;
+ clock-frequency = <10000>;
+
+ eeprom@50 {
+ compatible = "atmel,24c128";
+ reg = <0x50>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt
deleted file mode 100644
index 548a73cde796..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt
+++ /dev/null
@@ -1,82 +0,0 @@
-GPIO-based I2C Arbitration Using a Challenge & Response Mechanism
-=================================================================
-This uses GPIO lines and a challenge & response mechanism to arbitrate who is
-the master of an I2C bus in a multimaster situation.
-
-In many cases using GPIOs to arbitrate is not needed and a design can use
-the standard I2C multi-master rules. Using GPIOs is generally useful in
-the case where there is a device on the bus that has errata and/or bugs
-that makes standard multimaster mode not feasible.
-
-Note that this scheme works well enough but has some downsides:
-* It is nonstandard (not using standard I2C multimaster)
-* Having two masters on a bus in general makes it relatively hard to debug
- problems (hard to tell if i2c issues were caused by one master, another, or
- some device on the bus).
-
-
-Algorithm:
-
-All masters on the bus have a 'bus claim' line which is an output that the
-others can see. These are all active low with pull-ups enabled. We'll
-describe these lines as:
-
-- OUR_CLAIM: output from us signaling to other hosts that we want the bus
-- THEIR_CLAIMS: output from others signaling that they want the bus
-
-The basic algorithm is to assert your line when you want the bus, then make
-sure that the other side doesn't want it also. A detailed explanation is best
-done with an example.
-
-Let's say we want to claim the bus. We:
-1. Assert OUR_CLAIM.
-2. Waits a little bit for the other sides to notice (slew time, say 10
- microseconds).
-3. Check THEIR_CLAIMS. If none are asserted then the we have the bus and we are
- done.
-4. Otherwise, wait for a few milliseconds and see if THEIR_CLAIMS are released.
-5. If not, back off, release the claim and wait for a few more milliseconds.
-6. Go back to 1 (until retry time has expired).
-
-
-Required properties:
-- compatible: i2c-arb-gpio-challenge
-- our-claim-gpio: The GPIO that we use to claim the bus.
-- their-claim-gpios: The GPIOs that the other sides use to claim the bus.
- Note that some implementations may only support a single other master.
-- I2C arbitration bus node. See i2c-arb.txt in this directory.
-
-Optional properties:
-- slew-delay-us: microseconds to wait for a GPIO to go high. Default is 10 us.
-- wait-retry-us: we'll attempt another claim after this many microseconds.
- Default is 3000 us.
-- wait-free-us: we'll give up after this many microseconds. Default is 50000 us.
-
-
-Example:
- i2c@12ca0000 {
- compatible = "acme,some-i2c-device";
- #address-cells = <1>;
- #size-cells = <0>;
- };
-
- i2c-arbitrator {
- compatible = "i2c-arb-gpio-challenge";
-
- i2c-parent = <&{/i2c@12CA0000}>;
-
- our-claim-gpio = <&gpf0 3 1>;
- their-claim-gpios = <&gpe0 4 1>;
- slew-delay-us = <10>;
- wait-retry-us = <3000>;
- wait-free-us = <50000>;
-
- i2c-arb {
- #address-cells = <1>;
- #size-cells = <0>;
-
- i2c@52 {
- // Normal I2C device
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml
new file mode 100644
index 000000000000..b618b5a3433a
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-arb-gpio-challenge.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO-based I2C Arbitration Using a Challenge & Response Mechanism
+
+maintainers:
+ - Doug Anderson <dianders@chromium.org>
+ - Peter Rosin <peda@axentia.se>
+
+description: |
+ This uses GPIO lines and a challenge & response mechanism to arbitrate who is
+ the master of an I2C bus in a multimaster situation.
+
+ In many cases using GPIOs to arbitrate is not needed and a design can use the
+ standard I2C multi-master rules. Using GPIOs is generally useful in the case
+ where there is a device on the bus that has errata and/or bugs that makes
+ standard multimaster mode not feasible.
+
+ Note that this scheme works well enough but has some downsides:
+ * It is nonstandard (not using standard I2C multimaster)
+ * Having two masters on a bus in general makes it relatively hard to debug
+ problems (hard to tell if i2c issues were caused by one master, another,
+ or some device on the bus).
+
+ Algorithm:
+ All masters on the bus have a 'bus claim' line which is an output that the
+ others can see. These are all active low with pull-ups enabled. We'll
+ describe these lines as:
+ * OUR_CLAIM: output from us signaling to other hosts that we want the bus
+ * THEIR_CLAIMS: output from others signaling that they want the bus
+
+ The basic algorithm is to assert your line when you want the bus, then make
+ sure that the other side doesn't want it also. A detailed explanation is
+ best done with an example.
+
+ Let's say we want to claim the bus. We:
+ 1. Assert OUR_CLAIM.
+ 2. Waits a little bit for the other sides to notice (slew time, say 10
+ microseconds).
+ 3. Check THEIR_CLAIMS. If none are asserted then the we have the bus and we
+ are done.
+ 4. Otherwise, wait for a few milliseconds and see if THEIR_CLAIMS are released.
+ 5. If not, back off, release the claim and wait for a few more milliseconds.
+ 6. Go back to 1 (until retry time has expired).
+
+properties:
+ compatible:
+ const: i2c-arb-gpio-challenge
+
+ i2c-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ The I2C bus that this multiplexer's master-side port is connected to.
+
+ our-claim-gpios:
+ maxItems: 1
+ description:
+ The GPIO that we use to claim the bus.
+
+ slew-delay-us:
+ default: 10
+ description:
+ Time to wait for a GPIO to go high.
+
+ their-claim-gpios:
+ minItems: 1
+ maxItems: 8
+ description:
+ The GPIOs that the other sides use to claim the bus. Note that some
+ implementations may only support a single other master.
+
+ wait-free-us:
+ default: 50000
+ description:
+ We'll give up after this many microseconds.
+
+ wait-retry-us:
+ default: 3000
+ description:
+ We'll attempt another claim after this many microseconds.
+
+ i2c-arb:
+ type: object
+ $ref: /schemas/i2c/i2c-controller.yaml
+ unevaluatedProperties: false
+ description:
+ I2C arbitration bus node.
+
+required:
+ - compatible
+ - i2c-arb
+ - our-claim-gpios
+ - their-claim-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c-arbitrator {
+ compatible = "i2c-arb-gpio-challenge";
+ i2c-parent = <&i2c_4>;
+
+ our-claim-gpios = <&gpf0 3 GPIO_ACTIVE_LOW>;
+ their-claim-gpios = <&gpe0 4 GPIO_ACTIVE_LOW>;
+ slew-delay-us = <10>;
+ wait-retry-us = <3000>;
+ wait-free-us = <50000>;
+
+ i2c-arb {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sbs-battery@b {
+ compatible = "sbs,sbs-battery";
+ reg = <0xb>;
+ sbs,poll-retry-count = <1>;
+ };
+
+ embedded-controller@1e {
+ compatible = "google,cros-ec-i2c";
+ reg = <0x1e>;
+ interrupts = <6 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-parent = <&gpx1>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&ec_irq>;
+ wakeup-source;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb.txt b/Documentation/devicetree/bindings/i2c/i2c-arb.txt
deleted file mode 100644
index 59abf9277bdc..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-arb.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-Common i2c arbitration bus properties.
-
-- i2c-arb child node
-
-Required properties for the i2c-arb child node:
-- #address-cells = <1>;
-- #size-cells = <0>;
-
-Optional properties for i2c-arb child node:
-- Child nodes conforming to i2c bus binding
-
-
-Example :
-
- /*
- An NXP pca9541 I2C bus master selector at address 0x74
- with a NXP pca8574 GPIO expander attached.
- */
-
- arb@74 {
- compatible = "nxp,pca9541";
- reg = <0x74>;
-
- i2c-arb {
- #address-cells = <1>;
- #size-cells = <0>;
-
- gpio@38 {
- compatible = "nxp,pca8574";
- reg = <0x38>;
- #gpio-cells = <2>;
- gpio-controller;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-at91.txt b/Documentation/devicetree/bindings/i2c/i2c-at91.txt
deleted file mode 100644
index 2015f50aed0f..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-at91.txt
+++ /dev/null
@@ -1,82 +0,0 @@
-I2C for Atmel platforms
-
-Required properties :
-- compatible : Must be one of:
- "atmel,at91rm9200-i2c",
- "atmel,at91sam9261-i2c",
- "atmel,at91sam9260-i2c",
- "atmel,at91sam9g20-i2c",
- "atmel,at91sam9g10-i2c",
- "atmel,at91sam9x5-i2c",
- "atmel,sama5d4-i2c",
- "atmel,sama5d2-i2c",
- "microchip,sam9x60-i2c".
-- reg: physical base address of the controller and length of memory mapped
- region.
-- interrupts: interrupt number to the cpu.
-- #address-cells = <1>;
-- #size-cells = <0>;
-- clocks: phandles to input clocks.
-
-Optional properties:
-- clock-frequency: Desired I2C bus frequency in Hz, otherwise defaults to 100000
-- dmas: A list of two dma specifiers, one for each entry in dma-names.
-- dma-names: should contain "tx" and "rx".
-- atmel,fifo-size: maximum number of data the RX and TX FIFOs can store for FIFO
- capable I2C controllers.
-- i2c-sda-hold-time-ns: TWD hold time, only available for:
- "atmel,sama5d4-i2c",
- "atmel,sama5d2-i2c",
- "microchip,sam9x60-i2c".
-- scl-gpios: specify the gpio related to SCL pin
-- sda-gpios: specify the gpio related to SDA pin
-- pinctrl: add extra pinctrl to configure i2c pins to gpio function for i2c
- bus recovery, call it "gpio" state
-- Child nodes conforming to i2c bus binding
-
-
-Examples :
-
-i2c0: i2c@fff84000 {
- compatible = "atmel,at91sam9g20-i2c";
- reg = <0xfff84000 0x100>;
- interrupts = <12 4 6>;
- #address-cells = <1>;
- #size-cells = <0>;
- clocks = <&twi0_clk>;
- clock-frequency = <400000>;
-
- 24c512@50 {
- compatible = "atmel,24c512";
- reg = <0x50>;
- pagesize = <128>;
- }
-}
-
-i2c0: i2c@f8034600 {
- compatible = "atmel,sama5d2-i2c";
- reg = <0xf8034600 0x100>;
- interrupts = <19 IRQ_TYPE_LEVEL_HIGH 7>;
- dmas = <&dma0
- (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1))
- AT91_XDMAC_DT_PERID(11)>,
- <&dma0
- (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1))
- AT91_XDMAC_DT_PERID(12)>;
- dma-names = "tx", "rx";
- #address-cells = <1>;
- #size-cells = <0>;
- clocks = <&flx0>;
- atmel,fifo-size = <16>;
- i2c-sda-hold-time-ns = <336>;
- pinctrl-names = "default", "gpio";
- pinctrl-0 = <&pinctrl_i2c0>;
- pinctrl-1 = <&pinctrl_i2c0_gpio>;
- sda-gpios = <&pioA 30 GPIO_ACTIVE_HIGH>;
- scl-gpios = <&pioA 31 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
-
- wm8731: wm8731@1a {
- compatible = "wm8731";
- reg = <0x1a>;
- };
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-atr.yaml b/Documentation/devicetree/bindings/i2c/i2c-atr.yaml
new file mode 100644
index 000000000000..1939ab339bfc
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-atr.yaml
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-atr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common i2c address translator properties
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+
+description:
+ An I2C Address Translator (ATR) is a device with an I2C slave parent
+ ("upstream") port and N I2C master child ("downstream") ports, and
+ forwards transactions from upstream to the appropriate downstream port
+ with a modified slave address. The address used on the parent bus is
+ called the "alias" and is (potentially) different from the physical
+ slave address of the child bus. Address translation is done by the
+ hardware.
+
+properties:
+ i2c-alias-pool:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description:
+ I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
+ used to access the remote peripherals on the serializer's I2C bus. The
+ addresses must be available, not used by any other peripheral. Each
+ remote peripheral is assigned an alias from the pool, and transactions to
+ that address will be forwarded to the remote peripheral, with the address
+ translated to the remote peripheral's real address. This property is not
+ needed if there are no I2C addressable remote peripherals.
+
+additionalProperties: true
+...
diff --git a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt
deleted file mode 100644
index 86b2e433a969..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt
+++ /dev/null
@@ -1,135 +0,0 @@
-Pinctrl-based I2C Bus DeMux
-
-This binding describes an I2C bus demultiplexer that uses pin multiplexing to
-route the I2C signals, and represents the pin multiplexing configuration using
-the pinctrl device tree bindings. This may be used to select one I2C IP core at
-runtime which may have a better feature set for a given task than another I2C
-IP core on the SoC. The most simple example is to fall back to GPIO bitbanging
-if your current runtime configuration hits an errata of the internal IP core.
-
- +-------------------------------+
- | SoC |
- | | +-----+ +-----+
- | +------------+ | | dev | | dev |
- | |I2C IP Core1|--\ | +-----+ +-----+
- | +------------+ \-------+ | | |
- | |Pinctrl|--|------+--------+
- | +------------+ +-------+ |
- | |I2C IP Core2|--/ |
- | +------------+ |
- | |
- +-------------------------------+
-
-Required properties:
-- compatible: "i2c-demux-pinctrl"
-- i2c-parent: List of phandles of I2C masters available for selection. The first
- one will be used as default.
-- i2c-bus-name: The name of this bus. Also needed as pinctrl-name for the I2C
- parents.
-
-Furthermore, I2C mux properties and child nodes. See i2c-mux.yaml in this
-directory.
-
-Example:
-
-Here is a snipplet for a bus to be demuxed. It contains various i2c clients for
-HDMI, so the bus is named "i2c-hdmi":
-
- i2chdmi: i2c@8 {
-
- compatible = "i2c-demux-pinctrl";
- i2c-parent = <&gpioi2c>, <&iic2>, <&i2c2>;
- i2c-bus-name = "i2c-hdmi";
- #address-cells = <1>;
- #size-cells = <0>;
-
- ak4643: sound-codec@12 {
- compatible = "asahi-kasei,ak4643";
-
- #sound-dai-cells = <0>;
- reg = <0x12>;
- };
-
- composite-in@20 {
- compatible = "adi,adv7180";
- reg = <0x20>;
- remote = <&vin1>;
-
- port {
- adv7180: endpoint {
- bus-width = <8>;
- remote-endpoint = <&vin1ep0>;
- };
- };
- };
-
- hdmi@39 {
- compatible = "adi,adv7511w";
- reg = <0x39>;
- interrupt-parent = <&gpio1>;
- interrupts = <15 IRQ_TYPE_LEVEL_LOW>;
-
- adi,input-depth = <8>;
- adi,input-colorspace = "rgb";
- adi,input-clock = "1x";
- adi,input-style = <1>;
- adi,input-justification = "evenly";
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
- adv7511_in: endpoint {
- remote-endpoint = <&du_out_lvds0>;
- };
- };
-
- port@1 {
- reg = <1>;
- adv7511_out: endpoint {
- remote-endpoint = <&hdmi_con>;
- };
- };
- };
- };
- };
-
-And for clarification, here are the snipplets for the i2c-parents:
-
- gpioi2c: i2c@9 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "i2c-gpio";
- gpios = <&gpio5 6 GPIO_ACTIVE_HIGH /* sda */
- &gpio5 5 GPIO_ACTIVE_HIGH /* scl */
- >;
- i2c-gpio,delay-us = <5>;
- };
-
-...
-
-&i2c2 {
- pinctrl-0 = <&i2c2_pins>;
- pinctrl-names = "i2c-hdmi";
-
- clock-frequency = <100000>;
-};
-
-...
-
-&iic2 {
- pinctrl-0 = <&iic2_pins>;
- pinctrl-names = "i2c-hdmi";
-
- clock-frequency = <100000>;
-};
-
-Please note:
-
-- pinctrl properties for the parent I2C controllers need a pinctrl state
- with the same name as i2c-bus-name, not "default"!
-
-- the i2c masters must have their status "disabled". This driver will
- enable them at runtime when needed.
diff --git a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml
new file mode 100644
index 000000000000..1eaf00b90a77
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-demux-pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Pinctrl-based I2C Bus Demultiplexer
+
+maintainers:
+ - Wolfram Sang <wsa+renesas@sang-engineering.com>
+
+description: |
+ This binding describes an I2C bus demultiplexer that uses pin multiplexing to
+ route the I2C signals, and represents the pin multiplexing configuration
+ using the pinctrl device tree bindings. This may be used to select one I2C
+ IP core at runtime which may have a better feature set for a given task than
+ another I2C IP core on the SoC. The most simple example is to fall back to
+ GPIO bitbanging if your current runtime configuration hits an errata of the
+ internal IP core.
+
+ +-------------------------------+
+ | SoC |
+ | | +-----+ +-----+
+ | +------------+ | | dev | | dev |
+ | |I2C IP Core1|--\ | +-----+ +-----+
+ | +------------+ \-------+ | | |
+ | |Pinctrl|--|------+--------+
+ | +------------+ +-------+ |
+ | |I2C IP Core2|--/ |
+ | +------------+ |
+ | |
+ +-------------------------------+
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: i2c-demux-pinctrl
+
+ i2c-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ maxItems: 1
+ description:
+ List of phandles of I2C masters available for selection. The first one
+ will be used as default.
+
+ i2c-bus-name:
+ $ref: /schemas/types.yaml#/definitions/string
+ description:
+ The name of this bus. Also needed as pinctrl-name for the I2C parents.
+
+required:
+ - compatible
+ - i2c-parent
+ - i2c-bus-name
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpioi2c2: i2c-9 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "i2c-gpio";
+ scl-gpios = <&gpio5 5 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
+ sda-gpios = <&gpio5 6 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
+ i2c-gpio,delay-us = <5>;
+
+ // The I2C controller must have its status "disabled". The I2C bus
+ // demultiplexer will enable it at runtime when needed.
+ status = "disabled";
+ };
+
+ iic2: i2c@e6520000 {
+ reg = <0xe6520000 0x425>;
+ pinctrl-0 = <&iic2_pins>;
+ // The pinctrl property for the parent I2C controller needs a pinctrl
+ // state with the same name as i2c-bus-name in the I2C bus demultiplexer
+ // node, not "default"!
+ pinctrl-names = "i2c-hdmi";
+
+ clock-frequency = <100000>;
+
+ // The I2C controller must have its status "disabled". The I2C bus
+ // demultiplexer will enable it at runtime when needed.
+ status = "disabled";
+ };
+
+ i2c2: i2c@e6530000 {
+ reg = <0 0xe6530000 0 0x40>;
+ pinctrl-0 = <&i2c2_pins>;
+ // The pinctrl property for the parent I2C controller needs a pinctrl
+ // state with the same name as i2c-bus-name in the I2C bus demultiplexer
+ // node, not "default"!
+ pinctrl-names = "i2c-hdmi";
+
+ clock-frequency = <100000>;
+
+ // The I2C controller must have its status "disabled". The I2C bus
+ // demultiplexer will enable it at runtime when needed.
+ status = "disabled";
+ };
+
+ // Example for a bus to be demuxed. It contains various I2C clients for
+ // HDMI, so the bus is named "i2c-hdmi":
+ i2chdmi: i2c-mux3 {
+ compatible = "i2c-demux-pinctrl";
+ i2c-parent = <&iic2>, <&i2c2>, <&gpioi2c2>;
+ i2c-bus-name = "i2c-hdmi";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ak4643: codec@12 {
+ compatible = "asahi-kasei,ak4643";
+ #sound-dai-cells = <0>;
+ reg = <0x12>;
+ };
+
+ composite-in@20 {
+ compatible = "adi,adv7180";
+ reg = <0x20>;
+
+ port {
+ adv7180: endpoint {
+ bus-width = <8>;
+ remote-endpoint = <&vin1ep0>;
+ };
+ };
+ };
+
+ hdmi@39 {
+ compatible = "adi,adv7511w";
+ reg = <0x39>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <15 IRQ_TYPE_LEVEL_LOW>;
+ clocks = <&cec_clock>;
+ clock-names = "cec";
+
+ avdd-supply = <&fixedregulator1v8>;
+ dvdd-supply = <&fixedregulator1v8>;
+ pvdd-supply = <&fixedregulator1v8>;
+ dvdd-3v-supply = <&fixedregulator3v3>;
+ bgvdd-supply = <&fixedregulator1v8>;
+
+ adi,input-depth = <8>;
+ adi,input-colorspace = "rgb";
+ adi,input-clock = "1x";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ adv7511_in: endpoint {
+ remote-endpoint = <&lvds0_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ adv7511_out: endpoint {
+ remote-endpoint = <&hdmi_con_out>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-efm32.txt b/Documentation/devicetree/bindings/i2c/i2c-efm32.txt
deleted file mode 100644
index 3b30e54ae3c7..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-efm32.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-* Energymicro efm32 i2c controller
-
-Required properties :
-
- - reg : Offset and length of the register set for the device
- - compatible : should be "energymicro,efm32-i2c"
- - interrupts : the interrupt number
- - clocks : reference to the module clock
-
-Recommended properties :
-
- - clock-frequency : maximal I2C bus clock frequency in Hz.
- - energymicro,location : Decides the location of the USART I/O pins.
- Allowed range : [0 .. 6]
-
-Example:
- i2c0: i2c@4000a000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "energymicro,efm32-i2c";
- reg = <0x4000a000 0x400>;
- interrupts = <9>;
- clocks = <&cmu clk_HFPERCLKI2C0>;
- clock-frequency = <100000>;
- energymicro,location = <3>;
-
- eeprom@50 {
- compatible = "microchip,24c02";
- reg = <0x50>;
- pagesize = <16>;
- };
- };
-
diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt b/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt
deleted file mode 100644
index 2dbc0b62daa6..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-* Samsung's High Speed I2C controller
-
-The Samsung's High Speed I2C controller is used to interface with I2C devices
-at various speeds ranging from 100khz to 3.4Mhz.
-
-Required properties:
- - compatible: value should be.
- -> "samsung,exynos5-hsi2c", (DEPRECATED)
- for i2c compatible with HSI2C available
- on Exynos5250 and Exynos5420 SoCs.
- -> "samsung,exynos5250-hsi2c", for i2c compatible with HSI2C available
- on Exynos5250 and Exynos5420 SoCs.
- -> "samsung,exynos5260-hsi2c", for i2c compatible with HSI2C available
- on Exynos5260 SoCs.
- -> "samsung,exynos7-hsi2c", for i2c compatible with HSI2C available
- on Exynos7 SoCs.
-
- - reg: physical base address of the controller and length of memory mapped
- region.
- - interrupts: interrupt number to the cpu.
- - #address-cells: always 1 (for i2c addresses)
- - #size-cells: always 0
-
- - Pinctrl:
- - pinctrl-0: Pin control group to be used for this controller.
- - pinctrl-names: Should contain only one value - "default".
-
-Optional properties:
- - clock-frequency: Desired operating frequency in Hz of the bus.
- -> If not specified, the bus operates in fast-speed mode at
- at 100khz.
- -> If specified, the bus operates in high-speed mode only if the
- clock-frequency is >= 1Mhz.
-
-Example:
-
-hsi2c@12ca0000 {
- compatible = "samsung,exynos5250-hsi2c";
- reg = <0x12ca0000 0x100>;
- interrupts = <56>;
- clock-frequency = <100000>;
-
- pinctrl-0 = <&i2c4_bus>;
- pinctrl-names = "default";
-
- #address-cells = <1>;
- #size-cells = <0>;
-
- s2mps11_pmic@66 {
- compatible = "samsung,s2mps11-pmic";
- reg = <0x66>;
- };
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml
new file mode 100644
index 000000000000..32269239bae4
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml
@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-exynos5.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung's High Speed I2C controller
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ The Samsung's High Speed I2C controller is used to interface with I2C devices
+ at various speeds ranging from 100kHz to 3.4MHz.
+
+ In case the HSI2C controller is encapsulated within USI block (it's the case
+ e.g. for Exynos850 and Exynos Auto V9 SoCs), it might be also necessary to
+ define USI node in device tree file, choosing "i2c" configuration. Please see
+ Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml for details.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - samsung,exynos5250-hsi2c # Exynos5250 and Exynos5420
+ - samsung,exynos5260-hsi2c # Exynos5260
+ - samsung,exynos7-hsi2c # Exynos7
+ - samsung,exynos8895-hsi2c
+ - samsung,exynosautov9-hsi2c
+ - items:
+ - enum:
+ - samsung,exynos5433-hsi2c
+ - samsung,exynos7870-hsi2c
+ - tesla,fsd-hsi2c
+ - const: samsung,exynos7-hsi2c
+ - items:
+ - enum:
+ - samsung,exynos8890-hsi2c
+ - const: samsung,exynos8895-hsi2c
+ - items:
+ - enum:
+ - google,gs101-hsi2c
+ - samsung,exynos2200-hsi2c
+ - samsung,exynos850-hsi2c
+ - samsung,exynos990-hsi2c
+ - const: samsung,exynosautov9-hsi2c
+ - const: samsung,exynos5-hsi2c # Exynos5250 and Exynos5420
+ deprecated: true
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clock-frequency:
+ default: 100000
+ description:
+ Desired operating frequency in Hz of the bus.
+
+ If not specified, the bus operates in fast-speed mode at 100kHz.
+
+ If specified, the bus operates in high-speed mode only if the
+ clock-frequency is >= 1MHz.
+
+ clocks:
+ minItems: 1
+ items:
+ - description: I2C operating clock
+ - description: Bus clock (APB)
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: hsi2c
+ - const: hsi2c_pclk
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,exynosautov9-hsi2c
+
+ then:
+ properties:
+ clocks:
+ minItems: 2
+
+ clock-names:
+ minItems: 2
+
+ required:
+ - clock-names
+
+ else:
+ properties:
+ clocks:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos5420.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ hsi2c_8: i2c@12e00000 {
+ compatible = "samsung,exynos5250-hsi2c";
+ reg = <0x12e00000 0x1000>;
+ interrupts = <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clock-frequency = <100000>;
+ clocks = <&clock CLK_USI4>;
+ clock-names = "hsi2c";
+
+ pmic@66 {
+ /* compatible = "samsung,s2mps11-pmic"; */
+ reg = <0x66>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/clock/exynos850.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ hsi2c_2: i2c@138c0000 {
+ compatible = "samsung,exynosautov9-hsi2c";
+ reg = <0x138c0000 0xc0>;
+ interrupts = <GIC_SPI 195 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&cmu_peri CLK_GOUT_HSI2C2_IPCLK>,
+ <&cmu_peri CLK_GOUT_HSI2C2_PCLK>;
+ clock-names = "hsi2c", "hsi2c_pclk";
+
+ pmic@66 {
+ /* compatible = "samsung,s2mps11-pmic"; */
+ reg = <0x66>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-fsi.txt b/Documentation/devicetree/bindings/i2c/i2c-fsi.txt
deleted file mode 100644
index b1be2ceb7e69..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-fsi.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-Device-tree bindings for FSI-attached I2C master and busses
------------------------------------------------------------
-
-Required properties:
- - compatible = "ibm,i2c-fsi";
- - reg = < address size >; : The FSI CFAM address and address
- space size.
- - #address-cells = <1>; : Number of address cells in child
- nodes.
- - #size-cells = <0>; : Number of size cells in child nodes.
- - child nodes : Nodes to describe busses off the I2C
- master.
-
-Child node required properties:
- - reg = < port number > : The port number on the I2C master.
-
-Child node optional properties:
- - child nodes : Nodes to describe devices on the I2C
- bus.
-
-Examples:
-
- i2c@1800 {
- compatible = "ibm,i2c-fsi";
- reg = < 0x1800 0x400 >;
- #address-cells = <1>;
- #size-cells = <0>;
-
- i2c-bus@0 {
- reg = <0>;
- };
-
- i2c-bus@1 {
- reg = <1>;
-
- eeprom@50 {
- compatible = "vendor,dev-name";
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-gate.yaml b/Documentation/devicetree/bindings/i2c/i2c-gate.yaml
index 66472f12a7e2..0cdc3e890df7 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-gate.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-gate.yaml
@@ -31,9 +31,8 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
ak8975@c {
- compatible = "ak,ak8975";
+ compatible = "asahi-kasei,ak8975";
reg = <0x0c>;
};
};
...
-
diff --git a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml
index fd040284561f..afd4925c2a7d 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i2c/i2c-gpio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Bindings for GPIO bitbanged I2C
+title: GPIO bitbanged I2C
maintainers:
- Wolfram Sang <wsa@kernel.org>
@@ -33,6 +33,10 @@ properties:
open drain.
maxItems: 1
+ i2c-gpio,sda-output-only:
+ description: sda as output only
+ type: boolean
+
i2c-gpio,scl-output-only:
description: scl as output only
type: boolean
@@ -63,6 +67,28 @@ properties:
GPIO line used for SCL into open drain mode, and that something is not
the GPIO chip. It is essentially an inconsistency flag.
+ i2c-gpio,sda-has-no-pullup:
+ type: boolean
+ description: sda is used in a non-compliant way and has no pull-up.
+ Therefore disable open-drain. This property is mutually-exclusive
+ with i2c-gpio,sda-open-drain.
+
+ i2c-gpio,scl-has-no-pullup:
+ type: boolean
+ description: scl is used in a non-compliant way and has no pull-up.
+ Therefore disable open-drain. This property is mutually-exclusive
+ with i2c-gpio,scl-open-drain.
+
+dependencies:
+ i2c-gpio,sda-has-no-pullup:
+ not:
+ required:
+ - i2c-gpio,sda-open-drain
+ i2c-gpio,scl-has-no-pullup:
+ not:
+ required:
+ - i2c-gpio,scl-open-drain
+
required:
- compatible
- sda-gpios
diff --git a/Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt b/Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt
deleted file mode 100644
index f98b37401e6e..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-I2C for Hisilicon hix5hd2 chipset platform
-
-Required properties:
-- compatible: Must be "hisilicon,hix5hd2-i2c"
-- reg: physical base address of the controller and length of memory mapped
- region.
-- interrupts: interrupt number to the cpu.
-- #address-cells = <1>;
-- #size-cells = <0>;
-- clocks: phandles to input clocks.
-
-Optional properties:
-- clock-frequency: Desired I2C bus frequency in Hz, otherwise defaults to 100000
-- Child nodes conforming to i2c bus binding
-
-Examples:
-I2C0@f8b10000 {
- compatible = "hisilicon,hix5hd2-i2c";
- reg = <0xf8b10000 0x1000>;
- interrupts = <0 38 4>;
- clocks = <&clock HIX5HD2_I2C0_RST>;
- #address-cells = <1>;
- #size-cells = <0>;
-}
diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
index 29b9447f3b84..969030a6f82a 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml
@@ -7,7 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale Low Power Inter IC (LPI2C) for i.MX
maintainers:
- - Anson Huang <Anson.Huang@nxp.com>
+ - Shawn Guo <shawnguo@kernel.org>
+ - Sascha Hauer <s.hauer@pengutronix.de>
+ - Fabio Estevam <festevam@gmail.com>
allOf:
- $ref: /schemas/i2c/i2c-controller.yaml#
@@ -17,9 +19,15 @@ properties:
oneOf:
- enum:
- fsl,imx7ulp-lpi2c
- - fsl,imx8qm-lpi2c
- items:
- - const: fsl,imx8qxp-lpi2c
+ - enum:
+ - fsl,imx8qxp-lpi2c
+ - fsl,imx8dxl-lpi2c
+ - fsl,imx8qm-lpi2c
+ - fsl,imx8ulp-lpi2c
+ - fsl,imx93-lpi2c
+ - fsl,imx94-lpi2c
+ - fsl,imx95-lpi2c
- const: fsl,imx7ulp-lpi2c
reg:
@@ -34,10 +42,22 @@ properties:
clock-frequency: true
clock-names:
- maxItems: 1
+ items:
+ - const: per
+ - const: ipg
clocks:
- maxItems: 1
+ maxItems: 2
+
+ dmas:
+ items:
+ - description: DMA controller phandle and request line for TX
+ - description: DMA controller phandle and request line for RX
+
+ dma-names:
+ items:
+ - const: tx
+ - const: rx
power-domains:
maxItems: 1
@@ -60,5 +80,6 @@ examples:
reg = <0x40A50000 0x10000>;
interrupt-parent = <&intc>;
interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&clks IMX7ULP_CLK_LPI2C7>;
+ clocks = <&clks IMX7ULP_CLK_LPI2C7>,
+ <&clks IMX7ULP_CLK_NIC1_BUS_DIV>;
};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml
index 3592d49235e0..0682a5a10d41 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml
@@ -18,6 +18,18 @@ properties:
- const: fsl,imx1-i2c
- const: fsl,imx21-i2c
- const: fsl,vf610-i2c
+ - const: nxp,s32g2-i2c
+ - items:
+ - enum:
+ - fsl,ls1012a-i2c
+ - fsl,ls1021a-i2c
+ - fsl,ls1028a-i2c
+ - fsl,ls1043a-i2c
+ - fsl,ls1046a-i2c
+ - fsl,ls1088a-i2c
+ - fsl,ls208xa-i2c
+ - fsl,lx2160a-i2c
+ - const: fsl,vf610-i2c
- items:
- const: fsl,imx35-i2c
- const: fsl,imx1-i2c
@@ -43,6 +55,9 @@ properties:
- fsl,imx8mn-i2c
- fsl,imx8mp-i2c
- const: fsl,imx21-i2c
+ - items:
+ - const: nxp,s32g3-i2c
+ - const: nxp,s32g2-i2c
reg:
maxItems: 1
@@ -57,7 +72,9 @@ properties:
const: ipg
clock-frequency:
- enum: [ 100000, 400000 ]
+ minimum: 1
+ default: 100000
+ maximum: 400000
dmas:
items:
@@ -86,9 +103,7 @@ unevaluatedProperties: false
examples:
- |
#include <dt-bindings/clock/imx5-clock.h>
- #include <dt-bindings/clock/vf610-clock.h>
- #include <dt-bindings/gpio/gpio.h>
- #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
i2c@83fc4000 {
compatible = "fsl,imx51-i2c", "fsl,imx21-i2c";
@@ -97,6 +112,9 @@ examples:
clocks = <&clks IMX5_CLK_I2C2_GATE>;
};
+ - |
+ #include <dt-bindings/clock/vf610-clock.h>
+
i2c@40066000 {
compatible = "fsl,vf610-i2c";
reg = <0x40066000 0x1000>;
diff --git a/Documentation/devicetree/bindings/i2c/i2c-lpc2k.txt b/Documentation/devicetree/bindings/i2c/i2c-lpc2k.txt
deleted file mode 100644
index 4101aa621ad4..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-lpc2k.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-NXP I2C controller for LPC2xxx/178x/18xx/43xx
-
-Required properties:
- - compatible: must be "nxp,lpc1788-i2c"
- - reg: physical address and length of the device registers
- - interrupts: a single interrupt specifier
- - clocks: clock for the device
- - #address-cells: should be <1>
- - #size-cells: should be <0>
-
-Optional properties:
-- clock-frequency: the desired I2C bus clock frequency in Hz; in
- absence of this property the default value is used (100 kHz).
-
-Example:
-i2c0: i2c@400a1000 {
- compatible = "nxp,lpc1788-i2c";
- reg = <0x400a1000 0x1000>;
- interrupts = <18>;
- clocks = <&ccu1 CLK_APB1_I2C0>;
- #address-cells = <1>;
- #size-cells = <0>;
-};
-
-&i2c0 {
- clock-frequency = <400000>;
-
- lm75@48 {
- compatible = "nxp,lm75";
- reg = <0x48>;
- };
-};
-
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
index 98c6fcf7bf26..b1d7d14c0be4 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
@@ -43,6 +43,7 @@ properties:
fsl,timeout:
$ref: /schemas/types.yaml#/definitions/uint32
+ deprecated: true
description: |
I2C bus timeout in microseconds
@@ -73,6 +74,7 @@ examples:
clock-frequency = <100000>;
};
+ - |
/* MPC5200B based board */
i2c@3d00 {
#address-cells = <1>;
@@ -84,6 +86,7 @@ examples:
fsl,preserve-clocking;
};
+ - |
/* MPC8544 base board */
i2c@3100 {
#address-cells = <1>;
@@ -93,6 +96,6 @@ examples:
interrupts = <43 2>;
interrupt-parent = <&mpic>;
clock-frequency = <400000>;
- fsl,timeout = <10000>;
+ i2c-transfer-timeout-us = <10000>;
};
...
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt
deleted file mode 100644
index 5ea216ae7084..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-* MediaTek's I2C controller
-
-The MediaTek's I2C controller is used to interface with I2C devices.
-
-Required properties:
- - compatible: value should be either of the following.
- "mediatek,mt2701-i2c", "mediatek,mt6577-i2c": for MediaTek MT2701
- "mediatek,mt2712-i2c": for MediaTek MT2712
- "mediatek,mt6577-i2c": for MediaTek MT6577
- "mediatek,mt6589-i2c": for MediaTek MT6589
- "mediatek,mt6797-i2c", "mediatek,mt6577-i2c": for MediaTek MT6797
- "mediatek,mt7622-i2c": for MediaTek MT7622
- "mediatek,mt7623-i2c", "mediatek,mt6577-i2c": for MediaTek MT7623
- "mediatek,mt7629-i2c", "mediatek,mt2712-i2c": for MediaTek MT7629
- "mediatek,mt8173-i2c": for MediaTek MT8173
- "mediatek,mt8183-i2c": for MediaTek MT8183
- "mediatek,mt8192-i2c": for MediaTek MT8192
- "mediatek,mt8195-i2c", "mediatek,mt8192-i2c": for MediaTek MT8195
- "mediatek,mt8516-i2c", "mediatek,mt2712-i2c": for MediaTek MT8516
- - reg: physical base address of the controller and dma base, length of memory
- mapped region.
- - interrupts: interrupt number to the cpu.
- - clock-div: the fixed value for frequency divider of clock source in i2c
- module. Each IC may be different.
- - clocks: clock name from clock manager
- - clock-names: Must include "main" and "dma", "arb" is for multi-master that
- one bus has more than two i2c controllers, if enable have-pmic need include
- "pmic" extra.
-
-Optional properties:
- - clock-frequency: Frequency in Hz of the bus when transfer, the default value
- is 100000.
- - mediatek,have-pmic: platform can control i2c form special pmic side.
- Only mt6589 and mt8135 support this feature.
- - mediatek,use-push-pull: IO config use push-pull mode.
- - vbus-supply: phandle to the regulator that provides power to SCL/SDA.
-
-Example:
-
- i2c0: i2c@1100d000 {
- compatible = "mediatek,mt6577-i2c";
- reg = <0x1100d000 0x70>,
- <0x11000300 0x80>;
- interrupts = <GIC_SPI 44 IRQ_TYPE_LEVEL_LOW>;
- clock-frequency = <400000>;
- mediatek,have-pmic;
- clock-div = <16>;
- clocks = <&i2c0_ck>, <&ap_dma_ck>;
- clock-names = "main", "dma";
- };
-
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml
new file mode 100644
index 000000000000..3562ce0c0f7e
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-mt65xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek I2C controller
+
+description:
+ This driver interfaces with the native I2C controller present in
+ various MediaTek SoCs.
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+maintainers:
+ - Qii Wang <qii.wang@mediatek.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: mediatek,mt2712-i2c
+ - const: mediatek,mt6577-i2c
+ - const: mediatek,mt6589-i2c
+ - const: mediatek,mt7622-i2c
+ - const: mediatek,mt7981-i2c
+ - const: mediatek,mt7986-i2c
+ - const: mediatek,mt8168-i2c
+ - const: mediatek,mt8173-i2c
+ - const: mediatek,mt8183-i2c
+ - const: mediatek,mt8186-i2c
+ - const: mediatek,mt8188-i2c
+ - const: mediatek,mt8192-i2c
+ - items:
+ - enum:
+ - mediatek,mt7629-i2c
+ - mediatek,mt8516-i2c
+ - const: mediatek,mt2712-i2c
+ - items:
+ - enum:
+ - mediatek,mt2701-i2c
+ - mediatek,mt6797-i2c
+ - mediatek,mt7623-i2c
+ - const: mediatek,mt6577-i2c
+ - items:
+ - enum:
+ - mediatek,mt8365-i2c
+ - const: mediatek,mt8168-i2c
+ - items:
+ - enum:
+ - mediatek,mt6795-i2c
+ - const: mediatek,mt8173-i2c
+ - items:
+ - enum:
+ - mediatek,mt6878-i2c
+ - mediatek,mt6991-i2c
+ - mediatek,mt8196-i2c
+ - const: mediatek,mt8188-i2c
+ - items:
+ - enum:
+ - mediatek,mt6893-i2c
+ - mediatek,mt8195-i2c
+ - const: mediatek,mt8192-i2c
+
+ reg:
+ items:
+ - description: Physical base address
+ - description: DMA base address
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 2
+ items:
+ - description: Main clock for I2C bus
+ - description: Clock for I2C via DMA
+ - description: Bus arbitrator clock
+ - description: Clock for I2C from PMIC
+
+ clock-names:
+ minItems: 2
+ items:
+ - const: main
+ - const: dma
+ - const: arb
+ - const: pmic
+
+ clock-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Frequency divider of clock source in I2C module
+
+ clock-frequency:
+ default: 100000
+ description:
+ SCL frequency to use (in Hz). If omitted, 100kHz is used.
+
+ mediatek,have-pmic:
+ description: Platform controls I2C from PMIC side
+ type: boolean
+
+ mediatek,use-push-pull:
+ description: Use push-pull mode I/O config
+ type: boolean
+
+ vbus-supply:
+ description: Phandle to the regulator providing power to SCL/SDA
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - clock-div
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c0: i2c@1100d000 {
+ compatible = "mediatek,mt6577-i2c";
+ reg = <0x1100d000 0x70>, <0x11000300 0x80>;
+ interrupts = <GIC_SPI 44 IRQ_TYPE_LEVEL_LOW>;
+ clocks = <&i2c0_ck>, <&ap_dma_ck>;
+ clock-names = "main", "dma";
+ clock-div = <16>;
+ clock-frequency = <400000>;
+ mediatek,have-pmic;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt7621.txt b/Documentation/devicetree/bindings/i2c/i2c-mt7621.txt
deleted file mode 100644
index bc36f0eb94cd..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-mt7621.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-MediaTek MT7621/MT7628 I2C master controller
-
-Required properties:
-
-- compatible: Should be one of the following:
- - "mediatek,mt7621-i2c": for MT7621/MT7628/MT7688 platforms
-- #address-cells: should be 1.
-- #size-cells: should be 0.
-- reg: Address and length of the register set for the device
-- resets: phandle to the reset controller asserting this device in
- reset
- See ../reset/reset.txt for details.
-
-Optional properties :
-
-Example:
-
-i2c: i2c@900 {
- compatible = "mediatek,mt7621-i2c";
- reg = <0x900 0x100>;
- #address-cells = <1>;
- #size-cells = <0>;
- resets = <&rstctrl 16>;
- reset-names = "i2c";
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt
deleted file mode 100644
index d4cf10582a26..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.txt
+++ /dev/null
@@ -1,80 +0,0 @@
-GPIO-based I2C Bus Mux
-
-This binding describes an I2C bus multiplexer that uses GPIOs to
-route the I2C signals.
-
- +-----+ +-----+
- | dev | | dev |
- +------------+ +-----+ +-----+
- | SoC | | |
- | | /--------+--------+
- | +------+ | +------+ child bus A, on GPIO value set to 0
- | | I2C |-|--| Mux |
- | +------+ | +--+---+ child bus B, on GPIO value set to 1
- | | | \----------+--------+--------+
- | +------+ | | | | |
- | | GPIO |-|-----+ +-----+ +-----+ +-----+
- | +------+ | | dev | | dev | | dev |
- +------------+ +-----+ +-----+ +-----+
-
-Required properties:
-- compatible: i2c-mux-gpio
-- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side
- port is connected to.
-- mux-gpios: list of gpios used to control the muxer
-* Standard I2C mux properties. See i2c-mux.yaml in this directory.
-* I2C child bus nodes. See i2c-mux.yaml in this directory.
-
-Optional properties:
-- idle-state: value to set the muxer to when idle. When no value is
- given, it defaults to the last value used.
-
-For each i2c child node, an I2C child bus will be created. They will
-be numbered based on their order in the device tree.
-
-Whenever an access is made to a device on a child bus, the value set
-in the relevant node's reg property will be output using the list of
-GPIOs, the first in the list holding the least-significant value.
-
-If an idle state is defined, using the idle-state (optional) property,
-whenever an access is not being made to a device on a child bus, the
-GPIOs will be set according to the idle value.
-
-If an idle state is not defined, the most recently used value will be
-left programmed into hardware whenever no access is being made to a
-device on a child bus.
-
-Example:
- i2cmux {
- compatible = "i2c-mux-gpio";
- #address-cells = <1>;
- #size-cells = <0>;
- mux-gpios = <&gpio1 22 0 &gpio1 23 0>;
- i2c-parent = <&i2c1>;
-
- i2c@1 {
- reg = <1>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- ssd1307: oled@3c {
- compatible = "solomon,ssd1307fb-i2c";
- reg = <0x3c>;
- pwms = <&pwm 4 3000>;
- reset-gpios = <&gpio2 7 1>;
- };
- };
-
- i2c@3 {
- reg = <3>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- pca9555: pca9555@20 {
- compatible = "nxp,pca9555";
- gpio-controller;
- #gpio-cells = <2>;
- reg = <0x20>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml
new file mode 100644
index 000000000000..4a93d1f78f93
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-mux-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO-based I2C Bus Mux
+
+maintainers:
+ - Wolfram Sang <wsa@kernel.org>
+
+description: |
+ This binding describes an I2C bus multiplexer that uses GPIOs to route the I2C signals.
+
+ +-----+ +-----+
+ | dev | | dev |
+ +------------+ +-----+ +-----+
+ | SoC | | |
+ | | /--------+--------+
+ | +------+ | +------+ child bus A, on GPIO value set to 0
+ | | I2C |-|--| Mux |
+ | +------+ | +--+---+ child bus B, on GPIO value set to 1
+ | | | \----------+--------+--------+
+ | +------+ | | | | |
+ | | GPIO |-|-----+ +-----+ +-----+ +-----+
+ | +------+ | | dev | | dev | | dev |
+ +------------+ +-----+ +-----+ +-----+
+
+ For each I2C child node, an I2C child bus will be created. They will be numbered based on their
+ order in the device tree.
+
+ Whenever an access is made to a device on a child bus, the value set in the relevant node's reg
+ property will be output using the list of GPIOs, the first in the list holding the least-
+ significant value.
+
+ If an idle state is defined, using the idle-state (optional) property, whenever an access is not
+ being made to a device on a child bus, the GPIOs will be set according to the idle value.
+
+ If an idle state is not defined, the most recently used value will be left programmed into
+ hardware whenever no access is being made to a device on a child bus.
+
+properties:
+ compatible:
+ const: i2c-mux-gpio
+
+ i2c-parent:
+ description: phandle of the I2C bus that this multiplexer's master-side port is connected to
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ mux-gpios:
+ description: list of GPIOs used to control the muxer
+ minItems: 1
+ maxItems: 4 # Should be enough
+
+ idle-state:
+ description: Value to set the muxer to when idle. When no value is given, it defaults to the
+ last value used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ settle-time-us:
+ description: Delay to wait before doing any transfer when a new bus gets selected.
+
+allOf:
+ - $ref: i2c-mux.yaml
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - i2c-parent
+ - mux-gpios
+
+examples:
+ - |
+ i2cmux {
+ compatible = "i2c-mux-gpio";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ mux-gpios = <&gpio1 22 0>, <&gpio1 23 0>;
+ i2c-parent = <&i2c1>;
+
+ i2c@1 {
+ reg = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ssd1307: oled@3c {
+ compatible = "solomon,ssd1307fb-i2c";
+ reg = <0x3c>;
+ pwms = <&pwm 4 3000>;
+ reset-gpios = <&gpio2 7 1>;
+ };
+ };
+
+ i2c@3 {
+ reg = <3>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pca9555: pca9555@20 {
+ compatible = "nxp,pca9555";
+ gpio-controller;
+ #gpio-cells = <2>;
+ reg = <0x20>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.yaml
index 9b0603a72f40..d8610daa10cd 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.yaml
@@ -27,8 +27,6 @@ description: |+
| '------' | | dev | | dev | | dev |
'------------' '-----' '-----' '-----'
-
-
allOf:
- $ref: /schemas/i2c/i2c-mux.yaml#
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml
index 9f1726d0356b..9aa0585200c9 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml
@@ -4,21 +4,29 @@
$id: http://devicetree.org/schemas/i2c/i2c-mux-pca954x.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: NXP PCA954x I2C bus switch
+title: NXP PCA954x I2C and compatible bus switches
maintainers:
- Laurent Pinchart <laurent.pinchart@ideasonboard.com>
description:
- The binding supports NXP PCA954x and PCA984x I2C mux/switch devices.
-
-allOf:
- - $ref: /schemas/i2c/i2c-mux.yaml#
+ The NXP PCA954x and compatible devices are I2C bus
+ multiplexer/switches that share the same functionality
+ and register layout.
+ The devices usually have 4 or 8 child buses, which are
+ attached to the parent bus by using the SMBus "Send Byte"
+ command.
properties:
compatible:
oneOf:
- enum:
+ - maxim,max7356
+ - maxim,max7357
+ - maxim,max7358
+ - maxim,max7367
+ - maxim,max7368
+ - maxim,max7369
- nxp,pca9540
- nxp,pca9542
- nxp,pca9543
@@ -59,10 +67,64 @@ properties:
description: if present, overrides i2c-mux-idle-disconnect
$ref: /schemas/mux/mux-controller.yaml#/properties/idle-state
+ vdd-supply:
+ description: A voltage regulator supplying power to the chip. On PCA9846
+ the regulator supplies power to VDD2 (core logic) and optionally to VDD1.
+
+ maxim,isolate-stuck-channel:
+ type: boolean
+ description: Allows to use non faulty channels while a stuck channel is
+ isolated from the upstream bus. If not set all channels are isolated from
+ the upstream bus until the fault is cleared.
+
+ maxim,send-flush-out-sequence:
+ type: boolean
+ description: Send a flush-out sequence to stuck auxiliary buses
+ automatically after a stuck channel is being detected.
+
+ maxim,preconnection-wiggle-test-enable:
+ type: boolean
+ description: Send a STOP condition to the auxiliary buses when the switch
+ register activates a channel to detect a stuck high fault. On fault the
+ channel is isolated from the upstream bus.
+
required:
- compatible
- reg
+allOf:
+ - $ref: /schemas/i2c/i2c-mux.yaml#
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - maxim,max7367
+ - maxim,max7369
+ - nxp,pca9542
+ - nxp,pca9543
+ - nxp,pca9544
+ - nxp,pca9545
+ then:
+ properties:
+ interrupts: false
+ "#interrupt-cells": false
+ interrupt-controller: false
+
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - maxim,max7357
+ then:
+ properties:
+ maxim,isolate-stuck-channel: false
+ maxim,send-flush-out-sequence: false
+ maxim,preconnection-wiggle-test-enable: false
+
unevaluatedProperties: false
examples:
@@ -74,11 +136,13 @@ examples:
#size-cells = <0>;
i2c-mux@74 {
- compatible = "nxp,pca9548";
+ compatible = "nxp,pca9545";
#address-cells = <1>;
#size-cells = <0>;
reg = <0x74>;
+ vdd-supply = <&p3v3>;
+
interrupt-parent = <&ipic>;
interrupts = <17 IRQ_TYPE_LEVEL_LOW>;
interrupt-controller;
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt
deleted file mode 100644
index 997a287ed3f6..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-Pinctrl-based I2C Bus Mux
-
-This binding describes an I2C bus multiplexer that uses pin multiplexing to
-route the I2C signals, and represents the pin multiplexing configuration
-using the pinctrl device tree bindings.
-
- +-----+ +-----+
- | dev | | dev |
- +------------------------+ +-----+ +-----+
- | SoC | | |
- | /----|------+--------+
- | +---+ +------+ | child bus A, on first set of pins
- | |I2C|---|Pinmux| |
- | +---+ +------+ | child bus B, on second set of pins
- | \----|------+--------+--------+
- | | | | |
- +------------------------+ +-----+ +-----+ +-----+
- | dev | | dev | | dev |
- +-----+ +-----+ +-----+
-
-Required properties:
-- compatible: i2c-mux-pinctrl
-- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side
- port is connected to.
-
-Also required are:
-
-* Standard pinctrl properties that specify the pin mux state for each child
- bus. See ../pinctrl/pinctrl-bindings.txt.
-
-* Standard I2C mux properties. See i2c-mux.yaml in this directory.
-
-* I2C child bus nodes. See i2c-mux.yaml in this directory.
-
-For each named state defined in the pinctrl-names property, an I2C child bus
-will be created. I2C child bus numbers are assigned based on the index into
-the pinctrl-names property.
-
-The only exception is that no bus will be created for a state named "idle". If
-such a state is defined, it must be the last entry in pinctrl-names. For
-example:
-
- pinctrl-names = "ddc", "pta", "idle" -> ddc = bus 0, pta = bus 1
- pinctrl-names = "ddc", "idle", "pta" -> Invalid ("idle" not last)
- pinctrl-names = "idle", "ddc", "pta" -> Invalid ("idle" not last)
-
-Whenever an access is made to a device on a child bus, the relevant pinctrl
-state will be programmed into hardware.
-
-If an idle state is defined, whenever an access is not being made to a device
-on a child bus, the idle pinctrl state will be programmed into hardware.
-
-If an idle state is not defined, the most recently used pinctrl state will be
-left programmed into hardware whenever no access is being made of a device on
-a child bus.
-
-Example:
-
- i2cmux {
- compatible = "i2c-mux-pinctrl";
- #address-cells = <1>;
- #size-cells = <0>;
-
- i2c-parent = <&i2c1>;
-
- pinctrl-names = "ddc", "pta", "idle";
- pinctrl-0 = <&state_i2cmux_ddc>;
- pinctrl-1 = <&state_i2cmux_pta>;
- pinctrl-2 = <&state_i2cmux_idle>;
-
- i2c@0 {
- reg = <0>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- eeprom {
- compatible = "eeprom";
- reg = <0x50>;
- };
- };
-
- i2c@1 {
- reg = <1>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- eeprom {
- compatible = "eeprom";
- reg = <0x50>;
- };
- };
- };
-
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml
new file mode 100644
index 000000000000..2e3d555eb96c
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pinctrl.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-mux-pinctrl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Pinctrl-based I2C Bus Mux
+
+maintainers:
+ - Wolfram Sang <wsa@kernel.org>
+
+description: |
+ This binding describes an I2C bus multiplexer that uses pin multiplexing to route the I2C
+ signals, and represents the pin multiplexing configuration using the pinctrl device tree
+ bindings.
+
+ +-----+ +-----+
+ | dev | | dev |
+ +------------------------+ +-----+ +-----+
+ | SoC | | |
+ | /----|------+--------+
+ | +---+ +------+ | child bus A, on first set of pins
+ | |I2C|---|Pinmux| |
+ | +---+ +------+ | child bus B, on second set of pins
+ | \----|------+--------+--------+
+ | | | | |
+ +------------------------+ +-----+ +-----+ +-----+
+ | dev | | dev | | dev |
+ +-----+ +-----+ +-----+
+
+ For each named state defined in the pinctrl-names property, an I2C child bus will be created.
+ I2C child bus numbers are assigned based on the index into the pinctrl-names property.
+
+ The only exception is that no bus will be created for a state named "idle". If such a state is
+ defined, it must be the last entry in pinctrl-names. For example:
+
+ pinctrl-names = "ddc", "pta", "idle" -> ddc = bus 0, pta = bus 1
+ pinctrl-names = "ddc", "idle", "pta" -> Invalid ("idle" not last)
+ pinctrl-names = "idle", "ddc", "pta" -> Invalid ("idle" not last)
+
+ Whenever an access is made to a device on a child bus, the relevant pinctrl state will be
+ programmed into hardware.
+
+ If an idle state is defined, whenever an access is not being made to a device on a child bus,
+ the idle pinctrl state will be programmed into hardware.
+
+ If an idle state is not defined, the most recently used pinctrl state will be left programmed
+ into hardware whenever no access is being made of a device on a child bus.
+
+properties:
+ compatible:
+ const: i2c-mux-pinctrl
+
+ i2c-parent:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: The phandle of the I2C bus that this multiplexer's master-side port is connected
+ to.
+
+allOf:
+ - $ref: i2c-mux.yaml
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - i2c-parent
+
+examples:
+ - |
+ i2cmux {
+ compatible = "i2c-mux-pinctrl";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c-parent = <&i2c1>;
+
+ pinctrl-names = "ddc", "pta", "idle";
+ pinctrl-0 = <&state_i2cmux_ddc>;
+ pinctrl-1 = <&state_i2cmux_pta>;
+ pinctrl-2 = <&state_i2cmux_idle>;
+
+ i2c@0 {
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@50 {
+ compatible = "atmel,24c02";
+ reg = <0x50>;
+ };
+ };
+
+ i2c@1 {
+ reg = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@50 {
+ compatible = "atmel,24c02";
+ reg = <0x50>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml
index 21ae7bce038e..171a41407241 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml
@@ -9,6 +9,9 @@ title: Freescale MXS Inter IC (I2C) Controller
maintainers:
- Shawn Guo <shawnguo@kernel.org>
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
properties:
compatible:
enum:
@@ -37,7 +40,7 @@ required:
- dmas
- dma-names
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/i2c/i2c-nomadik.txt b/Documentation/devicetree/bindings/i2c/i2c-nomadik.txt
deleted file mode 100644
index 72065b0ff680..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-nomadik.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-I2C for Nomadik based systems
-
-Required (non-standard) properties:
- - Nil
-
-Recommended (non-standard) properties:
- - clock-frequency : Maximum bus clock frequency for the device
-
-Optional (non-standard) properties:
- - Nil
-
-Example :
-
-i2c@80004000 {
- compatible = "stericsson,db8500-i2c", "st,nomadik-i2c";
- reg = <0x80004000 0x1000>;
- interrupts = <0 21 0x4>;
- #address-cells = <1>;
- #size-cells = <0>;
- v-i2c-supply = <&db8500_vape_reg>;
-
- clock-frequency = <400000>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-ocores.txt b/Documentation/devicetree/bindings/i2c/i2c-ocores.txt
deleted file mode 100644
index a37c9455b244..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-ocores.txt
+++ /dev/null
@@ -1,78 +0,0 @@
-Device tree configuration for i2c-ocores
-
-Required properties:
-- compatible : "opencores,i2c-ocores"
- "aeroflexgaisler,i2cmst"
- "sifive,fu540-c000-i2c", "sifive,i2c0"
- For Opencore based I2C IP block reimplemented in
- FU540-C000 SoC.
- "sifive,fu740-c000-i2c", "sifive,i2c0"
- For Opencore based I2C IP block reimplemented in
- FU740-C000 SoC.
- Please refer to sifive-blocks-ip-versioning.txt for
- additional details.
-- reg : bus address start and address range size of device
-- clocks : handle to the controller clock; see the note below.
- Mutually exclusive with opencores,ip-clock-frequency
-- opencores,ip-clock-frequency: frequency of the controller clock in Hz;
- see the note below. Mutually exclusive with clocks
-- #address-cells : should be <1>
-- #size-cells : should be <0>
-
-Optional properties:
-- interrupts : interrupt number.
-- clock-frequency : frequency of bus clock in Hz; see the note below.
- Defaults to 100 KHz when the property is not specified
-- reg-shift : device register offsets are shifted by this value
-- reg-io-width : io register width in bytes (1, 2 or 4)
-- regstep : deprecated, use reg-shift above
-
-Note
-clock-frequency property is meant to control the bus frequency for i2c bus
-drivers, but it was incorrectly used to specify i2c controller input clock
-frequency. So the following rules are set to fix this situation:
-- if clock-frequency is present and neither opencores,ip-clock-frequency nor
- clocks are, then clock-frequency specifies i2c controller clock frequency.
- This is to keep backwards compatibility with setups using old DTB. i2c bus
- frequency is fixed at 100 KHz.
-- if clocks is present it specifies i2c controller clock. clock-frequency
- property specifies i2c bus frequency.
-- if opencores,ip-clock-frequency is present it specifies i2c controller
- clock frequency. clock-frequency property specifies i2c bus frequency.
-
-Examples:
-
- i2c0: ocores@a0000000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "opencores,i2c-ocores";
- reg = <0xa0000000 0x8>;
- interrupts = <10>;
- opencores,ip-clock-frequency = <20000000>;
-
- reg-shift = <0>; /* 8 bit registers */
- reg-io-width = <1>; /* 8 bit read/write */
-
- dummy@60 {
- compatible = "dummy";
- reg = <0x60>;
- };
- };
-or
- i2c0: ocores@a0000000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "opencores,i2c-ocores";
- reg = <0xa0000000 0x8>;
- interrupts = <10>;
- clocks = <&osc>;
- clock-frequency = <400000>; /* i2c bus frequency 400 KHz */
-
- reg-shift = <0>; /* 8 bit registers */
- reg-io-width = <1>; /* 8 bit read/write */
-
- dummy@60 {
- compatible = "dummy";
- reg = <0x60>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-pnx.txt b/Documentation/devicetree/bindings/i2c/i2c-pnx.txt
deleted file mode 100644
index 2a59006cf79e..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-pnx.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-* NXP PNX I2C Controller
-
-Required properties:
-
- - reg: Offset and length of the register set for the device
- - compatible: should be "nxp,pnx-i2c"
- - interrupts: configure one interrupt line
- - #address-cells: always 1 (for i2c addresses)
- - #size-cells: always 0
-
-Optional properties:
-
- - clock-frequency: desired I2C bus clock frequency in Hz, Default: 100000 Hz
-
-Examples:
-
- i2c1: i2c@400a0000 {
- compatible = "nxp,pnx-i2c";
- reg = <0x400a0000 0x100>;
- interrupt-parent = <&mic>;
- interrupts = <51 0>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
-
- i2c2: i2c@400a8000 {
- compatible = "nxp,pnx-i2c";
- reg = <0x400a8000 0x100>;
- interrupt-parent = <&mic>;
- interrupts = <50 0>;
- #address-cells = <1>;
- #size-cells = <0>;
- clock-frequency = <100000>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml
index 015885dd02d3..e89ee361741e 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/i2c/i2c-pxa.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Marvell MMP I2C controller bindings
+title: Marvell MMP I2C controller
maintainers:
- - Rob Herring <robh+dt@kernel.org>
+ - Rob Herring <robh@kernel.org>
allOf:
- $ref: /schemas/i2c/i2c-controller.yaml#
diff --git a/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt b/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt
deleted file mode 100644
index 7b9fc0c22eaf..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-qcom-cci.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-Qualcomm Camera Control Interface (CCI) I2C controller
-
-PROPERTIES:
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,msm8916-cci"
- "qcom,msm8996-cci"
- "qcom,sdm845-cci"
- "qcom,sm8250-cci"
-
-- reg
- Usage: required
- Value type: <prop-encoded-array>
- Definition: base address CCI I2C controller and length of memory
- mapped region.
-
-- interrupts:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: specifies the CCI I2C interrupt. The format of the
- specifier is defined by the binding document describing
- the node's interrupt parent.
-
-- clocks:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: a list of phandle, should contain an entry for each
- entries in clock-names.
-
-- clock-names
- Usage: required
- Value type: <string>
- Definition: a list of clock names, must include "cci" clock.
-
-- power-domains
- Usage: required for "qcom,msm8996-cci"
- Value type: <prop-encoded-array>
- Definition:
-
-SUBNODES:
-
-The CCI provides I2C masters for one (msm8916) or two i2c busses (msm8996,
-sdm845 and sm8250), described as subdevices named "i2c-bus@0" and "i2c-bus@1".
-
-PROPERTIES:
-
-- reg:
- Usage: required
- Value type: <u32>
- Definition: Index of the CCI bus/master
-
-- clock-frequency:
- Usage: optional
- Value type: <u32>
- Definition: Desired I2C bus clock frequency in Hz, defaults to 100
- kHz if omitted.
-
-Example:
-
- cci@a0c000 {
- compatible = "qcom,msm8996-cci";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0xa0c000 0x1000>;
- interrupts = <GIC_SPI 295 IRQ_TYPE_EDGE_RISING>;
- clocks = <&mmcc MMSS_MMAGIC_AHB_CLK>,
- <&mmcc CAMSS_TOP_AHB_CLK>,
- <&mmcc CAMSS_CCI_AHB_CLK>,
- <&mmcc CAMSS_CCI_CLK>,
- <&mmcc CAMSS_AHB_CLK>;
- clock-names = "mmss_mmagic_ahb",
- "camss_top_ahb",
- "cci_ahb",
- "cci",
- "camss_ahb";
-
- i2c-bus@0 {
- reg = <0>;
- clock-frequency = <400000>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
-
- i2c-bus@1 {
- reg = <1>;
- clock-frequency = <400000>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml b/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml
index 5339dd4fc370..91805fe8f393 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-rk3x.yaml
@@ -29,6 +29,7 @@ properties:
- items:
- enum:
- rockchip,rk3036-i2c
+ - rockchip,rk3128-i2c
- rockchip,rk3368-i2c
- const: rockchip,rk3288-i2c
- items:
@@ -36,7 +37,13 @@ properties:
- rockchip,px30-i2c
- rockchip,rk3308-i2c
- rockchip,rk3328-i2c
+ - rockchip,rk3506-i2c
+ - rockchip,rk3528-i2c
+ - rockchip,rk3562-i2c
- rockchip,rk3568-i2c
+ - rockchip,rk3576-i2c
+ - rockchip,rk3588-i2c
+ - rockchip,rv1126-i2c
- const: rockchip,rk3399-i2c
reg:
@@ -99,6 +106,9 @@ properties:
(t(f) in the I2C specification). If not specified we will use the SCL
value since they are the same in nearly all cases.
+ power-domains:
+ maxItems: 1
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt b/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt
deleted file mode 100644
index 66ae46d3bc2f..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-* Samsung's I2C controller
-
-The Samsung's I2C controller is used to interface with I2C devices.
-
-Required properties:
- - compatible: value should be either of the following.
- (a) "samsung, s3c2410-i2c", for i2c compatible with s3c2410 i2c.
- (b) "samsung, s3c2440-i2c", for i2c compatible with s3c2440 i2c.
- (c) "samsung, s3c2440-hdmiphy-i2c", for s3c2440-like i2c used
- inside HDMIPHY block found on several samsung SoCs
- (d) "samsung, exynos5-sata-phy-i2c", for s3c2440-like i2c used as
- a host to SATA PHY controller on an internal bus.
- - reg: physical base address of the controller and length of memory mapped
- region.
- - interrupts: interrupt number to the cpu.
- - samsung,i2c-sda-delay: Delay (in ns) applied to data line (SDA) edges.
-
-Required for all cases except "samsung,s3c2440-hdmiphy-i2c":
- - Samsung GPIO variant (deprecated):
- - gpios: The order of the gpios should be the following: <SDA, SCL>.
- The gpio specifier depends on the gpio controller. Required in all
- cases except for "samsung,s3c2440-hdmiphy-i2c" whose input/output
- lines are permanently wired to the respective clienta
- - Pinctrl variant (preferred, if available):
- - pinctrl-0: Pin control group to be used for this controller.
- - pinctrl-names: Should contain only one value - "default".
-
-Optional properties:
- - samsung,i2c-slave-addr: Slave address in multi-master environment. If not
- specified, default value is 0.
- - samsung,i2c-max-bus-freq: Desired frequency in Hz of the bus. If not
- specified, the default value in Hz is 100000.
- - samsung,sysreg-phandle - handle to syscon used to control the system registers
-
-Example:
-
- i2c@13870000 {
- compatible = "samsung,s3c2440-i2c";
- reg = <0x13870000 0x100>;
- interrupts = <345>;
- samsung,i2c-sda-delay = <100>;
- samsung,i2c-max-bus-freq = <100000>;
- /* Samsung GPIO variant begins here */
- gpios = <&gpd1 2 0 /* SDA */
- &gpd1 3 0 /* SCL */>;
- /* Samsung GPIO variant ends here */
- /* Pinctrl variant begins here */
- pinctrl-0 = <&i2c3_bus>;
- pinctrl-names = "default";
- /* Pinctrl variant ends here */
- #address-cells = <1>;
- #size-cells = <0>;
-
- wm8994@1a {
- compatible = "wlf,wm8994";
- reg = <0x1a>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-sprd.txt b/Documentation/devicetree/bindings/i2c/i2c-sprd.txt
deleted file mode 100644
index 60b7cda15dd2..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-sprd.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-I2C for Spreadtrum platforms
-
-Required properties:
-- compatible: Should be "sprd,sc9860-i2c".
-- reg: Specify the physical base address of the controller and length
- of memory mapped region.
-- interrupts: Should contain I2C interrupt.
-- clock-names: Should contain following entries:
- "i2c" for I2C clock,
- "source" for I2C source (parent) clock,
- "enable" for I2C module enable clock.
-- clocks: Should contain a clock specifier for each entry in clock-names.
-- clock-frequency: Constains desired I2C bus clock frequency in Hz.
-- #address-cells: Should be 1 to describe address cells for I2C device address.
-- #size-cells: Should be 0 means no size cell for I2C device address.
-
-Optional properties:
-- Child nodes conforming to I2C bus binding
-
-Examples:
-i2c0: i2c@70500000 {
- compatible = "sprd,sc9860-i2c";
- reg = <0 0x70500000 0 0x1000>;
- interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
- clock-names = "i2c", "source", "enable";
- clocks = <&clk_i2c3>, <&ext_26m>, <&clk_ap_apb_gates 11>;
- clock-frequency = <400000>;
- #address-cells = <1>;
- #size-cells = <0>;
-};
-
diff --git a/Documentation/devicetree/bindings/i2c/i2c-st.txt b/Documentation/devicetree/bindings/i2c/i2c-st.txt
deleted file mode 100644
index 4c26fda3844a..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-st.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-ST SSC binding, for I2C mode operation
-
-Required properties :
-- compatible : Must be "st,comms-ssc-i2c" or "st,comms-ssc4-i2c"
-- reg : Offset and length of the register set for the device
-- interrupts : the interrupt specifier
-- clock-names: Must contain "ssc".
-- clocks: Must contain an entry for each name in clock-names. See the common
- clock bindings.
-- A pinctrl state named "default" must be defined to set pins in mode of
- operation for I2C transfer.
-
-Optional properties :
-- clock-frequency : Desired I2C bus clock frequency in Hz. If not specified,
- the default 100 kHz frequency will be used. As only Normal and Fast modes
- are supported, possible values are 100000 and 400000.
-- st,i2c-min-scl-pulse-width-us : The minimum valid SCL pulse width that is
- allowed through the deglitch circuit. In units of us.
-- st,i2c-min-sda-pulse-width-us : The minimum valid SDA pulse width that is
- allowed through the deglitch circuit. In units of us.
-- A pinctrl state named "idle" could be defined to set pins in idle state
- when I2C instance is not performing a transfer.
-- A pinctrl state named "sleep" could be defined to set pins in sleep state
- when driver enters in suspend.
-
-
-
-Example :
-
-i2c0: i2c@fed40000 {
- compatible = "st,comms-ssc4-i2c";
- reg = <0xfed40000 0x110>;
- interrupts = <GIC_SPI 187 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&clk_s_a0_ls CLK_ICN_REG>;
- clock-names = "ssc";
- clock-frequency = <400000>;
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_i2c0_default>;
- st,i2c-min-scl-pulse-width-us = <0>;
- st,i2c-min-sda-pulse-width-us = <5>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt b/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt
deleted file mode 100644
index 72f4a2f0fedc..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-Socionext SynQuacer I2C
-
-Required properties:
-- compatible : Must be "socionext,synquacer-i2c"
-- reg : Offset and length of the register set for the device
-- interrupts : A single interrupt specifier
-- #address-cells : Must be <1>;
-- #size-cells : Must be <0>;
-- clock-names : Must contain "pclk".
-- clocks : Must contain an entry for each name in clock-names.
- (See the common clock bindings.)
-
-Optional properties:
-- clock-frequency : Desired I2C bus clock frequency in Hz. As only Normal and
- Fast modes are supported, possible values are 100000 and
- 400000.
-
-Example :
-
- i2c@51210000 {
- compatible = "socionext,synquacer-i2c";
- reg = <0x51210000 0x1000>;
- interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>;
- #address-cells = <1>;
- #size-cells = <0>;
- clock-names = "pclk";
- clocks = <&clk_i2c>;
- clock-frequency = <400000>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-versatile.txt b/Documentation/devicetree/bindings/i2c/i2c-versatile.txt
deleted file mode 100644
index 361d31c51b6f..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-versatile.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-i2c Controller on ARM Versatile platform:
-
-Required properties:
-- compatible : Must be "arm,versatile-i2c";
-- reg
-- #address-cells = <1>;
-- #size-cells = <0>;
-
-Optional properties:
-- Child nodes conforming to i2c bus binding
diff --git a/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml b/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml
new file mode 100644
index 000000000000..7d87ed855301
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-virtio.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/i2c-virtio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Virtio I2C Adapter
+
+maintainers:
+ - Viresh Kumar <viresh.kumar@linaro.org>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - $ref: /schemas/virtio/virtio-device.yaml#
+
+description:
+ Virtio I2C device, see /schemas/virtio/virtio-device.yaml for more details.
+
+properties:
+ $nodename:
+ const: i2c
+
+ compatible:
+ const: virtio,device22
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ virtio@3000 {
+ compatible = "virtio,mmio";
+ reg = <0x3000 0x100>;
+ interrupts = <41>;
+
+ i2c {
+ compatible = "virtio,device22";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@20 {
+ compatible = "dynaimage,al3320a";
+ reg = <0x20>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/i2c/i2c-wmt.txt b/Documentation/devicetree/bindings/i2c/i2c-wmt.txt
deleted file mode 100644
index 94a425eaa6c7..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-wmt.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-* Wondermedia I2C Controller
-
-Required properties :
-
- - compatible : should be "wm,wm8505-i2c"
- - reg : Offset and length of the register set for the device
- - interrupts : <IRQ> where IRQ is the interrupt number
- - clocks : phandle to the I2C clock source
-
-Optional properties :
-
- - clock-frequency : desired I2C bus clock frequency in Hz.
- Valid values are 100000 and 400000.
- Default to 100000 if not specified, or invalid value.
-
-Example :
-
- i2c_0: i2c@d8280000 {
- compatible = "wm,wm8505-i2c";
- reg = <0xd8280000 0x1000>;
- interrupts = <19>;
- clocks = <&clki2c0>;
- clock-frequency = <400000>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-xgene-slimpro.txt b/Documentation/devicetree/bindings/i2c/i2c-xgene-slimpro.txt
deleted file mode 100644
index f6b2c20cfbf6..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-xgene-slimpro.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-APM X-Gene SLIMpro Mailbox I2C Driver
-
-An I2C controller accessed over the "SLIMpro" mailbox.
-
-Required properties :
-
- - compatible : should be "apm,xgene-slimpro-i2c"
- - mboxes : use the label reference for the mailbox as the first parameter.
- The second parameter is the channel number.
-
-Example :
- i2cslimpro {
- compatible = "apm,xgene-slimpro-i2c";
- mboxes = <&mailbox 0>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-xlp9xx.txt b/Documentation/devicetree/bindings/i2c/i2c-xlp9xx.txt
deleted file mode 100644
index f818ef507ab7..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c-xlp9xx.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Device tree configuration for the I2C controller on the XLP9xx/5xx SoC
-
-Required properties:
-- compatible : should be "netlogic,xlp980-i2c"
-- reg : bus address start and address range size of device
-- interrupts : interrupt number
-
-Optional properties:
-- clock-frequency : frequency of bus clock in Hz
- Defaults to 100 KHz when the property is not specified
-
-Example:
-
-i2c0: i2c@113100 {
- compatible = "netlogic,xlp980-i2c";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0 0x113100 0x100>;
- clock-frequency = <400000>;
- interrupts = <30>;
- interrupt-parent = <&pic>;
-};
diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt
deleted file mode 100644
index b864916e087f..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c.txt
+++ /dev/null
@@ -1,147 +0,0 @@
-Generic device tree bindings for I2C busses
-===========================================
-
-This document describes generic bindings which can be used to describe I2C
-busses and their child devices in a device tree.
-
-Required properties (per bus)
------------------------------
-
-- #address-cells - should be <1>. Read more about addresses below.
-- #size-cells - should be <0>.
-- compatible - name of I2C bus controller
-
-For other required properties e.g. to describe register sets,
-clocks, etc. check the binding documentation of the specific driver.
-
-The cells properties above define that an address of children of an I2C bus
-are described by a single value.
-
-Optional properties (per bus)
------------------------------
-
-These properties may not be supported by all drivers. However, if a driver
-wants to support one of the below features, it should adapt these bindings.
-
-- clock-frequency
- frequency of bus clock in Hz.
-
-- i2c-bus
- For I2C adapters that have child nodes that are a mixture of both I2C
- devices and non-I2C devices, the 'i2c-bus' subnode can be used for
- populating I2C devices. If the 'i2c-bus' subnode is present, only
- subnodes of this will be considered as I2C slaves. The properties,
- '#address-cells' and '#size-cells' must be defined under this subnode
- if present.
-
-- i2c-scl-falling-time-ns
- Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
- specification.
-
-- i2c-scl-internal-delay-ns
- Number of nanoseconds the IP core additionally needs to setup SCL.
-
-- i2c-scl-rising-time-ns
- Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
- specification.
-
-- i2c-sda-falling-time-ns
- Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
- specification.
-
-- i2c-analog-filter
- Enable analog filter for i2c lines.
-
-- i2c-digital-filter
- Enable digital filter for i2c lines.
-
-- i2c-digital-filter-width-ns
- Width of spikes which can be filtered by digital filter
- (i2c-digital-filter). This width is specified in nanoseconds.
-
-- i2c-analog-filter-cutoff-frequency
- Frequency that the analog filter (i2c-analog-filter) uses to distinguish
- which signal to filter. Signal with higher frequency than specified will
- be filtered out. Only lower frequency will pass (this is applicable to
- a low-pass analog filter). Typical value should be above the normal
- i2c bus clock frequency (clock-frequency).
- Specified in Hz.
-
-- multi-master
- states that there is another master active on this bus. The OS can use
- this information to adapt power management to keep the arbitration awake
- all the time, for example. Can not be combined with 'single-master'.
-
-- pinctrl
- add extra pinctrl to configure SCL/SDA pins to GPIO function for bus
- recovery, call it "gpio" or "recovery" (deprecated) state
-
-- scl-gpios
- specify the gpio related to SCL pin. Used for GPIO bus recovery.
-
-- sda-gpios
- specify the gpio related to SDA pin. Optional for GPIO bus recovery.
-
-- single-master
- states that there is no other master active on this bus. The OS can use
- this information to detect a stalled bus more reliably, for example.
- Can not be combined with 'multi-master'.
-
-- smbus
- states that additional SMBus restrictions and features apply to this bus.
- An example of feature is SMBusHostNotify. Examples of restrictions are
- more reserved addresses and timeout definitions.
-
-- smbus-alert
- states that the optional SMBus-Alert feature apply to this bus.
-
-Required properties (per child device)
---------------------------------------
-
-- compatible
- name of I2C slave device
-
-- reg
- One or many I2C slave addresses. These are usually a 7 bit addresses.
- However, flags can be attached to an address. I2C_TEN_BIT_ADDRESS is
- used to mark a 10 bit address. It is needed to avoid the ambiguity
- between e.g. a 7 bit address of 0x50 and a 10 bit address of 0x050
- which, in theory, can be on the same bus.
- Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we
- listen to be devices ourselves.
-
-Optional properties (per child device)
---------------------------------------
-
-These properties may not be supported by all drivers. However, if a driver
-wants to support one of the below features, it should adapt these bindings.
-
-- host-notify
- device uses SMBus host notify protocol instead of interrupt line.
-
-- interrupts
- interrupts used by the device.
-
-- interrupt-names
- "irq", "wakeup" and "smbus_alert" names are recognized by I2C core,
- other names are left to individual drivers.
-
-- reg-names
- Names of map programmable addresses.
- It can contain any map needing another address than default one.
-
-- wakeup-source
- device can be used as a wakeup source.
-
-Binding may contain optional "interrupts" property, describing interrupts
-used by the device. I2C core will assign "irq" interrupt (or the very first
-interrupt if not using interrupt names) as primary interrupt for the slave.
-
-Alternatively, devices supporting SMBus Host Notify, and connected to
-adapters that support this feature, may use "host-notify" property. I2C
-core will create a virtual interrupt for Host Notify and assign it as
-primary interrupt for the slave.
-
-Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
-interrupt for the device. If "wakeup" interrupt name is not present in the
-binding, then primary interrupt will be used as wakeup interrupt.
diff --git a/Documentation/devicetree/bindings/i2c/ibm,i2c-fsi.yaml b/Documentation/devicetree/bindings/i2c/ibm,i2c-fsi.yaml
new file mode 100644
index 000000000000..40ea82942e4d
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/ibm,i2c-fsi.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/ibm,i2c-fsi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM FSI-attached I2C controller
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ This I2C controller is an FSI CFAM engine, providing access to a number of
+ I2C busses. Therefore this node will always be a child of an FSI CFAM node.
+
+properties:
+ compatible:
+ enum:
+ - ibm,i2c-fsi
+
+ reg:
+ items:
+ - description: FSI slave address
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^i2c-bus@[0-9a-f]+$":
+ type: object
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+ allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c@1800 {
+ compatible = "ibm,i2c-fsi";
+ reg = <0x1800 0x400>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c-bus@0 {
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+
+ i2c-bus@1 {
+ reg = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@50 {
+ compatible = "atmel,24c64";
+ reg = <0x50>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/ibm,p8-occ-hwmon.txt b/Documentation/devicetree/bindings/i2c/ibm,p8-occ-hwmon.txt
deleted file mode 100644
index 5dc5d2e2573d..000000000000
--- a/Documentation/devicetree/bindings/i2c/ibm,p8-occ-hwmon.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-Device-tree bindings for I2C-based On-Chip Controller hwmon device
-------------------------------------------------------------------
-
-Required properties:
- - compatible = "ibm,p8-occ-hwmon";
- - reg = <I2C address>; : I2C bus address
-
-Examples:
-
- i2c-bus@100 {
- #address-cells = <1>;
- #size-cells = <0>;
- clock-frequency = <100000>;
- < more properties >
-
- occ-hwmon@1 {
- compatible = "ibm,p8-occ-hwmon";
- reg = <0x50>;
- };
-
- occ-hwmon@2 {
- compatible = "ibm,p8-occ-hwmon";
- reg = <0x51>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml b/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml
index e1e65eb4f795..b61fdc9548d8 100644
--- a/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/ingenic,i2c.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i2c/ingenic,i2c.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Ingenic SoCs I2C controller devicetree bindings
+title: Ingenic SoCs I2C controller
maintainers:
- Paul Cercueil <paul@crapouillou.net>
@@ -60,7 +60,7 @@ unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/clock/jz4780-cgu.h>
+ #include <dt-bindings/clock/ingenic,jz4780-cgu.h>
#include <dt-bindings/dma/jz4780-dma.h>
#include <dt-bindings/interrupt-controller/irq.h>
i2c@10054000 {
@@ -69,8 +69,7 @@ examples:
#size-cells = <0>;
reg = <0x10054000 0x1000>;
- interrupt-parent = <&intc>;
- interrupts = <56>;
+ interrupts = <56 IRQ_TYPE_LEVEL_LOW>;
clocks = <&cgu JZ4780_CLK_SMB4>;
pinctrl-names = "default";
@@ -86,7 +85,6 @@ examples:
compatible = "nxp,pcf8563";
reg = <0x51>;
- interrupt-parent = <&gpf>;
interrupts = <30 IRQ_TYPE_LEVEL_LOW>;
};
};
diff --git a/Documentation/devicetree/bindings/i2c/loongson,ls2x-i2c.yaml b/Documentation/devicetree/bindings/i2c/loongson,ls2x-i2c.yaml
new file mode 100644
index 000000000000..67882ec6e06a
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/loongson,ls2x-i2c.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/loongson,ls2x-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson LS2X I2C Controller
+
+maintainers:
+ - Binbin Zhou <zhoubinbin@loongson.cn>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - loongson,ls2k-i2c
+ - loongson,ls7a-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c0: i2c@1fe21000 {
+ compatible = "loongson,ls2k-i2c";
+ reg = <0x1fe21000 0x8>;
+ interrupt-parent = <&extioiic>;
+ interrupts = <22 IRQ_TYPE_LEVEL_LOW>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@57 {
+ compatible = "atmel,24c16";
+ reg = <0x57>;
+ pagesize = <16>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
index f771c09aabfc..c4efcef59133 100644
--- a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i2c/marvell,mv64xxx-i2c.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Marvell MV64XXX I2C Controller Device Tree Bindings
+title: Marvell MV64XXX I2C Controller
maintainers:
- Gregory CLEMENT <gregory.clement@bootlin.com>
@@ -19,12 +19,22 @@ properties:
- const: allwinner,sun6i-a31-i2c
- items:
- enum:
+ - allwinner,suniv-f1c100s-i2c
- allwinner,sun8i-a23-i2c
- allwinner,sun8i-a83t-i2c
+ - allwinner,sun8i-v536-i2c
- allwinner,sun50i-a64-i2c
- - allwinner,sun50i-a100-i2c
- allwinner,sun50i-h6-i2c
+ - const: allwinner,sun6i-a31-i2c
+ - description: Allwinner SoCs with offload support
+ items:
+ - enum:
+ - allwinner,sun20i-d1-i2c
+ - allwinner,sun50i-a100-i2c
- allwinner,sun50i-h616-i2c
+ - allwinner,sun50i-r329-i2c
+ - allwinner,sun55i-a523-i2c
+ - const: allwinner,sun8i-v536-i2c
- const: allwinner,sun6i-a31-i2c
- const: marvell,mv64xxx-i2c
- const: marvell,mv78230-i2c
@@ -58,6 +68,19 @@ properties:
resets:
maxItems: 1
+ dmas:
+ items:
+ - description: RX DMA Channel
+ - description: TX DMA Channel
+
+ dma-names:
+ items:
+ - const: rx
+ - const: tx
+
+dependencies:
+ dmas: [ dma-names ]
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/i2c/mediatek,mt7621-i2c.yaml b/Documentation/devicetree/bindings/i2c/mediatek,mt7621-i2c.yaml
new file mode 100644
index 000000000000..118ec00fc190
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/mediatek,mt7621-i2c.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/mediatek,mt7621-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+maintainers:
+ - Stefan Roese <sr@denx.de>
+
+title: Mediatek MT7621/MT7628 I2C master controller
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: mediatek,mt7621-i2c
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: i2c
+
+ resets:
+ maxItems: 1
+
+ reset-names:
+ const: i2c
+
+required:
+ - compatible
+ - reg
+ - resets
+ - "#address-cells"
+ - "#size-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt7621-clk.h>
+ #include <dt-bindings/reset/mt7621-reset.h>
+
+ i2c: i2c@900 {
+ compatible = "mediatek,mt7621-i2c";
+ reg = <0x900 0x100>;
+ clocks = <&sysc MT7621_CLK_I2C>;
+ clock-names = "i2c";
+ resets = <&sysc MT7621_RST_I2C>;
+ reset-names = "i2c";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&i2c_pins>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.yaml b/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.yaml
deleted file mode 100644
index 93198d5d43a6..000000000000
--- a/Documentation/devicetree/bindings/i2c/mellanox,i2c-mlxbf.yaml
+++ /dev/null
@@ -1,77 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/i2c/mellanox,i2c-mlxbf.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Mellanox I2C SMBus on BlueField SoCs
-
-maintainers:
- - Khalil Blaiech <kblaiech@nvidia.com>
-
-allOf:
- - $ref: /schemas/i2c/i2c-controller.yaml#
-
-properties:
- compatible:
- enum:
- - mellanox,i2c-mlxbf1
- - mellanox,i2c-mlxbf2
-
- reg:
- minItems: 3
- items:
- - description: Smbus block registers
- - description: Cause master registers
- - description: Cause slave registers
- - description: Cause coalesce registers
-
- interrupts:
- maxItems: 1
-
- clock-frequency:
- enum: [ 100000, 400000, 1000000 ]
- description:
- bus frequency used to configure timing registers;
- The frequency is expressed in Hz. Default is 100000.
-
-required:
- - compatible
- - reg
- - interrupts
-
-unevaluatedProperties: false
-
-if:
- properties:
- compatible:
- contains:
- enum:
- - mellanox,i2c-mlxbf1
-
-then:
- properties:
- reg:
- maxItems: 3
-
-examples:
- - |
- i2c@2804000 {
- compatible = "mellanox,i2c-mlxbf1";
- reg = <0x02804000 0x800>,
- <0x02801200 0x020>,
- <0x02801260 0x020>;
- interrupts = <57>;
- clock-frequency = <100000>;
- };
-
- - |
- i2c@2808800 {
- compatible = "mellanox,i2c-mlxbf2";
- reg = <0x02808800 0x600>,
- <0x02808e00 0x020>,
- <0x02808e20 0x020>,
- <0x02808e40 0x010>;
- interrupts = <57>;
- clock-frequency = <400000>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/microchip,corei2c.yaml b/Documentation/devicetree/bindings/i2c/microchip,corei2c.yaml
new file mode 100644
index 000000000000..6ff58b64d496
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/microchip,corei2c.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/microchip,corei2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MPFS I2C Controller
+
+maintainers:
+ - Daire McNamara <daire.mcnamara@microchip.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - microchip,pic64gx-i2c
+ - microchip,mpfs-i2c # Microchip PolarFire SoC compatible SoCs
+ - const: microchip,corei2c-rtl-v7 # Microchip Fabric based i2c IP core
+ - const: microchip,corei2c-rtl-v7 # Microchip Fabric based i2c IP core
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ description: |
+ Desired I2C bus clock frequency in Hz. As only Standard and Fast
+ modes are supported, possible values are 100000 and 400000.
+ enum: [100000, 400000]
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@2010a000 {
+ compatible = "microchip,mpfs-i2c", "microchip,corei2c-rtl-v7";
+ reg = <0x2010a000 0x1000>;
+ clocks = <&clkcfg 15>;
+ interrupt-parent = <&plic>;
+ interrupts = <58>;
+ clock-frequency = <100000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml b/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml
index 128444942aec..00eb6ff6f5b1 100644
--- a/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/nuvoton,npcm7xx-i2c.yaml
@@ -4,20 +4,21 @@
$id: http://devicetree.org/schemas/i2c/nuvoton,npcm7xx-i2c.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: nuvoton NPCM7XX I2C Controller Device Tree Bindings
+title: nuvoton NPCM7XX I2C Controller
description: |
- The NPCM750x includes sixteen I2C bus controllers. All Controllers support
- both master and slave mode. Each controller can switch between master and slave
- at run time (i.e. IPMB mode). Each controller has two 16 byte HW FIFO for TX and
- RX.
+ I2C bus controllers of the NPCM series support both master and
+ slave mode. Each controller can switch between master and slave at run time
+ (i.e. IPMB mode). HW FIFO for TX and RX are supported.
maintainers:
- Tali Perry <tali.perry1@gmail.com>
properties:
compatible:
- const: nuvoton,npcm750-i2c
+ enum:
+ - nuvoton,npcm750-i2c
+ - nuvoton,npcm845-i2c
reg:
maxItems: 1
@@ -36,6 +37,10 @@ properties:
default: 100000
enum: [100000, 400000, 1000000]
+ nuvoton,sys-mgr:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: The phandle of system manager register node.
+
required:
- compatible
- reg
@@ -44,6 +49,15 @@ required:
allOf:
- $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: nuvoton,npcm845-i2c
+
+ then:
+ required:
+ - nuvoton,sys-mgr
unevaluatedProperties: false
@@ -57,6 +71,7 @@ examples:
clock-frequency = <100000>;
interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>;
compatible = "nuvoton,npcm750-i2c";
+ nuvoton,sys-mgr = <&gcr>;
};
...
diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt
deleted file mode 100644
index ab240e10debc..000000000000
--- a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt
+++ /dev/null
@@ -1,42 +0,0 @@
-NVIDIA Tegra186 BPMP I2C controller
-
-In Tegra186, the BPMP (Boot and Power Management Processor) owns certain HW
-devices, such as the I2C controller for the power management I2C bus. Software
-running on other CPUs must perform IPC to the BPMP in order to execute
-transactions on that I2C bus. This binding describes an I2C bus that is
-accessed in such a fashion.
-
-The BPMP I2C node must be located directly inside the main BPMP node. See
-../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding.
-
-This node represents an I2C controller. See ../i2c/i2c.txt for details of the
-core I2C binding.
-
-Required properties:
-- compatible:
- Array of strings.
- One of:
- - "nvidia,tegra186-bpmp-i2c".
-- #address-cells: Address cells for I2C device address.
- Single-cell integer.
- Must be <1>.
-- #size-cells:
- Single-cell integer.
- Must be <0>.
-- nvidia,bpmp-bus-id:
- Single-cell integer.
- Indicates the I2C bus number this DT node represent, as defined by the
- BPMP firmware.
-
-Example:
-
-bpmp {
- ...
-
- i2c {
- compatible = "nvidia,tegra186-bpmp-i2c";
- #address-cells = <1>;
- #size-cells = <0>;
- nvidia,bpmp-bus-id = <5>;
- };
-};
diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml
new file mode 100644
index 000000000000..8676335e9e94
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/nvidia,tegra186-bpmp-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra186 (and later) BPMP I2C controller
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+description: |
+ In Tegra186 and later, the BPMP (Boot and Power Management Processor)
+ owns certain HW devices, such as the I2C controller for the power
+ management I2C bus. Software running on other CPUs must perform IPC to
+ the BPMP in order to execute transactions on that I2C bus. This
+ binding describes an I2C bus that is accessed in such a fashion.
+
+ The BPMP I2C node must be located directly inside the main BPMP node.
+ See ../firmware/nvidia,tegra186-bpmp.yaml for details of the BPMP
+ binding.
+
+ This node represents an I2C controller.
+
+properties:
+ compatible:
+ const: nvidia,tegra186-bpmp-i2c
+
+ nvidia,bpmp-bus-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Indicates the I2C bus number this DT node represents,
+ as defined by the BPMP firmware.
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+ - nvidia,bpmp-bus-id
diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt
deleted file mode 100644
index 3f2f990c2e62..000000000000
--- a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt
+++ /dev/null
@@ -1,87 +0,0 @@
-NVIDIA Tegra20/Tegra30/Tegra114 I2C controller driver.
-
-Required properties:
-- compatible : For Tegra20, must be one of "nvidia,tegra20-i2c-dvc" or
- "nvidia,tegra20-i2c". For Tegra30, must be "nvidia,tegra30-i2c".
- For Tegra114, must be "nvidia,tegra114-i2c". Otherwise, must be
- "nvidia,<chip>-i2c", plus at least one of the above, where <chip> is
- tegra124, tegra132, or tegra210.
- Details of compatible are as follows:
- nvidia,tegra20-i2c-dvc: Tegra20 has specific I2C controller called as DVC I2C
- controller. This only support master mode of I2C communication. Register
- interface/offset and interrupts handling are different than generic I2C
- controller. Driver of DVC I2C controller is only compatible with
- "nvidia,tegra20-i2c-dvc".
- nvidia,tegra20-i2c: Tegra20 has 4 generic I2C controller. This can support
- master and slave mode of I2C communication. The i2c-tegra driver only
- support master mode of I2C communication. Driver of I2C controller is
- only compatible with "nvidia,tegra20-i2c".
- nvidia,tegra30-i2c: Tegra30 has 5 generic I2C controller. This controller is
- very much similar to Tegra20 I2C controller with additional feature:
- Continue Transfer Support. This feature helps to implement M_NO_START
- as per I2C core API transfer flags. Driver of I2C controller is
- compatible with "nvidia,tegra30-i2c" to enable the continue transfer
- support. This is also compatible with "nvidia,tegra20-i2c" without
- continue transfer support.
- nvidia,tegra114-i2c: Tegra114 has 5 generic I2C controller. This controller is
- very much similar to Tegra30 I2C controller with some hardware
- modification:
- - Tegra30/Tegra20 I2C controller has 2 clock source called div-clk and
- fast-clk. Tegra114 has only one clock source called as div-clk and
- hence clock mechanism is changed in I2C controller.
- - Tegra30/Tegra20 I2C controller has enabled per packet transfer by
- default and there is no way to disable it. Tegra114 has this
- interrupt disable by default and SW need to enable explicitly.
- Due to above changes, Tegra114 I2C driver makes incompatible with
- previous hardware driver. Hence, tegra114 I2C controller is compatible
- with "nvidia,tegra114-i2c".
- nvidia,tegra210-i2c-vi: Tegra210 has one I2C controller that is on host1x bus
- and is part of VE power domain and typically used for camera use-cases.
- This VI I2C controller is mostly compatible with the programming model
- of the regular I2C controllers with a few exceptions. The I2C registers
- start at an offset of 0xc00 (instead of 0), registers are 16 bytes
- apart (rather than 4) and the controller does not support slave mode.
-- reg: Should contain I2C controller registers physical address and length.
-- interrupts: Should contain I2C controller interrupts.
-- address-cells: Address cells for I2C device address.
-- size-cells: Size of the I2C device address.
-- clocks: Must contain an entry for each entry in clock-names.
- See ../clocks/clock-bindings.txt for details.
-- clock-names: Must include the following entries:
- Tegra20/Tegra30:
- - div-clk
- - fast-clk
- Tegra114:
- - div-clk
- Tegra210:
- - div-clk
- - slow (only for nvidia,tegra210-i2c-vi compatible node)
-- resets: Must contain an entry for each entry in reset-names.
- See ../reset/reset.txt for details.
-- reset-names: Must include the following entries:
- - i2c
-- power-domains: Only for nvidia,tegra210-i2c-vi compatible node and must
- include venc powergate node as vi i2c is part of VE power domain.
- tegra210-i2c-vi:
- - pd_venc
-- dmas: Must contain an entry for each entry in clock-names.
- See ../dma/dma.txt for details.
-- dma-names: Must include the following entries:
- - rx
- - tx
-
-Example:
-
- i2c@7000c000 {
- compatible = "nvidia,tegra20-i2c";
- reg = <0x7000c000 0x100>;
- interrupts = <0 38 0x04>;
- #address-cells = <1>;
- #size-cells = <0>;
- clocks = <&tegra_car 12>, <&tegra_car 124>;
- clock-names = "div-clk", "fast-clk";
- resets = <&tegra_car 12>;
- reset-names = "i2c";
- dmas = <&apbdma 16>, <&apbdma 16>;
- dma-names = "rx", "tx";
- };
diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml
new file mode 100644
index 000000000000..51241c1293e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.yaml
@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/nvidia,tegra20-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+title: NVIDIA Tegra I2C controller driver
+
+properties:
+ compatible:
+ oneOf:
+ - description: Tegra20 has 4 generic I2C controller. This can support
+ master and slave mode of I2C communication. The i2c-tegra driver
+ only support master mode of I2C communication. Driver of I2C
+ controller is only compatible with "nvidia,tegra20-i2c".
+ const: nvidia,tegra20-i2c
+ - description: Tegra20 has specific I2C controller called as DVC I2C
+ controller. This only support master mode of I2C communication.
+ Register interface/offset and interrupts handling are different than
+ generic I2C controller. Driver of DVC I2C controller is only
+ compatible with "nvidia,tegra20-i2c-dvc".
+ const: nvidia,tegra20-i2c-dvc
+ - description: |
+ Tegra30 has 5 generic I2C controller. This controller is very much
+ similar to Tegra20 I2C controller with additional feature: Continue
+ Transfer Support. This feature helps to implement M_NO_START as per
+ I2C core API transfer flags. Driver of I2C controller is compatible
+ with "nvidia,tegra30-i2c" to enable the continue transfer support.
+ This is also compatible with "nvidia,tegra20-i2c" without continue
+ transfer support.
+ items:
+ - const: nvidia,tegra30-i2c
+ - const: nvidia,tegra20-i2c
+ - description: |
+ Tegra114 has 5 generic I2C controllers. This controller is very much
+ similar to Tegra30 I2C controller with some hardware modification:
+ - Tegra30/Tegra20 I2C controller has 2 clock source called div-clk
+ and fast-clk. Tegra114 has only one clock source called as
+ div-clk and hence clock mechanism is changed in I2C controller.
+ - Tegra30/Tegra20 I2C controller has enabled per packet transfer
+ by default and there is no way to disable it. Tegra114 has this
+ interrupt disable by default and SW need to enable explicitly.
+ Due to above changes, Tegra114 I2C driver makes incompatible with
+ previous hardware driver. Hence, Tegra114 I2C controller is
+ compatible with "nvidia,tegra114-i2c".
+ const: nvidia,tegra114-i2c
+ - description: |
+ Tegra124 has 6 generic I2C controllers. These controllers are very
+ similar to those found on Tegra114 but also contain several hardware
+ improvements and new registers.
+ const: nvidia,tegra124-i2c
+ - description: |
+ Tegra210 has 6 generic I2C controllers. These controllers are very
+ similar to those found on Tegra124.
+ items:
+ - const: nvidia,tegra210-i2c
+ - const: nvidia,tegra124-i2c
+ - description: |
+ Tegra210 has one I2C controller that is on host1x bus and is part of
+ the VE power domain and typically used for camera use-cases. This VI
+ I2C controller is mostly compatible with the programming model of
+ the regular I2C controllers with a few exceptions. The I2C registers
+ start at an offset of 0xc00 (instead of 0), registers are 16 bytes
+ apart (rather than 4) and the controller does not support slave
+ mode.
+ const: nvidia,tegra210-i2c-vi
+ - description: |
+ Tegra186 has 9 generic I2C controllers, two of which are in the AON
+ (always-on) partition of the SoC. All of these controllers are very
+ similar to those found on Tegra210.
+ const: nvidia,tegra186-i2c
+ - description: |
+ Tegra194 has 8 generic I2C controllers, two of which are in the AON
+ (always-on) partition of the SoC. All of these controllers are very
+ similar to those found on Tegra186. However, these controllers have
+ support for 64 KiB transactions whereas earlier chips supported no
+ more than 4 KiB per transactions.
+ const: nvidia,tegra194-i2c
+ - description: |
+ Tegra256 has 8 generic I2C controllers. The controllers are similar to
+ the previous generations, but have a different parent clock and hence
+ the timing parameters are configured differently.
+ const: nvidia,tegra256-i2c
+ - description:
+ Tegra264 has 17 generic I2C controllers, two of which are in the AON
+ (always-on) partition of the SoC. In addition to the features from
+ Tegra194, a SW mutex register is added to support use of the same I2C
+ instance across multiple firmwares.
+ const: nvidia,tegra264-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+
+ resets:
+ items:
+ - description:
+ Module reset. This property is optional for controllers in Tegra194,
+ Tegra234 etc where an internal software reset is available as an
+ alternative.
+
+ reset-names:
+ items:
+ - const: i2c
+
+ power-domains:
+ maxItems: 1
+
+ dmas:
+ items:
+ - description: DMA channel for the reception FIFO
+ - description: DMA channel for the transmission FIFO
+
+ dma-names:
+ items:
+ - const: rx
+ - const: tx
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra20-i2c
+ - nvidia,tegra30-i2c
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ clock-names:
+ items:
+ - const: div-clk
+ - const: fast-clk
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra114-i2c
+ - nvidia,tegra210-i2c
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ items:
+ - const: div-clk
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: nvidia,tegra210-i2c-vi
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ clock-names:
+ items:
+ - const: div-clk
+ - const: slow
+ power-domains:
+ items:
+ - description: phandle to the VENC power domain
+ else:
+ properties:
+ power-domains: false
+
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nvidia,tegra194-i2c
+ - nvidia,tegra256-i2c
+ - nvidia,tegra264-i2c
+ then:
+ required:
+ - resets
+ - reset-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@7000c000 {
+ compatible = "nvidia,tegra20-i2c";
+ reg = <0x7000c000 0x100>;
+ interrupts = <0 38 0x04>;
+ clocks = <&tegra_car 12>, <&tegra_car 124>;
+ clock-names = "div-clk", "fast-clk";
+ resets = <&tegra_car 12>;
+ reset-names = "i2c";
+ dmas = <&apbdma 16>, <&apbdma 16>;
+ dma-names = "rx", "tx";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/nxp,lpc1788-i2c.yaml b/Documentation/devicetree/bindings/i2c/nxp,lpc1788-i2c.yaml
new file mode 100644
index 000000000000..9a1b95c2d03c
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/nxp,lpc1788-i2c.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/nxp,lpc1788-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP I2C controller for LPC2xxx/178x/18xx/43xx
+
+maintainers:
+ - Vladimir Zapolskiy <vz@mleia.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: nxp,lpc1788-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ description: the desired I2C bus clock frequency in Hz
+ default: 100000
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include "dt-bindings/clock/lpc18xx-ccu.h"
+
+ i2c@400a1000 {
+ compatible = "nxp,lpc1788-i2c";
+ reg = <0x400a1000 0x1000>;
+ interrupts = <18>;
+ clocks = <&ccu1 CLK_APB1_I2C0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt
deleted file mode 100644
index 42bfc09c8918..000000000000
--- a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-* NXP PCA9541 I2C bus master selector
-
-Required Properties:
-
- - compatible: Must be "nxp,pca9541"
-
- - reg: The I2C address of the device.
-
- The following required properties are defined externally:
-
- - I2C arbitration bus node. See i2c-arb.txt in this directory.
-
-
-Example:
-
- i2c-arbitrator@74 {
- compatible = "nxp,pca9541";
- reg = <0x74>;
-
- i2c-arb {
- #address-cells = <1>;
- #size-cells = <0>;
-
- eeprom@54 {
- compatible = "atmel,24c08";
- reg = <0x54>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml b/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml
new file mode 100644
index 000000000000..b65c25c1a435
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/nxp,pca9541.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PCA9541 I2C bus master selector
+
+maintainers:
+ - Peter Rosin <peda@axentia.se>
+
+properties:
+ compatible:
+ const: nxp,pca9541
+
+ reg:
+ maxItems: 1
+
+ i2c-arb:
+ type: object
+ $ref: /schemas/i2c/i2c-controller.yaml
+ unevaluatedProperties: false
+ description:
+ I2C arbitration bus node.
+
+required:
+ - compatible
+ - reg
+ - i2c-arb
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c-arbitrator@74 {
+ compatible = "nxp,pca9541";
+ reg = <0x74>;
+
+ i2c-arb {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ eeprom@54 {
+ compatible = "atmel,24c08";
+ reg = <0x54>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/nxp,pnx-i2c.yaml b/Documentation/devicetree/bindings/i2c/nxp,pnx-i2c.yaml
new file mode 100644
index 000000000000..e645784b77d3
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/nxp,pnx-i2c.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/nxp,pnx-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PNX I2C Controller
+
+maintainers:
+ - Animesh Agarwal <animeshagarwal28@gmail.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: nxp,pnx-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ default: 100000
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#address-cells"
+ - "#size-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@400a0000 {
+ compatible = "nxp,pnx-i2c";
+ reg = <0x400a0000 0x100>;
+ interrupt-parent = <&mic>;
+ interrupts = <51 0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml b/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml
new file mode 100644
index 000000000000..d9ef86729011
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/opencores,i2c-ocores.yaml
@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/opencores,i2c-ocores.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OpenCores I2C controller
+
+maintainers:
+ - Peter Korsgaard <peter@korsgaard.com>
+ - Andrew Lunn <andrew@lunn.ch>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - sifive,fu740-c000-i2c # Opencore based IP block FU740-C000 SoC
+ - sifive,fu540-c000-i2c # Opencore based IP block FU540-C000 SoC
+ - const: sifive,i2c0
+ - enum:
+ - opencores,i2c-ocores
+ - aeroflexgaisler,i2cmst
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ description: |
+ clock-frequency property is meant to control the bus frequency for i2c bus
+ drivers, but it was incorrectly used to specify i2c controller input clock
+ frequency. So the following rules are set to fix this situation:
+ - if clock-frequency is present and neither opencores,ip-clock-frequency nor
+ clocks are, then clock-frequency specifies i2c controller clock frequency.
+ This is to keep backwards compatibility with setups using old DTB. i2c bus
+ frequency is fixed at 100 KHz.
+ - if clocks is present it specifies i2c controller clock. clock-frequency
+ property specifies i2c bus frequency.
+ - if opencores,ip-clock-frequency is present it specifies i2c controller
+ clock frequency. clock-frequency property specifies i2c bus frequency.
+ default: 100000
+
+ reg-io-width:
+ description: |
+ io register width in bytes
+ enum: [1, 2, 4]
+
+ reg-shift:
+ description: |
+ device register offsets are shifted by this value
+ default: 0
+
+ regstep:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ deprecated, use reg-shift above
+ deprecated: true
+
+ opencores,ip-clock-frequency:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Frequency of the controller clock in Hz. Mutually exclusive with clocks.
+ See the note above.
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+oneOf:
+ - required:
+ - opencores,ip-clock-frequency
+ - required:
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@a0000000 {
+ compatible = "opencores,i2c-ocores";
+ reg = <0xa0000000 0x8>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ interrupts = <10>;
+ opencores,ip-clock-frequency = <20000000>;
+
+ reg-shift = <0>; /* 8 bit registers */
+ reg-io-width = <1>; /* 8 bit read/write */
+ };
+
+ i2c@b0000000 {
+ compatible = "opencores,i2c-ocores";
+ reg = <0xa0000000 0x8>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ interrupts = <10>;
+ clocks = <&osc>;
+ clock-frequency = <400000>; /* i2c bus frequency 400 KHz */
+
+ reg-shift = <0>; /* 8 bit registers */
+ reg-io-width = <1>; /* 8 bit read/write */
+ };
+...
diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml
new file mode 100644
index 000000000000..33852a5ffca8
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml
@@ -0,0 +1,367 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/qcom,i2c-cci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Camera Control Interface (CCI) I2C controller
+
+maintainers:
+ - Loic Poulain <loic.poulain@linaro.org>
+ - Robert Foss <robert.foss@linaro.org>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - qcom,msm8226-cci
+ - qcom,msm8953-cci
+ - qcom,msm8974-cci
+ - qcom,msm8996-cci
+
+ - items:
+ - enum:
+ - qcom,msm8916-cci
+ - const: qcom,msm8226-cci # CCI v1
+
+ - items:
+ - enum:
+ - qcom,kaanapali-cci
+ - qcom,qcm2290-cci
+ - qcom,sa8775p-cci
+ - qcom,sc7280-cci
+ - qcom,sc8280xp-cci
+ - qcom,sdm670-cci
+ - qcom,sdm845-cci
+ - qcom,sm6350-cci
+ - qcom,sm8250-cci
+ - qcom,sm8450-cci
+ - qcom,sm8550-cci
+ - qcom,sm8650-cci
+ - qcom,x1e80100-cci
+ - const: qcom,msm8996-cci # CCI v2
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ clocks:
+ minItems: 2
+ maxItems: 6
+
+ clock-names:
+ minItems: 2
+ maxItems: 6
+
+ interrupts:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+patternProperties:
+ "^i2c-bus@[01]$":
+ $ref: /schemas/i2c/i2c-controller.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ maxItems: 1
+
+ clock-frequency:
+ default: 100000
+
+required:
+ - compatible
+ - clock-names
+ - clocks
+ - interrupts
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8996-cci
+ then:
+ required:
+ - power-domains
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8226-cci
+ - qcom,msm8916-cci
+ then:
+ properties:
+ i2c-bus@1: false
+
+ - if:
+ properties:
+ compatible:
+ oneOf:
+ - contains:
+ enum:
+ - qcom,msm8974-cci
+
+ - const: qcom,msm8226-cci
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ maxItems: 3
+ clock-names:
+ items:
+ - const: camss_top_ahb
+ - const: cci_ahb
+ - const: cci
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,kaanapali-cci
+ - qcom,qcm2290-cci
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ maxItems: 2
+ clock-names:
+ items:
+ - const: ahb
+ - const: cci
+
+ - if:
+ properties:
+ compatible:
+ oneOf:
+ - contains:
+ enum:
+ - qcom,msm8916-cci
+ - qcom,msm8953-cci
+
+ - const: qcom,msm8996-cci
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: camss_top_ahb
+ - const: cci_ahb
+ - const: cci
+ - const: camss_ahb
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sdm670-cci
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: soc_ahb
+ - const: cpas_ahb
+ - const: cci
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sdm845-cci
+ - qcom,sm6350-cci
+ then:
+ properties:
+ clocks:
+ minItems: 6
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: soc_ahb
+ - const: slow_ahb_src
+ - const: cpas_ahb
+ - const: cci
+ - const: cci_src
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc7280-cci
+ - qcom,sm8250-cci
+ - qcom,sm8450-cci
+ then:
+ properties:
+ clocks:
+ minItems: 5
+ maxItems: 5
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: slow_ahb_src
+ - const: cpas_ahb
+ - const: cci
+ - const: cci_src
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc8280xp-cci
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: slow_ahb_src
+ - const: cpas_ahb
+ - const: cci
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sa8775p-cci
+ - qcom,sm8550-cci
+ - qcom,sm8650-cci
+ - qcom,x1e80100-cci
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ maxItems: 3
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: cpas_ahb
+ - const: cci
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,camcc-sdm845.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ cci@ac4a000 {
+ reg = <0x0ac4a000 0x4000>;
+ compatible = "qcom,sdm845-cci", "qcom,msm8996-cci";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ interrupts = <GIC_SPI 460 IRQ_TYPE_EDGE_RISING>;
+ power-domains = <&clock_camcc TITAN_TOP_GDSC>;
+
+ clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&clock_camcc CAM_CC_SOC_AHB_CLK>,
+ <&clock_camcc CAM_CC_SLOW_AHB_CLK_SRC>,
+ <&clock_camcc CAM_CC_CPAS_AHB_CLK>,
+ <&clock_camcc CAM_CC_CCI_CLK>,
+ <&clock_camcc CAM_CC_CCI_CLK_SRC>;
+ clock-names = "camnoc_axi",
+ "soc_ahb",
+ "slow_ahb_src",
+ "cpas_ahb",
+ "cci",
+ "cci_src";
+
+ assigned-clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&clock_camcc CAM_CC_CCI_CLK>;
+ assigned-clock-rates = <80000000>,
+ <37500000>;
+
+ pinctrl-names = "default", "sleep";
+ pinctrl-0 = <&cci0_default &cci1_default>;
+ pinctrl-1 = <&cci0_sleep &cci1_sleep>;
+
+ i2c-bus@0 {
+ reg = <0>;
+ clock-frequency = <1000000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@10 {
+ compatible = "ovti,ov8856";
+ reg = <0x10>;
+
+ reset-gpios = <&tlmm 9 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam0_default>;
+
+ clocks = <&clock_camcc CAM_CC_MCLK0_CLK>;
+ clock-names = "xvclk";
+ assigned-clocks = <&clock_camcc CAM_CC_MCLK0_CLK>;
+ assigned-clock-rates = <19200000>;
+
+ dovdd-supply = <&vreg_lvs1a_1p8>;
+ avdd-supply = <&cam0_avdd_2v8>;
+ dvdd-supply = <&cam0_dvdd_1v2>;
+
+ port {
+ ov8856_ep: endpoint {
+ link-frequencies = /bits/ 64 <360000000 180000000>;
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&csiphy0_ep>;
+ };
+ };
+ };
+ };
+
+ cci_i2c1: i2c-bus@1 {
+ reg = <1>;
+ clock-frequency = <1000000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@60 {
+ compatible = "ovti,ov7251";
+ reg = <0x60>;
+
+ enable-gpios = <&tlmm 21 GPIO_ACTIVE_HIGH>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam3_default>;
+
+ clocks = <&clock_camcc CAM_CC_MCLK3_CLK>;
+ clock-names = "xclk";
+ assigned-clocks = <&clock_camcc CAM_CC_MCLK3_CLK>;
+ assigned-clock-rates = <24000000>;
+
+ vdddo-supply = <&vreg_lvs1a_1p8>;
+ vdda-supply = <&cam3_avdd_2v8>;
+
+ port {
+ ov7251_ep: endpoint {
+ data-lanes = <0>;
+ link-frequencies = /bits/ 64 <240000000 319200000>;
+ remote-endpoint = <&csiphy3_ep>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml
new file mode 100644
index 000000000000..51534953a69c
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-geni-qcom.yaml
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/qcom,i2c-geni-qcom.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Geni based QUP I2C Controller
+
+maintainers:
+ - Andy Gross <agross@kernel.org>
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+properties:
+ compatible:
+ enum:
+ - qcom,geni-i2c
+ - qcom,geni-i2c-master-hub
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+
+ clock-frequency:
+ default: 100000
+
+ dmas:
+ maxItems: 2
+
+ dma-names:
+ items:
+ - const: tx
+ - const: rx
+
+ interconnects:
+ minItems: 2
+ maxItems: 3
+
+ interconnect-names:
+ minItems: 2
+ maxItems: 3
+
+ interrupts:
+ maxItems: 1
+
+ operating-points-v2: true
+
+ pinctrl-0: true
+ pinctrl-1: true
+
+ pinctrl-names:
+ minItems: 1
+ items:
+ - const: default
+ - const: sleep
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ required-opps:
+ maxItems: 1
+
+required:
+ - compatible
+ - interrupts
+ - clocks
+ - clock-names
+ - reg
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - $ref: /schemas/soc/qcom/qcom,se-common-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,geni-i2c-master-hub
+ then:
+ properties:
+ clocks:
+ minItems: 2
+
+ clock-names:
+ items:
+ - const: se
+ - const: core
+
+ dmas: false
+ dma-names: false
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: qup-core
+ - const: qup-config
+ else:
+ properties:
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: se
+
+ interconnects:
+ minItems: 3
+
+ interconnect-names:
+ items:
+ - const: qup-core
+ - const: qup-config
+ - const: qup-memory
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,gcc-sc7180.h>
+ #include <dt-bindings/interconnect/qcom,sc7180.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ i2c@88000 {
+ compatible = "qcom,geni-i2c";
+ reg = <0x00880000 0x4000>;
+ clock-names = "se";
+ clocks = <&gcc GCC_QUPV3_WRAP0_S0_CLK>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&qup_i2c0_default>;
+ interrupts = <GIC_SPI 601 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ interconnects = <&qup_virt MASTER_QUP_CORE_0 0 &qup_virt SLAVE_QUP_CORE_0 0>,
+ <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_QUP_0 0>,
+ <&aggre1_noc MASTER_QUP_0 0 &mc_virt SLAVE_EBI1 0>;
+ interconnect-names = "qup-core", "qup-config", "qup-memory";
+ power-domains = <&rpmhpd SC7180_CX>;
+ required-opps = <&rpmhpd_opp_low_svs>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-qup.txt b/Documentation/devicetree/bindings/i2c/qcom,i2c-qup.txt
deleted file mode 100644
index dc71754a56af..000000000000
--- a/Documentation/devicetree/bindings/i2c/qcom,i2c-qup.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-Qualcomm Universal Peripheral (QUP) I2C controller
-
-Required properties:
- - compatible: Should be:
- * "qcom,i2c-qup-v1.1.1" for 8660, 8960 and 8064.
- * "qcom,i2c-qup-v2.1.1" for 8974 v1.
- * "qcom,i2c-qup-v2.2.1" for 8974 v2 and later.
- - reg: Should contain QUP register address and length.
- - interrupts: Should contain I2C interrupt.
-
- - clocks: A list of phandles + clock-specifiers, one for each entry in
- clock-names.
- - clock-names: Should contain:
- * "core" for the core clock
- * "iface" for the AHB clock
-
- - #address-cells: Should be <1> Address cells for i2c device address
- - #size-cells: Should be <0> as i2c addresses have no size component
-
-Optional properties:
- - clock-frequency: Should specify the desired i2c bus clock frequency in Hz,
- defaults to 100kHz if omitted.
-
-Child nodes should conform to i2c bus binding.
-
-Example:
-
- i2c@f9924000 {
- compatible = "qcom,i2c-qup-v2.2.1";
- reg = <0xf9924000 0x1000>;
- interrupts = <0 96 0>;
-
- clocks = <&gcc GCC_BLSP1_QUP2_I2C_APPS_CLK>, <&gcc GCC_BLSP1_AHB_CLK>;
- clock-names = "core", "iface";
-
- clock-frequency = <355000>;
-
- #address-cells = <1>;
- #size-cells = <0>;
- };
diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-qup.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-qup.yaml
new file mode 100644
index 000000000000..06a04db3eda2
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-qup.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/qcom,i2c-qup.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Universal Peripheral (QUP) I2C controller
+
+maintainers:
+ - Andy Gross <agross@kernel.org>
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - qcom,i2c-qup-v1.1.1 # for 8660, 8960 and 8064
+ - qcom,i2c-qup-v2.1.1 # for 8974 v1
+ - qcom,i2c-qup-v2.2.1 # for 8974 v2 and later
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: core
+ - const: iface
+
+ clock-frequency:
+ default: 100000
+
+ dmas:
+ maxItems: 2
+
+ dma-names:
+ items:
+ - const: tx
+ - const: rx
+
+ interconnects:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ pinctrl-0: true
+ pinctrl-1: true
+
+ pinctrl-names:
+ minItems: 1
+ items:
+ - const: default
+ - const: sleep
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ required-opps:
+ maxItems: 1
+
+required:
+ - compatible
+ - clock-names
+ - clocks
+ - interrupts
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-msm8998.h>
+ #include <dt-bindings/interconnect/qcom,msm8996.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ i2c@c175000 {
+ compatible = "qcom,i2c-qup-v2.2.1";
+ reg = <0x0c175000 0x600>;
+ interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>;
+
+ clocks = <&gcc GCC_BLSP1_QUP1_I2C_APPS_CLK>,
+ <&gcc GCC_BLSP1_AHB_CLK>;
+ clock-names = "core", "iface";
+ dmas = <&blsp1_dma 6>, <&blsp1_dma 7>;
+ dma-names = "tx", "rx";
+ pinctrl-names = "default", "sleep";
+ pinctrl-0 = <&blsp1_i2c1_default>;
+ pinctrl-1 = <&blsp1_i2c1_sleep>;
+ power-domains = <&rpmpd MSM8909_VDDCX>;
+ required-opps = <&rpmpd_opp_svs_krait>;
+ interconnects = <&pnoc MASTER_BLSP_1 &bimc SLAVE_EBI_CH0>;
+ clock-frequency = <400000>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/realtek,rtl9301-i2c.yaml b/Documentation/devicetree/bindings/i2c/realtek,rtl9301-i2c.yaml
new file mode 100644
index 000000000000..f9a449fee2b0
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/realtek,rtl9301-i2c.yaml
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/realtek,rtl9301-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek RTL I2C Controller
+
+maintainers:
+ - Chris Packham <chris.packham@alliedtelesis.co.nz>
+
+description:
+ RTL9300 SoCs have two I2C controllers. Each of these has an SCL line (which
+ if not-used for SCL can be a GPIO). There are 8 common SDA lines that can be
+ assigned to either I2C controller.
+ RTL9310 SoCs have equal capabilities but support 12 common SDA lines which
+ can be assigned to either I2C controller.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - realtek,rtl9302b-i2c
+ - realtek,rtl9302c-i2c
+ - realtek,rtl9303-i2c
+ - const: realtek,rtl9301-i2c
+ - items:
+ - enum:
+ - realtek,rtl9311-i2c
+ - realtek,rtl9312-i2c
+ - realtek,rtl9313-i2c
+ - const: realtek,rtl9310-i2c
+ - enum:
+ - realtek,rtl9301-i2c
+ - realtek,rtl9310-i2c
+
+ reg:
+ items:
+ - description: Register offset and size of this I2C controller.
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ realtek,scl:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The SCL line number of this I2C controller.
+ enum: [ 0, 1 ]
+
+patternProperties:
+ '^i2c@[0-9ab]$':
+ $ref: /schemas/i2c/i2c-controller.yaml
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: The SDA line number associated with the I2C bus.
+ maxItems: 1
+
+ required:
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: realtek,rtl9310-i2c
+ then:
+ required:
+ - realtek,scl
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: realtek,rtl9301-i2c
+ then:
+ patternProperties:
+ '^i2c@[89ab]$': false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c@36c {
+ compatible = "realtek,rtl9301-i2c";
+ reg = <0x36c 0x14>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c@2 {
+ reg = <2>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/renesas,iic-emev2.yaml b/Documentation/devicetree/bindings/i2c/renesas,iic-emev2.yaml
index 17c1102562be..551cfa6f885a 100644
--- a/Documentation/devicetree/bindings/i2c/renesas,iic-emev2.yaml
+++ b/Documentation/devicetree/bindings/i2c/renesas,iic-emev2.yaml
@@ -44,11 +44,11 @@ examples:
#include <dt-bindings/interrupt-controller/arm-gic.h>
iic0: i2c@e0070000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "renesas,iic-emev2";
- reg = <0xe0070000 0x28>;
- interrupts = <GIC_SPI 32 IRQ_TYPE_EDGE_RISING>;
- clocks = <&iic0_sclk>;
- clock-names = "sclk";
+ compatible = "renesas,iic-emev2";
+ reg = <0xe0070000 0x28>;
+ interrupts = <GIC_SPI 32 IRQ_TYPE_EDGE_RISING>;
+ clocks = <&iic0_sclk>;
+ clock-names = "sclk";
+ #address-cells = <1>;
+ #size-cells = <0>;
};
diff --git a/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml b/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml
index 052aad44e781..6cc60c3f61cd 100644
--- a/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml
@@ -46,9 +46,16 @@ properties:
- renesas,i2c-r8a77980 # R-Car V3H
- renesas,i2c-r8a77990 # R-Car E3
- renesas,i2c-r8a77995 # R-Car D3
- - renesas,i2c-r8a779a0 # R-Car V3U
- const: renesas,rcar-gen3-i2c # R-Car Gen3 and RZ/G2
+ - items:
+ - enum:
+ - renesas,i2c-r8a779a0 # R-Car V3U
+ - renesas,i2c-r8a779f0 # R-Car S4-8
+ - renesas,i2c-r8a779g0 # R-Car V4H
+ - renesas,i2c-r8a779h0 # R-Car V4M
+ - const: renesas,rcar-gen4-i2c # R-Car Gen4
+
reg:
maxItems: 1
@@ -132,6 +139,7 @@ allOf:
enum:
- renesas,rcar-gen2-i2c
- renesas,rcar-gen3-i2c
+ - renesas,rcar-gen4-i2c
then:
required:
- resets
@@ -145,14 +153,14 @@ examples:
#include <dt-bindings/power/r8a7791-sysc.h>
i2c0: i2c@e6508000 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "renesas,i2c-r8a7791", "renesas,rcar-gen2-i2c";
- reg = <0xe6508000 0x40>;
- interrupts = <GIC_SPI 287 IRQ_TYPE_LEVEL_HIGH>;
- clock-frequency = <400000>;
- clocks = <&cpg CPG_MOD 931>;
- power-domains = <&sysc R8A7791_PD_ALWAYS_ON>;
- resets = <&cpg 931>;
- i2c-scl-internal-delay-ns = <6>;
+ compatible = "renesas,i2c-r8a7791", "renesas,rcar-gen2-i2c";
+ reg = <0xe6508000 0x40>;
+ interrupts = <GIC_SPI 287 IRQ_TYPE_LEVEL_HIGH>;
+ clock-frequency = <400000>;
+ clocks = <&cpg CPG_MOD 931>;
+ power-domains = <&sysc R8A7791_PD_ALWAYS_ON>;
+ resets = <&cpg 931>;
+ i2c-scl-internal-delay-ns = <6>;
+ #address-cells = <1>;
+ #size-cells = <0>;
};
diff --git a/Documentation/devicetree/bindings/i2c/renesas,riic.yaml b/Documentation/devicetree/bindings/i2c/renesas,riic.yaml
index 52d92ec7ec0b..6876eade431b 100644
--- a/Documentation/devicetree/bindings/i2c/renesas,riic.yaml
+++ b/Documentation/devicetree/bindings/i2c/renesas,riic.yaml
@@ -10,31 +10,69 @@ maintainers:
- Chris Brandt <chris.brandt@renesas.com>
- Wolfram Sang <wsa+renesas@sang-engineering.com>
-allOf:
- - $ref: /schemas/i2c/i2c-controller.yaml#
-
properties:
compatible:
- items:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,riic-r7s72100 # RZ/A1H
+ - renesas,riic-r7s9210 # RZ/A2M
+ - renesas,riic-r9a07g043 # RZ/G2UL and RZ/Five
+ - renesas,riic-r9a07g044 # RZ/G2{L,LC}
+ - renesas,riic-r9a07g054 # RZ/V2L
+ - const: renesas,riic-rz # RZ/A or RZ/G2L
+
+ - items:
+ - enum:
+ - renesas,riic-r9a08g045 # RZ/G3S
+ - renesas,riic-r9a09g047 # RZ/G3E
+ - renesas,riic-r9a09g056 # RZ/V2N
+ - const: renesas,riic-r9a09g057 # RZ/V2H(P)
+
- enum:
- - renesas,riic-r7s72100 # RZ/A1H
- - renesas,riic-r7s9210 # RZ/A2M
- - renesas,riic-r9a07g044 # RZ/G2{L,LC}
- - const: renesas,riic-rz # RZ/A or RZ/G2L
+ - renesas,riic-r9a09g057 # RZ/V2H(P)
+ - renesas,riic-r9a09g077 # RZ/T2H
+
+ - items:
+ - const: renesas,riic-r9a09g087 # RZ/N2H
+ - const: renesas,riic-r9a09g077 # RZ/T2H
reg:
maxItems: 1
interrupts:
- items:
- - description: Transmit End Interrupt (TEI)
- - description: Receive Data Full Interrupt (RI)
- - description: Transmit Data Empty Interrupt (TI)
- - description: Stop Condition Detection Interrupt (SPI)
- - description: Start Condition Detection Interrupt (STI)
- - description: NACK Reception Interrupt (NAKI)
- - description: Arbitration-Lost Interrupt (ALI)
- - description: Timeout Interrupt (TMOI)
+ oneOf:
+ - items:
+ - description: Transmit End Interrupt
+ - description: Receive Data Full Interrupt
+ - description: Transmit Data Empty Interrupt
+ - description: Stop Condition Detection Interrupt
+ - description: Start Condition Detection Interrupt
+ - description: NACK Reception Interrupt
+ - description: Arbitration-Lost Interrupt
+ - description: Timeout Interrupt
+ - items:
+ - description: Transfer Error Or Event Generation
+ - description: Receive Data Full Interrupt
+ - description: Transmit Data Empty Interrupt
+ - description: Transmit End Interrupt
+
+ interrupt-names:
+ oneOf:
+ - items:
+ - const: tei
+ - const: ri
+ - const: ti
+ - const: spi
+ - const: sti
+ - const: naki
+ - const: ali
+ - const: tmoi
+ - items:
+ - const: eei
+ - const: rxi
+ - const: txi
+ - const: tei
clock-frequency:
description:
@@ -47,25 +85,54 @@ properties:
power-domains:
maxItems: 1
+ resets:
+ maxItems: 1
+
required:
- compatible
- reg
- interrupts
+ - interrupt-names
- clocks
- clock-frequency
- power-domains
- '#address-cells'
- '#size-cells'
-if:
- properties:
- compatible:
- contains:
- enum:
- - renesas,riic-r9a07g044
-then:
- required:
- - resets
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,riic-r9a09g077
+ then:
+ properties:
+ interrupts:
+ maxItems: 4
+ interrupt-names:
+ maxItems: 4
+ resets: false
+ else:
+ properties:
+ interrupts:
+ minItems: 8
+ interrupt-names:
+ minItems: 8
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,riic-r9a07g043
+ - renesas,riic-r9a07g044
+ - renesas,riic-r9a07g054
+ - renesas,riic-r9a09g057
+ then:
+ required:
+ - resets
unevaluatedProperties: false
@@ -75,19 +142,21 @@ examples:
#include <dt-bindings/interrupt-controller/arm-gic.h>
i2c0: i2c@fcfee000 {
- compatible = "renesas,riic-r7s72100", "renesas,riic-rz";
- reg = <0xfcfee000 0x44>;
- interrupts = <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 158 IRQ_TYPE_EDGE_RISING>,
- <GIC_SPI 159 IRQ_TYPE_EDGE_RISING>,
- <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&mstp9_clks R7S72100_CLK_I2C0>;
- clock-frequency = <100000>;
- power-domains = <&cpg_clocks>;
- #address-cells = <1>;
- #size-cells = <0>;
+ compatible = "renesas,riic-r7s72100", "renesas,riic-rz";
+ reg = <0xfcfee000 0x44>;
+ interrupts = <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 158 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 159 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "tei", "ri", "ti", "spi", "sti", "naki", "ali",
+ "tmoi";
+ clocks = <&mstp9_clks R7S72100_CLK_I2C0>;
+ clock-frequency = <100000>;
+ power-domains = <&cpg_clocks>;
+ #address-cells = <1>;
+ #size-cells = <0>;
};
diff --git a/Documentation/devicetree/bindings/i2c/renesas,rmobile-iic.yaml b/Documentation/devicetree/bindings/i2c/renesas,rmobile-iic.yaml
index 04e4ffd80bc0..ec5222a1224f 100644
--- a/Documentation/devicetree/bindings/i2c/renesas,rmobile-iic.yaml
+++ b/Documentation/devicetree/bindings/i2c/renesas,rmobile-iic.yaml
@@ -134,16 +134,16 @@ examples:
#include <dt-bindings/power/r8a7790-sysc.h>
iic0: i2c@e6500000 {
- compatible = "renesas,iic-r8a7790", "renesas,rcar-gen2-iic",
- "renesas,rmobile-iic";
- reg = <0xe6500000 0x425>;
- interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 318>;
- clock-frequency = <400000>;
- dmas = <&dmac0 0x61>, <&dmac0 0x62>, <&dmac1 0x61>, <&dmac1 0x62>;
- dma-names = "tx", "rx", "tx", "rx";
- power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
- resets = <&cpg 318>;
- #address-cells = <1>;
- #size-cells = <0>;
+ compatible = "renesas,iic-r8a7790", "renesas,rcar-gen2-iic",
+ "renesas,rmobile-iic";
+ reg = <0xe6500000 0x425>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 318>;
+ clock-frequency = <400000>;
+ dmas = <&dmac0 0x61>, <&dmac0 0x62>, <&dmac1 0x61>, <&dmac1 0x62>;
+ dma-names = "tx", "rx", "tx", "rx";
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 318>;
+ #address-cells = <1>;
+ #size-cells = <0>;
};
diff --git a/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml b/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml
new file mode 100644
index 000000000000..5d1e7885b64a
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/renesas,rzv2m.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/renesas,rzv2m.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/V2M I2C Bus Interface
+
+maintainers:
+ - Fabrizio Castro <fabrizio.castro.jz@renesas.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - renesas,r9a09g011-i2c # RZ/V2M
+ - const: renesas,rzv2m-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: Data transmission/reception interrupt
+ - description: Status interrupt
+
+ interrupt-names:
+ items:
+ - const: tia
+ - const: tis
+
+ clock-frequency:
+ default: 100000
+ enum: [ 100000, 400000 ]
+ description:
+ Desired I2C bus clock frequency in Hz.
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - power-domains
+ - resets
+ - '#address-cells'
+ - '#size-cells'
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r9a09g011-cpg.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c0: i2c@a4030000 {
+ compatible = "renesas,r9a09g011-i2c", "renesas,rzv2m-i2c";
+ reg = <0xa4030000 0x80>;
+ interrupts = <GIC_SPI 232 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 236 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "tia", "tis";
+ clocks = <&cpg CPG_MOD R9A09G011_IIC_PCLK0>;
+ resets = <&cpg R9A09G011_IIC_GPA_PRESETN>;
+ power-domains = <&cpg>;
+ clock-frequency = <100000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml b/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml
new file mode 100644
index 000000000000..a2ddc6803617
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/samsung,s3c2410-i2c.yaml
@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/samsung,s3c2410-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S3C/S5P/Exynos SoC I2C Controller
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - samsung,s3c2440-i2c
+ # For s3c2440-like I2C used inside HDMIPHY block found on several SoCs:
+ - samsung,s3c2440-hdmiphy-i2c
+ # For s3c2440-like I2C used as a host to SATA PHY controller on an
+ # internal bus:
+ - samsung,exynos5-sata-phy-i2c
+ - items:
+ - enum:
+ - samsung,exynos7870-i2c
+ - samsung,exynos7885-i2c
+ - samsung,exynos850-i2c
+ - const: samsung,s3c2440-i2c
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: i2c
+
+ gpios:
+ description: |
+ The order of the GPIOs should be the following:: <SDA, SCL>. The GPIO
+ specifier depends on the gpio controller. Required in all cases except
+ for "samsung,s3c2440-hdmiphy-i2c" whose input/output lines are
+ permanently wired to the respective client.
+ This property is deprecated. Use "pinctrl-0" and "pinctrl-names" instead.
+ deprecated: true
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ samsung,i2c-max-bus-freq:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Desired frequency in Hz of the bus.
+ default: 100000
+
+ samsung,i2c-sda-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay (in ns) applied to data line (SDA) edges.
+ default: 0
+
+ samsung,i2c-slave-addr:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Slave address in multi-master environment.
+ default: 0
+
+ samsung,sysreg-phandle:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: Pandle to syscon used to control the system registers.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,s3c2440-hdmiphy-i2c
+ - samsung,exynos5-sata-phy-i2c
+ then:
+ properties:
+ gpios: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,s3c2440-i2c
+ - samsung,s3c2440-hdmiphy-i2c
+ then:
+ required:
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos5250.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c@12c60000 {
+ compatible = "samsung,s3c2440-i2c";
+ reg = <0x12C60000 0x100>;
+ interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&clock CLK_I2C0>;
+ clock-names = "i2c";
+ pinctrl-names = "default";
+ pinctrl-0 = <&i2c0_bus>;
+
+ samsung,sysreg-phandle = <&sysreg_system_controller>;
+ samsung,i2c-sda-delay = <100>;
+ samsung,i2c-max-bus-freq = <20000>;
+ samsung,i2c-slave-addr = <0x66>;
+
+ eeprom@50 {
+ compatible = "samsung,s524ad0xd1", "atmel,24c128";
+ reg = <0x50>;
+ };
+ };
+
+ i2c@12ce0000 {
+ compatible = "samsung,s3c2440-hdmiphy-i2c";
+ reg = <0x12CE0000 0x1000>;
+ interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&clock CLK_I2C_HDMI>;
+ clock-names = "i2c";
+
+ samsung,i2c-sda-delay = <100>;
+ samsung,i2c-max-bus-freq = <66000>;
+
+ phy-i2c@38 {
+ compatible = "samsung,exynos4212-hdmiphy";
+ reg = <0x38>;
+ };
+ };
+
+ i2c@121d0000 {
+ compatible = "samsung,exynos5-sata-phy-i2c";
+ reg = <0x121D0000 0x100>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&clock CLK_SATA_PHYI2C>;
+ clock-names = "i2c";
+
+ samsung,i2c-sda-delay = <100>;
+ samsung,i2c-max-bus-freq = <40000>;
+
+ phy-i2c@38 {
+ compatible = "samsung,exynos-sataphy-i2c";
+ reg = <0x38>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml b/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml
index d9293c57f573..d904191bb0c6 100644
--- a/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/snps,designware-i2c.yaml
@@ -27,12 +27,19 @@ properties:
oneOf:
- description: Generic Synopsys DesignWare I2C controller
const: snps,designware-i2c
- - description: Microsemi Ocelot SoCs I2C controller
+ - description: Renesas RZ/N1D I2C controller
items:
- - const: mscc,ocelot-i2c
+ - const: renesas,r9a06g032-i2c # RZ/N1D
+ - const: renesas,rzn1-i2c # RZ/N1
- const: snps,designware-i2c
- description: Baikal-T1 SoC System I2C controller
const: baikal,bt1-sys-i2c
+ - items:
+ - enum:
+ - mscc,ocelot-i2c
+ - sophgo,sg2044-i2c
+ - thead,th1520-i2c
+ - const: snps,designware-i2c
reg:
minItems: 1
@@ -93,6 +100,22 @@ properties:
- const: tx
- const: rx
+ snps,bus-capacitance-pf:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ This property indicates the bus capacitance in picofarads (pF).
+ This value is used to compute the tHIGH and tLOW periods for high speed
+ mode.
+ enum: [100, 400]
+ default: 100
+
+ snps,clk-freq-optimized:
+ description:
+ This property indicates whether the hardware reduce its clock frequency
+ by reducing the internal latency required to generate the high period and
+ low period of SCL line.
+ type: boolean
+
unevaluatedProperties: false
required:
@@ -117,6 +140,8 @@ examples:
i2c-sda-hold-time-ns = <300>;
i2c-sda-falling-time-ns = <300>;
i2c-scl-falling-time-ns = <300>;
+ snps,bus-capacitance-pf = <400>;
+ snps,clk-freq-optimized;
};
- |
i2c@2000 {
diff --git a/Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml b/Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml
new file mode 100644
index 000000000000..f9d6e2038bb4
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/socionext,synquacer-i2c.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/socionext,synquacer-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Socionext SynQuacer I2C Controller
+
+maintainers:
+ - Ard Biesheuvel <ardb@kernel.org>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: socionext,synquacer-i2c
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: pclk
+
+ clock-frequency:
+ minimum: 100000
+ maximum: 400000
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c@51210000 {
+ compatible = "socionext,synquacer-i2c";
+ reg = <0x51210000 0x1000>;
+ interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clock-names = "pclk";
+ clocks = <&clk_i2c>;
+ clock-frequency = <400000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/i2c/socionext,uniphier-fi2c.yaml b/Documentation/devicetree/bindings/i2c/socionext,uniphier-fi2c.yaml
index c76131902b77..4bbe9e775da1 100644
--- a/Documentation/devicetree/bindings/i2c/socionext,uniphier-fi2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/socionext,uniphier-fi2c.yaml
@@ -29,6 +29,9 @@ properties:
minimum: 100000
maximum: 400000
+ resets:
+ maxItems: 1
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/i2c/socionext,uniphier-i2c.yaml b/Documentation/devicetree/bindings/i2c/socionext,uniphier-i2c.yaml
index ddde08636ab0..5abf496edb59 100644
--- a/Documentation/devicetree/bindings/i2c/socionext,uniphier-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/socionext,uniphier-i2c.yaml
@@ -29,6 +29,9 @@ properties:
minimum: 100000
maximum: 400000
+ resets:
+ maxItems: 1
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/i2c/spacemit,k1-i2c.yaml b/Documentation/devicetree/bindings/i2c/spacemit,k1-i2c.yaml
new file mode 100644
index 000000000000..b7220fff2235
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/spacemit,k1-i2c.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/spacemit,k1-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: I2C controller embedded in SpacemiT's K1 SoC
+
+maintainers:
+ - Troy Mitchell <troymitchell988@gmail.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: spacemit,k1-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: I2C Functional Clock
+ - description: APB Bus Clock
+
+ clock-names:
+ items:
+ - const: func
+ - const: bus
+
+ clock-frequency:
+ description: |
+ K1 support three different modes which running different frequencies
+ standard speed mode: up to 100000 (100Hz)
+ fast speed mode : up to 400000 (400Hz)
+ high speed mode : up to 3300000 (3.3Mhz)
+ default: 400000
+ maximum: 3300000
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c@d4010800 {
+ compatible = "spacemit,k1-i2c";
+ reg = <0xd4010800 0x38>;
+ interrupt-parent = <&plic>;
+ interrupts = <36>;
+ clocks = <&ccu 32>, <&ccu 84>;
+ clock-names = "func", "bus";
+ clock-frequency = <100000>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/i2c/sprd,sc9860-i2c.yaml b/Documentation/devicetree/bindings/i2c/sprd,sc9860-i2c.yaml
new file mode 100644
index 000000000000..ec0d39e73d26
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/sprd,sc9860-i2c.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/sprd,sc9860-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Spreadtrum SC9860 I2C controller
+
+maintainers:
+ - Orson Zhai <orsonzhai@gmail.com>
+ - Baolin Wang <baolin.wang7@gmail.com>
+ - Chunyan Zhang <zhang.lyra@gmail.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: sprd,sc9860-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: I2C clock
+ - description: I2C source (parent) clock
+ - description: I2C module enable clock
+
+ clock-names:
+ items:
+ - const: i2c
+ - const: source
+ - const: enable
+
+ clock-frequency: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - clock-frequency
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c@70500000 {
+ compatible = "sprd,sc9860-i2c";
+ reg = <0x70500000 0x1000>;
+ interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk_i2c3>, <&ext_26m>, <&clk_ap_apb_gates 11>;
+ clock-names = "i2c", "source", "enable";
+ clock-frequency = <400000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/st,nomadik-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,nomadik-i2c.yaml
new file mode 100644
index 000000000000..012402debfeb
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/st,nomadik-i2c.yaml
@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/st,nomadik-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST Microelectronics Nomadik I2C
+
+description: The Nomadik I2C host controller began its life in the ST
+ Microelectronics STn8800 SoC, and was then inherited into STn8810 and
+ STn8815. It was part of the prototype STn8500 which then became ST-Ericsson
+ DB8500 after the merge of these two companies wireless divisions.
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+# Need a custom select here or 'arm,primecell' will match on lots of nodes
+select:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - st,nomadik-i2c
+ - mobileye,eyeq5-i2c
+ - mobileye,eyeq6h-i2c
+ required:
+ - compatible
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - st,nomadik-i2c
+ - mobileye,eyeq5-i2c
+ - mobileye,eyeq6h-i2c
+ - const: arm,primecell
+ - items:
+ - const: stericsson,db8500-i2c
+ - const: st,nomadik-i2c
+ - const: arm,primecell
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ oneOf:
+ # Clock name in STn8815
+ - items:
+ - const: mclk
+ - const: apb_pclk
+ # Clock name in DB8500 or EyeQ
+ - items:
+ - const: i2cclk
+ - const: apb_pclk
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ clock-frequency:
+ minimum: 1
+ maximum: 3400000
+
+ mobileye,olb:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: Phandle to OLB system controller node.
+ - description: Platform-wide controller ID (integer starting from zero).
+ description:
+ The phandle pointing to OLB system controller node, with the I2C
+ controller index.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mobileye,eyeq5-i2c
+ then:
+ required:
+ - mobileye,olb
+ else:
+ properties:
+ mobileye,olb: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/reset/stericsson,db8500-prcc-reset.h>
+ #include <dt-bindings/arm/ux500_pm_domains.h>
+ i2c@80004000 {
+ compatible = "stericsson,db8500-i2c", "st,nomadik-i2c", "arm,primecell";
+ reg = <0x80004000 0x1000>;
+ interrupts = <GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ clock-frequency = <400000>;
+ clocks = <&prcc_kclk 3 3>, <&prcc_pclk 3 3>;
+ clock-names = "i2cclk", "apb_pclk";
+ power-domains = <&pm_domains DOMAIN_VAPE>;
+ resets = <&prcc_reset DB8500_PRCC_3 DB8500_PRCC_3_RESET_I2C0>;
+ };
+
+ i2c@101f8000 {
+ compatible = "st,nomadik-i2c", "arm,primecell";
+ reg = <0x101f8000 0x1000>;
+ interrupt-parent = <&vica>;
+ interrupts = <20>;
+ clock-frequency = <100000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&i2c0clk>, <&pclki2c0>;
+ clock-names = "mclk", "apb_pclk";
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/mips-gic.h>
+ i2c@300000 {
+ compatible = "mobileye,eyeq5-i2c", "arm,primecell";
+ reg = <0x300000 0x1000>;
+ interrupt-parent = <&gic>;
+ interrupts = <GIC_SHARED 1 IRQ_TYPE_LEVEL_HIGH>;
+ clock-frequency = <400000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&i2c_ser_clk>, <&i2c_clk>;
+ clock-names = "i2cclk", "apb_pclk";
+ mobileye,olb = <&olb 0>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/i2c/st,sti-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,sti-i2c.yaml
new file mode 100644
index 000000000000..08f9c1e446fd
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/st,sti-i2c.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/st,sti-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: I2C controller embedded in STMicroelectronics STi platform
+
+maintainers:
+ - Patrice Chotard <patrice.chotard@foss.st.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - st,comms-ssc-i2c
+ - st,comms-ssc4-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ maxItems: 1
+
+ clock-frequency:
+ enum: [ 100000, 400000 ]
+ default: 100000
+
+ st,i2c-min-scl-pulse-width-us:
+ description:
+ The minimum valid SCL pulse width that is allowed through the
+ deglitch circuit. In units of us.
+
+ st,i2c-min-sda-pulse-width-us:
+ description:
+ The minimum valid SDA pulse width that is allowed through the
+ deglitch circuit. In units of us.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stih407-clks.h>
+ i2c@fed40000 {
+ compatible = "st,comms-ssc4-i2c";
+ reg = <0xfed40000 0x110>;
+ interrupts = <GIC_SPI 187 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk_s_a0_ls CLK_ICN_REG>;
+ clock-names = "ssc";
+ clock-frequency = <400000>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_i2c0_default>;
+ st,i2c-min-scl-pulse-width-us = <0>;
+ st,i2c-min-sda-pulse-width-us = <5>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml
index d747f4990ad8..457bb0702ed9 100644
--- a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: I2C controller embedded in STMicroelectronics STM32 I2C platform
maintainers:
- - Pierre-Yves MORDRET <pierre-yves.mordret@st.com>
+ - Pierre-Yves MORDRET <pierre-yves.mordret@foss.st.com>
allOf:
- $ref: /schemas/i2c/i2c-controller.yaml#
@@ -17,7 +17,9 @@ allOf:
contains:
enum:
- st,stm32f7-i2c
+ - st,stm32mp13-i2c
- st,stm32mp15-i2c
+ - st,stm32mp25-i2c
then:
properties:
i2c-scl-rising-time-ns:
@@ -25,16 +27,9 @@ allOf:
i2c-scl-falling-time-ns:
default: 10
-
- st,syscfg-fmp:
- description: Use to set Fast Mode Plus bit within SYSCFG when
- Fast Mode Plus speed is selected by slave.
- Format is phandle to syscfg / register offset within
- syscfg / register bitmask for FMP bit.
- $ref: "/schemas/types.yaml#/definitions/phandle-array"
- items:
- minItems: 3
- maxItems: 3
+ else:
+ properties:
+ st,syscfg-fmp: false
- if:
properties:
@@ -47,12 +42,38 @@ allOf:
clock-frequency:
enum: [100000, 400000]
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - st,stm32f4-i2c
+ - st,stm32f7-i2c
+ - st,stm32mp13-i2c
+ - st,stm32mp15-i2c
+ then:
+ properties:
+ interrupts:
+ minItems: 2
+
+ interrupt-names:
+ minItems: 2
+ else:
+ properties:
+ interrupts:
+ maxItems: 1
+
+ interrupt-names:
+ maxItems: 1
+
properties:
compatible:
enum:
- st,stm32f4-i2c
- st,stm32f7-i2c
+ - st,stm32mp13-i2c
- st,stm32mp15-i2c
+ - st,stm32mp25-i2c
reg:
maxItems: 1
@@ -61,6 +82,13 @@ properties:
items:
- description: interrupt ID for I2C event
- description: interrupt ID for I2C error
+ minItems: 1
+
+ interrupt-names:
+ items:
+ - const: event
+ - const: error
+ minItems: 1
resets:
maxItems: 1
@@ -87,6 +115,22 @@ properties:
minimum: 1
maximum: 1000000
+ st,syscfg-fmp:
+ description: Use to set Fast Mode Plus bit within SYSCFG when Fast Mode
+ Plus speed is selected by slave.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to syscfg
+ - description: register offset within syscfg
+ - description: register bitmask for FMP bit
+
+ wakeup-source: true
+
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
required:
- compatible
- reg
@@ -101,44 +145,49 @@ examples:
#include <dt-bindings/mfd/stm32f7-rcc.h>
#include <dt-bindings/clock/stm32fx-clock.h>
//Example 1 (with st,stm32f4-i2c compatible)
- i2c@40005400 {
- compatible = "st,stm32f4-i2c";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x40005400 0x400>;
- interrupts = <31>,
- <32>;
- resets = <&rcc 277>;
- clocks = <&rcc 0 149>;
- };
+ i2c@40005400 {
+ compatible = "st,stm32f4-i2c";
+ reg = <0x40005400 0x400>;
+ interrupts = <31>,
+ <32>;
+ resets = <&rcc 277>;
+ clocks = <&rcc 0 149>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ - |
+ #include <dt-bindings/mfd/stm32f7-rcc.h>
+ #include <dt-bindings/clock/stm32fx-clock.h>
//Example 2 (with st,stm32f7-i2c compatible)
- i2c@40005800 {
- compatible = "st,stm32f7-i2c";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x40005800 0x400>;
- interrupts = <31>,
- <32>;
- resets = <&rcc STM32F7_APB1_RESET(I2C1)>;
- clocks = <&rcc 1 CLK_I2C1>;
- };
+ i2c@40005800 {
+ compatible = "st,stm32f7-i2c";
+ reg = <0x40005800 0x400>;
+ interrupts = <31>,
+ <32>;
+ resets = <&rcc STM32F7_APB1_RESET(I2C1)>;
+ clocks = <&rcc 1 CLK_I2C1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ - |
+ #include <dt-bindings/mfd/stm32f7-rcc.h>
+ #include <dt-bindings/clock/stm32fx-clock.h>
//Example 3 (with st,stm32mp15-i2c compatible on stm32mp)
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/clock/stm32mp1-clks.h>
#include <dt-bindings/reset/stm32mp1-resets.h>
- i2c@40013000 {
- compatible = "st,stm32mp15-i2c";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x40013000 0x400>;
- interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&rcc I2C2_K>;
- resets = <&rcc I2C2_R>;
- i2c-scl-rising-time-ns = <185>;
- i2c-scl-falling-time-ns = <20>;
- st,syscfg-fmp = <&syscfg 0x4 0x2>;
- };
-...
+ i2c@40013000 {
+ compatible = "st,stm32mp15-i2c";
+ reg = <0x40013000 0x400>;
+ interrupts = <GIC_SPI 33 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 34 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&rcc I2C2_K>;
+ resets = <&rcc I2C2_R>;
+ i2c-scl-rising-time-ns = <185>;
+ i2c-scl-falling-time-ns = <20>;
+ st,syscfg-fmp = <&syscfg 0x4 0x2>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml b/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml
index ff165ad1bee8..58d32ceeacfc 100644
--- a/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i2c/ti,omap4-i2c.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Bindings for I2C controllers on TI's OMAP and K3 SoCs
+title: I2C controllers on TI's OMAP and K3 SoCs
maintainers:
- Vignesh Raghavendra <vigneshr@ti.com>
@@ -37,16 +37,8 @@ properties:
clock-names:
const: fck
- clock-frequency: true
-
power-domains: true
- "#address-cells":
- const: 1
-
- "#size-cells":
- const: 0
-
ti,hwmods:
description:
Must be "i2c<n>", n being the instance number (1-based).
@@ -55,38 +47,39 @@ properties:
$ref: /schemas/types.yaml#/definitions/string
deprecated: true
-# subnode's properties
-patternProperties:
- "@[0-9a-f]+$":
- type: object
+ mux-states:
description:
- Flash device uses the below defined properties in the subnode.
+ mux controller node to route the I2C signals from SoC to clients.
+ maxItems: 1
required:
- compatible
- reg
- interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - ti,omap2420-i2c
+ - ti,omap2430-i2c
+ - ti,omap3-i2c
+ - ti,omap4-i2c
-if:
- properties:
- compatible:
- oneOf:
- - const: ti,omap2420-i2c
- - const: ti,omap2430-i2c
- - const: ti,omap3-i2c
- - const: ti,omap4-i2c
+ then:
+ properties:
+ ti,hwmods:
+ items:
+ - pattern: "^i2c([1-9])$"
-then:
- properties:
- ti,hwmods:
- items:
- - pattern: "^i2c([1-9])$"
+ else:
+ properties:
+ ti,hwmods: false
-else:
- properties:
- ti,hwmods: false
+unevaluatedProperties: false
examples:
- |
@@ -94,9 +87,10 @@ examples:
#include <dt-bindings/interrupt-controller/arm-gic.h>
main_i2c0: i2c@2000000 {
- compatible = "ti,j721e-i2c", "ti,omap4-i2c";
- reg = <0x2000000 0x100>;
- interrupts = <GIC_SPI 200 IRQ_TYPE_LEVEL_HIGH>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
+ compatible = "ti,j721e-i2c", "ti,omap4-i2c";
+ reg = <0x2000000 0x100>;
+ interrupts = <GIC_SPI 200 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ mux-states = <&i2c_mux 1>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml b/Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml
new file mode 100644
index 000000000000..19cfffb39296
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/tsd,mule-i2c-mux.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Theobroma Systems Mule I2C multiplexer
+
+maintainers:
+ - Farouk Bouabid <farouk.bouabid@cherry.de>
+ - Quentin Schulz <quentin.schulz@cherry.de>
+
+description: |
+ Theobroma Systems Mule is an MCU that emulates a set of I2C devices, among
+ which devices that are reachable through an I2C-mux. The devices on the mux
+ can be selected by writing the appropriate device number to an I2C config
+ register.
+
+ +--------------------------------------------------+
+ | Mule |
+ 0x18| +---------------+ |
+ -------->|Config register|----+ |
+ | +---------------+ | |
+ | V_ |
+ | | \ +--------+ |
+ | | \-------->| dev #0 | |
+ | | | +--------+ |
+ 0x6f| | M |-------->| dev #1 | |
+ ---------------------------->| U | +--------+ |
+ | | X |-------->| dev #2 | |
+ | | | +--------+ |
+ | | /-------->| dev #3 | |
+ | |__/ +--------+ |
+ +--------------------------------------------------+
+
+allOf:
+ - $ref: /schemas/i2c/i2c-mux.yaml#
+
+properties:
+ compatible:
+ const: tsd,mule-i2c-mux
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c-mux {
+ compatible = "tsd,mule-i2c-mux";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ i2c@0 {
+ reg = <0x0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ rtc@6f {
+ compatible = "isil,isl1208";
+ reg = <0x6f>;
+ };
+ };
+ };
+...
+
diff --git a/Documentation/devicetree/bindings/i2c/wm,wm8505-i2c.yaml b/Documentation/devicetree/bindings/i2c/wm,wm8505-i2c.yaml
new file mode 100644
index 000000000000..e498ce47b885
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/wm,wm8505-i2c.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i2c/wm,wm8505-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: I2C Controller on WonderMedia WM8505 and related SoCs
+
+maintainers:
+ - Alexey Charkov <alchark@gmail.com>
+
+allOf:
+ - $ref: /schemas/i2c/i2c-controller.yaml#
+
+properties:
+ compatible:
+ const: wm,wm8505-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-frequency:
+ enum: [100000, 400000]
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c_0: i2c@d8280000 {
+ compatible = "wm,wm8505-i2c";
+ reg = <0xd8280000 0x1000>;
+ interrupts = <19>;
+ clocks = <&clki2c0>;
+ clock-frequency = <400000>;
+ };
diff --git a/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml b/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml
index 715dcfa5a922..658ae92fa86d 100644
--- a/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml
+++ b/Documentation/devicetree/bindings/i2c/xlnx,xps-iic-2.00.a.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/i2c/xlnx,xps-iic-2.00.a.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/i2c/xlnx,xps-iic-2.00.a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Xilinx IIC controller Device Tree Bindings
+title: Xilinx IIC controller
maintainers:
- info@mocean-labs.com
@@ -14,7 +14,9 @@ allOf:
properties:
compatible:
- const: xlnx,xps-iic-2.00.a
+ enum:
+ - xlnx,axi-iic-2.1
+ - xlnx,xps-iic-2.00.a
reg:
maxItems: 1
@@ -30,6 +32,13 @@ properties:
description: |
Input clock name.
+ clock-frequency:
+ description:
+ Optional I2C SCL clock frequency. If not specified, do not configure
+ in software, rely only on hardware design value.
+ default: 100000
+ enum: [ 100000, 400000, 1000000 ]
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml
new file mode 100644
index 000000000000..2498672d2654
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/adi,i3c-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices I3C Controller
+
+description:
+ FPGA-based I3C controller designed to interface with I3C and I2C peripherals,
+ implementing a subset of the I3C-basic specification. The IP core is tested
+ on arm, microblaze, and arm64 architectures.
+
+ https://analogdevicesinc.github.io/hdl/library/i3c_controller
+
+maintainers:
+ - Jorge Marques <jorge.marques@analog.com>
+
+properties:
+ compatible:
+ const: adi,i3c-master-v1
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ items:
+ - description: The AXI interconnect clock, drives the register map.
+ - description:
+ The secondary clock, drives the internal logic asynchronously to the
+ register map. The presence of this entry states that the IP Core was
+ synthesized with a second clock input, and the absence of this entry
+ indicates a topology where a single clock input drives all the
+ internal logic.
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: axi
+ - const: i3c
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+allOf:
+ - $ref: i3c.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i3c@44a00000 {
+ compatible = "adi,i3c-master-v1";
+ reg = <0x44a00000 0x1000>;
+ interrupts = <3 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clkc 15>, <&clkc 15>;
+ clock-names = "axi", "i3c";
+ #address-cells = <3>;
+ #size-cells = <0>;
+
+ /* I3C and I2C devices */
+ };
diff --git a/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml b/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml
new file mode 100644
index 000000000000..47be5d9a32d4
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/aspeed,ast2600-i3c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED AST2600 i3c controller
+
+maintainers:
+ - Jeremy Kerr <jk@codeconstruct.com.au>
+
+allOf:
+ - $ref: i3c.yaml#
+
+properties:
+ compatible:
+ const: aspeed,ast2600-i3c
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ sda-pullup-ohms:
+ enum: [545, 750, 2000]
+ default: 2000
+ description: |
+ Value to configure SDA pullup resistor, in Ohms.
+
+ aspeed,global-regs:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to i3c global register syscon node
+ - description: index of this i3c controller in the global register set
+ description: |
+ A (phandle, controller index) reference to the i3c global register set
+ used for this device.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+ - aspeed,global-regs
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i3c@2000 {
+ compatible = "aspeed,ast2600-i3c";
+ reg = <0x2000 0x1000>;
+ #address-cells = <3>;
+ #size-cells = <0>;
+ clocks = <&syscon 0>;
+ resets = <&syscon 0>;
+ aspeed,global-regs = <&i3c_global 0>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_i3c1_default>;
+ interrupts = <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt
deleted file mode 100644
index 3716589d6999..000000000000
--- a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-Bindings for cadence I3C master block
-=====================================
-
-Required properties:
---------------------
-- compatible: shall be "cdns,i3c-master"
-- clocks: shall reference the pclk and sysclk
-- clock-names: shall contain "pclk" and "sysclk"
-- interrupts: the interrupt line connected to this I3C master
-- reg: I3C master registers
-
-Mandatory properties defined by the generic binding (see
-Documentation/devicetree/bindings/i3c/i3c.yaml for more details):
-
-- #address-cells: shall be set to 1
-- #size-cells: shall be set to 0
-
-Optional properties defined by the generic binding (see
-Documentation/devicetree/bindings/i3c/i3c.yaml for more details):
-
-- i2c-scl-hz
-- i3c-scl-hz
-
-I3C device connected on the bus follow the generic description (see
-Documentation/devicetree/bindings/i3c/i3c.yaml for more details).
-
-Example:
-
- i3c-master@0d040000 {
- compatible = "cdns,i3c-master";
- clocks = <&coreclock>, <&i3csysclock>;
- clock-names = "pclk", "sysclk";
- interrupts = <3 0>;
- reg = <0x0d040000 0x1000>;
- #address-cells = <1>;
- #size-cells = <0>;
- i2c-scl-hz = <100000>;
-
- nunchuk: nunchuk@52 {
- compatible = "nintendo,nunchuk";
- reg = <0x52 0x0 0x10>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml
new file mode 100644
index 000000000000..6fa3078074d0
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/cdns,i3c-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cadence I3C master block
+
+maintainers:
+ - Boris Brezillon <bbrezillon@kernel.org>
+
+allOf:
+ - $ref: i3c.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - const: cdns,i3c-master
+ - items:
+ - enum:
+ - axiado,ax3000-i3c
+ - const: cdns,i3c-master
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: pclk
+ - const: sysclk
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i3c@d040000 {
+ compatible = "cdns,i3c-master";
+ clocks = <&coreclock>, <&i3csysclock>;
+ clock-names = "pclk", "sysclk";
+ interrupts = <3 0>;
+ reg = <0x0d040000 0x1000>;
+ #address-cells = <3>;
+ #size-cells = <0>;
+ i2c-scl-hz = <100000>;
+
+ eeprom@57{
+ compatible = "atmel,24c01";
+ reg = <0x57 0x0 0x10>;
+ pagesize = <0x8>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml
index 1f82fc923799..e25fa72fd785 100644
--- a/Documentation/devicetree/bindings/i3c/i3c.yaml
+++ b/Documentation/devicetree/bindings/i3c/i3c.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/i3c/i3c.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: I3C bus binding
+title: I3C bus
maintainers:
- Alexandre Belloni <alexandre.belloni@bootlin.com>
@@ -17,7 +17,7 @@ description: |
properties:
$nodename:
- pattern: "^i3c-master@[0-9a-f]+$"
+ pattern: "^i3c@[0-9a-f]+$"
"#address-cells":
const: 3
@@ -55,6 +55,12 @@ properties:
May not be supported by all controllers.
+ mctp-controller:
+ type: boolean
+ description: |
+ Indicates that the system is accessible via this bus as an endpoint for
+ MCTP over I3C transport.
+
required:
- "#address-cells"
- "#size-cells"
@@ -65,7 +71,7 @@ patternProperties:
description: |
I2C child, should be named: <device-type>@<i2c-address>
- All properties described in Documentation/devicetree/bindings/i2c/i2c.txt
+ All properties described in dtschema schemas/i2c/i2c-controller.yaml
are valid here, except the reg property whose content is changed.
properties:
@@ -85,6 +91,7 @@ patternProperties:
- const: 0
- description: |
Shall encode the I3C LVR (Legacy Virtual Register):
+ See include/dt-bindings/i3c/i3c.h
bit[31:8]: unused/ignored
bit[7:5]: I2C device index. Possible values:
* 0: I2C device has a 50 ns spike filter
@@ -119,12 +126,12 @@ patternProperties:
minimum: 0
maximum: 0x7f
- description: |
- First half of the Provisional ID (following the PID
+ First half of the Provisioned ID (following the PID
definition provided by the I3C specification).
Contains the manufacturer ID left-shifted by 1.
- description: |
- Second half of the Provisional ID (following the PID
+ Second half of the Provisioned ID (following the PID
definition provided by the I3C specification).
Contains the ORing of the part ID left-shifted by 16,
@@ -135,9 +142,10 @@ patternProperties:
minimum: 0x1
maximum: 0xff
description: |
- Dynamic address to be assigned to this device. This property is only
- valid if the I3C device has a static address (first cell of the reg
- property != 0).
+ Dynamic address to be assigned to this device. In case static address is
+ present (first cell of the reg property != 0), this address is assigned
+ through SETDASA. If static address is not present, this address is assigned
+ through SETNEWDA after assigning a temporary address via ENTDAA.
required:
- reg
@@ -146,7 +154,9 @@ additionalProperties: true
examples:
- |
- i3c-master@d040000 {
+ #include <dt-bindings/i3c/i3c.h>
+
+ i3c@d040000 {
compatible = "cdns,i3c-master";
clocks = <&coreclock>, <&i3csysclock>;
clock-names = "pclk", "sysclk";
@@ -159,16 +169,22 @@ examples:
/* I2C device. */
eeprom@57 {
compatible = "atmel,24c01";
- reg = <0x57 0x0 0x10>;
+ reg = <0x57 0x0 (I2C_FM | I2C_FILTER)>;
pagesize = <0x8>;
};
- /* I3C device with a static I2C address. */
+ /* I3C device with a static I2C address and assigned address. */
thermal_sensor: sensor@68,39200144004 {
reg = <0x68 0x392 0x144004>;
assigned-address = <0xa>;
};
+ /* I3C device with only assigned address. */
+ pressure_sensor: sensor@0,39200124004 {
+ reg = <0x0 0x392 0x124000>;
+ assigned-address = <0xc>;
+ };
+
/*
* I3C device without a static I2C address but requiring
* resources described in the DT.
diff --git a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml
index 04da001fc6ec..39bb1a1784c9 100644
--- a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml
+++ b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/i3c/mipi-i3c-hci.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/i3c/mipi-i3c-hci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: MIPI I3C HCI Device Tree Bindings
+title: MIPI I3C HCI
maintainers:
- Nicolas Pitre <npitre@baylibre.com>
@@ -43,7 +43,7 @@ unevaluatedProperties: false
examples:
- |
- i3c-master@a0000000 {
+ i3c@a0000000 {
compatible = "mipi-i3c-hci";
reg = <0xa0000000 0x2000>;
interrupts = <89>;
diff --git a/Documentation/devicetree/bindings/i3c/renesas,i3c.yaml b/Documentation/devicetree/bindings/i3c/renesas,i3c.yaml
new file mode 100644
index 000000000000..a20d875086d4
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/renesas,i3c.yaml
@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/renesas,i3c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas I3C Bus Interface
+
+maintainers:
+ - Wolfram Sang <wsa+renesas@sang-engineering.com>
+ - Tommaso Merciai <tommaso.merciai.xr@bp.renesas.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,r9a08g045-i3c # RZ/G3S
+ - renesas,r9a09g047-i3c # RZ/G3E
+ - items:
+ - enum:
+ - renesas,r9a09g056-i3c # RZ/V2N
+ - renesas,r9a09g057-i3c # RZ/V2H(P)
+ - const: renesas,r9a09g047-i3c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: Non-recoverable internal error interrupt
+ - description: Normal transfer error interrupt
+ - description: Normal transfer abort interrupt
+ - description: Normal response status buffer full interrupt
+ - description: Normal command buffer empty interrupt
+ - description: Normal IBI status buffer full interrupt
+ - description: Normal Rx data buffer full interrupt
+ - description: Normal Tx data buffer empty interrupt
+ - description: Normal receive status buffer full interrupt
+ - description: START condition detection interrupt
+ - description: STOP condition detection interrupt
+ - description: Transmit end interrupt
+ - description: NACK detection interrupt
+ - description: Arbitration lost interrupt
+ - description: Timeout detection interrupt
+ - description: Wake-up condition detection interrupt
+ - description: HDR Exit Pattern detection interrupt
+ minItems: 16
+
+ interrupt-names:
+ items:
+ - const: ierr
+ - const: terr
+ - const: abort
+ - const: resp
+ - const: cmd
+ - const: ibi
+ - const: rx
+ - const: tx
+ - const: rcv
+ - const: st
+ - const: sp
+ - const: tend
+ - const: nack
+ - const: al
+ - const: tmo
+ - const: wu
+ - const: exit
+ minItems: 16
+
+ clocks:
+ items:
+ - description: APB bus clock
+ - description: transfer clock
+ - description: SFRs clock
+ minItems: 2
+
+ clock-names:
+ items:
+ - const: pclk
+ - const: tclk
+ - const: pclkrw
+ minItems: 2
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ items:
+ - description: Reset signal
+ - description: APB interface reset signal/SCAN reset signal
+
+ reset-names:
+ items:
+ - const: presetn
+ - const: tresetn
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clock-names
+ - clocks
+ - power-domains
+ - resets
+ - reset-names
+
+allOf:
+ - $ref: i3c.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a08g045-i3c
+ then:
+ properties:
+ clocks:
+ maxItems: 2
+ clock-names:
+ maxItems: 2
+ interrupts:
+ minItems: 17
+ interrupt-names:
+ minItems: 17
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a09g047-i3c
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ clock-names:
+ minItems: 3
+ interrupts:
+ maxItems: 16
+ interrupt-names:
+ maxItems: 16
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r9a08g045-cpg.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i3c@1005b000 {
+ compatible = "renesas,r9a08g045-i3c";
+ reg = <0x1005b000 0x1000>;
+ clocks = <&cpg CPG_MOD R9A08G045_I3C_PCLK>,
+ <&cpg CPG_MOD R9A08G045_I3C_TCLK>;
+ clock-names = "pclk", "tclk";
+ interrupts = <GIC_SPI 289 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 290 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 293 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 294 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 295 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 296 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 297 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 298 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 299 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 304 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 307 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 308 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 309 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 310 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 311 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 306 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "ierr", "terr", "abort", "resp",
+ "cmd", "ibi", "rx", "tx", "rcv",
+ "st", "sp", "tend", "nack",
+ "al", "tmo", "wu", "exit";
+ resets = <&cpg R9A08G045_I3C_PRESETN>,
+ <&cpg R9A08G045_I3C_TRESETN>;
+ reset-names = "presetn", "tresetn";
+ power-domains = <&cpg>;
+ #address-cells = <3>;
+ #size-cells = <0>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml
index 62f3ca66274f..853092f7522d 100644
--- a/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml
+++ b/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml
@@ -9,12 +9,17 @@ title: Silvaco I3C master
maintainers:
- Conor Culhane <conor.culhane@silvaco.com>
-allOf:
- - $ref: "i3c.yaml#"
-
properties:
compatible:
- const: silvaco,i3c-master-v1
+ oneOf:
+ - enum:
+ - nuvoton,npcm845-i3c
+ - silvaco,i3c-master-v1
+ - items:
+ - enum:
+ - nxp,imx94-i3c
+ - nxp,imx95-i3c
+ - const: silvaco,i3c-master-v1
reg:
maxItems: 1
@@ -23,12 +28,14 @@ properties:
maxItems: 1
clocks:
+ minItems: 2
items:
- description: system clock
- description: bus clock
- description: other (slower) events clock
clock-names:
+ minItems: 2
items:
- const: pclk
- const: fast_clk
@@ -44,11 +51,39 @@ required:
- clock-names
- clocks
-additionalProperties: true
+allOf:
+ - $ref: i3c.yaml#
+ - if:
+ properties:
+ compatible:
+ enum:
+ - nuvoton,npcm845-i3c
+ - silvaco,i3c-master-v1
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ clock-names:
+ minItems: 3
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,imx94-i3c
+ - nxp,imx95-i3c
+ then:
+ properties:
+ clocks:
+ maxItems: 2
+ clock-names:
+ maxItems: 2
+
+unevaluatedProperties: false
examples:
- |
- i3c-master@a0000000 {
+ i3c@a0000000 {
compatible = "silvaco,i3c-master-v1";
clocks = <&zynqmp_clk 71>, <&fclk>, <&sclk>;
clock-names = "pclk", "fast_clk", "slow_clk";
diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt
deleted file mode 100644
index 07f35f36085d..000000000000
--- a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Bindings for Synopsys DesignWare I3C master block
-=================================================
-
-Required properties:
---------------------
-- compatible: shall be "snps,dw-i3c-master-1.00a"
-- clocks: shall reference the core_clk
-- interrupts: the interrupt line connected to this I3C master
-- reg: Offset and length of I3C master registers
-
-Mandatory properties defined by the generic binding (see
-Documentation/devicetree/bindings/i3c/i3c.yaml for more details):
-
-- #address-cells: shall be set to 3
-- #size-cells: shall be set to 0
-
-Optional properties defined by the generic binding (see
-Documentation/devicetree/bindings/i3c/i3c.yaml for more details):
-
-- i2c-scl-hz
-- i3c-scl-hz
-
-I3C device connected on the bus follow the generic description (see
-Documentation/devicetree/bindings/i3c/i3c.yaml for more details).
-
-Example:
-
- i3c-master@2000 {
- compatible = "snps,dw-i3c-master-1.00a";
- #address-cells = <3>;
- #size-cells = <0>;
- reg = <0x02000 0x1000>;
- interrupts = <0>;
- clocks = <&i3cclk>;
-
- eeprom@57{
- compatible = "atmel,24c01";
- reg = <0x57 0x0 0x10>;
- pagesize = <0x8>;
- };
- };
diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml
new file mode 100644
index 000000000000..e803457d3f55
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/snps,dw-i3c-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synopsys DesignWare I3C master block
+
+maintainers:
+ - Alexandre Belloni <alexandre.belloni@bootlin.com>
+
+allOf:
+ - $ref: i3c.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - const: snps,dw-i3c-master-1.00a
+ - items:
+ - const: altr,agilex5-dw-i3c-master
+ - const: snps,dw-i3c-master-1.00a
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ items:
+ - description: Core clock
+ - description: APB clock
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: core
+ - const: apb
+
+ interrupts:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i3c@2000 {
+ compatible = "snps,dw-i3c-master-1.00a";
+ #address-cells = <3>;
+ #size-cells = <0>;
+ reg = <0x02000 0x1000>;
+ interrupts = <0>;
+ clocks = <&i3cclk>;
+
+ eeprom@57{
+ compatible = "atmel,24c01";
+ reg = <0x57 0x0 0x10>;
+ pagesize = <0x8>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml
index 6f8f8a6258fe..b6ba7ad1a8d5 100644
--- a/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adis16201.yaml
@@ -27,20 +27,21 @@ properties:
interrupts:
maxItems: 1
- spi-max-frequency: true
-
vdd-supply: true
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml
index 4fcbfd93e218..a92e153705f3 100644
--- a/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml
@@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: ADIS16240 Programmable Impact Sensor and Recorder driver
maintainers:
- - Alexandru Ardelean <alexandru.ardelean@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
description: |
ADIS16240 Programmable Impact Sensor and Recorder driver that supports
@@ -25,20 +26,20 @@ properties:
interrupts:
maxItems: 1
- spi-max-frequency: true
-
required:
- compatible
- reg
- interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml
new file mode 100644
index 000000000000..3a8c69eecfde
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl313.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/adi,adxl313.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADXL312, ADXL313, and ADXL314 3-Axis Digital Accelerometers
+
+maintainers:
+ - Lucas Stankus <lucas.p.stankus@gmail.com>
+
+description: |
+ Analog Devices ADXL312, ADXL313, and ADXL314 3-Axis Digital Accelerometer that
+ support both I2C & SPI interfaces.
+ https://www.analog.com/en/products/adxl312.html
+ https://www.analog.com/en/products/adxl313.html
+ https://www.analog.com/en/products/adxl314.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adxl312
+ - adi,adxl313
+ - adi,adxl314
+
+ reg:
+ maxItems: 1
+
+ spi-3wire: true
+
+ vs-supply:
+ description: Regulator that supplies power to the accelerometer
+
+ vdd-supply:
+ description: Regulator that supplies the digital interface supply voltage
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Example for a I2C device node */
+ accelerometer@53 {
+ compatible = "adi,adxl313";
+ reg = <0x53>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "INT1";
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Example for a SPI device node */
+ accelerometer@0 {
+ compatible = "adi,adxl313";
+ reg = <0>;
+ spi-max-frequency = <5000000>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "INT1";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml
index 11d32a288535..61d7ba89adc2 100644
--- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml
@@ -32,38 +32,49 @@ properties:
spi-cpol: true
- spi-max-frequency: true
+ spi-3wire: true
interrupts:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - enum: [INT1, INT2]
+ - const: INT2
+
+dependencies:
+ interrupts: [ interrupt-names ]
required:
- compatible
- reg
- - interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
/* Example for a I2C device node */
accelerometer@2a {
compatible = "adi,adxl345";
- reg = <0x53>;
+ reg = <0x2a>;
interrupt-parent = <&gpio0>;
interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "INT1";
};
};
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -75,6 +86,8 @@ examples:
spi-cpol;
spi-cpha;
interrupt-parent = <&gpio0>;
- interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ interrupts = <0 IRQ_TYPE_LEVEL_HIGH>,
+ <1 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "INT1", "INT2";
};
};
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml
new file mode 100644
index 000000000000..f39e2912731f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl355.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/adi,adxl355.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADXL355 and ADXL359 3-Axis, Low noise MEMS Accelerometers
+
+maintainers:
+ - Puranjay Mohan <puranjay12@gmail.com>
+
+description: |
+ Analog Devices ADXL355 and ADXL359 3-Axis, Low noise MEMS Accelerometers that
+ support both I2C & SPI interfaces
+ https://www.analog.com/en/products/adxl355.html
+ https://www.analog.com/en/products/adxl359.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adxl355
+ - adi,adxl359
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 3
+ description: |
+ Type for DRDY should be IRQ_TYPE_EDGE_RISING.
+ Three configurable interrupt lines exist.
+
+ interrupt-names:
+ description: Specify which interrupt line is in use.
+ items:
+ enum:
+ - INT1
+ - INT2
+ - DRDY
+ minItems: 1
+ maxItems: 3
+
+ vdd-supply:
+ description: Regulator that provides power to the sensor
+
+ vddio-supply:
+ description: Regulator that provides power to the bus
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Example for a I2C device node */
+ accelerometer@1d {
+ compatible = "adi,adxl355";
+ reg = <0x1d>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "DRDY";
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accelerometer@0 {
+ compatible = "adi,adxl355";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "DRDY";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl367.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl367.yaml
new file mode 100644
index 000000000000..f10d98d34cb8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl367.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/adi,adxl367.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADXL367 3-Axis Digital Accelerometer
+
+maintainers:
+ - Cosmin Tanislav <cosmin.tanislav@analog.com>
+
+description: |
+ The ADXL367 is an ultralow power, 3-axis MEMS accelerometer.
+
+ The ADXL367 does not alias input signals by to achieve ultralow power
+ consumption, it samples the full bandwidth of the sensor at all
+ data rates. Measurement ranges of +-2g, +-4g, and +-8g are available,
+ with a resolution of 0.25mg/LSB on the +-2 g range.
+
+ In addition to its ultralow power consumption, the ADXL367
+ has many features to enable true system level power reduction.
+ It includes a deep multimode output FIFO, a built-in micropower
+ temperature sensor, and an internal ADC for synchronous conversion
+ of an additional analog input.
+ https://www.analog.com/en/products/adxl367.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adxl367
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accelerometer@53 {
+ compatible = "adi,adxl367";
+ reg = <0x53>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accelerometer@0 {
+ compatible = "adi,adxl367";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml
index 38b59b6454ce..0ba0df46c3a9 100644
--- a/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl372.yaml
@@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices ADXL372 3-Axis, +/-(200g) Digital Accelerometer
maintainers:
- - Stefan Popa <stefan.popa@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
description: |
Analog Devices ADXL372 3-Axis, +/-(200g) Digital Accelerometer that supports
@@ -25,43 +26,42 @@ properties:
interrupts:
maxItems: 1
- spi-max-frequency: true
-
required:
- compatible
- reg
- interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
- #include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
- /* Example for a I2C device node */
- accelerometer@53 {
- compatible = "adi,adxl372";
- reg = <0x53>;
- interrupt-parent = <&gpio>;
- interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
- };
+ /* Example for a I2C device node */
+ accelerometer@53 {
+ compatible = "adi,adxl372";
+ reg = <0x53>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
};
+ };
- |
- #include <dt-bindings/gpio/gpio.h>
- #include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
- #address-cells = <1>;
- #size-cells = <0>;
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
- accelerometer@0 {
- compatible = "adi,adxl372";
- reg = <0>;
- spi-max-frequency = <1000000>;
- interrupt-parent = <&gpio>;
- interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
- };
+ accelerometer@0 {
+ compatible = "adi,adxl372";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
};
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl380.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl380.yaml
new file mode 100644
index 000000000000..ab517720a6a7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl380.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/adi,adxl380.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADXL380/382 3-Axis Digital Accelerometer
+
+maintainers:
+ - Ramona Gradinariu <ramona.gradinariu@analog.com>
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ The ADXL380/ADXL382 and ADXL318/ADXL319 are low noise density,
+ low power, 3-axis accelerometers with selectable measurement ranges.
+ The ADXL380 and ADXL318 support the ±4 g, ±8 g, and ±16 g ranges,
+ while the ADXL382 and ADXL319 support ±15 g, ±30 g, and ±60 g ranges.
+
+ https://www.analog.com/en/products/adxl318.html
+ https://www.analog.com/en/products/adxl380.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adxl318
+ - adi,adxl319
+ - adi,adxl380
+ - adi,adxl382
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - enum: [INT0, INT1]
+ - const: INT1
+
+ vddio-supply: true
+
+ vsupply-supply: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - vddio-supply
+ - vsupply-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accelerometer@54 {
+ compatible = "adi,adxl380";
+ reg = <0x54>;
+ vddio-supply = <&vddio>;
+ vsupply-supply = <&vsupply>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "INT0";
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accelerometer@0 {
+ compatible = "adi,adxl380";
+ reg = <0>;
+ spi-max-frequency = <8000000>;
+ vddio-supply = <&vddio>;
+ vsupply-supply = <&vsupply>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "INT0";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma180.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma180.yaml
deleted file mode 100644
index a7e84089cc3d..000000000000
--- a/Documentation/devicetree/bindings/iio/accel/bosch,bma180.yaml
+++ /dev/null
@@ -1,61 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/iio/accel/bosch,bma180.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Bosch BMA023 / BMA150/ BMA180 / BMA250 / SMB380 triaxial accelerometers
-
-maintainers:
- - Jonathan Cameron <jic23@kernel.org>
-
-description: |
- https://media.digikey.com/pdf/Data%20Sheets/Bosch/BMA150.pdf
- http://omapworld.com/BMA180_111_1002839.pdf
- http://ae-bst.resource.bosch.com/media/products/dokumente/bma250/bst-bma250-ds002-05.pdf
-
-properties:
- compatible:
- enum:
- - bosch,bma023
- - bosch,bma150
- - bosch,bma180
- - bosch,bma250
- - bosch,smb380
-
- reg:
- maxItems: 1
-
- vdd-supply: true
-
- vddio-supply: true
-
- interrupts:
- minItems: 1
- maxItems: 2
- description: |
- Type should be either IRQ_TYPE_LEVEL_HIGH or IRQ_TYPE_EDGE_RISING.
- For the bma250 the first interrupt listed must be the one
- connected to the INT1 pin, the second (optional) interrupt
- listed must be the one connected to the INT2 pin.
-
-required:
- - compatible
- - reg
-
-additionalProperties: false
-
-examples:
- - |
- #include <dt-bindings/interrupt-controller/irq.h>
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
- accel@40 {
- compatible = "bosch,bma180";
- reg = <0x40>;
- interrupt-parent = <&gpio6>;
- interrupts = <18 (IRQ_TYPE_LEVEL_HIGH | IRQ_TYPE_EDGE_RISING)>;
- };
- };
-...
diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml
index 942b23ad0712..8c820c27f781 100644
--- a/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/bosch,bma220.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/accel/bosch,bma220.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Bosch BMA220 Trixial Acceleration Sensor
+title: Bosch BMA220 Triaxial Acceleration Sensor
maintainers:
- Jonathan Cameron <Jonathan.Cameron@huawei.com>
@@ -20,7 +20,8 @@ properties:
interrupts:
maxItems: 1
- spi-max-frequency: true
+ spi-cpha: true
+ spi-cpol: true
vdda-supply: true
vddd-supply: true
@@ -30,12 +31,15 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -43,8 +47,10 @@ examples:
compatible = "bosch,bma220";
reg = <0>;
spi-max-frequency = <2500000>;
+ spi-cpol;
+ spi-cpha;
interrupt-parent = <&gpio0>;
- interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
+ interrupts = <0 IRQ_TYPE_EDGE_RISING>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml
index e830d5295b92..85c9537f1f02 100644
--- a/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/bosch,bma255.yaml
@@ -8,6 +8,7 @@ title: Bosch BMA255 and Similar Accelerometers
maintainers:
- Linus Walleij <linus.walleij@linaro.org>
+ - Stephan Gerhold <stephan@gerhold.net>
description:
3 axis accelerometers with varying range and I2C or SPI
@@ -16,15 +17,24 @@ description:
properties:
compatible:
enum:
- - bosch,bmc150_accel
- - bosch,bmi055_accel
+ # bmc150-accel driver in Linux
+ - bosch,bma222
+ - bosch,bma222e
+ - bosch,bma250e
- bosch,bma253
- bosch,bma254
- bosch,bma255
- - bosch,bma250e
- - bosch,bma222
- - bosch,bma222e
- bosch,bma280
+ - bosch,bmc150_accel
+ - bosch,bmc156_accel
+ - bosch,bmi055_accel
+
+ # bma180 driver in Linux
+ - bosch,bma023
+ - bosch,bma150
+ - bosch,bma180
+ - bosch,bma250
+ - bosch,smb380
reg:
maxItems: 1
@@ -36,9 +46,21 @@ properties:
minItems: 1
maxItems: 2
description: |
- The first interrupt listed must be the one connected to the INT1 pin,
- the second (optional) interrupt listed must be the one connected to the
- INT2 pin (if available).
+ Without interrupt-names, the first interrupt listed must be the one
+ connected to the INT1 pin, the second (optional) interrupt listed must be
+ the one connected to the INT2 pin (if available). The type should be
+ IRQ_TYPE_EDGE_RISING.
+
+ BMC156 does not have an INT1 pin, therefore the first interrupt pin is
+ always treated as INT2.
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
mount-matrix:
description: an optional 3x3 mounting rotation matrix.
@@ -50,7 +72,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -63,11 +88,25 @@ examples:
reg = <0x08>;
vddio-supply = <&vddio>;
vdd-supply = <&vdd>;
- interrupts = <57 IRQ_TYPE_EDGE_FALLING>;
+ interrupts = <57 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ accelerometer@10 {
+ compatible = "bosch,bmc156_accel";
+ reg = <0x10>;
+ vddio-supply = <&vddio>;
+ vdd-supply = <&vdd>;
+ interrupts = <116 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT2";
};
};
- |
- # include <dt-bindings/interrupt-controller/irq.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml
index 8723a336229e..c5fedcf998f2 100644
--- a/Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml
@@ -40,7 +40,6 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml
index 911a1ae9c83f..3cb82576d758 100644
--- a/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml
@@ -17,13 +17,13 @@ description: |
properties:
compatible:
enum:
+ - bosch,bmi085-accel
- bosch,bmi088-accel
+ - bosch,bmi090l-accel
reg:
maxItems: 1
- spi-max-frequency: true
-
vdd-supply: true
vddio-supply: true
@@ -48,7 +48,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml b/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml
index 7c8f8bdc2333..cb31e75ba680 100644
--- a/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/fsl,mma7455.yaml
@@ -7,7 +7,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale MMA7455 and MMA7456 three axis accelerometers
maintainers:
- - Joachim Eastwood <manabian@gmail.com>
- Jonathan Cameron <jic23@kernel.org>
description:
@@ -37,16 +36,17 @@ properties:
maxItems: 2
items:
enum:
- - "INT1"
- - "INT2"
-
- spi-max-frequency: true
+ - INT1
+ - INT2
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml
new file mode 100644
index 000000000000..f07c70e51c45
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/kionix,kx022a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM/Kionix KX022A, KX132/134-1211 and KX132/134ACR-LBZ Accelerometers
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description: |
+ KX022A, KX132ACR-LBZ and KX132-1211 are 3-axis accelerometers supporting
+ +/- 2G, 4G, 8G and 16G ranges. The KX134ACR-LBZ and KX134-1211 support
+ +/- 8G, 16G, 32G and 64G. All the sensors also have variable output
+ data-rates and a hardware-fifo buffering. These accelerometers can be
+ accessed either via I2C or SPI.
+
+properties:
+ compatible:
+ enum:
+ - kionix,kx022a
+ - kionix,kx132-1211
+ - kionix,kx134-1211
+ - rohm,kx132acr-lbz
+ - rohm,kx134acr-lbz
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - enum: [INT1, INT2]
+ - const: INT2
+
+ vdd-supply: true
+ io-vdd-supply: true
+
+ mount-matrix:
+ description: |
+ an optional 3x3 mounting rotation matrix.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ accel@1f {
+ compatible = "kionix,kx022a";
+ reg = <0x1f>;
+
+ interrupt-parent = <&gpio1>;
+ interrupts = <29 IRQ_TYPE_LEVEL_LOW>;
+ interrupt-names = "INT1";
+
+ io-vdd-supply = <&iovdd>;
+ vdd-supply = <&vdd>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml
index 52fa0f7c2d0e..951a3a2ba8fc 100644
--- a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.yaml
@@ -16,11 +16,15 @@ properties:
- kionix,kxcj91008
- kionix,kxtj21009
- kionix,kxtf9
+ - kionix,kx022-1020
- kionix,kx023-1025
reg:
maxItems: 1
+ interrupts:
+ maxItems: 1
+
vdd-supply: true
vddio-supply: true
@@ -41,7 +45,7 @@ examples:
accel@f {
compatible = "kionix,kxtf9";
- reg = <0x0F>;
+ reg = <0xf>;
mount-matrix = "0", "1", "0",
"1", "0", "0",
"0", "0", "1";
diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml
index 390b87242fcb..53de921768ac 100644
--- a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml
@@ -29,13 +29,14 @@ properties:
mount-matrix:
description: an optional 3x3 mounting rotation matrix.
- spi-max-frequency: true
-
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -56,7 +57,6 @@ examples:
};
};
- |
- # include <dt-bindings/interrupt-controller/irq.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/accel/lis302.txt b/Documentation/devicetree/bindings/iio/accel/lis302.txt
index 764e28ec1a0a..457539647f36 100644
--- a/Documentation/devicetree/bindings/iio/accel/lis302.txt
+++ b/Documentation/devicetree/bindings/iio/accel/lis302.txt
@@ -36,7 +36,7 @@ Optional properties for all bus drivers:
- st,irq{1,2}-disable: disable IRQ 1/2
- st,irq{1,2}-ff-wu-1: raise IRQ 1/2 on FF_WU_1 condition
- st,irq{1,2}-ff-wu-2: raise IRQ 1/2 on FF_WU_2 condition
- - st,irq{1,2}-data-ready: raise IRQ 1/2 on data ready contition
+ - st,irq{1,2}-data-ready: raise IRQ 1/2 on data ready condition
- st,irq{1,2}-click: raise IRQ 1/2 on click condition
- st,irq-open-drain: consider IRQ lines open-drain
- st,irq-active-low: make IRQ lines active low
diff --git a/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml b/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml
new file mode 100644
index 000000000000..d530ec041fe7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/accel/memsensing,msa311.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/accel/memsensing,msa311.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MEMSensing digital 3-Axis accelerometer
+
+maintainers:
+ - Dmitry Rokosov <ddrokosov@sberdevices.ru>
+
+description: |
+ MSA311 is a tri-axial, low-g accelerometer with I2C digital output for
+ sensitivity consumer applications. It has dynamical user selectable full
+ scales range of +-2g/+-4g/+-8g/+-16g and allows acceleration measurements
+ with output data rates from 1Hz to 1000Hz.
+ Datasheet can be found at following URL
+ https://cdn-shop.adafruit.com/product-files/5309/MSA311-V1.1-ENG.pdf
+
+properties:
+ compatible:
+ const: memsensing,msa311
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ accelerometer@62 {
+ compatible = "memsensing,msa311";
+ reg = <0x62>;
+ interrupt-parent = <&gpio_intc>;
+ interrupts = <29 IRQ_TYPE_EDGE_RISING>;
+ vdd-supply = <&vcc_5v>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/accel/murata,sca3300.yaml b/Documentation/devicetree/bindings/iio/accel/murata,sca3300.yaml
index 55fd3548e3b6..00c990caa1e4 100644
--- a/Documentation/devicetree/bindings/iio/accel/murata,sca3300.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/murata,sca3300.yaml
@@ -17,6 +17,7 @@ properties:
compatible:
enum:
- murata,sca3300
+ - murata,scl3300
reg:
maxItems: 1
@@ -28,7 +29,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml b/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml
index ad529ab2c6e2..c175f4c4cbdb 100644
--- a/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml
+++ b/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml
@@ -14,12 +14,20 @@ description: |
SPI and I2C interface.
https://www.nxp.com/docs/en/data-sheet/FXLS8962AF.pdf
https://www.nxp.com/docs/en/data-sheet/FXLS8964AF.pdf
+ https://www.nxp.com/docs/en/data-sheet/FXLS8967AF.pdf
+ https://www.nxp.com/docs/en/data-sheet/FXLS8974CF.pdf
properties:
compatible:
- enum:
- - nxp,fxls8962af
- - nxp,fxls8964af
+ oneOf:
+ - enum:
+ - nxp,fxls8962af
+ - nxp,fxls8964af
+ - items:
+ - enum:
+ - nxp,fxls8967af
+ - nxp,fxls8974cf
+ - const: nxp,fxls8962af
reg:
maxItems: 1
@@ -27,8 +35,6 @@ properties:
vdd-supply:
description: phandle to the regulator that provides power to the accelerometer
- spi-max-frequency: true
-
interrupts:
maxItems: 1
@@ -40,16 +46,24 @@ properties:
drive-open-drain:
type: boolean
+ wakeup-source:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable wake on accelerometer event
+
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -60,11 +74,12 @@ examples:
interrupt-parent = <&gpio0>;
interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
interrupt-names = "INT1";
+ wakeup-source;
};
};
- |
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/adc/adc.yaml b/Documentation/devicetree/bindings/iio/adc/adc.yaml
index db348fcbb52c..b9bc02b5b07a 100644
--- a/Documentation/devicetree/bindings/iio/adc/adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/adc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Generic IIO bindings for ADC channels
+title: IIO Common Properties for ADC Channels
maintainers:
- Jonathan Cameron <jic23@kernel.org>
@@ -22,7 +22,6 @@ properties:
maxItems: 1
label:
- $ref: /schemas/types.yaml#/definitions/string
description: Unique name to identify which channel this is.
bipolar:
@@ -38,6 +37,29 @@ properties:
to both the positive and negative inputs of a differential ADC.
The first value specifies the positive input pin, the second
specifies the negative input pin.
+ There are also some ADCs, where the differential channel has dedicated
+ positive and negative inputs which can be used to measure differential
+ voltage levels. For those setups, this property can be configured with
+ the 'reg' property for both inputs (i.e. diff-channels = <reg reg>).
+
+ single-channel:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ When devices combine single-ended and differential channels, allow the
+ channel for a single element to be specified, independent of reg (as for
+ differential channels). If this and diff-channels are not present reg
+ shall be used instead.
+
+ common-mode-channel:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Some ADCs have differential input pins that can be used to measure
+ single-ended or pseudo-differential inputs. This property can be used
+ in addition to single-channel to signal software that this channel is
+ not differential but still specify two inputs.
+
+ The input pair is specified by setting single-channel to the positive
+ input pin and common-mode-channel to the negative pin.
settling-time-us:
description:
@@ -51,4 +73,15 @@ properties:
device design and can interact with other characteristics such as
settling time.
+anyOf:
+ - oneOf:
+ - required:
+ - reg
+ - diff-channels
+ - required:
+ - reg
+ - single-channel
+ - required:
+ - reg
+
additionalProperties: true
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml
new file mode 100644
index 000000000000..96e01a97dd95
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml
@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD4000 and similar Analog to Digital Converters
+
+maintainers:
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+
+description: |
+ Analog Devices AD4000 family of Analog to Digital Converters with SPI support.
+ Specifications can be found at:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4000-4004-4008.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4001-4005.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4002-4006-4010.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4003-4007-4011.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4020-4021-4022.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/adaq4001.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/adaq4003.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7685.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7686.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7687.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7688.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7690.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7691.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7693.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7942.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7946.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7980.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7982.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7983.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7984.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7988-1_7988-5.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - adi,ad4000
+ - adi,ad4001
+ - adi,ad4002
+ - adi,ad4003
+ - adi,ad4020
+ - adi,adaq4001
+ - adi,adaq4003
+ - adi,ad7687
+ - adi,ad7691
+ - adi,ad7942
+ - adi,ad7946
+ - adi,ad7983
+ - items:
+ - enum:
+ - adi,ad4004
+ - adi,ad4008
+ - const: adi,ad4000
+ - items:
+ - enum:
+ - adi,ad4005
+ - const: adi,ad4001
+ - items:
+ - enum:
+ - adi,ad4006
+ - adi,ad4010
+ - const: adi,ad4002
+ - items:
+ - enum:
+ - adi,ad4007
+ - adi,ad4011
+ - const: adi,ad4003
+ - items:
+ - enum:
+ - adi,ad4021
+ - adi,ad4022
+ - const: adi,ad4020
+ - items:
+ - enum:
+ - adi,ad7685
+ - adi,ad7686
+ - adi,ad7980
+ - adi,ad7988-1
+ - adi,ad7988-5
+ - const: adi,ad7983
+ - items:
+ - enum:
+ - adi,ad7688
+ - adi,ad7693
+ - const: adi,ad7687
+ - items:
+ - enum:
+ - adi,ad7690
+ - adi,ad7982
+ - adi,ad7984
+ - const: adi,ad7691
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 102040816 # for VIO > 2.7 V, 81300813 for VIO > 1.7 V
+
+ adi,sdi-pin:
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ high, low, cs, sdi ]
+ default: sdi
+ description:
+ Describes how the ADC SDI pin is wired. A value of "sdi" indicates that
+ the ADC SDI is connected to host SDO. "high" indicates that the ADC SDI
+ pin is hard-wired to logic high (VIO). "low" indicates that it is
+ hard-wired low (GND). "cs" indicates that the ADC SDI pin is connected to
+ the host CS line.
+
+ '#daisy-chained-devices': true
+
+ vdd-supply:
+ description: A 1.8V supply that powers the chip (VDD).
+
+ vio-supply:
+ description:
+ A 1.8V to 5.5V supply for the digital inputs and outputs (VIO).
+
+ ref-supply:
+ description:
+ A 2.5 to 5V supply for the external reference voltage (REF).
+
+ cnv-gpios:
+ description:
+ When provided, this property indicates the GPIO that is connected to the
+ CNV pin.
+ maxItems: 1
+
+ adi,high-z-input:
+ type: boolean
+ description:
+ High-Z mode allows the amplifier and RC filter in front of the ADC to be
+ chosen based on the signal bandwidth of interest, rather than the settling
+ requirements of the switched capacitor SAR ADC inputs.
+
+ adi,gain-milli:
+ description: |
+ The hardware gain applied to the ADC input (in milli units).
+ The gain provided by the ADC input scaler is defined by the hardware
+ connections between chip pins OUT+, R1K-, R1K1-, R1K+, R1K1+, and OUT-.
+ If not present, default to 1000 (no actual gain applied).
+ $ref: /schemas/types.yaml#/definitions/uint16
+ enum: [454, 909, 1000, 1900]
+ default: 1000
+
+ interrupts:
+ description:
+ The SDO pin can also function as a busy indicator. This node should be
+ connected to an interrupt that is triggered when the SDO line goes low
+ while the SDI line is high and the CNV line is low ("3-wire" mode) or the
+ SDI line is low and the CNV line is high ("4-wire" mode); or when the SDO
+ line goes high while the SDI and CNV lines are high (chain mode),
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vio-supply
+ - ref-supply
+
+allOf:
+ # Single-channel PulSAR devices have SDI either tied to VIO, GND, or host CS.
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7687
+ - adi,ad7691
+ - adi,ad7942
+ - adi,ad7946
+ - adi,ad7983
+ then:
+ properties:
+ adi,sdi-pin:
+ enum: [ high, low, cs ]
+ default: cs
+ # The configuration register can only be accessed if SDI is connected to MOSI
+ - if:
+ required:
+ - adi,sdi-pin
+ then:
+ properties:
+ adi,high-z-input: false
+ # chain mode has lower SCLK max rate
+ - if:
+ required:
+ - '#daisy-chained-devices'
+ then:
+ properties:
+ spi-max-frequency:
+ maximum: 50000000 # for VIO > 2.7 V, 40000000 for VIO > 1.7 V
+ # Gain property only applies to ADAQ devices
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - adi,adaq4001
+ - adi,adaq4003
+ then:
+ properties:
+ adi,gain-milli: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc@0 {
+ compatible = "adi,ad4020";
+ reg = <0>;
+ spi-max-frequency = <71000000>;
+ vdd-supply = <&supply_1_8V>;
+ vio-supply = <&supply_1_8V>;
+ ref-supply = <&supply_5V>;
+ adi,sdi-pin = "cs";
+ cnv-gpios = <&gpio0 88 GPIO_ACTIVE_HIGH>;
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc@0 {
+ compatible = "adi,adaq4003";
+ reg = <0>;
+ spi-max-frequency = <80000000>;
+ vdd-supply = <&supply_1_8V>;
+ vio-supply = <&supply_1_8V>;
+ ref-supply = <&supply_5V>;
+ adi,high-z-input;
+ adi,gain-milli = /bits/ 16 <454>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4030.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4030.yaml
new file mode 100644
index 000000000000..54e7349317b7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4030.yaml
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2024 Analog Devices Inc.
+# Copyright 2024 BayLibre, SAS.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4030.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD4030 and AD4630 ADC families
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Nuno Sa <nuno.sa@analog.com>
+
+description: |
+ Analog Devices AD4030 single channel and AD4630/AD4632 dual channel precision
+ SAR ADC families
+
+ * https://www.analog.com/media/en/technical-documentation/data-sheets/ad4030-24-4032-24.pdf
+ * https://www.analog.com/media/en/technical-documentation/data-sheets/ad4630-24_ad4632-24.pdf
+ * https://www.analog.com/media/en/technical-documentation/data-sheets/ad4630-16-4632-16.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4030-24
+ - adi,ad4032-24
+ - adi,ad4630-16
+ - adi,ad4630-24
+ - adi,ad4632-16
+ - adi,ad4632-24
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 102040816
+
+ spi-rx-bus-width:
+ enum: [1, 2, 4]
+
+ vdd-5v-supply: true
+ vdd-1v8-supply: true
+ vio-supply: true
+
+ ref-supply:
+ description:
+ Optional External unbuffered reference. Used when refin-supply is not
+ connected.
+
+ refin-supply:
+ description:
+ Internal buffered Reference. Used when ref-supply is not connected.
+
+ cnv-gpios:
+ description:
+ The Convert Input (CNV). It initiates the sampling conversions.
+ maxItems: 1
+
+ reset-gpios:
+ description:
+ The Reset Input (/RST). Used for asynchronous device reset.
+ maxItems: 1
+
+ interrupts:
+ description:
+ The BUSY pin is used to signal that the conversions results are available
+ to be transferred when in SPI Clocking Mode. This nodes should be
+ connected to an interrupt that is triggered when the BUSY line goes low.
+ maxItems: 1
+
+ interrupt-names:
+ const: busy
+
+required:
+ - compatible
+ - reg
+ - vdd-5v-supply
+ - vdd-1v8-supply
+ - vio-supply
+ - cnv-gpios
+
+oneOf:
+ - required:
+ - ref-supply
+ - required:
+ - refin-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4030-24";
+ reg = <0>;
+ spi-max-frequency = <80000000>;
+ vdd-5v-supply = <&supply_5V>;
+ vdd-1v8-supply = <&supply_1_8V>;
+ vio-supply = <&supply_1_8V>;
+ ref-supply = <&supply_5V>;
+ cnv-gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4080.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4080.yaml
new file mode 100644
index 000000000000..ccd6a0ac1539
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4080.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2025 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4080.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD4080 20-Bit, 40 MSPS, Differential SAR ADC
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ The AD4080 is a high speed, low noise, low distortion, 20-bit, Easy Drive,
+ successive approximation register (SAR) analog-to-digital converter (ADC).
+ Maintaining high performance (signal-to-noise and distortion (SINAD) ratio
+ > 90 dBFS) at signal frequencies in excess of 1 MHz enables the AD4080 to
+ service a wide variety of precision, wide bandwidth data acquisition
+ applications.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4080.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4080
+ - adi,ad4081
+ - adi,ad4083
+ - adi,ad4084
+ - adi,ad4086
+ - adi,ad4087
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ description: Configuration of the SPI bus.
+ maximum: 50000000
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: cnv
+
+ vdd33-supply: true
+
+ vdd11-supply: true
+
+ vddldo-supply: true
+
+ iovdd-supply: true
+
+ vrefin-supply: true
+
+ io-backends:
+ maxItems: 1
+
+ adi,lvds-cnv-enable:
+ description: Enable the LVDS signal type on the CNV pin. Default is CMOS.
+ type: boolean
+
+ adi,num-lanes:
+ description:
+ Number of lanes on which the data is sent on the output (DA, DB pins).
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2]
+ default: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - vdd33-supply
+ - vrefin-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4080";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ vdd33-supply = <&vdd33>;
+ vddldo-supply = <&vddldo>;
+ vrefin-supply = <&vrefin>;
+ clocks = <&cnv>;
+ clock-names = "cnv";
+ io-backends = <&iio_backend>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4130.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4130.yaml
new file mode 100644
index 000000000000..d00690a8d3fb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4130.yaml
@@ -0,0 +1,262 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2022 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4130.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD4130 ADC device driver
+
+maintainers:
+ - Cosmin Tanislav <cosmin.tanislav@analog.com>
+
+description: |
+ Bindings for the Analog Devices AD4130 ADC. Datasheet can be found here:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD4130-8.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4130
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description: phandle to the master clock (mclk)
+
+ clock-names:
+ items:
+ - const: mclk
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-names:
+ description: |
+ Specify which interrupt pin should be configured as Data Ready / FIFO
+ interrupt.
+ Default if not supplied is int.
+ enum:
+ - int
+ - clk
+ - p2
+ - dout
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ '#clock-cells':
+ const: 0
+
+ clock-output-names:
+ maxItems: 1
+
+ refin1-supply:
+ description: refin1 supply. Can be used as reference for conversion.
+
+ refin2-supply:
+ description: refin2 supply. Can be used as reference for conversion.
+
+ avdd-supply:
+ description: AVDD voltage supply. Can be used as reference for conversion.
+
+ iovdd-supply:
+ description: IOVDD voltage supply. Used for the chip interface.
+
+ spi-max-frequency:
+ maximum: 5000000
+
+ adi,ext-clk-freq-hz:
+ description: Specify the frequency of the external clock.
+ enum: [76800, 153600]
+ default: 76800
+
+ adi,bipolar:
+ description: Specify if the device should be used in bipolar mode.
+ type: boolean
+
+ adi,vbias-pins:
+ description: Analog inputs to apply a voltage bias of (AVDD − AVSS) / 2 to.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 16
+ items:
+ minimum: 0
+ maximum: 15
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+patternProperties:
+ "^channel@([0-9a-f])$":
+ type: object
+ $ref: adc.yaml
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: The channel number.
+ minimum: 0
+ maximum: 15
+
+ diff-channels:
+ description: |
+ Besides the analog inputs available, internal inputs can be used.
+ 16: Internal temperature sensor.
+ 17: AVSS
+ 18: Internal reference
+ 19: DGND
+ 20: (AVDD − AVSS)/6+
+ 21: (AVDD − AVSS)/6-
+ 22: (IOVDD − DGND)/6+
+ 23: (IOVDD − DGND)/6-
+ 24: (ALDO − AVSS)/6+
+ 25: (ALDO − AVSS)/6-
+ 26: (DLDO − DGND)/6+
+ 27: (DLDO − DGND)/6-
+ 28: V_MV_P
+ 29: V_MV_M
+ items:
+ minimum: 0
+ maximum: 29
+
+ adi,reference-select:
+ description: |
+ Select the reference source to use when converting on the
+ specific channel. Valid values are:
+ 0: REFIN1(+)/REFIN1(−)
+ 1: REFIN2(+)/REFIN2(−)
+ 2: REFOUT/AVSS (Internal reference)
+ 3: AVDD/AVSS
+ If not specified, REFIN1 is used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ default: 0
+
+ adi,excitation-pin-0:
+ description: |
+ Analog input to apply excitation current to while the channel
+ is active.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ default: 0
+
+ adi,excitation-pin-1:
+ description: |
+ Analog input to apply excitation current to while this channel
+ is active.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ default: 0
+
+ adi,excitation-current-0-nanoamp:
+ description: |
+ Excitation current in nanoamps to be applied to pin specified in
+ adi,excitation-pin-0 while this channel is active.
+ enum: [0, 100, 10000, 20000, 50000, 100000, 150000, 200000]
+ default: 0
+
+ adi,excitation-current-1-nanoamp:
+ description: |
+ Excitation current in nanoamps to be applied to pin specified in
+ adi,excitation-pin-1 while this channel is active.
+ enum: [0, 100, 10000, 20000, 50000, 100000, 150000, 200000]
+ default: 0
+
+ adi,burnout-current-nanoamp:
+ description: |
+ Burnout current in nanoamps to be applied for this channel.
+ enum: [0, 500, 2000, 4000]
+ default: 0
+
+ adi,buffered-positive:
+ description: Enable buffered mode for positive input.
+ type: boolean
+
+ adi,buffered-negative:
+ description: Enable buffered mode for negative input.
+ type: boolean
+
+ required:
+ - reg
+ - diff-channels
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4130";
+ reg = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ spi-max-frequency = <5000000>;
+ interrupts = <27 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+
+ channel@0 {
+ reg = <0>;
+
+ adi,reference-select = <2>;
+
+ /* AIN8, AIN9 */
+ diff-channels = <8 9>;
+ };
+
+ channel@1 {
+ reg = <1>;
+
+ adi,reference-select = <2>;
+
+ /* AIN10, AIN11 */
+ diff-channels = <10 11>;
+ };
+
+ channel@2 {
+ reg = <2>;
+
+ adi,reference-select = <2>;
+
+ /* Temperature Sensor, DGND */
+ diff-channels = <16 19>;
+ };
+
+ channel@3 {
+ reg = <3>;
+
+ adi,reference-select = <2>;
+
+ /* Internal reference, DGND */
+ diff-channels = <18 19>;
+ };
+
+ channel@4 {
+ reg = <4>;
+
+ adi,reference-select = <2>;
+
+ /* DGND, DGND */
+ diff-channels = <19 19>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4170-4.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4170-4.yaml
new file mode 100644
index 000000000000..da93213d12d4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4170-4.yaml
@@ -0,0 +1,554 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4170-4.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD4170-4 and similar Analog to Digital Converters
+
+maintainers:
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+
+description: |
+ Analog Devices AD4170-4 series of Sigma-delta Analog to Digital Converters.
+ Specifications can be found at:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4170-4.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4190-4.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4195-4.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+$defs:
+ reference-buffer:
+ description: |
+ Enable precharge buffer, full buffer, or skip reference buffering of
+ the positive/negative voltage reference. Because the output impedance
+ of the source driving the voltage reference inputs may be dynamic,
+ resistive/capacitive combinations of those inputs can cause DC gain
+ errors if the reference inputs go unbuffered into the ADC. Enable
+ reference buffering if the provided reference source has dynamic high
+ impedance output. Note the absolute voltage allowed on REFINn+ and REFINn-
+ inputs is from AVSS - 50 mV to AVDD + 50 mV when the reference buffers are
+ disabled but narrows to AVSS to AVDD when reference buffering is enabled
+ or in precharge mode.
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ precharge, full, disabled ]
+ default: full
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4170-4
+ - adi,ad4190-4
+ - adi,ad4195-4
+
+ avss-supply:
+ description:
+ Reference voltage supply for AVSS. A −2.625V minimum and 0V maximum supply
+ that powers the chip. If not provided, AVSS is assumed to be at system
+ ground (0V).
+
+ avdd-supply:
+ description:
+ A supply of 4.75V to 5.25V relative to AVSS that powers the chip (AVDD).
+
+ iovdd-supply:
+ description: 1.7V to 5.25V reference supply to the serial interface (IOVDD).
+
+ refin1p-supply:
+ description: REFIN+ supply that can be used as reference for conversion.
+
+ refin1n-supply:
+ description: REFIN- supply that can be used as reference for conversion.
+
+ refin2p-supply:
+ description: REFIN2+ supply that can be used as reference for conversion.
+
+ refin2n-supply:
+ description: REFIN2- supply that can be used as reference for conversion.
+
+ spi-cpol: true
+
+ spi-cpha: true
+
+ interrupts:
+ description:
+ Interrupt for signaling the completion of conversion results. The data
+ ready signal (RDY) used as interrupt is by default provided on the SDO
+ pin. Alternatively, it can be provided on the DIG_AUX1 pin in which case
+ the chip disables the RDY function on SDO. Thus, there can be only one
+ data ready interrupt enabled at a time.
+
+ interrupt-names:
+ description:
+ Specify which pin should be configured as Data Ready interrupt.
+ enum:
+ - sdo
+ - dig_aux1
+
+ clocks:
+ maxItems: 1
+ description:
+ Optional external clock source. Can specify either an external clock or
+ external crystal.
+
+ clock-names:
+ enum:
+ - ext-clk
+ - xtal
+ default: ext-clk
+
+ '#clock-cells':
+ const: 0
+
+ clock-output-names:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description: |
+ The first cell is for the GPIO number: 0 to 3.
+ The second cell takes standard GPIO flags.
+
+ ldac-gpios:
+ description:
+ GPIO connected to DIG_AUX2 pin to be used as LDAC toggle to control the
+ transfer of data from the DAC_INPUT_A register to the DAC.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ adi,vbias-pins:
+ description: Analog inputs to apply a voltage bias of (AVDD − AVSS) / 2 to.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 9
+ items:
+ minimum: 0
+ maximum: 8
+
+allOf:
+ # Some devices don't have integrated DAC
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad4190-4
+ - adi,ad4195-4
+ then:
+ properties:
+ ldac-gpios: false
+
+ # Require to specify the interrupt pin when using interrupts
+ - if:
+ required:
+ - interrupts
+ then:
+ required:
+ - interrupt-names
+
+ # If an external clock is set, the internal clock cannot go out and vice versa
+ - oneOf:
+ - required: [clocks]
+ properties:
+ '#clock-cells': false
+ - required: ['#clock-cells']
+ properties:
+ clocks: false
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - iovdd-supply
+ - spi-cpol
+ - spi-cpha
+
+unevaluatedProperties: false
+
+patternProperties:
+ "^channel@[0-9a-f]$":
+ $ref: /schemas/iio/adc/adc.yaml#
+ unevaluatedProperties: false
+ description:
+ Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description:
+ The channel number.
+ minimum: 0
+ maximum: 15
+
+ diff-channels:
+ description: |
+ This property is used for defining the inputs of a differential
+ voltage channel. The first value is the positive input and the second
+ value is the negative input of the channel.
+
+ Besides the analog input pins AIN0 to AIN8, there are special inputs
+ that can be selected with the following values:
+ 17: Internal temperature sensor
+ 18: (AVDD-AVSS)/5
+ 19: (IOVDD-DGND)/5
+ 20: DAC output
+ 21: ALDO
+ 22: DLDO
+ 23: AVSS
+ 24: DGND
+ 25: REFIN+
+ 26: REFIN-
+ 27: REFIN2+
+ 28: REFIN2-
+ 29: REFOUT
+ For the internal temperature sensor, use the input number for both
+ inputs (i.e. diff-channels = <17 17>).
+ items:
+ enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 17, 18, 19, 20, 21, 22, 23, 24, 25,
+ 26, 27, 28, 29]
+
+ adi,reference-select:
+ description: |
+ Select the reference source to use when converting on the
+ specific channel. Valid values are:
+ 0: REFIN+/REFIN-
+ 1: REFIN2+/REFIN2−
+ 2: REFOUT/AVSS (internal reference)
+ 3: AVDD/AVSS
+ If not specified, REFOUT/AVSS is used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ default: 1
+
+ adi,positive-reference-buffer:
+ $ref: '#/$defs/reference-buffer'
+
+ adi,negative-reference-buffer:
+ $ref: '#/$defs/reference-buffer'
+
+ adi,sensor-type:
+ description:
+ The AD4170-4 and similar designs have features to aid interfacing with
+ load cell weigh scale, RTD, and thermocouple sensors. Each of those
+ sensor types requires either distinct wiring configuration or
+ external circuitry for proper sensor operation and can use different
+ ADC chip functionality on their setups. A key characteristic of those
+ external sensors is that they must be excited either by voltage supply
+ or by ADC chip excitation signals. The sensor can then be read through
+ a pair of analog inputs. This property specifies which particular
+ sensor type is connected to the ADC so it can be properly setup and
+ handled. Omit this property for conventional (not weigh scale, RTD, or
+ thermocouple) ADC channel setups.
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ weighscale, rtd, thermocouple ]
+
+ adi,excitation-pin-0:
+ description:
+ Analog input to apply excitation current to while the channel
+ is active.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 20
+ default: 0
+
+ adi,excitation-pin-1:
+ description:
+ Analog input to apply excitation current to while the channel
+ is active.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 20
+ default: 0
+
+ adi,excitation-pin-2:
+ description:
+ Analog input to apply excitation current to while the channel
+ is active.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 20
+ default: 0
+
+ adi,excitation-pin-3:
+ description:
+ Analog input to apply excitation current to while the channel
+ is active.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 20
+ default: 0
+
+ adi,excitation-current-0-microamp:
+ description:
+ Excitation current in microamperes to be applied to pin specified in
+ adi,excitation-pin-0 while this channel is active.
+ enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
+ default: 0
+
+ adi,excitation-current-1-microamp:
+ description:
+ Excitation current in microamperes to be applied to pin specified in
+ adi,excitation-pin-1 while this channel is active.
+ enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
+ default: 0
+
+ adi,excitation-current-2-microamp:
+ description:
+ Excitation current in microamperes to be applied to pin specified in
+ adi,excitation-pin-2 while this channel is active.
+ enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
+ default: 0
+
+ adi,excitation-current-3-microamp:
+ description:
+ Excitation current in microamperes to be applied to pin specified in
+ adi,excitation-pin-3 while this channel is active.
+ enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
+ default: 0
+
+ adi,excitation-ac:
+ type: boolean
+ description:
+ Whether the external sensor has to be AC or DC excited. When omitted,
+ it is DC excited.
+
+ allOf:
+ - oneOf:
+ - required: [single-channel, common-mode-channel]
+ properties:
+ diff-channels: false
+ - required: [diff-channels]
+ properties:
+ single-channel: false
+ common-mode-channel: false
+ # Usual ADC channels don't need external circuitry excitation.
+ - if:
+ not:
+ required:
+ - adi,sensor-type
+ then:
+ properties:
+ adi,excitation-pin-0: false
+ adi,excitation-pin-1: false
+ adi,excitation-pin-2: false
+ adi,excitation-pin-3: false
+ adi,excitation-current-0-microamp: false
+ adi,excitation-current-1-microamp: false
+ adi,excitation-current-2-microamp: false
+ adi,excitation-current-3-microamp: false
+ adi,excitation-ac: false
+ # Weigh scale bridge AC excited with one pair of predefined signals.
+ - if:
+ allOf:
+ - properties:
+ adi,sensor-type:
+ contains:
+ const: weighscale
+ - required:
+ - adi,excitation-ac
+ - adi,excitation-pin-2
+ - adi,excitation-pin-3
+ - not:
+ required:
+ - adi,excitation-current-2-microamp
+ - adi,excitation-current-3-microamp
+ then:
+ properties:
+ adi,excitation-pin-2:
+ const: 19
+ adi,excitation-pin-3:
+ const: 20
+ # Weigh scale bridge AC excited with two pairs of predefined signals.
+ - if:
+ allOf:
+ - properties:
+ adi,sensor-type:
+ contains:
+ const: weighscale
+ - required:
+ - adi,excitation-ac
+ - adi,excitation-pin-0
+ - adi,excitation-pin-1
+ - adi,excitation-pin-2
+ - adi,excitation-pin-3
+ - not:
+ required:
+ - adi,excitation-current-0-microamp
+ - adi,excitation-current-1-microamp
+ - adi,excitation-current-2-microamp
+ - adi,excitation-current-3-microamp
+ then:
+ properties:
+ adi,excitation-pin-0:
+ const: 17
+ adi,excitation-pin-1:
+ const: 18
+ adi,excitation-pin-2:
+ const: 19
+ adi,excitation-pin-3:
+ const: 20
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4170-4";
+ reg = <0>;
+ spi-max-frequency = <20000000>;
+ spi-cpol;
+ spi-cpha;
+ avdd-supply = <&avdd>;
+ iovdd-supply = <&iovdd>;
+ clocks = <&clk>;
+ clock-names = "xtal";
+ interrupts = <0 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "dig_aux1";
+ adi,vbias-pins = <8>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ // Sample AIN0 with respect to DGND throughout AVDD/DGND input range
+ // Pseudo-differential unipolar
+ channel@0 {
+ reg = <0>;
+ single-channel = <0>;
+ common-mode-channel = <24>;
+ adi,reference-select = <3>;
+ };
+ // Weigh scale sensor
+ channel@1 {
+ reg = <1>;
+ bipolar;
+ diff-channels = <1 2>;
+ adi,reference-select = <0>;
+ adi,positive-reference-buffer = "precharge";
+ adi,negative-reference-buffer = "precharge";
+ adi,sensor-type = "weighscale";
+ adi,excitation-pin-2 = <19>;
+ adi,excitation-pin-3 = <20>;
+ adi,excitation-ac;
+ };
+ // RTD sensor
+ channel@2 {
+ reg = <2>;
+ bipolar;
+ diff-channels = <3 4>;
+ adi,reference-select = <0>;
+ adi,sensor-type = "rtd";
+ adi,excitation-pin-0 = <5>;
+ adi,excitation-pin-1 = <6>;
+ adi,excitation-current-0-microamp = <500>;
+ adi,excitation-current-1-microamp = <500>;
+ adi,excitation-ac;
+ };
+ // Thermocouple sensor
+ channel@3 {
+ reg = <3>;
+ bipolar;
+ diff-channels = <7 8>;
+ adi,reference-select = <0>;
+ adi,sensor-type = "thermocouple";
+ adi,excitation-pin-0 = <18>;
+ adi,excitation-current-0-microamp = <500>;
+ };
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4170-4";
+ reg = <0>;
+ spi-max-frequency = <20000000>;
+ spi-cpol;
+ spi-cpha;
+ avdd-supply = <&avdd>;
+ iovdd-supply = <&iovdd>;
+ #clock-cells = <0>;
+ clock-output-names = "ad4170-clk16mhz";
+ interrupts = <0 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "dig_aux1";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ // Sample AIN0 with respect to AIN1 throughout AVDD/AVSS input range
+ // Differential bipolar. If AVSS < 0V, differential true bipolar
+ channel@0 {
+ reg = <0>;
+ bipolar;
+ diff-channels = <0 1>;
+ adi,reference-select = <3>;
+ };
+ // Sample AIN2 with respect to DGND throughout AVDD/DGND input range
+ // Pseudo-differential unipolar
+ channel@1 {
+ reg = <1>;
+ single-channel = <2>;
+ common-mode-channel = <24>;
+ adi,reference-select = <3>;
+ };
+ // Sample AIN3 with respect to 2.5V throughout AVDD/AVSS input range
+ // Pseudo-differential bipolar
+ channel@2 {
+ reg = <2>;
+ bipolar;
+ single-channel = <3>;
+ common-mode-channel = <29>;
+ adi,reference-select = <3>;
+ };
+ // Sample AIN4 with respect to DGND throughout AVDD/AVSS input range
+ // Pseudo-differential bipolar
+ channel@3 {
+ reg = <3>;
+ bipolar;
+ single-channel = <4>;
+ common-mode-channel = <24>;
+ adi,reference-select = <3>;
+ };
+ // Sample AIN5 with respect to 2.5V throughout AVDD/AVSS input range
+ // Pseudo-differential unipolar (AD4170-4 datasheet page 46 example)
+ channel@4 {
+ reg = <4>;
+ single-channel = <5>;
+ common-mode-channel = <29>;
+ adi,reference-select = <3>;
+ };
+ // Sample AIN6 with respect to 2.5V throughout REFIN+/REFIN- input range
+ // Pseudo-differential bipolar
+ channel@5 {
+ reg = <5>;
+ bipolar;
+ single-channel = <6>;
+ common-mode-channel = <29>;
+ adi,reference-select = <0>;
+ };
+ // Weigh scale sensor
+ channel@6 {
+ reg = <6>;
+ bipolar;
+ diff-channels = <7 8>;
+ adi,reference-select = <0>;
+ adi,sensor-type = "weighscale";
+ adi,excitation-pin-0 = <17>;
+ adi,excitation-pin-1 = <18>;
+ adi,excitation-pin-2 = <19>;
+ adi,excitation-pin-3 = <20>;
+ adi,excitation-ac;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml
new file mode 100644
index 000000000000..cbde7a0505d2
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml
@@ -0,0 +1,268 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4695.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Easy Drive Multiplexed SAR Analog to Digital Converters
+
+maintainers:
+ - Michael Hennerich <Michael.Hennerich@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ A family of similar multi-channel analog to digital converters with SPI bus.
+
+ * https://www.analog.com/en/products/ad4695.html
+ * https://www.analog.com/en/products/ad4696.html
+ * https://www.analog.com/en/products/ad4697.html
+ * https://www.analog.com/en/products/ad4698.html
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4695
+ - adi,ad4696
+ - adi,ad4697
+ - adi,ad4698
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 80000000
+
+ spi-cpol: true
+ spi-cpha: true
+
+ spi-rx-bus-width:
+ minimum: 1
+ maximum: 4
+
+ avdd-supply:
+ description: Analog power supply.
+
+ vio-supply:
+ description: I/O pin power supply.
+
+ ldo-in-supply:
+ description: Internal LDO Input. Mutually exclusive with vdd-supply.
+
+ vdd-supply:
+ description: Core power supply. Mutually exclusive with ldo-in-supply.
+
+ ref-supply:
+ description:
+ External reference voltage. Mutually exclusive with refin-supply.
+
+ refin-supply:
+ description:
+ Internal reference buffer input. Mutually exclusive with ref-supply.
+
+ com-supply:
+ description: Common voltage supply for pseudo-differential analog inputs.
+
+ adi,no-ref-current-limit:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ When this flag is present, the REF Overvoltage Reduced Current protection
+ is disabled.
+
+ adi,no-ref-high-z:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable this flag if the ref-supply requires Reference Input High-Z Mode
+ to be disabled for proper operation.
+
+ cnv-gpios:
+ description: The Convert Input (CNV). If omitted, CNV is tied to SPI CS.
+ maxItems: 1
+
+ reset-gpios:
+ description: The Reset Input (RESET). Should be configured GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ pwms:
+ description: PWM signal connected to the CNV pin.
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ items:
+ - description: Signal coming from the BSY_ALT_GP0 pin (ALERT or BUSY).
+ - description: Signal coming from the GP2 pin (ALERT).
+ - description: Signal coming from the GP3 pin (BUSY).
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: gp0
+ - const: gp2
+ - const: gp3
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description: |
+ The first cell is the GPn number: 0 to 3.
+ The second cell takes standard GPIO flags.
+
+ '#trigger-source-cells':
+ description: |
+ First cell indicates the output signal: 0 = BUSY, 1 = ALERT.
+ Second cell indicates which GPn pin is used: 0, 2 or 3.
+
+ For convenience, macros for these values are available in
+ dt-bindings/iio/adc/adi,ad4695.h.
+ const: 2
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^in(?:[13579]|1[135])-supply$":
+ description:
+ Optional voltage supply for odd numbered channels when they are used as
+ the negative input for a pseudo-differential channel.
+
+ "^channel@[0-9a-f]$":
+ type: object
+ $ref: adc.yaml
+ unevaluatedProperties: false
+ description:
+ Describes each individual channel. In addition the properties defined
+ below, bipolar from adc.yaml is also supported.
+
+ properties:
+ reg:
+ maximum: 15
+
+ common-mode-channel:
+ description:
+ Describes the common mode channel for single channels. 0xFF is REFGND
+ and OxFE is COM. Macros are available for these values in
+ dt-bindings/iio/adc/adi,ad4695.h. Values 1 to 15 correspond to INx
+ inputs. Only odd numbered INx inputs can be used as common mode
+ channels.
+ enum: [1, 3, 5, 7, 9, 11, 13, 15, 0xFE, 0xFF]
+ default: 0xFF
+
+ adi,no-high-z:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable this flag if the input pin requires the Analog Input High-Z
+ Mode to be disabled for proper operation.
+
+ required:
+ - reg
+
+ allOf:
+ # bipolar mode can't be used with REFGND
+ - if:
+ properties:
+ common-mode-channel:
+ const: 0xFF
+ then:
+ properties:
+ bipolar: false
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - vio-supply
+
+allOf:
+ - oneOf:
+ - required:
+ - ldo-in-supply
+ - required:
+ - vdd-supply
+
+ - oneOf:
+ - required:
+ - ref-supply
+ - required:
+ - refin-supply
+
+ # the internal reference buffer always requires high-z mode
+ - if:
+ required:
+ - refin-supply
+ then:
+ properties:
+ adi,no-ref-high-z: false
+
+ # limit channels for 8-channel chips
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad4697
+ - adi,ad4698
+ then:
+ patternProperties:
+ "^in(?:9|1[135])-supply$": false
+ "^channel@[0-7]$":
+ properties:
+ reg:
+ maximum: 7
+ common-mode-channel:
+ enum: [1, 3, 5, 7, 0xFE, 0xFF]
+ "^channel@[8-9a-f]$": false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/iio/adc/adi,ad4695.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4695";
+ reg = <0>;
+ spi-cpol;
+ spi-cpha;
+ spi-max-frequency = <80000000>;
+ avdd-supply = <&power_supply>;
+ ldo-in-supply = <&power_supply>;
+ vio-supply = <&io_supply>;
+ refin-supply = <&supply_5V>;
+ com-supply = <&supply_2V5>;
+ in3-supply = <&supply_2V5>;
+ reset-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Pseudo-differential channel between IN0 and REFGND. */
+ channel@0 {
+ reg = <0>;
+ };
+
+ /* Pseudo-differential channel between IN1 and COM. */
+ channel@1 {
+ reg = <1>;
+ common-mode-channel = <AD4695_COMMON_MODE_COM>;
+ bipolar;
+ };
+
+ /* Pseudo-differential channel between IN2 and IN3. */
+ channel@2 {
+ reg = <2>;
+ common-mode-channel = <3>;
+ bipolar;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml
new file mode 100644
index 000000000000..b107322e0ea3
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4851.yaml
@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2024 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad4851.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD485X family
+
+maintainers:
+ - Sergiu Cuciurean <sergiu.cuciurean@analog.com>
+ - Dragos Bogdan <dragos.bogdan@analog.com>
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Analog Devices AD485X fully buffered, 8-channel simultaneous sampling,
+ 16/20-bit, 1 MSPS data acquisition system (DAS) with differential, wide
+ common-mode range inputs.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4855.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4856.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4857.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad4858.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4851
+ - adi,ad4852
+ - adi,ad4853
+ - adi,ad4854
+ - adi,ad4855
+ - adi,ad4856
+ - adi,ad4857
+ - adi,ad4858
+ - adi,ad4858i
+
+ reg:
+ maxItems: 1
+
+ vcc-supply: true
+
+ vee-supply: true
+
+ vdd-supply: true
+
+ vddh-supply: true
+
+ vddl-supply: true
+
+ vio-supply: true
+
+ vrefbuf-supply: true
+
+ vrefio-supply: true
+
+ pwms:
+ description: PWM connected to the CNV pin.
+ maxItems: 1
+
+ io-backends:
+ maxItems: 1
+
+ pd-gpios:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 25000000
+
+ spi-3wire: true
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel(@[0-7])?$":
+ $ref: adc.yaml
+ type: object
+ description: Represents the channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description:
+ The channel number, as specified in the datasheet (from 0 to 7).
+ minimum: 0
+ maximum: 7
+
+ diff-channels:
+ description:
+ Each channel can be configured as a bipolar differential channel.
+ The ADC uses the same positive and negative inputs for this.
+ This property must be specified as 'reg' (or the channel number) for
+ both positive and negative inputs (i.e. diff-channels = <reg reg>).
+ Since the configuration is bipolar differential, the 'bipolar'
+ property is required.
+ items:
+ minimum: 0
+ maximum: 7
+
+ bipolar: true
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+ - vee-supply
+ - vdd-supply
+ - vio-supply
+ - pwms
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0{
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "adi,ad4858";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ vcc-supply = <&vcc>;
+ vdd-supply = <&vdd>;
+ vee-supply = <&vee>;
+ vddh-supply = <&vddh>;
+ vddl-supply = <&vddl>;
+ vio-supply = <&vio>;
+ pwms = <&pwm_gen 0 0>;
+ io-backends = <&iio_backend>;
+
+ channel@0 {
+ reg = <0>;
+ diff-channels = <0 0>;
+ bipolar;
+ };
+
+ channel@1 {
+ reg = <1>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml
index 31ffa275f5fa..705adbe88def 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml
@@ -4,51 +4,124 @@
$id: http://devicetree.org/schemas/iio/adc/adi,ad7091r5.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Analog Devices AD7091R5 4-Channel 12-Bit ADC
+title: Analog Devices AD7091R-2/-4/-5/-8 Multi-Channel 12-Bit ADCs
maintainers:
- - Beniamin Bia <beniamin.bia@analog.com>
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
description: |
- Analog Devices AD7091R5 4-Channel 12-Bit ADC
+ Analog Devices AD7091R5 4-Channel 12-Bit ADC supporting I2C interface
https://www.analog.com/media/en/technical-documentation/data-sheets/ad7091r-5.pdf
+ Analog Devices AD7091R-2/AD7091R-4/AD7091R-8 2-/4-/8-Channel 12-Bit ADCs
+ supporting SPI interface
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7091R-2_7091R-4_7091R-8.pdf
properties:
compatible:
enum:
+ - adi,ad7091r2
+ - adi,ad7091r4
- adi,ad7091r5
+ - adi,ad7091r8
reg:
maxItems: 1
+ vdd-supply:
+ description:
+ Provide VDD power to the sensor (VDD range is from 2.7V to 5.25V).
+
+ vdrive-supply:
+ description:
+ Determines the voltage level at which the interface logic will operate.
+ The V_drive voltage range is from 1.8V to 5.25V and must not exceed VDD by
+ more than 0.3V.
+
vref-supply:
description:
Phandle to the vref power supply
- interrupts:
+ convst-gpios:
+ description:
+ GPIO connected to the CONVST pin.
+ This logic input is used to initiate conversions on the analog
+ input channels.
maxItems: 1
+ reset-gpios:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Interrupt for signaling when conversion results exceed the high limit for
+ ADC readings or fall below the low limit for them. Interrupt source must
+ be attached to ALERT/BUSY/GPO0 pin.
+ maxItems: 1
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+ # AD7091R-2 does not have ALERT/BUSY/GPO pin
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7091r2
+ then:
+ properties:
+ interrupts: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7091r2
+ - adi,ad7091r4
+ - adi,ad7091r8
+ then:
+ required:
+ - convst-gpios
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
adc@2f {
- compatible = "adi,ad7091r5";
- reg = <0x2f>;
+ compatible = "adi,ad7091r5";
+ reg = <0x2f>;
+
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+ };
+ };
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
- interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
- interrupt-parent = <&gpio>;
+ adc@0 {
+ compatible = "adi,ad7091r8";
+ reg = <0x0>;
+ spi-max-frequency = <1000000>;
+ vref-supply = <&adc_vref>;
+ convst-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&gpio 27 GPIO_ACTIVE_LOW>;
+ interrupts = <22 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml
index fb3d0dae9bae..2e3f84db6193 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml
@@ -8,7 +8,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices AD7124 ADC device driver
maintainers:
- - Stefan Popa <stefan.popa@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
description: |
Bindings for the Analog Devices AD7124 ADC device. Datasheet can be
@@ -27,16 +28,36 @@ properties:
clocks:
maxItems: 1
- description: phandle to the master clock (mclk)
+ description: Optional external clock connected to the CLK pin.
clock-names:
+ deprecated: true
+ description:
+ MCLK is an internal counter in the ADC. Do not use this property.
items:
- const: mclk
+ '#clock-cells':
+ description:
+ The CLK pin can be used as an output. When that is the case, include
+ this property.
+ const: 0
+
interrupts:
description: IRQ line for the ADC
maxItems: 1
+ rdy-gpios:
+ description:
+ GPIO reading the R̅D̅Y̅ line. Having such a GPIO is technically optional but
+ highly recommended because DOUT/R̅D̅Y̅ toggles during SPI transfers (in its
+ DOUT aka MISO role) and so usually triggers a spurious interrupt. The
+ distinction between such a spurious event and a real one can only be done
+ by reading such a GPIO. (There is a register telling the same
+ information, but accessing that one needs a SPI transfer which then
+ triggers another interrupt event.)
+ maxItems: 1
+
'#address-cells':
const: 1
@@ -52,18 +73,20 @@ properties:
avdd-supply:
description: avdd supply can be used as reference for conversion.
- spi-max-frequency: true
-
required:
- compatible
- reg
- - clocks
- - clock-names
- interrupts
+# Can't have both clock input and output at the same time.
+not:
+ required:
+ - '#clock-cells'
+ - clocks
+
patternProperties:
"^channel@([0-9]|1[0-5])$":
- $ref: "adc.yaml"
+ $ref: adc.yaml
type: object
description: |
Represents the external channels which are connected to the ADC.
@@ -106,10 +129,14 @@ patternProperties:
additionalProperties: false
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
+ #include <dt-bindings/gpio/gpio.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -120,9 +147,8 @@ examples:
spi-max-frequency = <5000000>;
interrupts = <25 2>;
interrupt-parent = <&gpio>;
+ rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
refin1-supply = <&adc_vref>;
- clocks = <&ad7124_mclk>;
- clock-names = "mclk";
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
new file mode 100644
index 000000000000..62d906e24997
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
@@ -0,0 +1,483 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2023 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7173.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7173 ADC
+
+maintainers:
+ - Ceclan Dumitru <dumitru.ceclan@analog.com>
+
+description: |
+ Analog Devices AD717x ADC's:
+ The AD717x family offer a complete integrated Sigma-Delta ADC solution which
+ can be used in high precision, low noise single channel applications
+ (Life Science measurements) or higher speed multiplexed applications
+ (Factory Automation PLC Input modules). The Sigma-Delta ADC is intended
+ primarily for measurement of signals close to DC but also delivers
+ outstanding performance with input bandwidths out to ~10kHz.
+
+ Analog Devices AD411x ADC's:
+ The AD411X family encompasses a series of low power, low noise, 24-bit,
+ sigma-delta analog-to-digital converters that offer a versatile range of
+ specifications. They integrate an analog front end suitable for processing
+ fully differential/single-ended and bipolar voltage inputs.
+
+ Datasheets for supported chips:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD4111.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD4112.pdf
+ <AD4113: not released yet>
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD4114.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD4115.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD4116.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-2.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-4.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7173-8.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-2.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-8.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7176-2.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7177-2.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad4111
+ - adi,ad4112
+ - adi,ad4113
+ - adi,ad4114
+ - adi,ad4115
+ - adi,ad4116
+ - adi,ad7172-2
+ - adi,ad7172-4
+ - adi,ad7173-8
+ - adi,ad7175-2
+ - adi,ad7175-8
+ - adi,ad7176-2
+ - adi,ad7177-2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ items:
+ - description: |
+ Ready: multiplexed with SPI data out. While SPI CS is low,
+ can be used to indicate the completion of a conversion.
+
+ - description: |
+ Error: The three error bits in the status register (ADC_ERROR, CRC_ERROR,
+ and REG_ERROR) are OR'ed, inverted, and mapped to the ERROR pin.
+ Therefore, the ERROR pin indicates that an error has occurred.
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: rdy
+ - const: err
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ spi-max-frequency:
+ maximum: 20000000
+
+ gpio-controller:
+ description: Marks the device node as a GPIO controller.
+
+ '#gpio-cells':
+ const: 2
+ description:
+ The first cell is the GPIO number and the second cell specifies
+ GPIO flags, as defined in <dt-bindings/gpio/gpio.h>.
+
+ vref-supply:
+ description: |
+ Differential external reference supply used for conversion. The reference
+ voltage (Vref) specified here must be the voltage difference between the
+ REF+ and REF- pins: Vref = (REF+) - (REF-).
+
+ vref2-supply:
+ description: |
+ Differential external reference supply used for conversion. The reference
+ voltage (Vref2) specified here must be the voltage difference between the
+ REF2+ and REF2- pins: Vref2 = (REF2+) - (REF2-).
+
+ avdd-supply:
+ description: Avdd supply, can be used as reference for conversion.
+ This supply is referenced to AVSS, voltage specified here
+ represents (AVDD1 - AVSS).
+
+ avdd2-supply:
+ description: Avdd2 supply, used as the input to the internal voltage regulator.
+ This supply is referenced to AVSS, voltage specified here
+ represents (AVDD2 - AVSS).
+
+ iovdd-supply:
+ description: iovdd supply, used for the chip digital interface.
+
+ clocks:
+ maxItems: 1
+ description: |
+ Optional external clock source. Can include one clock source: external
+ clock or external crystal.
+
+ clock-names:
+ enum:
+ - ext-clk
+ - xtal
+
+ '#clock-cells':
+ const: 0
+
+ rdy-gpios:
+ description:
+ GPIO reading the R̅D̅Y̅ line. Having such a GPIO is technically optional but
+ highly recommended because DOUT/R̅D̅Y̅ toggles during SPI transfers (in its
+ DOUT aka MISO role) and so usually triggers a spurious interrupt. The
+ distinction between such a spurious event and a real one can only be done
+ by reading such a GPIO. (There is a register telling the same
+ information, but accessing that one needs a SPI transfer which then
+ triggers another interrupt event.)
+ maxItems: 1
+
+patternProperties:
+ "^channel@[0-9a-f]$":
+ type: object
+ $ref: adc.yaml
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 15
+
+ diff-channels:
+ description: |
+ This property is used for defining the inputs of a differential
+ voltage channel. The first value is the positive input and the second
+ value is the negative input of the channel.
+
+ Family AD411x supports a dedicated VINCOM voltage input.
+ To select it set the second channel to 16.
+ (VIN2, VINCOM) -> diff-channels = <2 16>
+
+ There are special values that can be selected besides the voltage
+ analog inputs:
+ 21: REF+
+ 22: REF−
+
+ Supported only by AD7172-2, AD7172-4, AD7175-2, AD7175-8, AD7177-2,
+ must be paired together and can be used to monitor the power supply
+ of the ADC:
+ 19: ((AVDD1 − AVSS)/5)+
+ 20: ((AVDD1 − AVSS)/5)−
+
+ items:
+ minimum: 0
+ maximum: 31
+
+ single-channel:
+ description: |
+ This property is used for defining a current channel or the positive
+ input of a voltage channel (single-ended or pseudo-differential).
+
+ Models AD4111 and AD4112 support current channels.
+ Example: (IIN2+, IIN2−) -> single-channel = <2>
+ To correctly configure a current channel set the "adi,current-channel"
+ property to true.
+
+ To configure a single-ended/pseudo-differential channel set the
+ "common-mode-channel" property to the desired negative voltage input.
+
+ When used as a voltage channel, special inputs are valid as well.
+ minimum: 0
+ maximum: 31
+
+ common-mode-channel:
+ description:
+ This property is used for defining the negative input of a
+ single-ended or pseudo-differential voltage channel.
+
+ Special inputs are valid as well.
+ minimum: 0
+ maximum: 31
+
+ adi,reference-select:
+ description: |
+ Select the reference source to use when converting on
+ the specific channel. Valid values are:
+ vref : REF+ /REF−
+ vref2 : REF2+ /REF2−
+ refout-avss: REFOUT/AVSS (Internal reference)
+ avdd : AVDD /AVSS
+
+ External reference ref2 only available on ad7173-8 and ad7172-4.
+ Internal reference refout-avss not available on ad7172-4.
+
+ If not specified, internal reference used (if available).
+ $ref: /schemas/types.yaml#/definitions/string
+ enum:
+ - vref
+ - vref2
+ - refout-avss
+ - avdd
+ default: refout-avss
+
+ adi,current-channel:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: |
+ Signal that the selected inputs are current channels.
+ Only available on AD4111 and AD4112.
+
+ required:
+ - reg
+
+ allOf:
+ - oneOf:
+ - required: [single-channel]
+ properties:
+ diff-channels: false
+ - required: [diff-channels]
+ properties:
+ single-channel: false
+ adi,current-channel: false
+ common-mode-channel: false
+
+ - if:
+ required: [common-mode-channel]
+ then:
+ properties:
+ adi,current-channel: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+ # Only ad7172-4, ad7173-8 and ad7175-8 support vref2
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - adi,ad7172-4
+ - adi,ad7173-8
+ - adi,ad7175-8
+ then:
+ properties:
+ vref2-supply: false
+ patternProperties:
+ "^channel@[0-9a-f]$":
+ properties:
+ adi,reference-select:
+ enum:
+ - vref
+ - refout-avss
+ - avdd
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad4114
+ - adi,ad4115
+ - adi,ad4116
+ - adi,ad7173-8
+ - adi,ad7175-8
+ then:
+ patternProperties:
+ "^channel@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 15
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7172-2
+ - adi,ad7175-2
+ - adi,ad7176-2
+ - adi,ad7177-2
+ then:
+ patternProperties:
+ "^channel@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 3
+
+ # Model ad7172-4 does not support internal reference
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,ad7172-4
+ then:
+ patternProperties:
+ "^channel@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 7
+ adi,reference-select:
+ enum:
+ - vref
+ - vref2
+ - avdd
+ required:
+ - adi,reference-select
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad4111
+ - adi,ad4112
+ - adi,ad4113
+ - adi,ad4114
+ - adi,ad4115
+ - adi,ad4116
+ then:
+ properties:
+ avdd2-supply: false
+
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - adi,ad4111
+ - adi,ad4112
+ then:
+ patternProperties:
+ "^channel@[0-9a-f]$":
+ properties:
+ adi,current-channel: false
+
+ - if:
+ anyOf:
+ - required: [clock-names]
+ - required: [clocks]
+ then:
+ properties:
+ '#clock-cells': false
+
+unevaluatedProperties: false
+
+examples:
+ # Example AD7173-8 with external reference connected to REF+/REF-:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7173-8";
+ reg = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "rdy";
+ interrupt-parent = <&gpio>;
+ spi-max-frequency = <5000000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ #clock-cells = <0>;
+
+ vref-supply = <&dummy_regulator>;
+
+ channel@0 {
+ reg = <0>;
+ bipolar;
+ diff-channels = <0 1>;
+ adi,reference-select = "vref";
+ };
+
+ channel@1 {
+ reg = <1>;
+ diff-channels = <2 3>;
+ };
+
+ channel@2 {
+ reg = <2>;
+ bipolar;
+ diff-channels = <4 5>;
+ };
+
+ channel@3 {
+ reg = <3>;
+ bipolar;
+ diff-channels = <6 7>;
+ };
+
+ channel@4 {
+ reg = <4>;
+ diff-channels = <8 9>;
+ adi,reference-select = "avdd";
+ };
+ };
+ };
+
+ # Example AD4111 with current channel and single-ended channel:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad4111";
+ reg = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "rdy";
+ interrupt-parent = <&gpio>;
+ rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
+ spi-max-frequency = <5000000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ #clock-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ bipolar;
+ diff-channels = <4 5>;
+ };
+
+ // Single ended channel VIN2/VINCOM
+ channel@1 {
+ reg = <1>;
+ bipolar;
+ single-channel = <2>;
+ common-mode-channel = <16>;
+ };
+
+ // Current channel IN2+/IN2-
+ channel@2 {
+ reg = <2>;
+ single-channel = <2>;
+ adi,current-channel;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7191.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7191.yaml
new file mode 100644
index 000000000000..801ed319ee82
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7191.yaml
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2025 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7191.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7191 ADC
+
+maintainers:
+ - Alisa-Dariana Roman <alisa.roman@analog.com>
+
+description: |
+ Bindings for the Analog Devices AD7191 ADC device. Datasheet can be
+ found here:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7191.pdf
+ The device's PDOWN pin must be connected to the SPI controller's chip select
+ pin.
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7191
+
+ reg:
+ maxItems: 1
+
+ spi-cpol: true
+
+ spi-cpha: true
+
+ clocks:
+ maxItems: 1
+ description:
+ Must be present when CLKSEL pin is tied HIGH to select external clock
+ source (either a crystal between MCLK1 and MCLK2 pins, or a
+ CMOS-compatible clock driving MCLK2 pin). Must be absent when CLKSEL pin
+ is tied LOW to use the internal 4.92MHz clock.
+
+ interrupts:
+ maxItems: 1
+
+ avdd-supply:
+ description: AVdd voltage supply
+
+ dvdd-supply:
+ description: DVdd voltage supply
+
+ vref-supply:
+ description: Vref voltage supply
+
+ odr-gpios:
+ description:
+ ODR1 and ODR2 pins for output data rate selection. Should be defined if
+ adi,odr-value is absent.
+ minItems: 2
+ maxItems: 2
+
+ adi,odr-value:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Should be present if ODR pins are pin-strapped. Possible values:
+ 120 Hz (ODR1=0, ODR2=0)
+ 60 Hz (ODR1=0, ODR2=1)
+ 50 Hz (ODR1=1, ODR2=0)
+ 10 Hz (ODR1=1, ODR2=1)
+ If defined, odr-gpios must be absent.
+ enum: [120, 60, 50, 10]
+
+ pga-gpios:
+ description:
+ PGA1 and PGA2 pins for gain selection. Should be defined if adi,pga-value
+ is absent.
+ minItems: 2
+ maxItems: 2
+
+ adi,pga-value:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Should be present if PGA pins are pin-strapped. Possible values:
+ Gain 1 (PGA1=0, PGA2=0)
+ Gain 8 (PGA1=0, PGA2=1)
+ Gain 64 (PGA1=1, PGA2=0)
+ Gain 128 (PGA1=1, PGA2=1)
+ If defined, pga-gpios must be absent.
+ enum: [1, 8, 64, 128]
+
+ temp-gpios:
+ description: TEMP pin for temperature sensor enable.
+ maxItems: 1
+
+ chan-gpios:
+ description: CHAN pin for input channel selection.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - avdd-supply
+ - dvdd-supply
+ - vref-supply
+ - spi-cpol
+ - spi-cpha
+ - temp-gpios
+ - chan-gpios
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - oneOf:
+ - required:
+ - adi,odr-value
+ - required:
+ - odr-gpios
+ - oneOf:
+ - required:
+ - adi,pga-value
+ - required:
+ - pga-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7191";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+ spi-cpha;
+ clocks = <&ad7191_mclk>;
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+ avdd-supply = <&avdd>;
+ dvdd-supply = <&dvdd>;
+ vref-supply = <&vref>;
+ adi,pga-value = <1>;
+ odr-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>, <&gpio 24 GPIO_ACTIVE_HIGH>;
+ temp-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
+ chan-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml
index 22b7ed3723f6..0bd2c6906c83 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml
@@ -21,8 +21,15 @@ properties:
- adi,ad7190
- adi,ad7192
- adi,ad7193
+ - adi,ad7194
- adi,ad7195
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
reg:
maxItems: 1
@@ -30,25 +37,41 @@ properties:
spi-cpha: true
- spi-max-frequency: true
-
clocks:
maxItems: 1
- description: phandle to the master clock (mclk)
+ description:
+ Optionally, either a crystal can be attached externally between MCLK1 and
+ MCLK2 pins, or an external CMOS-compatible clock can drive the MCLK2
+ pin. If absent, internal 4.92MHz clock is used, which can be made
+ available on MCLK2 pin.
clock-names:
- items:
- - const: mclk
+ enum:
+ - xtal
+ - mclk
+
+ "#clock-cells":
+ const: 0
+ description:
+ If present when internal clock is used, configured as clock provider.
interrupts:
maxItems: 1
+ aincom-supply:
+ description: |
+ AINCOM voltage supply. Analog inputs AINx are referenced to this input
+ when configured for pseudo-differential operation.
+
dvdd-supply:
description: DVdd voltage supply
avdd-supply:
description: AVdd voltage supply
+ vref-supply:
+ description: VRef voltage supply
+
adi,rejection-60-Hz-enable:
description: |
This bit enables a notch at 60 Hz when the first notch of the sinc
@@ -83,41 +106,152 @@ properties:
description: see Documentation/devicetree/bindings/iio/adc/adc.yaml
type: boolean
+ rdy-gpios:
+ description:
+ GPIO reading the R̅D̅Y̅ line. Having such a GPIO is technically optional but
+ highly recommended because DOUT/R̅D̅Y̅ toggles during SPI transfers (in its
+ DOUT aka MISO role) and so usually triggers a spurious interrupt. The
+ distinction between such a spurious event and a real one can only be done
+ by reading such a GPIO. (There is a register telling the same
+ information, but accessing that one needs a SPI transfer which then
+ triggers another interrupt event.)
+ maxItems: 1
+
+patternProperties:
+ "^channel@[0-9a-f]+$":
+ type: object
+ $ref: adc.yaml
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: The channel index.
+ minimum: 0
+ maximum: 271
+
+ diff-channels:
+ description:
+ Both inputs can be connected to pins AIN1 to AIN16 by choosing the
+ appropriate value from 1 to 16.
+ items:
+ minimum: 1
+ maximum: 16
+
+ single-channel:
+ description:
+ Positive input can be connected to pins AIN1 to AIN16 by choosing the
+ appropriate value from 1 to 16. Negative input is connected to AINCOM.
+ minimum: 1
+ maximum: 16
+
+ oneOf:
+ - required:
+ - reg
+ - diff-channels
+ - required:
+ - reg
+ - single-channel
+
required:
- compatible
- reg
- - clocks
- - clock-names
- interrupts
- dvdd-supply
- avdd-supply
+ - vref-supply
- spi-cpol
- spi-cpha
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ enum:
+ - adi,ad7190
+ - adi,ad7192
+ - adi,ad7193
+ - adi,ad7195
+ then:
+ patternProperties:
+ "^channel@[0-9a-f]+$": false
+ - if:
+ anyOf:
+ - required:
+ - clocks
+ - required:
+ - clock-names
+ then:
+ properties:
+ "#clock-cells": false
+ required:
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
examples:
- |
- spi0 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- adc@0 {
- compatible = "adi,ad7192";
- reg = <0>;
- spi-max-frequency = <1000000>;
- spi-cpol;
- spi-cpha;
- clocks = <&ad7192_mclk>;
- clock-names = "mclk";
- interrupts = <25 0x2>;
- interrupt-parent = <&gpio>;
- dvdd-supply = <&dvdd>;
- avdd-supply = <&avdd>;
-
- adi,refin2-pins-enable;
- adi,rejection-60-Hz-enable;
- adi,buffer-enable;
- adi,burnout-currents-enable;
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7192";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+ spi-cpha;
+ clocks = <&ad7192_mclk>;
+ clock-names = "mclk";
+ interrupts = <25 0x2>;
+ interrupt-parent = <&gpio>;
+ rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
+ aincom-supply = <&aincom>;
+ dvdd-supply = <&dvdd>;
+ avdd-supply = <&avdd>;
+ vref-supply = <&vref>;
+
+ adi,refin2-pins-enable;
+ adi,rejection-60-Hz-enable;
+ adi,buffer-enable;
+ adi,burnout-currents-enable;
+ };
+ };
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7194";
+ reg = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+ spi-cpha;
+ #clock-cells = <0>;
+ interrupts = <25 0x2>;
+ interrupt-parent = <&gpio>;
+ rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
+ aincom-supply = <&aincom>;
+ dvdd-supply = <&dvdd>;
+ avdd-supply = <&avdd>;
+ vref-supply = <&vref>;
+
+ channel@0 {
+ reg = <0>;
+ diff-channels = <1 6>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ single-channel = <1>;
+ };
};
};
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7280a.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7280a.yaml
new file mode 100644
index 000000000000..dfb8f305e2f0
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7280a.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7280a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7280a Lithium Ion Battery Monitoring System
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ Bindings for the Analog Devices AD7280a Battery Monitoring System.
+ Used in devices such as hybrid electric cars, battery backup and power tools.
+ Multiple chips can be daisy chained and accessed via a single SPI interface.
+ Data sheet found here:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7280A.pdf
+
+properties:
+ compatible:
+ const: adi,ad7280a
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description: IRQ line for the ADC
+ maxItems: 1
+
+ adi,voltage-alert-last-chan:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Allows limiting of scope of which channels are considered for voltage
+ alerts, typically because not all are wired to anything. Only applies to
+ last device in the daisy chain.
+ default: 5
+ enum: [3, 4, 5]
+
+ adi,acquisition-time-ns:
+ description:
+ Additional time may be needed to charge the sampling capacitors depending
+ on external writing.
+ default: 400
+ enum: [400, 800, 1200, 1600]
+
+ adi,thermistor-termination:
+ type: boolean
+ description:
+ Enable the thermistor termination function.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7280a";
+ reg = <0>;
+ spi-max-frequency = <700000>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 2>;
+ adi,thermistor-termination;
+ adi,acquisition-time-ns = <800>;
+ adi,voltage-alert-last-chan = <5>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml
index 930f9e3904d7..0b2f5dc80600 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7291.yaml
@@ -44,4 +44,3 @@ examples:
};
};
...
-
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
index a3e39a40c9b3..2aa1f4b063eb 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7292.yaml
@@ -30,8 +30,6 @@ properties:
spi-cpha: true
- spi-max-frequency: true
-
'#address-cells':
const: 1
@@ -45,7 +43,7 @@ required:
patternProperties:
"^channel@[0-7]$":
- $ref: "adc.yaml"
+ $ref: adc.yaml
type: object
description: |
Represents the external channels which are connected to the ADC.
@@ -63,9 +61,12 @@ patternProperties:
required:
- reg
- additionalProperties: true
+ additionalProperties: false
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7298.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7298.yaml
index ca414bb396c5..cd8ac5162d27 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7298.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7298.yaml
@@ -24,13 +24,15 @@ properties:
vref-supply: true
vdd-supply: true
- spi-max-frequency: true
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7380.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7380.yaml
new file mode 100644
index 000000000000..b91bfb16ed6b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7380.yaml
@@ -0,0 +1,316 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7380.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Simultaneous Sampling Analog to Digital Converters
+
+maintainers:
+ - Michael Hennerich <Michael.Hennerich@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ * https://www.analog.com/en/products/ad7380.html
+ * https://www.analog.com/en/products/ad7381.html
+ * https://www.analog.com/en/products/ad7383.html
+ * https://www.analog.com/en/products/ad7384.html
+ * https://www.analog.com/en/products/ad7386.html
+ * https://www.analog.com/en/products/ad7387.html
+ * https://www.analog.com/en/products/ad7388.html
+ * https://www.analog.com/en/products/ad7380-4.html
+ * https://www.analog.com/en/products/ad7381-4.html
+ * https://www.analog.com/en/products/ad7383-4.html
+ * https://www.analog.com/en/products/ad7384-4.html
+ * https://www.analog.com/en/products/ad7386-4.html
+ * https://www.analog.com/en/products/ad7387-4.html
+ * https://www.analog.com/en/products/ad7388-4.html
+ * https://www.analog.com/en/products/ad7389-4.html
+ * https://www.analog.com/en/products/adaq4370-4.html
+ * https://www.analog.com/en/products/adaq4380-4.html
+ * https://www.analog.com/en/products/adaq4381-4.html
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7380
+ - adi,ad7381
+ - adi,ad7383
+ - adi,ad7384
+ - adi,ad7386
+ - adi,ad7387
+ - adi,ad7388
+ - adi,ad7380-4
+ - adi,ad7381-4
+ - adi,ad7383-4
+ - adi,ad7384-4
+ - adi,ad7386-4
+ - adi,ad7387-4
+ - adi,ad7388-4
+ - adi,ad7389-4
+ - adi,adaq4370-4
+ - adi,adaq4380-4
+ - adi,adaq4381-4
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 80000000
+ spi-cpol: true
+ spi-cpha: true
+
+ vcc-supply:
+ description: A 3V to 3.6V supply that powers the chip.
+
+ vlogic-supply:
+ description:
+ A 1.65V to 3.6V supply for the logic pins.
+
+ refio-supply:
+ description:
+ A 2.5V to 3.3V supply for the external reference voltage. When omitted,
+ the internal 2.5V reference is used.
+
+ refin-supply:
+ description:
+ A 2.5V to 3.3V supply for external reference voltage, for ad7380-4 only.
+ For adaq devices, a 5V supply voltage. A 3.3V internal reference is
+ derived from it. Connect to vs-p-supply for normal operation.
+
+ vs-p-supply:
+ description:
+ Amplifiers positive supply.
+
+ vs-n-supply:
+ description:
+ Amplifiers negative supply.
+
+ ldo-supply:
+ description:
+ LDO supply. Connect to vs-p-supply or a 3.6 to 5.5 V supply.
+
+ aina-supply:
+ description:
+ The common mode voltage supply for the AINA- pin on pseudo-differential
+ chips.
+
+ ainb-supply:
+ description:
+ The common mode voltage supply for the AINB- pin on pseudo-differential
+ chips.
+
+ ainc-supply:
+ description:
+ The common mode voltage supply for the AINC- pin on pseudo-differential
+ chips.
+
+ aind-supply:
+ description:
+ The common mode voltage supply for the AIND- pin on pseudo-differential
+ chips.
+
+ interrupts:
+ description:
+ When the device is using 1-wire mode, this property is used to optionally
+ specify the ALERT interrupt.
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+ - vlogic-supply
+
+patternProperties:
+ "^channel@[0-3]$":
+ $ref: adc.yaml
+ type: object
+
+ properties:
+ reg:
+ description:
+ The channel number. From 0 to 3 corresponding to channels A,B,C,D
+ minimum: 0
+ maximum: 3
+
+ adi,gain-milli:
+ description:
+ The hardware gain applied to the ADC input (in milli units).
+ If not present, default to 1000 (no actual gain applied).
+ Refer to the typical connection diagrams section of the datasheet for
+ pin wiring.
+ $ref: /schemas/types.yaml#/definitions/uint16
+ enum: [300, 600, 1000, 1600]
+ default: 1000
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+unevaluatedProperties: false
+
+allOf:
+ # pseudo-differential chips require common mode voltage supplies,
+ # true differential chips don't use them
+ - if:
+ properties:
+ compatible:
+ enum:
+ - adi,ad7383
+ - adi,ad7384
+ - adi,ad7383-4
+ - adi,ad7384-4
+ then:
+ required:
+ - aina-supply
+ - ainb-supply
+ else:
+ properties:
+ aina-supply: false
+ ainb-supply: false
+ - if:
+ properties:
+ compatible:
+ enum:
+ - adi,ad7383-4
+ - adi,ad7384-4
+ then:
+ required:
+ - ainc-supply
+ - aind-supply
+ else:
+ properties:
+ ainc-supply: false
+ aind-supply: false
+
+ # ad7380-4 uses refin-supply as external reference.
+ # adaq devices use internal reference only, derived from refin-supply
+ # All other chips from ad738x family use refio as optional external reference.
+ # When refio-supply is omitted, internal reference is used.
+ - if:
+ properties:
+ compatible:
+ enum:
+ - adi,ad7380-4
+ - adi,adaq4370-4
+ - adi,adaq4380-4
+ - adi,adaq4381-4
+ then:
+ properties:
+ refio-supply: false
+ required:
+ - refin-supply
+ else:
+ properties:
+ refin-supply: false
+
+ # adi,ad7389-4 is internal reference only
+ - if:
+ properties:
+ compatible:
+ const: adi,ad7389-4
+ then:
+ properties:
+ refio-supply: false
+
+ # adaq devices need more supplies and using channel to declare gain property
+ # only applies to adaq devices
+ - if:
+ properties:
+ compatible:
+ enum:
+ - adi,adaq4370-4
+ - adi,adaq4380-4
+ - adi,adaq4381-4
+ then:
+ required:
+ - vs-p-supply
+ - vs-n-supply
+ - ldo-supply
+ else:
+ properties:
+ vs-p-supply: false
+ vs-n-supply: false
+ ldo-supply: false
+ patternProperties:
+ "^channel@[0-3]$": false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7380";
+ reg = <0>;
+
+ spi-cpol;
+ spi-cpha;
+ spi-max-frequency = <80000000>;
+
+ interrupts = <27 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio0>;
+
+ vcc-supply = <&supply_3_3V>;
+ vlogic-supply = <&supply_3_3V>;
+ refio-supply = <&supply_2_5V>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,adaq4380-4";
+ reg = <0>;
+
+ spi-cpol;
+ spi-cpha;
+ spi-max-frequency = <80000000>;
+
+ interrupts = <27 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio0>;
+
+ vcc-supply = <&supply_3_3V>;
+ vlogic-supply = <&supply_3_3V>;
+ refin-supply = <&supply_5V>;
+ vs-p-supply = <&supply_5V>;
+ vs-n-supply = <&supply_0V>;
+ ldo-supply = <&supply_5V>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ adi,gain-milli = /bits/ 16 <300>;
+ };
+
+ channel@2 {
+ reg = <2>;
+ adi,gain-milli = /bits/ 16 <600>;
+ };
+
+ channel@3 {
+ reg = <3>;
+ adi,gain-milli = /bits/ 16 <1000>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7405.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7405.yaml
new file mode 100644
index 000000000000..57f097025705
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7405.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2025 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7405.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7405 family
+
+maintainers:
+ - Dragos Bogdan <dragos.bogdan@analog.com>
+ - Pop Ioan Daniel <pop.ioan-daniel@analog.com>
+
+description: |
+ Analog Devices AD7405 is a high performance isolated ADC, 1-channel,
+ 16-bit with a second-order Σ-Δ modulator that converts an analog input signal
+ into a high speed, single-bit data stream.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7405.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/adum7701.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/adum7702.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ADuM7703.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7405
+ - adi,adum7701
+ - adi,adum7702
+ - adi,adum7703
+
+ clocks:
+ maxItems: 1
+
+ vdd1-supply: true
+
+ vdd2-supply: true
+
+ io-backends:
+ maxItems: 1
+
+required:
+ - compatible
+ - clocks
+ - vdd1-supply
+ - vdd2-supply
+ - io-backends
+
+additionalProperties: false
+
+examples:
+ - |
+ adc {
+ compatible = "adi,ad7405";
+ clocks = <&axi_clk_gen 0>;
+ vdd1-supply = <&vdd1>;
+ vdd2-supply = <&vdd2>;
+ io-backends = <&axi_adc>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7476.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7476.yaml
index cf711082ad7d..55880191c511 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7476.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7476.yaml
@@ -17,39 +17,50 @@ description: |
properties:
compatible:
- enum:
- - adi,ad7091
- - adi,ad7091r
- - adi,ad7273
- - adi,ad7274
- - adi,ad7276
- - adi,ad7277
- - adi,ad7278
- - adi,ad7466
- - adi,ad7467
- - adi,ad7468
- - adi,ad7475
- - adi,ad7476
- - adi,ad7476a
- - adi,ad7477
- - adi,ad7477a
- - adi,ad7478
- - adi,ad7478a
- - adi,ad7495
- - adi,ad7910
- - adi,ad7920
- - adi,ad7940
- - ti,adc081s
- - ti,adc101s
- - ti,adc121s
- - ti,ads7866
- - ti,ads7867
- - ti,ads7868
- - lltc,ltc2314-14
+ oneOf:
+ - items:
+ - enum:
+ - adi,ad7091
+ - adi,ad7091r
+ - adi,ad7273
+ - adi,ad7274
+ - adi,ad7276
+ - adi,ad7277
+ - adi,ad7278
+ - adi,ad7466
+ - adi,ad7467
+ - adi,ad7468
+ - adi,ad7475
+ - adi,ad7476
+ - adi,ad7476a
+ - adi,ad7477
+ - adi,ad7477a
+ - adi,ad7478
+ - adi,ad7478a
+ - adi,ad7495
+ - adi,ad7910
+ - adi,ad7920
+ - adi,ad7940
+ - rohm,bd79105
+ - ti,adc081s
+ - ti,adc101s
+ - ti,adc121s
+ - ti,ads7866
+ - ti,ads7867
+ - ti,ads7868
+ - lltc,ltc2314-14
+ - items:
+ - const: rohm,bu79100g
+ - const: ti,ads7866
reg:
maxItems: 1
+ interrupts:
+ description:
+ The data-ready interrupt. Provided via DOUT pin.
+ maxItems: 1
+
vcc-supply:
description:
Main powersupply voltage for the chips, sometimes referred to as VDD on
@@ -66,19 +77,35 @@ properties:
to the other supplies. Needed to be able to establish channel scaling
unless there is also an internal reference available (e.g. ad7091r)
- spi-max-frequency: true
-
adi,conversion-start-gpios:
description: A GPIO used to trigger the start of a conversion
maxItems: 1
+ rdy-gpios:
+ description: A GPIO for detecting the data-ready.
+ maxItems: 1
+
required:
- compatible
- reg
-additionalProperties: false
-
allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+# Devices with an IRQ
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - rohm,bd79105
+ then:
+ properties:
+ interrupts: true
+ else:
+ properties:
+ interrupts: false
+
# Devices where reference is vcc
- if:
properties:
@@ -98,24 +125,24 @@ allOf:
- ti,adc121s
- ti,ads7866
- ti,ads7868
+ then:
required:
- vcc-supply
# Devices with a vref
- if:
- properties:
- compatible:
- contains:
- enum:
- - adi,ad7091r
- - adi,ad7273
- - adi,ad7274
- - adi,ad7475
- - lltc,ltc2314-14
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7091r
+ - adi,ad7273
+ - adi,ad7274
+ - adi,ad7475
+ - lltc,ltc2314-14
+ - rohm,bd79105
then:
properties:
- vref-supply: true
- else:
- properties:
vref-supply: false
# Devices with a vref where it is not optional
- if:
@@ -127,35 +154,60 @@ allOf:
- adi,ad7274
- adi,ad7475
- lltc,ltc2314-14
+ - rohm,bd79105
then:
required:
- vref-supply
- if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7475
+ - adi,ad7495
+ - rohm,bd79105
+ then:
properties:
- compatible:
- contains:
- enum:
- - adi,ad7475
- - adi,ad7495
+ vdrive-supply: false
+
+ # Devices which support polling the data-ready via GPIO
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - rohm,bd79105
then:
properties:
- vdrive-supply: true
- else:
+ rdy-gpios: false
+
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7091
+ - adi,ad7091r
+ - rohm,bd79105
+ then:
properties:
- vdrive-supply: false
+ adi,conversion-start-gpios: false
+
+ # Devices with a convstart GPIO where it is not optional
- if:
properties:
compatible:
contains:
enum:
- - adi,ad7091
- - adi,ad7091r
+ - rohm,bd79105
then:
- properties:
- adi,conversion-start-gpios: true
- else:
- properties:
- adi,conversion-start-gpios: false
+ required:
+ - adi,conversion-start-gpios
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
index 73775174cf57..73c8e9c532f3 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
@@ -7,135 +7,421 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices AD7606 Simultaneous Sampling ADC
maintainers:
- - Beniamin Bia <beniamin.bia@analog.com>
- - Stefan Popa <stefan.popa@analog.com>
+ - Michael Hennerich <michael.hennerich@analog.com>
description: |
Analog Devices AD7606 Simultaneous Sampling ADC
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7605-4.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606_7606-6_7606-4.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/AD7606B.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606c-16.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606c-18.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7607.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7608.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7609.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/AD7616.pdf
properties:
compatible:
enum:
- adi,ad7605-4
- - adi,ad7606-8
- - adi,ad7606-6
- adi,ad7606-4
+ - adi,ad7606-6
+ - adi,ad7606-8 # Referred to as AD7606 (without -8) in the datasheet
- adi,ad7606b
+ - adi,ad7606c-16
+ - adi,ad7606c-18
+ - adi,ad7607
+ - adi,ad7608
+ - adi,ad7609
- adi,ad7616
reg:
maxItems: 1
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ '#trigger-source-cells':
+ description: |
+ Cell indicates the output signal: 0 = BUSY, 1 = FIRSTDATA.
+
+ For convenience, macros for these values are available in
+ dt-bindings/iio/adc/adi,ad7606.h.
+ const: 1
+
+ # According to the datasheet, "Data is clocked in from SDI on the falling
+ # edge of SCLK, while data is clocked out on DOUTA on the rising edge of
+ # SCLK". Also, even if not stated textually in the datasheet, it is made
+ # clear on the diagrams that sclk idles at high. Subsequently, in case SPI
+ # interface is used, the correct way is to only set spi-cpol.
spi-cpha: true
spi-cpol: true
- spi-max-frequency: true
-
avcc-supply: true
+ vdrive-supply:
+ description:
+ Determines the voltage level at which the interface logic pins will
+ operate.
+
+ refin-supply:
+ description:
+ The voltage supply for optional external reference voltage.
+
interrupts:
+ description:
+ The BUSY pin falling edge indicates that the conversion is over, and thus
+ new data is available.
maxItems: 1
adi,conversion-start-gpios:
description:
- Must be the device tree identifier of the CONVST pin.
- This logic input is used to initiate conversions on the analog
- input channels. As the line is active high, it should be marked
- GPIO_ACTIVE_HIGH.
- maxItems: 1
+ Must be the device tree identifier of the CONVST pin(s). This logic input
+ is used to initiate conversions on the analog input channels. As the line
+ is active high, it should be marked GPIO_ACTIVE_HIGH.
+ minItems: 1
+ maxItems: 2
reset-gpios:
description:
- Must be the device tree identifier of the RESET pin. If specified,
- it will be asserted during driver probe. As the line is active high,
- it should be marked GPIO_ACTIVE_HIGH.
+ Must be the device tree identifier of the RESET pin. If specified, it will
+ be asserted during driver probe. On the AD7606x, as the line is active
+ high, it should be marked GPIO_ACTIVE_HIGH. On the AD7616, as the line is
+ active low, it should be marked GPIO_ACTIVE_LOW.
maxItems: 1
standby-gpios:
description:
- Must be the device tree identifier of the STBY pin. This pin is used
- to place the AD7606 into one of two power-down modes, Standby mode or
+ Must be the device tree identifier of the STBY pin. This pin is used to
+ place the AD7606 into one of two power-down modes, Standby mode or
Shutdown mode. As the line is active low, it should be marked
GPIO_ACTIVE_LOW.
maxItems: 1
adi,first-data-gpios:
description:
- Must be the device tree identifier of the FRSTDATA pin.
- The FRSTDATA output indicates when the first channel, V1, is
- being read back on either the parallel, byte or serial interface.
- As the line is active high, it should be marked GPIO_ACTIVE_HIGH.
+ Must be the device tree identifier of the FRSTDATA pin. The FRSTDATA
+ output indicates when the first channel, V1, is being read back on either
+ the parallel, byte or serial interface. As the line is active high, it
+ should be marked GPIO_ACTIVE_HIGH.
maxItems: 1
adi,range-gpios:
description:
- Must be the device tree identifier of the RANGE pin. The polarity on
- this pin determines the input range of the analog input channels. If
- this pin is tied to a logic high, the analog input range is ±10V for
- all channels. If this pin is tied to a logic low, the analog input range
+ Must be the device tree identifier of the RANGE pin. The state on this
+ pin determines the input range of the analog input channels. If this pin
+ is tied to a logic high, the analog input range is ±10V for all channels.
+ On the AD760X, if this pin is tied to a logic low, the analog input range
is ±5V for all channels. As the line is active high, it should be marked
- GPIO_ACTIVE_HIGH.
- maxItems: 1
+ GPIO_ACTIVE_HIGH. On the AD7616, there are 2 pins, and if the 2 pins are
+ tied to a logic high, software mode is enabled, otherwise one of the 3
+ possible range values is selected.
+ minItems: 1
+ maxItems: 2
adi,oversampling-ratio-gpios:
description:
- Must be the device tree identifier of the over-sampling
- mode pins. As the line is active high, it should be marked
- GPIO_ACTIVE_HIGH.
+ Must be the device tree identifier of the over-sampling mode pins. As the
+ line is active high, it should be marked GPIO_ACTIVE_HIGH. On the AD7606X
+ parts that support it, if all 3 pins are tied to a logic high, software
+ mode is enabled.
maxItems: 3
adi,sw-mode:
description:
- Software mode of operation, so far available only for ad7616 and ad7606b.
- It is enabled when all three oversampling mode pins are connected to
- high level. The device is configured by the corresponding registers. If the
- adi,oversampling-ratio-gpios property is defined, then the driver will set the
- oversampling gpios to high. Otherwise, it is assumed that the pins are hardwired
- to VDD.
+ Software mode of operation, so far available only for AD7616 and AD7606B.
+ It is enabled when all three oversampling mode pins are connected to high
+ level for the AD7606B, or both the range selection are connected to high
+ level for the AD7616. The device is configured by the corresponding
+ registers. If the adi,oversampling-ratio-gpios property is defined, then
+ the driver will set the oversampling gpios to high. Otherwise, it is
+ assumed that the pins are hardwired to VDD.
type: boolean
+ pwms:
+ description:
+ In case the conversion is triggered by a PWM instead of a GPIO plugged to
+ the CONVST pin, the PWM must be referenced.
+ The first is the PWM connected to CONVST or CONVST1 for the chips with the
+ 2nd PWM connected to CONVST2, if CONVST2 is available and not shorted to
+ CONVST1.
+ minItems: 1
+ maxItems: 2
+
+ pwm-names:
+ minItems: 1
+ items:
+ - const: convst1
+ - const: convst2
+
+ io-backends:
+ description:
+ A reference to the iio-backend, which is responsible handling the BUSY
+ pin's falling edge and communication.
+ An example of backend can be found at
+ http://analogdevicesinc.github.io/hdl/library/axi_ad7606x/index.html
+
+patternProperties:
+ "^channel@[1-8]$":
+ type: object
+ $ref: adc.yaml
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description:
+ The channel number, as specified in the datasheet (from 1 to 8).
+ minimum: 1
+ maximum: 8
+
+ diff-channels:
+ description:
+ Each channel can be configured as a bipolar differential channel.
+ The ADC uses the same positive and negative inputs for this.
+ This property must be specified as 'reg' (or the channel number) for
+ both positive and negative inputs (i.e. diff-channels = <reg reg>).
+ Since the configuration is bipolar differential, the 'bipolar'
+ property is required.
+ items:
+ minimum: 1
+ maximum: 8
+
+ bipolar:
+ description:
+ The ADC channels can be configured as
+ * Bipolar single-ended
+ * Unipolar single-ended
+ * Bipolar differential
+ Therefore in the DT, if no channel node is specified, it is considered
+ 'unipolar single-ended'. So for the other configurations the 'bipolar'
+ property must be specified. If 'diff-channels' is specified, it is
+ considered a bipolar differential channel. Otherwise it is bipolar
+ single-ended.
+
+ adi,rfilter-ohms:
+ description:
+ For ADCs that supports gain calibration, this property must be set to
+ the value of the external RFilter resistor. Proper gain error
+ correction is applied based on this value.
+ default: 0
+ minimum: 0
+ maximum: 64512
+
+ required:
+ - reg
+ - bipolar
+
required:
- compatible
- reg
- - spi-cpha
- avcc-supply
- - interrupts
- - adi,conversion-start-gpios
+ - vdrive-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+ - oneOf:
+ - required:
+ - adi,conversion-start-gpios
+ - required:
+ - pwms
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,ad7616
+ then:
+ properties:
+ adi,first-data-gpios: false
+ standby-gpios: false
+ adi,range-gpios:
+ maxItems: 2
+ else:
+ properties:
+ adi,range-gpios:
+ maxItems: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7605-4
+ - adi,ad7616
+ then:
+ properties:
+ adi,oversampling-ratio-gpios: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7605-4
+ - adi,ad7606-4
+ - adi,ad7606-6
+ - adi,ad7606-8
+ - adi,ad7607
+ - adi,ad7608
+ - adi,ad7609
+ - adi,ad7616
+ then:
+ patternProperties:
+ "^channel@[0-9a-f]+$":
+ properties:
+ adi,rfilter-ohms: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7605-4
+ - adi,ad7606-4
+ - adi,ad7606-6
+ - adi,ad7606-8
+ - adi,ad7607
+ - adi,ad7608
+ - adi,ad7609
+ then:
+ properties:
+ adi,sw-mode: false
+ else:
+ properties:
+ pwms:
+ maxItems: 1
+ pwm-names:
+ maxItems: 1
+ adi,conversion-start-gpios:
+ maxItems: 1
+
+ - if:
+ not:
+ required:
+ - adi,sw-mode
+ then:
+ patternProperties:
+ "^channel@[1-8]$": false
-additionalProperties: false
+ - if:
+ not:
+ properties:
+ compatible:
+ enum:
+ - adi,ad7606c-16
+ - adi,ad7606c-18
+ then:
+ patternProperties:
+ "^channel@[1-8]$": false
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
+ iio-backend {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adi_adc@0 {
+ compatible = "adi,ad7606b";
+ reg = <0>;
+ pwms = <&axi_pwm_gen 0 0>;
+
+ avcc-supply = <&adc_vref>;
+ vdrive-supply = <&vdd_supply>;
+
+ reset-gpios = <&gpio0 91 GPIO_ACTIVE_HIGH>;
+ standby-gpios = <&gpio0 90 GPIO_ACTIVE_LOW>;
+ adi,range-gpios = <&gpio0 89 GPIO_ACTIVE_HIGH>;
+ adi,oversampling-ratio-gpios = <&gpio0 88 GPIO_ACTIVE_HIGH
+ &gpio0 87 GPIO_ACTIVE_HIGH
+ &gpio0 86 GPIO_ACTIVE_HIGH>;
+ io-backends = <&iio_backend>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7606-8";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+
+ avcc-supply = <&adc_vref>;
+ vdrive-supply = <&vdd_supply>;
+
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+
+ adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
+ adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
+ adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH>,
+ <&gpio 23 GPIO_ACTIVE_HIGH>,
+ <&gpio 26 GPIO_ACTIVE_HIGH>;
+ standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;
+ };
+ };
+ - |
+ #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
adc@0 {
- compatible = "adi,ad7606-8";
- reg = <0>;
- spi-max-frequency = <1000000>;
- spi-cpol;
- spi-cpha;
-
- avcc-supply = <&adc_vref>;
-
- interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
- interrupt-parent = <&gpio>;
-
- adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
- reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
- adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
- adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH>,
- <&gpio 23 GPIO_ACTIVE_HIGH>,
- <&gpio 26 GPIO_ACTIVE_HIGH>;
- standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;
- adi,sw-mode;
+ compatible = "adi,ad7606c-18";
+ reg = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+
+ avcc-supply = <&adc_vref>;
+ vdrive-supply = <&vdd_supply>;
+
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+
+ adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
+ adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
+ standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;
+
+ adi,sw-mode;
+
+ channel@1 {
+ reg = <1>;
+ diff-channels = <1 1>;
+ bipolar;
+ };
+
+ channel@3 {
+ reg = <3>;
+ bipolar;
+ };
+
+ channel@8 {
+ reg = <8>;
+ diff-channels = <8 8>;
+ bipolar;
+ adi,rfilter-ohms = <2048>;
+ };
+
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7625.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7625.yaml
new file mode 100644
index 000000000000..8848562af28f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7625.yaml
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7625.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices Fast PulSAR Analog to Digital Converters
+
+maintainers:
+ - Michael Hennerich <Michael.Hennerich@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ A family of single channel differential analog to digital converters.
+
+ * https://www.analog.com/en/products/ad7625.html
+ * https://www.analog.com/en/products/ad7626.html
+ * https://www.analog.com/en/products/ad7960.html
+ * https://www.analog.com/en/products/ad7961.html
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7625
+ - adi,ad7626
+ - adi,ad7960
+ - adi,ad7961
+
+ vdd1-supply: true
+ vdd2-supply: true
+ vio-supply: true
+
+ ref-supply:
+ description:
+ Voltage regulator for the external reference voltage (REF).
+
+ refin-supply:
+ description:
+ Voltage regulator for the reference buffer input (REFIN).
+
+ clocks:
+ description:
+ The clock connected to the CLK pins, gated by the clk_gate PWM.
+ maxItems: 1
+
+ pwms:
+ items:
+ - description: PWM connected to the CNV input on the ADC.
+ - description: PWM that gates the clock connected to the ADC's CLK input.
+
+ pwm-names:
+ items:
+ - const: cnv
+ - const: clk_gate
+
+ io-backends:
+ description:
+ The AXI ADC IP block connected to the D+/- and DCO+/- lines of the
+ ADC. An example backend can be found at
+ http://analogdevicesinc.github.io/hdl/projects/pulsar_lvds/index.html.
+ maxItems: 1
+
+ adi,no-dco:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Indicates the wiring of the DCO+/- lines. If true, then they are
+ grounded and the device is in self-clocked mode. If this is not
+ present, then the device is in echoed clock mode.
+
+ adi,en0-always-on:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Indicates if EN0 is hard-wired to the high state. If neither this
+ nor en0-gpios are present, then EN0 is hard-wired low.
+
+ adi,en1-always-on:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Indicates if EN1 is hard-wired to the high state. If neither this
+ nor en1-gpios are present, then EN1 is hard-wired low.
+
+ adi,en2-always-on:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Indicates if EN2 is hard-wired to the high state. If neither this
+ nor en2-gpios are present, then EN2 is hard-wired low.
+
+ adi,en3-always-on:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Indicates if EN3 is hard-wired to the high state. If neither this
+ nor en3-gpios are present, then EN3 is hard-wired low.
+
+ en0-gpios:
+ description:
+ Configurable EN0 pin.
+
+ en1-gpios:
+ description:
+ Configurable EN1 pin.
+
+ en2-gpios:
+ description:
+ Configurable EN2 pin.
+
+ en3-gpios:
+ description:
+ Configurable EN3 pin.
+
+required:
+ - compatible
+ - vdd1-supply
+ - vdd2-supply
+ - vio-supply
+ - clocks
+ - pwms
+ - pwm-names
+ - io-backends
+
+allOf:
+ - if:
+ required:
+ - ref-supply
+ then:
+ properties:
+ refin-supply: false
+ - if:
+ required:
+ - refin-supply
+ then:
+ properties:
+ ref-supply: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7625
+ - adi,ad7626
+ then:
+ properties:
+ en2-gpios: false
+ en3-gpios: false
+ adi,en2-always-on: false
+ adi,en3-always-on: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad7960
+ - adi,ad7961
+ then:
+ # ad796x parts must have one of the two supplies
+ oneOf:
+ - required: [ref-supply]
+ - required: [refin-supply]
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ adc {
+ compatible = "adi,ad7625";
+ vdd1-supply = <&supply_5V>;
+ vdd2-supply = <&supply_2_5V>;
+ vio-supply = <&supply_2_5V>;
+ io-backends = <&axi_adc>;
+ clocks = <&ref_clk>;
+ pwms = <&axi_pwm_gen 0 0>, <&axi_pwm_gen 1 0>;
+ pwm-names = "cnv", "clk_gate";
+ en0-gpios = <&gpio0 86 GPIO_ACTIVE_HIGH>;
+ en1-gpios = <&gpio0 87 GPIO_ACTIVE_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml
index a85a28145ef6..c06d0fc791d3 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml
@@ -26,7 +26,26 @@ properties:
clock-names:
const: mclk
+ trigger-sources:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ minItems: 1
+ maxItems: 2
+ description: |
+ A list of phandles referencing trigger source providers. Each entry
+ represents a trigger source for the ADC:
+
+ - First entry specifies the device responsible for driving the
+ synchronization (SYNC_IN) pin, as an alternative to adi,sync-in-gpios.
+ This can be a `gpio-trigger` or another `ad7768-1` device. If the
+ device's own SYNC_OUT pin is internally connected to its SYNC_IN pin,
+ reference the device itself or omit this property.
+ - Second entry optionally defines a GPIO3 pin used as a START signal trigger.
+
+ Use the accompanying trigger source cell to identify the type of each entry.
+
interrupts:
+ description:
+ DRDY (Data Ready) pin, which signals conversion results are available.
maxItems: 1
'#address-cells':
@@ -47,11 +66,22 @@ properties:
in any way, for example if the filter decimation rate changes.
As the line is active low, it should be marked GPIO_ACTIVE_LOW.
+ regulators:
+ type: object
+ description:
+ list of regulators provided by this controller.
+
+ properties:
+ vcm-output:
+ $ref: /schemas/regulator/regulator.yaml#
+ type: object
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
reset-gpios:
maxItems: 1
- spi-max-frequency: true
-
spi-cpol: true
spi-cpha: true
@@ -59,6 +89,23 @@ properties:
"#io-channel-cells":
const: 1
+ "#trigger-source-cells":
+ description: |
+ Cell indicates the trigger output signal: 0 = SYNC_OUT, 1 = GPIO3,
+ 2 = DRDY.
+
+ For better readability, macros for these values are available in
+ dt-bindings/iio/adc/adi,ad7768-1.h.
+ const: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 2
+ description: |
+ The first cell is for the GPIO number: 0 to 3.
+ The second cell takes standard GPIO flags.
+
required:
- compatible
- reg
@@ -67,7 +114,16 @@ required:
- vref-supply
- spi-cpol
- spi-cpha
- - adi,sync-in-gpios
+
+dependencies:
+ adi,sync-in-gpios:
+ not:
+ required:
+ - trigger-sources
+ trigger-sources:
+ not:
+ required:
+ - adi,sync-in-gpios
patternProperties:
"^channel@([0-9]|1[0-5])$":
@@ -88,7 +144,10 @@ patternProperties:
- reg
additionalProperties: false
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -104,6 +163,8 @@ examples:
spi-max-frequency = <2000000>;
spi-cpol;
spi-cpha;
+ gpio-controller;
+ #gpio-cells = <2>;
vref-supply = <&adc_vref>;
interrupts = <25 IRQ_TYPE_EDGE_RISING>;
interrupt-parent = <&gpio>;
@@ -119,6 +180,12 @@ examples:
reg = <0>;
label = "channel_0";
};
+
+ regulators {
+ vcm_reg: vcm-output {
+ regulator-name = "ad7768-1-vcm";
+ };
+ };
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7779.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7779.yaml
new file mode 100644
index 000000000000..ba3f7b2bd6cf
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7779.yaml
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7779.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD777X family 8-Channel, 24-Bit, Simultaneous Sampling ADCs
+
+maintainers:
+ - Ramona Nechita <ramona.nechita@analog.com>
+
+description: |
+ The AD777X family consist of 8-channel, simultaneous sampling analog-to-
+ digital converter (ADC). Eight full Σ-Δ ADCs are on-chip. The
+ AD7771 provides an ultralow input current to allow direct sensor
+ connection. Each input channel has a programmable gain stage
+ allowing gains of 1, 2, 4, and 8 to map lower amplitude sensor
+ outputs into the full-scale ADC input range, maximizing the
+ dynamic range of the signal chain.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7770.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7771.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad7779.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7770
+ - adi,ad7771
+ - adi,ad7779
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ clocks:
+ maxItems: 1
+
+ avdd1-supply:
+ description: Front-End analog supply AVDD1. Can be used as conversion ref.
+
+ avdd2-supply:
+ description: AVDD2 Analog Supply from 2.2 V to 3.6 V.
+
+ avdd4-supply:
+ description: AVDD4 SAR Analog Supply and Reference Source.
+
+ interrupts:
+ minItems: 1
+ items:
+ - description: |
+ adc_rdy: Interrupt line for DRDY signal which indicates the end of
+ conversion independently of the interface selected to read back the
+ Σ-∆ conversion.
+ - description: |
+ Alert: The chip includes self diagnostic features to guarantee the
+ correct operation. If an error is detected, the ALERT pin is pulled
+ high to generate an external interruption to the controller.
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - adc_rdy
+ - alert
+
+ start-gpios:
+ description:
+ Pin that controls start synchronization pulse.
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ io-backends:
+ maxItems: 1
+
+ adi,num-lanes:
+ description:
+ Number of lanes on which the data is sent on the output when the data
+ output interface is used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 4]
+ default: 4
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+allOf:
+ - if:
+ not:
+ required:
+ - io-backends
+ then:
+ properties:
+ adi,num-lanes: false
+
+oneOf:
+ - required:
+ - interrupts
+ - required:
+ - io-backends
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7779";
+ reg = <0>;
+ start-gpios = <&gpio0 87 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&gpio0 93 GPIO_ACTIVE_LOW>;
+ interrupt-parent = <&intc>;
+ interrupts = <0 56 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "adc_rdy";
+ clocks = <&adc_clk>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ad7779";
+ reg = <0>;
+ start-gpios = <&gpio0 87 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&gpio0 93 GPIO_ACTIVE_LOW>;
+ clocks = <&adc_clk>;
+ io-backends = <&iio_backend>;
+ adi,num-lanes = <4>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml
index a67ba67dab51..5c8df45bfab0 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml
@@ -63,6 +63,17 @@ properties:
marked GPIO_ACTIVE_LOW.
maxItems: 1
+ rdy-gpios:
+ description:
+ GPIO reading the R̅D̅Y̅ line. Having such a GPIO is technically optional but
+ highly recommended because DOUT/R̅D̅Y̅ toggles during SPI transfers (in its
+ DOUT aka MISO role) and so usually triggers a spurious interrupt. The
+ distinction between such a spurious event and a real one can only be done
+ by reading such a GPIO. (There is a register telling the same
+ information, but accessing that one needs a SPI transfer which then
+ triggers another interrupt event.)
+ maxItems: 1
+
required:
- compatible
- reg
@@ -72,7 +83,7 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -80,9 +91,9 @@ examples:
compatible = "adi,ad7780";
reg = <0>;
- avdd-supply = <&vdd_supply>;
- powerdown-gpios = <&gpio0 12 GPIO_ACTIVE_HIGH>;
- adi,gain-gpios = <&gpio1 5 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&vdd_supply>;
+ powerdown-gpios = <&gpio0 12 GPIO_ACTIVE_HIGH>;
+ adi,gain-gpios = <&gpio1 5 GPIO_ACTIVE_LOW>;
adi,filter-gpios = <&gpio2 15 GPIO_ACTIVE_LOW>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7923.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7923.yaml
index e82194974eea..85148338c597 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7923.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7923.yaml
@@ -8,11 +8,10 @@ title: Analog Devices AD7923 and similars with 4 and 8 Channel ADCs.
maintainers:
- Michael Hennerich <michael.hennerich@analog.com>
- - Patrick Vasseur <patrick.vasseur@c-s.fr>
description: |
Analog Devices AD7904, AD7914, AD7923, AD7924 4 Channel ADCs, and AD7908,
- AD7918, AD7928 8 Channels ADCs.
+ AD7918, AD7927, AD7928 8 Channels ADCs.
Specifications about the part can be found at:
https://www.analog.com/media/en/technical-documentation/data-sheets/AD7923.pdf
@@ -21,14 +20,22 @@ description: |
properties:
compatible:
- enum:
- - adi,ad7904
- - adi,ad7914
- - adi,ad7923
- - adi,ad7924
- - adi,ad7908
- - adi,ad7918
- - adi,ad7928
+ oneOf:
+ - enum:
+ - adi,ad7904
+ - adi,ad7908
+ - adi,ad7914
+ - adi,ad7918
+ - adi,ad7923
+ - adi,ad7928
+ - const: adi,ad7924
+ deprecated: true
+ - items:
+ - const: adi,ad7924
+ - const: adi,ad7923
+ - items:
+ - const: adi,ad7927
+ - const: adi,ad7928
reg:
maxItems: 1
@@ -37,19 +44,24 @@ properties:
description: |
The regulator supply for ADC reference voltage.
+ adi,range-double:
+ description: Sets the analog input range from 0 to 2xVREF.
+ type: boolean
+
'#address-cells':
const: 1
'#size-cells':
const: 0
- spi-max-frequency: true
-
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7944.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7944.yaml
new file mode 100644
index 000000000000..d17d184842d3
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7944.yaml
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7944.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices PulSAR LFCSP Analog to Digital Converters
+
+maintainers:
+ - Michael Hennerich <Michael.Hennerich@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ A family of pin-compatible single channel differential analog to digital
+ converters with SPI support in a LFCSP package.
+
+ * https://www.analog.com/en/products/ad7944.html
+ * https://www.analog.com/en/products/ad7985.html
+ * https://www.analog.com/en/products/ad7986.html
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7944
+ - adi,ad7985
+ - adi,ad7986
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 111111111
+
+ spi-cpol: true
+ spi-cpha: true
+
+ adi,spi-mode:
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ single, chain ]
+ description: |
+ This property indicates the SPI wiring configuration.
+
+ When this property is omitted, it is assumed that the device is using what
+ the datasheet calls "4-wire mode". This is the conventional SPI mode used
+ when there are multiple devices on the same bus. In this mode, the CNV
+ line is used to initiate the conversion and the SDI line is connected to
+ CS on the SPI controller.
+
+ When this property is present, it indicates that the device is using one
+ of the following alternative wiring configurations:
+
+ * single: The datasheet calls this "3-wire mode". (NOTE: The datasheet's
+ definition of 3-wire mode is NOT at all related to the standard
+ spi-3wire property!) This mode is often used when the ADC is the only
+ device on the bus. In this mode, SDI is tied to VIO, and the CNV line
+ can be connected to the CS line of the SPI controller or to a GPIO, in
+ which case the CS line of the controller is unused.
+ * chain: The datasheet calls this "chain mode". This mode is used to save
+ on wiring when multiple ADCs are used. In this mode, the SDI line of
+ one chip is tied to the SDO of the next chip in the chain and the SDI of
+ the last chip in the chain is tied to GND. Only the first chip in the
+ chain is connected to the SPI bus. The CNV line of all chips are tied
+ together. The CS line of the SPI controller can be used as the CNV line
+ only if it is active high.
+
+ '#daisy-chained-devices': true
+
+ avdd-supply:
+ description: A 2.5V supply that powers the analog circuitry.
+
+ dvdd-supply:
+ description: A 2.5V supply that powers the digital circuitry.
+
+ vio-supply:
+ description:
+ A 1.8V to 2.7V supply for the digital inputs and outputs.
+
+ bvdd-supply:
+ description:
+ A voltage supply for the buffered power. When using an external reference
+ without an internal buffer (PDREF high, REFIN low), this should be
+ connected to the same supply as ref-supply. Otherwise, when using an
+ internal reference or an external reference with an internal buffer, this
+ is connected to a 5V supply.
+
+ ref-supply:
+ description:
+ Voltage regulator for the external reference voltage (REF). This property
+ is omitted when using an internal reference.
+
+ refin-supply:
+ description:
+ Voltage regulator for the reference buffer input (REFIN). When using an
+ external buffer with internal reference, this should be connected to a
+ 1.2V external reference voltage supply. Otherwise, this property is
+ omitted.
+
+ cnv-gpios:
+ description:
+ The Convert Input (CNV). This input has multiple functions. It initiates
+ the conversions and selects the SPI mode of the device (chain or CS). In
+ 'single' mode, this property is omitted if the CNV pin is connected to the
+ CS line of the SPI controller.
+ maxItems: 1
+
+ turbo-gpios:
+ description:
+ GPIO connected to the TURBO line. If omitted, it is assumed that the TURBO
+ line is hard-wired and the state is determined by the adi,always-turbo
+ property.
+ maxItems: 1
+
+ adi,always-turbo:
+ type: boolean
+ description:
+ When present, this property indicates that the TURBO line is hard-wired
+ and the state is always high. If neither this property nor turbo-gpios is
+ present, the TURBO line is assumed to be hard-wired and the state is
+ always low.
+
+ interrupts:
+ description:
+ The SDO pin can also function as a busy indicator. This node should be
+ connected to an interrupt that is triggered when the SDO line goes low
+ while the SDI line is high and the CNV line is low ('single' mode) or the
+ SDI line is low and the CNV line is high ('multi' mode); or when the SDO
+ line goes high while the SDI and CNV lines are high (chain mode),
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - dvdd-supply
+ - vio-supply
+ - bvdd-supply
+
+allOf:
+ # ref-supply and refin-supply are mutually exclusive (neither is also valid)
+ - if:
+ required:
+ - ref-supply
+ then:
+ properties:
+ refin-supply: false
+ - if:
+ required:
+ - refin-supply
+ then:
+ properties:
+ ref-supply: false
+ # in '4-wire' mode, cnv-gpios is required, for other modes it is optional
+ - if:
+ not:
+ required:
+ - adi,spi-mode
+ then:
+ required:
+ - cnv-gpios
+ # chain mode has lower SCLK max rate and doesn't work when TURBO is enabled
+ - if:
+ required:
+ - adi,spi-mode
+ properties:
+ adi,spi-mode:
+ const: chain
+ then:
+ properties:
+ spi-max-frequency:
+ maximum: 90909090
+ adi,always-turbo: false
+ required:
+ - '#daisy-chained-devices'
+ else:
+ properties:
+ '#daisy-chained-devices': false
+ # turbo-gpios and adi,always-turbo are mutually exclusive
+ - if:
+ required:
+ - turbo-gpios
+ then:
+ properties:
+ adi,always-turbo: false
+ - if:
+ required:
+ - adi,always-turbo
+ then:
+ properties:
+ turbo-gpios: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc@0 {
+ compatible = "adi,ad7944";
+ reg = <0>;
+ spi-cpha;
+ spi-max-frequency = <111111111>;
+ avdd-supply = <&supply_2_5V>;
+ dvdd-supply = <&supply_2_5V>;
+ vio-supply = <&supply_1_8V>;
+ bvdd-supply = <&supply_5V>;
+ cnv-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>;
+ turbo-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7949.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7949.yaml
index 9b56bd4d5510..238a8c9c4143 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7949.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7949.yaml
@@ -26,21 +26,45 @@ properties:
reg:
maxItems: 1
+ vrefin-supply:
+ description:
+ Buffered ADC reference voltage supply.
+
vref-supply:
description:
- ADC reference voltage supply
+ Unbuffered ADC reference voltage supply.
+
+ adi,internal-ref-microvolt:
+ description: |
+ Internal reference voltage selection in microvolts.
+
+ If no internal reference is specified, the channel will default to the
+ external reference defined by vrefin-supply (or vref-supply).
+ vrefin-supply will take precedence over vref-supply if both are defined.
+
+ If no supplies are defined, the reference selection will default to
+ 4096mV internal reference.
- spi-max-frequency: true
+ enum: [2500000, 4096000]
+ default: 4096000
- "#io-channel-cells":
+ '#io-channel-cells':
const: 1
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
required:
- compatible
- reg
- - vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -49,9 +73,30 @@ examples:
#size-cells = <0>;
adc@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
compatible = "adi,ad7949";
reg = <0>;
vref-supply = <&vdd_supply>;
};
+
+ adc@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ compatible = "adi,ad7949";
+ reg = <1>;
+ vrefin-supply = <&vdd_supply>;
+ };
+
+ adc@2 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ compatible = "adi,ad7949";
+ reg = <2>;
+ adi,internal-ref-microvolt = <4096000>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml
new file mode 100644
index 000000000000..433ed2c9295f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad799x.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad799x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD799x analog to digital converters
+
+maintainers:
+ - Michael Hennerich <Michael.Hennerich@analog.com>
+
+description: |
+ Support for Analog Devices AD7991, AD7992, AD7993, AD7994, AD7995, AD7997, AD7998,
+ AD7999 and similar analog to digital converters.
+ Specifications on the converters can be found at:
+ AD7991, AD7995, AD7999:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7991_7995_7999.pdf
+ AD7992:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7992.pdf
+ AD7993, AD7994:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7993_7994.pdf
+ AD7997, AD7998:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/AD7997_7998.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7991
+ - adi,ad7992
+ - adi,ad7993
+ - adi,ad7994
+ - adi,ad7995
+ - adi,ad7997
+ - adi,ad7998
+ - adi,ad7999
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vcc-supply:
+ description:
+ ADC power supply
+
+ vref-supply:
+ description:
+ ADC reference voltage supply, optional for AD7991, AD7995 and AD7999
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc1: adc@28 {
+ reg = <0x28>;
+ compatible = "adi,ad7991";
+ interrupts = <13 2>;
+ interrupt-parent = <&gpio6>;
+
+ vcc-supply = <&vcc_3v3>;
+ vref-supply = <&adc_vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml
index b5aed40d8a50..2606c0c5dfc6 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml
@@ -8,7 +8,6 @@ title: Analog Devices AD9467 and similar High-Speed ADCs
maintainers:
- Michael Hennerich <michael.hennerich@analog.com>
- - Alexandru Ardelean <alexandru.ardelean@analog.com>
description: |
The AD9467 and the parts similar with it, are high-speed analog-to-digital
@@ -29,6 +28,9 @@ properties:
- adi,ad9265
- adi,ad9434
- adi,ad9467
+ - adi,ad9643
+ - adi,ad9649
+ - adi,ad9652
reg:
maxItems: 1
@@ -45,6 +47,9 @@ properties:
Pin that controls the powerdown mode of the device.
maxItems: 1
+ io-backends:
+ maxItems: 1
+
reset-gpios:
description:
Reset pin for the device.
@@ -65,10 +70,11 @@ examples:
#size-cells = <0>;
adc@0 {
- compatible = "adi,ad9467";
- reg = <0>;
- clocks = <&adc_clk>;
- clock-names = "adc-clk";
+ compatible = "adi,ad9467";
+ reg = <0>;
+ clocks = <&adc_clk>;
+ clock-names = "adc-clk";
+ io-backends = <&iio_backend>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ade9000.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ade9000.yaml
new file mode 100644
index 000000000000..f22eba0250ee
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ade9000.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2025 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ade9000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADE9000 High Performance, Polyphase Energy Metering
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ The ADE9000 is a highly accurate, fully integrated, multiphase energy and power
+ quality monitoring device. Superior analog performance and a digital signal
+ processing (DSP) core enable accurate energy monitoring over a wide dynamic
+ range. An integrated high end reference ensures low drift over temperature
+ with a combined drift of less than ±25 ppm/°C maximum for the entire channel
+ including a programmable gain amplifier (PGA) and an analog-to-digital
+ converter (ADC).
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ADE9000.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,ade9000
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 20000000
+
+ interrupts:
+ maxItems: 3
+
+ interrupt-names:
+ items:
+ enum: [irq0, irq1, dready]
+ minItems: 1
+ maxItems: 3
+
+ reset-gpios:
+ description:
+ Must be the device tree identifier of the RESET pin. As the line is
+ active low, it should be marked GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ vdd-supply: true
+
+ vref-supply: true
+
+ clocks:
+ description: External clock source when not using crystal
+ maxItems: 1
+
+ "#clock-cells":
+ description:
+ ADE9000 can provide clock output via CLKOUT pin with external buffer.
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,ade9000";
+ reg = <0>;
+ spi-max-frequency = <7000000>;
+
+ #clock-cells = <0>;
+ reset-gpios = <&gpio 4 GPIO_ACTIVE_LOW>;
+ interrupts = <2 IRQ_TYPE_EDGE_FALLING>, <3 IRQ_TYPE_EDGE_FALLING>, <4 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "irq0", "irq1", "dready";
+ interrupt-parent = <&gpio>;
+ clocks = <&ext_clock_24576khz>;
+ vdd-supply = <&vdd_reg>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
index 0924b2b4972b..e91e421a3d6b 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml
@@ -8,7 +8,6 @@ title: Analog Devices AXI ADC IP core
maintainers:
- Michael Hennerich <michael.hennerich@analog.com>
- - Alexandru Ardelean <alexandru.ardelean@analog.com>
description: |
Analog Devices Generic AXI ADC IP core for interfacing an ADC device
@@ -18,17 +17,34 @@ description: |
interface for the actual ADC, while this IP core will interface
to the data-lines of the ADC and handle the streaming of data into
memory via DMA.
+ In some cases, the AXI ADC interface is used to perform specialized
+ operation to a particular ADC, e.g access the physical bus through
+ specific registers to write ADC registers.
+ In this case, we use a different compatible which indicates the target
+ IP core's name.
+ The following IP is currently supported:
+ - AXI AD7606x: specialized version of the IP core for all the chips from
+ the ad7606 family.
https://wiki.analog.com/resources/fpga/docs/axi_adc_ip
+ https://analogdevicesinc.github.io/hdl/library/axi_ad408x/index.html
+ https://analogdevicesinc.github.io/hdl/library/axi_ad485x/index.html
+ http://analogdevicesinc.github.io/hdl/library/axi_ad7606x/index.html
properties:
compatible:
enum:
- adi,axi-adc-10.0.a
+ - adi,axi-ad408x
+ - adi,axi-ad7606x
+ - adi,axi-ad485x
reg:
maxItems: 1
+ clocks:
+ maxItems: 1
+
dmas:
maxItems: 1
@@ -40,23 +56,85 @@ properties:
$ref: /schemas/types.yaml#/definitions/phandle
description:
A reference to a the actual ADC to which this FPGA ADC interfaces to.
+ deprecated: true
+
+ '#io-backend-cells':
+ const: 0
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^adc@[0-9a-f]+$":
+ type: object
+ properties:
+ reg:
+ maxItems: 1
+ additionalProperties: true
+ required:
+ - compatible
+ - reg
required:
- compatible
- dmas
- reg
- - adi,adc-dev
+ - clocks
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ const: adi,axi-ad7606x
+ then:
+ properties:
+ '#address-cells': false
+ '#size-cells': false
+ patternProperties:
+ "^adc@[0-9a-f]+$": false
additionalProperties: false
examples:
- |
- axi-adc@44a00000 {
- compatible = "adi,axi-adc-10.0.a";
- reg = <0x44a00000 0x10000>;
- dmas = <&rx_dma 0>;
- dma-names = "rx";
+ adc@44a00000 {
+ compatible = "adi,axi-adc-10.0.a";
+ reg = <0x44a00000 0x10000>;
+ dmas = <&rx_dma 0>;
+ dma-names = "rx";
+ clocks = <&axi_clk>;
+ #io-backend-cells = <0>;
+ };
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ parallel_bus_controller@44a00000 {
+ compatible = "adi,axi-ad7606x";
+ reg = <0x44a00000 0x10000>;
+ dmas = <&rx_dma 0>;
+ dma-names = "rx";
+ clocks = <&ext_clk>;
+ #address-cells = <1>;
+ #size-cells = <0>;
- adi,adc-dev = <&spi_adc>;
+ adc@0 {
+ compatible = "adi,ad7606b";
+ reg = <0>;
+ pwms = <&axi_pwm_gen 0 0>;
+ pwm-names = "convst1";
+ avcc-supply = <&adc_vref>;
+ vdrive-supply = <&vdd_supply>;
+ reset-gpios = <&gpio0 91 GPIO_ACTIVE_HIGH>;
+ standby-gpios = <&gpio0 90 GPIO_ACTIVE_LOW>;
+ adi,range-gpios = <&gpio0 89 GPIO_ACTIVE_HIGH>;
+ adi,oversampling-ratio-gpios = <&gpio0 88 GPIO_ACTIVE_HIGH
+ &gpio0 87 GPIO_ACTIVE_HIGH
+ &gpio0 86 GPIO_ACTIVE_HIGH>;
+ io-backends = <&parallel_bus_controller>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,max11410.yaml b/Documentation/devicetree/bindings/iio/adc/adi,max11410.yaml
new file mode 100644
index 000000000000..53f9feff137b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,max11410.yaml
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2022 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,max11410.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices MAX11410 ADC device driver
+
+maintainers:
+ - Ibrahim Tilki <Ibrahim.Tilki@analog.com>
+
+description: |
+ Bindings for the Analog Devices MAX11410 ADC device. Datasheet can be
+ found here:
+ https://datasheets.maximintegrated.com/en/ds/MAX11410.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,max11410
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ description: Name of the gpio pin of max11410 used for IRQ
+ minItems: 1
+ items:
+ - enum: [gpio0, gpio1]
+ - const: gpio1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ avdd-supply:
+ description: Optional avdd supply. Used as reference when no explicit reference supplied.
+
+ vref0p-supply:
+ description: vref0p supply can be used as reference for conversion.
+
+ vref1p-supply:
+ description: vref1p supply can be used as reference for conversion.
+
+ vref2p-supply:
+ description: vref2p supply can be used as reference for conversion.
+
+ vref0n-supply:
+ description: vref0n supply can be used as reference for conversion.
+
+ vref1n-supply:
+ description: vref1n supply can be used as reference for conversion.
+
+ vref2n-supply:
+ description: vref2n supply can be used as reference for conversion.
+
+ spi-max-frequency:
+ maximum: 8000000
+
+patternProperties:
+ "^channel(@[0-9])?$":
+ $ref: adc.yaml
+ type: object
+ description: Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description: The channel number in single-ended mode.
+ minimum: 0
+ maximum: 9
+
+ adi,reference:
+ description: |
+ Select the reference source to use when converting on
+ the specific channel. Valid values are:
+ 0: VREF0P/VREF0N
+ 1: VREF1P/VREF1N
+ 2: VREF2P/VREF2N
+ 3: AVDD/AGND
+ 4: VREF0P/AGND
+ 5: VREF1P/AGND
+ 6: VREF2P/AGND
+ If this field is left empty, AVDD/AGND is selected.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3, 4, 5, 6]
+ default: 3
+
+ adi,input-mode:
+ description: |
+ Select signal path of input channels. Valid values are:
+ 0: Buffered, low-power, unity-gain path (default)
+ 1: Bypass path
+ 2: PGA path
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+ default: 0
+
+ diff-channels: true
+
+ bipolar: true
+
+ settling-time-us: true
+
+ adi,buffered-vrefp:
+ description: Enable buffered mode for positive reference.
+ type: boolean
+
+ adi,buffered-vrefn:
+ description: Enable buffered mode for negative reference.
+ type: boolean
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ reg = <0>;
+ compatible = "adi,max11410";
+ spi-max-frequency = <8000000>;
+
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "gpio1";
+
+ avdd-supply = <&adc_avdd>;
+
+ vref1p-supply = <&adc_vref1p>;
+ vref1n-supply = <&adc_vref1n>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ diff-channels = <2 3>;
+ adi,reference = <1>;
+ bipolar;
+ settling-time-us = <100000>;
+ };
+
+ channel@2 {
+ reg = <2>;
+ diff-channels = <7 9>;
+ adi,reference = <5>;
+ adi,input-mode = <2>;
+ settling-time-us = <50000>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/adi,max14001.yaml b/Documentation/devicetree/bindings/iio/adc/adi,max14001.yaml
new file mode 100644
index 000000000000..a2dc59c9dcd8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,max14001.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2023-2025 Analog Devices Inc.
+# Copyright 2023 Kim Seer Paller
+# Copyright 2025 Marilene Andrade Garcia
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,max14001.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices MAX14001-MAX14002 ADC
+
+maintainers:
+ - Kim Seer Paller <kimseer.paller@analog.com>
+ - Marilene Andrade Garcia <marilene.agarcia@gmail.com>
+
+description: |
+ Single channel 10 bit ADC with SPI interface.
+ Datasheet can be found here
+ https://www.analog.com/media/en/technical-documentation/data-sheets/MAX14001-MAX14002.pdf
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - const: adi,max14002
+ - items:
+ - const: adi,max14001
+ - const: adi,max14002
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 5000000
+
+ vdd-supply:
+ description:
+ Isolated DC-DC power supply input voltage.
+
+ vddl-supply:
+ description:
+ Logic power supply.
+
+ refin-supply:
+ description:
+ ADC voltage reference supply.
+
+ interrupts:
+ minItems: 1
+ items:
+ - description: |
+ cout: comparator output signal that asserts high on the COUT pin
+ when ADC readings exceed the upper threshold and low when readings
+ fall below the lower threshold.
+ - description: |
+ fault: when fault reporting is enabled, the FAULT pin is asserted
+ low whenever one of the monitored fault conditions occurs.
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: cout
+ - const: fault
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vddl-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "adi,max14001", "adi,max14002";
+ reg = <0>;
+ spi-max-frequency = <5000000>;
+ spi-lsb-first;
+ vdd-supply = <&vdd>;
+ vddl-supply = <&vddl>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml b/Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml
new file mode 100644
index 000000000000..da605a051b94
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/allwinner,sun20i-d1-gpadc.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/allwinner,sun20i-d1-gpadc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner D1 General Purpose ADC
+
+maintainers:
+ - Maksim Kiselev <bigunclemax@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - allwinner,sun20i-d1-gpadc
+ - items:
+ - enum:
+ - allwinner,sun50i-h616-gpadc
+ - const: allwinner,sun20i-d1-gpadc
+
+ "#io-channel-cells":
+ const: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+patternProperties:
+ "^channel@[0-9a-f]+$":
+ $ref: adc.yaml
+ type: object
+ description:
+ Represents the internal channels of the ADC.
+
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 15
+
+ required:
+ - reg
+
+ unevaluatedProperties: false
+
+required:
+ - "#io-channel-cells"
+ - clocks
+ - compatible
+ - interrupts
+ - reg
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/sun20i-d1-ccu.h>
+ #include <dt-bindings/reset/sun20i-d1-ccu.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ gpadc: adc@2009000 {
+ compatible = "allwinner,sun20i-d1-gpadc";
+ reg = <0x2009000 0x400>;
+ clocks = <&ccu CLK_BUS_GPADC>;
+ resets = <&ccu RST_BUS_GPADC>;
+ interrupts = <73 IRQ_TYPE_LEVEL_HIGH>;
+ #io-channel-cells = <1>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml b/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml
index 15c514b83583..a73a355fc665 100644
--- a/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/allwinner,sun8i-a33-ths.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/allwinner,sun8i-a33-ths.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A33 Thermal Sensor Device Tree Bindings
+title: Allwinner A33 Thermal Sensor
maintainers:
- Chen-Yu Tsai <wens@csie.org>
diff --git a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.yaml b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.yaml
index 7e8328e9ce13..bb9825e7346d 100644
--- a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.yaml
@@ -23,6 +23,7 @@ properties:
- amlogic,meson8m2-saradc
- amlogic,meson-gxbb-saradc
- amlogic,meson-gxl-saradc
+ - amlogic,meson-gxlx-saradc
- amlogic,meson-gxm-saradc
- amlogic,meson-axg-saradc
- amlogic,meson-g12a-saradc
@@ -66,6 +67,9 @@ properties:
nvmem-cell-names:
const: temperature_calib
+ power-domains:
+ maxItems: 1
+
allOf:
- if:
properties:
@@ -95,6 +99,7 @@ allOf:
compatible:
contains:
enum:
+ - amlogic,meson8-saradc
- amlogic,meson8b-saradc
- amlogic,meson8m2-saradc
then:
diff --git a/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml b/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml
new file mode 100644
index 000000000000..509bfb1007c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/aspeed,ast2600-adc.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/aspeed,ast2600-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADC that forms part of an ASPEED server management processor.
+
+maintainers:
+ - Billy Tsai <billy_tsai@aspeedtech.com>
+
+description: |
+ • 10-bits resolution for 16 voltage channels.
+ • The device split into two individual engine and each contains 8 voltage
+ channels.
+ • Channel scanning can be non-continuous.
+ • Programmable ADC clock frequency.
+ • Programmable upper and lower threshold for each channels.
+ • Interrupt when larger or less than threshold for each channels.
+ • Support hysteresis for each channels.
+ • Built-in a compensating method.
+ • Built-in a register to trim internal reference voltage.
+ • Internal or External reference voltage.
+ • Support 2 Internal reference voltage 1.2v or 2.5v.
+ • Integrate dividing circuit for battery sensing.
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2600-adc0
+ - aspeed,ast2600-adc1
+ - aspeed,ast2700-adc0
+ - aspeed,ast2700-adc1
+ description:
+ Their trimming data, which is used to calibrate internal reference volage,
+ locates in different address of OTP.
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description:
+ Input clock used to derive the sample clock. Expected to be the
+ SoC's APB clock.
+
+ resets:
+ maxItems: 1
+
+ "#io-channel-cells":
+ const: 1
+
+ vref-supply:
+ description:
+ The external regulator supply ADC reference voltage.
+
+ aspeed,int-vref-microvolt:
+ enum: [1200000, 2500000]
+ description:
+ ADC internal reference voltage in microvolts.
+
+ aspeed,battery-sensing:
+ type: boolean
+ description:
+ Inform the driver that last channel will be used to sensor battery.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - resets
+ - "#io-channel-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/ast2600-clock.h>
+ adc0: adc@1e6e9000 {
+ compatible = "aspeed,ast2600-adc0";
+ reg = <0x1e6e9000 0x100>;
+ clocks = <&syscon ASPEED_CLK_APB2>;
+ resets = <&syscon ASPEED_RESET_ADC>;
+ #io-channel-cells = <1>;
+ aspeed,int-vref-microvolt = <2500000>;
+ };
+ adc1: adc@1e6e9100 {
+ compatible = "aspeed,ast2600-adc1";
+ reg = <0x1e6e9100 0x100>;
+ clocks = <&syscon ASPEED_CLK_APB2>;
+ resets = <&syscon ASPEED_RESET_ADC>;
+ #io-channel-cells = <1>;
+ aspeed,int-vref-microvolt = <2500000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml b/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml
index 79c13b408eda..4817b840977a 100644
--- a/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/atmel,sama5d2-adc.yaml
@@ -7,7 +7,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: AT91 SAMA5D2 Analog to Digital Converter (ADC)
maintainers:
- - Ludovic Desroches <ludovic.desroches@atmel.com>
- Eugen Hristev <eugen.hristev@microchip.com>
properties:
@@ -15,6 +14,7 @@ properties:
enum:
- atmel,sama5d2-adc
- microchip,sam9x60-adc
+ - microchip,sama7g5-adc
reg:
maxItems: 1
@@ -41,7 +41,7 @@ properties:
description: Startup time expressed in ms, it depends on SoC.
atmel,trigger-edge-type:
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description:
One of possible edge types for the ADTRG hardware trigger pin.
When the specific edge type is detected, the conversion will
@@ -71,7 +71,6 @@ required:
- atmel,min-sample-rate-hz
- atmel,max-sample-rate-hz
- atmel,startup-time-ms
- - atmel,trigger-edge-type
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml b/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml
index e6a1f915b542..1f30a8569187 100644
--- a/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/atmel,sama9260-adc.yaml
@@ -56,8 +56,8 @@ properties:
String corresponding to an identifier from atmel,adc-res-names property.
If not specified, the highest resolution will be used.
enum:
- - "lowres"
- - "highres"
+ - lowres
+ - highres
atmel,adc-sleep-mode:
$ref: /schemas/types.yaml#/definitions/flag
diff --git a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml
index 77605f17901c..9c57eb13f892 100644
--- a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/adc/avia-hx711.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/adc/avia-hx711.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: AVIA HX711 ADC chip for weight cells
diff --git a/Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml b/Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml
new file mode 100644
index 000000000000..6d4fb3e1d2a2
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/cirrus,ep9301-adc.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/cirrus,ep9301-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cirrus Logic EP930x internal ADC
+
+description: |
+ Cirrus Logic EP9301/EP9302 SoCs' internal ADC block.
+
+ User's manual:
+ https://cdn.embeddedts.com/resource-attachments/ts-7000_ep9301-ug.pdf
+
+maintainers:
+ - Alexander Sverdlin <alexander.sverdlin@gmail.com>
+
+properties:
+ compatible:
+ const: cirrus,ep9301-adc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ adc: adc@80900000 {
+ compatible = "cirrus,ep9301-adc";
+ reg = <0x80900000 0x28>;
+ clocks = <&syscon 24>;
+ interrupt-parent = <&vic1>;
+ interrupts = <30>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml b/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml
index 4e695b97d015..9ea44ce63f25 100644
--- a/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/cosmic,10001-adc.yaml
@@ -36,7 +36,6 @@ properties:
"#io-channel-cells":
const: 1
-
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml b/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml
index 1ca571056ea9..c770ff4998f5 100644
--- a/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/fsl,vf610-adc.yaml
@@ -7,14 +7,21 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: ADC found on Freescale vf610 and similar SoCs
maintainers:
- - Fugang Duan <fugang.duan@nxp.com>
+ - Haibo Chen <haibo.chen@nxp.com>
description:
ADCs found on vf610/i.MX6slx and upward SoCs from Freescale.
properties:
compatible:
- const: fsl,vf610-adc
+ oneOf:
+ - items:
+ - enum:
+ - fsl,imx6sx-adc
+ - fsl,imx6ul-adc
+ - const: fsl,vf610-adc
+ - items:
+ - const: fsl,vf610-adc
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/iio/adc/gehc,pmc-adc.yaml b/Documentation/devicetree/bindings/iio/adc/gehc,pmc-adc.yaml
new file mode 100644
index 000000000000..2cea7c104a26
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/gehc,pmc-adc.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/gehc,pmc-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GE HealthCare PMC Analog to Digital Converter (ADC)
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description:
+ The GE HealthCare PMC ADC is a 16-Channel (voltage and current), 16-Bit ADC
+ with an I2C Interface.
+
+properties:
+ compatible:
+ const: gehc,pmc-adc
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description:
+ Regulator for the VDD power supply.
+
+ vdda-supply:
+ description:
+ Regulator for the VDD analog (VDDA) power supply.
+
+ vddio-supply:
+ description:
+ Regulator for the VDD IO (VDDIO) power supply.
+
+ vref-supply:
+ description:
+ Regulator for the voltage reference power supply.
+
+ clocks:
+ maxItems: 1
+ description:
+ The component uses an external oscillator (osc) if an external oscillator
+ is connected to its clock pins. Otherwise, it uses an internal reference
+ clock.
+
+ clock-names:
+ items:
+ - const: osc
+
+ "#io-channel-cells":
+ const: 2
+ description: |
+ The first cell is the channel type (dt-bindings/iio/adc/gehc,pmc-adc.h
+ defines these values):
+ - 0: voltage
+ - 1: current
+ The second cell is the channel number from 0 to 15.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vdda-supply
+ - vddio-supply
+ - vref-supply
+ - '#io-channel-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@14 {
+ compatible = "gehc,pmc-adc";
+ reg = <0x14>;
+ vdd-supply = <&reg_vdd>;
+ vdda-supply = <&reg_vdda>;
+ vddio-supply = <&reg_vddio>;
+ vref-supply = <&reg_vref>;
+ #io-channel-cells = <2>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml b/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml
index 52490cbb0af0..56bcbe5dcd79 100644
--- a/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/holt,hi8435.yaml
@@ -24,8 +24,6 @@ properties:
GPIO used for controlling the reset pin
maxItems: 1
- spi-max-frequency: true
-
"#io-channel-cells":
const: 1
@@ -33,7 +31,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
index 433a3fb55a2e..9cd0fd539782 100644
--- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
@@ -2,10 +2,10 @@
# Copyright 2019-2020 Artur Rojek
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Ingenic JZ47xx ADC controller IIO bindings
+title: Ingenic JZ47xx ADC controller IIO
maintainers:
- Artur Rojek <contact@artur-rojek.eu>
@@ -23,6 +23,8 @@ properties:
enum:
- ingenic,jz4725b-adc
- ingenic,jz4740-adc
+ - ingenic,jz4760-adc
+ - ingenic,jz4760b-adc
- ingenic,jz4770-adc
'#io-channel-cells':
@@ -43,6 +45,23 @@ properties:
interrupts:
maxItems: 1
+ ingenic,use-internal-divider:
+ description:
+ If present, battery voltage is read from the VBAT_IR pin, which has an
+ internal 1/4 divider. If absent, it is read through the VBAT_ER pin,
+ which does not have such a divider.
+ type: boolean
+
+if:
+ not:
+ properties:
+ compatible:
+ contains:
+ const: ingenic,jz4760b-adc
+then:
+ properties:
+ ingenic,use-internal-divider: false
+
required:
- compatible
- '#io-channel-cells'
@@ -55,18 +74,18 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/clock/jz4740-cgu.h>
+ #include <dt-bindings/clock/ingenic,jz4740-cgu.h>
#include <dt-bindings/iio/adc/ingenic,adc.h>
adc@10070000 {
- compatible = "ingenic,jz4740-adc";
- #io-channel-cells = <1>;
+ compatible = "ingenic,jz4740-adc";
+ #io-channel-cells = <1>;
- reg = <0x10070000 0x30>;
+ reg = <0x10070000 0x30>;
- clocks = <&cgu JZ4740_CLK_ADC>;
- clock-names = "adc";
+ clocks = <&cgu JZ4740_CLK_ADC>;
+ clock-names = "adc";
- interrupt-parent = <&intc>;
- interrupts = <18>;
+ interrupt-parent = <&intc>;
+ interrupts = <18>;
};
diff --git a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml
index 0bd2fc0356c8..eac48166fe72 100644
--- a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml
@@ -9,7 +9,6 @@ title: Linear Technology / Analog Devices LTC2496 ADC
maintainers:
- Lars-Peter Clausen <lars@metafoo.de>
- Michael Hennerich <Michael.Hennerich@analog.com>
- - Stefan Popa <stefan.popa@analog.com>
properties:
compatible:
@@ -22,15 +21,15 @@ properties:
reg:
maxItems: 1
- spi-max-frequency:
- description: maximal spi bus frequency supported
-
required:
- compatible
- vref-supply
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml
index c1772b568cd1..5cc6a9684077 100644
--- a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml
@@ -4,19 +4,33 @@
$id: http://devicetree.org/schemas/iio/adc/lltc,ltc2497.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Linear Technology / Analog Devices LTC2497 ADC
+title: Linear Technology / Analog Devices LTC2497 and LTC2309 ADC
maintainers:
- Michael Hennerich <michael.hennerich@analog.com>
+ - Liam Beguin <liambeguin@gmail.com>
description: |
- 16bit ADC supporting up to 16 single ended or 8 differential inputs.
- I2C interface.
+ LTC2309:
+ low noise, low power, 8-channel, 12-bit successive approximation ADC with an
+ I2C compatible serial interface.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/2309fd.pdf
+
+ LTC2497:
+ LTC2499:
+ 16bit ADC supporting up to 16 single ended or 8 differential inputs.
+ I2C interface.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/2497fb.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/2499fe.pdf
properties:
compatible:
- const:
- lltc,ltc2497
+ enum:
+ - lltc,ltc2309
+ - lltc,ltc2497
+ - lltc,ltc2499
reg: true
vref-supply: true
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml
index 46b7747076b9..e4b362113509 100644
--- a/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1027.yaml
@@ -45,14 +45,17 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
spi {
- #address-cells = <1>;
- #size-cells = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
maxadc: adc@0 {
compatible = "maxim,max1027";
reg = <0>;
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max11100.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max11100.yaml
index 0cf87556ef82..4f74cb33383a 100644
--- a/Documentation/devicetree/bindings/iio/adc/maxim,max11100.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max11100.yaml
@@ -26,13 +26,16 @@ properties:
minimum: 100000
maximum: 4800000
-additionalProperties: false
-
required:
- compatible
- reg
- vref-supply
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
spi {
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1118.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1118.yaml
index e948b3e37b0c..bb336e33ebe2 100644
--- a/Documentation/devicetree/bindings/iio/adc/maxim,max1118.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1118.yaml
@@ -28,23 +28,25 @@ properties:
vref-supply:
description: External reference, needed to establish input scaling
-if:
- properties:
- compatible:
- contains:
- const: maxim,max1118
-then:
- required:
- - vref-supply
-else:
- properties:
- vref-supply: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: maxim,max1118
+ then:
+ required:
+ - vref-supply
+ else:
+ properties:
+ vref-supply: false
required:
- compatible
- reg
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max11205.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max11205.yaml
new file mode 100644
index 000000000000..5f9e043cf5cd
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max11205.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/maxim,max11205.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX11205 ADC
+
+maintainers:
+ - Ramona Bolboaca <ramona.bolboaca@analog.com>
+
+description: |
+ The MAX11205 is an ultra-low-power (< 300FA max active current),
+ high-resolution, serial-output ADC.
+
+ https://datasheets.maximintegrated.com/en/ds/MAX11205.pdf
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - maxim,max11205a
+ - maxim,max11205b
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 5000000
+
+ spi-cpha: true
+
+ vref-supply:
+ description:
+ The regulator supply for the ADC reference voltage. This is a differential
+ reference. It is equal to the V_REFP - V_REFN. The maximum value is 3.6V.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - spi-max-frequency
+ - spi-cpha
+ - vref-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc@0 {
+ compatible = "maxim,max11205a";
+ reg = <0>;
+ spi-max-frequency = <5000000>;
+ spi-cpha;
+ interrupt-parent = <&gpio>;
+ interrupts = <19 IRQ_TYPE_EDGE_FALLING>;
+ vref-supply = <&max11205_vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml
index 50bcd72ac9d6..ae3c89393f1a 100644
--- a/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1238.yaml
@@ -10,7 +10,7 @@ maintainers:
- Jonathan Cameron <jic23@kernel.org>
description: |
- Family of simple ADCs with i2c inteface and internal references.
+ Family of simple ADCs with i2c interface and internal references.
properties:
compatible:
@@ -53,6 +53,9 @@ properties:
reg:
maxItems: 1
+ "#io-channel-cells":
+ const: 1
+
vcc-supply: true
vref-supply:
description: Optional external reference. If not supplied, internal
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml
index 4c7e0d94bff1..592854766583 100644
--- a/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1241.yaml
@@ -39,22 +39,23 @@ properties:
thus enabling power-down mode.
maxItems: 1
- spi-max-frequency: true
-
required:
- compatible
- reg
- vdd-supply
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
spi {
- #address-cells = <1>;
- #size-cells = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
adc@0 {
compatible = "maxim,max1241";
@@ -62,6 +63,6 @@ examples:
vdd-supply = <&adc_vdd>;
vref-supply = <&adc_vref>;
spi-max-frequency = <1000000>;
- shutdown-gpios = <&gpio 26 1>;
+ shutdown-gpios = <&gpio 26 GPIO_ACTIVE_LOW>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml
index e04f09f35601..96f3f535fe34 100644
--- a/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max1363.yaml
@@ -10,7 +10,7 @@ maintainers:
- Jonathan Cameron <jic23@kernel.org>
description: |
- Family of ADCs with i2c inteface, internal references and threshold
+ Family of ADCs with i2c interface, internal references and threshold
monitoring.
properties:
diff --git a/Documentation/devicetree/bindings/iio/adc/maxim,max34408.yaml b/Documentation/devicetree/bindings/iio/adc/maxim,max34408.yaml
new file mode 100644
index 000000000000..4cba856e8d47
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/maxim,max34408.yaml
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/maxim,max34408.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX34408/MAX34409 current monitors with overcurrent control
+
+maintainers:
+ - Ivan Mikhaylov <fr0st61te@gmail.com>
+
+description: |
+ The MAX34408/MAX34409 are two- and four-channel current monitors that are
+ configured and monitored with a standard I2C/SMBus serial interface. Each
+ unidirectional current sensor offers precision high-side operation with a
+ low full-scale sense voltage. The devices automatically sequence through
+ two or four channels and collect the current-sense samples and average them
+ to reduce the effect of impulse noise. The raw ADC samples are compared to
+ user-programmable digital thresholds to indicate overcurrent conditions.
+ Overcurrent conditions trigger a hardware output to provide an immediate
+ indication to shut down any necessary external circuitry.
+
+ Specifications about the devices can be found at:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/MAX34408-MAX34409.pdf
+
+properties:
+ compatible:
+ enum:
+ - maxim,max34408
+ - maxim,max34409
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ powerdown-gpios:
+ description:
+ Shutdown Output. Open-drain output. This output transitions to high impedance
+ when any of the digital comparator thresholds are exceeded as long as the ENA
+ pin is high.
+ maxItems: 1
+
+ powerdown-status-gpios:
+ description:
+ SHTDN Enable Input. CMOS digital input. Connect to GND to clear the latch and
+ unconditionally deassert (force low) the SHTDN output and reset the shutdown
+ delay. Connect to VDD to enable normal latch operation of the SHTDN output.
+ maxItems: 1
+
+ vdd-supply: true
+
+patternProperties:
+ "^channel@[0-3]$":
+ $ref: adc.yaml
+ type: object
+ description:
+ Represents the internal channels of the ADC.
+
+ properties:
+ reg:
+ items:
+ - minimum: 0
+ maximum: 3
+
+ maxim,rsense-val-micro-ohms:
+ description:
+ Adjust the Rsense value to monitor higher or lower current levels for
+ input.
+ enum: [250, 500, 1000, 5000, 10000, 50000, 100000, 200000, 500000]
+ default: 1000
+
+ required:
+ - reg
+ - maxim,rsense-val-micro-ohms
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: maxim,max34408
+ then:
+ patternProperties:
+ "^channel@[2-3]$": false
+ "^channel@[0-1]$":
+ properties:
+ reg:
+ maximum: 1
+ else:
+ patternProperties:
+ "^channel@[0-3]$":
+ properties:
+ reg:
+ maximum: 3
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@1e {
+ compatible = "maxim,max34409";
+ reg = <0x1e>;
+ powerdown-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
+ powerdown-status-gpios = <&gpio0 2 GPIO_ACTIVE_HIGH>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0x0>;
+ maxim,rsense-val-micro-ohms = <5000>;
+ };
+
+ channel@1 {
+ reg = <0x1>;
+ maxim,rsense-val-micro-ohms = <10000>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml b/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml
index b939f9652e3a..d9e825e5054f 100644
--- a/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml
@@ -26,6 +26,7 @@ properties:
- mediatek,mt2712-auxadc
- mediatek,mt6765-auxadc
- mediatek,mt7622-auxadc
+ - mediatek,mt7986-auxadc
- mediatek,mt8173-auxadc
- items:
- enum:
@@ -33,7 +34,15 @@ properties:
- const: mediatek,mt2701-auxadc
- items:
- enum:
+ - mediatek,mt7981-auxadc
+ - const: mediatek,mt7986-auxadc
+ - items:
+ - enum:
+ - mediatek,mt6893-auxadc
- mediatek,mt8183-auxadc
+ - mediatek,mt8186-auxadc
+ - mediatek,mt8188-auxadc
+ - mediatek,mt8189-auxadc
- mediatek,mt8195-auxadc
- mediatek,mt8516-auxadc
- const: mediatek,mt8173-auxadc
diff --git a/Documentation/devicetree/bindings/iio/adc/mediatek,mt6359-auxadc.yaml b/Documentation/devicetree/bindings/iio/adc/mediatek,mt6359-auxadc.yaml
new file mode 100644
index 000000000000..5d4ab701f51a
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/mediatek,mt6359-auxadc.yaml
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/mediatek,mt6359-auxadc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek MT6350 series PMIC AUXADC
+
+maintainers:
+ - AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
+
+description:
+ The Auxiliary Analog/Digital Converter (AUXADC) is an ADC found
+ in some MediaTek PMICs, performing various PMIC related measurements
+ such as battery and PMIC internal voltage regulators temperatures,
+ accessory detection resistance (usually, for a 3.5mm audio jack)
+ other than voltages for various PMIC internal components.
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt6357-auxadc
+ - mediatek,mt6358-auxadc
+ - mediatek,mt6359-auxadc
+ - mediatek,mt6363-auxadc
+ - mediatek,mt6373-auxadc
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - "#io-channel-cells"
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3201.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3201.yaml
index cbbac4ce56d6..18108f0f3731 100644
--- a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3201.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3201.yaml
@@ -10,7 +10,7 @@ maintainers:
- Oskar Andero <oskar.andero@gmail.com>
description: |
- Family of simple ADCs with an I2C inteface.
+ Family of simple ADCs with a SPI interface.
properties:
compatible:
@@ -32,7 +32,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
spi-cpha: true
spi-cpol: true
@@ -51,7 +50,10 @@ required:
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml
new file mode 100644
index 000000000000..675319276197
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/microchip,mcp3564.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MCP346X and MCP356X ADC Family
+
+maintainers:
+ - Marius Cristea <marius.cristea@microchip.com>
+
+description: |
+ Bindings for the Microchip family of 153.6 ksps, Low-Noise 16/24-Bit
+ Delta-Sigma ADCs with an SPI interface. Datasheet can be found here:
+ Datasheet for MCP3561, MCP3562, MCP3564 can be found here:
+ https://ww1.microchip.com/downloads/aemDocuments/documents/MSLD/ProductDocuments/DataSheets/MCP3561-2-4-Family-Data-Sheet-DS20006181C.pdf
+ Datasheet for MCP3561R, MCP3562R, MCP3564R can be found here:
+ https://ww1.microchip.com/downloads/aemDocuments/documents/APID/ProductDocuments/DataSheets/MCP3561_2_4R-Data-Sheet-DS200006391C.pdf
+ Datasheet for MCP3461, MCP3462, MCP3464 can be found here:
+ https://ww1.microchip.com/downloads/aemDocuments/documents/APID/ProductDocuments/DataSheets/MCP3461-2-4-Two-Four-Eight-Channel-153.6-ksps-Low-Noise-16-Bit-Delta-Sigma-ADC-Data-Sheet-20006180D.pdf
+ Datasheet for MCP3461R, MCP3462R, MCP3464R can be found here:
+ https://ww1.microchip.com/downloads/aemDocuments/documents/APID/ProductDocuments/DataSheets/MCP3461-2-4R-Family-Data-Sheet-DS20006404C.pdf
+
+properties:
+ compatible:
+ enum:
+ - microchip,mcp3461
+ - microchip,mcp3462
+ - microchip,mcp3464
+ - microchip,mcp3461r
+ - microchip,mcp3462r
+ - microchip,mcp3464r
+ - microchip,mcp3561
+ - microchip,mcp3562
+ - microchip,mcp3564
+ - microchip,mcp3561r
+ - microchip,mcp3562r
+ - microchip,mcp3564r
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 20000000
+
+ spi-cpha: true
+
+ spi-cpol: true
+
+ vdd-supply: true
+
+ avdd-supply: true
+
+ clocks:
+ description:
+ Phandle and clock identifier for external sampling clock.
+ If not specified, the internal crystal oscillator will be used.
+ maxItems: 1
+
+ interrupts:
+ description: IRQ line of the ADC
+ maxItems: 1
+
+ drive-open-drain:
+ description:
+ Whether to drive the IRQ signal as push-pull (default) or open-drain. Note
+ that the device requires this pin to become "high", otherwise it will stop
+ converting.
+ type: boolean
+
+ vref-supply:
+ description:
+ Some devices have a specific reference voltage supplied on a different
+ pin to the other supplies. Needed to be able to establish channel scaling
+ unless there is also an internal reference available (e.g. mcp3564r). In
+ case of "r" devices (e. g. mcp3564r), if it does not exists the internal
+ reference will be used.
+
+ microchip,hw-device-address:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 3
+ description:
+ The address is set on a per-device basis by fuses in the factory,
+ configured on request. If not requested, the fuses are set for 0x1.
+ The device address is part of the device markings to avoid
+ potential confusion. This address is coded on two bits, so four possible
+ addresses are available when multiple devices are present on the same
+ SPI bus with only one Chip Select line for all devices.
+ Each device communication starts by a CS falling edge, followed by the
+ clocking of the device address (BITS[7:6] - top two bits of COMMAND BYTE
+ which is first one on the wire).
+
+ "#io-channel-cells":
+ const: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^channel@([0-9]|([1-7][0-9]))$":
+ $ref: adc.yaml
+ type: object
+ unevaluatedProperties: false
+ description: Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description: The channel number in single-ended and differential mode.
+ minimum: 0
+ maximum: 79
+
+ required:
+ - reg
+
+dependencies:
+ spi-cpol: [ spi-cpha ]
+ spi-cpha: [ spi-cpol ]
+
+required:
+ - compatible
+ - reg
+ - microchip,hw-device-address
+ - spi-max-frequency
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - # External vref, no internal reference
+ if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - microchip,mcp3461
+ - microchip,mcp3462
+ - microchip,mcp3464
+ - microchip,mcp3561
+ - microchip,mcp3562
+ - microchip,mcp3564
+ then:
+ required:
+ - vref-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "microchip,mcp3564r";
+ reg = <0>;
+ vref-supply = <&vref_reg>;
+ spi-cpha;
+ spi-cpol;
+ spi-max-frequency = <10000000>;
+ microchip,hw-device-address = <1>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ /* CH0 to AGND */
+ reg = <0>;
+ label = "CH0";
+ };
+
+ channel@1 {
+ /* CH1 to AGND */
+ reg = <1>;
+ label = "CH1";
+ };
+
+ /* diff-channels */
+ channel@11 {
+ reg = <11>;
+
+ /* CN0, CN1 */
+ diff-channels = <0 1>;
+ label = "CH0_CH1";
+ };
+
+ channel@22 {
+ reg = <0x22>;
+
+ /* CN1, CN2 */
+ diff-channels = <1 2>;
+ label = "CH1_CH3";
+ };
+
+ channel@23 {
+ reg = <0x23>;
+
+ /* CN1, CN3 */
+ diff-channels = <1 3>;
+ label = "CH1_CH3";
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml
index 95ab285f4eba..3a69ec60edb9 100644
--- a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml
@@ -2,8 +2,8 @@
# Copyright 2019 Marcus Folkesson <marcus.folkesson@gmail.com>
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/adc/microchip,mcp3911.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/adc/microchip,mcp3911.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Microchip MCP3911 Dual channel analog front end (ADC)
@@ -18,7 +18,13 @@ description: |
properties:
compatible:
enum:
+ - microchip,mcp3910
- microchip,mcp3911
+ - microchip,mcp3912
+ - microchip,mcp3913
+ - microchip,mcp3914
+ - microchip,mcp3918
+ - microchip,mcp3919
reg:
maxItems: 1
@@ -26,6 +32,9 @@ properties:
spi-max-frequency:
maximum: 20000000
+ reset-gpios:
+ maxItems: 1
+
clocks:
description: |
Phandle and clock identifier for external sampling clock.
@@ -36,6 +45,13 @@ properties:
description: IRQ line of the ADC
maxItems: 1
+ microchip,data-ready-hiz:
+ description:
+ Data Ready Pin Inactive State Control
+ true = The DR pin state is high-impedance
+ false = The DR pin state is logic high
+ type: boolean
+
microchip,device-addr:
description: Device address when multiple MCP3911 chips are present on the same SPI bus.
$ref: /schemas/types.yaml#/definitions/uint32
@@ -51,10 +67,14 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
+ #include <dt-bindings/gpio/gpio.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
@@ -64,6 +84,7 @@ examples:
reg = <0>;
interrupt-parent = <&gpio5>;
interrupts = <15 2>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
spi-max-frequency = <20000000>;
microchip,device-addr = <0>;
vref-supply = <&vref_reg>;
diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,pac1921.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,pac1921.yaml
new file mode 100644
index 000000000000..12e56b1b3d3f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/microchip,pac1921.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/microchip,pac1921.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip PAC1921 High-Side Power/Current Monitor with Anaog Output
+
+maintainers:
+ - Matteo Martelli <matteomartelli3@gmail.com>
+
+description: |
+ The PAC1921 is a power/current monitoring device with an analog output
+ and I2C/SMBus interface.
+
+ Datasheet can be found here:
+ https://ww1.microchip.com/downloads/en/DeviceDoc/PAC1921-Data-Sheet-DS20005293E.pdf
+
+properties:
+ compatible:
+ const: microchip,pac1921
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ "#io-channel-cells":
+ const: 1
+
+ shunt-resistor-micro-ohms:
+ description:
+ Value in micro Ohms of the shunt resistor connected between
+ the SENSE+ and SENSE- inputs, across which the current is measured.
+ Value is needed to compute the scaling of the measured current.
+
+ label:
+ description: Unique name to identify which device this is.
+
+ read-integrate-gpios:
+ description:
+ READ/INT input pin to control the current state of the device, either in
+ the INTEGRATE state when driven high, or in the READ state when driven low.
+ When not connected the pin is floating and it can be overridden by the
+ INT_EN register bit after asserting the READ/INT_OVR register bit.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - shunt-resistor-micro-ohms
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@4c {
+ compatible = "microchip,pac1921";
+ reg = <0x4c>;
+ vdd-supply = <&vdd>;
+ #io-channel-cells = <1>;
+ label = "vbat";
+ shunt-resistor-micro-ohms = <10000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,pac1934.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,pac1934.yaml
new file mode 100644
index 000000000000..47a11a9ac95e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/microchip,pac1934.yaml
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/microchip,pac1934.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip PAC1934 Power Monitors with Accumulator
+
+maintainers:
+ - Marius Cristea <marius.cristea@microchip.com>
+
+description: |
+ This device is part of the Microchip family of Power Monitors with
+ Accumulator.
+ The datasheet for PAC1931, PAC1932, PAC1933 and PAC1934 can be found here:
+ https://ww1.microchip.com/downloads/aemDocuments/documents/OTH/ProductDocuments/DataSheets/PAC1931-Family-Data-Sheet-DS20005850E.pdf
+
+properties:
+ compatible:
+ enum:
+ - microchip,pac1931
+ - microchip,pac1932
+ - microchip,pac1933
+ - microchip,pac1934
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+ slow-io-gpios:
+ description:
+ A GPIO used to trigger a change is sampling rate (lowering the chip power
+ consumption). If configured in SLOW mode, if this pin is forced high,
+ sampling rate is forced to eight samples/second. When it is forced low,
+ the sampling rate is 1024 samples/second unless a different sample rate
+ has been programmed.
+
+patternProperties:
+ "^channel@[1-4]+$":
+ type: object
+ $ref: adc.yaml
+ description:
+ Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ items:
+ minimum: 1
+ maximum: 4
+
+ shunt-resistor-micro-ohms:
+ description:
+ Value in micro Ohms of the shunt resistor connected between
+ the SENSE+ and SENSE- inputs, across which the current is measured.
+ Value is needed to compute the scaling of the measured current.
+
+ required:
+ - reg
+ - shunt-resistor-micro-ohms
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ power-monitor@10 {
+ compatible = "microchip,pac1934";
+ reg = <0x10>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@1 {
+ reg = <0x1>;
+ shunt-resistor-micro-ohms = <24900000>;
+ label = "CPU";
+ };
+
+ channel@2 {
+ reg = <0x2>;
+ shunt-resistor-micro-ohms = <49900000>;
+ label = "GPU";
+ };
+
+ channel@3 {
+ reg = <0x3>;
+ shunt-resistor-micro-ohms = <75000000>;
+ label = "MEM";
+ bipolar;
+ };
+
+ channel@4 {
+ reg = <0x4>;
+ shunt-resistor-micro-ohms = <100000000>;
+ label = "NET";
+ bipolar;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/motorola,cpcap-adc.yaml b/Documentation/devicetree/bindings/iio/adc/motorola,cpcap-adc.yaml
index a6cb857a232d..9ceb6f18c854 100644
--- a/Documentation/devicetree/bindings/iio/adc/motorola,cpcap-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/motorola,cpcap-adc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/motorola,cpcap-adc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Motorola CPCAP PMIC ADC binding
+title: Motorola CPCAP PMIC ADC
maintainers:
- Tony Lindgren <tony@atomide.com>
diff --git a/Documentation/devicetree/bindings/iio/adc/nuvoton,nct7201.yaml b/Documentation/devicetree/bindings/iio/adc/nuvoton,nct7201.yaml
new file mode 100644
index 000000000000..8ce7d415d956
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/nuvoton,nct7201.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/nuvoton,nct7201.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton nct7201 and similar ADCs
+
+maintainers:
+ - Eason Yang <j2anfernee@gmail.com>
+
+description: |
+ The NCT7201/NCT7202 is a Nuvoton Hardware Monitor IC, contains up to 12
+ voltage monitoring channels, with SMBus interface, and up to 4 sets SMBus
+ address selection by ADDR connection. It also provides ALERT# signal for
+ event notification and reset input RSTIN# to recover it from a fault
+ condition.
+
+ NCT7201 contains 8 voltage monitor inputs (VIN1~VIN8).
+ NCT7202 contains 12 voltage monitor inputs (VIN1~VIN12).
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,nct7201
+ - nuvoton,nct7202
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description:
+ A 3.3V to supply that powers the chip.
+
+ vref-supply:
+ description:
+ The regulator supply for the ADC reference voltage.
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@1d {
+ compatible = "nuvoton,nct7202";
+ reg = <0x1d>;
+ vdd-supply = <&vdd>;
+ vref-supply = <&vref>;
+ interrupt-parent = <&gpio3>;
+ interrupts = <30 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&gpio3 28 GPIO_ACTIVE_LOW>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm750-adc.yaml b/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm750-adc.yaml
index 001cf263b7d5..fede2aa64092 100644
--- a/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm750-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm750-adc.yaml
@@ -10,11 +10,14 @@ maintainers:
- Tomer Maimon <tmaimon77@gmail.com>
description:
- The NPCM ADC is a 10-bit converter for eight channel inputs.
+ The NPCM7XX ADC is a 10-bit converter and NPCM8XX ADC is a 12-bit converter,
+ both have eight channel inputs.
properties:
compatible:
- const: nuvoton,npcm750-adc
+ enum:
+ - nuvoton,npcm750-adc
+ - nuvoton,npcm845-adc
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/iio/adc/nxp,imx8qxp-adc.yaml b/Documentation/devicetree/bindings/iio/adc/nxp,imx8qxp-adc.yaml
new file mode 100644
index 000000000000..0a192ca192c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/nxp,imx8qxp-adc.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/nxp,imx8qxp-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP IMX8QXP ADC
+
+maintainers:
+ - Cai Huoqing <caihuoqing@baidu.com>
+
+description:
+ Supports the ADC found on the IMX8QXP SoC.
+
+properties:
+ compatible:
+ const: nxp,imx8qxp-adc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: per
+ - const: ipg
+
+ assigned-clocks:
+ maxItems: 1
+
+ assigned-clock-rates:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ vref-supply:
+ description: |
+ External ADC reference voltage supply on VREFH pad. If VERID[MVI] is
+ set, there are additional, internal reference voltages selectable.
+ VREFH1 is always from VREFH pad.
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - assigned-clocks
+ - assigned-clock-rates
+ - power-domains
+ - "#io-channel-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/firmware/imx/rsrc.h>
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ adc@5a880000 {
+ compatible = "nxp,imx8qxp-adc";
+ reg = <0x0 0x5a880000 0x0 0x10000>;
+ interrupts = <GIC_SPI 240 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX_SC_R_ADC_0>,
+ <&clk IMX_SC_R_ADC_0>;
+ clock-names = "per", "ipg";
+ assigned-clocks = <&clk IMX_SC_R_ADC_0>;
+ assigned-clock-rates = <24000000>;
+ power-domains = <&pd IMX_SC_R_ADC_0>;
+ vref-supply = <&reg_1v8>;
+ #io-channel-cells = <1>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml b/Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml
new file mode 100644
index 000000000000..c2e5ff418920
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/nxp,imx93-adc.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/nxp,imx93-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP iMX93 ADC
+
+maintainers:
+ - Haibo Chen <haibo.chen@nxp.com>
+
+description:
+ The ADC on iMX93 is a 8-channel 12-bit 1MS/s ADC with 4 channels
+ connected to pins. it support normal and inject mode, include
+ One-Shot and Scan (continuous) conversions. Programmable DMA
+ enables for each channel Also this ADC contain alternate analog
+ watchdog thresholds, select threshold through input ports. And
+ also has Self-test logic and Software-initiated calibration.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - nxp,imx93-adc
+ - items:
+ - enum:
+ - nxp,imx94-adc
+ - nxp,imx95-adc
+ - const: nxp,imx93-adc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: WDGnL, watchdog threshold interrupt requests.
+ - description: WDGnH, watchdog threshold interrupt requests.
+ - description: normal conversion, include EOC (End of Conversion),
+ ECH (End of Chain), JEOC (End of Injected Conversion) and
+ JECH (End of injected Chain).
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: ipg
+
+ vref-supply:
+ description:
+ The reference voltage which used to establish channel scaling.
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - vref-supply
+ - "#io-channel-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/imx93-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ soc {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ adc@44530000 {
+ compatible = "nxp,imx93-adc";
+ reg = <0x44530000 0x10000>;
+ interrupts = <GIC_SPI 217 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 218 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 219 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX93_CLK_ADC1_GATE>;
+ clock-names = "ipg";
+ vref-supply = <&reg_vref_1v8>;
+ #io-channel-cells = <1>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/nxp,lpc1850-adc.yaml b/Documentation/devicetree/bindings/iio/adc/nxp,lpc1850-adc.yaml
index 6404fb73f8ed..70b38038a080 100644
--- a/Documentation/devicetree/bindings/iio/adc/nxp,lpc1850-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/nxp,lpc1850-adc.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/iio/adc/nxp,lpc1850-adc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: NXP LPC1850 ADC bindings
+title: NXP LPC1850 ADC
maintainers:
- - Joachim Eastwood <manabian@gmail.com>
+ - Jonathan Cameron <jic23@kernel.org>
description:
Supports the ADC found on the LPC1850 SoC.
diff --git a/Documentation/devicetree/bindings/iio/adc/nxp,lpc3220-adc.yaml b/Documentation/devicetree/bindings/iio/adc/nxp,lpc3220-adc.yaml
index 2c5032be83bd..fd815ab30df1 100644
--- a/Documentation/devicetree/bindings/iio/adc/nxp,lpc3220-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/nxp,lpc3220-adc.yaml
@@ -22,6 +22,9 @@ properties:
interrupts:
maxItems: 1
+ clocks:
+ maxItems: 1
+
vref-supply: true
"#io-channel-cells":
diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml
index d186b713d6a7..58ea1ca4a5ee 100644
--- a/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/qcom,pm8018-adc.yaml
@@ -160,7 +160,7 @@ examples:
};
ref_muxoff: adc-channel@f {
reg = <0x00 0x0f>;
- };
+ };
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml
index 27e3108661c0..5ed893ef5c18 100644
--- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.yaml
@@ -18,10 +18,14 @@ description: |
properties:
compatible:
- const: qcom,spmi-iadc
+ items:
+ - enum:
+ - qcom,pm8226-iadc
+ - qcom,pm8941-iadc
+ - const: qcom,spmi-iadc
reg:
- description: IADC base address and length in the SPMI PMIC register map
+ description: IADC base address in the SPMI PMIC register map
maxItems: 1
qcom,external-resistor-micro-ohms:
@@ -46,15 +50,17 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- spmi_bus {
+
+ pmic {
#address-cells = <1>;
#size-cells = <0>;
- pmic_iadc: adc@3600 {
- compatible = "qcom,spmi-iadc";
- reg = <0x3600 0x100>;
+
+ adc@3600 {
+ compatible = "qcom,pm8941-iadc", "qcom,spmi-iadc";
+ reg = <0x3600>;
interrupts = <0x0 0x36 0x0 IRQ_TYPE_EDGE_RISING>;
qcom,external-resistor-micro-ohms = <10000>;
- #io-channel-cells = <1>;
+ #io-channel-cells = <1>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml
new file mode 100644
index 000000000000..862e450da214
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-rradc.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/qcom,spmi-rradc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm's SPMI PMIC Round Robin ADC
+
+maintainers:
+ - Casey Connolly <casey.connolly@linaro.org>
+
+description: |
+ The Qualcomm SPMI Round Robin ADC (RRADC) provides interface to clients to
+ read the voltage, current and temperature for supported peripherals such as
+ the battery thermistor die temperature, charger temperature, USB and DC input
+ voltage / current and battery ID resistor.
+
+properties:
+ compatible:
+ enum:
+ - qcom,pmi8998-rradc
+ - qcom,pm660-rradc
+
+ reg:
+ maxItems: 1
+
+ qcom,batt-id-delay-ms:
+ description: Sets the hardware settling time for the battery ID resistor.
+ enum: [0, 1, 4, 12, 20, 40, 60, 80]
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ pmic {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@4500 {
+ compatible = "qcom,pmi8998-rradc";
+ reg = <0x4500>;
+ #io-channel-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml
index 74a4a9d95798..b9dc04b0d307 100644
--- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml
@@ -22,13 +22,11 @@ properties:
- items:
- const: qcom,pms405-adc
- const: qcom,spmi-adc-rev2
-
- - items:
- - enum:
- - qcom,spmi-vadc
- - qcom,spmi-adc5
- - qcom,spmi-adc-rev2
- - qcom,spmi-adc7
+ - enum:
+ - qcom,spmi-vadc
+ - qcom,spmi-adc5
+ - qcom,spmi-adc-rev2
+ - qcom,spmi-adc7
reg:
description: VADC base address in the SPMI PMIC register map
@@ -56,8 +54,9 @@ required:
- '#io-channel-cells'
patternProperties:
- "^.*@[0-9a-f]+$":
+ "^channel@[0-9a-f]+$":
type: object
+ additionalProperties: false
description: |
Represents the external channels which are connected to the ADC.
For compatible property "qcom,spmi-vadc" following channels, also known as
@@ -76,7 +75,6 @@ patternProperties:
in the PMIC-specific files in include/dt-bindings/iio/.
label:
- $ref: /schemas/types.yaml#/definitions/string
description: |
ADC input of the platform as seen in the schematics.
For thermistor inputs connected to generic AMUX or GPIO inputs
@@ -102,7 +100,7 @@ patternProperties:
oneOf:
- items:
- const: 1
- - enum: [ 1, 3, 4, 6, 20, 8, 10 ]
+ - enum: [ 1, 3, 4, 6, 20, 8, 10, 16 ]
- items:
- const: 10
- const: 81
@@ -149,7 +147,7 @@ allOf:
then:
patternProperties:
- "^.*@[0-9a-f]+$":
+ "^channel@[0-9a-f]+$":
properties:
qcom,decimation:
enum: [ 512, 1024, 2048, 4096 ]
@@ -172,7 +170,7 @@ allOf:
then:
patternProperties:
- "^.*@[0-9a-f]+$":
+ "^channel@[0-9a-f]+$":
properties:
qcom,decimation:
enum: [ 256, 512, 1024 ]
@@ -195,7 +193,7 @@ allOf:
then:
patternProperties:
- "^.*@[0-9a-f]+$":
+ "^channel@[0-9a-f]+$":
properties:
qcom,decimation:
enum: [ 250, 420, 840 ]
@@ -218,7 +216,7 @@ allOf:
then:
patternProperties:
- "^.*@[0-9a-f]+$":
+ "^channel@[0-9a-f]+$":
properties:
qcom,decimation:
enum: [ 85, 340, 1360 ]
@@ -237,42 +235,74 @@ additionalProperties: false
examples:
- |
- spmi_bus {
- #address-cells = <1>;
- #size-cells = <0>;
- /* VADC node */
- pmic_vadc: adc@3100 {
- compatible = "qcom,spmi-vadc";
- reg = <0x3100>;
- interrupts = <0x0 0x31 0x0 0x1>;
+ pmic {
#address-cells = <1>;
#size-cells = <0>;
- #io-channel-cells = <1>;
-
- /* Channel node */
- adc-chan@39 {
- reg = <0x39>;
- qcom,decimation = <512>;
- qcom,ratiometric;
- qcom,hw-settle-time = <200>;
- qcom,avg-samples = <1>;
- qcom,pre-scaling = <1 3>;
- };
- adc-chan@9 {
- reg = <0x9>;
+ adc@3100 {
+ compatible = "qcom,spmi-vadc";
+ reg = <0x3100>;
+ interrupts = <0x0 0x31 0x0 0x1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #io-channel-cells = <1>;
+
+ /* Channel node */
+ channel@39 {
+ reg = <0x39>;
+ qcom,decimation = <512>;
+ qcom,ratiometric;
+ qcom,hw-settle-time = <200>;
+ qcom,avg-samples = <1>;
+ qcom,pre-scaling = <1 3>;
+ };
+
+ channel@9 {
+ reg = <0x9>;
+ };
+
+ channel@a {
+ reg = <0xa>;
+ };
+
+ channel@e {
+ reg = <0xe>;
+ };
+
+ channel@f {
+ reg = <0xf>;
+ };
};
+ };
- adc-chan@a {
- reg = <0xa>;
- };
+ - |
+ #include <dt-bindings/iio/qcom,spmi-adc7-pmk8350.h>
+ #include <dt-bindings/iio/qcom,spmi-adc7-pm8350.h>
- adc-chan@e {
- reg = <0xe>;
- };
+ pmic {
+ #address-cells = <1>;
+ #size-cells = <0>;
- adc-chan@f {
- reg = <0xf>;
+ adc@3100 {
+ reg = <0x3100>;
+ compatible = "qcom,spmi-adc7";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #io-channel-cells = <1>;
+
+ /* Other properties are omitted */
+ channel@44 {
+ reg = <PMK8350_ADC7_AMUX_THM1_100K_PU>;
+ qcom,ratiometric;
+ qcom,hw-settle-time = <200>;
+ label = "xo_therm";
+ };
+
+ channel@47 {
+ reg = <PM8350_ADC7_AMUX_THM4_100K_PU(1)>;
+ qcom,ratiometric;
+ qcom,hw-settle-time = <200>;
+ label = "conn_therm";
+ };
};
- };
};
diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,r9a09g077-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,r9a09g077-adc.yaml
new file mode 100644
index 000000000000..dc0206b28231
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/renesas,r9a09g077-adc.yaml
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/renesas,r9a09g077-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/T2H / RZ/N2H ADC12
+
+maintainers:
+ - Cosmin Tanislav <cosmin-gabriel.tanislav.xa@renesas.com>
+
+description: |
+ A/D Converter block is a successive approximation analog-to-digital converter
+ with a 12-bit accuracy. Up to 16 analog input channels can be selected.
+ Conversions can be performed in single or continuous mode. Result of the ADC
+ is stored in a 16-bit data register corresponding to each channel.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: renesas,r9a09g087-adc # RZ/N2H
+ - const: renesas,r9a09g077-adc # RZ/T2H
+ - items:
+ - const: renesas,r9a09g077-adc # RZ/T2H
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: A/D scan end interrupt
+ - description: A/D scan end interrupt for Group B
+ - description: A/D scan end interrupt for Group C
+ - description: Window A compare match
+ - description: Window B compare match
+ - description: Compare match
+ - description: Compare mismatch
+
+ interrupt-names:
+ items:
+ - const: adi
+ - const: gbadi
+ - const: gcadi
+ - const: cmpai
+ - const: cmpbi
+ - const: wcmpm
+ - const: wcmpum
+
+ clocks:
+ items:
+ - description: Converter clock
+ - description: Peripheral clock
+
+ clock-names:
+ items:
+ - const: adclk
+ - const: pclk
+
+ power-domains:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ "#io-channel-cells":
+ const: 1
+
+patternProperties:
+ "^channel@[0-9a-f]$":
+ $ref: adc.yaml
+ type: object
+ description: The external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description: The channel number.
+ maximum: 15
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/renesas,r9a09g077-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ adc@80008000 {
+ compatible = "renesas,r9a09g077-adc";
+ reg = <0x80008000 0x400>;
+ interrupts = <GIC_SPI 708 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 709 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 710 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 711 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 712 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 855 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 856 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "adi", "gbadi", "gcadi",
+ "cmpai", "cmpbi", "wcmpm", "wcmpum";
+ clocks = <&cpg CPG_CORE R9A09G077_CLK_PCLKL>,
+ <&cpg CPG_MOD 225>;
+ clock-names = "adclk", "pclk";
+ power-domains = <&cpg>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #io-channel-cells = <1>;
+
+ channel@0 {
+ reg = <0x0>;
+ };
+ channel@1 {
+ reg = <0x1>;
+ };
+ channel@2 {
+ reg = <0x2>;
+ };
+ channel@3 {
+ reg = <0x3>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rcar-gyroadc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rcar-gyroadc.yaml
index c115e2e99bd9..36dff3250ea7 100644
--- a/Documentation/devicetree/bindings/iio/adc/renesas,rcar-gyroadc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/renesas,rcar-gyroadc.yaml
@@ -34,9 +34,11 @@ properties:
clock-names:
const: fck
- power-domains: true
+ power-domains:
+ maxItems: 1
- resets: true
+ resets:
+ maxItems: 1
"#address-cells":
const: 1
@@ -51,6 +53,8 @@ required:
- reg
- clocks
- clock-names
+ - power-domains
+ - resets
- "#address-cells"
- "#size-cells"
@@ -86,7 +90,7 @@ patternProperties:
of the MAX chips to the GyroADC, while MISO line of each Maxim
ADC connects to a shared input pin of the GyroADC.
enum:
- - adi,7476
+ - adi,ad7476
- fujitsu,mb88101a
- maxim,max1162
- maxim,max11100
@@ -108,36 +112,30 @@ patternProperties:
examples:
- |
- #include <dt-bindings/clock/r8a7791-clock.h>
+ #include <dt-bindings/clock/r8a7791-cpg-mssr.h>
#include <dt-bindings/power/r8a7791-sysc.h>
- soc {
- #address-cells = <2>;
- #size-cells = <2>;
-
- adc@e6e54000 {
- compatible = "renesas,r8a7791-gyroadc", "renesas,rcar-gyroadc";
- reg = <0 0xe6e54000 0 64>;
- clocks = <&mstp9_clks R8A7791_CLK_GYROADC>;
- clock-names = "fck";
- power-domains = <&sysc R8A7791_PD_ALWAYS_ON>;
-
- pinctrl-0 = <&adc_pins>;
- pinctrl-names = "default";
-
- #address-cells = <1>;
- #size-cells = <0>;
-
- adc@0 {
- reg = <0>;
- compatible = "maxim,max1162";
- vref-supply = <&vref_max1162>;
- };
-
- adc@1 {
- reg = <1>;
- compatible = "maxim,max1162";
- vref-supply = <&vref_max1162>;
- };
+
+ adc@e6e54000 {
+ compatible = "renesas,r8a7791-gyroadc", "renesas,rcar-gyroadc";
+ reg = <0xe6e54000 64>;
+ clocks = <&cpg CPG_MOD 901>;
+ clock-names = "fck";
+ power-domains = <&sysc R8A7791_PD_ALWAYS_ON>;
+ resets = <&cpg 901>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ reg = <0>;
+ compatible = "maxim,max1162";
+ vref-supply = <&vref_max1162>;
+ };
+
+ adc@1 {
+ reg = <1>;
+ compatible = "maxim,max1162";
+ vref-supply = <&vref_max1162>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
new file mode 100644
index 000000000000..40341d541726
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/G2L ADC
+
+maintainers:
+ - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
+
+description: |
+ A/D Converter block is a successive approximation analog-to-digital converter
+ with a 12-bit accuracy. Up to eight analog input channels can be selected.
+ Conversions can be performed in single or repeat mode. Result of the ADC is
+ stored in a 32-bit data register corresponding to each channel.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,r9a07g043-adc # RZ/G2UL and RZ/Five
+ - renesas,r9a07g044-adc # RZ/G2L
+ - renesas,r9a07g054-adc # RZ/V2L
+ - const: renesas,rzg2l-adc
+ - items:
+ - const: renesas,r9a08g045-adc # RZ/G3S
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: converter clock
+ - description: peripheral clock
+
+ clock-names:
+ items:
+ - const: adclk
+ - const: pclk
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 2
+
+ reset-names:
+ items:
+ - const: presetn
+ - const: adrst-n
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+ - reset-names
+
+patternProperties:
+ "^channel@[0-8]$":
+ $ref: adc.yaml
+ type: object
+ description: |
+ Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description: |
+ The channel number.
+ minimum: 0
+ maximum: 8
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a07g043-adc
+ then:
+ patternProperties:
+ "^channel@[2-8]$": false
+ "^channel@[0-1]$":
+ properties:
+ reg:
+ maximum: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r9a07g044-adc
+ - renesas,r9a07g054-adc
+ then:
+ patternProperties:
+ "^channel@[8]$": false
+ "^channel@[0-7]$":
+ properties:
+ reg:
+ maximum: 7
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r9a07g044-cpg.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ adc: adc@10059000 {
+ compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
+ reg = <0x10059000 0x400>;
+ interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
+ clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
+ <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
+ clock-names = "adclk", "pclk";
+ power-domains = <&cpg>;
+ resets = <&cpg R9A07G044_ADC_PRESETN>,
+ <&cpg R9A07G044_ADC_ADRST_N>;
+ reset-names = "presetn", "adrst-n";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ };
+ channel@1 {
+ reg = <1>;
+ };
+ channel@2 {
+ reg = <2>;
+ };
+ channel@3 {
+ reg = <3>;
+ };
+ channel@4 {
+ reg = <4>;
+ };
+ channel@5 {
+ reg = <5>;
+ };
+ channel@6 {
+ reg = <6>;
+ };
+ channel@7 {
+ reg = <7>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzn1-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzn1-adc.yaml
new file mode 100644
index 000000000000..1a40352165fb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzn1-adc.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/renesas,rzn1-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/N1 Analog to Digital Converter (ADC)
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description:
+ The Renesas RZ/N1 ADC controller available in the Renesas RZ/N1 SoCs family
+ can use up to two internal ADC cores (ADC1 and ADC2) those internal cores are
+ handled through ADC controller virtual channels.
+
+properties:
+ compatible:
+ items:
+ - const: renesas,r9a06g032-adc # RZ/N1D
+ - const: renesas,rzn1-adc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: APB internal bus clock
+ - description: ADC clock
+
+ clock-names:
+ items:
+ - const: pclk
+ - const: adc
+
+ power-domains:
+ maxItems: 1
+
+ adc1-avdd-supply:
+ description:
+ ADC1 analog power supply.
+
+ adc1-vref-supply:
+ description:
+ ADC1 reference voltage supply.
+
+ adc2-avdd-supply:
+ description:
+ ADC2 analog power supply.
+
+ adc2-vref-supply:
+ description:
+ ADC2 reference voltage supply.
+
+ '#io-channel-cells':
+ const: 1
+ description: |
+ Channels numbers available:
+ if ADC1 is used (i.e. adc1-{avdd,vref}-supply present):
+ - 0: ADC1 IN0
+ - 1: ADC1 IN1
+ - 2: ADC1 IN2
+ - 3: ADC1 IN3
+ - 4: ADC1 IN4
+ - 5: ADC1 IN6
+ - 6: ADC1 IN7
+ - 7: ADC1 IN8
+ if ADC2 is used (i.e. adc2-{avdd,vref}-supply present):
+ - 8: ADC2 IN0
+ - 9: ADC2 IN1
+ - 10: ADC2 IN2
+ - 11: ADC2 IN3
+ - 12: ADC2 IN4
+ - 13: ADC2 IN6
+ - 14: ADC2 IN7
+ - 15: ADC2 IN8
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - power-domains
+ - '#io-channel-cells'
+
+# At least one of avvd/vref supplies
+anyOf:
+ - required:
+ - adc1-vref-supply
+ - adc1-avdd-supply
+ - required:
+ - adc2-vref-supply
+ - adc2-avdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r9a06g032-sysctrl.h>
+
+ adc: adc@40065000 {
+ compatible = "renesas,r9a06g032-adc", "renesas,rzn1-adc";
+ reg = <0x40065000 0x200>;
+ clocks = <&sysctrl R9A06G032_HCLK_ADC>, <&sysctrl R9A06G032_CLK_ADC>;
+ clock-names = "pclk", "adc";
+ power-domains = <&sysctrl>;
+ adc1-avdd-supply = <&adc1_avdd>;
+ adc1-vref-supply = <&adc1_vref>;
+ #io-channel-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml b/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml
new file mode 100644
index 000000000000..af2c3a67f888
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/richtek,rtq6056.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RTQ6056 Bi-Directional Current and Power Monitor with 16-bit ADC
+
+maintainers:
+ - ChiYuan Huang <cy_huang@richtek.com>
+
+description: |
+ The RTQ6056 is a high accuracy current-sense monitor with I2C and SMBus
+ interface, and the device provides full information for system by reading
+ out the loading current and power.
+
+ The device monitors both of the drops across sense resistor and the BUS
+ voltage, converts into the current in amperes, and power in watts through
+ internal analog-to-digital converter ADC. The programmable calibration,
+ adjustable conversion time, and averaging function are also built in for
+ more design flexibility.
+
+ Datasheet is available at
+ https://www.richtek.com/assets/product_file/RTQ6056/DSQ6056-00.pdf
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - richtek,rtq6056
+ - richtek,rtq6059
+ - items:
+ - enum:
+ - richtek,rtq6053
+ - const: richtek,rtq6056
+
+ reg:
+ maxItems: 1
+
+ "#io-channel-cells":
+ const: 1
+
+ shunt-resistor-micro-ohms:
+ description: Shunt IN+/IN- sensing node resistor
+
+required:
+ - compatible
+ - reg
+ - "#io-channel-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc@40 {
+ compatible = "richtek,rtq6056";
+ reg = <0x40>;
+ #io-channel-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml
index 1bb76197787b..6769d679c907 100644
--- a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.yaml
@@ -15,12 +15,23 @@ properties:
- const: rockchip,saradc
- const: rockchip,rk3066-tsadc
- const: rockchip,rk3399-saradc
+ - const: rockchip,rk3528-saradc
+ - items:
+ - const: rockchip,rk3506-saradc
+ - const: rockchip,rk3528-saradc
+ - const: rockchip,rk3562-saradc
+ - const: rockchip,rk3588-saradc
+ - items:
+ - const: rockchip,rk3576-saradc
+ - const: rockchip,rk3588-saradc
- items:
- enum:
- rockchip,px30-saradc
- rockchip,rk3308-saradc
- rockchip,rk3328-saradc
+ - rockchip,rk3568-saradc
- rockchip,rv1108-saradc
+ - rockchip,rv1126-saradc
- const: rockchip,rk3399-saradc
reg:
@@ -39,6 +50,9 @@ properties:
- const: saradc
- const: apb_pclk
+ power-domains:
+ maxItems: 1
+
resets:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/iio/adc/rohm,bd79104.yaml b/Documentation/devicetree/bindings/iio/adc/rohm,bd79104.yaml
new file mode 100644
index 000000000000..d5192ec58f59
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/rohm,bd79104.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/rohm,bd79104.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM Semiconductor BD79104 ADC
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description: |
+ 12 bit SPI ADC with 8 channels.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - rohm,bd79100
+ - rohm,bd79101
+ - rohm,bd79102
+ - rohm,bd79104
+ - items:
+ - const: rohm,bd79103
+ - const: rohm,bd79104
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ iovdd-supply: true
+
+# The component data-sheet says the frequency is 20M. I, however, found
+# that the ROHM evaluation board BD79104FV-EVK-001 had problems with 20M.
+# I have successfully used it with 4M. My _assumption_ is that this is not
+# the limitation of the component itself, but a limitation of the EVK.
+ spi-max-frequency:
+ maximum: 20000000
+
+ "#io-channel-cells":
+ const: 1
+
+ spi-cpha: true
+ spi-cpol: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - iovdd-supply
+ - spi-cpha
+ - spi-cpol
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "rohm,bd79104";
+ reg = <0>;
+ vdd-supply = <&vdd_supply>;
+ iovdd-supply = <&iovdd_supply>;
+ spi-max-frequency = <4000000>;
+ spi-cpha;
+ spi-cpol;
+ #io-channel-cells = <1>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/rohm,bd79112.yaml b/Documentation/devicetree/bindings/iio/adc/rohm,bd79112.yaml
new file mode 100644
index 000000000000..aa8b07c3fac1
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/rohm,bd79112.yaml
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/rohm,bd79112.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BD79112 ADC/GPO
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description: |
+ The ROHM BD79112 is a 12-bit, 32-channel, SAR ADC. ADC input pins can be
+ also configured as general purpose inputs/outputs. SPI should use MODE 3.
+
+properties:
+ compatible:
+ const: rohm,bd79112
+
+ reg:
+ maxItems: 1
+
+ spi-cpha: true
+ spi-cpol: true
+
+ gpio-controller: true
+ "#gpio-cells":
+ const: 2
+
+ vdd-supply: true
+
+ iovdd-supply: true
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^channel@([0-9]|[12][0-9]|3[01])$":
+ type: object
+ $ref: /schemas/iio/adc/adc.yaml#
+ description: Represents ADC channel. Omitted channels' inputs are GPIOs.
+
+ properties:
+ reg:
+ description: AIN pin number
+ minimum: 0
+ maximum: 31
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - iovdd-supply
+ - vdd-supply
+ - spi-cpha
+ - spi-cpol
+
+additionalProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc: adc@0 {
+ compatible = "rohm,bd79112";
+ reg = <0x0>;
+
+ spi-cpha;
+ spi-cpol;
+
+ vdd-supply = <&dummyreg>;
+ iovdd-supply = <&dummyreg>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ channel@0 {
+ reg = <0>;
+ };
+ channel@1 {
+ reg = <1>;
+ };
+ channel@2 {
+ reg = <2>;
+ };
+ channel@16 {
+ reg = <16>;
+ };
+ channel@20 {
+ reg = <20>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/rohm,bd79124.yaml b/Documentation/devicetree/bindings/iio/adc/rohm,bd79124.yaml
new file mode 100644
index 000000000000..4a8f127de7e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/rohm,bd79124.yaml
@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/rohm,bd79124.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BD79124 ADC/GPO
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description: |
+ The ROHM BD79124 is a 12-bit, 8-channel, SAR ADC. The ADC supports
+ an automatic measurement mode, with an alarm interrupt for out-of-window
+ measurements. ADC input pins can be also configured as general purpose
+ outputs.
+
+properties:
+ compatible:
+ const: rohm,bd79124
+
+ reg:
+ description:
+ I2C slave address.
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 1
+ description:
+ The pin number.
+
+ vdd-supply: true
+
+ iovdd-supply: true
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^channel@[0-7]+$":
+ type: object
+ $ref: /schemas/iio/adc/adc.yaml#
+ description: Represents ADC channel.
+
+ properties:
+ reg:
+ description: AIN pin number
+ minimum: 0
+ maximum: 7
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - iovdd-supply
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/leds/common.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc: adc@10 {
+ compatible = "rohm,bd79124";
+ reg = <0x10>;
+
+ interrupt-parent = <&gpio1>;
+ interrupts = <29 IRQ_TYPE_LEVEL_LOW>;
+
+ vdd-supply = <&dummyreg>;
+ iovdd-supply = <&dummyreg>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ };
+ channel@1 {
+ reg = <1>;
+ };
+ channel@2 {
+ reg = <2>;
+ };
+ channel@3 {
+ reg = <3>;
+ };
+ channel@4 {
+ reg = <4>;
+ };
+ channel@5 {
+ reg = <5>;
+ };
+ channel@6 {
+ reg = <6>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml
index c65921e66dc1..def879f6ed20 100644
--- a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.yaml
@@ -11,18 +11,19 @@ maintainers:
properties:
compatible:
- enum:
- - samsung,exynos-adc-v1 # Exynos5250
- - samsung,exynos-adc-v2
- - samsung,exynos3250-adc
- - samsung,exynos4212-adc # Exynos4212 and Exynos4412
- - samsung,exynos7-adc
- - samsung,s3c2410-adc
- - samsung,s3c2416-adc
- - samsung,s3c2440-adc
- - samsung,s3c2443-adc
- - samsung,s3c6410-adc
- - samsung,s5pv210-adc
+ oneOf:
+ - enum:
+ - samsung,exynos-adc-v1 # Exynos5250
+ - samsung,exynos-adc-v2
+ - samsung,exynos3250-adc
+ - samsung,exynos4212-adc # Exynos4212 and Exynos4412
+ - samsung,exynos7-adc
+ - samsung,s3c6410-adc
+ - samsung,s5pv210-adc
+ - items:
+ - enum:
+ - samsung,exynos5433-adc
+ - const: samsung,exynos7-adc
reg:
maxItems: 1
@@ -41,8 +42,6 @@ properties:
maxItems: 2
interrupts:
- description:
- ADC interrupt followed by optional touchscreen interrupt.
minItems: 1
maxItems: 2
@@ -52,16 +51,11 @@ properties:
vdd-supply: true
samsung,syscon-phandle:
- $ref: '/schemas/types.yaml#/definitions/phandle'
+ $ref: /schemas/types.yaml#/definitions/phandle
description:
Phandle to the PMU system controller node (to access the ADC_PHY
register on Exynos3250/4x12/5250/5420/5800).
- has-touchscreen:
- description:
- If present, indicates that a touchscreen is connected and usable.
- type: boolean
-
required:
- compatible
- reg
@@ -113,20 +107,29 @@ allOf:
- const: adc
- if:
- required:
- - has-touchscreen
+ properties:
+ compatible:
+ contains:
+ const: samsung,s5pv210-adc
then:
properties:
interrupts:
- minItems: 2
- maxItems: 2
+ items:
+ - description: main (ADC)
+ - description: pending (PENDN)
+ else:
+ properties:
+ interrupts:
+ maxItems: 1
examples:
- |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
adc: adc@12d10000 {
compatible = "samsung,exynos-adc-v1";
reg = <0x12d10000 0x100>;
- interrupts = <0 106 0>;
+ interrupts = <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH>;
#io-channel-cells = <1>;
clocks = <&clock 303>;
@@ -136,22 +139,23 @@ examples:
samsung,syscon-phandle = <&pmu_system_controller>;
/* NTC thermistor is a hwmon device */
- ncp15wb473 {
+ thermistor {
compatible = "murata,ncp15wb473";
pullup-uv = <1800000>;
pullup-ohm = <47000>;
pulldown-ohm = <0>;
io-channels = <&adc 4>;
- };
+ };
};
- |
#include <dt-bindings/clock/exynos3250.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
adc@126c0000 {
compatible = "samsung,exynos3250-adc";
- reg = <0x126C0000 0x100>;
- interrupts = <0 137 0>;
+ reg = <0x126c0000 0x100>;
+ interrupts = <GIC_SPI 137 IRQ_TYPE_LEVEL_HIGH>;
#io-channel-cells = <1>;
clocks = <&cmu CLK_TSADC>,
diff --git a/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml
index a390343d0c2a..c3a116427dc3 100644
--- a/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/iio/adc/sigma-delta-modulator.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Device-Tree bindings for sigma delta modulator
+title: Sigma delta modulator
maintainers:
- - Arnaud Pouliquen <arnaud.pouliquen@st.com>
+ - Arnaud Pouliquen <arnaud.pouliquen@foss.st.com>
properties:
compatible:
@@ -18,18 +18,39 @@ properties:
- sd-modulator
- ads1201
+ '#io-backend-cells':
+ const: 0
+
'#io-channel-cells':
const: 0
+ vref-supply:
+ description: Phandle to the vref input analog reference voltage.
+
+dependencies:
+ vref-supply: [ '#io-backend-cells' ]
+
required:
- compatible
- - '#io-channel-cells'
+
+anyOf:
+ - required: ['#io-backend-cells']
+ - required: ['#io-channel-cells']
additionalProperties: false
examples:
- |
- ads1202: adc {
+ // Backend binding example. SD modulator configured as an IIO backend device
+ ads1201_0: adc {
+ compatible = "sd-modulator";
+ vref-supply = <&vdd_adc>;
+ #io-backend-cells = <0>;
+ };
+
+ - |
+ // Legacy binding example. SD modulator configured as an IIO channel provider
+ ads1201_1: adc {
compatible = "sd-modulator";
#io-channel-cells = <0>;
};
diff --git a/Documentation/devicetree/bindings/iio/adc/sophgo,cv1800b-saradc.yaml b/Documentation/devicetree/bindings/iio/adc/sophgo,cv1800b-saradc.yaml
new file mode 100644
index 000000000000..f652b98615f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/sophgo,cv1800b-saradc.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/sophgo,cv1800b-saradc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title:
+ Sophgo CV1800B SoC 3 channels Successive Approximation Analog to
+ Digital Converters
+
+maintainers:
+ - Thomas Bonnefille <thomas.bonnefille@bootlin.com>
+
+description:
+ Datasheet at https://github.com/sophgo/sophgo-doc/releases
+
+properties:
+ compatible:
+ const: sophgo,cv1800b-saradc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@[0-2]$":
+ $ref: adc.yaml
+
+ properties:
+ reg:
+ items:
+ - minimum: 0
+ maximum: 2
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - '#address-cells'
+ - '#size-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/sophgo,cv1800.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ adc@30f0000 {
+ compatible = "sophgo,cv1800b-saradc";
+ reg = <0x030f0000 0x1000>;
+ clocks = <&clk CLK_SARADC>;
+ interrupts = <100 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ };
+
+ channel@2 {
+ reg = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/sprd,sc2720-adc.yaml b/Documentation/devicetree/bindings/iio/adc/sprd,sc2720-adc.yaml
index caa3ee0b4b8c..a678323d78e3 100644
--- a/Documentation/devicetree/bindings/iio/adc/sprd,sc2720-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/sprd,sc2720-adc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/sprd,sc2720-adc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Spreadtrum SC27XX series PMICs ADC binding
+title: Spreadtrum SC27XX series PMICs ADC
maintainers:
- Baolin Wang <baolin.wang7@gmail.com>
@@ -20,6 +20,7 @@ properties:
- sprd,sc2723-adc
- sprd,sc2730-adc
- sprd,sc2731-adc
+ - sprd,ump9620-adc
reg:
maxItems: 1
@@ -33,13 +34,39 @@ properties:
hwlocks:
maxItems: 1
- nvmem-cells:
- maxItems: 2
+ nvmem-cells: true
- nvmem-cell-names:
- items:
- - const: big_scale_calib
- - const: small_scale_calib
+ nvmem-cell-names: true
+
+allOf:
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - sprd,ump9620-adc
+ then:
+ properties:
+ nvmem-cells:
+ maxItems: 2
+ nvmem-cell-names:
+ items:
+ - const: big_scale_calib
+ - const: small_scale_calib
+
+ else:
+ properties:
+ nvmem-cells:
+ maxItems: 6
+ nvmem-cell-names:
+ items:
+ - const: big_scale_calib1
+ - const: big_scale_calib2
+ - const: small_scale_calib1
+ - const: small_scale_calib2
+ - const: vbat_det_cal1
+ - const: vbat_det_cal2
required:
- compatible
@@ -58,15 +85,19 @@ examples:
pmic {
#address-cells = <1>;
#size-cells = <0>;
- adc@480 {
- compatible = "sprd,sc2731-adc";
- reg = <0x480>;
- interrupt-parent = <&sc2731_pmic>;
+ adc@504 {
+ compatible = "sprd,ump9620-adc";
+ reg = <0x504>;
+ interrupt-parent = <&ump9620_pmic>;
interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
#io-channel-cells = <1>;
hwlocks = <&hwlock 4>;
- nvmem-cells = <&adc_big_scale>, <&adc_small_scale>;
- nvmem-cell-names = "big_scale_calib", "small_scale_calib";
+ nvmem-cells = <&adc_bcal1>, <&adc_bcal2>,
+ <&adc_scal1>, <&adc_scal2>,
+ <&vbat_det_cal1>, <&vbat_det_cal2>;
+ nvmem-cell-names = "big_scale_calib1", "big_scale_calib2",
+ "small_scale_calib1", "small_scale_calib2",
+ "vbat_det_cal1", "vbat_det_cal2";
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/st,spear600-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,spear600-adc.yaml
new file mode 100644
index 000000000000..dd9ec3038703
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/st,spear600-adc.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/st,spear600-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST SPEAr ADC device driver
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ Integrated ADC inside the ST SPEAr SoC, SPEAr600, supporting
+ 10-bit resolution. Datasheet can be found here:
+ https://www.st.com/resource/en/datasheet/spear600.pdf
+
+properties:
+ compatible:
+ enum:
+ - st,spear600-adc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ sampling-frequency:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 2500000
+ maximum: 20000000
+ description:
+ Default sampling frequency of the ADC in Hz.
+
+ vref-external:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1000
+ maximum: 2800
+ description:
+ External voltage reference in milli-volts. If omitted the internal voltage
+ reference will be used.
+
+ average-samples:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ default: 0
+ description:
+ Number of samples to generate an average value. If omitted, single data
+ conversion will be used.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - sampling-frequency
+
+additionalProperties: false
+
+examples:
+ - |
+ adc@d8200000 {
+ compatible = "st,spear600-adc";
+ reg = <0xd8200000 0x1000>;
+ interrupt-parent = <&vic1>;
+ interrupts = <6>;
+ sampling-frequency = <5000000>;
+ vref-external = <2500>; /* 2.5V VRef */
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml
index a58334c3bb76..c4c4575d3fa9 100644
--- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/adc/st,stm32-adc.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/adc/st,stm32-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 ADC bindings
+title: STMicroelectronics STM32 ADC
description: |
STM32 ADC is a successive approximation analog-to-digital converter.
@@ -19,7 +19,7 @@ description: |
Each STM32 ADC block can have up to 3 ADC instances.
maintainers:
- - Fabrice Gasnier <fabrice.gasnier@st.com>
+ - Fabrice Gasnier <fabrice.gasnier@foss.st.com>
properties:
compatible:
@@ -27,6 +27,7 @@ properties:
- st,stm32f4-adc-core
- st,stm32h7-adc-core
- st,stm32mp1-adc-core
+ - st,stm32mp13-adc-core
reg:
maxItems: 1
@@ -37,6 +38,7 @@ properties:
- stm32f4 and stm32h7 share a common ADC interrupt line.
- stm32mp1 has two separate interrupt lines, one for each ADC within
ADC block.
+ - stm32mp13 has an interrupt line per ADC block.
minItems: 1
maxItems: 2
@@ -52,7 +54,9 @@ properties:
It's not present on stm32f4.
It's required on stm32h7 and stm32mp1.
- clock-names: true
+ clock-names:
+ minItems: 1
+ maxItems: 2
st,max-clk-rate-hz:
description:
@@ -78,7 +82,7 @@ properties:
description:
Phandle to system configuration controller. It can be used to control the
analog circuitry on stm32mp1.
- $ref: "/schemas/types.yaml#/definitions/phandle-array"
+ $ref: /schemas/types.yaml#/definitions/phandle-array
interrupt-controller: true
@@ -91,6 +95,10 @@ properties:
'#size-cells':
const: 0
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
allOf:
- if:
properties:
@@ -138,7 +146,6 @@ allOf:
- const: bus
- const: adc
minItems: 1
- maxItems: 2
interrupts:
items:
@@ -170,7 +177,6 @@ allOf:
- const: bus
- const: adc
minItems: 1
- maxItems: 2
interrupts:
items:
@@ -182,6 +188,33 @@ allOf:
maximum: 36000000
default: 36000000
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: st,stm32mp13-adc-core
+
+ then:
+ properties:
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: bus
+ - const: adc
+ minItems: 1
+
+ interrupts:
+ items:
+ - description: ADC interrupt line
+
+ st,max-clk-rate-hz:
+ minimum: 150000
+ maximum: 75000000
+ default: 75000000
+
additionalProperties: false
required:
@@ -210,6 +243,7 @@ patternProperties:
- st,stm32f4-adc
- st,stm32h7-adc
- st,stm32mp1-adc
+ - st,stm32mp13-adc
reg:
description: |
@@ -222,10 +256,16 @@ patternProperties:
'#io-channel-cells':
const: 1
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
interrupts:
description: |
IRQ Line for the ADC instance. Valid values are:
- - 0 for adc@0
+ - 0 for adc@0 (single adc for stm32mp13)
- 1 for adc@100
- 2 for adc@200 (stm32f4 only)
maxItems: 1
@@ -246,16 +286,18 @@ patternProperties:
assigned-resolution-bits:
description: |
Resolution (bits) to use for conversions:
- - can be 6, 8, 10 or 12 on stm32f4
+ - can be 6, 8, 10 or 12 on stm32f4 and stm32mp13
- can be 8, 10, 12, 14 or 16 on stm32h7 and stm32mp1
st,adc-channels:
description: |
List of single-ended channels muxed for this ADC. It can have up to:
- 16 channels, numbered from 0 to 15 (for in0..in15) on stm32f4
+ - 19 channels, numbered from 0 to 18 (for in0..in18) on stm32mp13.
- 20 channels, numbered from 0 to 19 (for in0..in19) on stm32h7 and
stm32mp1.
$ref: /schemas/types.yaml#/definitions/uint32-array
+ deprecated: true
st,adc-diff-channels:
description: |
@@ -265,7 +307,9 @@ patternProperties:
<vinp vinn>, <vinp vinn>,... vinp and vinn are numbered from 0 to 19.
Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is
- required. Both properties can be used together. Some channels can be
+ required if no adc generic channel is defined. These legacy channel
+ properties are exclusive with adc generic channel bindings.
+ Both properties can be used together. Some channels can be
used as single-ended and some other ones as differential (mixed). But
channels can't be configured both as single-ended and differential.
$ref: /schemas/types.yaml#/definitions/uint32-matrix
@@ -279,6 +323,7 @@ patternProperties:
"vinn" indicates negative input number
minimum: 0
maximum: 19
+ deprecated: true
st,min-sample-time-nsecs:
description:
@@ -289,6 +334,50 @@ patternProperties:
list, to set sample time resp. for all channels, or independently for
each channel.
$ref: /schemas/types.yaml#/definitions/uint32-array
+ deprecated: true
+
+ nvmem-cells:
+ items:
+ - description: Phandle to the calibration vrefint data provided by otp
+
+ nvmem-cell-names:
+ items:
+ - const: vrefint
+
+ patternProperties:
+ "^channel@([0-9]|1[0-9])$":
+ type: object
+ $ref: adc.yaml
+ description: Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 19
+
+ label:
+ description: |
+ Unique name to identify which channel this is.
+ Reserved label names "vddcore", "vddcpu", "vddq_ddr", "vrefint" and "vbat"
+ are used to identify internal channels with matching names.
+
+ diff-channels:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ minimum: 0
+ maximum: 19
+
+ st,min-sample-time-ns:
+ description: |
+ Minimum sampling time in nanoseconds. Depending on hardware (board)
+ e.g. high/low analog input source impedance, fine tune of ADC
+ sampling time may be recommended.
+
+ required:
+ - reg
+
+ additionalProperties: false
allOf:
- if:
@@ -367,13 +456,37 @@ patternProperties:
items:
minimum: 40
- additionalProperties: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: st,stm32mp13-adc
+
+ then:
+ properties:
+ reg:
+ const: 0x0
- anyOf:
- - required:
- - st,adc-channels
- - required:
- - st,adc-diff-channels
+ interrupts:
+ const: 0
+
+ assigned-resolution-bits:
+ enum: [6, 8, 10, 12]
+ default: 12
+
+ st,adc-channels:
+ minItems: 1
+ maxItems: 19
+ items:
+ minimum: 0
+ maximum: 18
+
+ st,min-sample-time-nsecs:
+ minItems: 1
+ maxItems: 19
+ items:
+ minimum: 40
+ additionalProperties: false
required:
- compatible
@@ -384,7 +497,7 @@ patternProperties:
examples:
- |
// Example 1: with stm32f429, ADC1, single-ended channel 8
- adc123: adc@40012000 {
+ adc123: adc@40012000 {
compatible = "st,stm32f4-adc-core";
reg = <0x40012000 0x400>;
interrupts = <18>;
@@ -398,28 +511,28 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
adc@0 {
- compatible = "st,stm32f4-adc";
- #io-channel-cells = <1>;
- reg = <0x0>;
- clocks = <&rcc 0 168>;
- interrupt-parent = <&adc123>;
- interrupts = <0>;
- st,adc-channels = <8>;
- dmas = <&dma2 0 0 0x400 0x0>;
- dma-names = "rx";
- assigned-resolution-bits = <8>;
+ compatible = "st,stm32f4-adc";
+ #io-channel-cells = <1>;
+ reg = <0x0>;
+ clocks = <&rcc 0 168>;
+ interrupt-parent = <&adc123>;
+ interrupts = <0>;
+ st,adc-channels = <8>;
+ dmas = <&dma2 0 0 0x400 0x0>;
+ dma-names = "rx";
+ assigned-resolution-bits = <8>;
};
// ...
// other adc child nodes follow...
- };
+ };
- |
// Example 2: with stm32mp157c to setup ADC1 with:
// - channels 0 & 1 as single-ended
// - channels 2 & 3 as differential (with resp. 6 & 7 negative inputs)
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/stm32mp1-clks.h>
- adc12: adc@48003000 {
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stm32mp1-clks.h>
+ adc12: adc@48003000 {
compatible = "st,stm32mp1-adc-core";
reg = <0x48003000 0x400>;
interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
@@ -436,19 +549,65 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
adc@0 {
- compatible = "st,stm32mp1-adc";
- #io-channel-cells = <1>;
- reg = <0x0>;
- interrupt-parent = <&adc12>;
- interrupts = <0>;
- st,adc-channels = <0 1>;
- st,adc-diff-channels = <2 6>, <3 7>;
- st,min-sample-time-nsecs = <5000>;
- dmas = <&dmamux1 9 0x400 0x05>;
- dma-names = "rx";
+ compatible = "st,stm32mp1-adc";
+ #io-channel-cells = <1>;
+ reg = <0x0>;
+ interrupt-parent = <&adc12>;
+ interrupts = <0>;
+ st,adc-channels = <0 1>;
+ st,adc-diff-channels = <2 6>, <3 7>;
+ st,min-sample-time-nsecs = <5000>;
+ dmas = <&dmamux1 9 0x400 0x05>;
+ dma-names = "rx";
};
// ...
// other adc child node follow...
- };
+ };
+
+ - |
+ // Example 3: with stm32mp157c to setup ADC2 with:
+ // - internal channels 13, 14, 15.
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stm32mp1-clks.h>
+ adc122: adc@48003000 {
+ compatible = "st,stm32mp1-adc-core";
+ reg = <0x48003000 0x400>;
+ interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&rcc ADC12>, <&rcc ADC12_K>;
+ clock-names = "bus", "adc";
+ booster-supply = <&booster>;
+ vdd-supply = <&vdd>;
+ vdda-supply = <&vdda>;
+ vref-supply = <&vref>;
+ st,syscfg = <&syscfg>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adc@100 {
+ compatible = "st,stm32mp1-adc";
+ #io-channel-cells = <1>;
+ reg = <0x100>;
+ interrupts = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@13 {
+ reg = <13>;
+ label = "vrefint";
+ st,min-sample-time-ns = <9000>;
+ };
+ channel@14 {
+ reg = <14>;
+ label = "vddcore";
+ st,min-sample-time-ns = <9000>;
+ };
+ channel@15 {
+ reg = <15>;
+ label = "vbat";
+ st,min-sample-time-ns = <9000>;
+ };
+ };
+ };
...
diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml
index 733351dee252..c24ac98bbb3d 100644
--- a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml
@@ -7,8 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: STMicroelectronics STM32 DFSDM ADC device driver
maintainers:
- - Fabrice Gasnier <fabrice.gasnier@st.com>
- - Olivier Moysan <olivier.moysan@st.com>
+ - Fabrice Gasnier <fabrice.gasnier@foss.st.com>
+ - Olivier Moysan <olivier.moysan@foss.st.com>
description: |
STM32 DFSDM ADC is a sigma delta analog-to-digital converter dedicated to
@@ -59,6 +59,10 @@ properties:
If not, SPI CLKOUT frequency will not be accurate.
maximum: 20000000
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
required:
- compatible
- reg
@@ -72,6 +76,7 @@ additionalProperties: false
patternProperties:
"^filter@[0-9]+$":
type: object
+ unevaluatedProperties: false
description: child node
properties:
@@ -97,9 +102,11 @@ patternProperties:
items:
minimum: 0
maximum: 7
+ deprecated: true
st,adc-channel-names:
description: List of single-ended channel names.
+ deprecated: true
st,filter-order:
description: |
@@ -108,13 +115,17 @@ patternProperties:
- [1-5]: order 1 to 5.
For audio purpose it is recommended to use order 3 to 5.
$ref: /schemas/types.yaml#/definitions/uint32
- items:
- minimum: 0
- maximum: 5
+ maximum: 5
"#io-channel-cells":
const: 1
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
st,adc-channel-types:
description: |
Single-ended channel input type.
@@ -125,6 +136,7 @@ patternProperties:
items:
enum: [ SPI_R, SPI_F, MANCH_R, MANCH_F ]
$ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ deprecated: true
st,adc-channel-clk-src:
description: |
@@ -136,6 +148,7 @@ patternProperties:
items:
enum: [ CLKIN, CLKOUT, CLKOUT_F, CLKOUT_R ]
$ref: /schemas/types.yaml#/definitions/non-unique-string-array
+ deprecated: true
st,adc-alt-channel:
description:
@@ -144,6 +157,7 @@ patternProperties:
If not set, channel n is connected to SPI input n.
If set, channel n is connected to SPI input n + 1.
type: boolean
+ deprecated: true
st,filter0-sync:
description:
@@ -162,11 +176,60 @@ patternProperties:
- compatible
- reg
- interrupts
- - st,adc-channels
- - st,adc-channel-names
- st,filter-order
- "#io-channel-cells"
+ patternProperties:
+ "^channel@[0-7]$":
+ type: object
+ $ref: adc.yaml
+ unevaluatedProperties: false
+ description: Represents the external channels which are connected to the DFSDM.
+
+ properties:
+ reg:
+ maximum: 7
+
+ label:
+ description:
+ Unique name to identify which channel this is.
+
+ st,adc-channel-type:
+ description: |
+ Single-ended channel input type.
+ - "SPI_R": SPI with data on rising edge (default)
+ - "SPI_F": SPI with data on falling edge
+ - "MANCH_R": manchester codec, rising edge = logic 0, falling edge = logic 1
+ - "MANCH_F": manchester codec, rising edge = logic 1, falling edge = logic 0
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ SPI_R, SPI_F, MANCH_R, MANCH_F ]
+
+ st,adc-channel-clk-src:
+ description: |
+ Conversion clock source.
+ - "CLKIN": external SPI clock (CLKIN x)
+ - "CLKOUT": internal SPI clock (CLKOUT) (default)
+ - "CLKOUT_F": internal SPI clock divided by 2 (falling edge).
+ - "CLKOUT_R": internal SPI clock divided by 2 (rising edge).
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [ CLKIN, CLKOUT, CLKOUT_F, CLKOUT_R ]
+
+ st,adc-alt-channel:
+ description:
+ Must be defined if two sigma delta modulators are
+ connected on same SPI input.
+ If not set, channel n is connected to SPI input n.
+ If set, channel n is connected to SPI input n + 1.
+ type: boolean
+
+ io-backends:
+ description:
+ Used to pipe external sigma delta modulator or internal ADC backend to DFSDM channel.
+ maxItems: 1
+
+ required:
+ - reg
+
allOf:
- if:
properties:
@@ -174,7 +237,7 @@ patternProperties:
contains:
const: st,stm32-dfsdm-adc
- - then:
+ then:
properties:
st,adc-channels:
minItems: 1
@@ -196,9 +259,19 @@ patternProperties:
description:
From common IIO binding. Used to pipe external sigma delta
modulator or internal ADC output to DFSDM channel.
+ deprecated: true
- required:
- - io-channels
+ if:
+ required:
+ - st,adc-channels
+ then:
+ required:
+ - io-channels
+
+ patternProperties:
+ "^channel@[0-7]$":
+ required:
+ - io-backends
- if:
properties:
@@ -206,7 +279,7 @@ patternProperties:
contains:
const: st,stm32-dfsdm-dmic
- - then:
+ then:
properties:
st,adc-channels:
maxItems: 1
@@ -227,6 +300,7 @@ patternProperties:
patternProperties:
"^dfsdm-dai+$":
type: object
+ additionalProperties: false
description: child node
properties:
@@ -242,6 +316,10 @@ patternProperties:
From common IIO binding. Used to pipe external sigma delta
modulator or internal ADC output to DFSDM channel.
+ port:
+ $ref: /schemas/sound/audio-graph-port.yaml#
+ unevaluatedProperties: false
+
required:
- compatible
- "#sound-dai-cells"
@@ -254,7 +332,7 @@ allOf:
contains:
const: st,stm32h7-dfsdm
- - then:
+ then:
patternProperties:
"^filter@[0-9]+$":
properties:
@@ -269,7 +347,7 @@ allOf:
contains:
const: st,stm32mp1-dfsdm
- - then:
+ then:
patternProperties:
"^filter@[0-9]+$":
properties:
@@ -290,6 +368,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
+ // Example 1: Audio use case with generic binding
dfsdm0: filter@0 {
compatible = "st,stm32-dfsdm-dmic";
reg = <0>;
@@ -297,12 +376,18 @@ examples:
dmas = <&dmamux1 101 0x400 0x01>;
dma-names = "rx";
#io-channel-cells = <1>;
- st,adc-channels = <1>;
- st,adc-channel-names = "dmic0";
- st,adc-channel-types = "SPI_R";
- st,adc-channel-clk-src = "CLKOUT";
+ #address-cells = <1>;
+ #size-cells = <0>;
st,filter-order = <5>;
+ channel@1 {
+ reg = <1>;
+ label = "dmic0";
+ st,adc-channel-type = "SPI_R";
+ st,adc-channel-clk-src = "CLKOUT";
+ st,adc-alt-channel;
+ };
+
asoc_pdm0: dfsdm-dai {
compatible = "st,stm32h7-dfsdm-dai";
#sound-dai-cells = <0>;
@@ -310,19 +395,34 @@ examples:
};
};
- dfsdm_pdm1: filter@1 {
+ // Example 2: Analog use case with generic binding
+ dfsdm1: filter@1 {
compatible = "st,stm32-dfsdm-adc";
reg = <1>;
interrupts = <GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>;
dmas = <&dmamux1 102 0x400 0x01>;
dma-names = "rx";
- #io-channel-cells = <1>;
- st,adc-channels = <2 3>;
- st,adc-channel-names = "in2", "in3";
- st,adc-channel-types = "SPI_R", "SPI_R";
- st,adc-channel-clk-src = "CLKOUT_F", "CLKOUT_F";
- io-channels = <&sd_adc2 &sd_adc3>;
st,filter-order = <1>;
+ #io-channel-cells = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@2 {
+ reg = <2>;
+ label = "in2";
+ st,adc-channel-type = "SPI_F";
+ st,adc-channel-clk-src = "CLKOUT";
+ st,adc-alt-channel;
+ io-backends = <&sd_adc2>;
+ };
+
+ channel@3 {
+ reg = <3>;
+ label = "in3";
+ st,adc-channel-type = "SPI_R";
+ st,adc-channel-clk-src = "CLKOUT";
+ io-backends = <&sd_adc3>;
+ };
};
};
diff --git a/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml
index 9049c699152f..474e35c49348 100644
--- a/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/st,stmpe-adc.yaml
@@ -13,8 +13,7 @@ description:
This ADC forms part of an ST microelectronics STMPE multifunction device .
The ADC is shared with the STMPE touchscreen. As a result some ADC related
settings are specified in the parent node.
- The node name myst be stmpe_adc and should be a child node of the stmpe node
- to which it belongs.
+ The node should be a child node of the stmpe node to which it belongs.
properties:
compatible:
@@ -36,10 +35,8 @@ additionalProperties: false
examples:
- |
- stmpe {
- stmpe_adc {
- compatible = "st,stmpe-adc";
- st,norequest-mask = <0x0F>; /* dont use ADC CH3-0 */
- };
+ adc {
+ compatible = "st,stmpe-adc";
+ st,norequest-mask = <0x0f>; /* dont use ADC CH3-0 */
};
...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml
new file mode 100644
index 000000000000..caaad777580c
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc081c.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,adc081c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI Single-channel I2C ADCs
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+ - Lars-Peter Clausen <lars@metafoo.de>
+
+description: |
+ Single-channel ADC supporting 8, 10, or 12-bit samples and high/low alerts.
+
+properties:
+ compatible:
+ enum:
+ - ti,adc081c
+ - ti,adc101c
+ - ti,adc121c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vref-supply:
+ description:
+ Regulator for the combined power supply and voltage reference
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - vref-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@52 {
+ compatible = "ti,adc081c";
+ reg = <0x52>;
+ vref-supply = <&reg_2p5v>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc0832.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc0832.yaml
index f5a923cc847f..686721176a58 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,adc0832.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc0832.yaml
@@ -24,8 +24,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
vref-supply:
description: External reference, needed to establish input scaling
@@ -37,7 +35,10 @@ required:
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc084s021.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc084s021.yaml
index 1a113b30a414..726d2cbfa368 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,adc084s021.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc084s021.yaml
@@ -19,8 +19,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
vref-supply:
description: External reference, needed to establish input scaling
@@ -37,7 +35,10 @@ required:
- spi-cpol
- spi-cpha
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc108s102.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc108s102.yaml
index 54955f03df93..a60b1e100ee4 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,adc108s102.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc108s102.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Texas Instruments ADC108S102 and ADC128S102
maintainers:
- - Bogdan Pricop <bogdan.pricop@emutex.com>
+ - Jonathan Cameron <jic23@kernel.org>
description: |
Family of 8 channel, 10/12 bit, SPI, single ended ADCs.
@@ -19,7 +19,6 @@ properties:
reg: true
vref-supply: true
- spi-max-frequency: true
"#io-channel-cells":
const: 1
@@ -28,12 +27,15 @@ required:
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
spi {
- #address-cells= <1>;
+ #address-cells = <1>;
#size-cells = <0>;
adc@0 {
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc12138.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc12138.yaml
index ec3b2edf1fb7..076088a328c3 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,adc12138.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc12138.yaml
@@ -31,8 +31,6 @@ properties:
maxItems: 1
description: Conversion clock input.
- spi-max-frequency: true
-
vref-p-supply:
description: The regulator supply for positive analog voltage reference
@@ -62,7 +60,10 @@ required:
- clocks
- vref-p-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc128s052.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc128s052.yaml
index d54a0183f024..044b66a3b00c 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,adc128s052.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc128s052.yaml
@@ -27,8 +27,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
vref-supply: true
"#io-channel-cells":
@@ -39,11 +37,13 @@ required:
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/irq.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,adc161s626.yaml b/Documentation/devicetree/bindings/iio/adc/ti,adc161s626.yaml
index 3f4f334d6f73..afe782522904 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,adc161s626.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,adc161s626.yaml
@@ -21,8 +21,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
vdda-supply: true
"#io-channel-cells":
@@ -32,7 +30,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml
index 2c2d01bbc296..718f633c6e04 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/ti,ads1015.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: TI ADS1015 4 channel I2C analog to digital converter
+title: TI ADS1015/ADS1115 4 channel I2C analog to digital converter
maintainers:
- Daniel Baluta <daniel.baluta@nxp.com>
@@ -15,11 +15,18 @@ description: |
properties:
compatible:
- const: ti,ads1015
+ enum:
+ - ti,ads1015
+ - ti,ads1115
+ - ti,tla2021
+ - ti,tla2024
reg:
maxItems: 1
+ interrupts:
+ maxItems: 1
+
"#address-cells":
const: 1
@@ -40,6 +47,7 @@ additionalProperties: false
patternProperties:
"^channel@[0-7]+$":
type: object
+ additionalProperties: false
description:
Child nodes needed for each channel that the platform uses.
@@ -74,9 +82,9 @@ patternProperties:
ti,datarate:
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
- maximum: 6
+ maximum: 7
description: |
- Data acquisition rate in samples per second
+ Data acquisition rate in samples per second for ADS1015, TLA2024
0: 128
1: 250
2: 490
@@ -84,6 +92,17 @@ patternProperties:
4: 1600 (default)
5: 2400
6: 3300
+ 7: 3300
+
+ Data acquisition rate in samples per second for ADS1115
+ 0: 8
+ 1: 16
+ 2: 32
+ 3: 64
+ 4: 128 (default)
+ 5: 250
+ 6: 475
+ 7: 860
required:
- reg
@@ -100,12 +119,12 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
channel@0 {
- reg = <0>;
+ reg = <0>;
};
channel@4 {
- reg = <4>;
- ti,gain = <3>;
- ti,datarate = <5>;
+ reg = <4>;
+ ti,gain = <3>;
+ ti,datarate = <5>;
};
};
};
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1100.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1100.yaml
new file mode 100644
index 000000000000..970ccab15e1e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1100.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads1100.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI ADS1100/ADS1000 single channel I2C analog to digital converter
+
+maintainers:
+ - Mike Looijmans <mike.looijmans@topic.nl>
+
+description: |
+ Datasheet at: https://www.ti.com/lit/gpn/ads1100
+
+properties:
+ compatible:
+ enum:
+ - ti,ads1100
+ - ti,ads1000
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ "#io-channel-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@49 {
+ compatible = "ti,ads1100";
+ reg = <0x49>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1119.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1119.yaml
new file mode 100644
index 000000000000..ba6850ab1f90
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1119.yaml
@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads1119.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments ADS1119 ADC
+
+maintainers:
+ - João Paulo Gonçalves <jpaulo.silvagoncalves@gmail.com>
+
+description:
+ The TI ADS1119 is a precision 16-bit ADC over I2C that offers single-ended and
+ differential measurements using a multiplexed input. It features a programmable
+ gain, a programmable sample rate, an internal oscillator and voltage reference,
+ and a 50/60Hz rejection filter.
+
+properties:
+ compatible:
+ const: ti,ads1119
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ avdd-supply: true
+ dvdd-supply: true
+
+ vref-supply:
+ description:
+ ADC external reference voltage (VREF).
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+ - avdd-supply
+ - dvdd-supply
+
+patternProperties:
+ "^channel@([0-6])$":
+ $ref: adc.yaml
+ type: object
+ properties:
+ reg:
+ minimum: 0
+ maximum: 6
+
+ diff-channels:
+ description:
+ Differential input channels AIN0-AIN1, AIN2-AIN3 and AIN1-AIN2.
+ oneOf:
+ - items:
+ - const: 0
+ - const: 1
+ - items:
+ - const: 2
+ - const: 3
+ - items:
+ - const: 1
+ - const: 2
+
+ single-channel:
+ description:
+ Single-ended input channels AIN0, AIN1, AIN2 and AIN3.
+ minimum: 0
+ maximum: 3
+
+ oneOf:
+ - required:
+ - diff-channels
+ - required:
+ - single-channel
+
+ required:
+ - reg
+
+ unevaluatedProperties: false
+
+additionalProperties: false
+
+examples:
+ - |
+
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@40 {
+ compatible = "ti,ads1119";
+ reg = <0x40>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&reg_avdd_ads1119>;
+ dvdd-supply = <&reg_dvdd_ads1119>;
+ vref-supply = <&reg_vref_ads1119>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #io-channel-cells = <1>;
+
+ channel@0 {
+ reg = <0>;
+ single-channel = <0>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ diff-channels = <0 1>;
+ };
+
+ channel@2 {
+ reg = <2>;
+ single-channel = <3>;
+ };
+
+ channel@3 {
+ reg = <3>;
+ single-channel = <1>;
+ };
+
+ channel@4 {
+ reg = <4>;
+ single-channel = <2>;
+ };
+
+ channel@5 {
+ reg = <5>;
+ diff-channels = <1 2>;
+ };
+
+ channel@6 {
+ reg = <6>;
+ diff-channels = <2 3>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads124s08.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads124s08.yaml
index 9f5e96439c01..56a3f1766aab 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,ads124s08.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads124s08.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Texas Instruments' ads124s08 and ads124s06 ADC chip
maintainers:
- - Dan Murphy <dmurphy@ti.com>
+ - Andrew Davis <afd@ti.com>
properties:
compatible:
@@ -18,8 +18,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
spi-cpha: true
reset-gpios:
@@ -32,7 +30,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml
new file mode 100644
index 000000000000..71f9f9b745cb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads1298.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments' ads1298 medical ADC chips
+
+description: |
+ Datasheet at: https://www.ti.com/product/ADS1298
+ Bindings for this chip aren't complete.
+
+maintainers:
+ - Mike Looijmans <mike.looijmans@topic.nl>
+
+properties:
+ compatible:
+ enum:
+ - ti,ads1298
+
+ reg:
+ maxItems: 1
+
+ spi-cpha: true
+
+ reset-gpios:
+ maxItems: 1
+
+ avdd-supply:
+ description:
+ Analog power supply, voltage between AVDD and AVSS. When providing a
+ symmetric +/- 2.5V, the regulator should report 5V.
+
+ vref-supply:
+ description:
+ Optional reference voltage. If omitted, internal reference is used,
+ which is 2.4V when analog supply is below 4.4V, 4V otherwise.
+
+ clocks:
+ description: Optional 2.048 MHz external source clock on CLK pin
+ maxItems: 1
+
+ interrupts:
+ description: Interrupt on DRDY pin, triggers on falling edge
+ maxItems: 1
+
+ label: true
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - interrupts
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@1 {
+ reg = <1>;
+ compatible = "ti,ads1298";
+ label = "ads1298-1-ecg";
+ avdd-supply = <&reg_iso_5v_a>;
+ clocks = <&clk_ads1298>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <78 IRQ_TYPE_EDGE_FALLING>;
+ spi-max-frequency = <20000000>;
+ spi-cpha;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml
index e0670e3fbb72..890f125d422c 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Texas Instruments ADS131E0x 4-, 6- and 8-Channel ADCs
maintainers:
- - Tomislav Denis <tomislav.denis@avl.com>
+ - Jonathan Cameron <jic23@kernel.org>
description: |
The ADS131E0x are a family of multichannel, simultaneous sampling,
@@ -28,8 +28,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
spi-cpha: true
clocks:
@@ -79,7 +77,7 @@ required:
patternProperties:
"^channel@([0-7])$":
- $ref: "adc.yaml"
+ $ref: adc.yaml
type: object
description: |
Represents the external channels which are connected to the ADC.
@@ -120,7 +118,10 @@ patternProperties:
additionalProperties: false
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7138.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7138.yaml
new file mode 100644
index 000000000000..a51893e207d4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7138.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads7138.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments ADS7128/ADS7138 analog-to-digital converter (ADC)
+
+maintainers:
+ - Tobias Sperling <tobias.sperling@softing.com>
+
+description: |
+ The ADS7128 and ADS7138 chips are 12-bit, 8 channel analog-to-digital
+ converters (ADC) with build-in digital window comparator (DWC), using the
+ I2C interface.
+ ADS7128 differs in the addition of further hardware features, like a
+ root-mean-square (RMS) and a zero-crossing-detect (ZCD) module.
+
+ Datasheets:
+ https://www.ti.com/product/ADS7128
+ https://www.ti.com/product/ADS7138
+
+properties:
+ compatible:
+ enum:
+ - ti,ads7128
+ - ti,ads7138
+
+ reg:
+ maxItems: 1
+
+ avdd-supply:
+ description:
+ The regulator used as analog supply voltage as well as reference voltage.
+
+ interrupts:
+ description:
+ Interrupt on ALERT pin, triggers on low level.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@10 {
+ compatible = "ti,ads7138";
+ reg = <0x10>;
+ avdd-supply = <&reg_stb_3v3>;
+ interrupt-parent = <&gpio2>;
+ interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml
new file mode 100644
index 000000000000..0d8d06afed8b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads7924.yaml
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,ads7924.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI ADS7924 4 channels 12 bits I2C analog to digital converter
+
+maintainers:
+ - Hugo Villeneuve <hvilleneuve@dimonoff.com>
+
+description: |
+ Texas Instruments ADS7924 4 channels 12 bits I2C analog to digital converter
+
+ Specifications:
+ https://www.ti.com/lit/gpn/ads7924
+
+properties:
+ compatible:
+ const: ti,ads7924
+
+ reg:
+ maxItems: 1
+
+ vref-supply:
+ description:
+ The regulator supply for the ADC reference voltage (AVDD)
+
+ reset-gpios:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ "#io-channel-cells":
+ const: 1
+
+patternProperties:
+ "^channel@[0-3]+$":
+ $ref: adc.yaml
+
+ description: |
+ Represents the external channels which are connected to the ADC.
+
+ properties:
+ reg:
+ description: |
+ The channel number. It can have up to 4 channels numbered from 0 to 3.
+ items:
+ - minimum: 0
+ maximum: 3
+
+ label: true
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - vref-supply
+ - "#address-cells"
+ - "#size-cells"
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@48 {
+ compatible = "ti,ads7924";
+ reg = <0x48>;
+ vref-supply = <&ads7924_reg>;
+ reset-gpios = <&gpio 5 GPIO_ACTIVE_LOW>;
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@0 {
+ reg = <0>;
+ label = "CH0";
+ };
+ channel@1 {
+ reg = <1>;
+ label = "CH1";
+ };
+ channel@2 {
+ reg = <2>;
+ label = "CH2";
+ };
+ channel@3 {
+ reg = <3>;
+ label = "CH3";
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads8344.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads8344.yaml
index b8c398187d5c..f75b2c702986 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,ads8344.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads8344.yaml
@@ -19,8 +19,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
vref-supply:
description: Supply the 2.5V or 5V reference voltage
@@ -32,7 +30,10 @@ required:
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml
index a0af4b24877f..f26fdbc15f84 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml
@@ -25,13 +25,14 @@ properties:
description: Optional external reference. If not supplied, assume
REFSEL input tied low to enable the internal reference.
- spi-max-frequency: true
-
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,am3359-adc.yaml b/Documentation/devicetree/bindings/iio/adc/ti,am3359-adc.yaml
new file mode 100644
index 000000000000..b32be24a9f98
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,am3359-adc.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,am3359-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI AM3359 ADC
+
+maintainers:
+ - Miquel Raynal <miquel.raynal@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - ti,am3359-adc
+ - ti,am4372-adc
+ - items:
+ - enum:
+ - ti,am654-adc
+ - const: ti,am3359-adc
+
+ '#io-channel-cells':
+ const: 1
+
+ ti,adc-channels:
+ description: List of analog inputs available for ADC. AIN0 = 0, AIN1 = 1 and
+ so on until AIN7 = 7.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+
+ ti,chan-step-opendelay:
+ description: List of open delays for each channel of ADC in the order of
+ ti,adc-channels. The value corresponds to the number of ADC clock cycles
+ to wait after applying the step configuration registers and before sending
+ the start of ADC conversion. Maximum value is 0x3FFFF.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+
+ ti,chan-step-sampledelay:
+ description: List of sample delays for each channel of ADC in the order of
+ ti,adc-channels. The value corresponds to the number of ADC clock cycles
+ to sample (to hold start of conversion high). Maximum value is 0xFF.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+
+ ti,chan-step-avg:
+ description: Number of averages to be performed for each channel of ADC. If
+ average is 16 (this is also the maximum) then input is sampled 16 times
+ and averaged to get more accurate value. This increases the time taken by
+ ADC to generate a sample. Maximum value is 16.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+
+required:
+ - compatible
+ - '#io-channel-cells'
+ - ti,adc-channels
+
+additionalProperties: false
+
+examples:
+ - |
+ adc {
+ compatible = "ti,am3359-adc";
+ #io-channel-cells = <1>;
+ ti,adc-channels = <4 5 6 7>;
+ ti,chan-step-opendelay = <0x098 0x3ffff 0x098 0x0>;
+ ti,chan-step-sampledelay = <0xff 0x0 0xf 0x0>;
+ ti,chan-step-avg = <16 2 4 8>;
+ };
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml b/Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml
new file mode 100644
index 000000000000..5fb65bf7749d
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,lmp92064.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,lmp92064.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments LMP92064 Precision Current and Voltage Sensor.
+
+maintainers:
+ - Leonard Göhrs <l.goehrs@pengutronix.de>
+
+description: |
+ The LMP92064 is a two channel ADC intended for combined voltage and current
+ measurements.
+
+ The device contains two ADCs to allow simultaneous sampling of voltage and
+ current and thus of instantaneous power consumption.
+
+properties:
+ compatible:
+ enum:
+ - ti,lmp92064
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: Regulator that provides power to the main part of the chip
+
+ vdig-supply:
+ description: |
+ Regulator that provides power to the digital I/O part of the chip
+
+ shunt-resistor-micro-ohms:
+ description: |
+ Value of the shunt resistor (in µΩ) connected between INCP and INCN,
+ across which current is measured. Used to provide correct scaling of the
+ raw ADC measurement.
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - shunt-resistor-micro-ohms
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adc@0 {
+ compatible = "ti,lmp92064";
+ reg = <0>;
+ vdd-supply = <&vdd>;
+ vdig-supply = <&vdd>;
+ spi-max-frequency = <20000000>;
+ shunt-resistor-micro-ohms = <15000>;
+ reset-gpios = <&gpio1 16 GPIO_ACTIVE_HIGH>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,palmas-gpadc.yaml b/Documentation/devicetree/bindings/iio/adc/ti,palmas-gpadc.yaml
index 7b895784e008..f94057d8f605 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,palmas-gpadc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,palmas-gpadc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/ti,palmas-gpadc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Palmas general purpose ADC IP block devicetree bindings
+title: Palmas general purpose ADC IP block
maintainers:
- Tony Lindgren <tony@atomide.com>
@@ -67,19 +67,4 @@ required:
- compatible
- "#io-channel-cells"
-examples:
- - |
- #include <dt-bindings/clock/mt8183-clk.h>
- pmic {
- compatible = "ti,twl6035-pmic", "ti,palmas-pmic";
- adc {
- compatible = "ti,palmas-gpadc";
- interrupts = <18 0
- 16 0
- 17 0>;
- #io-channel-cells = <1>;
- ti,channel0-current-microamp = <5>;
- ti,channel3-current-microamp = <10>;
- };
- };
...
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,tlc4541.yaml b/Documentation/devicetree/bindings/iio/adc/ti,tlc4541.yaml
index 6c2539b3d707..314d1d99bf73 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,tlc4541.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,tlc4541.yaml
@@ -21,8 +21,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
vref-supply: true
"#io-channel-cells":
@@ -33,7 +31,10 @@ required:
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml b/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml
index 601d69971d84..866a05c9db36 100644
--- a/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/ti,tsc2046.yaml
@@ -23,7 +23,8 @@ properties:
interrupts:
maxItems: 1
- spi-max-frequency: true
+ vref-supply:
+ description: Optional supply of the reference voltage
"#io-channel-cells":
const: 1
@@ -40,7 +41,7 @@ required:
patternProperties:
"^channel@[0-7]$":
- $ref: "adc.yaml"
+ $ref: adc.yaml
type: object
properties:
@@ -59,7 +60,10 @@ patternProperties:
additionalProperties: false
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -79,36 +83,36 @@ examples:
#size-cells = <0>;
channel@0 {
- reg = <0>;
+ reg = <0>;
};
channel@1 {
- reg = <1>;
- settling-time-us = <700>;
- oversampling-ratio = <5>;
+ reg = <1>;
+ settling-time-us = <700>;
+ oversampling-ratio = <5>;
};
channel@2 {
- reg = <2>;
+ reg = <2>;
};
channel@3 {
- reg = <3>;
- settling-time-us = <700>;
- oversampling-ratio = <5>;
+ reg = <3>;
+ settling-time-us = <700>;
+ oversampling-ratio = <5>;
};
channel@4 {
- reg = <4>;
- settling-time-us = <700>;
- oversampling-ratio = <5>;
+ reg = <4>;
+ settling-time-us = <700>;
+ oversampling-ratio = <5>;
};
channel@5 {
- reg = <5>;
- settling-time-us = <700>;
- oversampling-ratio = <5>;
+ reg = <5>;
+ settling-time-us = <700>;
+ oversampling-ratio = <5>;
};
channel@6 {
- reg = <6>;
+ reg = <6>;
};
channel@7 {
- reg = <7>;
+ reg = <7>;
};
};
};
diff --git a/Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml b/Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml
new file mode 100644
index 000000000000..e779a8986e0b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/ti,twl6030-gpadc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPADC subsystem in the TWL6030 power module
+
+maintainers:
+ - Andreas Kemnade <andreas@kemnade.info>
+
+description:
+ The GPADC subsystem in the TWL603X consists of a 10-bit ADC
+ combined with a 15-input analog multiplexer in the TWL6030 resp. a
+ 19-input analog muliplexer in the TWL6032.
+
+properties:
+ compatible:
+ enum:
+ - ti,twl6030-gpadc
+ - ti,twl6032-gpadc
+
+ interrupts:
+ maxItems: 1
+
+ "#io-channel-cells":
+ const: 1
+
+required:
+ - compatible
+ - interrupts
+ - "#io-channel-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ gpadc {
+ compatible = "ti,twl6030-gpadc";
+ interrupts = <3>;
+ #io-channel-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml b/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml
index e759a5da708d..de91cb03fdc6 100644
--- a/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/x-powers,axp209-adc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/adc/x-powers,axp209-adc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: X-Powers AXP ADC bindings
+title: X-Powers AXP ADC
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -27,6 +27,7 @@ description: |
8 | batt_v
9 | batt_chrg_i
10 | batt_dischrg_i
+ 11 | ts_v
AXP22x
------
@@ -34,6 +35,18 @@ description: |
1 | batt_v
2 | batt_chrg_i
3 | batt_dischrg_i
+ 4 | ts_v
+
+ AXP717
+ ------
+ 0 | batt_v
+ 1 | ts_v
+ 2 | vbus_v
+ 3 | vsys_v
+ 4 | pmic_temp
+ 5 | batt_chrg_i
+ 6 | vmid_v
+ 7 | bkup_batt_v
AXP813
------
@@ -42,13 +55,14 @@ description: |
2 | batt_v
3 | batt_chrg_i
4 | batt_dischrg_i
-
+ 5 | ts_v
properties:
compatible:
oneOf:
- const: x-powers,axp209-adc
- const: x-powers,axp221-adc
+ - const: x-powers,axp717-adc
- const: x-powers,axp813-adc
- items:
diff --git a/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml b/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml
new file mode 100644
index 000000000000..3ae1a0bab38f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/xlnx,zynqmp-ams.yaml
@@ -0,0 +1,236 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/xlnx,zynqmp-ams.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx Zynq Ultrascale AMS controller
+
+maintainers:
+ - Salih Erim <salih.erim@amd.com>
+ - Conall O'Griofa <conall.ogriofa@amd.com>
+
+description: |
+ The AMS (Analog Monitoring System) includes an ADC as well as on-chip sensors
+ that can be used to sample external voltages and monitor on-die operating
+ conditions, such as temperature and supply voltage levels.
+ The AMS has two SYSMON blocks which are PL (Programmable Logic) SYSMON and
+ PS (Processing System) SYSMON.
+ All designs should have AMS registers, but PS and PL are optional. The
+ AMS controller can work with only PS, only PL and both PS and PL
+ configurations. Please specify registers according to your design. Devicetree
+ should always have AMS module property. Providing PS & PL module is optional.
+
+ AMS Channel Details
+ ```````````````````
+ Sysmon Block |Channel| Details |Measurement
+ |Number | |Type
+ ---------------------------------------------------------------------------------------------------------
+ AMS CTRL |0 |System PLLs voltage measurement, VCC_PSPLL. |Voltage
+ |1 |Battery voltage measurement, VCC_PSBATT. |Voltage
+ |2 |PL Internal voltage measurement, VCCINT. |Voltage
+ |3 |Block RAM voltage measurement, VCCBRAM. |Voltage
+ |4 |PL Aux voltage measurement, VCCAUX. |Voltage
+ |5 |Voltage measurement for six DDR I/O PLLs, VCC_PSDDR_PLL. |Voltage
+ |6 |VCC_PSINTFP_DDR voltage measurement. |Voltage
+ ---------------------------------------------------------------------------------------------------------
+ PS Sysmon |7 |LPD temperature measurement. |Temperature
+ |8 |FPD temperature measurement (REMOTE). |Temperature
+ |9 |VCC PS LPD voltage measurement (supply1). |Voltage
+ |10 |VCC PS FPD voltage measurement (supply2). |Voltage
+ |11 |PS Aux voltage reference (supply3). |Voltage
+ |12 |DDR I/O VCC voltage measurement. |Voltage
+ |13 |PS IO Bank 503 voltage measurement (supply5). |Voltage
+ |14 |PS IO Bank 500 voltage measurement (supply6). |Voltage
+ |15 |VCCO_PSIO1 voltage measurement. |Voltage
+ |16 |VCCO_PSIO2 voltage measurement. |Voltage
+ |17 |VCC_PS_GTR voltage measurement (VPS_MGTRAVCC). |Voltage
+ |18 |VTT_PS_GTR voltage measurement (VPS_MGTRAVTT). |Voltage
+ |19 |VCC_PSADC voltage measurement. |Voltage
+ ---------------------------------------------------------------------------------------------------------
+ PL Sysmon |20 |PL temperature measurement. |Temperature
+ |21 |PL Internal voltage measurement, VCCINT. |Voltage
+ |22 |PL Auxiliary voltage measurement, VCCAUX. |Voltage
+ |23 |ADC Reference P+ voltage measurement. |Voltage
+ |24 |ADC Reference N- voltage measurement. |Voltage
+ |25 |PL Block RAM voltage measurement, VCCBRAM. |Voltage
+ |26 |LPD Internal voltage measurement, VCC_PSINTLP (supply4). |Voltage
+ |27 |FPD Internal voltage measurement, VCC_PSINTFP (supply5). |Voltage
+ |28 |PS Auxiliary voltage measurement (supply6). |Voltage
+ |29 |PL VCCADC voltage measurement (vccams). |Voltage
+ |30 |Differential analog input signal voltage measurement. |Voltage
+ |31 |VUser0 voltage measurement (supply7). |Voltage
+ |32 |VUser1 voltage measurement (supply8). |Voltage
+ |33 |VUser2 voltage measurement (supply9). |Voltage
+ |34 |VUser3 voltage measurement (supply10). |Voltage
+ |35 |Auxiliary ch 0 voltage measurement (VAux0). |Voltage
+ |36 |Auxiliary ch 1 voltage measurement (VAux1). |Voltage
+ |37 |Auxiliary ch 2 voltage measurement (VAux2). |Voltage
+ |38 |Auxiliary ch 3 voltage measurement (VAux3). |Voltage
+ |39 |Auxiliary ch 4 voltage measurement (VAux4). |Voltage
+ |40 |Auxiliary ch 5 voltage measurement (VAux5). |Voltage
+ |41 |Auxiliary ch 6 voltage measurement (VAux6). |Voltage
+ |42 |Auxiliary ch 7 voltage measurement (VAux7). |Voltage
+ |43 |Auxiliary ch 8 voltage measurement (VAux8). |Voltage
+ |44 |Auxiliary ch 9 voltage measurement (VAux9). |Voltage
+ |45 |Auxiliary ch 10 voltage measurement (VAux10). |Voltage
+ |46 |Auxiliary ch 11 voltage measurement (VAux11). |Voltage
+ |47 |Auxiliary ch 12 voltage measurement (VAux12). |Voltage
+ |48 |Auxiliary ch 13 voltage measurement (VAux13). |Voltage
+ |49 |Auxiliary ch 14 voltage measurement (VAux14). |Voltage
+ |50 |Auxiliary ch 15 voltage measurement (VAux15). |Voltage
+ --------------------------------------------------------------------------------------------------------
+
+properties:
+ compatible:
+ enum:
+ - xlnx,zynqmp-ams
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ description: AMS Controller register space
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: AMS reference clock
+
+ ranges:
+ description:
+ Maps the child address space for PS and/or PL.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ '#io-channel-cells':
+ const: 1
+
+ ams-ps@0:
+ type: object
+ description: |
+ PS (Processing System) SYSMON is memory mapped to PS. This block has
+ built-in alarm generation logic that is used to interrupt the processor
+ based on condition set.
+
+ properties:
+ compatible:
+ enum:
+ - xlnx,zynqmp-ams-ps
+
+ reg:
+ description: Register Space for PS-SYSMON
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+
+ additionalProperties: false
+
+ ams-pl@400:
+ type: object
+ additionalProperties: false
+ description:
+ PL-SYSMON is capable of monitoring off chip voltage and temperature.
+ PL-SYSMON block has DRP, JTAG and I2C interface to enable monitoring
+ from external master. Out of this interface currently only DRP is
+ supported. This block has alarm generation logic that is used to
+ interrupt the processor based on condition set.
+
+ properties:
+ compatible:
+ items:
+ - enum:
+ - xlnx,zynqmp-ams-pl
+
+ reg:
+ description: Register Space for PL-SYSMON.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ patternProperties:
+ "^channel@([2-4][0-9]|50)$":
+ type: object
+ description:
+ Describes the external channels connected.
+
+ properties:
+ reg:
+ description:
+ Pair of pins the channel is connected to. This value is
+ same as Channel Number for a particular channel.
+ minimum: 20
+ maximum: 50
+
+ xlnx,bipolar:
+ $ref: /schemas/types.yaml#/definitions/flag
+ type: boolean
+ description:
+ If the set channel is used in bipolar mode.
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - ranges
+
+additionalProperties: false
+
+examples:
+ - |
+
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ xilinx_ams: ams@ffa50000 {
+ compatible = "xlnx,zynqmp-ams";
+ interrupt-parent = <&gic>;
+ interrupts = <0 56 4>;
+ reg = <0x0 0xffa50000 0x0 0x800>;
+ clocks = <&zynqmp_clk 70>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ #io-channel-cells = <1>;
+ ranges = <0 0 0xffa50800 0x800>;
+
+ ams_ps: ams-ps@0 {
+ compatible = "xlnx,zynqmp-ams-ps";
+ reg = <0 0x400>;
+ };
+
+ ams_pl: ams-pl@400 {
+ compatible = "xlnx,zynqmp-ams-pl";
+ reg = <0x400 0x400>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@30 {
+ reg = <30>;
+ xlnx,bipolar;
+ };
+ channel@31 {
+ reg = <31>;
+ };
+ channel@38 {
+ reg = <38>;
+ xlnx,bipolar;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml b/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml
new file mode 100644
index 000000000000..2a04906531fb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml
@@ -0,0 +1,371 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/addac/adi,ad74115.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD74115H device
+
+maintainers:
+ - Cosmin Tanislav <cosmin.tanislav@analog.com>
+
+description: |
+ The AD74115H is a single-channel software configurable input/output
+ device for industrial control applications. It contains functionality for
+ analog output, analog input, digital output, digital input, resistance
+ temperature detector, and thermocouple measurements integrated into a single
+ chip solution with an SPI interface. The device features a 16-bit ADC and a
+ 14-bit DAC.
+
+ https://www.analog.com/en/products/ad74115h.html
+
+properties:
+ compatible:
+ enum:
+ - adi,ad74115h
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 24000000
+
+ spi-cpol: true
+
+ reset-gpios:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - adc_rdy
+ - alert
+
+ avdd-supply: true
+ avcc-supply: true
+ dvcc-supply: true
+ dovdd-supply: true
+ refin-supply: true
+
+ adi,ch-func:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Channel function.
+ 0 - High impedance
+ 1 - Voltage output
+ 2 - Current output
+ 3 - Voltage input
+ 4 - Current input, externally-powered
+ 5 - Current input, loop-powered
+ 6 - Resistance input
+ 7 - RTD measure
+ 8 - Digital input logic
+ 9 - Digital input, loop-powered
+ 10 - Current output with HART
+ 11 - Current input, externally-powered, with HART
+ 12 - Current input, loop-powered, with HART
+ minimum: 0
+ maximum: 12
+ default: 0
+
+ adi,conv2-mux:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Input node for ADC conversion 2.
+ 0 - SENSE_EXT1 to AGND_SENSE
+ 1 - SENSE_EXT2 to AGND_SENSE
+ 2 - SENSE_EXT2 to SENSE_EXT1
+ 3 - AGND to AGND
+ minimum: 0
+ maximum: 3
+ default: 0
+
+ adi,conv2-range-microvolt:
+ description: Conversion range for ADC conversion 2.
+ oneOf:
+ - items:
+ - enum: [-2500000, 0]
+ - const: 2500000
+ - items:
+ - enum: [-12000000, 0]
+ - const: 12000000
+ - items:
+ - const: -2500000
+ - const: 0
+ - items:
+ - const: -104000
+ - const: 104000
+ - items:
+ - const: 0
+ - const: 625000
+
+ adi,sense-agnd-buffer-low-power:
+ type: boolean
+ description:
+ Whether to enable low-power buffered mode for the AGND sense pin.
+
+ adi,lf-buffer-low-power:
+ type: boolean
+ description:
+ Whether to enable low-power buffered mode for the low-side filtered
+ sense pin.
+
+ adi,hf-buffer-low-power:
+ type: boolean
+ description:
+ Whether to enable low-power buffered mode for the high-side filtered
+ sense pin.
+
+ adi,ext2-buffer-low-power:
+ type: boolean
+ description: Whether to enable low-power buffered mode for the EXT2 pin.
+
+ adi,ext1-buffer-low-power:
+ type: boolean
+ description: Whether to enable low-power buffered mode for the EXT1 pin.
+
+ adi,comparator-invert:
+ type: boolean
+ description: Whether to invert the comparator output.
+
+ adi,digital-input-sink-range-high:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ When not present, the digital input range is from 0 to 3700uA in steps
+ of 120uA, with a ~2k series resistance.
+ When present, the digital input range is from 0 to 7400uA in steps
+ of 240uA, with a ~1k series resistance.
+
+ adi,digital-input-sink-microamp:
+ description: Sink current in digital input mode.
+ minimum: 0
+ maximum: 3700
+ default: 0
+
+ adi,digital-input-debounce-mode-counter-reset:
+ type: boolean
+ description: |
+ When not present, a counter increments when the signal is asserted
+ and decrements when the signal is de-asserted.
+ When present, a counter increments while the signal is asserted and
+ resets when the signal de-asserts
+
+ adi,digital-input-unbuffered:
+ type: boolean
+ description: Whether to buffer digital input signals.
+
+ adi,digital-input-short-circuit-detection:
+ type: boolean
+ description: Whether to detect digital input short circuits.
+
+ adi,digital-input-open-circuit-detection:
+ type: boolean
+ description: Whether to detect digital input open circuits.
+
+ adi,digital-input-threshold-mode-fixed:
+ type: boolean
+ description: |
+ When not present, the digital input threshold range is -0.96 * AVDD
+ to AVDD.
+ When present, the threshold range is fixed from -19V to 30V.
+
+ adi,dac-bipolar:
+ type: boolean
+ description: |
+ When not present, the DAC operates in the 0V to 12V range.
+ When present, the DAC operates in the -12V to 12V range.
+
+ adi,charge-pump:
+ type: boolean
+ description: Whether to enable the internal charge pump.
+
+ adi,dac-hart-slew:
+ type: boolean
+ description: Whether to use a HART-compatible slew rate.
+
+ adi,dac-current-limit-low:
+ type: boolean
+ description: |
+ When not present, the DAC short-circuit current limit is 32mA in
+ either source or sink for VOUT and 4mA sink for IOUT.
+ When present, the limit is 16mA in either source or sink for VOUT,
+ 1mA sink for IOUT.
+
+ adi,4-wire-rtd:
+ type: boolean
+ description: |
+ When not present, the ADC should be used for measuring 3-wire RTDs.
+ When present, the ADC should be used for measuring 4-wire RTDs.
+
+ adi,3-wire-rtd-excitation-swap:
+ type: boolean
+ description: Whether to swap the excitation for 3-wire RTD.
+
+ adi,rtd-excitation-current-microamp:
+ description: Excitation current to apply to RTD.
+ enum: [250, 500, 750, 1000]
+ default: 250
+
+ adi,ext1-burnout:
+ type: boolean
+ description: Whether to enable burnout current for EXT1.
+
+ adi,ext1-burnout-current-nanoamp:
+ description:
+ Burnout current in nanoamps to be applied to EXT1.
+ enum: [0, 50, 500, 1000, 10000]
+ default: 0
+
+ adi,ext1-burnout-current-polarity-sourcing:
+ type: boolean
+ description: |
+ When not present, the burnout current polarity for EXT1 is sinking.
+ When present, the burnout current polarity for EXT1 is sourcing.
+
+ adi,ext2-burnout:
+ type: boolean
+ description: Whether to enable burnout current for EXT2.
+
+ adi,ext2-burnout-current-nanoamp:
+ description: Burnout current in nanoamps to be applied to EXT2.
+ enum: [0, 50, 500, 1000, 10000]
+ default: 0
+
+ adi,ext2-burnout-current-polarity-sourcing:
+ type: boolean
+ description: |
+ When not present, the burnout current polarity for EXT2 is sinking.
+ When present, the burnout current polarity for EXT2 is sourcing.
+
+ adi,viout-burnout:
+ type: boolean
+ description: Whether to enable burnout current for VIOUT.
+
+ adi,viout-burnout-current-nanoamp:
+ description: Burnout current in nanoamps to be applied to VIOUT.
+ enum: [0, 1000, 10000]
+ default: 0
+
+ adi,viout-burnout-current-polarity-sourcing:
+ type: boolean
+ description: |
+ When not present, the burnout current polarity for VIOUT is sinking.
+ When present, the burnout current polarity for VIOUT is sourcing.
+
+ adi,gpio0-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ GPIO functions.
+ 0 - Disabled
+ 1 - Logic I/O
+ 2 - Comparator output
+ 3 - Control HART CD
+ 4 - Monitor HART CD
+ 5 - Monitor HART EOM status
+ minimum: 0
+ maximum: 5
+ default: 0
+
+ adi,gpio1-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ GPIO functions.
+ 0 - Disabled
+ 1 - Logic I/O
+ 2 - Drive external digital output FET
+ 3 - Control HART RXD
+ 4 - Monitor HART RXD
+ 5 - Monitor HART SOM status
+ minimum: 0
+ maximum: 5
+ default: 0
+
+ adi,gpio2-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ GPIO functions.
+ 0 - Disabled
+ 1 - Logic I/O
+ 2 - Drive internal digital output FET
+ 3 - Control HART TXD
+ 4 - Monitor HART TXD
+ 5 - Monitor HART TX complete status
+ minimum: 0
+ maximum: 5
+ default: 0
+
+ adi,gpio3-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ GPIO functions.
+ 0 - Disabled
+ 1 - Logic I/O
+ 2 - High impedance
+ 3 - Control HART RTS
+ 4 - Monitor HART RTS
+ 5 - Monitor HART CD complete status
+ minimum: 0
+ maximum: 5
+ default: 0
+
+required:
+ - compatible
+ - reg
+ - spi-cpol
+ - avdd-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ required:
+ - adi,digital-input-sink-range-high
+ then:
+ properties:
+ adi,digital-input-sink-microamp:
+ maximum: 7400
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ addac@0 {
+ compatible = "adi,ad74115h";
+ reg = <0>;
+
+ spi-max-frequency = <12000000>;
+ spi-cpol;
+
+ reset-gpios = <&gpio 27 GPIO_ACTIVE_LOW>;
+
+ interrupt-parent = <&gpio>;
+ interrupts = <26 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "adc_rdy";
+
+ avdd-supply = <&ad74115_avdd>;
+
+ adi,ch-func = <1>;
+ adi,conv2-mux = <2>;
+ adi,conv2-range-microvolt = <(-12000000) 12000000>;
+
+ adi,gpio0-mode = <1>;
+ adi,gpio1-mode = <1>;
+ adi,gpio2-mode = <1>;
+ adi,gpio3-mode = <1>;
+
+ adi,dac-bipolar;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml b/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml
new file mode 100644
index 000000000000..590ea7936ad7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/addac/adi,ad74413r.yaml
@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/addac/adi,ad74413r.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD74412R/AD74413R device
+
+maintainers:
+ - Cosmin Tanislav <cosmin.tanislav@analog.com>
+
+description: |
+ The AD74412R and AD74413R are quad-channel software configurable input/output
+ solutions for building and process control applications. They contain
+ functionality for analog output, analog input, digital input, resistance
+ temperature detector, and thermocouple measurements integrated
+ into a single chip solution with an SPI interface.
+ The devices feature a 16-bit ADC and four configurable 13-bit DACs to provide
+ four configurable input/output channels and a suite of diagnostic functions.
+ The AD74413R differentiates itself from the AD74412R by being HART-compatible.
+ https://www.analog.com/en/products/ad74412r.html
+ https://www.analog.com/en/products/ad74413r.html
+
+properties:
+ compatible:
+ enum:
+ - adi,ad74412r
+ - adi,ad74413r
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ spi-max-frequency:
+ maximum: 1000000
+
+ spi-cpol: true
+
+ interrupts:
+ maxItems: 1
+
+ refin-supply: true
+
+ shunt-resistor-micro-ohms:
+ description:
+ Shunt (sense) resistor value in micro-Ohms.
+ default: 100000000
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - spi-max-frequency
+ - spi-cpol
+ - refin-supply
+
+patternProperties:
+ "^channel@[0-3]$":
+ type: object
+ additionalProperties: false
+ description: Represents the external channels which are connected to the device.
+
+ properties:
+ reg:
+ description: |
+ The channel number. It can have up to 4 channels numbered from 0 to 3.
+ minimum: 0
+ maximum: 3
+
+ adi,ch-func:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Channel function.
+ HART functions are not supported on AD74412R.
+ 0 - CH_FUNC_HIGH_IMPEDANCE
+ 1 - CH_FUNC_VOLTAGE_OUTPUT
+ 2 - CH_FUNC_CURRENT_OUTPUT
+ 3 - CH_FUNC_VOLTAGE_INPUT
+ 4 - CH_FUNC_CURRENT_INPUT_EXT_POWER
+ 5 - CH_FUNC_CURRENT_INPUT_LOOP_POWER
+ 6 - CH_FUNC_RESISTANCE_INPUT
+ 7 - CH_FUNC_DIGITAL_INPUT_LOGIC
+ 8 - CH_FUNC_DIGITAL_INPUT_LOOP_POWER
+ 9 - CH_FUNC_CURRENT_INPUT_EXT_POWER_HART
+ 10 - CH_FUNC_CURRENT_INPUT_LOOP_POWER_HART
+ minimum: 0
+ maximum: 10
+ default: 0
+
+ adi,gpo-comparator:
+ type: boolean
+ description: |
+ Whether to configure GPO as a comparator or not.
+ When not configured as a comparator, the GPO will be treated as an
+ output-only GPIO.
+
+ drive-strength-microamp:
+ description: |
+ For channels configured as digital input, this configures the sink
+ current.
+ minimum: 0
+ maximum: 1800
+ default: 0
+ multipleOf: 120
+
+ required:
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/iio/addac/adi,ad74413r.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ addac@0 {
+ compatible = "adi,ad74413r";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ spi-cpol;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ interrupt-parent = <&gpio>;
+ interrupts = <26 IRQ_TYPE_EDGE_FALLING>;
+
+ refin-supply = <&ad74413r_refin>;
+ reset-gpios = <&gpio2 6 GPIO_ACTIVE_LOW>;
+
+ channel@0 {
+ reg = <0>;
+
+ adi,ch-func = <CH_FUNC_VOLTAGE_OUTPUT>;
+ };
+
+ channel@1 {
+ reg = <1>;
+
+ adi,ch-func = <CH_FUNC_CURRENT_OUTPUT>;
+ };
+
+ channel@2 {
+ reg = <2>;
+
+ adi,ch-func = <CH_FUNC_DIGITAL_INPUT_LOGIC>;
+ adi,gpo-comparator;
+ };
+
+ channel@3 {
+ reg = <3>;
+
+ adi,ch-func = <CH_FUNC_CURRENT_INPUT_EXT_POWER>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/afe/current-sense-amplifier.yaml b/Documentation/devicetree/bindings/iio/afe/current-sense-amplifier.yaml
index 527501c1d695..bcf4ddcfd13b 100644
--- a/Documentation/devicetree/bindings/iio/afe/current-sense-amplifier.yaml
+++ b/Documentation/devicetree/bindings/iio/afe/current-sense-amplifier.yaml
@@ -24,6 +24,9 @@ properties:
description: |
Channel node of a voltage io-channel.
+ "#io-channel-cells":
+ const: 0
+
sense-resistor-micro-ohms:
description: The sense resistance.
@@ -46,6 +49,7 @@ examples:
- |
sysi {
compatible = "current-sense-amplifier";
+ #io-channel-cells = <0>;
io-channels = <&tiadc 0>;
sense-resistor-micro-ohms = <20000>;
diff --git a/Documentation/devicetree/bindings/iio/afe/temperature-sense-rtd.yaml b/Documentation/devicetree/bindings/iio/afe/temperature-sense-rtd.yaml
new file mode 100644
index 000000000000..336ce96371db
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/afe/temperature-sense-rtd.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/afe/temperature-sense-rtd.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Temperature Sense RTD
+
+maintainers:
+ - Liam Beguin <liambeguin@gmail.com>
+
+description: |
+ RTDs (Resistance Temperature Detectors) are a kind of temperature sensors
+ used to get a linear voltage to temperature reading within a give range
+ (usually 0 to 100 degrees Celsius).
+
+ When an io-channel measures the output voltage across an RTD such as a
+ PT1000, the interesting measurement is almost always the corresponding
+ temperature, not the voltage output. This binding describes such a circuit.
+
+ The general transfer function here is (using SI units)
+
+ V = R(T) * iexc
+ R(T) = r0 * (1 + alpha * T)
+ T = 1 / (alpha * r0 * iexc) * (V - r0 * iexc)
+
+ The following circuit matches what's in the examples section.
+
+ 5V0
+ -----
+ |
+ +---+----+
+ | R 5k |
+ +---+----+
+ |
+ V 1mA
+ |
+ +---- Vout
+ |
+ +---+----+
+ | PT1000 |
+ +---+----+
+ |
+ -----
+ GND
+
+properties:
+ compatible:
+ const: temperature-sense-rtd
+
+ io-channels:
+ maxItems: 1
+ description: |
+ Channel node of a voltage io-channel.
+
+ '#io-channel-cells':
+ const: 0
+
+ excitation-current-microamp:
+ description: The current fed through the RTD sensor.
+
+ alpha-ppm-per-celsius:
+ description: |
+ alpha can also be expressed in micro-ohms per ohm Celsius. It's a linear
+ approximation of the resistance versus temperature relationship
+ between 0 and 100 degrees Celsius.
+
+ alpha = (R_100 - R_0) / (100 * R_0)
+
+ Where, R_100 is the resistance of the sensor at 100 degrees Celsius, and
+ R_0 (or r-naught-ohms) is the resistance of the sensor at 0 degrees
+ Celsius.
+
+ Pure platinum has an alpha of 3925. Industry standards such as IEC60751
+ and ASTM E-1137 specify an alpha of 3850.
+
+ r-naught-ohms:
+ description: |
+ Resistance of the sensor at 0 degrees Celsius.
+ Common values are 100 for PT100, 500 for PT500, and 1000 for PT1000
+
+additionalProperties: false
+required:
+ - compatible
+ - io-channels
+ - excitation-current-microamp
+ - alpha-ppm-per-celsius
+ - r-naught-ohms
+
+examples:
+ - |
+ pt1000_1: temperature-sensor0 {
+ compatible = "temperature-sense-rtd";
+ #io-channel-cells = <0>;
+ io-channels = <&temp_adc1 0>;
+
+ excitation-current-microamp = <1000>; /* i = U/R = 5 / 5000 */
+ alpha-ppm-per-celsius = <3908>;
+ r-naught-ohms = <1000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/afe/temperature-transducer.yaml b/Documentation/devicetree/bindings/iio/afe/temperature-transducer.yaml
new file mode 100644
index 000000000000..cfbf5350db27
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/afe/temperature-transducer.yaml
@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/afe/temperature-transducer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Temperature Transducer
+
+maintainers:
+ - Liam Beguin <liambeguin@gmail.com>
+
+description: |
+ A temperature transducer is a device that converts a thermal quantity
+ into any other physical quantity. This binding applies to temperature to
+ voltage (like the LTC2997), and temperature to current (like the AD590)
+ linear transducers.
+ In both cases these are assumed to be connected to a voltage ADC.
+
+ When an io-channel measures the output voltage of a temperature analog front
+ end such as a temperature transducer, the interesting measurement is almost
+ always the corresponding temperature, not the voltage output. This binding
+ describes such a circuit.
+
+ The general transfer function here is (using SI units)
+ V(T) = Rsense * Isense(T)
+ T = (Isense(T) / alpha) + offset
+ T = 1 / (Rsense * alpha) * (V + offset * Rsense * alpha)
+
+ When using a temperature to voltage transducer, Rsense is set to 1.
+
+ The following circuits show a temperature to current and a temperature to
+ voltage transducer that can be used with this binding.
+
+ VCC
+ -----
+ |
+ +---+---+
+ | AD590 | VCC
+ +---+---+ -----
+ | |
+ V proportional to T +----+----+
+ | D+ --+ |
+ +---- Vout | LTC2997 +--- Vout
+ | D- --+ |
+ +---+----+ +---------+
+ | Rsense | |
+ +---+----+ -----
+ | GND
+ -----
+ GND
+
+properties:
+ compatible:
+ const: temperature-transducer
+
+ io-channels:
+ maxItems: 1
+ description: |
+ Channel node of a voltage io-channel.
+
+ '#io-channel-cells':
+ const: 0
+
+ sense-offset-millicelsius:
+ description: |
+ Temperature offset.
+ This offset is commonly used to convert from Kelvins to degrees Celsius.
+ In that case, sense-offset-millicelsius would be set to <(-273150)>.
+ default: 0
+
+ sense-resistor-ohms:
+ description: |
+ The sense resistor.
+ By default sense-resistor-ohms cancels out the resistor making the
+ circuit behave like a temperature transducer.
+ default: 1
+
+ alpha-ppm-per-celsius:
+ description: |
+ Sometimes referred to as output gain, slope, or temperature coefficient.
+
+ alpha is expressed in parts per million which can be micro-amps per
+ degrees Celsius or micro-volts per degrees Celsius. The is the main
+ characteristic of a temperature transducer and should be stated in the
+ datasheet.
+
+additionalProperties: false
+
+required:
+ - compatible
+ - io-channels
+ - alpha-ppm-per-celsius
+
+examples:
+ - |
+ ad950: temperature-sensor-0 {
+ compatible = "temperature-transducer";
+ #io-channel-cells = <0>;
+ io-channels = <&temp_adc 3>;
+
+ sense-offset-millicelsius = <(-273150)>; /* Kelvin to degrees Celsius */
+ sense-resistor-ohms = <8060>;
+ alpha-ppm-per-celsius = <1>; /* 1 uA/K */
+ };
+ - |
+ znq_tmp: temperature-sensor-1 {
+ compatible = "temperature-transducer";
+ #io-channel-cells = <0>;
+ io-channels = <&temp_adc 2>;
+
+ sense-offset-millicelsius = <(-273150)>; /* Kelvin to degrees Celsius */
+ alpha-ppm-per-celsius = <4000>; /* 4 mV/K */
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml b/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml
index df2589f214e1..9752d1450064 100644
--- a/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml
+++ b/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml
@@ -13,7 +13,7 @@ description: |
When an io-channel measures the midpoint of a voltage divider, the
interesting voltage is often the voltage over the full resistance
of the divider. This binding describes the voltage divider in such
- a curcuit.
+ a circuit.
Vin ----.
|
@@ -29,7 +29,6 @@ description: |
|
GND
-
properties:
compatible:
const: voltage-divider
@@ -39,6 +38,17 @@ properties:
description: |
Channel node of a voltage io-channel.
+ '#io-channel-cells':
+ description:
+ In addition to consuming the measurement services of a voltage
+ output channel, the voltage divider can act as a provider of
+ measurement services to other devices. This is particularly
+ useful in scenarios wherein an ADC has an analog frontend,
+ such as a voltage divider, and then consuming its raw value
+ isn't interesting. In this case, the voltage before the divider
+ is desired.
+ const: 1
+
output-ohms:
description:
Resistance Rout over which the output voltage is measured. See full-ohms.
diff --git a/Documentation/devicetree/bindings/iio/amplifiers/adi,ada4250.yaml b/Documentation/devicetree/bindings/iio/amplifiers/adi,ada4250.yaml
new file mode 100644
index 000000000000..c15da155d300
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/amplifiers/adi,ada4250.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/amplifiers/adi,ada4250.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADA4250 Programmable Gain Instrumentation Amplifier
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Precision Low Power, 110kHz, 26uA, Programmable Gain Instrumentation Amplifier.
+
+properties:
+ compatible:
+ enum:
+ - adi,ada4250
+
+ reg:
+ maxItems: 1
+
+ avdd-supply: true
+
+ adi,refbuf-enable:
+ description:
+ Enable internal buffer to drive the reference pin.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ amplifier@0 {
+ compatible = "adi,ada4250";
+ reg = <0>;
+ avdd-supply = <&avdd>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml b/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml
index a557761d8016..3a470459b965 100644
--- a/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml
+++ b/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml
@@ -4,31 +4,81 @@
$id: http://devicetree.org/schemas/iio/amplifiers/adi,hmc425a.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: HMC425A 6-bit Digital Step Attenuator
+title: Analog Devices HMC425A and similar Digital Step Attenuators
maintainers:
- Michael Hennerich <michael.hennerich@analog.com>
- - Beniamin Bia <beniamin.bia@analog.com>
description: |
- Digital Step Attenuator IIO device with gpio interface.
+ Digital Step Attenuator IIO devices with gpio interface.
+ Offer various frequency and attenuation ranges.
+ ADRF5750 2 dB LSB, 4-Bit, Silicon Digital Attenuator, 10 MHz to 60 GHz
+ https://www.analog.com/media/en/technical-documentation/data-sheets/adrf5740.pdf
+
HMC425A 0.5 dB LSB GaAs MMIC 6-BIT DIGITAL POSITIVE CONTROL ATTENUATOR, 2.2 - 8.0 GHz
- https://www.analog.com/media/en/technical-documentation/data-sheets/hmc425A.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/hmc425A.pdf
+
+ HMC540S 1 dB LSB Silicon MMIC 4-Bit Digital Positive Control Attenuator, 0.1 - 8 GHz
+ https://www.analog.com/media/en/technical-documentation/data-sheets/hmc540s.pdf
+
+ LTC6373 is a 3-Bit precision instrumentation amplifier with fully differential outputs
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ltc6373.pdf
properties:
compatible:
enum:
+ - adi,adrf5740
- adi,hmc425a
+ - adi,hmc540s
+ - adi,ltc6373
vcc-supply: true
ctrl-gpios:
description:
- Must contain an array of 6 GPIO specifiers, referring to the GPIO pins
- connected to the control pins V1-V6.
- minItems: 6
+ Must contain an array of GPIO specifiers, referring to the GPIO pins
+ connected to the control pins.
+ ADRF5740 - 4 GPIO connected to D2-D5
+ HMC540S - 4 GPIO connected to V1-V4
+ HMC425A - 6 GPIO connected to V1-V6
+ LTC6373 - 3 GPIO connected to A0-A2
+ minItems: 1
maxItems: 6
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,hmc425a
+ then:
+ properties:
+ ctrl-gpios:
+ minItems: 6
+ maxItems: 6
+ - if:
+ properties:
+ compatible:
+ contains:
+ anyOf:
+ - const: adi,adrf5740
+ - const: adi,hmc540s
+ then:
+ properties:
+ ctrl-gpios:
+ minItems: 4
+ maxItems: 4
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,ltc6373
+ then:
+ properties:
+ ctrl-gpios:
+ minItems: 3
+ maxItems: 3
+
required:
- compatible
- ctrl-gpios
diff --git a/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml
index 2155d3f5666c..3d7074fd17be 100644
--- a/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml
+++ b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/cdc/adi,ad7150.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Analog device AD7150 and similar capacitance to digital convertors.
+title: Analog device AD7150 and similar capacitance to digital converters.
maintainers:
- Jonathan Cameron <jic23@kernel.org>
diff --git a/Documentation/devicetree/bindings/iio/chemical/aosong,ags02ma.yaml b/Documentation/devicetree/bindings/iio/chemical/aosong,ags02ma.yaml
new file mode 100644
index 000000000000..35e7b094e878
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/aosong,ags02ma.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/aosong,ags02ma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aosong AGS02MA VOC Sensor
+
+description: |
+ AGS02MA is an TVOC (Total Volatile Organic Compounds) i2c sensor with default
+ address of 0x1a.
+
+ Datasheet:
+ https://asairsensors.com/wp-content/uploads/2021/09/AGS02MA.pdf
+
+maintainers:
+ - Anshul Dalal <anshulusr@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - aosong,ags02ma
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ voc-sensor@1a {
+ compatible = "aosong,ags02ma";
+ reg = <0x1a>;
+ vdd-supply = <&vdd_regulator>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml b/Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml
new file mode 100644
index 000000000000..fe98ec44f081
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/bosch,bme680.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bosch BME680 Gas sensor
+
+maintainers:
+ - Vasileios Amoiridis <vassilisamir@gmail.com>
+
+description: >
+ BME680 is a gas sensor which combines relative humidity, barometric pressure,
+ ambient temperature and gas (VOC - Volatile Organic Compounds) measurements.
+
+ https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme680-ds001.pdf
+
+properties:
+ compatible:
+ const: bosch,bme680
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ co2-sensor@77 {
+ compatible = "bosch,bme680";
+ reg = <0x77>;
+ vddio-supply = <&vddio>;
+ vdd-supply = <&vdd>;
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ co2-sensor@0 {
+ compatible = "bosch,bme680";
+ reg = <0>;
+ spi-max-frequency = <500000>;
+ vddio-supply = <&vddio>;
+ vdd-supply = <&vdd>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/chemical/sciosense,ens160.yaml b/Documentation/devicetree/bindings/iio/chemical/sciosense,ens160.yaml
new file mode 100644
index 000000000000..267033a68abb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/sciosense,ens160.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/sciosense,ens160.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ScioSense ENS160 multi-gas sensor
+
+maintainers:
+ - Gustavo Silva <gustavograzs@gmail.com>
+
+description: |
+ Digital Multi-Gas Sensor for Monitoring Indoor Air Quality.
+
+ Datasheet:
+ https://www.sciosense.com/wp-content/uploads/2023/12/ENS160-Datasheet.pdf
+
+properties:
+ compatible:
+ enum:
+ - sciosense,ens160
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gas-sensor@52 {
+ compatible = "sciosense,ens160";
+ reg = <0x52>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <19 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ gas-sensor@0 {
+ compatible = "sciosense,ens160";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ interrupt-parent = <&gpio>;
+ interrupts = <19 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/chemical/senseair,sunrise.yaml b/Documentation/devicetree/bindings/iio/chemical/senseair,sunrise.yaml
new file mode 100644
index 000000000000..337fe09e4bb8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/senseair,sunrise.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/senseair,sunrise.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Senseair Sunrise 006-0-0007 CO2 Sensor
+
+maintainers:
+ - Jacopo Mondi <jacopo@jmondi.org>
+
+description: |
+ Senseair Sunrise 006-0-0007 is a NDIR CO2 sensor. It supports I2C or UART buses
+ for communications and control.
+
+ Datasheets:
+ https://rmtplusstoragesenseair.blob.core.windows.net/docs/Dev/publicerat/PSP11704.pdf
+ https://rmtplusstoragesenseair.blob.core.windows.net/docs/Dev/publicerat/PSH11649.pdf
+ https://rmtplusstoragesenseair.blob.core.windows.net/docs/Dev/publicerat/TDE5531.pdf
+ https://rmtplusstoragesenseair.blob.core.windows.net/docs/Market/publicerat/TDE7318.pdf
+
+properties:
+ compatible:
+ const: senseair,sunrise-006-0-0007
+
+ reg:
+ maxItems: 1
+
+ ndry-gpios:
+ maxItems: 1
+ description:
+ Phandle to the GPIO line connected to the nDRY pin. Typically active low.
+
+ en-gpios:
+ maxItems: 1
+ description:
+ Phandle to the GPIO line connected to the EN pin. Typically active high.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ co2-sensor@68 {
+ compatible = "senseair,sunrise-006-0-0007";
+ reg = <0x68>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/chemical/sensirion,scd4x.yaml b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd4x.yaml
new file mode 100644
index 000000000000..798f48d05279
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd4x.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/sensirion,scd4x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sensirion SCD4X carbon dioxide sensor
+
+maintainers:
+ - Roan van Dijk <roan@protonic.nl>
+
+description: |
+ Air quality sensor capable of measuring co2 concentration, temperature
+ and relative humidity.
+
+properties:
+ compatible:
+ enum:
+ - sensirion,scd40
+ - sensirion,scd41
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ co2-sensor@62 {
+ compatible = "sensirion,scd41";
+ reg = <0x62>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/chemical/winsen,mhz19b.yaml b/Documentation/devicetree/bindings/iio/chemical/winsen,mhz19b.yaml
new file mode 100644
index 000000000000..2a6ddb33f163
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/chemical/winsen,mhz19b.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/chemical/winsen,mhz19b.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MHZ19B CO2 sensor
+
+maintainers:
+ - Gyeyoung Baek <gye976@gmail.com>
+
+properties:
+ compatible:
+ const: winsen,mhz19b
+
+ vin-supply:
+ description: Regulator that provides power to the sensor
+
+required:
+ - compatible
+ - vin-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ serial {
+ co2-sensor {
+ compatible = "winsen,mhz19b";
+ vin-supply = <&vdd>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/common.yaml b/Documentation/devicetree/bindings/iio/common.yaml
index f845b41d74c4..b3a10af86d76 100644
--- a/Documentation/devicetree/bindings/iio/common.yaml
+++ b/Documentation/devicetree/bindings/iio/common.yaml
@@ -12,7 +12,7 @@ maintainers:
description: |
This document defines device tree properties common to several iio
- sensors. It doesn't constitue a device tree binding specification by itself but
+ sensors. It doesn't constitute a device tree binding specification by itself but
is meant to be referenced by device tree bindings.
When referenced from sensor tree bindings the properties defined in this
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad3530r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad3530r.yaml
new file mode 100644
index 000000000000..a355d52a9d64
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad3530r.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad3530r.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD3530R and Similar DACs
+
+maintainers:
+ - Kim Seer Paller <kimseer.paller@analog.com>
+
+description: |
+ The AD3530/AD3530R (8-channel) and AD3531/AD3531R (4-channel) are low-power,
+ 16-bit, buffered voltage output digital-to-analog converters (DACs) with
+ software-programmable gain controls, providing full-scale output spans of 2.5V
+ or 5V for reference voltages of 2.5V. These devices operate from a single 2.7V
+ to 5.5V supply and are guaranteed monotonic by design. The "R" variants
+ include a 2.5V, 5ppm/°C internal reference, which is disabled by default.
+ Datasheet can be found here:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad3530_ad530r.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad3531-ad3531r.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad3530
+ - adi,ad3530r
+ - adi,ad3531
+ - adi,ad3531r
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 50000000
+
+ vdd-supply:
+ description: Power Supply Input.
+
+ iovdd-supply:
+ description: Digital Power Supply Input.
+
+ io-channels:
+ description:
+ ADC channel used to monitor internal die temperature, output voltages, and
+ current of a selected channel via the MUXOUT pin.
+ maxItems: 1
+
+ ref-supply:
+ description:
+ Reference Input/Output. The voltage at the REF pin sets the full-scale
+ range of all channels. If not provided the internal reference is used and
+ also provided on the VREF pin.
+
+ reset-gpios:
+ description:
+ Active low signal that is falling edge sensitive. When it is deasserted,
+ the digital core initialization is performed and all DAC registers except
+ the Interface Configuration A register are reset to their default values.
+ maxItems: 1
+
+ ldac-gpios:
+ description:
+ LDAC pin to be used as a hardware trigger to update the DAC channels. If
+ not present, the DAC channels are updated by Software LDAC.
+ maxItems: 1
+
+ adi,range-double:
+ description:
+ Configure the output range for all channels. If the property is present,
+ the output will range from 0V to 2Vref. If the property is not present,
+ the output will range from 0V to Vref.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - iovdd-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ compatible = "adi,ad3530r";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+
+ vdd-supply = <&vdd>;
+ iovdd-supply = <&iovdd>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
new file mode 100644
index 000000000000..547044b8e246
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2020 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad3552r.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD2552R DAC device driver
+
+maintainers:
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ Bindings for the Analog Devices AD3552R DAC device and similar.
+ Datasheet can be found here:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad3541r.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad3542r.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad3551r.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad3552r.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad3541r
+ - adi,ad3542r
+ - adi,ad3551r
+ - adi,ad3552r
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 66000000
+
+ reset-gpios:
+ maxItems: 1
+
+ ldac-gpios:
+ description: |
+ LDAC pin to be used as a hardware trigger to update the DAC channels.
+ maxItems: 1
+
+ vref-supply:
+ description:
+ The regulator to use as an external reference. If it does not exists the
+ internal reference will be used. External reference must be 2.5V
+
+ adi,vref-out-en:
+ description: Vref I/O driven by internal vref to 2.5V. If not set, Vref pin
+ will be floating.
+ type: boolean
+
+ adi,sdo-drive-strength:
+ description: |
+ Configure SDIO0 and SDIO1 strength levels:
+ - 0: low SDO drive strength.
+ - 1: medium low SDO drive strength.
+ - 2: medium high SDO drive strength.
+ - 3: high SDO drive strength
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+ io-backends:
+ description: The iio backend reference.
+ Device can be optionally connected to the "axi-ad3552r IP" fpga-based
+ QSPI + DDR (Double Data Rate) controller to reach high speed transfers.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@([0-1])$":
+ type: object
+ description: Configurations of the DAC Channels
+
+ additionalProperties: false
+
+ properties:
+ reg:
+ description: Channel number
+ enum: [0, 1]
+
+ adi,output-range-microvolt: true
+
+ custom-output-range-config:
+ type: object
+ additionalProperties: false
+ description: Configuration of custom range when
+ adi,output-range-microvolt is not present.
+ The formulas for calculation the output voltages are
+ Vout_fs = 2.5 + [(GainN + Offset/1024) * 2.5 * Rfbx * 1.03]
+ Vout_zs = 2.5 - [(GainP + Offset/1024) * 2.5 * Rfbx * 1.03]
+
+ properties:
+ adi,gain-offset:
+ description: Gain offset used in the above formula
+ $ref: /schemas/types.yaml#/definitions/int32
+ maximum: 511
+ minimum: -511
+
+ adi,gain-scaling-p:
+ description: GainP = 1 / ( 2 ^ adi,gain-scaling-p)
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+ adi,gain-scaling-n:
+ description: GainN = 1 / ( 2 ^ adi,gain-scaling-n)
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+
+ adi,rfb-ohms:
+ description: Feedback Resistor
+
+ required:
+ - adi,gain-offset
+ - adi,gain-scaling-p
+ - adi,gain-scaling-n
+ - adi,rfb-ohms
+
+ required:
+ - reg
+
+ oneOf:
+ # If adi,output-range-microvolt is missing,
+ # custom-output-range-config must be used
+ - required:
+ - adi,output-range-microvolt
+
+ - required:
+ - custom-output-range-config
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad3541r
+ - adi,ad3542r
+ then:
+ patternProperties:
+ "^channel@([0-1])$":
+ type: object
+ properties:
+ adi,output-range-microvolt:
+ description: |
+ Voltage output range of the channel as <minimum, maximum>
+ Required connections:
+ Rfb1x for: 0 to 2.5 V; 0 to 3V; 0 to 5 V;
+ Rfb2x for: 0 to 10 V; -2.5 to 7.5V; -5 to 5 V;
+ oneOf:
+ - items:
+ - const: 0
+ - enum: [2500000, 3000000, 5000000, 10000000]
+ - items:
+ - const: -2500000
+ - const: 7500000
+ - items:
+ - const: -5000000
+ - const: 5000000
+
+ required:
+ - adi,output-range-microvolt
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad3551r
+ - adi,ad3552r
+ then:
+ patternProperties:
+ "^channel@([0-1])$":
+ type: object
+ properties:
+ adi,output-range-microvolt:
+ description: |
+ Voltage output range of the channel as <minimum, maximum>
+ Required connections:
+ Rfb1x for: 0 to 2.5 V; 0 to 5 V;
+ Rfb2x for: 0 to 10 V; -5 to 5 V;
+ Rfb4x for: -10 to 10V
+ oneOf:
+ - items:
+ - const: 0
+ - enum: [2500000, 5000000, 10000000]
+ - items:
+ - const: -5000000
+ - const: 5000000
+ - items:
+ - const: -10000000
+ - const: 10000000
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad3541r
+ - adi,ad3551r
+ then:
+ properties:
+ channel@1: false
+ channel@0:
+ properties:
+ reg:
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - spi-max-frequency
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ad3552r@0 {
+ compatible = "adi,ad3552r";
+ reg = <0>;
+ spi-max-frequency = <20000000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@0 {
+ reg = <0>;
+ adi,output-range-microvolt = <0 10000000>;
+ };
+ channel@1 {
+ reg = <1>;
+ custom-output-range-config {
+ adi,gain-offset = <5>;
+ adi,gain-scaling-p = <1>;
+ adi,gain-scaling-n = <2>;
+ adi,rfb-ohms = <1>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml
new file mode 100644
index 000000000000..c04165fa9259
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5064.yaml
@@ -0,0 +1,267 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5064.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5064 and similar DACs
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ A range of similar DAC devices with between 1 and 12 channels. Some parts
+ have internal references, others require a single shared external reference
+ and the remainder have a separate reference pin for each DAC.
+
+properties:
+ compatible:
+ oneOf:
+ - description: I2C devics
+ enum:
+ - adi,ad5024
+ - adi,ad5025
+ - adi,ad5044
+ - adi,ad5045
+ - adi,ad5064
+ - adi,ad5064-1
+ - adi,ad5065
+ - adi,ad5628-1
+ - adi,ad5628-2
+ - adi,ad5648-1
+ - adi,ad5648-2
+ - adi,ad5666-1
+ - adi,ad5666-2
+ - adi,ad5668-1
+ - adi,ad5668-2
+ - adi,ad5668-3
+ - description: SPI devices
+ enum:
+ - adi,ad5625
+ - adi,ad5625r-1v25
+ - adi,ad5625r-2v5
+ - adi,ad5627
+ - adi,ad5627r-1v25
+ - adi,ad5627r-2v5
+ - adi,ad5629-1
+ - adi,ad5629-2
+ - adi,ad5629-3
+ - adi,ad5645r-1v25
+ - adi,ad5645r-2v5
+ - adi,ad5665
+ - adi,ad5665r-1v25
+ - adi,ad5665r-2v5
+ - adi,ad5667
+ - adi,ad5667r-1v25
+ - adi,ad5667r-2v5
+ - adi,ad5669-1
+ - adi,ad5669-2
+ - adi,ad5669-3
+ - lltc,ltc2606
+ - lltc,ltc2607
+ - lltc,ltc2609
+ - lltc,ltc2616
+ - lltc,ltc2617
+ - lltc,ltc2619
+ - lltc,ltc2626
+ - lltc,ltc2627
+ - lltc,ltc2629
+ - lltc,ltc2631-l12
+ - lltc,ltc2631-h12
+ - lltc,ltc2631-l10
+ - lltc,ltc2631-h10
+ - lltc,ltc2631-l8
+ - lltc,ltc2631-h8
+ - lltc,ltc2633-l12
+ - lltc,ltc2633-h12
+ - lltc,ltc2633-l10
+ - lltc,ltc2633-h10
+ - lltc,ltc2633-l8
+ - lltc,ltc2633-h8
+ - lltc,ltc2635-l12
+ - lltc,ltc2635-h12
+ - lltc,ltc2635-l10
+ - lltc,ltc2635-h10
+ - lltc,ltc2635-l8
+ - lltc,ltc2635-h8
+
+ reg:
+ maxItems: 1
+
+ vrefA-supply: true
+ vrefB-supply: true
+ vrefC-supply: true
+ vrefD-supply: true
+ vref-supply: true
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - # Shared external vref, no internal reference
+ if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5064-1
+ - adi,ad5625
+ - adi,ad5627
+ - adi,ad5665
+ - adi,ad5667
+ - lltc,ltc2606
+ - lltc,ltc2607
+ - lltc,ltc2616
+ - lltc,ltc2617
+ - lltc,ltc2626
+ - lltc,ltc2627
+ then:
+ properties:
+ vref-supply: true
+ vrefA-supply: false
+ vrefB-supply: false
+ vrefC-supply: false
+ vrefD-supply: false
+ required:
+ - vref-supply
+ - # Shared external vref, internal reference available
+ if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5625r-1v25
+ - adi,ad5625r-2v5
+ - adi,ad5627r-1v25
+ - adi,ad5627r-2v5
+ - adi,ad5628-1
+ - adi,ad5628-2
+ - adi,ad5629-1
+ - adi,ad5629-2
+ - adi,ad5629-3
+ - adi,ad5645r-1v25
+ - adi,ad5645r-2v5
+ - adi,ad5647r-1v25
+ - adi,ad5647r-2v5
+ - adi,ad5648-1
+ - adi,ad5648-2
+ - adi,ad5665r-1v25
+ - adi,ad5665r-2v5
+ - adi,ad5666-1
+ - adi,ad5666-2
+ - adi,ad5667r-1v25
+ - adi,ad5667r-2v5
+ - adi,ad5668-1
+ - adi,ad5668-2
+ - adi,ad5668-3
+ - adi,ad5669-1
+ - adi,ad5669-2
+ - adi,ad5669-3
+ - lltc,ltc2631-l12
+ - lltc,ltc2631-h12
+ - lltc,ltc2631-l10
+ - lltc,ltc2631-h10
+ - lltc,ltc2631-l8
+ - lltc,ltc2631-h8
+ - lltc,ltc2633-l12
+ - lltc,ltc2633-h12
+ - lltc,ltc2633-l10
+ - lltc,ltc2633-h10
+ - lltc,ltc2633-l8
+ - lltc,ltc2633-h8
+ - lltc,ltc2635-l12
+ - lltc,ltc2635-h12
+ - lltc,ltc2635-l10
+ - lltc,ltc2635-h10
+ - lltc,ltc2635-l8
+ - lltc,ltc2635-h8
+ then:
+ properties:
+ vref-supply: true
+ vrefA-supply: false
+ vrefB-supply: false
+ vrefC-supply: false
+ vrefD-supply: false
+ - # 4 input devices, separate vrefs, no internal reference
+ if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5024
+ - adi,ad5044
+ - adi,ad5064
+ - lltc,ltc2609
+ - lltc,ltc2619
+ - lltc,ltc2629
+ then:
+ properties:
+ vrefA-supply: true
+ vrefB-supply: true
+ vrefC-supply: true
+ vrefD-supply: true
+ vref-supply: false
+ required:
+ - vrefA-supply
+ - vrefB-supply
+ - vrefC-supply
+ - vrefD-supply
+ - # 2 input devices, separate vrefs, no internal reference
+ if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5025
+ - adi,ad5045
+ - adi,ad5065
+ then:
+ properties:
+ vrefA-supply: true
+ vrefB-supply: true
+ vrefC-supply: false
+ vrefD-supply: false
+ vref-supply: false
+ required:
+ - vrefA-supply
+ - vrefB-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5625";
+ vref-supply = <&dac_vref>;
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5625r-1v25";
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@42 {
+ reg = <0x42>;
+ compatible = "adi,ad5024";
+ vrefA-supply = <&dac_vref>;
+ vrefB-supply = <&dac_vref>;
+ vrefC-supply = <&dac_vref2>;
+ vrefD-supply = <&dac_vref2>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml
new file mode 100644
index 000000000000..86e2884cdfb1
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5360.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5360.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5360 and similar DACs
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5360
+ - adi,ad5361
+ - adi,ad5363
+ - adi,ad5370
+ - adi,ad5371
+ - adi,ad5372
+ - adi,ad5373
+
+ reg:
+ maxItems: 1
+
+ vref0-supply: true
+ vref1-supply: true
+ vref2-supply: true
+
+required:
+ - compatible
+ - reg
+ - vref0-supply
+ - vref1-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5360
+ - adi,ad5361
+ - adi,ad5363
+ - adi,ad5370
+ - adi,ad5372
+ - adi,ad5373
+ then:
+ properties:
+ vref2-supply: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5371
+ then:
+ required:
+ - vref2-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5371";
+ vref0-supply = <&dac_vref0>;
+ vref1-supply = <&dac_vref1>;
+ vref2-supply = <&dac_vref2>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml
new file mode 100644
index 000000000000..3e323f1a5458
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5380.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5380.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5380 and similar DACs
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ DAC devices supporting both SPI and I2C interfaces.
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5380-3
+ - adi,ad5380-5
+ - adi,ad5381-3
+ - adi,ad5381-5
+ - adi,ad5382-3
+ - adi,ad5382-5
+ - adi,ad5383-3
+ - adi,ad5383-5
+ - adi,ad5384-3
+ - adi,ad5384-5
+ - adi,ad5390-3
+ - adi,ad5390-5
+ - adi,ad5391-3
+ - adi,ad5391-5
+ - adi,ad5392-3
+ - adi,ad5392-5
+
+ reg:
+ maxItems: 1
+
+ vref-supply:
+ description:
+ If not supplied devices will use internal regulators.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5390-5";
+ vref-supply = <&dacvref>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@42 {
+ reg = <0x42>;
+ compatible = "adi,ad5380-3";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml
new file mode 100644
index 000000000000..52d089ebde95
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5421.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5421.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5421 DAC
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ AD5421 is designed for us in loop-powered, 4 mA to 20 mA smart transmitter
+ applications. It provides a 16-bit DAC, current amplifier, voltage regulator
+ to drive the loop and a voltage reference.
+
+properties:
+ compatible:
+ const: adi,ad5421
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+ description: Fault signal.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad5421";
+ reg = <0>;
+ spi-max-frequency = <30000000>;
+ interrupts = <55 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5446.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5446.yaml
new file mode 100644
index 000000000000..2669d2c4948b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5446.yaml
@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5446.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5446 and similar DACs
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
+
+description:
+ Digital to Analog Converter devices supporting both SPI and I2C interfaces.
+ These devices feature a range of resolutions from 8-bit to 16-bit.
+
+properties:
+ compatible:
+ oneOf:
+ - description: SPI DACs
+ enum:
+ - adi,ad5300
+ - adi,ad5310
+ - adi,ad5320
+ - adi,ad5444
+ - adi,ad5446
+ - adi,ad5450
+ - adi,ad5451
+ - adi,ad5452
+ - adi,ad5453
+ - adi,ad5512a
+ - adi,ad5541a
+ - adi,ad5542
+ - adi,ad5542a
+ - adi,ad5543
+ - adi,ad5553
+ - adi,ad5600
+ - adi,ad5601
+ - adi,ad5611
+ - adi,ad5621
+ - adi,ad5641
+ - adi,ad5620-2500
+ - adi,ad5620-1250
+ - adi,ad5640-2500
+ - adi,ad5640-1250
+ - adi,ad5660-2500
+ - adi,ad5660-1250
+ - adi,ad5662
+ - ti,dac081s101
+ - ti,dac101s101
+ - ti,dac121s101
+ - description: I2C DACs
+ enum:
+ - adi,ad5301
+ - adi,ad5311
+ - adi,ad5321
+ - adi,ad5602
+ - adi,ad5612
+ - adi,ad5622
+
+ reg:
+ maxItems: 1
+
+ vcc-supply:
+ description:
+ Reference voltage supply. If not supplied, devices with internal
+ voltage reference will use that.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5300
+ - adi,ad5310
+ - adi,ad5320
+ - adi,ad5444
+ - adi,ad5446
+ - adi,ad5450
+ - adi,ad5451
+ - adi,ad5452
+ - adi,ad5453
+ - adi,ad5512a
+ - adi,ad5541a
+ - adi,ad5542
+ - adi,ad5542a
+ - adi,ad5543
+ - adi,ad5553
+ - adi,ad5600
+ - adi,ad5601
+ - adi,ad5611
+ - adi,ad5621
+ - adi,ad5641
+ - adi,ad5620-2500
+ - adi,ad5620-1250
+ - adi,ad5640-2500
+ - adi,ad5640-1250
+ - adi,ad5660-2500
+ - adi,ad5660-1250
+ - adi,ad5662
+ - ti,dac081s101
+ - ti,dac101s101
+ - ti,dac121s101
+ then:
+ allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad5446";
+ reg = <0>;
+ vcc-supply = <&dac_vref>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@42 {
+ compatible = "adi,ad5622";
+ reg = <0x42>;
+ vcc-supply = <&dac_vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml
new file mode 100644
index 000000000000..d2af2d491986
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5449.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5449.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5449 and similar DACs
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description:
+ Family of multiplying DACs from Analog Devices
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5415
+ - adi,ad5426
+ - adi,ad5429
+ - adi,ad5432
+ - adi,ad5439
+ - adi,ad5443
+ - adi,ad5449
+
+ reg:
+ maxItems: 1
+
+ VREF-supply: true
+ VREFA-supply: true
+ VREFB-supply: true
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5415
+ - adi,ad5426
+ - adi,ad5432
+ then:
+ properties:
+ VREF-supply: true
+ VREFA-supply: false
+ VREFB-supply: false
+ required:
+ - VREF-supply
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5429
+ - adi,ad5439
+ - adi,ad5449
+ then:
+ properties:
+ VREF-supply: false
+ VREFA-supply: true
+ VREFB-supply: true
+ required:
+ - VREFA-supply
+ - VREFB-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5415";
+ VREF-supply = <&dac_ref>;
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5429";
+ VREFA-supply = <&dac_refA>;
+ VREFB-supply = <&dac_refB>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml
new file mode 100644
index 000000000000..9c2c038683b4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5504.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5504.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5501 and AD5504 DACs
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description:
+ High voltage (up to 60V) DACs with temperature sensor alarm function
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5501
+ - adi,ad5504
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description: Used for temperature alarm.
+ maxItems: 1
+
+ vcc-supply: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5504";
+ vcc-supply = <&dac_vcc>;
+ interrupts = <55 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml
new file mode 100644
index 000000000000..4d5111a5f9bd
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5624r.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5624r.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5624r and similar DACs
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5624r3
+ - adi,ad5644r3
+ - adi,ad5664r3
+ - adi,ad5624r5
+ - adi,ad5644r5
+ - adi,ad5664r5
+
+ reg:
+ maxItems: 1
+
+ vref-supply:
+ description: If not present, internal reference will be used.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5624r3";
+ vref-supply = <&vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml
new file mode 100644
index 000000000000..713f535bb33a
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5686.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5686.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5360 and similar SPI DACs
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5310r
+ - adi,ad5672r
+ - adi,ad5674r
+ - adi,ad5676
+ - adi,ad5676r
+ - adi,ad5679r
+ - adi,ad5681r
+ - adi,ad5682r
+ - adi,ad5683
+ - adi,ad5683r
+ - adi,ad5684
+ - adi,ad5684r
+ - adi,ad5685r
+ - adi,ad5686
+ - adi,ad5686r
+
+ reg:
+ maxItems: 1
+
+ vcc-supply:
+ description: If not supplied the internal reference is used.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ reg = <0>;
+ compatible = "adi,ad5310r";
+ vcc-supply = <&dac_vref0>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5696.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5696.yaml
index 56b0cda0f30a..b5a88b03dc2f 100644
--- a/Documentation/devicetree/bindings/iio/dac/adi,ad5696.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5696.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/dac/adi,ad5696.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Analog Devices AD5696 and similar multi-channel DACs
+title: Analog Devices AD5696 and similar I2C multi-channel DACs
maintainers:
- Michael Auchter <michael.auchter@ni.com>
@@ -16,6 +16,7 @@ properties:
compatible:
enum:
- adi,ad5311r
+ - adi,ad5337r
- adi,ad5338r
- adi,ad5671r
- adi,ad5675r
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml
index be419ac46caa..9a3c2926bf85 100644
--- a/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5755.yaml
@@ -25,8 +25,6 @@ properties:
description: Either this or spi-cpol but not both.
spi-cpol: true
- spi-max-frequency: true
-
adi,ext-dc-dc-compenstation-resistor:
$ref: /schemas/types.yaml#/definitions/flag
description:
@@ -67,8 +65,6 @@ required:
- compatible
- reg
-additionalProperties: false
-
patternProperties:
"^channel@[0-7]$":
type: object
@@ -123,9 +119,13 @@ oneOf:
- required:
- spi-cpol
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
- #include <dt-bindings/iio/adi,ad5592r.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml
index fd4edca34a28..5121685337b5 100644
--- a/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml
@@ -16,7 +16,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
spi-cpha: true
adi,dc-dc-mode:
@@ -79,7 +78,8 @@ properties:
- const: -1000
- const: 22000
- reset-gpios: true
+ reset-gpios:
+ maxItems: 1
adi,dc-dc-ilim-microamp:
enum: [150000, 200000, 250000, 300000, 350000, 400000]
@@ -99,11 +99,11 @@ required:
- adi,dc-dc-mode
allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
- if:
properties:
adi,dc-dc-mode:
- contains:
- enum: [1, 3]
+ enum: [1, 3]
then:
properties:
adi,range-microvolt: false
@@ -115,7 +115,7 @@ allOf:
required:
- adi,range-microvolt
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml
new file mode 100644
index 000000000000..df550b5af2f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5761.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5761.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5761 and similar DACs
+
+maintainers:
+ - Ricardo Ribalda <ribalda@kernel.org>
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+
+ compatible:
+ enum:
+ - adi,ad5721
+ - adi,ad5721r
+ - adi,ad5761
+ - adi,ad5761r
+
+ reg:
+ maxItems: 1
+
+ vref-supply:
+ description: If not supplied, internal reference will be used.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5721
+ - adi,ad5761
+ then:
+ required:
+ - vref-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad5721";
+ reg = <0>;
+ vref-supply = <&dac_vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml
new file mode 100644
index 000000000000..0b409a727a43
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5764.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5764.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5744 and AD5764 DAC families
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+
+ compatible:
+ enum:
+ - adi,ad5744
+ - adi,ad5744r
+ - adi,ad5764
+ - adi,ad5764r
+
+ reg:
+ maxItems: 1
+
+ vrefAB-supply: true
+ vrefCD-supply: true
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ad5744
+ - adi,ad5764
+ then:
+ required:
+ - vrefAB-supply
+ - vrefCD-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad5744";
+ reg = <0>;
+ vrefAB-supply = <&dac_vref>;
+ vrefCD-supply = <&dac_vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml
index d5c54813ce87..212c936bab8d 100644
--- a/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5766.yaml
@@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices AD5766 DAC device driver
maintainers:
- - Cristian Pop <cristian.pop@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
description: |
Bindings for the Analog Devices AD5766 current DAC device. Datasheet can be
@@ -22,6 +22,8 @@ properties:
- adi,ad5767
output-range-microvolts:
+ $ref: /schemas/types.yaml#/definitions/int32-array
+ maxItems: 2
description: Select converter output range.
reg:
@@ -49,15 +51,15 @@ additionalProperties: false
examples:
- |
spi {
- #address-cells = <1>;
- #size-cells = <0>;
-
- ad5766@0 {
- compatible = "adi,ad5766";
- output-range-microvolts = <(-5000) 5000>;
- reg = <0>;
- spi-cpol;
- spi-max-frequency = <1000000>;
- reset-gpios = <&gpio 22 0>;
- };
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ad5766@0 {
+ compatible = "adi,ad5766";
+ output-range-microvolts = <(-5000000) 5000000>;
+ reg = <0>;
+ spi-cpol;
+ spi-max-frequency = <1000000>;
+ reset-gpios = <&gpio 22 0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml
index fb2c48fc7ce4..091cc93f1f90 100644
--- a/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5770r.yaml
@@ -8,7 +8,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices AD5770R DAC device driver
maintainers:
- - Mircea Caprioru <mircea.caprioru@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
description: |
Bindings for the Analog Devices AD5770R current DAC device. Datasheet can be
@@ -49,8 +50,6 @@ properties:
asserted during driver probe.
maxItems: 1
- spi-max-frequency: true
-
'#address-cells':
const: 1
@@ -62,6 +61,7 @@ properties:
connected to the DAC. Channel 0 can act both as a current
source and sink.
type: object
+ additionalProperties: false
properties:
reg:
@@ -85,6 +85,7 @@ properties:
description: Represents an external channel which are
connected to the DAC.
type: object
+ additionalProperties: false
properties:
reg:
@@ -101,6 +102,7 @@ properties:
description: Represents an external channel which are
connected to the DAC.
type: object
+ additionalProperties: false
properties:
reg:
@@ -116,6 +118,7 @@ properties:
patternProperties:
"^channel@([3-5])$":
type: object
+ additionalProperties: false
description: Represents the external channels which are connected to the DAC.
properties:
reg:
@@ -138,53 +141,56 @@ required:
- channel@4
- channel@5
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- spi {
- #address-cells = <1>;
- #size-cells = <0>;
-
- ad5770r@0 {
- compatible = "adi,ad5770r";
- reg = <0>;
- spi-max-frequency = <1000000>;
- vref-supply = <&vref>;
- adi,external-resistor;
- reset-gpios = <&gpio 22 0>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- channel@0 {
- reg = <0>;
- adi,range-microamp = <0 300000>;
- };
-
- channel@1 {
- reg = <1>;
- adi,range-microamp = <0 140000>;
- };
-
- channel@2 {
- reg = <2>;
- adi,range-microamp = <0 55000>;
- };
-
- channel@3 {
- reg = <3>;
- adi,range-microamp = <0 45000>;
- };
-
- channel@4 {
- reg = <4>;
- adi,range-microamp = <0 45000>;
- };
-
- channel@5 {
- reg = <5>;
- adi,range-microamp = <0 45000>;
- };
- };
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ad5770r@0 {
+ compatible = "adi,ad5770r";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ vref-supply = <&vref>;
+ adi,external-resistor;
+ reset-gpios = <&gpio 22 0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ adi,range-microamp = <0 300000>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ adi,range-microamp = <0 140000>;
+ };
+
+ channel@2 {
+ reg = <2>;
+ adi,range-microamp = <0 55000>;
+ };
+
+ channel@3 {
+ reg = <3>;
+ adi,range-microamp = <0 45000>;
+ };
+
+ channel@4 {
+ reg = <4>;
+ adi,range-microamp = <0 45000>;
+ };
+
+ channel@5 {
+ reg = <5>;
+ adi,range-microamp = <0 45000>;
+ };
};
+ };
...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml
new file mode 100644
index 000000000000..2bd89e0aa46b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad5791.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5791 and similar DACs
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+
+ compatible:
+ enum:
+ - adi,ad5760
+ - adi,ad5780
+ - adi,ad5781
+ - adi,ad5790
+ - adi,ad5791
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vss-supply: true
+
+ vcc-supply:
+ description:
+ Supply that powers the chip.
+
+ iovcc-supply:
+ description:
+ Supply for the digital interface.
+
+ vrefp-supply:
+ description:
+ Positive referance input voltage range. From 5v to (vdd - 2.5)
+
+ vrefn-supply:
+ description:
+ Negative referance input voltage range. From (vss + 2.5) to 0.
+
+ adi,rbuf-gain2-en:
+ description: Specify to allow an external amplifier to be connected in a
+ gain of two configuration.
+ type: boolean
+
+ reset-gpios:
+ maxItems: 1
+
+ clear-gpios:
+ maxItems: 1
+
+ ldac-gpios:
+ description:
+ LDAC pin to be used as a hardware trigger to update the DAC channels.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vss-supply
+ - vcc-supply
+ - iovcc-supply
+ - vrefp-supply
+ - vrefn-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad5791";
+ reg = <0>;
+ vss-supply = <&dac_vss>;
+ vdd-supply = <&dac_vdd>;
+ vcc-supply = <&dac_vcc>;
+ iovcc-supply = <&dac_iovcc>;
+ vrefp-supply = <&dac_vrefp>;
+ vrefn-supply = <&dac_vrefn>;
+ reset-gpios = <&gpio_bd 16 GPIO_ACTIVE_LOW>;
+ clear-gpios = <&gpio_bd 17 GPIO_ACTIVE_LOW>;
+ ldac-gpios = <&gpio_bd 18 GPIO_ACTIVE_LOW>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml
new file mode 100644
index 000000000000..f994c1ef6d41
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad7293.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad7293.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AD7293 12-Bit Power Amplifier Current Controller with ADC,
+ DACs, Temperature and Current Sensors
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Power Amplifier drain current controller containing functionality
+ for general-purpose monitoring and control of current, voltage,
+ and temperature, integrated into a single chip solution with an
+ SPI-compatible interface.
+
+ https://www.analog.com/en/products/ad7293.html
+
+properties:
+ compatible:
+ enum:
+ - adi,ad7293
+
+ avdd-supply: true
+
+ vdrive-supply: true
+
+ vrefin-supply: true
+
+ reset-gpios:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 1000000
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - vdrive-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ad7293@0 {
+ compatible = "adi,ad7293";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ avdd-supply = <&avdd>;
+ vdrive-supply = <&vdrive>;
+ reset-gpios = <&gpio 10 0>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad8460.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad8460.yaml
new file mode 100644
index 000000000000..b65928024e12
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad8460.yaml
@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2024 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad8460.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD8460 DAC
+
+maintainers:
+ - Mariel Tinaco <mariel.tinaco@analog.com>
+
+description: |
+ Analog Devices AD8460 110 V High Voltage, 1 A High Current,
+ Arbitrary Waveform Generator with Integrated 14-Bit High Speed DAC
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad8460.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad8460
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ items:
+ - const: tx
+
+ spi-max-frequency:
+ maximum: 20000000
+
+ hvcc-supply:
+ description: Positive high voltage power supply line
+
+ hvee-supply:
+ description: Negative high voltage power supply line
+
+ vcc-5v-supply:
+ description: Low voltage power supply
+
+ vref-5v-supply:
+ description: Reference voltage for analog low voltage
+
+ dvdd-3p3v-supply:
+ description: Digital supply bypass
+
+ avdd-3p3v-supply:
+ description: Analog supply bypass
+
+ refio-1p2v-supply:
+ description: Drive voltage in the range of 1.2V maximum to as low as
+ low as 0.12V through the REF_IO pin to adjust full scale output span
+
+ adi,external-resistor-ohms:
+ description: Specify value of external resistor connected to FS_ADJ pin
+ to establish internal HVDAC's reference current I_REF
+ minimum: 2000
+ maximum: 20000
+ default: 2000
+
+ adi,range-microvolt:
+ description: Voltage output range specified as <minimum, maximum>
+ items:
+ - minimum: -55000000
+ maximum: 0
+ default: 0
+ - minimum: 0
+ maximum: 55000000
+ default: 0
+
+ adi,range-microamp:
+ description: Current output range specified as <minimum, maximum>
+ items:
+ - minimum: -1000000
+ maximum: 0
+ default: 0
+ - minimum: 0
+ maximum: 1000000
+ default: 0
+
+ adi,max-millicelsius:
+ description: Overtemperature threshold
+ minimum: 0
+ maximum: 150000
+ default: 0
+
+ shutdown-reset-gpios:
+ description: Corresponds to SDN_RESET pin. To exit shutdown
+ or sleep mode, pulse SDN_RESET HIGH, then leave LOW.
+ maxItems: 1
+
+ reset-gpios:
+ description: Manual Power On Reset (POR). Pull this GPIO pin
+ LOW and then HIGH to reset all digital registers to default
+ maxItems: 1
+
+ shutdown-gpios:
+ description: Corresponds to SDN_IO pin. Shutdown may be
+ initiated by the user, by pulsing SDN_IO high. To exit shutdown,
+ pulse SDN_IO low, then float.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - hvcc-supply
+ - hvee-supply
+ - vcc-5v-supply
+ - vref-5v-supply
+ - dvdd-3p3v-supply
+ - avdd-3p3v-supply
+ - refio-1p2v-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad8460";
+ reg = <0>;
+ spi-max-frequency = <8000000>;
+
+ dmas = <&tx_dma 0>;
+ dma-names = "tx";
+
+ shutdown-reset-gpios = <&gpio 86 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio 91 GPIO_ACTIVE_LOW>;
+ shutdown-gpios = <&gpio 88 GPIO_ACTIVE_HIGH>;
+
+ clocks = <&sync_ext_clk>;
+
+ hvcc-supply = <&hvcc>;
+ hvee-supply = <&hvee>;
+ vcc-5v-supply = <&vcc_5>;
+ vref-5v-supply = <&vref_5>;
+ dvdd-3p3v-supply = <&dvdd_3_3>;
+ avdd-3p3v-supply = <&avdd_3_3>;
+ refio-1p2v-supply = <&refio_1_2>;
+
+ adi,external-resistor-ohms = <2000>;
+ adi,range-microvolt = <(-40000000) 40000000>;
+ adi,range-microamp = <0 50000>;
+ adi,max-millicelsius = <50000>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml
new file mode 100644
index 000000000000..1849a2ff05c7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad8801.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad8801.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD8801 and AD8803 DACs
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+properties:
+
+ compatible:
+ enum:
+ - adi,ad8801
+ - adi,ad8803
+
+ reg:
+ maxItems: 1
+
+ vrefh-supply: true
+ vrefl-supply: true
+
+required:
+ - compatible
+ - reg
+ - vrefh-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,ad8803
+ then:
+ required:
+ - vrefl-supply
+ else:
+ properties:
+ vrefl-supply: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad8803";
+ reg = <0>;
+ vrefl-supply = <&dac_vrefl>;
+ vrefh-supply = <&dac_vrefh>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad9739a.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad9739a.yaml
new file mode 100644
index 000000000000..c0b36476113a
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad9739a.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad9739a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD9739A RF DAC
+
+maintainers:
+ - Dragos Bogdan <dragos.bogdan@analog.com>
+ - Nuno Sa <nuno.sa@analog.com>
+
+description: |
+ The AD9739A is a 14-bit, 2.5 GSPS high performance RF DACs that are capable
+ of synthesizing wideband signals from dc up to 3 GHz.
+
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad9737a_9739a.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ad9739a
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-3p3-supply:
+ description: 3.3V Digital input supply.
+
+ vdd-supply:
+ description: 1.8V Digital input supply.
+
+ vdda-supply:
+ description: 3.3V Analog input supply.
+
+ vddc-supply:
+ description: 1.8V Clock input supply.
+
+ vref-supply:
+ description: Input/Output reference supply.
+
+ io-backends:
+ maxItems: 1
+
+ adi,full-scale-microamp:
+ description: This property represents the DAC full scale current.
+ minimum: 8580
+ maximum: 31700
+ default: 20000
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - io-backends
+ - vdd-3p3-supply
+ - vdd-supply
+ - vdda-supply
+ - vddc-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad9739a";
+ reg = <0>;
+
+ clocks = <&dac_clk>;
+
+ io-backends = <&iio_backend>;
+
+ vdd-3p3-supply = <&vdd_3_3>;
+ vdd-supply = <&vdd>;
+ vdda-supply = <&vdd_3_3>;
+ vddc-supply = <&vdd>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,axi-dac.yaml b/Documentation/devicetree/bindings/iio/dac/adi,axi-dac.yaml
new file mode 100644
index 000000000000..1adba9aceeb1
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,axi-dac.yaml
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,axi-dac.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AXI DAC IP core
+
+maintainers:
+ - Nuno Sa <nuno.sa@analog.com>
+
+description: |
+ Analog Devices Generic AXI DAC IP core for interfacing a DAC device
+ with a high speed serial (JESD204B/C) or source synchronous parallel
+ interface (LVDS/CMOS).
+ Usually, some other interface type (i.e SPI) is used as a control
+ interface for the actual DAC, while this IP core will interface
+ to the data-lines of the DAC and handle the streaming of data from
+ memory via DMA into the DAC.
+
+ https://wiki.analog.com/resources/fpga/docs/axi_dac_ip
+ https://analogdevicesinc.github.io/hdl/library/axi_ad3552r/index.html
+
+properties:
+ compatible:
+ enum:
+ - adi,axi-dac-9.1.b
+ - adi,axi-ad3552r
+
+ reg:
+ maxItems: 1
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ items:
+ - const: tx
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: s_axi_aclk
+ - const: dac_clk
+ minItems: 1
+
+ '#io-backend-cells':
+ const: 0
+
+required:
+ - compatible
+ - dmas
+ - reg
+ - clocks
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,axi-ad3552r
+ then:
+ $ref: /schemas/spi/spi-controller.yaml#
+ properties:
+ clocks:
+ minItems: 2
+ clock-names:
+ minItems: 2
+ required:
+ - clock-names
+ else:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ dac@44a00000 {
+ compatible = "adi,axi-dac-9.1.b";
+ reg = <0x44a00000 0x10000>;
+ dmas = <&tx_dma 0>;
+ dma-names = "tx";
+ #io-backend-cells = <0>;
+ clocks = <&clkc 15>;
+ clock-names = "s_axi_aclk";
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ axi_dac: spi@44a70000 {
+ compatible = "adi,axi-ad3552r";
+ reg = <0x44a70000 0x1000>;
+ dmas = <&dac_tx_dma 0>;
+ dma-names = "tx";
+ #io-backend-cells = <0>;
+ clocks = <&clkc 15>, <&ref_clk>;
+ clock-names = "s_axi_aclk", "dac_clk";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "adi,ad3552r";
+ reg = <0>;
+ reset-gpios = <&gpio0 92 GPIO_ACTIVE_HIGH>;
+ io-backends = <&axi_dac>;
+ spi-max-frequency = <20000000>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ adi,output-range-microvolt = <(-10000000) (10000000)>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ltc2664.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ltc2664.yaml
new file mode 100644
index 000000000000..4688eccfeb89
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ltc2664.yaml
@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ltc2664.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LTC2664 DAC
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Kim Seer Paller <kimseer.paller@analog.com>
+
+description: |
+ Analog Devices LTC2664 4 channel, 12-/16-Bit, +-10V DAC
+ https://www.analog.com/media/en/technical-documentation/data-sheets/2664fa.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ltc2664
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 50000000
+
+ vcc-supply:
+ description: Analog Supply Voltage Input.
+
+ v-pos-supply:
+ description: Positive Supply Voltage Input.
+
+ v-neg-supply:
+ description: Negative Supply Voltage Input.
+
+ iovcc-supply:
+ description: Digital Input/Output Supply Voltage.
+
+ ref-supply:
+ description:
+ Reference Input/Output. The voltage at the REF pin sets the full-scale
+ range of all channels. If not provided the internal reference is used and
+ also provided on the VREF pin.
+
+ reset-gpios:
+ description:
+ Active-low Asynchronous Clear Input. A logic low at this level-triggered
+ input clears the part to the reset code and range determined by the
+ hardwired option chosen using the MSPAN pins. The control registers are
+ cleared to zero.
+ maxItems: 1
+
+ adi,manual-span-operation-config:
+ description:
+ This property must mimic the MSPAN pin configurations. By tying the MSPAN
+ pins (MSP2, MSP1 and MSP0) to GND and/or VCC, any output range can be
+ hardware-configured with different mid-scale or zero-scale reset options.
+ The hardware configuration is latched during power on reset for proper
+ operation.
+ 0 - MPS2=GND, MPS1=GND, MSP0=GND (+-10V, reset to 0V)
+ 1 - MPS2=GND, MPS1=GND, MSP0=VCC (+-5V, reset to 0V)
+ 2 - MPS2=GND, MPS1=VCC, MSP0=GND (+-2.5V, reset to 0V)
+ 3 - MPS2=GND, MPS1=VCC, MSP0=VCC (0V to 10, reset to 0V)
+ 4 - MPS2=VCC, MPS1=GND, MSP0=GND (0V to 10V, reset to 5V)
+ 5 - MPS2=VCC, MPS1=GND, MSP0=VCC (0V to 5V, reset to 0V)
+ 6 - MPS2=VCC, MPS1=VCC, MSP0=GND (0V to 5V, reset to 2.5V)
+ 7 - MPS2=VCC, MPS1=VCC, MSP0=VCC (0V to 5V, reset to 0V, enables SoftSpan)
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3, 4, 5, 6, 7]
+ default: 7
+
+ io-channels:
+ description:
+ ADC channel to monitor voltages and temperature at the MUXOUT pin.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@[0-3]$":
+ $ref: dac.yaml
+ type: object
+ additionalProperties: false
+
+ properties:
+ reg:
+ description: The channel number representing the DAC output channel.
+ maximum: 3
+
+ adi,toggle-mode:
+ description:
+ Set the channel as a toggle enabled channel. Toggle operation enables
+ fast switching of a DAC output between two different DAC codes without
+ any SPI transaction.
+ type: boolean
+
+ output-range-microvolt:
+ description:
+ This property is only allowed when SoftSpan is enabled. If not present,
+ [0, 5000000] is the default output range.
+ oneOf:
+ - items:
+ - const: 0
+ - enum: [5000000, 10000000]
+ - items:
+ - const: -5000000
+ - const: 5000000
+ - items:
+ - const: -10000000
+ - const: 10000000
+ - items:
+ - const: -2500000
+ - const: 2500000
+
+ required:
+ - reg
+
+ allOf:
+ - if:
+ not:
+ properties:
+ adi,manual-span-operation-config:
+ const: 7
+ then:
+ patternProperties:
+ "^channel@[0-3]$":
+ properties:
+ output-range-microvolt: false
+
+required:
+ - compatible
+ - reg
+ - spi-max-frequency
+ - vcc-supply
+ - iovcc-supply
+ - v-pos-supply
+ - v-neg-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ compatible = "adi,ltc2664";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+
+ vcc-supply = <&vcc>;
+ iovcc-supply = <&vcc>;
+ ref-supply = <&vref>;
+ v-pos-supply = <&vpos>;
+ v-neg-supply = <&vneg>;
+
+ io-channels = <&adc 0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@0 {
+ reg = <0>;
+ adi,toggle-mode;
+ output-range-microvolt = <(-10000000) 10000000>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ output-range-microvolt = <0 10000000>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ltc2672.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ltc2672.yaml
new file mode 100644
index 000000000000..3c8e5781e42c
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ltc2672.yaml
@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ltc2672.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LTC2672 DAC
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+ - Kim Seer Paller <kimseer.paller@analog.com>
+
+description: |
+ Analog Devices LTC2672 5 channel, 12-/16-Bit, 300mA DAC
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ltc2672.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ltc2672
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 50000000
+
+ vcc-supply:
+ description: Analog Supply Voltage Input.
+
+ v-neg-supply:
+ description: Negative Supply Voltage Input.
+
+ vdd0-supply:
+ description: Positive Supply Voltage Input for DAC OUT0.
+
+ vdd1-supply:
+ description: Positive Supply Voltage Input for DAC OUT1.
+
+ vdd2-supply:
+ description: Positive Supply Voltage Input for DAC OUT2.
+
+ vdd3-supply:
+ description: Positive Supply Voltage Input for DAC OUT3.
+
+ vdd4-supply:
+ description: Positive Supply Voltage Input for DAC OUT4.
+
+ iovcc-supply:
+ description: Digital Input/Output Supply Voltage.
+
+ ref-supply:
+ description:
+ Reference Input/Output. The voltage at the REF pin sets the full-scale
+ range of all channels. If not provided the internal reference is used and
+ also provided on the VREF pin.
+
+ reset-gpios:
+ description:
+ Active Low Asynchronous Clear Input. A logic low at this level triggered
+ input clears the device to the default reset code and output range, which
+ is zero-scale with the outputs off. The control registers are cleared to
+ zero.
+ maxItems: 1
+
+ adi,rfsadj-ohms:
+ description:
+ If FSADJ is tied to VCC, an internal RFSADJ (20 kΩ) is selected, which
+ results in nominal output ranges. When an external resistor of 19 kΩ to
+ 41 kΩ can be used instead by connecting the resistor between FSADJ and GND
+ it controls the scaling of the ranges, and the internal resistor is
+ automatically disconnected.
+ minimum: 19000
+ maximum: 41000
+ default: 20000
+
+ io-channels:
+ description:
+ ADC channel to monitor voltages and currents at the MUX pin.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@[0-4]$":
+ $ref: dac.yaml
+ type: object
+ additionalProperties: false
+
+ properties:
+ reg:
+ description: The channel number representing the DAC output channel.
+ maximum: 4
+
+ adi,toggle-mode:
+ description:
+ Set the channel as a toggle enabled channel. Toggle operation enables
+ fast switching of a DAC output between two different DAC codes without
+ any SPI transaction.
+ type: boolean
+
+ output-range-microamp:
+ items:
+ - const: 0
+ - enum: [3125000, 6250000, 12500000, 25000000, 50000000, 100000000,
+ 200000000, 300000000]
+
+ required:
+ - reg
+ - output-range-microamp
+
+required:
+ - compatible
+ - reg
+ - spi-max-frequency
+ - vcc-supply
+ - iovcc-supply
+ - v-neg-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ dac@0 {
+ compatible = "adi,ltc2672";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+
+ vcc-supply = <&vcc>;
+ iovcc-supply = <&vcc>;
+ ref-supply = <&vref>;
+ v-neg-supply = <&vneg>;
+
+ io-channels = <&adc 0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@0 {
+ reg = <0>;
+ adi,toggle-mode;
+ output-range-microamp = <0 3125000>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ output-range-microamp = <0 6250000>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml
new file mode 100644
index 000000000000..f22ef710ecde
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ltc2688.yaml
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ltc2688.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices LTC2688 DAC
+
+maintainers:
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ Analog Devices LTC2688 16 channel, 16 bit, +-15V DAC
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ltc2688.pdf
+
+properties:
+ compatible:
+ enum:
+ - adi,ltc2688
+
+ reg:
+ maxItems: 1
+
+ vcc-supply:
+ description: Analog Supply Voltage Input.
+
+ iovcc-supply:
+ description: Digital Input/Output Supply Voltage.
+
+ vref-supply:
+ description:
+ Reference Input/Output. The voltage at the REF pin sets the full-scale
+ range of all channels. If not provided the internal reference is used and
+ also provided on the VREF pin".
+
+ clr-gpios:
+ description:
+ If specified, it will be asserted during driver probe. As the line is
+ active low, it should be marked GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@([0-9]|1[0-5])$":
+ type: object
+ additionalProperties: false
+
+ properties:
+ reg:
+ description: The channel number representing the DAC output channel.
+ maximum: 15
+
+ adi,toggle-mode:
+ description:
+ Set the channel as a toggle enabled channel. Toggle operation enables
+ fast switching of a DAC output between two different DAC codes without
+ any SPI transaction.
+ type: boolean
+
+ adi,output-range-microvolt:
+ description: Specify the channel output full scale range.
+ oneOf:
+ - items:
+ - const: 0
+ - enum: [5000000, 10000000]
+ - items:
+ - const: -5000000
+ - const: 5000000
+ - items:
+ - const: -10000000
+ - const: 10000000
+ - items:
+ - const: -15000000
+ - const: 15000000
+
+ adi,overrange:
+ description: Enable 5% overrange over the selected full scale range.
+ type: boolean
+
+ clocks:
+ maxItems: 1
+
+ adi,toggle-dither-input:
+ description:
+ Selects the TGPx pin to be associated with this channel. This setting
+ only makes sense for toggle or dither enabled channels. If
+ @adi,toggle-mode is not set and this property is given, the channel is
+ assumed to be a dither capable channel. Note that multiple channels
+ can be mapped to the same pin. If this setting is given, the
+ respective @clock must also be provided. Mappings between this and
+ input pins
+ 0 - TGP1
+ 1 - TGP2
+ 2 - TGP3
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+
+ dependencies:
+ adi,toggle-dither-input: [ clocks ]
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ ltc2688: ltc2688@0 {
+ compatible = "adi,ltc2688";
+ reg = <0>;
+
+ vcc-supply = <&vcc>;
+ iovcc-supply = <&vcc>;
+ vref-supply = <&vref>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+ channel@0 {
+ reg = <0>;
+ adi,toggle-mode;
+ adi,overrange;
+ };
+
+ channel@1 {
+ reg = <1>;
+ adi,output-range-microvolt = <0 10000000>;
+
+ clocks = <&clock_tgp3>;
+ adi,toggle-dither-input = <2>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/dac.yaml b/Documentation/devicetree/bindings/iio/dac/dac.yaml
new file mode 100644
index 000000000000..daa40724e1cf
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/dac.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/dac.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IIO Common Properties for DAC Channels
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+description:
+ A few properties are defined in a common way for DAC channels.
+
+properties:
+ $nodename:
+ pattern: "^channel(@[0-9a-f]+)?$"
+ description:
+ A channel index should match reg.
+
+ reg:
+ maxItems: 1
+
+ label:
+ description: Unique name to identify which channel this is.
+
+ output-range-microamp:
+ maxItems: 2
+ minItems: 2
+ description:
+ Specify the channel output full scale range in microamperes.
+
+ output-range-microvolt:
+ maxItems: 2
+ minItems: 2
+ description:
+ Specify the channel output full scale range in microvolts.
+
+anyOf:
+ - oneOf:
+ - required:
+ - reg
+ - output-range-microamp
+ - required:
+ - reg
+ - output-range-microvolt
+ - required:
+ - reg
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml b/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml
index e51a585bd5a3..c9f51d00fa8f 100644
--- a/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/lltc,ltc1660.yaml
@@ -2,8 +2,8 @@
# Copyright 2019 Marcus Folkesson <marcus.folkesson@gmail.com>
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/dac/lltc,ltc1660.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/dac/lltc,ltc1660.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Linear Technology Micropower octal 8-Bit and 10-Bit DACs
@@ -41,7 +41,7 @@ examples:
spi {
#address-cells = <1>;
#size-cells = <0>;
-
+
dac@0 {
compatible = "lltc,ltc1660";
reg = <0>;
diff --git a/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml b/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml
index edf804d0aca2..733edc7d6d17 100644
--- a/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/lltc,ltc2632.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/dac/lltc,ltc2632.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/dac/lltc,ltc2632.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Linear Technology LTC263x 12-/10-/8-Bit Rail-to-Rail DAC
@@ -64,14 +64,14 @@ examples:
};
spi {
- #address-cells = <1>;
- #size-cells = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
- dac@0 {
- compatible = "lltc,ltc2632";
- reg = <0>; /* CS0 */
- spi-max-frequency = <1000000>;
- vref-supply = <&vref>;
- };
+ dac@0 {
+ compatible = "lltc,ltc2632-l12";
+ reg = <0>; /* CS0 */
+ spi-max-frequency = <1000000>;
+ vref-supply = <&vref>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/iio/dac/maxim,max5522.yaml b/Documentation/devicetree/bindings/iio/dac/maxim,max5522.yaml
new file mode 100644
index 000000000000..24830f56c501
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/maxim,max5522.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/maxim,max5522.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim Integrated MAX5522 Dual 10-bit Voltage-Output SPI DACs
+
+maintainers:
+ - Angelo Dureghello <angelo.dureghello@timesys.com>
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ Datasheet available at:
+ https://www.analog.com/en/products/max5522.html
+
+properties:
+ compatible:
+ const: maxim,max5522
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vrefin-supply: true
+
+required:
+ - compatible
+ - reg
+ - vrefin-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "maxim,max5522";
+ reg = <0>;
+ vrefin-supply = <&vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml
new file mode 100644
index 000000000000..99831d7f1c16
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4728.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/iio/dac/microchip,mcp4728.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MCP4728 DAC
+
+maintainers:
+ - Andrea Collamati <andrea.collamati@gmail.com>
+
+description: |
+ MCP4728 is a quad channel, 12-bit voltage output
+ Digital-to-Analog Converter with non-volatile
+ memory and I2C compatible Serial Interface.
+ https://www.microchip.com/en-us/product/mcp4728
+
+properties:
+ compatible:
+ const: microchip,mcp4728
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: |
+ Provides both power and acts as the reference supply on the MCP4728
+ when Internal Vref is not selected.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@60 {
+ compatible = "microchip,mcp4728";
+ reg = <0x60>;
+ vdd-supply = <&vdac_vdd>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4821.yaml b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4821.yaml
new file mode 100644
index 000000000000..26011b5639d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4821.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/microchip,mcp4821.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MCP4821 and similar DACs
+
+description: |
+ Supports MCP48x1 (single channel) and MCP48x2 (dual channel) series of DACs.
+ Device supports simplex communication over SPI in Mode 0 and Mode 3.
+
+ +---------+--------------+-------------+
+ | Device | Resolution | Channels |
+ |---------|--------------|-------------|
+ | MCP4801 | 8-bit | 1 |
+ | MCP4802 | 8-bit | 2 |
+ | MCP4811 | 10-bit | 1 |
+ | MCP4812 | 10-bit | 2 |
+ | MCP4821 | 12-bit | 1 |
+ | MCP4822 | 12-bit | 2 |
+ +---------+--------------+-------------+
+
+ Datasheet:
+ MCP48x1: https://ww1.microchip.com/downloads/en/DeviceDoc/22244B.pdf
+ MCP48x2: https://ww1.microchip.com/downloads/en/DeviceDoc/20002249B.pdf
+
+maintainers:
+ - Anshul Dalal <anshulusr@gmail.com>
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - microchip,mcp4801
+ - microchip,mcp4802
+ - microchip,mcp4811
+ - microchip,mcp4812
+ - microchip,mcp4821
+ - microchip,mcp4822
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ ldac-gpios:
+ description: |
+ Active Low LDAC (Latch DAC Input) pin used to update the DAC output.
+ maxItems: 1
+
+ powerdown-gpios:
+ description: |
+ Active Low SHDN pin used to enter the shutdown mode.
+ maxItems: 1
+
+ spi-cpha: true
+ spi-cpol: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "microchip,mcp4821";
+ reg = <0>;
+ vdd-supply = <&vdd_regulator>;
+ ldac-gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
+ powerdown-gpios = <&gpio0 2 GPIO_ACTIVE_HIGH>;
+ spi-cpha;
+ spi-cpol;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml
new file mode 100644
index 000000000000..19374401e509
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/microchip,mcp4922.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/microchip,mcp4922.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MCP4902, MCP4912 and MPC4922 dual output SPI DACs
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+ - Michael Welling <mwelling@ieee.org>
+
+properties:
+ compatible:
+ enum:
+ - microchip,mcp4902
+ - microchip,mcp4912
+ - microchip,mcp4921
+ - microchip,mcp4922
+
+ reg:
+ maxItems: 1
+
+ vref-supply: true
+
+required:
+ - compatible
+ - reg
+ - vref-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "microchip,mcp4912";
+ reg = <0>;
+ vref-supply = <&dac_vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/nxp,lpc1850-dac.yaml b/Documentation/devicetree/bindings/iio/dac/nxp,lpc1850-dac.yaml
index 595f481c548e..9c8afe3f1b69 100644
--- a/Documentation/devicetree/bindings/iio/dac/nxp,lpc1850-dac.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/nxp,lpc1850-dac.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/dac/nxp,lpc1850-dac.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: NXP LPC1850 DAC bindings
+title: NXP LPC1850 DAC
maintainers:
- Jonathan Cameron <jic23@kernel.org>
diff --git a/Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml b/Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml
new file mode 100644
index 000000000000..c00fa50e42e8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2024 ROHM Semiconductor.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/rohm,bd79703.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BD79700, BD79701, BD79702 and BD79703 DACs
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description: |
+ The ROHM BD7970[0,1,2,3] are 8-bit DACs. The BD79700 has 2 channels,
+ BD79701 3 channels, BD79702 4 channels and BD79703 has 6 channels.
+ Datasheets for BD79702 and BD79703 can be found from
+ https://fscdn.rohm.com/en/products/databook/datasheet/ic/data_converter/dac/bd79702fv-lb_bd79703fv-lb-e.pdf
+ and for the BD79700 and the BD79701 from
+ https://fscdn.rohm.com/en/products/databook/datasheet/ic/data_converter/dac/bd79700fvm-lb_bd79701fvm-lb-e.pdf
+
+properties:
+ compatible:
+ enum:
+ - rohm,bd79700
+ - rohm,bd79701
+ - rohm,bd79702
+ - rohm,bd79703
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 30000000
+
+ vfs-supply:
+ description:
+ The regulator to use as a full scale voltage. The voltage should be
+ between 2.7V .. VCC. Not present on BD79700 and BD79701.
+
+ vcc-supply:
+ description:
+ The regulator supplying the operating voltage. Should be between
+ 2.7V ... 5.5V. Is used also as a Vfs on BD79700 and BD79701.
+
+required:
+ - compatible
+ - reg
+ - spi-max-frequency
+ - vcc-supply
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - rohm,bd79702
+ - rohm,bd79703
+then:
+ required:
+ - vfs-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dac@0 {
+ compatible = "rohm,bd79703";
+ reg = <0>;
+ spi-max-frequency = <30000000>;
+ vcc-supply = <&vcc>;
+ vfs-supply = <&vref>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml
index 393f7005941a..b15de4eb209c 100644
--- a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/dac/st,stm32-dac.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/dac/st,stm32-dac.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 DAC bindings
+title: STMicroelectronics STM32 DAC
description: |
The STM32 DAC is a 12-bit voltage output digital-to-analog converter. The DAC
@@ -15,7 +15,7 @@ description: |
current.
maintainers:
- - Fabrice Gasnier <fabrice.gasnier@st.com>
+ - Fabrice Gasnier <fabrice.gasnier@foss.st.com>
properties:
compatible:
@@ -45,6 +45,10 @@ properties:
'#size-cells':
const: 0
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
additionalProperties: false
required:
diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac082s085.yaml b/Documentation/devicetree/bindings/iio/dac/ti,dac082s085.yaml
index b0157050f1ee..201b04af2b22 100644
--- a/Documentation/devicetree/bindings/iio/dac/ti,dac082s085.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/ti,dac082s085.yaml
@@ -33,21 +33,22 @@ properties:
vref-supply:
description: Needed to provide output scaling.
- spi-max-frequency: true
-
required:
- compatible
- reg
- vref-supply
-additionalProperties: false
-
oneOf:
- required:
- spi-cpha
- required:
- spi-cpol
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
vref_2v5_reg: regulator-vref {
diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml b/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml
index 714191724f7c..e59db861e2eb 100644
--- a/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/ti,dac5571.yaml
@@ -21,6 +21,8 @@ properties:
- ti,dac5573
- ti,dac6573
- ti,dac7573
+ - ti,dac081c081
+ - ti,dac121c081
reg:
maxItems: 1
@@ -45,7 +47,7 @@ examples:
dac@4c {
compatible = "ti,dac5571";
- reg = <0x4C>;
+ reg = <0x4c>;
vref-supply = <&vdd_supply>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7311.yaml b/Documentation/devicetree/bindings/iio/dac/ti,dac7311.yaml
index 10be98d1f19c..a6814587dbc4 100644
--- a/Documentation/devicetree/bindings/iio/dac/ti,dac7311.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7311.yaml
@@ -24,14 +24,15 @@ properties:
Reference voltage must be supplied to establish the scaling of the
output voltage.
- spi-max-frequency: true
-
required:
- compatible
- reg
- vref-supply
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.yaml b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.yaml
index d172b142f6ed..20dd1370660d 100644
--- a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.yaml
+++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.yaml
@@ -29,13 +29,14 @@ properties:
DACs are loaded when the pin connected to this GPIO is pulled low.
maxItems: 1
- spi-max-frequency: true
-
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml b/Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml
new file mode 100644
index 000000000000..ff0cb553e871
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/filter/adi,admv8818.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/filter/adi,admv8818.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADMV8818 Digitally Tunable, High-Pass and Low-Pass Filter
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Fully monolithic microwave integrated circuit (MMIC) that
+ features a digitally selectable frequency of operation.
+ The device features four independently controlled high-pass
+ filters (HPFs) and four independently controlled low-pass filters
+ (LPFs) that span the 2 GHz to 18 GHz frequency range.
+
+ https://www.analog.com/en/products/admv8818.html
+
+properties:
+ compatible:
+ enum:
+ - adi,admv8818
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 10000000
+
+ clocks:
+ description:
+ Definition of the external clock.
+ minItems: 1
+
+ clock-names:
+ items:
+ - const: rf_in
+
+ clock-output-names:
+ maxItems: 1
+
+ '#clock-cells':
+ const: 0
+
+ adi,lpf-margin-mhz:
+ description:
+ Sets the minimum distance between the fundamental frequency of `rf_in`
+ and the corner frequency of the low-pass, output filter when operated in
+ 'auto' mode. The selected low-pass corner frequency will be greater than,
+ or equal to, `rf_in` + `lpf-margin-hz`. If not setting is found that
+ satisfies this relationship the filter will be put into 'bypass'.
+ default: 0
+
+ adi,hpf-margin-mhz:
+ description:
+ Sets the minimum distance between the fundamental frequency of `rf_in`
+ and the corner frequency of the high-pass, input filter when operated in
+ 'auto' mode. The selected high-pass corner frequency will be less than,
+ or equal to, `rf_in` - `hpf-margin-hz`. If not setting is found that
+ satisfies this relationship the filter will be put into 'bypass'.
+ default: 0
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ admv8818@0 {
+ compatible = "adi,admv8818";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ clocks = <&admv8818_rfin>;
+ clock-names = "rf_in";
+ adi,lpf-margin-mhz = <300>;
+ adi,hpf-margin-mhz = <300>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml b/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
index 6b3a611e1cf1..2e1ff77fd1de 100644
--- a/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
+++ b/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
@@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices ADF4371/ADF4372 Wideband Synthesizers
maintainers:
- - Popa Stefan <stefan.popa@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
description: |
Analog Devices ADF4371/ADF4372 SPI Wideband Synthesizers
@@ -30,8 +31,9 @@ properties:
clock-names:
description:
- Must be "clkin"
- maxItems: 1
+ Must be "clkin" if the input reference is single ended or "clkin-diff"
+ if the input reference is differential.
+ enum: [clkin, clkin-diff]
adi,mute-till-lock-en:
type: boolean
@@ -40,28 +42,29 @@ properties:
output stage will shut down until the ADF4371/ADF4372 achieves lock as
measured by the digital lock detect circuitry.
- spi-max-frequency: true
-
required:
- compatible
- reg
- clocks
- clock-names
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
frequency@0 {
- compatible = "adi,adf4371";
- reg = <0>;
- spi-max-frequency = <1000000>;
- clocks = <&adf4371_clkin>;
- clock-names = "clkin";
+ compatible = "adi,adf4371";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ clocks = <&adf4371_clkin>;
+ clock-names = "clkin";
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,adf4350.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,adf4350.yaml
index d7f20b8518e0..d1d1311332f8 100644
--- a/Documentation/devicetree/bindings/iio/frequency/adi,adf4350.yaml
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,adf4350.yaml
@@ -28,6 +28,12 @@ properties:
clock-names:
const: clkin
+ '#clock-cells':
+ const: 0
+
+ clock-output-names:
+ maxItems: 1
+
gpios:
maxItems: 1
description: Lock detect GPIO.
@@ -160,13 +166,16 @@ properties:
2: +2dBm
3: +5dBm
-additionalProperties: false
-
required:
- compatible
- reg
- clocks
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
spi {
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,adf4377.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,adf4377.yaml
new file mode 100644
index 000000000000..5f950ee9aec7
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,adf4377.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/frequency/adi,adf4377.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADF4377 Microwave Wideband Synthesizer with Integrated VCO
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+ - Dragos Bogdan <dragos.bogdan@analog.com>
+
+description: |
+ The ADF4377 is a high performance, ultralow jitter, dual output integer-N
+ phased locked loop (PLL) with integrated voltage controlled oscillator (VCO)
+ ideally suited for data converter and mixed signal front end (MxFE) clock
+ applications.
+
+ https://www.analog.com/en/products/adf4377.html
+ https://www.analog.com/en/products/adf4378.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adf4377
+ - adi,adf4378
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 10000000
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ description:
+ External clock that provides reference input frequency.
+ items:
+ - const: ref_in
+
+ chip-enable-gpios:
+ description:
+ GPIO that controls the Chip Enable Pin.
+ maxItems: 1
+
+ clk1-enable-gpios:
+ description:
+ GPIO that controls the Enable Clock 1 Output Buffer Pin.
+ maxItems: 1
+
+ clk2-enable-gpios:
+ description:
+ GPIO that controls the Enable Clock 2 Output Buffer Pin.
+ maxItems: 1
+
+ adi,muxout-select:
+ description:
+ On chip multiplexer output selection.
+ high_z - MUXOUT Pin set to high-Z.
+ lock_detect - MUXOUT Pin set to lock detector output.
+ muxout_low - MUXOUT Pin set to low.
+ f_div_rclk_2 - MUXOUT Pin set to fDIV_RCLK/2.
+ f_div_nclk_2 - MUXOUT Pin set to fDIV_NCLK/2.
+ muxout_high - MUXOUT Pin set to high.
+ enum: [high_z, lock_detect, muxout_low, f_div_rclk_2, f_div_nclk_2, muxout_high]
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adf4378
+ then:
+ properties:
+ clk2-enable-gpios: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ frequency@0 {
+ compatible = "adi,adf4377";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ clocks = <&adf4377_ref_in>;
+ clock-names = "ref_in";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml
new file mode 100644
index 000000000000..2bcf4bbc12e4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2024 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/frequency/adi,admfm2000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADMFM2000 Dual Microwave Down Converter
+
+maintainers:
+ - Kim Seer Paller <kimseer.paller@analog.com>
+
+description:
+ Dual microwave down converter module with input RF and LO frequency ranges
+ from 0.5 to 32 GHz and an output IF frequency range from 0.1 to 8 GHz.
+ It consists of a LNA, mixer, IF filter, DSA, and IF amplifier for each down
+ conversion path.
+
+properties:
+ compatible:
+ enum:
+ - adi,admfm2000
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^channel@[0-1]$":
+ type: object
+ description: Represents a channel of the device.
+
+ additionalProperties: false
+
+ properties:
+ reg:
+ description:
+ The channel number.
+ minimum: 0
+ maximum: 1
+
+ adi,mixer-mode:
+ description:
+ Enable mixer mode for the channel. It downconverts RF between 5 GHz
+ and 32 GHz to IF between 0.5 GHz and 8 GHz. If not present, the channel
+ is in direct IF mode which bypasses the mixer and downconverts RF
+ between 2 GHz and 8 GHz to IF between 0.5 GHz and 8 GHz.
+ type: boolean
+
+ switch-gpios:
+ description: |
+ GPIOs to select the RF path for the channel. The same state of CTRL-A
+ and CTRL-B GPIOs is not permitted.
+ CTRL-A CTRL-B CH1 Status CH2 Status
+ 1 0 Direct IF mode Mixer mode
+ 0 1 Mixer mode Direct IF mode
+
+ items:
+ - description: CTRL-A GPIO
+ - description: CTRL-B GPIO
+
+ attenuation-gpios:
+ description: |
+ Choice of attenuation:
+ DSA-V4 DSA-V3 DSA-V2 DSA-V1 DSA-V0
+ 1 1 1 1 1 0 dB
+ 1 1 1 1 0 -1 dB
+ 1 1 1 0 1 -2 dB
+ 1 1 0 1 1 -4 dB
+ 1 0 1 1 1 -8 dB
+ 0 1 1 1 1 -16 dB
+ 0 0 0 0 0 -31 dB
+
+ items:
+ - description: DSA-V0 GPIO
+ - description: DSA-V1 GPIO
+ - description: DSA-V2 GPIO
+ - description: DSA-V3 GPIO
+ - description: DSA-V4 GPIO
+
+ required:
+ - reg
+ - switch-gpios
+ - attenuation-gpios
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ converter {
+ compatible = "adi,admfm2000";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ switch-gpios = <&gpio 1 GPIO_ACTIVE_LOW>,
+ <&gpio 2 GPIO_ACTIVE_HIGH>;
+
+ attenuation-gpios = <&gpio 17 GPIO_ACTIVE_LOW>,
+ <&gpio 22 GPIO_ACTIVE_LOW>,
+ <&gpio 23 GPIO_ACTIVE_LOW>,
+ <&gpio 24 GPIO_ACTIVE_LOW>,
+ <&gpio 25 GPIO_ACTIVE_LOW>;
+ };
+
+ channel@1 {
+ reg = <1>;
+ adi,mixer-mode;
+ switch-gpios = <&gpio 3 GPIO_ACTIVE_LOW>,
+ <&gpio 4 GPIO_ACTIVE_HIGH>;
+
+ attenuation-gpios = <&gpio 0 GPIO_ACTIVE_LOW>,
+ <&gpio 5 GPIO_ACTIVE_LOW>,
+ <&gpio 6 GPIO_ACTIVE_LOW>,
+ <&gpio 16 GPIO_ACTIVE_LOW>,
+ <&gpio 26 GPIO_ACTIVE_LOW>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml
new file mode 100644
index 000000000000..f2eb2287ed9e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,admv1013.yaml
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/frequency/adi,admv1013.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADMV1013 Microwave Upconverter
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Wideband, microwave upconverter optimized for point to point microwave
+ radio designs operating in the 24 GHz to 44 GHz frequency range.
+
+ https://www.analog.com/en/products/admv1013.html
+
+properties:
+ compatible:
+ enum:
+ - adi,admv1013
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 1000000
+
+ clocks:
+ description:
+ Definition of the external clock.
+ minItems: 1
+
+ clock-names:
+ items:
+ - const: lo_in
+
+ vcm-supply:
+ description:
+ Analog voltage regulator.
+
+ vcc-drv-supply:
+ description:
+ RF Driver voltage regulator.
+
+ vcc2-drv-supply:
+ description:
+ RF predriver voltage regulator.
+
+ vcc-vva-supply:
+ description:
+ VVA Control Circuit voltage regulator.
+
+ vcc-amp1-supply:
+ description:
+ RF Amplifier 1 voltage regulator.
+
+ vcc-amp2-supply:
+ description:
+ RF Amplifier 2 voltage regulator.
+
+ vcc-env-supply:
+ description:
+ Envelope Detector voltage regulator.
+
+ vcc-bg-supply:
+ description:
+ Mixer Chip Band Gap Circuit voltage regulator.
+
+ vcc-bg2-supply:
+ description:
+ VGA Chip Band Gap Circuit voltage regulator.
+
+ vcc-mixer-supply:
+ description:
+ Mixer voltage regulator.
+
+ vcc-quad-supply:
+ description:
+ Quadruppler voltage regulator.
+
+ adi,detector-enable:
+ description:
+ Enable the Envelope Detector available at output pins VENV_P and
+ VENV_N. Disable to reduce power consumption.
+ type: boolean
+
+ adi,input-mode:
+ description:
+ Select the input mode.
+ iq - in-phase quadrature (I/Q) input
+ if - complex intermediate frequency (IF) input
+ enum: [iq, if]
+
+ adi,quad-se-mode:
+ description:
+ Switch the LO path from differential to single-ended operation.
+ se-neg - Single-Ended Mode, Negative Side Disabled.
+ se-pos - Single-Ended Mode, Positive Side Disabled.
+ diff - Differential Mode.
+ enum: [se-neg, se-pos, diff]
+
+ '#clock-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - vcm-supply
+ - vcc-drv-supply
+ - vcc2-drv-supply
+ - vcc-vva-supply
+ - vcc-amp1-supply
+ - vcc-amp2-supply
+ - vcc-env-supply
+ - vcc-bg-supply
+ - vcc-bg2-supply
+ - vcc-mixer-supply
+ - vcc-quad-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ admv1013@0{
+ compatible = "adi,admv1013";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ clocks = <&admv1013_lo>;
+ clock-names = "lo_in";
+ vcm-supply = <&vcm>;
+ vcc-drv-supply = <&vcc_drv>;
+ vcc2-drv-supply = <&vcc2_drv>;
+ vcc-vva-supply = <&vcc_vva>;
+ vcc-amp1-supply = <&vcc_amp1>;
+ vcc-amp2-supply = <&vcc_amp2>;
+ vcc-env-supply = <&vcc_env>;
+ vcc-bg-supply = <&vcc_bg>;
+ vcc-bg2-supply = <&vcc_bg2>;
+ vcc-mixer-supply = <&vcc_mixer>;
+ vcc-quad-supply = <&vcc_quad>;
+ adi,quad-se-mode = "diff";
+ adi,detector-enable;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml
new file mode 100644
index 000000000000..39cc63a11762
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,admv1014.yaml
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/frequency/adi,admv1014.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADMV1014 Microwave Downconverter
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Wideband, microwave downconverter optimized for point to point microwave
+ radio designs operating in the 24 GHz to 44 GHz frequency range.
+
+ https://www.analog.com/en/products/admv1014.html
+
+properties:
+ compatible:
+ enum:
+ - adi,admv1014
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 1000000
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: lo_in
+ description:
+ External clock that provides the Local Oscillator input.
+
+ vcm-supply:
+ description:
+ Common-mode voltage regulator.
+
+ vcc-if-bb-supply:
+ description:
+ BB and IF supply voltage regulator.
+
+ vcc-vga-supply:
+ description:
+ RF Amplifier supply voltage regulator.
+
+ vcc-vva-supply:
+ description:
+ VVA Control Circuit supply voltage regulator.
+
+ vcc-lna-3p3-supply:
+ description:
+ Low Noise Amplifier 3.3V supply voltage regulator.
+
+ vcc-lna-1p5-supply:
+ description:
+ Low Noise Amplifier 1.5V supply voltage regulator.
+
+ vcc-bg-supply:
+ description:
+ Band Gap Circuit supply voltage regulator.
+
+ vcc-quad-supply:
+ description:
+ Quadruple supply voltage regulator.
+
+ vcc-mixer-supply:
+ description:
+ Mixer supply voltage regulator.
+
+ adi,input-mode:
+ description:
+ Select the input mode.
+ iq - in-phase quadrature (I/Q) input
+ if - complex intermediate frequency (IF) input
+ enum: [iq, if]
+
+ adi,detector-enable:
+ description:
+ Digital Rx Detector Enable. The Square Law Detector output is
+ available at output pin VDET.
+ type: boolean
+
+ adi,p1db-compensation-enable:
+ description:
+ Turn on bits to optimize P1dB.
+ type: boolean
+
+ adi,quad-se-mode:
+ description:
+ Switch the LO path from differential to single-ended operation.
+ se-neg - Single-Ended Mode, Negative Side Disabled.
+ se-pos - Single-Ended Mode, Positive Side Disabled.
+ diff - Differential Mode.
+ enum: [se-neg, se-pos, diff]
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - vcm-supply
+ - vcc-if-bb-supply
+ - vcc-vga-supply
+ - vcc-vva-supply
+ - vcc-lna-3p3-supply
+ - vcc-lna-1p5-supply
+ - vcc-bg-supply
+ - vcc-quad-supply
+ - vcc-mixer-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ converter@0 {
+ compatible = "adi,admv1014";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ clocks = <&admv1014_lo>;
+ clock-names = "lo_in";
+ vcm-supply = <&vcm>;
+ vcc-if-bb-supply = <&vcc_if_bb>;
+ vcc-vga-supply = <&vcc_vga>;
+ vcc-vva-supply = <&vcc_vva>;
+ vcc-lna-3p3-supply = <&vcc_lna_3p3>;
+ vcc-lna-1p5-supply = <&vcc_lna_1p5>;
+ vcc-bg-supply = <&vcc_bg>;
+ vcc-quad-supply = <&vcc_quad>;
+ vcc-mixer-supply = <&vcc_mixer>;
+ adi,quad-se-mode = "diff";
+ adi,detector-enable;
+ adi,p1db-compensation-enable;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admv4420.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admv4420.yaml
new file mode 100644
index 000000000000..ca40359a3944
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,admv4420.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/frequency/adi,admv4420.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADMV4420 K Band Downconverter
+
+maintainers:
+ - Nuno Sá <nuno.sa@analog.com>
+
+description:
+ The ADMV4420 is a highly integrated, double balanced, active
+ mixer with an integrated fractional-N synthesizer, ideally suited
+ for next generation K band satellite communications
+
+properties:
+ compatible:
+ enum:
+ - adi,admv4420
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 1000000
+
+ adi,lo-freq-khz:
+ description: LO Frequency
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ adi,ref-ext-single-ended-en:
+ description: External reference selected.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ mixer@0 {
+ compatible = "adi,admv4420";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ adi,lo-freq-khz = <16750000>;
+ adi,ref-ext-single-ended-en;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,adrf6780.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,adrf6780.yaml
new file mode 100644
index 000000000000..f11391ab4b62
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/frequency/adi,adrf6780.yaml
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/frequency/adi,adrf6780.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADRF6780 Microwave Upconverter
+
+maintainers:
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+
+description: |
+ Wideband, microwave upconverter optimized for point to point microwave
+ radio designs operating in the 5.9 GHz to 23.6 GHz frequency range.
+
+ https://www.analog.com/en/products/adrf6780.html
+
+properties:
+ compatible:
+ enum:
+ - adi,adrf6780
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 1000000
+
+ clocks:
+ description:
+ Definition of the external clock.
+ minItems: 1
+
+ clock-names:
+ items:
+ - const: lo_in
+
+ clock-output-names:
+ maxItems: 1
+
+ adi,vga-buff-en:
+ description:
+ RF Variable Gain Amplifier Buffer Enable. Gain is controlled by
+ the voltage on the VATT pin.
+ type: boolean
+
+ adi,lo-buff-en:
+ description:
+ Local Oscillator Amplifier Enable. Disable to put the part in
+ a power down state.
+ type: boolean
+
+ adi,if-mode-en:
+ description:
+ Intermediate Frequency Mode Enable. Either IF Mode or I/Q Mode
+ can be enabled at a time.
+ type: boolean
+
+ adi,iq-mode-en:
+ description:
+ I/Q Mode Enable. Either IF Mode or I/Q Mode can be enabled at a
+ time.
+ type: boolean
+
+ adi,lo-x2-en:
+ description:
+ Double the Local Oscillator output frequency from the Local
+ Oscillator Input Frequency. Either LOx1 or LOx2 can be enabled
+ at a time.
+ type: boolean
+
+ adi,lo-ppf-en:
+ description:
+ Local Oscillator input frequency equal to the Local Oscillator
+ output frequency (LO x1). Either LOx1 or LOx2 can be enabled
+ at a time.
+ type: boolean
+
+ adi,lo-en:
+ description:
+ Enable additional cirtuitry in the LO chain. Disable to put the
+ part in a power down state.
+ type: boolean
+
+ adi,uc-bias-en:
+ description:
+ Enable all bias circuitry thourghout the entire part.
+ Disable to put the part in a power down state.
+ type: boolean
+
+ adi,lo-sideband:
+ description:
+ Switch to the Lower LO Sideband. By default the Upper LO
+ sideband is enabled.
+ type: boolean
+
+ adi,vdet-out-en:
+ description:
+ VDET Output Select Enable. Expose the RF detector output to the
+ VDET external pin.
+ type: boolean
+
+ '#clock-cells':
+ const: 0
+
+dependencies:
+ adi,lo-x2-en: [ "adi,lo-en" ]
+ adi,lo-ppf-en: [ "adi,lo-en" ]
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ adrf6780@0 {
+ compatible = "adi,adrf6780";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ clocks = <&adrf6780_lo>;
+ clock-names = "lo_in";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml b/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml
index 662ec59ca0af..3d94dd4612c4 100644
--- a/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml
+++ b/Documentation/devicetree/bindings/iio/gyroscope/adi,adxrs290.yaml
@@ -38,7 +38,10 @@ required:
- spi-cpol
- spi-cpha
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -47,13 +50,13 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
gyro@0 {
- compatible = "adi,adxrs290";
- reg = <0>;
- spi-max-frequency = <5000000>;
- spi-cpol;
- spi-cpha;
- interrupt-parent = <&gpio>;
- interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ compatible = "adi,adxrs290";
+ reg = <0>;
+ spi-max-frequency = <5000000>;
+ spi-cpol;
+ spi-cpha;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml b/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml
index b6bbc312a7cf..3c6fe74af0b8 100644
--- a/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml
+++ b/Documentation/devicetree/bindings/iio/gyroscope/bosch,bmg160.yaml
@@ -22,16 +22,24 @@ properties:
vdd-supply: true
vddio-supply: true
+ spi-max-frequency:
+ maximum: 10000000
+
interrupts:
minItems: 1
+ maxItems: 2
description:
Should be configured with type IRQ_TYPE_EDGE_RISING.
+ If two interrupts are provided, expected order is INT1 and INT2.
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/gyroscope/invensense,itg3200.yaml b/Documentation/devicetree/bindings/iio/gyroscope/invensense,itg3200.yaml
new file mode 100644
index 000000000000..4d8abf8ac2c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/gyroscope/invensense,itg3200.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/gyroscope/invensense,itg3200.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Invensense ITG-3200 Gyroscope
+
+maintainers:
+ - Jonathan Cameron <jic23@kernel.org>
+
+description: |
+ Triple-axis, digital output gyroscope with a three 16-bit analog-to-digital
+ converters (ADCs) for digitizing the gyro outputs, a user-selectable internal
+ low-pass filter bandwidth, and a Fast-Mode I2C.
+
+properties:
+ compatible:
+ const: invensense,itg3200
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ vlogic-supply: true
+
+ interrupts:
+ maxItems: 1
+
+ mount-matrix:
+ description: an optional 3x3 mounting rotation matrix.
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: ext_clock
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ gyroscope@68 {
+ compatible = "invensense,itg3200";
+ reg = <0x68>;
+ interrupt-parent = <&gpio2>;
+ interrupts = <24 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml
index 7e2accc3d5ce..f3242dc0e7e6 100644
--- a/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml
+++ b/Documentation/devicetree/bindings/iio/gyroscope/invensense,mpu3050.yaml
@@ -21,7 +21,7 @@ properties:
vlogic-supply: true
interrupts:
- minItems: 1
+ maxItems: 1
description:
Interrupt mapping for the trigger interrupt from the internal oscillator.
@@ -61,7 +61,7 @@ examples:
#size-cells = <0>;
magnetometer@c {
- compatible = "ak,ak8975";
+ compatible = "asahi-kasei,ak8975";
reg = <0x0c>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml
index 3f57a1b813e6..297d519d68f2 100644
--- a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml
+++ b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.yaml
@@ -56,40 +56,43 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
gyroscope@20 {
- compatible = "nxp,fxas21002c";
- reg = <0x20>;
+ compatible = "nxp,fxas21002c";
+ reg = <0x20>;
- vdd-supply = <&reg_peri_3p15v>;
- vddio-supply = <&reg_peri_3p15v>;
+ vdd-supply = <&reg_peri_3p15v>;
+ vddio-supply = <&reg_peri_3p15v>;
- interrupt-parent = <&gpio1>;
- interrupts = <7 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "INT1";
+ interrupt-parent = <&gpio1>;
+ interrupts = <7 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
};
};
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
gyroscope@0 {
- compatible = "nxp,fxas21002c";
- reg = <0x0>;
+ compatible = "nxp,fxas21002c";
+ reg = <0x0>;
- spi-max-frequency = <2000000>;
+ spi-max-frequency = <2000000>;
- interrupt-parent = <&gpio2>;
- interrupts = <7 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "INT2";
+ interrupt-parent = <&gpio2>;
+ interrupts = <7 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT2";
};
};
diff --git a/Documentation/devicetree/bindings/iio/health/maxim,max30100.yaml b/Documentation/devicetree/bindings/iio/health/maxim,max30100.yaml
index 967778fb0ce8..d4753c85ecc3 100644
--- a/Documentation/devicetree/bindings/iio/health/maxim,max30100.yaml
+++ b/Documentation/devicetree/bindings/iio/health/maxim,max30100.yaml
@@ -27,6 +27,14 @@ properties:
LED current whilst the engine is running. First indexed value is
the configuration for the RED LED, and second value is for the IR LED.
+ maxim,pulse-width-us:
+ description: |
+ LED pulse width in microseconds. Appropriate pulse width depends on
+ factors such as optical window absorption, LED-to-sensor distance,
+ and expected reflectivity of the skin or contact surface.
+ enum: [200, 400, 800, 1600]
+ default: 1600
+
additionalProperties: false
required:
diff --git a/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml b/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml
index c13c10c8d65d..205d352ab467 100644
--- a/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml
+++ b/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml
@@ -4,16 +4,20 @@
$id: http://devicetree.org/schemas/iio/health/maxim,max30102.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Maxim MAX30102 heart rate and pulse oximeter and MAX30105 particle-sensor
+title: Maxim MAX30101/2 heart rate and pulse oximeter and MAX30105 particle-sensor
maintainers:
- Matt Ranostay <matt.ranostay@konsulko.com>
properties:
compatible:
- enum:
- - maxim,max30102
- - maxim,max30105
+ oneOf:
+ - enum:
+ - maxim,max30102
+ - maxim,max30105
+ - items:
+ - const: maxim,max30101
+ - const: maxim,max30105
reg:
maxItems: 1
@@ -42,7 +46,7 @@ allOf:
properties:
compatible:
contains:
- const: maxim,max30100
+ const: maxim,max30102
then:
properties:
maxim,green-led-current-microamp: false
diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml
index d861526c5c42..5b6cde86b5a5 100644
--- a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml
+++ b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml
@@ -23,16 +23,18 @@ properties:
maxItems: 1
description: Connected to ADC_RDY pin.
- reset-gpios: true
-
- spi-max-frequency: true
-
-additionalProperties: false
+ reset-gpios:
+ maxItems: 1
required:
- compatible
- reg
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
#include <dt-bindings/gpio/gpio.h>
@@ -41,7 +43,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- heart_mon@0 {
+ heart-mon@0 {
compatible = "ti,afe4403";
reg = <0>;
spi-max-frequency = <10000000>;
diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml
index c0e815d9999e..167d10bd60af 100644
--- a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml
+++ b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml
@@ -23,7 +23,8 @@ properties:
maxItems: 1
description: Connected to ADC_RDY pin.
- reset-gpios: true
+ reset-gpios:
+ maxItems: 1
additionalProperties: false
@@ -39,7 +40,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- heart_mon@58 {
+ heart-mon@58 {
compatible = "ti,afe4404";
reg = <0x58>;
tx-supply = <&vbat>;
diff --git a/Documentation/devicetree/bindings/iio/humidity/dht11.yaml b/Documentation/devicetree/bindings/iio/humidity/dht11.yaml
index 2247481d0203..0103f4238942 100644
--- a/Documentation/devicetree/bindings/iio/humidity/dht11.yaml
+++ b/Documentation/devicetree/bindings/iio/humidity/dht11.yaml
@@ -34,7 +34,7 @@ additionalProperties: false
examples:
- |
- humidity_sensor {
+ humidity-sensor {
compatible = "dht11";
gpios = <&gpio0 6 0>;
};
diff --git a/Documentation/devicetree/bindings/iio/humidity/sciosense,ens210.yaml b/Documentation/devicetree/bindings/iio/humidity/sciosense,ens210.yaml
new file mode 100644
index 000000000000..1e25cf781cf1
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/humidity/sciosense,ens210.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/humidity/sciosense,ens210.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ScioSense ENS210 temperature and humidity sensor
+
+maintainers:
+ - Joshua Felmeden <jfelmeden@thegoodpenguin.co.uk>
+
+description: |
+ Temperature and Humidity sensor.
+
+ Datasheet:
+ https://www.sciosense.com/wp-content/uploads/2024/04/ENS21x-Datasheet.pdf
+ https://www.sciosense.com/wp-content/uploads/2023/12/ENS210-Datasheet.pdf
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - sciosense,ens210a
+ - sciosense,ens211
+ - sciosense,ens212
+ - sciosense,ens213a
+ - sciosense,ens215
+ - const: sciosense,ens210
+ - const: sciosense,ens210
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@43 {
+ compatible = "sciosense,ens210";
+ reg = <0x43>;
+ };
+ };
+...
+
diff --git a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml
index 88384b69f917..e3eca8917517 100644
--- a/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml
+++ b/Documentation/devicetree/bindings/iio/humidity/ti,hdc2010.yaml
@@ -10,7 +10,7 @@ maintainers:
- Eugene Zaikonnikov <ez@norophonic.com>
description: |
- Relative humidity and tempereature sensors on I2C bus
+ Relative humidity and temperature sensors on I2C bus
Datasheets are available at:
http://www.ti.com/product/HDC2010/datasheet
@@ -27,6 +27,9 @@ properties:
reg:
maxItems: 1
+ interrupts:
+ maxItems: 1
+
required:
- compatible
- reg
@@ -35,12 +38,12 @@ additionalProperties: false
examples:
- |
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- humidity@40 {
- compatible = "ti,hdc2010";
- reg = <0x40>;
- };
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ humidity@40 {
+ compatible = "ti,hdc2010";
+ reg = <0x40>;
+ };
};
diff --git a/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml b/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml
new file mode 100644
index 000000000000..b375d307513f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/humidity/ti,hdc3020.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HDC3020/HDC3021/HDC3022 humidity and temperature iio sensors
+
+maintainers:
+ - Li peiyu <579lpy@gmail.com>
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+description:
+ https://www.ti.com/lit/ds/symlink/hdc3020.pdf
+
+ The HDC302x is an integrated capacitive based relative humidity (RH)
+ and temperature sensor.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - ti,hdc3021
+ - ti,hdc3022
+ - const: ti,hdc3020
+ - const: ti,hdc3020
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ humidity-sensor@47 {
+ compatible = "ti,hdc3021", "ti,hdc3020";
+ reg = <0x47>;
+ vdd-supply = <&vcc_3v3>;
+ interrupt-parent = <&gpio3>;
+ interrupts = <23 IRQ_TYPE_EDGE_RISING>;
+ reset-gpios = <&gpio3 27 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml
index 340be256f283..3a725ece7ec4 100644
--- a/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16460.yaml
@@ -25,7 +25,9 @@ properties:
spi-cpol: true
- spi-max-frequency: true
+ spi-cs-inactive-delay-ns:
+ minimum: 16000
+ default: 16000
interrupts:
maxItems: 1
@@ -35,13 +37,15 @@ required:
- reg
- interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml
index a7574210175a..9d185f7bfdcb 100644
--- a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml
@@ -30,12 +30,19 @@ properties:
- adi,adis16467-2
- adi,adis16467-3
- adi,adis16500
+ - adi,adis16501
- adi,adis16505-1
- adi,adis16505-2
- adi,adis16505-3
- adi,adis16507-1
- adi,adis16507-2
- adi,adis16507-3
+ - adi,adis16575-2
+ - adi,adis16575-3
+ - adi,adis16576-2
+ - adi,adis16576-3
+ - adi,adis16577-2
+ - adi,adis16577-3
reg:
maxItems: 1
@@ -47,6 +54,10 @@ properties:
spi-max-frequency:
maximum: 2000000
+ spi-cs-inactive-delay-ns:
+ minimum: 16000
+ default: 16000
+
interrupts:
maxItems: 1
@@ -79,18 +90,26 @@ required:
- spi-cpol
allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
- if:
properties:
compatible:
contains:
enum:
- adi,adis16500
+ - adi,adis16501
- adi,adis16505-1
- adi,adis16505-2
- adi,adis16505-3
- adi,adis16507-1
- adi,adis16507-2
- adi,adis16507-3
+ - adi,adis16575-2
+ - adi,adis16575-3
+ - adi,adis16576-2
+ - adi,adis16576-3
+ - adi,adis16577-2
+ - adi,adis16577-3
then:
properties:
@@ -107,23 +126,40 @@ allOf:
dependencies:
adi,sync-mode: [ clocks ]
-additionalProperties: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,adis16575-2
+ - adi,adis16575-3
+ - adi,adis16576-2
+ - adi,adis16576-3
+ - adi,adis16577-2
+ - adi,adis16577-3
+
+ then:
+ properties:
+ spi-max-frequency:
+ maximum: 15000000
+
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
spi {
- #address-cells = <1>;
- #size-cells = <0>;
-
- adis16475: adis16475-3@0 {
- compatible = "adi,adis16475-3";
- reg = <0>;
- spi-cpha;
- spi-cpol;
- spi-max-frequency = <2000000>;
- interrupts = <4 IRQ_TYPE_EDGE_RISING>;
- interrupt-parent = <&gpio>;
- };
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ adis16475: adis16475-3@0 {
+ compatible = "adi,adis16475-3";
+ reg = <0>;
+ spi-cpha;
+ spi-cpol;
+ spi-max-frequency = <2000000>;
+ interrupts = <4 IRQ_TYPE_EDGE_RISING>;
+ interrupt-parent = <&gpio>;
+ };
};
...
diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml
index 5dbe24be9925..43ecf46e9c20 100644
--- a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml
@@ -7,22 +7,35 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices ADIS16480 and similar IMUs
maintainers:
- - Alexandru Ardelean <alexandru.ardelean@analog.com>
+ - Marcelo Schmitt <marcelo.schmitt@analog.com>
+ - Nuno Sá <nuno.sa@analog.com>
properties:
compatible:
- enum:
- - adi,adis16375
- - adi,adis16480
- - adi,adis16485
- - adi,adis16488
- - adi,adis16490
- - adi,adis16495-1
- - adi,adis16495-2
- - adi,adis16495-3
- - adi,adis16497-1
- - adi,adis16497-2
- - adi,adis16497-3
+ oneOf:
+ - enum:
+ - adi,adis16375
+ - adi,adis16480
+ - adi,adis16485
+ - adi,adis16486
+ - adi,adis16488
+ - adi,adis16489
+ - adi,adis16490
+ - adi,adis16495-1
+ - adi,adis16495-2
+ - adi,adis16495-3
+ - adi,adis16497-1
+ - adi,adis16497-2
+ - adi,adis16497-3
+ - adi,adis16545-1
+ - adi,adis16545-2
+ - adi,adis16545-3
+ - adi,adis16547-1
+ - adi,adis16547-2
+ - adi,adis16547-3
+ - items:
+ - const: adi,adis16487
+ - const: adi,adis16485
reg:
maxItems: 1
@@ -47,8 +60,6 @@ properties:
- DIO3
- DIO4
- spi-max-frequency: true
-
spi-cpha: true
spi-cpol: true
@@ -96,8 +107,6 @@ properties:
- DIO3
- DIO4
-additionalProperties: false
-
required:
- compatible
- reg
@@ -106,6 +115,11 @@ required:
- spi-cpol
- spi-max-frequency
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16550.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16550.yaml
new file mode 100644
index 000000000000..cf5324de4fd6
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16550.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/adi,adis16550.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADIS16550 and similar IMUs
+
+maintainers:
+ - Nuno Sa <nuno.sa@analog.com>
+ - Ramona Gradinariu <ramona.gradinariu@analog.com>
+ - Antoniu Miclaus <antoniu.miclaus@analog.com>
+ - Robert Budai <robert.budai@analog.com>
+
+properties:
+ compatible:
+ enum:
+ - adi,adis16550
+
+ reg:
+ maxItems: 1
+
+ spi-cpha: true
+
+ spi-cpol: true
+
+ spi-max-frequency:
+ maximum: 15000000
+
+ vdd-supply: true
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ description:
+ Active low RESET pin.
+ maxItems: 1
+
+ clocks:
+ description: If not provided, then the internal clock is used.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - spi-cpha
+ - spi-cpol
+ - spi-max-frequency
+ - vdd-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ imu@0 {
+ compatible = "adi,adis16550";
+ reg = <0>;
+ spi-max-frequency = <15000000>;
+ spi-cpol;
+ spi-cpha;
+ vdd-supply = <&vdd>;
+ interrupts = <4 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml
index 6e73cd889b5c..2cf8a0c7eb4c 100644
--- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml
@@ -16,7 +16,11 @@ description: |
properties:
compatible:
- const: bosch,bmi160
+ oneOf:
+ - const: bosch,bmi160
+ - items:
+ - const: bosch,bmi120
+ - const: bosch,bmi160
reg:
maxItems: 1
@@ -33,6 +37,7 @@ properties:
to "INT2" if INT2 pin should be used instead
drive-open-drain:
+ type: boolean
description: |
set if the specified interrupt pin should be configured as
open drain. If not set, defaults to push-pull.
@@ -46,13 +51,14 @@ properties:
mount-matrix:
description: an optional 3x3 mounting rotation matrix
- spi-max-frequency: true
-
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -63,16 +69,16 @@ examples:
#size-cells = <0>;
bmi160@68 {
- compatible = "bosch,bmi160";
- reg = <0x68>;
- vdd-supply = <&pm8916_l17>;
- vddio-supply = <&pm8916_l6>;
- interrupt-parent = <&gpio4>;
- interrupts = <12 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "INT1";
- mount-matrix = "0", "1", "0",
- "-1", "0", "0",
- "0", "0", "1";
+ compatible = "bosch,bmi160";
+ reg = <0x68>;
+ vdd-supply = <&pm8916_l17>;
+ vddio-supply = <&pm8916_l6>;
+ interrupt-parent = <&gpio4>;
+ interrupts = <12 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
+ mount-matrix = "0", "1", "0",
+ "-1", "0", "0",
+ "0", "0", "1";
};
};
- |
@@ -83,11 +89,11 @@ examples:
#size-cells = <0>;
bmi160@0 {
- compatible = "bosch,bmi160";
- reg = <0>;
- spi-max-frequency = <10000000>;
- interrupt-parent = <&gpio2>;
- interrupts = <12 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "INT2";
+ compatible = "bosch,bmi160";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ interrupt-parent = <&gpio2>;
+ interrupts = <12 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT2";
};
};
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml
new file mode 100644
index 000000000000..860a6c1fea3c
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/bosch,bmi270.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bosch BMI270 6-Axis IMU
+
+maintainers:
+ - Alex Lanzano <lanzano.alex@gmail.com>
+
+description: |
+ BMI270 is a 6-axis inertial measurement unit that can measure acceleration and
+ angular velocity. The sensor also supports configurable interrupt events such
+ as motion, step counter, and wrist motion gestures. The sensor can communicate
+ I2C or SPI.
+ https://www.bosch-sensortec.com/products/motion-sensors/imus/bmi270/
+
+properties:
+ compatible:
+ enum:
+ - bosch,bmi260
+ - bosch,bmi270
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
+
+ drive-open-drain:
+ type: boolean
+ description:
+ set if the specified interrupt pins should be configured as
+ open drain. If not set, defaults to push-pull.
+
+ mount-matrix:
+ description:
+ an optional 3x3 mounting rotation matrix.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vddio-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@68 {
+ compatible = "bosch,bmi270";
+ reg = <0x68>;
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <16 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml
new file mode 100644
index 000000000000..7bf8294a8f2e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/bosch,bmi323.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bosch BMI323 6-Axis IMU
+
+maintainers:
+ - Jagath Jog J <jagathjog1996@gmail.com>
+
+description:
+ BMI323 is a 6-axis inertial measurement unit that supports acceleration and
+ gyroscopic measurements with hardware fifo buffering. Sensor also provides
+ events information such as motion, steps, orientation, single and double
+ tap detection.
+
+properties:
+ compatible:
+ const: bosch,bmi323
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
+
+ drive-open-drain:
+ type: boolean
+ description:
+ set if the specified interrupt pin should be configured as
+ open drain. If not set, defaults to push-pull.
+
+ mount-matrix:
+ description:
+ an optional 3x3 mounting rotation matrix.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vddio-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ // Example for I2C
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@68 {
+ compatible = "bosch,bmi323";
+ reg = <0x68>;
+ vddio-supply = <&vddio>;
+ vdd-supply = <&vdd>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <29 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bno055.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bno055.yaml
new file mode 100644
index 000000000000..e0d06db161a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,bno055.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/bosch,bno055.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bosch BNO055
+
+maintainers:
+ - Andrea Merello <andrea.merello@iit.it>
+
+description: |
+ Inertial Measurement Unit with Accelerometer, Gyroscope, Magnetometer and
+ internal MCU for sensor fusion
+ https://www.bosch-sensortec.com/products/smart-sensors/bno055/
+
+properties:
+ compatible:
+ enum:
+ - bosch,bno055
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ serial {
+ imu {
+ compatible = "bosch,bno055";
+ reset-gpios = <&gpio0 54 GPIO_ACTIVE_LOW>;
+ clocks = <&imu_clk>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@28 {
+ compatible = "bosch,bno055";
+ reg = <0x28>;
+ reset-gpios = <&gpio0 54 GPIO_ACTIVE_LOW>;
+ clocks = <&imu_clk>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,smi240.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,smi240.yaml
new file mode 100644
index 000000000000..58f1411728f6
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,smi240.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/bosch,smi240.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bosch smi240 imu
+
+maintainers:
+ - Jianping Shen <Jianping.Shen@de.bosch.com>
+
+description:
+ Inertial Measurement Unit with Accelerometer and Gyroscope
+ with a measurement range of +/-300°/s and up to 16g.
+ https://www.bosch-semiconductors.com/mems-sensors/highly-automated-driving/smi240/
+
+properties:
+ compatible:
+ const: bosch,smi240
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vddio-supply
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@0 {
+ compatible = "bosch,smi240";
+ reg = <0>;
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
+ spi-max-frequency = <10000000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,smi330.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,smi330.yaml
new file mode 100644
index 000000000000..0270ca456d2b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/bosch,smi330.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/bosch,smi330.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bosch SMI330 6-Axis IMU
+
+maintainers:
+ - Stefan Gutmann <stefam.gutmann@de.bosch.com>
+
+description:
+ SMI330 is a 6-axis inertial measurement unit that supports acceleration and
+ gyroscopic measurements with hardware fifo buffering. Sensor also provides
+ events information such as motion, no-motion and tilt detection.
+
+properties:
+ compatible:
+ const: bosch,smi330
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: provide VDD power to the sensor.
+
+ vddio-supply:
+ description: provide VDD IO power to the sensor.
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
+
+ drive-open-drain:
+ type: boolean
+ description:
+ set if the interrupt pin(s) should be configured as
+ open drain. If not set, defaults to push-pull.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ // Example for I2C
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@68 {
+ compatible = "bosch,smi330";
+ reg = <0x68>;
+ vddio-supply = <&vddio>;
+ vdd-supply = <&vdd>;
+ interrupt-parent = <&gpio>;
+ interrupts = <26 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
+ };
+ };
+
+ // Example for SPI
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@0 {
+ compatible = "bosch,smi330";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ interrupt-parent = <&gpio>;
+ interrupts = <26 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml
index 4c1c083d0e92..119e28a833fd 100644
--- a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: InvenSense ICM-426xx Inertial Measurement Unit
maintainers:
- - Jean-Baptiste Maneyrol <jmaneyrol@invensense.com>
+ - Jean-Baptiste Maneyrol <jean-baptiste.maneyrol@tdk.com>
description: |
6-axis MotionTracking device that combines a 3-axis gyroscope and a 3-axis
@@ -31,12 +31,24 @@ properties:
- invensense,icm42602
- invensense,icm42605
- invensense,icm42622
+ - invensense,icm42631
+ - invensense,icm42686
+ - invensense,icm42688
reg:
maxItems: 1
interrupts:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
drive-open-drain:
type: boolean
@@ -47,7 +59,6 @@ properties:
vddio-supply:
description: Regulator that provides power to the bus
- spi-max-frequency: true
spi-cpha: true
spi-cpol: true
@@ -56,41 +67,44 @@ required:
- reg
- interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
icm42605@68 {
- compatible = "invensense,icm42605";
- reg = <0x68>;
- interrupt-parent = <&gpio2>;
- interrupts = <7 IRQ_TYPE_EDGE_FALLING>;
- vdd-supply = <&vdd>;
- vddio-supply = <&vddio>;
+ compatible = "invensense,icm42605";
+ reg = <0x68>;
+ interrupt-parent = <&gpio2>;
+ interrupts = <7 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "INT1";
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
};
};
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
icm42602@0 {
- compatible = "invensense,icm42602";
- reg = <0>;
- spi-max-frequency = <24000000>;
- spi-cpha;
- spi-cpol;
- interrupt-parent = <&gpio1>;
- interrupts = <2 IRQ_TYPE_EDGE_FALLING>;
- vdd-supply = <&vdd>;
- vddio-supply = <&vddio>;
+ compatible = "invensense,icm42602";
+ reg = <0>;
+ spi-max-frequency = <24000000>;
+ spi-cpha;
+ spi-cpol;
+ interrupt-parent = <&gpio1>;
+ interrupts = <2 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "INT1";
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,icm45600.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,icm45600.yaml
new file mode 100644
index 000000000000..e0b78d14420f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/imu/invensense,icm45600.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/imu/invensense,icm45600.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: InvenSense ICM-45600 Inertial Measurement Unit
+
+maintainers:
+ - Remi Buisson <remi.buisson@tdk.com>
+
+description: |
+ 6-axis MotionTracking device that combines a 3-axis gyroscope and a 3-axis
+ accelerometer.
+
+ It has a configurable host interface that supports I3C, I2C and SPI serial
+ communication, features up to 8kB FIFO and 2 programmable interrupts with
+ ultra-low-power wake-on-motion support to minimize system power consumption.
+
+ Other industry-leading features include InvenSense on-chip APEX Motion
+ Processing engine for gesture recognition, activity classification, and
+ pedometer, along with programmable digital filters, and an embedded
+ temperature sensor.
+
+ https://invensense.tdk.com/wp-content/uploads/documentation/DS-000576_ICM-45605.pdf
+
+properties:
+ compatible:
+ enum:
+ - invensense,icm45605
+ - invensense,icm45606
+ - invensense,icm45608
+ - invensense,icm45634
+ - invensense,icm45686
+ - invensense,icm45687
+ - invensense,icm45688p
+ - invensense,icm45689
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - enum: [int1, int2]
+ - const: int2
+ description: Choose chip interrupt pin to be used as interrupt input.
+
+ drive-open-drain:
+ type: boolean
+
+ vdd-supply: true
+
+ vddio-supply: true
+
+ mount-matrix: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vddio-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imu@68 {
+ compatible = "invensense,icm45605";
+ reg = <0x68>;
+ interrupt-parent = <&gpio2>;
+ interrupt-names = "int1";
+ interrupts = <7 IRQ_TYPE_EDGE_RISING>;
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
+ mount-matrix = "0", "-1", "0",
+ "1", "0", "0",
+ "0", "0", "1";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml
index edbc2921aabd..1af0855c33e6 100644
--- a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml
@@ -7,28 +7,41 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: InvenSense MPU-6050 Six-Axis (Gyro + Accelerometer) MEMS MotionTracking Device
maintainers:
- - Jean-Baptiste Maneyrol <jmaneyrol@invensense.com>
+ - Jean-Baptiste Maneyrol <jean-baptiste.maneyrol@tdk.com>
description: |
These devices support both I2C and SPI bus interfaces.
properties:
compatible:
- enum:
- - invensense,iam20680
- - invensense,icm20608
- - invensense,icm20609
- - invensense,icm20689
- - invensense,icm20602
- - invensense,icm20690
- - invensense,mpu6000
- - invensense,mpu6050
- - invensense,mpu6500
- - invensense,mpu6515
- - invensense,mpu6880
- - invensense,mpu9150
- - invensense,mpu9250
- - invensense,mpu9255
+ oneOf:
+ - enum:
+ - invensense,iam20380
+ - invensense,iam20680
+ - invensense,icm20608
+ - invensense,icm20609
+ - invensense,icm20689
+ - invensense,icm20602
+ - invensense,icm20690
+ - invensense,mpu6000
+ - invensense,mpu6050
+ - invensense,mpu6500
+ - invensense,mpu6515
+ - invensense,mpu6880
+ - invensense,mpu9150
+ - invensense,mpu9250
+ - invensense,mpu9255
+ - items:
+ - const: invensense,icm20600
+ - const: invensense,icm20602
+ - items:
+ - const: invensense,icm20608d
+ - const: invensense,icm20608
+ - items:
+ - enum:
+ - invensense,iam20680hp
+ - invensense,iam20680ht
+ - const: invensense,iam20680
reg:
maxItems: 1
@@ -36,13 +49,16 @@ properties:
interrupts:
maxItems: 1
- spi-max-frequency: true
-
vdd-supply: true
vddio-supply: true
mount-matrix: true
+ invensense,level-shifter:
+ type: boolean
+ description: |
+ From ancient platform data struct: false: VLogic, true: VDD
+
i2c-gate:
$ref: /schemas/i2c/i2c-controller.yaml
unevaluatedProperties: false
@@ -50,25 +66,26 @@ properties:
These devices also support an auxiliary i2c bus via an i2c-gate.
allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
- if:
- not:
- properties:
- compatible:
- contains:
- enum:
- - invensense,mpu9150
- - invensense,mpu9250
- - invensense,mpu9255
+ properties:
+ compatible:
+ contains:
+ enum:
+ - invensense,iam20680
+ - invensense,icm20602
+ - invensense,icm20608
+ - invensense,icm20609
+ - invensense,icm20689
then:
properties:
i2c-gate: false
-additionalProperties: false
+unevaluatedProperties: false
required:
- compatible
- reg
- - interrupts
examples:
- |
@@ -95,7 +112,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
magnetometer@c {
- compatible = "ak,ak8975";
+ compatible = "asahi-kasei,ak8975";
reg = <0x0c>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml b/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml
index 479e7065d4eb..2930b3386703 100644
--- a/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/nxp,fxos8700.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale FXOS8700 Inertial Measurement Unit
maintainers:
- - Robert Jones <rjones@gateworks.com>
+ - Jonathan Cameron <jic23@kernel.org>
description: |
Accelerometer and magnetometer combo device with an i2c and SPI interface.
@@ -36,45 +36,44 @@ properties:
drive-open-drain:
type: boolean
- spi-max-frequency: true
-
required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
fxos8700@1e {
- compatible = "nxp,fxos8700";
- reg = <0x1e>;
+ compatible = "nxp,fxos8700";
+ reg = <0x1e>;
- interrupt-parent = <&gpio2>;
- interrupts = <7 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "INT1";
+ interrupt-parent = <&gpio2>;
+ interrupts = <7 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT1";
};
};
- |
- #include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- spi0 {
+ spi {
#address-cells = <1>;
#size-cells = <0>;
fxos8700@0 {
- compatible = "nxp,fxos8700";
- reg = <0>;
+ compatible = "nxp,fxos8700";
+ reg = <0>;
- spi-max-frequency = <1000000>;
- interrupt-parent = <&gpio1>;
- interrupts = <7 IRQ_TYPE_EDGE_RISING>;
- interrupt-names = "INT2";
+ spi-max-frequency = <1000000>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <7 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "INT2";
};
};
diff --git a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml
index d9b3213318fb..c48a96d17f51 100644
--- a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml
+++ b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml
@@ -14,23 +14,43 @@ description:
properties:
compatible:
- enum:
- - st,lsm6ds3
- - st,lsm6ds3h
- - st,lsm6dsl
- - st,lsm6dsm
- - st,ism330dlc
- - st,lsm6dso
- - st,asm330lhh
- - st,lsm6dsox
- - st,lsm6dsr
- - st,lsm6ds3tr-c
- - st,ism330dhcx
- - st,lsm9ds1-imu
- - st,lsm6ds0
- - st,lsm6dsrx
- - st,lsm6dst
- - st,lsm6dsop
+ oneOf:
+ - enum:
+ - st,lsm6ds3
+ - st,lsm6ds3h
+ - st,lsm6dsl
+ - st,lsm6dsm
+ - st,ism330dlc
+ - st,lsm6dso
+ - st,asm330lhh
+ - st,lsm6dsox
+ - st,lsm6dsr
+ - st,lsm6ds3tr-c
+ - st,ism330dhcx
+ - st,lsm9ds1-imu
+ - st,lsm6ds0
+ - st,lsm6dsrx
+ - st,lsm6dst
+ - st,lsm6dsop
+ - st,lsm6dsv
+ - st,lsm6dso16is
+ - items:
+ - enum:
+ - st,asm330lhhx
+ - st,asm330lhhxg1
+ - const: st,lsm6dsr
+ - items:
+ - const: st,lsm6dstx
+ - const: st,lsm6dst
+ - items:
+ - const: st,lsm6dsv16x
+ - const: st,lsm6dsv
+ - items:
+ - const: st,ism330is
+ - const: st,lsm6dso16is
+ - items:
+ - const: st,asm330lhb
+ - const: st,asm330lhh
reg:
maxItems: 1
@@ -41,8 +61,6 @@ properties:
description:
Supports up to 2 interrupt lines via the INT1 and INT2 pins.
- spi-max-frequency: true
-
vdd-supply:
description: if defined provides VDD power to the sensor.
@@ -50,7 +68,7 @@ properties:
description: if defined provides VDD IO power to the sensor.
st,drdy-int-pin:
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description: |
The pin on the package that will be used to signal data ready
enum:
@@ -61,6 +79,13 @@ properties:
type: boolean
description: enable/disable internal i2c controller pullup resistors.
+ st,disable-sensor-hub:
+ type: boolean
+ description:
+ Enable/disable internal i2c controller slave autoprobing at bootstrap.
+ Disable sensor-hub is useful if i2c controller clock/data lines are
+ connected through a pull-up with other chip lines (e.g. SDO/SA0).
+
drive-open-drain:
type: boolean
description:
@@ -70,12 +95,19 @@ properties:
wakeup-source:
$ref: /schemas/types.yaml#/definitions/flag
-additionalProperties: false
+ mount-matrix:
+ description: an optional 3x3 mounting rotation matrix
required:
- compatible
- reg
+allOf:
+ - $ref: /schemas/iio/iio.yaml#
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
diff --git a/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml b/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml
index 0e8cd02759b3..062a038aa0ff 100644
--- a/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml
+++ b/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml
@@ -4,19 +4,22 @@
$id: http://devicetree.org/schemas/iio/light/ams,as73211.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: AMS AS73211 JENCOLOR(R) Digital XYZ Sensor
+title: AMS AS73211 JENCOLOR(R) Digital XYZ Sensor and AMS AS7331 UV Sensor
maintainers:
- Christian Eggers <ceggers@arri.de>
description: |
- XYZ True Color Sensor with I2C Interface
+ AMS AS73211 XYZ True Color Sensor with I2C Interface
https://ams.com/documents/20143/36005/AS73211_DS000556_3-01.pdf/a65474c0-b302-c2fd-e30a-c98df87616df
+ AMS AS7331 UVA, UVB and UVC Sensor with I2C Interface
+ https://ams.com/documents/20143/9106314/AS7331_DS001047_4-00.pdf
properties:
compatible:
enum:
- ams,as73211
+ - ams,as7331
reg:
description:
diff --git a/Documentation/devicetree/bindings/iio/light/avago,apds9300.yaml b/Documentation/devicetree/bindings/iio/light/avago,apds9300.yaml
index 206af44f2c43..b750096530bc 100644
--- a/Documentation/devicetree/bindings/iio/light/avago,apds9300.yaml
+++ b/Documentation/devicetree/bindings/iio/light/avago,apds9300.yaml
@@ -4,17 +4,22 @@
$id: http://devicetree.org/schemas/iio/light/avago,apds9300.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Avago APDS9300 ambient light sensor
+title: Avago Gesture/RGB/ALS/Proximity sensors
maintainers:
- - Jonathan Cameron <jic23@kernel.org>
+ - Subhajit Ghosh <subhajit.ghosh@tweaklogic.com>
description: |
- Datasheet at https://www.avagotech.com/docs/AV02-1077EN
+ Datasheet: https://www.avagotech.com/docs/AV02-1077EN
+ Datasheet: https://www.avagotech.com/docs/AV02-4191EN
+ Datasheet: https://www.avagotech.com/docs/AV02-4755EN
properties:
compatible:
- const: avago,apds9300
+ enum:
+ - avago,apds9300
+ - avago,apds9306
+ - avago,apds9960
reg:
maxItems: 1
@@ -22,6 +27,8 @@ properties:
interrupts:
maxItems: 1
+ vdd-supply: true
+
additionalProperties: false
required:
@@ -30,6 +37,8 @@ required:
examples:
- |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -38,7 +47,8 @@ examples:
compatible = "avago,apds9300";
reg = <0x39>;
interrupt-parent = <&gpio2>;
- interrupts = <29 8>;
+ interrupts = <29 IRQ_TYPE_LEVEL_LOW>;
+ vdd-supply = <&regulator_3v3>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/light/avago,apds9960.yaml b/Documentation/devicetree/bindings/iio/light/avago,apds9960.yaml
deleted file mode 100644
index f06e0fda5629..000000000000
--- a/Documentation/devicetree/bindings/iio/light/avago,apds9960.yaml
+++ /dev/null
@@ -1,44 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/iio/light/avago,apds9960.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Avago APDS9960 gesture/RGB/ALS/proximity sensor
-
-maintainers:
- - Matt Ranostay <matt.ranostay@konsulko.com>
-
-description: |
- Datasheet at https://www.avagotech.com/docs/AV02-4191EN
-
-properties:
- compatible:
- const: avago,apds9960
-
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
-additionalProperties: false
-
-required:
- - compatible
- - reg
-
-examples:
- - |
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- light-sensor@39 {
- compatible = "avago,apds9960";
- reg = <0x39>;
- interrupt-parent = <&gpio1>;
- interrupts = <16 1>;
- };
- };
-...
diff --git a/Documentation/devicetree/bindings/iio/light/bh1750.yaml b/Documentation/devicetree/bindings/iio/light/bh1750.yaml
index 1a88b3c253d5..9df81c271411 100644
--- a/Documentation/devicetree/bindings/iio/light/bh1750.yaml
+++ b/Documentation/devicetree/bindings/iio/light/bh1750.yaml
@@ -24,6 +24,10 @@ properties:
reg:
maxItems: 1
+ reset-gpios:
+ description: GPIO connected to the DVI reset pin (active low)
+ maxItems: 1
+
required:
- compatible
- reg
@@ -32,6 +36,7 @@ additionalProperties: false
examples:
- |
+ #include <dt-bindings/gpio/gpio.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -39,6 +44,7 @@ examples:
light-sensor@23 {
compatible = "rohm,bh1750";
reg = <0x23>;
+ reset-gpios = <&gpio2 17 GPIO_ACTIVE_LOW>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/light/brcm,apds9160.yaml b/Documentation/devicetree/bindings/iio/light/brcm,apds9160.yaml
new file mode 100644
index 000000000000..bb1cc4404a55
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/brcm,apds9160.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/brcm,apds9160.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom Combined Proximity & Ambient light sensor
+
+maintainers:
+ - Mikael Gonella-Bolduc <m.gonella.bolduc@gmail.com>
+
+description: |
+ Datasheet: https://docs.broadcom.com/docs/APDS-9160-003-DS
+
+properties:
+ compatible:
+ enum:
+ - brcm,apds9160
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+ ps-cancellation-duration:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Proximity sensor cancellation pulse duration in half clock cycles.
+ This parameter determines a cancellation pulse duration.
+ The cancellation is applied in the integration phase to cancel out
+ unwanted reflected light from very near objects such as tempered glass
+ in front of the sensor.
+ default: 0
+ maximum: 63
+
+ ps-cancellation-current-picoamp:
+ description:
+ Proximity sensor crosstalk cancellation current in picoampere.
+ This parameter adjusts the current in steps of 2400 pA up to 276000 pA.
+ The provided value must be a multiple of 2400 and in one of these ranges
+ [60000 - 96000]
+ [120000 - 156000]
+ [180000 - 216000]
+ [240000 - 276000]
+ This parameter is used in conjunction with the cancellation duration.
+ minimum: 60000
+ maximum: 276000
+ multipleOf: 2400
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@53 {
+ compatible = "brcm,apds9160";
+ reg = <0x53>;
+ vdd-supply = <&vdd_reg>;
+ interrupts = <29 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&pinctrl>;
+ ps-cancellation-duration = <10>;
+ ps-cancellation-current-picoamp = <62400>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/light/dynaimage,al3010.yaml b/Documentation/devicetree/bindings/iio/light/dynaimage,al3010.yaml
index a3a979553e32..1472c997c16f 100644
--- a/Documentation/devicetree/bindings/iio/light/dynaimage,al3010.yaml
+++ b/Documentation/devicetree/bindings/iio/light/dynaimage,al3010.yaml
@@ -4,14 +4,16 @@
$id: http://devicetree.org/schemas/iio/light/dynaimage,al3010.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Dyna-Image AL3010 sensor
+title: Dyna-Image AL3000a/AL3010 sensor
maintainers:
- David Heidelberg <david@ixit.cz>
properties:
compatible:
- const: dynaimage,al3010
+ enum:
+ - dynaimage,al3000a
+ - dynaimage,al3010
reg:
maxItems: 1
@@ -40,6 +42,6 @@ examples:
compatible = "dynaimage,al3010";
reg = <0x1c>;
vdd-supply = <&vdd_reg>;
- interrupts = <0 99 4>;
+ interrupts = <99 IRQ_TYPE_LEVEL_HIGH>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/light/dynaimage,al3320a.yaml b/Documentation/devicetree/bindings/iio/light/dynaimage,al3320a.yaml
index 8249be99cff9..d06db737cd9e 100644
--- a/Documentation/devicetree/bindings/iio/light/dynaimage,al3320a.yaml
+++ b/Documentation/devicetree/bindings/iio/light/dynaimage,al3320a.yaml
@@ -40,6 +40,6 @@ examples:
compatible = "dynaimage,al3320a";
reg = <0x1c>;
vdd-supply = <&vdd_reg>;
- interrupts = <0 99 4>;
+ interrupts = <99 IRQ_TYPE_LEVEL_HIGH>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/light/liteon,ltr390.yaml b/Documentation/devicetree/bindings/iio/light/liteon,ltr390.yaml
new file mode 100644
index 000000000000..5d98ef2af74d
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/liteon,ltr390.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/liteon,ltr390.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Lite-On LTR390 ALS and UV Sensor
+
+description: |
+ The Lite-On LTR390 is an ALS (Ambient Light Sensor) and a UV sensor in a
+ single package with i2c address of 0x53.
+
+ Datasheet:
+ https://optoelectronics.liteon.com/upload/download/DS86-2015-0004/LTR-390UV_Final_%20DS_V1%201.pdf
+
+maintainers:
+ - Anshul Dalal <anshulusr@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - liteon,ltr390
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+ description: |
+ Level interrupt pin with open drain output.
+ The sensor pulls this pin low when the measured reading is greater than
+ some configured threshold.
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@53 {
+ compatible = "liteon,ltr390";
+ reg = <0x53>;
+ interrupts = <18 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&vdd_regulator>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml b/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml
new file mode 100644
index 000000000000..c8074f180a79
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/liteon,ltr501.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/liteon,ltr501.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LiteON LTR501 I2C Proximity and Light sensor
+
+maintainers:
+ - Nikita Travkin <nikita@trvn.ru>
+
+allOf:
+ - $ref: ../common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - liteon,ltr501
+ - liteon,ltr559
+ - liteon,ltr301
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+ vddio-supply: true
+
+ interrupts:
+ maxItems: 1
+
+ proximity-near-level: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@23 {
+ compatible = "liteon,ltr559";
+ reg = <0x23>;
+ proximity-near-level = <75>;
+
+ vdd-supply = <&pm8916_l17>;
+ vddio-supply = <&pm8916_l6>;
+
+ interrupt-parent = <&msmgpio>;
+ interrupts = <115 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/light/liteon,ltrf216a.yaml b/Documentation/devicetree/bindings/iio/light/liteon,ltrf216a.yaml
new file mode 100644
index 000000000000..877e955d4ebd
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/liteon,ltrf216a.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/liteon,ltrf216a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LTRF216A Ambient Light Sensor
+
+maintainers:
+ - Shreeya Patel <shreeya.patel@collabora.com>
+
+description:
+ Ambient light sensing with an i2c interface.
+
+properties:
+ compatible:
+ enum:
+ - liteon,ltr308
+ - liteon,ltrf216a
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply:
+ description: Regulator that provides power to the sensor.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@53 {
+ compatible = "liteon,ltrf216a";
+ reg = <0x53>;
+ vdd-supply = <&vdd_regulator>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <5 IRQ_TYPE_LEVEL_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/light/rohm,bh1745.yaml b/Documentation/devicetree/bindings/iio/light/rohm,bh1745.yaml
new file mode 100644
index 000000000000..44896795c67e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/rohm,bh1745.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/rohm,bh1745.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BH1745 colour sensor
+
+maintainers:
+ - Mudit Sharma <muditsharma.info@gmail.com>
+
+description:
+ BH1745 is an I2C colour sensor with red, green, blue and clear
+ channels. It has a programmable active low interrupt pin.
+ Interrupt occurs when the signal from the selected interrupt
+ source channel crosses set interrupt threshold high/low level.
+
+properties:
+ compatible:
+ const: rohm,bh1745
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ colour-sensor@38 {
+ compatible = "rohm,bh1745";
+ reg = <0x38>;
+ interrupt-parent = <&gpio>;
+ interrupts = <19 IRQ_TYPE_LEVEL_LOW>;
+ vdd-supply = <&vdd>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/light/rohm,bu27034anuc.yaml b/Documentation/devicetree/bindings/iio/light/rohm,bu27034anuc.yaml
new file mode 100644
index 000000000000..29c90ca5b258
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/rohm,bu27034anuc.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/rohm,bu27034anuc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BU27034ANUC ambient light sensor
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description: |
+ ROHM BU27034ANUC is an ambient light sensor with 2 channels and 2 photo diodes
+ capable of detecting a very wide range of illuminance. Typical application
+ is adjusting LCD and backlight power of TVs and mobile phones.
+
+properties:
+ compatible:
+ const: rohm,bu27034anuc
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@38 {
+ compatible = "rohm,bu27034anuc";
+ reg = <0x38>;
+ vdd-supply = <&vdd>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/iio/light/st,vl6180.yaml b/Documentation/devicetree/bindings/iio/light/st,vl6180.yaml
index 27c36ab7990d..8598fb631aac 100644
--- a/Documentation/devicetree/bindings/iio/light/st,vl6180.yaml
+++ b/Documentation/devicetree/bindings/iio/light/st,vl6180.yaml
@@ -32,7 +32,6 @@ required:
examples:
- |
- #include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/light/stk33xx.yaml b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml
index f92bf7b2b7f0..e4341fdced98 100644
--- a/Documentation/devicetree/bindings/iio/light/stk33xx.yaml
+++ b/Documentation/devicetree/bindings/iio/light/stk33xx.yaml
@@ -13,12 +13,20 @@ maintainers:
description: |
Ambient light and proximity sensor over an i2c interface.
+allOf:
+ - $ref: ../common.yaml#
+
properties:
compatible:
- enum:
- - sensortek,stk3310
- - sensortek,stk3311
- - sensortek,stk3335
+ oneOf:
+ - enum:
+ - sensortek,stk3310
+ - sensortek,stk3311
+ - sensortek,stk3335
+ - items:
+ - enum:
+ - sensortek,stk3013
+ - const: sensortek,stk3310
reg:
maxItems: 1
@@ -26,6 +34,8 @@ properties:
interrupts:
maxItems: 1
+ proximity-near-level: true
+
required:
- compatible
- reg
@@ -44,6 +54,7 @@ examples:
stk3310@48 {
compatible = "sensortek,stk3310";
reg = <0x48>;
+ proximity-near-level = <25>;
interrupt-parent = <&gpio1>;
interrupts = <5 IRQ_TYPE_LEVEL_LOW>;
};
diff --git a/Documentation/devicetree/bindings/iio/light/ti,opt3001.yaml b/Documentation/devicetree/bindings/iio/light/ti,opt3001.yaml
index 441e9343fc97..67ca8d08256a 100644
--- a/Documentation/devicetree/bindings/iio/light/ti,opt3001.yaml
+++ b/Documentation/devicetree/bindings/iio/light/ti,opt3001.yaml
@@ -15,7 +15,9 @@ description: |
properties:
compatible:
- const: ti,opt3001
+ enum:
+ - ti,opt3001
+ - ti,opt3002
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/iio/light/ti,opt4001.yaml b/Documentation/devicetree/bindings/iio/light/ti,opt4001.yaml
new file mode 100644
index 000000000000..12b0c7ed5d72
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/ti,opt4001.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/ti,opt4001.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments OPT4001 Ambient Light Sensor
+
+maintainers:
+ - Stefan Windfeldt-Prytz <stefan.windfeldt-prytz@axis.com>
+
+description:
+ Ambient light sensor with an i2c interface.
+ Last part of compatible is for the packaging used.
+ Picostar is a 4 pinned SMT and sot-5x3 is a 8 pinned SOT.
+ https://www.ti.com/lit/gpn/opt4001
+
+properties:
+ compatible:
+ enum:
+ - ti,opt4001-picostar
+ - ti,opt4001-sot-5x3
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply:
+ description: Regulator that provides power to the sensor
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,opt4001-sot-5x3
+ then:
+ properties:
+ interrupts:
+ maxItems: 1
+ else:
+ properties:
+ interrupts: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@44 {
+ compatible = "ti,opt4001-sot-5x3";
+ reg = <0x44>;
+ vdd-supply = <&vdd_reg>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <28 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml b/Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml
new file mode 100644
index 000000000000..568fb2a9b7a3
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/ti,opt4060.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments OPT4060 RGBW Color Sensor
+
+maintainers:
+ - Per-Daniel Olsson <perdaniel.olsson@axis.com>
+
+description:
+ Texas Instrument RGBW high resolution color sensor over I2C.
+ https://www.ti.com/lit/gpn/opt4060
+
+properties:
+ compatible:
+ enum:
+ - ti,opt4060
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@44 {
+ compatible = "ti,opt4060";
+ reg = <0x44>;
+ vdd-supply = <&vdd_reg>;
+ interrupt-parent = <&gpio5>;
+ interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/light/veml6030.yaml b/Documentation/devicetree/bindings/iio/light/veml6030.yaml
deleted file mode 100644
index fb19a2d7a849..000000000000
--- a/Documentation/devicetree/bindings/iio/light/veml6030.yaml
+++ /dev/null
@@ -1,64 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0+
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/iio/light/veml6030.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: VEML6030 Ambient Light Sensor (ALS)
-
-maintainers:
- - Rishi Gupta <gupt21@gmail.com>
-
-description: |
- Bindings for the ambient light sensor veml6030 from Vishay
- Semiconductors over an i2c interface.
-
- Irrespective of whether interrupt is used or not, application
- can get the ALS and White channel reading from IIO raw interface.
-
- If the interrupts are used, application will receive an IIO event
- whenever configured threshold is crossed.
-
- Specifications about the sensor can be found at:
- https://www.vishay.com/docs/84366/veml6030.pdf
-
-properties:
- compatible:
- enum:
- - vishay,veml6030
-
- reg:
- description:
- I2C address of the device.
- enum:
- - 0x10 # ADDR pin pulled down
- - 0x48 # ADDR pin pulled up
-
- interrupts:
- description:
- interrupt mapping for IRQ. Configure with IRQ_TYPE_LEVEL_LOW.
- Refer to interrupt-controller/interrupts.txt for generic
- interrupt client node bindings.
- maxItems: 1
-
-required:
- - compatible
- - reg
-
-additionalProperties: false
-
-examples:
- - |
- #include <dt-bindings/interrupt-controller/irq.h>
-
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- light-sensor@10 {
- compatible = "vishay,veml6030";
- reg = <0x10>;
- interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
- };
- };
-...
diff --git a/Documentation/devicetree/bindings/iio/light/vishay,veml6030.yaml b/Documentation/devicetree/bindings/iio/light/vishay,veml6030.yaml
new file mode 100644
index 000000000000..4ea69f1fdd63
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/vishay,veml6030.yaml
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: GPL-2.0+
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/vishay,veml6030.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: VEML3235, VEML6030, VEML6035 and VEML7700 Ambient Light Sensors (ALS)
+
+maintainers:
+ - Rishi Gupta <gupt21@gmail.com>
+
+description: |
+ Bindings for the ambient light sensors veml6030 and veml6035 from
+ Vishay Semiconductors over an i2c interface.
+
+ Irrespective of whether interrupt is used or not, application
+ can get the ALS and White channel reading from IIO raw interface.
+
+ If the interrupts are used, application will receive an IIO event
+ whenever configured threshold is crossed.
+
+ Specifications about the sensors can be found at:
+ https://www.vishay.com/docs/80131/veml3235.pdf
+ https://www.vishay.com/docs/84366/veml6030.pdf
+ https://www.vishay.com/docs/84889/veml6035.pdf
+ https://www.vishay.com/docs/84286/veml7700.pdf
+
+properties:
+ compatible:
+ enum:
+ - vishay,veml3235
+ - vishay,veml6030
+ - vishay,veml6035
+ - vishay,veml7700
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ interrupt mapping for IRQ. Configure with IRQ_TYPE_LEVEL_LOW.
+ Refer to interrupt-controller/interrupts.txt for generic
+ interrupt client node bindings.
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - vishay,veml6030
+ then:
+ properties:
+ reg:
+ enum:
+ - 0x10 # ADDR pin pulled down
+ - 0x48 # ADDR pin pulled up
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - vishay,veml6035
+ then:
+ properties:
+ reg:
+ enum:
+ - 0x29
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - vishay,veml3235
+ - vishay,veml7700
+ then:
+ properties:
+ reg:
+ enum:
+ - 0x10
+ interrupts: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ light-sensor@10 {
+ compatible = "vishay,veml6030";
+ reg = <0x10>;
+ interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
+ vdd-supply = <&vdd>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/light/vishay,veml6046x00.yaml b/Documentation/devicetree/bindings/iio/light/vishay,veml6046x00.yaml
new file mode 100644
index 000000000000..112d448ff0bf
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/vishay,veml6046x00.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/vishay,veml6046x00.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Vishay VEML6046X00 High accuracy RGBIR color sensor
+
+maintainers:
+ - Andreas Klinger <ak@it-klinger.de>
+
+description:
+ VEML6046X00 datasheet at https://www.vishay.com/docs/80173/veml6046x00.pdf
+
+properties:
+ compatible:
+ enum:
+ - vishay,veml6046x00
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ color-sensor@29 {
+ compatible = "vishay,veml6046x00";
+ reg = <0x29>;
+ vdd-supply = <&vdd_reg>;
+ interrupt-parent = <&gpio2>;
+ interrupts = <3 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/light/vishay,veml6075.yaml b/Documentation/devicetree/bindings/iio/light/vishay,veml6075.yaml
new file mode 100644
index 000000000000..d2effccbfb56
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/vishay,veml6075.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/vishay,veml6075.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Vishay VEML6070 UVA, VEML6075 UVA/B and VEML6040 RGBW sensors
+
+maintainers:
+ - Javier Carrasco <javier.carrasco.cruz@gmail.com>
+
+description:
+ VEML6040 datasheet at https://www.vishay.com/docs/84276/veml6040.pdf
+
+properties:
+ compatible:
+ enum:
+ - vishay,veml6040
+ - vishay,veml6070
+ - vishay,veml6075
+
+ reg:
+ maxItems: 1
+
+ vishay,rset-ohms:
+ description:
+ Resistor used to select the integration time.
+ default: 270000
+ minimum: 75000
+ maximum: 1200000
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - vishay,veml6040
+ - vishay,veml6075
+ then:
+ properties:
+ vishay,rset-ohms: false
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ uv-sensor@10 {
+ compatible = "vishay,veml6075";
+ reg = <0x10>;
+ vdd-supply = <&vdd_reg>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/allegromicro,als31300.yaml b/Documentation/devicetree/bindings/iio/magnetometer/allegromicro,als31300.yaml
new file mode 100644
index 000000000000..52e3781834ee
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/allegromicro,als31300.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/allegromicro,als31300.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allegro MicroSystems ALS31300 3-D Linear Hall Effect sensor
+
+maintainers:
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+properties:
+ $nodename:
+ pattern: '^magnetometer@[0-9a-f]+$'
+
+ compatible:
+ enum:
+ - allegromicro,als31300-500 # Factory configured at 500 Gauss input range
+ - allegromicro,als31300-1000 # Factory configured at 1000 Gauss input range
+ - allegromicro,als31300-2000 # Factory configured at 2000 Gauss input range
+
+ reg:
+ maxItems: 1
+
+ vcc-supply:
+ description: 5.5V supply
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ magnetometer@61 {
+ compatible = "allegromicro,als31300-500";
+ reg = <0x61>;
+ vcc-supply = <&hall_vcc>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml
index a0a1ffe017df..e8ca9a234027 100644
--- a/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml
+++ b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml
@@ -17,6 +17,11 @@ properties:
- asahi-kasei,ak8963
- asahi-kasei,ak09911
- asahi-kasei,ak09912
+ - asahi-kasei,ak09916
+ - items:
+ # ak09918 is register compatible with ak09912.
+ - const: asahi-kasei,ak09918
+ - const: asahi-kasei,ak09912
- enum:
- ak8975
- ak8963
@@ -43,6 +48,11 @@ properties:
an optional regulator that needs to be on to provide VDD power to
the sensor.
+ vid-supply:
+ description: |
+ an optional regulator that needs to be on to provide VID power to
+ the sensor.
+
mount-matrix:
description: an optional 3x3 mounting rotation matrix.
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml b/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml
index 2867ab6bf9b0..a3838ab0c524 100644
--- a/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml
+++ b/Documentation/devicetree/bindings/iio/magnetometer/bosch,bmc150_magn.yaml
@@ -36,6 +36,9 @@ properties:
interrupts:
maxItems: 1
+ mount-matrix:
+ description: an optional 3x3 mounting rotation matrix.
+
additionalProperties: false
required:
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/fsl,mag3110.yaml b/Documentation/devicetree/bindings/iio/magnetometer/fsl,mag3110.yaml
index 6b54d32323fc..fbe8c2eb0857 100644
--- a/Documentation/devicetree/bindings/iio/magnetometer/fsl,mag3110.yaml
+++ b/Documentation/devicetree/bindings/iio/magnetometer/fsl,mag3110.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale MAG3110 magnetometer sensor
maintainers:
- - Anson Huang <Anson.Huang@nxp.com>
+ - Jonathan Cameron <jic23@kernel.org>
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/infineon,tlv493d-a1b6.yaml b/Documentation/devicetree/bindings/iio/magnetometer/infineon,tlv493d-a1b6.yaml
new file mode 100644
index 000000000000..dd23a9370a71
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/infineon,tlv493d-a1b6.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/infineon,tlv493d-a1b6.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Infineon Technologies TLV493D Low-Power 3D Magnetic Sensor
+
+maintainers:
+ - Dixit Parmar <dixitparmar19@gmail.com>
+
+properties:
+ $nodename:
+ pattern: '^magnetometer@[0-9a-f]+$'
+
+ compatible:
+ const: infineon,tlv493d-a1b6
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: 2.8V to 3.5V VDD supply
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ magnetometer@5e {
+ compatible = "infineon,tlv493d-a1b6";
+ reg = <0x5e>;
+ vdd-supply = <&hall_vcc>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/silabs,si7210.yaml b/Documentation/devicetree/bindings/iio/magnetometer/silabs,si7210.yaml
new file mode 100644
index 000000000000..d4a3f7981c36
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/silabs,si7210.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/silabs,si7210.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Si7210 magnetic position and temperature sensor
+
+maintainers:
+ - Antoni Pokusinski <apokusinski01@gmail.com>
+
+description: |
+ Silabs Si7210 I2C Hall effect magnetic position and temperature sensor.
+ https://www.silabs.com/documents/public/data-sheets/si7210-datasheet.pdf
+
+properties:
+ compatible:
+ const: silabs,si7210
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply:
+ description: Regulator that provides power to the sensor
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ magnetometer@30 {
+ compatible = "silabs,si7210";
+ reg = <0x30>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <4 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&vdd_3v3_reg>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml b/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml
new file mode 100644
index 000000000000..121d540b7b6e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/ti,tmag5273.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/ti,tmag5273.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI TMAG5273 Low-Power Linear 3D Hall-Effect Sensor
+
+maintainers:
+ - Gerald Loacker <gerald.loacker@wolfvision.net>
+
+description:
+ The TI TMAG5273 is a low-power linear 3D Hall-effect sensor. This device
+ integrates three independent Hall-effect sensors in the X, Y, and Z axes.
+ The device has an integrated temperature sensor available. The TMAG5273
+ can be configured through the I2C interface to enable any combination of
+ magnetic axes and temperature measurements. An integrated angle calculation
+ engine (CORDIC) provides full 360° angular position information for both
+ on-axis and off-axis angle measurement topologies. The angle calculation is
+ performed using two user-selected magnetic axes.
+
+properties:
+ compatible:
+ const: ti,tmag5273
+
+ reg:
+ maxItems: 1
+
+ "#io-channel-cells":
+ const: 1
+
+ ti,angle-measurement:
+ $ref: /schemas/types.yaml#/definitions/string
+ description:
+ Enables angle measurement in the selected plane.
+ If not specified, "x-y" will be anables as default.
+ enum:
+ - off
+ - x-y
+ - y-z
+ - x-z
+
+ vcc-supply:
+ description:
+ A regulator providing 1.7 V to 3.6 V supply voltage on the VCC pin,
+ typically 3.3 V.
+
+ interrupts:
+ description:
+ The low active interrupt can be configured to be fixed width or latched.
+ Interrupt events can be configured to be generated from magnetic
+ thresholds or when a conversion is completed.
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ magnetometer@35 {
+ compatible = "ti,tmag5273";
+ reg = <0x35>;
+ #io-channel-cells = <1>;
+ ti,angle-measurement = "x-z";
+ vcc-supply = <&vcc3v3>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/voltafield,af8133j.yaml b/Documentation/devicetree/bindings/iio/magnetometer/voltafield,af8133j.yaml
new file mode 100644
index 000000000000..ed42dc5afb99
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/voltafield,af8133j.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/voltafield,af8133j.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Voltafield AF8133J magnetometer sensor
+
+maintainers:
+ - Ondřej Jirman <megi@xff.cz>
+
+properties:
+ compatible:
+ const: voltafield,af8133j
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ description:
+ A signal for active low reset input of the sensor. (optional; if not
+ used, software reset over I2C will be used instead)
+
+ avdd-supply:
+ description:
+ A regulator that provides AVDD power (Working power, usually 3.3V) to
+ the sensor.
+
+ dvdd-supply:
+ description:
+ A regulator that provides DVDD power (Digital IO power, 1.8V - AVDD)
+ to the sensor.
+
+ mount-matrix:
+ description: An optional 3x3 mounting rotation matrix.
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - dvdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ magnetometer@1c {
+ compatible = "voltafield,af8133j";
+ reg = <0x1c>;
+ avdd-supply = <&reg_dldo1>;
+ dvdd-supply = <&reg_dldo1>;
+ reset-gpios = <&pio 1 1 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml
index 4b0ef1ef5445..877226e9219b 100644
--- a/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml
+++ b/Documentation/devicetree/bindings/iio/magnetometer/yamaha,yas530.yaml
@@ -91,12 +91,12 @@ examples:
#size-cells = <0>;
magnetometer@2e {
- compatible = "yamaha,yas530";
- reg = <0x2e>;
- vdd-supply = <&ldo1_reg>;
- iovdd-supply = <&ldo2_reg>;
- reset-gpios = <&gpio6 12 GPIO_ACTIVE_LOW>;
- interrupts = <&gpio6 13 IRQ_TYPE_EDGE_RISING>;
+ compatible = "yamaha,yas530";
+ reg = <0x2e>;
+ vdd-supply = <&ldo1_reg>;
+ iovdd-supply = <&ldo2_reg>;
+ reset-gpios = <&gpio6 12 GPIO_ACTIVE_LOW>;
+ interrupts = <13 IRQ_TYPE_EDGE_RISING>;
};
};
@@ -105,8 +105,8 @@ examples:
#size-cells = <0>;
magnetometer@2e {
- compatible = "yamaha,yas539";
- reg = <0x2e>;
- vdd-supply = <&ldo1_reg>;
+ compatible = "yamaha,yas539";
+ reg = <0x2e>;
+ vdd-supply = <&ldo1_reg>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.yaml b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.yaml
index 870b043406d8..c55831b60ee6 100644
--- a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.yaml
+++ b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/multiplexer/io-channel-mux.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: I/O channel multiplexer bindings
+title: I/O channel multiplexer
maintainers:
- Peter Rosin <peda@axentia.se>
@@ -35,9 +35,18 @@ properties:
mux-control-names: true
channels:
- $ref: /schemas/types.yaml#/definitions/string-array
+ $ref: /schemas/types.yaml#/definitions/non-unique-string-array
description:
- List of strings, labeling the mux controller states.
+ List of strings, labeling the mux controller states. An empty
+ string for a state means that the channel is not available.
+
+ settle-time-us:
+ default: 0
+ description:
+ Time required for analog signals to settle after muxing.
+
+ "#io-channel-cells":
+ const: 1
required:
- compatible
diff --git a/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml b/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml
index 0ebb6725a1af..b8d7083c97f8 100644
--- a/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml
+++ b/Documentation/devicetree/bindings/iio/potentiometer/adi,ad5272.yaml
@@ -44,7 +44,7 @@ examples:
potentiometer@2f {
compatible = "adi,ad5272-020";
- reg = <0x2F>;
+ reg = <0x2f>;
reset-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>;
};
};
diff --git a/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp41010.yaml b/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp41010.yaml
index 567697d996ec..87e88f2a9908 100644
--- a/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp41010.yaml
+++ b/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp41010.yaml
@@ -25,14 +25,15 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
-additionalProperties: false
-
required:
- compatible
- reg
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
spi {
diff --git a/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp4131.yaml b/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp4131.yaml
index 945a2d644ddc..896fe0b5edcc 100644
--- a/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp4131.yaml
+++ b/Documentation/devicetree/bindings/iio/potentiometer/microchip,mcp4131.yaml
@@ -80,14 +80,15 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
-
-additionalProperties: false
-
required:
- compatible
- reg
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
spi {
@@ -95,7 +96,7 @@ examples:
#size-cells = <0>;
potentiometer@0 {
- compatible = "mcp4131-502";
+ compatible = "microchip,mcp4131-502";
reg = <0>;
spi-max-frequency = <500000>;
};
diff --git a/Documentation/devicetree/bindings/iio/potentiometer/renesas,x9250.yaml b/Documentation/devicetree/bindings/iio/potentiometer/renesas,x9250.yaml
new file mode 100644
index 000000000000..ab5c09c00ff4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/potentiometer/renesas,x9250.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/potentiometer/renesas,x9250.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas X9250 quad potentiometers
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description:
+ The Renesas X9250 integrates four digitally controlled potentiometers.
+ On each potentiometer, the X9250T has a 100 kOhms total resistance and the
+ X9250U has a 50 kOhms total resistance.
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml
+
+properties:
+ compatible:
+ enum:
+ - renesas,x9250t
+ - renesas,x9250u
+
+ reg:
+ maxItems: 1
+
+ vcc-supply:
+ description:
+ Regulator for the VCC power supply.
+
+ avp-supply:
+ description:
+ Regulator for the analog V+ power supply.
+
+ avn-supply:
+ description:
+ Regulator for the analog V- power supply.
+
+ '#io-channel-cells':
+ const: 1
+
+ spi-max-frequency:
+ maximum: 2000000
+
+ wp-gpios:
+ maxItems: 1
+ description:
+ GPIO connected to the write-protect pin.
+
+required:
+ - compatible
+ - reg
+ - vcc-supply
+ - avp-supply
+ - avn-supply
+ - '#io-channel-cells'
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ potentiometer@0 {
+ compatible = "renesas,x9250t";
+ reg = <0>;
+ vcc-supply = <&vcc_regulator>;
+ avp-supply = <&avp_regulator>;
+ avn-supply = <&avp_regulator>;
+ wp-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
+ spi-max-frequency = <2000000>;
+ #io-channel-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/pressure/aosong,adp810.yaml b/Documentation/devicetree/bindings/iio/pressure/aosong,adp810.yaml
new file mode 100644
index 000000000000..ad5f26ce5043
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/aosong,adp810.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/aosong,adp810.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: aosong adp810 differential pressure sensor
+
+maintainers:
+ - Akhilesh Patil <akhilesh@ee.iitb.ac.in>
+
+description:
+ ADP810 is differential pressure and temperature sensor. It has I2C bus
+ interface with fixed address of 0x25. This sensor supports 8 bit CRC for
+ reliable data transfer. It can measure differential pressure in the
+ range -500 to 500Pa and temperate in the range -40 to +85 degree celsius.
+
+properties:
+ compatible:
+ enum:
+ - aosong,adp810
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pressure-sensor@25 {
+ compatible = "aosong,adp810";
+ reg = <0x25>;
+ vdd-supply = <&vdd_regulator>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml
index be2be4b556db..9fb8d773efa3 100644
--- a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml
+++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: All Sensors DLH series low voltage digital pressure sensors
maintainers:
- - Tomislav Denis <tomislav.denis@avl.com>
+ - Jonathan Cameron <jic23@kernel.org>
description: |
Bindings for the All Sensors DLH series pressure sensors.
@@ -39,7 +39,7 @@ examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml
index 49257f9251e8..b9ea37317b53 100644
--- a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml
+++ b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/pressure/bmp085.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: BMP085/BMP180/BMP280/BME280 pressure iio sensors
+title: BMP085/BMP180/BMP280/BME280/BMP380 pressure iio sensors
maintainers:
- Andreas Klinger <ak@it-klinger.de>
@@ -16,6 +16,8 @@ description: |
https://www.bosch-sensortec.com/bst/products/all_products/bmp180
https://www.bosch-sensortec.com/bst/products/all_products/bmp280
https://www.bosch-sensortec.com/bst/products/all_products/bme280
+ https://www.bosch-sensortec.com/bst/products/all_products/bmp380
+ https://www.bosch-sensortec.com/bst/products/all_products/bmp580
properties:
compatible:
@@ -24,6 +26,8 @@ properties:
- bosch,bmp180
- bosch,bmp280
- bosch,bme280
+ - bosch,bmp380
+ - bosch,bmp580
reg:
maxItems: 1
@@ -43,31 +47,77 @@ properties:
maxItems: 1
interrupts:
- description:
- interrupt mapping for IRQ (BMP085 only)
maxItems: 1
+ drive-open-drain:
+ description:
+ set if the interrupt pin should be configured as open drain.
+ If not set, defaults to push-pull configuration.
+ type: boolean
+
+ spi-max-frequency:
+ maximum: 10000000
+
required:
- compatible
- vddd-supply
- vdda-supply
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - bosch,bmp085
+ - bosch,bmp380
+ - bosch,bmp580
+ then:
+ properties:
+ interrupts: false
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - bosch,bmp085
+ - bosch,bmp180
+ then:
+ properties:
+ spi-max-frequency: false
+
additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
- pressure@77 {
- compatible = "bosch,bmp085";
- reg = <0x77>;
- interrupt-parent = <&gpio0>;
- interrupts = <25 IRQ_TYPE_EDGE_RISING>;
- reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>;
- vddd-supply = <&foo>;
- vdda-supply = <&bar>;
- };
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pressure@77 {
+ compatible = "bosch,bmp085";
+ reg = <0x77>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>;
+ vddd-supply = <&foo>;
+ vdda-supply = <&bar>;
+ };
+ };
+ - |
+ # include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pressure@0 {
+ compatible = "bosch,bmp280";
+ reg = <0>;
+ spi-max-frequency = <10000000>;
+ reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>;
+ vddd-supply = <&foo>;
+ vdda-supply = <&bar>;
+ };
};
diff --git a/Documentation/devicetree/bindings/iio/pressure/fsl,mpl3115.yaml b/Documentation/devicetree/bindings/iio/pressure/fsl,mpl3115.yaml
new file mode 100644
index 000000000000..2933c2e10695
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/fsl,mpl3115.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/fsl,mpl3115.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MPL3115 precision pressure sensor with altimetry
+
+maintainers:
+ - Antoni Pokusinski <apokusinski01@gmail.com>
+
+description: |
+ MPL3115 is a pressure/altitude and temperature sensor with I2C interface.
+ It features two programmable interrupt lines which indicate events such as
+ data ready or pressure/temperature threshold reached.
+ https://www.nxp.com/docs/en/data-sheet/MPL3115A2.pdf
+
+properties:
+ compatible:
+ const: fsl,mpl3115
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+ vddio-supply: true
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum:
+ - INT1
+ - INT2
+
+ drive-open-drain:
+ type: boolean
+ description:
+ set if the specified interrupt pins should be configured as
+ open drain. If not set, defaults to push-pull.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vddio-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pressure@60 {
+ compatible = "fsl,mpl3115";
+ reg = <0x60>;
+ vdd-supply = <&vdd>;
+ vddio-supply = <&vddio>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <4 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-names = "INT2";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml b/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml
new file mode 100644
index 000000000000..412c7bcc310f
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/honeywell,hsc030pa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Honeywell TruStability HSC and SSC pressure sensor series
+
+description: |
+ support for Honeywell TruStability HSC and SSC digital pressure sensor
+ series.
+
+ These sensors have either an I2C, an SPI or an analog interface. Only the
+ digital versions are supported by this driver.
+
+ There are 118 models with different pressure ranges available in each family.
+ The vendor calls them "HSC series" and "SSC series". All of them have an
+ identical programming model but differ in pressure range, unit and transfer
+ function.
+
+ To support different models one needs to specify the pressure range as well
+ as the transfer function. Pressure range can either be provided via
+ pressure-triplet (directly extracted from the part number) or in case it's
+ a custom chip via numerical range limits converted to pascals.
+
+ The transfer function defines the ranges of raw conversion values delivered
+ by the sensor. pmin-pascal and pmax-pascal corespond to the minimum and
+ maximum pressure that can be measured.
+
+ Please note that in case of an SPI-based sensor, the clock signal should not
+ exceed 800kHz and the MOSI signal is not required.
+
+ Specifications about the devices can be found at:
+ https://prod-edam.honeywell.com/content/dam/honeywell-edam/sps/siot/en-us/products/sensors/pressure-sensors/board-mount-pressure-sensors/trustability-hsc-series/documents/sps-siot-trustability-hsc-series-high-accuracy-board-mount-pressure-sensors-50099148-a-en-ciid-151133.pdf
+ https://prod-edam.honeywell.com/content/dam/honeywell-edam/sps/siot/en-us/products/sensors/pressure-sensors/board-mount-pressure-sensors/trustability-ssc-series/documents/sps-siot-trustability-ssc-series-standard-accuracy-board-mount-pressure-sensors-50099533-a-en-ciid-151134.pdf
+
+maintainers:
+ - Petre Rodan <petre.rodan@subdimension.ro>
+
+properties:
+ compatible:
+ const: honeywell,hsc030pa
+
+ reg:
+ maxItems: 1
+
+ honeywell,transfer-function:
+ description: |
+ Transfer function which defines the range of valid values delivered by
+ the sensor.
+ 0 - A, 10% to 90% of 2^14
+ 1 - B, 5% to 95% of 2^14
+ 2 - C, 5% to 85% of 2^14
+ 3 - F, 4% to 94% of 2^14
+ enum: [0, 1, 2, 3]
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ honeywell,pressure-triplet:
+ description: |
+ Case-sensitive five character string that defines pressure range, unit
+ and type as part of the device nomenclature. In the unlikely case of a
+ custom chip, set to "NA" and provide pmin-pascal and pmax-pascal.
+ enum: [001BA, 1.6BA, 2.5BA, 004BA, 006BA, 010BA, 1.6MD, 2.5MD, 004MD,
+ 006MD, 010MD, 016MD, 025MD, 040MD, 060MD, 100MD, 160MD, 250MD,
+ 400MD, 600MD, 001BD, 1.6BD, 2.5BD, 004BD, 2.5MG, 004MG, 006MG,
+ 010MG, 016MG, 025MG, 040MG, 060MG, 100MG, 160MG, 250MG, 400MG,
+ 600MG, 001BG, 1.6BG, 2.5BG, 004BG, 006BG, 010BG, 100KA, 160KA,
+ 250KA, 400KA, 600KA, 001GA, 160LD, 250LD, 400LD, 600LD, 001KD,
+ 1.6KD, 2.5KD, 004KD, 006KD, 010KD, 016KD, 025KD, 040KD, 060KD,
+ 100KD, 160KD, 250KD, 400KD, 250LG, 400LG, 600LG, 001KG, 1.6KG,
+ 2.5KG, 004KG, 006KG, 010KG, 016KG, 025KG, 040KG, 060KG, 100KG,
+ 160KG, 250KG, 400KG, 600KG, 001GG, 015PA, 030PA, 060PA, 100PA,
+ 150PA, 0.5ND, 001ND, 002ND, 004ND, 005ND, 010ND, 020ND, 030ND,
+ 001PD, 005PD, 015PD, 030PD, 060PD, 001NG, 002NG, 004NG, 005NG,
+ 010NG, 020NG, 030NG, 001PG, 005PG, 015PG, 030PG, 060PG, 100PG,
+ 150PG, NA]
+ $ref: /schemas/types.yaml#/definitions/string
+
+ honeywell,pmin-pascal:
+ description: |
+ Minimum pressure value the sensor can measure in pascal.
+ To be specified only if honeywell,pressure-triplet is set to "NA".
+
+ honeywell,pmax-pascal:
+ description: |
+ Maximum pressure value the sensor can measure in pascal.
+ To be specified only if honeywell,pressure-triplet is set to "NA".
+
+ vdd-supply:
+ description:
+ Provide VDD power to the sensor (either 3.3V or 5V depending on the chip)
+
+ spi-max-frequency:
+ maximum: 800000
+
+required:
+ - compatible
+ - reg
+ - honeywell,transfer-function
+ - honeywell,pressure-triplet
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml
+
+unevaluatedProperties: false
+
+dependentSchemas:
+ honeywell,pmin-pascal:
+ properties:
+ honeywell,pressure-triplet:
+ const: NA
+ honeywell,pmax-pascal:
+ properties:
+ honeywell,pressure-triplet:
+ const: NA
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pressure@28 {
+ compatible = "honeywell,hsc030pa";
+ reg = <0x28>;
+ honeywell,transfer-function = <0>;
+ honeywell,pressure-triplet = "030PA";
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pressure@0 {
+ compatible = "honeywell,hsc030pa";
+ reg = <0>;
+ spi-max-frequency = <800000>;
+ honeywell,transfer-function = <0>;
+ honeywell,pressure-triplet = "NA";
+ honeywell,pmin-pascal = <0>;
+ honeywell,pmax-pascal = <200000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml b/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml
new file mode 100644
index 000000000000..c756aa863103
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/honeywell,mprls0025pa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Honeywell mprls0025pa pressure sensor
+
+maintainers:
+ - Andreas Klinger <ak@it-klinger.de>
+ - Petre Rodan <petre.rodan@subdimension.ro>
+
+description: |
+ Honeywell pressure sensor of model mprls0025pa.
+
+ This sensor has an I2C and SPI interface.
+
+ There are many models with different pressure ranges available. The vendor
+ calls them "mpr series". All of them have the identical programming model and
+ differ in the pressure range, unit and transfer function.
+
+ To support different models one need to specify its pressure triplet as well
+ as the transfer function.
+
+ For custom silicon chips not covered by the Honeywell MPR series datasheet,
+ the pressure values can be specified manually via honeywell,pmin-pascal and
+ honeywell,pmax-pascal.
+ The minimal range value stands for the minimum pressure and the maximum value
+ also for the maximum pressure with linear relation inside the range.
+
+ The transfer function defines the ranges of numerical values delivered by the
+ sensor.
+
+ Specifications about the devices can be found at:
+ https://prod-edam.honeywell.com/content/dam/honeywell-edam/sps/siot/en-us/
+ products/sensors/pressure-sensors/board-mount-pressure-sensors/
+ micropressure-mpr-series/documents/
+ sps-siot-mpr-series-datasheet-32332628-ciid-172626.pdf
+
+properties:
+ compatible:
+ const: honeywell,mprls0025pa
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Optional interrupt for indicating End-of-conversion.
+ If not present, the driver loops for a while until the received status
+ byte indicates correct measurement.
+ maxItems: 1
+
+ reset-gpios:
+ description:
+ Optional GPIO for resetting the device.
+ If not present the device is not reset during the probe.
+ maxItems: 1
+
+ honeywell,transfer-function:
+ description: |
+ Transfer function which defines the range of valid values delivered by the
+ sensor.
+ 1 - A, 10% to 90% of 2^24 (1677722 .. 15099494)
+ 2 - B, 2.5% to 22.5% of 2^24 (419430 .. 3774874)
+ 3 - C, 20% to 80% of 2^24 (3355443 .. 13421773)
+ enum: [1, 2, 3]
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ honeywell,pressure-triplet:
+ description: |
+ Case-sensitive five character string that defines pressure range, unit
+ and type as part of the device nomenclature. In the unlikely case of a
+ custom chip, unset and provide pmin-pascal and pmax-pascal instead.
+ enum: [0001BA, 01.6BA, 02.5BA, 0060MG, 0100MG, 0160MG, 0250MG, 0400MG,
+ 0600MG, 0001BG, 01.6BG, 02.5BG, 0100KA, 0160KA, 0250KA, 0006KG,
+ 0010KG, 0016KG, 0025KG, 0040KG, 0060KG, 0100KG, 0160KG, 0250KG,
+ 0015PA, 0025PA, 0030PA, 0001PG, 0005PG, 0015PG, 0030PG, 0300YG]
+ $ref: /schemas/types.yaml#/definitions/string
+
+ honeywell,pmin-pascal:
+ description:
+ Minimum pressure value the sensor can measure in pascal.
+
+ honeywell,pmax-pascal:
+ description:
+ Maximum pressure value the sensor can measure in pascal.
+
+ spi-max-frequency:
+ maximum: 800000
+
+ vdd-supply:
+ description: provide VDD power to the sensor.
+
+required:
+ - compatible
+ - reg
+ - honeywell,transfer-function
+ - vdd-supply
+
+oneOf:
+ - required:
+ - honeywell,pressure-triplet
+ - required:
+ - honeywell,pmin-pascal
+ - honeywell,pmax-pascal
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml
+ - if:
+ required:
+ - honeywell,pressure-triplet
+ then:
+ properties:
+ honeywell,pmin-pascal: false
+ honeywell,pmax-pascal: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pressure@18 {
+ compatible = "honeywell,mprls0025pa";
+ reg = <0x18>;
+ reset-gpios = <&gpio3 19 GPIO_ACTIVE_HIGH>;
+ interrupt-parent = <&gpio3>;
+ interrupts = <21 IRQ_TYPE_EDGE_RISING>;
+
+ honeywell,pressure-triplet = "0025PA";
+ honeywell,transfer-function = <1>;
+ vdd-supply = <&vcc_3v3>;
+ };
+ };
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pressure@0 {
+ compatible = "honeywell,mprls0025pa";
+ reg = <0>;
+ spi-max-frequency = <800000>;
+ reset-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <30 IRQ_TYPE_EDGE_RISING>;
+
+ honeywell,pressure-triplet = "0015PA";
+ honeywell,transfer-function = <1>;
+ vdd-supply = <&vcc_3v3>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/pressure/infineon,dps310.yaml b/Documentation/devicetree/bindings/iio/pressure/infineon,dps310.yaml
new file mode 100644
index 000000000000..e5d1e6c48939
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/infineon,dps310.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/infineon,dps310.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Infineon DPS310 barometric pressure and temperature sensor
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The DPS310 is a barometric pressure and temperature sensor with an I2C
+ interface.
+
+properties:
+ compatible:
+ enum:
+ - infineon,dps310
+
+ reg:
+ maxItems: 1
+
+ "#io-channel-cells":
+ const: 0
+
+ vdd-supply:
+ description:
+ Voltage supply for the chip's analog blocks.
+
+ vddio-supply:
+ description:
+ Digital voltage supply for the chip's digital blocks and I/O interface.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ dps: pressure-sensor@76 {
+ compatible = "infineon,dps310";
+ reg = <0x76>;
+ #io-channel-cells = <0>;
+ vdd-supply = <&vref1>;
+ vddio-supply = <&vref2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/pressure/invensense,icp10100.yaml b/Documentation/devicetree/bindings/iio/pressure/invensense,icp10100.yaml
new file mode 100644
index 000000000000..5d980aa04bb3
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/invensense,icp10100.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/invensense,icp10100.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: InvenSense ICP-101xx Barometric Pressure Sensors
+
+maintainers:
+ - Jean-Baptiste Maneyrol <jean-baptiste.maneyrol@tdk.com>
+
+description: |
+ Support for ICP-101xx family: ICP-10100, ICP-10101, ICP-10110, ICP-10111.
+ Those devices uses a simple I2C communication bus, measuring the pressure
+ in a ultra-low noise at the lowest power.
+ Datasheet: https://product.tdk.com/system/files/dam/doc/product/sensor/pressure/capacitive-pressure/data_sheet/ds-000186-icp-101xx.pdf
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - invensense,icp10101
+ - invensense,icp10110
+ - invensense,icp10111
+ - const: invensense,icp10100
+ - const: invensense,icp10100
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pressure@63 {
+ compatible = "invensense,icp10101", "invensense,icp10100";
+ reg = <0x63>;
+ vdd-supply = <&vdd_1v8>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/pressure/meas,ms5611.yaml b/Documentation/devicetree/bindings/iio/pressure/meas,ms5611.yaml
index 4f06707450bf..21e6ddb7f41e 100644
--- a/Documentation/devicetree/bindings/iio/pressure/meas,ms5611.yaml
+++ b/Documentation/devicetree/bindings/iio/pressure/meas,ms5611.yaml
@@ -30,7 +30,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -52,6 +55,7 @@ examples:
compatible = "meas,ms5611";
reg = <0>;
vdd-supply = <&ldo_3v3_gnss>;
+ spi-max-frequency = <20000000>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/pressure/murata,zpa2326.yaml b/Documentation/devicetree/bindings/iio/pressure/murata,zpa2326.yaml
index d6103be03460..886f4129c301 100644
--- a/Documentation/devicetree/bindings/iio/pressure/murata,zpa2326.yaml
+++ b/Documentation/devicetree/bindings/iio/pressure/murata,zpa2326.yaml
@@ -12,7 +12,6 @@ maintainers:
description: |
Pressure sensor from Murata with SPI and I2C bus interfaces.
-
properties:
compatible:
const: murata,zpa2326
@@ -33,7 +32,10 @@ required:
- compatible
- reg
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml b/Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml
new file mode 100644
index 000000000000..7c4ca6322bf8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/rohm,bm1390.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BM1390 pressure sensor
+
+maintainers:
+ - Matti Vaittinen <mazziesaccount@gmail.com>
+
+description:
+ BM1390GLV-Z is a pressure sensor which performs internal temperature
+ compensation for the MEMS. Pressure range is from 300 hPa to 1300 hPa
+ and sample averaging and IIR filtering is built in. Temperature
+ measurement is also supported.
+
+properties:
+ compatible:
+ const: rohm,bm1390glv-z
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pressure-sensor@5d {
+ compatible = "rohm,bm1390glv-z";
+ reg = <0x5d>;
+
+ interrupt-parent = <&gpio1>;
+ interrupts = <29 IRQ_TYPE_LEVEL_LOW>;
+
+ vdd-supply = <&vdd>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/pressure/sensirion,sdp500.yaml b/Documentation/devicetree/bindings/iio/pressure/sensirion,sdp500.yaml
new file mode 100644
index 000000000000..813239f6879a
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/pressure/sensirion,sdp500.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/pressure/sensirion,sdp500.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: sdp500/sdp510 pressure sensor with I2C bus interface
+
+maintainers:
+ - Petar Stoykov <petar.stoykov@prodrive-technologies.com>
+
+description: |
+ Pressure sensor from Sensirion with I2C bus interface.
+ There is no software difference between sdp500 and sdp510.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: sensirion,sdp510
+ - const: sensirion,sdp500
+ - const: sensirion,sdp500
+
+ reg:
+ maxItems: 1
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ pressure@40 {
+ compatible = "sensirion,sdp500";
+ reg = <0x40>;
+ vdd-supply = <&foo>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml b/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml
index 7fcba5d6d508..9567993ce480 100644
--- a/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml
+++ b/Documentation/devicetree/bindings/iio/proximity/ams,as3935.yaml
@@ -10,7 +10,7 @@ maintainers:
- Matt Ranostay <matt.ranostay@konsulko.com>
description:
- This lightening distance sensor uses an I2C or SPI interface. The
+ This lightning distance sensor uses an I2C or SPI interface. The
binding currently only covers the SPI option.
properties:
@@ -49,7 +49,10 @@ required:
- spi-cpha
- interrupts
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
@@ -57,7 +60,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- lightning@0 {
+ lightning@0 {
compatible = "ams,as3935";
reg = <0>;
spi-max-frequency = <400000>;
diff --git a/Documentation/devicetree/bindings/iio/proximity/awinic,aw96103.yaml b/Documentation/devicetree/bindings/iio/proximity/awinic,aw96103.yaml
new file mode 100644
index 000000000000..7a83ceced11c
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/proximity/awinic,aw96103.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/proximity/awinic,aw96103.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Awinic's AW96103 capacitive proximity sensor and similar
+
+maintainers:
+ - Wang Shuaijie <wangshuaijie@awinic.com>
+
+description: |
+ Awinic's AW96103/AW96105 proximity sensor.
+ The specific absorption rate (SAR) is a metric that measures
+ the degree of absorption of electromagnetic radiation emitted by
+ wireless devices, such as mobile phones and tablets, by human tissue.
+ In mobile phone applications, the proximity sensor is primarily
+ used to detect the proximity of the human body to the phone. When the
+ phone approaches the human body, it will actively reduce the transmit
+ power of the antenna to keep the SAR within a safe range. Therefore,
+ we also refer to the proximity sensor as a SAR sensor.
+
+properties:
+ compatible:
+ enum:
+ - awinic,aw96103
+ - awinic,aw96105
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Generated by the device to announce that a close/far
+ proximity event has happened.
+ maxItems: 1
+
+ vcc-supply: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - vcc-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ proximity@12 {
+ compatible = "awinic,aw96103";
+ reg = <0x12>;
+ interrupt-parent = <&gpio>;
+ interrupts = <23 IRQ_TYPE_EDGE_FALLING>;
+ vcc-supply = <&pp1800_prox>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml
index 099b4be927d4..d4e09d2dcd21 100644
--- a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml
+++ b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-
$id: http://devicetree.org/schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
@@ -10,7 +9,6 @@ title: ChromeOS EC MKBP Proximity Sensor
maintainers:
- Stephen Boyd <swboyd@chromium.org>
- Benson Leung <bleung@chromium.org>
- - Enric Balletbo i Serra <enric.balletbo@collabora.com>
description: |
Google's ChromeOS EC sometimes has the ability to detect user proximity.
diff --git a/Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml b/Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml
new file mode 100644
index 000000000000..67f5389ece67
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/proximity/murata,irsd200.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/proximity/murata,irsd200.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Murata IRS-D200 PIR sensor
+
+maintainers:
+ - Waqar Hameed <waqar.hameed@axis.com>
+
+description:
+ PIR sensor for human detection.
+
+properties:
+ compatible:
+ const: murata,irsd200
+
+ reg:
+ items:
+ - enum:
+ - 0x48
+ - 0x49
+ description: |
+ When the AD pin is connected to GND, the slave address is 0x48.
+ When the AD pin is connected to VDD, the slave address is 0x49.
+
+ interrupts:
+ maxItems: 1
+ description:
+ Type should be IRQ_TYPE_EDGE_RISING.
+
+ vdd-supply:
+ description:
+ 3.3 V supply voltage.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ proximity@48 {
+ compatible = "murata,irsd200";
+ reg = <0x48>;
+ interrupts = <24 IRQ_TYPE_EDGE_RISING>;
+ vdd-supply = <&regulator_3v3>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/proximity/nicera,d3323aa.yaml b/Documentation/devicetree/bindings/iio/proximity/nicera,d3323aa.yaml
new file mode 100644
index 000000000000..65d9b44fcd5e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/proximity/nicera,d3323aa.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/proximity/nicera,d3323aa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nicera D3-323-AA PIR sensor
+
+maintainers:
+ - Waqar Hameed <waqar.hameed@axis.com>
+
+description: |
+ PIR sensor for human detection.
+ Datasheet: https://www.endrich.com/Datenbl%C3%A4tter/Sensoren/D3-323-AA_e.pdf
+
+properties:
+ compatible:
+ const: nicera,d3323aa
+
+ vdd-supply:
+ description:
+ Supply voltage (1.8 to 5.5 V).
+
+ vout-clk-gpios:
+ maxItems: 1
+ description:
+ GPIO for clock and detection.
+ After reset, the device signals with two falling edges on this pin that it
+ is ready for configuration (within 1.2 s).
+ During configuration, it is used as clock for data reading and writing (on
+ data-gpios).
+ After all this, when device is in operational mode, it signals on this pin
+ for any detections.
+
+ data-gpios:
+ maxItems: 1
+ description:
+ GPIO for data reading and writing. This is denoted "DO (SI)" in datasheet.
+ During configuration, this pin is used for writing and reading
+ configuration data (together with vout-clk-gpios as clock).
+ After this, during operational mode, the device will output serial data on
+ this GPIO.
+
+required:
+ - compatible
+ - vdd-supply
+ - vout-clk-gpios
+ - data-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ proximity {
+ compatible = "nicera,d3323aa";
+ vdd-supply = <&regulator_3v3>;
+ vout-clk-gpios = <&gpio 78 GPIO_ACTIVE_HIGH>;
+ data-gpios = <&gpio 76 GPIO_ACTIVE_HIGH>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml
index 5de0bb2180e6..775555d147bf 100644
--- a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml
+++ b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9310.yaml
@@ -15,6 +15,9 @@ description: |
Specifications about the devices can be found at:
https://www.semtech.com/products/smart-sensing/sar-sensors/sx9310
+allOf:
+ - $ref: /schemas/iio/iio.yaml#
+
properties:
compatible:
enum:
@@ -102,7 +105,7 @@ required:
- reg
- "#io-channel-cells"
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml
new file mode 100644
index 000000000000..8fed45ee557b
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9324.yaml
@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/proximity/semtech,sx9324.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Semtech's SX9324 capacitive proximity sensor
+
+maintainers:
+ - Gwendal Grignou <gwendal@chromium.org>
+ - Daniel Campello <campello@chromium.org>
+
+description: |
+ Semtech's SX9324 proximity sensor.
+
+allOf:
+ - $ref: /schemas/iio/iio.yaml#
+
+properties:
+ compatible:
+ const: semtech,sx9324
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Generated by device to announce preceding read request has finished
+ and data is available or that a close/far proximity event has happened.
+ maxItems: 1
+
+ vdd-supply:
+ description: Main power supply
+
+ svdd-supply:
+ description: Host interface power supply
+
+ "#io-channel-cells":
+ const: 1
+
+ semtech,ph0-pin:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: |
+ Array of 3 entries. Index represent the id of the CS pin.
+ Value indicates how each CS pin is used during phase 0.
+ Each of the 3 pins have the following value -
+ 0 : unused (high impedance)
+ 1 : measured input
+ 2 : dynamic shield
+ 3 : grounded.
+ For instance, CS0 measured, CS1 shield and CS2 ground is [1, 2, 3]
+ items:
+ enum: [ 0, 1, 2, 3 ]
+ minItems: 3
+ maxItems: 3
+
+ semtech,ph1-pin:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: Same as ph0-pin for phase 1.
+ items:
+ enum: [ 0, 1, 2, 3 ]
+ minItems: 3
+ maxItems: 3
+
+ semtech,ph2-pin:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: Same as ph0-pin for phase 2.
+ items:
+ enum: [ 0, 1, 2, 3 ]
+ minItems: 3
+ maxItems: 3
+
+ semtech,ph3-pin:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: Same as ph0-pin for phase 3.
+ items:
+ enum: [ 0, 1, 2, 3 ]
+ minItems: 3
+ maxItems: 3
+
+ semtech,ph01-resolution:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [8, 16, 32, 64, 128, 256, 512, 1024]
+ description:
+ Capacitance measurement resolution. For phase 0 and 1.
+ Higher the number, higher the resolution.
+ default: 128
+
+ semtech,ph23-resolution:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [8, 16, 32, 64, 128, 256, 512, 1024]
+ description:
+ Capacitance measurement resolution. For phase 2 and 3
+ default: 128
+
+ semtech,startup-sensor:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ default: 0
+ description: |
+ Phase used for start-up proximity detection.
+ It is used when we enable a phase to remove static offset and measure
+ only capacitance changes introduced by the user.
+
+ semtech,ph01-proxraw-strength:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 7
+ default: 1
+ description:
+ PROXRAW filter strength for phase 0 and 1. A value of 0 represents off,
+ and other values represent 1-1/2^N.
+
+ semtech,ph23-proxraw-strength:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 7
+ default: 1
+ description:
+ Same as proxraw-strength01, for phase 2 and 3.
+
+ semtech,avg-pos-strength:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 16, 64, 128, 256, 512, 1024, 4294967295]
+ default: 16
+ description: |
+ Average positive filter strength. A value of 0 represents off and
+ UINT_MAX (4294967295) represents infinite. Other values
+ represent 1-1/N.
+
+ semtech,cs-idle-sleep:
+ description:
+ State of CS pins during sleep mode and idle time.
+ enum:
+ - hi-z
+ - gnd
+ - vdd
+
+ semtech,int-comp-resistor:
+ description:
+ Internal resistor setting for compensation.
+ enum:
+ - lowest
+ - low
+ - high
+ - highest
+
+ semtech,input-precharge-resistor-ohms:
+ default: 4000
+ multipleOf: 2000
+ minimum: 0
+ maximum: 30000
+ description:
+ Pre-charge input resistance in Ohm.
+
+ semtech,input-analog-gain:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 3
+ description: |
+ Defines the input antenna analog gain
+ 0: x1.247
+ 1: x1 (default)
+ 2: x0.768
+ 3: x0.552
+
+required:
+ - compatible
+ - reg
+ - "#io-channel-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ proximity@28 {
+ compatible = "semtech,sx9324";
+ reg = <0x28>;
+ interrupt-parent = <&pio>;
+ interrupts = <5 IRQ_TYPE_LEVEL_LOW 5>;
+ vdd-supply = <&pp3300_a>;
+ svdd-supply = <&pp1800_prox>;
+ #io-channel-cells = <1>;
+ semtech,ph0-pin = <1 2 3>;
+ semtech,ph1-pin = <3 2 1>;
+ semtech,ph2-pin = <1 2 3>;
+ semtech,ph3-pin = <3 2 1>;
+ semtech,ph01-resolution = <256>;
+ semtech,ph23-resolution = <256>;
+ semtech,startup-sensor = <1>;
+ semtech,ph01-proxraw-strength = <2>;
+ semtech,ph23-proxraw-strength = <2>;
+ semtech,avg-pos-strength = <64>;
+ semtech,int-comp-resistor = "lowest";
+ semtech,input-precharge-resistor-ohms = <2000>;
+ semtech,cs-idle-sleep = "gnd";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml
new file mode 100644
index 000000000000..ad0bb44f41b6
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/proximity/semtech,sx9360.yaml
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/proximity/semtech,sx9360.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Semtech's SX9360 capacitive proximity sensor
+
+maintainers:
+ - Gwendal Grignou <gwendal@chromium.org>
+ - Daniel Campello <campello@chromium.org>
+
+description: |
+ Semtech's SX9360 proximity sensor.
+
+properties:
+ compatible:
+ const: semtech,sx9360
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Generated by device to announce preceding read request has finished
+ and data is available or that a close/far proximity event has happened.
+ maxItems: 1
+
+ vdd-supply:
+ description: Main power supply
+
+ svdd-supply:
+ description: Host interface power supply
+
+ "#io-channel-cells":
+ const: 1
+
+ semtech,resolution:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [8, 16, 32, 64, 128, 256, 512, 1024]
+ description:
+ Capacitance measurement resolution. For both phases, "reference" and
+ "measurement". Higher the number, higher the resolution.
+ default: 128
+
+ semtech,proxraw-strength:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 7
+ default: 1
+ description:
+ PROXRAW filter strength for both phases. A value of 0 represents off,
+ and other values represent 1-1/2^N.
+
+ semtech,avg-pos-strength:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 16, 64, 128, 256, 512, 1024, 4294967295]
+ default: 16
+ description: |
+ Average positive filter strength. A value of 0 represents off and
+ UINT_MAX (4294967295) represents infinite. Other values
+ represent 1-1/N.
+
+ semtech,input-precharge-resistor-ohms:
+ default: 0
+ multipleOf: 2000
+ minimum: 0
+ maximum: 30000
+ description:
+ Pre-charge input resistance in Ohm.
+
+required:
+ - compatible
+ - reg
+ - "#io-channel-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ proximity@28 {
+ compatible = "semtech,sx9360";
+ reg = <0x28>;
+ interrupt-parent = <&pio>;
+ interrupts = <5 IRQ_TYPE_LEVEL_LOW 5>;
+ vdd-supply = <&pp3300_a>;
+ svdd-supply = <&pp1800_prox>;
+ #io-channel-cells = <1>;
+ semtech,resolution = <256>;
+ semtech,proxraw-strength = <2>;
+ semtech,avg-pos-strength = <64>;
+ semtech,input-precharge-resistor-ohms = <4000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/proximity/st,vl53l0x.yaml b/Documentation/devicetree/bindings/iio/proximity/st,vl53l0x.yaml
index 656460d9d8c8..322befc41de6 100644
--- a/Documentation/devicetree/bindings/iio/proximity/st,vl53l0x.yaml
+++ b/Documentation/devicetree/bindings/iio/proximity/st,vl53l0x.yaml
@@ -19,6 +19,11 @@ properties:
interrupts:
maxItems: 1
+ reset-gpios:
+ maxItems: 1
+
+ vdd-supply: true
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/iio/proximity/tyhx,hx9023s.yaml b/Documentation/devicetree/bindings/iio/proximity/tyhx,hx9023s.yaml
new file mode 100644
index 000000000000..64ce8bc8bd36
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/proximity/tyhx,hx9023s.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/proximity/tyhx,hx9023s.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TYHX HX9023S capacitive proximity sensor
+
+maintainers:
+ - Yasin Lee <yasin.lee.x@gmail.com>
+
+description: |
+ TYHX HX9023S proximity sensor. Datasheet can be found here:
+ http://www.tianyihexin.com/ueditor/php/upload/file/20240614/1718336303992081.pdf
+
+properties:
+ compatible:
+ const: tyhx,hx9023s
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description:
+ Generated by device to announce preceding read request has finished
+ and data is available or that a close/far proximity event has happened.
+ maxItems: 1
+
+ vdd-supply: true
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^channel@[0-4]$":
+ $ref: /schemas/iio/adc/adc.yaml
+ type: object
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 4
+ description: The channel number.
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ proximity@2a {
+ compatible = "tyhx,hx9023s";
+ reg = <0x2a>;
+ interrupt-parent = <&pio>;
+ interrupts = <16 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&pp1800_prox>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ channel@0 {
+ reg = <0>;
+ single-channel = <0>;
+ };
+ channel@1 {
+ reg = <1>;
+ single-channel = <1>;
+ };
+ channel@2 {
+ reg = <2>;
+ single-channel = <2>;
+ };
+ channel@3 {
+ reg = <3>;
+ diff-channels = <1 0>;
+ };
+ channel@4 {
+ reg = <4>;
+ diff-channels = <2 0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml b/Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml
new file mode 100644
index 000000000000..8980b3cd8337
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/resolver/adi,ad2s1210.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD2S1210 Resolver-to-Digital Converter
+
+maintainers:
+ - Michael Hennerich <michael.hennerich@analog.com>
+
+description: |
+ The AD2S1210 is a complete 10-bit to 16-bit resolution tracking
+ resolver-to-digital converter, integrating an on-board programmable
+ sinusoidal oscillator that provides sine wave excitation for
+ resolvers.
+
+ The AD2S1210 allows the user to read the angular position or the
+ angular velocity data directly from the parallel outputs or through
+ the serial interface.
+
+ The mode of operation of the communication channel (parallel or serial) is
+ selected by the A0 and A1 input pins. In normal mode, data is latched by
+ toggling the SAMPLE line and can then be read directly. In configuration mode,
+ data is read or written using a register access scheme (address byte with
+ read/write flag and data byte).
+
+ A1 A0 Result
+ 0 0 Normal mode - position output
+ 0 1 Normal mode - velocity output
+ 1 0 Reserved
+ 1 1 Configuration mode
+
+ In normal mode, the resolution of the digital output is selected using
+ the RES0 and RES1 input pins. In configuration mode, the resolution is
+ selected by setting the RES0 and RES1 bits in the control register.
+
+ RES1 RES0 Resolution (Bits)
+ 0 0 10
+ 0 1 12
+ 1 0 14
+ 1 1 16
+
+ Note on SPI connections: The CS line on the AD2S1210 should hard-wired to
+ logic low and the WR/FSYNC line on the AD2S1210 should be connected to the
+ SPI CSn output of the SPI controller.
+
+ Datasheet:
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ad2s1210.pdf
+
+properties:
+ compatible:
+ const: adi,ad2s1210
+
+ reg:
+ maxItems: 1
+
+ spi-max-frequency:
+ maximum: 25000000
+
+ spi-cpha: true
+
+ avdd-supply:
+ description:
+ A 4.75 to 5.25 V regulator that powers the Analog Supply Voltage (AVDD)
+ pin.
+
+ dvdd-supply:
+ description:
+ A 4.75 to 5.25 V regulator that powers the Digital Supply Voltage (DVDD)
+ pin.
+
+ vdrive-supply:
+ description:
+ A 2.3 to 5.25 V regulator that powers the Logic Power Supply Input
+ (VDrive) pin.
+
+ clocks:
+ maxItems: 1
+ description: External oscillator clock (CLKIN).
+
+ reset-gpios:
+ description:
+ GPIO connected to the /RESET pin. As the line needs to be low for the
+ reset to be active, it should be configured as GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ sample-gpios:
+ description:
+ GPIO connected to the /SAMPLE pin. As the line needs to be low to trigger
+ a sample, it should be configured as GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ mode-gpios:
+ description:
+ GPIO lines connected to the A0 and A1 pins. These pins select the data
+ transfer mode.
+ minItems: 2
+ maxItems: 2
+
+ resolution-gpios:
+ description:
+ GPIO lines connected to the RES0 and RES1 pins. These pins select the
+ resolution of the digital output. If omitted, it is assumed that the
+ RES0 and RES1 pins are hard-wired to match the assigned-resolution-bits
+ property.
+ minItems: 2
+ maxItems: 2
+
+ fault-gpios:
+ description:
+ GPIO lines connected to the LOT and DOS pins. These pins combined indicate
+ the type of fault present, if any. As these pins a pulled low to indicate
+ a fault condition, they should be configured as GPIO_ACTIVE_LOW.
+ minItems: 2
+ maxItems: 2
+
+ adi,fixed-mode:
+ description:
+ This is used to indicate the selected mode if A0 and A1 are hard-wired
+ instead of connected to GPIOS (i.e. mode-gpios is omitted).
+ $ref: /schemas/types.yaml#/definitions/string
+ enum: [config, velocity, position]
+
+ assigned-resolution-bits:
+ description:
+ Resolution of the digital output required by the application. This
+ determines the precision of the angle and/or the maximum speed that can
+ be measured. If resolution-gpios is omitted, it is assumed that RES0 and
+ RES1 are hard-wired to match this value.
+ enum: [10, 12, 14, 16]
+
+required:
+ - compatible
+ - reg
+ - spi-cpha
+ - avdd-supply
+ - dvdd-supply
+ - vdrive-supply
+ - clocks
+ - sample-gpios
+ - assigned-resolution-bits
+
+oneOf:
+ - required:
+ - mode-gpios
+ - required:
+ - adi,fixed-mode
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ resolver@0 {
+ compatible = "adi,ad2s1210";
+ reg = <0>;
+ spi-max-frequency = <20000000>;
+ spi-cpha;
+ avdd-supply = <&avdd_regulator>;
+ dvdd-supply = <&dvdd_regulator>;
+ vdrive-supply = <&vdrive_regulator>;
+ clocks = <&ext_osc>;
+ sample-gpios = <&gpio0 90 GPIO_ACTIVE_LOW>;
+ mode-gpios = <&gpio0 86 0>, <&gpio0 87 0>;
+ resolution-gpios = <&gpio0 88 0>, <&gpio0 89 0>;
+ assigned-resolution-bits = <16>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/resolver/adi,ad2s90.yaml b/Documentation/devicetree/bindings/iio/resolver/adi,ad2s90.yaml
index 81e4bdfc17c4..b24e5a202a48 100644
--- a/Documentation/devicetree/bindings/iio/resolver/adi,ad2s90.yaml
+++ b/Documentation/devicetree/bindings/iio/resolver/adi,ad2s90.yaml
@@ -33,8 +33,6 @@ properties:
spi-cpha: true
-additionalProperties: false
-
required:
- compatible
- reg
@@ -43,6 +41,11 @@ dependencies:
spi-cpol: [ spi-cpha ]
spi-cpha: [ spi-cpol ]
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
spi {
diff --git a/Documentation/devicetree/bindings/iio/samsung,sensorhub-rinato.yaml b/Documentation/devicetree/bindings/iio/samsung,sensorhub-rinato.yaml
index a88b3b14d6bd..dd2ae2bd1ad7 100644
--- a/Documentation/devicetree/bindings/iio/samsung,sensorhub-rinato.yaml
+++ b/Documentation/devicetree/bindings/iio/samsung,sensorhub-rinato.yaml
@@ -40,10 +40,6 @@ properties:
description:
Reset the sensorhub.
- spi-max-frequency: true
-
-additionalProperties: false
-
required:
- compatible
- reg
@@ -52,6 +48,11 @@ required:
- mcu-ap-gpios
- mcu-reset-gpios
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
examples:
- |
spi {
diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml
index b2a1e42c56fa..e955eb8e8797 100644
--- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml
+++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml
@@ -11,9 +11,6 @@ description: The STMicroelectronics sensor devices are pretty straight-forward
what type of sensor it is.
Note that whilst this covers many STMicro MEMs sensors, some more complex
IMUs need their own bindings.
- The STMicroelectronics sensor devices are pretty straight-forward I2C or
- SPI devices, all sharing the same device tree descriptions no matter what
- type of sensor it is.
maintainers:
- Denis Ciocca <denis.ciocca@st.com>
@@ -29,6 +26,8 @@ properties:
- st,lis2dw12
- st,lis2hh12
- st,lis2dh12-accel
+ - st,lis2ds12
+ - st,lis302dl
- st,lis331dl-accel
- st,lis331dlh-accel
- st,lis3de
@@ -38,6 +37,7 @@ properties:
- st,lis3lv02dl-accel
- st,lng2dm-accel
- st,lsm303agr-accel
+ - st,lsm303c-accel
- st,lsm303dl-accel
- st,lsm303dlh-accel
- st,lsm303dlhc-accel
@@ -46,6 +46,12 @@ properties:
- st,lsm330d-accel
- st,lsm330dl-accel
- st,lsm330dlc-accel
+ - items:
+ - const: st,iis328dq
+ - const: st,h3lis331dl-accel
+ - description: Silan Accelerometers
+ enum:
+ - silan,sc7a20
- description: STMicroelectronics Gyroscopes
enum:
- st,l3g4200d-gyro
@@ -59,9 +65,11 @@ properties:
- st,lsm9ds0-gyro
- description: STMicroelectronics Magnetometers
enum:
+ - st,iis2mdc
- st,lis2mdl
- st,lis3mdl-magn
- st,lsm303agr-magn
+ - st,lsm303c-magn
- st,lsm303dlh-magn
- st,lsm303dlhc-magn
- st,lsm303dlm-magn
@@ -69,6 +77,7 @@ properties:
- description: STMicroelectronics Pressure Sensors
enum:
- st,lps001wp-press
+ - st,lps22df
- st,lps22hb-press
- st,lps22hh
- st,lps25h-press
@@ -77,6 +86,7 @@ properties:
- st,lps35hw
- description: IMUs
enum:
+ - st,lsm303d-imu
- st,lsm9ds0-imu
- description: Deprecated bindings
enum:
@@ -89,7 +99,7 @@ properties:
interrupts:
description: interrupt line(s) connected to the DRDY line(s) and/or the
- Intertial interrupt lines INT1 and INT2 if these exist. This means up to
+ Inertial interrupt lines INT1 and INT2 if these exist. This means up to
three interrupts, and the DRDY must be the first one if it exists on
the package. The trigger edge of the interrupts is sometimes software
configurable in the hardware so the operating system should parse this
@@ -137,6 +147,7 @@ allOf:
- st,lis2mdl
- st,lis3l02dq
- st,lis3lv02dl-accel
+ - st,lps22df
- st,lps22hb-press
- st,lps22hh
- st,lps25h-press
@@ -152,47 +163,6 @@ allOf:
maxItems: 1
st,drdy-int-pin: false
- - if:
- properties:
- compatible:
- enum:
- # Two intertial interrupts i.e. accelerometer/gyro interrupts
- - st,h3lis331dl-accel
- - st,l3g4200d-gyro
- - st,l3g4is-gyro
- - st,l3gd20-gyro
- - st,l3gd20h-gyro
- - st,lis2de12
- - st,lis2dw12
- - st,lis2hh12
- - st,lis2dh12-accel
- - st,lis331dl-accel
- - st,lis331dlh-accel
- - st,lis3de
- - st,lis3dh-accel
- - st,lis3dhh
- - st,lis3mdl-magn
- - st,lng2dm-accel
- - st,lps331ap-press
- - st,lsm303agr-accel
- - st,lsm303dlh-accel
- - st,lsm303dlhc-accel
- - st,lsm303dlm-accel
- - st,lsm330-accel
- - st,lsm330-gyro
- - st,lsm330d-accel
- - st,lsm330d-gyro
- - st,lsm330dl-accel
- - st,lsm330dl-gyro
- - st,lsm330dlc-accel
- - st,lsm330dlc-gyro
- - st,lsm9ds0-gyro
- - st,lsm9ds1-magn
- then:
- properties:
- interrupts:
- maxItems: 2
-
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml
index 0f79d9a01c49..a22725f7619b 100644
--- a/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml
+++ b/Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml
@@ -4,19 +4,51 @@
$id: http://devicetree.org/schemas/iio/temperature/adi,ltc2983.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Analog Devices LTC2983 Multi-sensor Temperature system
+title: Analog Devices LTC2983, LTC2986, LTM2985 Multi-sensor Temperature system
maintainers:
- Nuno Sá <nuno.sa@analog.com>
description: |
- Analog Devices LTC2983 Multi-Sensor Digital Temperature Measurement System
+ Analog Devices LTC2983, LTC2984, LTC2986, LTM2985 Multi-Sensor Digital
+ Temperature Measurement Systems
+
https://www.analog.com/media/en/technical-documentation/data-sheets/2983fc.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/2984fb.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/29861fa.pdf
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ltm2985.pdf
+
+$defs:
+ sensor-node:
+ type: object
+ description: Sensor node common constraints
+
+ properties:
+ reg:
+ description:
+ Channel number. Connects the sensor to the channel with this number
+ of the device.
+ minimum: 1
+ maximum: 20
+
+ adi,sensor-type:
+ description: Type of sensor connected to the device.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ required:
+ - reg
+ - adi,sensor-type
properties:
compatible:
- enum:
- - adi,ltc2983
+ oneOf:
+ - enum:
+ - adi,ltc2983
+ - adi,ltc2986
+ - adi,ltm2985
+ - items:
+ - const: adi,ltc2984
+ - const: adi,ltc2983
reg:
maxItems: 1
@@ -24,27 +56,29 @@ properties:
interrupts:
maxItems: 1
+ vdd-supply: true
+
adi,mux-delay-config-us:
- description:
- The LTC2983 performs 2 or 3 internal conversion cycles per temperature
- result. Each conversion cycle is performed with different excitation and
- input multiplexer configurations. Prior to each conversion, these
- excitation circuits and input switch configurations are changed and an
- internal 1ms delay ensures settling prior to the conversion cycle in most
- cases. An extra delay can be configured using this property. The value is
- rounded to nearest 100us.
+ description: |
+ Extra delay prior to each conversion, in addition to the internal 1ms
+ delay, for the multiplexer to switch input configurations and
+ excitation values.
+
+ This property is supposed to be in microseconds, but to maintain
+ compatibility, this value will be multiplied by 100 before usage.
maximum: 255
+ default: 0
adi,filter-notch-freq:
description:
- Set's the default setting of the digital filter. The default is
- simultaneous 50/60Hz rejection.
+ Notch frequency of the digital filter.
0 - 50/60Hz rejection
1 - 60Hz rejection
2 - 50Hz rejection
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 2
+ default: 0
'#address-cells':
const: 1
@@ -53,30 +87,11 @@ properties:
const: 0
patternProperties:
- "@([1-9]|1[0-9]|20)$":
- type: object
-
- properties:
- reg:
- description:
- The channel number. It can be connected to one of the 20 channels of
- the device.
- minimum: 1
- maximum: 20
-
- adi,sensor-type:
- description: Identifies the type of sensor connected to the device.
- $ref: /schemas/types.yaml#/definitions/uint32
-
- required:
- - reg
- - adi,sensor-type
+ '^thermocouple@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
- "^thermocouple@":
- type: object
- description:
- Represents a thermocouple sensor which is connected to one of the device
- channels.
+ description: Thermocouple sensor.
properties:
adi,sensor-type:
@@ -95,86 +110,90 @@ patternProperties:
maximum: 9
adi,single-ended:
- description:
- Boolean property which set's the thermocouple as single-ended.
+ description: Whether the sensor is single-ended.
type: boolean
adi,sensor-oc-current-microamp:
- description:
- This property set's the pulsed current value applied during
- open-circuit detect.
+ description: Pulsed current value applied during open-circuit detect.
enum: [10, 100, 500, 1000]
+ default: 10
adi,cold-junction-handle:
description:
- Phandle which points to a sensor object responsible for measuring
- the thermocouple cold junction temperature.
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ Sensor responsible for measuring the thermocouple cold junction
+ temperature.
+ $ref: /schemas/types.yaml#/definitions/phandle
adi,custom-thermocouple:
description:
- This is a table, where each entry should be a pair of
- voltage(mv)-temperature(K). The entries must be given in nv and uK
- so that, the original values must be multiplied by 1000000. For
- more details look at table 69 and 70.
- Note should be signed, but dtc doesn't currently maintain the
- sign.
- $ref: /schemas/types.yaml#/definitions/uint64-matrix
+ Used for digitizing custom thermocouples.
+ See Page 59 of the datasheet.
+ $ref: /schemas/types.yaml#/definitions/int64-matrix
minItems: 3
maxItems: 64
items:
- minItems: 2
- maxItems: 2
+ items:
+ - description: Voltage point in nV, signed.
+ - description: Temperature point in uK.
- "^diode@":
- type: object
- description:
- Represents a diode sensor which is connected to one of the device
- channels.
+ allOf:
+ - if:
+ properties:
+ adi,sensor-type:
+ const: 9
+ then:
+ required:
+ - adi,custom-thermocouple
+
+ '^diode@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
+
+ description: Diode sensor.
properties:
adi,sensor-type:
- description: Identifies the sensor as a diode.
+ description: Sensor type for diodes.
$ref: /schemas/types.yaml#/definitions/uint32
const: 28
adi,single-ended:
- description: Boolean property which set's the diode as single-ended.
+ description: Whether the sensor is single-ended.
type: boolean
adi,three-conversion-cycles:
description:
- Boolean property which set's three conversion cycles removing
- parasitic resistance effects between the LTC2983 and the diode.
+ Whether to use three conversion cycles to remove parasitic
+ resistance between the device and the diode.
type: boolean
adi,average-on:
description:
- Boolean property which enables a running average of the diode
- temperature reading. This reduces the noise when the diode is used
- as a cold junction temperature element on an isothermal block
- where temperatures change slowly.
+ Whether to use a running average of the diode temperature
+ reading to reduce the noise when the diode is used as a cold
+ junction temperature element on an isothermal block where
+ temperatures change slowly.
type: boolean
adi,excitation-current-microamp:
description:
- This property controls the magnitude of the excitation current
- applied to the diode. Depending on the number of conversions
- cycles, this property will assume different predefined values on
- each cycle. Just set the value of the first cycle (1l).
+ Magnitude of the 1l excitation current applied to the diode.
+ 4l excitation current will be 4 times this value, and 8l
+ excitation current will be 8 times value.
enum: [10, 20, 40, 80]
+ default: 10
adi,ideal-factor-value:
description:
- This property sets the diode ideality factor. The real value must
- be multiplied by 1000000 to remove the fractional part. For more
- information look at table 20 of the datasheet.
+ Diode ideality factor.
+ Set this property to 1000000 times the real value.
$ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
- "^rtd@":
- type: object
- description:
- Represents a rtd sensor which is connected to one of the device channels.
+ '^rtd@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
+ description: RTD sensor.
properties:
reg:
@@ -197,68 +216,83 @@ patternProperties:
maximum: 18
adi,rsense-handle:
- description:
- Phandle pointing to a rsense object associated with this RTD.
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ description: Associated sense resistor sensor.
+ $ref: /schemas/types.yaml#/definitions/phandle
adi,number-of-wires:
description:
- Identifies the number of wires used by the RTD. Setting this
- property to 5 means 4 wires with Kelvin Rsense.
+ Number of wires used by the RTD.
+ 5 means 4 wires with Kelvin sense resistor.
$ref: /schemas/types.yaml#/definitions/uint32
enum: [2, 3, 4, 5]
+ default: 2
adi,rsense-share:
description:
- Boolean property which enables Rsense sharing, where one sense
- resistor is used for multiple 2-, 3-, and/or 4-wire RTDs.
- type: boolean
-
- adi,current-rotate:
- description:
- Boolean property which enables excitation current rotation to
- automatically remove parasitic thermocouple effects. Note that
- this property is not allowed for 2- and 3-wire RTDs.
+ Whether to enable sense resistor sharing, where one sense
+ resistor is used by multiple sensors.
type: boolean
adi,excitation-current-microamp:
- description:
- This property controls the magnitude of the excitation current
- applied to the RTD.
+ description: Excitation current applied to the RTD.
enum: [5, 10, 25, 50, 100, 250, 500, 1000]
+ default: 5
adi,rtd-curve:
- description:
- This property set the RTD curve used and the corresponding
- Callendar-VanDusen constants. Look at table 30 of the datasheet.
+ description: |
+ RTD curve and the corresponding Callendar-VanDusen constants.
+ 0 - European
+ 1 - American
+ 2 - Japanese
+ 3 - ITS-90
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 3
+ default: 0
adi,custom-rtd:
description:
- This is a table, where each entry should be a pair of
- resistance(ohm)-temperature(K). The entries added here are in uohm
- and uK. For more details values look at table 74 and 75.
+ Used for digitizing custom RTDs.
+ See Page 62 of the datasheet.
$ref: /schemas/types.yaml#/definitions/uint64-matrix
+ minItems: 3
+ maxItems: 64
items:
- minItems: 3
- maxItems: 64
items:
- minItems: 2
- maxItems: 2
+ - description: Resistance point in uOhms.
+ - description: Temperature point in uK.
required:
- adi,rsense-handle
- dependencies:
- adi,current-rotate: [ "adi,rsense-share" ]
-
- "^thermistor@":
- type: object
- description:
- Represents a thermistor sensor which is connected to one of the device
- channels.
+ allOf:
+ - if:
+ properties:
+ adi,number-of-wires:
+ const: 4
+ then:
+ properties:
+ adi,current-rotate:
+ description:
+ Whether to enable excitation current rotation to automatically
+ remove parasitic thermocouple effects.
+ type: boolean
+
+ dependencies:
+ adi,current-rotate: [ 'adi,rsense-share' ]
+
+ - if:
+ properties:
+ adi,sensor-type:
+ const: 18
+ then:
+ required:
+ - adi,custom-rtd
+
+ '^thermistor@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
+ description: Thermistor sensor.
properties:
adi,sensor-type:
@@ -277,87 +311,135 @@ patternProperties:
maximum: 27
adi,rsense-handle:
- description:
- Phandle pointing to a rsense object associated with this
- thermistor.
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ description: Associated sense resistor sensor.
+ $ref: /schemas/types.yaml#/definitions/phandle
adi,single-ended:
- description:
- Boolean property which set's the thermistor as single-ended.
+ description: Whether the sensor is single-ended.
type: boolean
adi,rsense-share:
description:
- Boolean property which enables Rsense sharing, where one sense
- resistor is used for multiple thermistors. Note that this property
- is ignored if adi,single-ended is set.
+ Whether to enable sense resistor sharing, where one sense
+ resistor is used by multiple sensors.
type: boolean
adi,current-rotate:
description:
- Boolean property which enables excitation current rotation to
- automatically remove parasitic thermocouple effects.
+ Whether to enable excitation current rotation to automatically
+ remove parasitic thermocouple effects.
type: boolean
adi,excitation-current-nanoamp:
description:
- This property controls the magnitude of the excitation current
- applied to the thermistor. Value 0 set's the sensor in auto-range
- mode.
- $ref: /schemas/types.yaml#/definitions/uint32
+ Excitation current applied to the thermistor.
+ 0 sets the sensor in auto-range mode.
enum: [0, 250, 500, 1000, 5000, 10000, 25000, 50000, 100000, 250000,
500000, 1000000]
+ default: 0
adi,custom-thermistor:
description:
- This is a table, where each entry should be a pair of
- resistance(ohm)-temperature(K). The entries added here are in uohm
- and uK only for custom thermistors. For more details look at table
- 78 and 79.
+ Used for digitizing custom thermistors.
+ See Page 65 of the datasheet.
$ref: /schemas/types.yaml#/definitions/uint64-matrix
minItems: 3
maxItems: 64
items:
- minItems: 2
- maxItems: 2
+ items:
+ - description: Resistance point in uOhms.
+ - description: Temperature point in uK.
adi,custom-steinhart:
description:
- Steinhart-Hart coefficients are also supported and can
- be programmed into the device memory using this property. For
- Steinhart sensors the coefficients are given in the raw
- format. Look at table 82 for more information.
+ Steinhart-Hart coefficients in raw format, used for digitizing
+ custom thermistors.
+ See Page 68 of the datasheet.
$ref: /schemas/types.yaml#/definitions/uint32-array
- items:
- minItems: 6
- maxItems: 6
+ minItems: 6
+ maxItems: 6
required:
- adi,rsense-handle
dependencies:
- adi,current-rotate: [ "adi,rsense-share" ]
-
- "^adc@":
- type: object
- description: Represents a channel which is being used as a direct adc.
+ adi,current-rotate: [ 'adi,rsense-share' ]
+
+ allOf:
+ - if:
+ properties:
+ adi,sensor-type:
+ const: 26
+ then:
+ properties:
+ adi,excitation-current-nanoamp:
+ enum: [250, 500, 1000, 5000, 10000, 25000, 50000, 100000,
+ 250000, 500000, 1000000]
+ default: 1000
+ required:
+ - adi,custom-steinhart
+ - if:
+ properties:
+ adi,sensor-type:
+ const: 27
+ then:
+ properties:
+ adi,excitation-current-nanoamp:
+ enum: [250, 500, 1000, 5000, 10000, 25000, 50000, 100000,
+ 250000, 500000, 1000000]
+ default: 1000
+ required:
+ - adi,custom-thermistor
+
+ '^adc@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
+ description: Direct ADC sensor.
properties:
adi,sensor-type:
- description: Identifies the sensor as a direct adc.
+ description: Sensor type for direct ADC sensors.
$ref: /schemas/types.yaml#/definitions/uint32
const: 30
adi,single-ended:
- description: Boolean property which set's the adc as single-ended.
+ description: Whether the sensor is single-ended.
type: boolean
- "^rsense@":
- type: object
- description:
- Represents a rsense which is connected to one of the device channels.
- Rsense are used by thermistors and RTD's.
+ '^temp@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
+ description: Active analog temperature sensor.
+
+ properties:
+ adi,sensor-type:
+ description: Sensor type for active analog temperature sensors.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ const: 31
+
+ adi,single-ended:
+ description: Whether the sensor is single-ended.
+ type: boolean
+
+ adi,custom-temp:
+ description:
+ Used for digitizing active analog temperature sensors.
+ See Page 67 of the LTM2985 datasheet.
+ $ref: /schemas/types.yaml#/definitions/uint64-matrix
+ minItems: 3
+ maxItems: 64
+ items:
+ items:
+ - description: Voltage point in nV, signed.
+ - description: Temperature point in uK.
+
+ required:
+ - adi,custom-temp
+
+ '^rsense@':
+ $ref: '#/$defs/sensor-node'
+ unevaluatedProperties: false
+ description: Sense resistor sensor.
properties:
reg:
@@ -365,14 +447,12 @@ patternProperties:
maximum: 20
adi,sensor-type:
- description: Identifies the sensor as a rsense.
+ description: Sensor type sense resistor sensors.
$ref: /schemas/types.yaml#/definitions/uint32
const: 29
adi,rsense-val-milli-ohms:
- description:
- Sets the value of the sense resistor. Look at table 20 of the
- datasheet for information.
+ description: Value of the sense resistor.
required:
- adi,rsense-val-milli-ohms
@@ -381,9 +461,22 @@ required:
- compatible
- reg
- interrupts
+ - vdd-supply
additionalProperties: false
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - adi,ltc2983
+ - adi,ltc2984
+ then:
+ patternProperties:
+ '^temp@': false
+
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
@@ -391,76 +484,76 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- sensor_ltc2983: ltc2983@0 {
- compatible = "adi,ltc2983";
- reg = <0>;
-
- #address-cells = <1>;
- #size-cells = <0>;
-
- interrupts = <20 IRQ_TYPE_EDGE_RISING>;
- interrupt-parent = <&gpio>;
-
- thermocouple@18 {
- reg = <18>;
- adi,sensor-type = <8>; //Type B
- adi,sensor-oc-current-microamp = <10>;
- adi,cold-junction-handle = <&diode5>;
- };
-
- diode5: diode@5 {
- reg = <5>;
- adi,sensor-type = <28>;
- };
-
- rsense2: rsense@2 {
- reg = <2>;
- adi,sensor-type = <29>;
- adi,rsense-val-milli-ohms = <1200000>; //1.2Kohms
- };
-
- rtd@14 {
- reg = <14>;
- adi,sensor-type = <15>; //PT1000
- /*2-wire, internal gnd, no current rotation*/
- adi,number-of-wires = <2>;
- adi,rsense-share;
- adi,excitation-current-microamp = <500>;
- adi,rsense-handle = <&rsense2>;
- };
-
- adc@10 {
- reg = <10>;
- adi,sensor-type = <30>;
- adi,single-ended;
- };
-
- thermistor@12 {
- reg = <12>;
- adi,sensor-type = <26>; //Steinhart
- adi,rsense-handle = <&rsense2>;
- adi,custom-steinhart = <0x00F371EC 0x12345678
- 0x2C0F8733 0x10018C66 0xA0FEACCD
- 0x90021D99>; //6 entries
- };
-
- thermocouple@20 {
- reg = <20>;
- adi,sensor-type = <9>; //custom thermocouple
- adi,single-ended;
- adi,custom-thermocouple = /bits/ 64
- <(-50220000) 0>,
- <(-30200000) 99100000>,
- <(-5300000) 135400000>,
- <0 273150000>,
- <40200000 361200000>,
- <55300000 522100000>,
- <88300000 720300000>,
- <132200000 811200000>,
- <188700000 922500000>,
- <460400000 1000000000>; //10 pairs
- };
-
+ temperature-sensor@0 {
+ compatible = "adi,ltc2983";
+ reg = <0>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vdd-supply = <&supply>;
+ interrupts = <20 IRQ_TYPE_EDGE_RISING>;
+ interrupt-parent = <&gpio>;
+
+ thermocouple@18 {
+ reg = <18>;
+ adi,sensor-type = <8>; //Type B
+ adi,sensor-oc-current-microamp = <10>;
+ adi,cold-junction-handle = <&diode5>;
+ };
+
+ diode5: diode@5 {
+ reg = <5>;
+ adi,sensor-type = <28>;
+ };
+
+ rsense2: rsense@2 {
+ reg = <2>;
+ adi,sensor-type = <29>;
+ adi,rsense-val-milli-ohms = <1200000>; //1.2Kohms
+ };
+
+ rtd@14 {
+ reg = <14>;
+ adi,sensor-type = <15>; //PT1000
+ /*2-wire, internal gnd, no current rotation*/
+ adi,number-of-wires = <2>;
+ adi,rsense-share;
+ adi,excitation-current-microamp = <500>;
+ adi,rsense-handle = <&rsense2>;
+ };
+
+ adc@10 {
+ reg = <10>;
+ adi,sensor-type = <30>;
+ adi,single-ended;
+ };
+
+ thermistor@12 {
+ reg = <12>;
+ adi,sensor-type = <26>; //Steinhart
+ adi,rsense-handle = <&rsense2>;
+ adi,custom-steinhart = <0x00f371ec 0x12345678
+ 0x2c0f8733 0x10018c66 0xa0feaccd
+ 0x90021d99>; //6 entries
+ };
+
+ thermocouple@20 {
+ reg = <20>;
+ adi,sensor-type = <9>; //custom thermocouple
+ adi,single-ended;
+ adi,custom-thermocouple =
+ /bits/ 64 <(-50220000) 0>,
+ /bits/ 64 <(-30200000) 99100000>,
+ /bits/ 64 <(-5300000) 135400000>,
+ /bits/ 64 <0 273150000>,
+ /bits/ 64 <40200000 361200000>,
+ /bits/ 64 <55300000 522100000>,
+ /bits/ 64 <88300000 720300000>,
+ /bits/ 64 <132200000 811200000>,
+ /bits/ 64 <188700000 922500000>,
+ /bits/ 64 <460400000 1000000000>; //10 pairs
+ };
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/temperature/maxim,max31855k.yaml b/Documentation/devicetree/bindings/iio/temperature/maxim,max31855k.yaml
index 9969bac66aa1..0805ed7e2113 100644
--- a/Documentation/devicetree/bindings/iio/temperature/maxim,max31855k.yaml
+++ b/Documentation/devicetree/bindings/iio/temperature/maxim,max31855k.yaml
@@ -32,7 +32,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
spi-cpha: true
required:
@@ -40,6 +39,7 @@ required:
- reg
allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
- if:
properties:
compatible:
@@ -53,7 +53,7 @@ allOf:
properties:
spi-cpha: false
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/temperature/maxim,max31856.yaml b/Documentation/devicetree/bindings/iio/temperature/maxim,max31856.yaml
index 873b34766676..228a94165487 100644
--- a/Documentation/devicetree/bindings/iio/temperature/maxim,max31856.yaml
+++ b/Documentation/devicetree/bindings/iio/temperature/maxim,max31856.yaml
@@ -19,7 +19,6 @@ properties:
reg:
maxItems: 1
- spi-max-frequency: true
spi-cpha: true
thermocouple-type:
@@ -34,7 +33,10 @@ required:
- reg
- spi-cpha
-additionalProperties: false
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml b/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml
new file mode 100644
index 000000000000..7c0c6ab6fc69
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/temperature/maxim,max31865.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/temperature/maxim,max31865.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX31865 Resistance Temperature Detector.
+
+maintainers:
+ - Navin Sankar Velliangiri <navin@linumiz.com>
+
+description: |
+ https://datasheets.maximintegrated.com/en/ds/MAX31865.pdf
+
+properties:
+ compatible:
+ const: maxim,max31865
+
+ reg:
+ maxItems: 1
+
+ maxim,3-wire:
+ description:
+ Identifies the number of wires used by the RTD. Setting this property
+ enables 3-wire RTD connection. Else 2-wire or 4-wire RTD connection.
+ type: boolean
+
+ spi-cpha: true
+
+required:
+ - compatible
+ - reg
+ - spi-cpha
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@0 {
+ compatible = "maxim,max31865";
+ reg = <0>;
+ spi-max-frequency = <400000>;
+ spi-cpha;
+ maxim,3-wire;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90614.yaml b/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90614.yaml
index d6965a0c1cf3..654d31f65d36 100644
--- a/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90614.yaml
+++ b/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90614.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/temperature/melexis,mlx90614.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Melexis MLX90614 contactless IR temperature sensor
+title: Melexis MLX90614/MLX90615 contactless IR temperature sensor
maintainers:
- Peter Meerwald <pmeerw@pmeerw.net>
@@ -15,7 +15,9 @@ description: |
properties:
compatible:
- const: melexis,mlx90614
+ enum:
+ - melexis,mlx90614
+ - melexis,mlx90615
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90632.yaml b/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90632.yaml
index b547ddcd544a..03bb5d4fa8b5 100644
--- a/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90632.yaml
+++ b/Documentation/devicetree/bindings/iio/temperature/melexis,mlx90632.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iio/temperature/melexis,mlx90632.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Melexis MLX90632 contactless Infra Red temperature sensor
+title: Melexis MLX90632 and MLX90635 contactless Infra Red temperature sensor
maintainers:
- Crt Mori <cmo@melexis.com>
@@ -27,14 +27,32 @@ description: |
Since measured object emissivity effects Infra Red energy emitted,
emissivity should be set before requesting the object temperature.
+ https://www.melexis.com/en/documents/documentation/datasheets/datasheet-mlx90635
+
+ MLX90635 is most suitable for consumer applications where
+ measured object temperature is in range between -20 to 100 degrees
+ Celsius with relative error of measurement 2 degree Celsius in
+ object temperature range for industrial applications, while just 0.2
+ degree Celsius for human body measurement applications. Since it can
+ operate and measure ambient temperature in range of -20 to 85 degrees
+ Celsius it is suitable also for outdoor use.
+
+ Since measured object emissivity effects Infra Red energy emitted,
+ emissivity should be set before requesting the object temperature.
+
properties:
compatible:
- const: melexis,mlx90632
+ enum:
+ - melexis,mlx90632
+ - melexis,mlx90635
reg:
maxItems: 1
description: Default is 0x3a, but can be reprogrammed.
+ vdd-supply:
+ description: provide VDD power to the sensor.
+
required:
- compatible
- reg
@@ -50,6 +68,7 @@ examples:
temp-sensor@3a {
compatible = "melexis,mlx90632";
reg = <0x3a>;
+ vdd-supply = <&ldo4_reg>;
};
};
...
diff --git a/Documentation/devicetree/bindings/iio/temperature/microchip,mcp9600.yaml b/Documentation/devicetree/bindings/iio/temperature/microchip,mcp9600.yaml
new file mode 100644
index 000000000000..effe3bee495d
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/temperature/microchip,mcp9600.yaml
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/temperature/microchip,mcp9600.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip MCP9600 and similar thermocouple EMF converters
+
+maintainers:
+ - Andrew Hepp <andrew.hepp@ahepp.dev>
+
+description:
+ https://ww1.microchip.com/downloads/en/DeviceDoc/MCP960X-Data-Sheet-20005426.pdf
+
+properties:
+ compatible:
+ oneOf:
+ - const: microchip,mcp9600
+ - items:
+ - const: microchip,mcp9601
+ - const: microchip,mcp9600
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 6
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 6
+ items:
+ enum:
+ - open-circuit
+ - short-circuit
+ - alert1
+ - alert2
+ - alert3
+ - alert4
+
+ thermocouple-type:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 3
+ description:
+ Type of thermocouple (THERMOCOUPLE_TYPE_K if omitted).
+ Use defines in dt-bindings/iio/temperature/thermocouple.h.
+ Supported types are B, E, J, K, N, R, S, T.
+
+ microchip,vsense:
+ type: boolean
+ description:
+ This flag indicates that the chip has been wired with VSENSE to
+ enable open and short circuit detect.
+
+ vdd-supply: true
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ const: microchip,mcp9601
+ then:
+ properties:
+ interrupts:
+ minItems: 1
+ maxItems: 4
+ interrupt-names:
+ minItems: 1
+ maxItems: 4
+ items:
+ enum:
+ - alert1
+ - alert2
+ - alert3
+ - alert4
+ microchip,vsense: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/iio/temperature/thermocouple.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@60 {
+ compatible = "microchip,mcp9600";
+ reg = <0x60>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "alert1";
+ thermocouple-type = <THERMOCOUPLE_TYPE_K>;
+ vdd-supply = <&vdd>;
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ temperature-sensor@62 {
+ compatible = "microchip,mcp9601", "microchip,mcp9600";
+ reg = <0x62>;
+ interrupt-parent = <&gpio>;
+ interrupts = <22 IRQ_TYPE_EDGE_RISING>, <23 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "open-circuit", "short-circuit";
+ vdd-supply = <&vdd>;
+ microchip,vsense;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/temperature/ti,tmp006.yaml b/Documentation/devicetree/bindings/iio/temperature/ti,tmp006.yaml
new file mode 100644
index 000000000000..590f50ba3a31
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/temperature/ti,tmp006.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/temperature/ti,tmp006.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI TMP006 IR thermopile sensor
+
+maintainers:
+ - Peter Meerwald <pmeerw@pmeerw.net>
+
+description: |
+ TI TMP006 - Infrared Thermopile Sensor in Chip-Scale Package.
+ https://cdn.sparkfun.com/datasheets/Sensors/Temp/tmp006.pdf
+
+properties:
+ compatible:
+ const: ti,tmp006
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: provide VDD power to the sensor.
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ temperature-sensor@40 {
+ compatible = "ti,tmp006";
+ reg = <0x40>;
+ vdd-supply = <&ldo4_reg>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <4 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml b/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml
index 347bc16a4671..fbba5e934861 100644
--- a/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml
+++ b/Documentation/devicetree/bindings/iio/temperature/ti,tmp117.yaml
@@ -1,15 +1,16 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/iio/temperature/ti,tmp117.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/iio/temperature/ti,tmp117.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: "TI TMP117 - Digital temperature sensor with integrated NV memory"
+title: TI TMP117 - Digital temperature sensor with integrated NV memory
description: |
- TI TMP117 - Digital temperature sensor with integrated NV memory that supports
- I2C interface.
- https://www.ti.com/lit/gpn/tmp1
+ TI TMP116/117 - Digital temperature sensor with integrated NV memory that
+ supports I2C interface.
+ https://www.ti.com/lit/gpn/tmp116
+ https://www.ti.com/lit/gpn/tmp117
maintainers:
- Puranjay Mohan <puranjay12@gmail.com>
@@ -17,14 +18,22 @@ maintainers:
properties:
compatible:
enum:
+ - ti,tmp116
- ti,tmp117
reg:
maxItems: 1
+ vcc-supply:
+ description: provide VCC power to the sensor.
+
+ label:
+ description: Unique name to identify which device this is.
+
required:
- compatible
- reg
+ - vcc-supply
additionalProperties: false
@@ -35,7 +44,8 @@ examples:
#size-cells = <0>;
tmp117@48 {
- compatible = "ti,tmp117";
- reg = <0x48>;
+ compatible = "ti,tmp117";
+ reg = <0x48>;
+ vcc-supply = <&pmic_reg_3v3>;
};
};
diff --git a/Documentation/devicetree/bindings/incomplete-devices.yaml b/Documentation/devicetree/bindings/incomplete-devices.yaml
new file mode 100644
index 000000000000..4bb6c0141e9f
--- /dev/null
+++ b/Documentation/devicetree/bindings/incomplete-devices.yaml
@@ -0,0 +1,285 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/incomplete-devices.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rejected, Legacy or Incomplete Devices
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+description:
+ Some devices will not or should not get a proper Devicetree bindings, but
+ their compatibles are present in Linux drivers for various reasons.
+
+ Examples are devices using ACPI PRP0001 with non-updatable firmware/ACPI
+ tables or old PowerPC platforms without in-tree DTS.
+
+ Following list of devices is an incomplete schema with a goal to pass DT schema
+ checks on undocumented compatibles but also reject any DTS file using such
+ un-approved compatible.
+
+ Usage of any of following compatibles is not allowed in Devicetree sources,
+ even if they come from immutable firmware.
+
+properties:
+ compatible:
+ oneOf:
+ - description:
+ Rejected compatibles in Devicetree, but used in ACPI-based devices
+ with non-updatable firmware/ACPI tables (via ACPI PRP0001)
+ enum:
+ - broadcom,bcm5241
+ - ltr,ltrf216a
+
+ - description: Legacy compatibles used on Macintosh devices
+ enum:
+ - AAPL,3500
+ - AAPL,7500
+ - AAPL,8500
+ - AAPL,9500
+ - AAPL,accelerometer_1
+ - AAPL,e411
+ - AAPL,Gossamer
+ - AAPL,PowerBook1998
+ - AAPL,ShinerESB
+ - adm1030
+ - amd-0137
+ - B5221
+ - bmac+
+ - burgundy
+ - cobalt
+ - cy28508
+ - daca
+ - fcu
+ - gatwick
+ - gmac
+ - heathrow
+ - heathrow-ata
+ - heathrow-media-bay
+ - i2sbus
+ - i2s-modem
+ - iMac
+ - K2-GMAC
+ - k2-i2c
+ - K2-Keylargo
+ - K2-UATA
+ - kauai-ata
+ - Keylargo
+ - keylargo-ata
+ - keylargo-media-bay
+ - lm87cimt
+ - MAC,adm1030
+ - MAC,ds1775
+ - MacRISC
+ - MacRISC2
+ - MacRISC3
+ - MacRISC4
+ - max6690
+ - ohare
+ - ohare-media-bay
+ - ohare-swim3
+ - PowerBook1,1
+ - PowerBook2,1
+ - PowerBook2,2
+ - PowerBook3,1
+ - PowerBook3,2
+ - PowerBook3,3
+ - PowerBook3,4
+ - PowerBook3,5
+ - PowerBook4,1
+ - PowerBook4,2
+ - PowerBook4,3
+ - PowerBook5,1
+ - PowerBook5,2
+ - PowerBook5,3
+ - PowerBook5,4
+ - PowerBook5,5
+ - PowerBook5,6
+ - PowerBook5,7
+ - PowerBook5,8
+ - PowerBook5,9
+ - PowerBook6,3
+ - PowerBook6,5
+ - PowerBook6,7
+ - PowerMac10,1
+ - PowerMac10,2
+ - PowerMac1,1
+ - PowerMac11,2
+ - PowerMac12,1
+ - PowerMac2,1
+ - PowerMac2,2
+ - PowerMac3,1
+ - PowerMac3,4
+ - PowerMac3,5
+ - PowerMac3,6
+ - PowerMac4,1
+ - PowerMac4,2
+ - PowerMac4,4
+ - PowerMac4,5
+ - PowerMac7,2
+ - PowerMac7,3
+ - PowerMac8,1
+ - PowerMac8,2
+ - PowerMac9,1
+ - paddington
+ - RackMac1,1
+ - RackMac1,2
+ - RackMac3,1
+ - screamer
+ - shasta-ata
+ - sms
+ - smu-rpm-fans
+ - smu-sat
+ - smu-sensors
+ - snapper
+ - swim3
+ - tumbler
+ - u3-agp
+ - u3-dart
+ - u3-ht
+ - u4-dart
+ - u4-pcie
+ - U4-pcie
+ - uni-n-i2c
+ - uni-north
+
+ - description: Legacy compatibles used on other PowerPC devices
+ enum:
+ - 1682m-gizmo
+ - 1682m-gpio
+ - 1682m-rng
+ - 1682m-sdc
+ - amcc,ppc440epx-rng
+ - amcc,ppc460ex-bcsr
+ - amcc,ppc460ex-crypto
+ - amcc,ppc460ex-rng
+ - amcc,ppc460sx-crypto
+ - amcc,ppc4xx-crypto
+ - amcc,sata-460ex
+ - CBEA,platform-open-pic
+ - CBEA,platform-spider-pic
+ - direct-mapped
+ - display
+ - gpio-mdio
+ - hawk-bridge
+ - hawk-pci
+ - IBM,CBEA
+ - IBM,lhca
+ - IBM,lhea
+ - IBM,lhea-ethernet
+ - ibm,axon-msic
+ - Momentum,Apache
+ - Momentum,Maple
+ - mai-logic,articia-s
+ - mpc10x-pci
+ - mpc5200b-fec-phy
+ - mpc5200-serial
+ - mpc5200-sram
+ - nintendo,flipper
+ - nintendo,flipper-exi
+ - nintendo,flipper-pi
+ - nintendo,flipper-pic
+ - nintendo,hollywood
+ - nintendo,hollywood-pic
+ - nintendo,latte-exi
+ - nintendo,latte-srnprot
+ - ohci-be
+ - ohci-bigendian
+ - ohci-le
+ - PA6T-1682M
+ - pasemi,1682m-iob
+ - pasemi,localbus
+ - pasemi,localbus-nand
+ - pasemi,nemo
+ - pasemi,pwrficient
+ - pasemi,pwrficient-rng
+ - pasemi,rootbus
+ - pasemi,sdc
+ - soc
+ - sony,ps3
+ - sti,platform-spider-pic
+
+ - description: Legacy compatibles used on SPARC devices
+ enum:
+ - bq4802
+ - ds1287
+ - i2cpcf,8584
+ - isa-m5819p
+ - isa-m5823p
+ - m5819
+ - qcn
+ - sab82532
+ - su
+ - sun4v
+ - SUNW,bbc-beep
+ - SUNW,bbc-i2c
+ - SUNW,CS4231
+ - SUNW,ebus-pic16f747-env
+ - SUNW,kt-cwq
+ - SUNW,kt-mau
+ - SUNW,n2-cwq
+ - SUNW,n2-mau
+ - SUNW,niusl
+ - SUNW,smbus-beep
+ - SUNW,sun4v-console
+ - SUNW,sun4v-pci
+ - SUNW,vf-cwq
+ - SUNW,vf-mau
+
+ - description: Incomplete and/or legacy compatibles for unknown devices
+ enum:
+ - electra-cf
+ - i2cpcf,8584
+ - virtio,uml
+
+ - description: Linux kernel unit tests and sample code
+ enum:
+ - audio-graph-card2-custom-sample
+ - compat1
+ - compat2
+ - compat3
+ - gpio-mockup
+ - gpio-simulator
+ - gpio-virtuser
+ - linux,spi-loopback-test
+ - mailbox-test
+ - regulator-virtual-consumer
+ - test-device
+
+ - description:
+ Devices on MIPS platform, without any DTS users. These are
+ unlikely to get converted to DT schema.
+ enum:
+ - mti,ranchu
+
+ - description:
+ Devices on PowerPC platform, without any DTS users. These are
+ unlikely to get converted to DT schema.
+ enum:
+ - fujitsu,coral
+ - fujitsu,lime
+ - fujitsu,MB86276
+ - fujitsu,MB86277
+ - fujitsu,MB86293
+ - fujitsu,MB86294
+ - fujitsu,mint
+ - ibm,axon-msic
+ - ibm,pmemory
+ - ibm,pmemory-v2
+ - ibm,power-rng
+ - ibm,ppc4xx-spi
+ - ibm,sdram-4xx-ddr2
+ - ibm,secureboot
+ - ibm,secureboot-v1
+ - ibm,secureboot-v2
+ - ibm,secvar-backend
+ - sgy,gpio-halt
+ - wrs,epld-localbus
+
+required:
+ - compatible
+ - broken-usage-of-incorrect-compatible
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
index d9002a3a0abb..cc1fbdc05657 100644
--- a/Documentation/devicetree/bindings/index.rst
+++ b/Documentation/devicetree/bindings/index.rst
@@ -4,6 +4,7 @@
:maxdepth: 1
ABI
+ dts-coding-style
writing-bindings
writing-schema
submitting-patches
diff --git a/Documentation/devicetree/bindings/input/adafruit,seesaw-gamepad.yaml b/Documentation/devicetree/bindings/input/adafruit,seesaw-gamepad.yaml
new file mode 100644
index 000000000000..5e86f6de6978
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/adafruit,seesaw-gamepad.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/adafruit,seesaw-gamepad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Adafruit Mini I2C Gamepad with seesaw
+
+maintainers:
+ - Anshul Dalal <anshulusr@gmail.com>
+
+description: |
+ Adafruit Mini I2C Gamepad
+
+ +-----------------------------+
+ | ___ |
+ | / \ (X) |
+ | | S | __ __ (Y) (A) |
+ | \___/ |ST| |SE| (B) |
+ | |
+ +-----------------------------+
+
+ S -> 10-bit precision bidirectional analog joystick
+ ST -> Start
+ SE -> Select
+ X, A, B, Y -> Digital action buttons
+
+ Datasheet: https://cdn-learn.adafruit.com/downloads/pdf/gamepad-qt.pdf
+ Product page: https://www.adafruit.com/product/5743
+ Arduino Driver: https://github.com/adafruit/Adafruit_Seesaw
+
+properties:
+ compatible:
+ const: adafruit,seesaw-gamepad
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+ description:
+ The gamepad's IRQ pin triggers a rising edge if interrupts are enabled.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ joystick@50 {
+ compatible = "adafruit,seesaw-gamepad";
+ interrupts = <18 IRQ_TYPE_EDGE_RISING>;
+ reg = <0x50>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml
index 721878d5b7af..6c244d66f8ce 100644
--- a/Documentation/devicetree/bindings/input/adc-joystick.yaml
+++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
@@ -2,8 +2,8 @@
# Copyright 2019-2020 Artur Rojek
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/input/adc-joystick.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/input/adc-joystick.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: ADC attached joystick
@@ -14,6 +14,9 @@ description: >
Bindings for joystick devices connected to ADC controllers supporting
the Industrial I/O subsystem.
+allOf:
+ - $ref: input.yaml#
+
properties:
compatible:
const: adc-joystick
@@ -28,6 +31,8 @@ properties:
https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/iio-consumer.yaml
for details.
+ poll-interval: true
+
'#address-cells':
const: 1
@@ -45,6 +50,7 @@ additionalProperties: false
patternProperties:
"^axis@[0-9a-f]+$":
type: object
+ $ref: input.yaml#
description: >
Represents a joystick axis bound to the given ADC channel.
For each entry in the io-channels list, one axis subnode with a matching
@@ -57,15 +63,13 @@ patternProperties:
description: Index of an io-channels list entry bound to this axis.
linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
description: EV_ABS specific event code generated by the axis.
abs-range:
- allOf:
- - $ref: /schemas/types.yaml#/definitions/uint32-array
- - items:
- - description: minimum value
- - description: maximum value
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - description: minimum value
+ - description: maximum value
description: >
Minimum and maximum values produced by the axis.
For an ABS_X axis this will be the left-most and right-most
diff --git a/Documentation/devicetree/bindings/input/adc-keys.txt b/Documentation/devicetree/bindings/input/adc-keys.txt
deleted file mode 100644
index 6c8be6a9ace2..000000000000
--- a/Documentation/devicetree/bindings/input/adc-keys.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-ADC attached resistor ladder buttons
-------------------------------------
-
-Required properties:
- - compatible: "adc-keys"
- - io-channels: Phandle to an ADC channel
- - io-channel-names = "buttons";
- - keyup-threshold-microvolt: Voltage above or equal to which all the keys are
- considered up.
-
-Optional properties:
- - poll-interval: Poll interval time in milliseconds
- - autorepeat: Boolean, Enable auto repeat feature of Linux input
- subsystem.
-
-Each button (key) is represented as a sub-node of "adc-keys":
-
-Required subnode-properties:
- - label: Descriptive name of the key.
- - linux,code: Keycode to emit.
- - press-threshold-microvolt: voltage above or equal to which this key is
- considered pressed.
-
-No two values of press-threshold-microvolt may be the same.
-All values of press-threshold-microvolt must be less than
-keyup-threshold-microvolt.
-
-Example:
-
-#include <dt-bindings/input/input.h>
-
- adc-keys {
- compatible = "adc-keys";
- io-channels = <&lradc 0>;
- io-channel-names = "buttons";
- keyup-threshold-microvolt = <2000000>;
-
- button-up {
- label = "Volume Up";
- linux,code = <KEY_VOLUMEUP>;
- press-threshold-microvolt = <1500000>;
- };
-
- button-down {
- label = "Volume Down";
- linux,code = <KEY_VOLUMEDOWN>;
- press-threshold-microvolt = <1000000>;
- };
-
- button-enter {
- label = "Enter";
- linux,code = <KEY_ENTER>;
- press-threshold-microvolt = <500000>;
- };
- };
-
-+--------------------------------+------------------------+
-| 2.000.000 <= value | no key pressed |
-+--------------------------------+------------------------+
-| 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed |
-+--------------------------------+------------------------+
-| 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed |
-+--------------------------------+------------------------+
-| 500.000 <= value < 1.000.000 | KEY_ENTER pressed |
-+--------------------------------+------------------------+
-| value < 500.000 | no key pressed |
-+--------------------------------+------------------------+
diff --git a/Documentation/devicetree/bindings/input/adc-keys.yaml b/Documentation/devicetree/bindings/input/adc-keys.yaml
new file mode 100644
index 000000000000..7aa078dead37
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/adc-keys.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/adc-keys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADC attached resistor ladder buttons
+
+maintainers:
+ - Alexandre Belloni <alexandre.belloni@bootlin.com>
+
+allOf:
+ - $ref: input.yaml#
+
+properties:
+ compatible:
+ const: adc-keys
+
+ io-channels:
+ maxItems: 1
+
+ io-channel-names:
+ const: buttons
+
+ keyup-threshold-microvolt:
+ description:
+ Voltage above or equal to which all the keys are considered up.
+
+ poll-interval: true
+ autorepeat: true
+
+patternProperties:
+ '^button-':
+ type: object
+ $ref: input.yaml#
+ additionalProperties: false
+ description:
+ Each button (key) is represented as a sub-node.
+
+ properties:
+ label: true
+
+ linux,code: true
+
+ press-threshold-microvolt:
+ description:
+ Voltage above or equal to which this key is considered pressed. No
+ two values of press-threshold-microvolt may be the same. All values
+ of press-threshold-microvolt must be less than
+ keyup-threshold-microvolt.
+
+ required:
+ - linux,code
+ - press-threshold-microvolt
+
+required:
+ - compatible
+ - io-channels
+ - io-channel-names
+ - keyup-threshold-microvolt
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ // +--------------------------------+------------------------+
+ // | 2.000.000 <= value | no key pressed |
+ // +--------------------------------+------------------------+
+ // | 1.500.000 <= value < 2.000.000 | KEY_VOLUMEUP pressed |
+ // +--------------------------------+------------------------+
+ // | 1.000.000 <= value < 1.500.000 | KEY_VOLUMEDOWN pressed |
+ // +--------------------------------+------------------------+
+ // | 500.000 <= value < 1.000.000 | KEY_ENTER pressed |
+ // +--------------------------------+------------------------+
+ // | value < 500.000 | no key pressed |
+ // +--------------------------------+------------------------+
+
+ adc-keys {
+ compatible = "adc-keys";
+ io-channels = <&lradc 0>;
+ io-channel-names = "buttons";
+ keyup-threshold-microvolt = <2000000>;
+
+ button-up {
+ label = "Volume Up";
+ linux,code = <KEY_VOLUMEUP>;
+ press-threshold-microvolt = <1500000>;
+ };
+
+ button-down {
+ label = "Volume Down";
+ linux,code = <KEY_VOLUMEDOWN>;
+ press-threshold-microvolt = <1000000>;
+ };
+
+ button-enter {
+ label = "Enter";
+ linux,code = <KEY_ENTER>;
+ press-threshold-microvolt = <500000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/adi,adp5588.yaml b/Documentation/devicetree/bindings/input/adi,adp5588.yaml
new file mode 100644
index 000000000000..336bc352579a
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/adi,adp5588.yaml
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/adi,adp5588.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADP5588 Keypad Controller
+
+maintainers:
+ - Nuno Sá <nuno.sa@analog.com>
+
+description: |
+ Analog Devices Mobile I/O Expander and QWERTY Keypad Controller
+ https://www.analog.com/media/en/technical-documentation/data-sheets/ADP5588.pdf
+
+allOf:
+ - $ref: matrix-keymap.yaml#
+ - $ref: input.yaml#
+
+properties:
+ compatible:
+ enum:
+ - adi,adp5587
+ - adi,adp5588
+
+ reg:
+ maxItems: 1
+
+ vcc-supply:
+ description: Supply Voltage Input
+
+ reset-gpios:
+ description:
+ If specified, it will be asserted during driver probe. As the line is
+ active low, it should be marked GPIO_ACTIVE_LOW.
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ gpio-controller:
+ description:
+ This property applies if either keypad,num-rows lower than 8 or
+ keypad,num-columns lower than 10.
+
+ '#gpio-cells':
+ const: 2
+
+ interrupt-controller:
+ description:
+ This property applies if either keypad,num-rows lower than 8 or
+ keypad,num-columns lower than 10. This property is optional if
+ keypad,num-rows or keypad,num-columns are not specified as the
+ device is then configured to be used purely for gpio during which
+ interrupts may or may not be utilized.
+
+ '#interrupt-cells':
+ const: 2
+
+ adi,unlock-keys:
+ description:
+ Specifies a maximum of 2 keys that can be used to unlock the keypad.
+ If this property is set, the keyboard will be locked and only unlocked
+ after these keys are pressed. If only one key is set, a double click is
+ needed to unlock the keypad. The value of this property cannot be bigger
+ or equal than keypad,num-rows * keypad,num-columns.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 2
+
+dependencies:
+ keypad,num-rows:
+ - linux,keymap
+ - keypad,num-columns
+ keypad,num-columns:
+ - linux,keymap
+ - keypad,num-rows
+ linux,keymap:
+ - keypad,num-rows
+ - keypad,num-columns
+ - interrupts
+ interrupt-controller:
+ - interrupts
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ keys@34 {
+ compatible = "adi,adp5588";
+ reg = <0x34>;
+
+ vcc-supply = <&vcc>;
+ interrupts = <21 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+ reset-gpios = <&gpio 20 GPIO_ACTIVE_LOW>;
+
+ keypad,num-rows = <1>;
+ keypad,num-columns = <9>;
+ linux,keymap = <
+ MATRIX_KEY(0x00, 0x00, KEY_1)
+ MATRIX_KEY(0x00, 0x01, KEY_2)
+ MATRIX_KEY(0x00, 0x02, KEY_3)
+ MATRIX_KEY(0x00, 0x03, KEY_4)
+ MATRIX_KEY(0x00, 0x04, KEY_5)
+ MATRIX_KEY(0x00, 0x05, KEY_6)
+ MATRIX_KEY(0x00, 0x06, KEY_7)
+ MATRIX_KEY(0x00, 0x07, KEY_8)
+ MATRIX_KEY(0x00, 0x08, KEY_9)
+ >;
+ };
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ gpio@34 {
+ compatible = "adi,adp5588";
+ reg = <0x34>;
+
+ #gpio-cells = <2>;
+ gpio-controller;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml
index cffd02028d02..6bdb8040be65 100644
--- a/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml
+++ b/Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/allwinner,sun4i-a10-lradc-keys.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A10 LRADC Device Tree Bindings
+title: Allwinner A10 LRADC
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -16,12 +16,26 @@ properties:
- const: allwinner,sun4i-a10-lradc-keys
- const: allwinner,sun8i-a83t-r-lradc
- items:
- - const: allwinner,sun50i-a64-lradc
+ - enum:
+ - allwinner,suniv-f1c100s-lradc
+ - allwinner,sun50i-a64-lradc
- const: allwinner,sun8i-a83t-r-lradc
+ - const: allwinner,sun50i-r329-lradc
+ - items:
+ - enum:
+ - allwinner,sun50i-h616-lradc
+ - allwinner,sun20i-d1-lradc
+ - const: allwinner,sun50i-r329-lradc
reg:
maxItems: 1
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
interrupts:
maxItems: 1
@@ -29,17 +43,17 @@ properties:
description:
Regulator for the LRADC reference voltage
+ wakeup-source: true
+
patternProperties:
"^button-[0-9]+$":
type: object
+ $ref: input.yaml#
properties:
label:
- $ref: /schemas/types.yaml#/definitions/string
description: Descriptive name of the key
- linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: Keycode to emit
+ linux,code: true
channel:
$ref: /schemas/types.yaml#/definitions/uint32
@@ -66,6 +80,18 @@ required:
- interrupts
- vref-supply
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - allwinner,sun50i-r329-lradc
+
+then:
+ required:
+ - clocks
+ - resets
+
additionalProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/input/ariel-pwrbutton.yaml b/Documentation/devicetree/bindings/input/ariel-pwrbutton.yaml
index b4ad829d7383..442f623bb294 100644
--- a/Documentation/devicetree/bindings/input/ariel-pwrbutton.yaml
+++ b/Documentation/devicetree/bindings/input/ariel-pwrbutton.yaml
@@ -17,6 +17,7 @@ description: |
allOf:
- $ref: input.yaml#
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/input/atmel,captouch.txt b/Documentation/devicetree/bindings/input/atmel,captouch.txt
deleted file mode 100644
index fe9ee5c53bcc..000000000000
--- a/Documentation/devicetree/bindings/input/atmel,captouch.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-Device tree bindings for Atmel capacitive touch device, typically
-an Atmel touch sensor connected to AtmegaXX MCU running firmware
-based on Qtouch library.
-
-The node for this device must be a child of a I2C controller node, as the
-device communicates via I2C.
-
-Required properties:
-
- compatible: Must be "atmel,captouch".
- reg: The I2C slave address of the device.
- interrupts: Property describing the interrupt line the device
- is connected to. The device only has one interrupt
- source.
- linux,keycodes: Specifies an array of numeric keycode values to
- be used for reporting button presses. The array can
- contain up to 8 entries.
-
-Optional properties:
-
- autorepeat: Enables the Linux input system's autorepeat
- feature on the input device.
-
-Example:
-
- atmel-captouch@51 {
- compatible = "atmel,captouch";
- reg = <0x51>;
- interrupt-parent = <&tlmm>;
- interrupts = <67 IRQ_TYPE_EDGE_FALLING>;
- linux,keycodes = <BTN_0>, <BTN_1>,
- <BTN_2>, <BTN_3>,
- <BTN_4>, <BTN_5>,
- <BTN_6>, <BTN_7>;
- autorepeat;
- };
diff --git a/Documentation/devicetree/bindings/input/atmel,captouch.yaml b/Documentation/devicetree/bindings/input/atmel,captouch.yaml
new file mode 100644
index 000000000000..f7477091d5a6
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/atmel,captouch.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/atmel,captouch.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel capacitive touch device
+
+maintainers:
+ - Dharma balasubiramani <dharma.b@microchip.com>
+
+description:
+ Atmel capacitive touch device, typically an Atmel touch sensor connected to
+ AtmegaXX MCU running firmware based on Qtouch library.
+
+allOf:
+ - $ref: input.yaml#
+
+properties:
+ compatible:
+ const: atmel,captouch
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ linux,keycodes:
+ minItems: 1
+ maxItems: 8
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - linux,keycodes
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/input/linux-event-codes.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touch@51 {
+ compatible = "atmel,captouch";
+ reg = <0x51>;
+ interrupt-parent = <&tlmm>;
+ interrupts = <67 IRQ_TYPE_EDGE_FALLING>;
+ linux,keycodes = <BTN_0>, <BTN_1>,
+ <BTN_2>, <BTN_3>,
+ <BTN_4>, <BTN_5>,
+ <BTN_6>, <BTN_7>;
+ autorepeat;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
index 3ec579d63570..d79b254f1cde 100644
--- a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
+++ b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
@@ -14,6 +14,10 @@ description: |
Atmel maXTouch touchscreen or touchpads such as the mXT244
and similar devices.
+allOf:
+ - $ref: input.yaml#
+ - $ref: touchscreen/touchscreen.yaml#
+
properties:
compatible:
const: atmel,maxtouch
@@ -60,6 +64,10 @@ properties:
or experiment to determine which bit corresponds to which input. Use
KEY_RESERVED for unused padding values.
+ linux,keycodes:
+ minItems: 1
+ maxItems: 8
+
atmel,wakeup-method:
$ref: /schemas/types.yaml#/definitions/uint32
description: |
@@ -88,7 +96,7 @@ required:
- reg
- interrupts
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/input/awinic,aw86927.yaml b/Documentation/devicetree/bindings/input/awinic,aw86927.yaml
new file mode 100644
index 000000000000..b7252916bd72
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/awinic,aw86927.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/awinic,aw86927.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Awinic AW86927 LRA Haptic IC
+
+maintainers:
+ - Griffin Kroah-Hartman <griffin.kroah@fairphone.com>
+
+properties:
+ compatible:
+ const: awinic,aw86927
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - reset-gpios
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vibrator@5a {
+ compatible = "awinic,aw86927";
+ reg = <0x5a>;
+ interrupts-extended = <&tlmm 101 IRQ_TYPE_EDGE_FALLING>;
+ reset-gpios = <&tlmm 100 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml b/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml
new file mode 100644
index 000000000000..418c168b223b
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/azoteq,iqs7222.yaml
@@ -0,0 +1,1148 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/azoteq,iqs7222.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Azoteq IQS7222A/B/C/D Capacitive Touch Controller
+
+maintainers:
+ - Jeff LaBundy <jeff@labundy.com>
+
+description: |
+ The Azoteq IQS7222A, IQS7222B, IQS7222C and IQS7222D are multichannel
+ capacitive touch controllers that feature additional sensing capabilities.
+
+ Link to datasheets: https://www.azoteq.com/
+
+properties:
+ compatible:
+ enum:
+ - azoteq,iqs7222a
+ - azoteq,iqs7222b
+ - azoteq,iqs7222c
+ - azoteq,iqs7222d
+
+ reg:
+ maxItems: 1
+
+ irq-gpios:
+ maxItems: 1
+ description:
+ Specifies the GPIO connected to the device's active-low RDY output.
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ Specifies the GPIO connected to the device's active-low MCLR input. The
+ device is temporarily held in hardware reset prior to initialization if
+ this property is present.
+
+ azoteq,max-counts:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ description: |
+ Specifies the maximum number of conversion periods (counts) that can be
+ reported as follows:
+ 0: 1023
+ 1: 2047
+ 2: 4095
+ 3: 16384
+
+ azoteq,auto-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ description: |
+ Specifies the number of conversions to occur before an interrupt is
+ generated as follows:
+ 0: 4
+ 1: 8
+ 2: 16
+ 3: 32
+
+ azoteq,ati-frac-div-fine:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the preloaded ATI fine fractional divider.
+
+ azoteq,ati-frac-div-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the preloaded ATI coarse fractional divider.
+
+ azoteq,ati-comp-select:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 1023
+ description: Specifies the preloaded ATI compensation selection.
+
+ azoteq,lta-beta-lp:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ Specifies the long-term average filter damping factor to be applied during
+ low-power mode.
+
+ azoteq,lta-beta-np:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ Specifies the long-term average filter damping factor to be applied during
+ normal-power mode.
+
+ azoteq,counts-beta-lp:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ Specifies the counts filter damping factor to be applied during low-power
+ mode.
+
+ azoteq,counts-beta-np:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ Specifies the counts filter damping factor to be applied during normal-
+ power mode.
+
+ azoteq,lta-fast-beta-lp:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ Specifies the long-term average filter fast damping factor to be applied
+ during low-power mode.
+
+ azoteq,lta-fast-beta-np:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ Specifies the long-term average filter fast damping factor to be applied
+ during normal-power mode.
+
+ azoteq,timeout-ati-ms:
+ multipleOf: 500
+ minimum: 0
+ maximum: 32767500
+ description:
+ Specifies the delay (in ms) before ATI is retried following an ATI error.
+
+ azoteq,rate-ati-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the rate (in ms) at which ATI status is evaluated.
+
+ azoteq,timeout-np-ms:
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the length of time (in ms) to wait for an event before moving
+ from normal-power mode to low-power mode.
+
+ azoteq,rate-np-ms:
+ minimum: 0
+ maximum: 3000
+ description: Specifies the report rate (in ms) during normal-power mode.
+
+ azoteq,timeout-lp-ms:
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the length of time (in ms) to wait for an event before moving
+ from low-power mode to ultra-low-power mode.
+
+ azoteq,rate-lp-ms:
+ minimum: 0
+ maximum: 3000
+ description: Specifies the report rate (in ms) during low-power mode.
+
+ azoteq,timeout-ulp-ms:
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the rate (in ms) at which channels not regularly sampled during
+ ultra-low-power mode are updated.
+
+ azoteq,rate-ulp-ms:
+ minimum: 0
+ maximum: 3000
+ description: Specifies the report rate (in ms) during ultra-low-power mode.
+
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-swapped-x-y: true
+
+ trackpad:
+ type: object
+ description: Represents all channels associated with the trackpad.
+
+ properties:
+ azoteq,channel-select:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 12
+ items:
+ minimum: 0
+ maximum: 13
+ description:
+ Specifies the order of the channels that participate in the trackpad.
+ Specify 255 to omit a given channel for the purpose of mapping a non-
+ rectangular trackpad.
+
+ azoteq,num-rows:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 12
+ description: Specifies the number of rows that comprise the trackpad.
+
+ azoteq,num-cols:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 12
+ description: Specifies the number of columns that comprise the trackpad.
+
+ azoteq,top-speed:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ multipleOf: 4
+ minimum: 0
+ maximum: 1020
+ description:
+ Specifies the speed (in coordinates traveled per conversion) after
+ which coordinate filtering is no longer applied.
+
+ azoteq,bottom-speed:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description:
+ Specifies the speed (in coordinates traveled per conversion) after
+ which coordinate filtering is linearly reduced.
+
+ azoteq,use-prox:
+ type: boolean
+ description:
+ Directs the trackpad to respond to the proximity states of the
+ selected channels instead of their corresponding touch states.
+ Note the trackpad cannot report granular coordinates during a
+ state of proximity.
+
+ patternProperties:
+ "^azoteq,lower-cal-(x|y)$":
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's lower starting points.
+
+ "^azoteq,upper-cal-(x|y)$":
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's upper starting points.
+
+ "^event-(press|tap|(swipe|flick)-(x|y)-(pos|neg))$":
+ type: object
+ $ref: input.yaml#
+ description:
+ Represents a press or gesture event reported by the trackpad. Specify
+ 'linux,code' under the press event to report absolute coordinates.
+
+ properties:
+ linux,code: true
+
+ azoteq,gesture-angle-tighten:
+ type: boolean
+ description:
+ Limits the tangent of the gesture angle to 0.5 (axial gestures
+ only). If specified in one direction, the effect is applied in
+ either direction.
+
+ azoteq,gesture-max-ms:
+ multipleOf: 16
+ minimum: 0
+ maximum: 4080
+ description:
+ Specifies the length of time (in ms) within which a tap, swipe
+ or flick gesture must be completed in order to be acknowledged
+ by the device. The number specified for any one swipe or flick
+ gesture applies to all other swipe or flick gestures.
+
+ azoteq,gesture-min-ms:
+ multipleOf: 16
+ minimum: 0
+ maximum: 4080
+ description:
+ Specifies the length of time (in ms) for which a tap gesture must
+ be held in order to be acknowledged by the device.
+
+ azoteq,gesture-dist:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the distance (in coordinates) across which a swipe or
+ flick gesture must travel in order to be acknowledged by the
+ device. The number specified for any one swipe or flick gesture
+ applies to all remaining swipe or flick gestures.
+
+ For tap gestures, this property specifies the distance from the
+ original point of contact across which the contact is permitted
+ to travel before the gesture is rejected by the device.
+
+ azoteq,gpio-select:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 3
+ items:
+ minimum: 0
+ maximum: 2
+ description: |
+ Specifies one or more GPIO mapped to the event as follows:
+ 0: GPIO0
+ 1: GPIO3
+ 2: GPIO4
+
+ Note that although multiple events can be mapped to a single
+ GPIO, they must all be of the same type (proximity, touch or
+ trackpad gesture).
+
+ additionalProperties: false
+
+ required:
+ - azoteq,channel-select
+
+ additionalProperties: false
+
+patternProperties:
+ "^cycle-[0-9]$":
+ type: object
+ description: Represents a conversion cycle serving two sensing channels.
+
+ properties:
+ azoteq,conv-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the cycle's conversion period.
+
+ azoteq,conv-frac:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the cycle's conversion frequency fraction.
+
+ azoteq,tx-enable:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 9
+ items:
+ minimum: 0
+ maximum: 8
+ description: Specifies the CTx pin(s) associated with the cycle.
+
+ azoteq,rx-float-inactive:
+ type: boolean
+ description: Floats any inactive CRx pins instead of grounding them.
+
+ azoteq,dead-time-enable:
+ type: boolean
+ description:
+ Increases the denominator of the conversion frequency formula by one.
+
+ azoteq,tx-freq-fosc:
+ type: boolean
+ description:
+ Fixes the conversion frequency to that of the device's core clock.
+
+ azoteq,vbias-enable:
+ type: boolean
+ description: Enables the bias voltage for use during inductive sensing.
+
+ azoteq,sense-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ description: |
+ Specifies the cycle's sensing mode as follows:
+ 0: None
+ 1: Self capacitive
+ 2: Mutual capacitive
+ 3: Inductive
+
+ Note that in the case of IQS7222A, cycles 5 and 6 are restricted to
+ Hall-effect sensing.
+
+ azoteq,iref-enable:
+ type: boolean
+ description:
+ Enables the current reference for use during various sensing modes.
+
+ azoteq,iref-level:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the cycle's current reference level.
+
+ azoteq,iref-trim:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the cycle's current reference trim.
+
+ dependencies:
+ azoteq,iref-level: ["azoteq,iref-enable"]
+ azoteq,iref-trim: ["azoteq,iref-enable"]
+
+ additionalProperties: false
+
+ "^channel-([0-9]|1[0-9])$":
+ type: object
+ description:
+ Represents a single sensing channel. A channel is active if defined and
+ inactive otherwise.
+
+ Note that in the case of IQS7222A, channels 10 and 11 are restricted to
+ Hall-effect sensing with events reported on channel 10 only.
+
+ properties:
+ azoteq,ulp-allow:
+ type: boolean
+ description:
+ Permits the device to enter ultra-low-power mode while the channel
+ lies in a state of touch or proximity.
+
+ azoteq,ref-select:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 9
+ description: Specifies a separate reference channel to be followed.
+
+ azoteq,ref-weight:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description: Specifies the relative weight of the reference channel.
+
+ azoteq,use-prox:
+ type: boolean
+ description:
+ Activates the reference channel in response to proximity events
+ instead of touch events.
+
+ azoteq,counts-filt-enable:
+ type: boolean
+ description: Applies counts filtering to the channel.
+
+ azoteq,ati-band:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ description: |
+ Specifies the channel's ATI band as a fraction of its ATI target as
+ follows:
+ 0: 1/16
+ 1: 1/8
+ 2: 1/4
+ 3: 1/2
+
+ azoteq,global-halt:
+ type: boolean
+ description:
+ Specifies that the channel's long-term average is to freeze if any
+ other participating channel lies in a proximity or touch state.
+
+ azoteq,invert-enable:
+ type: boolean
+ description:
+ Inverts the polarity of the states reported for proximity and touch
+ events relative to their respective thresholds.
+
+ azoteq,dual-direction:
+ type: boolean
+ description:
+ Specifies that the channel's long-term average is to freeze in the
+ presence of either increasing or decreasing counts, thereby permit-
+ ting events to be reported in either direction.
+
+ azoteq,rx-enable:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 4
+ items:
+ minimum: 0
+ maximum: 7
+ description: Specifies the CRx pin(s) associated with the channel.
+
+ azoteq,samp-cap-double:
+ type: boolean
+ description: Doubles the sampling capacitance from 40 pF to 80 pF.
+
+ azoteq,vref-half:
+ type: boolean
+ description: Halves the discharge threshold from 1.0 V to 0.5 V.
+
+ azoteq,proj-bias:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3]
+ description: |
+ Specifies the bias current applied during mutual (projected)
+ capacitive sensing as follows:
+ 0: 2 uA
+ 1: 5 uA
+ 2: 7 uA
+ 3: 10 uA
+
+ azoteq,ati-target:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ multipleOf: 8
+ minimum: 0
+ maximum: 2040
+ description: Specifies the channel's ATI target.
+
+ azoteq,ati-base:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ multipleOf: 16
+ minimum: 0
+ maximum: 496
+ description: Specifies the channel's ATI base.
+
+ azoteq,ati-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2, 3, 4, 5]
+ description: |
+ Specifies the channel's ATI mode as follows:
+ 0: Disabled
+ 1: Compensation
+ 2: Compensation divider
+ 3: Fine fractional divider
+ 4: Coarse fractional divider
+ 5: Full
+
+ azoteq,ati-frac-div-fine:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the channel's ATI fine fractional divider.
+
+ azoteq,ati-frac-mult-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the channel's ATI coarse fractional multiplier.
+
+ azoteq,ati-frac-div-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the channel's ATI coarse fractional divider.
+
+ azoteq,ati-comp-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the channel's ATI compensation divider.
+
+ azoteq,ati-comp-select:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 1023
+ description: Specifies the channel's ATI compensation selection.
+
+ azoteq,debounce-enter:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the channel's debounce entrance factor.
+
+ azoteq,debounce-exit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the channel's debounce exit factor.
+
+ patternProperties:
+ "^event-(prox|touch)$":
+ type: object
+ $ref: input.yaml#
+ description:
+ Represents a proximity or touch event reported by the channel.
+
+ properties:
+ azoteq,gpio-select:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 3
+ items:
+ minimum: 0
+ maximum: 2
+ description: |
+ Specifies one or more GPIO mapped to the event as follows:
+ 0: GPIO0
+ 1: GPIO3
+ 2: GPIO4
+
+ Note that although multiple events can be mapped to a single
+ GPIO, they must all be of the same type (proximity, touch or
+ slider/trackpad gesture).
+
+ azoteq,thresh:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Specifies the threshold for the event. Valid entries range from
+ 0-127 and 0-255 for proximity and touch events, respectively.
+
+ azoteq,hyst:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description:
+ Specifies the hysteresis for the event (touch events only).
+
+ azoteq,timeout-press-ms:
+ multipleOf: 500
+ minimum: 0
+ maximum: 127500
+ description:
+ Specifies the length of time (in ms) to wait before automatically
+ releasing a press event. Specify zero to allow the press state to
+ persist indefinitely.
+
+ The IQS7222B does not feature channel-specific timeouts; the time-
+ out specified for any one channel applies to all channels.
+
+ linux,code: true
+
+ linux,input-type:
+ enum: [1, 5]
+ default: 1
+ description:
+ Specifies whether the event is to be interpreted as a key (1)
+ or a switch (5).
+
+ additionalProperties: false
+
+ dependencies:
+ azoteq,ref-weight: ["azoteq,ref-select"]
+ azoteq,use-prox: ["azoteq,ref-select"]
+
+ additionalProperties: false
+
+ "^slider-[0-1]$":
+ type: object
+ description: Represents a slider comprising three or four channels.
+
+ properties:
+ azoteq,channel-select:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 3
+ maxItems: 4
+ items:
+ minimum: 0
+ maximum: 9
+ description:
+ Specifies the order of the channels that participate in the slider.
+
+ azoteq,slider-size:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 65535
+ description:
+ Specifies the slider's one-dimensional resolution, equal to the
+ maximum coordinate plus one.
+
+ azoteq,lower-cal:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the slider's lower starting point.
+
+ azoteq,upper-cal:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the slider's upper starting point.
+
+ azoteq,top-speed:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the speed (in coordinates traveled per conversion) after
+ which coordinate filtering is no longer applied.
+
+ azoteq,bottom-speed:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description:
+ Specifies the speed (in coordinates traveled per conversion) after
+ which coordinate filtering is linearly reduced.
+
+ azoteq,bottom-beta:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 7
+ description:
+ Specifies the coordinate filter damping factor to be applied
+ while the speed of movement is below that which is specified
+ by azoteq,bottom-speed.
+
+ azoteq,static-beta:
+ type: boolean
+ description:
+ Applies the coordinate filter damping factor specified by
+ azoteq,bottom-beta regardless of the speed of movement.
+
+ azoteq,use-prox:
+ type: boolean
+ description:
+ Directs the slider to respond to the proximity states of the selected
+ channels instead of their corresponding touch states. Note the slider
+ cannot report granular coordinates during a state of proximity.
+
+ linux,axis:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Specifies the absolute axis to which coordinates are mapped. Specify
+ ABS_WHEEL to operate the slider as a wheel (IQS7222C only).
+
+ patternProperties:
+ "^event-(press|tap|(swipe|flick)-(pos|neg))$":
+ type: object
+ $ref: input.yaml#
+ description:
+ Represents a press or gesture (IQS7222A only) event reported by
+ the slider.
+
+ properties:
+ linux,code: true
+
+ azoteq,gesture-max-ms:
+ multipleOf: 16
+ minimum: 0
+ maximum: 4080
+ description:
+ Specifies the length of time (in ms) within which a tap, swipe
+ or flick gesture must be completed in order to be acknowledged
+ by the device. The number specified for any one swipe or flick
+ gesture applies to all remaining swipe or flick gestures.
+
+ azoteq,gesture-min-ms:
+ multipleOf: 16
+ minimum: 0
+ maximum: 496
+ description:
+ Specifies the length of time (in ms) for which a tap gesture must
+ be held in order to be acknowledged by the device.
+
+ azoteq,gesture-dist:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ multipleOf: 16
+ minimum: 0
+ maximum: 4080
+ description:
+ Specifies the distance (in coordinates) across which a swipe or
+ flick gesture must travel in order to be acknowledged by the
+ device. The number specified for any one swipe or flick gesture
+ applies to all remaining swipe or flick gestures.
+
+ azoteq,gpio-select:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 3
+ items:
+ minimum: 0
+ maximum: 2
+ description: |
+ Specifies one or more GPIO mapped to the event as follows:
+ 0: GPIO0
+ 1: GPIO3
+ 2: GPIO4
+
+ Note that although multiple events can be mapped to a single
+ GPIO, they must all be of the same type (proximity, touch or
+ slider gesture).
+
+ additionalProperties: false
+
+ required:
+ - azoteq,channel-select
+
+ additionalProperties: false
+
+ "^gpio-[0-2]$":
+ type: object
+ description: |
+ Represents a GPIO mapped to one or more events as follows:
+ gpio-0: GPIO0
+ gpio-1: GPIO3
+ gpio-2: GPIO4
+
+ allOf:
+ - $ref: /schemas/pinctrl/pincfg-node.yaml#
+
+ properties:
+ drive-open-drain: true
+
+ additionalProperties: false
+
+allOf:
+ - $ref: touchscreen/touchscreen.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - azoteq,iqs7222a
+ - azoteq,iqs7222b
+ - azoteq,iqs7222c
+
+ then:
+ properties:
+ touchscreen-size-x: false
+ touchscreen-size-y: false
+ touchscreen-inverted-x: false
+ touchscreen-inverted-y: false
+ touchscreen-swapped-x-y: false
+
+ trackpad: false
+
+ patternProperties:
+ "^channel-([0-9]|1[0-9])$":
+ properties:
+ azoteq,counts-filt-enable: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - azoteq,iqs7222b
+ - azoteq,iqs7222c
+
+ then:
+ patternProperties:
+ "^channel-([0-9]|1[0-9])$":
+ properties:
+ azoteq,ulp-allow: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - azoteq,iqs7222b
+ - azoteq,iqs7222d
+
+ then:
+ patternProperties:
+ "^cycle-[0-9]$":
+ properties:
+ azoteq,iref-enable: false
+
+ "^channel-([0-9]|1[0-9])$":
+ properties:
+ azoteq,ref-select: false
+
+ "^slider-[0-1]$": false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: azoteq,iqs7222b
+
+ then:
+ patternProperties:
+ "^channel-([0-9]|1[0-9])$":
+ patternProperties:
+ "^event-(prox|touch)$":
+ properties:
+ azoteq,gpio-select: false
+
+ "^gpio-[0-2]$": false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: azoteq,iqs7222a
+
+ then:
+ patternProperties:
+ "^channel-([0-9]|1[0-9])$":
+ patternProperties:
+ "^event-(prox|touch)$":
+ properties:
+ azoteq,gpio-select:
+ maxItems: 1
+ items:
+ maximum: 0
+
+ "^slider-[0-1]$":
+ properties:
+ azoteq,slider-size:
+ multipleOf: 16
+ minimum: 16
+ maximum: 4080
+
+ azoteq,top-speed:
+ multipleOf: 4
+ maximum: 1020
+
+ patternProperties:
+ "^event-(press|tap|(swipe|flick)-(pos|neg))$":
+ properties:
+ azoteq,gpio-select:
+ maxItems: 1
+ items:
+ maximum: 0
+
+ else:
+ patternProperties:
+ "^slider-[0-1]$":
+ patternProperties:
+ "^event-(press|tap|(swipe|flick)-(pos|neg))$":
+ properties:
+ azoteq,gesture-max-ms: false
+
+ azoteq,gesture-min-ms: false
+
+ azoteq,gesture-dist: false
+
+required:
+ - compatible
+ - reg
+ - irq-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/input.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ iqs7222a@44 {
+ compatible = "azoteq,iqs7222a";
+ reg = <0x44>;
+ irq-gpios = <&gpio 4 GPIO_ACTIVE_LOW>;
+ azoteq,lta-beta-lp = <7>;
+ azoteq,lta-beta-np = <8>;
+ azoteq,counts-beta-lp = <2>;
+ azoteq,counts-beta-np = <3>;
+ azoteq,lta-fast-beta-lp = <3>;
+ azoteq,lta-fast-beta-np = <4>;
+
+ cycle-0 {
+ azoteq,conv-period = <5>;
+ azoteq,conv-frac = <127>;
+ azoteq,tx-enable = <1>, <2>, <4>, <5>;
+ azoteq,dead-time-enable;
+ azoteq,sense-mode = <2>;
+ };
+
+ cycle-1 {
+ azoteq,conv-period = <5>;
+ azoteq,conv-frac = <127>;
+ azoteq,tx-enable = <5>;
+ azoteq,dead-time-enable;
+ azoteq,sense-mode = <2>;
+ };
+
+ cycle-2 {
+ azoteq,conv-period = <5>;
+ azoteq,conv-frac = <127>;
+ azoteq,tx-enable = <4>;
+ azoteq,dead-time-enable;
+ azoteq,sense-mode = <2>;
+ };
+
+ cycle-3 {
+ azoteq,conv-period = <5>;
+ azoteq,conv-frac = <127>;
+ azoteq,tx-enable = <2>;
+ azoteq,dead-time-enable;
+ azoteq,sense-mode = <2>;
+ };
+
+ cycle-4 {
+ azoteq,conv-period = <5>;
+ azoteq,conv-frac = <127>;
+ azoteq,tx-enable = <1>;
+ azoteq,dead-time-enable;
+ azoteq,sense-mode = <2>;
+ };
+
+ cycle-5 {
+ azoteq,conv-period = <2>;
+ azoteq,conv-frac = <0>;
+ };
+
+ cycle-6 {
+ azoteq,conv-period = <2>;
+ azoteq,conv-frac = <0>;
+ };
+
+ channel-0 {
+ azoteq,ulp-allow;
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <3>;
+ azoteq,ati-target = <800>;
+ azoteq,ati-base = <208>;
+ azoteq,ati-mode = <5>;
+ };
+
+ channel-1 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <3>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <208>;
+ azoteq,ati-mode = <5>;
+ };
+
+ channel-2 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <3>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <208>;
+ azoteq,ati-mode = <5>;
+ };
+
+ channel-3 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <3>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <208>;
+ azoteq,ati-mode = <5>;
+ };
+
+ channel-4 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <3>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <208>;
+ azoteq,ati-mode = <5>;
+ };
+
+ channel-5 {
+ azoteq,ulp-allow;
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <6>;
+ azoteq,ati-target = <800>;
+ azoteq,ati-base = <144>;
+ azoteq,ati-mode = <5>;
+ };
+
+ channel-6 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <6>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <160>;
+ azoteq,ati-mode = <5>;
+
+ event-touch {
+ linux,code = <KEY_MUTE>;
+ };
+ };
+
+ channel-7 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <6>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <160>;
+ azoteq,ati-mode = <5>;
+
+ event-touch {
+ linux,code = <KEY_VOLUMEDOWN>;
+ };
+ };
+
+ channel-8 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <6>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <160>;
+ azoteq,ati-mode = <5>;
+
+ event-touch {
+ linux,code = <KEY_VOLUMEUP>;
+ };
+ };
+
+ channel-9 {
+ azoteq,global-halt;
+ azoteq,invert-enable;
+ azoteq,rx-enable = <6>;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <160>;
+ azoteq,ati-mode = <5>;
+
+ event-touch {
+ linux,code = <KEY_POWER>;
+ };
+ };
+
+ channel-10 {
+ azoteq,ulp-allow;
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <112>;
+
+ event-touch {
+ linux,code = <SW_LID>;
+ linux,input-type = <EV_SW>;
+ };
+ };
+
+ channel-11 {
+ azoteq,ati-target = <496>;
+ azoteq,ati-base = <112>;
+ };
+
+ slider-0 {
+ azoteq,channel-select = <1>, <2>, <3>, <4>;
+ azoteq,slider-size = <4080>;
+ azoteq,upper-cal = <50>;
+ azoteq,lower-cal = <30>;
+ azoteq,top-speed = <200>;
+ azoteq,bottom-speed = <1>;
+ azoteq,bottom-beta = <3>;
+
+ event-tap {
+ linux,code = <KEY_PLAYPAUSE>;
+ azoteq,gesture-max-ms = <400>;
+ azoteq,gesture-min-ms = <32>;
+ };
+
+ event-flick-pos {
+ linux,code = <KEY_NEXTSONG>;
+ azoteq,gesture-max-ms = <800>;
+ azoteq,gesture-dist = <800>;
+ };
+
+ event-flick-neg {
+ linux,code = <KEY_PREVIOUSSONG>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/cap11xx.txt b/Documentation/devicetree/bindings/input/cap11xx.txt
deleted file mode 100644
index 8c67a0b5058d..000000000000
--- a/Documentation/devicetree/bindings/input/cap11xx.txt
+++ /dev/null
@@ -1,78 +0,0 @@
-Device tree bindings for Microchip CAP11xx based capacitive touch sensors
-
-The node for this device must be a child of a I2C controller node, as the
-device communication via I2C only.
-
-Required properties:
-
- compatible: Must contain one of:
- "microchip,cap1106"
- "microchip,cap1126"
- "microchip,cap1188"
-
- reg: The I2C slave address of the device.
-
- interrupts: Property describing the interrupt line the
- device's ALERT#/CM_IRQ# pin is connected to.
- The device only has one interrupt source.
-
-Optional properties:
-
- autorepeat: Enables the Linux input system's autorepeat
- feature on the input device.
-
- microchip,sensor-gain: Defines the gain of the sensor circuitry. This
- effectively controls the sensitivity, as a
- smaller delta capacitance is required to
- generate the same delta count values.
- Valid values are 1, 2, 4, and 8.
- By default, a gain of 1 is set.
-
- microchip,irq-active-high: By default the interrupt pin is active low
- open drain. This property allows using the active
- high push-pull output.
-
- linux,keycodes: Specifies an array of numeric keycode values to
- be used for the channels. If this property is
- omitted, KEY_A, KEY_B, etc are used as
- defaults. The array must have exactly six
- entries.
-
-Example:
-
-i2c_controller {
- cap1106@28 {
- compatible = "microchip,cap1106";
- interrupt-parent = <&gpio1>;
- interrupts = <0 0>;
- reg = <0x28>;
- autorepeat;
- microchip,sensor-gain = <2>;
-
- linux,keycodes = <103>, /* KEY_UP */
- <106>, /* KEY_RIGHT */
- <108>, /* KEY_DOWN */
- <105>, /* KEY_LEFT */
- <109>, /* KEY_PAGEDOWN */
- <104>; /* KEY_PAGEUP */
-
- #address-cells = <1>;
- #size-cells = <0>;
-
- usr@0 {
- label = "cap11xx:green:usr0";
- reg = <0>;
- };
-
- usr@1 {
- label = "cap11xx:green:usr1";
- reg = <1>;
- };
-
- alive@2 {
- label = "cap11xx:green:alive";
- reg = <2>;
- linux,default_trigger = "heartbeat";
- };
- };
-}
diff --git a/Documentation/devicetree/bindings/input/cirrus,cs40l50.yaml b/Documentation/devicetree/bindings/input/cirrus,cs40l50.yaml
new file mode 100644
index 000000000000..89bd06864bd4
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/cirrus,cs40l50.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/cirrus,cs40l50.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cirrus Logic CS40L50 Advanced Haptic Driver
+
+maintainers:
+ - James Ogletree <jogletre@opensource.cirrus.com>
+
+description:
+ CS40L50 is a haptic driver with waveform memory,
+ integrated DSP, and closed-loop algorithms.
+
+properties:
+ compatible:
+ enum:
+ - cirrus,cs40l50
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ vdd-a-supply:
+ description: Power supply for internal analog circuits.
+
+ vdd-p-supply:
+ description: Power supply for always-on circuits.
+
+ vdd-io-supply:
+ description: Power supply for digital input/output.
+
+ vdd-b-supply:
+ description: Power supply for the boost converter.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - reset-gpios
+ - vdd-io-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ haptic-driver@34 {
+ compatible = "cirrus,cs40l50";
+ reg = <0x34>;
+ interrupt-parent = <&gpio>;
+ interrupts = <113 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&gpio 112 GPIO_ACTIVE_LOW>;
+ vdd-io-supply = <&vreg>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/cirrus,ep9307-keypad.yaml b/Documentation/devicetree/bindings/input/cirrus,ep9307-keypad.yaml
new file mode 100644
index 000000000000..a0d2460c55ab
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/cirrus,ep9307-keypad.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/cirrus,ep9307-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cirrus ep93xx keypad
+
+maintainers:
+ - Alexander Sverdlin <alexander.sverdlin@gmail.com>
+
+allOf:
+ - $ref: /schemas/input/matrix-keymap.yaml#
+
+description:
+ The KPP is designed to interface with a keypad matrix with 2-point contact
+ or 3-point contact keys. The KPP is designed to simplify the software task
+ of scanning a keypad matrix. The KPP is capable of detecting, debouncing,
+ and decoding one or multiple keys pressed simultaneously on a keypad.
+
+properties:
+ compatible:
+ oneOf:
+ - const: cirrus,ep9307-keypad
+ - items:
+ - enum:
+ - cirrus,ep9312-keypad
+ - cirrus,ep9315-keypad
+ - const: cirrus,ep9307-keypad
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ debounce-delay-ms:
+ description: |
+ Time in microseconds that key must be pressed or
+ released for state change interrupt to trigger.
+
+ cirrus,prescale:
+ description: row/column counter pre-scaler load value
+ $ref: /schemas/types.yaml#/definitions/uint16
+ maximum: 1023
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - linux,keymap
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/clock/cirrus,ep9301-syscon.h>
+ keypad@800f0000 {
+ compatible = "cirrus,ep9307-keypad";
+ reg = <0x800f0000 0x0c>;
+ interrupt-parent = <&vic0>;
+ interrupts = <29>;
+ clocks = <&eclk EP93XX_CLK_KEYPAD>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&keypad_default_pins>;
+ linux,keymap = <KEY_UP>,
+ <KEY_DOWN>,
+ <KEY_VOLUMEDOWN>,
+ <KEY_HOME>,
+ <KEY_RIGHT>,
+ <KEY_LEFT>,
+ <KEY_ENTER>,
+ <KEY_VOLUMEUP>,
+ <KEY_F6>,
+ <KEY_F8>,
+ <KEY_F9>,
+ <KEY_F10>,
+ <KEY_F1>,
+ <KEY_F2>,
+ <KEY_F3>,
+ <KEY_POWER>;
+ };
diff --git a/Documentation/devicetree/bindings/input/cypress,cyapa.txt b/Documentation/devicetree/bindings/input/cypress,cyapa.txt
deleted file mode 100644
index d3db65916a36..000000000000
--- a/Documentation/devicetree/bindings/input/cypress,cyapa.txt
+++ /dev/null
@@ -1,42 +0,0 @@
-Cypress I2C Touchpad
-
-Required properties:
-- compatible: must be "cypress,cyapa".
-- reg: I2C address of the chip.
-- interrupts: interrupt to which the chip is connected (see interrupt
- binding[0]).
-
-Optional properties:
-- wakeup-source: touchpad can be used as a wakeup source.
-- pinctrl-names: should be "default" (see pinctrl binding [1]).
-- pinctrl-0: a phandle pointing to the pin settings for the device (see
- pinctrl binding [1]).
-- vcc-supply: a phandle for the regulator supplying 3.3V power.
-
-[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-[1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
-
-Example:
- &i2c0 {
- /* ... */
-
- /* Cypress Gen3 touchpad */
- touchpad@67 {
- compatible = "cypress,cyapa";
- reg = <0x67>;
- interrupt-parent = <&gpio>;
- interrupts = <2 IRQ_TYPE_EDGE_FALLING>; /* GPIO 2 */
- wakeup-source;
- };
-
- /* Cypress Gen5 and later touchpad */
- touchpad@24 {
- compatible = "cypress,cyapa";
- reg = <0x24>;
- interrupt-parent = <&gpio>;
- interrupts = <2 IRQ_TYPE_EDGE_FALLING>; /* GPIO 2 */
- wakeup-source;
- };
-
- /* ... */
- };
diff --git a/Documentation/devicetree/bindings/input/cypress,cyapa.yaml b/Documentation/devicetree/bindings/input/cypress,cyapa.yaml
new file mode 100644
index 000000000000..da629d511da1
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/cypress,cyapa.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/cypress,cyapa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cypress All Points Addressable (APA) I2C Touchpad / Trackpad
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ const: cypress,cyapa
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ wakeup-source: true
+
+ vcc-supply:
+ description: 3.3V power
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ trackpad@67 {
+ reg = <0x67>;
+ compatible = "cypress,cyapa";
+ interrupts = <2 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpx1>;
+ wakeup-source;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/cypress-sf.yaml b/Documentation/devicetree/bindings/input/cypress-sf.yaml
new file mode 100644
index 000000000000..c0b051466272
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/cypress-sf.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/cypress-sf.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cypress StreetFighter touchkey controller
+
+maintainers:
+ - Yassine Oudjana <y.oudjana@protonmail.com>
+
+allOf:
+ - $ref: input.yaml#
+
+properties:
+ compatible:
+ const: cypress,sf3155
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ avdd-supply:
+ description: Regulator for AVDD analog voltage
+
+ vdd-supply:
+ description: Regulator for VDD digital voltage
+
+ linux,keycodes:
+ minItems: 1
+ maxItems: 8
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - avdd-supply
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchkey@28 {
+ compatible = "cypress,sf3155";
+ reg = <0x28>;
+ interrupt-parent = <&msmgpio>;
+ interrupts = <77 IRQ_TYPE_EDGE_FALLING>;
+ avdd-supply = <&vreg_l6a_1p8>;
+ vdd-supply = <&vdd_3v2_tp>;
+ linux,keycodes = <KEY_BACK KEY_MENU>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/da9062-onkey.txt b/Documentation/devicetree/bindings/input/da9062-onkey.txt
deleted file mode 100644
index 5f9fbc68e58a..000000000000
--- a/Documentation/devicetree/bindings/input/da9062-onkey.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-* Dialog DA9061/62/63 OnKey Module
-
-This module is part of the DA9061/DA9062/DA9063. For more details about entire
-DA9062 and DA9061 chips see Documentation/devicetree/bindings/mfd/da9062.txt
-For DA9063 see Documentation/devicetree/bindings/mfd/da9063.txt
-
-This module provides the KEY_POWER event.
-
-Required properties:
-
-- compatible: should be one of the following valid compatible string lines:
- "dlg,da9061-onkey", "dlg,da9062-onkey"
- "dlg,da9062-onkey"
- "dlg,da9063-onkey"
-
-Optional properties:
-
-- dlg,disable-key-power : Disable power-down using a long key-press. If this
- entry exists the OnKey driver will remove support for the KEY_POWER key
- press when triggered using a long press of the OnKey.
-
-Example: DA9063
-
- pmic0: da9063@58 {
- onkey {
- compatible = "dlg,da9063-onkey";
- dlg,disable-key-power;
- };
- };
-
-Example: DA9062
-
- pmic0: da9062@58 {
- onkey {
- compatible = "dlg,da9062-onkey";
- dlg,disable-key-power;
- };
- };
-
-Example: DA9061 using a fall-back compatible for the DA9062 onkey driver
-
- pmic0: da9061@58 {
- onkey {
- compatible = "dlg,da9061-onkey", "dlg,da9062-onkey";
- dlg,disable-key-power;
- };
- };
diff --git a/Documentation/devicetree/bindings/input/dlg,da7280.txt b/Documentation/devicetree/bindings/input/dlg,da7280.txt
deleted file mode 100644
index 96ee5d50e111..000000000000
--- a/Documentation/devicetree/bindings/input/dlg,da7280.txt
+++ /dev/null
@@ -1,108 +0,0 @@
-Dialog Semiconductor DA7280 Haptics bindings
-
-Required properties:
-- compatible: Should be "dlg,da7280".
-- reg: Specifies the I2C slave address.
-
-- interrupt-parent : Specifies the phandle of the interrupt controller to
- which the IRQs from DA7280 are delivered to.
-
-- dlg,actuator-type: Set Actuator type. it should be one of:
- "LRA" - Linear Resonance Actuator type.
- "ERM-bar" - Bar type Eccentric Rotating Mass.
- "ERM-coin" - Coin type Eccentric Rotating Mass.
-
-- dlg,const-op-mode: Haptic operation mode for FF_CONSTANT.
- Possible values:
- 1 - Direct register override(DRO) mode triggered by i2c(default),
- 2 - PWM data source mode controlled by PWM duty,
-- dlg,periodic-op-mode: Haptic operation mode for FF_PERIODIC.
- Possible values:
- 1 - Register triggered waveform memory(RTWM) mode, the pattern
- assigned to the PS_SEQ_ID played as much times as PS_SEQ_LOOP,
- 2 - Edge triggered waveform memory(ETWM) mode, external GPI(N)
- control are required to enable/disable and it needs to keep
- device enabled by sending magnitude (X > 0),
- the pattern is assigned to the GPI(N)_SEQUENCE_ID below.
- The default value is 1 for both of the operation modes.
- For more details, please see the datasheet.
-
-- dlg,nom-microvolt: Nominal actuator voltage rating.
- Valid values: 0 - 6000000.
-- dlg,abs-max-microvolt: Absolute actuator maximum voltage rating.
- Valid values: 0 - 6000000.
-- dlg,imax-microamp: Actuator max current rating.
- Valid values: 0 - 252000.
- Default: 130000.
-- dlg,impd-micro-ohms: the impedance of the actuator in micro ohms.
- Valid values: 0 - 1500000000.
-
-Optional properties:
-- pwms : phandle to the physical PWM(Pulse Width Modulation) device.
- PWM properties should be named "pwms". And number of cell is different
- for each pwm device.
- (See Documentation/devicetree/bindings/pwm/pwm.txt
- for further information relating to pwm properties)
-
-- dlg,ps-seq-id: the PS_SEQ_ID(pattern ID in waveform memory inside chip)
- to play back when RTWM-MODE is enabled.
- Valid range: 0 - 15.
-- dlg,ps-seq-loop: the PS_SEQ_LOOP, Number of times the pre-stored sequence
- pointed to by PS_SEQ_ID or GPI(N)_SEQUENCE_ID is repeated.
- Valid range: 0 - 15.
-- dlg,gpiN-seq-id: the GPI(N)_SEQUENCE_ID, pattern to play
- when gpi0 is triggered, 'N' must be 0 - 2.
- Valid range: 0 - 15.
-- dlg,gpiN-mode: the pattern mode which can select either
- "Single-pattern" or "Multi-pattern", 'N' must be 0 - 2.
-- dlg,gpiN-polarity: gpiN polarity which can be chosen among
- "Rising-edge", "Falling-edge" and "Both-edge",
- 'N' must be 0 - 2
- Haptic will work by this edge option in case of ETWM mode.
-
-- dlg,resonant-freq-hz: use in case of LRA.
- the frequency range: 50 - 300.
- Default: 205.
-
-- dlg,bemf-sens-enable: Enable for internal loop computations.
-- dlg,freq-track-enable: Enable for resonant frequency tracking.
-- dlg,acc-enable: Enable for active acceleration.
-- dlg,rapid-stop-enable: Enable for rapid stop.
-- dlg,amp-pid-enable: Enable for the amplitude PID.
-- dlg,mem-array: Customized waveform memory(patterns) data downloaded to
- the device during initialization. This is an array of 100 values(u8).
-
-For further information, see device datasheet.
-
-======
-
-Example:
-
- haptics: da7280-haptics@4a {
- compatible = "dlg,da7280";
- reg = <0x4a>;
- interrupt-parent = <&gpio6>;
- interrupts = <11 IRQ_TYPE_LEVEL_LOW>;
- dlg,actuator-type = "LRA";
- dlg,dlg,const-op-mode = <1>;
- dlg,dlg,periodic-op-mode = <1>;
- dlg,nom-microvolt = <2000000>;
- dlg,abs-max-microvolt = <2000000>;
- dlg,imax-microamp = <170000>;
- dlg,resonant-freq-hz = <180>;
- dlg,impd-micro-ohms = <10500000>;
- dlg,freq-track-enable;
- dlg,rapid-stop-enable;
- dlg,mem-array = <
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
- >;
- };
diff --git a/Documentation/devicetree/bindings/input/dlg,da7280.yaml b/Documentation/devicetree/bindings/input/dlg,da7280.yaml
new file mode 100644
index 000000000000..0d06755aaaa8
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/dlg,da7280.yaml
@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/dlg,da7280.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Dialog Semiconductor DA7280 Low Power High-Definition Haptic Driver
+
+maintainers:
+ - Roy Im <roy.im.opensource@diasemi.com>
+
+properties:
+ compatible:
+ const: dlg,da7280
+
+ reg:
+ maxItems: 1
+ description: I2C address of the device.
+
+ interrupts:
+ maxItems: 1
+
+ dlg,actuator-type:
+ enum:
+ - LRA # Linear Resonance Actuator type
+ - ERM-bar # Bar type Eccentric Rotating Mass
+ - ERM-coin # Coin type Eccentric Rotating Mass
+
+ dlg,const-op-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 1 # Direct register override (DRO) mode triggered by i2c (default)
+ - 2 # PWM data source mode controlled by PWM duty
+ description:
+ Haptic operation mode for FF_CONSTANT
+
+ dlg,periodic-op-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 1 # Register triggered waveform memory(RTWM) mode, the pattern
+ # assigned to the PS_SEQ_ID played as much times as PS_SEQ_LOOP
+ - 2 # Edge triggered waveform memory(ETWM) mode, external GPI(N)
+ # control are required to enable/disable and it needs to keep
+ # device enabled by sending magnitude (X > 0),
+ # the pattern is assigned to the GPI(N)_SEQUENCE_ID below
+ default: 1
+ description:
+ Haptic operation mode for FF_PERIODIC.
+ The default value is 1 for both of the operation modes.
+ For more details, please see the datasheet
+
+ dlg,nom-microvolt:
+ minimum: 0
+ maximum: 6000000
+ description:
+ Nominal actuator voltage rating
+
+ dlg,abs-max-microvolt:
+ minimum: 0
+ maximum: 6000000
+ description:
+ Absolute actuator maximum voltage rating
+
+ dlg,imax-microamp:
+ minimum: 0
+ maximum: 252000
+ default: 130000
+ description:
+ Actuator max current rating
+
+ dlg,impd-micro-ohms:
+ minimum: 0
+ maximum: 1500000000
+ description:
+ Impedance of the actuator
+
+ pwms:
+ maxItems: 1
+
+ dlg,ps-seq-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ The PS_SEQ_ID(pattern ID in waveform memory inside chip)
+ to play back when RTWM-MODE is enabled
+
+ dlg,ps-seq-loop:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ The PS_SEQ_LOOP, Number of times the pre-stored sequence pointed to by
+ PS_SEQ_ID or GPI(N)_SEQUENCE_ID is repeated
+
+ dlg,gpi0-seq-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ the GPI0_SEQUENCE_ID, pattern to play when gpi0 is triggered
+
+ dlg,gpi1-seq-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ the GPI1_SEQUENCE_ID, pattern to play when gpi1 is triggered
+
+ dlg,gpi2-seq-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description:
+ the GPI2_SEQUENCE_ID, pattern to play when gpi2 is triggered
+
+ dlg,gpi0-mode:
+ enum:
+ - Single-pattern
+ - Multi-pattern
+ description:
+ Pattern mode for gpi0
+
+ dlg,gpi1-mode:
+ enum:
+ - Single-pattern
+ - Multi-pattern
+ description:
+ Pattern mode for gpi1
+
+ dlg,gpi2-mode:
+ enum:
+ - Single-pattern
+ - Multi-pattern
+ description:
+ Pattern mode for gpi2
+
+ dlg,gpi0-polarity:
+ enum:
+ - Rising-edge
+ - Falling-edge
+ - Both-edge
+ description:
+ gpi0 polarity, Haptic will work by this edge option in case of ETWM mode
+
+ dlg,gpi1-polarity:
+ enum:
+ - Rising-edge
+ - Falling-edge
+ - Both-edge
+ description:
+ gpi1 polarity, Haptic will work by this edge option in case of ETWM mode
+
+ dlg,gpi2-polarity:
+ enum:
+ - Rising-edge
+ - Falling-edge
+ - Both-edge
+ description:
+ gpi2 polarity, Haptic will work by this edge option in case of ETWM mode
+
+ dlg,resonant-freq-hz:
+ minimum: 50
+ maximum: 300
+ default: 205
+
+ dlg,bemf-sens-enable:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable for internal loop computations
+
+ dlg,freq-track-enable:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable for resonant frequency tracking
+
+ dlg,acc-enable:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable for active acceleration
+
+ dlg,rapid-stop-enable:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable for rapid stop
+
+ dlg,amp-pid-enable:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable for the amplitude PID
+
+ dlg,mem-array:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 100
+ description:
+ Customized waveform memory (patterns) data downloaded to the device during initialization.
+ Each entry value must be included between 0 and 255.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - dlg,actuator-type
+ - dlg,const-op-mode
+ - dlg,periodic-op-mode
+ - dlg,nom-microvolt
+ - dlg,abs-max-microvolt
+ - dlg,imax-microamp
+ - dlg,impd-micro-ohms
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ haptics@4a {
+ compatible = "dlg,da7280";
+ reg = <0x4a>;
+ interrupt-parent = <&gpio6>;
+ interrupts = <11 IRQ_TYPE_LEVEL_LOW>;
+ dlg,actuator-type = "LRA";
+ dlg,const-op-mode = <1>;
+ dlg,periodic-op-mode = <1>;
+ dlg,nom-microvolt = <2000000>;
+ dlg,abs-max-microvolt = <2000000>;
+ dlg,imax-microamp = <170000>;
+ dlg,resonant-freq-hz = <180>;
+ dlg,impd-micro-ohms = <10500000>;
+ dlg,freq-track-enable;
+ dlg,rapid-stop-enable;
+ dlg,mem-array = <0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/dlg,da9062-onkey.yaml b/Documentation/devicetree/bindings/input/dlg,da9062-onkey.yaml
new file mode 100644
index 000000000000..1480d95421e1
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/dlg,da9062-onkey.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/dlg,da9062-onkey.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Dialog DA9061/62/63 OnKey Module
+
+maintainers:
+ - Biju Das <biju.das.jz@bp.renesas.com>
+
+description: |
+ This module is part of the DA9061/DA9062/DA9063. For more details about entire
+ DA906{1,2,3} chips see Documentation/devicetree/bindings/mfd/dlg,da9063.yaml
+
+ This module provides the KEY_POWER event.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - dlg,da9062-onkey
+ - dlg,da9063-onkey
+ - items:
+ - const: dlg,da9061-onkey
+ - const: dlg,da9062-onkey
+
+ dlg,disable-key-power:
+ type: boolean
+ description:
+ Disable power-down using a long key-press. If this entry exists
+ the OnKey driver will remove support for the KEY_POWER key press
+ when triggered using a long press of the OnKey.
+
+required:
+ - compatible
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/input/elan,ekth3000.yaml b/Documentation/devicetree/bindings/input/elan,ekth3000.yaml
new file mode 100644
index 000000000000..24dc2d69613f
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/elan,ekth3000.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/elan,ekth3000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Elantech I2C Touchpad
+
+maintainers:
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+
+allOf:
+ - $ref: touchscreen/touchscreen.yaml#
+
+properties:
+ compatible:
+ const: elan,ekth3000
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ wakeup-source:
+ type: boolean
+ description: touchpad can be used as a wakeup source
+
+ vcc-supply:
+ description: a phandle for the regulator supplying 3.3V power
+
+ elan,trackpoint:
+ type: boolean
+ description: touchpad can support a trackpoint
+
+ elan,clickpad:
+ type: boolean
+ description: touchpad is a clickpad (the entire surface is a button)
+
+ elan,middle-button:
+ type: boolean
+ description: touchpad has a physical middle button
+
+ elan,x_traces:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: number of antennas on the x axis
+
+ elan,y_traces:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: number of antennas on the y axis
+
+ touchscreen-size-x: true
+
+ touchscreen-size-y: true
+
+ touchscreen-x-mm: true
+
+ touchscreen-y-mm: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchpad@15 {
+ compatible = "elan,ekth3000";
+ reg = <0x15>;
+ interrupt-parent = <&gpio4>;
+ interrupts = <0x0 IRQ_TYPE_EDGE_FALLING>;
+ wakeup-source;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/elan,ekth6915.yaml b/Documentation/devicetree/bindings/input/elan,ekth6915.yaml
new file mode 100644
index 000000000000..0840e4ab28b7
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/elan,ekth6915.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/elan,ekth6915.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Elan I2C-HID touchscreen controllers
+
+maintainers:
+ - Douglas Anderson <dianders@chromium.org>
+
+description:
+ Supports the Elan eKTH6915 and other I2C-HID touchscreen controllers.
+ These touchscreen controller use the i2c-hid protocol with a reset GPIO.
+
+allOf:
+ - $ref: /schemas/input/touchscreen/touchscreen.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - elan,ekth5015m
+ - const: elan,ekth6915
+ - items:
+ - const: elan,ekth8d18
+ - const: elan,ekth6a12nay
+ - enum:
+ - elan,ekth6915
+ - elan,ekth6a12nay
+
+ reg: true
+
+ interrupts:
+ maxItems: 1
+
+ panel: true
+
+ reset-gpios:
+ description: Reset GPIO; not all touchscreens using eKTH6915 hook this up.
+
+ no-reset-on-power-off:
+ type: boolean
+ description:
+ Reset line is wired so that it can (and should) be left deasserted when
+ the power supply is off.
+
+ vcc33-supply:
+ description: The 3.3V supply to the touchscreen.
+
+ vccio-supply:
+ description:
+ The IO supply to the touchscreen. Need not be specified if this is the
+ same as the 3.3V supply.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - vcc33-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@10 {
+ compatible = "elan,ekth5015m", "elan,ekth6915";
+ reg = <0x10>;
+
+ interrupt-parent = <&tlmm>;
+ interrupts = <9 IRQ_TYPE_LEVEL_LOW>;
+
+ reset-gpios = <&tlmm 8 GPIO_ACTIVE_LOW>;
+ vcc33-supply = <&pp3300_ts>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/elan_i2c.txt b/Documentation/devicetree/bindings/input/elan_i2c.txt
deleted file mode 100644
index 9963247706f2..000000000000
--- a/Documentation/devicetree/bindings/input/elan_i2c.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-Elantech I2C Touchpad
-
-Required properties:
-- compatible: must be "elan,ekth3000".
-- reg: I2C address of the chip.
-- interrupts: interrupt to which the chip is connected (see interrupt
- binding[0]).
-
-Optional properties:
-- wakeup-source: touchpad can be used as a wakeup source.
-- pinctrl-names: should be "default" (see pinctrl binding [1]).
-- pinctrl-0: a phandle pointing to the pin settings for the device (see
- pinctrl binding [1]).
-- vcc-supply: a phandle for the regulator supplying 3.3V power.
-- elan,trackpoint: touchpad can support a trackpoint (boolean)
-- elan,clickpad: touchpad is a clickpad (the entire surface is a button)
-- elan,middle-button: touchpad has a physical middle button
-- elan,x_traces: number of antennas on the x axis
-- elan,y_traces: number of antennas on the y axis
-- some generic touchscreen properties [2]:
- * touchscreen-size-x
- * touchscreen-size-y
- * touchscreen-x-mm
- * touchscreen-y-mm
-
-
-[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-[1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
-[2]: Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
-
-Example:
- &i2c1 {
- /* ... */
-
- touchpad@15 {
- compatible = "elan,ekth3000";
- reg = <0x15>;
- interrupt-parent = <&gpio4>;
- interrupts = <0x0 IRQ_TYPE_EDGE_FALLING>;
- wakeup-source;
- };
-
- /* ... */
- };
diff --git a/Documentation/devicetree/bindings/input/fsl,mpr121-touchkey.yaml b/Documentation/devicetree/bindings/input/fsl,mpr121-touchkey.yaml
index 878464f128dc..5139af287d3e 100644
--- a/Documentation/devicetree/bindings/input/fsl,mpr121-touchkey.yaml
+++ b/Documentation/devicetree/bindings/input/fsl,mpr121-touchkey.yaml
@@ -57,7 +57,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- mpr121@5a {
+ touchkey@5a {
compatible = "fsl,mpr121-touchkey";
reg = <0x5a>;
interrupt-parent = <&gpio1>;
@@ -77,7 +77,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- mpr121@5a {
+ touchkey@5a {
compatible = "fsl,mpr121-touchkey";
reg = <0x5a>;
poll-interval = <20>;
diff --git a/Documentation/devicetree/bindings/input/fsl,scu-key.yaml b/Documentation/devicetree/bindings/input/fsl,scu-key.yaml
new file mode 100644
index 000000000000..29921aab9d97
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/fsl,scu-key.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/fsl,scu-key.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX SCU Client Device Node - SCU Key Based on SCU Message Protocol
+
+maintainers:
+ - Dong Aisheng <aisheng.dong@nxp.com>
+
+description: i.MX SCU Client Device Node
+ Client nodes are maintained as children of the relevant IMX-SCU device node.
+
+allOf:
+ - $ref: input.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: fsl,imx8qxp-sc-key
+ - const: fsl,imx-sc-key
+
+ linux,keycodes:
+ maxItems: 1
+
+ wakeup-source: true
+
+required:
+ - compatible
+ - linux,keycodes
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+
+ keys {
+ compatible = "fsl,imx8qxp-sc-key", "fsl,imx-sc-key";
+ linux,keycodes = <KEY_POWER>;
+ };
diff --git a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml
index fe1c5016f7f3..358cb8275bf1 100644
--- a/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml
+++ b/Documentation/devicetree/bindings/input/goodix,gt7375p.yaml
@@ -14,10 +14,16 @@ description:
This touchscreen uses the i2c-hid protocol but has some non-standard
power sequencing required.
+allOf:
+ - $ref: /schemas/input/touchscreen/touchscreen.yaml#
+
properties:
compatible:
- items:
+ oneOf:
- const: goodix,gt7375p
+ - items:
+ - const: goodix,gt7986u
+ - const: goodix,gt7375p
reg:
enum:
@@ -27,12 +33,30 @@ properties:
interrupts:
maxItems: 1
+ panel: true
+
reset-gpios:
true
vdd-supply:
description: The 3.3V supply to the touchscreen.
+ mainboard-vddio-supply:
+ description:
+ The supply on the main board needed to power up IO signals going
+ to the touchscreen. This supply need not go to the touchscreen
+ itself as long as it allows the main board to make signals compatible
+ with what the touchscreen is expecting for its IO rails.
+
+ goodix,no-reset-during-suspend:
+ description:
+ Set this to true to enforce the driver to not assert the reset GPIO
+ during suspend.
+ Due to potential touchscreen hardware flaw, back-powering could happen in
+ suspend if the power supply is on and with active-low reset GPIO asserted.
+ This property is used to avoid the back-powering issue.
+ type: boolean
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
new file mode 100644
index 000000000000..92bd0041feba
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/goodix,gt7986u-spifw.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/goodix,gt7986u-spifw.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Goodix GT7986U SPI HID Touchscreen
+
+maintainers:
+ - Charles Wang <charles.goodix@gmail.com>
+
+description: |
+ Supports the Goodix GT7986U touchscreen.
+ This touch controller reports data packaged according to the HID protocol
+ over the SPI bus, but it is incompatible with Microsoft's HID-over-SPI protocol.
+
+ NOTE: these bindings are distinct from the bindings used with the
+ GT7986U when the chip is running I2C firmware. This is because there's
+ not a single device that talks over both I2C and SPI but rather
+ distinct touchscreens that happen to be built with the same ASIC but
+ that are distinct products running distinct firmware.
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - goodix,gt7986u-spifw
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ spi-max-frequency: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - reset-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@0 {
+ compatible = "goodix,gt7986u-spifw";
+ reg = <0>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
+ spi-max-frequency = <10000000>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml b/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml
index 5377b232fa10..fefaaf46a240 100644
--- a/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml
+++ b/Documentation/devicetree/bindings/input/google,cros-ec-keyb.yaml
@@ -10,20 +10,21 @@ title: ChromeOS EC Keyboard
maintainers:
- Simon Glass <sjg@chromium.org>
- Benson Leung <bleung@chromium.org>
- - Enric Balletbo i Serra <enric.balletbo@collabora.com>
description: |
Google's ChromeOS EC Keyboard is a simple matrix keyboard
implemented on a separate EC (Embedded Controller) device. It provides
a message for reading key scans from the EC. These are then converted
- into keycodes for processing by the kernel.
-
-allOf:
- - $ref: "/schemas/input/matrix-keymap.yaml#"
+ into keycodes for processing by the kernel. This device also supports
+ switches/buttons like power and volume buttons.
properties:
compatible:
- const: google,cros-ec-keyb
+ oneOf:
+ - description: ChromeOS EC with only buttons/switches
+ const: google,cros-ec-keyb-switches
+ - description: ChromeOS EC with keyboard and possibly buttons/switches
+ const: google,cros-ec-keyb
google,needs-ghost-filter:
description:
@@ -32,6 +33,7 @@ properties:
type: boolean
function-row-physmap:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 1
maxItems: 15
description: |
@@ -42,15 +44,31 @@ properties:
where the lower 16 bits are reserved. This property is specified only
when the keyboard has a custom design for the top row keys.
+dependencies:
+ function-row-physmap: [ 'linux,keymap' ]
+ google,needs-ghost-filter: [ 'linux,keymap' ]
+
required:
- compatible
+if:
+ properties:
+ compatible:
+ contains:
+ const: google,cros-ec-keyb
+then:
+ $ref: /schemas/input/matrix-keymap.yaml#
+ required:
+ - keypad,num-rows
+ - keypad,num-columns
+ - linux,keymap
+
unevaluatedProperties: false
examples:
- |
#include <dt-bindings/input/input.h>
- cros-ec-keyb {
+ keyboard-controller {
compatible = "google,cros-ec-keyb";
keypad,num-rows = <8>;
keypad,num-columns = <13>;
@@ -114,3 +132,9 @@ examples:
/* UP LEFT */
0x070b0067 0x070c0069>;
};
+ - |
+ /* No matrix keyboard, just buttons/switches */
+ keyboard-controller {
+ compatible = "google,cros-ec-keyb-switches";
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/gpio-beeper.txt b/Documentation/devicetree/bindings/input/gpio-beeper.txt
deleted file mode 100644
index a5086e37fce6..000000000000
--- a/Documentation/devicetree/bindings/input/gpio-beeper.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-* GPIO beeper device tree bindings
-
-Register a beeper connected to GPIO pin.
-
-Required properties:
-- compatible: Should be "gpio-beeper".
-- gpios: From common gpio binding; gpio connection to beeper enable pin.
-
-Example:
- beeper: beeper {
- compatible = "gpio-beeper";
- gpios = <&gpio3 23 GPIO_ACTIVE_HIGH>;
- };
diff --git a/Documentation/devicetree/bindings/input/gpio-beeper.yaml b/Documentation/devicetree/bindings/input/gpio-beeper.yaml
new file mode 100644
index 000000000000..290372add3d5
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/gpio-beeper.yaml
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/gpio-beeper.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO controlled beeper
+
+maintainers:
+ - Fabio Estevam <festevam@denx.de>
+
+properties:
+ compatible:
+ const: gpio-beeper
+
+ gpios:
+ maxItems: 1
+ description:
+ GPIO that drives the beeper.
+
+required:
+ - compatible
+ - gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ beeper {
+ compatible = "gpio-beeper";
+ gpios = <&gpio3 23 GPIO_ACTIVE_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/input/gpio-keys.yaml b/Documentation/devicetree/bindings/input/gpio-keys.yaml
index 060a309ff8e7..cc78c2152921 100644
--- a/Documentation/devicetree/bindings/input/gpio-keys.yaml
+++ b/Documentation/devicetree/bindings/input/gpio-keys.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/gpio-keys.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Device-Tree bindings for GPIO attached keys
+title: GPIO attached keys
maintainers:
- Rob Herring <robh@kernel.org>
@@ -15,113 +15,136 @@ properties:
- gpio-keys
- gpio-keys-polled
-patternProperties:
- ".*":
- if:
- type: object
- then:
- $ref: input.yaml#
-
- properties:
- gpios:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
- label:
- description: Descriptive name of the key.
-
- linux,code:
- description: Key / Axis code to emit.
- $ref: /schemas/types.yaml#/definitions/uint32
-
- linux,input-type:
- description:
- Specify event type this button/key generates. If not specified defaults to
- <1> == EV_KEY.
- $ref: /schemas/types.yaml#/definitions/uint32
-
- default: 1
-
- linux,input-value:
- description: |
- If linux,input-type is EV_ABS or EV_REL then this
- value is sent for events this button generates when pressed.
- EV_ABS/EV_REL axis will generate an event with a value of 0
- when all buttons with linux,input-type == type and
- linux,code == axis are released. This value is interpreted
- as a signed 32 bit value, e.g. to make a button generate a
- value of -1 use:
-
- linux,input-value = <0xffffffff>; /* -1 */
-
- $ref: /schemas/types.yaml#/definitions/uint32
-
- debounce-interval:
- description:
- Debouncing interval time in milliseconds. If not specified defaults to 5.
- $ref: /schemas/types.yaml#/definitions/uint32
-
- default: 5
-
- wakeup-source:
- description: Button can wake-up the system.
-
- wakeup-event-action:
- description: |
- Specifies whether the key should wake the system when asserted, when
- deasserted, or both. This property is only valid for keys that wake up the
- system (e.g., when the "wakeup-source" property is also provided).
+ autorepeat: true
- Supported values are defined in linux-event-codes.h:
+ label:
+ description: Name of entire device
- EV_ACT_ANY - both asserted and deasserted
- EV_ACT_ASSERTED - asserted
- EV_ACT_DEASSERTED - deasserted
- $ref: /schemas/types.yaml#/definitions/uint32
- enum: [0, 1, 2]
+ poll-interval: true
- linux,can-disable:
- description:
- Indicates that button is connected to dedicated (not shared) interrupt
- which can be disabled to suppress events from the button.
- type: boolean
-
- pinctrl-0:
- maxItems: 1
-
- pinctrl-names:
- maxItems: 1
-
- required:
- - linux,code
-
- anyOf:
- - required:
+patternProperties:
+ "^(button|event|key|switch|(button|event|key|switch)-[a-z0-9-]+|[a-z0-9-]+-(button|event|key|switch))$":
+ $ref: input.yaml#
+
+ properties:
+ gpios:
+ maxItems: 1
+
+ interrupts:
+ oneOf:
+ - items:
+ - description: Optional key interrupt or wakeup interrupt
+ - items:
+ - description: Key interrupt
+ - description: Wakeup interrupt
+
+ interrupt-names:
+ description:
+ Optional interrupt names, can be used to specify a separate dedicated
+ wake-up interrupt in addition to the gpio irq
+ oneOf:
+ - items:
+ - enum: [ irq, wakeup ]
+ - items:
+ - const: irq
+ - const: wakeup
+
+ label:
+ description: Descriptive name of the key.
+
+ linux,code:
+ description: Key / Axis code to emit.
+
+ linux,input-type:
+ default: 1 # EV_KEY
+
+ linux,input-value:
+ description: |
+ If linux,input-type is EV_ABS or EV_REL then this
+ value is sent for events this button generates when pressed.
+ EV_ABS/EV_REL axis will generate an event with a value of 0
+ when all buttons with linux,input-type == type and
+ linux,code == axis are released. This value is interpreted
+ as a signed 32 bit value, e.g. to make a button generate a
+ value of -1 use:
+
+ linux,input-value = <0xffffffff>; /* -1 */
+
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ debounce-interval:
+ description:
+ Debouncing interval time in milliseconds. If not specified defaults to 5.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ default: 5
+
+ wakeup-source:
+ description: Button can wake-up the system.
+
+ wakeup-event-action:
+ description: |
+ Specifies whether the key should wake the system when asserted, when
+ deasserted, or both. This property is only valid for keys that wake up the
+ system (e.g., when the "wakeup-source" property is also provided).
+
+ Supported values are defined in linux-event-codes.h:
+
+ EV_ACT_ANY - both asserted and deasserted
+ EV_ACT_ASSERTED - asserted
+ EV_ACT_DEASSERTED - deasserted
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+
+ linux,can-disable:
+ description:
+ Indicates that button is connected to dedicated (not shared) interrupt
+ which can be disabled to suppress events from the button.
+ type: boolean
+
+ required:
+ - linux,code
+
+ anyOf:
+ - required:
+ - interrupts
+ - required:
+ - interrupts-extended
+ - required:
+ - gpios
+
+ allOf:
+ - if:
+ properties:
+ interrupts:
+ minItems: 2
+ required:
- interrupts
- - required:
- - gpios
-
- dependencies:
- wakeup-event-action: [ wakeup-source ]
- linux,input-value: [ gpios ]
-
- unevaluatedProperties: false
-
-if:
- properties:
- compatible:
- const: gpio-keys-polled
-then:
- properties:
- poll-interval:
- description:
- Poll interval time in milliseconds
- $ref: /schemas/types.yaml#/definitions/uint32
-
- required:
- - poll-interval
+ then:
+ properties:
+ interrupt-names:
+ minItems: 2
+ required:
+ - interrupt-names
+
+ dependencies:
+ wakeup-event-action: [ wakeup-source ]
+ linux,input-value: [ gpios ]
+
+ unevaluatedProperties: false
+
+allOf:
+ - $ref: input.yaml#
+ - if:
+ properties:
+ compatible:
+ const: gpio-keys-polled
+ then:
+ required:
+ - poll-interval
+ else:
+ properties:
+ poll-interval: false
additionalProperties: false
@@ -133,16 +156,25 @@ examples:
compatible = "gpio-keys";
autorepeat;
- up {
+ key-up {
label = "GPIO Key UP";
linux,code = <103>;
gpios = <&gpio1 0 1>;
};
- down {
+ key-down {
label = "GPIO Key DOWN";
linux,code = <108>;
- interrupts = <1 IRQ_TYPE_LEVEL_HIGH 7>;
+ interrupts = <1 IRQ_TYPE_EDGE_FALLING>;
+ };
+
+ key-wakeup {
+ label = "GPIO Key WAKEUP";
+ linux,code = <143>;
+ interrupts-extended = <&intc 2 IRQ_TYPE_EDGE_FALLING>,
+ <&intc_wakeup 0 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "irq", "wakeup";
+ wakeup-source;
};
};
diff --git a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt
deleted file mode 100644
index 570dc10f0cd7..000000000000
--- a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-* GPIO driven matrix keypad device tree bindings
-
-GPIO driven matrix keypad is used to interface a SoC with a matrix keypad.
-The matrix keypad supports multiple row and column lines, a key can be
-placed at each intersection of a unique row and a unique column. The matrix
-keypad can sense a key-press and key-release by means of GPIO lines and
-report the event using GPIO interrupts to the cpu.
-
-Required Properties:
-- compatible: Should be "gpio-matrix-keypad"
-- row-gpios: List of gpios used as row lines. The gpio specifier
- for this property depends on the gpio controller to
- which these row lines are connected.
-- col-gpios: List of gpios used as column lines. The gpio specifier
- for this property depends on the gpio controller to
- which these column lines are connected.
-- linux,keymap: The definition can be found at
- bindings/input/matrix-keymap.txt
-
-Optional Properties:
-- linux,no-autorepeat: do no enable autorepeat feature.
-- wakeup-source: use any event on keypad as wakeup event.
- (Legacy property supported: "linux,wakeup")
-- debounce-delay-ms: debounce interval in milliseconds
-- col-scan-delay-us: delay, measured in microseconds, that is needed
- before we can scan keypad after activating column gpio
-- drive-inactive-cols: drive inactive columns during scan,
- default is to turn inactive columns into inputs.
-
-Example:
- matrix-keypad {
- compatible = "gpio-matrix-keypad";
- debounce-delay-ms = <5>;
- col-scan-delay-us = <2>;
-
- row-gpios = <&gpio2 25 0
- &gpio2 26 0
- &gpio2 27 0>;
-
- col-gpios = <&gpio2 21 0
- &gpio2 22 0>;
-
- linux,keymap = <0x0000008B
- 0x0100009E
- 0x02000069
- 0x0001006A
- 0x0101001C
- 0x0201006C>;
- };
diff --git a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.yaml b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.yaml
new file mode 100644
index 000000000000..ebfff9e42a36
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/input/gpio-matrix-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO matrix keypad
+
+maintainers:
+ - Marek Vasut <marek.vasut@gmail.com>
+
+description:
+ GPIO driven matrix keypad is used to interface a SoC with a matrix keypad.
+ The matrix keypad supports multiple row and column lines, a key can be
+ placed at each intersection of a unique row and a unique column. The matrix
+ keypad can sense a key-press and key-release by means of GPIO lines and
+ report the event using GPIO interrupts to the cpu.
+
+allOf:
+ - $ref: /schemas/input/matrix-keymap.yaml#
+
+properties:
+ compatible:
+ const: gpio-matrix-keypad
+
+ row-gpios:
+ description:
+ List of GPIOs used as row lines. The gpio specifier for this property
+ depends on the gpio controller to which these row lines are connected.
+
+ col-gpios:
+ description:
+ List of GPIOs used as column lines. The gpio specifier for this property
+ depends on the gpio controller to which these column lines are connected.
+
+ linux,keymap: true
+
+ linux,no-autorepeat:
+ type: boolean
+ description: Do not enable autorepeat feature.
+
+ gpio-activelow:
+ type: boolean
+ description:
+ Force GPIO polarity to active low.
+ In the absence of this property GPIOs are treated as active high.
+
+ debounce-delay-ms:
+ description: Debounce interval in milliseconds.
+ default: 0
+
+ col-scan-delay-us:
+ description:
+ Delay, measured in microseconds, that is needed
+ before we can scan keypad after activating column gpio.
+ default: 0
+
+ all-cols-on-delay-us:
+ description:
+ Delay, measured in microseconds, that is needed
+ after activating all column gpios.
+ default: 0
+
+ drive-inactive-cols:
+ type: boolean
+ description:
+ Drive inactive columns during scan,
+ default is to turn inactive columns into inputs.
+
+ wakeup-source: true
+
+required:
+ - compatible
+ - row-gpios
+ - col-gpios
+ - linux,keymap
+
+additionalProperties: false
+
+examples:
+ - |
+ matrix-keypad {
+ compatible = "gpio-matrix-keypad";
+ debounce-delay-ms = <5>;
+ col-scan-delay-us = <2>;
+
+ row-gpios = <&gpio2 25 0
+ &gpio2 26 0
+ &gpio2 27 0>;
+
+ col-gpios = <&gpio2 21 0
+ &gpio2 22 0>;
+
+ linux,keymap = <0x0000008B
+ 0x0100009E
+ 0x02000069
+ 0x0001006A
+ 0x0101001C
+ 0x0201006C>;
+
+ wakeup-source;
+ };
diff --git a/Documentation/devicetree/bindings/input/gpio-mouse.txt b/Documentation/devicetree/bindings/input/gpio-mouse.txt
deleted file mode 100644
index 519510a11af9..000000000000
--- a/Documentation/devicetree/bindings/input/gpio-mouse.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-Device-Tree bindings for GPIO attached mice
-
-This simply uses standard GPIO handles to define a simple mouse connected
-to 5-7 GPIO lines.
-
-Required properties:
- - compatible: must be "gpio-mouse"
- - scan-interval-ms: The scanning interval in milliseconds
- - up-gpios: GPIO line phandle to the line indicating "up"
- - down-gpios: GPIO line phandle to the line indicating "down"
- - left-gpios: GPIO line phandle to the line indicating "left"
- - right-gpios: GPIO line phandle to the line indicating "right"
-
-Optional properties:
- - button-left-gpios: GPIO line handle to the left mouse button
- - button-middle-gpios: GPIO line handle to the middle mouse button
- - button-right-gpios: GPIO line handle to the right mouse button
-Example:
-
-#include <dt-bindings/gpio/gpio.h>
-
-gpio-mouse {
- compatible = "gpio-mouse";
- scan-interval-ms = <50>;
- up-gpios = <&gpio0 0 GPIO_ACTIVE_LOW>;
- down-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
- left-gpios = <&gpio0 2 GPIO_ACTIVE_LOW>;
- right-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>;
- button-left-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>;
- button-middle-gpios = <&gpio0 5 GPIO_ACTIVE_LOW>;
- button-right-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>;
-};
diff --git a/Documentation/devicetree/bindings/input/gpio-mouse.yaml b/Documentation/devicetree/bindings/input/gpio-mouse.yaml
new file mode 100644
index 000000000000..3928ec6aff1d
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/gpio-mouse.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/gpio-mouse.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO attached mouse
+
+description: |
+ This simply uses standard GPIO handles to define a simple mouse connected
+ to 5-7 GPIO lines.
+
+maintainers:
+ - Anshul Dalal <anshulusr@gmail.com>
+
+properties:
+ compatible:
+ const: gpio-mouse
+
+ scan-interval-ms:
+ maxItems: 1
+
+ up-gpios:
+ maxItems: 1
+
+ down-gpios:
+ maxItems: 1
+
+ left-gpios:
+ maxItems: 1
+
+ right-gpios:
+ maxItems: 1
+
+ button-left-gpios:
+ maxItems: 1
+
+ button-middle-gpios:
+ maxItems: 1
+
+ button-right-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - scan-interval-ms
+ - up-gpios
+ - down-gpios
+ - left-gpios
+ - right-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ gpio-mouse {
+ compatible = "gpio-mouse";
+ scan-interval-ms = <50>;
+ up-gpios = <&gpio0 0 GPIO_ACTIVE_LOW>;
+ down-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
+ left-gpios = <&gpio0 2 GPIO_ACTIVE_LOW>;
+ right-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>;
+ button-left-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>;
+ button-middle-gpios = <&gpio0 5 GPIO_ACTIVE_LOW>;
+ button-right-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt
deleted file mode 100644
index c76bafaf98d2..000000000000
--- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-* HID over I2C Device-Tree bindings
-
-HID over I2C provides support for various Human Interface Devices over the
-I2C bus. These devices can be for example touchpads, keyboards, touch screens
-or sensors.
-
-The specification has been written by Microsoft and is currently available here:
-http://msdn.microsoft.com/en-us/library/windows/hardware/hh852380.aspx
-
-If this binding is used, the kernel module i2c-hid will handle the communication
-with the device and the generic hid core layer will handle the protocol.
-
-Required properties:
-- compatible: must be "hid-over-i2c"
-- reg: i2c slave address
-- hid-descr-addr: HID descriptor address
-- interrupts: interrupt line
-
-Additional optional properties:
-
-Some devices may support additional optional properties to help with, e.g.,
-power sequencing. The following properties can be supported by one or more
-device-specific compatible properties, which should be used in addition to the
-"hid-over-i2c" string.
-
-- compatible:
- * "wacom,w9013" (Wacom W9013 digitizer). Supports:
- - vdd-supply (3.3V)
- - vddl-supply (1.8V)
- - post-power-on-delay-ms
-
-- vdd-supply: phandle of the regulator that provides the supply voltage.
-- post-power-on-delay-ms: time required by the device after enabling its regulators
- or powering it on, before it is ready for communication.
-
-Example:
-
- i2c-hid-dev@2c {
- compatible = "hid-over-i2c";
- reg = <0x2c>;
- hid-descr-addr = <0x0020>;
- interrupt-parent = <&gpx3>;
- interrupts = <3 2>;
- };
diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.yaml b/Documentation/devicetree/bindings/input/hid-over-i2c.yaml
new file mode 100644
index 000000000000..138caad96a29
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/hid-over-i2c.yaml
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: GPL-2.0-only
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/hid-over-i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HID over I2C Devices
+
+maintainers:
+ - Benjamin Tissoires <benjamin.tissoires@redhat.com>
+ - Jiri Kosina <jkosina@suse.cz>
+
+description: |+
+ HID over I2C provides support for various Human Interface Devices over the
+ I2C bus. These devices can be for example touchpads, keyboards, touch screens
+ or sensors.
+
+ The specification has been written by Microsoft and is currently available here:
+ https://msdn.microsoft.com/en-us/library/windows/hardware/hh852380.aspx
+
+ If this binding is used, the kernel module i2c-hid will handle the communication
+ with the device and the generic hid core layer will handle the protocol.
+
+allOf:
+ - $ref: /schemas/input/touchscreen/touchscreen.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - wacom,w9013
+ - const: hid-over-i2c
+ - description: Just "hid-over-i2c" alone is allowed, but not recommended.
+ const: hid-over-i2c
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ hid-descr-addr:
+ description: HID descriptor address
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ panel: true
+
+ post-power-on-delay-ms:
+ description: Time required by the device after enabling its regulators
+ or powering it on, before it is ready for communication.
+
+ touchscreen-inverted-x: true
+
+ touchscreen-inverted-y: true
+
+ vdd-supply:
+ description: 3.3V supply
+
+ vddl-supply:
+ description: 1.8V supply
+
+ wakeup-source: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hid@2c {
+ compatible = "hid-over-i2c";
+ reg = <0x2c>;
+ hid-descr-addr = <0x0020>;
+ interrupts = <3 2>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/ibm,op-panel.yaml b/Documentation/devicetree/bindings/input/ibm,op-panel.yaml
new file mode 100644
index 000000000000..29a1879e356d
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ibm,op-panel.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ibm,op-panel.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IBM Operation Panel
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+allOf:
+ - $ref: input.yaml#
+
+description: |
+ The IBM Operation Panel provides a simple interface to control the connected
+ server. It has a display and three buttons: two directional arrows and one
+ 'Enter' button.
+
+properties:
+ compatible:
+ const: ibm,op-panel
+
+ reg:
+ maxItems: 1
+
+ linux,keycodes:
+ minItems: 1
+ maxItems: 3
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/i2c/i2c.h>
+ #include <dt-bindings/input/input.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ibm-op-panel@62 {
+ compatible = "ibm,op-panel";
+ reg = <(0x62 | I2C_OWN_SLAVE_ADDRESS)>;
+ linux,keycodes = <KEY_UP>, <KEY_DOWN>, <KEY_ENTER>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/ilitek,ili2901.yaml b/Documentation/devicetree/bindings/input/ilitek,ili2901.yaml
new file mode 100644
index 000000000000..1abeec768d79
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ilitek,ili2901.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ilitek,ili2901.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ilitek ILI2901 touchscreen controller
+
+maintainers:
+ - Jiri Kosina <jkosina@suse.com>
+
+description:
+ Supports the Ilitek ILI2901 touchscreen controller.
+ This touchscreen controller uses the i2c-hid protocol with a reset GPIO.
+
+allOf:
+ - $ref: /schemas/input/touchscreen/touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - ilitek,ili2901
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ panel: true
+
+ reset-gpios:
+ maxItems: 1
+
+ vcc33-supply: true
+
+ vccio-supply: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - vcc33-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@41 {
+ compatible = "ilitek,ili2901";
+ reg = <0x41>;
+
+ interrupt-parent = <&tlmm>;
+ interrupts = <9 IRQ_TYPE_LEVEL_LOW>;
+
+ reset-gpios = <&tlmm 8 GPIO_ACTIVE_LOW>;
+ vcc33-supply = <&pp3300_ts>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt b/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt
deleted file mode 100644
index cdcaa3f52d25..000000000000
--- a/Documentation/devicetree/bindings/input/ilitek,ili2xxx.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Ilitek ILI210x/ILI2117/ILI2120/ILI251x touchscreen controller
-
-Required properties:
-- compatible:
- ilitek,ili210x for ILI210x
- ilitek,ili2117 for ILI2117
- ilitek,ili2120 for ILI2120
- ilitek,ili251x for ILI251x
-
-- reg: The I2C address of the device
-
-- interrupts: The sink for the touchscreen's IRQ output
- See ../interrupt-controller/interrupts.txt
-
-Optional properties for main touchpad device:
-
-- reset-gpios: GPIO specifier for the touchscreen's reset pin (active low)
-
-Example:
-
- touchscreen@41 {
- compatible = "ilitek,ili251x";
- reg = <0x41>;
- interrupt-parent = <&gpio4>;
- interrupts = <7 IRQ_TYPE_EDGE_FALLING>;
- reset-gpios = <&gpio5 21 GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml b/Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml
new file mode 100644
index 000000000000..c5d9e0e919f9
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ilitek,ili9882t.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ilitek,ili9882t.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ilitek ili9882t touchscreen controller
+
+maintainers:
+ - Cong Yang <yangcong5@huaqin.corp-partner.google.com>
+
+description:
+ Supports the Ilitek ili9882t touchscreen controller.
+ This touchscreen controller uses the i2c-hid protocol with a reset GPIO.
+
+allOf:
+ - $ref: /schemas/input/touchscreen/touchscreen.yaml#
+
+properties:
+ compatible:
+ const: ilitek,ili9882t
+
+ reg:
+ const: 0x41
+
+ interrupts:
+ maxItems: 1
+
+ panel: true
+
+ reset-gpios:
+ maxItems: 1
+ description: Reset GPIO.
+
+ vccio-supply:
+ description: The 1.8V supply to the touchscreen.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - panel
+ - vccio-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen: touchscreen@41 {
+ compatible = "ilitek,ili9882t";
+ reg = <0x41>;
+
+ interrupt-parent = <&pio>;
+ interrupts = <12 IRQ_TYPE_LEVEL_LOW>;
+
+ panel = <&panel>;
+ reset-gpios = <&pio 60 GPIO_ACTIVE_LOW>;
+ vccio-supply = <&mt6366_vio18_reg>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/imx-keypad.yaml b/Documentation/devicetree/bindings/input/imx-keypad.yaml
index f21db81206b4..b110eb1f3358 100644
--- a/Documentation/devicetree/bindings/input/imx-keypad.yaml
+++ b/Documentation/devicetree/bindings/input/imx-keypad.yaml
@@ -4,13 +4,13 @@
$id: http://devicetree.org/schemas/input/imx-keypad.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Freescale i.MX Keypad Port(KPP) device tree bindings
+title: Freescale i.MX Keypad Port(KPP)
maintainers:
- Liu Ying <gnuiyl@gmail.com>
allOf:
- - $ref: "/schemas/input/matrix-keymap.yaml#"
+ - $ref: /schemas/input/matrix-keymap.yaml#
description: |
The KPP is designed to interface with a keypad matrix with 2-point contact
diff --git a/Documentation/devicetree/bindings/input/input.yaml b/Documentation/devicetree/bindings/input/input.yaml
index d41d8743aad4..94f7942189e8 100644
--- a/Documentation/devicetree/bindings/input/input.yaml
+++ b/Documentation/devicetree/bindings/input/input.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/input.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Common input schema binding
+title: Input Devices Common Properties
maintainers:
- Dmitry Torokhov <dmitry.torokhov@gmail.com>
@@ -21,7 +21,26 @@ properties:
$ref: /schemas/types.yaml#/definitions/uint32-array
items:
minimum: 0
- maximum: 0xff
+ maximum: 0x2ff
+
+ linux,code:
+ description:
+ Specifies a single numeric keycode value to be used for reporting
+ button/switch events. Specify KEY_RESERVED (0) to opt out of event
+ reporting.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 0x2ff
+
+ linux,input-type:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 1 # EV_KEY
+ - 2 # EV_REL
+ - 3 # EV_ABS
+ - 5 # EV_SW
+ description:
+ Specifies whether the event is to be interpreted as a key, relative,
+ absolute, or switch.
poll-interval:
description: Poll interval time in milliseconds.
@@ -39,4 +58,7 @@ properties:
reset automatically. Device with key pressed reset feature can specify
this property.
+dependencies:
+ linux,input-type: [ "linux,code" ]
+
additionalProperties: true
diff --git a/Documentation/devicetree/bindings/input/iqs269a.yaml b/Documentation/devicetree/bindings/input/iqs269a.yaml
index 9c154e5e1a91..2c3f693b8982 100644
--- a/Documentation/devicetree/bindings/input/iqs269a.yaml
+++ b/Documentation/devicetree/bindings/input/iqs269a.yaml
@@ -9,6 +9,9 @@ title: Azoteq IQS269A Capacitive Touch Controller
maintainers:
- Jeff LaBundy <jeff@labundy.com>
+allOf:
+ - $ref: input.yaml#
+
description: |
The Azoteq IQS269A is an 8-channel capacitive touch controller that features
additional Hall-effect and inductive sensing capabilities.
@@ -17,7 +20,10 @@ description: |
properties:
compatible:
- const: azoteq,iqs269a
+ enum:
+ - azoteq,iqs269a
+ - azoteq,iqs269a-00
+ - azoteq,iqs269a-d0
reg:
maxItems: 1
@@ -204,6 +210,73 @@ properties:
default: 1
description: Specifies the slider coordinate filter strength.
+ azoteq,touch-hold-ms:
+ multipleOf: 256
+ minimum: 256
+ maximum: 65280
+ default: 5120
+ description:
+ Specifies the length of time (in ms) for which the channel selected by
+ 'azoteq,gpio3-select' must be held in a state of touch in order for an
+ approximately 60-ms pulse to be asserted on the GPIO4 pin.
+
+ linux,keycodes:
+ minItems: 1
+ maxItems: 8
+ description: |
+ Specifies the numeric keycodes associated with each available gesture in
+ the following order (enter 0 for unused gestures):
+ 0: Slider 0 tap
+ 1: Slider 0 hold
+ 2: Slider 0 positive flick or swipe
+ 3: Slider 0 negative flick or swipe
+ 4: Slider 1 tap
+ 5: Slider 1 hold
+ 6: Slider 1 positive flick or swipe
+ 7: Slider 1 negative flick or swipe
+
+ azoteq,gesture-swipe:
+ type: boolean
+ description:
+ Directs the device to interpret axial gestures as a swipe (finger remains
+ on slider) instead of a flick (finger leaves slider).
+
+ azoteq,timeout-tap-ms:
+ multipleOf: 16
+ minimum: 0
+ maximum: 4080
+ default: 400
+ description:
+ Specifies the length of time (in ms) within which a slider touch must be
+ released in order to be interpreted as a tap. Default and maximum values
+ as well as step size are reduced by a factor of 4 with device version 2.
+
+ azoteq,timeout-swipe-ms:
+ multipleOf: 16
+ minimum: 0
+ maximum: 4080
+ default: 2000
+ description:
+ Specifies the length of time (in ms) within which an axial gesture must be
+ completed in order to be interpreted as a flick or swipe. Default and max-
+ imum values as well as step size are reduced by a factor of 4 with device
+ version 2.
+
+ azoteq,thresh-swipe:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ default: 128
+ description:
+ Specifies the number of points across which an axial gesture must travel
+ in order to be interpreted as a flick or swipe.
+
+dependencies:
+ azoteq,gesture-swipe: ["linux,keycodes"]
+ azoteq,timeout-tap-ms: ["linux,keycodes"]
+ azoteq,timeout-swipe-ms: ["linux,keycodes"]
+ azoteq,thresh-swipe: ["linux,keycodes"]
+
patternProperties:
"^channel@[0-7]$":
type: object
@@ -370,6 +443,7 @@ patternProperties:
patternProperties:
"^event-prox(-alt)?$":
type: object
+ $ref: input.yaml#
description:
Represents a proximity event reported by the channel in response to
a decrease in counts. Node names suffixed with '-alt' instead corre-
@@ -396,14 +470,13 @@ patternProperties:
default: 10
description: Specifies the threshold for the event.
- linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: Numeric key or switch code associated with the event.
+ linux,code: true
additionalProperties: false
"^event-touch(-alt)?$":
type: object
+ $ref: input.yaml#
description: Represents a touch event reported by the channel.
properties:
@@ -421,14 +494,13 @@ patternProperties:
default: 4
description: Specifies the hysteresis for the event.
- linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: Numeric key or switch code associated with the event.
+ linux,code: true
additionalProperties: false
"^event-deep(-alt)?$":
type: object
+ $ref: input.yaml#
description: Represents a deep-touch event reported by the channel.
properties:
@@ -446,9 +518,7 @@ patternProperties:
default: 0
description: Specifies the hysteresis for the event.
- linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: Numeric key or switch code associated with the event.
+ linux,code: true
additionalProperties: false
@@ -457,6 +527,21 @@ patternProperties:
additionalProperties: false
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - azoteq,iqs269a-d0
+then:
+ patternProperties:
+ "^channel@[0-7]$":
+ properties:
+ azoteq,slider1-select: false
+else:
+ properties:
+ azoteq,touch-hold-ms: false
+
required:
- compatible
- reg
@@ -475,7 +560,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- iqs269a@44 {
+ touch@44 {
#address-cells = <1>;
#size-cells = <0>;
@@ -487,6 +572,14 @@ examples:
azoteq,hall-enable;
azoteq,suspend-mode = <2>;
+ linux,keycodes = <KEY_PLAYPAUSE>,
+ <KEY_STOPCD>,
+ <KEY_NEXTSONG>,
+ <KEY_PREVIOUSSONG>;
+
+ azoteq,timeout-tap-ms = <400>;
+ azoteq,timeout-swipe-ms = <800>;
+
channel@0 {
reg = <0x0>;
diff --git a/Documentation/devicetree/bindings/input/iqs626a.yaml b/Documentation/devicetree/bindings/input/iqs626a.yaml
index 0cb736c541c9..e424d67b0542 100644
--- a/Documentation/devicetree/bindings/input/iqs626a.yaml
+++ b/Documentation/devicetree/bindings/input/iqs626a.yaml
@@ -449,6 +449,7 @@ patternProperties:
patternProperties:
"^event-(prox|touch|deep)(-alt)?$":
type: object
+ $ref: input.yaml#
description:
Represents a proximity, touch or deep-touch event reported by the
channel in response to a decrease in counts. Node names suffixed with
@@ -487,21 +488,15 @@ patternProperties:
Specifies the hysteresis for the event (touch and deep-touch
events only).
- linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: Numeric key or switch code associated with the event.
+ linux,code: true
linux,input-type:
- $ref: /schemas/types.yaml#/definitions/uint32
enum: [1, 5]
description:
Specifies whether the event is to be interpreted as a key (1) or
a switch (5). By default, Hall-channel events are interpreted as
switches and all others are interpreted as keys.
- dependencies:
- linux,input-type: ["linux,code"]
-
additionalProperties: false
dependencies:
@@ -511,6 +506,7 @@ patternProperties:
"^trackpad-3x[2-3]$":
type: object
+ $ref: input.yaml#
description:
Represents all channels associated with the trackpad. The channels are
collectively active if the trackpad is defined and inactive otherwise.
@@ -568,16 +564,6 @@ patternProperties:
2: Partial
3: Full
- azoteq,ati-base:
- $ref: /schemas/types.yaml#/definitions/uint32-array
- minItems: 6
- maxItems: 9
- items:
- minimum: 45
- maximum: 300
- default: [45, 45, 45, 45, 45, 45, 45, 45, 45]
- description: Specifies each individual trackpad channel's ATI base.
-
azoteq,ati-target:
$ref: /schemas/types.yaml#/definitions/uint32
multipleOf: 32
@@ -624,17 +610,6 @@ patternProperties:
description:
Tightens the ATI band from 1/8 to 1/16 of the desired target.
- azoteq,thresh:
- $ref: /schemas/types.yaml#/definitions/uint32-array
- minItems: 6
- maxItems: 9
- items:
- minimum: 0
- maximum: 255
- default: [0, 0, 0, 0, 0, 0, 0, 0, 0]
- description:
- Specifies each individual trackpad channel's touch threshold.
-
azoteq,hyst:
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
@@ -679,7 +654,6 @@ patternProperties:
Specifies the raw count filter strength during low-power mode.
linux,keycodes:
- $ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 1
maxItems: 6
description: |
@@ -725,6 +699,28 @@ patternProperties:
Specifies the number of points across which an axial gesture must
travel in order to be interpreted as a flick or swipe.
+ patternProperties:
+ "^channel-[0-8]$":
+ type: object
+ description: Represents a single trackpad channel.
+
+ properties:
+ azoteq,thresh:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ default: 0
+ description: Specifies the threshold for the channel.
+
+ azoteq,ati-base:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 45
+ maximum: 300
+ default: 45
+ description: Specifies the channel's ATI base.
+
+ additionalProperties: false
+
dependencies:
azoteq,gesture-swipe: ["linux,keycodes"]
azoteq,timeout-tap-ms: ["linux,keycodes"]
@@ -751,7 +747,7 @@ examples:
#address-cells = <1>;
#size-cells = <0>;
- iqs626a@44 {
+ touch@44 {
#address-cells = <1>;
#size-cells = <0>;
@@ -785,14 +781,8 @@ examples:
azoteq,filt-str-lp-cnt = <1>;
azoteq,hyst = <4>;
- azoteq,thresh = <35>, <40>, <40>,
- <38>, <33>, <38>,
- <35>, <35>, <35>;
azoteq,ati-mode = <3>;
- azoteq,ati-base = <195>, <195>, <195>,
- <195>, <195>, <195>,
- <195>, <195>, <195>;
azoteq,ati-target = <512>;
azoteq,proj-bias = <1>;
@@ -809,6 +799,51 @@ examples:
azoteq,timeout-swipe-ms = <800>;
azoteq,timeout-tap-ms = <400>;
azoteq,thresh-swipe = <40>;
+
+ channel-0 {
+ azoteq,thresh = <35>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-1 {
+ azoteq,thresh = <40>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-2 {
+ azoteq,thresh = <40>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-3 {
+ azoteq,thresh = <38>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-4 {
+ azoteq,thresh = <33>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-5 {
+ azoteq,thresh = <38>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-6 {
+ azoteq,thresh = <35>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-7 {
+ azoteq,thresh = <35>;
+ azoteq,ati-base = <195>;
+ };
+
+ channel-8 {
+ azoteq,thresh = <35>;
+ azoteq,ati-base = <195>;
+ };
};
/*
diff --git a/Documentation/devicetree/bindings/input/iqs62x-keys.yaml b/Documentation/devicetree/bindings/input/iqs62x-keys.yaml
index 77fe3b545b35..0aa951f0ab92 100644
--- a/Documentation/devicetree/bindings/input/iqs62x-keys.yaml
+++ b/Documentation/devicetree/bindings/input/iqs62x-keys.yaml
@@ -9,6 +9,9 @@ title: Azoteq IQS620A/621/622/624/625 Keys and Switches
maintainers:
- Jeff LaBundy <jeff@labundy.com>
+allOf:
+ - $ref: input.yaml#
+
description: |
The Azoteq IQS620A, IQS621, IQS622, IQS624 and IQS625 multi-function sensors
feature a variety of self-capacitive, mutual-inductive and Hall-effect sens-
@@ -30,7 +33,6 @@ properties:
- azoteq,iqs625-keys
linux,keycodes:
- $ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 1
maxItems: 16
description: |
@@ -89,15 +91,14 @@ properties:
patternProperties:
"^hall-switch-(north|south)$":
type: object
+ $ref: input.yaml#
description:
Represents north/south-field Hall-effect sensor touch or proximity
events. Note that north/south-field orientation is reversed on the
IQS620AXzCSR device due to its flip-chip package.
properties:
- linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: Numeric switch code associated with the event.
+ linux,code: true
azoteq,use-prox:
$ref: /schemas/types.yaml#/definitions/flag
diff --git a/Documentation/devicetree/bindings/input/lpc32xx-key.txt b/Documentation/devicetree/bindings/input/lpc32xx-key.txt
deleted file mode 100644
index 2b075a080d30..000000000000
--- a/Documentation/devicetree/bindings/input/lpc32xx-key.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-NXP LPC32xx Key Scan Interface
-
-This binding is based on the matrix-keymap binding with the following
-changes:
-
-Required Properties:
-- compatible: Should be "nxp,lpc3220-key"
-- reg: Physical base address of the controller and length of memory mapped
- region.
-- interrupts: The interrupt number to the cpu.
-- clocks: phandle to clock controller plus clock-specifier pair
-- nxp,debounce-delay-ms: Debounce delay in ms
-- nxp,scan-delay-ms: Repeated scan period in ms
-- linux,keymap: the key-code to be reported when the key is pressed
- and released, see also
- Documentation/devicetree/bindings/input/matrix-keymap.txt
-
-Note: keypad,num-rows and keypad,num-columns are required, and must be equal
-since LPC32xx only supports square matrices
-
-Example:
-
- key@40050000 {
- compatible = "nxp,lpc3220-key";
- reg = <0x40050000 0x1000>;
- clocks = <&clk LPC32XX_CLK_KEY>;
- interrupt-parent = <&sic1>;
- interrupts = <22 IRQ_TYPE_LEVEL_HIGH>;
- keypad,num-rows = <1>;
- keypad,num-columns = <1>;
- nxp,debounce-delay-ms = <3>;
- nxp,scan-delay-ms = <34>;
- linux,keymap = <0x00000002>;
- };
diff --git a/Documentation/devicetree/bindings/input/matrix-keymap.yaml b/Documentation/devicetree/bindings/input/matrix-keymap.yaml
index 6699d5e32dca..a715c2a773fe 100644
--- a/Documentation/devicetree/bindings/input/matrix-keymap.yaml
+++ b/Documentation/devicetree/bindings/input/matrix-keymap.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/matrix-keymap.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Common key matrices binding for matrix-connected key boards
+title: Common Key Matrices on Matrix-connected Key Boards
maintainers:
- Olof Johansson <olof@lixom.net>
@@ -21,7 +21,7 @@ description: |
properties:
linux,keymap:
- $ref: '/schemas/types.yaml#/definitions/uint32-array'
+ $ref: /schemas/types.yaml#/definitions/uint32-array
description: |
An array of packed 1-cell entries containing the equivalent of row,
column and linux key-code. The 32-bit big endian cell is packed as:
diff --git a/Documentation/devicetree/bindings/input/max77650-onkey.yaml b/Documentation/devicetree/bindings/input/max77650-onkey.yaml
index 3a2ad6ec64db..48edc0c8c1dd 100644
--- a/Documentation/devicetree/bindings/input/max77650-onkey.yaml
+++ b/Documentation/devicetree/bindings/input/max77650-onkey.yaml
@@ -16,15 +16,15 @@ description: |
The onkey controller is represented as a sub-node of the PMIC node on
the device tree.
+allOf:
+ - $ref: input.yaml#
+
properties:
compatible:
const: maxim,max77650-onkey
linux,code:
- $ref: /schemas/types.yaml#/definitions/uint32
- description:
- The key-code to be reported when the key is pressed. Defaults
- to KEY_POWER.
+ default: 116 # KEY_POWER
maxim,onkey-slide:
$ref: /schemas/types.yaml#/definitions/flag
diff --git a/Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml b/Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml
new file mode 100644
index 000000000000..e365413732e7
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/mediatek,mt6779-keypad.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/mediatek,mt6779-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek's Keypad Controller
+
+maintainers:
+ - Mattijs Korpershoek <mkorpershoek@kernel.org>
+
+allOf:
+ - $ref: /schemas/input/matrix-keymap.yaml#
+
+description: |
+ Mediatek's Keypad controller is used to interface a SoC with a matrix-type
+ keypad device. The keypad controller supports multiple row and column lines.
+ A key can be placed at each intersection of a unique row and a unique column.
+ The keypad controller can sense a key-press and key-release and report the
+ event using a interrupt to the cpu.
+
+properties:
+ compatible:
+ oneOf:
+ - const: mediatek,mt6779-keypad
+ - items:
+ - enum:
+ - mediatek,mt6873-keypad
+ - mediatek,mt8183-keypad
+ - mediatek,mt8365-keypad
+ - mediatek,mt8516-keypad
+ - const: mediatek,mt6779-keypad
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: kpd
+
+ wakeup-source:
+ description: use any event on keypad as wakeup event
+ type: boolean
+
+ debounce-delay-ms:
+ maximum: 256
+ default: 16
+
+ mediatek,keys-per-group:
+ description: each (row, column) group has multiple keys
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 1
+ maximum: 2
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ keyboard@10010000 {
+ compatible = "mediatek,mt6779-keypad";
+ reg = <0 0x10010000 0 0x1000>;
+ interrupts = <GIC_SPI 75 IRQ_TYPE_EDGE_FALLING>;
+ clocks = <&clk26m>;
+ clock-names = "kpd";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/mediatek,pmic-keys.yaml b/Documentation/devicetree/bindings/input/mediatek,pmic-keys.yaml
new file mode 100644
index 000000000000..b95435bd6a9b
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/mediatek,pmic-keys.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/mediatek,pmic-keys.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek PMIC Keys
+
+maintainers:
+ - Chen Zhong <chen.zhong@mediatek.com>
+
+allOf:
+ - $ref: input.yaml#
+
+description: |
+ There are two key functions provided by MT6397, MT6323 and other MediaTek
+ PMICs: pwrkey and homekey.
+ The key functions are defined as the subnode of the function node provided
+ by the PMIC that is defined as a Multi-Function Device (MFD).
+
+ For MediaTek MT6323/MT6397 PMIC bindings see
+ Documentation/devicetree/bindings/mfd/mediatek,mt6397.yaml
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt6323-keys
+ - mediatek,mt6328-keys
+ - mediatek,mt6331-keys
+ - mediatek,mt6357-keys
+ - mediatek,mt6358-keys
+ - mediatek,mt6359-keys
+ - mediatek,mt6397-keys
+
+ power-off-time-sec: true
+
+ mediatek,long-press-mode:
+ description: |
+ Key long-press force shutdown setting
+ 0 - disabled
+ 1 - pwrkey
+ 2 - pwrkey+homekey
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+ maximum: 2
+
+patternProperties:
+ "^((power|home)|(key-[a-z0-9-]+|[a-z0-9-]+-key))$":
+ $ref: input.yaml#
+
+ properties:
+ interrupts:
+ minItems: 1
+ items:
+ - description: Key press interrupt
+ - description: Key release interrupt
+
+ interrupt-names: true
+
+ linux,keycodes:
+ maxItems: 1
+
+ wakeup-source: true
+
+ required:
+ - linux,keycodes
+
+ if:
+ properties:
+ interrupt-names:
+ contains:
+ const: powerkey
+ then:
+ properties:
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: powerkey
+ - const: powerkey_r
+ else:
+ properties:
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: homekey
+ - const: homekey_r
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+...
diff --git a/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml b/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml
new file mode 100644
index 000000000000..7ade03f1b32b
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml
@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/microchip,cap11xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip CAP11xx based capacitive touch sensors
+
+description: |
+ The Microchip CAP1xxx Family of RightTouchTM multiple-channel capacitive
+ touch controllers and LED drivers. The device communication via I2C only.
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - microchip,cap1106
+ - microchip,cap1126
+ - microchip,cap1188
+ - microchip,cap1203
+ - microchip,cap1206
+ - microchip,cap1293
+ - microchip,cap1298
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ interrupts:
+ maxItems: 1
+ description: |
+ Property describing the interrupt line the
+ device's ALERT#/CM_IRQ# pin is connected to.
+ The device only has one interrupt source.
+
+ autorepeat:
+ description: |
+ Enables the Linux input system's autorepeat feature on the input device.
+
+ linux,keycodes:
+ minItems: 3
+ maxItems: 8
+ description: |
+ Specifies an array of numeric keycode values to
+ be used for the channels. If this property is
+ omitted, KEY_A, KEY_B, etc are used as defaults.
+ The number of entries must correspond to the number of channels.
+
+ microchip,sensor-gain:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 1
+ enum: [1, 2, 4, 8]
+ description: |
+ Defines the gain of the sensor circuitry. This
+ effectively controls the sensitivity, as a
+ smaller delta capacitance is required to
+ generate the same delta count values.
+
+ microchip,irq-active-high:
+ type: boolean
+ description: |
+ By default the interrupt pin is active low
+ open drain. This property allows using the active
+ high push-pull output.
+
+ microchip,sensitivity-delta-sense:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 32
+ enum: [1, 2, 4, 8, 16, 32, 64, 128]
+ description:
+ Controls the sensitivity multiplier of a touch detection.
+ Higher value means more sensitive settings.
+ At the more sensitive settings, touches are detected for a smaller delta
+ capacitance corresponding to a "lighter" touch.
+
+ microchip,signal-guard:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 3
+ maxItems: 8
+ items:
+ enum: [0, 1]
+ description: |
+ 0 - off
+ 1 - on
+ The signal guard isolates the signal from virtual grounds.
+ If enabled then the behavior of the channel is changed to signal guard.
+ The number of entries must correspond to the number of channels.
+
+ microchip,input-threshold:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 3
+ maxItems: 8
+ items:
+ minimum: 0
+ maximum: 127
+ description:
+ Specifies the delta threshold that is used to determine if a touch has
+ been detected. A higher value means a larger difference in capacitance
+ is required for a touch to be registered, making the touch sensor less
+ sensitive.
+ The number of entries must correspond to the number of channels.
+
+ microchip,calib-sensitivity:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 3
+ maxItems: 8
+ items:
+ enum: [1, 2, 4]
+ description: |
+ Specifies an array of numeric values that controls the gain
+ used by the calibration routine to enable sensor inputs
+ to be more sensitive for proximity detection.
+ Gain is based on touch pad capacitance range
+ 1 - 5-50pF
+ 2 - 0-25pF
+ 4 - 0-12.5pF
+ The number of entries must correspond to the number of channels.
+
+patternProperties:
+ "^led@[0-7]$":
+ type: object
+ description: CAP11xx LEDs
+ $ref: /schemas/leds/common.yaml#
+
+ properties:
+ reg:
+ enum: [0, 1, 2, 3, 4, 5, 6, 7]
+
+ label: true
+
+ linux,default-trigger: true
+
+ default-state: true
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+allOf:
+ - $ref: input.yaml
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - microchip,cap1106
+ - microchip,cap1203
+ - microchip,cap1206
+ - microchip,cap1293
+ - microchip,cap1298
+ then:
+ patternProperties:
+ "^led@[0-7]$": false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - microchip,cap1106
+ - microchip,cap1126
+ - microchip,cap1188
+ - microchip,cap1203
+ - microchip,cap1206
+ then:
+ properties:
+ microchip,signal-guard: false
+ microchip,calib-sensitivity: false
+
+required:
+ - compatible
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touch@28 {
+ compatible = "microchip,cap1188";
+ interrupt-parent = <&gpio1>;
+ interrupts = <0 0>;
+ reg = <0x28>;
+ autorepeat;
+ microchip,sensor-gain = <2>;
+ microchip,sensitivity-delta-sense = <16>;
+ microchip,input-threshold = <21>, <18>, <46>, <46>, <46>, <21>;
+
+ linux,keycodes = <103>, /* KEY_UP */
+ <106>, /* KEY_RIGHT */
+ <108>, /* KEY_DOWN */
+ <105>, /* KEY_LEFT */
+ <109>, /* KEY_PAGEDOWN */
+ <104>; /* KEY_PAGEUP */
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ label = "cap11xx:green:usr0";
+ reg = <0>;
+ };
+
+ led@1 {
+ label = "cap11xx:green:usr1";
+ reg = <1>;
+ };
+
+ led@2 {
+ label = "cap11xx:green:alive";
+ reg = <2>;
+ linux,default-trigger = "heartbeat";
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt b/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt
deleted file mode 100644
index 535d92885372..000000000000
--- a/Documentation/devicetree/bindings/input/mtk-pmic-keys.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-MediaTek MT6397/MT6323 PMIC Keys Device Driver
-
-There are two key functions provided by MT6397/MT6323 PMIC, pwrkey
-and homekey. The key functions are defined as the subnode of the function
-node provided by MT6397/MT6323 PMIC that is being defined as one kind
-of Muti-Function Device (MFD)
-
-For MT6397/MT6323 MFD bindings see:
-Documentation/devicetree/bindings/mfd/mt6397.txt
-
-Required properties:
-- compatible: "mediatek,mt6397-keys" or "mediatek,mt6323-keys"
-- linux,keycodes: See Documentation/devicetree/bindings/input/input.yaml
-
-Optional Properties:
-- wakeup-source: See Documentation/devicetree/bindings/power/wakeup-source.txt
-- mediatek,long-press-mode: Long press key shutdown setting, 1 for
- pwrkey only, 2 for pwrkey/homekey together, others for disabled.
-- power-off-time-sec: See Documentation/devicetree/bindings/input/input.yaml
-
-Example:
-
- pmic: mt6397 {
- compatible = "mediatek,mt6397";
-
- ...
-
- mt6397keys: mt6397keys {
- compatible = "mediatek,mt6397-keys";
- mediatek,long-press-mode = <1>;
- power-off-time-sec = <0>;
-
- power {
- linux,keycodes = <116>;
- wakeup-source;
- };
-
- home {
- linux,keycodes = <114>;
- };
- };
-
- };
diff --git a/Documentation/devicetree/bindings/input/nxp,lpc3220-key.yaml b/Documentation/devicetree/bindings/input/nxp,lpc3220-key.yaml
new file mode 100644
index 000000000000..9e0d977bdf5c
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/nxp,lpc3220-key.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/nxp,lpc3220-key.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP LPC32xx Key Scan Interface
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: nxp,lpc3220-key
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ nxp,debounce-delay-ms:
+ description: Debounce delay in ms
+
+ nxp,scan-delay-ms:
+ description: Repeated scan period in ms
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - nxp,debounce-delay-ms
+ - nxp,scan-delay-ms
+ - linux,keymap
+
+allOf:
+ - $ref: matrix-keymap.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/lpc32xx-clock.h>
+
+ key@40050000 {
+ compatible = "nxp,lpc3220-key";
+ reg = <0x40050000 0x1000>;
+ clocks = <&clk LPC32XX_CLK_KEY>;
+ interrupt-parent = <&sic1>;
+ interrupts = <22 IRQ_TYPE_LEVEL_HIGH>;
+ keypad,num-rows = <1>;
+ keypad,num-columns = <1>;
+ nxp,debounce-delay-ms = <3>;
+ nxp,scan-delay-ms = <34>;
+ linux,keymap = <0x00000002>;
+ };
diff --git a/Documentation/devicetree/bindings/input/pine64,pinephone-keyboard.yaml b/Documentation/devicetree/bindings/input/pine64,pinephone-keyboard.yaml
new file mode 100644
index 000000000000..490f6c3d9e4b
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/pine64,pinephone-keyboard.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/pine64,pinephone-keyboard.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Pine64 PinePhone keyboard
+
+maintainers:
+ - Samuel Holland <samuel@sholland.org>
+
+description:
+ A keyboard accessory is available for the Pine64 PinePhone and PinePhone Pro.
+ It connects via I2C, providing a raw scan matrix, a flashing interface, and a
+ subordinate I2C bus for communication with a battery charger IC.
+
+properties:
+ compatible:
+ const: pine64,pinephone-keyboard
+
+ reg:
+ const: 0x15
+
+ interrupts:
+ maxItems: 1
+
+ vbat-supply:
+ description: Supply for the keyboard MCU
+
+ wakeup-source: true
+
+ i2c:
+ $ref: /schemas/i2c/i2c-controller.yaml#
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ keyboard@15 {
+ compatible = "pine64,pinephone-keyboard";
+ reg = <0x15>;
+ interrupt-parent = <&r_pio>;
+ interrupts = <0 12 IRQ_TYPE_EDGE_FALLING>; /* PL12 */
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ charger@75 {
+ reg = <0x75>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/pwm-beeper.txt b/Documentation/devicetree/bindings/input/pwm-beeper.txt
deleted file mode 100644
index 8fc0e48c20db..000000000000
--- a/Documentation/devicetree/bindings/input/pwm-beeper.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-* PWM beeper device tree bindings
-
-Registers a PWM device as beeper.
-
-Required properties:
-- compatible: should be "pwm-beeper"
-- pwms: phandle to the physical PWM device
-
-Optional properties:
-- amp-supply: phandle to a regulator that acts as an amplifier for the beeper
-- beeper-hz: bell frequency in Hz
-
-Example:
-
-beeper_amp: amplifier {
- compatible = "fixed-regulator";
- gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
-};
-
-beeper {
- compatible = "pwm-beeper";
- pwms = <&pwm0>;
- amp-supply = <&beeper_amp>;
-};
diff --git a/Documentation/devicetree/bindings/input/pwm-beeper.yaml b/Documentation/devicetree/bindings/input/pwm-beeper.yaml
new file mode 100644
index 000000000000..a7611c206989
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/pwm-beeper.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/pwm-beeper.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PWM beeper
+
+maintainers:
+ - Sascha Hauer <s.hauer@pengutronix.de>
+
+properties:
+ compatible:
+ const: pwm-beeper
+
+ pwms:
+ maxItems: 1
+
+ amp-supply:
+ description: an amplifier for the beeper
+
+ beeper-hz:
+ description: bell frequency in Hz
+ minimum: 10
+ maximum: 10000
+
+required:
+ - compatible
+ - pwms
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ beeper {
+ compatible = "pwm-beeper";
+ pwms = <&pwm0>;
+ amp-supply = <&beeper_amp>;
+ beeper-hz = <1000>;
+ };
diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.txt b/Documentation/devicetree/bindings/input/pwm-vibrator.txt
deleted file mode 100644
index 88c775a3fe21..000000000000
--- a/Documentation/devicetree/bindings/input/pwm-vibrator.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-* PWM vibrator device tree bindings
-
-Registers a PWM device as vibrator. It is expected, that the vibrator's
-strength increases based on the duty cycle of the enable PWM channel
-(100% duty cycle meaning strongest vibration, 0% meaning no vibration).
-
-The binding supports an optional direction PWM channel, that can be
-driven at fixed duty cycle. If available this is can be used to increase
-the vibration effect of some devices.
-
-Required properties:
-- compatible: should contain "pwm-vibrator"
-- pwm-names: Should contain "enable" and optionally "direction"
-- pwms: Should contain a PWM handle for each entry in pwm-names
-
-Optional properties:
-- vcc-supply: Phandle for the regulator supplying power
-- direction-duty-cycle-ns: Duty cycle of the direction PWM channel in
- nanoseconds, defaults to 50% of the channel's
- period.
-
-Example from Motorola Droid 4:
-
-&omap4_pmx_core {
- vibrator_direction_pin: pinmux_vibrator_direction_pin {
- pinctrl-single,pins = <
- OMAP4_IOPAD(0x1ce, PIN_OUTPUT | MUX_MODE1) /* dmtimer8_pwm_evt (gpio_27) */
- >;
- };
-
- vibrator_enable_pin: pinmux_vibrator_enable_pin {
- pinctrl-single,pins = <
- OMAP4_IOPAD(0X1d0, PIN_OUTPUT | MUX_MODE1) /* dmtimer9_pwm_evt (gpio_28) */
- >;
- };
-};
-
-/ {
- pwm8: dmtimer-pwm {
- pinctrl-names = "default";
- pinctrl-0 = <&vibrator_direction_pin>;
-
- compatible = "ti,omap-dmtimer-pwm";
- #pwm-cells = <3>;
- ti,timers = <&timer8>;
- ti,clock-source = <0x01>;
- };
-
- pwm9: dmtimer-pwm {
- pinctrl-names = "default";
- pinctrl-0 = <&vibrator_enable_pin>;
-
- compatible = "ti,omap-dmtimer-pwm";
- #pwm-cells = <3>;
- ti,timers = <&timer9>;
- ti,clock-source = <0x01>;
- };
-
- vibrator {
- compatible = "pwm-vibrator";
- pwms = <&pwm9 0 1000000000 0>,
- <&pwm8 0 1000000000 0>;
- pwm-names = "enable", "direction";
- direction-duty-cycle-ns = <1000000000>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.yaml b/Documentation/devicetree/bindings/input/pwm-vibrator.yaml
new file mode 100644
index 000000000000..6398534b43c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/pwm-vibrator.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/pwm-vibrator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PWM vibrator
+
+maintainers:
+ - Sebastian Reichel <sre@kernel.org>
+
+description: >
+ Registers a PWM device as vibrator. It is expected, that the vibrator's
+ strength increases based on the duty cycle of the enable PWM channel
+ (100% duty cycle meaning strongest vibration, 0% meaning no vibration).
+
+ The binding supports an optional direction PWM channel, that can be
+ driven at fixed duty cycle. If available this is can be used to increase
+ the vibration effect of some devices.
+
+properties:
+ compatible:
+ const: pwm-vibrator
+
+ pwm-names:
+ items:
+ - const: enable
+ - const: direction
+ minItems: 1
+
+ pwms:
+ minItems: 1
+ maxItems: 2
+
+ enable-gpios: true
+
+ vcc-supply: true
+
+ direction-duty-cycle-ns:
+ description: >
+ Duty cycle of the direction PWM channel in nanoseconds,
+ defaults to 50% of the channel's period.
+
+required:
+ - compatible
+ - pwm-names
+ - pwms
+
+additionalProperties: false
+
+examples:
+ - |
+ vibrator {
+ compatible = "pwm-vibrator";
+ pwms = <&pwm9 0 1000000000 0>,
+ <&pwm8 0 1000000000 0>;
+ pwm-names = "enable", "direction";
+ direction-duty-cycle-ns = <1000000000>;
+ };
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml b/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml
new file mode 100644
index 000000000000..e03611eef93d
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/qcom,pm8921-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm PM8921 PMIC KeyPad
+
+maintainers:
+ - Dmitry Baryshkov <dmitry.baryshkov@linaro.org>
+
+allOf:
+ - $ref: input.yaml#
+ - $ref: matrix-keymap.yaml#
+
+properties:
+ compatible:
+ enum:
+ - qcom,pm8058-keypad
+ - qcom,pm8921-keypad
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: key sense
+ - description: key stuck
+
+ wakeup-source:
+ type: boolean
+ description: use any event on keypad as wakeup event
+
+ linux,keypad-wakeup:
+ type: boolean
+ deprecated: true
+ description: legacy version of the wakeup-source property
+
+ debounce:
+ description:
+ Time in microseconds that key must be pressed or
+ released for state change interrupt to trigger.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ scan-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: time in microseconds to pause between successive scans of the
+ matrix array
+
+ row-hold:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: time in nanoseconds to pause between scans of each row in the
+ matrix array.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - linux,keymap
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ pmic {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ keypad@148 {
+ compatible = "qcom,pm8921-keypad";
+ reg = <0x148>;
+ interrupt-parent = <&pmicintc>;
+ interrupts = <74 IRQ_TYPE_EDGE_RISING>, <75 IRQ_TYPE_EDGE_RISING>;
+ linux,keymap = <
+ MATRIX_KEY(0, 0, KEY_VOLUMEUP)
+ MATRIX_KEY(0, 1, KEY_VOLUMEDOWN)
+ MATRIX_KEY(0, 2, KEY_CAMERA_FOCUS)
+ MATRIX_KEY(0, 3, KEY_CAMERA)
+ >;
+ keypad,num-rows = <1>;
+ keypad,num-columns = <5>;
+ debounce = <15>;
+ scan-delay = <32>;
+ row-hold = <91500>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml b/Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml
new file mode 100644
index 000000000000..64590894857a
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/qcom,pm8921-pwrkey.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/qcom,pm8921-pwrkey.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm PM8921 PMIC Power Key
+
+maintainers:
+ - Bjorn Andersson <andersson@kernel.org>
+
+allOf:
+ - $ref: input.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - qcom,pm8921-pwrkey
+ - qcom,pm8058-pwrkey
+ - items:
+ - enum:
+ - qcom,pm8018-pwrkey
+ - const: qcom,pm8921-pwrkey
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: key release
+ - description: key press
+
+ debounce:
+ description:
+ Time in microseconds that key must be pressed or
+ released for state change interrupt to trigger.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ pull-up:
+ description:
+ Presence of this property indicates that the KPDPWR_N
+ pin should be configured for pull up.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ ssbi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pmic@0 {
+ reg = <0x0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ pwrkey@1c {
+ compatible = "qcom,pm8921-pwrkey";
+ reg = <0x1c>;
+ interrupt-parent = <&pmicint>;
+ interrupts = <50 IRQ_TYPE_EDGE_RISING>, <51 IRQ_TYPE_EDGE_RISING>;
+ debounce = <15625>;
+ pull-up;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt b/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt
deleted file mode 100644
index 6cd08bca2c66..000000000000
--- a/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.txt
+++ /dev/null
@@ -1,55 +0,0 @@
-Qualcomm PM8941 PMIC Power Key
-
-PROPERTIES
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,pm8941-pwrkey"
- "qcom,pm8941-resin"
- "qcom,pmk8350-pwrkey"
- "qcom,pmk8350-resin"
-
-- reg:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: base address of registers for block
-
-- interrupts:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: key change interrupt; The format of the specifier is
- defined by the binding document describing the node's
- interrupt parent.
-
-- debounce:
- Usage: optional
- Value type: <u32>
- Definition: time in microseconds that key must be pressed or released
- for state change interrupt to trigger.
-
-- bias-pull-up:
- Usage: optional
- Value type: <empty>
- Definition: presence of this property indicates that the KPDPWR_N pin
- should be configured for pull up.
-
-- linux,code:
- Usage: optional
- Value type: <u32>
- Definition: The input key-code associated with the power key.
- Use the linux event codes defined in
- include/dt-bindings/input/linux-event-codes.h
- When property is omitted KEY_POWER is assumed.
-
-EXAMPLE
-
- pwrkey@800 {
- compatible = "qcom,pm8941-pwrkey";
- reg = <0x800>;
- interrupts = <0x0 0x8 0 IRQ_TYPE_EDGE_BOTH>;
- debounce = <15625>;
- bias-pull-up;
- linux,code = <KEY_POWER>;
- };
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml b/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml
new file mode 100644
index 000000000000..f978cf965a4d
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/qcom,pm8941-pwrkey.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/qcom,pm8941-pwrkey.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm PM8941 PMIC Power Key
+
+maintainers:
+ - Courtney Cavin <courtney.cavin@sonymobile.com>
+ - Vinod Koul <vkoul@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - qcom,pm8941-pwrkey
+ - qcom,pm8941-resin
+ - qcom,pmk8350-pwrkey
+ - qcom,pmk8350-resin
+
+ interrupts:
+ maxItems: 1
+
+ debounce:
+ description:
+ Time in microseconds that key must be pressed or released for state
+ change interrupt to trigger.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ bias-pull-up:
+ description:
+ Presence of this property indicates that the KPDPWR_N pin should be
+ configured for pull up.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ wakeup-source:
+ description:
+ Button can wake-up the system. Only applicable for 'resin', 'pwrkey'
+ always wakes the system by default.
+
+ linux,code:
+ description:
+ The input key-code associated with the power key. Use the linux event
+ codes defined in include/dt-bindings/input/linux-event-codes.h.
+ When property is omitted KEY_POWER is assumed.
+
+allOf:
+ - $ref: input.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,pm8941-pwrkey
+ - qcom,pmk8350-pwrkey
+ then:
+ properties:
+ wakeup-source: false
+
+required:
+ - compatible
+ - interrupts
+
+unevaluatedProperties: false
+...
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt
deleted file mode 100644
index 4a9dc6ba96b1..000000000000
--- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt
+++ /dev/null
@@ -1,90 +0,0 @@
-Qualcomm PM8xxx PMIC Keypad
-
-PROPERTIES
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,pm8058-keypad"
- "qcom,pm8921-keypad"
-
-- reg:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: address of keypad control register
-
-- interrupts:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: the first interrupt specifies the key sense interrupt
- and the second interrupt specifies the key stuck interrupt.
- The format of the specifier is defined by the binding
- document describing the node's interrupt parent.
-
-- linux,keymap:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: the linux keymap. More information can be found in
- input/matrix-keymap.txt.
-
-- linux,keypad-no-autorepeat:
- Usage: optional
- Value type: <bool>
- Definition: don't enable autorepeat feature.
-
-- wakeup-source:
- Usage: optional
- Value type: <bool>
- Definition: use any event on keypad as wakeup event.
- (Legacy property supported: "linux,keypad-wakeup")
-
-- keypad,num-rows:
- Usage: required
- Value type: <u32>
- Definition: number of rows in the keymap. More information can be found
- in input/matrix-keymap.txt.
-
-- keypad,num-columns:
- Usage: required
- Value type: <u32>
- Definition: number of columns in the keymap. More information can be
- found in input/matrix-keymap.txt.
-
-- debounce:
- Usage: optional
- Value type: <u32>
- Definition: time in microseconds that key must be pressed or release
- for key sense interrupt to trigger.
-
-- scan-delay:
- Usage: optional
- Value type: <u32>
- Definition: time in microseconds to pause between successive scans
- of the matrix array.
-
-- row-hold:
- Usage: optional
- Value type: <u32>
- Definition: time in nanoseconds to pause between scans of each row in
- the matrix array.
-
-EXAMPLE
-
- keypad@148 {
- compatible = "qcom,pm8921-keypad";
- reg = <0x148>;
- interrupt-parent = <&pmicintc>;
- interrupts = <74 1>, <75 1>;
- linux,keymap = <
- MATRIX_KEY(0, 0, KEY_VOLUMEUP)
- MATRIX_KEY(0, 1, KEY_VOLUMEDOWN)
- MATRIX_KEY(0, 2, KEY_CAMERA_FOCUS)
- MATRIX_KEY(0, 3, KEY_CAMERA)
- >;
- keypad,num-rows = <1>;
- keypad,num-columns = <5>;
- debounce = <15>;
- scan-delay = <32>;
- row-hold = <91500>;
- };
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt
deleted file mode 100644
index 588536cc96ed..000000000000
--- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-pwrkey.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-Qualcomm PM8xxx PMIC Power Key
-
-PROPERTIES
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,pm8058-pwrkey"
- "qcom,pm8921-pwrkey"
-
-- reg:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: address of power key control register
-
-- interrupts:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: the first interrupt specifies the key release interrupt
- and the second interrupt specifies the key press interrupt.
- The format of the specifier is defined by the binding
- document describing the node's interrupt parent.
-
-- debounce:
- Usage: optional
- Value type: <u32>
- Definition: time in microseconds that key must be pressed or release
- for state change interrupt to trigger.
-
-- pull-up:
- Usage: optional
- Value type: <empty>
- Definition: presence of this property indicates that the KPDPWR_N pin
- should be configured for pull up.
-
-EXAMPLE
-
- pwrkey@1c {
- compatible = "qcom,pm8921-pwrkey";
- reg = <0x1c>;
- interrupt-parent = <&pmicintc>;
- interrupts = <50 1>, <51 1>;
- debounce = <15625>;
- pull-up;
- };
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt
deleted file mode 100644
index 64bb990075c3..000000000000
--- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Qualcomm PM8xxx PMIC Vibrator
-
-PROPERTIES
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: must be one of:
- "qcom,pm8058-vib"
- "qcom,pm8916-vib"
- "qcom,pm8921-vib"
-
-- reg:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: address of vibration control register
-
-EXAMPLE
-
- vibrator@4a {
- compatible = "qcom,pm8058-vib";
- reg = <0x4a>;
- };
diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.yaml b/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.yaml
new file mode 100644
index 000000000000..76a286ec5959
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/qcom,pm8xxx-vib.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm PM8xxx PMIC Vibrator
+
+maintainers:
+ - Bjorn Andersson <andersson@kernel.org>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - qcom,pm8058-vib
+ - qcom,pm8916-vib
+ - qcom,pm8921-vib
+ - qcom,pmi632-vib
+ - items:
+ - enum:
+ - qcom,pm6150-vib
+ - qcom,pm7250b-vib
+ - qcom,pm7325b-vib
+ - qcom,pm7550ba-vib
+ - const: qcom,pmi632-vib
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ pmic {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vibrator@4a {
+ compatible = "qcom,pm8058-vib";
+ reg = <0x4a>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/regulator-haptic.txt b/Documentation/devicetree/bindings/input/regulator-haptic.txt
deleted file mode 100644
index 3ed1c7eb2f97..000000000000
--- a/Documentation/devicetree/bindings/input/regulator-haptic.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-* Regulator Haptic Device Tree Bindings
-
-Required Properties:
- - compatible : Should be "regulator-haptic"
- - haptic-supply : Power supply to the haptic motor.
- [*] refer Documentation/devicetree/bindings/regulator/regulator.txt
-
- - max-microvolt : The maximum voltage value supplied to the haptic motor.
- [The unit of the voltage is a micro]
-
- - min-microvolt : The minimum voltage value supplied to the haptic motor.
- [The unit of the voltage is a micro]
-
-Example:
-
- haptics {
- compatible = "regulator-haptic";
- haptic-supply = <&motor_regulator>;
- max-microvolt = <2700000>;
- min-microvolt = <1100000>;
- };
diff --git a/Documentation/devicetree/bindings/input/regulator-haptic.yaml b/Documentation/devicetree/bindings/input/regulator-haptic.yaml
new file mode 100644
index 000000000000..cf63f834dd7d
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/regulator-haptic.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/regulator-haptic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Regulator Haptic
+
+maintainers:
+ - Jaewon Kim <jaewon02.kim@samsung.com>
+
+properties:
+ compatible:
+ const: regulator-haptic
+
+ haptic-supply:
+ description: >
+ Power supply to the haptic motor
+
+ max-microvolt:
+ description: >
+ The maximum voltage value supplied to the haptic motor
+
+ min-microvolt:
+ description: >
+ The minimum voltage value supplied to the haptic motor
+
+required:
+ - compatible
+ - haptic-supply
+ - max-microvolt
+ - min-microvolt
+
+additionalProperties: false
+
+examples:
+ - |
+ haptics {
+ compatible = "regulator-haptic";
+ haptic-supply = <&motor_regulator>;
+ max-microvolt = <2700000>;
+ min-microvolt = <1100000>;
+ };
diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt
deleted file mode 100644
index 9afffbdf6e28..000000000000
--- a/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Synaptics RMI4 2D Sensor Device Binding
-
-The Synaptics RMI4 core is able to support RMI4 devices using different
-transports and different functions. This file describes the device tree
-bindings for devices which contain 2D sensors using Function 11 or
-Function 12. Complete documentation for transports and other functions
-can be found in:
-Documentation/devicetree/bindings/input/rmi4.
-
-RMI4 Function 11 and Function 12 are for 2D touch position sensing.
-Additional documentation for F11 can be found at:
-http://www.synaptics.com/sites/default/files/511-000136-01-Rev-E-RMI4-Interfacing-Guide.pdf
-
-Optional Touch Properties:
-Description in Documentation/devicetree/bindings/input/touchscreen
-- touchscreen-inverted-x
-- touchscreen-inverted-y
-- touchscreen-swapped-x-y
-- touchscreen-x-mm
-- touchscreen-y-mm
-
-Optional Properties:
-- syna,clip-x-low: Sets a minimum value for X.
-- syna,clip-y-low: Sets a minimum value for Y.
-- syna,clip-x-high: Sets a maximum value for X.
-- syna,clip-y-high: Sets a maximum value for Y.
-- syna,offset-x: Add an offset to X.
-- syna,offset-y: Add an offset to Y.
-- syna,delta-x-threshold: Set the minimum distance on the X axis required
- to generate an interrupt in reduced reporting
- mode.
-- syna,delta-y-threshold: Set the minimum distance on the Y axis required
- to generate an interrupt in reduced reporting
- mode.
-- syna,sensor-type: Set the sensor type. 1 for touchscreen 2 for touchpad.
-- syna,disable-report-mask: Mask for disabling posiiton reporting. Used to
- disable reporing absolute position data.
-- syna,rezero-wait-ms: Time in miliseconds to wait after issuing a rezero
- command.
-
-
-Example of a RMI4 I2C device with F11:
-Example:
- &i2c1 {
- rmi4-i2c-dev@2c {
- compatible = "syna,rmi4-i2c";
-
- ...
-
- rmi4-f11@11 {
- reg = <0x11>;
- touchscreen-inverted-y;
- syna,sensor-type = <2>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt
deleted file mode 100644
index 079cad2b6843..000000000000
--- a/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Synaptics RMI4 F01 Device Binding
-
-The Synaptics RMI4 core is able to support RMI4 devices using different
-transports and different functions. This file describes the device tree
-bindings for devices which contain Function 1. Complete documentation
-for transports and other functions can be found in:
-Documentation/devicetree/bindings/input/rmi4.
-
-Additional documentation for F01 can be found at:
-http://www.synaptics.com/sites/default/files/511-000136-01-Rev-E-RMI4-Interfacing-Guide.pdf
-
-Optional Properties:
-- syna,nosleep-mode: If set the device will run at full power without sleeping.
- nosleep has 3 modes, 0 will not change the default
- setting, 1 will disable nosleep (allow sleeping),
- and 2 will enable nosleep (disabling sleep).
-- syna,wakeup-threshold: Defines the amplitude of the disturbance to the
- background capacitance that will cause the
- device to wake from dozing.
-- syna,doze-holdoff-ms: The delay to wait after the last finger lift and the
- first doze cycle.
-- syna,doze-interval-ms: The time period that the device sleeps between finger
- activity.
-
-
-Example of a RMI4 I2C device with F01:
- Example:
- &i2c1 {
- rmi4-i2c-dev@2c {
- compatible = "syna,rmi4-i2c";
-
- ...
-
- rmi4-f01@1 {
- reg = <0x1>;
- syna,nosleep-mode = <1>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt
deleted file mode 100644
index dcb012f5b3ee..000000000000
--- a/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-Synaptics RMI4 I2C Device Binding
-
-The Synaptics RMI4 core is able to support RMI4 devices using different
-transports and different functions. This file describes the device tree
-bindings for devices using the I2C transport driver. Complete documentation
-for other transports and functions can be found in
-Documentation/devicetree/bindings/input/rmi4.
-
-Required Properties:
-- compatible: syna,rmi4-i2c
-- reg: I2C address
-- #address-cells: Set to 1 to indicate that the function child nodes
- consist of only on uint32 value.
-- #size-cells: Set to 0 to indicate that the function child nodes do not
- have a size property.
-
-Optional Properties:
-- interrupts: interrupt which the rmi device is connected to.
-See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-
-- syna,reset-delay-ms: The number of milliseconds to wait after resetting the
- device.
-
-- syna,startup-delay-ms: The number of milliseconds to wait after powering on
- the device.
-
-- vdd-supply: VDD power supply.
-See ../regulator/regulator.txt
-
-- vio-supply: VIO power supply
-See ../regulator/regulator.txt
-
-Function Parameters:
-Parameters specific to RMI functions are contained in child nodes of the rmi device
- node. Documentation for the parameters of each function can be found in:
-Documentation/devicetree/bindings/input/rmi4/rmi_f*.txt.
-
-
-
-Example:
- &i2c1 {
- rmi4-i2c-dev@2c {
- compatible = "syna,rmi4-i2c";
- reg = <0x2c>;
- #address-cells = <1>;
- #size-cells = <0>;
- interrupt-parent = <&gpio>;
- interrupts = <4 2>;
-
- rmi4-f01@1 {
- reg = <0x1>;
- syna,nosleep-mode = <1>;
- };
-
- rmi4-f11@11 {
- reg = <0x11>;
- touchscreen-inverted-y;
- syna,sensor-type = <2>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt
deleted file mode 100644
index 632f473db65b..000000000000
--- a/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-Synaptics RMI4 SPI Device Binding
-
-The Synaptics RMI4 core is able to support RMI4 devices using different
-transports and different functions. This file describes the device tree
-bindings for devices using the SPI transport driver. Complete documentation
-for other transports and functions can be found in
-Documentation/devicetree/bindings/input/rmi4.
-
-Required Properties:
-- compatible: syna,rmi4-spi
-- reg: Chip select address for the device
-- #address-cells: Set to 1 to indicate that the function child nodes
- consist of only on uint32 value.
-- #size-cells: Set to 0 to indicate that the function child nodes do not
- have a size property.
-
-Optional Properties:
-- interrupts: interrupt which the rmi device is connected to.
-See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-
-- spi-rx-delay-us: microsecond delay after a read transfer.
-- spi-tx-delay-us: microsecond delay after a write transfer.
-
-Function Parameters:
-Parameters specific to RMI functions are contained in child nodes of the rmi device
- node. Documentation for the parameters of each function can be found in:
-Documentation/devicetree/bindings/input/rmi4/rmi_f*.txt.
-
-
-
-Example:
- spi@7000d800 {
- rmi4-spi-dev@0 {
- compatible = "syna,rmi4-spi";
- reg = <0x0>;
- #address-cells = <1>;
- #size-cells = <0>;
- spi-max-frequency = <4000000>;
- spi-cpha;
- spi-cpol;
- interrupt-parent = <&gpio>;
- interrupts = <TEGRA_GPIO(K, 2) 0x2>;
- spi-rx-delay-us = <30>;
-
- rmi4-f01@1 {
- reg = <0x1>;
- syna,nosleep-mode = <1>;
- };
-
- rmi4-f11@11 {
- reg = <0x11>;
- touchscreen-inverted-y;
- syna,sensor-type = <2>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/input/rotary-encoder.txt b/Documentation/devicetree/bindings/input/rotary-encoder.txt
deleted file mode 100644
index a644408b33b8..000000000000
--- a/Documentation/devicetree/bindings/input/rotary-encoder.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-Rotary encoder DT bindings
-
-Required properties:
-- gpios: a spec for at least two GPIOs to be used, most significant first
-
-Optional properties:
-- linux,axis: the input subsystem axis to map to this rotary encoder.
- Defaults to 0 (ABS_X / REL_X)
-- rotary-encoder,steps: Number of steps in a full turnaround of the
- encoder. Only relevant for absolute axis. Defaults to 24 which is a
- typical value for such devices.
-- rotary-encoder,relative-axis: register a relative axis rather than an
- absolute one. Relative axis will only generate +1/-1 events on the input
- device, hence no steps need to be passed.
-- rotary-encoder,rollover: Automatic rollover when the rotary value becomes
- greater than the specified steps or smaller than 0. For absolute axis only.
-- rotary-encoder,steps-per-period: Number of steps (stable states) per period.
- The values have the following meaning:
- 1: Full-period mode (default)
- 2: Half-period mode
- 4: Quarter-period mode
-- wakeup-source: Boolean, rotary encoder can wake up the system.
-- rotary-encoder,encoding: String, the method used to encode steps.
- Supported are "gray" (the default and more common) and "binary".
-
-Deprecated properties:
-- rotary-encoder,half-period: Makes the driver work on half-period mode.
- This property is deprecated. Instead, a 'steps-per-period ' value should
- be used, such as "rotary-encoder,steps-per-period = <2>".
-
-See Documentation/input/devices/rotary-encoder.rst for more information.
-
-Example:
-
- rotary@0 {
- compatible = "rotary-encoder";
- gpios = <&gpio 19 1>, <&gpio 20 0>; /* GPIO19 is inverted */
- linux,axis = <0>; /* REL_X */
- rotary-encoder,encoding = "gray";
- rotary-encoder,relative-axis;
- };
-
- rotary@1 {
- compatible = "rotary-encoder";
- gpios = <&gpio 21 0>, <&gpio 22 0>;
- linux,axis = <1>; /* ABS_Y */
- rotary-encoder,steps = <24>;
- rotary-encoder,encoding = "binary";
- rotary-encoder,rollover;
- };
diff --git a/Documentation/devicetree/bindings/input/rotary-encoder.yaml b/Documentation/devicetree/bindings/input/rotary-encoder.yaml
new file mode 100644
index 000000000000..f9332bb2343f
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/rotary-encoder.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/rotary-encoder.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rotary encoder
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description:
+ See Documentation/input/devices/rotary-encoder.rst for more information.
+
+properties:
+ compatible:
+ const: rotary-encoder
+
+ gpios:
+ minItems: 2
+
+ linux,axis:
+ default: 0
+ description:
+ the input subsystem axis to map to this rotary encoder.
+ Defaults to 0 (ABS_X / REL_X)
+
+ rotary-encoder,steps:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 24
+ description:
+ Number of steps in a full turnaround of the
+ encoder. Only relevant for absolute axis. Defaults to 24 which is a
+ typical value for such devices.
+
+ rotary-encoder,relative-axis:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ register a relative axis rather than an
+ absolute one. Relative axis will only generate +1/-1 events on the input
+ device, hence no steps need to be passed.
+
+ rotary-encoder,rollover:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Automatic rollover when the rotary value becomes
+ greater than the specified steps or smaller than 0. For absolute axis only.
+
+ rotary-encoder,steps-per-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 1
+ enum: [1, 2, 4]
+ description: |
+ Number of steps (stable states) per period.
+ The values have the following meaning:
+ 1: Full-period mode (default)
+ 2: Half-period mode
+ 4: Quarter-period mode
+
+ wakeup-source: true
+
+ rotary-encoder,encoding:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: the method used to encode steps.
+ enum: [gray, binary]
+
+ rotary-encoder,half-period:
+ $ref: /schemas/types.yaml#/definitions/flag
+ deprecated: true
+ description:
+ Makes the driver work on half-period mode.
+ This property is deprecated. Instead, a 'steps-per-period ' value should
+ be used, such as "rotary-encoder,steps-per-period = <2>".
+
+required:
+ - compatible
+ - gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ rotary {
+ compatible = "rotary-encoder";
+ gpios = <&gpio 19 1>, <&gpio 20 0>; /* GPIO19 is inverted */
+ linux,axis = <0>; /* REL_X */
+ rotary-encoder,encoding = "gray";
+ rotary-encoder,relative-axis;
+ };
+
diff --git a/Documentation/devicetree/bindings/input/samsung,s3c6410-keypad.yaml b/Documentation/devicetree/bindings/input/samsung,s3c6410-keypad.yaml
new file mode 100644
index 000000000000..a53569aa0ee7
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/samsung,s3c6410-keypad.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/samsung,s3c6410-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung SoC series Keypad Controller
+
+description:
+ Samsung SoC Keypad controller is used to interface a SoC with a matrix-type
+ keypad device. The keypad controller supports multiple row and column lines.
+ A key can be placed at each intersection of a unique row and a unique column.
+ The keypad controller can sense a key-press and key-release and report the
+ event using a interrupt to the cpu.
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - samsung,s3c6410-keypad
+ - samsung,s5pv210-keypad
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: keypad
+
+ interrupts:
+ maxItems: 1
+
+ wakeup-source: true
+
+ linux,input-no-autorepeat:
+ type: boolean
+ description:
+ Do no enable autorepeat feature.
+
+ linux,input-wakeup:
+ type: boolean
+ deprecated: true
+
+ samsung,keypad-num-columns:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Number of column lines connected to the keypad controller.
+
+ samsung,keypad-num-rows:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Number of row lines connected to the keypad controller.
+
+patternProperties:
+ '^key-[0-9a-z]+$':
+ type: object
+ $ref: input.yaml#
+ additionalProperties: false
+ description:
+ Each key connected to the keypad controller is represented as a child
+ node to the keypad controller device node.
+
+ properties:
+ keypad,column:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The column number to which the key is connected.
+
+ keypad,row:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The row number to which the key is connected.
+
+ linux,code: true
+
+ required:
+ - keypad,column
+ - keypad,row
+ - linux,code
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - samsung,keypad-num-columns
+ - samsung,keypad-num-rows
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ keypad@100a0000 {
+ compatible = "samsung,s5pv210-keypad";
+ reg = <0x100a0000 0x100>;
+ interrupts = <GIC_SPI 109 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clock CLK_KEYIF>;
+ clock-names = "keypad";
+
+ samsung,keypad-num-rows = <2>;
+ samsung,keypad-num-columns = <8>;
+ linux,input-no-autorepeat;
+ wakeup-source;
+
+ key-1 {
+ keypad,row = <0>;
+ keypad,column = <3>;
+ linux,code = <2>;
+ };
+
+ key-2 {
+ keypad,row = <0>;
+ keypad,column = <4>;
+ linux,code = <3>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/samsung-keypad.txt b/Documentation/devicetree/bindings/input/samsung-keypad.txt
deleted file mode 100644
index 4c5c0a82586d..000000000000
--- a/Documentation/devicetree/bindings/input/samsung-keypad.txt
+++ /dev/null
@@ -1,77 +0,0 @@
-* Samsung's Keypad Controller device tree bindings
-
-Samsung's Keypad controller is used to interface a SoC with a matrix-type
-keypad device. The keypad controller supports multiple row and column lines.
-A key can be placed at each intersection of a unique row and a unique column.
-The keypad controller can sense a key-press and key-release and report the
-event using a interrupt to the cpu.
-
-Required SoC Specific Properties:
-- compatible: should be one of the following
- - "samsung,s3c6410-keypad": For controllers compatible with s3c6410 keypad
- controller.
- - "samsung,s5pv210-keypad": For controllers compatible with s5pv210 keypad
- controller.
-
-- reg: physical base address of the controller and length of memory mapped
- region.
-
-- interrupts: The interrupt number to the cpu.
-
-Required Board Specific Properties:
-- samsung,keypad-num-rows: Number of row lines connected to the keypad
- controller.
-
-- samsung,keypad-num-columns: Number of column lines connected to the
- keypad controller.
-
-- Keys represented as child nodes: Each key connected to the keypad
- controller is represented as a child node to the keypad controller
- device node and should include the following properties.
- - keypad,row: the row number to which the key is connected.
- - keypad,column: the column number to which the key is connected.
- - linux,code: the key-code to be reported when the key is pressed
- and released.
-
-- pinctrl-0: Should specify pin control groups used for this controller.
-- pinctrl-names: Should contain only one value - "default".
-
-Optional Properties:
-- wakeup-source: use any event on keypad as wakeup event.
- (Legacy property supported: "linux,input-wakeup")
-
-Optional Properties specific to linux:
-- linux,keypad-no-autorepeat: do no enable autorepeat feature.
-
-
-Example:
- keypad@100a0000 {
- compatible = "samsung,s5pv210-keypad";
- reg = <0x100A0000 0x100>;
- interrupts = <173>;
- samsung,keypad-num-rows = <2>;
- samsung,keypad-num-columns = <8>;
- linux,input-no-autorepeat;
- wakeup-source;
-
- pinctrl-names = "default";
- pinctrl-0 = <&keypad_rows &keypad_columns>;
-
- key_1 {
- keypad,row = <0>;
- keypad,column = <3>;
- linux,code = <2>;
- };
-
- key_2 {
- keypad,row = <0>;
- keypad,column = <4>;
- linux,code = <3>;
- };
-
- key_3 {
- keypad,row = <0>;
- keypad,column = <5>;
- linux,code = <4>;
- };
- };
diff --git a/Documentation/devicetree/bindings/input/snvs-pwrkey.txt b/Documentation/devicetree/bindings/input/snvs-pwrkey.txt
deleted file mode 100644
index 70c14250323b..000000000000
--- a/Documentation/devicetree/bindings/input/snvs-pwrkey.txt
+++ /dev/null
@@ -1 +0,0 @@
-See Documentation/devicetree/bindings/crypto/fsl-sec4.txt
diff --git a/Documentation/devicetree/bindings/input/sprd,sc27xx-vibrator.yaml b/Documentation/devicetree/bindings/input/sprd,sc27xx-vibrator.yaml
index 5d67fc8ebc18..4c8d303ff93c 100644
--- a/Documentation/devicetree/bindings/input/sprd,sc27xx-vibrator.yaml
+++ b/Documentation/devicetree/bindings/input/sprd,sc27xx-vibrator.yaml
@@ -5,7 +5,7 @@
$id: http://devicetree.org/schemas/input/sprd,sc27xx-vibrator.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Spreadtrum SC27xx PMIC Vibrator Device Tree Bindings
+title: Spreadtrum SC27xx PMIC Vibrator
maintainers:
- Orson Zhai <orsonzhai@gmail.com>
@@ -28,21 +28,4 @@ required:
additionalProperties: false
-examples:
- - |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- sc2731_pmic: pmic@0 {
- compatible = "sprd,sc2731";
- reg = <0 0>;
- spi-max-frequency = <26000000>;
- interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-controller;
- #interrupt-cells = <2>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- vibrator@eb4 {
- compatible = "sprd,sc2731-vibrator";
- reg = <0xeb4>;
- };
- };
+...
diff --git a/Documentation/devicetree/bindings/input/stmpe-keypad.txt b/Documentation/devicetree/bindings/input/stmpe-keypad.txt
deleted file mode 100644
index 12bb771d66d4..000000000000
--- a/Documentation/devicetree/bindings/input/stmpe-keypad.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-* STMPE Keypad
-
-Required properties:
- - compatible : "st,stmpe-keypad"
- - linux,keymap : See ./matrix-keymap.txt
-
-Optional properties:
- - debounce-interval : Debouncing interval time in milliseconds
- - st,scan-count : Scanning cycles elapsed before key data is updated
- - st,no-autorepeat : If specified device will not autorepeat
- - keypad,num-rows : See ./matrix-keymap.txt
- - keypad,num-columns : See ./matrix-keymap.txt
-
-Example:
-
- stmpe_keypad {
- compatible = "st,stmpe-keypad";
-
- debounce-interval = <64>;
- st,scan-count = <8>;
- st,no-autorepeat;
-
- linux,keymap = <0x205006b
- 0x4010074
- 0x3050072
- 0x1030004
- 0x502006a
- 0x500000a
- 0x5008b
- 0x706001c
- 0x405000b
- 0x6070003
- 0x3040067
- 0x303006c
- 0x60400e7
- 0x602009e
- 0x4020073
- 0x5050002
- 0x4030069
- 0x3020008>;
- };
diff --git a/Documentation/devicetree/bindings/input/syna,rmi4.yaml b/Documentation/devicetree/bindings/input/syna,rmi4.yaml
new file mode 100644
index 000000000000..f369385ffaf0
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/syna,rmi4.yaml
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/syna,rmi4.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synaptics RMI4 compliant devices
+
+maintainers:
+ - Jason A. Donenfeld <Jason@zx2c4.com>
+ - Matthias Schiffer <matthias.schiffer@ew.tq-group.com
+ - Vincent Huang <vincent.huang@tw.synaptics.com>
+
+description: |
+ The Synaptics RMI4 (Register Mapped Interface 4) core is able to support RMI4
+ devices using different transports (I2C, SPI) and different functions (e.g.
+ Function 1, 2D sensors using Function 11 or 12).
+
+properties:
+ compatible:
+ enum:
+ - syna,rmi4-i2c
+ - syna,rmi4-spi
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+ description: Active low signal
+
+ spi-cpha: true
+ spi-cpol: true
+
+ syna,reset-delay-ms:
+ description:
+ Delay to wait after resetting the device.
+
+ syna,startup-delay-ms:
+ description:
+ Delay to wait after powering on the device.
+
+ vdd-supply: true
+ vio-supply: true
+
+ rmi4-f01@1:
+ type: object
+ additionalProperties: false
+ description:
+ Function 1
+
+ properties:
+ reg:
+ maxItems: 1
+
+ syna,nosleep-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+ description:
+ If set the device will run at full power without sleeping. nosleep
+ has 3 modes, 0 will not change the default setting, 1 will disable
+ nosleep (allow sleeping), and 2 will enable nosleep (disabling
+ sleep).
+
+ syna,wakeup-threshold:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Defines the amplitude of the disturbance to the background
+ capacitance that will cause the device to wake from dozing.
+
+ syna,doze-holdoff-ms:
+ description:
+ The delay to wait after the last finger lift and the first doze
+ cycle.
+
+ syna,doze-interval-ms:
+ description:
+ The time period that the device sleeps between finger activity.
+
+ required:
+ - reg
+
+ rmi4-f1a@1a:
+ type: object
+ additionalProperties: false
+ $ref: input.yaml#
+ description:
+ RMI4 Function 1A is for capacitive keys.
+
+ properties:
+ reg:
+ maxItems: 1
+
+ linux,keycodes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - reg
+
+patternProperties:
+ "^rmi4-f1[12]@1[12]$":
+ type: object
+ unevaluatedProperties: false
+ $ref: /schemas/input/touchscreen/touchscreen.yaml#
+ description:
+ RMI4 Function 11 and Function 12 are for 2D touch position sensing.
+
+ properties:
+ reg:
+ maxItems: 1
+
+ syna,clip-x-low:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Minimum value for X.
+
+ syna,clip-y-low:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Minimum value for Y.
+
+ syna,clip-x-high:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Maximum value for X.
+
+ syna,clip-y-high:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Maximum value for Y.
+
+ syna,offset-x:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Add an offset to X.
+
+ syna,offset-y:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Add an offset to Y.
+
+ syna,delta-x-threshold:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Minimum distance on the X axis required to generate an interrupt in
+ reduced reporting mode.
+
+ syna,delta-y-threshold:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Minimum distance on the Y axis required to generate an interrupt in
+ reduced reporting mode.
+
+ syna,sensor-type:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2]
+ description: |
+ Sensor type: 1 for touchscreen 2 for touchpad.
+
+ syna,disable-report-mask:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Mask for disabling posiiton reporting. Used to disable reporing
+ absolute position data.
+
+ syna,rezero-wait-ms:
+ description:
+ Time to wait after issuing a rezero command.
+
+ required:
+ - reg
+
+ "^rmi4-f[0-9a-f]+@[0-9a-f]+$":
+ type: object
+ additionalProperties: true
+
+ description:
+ Other functions, not documented yet.
+
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: syna,rmi4-i2c
+ then:
+ properties:
+ spi-rx-delay-us: false
+ spi-tx-delay-us: false
+ else:
+ properties:
+ syna,reset-delay-ms: false
+ syna,startup-delay-ms: false
+
+examples:
+ - |
+ #include <dt-bindings/input/linux-event-codes.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@20 {
+ compatible = "syna,rmi4-i2c";
+ reg = <0x20>;
+ interrupt-parent = <&gpx1>;
+ interrupts = <6 IRQ_TYPE_EDGE_FALLING>;
+
+ syna,startup-delay-ms = <100>;
+ vdd-supply = <&tsp_vdd>;
+ vio-supply = <&ldo32_reg>;
+
+ pinctrl-0 = <&touch_irq>;
+ pinctrl-names = "default";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ rmi4-f01@1 {
+ reg = <0x1>;
+ syna,nosleep-mode = <1>;
+ };
+
+ rmi4-f12@12 {
+ reg = <0x12>;
+ syna,sensor-type = <1>;
+ };
+
+ rmi4-f1a@1a {
+ reg = <0x1a>;
+ linux,keycodes = <KEY_BACK KEY_HOME KEY_MENU>;
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@0 {
+ compatible = "syna,rmi4-spi";
+ reg = <0x0>;
+ interrupt-parent = <&gpx1>;
+ interrupts = <6 IRQ_TYPE_EDGE_FALLING>;
+
+ spi-max-frequency = <4000000>;
+ spi-rx-delay-us = <30>;
+ spi-cpha;
+ spi-cpol;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ rmi4-f01@1 {
+ reg = <0x1>;
+ syna,nosleep-mode = <1>;
+ };
+
+ rmi4-f11@11 {
+ reg = <0x11>;
+ touchscreen-inverted-y;
+ syna,sensor-type = <2>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/tca8418_keypad.txt b/Documentation/devicetree/bindings/input/tca8418_keypad.txt
deleted file mode 100644
index 255185009167..000000000000
--- a/Documentation/devicetree/bindings/input/tca8418_keypad.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-This binding is based on the matrix-keymap binding with the following
-changes:
-
-keypad,num-rows and keypad,num-columns are required.
-
-Required properties:
-- compatible: "ti,tca8418"
-- reg: the I2C address
-- interrupts: IRQ line number, should trigger on falling edge
-- linux,keymap: Keys definitions, see keypad-matrix.
diff --git a/Documentation/devicetree/bindings/input/ti,drv260x.txt b/Documentation/devicetree/bindings/input/ti,drv260x.txt
deleted file mode 100644
index 4c5312eaaa85..000000000000
--- a/Documentation/devicetree/bindings/input/ti,drv260x.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-* Texas Instruments - drv260x Haptics driver family
-
-Required properties:
- - compatible - One of:
- "ti,drv2604" - DRV2604
- "ti,drv2605" - DRV2605
- "ti,drv2605l" - DRV2605L
- - reg - I2C slave address
- - vbat-supply - Required supply regulator
- - mode - Power up mode of the chip (defined in include/dt-bindings/input/ti-drv260x.h)
- DRV260X_LRA_MODE - Linear Resonance Actuator mode (Piezoelectric)
- DRV260X_LRA_NO_CAL_MODE - This is a LRA Mode but there is no calibration
- sequence during init. And the device is configured for real
- time playback mode (RTP mode).
- DRV260X_ERM_MODE - Eccentric Rotating Mass mode (Rotary vibrator)
- - library-sel - These are ROM based waveforms pre-programmed into the IC.
- This should be set to set the library to use at power up.
- (defined in include/dt-bindings/input/ti-drv260x.h)
- DRV260X_LIB_EMPTY - Do not use a pre-programmed library
- DRV260X_ERM_LIB_A - Pre-programmed Library
- DRV260X_ERM_LIB_B - Pre-programmed Library
- DRV260X_ERM_LIB_C - Pre-programmed Library
- DRV260X_ERM_LIB_D - Pre-programmed Library
- DRV260X_ERM_LIB_E - Pre-programmed Library
- DRV260X_ERM_LIB_F - Pre-programmed Library
- DRV260X_LIB_LRA - Pre-programmed LRA Library
-
-Optional properties:
- - enable-gpio - gpio pin to enable/disable the device.
- - vib-rated-mv - The rated voltage of the actuator in millivolts.
- If this is not set then the value will be defaulted to
- 3.2 v.
- - vib-overdrive-mv - The overdrive voltage of the actuator in millivolts.
- If this is not set then the value will be defaulted to
- 3.2 v.
-Example:
-
-haptics: haptics@5a {
- compatible = "ti,drv2605l";
- reg = <0x5a>;
- vbat-supply = <&vbat>;
- enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>;
- mode = <DRV260X_LRA_MODE>;
- library-sel = <DRV260X_LIB_LRA>;
- vib-rated-mv = <3200>;
- vib-overdrive-mv = <3200>;
-}
-
-For more product information please see the link below:
-http://www.ti.com/product/drv2605
diff --git a/Documentation/devicetree/bindings/input/ti,drv260x.yaml b/Documentation/devicetree/bindings/input/ti,drv260x.yaml
new file mode 100644
index 000000000000..c6245c5b9e2e
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ti,drv260x.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ti,drv260x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments - drv260x Haptics driver family
+
+maintainers:
+ - Andrew Davis <afd@ti.com>
+
+properties:
+ compatible:
+ enum:
+ - ti,drv2604
+ - ti,drv2605
+ - ti,drv2605l
+
+ reg:
+ maxItems: 1
+
+ vbat-supply:
+ description: Power supply to the haptic motor
+
+ # TODO: Deprecate 'mode' in favor of differently named property
+ mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Power up mode of the chip
+ (defined in include/dt-bindings/input/ti-drv260x.h)
+
+ DRV260X_LRA_MODE
+ Linear Resonance Actuator mode (Piezoelectric)
+
+ DRV260X_LRA_NO_CAL_MODE
+ This is a LRA Mode but there is no calibration sequence during init.
+ And the device is configured for real time playback mode (RTP mode).
+
+ DRV260X_ERM_MODE
+ Eccentric Rotating Mass mode (Rotary vibrator)
+ enum: [ 0, 1, 2 ]
+
+ library-sel:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ These are ROM based waveforms pre-programmed into the IC.
+ This should be set to set the library to use at power up.
+ (defined in include/dt-bindings/input/ti-drv260x.h)
+
+ DRV260X_LIB_EMPTY - Do not use a pre-programmed library
+ DRV260X_ERM_LIB_A - Pre-programmed Library
+ DRV260X_ERM_LIB_B - Pre-programmed Library
+ DRV260X_ERM_LIB_C - Pre-programmed Library
+ DRV260X_ERM_LIB_D - Pre-programmed Library
+ DRV260X_ERM_LIB_E - Pre-programmed Library
+ DRV260X_ERM_LIB_F - Pre-programmed Library
+ DRV260X_LIB_LRA - Pre-programmed LRA Library
+ enum: [ 0, 1, 2, 3, 4, 5, 6, 7 ]
+
+ enable-gpio:
+ maxItems: 1
+ deprecated: true
+
+ enable-gpios:
+ maxItems: 1
+
+ vib-rated-mv:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ The rated voltage of the actuator in millivolts.
+ If this is not set then the value will be defaulted to 3200 mV.
+ default: 3200
+
+ vib-overdrive-mv:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ The overdrive voltage of the actuator in millivolts.
+ If this is not set then the value will be defaulted to 3200 mV.
+ default: 3200
+
+required:
+ - compatible
+ - reg
+ - enable-gpios
+ - mode
+ - library-sel
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/ti-drv260x.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ haptics@5a {
+ compatible = "ti,drv2605l";
+ reg = <0x5a>;
+ vbat-supply = <&vbat>;
+ enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
+ mode = <DRV260X_LRA_MODE>;
+ library-sel = <DRV260X_LIB_LRA>;
+ vib-rated-mv = <3200>;
+ vib-overdrive-mv = <3200>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/ti,drv2665.txt b/Documentation/devicetree/bindings/input/ti,drv2665.txt
deleted file mode 100644
index 1ba97ac04305..000000000000
--- a/Documentation/devicetree/bindings/input/ti,drv2665.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-* Texas Instruments - drv2665 Haptics driver
-
-Required properties:
- - compatible - "ti,drv2665" - DRV2665
- - reg - I2C slave address
- - vbat-supply - Required supply regulator
-
-Example:
-
-haptics: haptics@59 {
- compatible = "ti,drv2665";
- reg = <0x59>;
- vbat-supply = <&vbat>;
-};
-
-For more product information please see the link below:
-http://www.ti.com/product/drv2665
diff --git a/Documentation/devicetree/bindings/input/ti,drv2667.txt b/Documentation/devicetree/bindings/input/ti,drv2667.txt
deleted file mode 100644
index 996382cf994a..000000000000
--- a/Documentation/devicetree/bindings/input/ti,drv2667.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-* Texas Instruments - drv2667 Haptics driver
-
-Required properties:
- - compatible - "ti,drv2667" - DRV2667
- - reg - I2C slave address
- - vbat-supply - Required supply regulator
-
-Example:
-
-haptics: haptics@59 {
- compatible = "ti,drv2667";
- reg = <0x59>;
- vbat-supply = <&vbat>;
-};
-
-For more product information please see the link below:
-http://www.ti.com/product/drv2667
diff --git a/Documentation/devicetree/bindings/input/ti,drv266x.yaml b/Documentation/devicetree/bindings/input/ti,drv266x.yaml
new file mode 100644
index 000000000000..1bce389d0e5c
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ti,drv266x.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ti,drv266x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments - drv266x Haptics driver
+
+description: |
+ Product Page:
+ http://www.ti.com/product/drv2665
+ http://www.ti.com/product/drv2667
+
+maintainers:
+ - Anshul Dalal <anshulusr@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - ti,drv2665
+ - ti,drv2667
+
+ reg:
+ maxItems: 1
+
+ vbat-supply:
+ description: Required supply regulator
+
+required:
+ - compatible
+ - reg
+ - vbat-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ haptics@59 {
+ compatible = "ti,drv2667";
+ reg = <0x59>;
+ vbat-supply = <&vbat>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/ti,nspire-keypad.txt b/Documentation/devicetree/bindings/input/ti,nspire-keypad.txt
deleted file mode 100644
index 513d94d6e899..000000000000
--- a/Documentation/devicetree/bindings/input/ti,nspire-keypad.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-TI-NSPIRE Keypad
-
-Required properties:
-- compatible: Compatible property value should be "ti,nspire-keypad".
-
-- reg: Physical base address of the peripheral and length of memory mapped
- region.
-
-- interrupts: The interrupt number for the peripheral.
-
-- scan-interval: How often to scan in us. Based on a APB speed of 33MHz, the
- maximum and minimum delay time is ~2000us and ~500us respectively
-
-- row-delay: How long to wait before scanning each row.
-
-- clocks: The clock this peripheral is attached to.
-
-- linux,keymap: The keymap to use
- (see Documentation/devicetree/bindings/input/matrix-keymap.txt)
-
-Optional properties:
-- active-low: Specify that the keypad is active low (i.e. logical low signifies
- a key press).
-
-Example:
-
-input {
- compatible = "ti,nspire-keypad";
- reg = <0x900E0000 0x1000>;
- interrupts = <16>;
-
- scan-interval = <1000>;
- row-delay = <200>;
-
- clocks = <&apb_pclk>;
-
- linux,keymap = <
- 0x0000001c 0x0001001c 0x00040039
- 0x0005002c 0x00060015 0x0007000b
- 0x0008000f 0x0100002d 0x01010011
- 0x0102002f 0x01030004 0x01040016
- 0x01050014 0x0106001f 0x01070002
- 0x010a006a 0x02000013 0x02010010
- 0x02020019 0x02030007 0x02040018
- 0x02050031 0x02060032 0x02070005
- 0x02080028 0x0209006c 0x03000026
- 0x03010025 0x03020024 0x0303000a
- 0x03040017 0x03050023 0x03060022
- 0x03070008 0x03080035 0x03090069
- 0x04000021 0x04010012 0x04020020
- 0x0404002e 0x04050030 0x0406001e
- 0x0407000d 0x04080037 0x04090067
- 0x05010038 0x0502000c 0x0503001b
- 0x05040034 0x0505001a 0x05060006
- 0x05080027 0x0509000e 0x050a006f
- 0x0600002b 0x0602004e 0x06030068
- 0x06040003 0x0605006d 0x06060009
- 0x06070001 0x0609000f 0x0708002a
- 0x0709001d 0x070a0033 >;
-};
diff --git a/Documentation/devicetree/bindings/input/ti,nspire-keypad.yaml b/Documentation/devicetree/bindings/input/ti,nspire-keypad.yaml
new file mode 100644
index 000000000000..ed3cfff13add
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ti,nspire-keypad.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ti,nspire-keypad.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI-NSPIRE Keypad
+
+maintainers:
+ - Andrew Davis <afd@ti.com>
+
+allOf:
+ - $ref: input.yaml#
+ - $ref: matrix-keymap.yaml#
+
+properties:
+ compatible:
+ enum:
+ - ti,nspire-keypad
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ scan-interval:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: How often to scan in us. Based on a APB speed of 33MHz, the
+ maximum and minimum delay time is ~2000us and ~500us respectively
+
+ row-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: How long to wait between scanning each row in us.
+
+ active-low:
+ description: Specify that the keypad is active low.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - scan-interval
+ - row-delay
+ - linux,keymap
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ keypad@900e0000 {
+ compatible = "ti,nspire-keypad";
+ reg = <0x900e0000 0x1000>;
+ interrupts = <16>;
+
+ clocks = <&apb_pclk>;
+
+ scan-interval = <1000>;
+ row-delay = <200>;
+
+ linux,keymap = <
+ MATRIX_KEY(0, 0, KEY_ENTER)
+ MATRIX_KEY(0, 1, KEY_ENTER)
+ MATRIX_KEY(0, 4, KEY_SPACE)
+ MATRIX_KEY(0, 5, KEY_Z)
+ MATRIX_KEY(0, 6, KEY_Y)
+ MATRIX_KEY(0, 7, KEY_0)
+ >;
+ };
diff --git a/Documentation/devicetree/bindings/input/ti,tca8418.yaml b/Documentation/devicetree/bindings/input/ti,tca8418.yaml
new file mode 100644
index 000000000000..624a1830d0b0
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/ti,tca8418.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/ti,tca8418.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI TCA8418 I2C/SMBus keypad scanner
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - ti,tca8418
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+allOf:
+ - $ref: matrix-keymap.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ keypad@34 {
+ compatible = "ti,tca8418";
+ reg = <0x34>;
+ interrupt-parent = <&gpio5>;
+ interrupts = <11 IRQ_TYPE_EDGE_FALLING>;
+ keypad,num-rows = <4>;
+ keypad,num-columns = <4>;
+ linux,keymap = < MATRIX_KEY(0x00, 0x01, BTN_0)
+ MATRIX_KEY(0x00, 0x00, BTN_1)
+ MATRIX_KEY(0x01, 0x01, BTN_2)
+ MATRIX_KEY(0x01, 0x00, BTN_3)
+ MATRIX_KEY(0x02, 0x00, BTN_4)
+ MATRIX_KEY(0x00, 0x03, BTN_5)
+ MATRIX_KEY(0x00, 0x02, BTN_6)
+ MATRIX_KEY(0x01, 0x03, BTN_7)
+ MATRIX_KEY(0x01, 0x02, BTN_8)
+ MATRIX_KEY(0x02, 0x02, BTN_9)
+ >;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt b/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt
deleted file mode 100644
index afa38dc069f0..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-* Analog Devices AD7879(-1)/AD7889(-1) touchscreen interface (SPI/I2C)
-
-Required properties:
-- compatible : for SPI slave, use "adi,ad7879"
- for I2C slave, use "adi,ad7879-1"
-- reg : SPI chipselect/I2C slave address
- See spi-bus.txt for more SPI slave properties
-- interrupts : touch controller interrupt
-- touchscreen-max-pressure : maximum reported pressure
-- adi,resistance-plate-x : total resistance of X-plate (for pressure
- calculation)
-Optional properties:
-- touchscreen-swapped-x-y : X and Y axis are swapped (boolean)
-- adi,first-conversion-delay : 0-12: In 128us steps (starting with 128us)
- 13 : 2.560ms
- 14 : 3.584ms
- 15 : 4.096ms
- This property has to be a '/bits/ 8' value
-- adi,acquisition-time : 0: 2us
- 1: 4us
- 2: 8us
- 3: 16us
- This property has to be a '/bits/ 8' value
-- adi,median-filter-size : 0: disabled
- 1: 4 measurements
- 2: 8 measurements
- 3: 16 measurements
- This property has to be a '/bits/ 8' value
-- adi,averaging : 0: 2 middle values (1 if median disabled)
- 1: 4 middle values
- 2: 8 middle values
- 3: 16 values
- This property has to be a '/bits/ 8' value
-- adi,conversion-interval: : 0 : convert one time only
- 1-255: 515us + val * 35us (up to 9.440ms)
- This property has to be a '/bits/ 8' value
-- gpio-controller : Switch AUX/VBAT/GPIO pin to GPIO mode
-
-Example:
-
- touchscreen0@2c {
- compatible = "adi,ad7879-1";
- reg = <0x2c>;
- interrupt-parent = <&gpio1>;
- interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
- touchscreen-max-pressure = <4096>;
- adi,resistance-plate-x = <120>;
- adi,first-conversion-delay = /bits/ 8 <3>;
- adi,acquisition-time = /bits/ 8 <1>;
- adi,median-filter-size = /bits/ 8 <2>;
- adi,averaging = /bits/ 8 <1>;
- adi,conversion-interval = /bits/ 8 <255>;
- };
-
- touchscreen1@1 {
- compatible = "adi,ad7879";
- spi-max-frequency = <5000000>;
- reg = <1>;
- spi-cpol;
- spi-cpha;
- gpio-controller;
- interrupt-parent = <&gpio1>;
- interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
- touchscreen-max-pressure = <4096>;
- adi,resistance-plate-x = <120>;
- adi,first-conversion-delay = /bits/ 8 <3>;
- adi,acquisition-time = /bits/ 8 <1>;
- adi,median-filter-size = /bits/ 8 <2>;
- adi,averaging = /bits/ 8 <1>;
- adi,conversion-interval = /bits/ 8 <255>;
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/adi,ad7879.yaml b/Documentation/devicetree/bindings/input/touchscreen/adi,ad7879.yaml
new file mode 100644
index 000000000000..caa5fa3cc3f1
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/adi,ad7879.yaml
@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/adi,ad7879.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7879(-1)/AD7889(-1) touchscreen interface (SPI/I2C)
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ description: |
+ for SPI slave, use "adi,ad7879"
+ for I2C slave, use "adi,ad7879-1"
+ enum:
+ - adi,ad7879
+ - adi,ad7879-1
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ touchscreen-max-pressure:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: maximum reported pressure
+
+ adi,resistance-plate-x:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: total resistance of X-plate (for pressure calculation)
+
+ touchscreen-swapped-x-y:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: X and Y axis are swapped (boolean)
+
+ adi,first-conversion-delay:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ default: 0
+ minimum: 0
+ maximum: 15
+ description: |
+ 0-12: In 128us steps (starting with 128us)
+ 13 : 2.560ms
+ 14 : 3.584ms
+ 15 : 4.096ms
+ This property has to be a '/bits/ 8' value
+
+ adi,acquisition-time:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ default: 0
+ enum: [0, 1, 2, 3]
+ description: |
+ 0: 2us
+ 1: 4us
+ 2: 8us
+ 3: 16us
+ This property has to be a '/bits/ 8' value
+
+ adi,median-filter-size:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ default: 0
+ enum: [0, 1, 2, 3]
+ description: |
+ 0: disabled
+ 1: 4 measurements
+ 2: 8 measurements
+ 3: 16 measurements
+ This property has to be a '/bits/ 8' value
+
+ adi,averaging:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ default: 0
+ enum: [0, 1, 2, 3]
+ description: |
+ 0: 2 middle values (1 if median disabled)
+ 1: 4 middle values
+ 2: 8 middle values
+ 3: 16 values
+ This property has to be a '/bits/ 8' value
+
+ adi,conversion-interval:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ default: 0
+ description: |
+ 0 : convert one time only
+ 1-255: 515us + val * 35us (up to 9.440ms)
+ This property has to be a '/bits/ 8' value
+
+ gpio-controller: true
+
+ "#gpio-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen0@2c {
+ compatible = "adi,ad7879-1";
+ reg = <0x2c>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
+ touchscreen-max-pressure = <4096>;
+ adi,resistance-plate-x = <120>;
+ adi,first-conversion-delay = /bits/ 8 <3>;
+ adi,acquisition-time = /bits/ 8 <1>;
+ adi,median-filter-size = /bits/ 8 <2>;
+ adi,averaging = /bits/ 8 <1>;
+ adi,conversion-interval = /bits/ 8 <255>;
+ };
+ };
+
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen1@1 {
+ compatible = "adi,ad7879";
+ reg = <1>;
+ spi-max-frequency = <5000000>;
+ gpio-controller;
+ #gpio-cells = <1>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
+ touchscreen-max-pressure = <4096>;
+ adi,resistance-plate-x = <120>;
+ adi,first-conversion-delay = /bits/ 8 <3>;
+ adi,acquisition-time = /bits/ 8 <1>;
+ adi,median-filter-size = /bits/ 8 <2>;
+ adi,averaging = /bits/ 8 <1>;
+ adi,conversion-interval = /bits/ 8 <255>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt b/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt
deleted file mode 100644
index 81f6bda97d3c..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt
+++ /dev/null
@@ -1,106 +0,0 @@
-Device tree bindings for TI's ADS7843, ADS7845, ADS7846, ADS7873, TSC2046
-SPI driven touch screen controllers.
-
-The node for this driver must be a child node of a SPI controller, hence
-all mandatory properties described in
-
- Documentation/devicetree/bindings/spi/spi-bus.txt
-
-must be specified.
-
-Additional required properties:
-
- compatible Must be one of the following, depending on the
- model:
- "ti,tsc2046"
- "ti,ads7843"
- "ti,ads7845"
- "ti,ads7846"
- "ti,ads7873"
-
- interrupts An interrupt node describing the IRQ line the chip's
- !PENIRQ pin is connected to.
- vcc-supply A regulator node for the supply voltage.
-
-
-Optional properties:
-
- ti,vref-delay-usecs vref supply delay in usecs, 0 for
- external vref (u16).
- ti,vref-mv The VREF voltage, in millivolts (u16).
- Set to 0 to use internal references
- (ADS7846).
- ti,keep-vref-on set to keep vref on for differential
- measurements as well
- ti,settle-delay-usec Settling time of the analog signals;
- a function of Vcc and the capacitance
- on the X/Y drivers. If set to non-zero,
- two samples are taken with settle_delay
- us apart, and the second one is used.
- ~150 uSec with 0.01uF caps (u16).
- ti,penirq-recheck-delay-usecs If set to non-zero, after samples are
- taken this delay is applied and penirq
- is rechecked, to help avoid false
- events. This value is affected by the
- material used to build the touch layer
- (u16).
- ti,x-plate-ohms Resistance of the X-plate,
- in Ohms (u16).
- ti,y-plate-ohms Resistance of the Y-plate,
- in Ohms (u16).
- ti,x-min Minimum value on the X axis (u16).
- ti,y-min Minimum value on the Y axis (u16).
- ti,debounce-tol Tolerance used for filtering (u16).
- ti,debounce-rep Additional consecutive good readings
- required after the first two (u16).
- ti,pendown-gpio-debounce Platform specific debounce time for the
- pendown-gpio (u32).
- pendown-gpio GPIO handle describing the pin the !PENIRQ
- line is connected to.
- wakeup-source use any event on touchscreen as wakeup event.
- (Legacy property support: "linux,wakeup")
- touchscreen-size-x General touchscreen binding, see [1].
- touchscreen-size-y General touchscreen binding, see [1].
- touchscreen-max-pressure General touchscreen binding, see [1].
- touchscreen-min-pressure General touchscreen binding, see [1].
- touchscreen-average-samples General touchscreen binding, see [1].
- touchscreen-inverted-x General touchscreen binding, see [1].
- touchscreen-inverted-y General touchscreen binding, see [1].
- touchscreen-swapped-x-y General touchscreen binding, see [1].
-
-[1] All general touchscreen properties are described in
- Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt.
-
-Deprecated properties:
-
- ti,swap-xy swap x and y axis
- ti,x-max Maximum value on the X axis (u16).
- ti,y-max Maximum value on the Y axis (u16).
- ti,pressure-min Minimum reported pressure value
- (threshold) - u16.
- ti,pressure-max Maximum reported pressure value (u16).
- ti,debounce-max Max number of additional readings per
- sample (u16).
-
-Example for a TSC2046 chip connected to an McSPI controller of an OMAP SoC::
-
- spi_controller {
- tsc2046@0 {
- reg = <0>; /* CS0 */
- compatible = "ti,tsc2046";
- interrupt-parent = <&gpio1>;
- interrupts = <8 0>; /* BOOT6 / GPIO 8 */
- spi-max-frequency = <1000000>;
- pendown-gpio = <&gpio1 8 0>;
- vcc-supply = <&reg_vcc3>;
-
- ti,x-min = /bits/ 16 <0>;
- ti,x-max = /bits/ 16 <8000>;
- ti,y-min = /bits/ 16 <0>;
- ti,y-max = /bits/ 16 <4800>;
- ti,x-plate-ohms = /bits/ 16 <40>;
- ti,pressure-max = /bits/ 16 <255>;
-
- wakeup-source;
- };
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml b/Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml
new file mode 100644
index 000000000000..402ca6bffd34
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/apple,z2-multitouch.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple touchscreens attached using the Z2 protocol
+
+maintainers:
+ - Sasha Finkelstein <fnkl.kernel@gmail.com>
+
+description: A series of touschscreen controllers used in Apple products
+
+allOf:
+ - $ref: touchscreen.yaml#
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - apple,j293-touchbar
+ - apple,j493-touchbar
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ firmware-name:
+ maxItems: 1
+
+ apple,z2-cal-blob:
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+ maxItems: 4096
+ description:
+ Calibration blob supplied by the bootloader
+
+required:
+ - compatible
+ - interrupts
+ - reset-gpios
+ - firmware-name
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@0 {
+ compatible = "apple,j293-touchbar";
+ reg = <0>;
+ spi-max-frequency = <11500000>;
+ reset-gpios = <&pinctrl_ap 139 GPIO_ACTIVE_LOW>;
+ interrupts-extended = <&pinctrl_ap 194 IRQ_TYPE_EDGE_FALLING>;
+ firmware-name = "apple/dfrmtfw-j293.bin";
+ touchscreen-size-x = <23045>;
+ touchscreen-size-y = <640>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/auo_pixcir_ts.txt b/Documentation/devicetree/bindings/input/touchscreen/auo_pixcir_ts.txt
index f40f21c642b9..b8db975e9f77 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/auo_pixcir_ts.txt
+++ b/Documentation/devicetree/bindings/input/touchscreen/auo_pixcir_ts.txt
@@ -17,10 +17,10 @@ Example:
auo_pixcir_ts@5c {
compatible = "auo,auo_pixcir_ts";
reg = <0x5c>;
- interrupts = <2 0>;
+ interrupts = <2 IRQ_TYPE_LEVEL_HIGH>;
- gpios = <&gpf 2 0 2>, /* INT */
- <&gpf 5 1 0>; /* RST */
+ gpios = <&gpf 2 0 GPIO_LEVEL_HIGH>, /* INT */
+ <&gpf 5 1 GPIO_LEVEL_LOW>; /* RST */
x-size = <800>;
y-size = <600>;
diff --git a/Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml b/Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml
new file mode 100644
index 000000000000..e4dbbafb3779
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/azoteq,iqs7211.yaml
@@ -0,0 +1,769 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/azoteq,iqs7211.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Azoteq IQS7210A/7211A/E Trackpad/Touchscreen Controller
+
+maintainers:
+ - Jeff LaBundy <jeff@labundy.com>
+
+description: |
+ The Azoteq IQS7210A, IQS7211A and IQS7211E trackpad and touchscreen control-
+ lers employ projected-capacitance sensing and can track two contacts.
+
+ Link to datasheets: https://www.azoteq.com/
+
+properties:
+ compatible:
+ enum:
+ - azoteq,iqs7210a
+ - azoteq,iqs7211a
+ - azoteq,iqs7211e
+
+ reg:
+ maxItems: 1
+
+ irq-gpios:
+ maxItems: 1
+ description:
+ Specifies the GPIO connected to the device's active-low RDY output. The
+ pin doubles as the IQS7211E's active-low MCLR input, in which case this
+ GPIO must be configured as open-drain.
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ Specifies the GPIO connected to the device's active-low MCLR input. The
+ device is temporarily held in hardware reset prior to initialization if
+ this property is present.
+
+ azoteq,forced-comms:
+ type: boolean
+ description:
+ Enables forced communication; to be used with host adapters that cannot
+ tolerate clock stretching.
+
+ azoteq,forced-comms-default:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description:
+ Indicates if the device's OTP memory enables (1) or disables (0) forced
+ communication by default. Specifying this property can expedite startup
+ time if the default value is known.
+
+ If this property is not specified, communication is not initiated until
+ the device asserts its RDY pin shortly after exiting hardware reset. At
+ that point, forced communication is either enabled or disabled based on
+ the presence or absence of the 'azoteq,forced-comms' property.
+
+ azoteq,rate-active-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the report rate (in ms) during active mode.
+
+ azoteq,rate-touch-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the report rate (in ms) during idle-touch mode.
+
+ azoteq,rate-idle-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the report rate (in ms) during idle mode.
+
+ azoteq,rate-lp1-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the report rate (in ms) during low-power mode 1.
+
+ azoteq,rate-lp2-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the report rate (in ms) during low-power mode 2.
+
+ azoteq,timeout-active-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 65535000
+ description:
+ Specifies the length of time (in ms) to wait for an event before moving
+ from active mode to idle or idle-touch modes.
+
+ azoteq,timeout-touch-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 65535000
+ description:
+ Specifies the length of time (in ms) to wait for an event before moving
+ from idle-touch mode to idle mode.
+
+ azoteq,timeout-idle-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 65535000
+ description:
+ Specifies the length of time (in ms) to wait for an event before moving
+ from idle mode to low-power mode 1.
+
+ azoteq,timeout-lp1-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 65535000
+ description:
+ Specifies the length of time (in ms) to wait for an event before moving
+ from low-power mode 1 to low-power mode 2.
+
+ azoteq,timeout-lp2-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 60000
+ description:
+ Specifies the rate (in ms) at which the trackpad reference values
+ are updated during low-power modes 1 and 2.
+
+ azoteq,timeout-ati-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 60000
+ description:
+ Specifies the delay (in ms) before the automatic tuning implementation
+ (ATI) is retried in the event it fails to complete.
+
+ azoteq,timeout-comms-ms:
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the delay (in ms) before a communication window is closed.
+
+ azoteq,timeout-press-ms:
+ multipleOf: 1000
+ minimum: 0
+ maximum: 60000
+ description:
+ Specifies the length of time (in ms) to wait before automatically
+ releasing a press event. Specify zero to allow the press state to
+ persist indefinitely.
+
+ azoteq,fosc-freq:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description: |
+ Specifies the device's core clock frequency as follows:
+ 0: 14 MHz
+ 1: 18 MHz
+
+ azoteq,fosc-trim:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the device's core clock frequency trim.
+
+ azoteq,num-contacts:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 2
+ default: 0
+ description: Specifies the number of contacts reported by the device.
+
+ azoteq,contact-split:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the contact (finger) split factor.
+
+ azoteq,trim-x:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the horizontal trim width.
+
+ azoteq,trim-y:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the vertical trim height.
+
+ trackpad:
+ type: object
+ description: Represents all channels associated with the trackpad.
+
+ properties:
+ azoteq,rx-enable:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+ items:
+ minimum: 0
+ maximum: 7
+ description:
+ Specifies the order of the CRx pin(s) associated with the trackpad.
+
+ azoteq,tx-enable:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 12
+ items:
+ minimum: 0
+ maximum: 11
+ description:
+ Specifies the order of the CTx pin(s) associated with the trackpad.
+
+ azoteq,channel-select:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 36
+ items:
+ minimum: 0
+ maximum: 255
+ description: |
+ Specifies the channels mapped to each cycle in the following order:
+ Cycle 0, slot 0
+ Cycle 0, slot 1
+ Cycle 1, slot 0
+ Cycle 1, slot 1
+ ...and so on. Specify 255 to disable a given slot.
+
+ azoteq,ati-frac-div-fine:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the trackpad's ATI fine fractional divider.
+
+ azoteq,ati-frac-mult-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the trackpad's ATI coarse fractional multiplier.
+
+ azoteq,ati-frac-div-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the trackpad's ATI coarse fractional divider.
+
+ azoteq,ati-comp-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the trackpad's ATI compensation divider.
+
+ azoteq,ati-target:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description: Specifies the trackpad's ATI target.
+
+ azoteq,touch-enter:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's touch entrance factor.
+
+ azoteq,touch-exit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's touch exit factor.
+
+ azoteq,thresh:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's stationary touch threshold.
+
+ azoteq,conv-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's conversion period.
+
+ azoteq,conv-frac:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the trackpad's conversion frequency fraction.
+
+ patternProperties:
+ "^event-(tap(-double|-triple)?|hold|palm|swipe-(x|y)-(pos|neg)(-hold)?)$":
+ type: object
+ $ref: ../input.yaml#
+ description:
+ Represents a gesture event reported by the trackpad. In the case of
+ axial gestures, the duration or distance specified in one direction
+ applies to both directions along the same axis.
+
+ properties:
+ linux,code: true
+
+ azoteq,gesture-max-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the maximum duration of tap/swipe gestures.
+
+ azoteq,gesture-mid-ms:
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the maximum duration between subsequent tap gestures
+ (IQS7211E only).
+
+ azoteq,gesture-min-ms:
+ minimum: 0
+ maximum: 65535
+ description: Specifies the minimum duration of hold gestures.
+
+ azoteq,gesture-dist:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the minimum (swipe) or maximum (tap and hold) distance
+ a finger may travel to be considered a gesture.
+
+ azoteq,gesture-dist-rep:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description:
+ Specifies the minimum distance a finger must travel to elicit a
+ repeated swipe gesture (IQS7211E only).
+
+ azoteq,gesture-angle:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 75
+ description:
+ Specifies the maximum angle (in degrees) a finger may travel to
+ be considered a swipe gesture.
+
+ azoteq,thresh:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 42
+ description: Specifies the palm gesture threshold (IQS7211E only).
+
+ additionalProperties: false
+
+ dependencies:
+ azoteq,rx-enable: ["azoteq,tx-enable"]
+ azoteq,tx-enable: ["azoteq,rx-enable"]
+ azoteq,channel-select: ["azoteq,rx-enable"]
+
+ additionalProperties: false
+
+ alp:
+ type: object
+ $ref: ../input.yaml#
+ description: Represents the alternate low-power channel (ALP).
+
+ properties:
+ azoteq,rx-enable:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+ items:
+ minimum: 0
+ maximum: 7
+ description:
+ Specifies the CRx pin(s) associated with the ALP in no particular
+ order.
+
+ azoteq,tx-enable:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 12
+ items:
+ minimum: 0
+ maximum: 11
+ description:
+ Specifies the CTx pin(s) associated with the ALP in no particular
+ order.
+
+ azoteq,ati-frac-div-fine:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the ALP's ATI fine fractional divider.
+
+ azoteq,ati-frac-mult-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the ALP's ATI coarse fractional multiplier.
+
+ azoteq,ati-frac-div-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the ALP's ATI coarse fractional divider.
+
+ azoteq,ati-comp-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the ALP's ATI compensation divider.
+
+ azoteq,ati-target:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description: Specifies the ALP's ATI target.
+
+ azoteq,ati-base:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ multipleOf: 8
+ minimum: 0
+ maximum: 255
+ description: Specifies the ALP's ATI base.
+
+ azoteq,ati-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description: |
+ Specifies the ALP's ATI mode as follows:
+ 0: Partial
+ 1: Full
+
+ azoteq,sense-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description: |
+ Specifies the ALP's sensing mode as follows:
+ 0: Self capacitive
+ 1: Mutual capacitive
+
+ azoteq,debounce-enter:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the ALP's debounce entrance factor.
+
+ azoteq,debounce-exit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the ALP's debounce exit factor.
+
+ azoteq,thresh:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description: Specifies the ALP's proximity or touch threshold.
+
+ azoteq,conv-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the ALP's conversion period.
+
+ azoteq,conv-frac:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the ALP's conversion frequency fraction.
+
+ linux,code: true
+
+ additionalProperties: false
+
+ button:
+ type: object
+ description: Represents the inductive or capacitive button.
+
+ properties:
+ azoteq,ati-frac-div-fine:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the button's ATI fine fractional divider.
+
+ azoteq,ati-frac-mult-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 15
+ description: Specifies the button's ATI coarse fractional multiplier.
+
+ azoteq,ati-frac-div-coarse:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the button's ATI coarse fractional divider.
+
+ azoteq,ati-comp-div:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 31
+ description: Specifies the button's ATI compensation divider.
+
+ azoteq,ati-target:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description: Specifies the button's ATI target.
+
+ azoteq,ati-base:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ multipleOf: 8
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's ATI base.
+
+ azoteq,ati-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description: |
+ Specifies the button's ATI mode as follows:
+ 0: Partial
+ 1: Full
+
+ azoteq,sense-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+ description: |
+ Specifies the button's sensing mode as follows:
+ 0: Self capacitive
+ 1: Mutual capacitive
+ 2: Inductive
+
+ azoteq,touch-enter:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's touch entrance factor.
+
+ azoteq,touch-exit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's touch exit factor.
+
+ azoteq,debounce-enter:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's debounce entrance factor.
+
+ azoteq,debounce-exit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's debounce exit factor.
+
+ azoteq,thresh:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 65535
+ description: Specifies the button's proximity threshold.
+
+ azoteq,conv-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's conversion period.
+
+ azoteq,conv-frac:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+ description: Specifies the button's conversion frequency fraction.
+
+ patternProperties:
+ "^event-(prox|touch)$":
+ type: object
+ $ref: ../input.yaml#
+ description:
+ Represents a proximity or touch event reported by the button.
+
+ properties:
+ linux,code: true
+
+ additionalProperties: false
+
+ additionalProperties: false
+
+ wakeup-source: true
+
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-swapped-x-y: true
+
+dependencies:
+ touchscreen-size-x: ["azoteq,num-contacts"]
+ touchscreen-size-y: ["azoteq,num-contacts"]
+ touchscreen-inverted-x: ["azoteq,num-contacts"]
+ touchscreen-inverted-y: ["azoteq,num-contacts"]
+ touchscreen-swapped-x-y: ["azoteq,num-contacts"]
+
+required:
+ - compatible
+ - reg
+ - irq-gpios
+
+additionalProperties: false
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: azoteq,iqs7210a
+
+ then:
+ properties:
+ alp:
+ properties:
+ azoteq,rx-enable:
+ maxItems: 4
+ items:
+ minimum: 4
+
+ else:
+ properties:
+ azoteq,timeout-press-ms: false
+
+ alp:
+ properties:
+ azoteq,ati-mode: false
+
+ button: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: azoteq,iqs7211e
+
+ then:
+ properties:
+ reset-gpios: false
+
+ trackpad:
+ properties:
+ azoteq,tx-enable:
+ maxItems: 13
+ items:
+ maximum: 12
+
+ alp:
+ properties:
+ azoteq,tx-enable:
+ maxItems: 13
+ items:
+ maximum: 12
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/input.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@56 {
+ compatible = "azoteq,iqs7210a";
+ reg = <0x56>;
+ irq-gpios = <&gpio 4 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&gpio 17 (GPIO_ACTIVE_LOW |
+ GPIO_PUSH_PULL)>;
+ azoteq,num-contacts = <2>;
+
+ trackpad {
+ azoteq,rx-enable = <6>, <5>, <4>, <3>, <2>;
+ azoteq,tx-enable = <1>, <7>, <8>, <9>, <10>;
+ };
+
+ button {
+ azoteq,sense-mode = <2>;
+ azoteq,touch-enter = <40>;
+ azoteq,touch-exit = <36>;
+
+ event-touch {
+ linux,code = <KEY_HOME>;
+ };
+ };
+
+ alp {
+ azoteq,sense-mode = <1>;
+ linux,code = <KEY_POWER>;
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/input.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@56 {
+ compatible = "azoteq,iqs7211e";
+ reg = <0x56>;
+ irq-gpios = <&gpio 4 (GPIO_ACTIVE_LOW |
+ GPIO_OPEN_DRAIN)>;
+
+ trackpad {
+ event-tap {
+ linux,code = <KEY_PLAYPAUSE>;
+ };
+
+ event-tap-double {
+ linux,code = <KEY_SHUFFLE>;
+ };
+
+ event-tap-triple {
+ linux,code = <KEY_AGAIN>;
+ };
+
+ event-hold {
+ linux,code = <KEY_STOP>;
+ };
+
+ event-palm {
+ linux,code = <KEY_EXIT>;
+ };
+
+ event-swipe-x-pos {
+ linux,code = <KEY_REWIND>;
+ };
+
+ event-swipe-x-pos-hold {
+ linux,code = <KEY_PREVIOUS>;
+ };
+
+ event-swipe-x-neg {
+ linux,code = <KEY_FASTFORWARD>;
+ };
+
+ event-swipe-x-neg-hold {
+ linux,code = <KEY_NEXT>;
+ };
+
+ event-swipe-y-pos {
+ linux,code = <KEY_VOLUMEUP>;
+ };
+
+ event-swipe-y-pos-hold {
+ linux,code = <KEY_MUTE>;
+ };
+
+ event-swipe-y-neg {
+ linux,code = <KEY_VOLUMEDOWN>;
+ };
+
+ event-swipe-y-neg-hold {
+ linux,code = <KEY_MUTE>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt b/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt
deleted file mode 100644
index da4c9d8b99b1..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-* Rohm BU21013 Touch Screen
-
-Required properties:
- - compatible : "rohm,bu21013_tp"
- - reg : I2C device address
- - reset-gpios : GPIO pin enabling (selecting) chip (CS)
- - interrupt-parent : the phandle for the gpio controller
- - interrupts : (gpio) interrupt to which the chip is connected
-
-Optional properties:
- - touch-gpios : GPIO pin registering a touch event
- - <supply_name>-supply : Phandle to a regulator supply
- - touchscreen-size-x : General touchscreen binding, see [1].
- - touchscreen-size-y : General touchscreen binding, see [1].
- - touchscreen-inverted-x : General touchscreen binding, see [1].
- - touchscreen-inverted-y : General touchscreen binding, see [1].
- - touchscreen-swapped-x-y : General touchscreen binding, see [1].
-
-[1] All general touchscreen properties are described in
- Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt.
-
-Deprecated properties:
- - rohm,touch-max-x : Maximum outward permitted limit in the X axis
- - rohm,touch-max-y : Maximum outward permitted limit in the Y axis
- - rohm,flip-x : Flip touch coordinates on the X axis
- - rohm,flip-y : Flip touch coordinates on the Y axis
-
-Example:
-
- i2c@80110000 {
- bu21013_tp@5c {
- compatible = "rohm,bu21013_tp";
- reg = <0x5c>;
- interrupt-parent = <&gpio2>;
- interrupts <&20 IRQ_TYPE_LEVEL_LOW>;
- touch-gpio = <&gpio2 20 GPIO_ACTIVE_LOW>;
- avdd-supply = <&ab8500_ldo_aux1_reg>;
-
- touchscreen-size-x = <384>;
- touchscreen-size-y = <704>;
- touchscreen-inverted-y;
- };
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml b/Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml
new file mode 100644
index 000000000000..74a8a01e0745
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/chipone,icn8318.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/chipone,icn8318.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ChipOne ICN8318 Touchscreen Controller
+
+maintainers:
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ const: chipone,icn8318
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ wake-gpios:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - wake-gpios
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@40 {
+ compatible = "chipone,icn8318";
+ reg = <0x40>;
+ interrupt-parent = <&pio>;
+ interrupts = <9 IRQ_TYPE_EDGE_FALLING>; /* EINT9 (PG9) */
+ pinctrl-names = "default";
+ pinctrl-0 = <&ts_wake_pin_p66>;
+ wake-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>; /* PB3 */
+ touchscreen-size-x = <800>;
+ touchscreen-size-y = <480>;
+ touchscreen-inverted-x;
+ touchscreen-swapped-x-y;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt b/Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt
deleted file mode 100644
index 38b0603f65f3..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/chipone_icn8318.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-* ChipOne icn8318 I2C touchscreen controller
-
-Required properties:
- - compatible : "chipone,icn8318"
- - reg : I2C slave address of the chip (0x40)
- - interrupts : interrupt specification for the icn8318 interrupt
- - wake-gpios : GPIO specification for the WAKE input
- - touchscreen-size-x : horizontal resolution of touchscreen (in pixels)
- - touchscreen-size-y : vertical resolution of touchscreen (in pixels)
-
-Optional properties:
- - pinctrl-names : should be "default"
- - pinctrl-0: : a phandle pointing to the pin settings for the
- control gpios
- - touchscreen-fuzz-x : horizontal noise value of the absolute input
- device (in pixels)
- - touchscreen-fuzz-y : vertical noise value of the absolute input
- device (in pixels)
- - touchscreen-inverted-x : X axis is inverted (boolean)
- - touchscreen-inverted-y : Y axis is inverted (boolean)
- - touchscreen-swapped-x-y : X and Y axis are swapped (boolean)
- Swapping is done after inverting the axis
-
-Example:
-
-i2c@00000000 {
- /* ... */
-
- chipone_icn8318@40 {
- compatible = "chipone,icn8318";
- reg = <0x40>;
- interrupt-parent = <&pio>;
- interrupts = <9 IRQ_TYPE_EDGE_FALLING>; /* EINT9 (PG9) */
- pinctrl-names = "default";
- pinctrl-0 = <&ts_wake_pin_p66>;
- wake-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>; /* PB3 */
- touchscreen-size-x = <800>;
- touchscreen-size-y = <480>;
- touchscreen-inverted-x;
- touchscreen-swapped-x-y;
- };
-
- /* ... */
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/colibri-vf50-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/colibri-vf50-ts.txt
deleted file mode 100644
index 2e1490a8fe74..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/colibri-vf50-ts.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-* Toradex Colibri VF50 Touchscreen driver
-
-Required Properties:
-- compatible must be toradex,vf50-touchscreen
-- io-channels: adc channels being used by the Colibri VF50 module
-- xp-gpios: FET gate driver for input of X+
-- xm-gpios: FET gate driver for input of X-
-- yp-gpios: FET gate driver for input of Y+
-- ym-gpios: FET gate driver for input of Y-
-- interrupts: pen irq interrupt for touch detection
-- pinctrl-names: "idle", "default", "gpios"
-- pinctrl-0: pinctrl node for pen/touch detection state pinmux
-- pinctrl-1: pinctrl node for X/Y and pressure measurement (ADC) state pinmux
-- pinctrl-2: pinctrl node for gpios functioning as FET gate drivers
-- vf50-ts-min-pressure: pressure level at which to stop measuring X/Y values
-
-Example:
-
- touchctrl: vf50_touchctrl {
- compatible = "toradex,vf50-touchscreen";
- io-channels = <&adc1 0>,<&adc0 0>,
- <&adc0 1>,<&adc1 2>;
- xp-gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
- xm-gpios = <&gpio2 29 GPIO_ACTIVE_HIGH>;
- yp-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
- ym-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>;
- interrupt-parent = <&gpio0>;
- interrupts = <8 IRQ_TYPE_LEVEL_LOW>;
- pinctrl-names = "idle","default","gpios";
- pinctrl-0 = <&pinctrl_touchctrl_idle>;
- pinctrl-1 = <&pinctrl_touchctrl_default>;
- pinctrl-2 = <&pinctrl_touchctrl_gpios>;
- vf50-ts-min-pressure = <200>;
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml
index 3225c8d1fdaf..86a6d18f952a 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma140.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/cypress,cy8ctma140.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Cypress CY8CTMA140 series touchscreen controller bindings
+title: Cypress CY8CTMA140 series touchscreen controller
maintainers:
- Linus Walleij <linus.walleij@linaro.org>
diff --git a/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml
index 762e56ee90cd..4dfbb93678b5 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/cypress,cy8ctma340.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Cypress CY8CTMA340 series touchscreen controller bindings
+title: Cypress CY8CTMA340 series touchscreen controller
description: The Cypress CY8CTMA340 series (also known as "CYTTSP" after
the marketing name Cypress TrueTouch Standard Product) touchscreens can
diff --git a/Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml b/Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml
new file mode 100644
index 000000000000..037e5d3c447f
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/cypress,tt21000.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/cypress,tt21000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cypress TT21000 touchscreen controller
+
+description: The Cypress TT21000 series (also known as "CYTTSP5" after
+ the marketing name Cypress TrueTouch Standard Product series 5).
+
+maintainers:
+ - Alistair Francis <alistair@alistair23.me>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ const: cypress,tt21000
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply:
+ description: Regulator for voltage.
+
+ vddio-supply:
+ description: Optional Regulator for I/O voltage.
+
+ reset-gpios:
+ maxItems: 1
+
+ linux,keycodes:
+ description: EV_ABS specific event code generated by the axis.
+
+ wakeup-source: true
+
+patternProperties:
+ "^button@[0-9]+$":
+ type: object
+ $ref: ../input.yaml#
+ properties:
+ reg:
+ maxItems: 1
+ linux,keycodes:
+ description: Keycode to emit
+
+ required:
+ - reg
+ - linux,keycodes
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - vdd-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/linux-event-codes.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@24 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ compatible = "cypress,tt21000";
+ reg = <0x24>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&tp_reset_ds203>;
+ interrupt-parent = <&pio>;
+ interrupts = <1 5 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&pio 7 1 GPIO_ACTIVE_LOW>;
+ vdd-supply = <&reg_touch>;
+
+ button@0 {
+ reg = <0>;
+ linux,keycodes = <KEY_HOMEPAGE>;
+ };
+
+ button@1 {
+ reg = <1>;
+ linux,keycodes = <KEY_MENU>;
+ };
+
+ button@2 {
+ reg = <2>;
+ linux,keycodes = <KEY_BACK>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml
index 2e8da7470513..7d3edb58f72d 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/edt-ft5x06.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: FocalTech EDT-FT5x06 Polytouch Bindings
+title: FocalTech EDT-FT5x06 Polytouch
description: |
There are 5 variants of the chip for various touch panel sizes
@@ -39,7 +39,12 @@ properties:
- edt,edt-ft5406
- edt,edt-ft5506
- evervision,ev-ft5726
+ - focaltech,ft5426
+ - focaltech,ft5452
- focaltech,ft6236
+ - focaltech,ft8201
+ - focaltech,ft8716
+ - focaltech,ft8719
reg:
maxItems: 1
@@ -85,16 +90,23 @@ properties:
minimum: 0
maximum: 80
- touchscreen-size-x: true
- touchscreen-size-y: true
- touchscreen-fuzz-x: true
- touchscreen-fuzz-y: true
- touchscreen-inverted-x: true
- touchscreen-inverted-y: true
- touchscreen-swapped-x-y: true
+ report-rate-hz:
+ description: |
+ Allows setting the scan rate in Hertz.
+ M06 supports range from 30 to 140 Hz.
+ M12 supports range from 1 to 255 Hz.
+ minimum: 1
+ maximum: 255
+
+ threshold:
+ description: Allows setting the "click"-threshold in the range from 0 to 255.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 255
+
interrupt-controller: true
-additionalProperties: false
+unevaluatedProperties: false
required:
- compatible
@@ -108,7 +120,7 @@ examples:
i2c {
#address-cells = <1>;
#size-cells = <0>;
- edt-ft5x06@38 {
+ touchscreen@38 {
compatible = "edt,edt-ft5406";
reg = <0x38>;
interrupt-parent = <&gpio2>;
diff --git a/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml b/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml
index 007adbc89c14..930c70104b3f 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/eeti,exc3000.yaml
@@ -9,21 +9,35 @@ title: EETI EXC3000 series touchscreen controller
maintainers:
- Dmitry Torokhov <dmitry.torokhov@gmail.com>
-allOf:
- - $ref: touchscreen.yaml#
-
properties:
compatible:
- enum:
- - eeti,exc3000
- - eeti,exc80h60
- - eeti,exc80h84
+ oneOf:
+ - const: eeti,exc3000
+ - const: eeti,exc80h60
+ - const: eeti,exc80h84
+ - const: eeti,egalax_ts # Do NOT use for new binding
+ - const: eeti,exc3000-i2c
+ deprecated: true
+ - items:
+ - enum:
+ - eeti,exc81w32
+ - const: eeti,exc80h84
reg:
- const: 0x2a
+ enum: [0x4, 0xa, 0x2a]
interrupts:
maxItems: 1
reset-gpios:
maxItems: 1
+ wakeup-gpios:
+ maxItems: 1
+ vdd-supply:
+ description: Power supply regulator for the chip
+ attn-gpios:
+ deprecated: true
+ maxItems: 1
+ description: Phandle to a GPIO to check whether interrupt is still
+ latched. This is necessary for platforms that lack
+ support for level-triggered IRQs.
touchscreen-size-x: true
touchscreen-size-y: true
touchscreen-inverted-x: true
@@ -34,11 +48,33 @@ required:
- compatible
- reg
- interrupts
- - touchscreen-size-x
- - touchscreen-size-y
additionalProperties: false
+allOf:
+ - $ref: touchscreen.yaml#
+
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ enum:
+ - eeti,egalax_ts
+ - eeti,exc3000-i2c
+ then:
+ properties:
+ reg:
+ const: 0x2a
+
+ wakeup-gpios: false
+
+ attn-gpios: false
+
+ required:
+ - touchscreen-size-x
+ - touchscreen-size-y
+
examples:
- |
#include "dt-bindings/interrupt-controller/irq.h"
diff --git a/Documentation/devicetree/bindings/input/touchscreen/eeti.txt b/Documentation/devicetree/bindings/input/touchscreen/eeti.txt
deleted file mode 100644
index 32b3712c916e..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/eeti.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Bindings for EETI touchscreen controller
-
-Required properties:
-- compatible: should be "eeti,exc3000-i2c"
-- reg: I2C address of the chip. Should be set to <0xa>
-- interrupts: interrupt to which the chip is connected
-
-Optional properties:
-- attn-gpios: A handle to a GPIO to check whether interrupt is still
- latched. This is necessary for platforms that lack
- support for level-triggered IRQs.
-
-The following optional properties described in touchscreen.txt are
-also supported:
-
-- touchscreen-inverted-x
-- touchscreen-inverted-y
-- touchscreen-swapped-x-y
-
-Example:
-
-i2c-master {
- touchscreen@a {
- compatible = "eeti,exc3000-i2c";
- reg = <0xa>;
- interrupt-parent = <&gpio>;
- interrupts = <123 IRQ_TYPE_EDGE_RISING>;
- attn-gpios = <&gpio 123 GPIO_ACTIVE_HIGH>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt
deleted file mode 100644
index 92fb2620f5e2..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/egalax-ts.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-* EETI eGalax Multiple Touch Controller
-
-Required properties:
-- compatible: must be "eeti,egalax_ts"
-- reg: i2c slave address
-- interrupts: touch controller interrupt
-- wakeup-gpios: the gpio pin to be used for waking up the controller
- and also used as irq pin
-
-Example:
-
- touchscreen@4 {
- compatible = "eeti,egalax_ts";
- reg = <0x04>;
- interrupt-parent = <&gpio1>;
- interrupts = <9 2>;
- wakeup-gpios = <&gpio1 9 0>;
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ektf2127.txt b/Documentation/devicetree/bindings/input/touchscreen/ektf2127.txt
deleted file mode 100644
index 5eef5e7d6aae..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/ektf2127.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* Elan eKTF2127 I2C touchscreen controller
-
-Required properties:
- - compatible : "elan,ektf2127" or "elan,ektf2132"
- - reg : I2C slave address of the chip (0x40)
- - interrupts : interrupt specification for the ektf2127 interrupt
- - power-gpios : GPIO specification for the pin connected to the
- ektf2127's wake input. This needs to be driven high
- to take ektf2127 out of it's low power state
-
-For additional optional properties see: touchscreen.txt
-
-Example:
-
-i2c@00000000 {
- ektf2127: touchscreen@15 {
- compatible = "elan,ektf2127";
- reg = <0x15>;
- interrupt-parent = <&pio>;
- interrupts = <6 11 IRQ_TYPE_EDGE_FALLING>
- power-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>;
- touchscreen-inverted-x;
- touchscreen-swapped-x-y;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/elan,ektf2127.yaml b/Documentation/devicetree/bindings/input/touchscreen/elan,ektf2127.yaml
new file mode 100644
index 000000000000..ff0ec3fd24c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/elan,ektf2127.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/elan,ektf2127.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Elan eKTF2127 I2C touchscreen controller
+
+maintainers:
+ - Siebren Vroegindeweij <siebren.vroegindeweij@hotmail.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - elan,ektf2127
+ - elan,ektf2132
+ - elan,ektf2232
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ power-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - power-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@15 {
+ compatible = "elan,ektf2127";
+ reg = <0x15>;
+ interrupt-parent = <&pio>;
+ interrupts = <6 11 IRQ_TYPE_EDGE_FALLING>;
+ power-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>;
+ touchscreen-inverted-x;
+ touchscreen-swapped-x-y;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml b/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml
index a9b53c2e6f0a..3255c2c8951a 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/elan,elants_i2c.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/input/touchscreen/elan,elants_i2c.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/input/touchscreen/elan,elants_i2c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Elantech I2C Touchscreen
@@ -14,9 +14,13 @@ allOf:
properties:
compatible:
- enum:
- - elan,ektf3624
- - elan,ekth3500
+ oneOf:
+ - enum:
+ - elan,ektf3624
+ - elan,ekth3500
+ - items:
+ - const: elan,ekth3915
+ - const: elan,ekth3500
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/input/touchscreen/fsl,imx6ul-tsc.yaml b/Documentation/devicetree/bindings/input/touchscreen/fsl,imx6ul-tsc.yaml
new file mode 100644
index 000000000000..a99280aefcbe
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/fsl,imx6ul-tsc.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/fsl,imx6ul-tsc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale i.MX6UL Touch Controller
+
+maintainers:
+ - Haibo Chen <haibo.chen@nxp.com>
+ - Shawn Guo <shawnguo@kernel.org>
+ - Sascha Hauer <s.hauer@pengutronix.de>
+
+properties:
+ compatible:
+ const: fsl,imx6ul-tsc
+
+ reg:
+ items:
+ - description: touch controller address
+ - description: ADC2 address
+
+ interrupts:
+ items:
+ - description: touch controller address
+ - description: ADC2 address
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: tsc
+ - const: adc
+
+ xnur-gpios:
+ maxItems: 1
+ description:
+ The X- gpio this controller connect to. This xnur-gpio returns to
+ low once the finger leave the touch screen (The last touch event
+ the touch controller capture).
+
+ measure-delay-time:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The value of measure delay time. Before X-axis or Y-axis measurement,
+ the screen need some time before even potential distribution ready.
+ default: 0xffff
+ minimum: 0
+ maximum: 0xffffff
+
+ pre-charge-time:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The touch screen need some time to precharge.
+ default: 0xfff
+ minimum: 0
+ maximum: 0xffffffff
+
+ touchscreen-average-samples:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of data samples which are averaged for each read.
+ enum: [ 1, 4, 8, 16, 32 ]
+
+ debounce-delay-us:
+ description: |
+ Minimum duration in microseconds a signal must remain stable
+ to be considered valid.
+
+ Drivers must convert this value to IPG clock cycles and map
+ it to one of the four discrete thresholds exposed by the
+ TSC_DEBUG_MODE2 register:
+
+ 0: 8191 IPG cycles
+ 1: 4095 IPG cycles
+ 2: 2047 IPG cycles
+ 3: 1023 IPG cycles
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - xnur-gpios
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/imx6ul-clock.h>
+ #include <dt-bindings/gpio/gpio.h>
+ touchscreen@2040000 {
+ compatible = "fsl,imx6ul-tsc";
+ reg = <0x02040000 0x4000>, <0x0219c000 0x4000>;
+ interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clks IMX6UL_CLK_IPG>,
+ <&clks IMX6UL_CLK_ADC2>;
+ clock-names = "tsc", "adc";
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_tsc>;
+ xnur-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>;
+ measure-delay-time = <0xfff>;
+ pre-charge-time = <0xffff>;
+ touchscreen-average-samples = <32>;
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml
new file mode 100644
index 000000000000..c40d92b7f4af
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/goodix,gt9916.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Goodix Berlin series touchscreen controller
+
+description: The Goodix Berlin series of touchscreen controllers
+ be connected to either I2C or SPI buses.
+
+maintainers:
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+allOf:
+ - $ref: touchscreen.yaml#
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ enum:
+ - goodix,gt9897
+ - goodix,gt9916
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog power supply regulator on AVDD pin
+
+ vddio-supply:
+ description: power supply regulator on VDDIO pin
+
+ spi-max-frequency: true
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-swapped-x-y: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - avdd-supply
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@5d {
+ compatible = "goodix,gt9916";
+ reg = <0x5d>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&ts_avdd>;
+ touchscreen-size-x = <1024>;
+ touchscreen-size-y = <768>;
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ num-cs = <1>;
+ cs-gpios = <&gpio 2 GPIO_ACTIVE_HIGH>;
+ touchscreen@0 {
+ compatible = "goodix,gt9916";
+ reg = <0>;
+ interrupt-parent = <&gpio>;
+ interrupts = <25 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&ts_avdd>;
+ spi-max-frequency = <1000000>;
+ touchscreen-size-x = <1024>;
+ touchscreen-size-y = <768>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml
index 93f2ce3130ae..a96137c6f063 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/goodix.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Goodix GT9xx series touchscreen controller Bindings
+title: Goodix GT9xx series touchscreen controller
maintainers:
- Dmitry Torokhov <dmitry.torokhov@gmail.com>
@@ -16,6 +16,7 @@ properties:
compatible:
enum:
- goodix,gt1151
+ - goodix,gt1158
- goodix,gt5663
- goodix,gt5688
- goodix,gt911
@@ -36,8 +37,9 @@ properties:
maxItems: 1
irq-gpios:
- description: GPIO pin used for IRQ. The driver uses the interrupt gpio pin
- as output to reset the device.
+ description: GPIO pin used for IRQ input. Additionally, this line is
+ sampled by the device on reset deassertion to select the I2C client
+ address, thus it can be driven by the host during the reset sequence.
maxItems: 1
reset-gpios:
@@ -60,14 +62,13 @@ additionalProperties: false
required:
- compatible
- reg
- - interrupts
examples:
- |
i2c {
#address-cells = <1>;
#size-cells = <0>;
- gt928@5d {
+ touchscreen@5d {
compatible = "goodix,gt928";
reg = <0x5d>;
interrupt-parent = <&gpio>;
diff --git a/Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml b/Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml
new file mode 100644
index 000000000000..f5cfacb5e966
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/himax,hx83112b.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/himax,hx83112b.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Himax hx83112b touchscreen controller
+
+maintainers:
+ - Job Noorman <job@noorman.info>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - himax,hx83100a
+ - himax,hx83112b
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-swapped-x-y: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - reset-gpios
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@48 {
+ compatible = "himax,hx83112b";
+ reg = <0x48>;
+ interrupt-parent = <&tlmm>;
+ interrupts = <65 IRQ_TYPE_LEVEL_LOW>;
+ touchscreen-size-x = <1080>;
+ touchscreen-size-y = <2160>;
+ reset-gpios = <&tlmm 64 GPIO_ACTIVE_LOW>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/himax,hx852es.yaml b/Documentation/devicetree/bindings/input/touchscreen/himax,hx852es.yaml
new file mode 100644
index 000000000000..40a60880111d
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/himax,hx852es.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/himax,hx852es.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Himax HX852x(ES) touch panel controller
+
+maintainers:
+ - Stephan Gerhold <stephan@gerhold.net>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - himax,hx8525e
+ - himax,hx8526e
+ - himax,hx8527e
+ - const: himax,hx852es
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+ description: Touch Screen Interrupt (TSIX), active low
+
+ reset-gpios:
+ maxItems: 1
+ description: External Reset (XRES), active low
+
+ vcca-supply:
+ description: Analog power supply (VCCA)
+
+ vccd-supply:
+ description: Digital power supply (VCCD)
+
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-swapped-x-y: true
+
+ linux,keycodes:
+ minItems: 1
+ maxItems: 4
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - reset-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/input.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@48 {
+ compatible = "himax,hx8527e", "himax,hx852es";
+ reg = <0x48>;
+ interrupt-parent = <&tlmm>;
+ interrupts = <13 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&tlmm 12 GPIO_ACTIVE_LOW>;
+ vcca-supply = <&reg_ts_vcca>;
+ vccd-supply = <&pm8916_l6>;
+ linux,keycodes = <KEY_BACK KEY_HOMEPAGE KEY_APPSELECT>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/hycon,hy46xx.yaml b/Documentation/devicetree/bindings/input/touchscreen/hycon,hy46xx.yaml
index 942562f1e45b..874c0781c476 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/hycon,hy46xx.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/hycon,hy46xx.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/hycon,hy46xx.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Hycon HY46XX series touchscreen controller bindings
+title: Hycon HY46XX series touchscreen controller
description: |
There are 6 variants of the chip for various touch panel sizes and cover lens material
diff --git a/Documentation/devicetree/bindings/input/touchscreen/hynitron,cst816x.yaml b/Documentation/devicetree/bindings/input/touchscreen/hynitron,cst816x.yaml
new file mode 100644
index 000000000000..72d4da636881
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/hynitron,cst816x.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/hynitron,cst816x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Hynitron CST816x Series Capacitive Touch controller
+
+maintainers:
+ - Oleh Kuzhylnyi <kuzhylol@gmail.com>
+
+description: |
+ Bindings for CST816x high performance self-capacitance touch chip series
+ with single point gesture and real two-point operation.
+
+properties:
+ compatible:
+ enum:
+ - hynitron,cst816s
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ linux,keycodes:
+ minItems: 1
+ items:
+ - description: Slide up gesture
+ - description: Slide down gesture
+ - description: Slide left gesture
+ - description: Slide right gesture
+ - description: Long press gesture
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/input/linux-event-codes.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@15 {
+ compatible = "hynitron,cst816s";
+ reg = <0x15>;
+ interrupt-parent = <&gpio0>;
+ interrupts = <4 IRQ_TYPE_EDGE_RISING>;
+ reset-gpios = <&gpio 17 GPIO_ACTIVE_LOW>;
+ linux,keycodes = <KEY_UP>, <KEY_DOWN>, <KEY_LEFT>, <KEY_RIGHT>,
+ <BTN_TOOL_TRIPLETAP>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml b/Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml
new file mode 100644
index 000000000000..9cb5d4af00f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/hynitron,cstxxx.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/hynitron,cstxxx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Hynitron cstxxx series touchscreen controller
+
+description: |
+ Bindings for Hynitron cstxxx series multi-touch touchscreen
+ controllers.
+
+maintainers:
+ - Chris Morgan <macromorgan@hotmail.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - hynitron,cst340
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-swapped-x-y: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - reset-gpios
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@1a {
+ compatible = "hynitron,cst340";
+ reg = <0x1a>;
+ interrupt-parent = <&gpio4>;
+ interrupts = <9 IRQ_TYPE_EDGE_FALLING>;
+ reset-gpios = <&gpio4 6 GPIO_ACTIVE_LOW>;
+ touchscreen-size-x = <640>;
+ touchscreen-size-y = <480>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ilitek_ts_i2c.yaml b/Documentation/devicetree/bindings/input/touchscreen/ilitek_ts_i2c.yaml
index a190e7baac31..9f7328999756 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/ilitek_ts_i2c.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/ilitek_ts_i2c.yaml
@@ -15,6 +15,9 @@ allOf:
properties:
compatible:
enum:
+ - ilitek,ili210x
+ - ilitek,ili2117
+ - ilitek,ili2120
- ilitek,ili2130
- ilitek,ili2131
- ilitek,ili2132
@@ -22,11 +25,12 @@ properties:
- ilitek,ili2322
- ilitek,ili2323
- ilitek,ili2326
+ - ilitek,ili251x
- ilitek,ili2520
- ilitek,ili2521
reg:
- const: 0x41
+ maxItems: 1
interrupts:
maxItems: 1
@@ -50,7 +54,6 @@ required:
- compatible
- reg
- interrupts
- - reset-gpios
examples:
- |
diff --git a/Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml b/Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml
new file mode 100644
index 000000000000..0ef79343bf9a
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/imagis,ist3038c.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/imagis,ist3038c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Imagis IST30XXC family touchscreen controller
+
+maintainers:
+ - Markuss Broks <markuss.broks@gmail.com>
+
+properties:
+ $nodename:
+ pattern: "^touchscreen@[0-9a-f]+$"
+
+ compatible:
+ enum:
+ - imagis,ist3032c
+ - imagis,ist3038
+ - imagis,ist3038b
+ - imagis,ist3038c
+ - imagis,ist3038h
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vdd-supply:
+ description: Power supply regulator for the chip
+
+ vddio-supply:
+ description: Power supply regulator for the I2C bus
+
+ linux,keycodes:
+ description: Keycodes for the touch keys
+ minItems: 2
+ maxItems: 5
+
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-fuzz-x: true
+ touchscreen-fuzz-y: true
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-swapped-x-y: true
+
+additionalProperties: false
+
+allOf:
+ - $ref: touchscreen.yaml#
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ const: imagis,ist3032c
+ then:
+ properties:
+ linux,keycodes: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@50 {
+ compatible = "imagis,ist3038c";
+ reg = <0x50>;
+ interrupt-parent = <&gpio>;
+ interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&ldo1_reg>;
+ vddio-supply = <&ldo2_reg>;
+ touchscreen-size-x = <720>;
+ touchscreen-size-y = <1280>;
+ touchscreen-fuzz-x = <10>;
+ touchscreen-fuzz-y = <10>;
+ touchscreen-inverted-x;
+ touchscreen-inverted-y;
+ };
+ };
+ - |
+ #include <dt-bindings/input/linux-event-codes.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@50 {
+ compatible = "imagis,ist3032c";
+ reg = <0x50>;
+ interrupt-parent = <&gpio>;
+ interrupts = <72 IRQ_TYPE_EDGE_FALLING>;
+ vdd-supply = <&ldo2>;
+ touchscreen-size-x = <480>;
+ touchscreen-size-y = <800>;
+ linux,keycodes = <KEY_APPSELECT>, <KEY_BACK>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/imx6ul_tsc.txt b/Documentation/devicetree/bindings/input/touchscreen/imx6ul_tsc.txt
deleted file mode 100644
index 164915004424..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/imx6ul_tsc.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-* Freescale i.MX6UL Touch Controller
-
-Required properties:
-- compatible: must be "fsl,imx6ul-tsc".
-- reg: this touch controller address and the ADC2 address.
-- interrupts: the interrupt of this touch controller and ADC2.
-- clocks: the root clock of touch controller and ADC2.
-- clock-names; must be "tsc" and "adc".
-- xnur-gpio: the X- gpio this controller connect to.
- This xnur-gpio returns to low once the finger leave the touch screen (The
- last touch event the touch controller capture).
-
-Optional properties:
-- measure-delay-time: the value of measure delay time.
- Before X-axis or Y-axis measurement, the screen need some time before
- even potential distribution ready.
- This value depends on the touch screen.
-- pre-charge-time: the touch screen need some time to precharge.
- This value depends on the touch screen.
-- touchscreen-average-samples: Number of data samples which are averaged for
- each read. Valid values are 1, 4, 8, 16 and 32.
-
-Example:
- tsc: tsc@2040000 {
- compatible = "fsl,imx6ul-tsc";
- reg = <0x02040000 0x4000>, <0x0219c000 0x4000>;
- interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&clks IMX6UL_CLK_IPG>,
- <&clks IMX6UL_CLK_ADC2>;
- clock-names = "tsc", "adc";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_tsc>;
- xnur-gpio = <&gpio1 3 GPIO_ACTIVE_LOW>;
- measure-delay-time = <0xfff>;
- pre-charge-time = <0xffff>;
- touchscreen-average-samples = <32>;
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/lpc32xx-tsc.txt b/Documentation/devicetree/bindings/input/touchscreen/lpc32xx-tsc.txt
deleted file mode 100644
index 41cbf4b7a670..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/lpc32xx-tsc.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-* NXP LPC32xx SoC Touchscreen Controller (TSC)
-
-Required properties:
-- compatible: must be "nxp,lpc3220-tsc"
-- reg: physical base address of the controller and length of memory mapped
- region.
-- interrupts: The TSC/ADC interrupt
-
-Example:
-
- tsc@40048000 {
- compatible = "nxp,lpc3220-tsc";
- reg = <0x40048000 0x1000>;
- interrupt-parent = <&mic>;
- interrupts = <39 0>;
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt
deleted file mode 100644
index 05e982c3454e..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-* MAXI MAX11801 Resistive touch screen controller with i2c interface
-
-Required properties:
-- compatible: must be "maxim,max11801"
-- reg: i2c slave address
-- interrupts: touch controller interrupt
-
-Example:
-
-&i2c1 {
- max11801: touchscreen@48 {
- compatible = "maxim,max11801";
- reg = <0x48>;
- interrupt-parent = <&gpio3>;
- interrupts = <31 IRQ_TYPE_EDGE_FALLING>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/maxim,max11801.yaml b/Documentation/devicetree/bindings/input/touchscreen/maxim,max11801.yaml
new file mode 100644
index 000000000000..4f528d220199
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/maxim,max11801.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/maxim,max11801.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MAXI MAX11801 Resistive touch screen controller with i2c interface
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: maxim,max11801
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+allOf:
+ - $ref: touchscreen.yaml
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@48 {
+ compatible = "maxim,max11801";
+ reg = <0x48>;
+ interrupt-parent = <&gpio3>;
+ interrupts = <31 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml b/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml
index 62366886fb3e..90ebd4f8354c 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/melfas,mms114.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Melfas MMS114 family touchscreen controller bindings
+title: Melfas MMS114 family touchscreen controller
maintainers:
- Linus Walleij <linus.walleij@linaro.org>
@@ -17,13 +17,17 @@ properties:
pattern: "^touchscreen(@.*)?$"
compatible:
- items:
+ oneOf:
- enum:
- melfas,mms114
- melfas,mms134s
- melfas,mms136
- melfas,mms152
- melfas,mms345l
+ - items:
+ - enum:
+ - melfas,mms252
+ - const: melfas,mms114
reg:
description: I2C address
@@ -52,6 +56,11 @@ properties:
touchscreen-swapped-x-y: true
touchscreen-max-pressure: true
+ linux,keycodes:
+ description: Keycodes for the touch keys
+ minItems: 1
+ maxItems: 15
+
additionalProperties: false
required:
diff --git a/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml b/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml
index 3a42c23faf6f..ddbbc820c7e5 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/mstar,msg2638.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/input/touchscreen/mstar,msg2638.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: MStar msg2638 touchscreen controller Bindings
+title: MStar msg2638 touchscreen controller
maintainers:
- Vincent Knecht <vincent.knecht@mailoo.org>
@@ -14,7 +14,9 @@ allOf:
properties:
compatible:
- const: mstar,msg2638
+ enum:
+ - mstar,msg2138
+ - mstar,msg2638
reg:
const: 0x26
@@ -34,6 +36,10 @@ properties:
touchscreen-size-x: true
touchscreen-size-y: true
+ linux,keycodes:
+ minItems: 1
+ maxItems: 4
+
additionalProperties: false
required:
diff --git a/Documentation/devicetree/bindings/input/touchscreen/neonode,zforce.yaml b/Documentation/devicetree/bindings/input/touchscreen/neonode,zforce.yaml
new file mode 100644
index 000000000000..c2ee89b76ea1
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/neonode,zforce.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/neonode,zforce.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Neonode infrared touchscreen controller
+
+maintainers:
+ - Heiko Stuebner <heiko@sntech.de>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ const: neonode,zforce
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ irq-gpios:
+ maxItems: 1
+
+ x-size:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ y-size:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ vdd-supply: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - reset-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@50 {
+ compatible = "neonode,zforce";
+ reg = <0x50>;
+ interrupts = <2 0>;
+ vdd-supply = <&reg_zforce_vdd>;
+
+ reset-gpios = <&gpio5 9 0>; /* RST */
+ irq-gpios = <&gpio5 6 0>; /* IRQ, optional */
+
+ touchscreen-min-x = <0>;
+ touchscreen-size-x = <800>;
+ touchscreen-min-y = <0>;
+ touchscreen-size-y = <600>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/novatek,nvt-ts.yaml b/Documentation/devicetree/bindings/input/touchscreen/novatek,nvt-ts.yaml
new file mode 100644
index 000000000000..bd6a60486d1f
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/novatek,nvt-ts.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/novatek,nvt-ts.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Novatek NVT Touchscreen Controller
+
+maintainers:
+ - Hans de Goede <hdegoede@redhat.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - novatek,nt11205-ts
+ - novatek,nt36672a-ts
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ vcc-supply: true
+ iovcc-supply: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@1 {
+ compatible = "novatek,nt36672a-ts";
+ reg = <0x01>;
+ interrupts-extended = <&tlmm 31 IRQ_TYPE_EDGE_RISING>;
+ reset-gpios = <&tlmm 32 GPIO_ACTIVE_LOW>;
+ vcc-supply = <&vreg_l22a_2p85>;
+ iovcc-supply = <&vreg_l14a_1p8>;
+ pinctrl-0 = <&ts_int_default &ts_reset_default>;
+ pinctrl-1 = <&ts_int_sleep &ts_reset_sleep>;
+ pinctrl-names = "default", "sleep";
+ touchscreen-size-x = <1080>;
+ touchscreen-size-y = <2246>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/nxp,lpc3220-tsc.yaml b/Documentation/devicetree/bindings/input/touchscreen/nxp,lpc3220-tsc.yaml
new file mode 100644
index 000000000000..b6feda127c7b
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/nxp,lpc3220-tsc.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/nxp,lpc3220-tsc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP LPC32xx SoC Touchscreen Controller (TSC)
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: nxp,lpc3220-tsc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/lpc32xx-clock.h>
+
+ touchscreen@40048000 {
+ compatible = "nxp,lpc3220-tsc";
+ reg = <0x40048000 0x1000>;
+ interrupt-parent = <&mic>;
+ interrupts = <39 0>;
+ clocks = <&clk LPC32XX_CLK_ADC>;
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml b/Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml
new file mode 100644
index 000000000000..3305eda5ed88
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/pixcir,pixcir_ts.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/pixcir,pixcir_ts.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Pixcir Touchscreen Controller
+
+maintainers:
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - pixcir,pixcir_ts
+ - pixcir,pixcir_tangoc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ attb-gpio:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ enable-gpios:
+ maxItems: 1
+
+ wake-gpios:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - attb-gpio
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@5c {
+ compatible = "pixcir,pixcir_ts";
+ reg = <0x5c>;
+ interrupts = <2 0>;
+ attb-gpio = <&gpf 2 0 2>;
+ touchscreen-size-x = <800>;
+ touchscreen-size-y = <600>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt b/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt
deleted file mode 100644
index 697a3e7831e7..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-* Pixcir I2C touchscreen controllers
-
-Required properties:
-- compatible: must be "pixcir,pixcir_ts" or "pixcir,pixcir_tangoc"
-- reg: I2C address of the chip
-- interrupts: interrupt to which the chip is connected
-- attb-gpio: GPIO connected to the ATTB line of the chip
-- touchscreen-size-x: horizontal resolution of touchscreen (in pixels)
-- touchscreen-size-y: vertical resolution of touchscreen (in pixels)
-
-Optional properties:
-- reset-gpios: GPIO connected to the RESET line of the chip
-- enable-gpios: GPIO connected to the ENABLE line of the chip
-- wake-gpios: GPIO connected to the WAKE line of the chip
-
-Example:
-
- i2c@00000000 {
- /* ... */
-
- pixcir_ts@5c {
- compatible = "pixcir,pixcir_ts";
- reg = <0x5c>;
- interrupts = <2 0>;
- attb-gpio = <&gpf 2 0 2>;
- touchscreen-size-x = <800>;
- touchscreen-size-y = <600>;
- };
-
- /* ... */
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/raspberrypi,firmware-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/raspberrypi,firmware-ts.txt
deleted file mode 100644
index 2a1af240ccc3..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/raspberrypi,firmware-ts.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Raspberry Pi firmware based 7" touchscreen
-=====================================
-
-Required properties:
- - compatible: "raspberrypi,firmware-ts"
-
-Optional properties:
- - firmware: Reference to RPi's firmware device node
- - touchscreen-size-x: See touchscreen.txt
- - touchscreen-size-y: See touchscreen.txt
- - touchscreen-inverted-x: See touchscreen.txt
- - touchscreen-inverted-y: See touchscreen.txt
- - touchscreen-swapped-x-y: See touchscreen.txt
-
-Example:
-
-firmware: firmware-rpi {
- compatible = "raspberrypi,bcm2835-firmware";
- mboxes = <&mailbox>;
-
- ts: touchscreen {
- compatible = "raspberrypi,firmware-ts";
- touchscreen-size-x = <800>;
- touchscreen-size-y = <480>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.yaml b/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.yaml
index 7fc22a403d48..059d419f6c1c 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.yaml
@@ -55,7 +55,7 @@ properties:
touchscreen-min-pressure: true
touchscreen-x-plate-ohms: true
-additionalProperties: false
+unevaluatedProperties: false
required:
- compatible
diff --git a/Documentation/devicetree/bindings/input/touchscreen/rohm,bu21013.yaml b/Documentation/devicetree/bindings/input/touchscreen/rohm,bu21013.yaml
new file mode 100644
index 000000000000..adea2c4edf1f
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/rohm,bu21013.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/rohm,bu21013.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rohm BU21013 touchscreen
+
+description:
+ Rohm BU21013 I2C driven touchscreen controller.
+
+maintainers:
+ - Dario Binacchi <dario.binacchi@amarulasolutions.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - rohm,bu21013_tp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ touch-gpios:
+ maxItems: 1
+ description: GPIO registering a touch event.
+
+ avdd-supply:
+ description: Analogic power supply
+
+ rohm,touch-max-x:
+ deprecated: true
+ description: Maximum value on the X axis.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ rohm,touch-max-y:
+ deprecated: true
+ description: Maximum value on the Y axis.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ rohm,flip-x:
+ deprecated: true
+ description: Flip touch coordinates on the X axis
+ type: boolean
+
+ rohm,flip-y:
+ deprecated: true
+ description: Flip touch coordinates on the Y axis
+ type: boolean
+
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-swapped-x-y: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - reset-gpios
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@5c {
+ compatible = "rohm,bu21013_tp";
+ reg = <0x5c>;
+
+ interrupt-parent = <&gpio2>;
+ interrupts = <0x20 IRQ_TYPE_LEVEL_LOW>;
+ reset-gpios = <&gpio2 19 GPIO_ACTIVE_LOW>;
+ touch-gpios = <&gpio2 20 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&ab8500_ldo_aux1_reg>;
+
+ touchscreen-size-x = <384>;
+ touchscreen-size-y = <704>;
+ touchscreen-inverted-y;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.txt b/Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.txt
deleted file mode 100644
index 6805d10d226d..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-* Samsung S6SY761 touchscreen controller
-
-Required properties:
-- compatible : must be "samsung,s6sy761"
-- reg : I2C slave address, (e.g. 0x48)
-- interrupts : interrupt specification
-- avdd-supply : analogic power supply
-- vdd-supply : power supply
-
-Optional properties:
-- touchscreen-size-x : see touchscreen.txt. This property is embedded in the
- device. If defined it forces a different x resolution.
-- touchscreen-size-y : see touchscreen.txt. This property is embedded in the
- device. If defined it forces a different y resolution.
-
-Example:
-
-i2c@00000000 {
-
- /* ... */
-
- touchscreen@48 {
- compatible = "samsung,s6sy761";
- reg = <0x48>;
- interrupt-parent = <&gpa1>;
- interrupts = <1 IRQ_TYPE_NONE>;
- avdd-supply = <&ldo30_reg>;
- vdd-supply = <&ldo31_reg>;
- touchscreen-size-x = <4096>;
- touchscreen-size-y = <4096>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.yaml b/Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.yaml
new file mode 100644
index 000000000000..1ffd17af3c53
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/samsung,s6sy761.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/samsung,s6sy761.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S6SY761 touchscreen controller
+
+maintainers:
+ - Andi Shyti <andi.shyti@kernel.org>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ const: samsung,s6sy761
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ avdd-supply: true
+ vdd-supply: true
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - avdd-supply
+ - vdd-supply
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@48 {
+ compatible = "samsung,s6sy761";
+ reg = <0x48>;
+ interrupt-parent = <&gpa1>;
+ interrupts = <1 IRQ_TYPE_LEVEL_HIGH>;
+ avdd-supply = <&ldo30_reg>;
+ vdd-supply = <&ldo31_reg>;
+ touchscreen-size-x = <4096>;
+ touchscreen-size-y = <4096>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/semtech,sx8654.yaml b/Documentation/devicetree/bindings/input/touchscreen/semtech,sx8654.yaml
new file mode 100644
index 000000000000..b2554064b688
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/semtech,sx8654.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/semtech,sx8654.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Semtech SX8654 I2C Touchscreen Controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - semtech,sx8650
+ - semtech,sx8654
+ - semtech,sx8655
+ - semtech,sx8656
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@48 {
+ compatible = "semtech,sx8654";
+ reg = <0x48>;
+ interrupt-parent = <&gpio6>;
+ interrupts = <3 IRQ_TYPE_EDGE_FALLING>;
+ reset-gpios = <&gpio4 2 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml b/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml
new file mode 100644
index 000000000000..5381a96f4949
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/silead,gsl1680.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Silead GSL1680 Touchscreen Controller
+
+maintainers:
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - silead,gsl1680
+ - silead,gsl1688
+ - silead,gsl3670
+ - silead,gsl3675
+ - silead,gsl3692
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ power-gpios:
+ maxItems: 1
+
+ firmware-name:
+ maxItems: 1
+ description: >
+ File basename for board specific firmware
+
+ silead,max-fingers:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 5
+ description: >
+ Maximum number of fingers the touchscreen can detect
+
+ silead,home-button:
+ type: boolean
+ description: >
+ Does the device have a capacitive home-button build into the
+ touchscreen?
+
+ avdd-supply:
+ description: >
+ Regulator phandle for controller AVDD
+
+ vddio-supply:
+ description: >
+ Regulator phandle for controller VDDIO
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - power-gpios
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@40 {
+ compatible = "silead,gsl1680";
+ reg = <0x40>;
+ interrupt-parent = <&pio>;
+ interrupts = <6 11 IRQ_TYPE_EDGE_FALLING>;
+ power-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>;
+ touchscreen-size-x = <480>;
+ touchscreen-size-y = <800>;
+ touchscreen-inverted-x;
+ touchscreen-swapped-x-y;
+ silead,max-fingers = <5>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt
deleted file mode 100644
index d67e558e5ab5..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-* GSL 1680 touchscreen controller
-
-Required properties:
-- compatible : Must be one of the following, depending on the model:
- "silead,gsl1680"
- "silead,gsl1688"
- "silead,gsl3670"
- "silead,gsl3675"
- "silead,gsl3692"
-- reg : I2C slave address of the chip (0x40)
-- interrupts : interrupt specification for the gsl1680 interrupt
-- power-gpios : Specification for the pin connected to the gsl1680's
- shutdown input. This needs to be driven high to take the
- gsl1680 out of its low power state
-- touchscreen-size-x : See touchscreen.txt
-- touchscreen-size-y : See touchscreen.txt
-
-Optional properties:
-- firmware-name : File basename (string) for board specific firmware
-- touchscreen-inverted-x : See touchscreen.txt
-- touchscreen-inverted-y : See touchscreen.txt
-- touchscreen-swapped-x-y : See touchscreen.txt
-- silead,max-fingers : maximum number of fingers the touchscreen can detect
-- silead,home-button : Boolean, set to true on devices which have a
- capacitive home-button build into the touchscreen
-- vddio-supply : regulator phandle for controller VDDIO
-- avdd-supply : regulator phandle for controller AVDD
-
-Example:
-
-i2c@00000000 {
- gsl1680: touchscreen@40 {
- compatible = "silead,gsl1680";
- reg = <0x40>;
- interrupt-parent = <&pio>;
- interrupts = <6 11 IRQ_TYPE_EDGE_FALLING>;
- power-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>;
- touchscreen-size-x = <480>;
- touchscreen-size-y = <800>;
- touchscreen-inverted-x;
- touchscreen-swapped-x-y;
- silead,max-fingers = <5>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/sitronix,st1232.yaml b/Documentation/devicetree/bindings/input/touchscreen/sitronix,st1232.yaml
index 1d8ca19fd37a..e7ee7a0d74c4 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/sitronix,st1232.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/sitronix,st1232.yaml
@@ -37,6 +37,7 @@ unevaluatedProperties: false
examples:
- |
+ #include <dt-bindings/input/linux-event-codes.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -46,5 +47,33 @@ examples:
reg = <0x55>;
interrupts = <2 0>;
gpios = <&gpio1 166 0>;
+
+ touch-overlay {
+ segment-0 {
+ label = "Touchscreen";
+ x-origin = <0>;
+ x-size = <240>;
+ y-origin = <40>;
+ y-size = <280>;
+ };
+
+ segment-1a {
+ label = "Camera light";
+ linux,code = <KEY_LIGHTS_TOGGLE>;
+ x-origin = <40>;
+ x-size = <40>;
+ y-origin = <0>;
+ y-size = <40>;
+ };
+
+ segment-2a {
+ label = "Power";
+ linux,code = <KEY_POWER>;
+ x-origin = <160>;
+ x-size = <40>;
+ y-origin = <0>;
+ y-size = <40>;
+ };
+ };
};
};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/st,stmfts.txt b/Documentation/devicetree/bindings/input/touchscreen/st,stmfts.txt
deleted file mode 100644
index 0a5d0cb4a280..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/st,stmfts.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-* ST-Microelectronics FingerTip touchscreen controller
-
-The ST-Microelectronics FingerTip device provides a basic touchscreen
-functionality. Along with it the user can enable the touchkey which can work as
-a basic HOME and BACK key for phones.
-
-The driver supports also hovering as an absolute single touch event with x, y, z
-coordinates.
-
-Required properties:
-- compatible : must be "st,stmfts"
-- reg : I2C slave address, (e.g. 0x49)
-- interrupts : interrupt specification
-- avdd-supply : analogic power supply
-- vdd-supply : power supply
-- touchscreen-size-x : see touchscreen.txt
-- touchscreen-size-y : see touchscreen.txt
-
-Optional properties:
-- touch-key-connected : specifies whether the touchkey feature is connected
-- ledvdd-supply : power supply to the touch key leds
-
-Example:
-
-i2c@00000000 {
-
- /* ... */
-
- touchscreen@49 {
- compatible = "st,stmfts";
- reg = <0x49>;
- interrupt-parent = <&gpa1>;
- interrupts = <1 IRQ_TYPE_NONE>;
- touchscreen-size-x = <1599>;
- touchscreen-size-y = <2559>;
- touch-key-connected;
- avdd-supply = <&ldo30_reg>;
- vdd-supply = <&ldo31_reg>;
- ledvdd-supply = <&ldo33_reg>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/st,stmfts.yaml b/Documentation/devicetree/bindings/input/touchscreen/st,stmfts.yaml
new file mode 100644
index 000000000000..12256ae7df90
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/st,stmfts.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/st,stmfts.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST-Microelectronics FingerTip touchscreen controller
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description:
+ The ST-Microelectronics FingerTip device provides a basic touchscreen
+ functionality. Along with it the user can enable the touchkey which can work
+ as a basic HOME and BACK key for phones.
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ const: st,stmfts
+
+ reg:
+ maxItems: 1
+
+ avdd-supply:
+ description: Analogic power supply
+
+ interrupts:
+ maxItems: 1
+
+ ledvdd-supply:
+ description: Power supply to the touch key leds
+
+ touch-key-connected:
+ type: boolean
+ description: The touchkey feature is connected
+
+ vdd-supply:
+ description: Power supply
+
+required:
+ - compatible
+ - reg
+ - avdd-supply
+ - interrupts
+ - vdd-supply
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@49 {
+ compatible = "st,stmfts";
+ reg = <0x49>;
+ interrupt-parent = <&gpa1>;
+ interrupts = <1 IRQ_TYPE_LEVEL_LOW>;
+ touchscreen-size-x = <1599>;
+ touchscreen-size-y = <2559>;
+ touch-key-connected;
+ avdd-supply = <&ldo30_reg>;
+ vdd-supply = <&ldo31_reg>;
+ ledvdd-supply = <&ldo33_reg>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt b/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt
deleted file mode 100644
index c549924603d2..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt
+++ /dev/null
@@ -1,109 +0,0 @@
-STMPE Touchscreen
-----------------
-
-Required properties:
- - compatible: "st,stmpe-ts"
-
-Optional properties:
-- st,ave-ctrl : Sample average control
- 0 -> 1 sample
- 1 -> 2 samples
- 2 -> 4 samples
- 3 -> 8 samples
-- st,touch-det-delay : Touch detect interrupt delay (recommended is 3)
- 0 -> 10 us
- 1 -> 50 us
- 2 -> 100 us
- 3 -> 500 us
- 4 -> 1 ms
- 5 -> 5 ms
- 6 -> 10 ms
- 7 -> 50 ms
-- st,settling : Panel driver settling time (recommended is 2)
- 0 -> 10 us
- 1 -> 100 us
- 2 -> 500 us
- 3 -> 1 ms
- 4 -> 5 ms
- 5 -> 10 ms
- 6 -> 50 ms
- 7 -> 100 ms
-- st,fraction-z : Length of the fractional part in z (recommended is 7)
- (fraction-z ([0..7]) = Count of the fractional part)
-- st,i-drive : current limit value of the touchscreen drivers
- 0 -> 20 mA (typical 35mA max)
- 1 -> 50 mA (typical 80 mA max)
-
-Optional properties common with MFD (deprecated):
- - st,sample-time : ADC conversion time in number of clock.
- 0 -> 36 clocks
- 1 -> 44 clocks
- 2 -> 56 clocks
- 3 -> 64 clocks
- 4 -> 80 clocks (recommended)
- 5 -> 96 clocks
- 6 -> 124 clocks
- - st,mod-12b : ADC Bit mode
- 0 -> 10bit ADC
- 1 -> 12bit ADC
- - st,ref-sel : ADC reference source
- 0 -> internal
- 1 -> external
- - st,adc-freq : ADC Clock speed
- 0 -> 1.625 MHz
- 1 -> 3.25 MHz
- 2 || 3 -> 6.5 MHz
-
-Node name must be stmpe_touchscreen and should be child node of stmpe node to
-which it belongs.
-
-Note that common ADC settings of stmpe_touchscreen (child) will take precedence
-over the settings done in MFD.
-
-Example:
-
-stmpe811@41 {
- compatible = "st,stmpe811";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_touch_int>;
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x41>;
- interrupts = <10 IRQ_TYPE_LEVEL_LOW>;
- interrupt-parent = <&gpio4>;
- interrupt-controller;
- id = <0>;
- blocks = <0x5>;
- irq-trigger = <0x1>;
- /* Common ADC settings */
- /* 3.25 MHz ADC clock speed */
- st,adc-freq = <1>;
- /* 12-bit ADC */
- st,mod-12b = <1>;
- /* internal ADC reference */
- st,ref-sel = <0>;
- /* ADC converstion time: 80 clocks */
- st,sample-time = <4>;
-
- stmpe_touchscreen {
- compatible = "st,stmpe-ts";
- reg = <0>;
- /* 8 sample average control */
- st,ave-ctrl = <3>;
- /* 5 ms touch detect interrupt delay */
- st,touch-det-delay = <5>;
- /* 1 ms panel driver settling time */
- st,settling = <3>;
- /* 7 length fractional part in z */
- st,fraction-z = <7>;
- /*
- * 50 mA typical 80 mA max touchscreen drivers
- * current limit value
- */
- st,i-drive = <1>;
- };
- stmpe_adc {
- compatible = "st,stmpe-adc";
- st,norequest-mask = <0x0F>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/sx8654.txt b/Documentation/devicetree/bindings/input/touchscreen/sx8654.txt
deleted file mode 100644
index 0ebe6dd043c7..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/sx8654.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-* Semtech SX8654 I2C Touchscreen Controller
-
-Required properties:
-- compatible: must be one of the following, depending on the model:
- "semtech,sx8650"
- "semtech,sx8654"
- "semtech,sx8655"
- "semtech,sx8656"
-- reg: i2c slave address
-- interrupts: touch controller interrupt
-
-Optional properties:
- - reset-gpios: GPIO specification for the NRST input
-
-Example:
-
- sx8654@48 {
- compatible = "semtech,sx8654";
- reg = <0x48>;
- interrupt-parent = <&gpio6>;
- interrupts = <3 IRQ_TYPE_EDGE_FALLING>;
- reset-gpios = <&gpio4 2 GPIO_ACTIVE_LOW>;
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti,ads7843.yaml b/Documentation/devicetree/bindings/input/touchscreen/ti,ads7843.yaml
new file mode 100644
index 000000000000..8f6335d7da1c
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/ti,ads7843.yaml
@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/ti,ads7843.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI's SPI driven touch screen controllers
+
+maintainers:
+ - Alexander Stein <alexander.stein@ew.tq-group.com>
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+ - Marek Vasut <marex@denx.de>
+
+description:
+ TI's ADS7843, ADS7845, ADS7846, ADS7873, TSC2046 SPI driven touch screen
+ controllers.
+
+properties:
+ compatible:
+ enum:
+ - ti,ads7843
+ - ti,ads7845
+ - ti,ads7846
+ - ti,ads7873
+ - ti,tsc2046
+
+ interrupts:
+ maxItems: 1
+
+ pendown-gpio:
+ maxItems: 1
+ description:
+ GPIO handle describing the pin the !PENIRQ line is connected to.
+
+ vcc-supply:
+ description:
+ A regulator node for the supply voltage.
+
+ wakeup-source: true
+
+ ti,debounce-max:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Max number of additional readings per sample.
+
+ ti,debounce-rep:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Additional consecutive good readings required after the first two.
+
+ ti,debounce-tol:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Tolerance used for filtering.
+
+ ti,hsync-gpios:
+ maxItems: 1
+ description:
+ GPIO line to poll for hsync.
+
+ ti,keep-vref-on:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Set to keep Vref on for differential measurements as well.
+
+ ti,pendown-gpio-debounce:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Platform specific debounce time for the pendown-gpio.
+
+ ti,penirq-recheck-delay-usecs:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ If set to non-zero, after samples are taken this delay is applied and
+ penirq is rechecked, to help avoid false events. This value is
+ affected by the material used to build the touch layer.
+
+ ti,pressure-max:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Maximum reported pressure value.
+
+ ti,pressure-min:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Minimum reported pressure value (threshold).
+
+ ti,settle-delay-usec:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Settling time of the analog signals; a function of Vcc and the
+ capacitance on the X/Y drivers. If set to non-zero, two samples are
+ taken with settle_delay us apart, and the second one is used. ~150
+ uSec with 0.01uF caps.
+
+ ti,swap-xy:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Swap x and y axis.
+
+ ti,vref-delay-usecs:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Vref supply delay in usecs, 0 for external Vref.
+
+ ti,vref-mv:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ The VREF voltage, in millivolts.
+ Set to 0 to use internal references (ADS7846).
+
+ ti,x-plate-ohms:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Resistance of the X-plate, in Ohms.
+
+ ti,x-max:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Maximum value on the X axis.
+
+ ti,x-min:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Minimum value on the X axis.
+
+ ti,y-plate-ohms:
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Resistance of the Y-plate, in Ohms.
+
+ ti,y-max:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Maximum value on the Y axis.
+
+ ti,y-min:
+ deprecated: true
+ $ref: /schemas/types.yaml#/definitions/uint16
+ description:
+ Minimum value on the Y axis.
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: touchscreen.yaml#
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi{
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@0 {
+ compatible = "ti,tsc2046";
+ reg = <0>; /* CS0 */
+ interrupt-parent = <&gpio1>;
+ interrupts = <8 0>; /* BOOT6 / GPIO 8 */
+ pendown-gpio = <&gpio1 8 0>;
+ spi-max-frequency = <1000000>;
+ vcc-supply = <&reg_vcc3>;
+ wakeup-source;
+
+ ti,pressure-max = /bits/ 16 <255>;
+ ti,x-max = /bits/ 16 <8000>;
+ ti,x-min = /bits/ 16 <0>;
+ ti,x-plate-ohms = /bits/ 16 <40>;
+ ti,y-max = /bits/ 16 <4800>;
+ ti,y-min = /bits/ 16 <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti,am3359-tsc.yaml b/Documentation/devicetree/bindings/input/touchscreen/ti,am3359-tsc.yaml
new file mode 100644
index 000000000000..e44cc65abc8c
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/ti,am3359-tsc.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/ti,am3359-tsc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI AM3359 Touchscreen controller
+
+maintainers:
+ - Miquel Raynal <miquel.raynal@bootlin.com>
+
+properties:
+ compatible:
+ const: ti,am3359-tsc
+
+ ti,wires:
+ description: Wires refer to application modes i.e. 4/5/8 wire touchscreen
+ support on the platform.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [4, 5, 8]
+
+ ti,x-plate-resistance:
+ description: X plate resistance
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ ti,coordinate-readouts:
+ description: The sequencer supports a total of 16 programmable steps. Each
+ step is used to read a single coordinate. A single readout is enough but
+ multiple reads can increase the quality. A value of 5 means, 5 reads for
+ X, 5 for Y and 2 for Z (always). This utilises 12 of the 16 software steps
+ available. The remaining 4 can be used by the ADC.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 6
+
+ ti,wire-config:
+ description: Different boards could have a different order for connecting
+ wires on touchscreen. We need to provide an 8-bit number where the
+ first four bits represent the analog lines and the next 4 bits represent
+ positive/negative terminal on that input line. Notations to represent the
+ input lines and terminals respectively are as follows, AIN0 = 0, AIN1 = 1
+ and so on until AIN7 = 7. XP = 0, XN = 1, YP = 2, YN = 3.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 4
+ maxItems: 8
+
+ ti,charge-delay:
+ description: Length of touch screen charge delay step in terms of ADC clock
+ cycles. Charge delay value should be large in order to avoid false pen-up
+ events. This value effects the overall sampling speed, hence need to be
+ kept as low as possible, while avoiding false pen-up event. Start from a
+ lower value, say 0x400, and increase value until false pen-up events are
+ avoided. The pen-up detection happens immediately after the charge step,
+ so this does in fact function as a hardware knob for adjusting the amount
+ of "settling time".
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - ti,wires
+ - ti,x-plate-resistance
+ - ti,coordinate-readouts
+ - ti,wire-config
+
+additionalProperties: false
+
+examples:
+ - |
+ tsc {
+ compatible = "ti,am3359-tsc";
+ ti,wires = <4>;
+ ti,x-plate-resistance = <200>;
+ ti,coordinate-readouts = <5>;
+ ti,wire-config = <0x00 0x11 0x22 0x33>;
+ ti,charge-delay = <0x400>;
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml b/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml
new file mode 100644
index 000000000000..7187c390b2f5
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2005.yaml
@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/ti,tsc2005.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TSC2004 and TSC2005 touchscreen controller
+
+maintainers:
+ - Marek Vasut <marex@denx.de>
+ - Michael Welling <mwelling@ieee.org>
+
+properties:
+ $nodename:
+ pattern: "^touchscreen(@.*)?$"
+
+ compatible:
+ enum:
+ - ti,tsc2004
+ - ti,tsc2005
+
+ reg:
+ maxItems: 1
+ description: |
+ I2C address when used on the I2C bus, or the SPI chip select index
+ when used on the SPI bus
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+ description: GPIO specifier for the controller reset line
+
+ spi-max-frequency:
+ description: TSC2005 SPI bus clock frequency.
+ maximum: 25000000
+
+ ti,x-plate-ohms:
+ description: resistance of the touchscreen's X plates in ohm (defaults to 280)
+
+ ti,esd-recovery-timeout-ms:
+ description: |
+ if the touchscreen does not respond after the configured time
+ (in milli seconds), the driver will reset it. This is disabled
+ by default.
+
+ vio-supply:
+ description: Regulator specifier
+
+ touchscreen-fuzz-pressure: true
+ touchscreen-fuzz-x: true
+ touchscreen-fuzz-y: true
+ touchscreen-max-pressure: true
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+
+allOf:
+ - $ref: touchscreen.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,tsc2004
+ then:
+ properties:
+ spi-max-frequency: false
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@48 {
+ compatible = "ti,tsc2004";
+ reg = <0x48>;
+ vio-supply = <&vio>;
+
+ reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>;
+ interrupts-extended = <&gpio1 27 IRQ_TYPE_EDGE_RISING>;
+
+ touchscreen-fuzz-x = <4>;
+ touchscreen-fuzz-y = <7>;
+ touchscreen-fuzz-pressure = <2>;
+ touchscreen-size-x = <4096>;
+ touchscreen-size-y = <4096>;
+ touchscreen-max-pressure = <2048>;
+
+ ti,x-plate-ohms = <280>;
+ ti,esd-recovery-timeout-ms = <8000>;
+ };
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ touchscreen@0 {
+ compatible = "ti,tsc2005";
+ spi-max-frequency = <6000000>;
+ reg = <0>;
+
+ vio-supply = <&vio>;
+
+ reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; /* 104 */
+ interrupts-extended = <&gpio4 4 IRQ_TYPE_EDGE_RISING>; /* 100 */
+
+ touchscreen-fuzz-x = <4>;
+ touchscreen-fuzz-y = <7>;
+ touchscreen-fuzz-pressure = <2>;
+ touchscreen-size-x = <4096>;
+ touchscreen-size-y = <4096>;
+ touchscreen-max-pressure = <2048>;
+
+ ti,x-plate-ohms = <280>;
+ ti,esd-recovery-timeout-ms = <8000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2007.yaml b/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2007.yaml
new file mode 100644
index 000000000000..a595df3ea802
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/ti,tsc2007.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/ti,tsc2007.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments tsc2007 touchscreen controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: ti,tsc2007
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ ti,x-plate-ohms:
+ description: X-plate resistance in ohms.
+
+ gpios: true
+
+ pendown-gpio: true
+
+ wakeup-source: true
+
+ ti,max-rt:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: maximum pressure.
+
+ ti,fuzzx:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ specifies the absolute input fuzz x value.
+ If set, it will permit noise in the data up to +- the value given to the fuzz
+ parameter, that is used to filter noise from the event stream.
+
+ ti,fuzzy:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: specifies the absolute input fuzz y value.
+
+ ti,fuzzz:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: specifies the absolute input fuzz z value.
+
+ ti,poll-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ how much time to wait (in milliseconds) before reading again the
+ values from the tsc2007.
+
+required:
+ - compatible
+ - reg
+ - ti,x-plate-ohms
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touch@49 {
+ compatible = "ti,tsc2007";
+ reg = <0x49>;
+ interrupt-parent = <&gpio4>;
+ interrupts = <0x0 0x8>;
+ gpios = <&gpio4 0 0>;
+ ti,x-plate-ohms = <180>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt
deleted file mode 100644
index aad5e34965eb..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt
+++ /dev/null
@@ -1,91 +0,0 @@
-* TI - TSC ADC (Touschscreen and analog digital converter)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Required properties:
-- mfd
- compatible: Should be
- "ti,am3359-tscadc" for AM335x/AM437x SoCs
- "ti,am654-tscadc", "ti,am3359-tscadc" for AM654 SoCs
-- child "tsc"
- compatible: Should be "ti,am3359-tsc".
- ti,wires: Wires refer to application modes i.e. 4/5/8 wire touchscreen
- support on the platform.
- ti,x-plate-resistance: X plate resistance
- ti,coordinate-readouts: The sequencer supports a total of 16
- programmable steps each step is used to
- read a single coordinate. A single
- readout is enough but multiple reads can
- increase the quality.
- A value of 5 means, 5 reads for X, 5 for
- Y and 2 for Z (always). This utilises 12
- of the 16 software steps available. The
- remaining 4 can be used by the ADC.
- ti,wire-config: Different boards could have a different order for
- connecting wires on touchscreen. We need to provide an
- 8 bit number where in the 1st four bits represent the
- analog lines and the next 4 bits represent positive/
- negative terminal on that input line. Notations to
- represent the input lines and terminals resoectively
- is as follows:
- AIN0 = 0, AIN1 = 1 and so on till AIN7 = 7.
- XP = 0, XN = 1, YP = 2, YN = 3.
-- child "adc"
- compatible: Should be
- "ti,am3359-adc" for AM335x/AM437x SoCs
- "ti,am654-adc", "ti,am3359-adc" for AM654 SoCs
- ti,adc-channels: List of analog inputs available for ADC.
- AIN0 = 0, AIN1 = 1 and so on till AIN7 = 7.
-
-Optional properties:
-- child "tsc"
- ti,charge-delay: Length of touch screen charge delay step in terms of
- ADC clock cycles. Charge delay value should be large
- in order to avoid false pen-up events. This value
- effects the overall sampling speed, hence need to be
- kept as low as possible, while avoiding false pen-up
- event. Start from a lower value, say 0x400, and
- increase value until false pen-up events are avoided.
- The pen-up detection happens immediately after the
- charge step, so this does in fact function as a
- hardware knob for adjusting the amount of "settling
- time".
-
-- child "adc"
- ti,chan-step-opendelay: List of open delays for each channel of
- ADC in the order of ti,adc-channels. The
- value corresponds to the number of ADC
- clock cycles to wait after applying the
- step configuration registers and before
- sending the start of ADC conversion.
- Maximum value is 0x3FFFF.
- ti,chan-step-sampledelay: List of sample delays for each channel
- of ADC in the order of ti,adc-channels.
- The value corresponds to the number of
- ADC clock cycles to sample (to hold
- start of conversion high).
- Maximum value is 0xFF.
- ti,chan-step-avg: Number of averages to be performed for each
- channel of ADC. If average is 16 then input
- is sampled 16 times and averaged to get more
- accurate value. This increases the time taken
- by ADC to generate a sample. Valid range is 0
- average to 16 averages. Maximum value is 16.
-
-Example:
- tscadc: tscadc@44e0d000 {
- compatible = "ti,am3359-tscadc";
- tsc {
- ti,wires = <4>;
- ti,x-plate-resistance = <200>;
- ti,coordiante-readouts = <5>;
- ti,wire-config = <0x00 0x11 0x22 0x33>;
- ti,charge-delay = <0x400>;
- };
-
- adc {
- ti,adc-channels = <4 5 6 7>;
- ti,chan-step-opendelay = <0x098 0x3ffff 0x098 0x0>;
- ti,chan-step-sampledelay = <0xff 0x0 0xf 0x0>;
- ti,chan-step-avg = <16 2 4 8>;
- };
- }
diff --git a/Documentation/devicetree/bindings/input/touchscreen/toradex,vf50-touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/toradex,vf50-touchscreen.yaml
new file mode 100644
index 000000000000..5094c5183c74
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/toradex,vf50-touchscreen.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/toradex,vf50-touchscreen.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Toradex Colibri VF50 Touchscreen
+
+maintainers:
+ - Dmitry Torokhov <dmitry.torokhov@gmail.com>
+ - Sanchayan Maity <maitysanchayan@gmail.com>
+
+properties:
+ compatible:
+ const: toradex,vf50-touchscreen
+
+ interrupts:
+ maxItems: 1
+
+ io-channels:
+ maxItems: 4
+ description:
+ adc channels being used by the Colibri VF50 module
+ IIO ADC for Y-, X-, Y+, X+ connections
+
+ xp-gpios:
+ description: FET gate driver for input of X+
+
+ xm-gpios:
+ description: FET gate driver for input of X-
+
+ yp-gpios:
+ description: FET gate driver for input of Y+
+
+ ym-gpios:
+ description: FET gate driver for input of Y-
+
+ vf50-ts-min-pressure:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 50
+ maximum: 2000
+ description: pressure level at which to stop measuring X/Y values
+
+required:
+ - compatible
+ - io-channels
+ - xp-gpios
+ - xm-gpios
+ - yp-gpios
+ - ym-gpios
+ - interrupts
+ - vf50-ts-min-pressure
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ touchscreen {
+ compatible = "toradex,vf50-touchscreen";
+ interrupt-parent = <&gpio0>;
+ interrupts = <8 IRQ_TYPE_LEVEL_LOW>;
+ io-channels = <&adc1 0>, <&adc0 0>, <&adc0 1>, <&adc1 2>;
+ xp-gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
+ xm-gpios = <&gpio2 29 GPIO_ACTIVE_HIGH>;
+ yp-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
+ ym-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>;
+ pinctrl-names = "idle", "default";
+ pinctrl-0 = <&pinctrl_touchctrl_idle>, <&pinctrl_touchctrl_gpios>;
+ pinctrl-1 = <&pinctrl_touchctrl_default>, <&pinctrl_touchctrl_gpios>;
+ vf50-ts-min-pressure = <200>;
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
deleted file mode 100644
index e1adb902d503..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt
+++ /dev/null
@@ -1 +0,0 @@
-See touchscreen.yaml
diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
index 4b5b212c772c..7023e8c73a7b 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
@@ -4,12 +4,19 @@
$id: http://devicetree.org/schemas/input/touchscreen/touchscreen.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Common touchscreen Bindings
+title: Common touchscreen
maintainers:
- Dmitry Torokhov <dmitry.torokhov@gmail.com>
properties:
+ panel:
+ description: If this touchscreen is integrally connected to a panel, this
+ is a reference to that panel. The presence of this reference indicates
+ that the touchscreen should be power sequenced together with the panel
+ and that they may share power and/or reset signals.
+ $ref: /schemas/types.yaml#/definitions/phandle
+
touchscreen-min-x:
description: minimum x coordinate reported
$ref: /schemas/types.yaml#/definitions/uint32
@@ -80,6 +87,129 @@ properties:
touchscreen-y-plate-ohms:
description: Resistance of the Y-plate in Ohms
+ touch-overlay:
+ description: |
+ List of nodes defining segments (touch areas) on the touchscreen.
+
+ This object can be used to describe a series of segments to restrict
+ the region within touch events are reported or buttons with a specific
+ functionality.
+
+ This is of special interest if the touchscreen is shipped with a physical
+ overlay on top of it with a frame that hides some part of the original
+ touchscreen area. Printed buttons on that overlay are also a typical
+ use case.
+
+ A new touchscreen area is defined as a sub-node without a key code. If a
+ key code is defined in the sub-node, it will be interpreted as a button.
+
+ The x-origin and y-origin properties of a touchscreen area define the
+ offset of a new origin from where the touchscreen events are referenced.
+ This offset is applied to the events accordingly. The x-size and y-size
+ properties define the size of the touchscreen effective area.
+
+ The following example shows a new touchscreen area with the new origin
+ (0',0') for the touch events generated by the device.
+
+ Touchscreen (full area)
+ ┌────────────────────────────────────────┐
+ │ ┌───────────────────────────────┐ │
+ │ │ │ │
+ │ ├ y-size │ │
+ │ │ │ │
+ │ │ touchscreen area │ │
+ │ │ (no key code) │ │
+ │ │ │ │
+ │ │ x-size │ │
+ │ ┌└──────────────┴────────────────┘ │
+ │(0',0') │
+ ┌└────────────────────────────────────────┘
+ (0,0)
+
+ where (0',0') = (0+x-origin,0+y-origin)
+
+ Sub-nodes with key codes report the touch events on their surface as key
+ events instead.
+
+ The following example shows a touchscreen with a single button on it.
+
+ Touchscreen (full area)
+ ┌───────────────────────────────────┐
+ │ │
+ │ │
+ │ ┌─────────┐ │
+ │ │button 0 │ │
+ │ │KEY_POWER│ │
+ │ └─────────┘ │
+ │ │
+ │ │
+ ┌└───────────────────────────────────┘
+ (0,0)
+
+ Segments defining buttons and clipped toushcreen areas can be combined
+ as shown in the following example.
+ In that case only the events within the touchscreen area are reported
+ as touch events. Events within the button areas report their associated
+ key code. Any events outside the defined areas are ignored.
+
+ Touchscreen (full area)
+ ┌─────────┬──────────────────────────────┐
+ │ │ │
+ │ │ ┌───────────────────────┐ │
+ │ button 0│ │ │ │
+ │KEY_POWER│ │ │ │
+ │ │ │ │ │
+ ├─────────┤ │ touchscreen area │ │
+ │ │ │ (no key code) │ │
+ │ │ │ │ │
+ │ button 1│ │ │ │
+ │ KEY_INFO│ ┌└───────────────────────┘ │
+ │ │(0',0') │
+ ┌└─────────┴──────────────────────────────┘
+ (0,0)
+
+ type: object
+
+ patternProperties:
+ '^segment-':
+ type: object
+ description:
+ Each segment is represented as a sub-node.
+ properties:
+ x-origin:
+ description: horizontal origin of the node area
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ y-origin:
+ description: vertical origin of the node area
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ x-size:
+ description: horizontal resolution of the node area
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ y-size:
+ description: vertical resolution of the node area
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ label:
+ description: descriptive name of the segment
+ $ref: /schemas/types.yaml#/definitions/string
+
+ linux,code: true
+
+ required:
+ - x-origin
+ - y-origin
+ - x-size
+ - y-size
+
+ unevaluatedProperties: false
+
+ debounce-delay-us:
+ description: Minimum duration in microseconds a signal must remain stable
+ to be considered valid.
+
dependencies:
touchscreen-size-x: [ touchscreen-size-y ]
touchscreen-size-y: [ touchscreen-size-x ]
diff --git a/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt b/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt
deleted file mode 100644
index b80c04b0e5c0..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-* Texas Instruments tsc2004 and tsc2005 touchscreen controllers
-
-Required properties:
- - compatible : "ti,tsc2004" or "ti,tsc2005"
- - reg : Device address
- - interrupts : IRQ specifier
- - spi-max-frequency : Maximum SPI clocking speed of the device
- (for tsc2005)
-
-Optional properties:
- - vio-supply : Regulator specifier
- - reset-gpios : GPIO specifier for the controller reset line
- - ti,x-plate-ohms : integer, resistance of the touchscreen's X plates
- in ohm (defaults to 280)
- - ti,esd-recovery-timeout-ms : integer, if the touchscreen does not respond after
- the configured time (in milli seconds), the driver
- will reset it. This is disabled by default.
- - properties defined in touchscreen.txt
-
-Example:
-
-&i2c3 {
- tsc2004@48 {
- compatible = "ti,tsc2004";
- reg = <0x48>;
- vio-supply = <&vio>;
-
- reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>;
- interrupts-extended = <&gpio1 27 IRQ_TYPE_EDGE_RISING>;
-
- touchscreen-fuzz-x = <4>;
- touchscreen-fuzz-y = <7>;
- touchscreen-fuzz-pressure = <2>;
- touchscreen-size-x = <4096>;
- touchscreen-size-y = <4096>;
- touchscreen-max-pressure = <2048>;
-
- ti,x-plate-ohms = <280>;
- ti,esd-recovery-timeout-ms = <8000>;
- };
-}
-
-&mcspi1 {
- tsc2005@0 {
- compatible = "ti,tsc2005";
- spi-max-frequency = <6000000>;
- reg = <0>;
-
- vio-supply = <&vio>;
-
- reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; /* 104 */
- interrupts-extended = <&gpio4 4 IRQ_TYPE_EDGE_RISING>; /* 100 */
-
- touchscreen-fuzz-x = <4>;
- touchscreen-fuzz-y = <7>;
- touchscreen-fuzz-pressure = <2>;
- touchscreen-size-x = <4096>;
- touchscreen-size-y = <4096>;
- touchscreen-max-pressure = <2048>;
-
- ti,x-plate-ohms = <280>;
- ti,esd-recovery-timeout-ms = <8000>;
- };
-}
diff --git a/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt b/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt
deleted file mode 100644
index ed00f61b8c08..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/tsc2007.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-* Texas Instruments tsc2007 touchscreen controller
-
-Required properties:
-- compatible: must be "ti,tsc2007".
-- reg: I2C address of the chip.
-- ti,x-plate-ohms: X-plate resistance in ohms.
-
-Optional properties:
-- gpios: the interrupt gpio the chip is connected to (trough the penirq pin).
- The penirq pin goes to low when the panel is touched.
- (see GPIO binding[1] for more details).
-- interrupts: (gpio) interrupt to which the chip is connected
- (see interrupt binding[0]).
-- ti,max-rt: maximum pressure.
-- ti,fuzzx: specifies the absolute input fuzz x value.
- If set, it will permit noise in the data up to +- the value given to the fuzz
- parameter, that is used to filter noise from the event stream.
-- ti,fuzzy: specifies the absolute input fuzz y value.
-- ti,fuzzz: specifies the absolute input fuzz z value.
-- ti,poll-period: how much time to wait (in milliseconds) before reading again the
- values from the tsc2007.
-
-[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt
-[1]: Documentation/devicetree/bindings/gpio/gpio.txt
-
-Example:
- &i2c1 {
- /* ... */
- tsc2007@49 {
- compatible = "ti,tsc2007";
- reg = <0x49>;
- interrupt-parent = <&gpio4>;
- interrupts = <0x0 0x8>;
- gpios = <&gpio4 0 0>;
- ti,x-plate-ohms = <180>;
- };
-
- /* ... */
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/zeitec,zet6223.yaml b/Documentation/devicetree/bindings/input/touchscreen/zeitec,zet6223.yaml
new file mode 100644
index 000000000000..d5e132ec0273
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/zeitec,zet6223.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/zeitec,zet6223.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Zeitec ZET6223 touchscreen controller
+
+description:
+ Zeitec ZET6223 I2C driven touchscreen controller.
+
+maintainers:
+ - Dario Binacchi <dario.binacchi@amarulasolutions.com>
+
+allOf:
+ - $ref: touchscreen.yaml#
+
+properties:
+ compatible:
+ enum:
+ - zeitec,zet6223
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ vio-supply:
+ description: 1.8V or 3.3V VIO supply.
+
+ vcc-supply:
+ description: 3.3V VCC supply.
+
+ touchscreen-inverted-x: true
+ touchscreen-inverted-y: true
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-swapped-x-y: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@76 {
+ compatible = "zeitec,zet6223";
+ reg = <0x76>;
+ interrupt-parent = <&pio>;
+ interrupts = <6 11 IRQ_TYPE_EDGE_FALLING>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/zet6223.txt b/Documentation/devicetree/bindings/input/touchscreen/zet6223.txt
deleted file mode 100644
index 27d55a506f18..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/zet6223.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Zeitec ZET6223 I2C touchscreen controller
-
-Required properties:
-- compatible : "zeitec,zet6223"
-- reg : I2C slave address of the chip (0x76)
-- interrupts : interrupt specification for the zet6223 interrupt
-
-Optional properties:
-
-- vio-supply : Specification for VIO supply (1.8V or 3.3V,
- depending on system interface needs).
-- vcc-supply : Specification for 3.3V VCC supply.
-- touchscreen-size-x : See touchscreen.txt
-- touchscreen-size-y : See touchscreen.txt
-- touchscreen-inverted-x : See touchscreen.txt
-- touchscreen-inverted-y : See touchscreen.txt
-- touchscreen-swapped-x-y : See touchscreen.txt
-
-Example:
-
-i2c@00000000 {
-
- zet6223: touchscreen@76 {
- compatible = "zeitec,zet6223";
- reg = <0x76>;
- interrupt-parent = <&pio>;
- interrupts = <6 11 IRQ_TYPE_EDGE_FALLING>
- };
-
-};
diff --git a/Documentation/devicetree/bindings/input/touchscreen/zforce_ts.txt b/Documentation/devicetree/bindings/input/touchscreen/zforce_ts.txt
deleted file mode 100644
index e3c27c4fd9c8..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/zforce_ts.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-* Neonode infrared touchscreen controller
-
-Required properties:
-- compatible: must be "neonode,zforce"
-- reg: I2C address of the chip
-- interrupts: interrupt to which the chip is connected
-- reset-gpios: reset gpio the chip is connected to
-- x-size: horizontal resolution of touchscreen
-- y-size: vertical resolution of touchscreen
-
-Optional properties:
-- irq-gpios : interrupt gpio the chip is connected to
-- vdd-supply: Regulator controlling the controller supply
-
-Example:
-
- i2c@00000000 {
- /* ... */
-
- zforce_ts@50 {
- compatible = "neonode,zforce";
- reg = <0x50>;
- interrupts = <2 0>;
- vdd-supply = <&reg_zforce_vdd>;
-
- reset-gpios = <&gpio5 9 0>; /* RST */
- irq-gpios = <&gpio5 6 0>; /* IRQ, optional */
-
- x-size = <800>;
- y-size = <600>;
- };
-
- /* ... */
- };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml b/Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml
new file mode 100644
index 000000000000..3f663ce3e44e
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/touchscreen/zinitix,bt400.yaml
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/touchscreen/zinitix,bt400.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Zinitix BT4xx and BT5xx series touchscreen controller
+
+description: The Zinitix BT4xx and BT5xx series of touchscreen controllers
+ are Korea-produced touchscreens with embedded microcontrollers. The
+ BT4xx series was produced 2010-2013 and the BT5xx series 2013-2014.
+
+maintainers:
+ - Michael Srba <Michael.Srba@seznam.cz>
+ - Linus Walleij <linus.walleij@linaro.org>
+
+allOf:
+ - $ref: touchscreen.yaml#
+ - $ref: ../input.yaml#
+
+properties:
+ $nodename:
+ pattern: "^touchscreen(@.*)?$"
+
+ compatible:
+ enum:
+ - zinitix,bt402
+ - zinitix,bt403
+ - zinitix,bt404
+ - zinitix,bt412
+ - zinitix,bt413
+ - zinitix,bt431
+ - zinitix,bt432
+ - zinitix,bt531
+ - zinitix,bt532
+ - zinitix,bt538
+ - zinitix,bt541
+ - zinitix,bt548
+ - zinitix,bt554
+ - zinitix,at100
+
+ reg:
+ description: I2C address on the I2C bus
+
+ clock-frequency:
+ description: I2C client clock frequency, defined for host when using
+ the device on the I2C bus
+ minimum: 0
+ maximum: 400000
+
+ interrupts:
+ description: Interrupt to host
+ maxItems: 1
+
+ vcca-supply:
+ description: Analog power supply regulator on the VCCA pin
+
+ vdd-supply:
+ description: Digital power supply regulator on the VDD pin.
+ In older device trees this can be the accidental name for the analog
+ supply on the VCCA pin, and in that case the deprecated vddo-supply is
+ used for the digital power supply.
+
+ vddo-supply:
+ description: Deprecated name for the digital power supply, use vdd-supply
+ as this reflects the real name of the pin. If this supply is present,
+ the vdd-supply represents VCCA instead of VDD. Implementers should first
+ check for this property, and if it is present assume that the vdd-supply
+ represents the analog supply.
+ deprecated: true
+
+ reset-gpios:
+ description: Reset line for the touchscreen, should be tagged
+ as GPIO_ACTIVE_LOW
+
+ zinitix,mode:
+ description: Mode of reporting touch points. Some modes may not work
+ with a particular ts firmware for unknown reasons. Available modes are
+ 1 and 2. Mode 2 is the default and preferred.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2]
+
+ linux,keycodes:
+ description:
+ This property specifies an array of keycodes assigned to the
+ touch-keys that can be present in some touchscreen configurations.
+ If the touch-keys are enabled, controller firmware will assign some
+ touch sense lines to those keys.
+ minItems: 1
+ maxItems: 8
+
+ touchscreen-size-x: true
+ touchscreen-size-y: true
+ touchscreen-fuzz-x: true
+ touchscreen-fuzz-y: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - touchscreen-size-x
+ - touchscreen-size-y
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ touchscreen@20 {
+ compatible = "zinitix,bt541";
+ reg = <0x20>;
+ interrupt-parent = <&gpio>;
+ interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
+ vcca-supply = <&reg_vcca_tsp>;
+ vdd-supply = <&reg_vdd_tsp>;
+ touchscreen-size-x = <540>;
+ touchscreen-size-y = <960>;
+ zinitix,mode = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt b/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt
deleted file mode 100644
index 446efb9f5f55..000000000000
--- a/Documentation/devicetree/bindings/input/touchscreen/zinitix.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-Device tree bindings for Zinitx BT541 touchscreen controller
-
-Required properties:
-
- - compatible : Should be "zinitix,bt541"
- - reg : I2C address of the chip. Should be 0x20
- - interrupts : Interrupt to which the chip is connected
-
-Optional properties:
-
- - vdd-supply : Analog power supply regulator on VCCA pin
- - vddo-supply : Digital power supply regulator on VDD pin
- - zinitix,mode : Mode of reporting touch points. Some modes may not work
- with a particular ts firmware for unknown reasons. Available
- modes are 1 and 2. Mode 2 is the default and preferred.
-
-The touchscreen-* properties are documented in touchscreen.txt in this
-directory.
-
-Example:
-
- i2c@00000000 {
- /* ... */
-
- bt541@20 {
- compatible = "zinitix,bt541";
- reg = <0x20>;
- interrupt-parent = <&msmgpio>;
- interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
- pinctrl-names = "default";
- pinctrl-0 = <&tsp_default>;
- vdd-supply = <&reg_vdd_tsp>;
- vddo-supply = <&pm8916_l6>;
- touchscreen-size-x = <540>;
- touchscreen-size-y = <960>;
- zinitix,mode = <2>;
- };
-
- /* ... */
- };
diff --git a/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt b/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt
deleted file mode 100644
index f5021214edec..000000000000
--- a/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Texas Instruments TWL family (twl4030) pwrbutton module
-
-This module is part of the TWL4030. For more details about the whole
-chip see Documentation/devicetree/bindings/mfd/twl-family.txt.
-
-This module provides a simple power button event via an Interrupt.
-
-Required properties:
-- compatible: should be one of the following
- - "ti,twl4030-pwrbutton": For controllers compatible with twl4030
-- interrupts: should be one of the following
- - <8>: For controllers compatible with twl4030
-
-Example:
-
-&twl {
- twl_pwrbutton: pwrbutton {
- compatible = "ti,twl4030-pwrbutton";
- interrupts = <8>;
- };
-};
diff --git a/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.txt b/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.txt
deleted file mode 100644
index 43ef770dfeb9..000000000000
--- a/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Zodiac Inflight Innovations RAVE Supervisory Processor Power Button Bindings
-
-RAVE SP input device is a "MFD cell" device corresponding to power
-button functionality of RAVE Supervisory Processor. It is expected
-that its Device Tree node is specified as a child of the node
-corresponding to the parent RAVE SP device (as documented in
-Documentation/devicetree/bindings/mfd/zii,rave-sp.txt)
-
-Required properties:
-
-- compatible: Should be "zii,rave-sp-pwrbutton"
-
-Example:
-
- rave-sp {
- compatible = "zii,rave-sp-rdu1";
- current-speed = <38400>;
-
- pwrbutton {
- compatible = "zii,rave-sp-pwrbutton";
- };
- }
diff --git a/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.yaml b/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.yaml
new file mode 100644
index 000000000000..b26e6fe174f2
--- /dev/null
+++ b/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/input/zii,rave-sp-pwrbutton.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Zodiac Inflight Innovations RAVE Supervisory Processor Power Button
+
+maintainers:
+ - Frank Li <Frank.li@nxp.com>
+
+description:
+ RAVE SP input device is a "MFD cell" device corresponding to power
+ button functionality of RAVE Supervisory Processor. It is expected
+ that its Device Tree node is specified as a child of the node
+ corresponding to the parent RAVE SP device (as documented in
+ Documentation/devicetree/bindings/mfd/zii,rave-sp.yaml)
+
+properties:
+ compatible:
+ const: zii,rave-sp-pwrbutton
+
+required:
+ - compatible
+
+allOf:
+ - $ref: input.yaml
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ pwrbutton {
+ compatible = "zii,rave-sp-pwrbutton";
+ };
+
diff --git a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml
index a8873739d61a..fc21fe3e7b37 100644
--- a/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml
+++ b/Documentation/devicetree/bindings/interconnect/fsl,imx8m-noc.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Generic i.MX bus frequency device
maintainers:
- - Leonard Crestez <leonard.crestez@nxp.com>
+ - Peng Fan <peng.fan@nxp.com>
description: |
The i.MX SoC family has multiple buses for which clock frequency (and
@@ -26,14 +26,16 @@ properties:
oneOf:
- items:
- enum:
- - fsl,imx8mn-nic
- fsl,imx8mm-nic
+ - fsl,imx8mn-nic
+ - fsl,imx8mp-nic
- fsl,imx8mq-nic
- const: fsl,imx8m-nic
- items:
- enum:
- - fsl,imx8mn-noc
- fsl,imx8mm-noc
+ - fsl,imx8mn-noc
+ - fsl,imx8mp-noc
- fsl,imx8mq-noc
- const: fsl,imx8m-noc
- const: fsl,imx8m-nic
@@ -45,10 +47,11 @@ properties:
maxItems: 1
operating-points-v2: true
- opp-table: true
+ opp-table:
+ type: object
fsl,ddrc:
- $ref: "/schemas/types.yaml#/definitions/phandle"
+ $ref: /schemas/types.yaml#/definitions/phandle
description:
Phandle to DDR Controller.
@@ -81,10 +84,10 @@ examples:
noc_opp_table: opp-table {
compatible = "operating-points-v2";
- opp-133M {
+ opp-133333333 {
opp-hz = /bits/ 64 <133333333>;
};
- opp-800M {
+ opp-800000000 {
opp-hz = /bits/ 64 <800000000>;
};
};
diff --git a/Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml b/Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml
new file mode 100644
index 000000000000..4d72525f407e
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/mediatek,cci.yaml
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/mediatek,cci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Cache Coherent Interconnect (CCI) frequency and voltage scaling
+
+maintainers:
+ - Jia-Wei Chang <jia-wei.chang@mediatek.com>
+ - Johnson Wang <johnson.wang@mediatek.com>
+
+description: |
+ MediaTek Cache Coherent Interconnect (CCI) is a hardware engine used by
+ MT8183 and MT8186 SoCs to scale the frequency and adjust the voltage in
+ hardware. It can also optimize the voltage to reduce the power consumption.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8183-cci
+ - mediatek,mt8186-cci
+ - items:
+ - enum:
+ - mediatek,mt7988-cci
+ - const: mediatek,mt8183-cci
+
+ clocks:
+ items:
+ - description:
+ The multiplexer for clock input of the bus.
+ - description:
+ A parent of "bus" clock which is used as an intermediate clock source
+ when the original clock source (PLL) is under transition and not
+ stable yet.
+
+ clock-names:
+ items:
+ - const: cci
+ - const: intermediate
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+ proc-supply:
+ description:
+ Phandle of the regulator for CCI that provides the supply voltage.
+
+ sram-supply:
+ description:
+ Phandle of the regulator for sram of CCI that provides the supply
+ voltage. When it is present, the implementation needs to do
+ "voltage tracking" to step by step scale up/down Vproc and Vsram to fit
+ SoC specific needs. When absent, the voltage scaling flow is handled by
+ hardware, hence no software "voltage tracking" is needed.
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - operating-points-v2
+ - proc-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8183-clk.h>
+ cci: cci {
+ compatible = "mediatek,mt8183-cci";
+ clocks = <&mcucfg CLK_MCU_BUS_SEL>,
+ <&topckgen CLK_TOP_ARMPLL_DIV_PLL1>;
+ clock-names = "cci", "intermediate";
+ operating-points-v2 = <&cci_opp>;
+ proc-supply = <&mt6358_vproc12_reg>;
+ };
+
+ cci_opp: opp-table-cci {
+ compatible = "operating-points-v2";
+ opp-shared;
+ opp2_00: opp-273000000 {
+ opp-hz = /bits/ 64 <273000000>;
+ opp-microvolt = <650000>;
+ };
+ opp2_01: opp-338000000 {
+ opp-hz = /bits/ 64 <338000000>;
+ opp-microvolt = <687500>;
+ };
+ opp2_02: opp-403000000 {
+ opp-hz = /bits/ 64 <403000000>;
+ opp-microvolt = <718750>;
+ };
+ opp2_03: opp-463000000 {
+ opp-hz = /bits/ 64 <463000000>;
+ opp-microvolt = <756250>;
+ };
+ opp2_04: opp-546000000 {
+ opp-hz = /bits/ 64 <546000000>;
+ opp-microvolt = <800000>;
+ };
+ opp2_05: opp-624000000 {
+ opp-hz = /bits/ 64 <624000000>;
+ opp-microvolt = <818750>;
+ };
+ opp2_06: opp-689000000 {
+ opp-hz = /bits/ 64 <689000000>;
+ opp-microvolt = <850000>;
+ };
+ opp2_07: opp-767000000 {
+ opp-hz = /bits/ 64 <767000000>;
+ opp-microvolt = <868750>;
+ };
+ opp2_08: opp-845000000 {
+ opp-hz = /bits/ 64 <845000000>;
+ opp-microvolt = <893750>;
+ };
+ opp2_09: opp-871000000 {
+ opp-hz = /bits/ 64 <871000000>;
+ opp-microvolt = <906250>;
+ };
+ opp2_10: opp-923000000 {
+ opp-hz = /bits/ 64 <923000000>;
+ opp-microvolt = <931250>;
+ };
+ opp2_11: opp-962000000 {
+ opp-hz = /bits/ 64 <962000000>;
+ opp-microvolt = <943750>;
+ };
+ opp2_12: opp-1027000000 {
+ opp-hz = /bits/ 64 <1027000000>;
+ opp-microvolt = <975000>;
+ };
+ opp2_13: opp-1092000000 {
+ opp-hz = /bits/ 64 <1092000000>;
+ opp-microvolt = <1000000>;
+ };
+ opp2_14: opp-1144000000 {
+ opp-hz = /bits/ 64 <1144000000>;
+ opp-microvolt = <1025000>;
+ };
+ opp2_15: opp-1196000000 {
+ opp-hz = /bits/ 64 <1196000000>;
+ opp-microvolt = <1050000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/mediatek,mt8183-emi.yaml b/Documentation/devicetree/bindings/interconnect/mediatek,mt8183-emi.yaml
new file mode 100644
index 000000000000..017c8478b2a7
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/mediatek,mt8183-emi.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/mediatek,mt8183-emi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek External Memory Interface (EMI) Interconnect
+
+maintainers:
+ - AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
+
+description: |
+ EMI interconnect providers support system bandwidth requirements through
+ Dynamic Voltage Frequency Scaling Resource Collector (DVFSRC) hardware.
+ The provider is able to communicate with the DVFSRC through Secure Monitor
+ Call (SMC).
+
+ ICC provider ICC Nodes
+ ---- ----
+ _________ |CPU | |--- |VPU |
+ _____ | |----- ---- | ----
+ | |->| DRAM | ---- | ----
+ |DRAM |->|scheduler|----- |GPU | |--- |DISP|
+ | |->| (EMI) | ---- | ----
+ |_____|->|_________|---. ----- | ----
+ /|\ `-|MMSYS|--|--- |VDEC|
+ | ----- | ----
+ | | ----
+ | change DRAM freq |--- |VENC|
+ -------- | ----
+ SMC --> | DVFSRC | | ----
+ -------- |--- |IMG |
+ | ----
+ | ----
+ |--- |CAM |
+ ----
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt8183-emi
+ - mediatek,mt8195-emi
+
+ '#interconnect-cells':
+ const: 1
+
+required:
+ - compatible
+ - '#interconnect-cells'
+
+unevaluatedProperties: false
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml b/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml
index e23df4836c6f..eec987640b37 100644
--- a/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml
+++ b/Documentation/devicetree/bindings/interconnect/qcom,bcm-voter.yaml
@@ -45,20 +45,20 @@ additionalProperties: false
examples:
# Example 1: apps bcm_voter on SDM845 SoC should be defined inside &apps_rsc node
- # as defined in Documentation/devicetree/bindings/soc/qcom/rpmh-rsc.txt
+ # as defined in Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml
- |
- apps_bcm_voter: bcm_voter {
+ apps_bcm_voter: bcm-voter {
compatible = "qcom,bcm-voter";
};
# Example 2: disp bcm_voter on SDM845 should be defined inside &disp_rsc node
- # as defined in Documentation/devicetree/bindings/soc/qcom/rpmh-rsc.txt
+ # as defined in Documentation/devicetree/bindings/soc/qcom/qcom,rpmh-rsc.yaml
- |
#include <dt-bindings/interconnect/qcom,icc.h>
- disp_bcm_voter: bcm_voter {
+ disp_bcm_voter: bcm-voter {
compatible = "qcom,bcm-voter";
qcom,tcs-wait = <QCOM_ICC_TAG_AMC>;
};
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,glymur-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,glymur-rpmh.yaml
new file mode 100644
index 000000000000..d55a7bcf5591
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,glymur-rpmh.yaml
@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,glymur-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on GLYMUR
+
+maintainers:
+ - Raviteja Laggyshetty <raviteja.laggyshetty@oss.qualcomm.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,glymur-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,glymur-aggre1-noc
+ - qcom,glymur-aggre2-noc
+ - qcom,glymur-aggre3-noc
+ - qcom,glymur-aggre4-noc
+ - qcom,glymur-clk-virt
+ - qcom,glymur-cnoc-cfg
+ - qcom,glymur-cnoc-main
+ - qcom,glymur-hscnoc
+ - qcom,glymur-lpass-ag-noc
+ - qcom,glymur-lpass-lpiaon-noc
+ - qcom,glymur-lpass-lpicx-noc
+ - qcom,glymur-mc-virt
+ - qcom,glymur-mmss-noc
+ - qcom,glymur-nsinoc
+ - qcom,glymur-nsp-noc
+ - qcom,glymur-oobm-ss-noc
+ - qcom,glymur-pcie-east-anoc
+ - qcom,glymur-pcie-east-slv-noc
+ - qcom,glymur-pcie-west-anoc
+ - qcom,glymur-pcie-west-slv-noc
+ - qcom,glymur-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 4
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,glymur-clk-virt
+ - qcom,glymur-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,glymur-pcie-west-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre PCIE_3A WEST AXI clock
+ - description: aggre PCIE_3B WEST AXI clock
+ - description: aggre PCIE_4 WEST AXI clock
+ - description: aggre PCIE_6 WEST AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,glymur-pcie-east-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre PCIE_5 EAST AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,glymur-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre USB3 TERT AXI clock
+ - description: aggre USB4_2 AXI clock
+ - description: aggre UFS PHY AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,glymur-aggre4-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre USB3 PRIM AXI clock
+ - description: aggre USB3 SEC AXI clock
+ - description: aggre USB4_0 AXI clock
+ - description: aggre USB4_1 AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,glymur-pcie-west-anoc
+ - qcom,glymur-pcie-east-anoc
+ - qcom,glymur-aggre2-noc
+ - qcom,glymur-aggre4-noc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,glymur-gcc.h>
+ clk_virt: interconnect-0 {
+ compatible = "qcom,glymur-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@16e0000 {
+ compatible = "qcom,glymur-aggre1-noc";
+ reg = <0x016e0000 0x14400>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre4_noc: interconnect@1740000 {
+ compatible = "qcom,glymur-aggre4-noc";
+ reg = <0x01740000 0x14400>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ clocks = <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB3_SEC_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB4_0_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB4_1_AXI_CLK>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,kaanapali-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,kaanapali-rpmh.yaml
new file mode 100644
index 000000000000..2c3b2fd81a74
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,kaanapali-rpmh.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,kaanapali-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on Kaanapali
+
+maintainers:
+ - Raviteja Laggyshetty <raviteja.laggyshetty@oss.qualcomm.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,kaanapali-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,kaanapali-aggre-noc
+ - qcom,kaanapali-clk-virt
+ - qcom,kaanapali-cnoc-main
+ - qcom,kaanapali-cnoc-cfg
+ - qcom,kaanapali-gem-noc
+ - qcom,kaanapali-lpass-ag-noc
+ - qcom,kaanapali-lpass-lpiaon-noc
+ - qcom,kaanapali-lpass-lpicx-noc
+ - qcom,kaanapali-mc-virt
+ - qcom,kaanapali-mmss-noc
+ - qcom,kaanapali-nsp-noc
+ - qcom,kaanapali-pcie-anoc
+ - qcom,kaanapali-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 2
+ maxItems: 3
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,kaanapali-clk-virt
+ - qcom,kaanapali-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,kaanapali-pcie-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe AXI clock
+ - description: cfg-NOC PCIe a-NOC AHB clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,kaanapali-aggre-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre USB3 PRIM AXI clock
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,kaanapali-aggre-noc
+ - qcom,kaanapali-pcie-anoc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ clk_virt: interconnect-0 {
+ compatible = "qcom,kaanapali-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre_noc: interconnect@16e0000 {
+ compatible = "qcom,kaanapali-aggre-noc";
+ reg = <0x016e0000 0x42400>;
+ #interconnect-cells = <2>;
+ clocks = <&gcc_aggre_ufs_phy_axi_clk>,
+ <&gcc_aggre_usb3_prim_axi_clk>,
+ <&rpmhcc_ipa_clk>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,milos-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,milos-rpmh.yaml
new file mode 100644
index 000000000000..00b7a4108d45
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,milos-rpmh.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,milos-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on Milos SoC
+
+maintainers:
+ - Luca Weiss <luca.weiss@fairphone.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,milos-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,milos-aggre1-noc
+ - qcom,milos-aggre2-noc
+ - qcom,milos-clk-virt
+ - qcom,milos-cnoc-cfg
+ - qcom,milos-cnoc-main
+ - qcom,milos-gem-noc
+ - qcom,milos-lpass-ag-noc
+ - qcom,milos-mc-virt
+ - qcom,milos-mmss-noc
+ - qcom,milos-nsp-noc
+ - qcom,milos-pcie-anoc
+ - qcom,milos-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,milos-clk-virt
+ - qcom,milos-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,milos-pcie-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe AXI clock
+ - description: cfg-NOC PCIe a-NOC AHB clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,milos-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre USB3 PRIM AXI clock
+ - description: aggre UFS PHY AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,milos-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,milos-aggre1-noc
+ - qcom,milos-aggre2-noc
+ - qcom,milos-pcie-anoc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,milos-gcc.h>
+
+ interconnect-0 {
+ compatible = "qcom,milos-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ interconnect@16e0000 {
+ compatible = "qcom,milos-aggre1-noc";
+ reg = <0x016e0000 0x16400>;
+ #interconnect-cells = <2>;
+ clocks = <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>,
+ <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml
new file mode 100644
index 000000000000..534644cccdcb
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,msm8939.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm MSM8937/MSM8939/MSM8976 Network-On-Chip interconnect
+
+maintainers:
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description:
+ The Qualcomm MSM8937/MSM8939/MSM8976 interconnect providers support
+ adjusting the bandwidth requirements between the various NoC fabrics.
+
+allOf:
+ - $ref: qcom,rpm-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - qcom,msm8937-bimc
+ - qcom,msm8937-pcnoc
+ - qcom,msm8937-snoc
+ - qcom,msm8939-bimc
+ - qcom,msm8939-pcnoc
+ - qcom,msm8939-snoc
+ - qcom,msm8976-bimc
+ - qcom,msm8976-pcnoc
+ - qcom,msm8976-snoc
+
+ reg:
+ maxItems: 1
+
+patternProperties:
+ '^interconnect-[a-z0-9\-]+$':
+ type: object
+ $ref: qcom,rpm-common.yaml#
+ description:
+ The interconnect providers do not have a separate QoS register space,
+ but share parent's space.
+
+ allOf:
+ - $ref: qcom,rpm-common.yaml#
+
+ properties:
+ compatible:
+ enum:
+ - qcom,msm8937-snoc-mm
+ - qcom,msm8939-snoc-mm
+ - qcom,msm8976-snoc-mm
+
+ required:
+ - compatible
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+
+ snoc: interconnect@580000 {
+ compatible = "qcom,msm8939-snoc";
+ reg = <0x00580000 0x14000>;
+ #interconnect-cells = <1>;
+
+ snoc_mm: interconnect-snoc {
+ compatible = "qcom,msm8939-snoc-mm";
+ #interconnect-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8953.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8953.yaml
new file mode 100644
index 000000000000..56cdb77b369a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8953.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,msm8953.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm MSM8953 Network-On-Chip interconnect
+
+maintainers:
+ - Barnabas Czeman <barnabas.czeman@mainlining.org>
+
+description: |
+ The Qualcomm MSM8953 interconnect providers support adjusting the
+ bandwidth requirements between the various NoC fabrics.
+
+ See also: include/dt-bindings/interconnect/qcom,msm8953.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,msm8953-bimc
+ - qcom,msm8953-pcnoc
+ - qcom,msm8953-snoc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ maxItems: 1
+
+ '#interconnect-cells':
+ const: 2
+
+patternProperties:
+ '^interconnect-[a-z0-9\-]+$':
+ type: object
+ $ref: qcom,rpm-common.yaml#
+ unevaluatedProperties: false
+ description:
+ The interconnect providers do not have a separate QoS register space,
+ but share parent's space.
+
+ properties:
+ compatible:
+ const: qcom,msm8953-snoc-mm
+
+ required:
+ - compatible
+ - '#interconnect-cells'
+
+required:
+ - compatible
+ - reg
+ - '#interconnect-cells'
+
+allOf:
+ - $ref: qcom,rpm-common.yaml#
+ - if:
+ properties:
+ compatible:
+ const: qcom,msm8953-pcnoc
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: PCNOC USB3 AXI Clock.
+
+ clock-names:
+ const: pcnoc_usb3_axi
+
+ required:
+ - clocks
+ - clock-names
+ else:
+ properties:
+ clocks: false
+ clock-names: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-msm8953.h>
+
+ interconnect@580000 {
+ compatible = "qcom,msm8953-snoc";
+ reg = <0x580000 0x16080>;
+
+ #interconnect-cells = <2>;
+
+ interconnect-snoc {
+ compatible = "qcom,msm8953-snoc-mm";
+
+ #interconnect-cells = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8974.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8974.yaml
index 8004c4baf397..95ce25ce1f7d 100644
--- a/Documentation/devicetree/bindings/interconnect/qcom,msm8974.yaml
+++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8974.yaml
@@ -50,13 +50,13 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/clock/qcom,rpmcc.h>
-
- bimc: interconnect@fc380000 {
- reg = <0xfc380000 0x6a000>;
- compatible = "qcom,msm8974-bimc";
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_BIMC_CLK>,
- <&rpmcc RPM_SMD_BIMC_A_CLK>;
- };
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+
+ interconnect@fc380000 {
+ reg = <0xfc380000 0x6a000>;
+ compatible = "qcom,msm8974-bimc";
+ #interconnect-cells = <1>;
+ clock-names = "bus", "bus_a";
+ clocks = <&rpmcc RPM_SMD_BIMC_CLK>,
+ <&rpmcc RPM_SMD_BIMC_A_CLK>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml
new file mode 100644
index 000000000000..e3f964aaad1b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml
@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,msm8996.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm MSM8996 Network-On-Chip interconnect
+
+maintainers:
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description: |
+ The Qualcomm MSM8996 interconnect providers support adjusting the
+ bandwidth requirements between the various NoC fabrics.
+
+properties:
+ compatible:
+ enum:
+ - qcom,msm8996-a0noc
+ - qcom,msm8996-a1noc
+ - qcom,msm8996-a2noc
+ - qcom,msm8996-bimc
+ - qcom,msm8996-cnoc
+ - qcom,msm8996-mnoc
+ - qcom,msm8996-pnoc
+ - qcom,msm8996-snoc
+
+ reg:
+ maxItems: 1
+
+ clock-names:
+ minItems: 1
+ maxItems: 3
+
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+allOf:
+ - $ref: qcom,rpm-common.yaml#
+ - if:
+ properties:
+ compatible:
+ const: qcom,msm8996-a0noc
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: Aggregate0 System NoC AXI Clock.
+ - description: Aggregate0 Config NoC AHB Clock.
+ - description: Aggregate0 NoC MPU Clock.
+
+ clock-names:
+ items:
+ - const: aggre0_snoc_axi
+ - const: aggre0_cnoc_ahb
+ - const: aggre0_noc_mpu_cfg
+
+ required:
+ - power-domains
+
+ - if:
+ properties:
+ compatible:
+ const: qcom,msm8996-mnoc
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: CPU-NoC High-performance Bus Clock.
+
+ clock-names:
+ const: iface
+
+ - if:
+ properties:
+ compatible:
+ const: qcom,msm8996-a2noc
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: Aggregate2 NoC UFS AXI Clock
+ - description: UFS AXI Clock
+
+ clock-names:
+ items:
+ - const: aggre2_ufs_axi
+ - const: ufs_axi
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-msm8996.h>
+ #include <dt-bindings/clock/qcom,mmcc-msm8996.h>
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+
+ bimc: interconnect@408000 {
+ compatible = "qcom,msm8996-bimc";
+ reg = <0x00408000 0x5a000>;
+ #interconnect-cells = <1>;
+ };
+
+ a0noc: interconnect@543000 {
+ compatible = "qcom,msm8996-a0noc";
+ reg = <0x00543000 0x6000>;
+ #interconnect-cells = <1>;
+ clocks = <&gcc GCC_AGGRE0_SNOC_AXI_CLK>,
+ <&gcc GCC_AGGRE0_CNOC_AHB_CLK>,
+ <&gcc GCC_AGGRE0_NOC_MPU_CFG_AHB_CLK>;
+ clock-names = "aggre0_snoc_axi",
+ "aggre0_cnoc_ahb",
+ "aggre0_noc_mpu_cfg";
+ power-domains = <&gcc AGGRE0_NOC_GDSC>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml
new file mode 100644
index 000000000000..17b09292000e
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,msm8998-bwmon.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Interconnect Bandwidth Monitor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ Bandwidth Monitor measures current throughput on buses between various NoC
+ fabrics and provides information when it crosses configured thresholds.
+
+ Certain SoCs might have more than one Bandwidth Monitors, for example on SDM845::
+ - Measuring the bandwidth between CPUs and Last Level Cache Controller -
+ called just BWMON,
+ - Measuring the bandwidth between Last Level Cache Controller and memory
+ (DDR) - called LLCC BWMON.
+
+properties:
+ compatible:
+ oneOf:
+ - const: qcom,msm8998-bwmon # BWMON v4
+ - items:
+ - enum:
+ - qcom,kaanapali-cpu-bwmon
+ - qcom,qcm2290-cpu-bwmon
+ - qcom,qcs615-cpu-bwmon
+ - qcom,qcs8300-cpu-bwmon
+ - qcom,sa8775p-cpu-bwmon
+ - qcom,sc7180-cpu-bwmon
+ - qcom,sc7280-cpu-bwmon
+ - qcom,sc8280xp-cpu-bwmon
+ - qcom,sdm845-cpu-bwmon
+ - qcom,sm6115-cpu-bwmon
+ - qcom,sm6350-llcc-bwmon
+ - qcom,sm8250-cpu-bwmon
+ - qcom,sm8550-cpu-bwmon
+ - qcom,sm8650-cpu-bwmon
+ - qcom,sm8750-cpu-bwmon
+ - qcom,x1e80100-cpu-bwmon
+ - const: qcom,sdm845-bwmon # BWMON v4, unified register space
+ - items:
+ - enum:
+ - qcom,qcs615-llcc-bwmon
+ - qcom,qcs8300-llcc-bwmon
+ - qcom,sa8775p-llcc-bwmon
+ - qcom,sc7180-llcc-bwmon
+ - qcom,sc8280xp-llcc-bwmon
+ - qcom,sm6350-cpu-bwmon
+ - qcom,sm8250-llcc-bwmon
+ - qcom,sm8550-llcc-bwmon
+ - qcom,sm8650-llcc-bwmon
+ - qcom,x1e80100-llcc-bwmon
+ - const: qcom,sc7280-llcc-bwmon
+ - const: qcom,sc7280-llcc-bwmon # BWMON v5
+ - const: qcom,sdm845-llcc-bwmon # BWMON v5
+
+ interconnects:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+ reg:
+ # BWMON v5 uses one register address space, v1-v4 use one or two.
+ minItems: 1
+ maxItems: 2
+
+ reg-names:
+ minItems: 1
+ maxItems: 2
+
+ nonposted-mmio: true
+
+required:
+ - compatible
+ - interconnects
+ - interrupts
+ - operating-points-v2
+ - reg
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ const: qcom,msm8998-bwmon
+ then:
+ properties:
+ reg:
+ minItems: 2
+
+ reg-names:
+ items:
+ - const: monitor
+ - const: global
+
+ else:
+ properties:
+ reg:
+ maxItems: 1
+
+ reg-names:
+ maxItems: 1
+
+examples:
+ - |
+ #include <dt-bindings/interconnect/qcom,sdm845.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ pmu@1436400 {
+ compatible = "qcom,sdm845-cpu-bwmon", "qcom,sdm845-bwmon";
+ reg = <0x01436400 0x600>;
+ interrupts = <GIC_SPI 581 IRQ_TYPE_LEVEL_HIGH>;
+ interconnects = <&gladiator_noc MASTER_APPSS_PROC 3 &mem_noc SLAVE_LLCC 3>;
+
+ operating-points-v2 = <&cpu_bwmon_opp_table>;
+
+ cpu_bwmon_opp_table: opp-table {
+ compatible = "operating-points-v2";
+ opp-0 {
+ opp-peak-kBps = <4800000>;
+ };
+ opp-1 {
+ opp-peak-kBps = <9216000>;
+ };
+ opp-2 {
+ opp-peak-kBps = <15052800>;
+ };
+ opp-3 {
+ opp-peak-kBps = <20889600>;
+ };
+ opp-4 {
+ opp-peak-kBps = <25497600>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml
index d6a95c3cb26f..4b9b98fbe8f2 100644
--- a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml
+++ b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm Operating State Manager (OSM) L3 Interconnect Provider
maintainers:
- - Sibi Sankar <sibis@codeaurora.org>
+ - Sibi Sankar <quic_sibis@quicinc.com>
description:
L3 cache bandwidth requirements on Qualcomm SoCs is serviced by the OSM.
@@ -16,11 +16,36 @@ description:
properties:
compatible:
- enum:
- - qcom,sc7180-osm-l3
- - qcom,sdm845-osm-l3
- - qcom,sm8150-osm-l3
- - qcom,sm8250-epss-l3
+ oneOf:
+ - items:
+ - enum:
+ - qcom,sc7180-osm-l3
+ - qcom,sc8180x-osm-l3
+ - qcom,sdm670-osm-l3
+ - qcom,sdm845-osm-l3
+ - qcom,sm6350-osm-l3
+ - qcom,sm8150-osm-l3
+ - const: qcom,osm-l3
+ - items:
+ - enum:
+ - qcom,sa8775p-epss-l3
+ - qcom,sc7280-epss-l3
+ - qcom,sc8280xp-epss-l3
+ - qcom,sm6375-cpucp-l3
+ - qcom,sm8250-epss-l3
+ - qcom,sm8350-epss-l3
+ - qcom,sm8650-epss-l3
+ - const: qcom,epss-l3
+ - items:
+ - enum:
+ - qcom,qcs8300-epss-l3
+ - const: qcom,sa8775p-epss-l3
+ - const: qcom,epss-l3
+ - items:
+ - enum:
+ - qcom,qcs615-osm-l3
+ - const: qcom,sm8150-osm-l3
+ - const: qcom,osm-l3
reg:
maxItems: 1
@@ -54,7 +79,7 @@ examples:
#define RPMH_CXO_CLK 0
osm_l3: interconnect@17d41000 {
- compatible = "qcom,sdm845-osm-l3";
+ compatible = "qcom,sdm845-osm-l3", "qcom,osm-l3";
reg = <0x17d41000 0x1400>;
clocks = <&rpmhcc RPMH_CXO_CLK>, <&gcc GPLL0>;
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml
new file mode 100644
index 000000000000..b6c15314c5c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,qcm2290.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm QCM2290 Network-On-Chip interconnect
+
+maintainers:
+ - Shawn Guo <shawn.guo@linaro.org>
+
+description: |
+ The Qualcomm QCM2290 interconnect providers support adjusting the
+ bandwidth requirements between the various NoC fabrics.
+
+allOf:
+ - $ref: qcom,rpm-common.yaml#
+
+properties:
+ reg:
+ maxItems: 1
+
+ compatible:
+ enum:
+ - qcom,qcm2290-bimc
+ - qcom,qcm2290-cnoc
+ - qcom,qcm2290-snoc
+
+# Child node's properties
+patternProperties:
+ '^interconnect-[a-z0-9]+$':
+ type: object
+ description:
+ The interconnect providers do not have a separate QoS register space,
+ but share parent's space.
+
+ allOf:
+ - $ref: qcom,rpm-common.yaml#
+
+ properties:
+ compatible:
+ enum:
+ - qcom,qcm2290-qup-virt
+ - qcom,qcm2290-mmrt-virt
+ - qcom,qcm2290-mmnrt-virt
+
+ required:
+ - compatible
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+
+ snoc: interconnect@1880000 {
+ compatible = "qcom,qcm2290-snoc";
+ reg = <0x01880000 0x60200>;
+ #interconnect-cells = <1>;
+
+ qup_virt: interconnect-qup {
+ compatible = "qcom,qcm2290-qup-virt";
+ #interconnect-cells = <1>;
+ };
+
+ mmnrt_virt: interconnect-mmnrt {
+ compatible = "qcom,qcm2290-mmnrt-virt";
+ #interconnect-cells = <1>;
+ };
+
+ mmrt_virt: interconnect-mmrt {
+ compatible = "qcom,qcm2290-mmrt-virt";
+ #interconnect-cells = <1>;
+ };
+ };
+
+ cnoc: interconnect@1900000 {
+ compatible = "qcom,qcm2290-cnoc";
+ reg = <0x01900000 0x8200>;
+ #interconnect-cells = <1>;
+ };
+
+ bimc: interconnect@4480000 {
+ compatible = "qcom,qcm2290-bimc";
+ reg = <0x04480000 0x80000>;
+ #interconnect-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcs615-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qcs615-rpmh.yaml
new file mode 100644
index 000000000000..9d762b2a1fcf
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,qcs615-rpmh.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,qcs615-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on QCS615
+
+maintainers:
+ - Raviteja Laggyshetty <quic_rlaggysh@quicinc.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,qcs615-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,qcs615-aggre1-noc
+ - qcom,qcs615-camnoc-virt
+ - qcom,qcs615-config-noc
+ - qcom,qcs615-dc-noc
+ - qcom,qcs615-gem-noc
+ - qcom,qcs615-ipa-virt
+ - qcom,qcs615-mc-virt
+ - qcom,qcs615-mmss-noc
+ - qcom,qcs615-system-noc
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,qcs615-camnoc-virt
+ - qcom,qcs615-ipa-virt
+ - qcom,qcs615-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ gem_noc: interconnect@9680000 {
+ compatible = "qcom,qcs615-gem-noc";
+ reg = <0x9680000 0x3e200>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ mc_virt: interconnect-2 {
+ compatible = "qcom,qcs615-mc-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcs8300-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qcs8300-rpmh.yaml
new file mode 100644
index 000000000000..e9f528d6d9a8
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,qcs8300-rpmh.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,qcs8300-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on QCS8300
+
+maintainers:
+ - Raviteja Laggyshetty <quic_rlaggysh@quicinc.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM).
+
+ See also: include/dt-bindings/interconnect/qcom,qcs8300-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,qcs8300-aggre1-noc
+ - qcom,qcs8300-aggre2-noc
+ - qcom,qcs8300-clk-virt
+ - qcom,qcs8300-config-noc
+ - qcom,qcs8300-dc-noc
+ - qcom,qcs8300-gem-noc
+ - qcom,qcs8300-gpdsp-anoc
+ - qcom,qcs8300-lpass-ag-noc
+ - qcom,qcs8300-mc-virt
+ - qcom,qcs8300-mmss-noc
+ - qcom,qcs8300-nspa-noc
+ - qcom,qcs8300-pcie-anoc
+ - qcom,qcs8300-system-noc
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,qcs8300-clk-virt
+ - qcom,qcs8300-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ gem_noc: interconnect@9100000 {
+ compatible = "qcom,qcs8300-gem-noc";
+ reg = <0x9100000 0xf7080>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ clk_virt: interconnect-0 {
+ compatible = "qcom,qcs8300-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml
new file mode 100644
index 000000000000..0070b0396e31
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,qdu1000-rpmh.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,qdu1000-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on QDU1000
+
+maintainers:
+ - Georgi Djakov <djakov@kernel.org>
+ - Odelu Kukatla <quic_okukatla@quicinc.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+properties:
+ compatible:
+ enum:
+ - qcom,qdu1000-clk-virt
+ - qcom,qdu1000-gem-noc
+ - qcom,qdu1000-mc-virt
+ - qcom,qdu1000-system-noc
+
+ '#interconnect-cells': true
+
+ reg:
+ maxItems: 1
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,qdu1000-clk-virt
+ - qcom,qdu1000-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interconnect/qcom,qdu1000-rpmh.h>
+
+ system_noc: interconnect@1640000 {
+ compatible = "qcom,qdu1000-system-noc";
+ reg = <0x1640000 0x45080>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ clk_virt: interconnect-0 {
+ compatible = "qcom,qdu1000-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml
new file mode 100644
index 000000000000..1ea52b091609
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,rpm-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect
+
+maintainers:
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description:
+ RPM interconnect providers support for managing system bandwidth requirements
+ through manual requests based on either predefined values or as indicated by
+ the bus monitor hardware. Each provider node represents a NoC bus master,
+ driven by a dedicated clock source.
+
+properties:
+ '#interconnect-cells':
+ oneOf:
+ - const: 2
+ - const: 1
+ deprecated: true
+
+required:
+ - '#interconnect-cells'
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml
index 983d71fb5399..01d436d4a553 100644
--- a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml
+++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml
@@ -7,79 +7,44 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm RPM Network-On-Chip Interconnect
maintainers:
- - Georgi Djakov <georgi.djakov@linaro.org>
+ - Georgi Djakov <djakov@kernel.org>
description: |
RPM interconnect providers support system bandwidth requirements through
RPM processor. The provider is able to communicate with the RPM through
the RPM shared memory device.
+allOf:
+ - $ref: qcom,rpm-common.yaml#
+
properties:
reg:
maxItems: 1
compatible:
enum:
+ - qcom,msm8909-bimc
+ - qcom,msm8909-pcnoc
+ - qcom,msm8909-snoc
- qcom,msm8916-bimc
- qcom,msm8916-pcnoc
- qcom,msm8916-snoc
- - qcom,msm8939-bimc
- - qcom,msm8939-pcnoc
- - qcom,msm8939-snoc
- - qcom,msm8939-snoc-mm
- qcom,qcs404-bimc
- qcom,qcs404-pcnoc
- qcom,qcs404-snoc
- '#interconnect-cells':
- const: 1
-
- clock-names:
- items:
- - const: bus
- - const: bus_a
-
- clocks:
- items:
- - description: Bus Clock
- - description: Bus A Clock
-
required:
- compatible
- reg
- - '#interconnect-cells'
- - clock-names
- - clocks
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/clock/qcom,rpmcc.h>
-
- bimc: interconnect@400000 {
- compatible = "qcom,msm8916-bimc";
- reg = <0x00400000 0x62000>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_BIMC_CLK>,
- <&rpmcc RPM_SMD_BIMC_A_CLK>;
- };
-
- pcnoc: interconnect@500000 {
- compatible = "qcom,msm8916-pcnoc";
- reg = <0x00500000 0x11000>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_PCNOC_CLK>,
- <&rpmcc RPM_SMD_PCNOC_A_CLK>;
- };
+ #include <dt-bindings/clock/qcom,rpmcc.h>
- snoc: interconnect@580000 {
- compatible = "qcom,msm8916-snoc";
- reg = <0x00580000 0x14000>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_SNOC_CLK>,
- <&rpmcc RPM_SMD_SNOC_A_CLK>;
- };
+ interconnect@400000 {
+ compatible = "qcom,msm8916-bimc";
+ reg = <0x00400000 0x62000>;
+ #interconnect-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh-common.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh-common.yaml
new file mode 100644
index 000000000000..bbeb0541536b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh-common.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,rpmh-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect
+
+maintainers:
+ - Georgi Djakov <djakov@kernel.org>
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+description:
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+properties:
+ '#interconnect-cells':
+ enum: [ 1, 2 ]
+
+ qcom,bcm-voters:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ maxItems: 1
+ maxItems: 2
+ description:
+ List of phandles to qcom,bcm-voter nodes that are required by
+ this interconnect to send RPMh commands.
+
+ qcom,bcm-voter-names:
+ maxItems: 2
+ description:
+ Names for each of the qcom,bcm-voters specified.
+
+required:
+ - '#interconnect-cells'
+ - qcom,bcm-voters
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml
index 5accc0d113be..da16d8e9bdc5 100644
--- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml
+++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml
@@ -8,7 +8,7 @@ title: Qualcomm RPMh Network-On-Chip Interconnect
maintainers:
- Georgi Djakov <georgi.djakov@linaro.org>
- - Odelu Kukatla <okukatla@codeaurora.org>
+ - Odelu Kukatla <quic_okukatla@quicinc.com>
description: |
RPMh interconnect providers support system bandwidth requirements through
@@ -31,24 +31,30 @@ properties:
- qcom,sc7180-config-noc
- qcom,sc7180-dc-noc
- qcom,sc7180-gem-noc
- - qcom,sc7180-ipa-virt
- qcom,sc7180-mc-virt
- qcom,sc7180-mmss-noc
- qcom,sc7180-npu-noc
- qcom,sc7180-qup-virt
- qcom,sc7180-system-noc
- - qcom,sc7280-aggre1-noc
- - qcom,sc7280-aggre2-noc
- - qcom,sc7280-clk-virt
- - qcom,sc7280-cnoc2
- - qcom,sc7280-cnoc3
- - qcom,sc7280-dc-noc
- - qcom,sc7280-gem-noc
- - qcom,sc7280-lpass-ag-noc
- - qcom,sc7280-mc-virt
- - qcom,sc7280-mmss-noc
- - qcom,sc7280-nsp-noc
- - qcom,sc7280-system-noc
+ - qcom,sc8180x-aggre1-noc
+ - qcom,sc8180x-aggre2-noc
+ - qcom,sc8180x-camnoc-virt
+ - qcom,sc8180x-compute-noc
+ - qcom,sc8180x-config-noc
+ - qcom,sc8180x-dc-noc
+ - qcom,sc8180x-gem-noc
+ - qcom,sc8180x-mc-virt
+ - qcom,sc8180x-mmss-noc
+ - qcom,sc8180x-qup-virt
+ - qcom,sc8180x-system-noc
+ - qcom,sdm670-aggre1-noc
+ - qcom,sdm670-aggre2-noc
+ - qcom,sdm670-config-noc
+ - qcom,sdm670-dc-noc
+ - qcom,sdm670-gladiator-noc
+ - qcom,sdm670-mem-noc
+ - qcom,sdm670-mmss-noc
+ - qcom,sdm670-system-noc
- qcom,sdm845-aggre1-noc
- qcom,sdm845-aggre2-noc
- qcom,sdm845-config-noc
@@ -57,18 +63,19 @@ properties:
- qcom,sdm845-mem-noc
- qcom,sdm845-mmss-noc
- qcom,sdm845-system-noc
- - qcom,sdx55-ipa-virt
- qcom,sdx55-mc-virt
- qcom,sdx55-mem-noc
- qcom,sdx55-system-noc
+ - qcom,sdx65-mc-virt
+ - qcom,sdx65-mem-noc
+ - qcom,sdx65-system-noc
- qcom,sm8150-aggre1-noc
- qcom,sm8150-aggre2-noc
- - qcom,sm8150-camnoc-noc
+ - qcom,sm8150-camnoc-virt
- qcom,sm8150-compute-noc
- qcom,sm8150-config-noc
- qcom,sm8150-dc-noc
- qcom,sm8150-gem-noc
- - qcom,sm8150-ipa-virt
- qcom,sm8150-mc-virt
- qcom,sm8150-mmss-noc
- qcom,sm8150-system-noc
@@ -78,10 +85,10 @@ properties:
- qcom,sm8250-config-noc
- qcom,sm8250-dc-noc
- qcom,sm8250-gem-noc
- - qcom,sm8250-ipa-virt
- qcom,sm8250-mc-virt
- qcom,sm8250-mmss-noc
- qcom,sm8250-npu-noc
+ - qcom,sm8250-qup-virt
- qcom,sm8250-system-noc
- qcom,sm8350-aggre1-noc
- qcom,sm8350-aggre2-noc
@@ -94,42 +101,44 @@ properties:
- qcom,sm8350-compute-noc
- qcom,sm8350-system-noc
- '#interconnect-cells':
- enum: [ 1, 2 ]
-
- qcom,bcm-voters:
- $ref: /schemas/types.yaml#/definitions/phandle-array
- description: |
- List of phandles to qcom,bcm-voter nodes that are required by
- this interconnect to send RPMh commands.
-
- qcom,bcm-voter-names:
- description: |
- Names for each of the qcom,bcm-voters specified.
+ '#interconnect-cells': true
required:
- compatible
- - reg
- - '#interconnect-cells'
- - qcom,bcm-voters
-additionalProperties: false
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ not:
+ properties:
+ compatible:
+ enum:
+ - qcom,sc8180x-camnoc-virt
+ - qcom,sc8180x-mc-virt
+ - qcom,sc8180x-qup-virt
+ - qcom,sdx65-mc-virt
+ - qcom,sm8250-qup-virt
+ then:
+ required:
+ - reg
+
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interconnect/qcom,sdm845.h>
+ #include <dt-bindings/interconnect/qcom,sdm845.h>
- mem_noc: interconnect@1380000 {
- compatible = "qcom,sdm845-mem-noc";
- reg = <0x01380000 0x27200>;
- #interconnect-cells = <1>;
- qcom,bcm-voters = <&apps_bcm_voter>;
- };
+ interconnect@1380000 {
+ compatible = "qcom,sdm845-mem-noc";
+ reg = <0x01380000 0x27200>;
+ #interconnect-cells = <1>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
- mmss_noc: interconnect@1740000 {
- compatible = "qcom,sdm845-mmss-noc";
- reg = <0x01740000 0x1c1000>;
- #interconnect-cells = <1>;
- qcom,bcm-voter-names = "apps", "disp";
- qcom,bcm-voters = <&apps_bcm_voter>, <&disp_bcm_voter>;
- };
+ interconnect@1740000 {
+ compatible = "qcom,sdm845-mmss-noc";
+ reg = <0x01740000 0x1c1000>;
+ #interconnect-cells = <1>;
+ qcom,bcm-voter-names = "apps", "disp";
+ qcom,bcm-voters = <&apps_bcm_voter>, <&disp_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml
new file mode 100644
index 000000000000..71428d2cce18
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sa8775p-rpmh.yaml
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sa8775p-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SA8775P
+
+maintainers:
+ - Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM).
+
+ See also: include/dt-bindings/interconnect/qcom,sa8775p.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sa8775p-aggre1-noc
+ - qcom,sa8775p-aggre2-noc
+ - qcom,sa8775p-clk-virt
+ - qcom,sa8775p-config-noc
+ - qcom,sa8775p-dc-noc
+ - qcom,sa8775p-gem-noc
+ - qcom,sa8775p-gpdsp-anoc
+ - qcom,sa8775p-lpass-ag-noc
+ - qcom,sa8775p-mc-virt
+ - qcom,sa8775p-mmss-noc
+ - qcom,sa8775p-nspa-noc
+ - qcom,sa8775p-nspb-noc
+ - qcom,sa8775p-pcie-anoc
+ - qcom,sa8775p-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 2
+ maxItems: 5
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sa8775p-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre QUP PRIM AXI clock
+ - description: aggre USB2 PRIM AXI clock
+ - description: aggre USB3 PRIM AXI clock
+ - description: aggre USB3 SEC AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sa8775p-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS CARD AXI clock
+ - description: RPMH CC IPA clock
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,sa8775p-gcc.h>
+ clk_virt: interconnect-clk-virt {
+ compatible = "qcom,sa8775p-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@16c0000 {
+ compatible = "qcom,sa8775p-aggre1-noc";
+ reg = <0x016c0000 0x18080>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ clocks = <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>,
+ <&gcc GCC_AGGRE_NOC_QUPV3_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB2_PRIM_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB3_SEC_AXI_CLK>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sar2130p-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sar2130p-rpmh.yaml
new file mode 100644
index 000000000000..f5d3d0c5df73
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sar2130p-rpmh.yaml
@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sar2130p-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SAR2130P
+
+maintainers:
+ - Dmitry Baryshkov <dmitry.baryshkov@linaro.org>
+ - Georgi Djakov <djakov@kernel.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,sar2130p-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sar2130p-clk-virt
+ - qcom,sar2130p-config-noc
+ - qcom,sar2130p-gem-noc
+ - qcom,sar2130p-lpass-ag-noc
+ - qcom,sar2130p-mc-virt
+ - qcom,sar2130p-mmss-noc
+ - qcom,sar2130p-nsp-noc
+ - qcom,sar2130p-pcie-anoc
+ - qcom,sar2130p-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sar2130p-clk-virt
+ - qcom,sar2130p-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sar2130p-pcie-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe AXI clock
+ - description: cfg-NOC PCIe a-NOC AHB clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sar2130p-system-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre USB3 PRIM AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sar2130p-system-noc
+ - qcom,sar2130p-pcie-anoc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ clk_virt: interconnect-0 {
+ compatible = "qcom,sar2130p-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@1680000 {
+ compatible = "qcom,sar2130p-system-noc";
+ reg = <0x01680000 0x29080>;
+ #interconnect-cells = <2>;
+ clocks = <&gcc_prim_axi_clk>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml
new file mode 100644
index 000000000000..81c3dff53992
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sc7280-rpmh.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sc7280-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SC7280
+
+maintainers:
+ - Bjorn Andersson <andersson@kernel.org>
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM).
+
+ See also: include/dt-bindings/interconnect/qcom,sc7280.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sc7280-aggre1-noc
+ - qcom,sc7280-aggre2-noc
+ - qcom,sc7280-clk-virt
+ - qcom,sc7280-cnoc2
+ - qcom,sc7280-cnoc3
+ - qcom,sc7280-dc-noc
+ - qcom,sc7280-gem-noc
+ - qcom,sc7280-lpass-ag-noc
+ - qcom,sc7280-mc-virt
+ - qcom,sc7280-mmss-noc
+ - qcom,sc7280-nsp-noc
+ - qcom,sc7280-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc7280-clk-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc7280-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre USB3 PRIM AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc7280-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc7280-aggre1-noc
+ - qcom,sc7280-aggre2-noc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sc7280.h>
+ interconnect {
+ compatible = "qcom,sc7280-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ interconnect@9100000 {
+ reg = <0x9100000 0xe2200>;
+ compatible = "qcom,sc7280-gem-noc";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ interconnect@16e0000 {
+ reg = <0x016e0000 0x1c080>;
+ compatible = "qcom,sc7280-aggre1-noc";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ clocks = <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml
new file mode 100644
index 000000000000..2a5a7594bafd
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sc8280xp-rpmh.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sc8280xp-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SC8280XP
+
+maintainers:
+ - Bjorn Andersson <andersson@kernel.org>
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM).
+
+ See also: include/dt-bindings/interconnect/qcom,sc8280xp.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sc8280xp-aggre1-noc
+ - qcom,sc8280xp-aggre2-noc
+ - qcom,sc8280xp-clk-virt
+ - qcom,sc8280xp-config-noc
+ - qcom,sc8280xp-dc-noc
+ - qcom,sc8280xp-gem-noc
+ - qcom,sc8280xp-lpass-ag-noc
+ - qcom,sc8280xp-mc-virt
+ - qcom,sc8280xp-mmss-noc
+ - qcom,sc8280xp-nspa-noc
+ - qcom,sc8280xp-nspb-noc
+ - qcom,sc8280xp-system-noc
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ interconnect-0 {
+ compatible = "qcom,sc8280xp-aggre1-noc";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml
index 29de7807df54..8f6bc6399626 100644
--- a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml
@@ -7,16 +7,13 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm SDM660 Network-On-Chip interconnect
maintainers:
- - AngeloGioacchino Del Regno <kholk11@gmail.com>
+ - Konrad Dybcio <konradybcio@kernel.org>
description: |
The Qualcomm SDM660 interconnect providers support adjusting the
bandwidth requirements between the various NoC fabrics.
properties:
- reg:
- maxItems: 1
-
compatible:
enum:
- qcom,sdm660-a2noc
@@ -26,122 +23,86 @@ properties:
- qcom,sdm660-mnoc
- qcom,sdm660-snoc
- '#interconnect-cells':
- const: 1
+ reg:
+ maxItems: 1
- clocks:
+ clock-names:
minItems: 1
- maxItems: 3
+ maxItems: 5
- clock-names:
+ clocks:
minItems: 1
- maxItems: 3
+ maxItems: 5
required:
- compatible
- reg
- - '#interconnect-cells'
- - clock-names
- - clocks
-additionalProperties: false
+unevaluatedProperties: false
allOf:
+ - $ref: qcom,rpm-common.yaml#
- if:
properties:
compatible:
- contains:
- enum:
- - qcom,sdm660-mnoc
+ const: qcom,sdm660-mnoc
+
then:
properties:
clocks:
items:
- - description: Bus Clock.
- - description: Bus A Clock.
- description: CPU-NoC High-performance Bus Clock.
+
clock-names:
- items:
- - const: bus
- - const: bus_a
- - const: iface
+ const: iface
- if:
properties:
compatible:
- contains:
- enum:
- - qcom,sdm660-a2noc
- - qcom,sdm660-bimc
- - qcom,sdm660-cnoc
- - qcom,sdm660-gnoc
- - qcom,sdm660-snoc
+ const: qcom,sdm660-a2noc
+
then:
properties:
clocks:
items:
- - description: Bus Clock.
- - description: Bus A Clock.
+ - description: IPA Clock.
+ - description: UFS AXI Clock.
+ - description: Aggregate2 UFS AXI Clock.
+ - description: Aggregate2 USB3 AXI Clock.
+ - description: Config NoC USB2 AXI Clock.
+
clock-names:
items:
- - const: bus
- - const: bus_a
+ - const: ipa
+ - const: ufs_axi
+ - const: aggre2_ufs_axi
+ - const: aggre2_usb3_axi
+ - const: cfg_noc_usb2_axi
examples:
- |
- #include <dt-bindings/clock/qcom,rpmcc.h>
- #include <dt-bindings/clock/qcom,mmcc-sdm660.h>
-
- bimc: interconnect@1008000 {
- compatible = "qcom,sdm660-bimc";
- reg = <0x01008000 0x78000>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_BIMC_CLK>,
- <&rpmcc RPM_SMD_BIMC_A_CLK>;
- };
-
- cnoc: interconnect@1500000 {
- compatible = "qcom,sdm660-cnoc";
- reg = <0x01500000 0x10000>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_CNOC_CLK>,
- <&rpmcc RPM_SMD_CNOC_A_CLK>;
- };
-
- snoc: interconnect@1626000 {
- compatible = "qcom,sdm660-snoc";
- reg = <0x01626000 0x7090>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_SNOC_CLK>,
- <&rpmcc RPM_SMD_SNOC_A_CLK>;
- };
-
- a2noc: interconnect@1704000 {
- compatible = "qcom,sdm660-a2noc";
- reg = <0x01704000 0xc100>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&rpmcc RPM_SMD_AGGR2_NOC_CLK>,
- <&rpmcc RPM_SMD_AGGR2_NOC_A_CLK>;
- };
-
- mnoc: interconnect@1745000 {
- compatible = "qcom,sdm660-mnoc";
- reg = <0x01745000 0xa010>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a", "iface";
- clocks = <&rpmcc RPM_SMD_MMSSNOC_AXI_CLK>,
- <&rpmcc RPM_SMD_MMSSNOC_AXI_CLK_A>,
- <&mmcc AHB_CLK_SRC>;
- };
-
- gnoc: interconnect@17900000 {
- compatible = "qcom,sdm660-gnoc";
- reg = <0x17900000 0xe000>;
- #interconnect-cells = <1>;
- clock-names = "bus", "bus_a";
- clocks = <&xo_board>, <&xo_board>;
- };
+ #include <dt-bindings/clock/qcom,gcc-sdm660.h>
+ #include <dt-bindings/clock/qcom,mmcc-sdm660.h>
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+
+ bimc: interconnect@1008000 {
+ compatible = "qcom,sdm660-bimc";
+ reg = <0x01008000 0x78000>;
+ #interconnect-cells = <1>;
+ };
+
+ a2noc: interconnect@1704000 {
+ compatible = "qcom,sdm660-a2noc";
+ reg = <0x01704000 0xc100>;
+ #interconnect-cells = <1>;
+ clocks = <&rpmcc RPM_SMD_IPA_CLK>,
+ <&gcc GCC_UFS_AXI_CLK>,
+ <&gcc GCC_AGGRE2_UFS_AXI_CLK>,
+ <&gcc GCC_AGGRE2_USB3_AXI_CLK>,
+ <&gcc GCC_CFG_NOC_USB2_AXI_CLK>;
+ clock-names = "ipa",
+ "ufs_axi",
+ "aggre2_ufs_axi",
+ "aggre2_usb3_axi",
+ "cfg_noc_usb2_axi";
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml
new file mode 100644
index 000000000000..4b5e9f9b07ec
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml
@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sdx75-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SDX75
+
+maintainers:
+ - Rohit Agarwal <quic_rohiagar@quicinc.com>
+
+description:
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+properties:
+ compatible:
+ enum:
+ - qcom,sdx75-clk-virt
+ - qcom,sdx75-dc-noc
+ - qcom,sdx75-gem-noc
+ - qcom,sdx75-mc-virt
+ - qcom,sdx75-pcie-anoc
+ - qcom,sdx75-system-noc
+
+ '#interconnect-cells': true
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sdx75-clk-virt
+ - qcom,sdx75-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sdx75-clk-virt
+ then:
+ properties:
+ clocks:
+ items:
+ - description: RPMH CC QPIC Clock
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+
+ clk_virt: interconnect-0 {
+ compatible = "qcom,sdx75-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ clocks = <&rpmhcc RPMH_QPIC_CLK>;
+ };
+
+ system_noc: interconnect@1640000 {
+ compatible = "qcom,sdx75-system-noc";
+ reg = <0x1640000 0x4b400>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml
new file mode 100644
index 000000000000..14b1a0b08e73
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm6115.yaml
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm6115.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SM6115 Network-On-Chip interconnect
+
+maintainers:
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description:
+ The Qualcomm SM6115 interconnect providers support adjusting the
+ bandwidth requirements between the various NoC fabrics.
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm6115-bimc
+ - qcom,sm6115-cnoc
+ - qcom,sm6115-snoc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 4
+
+ clock-names:
+ minItems: 1
+ maxItems: 4
+
+# Child node's properties
+patternProperties:
+ '^interconnect-[a-z0-9]+$':
+ type: object
+ description:
+ The interconnect providers do not have a separate QoS register space,
+ but share parent's space.
+
+ $ref: qcom,rpm-common.yaml#
+
+ properties:
+ compatible:
+ enum:
+ - qcom,sm6115-clk-virt
+ - qcom,sm6115-mmrt-virt
+ - qcom,sm6115-mmnrt-virt
+
+ required:
+ - compatible
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: qcom,rpm-common.yaml#
+ - if:
+ properties:
+ compatible:
+ const: qcom,sm6115-cnoc
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: USB-NoC AXI clock
+
+ clock-names:
+ items:
+ - const: usb_axi
+
+ - if:
+ properties:
+ compatible:
+ const: qcom,sm6115-snoc
+
+ then:
+ properties:
+ clocks:
+ items:
+ - description: CPU-NoC AXI clock.
+ - description: UFS-NoC AXI clock.
+ - description: USB-NoC AXI clock.
+ - description: IPA clock.
+
+ clock-names:
+ items:
+ - const: cpu_axi
+ - const: ufs_axi
+ - const: usb_axi
+ - const: ipa
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sm6115-bimc
+ - qcom,sm6115-clk-virt
+ - qcom,sm6115-mmrt-virt
+ - qcom,sm6115-mmnrt-virt
+
+ then:
+ properties:
+ clocks: false
+ clock-names: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sm6115.h>
+ #include <dt-bindings/clock/qcom,rpmcc.h>
+
+ snoc: interconnect@1880000 {
+ compatible = "qcom,sm6115-snoc";
+ reg = <0x01880000 0x60200>;
+ clocks = <&gcc GCC_SYS_NOC_CPUSS_AHB_CLK>,
+ <&gcc GCC_SYS_NOC_UFS_PHY_AXI_CLK>,
+ <&gcc GCC_SYS_NOC_USB3_PRIM_AXI_CLK>,
+ <&rpmcc RPM_SMD_IPA_CLK>;
+ clock-names = "cpu_axi",
+ "ufs_axi",
+ "usb_axi",
+ "ipa";
+ #interconnect-cells = <1>;
+
+ qup_virt: interconnect-clk {
+ compatible = "qcom,sm6115-clk-virt";
+ #interconnect-cells = <1>;
+ };
+
+ mmnrt_virt: interconnect-mmnrt {
+ compatible = "qcom,sm6115-mmnrt-virt";
+ #interconnect-cells = <1>;
+ };
+
+ mmrt_virt: interconnect-mmrt {
+ compatible = "qcom,sm6115-mmrt-virt";
+ #interconnect-cells = <1>;
+ };
+ };
+
+ cnoc: interconnect@1900000 {
+ compatible = "qcom,sm6115-cnoc";
+ reg = <0x01900000 0x8200>;
+ #interconnect-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm6350-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm6350-rpmh.yaml
new file mode 100644
index 000000000000..2dc16e4293a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm6350-rpmh.yaml
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm6350-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SM6350 RPMh Network-On-Chip Interconnect
+
+maintainers:
+ - Luca Weiss <luca.weiss@fairphone.com>
+
+description:
+ Qualcomm RPMh-based interconnect provider on SM6350.
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm6350-aggre1-noc
+ - qcom,sm6350-aggre2-noc
+ - qcom,sm6350-config-noc
+ - qcom,sm6350-dc-noc
+ - qcom,sm6350-gem-noc
+ - qcom,sm6350-mmss-noc
+ - qcom,sm6350-npu-noc
+ - qcom,sm6350-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+patternProperties:
+ '^interconnect-[a-z0-9\-]+$':
+ type: object
+ description:
+ The interconnect providers do not have a separate QoS register space,
+ but share parent's space.
+ $ref: qcom,rpmh-common.yaml#
+
+ properties:
+ compatible:
+ enum:
+ - qcom,sm6350-clk-virt
+ - qcom,sm6350-compute-noc
+
+ required:
+ - compatible
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm6350-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm6350-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre USB3 PRIM AXI clock
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm6350-aggre1-noc
+ - qcom,sm6350-aggre2-noc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sm6350.h>
+ #include <dt-bindings/clock/qcom,rpmh.h>
+
+ config_noc: interconnect@1500000 {
+ compatible = "qcom,sm6350-config-noc";
+ reg = <0x01500000 0x28000>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre2_noc: interconnect@1700000 {
+ compatible = "qcom,sm6350-aggre2-noc";
+ reg = <0x01700000 0x1f880>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ clocks = <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>,
+ <&rpmhcc RPMH_IPA_CLK>;
+
+ compute_noc: interconnect-compute-noc {
+ compatible = "qcom,sm6350-compute-noc";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm7150-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm7150-rpmh.yaml
new file mode 100644
index 000000000000..978930324bbf
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm7150-rpmh.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm7150-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SM7150
+
+maintainers:
+ - Danila Tikhonov <danila@jiaxyga.com>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM).
+
+ See also: include/dt-bindings/interconnect/qcom,sm7150-rpmh.h
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm7150-aggre1-noc
+ - qcom,sm7150-aggre2-noc
+ - qcom,sm7150-compute-noc
+ - qcom,sm7150-config-noc
+ - qcom,sm7150-dc-noc
+ - qcom,sm7150-gem-noc
+ - qcom,sm7150-mc-virt
+ - qcom,sm7150-mmss-noc
+ - qcom,sm7150-system-noc
+
+ reg:
+ maxItems: 1
+
+# Child node's properties
+patternProperties:
+ '^interconnect-[0-9]+$':
+ type: object
+ description:
+ The interconnect providers do not have a separate QoS register space,
+ but share parent's space.
+
+ allOf:
+ - $ref: qcom,rpmh-common.yaml#
+
+ properties:
+ compatible:
+ enum:
+ - qcom,sm7150-camnoc-virt
+
+ required:
+ - compatible
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ mc_virt: interconnect@1380000 {
+ compatible = "qcom,sm7150-mc-virt";
+ reg = <0x01380000 0x40000>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ system_noc: interconnect@1620000 {
+ compatible = "qcom,sm7150-system-noc";
+ reg = <0x01620000 0x40000>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+
+ camnoc_virt: interconnect-0 {
+ compatible = "qcom,sm7150-camnoc-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml
new file mode 100644
index 000000000000..6a46dc7d473e
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8450-rpmh.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm8450-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SM8450
+
+maintainers:
+ - Bjorn Andersson <andersson@kernel.org>
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM).
+
+ See also: include/dt-bindings/interconnect/qcom,sm8450.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm8450-aggre1-noc
+ - qcom,sm8450-aggre2-noc
+ - qcom,sm8450-clk-virt
+ - qcom,sm8450-config-noc
+ - qcom,sm8450-gem-noc
+ - qcom,sm8450-lpass-ag-noc
+ - qcom,sm8450-mc-virt
+ - qcom,sm8450-mmss-noc
+ - qcom,sm8450-nsp-noc
+ - qcom,sm8450-pcie-anoc
+ - qcom,sm8450-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 4
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8450-clk-virt
+ - qcom,sm8450-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8450-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre USB3 PRIM AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8450-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe 0 AXI clock
+ - description: aggre-NOC PCIe 1 AXI clock
+ - description: aggre UFS PHY AXI clock
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8450-aggre1-noc
+ - qcom,sm8450-aggre2-noc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sm8450.h>
+ #include <dt-bindings/clock/qcom,rpmh.h>
+
+ interconnect-0 {
+ compatible = "qcom,sm8450-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ interconnect@1700000 {
+ compatible = "qcom,sm8450-aggre2-noc";
+ reg = <0x01700000 0x31080>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ clocks = <&gcc GCC_AGGRE_NOC_PCIE_0_AXI_CLK>,
+ <&gcc GCC_AGGRE_NOC_PCIE_1_AXI_CLK>,
+ <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>,
+ <&rpmhcc RPMH_IPA_CLK>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml
new file mode 100644
index 000000000000..5325ebe23c77
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8550-rpmh.yaml
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm8550-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SM8550
+
+maintainers:
+ - Abel Vesa <abel.vesa@linaro.org>
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,sm8550-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm8550-aggre1-noc
+ - qcom,sm8550-aggre2-noc
+ - qcom,sm8550-clk-virt
+ - qcom,sm8550-cnoc-main
+ - qcom,sm8550-config-noc
+ - qcom,sm8550-gem-noc
+ - qcom,sm8550-lpass-ag-noc
+ - qcom,sm8550-lpass-lpiaon-noc
+ - qcom,sm8550-lpass-lpicx-noc
+ - qcom,sm8550-mc-virt
+ - qcom,sm8550-mmss-noc
+ - qcom,sm8550-nsp-noc
+ - qcom,sm8550-pcie-anoc
+ - qcom,sm8550-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8550-clk-virt
+ - qcom,sm8550-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8550-pcie-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe AXI clock
+ - description: cfg-NOC PCIe a-NOC AHB clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8550-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre USB3 PRIM AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8550-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8550-aggre1-noc
+ - qcom,sm8550-aggre2-noc
+ - qcom,sm8550-pcie-anoc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+required:
+ - compatible
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,sm8550-gcc.h>
+
+ clk_virt: interconnect-0 {
+ compatible = "qcom,sm8550-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@16e0000 {
+ compatible = "qcom,sm8550-aggre1-noc";
+ reg = <0x016e0000 0x14400>;
+ #interconnect-cells = <2>;
+ clocks = <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>,
+ <&gcc GCC_AGGRE_USB3_PRIM_AXI_CLK>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml
new file mode 100644
index 000000000000..199fe7b232af
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8650-rpmh.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm8650-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SM8650
+
+maintainers:
+ - Abel Vesa <abel.vesa@linaro.org>
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,sm8650-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm8650-aggre1-noc
+ - qcom,sm8650-aggre2-noc
+ - qcom,sm8650-clk-virt
+ - qcom,sm8650-cnoc-main
+ - qcom,sm8650-config-noc
+ - qcom,sm8650-gem-noc
+ - qcom,sm8650-lpass-ag-noc
+ - qcom,sm8650-lpass-lpiaon-noc
+ - qcom,sm8650-lpass-lpicx-noc
+ - qcom,sm8650-mc-virt
+ - qcom,sm8650-mmss-noc
+ - qcom,sm8650-nsp-noc
+ - qcom,sm8650-pcie-anoc
+ - qcom,sm8650-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8650-clk-virt
+ - qcom,sm8650-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8650-pcie-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe AXI clock
+ - description: cfg-NOC PCIe a-NOC AHB clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8650-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre USB3 PRIM AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8650-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8650-aggre1-noc
+ - qcom,sm8650-aggre2-noc
+ - qcom,sm8650-pcie-anoc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ clk_virt: interconnect-0 {
+ compatible = "qcom,sm8650-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@16e0000 {
+ compatible = "qcom,sm8650-aggre1-noc";
+ reg = <0x016e0000 0x14400>;
+ #interconnect-cells = <2>;
+ clocks = <&gcc_phy_axi_clk>, <&gcc_prim_axi_clk>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sm8750-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sm8750-rpmh.yaml
new file mode 100644
index 000000000000..366f40d980c2
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,sm8750-rpmh.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,sm8750-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on SM8750
+
+maintainers:
+ - Abel Vesa <abel.vesa@linaro.org>
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,sm8750-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm8750-aggre1-noc
+ - qcom,sm8750-aggre2-noc
+ - qcom,sm8750-clk-virt
+ - qcom,sm8750-cnoc-main
+ - qcom,sm8750-config-noc
+ - qcom,sm8750-gem-noc
+ - qcom,sm8750-lpass-ag-noc
+ - qcom,sm8750-lpass-lpiaon-noc
+ - qcom,sm8750-lpass-lpicx-noc
+ - qcom,sm8750-mc-virt
+ - qcom,sm8750-mmss-noc
+ - qcom,sm8750-nsp-noc
+ - qcom,sm8750-pcie-anoc
+ - qcom,sm8750-system-noc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8750-clk-virt
+ - qcom,sm8750-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8750-pcie-anoc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre-NOC PCIe AXI clock
+ - description: cfg-NOC PCIe a-NOC AHB clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8750-aggre1-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: aggre UFS PHY AXI clock
+ - description: aggre USB3 PRIM AXI clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8750-aggre2-noc
+ then:
+ properties:
+ clocks:
+ items:
+ - description: RPMH CC IPA clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm8750-aggre1-noc
+ - qcom,sm8750-aggre2-noc
+ - qcom,sm8750-pcie-anoc
+ then:
+ required:
+ - clocks
+ else:
+ properties:
+ clocks: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ clk_virt: interconnect-0 {
+ compatible = "qcom,sm8750-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@16e0000 {
+ compatible = "qcom,sm8750-aggre1-noc";
+ reg = <0x016e0000 0x16400>;
+ #interconnect-cells = <2>;
+ clocks = <&gcc_phy_axi_clk>, <&gcc_prim_axi_clk>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml
new file mode 100644
index 000000000000..0840b0ec6e27
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/qcom,x1e80100-rpmh.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/qcom,x1e80100-rpmh.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm RPMh Network-On-Chip Interconnect on X1E80100
+
+maintainers:
+ - Rajendra Nayak <quic_rjendra@quicinc.com>
+ - Abel Vesa <abel.vesa@linaro.org>
+
+description: |
+ RPMh interconnect providers support system bandwidth requirements through
+ RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is
+ able to communicate with the BCM through the Resource State Coordinator (RSC)
+ associated with each execution environment. Provider nodes must point to at
+ least one RPMh device child node pertaining to their RSC and each provider
+ can map to multiple RPMh resources.
+
+ See also: include/dt-bindings/interconnect/qcom,x1e80100-rpmh.h
+
+properties:
+ compatible:
+ enum:
+ - qcom,x1e80100-aggre1-noc
+ - qcom,x1e80100-aggre2-noc
+ - qcom,x1e80100-clk-virt
+ - qcom,x1e80100-cnoc-cfg
+ - qcom,x1e80100-cnoc-main
+ - qcom,x1e80100-gem-noc
+ - qcom,x1e80100-lpass-ag-noc
+ - qcom,x1e80100-lpass-lpiaon-noc
+ - qcom,x1e80100-lpass-lpicx-noc
+ - qcom,x1e80100-mc-virt
+ - qcom,x1e80100-mmss-noc
+ - qcom,x1e80100-nsp-noc
+ - qcom,x1e80100-pcie-center-anoc
+ - qcom,x1e80100-pcie-north-anoc
+ - qcom,x1e80100-pcie-south-anoc
+ - qcom,x1e80100-system-noc
+ - qcom,x1e80100-usb-center-anoc
+ - qcom,x1e80100-usb-north-anoc
+ - qcom,x1e80100-usb-south-anoc
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+
+allOf:
+ - $ref: qcom,rpmh-common.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,x1e80100-clk-virt
+ - qcom,x1e80100-mc-virt
+ then:
+ properties:
+ reg: false
+ else:
+ required:
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ clk_virt: interconnect-0 {
+ compatible = "qcom,x1e80100-clk-virt";
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
+
+ aggre1_noc: interconnect@16e0000 {
+ compatible = "qcom,x1e80100-aggre1-noc";
+ reg = <0x016e0000 0x14400>;
+ #interconnect-cells = <2>;
+ qcom,bcm-voters = <&apps_bcm_voter>;
+ };
diff --git a/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml b/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml
new file mode 100644
index 000000000000..5e26e48c7217
--- /dev/null
+++ b/Documentation/devicetree/bindings/interconnect/samsung,exynos-bus.yaml
@@ -0,0 +1,317 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interconnect/samsung,exynos-bus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos SoC Bus and Interconnect
+
+maintainers:
+ - Chanwoo Choi <cw00.choi@samsung.com>
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ The Samsung Exynos SoC has many buses for data transfer between DRAM and
+ sub-blocks in SoC. Most Exynos SoCs share the common architecture for buses.
+ Generally, each bus of Exynos SoC includes a source clock and a power line,
+ which are able to change the clock frequency of the bus in runtime. To
+ monitor the usage of each bus in runtime, the driver uses the PPMU (Platform
+ Performance Monitoring Unit), which is able to measure the current load of
+ sub-blocks.
+
+ The Exynos SoC includes the various sub-blocks which have the each AXI bus.
+ The each AXI bus has the owned source clock but, has not the only owned power
+ line. The power line might be shared among one more sub-blocks. So, we can
+ divide into two type of device as the role of each sub-block. There are two
+ type of bus devices as following::
+ - parent bus device
+ - passive bus device
+
+ Basically, parent and passive bus device share the same power line. The
+ parent bus device can only change the voltage of shared power line and the
+ rest bus devices (passive bus device) depend on the decision of the parent
+ bus device. If there are three blocks which share the VDD_xxx power line,
+ Only one block should be parent device and then the rest blocks should depend
+ on the parent device as passive device.
+
+ VDD_xxx |--- A block (parent)
+ |--- B block (passive)
+ |--- C block (passive)
+
+ There are a little different composition among Exynos SoC because each Exynos
+ SoC has different sub-blocks. Therefore, such difference should be specified
+ in devicetree file instead of each device driver. In result, this driver is
+ able to support the bus frequency for all Exynos SoCs.
+
+ Detailed correlation between sub-blocks and power line according
+ to Exynos SoC::
+ - In case of Exynos3250, there are two power line as following::
+ VDD_MIF |--- DMC (Dynamic Memory Controller)
+
+ VDD_INT |--- LEFTBUS (parent device)
+ |--- PERIL
+ |--- MFC
+ |--- G3D
+ |--- RIGHTBUS
+ |--- PERIR
+ |--- FSYS
+ |--- LCD0
+ |--- PERIR
+ |--- ISP
+ |--- CAM
+
+ - MIF bus's frequency/voltage table
+ -----------------------
+ |Lv| Freq | Voltage |
+ -----------------------
+ |L1| 50000 |800000 |
+ |L2| 100000 |800000 |
+ |L3| 134000 |800000 |
+ |L4| 200000 |825000 |
+ |L5| 400000 |875000 |
+ -----------------------
+
+ - INT bus's frequency/voltage table
+ ----------------------------------------------------------
+ |Block|LEFTBUS|RIGHTBUS|MCUISP |ISP |PERIL ||VDD_INT |
+ | name| |LCD0 | | | || |
+ | | |FSYS | | | || |
+ | | |MFC | | | || |
+ ----------------------------------------------------------
+ |Mode |*parent|passive |passive|passive|passive|| |
+ ----------------------------------------------------------
+ |Lv |Frequency ||Voltage |
+ ----------------------------------------------------------
+ |L1 |50000 |50000 |50000 |50000 |50000 ||900000 |
+ |L2 |80000 |80000 |80000 |80000 |80000 ||900000 |
+ |L3 |100000 |100000 |100000 |100000 |100000 ||1000000 |
+ |L4 |134000 |134000 |200000 |200000 | ||1000000 |
+ |L5 |200000 |200000 |400000 |300000 | ||1000000 |
+ ----------------------------------------------------------
+
+ - In case of Exynos4210, there is one power line as following::
+ VDD_INT |--- DMC (parent device, Dynamic Memory Controller)
+ |--- LEFTBUS
+ |--- PERIL
+ |--- MFC(L)
+ |--- G3D
+ |--- TV
+ |--- LCD0
+ |--- RIGHTBUS
+ |--- PERIR
+ |--- MFC(R)
+ |--- CAM
+ |--- FSYS
+ |--- GPS
+ |--- LCD0
+ |--- LCD1
+
+ - In case of Exynos4x12, there are two power line as following::
+ VDD_MIF |--- DMC (Dynamic Memory Controller)
+
+ VDD_INT |--- LEFTBUS (parent device)
+ |--- PERIL
+ |--- MFC(L)
+ |--- G3D
+ |--- TV
+ |--- IMAGE
+ |--- RIGHTBUS
+ |--- PERIR
+ |--- MFC(R)
+ |--- CAM
+ |--- FSYS
+ |--- GPS
+ |--- LCD0
+ |--- ISP
+
+ - In case of Exynos5422, there are two power line as following::
+ VDD_MIF |--- DREX 0 (parent device, DRAM EXpress controller)
+ |--- DREX 1
+
+ VDD_INT |--- NoC_Core (parent device)
+ |--- G2D
+ |--- G3D
+ |--- DISP1
+ |--- NoC_WCORE
+ |--- GSCL
+ |--- MSCL
+ |--- ISP
+ |--- MFC
+ |--- GEN
+ |--- PERIS
+ |--- PERIC
+ |--- FSYS
+ |--- FSYS2
+
+ - In case of Exynos5433, there is VDD_INT power line as following::
+ VDD_INT |--- G2D (parent device)
+ |--- MSCL
+ |--- GSCL
+ |--- JPEG
+ |--- MFC
+ |--- HEVC
+ |--- BUS0
+ |--- BUS1
+ |--- BUS2
+ |--- PERIS (Fixed clock rate)
+ |--- PERIC (Fixed clock rate)
+ |--- FSYS (Fixed clock rate)
+
+properties:
+ compatible:
+ enum:
+ - samsung,exynos-bus
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: bus
+
+ devfreq:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Parent bus device. Valid and required only for the passive bus devices.
+
+ devfreq-events:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ minItems: 1
+ maxItems: 4
+ description:
+ Devfreq-event device to monitor the current utilization of buses. Valid
+ and required only for the parent bus devices.
+
+ exynos,saturation-ratio:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Percentage value which is used to calibrate the performance count against
+ total cycle count. Valid only for the parent bus devices.
+
+ '#interconnect-cells':
+ const: 0
+
+ interconnects:
+ minItems: 1
+ maxItems: 2
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+ samsung,data-clock-ratio:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 8
+ description:
+ Ratio of the data throughput in B/s to minimum data clock frequency in
+ Hz.
+
+ vdd-supply:
+ description:
+ Main bus power rail. Valid and required only for the parent bus devices.
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - operating-points-v2
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos3250.h>
+
+ bus-dmc {
+ compatible = "samsung,exynos-bus";
+ clocks = <&cmu_dmc CLK_DIV_DMC>;
+ clock-names = "bus";
+ operating-points-v2 = <&bus_dmc_opp_table>;
+ devfreq-events = <&ppmu_dmc0_3>, <&ppmu_dmc1_3>;
+ vdd-supply = <&buck1_reg>;
+
+ bus_dmc_opp_table: opp-table {
+ compatible = "operating-points-v2";
+
+ opp-50000000 {
+ opp-hz = /bits/ 64 <50000000>;
+ opp-microvolt = <800000>;
+ };
+ opp-100000000 {
+ opp-hz = /bits/ 64 <100000000>;
+ opp-microvolt = <800000>;
+ };
+ opp-134000000 {
+ opp-hz = /bits/ 64 <134000000>;
+ opp-microvolt = <800000>;
+ };
+ opp-200000000 {
+ opp-hz = /bits/ 64 <200000000>;
+ opp-microvolt = <825000>;
+ };
+ opp-400000000 {
+ opp-hz = /bits/ 64 <400000000>;
+ opp-microvolt = <875000>;
+ };
+ };
+ };
+
+ ppmu_dmc0: ppmu@106a0000 {
+ compatible = "samsung,exynos-ppmu";
+ reg = <0x106a0000 0x2000>;
+ events {
+ ppmu_dmc0_3: ppmu-event3-dmc0 {
+ event-name = "ppmu-event3-dmc0";
+ };
+ };
+ };
+
+ bus_leftbus: bus-leftbus {
+ compatible = "samsung,exynos-bus";
+ clocks = <&cmu CLK_DIV_GDL>;
+ clock-names = "bus";
+ operating-points-v2 = <&bus_leftbus_opp_table>;
+ devfreq-events = <&ppmu_leftbus_3>, <&ppmu_rightbus_3>;
+ vdd-supply = <&buck3_reg>;
+ };
+
+ bus-rightbus {
+ compatible = "samsung,exynos-bus";
+ clocks = <&cmu CLK_DIV_GDR>;
+ clock-names = "bus";
+ operating-points-v2 = <&bus_leftbus_opp_table>;
+ devfreq = <&bus_leftbus>;
+ };
+
+ - |
+ dmc: bus-dmc {
+ compatible = "samsung,exynos-bus";
+ clocks = <&clock CLK_DIV_DMC>;
+ clock-names = "bus";
+ operating-points-v2 = <&bus_dmc_opp_table>;
+ samsung,data-clock-ratio = <4>;
+ #interconnect-cells = <0>;
+ devfreq-events = <&ppmu_dmc0_3>, <&ppmu_dmc1_3>;
+ vdd-supply = <&buck1_reg>;
+ };
+
+ leftbus: bus-leftbus {
+ compatible = "samsung,exynos-bus";
+ clocks = <&clock CLK_DIV_GDL>;
+ clock-names = "bus";
+ operating-points-v2 = <&bus_leftbus_opp_table>;
+ interconnects = <&dmc>;
+ #interconnect-cells = <0>;
+ devfreq-events = <&ppmu_leftbus_3>, <&ppmu_rightbus_3>;
+ vdd-supply = <&buck3_reg>;
+ };
+
+ display: bus-display {
+ compatible = "samsung,exynos-bus";
+ clocks = <&clock CLK_DIV_ACLK_266>;
+ clock-names = "bus";
+ operating-points-v2 = <&bus_display_opp_table>;
+ interconnects = <&leftbus &dmc>;
+ #interconnect-cells = <0>;
+ devfreq = <&leftbus>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.txt b/Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.txt
deleted file mode 100644
index 5a4dd263fc12..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-TB10x Top Level Interrupt Controller
-====================================
-
-The Abilis TB10x SOC contains a custom interrupt controller. It performs
-one-to-one mapping of external interrupt sources to CPU interrupts and
-provides support for reconfigurable trigger modes.
-
-Required properties
--------------------
-
-- compatible: Should be "abilis,tb10x-ictl"
-- reg: specifies physical base address and size of register range.
-- interrupt-congroller: Identifies the node as an interrupt controller.
-- #interrupt cells: Specifies the number of cells used to encode an interrupt
- source connected to this controller. The value shall be 2.
-- interrupts: Specifies the list of interrupt lines which are handled by
- the interrupt controller in the parent controller's notation. Interrupts
- are mapped one-to-one to parent interrupts.
-
-Example
--------
-
-intc: interrupt-controller { /* Parent interrupt controller */
- interrupt-controller;
- #interrupt-cells = <1>; /* For example below */
- /* ... */
-};
-
-tb10x_ictl: pic@2000 { /* TB10x interrupt controller */
- compatible = "abilis,tb10x-ictl";
- reg = <0x2000 0x20>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupt-parent = <&intc>;
- interrupts = <5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
- 20 21 22 23 24 25 26 27 28 29 30 31>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.yaml b/Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.yaml
new file mode 100644
index 000000000000..cd2c49670e7b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/abilis,tb10x-ictl.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/abilis,tb10x-ictl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TB10x Top Level Interrupt Controller
+
+maintainers:
+ - Christian Ruppert <christian.ruppert@abilis.com>
+
+description:
+ The Abilis TB10x SOC contains a custom interrupt controller. It performs
+ one-to-one mapping of external interrupt sources to CPU interrupts and
+ provides support for reconfigurable trigger modes.
+
+properties:
+ compatible:
+ const: abilis,tb10x-ictl
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ description: A one-to-one mapping of external interrupt sources to parent
+ interrupts.
+ minItems: 1
+ maxItems: 32
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@2000 {
+ compatible = "abilis,tb10x-ictl";
+ reg = <0x2000 0x20>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <5>, <6>, <7>, <8>, <9>, <10>, <11>, <12>, <13>, <14>,
+ <15>, <16>, <17>, <18>, <19>, <20>, <21>, <22>, <23>,
+ <24>, <25>, <26>, <27>, <28>, <29>, <30>, <31>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml
index 5da333c644c9..27756d0c5419 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/actions,owl-sirq.yaml
@@ -32,7 +32,7 @@ properties:
The first cell is the input IRQ number, between 0 and 2, while the second
cell is the trigger type as defined in interrupt.txt in this directory.
- 'interrupts':
+ interrupts:
description: |
Contains the GIC SPI IRQs mapped to the external interrupt lines.
They shall be specified sequentially from output 0 to 2.
@@ -44,7 +44,7 @@ required:
- reg
- interrupt-controller
- '#interrupt-cells'
- - 'interrupts'
+ - interrupts
additionalProperties: false
diff --git a/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.txt b/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.txt
deleted file mode 100644
index 5669764f9cc9..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-Alpine MSIX controller
-
-See arm,gic-v3.txt for SPI and MSI definitions.
-
-Required properties:
-
-- compatible: should be "al,alpine-msix"
-- reg: physical base address and size of the registers
-- interrupt-controller: identifies the node as an interrupt controller
-- msi-controller: identifies the node as an PCI Message Signaled Interrupt
- controller
-- al,msi-base-spi: SPI base of the MSI frame
-- al,msi-num-spis: number of SPIs assigned to the MSI frame, relative to SPI0
-
-Example:
-
-msix: msix {
- compatible = "al,alpine-msix";
- reg = <0x0 0xfbe00000 0x0 0x100000>;
- interrupt-parent = <&gic>;
- interrupt-controller;
- msi-controller;
- al,msi-base-spi = <160>;
- al,msi-num-spis = <160>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.yaml b/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.yaml
new file mode 100644
index 000000000000..9f1ff8ec686f
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/al,alpine-msix.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Alpine MSIX controller
+
+maintainers:
+ - Antoine Tenart <atenart@kernel.org>
+
+properties:
+ compatible:
+ const: al,alpine-msix
+
+ reg:
+ maxItems: 1
+
+ interrupt-parent: true
+
+ msi-controller: true
+
+ al,msi-base-spi:
+ description: SPI base of the MSI frame
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ al,msi-num-spis:
+ description: number of SPIs assigned to the MSI frame, relative to SPI0
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - msi-controller
+ - al,msi-base-spi
+ - al,msi-num-spis
+
+additionalProperties: false
+
+examples:
+ - |
+ msi-controller@fbe00000 {
+ compatible = "al,alpine-msix";
+ reg = <0xfbe00000 0x100000>;
+ interrupt-parent = <&gic>;
+ msi-controller;
+ al,msi-base-spi = <160>;
+ al,msi-num-spis = <160>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml
index 953d875b5e74..a713633be733 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-a10-ic.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/allwinner,sun4i-a10-ic.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A10 Interrupt Controller Device Tree Bindings
+title: Allwinner A10 Interrupt Controller
maintainers:
- Chen-Yu Tsai <wens@csie.org>
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml
index 4db24b8a9ffe..4fa6fd400eef 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/allwinner,sun6i-a31-r-intc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A31 NMI/Wakeup Interrupt Controller Device Tree Bindings
+title: Allwinner A31 NMI/Wakeup Interrupt Controller
maintainers:
- Chen-Yu Tsai <wens@csie.org>
diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml
index 7fc9ad5ef38c..06e3621a8c06 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/allwinner,sun7i-a20-sc-nmi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A20 Non-Maskable Interrupt Controller Device Tree Bindings
+title: Allwinner A20 Non-Maskable Interrupt Controller
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -25,12 +25,13 @@ properties:
- const: allwinner,sun6i-a31-sc-nmi
deprecated: true
- const: allwinner,sun7i-a20-sc-nmi
- - items:
- - const: allwinner,sun8i-v3s-nmi
- - const: allwinner,sun9i-a80-nmi
- const: allwinner,sun9i-a80-nmi
+ - const: allwinner,sun55i-a523-nmi
- items:
- - const: allwinner,sun50i-a100-nmi
+ - enum:
+ - allwinner,sun8i-v3s-nmi
+ - allwinner,sun50i-a100-nmi
+ - allwinner,sun50i-h616-nmi
- const: allwinner,sun9i-a80-nmi
reg:
diff --git a/Documentation/devicetree/bindings/interrupt-controller/altr,msi-controller.yaml b/Documentation/devicetree/bindings/interrupt-controller/altr,msi-controller.yaml
new file mode 100644
index 000000000000..d046954b8a27
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/altr,msi-controller.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (C) 2015, 2024, Intel Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/altr,msi-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Altera PCIe MSI controller
+
+maintainers:
+ - Matthew Gerlach <matthew.gerlach@linux.intel.com>
+
+properties:
+ compatible:
+ enum:
+ - altr,msi-1.0
+
+ reg:
+ items:
+ - description: CSR registers
+ - description: Vectors slave port region
+
+ reg-names:
+ items:
+ - const: csr
+ - const: vector_slave
+
+ interrupts:
+ maxItems: 1
+
+ msi-controller: true
+
+ num-vectors:
+ description: number of vectors
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 32
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - msi-controller
+ - num-vectors
+
+allOf:
+ - $ref: /schemas/interrupt-controller/msi-controller.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ msi@ff200000 {
+ compatible = "altr,msi-1.0";
+ reg = <0xff200000 0x00000010>,
+ <0xff200010 0x00000080>;
+ reg-names = "csr", "vector_slave";
+ interrupt-parent = <&hps_0_arm_gic_0>;
+ interrupts = <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>;
+ msi-controller;
+ num-vectors = <32>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.txt b/Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.txt
deleted file mode 100644
index c676b03c752e..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Amazon's Annapurna Labs Fabric Interrupt Controller
-
-Required properties:
-
-- compatible: should be "amazon,al-fic"
-- reg: physical base address and size of the registers
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells : must be 2. Specifies the number of cells needed to encode
- an interrupt source. Supported trigger types are low-to-high edge
- triggered and active high level-sensitive.
-- interrupts: describes which input line in the interrupt parent, this
- fic's output is connected to. This field property depends on the parent's
- binding
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-Example:
-
-amazon_fic: interrupt-controller@fd8a8500 {
- compatible = "amazon,al-fic";
- interrupt-controller;
- #interrupt-cells = <2>;
- reg = <0x0 0xfd8a8500 0x0 0x1000>;
- interrupt-parent = <&gic>;
- interrupts = <GIC_SPI 0x0 IRQ_TYPE_LEVEL_HIGH>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.yaml b/Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.yaml
new file mode 100644
index 000000000000..26bc05dee0bc
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/amazon,al-fic.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/amazon,al-fic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amazon Annapurna Labs Fabric Interrupt Controller
+
+maintainers:
+ - Talel Shenhar <talel@amazon.com>
+
+properties:
+ compatible:
+ const: amazon,al-fic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@fd8a8500 {
+ compatible = "amazon,al-fic";
+ reg = <0xfd8a8500 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <GIC_SPI 0x0 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt
deleted file mode 100644
index 23b18b92c558..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-Amlogic meson GPIO interrupt controller
-
-Meson SoCs contains an interrupt controller which is able to watch the SoC
-pads and generate an interrupt on edge or level. The controller is essentially
-a 256 pads to 8 GIC interrupt multiplexer, with a filter block to select edge
-or level and polarity. It does not expose all 256 mux inputs because the
-documentation shows that the upper part is not mapped to any pad. The actual
-number of interrupt exposed depends on the SoC.
-
-Required properties:
-
-- compatible : must have "amlogic,meson8-gpio-intc" and either
- "amlogic,meson8-gpio-intc" for meson8 SoCs (S802) or
- "amlogic,meson8b-gpio-intc" for meson8b SoCs (S805) or
- "amlogic,meson-gxbb-gpio-intc" for GXBB SoCs (S905) or
- "amlogic,meson-gxl-gpio-intc" for GXL SoCs (S905X, S912)
- "amlogic,meson-axg-gpio-intc" for AXG SoCs (A113D, A113X)
- "amlogic,meson-g12a-gpio-intc" for G12A SoCs (S905D2, S905X2, S905Y2)
- "amlogic,meson-sm1-gpio-intc" for SM1 SoCs (S905D3, S905X3, S905Y3)
- "amlogic,meson-a1-gpio-intc" for A1 SoCs (A113L)
-- reg : Specifies base physical address and size of the registers.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value must be 2.
-- meson,channel-interrupts: Array with the 8 upstream hwirq numbers. These
- are the hwirqs used on the parent interrupt controller.
-
-Example:
-
-gpio_interrupt: interrupt-controller@9880 {
- compatible = "amlogic,meson-gxbb-gpio-intc",
- "amlogic,meson-gpio-intc";
- reg = <0x0 0x9880 0x0 0x10>;
- interrupt-controller;
- #interrupt-cells = <2>;
- meson,channel-interrupts = <64 65 66 67 68 69 70 71>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml
new file mode 100644
index 000000000000..d0fad930de9d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/amlogic,meson-gpio-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic Meson GPIO interrupt controller
+
+maintainers:
+ - Heiner Kallweit <hkallweit1@gmail.com>
+
+description: |
+ Meson SoCs contains an interrupt controller which is able to watch the SoC
+ pads and generate an interrupt on edge or level. The controller is essentially
+ a 256 pads to 8 or 12 GIC interrupt multiplexer, with a filter block to select
+ edge or level and polarity. It does not expose all 256 mux inputs because the
+ documentation shows that the upper part is not mapped to any pad. The actual
+ number of interrupts exposed depends on the SoC.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - const: amlogic,meson-gpio-intc
+ - items:
+ - enum:
+ - amlogic,meson8-gpio-intc
+ - amlogic,meson8b-gpio-intc
+ - amlogic,meson-gxbb-gpio-intc
+ - amlogic,meson-gxl-gpio-intc
+ - amlogic,meson-axg-gpio-intc
+ - amlogic,meson-g12a-gpio-intc
+ - amlogic,meson-sm1-gpio-intc
+ - amlogic,meson-a1-gpio-intc
+ - amlogic,meson-s4-gpio-intc
+ - amlogic,a4-gpio-intc
+ - amlogic,a4-gpio-ao-intc
+ - amlogic,a5-gpio-intc
+ - amlogic,c3-gpio-intc
+ - amlogic,s6-gpio-intc
+ - amlogic,s7-gpio-intc
+ - amlogic,s7d-gpio-intc
+ - amlogic,t7-gpio-intc
+ - const: amlogic,meson-gpio-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ amlogic,channel-interrupts:
+ description: Array with the upstream hwirq numbers
+ minItems: 2
+ maxItems: 12
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - amlogic,channel-interrupts
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: amlogic,a4-gpio-ao-intc
+then:
+ properties:
+ amlogic,channel-interrupts:
+ maxItems: 2
+else:
+ properties:
+ amlogic,channel-interrupts:
+ minItems: 8
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@9880 {
+ compatible = "amlogic,meson-gxbb-gpio-intc",
+ "amlogic,meson-gpio-intc";
+ reg = <0x9880 0x10>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ amlogic,channel-interrupts = <64 65 66 67 68 69 70 71>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/andestech,ativic32.txt b/Documentation/devicetree/bindings/interrupt-controller/andestech,ativic32.txt
deleted file mode 100644
index f4b4193d830e..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/andestech,ativic32.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-* Andestech Internal Vector Interrupt Controller
-
-The Internal Vector Interrupt Controller (IVIC) is a basic interrupt controller
-suitable for a simpler SoC platform not requiring a more sophisticated and
-bigger External Vector Interrupt Controller.
-
-
-Main node required properties:
-
-- compatible : should at least contain "andestech,ativic32".
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells: 1 cells and refer to interrupt-controller/interrupts
-
-Examples:
- intc: interrupt-controller {
- compatible = "andestech,ativic32";
- #interrupt-cells = <1>;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/andestech,plicsw.yaml b/Documentation/devicetree/bindings/interrupt-controller/andestech,plicsw.yaml
new file mode 100644
index 000000000000..eb2eb611ac09
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/andestech,plicsw.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/andestech,plicsw.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Andes machine-level software interrupt controller
+
+description:
+ In the Andes platform such as QiLai SoC, the PLIC module is instantiated a
+ second time with all interrupt sources tied to zero as the software interrupt
+ controller (PLIC_SW). PLIC_SW directly connects to the machine-mode
+ inter-processor interrupt lines of CPUs, so RISC-V per-CPU local interrupt
+ controller is the parent interrupt controller for PLIC_SW. PLIC_SW can
+ generate machine-mode inter-processor interrupts through programming its
+ registers.
+
+maintainers:
+ - Ben Zong-You Xie <ben717@andestech.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - andestech,qilai-plicsw
+ - const: andestech,plicsw
+
+ reg:
+ maxItems: 1
+
+ interrupts-extended:
+ minItems: 1
+ maxItems: 15872
+ description:
+ Specifies which harts are connected to the PLIC_SW. Each item must points
+ to a riscv,cpu-intc node, which has a riscv cpu node as parent.
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts-extended
+
+examples:
+ - |
+ interrupt-controller@400000 {
+ compatible = "andestech,qilai-plicsw", "andestech,plicsw";
+ reg = <0x400000 0x400000>;
+ interrupts-extended = <&cpu0intc 3>,
+ <&cpu1intc 3>,
+ <&cpu2intc 3>,
+ <&cpu3intc 3>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/apm,xgene1-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/apm,xgene1-msi.yaml
new file mode 100644
index 000000000000..49db952697f3
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/apm,xgene1-msi.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/apm,xgene1-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AppliedMicro X-Gene v1 PCIe MSI controller
+
+maintainers:
+ - Toan Le <toan@os.amperecomputing.com>
+
+properties:
+ compatible:
+ const: apm,xgene1-msi
+
+ msi-controller: true
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 16
+
+required:
+ - compatible
+ - msi-controller
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ msi@79000000 {
+ compatible = "apm,xgene1-msi";
+ msi-controller;
+ reg = <0x79000000 0x900000>;
+ interrupts = <0x0 0x10 0x4>,
+ <0x0 0x11 0x4>,
+ <0x0 0x12 0x4>,
+ <0x0 0x13 0x4>,
+ <0x0 0x14 0x4>,
+ <0x0 0x15 0x4>,
+ <0x0 0x16 0x4>,
+ <0x0 0x17 0x4>,
+ <0x0 0x18 0x4>,
+ <0x0 0x19 0x4>,
+ <0x0 0x1a 0x4>,
+ <0x0 0x1b 0x4>,
+ <0x0 0x1c 0x4>,
+ <0x0 0x1d 0x4>,
+ <0x0 0x1e 0x4>,
+ <0x0 0x1f 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml
index cf6c091a07b1..4be9b596a790 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml
@@ -31,13 +31,25 @@ description: |
This device also represents the FIQ interrupt sources on platforms using AIC,
which do not go through a discrete interrupt controller.
+ IPIs may be performed via MMIO registers on all variants of AIC. Starting
+ from A11, system registers may also be used for "fast" IPIs. Starting from
+ M1, even faster IPIs within the same cluster may be achieved by writing to
+ a "local" fast IPI register as opposed to using the "global" fast IPI
+ register.
+
allOf:
- $ref: /schemas/interrupt-controller.yaml#
properties:
compatible:
items:
- - const: apple,t8103-aic
+ - enum:
+ - apple,s5l8960x-aic
+ - apple,t7000-aic
+ - apple,s8000-aic
+ - apple,t8010-aic
+ - apple,t8015-aic
+ - apple,t8103-aic
- const: apple,aic
interrupt-controller: true
@@ -56,6 +68,8 @@ properties:
- 1: virtual HV timer
- 2: physical guest timer
- 3: virtual guest timer
+ - 4: 'efficient' CPU PMU
+ - 5: 'performance' CPU PMU
The 3rd cell contains the interrupt flags. This is normally
IRQ_TYPE_LEVEL_HIGH (4).
@@ -65,6 +79,37 @@ properties:
Specifies base physical address and size of the AIC registers.
maxItems: 1
+ power-domains:
+ maxItems: 1
+
+ affinities:
+ type: object
+ additionalProperties: false
+ description:
+ FIQ affinity can be expressed as a single "affinities" node,
+ containing a set of sub-nodes, one per FIQ with a non-default
+ affinity.
+ patternProperties:
+ "^.+-affinity$":
+ type: object
+ additionalProperties: false
+ properties:
+ apple,fiq-index:
+ description:
+ The interrupt number specified as a FIQ, and for which
+ the affinity is not the default.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 5
+
+ cpus:
+ description:
+ Should be a list of phandles to CPU nodes (as described in
+ Documentation/devicetree/bindings/arm/cpus.yaml).
+
+ required:
+ - apple,fiq-index
+ - cpus
+
required:
- compatible
- '#interrupt-cells'
diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml
new file mode 100644
index 000000000000..ee5a0dfff437
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic2.yaml
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/apple,aic2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple Interrupt Controller 2
+
+maintainers:
+ - Hector Martin <marcan@marcan.st>
+
+description: |
+ The Apple Interrupt Controller 2 is a simple interrupt controller present on
+ Apple ARM SoC platforms starting with t600x (M1 Pro and Max).
+
+ It provides the following features:
+
+ - Level-triggered hardware IRQs wired to SoC blocks
+ - Single mask bit per IRQ
+ - Automatic masking on event delivery (auto-ack)
+ - Software triggering (ORed with hw line)
+ - Automatic prioritization (single event/ack register per CPU, lower IRQs =
+ higher priority)
+ - Automatic masking on ack
+ - Support for multiple dies
+
+ This device also represents the FIQ interrupt sources on platforms using AIC,
+ which do not go through a discrete interrupt controller. It also handles
+ FIQ-based Fast IPIs.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - apple,t8112-aic
+ - apple,t6000-aic
+ - apple,t6020-aic
+ - const: apple,aic2
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ minimum: 3
+ maximum: 4
+ description: |
+ The 1st cell contains the interrupt type:
+ - 0: Hardware IRQ
+ - 1: FIQ
+
+ The 2nd cell contains the die ID (only present on apple,t6000-aic).
+
+ The next cell contains the interrupt number.
+ - HW IRQs: interrupt number
+ - FIQs:
+ - 0: physical HV timer
+ - 1: virtual HV timer
+ - 2: physical guest timer
+ - 3: virtual guest timer
+
+ The last cell contains the interrupt flags. This is normally
+ IRQ_TYPE_LEVEL_HIGH (4).
+
+ reg:
+ items:
+ - description: Address and size of the main AIC2 registers.
+ - description: Address and size of the AIC2 Event register.
+
+ reg-names:
+ items:
+ - const: core
+ - const: event
+
+ power-domains:
+ maxItems: 1
+
+ affinities:
+ type: object
+ additionalProperties: false
+ description:
+ FIQ affinity can be expressed as a single "affinities" node,
+ containing a set of sub-nodes, one per FIQ with a non-default
+ affinity.
+ patternProperties:
+ "^.+-affinity$":
+ type: object
+ additionalProperties: false
+ properties:
+ apple,fiq-index:
+ description:
+ The interrupt number specified as a FIQ, and for which
+ the affinity is not the default.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 5
+
+ cpus:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ description:
+ Should be a list of phandles to CPU nodes (as described in
+ Documentation/devicetree/bindings/arm/cpus.yaml).
+
+ required:
+ - apple,fiq-index
+ - cpus
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - interrupt-controller
+ - reg
+ - reg-names
+
+additionalProperties: false
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: apple,t8112-aic
+ then:
+ properties:
+ '#interrupt-cells':
+ const: 3
+ else:
+ properties:
+ '#interrupt-cells':
+ const: 4
+
+examples:
+ - |
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ aic: interrupt-controller@28e100000 {
+ compatible = "apple,t6000-aic", "apple,aic2";
+ #interrupt-cells = <4>;
+ interrupt-controller;
+ reg = <0x2 0x8e100000 0x0 0xc000>,
+ <0x2 0x8e10c000 0x0 0x4>;
+ reg-names = "core", "event";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
index c84f9fe7f254..bfd30aae682b 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: ARM Generic Interrupt Controller, version 3
maintainers:
- - Marc Zyngier <marc.zyngier@arm.com>
+ - Marc Zyngier <maz@kernel.org>
description: |
AArch64 SMP cores are often associated with a GICv3, providing Private
@@ -49,7 +49,7 @@ properties:
The 2nd cell contains the interrupt number for the interrupt type.
SPI interrupts are in the range [0-987]. PPI interrupts are in the
- range [0-15]. Extented SPI interrupts are in the range [0-1023].
+ range [0-15]. Extended SPI interrupts are in the range [0-1023].
Extended PPI interrupts are in the range [0-127].
The 3rd cell is the flags, encoded as follows:
@@ -60,7 +60,7 @@ properties:
The 4th cell is a phandle to a node describing a set of CPUs this
interrupt is affine to. The interrupt must be a PPI, and the node
pointed must be a subnode of the "ppi-partitions" subnode. For
- interrupt types other than PPI or PPIs that are not partitionned,
+ interrupt types other than PPI or PPIs that are not partitioned,
this cell must be zero. See the "ppi-partitions" node description
below.
@@ -78,7 +78,11 @@ properties:
- GIC Hypervisor interface (GICH)
- GIC Virtual CPU interface (GICV)
- GICC, GICH and GICV are optional.
+ GICC, GICH and GICV are optional, but must be described if the CPUs
+ support them. Examples of such CPUs are ARM's implementations of the
+ ARMv8.0 architecture such as Cortex-A32, A34, A35, A53, A57, A72 and
+ A73 (this list is not exhaustive).
+
minItems: 2
maxItems: 4096 # Should be enough?
@@ -102,9 +106,15 @@ properties:
$ref: /schemas/types.yaml#/definitions/uint32
maximum: 4096
+ dma-noncoherent:
+ description:
+ Present if the GIC redistributors permit programming shareability
+ and cacheability attributes but are connected to a non-coherent
+ downstream interconnect.
+
msi-controller:
description:
- Only present if the Message Based Interrupt functionnality is
+ Only present if the Message Based Interrupt functionality is
being exposed by the HW, and the mbi-ranges property present.
mbi-ranges:
@@ -122,22 +132,25 @@ properties:
Address property. Base address of an alias of the GICD region containing
only the {SET,CLR}SPI registers to be used if isolation is required,
and if supported by the HW.
- $ref: /schemas/types.yaml#/definitions/uint32-array
- items:
- minItems: 1
- maxItems: 2
+ oneOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - $ref: /schemas/types.yaml#/definitions/uint64
ppi-partitions:
type: object
+ additionalProperties: false
description:
PPI affinity can be expressed as a single "ppi-partitions" node,
containing a set of sub-nodes.
patternProperties:
"^interrupt-partition-[0-9]+$":
type: object
+ additionalProperties: false
properties:
affinity:
$ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ maxItems: 1
description:
Should be a list of phandles to CPU nodes (as described in
Documentation/devicetree/bindings/arm/cpus.yaml).
@@ -158,13 +171,18 @@ properties:
resets:
maxItems: 1
+ mediatek,broken-save-restore-fw:
+ type: boolean
+ description:
+ Asserts that the firmware on this device has issues saving and restoring
+ GICR registers when the GIC redistributors are powered off.
+
dependencies:
mbi-ranges: [ msi-controller ]
msi-controller: [ mbi-ranges ]
required:
- compatible
- - interrupts
- reg
patternProperties:
@@ -180,6 +198,12 @@ patternProperties:
compatible:
const: arm,gic-v3-its
+ dma-noncoherent:
+ description:
+ Present if the GIC ITS permits programming shareability and
+ cacheability attributes but is connected to a non-coherent
+ downstream interconnect.
+
msi-controller: true
"#msi-cells":
@@ -198,9 +222,8 @@ patternProperties:
(u32, u32) tuple describing the untranslated
address and size of the pre-ITS window.
$ref: /schemas/types.yaml#/definitions/uint32-array
- items:
- minItems: 2
- maxItems: 2
+ minItems: 2
+ maxItems: 2
required:
- compatible
@@ -239,6 +262,7 @@ examples:
};
};
+ - |
interrupt-controller@2c010000 {
compatible = "arm,gic-v3";
#interrupt-cells = <4>;
@@ -254,7 +278,7 @@ examples:
<0x2c040000 0x2000>, // GICC
<0x2c060000 0x2000>, // GICH
<0x2c080000 0x2000>; // GICV
- interrupts = <1 9 4>;
+ interrupts = <1 9 4 0>;
msi-controller@2c200000 {
compatible = "arm,gic-v3-its";
@@ -272,16 +296,15 @@ examples:
ppi-partitions {
part0: interrupt-partition-0 {
- affinity = <&cpu0 &cpu2>;
+ affinity = <&cpu0>, <&cpu2>;
};
part1: interrupt-partition-1 {
- affinity = <&cpu1 &cpu3>;
+ affinity = <&cpu1>, <&cpu3>;
};
};
};
-
device@0 {
reg = <0 4>;
interrupts = <1 1 4 &part0>;
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml
new file mode 100644
index 000000000000..99a266a62385
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5-iwb.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/arm,gic-v5-iwb.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Generic Interrupt Controller, version 5 Interrupt Wire Bridge (IWB)
+
+maintainers:
+ - Lorenzo Pieralisi <lpieralisi@kernel.org>
+ - Marc Zyngier <maz@kernel.org>
+
+description: |
+ The GICv5 architecture defines the guidelines to implement GICv5
+ compliant interrupt controllers for AArch64 systems.
+
+ The GICv5 specification can be found at
+ https://developer.arm.com/documentation/aes0070
+
+ GICv5 has zero or more Interrupt Wire Bridges (IWB) that are responsible
+ for translating wire signals into interrupt messages to the GICv5 ITS.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: arm,gic-v5-iwb
+
+ reg:
+ items:
+ - description: IWB control frame
+
+ "#address-cells":
+ const: 0
+
+ "#interrupt-cells":
+ description: |
+ The 1st cell corresponds to the IWB wire.
+
+ The 2nd cell is the flags, encoded as follows:
+ bits[3:0] trigger type and level flags.
+
+ 1 = low-to-high edge triggered
+ 2 = high-to-low edge triggered
+ 4 = active high level-sensitive
+ 8 = active low level-sensitive
+
+ const: 2
+
+ interrupt-controller: true
+
+ msi-parent:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - "#interrupt-cells"
+ - interrupt-controller
+ - msi-parent
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@2f000000 {
+ compatible = "arm,gic-v5-iwb";
+ reg = <0x2f000000 0x10000>;
+
+ #address-cells = <0>;
+
+ #interrupt-cells = <2>;
+ interrupt-controller;
+
+ msi-parent = <&its0 64>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml
new file mode 100644
index 000000000000..86ca7f3ac281
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml
@@ -0,0 +1,267 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/arm,gic-v5.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Generic Interrupt Controller, version 5
+
+maintainers:
+ - Lorenzo Pieralisi <lpieralisi@kernel.org>
+ - Marc Zyngier <maz@kernel.org>
+
+description: |
+ The GICv5 architecture defines the guidelines to implement GICv5
+ compliant interrupt controllers for AArch64 systems.
+
+ The GICv5 specification can be found at
+ https://developer.arm.com/documentation/aes0070
+
+ The GICv5 architecture is composed of multiple components:
+ - one or more IRS (Interrupt Routing Service)
+ - zero or more ITS (Interrupt Translation Service)
+
+ The architecture defines:
+ - PE-Private Peripheral Interrupts (PPI)
+ - Shared Peripheral Interrupts (SPI)
+ - Logical Peripheral Interrupts (LPI)
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: arm,gic-v5
+
+ "#address-cells":
+ enum: [ 1, 2 ]
+
+ "#size-cells":
+ enum: [ 1, 2 ]
+
+ ranges: true
+
+ "#interrupt-cells":
+ description: |
+ The 1st cell corresponds to the INTID.Type field in the INTID; 1 for PPI,
+ 3 for SPI. LPI interrupts must not be described in the bindings since
+ they are allocated dynamically by the software component managing them.
+
+ The 2nd cell contains the interrupt INTID.ID field.
+
+ The 3rd cell is the flags, encoded as follows:
+ bits[3:0] trigger type and level flags.
+
+ 1 = low-to-high edge triggered
+ 2 = high-to-low edge triggered
+ 4 = active high level-sensitive
+ 8 = active low level-sensitive
+
+ const: 3
+
+ interrupt-controller: true
+
+ interrupts:
+ description:
+ The VGIC maintenance interrupt.
+ maxItems: 1
+
+required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+ - ranges
+ - "#interrupt-cells"
+ - interrupt-controller
+
+patternProperties:
+ "^irs@[0-9a-f]+$":
+ type: object
+ description:
+ GICv5 has one or more Interrupt Routing Services (IRS) that are
+ responsible for handling IRQ state and routing.
+
+ additionalProperties: false
+
+ properties:
+ compatible:
+ const: arm,gic-v5-irs
+
+ reg:
+ minItems: 1
+ items:
+ - description: IRS config frames
+ - description: IRS setlpi frames
+
+ reg-names:
+ description:
+ Describe config and setlpi frames that are present.
+ "ns-" stands for non-secure, "s-" for secure, "realm-" for realm
+ and "el3-" for EL3.
+ minItems: 1
+ maxItems: 8
+ items:
+ enum: [ ns-config, s-config, realm-config, el3-config, ns-setlpi,
+ s-setlpi, realm-setlpi, el3-setlpi ]
+
+ "#address-cells":
+ enum: [ 1, 2 ]
+
+ "#size-cells":
+ enum: [ 1, 2 ]
+
+ ranges: true
+
+ dma-noncoherent:
+ description:
+ Present if the GIC IRS permits programming shareability and
+ cacheability attributes but is connected to a non-coherent
+ downstream interconnect.
+
+ cpus:
+ description:
+ CPUs managed by the IRS.
+
+ arm,iaffids:
+ $ref: /schemas/types.yaml#/definitions/uint16-array
+ description:
+ Interrupt AFFinity ID (IAFFID) associated with the CPU whose
+ CPU node phandle is at the same index in the cpus array.
+
+ patternProperties:
+ "^its@[0-9a-f]+$":
+ type: object
+ description:
+ GICv5 has zero or more Interrupt Translation Services (ITS) that are
+ used to route Message Signalled Interrupts (MSI) to the CPUs. Each
+ ITS is connected to an IRS.
+ additionalProperties: false
+
+ properties:
+ compatible:
+ const: arm,gic-v5-its
+
+ reg:
+ items:
+ - description: ITS config frames
+
+ reg-names:
+ description:
+ Describe config frames that are present.
+ "ns-" stands for non-secure, "s-" for secure, "realm-" for realm
+ and "el3-" for EL3.
+ minItems: 1
+ maxItems: 4
+ items:
+ enum: [ ns-config, s-config, realm-config, el3-config ]
+
+ "#address-cells":
+ enum: [ 1, 2 ]
+
+ "#size-cells":
+ enum: [ 1, 2 ]
+
+ ranges: true
+
+ dma-noncoherent:
+ description:
+ Present if the GIC ITS permits programming shareability and
+ cacheability attributes but is connected to a non-coherent
+ downstream interconnect.
+
+ patternProperties:
+ "^msi-controller@[0-9a-f]+$":
+ type: object
+ description:
+ GICv5 ITS has one or more translate register frames.
+ additionalProperties: false
+
+ properties:
+ reg:
+ items:
+ - description: ITS translate frames
+
+ reg-names:
+ description:
+ Describe translate frames that are present.
+ "ns-" stands for non-secure, "s-" for secure, "realm-" for realm
+ and "el3-" for EL3.
+ minItems: 1
+ maxItems: 4
+ items:
+ enum: [ ns-translate, s-translate, realm-translate, el3-translate ]
+
+ "#msi-cells":
+ description:
+ The single msi-cell is the DeviceID of the device which will
+ generate the MSI.
+ const: 1
+
+ msi-controller: true
+
+ required:
+ - reg
+ - reg-names
+ - "#msi-cells"
+ - msi-controller
+
+ required:
+ - compatible
+ - reg
+ - reg-names
+
+ required:
+ - compatible
+ - reg
+ - reg-names
+ - cpus
+ - arm,iaffids
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "arm,gic-v5";
+
+ #interrupt-cells = <3>;
+ interrupt-controller;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ interrupts = <1 25 4>;
+
+ irs@2f1a0000 {
+ compatible = "arm,gic-v5-irs";
+ reg = <0x2f1a0000 0x10000>; // IRS_CONFIG_FRAME
+ reg-names = "ns-config";
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ cpus = <&cpu0>, <&cpu1>, <&cpu2>, <&cpu3>, <&cpu4>, <&cpu5>, <&cpu6>, <&cpu7>;
+ arm,iaffids = /bits/ 16 <0 1 2 3 4 5 6 7>;
+
+ its@2f120000 {
+ compatible = "arm,gic-v5-its";
+ reg = <0x2f120000 0x10000>; // ITS_CONFIG_FRAME
+ reg-names = "ns-config";
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ msi-controller@2f130000 {
+ reg = <0x2f130000 0x10000>; // ITS_TRANSLATE_FRAME
+ reg-names = "ns-translate";
+
+ #msi-cells = <1>;
+ msi-controller;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
index ba282f4c9fd0..ee4c77dac201 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
@@ -58,14 +58,16 @@ properties:
- enum:
- nvidia,tegra186-agic
- nvidia,tegra194-agic
+ - nvidia,tegra234-agic
+ - nvidia,tegra264-agic
- const: nvidia,tegra210-agic
interrupt-controller: true
"#address-cells":
- enum: [ 0, 1 ]
+ enum: [ 0, 1, 2 ]
"#size-cells":
- const: 1
+ enum: [ 1, 2 ]
"#interrupt-cells":
const: 3
@@ -109,8 +111,8 @@ properties:
interrupts:
description: Interrupt source of the parent interrupt controller on
- secondary GICs, or VGIC maintenance interrupt on primary GIC (see
- below).
+ secondary GICs, or VGIC maintenance interrupt on primary GIC (see "GICv2
+ with virtualization extensions" paragraph in the "reg" property).
maxItems: 1
cpu-offset:
@@ -132,8 +134,8 @@ properties:
- items: # for "arm,cortex-a9-gic"
- const: PERIPHCLK
- const: PERIPHCLKEN
- - const: clk # for "arm,gic-400" and "nvidia,tegra210"
- - const: gclk #for "arm,pl390"
+ - const: clk # for "arm,gic-400" and "nvidia,tegra210"
+ - const: gclk # for "arm,pl390"
power-domains:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.txt
deleted file mode 100644
index 386ab37a383f..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-* ARM Nested Vector Interrupt Controller (NVIC)
-
-The NVIC provides an interrupt controller that is tightly coupled to
-Cortex-M based processor cores. The NVIC implemented on different SoCs
-vary in the number of interrupts and priority bits per interrupt.
-
-Main node required properties:
-
-- compatible : should be one of:
- "arm,v6m-nvic"
- "arm,v7m-nvic"
- "arm,v8m-nvic"
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The type shall be a <u32> and the value shall be 2.
-
- The 1st cell contains the interrupt number for the interrupt type.
-
- The 2nd cell is the priority of the interrupt.
-
-- reg : Specifies base physical address(s) and size of the NVIC registers.
- This is at a fixed address (0xe000e100) and size (0xc00).
-
-- arm,num-irq-priority-bits: The number of priority bits implemented by the
- given SoC
-
-Example:
-
- intc: interrupt-controller@e000e100 {
- compatible = "arm,v7m-nvic";
- #interrupt-cells = <2>;
- #address-cells = <1>;
- interrupt-controller;
- reg = <0xe000e100 0xc00>;
- arm,num-irq-priority-bits = <4>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.yaml
new file mode 100644
index 000000000000..32dfa2bf05d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/arm,nvic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Nested Vector Interrupt Controller (NVIC)
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+description:
+ The NVIC provides an interrupt controller that is tightly coupled to Cortex-M
+ based processor cores. The NVIC implemented on different SoCs vary in the
+ number of interrupts and priority bits per interrupt.
+
+properties:
+ compatible:
+ enum:
+ - arm,armv7m-nvic # deprecated
+ - arm,v6m-nvic
+ - arm,v7m-nvic
+ - arm,v8m-nvic
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 0
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ enum: [1, 2]
+ description: |
+ Number of cells to encode an interrupt source:
+ first = interrupt number, second = priority.
+
+ arm,num-irq-priority-bits:
+ description: Number of priority bits implemented by the SoC
+ minimum: 1
+ maximum: 8
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - arm,num-irq-priority-bits
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@e000e100 {
+ compatible = "arm,v7m-nvic";
+ #interrupt-cells = <2>;
+ #address-cells = <0>;
+ interrupt-controller;
+ reg = <0xe000e100 0xc00>;
+ arm,num-irq-priority-bits = <4>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt
deleted file mode 100644
index 2a1d16bdf834..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-* ARM Versatile FPGA interrupt controller
-
-One or more FPGA IRQ controllers can be synthesized in an ARM reference board
-such as the Integrator or Versatile family. The output of these different
-controllers are OR:ed together and fed to the CPU tile's IRQ input. Each
-instance can handle up to 32 interrupts.
-
-Required properties:
-- compatible: "arm,versatile-fpga-irq" or "oxsemi,ox810se-rps-irq"
-- interrupt-controller: Identifies the node as an interrupt controller
-- #interrupt-cells: The number of cells to define the interrupts. Must be 1
- as the FPGA IRQ controller has no configuration options for interrupt
- sources. The cell is a u32 and defines the interrupt number.
-- reg: The register bank for the FPGA interrupt controller.
-- clear-mask: a u32 number representing the mask written to clear all IRQs
- on the controller at boot for example.
-- valid-mask: a u32 number representing a bit mask determining which of
- the interrupts are valid. Unconnected/unused lines are set to 0, and
- the system till not make it possible for devices to request these
- interrupts.
-
-Example:
-
-pic: pic@14000000 {
- compatible = "arm,versatile-fpga-irq";
- #interrupt-cells = <1>;
- interrupt-controller;
- reg = <0x14000000 0x100>;
- clear-mask = <0xffffffff>;
- valid-mask = <0x003fffff>;
-};
-
-Optional properties:
-- interrupts: if the FPGA IRQ controller is cascaded, i.e. if its IRQ
- output is simply connected to the input of another IRQ controller,
- then the parent IRQ shall be specified in this property.
diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.yaml
new file mode 100644
index 000000000000..8d581b3aac3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/arm,versatile-fpga-irq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Versatile FPGA IRQ Controller
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description:
+ One or more FPGA IRQ controllers can be synthesized in an ARM reference board
+ such as the Integrator or Versatile family. The output of these different
+ controllers are OR:ed together and fed to the CPU tile's IRQ input. Each
+ instance can handle up to 32 interrupts.
+
+properties:
+ compatible:
+ const: arm,versatile-fpga-irq
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ reg:
+ maxItems: 1
+
+ clear-mask:
+ description: A mask written to clear all IRQs on the controller at boot.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ valid-mask:
+ description:
+ A bit mask determining which interrupts are valid; unused lines are set to 0.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ interrupts:
+ maxItems: 1
+
+additionalProperties: false
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+ - reg
+ - clear-mask
+ - valid-mask
+
+examples:
+ - |
+ interrupt-controller@14000000 {
+ compatible = "arm,versatile-fpga-irq";
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ reg = <0x14000000 0x100>;
+ clear-mask = <0xffffffff>;
+ valid-mask = <0x003fffff>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.txt
deleted file mode 100644
index 033cc82e5684..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-Device tree configuration for the I2C Interrupt Controller on the AST24XX and
-AST25XX SoCs.
-
-Required Properties:
-- #address-cells : should be 1
-- #size-cells : should be 1
-- #interrupt-cells : should be 1
-- compatible : should be "aspeed,ast2400-i2c-ic"
- or "aspeed,ast2500-i2c-ic"
-- reg : address start and range of controller
-- interrupts : interrupt number
-- interrupt-controller : denotes that the controller receives and fires
- new interrupts for child busses
-
-Example:
-
-i2c_ic: interrupt-controller@0 {
- #address-cells = <1>;
- #size-cells = <1>;
- #interrupt-cells = <1>;
- compatible = "aspeed,ast2400-i2c-ic";
- reg = <0x0 0x40>;
- interrupts = <12>;
- interrupt-controller;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.yaml
new file mode 100644
index 000000000000..6cff6a7231bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-i2c-ic.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2400-i2c-ic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed I2C Interrupt Controller (AST24XX/AST25XX)
+
+maintainers:
+ - Ryan Chen <ryan_chen@aspeedtech.com>
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-i2c-ic
+ - aspeed,ast2500-i2c-ic
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupts
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@0 {
+ compatible = "aspeed,ast2400-i2c-ic";
+ reg = <0x0 0x40>;
+ #interrupt-cells = <1>;
+ interrupts = <12>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.txt b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.txt
deleted file mode 100644
index e3fea0758d25..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Aspeed Vectored Interrupt Controller
-
-These bindings are for the Aspeed interrupt controller. The AST2400 and
-AST2500 SoC families include a legacy register layout before a re-designed
-layout, but the bindings do not prescribe the use of one or the other.
-
-Required properties:
-
-- compatible : "aspeed,ast2400-vic"
- "aspeed,ast2500-vic"
-
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-
-Example:
-
- vic: interrupt-controller@1e6c0080 {
- compatible = "aspeed,ast2400-vic";
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0x1e6c0080 0x80>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.yaml b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.yaml
new file mode 100644
index 000000000000..86516cd44b9d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2400-vic.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2400-vic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed Vectored Interrupt Controller
+
+maintainers:
+ - Andrew Jeffery <andrew@codeconstruct.com.au>
+
+description:
+ The AST2400 and AST2500 SoC families include a legacy register layout before
+ a redesigned layout, but the bindings do not prescribe the use of one or the
+ other.
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-vic
+ - aspeed,ast2500-vic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+ description:
+ Specifies the number of cells needed to encode an interrupt source. It
+ must be 1 as the VIC has no configuration options for interrupt sources.
+ The single cell defines the interrupt number.
+
+ valid-sources:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ description:
+ A bitmap of supported sources for the implementation.
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@1e6c0080 {
+ compatible = "aspeed,ast2400-vic";
+ reg = <0x1e6c0080 0x80>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ valid-sources = <0xffffffff 0x0007ffff>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2500-scu-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2500-scu-ic.yaml
new file mode 100644
index 000000000000..d998a9d69b91
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2500-scu-ic.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2025 Eddie James
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2500-scu-ic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed AST25XX, AST26XX, AST27XX SCU Interrupt Controller
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2500-scu-ic
+ - aspeed,ast2600-scu-ic0
+ - aspeed,ast2600-scu-ic1
+ - aspeed,ast2700-scu-ic0
+ - aspeed,ast2700-scu-ic1
+ - aspeed,ast2700-scu-ic2
+ - aspeed,ast2700-scu-ic3
+
+ reg:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupts
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@18 {
+ compatible = "aspeed,ast2500-scu-ic";
+ reg = <0x18 0x4>;
+ #interrupt-cells = <1>;
+ interrupts = <21>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml
new file mode 100644
index 000000000000..258d21fe6e35
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2700-intc.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/aspeed,ast2700-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed AST2700 Interrupt Controller
+
+description:
+ This interrupt controller hardware is second level interrupt controller that
+ is hooked to a parent interrupt controller. It's useful to combine multiple
+ interrupt sources into 1 interrupt to parent interrupt controller.
+
+maintainers:
+ - Kevin Chen <kevin_chen@aspeedtech.com>
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2700-intc-ic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+ description:
+ The first cell is the IRQ number, the second cell is the trigger
+ type as defined in interrupt.txt in this directory.
+
+ interrupts:
+ minItems: 1
+ maxItems: 10
+ description: |
+ Depend to which INTC0 or INTC1 used.
+ INTC0 and INTC1 are two kinds of interrupt controller with enable and raw
+ status registers for use.
+ INTC0 is used to assert GIC if interrupt in INTC1 asserted.
+ INTC1 is used to assert INTC0 if interrupt of modules asserted.
+ +-----+ +-------+ +---------+---module0
+ | GIC |---| INTC0 |--+--| INTC1_0 |---module2
+ | | | | | | |---...
+ +-----+ +-------+ | +---------+---module31
+ |
+ | +---------+---module0
+ +---| INTC1_1 |---module2
+ | | |---...
+ | +---------+---module31
+ ...
+ | +---------+---module0
+ +---| INTC1_5 |---module2
+ | |---...
+ +---------+---module31
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ interrupt-controller@12101b00 {
+ compatible = "aspeed,ast2700-intc-ic";
+ reg = <0 0x12101b00 0 0x10>;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ interrupts = <GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 193 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 194 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 195 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 196 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 197 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 198 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 199 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 200 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 201 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2xxx-scu-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2xxx-scu-ic.txt
deleted file mode 100644
index 251ed44171db..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/aspeed,ast2xxx-scu-ic.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Aspeed AST25XX and AST26XX SCU Interrupt Controller
-
-Required Properties:
- - #interrupt-cells : must be 1
- - compatible : must be "aspeed,ast2500-scu-ic",
- "aspeed,ast2600-scu-ic0" or
- "aspeed,ast2600-scu-ic1"
- - interrupts : interrupt from the parent controller
- - interrupt-controller : indicates that the controller receives and
- fires new interrupts for child busses
-
-Example:
-
- syscon@1e6e2000 {
- ranges = <0 0x1e6e2000 0x1a8>;
-
- scu_ic: interrupt-controller@18 {
- #interrupt-cells = <1>;
- compatible = "aspeed,ast2500-scu-ic";
- interrupts = <21>;
- interrupt-controller;
- };
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt
deleted file mode 100644
index 7079d44bf3ba..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-* Advanced Interrupt Controller (AIC)
-
-Required properties:
-- compatible: Should be:
- - "atmel,<chip>-aic" where <chip> can be "at91rm9200", "sama5d2",
- "sama5d3" or "sama5d4"
- - "microchip,<chip>-aic" where <chip> can be "sam9x60"
-
-- interrupt-controller: Identifies the node as an interrupt controller.
-- #interrupt-cells: The number of cells to define the interrupts. It should be 3.
- The first cell is the IRQ number (aka "Peripheral IDentifier" on datasheet).
- The second cell is used to specify flags:
- bits[3:0] trigger type and level flags:
- 1 = low-to-high edge triggered.
- 2 = high-to-low edge triggered.
- 4 = active high level-sensitive.
- 8 = active low level-sensitive.
- Valid combinations are 1, 2, 3, 4, 8.
- Default flag for internal sources should be set to 4 (active high).
- The third cell is used to specify the irq priority from 0 (lowest) to 7
- (highest).
-- reg: Should contain AIC registers location and length
-- atmel,external-irqs: u32 array of external irqs.
-
-Examples:
- /*
- * AIC
- */
- aic: interrupt-controller@fffff000 {
- compatible = "atmel,at91rm9200-aic";
- interrupt-controller;
- #interrupt-cells = <3>;
- reg = <0xfffff000 0x200>;
- };
-
- /*
- * An interrupt generating device that is wired to an AIC.
- */
- dma: dma-controller@ffffec00 {
- compatible = "atmel,at91sam9g45-dma";
- reg = <0xffffec00 0x200>;
- interrupts = <21 4 5>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
new file mode 100644
index 000000000000..d671ed884c9e
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/atmel,aic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Advanced Interrupt Controller (AIC)
+
+maintainers:
+ - Nicolas Ferre <nicolas.ferre@microchip.com>
+ - Dharma balasubiramani <dharma.b@microchip.com>
+
+description:
+ The Advanced Interrupt Controller (AIC) is an 8-level priority, individually
+ maskable, vectored interrupt controller providing handling of up to one
+ hundred and twenty-eight interrupt sources.
+
+properties:
+ compatible:
+ enum:
+ - atmel,at91rm9200-aic
+ - atmel,sama5d2-aic
+ - atmel,sama5d3-aic
+ - atmel,sama5d4-aic
+ - microchip,sam9x60-aic
+ - microchip,sam9x7-aic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 3
+ description: |
+ The 1st cell is the IRQ number (Peripheral IDentifier on datasheet).
+ The 2nd cell specifies flags:
+ bits[3:0] trigger type and level flags:
+ 1 = low-to-high edge triggered.
+ 2 = high-to-low edge triggered.
+ 4 = active high level-sensitive.
+ 8 = active low level-sensitive.
+ Valid combinations: 1, 2, 3, 4, 8.
+ Default for internal sources: 4 (active high).
+ The 3rd cell specifies irq priority from 0 (lowest) to 7 (highest).
+
+ interrupts:
+ maxItems: 1
+
+ atmel,external-irqs:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: u32 array of external irqs.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: atmel,at91rm9200-aic
+ then:
+ properties:
+ atmel,external-irqs:
+ minItems: 1
+ maxItems: 7
+ else:
+ properties:
+ atmel,external-irqs:
+ minItems: 1
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - atmel,external-irqs
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ interrupt-controller@fffff000 {
+ compatible = "atmel,at91rm9200-aic";
+ reg = <0xfffff000 0x200>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ atmel,external-irqs = <31>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2712-msix.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2712-msix.yaml
new file mode 100644
index 000000000000..c84614663b5d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2712-msix.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm2712-msix.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom bcm2712 MSI-X Interrupt Peripheral support
+
+maintainers:
+ - Stanimir Varbanov <svarbanov@suse.de>
+
+description:
+ This interrupt controller is used to provide interrupt vectors to the
+ generic interrupt controller (GIC) on bcm2712. It will be used as
+ external MSI-X controller for PCIe root complex.
+
+allOf:
+ - $ref: /schemas/interrupt-controller/msi-controller.yaml#
+
+properties:
+ compatible:
+ const: brcm,bcm2712-mip
+
+ reg:
+ items:
+ - description: Base register address
+ - description: PCIe message address
+
+ "#msi-cells":
+ const: 0
+
+ brcm,msi-offset:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Shift the allocated MSI's.
+
+unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - msi-controller
+ - msi-ranges
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ axi {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ msi-controller@1000130000 {
+ compatible = "brcm,bcm2712-mip";
+ reg = <0x10 0x00130000 0x00 0xc0>,
+ <0xff 0xfffff000 0x00 0x1000>;
+ msi-controller;
+ #msi-cells = <0>;
+ msi-ranges = <&gicv2 GIC_SPI 128 IRQ_TYPE_EDGE_RISING 64>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
deleted file mode 100644
index 0f1af5a1c12e..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
+++ /dev/null
@@ -1,131 +0,0 @@
-BCM2835 Top-Level ("ARMCTRL") Interrupt Controller
-
-The BCM2835 contains a custom top-level interrupt controller, which supports
-72 interrupt sources using a 2-level register scheme. The interrupt
-controller, or the HW block containing it, is referred to occasionally
-as "armctrl" in the SoC documentation, hence naming of this binding.
-
-The BCM2836 contains the same interrupt controller with the same
-interrupts, but the per-CPU interrupt controller is the root, and an
-interrupt there indicates that the ARMCTRL has an interrupt to handle.
-
-Required properties:
-
-- compatible : should be "brcm,bcm2835-armctrl-ic" or
- "brcm,bcm2836-armctrl-ic"
-- reg : Specifies base physical address and size of the registers.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 2.
-
- The 1st cell is the interrupt bank; 0 for interrupts in the "IRQ basic
- pending" register, or 1/2 respectively for interrupts in the "IRQ pending
- 1/2" register.
-
- The 2nd cell contains the interrupt number within the bank. Valid values
- are 0..7 for bank 0, and 0..31 for bank 1.
-
-Additional required properties for brcm,bcm2836-armctrl-ic:
-- interrupts : Specifies the interrupt on the parent for this interrupt
- controller to handle.
-
-The interrupt sources are as follows:
-
-Bank 0:
-0: ARM_TIMER
-1: ARM_MAILBOX
-2: ARM_DOORBELL_0
-3: ARM_DOORBELL_1
-4: VPU0_HALTED
-5: VPU1_HALTED
-6: ILLEGAL_TYPE0
-7: ILLEGAL_TYPE1
-
-Bank 1:
-0: TIMER0
-1: TIMER1
-2: TIMER2
-3: TIMER3
-4: CODEC0
-5: CODEC1
-6: CODEC2
-7: VC_JPEG
-8: ISP
-9: VC_USB
-10: VC_3D
-11: TRANSPOSER
-12: MULTICORESYNC0
-13: MULTICORESYNC1
-14: MULTICORESYNC2
-15: MULTICORESYNC3
-16: DMA0
-17: DMA1
-18: VC_DMA2
-19: VC_DMA3
-20: DMA4
-21: DMA5
-22: DMA6
-23: DMA7
-24: DMA8
-25: DMA9
-26: DMA10
-27: DMA11-14 - shared interrupt for DMA 11 to 14
-28: DMAALL - triggers on all dma interrupts (including chanel 15)
-29: AUX
-30: ARM
-31: VPUDMA
-
-Bank 2:
-0: HOSTPORT
-1: VIDEOSCALER
-2: CCP2TX
-3: SDC
-4: DSI0
-5: AVE
-6: CAM0
-7: CAM1
-8: HDMI0
-9: HDMI1
-10: PIXELVALVE1
-11: I2CSPISLV
-12: DSI1
-13: PWA0
-14: PWA1
-15: CPR
-16: SMI
-17: GPIO0
-18: GPIO1
-19: GPIO2
-20: GPIO3
-21: VC_I2C
-22: VC_SPI
-23: VC_I2SPCM
-24: VC_SDIO
-25: VC_UART
-26: SLIMBUS
-27: VEC
-28: CPG
-29: RNG
-30: VC_ARASANSDIO
-31: AVSPMON
-
-Example:
-
-/* BCM2835, first level */
-intc: interrupt-controller {
- compatible = "brcm,bcm2835-armctrl-ic";
- reg = <0x7e00b200 0x200>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
-
-/* BCM2836, second level */
-intc: interrupt-controller {
- compatible = "brcm,bcm2836-armctrl-ic";
- reg = <0x7e00b200 0x200>;
- interrupt-controller;
- #interrupt-cells = <2>;
-
- interrupt-parent = <&local_intc>;
- interrupts = <8>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.yaml
new file mode 100644
index 000000000000..625eb22bedf0
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.yaml
@@ -0,0 +1,162 @@
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm2835-armctrl-ic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: BCM2835 ARMCTRL Interrupt Controller
+
+maintainers:
+ - Florian Fainelli <florian.fainelli@broadcom.com>
+ - Raspberry Pi Kernel Maintenance <kernel-list@raspberrypi.com>
+
+description: >
+ The BCM2835 contains a custom top-level interrupt controller, which supports
+ 72 interrupt sources using a 2-level register scheme. The interrupt
+ controller, or the HW block containing it, is referred to occasionally as
+ "armctrl" in the SoC documentation, hence naming of this binding.
+
+ The BCM2836 contains the same interrupt controller with the same interrupts,
+ but the per-CPU interrupt controller is the root, and an interrupt there
+ indicates that the ARMCTRL has an interrupt to handle.
+
+ The interrupt sources are as follows:
+
+ Bank 0:
+ 0: ARM_TIMER
+ 1: ARM_MAILBOX
+ 2: ARM_DOORBELL_0
+ 3: ARM_DOORBELL_1
+ 4: VPU0_HALTED
+ 5: VPU1_HALTED
+ 6: ILLEGAL_TYPE0
+ 7: ILLEGAL_TYPE1
+
+ Bank 1:
+ 0: TIMER0
+ 1: TIMER1
+ 2: TIMER2
+ 3: TIMER3
+ 4: CODEC0
+ 5: CODEC1
+ 6: CODEC2
+ 7: VC_JPEG
+ 8: ISP
+ 9: VC_USB
+ 10: VC_3D
+ 11: TRANSPOSER
+ 12: MULTICORESYNC0
+ 13: MULTICORESYNC1
+ 14: MULTICORESYNC2
+ 15: MULTICORESYNC3
+ 16: DMA0
+ 17: DMA1
+ 18: VC_DMA2
+ 19: VC_DMA3
+ 20: DMA4
+ 21: DMA5
+ 22: DMA6
+ 23: DMA7
+ 24: DMA8
+ 25: DMA9
+ 26: DMA10
+ 27: DMA11-14 - shared interrupt for DMA 11 to 14
+ 28: DMAALL - triggers on all dma interrupts (including channel 15)
+ 29: AUX
+ 30: ARM
+ 31: VPUDMA
+
+ Bank 2:
+ 0: HOSTPORT
+ 1: VIDEOSCALER
+ 2: CCP2TX
+ 3: SDC
+ 4: DSI0
+ 5: AVE
+ 6: CAM0
+ 7: CAM1
+ 8: HDMI0
+ 9: HDMI1
+ 10: PIXELVALVE1
+ 11: I2CSPISLV
+ 12: DSI1
+ 13: PWA0
+ 14: PWA1
+ 15: CPR
+ 16: SMI
+ 17: GPIO0
+ 18: GPIO1
+ 19: GPIO2
+ 20: GPIO3
+ 21: VC_I2C
+ 22: VC_SPI
+ 23: VC_I2SPCM
+ 24: VC_SDIO
+ 25: VC_UART
+ 26: SLIMBUS
+ 27: VEC
+ 28: CPG
+ 29: RNG
+ 30: VC_ARASANSDIO
+ 31: AVSPMON
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm2835-armctrl-ic
+ - brcm,bcm2836-armctrl-ic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description: >
+ The 1st cell is the interrupt bank; 0 for interrupts in the "IRQ basic
+ pending" register, or 1/2 respectively for interrupts in the "IRQ pending
+ 1/2" register.
+
+ The 2nd cell contains the interrupt number within the bank. Valid values
+ are 0..7 for bank 0, and 0..31 for bank 1.
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: brcm,bcm2836-armctrl-ic
+ then:
+ required:
+ - interrupts
+ else:
+ properties:
+ interrupts: false
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@7e00b200 {
+ compatible = "brcm,bcm2835-armctrl-ic";
+ reg = <0x7e00b200 0x200>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+ - |
+ interrupt-controller@7e00b200 {
+ compatible = "brcm,bcm2836-armctrl-ic";
+ reg = <0x7e00b200 0x200>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <8>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.txt
deleted file mode 100644
index 8ced1696c325..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-BCM2836 per-CPU interrupt controller
-
-The BCM2836 has a per-cpu interrupt controller for the timer, PMU
-events, and SMP IPIs. One of the CPUs may receive interrupts for the
-peripheral (GPU) events, which chain to the BCM2835-style interrupt
-controller.
-
-Required properties:
-
-- compatible: Should be "brcm,bcm2836-l1-intc"
-- reg: Specifies base physical address and size of the
- registers
-- interrupt-controller: Identifies the node as an interrupt controller
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The value shall be 2
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-The interrupt sources are as follows:
-
-0: CNTPSIRQ
-1: CNTPNSIRQ
-2: CNTHPIRQ
-3: CNTVIRQ
-8: GPU_FAST
-9: PMU_FAST
-
-Example:
-
-local_intc: local_intc {
- compatible = "brcm,bcm2836-l1-intc";
- reg = <0x40000000 0x100>;
- interrupt-controller;
- #interrupt-cells = <2>;
- interrupt-parent = <&local_intc>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.yaml
new file mode 100644
index 000000000000..2ff390c1705b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm2836-l1-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: BCM2836 per-CPU interrupt controller
+
+maintainers:
+ - Stefan Wahren <wahrenst@gmx.net>
+ - Raspberry Pi Kernel Maintenance <kernel-list@raspberrypi.com>
+
+description:
+ The BCM2836 has a per-cpu interrupt controller for the timer, PMU
+ events, and SMP IPIs. One of the CPUs may receive interrupts for the
+ peripheral (GPU) events, which chain to the BCM2835-style interrupt
+ controller.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: brcm,bcm2836-l1-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ local_intc: interrupt-controller@40000000 {
+ compatible = "brcm,bcm2836-l1-intc";
+ reg = <0x40000000 0x100>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&local_intc>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt
deleted file mode 100644
index 37aea40d5430..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm3380-l2-intc.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Broadcom BCM3380-style Level 1 / Level 2 interrupt controller
-
-This interrupt controller shows up in various forms on many BCM338x/BCM63xx
-chipsets. It has the following properties:
-
-- outputs a single interrupt signal to its interrupt controller parent
-
-- contains one or more enable/status word pairs, which often appear at
- different offsets in different blocks
-
-- no atomic set/clear operations
-
-Required properties:
-
-- compatible: should be "brcm,bcm3380-l2-intc"
-- reg: specifies one or more enable/status pairs, in the following format:
- <enable_reg 0x4 status_reg 0x4>...
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: specifies the number of cells needed to encode an interrupt
- source, should be 1.
-- interrupts: specifies the interrupt line in the interrupt-parent controller
- node, valid values depend on the type of parent interrupt controller
-
-Optional properties:
-
-- brcm,irq-can-wake: if present, this means the L2 controller can be used as a
- wakeup source for system suspend/resume.
-
-Example:
-
-irq0_intc: interrupt-controller@10000020 {
- compatible = "brcm,bcm3380-l2-intc";
- reg = <0x10000024 0x4 0x1000002c 0x4>,
- <0x10000020 0x4 0x10000028 0x4>;
- interrupt-controller;
- #interrupt-cells = <1>;
- interrupt-parent = <&cpu_intc>;
- interrupts = <2>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.txt
deleted file mode 100644
index 2bc19b1ac877..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.txt
+++ /dev/null
@@ -1,55 +0,0 @@
-Broadcom BCM6345-style Level 1 interrupt controller
-
-This block is a first level interrupt controller that is typically connected
-directly to one of the HW INT lines on each CPU.
-
-Key elements of the hardware design include:
-
-- 32, 64 or 128 incoming level IRQ lines
-
-- Most onchip peripherals are wired directly to an L1 input
-
-- A separate instance of the register set for each CPU, allowing individual
- peripheral IRQs to be routed to any CPU
-
-- Contains one or more enable/status word pairs per CPU
-
-- No atomic set/clear operations
-
-- No polarity/level/edge settings
-
-- No FIFO or priority encoder logic; software is expected to read all
- 2-4 status words to determine which IRQs are pending
-
-Required properties:
-
-- compatible: should be "brcm,bcm<soc>-l1-intc", "brcm,bcm6345-l1-intc"
-- reg: specifies the base physical address and size of the registers;
- the number of supported IRQs is inferred from the size argument
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: specifies the number of cells needed to encode an interrupt
- source, should be 1.
-- interrupts: specifies the interrupt line(s) in the interrupt-parent controller
- node; valid values depend on the type of parent interrupt controller
-
-If multiple reg ranges and interrupt-parent entries are present on an SMP
-system, the driver will allow IRQ SMP affinity to be set up through the
-/proc/irq/ interface. In the simplest possible configuration, only one
-reg range and one interrupt-parent is needed.
-
-The driver operates in native CPU endian by default, there is no support for
-specifying an alternative endianness.
-
-Example:
-
-periph_intc: interrupt-controller@10000000 {
- compatible = "brcm,bcm63168-l1-intc", "brcm,bcm6345-l1-intc";
- reg = <0x10000020 0x20>,
- <0x10000040 0x20>;
-
- interrupt-controller;
- #interrupt-cells = <1>;
-
- interrupt-parent = <&cpu_intc>;
- interrupts = <2>, <3>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.yaml
new file mode 100644
index 000000000000..ca6a2ff43acd
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm6345-l1-intc.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm6345-l1-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM6345-style Level 1 interrupt controller
+
+maintainers:
+ - Simon Arlott <simon@octiron.net>
+
+description: >
+ This block is a first level interrupt controller that is typically connected
+ directly to one of the HW INT lines on each CPU.
+
+ Key elements of the hardware design include:
+
+ - 32, 64 or 128 incoming level IRQ lines
+
+ - Most onchip peripherals are wired directly to an L1 input
+
+ - A separate instance of the register set for each CPU, allowing individual
+ peripheral IRQs to be routed to any CPU
+
+ - Contains one or more enable/status word pairs per CPU
+
+ - No atomic set/clear operations
+
+ - No polarity/level/edge settings
+
+ - No FIFO or priority encoder logic; software is expected to read all
+ 2-4 status words to determine which IRQs are pending
+
+ If multiple reg ranges and interrupt-parent entries are present on an SMP
+ system, the driver will allow IRQ SMP affinity to be set up through the
+ /proc/irq/ interface. In the simplest possible configuration, only one
+ reg range and one interrupt-parent is needed.
+
+ The driver operates in native CPU endian by default, there is no support for
+ specifying an alternative endianness.
+
+properties:
+ compatible:
+ const: brcm,bcm6345-l1-intc
+
+ reg:
+ description: One entry per CPU core
+ minItems: 1
+ maxItems: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupts:
+ description: One entry per CPU core
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@10000000 {
+ compatible = "brcm,bcm6345-l1-intc";
+ reg = <0x10000020 0x20>,
+ <0x10000040 0x20>;
+
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ interrupts = <2>, <3>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt
deleted file mode 100644
index 5ddef1dc0c1a..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-Broadcom BCM7038-style Level 1 interrupt controller
-
-This block is a first level interrupt controller that is typically connected
-directly to one of the HW INT lines on each CPU. Every BCM7xxx set-top chip
-since BCM7038 has contained this hardware.
-
-Key elements of the hardware design include:
-
-- 64, 96, 128, or 160 incoming level IRQ lines
-
-- Most onchip peripherals are wired directly to an L1 input
-
-- A separate instance of the register set for each CPU, allowing individual
- peripheral IRQs to be routed to any CPU
-
-- Atomic mask/unmask operations
-
-- No polarity/level/edge settings
-
-- No FIFO or priority encoder logic; software is expected to read all
- 2-5 status words to determine which IRQs are pending
-
-Required properties:
-
-- compatible: should be "brcm,bcm7038-l1-intc"
-- reg: specifies the base physical address and size of the registers;
- the number of supported IRQs is inferred from the size argument
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: specifies the number of cells needed to encode an interrupt
- source, should be 1.
-- interrupts: specifies the interrupt line(s) in the interrupt-parent controller
- node; valid values depend on the type of parent interrupt controller
-
-Optional properties:
-
-- brcm,irq-can-wake: If present, this means the L1 controller can be used as a
- wakeup source for system suspend/resume.
-
-Optional properties:
-
-- brcm,int-fwd-mask: if present, a bit mask to indicate which interrupts
- have already been configured by the firmware and should be left unmanaged.
- This should have one 32-bit word per status/set/clear/mask group.
-
-If multiple reg ranges and interrupt-parent entries are present on an SMP
-system, the driver will allow IRQ SMP affinity to be set up through the
-/proc/irq/ interface. In the simplest possible configuration, only one
-reg range and one interrupt-parent is needed.
-
-Example:
-
-periph_intc: periph_intc@1041a400 {
- compatible = "brcm,bcm7038-l1-intc";
- reg = <0x1041a400 0x30 0x1041a600 0x30>;
-
- interrupt-controller;
- #interrupt-cells = <1>;
-
- interrupt-parent = <&cpu_intc>;
- interrupts = <2>, <3>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml
new file mode 100644
index 000000000000..5ecb6faa70dc
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7038-l1-intc.yaml
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm7038-l1-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM7038-style Level 1 interrupt controller
+
+description: >
+ This block is a first level interrupt controller that is typically connected
+ directly to one of the HW INT lines on each CPU. Every BCM7xxx set-top chip
+ since BCM7038 has contained this hardware.
+
+ Key elements of the hardware design include:
+
+ - 64, 96, 128, or 160 incoming level IRQ lines
+
+ - Most onchip peripherals are wired directly to an L1 input
+
+ - A separate instance of the register set for each CPU, allowing individual
+ peripheral IRQs to be routed to any CPU
+
+ - Atomic mask/unmask operations
+
+ - No polarity/level/edge settings
+
+ - No FIFO or priority encoder logic; software is expected to read all
+ 2-5 status words to determine which IRQs are pending
+
+ If multiple reg ranges and interrupt-parent entries are present on an SMP
+ system, the driver will allow IRQ SMP affinity to be set up through the
+ /proc/irq/ interface. In the simplest possible configuration, only one
+ reg range and one interrupt-parent is needed.
+
+maintainers:
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: brcm,bcm7038-l1-intc
+
+ reg:
+ description: >
+ Specifies the base physical address and size of the registers
+ the number of supported IRQs is inferred from the size argument
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupts:
+ description: >
+ Specifies the interrupt line(s) in the interrupt-parent controller node;
+ valid values depend on the type of parent interrupt controller
+
+ brcm,irq-can-wake:
+ type: boolean
+ description: >
+ If present, this means the L1 controller can be used as a
+ wakeup source for system suspend/resume.
+
+ brcm,int-fwd-mask:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description:
+ If present, a bit mask to indicate which interrupts have already been
+ configured by the firmware and should be left unmanaged. This should
+ have one 32-bit word per status/set/clear/mask group.
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ periph_intc: interrupt-controller@1041a400 {
+ compatible = "brcm,bcm7038-l1-intc";
+ reg = <0x1041a400 0x30>, <0x1041a600 0x30>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupt-parent = <&cpu_intc>;
+ interrupts = <2>, <3>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt
deleted file mode 100644
index addd86b6ca2f..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-Broadcom BCM7120-style Level 2 interrupt controller
-
-This interrupt controller hardware is a second level interrupt controller that
-is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based
-platforms. It can be found on BCM7xxx products starting with BCM7120.
-
-Such an interrupt controller has the following hardware design:
-
-- outputs multiple interrupts signals towards its interrupt controller parent
-
-- controls how some of the interrupts will be flowing, whether they will
- directly output an interrupt signal towards the interrupt controller parent,
- or if they will output an interrupt signal at this 2nd level interrupt
- controller, in particular for UARTs
-
-- has one 32-bit enable word and one 32-bit status word
-
-- no atomic set/clear operations
-
-- not all bits within the interrupt controller actually map to an interrupt
-
-The typical hardware layout for this controller is represented below:
-
-2nd level interrupt line Outputs for the parent controller (e.g: ARM GIC)
-
-0 -----[ MUX ] ------------|==========> GIC interrupt 75
- \-----------\
- |
-1 -----[ MUX ] --------)---|==========> GIC interrupt 76
- \------------|
- |
-2 -----[ MUX ] --------)---|==========> GIC interrupt 77
- \------------|
- |
-3 ---------------------|
-4 ---------------------|
-5 ---------------------|
-7 ---------------------|---|===========> GIC interrupt 66
-9 ---------------------|
-10 --------------------|
-11 --------------------/
-
-6 ------------------------\
- |===========> GIC interrupt 64
-8 ------------------------/
-
-12 ........................ X
-13 ........................ X (not connected)
-..
-31 ........................ X
-
-Required properties:
-
-- compatible: should be "brcm,bcm7120-l2-intc"
-- reg: specifies the base physical address and size of the registers
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: specifies the number of cells needed to encode an interrupt
- source, should be 1.
-- interrupts: specifies the interrupt line(s) in the interrupt-parent controller
- node, valid values depend on the type of parent interrupt controller
-- brcm,int-map-mask: 32-bits bit mask describing how many and which interrupts
- are wired to this 2nd level interrupt controller, and how they match their
- respective interrupt parents. Should match exactly the number of interrupts
- specified in the 'interrupts' property.
-
-Optional properties:
-
-- brcm,irq-can-wake: if present, this means the L2 controller can be used as a
- wakeup source for system suspend/resume.
-
-- brcm,int-fwd-mask: if present, a bit mask to configure the interrupts which
- have a mux gate, typically UARTs. Setting these bits will make their
- respective interrupt outputs bypass this 2nd level interrupt controller
- completely; it is completely transparent for the interrupt controller
- parent. This should have one 32-bit word per enable/status pair.
-
-Example:
-
-irq0_intc: interrupt-controller@f0406800 {
- compatible = "brcm,bcm7120-l2-intc";
- interrupt-parent = <&intc>;
- #interrupt-cells = <1>;
- reg = <0xf0406800 0x8>;
- interrupt-controller;
- interrupts = <0x0 0x42 0x0>, <0x0 0x40 0x0>;
- brcm,int-map-mask = <0xeb8>, <0x140>;
- brcm,int-fwd-mask = <0x7>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml
new file mode 100644
index 000000000000..0fcbe304cd05
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.yaml
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,bcm7120-l2-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM7120-style Level 2 and Broadcom BCM3380 Level 1 / Level 2
+
+maintainers:
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+description: >
+ This interrupt controller hardware is a second level interrupt controller that
+ is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based
+ platforms. It can be found on BCM7xxx products starting with BCM7120.
+
+ Such an interrupt controller has the following hardware design:
+
+ - outputs multiple interrupts signals towards its interrupt controller parent
+
+ - controls how some of the interrupts will be flowing, whether they will
+ directly output an interrupt signal towards the interrupt controller parent,
+ or if they will output an interrupt signal at this 2nd level interrupt
+ controller, in particular for UARTs
+
+ - has one 32-bit enable word and one 32-bit status word
+
+ - no atomic set/clear operations
+
+ - not all bits within the interrupt controller actually map to an interrupt
+
+ The typical hardware layout for this controller is represented below:
+
+ 2nd level interrupt line Outputs for the parent controller (e.g: ARM GIC)
+
+ 0 -----[ MUX ] ------------|==========> GIC interrupt 75
+ \-----------\
+ |
+ 1 -----[ MUX ] --------)---|==========> GIC interrupt 76
+ \------------|
+ |
+ 2 -----[ MUX ] --------)---|==========> GIC interrupt 77
+ \------------|
+ |
+ 3 ---------------------|
+ 4 ---------------------|
+ 5 ---------------------|
+ 7 ---------------------|---|===========> GIC interrupt 66
+ 9 ---------------------|
+ 10 --------------------|
+ 11 --------------------/
+
+ 6 ------------------------\
+ |===========> GIC interrupt 64
+ 8 ------------------------/
+
+ 12 ........................ X
+ 13 ........................ X (not connected)
+ ..
+ 31 ........................ X
+
+ The BCM3380 Level 1 / Level 2 interrupt controller shows up in various forms
+ on many BCM338x/BCM63xx chipsets. It has the following properties:
+
+ - outputs a single interrupt signal to its interrupt controller parent
+
+ - contains one or more enable/status word pairs, which often appear at
+ different offsets in different blocks
+
+ - no atomic set/clear operations
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm7120-l2-intc
+ - brcm,bcm3380-l2-intc
+
+ reg:
+ minItems: 1
+ maxItems: 4
+ description: >
+ Specifies the base physical address and size of the registers
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 32
+
+ brcm,int-map-mask:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: >
+ 32-bits bit mask describing how many and which interrupts are wired to
+ this 2nd level interrupt controller, and how they match their respective
+ interrupt parents. Should match exactly the number of interrupts
+ specified in the 'interrupts' property.
+
+ brcm,irq-can-wake:
+ type: boolean
+ description: >
+ If present, this means the L2 controller can be used as a wakeup source
+ for system suspend/resume.
+
+ brcm,int-fwd-mask:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 1
+ description: >
+ if present, a bit mask to configure the interrupts which have a mux gate,
+ typically UARTs. Setting these bits will make their respective interrupt
+ outputs bypass this 2nd level interrupt controller completely; it is
+ completely transparent for the interrupt controller parent. This should
+ have one 32-bit word per enable/status pair.
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+examples:
+ - |
+ irq0_intc: interrupt-controller@f0406800 {
+ compatible = "brcm,bcm7120-l2-intc";
+ interrupt-parent = <&intc>;
+ #interrupt-cells = <1>;
+ reg = <0xf0406800 0x8>;
+ interrupt-controller;
+ interrupts = <0x0 0x42 0x0>, <0x0 0x40 0x0>;
+ brcm,int-map-mask = <0xeb8>, <0x140>;
+ brcm,int-fwd-mask = <0x7>;
+ };
+
+ - |
+ irq1_intc: interrupt-controller@10000020 {
+ compatible = "brcm,bcm3380-l2-intc";
+ reg = <0x10000024 0x4>, <0x1000002c 0x4>,
+ <0x10000020 0x4>, <0x10000028 0x4>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupt-parent = <&cpu_intc>;
+ interrupts = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt
deleted file mode 100644
index 021cf822395c..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-Broadcom Generic Level 2 Interrupt Controller
-
-Required properties:
-
-- compatible: should be one of:
- "brcm,hif-spi-l2-intc" or
- "brcm,upg-aux-aon-l2-intc" or
- "brcm,l2-intc" for latched interrupt controllers
- should be "brcm,bcm7271-l2-intc" for level interrupt controllers
-- reg: specifies the base physical address and size of the registers
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: specifies the number of cells needed to encode an
- interrupt source. Should be 1.
-- interrupts: specifies the interrupt line in the interrupt-parent irq space
- to be used for cascading
-
-Optional properties:
-
-- brcm,irq-can-wake: If present, this means the L2 controller can be used as a
- wakeup source for system suspend/resume.
-
-Example:
-
-hif_intr2_intc: interrupt-controller@f0441000 {
- compatible = "brcm,l2-intc";
- reg = <0xf0441000 0x30>;
- interrupt-controller;
- #interrupt-cells = <1>;
- interrupt-parent = <&intc>;
- interrupts = <0x0 0x20 0x0>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml
new file mode 100644
index 000000000000..8961afca96f1
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/brcm,l2-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom Generic Level 2 Interrupt Controller
+
+maintainers:
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - brcm,hif-spi-l2-intc
+ - brcm,upg-aux-aon-l2-intc
+ - const: brcm,l2-intc
+ - items:
+ - enum:
+ - brcm,bcm2711-l2-intc
+ - const: brcm,l2-intc
+ - items:
+ - const: brcm,bcm7271-l2-intc
+ - items:
+ - const: brcm,l2-intc
+
+ reg:
+ maxItems: 1
+ description: >
+ Specifies the base physical address and size of the registers
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-names:
+ maxItems: 1
+
+ brcm,irq-can-wake:
+ type: boolean
+ description: >
+ If present, this means the L2 controller can be used as a wakeup source
+ for system suspend/resume.
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+examples:
+ - |
+ hif_intr2_intc: interrupt-controller@f0441000 {
+ compatible = "brcm,l2-intc";
+ reg = <0xf0441000 0x30>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupt-parent = <&intc>;
+ interrupts = <0x0 0x20 0x0>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-mx.txt b/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-mx.txt
deleted file mode 100644
index d4de980e55fa..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-mx.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-* Xtensa Interrupt Distributor and Programmable Interrupt Controller (MX)
-
-Required properties:
-- compatible: Should be "cdns,xtensa-mx".
-
-Remaining properties have exact same meaning as in Xtensa PIC
-(see cdns,xtensa-pic.txt).
-
-Examples:
- pic: pic {
- compatible = "cdns,xtensa-mx";
- /* one cell: internal irq number,
- * two cells: second cell == 0: internal irq number
- * second cell == 1: external irq number
- */
- #interrupt-cells = <2>;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.txt
deleted file mode 100644
index 026ef4cfc1d5..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* Xtensa built-in Programmable Interrupt Controller (PIC)
-
-Required properties:
-- compatible: Should be "cdns,xtensa-pic".
-- interrupt-controller: Identifies the node as an interrupt controller.
-- #interrupt-cells: The number of cells to define the interrupts.
- It may be either 1 or 2.
- When it's 1, the first cell is the internal IRQ number.
- When it's 2, the first cell is the IRQ number, and the second cell
- specifies whether it's internal (0) or external (1).
- Periferals are usually connected to a fixed external IRQ, but for different
- core variants it may be mapped to different internal IRQ.
- IRQ sensitivity and priority are fixed for each core variant and may not be
- changed at runtime.
-
-Examples:
- pic: pic {
- compatible = "cdns,xtensa-pic";
- /* one cell: internal irq number,
- * two cells: second cell == 0: internal irq number
- * second cell == 1: external irq number
- */
- #interrupt-cells = <2>;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.yaml
new file mode 100644
index 000000000000..6773207fee01
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/cdns,xtensa-pic.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2025 Max Filippov <jcmvbkbc@gmail.com>
+
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/cdns,xtensa-pic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xtensa Interrupt Controllers
+
+maintainers:
+ - Max Filippov <jcmvbkbc@gmail.com>
+
+description:
+ Xtensa Interrupt Distributor and Programmable Interrupt Controller (MX) and
+ Xtensa built-in Programmable Interrupt Controller (PIC)
+
+properties:
+ compatible:
+ enum:
+ - cdns,xtensa-mx
+ - cdns,xtensa-pic
+
+ '#interrupt-cells':
+ enum: [ 1, 2 ]
+ description:
+ Number of cells to define the interrupts. When 1, the first cell is the
+ internal IRQ number; when 2, the second cell specifies internal (0) or
+ external (1).
+
+ interrupt-controller: true
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "cdns,xtensa-pic";
+ /* one cell: internal irq number,
+ * two cells: second cell == 0: internal irq number
+ * second cell == 1: external irq number
+ */
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/chrp,open-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/chrp,open-pic.yaml
new file mode 100644
index 000000000000..642738512f3c
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/chrp,open-pic.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/chrp,open-pic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Open PIC Interrupt Controller
+
+maintainers:
+ - Rob Herring <robh@kernel.org>
+
+description:
+ This binding specifies what properties must be available in the device tree
+ representation of an Open PIC compliant interrupt controller. This binding is
+ based on the binding defined for Open PIC in [1] and is a superset of that
+ binding.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: fsl,mpic
+ - const: chrp,open-pic
+ - const: chrp,open-pic
+
+ device_type:
+ const: open-pci
+ deprecated: true
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#address-cells':
+ const: 0
+
+ '#interrupt-cells':
+ description:
+ A value of 4 means that interrupt specifiers contain the interrupt-type or
+ type-specific information cells.
+ enum: [ 2, 4 ]
+
+ pic-no-reset:
+ description: Indicates the PIC shall not be reset during runtime initialization.
+ type: boolean
+
+ single-cpu-affinity:
+ description:
+ If present, non-IPI interrupts will be routed to a single CPU at a time.
+ type: boolean
+
+ last-interrupt-source:
+ description:
+ Some MPICs do not correctly report the number of hardware sources in the
+ global feature registers. This value, if specified, overrides the value
+ read from MPIC_GREG_FEATURE_LAST_SRC.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#address-cells'
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@40000 {
+ compatible = "chrp,open-pic";
+ reg = <0x40000 0x40000>;
+ interrupt-controller;
+ #address-cells = <0>;
+ #interrupt-cells = <2>;
+ pic-no-reset;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/cirrus,clps711x-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/cirrus,clps711x-intc.txt
deleted file mode 100644
index 969b4582ec60..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/cirrus,clps711x-intc.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-Cirrus Logic CLPS711X Interrupt Controller
-
-Required properties:
-
-- compatible: Should be "cirrus,ep7209-intc".
-- reg: Specifies base physical address of the registers set.
-- interrupt-controller: Identifies the node as an interrupt controller.
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-
-The interrupt sources are as follows:
-ID Name Description
----------------------------
-1: BLINT Battery low (FIQ)
-3: MCINT Media changed (FIQ)
-4: CSINT CODEC sound
-5: EINT1 External 1
-6: EINT2 External 2
-7: EINT3 External 3
-8: TC1OI TC1 under flow
-9: TC2OI TC2 under flow
-10: RTCMI RTC compare match
-11: TINT 64Hz tick
-12: UTXINT1 UART1 transmit FIFO half empty
-13: URXINT1 UART1 receive FIFO half full
-14: UMSINT UART1 modem status changed
-15: SSEOTI SSI1 end of transfer
-16: KBDINT Keyboard
-17: SS2RX SSI2 receive FIFO half or greater full
-18: SS2TX SSI2 transmit FIFO less than half empty
-28: UTXINT2 UART2 transmit FIFO half empty
-29: URXINT2 UART2 receive FIFO half full
-32: DAIINT DAI interface (FIQ)
-
-Example:
- intc: interrupt-controller {
- compatible = "cirrus,ep7312-intc", "cirrus,ep7209-intc";
- reg = <0x80000000 0x4000>;
- interrupt-controller;
- #interrupt-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/cirrus,ep7209-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/cirrus,ep7209-intc.yaml
new file mode 100644
index 000000000000..d3cc49d29e10
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/cirrus,ep7209-intc.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/cirrus,ep7209-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cirrus Logic CLPS711X Interrupt Controller
+
+maintainers:
+ - Alexander Shiyan <shc_work@mail.ru>
+
+description: >
+ Cirrus Logic CLPS711X Interrupt Controller
+
+ The interrupt sources are as follows:
+ ID Name Description
+ ---------------------------
+ 1: BLINT Battery low (FIQ)
+ 3: MCINT Media changed (FIQ)
+ 4: CSINT CODEC sound
+ 5: EINT1 External 1
+ 6: EINT2 External 2
+ 7: EINT3 External 3
+ 8: TC1OI TC1 under flow
+ 9: TC2OI TC2 under flow
+ 10: RTCMI RTC compare match
+ 11: TINT 64Hz tick
+ 12: UTXINT1 UART1 transmit FIFO half empty
+ 13: URXINT1 UART1 receive FIFO half full
+ 14: UMSINT UART1 modem status changed
+ 15: SSEOTI SSI1 end of transfer
+ 16: KBDINT Keyboard
+ 17: SS2RX SSI2 receive FIFO half or greater full
+ 18: SS2TX SSI2 transmit FIFO less than half empty
+ 28: UTXINT2 UART2 transmit FIFO half empty
+ 29: URXINT2 UART2 receive FIFO half full
+ 32: DAIINT DAI interface (FIQ)
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: cirrus,ep7312-intc
+ - const: cirrus,ep7209-intc
+ - items:
+ - const: cirrus,ep7209-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@80000000 {
+ compatible = "cirrus,ep7312-intc", "cirrus,ep7209-intc";
+ reg = <0x80000000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/cnxt,cx92755-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/cnxt,cx92755-ic.yaml
new file mode 100644
index 000000000000..3f016cf47812
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/cnxt,cx92755-ic.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/cnxt,cx92755-ic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Conexant Digicolor Interrupt Controller
+
+maintainers:
+ - Baruch Siach <baruch@tkos.co.il>
+
+description: Conexant Digicolor Interrupt Controller
+
+properties:
+ compatible:
+ const: cnxt,cx92755-ic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ syscon:
+ description: A phandle to the syscon node describing UC registers
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - syscon
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@f0000040 {
+ compatible = "cnxt,cx92755-ic";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ reg = <0xf0000040 0x40>;
+ syscon = <&uc_regs>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.txt
deleted file mode 100644
index 44286dcbac62..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-==============================
-C-SKY APB Interrupt Controller
-==============================
-
-C-SKY APB Interrupt Controller is a simple soc interrupt controller
-on the apb bus and we only use it as root irq controller.
-
- - csky,apb-intc is used in a lot of csky fpgas and socs, it support 64 irq nums.
- - csky,dual-apb-intc consists of 2 apb-intc and 128 irq nums supported.
- - csky,gx6605s-intc is gx6605s soc internal irq interrupt controller, 64 irq nums.
-
-=============================
-intc node bindings definition
-=============================
-
- Description: Describes APB interrupt controller
-
- PROPERTIES
-
- - compatible
- Usage: required
- Value type: <string>
- Definition: must be "csky,apb-intc"
- "csky,dual-apb-intc"
- "csky,gx6605s-intc"
- - #interrupt-cells
- Usage: required
- Value type: <u32>
- Definition: must be <1>
- - reg
- Usage: required
- Value type: <u32 u32>
- Definition: <phyaddr size> in soc from cpu view
- - interrupt-controller:
- Usage: required
- - csky,support-pulse-signal:
- Usage: select
- Description: to support pulse signal flag
-
-Examples:
----------
-
- intc: interrupt-controller@500000 {
- compatible = "csky,apb-intc";
- #interrupt-cells = <1>;
- reg = <0x00500000 0x400>;
- interrupt-controller;
- };
-
- intc: interrupt-controller@500000 {
- compatible = "csky,dual-apb-intc";
- #interrupt-cells = <1>;
- reg = <0x00500000 0x400>;
- interrupt-controller;
- };
-
- intc: interrupt-controller@500000 {
- compatible = "csky,gx6605s-intc";
- #interrupt-cells = <1>;
- reg = <0x00500000 0x400>;
- interrupt-controller;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.yaml
new file mode 100644
index 000000000000..902648ead975
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/csky,apb-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: C-SKY APB Interrupt Controller
+
+maintainers:
+ - Guo Ren <guoren@kernel.org>
+
+description: >
+ C-SKY APB Interrupt Controller is a simple soc interrupt controller on the apb
+ bus and we only use it as root irq controller.
+
+ - csky,apb-intc is used in a lot of csky fpgas and socs, it support 64 irq nums.
+ - csky,dual-apb-intc consists of 2 apb-intc and 128 irq nums supported.
+ - csky,gx6605s-intc is gx6605s soc internal irq interrupt controller, 64 irq nums.
+
+properties:
+ compatible:
+ enum:
+ - csky,apb-intc
+ - csky,dual-apb-intc
+ - csky,gx6605s-intc
+
+ reg:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupt-controller: true
+
+ csky,support-pulse-signal:
+ type: boolean
+ description: Support for pulse signal flag.
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupt-controller
+
+examples:
+ - |
+ intc: interrupt-controller@500000 {
+ compatible = "csky,apb-intc";
+ #interrupt-cells = <1>;
+ reg = <0x00500000 0x400>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt
deleted file mode 100644
index e6bbcae4d07f..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-===========================================
-C-SKY Multi-processors Interrupt Controller
-===========================================
-
-C-SKY Multi-processors Interrupt Controller is designed for ck807/ck810/ck860
-SMP soc, and it also could be used in non-SMP system.
-
-Interrupt number definition:
- 0-15 : software irq, and we use 15 as our IPI_IRQ.
- 16-31 : private irq, and we use 16 as the co-processor timer.
- 31-1024: common irq for soc ip.
-
-Interrupt trigger mode: (Defined in dt-bindings/interrupt-controller/irq.h)
- IRQ_TYPE_LEVEL_HIGH (default)
- IRQ_TYPE_LEVEL_LOW
- IRQ_TYPE_EDGE_RISING
- IRQ_TYPE_EDGE_FALLING
-
-=============================
-intc node bindings definition
-=============================
-
- Description: Describes SMP interrupt controller
-
- PROPERTIES
-
- - compatible
- Usage: required
- Value type: <string>
- Definition: must be "csky,mpintc"
- - #interrupt-cells
- Usage: required
- Value type: <u32>
- Definition: <2>
- - interrupt-controller:
- Usage: required
-
-Examples: ("interrupts = <irq_num IRQ_TYPE_XXX>")
----------
-#include <dt-bindings/interrupt-controller/irq.h>
-
- intc: interrupt-controller {
- compatible = "csky,mpintc";
- #interrupt-cells = <2>;
- interrupt-controller;
- };
-
- device: device-example {
- ...
- interrupts = <34 IRQ_TYPE_EDGE_RISING>;
- interrupt-parent = <&intc>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.yaml b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.yaml
new file mode 100644
index 000000000000..3df7739e31c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/csky,mpintc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: C-SKY Multi-processors Interrupt Controller
+
+maintainers:
+ - Guo Ren <guoren@kernel.org>
+
+description: >
+ C-SKY Multi-processors Interrupt Controller is designed for ck807/ck810/ck860
+ SMP soc, and it also could be used in non-SMP system.
+
+ Interrupt number definition:
+ 0-15 : software irq, and we use 15 as our IPI_IRQ.
+ 16-31 : private irq, and we use 16 as the co-processor timer.
+ 31-1024: common irq for soc ip.
+
+properties:
+ compatible:
+ const: csky,mpintc
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupt-controller: true
+
+required:
+ - compatible
+ - "#interrupt-cells"
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "csky,mpintc";
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt
deleted file mode 100644
index 42d41ec84c7b..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/digicolor-ic.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Conexant Digicolor Interrupt Controller
-
-Required properties:
-
-- compatible : should be "cnxt,cx92755-ic"
-- reg : Specifies base physical address and size of the interrupt controller
- registers (IC) area
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-- syscon: A phandle to the syscon node describing UC registers
-
-Example:
-
- intc: interrupt-controller@f0000040 {
- compatible = "cnxt,cx92755-ic";
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0xf0000040 0x40>;
- syscon = <&uc_regs>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/econet,en751221-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/econet,en751221-intc.yaml
new file mode 100644
index 000000000000..5536319c49c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/econet,en751221-intc.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/econet,en751221-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: EcoNet EN751221 Interrupt Controller
+
+maintainers:
+ - Caleb James DeLisle <cjd@cjdns.fr>
+
+description:
+ The EcoNet EN751221 Interrupt Controller is a simple interrupt controller
+ designed for the MIPS 34Kc MT SMP processor with 2 VPEs. Each interrupt can
+ be routed to either VPE but not both, so to support per-CPU interrupts, a
+ secondary IRQ number is allocated to control masking/unmasking on VPE#1. For
+ lack of a better term we call these "shadow interrupts". The assignment of
+ shadow interrupts is defined by the SoC integrator when wiring the interrupt
+ lines, so they are configurable in the device tree.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: econet,en751221-intc
+
+ reg:
+ maxItems: 1
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupt-controller: true
+
+ interrupts:
+ maxItems: 1
+ description: Interrupt line connecting this controller to its parent.
+
+ econet,shadow-interrupts:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ description:
+ An array of interrupt number pairs where each pair represents a shadow
+ interrupt relationship. The first number in each pair is the primary IRQ,
+ and the second is its shadow IRQ used for VPE#1 control. For example,
+ <8 3> means IRQ 8 is shadowed by IRQ 3, so IRQ 3 cannot be mapped, but
+ when VPE#1 requests IRQ 8, it will manipulate the IRQ 3 mask bit.
+ minItems: 1
+ maxItems: 20
+ items:
+ items:
+ - description: primary per-CPU IRQ
+ - description: shadow IRQ number
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@1fb40000 {
+ compatible = "econet,en751221-intc";
+ reg = <0x1fb40000 0x100>;
+
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ interrupt-parent = <&cpuintc>;
+ interrupts = <2>;
+
+ econet,shadow-interrupts = <7 2>, <8 3>, <13 12>, <30 29>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.txt
deleted file mode 100644
index 888b2b9f7064..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-EZchip NPS Interrupt Controller
-
-Required properties:
-
-- compatible : should be "ezchip,nps400-ic"
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-
-
-Example:
-
-intc: interrupt-controller {
- compatible = "ezchip,nps400-ic";
- interrupt-controller;
- #interrupt-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.yaml b/Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.yaml
new file mode 100644
index 000000000000..589c6ebf6c1a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/ezchip,nps400-ic.yaml
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ezchip,nps400-ic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: EZchip NPS Interrupt Controller
+
+maintainers:
+ - Noam Camus <noamc@ezchip.com>
+
+properties:
+ compatible:
+ const: ezchip,nps400-ic
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "ezchip,nps400-ic";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.txt b/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.txt
deleted file mode 100644
index 24428d47f487..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* Faraday Technologt FTINTC010 interrupt controller
-
-This interrupt controller is a stock IP block from Faraday Technology found
-in the Gemini SoCs and other designs.
-
-Required properties:
-- compatible: must be one of
- "faraday,ftintc010"
- "cortina,gemini-interrupt-controller" (deprecated)
-- reg: The register bank for the interrupt controller.
-- interrupt-controller: Identifies the node as an interrupt controller
-- #interrupt-cells: The number of cells to define the interrupts.
- Must be 2 as the controller can specify level or rising edge
- IRQs. The bindings follows the standard binding for controllers
- with two cells specified in
- interrupt-controller/interrupts.txt
-
-Example:
-
-interrupt-controller@48000000 {
- compatible = "faraday,ftintc010"
- reg = <0x48000000 0x1000>;
- interrupt-controller;
- #interrupt-cells = <2>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.yaml b/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.yaml
new file mode 100644
index 000000000000..980e5c45f25b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+---
+$id: http://devicetree.org/schemas/interrupt-controller/faraday,ftintc010.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Faraday Technology FTINTC010 interrupt controller
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description:
+ This interrupt controller is a stock IP block from Faraday Technology found
+ in the Gemini SoCs and other designs.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: moxa,moxart-ic
+ - const: faraday,ftintc010
+ - enum:
+ - faraday,ftintc010
+ - cortina,gemini-interrupt-controller
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@48000000 {
+ compatible = "faraday,ftintc010";
+ reg = <0x48000000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,icoll.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,icoll.yaml
new file mode 100644
index 000000000000..7b09fd7d588f
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,icoll.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,icoll.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MXS icoll Interrupt controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - fsl,imx23-icoll
+ - fsl,imx28-icoll
+ - const: fsl,icoll
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@80000000 {
+ compatible = "fsl,imx28-icoll", "fsl,icoll";
+ reg = <0x80000000 0x2000>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
+
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,imx8qxp-dc-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,imx8qxp-dc-intc.yaml
new file mode 100644
index 000000000000..6985ee644a25
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,imx8qxp-dc-intc.yaml
@@ -0,0 +1,318 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,imx8qxp-dc-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale i.MX8qxp Display Controller interrupt controller
+
+description: |
+ The Display Controller has a built-in interrupt controller with the following
+ features for all relevant HW events:
+
+ * Enable bit (mask)
+ * Status bit (set by an HW event)
+ * Preset bit (can be used by SW to set status)
+ * Clear bit (used by SW to reset the status)
+
+ Each interrupt can be connected as IRQ (maskable) and/or NMI (non-maskable).
+ Alternatively the un-masked trigger signals for all HW events are provided,
+ allowing it to use a global interrupt controller instead.
+
+ Each interrupt can be protected against SW running in user mode. In that case,
+ only privileged AHB access can control the interrupt status.
+
+maintainers:
+ - Liu Ying <victor.liu@nxp.com>
+
+properties:
+ compatible:
+ const: fsl,imx8qxp-dc-intc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupts:
+ items:
+ - description: store9 shadow load interrupt(blit engine)
+ - description: store9 frame complete interrupt(blit engine)
+ - description: store9 sequence complete interrupt(blit engine)
+ - description:
+ extdst0 shadow load interrupt
+ (display controller, content stream 0)
+ - description:
+ extdst0 frame complete interrupt
+ (display controller, content stream 0)
+ - description:
+ extdst0 sequence complete interrupt
+ (display controller, content stream 0)
+ - description:
+ extdst4 shadow load interrupt
+ (display controller, safety stream 0)
+ - description:
+ extdst4 frame complete interrupt
+ (display controller, safety stream 0)
+ - description:
+ extdst4 sequence complete interrupt
+ (display controller, safety stream 0)
+ - description:
+ extdst1 shadow load interrupt
+ (display controller, content stream 1)
+ - description:
+ extdst1 frame complete interrupt
+ (display controller, content stream 1)
+ - description:
+ extdst1 sequence complete interrupt
+ (display controller, content stream 1)
+ - description:
+ extdst5 shadow load interrupt
+ (display controller, safety stream 1)
+ - description:
+ extdst5 frame complete interrupt
+ (display controller, safety stream 1)
+ - description:
+ extdst5 sequence complete interrupt
+ (display controller, safety stream 1)
+ - description:
+ disengcfg0 shadow load interrupt
+ (display controller, display stream 0)
+ - description:
+ disengcfg0 frame complete interrupt
+ (display controller, display stream 0)
+ - description:
+ disengcfg0 sequence complete interrupt
+ (display controller, display stream 0)
+ - description:
+ framegen0 programmable interrupt0
+ (display controller, display stream 0)
+ - description:
+ framegen0 programmable interrupt1
+ (display controller, display stream 0)
+ - description:
+ framegen0 programmable interrupt2
+ (display controller, display stream 0)
+ - description:
+ framegen0 programmable interrupt3
+ (display controller, display stream 0)
+ - description:
+ signature0 shadow load interrupt
+ (display controller, display stream 0)
+ - description:
+ signature0 measurement valid interrupt
+ (display controller, display stream 0)
+ - description:
+ signature0 error condition interrupt
+ (display controller, display stream 0)
+ - description:
+ disengcfg1 shadow load interrupt
+ (display controller, display stream 1)
+ - description:
+ disengcfg1 frame complete interrupt
+ (display controller, display stream 1)
+ - description:
+ disengcfg1 sequence complete interrupt
+ (display controller, display stream 1)
+ - description:
+ framegen1 programmable interrupt0
+ (display controller, display stream 1)
+ - description:
+ framegen1 programmable interrupt1
+ (display controller, display stream 1)
+ - description:
+ framegen1 programmable interrupt2
+ (display controller, display stream 1)
+ - description:
+ framegen1 programmable interrupt3
+ (display controller, display stream 1)
+ - description:
+ signature1 shadow load interrupt
+ (display controller, display stream 1)
+ - description:
+ signature1 measurement valid interrupt
+ (display controller, display stream 1)
+ - description:
+ signature1 error condition interrupt
+ (display controller, display stream 1)
+ - description: reserved
+ - description:
+ command sequencer error condition interrupt(command sequencer)
+ - description:
+ common control software interrupt0(common control)
+ - description:
+ common control software interrupt1(common control)
+ - description:
+ common control software interrupt2(common control)
+ - description:
+ common control software interrupt3(common control)
+ - description:
+ framegen0 synchronization status activated interrupt
+ (display controller, safety stream 0)
+ - description:
+ framegen0 synchronization status deactivated interrupt
+ (display controller, safety stream 0)
+ - description:
+ framegen0 synchronization status activated interrupt
+ (display controller, content stream 0)
+ - description:
+ framegen0 synchronization status deactivated interrupt
+ (display controller, content stream 0)
+ - description:
+ framegen1 synchronization status activated interrupt
+ (display controller, safety stream 1)
+ - description:
+ framegen1 synchronization status deactivated interrupt
+ (display controller, safety stream 1)
+ - description:
+ framegen1 synchronization status activated interrupt
+ (display controller, content stream 1)
+ - description:
+ framegen1 synchronization status deactivated interrupt
+ (display controller, content stream 1)
+ minItems: 49
+
+ interrupt-names:
+ items:
+ - const: store9_shdload
+ - const: store9_framecomplete
+ - const: store9_seqcomplete
+ - const: extdst0_shdload
+ - const: extdst0_framecomplete
+ - const: extdst0_seqcomplete
+ - const: extdst4_shdload
+ - const: extdst4_framecomplete
+ - const: extdst4_seqcomplete
+ - const: extdst1_shdload
+ - const: extdst1_framecomplete
+ - const: extdst1_seqcomplete
+ - const: extdst5_shdload
+ - const: extdst5_framecomplete
+ - const: extdst5_seqcomplete
+ - const: disengcfg_shdload0
+ - const: disengcfg_framecomplete0
+ - const: disengcfg_seqcomplete0
+ - const: framegen0_int0
+ - const: framegen0_int1
+ - const: framegen0_int2
+ - const: framegen0_int3
+ - const: sig0_shdload
+ - const: sig0_valid
+ - const: sig0_error
+ - const: disengcfg_shdload1
+ - const: disengcfg_framecomplete1
+ - const: disengcfg_seqcomplete1
+ - const: framegen1_int0
+ - const: framegen1_int1
+ - const: framegen1_int2
+ - const: framegen1_int3
+ - const: sig1_shdload
+ - const: sig1_valid
+ - const: sig1_error
+ - const: reserved
+ - const: cmdseq_error
+ - const: comctrl_sw0
+ - const: comctrl_sw1
+ - const: comctrl_sw2
+ - const: comctrl_sw3
+ - const: framegen0_primsync_on
+ - const: framegen0_primsync_off
+ - const: framegen0_secsync_on
+ - const: framegen0_secsync_off
+ - const: framegen1_primsync_on
+ - const: framegen1_primsync_off
+ - const: framegen1_secsync_on
+ - const: framegen1_secsync_off
+ minItems: 49
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+ - interrupt-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx8-lpcg.h>
+
+ interrupt-controller@56180040 {
+ compatible = "fsl,imx8qxp-dc-intc";
+ reg = <0x56180040 0x60>;
+ clocks = <&dc0_lpcg IMX_LPCG_CLK_5>;
+ interrupt-controller;
+ interrupt-parent = <&dc0_irqsteer>;
+ #interrupt-cells = <1>;
+ interrupts = <448>, <449>, <450>, <64>,
+ <65>, <66>, <67>, <68>,
+ <69>, <70>, <193>, <194>,
+ <195>, <196>, <197>, <72>,
+ <73>, <74>, <75>, <76>,
+ <77>, <78>, <79>, <80>,
+ <81>, <199>, <200>, <201>,
+ <202>, <203>, <204>, <205>,
+ <206>, <207>, <208>, <5>,
+ <0>, <1>, <2>, <3>,
+ <4>, <82>, <83>, <84>,
+ <85>, <209>, <210>, <211>,
+ <212>;
+ interrupt-names = "store9_shdload",
+ "store9_framecomplete",
+ "store9_seqcomplete",
+ "extdst0_shdload",
+ "extdst0_framecomplete",
+ "extdst0_seqcomplete",
+ "extdst4_shdload",
+ "extdst4_framecomplete",
+ "extdst4_seqcomplete",
+ "extdst1_shdload",
+ "extdst1_framecomplete",
+ "extdst1_seqcomplete",
+ "extdst5_shdload",
+ "extdst5_framecomplete",
+ "extdst5_seqcomplete",
+ "disengcfg_shdload0",
+ "disengcfg_framecomplete0",
+ "disengcfg_seqcomplete0",
+ "framegen0_int0",
+ "framegen0_int1",
+ "framegen0_int2",
+ "framegen0_int3",
+ "sig0_shdload",
+ "sig0_valid",
+ "sig0_error",
+ "disengcfg_shdload1",
+ "disengcfg_framecomplete1",
+ "disengcfg_seqcomplete1",
+ "framegen1_int0",
+ "framegen1_int1",
+ "framegen1_int2",
+ "framegen1_int3",
+ "sig1_shdload",
+ "sig1_valid",
+ "sig1_error",
+ "reserved",
+ "cmdseq_error",
+ "comctrl_sw0",
+ "comctrl_sw1",
+ "comctrl_sw2",
+ "comctrl_sw3",
+ "framegen0_primsync_on",
+ "framegen0_primsync_off",
+ "framegen0_secsync_on",
+ "framegen0_secsync_off",
+ "framegen1_primsync_on",
+ "framegen1_primsync_off",
+ "framegen1_secsync_on",
+ "framegen1_secsync_off";
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml
index 1d6e0f64a807..78baa0a571cf 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,intmux.yaml
@@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale INTMUX interrupt multiplexer
maintainers:
- - Joakim Zhang <qiangqing.zhang@nxp.com>
+ - Shawn Guo <shawnguo@kernel.org>
+ - NXP Linux Team <linux-imx@nxp.com>
properties:
compatible:
@@ -36,6 +37,9 @@ properties:
clock-names:
const: ipg
+ power-domains:
+ maxItems: 1
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.yaml
index bcb5e20fa9ca..5c768c1e159c 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.yaml
@@ -14,7 +14,13 @@ properties:
oneOf:
- const: fsl,imx-irqsteer
- items:
- - const: fsl,imx8m-irqsteer
+ - enum:
+ - fsl,imx8m-irqsteer
+ - fsl,imx8mp-irqsteer
+ - fsl,imx8qm-irqsteer
+ - fsl,imx8qxp-irqsteer
+ - fsl,imx94-irqsteer
+ - fsl,imx95-irqsteer
- const: fsl,imx-irqsteer
reg:
@@ -42,19 +48,22 @@ properties:
clock-names:
const: ipg
+ power-domains:
+ maxItems: 1
+
interrupt-controller: true
"#interrupt-cells":
const: 1
fsl,channel:
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description: |
u32 value representing the output channel that all input IRQs should be
steered into.
fsl,num-irqs:
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description: |
u32 value representing the number of input interrupts of this channel,
should be multiple of 32 input interrupts and up to 512 interrupts.
@@ -70,6 +79,23 @@ required:
- fsl,channel
- fsl,num-irqs
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8mp-irqsteer
+ - fsl,imx8qm-irqsteer
+ - fsl,imx8qxp-irqsteer
+ - fsl,imx95-irqsteer
+ then:
+ required:
+ - power-domains
+ else:
+ properties:
+ power-domains: false
+
additionalProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.txt b/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.txt
deleted file mode 100644
index 4d47df1a5c91..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-* Freescale Layerscape external IRQs
-
-Some Layerscape SOCs (LS1021A, LS1043A, LS1046A
-LS1088A, LS208xA, LX216xA) support inverting
-the polarity of certain external interrupt lines.
-
-The device node must be a child of the node representing the
-Supplemental Configuration Unit (SCFG).
-
-Required properties:
-- compatible: should be "fsl,<soc-name>-extirq", e.g. "fsl,ls1021a-extirq".
- "fsl,ls1043a-extirq": for LS1043A, LS1046A.
- "fsl,ls1088a-extirq": for LS1088A, LS208xA, LX216xA.
-- #interrupt-cells: Must be 2. The first element is the index of the
- external interrupt line. The second element is the trigger type.
-- #address-cells: Must be 0.
-- interrupt-controller: Identifies the node as an interrupt controller
-- reg: Specifies the Interrupt Polarity Control Register (INTPCR) in
- the SCFG or the External Interrupt Control Register (IRQCR) in
- the ISC.
-- interrupt-map: Specifies the mapping from external interrupts to GIC
- interrupts.
-- interrupt-map-mask: Must be <0xffffffff 0>.
-
-Example:
- scfg: scfg@1570000 {
- compatible = "fsl,ls1021a-scfg", "syscon";
- reg = <0x0 0x1570000 0x0 0x10000>;
- big-endian;
- #address-cells = <1>;
- #size-cells = <1>;
- ranges = <0x0 0x0 0x1570000 0x10000>;
-
- extirq: interrupt-controller@1ac {
- compatible = "fsl,ls1021a-extirq";
- #interrupt-cells = <2>;
- #address-cells = <0>;
- interrupt-controller;
- reg = <0x1ac 4>;
- interrupt-map =
- <0 0 &gic GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>,
- <1 0 &gic GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>,
- <2 0 &gic GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>,
- <3 0 &gic GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>,
- <4 0 &gic GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>,
- <5 0 &gic GIC_SPI 169 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-map-mask = <0xffffffff 0x0>;
- };
- };
-
-
- interrupts-extended = <&gic GIC_SPI 88 IRQ_TYPE_LEVEL_HIGH>,
- <&extirq 1 IRQ_TYPE_LEVEL_LOW>;
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.yaml
new file mode 100644
index 000000000000..7ff4efc4758a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-extirq.yaml
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,ls-extirq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Layerscape External Interrupt Controller
+
+maintainers:
+ - Shawn Guo <shawnguo@kernel.org>
+
+description: |
+ Some Layerscape SOCs (LS1021A, LS1043A, LS1046A LS1088A, LS208xA,
+ LX216xA) support inverting the polarity of certain external interrupt
+ lines.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - fsl,ls1021a-extirq
+ - fsl,ls1043a-extirq
+ - fsl,ls1088a-extirq
+ - items:
+ - enum:
+ - fsl,ls1046a-extirq
+ - const: fsl,ls1043a-extirq
+ - items:
+ - enum:
+ - fsl,ls2080a-extirq
+ - fsl,lx2160a-extirq
+ - const: fsl,ls1088a-extirq
+
+ '#interrupt-cells':
+ const: 2
+
+ '#address-cells':
+ const: 0
+
+ interrupt-controller: true
+
+ reg:
+ maxItems: 1
+ description:
+ Specifies the Interrupt Polarity Control Register (INTPCR) in the
+ SCFG or the External Interrupt Control Register (IRQCR) in the ISC.
+
+ interrupt-map:
+ description: Specifies the mapping from external interrupts to GIC interrupts.
+
+ interrupt-map-mask: true
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - '#address-cells'
+ - interrupt-controller
+ - reg
+ - interrupt-map
+ - interrupt-map-mask
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,ls1021a-extirq
+ then:
+ properties:
+ interrupt-map:
+ minItems: 6
+ maxItems: 6
+ interrupt-map-mask:
+ items:
+ - const: 0x7
+ - const: 0
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,ls1043a-extirq
+ - fsl,ls1046a-extirq
+ then:
+ properties:
+ interrupt-map:
+ minItems: 12
+ maxItems: 12
+ interrupt-map-mask:
+ items:
+ - const: 0xf
+ - const: 0
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,ls1088a-extirq
+ - fsl,ls2080a-extirq
+ - fsl,lx2160a-extirq
+# The driver(drivers/irqchip/irq-ls-extirq.c) have not use standard DT
+# function to parser interrupt-map. So it doesn't consider '#address-size'
+# in parent interrupt controller, such as GIC.
+#
+# When dt-binding verify interrupt-map, item data matrix is spitted at
+# incorrect position. Remove interrupt-map restriction because it always
+# wrong.
+
+ then:
+ properties:
+ interrupt-map-mask:
+ items:
+ - const: 0xf
+ - const: 0
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ interrupt-controller@1ac {
+ compatible = "fsl,ls1021a-extirq";
+ #interrupt-cells = <2>;
+ #address-cells = <0>;
+ interrupt-controller;
+ reg = <0x1ac 4>;
+ interrupt-map =
+ <0 0 &gic GIC_SPI 163 IRQ_TYPE_LEVEL_HIGH>,
+ <1 0 &gic GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>,
+ <2 0 &gic GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>,
+ <3 0 &gic GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>,
+ <4 0 &gic GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>,
+ <5 0 &gic GIC_SPI 169 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-map-mask = <0x7 0x0>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-msi.yaml
new file mode 100644
index 000000000000..9ba8d4d73351
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-msi.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,ls-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Layerscape SCFG PCIe MSI controller
+
+description: |
+ This interrupt controller hardware is a second level interrupt controller that
+ is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based
+ platforms. If interrupt-parent is not provided, the default parent interrupt
+ controller will be used.
+
+ Each PCIe node needs to have property msi-parent that points to
+ MSI controller node
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ enum:
+ - fsl,ls1012a-msi
+ - fsl,ls1021a-msi
+ - fsl,ls1043a-msi
+ - fsl,ls1043a-v1.1-msi
+ - fsl,ls1046a-msi
+
+ reg:
+ maxItems: 1
+
+ '#msi-cells':
+ const: 1
+
+ interrupts:
+ items:
+ - description: Shared MSI interrupt group 0
+ - description: Shared MSI interrupt group 1
+ - description: Shared MSI interrupt group 2
+ - description: Shared MSI interrupt group 3
+ minItems: 1
+
+required:
+ - compatible
+ - reg
+ - msi-controller
+ - interrupts
+
+allOf:
+ - $ref: msi-controller.yaml
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,ls1046a-msi
+ then:
+ properties:
+ interrupts:
+ minItems: 4
+ else:
+ properties:
+ interrupts:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@1571000 {
+ compatible = "fsl,ls1043a-msi";
+ reg = <0x1571000 0x8>;
+ msi-controller;
+ #msi-cells = <1>;
+ interrupts = <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-scfg-msi.txt b/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-scfg-msi.txt
deleted file mode 100644
index 454ce04d6787..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/fsl,ls-scfg-msi.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-* Freescale Layerscape SCFG PCIe MSI controller
-
-Required properties:
-
-- compatible: should be "fsl,<soc-name>-msi" to identify
- Layerscape PCIe MSI controller block such as:
- "fsl,ls1021a-msi"
- "fsl,ls1043a-msi"
- "fsl,ls1046a-msi"
- "fsl,ls1043a-v1.1-msi"
- "fsl,ls1012a-msi"
-- msi-controller: indicates that this is a PCIe MSI controller node
-- reg: physical base address of the controller and length of memory mapped.
-- interrupts: an interrupt to the parent interrupt controller.
-
-This interrupt controller hardware is a second level interrupt controller that
-is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based
-platforms. If interrupt-parent is not provided, the default parent interrupt
-controller will be used.
-Each PCIe node needs to have property msi-parent that points to
-MSI controller node
-
-Examples:
-
- msi1: msi-controller@1571000 {
- compatible = "fsl,ls1043a-msi";
- reg = <0x0 0x1571000 0x0 0x8>,
- msi-controller;
- interrupts = <0 116 0x4>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
new file mode 100644
index 000000000000..78d784973661
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,mpic-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MSI interrupt controller
+
+description: |
+ The Freescale hypervisor and msi-address-64
+ -------------------------------------------
+
+ Normally, PCI devices have access to all of CCSR via an ATMU mapping. The
+ Freescale MSI driver calculates the address of MSIIR (in the MSI register
+ block) and sets that address as the MSI message address.
+
+ In a virtualized environment, the hypervisor may need to create an IOMMU
+ mapping for MSIIR. The Freescale ePAPR hypervisor has this requirement
+ because of hardware limitations of the Peripheral Access Management Unit
+ (PAMU), which is currently the only IOMMU that the hypervisor supports.
+ The ATMU is programmed with the guest physical address, and the PAMU
+ intercepts transactions and reroutes them to the true physical address.
+
+ In the PAMU, each PCI controller is given only one primary window. The
+ PAMU restricts DMA operations so that they can only occur within a window.
+ Because PCI devices must be able to DMA to memory, the primary window must
+ be used to cover all of the guest's memory space.
+
+ PAMU primary windows can be divided into 256 subwindows, and each
+ subwindow can have its own address mapping ("guest physical" to "true
+ physical"). However, each subwindow has to have the same alignment, which
+ means they cannot be located at just any address. Because of these
+ restrictions, it is usually impossible to create a 4KB subwindow that
+ covers MSIIR where it's normally located.
+
+ Therefore, the hypervisor has to create a subwindow inside the same
+ primary window used for memory, but mapped to the MSIR block (where MSIIR
+ lives). The first subwindow after the end of guest memory is used for
+ this. The address specified in the msi-address-64 property is the PCI
+ address of MSIIR. The hypervisor configures the PAMU to map that address to
+ the true physical address of MSIIR.
+
+maintainers:
+ - J. Neuschäfer <j.ne@posteo.net>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - fsl,mpic-msi
+ - fsl,mpic-msi-v4.3
+ - fsl,ipic-msi
+ - fsl,vmpic-msi
+ - fsl,vmpic-msi-v4.3
+ - items:
+ - enum:
+ - fsl,mpc8572-msi
+ - fsl,mpc8610-msi
+ - fsl,mpc8641-msi
+ - const: fsl,mpic-msi
+
+ reg:
+ minItems: 1
+ items:
+ - description: Address and length of the shared message interrupt
+ register set
+ - description: Address of aliased MSIIR or MSIIR1 register for platforms
+ that have such an alias. If using MSIIR1, the second region must be
+ added because different MSI group has different MSIIR1 offset.
+
+ interrupts:
+ minItems: 1
+ maxItems: 16
+ description:
+ Each one of the interrupts here is one entry per 32 MSIs, and routed to
+ the host interrupt controller. The interrupts should be set as edge
+ sensitive. If msi-available-ranges is present, only the interrupts that
+ correspond to available ranges shall be present.
+
+ msi-available-ranges:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ items:
+ items:
+ - description: First MSI interrupt in this range
+ - description: Number of MSI interrupts in this range
+ description:
+ Define which MSI interrupt can be used in the 256 MSI interrupts.
+ If not specified, all the MSI interrupts can be used.
+ Each available range must begin and end on a multiple of 32 (i.e. no
+ splitting an individual MSI register or the associated PIC interrupt).
+
+ msi-address-64:
+ $ref: /schemas/types.yaml#/definitions/uint64
+ description:
+ 64-bit PCI address of the MSIIR register. The MSIIR register is used for
+ MSI messaging. The address of MSIIR in PCI address space is the MSI
+ message address.
+
+ This property may be used in virtualized environments where the hypervisor
+ has created an alternate mapping for the MSIR block. See the top-level
+ description for an explanation.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,mpic-msi-v4.3
+ - fsl,vmpic-msi-v4.3
+ then:
+ properties:
+ interrupts:
+ minItems: 16
+ description:
+ Version 4.3 implies that there are 16 shared interrupts, and they
+ are configured through MSIIR1.
+
+ # MPIC v4.3 does not support this property because the 32 interrupts of
+ # an individual register are not continuous when using MSIIR1.
+ msi-available-ranges: false
+
+ reg:
+ minItems: 2
+
+ else:
+ properties:
+ interrupts:
+ maxItems: 8
+ description:
+ In versions before 4.3, only 8 shared interrupts are available, and
+ they are configured through MSIIR.
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ msi@41600 {
+ compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
+ reg = <0x41600 0x80>;
+ msi-available-ranges = <0 0x100>;
+ interrupts = <0xe0 0>, <0xe1 0>, <0xe2 0>, <0xe3 0>,
+ <0xe4 0>, <0xe5 0>, <0xe6 0>, <0xe7 0>;
+ };
+
+ - |
+ msi@41600 {
+ compatible = "fsl,mpic-msi-v4.3";
+ reg = <0x41600 0x200>, <0x44148 4>;
+ interrupts = <0xe0 0 0 0>, <0xe1 0 0 0>, <0xe2 0 0 0>, <0xe3 0 0 0>,
+ <0xe4 0 0 0>, <0xe5 0 0 0>, <0xe6 0 0 0>, <0xe7 0 0 0>,
+ <0x100 0 0 0>, <0x101 0 0 0>, <0x102 0 0 0>, <0x103 0 0 0>,
+ <0x104 0 0 0>, <0x105 0 0 0>, <0x106 0 0 0>, <0x107 0 0 0>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,mu-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,mu-msi.yaml
new file mode 100644
index 000000000000..b5282c857f44
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,mu-msi.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,mu-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale/NXP i.MX Messaging Unit (MU) work as msi controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description: |
+ The Messaging Unit module enables two processors within the SoC to
+ communicate and coordinate by passing messages (e.g. data, status
+ and control) through the MU interface. The MU also provides the ability
+ for one processor (A side) to signal the other processor (B side) using
+ interrupts.
+
+ Because the MU manages the messaging between processors, the MU uses
+ different clocks (from each side of the different peripheral buses).
+ Therefore, the MU must synchronize the accesses from one side to the
+ other. The MU accomplishes synchronization using two sets of matching
+ registers (Processor A-side, Processor B-side).
+
+ MU can work as msi interrupt controller to do doorbell
+
+allOf:
+ - $ref: /schemas/interrupt-controller/msi-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx6sx-mu-msi
+ - fsl,imx7ulp-mu-msi
+ - fsl,imx8ulp-mu-msi
+ - fsl,imx8ulp-mu-msi-s4
+
+ reg:
+ items:
+ - description: a side register base address
+ - description: b side register base address
+
+ reg-names:
+ items:
+ - const: processor-a-side
+ - const: processor-b-side
+
+ interrupts:
+ description: a side interrupt number.
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: a side power domain
+ - description: b side power domain
+
+ power-domain-names:
+ items:
+ - const: processor-a-side
+ - const: processor-b-side
+
+ msi-controller: true
+
+ "#msi-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - msi-controller
+ - "#msi-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/firmware/imx/rsrc.h>
+
+ msi-controller@5d270000 {
+ compatible = "fsl,imx6sx-mu-msi";
+ msi-controller;
+ #msi-cells = <0>;
+ reg = <0x5d270000 0x10000>, /* A side */
+ <0x5d300000 0x10000>; /* B side */
+ reg-names = "processor-a-side", "processor-b-side";
+ interrupts = <GIC_SPI 191 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&pd IMX_SC_R_MU_12A>,
+ <&pd IMX_SC_R_MU_12B>;
+ power-domain-names = "processor-a-side", "processor-b-side";
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,tzic.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,tzic.yaml
new file mode 100644
index 000000000000..5f2c8761a31d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,tzic.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,tzic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale tzic Interrupt controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - fsl,imx51-tzic
+ - fsl,imx53-tzic
+ - const: fsl,tzic
+ - items:
+ - const: fsl,imx50-tzic
+ - const: fsl,imx53-tzic
+ - const: fsl,tzic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ tz-interrupt-controller@fffc000 {
+ compatible = "fsl,imx53-tzic", "fsl,tzic";
+ reg = <0x0fffc000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,vf610-mscm-ir.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,vf610-mscm-ir.yaml
new file mode 100644
index 000000000000..55b1ae863b91
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,vf610-mscm-ir.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,vf610-mscm-ir.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Vybrid Miscellaneous System Control - Interrupt Router
+
+description:
+ The MSCM IP contains multiple sub modules, this binding describes the second
+ block of registers which control the interrupt router. The interrupt router
+ allows to configure the recipient of each peripheral interrupt. Furthermore
+ it controls the directed processor interrupts. The module is available in all
+ Vybrid SoC's but is only really useful in dual core configurations (VF6xx
+ which comes with a Cortex-A5/Cortex-M4 combination).
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: fsl,vf610-mscm-ir
+
+ reg:
+ maxItems: 1
+
+ fsl,cpucfg:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ The handle to the MSCM CPU configuration node, required
+ to get the current CPU ID
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description:
+ Two cells, interrupt number and cells.
+ The hardware interrupt number according to interrupt
+ assignment of the interrupt router is required.
+ Flags get passed only when using GIC as parent. Flags
+ encoding as documented by the GIC bindings.
+
+required:
+ - compatible
+ - reg
+ - fsl,cpucfg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@40001800 {
+ compatible = "fsl,vf610-mscm-ir";
+ reg = <0x40001800 0x400>;
+ fsl,cpucfg = <&mscm_cpucfg>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&intc>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.txt
deleted file mode 100644
index 35f752706e7d..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Android Goldfish PIC
-
-Android Goldfish programmable interrupt device used by Android
-emulator.
-
-Required properties:
-
-- compatible : should contain "google,goldfish-pic"
-- reg : <registers mapping>
-- interrupts : <interrupt mapping>
-
-Example for mips when used in cascade mode:
-
- cpuintc {
- #interrupt-cells = <0x1>;
- #address-cells = <0>;
- interrupt-controller;
- compatible = "mti,cpu-interrupt-controller";
- };
-
- interrupt-controller@1f000000 {
- compatible = "google,goldfish-pic";
- reg = <0x1f000000 0x1000>;
-
- interrupt-controller;
- #interrupt-cells = <0x1>;
-
- interrupt-parent = <&cpuintc>;
- interrupts = <0x2>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.yaml
new file mode 100644
index 000000000000..ac3c3c3ca186
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/google,goldfish-pic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Android Goldfish PIC
+
+maintainers:
+ - Miodrag Dinic <miodrag.dinic@mips.com>
+
+description:
+ Android Goldfish programmable interrupt device used by Android emulator.
+
+properties:
+ compatible:
+ const: google,goldfish-pic
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - '#interrupt-cells'
+
+examples:
+ - |
+ interrupt-controller@1f000000 {
+ compatible = "google,goldfish-pic";
+ reg = <0x1f000000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <2>;
+ };
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.txt b/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.txt
deleted file mode 100644
index a6813a071f15..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.txt
+++ /dev/null
@@ -1,84 +0,0 @@
-Hisilicon mbigen device tree bindings.
-=======================================
-
-Mbigen means: message based interrupt generator.
-
-MBI is kind of msi interrupt only used on Non-PCI devices.
-
-To reduce the wired interrupt number connected to GIC,
-Hisilicon designed mbigen to collect and generate interrupt.
-
-
-Non-pci devices can connect to mbigen and generate the
-interrupt by writing ITS register.
-
-The mbigen chip and devices connect to mbigen have the following properties:
-
-Mbigen main node required properties:
--------------------------------------------
-- compatible: Should be "hisilicon,mbigen-v2"
-
-- reg: Specifies the base physical address and size of the Mbigen
- registers.
-
-Mbigen sub node required properties:
-------------------------------------------
-- interrupt controller: Identifies the node as an interrupt controller
-
-- msi-parent: Specifies the MSI controller this mbigen use.
- For more detail information,please refer to the generic msi-parent binding in
- Documentation/devicetree/bindings/interrupt-controller/msi.txt.
-
-- num-pins: the total number of pins implemented in this Mbigen
- instance.
-
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value must be 2.
-
- The 1st cell is hardware pin number of the interrupt.This number is local to
- each mbigen chip and in the range from 0 to the maximum interrupts number
- of the mbigen.
-
- The 2nd cell is the interrupt trigger type.
- The value of this cell should be:
- 1: rising edge triggered
- or
- 4: high level triggered
-
-Examples:
-
- mbigen_chip_dsa {
- compatible = "hisilicon,mbigen-v2";
- reg = <0x0 0xc0080000 0x0 0x10000>;
-
- mbigen_gmac:intc_gmac {
- interrupt-controller;
- msi-parent = <&its_dsa 0x40b1c>;
- num-pins = <9>;
- #interrupt-cells = <2>;
- };
-
- mbigen_i2c:intc_i2c {
- interrupt-controller;
- msi-parent = <&its_dsa 0x40b0e>;
- num-pins = <2>;
- #interrupt-cells = <2>;
- };
- };
-
-Devices connect to mbigen required properties:
-----------------------------------------------------
--interrupts:Specifies the interrupt source.
- For the specific information of each cell in this property,please refer to
- the "interrupt-cells" description mentioned above.
-
-Examples:
- gmac0: ethernet@c2080000 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0 0xc2080000 0 0x20000>,
- <0 0xc0000000 0 0x1000>;
- interrupt-parent = <&mbigen_device_gmac>;
- interrupts = <656 1>,
- <657 1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.yaml b/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.yaml
new file mode 100644
index 000000000000..326424e6e02a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/hisilicon,mbigen-v2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Hisilicon mbigen v2
+
+maintainers:
+ - Wei Xu <xuwei5@hisilicon.com>
+
+description: >
+ Mbigen means: message based interrupt generator.
+
+ MBI is kind of msi interrupt only used on Non-PCI devices.
+
+ To reduce the wired interrupt number connected to GIC, Hisilicon designed
+ mbigen to collect and generate interrupt.
+
+ Non-pci devices can connect to mbigen and generate the interrupt by writing
+ ITS register.
+
+properties:
+ compatible:
+ const: hisilicon,mbigen-v2
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties:
+ type: object
+ additionalProperties: false
+
+ properties:
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ msi-parent:
+ maxItems: 1
+
+ num-pins:
+ description: The total number of pins implemented in this Mbigen instance.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ required:
+ - interrupt-controller
+ - "#interrupt-cells"
+ - msi-parent
+ - num-pins
+
+examples:
+ - |
+ mbigen@c0080000 {
+ compatible = "hisilicon,mbigen-v2";
+ reg = <0xc0080000 0x10000>;
+
+ mbigen_gmac: intc_gmac {
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ msi-parent = <&its_dsa 0x40b1c>;
+ num-pins = <9>;
+ };
+
+ mbigen_i2c: intc_i2c {
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ msi-parent = <&its_dsa 0x40b0e>;
+ num-pins = <2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml
index 160ff4b07cac..afb3dd80b643 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/idt,32434-pic.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: IDT 79RC32434 Interrupt Controller Device Tree Bindings
+title: IDT 79RC32434 Interrupt Controller
maintainers:
- Thomas Bogendoerfer <tsbogend@alpha.franken.de>
diff --git a/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt
deleted file mode 100644
index 5dc2a55ad811..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt
+++ /dev/null
@@ -1,105 +0,0 @@
-* ImgTec Powerdown Controller (PDC) Interrupt Controller Binding
-
-This binding specifies what properties must be available in the device tree
-representation of a PDC IRQ controller. This has a number of input interrupt
-lines which can wake the system, and are passed on through output interrupt
-lines.
-
-Required properties:
-
- - compatible: Specifies the compatibility list for the interrupt controller.
- The type shall be <string> and the value shall include "img,pdc-intc".
-
- - reg: Specifies the base PDC physical address(s) and size(s) of the
- addressable register space. The type shall be <prop-encoded-array>.
-
- - interrupt-controller: The presence of this property identifies the node
- as an interrupt controller. No property value shall be defined.
-
- - #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The type shall be a <u32> and the value shall be 2.
-
- - num-perips: Number of waking peripherals.
-
- - num-syswakes: Number of SysWake inputs.
-
- - interrupts: List of interrupt specifiers. The first specifier shall be the
- shared SysWake interrupt, and remaining specifies shall be PDC peripheral
- interrupts in order.
-
-* Interrupt Specifier Definition
-
- Interrupt specifiers consists of 2 cells encoded as follows:
-
- - <1st-cell>: The interrupt-number that identifies the interrupt source.
- 0-7: Peripheral interrupts
- 8-15: SysWake interrupts
-
- - <2nd-cell>: The level-sense information, encoded using the Linux interrupt
- flags as follows (only 4 valid for peripheral interrupts):
- 0 = none (decided by software)
- 1 = low-to-high edge triggered
- 2 = high-to-low edge triggered
- 3 = both edge triggered
- 4 = active-high level-sensitive (required for perip irqs)
- 8 = active-low level-sensitive
-
-* Examples
-
-Example 1:
-
- /*
- * TZ1090 PDC block
- */
- pdc: pdc@02006000 {
- // This is an interrupt controller node.
- interrupt-controller;
-
- // Three cells to encode interrupt sources.
- #interrupt-cells = <2>;
-
- // Offset address of 0x02006000 and size of 0x1000.
- reg = <0x02006000 0x1000>;
-
- // Compatible with Meta hardware trigger block.
- compatible = "img,pdc-intc";
-
- // Three peripherals are connected.
- num-perips = <3>;
-
- // Four SysWakes are connected.
- num-syswakes = <4>;
-
- interrupts = <18 4 /* level */>, /* Syswakes */
- <30 4 /* level */>, /* Peripheral 0 (RTC) */
- <29 4 /* level */>, /* Peripheral 1 (IR) */
- <31 4 /* level */>; /* Peripheral 2 (WDT) */
- };
-
-Example 2:
-
- /*
- * An SoC peripheral that is wired through the PDC.
- */
- rtc0 {
- // The interrupt controller that this device is wired to.
- interrupt-parent = <&pdc>;
-
- // Interrupt source Peripheral 0
- interrupts = <0 /* Peripheral 0 (RTC) */
- 4> /* IRQ_TYPE_LEVEL_HIGH */
- };
-
-Example 3:
-
- /*
- * An interrupt generating device that is wired to a SysWake pin.
- */
- touchscreen0 {
- // The interrupt controller that this device is wired to.
- interrupt-parent = <&pdc>;
-
- // Interrupt source SysWake 0 that is active-low level-sensitive
- interrupts = <8 /* SysWake0 */
- 8 /* IRQ_TYPE_LEVEL_LOW */>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.yaml
new file mode 100644
index 000000000000..99e7a4281595
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/img,pdc-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ImgTec Powerdown Controller (PDC) Interrupt Controller
+
+maintainers:
+ - James Hogan <jhogan@kernel.org>
+
+description:
+ ImgTec Powerdown Controller (PDC) Interrupt Controller has a number of input
+ interrupt lines which can wake the system, and are passed on through output
+ interrupt lines.
+
+properties:
+ compatible:
+ const: img,pdc-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ description: >
+ <1st-cell>: The interrupt-number that identifies the interrupt source.
+ 0-7: Peripheral interrupts
+ 8-15: SysWake interrupts
+
+ <2nd-cell>: The level-sense information, encoded using the Linux interrupt
+ flags as follows (only 4 valid for peripheral interrupts):
+ 0 = none (decided by software)
+ 1 = low-to-high edge triggered
+ 2 = high-to-low edge triggered
+ 3 = both edge triggered
+ 4 = active-high level-sensitive (required for perip irqs)
+ 8 = active-low level-sensitive
+ const: 2
+
+ num-perips:
+ description: Number of waking peripherals
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 8
+
+ num-syswakes:
+ description: Number of SysWake inputs
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 8
+
+ interrupts:
+ description:
+ First entry is syswake IRQ. Subsequent entries are 1 per peripheral.
+ minItems: 2
+ maxItems: 9
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - num-perips
+ - num-syswakes
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@2006000 {
+ compatible = "img,pdc-intc";
+ reg = <0x02006000 0x1000>;
+ interrupts = <18 4>, <30 4>, <29 4>, <31 4>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ num-perips = <3>;
+ num-syswakes = <4>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml
index 0358a7739c8e..609308a5f91d 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/ingenic,intc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Ingenic SoCs interrupt controller devicetree bindings
+title: Ingenic SoCs interrupt controller
maintainers:
- Paul Cercueil <paul@crapouillou.net>
diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt
deleted file mode 100644
index 7d19f494f19a..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Interrupt chips
----------------
-
-* Intel I/O Advanced Programmable Interrupt Controller (IO APIC)
-
- Required properties:
- --------------------
- compatible = "intel,ce4100-ioapic";
- #interrupt-cells = <2>;
-
- Device's interrupt property:
-
- interrupts = <P S>;
-
- The first number (P) represents the interrupt pin which is wired to the
- IO APIC. The second number (S) represents the sense of interrupt which
- should be configured and can be one of:
- 0 - Edge Rising
- 1 - Level Low
- 2 - Level High
- 3 - Edge Falling
-
-* Local APIC
- Required property:
-
- compatible = "intel,ce4100-lapic";
diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml
new file mode 100644
index 000000000000..a3ac818f067d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/intel,ce4100-ioapic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intel I/O Advanced Programmable Interrupt Controller (IO APIC)
+
+maintainers:
+ - Rahul Tanwar <rtanwar@maxlinear.com>
+
+description: |
+ Intel's Advanced Programmable Interrupt Controller (APIC) is a
+ family of interrupt controllers. The APIC is a split
+ architecture design, with a local component (LAPIC) integrated
+ into the processor itself and an external I/O APIC. Local APIC
+ (lapic) receives interrupts from the processor's interrupt pins,
+ from internal sources and from an external I/O APIC (ioapic).
+ And it sends these to the processor core for handling.
+ See [1] Chapter 8 for more details.
+
+ Many of the Intel's generic devices like hpet, ioapic, lapic have
+ the ce4100 name in their compatible property names because they
+ first appeared in CE4100 SoC.
+
+ This schema defines bindings for I/O APIC interrupt controller.
+
+ [1] https://pdos.csail.mit.edu/6.828/2008/readings/ia32/IA32-3A.pdf
+
+properties:
+ compatible:
+ const: intel,ce4100-ioapic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ ioapic1: interrupt-controller@fec00000 {
+ compatible = "intel,ce4100-ioapic";
+ reg = <0xfec00000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml
new file mode 100644
index 000000000000..6b20a5fa8590
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-lapic.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/intel,ce4100-lapic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intel Local Advanced Programmable Interrupt Controller (LAPIC)
+
+maintainers:
+ - Rahul Tanwar <rtanwar@maxlinear.com>
+
+description: |
+ Intel's Advanced Programmable Interrupt Controller (APIC) is a
+ family of interrupt controllers. The APIC is a split
+ architecture design, with a local component (LAPIC) integrated
+ into the processor itself and an external I/O APIC. Local APIC
+ (lapic) receives interrupts from the processor's interrupt pins,
+ from internal sources and from an external I/O APIC (ioapic).
+ And it sends these to the processor core for handling.
+ See [1] Chapter 8 for more details.
+
+ Many of the Intel's generic devices like hpet, ioapic, lapic have
+ the ce4100 name in their compatible property names because they
+ first appeared in CE4100 SoC.
+
+ This schema defines bindings for local APIC interrupt controller.
+
+ [1] https://pdos.csail.mit.edu/6.828/2008/readings/ia32/IA32-3A.pdf
+
+properties:
+ compatible:
+ const: intel,ce4100-lapic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ intel,virtual-wire-mode:
+ description: Intel defines a few possible interrupt delivery
+ modes. With respect to boot/init time, mainly two interrupt
+ delivery modes are possible.
+ PIC Mode - Legacy external 8259 compliant PIC interrupt controller.
+ Virtual Wire Mode - use lapic as virtual wire interrupt delivery mode.
+ For ACPI or MPS spec compliant systems, it is figured out by some read
+ only bit field/s available in their respective defined data structures.
+ For OF based systems, it is by default set to PIC mode.
+ But if this optional boolean property is set, then the interrupt delivery
+ mode is configured to virtual wire compatibility mode.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ lapic0: interrupt-controller@fee00000 {
+ compatible = "intel,ce4100-lapic";
+ reg = <0xfee00000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ intel,virtual-wire-mode;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml b/Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml
index 14dced11877b..a02a6b5af205 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/intel,ixp4xx-interrupt.yaml
@@ -2,8 +2,8 @@
# Copyright 2018 Linaro Ltd.
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/intel,ixp4xx-interrupt.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/intel,ixp4xx-interrupt.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Intel IXP4xx XScale Networking Processors Interrupt Controller
diff --git a/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.txt b/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.txt
deleted file mode 100644
index ee2ad36f8df8..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-J-Core Advanced Interrupt Controller
-
-Required properties:
-
-- compatible: Should be "jcore,aic1" for the (obsolete) first-generation aic
- with 8 interrupt lines with programmable priorities, or "jcore,aic2" for
- the "aic2" core with 64 interrupts.
-
-- reg: Memory region(s) for configuration. For SMP, there should be one
- region per cpu, indexed by the sequential, zero-based hardware cpu
- number.
-
-- interrupt-controller: Identifies the node as an interrupt controller
-
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-
-
-Example:
-
-aic: interrupt-controller@200 {
- compatible = "jcore,aic2";
- reg = < 0x200 0x30 0x500 0x30 >;
- interrupt-controller;
- #interrupt-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.yaml
new file mode 100644
index 000000000000..df8abc24591c
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2018 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/jcore,aic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: J-Core Advanced Interrupt Controller
+
+maintainers:
+ - Rich Felker <dalias@libc.org>
+
+properties:
+ compatible:
+ enum:
+ - jcore,aic1
+ - jcore,aic2
+
+ reg:
+ description: Memory region(s) for configuration. For SMP, there should be one
+ region per CPU, indexed by the sequential, zero-based hardware CPU number.
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ aic: interrupt-controller@200 {
+ compatible = "jcore,aic2";
+ reg = <0x200 0x30>, <0x500 0x30>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/kontron,sl28cpld-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/kontron,sl28cpld-intc.yaml
index e8dfa6507f64..87df07beda59 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/kontron,sl28cpld-intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/kontron,sl28cpld-intc.yaml
@@ -11,7 +11,7 @@ maintainers:
description: |
This module is part of the sl28cpld multi-function device. For more
- details see ../mfd/kontron,sl28cpld.yaml.
+ details see ../embedded-controller/kontron,sl28cpld.yaml.
The following interrupts are available. All types and levels are fixed
and handled by the board management controller.
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,cpu-interrupt-controller.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,cpu-interrupt-controller.yaml
new file mode 100644
index 000000000000..adf989976dcc
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,cpu-interrupt-controller.yaml
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,cpu-interrupt-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LoongArch CPU Interrupt Controller
+
+maintainers:
+ - Liu Peibao <liupeibao@loongson.cn>
+
+properties:
+ compatible:
+ const: loongson,cpu-interrupt-controller
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupt-controller: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - interrupt-controller
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "loongson,cpu-interrupt-controller";
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml
new file mode 100644
index 000000000000..393c128a41d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,eiointc.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,eiointc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson Extended I/O Interrupt Controller
+
+maintainers:
+ - Binbin Zhou <zhoubinbin@loongson.cn>
+
+description: |
+ This interrupt controller is found on the Loongson-3 family chips and
+ Loongson-2K series chips and is used to distribute interrupts directly to
+ individual cores without forwarding them through the HT's interrupt line.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - loongson,ls2k0500-eiointc
+ - loongson,ls2k2000-eiointc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - '#interrupt-cells'
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ eiointc: interrupt-controller@1fe11600 {
+ compatible = "loongson,ls2k0500-eiointc";
+ reg = <0x1fe10000 0x10000>;
+
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ interrupt-parent = <&cpuintc>;
+ interrupts = <3>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml
index d6bc1a687fc7..f0acd5671bb1 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,htpic.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/loongson,htpic.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,htpic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Loongson-3 HyperTransport Interrupt Controller
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml
index 87a74558204f..1d145763908e 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/loongson,htvec.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,htvec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Loongson-3 HyperTransport Interrupt Vector Controller
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml
index edf26452dc72..f63b23f48d8e 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/loongson,liointc.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,liointc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Loongson Local I/O Interrupt Controller
@@ -11,18 +11,23 @@ maintainers:
description: |
This interrupt controller is found in the Loongson-3 family of chips and
- Loongson-2K1000 chip, as the primary package interrupt controller which
+ Loongson-2K series chips, as the primary package interrupt controller which
can route local I/O interrupt to interrupt lines of cores.
+ Be aware of the following points.
+ 1.The Loongson-2K0500 is a single core CPU;
+ 2.The Loongson-2K0500/2K1000 has 64 device interrupt sources as inputs, so we
+ need to define two nodes in dts{i} to describe the "0-31" and "32-61" interrupt
+ sources respectively.
allOf:
- $ref: /schemas/interrupt-controller.yaml#
properties:
compatible:
- oneOf:
- - const: loongson,liointc-1.0
- - const: loongson,liointc-1.0a
- - const: loongson,liointc-2.0
+ enum:
+ - loongson,liointc-1.0
+ - loongson,liointc-1.0a
+ - loongson,liointc-2.0
reg:
minItems: 1
@@ -33,6 +38,7 @@ properties:
- const: main
- const: isr0
- const: isr1
+ minItems: 2
interrupt-controller: true
@@ -45,16 +51,14 @@ properties:
interrupt-names:
description: List of names for the parent interrupts.
items:
- - const: int0
- - const: int1
- - const: int2
- - const: int3
+ pattern: int[0-3]
minItems: 1
+ maxItems: 4
'#interrupt-cells':
const: 2
- 'loongson,parent_int_map':
+ loongson,parent_int_map:
description: |
This property points how the children interrupts will be mapped into CPU
interrupt lines. Each cell refers to a parent interrupt line from 0 to 3
@@ -69,10 +73,10 @@ required:
- compatible
- reg
- interrupts
+ - interrupt-names
- interrupt-controller
- '#interrupt-cells'
- - 'loongson,parent_int_map'
-
+ - loongson,parent_int_map
unevaluatedProperties: false
@@ -86,7 +90,8 @@ if:
then:
properties:
reg:
- minItems: 3
+ minItems: 2
+ maxItems: 3
required:
- reg-names
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt
deleted file mode 100644
index a63ed9fcb535..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-Loongson ls1x Interrupt Controller
-
-Required properties:
-
-- compatible : should be "loongson,ls1x-intc". Valid strings are:
-
-- reg : Specifies base physical address and size of the registers.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 2.
-- interrupts : Specifies the CPU interrupt the controller is connected to.
-
-Example:
-
-intc: interrupt-controller@1fd01040 {
- compatible = "loongson,ls1x-intc";
- reg = <0x1fd01040 0x18>;
-
- interrupt-controller;
- #interrupt-cells = <2>;
-
- interrupt-parent = <&cpu_intc>;
- interrupts = <2>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml
new file mode 100644
index 000000000000..c60125fb1cbf
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.yaml
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,ls1x-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson-1 Interrupt Controller
+
+maintainers:
+ - Keguang Zhang <keguang.zhang@gmail.com>
+
+description:
+ Loongson-1 interrupt controller is connected to the MIPS core interrupt
+ controller, which controls several groups of interrupts.
+
+properties:
+ compatible:
+ const: loongson,ls1x-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ intc0: interrupt-controller@1fd01040 {
+ compatible = "loongson,ls1x-intc";
+ reg = <0x1fd01040 0x18>;
+
+ interrupt-controller;
+ #interrupt-cells = <2>;
+
+ interrupt-parent = <&cpu_intc>;
+ interrupts = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml
index 1f6fd73d4624..a71fc2218ede 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-msi.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/loongson,pch-msi.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,pch-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Loongson PCH MSI Controller
@@ -25,7 +25,7 @@ properties:
description:
u32 value of the base of parent HyperTransport vector allocated
to PCH MSI.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 255
@@ -33,7 +33,7 @@ properties:
description:
u32 value of the number of parent HyperTransport vectors allocated
to PCH MSI.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 1
maximum: 256
@@ -46,7 +46,7 @@ required:
- loongson,msi-base-vec
- loongson,msi-num-vecs
-additionalProperties: true #fixme
+additionalProperties: true # fixme
examples:
- |
diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml
index fdd6a38a31db..b7bc5cb1dff2 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,pch-pic.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/loongson,pch-pic.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/loongson,pch-pic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Loongson PCH PIC Controller
@@ -25,7 +25,7 @@ properties:
description:
u32 value of the base of parent HyperTransport vector allocated
to PCH PIC.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
maximum: 192
diff --git a/Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.txt
deleted file mode 100644
index aee38e7c13e7..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-TI-NSPIRE interrupt controller
-
-Required properties:
-- compatible: Compatible property value should be "lsi,zevio-intc".
-
-- reg: Physical base address of the controller and length of memory mapped
- region.
-
-- interrupt-controller : Identifies the node as an interrupt controller
-
-Example:
-
-interrupt-controller {
- compatible = "lsi,zevio-intc";
- interrupt-controller;
- reg = <0xDC000000 0x1000>;
- #interrupt-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.yaml
new file mode 100644
index 000000000000..e66b25f579c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/lsi,zevio-intc.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2025 Daniel Tang <dt.tangr@gmail.com>
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/lsi,zevio-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI-NSPIRE Interrupt Controller
+
+maintainers:
+ - Daniel Tang <dt.tangr@gmail.com>
+
+description: |
+ TI-NSPIRE interrupt controller
+
+properties:
+ compatible:
+ const: lsi,zevio-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@dc000000 {
+ compatible = "lsi,zevio-intc";
+ interrupt-controller;
+ reg = <0xdc000000 0x1000>;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-gicp.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-gicp.yaml
new file mode 100644
index 000000000000..5faedd95b9a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-gicp.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,ap806-gicp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell GICP Controller
+
+maintainers:
+ - Thomas Petazzoni <thomas.petazzoni@bootlin.com>
+
+description:
+ GICP is a Marvell extension of the GIC that allows to trigger GIC SPI
+ interrupts by doing a memory transaction. It is used by the ICU
+ located in the Marvell CP110 to turn wired interrupts inside the CP
+ into GIC SPI interrupts.
+
+properties:
+ compatible:
+ const: marvell,ap806-gicp
+
+ reg:
+ maxItems: 1
+
+ marvell,spi-ranges:
+ description: Tuples of GIC SPI interrupt ranges available for this GICP
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ items:
+ items:
+ - description: SPI interrupt base
+ - description: Number of interrupts in the range
+
+ msi-controller: true
+
+required:
+ - compatible
+ - reg
+ - msi-controller
+ - marvell,spi-ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ msi-controller@3f0040 {
+ compatible = "marvell,ap806-gicp";
+ reg = <0x3f0040 0x10>;
+ marvell,spi-ranges = <64 64>, <288 64>;
+ msi-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-sei.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-sei.yaml
new file mode 100644
index 000000000000..e812f9a86307
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,ap806-sei.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,ap806-sei.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell SEI (System Error Interrupt) Controller
+
+maintainers:
+ - Miquel Raynal <miquel.raynal@bootlin.com>
+
+description: >
+ Marvell SEI (System Error Interrupt) controller is an interrupt aggregator. It
+ receives interrupts from several sources and aggregates them to a single
+ interrupt line (an SPI) on the parent interrupt controller.
+
+ This interrupt controller can handle up to 64 SEIs, a set comes from the AP
+ and is wired while a second set comes from the CPs by the mean of MSIs.
+
+properties:
+ compatible:
+ const: marvell,ap806-sei
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupt-controller: true
+
+ msi-controller: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#interrupt-cells'
+ - interrupt-controller
+ - msi-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@3f0200 {
+ compatible = "marvell,ap806-sei";
+ reg = <0x3f0200 0x40>;
+ interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ msi-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-370-xp-mpic.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-370-xp-mpic.txt
deleted file mode 100644
index 5fc03134a999..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-370-xp-mpic.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-Marvell Armada 370, 375, 38x, XP Interrupt Controller
------------------------------------------------------
-
-Required properties:
-- compatible: Should be "marvell,mpic"
-- interrupt-controller: Identifies the node as an interrupt controller.
-- msi-controller: Identifies the node as an PCI Message Signaled
- Interrupt controller.
-- #interrupt-cells: The number of cells to define the interrupts. Should be 1.
- The cell is the IRQ number
-
-- reg: Should contain PMIC registers location and length. First pair
- for the main interrupt registers, second pair for the per-CPU
- interrupt registers. For this last pair, to be compliant with SMP
- support, the "virtual" must be use (For the record, these registers
- automatically map to the interrupt controller registers of the
- current CPU)
-
-Optional properties:
-
-- interrupts: If defined, then it indicates that this MPIC is
- connected as a slave to another interrupt controller. This is
- typically the case on Armada 375 and Armada 38x, where the MPIC is
- connected as a slave to the Cortex-A9 GIC. The provided interrupt
- indicate to which GIC interrupt the MPIC output is connected.
-
-Example:
-
- mpic: interrupt-controller@d0020000 {
- compatible = "marvell,mpic";
- #interrupt-cells = <1>;
- #address-cells = <1>;
- #size-cells = <1>;
- interrupt-controller;
- msi-controller;
- reg = <0xd0020a00 0x1d0>,
- <0xd0021070 0x58>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.txt
deleted file mode 100644
index 86a7b4cd03f5..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-Marvell Armada 7K/8K PIC Interrupt controller
----------------------------------------------
-
-This is the Device Tree binding for the PIC, a secondary interrupt
-controller available on the Marvell Armada 7K/8K ARM64 SoCs, and
-typically connected to the GIC as the primary interrupt controller.
-
-Required properties:
-- compatible: should be "marvell,armada-8k-pic"
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: the number of cells to define interrupts on this
- controller. Should be 1
-- reg: the register area for the PIC interrupt controller
-- interrupts: the interrupt to the primary interrupt controller,
- typically the GIC
-
-Example:
-
- pic: interrupt-controller@3f0100 {
- compatible = "marvell,armada-8k-pic";
- reg = <0x3f0100 0x10>;
- #interrupt-cells = <1>;
- interrupt-controller;
- interrupts = <GIC_PPI 15 IRQ_TYPE_LEVEL_HIGH>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.yaml
new file mode 100644
index 000000000000..5a455f7353db
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,armada-8k-pic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell Armada 7K/8K PIC Interrupt controller
+
+maintainers:
+ - Thomas Petazzoni <thomas.petazzoni@bootlin.com>
+
+description:
+ The Marvell Armada 7K/8K PIC is a secondary interrupt controller available on
+ the Marvell Armada 7K/8K ARM64 SoCs, and typically connected to the GIC as the
+ primary interrupt controller.
+
+properties:
+ compatible:
+ const: marvell,armada-8k-pic
+
+ reg:
+ maxItems: 1
+
+ "#interrupt-cells":
+ const: 1
+
+ interrupt-controller: true
+
+ interrupts:
+ maxItems: 1
+ description: Interrupt to the primary interrupt controller (GIC).
+
+required:
+ - compatible
+ - reg
+ - "#interrupt-cells"
+ - interrupt-controller
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@3f0100 {
+ compatible = "marvell,armada-8k-pic";
+ reg = <0x3f0100 0x10>;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ interrupts = <GIC_PPI 15 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,cp110-icu.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,cp110-icu.yaml
new file mode 100644
index 000000000000..ddfce217e119
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,cp110-icu.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,cp110-icu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+maintainers:
+ - Miquel Raynal <miquel.raynal@bootlin.com>
+ - Thomas Petazzoni <thomas.petazzoni@bootlin.com>
+
+title: Marvell ICU Interrupt Controller
+
+description:
+ The Marvell ICU (Interrupt Consolidation Unit) controller is responsible for
+ collecting all wired-interrupt sources in the CP and communicating them to the
+ GIC in the AP. The unit translates interrupt requests on input wires to MSG
+ memory mapped transactions to the GIC. These messages access different GIC
+ memory areas depending on their type (NSR, SR, SEI, REI, etc).
+
+properties:
+ compatible:
+ const: marvell,cp110-icu
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ ranges: true
+
+patternProperties:
+ "^interrupt-controller@":
+ type: object
+ description: Interrupt group child nodes
+ additionalProperties: false
+
+ properties:
+ compatible:
+ enum:
+ - marvell,cp110-icu-nsr
+ - marvell,cp110-icu-sr
+ - marvell,cp110-icu-sei
+ - marvell,cp110-icu-rei
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 0
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupt-controller: true
+
+ msi-parent:
+ maxItems: 1
+ description: Phandle to the GICP controller
+
+ required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupt-controller
+ - msi-parent
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@1e0000 {
+ compatible = "marvell,cp110-icu";
+ reg = <0x1e0000 0x440>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ interrupt-controller@10 {
+ compatible = "marvell,cp110-icu-nsr";
+ reg = <0x10 0x20>;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ msi-parent = <&gicp>;
+ };
+
+ interrupt-controller@50 {
+ compatible = "marvell,cp110-icu-sei";
+ reg = <0x50 0x10>;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ msi-parent = <&sei>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,gicp.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,gicp.txt
deleted file mode 100644
index 64a00ceb7da4..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,gicp.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Marvell GICP Controller
------------------------
-
-GICP is a Marvell extension of the GIC that allows to trigger GIC SPI
-interrupts by doing a memory transaction. It is used by the ICU
-located in the Marvell CP110 to turn wired interrupts inside the CP
-into GIC SPI interrupts.
-
-Required properties:
-
-- compatible: Must be "marvell,ap806-gicp"
-
-- reg: Must be the address and size of the GICP SPI registers
-
-- marvell,spi-ranges: tuples of GIC SPI interrupts ranges available
- for this GICP
-
-- msi-controller: indicates that this is an MSI controller
-
-Example:
-
-gicp_spi: gicp-spi@3f0040 {
- compatible = "marvell,ap806-gicp";
- reg = <0x3f0040 0x10>;
- marvell,spi-ranges = <64 64>, <288 64>;
- msi-controller;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,icu.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,icu.txt
deleted file mode 100644
index 1c94a57a661e..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,icu.txt
+++ /dev/null
@@ -1,112 +0,0 @@
-Marvell ICU Interrupt Controller
---------------------------------
-
-The Marvell ICU (Interrupt Consolidation Unit) controller is
-responsible for collecting all wired-interrupt sources in the CP and
-communicating them to the GIC in the AP, the unit translates interrupt
-requests on input wires to MSG memory mapped transactions to the GIC.
-These messages will access a different GIC memory area depending on
-their type (NSR, SR, SEI, REI, etc).
-
-Required properties:
-
-- compatible: Should be "marvell,cp110-icu"
-
-- reg: Should contain ICU registers location and length.
-
-Subnodes: Each group of interrupt is declared as a subnode of the ICU,
-with their own compatible.
-
-Required properties for the icu_nsr/icu_sei subnodes:
-
-- compatible: Should be one of:
- * "marvell,cp110-icu-nsr"
- * "marvell,cp110-icu-sr"
- * "marvell,cp110-icu-sei"
- * "marvell,cp110-icu-rei"
-
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The value shall be 2.
-
- The 1st cell is the index of the interrupt in the ICU unit.
-
- The 2nd cell is the type of the interrupt. See arm,gic.txt for
- details.
-
-- interrupt-controller: Identifies the node as an interrupt
- controller.
-
-- msi-parent: Should point to the GICP controller, the GIC extension
- that allows to trigger interrupts using MSG memory mapped
- transactions.
-
-Note: each 'interrupts' property referring to any 'icu_xxx' node shall
- have a different number within [0:206].
-
-Example:
-
-icu: interrupt-controller@1e0000 {
- compatible = "marvell,cp110-icu";
- reg = <0x1e0000 0x440>;
-
- CP110_LABEL(icu_nsr): interrupt-controller@10 {
- compatible = "marvell,cp110-icu-nsr";
- reg = <0x10 0x20>;
- #interrupt-cells = <2>;
- interrupt-controller;
- msi-parent = <&gicp>;
- };
-
- CP110_LABEL(icu_sei): interrupt-controller@50 {
- compatible = "marvell,cp110-icu-sei";
- reg = <0x50 0x10>;
- #interrupt-cells = <2>;
- interrupt-controller;
- msi-parent = <&sei>;
- };
-};
-
-node1 {
- interrupt-parent = <&icu_nsr>;
- interrupts = <106 IRQ_TYPE_LEVEL_HIGH>;
-};
-
-node2 {
- interrupt-parent = <&icu_sei>;
- interrupts = <107 IRQ_TYPE_LEVEL_HIGH>;
-};
-
-/* Would not work with the above nodes */
-node3 {
- interrupt-parent = <&icu_nsr>;
- interrupts = <107 IRQ_TYPE_LEVEL_HIGH>;
-};
-
-The legacy bindings were different in this way:
-
-- #interrupt-cells: The value was 3.
- The 1st cell was the group type of the ICU interrupt. Possible
- group types were:
- ICU_GRP_NSR (0x0) : Shared peripheral interrupt, non-secure
- ICU_GRP_SR (0x1) : Shared peripheral interrupt, secure
- ICU_GRP_SEI (0x4) : System error interrupt
- ICU_GRP_REI (0x5) : RAM error interrupt
- The 2nd cell was the index of the interrupt in the ICU unit.
- The 3rd cell was the type of the interrupt. See arm,gic.txt for
- details.
-
-Example:
-
-icu: interrupt-controller@1e0000 {
- compatible = "marvell,cp110-icu";
- reg = <0x1e0000 0x440>;
-
- #interrupt-cells = <3>;
- interrupt-controller;
- msi-parent = <&gicp>;
-};
-
-node1 {
- interrupt-parent = <&icu>;
- interrupts = <ICU_GRP_NSR 106 IRQ_TYPE_LEVEL_HIGH>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,mpic.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,mpic.yaml
new file mode 100644
index 000000000000..616a41c87352
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,mpic.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,mpic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell Armada 370, 375, 38x, 39x, XP Interrupt Controller
+
+maintainers:
+ - Marek Behún <kabel@kernel.org>
+
+description: |
+ The top-level interrupt controller on Marvell Armada 370 and XP. On these
+ platforms it also provides inter-processor interrupts.
+
+ On Marvell Armada 375, 38x and 39x this controller is wired under ARM GIC.
+
+ Provides MSI handling for the PCIe controllers.
+
+properties:
+ compatible:
+ const: marvell,mpic
+
+ reg:
+ items:
+ - description: main registers
+ - description: per-cpu registers
+
+ interrupts:
+ items:
+ - description: |
+ Parent interrupt on platforms where MPIC is not the top-level
+ interrupt controller.
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ msi-controller: true
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - msi-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ interrupt-controller@20a00 {
+ compatible = "marvell,mpic";
+ reg = <0x20a00 0x2d0>, <0x21070 0x58>;
+ interrupts = <GIC_PPI 15 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ msi-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt
deleted file mode 100644
index 0ebfc952cb34..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt
+++ /dev/null
@@ -1,42 +0,0 @@
-
-* Marvell ODMI for MSI support
-
-Some Marvell SoCs have an On-Die Message Interrupt (ODMI) controller
-which can be used by on-board peripheral for MSI interrupts.
-
-Required properties:
-
-- compatible : The value here should contain:
-
- "marvell,ap806-odmi-controller", "marvell,odmi-controller".
-
-- interrupt,controller : Identifies the node as an interrupt controller.
-
-- msi-controller : Identifies the node as an MSI controller.
-
-- marvell,odmi-frames : Number of ODMI frames available. Each frame
- provides a number of events.
-
-- reg : List of register definitions, one for each
- ODMI frame.
-
-- marvell,spi-base : List of GIC base SPI interrupts, one for each
- ODMI frame. Those SPI interrupts are 0-based,
- i.e marvell,spi-base = <128> will use SPI #96.
- See Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
- for details about the GIC Device Tree binding.
-
-Example:
-
- odmi: odmi@300000 {
- compatible = "marvell,ap806-odmi-controller",
- "marvell,odmi-controller";
- interrupt-controller;
- msi-controller;
- marvell,odmi-frames = <4>;
- reg = <0x300000 0x4000>,
- <0x304000 0x4000>,
- <0x308000 0x4000>,
- <0x30C000 0x4000>;
- marvell,spi-base = <128>, <136>, <144>, <152>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.yaml
new file mode 100644
index 000000000000..9ec1ed4a5155
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,odmi-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell ODMI controller
+
+maintainers:
+ - Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
+
+description:
+ Some Marvell SoCs have an On-Die Message Interrupt (ODMI) controller which can
+ be used by on-board peripherals for MSI interrupts.
+
+properties:
+ compatible:
+ const: marvell,odmi-controller
+
+ reg:
+ description: List of register definitions, one for each ODMI frame.
+
+ msi-controller: true
+
+ marvell,odmi-frames:
+ description: Number of ODMI frames available. Each frame provides a number of events.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ marvell,spi-base:
+ description: >
+ List of GIC base SPI interrupts, one for each ODMI frame. Those SPI
+ interrupts are 0-based, i.e. marvell,spi-base = <128> will use SPI #96.
+ See Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml
+ for details.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+required:
+ - compatible
+ - reg
+ - msi-controller
+ - marvell,odmi-frames
+ - marvell,spi-base
+
+additionalProperties: false
+
+examples:
+ - |
+ msi-controller@300000 {
+ compatible = "marvell,odmi-controller";
+ msi-controller;
+ marvell,odmi-frames = <4>;
+ reg = <0x300000 0x4000>, <0x304000 0x4000>, <0x308000 0x4000>, <0x30C000 0x4000>;
+ marvell,spi-base = <128>, <136>, <144>, <152>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,orion-bridge-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/marvell,orion-bridge-intc.yaml
new file mode 100644
index 000000000000..e1310ec65382
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,orion-bridge-intc.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+---
+$id: http://devicetree.org/schemas/interrupt-controller/marvell,orion-bridge-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell Orion SoC Bridge Interrupt Controller
+
+maintainers:
+ - Andrew Lunn <andrew@lunn.ch>
+ - Gregory Clement <gregory.clement@bootlin.com>
+
+properties:
+ compatible:
+ const: marvell,orion-bridge-intc
+
+ reg:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupts:
+ description: Bridge interrupt of the main interrupt controller
+
+ marvell,#interrupts:
+ description: Number of interrupts provided by bridge interrupt controller.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 32
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@20110 {
+ compatible = "marvell,orion-bridge-intc";
+ reg = <0x20110 0x8>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <0>;
+ /* Dove bridge provides 5 interrupts */
+ marvell,#interrupts = <5>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,orion-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,orion-intc.txt
deleted file mode 100644
index 2c11ac76fac9..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,orion-intc.txt
+++ /dev/null
@@ -1,48 +0,0 @@
-Marvell Orion SoC interrupt controllers
-
-* Main interrupt controller
-
-Required properties:
-- compatible: shall be "marvell,orion-intc"
-- reg: base address(es) of interrupt registers starting with CAUSE register
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: number of cells to encode an interrupt source, shall be 1
-
-The interrupt sources map to the corresponding bits in the interrupt
-registers, i.e.
-- 0 maps to bit 0 of first base address,
-- 1 maps to bit 1 of first base address,
-- 32 maps to bit 0 of second base address, and so on.
-
-Example:
- intc: interrupt-controller {
- compatible = "marvell,orion-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- /* Dove has 64 first level interrupts */
- reg = <0x20200 0x10>, <0x20210 0x10>;
- };
-
-* Bridge interrupt controller
-
-Required properties:
-- compatible: shall be "marvell,orion-bridge-intc"
-- reg: base address of bridge interrupt registers starting with CAUSE register
-- interrupts: bridge interrupt of the main interrupt controller
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: number of cells to encode an interrupt source, shall be 1
-
-Optional properties:
-- marvell,#interrupts: number of interrupts provided by bridge interrupt
- controller, defaults to 32 if not set
-
-Example:
- bridge_intc: interrupt-controller {
- compatible = "marvell,orion-bridge-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0x20110 0x8>;
- interrupts = <0>;
- /* Dove bridge provides 5 interrupts */
- marvell,#interrupts = <5>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,sei.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,sei.txt
deleted file mode 100644
index 0beafed502f5..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/marvell,sei.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-Marvell SEI (System Error Interrupt) Controller
------------------------------------------------
-
-Marvell SEI (System Error Interrupt) controller is an interrupt
-aggregator. It receives interrupts from several sources and aggregates
-them to a single interrupt line (an SPI) on the parent interrupt
-controller.
-
-This interrupt controller can handle up to 64 SEIs, a set comes from the
-AP and is wired while a second set comes from the CPs by the mean of
-MSIs.
-
-Required properties:
-
-- compatible: should be one of:
- * "marvell,ap806-sei"
-- reg: SEI registers location and length.
-- interrupts: identifies the parent IRQ that will be triggered.
-- #interrupt-cells: number of cells to define an SEI wired interrupt
- coming from the AP, should be 1. The cell is the IRQ
- number.
-- interrupt-controller: identifies the node as an interrupt controller
- for AP interrupts.
-- msi-controller: identifies the node as an MSI controller for the CPs
- interrupts.
-
-Example:
-
- sei: interrupt-controller@3f0200 {
- compatible = "marvell,ap806-sei";
- reg = <0x3f0200 0x40>;
- interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>;
- #interrupt-cells = <1>;
- interrupt-controller;
- msi-controller;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt
deleted file mode 100644
index 5865f4f2c69d..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-* Mediatek 27xx cirq
-
-In Mediatek SOCs, the CIRQ is a low power interrupt controller designed to
-work outside MCUSYS which comprises with Cortex-Ax cores,CCI and GIC.
-The external interrupts (outside MCUSYS) will feed through CIRQ and connect
-to GIC in MCUSYS. When CIRQ is enabled, it will record the edge-sensitive
-interrupts and generate a pulse signal to parent interrupt controller when
-flush command is executed. With CIRQ, MCUSYS can be completely turned off
-to improve the system power consumption without losing interrupts.
-
-Required properties:
-- compatible: should be one of
- - "mediatek,mt2701-cirq" for mt2701 CIRQ
- - "mediatek,mt8135-cirq" for mt8135 CIRQ
- - "mediatek,mt8173-cirq" for mt8173 CIRQ
- and "mediatek,cirq" as a fallback.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : Use the same format as specified by GIC in arm,gic.txt.
-- reg: Physical base address of the cirq registers and length of memory
- mapped region.
-- mediatek,ext-irq-range: Identifies external irq number range in different
- SOCs.
-
-Example:
- cirq: interrupt-controller@10204000 {
- compatible = "mediatek,mt2701-cirq",
- "mediatek,mtk-cirq";
- interrupt-controller;
- #interrupt-cells = <3>;
- interrupt-parent = <&sysirq>;
- reg = <0 0x10204000 0 0x400>;
- mediatek,ext-irq-start = <32 200>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml
new file mode 100644
index 000000000000..30d76692ca87
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/mediatek,mt6577-sysirq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek sysirq
+
+description:
+ MediaTek SOCs sysirq support controllable irq inverter for each GIC SPI
+ interrupt.
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: mediatek,mt6577-sysirq
+ - items:
+ - enum:
+ - mediatek,mt2701-sysirq
+ - mediatek,mt2712-sysirq
+ - mediatek,mt6572-sysirq
+ - mediatek,mt6580-sysirq
+ - mediatek,mt6582-sysirq
+ - mediatek,mt6589-sysirq
+ - mediatek,mt6592-sysirq
+ - mediatek,mt6755-sysirq
+ - mediatek,mt6765-sysirq
+ - mediatek,mt6779-sysirq
+ - mediatek,mt6795-sysirq
+ - mediatek,mt6797-sysirq
+ - mediatek,mt7622-sysirq
+ - mediatek,mt7623-sysirq
+ - mediatek,mt7629-sysirq
+ - mediatek,mt8127-sysirq
+ - mediatek,mt8135-sysirq
+ - mediatek,mt8173-sysirq
+ - mediatek,mt8183-sysirq
+ - mediatek,mt8365-sysirq
+ - mediatek,mt8516-sysirq
+ - const: mediatek,mt6577-sysirq
+
+ reg:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ $ref: arm,gic.yaml#/properties/#interrupt-cells
+
+required:
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt6797-sysirq
+ then:
+ properties:
+ reg:
+ minItems: 2
+ else:
+ properties:
+ reg:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ interrupt-controller@10200620 {
+ compatible = "mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq";
+ reg = <0x10220620 0x20>,
+ <0x10220690 0x10>;
+ interrupt-parent = <&gic>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.yaml
new file mode 100644
index 000000000000..20dfffb34f0c
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mtk-cirq.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/mediatek,mtk-cirq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek System Interrupt Controller
+
+maintainers:
+ - Youlin Pei <youlin.pei@mediatek.com>
+
+description:
+ In MediaTek SoCs, the CIRQ is a low power interrupt controller designed to
+ work outside of MCUSYS which comprises with Cortex-Ax cores, CCI and GIC.
+ The external interrupts (outside MCUSYS) will feed through CIRQ and connect
+ to GIC in MCUSYS. When CIRQ is enabled, it will record the edge-sensitive
+ interrupts and generate a pulse signal to parent interrupt controller when
+ flush command is executed. With CIRQ, MCUSYS can be completely turned off
+ to improve the system power consumption without losing interrupts.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - mediatek,mt2701-cirq
+ - mediatek,mt8135-cirq
+ - mediatek,mt8173-cirq
+ - mediatek,mt8192-cirq
+ - const: mediatek,mtk-cirq
+
+ reg:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 3
+
+ interrupt-controller: true
+
+ mediatek,ext-irq-range:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - description: First CIRQ interrupt
+ - description: Last CIRQ interrupt
+ description:
+ Identifies the range of external interrupts in different SoCs
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupt-controller
+ - mediatek,ext-irq-range
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ cirq: interrupt-controller@10204000 {
+ compatible = "mediatek,mt2701-cirq", "mediatek,mtk-cirq";
+ reg = <0x10204000 0x400>;
+ #interrupt-cells = <3>;
+ interrupt-controller;
+ interrupt-parent = <&sysirq>;
+ mediatek,ext-irq-range = <32 200>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt
deleted file mode 100644
index 84ced3f4179b..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-MediaTek sysirq
-
-MediaTek SOCs sysirq support controllable irq inverter for each GIC SPI
-interrupt.
-
-Required properties:
-- compatible: should be
- "mediatek,mt8516-sysirq", "mediatek,mt6577-sysirq": for MT8516
- "mediatek,mt8183-sysirq", "mediatek,mt6577-sysirq": for MT8183
- "mediatek,mt8173-sysirq", "mediatek,mt6577-sysirq": for MT8173
- "mediatek,mt8135-sysirq", "mediatek,mt6577-sysirq": for MT8135
- "mediatek,mt8127-sysirq", "mediatek,mt6577-sysirq": for MT8127
- "mediatek,mt7622-sysirq", "mediatek,mt6577-sysirq": for MT7622
- "mediatek,mt7623-sysirq", "mediatek,mt6577-sysirq": for MT7623
- "mediatek,mt7629-sysirq", "mediatek,mt6577-sysirq": for MT7629
- "mediatek,mt6795-sysirq", "mediatek,mt6577-sysirq": for MT6795
- "mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq": for MT6797
- "mediatek,mt6779-sysirq", "mediatek,mt6577-sysirq": for MT6779
- "mediatek,mt6765-sysirq", "mediatek,mt6577-sysirq": for MT6765
- "mediatek,mt6755-sysirq", "mediatek,mt6577-sysirq": for MT6755
- "mediatek,mt6592-sysirq", "mediatek,mt6577-sysirq": for MT6592
- "mediatek,mt6589-sysirq", "mediatek,mt6577-sysirq": for MT6589
- "mediatek,mt6582-sysirq", "mediatek,mt6577-sysirq": for MT6582
- "mediatek,mt6580-sysirq", "mediatek,mt6577-sysirq": for MT6580
- "mediatek,mt6577-sysirq": for MT6577
- "mediatek,mt2712-sysirq", "mediatek,mt6577-sysirq": for MT2712
- "mediatek,mt2701-sysirq", "mediatek,mt6577-sysirq": for MT2701
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Use the same format as specified by GIC in arm,gic.txt.
-- reg: Physical base address of the intpol registers and length of memory
- mapped region. Could be multiple bases here. Ex: mt6797 needs 2 reg, others
- need 1.
-
-Example:
- sysirq: intpol-controller@10200620 {
- compatible = "mediatek,mt6797-sysirq",
- "mediatek,mt6577-sysirq";
- interrupt-controller;
- #interrupt-cells = <3>;
- interrupt-parent = <&gic>;
- reg = <0 0x10220620 0 0x20>,
- <0 0x10220690 0 0x10>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/microchip,lan966x-oic.yaml b/Documentation/devicetree/bindings/interrupt-controller/microchip,lan966x-oic.yaml
new file mode 100644
index 000000000000..dca16e202da9
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/microchip,lan966x-oic.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/microchip,lan966x-oic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip LAN966x outband interrupt controller
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+description: |
+ The Microchip LAN966x outband interrupt controller (OIC) maps the internal
+ interrupt sources of the LAN966x device to a PCI interrupt when the LAN966x
+ device is used as a PCI device.
+
+properties:
+ compatible:
+ const: microchip,lan966x-oic
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupt-controller: true
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - interrupt-controller
+ - interrupts
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@e00c0120 {
+ compatible = "microchip,lan966x-oic";
+ reg = <0xe00c0120 0x190>;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ interrupts = <0>;
+ interrupt-parent = <&intc>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32-evic.txt b/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32-evic.txt
deleted file mode 100644
index c3a1b37c4c35..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32-evic.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-Microchip PIC32 Interrupt Controller
-====================================
-
-The Microchip PIC32 contains an Enhanced Vectored Interrupt Controller (EVIC).
-It handles all internal and external interrupts. This controller exists outside
-of the CPU and is the arbitrator of all interrupts (including interrupts from
-the CPU itself) before they are presented to the CPU.
-
-External interrupts have a software configurable edge polarity. Non external
-interrupts have a type and polarity that is determined by the source of the
-interrupt.
-
-Required properties
--------------------
-
-- compatible: Should be "microchip,pic32mzda-evic"
-- reg: Specifies physical base address and size of register range.
-- interrupt-controller: Identifies the node as an interrupt controller.
-- #interrupt cells: Specifies the number of cells used to encode an interrupt
- source connected to this controller. The value shall be 2 and interrupt
- descriptor shall have the following format:
-
- <hw_irq irq_type>
-
- hw_irq - represents the hardware interrupt number as in the data sheet.
- irq_type - is used to describe the type and polarity of an interrupt. For
- internal interrupts use IRQ_TYPE_EDGE_RISING for non persistent interrupts and
- IRQ_TYPE_LEVEL_HIGH for persistent interrupts. For external interrupts use
- IRQ_TYPE_EDGE_RISING or IRQ_TYPE_EDGE_FALLING to select the desired polarity.
-
-Optional properties
--------------------
-- microchip,external-irqs: u32 array of external interrupts with software
- polarity configuration. This array corresponds to the bits in the INTCON
- SFR.
-
-Example
--------
-
-evic: interrupt-controller@1f810000 {
- compatible = "microchip,pic32mzda-evic";
- interrupt-controller;
- #interrupt-cells = <2>;
- reg = <0x1f810000 0x1000>;
- microchip,external-irqs = <3 8 13 18 23>;
-};
-
-Each device/peripheral must request its interrupt line with the associated type
-and polarity.
-
-Internal interrupt DTS snippet
-------------------------------
-
-device@1f800000 {
- ...
- interrupts = <113 IRQ_TYPE_LEVEL_HIGH>;
- ...
-};
-
-External interrupt DTS snippet
-------------------------------
-
-device@1f800000 {
- ...
- interrupts = <3 IRQ_TYPE_EDGE_RISING>;
- ...
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32mzda-evic.yaml b/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32mzda-evic.yaml
new file mode 100644
index 000000000000..74bfc42693f0
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32mzda-evic.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/microchip,pic32mzda-evic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip PIC32 EVIC Interrupt Controller
+
+maintainers:
+ - Cristian Birsan <cristian.birsan@microchip.com>
+
+description: >
+ The Microchip PIC32 contains an Enhanced Vectored Interrupt Controller (EVIC).
+ It handles all internal and external interrupts. This controller exists
+ outside of the CPU and is the arbitrator of all interrupts (including
+ interrupts from the CPU itself) before they are presented to the CPU.
+
+ External interrupts have a software configurable edge polarity. Non external
+ interrupts have a type and polarity that is determined by the source of the
+ interrupt.
+
+properties:
+ compatible:
+ items:
+ - const: microchip,pic32mzda-evic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ maxItems: 1
+
+ microchip,external-irqs:
+ description:
+ External interrupts with software polarity configuration corresponding to
+ the INTCON SFR bits.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@1f810000 {
+ compatible = "microchip,pic32mzda-evic";
+ reg = <0x1f810000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ microchip,external-irqs = <3 8 13 18 23>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/microchip,sama7g5-eic.yaml b/Documentation/devicetree/bindings/interrupt-controller/microchip,sama7g5-eic.yaml
new file mode 100644
index 000000000000..d56ba65b17d1
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/microchip,sama7g5-eic.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/microchip,sama7g5-eic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip External Interrupt Controller
+
+maintainers:
+ - Claudiu Beznea <claudiu.beznea@microchip.com>
+
+description:
+ This interrupt controller is found in Microchip SoCs (SAMA7G5) and provides
+ support for handling up to 2 external interrupt lines.
+
+properties:
+ compatible:
+ enum:
+ - microchip,sama7g5-eic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description:
+ The first cell is the input IRQ number (between 0 and 1), the second cell
+ is the trigger type as defined in interrupt.txt present in this directory.
+
+ interrupts:
+ description: |
+ Contains the GIC SPI IRQs mapped to the external interrupt lines. They
+ should be specified sequentially from output 0 to output 1.
+ minItems: 2
+ maxItems: 2
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: pclk
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/at91.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ eic: interrupt-controller@e1628000 {
+ compatible = "microchip,sama7g5-eic";
+ reg = <0xe1628000 0x100>;
+ interrupt-parent = <&gic>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupts = <GIC_SPI 153 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 154 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&pmc PMC_TYPE_PERIPHERAL 37>;
+ clock-names = "pclk";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml
index 372ccbfae771..b7c5022eec84 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml
@@ -4,13 +4,11 @@
$id: http://devicetree.org/schemas/interrupt-controller/mrvl,intc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Marvell MMP/Orion Interrupt controller bindings
+title: Marvell MMP/Orion Interrupt controller
maintainers:
- - Thomas Gleixner <tglx@linutronix.de>
- - Jason Cooper <jason@lakedaemon.net>
- - Marc Zyngier <maz@kernel.org>
- - Rob Herring <robh+dt@kernel.org>
+ - Andrew Lunn <andrew@lunn.ch>
+ - Gregory Clement <gregory.clement@bootlin.com>
allOf:
- if:
@@ -55,8 +53,8 @@ allOf:
maxItems: 1
reg-names:
items:
- - const: 'mux status'
- - const: 'mux mask'
+ - const: mux status
+ - const: mux mask
required:
- interrupts
else:
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.yaml b/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.yaml
index 27b798bfe29b..d943ea820cdd 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/interrupt-controller/mscc,ocelot-icpu-intr.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/interrupt-controller/mscc,ocelot-icpu-intr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Microsemi Ocelot SoC ICPU Interrupt Controller
@@ -26,7 +26,6 @@ properties:
- mscc,ocelot-icpu-intr
- mscc,serval-icpu-intr
-
'#interrupt-cells':
const: 1
diff --git a/Documentation/devicetree/bindings/interrupt-controller/msi-controller.yaml b/Documentation/devicetree/bindings/interrupt-controller/msi-controller.yaml
new file mode 100644
index 000000000000..449d6067ec88
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/msi-controller.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/msi-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MSI controller
+
+maintainers:
+ - Marc Zyngier <maz@kernel.org>
+
+description: |
+ An MSI controller signals interrupts to a CPU when a write is made
+ to an MMIO address by some master. An MSI controller may feature a
+ number of doorbells.
+
+properties:
+ "#msi-cells":
+ description: |
+ The number of cells in an msi-specifier, required if not zero.
+
+ Typically this will encode information related to sideband data,
+ and will not encode doorbells or payloads as these can be
+ configured dynamically.
+
+ The meaning of the msi-specifier is defined by the device tree
+ binding of the specific MSI controller.
+ enum: [0, 1]
+
+ msi-controller:
+ description:
+ Identifies the node as an MSI controller.
+ $ref: /schemas/types.yaml#/definitions/flag
+
+ msi-ranges:
+ description:
+ A list of <phandle intspec span> tuples, where "phandle" is the
+ parent interrupt controller, "intspec" is the starting/base
+ interrupt specifier and "span" is the size of the
+ range. Multiple ranges can be provided.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+
+dependencies:
+ "#msi-cells": [ msi-controller ]
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/interrupt-controller/mti,cpu-interrupt-controller.yaml b/Documentation/devicetree/bindings/interrupt-controller/mti,cpu-interrupt-controller.yaml
new file mode 100644
index 000000000000..46a1f5f54b74
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/mti,cpu-interrupt-controller.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/mti,cpu-interrupt-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MIPS CPU Interrupt Controller
+
+description: >
+ On MIPS the mips_cpu_irq_of_init() helper can be used to initialize the 8 CPU
+ IRQs from a devicetree file and create a irq_domain for IRQ controller.
+
+ With the irq_domain in place we can describe how the 8 IRQs are wired to the
+ platforms internal interrupt controller cascade.
+
+maintainers:
+ - Thomas Bogendoerfer <tsbogend@alpha.franken.de>
+
+properties:
+ compatible:
+ const: mti,cpu-interrupt-controller
+
+ '#interrupt-cells':
+ const: 1
+
+ '#address-cells':
+ const: 0
+
+ interrupt-controller: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - '#address-cells'
+ - interrupt-controller
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "mti,cpu-interrupt-controller";
+ #address-cells = <0>;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml
index 9ce6804bdb99..2d6307a383ad 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/nuvoton,wpcm450-aic.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Nuvoton WPCM450 Advanced Interrupt Controller bindings
+title: Nuvoton WPCM450 Advanced Interrupt Controller
maintainers:
- Jonathan Neuschäfer <j.neuschaefer@gmx.net>
diff --git a/Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.txt b/Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.txt
deleted file mode 100644
index 2ff356640100..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-NVIDIA Legacy Interrupt Controller
-
-All Tegra SoCs contain a legacy interrupt controller that routes
-interrupts to the GIC, and also serves as a wakeup source. It is also
-referred to as "ictlr", hence the name of the binding.
-
-The HW block exposes a number of interrupt controllers, each
-implementing a set of 32 interrupts.
-
-Required properties:
-
-- compatible : should be: "nvidia,tegra<chip>-ictlr". The LIC on
- subsequent SoCs remained backwards-compatible with Tegra30, so on
- Tegra generations later than Tegra30 the compatible value should
- include "nvidia,tegra30-ictlr".
-- reg : Specifies base physical address and size of the registers.
- Each controller must be described separately (Tegra20 has 4 of them,
- whereas Tegra30 and later have 5).
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value must be 3.
-
-Notes:
-
-- Because this HW ultimately routes interrupts to the GIC, the
- interrupt specifier must be that of the GIC.
-- Only SPIs can use the ictlr as an interrupt parent. SGIs and PPIs
- are explicitly forbidden.
-
-Example:
-
- ictlr: interrupt-controller@60004000 {
- compatible = "nvidia,tegra20-ictlr", "nvidia,tegra-ictlr";
- reg = <0x60004000 64>,
- <0x60004100 64>,
- <0x60004200 64>,
- <0x60004300 64>;
- interrupt-controller;
- #interrupt-cells = <3>;
- interrupt-parent = <&intc>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.yaml b/Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.yaml
new file mode 100644
index 000000000000..074a873880e5
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/nvidia,tegra20-ictlr.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/nvidia,tegra20-ictlr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra20 Legacy Interrupt Controller
+
+maintainers:
+ - Thierry Reding <treding@nvidia.com>
+ - Jonathan Hunter <jonathanh@nvidia.com>
+
+description: >
+ All Tegra SoCs contain a legacy interrupt controller that routes interrupts to
+ the GIC, and also serves as a wakeup source. It is also referred to as
+ "ictlr", hence the name of the binding.
+
+ The HW block exposes a number of interrupt controllers, each implementing a
+ set of 32 interrupts.
+
+ Notes:
+ - Because this HW ultimately routes interrupts to the GIC, the
+ interrupt specifier must be that of the GIC.
+ - Only SPIs can use the ictlr as an interrupt parent. SGIs and PPIs
+ are explicitly forbidden.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - nvidia,tegra114-ictlr
+ - nvidia,tegra124-ictlr
+ - const: nvidia,tegra30-ictlr
+ - enum:
+ - nvidia,tegra20-ictlr
+ - nvidia,tegra30-ictlr
+
+ reg:
+ description: Each entry is a block of 32 interrupts
+ minItems: 4
+ maxItems: 5
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 3
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: nvidia,tegra20-ictlr
+ then:
+ properties:
+ reg:
+ maxItems: 4
+ else:
+ properties:
+ reg:
+ minItems: 5
+
+examples:
+ - |
+ interrupt-controller@60004000 {
+ compatible = "nvidia,tegra20-ictlr";
+ reg = <0x60004000 64>,
+ <0x60004100 64>,
+ <0x60004200 64>,
+ <0x60004300 64>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.txt b/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.txt
deleted file mode 100644
index 0bfb3ba55f4c..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-* NXP LPC32xx MIC, SIC1 and SIC2 Interrupt Controllers
-
-Required properties:
-- compatible: "nxp,lpc3220-mic" or "nxp,lpc3220-sic".
-- reg: should contain IC registers location and length.
-- interrupt-controller: identifies the node as an interrupt controller.
-- #interrupt-cells: the number of cells to define an interrupt, should be 2.
- The first cell is the IRQ number, the second cell is used to specify
- one of the supported IRQ types:
- IRQ_TYPE_EDGE_RISING = low-to-high edge triggered,
- IRQ_TYPE_EDGE_FALLING = high-to-low edge triggered,
- IRQ_TYPE_LEVEL_HIGH = active high level-sensitive,
- IRQ_TYPE_LEVEL_LOW = active low level-sensitive.
- Reset value is IRQ_TYPE_LEVEL_LOW.
-
-Optional properties:
-- interrupts: empty for MIC interrupt controller, cascaded MIC
- hardware interrupts for SIC1 and SIC2
-
-Examples:
-
- /* LPC32xx MIC, SIC1 and SIC2 interrupt controllers */
- mic: interrupt-controller@40008000 {
- compatible = "nxp,lpc3220-mic";
- reg = <0x40008000 0x4000>;
- interrupt-controller;
- #interrupt-cells = <2>;
- };
-
- sic1: interrupt-controller@4000c000 {
- compatible = "nxp,lpc3220-sic";
- reg = <0x4000c000 0x4000>;
- interrupt-controller;
- #interrupt-cells = <2>;
-
- interrupt-parent = <&mic>;
- interrupts = <0 IRQ_TYPE_LEVEL_LOW>,
- <30 IRQ_TYPE_LEVEL_LOW>;
- };
-
- sic2: interrupt-controller@40010000 {
- compatible = "nxp,lpc3220-sic";
- reg = <0x40010000 0x4000>;
- interrupt-controller;
- #interrupt-cells = <2>;
-
- interrupt-parent = <&mic>;
- interrupts = <1 IRQ_TYPE_LEVEL_LOW>,
- <31 IRQ_TYPE_LEVEL_LOW>;
- };
-
- /* ADC */
- adc@40048000 {
- compatible = "nxp,lpc3220-adc";
- reg = <0x40048000 0x1000>;
- interrupt-parent = <&sic1>;
- interrupts = <7 IRQ_TYPE_LEVEL_HIGH>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.yaml b/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.yaml
new file mode 100644
index 000000000000..724c869e3c40
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/nxp,lpc3220-mic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP LPC32xx MIC, SIC1 and SIC2 Interrupt Controllers
+
+maintainers:
+ - Vladimir Zapolskiy <vz@mleia.com>
+
+properties:
+ compatible:
+ enum:
+ - nxp,lpc3220-mic
+ - nxp,lpc3220-sic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupts:
+ items:
+ - description: Regular interrupt request
+ - description: Fast interrupt request
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: nxp,lpc3220-sic
+ then:
+ required:
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ mic: interrupt-controller@40008000 {
+ compatible = "nxp,lpc3220-mic";
+ reg = <0x40008000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+
+ interrupt-controller@4000c000 {
+ compatible = "nxp,lpc3220-sic";
+ reg = <0x4000c000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&mic>;
+ interrupts = <0 IRQ_TYPE_LEVEL_LOW>,
+ <30 IRQ_TYPE_LEVEL_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt
deleted file mode 100644
index ccbbfdc53c72..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt
+++ /dev/null
@@ -1,97 +0,0 @@
-* Open PIC Binding
-
-This binding specifies what properties must be available in the device tree
-representation of an Open PIC compliant interrupt controller. This binding is
-based on the binding defined for Open PIC in [1] and is a superset of that
-binding.
-
-Required properties:
-
- NOTE: Many of these descriptions were paraphrased here from [1] to aid
- readability.
-
- - compatible: Specifies the compatibility list for the PIC. The type
- shall be <string> and the value shall include "open-pic".
-
- - reg: Specifies the base physical address(s) and size(s) of this
- PIC's addressable register space. The type shall be <prop-encoded-array>.
-
- - interrupt-controller: The presence of this property identifies the node
- as an Open PIC. No property value shall be defined.
-
- - #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The type shall be a <u32> and the value shall be 2.
-
- - #address-cells: Specifies the number of cells needed to encode an
- address. The type shall be <u32> and the value shall be 0. As such,
- 'interrupt-map' nodes do not have to specify a parent unit address.
-
-Optional properties:
-
- - pic-no-reset: The presence of this property indicates that the PIC
- shall not be reset during runtime initialization. No property value shall
- be defined. The presence of this property also mandates that any
- initialization related to interrupt sources shall be limited to sources
- explicitly referenced in the device tree.
-
-* Interrupt Specifier Definition
-
- Interrupt specifiers consists of 2 cells encoded as
- follows:
-
- - <1st-cell>: The interrupt-number that identifies the interrupt source.
-
- - <2nd-cell>: The level-sense information, encoded as follows:
- 0 = low-to-high edge triggered
- 1 = active low level-sensitive
- 2 = active high level-sensitive
- 3 = high-to-low edge triggered
-
-* Examples
-
-Example 1:
-
- /*
- * An Open PIC interrupt controller
- */
- mpic: pic@40000 {
- // This is an interrupt controller node.
- interrupt-controller;
-
- // No address cells so that 'interrupt-map' nodes which reference
- // this Open PIC node do not need a parent address specifier.
- #address-cells = <0>;
-
- // Two cells to encode interrupt sources.
- #interrupt-cells = <2>;
-
- // Offset address of 0x40000 and size of 0x40000.
- reg = <0x40000 0x40000>;
-
- // Compatible with Open PIC.
- compatible = "open-pic";
-
- // The PIC shall not be reset.
- pic-no-reset;
- };
-
-Example 2:
-
- /*
- * An interrupt generating device that is wired to an Open PIC.
- */
- serial0: serial@4500 {
- // Interrupt source '42' that is active high level-sensitive.
- // Note that there are only two cells as specified in the interrupt
- // parent's '#interrupt-cells' property.
- interrupts = <42 2>;
-
- // The interrupt controller that this device is wired to.
- interrupt-parent = <&mpic>;
- };
-
-* References
-
-[1] Devicetree Specification
- (https://www.devicetree.org/specifications/)
-
diff --git a/Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.txt
deleted file mode 100644
index 55c04faa3f3f..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-OpenRISC 1000 Programmable Interrupt Controller
-
-Required properties:
-
-- compatible : should be "opencores,or1k-pic-level" for variants with
- level triggered interrupt lines, "opencores,or1k-pic-edge" for variants with
- edge triggered interrupt lines or "opencores,or1200-pic" for machines
- with the non-spec compliant or1200 type implementation.
-
- "opencores,or1k-pic" is also provided as an alias to "opencores,or1200-pic",
- but this is only for backwards compatibility.
-
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 1.
-
-Example:
-
-intc: interrupt-controller {
- compatible = "opencores,or1k-pic-level";
- interrupt-controller;
- #interrupt-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.yaml
new file mode 100644
index 000000000000..995b68c3aed4
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/opencores,or1k-pic.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/opencores,or1k-pic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OpenRISC 1000 Programmable Interrupt Controller
+
+maintainers:
+ - Stefan Kristiansson <stefan.kristiansson@saunalahti.fi>
+
+properties:
+ compatible:
+ enum:
+ - opencores,or1k-pic-level
+ - opencores,or1k-pic-edge
+ - opencores,or1200-pic
+ - opencores,or1k-pic
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "opencores,or1k-pic-level";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.txt b/Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.txt
deleted file mode 100644
index caec07cc7149..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Open Multi-Processor Interrupt Controller
-
-Required properties:
-
-- compatible : This should be "openrisc,ompic"
-- reg : Specifies base physical address and size of the register space. The
- size is based on the number of cores the controller has been configured
- to handle, this should be set to 8 bytes per cpu core.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : This should be set to 0 as this will not be an irq
- parent.
-- interrupts : Specifies the interrupt line to which the ompic is wired.
-
-Example:
-
-ompic: interrupt-controller@98000000 {
- compatible = "openrisc,ompic";
- reg = <0x98000000 16>;
- interrupt-controller;
- #interrupt-cells = <0>;
- interrupts = <1>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.yaml b/Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.yaml
new file mode 100644
index 000000000000..4efbfba3aa6b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/openrisc,ompic.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/openrisc,ompic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Open Multi-Processor Interrupt Controller
+
+maintainers:
+ - Stafford Horne <shorne@gmail.com>
+
+properties:
+ compatible:
+ items:
+ - const: openrisc,ompic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@98000000 {
+ compatible = "openrisc,ompic";
+ reg = <0x98000000 16>;
+ interrupt-controller;
+ #interrupt-cells = <0>;
+ interrupts = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-cpu-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-cpu-intc.yaml
new file mode 100644
index 000000000000..ab32a91af4c4
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-cpu-intc.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/qca,ar7100-cpu-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Atheros ath79 CPU interrupt controller
+
+maintainers:
+ - Alban Bedel <albeu@free.fr>
+
+description:
+ On most SoC the IRQ controller need to flush the DDR FIFO before running the
+ interrupt handler of some devices. This is configured using the
+ qca,ddr-wb-channels and qca,ddr-wb-channel-interrupts properties.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: qca,ar9132-cpu-intc
+ - const: qca,ar7100-cpu-intc
+ - items:
+ - const: qca,ar7100-cpu-intc
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ qca,ddr-wb-channel-interrupts:
+ description: List of interrupts needing a write buffer flush
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ qca,ddr-wb-channels:
+ description: List of write buffer channel phandles for each interrupt
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "qca,ar9132-cpu-intc", "qca,ar7100-cpu-intc";
+
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ qca,ddr-wb-channel-interrupts = <2>, <3>, <4>, <5>;
+ qca,ddr-wb-channels = <&ddr_ctrl 3>, <&ddr_ctrl 2>,
+ <&ddr_ctrl 0>, <&ddr_ctrl 1>;
+ };
+
+ ddr_ctrl: memory-controller {
+ #qca,ddr-wb-channel-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-misc-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-misc-intc.yaml
new file mode 100644
index 000000000000..ae813189f5ab
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/qca,ar7100-misc-intc.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/qca,ar7100-misc-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Atheros AR7xxx/AR9XXX MISC interrupt controller
+
+maintainers:
+ - Alban Bedel <albeu@free.fr>
+ - Alexander Couzens <lynxis@fe80.eu>
+
+description:
+ The Qualcomm Atheros AR7xxx/AR9XXX MISC interrupt controller is a secondary
+ controller for lower priority interrupts.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: qca,ar9132-misc-intc
+ - const: qca,ar7100-misc-intc
+ - const: qca,ar7240-misc-intc
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+
+examples:
+ - |
+ interrupt-controller@18060010 {
+ compatible = "qca,ar9132-misc-intc", "qca,ar7100-misc-intc";
+ reg = <0x18060010 0x4>;
+ interrupts = <6>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-cpu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-cpu-intc.txt
deleted file mode 100644
index aabce7810d29..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-cpu-intc.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-Binding for Qualcomm Atheros AR7xxx/AR9XXX CPU interrupt controller
-
-On most SoC the IRQ controller need to flush the DDR FIFO before running
-the interrupt handler of some devices. This is configured using the
-qca,ddr-wb-channels and qca,ddr-wb-channel-interrupts properties.
-
-Required Properties:
-
-- compatible: has to be "qca,<soctype>-cpu-intc", "qca,ar7100-cpu-intc"
- as fallback
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode interrupt
- source, should be 1 for intc
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-Optional Properties:
-
-- qca,ddr-wb-channel-interrupts: List of the interrupts needing a write
- buffer flush
-- qca,ddr-wb-channels: List of phandles to the write buffer channels for
- each interrupt. If qca,ddr-wb-channel-interrupts is not present the interrupt
- default to the entry's index.
-
-Example:
-
- interrupt-controller {
- compatible = "qca,ar9132-cpu-intc", "qca,ar7100-cpu-intc";
-
- interrupt-controller;
- #interrupt-cells = <1>;
-
- qca,ddr-wb-channel-interrupts = <2>, <3>, <4>, <5>;
- qca,ddr-wb-channels = <&ddr_ctrl 3>, <&ddr_ctrl 2>,
- <&ddr_ctrl 0>, <&ddr_ctrl 1>;
- };
-
- ...
-
- ddr_ctrl: memory-controller@18000000 {
- ...
- #qca,ddr-wb-channel-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt
deleted file mode 100644
index ad70006c1848..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-Binding for Qualcomm Atheros AR7xxx/AR9XXX MISC interrupt controller
-
-The MISC interrupt controller is a secondary controller for lower priority
-interrupt.
-
-Required Properties:
-- compatible: has to be "qca,<soctype>-cpu-intc", "qca,ar7100-misc-intc" or
- "qca,<soctype>-cpu-intc", "qca,ar7240-misc-intc"
-- reg: Base address and size of the controllers memory area
-- interrupts: Interrupt specifier for the controllers interrupt.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode interrupt
- source, should be 1
-
-Compatible fallback depends on the SoC. Use ar7100 for ar71xx and ar913x,
-use ar7240 for all other SoCs.
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-Example:
-
- interrupt-controller@18060010 {
- compatible = "qca,ar9132-misc-intc", "qca,ar7100-misc-intc";
- reg = <0x18060010 0x4>;
-
- interrupt-parent = <&cpuintc>;
- interrupts = <6>;
-
- interrupt-controller;
- #interrupt-cells = <1>;
- };
-
-Another example:
-
- interrupt-controller@18060010 {
- compatible = "qca,ar9331-misc-intc", qca,ar7240-misc-intc";
- reg = <0x18060010 0x4>;
-
- interrupt-parent = <&cpuintc>;
- interrupts = <6>;
-
- interrupt-controller;
- #interrupt-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml
new file mode 100644
index 000000000000..ebb40c48950a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,mpm.yaml
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/qcom,mpm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcom MPM Interrupt Controller
+
+maintainers:
+ - Shawn Guo <shawn.guo@linaro.org>
+
+description:
+ Qualcomm Technologies Inc. SoCs based on the RPM architecture have a
+ MSM Power Manager (MPM) that is in always-on domain. In addition to managing
+ resources during sleep, the hardware also has an interrupt controller that
+ monitors the interrupts when the system is asleep, wakes up the APSS when
+ one of these interrupts occur and replays it to GIC interrupt controller
+ after GIC becomes operational.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - const: qcom,mpm
+
+ reg:
+ maxItems: 1
+ description:
+ Specifies the base address and size of vMPM registers in RPM MSG RAM.
+ deprecated: true
+
+ qcom,rpm-msg-ram:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle to the APSS MPM slice of the RPM Message RAM
+
+ interrupts:
+ maxItems: 1
+ description:
+ Specify the IRQ used by RPM to wakeup APSS.
+
+ mboxes:
+ maxItems: 1
+ description:
+ Specify the mailbox used to notify RPM for writing vMPM registers.
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+ description:
+ The first cell is the MPM pin number for the interrupt, and the second
+ is the trigger type.
+
+ qcom,mpm-pin-count:
+ description:
+ Specify the total MPM pin count that a SoC supports.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ qcom,mpm-pin-map:
+ description:
+ A set of MPM pin numbers and the corresponding GIC SPIs.
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ items:
+ items:
+ - description: MPM pin number
+ - description: GIC SPI number for the MPM pin
+
+ '#power-domain-cells':
+ const: 0
+
+required:
+ - compatible
+ - interrupts
+ - mboxes
+ - interrupt-controller
+ - '#interrupt-cells'
+ - qcom,mpm-pin-count
+ - qcom,mpm-pin-map
+ - qcom,rpm-msg-ram
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ remoteproc-rpm {
+ compatible = "qcom,msm8998-rpm-proc", "qcom,rpm-proc";
+
+ glink-edge {
+ compatible = "qcom,glink-rpm";
+
+ interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>;
+ qcom,rpm-msg-ram = <&rpm_msg_ram>;
+ mboxes = <&apcs_glb 0>;
+ };
+
+ mpm: interrupt-controller {
+ compatible = "qcom,mpm";
+ qcom,rpm-msg-ram = <&apss_mpm>;
+ interrupts = <GIC_SPI 197 IRQ_TYPE_EDGE_RISING>;
+ mboxes = <&apcs_glb 1>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&intc>;
+ qcom,mpm-pin-count = <96>;
+ qcom,mpm-pin-map = <2 275>,
+ <5 296>,
+ <12 422>,
+ <24 79>,
+ <86 183>,
+ <91 260>;
+ #power-domain-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt
deleted file mode 100644
index 98d89e53013d..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt
+++ /dev/null
@@ -1,76 +0,0 @@
-PDC interrupt controller
-
-Qualcomm Technologies Inc. SoCs based on the RPM Hardened architecture have a
-Power Domain Controller (PDC) that is on always-on domain. In addition to
-providing power control for the power domains, the hardware also has an
-interrupt controller that can be used to help detect edge low interrupts as
-well detect interrupts when the GIC is non-operational.
-
-GIC is parent interrupt controller at the highest level. Platform interrupt
-controller PDC is next in hierarchy, followed by others. Drivers requiring
-wakeup capabilities of their device interrupts routed through the PDC, must
-specify PDC as their interrupt controller and request the PDC port associated
-with the GIC interrupt. See example below.
-
-Properties:
-
-- compatible:
- Usage: required
- Value type: <string>
- Definition: Should contain "qcom,<soc>-pdc" and "qcom,pdc"
- - "qcom,sc7180-pdc": For SC7180
- - "qcom,sc7280-pdc": For SC7280
- - "qcom,sdm845-pdc": For SDM845
- - "qcom,sdm8250-pdc": For SM8250
- - "qcom,sdm8350-pdc": For SM8350
-
-- reg:
- Usage: required
- Value type: <prop-encoded-array>
- Definition: Specifies the base physical address for PDC hardware.
-
-- interrupt-cells:
- Usage: required
- Value type: <u32>
- Definition: Specifies the number of cells needed to encode an interrupt
- source.
- Must be 2.
- The first element of the tuple is the PDC pin for the
- interrupt.
- The second element is the trigger type.
-
-- interrupt-controller:
- Usage: required
- Value type: <bool>
- Definition: Identifies the node as an interrupt controller.
-
-- qcom,pdc-ranges:
- Usage: required
- Value type: <u32 array>
- Definition: Specifies the PDC pin offset and the number of PDC ports.
- The tuples indicates the valid mapping of valid PDC ports
- and their hwirq mapping.
- The first element of the tuple is the starting PDC port.
- The second element is the GIC hwirq number for the PDC port.
- The third element is the number of interrupts in sequence.
-
-Example:
-
- pdc: interrupt-controller@b220000 {
- compatible = "qcom,sdm845-pdc";
- reg = <0xb220000 0x30000>;
- qcom,pdc-ranges = <0 512 94>, <94 641 15>, <115 662 7>;
- #interrupt-cells = <2>;
- interrupt-parent = <&intc>;
- interrupt-controller;
- };
-
-DT binding of a device that wants to use the GIC SPI 514 as a wakeup
-interrupt, must do -
-
- wake-device {
- interrupts-extended = <&pdc 2 IRQ_TYPE_LEVEL_HIGH>;
- };
-
-In this case interrupt 514 would be mapped to port 2 on the PDC as defined by
-the qcom,pdc-ranges property.
diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml
new file mode 100644
index 000000000000..38d0c2d57dd6
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/qcom,pdc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: PDC interrupt controller
+
+maintainers:
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+description: |
+ Qualcomm Technologies Inc. SoCs based on the RPM Hardened architecture have a
+ Power Domain Controller (PDC) that is on always-on domain. In addition to
+ providing power control for the power domains, the hardware also has an
+ interrupt controller that can be used to help detect edge low interrupts as
+ well detect interrupts when the GIC is non-operational.
+
+ GIC is parent interrupt controller at the highest level. Platform interrupt
+ controller PDC is next in hierarchy, followed by others. Drivers requiring
+ wakeup capabilities of their device interrupts routed through the PDC, must
+ specify PDC as their interrupt controller and request the PDC port associated
+ with the GIC interrupt. See example below.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - qcom,glymur-pdc
+ - qcom,qcs615-pdc
+ - qcom,qcs8300-pdc
+ - qcom,qdu1000-pdc
+ - qcom,sa8255p-pdc
+ - qcom,sa8775p-pdc
+ - qcom,sar2130p-pdc
+ - qcom,sc7180-pdc
+ - qcom,sc7280-pdc
+ - qcom,sc8180x-pdc
+ - qcom,sc8280xp-pdc
+ - qcom,sdm670-pdc
+ - qcom,sdm845-pdc
+ - qcom,sdx55-pdc
+ - qcom,sdx65-pdc
+ - qcom,sdx75-pdc
+ - qcom,sm4450-pdc
+ - qcom,sm6350-pdc
+ - qcom,sm8150-pdc
+ - qcom,sm8250-pdc
+ - qcom,sm8350-pdc
+ - qcom,sm8450-pdc
+ - qcom,sm8550-pdc
+ - qcom,sm8650-pdc
+ - qcom,sm8750-pdc
+ - qcom,x1e80100-pdc
+ - const: qcom,pdc
+
+ reg:
+ minItems: 1
+ items:
+ - description: PDC base register region
+ - description: Edge or Level config register for SPI interrupts
+
+ '#interrupt-cells':
+ const: 2
+
+ interrupt-controller: true
+
+ qcom,pdc-ranges:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ minItems: 1
+ maxItems: 128 # no hard limit
+ items:
+ items:
+ - description: starting PDC port
+ - description: GIC hwirq number for the PDC port
+ - description: number of interrupts in sequence
+ description: |
+ Specifies the PDC pin offset and the number of PDC ports.
+ The tuples indicates the valid mapping of valid PDC ports
+ and their hwirq mapping.
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupt-controller
+ - qcom,pdc-ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ pdc: interrupt-controller@b220000 {
+ compatible = "qcom,sdm845-pdc", "qcom,pdc";
+ reg = <0xb220000 0x30000>;
+ qcom,pdc-ranges = <0 512 94>, <94 641 15>, <115 662 7>;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&intc>;
+ interrupt-controller;
+ };
+
+ wake-device {
+ interrupts-extended = <&pdc 2 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ralink,rt2880-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ralink,rt2880-intc.yaml
new file mode 100644
index 000000000000..0fa952a9edfd
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/ralink,rt2880-intc.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/ralink,rt2880-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ralink SoCs Interrupt Controller
+
+maintainers:
+ - Sergio Paracuellos <sergio.paracuellos@gmail.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+description:
+ This interrupt controller support a central point for interrupt aggregation
+ for platform related blocks.
+
+properties:
+ compatible:
+ const: ralink,rt2880-intc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@200 {
+ compatible = "ralink,rt2880-intc";
+ reg = <0x200 0x100>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+
+ interrupt-parent = <&cpuintc>;
+ interrupts = <2>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.txt
deleted file mode 100644
index e0062aebf025..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-RDA Micro RDA8810PL Interrupt Controller
-
-The interrupt controller in RDA8810PL SoC is a custom interrupt controller
-which supports up to 32 interrupts.
-
-Required properties:
-
-- compatible: Should be "rda,8810pl-intc".
-- reg: Specifies base physical address of the registers set.
-- interrupt-controller: Identifies the node as an interrupt controller.
-- #interrupt-cells: Specifies the number of cells needed to encode an
- interrupt source. The value shall be 2.
-
-The interrupt sources are as follows:
-
-ID Name
-------------
-0: PULSE_DUMMY
-1: I2C
-2: NAND_NFSC
-3: SDMMC1
-4: SDMMC2
-5: SDMMC3
-6: SPI1
-7: SPI2
-8: SPI3
-9: UART1
-10: UART2
-11: UART3
-12: GPIO1
-13: GPIO2
-14: GPIO3
-15: KEYPAD
-16: TIMER
-17: TIMEROS
-18: COMREG0
-19: COMREG1
-20: USB
-21: DMC
-22: DMA
-23: CAMERA
-24: GOUDA
-25: GPU
-26: VPU_JPG
-27: VPU_HOST
-28: VOC
-29: AUIFC0
-30: AUIFC1
-31: L2CC
-
-Example:
- apb@20800000 {
- compatible = "simple-bus";
- ...
- intc: interrupt-controller@0 {
- compatible = "rda,8810pl-intc";
- reg = <0x0 0x1000>;
- interrupt-controller;
- #interrupt-cells = <2>;
- };
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.yaml
new file mode 100644
index 000000000000..96d6285d0087
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/rda,8810pl-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RDA Micro RDA8810PL interrupt controller
+
+maintainers:
+ - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: rda,8810pl-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ intc: interrupt-controller@0 {
+ compatible = "rda,8810pl-intc";
+ reg = <0x0 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml
index 9e76fff20323..833a01cdd1b1 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml
@@ -4,7 +4,15 @@
$id: http://devicetree.org/schemas/interrupt-controller/realtek,rtl-intc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Realtek RTL SoC interrupt controller devicetree bindings
+title: Realtek RTL SoC interrupt controller
+
+description:
+ Interrupt controller and router for Realtek MIPS SoCs, allowing each SoC
+ interrupt to be routed to one parent CPU (hardware) interrupt, or left
+ disconnected.
+ All connected input lines from SoC peripherals can be masked individually,
+ and an interrupt status register is present to indicate which interrupts are
+ pending.
maintainers:
- Birger Koblitz <mail@birger-koblitz.de>
@@ -13,23 +21,37 @@ maintainers:
properties:
compatible:
- const: realtek,rtl-intc
+ oneOf:
+ - items:
+ - enum:
+ - realtek,rtl8380-intc
+ - realtek,rtl9300-intc
+ - const: realtek,rtl-intc
+ - const: realtek,rtl-intc
+ deprecated: true
"#interrupt-cells":
+ description:
+ SoC interrupt line index.
const: 1
reg:
- maxItems: 1
+ minItems: 1
+ items:
+ - description: vpe0 registers
+ - description: vpe1 registers
interrupts:
- maxItems: 1
+ minItems: 1
+ maxItems: 15
+ description:
+ List of parent interrupts, in the order that they are connected to this
+ interrupt router's outputs, starting at the first output.
interrupt-controller: true
- "#address-cells":
- const: 0
-
interrupt-map:
+ deprecated: true
description: Describes mapping from SoC interrupts to CPU interrupts
required:
@@ -37,21 +59,47 @@ required:
- reg
- "#interrupt-cells"
- interrupt-controller
- - "#address-cells"
- - interrupt-map
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ const: realtek,rtl-intc
+ then:
+ properties:
+ "#address-cells":
+ const: 0
+ required:
+ - "#address-cells"
+ - interrupt-map
+ else:
+ required:
+ - interrupts
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: realtek,rtl9300-intc
+ then:
+ properties:
+ reg:
+ minItems: 2
+ maxItems: 2
+ else:
+ properties:
+ reg:
+ maxItems: 1
additionalProperties: false
examples:
- |
- intc: interrupt-controller@3000 {
- compatible = "realtek,rtl-intc";
+ interrupt-controller@3000 {
+ compatible = "realtek,rtl8380-intc", "realtek,rtl-intc";
#interrupt-cells = <1>;
interrupt-controller;
- reg = <0x3000 0x20>;
- #address-cells = <0>;
- interrupt-map =
- <31 &cpuintc 2>,
- <30 &cpuintc 1>,
- <29 &cpuintc 5>;
+ reg = <0x3000 0x18>;
+
+ interrupt-parent = <&cpuintc>;
+ interrupts = <2>, <3>, <4>, <5>, <6>;
};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,h8300h-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,h8300h-intc.txt
deleted file mode 100644
index 56e8d82aff34..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/renesas,h8300h-intc.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-* H8/300H Interrupt controller
-
-Required properties:
-
-- compatible: has to be "renesas,h8300h-intc", "renesas,h8300-intc" as fallback.
-- #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in
- interrupts.txt in this directory
-- regs: Base address of interrupt controller registers.
-
-Optional properties:
-
-- any properties, listed in interrupts.txt, and any standard resource allocation
- properties
-
-Example:
-
- h8intc: interrupt-controller@fee012 {
- compatible = "renesas,h8300h-intc", "renesas,h8300-intc";
- #interrupt-cells = <2>;
- interrupt-controller;
- reg = <0xfee012 7>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,h8s-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,h8s-intc.txt
deleted file mode 100644
index faded2b1559b..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/renesas,h8s-intc.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-* H8S Interrupt controller
-
-Required properties:
-
-- compatible: has to be "renesas,h8s-intc", "renesas,h8300-intc" as fallback.
-- #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in
- interrupts.txt in this directory
-- regs: Base address of interrupt controller registers.
-
-Optional properties:
-
-- any properties, listed in interrupts.txt, and any standard resource allocation
- properties
-
-Example:
-
- h8intc: interrupt-controller@fffe00 {
- compatible = "renesas,h8s-intc", "renesas,h8300-intc";
- #interrupt-cells = <2>;
- interrupt-controller;
- reg = <0xfffe00 24>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml
index abb22db3bb28..fb3c29e81349 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/interrupt-controller/renesas,irqc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: DT bindings for the R-Mobile/R-Car/RZ/G interrupt controller
+title: R-Mobile/R-Car/RZ/G interrupt controller
maintainers:
- Geert Uytterhoeven <geert+renesas@glider.be>
@@ -27,6 +27,7 @@ properties:
- renesas,intc-ex-r8a774a1 # RZ/G2M
- renesas,intc-ex-r8a774b1 # RZ/G2N
- renesas,intc-ex-r8a774c0 # RZ/G2E
+ - renesas,intc-ex-r8a774e1 # RZ/G2H
- renesas,intc-ex-r8a7795 # R-Car H3
- renesas,intc-ex-r8a7796 # R-Car M3-W
- renesas,intc-ex-r8a77961 # R-Car M3-W+
@@ -35,6 +36,10 @@ properties:
- renesas,intc-ex-r8a77980 # R-Car V3H
- renesas,intc-ex-r8a77990 # R-Car E3
- renesas,intc-ex-r8a77995 # R-Car D3
+ - renesas,intc-ex-r8a779a0 # R-Car V3U
+ - renesas,intc-ex-r8a779f0 # R-Car S4-8
+ - renesas,intc-ex-r8a779g0 # R-Car V4H
+ - renesas,intc-ex-r8a779h0 # R-Car V4M
- const: renesas,irqc
'#interrupt-cells':
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml
new file mode 100644
index 000000000000..44b6ae5fc802
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzg2l-irqc.yaml
@@ -0,0 +1,282 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/renesas,rzg2l-irqc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/G2L (and alike SoC's) Interrupt Controller (IA55)
+
+maintainers:
+ - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
+ - Geert Uytterhoeven <geert+renesas@glider.be>
+
+description: |
+ IA55 performs various interrupt controls including synchronization for the external
+ interrupts of NMI, IRQ, and GPIOINT and the interrupts of the built-in peripheral
+ interrupts output by each IP. And it notifies the interrupt to the GIC
+ - IRQ sense select for 8 external interrupts, mapped to 8 GIC SPI interrupts
+ - GPIO pins used as external interrupt input pins, mapped to 32 GIC SPI interrupts
+ - NMI edge select (NMI is not treated as NMI exception and supports fall edge and
+ stand-up edge detection interrupts)
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,r9a07g043u-irqc # RZ/G2UL
+ - renesas,r9a07g044-irqc # RZ/G2{L,LC}
+ - renesas,r9a07g054-irqc # RZ/V2L
+ - renesas,r9a08g045-irqc # RZ/G3S
+ - const: renesas,rzg2l-irqc
+
+ - const: renesas,r9a07g043f-irqc # RZ/Five
+
+ '#interrupt-cells':
+ description: The first cell should contain a macro RZG2L_{NMI,IRQX} included in the
+ include/dt-bindings/interrupt-controller/irqc-rzg2l.h and the second
+ cell is used to specify the flag.
+ const: 2
+
+ '#address-cells':
+ const: 0
+
+ interrupt-controller: true
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 45
+ items:
+ - description: NMI interrupt
+ - description: IRQ0 interrupt
+ - description: IRQ1 interrupt
+ - description: IRQ2 interrupt
+ - description: IRQ3 interrupt
+ - description: IRQ4 interrupt
+ - description: IRQ5 interrupt
+ - description: IRQ6 interrupt
+ - description: IRQ7 interrupt
+ - description: GPIO interrupt, TINT0
+ - description: GPIO interrupt, TINT1
+ - description: GPIO interrupt, TINT2
+ - description: GPIO interrupt, TINT3
+ - description: GPIO interrupt, TINT4
+ - description: GPIO interrupt, TINT5
+ - description: GPIO interrupt, TINT6
+ - description: GPIO interrupt, TINT7
+ - description: GPIO interrupt, TINT8
+ - description: GPIO interrupt, TINT9
+ - description: GPIO interrupt, TINT10
+ - description: GPIO interrupt, TINT11
+ - description: GPIO interrupt, TINT12
+ - description: GPIO interrupt, TINT13
+ - description: GPIO interrupt, TINT14
+ - description: GPIO interrupt, TINT15
+ - description: GPIO interrupt, TINT16
+ - description: GPIO interrupt, TINT17
+ - description: GPIO interrupt, TINT18
+ - description: GPIO interrupt, TINT19
+ - description: GPIO interrupt, TINT20
+ - description: GPIO interrupt, TINT21
+ - description: GPIO interrupt, TINT22
+ - description: GPIO interrupt, TINT23
+ - description: GPIO interrupt, TINT24
+ - description: GPIO interrupt, TINT25
+ - description: GPIO interrupt, TINT26
+ - description: GPIO interrupt, TINT27
+ - description: GPIO interrupt, TINT28
+ - description: GPIO interrupt, TINT29
+ - description: GPIO interrupt, TINT30
+ - description: GPIO interrupt, TINT31
+ - description: Bus error interrupt
+ - description: ECCRAM0 or combined ECCRAM0/1 1bit error interrupt
+ - description: ECCRAM0 or combined ECCRAM0/1 2bit error interrupt
+ - description: ECCRAM0 or combined ECCRAM0/1 error overflow interrupt
+ - description: ECCRAM1 1bit error interrupt
+ - description: ECCRAM1 2bit error interrupt
+ - description: ECCRAM1 error overflow interrupt
+
+ interrupt-names:
+ minItems: 45
+ items:
+ - const: nmi
+ - const: irq0
+ - const: irq1
+ - const: irq2
+ - const: irq3
+ - const: irq4
+ - const: irq5
+ - const: irq6
+ - const: irq7
+ - const: tint0
+ - const: tint1
+ - const: tint2
+ - const: tint3
+ - const: tint4
+ - const: tint5
+ - const: tint6
+ - const: tint7
+ - const: tint8
+ - const: tint9
+ - const: tint10
+ - const: tint11
+ - const: tint12
+ - const: tint13
+ - const: tint14
+ - const: tint15
+ - const: tint16
+ - const: tint17
+ - const: tint18
+ - const: tint19
+ - const: tint20
+ - const: tint21
+ - const: tint22
+ - const: tint23
+ - const: tint24
+ - const: tint25
+ - const: tint26
+ - const: tint27
+ - const: tint28
+ - const: tint29
+ - const: tint30
+ - const: tint31
+ - const: bus-err
+ - const: ec7tie1-0
+ - const: ec7tie2-0
+ - const: ec7tiovf-0
+ - const: ec7tie1-1
+ - const: ec7tie2-1
+ - const: ec7tiovf-1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: clk
+ - const: pclk
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - '#address-cells'
+ - interrupt-controller
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r9a08g045-irqc
+ then:
+ properties:
+ interrupts:
+ maxItems: 45
+ interrupt-names:
+ maxItems: 45
+ else:
+ properties:
+ interrupts:
+ minItems: 48
+ interrupt-names:
+ minItems: 48
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/r9a07g044-cpg.h>
+
+ irqc: interrupt-controller@110a0000 {
+ compatible = "renesas,r9a07g044-irqc", "renesas,rzg2l-irqc";
+ reg = <0x110a0000 0x10000>;
+ #interrupt-cells = <2>;
+ #address-cells = <0>;
+ interrupt-controller;
+ interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 444 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 445 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 446 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 447 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 449 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 450 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 451 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 452 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 453 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 454 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 455 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 456 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 457 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 458 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 459 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 460 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 461 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 462 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 463 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 470 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 471 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 472 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 473 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 474 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 475 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 25 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 34 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 35 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 36 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 37 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 38 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 39 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "nmi",
+ "irq0", "irq1", "irq2", "irq3",
+ "irq4", "irq5", "irq6", "irq7",
+ "tint0", "tint1", "tint2", "tint3",
+ "tint4", "tint5", "tint6", "tint7",
+ "tint8", "tint9", "tint10", "tint11",
+ "tint12", "tint13", "tint14", "tint15",
+ "tint16", "tint17", "tint18", "tint19",
+ "tint20", "tint21", "tint22", "tint23",
+ "tint24", "tint25", "tint26", "tint27",
+ "tint28", "tint29", "tint30", "tint31",
+ "bus-err", "ec7tie1-0", "ec7tie2-0",
+ "ec7tiovf-0", "ec7tie1-1", "ec7tie2-1",
+ "ec7tiovf-1";
+ clocks = <&cpg CPG_MOD R9A07G044_IA55_CLK>,
+ <&cpg CPG_MOD R9A07G044_IA55_PCLK>;
+ clock-names = "clk", "pclk";
+ power-domains = <&cpg>;
+ resets = <&cpg R9A07G044_IA55_RESETN>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rzv2h-icu.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzv2h-icu.yaml
new file mode 100644
index 000000000000..3f99c8645767
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rzv2h-icu.yaml
@@ -0,0 +1,280 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/renesas,rzv2h-icu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/{G3E,V2H(P)} Interrupt Control Unit
+
+maintainers:
+ - Fabrizio Castro <fabrizio.castro.jz@renesas.com>
+ - Geert Uytterhoeven <geert+renesas@glider.be>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+description:
+ The Interrupt Control Unit (ICU) handles external interrupts (NMI, IRQ, and
+ TINT), error interrupts, DMAC requests, GPT interrupts, and internal
+ interrupts.
+
+properties:
+ compatible:
+ enum:
+ - renesas,r9a09g047-icu # RZ/G3E
+ - renesas,r9a09g057-icu # RZ/V2H(P)
+
+ '#interrupt-cells':
+ description: The first cell is the SPI number of the NMI or the
+ PORT_IRQ[0-15] interrupt, as per user manual. The second cell is used to
+ specify the flag.
+ const: 2
+
+ '#address-cells':
+ const: 0
+
+ interrupt-controller: true
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 58
+ items:
+ - description: NMI interrupt
+ - description: PORT_IRQ0 interrupt
+ - description: PORT_IRQ1 interrupt
+ - description: PORT_IRQ2 interrupt
+ - description: PORT_IRQ3 interrupt
+ - description: PORT_IRQ4 interrupt
+ - description: PORT_IRQ5 interrupt
+ - description: PORT_IRQ6 interrupt
+ - description: PORT_IRQ7 interrupt
+ - description: PORT_IRQ8 interrupt
+ - description: PORT_IRQ9 interrupt
+ - description: PORT_IRQ10 interrupt
+ - description: PORT_IRQ11 interrupt
+ - description: PORT_IRQ12 interrupt
+ - description: PORT_IRQ13 interrupt
+ - description: PORT_IRQ14 interrupt
+ - description: PORT_IRQ15 interrupt
+ - description: GPIO interrupt, TINT0
+ - description: GPIO interrupt, TINT1
+ - description: GPIO interrupt, TINT2
+ - description: GPIO interrupt, TINT3
+ - description: GPIO interrupt, TINT4
+ - description: GPIO interrupt, TINT5
+ - description: GPIO interrupt, TINT6
+ - description: GPIO interrupt, TINT7
+ - description: GPIO interrupt, TINT8
+ - description: GPIO interrupt, TINT9
+ - description: GPIO interrupt, TINT10
+ - description: GPIO interrupt, TINT11
+ - description: GPIO interrupt, TINT12
+ - description: GPIO interrupt, TINT13
+ - description: GPIO interrupt, TINT14
+ - description: GPIO interrupt, TINT15
+ - description: GPIO interrupt, TINT16
+ - description: GPIO interrupt, TINT17
+ - description: GPIO interrupt, TINT18
+ - description: GPIO interrupt, TINT19
+ - description: GPIO interrupt, TINT20
+ - description: GPIO interrupt, TINT21
+ - description: GPIO interrupt, TINT22
+ - description: GPIO interrupt, TINT23
+ - description: GPIO interrupt, TINT24
+ - description: GPIO interrupt, TINT25
+ - description: GPIO interrupt, TINT26
+ - description: GPIO interrupt, TINT27
+ - description: GPIO interrupt, TINT28
+ - description: GPIO interrupt, TINT29
+ - description: GPIO interrupt, TINT30
+ - description: GPIO interrupt, TINT31
+ - description: Software interrupt, INTA55_0
+ - description: Software interrupt, INTA55_1
+ - description: Software interrupt, INTA55_2
+ - description: Software interrupt, INTA55_3
+ - description: Error interrupt to CA55
+ - description: GTCCRA compare match/input capture (U0)
+ - description: GTCCRB compare match/input capture (U0)
+ - description: GTCCRA compare match/input capture (U1)
+ - description: GTCCRB compare match/input capture (U1)
+
+ interrupt-names:
+ minItems: 58
+ items:
+ - const: nmi
+ - const: port_irq0
+ - const: port_irq1
+ - const: port_irq2
+ - const: port_irq3
+ - const: port_irq4
+ - const: port_irq5
+ - const: port_irq6
+ - const: port_irq7
+ - const: port_irq8
+ - const: port_irq9
+ - const: port_irq10
+ - const: port_irq11
+ - const: port_irq12
+ - const: port_irq13
+ - const: port_irq14
+ - const: port_irq15
+ - const: tint0
+ - const: tint1
+ - const: tint2
+ - const: tint3
+ - const: tint4
+ - const: tint5
+ - const: tint6
+ - const: tint7
+ - const: tint8
+ - const: tint9
+ - const: tint10
+ - const: tint11
+ - const: tint12
+ - const: tint13
+ - const: tint14
+ - const: tint15
+ - const: tint16
+ - const: tint17
+ - const: tint18
+ - const: tint19
+ - const: tint20
+ - const: tint21
+ - const: tint22
+ - const: tint23
+ - const: tint24
+ - const: tint25
+ - const: tint26
+ - const: tint27
+ - const: tint28
+ - const: tint29
+ - const: tint30
+ - const: tint31
+ - const: int-ca55-0
+ - const: int-ca55-1
+ - const: int-ca55-2
+ - const: int-ca55-3
+ - const: icu-error-ca55
+ - const: gpt-u0-gtciada
+ - const: gpt-u0-gtciadb
+ - const: gpt-u1-gtciada
+ - const: gpt-u1-gtciadb
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - '#address-cells'
+ - interrupt-controller
+ - interrupts
+ - interrupt-names
+ - clocks
+ - power-domains
+ - resets
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/renesas-cpg-mssr.h>
+
+ icu: interrupt-controller@10400000 {
+ compatible = "renesas,r9a09g057-icu";
+ reg = <0x10400000 0x10000>;
+ #interrupt-cells = <2>;
+ #address-cells = <0>;
+ interrupt-controller;
+ interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 420 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 421 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 422 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 423 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 424 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 425 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 426 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 427 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 428 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 429 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 430 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 431 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 432 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 433 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 434 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 435 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 436 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 437 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 438 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 439 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 440 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 441 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 442 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 443 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 444 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 445 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 446 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 447 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 449 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 450 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 262 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 263 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 264 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 265 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 266 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 451 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 452 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 453 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 454 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "nmi",
+ "port_irq0", "port_irq1", "port_irq2",
+ "port_irq3", "port_irq4", "port_irq5",
+ "port_irq6", "port_irq7", "port_irq8",
+ "port_irq9", "port_irq10", "port_irq11",
+ "port_irq12", "port_irq13", "port_irq14",
+ "port_irq15",
+ "tint0", "tint1", "tint2", "tint3",
+ "tint4", "tint5", "tint6", "tint7",
+ "tint8", "tint9", "tint10", "tint11",
+ "tint12", "tint13", "tint14", "tint15",
+ "tint16", "tint17", "tint18", "tint19",
+ "tint20", "tint21", "tint22", "tint23",
+ "tint24", "tint25", "tint26", "tint27",
+ "tint28", "tint29", "tint30", "tint31",
+ "int-ca55-0", "int-ca55-1",
+ "int-ca55-2", "int-ca55-3",
+ "icu-error-ca55",
+ "gpt-u0-gtciada", "gpt-u0-gtciadb",
+ "gpt-u1-gtciada", "gpt-u1-gtciadb";
+ clocks = <&cpg CPG_MOD 0x5>;
+ power-domains = <&cpg>;
+ resets = <&cpg 0x36>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml b/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml
new file mode 100644
index 000000000000..bef00521d5da
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml
@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/riscv,aplic.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RISC-V Advanced Platform Level Interrupt Controller (APLIC)
+
+maintainers:
+ - Anup Patel <anup@brainfault.org>
+
+description:
+ The RISC-V advanced interrupt architecture (AIA) defines an advanced
+ platform level interrupt controller (APLIC) for handling wired interrupts
+ in a RISC-V platform. The RISC-V AIA specification can be found at
+ https://github.com/riscv/riscv-aia.
+
+ The RISC-V APLIC is implemented as hierarchical APLIC domains where all
+ interrupt sources connect to the root APLIC domain and a parent APLIC
+ domain can delegate interrupt sources to it's child APLIC domains. There
+ is one device tree node for each APLIC domain.
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - qemu,aplic
+ - const: riscv,aplic
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+
+ interrupts-extended:
+ minItems: 1
+ maxItems: 16384
+ description:
+ Given APLIC domain directly injects external interrupts to a set of
+ RISC-V HARTS (or CPUs). Each node pointed to should be a riscv,cpu-intc
+ node, which has a CPU node (i.e. RISC-V HART) as parent.
+
+ msi-parent:
+ description:
+ Given APLIC domain forwards wired interrupts as MSIs to a AIA incoming
+ message signaled interrupt controller (IMSIC). If both "msi-parent" and
+ "interrupts-extended" properties are present then it means the APLIC
+ domain supports both MSI mode and Direct mode in HW. In this case, the
+ APLIC driver has to choose between MSI mode or Direct mode.
+
+ riscv,num-sources:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 1023
+ description:
+ Specifies the number of wired interrupt sources supported by this
+ APLIC domain.
+
+ riscv,children:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ minItems: 1
+ maxItems: 1024
+ items:
+ maxItems: 1
+ description:
+ A list of child APLIC domains for the given APLIC domain. Each child
+ APLIC domain is assigned a child index in increasing order, with the
+ first child APLIC domain assigned child index 0. The APLIC domain child
+ index is used by firmware to delegate interrupts from the given APLIC
+ domain to a particular child APLIC domain.
+
+ riscv,delegation:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ minItems: 1
+ maxItems: 1024
+ items:
+ items:
+ - description: child APLIC domain phandle
+ - description: first interrupt number of the parent APLIC domain (inclusive)
+ - description: last interrupt number of the parent APLIC domain (inclusive)
+ description:
+ A interrupt delegation list where each entry is a triple consisting
+ of child APLIC domain phandle, first interrupt number of the parent
+ APLIC domain, and last interrupt number of the parent APLIC domain.
+ Firmware must configure interrupt delegation registers based on
+ interrupt delegation list.
+
+ riscv,hart-indexes:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 16384
+ description:
+ A list of hart indexes that APLIC should use to address each hart
+ that is mentioned in the "interrupts-extended"
+
+dependencies:
+ riscv,delegation: [ "riscv,children" ]
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - riscv,num-sources
+
+anyOf:
+ - required:
+ - interrupts-extended
+ - required:
+ - msi-parent
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ // Example 1 (APLIC domains directly injecting interrupt to HARTs):
+
+ interrupt-controller@c000000 {
+ compatible = "qemu,aplic", "riscv,aplic";
+ interrupts-extended = <&cpu1_intc 11>,
+ <&cpu2_intc 11>,
+ <&cpu3_intc 11>,
+ <&cpu4_intc 11>;
+ reg = <0xc000000 0x4080>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ riscv,num-sources = <63>;
+ riscv,children = <&aplic1>, <&aplic2>;
+ riscv,delegation = <&aplic1 1 63>;
+ };
+
+ aplic1: interrupt-controller@d000000 {
+ compatible = "qemu,aplic", "riscv,aplic";
+ interrupts-extended = <&cpu1_intc 9>,
+ <&cpu2_intc 9>;
+ reg = <0xd000000 0x4080>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ riscv,num-sources = <63>;
+ };
+
+ aplic2: interrupt-controller@e000000 {
+ compatible = "qemu,aplic", "riscv,aplic";
+ interrupts-extended = <&cpu3_intc 9>,
+ <&cpu4_intc 9>;
+ reg = <0xe000000 0x4080>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ riscv,num-sources = <63>;
+ };
+
+ - |
+ // Example 2 (APLIC domains forwarding interrupts as MSIs):
+
+ interrupt-controller@c000000 {
+ compatible = "qemu,aplic", "riscv,aplic";
+ msi-parent = <&imsic_mlevel>;
+ reg = <0xc000000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ riscv,num-sources = <63>;
+ riscv,children = <&aplic3>;
+ riscv,delegation = <&aplic3 1 63>;
+ };
+
+ aplic3: interrupt-controller@d000000 {
+ compatible = "qemu,aplic", "riscv,aplic";
+ msi-parent = <&imsic_slevel>;
+ reg = <0xd000000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ riscv,num-sources = <63>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt
deleted file mode 100644
index 265b223cd978..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-RISC-V Hart-Level Interrupt Controller (HLIC)
----------------------------------------------
-
-RISC-V cores include Control Status Registers (CSRs) which are local to each
-CPU core (HART in RISC-V terminology) and can be read or written by software.
-Some of these CSRs are used to control local interrupts connected to the core.
-Every interrupt is ultimately routed through a hart's HLIC before it
-interrupts that hart.
-
-The RISC-V supervisor ISA manual specifies three interrupt sources that are
-attached to every HLIC: software interrupts, the timer interrupt, and external
-interrupts. Software interrupts are used to send IPIs between cores. The
-timer interrupt comes from an architecturally mandated real-time timer that is
-controlled via Supervisor Binary Interface (SBI) calls and CSR reads. External
-interrupts connect all other device interrupts to the HLIC, which are routed
-via the platform-level interrupt controller (PLIC).
-
-All RISC-V systems that conform to the supervisor ISA specification are
-required to have a HLIC with these three interrupt sources present. Since the
-interrupt map is defined by the ISA it's not listed in the HLIC's device tree
-entry, though external interrupt controllers (like the PLIC, for example) will
-need to define how their interrupts map to the relevant HLICs. This means
-a PLIC interrupt property will typically list the HLICs for all present HARTs
-in the system.
-
-Required properties:
-- compatible : "riscv,cpu-intc"
-- #interrupt-cells : should be <1>. The interrupt sources are defined by the
- RISC-V supervisor ISA manual, with only the following three interrupts being
- defined for supervisor mode:
- - Source 1 is the supervisor software interrupt, which can be sent by an SBI
- call and is reserved for use by software.
- - Source 5 is the supervisor timer interrupt, which can be configured by
- SBI calls and implements a one-shot timer.
- - Source 9 is the supervisor external interrupt, which chains to all other
- device interrupts.
-- interrupt-controller : Identifies the node as an interrupt controller
-
-Furthermore, this interrupt-controller MUST be embedded inside the cpu
-definition of the hart whose CSRs control these local interrupts.
-
-An example device tree entry for a HLIC is show below.
-
- cpu1: cpu@1 {
- compatible = "riscv";
- ...
- cpu1-intc: interrupt-controller {
- #interrupt-cells = <1>;
- compatible = "sifive,fu540-c000-cpu-intc", "riscv,cpu-intc";
- interrupt-controller;
- };
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.yaml
new file mode 100644
index 000000000000..83256cc0bd5c
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/riscv,cpu-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RISC-V Hart-Level Interrupt Controller (HLIC)
+
+description:
+ RISC-V cores include Control Status Registers (CSRs) which are local to
+ each CPU core (HART in RISC-V terminology) and can be read or written by
+ software. Some of these CSRs are used to control local interrupts connected
+ to the core. Every interrupt is ultimately routed through a hart's HLIC
+ before it interrupts that hart.
+
+ The RISC-V supervisor ISA manual specifies three interrupt sources that are
+ attached to every HLIC namely software interrupts, the timer interrupt, and
+ external interrupts. Software interrupts are used to send IPIs between
+ cores. The timer interrupt comes from an architecturally mandated real-
+ time timer that is controlled via Supervisor Binary Interface (SBI) calls
+ and CSR reads. External interrupts connect all other device interrupts to
+ the HLIC, which are routed via the platform-level interrupt controller
+ (PLIC).
+
+ All RISC-V systems that conform to the supervisor ISA specification are
+ required to have a HLIC with these three interrupt sources present. Since
+ the interrupt map is defined by the ISA it's not listed in the HLIC's device
+ tree entry, though external interrupt controllers (like the PLIC, for
+ example) will need to define how their interrupts map to the relevant HLICs.
+ This means a PLIC interrupt property will typically list the HLICs for all
+ present HARTs in the system.
+
+maintainers:
+ - Palmer Dabbelt <palmer@dabbelt.com>
+ - Paul Walmsley <paul.walmsley@sifive.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: andestech,cpu-intc
+ - const: riscv,cpu-intc
+ - const: riscv,cpu-intc
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+ description: |
+ The interrupt sources are defined by the RISC-V supervisor ISA manual,
+ with only the following three interrupts being defined for
+ supervisor mode:
+ - Source 1 is the supervisor software interrupt, which can be sent by
+ an SBI call and is reserved for use by software.
+ - Source 5 is the supervisor timer interrupt, which can be configured
+ by SBI calls and implements a one-shot timer.
+ - Source 9 is the supervisor external interrupt, which chains to all
+ other device interrupts.
+
+required:
+ - compatible
+ - '#interrupt-cells'
+ - interrupt-controller
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ #interrupt-cells = <1>;
+ compatible = "riscv,cpu-intc";
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,imsics.yaml b/Documentation/devicetree/bindings/interrupt-controller/riscv,imsics.yaml
new file mode 100644
index 000000000000..c23b5c09fdb9
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,imsics.yaml
@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/riscv,imsics.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RISC-V Incoming MSI Controller (IMSIC)
+
+maintainers:
+ - Anup Patel <anup@brainfault.org>
+
+description: |
+ The RISC-V advanced interrupt architecture (AIA) defines a per-CPU incoming
+ MSI controller (IMSIC) for handling MSIs in a RISC-V platform. The RISC-V
+ AIA specification can be found at https://github.com/riscv/riscv-aia.
+
+ The IMSIC is a per-CPU (or per-HART) device with separate interrupt file
+ for each privilege level (machine or supervisor). The configuration of
+ a IMSIC interrupt file is done using AIA CSRs and it also has a 4KB MMIO
+ space to receive MSIs from devices. Each IMSIC interrupt file supports a
+ fixed number of interrupt identities (to distinguish MSIs from devices)
+ which is same for given privilege level across CPUs (or HARTs).
+
+ The device tree of a RISC-V platform will have one IMSIC device tree node
+ for each privilege level (machine or supervisor) which collectively describe
+ IMSIC interrupt files at that privilege level across CPUs (or HARTs).
+
+ The arrangement of IMSIC interrupt files in MMIO space of a RISC-V platform
+ follows a particular scheme defined by the RISC-V AIA specification. A IMSIC
+ group is a set of IMSIC interrupt files co-located in MMIO space and we can
+ have multiple IMSIC groups (i.e. clusters, sockets, chiplets, etc) in a
+ RISC-V platform. The MSI target address of a IMSIC interrupt file at given
+ privilege level (machine or supervisor) encodes group index, HART index,
+ and guest index (shown below).
+
+ XLEN-1 > (HART Index MSB) 12 0
+ | | | |
+ -------------------------------------------------------------
+ |xxxxxx|Group Index|xxxxxxxxxxx|HART Index|Guest Index| 0 |
+ -------------------------------------------------------------
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+ - $ref: /schemas/interrupt-controller/msi-controller.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - qemu,imsics
+ - const: riscv,imsics
+
+ reg:
+ minItems: 1
+ maxItems: 16384
+ description:
+ Base address of each IMSIC group.
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 0
+
+ msi-controller: true
+
+ "#msi-cells":
+ const: 0
+
+ interrupts-extended:
+ minItems: 1
+ maxItems: 16384
+ description:
+ This property represents the set of CPUs (or HARTs) for which given
+ device tree node describes the IMSIC interrupt files. Each node pointed
+ to should be a riscv,cpu-intc node, which has a CPU node (i.e. RISC-V
+ HART) as parent.
+
+ riscv,num-ids:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 63
+ maximum: 2047
+ description:
+ Number of interrupt identities supported by IMSIC interrupt file.
+
+ riscv,num-guest-ids:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 63
+ maximum: 2047
+ description:
+ Number of interrupt identities are supported by IMSIC guest interrupt
+ file. When not specified it is assumed to be same as specified by the
+ riscv,num-ids property.
+
+ riscv,guest-index-bits:
+ minimum: 0
+ maximum: 7
+ default: 0
+ description:
+ Number of guest index bits in the MSI target address.
+
+ riscv,hart-index-bits:
+ minimum: 0
+ maximum: 15
+ description:
+ Number of HART index bits in the MSI target address. When not
+ specified it is calculated based on the interrupts-extended property.
+
+ riscv,group-index-bits:
+ minimum: 0
+ maximum: 7
+ default: 0
+ description:
+ Number of group index bits in the MSI target address.
+
+ riscv,group-index-shift:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 55
+ default: 24
+ description:
+ The least significant bit position of the group index bits in the
+ MSI target address.
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - msi-controller
+ - "#msi-cells"
+ - interrupts-extended
+ - riscv,num-ids
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ // Example 1 (Machine-level IMSIC files with just one group):
+
+ interrupt-controller@24000000 {
+ compatible = "qemu,imsics", "riscv,imsics";
+ interrupts-extended = <&cpu1_intc 11>,
+ <&cpu2_intc 11>,
+ <&cpu3_intc 11>,
+ <&cpu4_intc 11>;
+ reg = <0x24000000 0x4000>;
+ interrupt-controller;
+ #interrupt-cells = <0>;
+ msi-controller;
+ #msi-cells = <0>;
+ riscv,num-ids = <127>;
+ };
+
+ - |
+ // Example 2 (Supervisor-level IMSIC files with two groups):
+
+ interrupt-controller@28000000 {
+ compatible = "qemu,imsics", "riscv,imsics";
+ interrupts-extended = <&cpu1_intc 9>,
+ <&cpu2_intc 9>,
+ <&cpu3_intc 9>,
+ <&cpu4_intc 9>;
+ reg = <0x28000000 0x2000>, /* Group0 IMSICs */
+ <0x29000000 0x2000>; /* Group1 IMSICs */
+ interrupt-controller;
+ #interrupt-cells = <0>;
+ msi-controller;
+ #msi-cells = <0>;
+ riscv,num-ids = <127>;
+ riscv,group-index-bits = <1>;
+ riscv,group-index-shift = <24>;
+ };
+...
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/interrupt-controller/samsung,exynos4210-combiner.txt b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt
deleted file mode 100644
index 19af687858a1..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-* Samsung Exynos Interrupt Combiner Controller
-
-Samsung's Exynos4 architecture includes a interrupt combiner controller which
-can combine interrupt sources as a group and provide a single interrupt request
-for the group. The interrupt request from each group are connected to a parent
-interrupt controller, such as GIC in case of Exynos4210.
-
-The interrupt combiner controller consists of multiple combiners. Up to eight
-interrupt sources can be connected to a combiner. The combiner outputs one
-combined interrupt for its eight interrupt sources. The combined interrupt
-is usually connected to a parent interrupt controller.
-
-A single node in the device tree is used to describe the interrupt combiner
-controller module (which includes multiple combiners). A combiner in the
-interrupt controller module shares config/control registers with other
-combiners. For example, a 32-bit interrupt enable/disable config register
-can accommodate up to 4 interrupt combiners (with each combiner supporting
-up to 8 interrupt sources).
-
-Required properties:
-- compatible: should be "samsung,exynos4210-combiner".
-- interrupt-controller: Identifies the node as an interrupt controller.
-- #interrupt-cells: should be <2>. The meaning of the cells are
- * First Cell: Combiner Group Number.
- * Second Cell: Interrupt number within the group.
-- reg: Base address and size of interrupt combiner registers.
-- interrupts: The list of interrupts generated by the combiners which are then
- connected to a parent interrupt controller. The format of the interrupt
- specifier depends in the interrupt parent controller.
-
-Optional properties:
-- samsung,combiner-nr: The number of interrupt combiners supported. If this
- property is not specified, the default number of combiners is assumed
- to be 16.
-
-
-Example:
-
- The following is a an example from the Exynos4210 SoC dtsi file.
-
- combiner:interrupt-controller@10440000 {
- compatible = "samsung,exynos4210-combiner";
- interrupt-controller;
- #interrupt-cells = <2>;
- reg = <0x10440000 0x1000>;
- interrupts = <0 0 0>, <0 1 0>, <0 2 0>, <0 3 0>,
- <0 4 0>, <0 5 0>, <0 6 0>, <0 7 0>,
- <0 8 0>, <0 9 0>, <0 10 0>, <0 11 0>,
- <0 12 0>, <0 13 0>, <0 14 0>, <0 15 0>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml
new file mode 100644
index 000000000000..72456a07dac9
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/samsung,exynos4210-combiner.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos SoC Interrupt Combiner Controller
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ Samsung's Exynos4 architecture includes a interrupt combiner controller which
+ can combine interrupt sources as a group and provide a single interrupt
+ request for the group. The interrupt request from each group are connected to
+ a parent interrupt controller, such as GIC in case of Exynos4210.
+
+ The interrupt combiner controller consists of multiple combiners. Up to eight
+ interrupt sources can be connected to a combiner. The combiner outputs one
+ combined interrupt for its eight interrupt sources. The combined interrupt is
+ usually connected to a parent interrupt controller.
+
+ A single node in the device tree is used to describe the interrupt combiner
+ controller module (which includes multiple combiners). A combiner in the
+ interrupt controller module shares config/control registers with other
+ combiners. For example, a 32-bit interrupt enable/disable config register can
+ accommodate up to 4 interrupt combiners (with each combiner supporting up to
+ 8 interrupt sources).
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: samsung,exynos4210-combiner
+
+ interrupt-controller: true
+
+ interrupts:
+ minItems: 8
+ maxItems: 32
+
+ "#interrupt-cells":
+ description: |
+ The meaning of the cells are:
+ * First Cell: Combiner Group Number.
+ * Second Cell: Interrupt number within the group.
+ const: 2
+
+ reg:
+ maxItems: 1
+
+ samsung,combiner-nr:
+ description: |
+ The number of interrupt combiners supported. Should match number
+ of interrupts set in "interrupts" property.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 8
+ maximum: 32
+ default: 16
+
+required:
+ - compatible
+ - interrupt-controller
+ - interrupts
+ - "#interrupt-cells"
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@10440000 {
+ compatible = "samsung,exynos4210-combiner";
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ reg = <0x10440000 0x1000>;
+ interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt
deleted file mode 100644
index c54c5a9a2a90..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/samsung,s3c24xx-irq.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-Samsung S3C24XX Interrupt Controllers
-
-The S3C24XX SoCs contain a custom set of interrupt controllers providing a
-varying number of interrupt sources. The set consists of a main- and sub-
-controller and on newer SoCs even a second main controller.
-
-Required properties:
-- compatible: Compatible property value should be "samsung,s3c2410-irq"
- for machines before s3c2416 and "samsung,s3c2416-irq" for s3c2416 and later.
-
-- reg: Physical base address of the controller and length of memory mapped
- region.
-
-- interrupt-controller : Identifies the node as an interrupt controller
-
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value shall be 4 and interrupt descriptor shall
- have the following format:
- <ctrl_num parent_irq ctrl_irq type>
-
- ctrl_num contains the controller to use:
- - 0 ... main controller
- - 1 ... sub controller
- - 2 ... second main controller on s3c2416 and s3c2450
- parent_irq contains the parent bit in the main controller and will be
- ignored in main controllers
- ctrl_irq contains the interrupt bit of the controller
- type contains the trigger type to use
-
-Example:
-
- interrupt-controller@4a000000 {
- compatible = "samsung,s3c2410-irq";
- reg = <0x4a000000 0x100>;
- interrupt-controller;
- #interrupt-cells=<4>;
- };
-
- [...]
-
- serial@50000000 {
- compatible = "samsung,s3c2410-uart";
- reg = <0x50000000 0x4000>;
- interrupt-parent = <&subintc>;
- interrupts = <1 28 0 4>, <1 28 1 4>;
- };
-
- rtc@57000000 {
- compatible = "samsung,s3c2410-rtc";
- reg = <0x57000000 0x100>;
- interrupt-parent = <&intc>;
- interrupts = <0 30 0 3>, <0 8 0 3>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml
index 08d5a57ce00f..388fc2c620c0 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml
@@ -26,27 +26,66 @@ description:
with priority below this threshold will not cause the PLIC to raise its
interrupt line leading to the context.
- While the PLIC supports both edge-triggered and level-triggered interrupts,
- interrupt handlers are oblivious to this distinction and therefore it is not
- specified in the PLIC device-tree binding.
+ The PLIC supports both edge-triggered and level-triggered interrupts. For
+ edge-triggered interrupts, the RISC-V PLIC spec allows two responses to edges
+ seen while an interrupt handler is active; the PLIC may either queue them or
+ ignore them. In the first case, handlers are oblivious to the trigger type, so
+ it is not included in the interrupt specifier. In the second case, software
+ needs to know the trigger type, so it can reorder the interrupt flow to avoid
+ missing interrupts. This special handling is needed by at least the Renesas
+ RZ/Five SoC (AX45MP AndesCore with a NCEPLIC100) and the T-HEAD C900 PLIC.
While the RISC-V ISA doesn't specify a memory layout for the PLIC, the
"sifive,plic-1.0.0" device is a concrete implementation of the PLIC that
contains a specific memory layout, which is documented in chapter 8 of the
SiFive U5 Coreplex Series Manual <https://static.dev.sifive.com/U54-MC-RVCoreIP.pdf>.
+ The thead,c900-plic is different from sifive,plic-1.0.0 in opensbi, the
+ T-HEAD PLIC implementation requires setting a delegation bit to allow access
+ from S-mode. So add thead,c900-plic to distinguish them.
+
maintainers:
- - Sagar Kadam <sagar.kadam@sifive.com>
- Paul Walmsley <paul.walmsley@sifive.com>
- Palmer Dabbelt <palmer@dabbelt.com>
properties:
compatible:
- items:
- - enum:
- - sifive,fu540-c000-plic
- - canaan,k210-plic
- - const: sifive,plic-1.0.0
+ oneOf:
+ - items:
+ - enum:
+ - andestech,qilai-plic
+ - renesas,r9a07g043-plic
+ - const: andestech,nceplic100
+ - items:
+ - enum:
+ - anlogic,dr1v90-plic
+ - canaan,k210-plic
+ - eswin,eic7700-plic
+ - microchip,pic64gx-plic
+ - sifive,fu540-c000-plic
+ - spacemit,k1-plic
+ - starfive,jh7100-plic
+ - starfive,jh7110-plic
+ - tenstorrent,blackhole-plic
+ - const: sifive,plic-1.0.0
+ - items:
+ - enum:
+ - allwinner,sun20i-d1-plic
+ - sophgo,cv1800b-plic
+ - sophgo,cv1812h-plic
+ - sophgo,sg2002-plic
+ - sophgo,sg2042-plic
+ - sophgo,sg2044-plic
+ - thead,th1520-plic
+ - const: thead,c900-plic
+ - items:
+ - const: ultrarisc,dp1000-plic
+ - const: ultrarisc,cp100-plic
+ - items:
+ - const: sifive,plic-1.0.0
+ - const: riscv,plic0
+ deprecated: true
+ description: For the QEMU virt machine only
reg:
maxItems: 1
@@ -54,23 +93,29 @@ properties:
'#address-cells':
const: 0
- '#interrupt-cells':
- const: 1
+ '#interrupt-cells': true
interrupt-controller: true
interrupts-extended:
minItems: 1
+ maxItems: 15872
description:
Specifies which contexts are connected to the PLIC, with "-1" specifying
that a context is not present. Each node pointed to should be a
riscv,cpu-intc node, which has a riscv node as parent.
riscv,ndev:
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
description:
Specifies how many external interrupts are supported by this controller.
+ clocks: true
+
+ power-domains: true
+
+ resets: true
+
required:
- compatible
- '#address-cells'
@@ -80,6 +125,47 @@ required:
- interrupts-extended
- riscv,ndev
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - andestech,nceplic100
+ - thead,c900-plic
+
+ then:
+ properties:
+ '#interrupt-cells':
+ const: 2
+
+ else:
+ properties:
+ '#interrupt-cells':
+ const: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a07g043-plic
+
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ required:
+ - clocks
+ - power-domains
+ - resets
+
additionalProperties: false
examples:
@@ -89,12 +175,11 @@ examples:
#interrupt-cells = <1>;
compatible = "sifive,fu540-c000-plic", "sifive,plic-1.0.0";
interrupt-controller;
- interrupts-extended = <
- &cpu0_intc 11
- &cpu1_intc 11 &cpu1_intc 9
- &cpu2_intc 11 &cpu2_intc 9
- &cpu3_intc 11 &cpu3_intc 9
- &cpu4_intc 11 &cpu4_intc 9>;
+ interrupts-extended = <&cpu0_intc 11>,
+ <&cpu1_intc 11>, <&cpu1_intc 9>,
+ <&cpu2_intc 11>, <&cpu2_intc 9>,
+ <&cpu3_intc 11>, <&cpu3_intc 9>,
+ <&cpu4_intc 11>, <&cpu4_intc 9>;
reg = <0xc000000 0x4000000>;
riscv,ndev = <10>;
};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.txt
deleted file mode 100644
index 9a5d562435ea..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-* ARC700 incore Interrupt Controller
-
- The core interrupt controller provides 32 prioritised interrupts (2 levels)
- to ARC700 core.
-
-Properties:
-
-- compatible: "snps,arc700-intc"
-- interrupt-controller: This is an interrupt controller.
-- #interrupt-cells: Must be <1>.
-
- Single Cell "interrupts" property of a device specifies the IRQ number
- between 0 to 31
-
- intc accessed via the special ARC AUX register interface, hence "reg" property
- is not specified.
-
-Example:
-
- intc: interrupt-controller {
- compatible = "snps,arc700-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.yaml
new file mode 100644
index 000000000000..000a734d997c
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/snps,arc700-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARC700 incore Interrupt Controller
+
+maintainers:
+ - Vineet Gupta <vgupta@kernel.org>
+
+description: >
+ The core interrupt controller provides 32 prioritized interrupts (2 levels)
+ to ARC700 core.
+
+ intc accessed via the special ARC AUX register interface, hence "reg" property
+ is not specified.
+
+properties:
+ compatible:
+ const: snps,arc700-intc
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ description: An interrupt number 0-31
+ const: 1
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "snps,arc700-intc";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt
deleted file mode 100644
index a5c1db95b3ec..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt
+++ /dev/null
@@ -1,46 +0,0 @@
-* ARC-HS Interrupt Distribution Unit
-
- This optional 2nd level interrupt controller can be used in SMP configurations
- for dynamic IRQ routing, load balancing of common/external IRQs towards core
- intc.
-
-Properties:
-
-- compatible: "snps,archs-idu-intc"
-- interrupt-controller: This is an interrupt controller.
-- #interrupt-cells: Must be <1> or <2>.
-
- Value of the first cell specifies the "common" IRQ from peripheral to IDU.
- Number N of the particular interrupt line of IDU corresponds to the line N+24
- of the core interrupt controller.
-
- The (optional) second cell specifies any of the following flags:
- - bits[3:0] trigger type and level flags
- 1 = low-to-high edge triggered
- 2 = NOT SUPPORTED (high-to-low edge triggered)
- 4 = active high level-sensitive <<< DEFAULT
- 8 = NOT SUPPORTED (active low level-sensitive)
- When no second cell is specified, the interrupt is assumed to be level
- sensitive.
-
- The interrupt controller is accessed via the special ARC AUX register
- interface, hence "reg" property is not specified.
-
-Example:
- core_intc: core-interrupt-controller {
- compatible = "snps,archs-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- };
-
- idu_intc: idu-interrupt-controller {
- compatible = "snps,archs-idu-intc";
- interrupt-controller;
- interrupt-parent = <&core_intc>;
- #interrupt-cells = <1>;
- };
-
- some_device: serial@c0fc1000 {
- interrupt-parent = <&idu_intc>;
- interrupts = <0>; /* upstream idu IRQ #24 */
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.yaml
new file mode 100644
index 000000000000..286a964f23e1
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/snps,archs-idu-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARC-HS Interrupt Distribution Unit
+
+maintainers:
+ - Vineet Gupta <vgupta@kernel.org>
+
+description: >
+ ARC-HS Interrupt Distribution Unit is an optional 2nd level interrupt
+ controller which can be used in SMP configurations for dynamic IRQ routing,
+ load balancing of common/external IRQs towards core intc.
+
+ The interrupt controller is accessed via the special ARC AUX register
+ interface, hence "reg" property is not specified.
+
+properties:
+ compatible:
+ const: snps,archs-idu-intc
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ description: |
+ Number of interrupt specifier cells:
+ - 1: only a common IRQ is specified.
+ - 2: a second cell encodes trigger type and level flags:
+ 1 = low-to-high edge triggered
+ 4 = active high level-sensitive (default)
+ enum: [1, 2]
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "snps,archs-idu-intc";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.txt
deleted file mode 100644
index 69f326d6a5ad..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-* ARC-HS incore Interrupt Controller (Provided by cores implementing ARCv2 ISA)
-
-Properties:
-
-- compatible: "snps,archs-intc"
-- interrupt-controller: This is an interrupt controller.
-- #interrupt-cells: Must be <1>.
-
- Single Cell "interrupts" property of a device specifies the IRQ number
- between 16 to 256
-
- intc accessed via the special ARC AUX register interface, hence "reg" property
- is not specified.
-
-Example:
-
- intc: interrupt-controller {
- compatible = "snps,archs-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- interrupts = <16 17 18 19 20 21 22 23 24 25>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.yaml
new file mode 100644
index 000000000000..9d248ef7fe3d
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/snps,archs-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARC-HS incore Interrupt Controller
+
+maintainers:
+ - Vineet Gupta <vgupta@kernel.org>
+
+description:
+ ARC-HS incore Interrupt Controller provided by cores implementing ARCv2 ISA.
+ intc accessed via the special ARC AUX register interface, hence "reg" property
+ is not specified.
+
+properties:
+ compatible:
+ const: snps,archs-intc
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupts:
+ description: List of IRQ numbers between 16 and 256
+ items:
+ items:
+ - minimum: 16
+ maximum: 256
+
+required:
+ - compatible
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller {
+ compatible = "snps,archs-intc";
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <16>, <17>, <18>, <19>, <20>, <21>, <22>, <23>, <24>, <25>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.txt
deleted file mode 100644
index 2db59df9408f..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-Synopsys DesignWare APB interrupt controller (dw_apb_ictl)
-
-Synopsys DesignWare provides interrupt controller IP for APB known as
-dw_apb_ictl. The IP is used as secondary interrupt controller in some SoCs with
-APB bus, e.g. Marvell Armada 1500. It can also be used as primary interrupt
-controller in some SoCs, e.g. Hisilicon SD5203.
-
-Required properties:
-- compatible: shall be "snps,dw-apb-ictl"
-- reg: physical base address of the controller and length of memory mapped
- region starting with ENABLE_LOW register
-- interrupt-controller: identifies the node as an interrupt controller
-- #interrupt-cells: number of cells to encode an interrupt-specifier, shall be 1
-
-Additional required property when it's used as secondary interrupt controller:
-- interrupts: interrupt reference to primary interrupt controller
-
-The interrupt sources map to the corresponding bits in the interrupt
-registers, i.e.
-- 0 maps to bit 0 of low interrupts,
-- 1 maps to bit 1 of low interrupts,
-- 32 maps to bit 0 of high interrupts,
-- 33 maps to bit 1 of high interrupts,
-- (optional) fast interrupts start at 64.
-
-Example:
- /* dw_apb_ictl is used as secondary interrupt controller */
- aic: interrupt-controller@3000 {
- compatible = "snps,dw-apb-ictl";
- reg = <0x3000 0xc00>;
- interrupt-controller;
- #interrupt-cells = <1>;
- interrupt-parent = <&gic>;
- interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- /* dw_apb_ictl is used as primary interrupt controller */
- vic: interrupt-controller@10130000 {
- compatible = "snps,dw-apb-ictl";
- reg = <0x10130000 0x1000>;
- interrupt-controller;
- #interrupt-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.yaml b/Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.yaml
new file mode 100644
index 000000000000..6b59b600a037
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/snps,dw-apb-ictl.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/snps,dw-apb-ictl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synopsys DesignWare APB interrupt controller
+
+maintainers:
+ - Sebastian Hesselbarth <sebastian.hesselbarth@gmail.com>
+ - Zhen Lei <thunder.leizhen@huawei.com>
+
+description:
+ Synopsys DesignWare provides interrupt controller IP for APB known as
+ dw_apb_ictl. The IP is used as secondary interrupt controller in some SoCs
+ with APB bus, e.g. Marvell Armada 1500. It can also be used as primary
+ interrupt controller in some SoCs, e.g. Hisilicon SD5203.
+
+properties:
+ compatible:
+ const: snps,dw-apb-ictl
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupts:
+ maxItems: 1
+ description: >
+ Interrupt input connected to the primary interrupt controller when used
+ as a secondary controller. The interrupt specifier maps to bits in the
+ low and high interrupt registers (0⇒bit 0 low, 1⇒bit 1 low, 32⇒bit 0 high,
+ 33⇒bit 1 high, fast interrupts start at 64).
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@3000 {
+ compatible = "snps,dw-apb-ictl";
+ reg = <0x3000 0xc00>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ - |
+ interrupt-controller@10130000 {
+ compatible = "snps,dw-apb-ictl";
+ reg = <0x10130000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.txt b/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.txt
deleted file mode 100644
index dac0846fe789..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-Socionext SynQuacer External Interrupt Unit (EXIU)
-
-The Socionext Synquacer SoC has an external interrupt unit (EXIU)
-that forwards a block of 32 configurable input lines to 32 adjacent
-level-high type GICv3 SPIs.
-
-Required properties:
-
-- compatible : Should be "socionext,synquacer-exiu".
-- reg : Specifies base physical address and size of the
- control registers.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value must be 3.
-- socionext,spi-base : The SPI number of the first SPI of the 32 adjacent
- ones the EXIU forwards its interrups to.
-
-Notes:
-
-- Only SPIs can use the EXIU as an interrupt parent.
-
-Example:
-
- exiu: interrupt-controller@510c0000 {
- compatible = "socionext,synquacer-exiu";
- reg = <0x0 0x510c0000 0x0 0x20>;
- interrupt-controller;
- interrupt-parent = <&gic>;
- #interrupt-cells = <3>;
- socionext,spi-base = <112>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml b/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml
new file mode 100644
index 000000000000..92cec2255cca
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/socionext,synquacer-exiu.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/socionext,synquacer-exiu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Socionext SynQuacer External Interrupt Unit (EXIU)
+
+maintainers:
+ - Ard Biesheuvel <ardb@kernel.org>
+
+description: |+
+ The Socionext SynQuacer SoC has an external interrupt unit (EXIU)
+ that forwards a block of 32 configurable input lines to 32 adjacent
+ level-high type GICv3 SPIs.
+
+properties:
+ compatible:
+ const: socionext,synquacer-exiu
+
+ reg:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 3
+
+ interrupt-controller: true
+
+ socionext,spi-base:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The SPI number of the first SPI of the 32 adjacent ones the
+ EXIU forwards its interrupts to.
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupt-controller
+ - socionext,spi-base
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ interrupt-controller@510c0000 {
+ compatible = "socionext,synquacer-exiu";
+ reg = <0x510c0000 0x20>;
+ interrupt-controller;
+ interrupt-parent = <&gic>;
+ #interrupt-cells = <3>;
+ socionext,spi-base = <112>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml b/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml
index f89ebde76dab..de7c5e59bae1 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/socionext,uniphier-aidet.yaml
@@ -30,6 +30,7 @@ properties:
- socionext,uniphier-ld11-aidet
- socionext,uniphier-ld20-aidet
- socionext,uniphier-pxs3-aidet
+ - socionext,uniphier-nx1-aidet
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/interrupt-controller/sophgo,sg2042-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/sophgo,sg2042-msi.yaml
new file mode 100644
index 000000000000..f6b8b1d92f79
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/sophgo,sg2042-msi.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/sophgo,sg2042-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sophgo SG2042 MSI Controller
+
+maintainers:
+ - Chen Wang <unicorn_wang@outlook.com>
+
+description:
+ This interrupt controller is in Sophgo SG2042 for transforming interrupts from
+ PCIe MSI to PLIC interrupts.
+
+allOf:
+ - $ref: /schemas/interrupt-controller/msi-controller.yaml#
+
+properties:
+ compatible:
+ enum:
+ - sophgo,sg2042-msi
+ - sophgo,sg2044-msi
+
+ reg:
+ items:
+ - description: clear register
+ - description: msi doorbell address
+
+ reg-names:
+ items:
+ - const: clr
+ - const: doorbell
+
+ msi-controller: true
+
+ msi-ranges:
+ maxItems: 1
+
+ "#msi-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - msi-controller
+ - msi-ranges
+ - "#msi-cells"
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ msi-controller@30000000 {
+ compatible = "sophgo,sg2042-msi";
+ reg = <0x30000000 0x4>, <0x30000008 0x4>;
+ reg-names = "clr", "doorbell";
+ msi-controller;
+ #msi-cells = <0>;
+ msi-ranges = <&plic 64 IRQ_TYPE_LEVEL_HIGH 32>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,spear300-shirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/st,spear300-shirq.yaml
new file mode 100644
index 000000000000..27d36173366a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/st,spear300-shirq.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/st,spear300-shirq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SPEAr3xx Shared IRQ controller
+
+maintainers:
+ - Viresh Kumar <vireshk@kernel.org>
+ - Shiraz Hashim <shiraz.linux.kernel@gmail.com>
+
+description: |
+ SPEAr3xx architecture includes shared/multiplexed irqs for certain set of
+ devices. The multiplexor provides a single interrupt to parent interrupt
+ controller (VIC) on behalf of a group of devices.
+
+ There can be multiple groups available on SPEAr3xx variants but not exceeding
+ 4. The number of devices in a group can differ, further they may share same
+ set of status/mask registers spanning across different bit masks. Also in some
+ cases the group may not have enable or other registers. This makes software
+ little complex.
+
+ A single node in the device tree is used to describe the shared interrupt
+ multiplexer (one node for all groups). A group in the interrupt controller
+ shares config/control registers with other groups. For example, a 32-bit
+ interrupt enable/disable config register can accommodate up to 4 interrupt
+ groups.
+
+properties:
+ compatible:
+ enum:
+ - st,spear300-shirq
+ - st,spear310-shirq
+ - st,spear320-shirq
+
+ reg:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupt-controller: true
+
+ interrupts:
+ description: Interrupt specifier array for SHIRQ groups
+ minItems: 1
+ maxItems: 4
+
+required:
+ - compatible
+ - reg
+ - '#interrupt-cells'
+ - interrupt-controller
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@b3000000 {
+ compatible = "st,spear320-shirq";
+ reg = <0xb3000000 0x1000>;
+ interrupts = <28 29 30 1>;
+ #interrupt-cells = <1>;
+ interrupt-controller;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt b/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt
deleted file mode 100644
index a407c499b3cc..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-* SPEAr Shared IRQ layer (shirq)
-
-SPEAr3xx architecture includes shared/multiplexed irqs for certain set
-of devices. The multiplexor provides a single interrupt to parent
-interrupt controller (VIC) on behalf of a group of devices.
-
-There can be multiple groups available on SPEAr3xx variants but not
-exceeding 4. The number of devices in a group can differ, further they
-may share same set of status/mask registers spanning across different
-bit masks. Also in some cases the group may not have enable or other
-registers. This makes software little complex.
-
-A single node in the device tree is used to describe the shared
-interrupt multiplexor (one node for all groups). A group in the
-interrupt controller shares config/control registers with other groups.
-For example, a 32-bit interrupt enable/disable config register can
-accommodate up to 4 interrupt groups.
-
-Required properties:
- - compatible: should be, either of
- - "st,spear300-shirq"
- - "st,spear310-shirq"
- - "st,spear320-shirq"
- - interrupt-controller: Identifies the node as an interrupt controller.
- - #interrupt-cells: should be <1> which basically contains the offset
- (starting from 0) of interrupts for all the groups.
- - reg: Base address and size of shirq registers.
- - interrupts: The list of interrupts generated by the groups which are
- then connected to a parent interrupt controller. Each group is
- associated with one of the interrupts, hence number of interrupts (to
- parent) is equal to number of groups. The format of the interrupt
- specifier depends in the interrupt parent controller.
-
-Example:
-
-The following is an example from the SPEAr320 SoC dtsi file.
-
-shirq: interrupt-controller@b3000000 {
- compatible = "st,spear320-shirq";
- reg = <0xb3000000 0x1000>;
- interrupts = <28 29 30 1>;
- #interrupt-cells = <1>;
- interrupt-controller;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt b/Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt
deleted file mode 100644
index ced6014061a3..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/st,sti-irq-syscfg.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-STMicroelectronics STi System Configuration Controlled IRQs
------------------------------------------------------------
-
-On STi based systems; External, CTI (Core Sight), PMU (Performance Management),
-and PL310 L2 Cache IRQs are controlled using System Configuration registers.
-This driver is used to unmask them prior to use.
-
-Required properties:
-- compatible : Should be set to one of:
- "st,stih415-irq-syscfg"
- "st,stih416-irq-syscfg"
- "st,stih407-irq-syscfg"
- "st,stid127-irq-syscfg"
-- st,syscfg : Phandle to Cortex-A9 IRQ system config registers
-- st,irq-device : Array of IRQs to enable - should be 2 in length
-- st,fiq-device : Array of FIQs to enable - should be 2 in length
-
-Optional properties:
-- st,invert-ext : External IRQs can be inverted at will. This property inverts
- these IRQs using bitwise logic. A number of defines have been
- provided for convenience:
- ST_IRQ_SYSCFG_EXT_1_INV
- ST_IRQ_SYSCFG_EXT_2_INV
- ST_IRQ_SYSCFG_EXT_3_INV
-Example:
-
-irq-syscfg {
- compatible = "st,stih416-irq-syscfg";
- st,syscfg = <&syscfg_cpu>;
- st,irq-device = <ST_IRQ_SYSCFG_PMU_0>,
- <ST_IRQ_SYSCFG_PMU_1>;
- st,fiq-device = <ST_IRQ_SYSCFG_DISABLED>,
- <ST_IRQ_SYSCFG_DISABLED>;
- st,invert-ext = <(ST_IRQ_SYSCFG_EXT_1_INV | ST_IRQ_SYSCFG_EXT_3_INV)>;
-};
diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml b/Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml
new file mode 100644
index 000000000000..e44e4e5708a7
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/st,stih407-irq-syscfg.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/st,stih407-irq-syscfg.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STi System Configuration Controlled IRQs
+
+maintainers:
+ - Patrice Chotard <patrice.chotard@foss.st.com>
+
+description:
+ On STi based systems; External, CTI (Core Sight), PMU (Performance
+ Management), and PL310 L2 Cache IRQs are controlled using System
+ Configuration registers. This device is used to unmask them prior to use.
+
+properties:
+ compatible:
+ const: st,stih407-irq-syscfg
+
+ st,syscfg:
+ description: Phandle to Cortex-A9 IRQ system config registers
+ $ref: /schemas/types.yaml#/definitions/phandle
+
+ st,irq-device:
+ description: Array of IRQs to enable.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - description: Enable the IRQ of the channel one.
+ - description: Enable the IRQ of the channel two.
+
+ st,fiq-device:
+ description: Array of FIQs to enable.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - description: Enable the IRQ of the channel one.
+ - description: Enable the IRQ of the channel two.
+
+ st,invert-ext:
+ description: External IRQs can be inverted at will. This property inverts
+ these three IRQs using bitwise logic, each one being encoded respectively
+ on the first, second and fourth bit.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 1, 2, 3, 4, 5, 6 ]
+
+required:
+ - compatible
+ - st,syscfg
+ - st,irq-device
+ - st,fiq-device
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq-st.h>
+ irq-syscfg {
+ compatible = "st,stih407-irq-syscfg";
+ st,syscfg = <&syscfg_cpu>;
+ st,irq-device = <ST_IRQ_SYSCFG_PMU_0>,
+ <ST_IRQ_SYSCFG_PMU_1>;
+ st,fiq-device = <ST_IRQ_SYSCFG_DISABLED>,
+ <ST_IRQ_SYSCFG_DISABLED>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml
index 6d3e68eb2e8b..9967e57b449b 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.yaml
@@ -4,11 +4,11 @@
$id: http://devicetree.org/schemas/interrupt-controller/st,stm32-exti.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STM32 External Interrupt Controller Device Tree Bindings
+title: STM32 External Interrupt Controller
maintainers:
- - Alexandre Torgue <alexandre.torgue@st.com>
- - Ludovic Barre <ludovic.barre@st.com>
+ - Alexandre Torgue <alexandre.torgue@foss.st.com>
+ - Ludovic Barre <ludovic.barre@foss.st.com>
properties:
compatible:
@@ -20,6 +20,7 @@ properties:
- items:
- enum:
- st,stm32mp1-exti
+ - st,stm32mp13-exti
- const: syscon
"#interrupt-cells":
@@ -88,8 +89,23 @@ examples:
reg = <0x5000d000 0x400>;
};
+ - |
//Example 2
- exti2: interrupt-controller@40013c00 {
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ exti2: interrupt-controller@5000d000 {
+ compatible = "st,stm32mp1-exti", "syscon";
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ reg = <0x5000d000 0x400>;
+ interrupts-extended =
+ <&intc GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>,
+ <0>,
+ <&intc GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ - |
+ //Example 3
+ exti3: interrupt-controller@40013c00 {
compatible = "st,stm32-exti";
interrupt-controller;
#interrupt-cells = <2>;
diff --git a/Documentation/devicetree/bindings/interrupt-controller/starfive,jh8100-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/starfive,jh8100-intc.yaml
new file mode 100644
index 000000000000..ada5788602d6
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/starfive,jh8100-intc.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/starfive,jh8100-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: StarFive External Interrupt Controller
+
+description:
+ StarFive SoC JH8100 contain a external interrupt controller. It can be used
+ to handle high-level input interrupt signals. It also send the output
+ interrupt signal to RISC-V PLIC.
+
+maintainers:
+ - Changhuang Liang <changhuang.liang@starfivetech.com>
+
+properties:
+ compatible:
+ const: starfive,jh8100-intc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: APB clock for the interrupt controller
+ maxItems: 1
+
+ resets:
+ description: APB reset for the interrupt controller
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - resets
+ - interrupts
+ - interrupt-controller
+ - "#interrupt-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@12260000 {
+ compatible = "starfive,jh8100-intc";
+ reg = <0x12260000 0x10000>;
+ clocks = <&syscrg_ne 76>;
+ resets = <&syscrg_ne 13>;
+ interrupts = <45>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml
new file mode 100644
index 000000000000..bd0021dbab0b
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/sunplus,sp7021-intc.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) Sunplus Co., Ltd. 2021
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/sunplus,sp7021-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sunplus SP7021 SoC Interrupt Controller
+
+maintainers:
+ - Qin Jian <qinjian@cqplus1.com>
+
+properties:
+ compatible:
+ items:
+ - const: sunplus,sp7021-intc
+
+ reg:
+ maxItems: 2
+ description:
+ Specifies base physical address(s) and size of the controller regs.
+ The 1st region include type/polarity/priority/mask regs.
+ The 2nd region include clear/masked_ext0/masked_ext1/group regs.
+
+ interrupt-controller: true
+
+ "#interrupt-cells":
+ const: 2
+ description:
+ The first cell is the IRQ number, the second cell is the trigger
+ type as defined in interrupt.txt in this directory.
+
+ interrupts:
+ maxItems: 2
+ description:
+ EXT_INT0 & EXT_INT1, 2 interrupts references to primary interrupt
+ controller.
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - "#interrupt-cells"
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ intc: interrupt-controller@9c000780 {
+ compatible = "sunplus,sp7021-intc";
+ reg = <0x9c000780 0x80>, <0x9c000a80 0x80>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&gic>;
+ interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, /* EXT_INT0 */
+ <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>; /* EXT_INT1 */
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800-irqc.yaml
new file mode 100644
index 000000000000..f1a15d725cd6
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800-irqc.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/technologic,ts4800-irqc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TS-4800 FPGA Interrupt Controller
+
+maintainers:
+ - Damien Riegel <damien.riegel@savoirfairelinux.com>
+
+description:
+ TS-4800 FPGA has an internal interrupt controller. When one of the interrupts
+ is triggered, the SoC is notified, usually using a GPIO as parent interrupt
+ source.
+
+properties:
+ compatible:
+ const: technologic,ts4800-irqc
+
+ reg:
+ maxItems: 1
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupt-controller: true
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@1000 {
+ compatible = "technologic,ts4800-irqc";
+ reg = <0x1000 0x80>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ interrupts = <10>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800.txt b/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800.txt
deleted file mode 100644
index 341ae5909333..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-TS-4800 FPGA interrupt controller
-
-TS-4800 FPGA has an internal interrupt controller. When one of the
-interrupts is triggered, the SoC is notified, usually using a GPIO as
-parent interrupt source.
-
-Required properties:
-- compatible: should be "technologic,ts4800-irqc"
-- interrupt-controller: identifies the node as an interrupt controller
-- reg: physical base address of the controller and length of memory mapped
- region
-- #interrupt-cells: specifies the number of cells needed to encode an interrupt
- source, should be 1.
-- interrupts: specifies the interrupt line in the interrupt-parent controller
diff --git a/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml
new file mode 100644
index 000000000000..62fd220e126e
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/thead,c900-aclint-mswi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ACLINT Machine-level Software Interrupt Device
+
+maintainers:
+ - Inochi Amaoto <inochiama@outlook.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - sophgo,sg2042-aclint-mswi
+ - sophgo,sg2044-aclint-mswi
+ - const: thead,c900-aclint-mswi
+ - items:
+ - enum:
+ - anlogic,dr1v90-aclint-mswi
+ - const: nuclei,ux900-aclint-mswi
+
+ reg:
+ maxItems: 1
+
+ interrupts-extended:
+ minItems: 1
+ maxItems: 4095
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts-extended
+
+examples:
+ - |
+ interrupt-controller@94000000 {
+ compatible = "sophgo,sg2042-aclint-mswi", "thead,c900-aclint-mswi";
+ interrupts-extended = <&cpu1intc 3>,
+ <&cpu2intc 3>,
+ <&cpu3intc 3>,
+ <&cpu4intc 3>;
+ reg = <0x94000000 0x00010000>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-sswi.yaml b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-sswi.yaml
new file mode 100644
index 000000000000..d02c6886283a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-sswi.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/thead,c900-aclint-sswi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ACLINT Supervisor-level Software Interrupt Device
+
+maintainers:
+ - Inochi Amaoto <inochiama@outlook.com>
+
+description:
+ The SSWI device is a part of the ACLINT device. It provides
+ supervisor-level IPI functionality for a set of HARTs on a supported
+ platforms. It provides a register to set an IPI (SETSSIP) for each
+ HART connected to the SSWI device. See draft specification
+ https://github.com/riscvarchive/riscv-aclint
+
+ Following variants of the SSWI ACLINT supported, using dedicated
+ compatible string
+ - THEAD C900
+ - MIPS P8700
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - sophgo,sg2044-aclint-sswi
+ - const: thead,c900-aclint-sswi
+ - items:
+ - const: mips,p8700-aclint-sswi
+ - items:
+ - enum:
+ - anlogic,dr1v90-aclint-sswi
+ - const: nuclei,ux900-aclint-sswi
+
+ reg:
+ maxItems: 1
+
+ "#interrupt-cells":
+ const: 0
+
+ interrupt-controller: true
+
+ interrupts-extended:
+ minItems: 1
+ maxItems: 4095
+
+ riscv,hart-indexes:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 4095
+ description:
+ A list of hart indexes that APLIC should use to address each hart
+ that is mentioned in the "interrupts-extended"
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - "#interrupt-cells"
+ - interrupt-controller
+ - interrupts-extended
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mips,p8700-aclint-sswi
+ then:
+ required:
+ - riscv,hart-indexes
+ else:
+ properties:
+ riscv,hart-indexes: false
+
+examples:
+ - |
+ //Example 1
+ interrupt-controller@94000000 {
+ compatible = "sophgo,sg2044-aclint-sswi", "thead,c900-aclint-sswi";
+ reg = <0x94000000 0x00004000>;
+ #interrupt-cells = <0>;
+ interrupt-controller;
+ interrupts-extended = <&cpu1intc 1>,
+ <&cpu2intc 1>,
+ <&cpu3intc 1>,
+ <&cpu4intc 1>;
+ };
+
+ - |
+ //Example 2
+ interrupt-controller@94000000 {
+ compatible = "mips,p8700-aclint-sswi";
+ reg = <0x94000000 0x00004000>;
+ #interrupt-cells = <0>;
+ interrupt-controller;
+ interrupts-extended = <&cpu1intc 1>,
+ <&cpu2intc 1>,
+ <&cpu3intc 1>,
+ <&cpu4intc 1>;
+ riscv,hart-indexes = <0x0 0x1 0x10 0x11>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.txt
deleted file mode 100644
index 597e8a089fe4..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-* TI Common Platform Interrupt Controller
-
-Common Platform Interrupt Controller (cp_intc) is used on
-OMAP-L1x SoCs and can support several configurable number
-of interrupts.
-
-Main node required properties:
-
-- compatible : should be:
- "ti,cp-intc"
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The type shall be a <u32> and the value shall be 1.
-
- The cell contains the interrupt number in the range [0-128].
-- ti,intc-size: Number of interrupts handled by the interrupt controller.
-- reg: physical base address and size of the intc registers map.
-
-Example:
-
- intc: interrupt-controller@1 {
- compatible = "ti,cp-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- ti,intc-size = <101>;
- reg = <0xfffee000 0x2000>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.yaml
new file mode 100644
index 000000000000..77d018d20f9f
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.yaml
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/ti,cp-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI Common Platform Interrupt Controller
+
+maintainers:
+ - Bartosz Golaszewski <brgl@bgdev.pl>
+
+description:
+ Common Platform Interrupt Controller (cp_intc) is used on OMAP-L1x SoCs and
+ can support several configurable number of interrupts.
+
+properties:
+ compatible:
+ const: ti,cp-intc
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+ description: Encodes an interrupt number in the range 0–128.
+
+ ti,intc-size:
+ description: Number of interrupts handled by the interrupt controller.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - ti,intc-size
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@fffee000 {
+ compatible = "ti,cp-intc";
+ reg = <0xfffee000 0x2000>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ ti,intc-size = <101>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt
deleted file mode 100644
index 5f94d7739d8d..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-Keystone 2 IRQ controller IP
-
-On Keystone SOCs, DSP cores can send interrupts to ARM
-host using the IRQ controller IP. It provides 28 IRQ signals to ARM.
-The IRQ handler running on HOST OS can identify DSP signal source by
-analyzing SRCCx bits in IPCARx registers. This is one of the component
-used by the IPC mechanism used on Keystone SOCs.
-
-Required Properties:
-- compatible: should be "ti,keystone-irq"
-- ti,syscon-dev : phandle and offset pair. The phandle to syscon used to
- access device control registers and the offset inside
- device control registers range.
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode interrupt
- source should be 1.
-- interrupts: interrupt reference to primary interrupt controller
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-Example:
- kirq0: keystone_irq0@26202a0 {
- compatible = "ti,keystone-irq";
- ti,syscon-dev = <&devctrl 0x2a0>;
- interrupts = <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>;
- interrupt-controller;
- #interrupt-cells = <1>;
- };
-
- dsp0: dsp0 {
- compatible = "linux,rproc-user";
- ...
- interrupt-parent = <&kirq0>;
- interrupts = <10 2>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.yaml
new file mode 100644
index 000000000000..27d448d1786a
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ti,keystone-irq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Keystone 2 IRQ controller IP
+
+maintainers:
+ - Grygorii Strashko <grygorii.strashko@ti.com>
+
+description:
+ On Keystone SOCs, DSP cores can send interrupts to ARM host using the IRQ
+ controller IP. It provides 28 IRQ signals to ARM. The IRQ handler running on
+ HOST OS can identify DSP signal source by analyzing SRCCx bits in IPCARx
+ registers. This is one of the component used by the IPC mechanism used on
+ Keystone SOCs.
+
+properties:
+ compatible:
+ const: ti,keystone-irq
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+ interrupts:
+ maxItems: 1
+
+ ti,syscon-dev:
+ description: Phandle and offset to syscon device
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: Phandle to syscon device control registers
+ - description: Offset to control register
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+ - interrupts
+ - ti,syscon-dev
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ interrupt-controller@2a0 {
+ compatible = "ti,keystone-irq";
+ reg = <0x2a0 0x4>;
+ ti,syscon-dev = <&devctrl 0x2a0>;
+ interrupts = <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt
deleted file mode 100644
index 38ce5d037722..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Omap2/3 intc controller
-
-On TI omap2 and 3 the intc interrupt controller can provide
-96 or 128 IRQ signals to the ARM host depending on the SoC.
-
-Required Properties:
-- compatible: should be one of
- "ti,omap2-intc"
- "ti,omap3-intc"
- "ti,dm814-intc"
- "ti,dm816-intc"
- "ti,am33xx-intc"
-
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode interrupt
- source, should be 1 for intc
-- interrupts: interrupt reference to primary interrupt controller
-
-Please refer to interrupts.txt in this directory for details of the common
-Interrupt Controllers bindings used by client devices.
-
-Example:
- intc: interrupt-controller@48200000 {
- compatible = "ti,omap3-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- reg = <0x48200000 0x1000>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.yaml
new file mode 100644
index 000000000000..cb118180621f
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,omap-intc-irq.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/ti,omap-intc-irq.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI OMAP Interrupt Controller
+
+maintainers:
+ - Tony Lindgren <tony@atomide.com>
+
+description:
+ On TI omap2 and 3 the intc interrupt controller can provide 96 or 128 IRQ
+ signals to the ARM host depending on the SoC.
+
+properties:
+ compatible:
+ enum:
+ - ti,omap2-intc
+ - ti,omap3-intc
+ - ti,dm814-intc
+ - ti,dm816-intc
+ - ti,am33xx-intc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@48200000 {
+ compatible = "ti,omap3-intc";
+ reg = <0x48200000 0x1000>;
+ interrupts = <32>;
+ interrupt-controller;
+ #interrupt-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,omap2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,omap2-intc.txt
deleted file mode 100644
index f2583e6ec060..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,omap2-intc.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-* OMAP Interrupt Controller
-
-OMAP2/3 are using a TI interrupt controller that can support several
-configurable number of interrupts.
-
-Main node required properties:
-
-- compatible : should be:
- "ti,omap2-intc"
-- interrupt-controller : Identifies the node as an interrupt controller
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The type shall be a <u32> and the value shall be 1.
-
- The cell contains the interrupt number in the range [0-128].
-- ti,intc-size: Number of interrupts handled by the interrupt controller.
-- reg: physical base address and size of the intc registers map.
-
-Example:
-
- intc: interrupt-controller@1 {
- compatible = "ti,omap2-intc";
- interrupt-controller;
- #interrupt-cells = <1>;
- ti,intc-size = <96>;
- reg = <0x48200000 0x1000>;
- };
-
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu b/Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu
deleted file mode 100644
index 422d6908f8b2..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu
+++ /dev/null
@@ -1,31 +0,0 @@
-TI OMAP4 Wake-up Generator
-
-All TI OMAP4/5 (and their derivatives) an interrupt controller that
-routes interrupts to the GIC, and also serves as a wakeup source. It
-is also referred to as "WUGEN-MPU", hence the name of the binding.
-
-Required properties:
-
-- compatible : should contain at least "ti,omap4-wugen-mpu" or
- "ti,omap5-wugen-mpu"
-- reg : Specifies base physical address and size of the registers.
-- interrupt-controller : Identifies the node as an interrupt controller.
-- #interrupt-cells : Specifies the number of cells needed to encode an
- interrupt source. The value must be 3.
-
-Notes:
-
-- Because this HW ultimately routes interrupts to the GIC, the
- interrupt specifier must be that of the GIC.
-- Only SPIs can use the WUGEN as an interrupt parent. SGIs and PPIs
- are explicitly forbidden.
-
-Example:
-
- wakeupgen: interrupt-controller@48281000 {
- compatible = "ti,omap5-wugen-mpu", "ti,omap4-wugen-mpu";
- interrupt-controller;
- #interrupt-cells = <3>;
- reg = <0x48281000 0x1000>;
- interrupt-parent = <&gic>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu.yaml
new file mode 100644
index 000000000000..61b30a7732ec
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,omap4-wugen-mpu.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/ti,omap4-wugen-mpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI OMAP4 Wake-up Generator
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: >
+ All TI OMAP4/5 (and their derivatives) are interrupt controllers that route
+ interrupts to the GIC, and also serve as wakeup sources. They are also
+ referred to as "WUGEN-MPU", hence the name of the binding.
+
+ Notes:
+
+ - Because this HW ultimately routes interrupts to the GIC, the interrupt
+ specifier must be that of the GIC.
+ - Only SPIs can use the WUGEN as an interrupt parent. SGIs and PPIs are
+ explicitly forbidden.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: ti,omap5-wugen-mpu
+ - const: ti,omap4-wugen-mpu
+ - const: ti,omap4-wugen-mpu
+
+ reg:
+ maxItems: 1
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 3
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@48281000 {
+ compatible = "ti,omap5-wugen-mpu", "ti,omap4-wugen-mpu";
+ reg = <0x48281000 0x1000>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml
index 051beb45d998..3cd5a1822e14 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml
@@ -1,4 +1,4 @@
-# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/interrupt-controller/ti,pruss-intc.yaml#
@@ -46,7 +46,7 @@ properties:
AM437x family of SoCs,
AM57xx family of SoCs
66AK2G family of SoCs
- Use "ti,icssg-intc" for K3 AM65x & J721E family of SoCs
+ Use "ti,icssg-intc" for K3 AM65x, J721E and AM64x family of SoCs
reg:
maxItems: 1
@@ -95,6 +95,8 @@ properties:
- AM65x and J721E SoCs have "host_intr5", "host_intr6" and
"host_intr7" interrupts connected to MPU, and other ICSSG
instances.
+ - AM64x SoCs have all the 8 host interrupts connected to various
+ other SoC entities
required:
- compatible
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml
index 3d89668573e8..5449266f258a 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-inta.yaml
@@ -59,6 +59,9 @@ properties:
interrupt-controller: true
+ '#interrupt-cells':
+ const: 0
+
msi-controller: true
ti,interrupt-ranges:
@@ -77,9 +80,14 @@ properties:
ti,unmapped-event-sources:
$ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ maxItems: 1
description:
Array of phandles to DMA controllers where the unmapped events originate.
+ power-domains:
+ maxItems: 1
+
required:
- compatible
- reg
@@ -101,6 +109,7 @@ examples:
compatible = "ti,sci-inta";
reg = <0x0 0x33d00000 0x0 0x100000>;
interrupt-controller;
+ #interrupt-cells = <0>;
msi-controller;
interrupt-parent = <&main_navss_intr>;
ti,sci = <&dmsc>;
diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
index e12aee42b126..c99cc7323c71 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
@@ -58,6 +58,9 @@ properties:
1 = If intr supports edge triggered interrupts.
4 = If intr supports level triggered interrupts.
+ reg:
+ maxItems: 1
+
interrupt-controller: true
'#interrupt-cells':
diff --git a/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.txt
deleted file mode 100644
index 0a4ce1051b02..000000000000
--- a/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-VIA/Wondermedia VT8500 Interrupt Controller
------------------------------------------------------
-
-Required properties:
-- compatible : "via,vt8500-intc"
-- reg : Should contain 1 register ranges(address and length)
-- #interrupt-cells : should be <1>
-
-Example:
-
- intc: interrupt-controller@d8140000 {
- compatible = "via,vt8500-intc";
- interrupt-controller;
- reg = <0xd8140000 0x10000>;
- #interrupt-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.yaml
new file mode 100644
index 000000000000..bc14c74bf7d5
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.yaml
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/via,vt8500-intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: VIA and WonderMedia SoCs Interrupt Controller
+
+description:
+ This is the interrupt controller used in single-core ARM SoCs made by
+ VIA and WonderMedia (up to and including WM8950). Each block handles
+ up to 64 interrupt sources (level or edge triggered) and can generate
+ up to 8 interrupts to its parent when used in a chained configuration.
+
+maintainers:
+ - Alexey Charkov <alchark@gmail.com>
+
+allOf:
+ - $ref: /schemas/interrupt-controller.yaml#
+
+properties:
+ compatible:
+ const: via,vt8500-intc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description:
+ Interrupt number raised by the IRQ0 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ1 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ2 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ3 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ4 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ5 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ6 output of this controller
+ Only used if this controller is chained
+ - description:
+ Interrupt number raised by the IRQ7 output of this controller
+ Only used if this controller is chained
+
+ interrupt-controller: true
+
+ '#interrupt-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupt-controller
+ - '#interrupt-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@d8140000 {
+ compatible = "via,vt8500-intc";
+ interrupt-controller;
+ reg = <0xd8140000 0x10000>;
+ #interrupt-cells = <1>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/interrupt-controller/xlnx,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/xlnx,intc.yaml
new file mode 100644
index 000000000000..b4f58ed25993
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/xlnx,intc.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/xlnx,intc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx Interrupt Controller
+
+maintainers:
+ - Michal Simek <michal.simek@amd.com>
+
+description:
+ The controller is a soft IP core that is configured at build time for the
+ number of interrupts and the type of each interrupt. These details cannot
+ be changed at run time.
+
+properties:
+ compatible:
+ const: xlnx,xps-intc-1.00.a
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ "#interrupt-cells":
+ const: 2
+ description:
+ Specifies the number of cells needed to encode an interrupt source.
+ The value shall be a minimum of 1. The Xilinx device trees typically
+ use 2 but the 2nd value is not used.
+
+ interrupt-controller: true
+
+ interrupts:
+ maxItems: 1
+ description:
+ Specifies the interrupt of the parent controller from which it is chained.
+
+ xlnx,kind-of-intr:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ A 32 bit value specifying the interrupt type for each possible interrupt
+ (1 = edge, 0 = level). The interrupt type typically comes in thru
+ the device tree node of the interrupt generating device, but in this case
+ the interrupt type is determined by the interrupt controller based on how
+ it was implemented.
+
+ xlnx,num-intr-inputs:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 32
+ description:
+ Specifies the number of interrupts supported by the specific
+ implementation of the controller.
+
+required:
+ - reg
+ - "#interrupt-cells"
+ - interrupt-controller
+ - xlnx,kind-of-intr
+ - xlnx,num-intr-inputs
+
+additionalProperties: false
+
+examples:
+ - |
+ interrupt-controller@41800000 {
+ compatible = "xlnx,xps-intc-1.00.a";
+ reg = <0x41800000 0x10000>;
+ #interrupt-cells = <2>;
+ interrupt-controller;
+ xlnx,kind-of-intr = <0x1>;
+ xlnx,num-intr-inputs = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml b/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml
index 5e125cf2a88b..a8409db4a3e3 100644
--- a/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml
+++ b/Documentation/devicetree/bindings/iommu/allwinner,sun50i-h6-iommu.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/iommu/allwinner,sun50i-h6-iommu.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner H6 IOMMU Device Tree Bindings
+title: Allwinner H6 IOMMU
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -17,7 +17,12 @@ properties:
The content of the cell is the master ID.
compatible:
- const: allwinner,sun50i-h6-iommu
+ oneOf:
+ - const: allwinner,sun50i-h6-iommu
+ - const: allwinner,sun50i-h616-iommu
+ - items:
+ - const: allwinner,sun55i-a523-iommu
+ - const: allwinner,sun50i-h616-iommu
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/iommu/apple,dart.yaml b/Documentation/devicetree/bindings/iommu/apple,dart.yaml
new file mode 100644
index 000000000000..47ec7fa52c3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/apple,dart.yaml
@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iommu/apple,dart.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple DART IOMMU
+
+maintainers:
+ - Sven Peter <sven@svenpeter.dev>
+
+description: |+
+ Apple SoCs may contain an implementation of their Device Address
+ Resolution Table which provides a mandatory layer of address
+ translations for various masters.
+
+ Each DART instance is capable of handling up to 16 different streams
+ with individual pagetables and page-level read/write protection flags.
+
+ This DART IOMMU also raises interrupts in response to various
+ fault conditions.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - apple,t8103-dart
+ - apple,t8103-usb4-dart
+ - apple,t8110-dart
+ - apple,t6000-dart
+ - items:
+ - const: apple,t6020-dart
+ - const: apple,t8110-dart
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ description:
+ Reference to the gate clock phandle if required for this IOMMU.
+ Optional since not all IOMMUs are attached to a clock gate.
+
+ '#iommu-cells':
+ const: 1
+ description:
+ Has to be one. The single cell describes the stream id emitted by
+ a master to the IOMMU.
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - '#iommu-cells'
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |+
+ dart1: iommu@82f80000 {
+ compatible = "apple,t8103-dart";
+ reg = <0x82f80000 0x4000>;
+ interrupts = <1 781 4>;
+ #iommu-cells = <1>;
+ };
+
+ master1 {
+ iommus = <&dart1 0>;
+ };
+
+ - |+
+ dart2a: iommu@82f00000 {
+ compatible = "apple,t8103-dart";
+ reg = <0x82f00000 0x4000>;
+ interrupts = <1 781 4>;
+ #iommu-cells = <1>;
+ };
+ dart2b: iommu@82f80000 {
+ compatible = "apple,t8103-dart";
+ reg = <0x82f80000 0x4000>;
+ interrupts = <1 781 4>;
+ #iommu-cells = <1>;
+ };
+
+ master2 {
+ iommus = <&dart2a 0>, <&dart2b 1>;
+ };
diff --git a/Documentation/devicetree/bindings/iommu/apple,sart.yaml b/Documentation/devicetree/bindings/iommu/apple,sart.yaml
new file mode 100644
index 000000000000..88e66d4b13c6
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/apple,sart.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iommu/apple,sart.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple SART DMA address filter
+
+maintainers:
+ - Sven Peter <sven@svenpeter.dev>
+
+description:
+ Apple SART is a simple address filter for DMA transactions. Regions of
+ physical memory must be added to the SART's allow list before any
+ DMA can target these. Unlike a proper IOMMU no remapping can be done and
+ special support in the consumer driver is required since not all DMA
+ transactions of a single device are subject to SART filtering.
+
+ SART1 has first been used since at least the A11 (iPhone 8 and iPhone X)
+ and allows 36 bit of physical address space and filter entries with sizes
+ up to 24 bit.
+
+ SART2, first seen in A14 and M1, allows 36 bit of physical address space
+ and filter entry size up to 36 bit.
+
+ SART3, first seen in M1 Pro/Max, extends both the address space and filter
+ entry size to 42 bit.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - apple,t6020-sart
+ - apple,t8112-sart
+ - const: apple,t6000-sart
+ - enum:
+ - apple,t6000-sart
+ - apple,t8015-sart
+ - apple,t8103-sart
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ iommu@7bc50000 {
+ compatible = "apple,t8103-sart";
+ reg = <0x7bc50000 0x4000>;
+ };
diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu-v3.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu-v3.yaml
index e87bfbcc6913..75fcf4cb52d9 100644
--- a/Documentation/devicetree/bindings/iommu/arm,smmu-v3.yaml
+++ b/Documentation/devicetree/bindings/iommu/arm,smmu-v3.yaml
@@ -37,12 +37,13 @@ properties:
hardware supports just a single, combined interrupt line.
If provided, then the combined interrupt will be used in preference to
any others.
- - minItems: 2
+ - minItems: 1
items:
- - const: eventq # Event Queue not empty
- - const: gerror # Global Error activated
- - const: priq # PRI Queue not empty
- - const: cmdq-sync # CMD_SYNC complete
+ enum:
+ - eventq # Event Queue not empty
+ - gerror # Global Error activated
+ - cmdq-sync # CMD_SYNC complete
+ - priq # PRI Queue not empty
'#iommu-cells':
const: 1
diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml
index 1181b590db71..cdbd23b5c08c 100644
--- a/Documentation/devicetree/bindings/iommu/arm,smmu.yaml
+++ b/Documentation/devicetree/bindings/iommu/arm,smmu.yaml
@@ -28,40 +28,129 @@ properties:
- enum:
- qcom,msm8996-smmu-v2
- qcom,msm8998-smmu-v2
+ - qcom,sdm630-smmu-v2
+ - qcom,sm6375-smmu-v2
- const: qcom,smmu-v2
- - description: Qcom SoCs implementing "arm,mmu-500"
+ - description: Qcom SoCs implementing "qcom,smmu-500" and "arm,mmu-500"
items:
- enum:
+ - qcom,glymur-smmu-500
+ - qcom,kaanapali-smmu-500
+ - qcom,milos-smmu-500
+ - qcom,qcm2290-smmu-500
+ - qcom,qcs615-smmu-500
+ - qcom,qcs8300-smmu-500
+ - qcom,qdu1000-smmu-500
+ - qcom,sa8255p-smmu-500
+ - qcom,sa8775p-smmu-500
+ - qcom,sar2130p-smmu-500
- qcom,sc7180-smmu-500
- qcom,sc7280-smmu-500
- qcom,sc8180x-smmu-500
+ - qcom,sc8280xp-smmu-500
+ - qcom,sdm670-smmu-500
- qcom,sdm845-smmu-500
+ - qcom,sdx55-smmu-500
+ - qcom,sdx65-smmu-500
+ - qcom,sdx75-smmu-500
+ - qcom,sm6115-smmu-500
+ - qcom,sm6125-smmu-500
+ - qcom,sm6350-smmu-500
+ - qcom,sm6375-smmu-500
- qcom,sm8150-smmu-500
- qcom,sm8250-smmu-500
- qcom,sm8350-smmu-500
+ - qcom,sm8450-smmu-500
+ - qcom,sm8550-smmu-500
+ - qcom,sm8650-smmu-500
+ - qcom,sm8750-smmu-500
+ - qcom,x1e80100-smmu-500
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+
+ - description: Qcom SoCs implementing "arm,mmu-500" (legacy binding)
+ deprecated: true
+ items:
+ # Do not add additional SoC to this list. Instead use two previous lists.
+ - enum:
+ - qcom,qcm2290-smmu-500
+ - qcom,sc7180-smmu-500
+ - qcom,sc7280-smmu-500
+ - qcom,sc8180x-smmu-500
+ - qcom,sc8280xp-smmu-500
+ - qcom,sdm845-smmu-500
+ - qcom,sm6115-smmu-500
+ - qcom,sm6350-smmu-500
+ - qcom,sm6375-smmu-500
+ - qcom,sm8150-smmu-500
+ - qcom,sm8250-smmu-500
+ - qcom,sm8350-smmu-500
+ - qcom,sm8450-smmu-500
+ - const: arm,mmu-500
+ - description: Qcom Adreno GPUs implementing "qcom,smmu-500" and "arm,mmu-500"
+ items:
+ - enum:
+ - qcom,glymur-smmu-500
+ - qcom,kaanapali-smmu-500
+ - qcom,milos-smmu-500
+ - qcom,qcm2290-smmu-500
+ - qcom,qcs615-smmu-500
+ - qcom,qcs8300-smmu-500
+ - qcom,sa8255p-smmu-500
+ - qcom,sa8775p-smmu-500
+ - qcom,sar2130p-smmu-500
+ - qcom,sc7280-smmu-500
+ - qcom,sc8180x-smmu-500
+ - qcom,sc8280xp-smmu-500
+ - qcom,sm6115-smmu-500
+ - qcom,sm6125-smmu-500
+ - qcom,sm8150-smmu-500
+ - qcom,sm8250-smmu-500
+ - qcom,sm8350-smmu-500
+ - qcom,sm8450-smmu-500
+ - qcom,sm8550-smmu-500
+ - qcom,sm8650-smmu-500
+ - qcom,sm8750-smmu-500
+ - qcom,x1e80100-smmu-500
+ - const: qcom,adreno-smmu
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+ - description: Qcom Adreno GPUs implementing "arm,mmu-500" (legacy binding)
+ deprecated: true
+ items:
+ # Do not add additional SoC to this list. Instead use previous list.
+ - enum:
+ - qcom,sc7280-smmu-500
+ - qcom,sm8150-smmu-500
+ - qcom,sm8250-smmu-500
+ - const: qcom,adreno-smmu
- const: arm,mmu-500
- description: Qcom Adreno GPUs implementing "arm,smmu-v2"
items:
- enum:
+ - qcom,msm8996-smmu-v2
- qcom,sc7180-smmu-v2
+ - qcom,sdm630-smmu-v2
+ - qcom,sdm670-smmu-v2
- qcom,sdm845-smmu-v2
+ - qcom,sm6350-smmu-v2
+ - qcom,sm7150-smmu-v2
- const: qcom,adreno-smmu
- const: qcom,smmu-v2
- description: Marvell SoCs implementing "arm,mmu-500"
items:
- const: marvell,ap806-smmu-500
- const: arm,mmu-500
- - description: NVIDIA SoCs that program two ARM MMU-500s identically
- items:
- description: NVIDIA SoCs that require memory controller interaction
and may program multiple ARM MMU-500s identically with the memory
controller interleaving translations between multiple instances
for improved performance.
items:
- enum:
- - const: nvidia,tegra194-smmu
- - const: nvidia,tegra186-smmu
+ - nvidia,tegra186-smmu
+ - nvidia,tegra194-smmu
+ - nvidia,tegra234-smmu
- const: nvidia,smmu-500
- items:
- const: arm,mmu-500
@@ -141,19 +230,27 @@ properties:
present in such cases.
clock-names:
- items:
- - const: bus
- - const: iface
+ minItems: 1
+ maxItems: 7
clocks:
- items:
- - description: bus clock required for downstream bus access and for the
- smmu ptw
- - description: interface clock required to access smmu's registers
- through the TCU's programming interface.
+ minItems: 1
+ maxItems: 7
power-domains:
- maxItems: 1
+ minItems: 1
+ maxItems: 3
+
+ nvidia,memory-controller:
+ description: |
+ A phandle to the memory controller on NVIDIA Tegra186 and later SoCs.
+ The memory controller needs to be programmed with a mapping of memory
+ client IDs to ARM SMMU stream IDs.
+
+ If this property is absent, the mapping programmed by early firmware
+ will be used and it is not guaranteed that IOMMU translations will be
+ enabled for any given device.
+ $ref: /schemas/types.yaml#/definitions/phandle
required:
- compatible
@@ -170,18 +267,359 @@ allOf:
compatible:
contains:
enum:
- - nvidia,tegra194-smmu
- nvidia,tegra186-smmu
+ - nvidia,tegra194-smmu
+ - nvidia,tegra234-smmu
then:
properties:
reg:
minItems: 1
maxItems: 2
+
+ # The reference to the memory controller is required to ensure that the
+ # memory client to stream ID mapping can be done synchronously with the
+ # IOMMU attachment.
+ required:
+ - nvidia,memory-controller
else:
properties:
reg:
maxItems: 1
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8998-smmu-v2
+ - qcom,sdm630-smmu-v2
+ then:
+ anyOf:
+ - properties:
+ clock-names:
+ items:
+ - const: bus
+ clocks:
+ items:
+ - description: bus clock required for downstream bus access and for
+ the smmu ptw
+ - properties:
+ clock-names:
+ items:
+ - const: iface
+ - const: mem
+ - const: mem_iface
+ clocks:
+ items:
+ - description: interface clock required to access smmu's registers
+ through the TCU's programming interface.
+ - description: bus clock required for memory access
+ - description: bus clock required for GPU memory access
+ - properties:
+ clock-names:
+ items:
+ - const: iface-mm
+ - const: iface-smmu
+ - const: bus-smmu
+ clocks:
+ items:
+ - description: interface clock required to access mnoc's registers
+ through the TCU's programming interface.
+ - description: interface clock required to access smmu's registers
+ through the TCU's programming interface.
+ - description: bus clock required for the smmu ptw
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sm6375-smmu-v2
+ then:
+ anyOf:
+ - properties:
+ clock-names:
+ items:
+ - const: bus
+ clocks:
+ items:
+ - description: bus clock required for downstream bus access and for
+ the smmu ptw
+ - properties:
+ clock-names:
+ items:
+ - const: iface
+ - const: mem
+ - const: mem_iface
+ clocks:
+ items:
+ - description: interface clock required to access smmu's registers
+ through the TCU's programming interface.
+ - description: bus clock required for memory access
+ - description: bus clock required for GPU memory access
+ - properties:
+ clock-names:
+ items:
+ - const: iface-mm
+ - const: iface-smmu
+ - const: bus-mm
+ - const: bus-smmu
+ clocks:
+ items:
+ - description: interface clock required to access mnoc's registers
+ through the TCU's programming interface.
+ - description: interface clock required to access smmu's registers
+ through the TCU's programming interface.
+ - description: bus clock required for downstream bus access
+ - description: bus clock required for the smmu ptw
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8996-smmu-v2
+ - qcom,sc7180-smmu-v2
+ - qcom,sdm845-smmu-v2
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: bus
+ - const: iface
+
+ clocks:
+ items:
+ - description: bus clock required for downstream bus access and for
+ the smmu ptw
+ - description: interface clock required to access smmu's registers
+ through the TCU's programming interface.
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,qcs8300-smmu-500
+ - qcom,sa8775p-smmu-500
+ - qcom,sc7280-smmu-500
+ - qcom,sc8280xp-smmu-500
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: gcc_gpu_memnoc_gfx_clk
+ - const: gcc_gpu_snoc_dvm_gfx_clk
+ - const: gpu_cc_ahb_clk
+ - const: gpu_cc_hlos1_vote_gpu_smmu_clk
+ - const: gpu_cc_cx_gmu_clk
+ - const: gpu_cc_hub_cx_int_clk
+ - const: gpu_cc_hub_aon_clk
+
+ clocks:
+ items:
+ - description: GPU memnoc_gfx clock
+ - description: GPU snoc_dvm_gfx clock
+ - description: GPU ahb clock
+ - description: GPU hlos1_vote_GPU smmu clock
+ - description: GPU cx_gmu clock
+ - description: GPU hub_cx_int clock
+ - description: GPU hub_aon clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sc8180x-smmu-500
+ - qcom,sm6350-smmu-v2
+ - qcom,sm7150-smmu-v2
+ - qcom,sm8150-smmu-500
+ - qcom,sm8250-smmu-500
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: ahb
+ - const: bus
+ - const: iface
+
+ clocks:
+ items:
+ - description: bus clock required for AHB bus access
+ - description: bus clock required for downstream bus access and for
+ the smmu ptw
+ - description: interface clock required to access smmu's registers
+ through the TCU's programming interface.
+
+ - if:
+ properties:
+ compatible:
+ items:
+ - enum:
+ - qcom,sm8350-smmu-500
+ - const: qcom,adreno-smmu
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: bus
+ - const: iface
+ - const: ahb
+ - const: hlos1_vote_gpu_smmu
+ - const: cx_gmu
+ - const: hub_cx_int
+ - const: hub_aon
+ clocks:
+ minItems: 7
+ maxItems: 7
+
+ - if:
+ properties:
+ compatible:
+ items:
+ - enum:
+ - qcom,qcm2290-smmu-500
+ - qcom,qcs615-smmu-500
+ - qcom,sm6115-smmu-500
+ - qcom,sm6125-smmu-500
+ - const: qcom,adreno-smmu
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: mem
+ - const: hlos
+ - const: iface
+
+ clocks:
+ items:
+ - description: GPU memory bus clock
+ - description: Voter clock required for HLOS SMMU access
+ - description: Interface clock required for register access
+
+ - if:
+ properties:
+ compatible:
+ items:
+ - const: qcom,sm8450-smmu-500
+ - const: qcom,adreno-smmu
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: gmu
+ - const: hub
+ - const: hlos
+ - const: bus
+ - const: iface
+ - const: ahb
+
+ clocks:
+ items:
+ - description: GMU clock
+ - description: GPU HUB clock
+ - description: HLOS vote clock
+ - description: GPU memory bus clock
+ - description: GPU SNoC bus clock
+ - description: GPU AHB clock
+
+ - if:
+ properties:
+ compatible:
+ items:
+ - enum:
+ - qcom,milos-smmu-500
+ - qcom,sar2130p-smmu-500
+ - qcom,sm8550-smmu-500
+ - qcom,sm8650-smmu-500
+ - qcom,x1e80100-smmu-500
+ - const: qcom,adreno-smmu
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: hlos
+ - const: bus
+ - const: iface
+ - const: ahb
+
+ clocks:
+ items:
+ - description: HLOS vote clock
+ - description: GPU memory bus clock
+ - description: GPU SNoC bus clock
+ - description: GPU AHB clock
+
+ - if:
+ properties:
+ compatible:
+ items:
+ - const: qcom,sm8750-smmu-500
+ - const: qcom,adreno-smmu
+ - const: qcom,smmu-500
+ - const: arm,mmu-500
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: hlos
+ clocks:
+ items:
+ - description: HLOS vote clock
+
+ # Disallow clocks for all other platforms with specific compatibles
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - cavium,smmu-v2
+ - marvell,ap806-smmu-500
+ - nvidia,smmu-500
+ - qcom,qdu1000-smmu-500
+ - qcom,sa8255p-smmu-500
+ - qcom,sc7180-smmu-500
+ - qcom,sdm670-smmu-500
+ - qcom,sdm845-smmu-500
+ - qcom,sdx55-smmu-500
+ - qcom,sdx65-smmu-500
+ - qcom,sm6350-smmu-500
+ - qcom,sm6375-smmu-500
+ then:
+ properties:
+ clock-names: false
+ clocks: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,sm6375-smmu-500
+ then:
+ properties:
+ power-domains:
+ items:
+ - description: SNoC MMU TBU RT GDSC
+ - description: SNoC MMU TBU NRT GDSC
+ - description: SNoC TURING MMU TBU0 GDSC
+
+ required:
+ - power-domains
+ else:
+ properties:
+ power-domains:
+ maxItems: 1
+
examples:
- |+
/* SMMU with stream matching or stream indexing */
@@ -204,7 +642,6 @@ examples:
<&smmu1 7>;
};
-
/* SMMU with stream matching */
smmu2: iommu@ba5f0000 {
compatible = "arm,smmu-v1";
@@ -230,7 +667,6 @@ examples:
iommus = <&smmu2 1 0x30>;
};
-
/* ARM MMU-500 with 10-bit stream ID input configuration */
smmu3: iommu@ba600000 {
compatible = "arm,mmu-500", "arm,smmu-v2";
@@ -251,8 +687,6 @@ examples:
/* bus whose child devices emit one unique 10-bit stream
ID each, but may master through multiple SMMU TBUs */
iommu-map = <0 &smmu3 0 0x400>;
-
-
};
- |+
diff --git a/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml b/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
index 0f26fe14c8e2..79c573c47b08 100644
--- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
+++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
@@ -52,7 +52,7 @@ description: |+
As above, The Multimedia HW will go through SMI and M4U while it
access EMI. SMI is a bridge between m4u and the Multimedia HW. It contain
smi local arbiter and smi common. It will control whether the Multimedia
- HW should go though the m4u for translation or bypass it and talk
+ HW should go through the m4u for translation or bypass it and talk
directly with EMI. And also SMI help control the power domain and clocks for
each local arbiter.
@@ -73,10 +73,23 @@ properties:
- mediatek,mt2701-m4u # generation one
- mediatek,mt2712-m4u # generation two
- mediatek,mt6779-m4u # generation two
+ - mediatek,mt6795-m4u # generation two
+ - mediatek,mt6893-iommu-mm # generation two
- mediatek,mt8167-m4u # generation two
- mediatek,mt8173-m4u # generation two
- mediatek,mt8183-m4u # generation two
+ - mediatek,mt8186-iommu-mm # generation two
+ - mediatek,mt8188-iommu-vdo # generation two
+ - mediatek,mt8188-iommu-vpp # generation two
+ - mediatek,mt8188-iommu-infra # generation two
+ - mediatek,mt8189-iommu-apu # generation two
+ - mediatek,mt8189-iommu-infra # generation two
+ - mediatek,mt8189-iommu-mm # generation two
- mediatek,mt8192-m4u # generation two
+ - mediatek,mt8195-iommu-vdo # generation two
+ - mediatek,mt8195-iommu-vpp # generation two
+ - mediatek,mt8195-iommu-infra # generation two
+ - mediatek,mt8365-m4u # generation two
- description: mt7623 generation one
items:
@@ -97,10 +110,16 @@ properties:
items:
- const: bclk
+ mediatek,infracfg:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: The phandle to the mediatek infracfg syscon
+
mediatek,larbs:
$ref: /schemas/types.yaml#/definitions/phandle-array
minItems: 1
maxItems: 32
+ items:
+ maxItems: 1
description: |
List of phandle to the local arbiters in the current Socs.
Refer to bindings/memory-controllers/mediatek,smi-larb.yaml. It must sort
@@ -111,13 +130,20 @@ properties:
description: |
This is the mtk_m4u_id according to the HW. Specifies the mtk_m4u_id as
defined in
+ dt-binding/memory/mediatek,mt8188-memory-port.h for mt8188,
+ dt-binding/memory/mediatek,mt8189-memory-port.h for mt8189,
dt-binding/memory/mt2701-larb-port.h for mt2701 and mt7623,
dt-binding/memory/mt2712-larb-port.h for mt2712,
dt-binding/memory/mt6779-larb-port.h for mt6779,
+ dt-binding/memory/mt6795-larb-port.h for mt6795,
+ dt-binding/memory/mediatek,mt6893-memory-port.h for mt6893,
dt-binding/memory/mt8167-larb-port.h for mt8167,
dt-binding/memory/mt8173-larb-port.h for mt8173,
dt-binding/memory/mt8183-larb-port.h for mt8183,
+ dt-binding/memory/mt8186-memory-port.h for mt8186,
dt-binding/memory/mt8192-larb-port.h for mt8192.
+ dt-binding/memory/mt8195-memory-port.h for mt8195.
+ dt-binding/memory/mediatek,mt8365-larb-port.h for mt8365.
power-domains:
maxItems: 1
@@ -126,7 +152,6 @@ required:
- compatible
- reg
- interrupts
- - mediatek,larbs
- '#iommu-cells'
allOf:
@@ -137,8 +162,16 @@ allOf:
enum:
- mediatek,mt2701-m4u
- mediatek,mt2712-m4u
+ - mediatek,mt6795-m4u
+ - mediatek,mt6893-iommu-mm
- mediatek,mt8173-m4u
+ - mediatek,mt8186-iommu-mm
+ - mediatek,mt8188-iommu-vdo
+ - mediatek,mt8188-iommu-vpp
+ - mediatek,mt8189-iommu-mm
- mediatek,mt8192-m4u
+ - mediatek,mt8195-iommu-vdo
+ - mediatek,mt8195-iommu-vpp
then:
required:
@@ -148,12 +181,47 @@ allOf:
properties:
compatible:
enum:
+ - mediatek,mt6893-iommu-mm
+ - mediatek,mt8186-iommu-mm
+ - mediatek,mt8188-iommu-vdo
+ - mediatek,mt8188-iommu-vpp
+ - mediatek,mt8189-iommu-mm
- mediatek,mt8192-m4u
+ - mediatek,mt8195-iommu-vdo
+ - mediatek,mt8195-iommu-vpp
then:
required:
- power-domains
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt2712-m4u
+ - mediatek,mt6795-m4u
+ - mediatek,mt8173-m4u
+
+ then:
+ required:
+ - mediatek,infracfg
+
+ - if: # The IOMMUs don't have larbs.
+ not:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8188-iommu-infra
+ - mediatek,mt8189-iommu-apu
+ - mediatek,mt8189-iommu-infra
+ - mediatek,mt8195-iommu-infra
+
+ then:
+ required:
+ - mediatek,larbs
+
additionalProperties: false
examples:
@@ -167,17 +235,8 @@ examples:
interrupts = <GIC_SPI 139 IRQ_TYPE_LEVEL_LOW>;
clocks = <&infracfg CLK_INFRA_M4U>;
clock-names = "bclk";
- mediatek,larbs = <&larb0 &larb1 &larb2
- &larb3 &larb4 &larb5>;
+ mediatek,infracfg = <&infracfg>;
+ mediatek,larbs = <&larb0>, <&larb1>, <&larb2>,
+ <&larb3>, <&larb4>, <&larb5>;
#iommu-cells = <1>;
};
-
- - |
- #include <dt-bindings/memory/mt8173-larb-port.h>
-
- /* Example for a client device */
- display {
- compatible = "mediatek,mt8173-disp";
- iommus = <&iommu M4U_PORT_DISP_OVL0>,
- <&iommu M4U_PORT_DISP_RDMA0>;
- };
diff --git a/Documentation/devicetree/bindings/iommu/msm,iommu-v0.txt b/Documentation/devicetree/bindings/iommu/msm,iommu-v0.txt
deleted file mode 100644
index 20236385f26e..000000000000
--- a/Documentation/devicetree/bindings/iommu/msm,iommu-v0.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-* QCOM IOMMU
-
-The MSM IOMMU is an implementation compatible with the ARM VMSA short
-descriptor page tables. It provides address translation for bus masters outside
-of the CPU, each connected to the IOMMU through a port called micro-TLB.
-
-Required Properties:
-
- - compatible: Must contain "qcom,apq8064-iommu".
- - reg: Base address and size of the IOMMU registers.
- - interrupts: Specifiers for the MMU fault interrupts. For instances that
- support secure mode two interrupts must be specified, for non-secure and
- secure mode, in that order. For instances that don't support secure mode a
- single interrupt must be specified.
- - #iommu-cells: The number of cells needed to specify the stream id. This
- is always 1.
- - qcom,ncb: The total number of context banks in the IOMMU.
- - clocks : List of clocks to be used during SMMU register access. See
- Documentation/devicetree/bindings/clock/clock-bindings.txt
- for information about the format. For each clock specified
- here, there must be a corresponding entry in clock-names
- (see below).
-
- - clock-names : List of clock names corresponding to the clocks specified in
- the "clocks" property (above).
- Should be "smmu_pclk" for specifying the interface clock
- required for iommu's register accesses.
- Should be "smmu_clk" for specifying the functional clock
- required by iommu for bus accesses.
-
-Each bus master connected to an IOMMU must reference the IOMMU in its device
-node with the following property:
-
- - iommus: A reference to the IOMMU in multiple cells. The first cell is a
- phandle to the IOMMU and the second cell is the stream id.
- A single master device can be connected to more than one iommu
- and multiple contexts in each of the iommu. So multiple entries
- are required to list all the iommus and the stream ids that the
- master is connected to.
-
-Example: mdp iommu and its bus master
-
- mdp_port0: iommu@7500000 {
- compatible = "qcom,apq8064-iommu";
- #iommu-cells = <1>;
- clock-names =
- "smmu_pclk",
- "smmu_clk";
- clocks =
- <&mmcc SMMU_AHB_CLK>,
- <&mmcc MDP_AXI_CLK>;
- reg = <0x07500000 0x100000>;
- interrupts =
- <GIC_SPI 63 0>,
- <GIC_SPI 64 0>;
- qcom,ncb = <2>;
- };
-
- mdp: qcom,mdp@5100000 {
- compatible = "qcom,mdp";
- ...
- iommus = <&mdp_port0 0
- &mdp_port0 2>;
- };
diff --git a/Documentation/devicetree/bindings/iommu/qcom,apq8064-iommu.yaml b/Documentation/devicetree/bindings/iommu/qcom,apq8064-iommu.yaml
new file mode 100644
index 000000000000..9f83f851e61a
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/qcom,apq8064-iommu.yaml
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/iommu/qcom,apq8064-iommu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm APQ8064 IOMMU
+
+maintainers:
+ - David Heidelberg <david@ixit.cz>
+
+description:
+ The MSM IOMMU is an implementation compatible with the ARM VMSA short
+ descriptor page tables. It provides address translation for bus masters
+ outside of the CPU, each connected to the IOMMU through a port called micro-TLB.
+
+properties:
+ compatible:
+ const: qcom,apq8064-iommu
+
+ clocks:
+ items:
+ - description: interface clock for register accesses
+ - description: functional clock for bus accesses
+
+ clock-names:
+ items:
+ - const: smmu_pclk
+ - const: iommu_clk
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ description: Specifiers for the MMU fault interrupts.
+ minItems: 1
+ items:
+ - description: non-secure mode interrupt
+ - description: secure mode interrupt (for instances which supports it)
+
+ "#iommu-cells":
+ const: 1
+ description: Each IOMMU specifier describes a single Stream ID.
+
+ qcom,ncb:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: The total number of context banks in the IOMMU.
+ minimum: 1
+ maximum: 4
+
+required:
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - qcom,ncb
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,mmcc-msm8960.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ iommu@7500000 {
+ compatible = "qcom,apq8064-iommu";
+ reg = <0x07500000 0x100000>;
+ interrupts = <GIC_SPI 63 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk SMMU_AHB_CLK>,
+ <&clk MDP_AXI_CLK>;
+ clock-names = "smmu_pclk",
+ "iommu_clk";
+ #iommu-cells = <1>;
+ qcom,ncb = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/iommu/qcom,iommu.txt b/Documentation/devicetree/bindings/iommu/qcom,iommu.txt
deleted file mode 100644
index 059139abce35..000000000000
--- a/Documentation/devicetree/bindings/iommu/qcom,iommu.txt
+++ /dev/null
@@ -1,121 +0,0 @@
-* QCOM IOMMU v1 Implementation
-
-Qualcomm "B" family devices which are not compatible with arm-smmu have
-a similar looking IOMMU but without access to the global register space,
-and optionally requiring additional configuration to route context irqs
-to non-secure vs secure interrupt line.
-
-** Required properties:
-
-- compatible : Should be one of:
-
- "qcom,msm8916-iommu"
-
- Followed by "qcom,msm-iommu-v1".
-
-- clock-names : Should be a pair of "iface" (required for IOMMUs
- register group access) and "bus" (required for
- the IOMMUs underlying bus access).
-
-- clocks : Phandles for respective clocks described by
- clock-names.
-
-- #address-cells : must be 1.
-
-- #size-cells : must be 1.
-
-- #iommu-cells : Must be 1. Index identifies the context-bank #.
-
-- ranges : Base address and size of the iommu context banks.
-
-- qcom,iommu-secure-id : secure-id.
-
-- List of sub-nodes, one per translation context bank. Each sub-node
- has the following required properties:
-
- - compatible : Should be one of:
- - "qcom,msm-iommu-v1-ns" : non-secure context bank
- - "qcom,msm-iommu-v1-sec" : secure context bank
- - reg : Base address and size of context bank within the iommu
- - interrupts : The context fault irq.
-
-** Optional properties:
-
-- reg : Base address and size of the SMMU local base, should
- be only specified if the iommu requires configuration
- for routing of context bank irq's to secure vs non-
- secure lines. (Ie. if the iommu contains secure
- context banks)
-
-
-** Examples:
-
- apps_iommu: iommu@1e20000 {
- #address-cells = <1>;
- #size-cells = <1>;
- #iommu-cells = <1>;
- compatible = "qcom,msm8916-iommu", "qcom,msm-iommu-v1";
- ranges = <0 0x1e20000 0x40000>;
- reg = <0x1ef0000 0x3000>;
- clocks = <&gcc GCC_SMMU_CFG_CLK>,
- <&gcc GCC_APSS_TCU_CLK>;
- clock-names = "iface", "bus";
- qcom,iommu-secure-id = <17>;
-
- // mdp_0:
- iommu-ctx@4000 {
- compatible = "qcom,msm-iommu-v1-ns";
- reg = <0x4000 0x1000>;
- interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- // venus_ns:
- iommu-ctx@5000 {
- compatible = "qcom,msm-iommu-v1-sec";
- reg = <0x5000 0x1000>;
- interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>;
- };
- };
-
- gpu_iommu: iommu@1f08000 {
- #address-cells = <1>;
- #size-cells = <1>;
- #iommu-cells = <1>;
- compatible = "qcom,msm8916-iommu", "qcom,msm-iommu-v1";
- ranges = <0 0x1f08000 0x10000>;
- clocks = <&gcc GCC_SMMU_CFG_CLK>,
- <&gcc GCC_GFX_TCU_CLK>;
- clock-names = "iface", "bus";
- qcom,iommu-secure-id = <18>;
-
- // gfx3d_user:
- iommu-ctx@1000 {
- compatible = "qcom,msm-iommu-v1-ns";
- reg = <0x1000 0x1000>;
- interrupts = <GIC_SPI 241 IRQ_TYPE_LEVEL_HIGH>;
- };
-
- // gfx3d_priv:
- iommu-ctx@2000 {
- compatible = "qcom,msm-iommu-v1-ns";
- reg = <0x2000 0x1000>;
- interrupts = <GIC_SPI 242 IRQ_TYPE_LEVEL_HIGH>;
- };
- };
-
- ...
-
- venus: video-codec@1d00000 {
- ...
- iommus = <&apps_iommu 5>;
- };
-
- mdp: mdp@1a01000 {
- ...
- iommus = <&apps_iommu 4>;
- };
-
- gpu@1c00000 {
- ...
- iommus = <&gpu_iommu 1>, <&gpu_iommu 2>;
- };
diff --git a/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml b/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml
new file mode 100644
index 000000000000..93a489025317
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/qcom,iommu.yaml
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iommu/qcom,iommu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Technologies legacy IOMMU implementations
+
+maintainers:
+ - Konrad Dybcio <konradybcio@kernel.org>
+
+description: |
+ Qualcomm "B" family devices which are not compatible with arm-smmu have
+ a similar looking IOMMU, but without access to the global register space
+ and optionally requiring additional configuration to route context IRQs
+ to non-secure vs secure interrupt line.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - qcom,msm8916-iommu
+ - qcom,msm8917-iommu
+ - qcom,msm8937-iommu
+ - qcom,msm8953-iommu
+ - const: qcom,msm-iommu-v1
+ - items:
+ - enum:
+ - qcom,msm8953-iommu
+ - qcom,msm8976-iommu
+ - const: qcom,msm-iommu-v2
+
+ clocks:
+ minItems: 2
+ items:
+ - description: Clock required for IOMMU register group access
+ - description: Clock required for underlying bus access
+ - description: Clock required for Translation Buffer Unit access
+
+ clock-names:
+ minItems: 2
+ items:
+ - const: iface
+ - const: bus
+ - const: tbu
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ ranges: true
+
+ qcom,iommu-secure-id:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The SCM secure ID of the IOMMU instance.
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ '#iommu-cells':
+ const: 1
+
+patternProperties:
+ "^iommu-ctx@[0-9a-f]+$":
+ type: object
+ additionalProperties: false
+ properties:
+ compatible:
+ enum:
+ - qcom,msm-iommu-v1-ns
+ - qcom,msm-iommu-v1-sec
+ - qcom,msm-iommu-v2-ns
+ - qcom,msm-iommu-v2-sec
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ qcom,ctx-asid:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The ASID number associated to the context bank.
+
+ required:
+ - compatible
+ - interrupts
+ - reg
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - ranges
+ - '#address-cells'
+ - '#size-cells'
+ - '#iommu-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-msm8916.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ apps_iommu: iommu@1e20000 {
+ compatible = "qcom,msm8916-iommu", "qcom,msm-iommu-v1";
+ reg = <0x01ef0000 0x3000>;
+ clocks = <&gcc GCC_SMMU_CFG_CLK>,
+ <&gcc GCC_APSS_TCU_CLK>;
+ clock-names = "iface", "bus";
+ qcom,iommu-secure-id = <17>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ #iommu-cells = <1>;
+ ranges = <0 0x01e20000 0x40000>;
+
+ /* mdp_0: */
+ iommu-ctx@4000 {
+ compatible = "qcom,msm-iommu-v1-ns";
+ reg = <0x4000 0x1000>;
+ interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iommu/qcom,tbu.yaml b/Documentation/devicetree/bindings/iommu/qcom,tbu.yaml
new file mode 100644
index 000000000000..82dfe935573e
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/qcom,tbu.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iommu/qcom,tbu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm TBU (Translation Buffer Unit)
+
+maintainers:
+ - Georgi Djakov <quic_c_gdjako@quicinc.com>
+
+description:
+ The Qualcomm SMMU500 implementation consists of TCU and TBU. The TBU contains
+ a Translation Lookaside Buffer (TLB) that caches page tables. TBUs provides
+ debug features to trace and trigger debug transactions. There are multiple TBU
+ instances with each client core.
+
+properties:
+ compatible:
+ enum:
+ - qcom,sc7280-tbu
+ - qcom,sdm845-tbu
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interconnects:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ qcom,stream-id-range:
+ description: |
+ Phandle of a SMMU device and Stream ID range (address and size) that
+ is assigned by the TBU
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle of a smmu node
+ - description: stream id base address
+ - description: stream id size
+
+required:
+ - compatible
+ - reg
+ - qcom,stream-id-range
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-sdm845.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interconnect/qcom,sdm845.h>
+
+ tbu@150e1000 {
+ compatible = "qcom,sdm845-tbu";
+ reg = <0x150e1000 0x1000>;
+ clocks = <&gcc GCC_AGGRE_NOC_PCIE_TBU_CLK>;
+ interconnects = <&system_noc MASTER_GNOC_SNOC QCOM_ICC_TAG_ACTIVE_ONLY
+ &config_noc SLAVE_IMEM_CFG QCOM_ICC_TAG_ACTIVE_ONLY>;
+ power-domains = <&gcc HLOS1_VOTE_AGGRE_NOC_MMU_PCIE_TBU_GDSC>;
+ qcom,stream-id-range = <&apps_smmu 0x1c00 0x400>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml
index 02c69a95c332..0acaa2bcec08 100644
--- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml
+++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml
@@ -29,6 +29,7 @@ properties:
- renesas,ipmmu-r8a7793 # R-Car M2-N
- renesas,ipmmu-r8a7794 # R-Car E2
- const: renesas,ipmmu-vmsa # R-Mobile APE6 or R-Car Gen2 or RZ/G1
+
- items:
- enum:
- renesas,ipmmu-r8a774a1 # RZ/G2M
@@ -44,6 +45,14 @@ properties:
- renesas,ipmmu-r8a77990 # R-Car E3
- renesas,ipmmu-r8a77995 # R-Car D3
+ - items:
+ - enum:
+ - renesas,ipmmu-r8a779a0 # R-Car V3U
+ - renesas,ipmmu-r8a779f0 # R-Car S4-8
+ - renesas,ipmmu-r8a779g0 # R-Car V4H
+ - renesas,ipmmu-r8a779h0 # R-Car V4M
+ - const: renesas,rcar-gen4-ipmmu-vmsa # R-Car Gen4
+
reg:
maxItems: 1
@@ -65,11 +74,17 @@ properties:
renesas,ipmmu-main:
$ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - minItems: 1
+ items:
+ - description: phandle to main IPMMU
+ - description:
+ The interrupt bit number associated with the particular cache
+ IPMMU device. If present, the interrupt bit number needs to match
+ the main IPMMU IMSSTR register. Only used by cache IPMMU
+ instances.
description:
- Reference to the main IPMMU phandle plus 1 cell. The cell is
- the interrupt bit number associated with the particular cache IPMMU
- device. The interrupt bit number needs to match the main IPMMU IMSSTR
- register. Only used by cache IPMMU instances.
+ Reference to the main IPMMU.
required:
- compatible
@@ -95,6 +110,22 @@ allOf:
required:
- power-domains
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,rcar-gen4-ipmmu-vmsa
+ then:
+ properties:
+ renesas,ipmmu-main:
+ items:
+ - maxItems: 1
+ else:
+ properties:
+ renesas,ipmmu-main:
+ items:
+ - minItems: 2
+
examples:
- |
#include <dt-bindings/clock/r8a7791-cpg-mssr.h>
diff --git a/Documentation/devicetree/bindings/iommu/riscv,iommu.yaml b/Documentation/devicetree/bindings/iommu/riscv,iommu.yaml
new file mode 100644
index 000000000000..d4838c3b3741
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/riscv,iommu.yaml
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iommu/riscv,iommu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RISC-V IOMMU Architecture Implementation
+
+maintainers:
+ - Tomasz Jeznach <tjeznach@rivosinc.com>
+
+description: |
+ The RISC-V IOMMU provides memory address translation and isolation for
+ input and output devices, supporting per-device translation context,
+ shared process address spaces including the ATS and PRI components of
+ the PCIe specification, two stage address translation and MSI remapping.
+ It supports identical translation table format to the RISC-V address
+ translation tables with page level access and protection attributes.
+ Hardware uses in-memory command and fault reporting queues with wired
+ interrupt or MSI notifications.
+
+ Visit https://github.com/riscv-non-isa/riscv-iommu for more details.
+
+ For information on assigning RISC-V IOMMU to its peripheral devices,
+ see generic IOMMU bindings.
+
+properties:
+ # For PCIe IOMMU hardware compatible property should contain the vendor
+ # and device ID according to the PCI Bus Binding specification.
+ # Since PCI provides built-in identification methods, compatible is not
+ # actually required. For non-PCIe hardware implementations 'riscv,iommu'
+ # should be specified along with 'reg' property providing MMIO location.
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - qemu,riscv-iommu
+ - const: riscv,iommu
+ - items:
+ - enum:
+ - pci1efd,edf1
+ - const: riscv,pci-iommu
+
+ reg:
+ maxItems: 1
+ description:
+ For non-PCI devices this represents base address and size of for the
+ IOMMU memory mapped registers interface.
+ For PCI IOMMU hardware implementation this should represent an address
+ of the IOMMU, as defined in the PCI Bus Binding reference.
+
+ '#iommu-cells':
+ const: 1
+ description:
+ The single cell describes the requester id emitted by a master to the
+ IOMMU.
+
+ interrupts:
+ minItems: 1
+ maxItems: 4
+ description:
+ Wired interrupt vectors available for RISC-V IOMMU to notify the
+ RISC-V HARTS. The cause to interrupt vector is software defined
+ using IVEC IOMMU register.
+
+ msi-parent: true
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - '#iommu-cells'
+
+additionalProperties: false
+
+examples:
+ - |+
+ /* Example 1 (IOMMU device with wired interrupts) */
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ iommu1: iommu@1bccd000 {
+ compatible = "qemu,riscv-iommu", "riscv,iommu";
+ reg = <0x1bccd000 0x1000>;
+ interrupt-parent = <&aplic_smode>;
+ interrupts = <32 IRQ_TYPE_LEVEL_HIGH>,
+ <33 IRQ_TYPE_LEVEL_HIGH>,
+ <34 IRQ_TYPE_LEVEL_HIGH>,
+ <35 IRQ_TYPE_LEVEL_HIGH>;
+ #iommu-cells = <1>;
+ };
+
+ /* Device with two IOMMU device IDs, 0 and 7 */
+ master1 {
+ iommus = <&iommu1 0>, <&iommu1 7>;
+ };
+
+ - |+
+ /* Example 2 (IOMMU device with shared wired interrupt) */
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ iommu2: iommu@1bccd000 {
+ compatible = "qemu,riscv-iommu", "riscv,iommu";
+ reg = <0x1bccd000 0x1000>;
+ interrupt-parent = <&aplic_smode>;
+ interrupts = <32 IRQ_TYPE_LEVEL_HIGH>;
+ #iommu-cells = <1>;
+ };
+
+ - |+
+ /* Example 3 (IOMMU device with MSIs) */
+ iommu3: iommu@1bcdd000 {
+ compatible = "qemu,riscv-iommu", "riscv,iommu";
+ reg = <0x1bccd000 0x1000>;
+ msi-parent = <&imsics_smode>;
+ #iommu-cells = <1>;
+ };
+
+ - |+
+ /* Example 4 (IOMMU PCIe device with MSIs) */
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ pcie@30000000 {
+ device_type = "pci";
+ #address-cells = <3>;
+ #size-cells = <2>;
+ reg = <0x0 0x30000000 0x0 0x1000000>;
+ ranges = <0x02000000 0x0 0x41000000 0x0 0x41000000 0x0 0x0f000000>;
+
+ /*
+ * The IOMMU manages all functions in this PCI domain except
+ * itself. Omit BDF 00:01.0.
+ */
+ iommu-map = <0x0 &iommu0 0x0 0x8>,
+ <0x9 &iommu0 0x9 0xfff7>;
+
+ /* The IOMMU programming interface uses slot 00:01.0 */
+ iommu0: iommu@1,0 {
+ compatible = "pci1efd,edf1", "riscv,pci-iommu";
+ reg = <0x800 0 0 0 0>;
+ #iommu-cells = <1>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/iommu/rockchip,iommu.yaml b/Documentation/devicetree/bindings/iommu/rockchip,iommu.yaml
index d2e28a9e3545..6ce41d11ff5e 100644
--- a/Documentation/devicetree/bindings/iommu/rockchip,iommu.yaml
+++ b/Documentation/devicetree/bindings/iommu/rockchip,iommu.yaml
@@ -19,23 +19,27 @@ description: |+
properties:
compatible:
- enum:
- - rockchip,iommu
- - rockchip,rk3568-iommu
+ oneOf:
+ - enum:
+ - rockchip,iommu
+ - rockchip,rk3568-iommu
+ - items:
+ - enum:
+ - rockchip,rk3576-iommu
+ - rockchip,rk3588-iommu
+ - const: rockchip,rk3568-iommu
reg:
items:
- description: configuration registers for MMU instance 0
- description: configuration registers for MMU instance 1
minItems: 1
- maxItems: 2
interrupts:
items:
- description: interruption for MMU instance 0
- description: interruption for MMU instance 1
minItems: 1
- maxItems: 2
clocks:
items:
diff --git a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.yaml b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.yaml
index af51b91c893e..672a0beea600 100644
--- a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.yaml
+++ b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.yaml
@@ -86,16 +86,6 @@ examples:
- |
#include <dt-bindings/clock/exynos5250.h>
- gsc_0: scaler@13e00000 {
- compatible = "samsung,exynos5-gsc";
- reg = <0x13e00000 0x1000>;
- interrupts = <0 85 0>;
- power-domains = <&pd_gsc>;
- clocks = <&clock CLK_GSCL0>;
- clock-names = "gscl";
- iommus = <&sysmmu_gsc0>;
- };
-
sysmmu_gsc0: iommu@13e80000 {
compatible = "samsung,exynos-sysmmu";
reg = <0x13E80000 0x1000>;
@@ -107,4 +97,3 @@ examples:
power-domains = <&pd_gsc>;
#iommu-cells = <0>;
};
-
diff --git a/Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml b/Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml
new file mode 100644
index 000000000000..3528b81daa25
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/xen,grant-dma.yaml
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iommu/xen,grant-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xen specific IOMMU for virtualized devices (e.g. virtio)
+
+maintainers:
+ - Stefano Stabellini <sstabellini@kernel.org>
+
+description:
+ The Xen IOMMU represents the Xen grant table interface. Grant mappings
+ are to be used with devices connected to the Xen IOMMU using the "iommus"
+ property, which also specifies the ID of the backend domain.
+ The binding is required to restrict memory access using Xen grant mappings.
+
+properties:
+ compatible:
+ const: xen,grant-dma
+
+ '#iommu-cells':
+ const: 1
+ description:
+ The single cell is the domid (domain ID) of the domain where the backend
+ is running.
+
+required:
+ - compatible
+ - "#iommu-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ iommu {
+ compatible = "xen,grant-dma";
+ #iommu-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt
deleted file mode 100644
index 028268fd99ee..000000000000
--- a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* Aspeed BT (Block Transfer) IPMI interface
-
-The Aspeed SOCs (AST2400 and AST2500) are commonly used as BMCs
-(BaseBoard Management Controllers) and the BT interface can be used to
-perform in-band IPMI communication with their host.
-
-Required properties:
-
-- compatible : should be one of
- "aspeed,ast2400-ibt-bmc"
- "aspeed,ast2500-ibt-bmc"
-- reg: physical address and size of the registers
-
-Optional properties:
-
-- interrupts: interrupt generated by the BT interface. without an
- interrupt, the driver will operate in poll mode.
-
-Example:
-
- ibt@1e789140 {
- compatible = "aspeed,ast2400-ibt-bmc";
- reg = <0x1e789140 0x18>;
- interrupts = <8>;
- };
diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.yaml b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.yaml
new file mode 100644
index 000000000000..c4f7cdbbe16b
--- /dev/null
+++ b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.yaml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ipmi/aspeed,ast2400-ibt-bmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aspeed Block Transfer (BT) IPMI interface
+
+maintainers:
+ - Joel Stanley <joel@jms.id.au>
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-ibt-bmc
+ - aspeed,ast2500-ibt-bmc
+ - aspeed,ast2600-ibt-bmc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/aspeed-clock.h>
+
+ bt@1e789140 {
+ compatible = "aspeed,ast2400-ibt-bmc";
+ reg = <0x1e789140 0x18>;
+ interrupts = <8>;
+ clocks = <&syscon ASPEED_CLK_GATE_LCLK>;
+ };
diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml
index 4ff6fabfcb30..610c79863208 100644
--- a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml
+++ b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-kcs-bmc.yaml
@@ -40,8 +40,11 @@ properties:
- description: ODR register
- description: STR register
+ clocks:
+ maxItems: 1
+
aspeed,lpc-io-reg:
- $ref: '/schemas/types.yaml#/definitions/uint32-array'
+ $ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 1
maxItems: 2
description: |
@@ -50,7 +53,7 @@ properties:
status address may be optionally provided.
aspeed,lpc-interrupts:
- $ref: "/schemas/types.yaml#/definitions/uint32-array"
+ $ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 2
maxItems: 2
description: |
@@ -63,12 +66,12 @@ properties:
kcs_chan:
deprecated: true
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description: The LPC channel number in the controller
kcs_addr:
deprecated: true
- $ref: '/schemas/types.yaml#/definitions/uint32'
+ $ref: /schemas/types.yaml#/definitions/uint32
description: The host CPU IO map address
required:
diff --git a/Documentation/devicetree/bindings/ipmi/ipmb-dev.yaml b/Documentation/devicetree/bindings/ipmi/ipmb-dev.yaml
new file mode 100644
index 000000000000..8b0d71901195
--- /dev/null
+++ b/Documentation/devicetree/bindings/ipmi/ipmb-dev.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ipmi/ipmb-dev.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: The Intelligent Platform Management Bus(IPMB) Device
+
+description: |
+ The IPMB is an I2C bus which provides interconnection between a Baseboard
+ Management Controller(BMC) and chassis electronics. The BMC sends IPMI
+ requests to intelligent controllers like Satellite Management Controller(MC)
+ devices via IPMB and the device sends responses back to the BMC.
+ This device uses an I2C slave device to send and receive IPMB messages,
+ either on a BMC or other MC. A miscellaneous device provices a user space
+ program to communicate with the kernel and the backend device. Some IPMB
+ devices only support the I2C protocol and not the SMB protocol.
+
+ IPMB communications protocol Specification V1.0
+ https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmp-spec-v1.0.pdf
+
+maintainers:
+ - Ninad Palsule <ninad@linux.ibm.com>
+
+properties:
+ compatible:
+ enum:
+ - ipmb-dev
+
+ reg:
+ maxItems: 1
+
+ i2c-protocol:
+ description:
+ Use I2C block transfer instead of SMBUS block transfer.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/i2c/i2c.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ipmb-dev@10 {
+ compatible = "ipmb-dev";
+ reg = <(0x10 | I2C_OWN_SLAVE_ADDRESS)>;
+ i2c-protocol;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml b/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml
new file mode 100644
index 000000000000..52647bff31af
--- /dev/null
+++ b/Documentation/devicetree/bindings/ipmi/ipmi-ipmb.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ipmi/ipmi-ipmb.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IPMI IPMB device
+
+description: IPMI IPMB device bindings
+
+maintainers:
+ - Corey Minyard <cminyard@mvista.com>
+
+properties:
+ compatible:
+ enum:
+ - ipmi-ipmb
+
+ device_type:
+ items:
+ - const: ipmi
+
+ reg:
+ maxItems: 1
+
+ bmcaddr:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: The address of the BMC on the IPMB bus. Defaults to 0x20.
+
+ retry-time:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Time between retries of sends, in milliseconds. Defaults to 250.
+
+ max-retries:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of retries before a failure is declared. Defaults to 1.
+
+ slave-dev:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: |
+ The slave i2c device. If not present, the main device is used. This
+ lets you use two devices on the IPMB, one for master and one for slave,
+ in case you have a slave device that can only be a slave. The slave
+ will receive messages and the master will transmit.
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ipmi-ipmb@40 {
+ compatible = "ipmi-ipmb";
+ device_type = "ipmi";
+ reg = <0x40>;
+ bmcaddr = /bits/ 8 <0x20>;
+ retry-time = <250>;
+ max-retries = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml b/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml
index 898e3267893a..4bffa3d86128 100644
--- a/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml
+++ b/Documentation/devicetree/bindings/ipmi/ipmi-smic.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/ipmi/ipmi-smic.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: IPMI device bindings
+title: IPMI device
description: IPMI device bindings
@@ -20,7 +20,7 @@ properties:
device_type:
items:
- - const: "ipmi"
+ - const: ipmi
reg:
maxItems: 1
diff --git a/Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt b/Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt
deleted file mode 100644
index 352f5e9c759b..000000000000
--- a/Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-* Nuvoton NPCM7xx KCS (Keyboard Controller Style) IPMI interface
-
-The Nuvoton SOCs (NPCM7xx) are commonly used as BMCs
-(Baseboard Management Controllers) and the KCS interface can be
-used to perform in-band IPMI communication with their host.
-
-Required properties:
-- compatible : should be one of
- "nuvoton,npcm750-kcs-bmc"
-- interrupts : interrupt generated by the controller
-- kcs_chan : The KCS channel number in the controller
-
-Example:
-
- lpc_kcs: lpc_kcs@f0007000 {
- compatible = "nuvoton,npcm750-lpc-kcs", "simple-mfd", "syscon";
- reg = <0xf0007000 0x40>;
- reg-io-width = <1>;
-
- #address-cells = <1>;
- #size-cells = <1>;
- ranges = <0x0 0xf0007000 0x40>;
-
- kcs1: kcs1@0 {
- compatible = "nuvoton,npcm750-kcs-bmc";
- reg = <0x0 0x40>;
- interrupts = <0 9 4>;
- kcs_chan = <1>;
- status = "disabled";
- };
-
- kcs2: kcs2@0 {
- compatible = "nuvoton,npcm750-kcs-bmc";
- reg = <0x0 0x40>;
- interrupts = <0 9 4>;
- kcs_chan = <2>;
- status = "disabled";
- };
- };
diff --git a/Documentation/devicetree/bindings/ipmi/nuvoton,npcm750-kcs-bmc.yaml b/Documentation/devicetree/bindings/ipmi/nuvoton,npcm750-kcs-bmc.yaml
new file mode 100644
index 000000000000..fc5df1c5e3bc
--- /dev/null
+++ b/Documentation/devicetree/bindings/ipmi/nuvoton,npcm750-kcs-bmc.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ipmi/nuvoton,npcm750-kcs-bmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton NPCM KCS BMC
+
+maintainers:
+ - Avi Fishman <avifishman70@gmail.com>
+ - Tomer Maimon <tmaimon77@gmail.com>
+ - Tali Perry <tali.perry1@gmail.com>
+
+description:
+ The Nuvoton SOCs (NPCM) are commonly used as BMCs (Baseboard Management
+ Controllers) and the KCS interface can be used to perform in-band IPMI
+ communication with their host.
+
+properties:
+ compatible:
+ oneOf:
+ - const: nuvoton,npcm750-kcs-bmc
+ - items:
+ - enum:
+ - nuvoton,npcm845-kcs-bmc
+ - const: nuvoton,npcm750-kcs-bmc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ kcs_chan:
+ description: The KCS channel number in the controller
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 1
+ maximum: 3
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - kcs_chan
+
+additionalProperties: false
+
+examples:
+ - |
+ kcs@0 {
+ compatible = "nuvoton,npcm750-kcs-bmc";
+ reg = <0x0 0x40>;
+ interrupts = <9 4>;
+ kcs_chan = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml b/Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml
new file mode 100644
index 000000000000..02b662d780bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/ipmi/ssif-bmc.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ipmi/ssif-bmc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SSIF IPMI BMC interface
+
+description: SSIF IPMI BMC device bindings
+
+maintainers:
+ - Quan Nguyen <quan@os.amperecomputing.com>
+
+properties:
+ compatible:
+ enum:
+ - ssif-bmc
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ssif-bmc@10 {
+ compatible = "ssif-bmc";
+ reg = <0x10>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/allwinner,sun50i-a100-ledc.yaml b/Documentation/devicetree/bindings/leds/allwinner,sun50i-a100-ledc.yaml
new file mode 100644
index 000000000000..760cb336dccb
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/allwinner,sun50i-a100-ledc.yaml
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/allwinner,sun50i-a100-ledc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A100 LED Controller
+
+maintainers:
+ - Samuel Holland <samuel@sholland.org>
+
+description:
+ The LED controller found in Allwinner sunxi SoCs uses a one-wire serial
+ interface to drive up to 1024 RGB LEDs.
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun50i-a100-ledc
+ - items:
+ - enum:
+ - allwinner,sun20i-d1-ledc
+ - allwinner,sun50i-r329-ledc
+ - const: allwinner,sun50i-a100-ledc
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus clock
+ - description: Module clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+
+ resets:
+ maxItems: 1
+
+ dmas:
+ maxItems: 1
+ description: TX DMA channel
+
+ dma-names:
+ const: tx
+
+ allwinner,pixel-format:
+ description: Pixel format (subpixel transmission order), default is "grb"
+ enum:
+ - bgr
+ - brg
+ - gbr
+ - grb
+ - rbg
+ - rgb
+
+ allwinner,t0h-ns:
+ default: 336
+ description: Length of high pulse when transmitting a "0" bit
+
+ allwinner,t0l-ns:
+ default: 840
+ description: Length of low pulse when transmitting a "0" bit
+
+ allwinner,t1h-ns:
+ default: 882
+ description: Length of high pulse when transmitting a "1" bit
+
+ allwinner,t1l-ns:
+ default: 294
+ description: Length of low pulse when transmitting a "1" bit
+
+ allwinner,treset-ns:
+ default: 300000
+ description: Minimum delay between transmission frames
+
+patternProperties:
+ "^multi-led@[0-9a-f]+$":
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+ properties:
+ reg:
+ minimum: 0
+ maximum: 1023
+ description: Index of the LED in the series (must be contiguous)
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/leds/common.h>
+
+ ledc: led-controller@2008000 {
+ compatible = "allwinner,sun20i-d1-ledc",
+ "allwinner,sun50i-a100-ledc";
+ reg = <0x2008000 0x400>;
+ interrupts = <36 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu 12>, <&ccu 34>;
+ clock-names = "bus", "mod";
+ resets = <&ccu 12>;
+ dmas = <&dma 42>;
+ dma-names = "tx";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ multi-led@0 {
+ reg = <0x0>;
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_INDICATOR;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/ams,as3645a.txt b/Documentation/devicetree/bindings/leds/ams,as3645a.txt
deleted file mode 100644
index 4af2987b25e9..000000000000
--- a/Documentation/devicetree/bindings/leds/ams,as3645a.txt
+++ /dev/null
@@ -1,85 +0,0 @@
-Analog devices AS3645A device tree bindings
-
-The AS3645A flash LED controller can drive two LEDs, one high current
-flash LED and one indicator LED. The high current flash LED can be
-used in torch mode as well.
-
-Ranges below noted as [a, b] are closed ranges between a and b, i.e. a
-and b are included in the range.
-
-Please also see common.txt in the same directory.
-
-
-Required properties
-===================
-
-compatible : Must be "ams,as3645a".
-reg : The I2C address of the device. Typically 0x30.
-#address-cells : 1
-#size-cells : 0
-
-
-Required properties of the flash child node (0)
-===============================================
-
-reg: 0
-flash-timeout-us: Flash timeout in microseconds. The value must be in
- the range [100000, 850000] and divisible by 50000.
-flash-max-microamp: Maximum flash current in microamperes. Has to be
- in the range between [200000, 500000] and
- divisible by 20000.
-led-max-microamp: Maximum torch (assist) current in microamperes. The
- value must be in the range between [20000, 160000] and
- divisible by 20000.
-ams,input-max-microamp: Maximum flash controller input current. The
- value must be in the range [1250000, 2000000]
- and divisible by 50000.
-
-
-Optional properties of the flash child node
-===========================================
-
-function : See Documentation/devicetree/bindings/leds/common.txt.
-color : See Documentation/devicetree/bindings/leds/common.txt.
-label : See Documentation/devicetree/bindings/leds/common.txt (deprecated).
-
-
-Required properties of the indicator child node (1)
-===================================================
-
-reg: 1
-led-max-microamp: Maximum indicator current. The allowed values are
- 2500, 5000, 7500 and 10000.
-
-Optional properties of the indicator child node
-===============================================
-
-function : See Documentation/devicetree/bindings/leds/common.txt.
-color : See Documentation/devicetree/bindings/leds/common.txt.
-label : See Documentation/devicetree/bindings/leds/common.txt (deprecated).
-
-
-Example
-=======
-
-#include <dt-bindings/leds/common.h>
-
- as3645a@30 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x30>;
- compatible = "ams,as3645a";
- led@0 {
- reg = <0x0>;
- flash-timeout-us = <150000>;
- flash-max-microamp = <320000>;
- led-max-microamp = <60000>;
- ams,input-max-microamp = <1750000>;
- function = LED_FUNCTION_FLASH;
- };
- led@1 {
- reg = <0x1>;
- led-max-microamp = <10000>;
- function = LED_FUNCTION_INDICATOR;
- };
- };
diff --git a/Documentation/devicetree/bindings/leds/ams,as3645a.yaml b/Documentation/devicetree/bindings/leds/ams,as3645a.yaml
new file mode 100644
index 000000000000..250a4b275d8a
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/ams,as3645a.yaml
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/ams,as3645a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AS3645A LED Controller
+
+maintainers:
+ - Sakari Ailus <sakari.ailus@iki.fi>
+
+description:
+ The AS3645A flash LED controller can drive two LEDs, one
+ high current flash LED and one indicator LED. The high
+ current flash LED can be used in torch mode as well.
+
+properties:
+ compatible:
+ const: ams,as3645a
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ led@0:
+ description: led0 describes the 'flash' feature
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 0
+
+ flash-timeout-us:
+ minimum: 100000
+ maximum: 850000
+ multipleOf: 50000
+
+ flash-max-microamp:
+ minimum: 200000
+ maximum: 500000
+ multipleOf: 20000
+
+ led-max-microamp:
+ minimum: 20000
+ maximum: 160000
+ multipleOf: 20000
+ description:
+ Maximum current when in torch (assist) mode.
+
+ ams,input-max-microamp:
+ minimum: 1250000
+ maximum: 2000000
+ multipleOf: 50000
+
+ required:
+ - reg
+ - flash-timeout-us
+ - flash-max-microamp
+ - led-max-microamp
+ - ams,input-max-microamp
+
+ led@1:
+ description: led1 describes the 'indicator' feature
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ const: 1
+
+ led-max-microamp:
+ enum:
+ - 2500
+ - 5000
+ - 7500
+ - 10000
+ description:
+ Maximum indicator current.
+
+ required:
+ - reg
+ - led-max-microamp
+
+required:
+ - compatible
+ - reg
+ - "#size-cells"
+ - "#address-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c{
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@30 {
+ compatible = "ams,as3645a";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x30>;
+
+ led@0 {
+ reg = <0>;
+ flash-timeout-us = <150000>;
+ flash-max-microamp = <320000>;
+ led-max-microamp = <60000>;
+ ams,input-max-microamp = <1750000>;
+ function = LED_FUNCTION_FLASH;
+ };
+
+ led@1 {
+ reg = <1>;
+ led-max-microamp = <10000>;
+ function = LED_FUNCTION_INDICATOR;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/awinic,aw200xx.yaml b/Documentation/devicetree/bindings/leds/awinic,aw200xx.yaml
new file mode 100644
index 000000000000..17e971903ee9
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/awinic,aw200xx.yaml
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/awinic,aw200xx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AWINIC AW200XX LED
+
+maintainers:
+ - Martin Kurbanov <mmkurbanov@sberdevices.ru>
+
+description: |
+ It is a matrix LED driver programmed via an I2C interface. Devices have
+ a set of individually controlled leds and support 3 pattern controllers
+ for auto breathing or group dimming control. Supported devices:
+ - AW20036 (3x12) 36 LEDs
+ - AW20054 (6x9) 54 LEDs
+ - AW20072 (6x12) 72 LEDs
+ - AW20108 (9x12) 108 LEDs
+
+ For more product information please see the link below:
+ aw20036 - https://www.awinic.com/en/productDetail/AW20036QNR#tech-docs
+ aw20054 - https://www.awinic.com/en/productDetail/AW20054QNR#tech-docs
+ aw20072 - https://www.awinic.com/en/productDetail/AW20072QNR#tech-docs
+ aw20108 - https://www.awinic.com/en/productDetail/AW20108QNR#tech-docs
+
+properties:
+ compatible:
+ enum:
+ - awinic,aw20036
+ - awinic,aw20054
+ - awinic,aw20072
+ - awinic,aw20108
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ enable-gpios:
+ maxItems: 1
+
+patternProperties:
+ "^led@[0-9a-f]+$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description:
+ LED number
+ maxItems: 1
+
+ led-max-microamp:
+ default: 9780
+ description: |
+ Note that a driver will take the minimum of all LED limits
+ since the chip has a single global setting.
+ The maximum output current of each LED is calculated by the
+ following formula:
+ IMAXled = 160000 * (592 / 600.5) * (1 / max-current-switch-number)
+ And the minimum output current formula:
+ IMINled = 3300 * (592 / 600.5) * (1 / max-current-switch-number)
+ where max-current-switch-number is determined by led configuration
+ and depends on how leds are physically connected to the led driver.
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: awinic,aw20036
+ then:
+ patternProperties:
+ "^led@[0-9a-f]+$":
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 36
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: awinic,aw20054
+ then:
+ patternProperties:
+ "^led@[0-9a-f]+$":
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 54
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: awinic,aw20072
+ then:
+ patternProperties:
+ "^led@[0-9a-f]+$":
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 72
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: awinic,aw20108
+ then:
+ patternProperties:
+ "^led@[0-9a-f]+$":
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 108
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@3a {
+ compatible = "awinic,aw20036";
+ reg = <0x3a>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ enable-gpios = <&gpio 3 GPIO_ACTIVE_HIGH>;
+
+ led@0 {
+ reg = <0x0>;
+ color = <LED_COLOR_ID_RED>;
+ led-max-microamp = <9780>;
+ };
+
+ led@1 {
+ reg = <0x1>;
+ color = <LED_COLOR_ID_GREEN>;
+ led-max-microamp = <9780>;
+ };
+
+ led@2 {
+ reg = <0x2>;
+ color = <LED_COLOR_ID_BLUE>;
+ led-max-microamp = <9780>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/backlight/apple,dwi-bl.yaml b/Documentation/devicetree/bindings/leds/backlight/apple,dwi-bl.yaml
new file mode 100644
index 000000000000..29caeb356e6f
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/apple,dwi-bl.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/apple,dwi-bl.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple DWI 2-Wire Interface Backlight Controller
+
+maintainers:
+ - Nick Chan <towinchenmi@gmail.com>
+
+description:
+ Apple SoCs contain a 2-wire interface called DWI. On some Apple iPhones,
+ iPads and iPod touches with a LCD display, 1-2 backlight controllers
+ are connected via DWI. Interfacing with DWI controls all backlight
+ controllers at the same time. As such, the backlight controllers are
+ treated as a single controller regardless of the underlying
+ configuration.
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - apple,s5l8960x-dwi-bl
+ - apple,t7000-dwi-bl
+ - apple,s8000-dwi-bl
+ - apple,t8010-dwi-bl
+ - apple,t8015-dwi-bl
+ - const: apple,dwi-bl
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ dwi_bl: backlight@20e200010 {
+ compatible = "apple,s5l8960x-dwi-bl", "apple,dwi-bl";
+ reg = <0x2 0x0e200010 0x0 0x8>;
+ power-domains = <&ps_dwi>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/backlight/arc,arc2c0608.yaml b/Documentation/devicetree/bindings/leds/backlight/arc,arc2c0608.yaml
new file mode 100644
index 000000000000..786beced5590
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/arc,arc2c0608.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/arc,arc2c0608.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ArcticSand arc2c0608 LED driver
+
+description: |
+ The ArcticSand arc2c0608 LED driver provides ultra
+ efficient notebook backlighting. Optional properties not
+ specified will default to values in IC EPROM.
+
+ Datasheet:
+ https://www.murata.com/-/media/webrenewal/products/power/power-semiconductor/overview/lineup/led-boost/arc2/arc2c0608.ashx.
+
+maintainers:
+ - Brian Dodge <bdodge@arcticsand.com>
+
+allOf:
+ - $ref: /schemas/leds/common.yaml
+
+properties:
+ compatible:
+ const: arc,arc2c0608
+
+ reg:
+ maxItems: 1
+
+ default-brightness:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 4095
+
+ led-sources:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description: List of enabled channels
+ items:
+ enum: [0, 1, 2, 3, 4, 5]
+ minItems: 1
+ uniqueItems: true
+
+ arc,led-config-0:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Fading speed (period between intensity
+ steps)
+
+ arc,led-config-1:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: If set, sets ILED_CONFIG register. Used for
+ fine tuning the maximum LED current.
+
+ arc,dim-freq:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: PWM mode frequency setting (bits [3:0] used)
+
+ arc,comp-config:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Setting for register CONFIG_COMP which
+ controls internal resitances, feed forward freqs,
+ and initial VOUT at startup. Consult the datasheet.
+
+ arc,filter-config:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: RC and PWM Filter settings.
+ Bit Assignment
+ 7654 3 2 1 0
+ xxxx RCF1 RCF0 PWM1 PWM0
+ RCF statuses PWM Filter Statues
+ 00 = OFF (default) 00 = OFF (default)
+ 01 = LOW 01 = 2 STEPS
+ 10 - MEDIUM 10 = 4 STEPS
+ 11 = HIGH 11 = 8 STEPS
+
+ arc,trim-config:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Sets percentage increase of Maximum LED
+ Current.
+ 0x00 = 0% increase.
+ 0x20 = 20.2%.
+ 0x3F = 41.5%
+
+ label: true
+
+ linux,default-trigger: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@30 {
+ compatible = "arc,arc2c0608";
+ reg = <0x30>;
+ default-brightness = <500>;
+ label = "lcd-backlight";
+ linux,default-trigger = "backlight";
+ led-sources = <0 1 2 5>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/backlight/arcxcnn_bl.txt b/Documentation/devicetree/bindings/leds/backlight/arcxcnn_bl.txt
deleted file mode 100644
index 230abdefd6e7..000000000000
--- a/Documentation/devicetree/bindings/leds/backlight/arcxcnn_bl.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-Binding for ArcticSand arc2c0608 LED driver
-
-Required properties:
-- compatible: should be "arc,arc2c0608"
-- reg: slave address
-
-Optional properties:
-- default-brightness: brightness value on boot, value from: 0-4095
-- label: The name of the backlight device
- See Documentation/devicetree/bindings/leds/common.txt
-- led-sources: List of enabled channels from 0 to 5.
- See Documentation/devicetree/bindings/leds/common.txt
-
-- arc,led-config-0: setting for register ILED_CONFIG_0
-- arc,led-config-1: setting for register ILED_CONFIG_1
-- arc,dim-freq: PWM mode frequence setting (bits [3:0] used)
-- arc,comp-config: setting for register CONFIG_COMP
-- arc,filter-config: setting for register FILTER_CONFIG
-- arc,trim-config: setting for register IMAXTUNE
-
-Note: Optional properties not specified will default to values in IC EPROM
-
-Example:
-
-arc2c0608@30 {
- compatible = "arc,arc2c0608";
- reg = <0x30>;
- default-brightness = <500>;
- label = "lcd-backlight";
- linux,default-trigger = "backlight";
- led-sources = <0 1 2 5>;
-};
-
diff --git a/Documentation/devicetree/bindings/leds/backlight/awinic,aw99706.yaml b/Documentation/devicetree/bindings/leds/backlight/awinic,aw99706.yaml
new file mode 100644
index 000000000000..f48ce7a3434d
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/awinic,aw99706.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/awinic,aw99706.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Awinic AW99706 6-channel WLED Backlight Driver
+
+maintainers:
+ - Junjie Cao <caojunjie650@gmail.com>
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ const: awinic,aw99706
+
+ reg:
+ maxItems: 1
+
+ enable-gpios:
+ description: GPIO to use to enable/disable the backlight (HWEN pin).
+ maxItems: 1
+
+ awinic,dim-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: >
+ Select dimming mode of the device.
+ 0 = Bypass mode.
+ 1 = DC mode.
+ 2 = MIX mode(PWM at low brightness and DC at high brightness).
+ 3 = MIX-26k mode(MIX mode with different PWM frequency).
+ enum: [ 0, 1, 2, 3 ]
+ default: 1
+
+ awinic,sw-freq-hz:
+ description: Boost switching frequency in Hz.
+ enum: [ 300000, 400000, 500000, 600000, 660000, 750000, 850000, 1000000,
+ 1200000, 1330000, 1500000, 1700000 ]
+ default: 750000
+
+ awinic,sw-ilmt-microamp:
+ description: Switching current limitation in uA.
+ enum: [ 1500000, 2000000, 2500000, 3000000 ]
+ default: 3000000
+
+ awinic,iled-max-microamp:
+ description: Maximum LED current setting in uA.
+ minimum: 5000
+ maximum: 50000
+ multipleOf: 500
+ default: 20000
+
+ awinic,uvlo-thres-microvolt:
+ description: UVLO(Under Voltage Lock Out) in uV.
+ enum: [ 2200000, 5000000 ]
+ default: 2200000
+
+ awinic,ramp-ctl:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: >
+ Select ramp control and filter of the device.
+ 0 = Fade in/fade out.
+ 1 = Light filter.
+ 2 = Medium filter.
+ 3 = Heavy filter.
+ enum: [ 0, 1, 2, 3 ]
+ default: 2
+
+required:
+ - compatible
+ - reg
+ - enable-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@76 {
+ compatible = "awinic,aw99706";
+ reg = <0x76>;
+ enable-gpios = <&tlmm 88 GPIO_ACTIVE_HIGH>;
+ default-brightness = <2047>;
+ max-brightness = <4095>;
+ awinic,dim-mode = <1>;
+ awinic,sw-freq-hz = <750000>;
+ awinic,sw-ilmt-microamp = <3000000>;
+ awinic,uvlo-thres-microvolt = <2200000>;
+ awinic,iled-max-microamp = <20000>;
+ awinic,ramp-ctl = <2>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/backlight/common.yaml b/Documentation/devicetree/bindings/leds/backlight/common.yaml
index 702ba350d869..e0983e44934c 100644
--- a/Documentation/devicetree/bindings/leds/backlight/common.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/common.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Common backlight properties
maintainers:
- - Lee Jones <lee.jones@linaro.org>
+ - Lee Jones <lee@kernel.org>
- Daniel Thompson <daniel.thompson@linaro.org>
- Jingoo Han <jingoohan1@gmail.com>
@@ -33,4 +33,21 @@ properties:
due to restrictions in a specific system, such as mounting conditions.
$ref: /schemas/types.yaml#/definitions/uint32
+ brightness-levels:
+ description:
+ Array of distinct brightness levels. The levels must be in the range
+ accepted by the underlying LED device. Typically these are in the range
+ from 0 to 255, but any range starting at 0 will do, as long as they are
+ accepted by the LED.
+ The 0 value means a 0% of brightness (darkest/off), while the last value
+ in the array represents a full 100% brightness (brightest).
+ If this array is not provided, the driver default mapping is used.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ default-brightness-level:
+ description:
+ The default brightness level (index into the array defined by the
+ "brightness-levels" property).
+ $ref: /schemas/types.yaml#/definitions/uint32
+
additionalProperties: true
diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml
index 75cc569b9c55..584030b6b0b9 100644
--- a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/leds/backlight/gpio-backlight.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: gpio-backlight bindings
+title: gpio-backlight
maintainers:
- - Lee Jones <lee.jones@linaro.org>
+ - Lee Jones <lee@kernel.org>
- Daniel Thompson <daniel.thompson@linaro.org>
- Jingoo Han <jingoohan1@gmail.com>
diff --git a/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml
new file mode 100644
index 000000000000..b005065e0f48
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/kinetic,ktd2801.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Kinetic Technologies KTD2801 one-wire backlight
+
+maintainers:
+ - Duje Mihanović <duje.mihanovic@skole.hr>
+
+description: |
+ The Kinetic Technologies KTD2801 is a LED backlight driver controlled
+ by a single GPIO line. The driver can be controlled with a PWM signal
+ or by pulsing the GPIO line to set the backlight level. This is called
+ "ExpressWire".
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ const: kinetic,ktd2801
+
+ ctrl-gpios:
+ maxItems: 1
+
+ default-brightness: true
+ max-brightness: true
+
+required:
+ - compatible
+ - ctrl-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ backlight {
+ compatible = "kinetic,ktd2801";
+ ctrl-gpios = <&gpio 97 GPIO_ACTIVE_HIGH>;
+ max-brightness = <210>;
+ default-brightness = <100>;
+ };
diff --git a/Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml
new file mode 100644
index 000000000000..c914e1276982
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktz8866.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/kinetic,ktz8866.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Kinetic Technologies KTZ8866 backlight
+
+maintainers:
+ - Jianhua Lu <lujianhua000@gmail.com>
+
+description: |
+ The Kinetic Technologies KTZ8866 is a high efficiency 6-channels-current-sinks
+ led backlight with dual lcd bias power.
+ https://www.kinet-ic.com/ktz8866/
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ const: kinetic,ktz8866
+
+ reg:
+ maxItems: 1
+
+ vddpos-supply:
+ description: positive boost supply regulator.
+
+ vddneg-supply:
+ description: negative boost supply regulator.
+
+ enable-gpios:
+ description: GPIO to use to enable/disable the backlight (HWEN pin).
+ maxItems: 1
+
+ current-num-sinks:
+ description: number of the LED current sinks' channels.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [1, 2, 3, 4, 5, 6]
+
+ kinetic,current-ramp-delay-ms:
+ description: |
+ LED current ramping delay time in milliseconds, note that the
+ case 1 will be mapped to 1μs.
+ enum: [1, 2, 4, 8, 16, 32, 64, 128, 192, 256, 320, 384, 448, 512, 576, 640]
+
+ kinetic,led-enable-ramp-delay-ms:
+ description: |
+ LED on/off ramping delay time in milliseconds, note that the case 0 will be
+ mapped to 512μs because ktz8866 can't ramp faster than it.
+ enum: [0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384]
+
+ kinetic,enable-lcd-bias:
+ description: Set if we want to output bias power supply for LCD.
+ type: boolean
+
+required:
+ - compatible
+ - reg
+ - vddpos-supply
+ - vddneg-supply
+ - enable-gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@11 {
+ compatible = "kinetic,ktz8866";
+ reg = <0x11>;
+ vddpos-supply = <&bl_vddpos_5p5>;
+ vddneg-supply = <&bl_vddneg_5p5>;
+ enable-gpios = <&tlmm 139 GPIO_ACTIVE_HIGH>;
+ current-num-sinks = <5>;
+ kinetic,current-ramp-delay-ms = <128>;
+ kinetic,led-enable-ramp-delay-ms = <1>;
+ kinetic,enable-lcd-bias;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml
index 625082bf3892..8fc5af8f27f9 100644
--- a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/leds/backlight/led-backlight.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: led-backlight bindings
+title: led-backlight
maintainers:
- - Lee Jones <lee.jones@linaro.org>
+ - Lee Jones <lee@kernel.org>
- Daniel Thompson <daniel.thompson@linaro.org>
- Jingoo Han <jingoohan1@gmail.com>
@@ -16,33 +16,20 @@ description:
can also be used to describe a backlight device controlled by the output of
a LED driver.
+allOf:
+ - $ref: common.yaml#
+
properties:
compatible:
const: led-backlight
- leds:
- description: A list of LED nodes
- $ref: /schemas/types.yaml#/definitions/phandle-array
-
- brightness-levels:
- description:
- Array of distinct brightness levels. The levels must be in the range
- accepted by the underlying LED devices. This is used to translate a
- backlight brightness level into a LED brightness level. If it is not
- provided, the identity mapping is used.
- $ref: /schemas/types.yaml#/definitions/uint32-array
-
- default-brightness-level:
- description:
- The default brightness level (index into the array defined by the
- "brightness-levels" property).
- $ref: /schemas/types.yaml#/definitions/uint32
+ leds: true
required:
- compatible
- leds
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml
index 08fe5cf8614a..3c9b4054ed9a 100644
--- a/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: TI LM3630A High-Efficiency Dual-String White LED
maintainers:
- - Lee Jones <lee.jones@linaro.org>
+ - Lee Jones <lee@kernel.org>
- Daniel Thompson <daniel.thompson@linaro.org>
- Jingoo Han <jingoohan1@gmail.com>
diff --git a/Documentation/devicetree/bindings/leds/backlight/lp855x-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/lp855x-backlight.yaml
new file mode 100644
index 000000000000..9416e1bfab92
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/lp855x-backlight.yaml
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/lp855x-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments LP855X backlight controllers
+
+maintainers:
+ - Artur Weber <aweber.kernel@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - ti,lp8550
+ - ti,lp8551
+ - ti,lp8552
+ - ti,lp8553
+ - ti,lp8555
+ - ti,lp8556
+ - ti,lp8557
+
+ reg:
+ maxItems: 1
+
+ dev-ctrl:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description:
+ Value of device control register. This is a device-specific value.
+
+ bl-name:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: Backlight device name.
+
+ init-brt:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: Initial value of backlight brightness.
+
+ power-supply:
+ description: Regulator which controls the 3V rail.
+
+ enable-supply:
+ description: Regulator which controls the EN/VDDIO input.
+
+ pwms:
+ maxItems: 1
+ description: |
+ PWM channel to use for controlling the backlight; setting this
+ enables the PWM-based backlight control mode.
+
+ pwm-names: true
+
+ pwm-period:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ PWM period value. Deprecated; set the period value in the pwms
+ property instead.
+ deprecated: true
+
+patternProperties:
+ "^rom-[0-9a-f]{2}h$":
+ type: object
+ description: Nodes containing the values of configuration registers.
+ additionalProperties: false
+ properties:
+ rom-addr:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: Register address of ROM area to be updated.
+
+ rom-val:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: Value to write to the ROM register.
+
+required:
+ - compatible
+ - reg
+ - dev-ctrl
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@2c {
+ compatible = "ti,lp8555";
+ reg = <0x2c>;
+
+ dev-ctrl = /bits/ 8 <0x00>;
+
+ pwms = <&pwm 0 10000>;
+ pwm-names = "lp8555";
+
+ /* 4V OV, 4 output LED0 string enabled */
+ rom-14h {
+ rom-addr = /bits/ 8 <0x14>;
+ rom-val = /bits/ 8 <0xcf>;
+ };
+
+ /* Heavy smoothing, 24ms ramp time step */
+ rom-15h {
+ rom-addr = /bits/ 8 <0x15>;
+ rom-val = /bits/ 8 <0xc7>;
+ };
+
+ /* 4 output LED1 string enabled */
+ rom-19h {
+ rom-addr = /bits/ 8 <0x19>;
+ rom-val = /bits/ 8 <0x0f>;
+ };
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@2c {
+ compatible = "ti,lp8556";
+ reg = <0x2c>;
+
+ bl-name = "lcd-bl";
+ dev-ctrl = /bits/ 8 <0x85>;
+ init-brt = /bits/ 8 <0x10>;
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@2c {
+ compatible = "ti,lp8557";
+ reg = <0x2c>;
+ enable-supply = <&backlight_vddio>;
+ power-supply = <&backlight_vdd>;
+
+ dev-ctrl = /bits/ 8 <0x41>;
+ init-brt = /bits/ 8 <0x0a>;
+
+ /* 4V OV, 4 output LED string enabled */
+ rom-14h {
+ rom-addr = /bits/ 8 <0x14>;
+ rom-val = /bits/ 8 <0xcf>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/backlight/lp855x.txt b/Documentation/devicetree/bindings/leds/backlight/lp855x.txt
deleted file mode 100644
index 88f56641fc28..000000000000
--- a/Documentation/devicetree/bindings/leds/backlight/lp855x.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-lp855x bindings
-
-Required properties:
- - compatible: "ti,lp8550", "ti,lp8551", "ti,lp8552", "ti,lp8553",
- "ti,lp8555", "ti,lp8556", "ti,lp8557"
- - reg: I2C slave address (u8)
- - dev-ctrl: Value of DEVICE CONTROL register (u8). It depends on the device.
-
-Optional properties:
- - bl-name: Backlight device name (string)
- - init-brt: Initial value of backlight brightness (u8)
- - pwm-period: PWM period value. Set only PWM input mode used (u32)
- - rom-addr: Register address of ROM area to be updated (u8)
- - rom-val: Register value to be updated (u8)
- - power-supply: Regulator which controls the 3V rail
- - enable-supply: Regulator which controls the EN/VDDIO input
-
-Example:
-
- /* LP8555 */
- backlight@2c {
- compatible = "ti,lp8555";
- reg = <0x2c>;
-
- dev-ctrl = /bits/ 8 <0x00>;
- pwm-period = <10000>;
-
- /* 4V OV, 4 output LED0 string enabled */
- rom_14h {
- rom-addr = /bits/ 8 <0x14>;
- rom-val = /bits/ 8 <0xcf>;
- };
-
- /* Heavy smoothing, 24ms ramp time step */
- rom_15h {
- rom-addr = /bits/ 8 <0x15>;
- rom-val = /bits/ 8 <0xc7>;
- };
-
- /* 4 output LED1 string enabled */
- rom_19h {
- rom-addr = /bits/ 8 <0x19>;
- rom-val = /bits/ 8 <0x0f>;
- };
- };
-
- /* LP8556 */
- backlight@2c {
- compatible = "ti,lp8556";
- reg = <0x2c>;
-
- bl-name = "lcd-bl";
- dev-ctrl = /bits/ 8 <0x85>;
- init-brt = /bits/ 8 <0x10>;
- };
-
- /* LP8557 */
- backlight@2c {
- compatible = "ti,lp8557";
- reg = <0x2c>;
- enable-supply = <&backlight_vddio>;
- power-supply = <&backlight_vdd>;
-
- dev-ctrl = /bits/ 8 <0x41>;
- init-brt = /bits/ 8 <0x0a>;
-
- /* 4V OV, 4 output LED string enabled */
- rom_14h {
- rom-addr = /bits/ 8 <0x14>;
- rom-val = /bits/ 8 <0xcf>;
- };
- };
diff --git a/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt
deleted file mode 100644
index b4cffdaa4137..000000000000
--- a/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-88pm860x-backlight bindings
-
-Optional properties:
- - maxim,max8925-dual-string: whether support dual string
-
-Example:
-
- backlights {
- maxim,max8925-dual-string = <0>;
- };
diff --git a/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml
new file mode 100644
index 000000000000..16fc98e71233
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/mediatek,mt6370-backlight.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/mediatek,mt6370-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek MT6370 Backlight
+
+maintainers:
+ - ChiaEn Wu <chiaen_wu@richtek.com>
+
+description: |
+ This module is part of the MT6370 MFD device.
+ The MT6370 Backlight WLED driver supports up to a 29V output voltage for
+ 4 channels of 8 series WLEDs. Each channel supports up to 30mA of current
+ capability with 2048 current steps (11 bits, only for MT6370/MT6371) or
+ 16384 current steps (14 bits, only for MT6372) in exponential or linear
+ mapping curves.
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt6370-backlight
+ - mediatek,mt6372-backlight
+
+ default-brightness:
+ minimum: 0
+
+ max-brightness:
+ minimum: 0
+
+ enable-gpios:
+ description: External backlight 'enable' pin
+ maxItems: 1
+
+ mediatek,bled-pwm-enable:
+ description: |
+ Enable external PWM input for backlight dimming
+ type: boolean
+
+ mediatek,bled-pwm-hys-enable:
+ description: |
+ Enable the backlight input-hysteresis for PWM mode
+ type: boolean
+
+ mediatek,bled-pwm-hys-input-th-steps:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ enum: [1, 4, 16, 64]
+ description: |
+ The selection of the upper and lower bounds threshold of backlight
+ PWM resolution. If we choose selection 64, the variation of PWM
+ resolution needs more than 64 steps.
+
+ mediatek,bled-ovp-shutdown:
+ description: |
+ Enable the backlight shutdown when OVP level triggered
+ type: boolean
+
+ mediatek,bled-ovp-microvolt:
+ enum: [17000000, 21000000, 25000000, 29000000]
+ description: |
+ Backlight OVP level selection.
+
+ mediatek,bled-ocp-shutdown:
+ description: |
+ Enable the backlight shutdown when OCP level triggered.
+ type: boolean
+
+ mediatek,bled-ocp-microamp:
+ enum: [900000, 1200000, 1500000, 1800000]
+ description: |
+ Backlight OC level selection.
+
+ mediatek,bled-exponential-mode-enable:
+ description: |
+ Enable the exponential mode of backlight brightness. If this property
+ is not enabled, the default is to use linear mode.
+ type: boolean
+
+ mediatek,bled-channel-use:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: |
+ Backlight LED channel to be used.
+ Each bit mapping to:
+ - 0: CH4
+ - 1: CH3
+ - 2: CH2
+ - 3: CH1
+ minimum: 1
+ maximum: 15
+
+if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt6372-backlight
+
+then:
+ properties:
+ default-brightness:
+ maximum: 16384
+
+ max-brightness:
+ maximum: 16384
+
+else:
+ properties:
+ default-brightness:
+ maximum: 2048
+
+ max-brightness:
+ maximum: 2048
+
+required:
+ - compatible
+ - mediatek,bled-channel-use
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml b/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml
new file mode 100644
index 000000000000..527a37368ed7
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/mps,mp3309c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MPS MP3309C backlight
+
+maintainers:
+ - Flavio Suligoi <f.suligoi@asem.it>
+
+description: |
+ The Monolithic Power (MPS) MP3309C is a WLED step-up converter, featuring a
+ programmable switching frequency to optimize efficiency.
+ It supports two different dimming modes:
+
+ - analog mode, via I2C commands, as default mode (32 dimming levels)
+ - PWM controlled mode (optional)
+
+ The datasheet is available at:
+ https://www.monolithicpower.com/en/mp3309c.html
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ const: mps,mp3309c
+
+ reg:
+ maxItems: 1
+
+ pwms:
+ description: if present, the backlight is controlled in PWM mode.
+ maxItems: 1
+
+ enable-gpios:
+ description: GPIO used to enable the backlight in "analog-i2c" dimming mode.
+ maxItems: 1
+
+ mps,overvoltage-protection-microvolt:
+ description: Overvoltage protection (13.5V, 24V or 35.5V).
+ enum: [ 13500000, 24000000, 35500000 ]
+ default: 35500000
+
+ mps,no-sync-mode:
+ description: disable synchronous rectification mode
+ type: boolean
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Backlight with PWM control */
+ backlight_pwm: backlight@17 {
+ compatible = "mps,mp3309c";
+ reg = <0x17>;
+ pwms = <&pwm1 0 3333333 0>; /* 300 Hz --> (1/f) * 1*10^9 */
+ brightness-levels = <0 4 8 16 32 64 128 255>;
+ default-brightness = <6>;
+ mps,overvoltage-protection-microvolt = <24000000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml
index fcb8429f3088..b71f6454a4ac 100644
--- a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml
@@ -4,13 +4,16 @@
$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: pwm-backlight bindings
+title: pwm-backlight
maintainers:
- - Lee Jones <lee.jones@linaro.org>
+ - Lee Jones <lee@kernel.org>
- Daniel Thompson <daniel.thompson@linaro.org>
- Jingoo Han <jingoohan1@gmail.com>
+allOf:
+ - $ref: common.yaml#
+
properties:
compatible:
const: pwm-backlight
@@ -39,21 +42,6 @@ properties:
Delay in ms between disabling the backlight using GPIO and setting PWM
value to 0.
- brightness-levels:
- description:
- Array of distinct brightness levels. Typically these are in the range
- from 0 to 255, but any range starting at 0 will do. The actual brightness
- level (PWM duty cycle) will be interpolated from these values. 0 means a
- 0% duty cycle (darkest/off), while the last value in the array represents
- a 100% duty cycle (brightest).
- $ref: /schemas/types.yaml#/definitions/uint32-array
-
- default-brightness-level:
- description:
- The default brightness level (index into the array defined by the
- "brightness-levels" property).
- $ref: /schemas/types.yaml#/definitions/uint32
-
num-interpolated-steps:
description:
Number of interpolated steps between each value of brightness-levels
@@ -68,9 +56,8 @@ dependencies:
required:
- compatible
- pwms
- - power-supply
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml
index d839e75d9788..a8490781011d 100644
--- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml
@@ -4,11 +4,11 @@
$id: http://devicetree.org/schemas/leds/backlight/qcom-wled.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Binding for Qualcomm Technologies, Inc. WLED driver
+title: Qualcomm Technologies, Inc. WLED driver
maintainers:
- - Bjorn Andersson <bjorn.andersson@linaro.org>
- - Kiran Gunda <kgunda@codeaurora.org>
+ - Bjorn Andersson <andersson@kernel.org>
+ - Kiran Gunda <quic_kgunda@quicinc.com>
description: |
WLED (White Light Emitting Diode) driver is used for controlling display
@@ -19,13 +19,16 @@ properties:
compatible:
enum:
- qcom,pm8941-wled
+ - qcom,pmi8950-wled
- qcom,pmi8994-wled
- qcom,pmi8998-wled
- qcom,pm660l-wled
+ - qcom,pm6150l-wled
- qcom,pm8150l-wled
reg:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
default-brightness:
description: |
@@ -80,7 +83,7 @@ properties:
description: |
kHz; switching frequency.
$ref: /schemas/types.yaml#/definitions/uint32
- enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920,
+ enum: [ 600, 640, 685, 738, 800, 872, 960, 1066, 1200, 1371, 1600, 1920,
2400, 3200, 4800, 9600 ]
qcom,ovp:
@@ -170,6 +173,9 @@ allOf:
then:
properties:
+ reg:
+ maxItems: 1
+
qcom,current-boost-limit:
enum: [ 105, 385, 525, 805, 980, 1260, 1400, 1680 ]
default: 805
@@ -188,6 +194,9 @@ allOf:
else:
properties:
+ reg:
+ minItems: 2
+
qcom,current-boost-limit:
enum: [ 105, 280, 450, 620, 970, 1150, 1300, 1500 ]
default: 970
diff --git a/Documentation/devicetree/bindings/leds/backlight/richtek,rt4831-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/richtek,rt4831-backlight.yaml
index e0ac68694b63..99e9e138fa92 100644
--- a/Documentation/devicetree/bindings/leds/backlight/richtek,rt4831-backlight.yaml
+++ b/Documentation/devicetree/bindings/leds/backlight/richtek,rt4831-backlight.yaml
@@ -47,6 +47,11 @@ properties:
minimum: 0
maximum: 3
+ richtek,bled-ocp-microamp:
+ description: |
+ Backlight over current protection level.
+ enum: [900000, 1200000, 1500000, 1800000]
+
richtek,channel-use:
description: |
Backlight LED channel to be used.
diff --git a/Documentation/devicetree/bindings/leds/backlight/ti,lm3509.yaml b/Documentation/devicetree/bindings/leds/backlight/ti,lm3509.yaml
new file mode 100644
index 000000000000..482fae71dd53
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/ti,lm3509.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/ti,lm3509.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI LM3509 High Efficiency Boost for White LED's and/or OLED Displays
+
+maintainers:
+ - Patrick Gansterer <paroga@paroga.com>
+
+description:
+ The LM3509 current mode boost converter offers two separate outputs.
+ https://www.ti.com/product/LM3509
+
+properties:
+ compatible:
+ const: ti,lm3509
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ reset-gpios:
+ maxItems: 1
+
+ ti,brightness-rate-of-change-us:
+ description: Brightness Rate of Change in microseconds.
+ enum: [51, 13000, 26000, 52000]
+
+ ti,oled-mode:
+ description: Enable OLED mode.
+ type: boolean
+
+patternProperties:
+ "^led@[01]$":
+ type: object
+ description: Properties for a string of connected LEDs.
+ $ref: common.yaml#
+
+ properties:
+ reg:
+ description:
+ The control register that is used to program the two current sinks.
+ The LM3509 has two registers (BMAIN and BSUB) and are represented
+ as 0 or 1 in this property. The two current sinks can be controlled
+ independently with both registers, or register BMAIN can be
+ configured to control both sinks with the led-sources property.
+ minimum: 0
+ maximum: 1
+
+ label: true
+
+ led-sources:
+ minItems: 1
+ maxItems: 2
+ items:
+ minimum: 0
+ maximum: 1
+
+ default-brightness:
+ minimum: 0
+ maximum: 31
+ default: 18
+
+ max-brightness:
+ minimum: 0
+ maximum: 31
+ default: 31
+
+ required:
+ - reg
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@36 {
+ compatible = "ti,lm3509";
+ reg = <0x36>;
+ reset-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>;
+
+ ti,oled-mode;
+ ti,brightness-rate-of-change-us = <52000>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ led-sources = <0 1>;
+ label = "lcd-backlight";
+ default-brightness = <12>;
+ max-brightness = <31>;
+ };
+ };
+ };
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ backlight@36 {
+ compatible = "ti,lm3509";
+ reg = <0x36>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ default-brightness = <12>;
+ };
+
+ led@1 {
+ reg = <1>;
+ default-brightness = <15>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/backlight/ti,lp8864.yaml b/Documentation/devicetree/bindings/leds/backlight/ti,lp8864.yaml
new file mode 100644
index 000000000000..d44232d462bd
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/ti,lp8864.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/ti,lp8864.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments - LP8864/LP8866 4/6-Channel LED Driver family
+
+maintainers:
+ - Andrew Davis <afd@ti.com>
+ - Alexander Sverdlin <alexander.sverdlin@siemens.com>
+
+description: |
+ LP8866-Q1, LP8866S-Q1, LP8864-Q1, LP8864S-Q1 are display LED-backlight drivers
+ with 4/6 channels. LED brightness can be controlled globally through the I2C
+ interface or PWM input.
+
+ For more product information please see the links below:
+ https://www.ti.com/product/LP8864-Q1
+ https://www.ti.com/product/LP8864S-Q1
+ https://www.ti.com/product/LP8866-Q1
+ https://www.ti.com/product/LP8866S-Q1
+
+properties:
+ compatible:
+ const: ti,lp8864
+
+ reg:
+ maxItems: 1
+ description: I2C slave address
+
+ enable-gpios:
+ maxItems: 1
+ description: GPIO pin to enable (active high) / disable the device
+
+ vled-supply:
+ description: LED supply
+
+ led:
+ type: object
+ $ref: common.yaml#
+ properties:
+ function: true
+ color: true
+ label: true
+ linux,default-trigger: true
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - led
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@3a {
+ compatible = "ti,lp8864";
+ reg = <0x3a>;
+ enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
+ vled-supply = <&vbatt>;
+
+ led {
+ function = LED_FUNCTION_BACKLIGHT;
+ color = <LED_COLOR_ID_WHITE>;
+ linux,default-trigger = "backlight";
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.txt
deleted file mode 100644
index ff5c92138650..000000000000
--- a/Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Zodiac Inflight Innovations RAVE Supervisory Processor Backlight Bindings
-
-RAVE SP backlight device is a "MFD cell" device corresponding to
-backlight functionality of RAVE Supervisory Processor. It is expected
-that its Device Tree node is specified as a child of the node
-corresponding to the parent RAVE SP device (as documented in
-Documentation/devicetree/bindings/mfd/zii,rave-sp.txt)
-
-Required properties:
-
-- compatible: Should be "zii,rave-sp-backlight"
-
-Example:
-
- rave-sp {
- compatible = "zii,rave-sp-rdu1";
- current-speed = <38400>;
-
- backlight {
- compatible = "zii,rave-sp-backlight";
- };
- }
-
diff --git a/Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.yaml
new file mode 100644
index 000000000000..ee93a3e64852
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/backlight/zii,rave-sp-backlight.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/backlight/zii,rave-sp-backlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Zodiac Inflight Innovations RAVE Supervisory Processor Backlight
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description:
+ RAVE SP backlight device is a "MFD cell" device corresponding to
+ backlight functionality of RAVE Supervisory Processor. It is expected
+ that its Device Tree node is specified as a child of the node
+ corresponding to the parent RAVE SP device (as documented in
+ Documentation/devicetree/bindings/mfd/zii,rave-sp.yaml)
+
+properties:
+ compatible:
+ const: zii,rave-sp-backlight
+
+required:
+ - compatible
+
+allOf:
+ - $ref: common.yaml
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ backlight {
+ compatible = "zii,rave-sp-backlight";
+ };
+
diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml
index b1f363747a62..f4e44b33f56d 100644
--- a/Documentation/devicetree/bindings/leds/common.yaml
+++ b/Documentation/devicetree/bindings/leds/common.yaml
@@ -43,7 +43,7 @@ properties:
LED_COLOR_ID available, add a new one.
$ref: /schemas/types.yaml#/definitions/uint32
minimum: 0
- maximum: 9
+ maximum: 14
function-enumerator:
description:
@@ -62,7 +62,7 @@ properties:
default-state:
description:
The initial state of the LED. If the LED is already on or off and the
- default-state property is set the to same value, then no glitch should be
+ default-state property is set to the same value, then no glitch should be
produced where the LED momentarily turns off (or on). The "keep" setting
will keep the LED at whatever its current state is, without producing a
glitch.
@@ -79,24 +79,63 @@ properties:
the LED.
$ref: /schemas/types.yaml#/definitions/string
- enum:
- # LED will act as a back-light, controlled by the framebuffer system
- - backlight
- # LED will turn on (but for leds-gpio see "default-state" property in
- # Documentation/devicetree/bindings/leds/leds-gpio.yaml)
- - default-on
- # LED "double" flashes at a load average based rate
- - heartbeat
- # LED indicates disk activity
- - disk-activity
- # LED indicates IDE disk activity (deprecated), in new implementations
- # use "disk-activity"
- - ide-disk
- # LED flashes at a fixed, configurable rate
- - timer
- # LED alters the brightness for the specified duration with one software
- # timer (requires "led-pattern" property)
- - pattern
+ oneOf:
+ - enum:
+ # LED will act as a back-light, controlled by the framebuffer system
+ - backlight
+ # LED will turn on (see also "default-state" property)
+ - default-on
+ # LED "double" flashes at a load average based rate
+ - heartbeat
+ # LED indicates disk activity
+ - disk-activity
+ # LED indicates disk read activity
+ - disk-read
+ # LED indicates disk write activity
+ - disk-write
+ # LED flashes at a fixed, configurable rate
+ - timer
+ # LED alters the brightness for the specified duration with one software
+ # timer (requires "led-pattern" property)
+ - pattern
+ # LED indicates mic mute state
+ - audio-micmute
+ # LED indicates audio mute state
+ - audio-mute
+ # LED indicates bluetooth power state
+ - bluetooth-power
+ # LED indicates camera flash state
+ - flash
+ # LED indicated keyboard capslock
+ - kbd-capslock
+ # LED indicates MTD memory activity
+ - mtd
+ # LED indicates NAND memory activity (deprecated),
+ # in new implementations use "mtd"
+ - nand-disk
+ # LED indicates network activity
+ - netdev
+ # No trigger assigned to the LED. This is the default mode
+ # if trigger is absent
+ - none
+ # LED indicates remote control feedback
+ - rc-feedback
+ # LED indicates camera torch state
+ - torch
+ # LED indicates USB gadget activity
+ - usb-gadget
+ # LED indicates USB host activity
+ - usb-host
+ # LED indicates USB port state
+ - usbport
+ # LED is triggered by CPU activity
+ - pattern: "^cpu[0-9]*$"
+ # LED is triggered by Bluetooth activity
+ - pattern: "^hci[0-9]+-power$"
+ # LED is triggered by SD/MMC activity
+ - pattern: "^mmc[0-9]+$"
+ # LED is triggered by WLAN activity
+ - pattern: "^phy[0-9]+tx$"
led-pattern:
description: |
@@ -122,12 +161,36 @@ properties:
For flash LED controllers with configurable current this property is
mandatory for the LEDs in the non-flash modes (e.g. torch or indicator).
+ max-brightness:
+ description:
+ Normally, the maximum brightness is determined by the hardware, and this
+ property is not required. This property is used to set a software limit.
+ It could happen that an LED is made so bright that it gets damaged or
+ causes damage due to restrictions in a specific system, such as mounting
+ conditions.
+ Note that this flag is mainly used for PWM-LEDs, where it is not possible
+ to map brightness to current. Drivers for other controllers should use
+ led-max-microamp.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ default-brightness:
+ description:
+ Brightness to be set if LED's default state is on. Used only during
+ initialization. If the option is not set then max brightness is used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
panic-indicator:
description:
This property specifies that the LED should be used, if at all possible,
as a panic indicator.
type: boolean
+ retain-state-shutdown:
+ description:
+ This property specifies that the LED should not be turned off or changed
+ when the system shuts down.
+ type: boolean
+
trigger-sources:
description: |
List of devices which should be used as a source triggering this LED
@@ -138,6 +201,8 @@ properties:
each of them having its own LED assigned (assuming they are not
hardwired). In such cases this property should contain phandle(s) of
related source device(s).
+ Another example is a GPIO line that will be monitored and mirror the
+ state of the line (with or without inversion flags) to the LED.
In many cases LED can be related to more than one device (e.g. one USB LED
vs. multiple USB ports). Each source should be represented by a node in
the device tree and be referenced by a phandle and a set of phandle
@@ -145,6 +210,24 @@ properties:
#trigger-source-cells property in the source node.
$ref: /schemas/types.yaml#/definitions/phandle-array
+ active-high:
+ type: boolean
+ description:
+ Makes LED active high. To turn the LED ON, line needs to be
+ set to high voltage instead of low.
+
+ active-low:
+ type: boolean
+ description:
+ Makes LED active low. To turn the LED ON, line needs to be
+ set to low voltage instead of high.
+
+ inactive-high-impedance:
+ type: boolean
+ description:
+ Set LED to high-impedance mode to turn the LED OFF. LED might also
+ describe this mode as tristate.
+
# Required properties for flash LED child nodes:
flash-max-microamp:
description:
@@ -156,6 +239,14 @@ properties:
Maximum timeout in microseconds after which the flash LED is turned off.
Required for flash LED nodes with configurable timeout.
+allOf:
+ - if:
+ required:
+ - active-low
+ then:
+ properties:
+ active-high: false
+
additionalProperties: true
examples:
@@ -179,9 +270,11 @@ examples:
};
};
- led-controller@0 {
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ led-controller {
compatible = "maxim,max77693-led";
- reg = <0 0x100>;
led {
function = LED_FUNCTION_FLASH;
@@ -193,6 +286,9 @@ examples:
};
};
+ - |
+ #include <dt-bindings/leds/common.h>
+
i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml
index c7ed2871da06..f52f6304c79e 100644
--- a/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml
+++ b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml
@@ -23,6 +23,12 @@ properties:
description: I2C slave address of the microcontroller.
maxItems: 1
+ interrupts:
+ description:
+ Specifier for the global LED brightness changed by front button press
+ interrupt.
+ maxItems: 1
+
"#address-cells":
const: 1
@@ -32,8 +38,9 @@ properties:
patternProperties:
"^multi-led@[0-9a-b]$":
type: object
- allOf:
- - $ref: leds-class-multicolor.yaml#
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
description:
This node represents one of the RGB LED devices on Turris Omnia.
No subnodes need to be added for subchannels since this controller only
@@ -55,15 +62,17 @@ additionalProperties: false
examples:
- |
+ #include <dt-bindings/interrupt-controller/irq.h>
#include <dt-bindings/leds/common.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
led-controller@2b {
compatible = "cznic,turris-omnia-leds";
reg = <0x2b>;
+ interrupts-extended = <&mcu 11 IRQ_TYPE_NONE>;
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.txt b/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.txt
deleted file mode 100644
index cbe8dfd29715..000000000000
--- a/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-Device tree bindings for IR LED connected through gpio pin which is used as
-remote controller transmitter.
-
-Required properties:
- - compatible: should be "gpio-ir-tx".
- - gpios : Should specify the IR LED GPIO, see "gpios property" in
- Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs
- should be indicated using flags in the GPIO specifier.
-
-Example:
- irled@0 {
- compatible = "gpio-ir-tx";
- gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>;
- };
diff --git a/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml b/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml
new file mode 100644
index 000000000000..5839d00c7089
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/irled/gpio-ir-tx.yaml
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/irled/gpio-ir-tx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IR LED connected through GPIO pin
+
+maintainers:
+ - Sean Young <sean@mess.org>
+
+description:
+ IR LED connected through GPIO pin which is used as remote controller
+ transmitter.
+
+properties:
+ compatible:
+ const: gpio-ir-tx
+
+ gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ irled {
+ compatible = "gpio-ir-tx";
+ gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml b/Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml
new file mode 100644
index 000000000000..72cadebf6e3e
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/irled/ir-spi-led.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/irled/ir-spi-led.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IR LED connected through SPI bus
+
+maintainers:
+ - Sean Young <sean@mess.org>
+
+description:
+ IR LED switch is connected to the MOSI line of the SPI device and the data
+ is delivered through that.
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+ compatible:
+ const: ir-spi-led
+
+ reg:
+ maxItems: 1
+
+ duty-cycle:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ enum: [50, 60, 70, 75, 80, 90]
+ description:
+ Percentage of one period in which the signal is active.
+
+ led-active-low:
+ type: boolean
+ description:
+ Output is negated with a NOT gate.
+
+ power-supply: true
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ irled@0 {
+ compatible = "ir-spi-led";
+ reg = <0x0>;
+
+ duty-cycle = /bits/ 8 <60>;
+ led-active-low;
+ power-supply = <&irda_regulator>;
+ spi-max-frequency = <5000000>;
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.txt b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.txt
deleted file mode 100644
index 66e5672c2e3d..000000000000
--- a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-Device tree bindings for IR LED connected through pwm pin which is used as
-remote controller transmitter.
-
-Required properties:
- - compatible: should be "pwm-ir-tx".
- - pwms : PWM property to point to the PWM device (phandle)/port (id)
- and to specify the period time to be used: <&phandle id period_ns>;
-
-Example:
- irled {
- compatible = "pwm-ir-tx";
- pwms = <&pwm0 0 10000000>;
- };
diff --git a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml
new file mode 100644
index 000000000000..7526e3149f72
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/irled/pwm-ir-tx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IR LED connected through PWM pin
+
+maintainers:
+ - Sean Young <sean@mess.org>
+
+description:
+ IR LED connected through PWM pin which is used as remote controller
+ transmitter.
+
+properties:
+ compatible:
+ oneOf:
+ - const: pwm-ir-tx
+ - const: nokia,n900-ir
+ deprecated: true
+
+ pwms:
+ maxItems: 1
+
+required:
+ - compatible
+ - pwms
+
+additionalProperties: false
+
+examples:
+ - |
+ irled {
+ compatible = "pwm-ir-tx";
+ pwms = <&pwm0 0 10000000>;
+ };
diff --git a/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt b/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt
deleted file mode 100644
index 83ff1b4d70a6..000000000000
--- a/Documentation/devicetree/bindings/leds/irled/spi-ir-led.txt
+++ /dev/null
@@ -1,29 +0,0 @@
-Device tree bindings for IR LED connected through SPI bus which is used as
-remote controller.
-
-The IR LED switch is connected to the MOSI line of the SPI device and the data
-are delivered thourgh that.
-
-Required properties:
- - compatible: should be "ir-spi-led".
-
-Optional properties:
- - duty-cycle: 8 bit value that represents the percentage of one period
- in which the signal is active. It can be 50, 60, 70, 75, 80 or 90.
- - led-active-low: boolean value that specifies whether the output is
- negated with a NOT gate.
- - power-supply: specifies the power source. It can either be a regulator
- or a gpio which enables a regulator, i.e. a regulator-fixed as
- described in
- Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
-
-Example:
-
- irled@0 {
- compatible = "ir-spi-led";
- reg = <0x0>;
- spi-max-frequency = <5000000>;
- power-supply = <&vdd_led>;
- led-active-low;
- duty-cycle = /bits/ 8 <60>;
- };
diff --git a/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml b/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml
new file mode 100644
index 000000000000..906735acfbaf
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/issi,is31fl319x.yaml
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/issi,is31fl319x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ISSI LED Controllers for IS31FL319{0,1,3,6,9}
+
+maintainers:
+ - Vincent Knecht <vincent.knecht@mailoo.org>
+
+description: |
+ The IS31FL319X are LED controllers with I2C interface.
+ Previously known as Si-En SN319{0,1,3,6,9}.
+
+ For more product information please see the links below:
+ https://lumissil.com/assets/pdf/core/IS31FL3190_DS.pdf
+ https://lumissil.com/assets/pdf/core/IS31FL3191_DS.pdf
+ https://lumissil.com/assets/pdf/core/IS31FL3193_DS.pdf
+ https://lumissil.com/assets/pdf/core/IS31FL3196_DS.pdf
+ https://lumissil.com/assets/pdf/core/IS31FL3199_DS.pdf
+
+properties:
+ compatible:
+ enum:
+ - issi,is31fl3190
+ - issi,is31fl3191
+ - issi,is31fl3193
+ - issi,is31fl3196
+ - issi,is31fl3199
+ - si-en,sn3190
+ - si-en,sn3191
+ - si-en,sn3193
+ - si-en,sn3196
+ - si-en,sn3199
+
+ reg:
+ maxItems: 1
+
+ shutdown-gpios:
+ maxItems: 1
+ description: GPIO attached to the SDB pin.
+
+ audio-gain-db:
+ default: 0
+ description: Audio gain selection for external analog modulation input.
+ enum: [0, 3, 6, 9, 12, 15, 18, 21]
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[1-9]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: Index of the LED.
+ minimum: 1
+ maximum: 9
+
+ led-max-microamp:
+ description:
+ Note that a driver will take the lowest of all LED limits
+ since the chip has a single global setting. The lowest value
+ will be chosen due to the PWM specificity, where lower
+ brightness is achieved by reducing the duty-cycle of pulses
+ and not the current, which will always have its peak value
+ equal to led-max-microamp.
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - issi,is31fl3190
+ - issi,is31fl3191
+ - issi,is31fl3193
+ - si-en,sn3190
+ - si-en,sn3191
+ - si-en,sn3193
+ then:
+ properties:
+ reg:
+ enum: [0x68, 0x69, 0x6a, 0x6b]
+
+ audio-gain-db: false
+
+ patternProperties:
+ "^led@[1-9]$":
+ properties:
+ led-max-microamp:
+ default: 42000
+ enum: [5000, 10000, 17500, 30000, 42000]
+ else:
+ properties:
+ reg:
+ enum: [0x64, 0x65, 0x66, 0x67]
+
+ patternProperties:
+ "^led@[1-9]$":
+ properties:
+ led-max-microamp:
+ default: 20000
+ enum: [5000, 10000, 15000, 20000, 25000, 30000, 35000, 40000]
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - issi,is31fl3190
+ - issi,is31fl3191
+ - si-en,sn3190
+ - si-en,sn3191
+ then:
+ patternProperties:
+ "^led@[1-9]$":
+ properties:
+ reg:
+ maximum: 1
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - issi,is31fl3193
+ - si-en,sn3193
+ then:
+ patternProperties:
+ "^led@[1-9]$":
+ properties:
+ reg:
+ maximum: 3
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - issi,is31fl3196
+ - si-en,sn3196
+ then:
+ patternProperties:
+ "^led@[1-9]$":
+ properties:
+ reg:
+ maximum: 6
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@65 {
+ compatible = "issi,is31fl3196";
+ reg = <0x65>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ shutdown-gpios = <&gpio0 11 GPIO_ACTIVE_HIGH>;
+
+ led@1 {
+ reg = <1>;
+ label = "red:aux";
+ led-max-microamp = <10000>;
+ };
+
+ led@5 {
+ reg = <5>;
+ label = "green:power";
+ linux,default-trigger = "default-on";
+ };
+ };
+ };
+...
+
diff --git a/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml b/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml
new file mode 100644
index 000000000000..832c030a5acf
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/kinetic,ktd202x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Kinetic KTD2026/7 RGB/White LED Driver
+
+maintainers:
+ - André Apitzsch <git@apitzsch.eu>
+
+description: |
+ The KTD2026/7 is a RGB/White LED driver with I2C interface.
+
+ The data sheet can be found at:
+ https://www.kinet-ic.com/uploads/KTD2026-7-04h.pdf
+
+properties:
+ compatible:
+ enum:
+ - kinetic,ktd2026
+ - kinetic,ktd2027
+
+ reg:
+ maxItems: 1
+
+ vin-supply:
+ description: Regulator providing power to the "VIN" pin.
+
+ vio-supply:
+ description: Regulator providing power for pull-up of the I/O lines.
+ Note that this regulator does not directly connect to KTD2026, but is
+ needed for the correct operation of the status ("ST") and I2C lines.
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ multi-led:
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^led@[0-3]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: Index of the LED.
+ minimum: 0
+ maximum: 3
+
+ required:
+ - reg
+ - color
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+patternProperties:
+ "^led@[0-3]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: Index of the LED.
+ minimum: 0
+ maximum: 3
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@30 {
+ compatible = "kinetic,ktd2026";
+ reg = <0x30>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vin-supply = <&pm8916_l17>;
+ vio-supply = <&pm8916_l6>;
+
+ led@0 {
+ reg = <0>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@1 {
+ reg = <1>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@2 {
+ reg = <2>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ };
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@30 {
+ compatible = "kinetic,ktd2026";
+ reg = <0x30>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vin-supply = <&pm8916_l17>;
+ vio-supply = <&pm8916_l6>;
+
+ multi-led {
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_STATUS;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/kinetic,ktd2692.yaml b/Documentation/devicetree/bindings/leds/kinetic,ktd2692.yaml
new file mode 100644
index 000000000000..bac95a51afa1
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/kinetic,ktd2692.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/kinetic,ktd2692.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: KTD2692 Flash LED Driver from Kinetic Technologies
+
+maintainers:
+ - Markuss Broks <markuss.broks@gmail.com>
+
+description: |
+ KTD2692 is the ideal power solution for high-power flash LEDs.
+ It uses ExpressWire single-wire programming for maximum flexibility.
+
+ The ExpressWire interface through CTRL pin can control LED on/off and
+ enable/disable the IC, Movie(max 1/3 of Flash current) / Flash mode current,
+ Flash timeout, LVP(low voltage protection).
+
+ Also, When the AUX pin is pulled high while CTRL pin is high,
+ LED current will be ramped up to the flash-mode current level.
+
+properties:
+ compatible:
+ const: kinetic,ktd2692
+
+ ctrl-gpios:
+ maxItems: 1
+ description: Specifier of the GPIO connected to CTRL pin.
+
+ aux-gpios:
+ maxItems: 1
+ description: Specifier of the GPIO connected to CTRL pin.
+
+ vin-supply:
+ description: LED supply (2.7V to 5.5V).
+
+ led:
+ type: object
+ $ref: common.yaml#
+ description: Properties for the LED.
+ properties:
+ function: true
+ color: true
+ flash-max-timeout-us:
+ description: Flash LED maximum timeout.
+
+ led-max-microamp:
+ maximum: 300000
+ description: Minimum Threshold for Timer protection
+ is defined internally (Maximum 300mA).
+
+ flash-max-microamp:
+ maximum: 300000
+ description: Flash LED maximum current
+ Formula - I(uA) = 15000000 / Rset.
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - ctrl-gpios
+ - led
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ ktd2692 {
+ compatible = "kinetic,ktd2692";
+ ctrl-gpios = <&gpc0 1 0>;
+ aux-gpios = <&gpc0 2 0>;
+ vin-supply = <&vbat>;
+
+ led {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ flash-max-timeout-us = <250000>;
+ flash-max-microamp = <150000>;
+ led-max-microamp = <25000>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-aat1290.txt b/Documentation/devicetree/bindings/leds/leds-aat1290.txt
deleted file mode 100644
index 62ed17ec075b..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-aat1290.txt
+++ /dev/null
@@ -1,77 +0,0 @@
-* Skyworks Solutions, Inc. AAT1290 Current Regulator for Flash LEDs
-
-The device is controlled through two pins: FL_EN and EN_SET. The pins when,
-asserted high, enable flash strobe and movie mode (max 1/2 of flash current)
-respectively. In order to add a capability of selecting the strobe signal source
-(e.g. CPU or camera sensor) there is an additional switch required, independent
-of the flash chip. The switch is controlled with pin control.
-
-Required properties:
-
-- compatible : Must be "skyworks,aat1290".
-- flen-gpios : Must be device tree identifier of the flash device FL_EN pin.
-- enset-gpios : Must be device tree identifier of the flash device EN_SET pin.
-
-Optional properties:
-- pinctrl-names : Must contain entries: "default", "host", "isp". Entries
- "default" and "host" must refer to the same pin configuration
- node, which sets the host as a strobe signal provider. Entry
- "isp" must refer to the pin configuration node, which sets the
- ISP as a strobe signal provider.
-
-A discrete LED element connected to the device must be represented by a child
-node - see Documentation/devicetree/bindings/leds/common.txt.
-
-Required properties of the LED child node:
-- led-max-microamp : see Documentation/devicetree/bindings/leds/common.txt
-- flash-max-microamp : see Documentation/devicetree/bindings/leds/common.txt
- Maximum flash LED supply current can be calculated using
- following formula: I = 1A * 162kohm / Rset.
-- flash-max-timeout-us : see Documentation/devicetree/bindings/leds/common.txt
- Maximum flash timeout can be calculated using following
- formula: T = 8.82 * 10^9 * Ct.
-
-Optional properties of the LED child node:
-- function : see Documentation/devicetree/bindings/leds/common.txt
-- color : see Documentation/devicetree/bindings/leds/common.txt
-- label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
-
-Example (by Ct = 220nF, Rset = 160kohm and exynos4412-trats2 board with
-a switch that allows for routing strobe signal either from the host or from
-the camera sensor):
-
-#include "exynos4412.dtsi"
-#include <dt-bindings/leds/common.h>
-
-led-controller {
- compatible = "skyworks,aat1290";
- flen-gpios = <&gpj1 1 GPIO_ACTIVE_HIGH>;
- enset-gpios = <&gpj1 2 GPIO_ACTIVE_HIGH>;
-
- pinctrl-names = "default", "host", "isp";
- pinctrl-0 = <&camera_flash_host>;
- pinctrl-1 = <&camera_flash_host>;
- pinctrl-2 = <&camera_flash_isp>;
-
- camera_flash: led {
- function = LED_FUNCTION_FLASH;
- color = <LED_COLOR_ID_WHITE>;
- led-max-microamp = <520833>;
- flash-max-microamp = <1012500>;
- flash-max-timeout-us = <1940000>;
- };
-};
-
-&pinctrl_0 {
- camera_flash_host: camera-flash-host {
- samsung,pins = "gpj1-0";
- samsung,pin-function = <1>;
- samsung,pin-val = <0>;
- };
-
- camera_flash_isp: camera-flash-isp {
- samsung,pins = "gpj1-0";
- samsung,pin-function = <1>;
- samsung,pin-val = <1>;
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-an30259a.txt b/Documentation/devicetree/bindings/leds/leds-an30259a.txt
deleted file mode 100644
index cbd833906b2b..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-an30259a.txt
+++ /dev/null
@@ -1,55 +0,0 @@
-* Panasonic AN30259A 3-channel LED driver
-
-The AN30259A is a LED controller capable of driving three LEDs independently. It supports
-constant current output and sloping current output modes. The chip is connected over I2C.
-
-Required properties:
- - compatible: Must be "panasonic,an30259a".
- - reg: I2C slave address.
- - #address-cells: Must be 1.
- - #size-cells: Must be 0.
-
-Each LED is represented as a sub-node of the panasonic,an30259a node.
-
-Required sub-node properties:
- - reg: Pin that the LED is connected to. Must be 1, 2, or 3.
-
-Optional sub-node properties:
- - function :
- see Documentation/devicetree/bindings/leds/common.txt
- - color :
- see Documentation/devicetree/bindings/leds/common.txt
- - label :
- see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- - linux,default-trigger :
- see Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
-#include <dt-bindings/leds/common.h>
-
-led-controller@30 {
- compatible = "panasonic,an30259a";
- reg = <0x30>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- led@1 {
- reg = <1>;
- linux,default-trigger = "heartbeat";
- function = LED_FUNCTION_INDICATOR;
- color = <LED_COLOR_ID_RED>;
- };
-
- led@2 {
- reg = <2>;
- function = LED_FUNCTION_INDICATOR;
- color = <LED_COLOR_ID_GREEN>;
- };
-
- led@3 {
- reg = <3>;
- function = LED_FUNCTION_INDICATOR;
- color = <LED_COLOR_ID_BLUE>;
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml
index e24b0d15ef01..26238446f2bd 100644
--- a/Documentation/devicetree/bindings/leds/leds-aw2013.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-aw2013.yaml
@@ -20,9 +20,20 @@ properties:
reg:
maxItems: 1
+ interrupts:
+ maxItems: 1
+ description: Open-drain, low active interrupt pin "INTN".
+ Used to report completion of operations (power up, LED breath effects).
+
vcc-supply:
description: Regulator providing power to the "VCC" pin.
+ vio-supply:
+ description: Regulator providing power for pull-up of the I/O lines.
+ "VIO1" in the typical application circuit example of the datasheet.
+ Note that this regulator does not directly connect to AW2013, but is
+ needed for the correct operation of the interrupt and I2C lines.
+
"#address-cells":
const: 1
@@ -33,6 +44,7 @@ patternProperties:
"^led@[0-2]$":
type: object
$ref: common.yaml#
+ unevaluatedProperties: false
properties:
reg:
@@ -51,15 +63,17 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
#include <dt-bindings/leds/common.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
led-controller@45 {
compatible = "awinic,aw2013";
reg = <0x45>;
+ interrupts = <42 IRQ_TYPE_LEVEL_LOW>;
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml b/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml
new file mode 100644
index 000000000000..62326507c1aa
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-bcm63138.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom's BCM63138 LEDs controller
+
+maintainers:
+ - Rafał Miłecki <rafal@milecki.pl>
+
+description: |
+ This LEDs controller was first used on BCM63138 and later reused on BCM4908,
+ BCM6848, BCM6858, BCM63138, BCM63148, BCM63381 and BCM68360 SoCs.
+
+ It supports up to 32 LEDs that can be connected parallelly or serially. It
+ also includes limited support for hardware blinking.
+
+ Binding serially connected LEDs isn't documented yet.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - brcm,bcm4908-leds
+ - brcm,bcm6848-leds
+ - brcm,bcm6858-leds
+ - brcm,bcm63148-leds
+ - brcm,bcm63381-leds
+ - brcm,bcm68360-leds
+ - const: brcm,bcm63138-leds
+ - const: brcm,bcm63138-leds
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ brcm,serial-shift-bits:
+ minimum: 1
+ maximum: 32
+ description:
+ This describes the number of 8-bit serial shifters connected to the LED
+ controller block. The hardware is typically using 8-bit shift registers
+ with 8 LEDs per shift register, so 4 shifters results in 32 LEDs or 2
+ shifters give 16 LEDs etc, but the hardware supports any odd number of
+ registers. If left unspecified, the hardware boot-time default is used.
+
+patternProperties:
+ "^led@[a-f0-9]+$":
+ type: object
+
+ $ref: common.yaml#
+
+ properties:
+ reg:
+ maxItems: 1
+ description: LED pin number
+
+ required:
+ - reg
+
+ unevaluatedProperties: false
+
+required:
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ leds@ff800800 {
+ compatible = "brcm,bcm4908-leds", "brcm,bcm63138-leds";
+ reg = <0xff800800 0xdc>;
+ brcm,serial-shift-bits = <16>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0x0>;
+ function = LED_FUNCTION_POWER;
+ color = <LED_COLOR_ID_GREEN>;
+ default-state = "on";
+ };
+
+ led@3 {
+ reg = <0x3>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_GREEN>;
+ active-low;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt
deleted file mode 100644
index a555d94084b7..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt
+++ /dev/null
@@ -1,319 +0,0 @@
-LEDs connected to Broadcom BCM6328 controller
-
-This controller is present on BCM6318, BCM6328, BCM6362 and BCM63268.
-In these SoCs it's possible to control LEDs both as GPIOs or by hardware.
-However, on some devices there are Serial LEDs (LEDs connected to a 74x164
-controller), which can either be controlled by software (exporting the 74x164
-as spi-gpio. See Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml),
-or by hardware using this driver.
-Some of these Serial LEDs are hardware controlled (e.g. ethernet LEDs) and
-exporting the 74x164 as spi-gpio prevents those LEDs to be hardware
-controlled, so the only chance to keep them working is by using this driver.
-
-BCM6328 LED controller has a HWDIS register, which controls whether a LED
-should be controlled by a hardware signal instead of the MODE register value,
-with 0 meaning hardware control enabled and 1 hardware control disabled. This
-is usually 1:1 for hardware to LED signals, but through the activity/link
-registers you have some limited control over rerouting the LEDs (as
-explained later in brcm,link-signal-sources). Even if a LED is hardware
-controlled you are still able to make it blink or light it up if it isn't,
-but you can't turn it off if the hardware decides to light it up. For this
-reason, hardware controlled LEDs aren't registered as LED class devices.
-
-Required properties:
- - compatible : should be "brcm,bcm6328-leds".
- - #address-cells : must be 1.
- - #size-cells : must be 0.
- - reg : BCM6328 LED controller address and size.
-
-Optional properties:
- - brcm,serial-leds : Boolean, enables Serial LEDs.
- Default : false
- - brcm,serial-mux : Boolean, enables Serial LEDs multiplexing.
- Default : false
- - brcm,serial-clk-low : Boolean, makes clock signal active low.
- Default : false
- - brcm,serial-dat-low : Boolean, makes data signal active low.
- Default : false
- - brcm,serial-shift-inv : Boolean, inverts Serial LEDs shift direction.
- Default : false
-
-Each LED is represented as a sub-node of the brcm,bcm6328-leds device.
-
-LED sub-node required properties:
- - reg : LED pin number (only LEDs 0 to 23 are valid).
-
-LED sub-node optional properties:
- a) Optional properties for sub-nodes related to software controlled LEDs:
- - label : see Documentation/devicetree/bindings/leds/common.txt
- - active-low : Boolean, makes LED active low.
- Default : false
- - default-state : see
- Documentation/devicetree/bindings/leds/common.txt
- - linux,default-trigger : see
- Documentation/devicetree/bindings/leds/common.txt
-
- b) Optional properties for sub-nodes related to hardware controlled LEDs:
- - brcm,hardware-controlled : Boolean, makes this LED hardware controlled.
- Default : false
- - brcm,link-signal-sources : An array of hardware link
- signal sources. Up to four link hardware signals can get muxed into
- these LEDs. Only valid for LEDs 0 to 7, where LED signals 0 to 3 may
- be muxed to LEDs 0 to 3, and signals 4 to 7 may be muxed to LEDs
- 4 to 7. A signal can be muxed to more than one LED, and one LED can
- have more than one source signal.
- - brcm,activity-signal-sources : An array of hardware activity
- signal sources. Up to four activity hardware signals can get muxed into
- these LEDs. Only valid for LEDs 0 to 7, where LED signals 0 to 3 may
- be muxed to LEDs 0 to 3, and signals 4 to 7 may be muxed to LEDs
- 4 to 7. A signal can be muxed to more than one LED, and one LED can
- have more than one source signal.
-
-Examples:
-Scenario 1 : BCM6328 with 4 EPHY LEDs
- leds0: led-controller@10000800 {
- compatible = "brcm,bcm6328-leds";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x10000800 0x24>;
-
- alarm_red@2 {
- reg = <2>;
- active-low;
- label = "red:alarm";
- };
- inet_green@3 {
- reg = <3>;
- active-low;
- label = "green:inet";
- };
- power_green@4 {
- reg = <4>;
- active-low;
- label = "green:power";
- default-state = "on";
- };
- ephy0_spd@17 {
- reg = <17>;
- brcm,hardware-controlled;
- };
- ephy1_spd@18 {
- reg = <18>;
- brcm,hardware-controlled;
- };
- ephy2_spd@19 {
- reg = <19>;
- brcm,hardware-controlled;
- };
- ephy3_spd@20 {
- reg = <20>;
- brcm,hardware-controlled;
- };
- };
-
-Scenario 2 : BCM63268 with Serial/GPHY0 LEDs
- leds0: led-controller@10001900 {
- compatible = "brcm,bcm6328-leds";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x10001900 0x24>;
- brcm,serial-leds;
- brcm,serial-dat-low;
- brcm,serial-shift-inv;
-
- gphy0_spd0@0 {
- reg = <0>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <0>;
- };
- gphy0_spd1@1 {
- reg = <1>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <1>;
- };
- inet_red@2 {
- reg = <2>;
- active-low;
- label = "red:inet";
- };
- dsl_green@3 {
- reg = <3>;
- active-low;
- label = "green:dsl";
- };
- usb_green@4 {
- reg = <4>;
- active-low;
- label = "green:usb";
- };
- wps_green@7 {
- reg = <7>;
- active-low;
- label = "green:wps";
- };
- inet_green@8 {
- reg = <8>;
- active-low;
- label = "green:inet";
- };
- ephy0_act@9 {
- reg = <9>;
- brcm,hardware-controlled;
- };
- ephy1_act@10 {
- reg = <10>;
- brcm,hardware-controlled;
- };
- ephy2_act@11 {
- reg = <11>;
- brcm,hardware-controlled;
- };
- gphy0_act@12 {
- reg = <12>;
- brcm,hardware-controlled;
- };
- ephy0_spd@13 {
- reg = <13>;
- brcm,hardware-controlled;
- };
- ephy1_spd@14 {
- reg = <14>;
- brcm,hardware-controlled;
- };
- ephy2_spd@15 {
- reg = <15>;
- brcm,hardware-controlled;
- };
- power_green@20 {
- reg = <20>;
- active-low;
- label = "green:power";
- default-state = "on";
- };
- };
-
-Scenario 3 : BCM6362 with 1 LED for each EPHY
- leds0: led-controller@10001900 {
- compatible = "brcm,bcm6328-leds";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x10001900 0x24>;
-
- usb@0 {
- reg = <0>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <0>;
- brcm,activity-signal-sources = <0>;
- /* USB link/activity routed to USB LED */
- };
- inet@1 {
- reg = <1>;
- brcm,hardware-controlled;
- brcm,activity-signal-sources = <1>;
- /* INET activity routed to INET LED */
- };
- ephy0@4 {
- reg = <4>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <4>;
- /* EPHY0 link routed to EPHY0 LED */
- };
- ephy1@5 {
- reg = <5>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <5>;
- /* EPHY1 link routed to EPHY1 LED */
- };
- ephy2@6 {
- reg = <6>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <6>;
- /* EPHY2 link routed to EPHY2 LED */
- };
- ephy3@7 {
- reg = <7>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <7>;
- /* EPHY3 link routed to EPHY3 LED */
- };
- power_green@20 {
- reg = <20>;
- active-low;
- label = "green:power";
- default-state = "on";
- };
- };
-
-Scenario 4 : BCM6362 with 1 LED for all EPHYs
- leds0: led-controller@10001900 {
- compatible = "brcm,bcm6328-leds";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x10001900 0x24>;
-
- usb@0 {
- reg = <0>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <0 1>;
- brcm,activity-signal-sources = <0 1>;
- /* USB/INET link/activity routed to USB LED */
- };
- ephy@4 {
- reg = <4>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <4 5 6 7>;
- /* EPHY0/1/2/3 link routed to EPHY0 LED */
- };
- power_green@20 {
- reg = <20>;
- active-low;
- label = "green:power";
- default-state = "on";
- };
- };
-
-Scenario 5 : BCM6362 with EPHY LEDs swapped
- leds0: led-controller@10001900 {
- compatible = "brcm,bcm6328-leds";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x10001900 0x24>;
-
- usb@0 {
- reg = <0>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <0>;
- brcm,activity-signal-sources = <0 1>;
- /* USB link/act and INET act routed to USB LED */
- };
- ephy0@4 {
- reg = <4>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <7>;
- /* EPHY3 link routed to EPHY0 LED */
- };
- ephy1@5 {
- reg = <5>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <6>;
- /* EPHY2 link routed to EPHY1 LED */
- };
- ephy2@6 {
- reg = <6>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <5>;
- /* EPHY1 link routed to EPHY2 LED */
- };
- ephy3@7 {
- reg = <7>;
- brcm,hardware-controlled;
- brcm,link-signal-sources = <4>;
- /* EPHY0 link routed to EPHY3 LED */
- };
- power_green@20 {
- reg = <20>;
- active-low;
- label = "green:power";
- default-state = "on";
- };
- };
diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml b/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml
new file mode 100644
index 000000000000..f3a3ef992929
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml
@@ -0,0 +1,400 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-bcm6328.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LEDs connected to Broadcom BCM6328 controller
+
+maintainers:
+ - Álvaro Fernández Rojas <noltari@gmail.com>
+
+description: |
+ This controller is present on BCM6318, BCM6328, BCM6362 and BCM63268.
+ In these SoCs it's possible to control LEDs both as GPIOs or by hardware.
+ However, on some devices there are Serial LEDs (LEDs connected to a 74x164
+ controller), which can either be controlled by software (exporting the 74x164
+ as spi-gpio. See
+ Documentation/devicetree/bindings/gpio/fairchild,74hc595.yaml), or by hardware
+ using this driver.
+ Some of these Serial LEDs are hardware controlled (e.g. ethernet LEDs) and
+ exporting the 74x164 as spi-gpio prevents those LEDs to be hardware
+ controlled, so the only chance to keep them working is by using this driver.
+
+ BCM6328 LED controller has a HWDIS register, which controls whether a LED
+ should be controlled by a hardware signal instead of the MODE register value,
+ with 0 meaning hardware control enabled and 1 hardware control disabled. This
+ is usually 1:1 for hardware to LED signals, but through the activity/link
+ registers you have some limited control over rerouting the LEDs (as
+ explained later in brcm,link-signal-sources). Even if a LED is hardware
+ controlled you are still able to make it blink or light it up if it isn't,
+ but you can't turn it off if the hardware decides to light it up. For this
+ reason, hardware controlled LEDs aren't registered as LED class devices.
+
+ Each LED is represented as a sub-node of the brcm,bcm6328-leds device.
+
+properties:
+ compatible:
+ const: brcm,bcm6328-leds
+
+ reg:
+ maxItems: 1
+
+ brcm,serial-leds:
+ type: boolean
+ description: Enables Serial LEDs.
+
+ brcm,serial-mux:
+ type: boolean
+ description: Enables Serial LEDs multiplexing.
+
+ brcm,serial-clk-low:
+ type: boolean
+ description: Makes clock signal active low.
+
+ brcm,serial-dat-low:
+ type: boolean
+ description: Makes data signal active low.
+
+ brcm,serial-shift-inv:
+ type: boolean
+ description: Inverts Serial LEDs shift direction.
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "@[a-f0-9]+$":
+ type: object
+
+ $ref: common.yaml#
+
+ properties:
+ reg:
+ items:
+ - maximum: 23
+ description: LED pin number (only LEDs 0 to 23 are valid).
+
+ brcm,hardware-controlled:
+ type: boolean
+ description: Makes this LED hardware controlled.
+
+ brcm,link-signal-sources:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 4
+ description: >
+ An array of hardware link signal sources. Up to four link hardware
+ signals can get muxed into these LEDs. Only valid for LEDs 0 to 7,
+ where LED signals 0 to 3 may be muxed to LEDs 0 to 3, and signals 4 to
+ 7 may be muxed to LEDs 4 to 7. A signal can be muxed to more than one
+ LED, and one LED can have more than one source signal.
+
+ brcm,activity-signal-sources:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 4
+ description: >
+ An array of hardware activity signal sources. Up to four activity
+ hardware signals can get muxed into these LEDs. Only valid for LEDs 0
+ to 7, where LED signals 0 to 3 may be muxed to LEDs 0 to 3, and
+ signals 4 to 7 may be muxed to LEDs 4 to 7. A signal can be muxed to
+ more than one LED, and one LED can have more than one source signal.
+
+ required:
+ - reg
+
+ unevaluatedProperties: false
+
+required:
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ /* BCM6328 with 4 EPHY LEDs */
+ led-controller@10000800 {
+ compatible = "brcm,bcm6328-leds";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x10000800 0x24>;
+
+ alarm_red@2 {
+ reg = <2>;
+ active-low;
+ label = "red:alarm";
+ };
+
+ inet_green@3 {
+ reg = <3>;
+ active-low;
+ label = "green:inet";
+ };
+
+ power_green@4 {
+ reg = <4>;
+ active-low;
+ label = "green:power";
+ default-state = "on";
+ };
+
+ ephy0_spd@17 {
+ reg = <17>;
+ brcm,hardware-controlled;
+ };
+
+ ephy1_spd@18 {
+ reg = <18>;
+ brcm,hardware-controlled;
+ };
+
+ ephy2_spd@19 {
+ reg = <19>;
+ brcm,hardware-controlled;
+ };
+
+ ephy3_spd@20 {
+ reg = <20>;
+ brcm,hardware-controlled;
+ };
+ };
+ - |
+ /* BCM63268 with Serial/GPHY0 LEDs */
+ led-controller@10001900 {
+ compatible = "brcm,bcm6328-leds";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x10001900 0x24>;
+ brcm,serial-leds;
+ brcm,serial-dat-low;
+ brcm,serial-shift-inv;
+
+ gphy0_spd0@0 {
+ reg = <0>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <0>;
+ };
+
+ gphy0_spd1@1 {
+ reg = <1>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <1>;
+ };
+
+ inet_red@2 {
+ reg = <2>;
+ active-low;
+ label = "red:inet";
+ };
+
+ dsl_green@3 {
+ reg = <3>;
+ active-low;
+ label = "green:dsl";
+ };
+
+ usb_green@4 {
+ reg = <4>;
+ active-low;
+ label = "green:usb";
+ };
+
+ wps_green@7 {
+ reg = <7>;
+ active-low;
+ label = "green:wps";
+ };
+
+ inet_green@8 {
+ reg = <8>;
+ active-low;
+ label = "green:inet";
+ };
+
+ ephy0_act@9 {
+ reg = <9>;
+ brcm,hardware-controlled;
+ };
+
+ ephy1_act@10 {
+ reg = <10>;
+ brcm,hardware-controlled;
+ };
+
+ ephy2_act@11 {
+ reg = <11>;
+ brcm,hardware-controlled;
+ };
+
+ gphy0_act@12 {
+ reg = <12>;
+ brcm,hardware-controlled;
+ };
+
+ ephy0_spd@13 {
+ reg = <13>;
+ brcm,hardware-controlled;
+ };
+
+ ephy1_spd@14 {
+ reg = <14>;
+ brcm,hardware-controlled;
+ };
+
+ ephy2_spd@15 {
+ reg = <15>;
+ brcm,hardware-controlled;
+ };
+
+ power_green@20 {
+ reg = <20>;
+ active-low;
+ label = "green:power";
+ default-state = "on";
+ };
+ };
+ - |
+ /* BCM6362 with 1 LED for each EPHY */
+ led-controller@10001900 {
+ compatible = "brcm,bcm6328-leds";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x10001900 0x24>;
+
+ usb@0 {
+ reg = <0>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <0>;
+ brcm,activity-signal-sources = <0>;
+ /* USB link/activity routed to USB LED */
+ };
+
+ inet@1 {
+ reg = <1>;
+ brcm,hardware-controlled;
+ brcm,activity-signal-sources = <1>;
+ /* INET activity routed to INET LED */
+ };
+
+ ephy0@4 {
+ reg = <4>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <4>;
+ /* EPHY0 link routed to EPHY0 LED */
+ };
+
+ ephy1@5 {
+ reg = <5>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <5>;
+ /* EPHY1 link routed to EPHY1 LED */
+ };
+
+ ephy2@6 {
+ reg = <6>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <6>;
+ /* EPHY2 link routed to EPHY2 LED */
+ };
+
+ ephy3@7 {
+ reg = <7>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <7>;
+ /* EPHY3 link routed to EPHY3 LED */
+ };
+
+ power_green@20 {
+ reg = <20>;
+ active-low;
+ label = "green:power";
+ default-state = "on";
+ };
+ };
+ - |
+ /* BCM6362 with 1 LED for all EPHYs */
+ led-controller@10001900 {
+ compatible = "brcm,bcm6328-leds";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x10001900 0x24>;
+
+ usb@0 {
+ reg = <0>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <0 1>;
+ brcm,activity-signal-sources = <0 1>;
+ /* USB/INET link/activity routed to USB LED */
+ };
+
+ ephy@4 {
+ reg = <4>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <4 5 6 7>;
+ /* EPHY0/1/2/3 link routed to EPHY0 LED */
+ };
+
+ power_green@20 {
+ reg = <20>;
+ active-low;
+ label = "green:power";
+ default-state = "on";
+ };
+ };
+ - |
+ /* BCM6362 with EPHY LEDs swapped */
+ led-controller@10001900 {
+ compatible = "brcm,bcm6328-leds";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x10001900 0x24>;
+
+ usb@0 {
+ reg = <0>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <0>;
+ brcm,activity-signal-sources = <0 1>;
+ /* USB link/act and INET act routed to USB LED */
+ };
+
+ ephy0@4 {
+ reg = <4>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <7>;
+ /* EPHY3 link routed to EPHY0 LED */
+ };
+
+ ephy1@5 {
+ reg = <5>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <6>;
+ /* EPHY2 link routed to EPHY1 LED */
+ };
+
+ ephy2@6 {
+ reg = <6>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <5>;
+ /* EPHY1 link routed to EPHY2 LED */
+ };
+
+ ephy3@7 {
+ reg = <7>;
+ brcm,hardware-controlled;
+ brcm,link-signal-sources = <4>;
+ /* EPHY0 link routed to EPHY3 LED */
+ };
+
+ power_green@20 {
+ reg = <20>;
+ active-low;
+ label = "green:power";
+ default-state = "on";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt
index 6e51c6b91ee5..211ffc3c4a20 100644
--- a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt
+++ b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt
@@ -25,8 +25,6 @@ LED sub-node required properties:
LED sub-node optional properties:
- label : see Documentation/devicetree/bindings/leds/common.txt
- - active-low : Boolean, makes LED active low.
- Default : false
- default-state : see
Documentation/devicetree/bindings/leds/common.txt
- linux,default-trigger : see
diff --git a/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml
index 37445c68cdef..bb40bb9e036e 100644
--- a/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Common properties for the multicolor LED class.
maintainers:
- - Dan Murphy <dmurphy@ti.com>
+ - Andrew Davis <afd@ti.com>
description: |
Bindings for multi color LEDs show how to describe current outputs of
@@ -19,22 +19,22 @@ description: |
LED class. Common LED nodes and properties are inherited from the common.yaml
within this documentation directory.
-patternProperties:
- "^multi-led@([0-9a-f])$":
- type: object
- description: Represents the LEDs that are to be grouped.
- properties:
- color:
- description: |
- For multicolor LED support this property should be defined as either
- LED_COLOR_ID_RGB or LED_COLOR_ID_MULTI which can be found in
- include/linux/leds/common.h.
- enum: [ 8, 9 ]
-
- $ref: "common.yaml#"
-
- required:
- - color
+properties:
+ $nodename:
+ pattern: "^multi-led(@[0-9a-f])?$"
+
+ color:
+ description: |
+ For multicolor LED support this property should be defined as either
+ LED_COLOR_ID_RGB or LED_COLOR_ID_MULTI which can be found in
+ include/dt-bindings/leds/common.h.
+ enum: [ 8, 9 ]
+
+required:
+ - color
+
+allOf:
+ - $ref: common.yaml#
additionalProperties: true
diff --git a/Documentation/devicetree/bindings/leds/leds-consumer.yaml b/Documentation/devicetree/bindings/leds/leds-consumer.yaml
new file mode 100644
index 000000000000..fe6a0faa1d3b
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-consumer.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-consumer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common leds consumer
+
+maintainers:
+ - Aleksandrs Vinarskis <alex@vinarskis.com>
+
+description:
+ Some LED defined in DT are required by other DT consumers, for example
+ v4l2 subnode may require privacy or flash LED. Unlike trigger-source
+ approach which is typically used as 'soft' binding, referencing LED
+ devices by phandle makes things simpler when 'hard' binding is desired.
+
+ Document LED properties that its consumers may define.
+
+select: true
+
+properties:
+ leds:
+ oneOf:
+ - type: object
+ - $ref: /schemas/types.yaml#/definitions/phandle-array
+ description:
+ A list of LED device(s) required by a particular consumer.
+ items:
+ maxItems: 1
+
+ led-names:
+ description:
+ A list of device name(s). Used to map LED devices to their respective
+ functions, when consumer requires more than one LED.
+
+additionalProperties: true
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ leds {
+ compatible = "gpio-leds";
+
+ privacy_led: privacy-led {
+ color = <LED_COLOR_ID_RED>;
+ default-state = "off";
+ function = LED_FUNCTION_INDICATOR;
+ gpios = <&tlmm 110 GPIO_ACTIVE_HIGH>;
+ };
+ };
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ v4l2_node: camera@36 {
+ reg = <0x36>;
+
+ leds = <&privacy_led>;
+ led-names = "privacy";
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.yaml b/Documentation/devicetree/bindings/leds/leds-gpio.yaml
index 7ad2baeda0b0..7e11703acbd6 100644
--- a/Documentation/devicetree/bindings/leds/leds-gpio.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-gpio.yaml
@@ -23,8 +23,8 @@ patternProperties:
# node name to at least catch some child nodes.
"(^led-[0-9a-f]$|led)":
type: object
-
$ref: common.yaml#
+ unevaluatedProperties: false
properties:
gpios:
diff --git a/Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml
new file mode 100644
index 000000000000..5c9cfa39396b
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-group-multicolor.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-group-multicolor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Multi-color LED built with monochromatic LEDs
+
+maintainers:
+ - Jean-Jacques Hiblot <jjhiblot@traphandler.com>
+
+description: |
+ This driver combines several monochromatic LEDs into one multi-color
+ LED using the multicolor LED class.
+
+properties:
+ compatible:
+ const: leds-group-multicolor
+
+ leds: true
+
+required:
+ - leds
+
+allOf:
+ - $ref: leds-class-multicolor.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ monochromatic-leds {
+ compatible = "gpio-leds";
+
+ led0: led-0 {
+ gpios = <&mcu_pio 0 GPIO_ACTIVE_LOW>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led1: led-1 {
+ gpios = <&mcu_pio 1 GPIO_ACTIVE_HIGH>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led2: led-2 {
+ gpios = <&mcu_pio 2 GPIO_ACTIVE_HIGH>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+
+ multi-led {
+ compatible = "leds-group-multicolor";
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_INDICATOR;
+ leds = <&led0>, <&led1>, <&led2>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-is31fl319x.txt b/Documentation/devicetree/bindings/leds/leds-is31fl319x.txt
deleted file mode 100644
index 676d43ec8169..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-is31fl319x.txt
+++ /dev/null
@@ -1,61 +0,0 @@
-LEDs connected to is31fl319x LED controller chip
-
-Required properties:
-- compatible : Should be any of
- "issi,is31fl3190"
- "issi,is31fl3191"
- "issi,is31fl3193"
- "issi,is31fl3196"
- "issi,is31fl3199"
- "si-en,sn3199".
-- #address-cells: Must be 1.
-- #size-cells: Must be 0.
-- reg: 0x64, 0x65, 0x66, or 0x67.
-
-Optional properties:
-- audio-gain-db : audio gain selection for external analog modulation input.
- Valid values: 0 - 21, step by 3 (rounded down)
- Default: 0
-- shutdown-gpios : Specifier of the GPIO connected to SDB pin of the chip.
-
-Each led is represented as a sub-node of the issi,is31fl319x device.
-There can be less leds subnodes than the chip can support but not more.
-
-Required led sub-node properties:
-- reg : number of LED line
- Valid values: 1 - number of leds supported by the chip variant.
-
-Optional led sub-node properties:
-- label : see Documentation/devicetree/bindings/leds/common.txt.
-- linux,default-trigger :
- see Documentation/devicetree/bindings/leds/common.txt.
-- led-max-microamp : (optional)
- Valid values: 5000 - 40000, step by 5000 (rounded down)
- Default: 20000 (20 mA)
- Note: a driver will take the lowest of all led limits since the
- chip has a single global setting. The lowest value will be chosen
- due to the PWM specificity, where lower brightness is achieved
- by reducing the dury-cycle of pulses and not the current, which
- will always have its peak value equal to led-max-microamp.
-
-Examples:
-
-fancy_leds: leds@65 {
- compatible = "issi,is31fl3196";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x65>;
- shutdown-gpios = <&gpio0 11 GPIO_ACTIVE_HIGH>;
-
- red_aux: led@1 {
- label = "red:aux";
- reg = <1>;
- led-max-microamp = <10000>;
- };
-
- green_power: led@5 {
- label = "green:power";
- reg = <5>;
- linux,default-trigger = "default-on";
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-ktd2692.txt b/Documentation/devicetree/bindings/leds/leds-ktd2692.txt
deleted file mode 100644
index 853737452580..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-ktd2692.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-* Kinetic Technologies - KTD2692 Flash LED Driver
-
-KTD2692 is the ideal power solution for high-power flash LEDs.
-It uses ExpressWire single-wire programming for maximum flexibility.
-
-The ExpressWire interface through CTRL pin can control LED on/off and
-enable/disable the IC, Movie(max 1/3 of Flash current) / Flash mode current,
-Flash timeout, LVP(low voltage protection).
-
-Also, When the AUX pin is pulled high while CTRL pin is high,
-LED current will be ramped up to the flash-mode current level.
-
-Required properties:
-- compatible : Should be "kinetic,ktd2692".
-- ctrl-gpios : Specifier of the GPIO connected to CTRL pin.
-- aux-gpios : Specifier of the GPIO connected to AUX pin.
-
-Optional properties:
-- vin-supply : "vin" LED supply (2.7V to 5.5V).
- See Documentation/devicetree/bindings/regulator/regulator.txt
-
-A discrete LED element connected to the device must be represented by a child
-node - See Documentation/devicetree/bindings/leds/common.txt
-
-Required properties for flash LED child nodes:
- See Documentation/devicetree/bindings/leds/common.txt
-- led-max-microamp : Minimum Threshold for Timer protection
- is defined internally (Maximum 300mA).
-- flash-max-microamp : Flash LED maximum current
- Formula : I(mA) = 15000 / Rset.
-- flash-max-timeout-us : Flash LED maximum timeout.
-
-Optional properties for flash LED child nodes:
-- label : See Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
-ktd2692 {
- compatible = "kinetic,ktd2692";
- ctrl-gpios = <&gpc0 1 0>;
- aux-gpios = <&gpc0 2 0>;
- vin-supply = <&vbat>;
-
- flash-led {
- label = "ktd2692-flash";
- led-max-microamp = <300000>;
- flash-max-microamp = <1500000>;
- flash-max-timeout-us = <1835000>;
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-lgm.yaml b/Documentation/devicetree/bindings/leds/leds-lgm.yaml
index f8d7963c3a13..8b3b3bf1eaf2 100644
--- a/Documentation/devicetree/bindings/leds/leds-lgm.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-lgm.yaml
@@ -56,7 +56,8 @@ properties:
patternProperties:
"^led@[0-2]$":
- type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
properties:
reg:
@@ -64,6 +65,9 @@ properties:
minimum: 0
maximum: 2
+ led-gpios:
+ maxItems: 1
+
intel,sso-hw-trigger:
type: boolean
description: This property indicates Hardware driven/control LED.
@@ -118,14 +122,14 @@ examples:
reg = <0>;
function = "gphy";
color = <LED_COLOR_ID_GREEN>;
- led-gpio = <&ssogpio 0 0>;
+ led-gpios = <&ssogpio 0 0>;
};
led@2 {
reg = <2>;
function = LED_FUNCTION_POWER;
color = <LED_COLOR_ID_GREEN>;
- led-gpio = <&ssogpio 23 0>;
+ led-gpios = <&ssogpio 23 0>;
};
};
};
diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
deleted file mode 100644
index b1103d961d6c..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt
+++ /dev/null
@@ -1,65 +0,0 @@
-* Texas Instruments - LM3692x Highly Efficient White LED Driver
-
-The LM3692x is an ultra-compact, highly efficient,
-white-LED driver designed for LCD display backlighting.
-
-The main difference between the LM36922 and LM36923 is the number of
-LED strings it supports. The LM36922 supports two strings while the LM36923
-supports three strings.
-
-Required properties:
- - compatible:
- "ti,lm36922"
- "ti,lm36923"
- - reg : I2C slave address
- - #address-cells : 1
- - #size-cells : 0
-
-Optional properties:
- - enable-gpios : gpio pin to enable/disable the device.
- - vled-supply : LED supply
- - ti,ovp-microvolt: Overvoltage protection in
- micro-volt, can be 17000000, 21000000, 25000000 or
- 29000000. If ti,ovp-microvolt is not specified it
- defaults to 29000000.
-
-Required child properties:
- - reg : 0 - Will enable all LED sync paths
- 1 - Will enable the LED1 sync
- 2 - Will enable the LED2 sync
- 3 - Will enable the LED3 sync (LM36923 only)
-
-Optional child properties:
- - function : see Documentation/devicetree/bindings/leds/common.txt
- - color : see Documentation/devicetree/bindings/leds/common.txt
- - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- - linux,default-trigger :
- see Documentation/devicetree/bindings/leds/common.txt
- - led-max-microamp :
- see Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
-#include <dt-bindings/leds/common.h>
-
-led-controller@36 {
- compatible = "ti,lm3692x";
- reg = <0x36>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
- vled-supply = <&vbatt>;
- ti,ovp-microvolt = <29000000>;
-
- led@0 {
- reg = <0>;
- function = LED_FUNCTION_BACKLIGHT;
- color = <LED_COLOR_ID_WHITE>;
- linux,default-trigger = "backlight";
- led-max-microamp = <20000>;
- };
-}
-
-For more product information please see the link below:
-https://www.ti.com/lit/ds/snvsa29/snvsa29.pdf
diff --git a/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml
index c192b5feadc7..23f809906ba7 100644
--- a/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-lp50xx.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: LED driver for LP50XX RGB LED from Texas Instruments.
maintainers:
- - Dan Murphy <dmurphy@ti.com>
+ - Andrew Davis <afd@ti.com>
description: |
The LP50XX is multi-channel, I2C RGB LED Drivers that can group RGB LEDs into
@@ -55,8 +55,9 @@ properties:
patternProperties:
'^multi-led@[0-9a-f]$':
type: object
- allOf:
- - $ref: leds-class-multicolor.yaml#
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
properties:
reg:
minItems: 1
@@ -66,10 +67,29 @@ patternProperties:
for the child node. The LED modules can either be used stand alone
or grouped into a module bank.
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
patternProperties:
- "(^led-[0-9a-f]$|led)":
+ "^led@[0-9a-f]+$":
type: object
$ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ items:
+ - minimum: 0
+ maximum: 2
+
+ description:
+ This property denotes the index within the LED bank.
+
+ required:
+ - reg
required:
- compatible
@@ -79,60 +99,66 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/gpio/gpio.h>
- #include <dt-bindings/leds/common.h>
-
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- led-controller@14 {
- compatible = "ti,lp5009";
- reg = <0x14>;
- #address-cells = <1>;
- #size-cells = <0>;
- enable-gpios = <&gpio1 16>;
-
- multi-led@1 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x1>;
- color = <LED_COLOR_ID_RGB>;
- function = LED_FUNCTION_CHARGING;
-
- led-0 {
- color = <LED_COLOR_ID_RED>;
- };
-
- led-1 {
- color = <LED_COLOR_ID_GREEN>;
- };
-
- led-2 {
- color = <LED_COLOR_ID_BLUE>;
- };
- };
-
- multi-led@2 {
- #address-cells = <1>;
- #size-cells = <2>;
- reg = <0x2 0x3 0x5>;
- color = <LED_COLOR_ID_RGB>;
- function = LED_FUNCTION_STANDBY;
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
- led-6 {
- color = <LED_COLOR_ID_RED>;
- };
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
- led-7 {
- color = <LED_COLOR_ID_GREEN>;
+ led-controller@14 {
+ compatible = "ti,lp5009";
+ reg = <0x14>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ enable-gpios = <&gpio1 16>;
+
+ multi-led@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x1>;
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_CHARGING;
+
+ led@0 {
+ reg = <0x0>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@1 {
+ reg = <0x1>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@2 {
+ reg = <0x2>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
};
- led-8 {
- color = <LED_COLOR_ID_BLUE>;
+ multi-led@3 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x3>, <0x4>, <0x5>;
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_STANDBY;
+
+ led@0 {
+ reg = <0x0>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@1 {
+ reg = <0x1>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@2 {
+ reg = <0x2>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
};
- };
- };
+ };
};
...
diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml
index f552cd143d5b..fe8aaecf3010 100644
--- a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml
@@ -28,6 +28,7 @@ properties:
- national,lp5523
- ti,lp55231
- ti,lp5562
+ - ti,lp5569
- ti,lp8501
reg:
@@ -43,11 +44,13 @@ properties:
- 1 # internal
- 2 # external
- enable-gpio:
+ enable-gpios:
maxItems: 1
description: |
GPIO attached to the chip's enable pin
+ label: true
+
pwr-sel:
$ref: /schemas/types.yaml#/definitions/uint8
description: |
@@ -64,10 +67,59 @@ properties:
'#size-cells':
const: 0
+ ti,charge-pump-mode:
+ description:
+ Set the operating mode of the internal charge pump as defined in
+ <dt-bindings/leds/leds-lp55xx.h>.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 3 # auto
+ maximum: 3
+
patternProperties:
- "(^led@[0-9a-f]$|led)":
+ '^multi-led@[0-8]$':
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ maximum: 8
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ patternProperties:
+ "^led@[0-8]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ led-cur:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: |
+ Current setting at each LED channel (mA x10, 0 if LED is not connected)
+ minimum: 0
+ maximum: 255
+
+ max-cur:
+ $ref: /schemas/types.yaml#/definitions/uint8
+ description: Maximum current at each LED channel.
+
+ reg:
+ maximum: 8
+
+ required:
+ - reg
+
+ "^led@[0-8]$":
type: object
$ref: common.yaml#
+ unevaluatedProperties: false
+
properties:
led-cur:
$ref: /schemas/types.yaml#/definitions/uint8
@@ -78,7 +130,7 @@ patternProperties:
max-cur:
$ref: /schemas/types.yaml#/definitions/uint8
- description: Maximun current at each LED channel.
+ description: Maximum current at each LED channel.
reg:
description: |
@@ -100,6 +152,16 @@ patternProperties:
$ref: /schemas/types.yaml#/definitions/string
description: name of channel
+if:
+ not:
+ properties:
+ compatible:
+ contains:
+ const: ti,lp8501
+then:
+ properties:
+ pwr-sel: false
+
required:
- compatible
- reg
@@ -108,119 +170,121 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/leds/common.h>
-
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- led-controller@32 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "ti,lp8501";
- reg = <0x32>;
- clock-mode = /bits/ 8 <2>;
- pwr-sel = /bits/ 8 <3>; /* D1~9 connected to VOUT */
-
- led@0 {
- reg = <0>;
- chan-name = "d1";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@1 {
- reg = <1>;
- chan-name = "d2";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@2 {
- reg = <2>;
- chan-name = "d3";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@3 {
- reg = <3>;
- chan-name = "d4";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@4 {
- reg = <4>;
- chan-name = "d5";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@5 {
- reg = <5>;
- chan-name = "d6";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@6 {
- reg = <6>;
- chan-name = "d7";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@7 {
- reg = <7>;
- chan-name = "d8";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
-
- led@8 {
- reg = <8>;
- chan-name = "d9";
- led-cur = /bits/ 8 <0x14>;
- max-cur = /bits/ 8 <0x20>;
- };
+ #include <dt-bindings/leds/common.h>
+ #include <dt-bindings/leds/leds-lp55xx.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@32 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "ti,lp8501";
+ reg = <0x32>;
+ clock-mode = /bits/ 8 <2>;
+ pwr-sel = /bits/ 8 <3>; /* D1~9 connected to VOUT */
+ ti,charge-pump-mode = <LP55XX_CP_BYPASS>;
+
+ led@0 {
+ reg = <0>;
+ chan-name = "d1";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@1 {
+ reg = <1>;
+ chan-name = "d2";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@2 {
+ reg = <2>;
+ chan-name = "d3";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@3 {
+ reg = <3>;
+ chan-name = "d4";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@4 {
+ reg = <4>;
+ chan-name = "d5";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@5 {
+ reg = <5>;
+ chan-name = "d6";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@6 {
+ reg = <6>;
+ chan-name = "d7";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@7 {
+ reg = <7>;
+ chan-name = "d8";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
+
+ led@8 {
+ reg = <8>;
+ chan-name = "d9";
+ led-cur = /bits/ 8 <0x14>;
+ max-cur = /bits/ 8 <0x20>;
+ };
};
- led-controller@33 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "national,lp5523";
- reg = <0x33>;
- clock-mode = /bits/ 8 <0>;
-
- multi-led@2 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x2>;
- color = <LED_COLOR_ID_RGB>;
- function = LED_FUNCTION_STANDBY;
- linux,default-trigger = "heartbeat";
-
- led@0 {
- led-cur = /bits/ 8 <50>;
- max-cur = /bits/ 8 <100>;
- reg = <0x0>;
- color = <LED_COLOR_ID_GREEN>;
- };
-
- led@1 {
- led-cur = /bits/ 8 <50>;
- max-cur = /bits/ 8 <100>;
- reg = <0x1>;
- color = <LED_COLOR_ID_BLUE>;
- };
-
- led@6 {
- led-cur = /bits/ 8 <50>;
- max-cur = /bits/ 8 <100>;
- reg = <0x6>;
- color = <LED_COLOR_ID_RED>;
- };
+ led-controller@33 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "national,lp5523";
+ reg = <0x33>;
+ clock-mode = /bits/ 8 <0>;
+
+ multi-led@2 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x2>;
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_STANDBY;
+ linux,default-trigger = "heartbeat";
+
+ led@0 {
+ led-cur = /bits/ 8 <50>;
+ max-cur = /bits/ 8 <100>;
+ reg = <0x0>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@1 {
+ led-cur = /bits/ 8 <50>;
+ max-cur = /bits/ 8 <100>;
+ reg = <0x1>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+
+ led@6 {
+ led-cur = /bits/ 8 <50>;
+ max-cur = /bits/ 8 <100>;
+ reg = <0x6>;
+ color = <LED_COLOR_ID_RED>;
+ };
};
};
};
diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt
deleted file mode 100644
index 8bb25749a3da..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-* Texas Instruments - lp8860 4-Channel LED Driver
-
-The LP8860-Q1 is an high-efficiency LED
-driver with boost controller. It has 4 high-precision
-current sinks that can be controlled by a PWM input
-signal, a SPI/I2C master, or both.
-
-Required properties:
- - compatible :
- "ti,lp8860"
- - reg : I2C slave address
- - #address-cells : 1
- - #size-cells : 0
-
-Optional properties:
- - enable-gpios : gpio pin to enable (active high)/disable the device.
- - vled-supply : LED supply
-
-Required child properties:
- - reg : 0
-
-Optional child properties:
- - function : see Documentation/devicetree/bindings/leds/common.txt
- - color : see Documentation/devicetree/bindings/leds/common.txt
- - label : see Documentation/devicetree/bindings/leds/common.txt (deprecated)
- - linux,default-trigger :
- see Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
-#include <dt-bindings/leds/common.h>
-
-led-controller@2d {
- compatible = "ti,lp8860";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x2d>;
- enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
- vled-supply = <&vbatt>;
-
- led@0 {
- reg = <0>;
- function = LED_FUNCTION_BACKLIGHT;
- color = <LED_COLOR_ID_WHITE>;
- linux,default-trigger = "backlight";
- };
-}
-
-For more product information please see the link below:
-https://www.ti.com/product/lp8860-q1
diff --git a/Documentation/devicetree/bindings/leds/leds-max77650.yaml b/Documentation/devicetree/bindings/leds/leds-max77650.yaml
index c6f96cabd4d1..fdb08f44a45d 100644
--- a/Documentation/devicetree/bindings/leds/leds-max77650.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-max77650.yaml
@@ -30,9 +30,8 @@ properties:
patternProperties:
"^led@[0-2]$":
- type: object
- description: |
- Properties for a single LED.
+ $ref: common.yaml#
+ unevaluatedProperties: false
properties:
reg:
@@ -41,10 +40,6 @@ patternProperties:
minimum: 0
maximum: 2
- label: true
-
- linux,default-trigger: true
-
required:
- compatible
- "#address-cells"
diff --git a/Documentation/devicetree/bindings/leds/leds-mt6323.txt b/Documentation/devicetree/bindings/leds/leds-mt6323.txt
deleted file mode 100644
index 45bf9f7d85f3..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-mt6323.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-Device Tree Bindings for LED support on MT6323 PMIC
-
-MT6323 LED controller is subfunction provided by MT6323 PMIC, so the LED
-controllers are defined as the subnode of the function node provided by MT6323
-PMIC controller that is being defined as one kind of Muti-Function Device (MFD)
-using shared bus called PMIC wrapper for each subfunction to access remote
-MT6323 PMIC hardware.
-
-For MT6323 MFD bindings see:
-Documentation/devicetree/bindings/mfd/mt6397.txt
-For MediaTek PMIC wrapper bindings see:
-Documentation/devicetree/bindings/soc/mediatek/pwrap.txt
-
-Required properties:
-- compatible : Must be "mediatek,mt6323-led"
-- address-cells : Must be 1
-- size-cells : Must be 0
-
-Each led is represented as a child node of the mediatek,mt6323-led that
-describes the initial behavior for each LED physically and currently only four
-LED child nodes can be supported.
-
-Required properties for the LED child node:
-- reg : LED channel number (0..3)
-
-Optional properties for the LED child node:
-- label : See Documentation/devicetree/bindings/leds/common.txt
-- linux,default-trigger : See Documentation/devicetree/bindings/leds/common.txt
-- default-state: See Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
- mt6323: pmic {
- compatible = "mediatek,mt6323";
-
- ...
-
- mt6323led: leds {
- compatible = "mediatek,mt6323-led";
- #address-cells = <1>;
- #size-cells = <0>;
-
- led@0 {
- reg = <0>;
- label = "LED0";
- linux,default-trigger = "timer";
- default-state = "on";
- };
- led@1 {
- reg = <1>;
- label = "LED1";
- default-state = "off";
- };
- led@2 {
- reg = <2>;
- label = "LED2";
- default-state = "on";
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/leds/leds-mt6360.yaml b/Documentation/devicetree/bindings/leds/leds-mt6360.yaml
new file mode 100644
index 000000000000..d2e1d8afc302
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-mt6360.yaml
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-mt6360.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LED driver for MT6360 PMIC from MediaTek Integrated.
+
+maintainers:
+ - Gene Chen <gene_chen@richtek.com>
+
+description: |
+ This module is part of the MT6360 MFD device.
+ see Documentation/devicetree/bindings/mfd/mediatek,mt6360.yaml
+ Add MT6360 LED driver include 2-channel Flash LED with torch/strobe mode,
+ and 4-channel RGB LED support Register/Flash/Breath Mode
+
+properties:
+ compatible:
+ const: mediatek,mt6360-led
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^multi-led@[0-5]$":
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: Index of the LED.
+ enum:
+ - 0 # LED output ISINK1
+ - 1 # LED output ISINK2
+ - 2 # LED output ISINK3
+ - 3 # LED output ISINKML
+ - 4 # LED output FLASH1
+ - 5 # LED output FLASH2
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^led@[0-2]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ enum: [0, 1, 2]
+
+ required:
+ - reg
+ - color
+
+ required:
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+ "^led@[0-5]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+ description:
+ Properties for a single LED.
+
+ properties:
+ reg:
+ enum: [0, 1, 2, 3, 4, 5]
+
+required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+ led-controller {
+ compatible = "mediatek,mt6360-led";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ multi-led@0 {
+ reg = <0>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_RGB>;
+ led-max-microamp = <24000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ led@0 {
+ reg = <0>;
+ color = <LED_COLOR_ID_RED>;
+ };
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ led@3 {
+ reg = <3>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_WHITE>;
+ led-max-microamp = <150000>;
+ };
+ led@4 {
+ reg = <4>;
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ function-enumerator = <1>;
+ led-max-microamp = <200000>;
+ flash-max-microamp = <500000>;
+ flash-max-timeout-us = <1024000>;
+ };
+ led@5 {
+ reg = <5>;
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ function-enumerator = <2>;
+ led-max-microamp = <200000>;
+ flash-max-microamp = <500000>;
+ flash-max-timeout-us = <1024000>;
+ };
+ };
+
+ - |
+ led-controller {
+ compatible = "mediatek,mt6360-led";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_RED>;
+ led-max-microamp = <24000>;
+ };
+ led@1 {
+ reg = <1>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_GREEN>;
+ led-max-microamp = <24000>;
+ };
+ led@2 {
+ reg = <2>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_BLUE>;
+ led-max-microamp = <24000>;
+ };
+ led@3 {
+ reg = <3>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_WHITE>;
+ led-max-microamp = <150000>;
+ };
+ led@4 {
+ reg = <4>;
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ function-enumerator = <1>;
+ led-max-microamp = <200000>;
+ flash-max-microamp = <500000>;
+ flash-max-timeout-us = <1024000>;
+ };
+ led@5 {
+ reg = <5>;
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ function-enumerator = <2>;
+ led-max-microamp = <200000>;
+ flash-max-microamp = <500000>;
+ flash-max-timeout-us = <1024000>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-pca9532.txt b/Documentation/devicetree/bindings/leds/leds-pca9532.txt
deleted file mode 100644
index f769c52e3643..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-pca9532.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-*NXP - pca9532 PWM LED Driver
-
-The PCA9532 family is SMBus I/O expander optimized for dimming LEDs.
-The PWM support 256 steps.
-
-Required properties:
- - compatible:
- "nxp,pca9530"
- "nxp,pca9531"
- "nxp,pca9532"
- "nxp,pca9533"
- - reg - I2C slave address
-
-Each led is represented as a sub-node of the nxp,pca9530.
-
-Optional sub-node properties:
- - label: see Documentation/devicetree/bindings/leds/common.txt
- - type: Output configuration, see dt-bindings/leds/leds-pca9532.h (default NONE)
- - linux,default-trigger: see Documentation/devicetree/bindings/leds/common.txt
- - default-state: see Documentation/devicetree/bindings/leds/common.txt
- This property is only valid for sub-nodes of type <PCA9532_TYPE_LED>.
-
-Example:
- #include <dt-bindings/leds/leds-pca9532.h>
-
- leds: pca9530@60 {
- compatible = "nxp,pca9530";
- reg = <0x60>;
-
- red-power {
- label = "pca:red:power";
- type = <PCA9532_TYPE_LED>;
- };
- green-power {
- label = "pca:green:power";
- type = <PCA9532_TYPE_LED>;
- };
- kernel-booting {
- type = <PCA9532_TYPE_LED>;
- default-state = "on";
- };
- sys-stat {
- type = <PCA9532_TYPE_LED>;
- default-state = "keep"; // don't touch, was set by U-Boot
- };
- };
-
-For more product information please see the link below:
-http://nxp.com/documents/data_sheet/PCA9532.pdf
diff --git a/Documentation/devicetree/bindings/leds/leds-pca955x.txt b/Documentation/devicetree/bindings/leds/leds-pca955x.txt
deleted file mode 100644
index 817f460f3a72..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-pca955x.txt
+++ /dev/null
@@ -1,89 +0,0 @@
-* NXP - pca955x LED driver
-
-The PCA955x family of chips are I2C LED blinkers whose pins not used
-to control LEDs can be used as general purpose I/Os. The GPIO pins can
-be input or output, and output pins can also be pulse-width controlled.
-
-Required properties:
-- compatible : should be one of :
- "nxp,pca9550"
- "nxp,pca9551"
- "nxp,pca9552"
- "ibm,pca9552"
- "nxp,pca9553"
-- #address-cells: must be 1
-- #size-cells: must be 0
-- reg: I2C slave address. depends on the model.
-
-Optional properties:
-- gpio-controller: allows pins to be used as GPIOs.
-- #gpio-cells: must be 2.
-- gpio-line-names: define the names of the GPIO lines
-
-LED sub-node properties:
-- reg : number of LED line.
- from 0 to 1 for the pca9550
- from 0 to 7 for the pca9551
- from 0 to 15 for the pca9552
- from 0 to 3 for the pca9553
-- type: (optional) either
- PCA955X_TYPE_NONE
- PCA955X_TYPE_LED
- PCA955X_TYPE_GPIO
- see dt-bindings/leds/leds-pca955x.h (default to LED)
-- label : (optional)
- see Documentation/devicetree/bindings/leds/common.txt
-- linux,default-trigger : (optional)
- see Documentation/devicetree/bindings/leds/common.txt
-
-Examples:
-
-pca9552: pca9552@60 {
- compatible = "nxp,pca9552";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x60>;
-
- gpio-controller;
- #gpio-cells = <2>;
- gpio-line-names = "GPIO12", "GPIO13", "GPIO14", "GPIO15";
-
- gpio@12 {
- reg = <12>;
- type = <PCA955X_TYPE_GPIO>;
- };
- gpio@13 {
- reg = <13>;
- type = <PCA955X_TYPE_GPIO>;
- };
- gpio@14 {
- reg = <14>;
- type = <PCA955X_TYPE_GPIO>;
- };
- gpio@15 {
- reg = <15>;
- type = <PCA955X_TYPE_GPIO>;
- };
-
- led@0 {
- label = "red:power";
- linux,default-trigger = "default-on";
- reg = <0>;
- type = <PCA955X_TYPE_LED>;
- };
- led@1 {
- label = "green:power";
- reg = <1>;
- type = <PCA955X_TYPE_LED>;
- };
- led@2 {
- label = "pca9552:yellow";
- reg = <2>;
- type = <PCA955X_TYPE_LED>;
- };
- led@3 {
- label = "pca9552:white";
- reg = <3>;
- type = <PCA955X_TYPE_LED>;
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-pm8058.txt b/Documentation/devicetree/bindings/leds/leds-pm8058.txt
deleted file mode 100644
index 89584c49aab2..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-pm8058.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-Qualcomm PM8058 LED driver
-
-The Qualcomm PM8058 is a multi-functional device which contains
-an LED driver block for up to six LEDs: three normal LEDs, two
-"flash" LEDs and one "keypad backlight" LED. The names are
-quoted because sometimes these LED drivers are used for wildly
-different things than flash or keypad backlight: their names
-are more of a suggestion than a hard-wired usecase.
-
-Hardware-wise the different LEDs support slightly different
-output currents. The "flash" LEDs do not need to charge nor
-do they support external triggers. They are just powerful LED
-drivers.
-
-The LEDs appear as children to the PM8058 device, with the
-proper compatible string. For the PM8058 bindings see:
-mfd/qcom-pm8xxx.txt.
-
-Each LED is represented as a sub-node of the syscon device. Each
-node's name represents the name of the corresponding LED.
-
-LED sub-node properties:
-
-Required properties:
-- compatible: one of
- "qcom,pm8058-led" (for the normal LEDs at 0x131, 0x132 and 0x133)
- "qcom,pm8058-keypad-led" (for the "keypad" LED at 0x48)
- "qcom,pm8058-flash-led" (for the "flash" LEDs at 0x49 and 0xFB)
-
-Optional properties:
-- label: see Documentation/devicetree/bindings/leds/common.txt
-- default-state: see Documentation/devicetree/bindings/leds/common.txt
-- linux,default-trigger: see Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
-qcom,ssbi@500000 {
- pmicintc: pmic@0 {
- compatible = "qcom,pm8058";
- led@48 {
- compatible = "qcom,pm8058-keypad-led";
- reg = <0x48>;
- label = "pm8050:white:keypad";
- default-state = "off";
- };
- led@131 {
- compatible = "qcom,pm8058-led";
- reg = <0x131>;
- label = "pm8058:red";
- default-state = "off";
- };
- led@132 {
- compatible = "qcom,pm8058-led";
- reg = <0x132>;
- label = "pm8058:yellow";
- default-state = "off";
- linux,default-trigger = "mmc0";
- };
- led@133 {
- compatible = "qcom,pm8058-led";
- reg = <0x133>;
- label = "pm8058:green";
- default-state = "on";
- linux,default-trigger = "heartbeat";
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml
new file mode 100644
index 000000000000..a31a202afe5c
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-pwm-multicolor.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Multi-color LEDs connected to PWM
+
+maintainers:
+ - Sven Schwermer <sven.schwermer@disruptive-technologies.com>
+
+description: |
+ This driver combines several monochrome PWM LEDs into one multi-color
+ LED using the multicolor LED class.
+
+properties:
+ compatible:
+ const: pwm-leds-multicolor
+
+ multi-led:
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ max-brightness:
+ description:
+ Maximum brightness possible for the LED
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ patternProperties:
+ "^led-[0-9a-z]+$":
+ type: object
+ $ref: common.yaml#
+
+ additionalProperties: false
+
+ properties:
+ pwms:
+ maxItems: 1
+
+ pwm-names: true
+
+ active-low: true
+
+ color: true
+
+ required:
+ - pwms
+ - color
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ led-controller {
+ compatible = "pwm-leds-multicolor";
+
+ multi-led {
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_INDICATOR;
+ max-brightness = <65535>;
+
+ led-red {
+ pwms = <&pwm1 0 1000000>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led-green {
+ pwms = <&pwm2 0 1000000>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led-blue {
+ pwms = <&pwm3 0 1000000>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/leds-pwm.yaml b/Documentation/devicetree/bindings/leds/leds-pwm.yaml
index fe4d5fd25913..6c4fcefbe25f 100644
--- a/Documentation/devicetree/bindings/leds/leds-pwm.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-pwm.yaml
@@ -20,8 +20,8 @@ properties:
patternProperties:
"^led(-[0-9a-f]+)?$":
type: object
-
$ref: common.yaml#
+ unevaluatedProperties: false
properties:
pwms:
@@ -34,10 +34,18 @@ patternProperties:
Maximum brightness possible for the LED
$ref: /schemas/types.yaml#/definitions/uint32
- active-low:
+ default-brightness:
description:
- For PWMs where the LED is wired to supply rather than ground.
- type: boolean
+ Brightness to be set if LED's default state is on. Used only during
+ initialization. If the option is not set then max brightness is used.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ enable-gpios:
+ description:
+ GPIO for LED hardware enable control. Set active when brightness is
+ non-zero and inactive when brightness is zero.
+ The GPIO default state follows the "default-state" property.
+ maxItems: 1
required:
- pwms
diff --git a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml
new file mode 100644
index 000000000000..c4b7e57b2518
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml
@@ -0,0 +1,307 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/leds-qcom-lpg.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Light Pulse Generator
+
+maintainers:
+ - Bjorn Andersson <bjorn.andersson@linaro.org>
+
+description: >
+ The Qualcomm Light Pulse Generator consists of three different hardware blocks;
+ a ramp generator with lookup table (LUT), the light pulse generator and a three
+ channel current sink. These blocks are found in a wide range of Qualcomm PMICs.
+ The light pulse generator (LPG) can also be used independently to output PWM
+ signal for standard PWM applications. In this scenario, the LPG output should
+ be routed to a specific PMIC GPIO by setting the GPIO pin mux to the special
+ functions indicated in the datasheet, the TRILED driver for the channel will
+ not be enabled in this configuration.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - qcom,pm660l-lpg
+ - qcom,pm8150b-lpg
+ - qcom,pm8150l-lpg
+ - qcom,pm8350c-pwm
+ - qcom,pm8916-pwm
+ - qcom,pm8941-lpg
+ - qcom,pm8994-lpg
+ - qcom,pmc8180c-lpg
+ - qcom,pmi632-lpg
+ - qcom,pmi8950-pwm
+ - qcom,pmi8994-lpg
+ - qcom,pmi8998-lpg
+ - qcom,pmk8550-pwm
+ - items:
+ - enum:
+ - qcom,pm6150l-lpg
+ - const: qcom,pm8150l-lpg
+ - items:
+ - enum:
+ - qcom,pm8550-pwm
+ - const: qcom,pm8350c-pwm
+ - items:
+ - enum:
+ - qcom,pm8937-pwm
+ - const: qcom,pm8916-pwm
+
+ "#pwm-cells":
+ const: 2
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ qcom,power-source:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ power-source used to drive the output, as defined in the datasheet.
+ Should be specified if the TRILED block is present
+ enum: [0, 1, 3]
+
+ qcom,dtest:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ description: >
+ A list of integer pairs, where each pair represent the dtest line the
+ particular channel should be connected to and the flags denoting how the
+ value should be outputted, as defined in the datasheet. The number of
+ pairs should be the same as the number of channels.
+ items:
+ items:
+ - description: dtest line to attach
+ - description: flags for the attachment
+
+ nvmem:
+ description: >
+ This property is required for PMICs that supports PPG, which is when a
+ PMIC stores LPG per-channel data and pattern LUT in SDAM modules instead
+ of in a LUT peripheral. For PMICs, such as PM8350C, per-channel data
+ and pattern LUT is separated into 2 SDAM modules. In that case, phandles
+ to both SDAM modules need to be specified.
+ minItems: 1
+ maxItems: 2
+
+ nvmem-names:
+ minItems: 1
+ items:
+ - const: lpg_chan_sdam
+ - const: lut_sdam
+
+ qcom,pbs:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: >
+ Phandle of the Qualcomm Programmable Boot Sequencer node (PBS).
+ PBS node is used to trigger LPG pattern sequences for PMICs that support
+ single SDAM PPG.
+
+ multi-led:
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^led@[0-9a-f]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+patternProperties:
+ "^led@[0-9a-f]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+required:
+ - compatible
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,pm660l-lpg
+ - qcom,pm8150b-lpg
+ - qcom,pm8150l-lpg
+ - qcom,pm8916-pwm
+ - qcom,pm8941-lpg
+ - qcom,pm8994-lpg
+ - qcom,pmc8180c-lpg
+ - qcom,pmi8950-pwm
+ - qcom,pmi8994-lpg
+ - qcom,pmi8998-lpg
+ - qcom,pmk8550-pwm
+ then:
+ properties:
+ nvmem: false
+ nvmem-names: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: qcom,pmi632-lpg
+ then:
+ properties:
+ nvmem:
+ maxItems: 1
+ nvmem-names:
+ maxItems: 1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,pm8350c-pwm
+ then:
+ properties:
+ nvmem:
+ minItems: 2
+ nvmem-names:
+ minItems: 2
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ led-controller {
+ compatible = "qcom,pmi8994-lpg";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ qcom,power-source = <1>;
+
+ qcom,dtest = <0 0>,
+ <0 0>,
+ <0 0>,
+ <4 1>;
+
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <1>;
+ };
+
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <0>;
+ default-state = "on";
+ };
+
+ led@3 {
+ reg = <3>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <2>;
+ };
+
+ led@4 {
+ reg = <4>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_INDICATOR;
+ function-enumerator = <3>;
+ };
+ };
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ led-controller {
+ compatible = "qcom,pmi8994-lpg";
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ qcom,power-source = <1>;
+
+ multi-led {
+ color = <LED_COLOR_ID_RGB>;
+ function = LED_FUNCTION_STATUS;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@3 {
+ reg = <3>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ };
+ - |
+ pwm-controller {
+ compatible = "qcom,pm8916-pwm";
+ #pwm-cells = <2>;
+ };
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ led-controller {
+ compatible = "qcom,pmi632-lpg";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ #pwm-cells = <2>;
+ nvmem-names = "lpg_chan_sdam";
+ nvmem = <&pmi632_sdam_7>;
+ qcom,pbs = <&pmi632_pbs_client3>;
+
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_RED>;
+ label = "red";
+ };
+
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_GREEN>;
+ label = "green";
+ };
+
+ led@3 {
+ reg = <3>;
+ color = <LED_COLOR_ID_BLUE>;
+ label = "blue";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/leds-rt4505.yaml b/Documentation/devicetree/bindings/leds/leds-rt4505.yaml
index 5b0c74aa6723..bfd0e240f7d6 100644
--- a/Documentation/devicetree/bindings/leds/leds-rt4505.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-rt4505.yaml
@@ -27,6 +27,7 @@ properties:
led:
type: object
$ref: common.yaml#
+ unevaluatedProperties: false
required:
- compatible
@@ -38,7 +39,7 @@ examples:
- |
#include <dt-bindings/leds/common.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
deleted file mode 100644
index df2b4e1c492b..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-LEDs connected to Spreadtrum SC27XX PMIC breathing light controller
-
-The SC27xx breathing light controller supports to 3 outputs:
-red LED, green LED and blue LED. Each LED can work at normal
-PWM mode or breath light mode.
-
-Required properties:
-- compatible: Should be "sprd,sc2731-bltc".
-- #address-cells: Must be 1.
-- #size-cells: Must be 0.
-- reg: Specify the controller address.
-
-Required child properties:
-- reg: Port this LED is connected to.
-
-Optional child properties:
-- function: See Documentation/devicetree/bindings/leds/common.txt.
-- color: See Documentation/devicetree/bindings/leds/common.txt.
-- label: See Documentation/devicetree/bindings/leds/common.txt (deprecated).
-
-Examples:
-
-led-controller@200 {
- compatible = "sprd,sc2731-bltc";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x200>;
-
- led@0 {
- color = <LED_COLOR_ID_RED>;
- reg = <0x0>;
- };
-
- led@1 {
- color = <LED_COLOR_ID_GREEN>;
- reg = <0x1>;
- };
-
- led@2 {
- color = <LED_COLOR_ID_BLUE>;
- reg = <0x2>;
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml b/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml
index f68259619488..37d2a93780ab 100644
--- a/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml
+++ b/Documentation/devicetree/bindings/leds/leds-sgm3140.yaml
@@ -18,7 +18,10 @@ description: |
properties:
compatible:
- const: sgmicro,sgm3140
+ enum:
+ - ocs,ocp8110
+ - richtek,rt5033-led
+ - sgmicro,sgm3140
enable-gpios:
maxItems: 1
@@ -34,6 +37,7 @@ properties:
led:
type: object
$ref: common.yaml#
+ unevaluatedProperties: false
required:
- compatible
diff --git a/Documentation/devicetree/bindings/leds/leds-tlc591xx.txt b/Documentation/devicetree/bindings/leds/leds-tlc591xx.txt
deleted file mode 100644
index 3bbbf7024411..000000000000
--- a/Documentation/devicetree/bindings/leds/leds-tlc591xx.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-LEDs connected to tlc59116 or tlc59108
-
-Required properties
-- compatible: should be "ti,tlc59116" or "ti,tlc59108"
-- #address-cells: must be 1
-- #size-cells: must be 0
-- reg: typically 0x68
-
-Each led is represented as a sub-node of the ti,tlc59116.
-See Documentation/devicetree/bindings/leds/common.txt
-
-LED sub-node properties:
-- reg: number of LED line, 0 to 15 or 0 to 7
-- label: (optional) name of LED
-- linux,default-trigger : (optional)
-
-Examples:
-
-tlc59116@68 {
- #address-cells = <1>;
- #size-cells = <0>;
- compatible = "ti,tlc59116";
- reg = <0x68>;
-
- wan@0 {
- label = "wrt1900ac:amber:wan";
- reg = <0x0>;
- };
-
- 2g@2 {
- label = "wrt1900ac:white:2g";
- reg = <0x2>;
- };
-
- alive@9 {
- label = "wrt1900ac:green:alive";
- reg = <0x9>;
- linux,default_trigger = "heartbeat";
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/maxim,max77693.yaml b/Documentation/devicetree/bindings/leds/maxim,max77693.yaml
new file mode 100644
index 000000000000..e27f57bb52ae
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/maxim,max77693.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/maxim,max77693.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX77693 MicroUSB and Companion Power Management IC LEDs
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ This is a part of device tree bindings for Maxim MAX77693 MicroUSB Integrated
+ Circuit (MUIC).
+
+ There are two LED outputs available - FLED1 and FLED2. Each of them can
+ control a separate LED or they can be connected together to double the
+ maximum current for a single connected LED. One LED is represented by one
+ child node.
+
+ See also Documentation/devicetree/bindings/mfd/maxim,max77693.yaml for
+ additional information and example.
+
+properties:
+ compatible:
+ const: maxim,max77693-led
+
+ maxim,boost-mode:
+ description:
+ In boost mode the device can produce up to 1.2A of total current on both
+ outputs. The maximum current on each output is reduced to 625mA then. If
+ not enabled explicitly, boost setting defaults to LEDS_BOOST_FIXED in
+ case both current sources are used.
+ See LEDS_BOOST_* in include/dt-bindings/leds/common.h.
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1, 2]
+
+ maxim,boost-mvout:
+ description: |
+ Output voltage of the boost module in millivolts.
+ Valid values: 3300 - 5500, step by 25 (rounded down)
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 3300
+ maximum: 5500
+ default: 3300
+
+ maxim,mvsys-min:
+ description: |
+ Low input voltage level in millivolts. Flash is not fired if chip
+ estimates that system voltage could drop below this level due to flash
+ power consumption.
+ Valid values: 2400 - 3400, step by 33 (rounded down)
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 2400
+ maximum: 3400
+ default: 2400
+
+patternProperties:
+ "^([a-z]+-)?led[01]?$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ led-sources:
+ allOf:
+ - minItems: 1
+ maxItems: 2
+ items:
+ minimum: 0
+ maximum: 1
+
+ led-max-microamp:
+ description: |
+ Valid values for a LED connected to one FLED output:
+ 15625 - 250000, step by 15625 (rounded down)
+ Valid values for a LED connected to both FLED outputs:
+ 15625 - 500000, step by 15625 (rounded down)
+
+ flash-max-microamp:
+ description: |
+ Valid values for a single LED connected to one FLED output
+ (boost mode must be turned off):
+ 15625 - 1000000, step by 15625 (rounded down)
+ Valid values for a single LED connected to both FLED outputs:
+ 15625 - 1250000, step by 15625 (rounded down)
+ Valid values for two LEDs case:
+ 15625 - 625000, step by 15625 (rounded down)
+
+ flash-max-timeout-us:
+ description: |
+ Valid values: 62500 - 1000000, step by 62500 (rounded down)
+ minimum: 62500
+ maximum: 1000000
+
+ required:
+ - flash-max-microamp
+ - flash-max-timeout-us
+ - led-max-microamp
+ - led-sources
+
+required:
+ - compatible
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/leds/mediatek,mt6370-flashlight.yaml b/Documentation/devicetree/bindings/leds/mediatek,mt6370-flashlight.yaml
new file mode 100644
index 000000000000..e9d02ed6a590
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/mediatek,mt6370-flashlight.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/mediatek,mt6370-flashlight.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Flash LED driver for MT6370 PMIC from MediaTek Integrated.
+
+maintainers:
+ - Alice Chen <alice_chen@richtek.com>
+
+description: |
+ This module is part of the MT6370 MFD device.
+ Add MT6370 flash LED driver include 2-channel flash LED support Torch/Strobe Mode.
+
+properties:
+ compatible:
+ const: mediatek,mt6370-flashlight
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[0-1]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ enum: [0, 1]
+
+required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/leds/mediatek,mt6370-indicator.yaml b/Documentation/devicetree/bindings/leds/mediatek,mt6370-indicator.yaml
new file mode 100644
index 000000000000..16b3abc2af3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/mediatek,mt6370-indicator.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/mediatek,mt6370-indicator.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LED driver for MT6370 PMIC from MediaTek Integrated.
+
+maintainers:
+ - Alice Chen <alice_chen@richtek.com>
+
+description: |
+ This module is part of the MT6370 MFD device.
+ Add MT6370 LED driver include 4-channel RGB LED support Register/PWM/Breath Mode
+
+properties:
+ compatible:
+ const: mediatek,mt6370-indicator
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^multi-led@[0-3]$":
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ enum: [0, 1, 2, 3]
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^led@[0-2]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ enum: [0, 1, 2]
+
+ required:
+ - reg
+ - color
+
+ required:
+ - reg
+ - color
+ - "#address-cells"
+ - "#size-cells"
+
+ "^led@[0-3]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ enum: [0, 1, 2, 3]
+
+ required:
+ - reg
+ - color
+
+required:
+ - compatible
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
diff --git a/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml b/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml
new file mode 100644
index 000000000000..9610bca57dd5
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/nxp,pca953x.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/nxp,pca953x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PCA9532 LED Dimmer
+
+maintainers:
+ - Riku Voipio <riku.voipio@iki.fi>
+
+description: |
+ The PCA9532 family is SMBus I/O expander optimized for dimming LEDs.
+ The PWM support 256 steps.
+
+ For more product information please see the link below:
+ https://www.nxp.com/docs/en/data-sheet/PCA9532.pdf
+
+properties:
+ compatible:
+ enum:
+ - nxp,pca9530
+ - nxp,pca9531
+ - nxp,pca9532
+ - nxp,pca9533
+
+ reg:
+ maxItems: 1
+
+ gpio-controller: true
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 16
+
+ '#gpio-cells':
+ const: 2
+
+patternProperties:
+ "^led-[0-9a-z]+$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ type:
+ description: |
+ Output configuration, see include/dt-bindings/leds/leds-pca9532.h
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+ minimum: 0
+ maximum: 4
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/leds-pca9532.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@62 {
+ compatible = "nxp,pca9533";
+ reg = <0x62>;
+
+ led-1 {
+ label = "pca:red:power";
+ type = <PCA9532_TYPE_LED>;
+ };
+
+ led-2 {
+ label = "pca:green:power";
+ type = <PCA9532_TYPE_LED>;
+ };
+
+ led-3 {
+ type = <PCA9532_TYPE_LED>;
+ default-state = "on";
+ };
+
+ led-4 {
+ type = <PCA9532_TYPE_LED>;
+ default-state = "keep";
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/nxp,pca955x.yaml b/Documentation/devicetree/bindings/leds/nxp,pca955x.yaml
new file mode 100644
index 000000000000..ae7384cc760c
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/nxp,pca955x.yaml
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/nxp,pca955x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PCA955X LED controllers
+
+maintainers:
+ - Nate Case <ncase@xes-inc.com>
+
+description: |
+ The PCA955x family of chips are I2C LED blinkers whose pins not used
+ to control LEDs can be used as general purpose I/Os. The GPIO pins can
+ be input or output, and output pins can also be pulse-width controlled.
+
+ For more product information please see the link below:
+ - https://www.nxp.com/docs/en/data-sheet/PCA9552.pdf
+
+properties:
+ compatible:
+ enum:
+ - nxp,pca9550
+ - nxp,pca9551
+ - nxp,pca9552
+ - ibm,pca9552
+ - nxp,pca9553
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ gpio-controller: true
+
+ gpio-line-names:
+ minItems: 1
+ maxItems: 16
+
+ "#gpio-cells":
+ const: 2
+
+patternProperties:
+ "^led@[0-9a-f]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ maxItems: 1
+ type:
+ description: |
+ Output configuration, see include/dt-bindings/leds/leds-pca955x.h
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+ minimum: 0
+ maximum: 2
+
+ required:
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,pca9550
+ then:
+ patternProperties:
+ "^led@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 1
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,pca9551
+ then:
+ patternProperties:
+ "^led@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 7
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,pca9552
+ - ibm,pca9552
+ then:
+ patternProperties:
+ "^led@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 15
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,pca9553
+ then:
+ patternProperties:
+ "^led@[0-9a-f]$":
+ properties:
+ reg:
+ maximum: 3
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/leds-pca955x.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@60 {
+ compatible = "nxp,pca9552";
+ reg = <0x60>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ label = "red:power";
+ linux,default-trigger = "default-on";
+ type = <PCA955X_TYPE_LED>;
+ };
+ led@1 {
+ reg = <1>;
+ label = "green:power";
+ type = <PCA955X_TYPE_LED>;
+ };
+ led@2 {
+ reg = <2>;
+ label = "pca9552:yellow";
+ type = <PCA955X_TYPE_LED>;
+ };
+ led@3 {
+ reg = <3>;
+ label = "pca9552:white";
+ type = <PCA955X_TYPE_LED>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/nxp,pca963x.yaml b/Documentation/devicetree/bindings/leds/nxp,pca963x.yaml
new file mode 100644
index 000000000000..938d0e48fe51
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/nxp,pca963x.yaml
@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/nxp,pca963x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PCA963x LED controllers
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |
+ The NXP PCA963x are I2C-controlled LED drivers optimized for
+ Red/Green/Blue/Amber (RGBA) color mixing applications. Each LED is
+ individually controllable and has its own PWM controller.
+
+ Datasheets are available at
+
+ - https://www.nxp.com/docs/en/data-sheet/PCA9632.pdf
+ - https://www.nxp.com/docs/en/data-sheet/PCA9633.pdf
+ - https://www.nxp.com/docs/en/data-sheet/PCA9634.pdf
+ - https://www.nxp.com/docs/en/data-sheet/PCA9635.pdf
+
+properties:
+ compatible:
+ enum:
+ - nxp,pca9632
+ - nxp,pca9633
+ - nxp,pca9634
+ - nxp,pca9635
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ nxp,hw-blink:
+ type: boolean
+ description:
+ Use hardware blinking instead of software blinking
+
+ nxp,inverted-out:
+ type: boolean
+ description:
+ Invert the polarity of the generated PWM.
+
+ nxp,period-scale:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ In some configurations, the chip blinks faster than expected. This
+ parameter provides a scaling ratio (fixed point, decimal divided by 1000)
+ to compensate, e.g. 1300=1.3x and 750=0.75x.
+
+ nxp,totem-pole:
+ type: boolean
+ description:
+ Use totem pole (push-pull) instead of open-drain (pca9632 defaults to
+ open-drain, newer chips to totem pole).
+
+patternProperties:
+ "^led@[0-9a-f]+$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+
+ required:
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,pca9632
+ - nxp,pca9633
+ then:
+ patternProperties:
+ "^led@[0-9a-f]+$":
+ properties:
+ reg:
+ maximum: 3
+ else:
+ patternProperties:
+ "^led@[0-9a-f]+$":
+ properties:
+ reg:
+ maximum: 7
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@62 {
+ compatible = "nxp,pca9632";
+ reg = <0x62>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ color = <LED_COLOR_ID_RED>;
+ function = LED_FUNCTION_STATUS;
+ };
+
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_GREEN>;
+ function = LED_FUNCTION_STATUS;
+ };
+
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_BLUE>;
+ function = LED_FUNCTION_STATUS;
+ };
+
+ led@3 {
+ reg = <3>;
+ color = <LED_COLOR_ID_WHITE>;
+ function = LED_FUNCTION_STATUS;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/nxp,pca995x.yaml b/Documentation/devicetree/bindings/leds/nxp,pca995x.yaml
new file mode 100644
index 000000000000..ab8c90cbadb5
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/nxp,pca995x.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/nxp,pca995x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP PCA995x LED controllers
+
+maintainers:
+ - Isai Gaspar <isaiezequiel.gaspar@nxp.com>
+ - Marek Vasut <marex@denx.de>
+
+description:
+ The NXP PCA995x family are programmable LED controllers connected via I2C
+ that can drive separate lines. Each of them can be individually switched
+ on and off, and brightness can be controlled via individual PWM.
+
+ Datasheets are available at
+ https://www.nxp.com/docs/en/data-sheet/PCA9952_PCA9955.pdf
+ https://www.nxp.com/docs/en/data-sheet/PCA9955B.pdf
+ https://www.nxp.com/docs/en/data-sheet/PCA9956B.pdf
+
+properties:
+ compatible:
+ enum:
+ - nxp,pca9952
+ - nxp,pca9955b
+ - nxp,pca9956b
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[0-9a-f]+$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 15
+
+ required:
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@1 {
+ compatible = "nxp,pca9955b";
+ reg = <0x01>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0x0>;
+ color = <LED_COLOR_ID_RED>;
+ function = LED_FUNCTION_POWER;
+ };
+
+ led@2 {
+ reg = <0x2>;
+ color = <LED_COLOR_ID_WHITE>;
+ function = LED_FUNCTION_STATUS;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/onnn,ncp5623.yaml b/Documentation/devicetree/bindings/leds/onnn,ncp5623.yaml
new file mode 100644
index 000000000000..11d45c7f741d
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/onnn,ncp5623.yaml
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/onnn,ncp5623.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ON Semiconductor NCP5623 multi-LED Driver
+
+maintainers:
+ - Abdel Alkuor <alkuor@gmail.com>
+
+description:
+ NCP5623 Triple Output I2C Controlled LED Driver.
+ https://www.onsemi.com/pdf/datasheet/ncp5623-d.pdf
+
+properties:
+ compatible:
+ enum:
+ - onnn,ncp5623
+
+ reg:
+ enum:
+ - 0x38
+ - 0x39
+
+ multi-led:
+ type: object
+ $ref: leds-class-multicolor.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^led@[0-2]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 2
+
+ required:
+ - reg
+ - color
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+required:
+ - compatible
+ - reg
+ - multi-led
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@38 {
+ compatible = "onnn,ncp5623";
+ reg = <0x38>;
+
+ multi-led {
+ color = <LED_COLOR_ID_RGB>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0>;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@1 {
+ reg = <1>;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@2 {
+ reg = <2>;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml b/Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml
new file mode 100644
index 000000000000..e918dceea082
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/panasonic,an30259a.yaml
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/panasonic,an30259a.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Panasonic AN30259A 3-channel LED controller
+
+maintainers:
+ - Iskren Chernev <me@iskren.info>
+
+description:
+ The AN30259A is a LED controller capable of driving three LEDs independently.
+ It supports constant current output and sloping current output modes. The chip
+ is connected over I2C.
+
+properties:
+ compatible:
+ const: panasonic,an30259a
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[1-3]$":
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ enum: [ 1, 2, 3 ]
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@30 {
+ compatible = "panasonic,an30259a";
+ reg = <0x30>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@1 {
+ reg = <1>;
+ linux,default-trigger = "heartbeat";
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_RED>;
+ };
+
+ led@2 {
+ reg = <2>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_GREEN>;
+ };
+
+ led@3 {
+ reg = <3>;
+ function = LED_FUNCTION_INDICATOR;
+ color = <LED_COLOR_ID_BLUE>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/pca963x.txt b/Documentation/devicetree/bindings/leds/pca963x.txt
deleted file mode 100644
index 4eee41482041..000000000000
--- a/Documentation/devicetree/bindings/leds/pca963x.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-LEDs connected to pca9632, pca9633 or pca9634
-
-Required properties:
-- compatible : should be : "nxp,pca9632", "nxp,pca9633", "nxp,pca9634" or "nxp,pca9635"
-
-Optional properties:
-- nxp,totem-pole : use totem pole (push-pull) instead of open-drain (pca9632 defaults
- to open-drain, newer chips to totem pole)
-- nxp,hw-blink : use hardware blinking instead of software blinking
-- nxp,period-scale : In some configurations, the chip blinks faster than expected.
- This parameter provides a scaling ratio (fixed point, decimal divided
- by 1000) to compensate, e.g. 1300=1.3x and 750=0.75x.
-- nxp,inverted-out: invert the polarity of the generated PWM
-
-Each led is represented as a sub-node of the nxp,pca963x device.
-
-LED sub-node properties:
-- label : (optional) see Documentation/devicetree/bindings/leds/common.txt
-- reg : number of LED line (could be from 0 to 3 in pca9632 or pca9633,
- 0 to 7 in pca9634, or 0 to 15 in pca9635)
-- linux,default-trigger : (optional)
- see Documentation/devicetree/bindings/leds/common.txt
-
-Examples:
-
-pca9632: pca9632 {
- compatible = "nxp,pca9632";
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0x62>;
-
- red@0 {
- label = "red";
- reg = <0>;
- linux,default-trigger = "none";
- };
- green@1 {
- label = "green";
- reg = <1>;
- linux,default-trigger = "none";
- };
- blue@2 {
- label = "blue";
- reg = <2>;
- linux,default-trigger = "none";
- };
- unused@3 {
- label = "unused";
- reg = <3>;
- linux,default-trigger = "none";
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/qcom,pm8058-led.yaml b/Documentation/devicetree/bindings/leds/qcom,pm8058-led.yaml
new file mode 100644
index 000000000000..b409b2a8b5c5
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/qcom,pm8058-led.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/qcom,pm8058-led.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm PM8058 PMIC LED
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ The Qualcomm PM8058 contains an LED block for up to six LEDs:: three normal
+ LEDs, two "flash" LEDs and one "keypad backlight" LED. The names are quoted
+ because sometimes these LED drivers are used for wildly different things than
+ flash or keypad backlight:: their names are more of a suggestion than a
+ hard-wired usecase.
+
+ Hardware-wise the different LEDs support slightly different output currents.
+ The "flash" LEDs do not need to charge nor do they support external triggers.
+ They are just powerful LED drivers.
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ compatible:
+ enum:
+ - qcom,pm8058-led
+ - qcom,pm8058-keypad-led
+ - qcom,pm8058-flash-led
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ pmic {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@131 {
+ compatible = "qcom,pm8058-led";
+ reg = <0x131>;
+ label = "pm8058:red";
+ color = <LED_COLOR_ID_RED>;
+ default-state = "off";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/qcom,spmi-flash-led.yaml b/Documentation/devicetree/bindings/leds/qcom,spmi-flash-led.yaml
new file mode 100644
index 000000000000..05250aefd385
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/qcom,spmi-flash-led.yaml
@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/qcom,spmi-flash-led.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Flash LED device inside Qualcomm Technologies, Inc. PMICs
+
+maintainers:
+ - Fenglin Wu <quic_fenglinw@quicinc.com>
+
+description: |
+ Flash LED controller is present inside some Qualcomm Technologies, Inc. PMICs.
+ The flash LED module can have different number of LED channels supported
+ e.g. 3 or 4. There are some different registers between them but they can
+ both support maximum current up to 1.5 A per channel and they can also support
+ ganging 2 channels together to supply maximum current up to 2 A. The current
+ will be split symmetrically on each channel and they will be enabled and
+ disabled at the same time.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - qcom,pm6150l-flash-led
+ - qcom,pm660l-flash-led
+ - qcom,pm7550-flash-led
+ - qcom,pm8150c-flash-led
+ - qcom,pm8150l-flash-led
+ - qcom,pm8350c-flash-led
+ - qcom,pm8550-flash-led
+ - qcom,pmi8998-flash-led
+ - const: qcom,spmi-flash-led
+
+ reg:
+ maxItems: 1
+
+patternProperties:
+ "^led-[0-3]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+ description:
+ Represents the physical LED components which are connected to the
+ flash LED channels' output.
+
+ properties:
+ led-sources:
+ description:
+ The HW indices of the flash LED channels that connect to the
+ physical LED
+ allOf:
+ - minItems: 1
+ maxItems: 2
+ items:
+ enum: [1, 2, 3, 4]
+
+ led-max-microamp:
+ anyOf:
+ - minimum: 5000
+ maximum: 500000
+ multipleOf: 5000
+ - minimum: 10000
+ maximum: 1000000
+ multipleOf: 10000
+
+ flash-max-microamp:
+ anyOf:
+ - minimum: 12500
+ maximum: 1500000
+ multipleOf: 12500
+ - minimum: 25000
+ maximum: 2000000
+ multipleOf: 25000
+
+ flash-max-timeout-us:
+ minimum: 10000
+ maximum: 1280000
+ multipleOf: 10000
+
+ required:
+ - led-sources
+ - led-max-microamp
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ pmic {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@ee00 {
+ compatible = "qcom,pm8350c-flash-led", "qcom,spmi-flash-led";
+ reg = <0xee00>;
+
+ led-0 {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ led-sources = <1>, <4>;
+ led-max-microamp = <300000>;
+ flash-max-microamp = <2000000>;
+ flash-max-timeout-us = <1280000>;
+ function-enumerator = <0>;
+ };
+
+ led-1 {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_YELLOW>;
+ led-sources = <2>, <3>;
+ led-max-microamp = <300000>;
+ flash-max-microamp = <2000000>;
+ flash-max-timeout-us = <1280000>;
+ function-enumerator = <1>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/register-bit-led.txt b/Documentation/devicetree/bindings/leds/register-bit-led.txt
deleted file mode 100644
index c7af6f70a97b..000000000000
--- a/Documentation/devicetree/bindings/leds/register-bit-led.txt
+++ /dev/null
@@ -1,94 +0,0 @@
-Device Tree Bindings for Register Bit LEDs
-
-Register bit leds are used with syscon multifunctional devices
-where single bits in a certain register can turn on/off a
-single LED. The register bit LEDs appear as children to the
-syscon device, with the proper compatible string. For the
-syscon bindings see:
-Documentation/devicetree/bindings/mfd/syscon.yaml
-
-Each LED is represented as a sub-node of the syscon device. Each
-node's name represents the name of the corresponding LED.
-
-LED sub-node properties:
-
-Required properties:
-- compatible : must be "register-bit-led"
-- offset : register offset to the register controlling this LED
-- mask : bit mask for the bit controlling this LED in the register
- typically 0x01, 0x02, 0x04 ...
-
-Optional properties:
-- label : (optional)
- see Documentation/devicetree/bindings/leds/common.txt
-- linux,default-trigger : (optional)
- see Documentation/devicetree/bindings/leds/common.txt
-- default-state: (optional) The initial state of the LED
- see Documentation/devicetree/bindings/leds/common.txt
-
-Example:
-
-syscon: syscon@10000000 {
- compatible = "arm,realview-pb1176-syscon", "syscon";
- reg = <0x10000000 0x1000>;
-
- led@8.0 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x01>;
- label = "versatile:0";
- linux,default-trigger = "heartbeat";
- default-state = "on";
- };
- led@8.1 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x02>;
- label = "versatile:1";
- linux,default-trigger = "mmc0";
- default-state = "off";
- };
- led@8.2 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x04>;
- label = "versatile:2";
- linux,default-trigger = "cpu0";
- default-state = "off";
- };
- led@8.3 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x08>;
- label = "versatile:3";
- default-state = "off";
- };
- led@8.4 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x10>;
- label = "versatile:4";
- default-state = "off";
- };
- led@8.5 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x20>;
- label = "versatile:5";
- default-state = "off";
- };
- led@8.6 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x40>;
- label = "versatile:6";
- default-state = "off";
- };
- led@8.7 {
- compatible = "register-bit-led";
- offset = <0x08>;
- mask = <0x80>;
- label = "versatile:7";
- default-state = "off";
- };
-};
diff --git a/Documentation/devicetree/bindings/leds/register-bit-led.yaml b/Documentation/devicetree/bindings/leds/register-bit-led.yaml
new file mode 100644
index 000000000000..20930d327ae9
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/register-bit-led.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/register-bit-led.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Register Bit LEDs
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description: |+
+ Register bit leds are used with syscon multifunctional devices where single
+ bits in a certain register can turn on/off a single LED. The register bit LEDs
+ appear as children to the syscon device, with the proper compatible string.
+ For the syscon bindings see:
+ Documentation/devicetree/bindings/mfd/syscon.yaml
+
+allOf:
+ - $ref: /schemas/leds/common.yaml#
+
+properties:
+ $nodename:
+ description:
+ The unit-address is in the form of @<reg addr>,<bit offset>
+ pattern: '^led@[0-9a-f]+,[0-9a-f]{1,2}$'
+
+ compatible:
+ const: register-bit-led
+
+ reg:
+ description:
+ The register address and size
+ maxItems: 1
+
+ mask:
+ description:
+ bit mask for the bit controlling this LED in the register
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ [ 0x1, 0x2, 0x4, 0x8, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200, 0x400, 0x800,
+ 0x1000, 0x2000, 0x4000, 0x8000, 0x10000, 0x20000, 0x40000, 0x80000,
+ 0x100000, 0x200000, 0x400000, 0x800000, 0x1000000, 0x2000000, 0x4000000,
+ 0x8000000, 0x10000000, 0x20000000, 0x40000000, 0x80000000 ]
+
+ offset:
+ description:
+ register offset to the register controlling this LED
+ $ref: /schemas/types.yaml#/definitions/uint32
+ deprecated: true
+
+required:
+ - compatible
+ - mask
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+
+ syscon@10000000 {
+ compatible = "arm,realview-pb1176-syscon", "syscon", "simple-mfd";
+ reg = <0x10000000 0x1000>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0x0 0x10000000 0x1000>;
+
+ led@8,0 {
+ compatible = "register-bit-led";
+ reg = <0x08 0x04>;
+ offset = <0x08>;
+ mask = <0x01>;
+ label = "versatile:0";
+ linux,default-trigger = "heartbeat";
+ default-state = "on";
+ };
+ led@8,1 {
+ compatible = "register-bit-led";
+ reg = <0x08 0x04>;
+ offset = <0x08>;
+ mask = <0x02>;
+ label = "versatile:1";
+ default-state = "off";
+ };
+ led@8,2 {
+ compatible = "register-bit-led";
+ reg = <0x08 0x04>;
+ offset = <0x08>;
+ mask = <0x04>;
+ label = "versatile:2";
+ default-state = "off";
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/regulator-led.yaml b/Documentation/devicetree/bindings/leds/regulator-led.yaml
new file mode 100644
index 000000000000..4ef7b96e9a08
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/regulator-led.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/regulator-led.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Regulator LEDs
+
+maintainers:
+ - Linus Walleij <linus.walleij@linaro.org>
+
+description: |
+ Regulator LEDs are powered by a single regulator such that they can
+ be turned on or off by enabling or disabling the regulator. The available
+ brightness settings will be inferred from the available voltages on the
+ regulator, and any constraints on the voltage or current will need to be
+ specified on the regulator.
+
+allOf:
+ - $ref: common.yaml#
+
+properties:
+ $nodename:
+ pattern: '^led.*$'
+
+ compatible:
+ const: regulator-led
+
+ vled-supply:
+ description:
+ The regulator controlling the current to the LED.
+
+ function: true
+ color: true
+ linux,default-trigger: true
+ default-state: true
+
+required:
+ - compatible
+ - vled-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ led-heartbeat {
+ compatible = "regulator-led";
+ vled-supply = <&regulator>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_BLUE>;
+ linux,default-trigger = "heartbeat";
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml b/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml
new file mode 100644
index 000000000000..44dd91aa239d
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/rohm,bd2606mvv.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/rohm,bd2606mvv.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ROHM BD2606MVV LED controller
+
+maintainers:
+ - Andreas Kemnade <andreas@kemnade.info>
+
+description:
+ The BD2606 MVV is a programmable LED controller connected via I2C that can
+ drive 6 separate lines. Each of them can be individually switched on and off,
+ but the brightness setting is shared between pairs of them.
+
+ Datasheet is available at
+ https://fscdn.rohm.com/en/products/databook/datasheet/ic/power/led_driver/bd2606mvv_1-e.pdf
+
+properties:
+ compatible:
+ const: rohm,bd2606mvv
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ enable-gpios:
+ maxItems: 1
+ description: GPIO pin to enable/disable the device.
+
+patternProperties:
+ "^led@[0-5]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 5
+
+ required:
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@66 {
+ compatible = "rohm,bd2606mvv";
+ reg = <0x66>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0x0>;
+ color = <LED_COLOR_ID_RED>;
+ function = LED_FUNCTION_POWER;
+ };
+
+ led@2 {
+ reg = <0x2>;
+ color = <LED_COLOR_ID_WHITE>;
+ function = LED_FUNCTION_STATUS;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml
index 86a37c92b834..b7a3ef76cbf4 100644
--- a/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml
+++ b/Documentation/devicetree/bindings/leds/rohm,bd71828-leds.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: ROHM BD71828 Power Management Integrated Circuit LED driver
maintainers:
- - Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com>
+ - Matti Vaittinen <mazziesaccount@gmail.com>
description: |
This module is part of the ROHM BD71828 MFD device. For more details
@@ -18,34 +18,22 @@ description: |
The device has two LED outputs referred as GRNLED and AMBLED in data-sheet.
-select: false
-
properties:
compatible:
const: rohm,bd71828-leds
patternProperties:
"^led-[1-2]$":
- type: object
- description:
- Properties for a single LED.
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
properties:
- #allOf:
- #- $ref: "common.yaml#"
rohm,led-compatible:
description: LED identification string
- $ref: "/schemas/types.yaml#/definitions/string"
+ $ref: /schemas/types.yaml#/definitions/string
enum:
- bd71828-ambled
- bd71828-grnled
- function:
- description:
- Purpose of LED as defined in dt-bindings/leds/common.h
- $ref: "/schemas/types.yaml#/definitions/string"
- color:
- description:
- LED colour as defined in dt-bindings/leds/common.h
- $ref: "/schemas/types.yaml#/definitions/uint32"
required:
- compatible
diff --git a/Documentation/devicetree/bindings/leds/silergy,sy7802.yaml b/Documentation/devicetree/bindings/leds/silergy,sy7802.yaml
new file mode 100644
index 000000000000..46b8e5452b62
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/silergy,sy7802.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/silergy,sy7802.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Silergy SY7802 1800mA Boost Charge Pump LED Driver
+
+maintainers:
+ - André Apitzsch <git@apitzsch.eu>
+
+description: |
+ The SY7802 is a current-regulated charge pump which can regulate two current
+ levels for Flash and Torch modes.
+
+ The SY7802 is a high-current synchronous boost converter with 2-channel
+ high side current sources. Each channel is able to deliver 900mA current.
+
+properties:
+ compatible:
+ enum:
+ - silergy,sy7802
+
+ reg:
+ maxItems: 1
+
+ enable-gpios:
+ maxItems: 1
+ description: A connection to the 'EN' pin.
+
+ flash-gpios:
+ maxItems: 1
+ description: A connection to the 'FLEN' pin.
+
+ vin-supply:
+ description: Regulator providing power to the 'VIN' pin.
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[0-1]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description: Index of the LED.
+ minimum: 0
+ maximum: 1
+
+ led-sources:
+ minItems: 1
+ maxItems: 2
+ items:
+ minimum: 0
+ maximum: 1
+
+ required:
+ - reg
+ - led-sources
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+ - enable-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ flash-led-controller@53 {
+ compatible = "silergy,sy7802";
+ reg = <0x53>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ enable-gpios = <&tlmm 16 GPIO_ACTIVE_HIGH>;
+
+ led@0 {
+ reg = <0>;
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ led-sources = <0>, <1>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/skyworks,aat1290.yaml b/Documentation/devicetree/bindings/leds/skyworks,aat1290.yaml
new file mode 100644
index 000000000000..a6aaa92dbccd
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/skyworks,aat1290.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/skyworks,aat1290.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Skyworks Solutions, Inc. AAT1290 Current Regulator for Flash LEDs
+
+maintainers:
+ - Jacek Anaszewski <jacek.anaszewski@gmail.com>
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |
+ The device is controlled through two pins:: FL_EN and EN_SET. The pins when,
+ asserted high, enable flash strobe and movie mode (max 1/2 of flash current)
+ respectively. In order to add a capability of selecting the strobe signal
+ source (e.g. CPU or camera sensor) there is an additional switch required,
+ independent of the flash chip. The switch is controlled with pin control.
+
+properties:
+ compatible:
+ const: skyworks,aat1290
+
+ enset-gpios:
+ maxItems: 1
+ description: EN_SET pin
+
+ flen-gpios:
+ maxItems: 1
+ description: FL_EN pin
+
+ led:
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ led-max-microamp: true
+
+ flash-max-microamp:
+ description: |
+ Maximum flash LED supply current can be calculated using following
+ formula:: I = 1A * 162 kOhm / Rset.
+
+ flash-max-timeout-us:
+ description: |
+ Maximum flash timeout can be calculated using following formula::
+ T = 8.82 * 10^9 * Ct.
+
+ required:
+ - flash-max-microamp
+ - flash-max-timeout-us
+ - led-max-microamp
+
+ pinctrl-names:
+ items:
+ - const: default
+ - const: host
+ - const: isp
+
+ pinctrl-0: true
+ pinctrl-1: true
+ pinctrl-2: true
+
+required:
+ - compatible
+ - enset-gpios
+ - flen-gpios
+ - led
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ // Ct = 220 nF, Rset = 160 kOhm
+ led-controller {
+ compatible = "skyworks,aat1290";
+ flen-gpios = <&gpj1 1 GPIO_ACTIVE_HIGH>;
+ enset-gpios = <&gpj1 2 GPIO_ACTIVE_HIGH>;
+
+ pinctrl-names = "default", "host", "isp";
+ pinctrl-0 = <&camera_flash_host>;
+ pinctrl-1 = <&camera_flash_host>;
+ pinctrl-2 = <&camera_flash_isp>;
+
+ led {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ led-max-microamp = <520833>;
+ flash-max-microamp = <1012500>;
+ flash-max-timeout-us = <1940000>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/sprd,sc2731-bltc.yaml b/Documentation/devicetree/bindings/leds/sprd,sc2731-bltc.yaml
new file mode 100644
index 000000000000..97535d6dc47a
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/sprd,sc2731-bltc.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/sprd,sc2731-bltc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Spreadtrum SC2731 PMIC breathing light controller
+
+maintainers:
+ - Orson Zhai <orsonzhai@gmail.com>
+ - Baolin Wang <baolin.wang7@gmail.com>
+ - Chunyan Zhang <zhang.lyra@gmail.com>
+
+description: |
+ The SC2731 breathing light controller supports up to 3 outputs:
+ red LED, green LED and blue LED. Each LED can work at normal PWM mode
+ or breath light mode.
+
+properties:
+ compatible:
+ const: sprd,sc2731-bltc
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+patternProperties:
+ "^led@[0-2]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 2
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - '#address-cells'
+ - '#size-cells'
+
+additionalProperties: false
+...
diff --git a/Documentation/devicetree/bindings/leds/st,led1202.yaml b/Documentation/devicetree/bindings/leds/st,led1202.yaml
new file mode 100644
index 000000000000..f1e5e4efaa3a
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/st,led1202.yaml
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/st,led1202.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ST LED1202 LED controllers
+
+maintainers:
+ - Vicentiu Galanopulo <vicentiu.galanopulo@remote-tech.co.uk>
+
+description: |
+ The LED1202 is a 12-channel low quiescent current LED controller
+ programmable via I2C; The output current can be adjusted separately
+ for each channel by 8-bit analog and 12-bit digital dimming control.
+ Datasheet available at
+ https://www.st.com/en/power-management/led1202.html
+
+properties:
+ compatible:
+ const: st,led1202
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[0-9a-f]$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ minimum: 0
+ maximum: 11
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@58 {
+ compatible = "st,led1202";
+ reg = <0x58>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0x0>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_RED>;
+ function-enumerator = <1>;
+ };
+
+ led@1 {
+ reg = <0x1>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_GREEN>;
+ function-enumerator = <2>;
+ };
+
+ led@2 {
+ reg = <0x2>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_BLUE>;
+ function-enumerator = <3>;
+ };
+
+ led@3 {
+ reg = <0x3>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_RED>;
+ function-enumerator = <4>;
+ };
+
+ led@4 {
+ reg = <0x4>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_GREEN>;
+ function-enumerator = <5>;
+ };
+
+ led@5 {
+ reg = <0x5>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_BLUE>;
+ function-enumerator = <6>;
+ };
+
+ led@6 {
+ reg = <0x6>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_RED>;
+ function-enumerator = <7>;
+ };
+
+ led@7 {
+ reg = <0x7>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_GREEN>;
+ function-enumerator = <8>;
+ };
+
+ led@8 {
+ reg = <0x8>;
+ function = LED_FUNCTION_STATUS;
+ color = <LED_COLOR_ID_BLUE>;
+ function-enumerator = <9>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/leds/ti,lp8860.yaml b/Documentation/devicetree/bindings/leds/ti,lp8860.yaml
new file mode 100644
index 000000000000..0ee357b02661
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/ti,lp8860.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/ti,lp8860.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments - lp8860 4-Channel LED Driver
+
+maintainers:
+ - Andrew Davis <afd@ti.com>
+
+description: |
+ The LP8860-Q1 is an high-efficiency LED driver with boost controller.
+ It has 4 high-precision current sinks that can be controlled by a PWM input
+ signal, a SPI/I2C master, or both.
+
+ For more product information please see the link below:
+ https://www.ti.com/product/lp8860-q1
+
+properties:
+ compatible:
+ const: ti,lp8860
+
+ reg:
+ maxItems: 1
+ description: I2C slave address
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ enable-gpios:
+ maxItems: 1
+ description: GPIO pin to enable (active high) / disable the device
+
+ vled-supply:
+ description: LED supply
+
+patternProperties:
+ "^led(@[0-3])?$":
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ reg:
+ description:
+ Index of the LED.
+ maxItems: 1
+
+ function: true
+ color: true
+ label: true
+ linux,default-trigger: true
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@2d {
+ compatible = "ti,lp8860";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0x2d>;
+ enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
+ vled-supply = <&vbatt>;
+
+ led@0 {
+ reg = <0>;
+ function = LED_FUNCTION_BACKLIGHT;
+ color = <LED_COLOR_ID_WHITE>;
+ linux,default-trigger = "backlight";
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/leds/ti,tca6507.yaml b/Documentation/devicetree/bindings/leds/ti,tca6507.yaml
index 32c600387895..4b1575e4f180 100644
--- a/Documentation/devicetree/bindings/leds/ti,tca6507.yaml
+++ b/Documentation/devicetree/bindings/leds/ti,tca6507.yaml
@@ -38,8 +38,8 @@ properties:
patternProperties:
"^led@[0-6]$":
type: object
-
$ref: common.yaml#
+ unevaluatedProperties: false
properties:
reg:
@@ -87,7 +87,7 @@ examples:
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/leds/common.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/leds/ti,tlc59116.yaml b/Documentation/devicetree/bindings/leds/ti,tlc59116.yaml
new file mode 100644
index 000000000000..ce9713793908
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/ti,tlc59116.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/ti,tlc59116.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LEDs connected to tlc59116 or tlc59108
+
+maintainers:
+ - Andrew Lunn <andrew@lunn.ch>
+
+properties:
+ compatible:
+ enum:
+ - ti,tlc59108
+ - ti,tlc59116
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^led@[0-9a-f]$":
+ type: object
+ $ref: common.yaml#
+ properties:
+ reg:
+ items:
+ minimum: 0
+ maximum: 15
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,tlc59108
+ then:
+ patternProperties:
+ "^led@[0-9a-f]$":
+ properties:
+ reg:
+ items:
+ maximum: 7
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@68 {
+ compatible = "ti,tlc59116";
+ reg = <0x68>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led@0 {
+ reg = <0x0>;
+ label = "wrt1900ac:amber:wan";
+ };
+
+ led@2 {
+ reg = <0x2>;
+ label = "wrt1900ac:white:2g";
+ };
+
+ led@9 {
+ reg = <0x9>;
+ label = "wrt1900ac:green:alive";
+ linux,default-trigger = "heartbeat";
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/leds/ti,tps61310.yaml b/Documentation/devicetree/bindings/leds/ti,tps61310.yaml
new file mode 100644
index 000000000000..118f9c8bfdf7
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/ti,tps61310.yaml
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/ti,tps61310.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TPS6131X flash LED driver
+
+maintainers:
+ - Matthias Fend <matthias.fend@emfend.at>
+
+description: |
+ The TPS61310/TPS61311 is a flash LED driver with I2C interface.
+ Its power stage is capable of supplying a maximum total current of roughly 1500mA.
+ The TPS6131x provides three constant-current sinks, capable of sinking
+ up to 2 x 400mA (LED1 and LED3) and 800mA (LED2) in flash mode.
+ In torch mode, each sink (LED1, LED2, LED3) supports currents up to 175mA.
+ Since the three current sinks share most of the control components such as
+ flash timer, control logic, safety timer and the operating mode, they cannot
+ be used completely independently of each other. Therefore, only one LED is
+ supported, but the current sinks can be combined accordingly.
+
+ The data sheet can be found at:
+ https://www.ti.com/lit/ds/symlink/tps61310.pdf
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - ti,tps61311
+ - const: ti,tps61310
+ - items:
+ - const: ti,tps61310
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+ description: GPIO connected to NRESET pin
+
+ ti,valley-current-limit:
+ type: boolean
+ description:
+ Reduce the valley peak current limit from 1750mA to 1250mA (TPS61310) or
+ from 2480mA to 1800mA (TPS61311).
+
+ led:
+ type: object
+ $ref: common.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ led-sources:
+ minItems: 1
+ maxItems: 3
+ items:
+ enum: [1, 2, 3]
+
+ led-max-microamp:
+ oneOf:
+ - minimum: 50000
+ maximum: 350000
+ multipleOf: 50000
+ - minimum: 25000
+ maximum: 525000
+ multipleOf: 25000
+
+ flash-max-microamp:
+ oneOf:
+ - minimum: 50000
+ maximum: 800000
+ multipleOf: 50000
+ - minimum: 25000
+ maximum: 1500000
+ multipleOf: 25000
+
+ flash-max-timeout-us:
+ enum: [ 5300, 10700, 16000, 21300, 26600, 32000, 37300, 68200, 71500,
+ 102200, 136300, 170400, 204500, 340800, 579300, 852000 ]
+
+ required:
+ - led-sources
+ - led-max-microamp
+ - flash-max-microamp
+ - flash-max-timeout-us
+
+required:
+ - compatible
+ - reg
+ - led
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/leds/common.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@33 {
+ compatible = "ti,tps61311", "ti,tps61310";
+ reg = <0x33>;
+
+ reset-gpios = <&gpio1 0 GPIO_ACTIVE_LOW>;
+
+ led {
+ function = LED_FUNCTION_FLASH;
+ color = <LED_COLOR_ID_WHITE>;
+ led-sources = <1>, <2>, <3>;
+ led-max-microamp = <525000>;
+ flash-max-microamp = <1500000>;
+ flash-max-timeout-us = <852000>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/leds/ti.lm36922.yaml b/Documentation/devicetree/bindings/leds/ti.lm36922.yaml
new file mode 100644
index 000000000000..8ffbc6b785a3
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/ti.lm36922.yaml
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/leds/ti.lm36922.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments - LM3692x Highly Efficient White LED Driver
+
+maintainers:
+ - Dan Murphy <dmurphy@ti.com>
+
+description: |
+ The LM3692x is an ultra-compact, highly efficient,
+ white-LED driver designed for LCD display backlighting.
+
+ The main difference between the LM36922 and LM36923 is the number of
+ LED strings it supports. The LM36922 supports two strings while the LM36923
+ supports three strings.
+
+ For more product information please see the link below:
+ https://www.ti.com/lit/ds/snvsa29/snvsa29.pdf
+
+properties:
+ compatible:
+ enum:
+ - ti,lm36922
+ - ti,lm36923
+
+ reg:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ enable-gpios:
+ description: gpio pin to enable/disable the device.
+
+ vled-supply:
+ description: LED supply
+
+ ti,ovp-microvolt:
+ description: Overvoltage protection.
+ default: 29000000
+ enum: [17000000, 21000000, 25000000, 29000000]
+
+patternProperties:
+ '^led@[0-3]$':
+ type: object
+ $ref: common.yaml
+ properties:
+ reg:
+ enum: [0, 1, 2, 3]
+ description: |
+ 0 - Will enable all LED sync paths
+ 1 - Will enable the LED1 sync
+ 2 - Will enable the LED2 sync
+ 3 - Will enable the LED3 sync (LM36923 only)
+
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ti,lm36922
+ then:
+ properties:
+ led@3: false
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/leds/common.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ led-controller@36 {
+ compatible = "ti,lm36922";
+ reg = <0x36>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>;
+ vled-supply = <&vbatt>;
+ ti,ovp-microvolt = <29000000>;
+
+ led@0 {
+ reg = <0>;
+ function = LED_FUNCTION_BACKLIGHT;
+ color = <LED_COLOR_ID_WHITE>;
+ linux,default-trigger = "backlight";
+ led-max-microamp = <20000>;
+ };
+ };
+ };
+
diff --git a/Documentation/devicetree/bindings/loongarch/cpus.yaml b/Documentation/devicetree/bindings/loongarch/cpus.yaml
new file mode 100644
index 000000000000..f175872995e1
--- /dev/null
+++ b/Documentation/devicetree/bindings/loongarch/cpus.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/loongarch/cpus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LoongArch CPUs
+
+maintainers:
+ - Binbin Zhou <zhoubinbin@loongson.cn>
+
+description:
+ This document describes the list of LoongArch CPU cores that support FDT,
+ it describe the layout of CPUs in a system through the "cpus" node.
+
+allOf:
+ - $ref: /schemas/cpu.yaml#
+
+properties:
+ compatible:
+ enum:
+ - loongson,la264
+ - loongson,la364
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/loongson,ls2k-clk.h>
+
+ cpus {
+ #size-cells = <0>;
+ #address-cells = <1>;
+
+ cpu@0 {
+ compatible = "loongson,la264";
+ device_type = "cpu";
+ reg = <0>;
+ clocks = <&clk LOONGSON2_NODE_CLK>;
+ };
+
+ cpu@1 {
+ compatible = "loongson,la264";
+ device_type = "cpu";
+ reg = <1>;
+ clocks = <&clk LOONGSON2_NODE_CLK>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/loongarch/loongson.yaml b/Documentation/devicetree/bindings/loongarch/loongson.yaml
new file mode 100644
index 000000000000..e1a4a97b7576
--- /dev/null
+++ b/Documentation/devicetree/bindings/loongarch/loongson.yaml
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/loongarch/loongson.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Loongson SoC-based boards
+
+maintainers:
+ - Binbin Zhou <zhoubinbin@loongson.cn>
+
+properties:
+ $nodename:
+ const: '/'
+ compatible:
+ oneOf:
+ - description: Loongson-2K0500 processor based boards
+ items:
+ - const: loongson,ls2k0500-ref
+ - const: loongson,ls2k0500
+
+ - description: Loongson-2K1000 processor based boards
+ items:
+ - const: loongson,ls2k1000-ref
+ - const: loongson,ls2k1000
+
+ - description: Loongson-2K2000 processor based boards
+ items:
+ - const: loongson,ls2k2000-ref
+ - const: loongson,ls2k2000
+
+additionalProperties: true
+
+...
diff --git a/Documentation/devicetree/bindings/mailbox/allwinner,sun6i-a31-msgbox.yaml b/Documentation/devicetree/bindings/mailbox/allwinner,sun6i-a31-msgbox.yaml
index 75d5d97305e1..87d31963c1b7 100644
--- a/Documentation/devicetree/bindings/mailbox/allwinner,sun6i-a31-msgbox.yaml
+++ b/Documentation/devicetree/bindings/mailbox/allwinner,sun6i-a31-msgbox.yaml
@@ -68,13 +68,13 @@ examples:
#include <dt-bindings/reset/sun8i-h3-ccu.h>
msgbox: mailbox@1c17000 {
- compatible = "allwinner,sun8i-h3-msgbox",
- "allwinner,sun6i-a31-msgbox";
- reg = <0x01c17000 0x1000>;
- clocks = <&ccu CLK_BUS_MSGBOX>;
- resets = <&ccu RST_BUS_MSGBOX>;
- interrupts = <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>;
- #mbox-cells = <1>;
+ compatible = "allwinner,sun8i-h3-msgbox",
+ "allwinner,sun6i-a31-msgbox";
+ reg = <0x01c17000 0x1000>;
+ clocks = <&ccu CLK_BUS_MSGBOX>;
+ resets = <&ccu RST_BUS_MSGBOX>;
+ interrupts = <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <1>;
};
...
diff --git a/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml b/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml
index aa2b3bf56b57..79963c9878ba 100644
--- a/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml
+++ b/Documentation/devicetree/bindings/mailbox/amlogic,meson-gxbb-mhu.yaml
@@ -2,13 +2,13 @@
# Copyright 2019 BayLibre, SAS
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/mailbox/amlogic,meson-gxbb-mhu.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/mailbox/amlogic,meson-gxbb-mhu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Amlogic Meson Message-Handling-Unit Controller
maintainers:
- - Neil Armstrong <narmstrong@baylibre.com>
+ - Neil Armstrong <neil.armstrong@linaro.org>
description: |
The Amlogic's Meson SoCs Message-Handling-Unit (MHU) is a mailbox controller
@@ -27,7 +27,7 @@ properties:
maxItems: 1
interrupts:
- minItems: 3
+ maxItems: 3
description:
Contains the interrupt information corresponding to each of the 3 links
of MHU.
@@ -46,9 +46,8 @@ additionalProperties: false
examples:
- |
mailbox@c883c404 {
- compatible = "amlogic,meson-gxbb-mhu";
- reg = <0xc883c404 0x4c>;
- interrupts = <208>, <209>, <210>;
- #mbox-cells = <1>;
+ compatible = "amlogic,meson-gxbb-mhu";
+ reg = <0xc883c404 0x4c>;
+ interrupts = <208>, <209>, <210>;
+ #mbox-cells = <1>;
};
-
diff --git a/Documentation/devicetree/bindings/mailbox/apm,xgene-slimpro-mbox.yaml b/Documentation/devicetree/bindings/mailbox/apm,xgene-slimpro-mbox.yaml
new file mode 100644
index 000000000000..815f08d61de8
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/apm,xgene-slimpro-mbox.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/apm,xgene-slimpro-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: APM X-Gene SLIMpro mailbox
+
+maintainers:
+ - Khuong Dinh <khuong@os.amperecomputing.com>
+
+description:
+ The APM X-Gene SLIMpro mailbox is used to communicate messages between
+ the ARM64 processors and the Cortex M3 (dubbed SLIMpro). It uses a simple
+ interrupt based door bell mechanism and can exchange simple messages using the
+ internal registers.
+
+properties:
+ compatible:
+ const: apm,xgene-slimpro-mbox
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: mailbox channel 0 doorbell
+ - description: mailbox channel 1 doorbell
+ - description: mailbox channel 2 doorbell
+ - description: mailbox channel 3 doorbell
+ - description: mailbox channel 4 doorbell
+ - description: mailbox channel 5 doorbell
+ - description: mailbox channel 6 doorbell
+ - description: mailbox channel 7 doorbell
+
+ '#mbox-cells':
+ description: Number of mailbox channel.
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ mailbox@10540000 {
+ compatible = "apm,xgene-slimpro-mbox";
+ reg = <0x10540000 0xa000>;
+ #mbox-cells = <1>;
+ interrupts = <0x0 0x0 0x4>,
+ <0x0 0x1 0x4>,
+ <0x0 0x2 0x4>,
+ <0x0 0x3 0x4>,
+ <0x0 0x4 0x4>,
+ <0x0 0x5 0x4>,
+ <0x0 0x6 0x4>,
+ <0x0 0x7 0x4>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml b/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml
new file mode 100644
index 000000000000..28985cc62c25
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/apple,mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple Mailbox Controller
+
+maintainers:
+ - Hector Martin <marcan@marcan.st>
+ - Sven Peter <sven@svenpeter.dev>
+
+description:
+ The Apple mailbox consists of two FIFOs used to exchange 64+32 bit
+ messages between the main CPU and a co-processor. Multiple instances
+ of this mailbox can be found on Apple SoCs.
+ One of the two FIFOs is used to send data to a co-processor while the other
+ FIFO is used for the other direction.
+ Various clients implement different IPC protocols based on these simple
+ messages and shared memory buffers.
+
+properties:
+ compatible:
+ oneOf:
+ - description:
+ ASC mailboxes are the most common variant found on the M1 used
+ for example for the display controller, the system management
+ controller and the NVMe coprocessor.
+ items:
+ - enum:
+ - apple,t8103-asc-mailbox
+ - apple,t8112-asc-mailbox
+ - apple,t6000-asc-mailbox
+ - apple,t6020-asc-mailbox
+ - const: apple,asc-mailbox-v4
+
+ - description:
+ An older ASC mailbox interface found on T2 and A11 that is also
+ used for the NVMe coprocessor and the system management
+ controller.
+ items:
+ - const: apple,t8015-asc-mailbox
+
+ - description:
+ M3 mailboxes are an older variant with a slightly different MMIO
+ interface still found on the M1. It is used for the Thunderbolt
+ co-processors.
+ items:
+ - enum:
+ - apple,t8103-m3-mailbox
+ - apple,t8112-m3-mailbox
+ - apple,t6000-m3-mailbox
+ - const: apple,m3-mailbox-v2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: send fifo is empty interrupt
+ - description: send fifo is not empty interrupt
+ - description: receive fifo is empty interrupt
+ - description: receive fifo is not empty interrupt
+
+ interrupt-names:
+ items:
+ - const: send-empty
+ - const: send-not-empty
+ - const: recv-empty
+ - const: recv-not-empty
+
+ "#mbox-cells":
+ const: 0
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ mailbox@77408000 {
+ compatible = "apple,t8103-asc-mailbox", "apple,asc-mailbox-v4";
+ reg = <0x77408000 0x4000>;
+ interrupts = <1 583 4>, <1 584 4>, <1 585 4>, <1 586 4>;
+ interrupt-names = "send-empty", "send-not-empty",
+ "recv-empty", "recv-not-empty";
+ #mbox-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhu.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhu.yaml
index bd49c201477d..e45b661e8b41 100644
--- a/Documentation/devicetree/bindings/mailbox/arm,mhu.yaml
+++ b/Documentation/devicetree/bindings/mailbox/arm,mhu.yaml
@@ -52,11 +52,11 @@ properties:
- const: arm,mhu-doorbell
- const: arm,primecell
-
reg:
maxItems: 1
interrupts:
+ minItems: 2
items:
- description: low-priority non-secure
- description: high-priority non-secure
diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml
index a4f1fe63659a..3828d77f6316 100644
--- a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml
+++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml
@@ -127,7 +127,6 @@ properties:
- minimum: 0
maximum: 124
-
'#mbox-cells':
description: |
It is always set to 2. The first argument in the consumers 'mboxes'
@@ -197,7 +196,7 @@ examples:
reg = <0 0x596e8000 0 0x88000>;
clocks = <&adma_lpcg 0>, <&adma_lpcg 1>, <&adma_lpcg 2>;
clock-names = "ipg", "ocram", "core";
- power-domains = <&pd 0>, <&pd 1>, <&pd 2>, <&pd 3>;
+ power-domains = <&pd 0>, <&pd 1>;
mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1";
mboxes = <&mhu_tx 2 0>, //data-transfer protocol with 5 windows, mhu-tx
<&mhu_tx 3 0>, //data-transfer protocol with 7 windows, mhu-tx
diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
new file mode 100644
index 000000000000..449b55afeb7d
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM MHUv3 Mailbox Controller
+
+maintainers:
+ - Sudeep Holla <sudeep.holla@arm.com>
+ - Cristian Marussi <cristian.marussi@arm.com>
+
+description: |
+ The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that
+ enables unidirectional communications with remote processors through various
+ possible transport protocols.
+ The controller can optionally support a varying number of extensions that, in
+ turn, enable different kinds of transport to be used for communication.
+ Number, type and characteristics of each supported extension can be discovered
+ dynamically at runtime.
+
+ Given the unidirectional nature of the controller, an MHUv3 mailbox controller
+ is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU
+ Receiver (MHUR) containing a MailBox (MBX) block, where
+
+ PBX is used to
+ - Configure the MHU
+ - Send Transfers to the Receiver
+ - Optionally receive acknowledgment of a Transfer from the Receiver
+
+ MBX is used to
+ - Configure the MHU
+ - Receive Transfers from the Sender
+ - Optionally acknowledge Transfers sent by the Sender
+
+ Both PBX and MBX need to be present and defined in the DT description if you
+ need to establish a bidirectional communication, since you will have to
+ acquire two distinct unidirectional channels, one for each block.
+
+ As a consequence both blocks needs to be represented separately and specified
+ as distinct DT nodes in order to properly describe their resources.
+
+ Note that, though, thanks to the runtime discoverability, there is no need to
+ identify the type of blocks with distinct compatibles.
+
+ Following are the MHUv3 possible extensions.
+
+ - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell
+ Channel (DBCH). DBCH enables a single bit Transfer to be sent from the
+ Sender to Receiver. The Transfer indicates that an event has occurred.
+ When DBE is implemented, the number of DBCHs that an implementation of the
+ MHU can support is between 1 and 128, numbered starting from 0 in ascending
+ order and discoverable at run-time.
+ Each DBCH contains 32 individual fields, referred to as flags, each of which
+ can be used independently. It is possible for the Sender to send multiple
+ Transfers at once using a single DBCH, so long as each Transfer uses
+ a different flag in the DBCH.
+ Optionally, data may be transmitted through an out-of-band shared memory
+ region, wherein the MHU Doorbell is used strictly as an interrupt generation
+ mechanism, but this is out of the scope of these bindings.
+
+ - FastChannel Extension (FCE): FCE defines a type of channel called a Fast
+ Channel (FCH). FCH is intended for lower overhead communication between
+ Sender and Receiver at the expense of determinism. An FCH allows the Sender
+ to update the channel value at any time, regardless of whether the previous
+ value has been seen by the Receiver. When the Receiver reads the channel's
+ content it gets the last value written to the channel.
+ FCH is considered lossy in nature, and means that the Sender has no way of
+ knowing if, or when, the Receiver will act on the Transfer.
+ FCHs are expected to behave as RAM which generates interrupts when writes
+ occur to the locations within the RAM.
+ When FCE is implemented, the number of FCHs that an implementation of the
+ MHU can support is between 1-1024, if the FastChannel word-size is 32-bits,
+ or between 1-512, when the FastChannel word-size is 64-bits.
+ FCHs are numbered from 0 in ascending order.
+ Note that the number of FCHs and the word-size are implementation defined,
+ not configurable but discoverable at run-time.
+ Optionally, data may be transmitted through an out-of-band shared memory
+ region, wherein the MHU FastChannel is used as an interrupt generation
+ mechanism which carries also a pointer to such out-of-band data, but this
+ is out of the scope of these bindings.
+
+ - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH).
+ FFCH allows a Sender to send
+ - Multiple Transfers to the Receiver without having to wait for the
+ previous Transfer to be acknowledged by the Receiver, as long as the
+ FIFO has room for the Transfer.
+ - Transfers which require the Receiver to provide acknowledgment.
+ - Transfers which have in-band payload.
+ In all cases, the data is guaranteed to be observed by the Receiver in the
+ same order which the Sender sent it.
+ When FE is implemented, the number of FFCHs that an implementation of the
+ MHU can support is between 1 and 64, numbered starting from 0 in ascending
+ order. The number of FFCHs, their depth (same for all implemented FFCHs) and
+ the access-granularity are implementation defined, not configurable but
+ discoverable at run-time.
+ Optionally, additional data may be transmitted through an out-of-band shared
+ memory region, wherein the MHU FIFO is used to transmit, in order, a small
+ part of the payload (like a header) and a reference to the shared memory
+ area holding the remaining, bigger, chunk of the payload, but this is out of
+ the scope of these bindings.
+
+properties:
+ compatible:
+ const: arm,mhuv3
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 74
+
+ interrupt-names:
+ description: |
+ The MHUv3 controller generates a number of events some of which are used
+ to generate interrupts; as a consequence it can expose a varying number of
+ optional PBX/MBX interrupts, representing the events generated during the
+ operation of the various transport protocols associated with different
+ extensions. All interrupts of the MHU are level-sensitive.
+ Some of these optional interrupts are defined per-channel, where the
+ number of channels effectively available is implementation defined and
+ run-time discoverable.
+ In the following names are enumerated using patterns, with per-channel
+ interrupts implicitly capped at the maximum channels allowed by the
+ specification for each extension type.
+ For the sake of simplicity maxItems is anyway capped to a most plausible
+ number, assuming way less channels would be implemented than actually
+ possible.
+
+ The only mandatory interrupts on the MHU are:
+ - combined
+ - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented.
+
+ minItems: 1
+ maxItems: 74
+ items:
+ oneOf:
+ - const: combined
+ description: PBX/MBX Combined interrupt
+ - const: combined-ffch
+ description: PBX/MBX FIFO Combined interrupt
+ - pattern: '^ffch-low-tide-[0-9]+$'
+ description: PBX/MBX FIFO Channel <N> Low Tide interrupt
+ - pattern: '^ffch-high-tide-[0-9]+$'
+ description: PBX/MBX FIFO Channel <N> High Tide interrupt
+ - pattern: '^ffch-flush-[0-9]+$'
+ description: PBX/MBX FIFO Channel <N> Flush interrupt
+ - pattern: '^mbx-dbch-xfer-[0-9]+$'
+ description: MBX Doorbell Channel <N> Transfer interrupt
+ - pattern: '^mbx-fch-xfer-[0-9]+$'
+ description: MBX FastChannel <N> Transfer interrupt
+ - pattern: '^mbx-fchgrp-xfer-[0-9]+$'
+ description: MBX FastChannel <N> Group Transfer interrupt
+ - pattern: '^mbx-ffch-xfer-[0-9]+$'
+ description: MBX FIFO Channel <N> Transfer interrupt
+ - pattern: '^pbx-dbch-xfer-ack-[0-9]+$'
+ description: PBX Doorbell Channel <N> Transfer Ack interrupt
+ - pattern: '^pbx-ffch-xfer-ack-[0-9]+$'
+ description: PBX FIFO Channel <N> Transfer Ack interrupt
+
+ '#mbox-cells':
+ description: |
+ The first argument in the consumers 'mboxes' property represents the
+ extension type, the second is for the channel number while the third
+ depends on extension type.
+
+ Extension types constants are defined in <dt-bindings/arm/mhuv3-dt.h>.
+
+ Extension type for DBE is DBE_EXT and the third parameter represents the
+ doorbell flag number to use.
+ Extension type for FCE is FCE_EXT, third parameter unused.
+ Extension type for FE is FE_EXT, third parameter unused.
+
+ mboxes = <&mhu DBE_EXT 0 5>; // DBE, Doorbell Channel Window 0, doorbell 5.
+ mboxes = <&mhu DBE_EXT 7>; // DBE, Doorbell Channel Window 1, doorbell 7.
+ mboxes = <&mhu FCE_EXT 0 0>; // FCE, FastChannel Window 0.
+ mboxes = <&mhu FCE_EXT 3 0>; // FCE, FastChannel Window 3.
+ mboxes = <&mhu FE_EXT 1 0>; // FE, FIFO Channel Window 1.
+ mboxes = <&mhu FE_EXT 7 0>; // FE, FIFO Channel Window 7.
+ const: 3
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ mailbox@2aaa0000 {
+ compatible = "arm,mhuv3";
+ #mbox-cells = <3>;
+ reg = <0 0x2aaa0000 0 0x10000>;
+ clocks = <&clock 0>;
+ interrupt-names = "combined", "pbx-dbch-xfer-ack-1",
+ "ffch-high-tide-0";
+ interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;
+ };
+
+ mailbox@2ab00000 {
+ compatible = "arm,mhuv3";
+ #mbox-cells = <3>;
+ reg = <0 0x2aab0000 0 0x10000>;
+ clocks = <&clock 0>;
+ interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0";
+ interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/aspeed,ast2700-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/aspeed,ast2700-mailbox.yaml
new file mode 100644
index 000000000000..600e2d63fccd
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/aspeed,ast2700-mailbox.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/aspeed,ast2700-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED AST2700 mailbox controller
+
+maintainers:
+ - Jammy Huang <jammy_huang@aspeedtech.com>
+
+description: >
+ ASPEED AST2700 has multiple processors that need to communicate with each
+ other. The mailbox controller provides a way for these processors to send
+ messages to each other. It is a hardware-based inter-processor communication
+ mechanism that allows processors to send and receive messages through
+ dedicated channels.
+
+ The mailbox's tx/rx are independent, meaning that one processor can send a
+ message while another processor is receiving a message simultaneously.
+ There are 4 channels available for both tx and rx operations. Each channel
+ has a FIFO buffer that can hold messages of a fixed size (32 bytes in this
+ case).
+
+ The mailbox controller also supports interrupt generation, allowing
+ processors to notify each other when a message is available or when an event
+ occurs.
+
+properties:
+ compatible:
+ const: aspeed,ast2700-mailbox
+
+ reg:
+ items:
+ - description: TX control register
+ - description: RX control register
+
+ reg-names:
+ items:
+ - const: tx
+ - const: rx
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox@12c1c200 {
+ compatible = "aspeed,ast2700-mailbox";
+ reg = <0x12c1c200 0x100>, <0x12c1c300 0x100>;
+ reg-names = "tx", "rx";
+ interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.txt
deleted file mode 100644
index b48d7d30012c..000000000000
--- a/Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Broadcom BCM2835 VideoCore mailbox IPC
-
-Required properties:
-
-- compatible: Should be "brcm,bcm2835-mbox"
-- reg: Specifies base physical address and size of the registers
-- interrupts: The interrupt number
- See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
-- #mbox-cells: Specifies the number of cells needed to encode a mailbox
- channel. The value shall be 0, since there is only one
- mailbox channel implemented by the device.
-
-Example:
-
-mailbox: mailbox@7e00b880 {
- compatible = "brcm,bcm2835-mbox";
- reg = <0x7e00b880 0x40>;
- interrupts = <0 1>;
- #mbox-cells = <0>;
-};
-
-firmware: firmware {
- compatible = "raspberrypi,firmware";
- mboxes = <&mailbox>;
- #power-domain-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.yaml b/Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.yaml
new file mode 100644
index 000000000000..9588817f4511
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/brcm,bcm2835-mbox.yaml
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/brcm,bcm2835-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM2835 VideoCore mailbox IPC
+
+maintainers:
+ - Stefan Wahren <stefan.wahren@i2se.com>
+
+properties:
+ compatible:
+ const: brcm,bcm2835-mbox
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ mailbox@7e00b880 {
+ compatible = "brcm,bcm2835-mbox";
+ reg = <0x7e00b880 0x40>;
+ interrupts = <0 1>;
+ #mbox-cells = <0>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,bcm74110-mbox.yaml b/Documentation/devicetree/bindings/mailbox/brcm,bcm74110-mbox.yaml
new file mode 100644
index 000000000000..750cc96edb46
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/brcm,bcm74110-mbox.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/brcm,bcm74110-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM74110 Mailbox
+
+maintainers:
+ - Justin Chen <justin.chen@broadcom.com>
+ - Florian Fainelli <florian.fainelli@broadcom.com>
+
+description: Broadcom mailbox hardware first introduced with 74110
+
+properties:
+ compatible:
+ enum:
+ - brcm,bcm74110-mbox
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ items:
+ - description: RX doorbell and watermark interrupts
+ - description: TX doorbell and watermark interrupts
+
+ "#mbox-cells":
+ const: 2
+ description:
+ The first cell is channel type and second cell is shared memory slot
+
+ brcm,rx:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: RX Mailbox number
+
+ brcm,tx:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: TX Mailbox number
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+ - brcm,rx
+ - brcm,tx
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox@a552000 {
+ compatible = "brcm,bcm74110-mbox";
+ reg = <0xa552000 0x1104>;
+ interrupts = <GIC_SPI 0x67 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 0x66 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <0x2>;
+ brcm,rx = <0x7>;
+ brcm,tx = <0x6>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt
deleted file mode 100644
index 752ae6b00d26..000000000000
--- a/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-Broadcom FlexRM Ring Manager
-============================
-The Broadcom FlexRM ring manager provides a set of rings which can be
-used to submit work to offload engines. An SoC may have multiple FlexRM
-hardware blocks. There is one device tree entry per FlexRM block. The
-FlexRM driver will create a mailbox-controller instance for given FlexRM
-hardware block where each mailbox channel is a separate FlexRM ring.
-
-Required properties:
---------------------
-- compatible: Should be "brcm,iproc-flexrm-mbox"
-- reg: Specifies base physical address and size of the FlexRM
- ring registers
-- msi-parent: Phandles (and potential Device IDs) to MSI controllers
- The FlexRM engine will send MSIs (instead of wired
- interrupts) to CPU. There is one MSI for each FlexRM ring.
- Refer devicetree/bindings/interrupt-controller/msi.txt
-- #mbox-cells: Specifies the number of cells needed to encode a mailbox
- channel. This should be 3.
-
- The 1st cell is the mailbox channel number.
-
- The 2nd cell contains MSI completion threshold. This is the
- number of completion messages for which FlexRM will inject
- one MSI interrupt to CPU.
-
- The 3nd cell contains MSI timer value representing time for
- which FlexRM will wait to accumulate N completion messages
- where N is the value specified by 2nd cell above. If FlexRM
- does not get required number of completion messages in time
- specified by this cell then it will inject one MSI interrupt
- to CPU provided atleast one completion message is available.
-
-Optional properties:
---------------------
-- dma-coherent: Present if DMA operations made by the FlexRM engine (such
- as DMA descriptor access, access to buffers pointed by DMA
- descriptors and read/write pointer updates to DDR) are
- cache coherent with the CPU.
-
-Example:
---------
-crypto_mbox: mbox@67000000 {
- compatible = "brcm,iproc-flexrm-mbox";
- reg = <0x67000000 0x200000>;
- msi-parent = <&gic_its 0x7f00>;
- #mbox-cells = <3>;
-};
-
-crypto@672c0000 {
- compatible = "brcm,spu2-v2-crypto";
- reg = <0x672c0000 0x1000>;
- mboxes = <&crypto_mbox 0 0x1 0xffff>,
- <&crypto_mbox 1 0x1 0xffff>,
- <&crypto_mbox 16 0x1 0xffff>,
- <&crypto_mbox 17 0x1 0xffff>,
- <&crypto_mbox 30 0x1 0xffff>,
- <&crypto_mbox 31 0x1 0xffff>;
-};
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.yaml b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.yaml
new file mode 100644
index 000000000000..c801bd2e95f3
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/brcm,iproc-flexrm-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom FlexRM Ring Manager
+
+maintainers:
+ - Ray Jui <rjui@broadcom.com>
+ - Scott Branden <sbranden@broadcom.com>
+
+description:
+ The Broadcom FlexRM ring manager provides a set of rings which can be used to
+ submit work to offload engines. An SoC may have multiple FlexRM hardware
+ blocks. There is one device tree entry per FlexRM block. The FlexRM driver
+ will create a mailbox-controller instance for given FlexRM hardware block
+ where each mailbox channel is a separate FlexRM ring.
+
+properties:
+ compatible:
+ const: brcm,iproc-flexrm-mbox
+
+ reg:
+ maxItems: 1
+
+ msi-parent:
+ maxItems: 1
+
+ '#mbox-cells':
+ description: >
+ The 1st cell is the mailbox channel number.
+
+ The 2nd cell contains MSI completion threshold. This is the number of
+ completion messages for which FlexRM will inject one MSI interrupt to CPU.
+
+ The 3rd cell contains MSI timer value representing time for which FlexRM
+ will wait to accumulate N completion messages where N is the value
+ specified by 2nd cell above. If FlexRM does not get required number of
+ completion messages in time specified by this cell then it will inject one
+ MSI interrupt to CPU provided at least one completion message is
+ available.
+ const: 3
+
+ dma-coherent: true
+
+required:
+ - compatible
+ - reg
+ - msi-parent
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ mailbox@67000000 {
+ compatible = "brcm,iproc-flexrm-mbox";
+ reg = <0x67000000 0x200000>;
+ msi-parent = <&gic_its 0x7f00>;
+ #mbox-cells = <3>;
+ dma-coherent;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt
deleted file mode 100644
index 9bcdf2087625..000000000000
--- a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-The PDC driver manages data transfer to and from various offload engines
-on some Broadcom SoCs. An SoC may have multiple PDC hardware blocks. There is
-one device tree entry per block. On some chips, the PDC functionality is
-handled by the FA2 (Northstar Plus).
-
-Required properties:
-- compatible : Should be "brcm,iproc-pdc-mbox" or "brcm,iproc-fa2-mbox" for
- FA2/Northstar Plus.
-- reg: Should contain PDC registers location and length.
-- interrupts: Should contain the IRQ line for the PDC.
-- #mbox-cells: 1
-- brcm,rx-status-len: Length of metadata preceding received frames, in bytes.
-
-Optional properties:
-- brcm,use-bcm-hdr: present if a BCM header precedes each frame.
-
-Example:
- pdc0: iproc-pdc0@612c0000 {
- compatible = "brcm,iproc-pdc-mbox";
- reg = <0 0x612c0000 0 0x445>; /* PDC FS0 regs */
- interrupts = <GIC_SPI 187 IRQ_TYPE_LEVEL_HIGH>;
- #mbox-cells = <1>; /* one cell per mailbox channel */
- brcm,rx-status-len = <32>;
- brcm,use-bcm-hdr;
- };
diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.yaml b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.yaml
new file mode 100644
index 000000000000..5534ae07c9fa
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/brcm,iproc-pdc-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom iProc PDC mailbox
+
+maintainers:
+ - Ray Jui <rjui@broadcom.com>
+ - Scott Branden <sbranden@broadcom.com>
+
+description:
+ The PDC driver manages data transfer to and from various offload engines on
+ some Broadcom SoCs. An SoC may have multiple PDC hardware blocks. There is one
+ device tree entry per block. On some chips, the PDC functionality is handled
+ by the FA2 (Northstar Plus).
+
+properties:
+ compatible:
+ enum:
+ - brcm,iproc-pdc-mbox
+ - brcm,iproc-fa2-mbox
+
+ reg:
+ maxItems: 1
+
+ dma-coherent: true
+
+ interrupts:
+ maxItems: 1
+
+ '#mbox-cells':
+ const: 1
+
+ brcm,rx-status-len:
+ description:
+ Length of metadata preceding received frames, in bytes.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ brcm,use-bcm-hdr:
+ type: boolean
+ description:
+ Present if a BCM header precedes each frame.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#mbox-cells'
+ - brcm,rx-status-len
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox0@612c0000 {
+ compatible = "brcm,iproc-pdc-mbox";
+ reg = <0x612c0000 0x445>;
+ interrupts = <GIC_SPI 187 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <1>;
+ brcm,rx-status-len = <32>;
+ brcm,use-bcm-hdr;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/cix,sky1-mbox.yaml b/Documentation/devicetree/bindings/mailbox/cix,sky1-mbox.yaml
new file mode 100644
index 000000000000..66d75b7bc8c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/cix,sky1-mbox.yaml
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/cix,sky1-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cixtech mailbox controller
+
+maintainers:
+ - Guomin Chen <Guomin.Chen@cixtech.com>
+
+description:
+ The Cixtech mailbox controller, used in the Cixtech Sky1 SoC,
+ is used for message transmission between multiple processors
+ within the SoC, such as the AP, PM, audio DSP, SensorHub MCU,
+ and others
+
+ Each Cixtech mailbox controller is unidirectional, so they are
+ typically used in pairs-one for receiving and one for transmitting.
+
+ Each Cixtech mailbox supports 11 channels with different transmission modes
+ channel 0-7 - Fast channel with 32bit transmit register and IRQ support
+ channel 8 - Doorbell mode,using the mailbox as an interrupt-generating
+ mechanism.
+ channel 9 - Fifo based channel with 32*32bit depth fifo and IRQ support
+ channel 10 - Reg based channel with 32*32bit transmit register and
+ Doorbell+transmit acknowledgment IRQ support
+
+ In the CIX Sky1 SoC use case, there are 4 pairs of mailbox controllers
+ AP <--> PM - using Doorbell transfer mode
+ AP <--> SE - using REG transfer mode
+ AP <--> DSP - using FIFO transfer mode
+ AP <--> SensorHub - using FIFO transfer mode
+
+properties:
+ compatible:
+ const: cix,sky1-mbox
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 1
+
+ cix,mbox-dir:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: Direction of the mailbox relative to the AP
+ enum: [tx, rx]
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+ - cix,mbox-dir
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ mbox_ap2pm: mailbox@30000000 {
+ compatible = "cix,sky1-mbox";
+ reg = <0 0x30000000 0 0x10000>;
+ interrupts = <GIC_SPI 136 IRQ_TYPE_LEVEL_HIGH 0>;
+ #mbox-cells = <1>;
+ cix,mbox-dir = "tx";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml
index 675ad9de15bb..581425aacdcc 100644
--- a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml
+++ b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml
@@ -28,6 +28,15 @@ properties:
- const: fsl,imx7ulp-mu
- const: fsl,imx8ulp-mu
- const: fsl,imx8-mu-scu
+ - const: fsl,imx8-mu-seco
+ - const: fsl,imx8ulp-mu-s4
+ - const: fsl,imx93-mu-s4
+ - const: fsl,imx95-mu
+ - const: fsl,imx95-mu-ele
+ - const: fsl,imx95-mu-v2x
+ - items:
+ - const: fsl,imx93-mu
+ - const: fsl,imx8ulp-mu
- items:
- enum:
- fsl,imx7s-mu
@@ -45,12 +54,23 @@ properties:
- fsl,imx8qm-mu
- fsl,imx8qxp-mu
- const: fsl,imx6sx-mu
+ - items:
+ - enum:
+ - fsl,imx94-mu
+ - const: fsl,imx95-mu
reg:
maxItems: 1
interrupts:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: tx
+ - const: rx
"#mbox-cells":
description: |
@@ -59,14 +79,17 @@ properties:
type : Channel type
channel : Channel number
- This MU support 4 type of unidirectional channels, each type
- has 4 channels. A total of 16 channels. Following types are
+ This MU support 6 type of unidirectional channels, each type
+ has 4 channels except RST channel which only has 1 channel.
+ A total of 21 channels. Following types are
supported:
0 - TX channel with 32bit transmit register and IRQ transmit
acknowledgment support.
1 - RX channel with 32bit receive register and IRQ support
2 - TX doorbell channel. Without own register and no ACK support.
3 - RX doorbell channel.
+ 4 - RST channel
+ 5 - Tx doorbell channel. With S/W ACK from the other side.
const: 2
clocks:
@@ -79,12 +102,56 @@ properties:
power-domains:
maxItems: 1
+ ranges: true
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+patternProperties:
+ "^sram@[a-f0-9]+":
+ $ref: /schemas/sram/sram.yaml#
+ unevaluatedProperties: false
+
required:
- compatible
- reg
- interrupts
- "#mbox-cells"
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - fsl,imx93-mu-s4
+ then:
+ properties:
+ interrupt-names:
+ minItems: 2
+ interrupts:
+ minItems: 2
+
+ else:
+ properties:
+ interrupts:
+ maxItems: 1
+ not:
+ required:
+ - interrupt-names
+
+ - if:
+ not:
+ properties:
+ compatible:
+ contains:
+ const: fsl,imx95-mu
+ then:
+ patternProperties:
+ "^sram@[a-f0-9]+": false
+
additionalProperties: false
examples:
@@ -97,3 +164,34 @@ examples:
interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>;
#mbox-cells = <2>;
};
+
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox@445b0000 {
+ compatible = "fsl,imx95-mu";
+ reg = <0x445b0000 0x10000>;
+ ranges;
+ interrupts = <GIC_SPI 226 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ #mbox-cells = <2>;
+
+ sram@445b1000 {
+ compatible = "mmio-sram";
+ reg = <0x445b1000 0x400>;
+ ranges = <0x0 0x445b1000 0x400>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ scmi-sram-section@0 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x0 0x80>;
+ };
+
+ scmi-sram-section@80 {
+ compatible = "arm,scmi-shmem";
+ reg = <0x80 0x80>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/google,gs101-mbox.yaml b/Documentation/devicetree/bindings/mailbox/google,gs101-mbox.yaml
new file mode 100644
index 000000000000..e249db4c1fbc
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/google,gs101-mbox.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2024 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/google,gs101-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos Mailbox Controller
+
+maintainers:
+ - Tudor Ambarus <tudor.ambarus@linaro.org>
+
+description:
+ The Samsung Exynos mailbox controller, used on Google GS101 SoC, has 16 flag
+ bits for hardware interrupt generation and a shared register for passing
+ mailbox messages. When the controller is used by the ACPM interface
+ the shared register is ignored and the mailbox controller acts as a doorbell.
+ The controller just raises the interrupt to the firmware after the
+ ACPM interface has written the message to SRAM.
+
+properties:
+ compatible:
+ const: google,gs101-mbox
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: pclk
+
+ interrupts:
+ description: IRQ line for the RX mailbox.
+ maxItems: 1
+
+ '#mbox-cells':
+ const: 0
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/google,gs101.h>
+
+ soc {
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ ap2apm_mailbox: mailbox@17610000 {
+ compatible = "google,gs101-mbox";
+ reg = <0x17610000 0x1000>;
+ clocks = <&cmu_apm CLK_GOUT_APM_MAILBOX_APM_AP_PCLK>;
+ clock-names = "pclk";
+ interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH 0>;
+ #mbox-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.txt b/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.txt
deleted file mode 100644
index 282ab81a4ea6..000000000000
--- a/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-* rWTM BIU Mailbox driver for Armada 37xx
-
-Required properties:
-- compatible: must be "marvell,armada-3700-rwtm-mailbox"
-- reg: physical base address of the mailbox and length of memory mapped
- region
-- interrupts: the IRQ line for the mailbox
-- #mbox-cells: must be 1
-
-Example:
- rwtm: mailbox@b0000 {
- compatible = "marvell,armada-3700-rwtm-mailbox";
- reg = <0xb0000 0x100>;
- interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>;
- #mbox-cells = <1>;
- };
diff --git a/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.yaml
new file mode 100644
index 000000000000..0a07ed1b1beb
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/marvell,armada-3700-rwtm-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Marvell Armada 3700 rWTM Mailbox
+
+maintainers:
+ - Marek Behún <kabel@kernel.org>
+
+properties:
+ compatible:
+ const: marvell,armada-3700-rwtm-mailbox
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ '#mbox-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox@b0000 {
+ compatible = "marvell,armada-3700-rwtm-mailbox";
+ reg = <0xb0000 0x100>;
+ interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/mediatek,gce-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/mediatek,gce-mailbox.yaml
new file mode 100644
index 000000000000..587126d03fc6
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/mediatek,gce-mailbox.yaml
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/mediatek,gce-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek Global Command Engine Mailbox
+
+maintainers:
+ - Houlong Wei <houlong.wei@mediatek.com>
+
+description:
+ The Global Command Engine (GCE) is used to help read/write registers with
+ critical time limitation, such as updating display configuration during the
+ vblank. The GCE can be used to implement the Command Queue (CMDQ) driver.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt6779-gce
+ - mediatek,mt8173-gce
+ - mediatek,mt8183-gce
+ - mediatek,mt8186-gce
+ - mediatek,mt8188-gce
+ - mediatek,mt8192-gce
+ - mediatek,mt8195-gce
+ - mediatek,mt8196-gce
+ - items:
+ - const: mediatek,mt6795-gce
+ - const: mediatek,mt8173-gce
+
+ "#mbox-cells":
+ const: 2
+ description:
+ The first cell describes the Thread ID of the GCE,
+ the second cell describes the priority of the GCE thread
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Global Command Engine clock
+
+ clock-names:
+ items:
+ - const: gce
+
+ iommus:
+ maxItems: 1
+
+required:
+ - compatible
+ - "#mbox-cells"
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8173-clk.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ gce: mailbox@10212000 {
+ compatible = "mediatek,mt8173-gce";
+ reg = <0 0x10212000 0 0x1000>;
+ interrupts = <GIC_SPI 135 IRQ_TYPE_LEVEL_LOW>;
+ #mbox-cells = <2>;
+ clocks = <&infracfg CLK_INFRA_GCE>;
+ clock-names = "gce";
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/mediatek,gce-props.yaml b/Documentation/devicetree/bindings/mailbox/mediatek,gce-props.yaml
new file mode 100644
index 000000000000..c25eed4606fe
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/mediatek,gce-props.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/mediatek,gce-props.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Global Command Engine Common Properties
+
+maintainers:
+ - Houlong Wei <houlong.wei@mediatek.com>
+
+description:
+ The Global Command Engine (GCE) is an instruction based, multi-threaded,
+ single-core command dispatcher for MediaTek hardware. The Command Queue
+ (CMDQ) mailbox driver is a driver for GCE, implemented using the Linux
+ mailbox framework. It is used to receive messages from mailbox consumers
+ and configure GCE to execute the specified instruction set in the message.
+ We use mediatek,gce-mailbox.yaml to define the properties for CMDQ mailbox
+ driver. A device driver that uses the CMDQ driver to configure its hardware
+ registers is a mailbox consumer. The mailbox consumer can request a mailbox
+ channel corresponding to a GCE hardware thread to send a message, specifying
+ that the GCE thread to configure its hardware. The mailbox provider can also
+ reserve a mailbox channel to configure GCE hardware register by the specific
+ GCE thread. This binding defines the common GCE properties for both mailbox
+ provider and consumers.
+
+properties:
+ mediatek,gce-events:
+ description:
+ GCE has an event table in SRAM, consisting of 1024 event IDs (0~1023).
+ Each event ID has a boolean event value with the default value 0.
+ The property mediatek,gce-events is used to obtain the event IDs.
+ Some gce-events are hardware-bound and cannot be changed by software.
+ For instance, in MT8195, when VDO0_MUTEX is stream done, VDO_MUTEX will
+ send an event signal to GCE, setting the value of event ID 597 to 1.
+ Similarly, in MT8188, the value of event ID 574 will be set to 1 when
+ VOD0_MUTEX is stream done.
+ On the other hand, some gce-events are not hardware-bound and can be
+ changed by software. For example, in MT8188, we can set the value of
+ event ID 855, which is not bound to any hardware, to 1 when the driver
+ in the secure world completes a task. However, in MT8195, event ID 855
+ is already bound to VDEC_LAT1, so we need to select another event ID to
+ achieve the same purpose. This event ID can be any ID that is not bound
+ to any hardware and is not yet used in any software driver.
+ To determine if the event ID is bound to the hardware or used by a
+ software driver, refer to the GCE header
+ include/dt-bindings/gce/<chip>-gce.h of each chip.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 32
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/mailbox/mediatek,mt8196-gpueb-mbox.yaml b/Documentation/devicetree/bindings/mailbox/mediatek,mt8196-gpueb-mbox.yaml
new file mode 100644
index 000000000000..ab5b780cb83a
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/mediatek,mt8196-gpueb-mbox.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/mediatek,mt8196-gpueb-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek MFlexGraphics GPUEB Mailbox Controller
+
+maintainers:
+ - Nicolas Frattaroli <nicolas.frattaroli@collabora.com>
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt8196-gpueb-mbox
+
+ reg:
+ items:
+ - description: mailbox data registers
+ - description: mailbox control registers
+
+ reg-names:
+ items:
+ - const: data
+ - const: ctl
+
+ clocks:
+ items:
+ - description: main clock of the GPUEB MCU
+
+ interrupts:
+ items:
+ - description: fires when a new message is received
+
+ "#mbox-cells":
+ const: 1
+ description:
+ The number of the mailbox channel.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - interrupts
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mediatek,mt8196-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ mailbox@4b09fd80 {
+ compatible = "mediatek,mt8196-gpueb-mbox";
+ reg = <0x4b09fd80 0x280>,
+ <0x4b170000 0x7c>;
+ reg-names = "data", "ctl";
+ clocks = <&topckgen CLK_TOP_MFG_EB>;
+ interrupts = <GIC_SPI 608 IRQ_TYPE_LEVEL_HIGH 0>;
+ #mbox-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/microchip,mpfs-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/microchip,mpfs-mailbox.yaml
new file mode 100644
index 000000000000..1332aab9a888
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/microchip,mpfs-mailbox.yaml
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/microchip,mpfs-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip PolarFire SoC (MPFS) MSS (microprocessor subsystem) mailbox controller
+
+maintainers:
+ - Conor Dooley <conor.dooley@microchip.com>
+
+properties:
+ compatible:
+ const: microchip,mpfs-mailbox
+
+ reg:
+ oneOf:
+ - items:
+ - description: mailbox data registers
+ - items:
+ - description: mailbox control & data registers
+ - description: mailbox interrupt registers
+ deprecated: true
+ - items:
+ - description: mailbox control registers
+ - description: mailbox interrupt registers
+ - description: mailbox data registers
+ deprecated: true
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ soc {
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ mailbox@37020800 {
+ compatible = "microchip,mpfs-mailbox";
+ reg = <0x37020800 0x100>;
+ interrupt-parent = <&L1>;
+ interrupts = <96>;
+ #mbox-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/microchip,polarfire-soc-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/microchip,polarfire-soc-mailbox.yaml
deleted file mode 100644
index bbb173ea483c..000000000000
--- a/Documentation/devicetree/bindings/mailbox/microchip,polarfire-soc-mailbox.yaml
+++ /dev/null
@@ -1,47 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: "http://devicetree.org/schemas/mailbox/microchip,polarfire-soc-mailbox.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
-
-title: Microchip PolarFire SoC (MPFS) MSS (microprocessor subsystem) mailbox controller
-
-maintainers:
- - Conor Dooley <conor.dooley@microchip.com>
-
-properties:
- compatible:
- const: microchip,polarfire-soc-mailbox
-
- reg:
- items:
- - description: mailbox data registers
- - description: mailbox interrupt registers
-
- interrupts:
- maxItems: 1
-
- "#mbox-cells":
- const: 1
-
-required:
- - compatible
- - reg
- - interrupts
- - "#mbox-cells"
-
-additionalProperties: false
-
-examples:
- - |
- soc {
- #address-cells = <2>;
- #size-cells = <2>;
- mbox: mailbox@37020000 {
- compatible = "microchip,polarfire-soc-mailbox";
- reg = <0x0 0x37020000 0x0 0x1000>, <0x0 0x2000318c 0x0 0x40>;
- interrupt-parent = <&L1>;
- interrupts = <96>;
- #mbox-cells = <1>;
- };
- };
diff --git a/Documentation/devicetree/bindings/mailbox/microchip,sbi-ipc.yaml b/Documentation/devicetree/bindings/mailbox/microchip,sbi-ipc.yaml
new file mode 100644
index 000000000000..8ed67ea7c883
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/microchip,sbi-ipc.yaml
@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/microchip,sbi-ipc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip Inter-processor communication (IPC) mailbox controller
+
+maintainers:
+ - Valentina Fernandez <valentina.fernandezalanis@microchip.com>
+
+description:
+ The Microchip Inter-processor Communication (IPC) facilitates
+ message passing between processors using an interrupt signaling
+ mechanism.
+
+properties:
+ compatible:
+ oneOf:
+ - description:
+ Intended for use by software running in supervisor privileged
+ mode (s-mode). This SBI interface is compatible with the Mi-V
+ Inter-hart Communication (IHC) IP.
+ const: microchip,sbi-ipc
+
+ - description:
+ Intended for use by the SBI implementation in machine mode
+ (m-mode), this compatible string is for the MIV_IHC Soft-IP.
+ const: microchip,miv-ihc-rtl-v2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 5
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 5
+ items:
+ enum:
+ - hart-0
+ - hart-1
+ - hart-2
+ - hart-3
+ - hart-4
+ - hart-5
+
+ "#mbox-cells":
+ description: >
+ For "microchip,sbi-ipc", the cell represents the global "logical"
+ channel IDs. The meaning of channel IDs are platform firmware dependent.
+
+ For "microchip,miv-ihc-rtl-v2", the cell represents the physical
+ channel and does not vary based on the platform firmware.
+ const: 1
+
+ microchip,ihc-chan-disabled-mask:
+ description: >
+ Represents the enable/disable state of the bi-directional IHC
+ channels within the MIV-IHC IP configuration.
+
+ A bit set to '1' indicates that the corresponding channel is disabled,
+ and any read or write operations to that channel will return zero.
+
+ A bit set to '0' indicates that the corresponding channel is enabled
+ and will be accessible through its dedicated address range registers.
+
+ The actual enable/disable state of each channel is determined by the
+ IP block’s configuration.
+ $ref: /schemas/types.yaml#/definitions/uint16
+ maximum: 0x7fff
+ default: 0
+
+required:
+ - compatible
+ - interrupts
+ - interrupt-names
+ - "#mbox-cells"
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: microchip,sbi-ipc
+ then:
+ properties:
+ reg:
+ not: {}
+ description:
+ The 'microchip,sbi-ipc' operates in a programming model
+ that does not require memory-mapped I/O (MMIO) registers
+ since it uses SBI ecalls provided by the m-mode/firmware
+ SBI implementation to access hardware registers.
+ microchip,ihc-chan-disabled-mask: false
+ else:
+ required:
+ - reg
+ - microchip,ihc-chan-disabled-mask
+
+additionalProperties: false
+
+examples:
+ - |
+ mailbox {
+ compatible = "microchip,sbi-ipc";
+ interrupt-parent = <&plic>;
+ interrupts = <180>, <179>, <178>;
+ interrupt-names = "hart-1", "hart-2", "hart-3";
+ #mbox-cells = <1>;
+ };
+ - |
+ mailbox@50000000 {
+ compatible = "microchip,miv-ihc-rtl-v2";
+ microchip,ihc-chan-disabled-mask = /bits/ 16 <0>;
+ reg = <0x50000000 0x1c000>;
+ interrupt-parent = <&plic>;
+ interrupts = <180>, <179>, <178>;
+ interrupt-names = "hart-1", "hart-2", "hart-3";
+ #mbox-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/mtk,adsp-mbox.yaml b/Documentation/devicetree/bindings/mailbox/mtk,adsp-mbox.yaml
new file mode 100644
index 000000000000..4ca0d5e49c79
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/mtk,adsp-mbox.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/mtk,adsp-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek ADSP mailbox
+
+maintainers:
+ - Allen-KH Cheng <Allen-KH.Cheng@mediatek.com>
+
+description: |
+ The MTK ADSP mailbox Inter-Processor Communication (IPC) enables the SoC
+ to communicate with ADSP by passing messages through two mailbox channels.
+ The MTK ADSP mailbox IPC also provides the ability for one processor to
+ signal the other processor using interrupts.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8186-adsp-mbox
+ - mediatek,mt8195-adsp-mbox
+ - items:
+ - enum:
+ - mediatek,mt8188-adsp-mbox
+ - const: mediatek,mt8186-adsp-mbox
+
+ "#mbox-cells":
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - "#mbox-cells"
+ - reg
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ adsp_mailbox0:mailbox@10816000 {
+ compatible = "mediatek,mt8195-adsp-mbox";
+ #mbox-cells = <0>;
+ reg = <0x10816000 0x1000>;
+ interrupts = <GIC_SPI 702 IRQ_TYPE_LEVEL_HIGH 0>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
deleted file mode 100644
index 7771ecaac586..000000000000
--- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-MediaTek GCE
-===============
-
-The Global Command Engine (GCE) is used to help read/write registers with
-critical time limitation, such as updating display configuration during the
-vblank. The GCE can be used to implement the Command Queue (CMDQ) driver.
-
-CMDQ driver uses mailbox framework for communication. Please refer to
-mailbox.txt for generic information about mailbox device-tree bindings.
-
-Required properties:
-- compatible: can be "mediatek,mt8173-gce", "mediatek,mt8183-gce" or
- "mediatek,mt6779-gce".
-- reg: Address range of the GCE unit
-- interrupts: The interrupt signal from the GCE block
-- clock: Clocks according to the common clock binding
-- clock-names: Must be "gce" to stand for GCE clock
-- #mbox-cells: Should be 2.
- <&phandle channel priority>
- phandle: Label name of a gce node.
- channel: Channel of mailbox. Be equal to the thread id of GCE.
- priority: Priority of GCE thread.
-
-Required properties for a client device:
-- mboxes: Client use mailbox to communicate with GCE, it should have this
- property and list of phandle, mailbox specifiers.
-Optional properties for a client device:
-- mediatek,gce-client-reg: Specify the sub-system id which is corresponding
- to the register address, it should have this property and list of phandle,
- sub-system specifiers.
- <&phandle subsys_number start_offset size>
- phandle: Label name of a gce node.
- subsys_number: specify the sub-system id which is corresponding
- to the register address.
- start_offset: the start offset of register address that GCE can access.
- size: the total size of register address that GCE can access.
-
-Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h',
-'dt-binding/gce/mt8183-gce.h' or 'dt-bindings/gce/mt6779-gce.h'. Such as
-sub-system ids, thread priority, event ids.
-
-Example:
-
- gce: gce@10212000 {
- compatible = "mediatek,mt8173-gce";
- reg = <0 0x10212000 0 0x1000>;
- interrupts = <GIC_SPI 135 IRQ_TYPE_LEVEL_LOW>;
- clocks = <&infracfg CLK_INFRA_GCE>;
- clock-names = "gce";
- #mbox-cells = <2>;
- };
-
-Example for a client device:
-
- mmsys: clock-controller@14000000 {
- compatible = "mediatek,mt8173-mmsys";
- mboxes = <&gce 0 CMDQ_THR_PRIO_LOWEST>,
- <&gce 1 CMDQ_THR_PRIO_LOWEST>;
- mutex-event-eof = <CMDQ_EVENT_MUTEX0_STREAM_EOF
- CMDQ_EVENT_MUTEX1_STREAM_EOF>;
- mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x3000 0x1000>,
- <&gce SUBSYS_1401XXXX 0x2000 0x100>;
- ...
- };
diff --git a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt
deleted file mode 100644
index ff3eafc5a882..000000000000
--- a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-NVIDIA Tegra Hardware Synchronization Primitives (HSP)
-
-The HSP modules are used for the processors to share resources and communicate
-together. It provides a set of hardware synchronization primitives for
-interprocessor communication. So the interprocessor communication (IPC)
-protocols can use hardware synchronization primitives, when operating between
-two processors not in an SMP relationship.
-
-The features that HSP supported are shared mailboxes, shared semaphores,
-arbitrated semaphores and doorbells.
-
-Required properties:
-- name : Should be hsp
-- compatible
- Array of strings.
- one of:
- - "nvidia,tegra186-hsp"
- - "nvidia,tegra194-hsp", "nvidia,tegra186-hsp"
-- reg : Offset and length of the register set for the device.
-- interrupt-names
- Array of strings.
- Contains a list of names for the interrupts described by the interrupt
- property. May contain the following entries, in any order:
- - "doorbell"
- - "sharedN", where 'N' is a number from zero up to the number of
- external interrupts supported by the HSP instance minus one.
- Users of this binding MUST look up entries in the interrupt property
- by name, using this interrupt-names property to do so.
-- interrupts
- Array of interrupt specifiers.
- Must contain one entry per entry in the interrupt-names property,
- in a matching order.
-- #mbox-cells : Should be 2.
-
-The mbox specifier of the "mboxes" property in the client node should contain
-two cells. The first cell determines the HSP type and the second cell is used
-to identify the mailbox that the client is going to use.
-
-For doorbells, the second cell specifies the index of the doorbell to use.
-
-For shared mailboxes, the second cell is composed of two fields:
-- bits 31..24:
- A bit mask of flags that further specify how the shared mailbox will be
- used. Valid flags are:
- - bit 31:
- Defines the direction of the mailbox. If set, the mailbox will be used
- as a producer (i.e. used to send data). If cleared, the mailbox is the
- consumer of data sent by a producer.
-
-- bits 23.. 0:
- The index of the shared mailbox to use. The number of available mailboxes
- may vary by instance of the HSP block and SoC generation.
-
-The following file contains definitions that can be used to construct mailbox
-specifiers:
-
- <dt-bindings/mailbox/tegra186-hsp.h>
-
-Example:
-
-hsp_top0: hsp@3c00000 {
- compatible = "nvidia,tegra186-hsp";
- reg = <0x0 0x03c00000 0x0 0xa0000>;
- interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "doorbell";
- #mbox-cells = <2>;
-};
-
-client {
- ...
- mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_DB TEGRA_HSP_DB_MASTER_XXX>;
-};
diff --git a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml
new file mode 100644
index 000000000000..f833b845de0d
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.yaml
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/nvidia,tegra186-hsp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra Hardware Synchronization Primitives (HSP)
+
+maintainers:
+ - Thierry Reding <thierry.reding@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+
+description: |
+ The HSP modules are used for the processors to share resources and
+ communicate together. It provides a set of hardware synchronization
+ primitives for interprocessor communication. So the interprocessor
+ communication (IPC) protocols can use hardware synchronization
+ primitives, when operating between two processors not in an SMP
+ relationship.
+
+ The features that HSP supported are shared mailboxes, shared
+ semaphores, arbitrated semaphores and doorbells.
+
+ The mbox specifier of the "mboxes" property in the client node should
+ contain two cells. The first cell determines the HSP type and the
+ second cell is used to identify the mailbox that the client is going
+ to use.
+
+ For shared mailboxes, the first cell composed of two fields:
+ - bits 15..8:
+ A bit mask of flags that further specifies the type of shared
+ mailbox to be used (based on the data size). If no flag is
+ specified then, 32-bit shared mailbox is used.
+ - bits 7..0:
+ Defines the type of the mailbox to be used. This field should be
+ TEGRA_HSP_MBOX_TYPE_SM for shared mailboxes.
+
+ For doorbells, the second cell specifies the index of the doorbell to
+ use.
+
+ For shared mailboxes, the second cell is composed of two fields:
+ - bits 31..24:
+ A bit mask of flags that further specify how the shared mailbox
+ will be used. Valid flags are:
+ - bit 31:
+ Defines the direction of the mailbox. If set, the mailbox
+ will be used as a producer (i.e. used to send data). If
+ cleared, the mailbox is the consumer of data sent by a
+ producer.
+
+ - bits 23..0:
+ The index of the shared mailbox to use. The number of available
+ mailboxes may vary by instance of the HSP block and SoC
+ generation.
+
+ The following file contains definitions that can be used to
+ construct mailbox specifiers:
+
+ <dt-bindings/mailbox/tegra186-hsp.h>
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - nvidia,tegra186-hsp
+ - nvidia,tegra194-hsp
+ - nvidia,tegra264-hsp
+ - items:
+ - const: nvidia,tegra234-hsp
+ - const: nvidia,tegra194-hsp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 17
+
+ interrupt-names:
+ oneOf:
+ # shared interrupts are optional
+ - items:
+ - const: doorbell
+
+ - items:
+ - const: doorbell
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+ - pattern: "^shared([0-9]|1[0-5])$"
+
+ - items:
+ - const: doorbell
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+
+ - items:
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+ - pattern: "^shared[0-7]$"
+
+ "#mbox-cells":
+ const: 2
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/mailbox/tegra186-hsp.h>
+
+ mailbox@3c00000 {
+ compatible = "nvidia,tegra186-hsp";
+ reg = <0x03c00000 0xa0000>;
+ interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "doorbell";
+ #mbox-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml
index 8878ec00820e..f40dc9048327 100644
--- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml
+++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml
@@ -1,35 +1,70 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/mailbox/qcom,apcs-kpss-global.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/mailbox/qcom,apcs-kpss-global.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm APCS global block bindings
+title: Qualcomm APCS global block
description:
This binding describes the APCS "global" block found in various Qualcomm
platforms.
maintainers:
- - Sivaprakash Murugesan <sivaprak@codeaurora.org>
+ - Jassi Brar <jassisinghbrar@gmail.com>
properties:
compatible:
- enum:
- - qcom,ipq6018-apcs-apps-global
- - qcom,ipq8074-apcs-apps-global
- - qcom,msm8916-apcs-kpss-global
- - qcom,msm8939-apcs-kpss-global
- - qcom,msm8994-apcs-kpss-global
- - qcom,msm8996-apcs-hmss-global
- - qcom,msm8998-apcs-hmss-global
- - qcom,qcs404-apcs-apps-global
- - qcom,sc7180-apss-shared
- - qcom,sc8180x-apss-shared
- - qcom,sdm660-apcs-hmss-global
- - qcom,sdm845-apss-shared
- - qcom,sm6125-apcs-hmss-global
- - qcom,sm8150-apss-shared
+ oneOf:
+ - items:
+ - enum:
+ - qcom,ipq5018-apcs-apps-global
+ - qcom,ipq5332-apcs-apps-global
+ - qcom,ipq5424-apcs-apps-global
+ - qcom,ipq8074-apcs-apps-global
+ - qcom,ipq9574-apcs-apps-global
+ - const: qcom,ipq6018-apcs-apps-global
+ - items:
+ - enum:
+ - qcom,msm8226-apcs-kpss-global
+ - qcom,qcs404-apcs-apps-global
+ - const: qcom,msm8916-apcs-kpss-global
+ - const: syscon
+ - items:
+ - enum:
+ - qcom,msm8974-apcs-kpss-global
+ - qcom,msm8976-apcs-kpss-global
+ - const: qcom,msm8994-apcs-kpss-global
+ - const: syscon
+ - items:
+ - enum:
+ - qcom,msm8998-apcs-hmss-global
+ - qcom,sdm660-apcs-hmss-global
+ - qcom,sm4250-apcs-hmss-global
+ - qcom,sm6115-apcs-hmss-global
+ - qcom,sm6125-apcs-hmss-global
+ - const: qcom,msm8994-apcs-kpss-global
+ - items:
+ - enum:
+ - qcom,qcs615-apss-shared
+ - qcom,sc7180-apss-shared
+ - qcom,sc8180x-apss-shared
+ - qcom,sm7150-apss-shared
+ - qcom,sm8150-apss-shared
+ - const: qcom,sdm845-apss-shared
+ - items:
+ - enum:
+ - qcom,msm8916-apcs-kpss-global
+ - qcom,msm8939-apcs-kpss-global
+ - qcom,msm8953-apcs-kpss-global
+ - qcom,msm8994-apcs-kpss-global
+ - qcom,sdx55-apcs-gcc
+ - const: syscon
+ - enum:
+ - qcom,ipq6018-apcs-apps-global
+ - qcom,msm8996-apcs-hmss-global
+ - qcom,qcm2290-apcs-hmss-global
+ - qcom,sdm845-apss-shared
reg:
maxItems: 1
@@ -37,23 +72,35 @@ properties:
clocks:
description: phandles to the parent clocks of the clock driver
minItems: 2
- items:
- - description: primary pll parent of the clock driver
- - description: auxiliary parent
- - description: reference clock
+ maxItems: 3
+ deprecated: true
'#mbox-cells':
const: 1
'#clock-cells':
- const: 0
+ enum: [0, 1]
clock-names:
minItems: 2
- items:
- - const: pll
- - const: aux
- - const: ref
+ maxItems: 3
+ deprecated: true
+
+ clock-controller:
+ type: object
+ additionalProperties: false
+ properties:
+ clocks:
+ description: phandles to the parent clocks of the clock driver
+ minItems: 2
+ maxItems: 3
+
+ '#clock-cells':
+ enum: [0, 1]
+
+ clock-names:
+ minItems: 2
+ maxItems: 3
required:
- compatible
@@ -62,62 +109,180 @@ required:
additionalProperties: false
+# Clocks should be specified either on the parent node or on the child node
+oneOf:
+ - required:
+ - clock-controller
+ properties:
+ clocks: false
+ clock-names: false
+ '#clock-cells': false
+ - properties:
+ clock-controller: false
+
+$defs:
+ msm8916-apcs-clock-controller:
+ properties:
+ clocks:
+ items:
+ - description: primary pll parent of the clock driver
+ - description: auxiliary parent
+ clock-names:
+ items:
+ - const: pll
+ - const: aux
+ '#clock-cells':
+ const: 0
+
+ msm8939-apcs-clock-controller:
+ properties:
+ clocks:
+ items:
+ - description: primary pll parent of the clock driver
+ - description: auxiliary parent
+ - description: reference clock
+ clock-names:
+ items:
+ - const: pll
+ - const: aux
+ - const: ref
+ '#clock-cells':
+ const: 0
+
+ sdx55-apcs-clock-controller:
+ properties:
+ clocks:
+ items:
+ - description: reference clock
+ - description: primary pll parent of the clock driver
+ - description: auxiliary parent
+ clock-names:
+ items:
+ - const: ref
+ - const: pll
+ - const: aux
+ '#clock-cells':
+ const: 0
+
+ ipq6018-apcs-clock-controller:
+ properties:
+ clocks:
+ items:
+ - description: primary pll parent of the clock driver
+ - description: XO clock
+ - description: GCC GPLL0 clock source
+ clock-names:
+ items:
+ - const: pll
+ - const: xo
+ - const: gpll0
+ '#clock-cells':
+ const: 1
+
allOf:
- if:
properties:
compatible:
- enum:
- - qcom,ipq6018-apcs-apps-global
- - qcom,ipq8074-apcs-apps-global
- - qcom,msm8916-apcs-kpss-global
- - qcom,msm8994-apcs-kpss-global
- - qcom,msm8996-apcs-hmss-global
- - qcom,msm8998-apcs-hmss-global
- - qcom,qcs404-apcs-apps-global
- - qcom,sc7180-apss-shared
- - qcom,sdm660-apcs-hmss-global
- - qcom,sdm845-apss-shared
- - qcom,sm6125-apcs-hmss-global
- - qcom,sm8150-apss-shared
+ contains:
+ enum:
+ - qcom,msm8916-apcs-kpss-global
then:
+ $ref: '#/$defs/msm8916-apcs-clock-controller'
properties:
- clocks:
- maxItems: 2
+ clock-controller:
+ $ref: '#/$defs/msm8916-apcs-clock-controller'
+
- if:
properties:
compatible:
- enum:
- - qcom,sdx55-apcs-gcc
+ contains:
+ enum:
+ - qcom,msm8939-apcs-kpss-global
then:
+ $ref: '#/$defs/msm8939-apcs-clock-controller'
properties:
- clocks:
- maxItems: 3
+ clock-controller:
+ $ref: '#/$defs/msm8939-apcs-clock-controller'
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,sdx55-apcs-gcc
+ then:
+ $ref: '#/$defs/sdx55-apcs-clock-controller'
+ properties:
+ clock-controller:
+ $ref: '#/$defs/sdx55-apcs-clock-controller'
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,ipq6018-apcs-apps-global
+ then:
+ $ref: '#/$defs/ipq6018-apcs-clock-controller'
+ properties:
+ clock-controller:
+ $ref: '#/$defs/ipq6018-apcs-clock-controller'
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - qcom,msm8953-apcs-kpss-global
+ - qcom,msm8994-apcs-kpss-global
+ - qcom,msm8996-apcs-hmss-global
+ - qcom,qcm2290-apcs-hmss-global
+ - qcom,sdm845-apss-shared
+ then:
+ properties:
+ clocks: false
+ clock-names: false
+ clock-controller: false
+ '#clock-cells':
+ const: 0
+
examples:
# Example apcs with msm8996
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
- apcs_glb: mailbox@9820000 {
+ mailbox@9820000 {
compatible = "qcom,msm8996-apcs-hmss-global";
reg = <0x9820000 0x1000>;
#mbox-cells = <1>;
+ #clock-cells = <0>;
};
- rpm-glink {
- compatible = "qcom,glink-rpm";
- interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>;
- qcom,rpm-msg-ram = <&rpm_msg_ram>;
- mboxes = <&apcs_glb 0>;
- mbox-names = "rpm_hlos";
+ # Example apcs with qcs404
+ - |
+ #define GCC_APSS_AHB_CLK_SRC 1
+ #define GCC_GPLL0_AO_OUT_MAIN 123
+ mailbox@b011000 {
+ compatible = "qcom,qcs404-apcs-apps-global",
+ "qcom,msm8916-apcs-kpss-global", "syscon";
+ reg = <0x0b011000 0x1000>;
+ #mbox-cells = <1>;
+
+ apcs_clk: clock-controller {
+ clocks = <&apcs_hfpll>, <&gcc GCC_GPLL0_AO_OUT_MAIN>;
+ clock-names = "pll", "aux";
+ #clock-cells = <0>;
+ };
};
- # Example apcs with qcs404
+ # Example apcs with qcs404 (deprecated: use clock-controller subnode)
- |
#define GCC_APSS_AHB_CLK_SRC 1
#define GCC_GPLL0_AO_OUT_MAIN 123
apcs: mailbox@b011000 {
- compatible = "qcom,qcs404-apcs-apps-global";
+ compatible = "qcom,qcs404-apcs-apps-global",
+ "qcom,msm8916-apcs-kpss-global", "syscon";
reg = <0x0b011000 0x1000>;
#mbox-cells = <1>;
clocks = <&apcs_hfpll>, <&gcc GCC_GPLL0_AO_OUT_MAIN>;
diff --git a/Documentation/devicetree/bindings/mailbox/qcom,cpucp-mbox.yaml b/Documentation/devicetree/bindings/mailbox/qcom,cpucp-mbox.yaml
new file mode 100644
index 000000000000..9122c3d2dc30
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/qcom,cpucp-mbox.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/qcom,cpucp-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm Technologies, Inc. CPUCP Mailbox Controller
+
+maintainers:
+ - Sibi Sankar <quic_sibis@quicinc.com>
+
+description:
+ The CPUSS Control Processor (CPUCP) mailbox controller enables communication
+ between AP and CPUCP by acting as a doorbell between them.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - qcom,glymur-cpucp-mbox
+ - const: qcom,x1e80100-cpucp-mbox
+ - enum:
+ - qcom,x1e80100-cpucp-mbox
+
+ reg:
+ items:
+ - description: CPUCP rx register region
+ - description: CPUCP tx register region
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox@17430000 {
+ compatible = "qcom,x1e80100-cpucp-mbox";
+ reg = <0x17430000 0x10000>, <0x18830000 0x10000>;
+ interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml
index b222f993b232..e5c423130db6 100644
--- a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml
+++ b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml
@@ -24,9 +24,24 @@ properties:
compatible:
items:
- enum:
+ - qcom,milos-ipcc
+ - qcom,qcs8300-ipcc
+ - qcom,qdu1000-ipcc
+ - qcom,sa8255p-ipcc
+ - qcom,sa8775p-ipcc
+ - qcom,sar2130p-ipcc
+ - qcom,sc7280-ipcc
+ - qcom,sc8280xp-ipcc
+ - qcom,sdx75-ipcc
+ - qcom,sm6350-ipcc
+ - qcom,sm6375-ipcc
- qcom,sm8250-ipcc
- qcom,sm8350-ipcc
- - qcom,sc7280-ipcc
+ - qcom,sm8450-ipcc
+ - qcom,sm8550-ipcc
+ - qcom,sm8650-ipcc
+ - qcom,sm8750-ipcc
+ - qcom,x1e80100-ipcc
- const: qcom,ipcc
reg:
@@ -60,23 +75,14 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/mailbox/qcom-ipcc.h>
-
- mailbox@408000 {
- compatible = "qcom,sm8250-ipcc", "qcom,ipcc";
- reg = <0x408000 0x1000>;
- interrupts = <GIC_SPI 229 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-controller;
- #interrupt-cells = <3>;
- #mbox-cells = <2>;
- };
-
- smp2p-modem {
- compatible = "qcom,smp2p";
- interrupts-extended = <&ipcc_mproc IPCC_CLIENT_MPSS
- IPCC_MPROC_SIGNAL_SMP2P IRQ_TYPE_EDGE_RISING>;
- mboxes = <&ipcc_mproc IPCC_CLIENT_MPSS IPCC_MPROC_SIGNAL_SMP2P>;
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/mailbox/qcom-ipcc.h>
- /* Other SMP2P fields */
- };
+ mailbox@408000 {
+ compatible = "qcom,sm8250-ipcc", "qcom,ipcc";
+ reg = <0x408000 0x1000>;
+ interrupts = <GIC_SPI 229 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-controller;
+ #interrupt-cells = <3>;
+ #mbox-cells = <2>;
+ };
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/mailbox/rockchip,rk3368-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/rockchip,rk3368-mailbox.yaml
new file mode 100644
index 000000000000..107bc96a8f3d
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/rockchip,rk3368-mailbox.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/rockchip,rk3368-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rockchip RK3368 Mailbox Controller
+
+maintainers:
+ - Heiko Stuebner <heiko@sntech.de>
+
+description:
+ The Rockchip mailbox is used by the Rockchip CPU cores to communicate
+ requests to MCU processor.
+
+properties:
+ compatible:
+ const: rockchip,rk3368-mailbox
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: pclk_mailbox
+
+ interrupts:
+ description: One interrupt for each channel
+ maxItems: 4
+
+ '#mbox-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ mailbox@ff6b0000 {
+ compatible = "rockchip,rk3368-mailbox";
+ reg = <0xff6b0000 0x1000>;
+ interrupts = <GIC_SPI 146 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 149 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/rockchip-mailbox.txt b/Documentation/devicetree/bindings/mailbox/rockchip-mailbox.txt
deleted file mode 100644
index b6bb84acf5be..000000000000
--- a/Documentation/devicetree/bindings/mailbox/rockchip-mailbox.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-Rockchip mailbox
-
-The Rockchip mailbox is used by the Rockchip CPU cores to communicate
-requests to MCU processor.
-
-Refer to ./mailbox.txt for generic information about mailbox device-tree
-bindings.
-
-Required properties:
-
- - compatible: should be one of the following.
- - "rockchip,rk3368-mbox" for rk3368
- - reg: physical base address of the controller and length of memory mapped
- region.
- - interrupts: The interrupt number to the cpu. The interrupt specifier format
- depends on the interrupt controller.
- - #mbox-cells: Common mailbox binding property to identify the number
- of cells required for the mailbox specifier. Should be 1
-
-Example:
---------
-
-/* RK3368 */
-mbox: mbox@ff6b0000 {
- compatible = "rockchip,rk3368-mailbox";
- reg = <0x0 0xff6b0000 0x0 0x1000>,
- interrupts = <GIC_SPI 146 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 149 IRQ_TYPE_LEVEL_HIGH>;
- #mbox-cells = <1>;
-};
diff --git a/Documentation/devicetree/bindings/mailbox/sophgo,cv1800b-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/sophgo,cv1800b-mailbox.yaml
new file mode 100644
index 000000000000..24e126bd3a20
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/sophgo,cv1800b-mailbox.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/sophgo,cv1800b-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sophgo CV1800/SG2000 mailbox controller
+
+maintainers:
+ - Yuntao Dai <d1581209858@live.com>
+ - Junhui Liu <junhui.liu@pigmoral.tech>
+
+description:
+ Mailboxes integrated in Sophgo CV1800/SG2000 SoCs have 8 channels, each
+ shipping an 8-byte FIFO. Any processor can write to an arbitrary channel
+ and raise interrupts to receivers. Sending messages to itself is also
+ supported.
+
+properties:
+ compatible:
+ const: sophgo,cv1800b-mailbox
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 2
+ description: |
+ <&phandle channel target>
+ phandle : Label name of mailbox controller
+ channel : 0-7, Channel index
+ target : 0-3, Target processor ID
+
+ Sophgo CV1800/SG2000 SoCs include the following processors, numbered as:
+ <0> Cortex-A53 (Only available on CV181X/SG200X)
+ <1> C906B
+ <2> C906L
+ <3> 8051
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ mailbox@1900000 {
+ compatible = "sophgo,cv1800b-mailbox";
+ reg = <0x01900000 0x1000>;
+ interrupts = <101 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml
index 80feba82cbd6..b526f9c0c272 100644
--- a/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml
+++ b/Documentation/devicetree/bindings/mailbox/sprd-mailbox.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/mailbox/sprd-mailbox.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/mailbox/sprd-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Spreadtrum mailbox controller bindings
+title: Spreadtrum mailbox controller
maintainers:
- Orson Zhai <orsonzhai@gmail.com>
diff --git a/Documentation/devicetree/bindings/mailbox/st,sti-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/st,sti-mailbox.yaml
new file mode 100644
index 000000000000..a023c28dff49
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/st,sti-mailbox.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/st,sti-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics Mailbox Driver for STi platform
+
+description:
+ Each ST Mailbox IP currently consists of 4 instances of 32 channels.
+ Messages are passed between Application and Remote processors using
+ shared memory.
+
+maintainers:
+ - Patrice Chotard <patrice.chotard@foss.st.com>
+
+properties:
+ compatible:
+ const: st,stih407-mailbox
+
+ reg:
+ maxItems: 1
+
+ mbox-name:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: name of the mailbox IP
+
+ interrupts:
+ description: the irq line for the RX mailbox
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - "#mbox-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ mailbox0: mailbox@8f00000 {
+ compatible = "st,stih407-mailbox";
+ reg = <0x8f00000 0x1000>;
+ interrupts = <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>;
+ #mbox-cells = <2>;
+ mbox-name = "a9";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/mailbox/st,stm32-ipcc.yaml b/Documentation/devicetree/bindings/mailbox/st,stm32-ipcc.yaml
index b15da9ba90b2..134fd223a02b 100644
--- a/Documentation/devicetree/bindings/mailbox/st,stm32-ipcc.yaml
+++ b/Documentation/devicetree/bindings/mailbox/st,stm32-ipcc.yaml
@@ -1,10 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/mailbox/st,stm32-ipcc.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/mailbox/st,stm32-ipcc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 IPC controller bindings
+title: STMicroelectronics STM32 IPC controller
description:
The IPCC block provides a non blocking signaling mechanism to post and
@@ -13,8 +13,8 @@ description:
channels (N) can be read from a dedicated register.
maintainers:
- - Fabien Dessenne <fabien.dessenne@st.com>
- - Arnaud Pouliquen <arnaud.pouliquen@st.com>
+ - Fabien Dessenne <fabien.dessenne@foss.st.com>
+ - Arnaud Pouliquen <arnaud.pouliquen@foss.st.com>
properties:
compatible:
@@ -30,15 +30,11 @@ properties:
items:
- description: rx channel occupied
- description: tx channel free
- - description: wakeup source
- minItems: 2
interrupt-names:
items:
- const: rx
- const: tx
- - const: wakeup
- minItems: 2
wakeup-source: true
@@ -70,10 +66,9 @@ examples:
#mbox-cells = <1>;
reg = <0x4c001000 0x400>;
st,proc-id = <0>;
- interrupts-extended = <&intc GIC_SPI 100 IRQ_TYPE_NONE>,
- <&intc GIC_SPI 101 IRQ_TYPE_NONE>,
- <&aiec 62 1>;
- interrupt-names = "rx", "tx", "wakeup";
+ interrupts-extended = <&exti 61 1>,
+ <&intc GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "rx", "tx";
clocks = <&rcc_clk IPCC>;
wakeup-source;
};
diff --git a/Documentation/devicetree/bindings/mailbox/sti-mailbox.txt b/Documentation/devicetree/bindings/mailbox/sti-mailbox.txt
deleted file mode 100644
index 351f612673fc..000000000000
--- a/Documentation/devicetree/bindings/mailbox/sti-mailbox.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-ST Microelectronics Mailbox Driver
-
-Each ST Mailbox IP currently consists of 4 instances of 32 channels. Messages
-are passed between Application and Remote processors using shared memory.
-
-Controller
-----------
-
-Required properties:
-- compatible : Should be "st,stih407-mailbox"
-- reg : Offset and length of the device's register set
-- mbox-name : Name of the mailbox
-- #mbox-cells: : Must be 2
- <&phandle instance channel direction>
- phandle : Label name of controller
- instance : Instance number
- channel : Channel number
-
-Optional properties
-- interrupts : Contains the IRQ line for a Rx mailbox
-
-Example:
-
-mailbox0: mailbox@0 {
- compatible = "st,stih407-mailbox";
- reg = <0x08f00000 0x1000>;
- interrupts = <GIC_SPI 1 IRQ_TYPE_NONE>;
- #mbox-cells = <2>;
- mbox-name = "a9";
-};
-
-Client
-------
-
-Required properties:
-- compatible : Many (See the client docs)
-- reg : Shared (between Application and Remote) memory address
-- mboxes : Standard property to specify a Mailbox (See ./mailbox.txt)
- Cells must match 'mbox-cells' (See Controller docs above)
-
-Optional properties
-- mbox-names : Name given to channels seen in the 'mboxes' property.
-
-Example:
-
-mailbox_test {
- compatible = "mailbox-test";
- reg = <0x[shared_memory_address], [shared_memory_size]>;
- mboxes = <&mailbox2 0 1>, <&mailbox0 2 1>;
- mbox-names = "tx", "rx";
-};
diff --git a/Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml b/Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
new file mode 100644
index 000000000000..0971fb97896e
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/thead,th1520-mbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: T-head TH1520 Mailbox Controller
+
+description:
+ The T-head mailbox controller enables communication and coordination between
+ cores within the SoC by passing messages (e.g., data, status, and control)
+ through mailbox channels. It also allows one core to signal another processor
+ using interrupts via the Interrupt Controller Unit (ICU).
+
+maintainers:
+ - Michal Wilczynski <m.wilczynski@samsung.com>
+
+properties:
+ compatible:
+ const: thead,th1520-mbox
+
+ clocks:
+ items:
+ - description: Clock for the local mailbox
+ - description: Clock for remote ICU 0
+ - description: Clock for remote ICU 1
+ - description: Clock for remote ICU 2
+
+ clock-names:
+ items:
+ - const: clk-local
+ - const: clk-remote-icu0
+ - const: clk-remote-icu1
+ - const: clk-remote-icu2
+
+ reg:
+ items:
+ - description: Mailbox local base address
+ - description: Remote ICU 0 base address
+ - description: Remote ICU 1 base address
+ - description: Remote ICU 2 base address
+
+ reg-names:
+ items:
+ - const: local
+ - const: remote-icu0
+ - const: remote-icu1
+ - const: remote-icu2
+
+ interrupts:
+ maxItems: 1
+
+ '#mbox-cells':
+ const: 1
+ description:
+ The one and only cell describes destination CPU ID.
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - reg
+ - reg-names
+ - interrupts
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/thead,th1520-clk-ap.h>
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ mailbox@ffffc38000 {
+ compatible = "thead,th1520-mbox";
+ reg = <0xff 0xffc38000 0x0 0x4000>,
+ <0xff 0xffc44000 0x0 0x1000>,
+ <0xff 0xffc4c000 0x0 0x1000>,
+ <0xff 0xffc54000 0x0 0x1000>;
+ reg-names = "local", "remote-icu0", "remote-icu1", "remote-icu2";
+ clocks = <&clk CLK_MBOX0>, <&clk CLK_MBOX1>, <&clk CLK_MBOX2>,
+ <&clk CLK_MBOX3>;
+ clock-names = "clk-local", "clk-remote-icu0", "clk-remote-icu1",
+ "clk-remote-icu2";
+ interrupts = <28>;
+ #mbox-cells = <1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml
index e864d798168d..8504ceb64806 100644
--- a/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml
+++ b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml
@@ -1,4 +1,4 @@
-# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/mailbox/ti,omap-mailbox.yaml#
@@ -159,7 +159,7 @@ properties:
a corresponding sysc interconnect node.
This property is only needed on some legacy OMAP SoCs which have not
- yet been converted to the ti,sysc interconnect hierarachy, but is
+ yet been converted to the ti,sysc interconnect hierarchy, but is
otherwise considered obsolete.
patternProperties:
@@ -180,15 +180,6 @@ allOf:
compatible:
enum:
- ti,am654-mailbox
- then:
- required:
- - interrupt-parent
-
- - if:
- properties:
- compatible:
- enum:
- - ti,am654-mailbox
- ti,am64-mailbox
then:
properties:
@@ -251,7 +242,7 @@ examples:
- |
/* OMAP4 */
#include <dt-bindings/interrupt-controller/arm-gic.h>
- mailbox: mailbox@4a0f4000 {
+ mailbox@4a0f4000 {
compatible = "ti,omap4-mailbox";
reg = <0x4a0f4000 0x200>;
interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
@@ -269,13 +260,9 @@ examples:
};
};
- dsp {
- mboxes = <&mailbox &mbox_dsp>;
- };
-
- |
/* AM33xx */
- mailbox1: mailbox@480c8000 {
+ mailbox@480c8000 {
compatible = "ti,omap4-mailbox";
reg = <0x480c8000 0x200>;
interrupts = <77>;
@@ -292,7 +279,7 @@ examples:
- |
/* AM65x */
- mailbox0_cluster0: mailbox@31f80000 {
+ mailbox@31f80000 {
compatible = "ti,am654-mailbox";
reg = <0x31f80000 0x200>;
#mbox-cells = <1>;
diff --git a/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml b/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml
index eea822861804..c321b69f0ccd 100644
--- a/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml
+++ b/Documentation/devicetree/bindings/mailbox/ti,secure-proxy.yaml
@@ -36,7 +36,7 @@ properties:
- const: scfg
reg:
- minItems: 3
+ maxItems: 3
interrupt-names:
minItems: 1
@@ -68,12 +68,12 @@ examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
secure_proxy: mailbox@32c00000 {
- compatible = "ti,am654-secure-proxy";
- #mbox-cells = <1>;
- reg-names = "target_data", "rt", "scfg";
- reg = <0x32c00000 0x100000>,
- <0x32400000 0x100000>,
- <0x32800000 0x100000>;
- interrupt-names = "rx_011";
- interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
+ compatible = "ti,am654-secure-proxy";
+ #mbox-cells = <1>;
+ reg-names = "target_data", "rt", "scfg";
+ reg = <0x32c00000 0x100000>,
+ <0x32400000 0x100000>,
+ <0x32800000 0x100000>;
+ interrupt-names = "rx_011";
+ interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
};
diff --git a/Documentation/devicetree/bindings/mailbox/xgene-slimpro-mailbox.txt b/Documentation/devicetree/bindings/mailbox/xgene-slimpro-mailbox.txt
deleted file mode 100644
index e46451bb242f..000000000000
--- a/Documentation/devicetree/bindings/mailbox/xgene-slimpro-mailbox.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-The APM X-Gene SLIMpro mailbox is used to communicate messages between
-the ARM64 processors and the Cortex M3 (dubbed SLIMpro). It uses a simple
-interrupt based door bell mechanism and can exchange simple messages using the
-internal registers.
-
-There are total of 8 interrupts in this mailbox. Each used for an individual
-door bell (or mailbox channel).
-
-Required properties:
-- compatible: Should be as "apm,xgene-slimpro-mbox".
-
-- reg: Contains the mailbox register address range.
-
-- interrupts: 8 interrupts must be from 0 to 7, interrupt 0 define the
- the interrupt for mailbox channel 0 and interrupt 1 for
- mailbox channel 1 and so likewise for the reminder.
-
-- #mbox-cells: only one to specify the mailbox channel number.
-
-Example:
-
-Mailbox Node:
- mailbox: mailbox@10540000 {
- compatible = "apm,xgene-slimpro-mbox";
- reg = <0x0 0x10540000 0x0 0xa000>;
- #mbox-cells = <1>;
- interrupts = <0x0 0x0 0x4>,
- <0x0 0x1 0x4>,
- <0x0 0x2 0x4>,
- <0x0 0x3 0x4>,
- <0x0 0x4 0x4>,
- <0x0 0x5 0x4>,
- <0x0 0x6 0x4>,
- <0x0 0x7 0x4>,
- };
diff --git a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt
deleted file mode 100644
index ad76edccf881..000000000000
--- a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt
+++ /dev/null
@@ -1,127 +0,0 @@
-Xilinx IPI Mailbox Controller
-========================================
-
-The Xilinx IPI(Inter Processor Interrupt) mailbox controller is to manage
-messaging between two Xilinx Zynq UltraScale+ MPSoC IPI agents. Each IPI
-agent owns registers used for notification and buffers for message.
-
- +-------------------------------------+
- | Xilinx ZynqMP IPI Controller |
- +-------------------------------------+
- +--------------------------------------------------+
-ATF | |
- | |
- | |
- +--------------------------+ |
- | |
- | |
- +--------------------------------------------------+
- +------------------------------------------+
- | +----------------+ +----------------+ |
-Hardware | | IPI Agent | | IPI Buffers | |
- | | Registers | | | |
- | | | | | |
- | +----------------+ +----------------+ |
- | |
- | Xilinx IPI Agent Block |
- +------------------------------------------+
-
-
-Controller Device Node:
-===========================
-Required properties:
---------------------
-IPI agent node:
-- compatible: Shall be: "xlnx,zynqmp-ipi-mailbox"
-- interrupt-parent: Phandle for the interrupt controller
-- interrupts: Interrupt information corresponding to the
- interrupt-names property.
-- xlnx,ipi-id: local Xilinx IPI agent ID
-- #address-cells: number of address cells of internal IPI mailbox nodes
-- #size-cells: number of size cells of internal IPI mailbox nodes
-
-Internal IPI mailbox node:
-- reg: IPI buffers address ranges
-- reg-names: Names of the reg resources. It should have:
- * local_request_region
- - IPI request msg buffer written by local and read
- by remote
- * local_response_region
- - IPI response msg buffer written by local and read
- by remote
- * remote_request_region
- - IPI request msg buffer written by remote and read
- by local
- * remote_response_region
- - IPI response msg buffer written by remote and read
- by local
-- #mbox-cells: Shall be 1. It contains:
- * tx(0) or rx(1) channel
-- xlnx,ipi-id: remote Xilinx IPI agent ID of which the mailbox is
- connected to.
-
-Optional properties:
---------------------
-- method: The method of accessing the IPI agent registers.
- Permitted values are: "smc" and "hvc". Default is
- "smc".
-
-Client Device Node:
-===========================
-Required properties:
---------------------
-- mboxes: Standard property to specify a mailbox
- (See ./mailbox.txt)
-- mbox-names: List of identifier strings for each mailbox
- channel.
-
-Example:
-===========================
- zynqmp_ipi {
- compatible = "xlnx,zynqmp-ipi-mailbox";
- interrupt-parent = <&gic>;
- interrupts = <0 29 4>;
- xlnx,ipi-id = <0>;
- #address-cells = <1>;
- #size-cells = <1>;
- ranges;
-
- /* APU<->RPU0 IPI mailbox controller */
- ipi_mailbox_rpu0: mailbox@ff990400 {
- reg = <0xff990400 0x20>,
- <0xff990420 0x20>,
- <0xff990080 0x20>,
- <0xff9900a0 0x20>;
- reg-names = "local_request_region",
- "local_response_region",
- "remote_request_region",
- "remote_response_region";
- #mbox-cells = <1>;
- xlnx,ipi-id = <1>;
- };
- /* APU<->RPU1 IPI mailbox controller */
- ipi_mailbox_rpu1: mailbox@ff990440 {
- reg = <0xff990440 0x20>,
- <0xff990460 0x20>,
- <0xff990280 0x20>,
- <0xff9902a0 0x20>;
- reg-names = "local_request_region",
- "local_response_region",
- "remote_request_region",
- "remote_response_region";
- #mbox-cells = <1>;
- xlnx,ipi-id = <2>;
- };
- };
- rpu0 {
- ...
- mboxes = <&ipi_mailbox_rpu0 0>,
- <&ipi_mailbox_rpu0 1>;
- mbox-names = "tx", "rx";
- };
- rpu1 {
- ...
- mboxes = <&ipi_mailbox_rpu1 0>,
- <&ipi_mailbox_rpu1 1>;
- mbox-names = "tx", "rx";
- };
diff --git a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml
new file mode 100644
index 000000000000..04d6473d666f
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml
@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/xlnx,zynqmp-ipi-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Xilinx IPI(Inter Processor Interrupt) mailbox controller
+
+description: |
+ The Xilinx IPI(Inter Processor Interrupt) mailbox controller is to manage
+ messaging between two Xilinx Zynq UltraScale+ MPSoC IPI agents. Each IPI
+ agent owns registers used for notification and buffers for message.
+
+ +-------------------------------------+
+ | Xilinx ZynqMP IPI Controller |
+ +-------------------------------------+
+ +--------------------------------------------------+
+ TF-A | |
+ | |
+ | |
+ +--------------------------+ |
+ | |
+ | |
+ +--------------------------------------------------+
+ +------------------------------------------+
+ | +----------------+ +----------------+ |
+ Hardware | | IPI Agent | | IPI Buffers | |
+ | | Registers | | | |
+ | | | | | |
+ | +----------------+ +----------------+ |
+ | |
+ | Xilinx IPI Agent Block |
+ +------------------------------------------+
+
+maintainers:
+ - Shubhrajyoti Datta <shubhrajyoti.datta@amd.com>
+
+properties:
+ compatible:
+ enum:
+ - xlnx,zynqmp-ipi-mailbox
+ - xlnx,versal-ipi-mailbox
+
+ method:
+ description: |
+ The method of calling the PM-API firmware layer.
+ Permitted values are.
+ - "smc" : SMC #0, following the SMCCC
+ - "hvc" : HVC #0, following the SMCCC
+
+ $ref: /schemas/types.yaml#/definitions/string
+ enum:
+ - smc
+ - hvc
+ default: smc
+
+ '#address-cells':
+ const: 2
+
+ '#size-cells':
+ const: 2
+
+ reg:
+ maxItems: 2
+
+ reg-names:
+ maxItems: 2
+
+ xlnx,ipi-id:
+ description: |
+ Remote Xilinx IPI agent ID of which the mailbox is connected to.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ interrupts:
+ maxItems: 1
+
+ ranges: true
+
+patternProperties:
+ '^mailbox@[0-9a-f]+$':
+ description: Internal ipi mailbox node
+ type: object # DT nodes are json objects
+ additionalProperties: false
+ properties:
+
+ compatible:
+ enum:
+ - xlnx,zynqmp-ipi-dest-mailbox
+ - xlnx,versal-ipi-dest-mailbox
+
+ reg:
+ minItems: 1
+ maxItems: 4
+
+ reg-names:
+ minItems: 1
+ maxItems: 4
+
+ xlnx,ipi-id:
+ description:
+ Remote Xilinx IPI agent ID of which the mailbox is connected to.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ '#mbox-cells':
+ const: 1
+ description:
+ It contains tx(0) or rx(1) channel IPI id number.
+
+ allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - xlnx,zynqmp-ipi-dest-mailbox
+ then:
+ properties:
+ reg:
+ maxItems: 4
+
+ reg-names:
+ items:
+ - const: local_request_region
+ - const: local_response_region
+ - const: remote_request_region
+ - const: remote_response_region
+ else:
+ properties:
+ reg:
+ minItems: 1
+ items:
+ - description: Remote IPI agent control register region
+ - description: Remote IPI agent optional message buffers
+
+ reg-names:
+ minItems: 1
+ items:
+ - const: ctrl
+ - const: msg
+
+ required:
+ - compatible
+ - reg
+ - reg-names
+ - '#mbox-cells'
+ - xlnx,ipi-id
+
+required:
+ - compatible
+ - interrupts
+ - '#address-cells'
+ - '#size-cells'
+ - xlnx,ipi-id
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - xlnx,zynqmp-ipi-mailbox
+ then:
+ properties:
+ reg: false
+ reg-names: false
+
+ else:
+ properties:
+ reg:
+ items:
+ - description: Host IPI agent control register region
+ - description: Host IPI agent optional message buffers
+
+ reg-names:
+ items:
+ - const: ctrl
+ - const: msg
+
+ required:
+ - reg
+ - reg-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include<dt-bindings/interrupt-controller/arm-gic.h>
+
+ amba {
+ #address-cells = <0x2>;
+ #size-cells = <0x2>;
+ zynqmp-mailbox {
+ compatible = "xlnx,zynqmp-ipi-mailbox";
+ interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>;
+ xlnx,ipi-id = <0>;
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges;
+
+ mailbox: mailbox@ff9905c0 {
+ compatible = "xlnx,zynqmp-ipi-dest-mailbox";
+ reg = <0x0 0xff9905c0 0x0 0x20>,
+ <0x0 0xff9905e0 0x0 0x20>,
+ <0x0 0xff990e80 0x0 0x20>,
+ <0x0 0xff990ea0 0x0 0x20>;
+ reg-names = "local_request_region",
+ "local_response_region",
+ "remote_request_region",
+ "remote_response_region";
+ #mbox-cells = <1>;
+ xlnx,ipi-id = <4>;
+ };
+ };
+ };
+
+ - |
+ #include<dt-bindings/interrupt-controller/arm-gic.h>
+
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ mailbox@ff300000 {
+ compatible = "xlnx,versal-ipi-mailbox";
+ interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>;
+ #address-cells = <2>;
+ #size-cells = <2>;
+ reg = <0x0 0xff300000 0x0 0x1000>,
+ <0x0 0xff990000 0x0 0x1ff>;
+ reg-names = "ctrl", "msg";
+ xlnx,ipi-id = <0>;
+ ranges;
+
+ /* buffered IPI */
+ mailbox@ff340000 {
+ compatible = "xlnx,versal-ipi-dest-mailbox";
+ reg = <0x0 0xff340000 0x0 0x1000>,
+ <0x0 0xff990400 0x0 0x1ff>;
+ reg-names = "ctrl", "msg";
+ #mbox-cells = <1>;
+ xlnx,ipi-id = <4>;
+ };
+
+ /* bufferless IPI */
+ mailbox@ff370000 {
+ compatible = "xlnx,versal-ipi-dest-mailbox";
+ reg = <0x0 0xff370000 0x0 0x1000>;
+ reg-names = "ctrl";
+ #mbox-cells = <1>;
+ xlnx,ipi-id = <7>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/allegro,al5e.yaml b/Documentation/devicetree/bindings/media/allegro,al5e.yaml
index 135bea94b587..2899d26d690e 100644
--- a/Documentation/devicetree/bindings/media/allegro,al5e.yaml
+++ b/Documentation/devicetree/bindings/media/allegro,al5e.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/allegro,al5e.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allegro DVT Video IP Codecs Device Tree Bindings
+title: Allegro DVT Video IP Codecs
maintainers:
- Michael Tretter <m.tretter@pengutronix.de>
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml
index 6ced94064215..617264ce477d 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-csi.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/allwinner,sun4i-a10-csi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A10 CMOS Sensor Interface (CSI) Device Tree Bindings
+title: Allwinner A10 CMOS Sensor Interface (CSI)
maintainers:
- Chen-Yu Tsai <wens@csie.org>
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml
index 6d8395d6bca0..42dfe22ad5f1 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml
@@ -4,14 +4,14 @@
$id: http://devicetree.org/schemas/media/allwinner,sun4i-a10-ir.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A10 Infrared Controller Device Tree Bindings
+title: Allwinner A10 Infrared Controller
maintainers:
- Chen-Yu Tsai <wens@csie.org>
- Maxime Ripard <mripard@kernel.org>
allOf:
- - $ref: "rc.yaml#"
+ - $ref: rc.yaml#
properties:
compatible:
@@ -21,6 +21,7 @@ properties:
- const: allwinner,sun6i-a31-ir
- items:
- enum:
+ - allwinner,suniv-f1c100s-ir
- allwinner,sun8i-a83t-ir
- allwinner,sun8i-r40-ir
- allwinner,sun50i-a64-ir
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml
index c34303b87a5b..541325f900a1 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/allwinner,sun4i-a10-video-engine.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A10 Video Engine Device Tree Bindings
+title: Allwinner A10 Video Engine
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -20,6 +20,7 @@ properties:
- allwinner,sun8i-h3-video-engine
- allwinner,sun8i-v3s-video-engine
- allwinner,sun8i-r40-video-engine
+ - allwinner,sun20i-d1-video-engine
- allwinner,sun50i-a64-video-engine
- allwinner,sun50i-h5-video-engine
- allwinner,sun50i-h6-video-engine
@@ -47,6 +48,10 @@ properties:
allwinner,sram:
$ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to SRAM
+ - description: register value for device
description: Phandle to the device SRAM
iommus:
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml b/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml
new file mode 100644
index 000000000000..8ba5177ac631
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/allwinner,sun50i-h6-vpu-g2.yaml
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/allwinner,sun50i-h6-vpu-g2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Hantro G2 VPU codec implemented on Allwinner H6 SoC
+
+maintainers:
+ - Jernej Skrabec <jernej.skrabec@gmail.com>
+
+description:
+ Hantro G2 video decode accelerator present on Allwinner H6 SoC.
+
+properties:
+ compatible:
+ const: allwinner,sun50i-h6-vpu-g2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+
+ resets:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+ - iommus
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/sun50i-h6-ccu.h>
+ #include <dt-bindings/reset/sun50i-h6-ccu.h>
+
+ video-codec-g2@1c00000 {
+ compatible = "allwinner,sun50i-h6-vpu-g2";
+ reg = <0x01c00000 0x1000>;
+ interrupts = <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu CLK_BUS_VP9>, <&ccu CLK_VP9>;
+ clock-names = "bus", "mod";
+ resets = <&ccu RST_BUS_VP9>;
+ iommus = <&iommu 5>;
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml
index 8b568072a069..1aa5775ba2bc 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-csi.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/allwinner,sun6i-a31-csi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A31 CMOS Sensor Interface (CSI) Device Tree Bindings
+title: Allwinner A31 CMOS Sensor Interface (CSI)
maintainers:
- Chen-Yu Tsai <wens@csie.org>
@@ -42,6 +42,7 @@ properties:
port:
$ref: /schemas/graph.yaml#/$defs/port-base
+ description: Parallel input port, connect to a parallel sensor
properties:
endpoint:
@@ -59,7 +60,28 @@ properties:
required:
- bus-width
- additionalProperties: false
+ unevaluatedProperties: false
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: "#/properties/port"
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: MIPI CSI-2 bridge input port
+
+ port@2:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Internal output port to the ISP
+
+ anyOf:
+ - required:
+ - port@0
+ - required:
+ - port@1
required:
- compatible
@@ -69,6 +91,12 @@ required:
- clock-names
- resets
+oneOf:
+ - required:
+ - ports
+ - required:
+ - port
+
additionalProperties: false
examples:
@@ -82,26 +110,32 @@ examples:
reg = <0x01cb4000 0x1000>;
interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>;
clocks = <&ccu CLK_BUS_CSI>,
- <&ccu CLK_CSI1_SCLK>,
+ <&ccu CLK_CSI_SCLK>,
<&ccu CLK_DRAM_CSI>;
clock-names = "bus",
"mod",
"ram";
resets = <&ccu RST_BUS_CSI>;
- port {
- /* Parallel bus endpoint */
- csi1_ep: endpoint {
- remote-endpoint = <&adv7611_ep>;
- bus-width = <16>;
-
- /*
- * If hsync-active/vsync-active are missing,
- * embedded BT.656 sync is used.
- */
- hsync-active = <0>; /* Active low */
- vsync-active = <0>; /* Active low */
- pclk-sample = <1>; /* Rising */
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ /* Parallel bus endpoint */
+ csi1_ep: endpoint {
+ remote-endpoint = <&adv7611_ep>;
+ bus-width = <16>;
+
+ /*
+ * If hsync-active/vsync-active are missing,
+ * embedded BT.656 sync is used.
+ */
+ hsync-active = <0>; /* Active low */
+ vsync-active = <0>; /* Active low */
+ pclk-sample = <1>; /* Rising */
+ };
};
};
};
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml
new file mode 100644
index 000000000000..3ea4a4290f23
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-isp.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/allwinner,sun6i-a31-isp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A31 Image Signal Processor Driver (ISP)
+
+maintainers:
+ - Paul Kocialkowski <paul.kocialkowski@bootlin.com>
+
+properties:
+ compatible:
+ enum:
+ - allwinner,sun6i-a31-isp
+ - allwinner,sun8i-v3s-isp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+ - description: DRAM Clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+ - const: ram
+
+ resets:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: CSI0 input port
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: CSI1 input port
+
+ if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - allwinner,sun8i-v3s-isp
+ then:
+ required:
+ - port@0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/sun8i-v3s-ccu.h>
+ #include <dt-bindings/reset/sun8i-v3s-ccu.h>
+
+ isp: isp@1cb8000 {
+ compatible = "allwinner,sun8i-v3s-isp";
+ reg = <0x01cb8000 0x1000>;
+ interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu CLK_BUS_CSI>,
+ <&ccu CLK_CSI_SCLK>,
+ <&ccu CLK_DRAM_CSI>;
+ clock-names = "bus", "mod", "ram";
+ resets = <&ccu RST_BUS_CSI>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ isp_in_csi0: endpoint {
+ remote-endpoint = <&csi0_out_isp>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-mipi-csi2.yaml
new file mode 100644
index 000000000000..627b28e94354
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/allwinner,sun6i-a31-mipi-csi2.yaml
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/allwinner,sun6i-a31-mipi-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A31 MIPI CSI-2
+
+maintainers:
+ - Paul Kocialkowski <paul.kocialkowski@bootlin.com>
+
+properties:
+ compatible:
+ oneOf:
+ - const: allwinner,sun6i-a31-mipi-csi2
+ - items:
+ - const: allwinner,sun8i-v3s-mipi-csi2
+ - const: allwinner,sun6i-a31-mipi-csi2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+
+ phys:
+ maxItems: 1
+ description: MIPI D-PHY
+
+ phy-names:
+ items:
+ - const: dphy
+
+ resets:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ description: Input port, connect to a MIPI CSI-2 sensor
+
+ properties:
+ reg:
+ const: 0
+
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ unevaluatedProperties: false
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output port, connect to a CSI controller
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - phys
+ - phy-names
+ - resets
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/sun8i-v3s-ccu.h>
+ #include <dt-bindings/reset/sun8i-v3s-ccu.h>
+
+ mipi_csi2: csi@1cb1000 {
+ compatible = "allwinner,sun8i-v3s-mipi-csi2",
+ "allwinner,sun6i-a31-mipi-csi2";
+ reg = <0x01cb1000 0x1000>;
+ interrupts = <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu CLK_BUS_CSI>,
+ <&ccu CLK_CSI_SCLK>;
+ clock-names = "bus", "mod";
+ resets = <&ccu RST_BUS_CSI>;
+
+ phys = <&dphy>;
+ phy-names = "dphy";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ mipi_csi2_in: port@0 {
+ reg = <0>;
+
+ mipi_csi2_in_ov5648: endpoint {
+ data-lanes = <1 2 3 4>;
+
+ remote-endpoint = <&ov5648_out_mipi_csi2>;
+ };
+ };
+
+ mipi_csi2_out: port@1 {
+ reg = <1>;
+
+ mipi_csi2_out_csi0: endpoint {
+ remote-endpoint = <&csi0_in_mipi_csi2>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-de2-rotate.yaml b/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-de2-rotate.yaml
index a258832d520c..c2f292dd01ed 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-de2-rotate.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-de2-rotate.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/allwinner,sun8i-a83t-de2-rotate.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner A83T DE2 Rotate Device Tree Bindings
+title: Allwinner A83T DE2 Rotate
maintainers:
- Jernej Skrabec <jernej.skrabec@siol.net>
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-mipi-csi2.yaml
new file mode 100644
index 000000000000..3cac68a87ad7
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/allwinner,sun8i-a83t-mipi-csi2.yaml
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/allwinner,sun8i-a83t-mipi-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A83T MIPI CSI-2
+
+maintainers:
+ - Paul Kocialkowski <paul.kocialkowski@bootlin.com>
+
+properties:
+ compatible:
+ const: allwinner,sun8i-a83t-mipi-csi2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Bus Clock
+ - description: Module Clock
+ - description: MIPI-specific Clock
+ - description: Misc CSI Clock
+
+ clock-names:
+ items:
+ - const: bus
+ - const: mod
+ - const: mipi
+ - const: misc
+
+ resets:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ description: Input port, connect to a MIPI CSI-2 sensor
+
+ properties:
+ reg:
+ const: 0
+
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ unevaluatedProperties: false
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output port, connect to a CSI controller
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/sun8i-a83t-ccu.h>
+ #include <dt-bindings/reset/sun8i-a83t-ccu.h>
+
+ mipi_csi2: csi@1cb1000 {
+ compatible = "allwinner,sun8i-a83t-mipi-csi2";
+ reg = <0x01cb1000 0x1000>;
+ interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ccu CLK_BUS_CSI>,
+ <&ccu CLK_CSI_SCLK>,
+ <&ccu CLK_MIPI_CSI>,
+ <&ccu CLK_CSI_MISC>;
+ clock-names = "bus", "mod", "mipi", "misc";
+ resets = <&ccu RST_BUS_CSI>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ mipi_csi2_in: port@0 {
+ reg = <0>;
+
+ mipi_csi2_in_ov8865: endpoint {
+ data-lanes = <1 2 3 4>;
+
+ remote-endpoint = <&ov8865_out_mipi_csi2>;
+ };
+ };
+
+ mipi_csi2_out: port@1 {
+ reg = <1>;
+
+ mipi_csi2_out_csi: endpoint {
+ remote-endpoint = <&csi_in_mipi_csi2>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml b/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml
index b80980b1908e..3ccd52164f5b 100644
--- a/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml
+++ b/Documentation/devicetree/bindings/media/allwinner,sun8i-h3-deinterlace.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/allwinner,sun8i-h3-deinterlace.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Allwinner H3 Deinterlace Device Tree Bindings
+title: Allwinner H3 Deinterlace
maintainers:
- Jernej Skrabec <jernej.skrabec@siol.net>
diff --git a/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml
index bee93bd84771..f23fa6d06ad0 100644
--- a/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml
+++ b/Documentation/devicetree/bindings/media/amlogic,axg-ge2d.yaml
@@ -2,13 +2,13 @@
# Copyright 2020 BayLibre, SAS
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/amlogic,axg-ge2d.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/amlogic,axg-ge2d.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Amlogic GE2D Acceleration Unit
maintainers:
- - Neil Armstrong <narmstrong@baylibre.com>
+ - Neil Armstrong <neil.armstrong@linaro.org>
properties:
compatible:
diff --git a/Documentation/devicetree/bindings/media/amlogic,c3-isp.yaml b/Documentation/devicetree/bindings/media/amlogic,c3-isp.yaml
new file mode 100644
index 000000000000..123bf462f098
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/amlogic,c3-isp.yaml
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/amlogic,c3-isp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic C3 Image Signal Processing Unit
+
+maintainers:
+ - Keke Li <keke.li@amlogic.com>
+
+description:
+ Amlogic ISP is the RAW image processing module
+ and supports three channels image output.
+
+properties:
+ compatible:
+ enum:
+ - amlogic,c3-isp
+
+ reg:
+ maxItems: 1
+
+ reg-names:
+ items:
+ - const: isp
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: vapb
+ - const: isp0
+
+ interrupts:
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: input port node.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - power-domains
+ - clocks
+ - clock-names
+ - interrupts
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/amlogic,c3-peripherals-clkc.h>
+ #include <dt-bindings/power/amlogic,c3-pwrc.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp: isp@ff000000 {
+ compatible = "amlogic,c3-isp";
+ reg = <0x0 0xff000000 0x0 0xf000>;
+ reg-names = "isp";
+ power-domains = <&pwrc PWRC_C3_ISP_TOP_ID>;
+ clocks = <&clkc_periphs CLKID_VAPB>,
+ <&clkc_periphs CLKID_ISP0>;
+ clock-names = "vapb", "isp0";
+ assigned-clocks = <&clkc_periphs CLKID_VAPB>,
+ <&clkc_periphs CLKID_ISP0>;
+ assigned-clock-rates = <0>, <400000000>;
+ interrupts = <GIC_SPI 145 IRQ_TYPE_EDGE_RISING>;
+
+ port {
+ c3_isp_in: endpoint {
+ remote-endpoint = <&c3_adap_out>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/amlogic,c3-mipi-adapter.yaml b/Documentation/devicetree/bindings/media/amlogic,c3-mipi-adapter.yaml
new file mode 100644
index 000000000000..ba43bc6709a0
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/amlogic,c3-mipi-adapter.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/amlogic,c3-mipi-adapter.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic C3 MIPI adapter receiver
+
+maintainers:
+ - Keke Li <keke.li@amlogic.com>
+
+description:
+ MIPI adapter is used to convert the MIPI CSI-2 data
+ into an ISP supported data format.
+
+properties:
+ compatible:
+ enum:
+ - amlogic,c3-mipi-adapter
+
+ reg:
+ maxItems: 3
+
+ reg-names:
+ items:
+ - const: top
+ - const: fd
+ - const: rd
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: vapb
+ - const: isp0
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: input port node.
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: output port node.
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - power-domains
+ - clocks
+ - clock-names
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/amlogic,c3-peripherals-clkc.h>
+ #include <dt-bindings/power/amlogic,c3-pwrc.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ adap: adap@ff010000 {
+ compatible = "amlogic,c3-mipi-adapter";
+ reg = <0x0 0xff010000 0x0 0x100>,
+ <0x0 0xff01b000 0x0 0x100>,
+ <0x0 0xff01d000 0x0 0x200>;
+ reg-names = "top", "fd", "rd";
+ power-domains = <&pwrc PWRC_C3_ISP_TOP_ID>;
+ clocks = <&clkc_periphs CLKID_VAPB>,
+ <&clkc_periphs CLKID_ISP0>;
+ clock-names = "vapb", "isp0";
+ assigned-clocks = <&clkc_periphs CLKID_VAPB>,
+ <&clkc_periphs CLKID_ISP0>;
+ assigned-clock-rates = <0>, <400000000>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ c3_adap_in: endpoint {
+ remote-endpoint = <&c3_mipi_csi_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ c3_adap_out: endpoint {
+ remote-endpoint = <&c3_isp_in>;
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/amlogic,c3-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/amlogic,c3-mipi-csi2.yaml
new file mode 100644
index 000000000000..b0129beab0c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/amlogic,c3-mipi-csi2.yaml
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/amlogic,c3-mipi-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic C3 MIPI CSI-2 receiver
+
+maintainers:
+ - Keke Li <keke.li@amlogic.com>
+
+description:
+ MIPI CSI-2 receiver contains CSI-2 RX PHY and host controller.
+ It receives the MIPI data from the image sensor and sends MIPI data
+ to MIPI adapter.
+
+properties:
+ compatible:
+ enum:
+ - amlogic,c3-mipi-csi2
+
+ reg:
+ maxItems: 3
+
+ reg-names:
+ items:
+ - const: aphy
+ - const: dphy
+ - const: host
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: vapb
+ - const: phy0
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: input port node, connected to sensor.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: output port node
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - power-domains
+ - clocks
+ - clock-names
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/amlogic,c3-peripherals-clkc.h>
+ #include <dt-bindings/power/amlogic,c3-pwrc.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ csi: csi@ff018000 {
+ compatible = "amlogic,c3-mipi-csi2";
+ reg = <0x0 0xff018000 0x0 0x400>,
+ <0x0 0xff019000 0x0 0x300>,
+ <0x0 0xff01a000 0x0 0x100>;
+ reg-names = "aphy", "dphy", "host";
+ power-domains = <&pwrc PWRC_C3_MIPI_ISP_WRAP_ID>;
+ clocks = <&clkc_periphs CLKID_VAPB>,
+ <&clkc_periphs CLKID_CSI_PHY0>;
+ clock-names = "vapb", "phy0";
+ assigned-clocks = <&clkc_periphs CLKID_VAPB>,
+ <&clkc_periphs CLKID_CSI_PHY0>;
+ assigned-clock-rates = <0>, <200000000>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ c3_mipi_csi_in: endpoint {
+ remote-endpoint = <&imx290_out>;
+ data-lanes = <1 2 3 4>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ c3_mipi_csi_out: endpoint {
+ remote-endpoint = <&c3_adap_in>;
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml b/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml
index 5044c4bb94e0..47dce75aeae6 100644
--- a/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml
+++ b/Documentation/devicetree/bindings/media/amlogic,gx-vdec.yaml
@@ -2,13 +2,13 @@
# Copyright 2019 BayLibre, SAS
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/amlogic,gx-vdec.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/amlogic,gx-vdec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Amlogic Video Decoder
maintainers:
- - Neil Armstrong <narmstrong@baylibre.com>
+ - Neil Armstrong <neil.armstrong@linaro.org>
- Maxime Jourdan <mjourdan@baylibre.com>
description: |
@@ -31,7 +31,8 @@ properties:
- items:
- enum:
- amlogic,gxbb-vdec # GXBB (S905)
- - amlogic,gxl-vdec # GXL (S905X, S905D)
+ - amlogic,gxl-vdec # GXL (S905D, S905W, S905X, S905Y)
+ - amlogic,gxlx-vdec # GXLX (S905L)
- amlogic,gxm-vdec # GXM (S912)
- const: amlogic,gx-vdec
- enum:
diff --git a/Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml b/Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml
new file mode 100644
index 000000000000..6da8a6aded23
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/amlogic,meson-ir-tx.yaml
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/amlogic,meson-ir-tx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic Meson IR transmitter
+
+maintainers:
+ - Viktor Prutyanov <viktor.prutyanov@phystech.edu>
+
+description: |
+ Some Amlogic SoCs such as A311D and T950D4 have IR transmitter
+ (also called blaster) controller onboard. It is capable of
+ sending IR signals with arbitrary carrier frequency and duty cycle.
+
+properties:
+ compatible:
+ oneOf:
+ - const: amlogic,meson-ir-tx
+ - items:
+ - const: amlogic,meson-g12a-ir-tx
+ - const: amlogic,meson-ir-tx
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: sysclk
+ - const: xtal
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/g12a-clkc.h>
+
+ ir@ff80014c {
+ compatible = "amlogic,meson-g12a-ir-tx", "amlogic,meson-ir-tx";
+ reg = <0xff80014c 0x10>;
+ interrupts = <0 198 IRQ_TYPE_EDGE_RISING>;
+ clocks = <&clkc CLKID_CLK81>, <&xtal>;
+ clock-names = "sysclk", "xtal";
+ };
diff --git a/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml b/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml
new file mode 100644
index 000000000000..0f95fe8dd9ac
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/amlogic,meson6-ir.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amlogic Meson IR remote control receiver
+
+maintainers:
+ - Neil Armstrong <neil.armstrong@linaro.org>
+
+allOf:
+ - $ref: rc.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - amlogic,meson6-ir
+ - amlogic,meson8b-ir
+ - amlogic,meson-gxbb-ir
+ - amlogic,meson-s4-ir
+ - items:
+ - const: amlogic,meson-gx-ir
+ - const: amlogic,meson-gxbb-ir
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ ir-receiver@c8100480 {
+ compatible = "amlogic,meson6-ir";
+ reg = <0xc8100480 0x20>;
+ interrupts = <GIC_SPI 15 IRQ_TYPE_EDGE_RISING>;
+ };
diff --git a/Documentation/devicetree/bindings/media/amphion,vpu.yaml b/Documentation/devicetree/bindings/media/amphion,vpu.yaml
new file mode 100644
index 000000000000..fa18013d705d
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/amphion,vpu.yaml
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/amphion,vpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Amphion VPU codec IP
+
+maintainers:
+ - Ming Qian <ming.qian@nxp.com>
+ - Shijie Qin <shijie.qin@nxp.com>
+
+description: |-
+ The Amphion MXC video encoder(Windsor) and decoder(Malone) accelerators present
+ on NXP i.MX8Q SoCs.
+
+properties:
+ $nodename:
+ pattern: "^vpu@[0-9a-f]+$"
+
+ compatible:
+ items:
+ - enum:
+ - nxp,imx8qm-vpu
+ - nxp,imx8qxp-vpu
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+ ranges: true
+
+patternProperties:
+ "^mailbox@[0-9a-f]+$":
+ description:
+ Each vpu encoder or decoder correspond a MU, which used for communication
+ between driver and firmware. Implement via mailbox on driver.
+ $ref: /schemas/mailbox/fsl,mu.yaml#
+
+ "^vpu-core@[0-9a-f]+$":
+ description:
+ Each core correspond a decoder or encoder, need to configure them
+ separately. NXP i.MX8QM SoC has one decoder and two encoder, i.MX8QXP SoC
+ has one decoder and one encoder.
+ type: object
+
+ properties:
+ compatible:
+ items:
+ - enum:
+ - nxp,imx8q-vpu-decoder
+ - nxp,imx8q-vpu-encoder
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ mbox-names:
+ items:
+ - const: tx0
+ - const: tx1
+ - const: rx
+
+ mboxes:
+ description:
+ List of phandle of 2 MU channels for tx, 1 MU channel for rx.
+ maxItems: 3
+
+ memory-region:
+ description:
+ Phandle to the reserved memory nodes to be associated with the
+ remoteproc device. The reserved memory nodes should be carveout nodes,
+ and should be defined as per the bindings in
+ Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
+ items:
+ - description: region reserved for firmware image sections.
+ - description: region used for RPC shared memory between firmware and
+ driver.
+
+ required:
+ - compatible
+ - reg
+ - power-domains
+ - mbox-names
+ - mboxes
+ - memory-region
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - power-domains
+
+additionalProperties: false
+
+examples:
+ # Device node example for i.MX8QM platform:
+ - |
+ #include <dt-bindings/firmware/imx/rsrc.h>
+
+ vpu: vpu@2c000000 {
+ compatible = "nxp,imx8qm-vpu";
+ ranges = <0x2c000000 0x2c000000 0x2000000>;
+ reg = <0x2c000000 0x1000000>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ power-domains = <&pd IMX_SC_R_VPU>;
+
+ mu_m0: mailbox@2d000000 {
+ compatible = "fsl,imx6sx-mu";
+ reg = <0x2d000000 0x20000>;
+ interrupts = <0 472 4>;
+ #mbox-cells = <2>;
+ power-domains = <&pd IMX_SC_R_VPU_MU_0>;
+ };
+
+ mu1_m0: mailbox@2d020000 {
+ compatible = "fsl,imx6sx-mu";
+ reg = <0x2d020000 0x20000>;
+ interrupts = <0 473 4>;
+ #mbox-cells = <2>;
+ power-domains = <&pd IMX_SC_R_VPU_MU_1>;
+ };
+
+ mu2_m0: mailbox@2d040000 {
+ compatible = "fsl,imx6sx-mu";
+ reg = <0x2d040000 0x20000>;
+ interrupts = <0 474 4>;
+ #mbox-cells = <2>;
+ power-domains = <&pd IMX_SC_R_VPU_MU_2>;
+ };
+
+ vpu_core0: vpu-core@2d080000 {
+ compatible = "nxp,imx8q-vpu-decoder";
+ reg = <0x2d080000 0x10000>;
+ power-domains = <&pd IMX_SC_R_VPU_DEC_0>;
+ mbox-names = "tx0", "tx1", "rx";
+ mboxes = <&mu_m0 0 0>,
+ <&mu_m0 0 1>,
+ <&mu_m0 1 0>;
+ memory-region = <&decoder_boot>, <&decoder_rpc>;
+ };
+
+ vpu_core1: vpu-core@2d090000 {
+ compatible = "nxp,imx8q-vpu-encoder";
+ reg = <0x2d090000 0x10000>;
+ power-domains = <&pd IMX_SC_R_VPU_ENC_0>;
+ mbox-names = "tx0", "tx1", "rx";
+ mboxes = <&mu1_m0 0 0>,
+ <&mu1_m0 0 1>,
+ <&mu1_m0 1 0>;
+ memory-region = <&encoder1_boot>, <&encoder1_rpc>;
+ };
+
+ vpu_core2: vpu-core@2d0a0000 {
+ reg = <0x2d0a0000 0x10000>;
+ compatible = "nxp,imx8q-vpu-encoder";
+ power-domains = <&pd IMX_SC_R_VPU_ENC_1>;
+ mbox-names = "tx0", "tx1", "rx";
+ mboxes = <&mu2_m0 0 0>,
+ <&mu2_m0 0 1>,
+ <&mu2_m0 1 0>;
+ memory-region = <&encoder2_boot>, <&encoder2_rpc>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/arm,mali-c55.yaml b/Documentation/devicetree/bindings/media/arm,mali-c55.yaml
new file mode 100644
index 000000000000..fc4fcd19922a
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/arm,mali-c55.yaml
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/arm,mali-c55.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM Mali-C55 Image Signal Processor
+
+maintainers:
+ - Daniel Scally <dan.scally@ideasonboard.com>
+ - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+
+properties:
+ compatible:
+ const: arm,mali-c55
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: ISP Video Clock
+ - description: ISP AXI clock
+ - description: ISP AHB-lite clock
+
+ clock-names:
+ items:
+ - const: vclk
+ - const: aclk
+ - const: hclk
+
+ resets:
+ items:
+ - description: vclk domain reset
+ - description: aclk domain reset
+ - description: hclk domain reset
+
+ reset-names:
+ items:
+ - const: vresetn
+ - const: aresetn
+ - const: hresetn
+
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input parallel video bus
+
+ properties:
+ endpoint:
+ $ref: /schemas/graph.yaml#/properties/endpoint
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ isp@400000 {
+ compatible = "arm,mali-c55";
+ reg = <0x400000 0x200000>;
+ clocks = <&clk 0>, <&clk 1>, <&clk 2>;
+ clock-names = "vclk", "aclk", "hclk";
+ resets = <&resets 0>, <&resets 1>, <&resets 2>;
+ reset-names = "vresetn", "aresetn", "hresetn";
+ interrupts = <GIC_SPI 861 IRQ_TYPE_EDGE_RISING>;
+
+ port {
+ isp_in: endpoint {
+ remote-endpoint = <&csi2_rx_out>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/aspeed,video-engine.yaml b/Documentation/devicetree/bindings/media/aspeed,video-engine.yaml
new file mode 100644
index 000000000000..682bba20778c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/aspeed,video-engine.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/aspeed,video-engine.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED Video Engine
+
+maintainers:
+ - Eddie James <eajames@linux.ibm.com>
+
+description:
+ The Video Engine (VE) embedded in the ASPEED SOCs can be configured to
+ capture and compress video data from digital or analog sources.
+
+properties:
+ compatible:
+ enum:
+ - aspeed,ast2400-video-engine
+ - aspeed,ast2500-video-engine
+ - aspeed,ast2600-video-engine
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: vclk
+ - const: eclk
+
+ resets:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ memory-region:
+ maxItems: 1
+ description: |
+ Phandle to the reserved memory nodes to be associated with the
+ VE. VE will acquires memory space for 3 purposes:
+ 1. JPEG header
+ 2. Compressed result
+ 3. Temporary transformed image data
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/ast2600-clock.h>
+
+ video@1e700000 {
+ compatible = "aspeed,ast2600-video-engine";
+ reg = <0x1e700000 0x1000>;
+ clocks = <&syscon ASPEED_CLK_GATE_VCLK>,
+ <&syscon ASPEED_CLK_GATE_ECLK>;
+ clock-names = "vclk", "eclk";
+ interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/media/aspeed-video.txt b/Documentation/devicetree/bindings/media/aspeed-video.txt
deleted file mode 100644
index d2ca32512272..000000000000
--- a/Documentation/devicetree/bindings/media/aspeed-video.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-* Device tree bindings for Aspeed Video Engine
-
-The Video Engine (VE) embedded in the Aspeed AST2400/2500/2600 SOCs can
-capture and compress video data from digital or analog sources.
-
-Required properties:
- - compatible: "aspeed,ast2400-video-engine" or
- "aspeed,ast2500-video-engine" or
- "aspeed,ast2600-video-engine"
- - reg: contains the offset and length of the VE memory region
- - clocks: clock specifiers for the syscon clocks associated with
- the VE (ordering must match the clock-names property)
- - clock-names: "vclk" and "eclk"
- - resets: reset specifier for the syscon reset associated with
- the VE
- - interrupts: the interrupt associated with the VE on this platform
-
-Optional properties:
- - memory-region:
- phandle to a memory region to allocate from, as defined in
- Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
-
-Example:
-
-video-engine@1e700000 {
- compatible = "aspeed,ast2500-video-engine";
- reg = <0x1e700000 0x20000>;
- clocks = <&syscon ASPEED_CLK_GATE_VCLK>, <&syscon ASPEED_CLK_GATE_ECLK>;
- clock-names = "vclk", "eclk";
- resets = <&syscon ASPEED_RESET_VIDEO>;
- interrupts = <7>;
- memory-region = <&video_engine_memory>;
-};
diff --git a/Documentation/devicetree/bindings/media/atmel,isc.yaml b/Documentation/devicetree/bindings/media/atmel,isc.yaml
index 3e4bb8892d94..dc8aba698d78 100644
--- a/Documentation/devicetree/bindings/media/atmel,isc.yaml
+++ b/Documentation/devicetree/bindings/media/atmel,isc.yaml
@@ -44,7 +44,8 @@ properties:
const: isc-mck
port:
- $ref: /schemas/graph.yaml#/properties/port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
description:
Input port node, single endpoint describing the input pad.
@@ -76,8 +77,6 @@ properties:
additionalProperties: false
- additionalProperties: false
-
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/media/brcm,bcm2835-unicam.yaml b/Documentation/devicetree/bindings/media/brcm,bcm2835-unicam.yaml
new file mode 100644
index 000000000000..5fb5d60f069a
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/brcm,bcm2835-unicam.yaml
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/brcm,bcm2835-unicam.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Broadcom BCM283x Camera Interface (Unicam)
+
+maintainers:
+ - Raspberry Pi Kernel Maintenance <kernel-list@raspberrypi.com>
+
+description: |-
+ The Unicam block on BCM283x SoCs is the receiver for either
+ CSI-2 or CCP2 data from image sensors or similar devices.
+
+ The main platform using this SoC is the Raspberry Pi family of boards. On
+ the Pi the VideoCore firmware can also control this hardware block, and
+ driving it from two different processors will cause issues. To avoid this,
+ the firmware checks the device tree configuration during boot. If it finds
+ device tree nodes whose name starts with 'csi' then it will stop the firmware
+ accessing the block, and it can then safely be used via the device tree
+ binding.
+
+properties:
+ compatible:
+ const: brcm,bcm2835-unicam
+
+ reg:
+ items:
+ - description: Unicam block.
+ - description: Clock Manager Image (CMI) block.
+
+ reg-names:
+ items:
+ - const: unicam
+ - const: cmi
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Clock to drive the LP state machine of Unicam.
+ - description: Clock for the VPU (core clock).
+
+ clock-names:
+ items:
+ - const: lp
+ - const: vpu
+
+ power-domains:
+ items:
+ - description: Unicam power domain
+
+ brcm,num-data-lanes:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 2, 4 ]
+ description: |
+ Number of CSI-2 data lanes supported by this Unicam instance. The number
+ of data lanes actively used is specified with the data-lanes endpoint
+ property.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ bus-type:
+ enum: [ 3, 4 ]
+
+ clock-noncontinuous: true
+ data-lanes: true
+ remote-endpoint: true
+
+ required:
+ - bus-type
+ - data-lanes
+ - remote-endpoint
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - brcm,num-data-lanes
+ - port
+
+additionalProperties: False
+
+examples:
+ - |
+ #include <dt-bindings/clock/bcm2835.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/media/video-interfaces.h>
+ #include <dt-bindings/power/raspberrypi-power.h>
+
+ csi1: csi@7e801000 {
+ compatible = "brcm,bcm2835-unicam";
+ reg = <0x7e801000 0x800>,
+ <0x7e802004 0x4>;
+ reg-names = "unicam", "cmi";
+ interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clocks BCM2835_CLOCK_CAM1>,
+ <&firmware_clocks 4>;
+ clock-names = "lp", "vpu";
+ power-domains = <&power RPI_POWER_DOMAIN_UNICAM1>;
+ brcm,num-data-lanes = <2>;
+ port {
+ csi1_ep: endpoint {
+ remote-endpoint = <&imx219_0>;
+ bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/cdns,csi2rx.txt b/Documentation/devicetree/bindings/media/cdns,csi2rx.txt
deleted file mode 100644
index 6b02a0657ad9..000000000000
--- a/Documentation/devicetree/bindings/media/cdns,csi2rx.txt
+++ /dev/null
@@ -1,100 +0,0 @@
-Cadence MIPI-CSI2 RX controller
-===============================
-
-The Cadence MIPI-CSI2 RX controller is a CSI-2 bridge supporting up to 4 CSI
-lanes in input, and 4 different pixel streams in output.
-
-Required properties:
- - compatible: must be set to "cdns,csi2rx" and an SoC-specific compatible
- - reg: base address and size of the memory mapped region
- - clocks: phandles to the clocks driving the controller
- - clock-names: must contain:
- * sys_clk: main clock
- * p_clk: register bank clock
- * pixel_if[0-3]_clk: pixel stream output clock, one for each stream
- implemented in hardware, between 0 and 3
-
-Optional properties:
- - phys: phandle to the external D-PHY, phy-names must be provided
- - phy-names: must contain "dphy", if the implementation uses an
- external D-PHY
-
-Required subnodes:
- - ports: A ports node with one port child node per device input and output
- port, in accordance with the video interface bindings defined in
- Documentation/devicetree/bindings/media/video-interfaces.txt. The
- port nodes are numbered as follows:
-
- Port Description
- -----------------------------
- 0 CSI-2 input
- 1 Stream 0 output
- 2 Stream 1 output
- 3 Stream 2 output
- 4 Stream 3 output
-
- The stream output port nodes are optional if they are not
- connected to anything at the hardware level or implemented
- in the design.Since there is only one endpoint per port,
- the endpoints are not numbered.
-
-
-Example:
-
-csi2rx: csi-bridge@0d060000 {
- compatible = "cdns,csi2rx";
- reg = <0x0d060000 0x1000>;
- clocks = <&byteclock>, <&byteclock>
- <&coreclock>, <&coreclock>,
- <&coreclock>, <&coreclock>;
- clock-names = "sys_clk", "p_clk",
- "pixel_if0_clk", "pixel_if1_clk",
- "pixel_if2_clk", "pixel_if3_clk";
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
-
- csi2rx_in_sensor: endpoint {
- remote-endpoint = <&sensor_out_csi2rx>;
- clock-lanes = <0>;
- data-lanes = <1 2>;
- };
- };
-
- port@1 {
- reg = <1>;
-
- csi2rx_out_grabber0: endpoint {
- remote-endpoint = <&grabber0_in_csi2rx>;
- };
- };
-
- port@2 {
- reg = <2>;
-
- csi2rx_out_grabber1: endpoint {
- remote-endpoint = <&grabber1_in_csi2rx>;
- };
- };
-
- port@3 {
- reg = <3>;
-
- csi2rx_out_grabber2: endpoint {
- remote-endpoint = <&grabber2_in_csi2rx>;
- };
- };
-
- port@4 {
- reg = <4>;
-
- csi2rx_out_grabber3: endpoint {
- remote-endpoint = <&grabber3_in_csi2rx>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml b/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml
new file mode 100644
index 000000000000..6ed9a5621064
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml
@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cdns,csi2rx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cadence MIPI-CSI2 RX controller
+
+maintainers:
+ - Maxime Ripard <mripard@kernel.org>
+
+description:
+ The Cadence MIPI-CSI2 RX controller is a CSI-2 bridge supporting up to 4 CSI
+ lanes in input, and 4 different pixel streams in output.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - starfive,jh7110-csi2rx
+ - ti,j721e-csi2rx
+ - const: cdns,csi2rx
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 2
+
+ interrupt-names:
+ items:
+ - const: error_irq
+ - const: irq
+
+ clocks:
+ items:
+ - description: CSI2Rx system clock
+ - description: Gated Register bank clock for APB interface
+ - description: pixel Clock for Stream interface 0
+ - description: pixel Clock for Stream interface 1
+ - description: pixel Clock for Stream interface 2
+ - description: pixel Clock for Stream interface 3
+
+ clock-names:
+ items:
+ - const: sys_clk
+ - const: p_clk
+ - const: pixel_if0_clk
+ - const: pixel_if1_clk
+ - const: pixel_if2_clk
+ - const: pixel_if3_clk
+
+ resets:
+ items:
+ - description: CSI2Rx system reset
+ - description: Gated Register bank reset for APB interface
+ - description: pixel reset for Stream interface 0
+ - description: pixel reset for Stream interface 1
+ - description: pixel reset for Stream interface 2
+ - description: pixel reset for Stream interface 3
+
+ reset-names:
+ items:
+ - const: sys
+ - const: reg_bank
+ - const: pixel_if0
+ - const: pixel_if1
+ - const: pixel_if2
+ - const: pixel_if3
+
+ phys:
+ maxItems: 1
+ description: MIPI D-PHY
+
+ phy-names:
+ items:
+ - const: dphy
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ const: 4
+
+ clock-lanes:
+ const: 0
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+ items:
+ maximum: 4
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Stream 0 Output port node
+
+ port@2:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Stream 1 Output port node
+
+ port@3:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Stream 2 Output port node
+
+ port@4:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Stream 3 Output port node
+
+ required:
+ - port@0
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ csi@d060000 {
+ compatible = "starfive,jh7110-csi2rx", "cdns,csi2rx";
+ reg = <0x0d060000 0x1000>;
+ clocks = <&byteclock 7>, <&byteclock 6>,
+ <&coreclock 8>, <&coreclock 9>,
+ <&coreclock 10>, <&coreclock 11>;
+ clock-names = "sys_clk", "p_clk",
+ "pixel_if0_clk", "pixel_if1_clk",
+ "pixel_if2_clk", "pixel_if3_clk";
+ resets = <&bytereset 9>, <&bytereset 4>,
+ <&corereset 5>, <&corereset 6>,
+ <&corereset 7>, <&corereset 8>;
+ reset-names = "sys", "reg_bank",
+ "pixel_if0", "pixel_if1",
+ "pixel_if2", "pixel_if3";
+ phys = <&csi_phy>;
+ phy-names = "dphy";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ csi2rx_in_sensor: endpoint {
+ remote-endpoint = <&sensor_out_csi2rx>;
+ clock-lanes = <0>;
+ data-lanes = <1 2>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ csi2rx_out_grabber0: endpoint {
+ remote-endpoint = <&grabber0_in_csi2rx>;
+ };
+ };
+
+ port@2 {
+ reg = <2>;
+
+ csi2rx_out_grabber1: endpoint {
+ remote-endpoint = <&grabber1_in_csi2rx>;
+ };
+ };
+
+ port@3 {
+ reg = <3>;
+
+ csi2rx_out_grabber2: endpoint {
+ remote-endpoint = <&grabber2_in_csi2rx>;
+ };
+ };
+
+ port@4 {
+ reg = <4>;
+
+ csi2rx_out_grabber3: endpoint {
+ remote-endpoint = <&grabber3_in_csi2rx>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/cec-gpio.txt b/Documentation/devicetree/bindings/media/cec-gpio.txt
deleted file mode 100644
index 47e8d73d32a3..000000000000
--- a/Documentation/devicetree/bindings/media/cec-gpio.txt
+++ /dev/null
@@ -1,42 +0,0 @@
-* HDMI CEC GPIO driver
-
-The HDMI CEC GPIO module supports CEC implementations where the CEC line
-is hooked up to a pull-up GPIO line and - optionally - the HPD line is
-hooked up to another GPIO line.
-
-Please note: the maximum voltage for the CEC line is 3.63V, for the HPD and
-5V lines it is 5.3V. So you may need some sort of level conversion circuitry
-when connecting them to a GPIO line.
-
-Required properties:
- - compatible: value must be "cec-gpio".
- - cec-gpios: gpio that the CEC line is connected to. The line should be
- tagged as open drain.
-
-If the CEC line is associated with an HDMI receiver/transmitter, then the
-following property is also required:
-
- - hdmi-phandle - phandle to the HDMI controller, see also cec.txt.
-
-If the CEC line is not associated with an HDMI receiver/transmitter, then
-the following property is optional and can be used for debugging HPD changes:
-
- - hpd-gpios: gpio that the HPD line is connected to.
-
-This property is optional and can be used for debugging changes on the 5V line:
-
- - v5-gpios: gpio that the 5V line is connected to.
-
-Example for the Raspberry Pi 3 where the CEC line is connected to
-pin 26 aka BCM7 aka CE1 on the GPIO pin header, the HPD line is
-connected to pin 11 aka BCM17 and the 5V line is connected to pin
-15 aka BCM22 (some level shifter is needed for the HPD and 5V lines!):
-
-#include <dt-bindings/gpio/gpio.h>
-
-cec-gpio {
- compatible = "cec-gpio";
- cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
- hpd-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
- v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
-};
diff --git a/Documentation/devicetree/bindings/media/cec.txt b/Documentation/devicetree/bindings/media/cec.txt
deleted file mode 100644
index 22d7aae3d3d7..000000000000
--- a/Documentation/devicetree/bindings/media/cec.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Common bindings for HDMI CEC adapters
-
-- hdmi-phandle: phandle to the HDMI controller.
-
-- needs-hpd: if present the CEC support is only available when the HPD
- is high. Some boards only let the CEC pin through if the HPD is high,
- for example if there is a level converter that uses the HPD to power
- up or down.
diff --git a/Documentation/devicetree/bindings/media/amlogic,meson-gx-ao-cec.yaml b/Documentation/devicetree/bindings/media/cec/amlogic,meson-gx-ao-cec.yaml
index d93aea6a0258..b1fab53418f9 100644
--- a/Documentation/devicetree/bindings/media/amlogic,meson-gx-ao-cec.yaml
+++ b/Documentation/devicetree/bindings/media/cec/amlogic,meson-gx-ao-cec.yaml
@@ -2,13 +2,13 @@
# Copyright 2019 BayLibre, SAS
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/amlogic,meson-gx-ao-cec.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/cec/amlogic,meson-gx-ao-cec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Amlogic Meson AO-CEC Controller
maintainers:
- - Neil Armstrong <narmstrong@baylibre.com>
+ - Neil Armstrong <neil.armstrong@linaro.org>
description: |
The Amlogic Meson AO-CEC module is present is Amlogic SoCs and its purpose is
@@ -33,11 +33,8 @@ properties:
interrupts:
maxItems: 1
- hdmi-phandle:
- description: phandle to the HDMI controller
- $ref: /schemas/types.yaml#/definitions/phandle
-
allOf:
+ - $ref: cec-common.yaml#
- if:
properties:
compatible:
@@ -81,7 +78,7 @@ required:
- clocks
- clock-names
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
diff --git a/Documentation/devicetree/bindings/media/cec/cec-common.yaml b/Documentation/devicetree/bindings/media/cec/cec-common.yaml
new file mode 100644
index 000000000000..6d5017d9bf55
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cec/cec-common.yaml
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cec/cec-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HDMI CEC Adapters Common Properties
+
+maintainers:
+ - Hans Verkuil <hverkuil@kernel.org>
+
+properties:
+ $nodename:
+ pattern: "^cec(@[0-9a-f]+|-[0-9]+)?$"
+
+ hdmi-phandle:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle to the HDMI controller.
+
+ needs-hpd:
+ type: boolean
+ description:
+ The CEC support is only available when the HPD is high. Some boards only
+ let the CEC pin through if the HPD is high, for example if there is a
+ level converter that uses the HPD to power up or down.
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/media/cec/cec-gpio.yaml b/Documentation/devicetree/bindings/media/cec/cec-gpio.yaml
new file mode 100644
index 000000000000..582c6c9cae48
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cec/cec-gpio.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cec/cec-gpio.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: HDMI CEC GPIO
+
+maintainers:
+ - Hans Verkuil <hverkuil@kernel.org>
+
+description: |
+ The HDMI CEC GPIO module supports CEC implementations where the CEC line is
+ hooked up to a pull-up GPIO line and - optionally - the HPD line is hooked up
+ to another GPIO line.
+
+ Please note:: the maximum voltage for the CEC line is 3.63V, for the HPD and
+ 5V lines it is 5.3V. So you may need some sort of level conversion
+ circuitry when connecting them to a GPIO line.
+
+properties:
+ compatible:
+ const: cec-gpio
+
+ cec-gpios:
+ maxItems: 1
+ description:
+ GPIO that the CEC line is connected to. The line should be tagged as open
+ drain.
+
+ hpd-gpios:
+ maxItems: 1
+ description:
+ GPIO that the HPD line is connected to. Used for debugging HPD changes
+ when the CEC line is not associated with an HDMI receiver/transmitter.
+
+ v5-gpios:
+ maxItems: 1
+ description:
+ GPIO that the 5V line is connected to. Used for debugging changes on the
+ 5V line.
+
+required:
+ - compatible
+ - cec-gpios
+
+allOf:
+ - $ref: cec-common.yaml#
+ - if:
+ required:
+ - hdmi-phandle
+ then:
+ properties:
+ hpd-gpios: false
+
+ - if:
+ required:
+ - hpd-gpios
+ then:
+ properties:
+ hdmi-phandle: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ cec {
+ compatible = "cec-gpio";
+ cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
+ hpd-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
+ v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
+ };
diff --git a/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml b/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml
new file mode 100644
index 000000000000..6ef545b1d622
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cec/nvidia,tegra114-cec.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cec/nvidia,tegra114-cec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra HDMI CEC
+
+maintainers:
+ - Hans Verkuil <hverkuil@kernel.org>
+
+allOf:
+ - $ref: cec-common.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - nvidia,tegra114-cec
+ - nvidia,tegra124-cec
+ - nvidia,tegra210-cec
+ - items:
+ - enum:
+ - nvidia,tegra186-cec
+ - nvidia,tegra194-cec
+ - const: nvidia,tegra210-cec
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: cec
+
+ interrupts:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - hdmi-phandle
+ - interrupts
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/tegra124-car.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ cec@70015000 {
+ compatible = "nvidia,tegra124-cec";
+ reg = <0x70015000 0x00001000>;
+ interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&tegra_car TEGRA124_CLK_CEC>;
+ clock-names = "cec";
+ hdmi-phandle = <&hdmi>;
+ };
diff --git a/Documentation/devicetree/bindings/media/cec/samsung,s5p-cec.yaml b/Documentation/devicetree/bindings/media/cec/samsung,s5p-cec.yaml
new file mode 100644
index 000000000000..016c8a77c1a6
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cec/samsung,s5p-cec.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cec/samsung,s5p-cec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5PV210 and Exynos HDMI CEC
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Marek Szyprowski <m.szyprowski@samsung.com>
+
+allOf:
+ - $ref: cec-common.yaml#
+
+properties:
+ compatible:
+ const: samsung,s5p-cec
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: hdmicec
+
+ interrupts:
+ maxItems: 1
+
+ samsung,syscon-phandle:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle to PMU system controller interface
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - hdmi-phandle
+ - interrupts
+ - samsung,syscon-phandle
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos5420.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ cec@101b0000 {
+ compatible = "samsung,s5p-cec";
+ reg = <0x101B0000 0x200>;
+
+ clocks = <&clock CLK_HDMI_CEC>;
+ clock-names = "hdmicec";
+ interrupts = <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>;
+ hdmi-phandle = <&hdmi>;
+ needs-hpd;
+ pinctrl-names = "default";
+ pinctrl-0 = <&hdmi_cec>;
+ samsung,syscon-phandle = <&pmu_system_controller>;
+ };
diff --git a/Documentation/devicetree/bindings/media/cec/st,stih-cec.yaml b/Documentation/devicetree/bindings/media/cec/st,stih-cec.yaml
new file mode 100644
index 000000000000..aeddf16ed339
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cec/st,stih-cec.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cec/st,stih-cec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STIH4xx HDMI CEC
+
+maintainers:
+ - Alain Volmat <alain.volmat@foss.st.com>
+
+allOf:
+ - $ref: cec-common.yaml#
+
+properties:
+ compatible:
+ const: st,stih-cec
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: cec-clk
+
+ interrupts:
+ maxItems: 1
+
+ interrupt-names:
+ items:
+ - const: cec-irq
+
+ resets:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - clocks
+ - hdmi-phandle
+ - interrupts
+ - resets
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/reset/stih407-resets.h>
+
+ cec@94a087c {
+ compatible = "st,stih-cec";
+ reg = <0x94a087c 0x64>;
+
+ clocks = <&clk_sysin>;
+ clock-names = "cec-clk";
+ hdmi-phandle = <&sti_hdmi>;
+ interrupts = <GIC_SPI 140 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "cec-irq";
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_cec0_default>;
+ resets = <&softreset STIH407_LPM_SOFTRESET>;
+ };
diff --git a/Documentation/devicetree/bindings/media/st,stm32-cec.yaml b/Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml
index d75019c093a4..1d930d9e10fd 100644
--- a/Documentation/devicetree/bindings/media/st,stm32-cec.yaml
+++ b/Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml
@@ -1,14 +1,13 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: http://devicetree.org/schemas/media/st,stm32-cec.yaml#
+$id: http://devicetree.org/schemas/media/cec/st,stm32-cec.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 CEC bindings
+title: STMicroelectronics STM32 CEC
maintainers:
- - Benjamin Gaignard <benjamin.gaignard@st.com>
- - Yannick Fertre <yannick.fertre@st.com>
+ - Yannick Fertre <yannick.fertre@foss.st.com>
properties:
compatible:
@@ -30,6 +29,10 @@ properties:
- const: cec
- const: hdmi-cec
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
required:
- compatible
- reg
diff --git a/Documentation/devicetree/bindings/media/cnm,wave521c.yaml b/Documentation/devicetree/bindings/media/cnm,wave521c.yaml
new file mode 100644
index 000000000000..6a11c1d11fb5
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/cnm,wave521c.yaml
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/cnm,wave521c.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Chips&Media Wave 5 Series multi-standard codec IP
+
+maintainers:
+ - Nas Chung <nas.chung@chipsnmedia.com>
+ - Jackson Lee <jackson.lee@chipsnmedia.com>
+
+description:
+ The Chips&Media WAVE codec IP is a multi format video encoder/decoder
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - ti,j721s2-wave521c
+ - const: cnm,wave521c
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: VCODEC clock
+
+ interrupts:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ sram:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ The VPU uses the SRAM to store some of the reference data instead of
+ storing it on DMA memory. It is mainly used for the purpose of reducing
+ bandwidth.
+
+required:
+ - compatible
+ - reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ vpu: video-codec@12345678 {
+ compatible = "ti,j721s2-wave521c", "cnm,wave521c";
+ reg = <0x12345678 0x1000>;
+ clocks = <&clks 42>;
+ interrupts = <42>;
+ sram = <&sram>;
+ };
diff --git a/Documentation/devicetree/bindings/media/coda.yaml b/Documentation/devicetree/bindings/media/coda.yaml
index 36781ee4617f..c9d5adbc8c4a 100644
--- a/Documentation/devicetree/bindings/media/coda.yaml
+++ b/Documentation/devicetree/bindings/media/coda.yaml
@@ -65,7 +65,6 @@ properties:
iram:
$ref: /schemas/types.yaml#/definitions/phandle
description: phandle pointing to the SRAM device node
- maxItems: 1
required:
- compatible
diff --git a/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt b/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt
deleted file mode 100644
index 0bf6fb7fbeab..000000000000
--- a/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-Exynos4x12/Exynos5 SoC series camera host interface (FIMC-LITE)
-
-Required properties:
-
-- compatible : should be one of:
- "samsung,exynos4212-fimc-lite" for Exynos4212/4412 SoCs,
- "samsung,exynos5250-fimc-lite" for Exynos5250 compatible
- devices;
-- reg : physical base address and size of the device memory mapped
- registers;
-- interrupts : should contain FIMC-LITE interrupt;
-- clocks : FIMC LITE gate clock should be specified in this property.
-- clock-names : should contain "flite" entry.
-
-Each FIMC device should have an alias in the aliases node, in the form of
-fimc-lite<n>, where <n> is an integer specifying the IP block instance.
diff --git a/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt b/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt
deleted file mode 100644
index ce9a22689e53..000000000000
--- a/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-Samsung S5P/Exynos SoC series JPEG codec
-
-Required properties:
-
-- compatible : should be one of:
- "samsung,s5pv210-jpeg", "samsung,exynos4210-jpeg",
- "samsung,exynos3250-jpeg", "samsung,exynos5420-jpeg",
- "samsung,exynos5433-jpeg";
-- reg : address and length of the JPEG codec IP register set;
-- interrupts : specifies the JPEG codec IP interrupt;
-- clock-names : should contain:
- - "jpeg" for the core gate clock,
- - "sclk" for the special clock (optional).
-- clocks : should contain the clock specifier and clock ID list
- matching entries in the clock-names property; from
- the common clock bindings.
diff --git a/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt b/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt
deleted file mode 100644
index 32ced99d4244..000000000000
--- a/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-Exynos4x12 SoC series Imaging Subsystem (FIMC-IS)
-
-The FIMC-IS is a subsystem for processing image signal from an image sensor.
-The Exynos4x12 SoC series FIMC-IS V1.5 comprises of a dedicated ARM Cortex-A5
-processor, ISP, DRC and FD IP blocks and peripheral devices such as UART, I2C
-and SPI bus controllers, PWM and ADC.
-
-fimc-is node
-------------
-
-Required properties:
-- compatible : should be "samsung,exynos4212-fimc-is" for Exynos4212 and
- Exynos4412 SoCs;
-- reg : physical base address and length of the registers set;
-- interrupts : must contain two FIMC-IS interrupts, in order: ISP0, ISP1;
-- clocks : list of clock specifiers, corresponding to entries in
- clock-names property;
-- clock-names : must contain "ppmuispx", "ppmuispx", "lite0", "lite1"
- "mpll", "sysreg", "isp", "drc", "fd", "mcuisp", "gicisp",
- "pwm_isp", "mcuctl_isp", "uart", "ispdiv0", "ispdiv1",
- "mcuispdiv0", "mcuispdiv1", "aclk200", "div_aclk200",
- "aclk400mcuisp", "div_aclk400mcuisp" entries,
- matching entries in the clocks property.
-pmu subnode
------------
-
-Required properties:
- - reg : must contain PMU physical base address and size of the register set.
-
-The following are the FIMC-IS peripheral device nodes and can be specified
-either standalone or as the fimc-is node child nodes.
-
-i2c-isp (ISP I2C bus controller) nodes
-------------------------------------------
-
-Required properties:
-
-- compatible : should be "samsung,exynos4212-i2c-isp" for Exynos4212 and
- Exynos4412 SoCs;
-- reg : physical base address and length of the registers set;
-- clocks : must contain gate clock specifier for this controller;
-- clock-names : must contain "i2c_isp" entry.
-
-For the above nodes it is required to specify a pinctrl state named "default",
-according to the pinctrl bindings defined in ../pinctrl/pinctrl-bindings.txt.
-
-Device tree nodes of the image sensors' controlled directly by the FIMC-IS
-firmware must be child nodes of their corresponding ISP I2C bus controller node.
-The data link of these image sensors must be specified using the common video
-interfaces bindings, defined in video-interfaces.txt.
diff --git a/Documentation/devicetree/bindings/media/exynos5-gsc.txt b/Documentation/devicetree/bindings/media/exynos5-gsc.txt
deleted file mode 100644
index 1872688fa408..000000000000
--- a/Documentation/devicetree/bindings/media/exynos5-gsc.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-* Samsung Exynos5 G-Scaler device
-
-G-Scaler is used for scaling and color space conversion on Exynos5 SoCs.
-
-Required properties:
-- compatible: should be one of
- "samsung,exynos5250-gsc"
- "samsung,exynos5420-gsc"
- "samsung,exynos5433-gsc"
- "samsung,exynos5-gsc" (deprecated)
-- reg: should contain G-Scaler physical address location and length.
-- interrupts: should contain G-Scaler interrupt number
-
-Optional properties:
-- samsung,sysreg: handle to syscon used to control the system registers to
- set writeback input and destination
-
-Example:
-
-gsc_0: gsc@13e00000 {
- compatible = "samsung,exynos5250-gsc";
- reg = <0x13e00000 0x1000>;
- interrupts = <0 85 0>;
-};
-
-Aliases:
-Each G-Scaler node should have a numbered alias in the aliases node,
-in the form of gscN, N = 0...3. G-Scaler driver uses these aliases
-to retrieve the device IDs using "of_alias_get_id()" call.
-
-Example:
-
-aliases {
- gsc0 =&gsc_0;
- gsc1 =&gsc_1;
- gsc2 =&gsc_2;
- gsc3 =&gsc_3;
-};
diff --git a/Documentation/devicetree/bindings/media/fsl,imx-capture-subsystem.yaml b/Documentation/devicetree/bindings/media/fsl,imx-capture-subsystem.yaml
new file mode 100644
index 000000000000..25e65a344a0a
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/fsl,imx-capture-subsystem.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/fsl,imx-capture-subsystem.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale i.MX Media Video Device
+
+description:
+ This is the media controller node for video capture support. It is a
+ virtual device that lists the camera serial interface nodes that the
+ media device will control
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: fsl,imx-capture-subsystem
+
+ ports:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ description:
+ Should contain a list of phandles pointing to camera
+ sensor interface ports of IPU devices.
+
+required:
+ - compatible
+
+additionalProperties: false
+
+examples:
+ - |
+ capture-subsystem {
+ compatible = "fsl,imx-capture-subsystem";
+ ports = <&ipu1_csi0>, <&ipu1_csi1>;
+ };
diff --git a/Documentation/devicetree/bindings/media/fsl,imx6-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/fsl,imx6-mipi-csi2.yaml
new file mode 100644
index 000000000000..65255f576f26
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/fsl,imx6-mipi-csi2.yaml
@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/fsl,imx6-mipi-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MIPI CSI-2 Receiver core in the i.MX SoC
+
+description:
+ This is the device node for the MIPI CSI-2 Receiver core in the i.MX
+ SoC. This is a Synopsys Designware MIPI CSI-2 host controller core
+ combined with a D-PHY core mixed into the same register block. In
+ addition this device consists of an i.MX-specific "CSI2IPU gasket"
+ glue logic, also controlled from the same register block. The CSI2IPU
+ gasket demultiplexes the four virtual channel streams from the host
+ controller's 32-bit output image bus onto four 16-bit parallel busses
+ to the i.MX IPU CSIs.
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: fsl,imx6-mipi-csi2
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: hsi_tx (the D-PHY clock)
+ - description: video_27m (D-PHY PLL reference clock)
+ - description: eim_podf;
+
+ clock-names:
+ items:
+ - const: dphy
+ - const: ref
+ - const: pix
+
+ interrupts:
+ items:
+ - description: CSI-2 ERR1 irq
+ - description: CSI-2 ERR2 irq
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ const: 0
+
+ data-lanes:
+ minItems: 1
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ required:
+ - data-lanes
+
+patternProperties:
+ '^port@[1-4]$':
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ ports 1 through 4 are output ports connecting with parallel bus sink
+ endpoint nodes and correspond to the four MIPI CSI-2 virtual channel
+ outputs.
+
+ properties:
+ endpoint@0:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ endpoint@1:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx6qdl-clock.h>
+
+ mipi@21dc000 {
+ compatible = "fsl,imx6-mipi-csi2";
+ reg = <0x021dc000 0x4000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ clocks = <&clks IMX6QDL_CLK_HSI_TX>,
+ <&clks IMX6QDL_CLK_VIDEO_27M>,
+ <&clks IMX6QDL_CLK_EIM_PODF>;
+ clock-names = "dphy", "ref", "pix";
+
+ port@0 {
+ reg = <0>;
+
+ endpoint {
+ remote-endpoint = <&ov5640_to_mipi_csi2>;
+ clock-lanes = <0>;
+ data-lanes = <1 2>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&ipu1_csi0_mux_from_mipi_vc0>;
+ };
+
+ endpoint@1 {
+ reg = <1>;
+ remote-endpoint = <&ipu1_csi1_mux_from_mipi_vc0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/fsl,imx6q-vdoa.yaml b/Documentation/devicetree/bindings/media/fsl,imx6q-vdoa.yaml
new file mode 100644
index 000000000000..988a5b3a62bd
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/fsl,imx6q-vdoa.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/fsl,imx6q-vdoa.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Video Data Order Adapter
+
+description:
+ The Video Data Order Adapter (VDOA) is present on the i.MX6q. Its sole purpose
+ is to reorder video data from the macroblock tiled order produced by the CODA
+ 960 VPU to the conventional raster-scan order for scanout.
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+properties:
+ compatible:
+ const: fsl,imx6q-vdoa
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/imx6qdl-clock.h>
+
+ vdoa@21e4000 {
+ compatible = "fsl,imx6q-vdoa";
+ reg = <0x021e4000 0x4000>;
+ interrupts = <0 18 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clks IMX6QDL_CLK_VDOA>;
+ };
diff --git a/Documentation/devicetree/bindings/media/fsl,imx6ull-pxp.yaml b/Documentation/devicetree/bindings/media/fsl,imx6ull-pxp.yaml
new file mode 100644
index 000000000000..3f47744459aa
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/fsl,imx6ull-pxp.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/fsl,imx6ull-pxp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale Pixel Pipeline
+
+maintainers:
+ - Philipp Zabel <p.zabel@pengutronix.de>
+ - Michael Tretter <m.tretter@pengutronix.de>
+
+description:
+ The Pixel Pipeline (PXP) is a memory-to-memory graphics processing engine
+ that supports scaling, colorspace conversion, alpha blending, rotation, and
+ pixel conversion via lookup table. Different versions are present on various
+ i.MX SoCs from i.MX23 to i.MX7.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - fsl,imx6ul-pxp
+ - fsl,imx6ull-pxp
+ - fsl,imx7d-pxp
+ - items:
+ - enum:
+ - fsl,imx6sll-pxp
+ - fsl,imx6sx-pxp
+ - const: fsl,imx6ull-pxp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: axi
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx6sx-pxp
+ - fsl,imx6ul-pxp
+ then:
+ properties:
+ interrupts:
+ maxItems: 1
+ else:
+ properties:
+ interrupts:
+ minItems: 2
+ maxItems: 2
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx6ul-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ pxp: pxp@21cc000 {
+ compatible = "fsl,imx6ull-pxp";
+ reg = <0x021cc000 0x4000>;
+ interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>;
+ clock-names = "axi";
+ clocks = <&clks IMX6UL_CLK_PXP>;
+ };
diff --git a/Documentation/devicetree/bindings/media/fsl,imx8qm-isi.yaml b/Documentation/devicetree/bindings/media/fsl,imx8qm-isi.yaml
new file mode 100644
index 000000000000..93f527e223af
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/fsl,imx8qm-isi.yaml
@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/fsl,imx8qm-isi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX8QM Image Sensing Interface
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description:
+ The Image Sensing Interface (ISI) combines image processing pipelines with
+ DMA engines to process and capture frames originating from a variety of
+ sources. The inputs to the ISI go through Pixel Link interfaces, and their
+ number and nature is SoC-dependent. They cover both capture interfaces (MIPI
+ CSI-2 RX, HDMI RX, ...) and display engine outputs for writeback support.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx8qm-isi
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 8
+
+ clock-names:
+ items:
+ - const: per0
+ - const: per1
+ - const: per2
+ - const: per3
+ - const: per4
+ - const: per5
+ - const: per6
+ - const: per7
+
+ interrupts:
+ maxItems: 8
+
+ power-domains:
+ maxItems: 8
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@2:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: MIPI CSI-2 RX 0
+ port@3:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: MIPI CSI-2 RX 1
+ port@4:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: HDMI RX
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+ - power-domains
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/imx8-clock.h>
+ #include <dt-bindings/clock/imx8-lpcg.h>
+ #include <dt-bindings/firmware/imx/rsrc.h>
+
+ image-controller@58100000 {
+ compatible = "fsl,imx8qm-isi";
+ reg = <0x58100000 0x80000>;
+ interrupts = <GIC_SPI 297 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 298 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 299 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 300 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 301 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 302 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 303 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 304 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&pdma0_lpcg IMX_LPCG_CLK_0>,
+ <&pdma1_lpcg IMX_LPCG_CLK_0>,
+ <&pdma2_lpcg IMX_LPCG_CLK_0>,
+ <&pdma3_lpcg IMX_LPCG_CLK_0>,
+ <&pdma4_lpcg IMX_LPCG_CLK_0>,
+ <&pdma5_lpcg IMX_LPCG_CLK_0>,
+ <&pdma6_lpcg IMX_LPCG_CLK_0>,
+ <&pdma7_lpcg IMX_LPCG_CLK_0>;
+ clock-names = "per0", "per1", "per2", "per3",
+ "per4", "per5", "per6", "per7";
+ power-domains = <&pd IMX_SC_R_ISI_CH0>, <&pd IMX_SC_R_ISI_CH1>,
+ <&pd IMX_SC_R_ISI_CH2>, <&pd IMX_SC_R_ISI_CH3>,
+ <&pd IMX_SC_R_ISI_CH4>, <&pd IMX_SC_R_ISI_CH5>,
+ <&pd IMX_SC_R_ISI_CH6>, <&pd IMX_SC_R_ISI_CH7>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@2 {
+ reg = <2>;
+ endpoint {
+ remote-endpoint = <&mipi_csi0_out>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/fsl,imx8qxp-isi.yaml b/Documentation/devicetree/bindings/media/fsl,imx8qxp-isi.yaml
new file mode 100644
index 000000000000..bb41996bd2e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/fsl,imx8qxp-isi.yaml
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/fsl,imx8qxp-isi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX8QXP Image Sensing Interface
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description:
+ The Image Sensing Interface (ISI) combines image processing pipelines with
+ DMA engines to process and capture frames originating from a variety of
+ sources. The inputs to the ISI go through Pixel Link interfaces, and their
+ number and nature is SoC-dependent. They cover both capture interfaces (MIPI
+ CSI-2 RX, HDMI RX, ...) and display engine outputs for writeback support.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx8qxp-isi
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 6
+
+ clock-names:
+ items:
+ - const: per0
+ - const: per1
+ - const: per2
+ - const: per3
+ - const: per4
+ - const: per5
+
+ interrupts:
+ maxItems: 6
+
+ power-domains:
+ maxItems: 6
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@2:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: MIPI CSI-2 RX 0
+ port@6:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: CSI-2 Parallel RX
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+ - power-domains
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/imx8-clock.h>
+ #include <dt-bindings/clock/imx8-lpcg.h>
+ #include <dt-bindings/firmware/imx/rsrc.h>
+
+ image-controller@58100000 {
+ compatible = "fsl,imx8qxp-isi";
+ reg = <0x58100000 0x60000>;
+ interrupts = <GIC_SPI 297 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 298 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 299 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 300 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 301 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 302 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&pdma0_lpcg IMX_LPCG_CLK_0>,
+ <&pdma1_lpcg IMX_LPCG_CLK_0>,
+ <&pdma2_lpcg IMX_LPCG_CLK_0>,
+ <&pdma3_lpcg IMX_LPCG_CLK_0>,
+ <&pdma4_lpcg IMX_LPCG_CLK_0>,
+ <&pdma5_lpcg IMX_LPCG_CLK_0>;
+ clock-names = "per0", "per1", "per2", "per3", "per4", "per5";
+ power-domains = <&pd IMX_SC_R_ISI_CH0>, <&pd IMX_SC_R_ISI_CH1>,
+ <&pd IMX_SC_R_ISI_CH2>, <&pd IMX_SC_R_ISI_CH3>,
+ <&pd IMX_SC_R_ISI_CH4>, <&pd IMX_SC_R_ISI_CH5>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@2 {
+ reg = <2>;
+ endpoint {
+ remote-endpoint = <&mipi_csi0_out>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/fsl-pxp.txt b/Documentation/devicetree/bindings/media/fsl-pxp.txt
deleted file mode 100644
index f8090e06530d..000000000000
--- a/Documentation/devicetree/bindings/media/fsl-pxp.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-Freescale Pixel Pipeline
-========================
-
-The Pixel Pipeline (PXP) is a memory-to-memory graphics processing engine
-that supports scaling, colorspace conversion, alpha blending, rotation, and
-pixel conversion via lookup table. Different versions are present on various
-i.MX SoCs from i.MX23 to i.MX7.
-
-Required properties:
-- compatible: should be "fsl,<soc>-pxp", where SoC can be one of imx23, imx28,
- imx6dl, imx6sl, imx6sll, imx6ul, imx6sx, imx6ull, or imx7d.
-- reg: the register base and size for the device registers
-- interrupts: the PXP interrupt, two interrupts for imx6ull and imx7d.
-- clock-names: should be "axi"
-- clocks: the PXP AXI clock
-
-Example:
-
-pxp@21cc000 {
- compatible = "fsl,imx6ull-pxp";
- reg = <0x021cc000 0x4000>;
- interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>;
- clock-names = "axi";
- clocks = <&clks IMX6UL_CLK_PXP>;
-};
diff --git a/Documentation/devicetree/bindings/media/fsl-vdoa.txt b/Documentation/devicetree/bindings/media/fsl-vdoa.txt
deleted file mode 100644
index 6c5628530bb7..000000000000
--- a/Documentation/devicetree/bindings/media/fsl-vdoa.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Freescale Video Data Order Adapter
-==================================
-
-The Video Data Order Adapter (VDOA) is present on the i.MX6q. Its sole purpose
-is to reorder video data from the macroblock tiled order produced by the CODA
-960 VPU to the conventional raster-scan order for scanout.
-
-Required properties:
-- compatible: must be "fsl,imx6q-vdoa"
-- reg: the register base and size for the device registers
-- interrupts: the VDOA interrupt
-- clocks: the vdoa clock
-
-Example:
-
-vdoa@21e4000 {
- compatible = "fsl,imx6q-vdoa";
- reg = <0x021e4000 0x4000>;
- interrupts = <0 18 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&clks IMX6QDL_CLK_VDOA>;
-};
diff --git a/Documentation/devicetree/bindings/media/gpio-ir-receiver.txt b/Documentation/devicetree/bindings/media/gpio-ir-receiver.txt
deleted file mode 100644
index 108bf435b933..000000000000
--- a/Documentation/devicetree/bindings/media/gpio-ir-receiver.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Device-Tree bindings for GPIO IR receiver
-
-Required properties:
- - compatible: should be "gpio-ir-receiver".
- - gpios: specifies GPIO used for IR signal reception.
-
-Optional properties:
- - linux,rc-map-name: see rc.txt file in the same
- directory.
- - linux,autosuspend-period: autosuspend delay time,
- the unit is milisecond.
-
-Example node:
-
- ir: ir-receiver {
- compatible = "gpio-ir-receiver";
- gpios = <&gpio0 19 1>;
- linux,rc-map-name = "rc-rc6-mce";
- linux,autosuspend-period = <125>;
- };
diff --git a/Documentation/devicetree/bindings/media/gpio-ir-receiver.yaml b/Documentation/devicetree/bindings/media/gpio-ir-receiver.yaml
new file mode 100644
index 000000000000..008c007ed702
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/gpio-ir-receiver.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/gpio-ir-receiver.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GPIO Based IR receiver
+
+maintainers:
+ - Sebastian Hesselbarth <sebastian.hesselbarth@gmail.com>
+
+allOf:
+ - $ref: rc.yaml#
+
+properties:
+ compatible:
+ const: gpio-ir-receiver
+
+ gpios:
+ maxItems: 1
+
+ linux,autosuspend-period:
+ description: autosuspend delay time in milliseconds
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ wakeup-source:
+ description: IR receiver can wake-up the system.
+
+required:
+ - compatible
+ - gpios
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ ir-receiver {
+ compatible = "gpio-ir-receiver";
+ gpios = <&gpio0 19 1>;
+ linux,rc-map-name = "rc-rc6-mce";
+ linux,autosuspend-period = <125>;
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ad5820.txt b/Documentation/devicetree/bindings/media/i2c/ad5820.txt
deleted file mode 100644
index 5764cbedf9b7..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ad5820.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-* Analog Devices AD5820 autofocus coil
-
-Required Properties:
-
- - compatible: Must contain one of:
- - "adi,ad5820"
- - "adi,ad5821"
- - "adi,ad5823"
-
- - reg: I2C slave address
-
- - VANA-supply: supply of voltage for VANA pin
-
-Optional properties:
-
- - enable-gpios : GPIO spec for the XSHUTDOWN pin. The XSHUTDOWN signal is
-active low, a high level on the pin enables the device.
-
-Example:
-
- ad5820: coil@c {
- compatible = "adi,ad5820";
- reg = <0x0c>;
-
- VANA-supply = <&vaux4>;
- enable-gpios = <&msmgpio 26 GPIO_ACTIVE_HIGH>;
- };
-
diff --git a/Documentation/devicetree/bindings/media/i2c/adi,ad5820.yaml b/Documentation/devicetree/bindings/media/i2c/adi,ad5820.yaml
new file mode 100644
index 000000000000..0c8f24f692ca
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/adi,ad5820.yaml
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/adi,ad5820.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD5820 autofocus coil
+
+maintainers:
+ - Pavel Machek <pavel@ucw.cz>
+
+description:
+ The AD5820 is a current sink driver designed for precise control of
+ voice coil motors (VCMs) in camera autofocus systems.
+
+properties:
+ compatible:
+ enum:
+ - adi,ad5820
+ - adi,ad5821
+ - adi,ad5823
+
+ reg:
+ maxItems: 1
+
+ enable-gpios:
+ maxItems: 1
+ description:
+ GPIO spec for the XSHUTDOWN pin. The XSHUTDOWN signal is active low,
+ a high level on the pin enables the device.
+
+ VANA-supply:
+ description: supply of voltage for VANA pin
+
+required:
+ - compatible
+ - reg
+ - VANA-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ coil@c {
+ compatible = "adi,ad5820";
+ reg = <0x0c>;
+
+ enable-gpios = <&msmgpio 26 GPIO_ACTIVE_HIGH>;
+ VANA-supply = <&vaux4>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/adp1653.txt b/Documentation/devicetree/bindings/media/i2c/adi,adp1653.txt
index 4cce0de40ee9..4cce0de40ee9 100644
--- a/Documentation/devicetree/bindings/media/i2c/adp1653.txt
+++ b/Documentation/devicetree/bindings/media/i2c/adi,adp1653.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/adi,adv7180.yaml b/Documentation/devicetree/bindings/media/i2c/adi,adv7180.yaml
new file mode 100644
index 000000000000..dee8ce7cb7ba
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/adi,adv7180.yaml
@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/adi,adv7180.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADV7180 analog video decoder family
+
+maintainers:
+ - Lars-Peter Clausen <lars@metafoo.de>
+
+description:
+ The adv7180 family devices are used to capture analog video to different
+ digital interfaces like MIPI CSI-2 or parallel video.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - adi,adv7180
+ - adi,adv7180cp
+ - adi,adv7180st
+ - adi,adv7182
+ - adi,adv7280
+ - adi,adv7280-m
+ - adi,adv7281
+ - adi,adv7281-m
+ - adi,adv7281-ma
+ - adi,adv7282
+ - adi,adv7282-m
+
+ reg:
+ maxItems: 1
+
+ powerdown-gpios:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ adv,force-bt656-4:
+ deprecated: true
+ description:
+ Indicates that the output is a BT.656-4 compatible stream.
+ type: boolean
+
+ adi,force-bt656-4:
+ description:
+ Indicates that the output is a BT.656-4 compatible stream.
+ type: boolean
+
+ interrupts:
+ items:
+ - description: The GPIO connected to the INTRQ pin.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ ports: true
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - adi,adv7180
+ - adi,adv7182
+ - adi,adv7280
+ - adi,adv7280-m
+ - adi,adv7281
+ - adi,adv7281-m
+ - adi,adv7281-ma
+ - adi,adv7282
+ - adi,adv7282-m
+ then:
+ required:
+ - port
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7180cp
+ then:
+ properties:
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@3:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output port
+
+ patternProperties:
+ "^port@[0-2]$":
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port
+
+ required:
+ - port@3
+
+ required:
+ - ports
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7180st
+ then:
+ properties:
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@6:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output port
+
+ patternProperties:
+ "^port@[0-5]$":
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port
+
+ required:
+ - port@6
+
+ required:
+ - ports
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ composite-in@20 {
+ compatible = "adi,adv7180";
+ reg = <0x20>;
+
+ port {
+ adv7180: endpoint {
+ bus-width = <8>;
+ remote-endpoint = <&vin1ep>;
+ };
+ };
+ };
+
+ };
+
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ composite-in@20 {
+ compatible = "adi,adv7180cp";
+ reg = <0x20>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ adv7180_in: endpoint {
+ remote-endpoint = <&composite_con_in>;
+ };
+ };
+
+ port@3 {
+ reg = <3>;
+ adv7180_out: endpoint {
+ remote-endpoint = <&vin4_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/adv7343.txt b/Documentation/devicetree/bindings/media/i2c/adi,adv7343.txt
index 5653bc2428b8..5653bc2428b8 100644
--- a/Documentation/devicetree/bindings/media/i2c/adv7343.txt
+++ b/Documentation/devicetree/bindings/media/i2c/adi,adv7343.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/adi,adv748x.yaml b/Documentation/devicetree/bindings/media/i2c/adi,adv748x.yaml
new file mode 100644
index 000000000000..254987350321
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/adi,adv748x.yaml
@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/adi,adv748x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADV748X video decoder with HDMI receiver
+
+maintainers:
+ - Kieran Bingham <kieran.bingham@ideasonboard.com>
+ - Niklas Söderlund <niklas.soderlund@ragnatech.se>
+
+description:
+ The ADV7481 and ADV7482 are multi format video decoders with an integrated
+ HDMI receiver. They can output CSI-2 on two independent outputs TXA and TXB
+ from three input sources HDMI, analog and TTL.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - adi,adv7481
+ - adi,adv7482
+
+ reg:
+ minItems: 1
+ maxItems: 12
+ description:
+ The ADV748x has up to twelve 256-byte maps that can be accessed via the
+ main I2C ports. Each map has it own I2C address and acts as a standard
+ slave device on the I2C bus. The main address is mandatory, others are
+ optional and remain at default values if not specified.
+
+ reg-names:
+ minItems: 1
+ items:
+ - const: main
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+ - enum: [ dpll, cp, hdmi, edid, repeater, infoframe, cbus, cec, sdp, txa, txb ]
+
+ interrupts: true
+
+ interrupt-names: true
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ patternProperties:
+ "^port@[0-7]$":
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port nodes for analog inputs AIN[0-7].
+
+ properties:
+ port@8:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port node for HDMI.
+
+ port@9:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port node for TTL.
+
+ port@a:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Output port node, single endpoint describing the CSI-2 transmitter TXA.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@b:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Output port node, single endpoint describing the CSI-2 transmitter TXB.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ maxItems: 1
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7481
+ then:
+ properties:
+ interrupts:
+ minItems: 1
+ maxItems: 3
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 3
+ items:
+ enum: [ intrq1, intrq2, intrq3 ]
+ else:
+ properties:
+ interrupts:
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [ intrq1, intrq2 ]
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - ports
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ video-receiver@70 {
+ compatible = "adi,adv7482";
+ reg = <0x70 0x71 0x72 0x73 0x74 0x75
+ 0x60 0x61 0x62 0x63 0x64 0x65>;
+ reg-names = "main", "dpll", "cp", "hdmi", "edid", "repeater",
+ "infoframe", "cbus", "cec", "sdp", "txa", "txb";
+
+ interrupt-parent = <&gpio6>;
+ interrupts = <30 IRQ_TYPE_LEVEL_LOW>, <31 IRQ_TYPE_LEVEL_LOW>;
+ interrupt-names = "intrq1", "intrq2";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@7 {
+ reg = <7>;
+
+ adv7482_ain7: endpoint {
+ remote-endpoint = <&cvbs_in>;
+ };
+ };
+
+ port@8 {
+ reg = <8>;
+
+ adv7482_hdmi: endpoint {
+ remote-endpoint = <&hdmi_in>;
+ };
+ };
+
+ port@a {
+ reg = <10>;
+
+ adv7482_txa: endpoint {
+ clock-lanes = <0>;
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&csi40_in>;
+ };
+ };
+
+ port@b {
+ reg = <11>;
+
+ adv7482_txb: endpoint {
+ clock-lanes = <0>;
+ data-lanes = <1>;
+ remote-endpoint = <&csi20_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/adi,adv7604.yaml b/Documentation/devicetree/bindings/media/i2c/adi,adv7604.yaml
new file mode 100644
index 000000000000..f8d9889dbc21
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/adi,adv7604.yaml
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/adi,adv7604.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADV7604/10/11/12 video decoder with HDMI receiver
+
+maintainers:
+ - Hans Verkuil <hverkuil@kernel.org>
+
+description:
+ The ADV7604 and ADV7610/11/12 are multiformat video decoders with
+ an integrated HDMI receiver. The ADV7604 has four multiplexed HDMI inputs
+ and one analog input, and the ADV7610/11 have one HDMI input and no analog
+ input. The ADV7612 is similar to the ADV7610/11 but has 2 HDMI inputs.
+
+ These device tree bindings support the ADV7610/11/12 only at the moment.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - adi,adv7610
+ - adi,adv7611
+ - adi,adv7612
+
+ reg:
+ minItems: 1
+ maxItems: 13
+
+ reg-names:
+ minItems: 1
+ items:
+ - const: main
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+ - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ hpd-gpios:
+ minItems: 1
+ description:
+ References to the GPIOs that control the HDMI hot-plug detection pins,
+ one per HDMI input. The active flag indicates the GPIO level that
+ enables hot-plug detection.
+
+ default-input:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 0, 1 ]
+ description:
+ Select which input is selected after reset.
+
+ ports: true
+
+required:
+ - compatible
+ - reg
+ - ports
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7611
+ then:
+ properties:
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output port
+
+ required:
+ - port@1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: adi,adv7612
+ then:
+ properties:
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@2:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output port
+
+ patternProperties:
+ "^port@[0-1]$":
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port
+
+ required:
+ - port@2
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hdmi_receiver@4c {
+ compatible = "adi,adv7611";
+ /*
+ * The edid page will be accessible @ 0x66 on the I2C bus. All
+ * other maps will retain their default addresses.
+ */
+ reg = <0x4c>, <0x66>;
+ reg-names = "main", "edid";
+
+ reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>;
+ hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>;
+ default-input = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ };
+
+ port@1 {
+ reg = <1>;
+ hdmi_in: endpoint {
+ remote-endpoint = <&ccdc_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml
deleted file mode 100644
index 3ce4af143a3a..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml
+++ /dev/null
@@ -1,171 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/media/i2c/adv7180.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Analog Devices ADV7180 analog video decoder family
-
-maintainers:
- - Lars-Peter Clausen <lars@metafoo.de>
-
-description:
- The adv7180 family devices are used to capture analog video to different
- digital interfaces like MIPI CSI-2 or parallel video.
-
-properties:
- compatible:
- items:
- - enum:
- - adi,adv7180
- - adi,adv7180cp
- - adi,adv7180st
- - adi,adv7182
- - adi,adv7280
- - adi,adv7280-m
- - adi,adv7281
- - adi,adv7281-m
- - adi,adv7281-ma
- - adi,adv7282
- - adi,adv7282-m
-
- reg:
- maxItems: 1
-
- powerdown-gpios:
- maxItems: 1
-
- port:
- $ref: /schemas/graph.yaml#/$defs/port-base
- unevaluatedProperties: false
-
- properties:
- endpoint:
- $ref: /schemas/media/video-interfaces.yaml#
- unevaluatedProperties: false
-
- ports: true
-
-additionalProperties: false
-
-required:
- - compatible
- - reg
-
-allOf:
- - if:
- properties:
- compatible:
- enum:
- - adi,adv7180
- - adi,adv7182
- - adi,adv7280
- - adi,adv7280-m
- - adi,adv7281
- - adi,adv7281-m
- - adi,adv7281-ma
- - adi,adv7282
- - adi,adv7282-m
- then:
- required:
- - port
-
- - if:
- properties:
- compatible:
- contains:
- const: adi,adv7180cp
- then:
- properties:
- ports:
- $ref: /schemas/graph.yaml#/properties/ports
- properties:
- port@3:
- $ref: /schemas/graph.yaml#/properties/port
- description: Output port
-
- patternProperties:
- "^port@[0-2]$":
- $ref: /schemas/graph.yaml#/properties/port
- description: Input port
-
- required:
- - port@3
-
- required:
- - ports
-
- - if:
- properties:
- compatible:
- contains:
- const: adi,adv7180st
- then:
- properties:
- ports:
- $ref: /schemas/graph.yaml#/properties/ports
- properties:
- port@6:
- $ref: /schemas/graph.yaml#/properties/port
- description: Output port
-
- patternProperties:
- "^port@[0-5]$":
- $ref: /schemas/graph.yaml#/properties/port
- description: Input port
-
- required:
- - port@6
-
- required:
- - ports
-
-examples:
- - |
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- composite-in@20 {
- compatible = "adi,adv7180";
- reg = <0x20>;
-
- port {
- adv7180: endpoint {
- bus-width = <8>;
- remote-endpoint = <&vin1ep>;
- };
- };
- };
-
- };
-
- - |
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- composite-in@20 {
- compatible = "adi,adv7180cp";
- reg = <0x20>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
- adv7180_in: endpoint {
- remote-endpoint = <&composite_con_in>;
- };
- };
-
- port@3 {
- reg = <3>;
- adv7180_out: endpoint {
- remote-endpoint = <&vin4_in>;
- };
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/adv748x.txt b/Documentation/devicetree/bindings/media/i2c/adv748x.txt
deleted file mode 100644
index 4f91686e54a6..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/adv748x.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-* Analog Devices ADV748X video decoder with HDMI receiver
-
-The ADV7481 and ADV7482 are multi format video decoders with an integrated
-HDMI receiver. They can output CSI-2 on two independent outputs TXA and TXB
-from three input sources HDMI, analog and TTL.
-
-Required Properties:
-
- - compatible: Must contain one of the following
- - "adi,adv7481" for the ADV7481
- - "adi,adv7482" for the ADV7482
-
- - reg: I2C slave addresses
- The ADV748x has up to twelve 256-byte maps that can be accessed via the
- main I2C ports. Each map has it own I2C address and acts as a standard
- slave device on the I2C bus. The main address is mandatory, others are
- optional and remain at default values if not specified.
-
-Optional Properties:
-
- - interrupt-names: Should specify the interrupts as "intrq1", "intrq2" and/or
- "intrq3". All interrupts are optional. The "intrq3" interrupt
- is only available on the adv7481
- - interrupts: Specify the interrupt lines for the ADV748x
- - reg-names : Names of maps with programmable addresses.
- It shall contain all maps needing a non-default address.
- Possible map names are:
- "main", "dpll", "cp", "hdmi", "edid", "repeater",
- "infoframe", "cbus", "cec", "sdp", "txa", "txb"
-
-The device node must contain one 'port' child node per device input and output
-port, in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt. The port nodes
-are numbered as follows.
-
- Name Type Port
- ---------------------------------------
- AIN0 sink 0
- AIN1 sink 1
- AIN2 sink 2
- AIN3 sink 3
- AIN4 sink 4
- AIN5 sink 5
- AIN6 sink 6
- AIN7 sink 7
- HDMI sink 8
- TTL sink 9
- TXA source 10
- TXB source 11
-
-The digital output port nodes, when present, shall contain at least one
-endpoint. Each of those endpoints shall contain the data-lanes property as
-described in video-interfaces.txt.
-
-Required source endpoint properties:
- - data-lanes: an array of physical data lane indexes
- The accepted value(s) for this property depends on which of the two
- sources are described. For TXA 1, 2 or 4 data lanes can be described
- while for TXB only 1 data lane is valid. See video-interfaces.txt
- for detailed description.
-
-Ports are optional if they are not connected to anything at the hardware level.
-
-Example:
-
- video-receiver@70 {
- compatible = "adi,adv7482";
- reg = <0x70 0x71 0x72 0x73 0x74 0x75
- 0x60 0x61 0x62 0x63 0x64 0x65>;
- reg-names = "main", "dpll", "cp", "hdmi", "edid", "repeater",
- "infoframe", "cbus", "cec", "sdp", "txa", "txb";
-
- #address-cells = <1>;
- #size-cells = <0>;
-
- interrupt-parent = <&gpio6>;
- interrupt-names = "intrq1", "intrq2";
- interrupts = <30 IRQ_TYPE_LEVEL_LOW>,
- <31 IRQ_TYPE_LEVEL_LOW>;
-
- port@7 {
- reg = <7>;
-
- adv7482_ain7: endpoint {
- remote-endpoint = <&cvbs_in>;
- };
- };
-
- port@8 {
- reg = <8>;
-
- adv7482_hdmi: endpoint {
- remote-endpoint = <&hdmi_in>;
- };
- };
-
- port@a {
- reg = <10>;
-
- adv7482_txa: endpoint {
- clock-lanes = <0>;
- data-lanes = <1 2 3 4>;
- remote-endpoint = <&csi40_in>;
- };
- };
-
- port@b {
- reg = <11>;
-
- adv7482_txb: endpoint {
- clock-lanes = <0>;
- data-lanes = <1>;
- remote-endpoint = <&csi20_in>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.yaml b/Documentation/devicetree/bindings/media/i2c/adv7604.yaml
deleted file mode 100644
index de15cebe2955..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/adv7604.yaml
+++ /dev/null
@@ -1,158 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/media/i2c/adv7604.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Analog Devices ADV7604/11/12 video decoder with HDMI receiver
-
-maintainers:
- - Hans Verkuil <hverkuil-cisco@xs4all.nl>
-
-description:
- The ADV7604 and ADV7611/12 are multiformat video decoders with an integrated
- HDMI receiver. The ADV7604 has four multiplexed HDMI inputs and one analog
- input, and the ADV7611 has one HDMI input and no analog input. The 7612 is
- similar to the 7611 but has 2 HDMI inputs.
-
- These device tree bindings support the ADV7611/12 only at the moment.
-
-properties:
- compatible:
- items:
- - enum:
- - adi,adv7611
- - adi,adv7612
-
- reg:
- minItems: 1
- maxItems: 13
-
- reg-names:
- minItems: 1
- items:
- - const: main
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
- - enum: [ avlink, cec, infoframe, esdp, dpp, afe, rep, edid, hdmi, test, cp, vdp ]
-
- interrupts:
- maxItems: 1
-
- reset-gpios:
- maxItems: 1
-
- hpd-gpios:
- minItems: 1
- description:
- References to the GPIOs that control the HDMI hot-plug detection pins,
- one per HDMI input. The active flag indicates the GPIO level that
- enables hot-plug detection.
-
- default-input:
- maxItems: 1
- description:
- Select which input is selected after reset.
-
- ports: true
-
-required:
- - compatible
- - reg
- - ports
-
-additionalProperties: false
-
-allOf:
- - if:
- properties:
- compatible:
- contains:
- const: adi,adv7611
- then:
- properties:
- ports:
- $ref: /schemas/graph.yaml#/properties/ports
- properties:
- port@0:
- $ref: /schemas/graph.yaml#/properties/port
- description: Input port
-
- port@1:
- $ref: /schemas/graph.yaml#/properties/port
- description: Output port
-
- required:
- - port@1
-
- - if:
- properties:
- compatible:
- contains:
- const: adi,adv7612
- then:
- properties:
- ports:
- $ref: /schemas/graph.yaml#/properties/ports
- properties:
- port@2:
- $ref: /schemas/graph.yaml#/properties/port
- description: Output port
-
- patternProperties:
- "^port@[0-1]$":
- $ref: /schemas/graph.yaml#/properties/port
- description: Input port
-
- required:
- - port@2
-
-examples:
- - |
- #include <dt-bindings/gpio/gpio.h>
-
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- hdmi_receiver@4c {
- compatible = "adi,adv7611";
- /*
- * The edid page will be accessible @ 0x66 on the I2C bus. All
- * other maps will retain their default addresses.
- */
- reg = <0x4c>, <0x66>;
- reg-names = "main", "edid";
-
- reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>;
- hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>;
- default-input = <0>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
- };
-
- port@1 {
- reg = <1>;
- hdmi_in: endpoint {
- remote-endpoint = <&ccdc_in>;
- };
- };
- };
-
-
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/ak7375.txt b/Documentation/devicetree/bindings/media/i2c/ak7375.txt
deleted file mode 100644
index aa3e24b41241..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ak7375.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Asahi Kasei Microdevices AK7375 voice coil lens driver
-
-AK7375 is a camera voice coil lens.
-
-Mandatory properties:
-
-- compatible: "asahi-kasei,ak7375"
-- reg: I2C slave address
diff --git a/Documentation/devicetree/bindings/media/i2c/alliedvision,alvium-csi2.yaml b/Documentation/devicetree/bindings/media/i2c/alliedvision,alvium-csi2.yaml
new file mode 100644
index 000000000000..d3329e991d16
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/alliedvision,alvium-csi2.yaml
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/alliedvision,alvium-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allied Vision Alvium Camera
+
+maintainers:
+ - Tommaso Merciai <tomm.merciai@gmail.com>
+ - Martin Hecht <martin.hecht@avnet.eu>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: alliedvision,alvium-csi2
+
+ reg:
+ maxItems: 1
+
+ vcc-ext-in-supply:
+ description: |
+ The regulator that supplies power to the VCC_EXT_IN pins.
+
+ port:
+ description: Digital Output Port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ link-frequencies: true
+
+ data-lanes:
+ minItems: 1
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - vcc-ext-in-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ alvium: camera@3c {
+ compatible = "alliedvision,alvium-csi2";
+ reg = <0x3c>;
+ vcc-ext-in-supply = <&reg_vcc_ext_in>;
+
+ port {
+ alvium_out: endpoint {
+ remote-endpoint = <&mipi_csi_0_in>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <681250000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9p031.yaml b/Documentation/devicetree/bindings/media/i2c/aptina,mt9p031.yaml
new file mode 100644
index 000000000000..be00de2f2d58
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/aptina,mt9p031.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/aptina,mt9p031.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Aptina 1/2.5-Inch 5Mp CMOS Digital Image Sensor
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |
+ The Aptina MT9P031 is a 1/2.5-inch CMOS active pixel digital image sensor
+ with an active array size of 2592H x 1944V. It is programmable through a
+ simple two-wire serial interface.
+
+properties:
+ compatible:
+ enum:
+ - aptina,mt9p006
+ - aptina,mt9p031
+ - aptina,mt9p031m
+
+ reg:
+ description: I2C device address
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ vdd-supply:
+ description: Digital supply voltage, 1.8 V
+
+ vdd_io-supply:
+ description: I/O supply voltage, 1.8 or 2.8 V
+
+ vaa-supply:
+ description: Analog supply voltage, 2.8 V
+
+ reset-gpios:
+ maxItems: 1
+ description: Chip reset GPIO
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ input-clock-frequency:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 6000000
+ maximum: 96000000
+ description: Input clock frequency
+
+ pixel-clock-frequency:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 96000000
+ description: Target pixel clock frequency
+
+ pclk-sample:
+ default: 0
+
+ required:
+ - input-clock-frequency
+ - pixel-clock-frequency
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vdd-supply
+ - vdd_io-supply
+ - vaa-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ mt9p031@5d {
+ compatible = "aptina,mt9p031";
+ reg = <0x5d>;
+ reset-gpios = <&gpio_sensor 0 0>;
+
+ clocks = <&sensor_clk>;
+
+ vdd-supply = <&reg_vdd>;
+ vdd_io-supply = <&reg_vdd_io>;
+ vaa-supply = <&reg_vaa>;
+
+ port {
+ mt9p031_1: endpoint {
+ input-clock-frequency = <6000000>;
+ pixel-clock-frequency = <96000000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/mt9v032.txt b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v032.txt
index 100f0ae43269..100f0ae43269 100644
--- a/Documentation/devicetree/bindings/media/i2c/mt9v032.txt
+++ b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v032.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml
index e53b8d65f381..088022f88010 100644
--- a/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/aptina,mt9v111.yaml
@@ -55,7 +55,7 @@ additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/media/i2c/asahi-kasei,ak7375.yaml b/Documentation/devicetree/bindings/media/i2c/asahi-kasei,ak7375.yaml
new file mode 100644
index 000000000000..fe312cc6a873
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/asahi-kasei,ak7375.yaml
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/asahi-kasei,ak7375.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Asahi Kasei Microdevices AK7375 voice coil lens actuator
+
+maintainers:
+ - Tianshu Qiu <tian.shu.qiu@intel.com>
+
+description:
+ AK7375 is a voice coil motor (VCM) camera lens actuator that
+ is controlled over I2C.
+
+properties:
+ compatible:
+ enum:
+ - asahi-kasei,ak7345
+ - asahi-kasei,ak7375
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: VDD supply
+
+ vio-supply:
+ description: I/O pull-up supply
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+ - vio-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ak7375: camera-lens@c {
+ compatible = "asahi-kasei,ak7375";
+ reg = <0x0c>;
+
+ vdd-supply = <&vreg_l23a_2p8>;
+ vio-supply = <&vreg_lvs1a_1p8>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml b/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml
index 63e5b89d2e0b..4e69b6a7ffcc 100644
--- a/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml
@@ -1,8 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/i2c/chrontel,ch7322.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/i2c/chrontel,ch7322.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Chrontel HDMI-CEC Controller
@@ -13,6 +13,9 @@ description:
The Chrontel CH7322 is a discrete HDMI-CEC controller. It is
programmable through I2C and drives a single CEC line.
+allOf:
+ - $ref: /schemas/media/cec/cec-common.yaml#
+
properties:
compatible:
const: chrontel,ch7322
@@ -40,16 +43,12 @@ properties:
if in auto mode.
maxItems: 1
- # see ../cec.txt
- hdmi-phandle:
- description: phandle to the HDMI controller
-
required:
- compatible
- reg
- interrupts
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
@@ -58,7 +57,7 @@ examples:
i2c {
#address-cells = <1>;
#size-cells = <0>;
- ch7322@75 {
+ cec@75 {
compatible = "chrontel,ch7322";
reg = <0x75>;
interrupts = <47 IRQ_TYPE_EDGE_RISING>;
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.txt b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.txt
deleted file mode 100644
index b88dcdd41def..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-Dongwoon Anatech DW9714 camera voice coil lens driver
-
-DW9174 is a 10-bit DAC with current sink capability. It is intended
-for driving voice coil lenses in camera modules.
-
-Mandatory properties:
-
-- compatible: "dongwoon,dw9714"
-- reg: I²C slave address
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.yaml b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.yaml
new file mode 100644
index 000000000000..66229a3dc05d
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9714.yaml
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/dongwoon,dw9714.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Dongwoon Anatech DW9714 camera voice coil lens driver
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description:
+ DW9174 is a 10-bit DAC with current sink capability. It is intended for
+ driving voice coil lenses in camera modules.
+
+properties:
+ compatible:
+ const: dongwoon,dw9714
+
+ reg:
+ maxItems: 1
+
+ powerdown-gpios:
+ description:
+ XSD pin for shutdown (active low)
+
+ vcc-supply:
+ description: VDD power supply
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera-lens@c {
+ compatible = "dongwoon,dw9714";
+ reg = <0x0c>;
+ vcc-supply = <&reg_csi_1v8>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9719.yaml b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9719.yaml
new file mode 100644
index 000000000000..8e8d62436e0d
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9719.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/dongwoon,dw9719.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Dongwoon Anatech DW9719 Voice Coil Motor (VCM) Controller
+
+maintainers:
+ - André Apitzsch <git@apitzsch.eu>
+
+description:
+ The Dongwoon DW9718S/9719/9761 is a single 10-bit digital-to-analog converter
+ with 100 mA output current sink capability, designed for linear control of
+ voice coil motors (VCM) in camera lenses. This chip provides a Smart Actuator
+ Control (SAC) mode intended for driving voice coil lenses in camera modules.
+
+properties:
+ compatible:
+ enum:
+ - dongwoon,dw9718s
+ - dongwoon,dw9719
+ - dongwoon,dw9761
+ - dongwoon,dw9800k
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: VDD power supply
+
+ dongwoon,sac-mode:
+ description: |
+ Slew Rate Control mode to use: direct, LSC (Linear Slope Control) or
+ SAC1-SAC6 (Smart Actuator Control).
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 0 # Direct mode
+ - 1 # LSC mode
+ - 2 # SAC1 mode (operation time# 0.32 x Tvib)
+ - 3 # SAC2 mode (operation time# 0.48 x Tvib)
+ - 4 # SAC3 mode (operation time# 0.72 x Tvib)
+ - 5 # SAC4 mode (operation time# 1.20 x Tvib)
+ - 6 # SAC5 mode (operation time# 1.64 x Tvib)
+ - 7 # SAC6 mode (operation time# 1.88 x Tvib)
+ default: 4
+
+ dongwoon,vcm-prescale:
+ description:
+ Indication of VCM switching frequency dividing rate select.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+required:
+ - compatible
+ - reg
+ - vdd-supply
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: dongwoon,dw9718s
+ then:
+ properties:
+ dongwoon,vcm-prescale:
+ description:
+ The final frequency is 10 MHz divided by (value + 2).
+ maximum: 15
+ default: 0
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ actuator@c {
+ compatible = "dongwoon,dw9718s";
+ reg = <0x0c>;
+
+ vdd-supply = <&pm8937_l17>;
+
+ dongwoon,sac-mode = <4>;
+ dongwoon,vcm-prescale = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml
index 21864ab86ec4..a0855d3b7577 100644
--- a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml
@@ -5,7 +5,7 @@
$id: http://devicetree.org/schemas/media/i2c/dongwoon,dw9768.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Dongwoon Anatech DW9768 Voice Coil Motor (VCM) Lens Device Tree Bindings
+title: Dongwoon Anatech DW9768 Voice Coil Motor (VCM) Lens
maintainers:
- Dongchun Zhu <dongchun.zhu@mediatek.com>
@@ -38,7 +38,7 @@ properties:
dongwoon,aac-mode:
description:
Indication of AAC mode select.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
enum:
- 1 # AAC2 mode(operation time# 0.48 x Tvib)
- 2 # AAC3 mode(operation time# 0.70 x Tvib)
@@ -50,7 +50,7 @@ properties:
description:
Number of AAC Timing count that controlled by one 6-bit period of
vibration register AACT[5:0], the unit of which is 100 us.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
default: 0x20
minimum: 0x00
maximum: 0x3f
@@ -59,7 +59,7 @@ properties:
description:
Indication of VCM internal clock dividing rate select, as one multiple
factor to calculate VCM ring periodic time Tvib.
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
enum:
- 0 # Dividing Rate - 2
- 1 # Dividing Rate - 1
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.txt b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.txt
deleted file mode 100644
index c4701f1eaaf6..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-Dongwoon Anatech DW9807 voice coil lens driver
-
-DW9807 is a 10-bit DAC with current sink capability. It is intended for
-controlling voice coil lenses.
-
-Mandatory properties:
-
-- compatible: "dongwoon,dw9807-vcm"
-- reg: I2C slave address
diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.yaml b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.yaml
new file mode 100644
index 000000000000..aae246ca3fcf
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.yaml
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2018, 2021 Intel Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/dongwoon,dw9807-vcm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Dongwoon Anatech DW9807 voice coil lens driver
+
+maintainers:
+ - Sakari Ailus <sakari.ailus@linux.intel.com>
+
+description: |
+ DW9807 is a 10-bit DAC with current sink capability. It is intended for
+ controlling voice coil lenses.
+
+properties:
+ compatible:
+ const: dongwoon,dw9807-vcm
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ lens@e {
+ compatible = "dongwoon,dw9807-vcm";
+ reg = <0x0e>;
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/galaxycore,gc0308.yaml b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc0308.yaml
new file mode 100644
index 000000000000..2bf1a81feaf4
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc0308.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/galaxycore,gc0308.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Galaxycore GC0308 and GC0309 Image Sensors
+
+maintainers:
+ - Sebastian Reichel <sre@kernel.org>
+
+description: |
+ The GalaxyCore GC0308 (1/6.5") and GC0309 (1/9") are 640x480 VGA sensors
+ programmable through an I2C interface and connected via parallel bus.
+ They include an ISP capable of auto exposure and auto white balance.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - const: galaxycore,gc0308
+ - items:
+ - const: galaxycore,gc0309
+ - const: galaxycore,gc0308
+
+ reg:
+ const: 0x21
+
+ clocks:
+ description: Reference to the xclk clock.
+ maxItems: 1
+
+ reset-gpios:
+ description: GPIO descriptor for the reset pin.
+ maxItems: 1
+
+ powerdown-gpios:
+ description: GPIO descriptor for the powerdown pin.
+ maxItems: 1
+
+ vdd28-supply:
+ description: 2.8V supply
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ description: |
+ Video output port.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-width: true
+ data-shift: true
+ hsync-active: true
+ vsync-active: true
+ data-active: true
+ pclk-sample: true
+
+ required:
+ - bus-width
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - powerdown-gpios
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera-sensor@21 {
+ compatible = "galaxycore,gc0308";
+ reg = <0x21>;
+ clocks = <&camera_clk>;
+ powerdown-gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio1 6 GPIO_ACTIVE_LOW>;
+ vdd28-supply = <&vdd28>;
+
+ port {
+ gc0308_ep: endpoint {
+ remote-endpoint = <&parallel_from_gc0308>;
+ bus-width = <8>;
+ data-shift = <2>; /* lines 9:2 are used */
+ hsync-active = <1>; /* active high */
+ vsync-active = <1>; /* active high */
+ data-active = <1>; /* active high */
+ pclk-sample = <1>; /* sample on rising edge */
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/galaxycore,gc05a2.yaml b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc05a2.yaml
new file mode 100644
index 000000000000..0e7a7b5ac89f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc05a2.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2023 MediaTek Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/galaxycore,gc05a2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GalaxyCore gc05a2 1/5" 5M Pixel MIPI CSI-2 sensor
+
+maintainers:
+ - Zhi Mao <zhi.mao@mediatek.com>
+
+description:
+ The gc05a2 is a raw image sensor with an MIPI CSI-2 image data
+ interface and CCI (I2C compatible) control bus. The output format
+ is raw Bayer.
+
+properties:
+ compatible:
+ const: galaxycore,gc05a2
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ dovdd-supply: true
+
+ avdd-supply: true
+
+ dvdd-supply: true
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the RESETB pin.
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+ description:
+ Output port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+ - items:
+ - const: 1
+ - const: 2
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - dovdd-supply
+ - avdd-supply
+ - dvdd-supply
+ - reset-gpios
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@37 {
+ compatible = "galaxycore,gc05a2";
+ reg = <0x37>;
+
+ clocks = <&gc05a2_clk>;
+
+ reset-gpios = <&pio 21 GPIO_ACTIVE_LOW>;
+
+ avdd-supply = <&gc05a2_avdd>;
+ dovdd-supply = <&gc05a2_dovdd>;
+ dvdd-supply = <&gc05a2_dvdd>;
+
+ port {
+ sensor_out: endpoint {
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <448000000 224000000>;
+ remote-endpoint = <&seninf_csi_port_1_in>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/galaxycore,gc08a3.yaml b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc08a3.yaml
new file mode 100644
index 000000000000..51b8ece09c72
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc08a3.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2023 MediaTek Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/galaxycore,gc08a3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: GalaxyCore gc08a3 1/4" 8M Pixel MIPI CSI-2 sensor
+
+maintainers:
+ - Zhi Mao <zhi.mao@mediatek.com>
+
+description:
+ The gc08a3 is a raw image sensor with an MIPI CSI-2 image data
+ interface and CCI (I2C compatible) control bus. The output format
+ is raw Bayer.
+
+properties:
+ compatible:
+ const: galaxycore,gc08a3
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ dovdd-supply: true
+
+ avdd-supply: true
+
+ dvdd-supply: true
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the RESETB pin.
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+ description:
+ Output port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+ - items:
+ - const: 1
+ - const: 2
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - dovdd-supply
+ - avdd-supply
+ - dvdd-supply
+ - reset-gpios
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@31 {
+ compatible = "galaxycore,gc08a3";
+ reg = <0x31>;
+
+ clocks = <&gc08a3_clk>;
+
+ reset-gpios = <&pio 19 GPIO_ACTIVE_LOW>;
+
+ avdd-supply = <&gc08a3_avdd>;
+ dovdd-supply = <&gc08a3_dovdd>;
+ dvdd-supply = <&gc08a3_dvdd>;
+
+ port {
+ sensor_out: endpoint {
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <336000000 207000000>;
+ remote-endpoint = <&seninf_csi_port_0_in>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/galaxycore,gc2145.yaml b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc2145.yaml
new file mode 100644
index 000000000000..9eac588de0bc
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/galaxycore,gc2145.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/galaxycore,gc2145.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Galaxy Core 1/5'' UXGA CMOS Image Sensor
+
+maintainers:
+ - Alain Volmat <alain.volmat@foss.st.com>
+
+description:
+ The Galaxy Core GC2145 is a 2 Megapixel CMOS image sensor, for mobile
+ phone camera applications and digital camera products. GC2145 incorporates a
+ 1616V x 1232H active pixel array, on-chip 10-bit ADC, and image signal
+ processor allowing AE/AWB/interpolation/de-noise/color-conversion and
+ gamma correction. Bayer RGB, RGB565 and YCbCr 4:2:2 can be provided by the
+ sensor. It is programmable through an I2C interface. Image data is sent
+ either through a parallel interface or through MIPI CSI-2.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: galaxycore,gc2145
+
+ reg:
+ const: 0x3c
+
+ clocks:
+ maxItems: 1
+
+ powerdown-gpios:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ iovdd-supply:
+ description: Power Supply for I/O circuits (1.7 - 3V).
+
+ avdd-supply:
+ description: Power for analog circuit/sensor array (2.7 - 3V).
+
+ dvdd-supply:
+ description: Power for digital core (1.7 - 1.9V).
+
+ orientation: true
+
+ rotation: true
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ link-frequencies: true
+
+ required:
+ - link-frequencies
+
+ required:
+ - endpoint
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - powerdown-gpios
+ - reset-gpios
+ - iovdd-supply
+ - avdd-supply
+ - dvdd-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3c {
+ compatible = "galaxycore,gc2145";
+ reg = <0x3c>;
+ clocks = <&clk_ext_camera>;
+ iovdd-supply = <&scmi_v3v3_sw>;
+ avdd-supply = <&scmi_v3v3_sw>;
+ dvdd-supply = <&scmi_v3v3_sw>;
+ powerdown-gpios = <&mcp23017 3 (GPIO_ACTIVE_LOW | GPIO_PUSH_PULL)>;
+ reset-gpios = <&mcp23017 4 (GPIO_ACTIVE_LOW | GPIO_PUSH_PULL)>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&mipid02_0>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <120000000 192000000 240000000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml b/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml
new file mode 100644
index 000000000000..1a57f2aa1982
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/hynix,hi846.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SK Hynix Hi-846 1/4" 8M Pixel MIPI CSI-2 sensor
+
+maintainers:
+ - Martin Kepplinger <martin.kepplinger@puri.sm>
+
+description: |-
+ The Hi-846 is a raw image sensor with an MIPI CSI-2 image data
+ interface and CCI (I2C compatible) control bus. The output format
+ is raw Bayer.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: hynix,hi846
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Reference to the mclk clock.
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the RESETB pin. Active low.
+ maxItems: 1
+
+ shutdown-gpios:
+ description: Reference to the GPIO connected to the XSHUTDOWN pin. Active low.
+ maxItems: 1
+
+ vddio-supply:
+ description: Definition of the regulator used for the VDDIO power supply.
+
+ vdda-supply:
+ description: Definition of the regulator used for the VDDA power supply.
+
+ vddd-supply:
+ description: Definition of the regulator used for the VDDD power supply.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+ - items:
+ - const: 1
+ - const: 2
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vddio-supply
+ - vdda-supply
+ - vddd-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hi846: camera@20 {
+ compatible = "hynix,hi846";
+ reg = <0x20>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_csi1>;
+ clocks = <&clk 0>;
+ vdda-supply = <&reg_camera_vdda>;
+ vddd-supply = <&reg_camera_vddd>;
+ vddio-supply = <&reg_camera_vddio>;
+ reset-gpios = <&gpio1 25 GPIO_ACTIVE_LOW>;
+ shutdown-gpios = <&gpio5 4 GPIO_ACTIVE_LOW>;
+ orientation = <0>;
+ rotation = <0>;
+
+ port {
+ camera_out: endpoint {
+ remote-endpoint = <&csi1_ep1>;
+ link-frequencies = /bits/ 64
+ <80000000 200000000>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/imx219.yaml b/Documentation/devicetree/bindings/media/i2c/imx219.yaml
deleted file mode 100644
index 5fc96944b448..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/imx219.yaml
+++ /dev/null
@@ -1,109 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/media/i2c/imx219.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Sony 1/4.0-Inch 8Mpixel CMOS Digital Image Sensor
-
-maintainers:
- - Dave Stevenson <dave.stevenson@raspberrypi.com>
-
-description: |-
- The Sony imx219 is a 1/4.0-inch CMOS active pixel digital image sensor
- with an active array size of 3280H x 2464V. It is programmable through
- I2C interface. The I2C address is fixed to 0x10 as per sensor data sheet.
- Image data is sent through MIPI CSI-2, which is configured as either 2 or
- 4 data lanes.
-
-properties:
- compatible:
- const: sony,imx219
-
- reg:
- description: I2C device address
- maxItems: 1
-
- clocks:
- maxItems: 1
-
- VDIG-supply:
- description:
- Digital I/O voltage supply, 1.8 volts
-
- VANA-supply:
- description:
- Analog voltage supply, 2.8 volts
-
- VDDL-supply:
- description:
- Digital core voltage supply, 1.2 volts
-
- reset-gpios:
- maxItems: 1
- description: |-
- Reference to the GPIO connected to the xclr pin, if any.
- Must be released (set high) after all supplies are applied.
-
- port:
- $ref: /schemas/graph.yaml#/$defs/port-base
- additionalProperties: false
-
- properties:
- endpoint:
- $ref: /schemas/media/video-interfaces.yaml#
- unevaluatedProperties: false
-
- properties:
- data-lanes:
- description: |-
- The sensor supports either two-lane, or four-lane operation.
- If this property is omitted four-lane operation is assumed.
- For two-lane operation the property must be set to <1 2>.
- items:
- - const: 1
- - const: 2
-
- clock-noncontinuous: true
- link-frequencies: true
-
- required:
- - link-frequencies
-
-required:
- - compatible
- - reg
- - clocks
- - VANA-supply
- - VDIG-supply
- - VDDL-supply
- - port
-
-additionalProperties: false
-
-examples:
- - |
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- imx219: sensor@10 {
- compatible = "sony,imx219";
- reg = <0x10>;
- clocks = <&imx219_clk>;
- VANA-supply = <&imx219_vana>; /* 2.8v */
- VDIG-supply = <&imx219_vdig>; /* 1.8v */
- VDDL-supply = <&imx219_vddl>; /* 1.2v */
-
- port {
- imx219_0: endpoint {
- remote-endpoint = <&csi1_ep>;
- data-lanes = <1 2>;
- clock-noncontinuous;
- link-frequencies = /bits/ 64 <456000000>;
- };
- };
- };
- };
-
-...
diff --git a/Documentation/devicetree/bindings/media/i2c/imx258.yaml b/Documentation/devicetree/bindings/media/i2c/imx258.yaml
deleted file mode 100644
index cde0f7383b2a..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/imx258.yaml
+++ /dev/null
@@ -1,134 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/media/i2c/imx258.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Sony IMX258 13 Mpixel CMOS Digital Image Sensor
-
-maintainers:
- - Krzysztof Kozlowski <krzk@kernel.org>
-
-description: |-
- IMX258 is a diagonal 5.867mm (Type 1/3.06) 13 Mega-pixel CMOS active pixel
- type stacked image sensor with a square pixel array of size 4208 x 3120. It
- is programmable through I2C interface. Image data is sent through MIPI
- CSI-2.
-
-properties:
- compatible:
- const: sony,imx258
-
- assigned-clocks: true
- assigned-clock-parents: true
- assigned-clock-rates: true
-
- clocks:
- description:
- Clock frequency from 6 to 27 MHz.
- maxItems: 1
-
- reg:
- maxItems: 1
-
- reset-gpios:
- description: |-
- Reference to the GPIO connected to the XCLR pin, if any.
-
- vana-supply:
- description:
- Analog voltage (VANA) supply, 2.7 V
-
- vdig-supply:
- description:
- Digital I/O voltage (VDIG) supply, 1.2 V
-
- vif-supply:
- description:
- Interface voltage (VIF) supply, 1.8 V
-
- # See ../video-interfaces.txt for more details
- port:
- $ref: /schemas/graph.yaml#/$defs/port-base
- additionalProperties: false
-
- properties:
- endpoint:
- $ref: /schemas/media/video-interfaces.yaml#
- unevaluatedProperties: false
-
- properties:
- data-lanes:
- oneOf:
- - items:
- - const: 1
- - const: 2
- - const: 3
- - const: 4
- - items:
- - const: 1
- - const: 2
-
- link-frequencies: true
-
- required:
- - data-lanes
- - link-frequencies
-
-required:
- - compatible
- - reg
- - port
-
-additionalProperties: false
-
-examples:
- - |
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- sensor@6c {
- compatible = "sony,imx258";
- reg = <0x6c>;
- clocks = <&imx258_clk>;
-
- port {
- endpoint {
- remote-endpoint = <&csi1_ep>;
- data-lanes = <1 2 3 4>;
- link-frequencies = /bits/ 64 <320000000>;
- };
- };
- };
- };
-
- /* Oscillator on the camera board */
- imx258_clk: clk {
- compatible = "fixed-clock";
- #clock-cells = <0>;
- clock-frequency = <19200000>;
- };
-
- - |
- i2c0 {
- #address-cells = <1>;
- #size-cells = <0>;
-
- sensor@6c {
- compatible = "sony,imx258";
- reg = <0x6c>;
- clocks = <&imx258_clk>;
-
- assigned-clocks = <&imx258_clk>;
- assigned-clock-rates = <19200000>;
-
- port {
- endpoint {
- remote-endpoint = <&csi1_ep>;
- data-lanes = <1 2 3 4>;
- link-frequencies = /bits/ 64 <633600000>;
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/imx290.txt b/Documentation/devicetree/bindings/media/i2c/imx290.txt
deleted file mode 100644
index a3cc21410f7c..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/imx290.txt
+++ /dev/null
@@ -1,57 +0,0 @@
-* Sony IMX290 1/2.8-Inch CMOS Image Sensor
-
-The Sony IMX290 is a 1/2.8-Inch CMOS Solid-state image sensor with
-Square Pixel for Color Cameras. It is programmable through I2C and 4-wire
-interfaces. The sensor output is available via CMOS logic parallel SDR output,
-Low voltage LVDS DDR output and CSI-2 serial data output. The CSI-2 bus is the
-default. No bindings have been defined for the other busses.
-
-Required Properties:
-- compatible: Should be "sony,imx290"
-- reg: I2C bus address of the device
-- clocks: Reference to the xclk clock.
-- clock-names: Should be "xclk".
-- clock-frequency: Frequency of the xclk clock in Hz.
-- vdddo-supply: Sensor digital IO regulator.
-- vdda-supply: Sensor analog regulator.
-- vddd-supply: Sensor digital core regulator.
-
-Optional Properties:
-- reset-gpios: Sensor reset GPIO
-
-The imx290 device node should contain one 'port' child node with
-an 'endpoint' subnode. For further reading on port node refer to
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-Required Properties on endpoint:
-- data-lanes: check ../video-interfaces.txt
-- link-frequencies: check ../video-interfaces.txt
-- remote-endpoint: check ../video-interfaces.txt
-
-Example:
- &i2c1 {
- ...
- imx290: camera-sensor@1a {
- compatible = "sony,imx290";
- reg = <0x1a>;
-
- reset-gpios = <&msmgpio 35 GPIO_ACTIVE_LOW>;
- pinctrl-names = "default";
- pinctrl-0 = <&camera_rear_default>;
-
- clocks = <&gcc GCC_CAMSS_MCLK0_CLK>;
- clock-names = "xclk";
- clock-frequency = <37125000>;
-
- vdddo-supply = <&camera_vdddo_1v8>;
- vdda-supply = <&camera_vdda_2v8>;
- vddd-supply = <&camera_vddd_1v5>;
-
- port {
- imx290_ep: endpoint {
- data-lanes = <1 2 3 4>;
- link-frequencies = /bits/ 64 <445500000>;
- remote-endpoint = <&csiphy0_ep>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/isil,isl79987.yaml b/Documentation/devicetree/bindings/media/i2c/isil,isl79987.yaml
new file mode 100644
index 000000000000..034a6e3466af
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/isil,isl79987.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/isil,isl79987.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Intersil ISL79987 Analog to MIPI CSI-2 decoder
+
+maintainers:
+ - Michael Tretter <m.tretter@pengutronix.de>
+ - Marek Vasut <marex@denx.de>
+
+description:
+ The Intersil ISL79987 is an analog to MIPI CSI-2 decoder which is capable of
+ receiving up to four analog stream and multiplexing them into up to four MIPI
+ CSI-2 virtual channels, using one MIPI clock lane and 1/2 data lanes.
+
+properties:
+ compatible:
+ enum:
+ - isil,isl79987
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ A GPIO spec for the RSTB pin (active high)
+
+ powerdown-gpios:
+ maxItems: 1
+ description:
+ A GPIO spec for the Power Down pin (active high)
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: Output port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+
+ required:
+ - data-lanes
+
+ patternProperties:
+ "^port@[1-4]$":
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input ports
+
+ required:
+ - port@0
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - ports
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ isl7998x_mipi@44 {
+ compatible = "isil,isl79987";
+ reg = <0x44>;
+ powerdown-gpios = <&gpio3 27 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio3 28 GPIO_ACTIVE_HIGH>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ isl79987_out: endpoint {
+ remote-endpoint = <&mipi_csi2_in>;
+ data-lanes = <1 2>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ endpoint {
+ remote-endpoint = <&camera_0>;
+ };
+ };
+
+ port@2 {
+ reg = <2>;
+ endpoint {
+ remote-endpoint = <&camera_1>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/max2175.txt b/Documentation/devicetree/bindings/media/i2c/maxim,max2175.txt
index 02b4e9cd7b1b..02b4e9cd7b1b 100644
--- a/Documentation/devicetree/bindings/media/i2c/max2175.txt
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max2175.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
index 02f656e78700..a37447256f8d 100644
--- a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
@@ -39,7 +39,7 @@ properties:
maxItems: 1
poc-supply:
- description: Regulator providing Power over Coax to the cameras
+ description: Regulator providing Power over Coax to all the ports
enable-gpios:
description: GPIO connected to the \#PWDN pin with inverted polarity
@@ -50,6 +50,21 @@ properties:
'#gpio-cells':
const: 2
+ maxim,bus-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [ 24, 27, 32 ]
+ description: |
+ The GMSL serial data bus width. This setting is normally controlled by
+ the BWS pin, but may be overridden with this property. The value must
+ match the configuration of the remote serializers.
+
+ maxim,i2c-remote-bus-hz:
+ enum: [ 8470, 28300, 84700, 105000, 173000, 339000, 533000, 837000 ]
+ default: 105000
+ description: |
+ The I2C clock frequency for the remote I2C buses. The value must match
+ the configuration of the remote serializers.
+
maxim,reverse-channel-microvolt:
minimum: 30000
maximum: 200000
@@ -70,6 +85,28 @@ properties:
a remote serializer whose high-threshold noise immunity is not enabled
is 100000 micro volts
+ maxim,gpio-poc:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 2
+ maxItems: 2
+ description: |
+ Index of the MAX9286 gpio output line (0 or 1) that controls Power over
+ Coax to the cameras and its associated polarity flag.
+
+ The property accepts an array of two unsigned integers, the first being
+ the gpio line index (0 or 1) and the second being the gpio line polarity
+ flag (GPIO_ACTIVE_HIGH or GPIO_ACTIVE_LOW) as defined in
+ <include/dt-bindings/gpio/gpio.h>.
+
+ When the remote cameras power is controlled by one of the MAX9286 gpio
+ lines, this property has to be used to specify which line among the two
+ available ones controls the remote camera power enablement.
+
+ When this property is used it is not possible to register a gpio
+ controller as the gpio lines are controlled directly by the MAX9286 and
+ not available for consumers, nor the 'poc-supply' property should be
+ specified.
+
ports:
$ref: /schemas/graph.yaml#/properties/ports
@@ -119,6 +156,7 @@ properties:
patternProperties:
"^i2c@[0-3]$":
type: object
+ additionalProperties: false
description: |
Child node of the i2c bus multiplexer which represents a GMSL link.
Each serializer device on the GMSL link remote end is represented with
@@ -130,6 +168,12 @@ properties:
description: The index of the GMSL channel.
maxItems: 1
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
patternProperties:
"^camera@[a-f0-9]+$":
type: object
@@ -160,12 +204,36 @@ properties:
additionalProperties: false
+patternProperties:
+ "^port[0-3]-poc-supply$":
+ description: Regulator providing Power over Coax for a particular port
+
required:
- compatible
- reg
- ports
- i2c-mux
- - gpio-controller
+
+allOf:
+ # Only one way of specifying power supplies is allowed: 'maxim,gpio-poc',
+ # 'poc-supply' or per-port poc-supply. Additionally, if 'maxim,gpio-poc' is
+ # present, then 'gpio-controller' isn't allowed.
+ - if:
+ required:
+ - maxim,gpio-poc
+ then:
+ properties:
+ poc-supply: false
+ gpio-controller: false
+ patternProperties:
+ "^port[0-3]-poc-supply$": false
+
+ - if:
+ required:
+ - poc-supply
+ then:
+ patternProperties:
+ "^port[0-3]-poc-supply$": false
additionalProperties: false
@@ -174,140 +242,175 @@ examples:
#include <dt-bindings/gpio/gpio.h>
i2c@e66d8000 {
- #address-cells = <1>;
- #size-cells = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
- reg = <0 0xe66d8000>;
+ reg = <0 0xe66d8000>;
- gmsl-deserializer@2c {
- compatible = "maxim,max9286";
- reg = <0x2c>;
- poc-supply = <&camera_poc_12v>;
- enable-gpios = <&gpio 13 GPIO_ACTIVE_HIGH>;
+ gmsl-deserializer@2c {
+ compatible = "maxim,max9286";
+ reg = <0x2c>;
+ poc-supply = <&camera_poc_12v>;
+ enable-gpios = <&gpio 13 GPIO_ACTIVE_HIGH>;
- gpio-controller;
- #gpio-cells = <2>;
+ gpio-controller;
+ #gpio-cells = <2>;
- maxim,reverse-channel-microvolt = <170000>;
+ maxim,i2c-remote-bus-hz = <339000>;
+ maxim,reverse-channel-microvolt = <170000>;
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
- port@0 {
- reg = <0>;
+ port@0 {
+ reg = <0>;
- max9286_in0: endpoint {
- remote-endpoint = <&rdacm20_out0>;
- };
- };
+ max9286_in0: endpoint {
+ remote-endpoint = <&rdacm20_out0>;
+ };
+ };
- port@1 {
- reg = <1>;
+ port@1 {
+ reg = <1>;
- max9286_in1: endpoint {
- remote-endpoint = <&rdacm20_out1>;
- };
- };
+ max9286_in1: endpoint {
+ remote-endpoint = <&rdacm20_out1>;
+ };
+ };
- port@2 {
- reg = <2>;
+ port@2 {
+ reg = <2>;
- max9286_in2: endpoint {
- remote-endpoint = <&rdacm20_out2>;
- };
- };
+ max9286_in2: endpoint {
+ remote-endpoint = <&rdacm20_out2>;
+ };
+ };
- port@3 {
- reg = <3>;
+ port@3 {
+ reg = <3>;
- max9286_in3: endpoint {
- remote-endpoint = <&rdacm20_out3>;
- };
- };
+ max9286_in3: endpoint {
+ remote-endpoint = <&rdacm20_out3>;
+ };
+ };
- port@4 {
- reg = <4>;
+ port@4 {
+ reg = <4>;
- max9286_out: endpoint {
- data-lanes = <1 2 3 4>;
- remote-endpoint = <&csi40_in>;
+ max9286_out: endpoint {
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&csi40_in>;
+ };
+ };
};
- };
- };
- i2c-mux {
- #address-cells = <1>;
- #size-cells = <0>;
+ i2c-mux {
+ #address-cells = <1>;
+ #size-cells = <0>;
- i2c@0 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0>;
+ i2c@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0>;
- camera@51 {
- compatible = "imi,rdacm20";
- reg = <0x51>, <0x61>;
+ camera@51 {
+ compatible = "imi,rdacm20";
+ reg = <0x51>, <0x61>;
- port {
- rdacm20_out0: endpoint {
- remote-endpoint = <&max9286_in0>;
- };
- };
+ port {
+ rdacm20_out0: endpoint {
+ remote-endpoint = <&max9286_in0>;
+ };
+ };
- };
- };
+ };
+ };
- i2c@1 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <1>;
+ i2c@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <1>;
+
+ camera@52 {
+ compatible = "imi,rdacm20";
+ reg = <0x52>, <0x62>;
+
+ port {
+ rdacm20_out1: endpoint {
+ remote-endpoint = <&max9286_in1>;
+ };
+ };
+ };
+ };
- camera@52 {
- compatible = "imi,rdacm20";
- reg = <0x52>, <0x62>;
+ i2c@2 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <2>;
+
+ camera@53 {
+ compatible = "imi,rdacm20";
+ reg = <0x53>, <0x63>;
+
+ port {
+ rdacm20_out2: endpoint {
+ remote-endpoint = <&max9286_in2>;
+ };
+ };
+ };
+ };
- port {
- rdacm20_out1: endpoint {
- remote-endpoint = <&max9286_in1>;
+ i2c@3 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <3>;
+
+ camera@54 {
+ compatible = "imi,rdacm20";
+ reg = <0x54>, <0x64>;
+
+ port {
+ rdacm20_out3: endpoint {
+ remote-endpoint = <&max9286_in3>;
+ };
+ };
+ };
};
- };
};
- };
-
- i2c@2 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <2>;
-
- camera@53 {
- compatible = "imi,rdacm20";
- reg = <0x53>, <0x63>;
+ };
- port {
- rdacm20_out2: endpoint {
- remote-endpoint = <&max9286_in2>;
+ /*
+ * Example of a deserializer that controls the camera Power over Coax
+ * through one of its gpio lines.
+ */
+ gmsl-deserializer@6c {
+ compatible = "maxim,max9286";
+ reg = <0x6c>;
+ enable-gpios = <&gpio 14 GPIO_ACTIVE_HIGH>;
+
+ /*
+ * The remote camera power is controlled by MAX9286 GPIO line #0.
+ * No 'poc-supply' nor 'gpio-controller' are specified.
+ */
+ maxim,gpio-poc = <0 GPIO_ACTIVE_LOW>;
+
+ /*
+ * Do not describe connections as they're the same as in the previous
+ * example.
+ */
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@4 {
+ reg = <4>;
};
- };
};
- };
-
- i2c@3 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <3>;
- camera@54 {
- compatible = "imi,rdacm20";
- reg = <0x54>, <0x64>;
-
- port {
- rdacm20_out3: endpoint {
- remote-endpoint = <&max9286_in3>;
- };
- };
+ i2c-mux {
+ #address-cells = <1>;
+ #size-cells = <0>;
};
- };
};
- };
};
diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml
new file mode 100644
index 000000000000..26f85151afbd
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max96712.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2021 Renesas Electronics Corp.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/maxim,max96712.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Quad GMSL2 to CSI-2 Deserializer with GMSL1 Compatibility
+
+maintainers:
+ - Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
+
+description: |
+ The MAX96712 deserializer converts GMSL2 or GMSL1 serial inputs into MIPI
+ CSI-2 D-PHY or C-PHY formatted outputs. The device allows each link to
+ simultaneously transmit bidirectional control-channel data while forward
+ video transmissions are in progress. The MAX96712 can accommodate as many as
+ four remotely located sensors using industry-standard coax or STP
+ interconnects.
+
+ Each GMSL2 serial link operates at a fixed rate of 3Gbps or 6Gbps in the
+ forward direction and 187.5Mbps in the reverse direction. In GMSL1 mode, the
+ MAX96712 can be paired with first-generation 3.12Gbps or 1.5Gbps GMSL1
+ serializers or operate up to 3.12Gbps with GMSL2 serializers in GMSL1 mode.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - maxim,max96712
+ - maxim,max96724
+
+ reg:
+ description: I2C device address
+ maxItems: 1
+
+ enable-gpios: true
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: GMSL Input 0
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: GMSL Input 1
+
+ port@2:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: GMSL Input 2
+
+ port@3:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: GMSL Input 3
+
+ port@4:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 Output
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes: true
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+ - bus-type
+
+ required:
+ - port@4
+
+required:
+ - compatible
+ - reg
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c@e6508000 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0 0xe6508000>;
+
+ gmsl0: gmsl-deserializer@49 {
+ compatible = "maxim,max96712";
+ reg = <0x49>;
+ enable-gpios = <&pca9654_a 0 GPIO_ACTIVE_HIGH>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@4 {
+ reg = <4>;
+ max96712_out0: endpoint {
+ bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>;
+ clock-lanes = <0>;
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&csi40_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max96714.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max96714.yaml
new file mode 100644
index 000000000000..3ace50e11921
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max96714.yaml
@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2024 Collabora Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/maxim,max96714.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Maxim MAX96714 GMSL2 to CSI-2 Deserializer
+
+maintainers:
+ - Julien Massot <julien.massot@collabora.com>
+
+description:
+ The MAX96714 deserializer converts GMSL2 serial inputs into MIPI
+ CSI-2 D-PHY formatted output. The device allows the GMSL2 link to
+ simultaneously transmit bidirectional control-channel data while forward
+ video transmissions are in progress. The MAX96714 can connect to one
+ remotely located serializer using industry-standard coax or STP
+ interconnects. The device cans operate in pixel or tunnel mode. In pixel mode
+ the MAX96714 can select individual video stream, while the tunnel mode forward all
+ the MIPI data received by the serializer.
+
+ The GMSL2 serial link operates at a fixed rate of 3Gbps or 6Gbps in the
+ forward direction and 187.5Mbps in the reverse direction.
+ MAX96714F only supports a fixed rate of 3Gbps in the forward direction.
+
+properties:
+ compatible:
+ oneOf:
+ - const: maxim,max96714f
+ - items:
+ - enum:
+ - maxim,max96714
+ - const: maxim,max96714f
+
+ reg:
+ maxItems: 1
+
+ powerdown-gpios:
+ maxItems: 1
+ description:
+ Specifier for the GPIO connected to the PWDNB pin.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port
+ unevaluatedProperties: false
+ description: GMSL Input
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+ description:
+ Endpoint for GMSL2-Link port.
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 Output port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ lane-polarities:
+ minItems: 1
+ maxItems: 5
+
+ link-frequencies:
+ maxItems: 1
+
+ required:
+ - data-lanes
+
+ required:
+ - port@1
+
+ i2c-gate:
+ $ref: /schemas/i2c/i2c-gate.yaml
+ unevaluatedProperties: false
+ description:
+ The MAX96714 will pass through and forward the I2C requests from the
+ incoming I2C bus over the GMSL2 link. Therefore it supports an i2c-gate
+ subnode to configure a serializer.
+
+ port0-poc-supply:
+ description: Regulator providing Power over Coax for the GMSL port
+
+required:
+ - compatible
+ - reg
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ deserializer@28 {
+ compatible = "maxim,max96714f";
+ reg = <0x28>;
+ powerdown-gpios = <&main_gpio0 37 GPIO_ACTIVE_LOW>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ port@0 {
+ reg = <0>;
+ max96714_gmsl_in: endpoint {
+ remote-endpoint = <&max96917f_gmsl_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ max96714_csi_out: endpoint {
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <400000000>;
+ remote-endpoint = <&csi_in>;
+ };
+ };
+ };
+
+ i2c-gate {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ serializer@40 {
+ compatible = "maxim,max96717f";
+ reg = <0x40>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ max96717f_csi_in: endpoint {
+ data-lanes = <1 2>;
+ lane-polarities = <1 0 1>;
+ remote-endpoint = <&sensor_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ max96917f_gmsl_out: endpoint {
+ remote-endpoint = <&max96714_gmsl_in>;
+ };
+ };
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max96717.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max96717.yaml
new file mode 100644
index 000000000000..d1e8ba6e368e
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max96717.yaml
@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2024 Collabora Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/maxim,max96717.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MAX96717 CSI-2 to GMSL2 Serializer
+
+maintainers:
+ - Julien Massot <julien.massot@collabora.com>
+
+description:
+ The MAX96717 serializer converts MIPI CSI-2 D-PHY formatted input
+ into GMSL2 serial outputs. The device allows the GMSL2 link to
+ simultaneously transmit bidirectional control-channel data while forward
+ video transmissions are in progress. The MAX96717 can connect to one
+ remotely located deserializer using industry-standard coax or STP
+ interconnects. The device cans operate in pixel or tunnel mode. In pixel mode
+ the MAX96717 can select the MIPI datatype, while the tunnel mode forward all the MIPI
+ data received by the serializer.
+ The MAX96717 supports Reference Over Reverse (channel),
+ to generate a clock output for the sensor from the GMSL reverse channel.
+
+ The GMSL2 serial link operates at a fixed rate of 3Gbps or 6Gbps in the
+ forward direction and 187.5Mbps in the reverse direction.
+ MAX96717F only supports a fixed rate of 3Gbps in the forward direction.
+
+properties:
+ compatible:
+ oneOf:
+ - const: maxim,max96717f
+ - items:
+ - enum:
+ - maxim,max96717
+ - const: maxim,max96717f
+
+ '#gpio-cells':
+ const: 2
+ description:
+ First cell is the GPIO pin number, second cell is the flags. The GPIO pin
+ number must be in range of [0, 10].
+
+ gpio-controller: true
+
+ '#clock-cells':
+ const: 0
+
+ reg:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 Input port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ lane-polarities:
+ minItems: 1
+ maxItems: 5
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ unevaluatedProperties: false
+ description: GMSL Output port
+
+ required:
+ - port@1
+
+ i2c-gate:
+ $ref: /schemas/i2c/i2c-gate.yaml
+ unevaluatedProperties: false
+ description:
+ The MAX96717 will forward the I2C requests from the
+ incoming GMSL2 link. Therefore, it supports an i2c-gate
+ subnode to configure a sensor.
+
+required:
+ - compatible
+ - reg
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ serializer: serializer@40 {
+ compatible = "maxim,max96717f";
+ reg = <0x40>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ max96717f_csi_in: endpoint {
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&sensor_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ max96917f_gmsl_out: endpoint {
+ remote-endpoint = <&deser_gmsl_in>;
+ };
+ };
+ };
+
+ i2c-gate {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ sensor@10 {
+ compatible = "st,st-vgxy61";
+ reg = <0x10>;
+ reset-gpios = <&serializer 0 GPIO_ACTIVE_LOW>;
+ clocks = <&serializer>;
+ VCORE-supply = <&v1v2>;
+ VDDIO-supply = <&v1v8>;
+ VANA-supply = <&v2v8>;
+ port {
+ sensor_out: endpoint {
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&max96717f_csi_in>;
+ };
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt b/Documentation/devicetree/bindings/media/i2c/micron,mt9m111.txt
index d0bed6fa901a..d0bed6fa901a 100644
--- a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt
+++ b/Documentation/devicetree/bindings/media/i2c/micron,mt9m111.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml
index 701f4e0d138f..217b08c8cbbd 100644
--- a/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml
@@ -23,6 +23,9 @@ description:
More detailed documentation can be found in
Documentation/devicetree/bindings/media/video-interfaces.txt .
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
properties:
compatible:
oneOf:
@@ -52,22 +55,17 @@ properties:
clock-frequency:
description: Frequency of the external clock to the sensor in Hz.
+ deprecated: true
reset-gpios:
description: Reset GPIO. Also commonly called XSHUTDOWN in hardware
documentation.
maxItems: 1
- flash-leds:
- description: Flash LED phandles. See ../video-interfaces.txt for details.
-
- lens-focus:
- description: Lens focus controller phandles. See ../video-interfaces.txt
- for details.
+ flash-leds: true
+ lens-focus: true
rotation:
- description: Rotation of the sensor. See ../video-interfaces.txt for
- details.
enum: [ 0, 180 ]
port:
@@ -83,10 +81,10 @@ properties:
link-frequencies: true
data-lanes: true
bus-type:
- oneOf:
- - const: 1 # CSI-2 C-PHY
- - const: 3 # CCP2
- - const: 4 # CSI-2 D-PHY
+ enum:
+ - 1 # CSI-2 C-PHY
+ - 3 # CCP2
+ - 4 # CSI-2 D-PHY
required:
- link-frequencies
@@ -96,7 +94,6 @@ properties:
required:
- compatible
- reg
- - clock-frequency
- clocks
additionalProperties: false
@@ -104,8 +101,9 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
- i2c2 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -116,15 +114,18 @@ examples:
reg = <0x10>;
reset-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>;
vana-supply = <&vaux3>;
+
clocks = <&omap3_isp 0>;
- clock-frequency = <9600000>;
+ assigned-clocks = <&omap3_isp 0>;
+ assigned-clock-rates = <9600000>;
+
port {
ccs_ep: endpoint {
data-lanes = <1 2>;
remote-endpoint = <&csi2a_ep>;
link-frequencies = /bits/ 64 <199200000 210000000
499200000>;
- bus-type = <4>;
+ bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>;
};
};
};
diff --git a/Documentation/devicetree/bindings/media/i2c/mt9p031.txt b/Documentation/devicetree/bindings/media/i2c/mt9p031.txt
deleted file mode 100644
index cb60443ff78f..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/mt9p031.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-* Aptina 1/2.5-Inch 5Mp CMOS Digital Image Sensor
-
-The Aptina MT9P031 is a 1/2.5-inch CMOS active pixel digital image sensor with
-an active array size of 2592H x 1944V. It is programmable through a simple
-two-wire serial interface.
-
-Required Properties:
-- compatible: value should be either one among the following
- (a) "aptina,mt9p031" for mt9p031 sensor
- (b) "aptina,mt9p031m" for mt9p031m sensor
-
-- input-clock-frequency: Input clock frequency.
-
-- pixel-clock-frequency: Pixel clock frequency.
-
-Optional Properties:
-- reset-gpios: Chip reset GPIO
-
-For further reading on port node refer to
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-Example:
-
- i2c0@1c22000 {
- ...
- ...
- mt9p031@5d {
- compatible = "aptina,mt9p031";
- reg = <0x5d>;
- reset-gpios = <&gpio3 30 0>;
-
- port {
- mt9p031_1: endpoint {
- input-clock-frequency = <6000000>;
- pixel-clock-frequency = <96000000>;
- };
- };
- };
- ...
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/nxp,tda19971.yaml b/Documentation/devicetree/bindings/media/i2c/nxp,tda19971.yaml
new file mode 100644
index 000000000000..477e59316dfa
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/nxp,tda19971.yaml
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/nxp,tda19971.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP TDA1997x HDMI receiver
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description: |
+ The TDA19971/73 are HDMI video receivers.
+
+ The TDA19971 Video port output pins can be used as follows:
+ - RGB 8bit per color (24 bits total): R[11:4] B[11:4] G[11:4]
+ - YUV444 8bit per color (24 bits total): Y[11:4] Cr[11:4] Cb[11:4]
+ - YUV422 semi-planar 8bit per component (16 bits total): Y[11:4] CbCr[11:4]
+ - YUV422 semi-planar 10bit per component (20 bits total): Y[11:2] CbCr[11:2]
+ - YUV422 semi-planar 12bit per component (24 bits total): - Y[11:0] CbCr[11:0]
+ - YUV422 BT656 8bit per component (8 bits total): YCbCr[11:4] (2-cycles)
+ - YUV422 BT656 10bit per component (10 bits total): YCbCr[11:2] (2-cycles)
+ - YUV422 BT656 12bit per component (12 bits total): YCbCr[11:0] (2-cycles)
+
+ The TDA19973 Video port output pins can be used as follows:
+ - RGB 12bit per color (36 bits total): R[11:0] B[11:0] G[11:0]
+ - YUV444 12bit per color (36 bits total): Y[11:0] Cb[11:0] Cr[11:0]
+ - YUV422 semi-planar 12bit per component (24 bits total): Y[11:0] CbCr[11:0]
+ - YUV422 BT656 12bit per component (12 bits total): YCbCr[11:0] (2-cycles)
+
+ The Video port output pins are mapped via 4-bit 'pin groups' allowing
+ for a variety of connection possibilities including swapping pin order within
+ pin groups. The video_portcfg device-tree property consists of register mapping
+ pairs which map a chip-specific VP output register to a 4-bit pin group. If
+ the pin group needs to be bit-swapped you can use the *_S pin-group defines.
+
+properties:
+ compatible:
+ enum:
+ - nxp,tda19971
+ - nxp,tda19973
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ DOVDD-supply: true
+
+ DVDD-supply: true
+
+ AVDD-supply: true
+
+ '#sound-dai-cells':
+ const: 0
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ nxp,vidout-portcfg:
+ $ref: /schemas/types.yaml#/definitions/uint32-matrix
+ minItems: 1
+ maxItems: 4
+ items:
+ items:
+ - description: Video Port control registers index.
+ maximum: 8
+ minimum: 0
+ - description: pin(pinswapped) groups
+
+ description:
+ array of pairs mapping VP output pins to pin groups.
+
+ nxp,audout-format:
+ enum:
+ - i2s
+ - spdif
+
+ nxp,audout-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [8, 16, 24, 32]
+ description:
+ width of audio output data bus.
+
+ nxp,audout-layout:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [0, 1]
+ description:
+ data layout (0=AP0 used, 1=AP0/AP1/AP2/AP3 used).
+
+ nxp,audout-mclk-fs:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Multiplication factor between stream rate and codec mclk.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - DOVDD-supply
+ - AVDD-supply
+ - DVDD-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/media/tda1997x.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ hdmi-receiver@48 {
+ compatible = "nxp,tda19971";
+ reg = <0x48>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_tda1997x>;
+ interrupt-parent = <&gpio1>;
+ interrupts = <7 IRQ_TYPE_LEVEL_LOW>;
+ DOVDD-supply = <&reg_3p3v>;
+ AVDD-supply = <&reg_1p8v>;
+ DVDD-supply = <&reg_1p8v>;
+ /* audio */
+ #sound-dai-cells = <0>;
+ nxp,audout-format = "i2s";
+ nxp,audout-layout = <0>;
+ nxp,audout-width = <16>;
+ nxp,audout-mclk-fs = <128>;
+ /*
+ * The 8bpp YUV422 semi-planar mode outputs CbCr[11:4]
+ * and Y[11:4] across 16bits in the same pixclk cycle.
+ */
+ nxp,vidout-portcfg =
+ /* Y[11:8]<->VP[15:12]<->CSI_DATA[19:16] */
+ < TDA1997X_VP24_V15_12 TDA1997X_G_Y_11_8 >,
+ /* Y[7:4]<->VP[11:08]<->CSI_DATA[15:12] */
+ < TDA1997X_VP24_V11_08 TDA1997X_G_Y_7_4 >,
+ /* CbCc[11:8]<->VP[07:04]<->CSI_DATA[11:8] */
+ < TDA1997X_VP24_V07_04 TDA1997X_R_CR_CBCR_11_8 >,
+ /* CbCr[7:4]<->VP[03:00]<->CSI_DATA[7:4] */
+ < TDA1997X_VP24_V03_00 TDA1997X_R_CR_CBCR_7_4 >;
+
+ port {
+ endpoint {
+ remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>;
+ bus-width = <16>;
+ hsync-active = <1>;
+ vsync-active = <1>;
+ data-active = <1>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/onnn,ar0521.yaml b/Documentation/devicetree/bindings/media/i2c/onnn,ar0521.yaml
new file mode 100644
index 000000000000..b617cc5c6a9f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/onnn,ar0521.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/onnn,ar0521.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ON Semiconductor AR0521 MIPI CSI-2 sensor
+
+maintainers:
+ - Krzysztof Hałasa <khalasa@piap.pl>
+
+description: |-
+ The AR0521 is a raw CMOS image sensor with MIPI CSI-2 and
+ I2C-compatible control interface.
+
+properties:
+ compatible:
+ const: onnn,ar0521
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: extclk
+
+ vaa-supply:
+ description:
+ Definition of the regulator used as analog (2.7 V) voltage supply.
+
+ vdd-supply:
+ description:
+ Definition of the regulator used as digital core (1.2 V) voltage supply.
+
+ vdd_io-supply:
+ description:
+ Definition of the regulator used as digital I/O (1.8 V) voltage supply.
+
+ reset-gpios:
+ description: reset GPIO, usually active low
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: |
+ Video output port.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ const: 4
+ data-lanes:
+ anyOf:
+ - items:
+ - const: 1
+ - items:
+ - const: 1
+ - const: 2
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - vaa-supply
+ - vdd-supply
+ - vdd_io-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/clock/imx6qdl-clock.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ar0521: camera-sensor@36 {
+ compatible = "onnn,ar0521";
+ reg = <0x36>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_mipi_camera>;
+ clocks = <&clks IMX6QDL_CLK_CKO>;
+ clock-names = "extclk";
+ reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>;
+ vaa-supply = <&reg_2p7v>;
+ vdd-supply = <&reg_1p2v>;
+ vdd_io-supply = <&reg_1p8v>;
+
+ port {
+ mipi_camera_to_mipi_csi2: endpoint {
+ remote-endpoint = <&mipi_csi2_in>;
+ data-lanes = <1 2 3 4>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/mt9m001.txt b/Documentation/devicetree/bindings/media/i2c/onnn,mt9m001.txt
index c920552b03ef..c920552b03ef 100644
--- a/Documentation/devicetree/bindings/media/i2c/mt9m001.txt
+++ b/Documentation/devicetree/bindings/media/i2c/onnn,mt9m001.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml b/Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml
new file mode 100644
index 000000000000..a89f740214f7
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml
@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/onnn,mt9m114.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: onsemi 1/6-inch 720p CMOS Digital Image Sensor
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |-
+ The onsemi MT9M114 is a 1/6-inch 720p (1.26 Mp) CMOS digital image sensor
+ with an active pixel-array size of 1296H x 976V. It is programmable through
+ an I2C interface and outputs image data over a 8-bit parallel or 1-lane MIPI
+ CSI-2 connection.
+
+properties:
+ compatible:
+ const: onnn,mt9m114
+
+ reg:
+ description: I2C device address
+ enum:
+ - 0x48
+ - 0x5d
+
+ clocks:
+ description: EXTCLK clock signal
+ maxItems: 1
+
+ vdd-supply:
+ description:
+ Core digital voltage supply, 1.8V
+
+ vddio-supply:
+ description:
+ I/O digital voltage supply, 1.8V or 2.8V
+
+ vaa-supply:
+ description:
+ Analog voltage supply, 2.8V
+
+ reset-gpios:
+ description: |-
+ Reference to the GPIO connected to the RESET_BAR pin, if any (active
+ low).
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ bus-type:
+ enum: [4, 5, 6]
+
+ link-frequencies: true
+ remote-endpoint: true
+
+ # The number and mapping of lanes (for CSI-2), and the bus width and
+ # signal polarities (for parallel and BT.656) are fixed and must not
+ # be specified.
+
+ required:
+ - bus-type
+ - link-frequencies
+
+ slew-rate:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Slew rate ot the output pads DOUT[7:0], LINE_VALID, FRAME_VALID and
+ PIXCLK. Higher values imply steeper voltage-flanks on the pads.
+ minimum: 0
+ maximum: 7
+ default: 7
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vdd-supply
+ - vddio-supply
+ - vaa-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@48 {
+ compatible = "onnn,mt9m114";
+ reg = <0x48>;
+
+ clocks = <&clk24m 0>;
+
+ reset-gpios = <&gpio5 21 GPIO_ACTIVE_LOW>;
+
+ vddio-supply = <&reg_cam_1v8>;
+ vdd-supply = <&reg_cam_1v8>;
+ vaa-supply = <&reg_2p8v>;
+
+ port {
+ endpoint {
+ bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>;
+ link-frequencies = /bits/ 64 <384000000>;
+ remote-endpoint = <&mipi_csi_in>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ov2685.txt b/Documentation/devicetree/bindings/media/i2c/ov2685.txt
deleted file mode 100644
index 625c4a8c0d53..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ov2685.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-* Omnivision OV2685 MIPI CSI-2 sensor
-
-Required Properties:
-- compatible: shall be "ovti,ov2685"
-- clocks: reference to the xvclk input clock
-- clock-names: shall be "xvclk"
-- avdd-supply: Analog voltage supply, 2.8 volts
-- dovdd-supply: Digital I/O voltage supply, 1.8 volts
-- dvdd-supply: Digital core voltage supply, 1.8 volts
-- reset-gpios: Low active reset gpio
-
-The device node shall contain one 'port' child node with an
-'endpoint' subnode for its digital output video port,
-in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-The endpoint optional property 'data-lanes' shall be "<1>".
-
-Example:
-&i2c7 {
- ov2685: camera-sensor@3c {
- compatible = "ovti,ov2685";
- reg = <0x3c>;
- pinctrl-names = "default";
- pinctrl-0 = <&clk_24m_cam>;
-
- clocks = <&cru SCLK_TESTCLKOUT1>;
- clock-names = "xvclk";
-
- avdd-supply = <&pp2800_cam>;
- dovdd-supply = <&pp1800>;
- dvdd-supply = <&pp1800>;
- reset-gpios = <&gpio2 3 GPIO_ACTIVE_LOW>;
-
- port {
- ucam_out: endpoint {
- remote-endpoint = <&mipi_in_ucam>;
- data-lanes = <1>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/i2c/ov5640.txt b/Documentation/devicetree/bindings/media/i2c/ov5640.txt
deleted file mode 100644
index c97c2f2da12d..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ov5640.txt
+++ /dev/null
@@ -1,92 +0,0 @@
-* Omnivision OV5640 MIPI CSI-2 / parallel sensor
-
-Required Properties:
-- compatible: should be "ovti,ov5640"
-- clocks: reference to the xclk input clock.
-- clock-names: should be "xclk".
-- DOVDD-supply: Digital I/O voltage supply, 1.8 volts
-- AVDD-supply: Analog voltage supply, 2.8 volts
-- DVDD-supply: Digital core voltage supply, 1.5 volts
-
-Optional Properties:
-- reset-gpios: reference to the GPIO connected to the reset pin, if any.
- This is an active low signal to the OV5640.
-- powerdown-gpios: reference to the GPIO connected to the powerdown pin,
- if any. This is an active high signal to the OV5640.
-- rotation: as defined in
- Documentation/devicetree/bindings/media/video-interfaces.txt,
- valid values are 0 (sensor mounted upright) and 180 (sensor
- mounted upside down).
-
-The device node must contain one 'port' child node for its digital output
-video port, in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-OV5640 can be connected to a MIPI CSI-2 bus or a parallel bus endpoint.
-
-Endpoint node required properties for CSI-2 connection are:
-- remote-endpoint: a phandle to the bus receiver's endpoint node.
-- clock-lanes: should be set to <0> (clock lane on hardware lane 0)
-- data-lanes: should be set to <1> or <1 2> (one or two CSI-2 lanes supported)
-
-Endpoint node required properties for parallel connection are:
-- remote-endpoint: a phandle to the bus receiver's endpoint node.
-- bus-width: shall be set to <8> for 8 bits parallel bus
- or <10> for 10 bits parallel bus
-- data-shift: shall be set to <2> for 8 bits parallel bus
- (lines 9:2 are used) or <0> for 10 bits parallel bus
-- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
-- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively.
-- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock
- signal.
-
-Examples:
-
-&i2c1 {
- ov5640: camera@3c {
- compatible = "ovti,ov5640";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_ov5640>;
- reg = <0x3c>;
- clocks = <&clks IMX6QDL_CLK_CKO>;
- clock-names = "xclk";
- DOVDD-supply = <&vgen4_reg>; /* 1.8v */
- AVDD-supply = <&vgen3_reg>; /* 2.8v */
- DVDD-supply = <&vgen2_reg>; /* 1.5v */
- powerdown-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>;
- reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>;
- rotation = <180>;
-
- port {
- /* MIPI CSI-2 bus endpoint */
- ov5640_to_mipi_csi2: endpoint {
- remote-endpoint = <&mipi_csi2_from_ov5640>;
- clock-lanes = <0>;
- data-lanes = <1 2>;
- };
- };
- };
-};
-
-&i2c1 {
- ov5640: camera@3c {
- compatible = "ovti,ov5640";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_ov5640>;
- reg = <0x3c>;
- clocks = <&clk_ext_camera>;
- clock-names = "xclk";
-
- port {
- /* Parallel bus endpoint */
- ov5640_to_parallel: endpoint {
- remote-endpoint = <&parallel_from_ov5640>;
- bus-width = <8>;
- data-shift = <2>; /* lines 9:2 are used */
- hsync-active = <0>;
- vsync-active = <0>;
- pclk-sample = <1>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/i2c/ov5645.txt b/Documentation/devicetree/bindings/media/i2c/ov5645.txt
deleted file mode 100644
index 72ad992f77be..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ov5645.txt
+++ /dev/null
@@ -1,54 +0,0 @@
-* Omnivision 1/4-Inch 5Mp CMOS Digital Image Sensor
-
-The Omnivision OV5645 is a 1/4-Inch CMOS active pixel digital image sensor with
-an active array size of 2592H x 1944V. It is programmable through a serial I2C
-interface.
-
-Required Properties:
-- compatible: Value should be "ovti,ov5645".
-- clocks: Reference to the xclk clock.
-- clock-names: Should be "xclk".
-- clock-frequency: Frequency of the xclk clock.
-- enable-gpios: Chip enable GPIO. Polarity is GPIO_ACTIVE_HIGH. This corresponds
- to the hardware pin PWDNB which is physically active low.
-- reset-gpios: Chip reset GPIO. Polarity is GPIO_ACTIVE_LOW. This corresponds to
- the hardware pin RESETB.
-- vdddo-supply: Chip digital IO regulator.
-- vdda-supply: Chip analog regulator.
-- vddd-supply: Chip digital core regulator.
-
-The device node must contain one 'port' child node for its digital output
-video port, in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-Example:
-
- &i2c1 {
- ...
-
- ov5645: ov5645@3c {
- compatible = "ovti,ov5645";
- reg = <0x3c>;
-
- enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>;
- reset-gpios = <&gpio5 20 GPIO_ACTIVE_LOW>;
- pinctrl-names = "default";
- pinctrl-0 = <&camera_rear_default>;
-
- clocks = <&clks 200>;
- clock-names = "xclk";
- clock-frequency = <24000000>;
-
- vdddo-supply = <&camera_dovdd_1v8>;
- vdda-supply = <&camera_avdd_2v8>;
- vddd-supply = <&camera_dvdd_1v2>;
-
- port {
- ov5645_ep: endpoint {
- clock-lanes = <1>;
- data-lanes = <0 2>;
- remote-endpoint = <&csi0_ep>;
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/ov5695.txt b/Documentation/devicetree/bindings/media/i2c/ov5695.txt
deleted file mode 100644
index 640a63717d96..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ov5695.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-* Omnivision OV5695 MIPI CSI-2 sensor
-
-Required Properties:
-- compatible: shall be "ovti,ov5695"
-- clocks: reference to the xvclk input clock
-- clock-names: shall be "xvclk"
-- avdd-supply: Analog voltage supply, 2.8 volts
-- dovdd-supply: Digital I/O voltage supply, 1.8 volts
-- dvdd-supply: Digital core voltage supply, 1.2 volts
-- reset-gpios: Low active reset gpio
-
-The device node shall contain one 'port' child node with an
-'endpoint' subnode for its digital output video port,
-in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-The endpoint optional property 'data-lanes' shall be "<1 2>".
-
-Example:
-&i2c7 {
- ov5695: camera-sensor@36 {
- compatible = "ovti,ov5695";
- reg = <0x36>;
- pinctrl-names = "default";
- pinctrl-0 = <&clk_24m_cam>;
-
- clocks = <&cru SCLK_TESTCLKOUT1>;
- clock-names = "xvclk";
-
- avdd-supply = <&pp2800_cam>;
- dovdd-supply = <&pp1800>;
- dvdd-supply = <&pp1250_cam>;
- reset-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>;
-
- port {
- wcam_out: endpoint {
- remote-endpoint = <&mipi_in_wcam>;
- data-lanes = <1 2>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/i2c/ov7251.txt b/Documentation/devicetree/bindings/media/i2c/ov7251.txt
deleted file mode 100644
index 8281151f7493..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ov7251.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-* Omnivision 1/7.5-Inch B&W VGA CMOS Digital Image Sensor
-
-The Omnivision OV7251 is a 1/7.5-Inch CMOS active pixel digital image sensor
-with an active array size of 640H x 480V. It is programmable through a serial
-I2C interface.
-
-Required Properties:
-- compatible: Value should be "ovti,ov7251".
-- clocks: Reference to the xclk clock.
-- clock-names: Should be "xclk".
-- clock-frequency: Frequency of the xclk clock.
-- enable-gpios: Chip enable GPIO. Polarity is GPIO_ACTIVE_HIGH. This corresponds
- to the hardware pin XSHUTDOWN which is physically active low.
-- vdddo-supply: Chip digital IO regulator.
-- vdda-supply: Chip analog regulator.
-- vddd-supply: Chip digital core regulator.
-
-The device node shall contain one 'port' child node with a single 'endpoint'
-subnode for its digital output video port, in accordance with the video
-interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-Example:
-
- &i2c1 {
- ...
-
- ov7251: camera-sensor@60 {
- compatible = "ovti,ov7251";
- reg = <0x60>;
-
- enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>;
- pinctrl-names = "default";
- pinctrl-0 = <&camera_bw_default>;
-
- clocks = <&clks 200>;
- clock-names = "xclk";
- clock-frequency = <24000000>;
-
- vdddo-supply = <&camera_dovdd_1v8>;
- vdda-supply = <&camera_avdd_2v8>;
- vddd-supply = <&camera_dvdd_1v2>;
-
- port {
- ov7251_ep: endpoint {
- clock-lanes = <1>;
- data-lanes = <0>;
- remote-endpoint = <&csi0_ep>;
- };
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/ov8856.yaml b/Documentation/devicetree/bindings/media/i2c/ov8856.yaml
deleted file mode 100644
index baf92aaaf049..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/ov8856.yaml
+++ /dev/null
@@ -1,134 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-# Copyright (c) 2019 MediaTek Inc.
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/media/i2c/ov8856.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: Omnivision OV8856 CMOS Sensor Device Tree Bindings
-
-maintainers:
- - Dongchun Zhu <dongchun.zhu@mediatek.com>
-
-description: |-
- The Omnivision OV8856 is a high performance, 1/4-inch, 8 megapixel, CMOS
- image sensor that delivers 3264x2448 at 30fps. It provides full-frame,
- sub-sampled, and windowed 10-bit MIPI images in various formats via the
- Serial Camera Control Bus (SCCB) interface. This chip is programmable
- through I2C and two-wire SCCB. The sensor output is available via CSI-2
- serial data output (up to 4-lane).
-
-properties:
- compatible:
- const: ovti,ov8856
-
- reg:
- maxItems: 1
-
- clocks:
- maxItems: 1
-
- clock-names:
- description:
- Input clock for the sensor.
- items:
- - const: xvclk
-
- clock-frequency:
- description:
- Frequency of the xvclk clock in Hertz.
-
- dovdd-supply:
- description:
- Definition of the regulator used as interface power supply.
-
- avdd-supply:
- description:
- Definition of the regulator used as analog power supply.
-
- dvdd-supply:
- description:
- Definition of the regulator used as digital power supply.
-
- reset-gpios:
- description:
- The phandle and specifier for the GPIO that controls sensor reset.
- This corresponds to the hardware pin XSHUTDOWN which is physically
- active low.
-
- port:
- $ref: /schemas/graph.yaml#/$defs/port-base
- additionalProperties: false
-
- properties:
- endpoint:
- $ref: /schemas/media/video-interfaces.yaml#
- unevaluatedProperties: false
-
- properties:
- data-lanes:
- description: |-
- The driver only supports four-lane operation.
- items:
- - const: 1
- - const: 2
- - const: 3
- - const: 4
-
- link-frequencies:
- description: Frequencies listed are driver, not h/w limitations.
- maxItems: 2
- items:
- enum: [ 360000000, 180000000 ]
-
- required:
- - link-frequencies
-
-required:
- - compatible
- - reg
- - clocks
- - clock-names
- - clock-frequency
- - dovdd-supply
- - avdd-supply
- - dvdd-supply
- - reset-gpios
- - port
-
-additionalProperties: false
-
-examples:
- - |
- #include <dt-bindings/gpio/gpio.h>
-
- i2c {
- #address-cells = <1>;
- #size-cells = <0>;
-
- ov8856: camera@10 {
- compatible = "ovti,ov8856";
- reg = <0x10>;
-
- reset-gpios = <&pio 111 GPIO_ACTIVE_LOW>;
- pinctrl-names = "default";
- pinctrl-0 = <&clk_24m_cam>;
-
- clocks = <&cam_osc>;
- clock-names = "xvclk";
- clock-frequency = <19200000>;
-
- avdd-supply = <&mt6358_vcama2_reg>;
- dvdd-supply = <&mt6358_vcamd_reg>;
- dovdd-supply = <&mt6358_vcamio_reg>;
-
- port {
- wcam_out: endpoint {
- remote-endpoint = <&mipi_in_wcam>;
- data-lanes = <1 2 3 4>;
- link-frequencies = /bits/ 64 <360000000>;
- };
- };
- };
- };
-...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,og01a1b.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,og01a1b.yaml
new file mode 100644
index 000000000000..ca57c01739d2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,og01a1b.yaml
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2023-2024 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,og01a1b.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OG01A1B Image Sensor
+
+maintainers:
+ - Vladimir Zapolskiy <vladimir.zapolskiy@linaro.org>
+
+description:
+ The OmniVision OG01A1B is black and white CMOS 1.3 Megapixel (1280x1024)
+ image sensor controlled over an I2C-compatible SCCB bus.
+ The sensor transmits images on a MIPI CSI-2 output interface with one or
+ two data lanes.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,og01a1b
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ reset-gpios:
+ description: Active low GPIO connected to XSHUTDOWN pad of the sensor.
+ maxItems: 1
+
+ strobe-gpios:
+ description: Input GPIO connected to strobe pad of the sensor.
+ maxItems: 1
+
+ avdd-supply:
+ description: Analogue circuit voltage supply.
+
+ dovdd-supply:
+ description: I/O circuit voltage supply.
+
+ dvdd-supply:
+ description: Digital circuit voltage supply.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+ description:
+ Output port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [1, 2]
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@60 {
+ compatible = "ovti,og01a1b";
+ reg = <0x60>;
+ clocks = <&clk 0>;
+ reset-gpios = <&gpio 117 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&vreg_3v3>;
+ dovdd-supply = <&vreg_1p8>;
+ dvdd-supply = <&vreg_1p2>;
+
+ port {
+ og01a1b_ep: endpoint {
+ remote-endpoint = <&csiphy_ep>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <500000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,og0ve1b.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,og0ve1b.yaml
new file mode 100644
index 000000000000..bd2f1ae23e65
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,og0ve1b.yaml
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,og0ve1b.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OG0VE1B Image Sensor
+
+description:
+ OmniVision OG0VE1B image sensor is a low power consuming monochrome
+ image sensor. The sensor is controlled over a serial camera control
+ bus protocol (SCCB), the widest supported image size is 640x480 at
+ 120 frames per second rate, data output format is 8/10-bit RAW
+ transferred over one-lane MIPI D-PHY at up to 800 Mbps.
+
+maintainers:
+ - Vladimir Zapolskiy <vladimir.zapolskiy@linaro.org>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,og0ve1b
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: XVCLK supply clock, 6MHz to 27MHz frequency.
+ maxItems: 1
+
+ reset-gpios:
+ description: Active low GPIO connected to XSHUTDOWN pad of the sensor.
+ maxItems: 1
+
+ strobe-gpios:
+ description: Input GPIO connected to strobe pad of the sensor.
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog voltage supply, 2.6 to 3.0 volts.
+
+ dovdd-supply:
+ description: Digital I/O voltage supply, 1.7 to 3.0 volts.
+
+ dvdd-supply:
+ description: Digital core voltage supply.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ required:
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3e {
+ compatible = "ovti,og0ve1b";
+ reg = <0x3e>;
+ clocks = <&camera_clk 0>;
+ assigned-clocks = <&camera_clk 0>;
+ assigned-clock-rates = <24000000>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&vreg_2p8>;
+ dovdd-supply = <&vreg_1p8>;
+ dvdd-supply = <&vreg_1p2>;
+
+ port {
+ endpoint {
+ link-frequencies = /bits/ 64 <500000000>;
+ remote-endpoint = <&mipi_csi2_ep>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml
index 63a040944f3d..0e1d9c390180 100644
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml
@@ -5,7 +5,7 @@
$id: http://devicetree.org/schemas/media/i2c/ovti,ov02a10.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Omnivision OV02A10 CMOS Sensor Device Tree Bindings
+title: Omnivision OV02A10 CMOS Sensor
maintainers:
- Dongchun Zhu <dongchun.zhu@mediatek.com>
@@ -39,6 +39,7 @@ properties:
clock-frequency:
description:
Frequency of the eclk clock in Hz.
+ deprecated: true
dovdd-supply:
description:
@@ -68,12 +69,6 @@ properties:
marked GPIO_ACTIVE_LOW.
maxItems: 1
- rotation:
- enum:
- - 0 # Sensor Mounted Upright
- - 180 # Sensor Mounted Upside Down
- default: 0
-
port:
$ref: /schemas/graph.yaml#/$defs/port-base
additionalProperties: false
@@ -88,7 +83,7 @@ properties:
properties:
link-frequencies: true
ovti,mipi-clock-voltage:
- $ref: "/schemas/types.yaml#/definitions/uint32"
+ $ref: /schemas/types.yaml#/definitions/uint32
description:
Definition of MIPI clock voltage unit. This entry corresponds to
the link speed defined by the 'link-frequencies' property.
@@ -106,7 +101,6 @@ required:
- reg
- clocks
- clock-names
- - clock-frequency
- dovdd-supply
- avdd-supply
- dvdd-supply
@@ -114,7 +108,7 @@ required:
- reset-gpios
- port
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
@@ -133,7 +127,6 @@ examples:
clocks = <&ov02a10_clk>;
clock-names = "eclk";
- clock-frequency = <24000000>;
rotation = <180>;
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov02e10.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov02e10.yaml
new file mode 100644
index 000000000000..03d476bcf805
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov02e10.yaml
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2025 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov02e10.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV02E10 CMOS Sensor
+
+maintainers:
+ - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
+
+description: |
+ The Omnivision OV02E10 and OV02C10 sensors are 2 megapixel, CMOS image sensors which support:
+ - Automatic black level calibration (ABLC)
+ - Programmable controls for frame rate, mirror and flip, binning, cropping
+ and windowing
+ - OVO2C10
+ - 10 bit RAW Bayer 1920x1080 60 fps 2-lane @ 800 Mbps/lane
+ - 10 bit RAW Bayer 1920x1080 60 fps 1-lane @ 1500 Mbps/lane
+ - 10 bit RAW Bayer 1280x720 60 fps cropped 1-lane @ 960 Mbps/lane
+ - 10 bit RGB/BW 640x480 60 fps bin2 or skip2 1-lane @ 800 Mbps/lane
+ - 10 bit RGB/BW 480x270 60 fps bin4 or skip4 1-lane @ 800 Mbps/lane
+ - OV02E10
+ - 10 bit RAW Bayer 1920x1088 60 fps 2-lane @ 720 Mbps/lane
+ - 10 bit RAW Bayer 1280x1080 60 fps 2-lane @ 720 Mbps/lane
+ - 10 bit Quad Bayer 960x540 60 fps 2-lane 360 Mbps/lane
+ - 8 bit Quad Bayer 480x270 1/3/5/10 fps sub2 288 Mbps/lane
+ - 8 bit Quad Bayer 232x132 1/3/5/10 fps sub4 144 Mbps/lane
+ - Dynamic defect pixel cancellation
+ - Standard SCCB command interface
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ enum:
+ - ovti,ov02c10
+ - ovti,ov02e10
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ avdd-supply:
+ description: Analogue circuit voltage supply.
+
+ dovdd-supply:
+ description: I/O circuit voltage supply.
+
+ dvdd-supply:
+ description: Digital circuit voltage supply.
+
+ reset-gpios:
+ description: Active low GPIO connected to XSHUTDOWN pad of the sensor.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ data-lanes:
+ items:
+ - const: 1
+ - const: 2
+ link-frequencies: true
+ remote-endpoint: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+ - remote-endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov02e10: camera@10 {
+ compatible = "ovti,ov02e10";
+ reg = <0x10>;
+
+ reset-gpios = <&tlmm 237 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam_rgb_defaultt>;
+
+ clocks = <&ov02e10_clk>;
+
+ assigned-clocks = <&ov02e10_clk>;
+ assigned-clock-parents = <&ov02e10_clk_parent>;
+ assigned-clock-rates = <19200000>;
+
+ avdd-supply = <&vreg_l7b_2p8>;
+ dvdd-supply = <&vreg_l7b_1p8>;
+ dovdd-supply = <&vreg_l3m_1p8>;
+
+ port {
+ ov02e10_ep: endpoint {
+ remote-endpoint = <&csiphy4_ep>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <400000000>;
+ };
+ };
+ };
+
+ ov02c10: camera@36 {
+ compatible = "ovti,ov02c10";
+ reg = <0x36>;
+
+ reset-gpios = <&tlmm 237 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam_rgb_defaultt>;
+
+ clocks = <&ov02c10_clk>;
+
+ assigned-clocks = <&ov02c10_clk>;
+ assigned-clock-parents = <&ov02c10_clk_parent>;
+ assigned-clock-rates = <19200000>;
+
+ avdd-supply = <&vreg_l7b_2p8>;
+ dvdd-supply = <&vreg_l7b_1p8>;
+ dovdd-supply = <&vreg_l3m_1p8>;
+
+ port {
+ ov02c10_ep: endpoint {
+ remote-endpoint = <&csiphy4_ep>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <400000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov08x40.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov08x40.yaml
new file mode 100644
index 000000000000..552efdf8934f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov08x40.yaml
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2024 Linaro Ltd.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov08x40.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV08X40 CMOS Sensor
+
+maintainers:
+ - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
+
+description: |
+ The Omnivision OV08X40 is a 9.2 megapixel, CMOS image sensor which supports:
+ - Automatic black level calibration (ABLC)
+ - Programmable controls for frame rate, mirror and flip, binning, cropping
+ and windowing
+ - Output formats 10-bit 4C RGB RAW, 10-bit Bayer RAW
+ - 4-lane MIPI D-PHY TX @ 1 Gbps per lane
+ - 2-lane MPIP D-PHY TX @ 2 Gbps per lane
+ - Dynamic defect pixel cancellation
+ - Standard SCCB command interface
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov08x40
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ avdd-supply:
+ description: Analogue circuit voltage supply.
+
+ dovdd-supply:
+ description: I/O circuit voltage supply.
+
+ dvdd-supply:
+ description: Digital circuit voltage supply.
+
+ reset-gpios:
+ description: Active low GPIO connected to XSHUTDOWN pad of the sensor.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+ link-frequencies: true
+ remote-endpoint: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+ - remote-endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov08x40: camera@36 {
+ compatible = "ovti,ov08x40";
+ reg = <0x36>;
+
+ reset-gpios = <&tlmm 111 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam_rgb_defaultt>;
+
+ clocks = <&ov08x40_clk>;
+
+ assigned-clocks = <&ov08x40_clk>;
+ assigned-clock-parents = <&ov08x40_clk_parent>;
+ assigned-clock-rates = <19200000>;
+
+ avdd-supply = <&vreg_l7b_2p8>;
+ dvdd-supply = <&vreg_l7b_1p8>;
+ dovdd-supply = <&vreg_l3m_1p8>;
+
+ port {
+ ov08x40_ep: endpoint {
+ remote-endpoint = <&csiphy4_ep>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <400000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ov2640.txt b/Documentation/devicetree/bindings/media/i2c/ovti,ov2640.txt
index 989ce6cb6ac3..989ce6cb6ac3 100644
--- a/Documentation/devicetree/bindings/media/i2c/ov2640.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2640.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/ov2659.txt b/Documentation/devicetree/bindings/media/i2c/ovti,ov2659.txt
index 92989a619f29..92989a619f29 100644
--- a/Documentation/devicetree/bindings/media/i2c/ov2659.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2659.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml
index cf456f8d9ddc..634d3b821b8c 100644
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2680.yaml
@@ -37,31 +37,45 @@ properties:
active low.
maxItems: 1
- dovdd-supply:
+ DOVDD-supply:
description:
Definition of the regulator used as interface power supply.
- avdd-supply:
+ AVDD-supply:
description:
Definition of the regulator used as analog power supply.
- dvdd-supply:
+ DVDD-supply:
description:
Definition of the regulator used as digital power supply.
port:
- $ref: /schemas/graph.yaml#/properties/port
description:
A node containing an output port node.
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ link-frequencies: true
+
+ remote-endpoint: true
+
+ required:
+ - link-frequencies
required:
- compatible
- reg
- clocks
- clock-names
- - dovdd-supply
- - avdd-supply
- - dvdd-supply
+ - DOVDD-supply
+ - AVDD-supply
+ - DVDD-supply
- reset-gpios
- port
@@ -82,13 +96,14 @@ examples:
clock-names = "xvclk";
reset-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>;
- dovdd-supply = <&sw2_reg>;
- dvdd-supply = <&sw2_reg>;
- avdd-supply = <&reg_peri_3p15v>;
+ DOVDD-supply = <&sw2_reg>;
+ DVDD-supply = <&sw2_reg>;
+ AVDD-supply = <&reg_peri_3p15v>;
port {
ov2680_to_mipi: endpoint {
remote-endpoint = <&mipi_from_sensor>;
+ link-frequencies = /bits/ 64 <330000000>;
};
};
};
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov2685.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov2685.yaml
new file mode 100644
index 000000000000..e2ffe0a9c26b
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2685.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov2685.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV2685 Image Sensor
+
+maintainers:
+ - Shunqian Zheng <zhengsq@rock-chips.com>
+
+properties:
+ compatible:
+ const: ovti,ov2685
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: XVCLK clock
+
+ clock-names:
+ items:
+ - const: xvclk
+
+ dvdd-supply:
+ description: Digital Domain Power Supply
+
+ avdd-supply:
+ description: Analog Domain Power Supply
+
+ dovdd-supply:
+ description: I/O Domain Power Supply
+
+ reset-gpios:
+ maxItems: 1
+ description: Reset Pin GPIO Control (active low)
+
+ port:
+ description: MIPI CSI-2 transmitter port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - dvdd-supply
+ - avdd-supply
+ - dovdd-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/rk3399-cru.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov2685: camera-sensor@3c {
+ compatible = "ovti,ov2685";
+ reg = <0x3c>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&clk_24m_cam>;
+
+ clocks = <&cru SCLK_TESTCLKOUT1>;
+ clock-names = "xvclk";
+
+ avdd-supply = <&pp2800_cam>;
+ dovdd-supply = <&pp1800>;
+ dvdd-supply = <&pp1800>;
+ reset-gpios = <&gpio2 3 GPIO_ACTIVE_LOW>;
+
+ port {
+ ucam_out: endpoint {
+ remote-endpoint = <&mipi_in_ucam>;
+ data-lanes = <1>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov2735.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov2735.yaml
new file mode 100644
index 000000000000..bb34f21519c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov2735.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov2735.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV2735 Image Sensor
+
+maintainers:
+ - Himanshu Bhavani <himanshu.bhavani@siliconsignals.io>
+
+description:
+ The OmniVision OV2735 is a 2MP (1920x1080) color CMOS image sensor controlled
+ through an I2C-compatible SCCB bus. it outputs RAW10 format and uses a 1/2.7"
+ optical format.
+
+properties:
+ compatible:
+ const: ovti,ov2735
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: XVCLK clock
+
+ avdd-supply:
+ description: Analog Domain Power Supply
+
+ dovdd-supply:
+ description: I/O Domain Power Supply
+
+ dvdd-supply:
+ description: Digital Domain Power Supply
+
+ reset-gpios:
+ maxItems: 1
+ description: Reset Pin GPIO Control (active low)
+
+ enable-gpios:
+ maxItems: 1
+ description:
+ Active-low enable pin. Labeled as 'PWDN' in the datasheet, but acts as
+ an enable signal. During power rail ramp-up, the device remains powered
+ down. Once power rails are stable, pulling this pin low powers on the
+ device.
+
+ port:
+ description: MIPI CSI-2 transmitter port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ items:
+ - const: 1
+ - const: 2
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - avdd-supply
+ - dovdd-supply
+ - dvdd-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera-sensor@3c {
+ compatible = "ovti,ov2735";
+ reg = <0x3c>;
+ clocks = <&ov2735_clk>;
+
+ avdd-supply = <&ov2735_avdd>;
+ dovdd-supply = <&ov2735_dovdd>;
+ dvdd-supply = <&ov2735_dvdd>;
+
+ reset-gpios = <&gpio1 6 GPIO_ACTIVE_LOW>;
+ enable-gpios = <&gpio2 11 GPIO_ACTIVE_LOW>;
+
+ port {
+ cam_out: endpoint {
+ remote-endpoint = <&mipi_in_cam>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <420000000>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml
new file mode 100644
index 000000000000..d96199031b66
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov4689.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV4689 CMOS
+
+maintainers:
+ - Mikhail Rudenko <mike.rudenko@gmail.com>
+
+description: |
+ The Omnivision OV4689 is a high performance, 1/3-inch, 4 megapixel
+ image sensor. Ihis chip supports high frame rate speeds up to 90 fps
+ at 2688x1520 resolution. It is programmable through an I2C
+ interface, and sensor output is sent via 1/2/4 lane MIPI CSI-2
+ connection.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov4689
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description:
+ External clock (XVCLK) for the sensor, 6-64 MHz
+ maxItems: 1
+
+ dovdd-supply:
+ description:
+ Digital I/O voltage supply, 1.7-3.0 V
+
+ avdd-supply:
+ description:
+ Analog voltage supply, 2.6-3.0 V
+
+ dvdd-supply:
+ description:
+ Digital core voltage supply, 1.1-1.3 V
+
+ powerdown-gpios:
+ description:
+ GPIO connected to the powerdown pin (active low)
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ GPIO connected to the reset pin (active low)
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+ description:
+ Output port node, single endpoint describing the CSI-2 transmitter
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+ - items:
+ - const: 1
+ - const: 2
+ - items:
+ - const: 1
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - dovdd-supply
+ - avdd-supply
+ - dvdd-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov4689: camera@36 {
+ compatible = "ovti,ov4689";
+ reg = <0x36>;
+
+ clocks = <&ov4689_clk>;
+
+ avdd-supply = <&ov4689_avdd>;
+ dovdd-supply = <&ov4689_dovdd>;
+ dvdd-supply = <&ov4689_dvdd>;
+
+ powerdown-gpios = <&pio 107 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&pio 109 GPIO_ACTIVE_LOW>;
+
+ orientation = <2>;
+ rotation = <0>;
+
+ port {
+ wcam_out: endpoint {
+ remote-endpoint = <&mipi_in_wcam>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <504000000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml
new file mode 100644
index 000000000000..2c5e69356658
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5640.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV5640 Image Sensor
+
+maintainers:
+ - Steve Longerbeam <slongerbeam@gmail.com>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov5640
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: XCLK Input Clock
+
+ clock-names:
+ const: xclk
+
+ AVDD-supply:
+ description: Analog voltage supply, 2.8 volts
+
+ DVDD-supply:
+ description: Digital core voltage supply, 1.5 volts
+
+ DOVDD-supply:
+ description: Digital I/O voltage supply, 1.8 volts
+
+ powerdown-gpios:
+ maxItems: 1
+ description: >
+ Reference to the GPIO connected to the powerdown pin, if any.
+
+ reset-gpios:
+ maxItems: 1
+ description: >
+ Reference to the GPIO connected to the reset pin, if any.
+
+ port:
+ description: Digital Output Port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ const: 0
+
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [1, 2]
+
+ bus-width:
+ enum: [8, 10]
+
+ data-shift:
+ enum: [0, 2]
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - AVDD-supply
+ - DVDD-supply
+ - DOVDD-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx6qdl-clock.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3c {
+ compatible = "ovti,ov5640";
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_ov5640>;
+ reg = <0x3c>;
+ clocks = <&clks IMX6QDL_CLK_CKO>;
+ clock-names = "xclk";
+ DOVDD-supply = <&vgen4_reg>; /* 1.8v */
+ AVDD-supply = <&vgen3_reg>; /* 2.8v */
+ DVDD-supply = <&vgen2_reg>; /* 1.5v */
+ powerdown-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>;
+ rotation = <180>;
+
+ port {
+ /* MIPI CSI-2 bus endpoint */
+ ov5640_to_mipi_csi2: endpoint {
+ remote-endpoint = <&mipi_csi2_from_ov5640>;
+ clock-lanes = <0>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+ };
+
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3c {
+ compatible = "ovti,ov5640";
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_ov5640>;
+ reg = <0x3c>;
+ clocks = <&clk_ext_camera>;
+ clock-names = "xclk";
+ DOVDD-supply = <&vgen4_reg>; /* 1.8v */
+ AVDD-supply = <&vgen3_reg>; /* 2.8v */
+ DVDD-supply = <&vgen2_reg>; /* 1.5v */
+
+ port {
+ /* Parallel bus endpoint */
+ ov5640_to_parallel: endpoint {
+ remote-endpoint = <&parallel_from_ov5640>;
+ bus-width = <8>;
+ data-shift = <2>; /* lines 9:2 are used */
+ hsync-active = <0>;
+ vsync-active = <0>;
+ pclk-sample = <1>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml
new file mode 100644
index 000000000000..01f8b2b3fd17
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml
@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5642.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV5642 Image Sensor
+
+maintainers:
+ - Fabio Estevam <festevam@gmail.com>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov5642
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: XCLK Input Clock
+
+ AVDD-supply:
+ description: Analog voltage supply, 2.8V.
+
+ DVDD-supply:
+ description: Digital core voltage supply, 1.5V.
+
+ DOVDD-supply:
+ description: Digital I/O voltage supply, 1.8V.
+
+ powerdown-gpios:
+ maxItems: 1
+ description: Reference to the GPIO connected to the powerdown pin, if any.
+
+ reset-gpios:
+ maxItems: 1
+ description: Reference to the GPIO connected to the reset pin, if any.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ description: |
+ Video output port.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ enum: [5, 6]
+
+ bus-width:
+ enum: [8, 10]
+ default: 10
+
+ data-shift:
+ enum: [0, 2]
+ default: 0
+
+ hsync-active:
+ enum: [0, 1]
+ default: 1
+
+ vsync-active:
+ enum: [0, 1]
+ default: 1
+
+ pclk-sample:
+ enum: [0, 1]
+ default: 1
+
+ allOf:
+ - if:
+ properties:
+ bus-type:
+ const: 6
+ then:
+ properties:
+ hsync-active: false
+ vsync-active: false
+
+ - if:
+ properties:
+ bus-width:
+ const: 10
+ then:
+ properties:
+ data-shift:
+ const: 0
+
+ required:
+ - bus-type
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3c {
+ compatible = "ovti,ov5642";
+ reg = <0x3c>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_ov5642>;
+ clocks = <&clk_ext_camera>;
+ DOVDD-supply = <&vgen4_reg>;
+ AVDD-supply = <&vgen3_reg>;
+ DVDD-supply = <&vgen2_reg>;
+ powerdown-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>;
+
+ port {
+ ov5642_to_parallel: endpoint {
+ bus-type = <MEDIA_BUS_TYPE_PARALLEL>;
+ remote-endpoint = <&parallel_from_ov5642>;
+ bus-width = <8>;
+ data-shift = <2>; /* lines 9:2 are used */
+ hsync-active = <0>;
+ vsync-active = <0>;
+ pclk-sample = <1>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml
new file mode 100644
index 000000000000..a583714b1ac7
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5645.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5645.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV5645 Image Sensor
+
+maintainers:
+ - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
+
+properties:
+ compatible:
+ const: ovti,ov5645
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: XCLK Input Clock
+
+ clock-frequency:
+ description: Frequency of the xclk clock in Hz.
+ deprecated: true
+
+ vdda-supply:
+ description: Analog voltage supply, 2.8 volts
+
+ vddd-supply:
+ description: Digital core voltage supply, 1.5 volts
+
+ vdddo-supply:
+ description: Digital I/O voltage supply, 1.8 volts
+
+ enable-gpios:
+ maxItems: 1
+ description:
+ Reference to the GPIO connected to the PWDNB pin, if any.
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ Reference to the GPIO connected to the RESETB pin, if any.
+
+ port:
+ description: Digital Output Port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [1, 2]
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vdddo-supply
+ - vdda-supply
+ - vddd-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3c {
+ compatible = "ovti,ov5645";
+ reg = <0x3c>;
+
+ clocks = <&clks 1>;
+ assigned-clocks = <&clks 1>;
+ assigned-clock-rates = <24000000>;
+
+ vdddo-supply = <&ov5645_vdddo_1v8>;
+ vdda-supply = <&ov5645_vdda_2v8>;
+ vddd-supply = <&ov5645_vddd_1v5>;
+ enable-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&pinctrl_ov5645>;
+
+ port {
+ ov5645_ep: endpoint {
+ remote-endpoint = <&csi0_ep>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml
index 3e5d82df90a2..a2abed06a099 100644
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5647.yaml
@@ -31,7 +31,7 @@ properties:
maxItems: 1
port:
- $ref: /schemas/graph.yaml#/properties/port
+ $ref: /schemas/graph.yaml#/$defs/port-base
additionalProperties: false
properties:
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml
index 246dc5fec716..8028c8b107c4 100644
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5648.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/i2c/ovti,ov5648.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: OmniVision OV5648 Image Sensor Device Tree Bindings
+title: OmniVision OV5648 Image Sensor
maintainers:
- Paul Kocialkowski <paul.kocialkowski@bootlin.com>
@@ -20,12 +20,6 @@ properties:
items:
- description: XVCLK Clock
- assigned-clocks:
- maxItems: 1
-
- assigned-clock-rates:
- maxItems: 1
-
dvdd-supply:
description: Digital Domain Power Supply
@@ -68,8 +62,6 @@ required:
- compatible
- reg
- clocks
- - assigned-clocks
- - assigned-clock-rates
- dvdd-supply
- dovdd-supply
- port
@@ -81,7 +73,7 @@ examples:
#include <dt-bindings/clock/sun8i-v3s-ccu.h>
#include <dt-bindings/gpio/gpio.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -93,9 +85,6 @@ examples:
avdd-supply = <&ov5648_avdd>;
dovdd-supply = <&ov5648_dovdd>;
clocks = <&ov5648_xvclk 0>;
- assigned-clocks = <&ov5648_xvclk 0>;
- assigned-clock-rates = <24000000>;
-
ov5648_out: port {
ov5648_out_mipi_csi2: endpoint {
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
new file mode 100644
index 000000000000..6e089fe1d613
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5670.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV5670 5 Megapixels raw image sensor
+
+maintainers:
+ - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+
+description: |-
+ The OV5670 is a 5 Megapixels raw image sensor which provides images in 10-bits
+ RAW BGGR Bayer format on a 2 data lanes MIPI CSI-2 serial interface and is
+ controlled through an I2C compatible control bus.
+
+properties:
+ compatible:
+ const: ovti,ov5670
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: System clock. From 6 to 27 MHz.
+ maxItems: 1
+
+ powerdown-gpios:
+ description: Reference to the GPIO connected to the PWDNB pin. Active low.
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the XSHUTDOWN pin. Active low.
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog circuit power. Typically 2.8V.
+
+ dvdd-supply:
+ description: Digital circuit power. Typically 1.2V.
+
+ dovdd-supply:
+ description: Digital I/O circuit power. Typically 2.8V or 1.8V.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [1, 2]
+
+ clock-noncontinuous: true
+ remote-endpoint: true
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov5670: sensor@36 {
+ compatible = "ovti,ov5670";
+ reg = <0x36>;
+
+ clocks = <&sensor_xclk>;
+
+ port {
+ ov5670_ep: endpoint {
+ remote-endpoint = <&csi_ep>;
+ data-lanes = <1 2>;
+ clock-noncontinuous;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5675.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5675.yaml
new file mode 100644
index 000000000000..ad07204057f9
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5675.yaml
@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2022 Theobroma Systems Design und Consulting GmbH
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5675.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV5675 CMOS Sensor
+
+maintainers:
+ - Quentin Schulz <quentin.schulz@theobroma-systems.com>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+description: |
+ The Omnivision OV5675 is a high performance, 1/5-inch, 5 megapixel, CMOS
+ image sensor that delivers 2592x1944 at 30fps. It provides full-frame,
+ sub-sampled, and windowed 10-bit MIPI images in various formats via the
+ Serial Camera Control Bus (SCCB) interface.
+
+ This chip is programmable through I2C and two-wire SCCB. The sensor output
+ is available via CSI-2 serial data output (up to 2-lane).
+
+properties:
+ compatible:
+ const: ovti,ov5675
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description:
+ System input clock (aka XVCLK). From 6 to 27 MHz.
+ maxItems: 1
+
+ dovdd-supply:
+ description:
+ Digital I/O voltage supply, 1.8 volts.
+
+ avdd-supply:
+ description:
+ Analog voltage supply, 2.8 volts.
+
+ dvdd-supply:
+ description:
+ Digital core voltage supply, 1.2 volts.
+
+ reset-gpios:
+ description:
+ The phandle and specifier for the GPIO that controls sensor reset.
+ This corresponds to the hardware pin XSHUTDN which is physically
+ active low.
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+
+ # Supports max data transfer of 900 Mbps per lane
+ link-frequencies: true
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - dovdd-supply
+ - avdd-supply
+ - dvdd-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/px30-cru.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/pinctrl/rockchip.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov5675: camera@36 {
+ compatible = "ovti,ov5675";
+ reg = <0x36>;
+
+ reset-gpios = <&gpio2 RK_PB1 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cif_clkout_m0>;
+
+ clocks = <&cru SCLK_CIF_OUT>;
+ assigned-clocks = <&cru SCLK_CIF_OUT>;
+ assigned-clock-rates = <19200000>;
+
+ avdd-supply = <&vcc_1v8>;
+ dvdd-supply = <&vcc_1v2>;
+ dovdd-supply = <&vcc_2v8>;
+
+ rotation = <90>;
+ orientation = <0>;
+
+ port {
+ ucam_out: endpoint {
+ remote-endpoint = <&mipi_in_ucam>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <450000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml
new file mode 100644
index 000000000000..3368b3bd8ef2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml
@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2022 Amarulasolutions
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5693.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV5693/OV5695 CMOS Sensors
+
+maintainers:
+ - Tommaso Merciai <tomm.merciai@gmail.com>
+
+description: |
+ The Omnivision OV5693/OV5695 are high performance, 1/4-inch, 5 megapixel, CMOS
+ image sensors that deliver 2592x1944 at 30fps. It provides full-frame,
+ sub-sampled, and windowed 10-bit MIPI images in various formats via the
+ Serial Camera Control Bus (SCCB) interface.
+
+ OV5693/OV5695 are controlled via I2C and two-wire Serial Camera Control Bus
+ (SCCB). The sensor output is available via CSI-2 serial data output (up to
+ 2-lane).
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: ovti,ov5693
+ then:
+ properties:
+ port:
+ properties:
+ endpoint:
+ required:
+ - link-frequencies
+
+properties:
+ compatible:
+ enum:
+ - ovti,ov5693
+ - ovti,ov5695
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description:
+ System input clock (aka XVCLK). From 6 to 27 MHz.
+ maxItems: 1
+
+ clock-names:
+ const: xvclk
+
+ dovdd-supply:
+ description:
+ Digital I/O voltage supply, 1.8V.
+
+ avdd-supply:
+ description:
+ Analog voltage supply, 2.8V.
+
+ dvdd-supply:
+ description:
+ Digital core voltage supply, 1.2V.
+
+ reset-gpios:
+ description:
+ The phandle and specifier for the GPIO that controls sensor reset.
+ This corresponds to the hardware pin XSHUTDN which is physically
+ active low.
+ maxItems: 1
+
+ port:
+ description: MIPI CSI-2 transmitter port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ link-frequencies: true
+
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/px30-cru.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/pinctrl/rockchip.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov5693: camera@36 {
+ compatible = "ovti,ov5693";
+ reg = <0x36>;
+
+ reset-gpios = <&gpio2 RK_PB1 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&cif_clkout_m0>;
+
+ clocks = <&cru SCLK_CIF_OUT>;
+ assigned-clocks = <&cru SCLK_CIF_OUT>;
+ assigned-clock-rates = <19200000>;
+
+ avdd-supply = <&vcc_1v8>;
+ dvdd-supply = <&vcc_1v2>;
+ dovdd-supply = <&vcc_2v8>;
+
+ rotation = <90>;
+ orientation = <0>;
+
+ port {
+ ucam_out: endpoint {
+ remote-endpoint = <&mipi_in_ucam>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <450000000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov6211.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov6211.yaml
new file mode 100644
index 000000000000..5a857fa2f371
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov6211.yaml
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov6211.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV6211 Image Sensor
+
+description:
+ OmniVision OV6211 image sensor is a high performance monochrome image
+ sensor. The sensor is controlled over a serial camera control bus
+ protocol (SCCB), the widest supported output image frame size is 400x400
+ at 120 frames per second rate, data output format is 8/10-bit RAW
+ transferred over one-lane MIPI D-PHY interface.
+
+maintainers:
+ - Vladimir Zapolskiy <vladimir.zapolskiy@linaro.org>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov6211
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: XVCLK supply clock, 6MHz to 27MHz frequency.
+ maxItems: 1
+
+ reset-gpios:
+ description: Active low GPIO connected to XSHUTDOWN pad of the sensor.
+ maxItems: 1
+
+ strobe-gpios:
+ description: Input GPIO connected to strobe pad of the sensor.
+ maxItems: 1
+
+ avdd-supply:
+ description: Analogue voltage supply, 2.6 to 3.0 volts.
+
+ dovdd-supply:
+ description: Digital I/O voltage supply, 1.8 volts.
+
+ dvdd-supply:
+ description: Digital core voltage supply.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ required:
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@60 {
+ compatible = "ovti,ov6211";
+ reg = <0x60>;
+ clocks = <&camera_clk 0>;
+ assigned-clocks = <&camera_clk 0>;
+ assigned-clock-rates = <24000000>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
+ avdd-supply = <&vreg_2p8>;
+ dovdd-supply = <&vreg_1p8>;
+ dvdd-supply = <&vreg_1p2>;
+
+ port {
+ endpoint {
+ link-frequencies = /bits/ 64 <480000000>;
+ remote-endpoint = <&mipi_csi2_ep>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov64a40.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov64a40.yaml
new file mode 100644
index 000000000000..2b6143aff391
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov64a40.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov64a40.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV64A40 Image Sensor
+
+maintainers:
+ - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov64a40
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog voltage supply, 2.8 volts
+
+ dvdd-supply:
+ description: Digital core voltage supply, 1.1 volts
+
+ dovdd-supply:
+ description: Digital I/O voltage supply, 1.8 volts
+
+ powerdown-gpios:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ additionalProperties: false
+
+ properties:
+ bus-type:
+ enum:
+ - 1 # MIPI CSI-2 C-PHY
+ - 4 # MIPI CSI-2 D-PHY
+ data-lanes: true
+ link-frequencies: true
+ clock-noncontinuous: true
+ remote-endpoint: true
+
+ required:
+ - bus-type
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@36 {
+ compatible = "ovti,ov64a40";
+ reg = <0x36>;
+ clocks = <&camera_clk>;
+ dovdd-supply = <&vgen4_reg>;
+ avdd-supply = <&vgen3_reg>;
+ dvdd-supply = <&vgen2_reg>;
+ powerdown-gpios = <&gpio1 9 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;
+ rotation = <180>;
+ orientation = <2>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&mipi_csi2_in>;
+ bus-type = <4>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <456000000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml
new file mode 100644
index 000000000000..922996da59b2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov7251.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov7251.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV7251 Image Sensor
+
+description:
+ The Omnivision OV7251 is a 1/7.5-Inch CMOS active pixel digital image sensor
+ with an active array size of 640H x 480V. It is programmable through a serial
+ I2C interface.
+
+maintainers:
+ - Todor Tomov <todor.too@gmail.com>
+
+properties:
+ compatible:
+ const: ovti,ov7251
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: XCLK Input Clock
+
+ clock-names:
+ const: xclk
+
+ clock-frequency:
+ description: Frequency of the xclk clock in Hz.
+ deprecated: true
+
+ vdda-supply:
+ description: Analog voltage supply, 2.8 volts
+
+ vddd-supply:
+ description: Digital core voltage supply, 1.2 volts
+
+ vdddo-supply:
+ description: Digital I/O voltage supply, 1.8 volts
+
+ enable-gpios:
+ maxItems: 1
+ description:
+ Reference to the GPIO connected to the XSHUTDOWN pin, if any. Polarity
+ is GPIO_ACTIVE_HIGH.
+
+ port:
+ description: Digital Output Port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maximum: 1
+
+ data-lanes:
+ maxItems: 1
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vdddo-supply
+ - vdda-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@3c {
+ compatible = "ovti,ov7251";
+ reg = <0x3c>;
+
+ clocks = <&clks 1>;
+ assigned-clocks = <&clks 1>;
+ assigned-clock-rates = <24000000>;
+
+ vdddo-supply = <&ov7251_vdddo_1v8>;
+ vdda-supply = <&ov7251_vdda_2v8>;
+ vddd-supply = <&ov7251_vddd_1v5>;
+ enable-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>;
+
+ port {
+ ov7251_ep: endpoint {
+ remote-endpoint = <&csi0_ep>;
+ clock-lanes = <1>;
+ data-lanes = <0>;
+ link-frequencies = /bits/ 64 <240000000 319200000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ov7670.txt b/Documentation/devicetree/bindings/media/i2c/ovti,ov7670.txt
index 2c972a56f3cb..2c972a56f3cb 100644
--- a/Documentation/devicetree/bindings/media/i2c/ov7670.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov7670.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml
index 44529425ce3a..5d24edba8f99 100644
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov772x.yaml
@@ -105,8 +105,9 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
ov772x: camera@21 {
@@ -118,7 +119,7 @@ examples:
port {
ov772x_0: endpoint {
- bus-type = <5>;
+ bus-type = <MEDIA_BUS_TYPE_PARALLEL>;
vsync-active = <0>;
hsync-active = <0>;
pclk-sample = <0>;
diff --git a/Documentation/devicetree/bindings/media/i2c/ov7740.txt b/Documentation/devicetree/bindings/media/i2c/ovti,ov7740.txt
index af781c3a5f0e..af781c3a5f0e 100644
--- a/Documentation/devicetree/bindings/media/i2c/ov7740.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov7740.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov8856.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov8856.yaml
new file mode 100644
index 000000000000..fa71f24823f2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov8856.yaml
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2019 MediaTek Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov8856.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV8856 CMOS Sensor
+
+maintainers:
+ - Sakari Ailus <sakari.ailus@linux.intel.com>
+
+description: |-
+ The Omnivision OV8856 is a high performance, 1/4-inch, 8 megapixel, CMOS
+ image sensor that delivers 3264x2448 at 30fps. It provides full-frame,
+ sub-sampled, and windowed 10-bit MIPI images in various formats via the
+ Serial Camera Control Bus (SCCB) interface. This chip is programmable
+ through I2C and two-wire SCCB. The sensor output is available via CSI-2
+ serial data output (up to 4-lane).
+
+properties:
+ compatible:
+ const: ovti,ov8856
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ description:
+ Input clock for the sensor.
+ items:
+ - const: xvclk
+
+ clock-frequency:
+ description:
+ Frequency of the xvclk clock in Hertz.
+ deprecated: true
+
+ dovdd-supply:
+ description:
+ Definition of the regulator used as interface power supply.
+
+ avdd-supply:
+ description:
+ Definition of the regulator used as analog power supply.
+
+ dvdd-supply:
+ description:
+ Definition of the regulator used as digital power supply.
+
+ reset-gpios:
+ description:
+ The phandle and specifier for the GPIO that controls sensor reset.
+ This corresponds to the hardware pin XSHUTDOWN which is physically
+ active low.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - items:
+ - const: 1
+ - const: 2
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ required:
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - dovdd-supply
+ - avdd-supply
+ - dvdd-supply
+ - reset-gpios
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov8856: camera@10 {
+ compatible = "ovti,ov8856";
+ reg = <0x10>;
+
+ reset-gpios = <&pio 111 GPIO_ACTIVE_LOW>;
+ pinctrl-names = "default";
+ pinctrl-0 = <&clk_24m_cam>;
+
+ clocks = <&cam_osc>;
+ clock-names = "xvclk";
+
+ avdd-supply = <&mt6358_vcama2_reg>;
+ dvdd-supply = <&mt6358_vcamd_reg>;
+ dovdd-supply = <&mt6358_vcamio_reg>;
+
+ port {
+ wcam_out: endpoint {
+ remote-endpoint = <&mipi_in_wcam>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <360000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov8858.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov8858.yaml
new file mode 100644
index 000000000000..491f2931e6bc
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov8858.yaml
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov8858.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV8858 Image Sensor
+
+maintainers:
+ - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+ - Nicholas Roth <nicholas@rothemail.net>
+
+description: |
+ The OmniVision OV8858 is a color CMOS 8 Megapixels (3264x2448) image sensor
+ controlled through an I2C-compatible SCCB bus. The sensor transmits images
+ on a MIPI CSI-2 output interface with up to 4 data lanes.
+
+$ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: ovti,ov8858
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description: XVCLK external clock
+
+ clock-names:
+ const: xvclk
+
+ dvdd-supply:
+ description: Digital Domain Power Supply
+
+ avdd-supply:
+ description: Analog Domain Power Supply
+
+ dovdd-supply:
+ description: I/O Domain Power Supply
+
+ powerdown-gpios:
+ description: PWDNB powerdown GPIO (active low)
+
+ reset-gpios:
+ maxItems: 1
+ description: XSHUTDN reset GPIO (active low)
+
+ port:
+ description: MIPI CSI-2 transmitter port
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/pinctrl/rockchip.h>
+ #include <dt-bindings/clock/rk3399-cru.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov8858: camera@36 {
+ compatible = "ovti,ov8858";
+ reg = <0x36>;
+
+ clocks = <&cru SCLK_CIF_OUT>;
+ clock-names = "xvclk";
+ assigned-clocks = <&cru SCLK_CIF_OUT>;
+ assigned-clock-rates = <24000000>;
+
+ dovdd-supply = <&vcc1v8_dvp>;
+
+ reset-gpios = <&gpio1 RK_PA4 GPIO_ACTIVE_LOW>;
+ powerdown-gpios = <&gpio2 RK_PB4 GPIO_ACTIVE_LOW>;
+
+ port {
+ ucam_out: endpoint {
+ remote-endpoint = <&mipi_in_ucam>;
+ data-lanes = <1 2 3 4>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml
index b962863e4f65..320b9aacbb8b 100644
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov8865.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/i2c/ovti,ov8865.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: OmniVision OV8865 Image Sensor Device Tree Bindings
+title: OmniVision OV8865 Image Sensor
maintainers:
- Paul Kocialkowski <paul.kocialkowski@bootlin.com>
@@ -20,12 +20,6 @@ properties:
items:
- description: EXTCLK Clock
- assigned-clocks:
- maxItems: 1
-
- assigned-clock-rates:
- maxItems: 1
-
dvdd-supply:
description: Digital Domain Power Supply
@@ -68,8 +62,6 @@ required:
- compatible
- reg
- clocks
- - assigned-clocks
- - assigned-clock-rates
- dvdd-supply
- avdd-supply
- dovdd-supply
@@ -82,7 +74,7 @@ examples:
#include <dt-bindings/clock/sun8i-a83t-ccu.h>
#include <dt-bindings/gpio/gpio.h>
- i2c2 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -94,8 +86,6 @@ examples:
pinctrl-0 = <&csi_mclk_pin>;
clocks = <&ccu CLK_CSI_MCLK>;
- assigned-clocks = <&ccu CLK_CSI_MCLK>;
- assigned-clock-rates = <24000000>;
avdd-supply = <&reg_ov8865_avdd>;
dovdd-supply = <&reg_ov8865_dovdd>;
diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml
new file mode 100644
index 000000000000..401c8613f840
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov9282.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2021 Intel Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov9282.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: OmniVision OV9282 Sensor
+
+maintainers:
+ - Paul J. Murphy <paul.j.murphy@intel.com>
+ - Daniele Alessandrelli <daniele.alessandrelli@intel.com>
+
+description:
+ OV9282 sensor is an OmniVision black & white CMOS active pixel digital image
+ sensor with an active array size of 1296H x 816V. It is programmable through
+ I2C interface. The I2C client address is fixed to 0x60/0x70 as per sensor data
+ sheet. Image data is sent through MIPI CSI-2.
+ OV9281 has a different lens chief ray angle.
+
+properties:
+ compatible:
+ enum:
+ - ovti,ov9281
+ - ovti,ov9282
+ reg:
+ description: I2C address
+ maxItems: 1
+
+ clocks:
+ description: Clock frequency from 6 to 27MHz
+ maxItems: 1
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the XCLR pin, if any.
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog voltage supply, 2.8 volts
+
+ dvdd-supply:
+ description: Digital core voltage supply, 1.2 volts
+
+ dovdd-supply:
+ description: Digital I/O voltage supply, 1.8 volts
+
+ port:
+ additionalProperties: false
+ $ref: /schemas/graph.yaml#/$defs/port-base
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes: true
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@60 {
+ compatible = "ovti,ov9282";
+ reg = <0x60>;
+ clocks = <&ov9282_clk>;
+
+ port {
+ ov9282: endpoint {
+ remote-endpoint = <&cam>;
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <800000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ov9650.txt b/Documentation/devicetree/bindings/media/i2c/ovti,ov9650.txt
index 506dfc52872a..506dfc52872a 100644
--- a/Documentation/devicetree/bindings/media/i2c/ov9650.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov9650.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/rda,rda5807.yaml b/Documentation/devicetree/bindings/media/i2c/rda,rda5807.yaml
index f50e54a722eb..34a05df786ce 100644
--- a/Documentation/devicetree/bindings/media/i2c/rda,rda5807.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/rda,rda5807.yaml
@@ -50,7 +50,7 @@ additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/media/i2c/samsung,s5k5baf.yaml b/Documentation/devicetree/bindings/media/i2c/samsung,s5k5baf.yaml
new file mode 100644
index 000000000000..4cb0f5aa1301
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/samsung,s5k5baf.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/samsung,s5k5baf.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5K5BAF UXGA 1/5" 2M CMOS Image Sensor with embedded SoC ISP
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ const: samsung,s5k5baf
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: mclk
+
+ clock-frequency:
+ default: 24000000
+ description: mclk clock frequency
+ deprecated: true
+
+ rstn-gpios:
+ maxItems: 1
+ description: RSTN pin
+
+ stbyn-gpios:
+ maxItems: 1
+ description: STDBYN pin
+
+ vdda-supply:
+ description: Analog power supply 2.8V (2.6V to 3.0V)
+
+ vddio-supply:
+ description: I/O power supply 1.8V (1.65V to 1.95V) or 2.8V (2.5V to 3.1V)
+
+ vddreg-supply:
+ description:
+ Regulator input power supply 1.8V (1.7V to 1.9V) or 2.8V (2.6V to 3.0)
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ items:
+ - const: 1
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - rstn-gpios
+ - stbyn-gpios
+ - vdda-supply
+ - vddio-supply
+ - vddreg-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@2d {
+ compatible = "samsung,s5k5baf";
+ reg = <0x2d>;
+
+ clocks = <&camera 0>;
+ assigned-clocks = <&camera 0>;
+ assigned-clock-rates = <24000000>;
+
+ clock-names = "mclk";
+ rstn-gpios = <&gpl2 1 GPIO_ACTIVE_LOW>;
+ stbyn-gpios = <&gpl2 0 GPIO_ACTIVE_LOW>;
+ vdda-supply = <&cam_io_en_reg>;
+ vddio-supply = <&vtcam_reg>;
+ vddreg-supply = <&vt_core_15v_reg>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&csis1_ep>;
+ data-lanes = <1>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/samsung,s5k6a3.yaml b/Documentation/devicetree/bindings/media/i2c/samsung,s5k6a3.yaml
new file mode 100644
index 000000000000..9df1e0f872f2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/samsung,s5k6a3.yaml
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/samsung,s5k6a3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5K6A3(YX) raw image sensor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description:
+ S5K6A3(YX) is a raw image sensor with MIPI CSI-2 and CCP2 image data
+ interfaces and CCI (I2C compatible) control bus.
+
+properties:
+ compatible:
+ const: samsung,s5k6a3
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: extclk
+
+ clock-frequency:
+ default: 24000000
+ description: extclk clock frequency
+ deprecated: true
+
+ gpios:
+ maxItems: 1
+ description: GPIO connected to the RESET pin
+
+ afvdd-supply:
+ description: AF (actuator) voltage supply
+
+ svdda-supply:
+ description: Core voltage supply
+
+ svddio-supply:
+ description: I/O voltage supply
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ items:
+ - const: 1
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - gpios
+ - afvdd-supply
+ - svdda-supply
+ - svddio-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@10 {
+ compatible = "samsung,s5k6a3";
+ reg = <0x10>;
+
+ clocks = <&camera 1>;
+ assigned-clocks = <&camera 1>;
+ assigned-clock-rates = <24000000>;
+
+ clock-names = "extclk";
+ gpios = <&gpm1 6 GPIO_ACTIVE_LOW>;
+ afvdd-supply = <&ldo19_reg>;
+ svdda-supply = <&cam_io_reg>;
+ svddio-supply = <&ldo19_reg>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&csis1_ep>;
+ data-lanes = <1>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx111.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx111.yaml
new file mode 100644
index 000000000000..20f48d5e9b2d
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx111.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx111.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX111 8MP CMOS Digital Image Sensor
+
+maintainers:
+ - Svyatoslav Ryhel <clamor95@gmail.com>
+
+description:
+ IMX111 sensor is a Sony CMOS active pixel digital image sensor with an active
+ array size of 2464H x 3280V. It is programmable through I2C interface. Image
+ data is sent through MIPI CSI-2, through 1 or 2 lanes.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+ - $ref: /schemas/nvmem/nvmem-consumer.yaml#
+
+properties:
+ compatible:
+ const: sony,imx111
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: EXTCLK with possible frequency from 6 to 54 MHz
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ iovdd-supply:
+ description: Digital IO power supply (1.8V)
+
+ dvdd-supply:
+ description: Digital power supply (1.2V)
+
+ avdd-supply:
+ description: Analog power supply (2.7V)
+
+ port:
+ additionalProperties: false
+ $ref: /schemas/graph.yaml#/$defs/port-base
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@10 {
+ compatible = "sony,imx111";
+ reg = <0x10>;
+
+ clocks = <&imx111_clk>;
+
+ iovdd-supply = <&camera_vddio_1v8>;
+ dvdd-supply = <&camera_vddd_1v2>;
+ avdd-supply = <&camera_vdda_2v7>;
+
+ orientation = <1>;
+ rotation = <90>;
+
+ nvmem = <&eeprom>;
+ flash-leds = <&led>;
+ lens-focus = <&vcm>;
+
+ reset-gpios = <&gpio 84 GPIO_ACTIVE_LOW>;
+
+ port {
+ imx111_output: endpoint {
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <542400000>;
+ remote-endpoint = <&csi_input>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml
index c9760f895b3e..aea99ebf8e9e 100644
--- a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml
@@ -16,7 +16,7 @@ description: |
maximum throughput of 1.2Gbps/lane.
allOf:
- - $ref: ../video-interface-devices.yaml#
+ - $ref: /schemas/media/video-interface-devices.yaml#
properties:
compatible:
@@ -33,20 +33,21 @@ properties:
clock-frequency:
description: Frequency of the xclk clock in Hz.
+ deprecated: true
enable-gpios:
description: GPIO descriptor for the enable pin.
maxItems: 1
- vdddo-supply:
- description: Chip digital IO regulator (1.8V).
-
vdda-supply:
description: Chip analog regulator (2.7V).
vddd-supply:
description: Chip digital core regulator (1.12V).
+ vdddo-supply:
+ description: Chip digital IO regulator (1.8V).
+
flash-leds: true
lens-focus: true
@@ -84,42 +85,44 @@ required:
- compatible
- reg
- clocks
- - clock-frequency
- enable-gpios
- - vdddo-supply
- vdda-supply
- vddd-supply
+ - vdddo-supply
- port
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
camera-sensor@1a {
compatible = "sony,imx214";
reg = <0x1a>;
- vdddo-supply = <&pm8994_lvs1>;
- vddd-supply = <&camera_vddd_1v12>;
+
+ clocks = <&camera_clk>;
+ assigned-clocks = <&camera_clk>;
+ assigned-clock-rates = <24000000>;
+
+ enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>;
+
vdda-supply = <&pm8994_l17>;
+ vddd-supply = <&camera_vddd_1v12>;
+ vdddo-supply = <&pm8994_lvs1>;
+
lens-focus = <&ad5820>;
- enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>;
- clocks = <&camera_clk>;
- clock-frequency = <24000000>;
port {
imx214_ep: endpoint {
data-lanes = <1 2 3 4>;
- link-frequencies = /bits/ 64 <480000000>;
+ link-frequencies = /bits/ 64 <600000000>;
remote-endpoint = <&csiphy0_ep>;
};
};
};
};
-
-...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx219.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx219.yaml
new file mode 100644
index 000000000000..38c3759bcd9f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx219.yaml
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx219.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony 1/4.0-Inch 8Mpixel CMOS Digital Image Sensor
+
+maintainers:
+ - Dave Stevenson <dave.stevenson@raspberrypi.com>
+
+description: |-
+ The Sony imx219 is a 1/4.0-inch CMOS active pixel digital image sensor
+ with an active array size of 3280H x 2464V. It is programmable through
+ I2C interface. The I2C address is fixed to 0x10 as per sensor data sheet.
+ Image data is sent through MIPI CSI-2, which is configured as either 2 or
+ 4 data lanes.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: sony,imx219
+
+ reg:
+ description: I2C device address
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ VDIG-supply:
+ description:
+ Digital I/O voltage supply, 1.8 volts
+
+ VANA-supply:
+ description:
+ Analog voltage supply, 2.8 volts
+
+ VDDL-supply:
+ description:
+ Digital core voltage supply, 1.2 volts
+
+ reset-gpios:
+ maxItems: 1
+ description: |-
+ Reference to the GPIO connected to the xclr pin, if any.
+ Must be released (set high) after all supplies are applied.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ description: |-
+ The sensor supports either two-lane, or four-lane operation.
+ If this property is omitted four-lane operation is assumed.
+ For two-lane operation the property must be set to <1 2>.
+ items:
+ - const: 1
+ - const: 2
+
+ clock-noncontinuous: true
+ link-frequencies: true
+
+ required:
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - VANA-supply
+ - VDIG-supply
+ - VDDL-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imx219: sensor@10 {
+ compatible = "sony,imx219";
+ reg = <0x10>;
+ clocks = <&imx219_clk>;
+ VANA-supply = <&imx219_vana>; /* 2.8v */
+ VDIG-supply = <&imx219_vdig>; /* 1.8v */
+ VDDL-supply = <&imx219_vddl>; /* 1.2v */
+
+ port {
+ imx219_0: endpoint {
+ remote-endpoint = <&csi1_ep>;
+ data-lanes = <1 2>;
+ clock-noncontinuous;
+ link-frequencies = /bits/ 64 <456000000>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx258.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx258.yaml
new file mode 100644
index 000000000000..d105bd357dbb
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx258.yaml
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx258.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX258 13 Mpixel CMOS Digital Image Sensor
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description: |-
+ IMX258 is a diagonal 5.867mm (Type 1/3.06) 13 Mega-pixel CMOS active pixel
+ type stacked image sensor with a square pixel array of size 4208 x 3120. It
+ is programmable through I2C interface. Image data is sent through MIPI
+ CSI-2. The sensor exists in two different models, a standard variant
+ (IMX258) and a variant with phase detection autofocus (IMX258-PDAF).
+ The camera module does not expose the model through registers, so the
+ exact model needs to be specified.
+
+$ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ enum:
+ - sony,imx258
+ - sony,imx258-pdaf
+
+ clocks:
+ description:
+ Clock frequency from 6 to 27 MHz.
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ reset-gpios:
+ description: |-
+ Reference to the GPIO connected to the XCLR pin, if any.
+
+ vana-supply:
+ description:
+ Analog voltage (VANA) supply, 2.7 V
+
+ vdig-supply:
+ description:
+ Digital I/O voltage (VDIG) supply, 1.2 V
+
+ vif-supply:
+ description:
+ Interface voltage (VIF) supply, 1.8 V
+
+ # See ../video-interfaces.txt for more details
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+ - items:
+ - const: 1
+ - const: 2
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@6c {
+ compatible = "sony,imx258";
+ reg = <0x6c>;
+ clocks = <&imx258_clk>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&csi1_ep>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <320000000>;
+ };
+ };
+ };
+ };
+
+ /* Oscillator on the camera board */
+ imx258_clk: clk {
+ compatible = "fixed-clock";
+ #clock-cells = <0>;
+ clock-frequency = <19200000>;
+ };
+
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@6c {
+ compatible = "sony,imx258";
+ reg = <0x6c>;
+ clocks = <&imx258_clk>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&csi1_ep>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <633600000>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml
index 4271fc3cc623..b06a6e75ba97 100644
--- a/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx274.yaml
@@ -46,19 +46,23 @@ properties:
required:
- compatible
- reg
+ - clocks
+ - clock-names
- port
additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
imx274: camera-sensor@1a {
compatible = "sony,imx274";
reg = <0x1a>;
+ clocks = <&imx274_clk>;
+ clock-names = "inck";
reset-gpios = <&gpio_sensor 0 0>;
port {
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx283.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx283.yaml
new file mode 100644
index 000000000000..e4f49f1435a5
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx283.yaml
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2024 Ideas on Board Oy
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx283.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX283 Sensor
+
+maintainers:
+ - Kieran Bingham <kieran.bingham@ideasonboard.com>
+ - Umang Jain <umang.jain@ideasonboard.com>
+
+description:
+ IMX283 sensor is a Sony CMOS active pixel digital image sensor with an active
+ array size of 5472H x 3648V. It is programmable through I2C interface. The
+ I2C client address is fixed to 0x1a as per sensor data sheet. Image data is
+ sent through MIPI CSI-2.
+
+properties:
+ compatible:
+ const: sony,imx283
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: Clock frequency from 6 to 24 MHz.
+ maxItems: 1
+
+ vadd-supply:
+ description: Analog power supply (2.9V)
+
+ vdd1-supply:
+ description: Interface power supply (1.8V)
+
+ vdd2-supply:
+ description: Digital power supply (1.2V)
+
+ reset-gpios:
+ description: Sensor reset (XCLR) GPIO
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ anyOf:
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@1a {
+ compatible = "sony,imx283";
+ reg = <0x1a>;
+ clocks = <&imx283_clk>;
+
+ assigned-clocks = <&imx283_clk>;
+ assigned-clock-parents = <&imx283_clk_parent>;
+ assigned-clock-rates = <12000000>;
+
+ vadd-supply = <&camera_vadd_2v9>;
+ vdd1-supply = <&camera_vdd1_1v8>;
+ vdd2-supply = <&camera_vdd2_1v2>;
+
+ port {
+ imx283: endpoint {
+ remote-endpoint = <&cam>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <360000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml
new file mode 100644
index 000000000000..484039671cd1
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx290.yaml
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx290.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX290 1/2.8-Inch CMOS Image Sensor
+
+maintainers:
+ - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |-
+ The Sony IMX290 is a 1/2.8-Inch CMOS Solid-state image sensor with Square
+ Pixel, available in either mono or colour variants. It is programmable
+ through I2C and 4-wire interfaces.
+
+ The sensor output is available via CMOS logic parallel SDR output, Low voltage
+ LVDS DDR output and CSI-2 serial data output. The CSI-2 bus is the default.
+ No bindings have been defined for the other busses.
+
+ imx290lqr is the full model identifier for the colour variant. "sony,imx290"
+ is treated the same as this as it was the original compatible string.
+ imx290llr is the mono version of the sensor.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - sony,imx290lqr # Colour
+ - sony,imx290llr # Monochrome
+ - sony,imx327lqr # Colour
+ - sony,imx462lqr # Colour
+ - sony,imx462llr # Monochrome
+ - const: sony,imx290
+ deprecated: true
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ description: Input clock (37.125 MHz or 74.25 MHz)
+ items:
+ - const: xclk
+
+ clock-frequency:
+ description: Frequency of the xclk clock in Hz
+ deprecated: true
+
+ vdda-supply:
+ description: Analog power supply (2.9V)
+
+ vddd-supply:
+ description: Digital core power supply (1.2V)
+
+ vdddo-supply:
+ description: Digital I/O power supply (1.8V)
+
+ reset-gpios:
+ description: Sensor reset (XCLR) GPIO
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ description: |
+ Video output port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ anyOf:
+ - items:
+ - const: 1
+ - const: 2
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - vdda-supply
+ - vddd-supply
+ - vdddo-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imx290: camera-sensor@1a {
+ compatible = "sony,imx290lqr";
+ reg = <0x1a>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&camera_rear_default>;
+
+ clocks = <&gcc 90>;
+ clock-names = "xclk";
+ assigned-clocks = <&clks 1>;
+ assigned-clock-rates = <37125000>;
+
+ vdddo-supply = <&camera_vdddo_1v8>;
+ vdda-supply = <&camera_vdda_2v8>;
+ vddd-supply = <&camera_vddd_1v5>;
+
+ reset-gpios = <&msmgpio 35 GPIO_ACTIVE_LOW>;
+
+ port {
+ imx290_ep: endpoint {
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <222750000 148500000>;
+ remote-endpoint = <&csiphy0_ep>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx296.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx296.yaml
new file mode 100644
index 000000000000..65ad9c100e45
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx296.yaml
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx296.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX296 1/2.8-Inch CMOS Image Sensor
+
+maintainers:
+ - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |-
+ The Sony IMX296 is a 1/2.9-Inch active pixel type CMOS Solid-state image
+ sensor with square pixel array and 1.58 M effective pixels. This chip
+ features a global shutter with variable charge-integration time. It is
+ programmable through I2C and 4-wire interfaces. The sensor output is
+ available via CSI-2 serial data output (1 Lane).
+
+properties:
+ compatible:
+ enum:
+ - sony,imx296
+ - sony,imx296ll
+ - sony,imx296lq
+ description:
+ The IMX296 sensor exists in two different models, a colour variant
+ (IMX296LQ) and a monochrome variant (IMX296LL). The device exposes the
+ model through registers, allowing for auto-detection with a common
+ "sony,imx296" compatible string. However, some camera modules disable the
+ ability to read the sensor model register, which disables this feature.
+ In those cases, the exact model needs to be specified as "sony,imx296ll"
+ or "sony,imx296lq".
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ description: Input clock (37.125 MHz, 54 MHz or 74.25 MHz)
+ items:
+ - const: inck
+
+ avdd-supply:
+ description: Analog power supply (3.3V)
+
+ dvdd-supply:
+ description: Digital power supply (1.2V)
+
+ ovdd-supply:
+ description: Interface power supply (1.8V)
+
+ reset-gpios:
+ description: Sensor reset (XCLR) GPIO
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - avdd-supply
+ - dvdd-supply
+ - ovdd-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imx296: camera-sensor@1a {
+ compatible = "sony,imx296";
+ reg = <0x1a>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&camera_rear_default>;
+
+ clocks = <&gcc 90>;
+ clock-names = "inck";
+
+ avdd-supply = <&camera_vdda_3v3>;
+ dvdd-supply = <&camera_vddd_1v2>;
+ ovdd-supply = <&camera_vddo_1v8>;
+
+ reset-gpios = <&msmgpio 35 GPIO_ACTIVE_LOW>;
+
+ port {
+ imx296_ep: endpoint {
+ remote-endpoint = <&csiphy0_ep>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml
index f5055b9db693..3842e5130463 100644
--- a/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx334.yaml
@@ -24,10 +24,6 @@ properties:
description: I2C address
maxItems: 1
- assigned-clocks: true
- assigned-clock-parents: true
- assigned-clock-rates: true
-
clocks:
description: Clock frequency from 6 to 27 MHz, 37.125MHz, 74.25MHz
maxItems: 1
@@ -65,7 +61,7 @@ additionalProperties: false
examples:
- |
- i2c0 {
+ i2c {
#address-cells = <1>;
#size-cells = <0>;
@@ -74,15 +70,11 @@ examples:
reg = <0x1a>;
clocks = <&imx334_clk>;
- assigned-clocks = <&imx334_clk>;
- assigned-clock-parents = <&imx334_clk_parent>;
- assigned-clock-rates = <24000000>;
-
port {
imx334: endpoint {
remote-endpoint = <&cam>;
data-lanes = <1 2 3 4>;
- link-frequencies = /bits/ 64 <891000000>;
+ link-frequencies = /bits/ 64 <891000000 445500000>;
};
};
};
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml
new file mode 100644
index 000000000000..80f879b6bd01
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx335.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2021 Intel Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx335.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX335 Sensor
+
+maintainers:
+ - Paul J. Murphy <paul.j.murphy@intel.com>
+ - Daniele Alessandrelli <daniele.alessandrelli@intel.com>
+
+description:
+ IMX335 sensor is a Sony CMOS active pixel digital image sensor with an active
+ array size of 2592H x 1944V. It is programmable through I2C interface. The
+ I2C client address is fixed to 0x1a as per sensor data sheet. Image data is
+ sent through MIPI CSI-2.
+
+properties:
+ compatible:
+ const: sony,imx335
+ reg:
+ description: I2C address
+ maxItems: 1
+
+ clocks:
+ description: Clock frequency from 6 to 27 MHz, 37.125MHz, 74.25MHz
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog power supply (2.9V)
+
+ ovdd-supply:
+ description: Interface power supply (1.8V)
+
+ dvdd-supply:
+ description: Digital power supply (1.2V)
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the XCLR pin, if any.
+ maxItems: 1
+
+ port:
+ additionalProperties: false
+ $ref: /schemas/graph.yaml#/$defs/port-base
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes: true
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@1a {
+ compatible = "sony,imx335";
+ reg = <0x1a>;
+ clocks = <&imx335_clk>;
+
+ avdd-supply = <&camera_vdda_2v9>;
+ ovdd-supply = <&camera_vddo_1v8>;
+ dvdd-supply = <&camera_vddd_1v2>;
+
+ reset-gpios = <&gpio 50 GPIO_ACTIVE_LOW>;
+
+ port {
+ imx335: endpoint {
+ remote-endpoint = <&cam>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <594000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml
new file mode 100644
index 000000000000..5447ab0768a6
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx412.yaml
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (C) 2021 Intel Corporation
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx412.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX412 Sensor
+
+maintainers:
+ - Paul J. Murphy <paul.j.murphy@intel.com>
+ - Daniele Alessandrelli <daniele.alessandrelli@intel.com>
+
+description:
+ IMX412 sensor is a Sony CMOS active pixel digital image sensor with an active
+ array size of 4072H x 3176V. It is programmable through I2C interface. The
+ I2C client address is fixed to 0x1a as per sensor data sheet. Image data is
+ sent through MIPI CSI-2.
+
+properties:
+ compatible:
+ enum:
+ - sony,imx412
+ - sony,imx577
+ reg:
+ description: I2C address
+ maxItems: 1
+
+ clocks:
+ description: Clock frequency 6MHz, 12MHz, 18MHz, 24MHz or 27MHz
+ maxItems: 1
+
+ dovdd-supply:
+ description: Interface power supply.
+
+ avdd-supply:
+ description: Analog power supply.
+
+ dvdd-supply:
+ description: Digital power supply.
+
+ reset-gpios:
+ description: Reference to the GPIO connected to the XCLR pin, if any.
+ maxItems: 1
+
+ port:
+ additionalProperties: false
+ $ref: /schemas/graph.yaml#/$defs/port-base
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes: true
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@1a {
+ compatible = "sony,imx412";
+ reg = <0x1a>;
+ clocks = <&imx412_clk>;
+
+ port {
+ imx412: endpoint {
+ remote-endpoint = <&cam>;
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <600000000>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml
new file mode 100644
index 000000000000..7c11e871dca6
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/sony,imx415.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Sony IMX415 CMOS Image Sensor
+
+maintainers:
+ - Michael Riesch <michael.riesch@collabora.com>
+
+description: |-
+ The Sony IMX415 is a diagonal 6.4 mm (Type 1/2.8) CMOS active pixel type
+ solid-state image sensor with a square pixel array and 8.46 M effective
+ pixels. This chip operates with analog 2.9 V, digital 1.1 V, and interface
+ 1.8 V triple power supply, and has low power consumption.
+ The IMX415 is programmable through I2C interface. The sensor output is
+ available via CSI-2 serial data output (two or four lanes).
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: sony,imx415
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description: Input clock (24 MHz, 27 MHz, 37.125 MHz, 72 MHz or 74.25 MHz)
+ maxItems: 1
+
+ avdd-supply:
+ description: Analog power supply (2.9 V)
+
+ dvdd-supply:
+ description: Digital power supply (1.1 V)
+
+ ovdd-supply:
+ description: Interface power supply (1.8 V)
+
+ reset-gpios:
+ description: Sensor reset (XCLR) GPIO
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ oneOf:
+ - items:
+ - const: 1
+ - const: 2
+ - items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - endpoint
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - avdd-supply
+ - dvdd-supply
+ - ovdd-supply
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ imx415: camera-sensor@1a {
+ compatible = "sony,imx415";
+ reg = <0x1a>;
+ avdd-supply = <&vcc2v9_cam>;
+ clocks = <&clock_cam>;
+ dvdd-supply = <&vcc1v1_cam>;
+ lens-focus = <&vcm>;
+ orientation = <2>;
+ ovdd-supply = <&vcc1v8_cam>;
+ reset-gpios = <&gpio_expander 14 GPIO_ACTIVE_LOW>;
+ rotation = <180>;
+
+ port {
+ imx415_ep: endpoint {
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <445500000>;
+ remote-endpoint = <&mipi_in>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt
deleted file mode 100644
index 7976e6c40a80..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt
+++ /dev/null
@@ -1,82 +0,0 @@
-STMicroelectronics MIPID02 CSI-2 to PARALLEL bridge
-
-MIPID02 has two CSI-2 input ports, only one of those ports can be active at a
-time. Active port input stream will be de-serialized and its content outputted
-through PARALLEL output port.
-CSI-2 first input port is a dual lane 800Mbps per lane whereas CSI-2 second
-input port is a single lane 800Mbps. Both ports support clock and data lane
-polarity swap. First port also supports data lane swap.
-PARALLEL output port has a maximum width of 12 bits.
-Supported formats are RAW6, RAW7, RAW8, RAW10, RAW12, RGB565, RGB888, RGB444,
-YUV420 8-bit, YUV422 8-bit and YUV420 10-bit.
-
-Required Properties:
-- compatible: shall be "st,st-mipid02"
-- clocks: reference to the xclk input clock.
-- clock-names: shall be "xclk".
-- VDDE-supply: sensor digital IO supply. Must be 1.8 volts.
-- VDDIN-supply: sensor internal regulator supply. Must be 1.8 volts.
-
-Optional Properties:
-- reset-gpios: reference to the GPIO connected to the xsdn pin, if any.
- This is an active low signal to the mipid02.
-
-Required subnodes:
- - ports: A ports node with one port child node per device input and output
- port, in accordance with the video interface bindings defined in
- Documentation/devicetree/bindings/media/video-interfaces.txt. The
- port nodes are numbered as follows:
-
- Port Description
- -----------------------------
- 0 CSI-2 first input port
- 1 CSI-2 second input port
- 2 PARALLEL output
-
-Endpoint node required property for CSI-2 connection is:
-- data-lanes: shall be <1> for Port 1. for Port 0 dual-lane operation shall be
-<1 2> or <2 1>. For Port 0 single-lane operation shall be <1> or <2>.
-Endpoint node optional property for CSI-2 connection is:
-- lane-polarities: any lane can be inverted or not.
-
-Endpoint node required property for PARALLEL connection is:
-- bus-width: shall be set to <6>, <7>, <8>, <10> or <12>.
-Endpoint node optional properties for PARALLEL connection are:
-- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
-LOW being the default.
-- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively.
-LOW being the default.
-
-Example:
-
-mipid02: csi2rx@14 {
- compatible = "st,st-mipid02";
- reg = <0x14>;
- status = "okay";
- clocks = <&clk_ext_camera_12>;
- clock-names = "xclk";
- VDDE-supply = <&vdd>;
- VDDIN-supply = <&vdd>;
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
- port@0 {
- reg = <0>;
-
- ep0: endpoint {
- data-lanes = <1 2>;
- remote-endpoint = <&mipi_csi2_in>;
- };
- };
- port@2 {
- reg = <2>;
-
- ep2: endpoint {
- bus-width = <8>;
- hsync-active = <0>;
- vsync-active = <0>;
- remote-endpoint = <&parallel_out>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml
new file mode 100644
index 000000000000..4d40e75b4e1e
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.yaml
@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/st,st-mipid02.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics MIPID02 CSI-2 to PARALLEL bridge
+
+maintainers:
+ - Benjamin Mugnier <benjamin.mugnier@foss.st.com>
+ - Sylvain Petinot <sylvain.petinot@foss.st.com>
+
+description:
+ MIPID02 has two CSI-2 input ports, only one of those ports can be
+ active at a time. Active port input stream will be de-serialized
+ and its content outputted through PARALLEL output port.
+ CSI-2 first input port is a dual lane 800Mbps per lane whereas CSI-2
+ second input port is a single lane 800Mbps. Both ports support clock
+ and data lane polarity swap. First port also supports data lane swap.
+ PARALLEL output port has a maximum width of 12 bits.
+ Supported formats are RAW6, RAW7, RAW8, RAW10, RAW12, RGB565, RGB888,
+ RGB444, YUV420 8-bit, YUV422 8-bit and YUV420 10-bit.
+
+properties:
+ compatible:
+ const: st,st-mipid02
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ const: xclk
+
+ VDDE-supply:
+ description:
+ Sensor digital IO supply. Must be 1.8 volts.
+
+ VDDIN-supply:
+ description:
+ Sensor internal regulator supply. Must be 1.8 volts.
+
+ reset-gpios:
+ description:
+ Reference to the GPIO connected to the xsdn pin, if any.
+ This is an active low signal to the mipid02.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 first input port
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ description:
+ Single-lane operation shall be <1> or <2> .
+ Dual-lane operation shall be <1 2> or <2 1> .
+ minItems: 1
+ maxItems: 2
+
+ lane-polarities:
+ description:
+ Any lane can be inverted or not.
+ minItems: 1
+ maxItems: 3
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 second input port
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ description:
+ Single-lane operation shall be <1> or <2> .
+ maxItems: 1
+
+ lane-polarities:
+ description:
+ Any lane can be inverted or not.
+ maxItems: 1
+
+ required:
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: Output port
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-width:
+ enum: [6, 7, 8, 10, 12]
+
+ required:
+ - bus-width
+
+ anyOf:
+ - required:
+ - port@0
+ - required:
+ - port@1
+
+ required:
+ - port@2
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - VDDE-supply
+ - VDDIN-supply
+ - ports
+
+examples:
+ - |
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ mipid02: csi2rx@14 {
+ compatible = "st,st-mipid02";
+ reg = <0x14>;
+ clocks = <&clk_ext_camera_12>;
+ clock-names = "xclk";
+ VDDE-supply = <&vdd>;
+ VDDIN-supply = <&vdd>;
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ port@0 {
+ reg = <0>;
+
+ ep0: endpoint {
+ data-lanes = <1 2>;
+ remote-endpoint = <&mipi_csi2_in>;
+ };
+ };
+ port@2 {
+ reg = <2>;
+
+ ep2: endpoint {
+ bus-width = <8>;
+ hsync-active = <0>;
+ vsync-active = <0>;
+ remote-endpoint = <&parallel_out>;
+ };
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml b/Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml
new file mode 100644
index 000000000000..8c28848b226a
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/st,st-vgxy61.yaml
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2022 STMicroelectronics SA.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/st,st-vgxy61.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics VGxy61 HDR Global Shutter Sensor Family
+
+maintainers:
+ - Benjamin Mugnier <benjamin.mugnier@foss.st.com>
+ - Sylvain Petinot <sylvain.petinot@foss.st.com>
+
+description: |-
+ STMicroelectronics VGxy61 family has a CSI-2 output port. CSI-2 output is a
+ quad lanes 800Mbps per lane.
+ Supported formats are RAW8, RAW10, RAW12, RAW14 and RAW16.
+ Following part number are supported
+ - VG5661 and VG6661 are 1.6 Mpx (1464 x 1104) monochrome and color sensors.
+ Maximum frame rate is 75 fps.
+ - VG5761 and VG6761 are 2.3 Mpx (1944 x 1204) monochrome and color sensors.
+ Maximum frame rate is 60 fps.
+
+properties:
+ compatible:
+ const: st,st-vgxy61
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ VCORE-supply:
+ description:
+ Sensor digital core supply. Must be 1.2 volts.
+
+ VDDIO-supply:
+ description:
+ Sensor digital IO supply. Must be 1.8 volts.
+
+ VANA-supply:
+ description:
+ Sensor analog supply. Must be 2.8 volts.
+
+ reset-gpios:
+ description:
+ Reference to the GPIO connected to the reset pin, if any.
+ This is an active low signal to the vgxy61.
+
+ st,strobe-gpios-polarity:
+ description:
+ Invert polarity of illuminator's lights strobe GPIOs.
+ These GPIOs directly drive the illuminator LEDs.
+ type: boolean
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ description:
+ CSI lanes to use
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ remote-endpoint: true
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - clocks
+ - VCORE-supply
+ - VDDIO-supply
+ - VANA-supply
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ vgxy61: csi2tx@10 {
+ compatible = "st,st-vgxy61";
+ reg = <0x10>;
+ clocks = <&clk_ext_camera>;
+ VCORE-supply = <&v1v2>;
+ VDDIO-supply = <&v1v8>;
+ VANA-supply = <&v2v8>;
+ reset-gpios = <&mfxgpio 18 GPIO_ACTIVE_LOW>;
+ port {
+ ep0: endpoint {
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&mipi_csi2_out>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/st,vd55g1.yaml b/Documentation/devicetree/bindings/media/i2c/st,vd55g1.yaml
new file mode 100644
index 000000000000..060ac6829b66
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/st,vd55g1.yaml
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2025 STMicroelectronics SA.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/st,vd55g1.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics VD55G1 Global Shutter Image Sensor
+
+maintainers:
+ - Benjamin Mugnier <benjamin.mugnier@foss.st.com>
+ - Sylvain Petinot <sylvain.petinot@foss.st.com>
+
+description: |-
+ The STMicroelectronics VD55G1 is a global shutter image sensor with an active
+ array size of 804H x 704V. It is programmable through I2C interface. The I2C
+ address is fixed to 0x10.
+
+ Image data is sent through MIPI CSI-2, which is configured as only 1 data
+ lane. The sensor provides 4 GPIOS that can be used for external LED signal
+ (synchronized with sensor integration periods).
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ enum:
+ - st,vd55g1
+ - st,vd65g4
+ description:
+ VD55G1 is the monochrome variant, while VD65G4 is the color one.
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ vcore-supply:
+ description: Digital core power supply (1.15V)
+
+ vddio-supply:
+ description: Digital IO power supply (1.8V)
+
+ vana-supply:
+ description: Analog power supply (2.8V)
+
+ reset-gpios:
+ description: Sensor reset active low GPIO (XSHUTDOWN)
+ maxItems: 1
+
+ st,leds:
+ description:
+ List sensor's GPIOs used to control strobe light sources during exposure
+ time. The numbers identify the sensor pin on which the illumination
+ system is connected. GPIOs are active-high.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 4
+ items:
+ minimum: 0
+ maximum: 3
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ items:
+ - const: 1
+
+ link-frequencies:
+ maxItems: 1
+ items:
+ minimum: 125000000
+ maximum: 600000000
+
+ lane-polarities:
+ minItems: 1
+ maxItems: 2
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vcore-supply
+ - vddio-supply
+ - vana-supply
+ - reset-gpios
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera-sensor@10 {
+ compatible = "st,vd55g1";
+ reg = <0x10>;
+
+ clocks = <&camera_clk_12M>;
+
+ vcore-supply = <&camera_vcore_v1v15>;
+ vddio-supply = <&camera_vddio_v1v8>;
+ vana-supply = <&camera_vana_v2v8>;
+
+ reset-gpios = <&gpio 5 GPIO_ACTIVE_LOW>;
+ st,leds = <2>;
+
+ orientation = <2>;
+ rotation = <0>;
+
+ port {
+ endpoint {
+ data-lanes = <1>;
+ link-frequencies = /bits/ 64 <600000000>;
+ remote-endpoint = <&csiphy0_ep>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/st,vd56g3.yaml b/Documentation/devicetree/bindings/media/i2c/st,vd56g3.yaml
new file mode 100644
index 000000000000..c6673b8539db
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/st,vd56g3.yaml
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (c) 2024 STMicroelectronics SA.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/st,vd56g3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics VD56G3 Global Shutter Image Sensor
+
+maintainers:
+ - Benjamin Mugnier <benjamin.mugnier@foss.st.com>
+ - Sylvain Petinot <sylvain.petinot@foss.st.com>
+
+description: |-
+ The STMicroelectronics VD56G3 is a 1.5 M pixel global shutter image sensor
+ with an active array size of 1124 x 1364 (portrait orientation). It is
+ programmable through I2C, the address is fixed to 0x10. The sensor output is
+ available via CSI-2, which is configured as either 1 or 2 data lanes. The
+ sensor provides 8 GPIOS that can be used for external LED signal
+ (synchronized with sensor integration periods)
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ enum:
+ - st,vd56g3
+ - st,vd66gy
+ description:
+ Two variants are availables; VD56G3 is a monochrome sensor while VD66GY
+ is a colour variant.
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ vcore-supply:
+ description: Digital core power supply (1.15V)
+
+ vddio-supply:
+ description: Digital IO power supply (1.8V)
+
+ vana-supply:
+ description: Analog power supply (2.8V)
+
+ reset-gpios:
+ description: Sensor reset active low GPIO (XSHUTDOWN)
+ maxItems: 1
+
+ st,leds:
+ description:
+ List sensor's GPIOs used to control strobe light sources during exposure
+ time. The numbers identify the sensor pin on which the illumination system
+ is connected. GPIOs are active-high.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+ items:
+ minimum: 0
+ maximum: 7
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 2
+ items:
+ enum: [1, 2]
+
+ link-frequencies:
+ maxItems: 1
+ items:
+ enum: [402000000, 750000000]
+
+ lane-polarities:
+ minItems: 1
+ maxItems: 3
+ description: Any lane can be inverted or not.
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - vcore-supply
+ - vddio-supply
+ - vana-supply
+ - reset-gpios
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera-sensor@10 {
+ compatible = "st,vd56g3";
+ reg = <0x10>;
+
+ clocks = <&camera_clk_12M>;
+
+ vcore-supply = <&camera_vcore_v1v15>;
+ vddio-supply = <&camera_vddio_v1v8>;
+ vana-supply = <&camera_vana_v2v8>;
+
+ reset-gpios = <&gpio 5 GPIO_ACTIVE_LOW>;
+ st,leds = <6>;
+
+ orientation = <2>;
+ rotation = <0>;
+
+ port {
+ endpoint {
+ data-lanes = <1 2>;
+ link-frequencies = /bits/ 64 <402000000>;
+ remote-endpoint = <&csiphy0_ep>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/tda1997x.txt b/Documentation/devicetree/bindings/media/i2c/tda1997x.txt
deleted file mode 100644
index e76167999d76..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/tda1997x.txt
+++ /dev/null
@@ -1,178 +0,0 @@
-Device-Tree bindings for the NXP TDA1997x HDMI receiver
-
-The TDA19971/73 are HDMI video receivers.
-
-The TDA19971 Video port output pins can be used as follows:
- - RGB 8bit per color (24 bits total): R[11:4] B[11:4] G[11:4]
- - YUV444 8bit per color (24 bits total): Y[11:4] Cr[11:4] Cb[11:4]
- - YUV422 semi-planar 8bit per component (16 bits total): Y[11:4] CbCr[11:4]
- - YUV422 semi-planar 10bit per component (20 bits total): Y[11:2] CbCr[11:2]
- - YUV422 semi-planar 12bit per component (24 bits total): - Y[11:0] CbCr[11:0]
- - YUV422 BT656 8bit per component (8 bits total): YCbCr[11:4] (2-cycles)
- - YUV422 BT656 10bit per component (10 bits total): YCbCr[11:2] (2-cycles)
- - YUV422 BT656 12bit per component (12 bits total): YCbCr[11:0] (2-cycles)
-
-The TDA19973 Video port output pins can be used as follows:
- - RGB 12bit per color (36 bits total): R[11:0] B[11:0] G[11:0]
- - YUV444 12bit per color (36 bits total): Y[11:0] Cb[11:0] Cr[11:0]
- - YUV422 semi-planar 12bit per component (24 bits total): Y[11:0] CbCr[11:0]
- - YUV422 BT656 12bit per component (12 bits total): YCbCr[11:0] (2-cycles)
-
-The Video port output pins are mapped via 4-bit 'pin groups' allowing
-for a variety of connection possibilities including swapping pin order within
-pin groups. The video_portcfg device-tree property consists of register mapping
-pairs which map a chip-specific VP output register to a 4-bit pin group. If
-the pin group needs to be bit-swapped you can use the *_S pin-group defines.
-
-Required Properties:
- - compatible :
- - "nxp,tda19971" for the TDA19971
- - "nxp,tda19973" for the TDA19973
- - reg : I2C slave address
- - interrupts : The interrupt number
- - DOVDD-supply : Digital I/O supply
- - DVDD-supply : Digital Core supply
- - AVDD-supply : Analog supply
- - nxp,vidout-portcfg : array of pairs mapping VP output pins to pin groups.
-
-Optional Properties:
- - nxp,audout-format : DAI bus format: "i2s" or "spdif".
- - nxp,audout-width : width of audio output data bus (1-4).
- - nxp,audout-layout : data layout (0=AP0 used, 1=AP0/AP1/AP2/AP3 used).
- - nxp,audout-mclk-fs : Multiplication factor between stream rate and codec
- mclk.
-
-The port node shall contain one endpoint child node for its digital
-output video port, in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-Optional Endpoint Properties:
- The following three properties are defined in video-interfaces.txt and
- are valid for the output parallel bus endpoint:
- - hsync-active: Horizontal synchronization polarity. Defaults to active high.
- - vsync-active: Vertical synchronization polarity. Defaults to active high.
- - data-active: Data polarity. Defaults to active high.
-
-Examples:
- - VP[15:0] connected to IMX6 CSI_DATA[19:4] for 16bit YUV422
- 16bit I2S layout0 with a 128*fs clock (A_WS, AP0, A_CLK pins)
- hdmi-receiver@48 {
- compatible = "nxp,tda19971";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_tda1997x>;
- reg = <0x48>;
- interrupt-parent = <&gpio1>;
- interrupts = <7 IRQ_TYPE_LEVEL_LOW>;
- DOVDD-supply = <&reg_3p3v>;
- AVDD-supply = <&reg_1p8v>;
- DVDD-supply = <&reg_1p8v>;
- /* audio */
- #sound-dai-cells = <0>;
- nxp,audout-format = "i2s";
- nxp,audout-layout = <0>;
- nxp,audout-width = <16>;
- nxp,audout-mclk-fs = <128>;
- /*
- * The 8bpp YUV422 semi-planar mode outputs CbCr[11:4]
- * and Y[11:4] across 16bits in the same pixclk cycle.
- */
- nxp,vidout-portcfg =
- /* Y[11:8]<->VP[15:12]<->CSI_DATA[19:16] */
- < TDA1997X_VP24_V15_12 TDA1997X_G_Y_11_8 >,
- /* Y[7:4]<->VP[11:08]<->CSI_DATA[15:12] */
- < TDA1997X_VP24_V11_08 TDA1997X_G_Y_7_4 >,
- /* CbCc[11:8]<->VP[07:04]<->CSI_DATA[11:8] */
- < TDA1997X_VP24_V07_04 TDA1997X_R_CR_CBCR_11_8 >,
- /* CbCr[7:4]<->VP[03:00]<->CSI_DATA[7:4] */
- < TDA1997X_VP24_V03_00 TDA1997X_R_CR_CBCR_7_4 >;
-
- port {
- tda1997x_to_ipu1_csi0_mux: endpoint {
- remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>;
- bus-width = <16>;
- hsync-active = <1>;
- vsync-active = <1>;
- data-active = <1>;
- };
- };
- };
- - VP[15:8] connected to IMX6 CSI_DATA[19:12] for 8bit BT656
- 16bit I2S layout0 with a 128*fs clock (A_WS, AP0, A_CLK pins)
- hdmi-receiver@48 {
- compatible = "nxp,tda19971";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_tda1997x>;
- reg = <0x48>;
- interrupt-parent = <&gpio1>;
- interrupts = <7 IRQ_TYPE_LEVEL_LOW>;
- DOVDD-supply = <&reg_3p3v>;
- AVDD-supply = <&reg_1p8v>;
- DVDD-supply = <&reg_1p8v>;
- /* audio */
- #sound-dai-cells = <0>;
- nxp,audout-format = "i2s";
- nxp,audout-layout = <0>;
- nxp,audout-width = <16>;
- nxp,audout-mclk-fs = <128>;
- /*
- * The 8bpp YUV422 semi-planar mode outputs CbCr[11:4]
- * and Y[11:4] across 16bits in the same pixclk cycle.
- */
- nxp,vidout-portcfg =
- /* Y[11:8]<->VP[15:12]<->CSI_DATA[19:16] */
- < TDA1997X_VP24_V15_12 TDA1997X_G_Y_11_8 >,
- /* Y[7:4]<->VP[11:08]<->CSI_DATA[15:12] */
- < TDA1997X_VP24_V11_08 TDA1997X_G_Y_7_4 >,
- /* CbCc[11:8]<->VP[07:04]<->CSI_DATA[11:8] */
- < TDA1997X_VP24_V07_04 TDA1997X_R_CR_CBCR_11_8 >,
- /* CbCr[7:4]<->VP[03:00]<->CSI_DATA[7:4] */
- < TDA1997X_VP24_V03_00 TDA1997X_R_CR_CBCR_7_4 >;
-
- port {
- tda1997x_to_ipu1_csi0_mux: endpoint {
- remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>;
- bus-width = <16>;
- hsync-active = <1>;
- vsync-active = <1>;
- data-active = <1>;
- };
- };
- };
- - VP[15:8] connected to IMX6 CSI_DATA[19:12] for 8bit BT656
- 16bit I2S layout0 with a 128*fs clock (A_WS, AP0, A_CLK pins)
- hdmi-receiver@48 {
- compatible = "nxp,tda19971";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_tda1997x>;
- reg = <0x48>;
- interrupt-parent = <&gpio1>;
- interrupts = <7 IRQ_TYPE_LEVEL_LOW>;
- DOVDD-supply = <&reg_3p3v>;
- AVDD-supply = <&reg_1p8v>;
- DVDD-supply = <&reg_1p8v>;
- /* audio */
- #sound-dai-cells = <0>;
- nxp,audout-format = "i2s";
- nxp,audout-layout = <0>;
- nxp,audout-width = <16>;
- nxp,audout-mclk-fs = <128>;
- /*
- * The 8bpp BT656 mode outputs YCbCr[11:4] across 8bits over
- * 2 pixclk cycles.
- */
- nxp,vidout-portcfg =
- /* YCbCr[11:8]<->VP[15:12]<->CSI_DATA[19:16] */
- < TDA1997X_VP24_V15_12 TDA1997X_R_CR_CBCR_11_8 >,
- /* YCbCr[7:4]<->VP[11:08]<->CSI_DATA[15:12] */
- < TDA1997X_VP24_V11_08 TDA1997X_R_CR_CBCR_7_4 >,
-
- port {
- tda1997x_to_ipu1_csi0_mux: endpoint {
- remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>;
- bus-width = <16>;
- hsync-active = <1>;
- vsync-active = <1>;
- data-active = <1>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml b/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml
new file mode 100644
index 000000000000..0592d0b9af92
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/techwell,tw9900.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Techwell TW9900 NTSC/PAL video decoder
+
+maintainers:
+ - Mehdi Djait <mehdi.djait@bootlin.com>
+
+description:
+ The tw9900 is a multi-standard video decoder, supporting NTSC, PAL standards
+ with auto-detection features.
+
+properties:
+ compatible:
+ const: techwell,tw9900
+
+ reg:
+ maxItems: 1
+
+ vdd-supply:
+ description: VDD power supply
+
+ reset-gpios:
+ description: GPIO descriptor for the RESET input pin
+ maxItems: 1
+
+ powerdown-gpios:
+ description: GPIO descriptor for the POWERDOWN input pin
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Analog input port
+
+ properties:
+ endpoint@0:
+ $ref: /schemas/graph.yaml#/properties/endpoint
+ description: CVBS over MUX0
+
+ endpoint@1:
+ $ref: /schemas/graph.yaml#/properties/endpoint
+ description: CVBS over MUX1
+
+ endpoint@2:
+ $ref: /schemas/graph.yaml#/properties/endpoint
+ description: Chroma over CIN0 and Y over MUX0
+
+ endpoint@3:
+ $ref: /schemas/graph.yaml#/properties/endpoint
+ description: Chroma over CIN0 and Y over MUX1
+
+ oneOf:
+ - required:
+ - endpoint@0
+ - required:
+ - endpoint@1
+ - required:
+ - endpoint@2
+ - required:
+ - endpoint@3
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Video port for the decoder output.
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - ports
+ - reg
+ - vdd-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/display/sdtv-standards.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ composite_connector {
+ compatible = "composite-video-connector";
+ label = "tv";
+ sdtv-standards = <(SDTV_STD_PAL | SDTV_STD_NTSC)>;
+
+ port {
+ composite_to_tw9900: endpoint {
+ remote-endpoint = <&tw9900_to_composite>;
+ };
+ };
+ };
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ video-decoder@44 {
+ compatible = "techwell,tw9900";
+ reg = <0x44>;
+
+ vdd-supply = <&tw9900_supply>;
+ reset-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0>;
+ tw9900_to_composite: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&composite_to_tw9900>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ endpoint {
+ remote-endpoint = <&cif_in>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/thine,thp7312.yaml b/Documentation/devicetree/bindings/media/i2c/thine,thp7312.yaml
new file mode 100644
index 000000000000..bc339a7374b2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/thine,thp7312.yaml
@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright (c) 2023 Ideas on Board
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/thine,thp7312.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: THine THP7312
+
+maintainers:
+ - Paul Elder <paul.elder@@ideasonboard.com>
+
+description:
+ The THP7312 is a standalone ISP controlled over i2c, and is capable of
+ various image processing and correction functions, including 3A control. It
+ can be connected to CMOS image sensors from various vendors, supporting both
+ MIPI CSI-2 and parallel interfaces. It can also output on either MIPI CSI-2
+ or parallel. The hardware is capable of transmitting and receiving MIPI
+ interleaved data streams with data types or multiple virtual channel
+ identifiers.
+
+allOf:
+ - $ref: /schemas/media/video-interface-devices.yaml#
+
+properties:
+ compatible:
+ const: thine,thp7312
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description: CLKI clock input
+
+ thine,boot-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ minimum: 0
+ maximum: 1
+ default: 1
+ description:
+ Boot mode of the THP7312, reflecting the value of the BOOT[0] pin strap.
+ 0 is for the SPI/2-wire slave boot, 1 is for the SPI master boot (from
+ external flash ROM).
+
+ reset-gpios:
+ maxItems: 1
+ description:
+ Reference to the GPIO connected to the RESET_N pin, if any.
+ Must be released (set high) after all supplies are applied.
+
+ vddcore-supply:
+ description:
+ 1.2V supply for core, PLL, MIPI rx and MIPI tx.
+
+ vhtermrx-supply:
+ description:
+ Supply for input (RX). 1.8V for MIPI, or 1.8/2.8/3.3V for parallel.
+
+ vddtx-supply:
+ description:
+ Supply for output (TX). 1.8V for MIPI, or 1.8/2.8/3.3V for parallel.
+
+ vddhost-supply:
+ description:
+ Supply for host interface. 1.8V, 2.8V, or 3.3V.
+
+ vddcmos-supply:
+ description:
+ Supply for sensor interface. 1.8V, 2.8V, or 3.3V.
+
+ vddgpio-0-supply:
+ description:
+ Supply for GPIO_0. 1.8V, 2.8V, or 3.3V.
+
+ vddgpio-1-supply:
+ description:
+ Supply for GPIO_1. 1.8V, 2.8V, or 3.3V.
+
+ orientation: true
+ rotation: true
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ const: 4 # CSI-2 D-PHY
+
+ data-lanes:
+ description:
+ This property is for lane reordering between the THP7312 and the
+ SoC. The sensor supports either two-lane, or four-lane operation.
+ If this property is omitted four-lane operation is assumed. For
+ two-lane operation the property must be set to <1 2>.
+ minItems: 2
+ maxItems: 4
+ items:
+ maximum: 4
+
+ sensors:
+ type: object
+ description: List of connected sensors
+
+ properties:
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+ patternProperties:
+ "^sensor@[01]$":
+ type: object
+ description:
+ Sensors connected to the first and second input, with one node per
+ sensor.
+
+ properties:
+ thine,model:
+ $ref: /schemas/types.yaml#/definitions/string
+ description:
+ Model of the connected sensors. Must be a valid compatible string.
+
+ reg:
+ description: THP7312 input port number
+ items:
+ - maximum: 1
+
+ data-lanes:
+ $ref: /schemas/media/video-interfaces.yaml#/properties/data-lanes
+ maxItems: 4
+ description:
+ This property is for lane reordering between the THP7312 and the imaging
+ sensor that it is connected to.
+
+ required:
+ - reg
+ - data-lanes
+
+ additionalProperties: false
+
+ required:
+ - "#address-cells"
+ - "#size-cells"
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - reset-gpios
+ - clocks
+ - vddcore-supply
+ - vhtermrx-supply
+ - vddtx-supply
+ - vddhost-supply
+ - vddcmos-supply
+ - vddgpio-0-supply
+ - vddgpio-1-supply
+ - sensors
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ camera@61 {
+ compatible = "thine,thp7312";
+ reg = <0x61>;
+
+ pinctrl-names = "default";
+ pinctrl-0 = <&cam1_pins_default>;
+
+ reset-gpios = <&pio 119 GPIO_ACTIVE_LOW>;
+ clocks = <&camera61_clk>;
+
+ vddcore-supply = <&vsys_v4p2>;
+ vhtermrx-supply = <&vsys_v4p2>;
+ vddtx-supply = <&vsys_v4p2>;
+ vddhost-supply = <&vsys_v4p2>;
+ vddcmos-supply = <&vsys_v4p2>;
+ vddgpio-0-supply = <&vsys_v4p2>;
+ vddgpio-1-supply = <&vsys_v4p2>;
+
+ orientation = <0>;
+ rotation = <0>;
+
+ sensors {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@0 {
+ thine,model = "sony,imx258";
+ reg = <0>;
+
+ data-lanes = <4 1 3 2>;
+ };
+ };
+
+ port {
+ thp7312_2_endpoint: endpoint {
+ remote-endpoint = <&mipi_thp7312_2>;
+ bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>;
+ data-lanes = <4 2 1 3>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml
new file mode 100644
index 000000000000..f6612bb0f667
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub913.yaml
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub913.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments DS90UB913 FPD-Link III Serializer
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+
+description:
+ The TI DS90UB913 is an FPD-Link III video serializer for parallel video.
+
+properties:
+ compatible:
+ enum:
+ - ti,ds90ub913a-q1
+
+ '#gpio-cells':
+ const: 2
+ description:
+ First cell is the GPO pin number, second cell is the flags. The GPO pin
+ number must be in range of [0, 3]. Note that GPOs 2 and 3 are not
+ available in external oscillator mode.
+
+ gpio-controller: true
+
+ clocks:
+ maxItems: 1
+ description:
+ Reference clock connected to the CLKIN pin.
+
+ clock-names:
+ items:
+ - const: clkin
+
+ '#clock-cells':
+ const: 0
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: Parallel input port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ required:
+ - pclk-sample
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ unevaluatedProperties: false
+ description: FPD-Link III output port
+
+ required:
+ - port@0
+ - port@1
+
+ i2c:
+ $ref: /schemas/i2c/i2c-controller.yaml#
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - '#gpio-cells'
+ - gpio-controller
+ - '#clock-cells'
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ serializer {
+ compatible = "ti,ds90ub913a-q1";
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ clocks = <&clk_cam_48M>;
+ clock-names = "clkin";
+
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ ub913_in: endpoint {
+ remote-endpoint = <&sensor_out>;
+ pclk-sample = <1>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ endpoint {
+ remote-endpoint = <&deser_fpd_in>;
+ };
+ };
+ };
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@48 {
+ compatible = "aptina,mt9v111";
+ reg = <0x48>;
+
+ clocks = <&fixed_clock>;
+
+ port {
+ sensor_out: endpoint {
+ remote-endpoint = <&ub913_in>;
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml
new file mode 100644
index 000000000000..2e129bf573b7
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub953.yaml
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub953.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments DS90UB953 FPD-Link III Serializer
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+
+description:
+ The TI DS90UB953 is an FPD-Link III video serializer for MIPI CSI-2.
+
+properties:
+ compatible:
+ enum:
+ - ti,ds90ub953-q1
+ - ti,ds90ub971-q1
+
+ '#gpio-cells':
+ const: 2
+ description:
+ First cell is the GPIO pin number, second cell is the flags. The GPIO pin
+ number must be in range of [0, 3].
+
+ gpio-controller: true
+
+ clocks:
+ maxItems: 1
+ description:
+ Reference clock connected to the CLKIN pin.
+
+ clock-names:
+ items:
+ - const: clkin
+
+ '#clock-cells':
+ const: 0
+
+ reg:
+ maxItems: 1
+ description:
+ The strap I2C address of the serializer. Can be used by the deserializer
+ to communicate over back-channel when the forward-channel is not yet
+ active.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 input port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ unevaluatedProperties: false
+ description: FPD-Link III output port
+
+ required:
+ - port@0
+ - port@1
+
+ i2c:
+ $ref: /schemas/i2c/i2c-controller.yaml#
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - '#gpio-cells'
+ - gpio-controller
+ - '#clock-cells'
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ link {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ serializer@18 {
+ compatible = "ti,ds90ub953-q1";
+ reg = <0x18>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ ub953_in: endpoint {
+ clock-lanes = <0>;
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&sensor_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ endpoint {
+ remote-endpoint = <&deser_fpd_in>;
+ };
+ };
+ };
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@1a {
+ compatible = "sony,imx274";
+ reg = <0x1a>;
+
+ reset-gpios = <&serializer 0 GPIO_ACTIVE_LOW>;
+
+ clocks = <&serializer>;
+ clock-names = "inck";
+
+ port {
+ sensor_out: endpoint {
+ remote-endpoint = <&ub953_in>;
+ };
+ };
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
new file mode 100644
index 000000000000..0539d52de422
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
@@ -0,0 +1,441 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+
+description:
+ The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
+ forwarding.
+
+allOf:
+ - $ref: /schemas/i2c/i2c-atr.yaml#
+
+properties:
+ compatible:
+ enum:
+ - ti,ds90ub960-q1
+ - ti,ds90ub9702-q1
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+ description:
+ Reference clock connected to the REFCLK pin.
+
+ clock-names:
+ items:
+ - const: refclk
+
+ powerdown-gpios:
+ maxItems: 1
+ description:
+ Specifier for the GPIO connected to the PDB pin.
+
+ i2c-alias-pool:
+ minItems: 1
+ maxItems: 32
+
+ links:
+ type: object
+ additionalProperties: false
+
+ properties:
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ ti,manual-strobe:
+ type: boolean
+ description:
+ Enable manual strobe position and EQ level
+
+ patternProperties:
+ '^link@[0-3]$':
+ type: object
+ additionalProperties: false
+ properties:
+ reg:
+ description: The link number
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ i2c-alias:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ The I2C address used for the serializer. Transactions to this
+ address on the I2C bus where the deserializer resides are
+ forwarded to the serializer.
+
+ ti,rx-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 0 # RAW10
+ - 1 # RAW12 HF
+ - 2 # RAW12 LF
+ - 3 # CSI2 SYNC
+ - 4 # CSI2 NON-SYNC
+ description:
+ FPD-Link Input Mode. This should reflect the hardware and the
+ default mode of the connected device.
+
+ ti,cdr-mode:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum:
+ - 0 # FPD-Link III
+ - 1 # FPD-Link IV
+ description:
+ FPD-Link CDR Mode. This should reflect the hardware and the
+ default mode of the connected device.
+
+ ti,strobe-pos:
+ $ref: /schemas/types.yaml#/definitions/int32
+ minimum: -13
+ maximum: 13
+ description: Manual strobe position
+
+ ti,eq-level:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 14
+ description: Manual EQ level
+
+ patternProperties:
+ '^serializer(@[0-9a-f]+)*$':
+ type: object
+ description: FPD-Link Serializer node
+
+ required:
+ - reg
+ - i2c-alias
+ - ti,rx-mode
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: FPD-Link input 0
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+ description:
+ Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+ hsync-active and vsync-active must be defined.
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: FPD-Link input 1
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+ description:
+ Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+ hsync-active and vsync-active must be defined.
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: FPD-Link input 2
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+ description:
+ Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+ hsync-active and vsync-active must be defined.
+
+ port@3:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: FPD-Link input 3
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+ description:
+ Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+ hsync-active and vsync-active must be defined.
+
+ port@4:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 Output 0
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+ link-frequencies:
+ maxItems: 1
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ port@5:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: CSI-2 Output 1
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+ link-frequencies:
+ maxItems: 1
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - port@0
+ - port@1
+ - port@2
+ - port@3
+ - port@4
+ - port@5
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - ports
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ clock-frequency = <400000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ deser@3d {
+ compatible = "ti,ds90ub960-q1";
+ reg = <0x3d>;
+
+ clock-names = "refclk";
+ clocks = <&fixed_clock>;
+
+ powerdown-gpios = <&pca9555 7 GPIO_ACTIVE_LOW>;
+
+ i2c-alias-pool = <0x4a 0x4b 0x4c 0x4d 0x4e 0x4f>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Port 0, Camera 0 */
+ port@0 {
+ reg = <0>;
+
+ ub960_fpd3_1_in: endpoint {
+ remote-endpoint = <&ub953_1_out>;
+ };
+ };
+
+ /* Port 1, Camera 1 */
+ port@1 {
+ reg = <1>;
+
+ ub960_fpd3_2_in: endpoint {
+ remote-endpoint = <&ub913_2_out>;
+ hsync-active = <0>;
+ vsync-active = <1>;
+ };
+ };
+
+ /* Port 2, unconnected */
+ port@2 {
+ reg = <2>;
+ };
+
+ /* Port 3, unconnected */
+ port@3 {
+ reg = <3>;
+ };
+
+ /* Port 4, CSI-2 TX */
+ port@4 {
+ reg = <4>;
+ ds90ub960_0_csi_out: endpoint {
+ data-lanes = <1 2 3 4>;
+ link-frequencies = /bits/ 64 <800000000>;
+ remote-endpoint = <&csi2_phy0>;
+ };
+ };
+
+ /* Port 5, unconnected */
+ port@5 {
+ reg = <5>;
+ };
+ };
+
+ links {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Link 0 has DS90UB953 serializer and IMX274 sensor */
+
+ link@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <0>;
+ i2c-alias = <0x44>;
+
+ ti,rx-mode = <3>;
+
+ serializer1: serializer@30 {
+ compatible = "ti,ds90ub953-q1";
+ reg = <0x30>;
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ ub953_1_in: endpoint {
+ data-lanes = <1 2 3 4>;
+ remote-endpoint = <&sensor_1_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ ub953_1_out: endpoint {
+ remote-endpoint = <&ub960_fpd3_1_in>;
+ };
+ };
+ };
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@1a {
+ compatible = "sony,imx274";
+ reg = <0x1a>;
+
+ clocks = <&serializer>;
+ clock-names = "inck";
+
+ reset-gpios = <&serializer1 0 GPIO_ACTIVE_LOW>;
+
+ port {
+ sensor_1_out: endpoint {
+ remote-endpoint = <&ub953_1_in>;
+ };
+ };
+ };
+ };
+ };
+ }; /* End of link@0 */
+
+ /* Link 1 has DS90UB913 serializer and MT9V111 sensor */
+
+ link@1 {
+ reg = <1>;
+ i2c-alias = <0x45>;
+
+ ti,rx-mode = <0>;
+
+ serializer2: serializer {
+ compatible = "ti,ds90ub913a-q1";
+
+ gpio-controller;
+ #gpio-cells = <2>;
+
+ clocks = <&clk_cam_48M>;
+ clock-names = "clkin";
+
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ ub913_2_in: endpoint {
+ remote-endpoint = <&sensor_2_out>;
+ pclk-sample = <1>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ ub913_2_out: endpoint {
+ remote-endpoint = <&ub960_fpd3_2_in>;
+ };
+ };
+ };
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sensor@48 {
+ compatible = "aptina,mt9v111";
+ reg = <0x48>;
+
+ clocks = <&serializer2>;
+
+ port {
+ sensor_2_out: endpoint {
+ remote-endpoint = <&ub913_2_in>;
+ };
+ };
+ };
+ };
+ };
+ }; /* End of link@1 */
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/i2c/ths8200.txt b/Documentation/devicetree/bindings/media/i2c/ti,ths8200.txt
index 285f6ae7dfa9..285f6ae7dfa9 100644
--- a/Documentation/devicetree/bindings/media/i2c/ths8200.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ti,ths8200.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/tvp514x.txt b/Documentation/devicetree/bindings/media/i2c/ti,tvp514x.txt
index 46752cc71f2e..46752cc71f2e 100644
--- a/Documentation/devicetree/bindings/media/i2c/tvp514x.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ti,tvp514x.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/ti,tvp5150.yaml b/Documentation/devicetree/bindings/media/i2c/ti,tvp5150.yaml
new file mode 100644
index 000000000000..382a29652a05
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ti,tvp5150.yaml
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ti,tvp5150.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments TVP5150 and TVP5151 video decoders
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+description:
+ The TVP5150 and TVP5151 are video decoders that convert baseband NTSC and PAL
+ (and also SECAM in the TVP5151 case) video signals to either 8-bit 4:2:2 YUV
+ with discrete syncs or 8-bit ITU-R BT.656 with embedded syncs output formats.
+
+properties:
+ compatible:
+ const: ti,tvp5150
+
+ reg:
+ maxItems: 1
+
+ pdn-gpios:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ sink port node, AIP1A
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ sink port node, AIP1B
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ source port node, Y-OUT
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - port@2
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/display/sdtv-standards.h>
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ bridge@5c {
+ compatible = "ti,tvp5150";
+ reg = <0x5c>;
+ pdn-gpios = <&gpio4 30 GPIO_ACTIVE_LOW>;
+ reset-gpios = <&gpio6 7 GPIO_ACTIVE_LOW>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0>;
+
+ endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&composite0_to_tvp5150>;
+ };
+
+ endpoint@1 {
+ reg = <1>;
+ remote-endpoint = <&svideo_luma_to_tvp5150>;
+ };
+ };
+
+ port@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <1>;
+
+ endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&composite1_to_tvp5150>;
+ };
+
+ endpoint@1 {
+ reg = <1>;
+ remote-endpoint = <&svideo_chroma_to_tvp5150>;
+ };
+ };
+
+ port@2 {
+ reg = <2>;
+
+ endpoint {
+ remote-endpoint = <&ccdc_ep>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/tvp7002.txt b/Documentation/devicetree/bindings/media/i2c/ti,tvp7002.txt
index 5f28b5d9abcc..5f28b5d9abcc 100644
--- a/Documentation/devicetree/bindings/media/i2c/tvp7002.txt
+++ b/Documentation/devicetree/bindings/media/i2c/ti,tvp7002.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt b/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt
index e80d5891b7ed..8d8e40c56872 100644
--- a/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt
+++ b/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt
@@ -13,9 +13,6 @@ Mandatory properties
- reg: I2C address (0x3e, or an alternative address)
- vana-supply: Analogue voltage supply (VANA), 2.8 volts
- clocks: External clock to the sensor
-- clock-frequency: Frequency of the external clock to the sensor. Camera
- driver will set this frequency on the external clock. The clock frequency is
- a pre-determined frequency known to be suitable to the board.
- reset-gpios: XSHUTDOWN GPIO. The XSHUTDOWN signal is active low. The sensor
is in hardware standby mode when the signal is in the low state.
@@ -43,8 +40,11 @@ Example
compatible = "toshiba,et8ek8";
reg = <0x3e>;
vana-supply = <&vaux4>;
+
clocks = <&isp 0>;
- clock-frequency = <9600000>;
+ assigned-clocks = <&isp 0>;
+ assigned-clock-rates = <9600000>;
+
reset-gpio = <&gpio4 6 GPIO_ACTIVE_HIGH>; /* 102 */
port {
csi_cam1: endpoint {
diff --git a/Documentation/devicetree/bindings/media/i2c/tc358743.txt b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358743.txt
index 59102edcf01e..59102edcf01e 100644
--- a/Documentation/devicetree/bindings/media/i2c/tc358743.txt
+++ b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358743.txt
diff --git a/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml
new file mode 100644
index 000000000000..1c476b635b69
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/toshiba,tc358746.yaml
@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/toshiba,tc358746.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Toshiba TC358746 Parallel to MIPI CSI2 Bridge
+
+maintainers:
+ - Marco Felsch <kernel@pengutronix.de>
+
+description: |-
+ The Toshiba TC358746 converts a parallel video stream into a MIPI CSI-2
+ stream. The direction can be either parallel-in -> csi-out or csi-in ->
+ parallel-out The chip is programmable through I2C and SPI but the SPI
+ interface is only supported in parallel-in -> csi-out mode.
+
+ Note that the current device tree bindings only support the
+ parallel-in -> csi-out path.
+
+properties:
+ compatible:
+ const: toshiba,tc358746
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ description:
+ The phandle to the reference clock source. This corresponds to the
+ hardware pin REFCLK.
+ maxItems: 1
+
+ clock-names:
+ const: refclk
+
+ "#clock-cells":
+ description: |
+ The bridge can act as clock provider for the sensor. To enable this
+ support #clock-cells must be specified. Attention if this feature is used
+ then the mclk rate must be at least: (2 * link-frequency) / 8
+ `------------------´ ^
+ internal PLL rate smallest possible
+ mclk-div
+ const: 0
+
+ clock-output-names:
+ description:
+ The clock name of the MCLK output, the default name is tc358746-mclk.
+ maxItems: 1
+
+ vddc-supply:
+ description: Digital core voltage supply, 1.2 volts
+
+ vddio-supply:
+ description: Digital I/O voltage supply, 1.8 volts
+
+ vddmipi-supply:
+ description: MIPI CSI phy voltage supply, 1.2 volts
+
+ reset-gpios:
+ description:
+ The phandle and specifier for the GPIO that controls the chip reset.
+ This corresponds to the hardware pin RESX which is physically active low.
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: Input port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ hsync-active: true
+ vsync-active: true
+ bus-type:
+ enum: [ 5, 6 ]
+
+ required:
+ - hsync-active
+ - vsync-active
+ - bus-type
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: Output port
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ clock-noncontinuous: true
+ link-frequencies: true
+
+ required:
+ - data-lanes
+ - link-frequencies
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - vddc-supply
+ - vddio-supply
+ - vddmipi-supply
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ csi-bridge@e {
+ compatible = "toshiba,tc358746";
+ reg = <0xe>;
+
+ clocks = <&refclk>;
+ clock-names = "refclk";
+
+ reset-gpios = <&gpio 2 GPIO_ACTIVE_LOW>;
+
+ vddc-supply = <&v1_2d>;
+ vddio-supply = <&v1_8d>;
+ vddmipi-supply = <&v1_2d>;
+
+ /* sensor mclk provider */
+ #clock-cells = <0>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Input */
+ port@0 {
+ reg = <0>;
+ tc358746_in: endpoint {
+ remote-endpoint = <&sensor_out>;
+ hsync-active = <0>;
+ vsync-active = <0>;
+ bus-type = <5>;
+ };
+ };
+
+ /* Output */
+ port@1 {
+ reg = <1>;
+ tc358746_out: endpoint {
+ remote-endpoint = <&mipi_csi2_in>;
+ data-lanes = <1 2>;
+ clock-noncontinuous;
+ link-frequencies = /bits/ 64 <216000000>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt
deleted file mode 100644
index 719b2995dc17..000000000000
--- a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt
+++ /dev/null
@@ -1,157 +0,0 @@
-* Texas Instruments TVP5150 and TVP5151 video decoders
-
-The TVP5150 and TVP5151 are video decoders that convert baseband NTSC and PAL
-(and also SECAM in the TVP5151 case) video signals to either 8-bit 4:2:2 YUV
-with discrete syncs or 8-bit ITU-R BT.656 with embedded syncs output formats.
-
-Required Properties:
-====================
-- compatible: Value must be "ti,tvp5150".
-- reg: I2C slave address.
-
-Optional Properties:
-====================
-- pdn-gpios: Phandle for the GPIO connected to the PDN pin, if any.
-- reset-gpios: Phandle for the GPIO connected to the RESETB pin, if any.
-
-The device node must contain one 'port' child node per device physical input
-and output port, in accordance with the video interface bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt. The port nodes
-are numbered as follows
-
- Name Type Port
- --------------------------------------
- AIP1A sink 0
- AIP1B sink 1
- Y-OUT src 2
-
-The device node must contain at least one sink port and the src port. Each input
-port must be linked to an endpoint defined in [1]. The port/connector layout is
-as follows
-
-tvp-5150 port@0 (AIP1A)
- endpoint@0 -----------> Comp0-Con port
- endpoint@1 ------+----> Svideo-Con port
-tvp-5150 port@1 (AIP1B) |
- endpoint@1 ------+
- endpoint@0 -----------> Comp1-Con port
-tvp-5150 port@2
- endpoint (video bitstream output at YOUT[0-7] parallel bus)
-
-Required Endpoint Properties for parallel synchronization on output port:
-=========================================================================
-
-- hsync-active: Active state of the HSYNC signal. Must be <1> (HIGH).
-- vsync-active: Active state of the VSYNC signal. Must be <1> (HIGH).
-- field-even-active: Field signal level during the even field data
- transmission. Must be <0>.
-
-Note: Do not specify any of these properties if you want to use the embedded
- BT.656 synchronization.
-
-Optional Connector Properties:
-==============================
-
-- sdtv-standards: Set the possible signals to which the hardware tries to lock
- instead of using the autodetection mechnism. Please look at
- [1] for more information.
-
-[1] Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml.
-
-Example - three input sources:
-#include <dt-bindings/display/sdtv-standards.h>
-
-comp_connector_0 {
- compatible = "composite-video-connector";
- label = "Composite0";
- sdtv-standards = <SDTV_STD_PAL_M>; /* limit to pal-m signals */
-
- port {
- composite0_to_tvp5150: endpoint {
- remote-endpoint = <&tvp5150_to_composite0>;
- };
- };
-};
-
-comp_connector_1 {
- compatible = "composite-video-connector";
- label = "Composite1";
- sdtv-standards = <SDTV_STD_NTSC_M>; /* limit to ntsc-m signals */
-
- port {
- composite1_to_tvp5150: endpoint {
- remote-endpoint = <&tvp5150_to_composite1>;
- };
- };
-};
-
-svideo_connector {
- compatible = "svideo-connector";
- label = "S-Video";
-
- port {
- #address-cells = <1>;
- #size-cells = <0>;
-
- svideo_luma_to_tvp5150: endpoint@0 {
- reg = <0>;
- remote-endpoint = <&tvp5150_to_svideo_luma>;
- };
-
- svideo_chroma_to_tvp5150: endpoint@1 {
- reg = <1>;
- remote-endpoint = <&tvp5150_to_svideo_chroma>;
- };
- };
-};
-
-&i2c2 {
- tvp5150@5c {
- compatible = "ti,tvp5150";
- reg = <0x5c>;
- pdn-gpios = <&gpio4 30 GPIO_ACTIVE_LOW>;
- reset-gpios = <&gpio6 7 GPIO_ACTIVE_LOW>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <0>;
-
- tvp5150_to_composite0: endpoint@0 {
- reg = <0>;
- remote-endpoint = <&composite0_to_tvp5150>;
- };
-
- tvp5150_to_svideo_luma: endpoint@1 {
- reg = <1>;
- remote-endpoint = <&svideo_luma_to_tvp5150>;
- };
- };
-
- port@1 {
- #address-cells = <1>;
- #size-cells = <0>;
- reg = <1>;
-
- tvp5150_to_composite1: endpoint@0 {
- reg = <0>;
- remote-endpoint = <&composite1_to_tvp5150>;
- };
-
- tvp5150_to_svideo_chroma: endpoint@1 {
- reg = <1>;
- remote-endpoint = <&svideo_chroma_to_tvp5150>;
- };
- };
-
- port@2 {
- reg = <2>;
-
- tvp5150_1: endpoint {
- remote-endpoint = <&ccdc_ep>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/img,e5010-jpeg-enc.yaml b/Documentation/devicetree/bindings/media/img,e5010-jpeg-enc.yaml
new file mode 100644
index 000000000000..085020cb9e61
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/img,e5010-jpeg-enc.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/img,e5010-jpeg-enc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Imagination E5010 JPEG Encoder
+
+maintainers:
+ - Devarsh Thakkar <devarsht@ti.com>
+
+description: |
+ The E5010 is a JPEG encoder from Imagination Technologies implemented on
+ TI's AM62A SoC. It is capable of real time encoding of YUV420 and YUV422
+ inputs to JPEG and M-JPEG. It supports baseline JPEG Encoding up to
+ 8Kx8K resolution.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: ti,am62a-jpeg-enc
+ - const: img,e5010-jpeg-enc
+ - const: img,e5010-jpeg-enc
+
+ reg:
+ items:
+ - description: The E5010 core register region
+ - description: The E5010 mmu register region
+
+ reg-names:
+ items:
+ - const: core
+ - const: mmu
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ jpeg-encoder@fd20000 {
+ compatible = "img,e5010-jpeg-enc";
+ reg = <0x00 0xfd20000 0x00 0x100>,
+ <0x00 0xfd20200 0x00 0x200>;
+ reg-names = "core", "mmu";
+ clocks = <&k3_clks 201 0>;
+ power-domains = <&k3_pds 201 TI_SCI_PD_EXCLUSIVE>;
+ interrupts = <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/imx.txt b/Documentation/devicetree/bindings/media/imx.txt
deleted file mode 100644
index 77f4b0a7fd2b..000000000000
--- a/Documentation/devicetree/bindings/media/imx.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-Freescale i.MX Media Video Device
-=================================
-
-Video Media Controller node
----------------------------
-
-This is the media controller node for video capture support. It is a
-virtual device that lists the camera serial interface nodes that the
-media device will control.
-
-Required properties:
-- compatible : "fsl,imx-capture-subsystem";
-- ports : Should contain a list of phandles pointing to camera
- sensor interface ports of IPU devices
-
-example:
-
-capture-subsystem {
- compatible = "fsl,imx-capture-subsystem";
- ports = <&ipu1_csi0>, <&ipu1_csi1>;
-};
-
-
-mipi_csi2 node
---------------
-
-This is the device node for the MIPI CSI-2 Receiver core in the i.MX
-SoC. This is a Synopsys Designware MIPI CSI-2 host controller core
-combined with a D-PHY core mixed into the same register block. In
-addition this device consists of an i.MX-specific "CSI2IPU gasket"
-glue logic, also controlled from the same register block. The CSI2IPU
-gasket demultiplexes the four virtual channel streams from the host
-controller's 32-bit output image bus onto four 16-bit parallel busses
-to the i.MX IPU CSIs.
-
-Required properties:
-- compatible : "fsl,imx6-mipi-csi2";
-- reg : physical base address and length of the register set;
-- clocks : the MIPI CSI-2 receiver requires three clocks: hsi_tx
- (the D-PHY clock), video_27m (D-PHY PLL reference
- clock), and eim_podf;
-- clock-names : must contain "dphy", "ref", "pix";
-- port@* : five port nodes must exist, containing endpoints
- connecting to the source and sink devices according to
- of_graph bindings. The first port is an input port,
- connecting with a MIPI CSI-2 source, and ports 1
- through 4 are output ports connecting with parallel
- bus sink endpoint nodes and correspond to the four
- MIPI CSI-2 virtual channel outputs.
-
-Optional properties:
-- interrupts : must contain two level-triggered interrupts,
- in order: 100 and 101;
diff --git a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml
index b39b84c5f012..de3e483f146a 100644
--- a/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml
+++ b/Documentation/devicetree/bindings/media/marvell,mmp2-ccic.yaml
@@ -5,7 +5,7 @@
$id: http://devicetree.org/schemas/media/marvell,mmp2-ccic.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Marvell MMP2 camera host interface bindings
+title: Marvell MMP2 camera host interface
maintainers:
- Lubomir Rintel <lkundrak@v3.sk>
@@ -68,6 +68,7 @@ additionalProperties: false
examples:
- |
#include <dt-bindings/clock/marvell,mmp2.h>
+ #include <dt-bindings/media/video-interfaces.h>
#include <dt-bindings/power/marvell,mmp2.h>
camera@d420a000 {
@@ -83,7 +84,7 @@ examples:
port {
camera0_0: endpoint {
remote-endpoint = <&ov7670_0>;
- bus-type = <5>; /* Parallel */
+ bus-type = <MEDIA_BUS_TYPE_PARALLEL>;
hsync-active = <1>; /* Active high */
vsync-active = <1>; /* Active high */
pclk-sample = <0>; /* Falling */
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml
new file mode 100644
index 000000000000..40fda59fa8a8
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-fg.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-fg.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Media Data Path 3 Film Grain
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description:
+ Film Grain (FG) is a Media Data Path 3 (MDP3) component used to add
+ the film grain according to the AOMedia Video 1 (AV1) standard.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8195-mdp3-fg
+ - items:
+ - const: mediatek,mt8188-mdp3-fg
+ - const: mediatek,mt8195-mdp3-fg
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ description:
+ The register of display function block to be set by gce. There are 4 arguments,
+ such as gce node, subsys id, offset and register size. The subsys id that is
+ mapping to the register of display function blocks is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/gce/mt8195-gce.h>
+
+ display@14002000 {
+ compatible = "mediatek,mt8195-mdp3-fg";
+ reg = <0x14002000 0x1000>;
+ mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x2000 0x1000>;
+ clocks = <&vppsys0 CLK_VPP0_MDP_FG>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml
new file mode 100644
index 000000000000..d9f926c20220
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-hdr.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-hdr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Media Data Path 3 HDR
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description:
+ A Media Data Path 3 (MDP3) component used to perform conversion from
+ High Dynamic Range (HDR) to Standard Dynamic Range (SDR).
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8195-mdp3-hdr
+ - items:
+ - const: mediatek,mt8188-mdp3-hdr
+ - const: mediatek,mt8195-mdp3-hdr
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ description:
+ The register of display function block to be set by gce. There are 4 arguments,
+ such as gce node, subsys id, offset and register size. The subsys id that is
+ mapping to the register of display function blocks is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/gce/mt8195-gce.h>
+
+ display@14004000 {
+ compatible = "mediatek,mt8195-mdp3-hdr";
+ reg = <0x14004000 0x1000>;
+ mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x4000 0x1000>;
+ clocks = <&vppsys0 CLK_VPP0_MDP_HDR>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml
new file mode 100644
index 000000000000..18603f6c5e06
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-rdma.yaml
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-rdma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Read Direct Memory Access
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description: |
+ MediaTek Read Direct Memory Access(RDMA) component used to do read DMA.
+ It contains one line buffer to store the sufficient pixel data, and
+ must be siblings to the central MMSYS_CONFIG node.
+ For a description of the MMSYS_CONFIG binding, see
+ Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.yaml
+ for details.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8183-mdp3-rdma
+ - mediatek,mt8188-mdp3-rdma
+ - mediatek,mt8195-mdp3-rdma
+ - mediatek,mt8195-vdo1-rdma
+ - items:
+ - const: mediatek,mt8188-vdo1-rdma
+ - const: mediatek,mt8195-vdo1-rdma
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ description: The register of client driver can be configured by gce with
+ 4 arguments defined in this property. Each GCE subsys id is mapping to
+ a client defined in the header include/dt-bindings/gce/<chip>-gce.h.
+
+ mediatek,gce-events:
+ description:
+ The event id which is mapping to the specific hardware event signal
+ to gce. The event id is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ mediatek,scp:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle to the System Control Processor (SCP) used for initializing
+ and stopping the MDP3, for sending frame data locations to the MDP3's
+ VPU and to install Inter-Processor Interrupt handlers to control
+ processing states.
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: RDMA clock
+ - description: RSZ clock
+ minItems: 1
+
+ iommus:
+ maxItems: 1
+
+ mboxes:
+ items:
+ - description: used for 1st data pipe from RDMA
+ - description: used for 2nd data pipe from RDMA
+ - description: used for 3rd data pipe from RDMA
+ - description: used for 4th data pipe from RDMA
+ - description: used for the data pipe from SPLIT
+ minItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ '#dma-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - power-domains
+ - clocks
+ - iommus
+ - '#dma-cells'
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8183-mdp3-rdma
+
+ then:
+ properties:
+ clocks:
+ minItems: 2
+
+ mboxes:
+ minItems: 2
+
+ required:
+ - mboxes
+ - mediatek,gce-events
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8195-mdp3-rdma
+
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+ mboxes:
+ minItems: 5
+
+ required:
+ - mediatek,gce-events
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8195-vdo1-rdma
+
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8183-clk.h>
+ #include <dt-bindings/gce/mt8183-gce.h>
+ #include <dt-bindings/power/mt8183-power.h>
+ #include <dt-bindings/memory/mt8183-larb-port.h>
+
+ dma-controller@14001000 {
+ compatible = "mediatek,mt8183-mdp3-rdma";
+ reg = <0x14001000 0x1000>;
+ mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x1000 0x1000>;
+ mediatek,gce-events = <CMDQ_EVENT_MDP_RDMA0_SOF>,
+ <CMDQ_EVENT_MDP_RDMA0_EOF>;
+ power-domains = <&spm MT8183_POWER_DOMAIN_DISP>;
+ clocks = <&mmsys CLK_MM_MDP_RDMA0>,
+ <&mmsys CLK_MM_MDP_RSZ1>;
+ iommus = <&iommu>;
+ mboxes = <&gce 20 CMDQ_THR_PRIO_LOWEST>,
+ <&gce 21 CMDQ_THR_PRIO_LOWEST>;
+ #dma-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml
new file mode 100644
index 000000000000..8124c39d73e9
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-rsz.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-rsz.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Resizer
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description: |
+ One of Media Data Path 3 (MDP3) components used to do frame resizing.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8183-mdp3-rsz
+ - items:
+ - enum:
+ - mediatek,mt8188-mdp3-rsz
+ - mediatek,mt8195-mdp3-rsz
+ - const: mediatek,mt8183-mdp3-rsz
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ description: The register of client driver can be configured by gce with
+ 4 arguments defined in this property. Each GCE subsys id is mapping to
+ a client defined in the header include/dt-bindings/gce/<chip>-gce.h.
+
+ mediatek,gce-events:
+ description:
+ The event id which is mapping to the specific hardware event signal
+ to gce. The event id is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ clocks:
+ minItems: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - mediatek,gce-events
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8183-clk.h>
+ #include <dt-bindings/gce/mt8183-gce.h>
+
+ mdp3_rsz0: mdp3-rsz0@14003000 {
+ compatible = "mediatek,mt8183-mdp3-rsz";
+ reg = <0x14003000 0x1000>;
+ mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x3000 0x1000>;
+ mediatek,gce-events = <CMDQ_EVENT_MDP_RSZ0_SOF>,
+ <CMDQ_EVENT_MDP_RSZ0_EOF>;
+ clocks = <&mmsys CLK_MM_MDP_RSZ0>;
+ };
+
+ mdp3_rsz1: mdp3-rsz1@14004000 {
+ compatible = "mediatek,mt8183-mdp3-rsz";
+ reg = <0x14004000 0x1000>;
+ mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x4000 0x1000>;
+ mediatek,gce-events = <CMDQ_EVENT_MDP_RSZ1_SOF>,
+ <CMDQ_EVENT_MDP_RSZ1_EOF>;
+ clocks = <&mmsys CLK_MM_MDP_RSZ1>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml
new file mode 100644
index 000000000000..1d8e7e202c42
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-stitch.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-stitch.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Media Data Path 3 STITCH
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description:
+ One of Media Data Path 3 (MDP3) components used to combine multiple video frame
+ with overlapping fields of view to produce a segmented panorame.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8195-mdp3-stitch
+ - items:
+ - const: mediatek,mt8188-mdp3-stitch
+ - const: mediatek,mt8195-mdp3-stitch
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ description:
+ The register of display function block to be set by gce. There are 4 arguments,
+ such as gce node, subsys id, offset and register size. The subsys id that is
+ mapping to the register of display function blocks is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/gce/mt8195-gce.h>
+
+ display@14003000 {
+ compatible = "mediatek,mt8195-mdp3-stitch";
+ reg = <0x14003000 0x1000>;
+ mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x3000 0x1000>;
+ clocks = <&vppsys0 CLK_VPP0_STITCH>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml
new file mode 100644
index 000000000000..6cff7c073ce4
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-tcc.yaml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-tcc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Media Data Path 3 Tone Curve Conversion
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+
+description:
+ Tone Curve Conversion (TCC) is one of Media Profile Path 3 (MDP3) components.
+ It is used to handle the tone mapping of various gamma curves in order to
+ achieve HDR10 effects. This helps adapt the content to the color and
+ brightness range that standard display devices typically support.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8195-mdp3-tcc
+ - items:
+ - const: mediatek,mt8188-mdp3-tcc
+ - const: mediatek,mt8195-mdp3-tcc
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ description:
+ The register of display function block to be set by gce. There are 4 arguments,
+ such as gce node, subsys id, offset and register size. The subsys id that is
+ mapping to the register of display function blocks is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/gce/mt8195-gce.h>
+
+ display@1400b000 {
+ compatible = "mediatek,mt8195-mdp3-tcc";
+ reg = <0x1400b000 0x1000>;
+ mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0xb000 0x1000>;
+ clocks = <&vppsys0 CLK_VPP0_MDP_TCC>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml
new file mode 100644
index 000000000000..cdfa27324738
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-tdshp.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-tdshp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Media Data Path 3 Two-Dimensional Sharpness
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description:
+ Two-Dimensional Sharpness (TDSHP) is a Media Profile Path 3 (MDP3) component
+ used to perform image edge sharpening and enhance vividness and contrast.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8195-mdp3-tdshp
+ - items:
+ - const: mediatek,mt8188-mdp3-tdshp
+ - const: mediatek,mt8195-mdp3-tdshp
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ description:
+ The register of display function block to be set by gce. There are 4 arguments,
+ such as gce node, subsys id, offset and register size. The subsys id that is
+ mapping to the register of display function blocks is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/gce/mt8195-gce.h>
+
+ display@14007000 {
+ compatible = "mediatek,mt8195-mdp3-tdshp";
+ reg = <0x14007000 0x1000>;
+ mediatek,gce-client-reg = <&gce1 SUBSYS_1400XXXX 0x7000 0x1000>;
+ clocks = <&vppsys0 CLK_VPP0_MDP_TDSHP>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml b/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml
new file mode 100644
index 000000000000..b6269f4f9fd6
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mdp3-wrot.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mdp3-wrot.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Write DMA with Rotation
+
+maintainers:
+ - Matthias Brugger <matthias.bgg@gmail.com>
+ - Moudy Ho <moudy.ho@mediatek.com>
+
+description: |
+ One of Media Data Path 3 (MDP3) components used to write DMA with frame rotation.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8183-mdp3-wrot
+ - items:
+ - enum:
+ - mediatek,mt8188-mdp3-wrot
+ - mediatek,mt8195-mdp3-wrot
+ - const: mediatek,mt8183-mdp3-wrot
+
+ reg:
+ maxItems: 1
+
+ mediatek,gce-client-reg:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ items:
+ - description: phandle of GCE
+ - description: GCE subsys id
+ - description: register offset
+ - description: register size
+ description: The register of client driver can be configured by gce with
+ 4 arguments defined in this property. Each GCE subsys id is mapping to
+ a client defined in the header include/dt-bindings/gce/<chip>-gce.h.
+
+ mediatek,gce-events:
+ description:
+ The event id which is mapping to the specific hardware event signal
+ to gce. The event id is defined in the gce header
+ include/dt-bindings/gce/<chip>-gce.h of each chips.
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+
+ power-domains:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+
+ iommus:
+ maxItems: 1
+
+ '#dma-cells':
+ const: 1
+
+required:
+ - compatible
+ - reg
+ - mediatek,gce-client-reg
+ - mediatek,gce-events
+ - power-domains
+ - clocks
+ - iommus
+ - '#dma-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8183-clk.h>
+ #include <dt-bindings/gce/mt8183-gce.h>
+ #include <dt-bindings/power/mt8183-power.h>
+ #include <dt-bindings/memory/mt8183-larb-port.h>
+
+ dma-controller@14005000 {
+ compatible = "mediatek,mt8183-mdp3-wrot";
+ reg = <0x14005000 0x1000>;
+ mediatek,gce-client-reg = <&gce SUBSYS_1400XXXX 0x5000 0x1000>;
+ mediatek,gce-events = <CMDQ_EVENT_MDP_WROT0_SOF>,
+ <CMDQ_EVENT_MDP_WROT0_EOF>;
+ power-domains = <&spm MT8183_POWER_DOMAIN_DISP>;
+ clocks = <&mmsys CLK_MM_MDP_WROT0>;
+ iommus = <&iommu>;
+ #dma-cells = <1>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mt7622-cir.yaml b/Documentation/devicetree/bindings/media/mediatek,mt7622-cir.yaml
new file mode 100644
index 000000000000..c01210e053f9
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mt7622-cir.yaml
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mt7622-cir.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Consumer Infrared Receiver on-SoC Controller
+
+maintainers:
+ - Sean Wang <sean.wang@mediatek.com>
+
+allOf:
+ - $ref: rc.yaml#
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt7622-cir
+ - mediatek,mt7623-cir
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: clk
+ - const: bus
+
+required:
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt2701-clk.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ ir@10013000 {
+ compatible = "mediatek,mt7623-cir";
+ reg = <0x10013000 0x1000>;
+ interrupts = <GIC_SPI 87 IRQ_TYPE_LEVEL_LOW>;
+ clocks = <&infracfg CLK_INFRA_IRRX>, <&topckgen CLK_TOP_AXI_SEL>;
+ clock-names = "clk", "bus";
+ linux,rc-map-name = "rc-rc6-mce";
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mt8173-mdp.yaml b/Documentation/devicetree/bindings/media/mediatek,mt8173-mdp.yaml
new file mode 100644
index 000000000000..8ca33a733c47
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mt8173-mdp.yaml
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mt8173-mdp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek MT8173 Media Data Path
+
+maintainers:
+ - Ariel D'Alessandro <ariel.dalessandro@collabora.com>
+
+description:
+ Media Data Path is used for scaling and color space conversion.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - mediatek,mt8173-mdp-rdma
+ - mediatek,mt8173-mdp-rsz
+ - mediatek,mt8173-mdp-wdma
+ - mediatek,mt8173-mdp-wrot
+ - items:
+ - const: mediatek,mt8173-mdp-rdma
+ - const: mediatek,mt8173-mdp
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ mediatek,vpu:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ phandle to Mediatek Video Processor Unit for HW Codec encode/decode and
+ image processing.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - power-domains
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8173-mdp-rdma
+ then:
+ properties:
+ clocks:
+ items:
+ - description: Main clock
+ - description: Mutex clock
+ else:
+ properties:
+ clocks:
+ items:
+ - description: Main clock
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8173-mdp-rdma
+ - mediatek,mt8173-mdp-wdma
+ - mediatek,mt8173-mdp-wrot
+ then:
+ required:
+ - iommus
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: mediatek,mt8173-mdp
+ then:
+ required:
+ - mediatek,vpu
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8173-clk.h>
+ #include <dt-bindings/memory/mt8173-larb-port.h>
+ #include <dt-bindings/power/mt8173-power.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ mdp_rdma0: rdma@14001000 {
+ compatible = "mediatek,mt8173-mdp-rdma",
+ "mediatek,mt8173-mdp";
+ reg = <0 0x14001000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_RDMA0>,
+ <&mmsys CLK_MM_MUTEX_32K>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ iommus = <&iommu M4U_PORT_MDP_RDMA0>;
+ mediatek,vpu = <&vpu>;
+ };
+
+ mdp_rdma1: rdma@14002000 {
+ compatible = "mediatek,mt8173-mdp-rdma";
+ reg = <0 0x14002000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_RDMA1>,
+ <&mmsys CLK_MM_MUTEX_32K>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ iommus = <&iommu M4U_PORT_MDP_RDMA1>;
+ };
+
+ mdp_rsz0: rsz@14003000 {
+ compatible = "mediatek,mt8173-mdp-rsz";
+ reg = <0 0x14003000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_RSZ0>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ };
+
+ mdp_rsz1: rsz@14004000 {
+ compatible = "mediatek,mt8173-mdp-rsz";
+ reg = <0 0x14004000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_RSZ1>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ };
+
+ mdp_rsz2: rsz@14005000 {
+ compatible = "mediatek,mt8173-mdp-rsz";
+ reg = <0 0x14005000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_RSZ2>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ };
+
+ mdp_wdma0: wdma@14006000 {
+ compatible = "mediatek,mt8173-mdp-wdma";
+ reg = <0 0x14006000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_WDMA>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ iommus = <&iommu M4U_PORT_MDP_WDMA>;
+ };
+
+ mdp_wrot0: wrot@14007000 {
+ compatible = "mediatek,mt8173-mdp-wrot";
+ reg = <0 0x14007000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_WROT0>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ iommus = <&iommu M4U_PORT_MDP_WROT0>;
+ };
+
+ mdp_wrot1: wrot@14008000 {
+ compatible = "mediatek,mt8173-mdp-wrot";
+ reg = <0 0x14008000 0 0x1000>;
+ clocks = <&mmsys CLK_MM_MDP_WROT1>;
+ power-domains = <&spm MT8173_POWER_DOMAIN_MM>;
+ iommus = <&iommu M4U_PORT_MDP_WROT1>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/mediatek,mt8173-vpu.yaml b/Documentation/devicetree/bindings/media/mediatek,mt8173-vpu.yaml
new file mode 100644
index 000000000000..8a47761f1e6b
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mt8173-vpu.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mt8173-vpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek MT8173 Video Processor Unit
+
+maintainers:
+ - Ariel D'Alessandro <ariel.dalessandro@collabora.com>
+
+description:
+ Video Processor Unit is a HW video controller. It controls HW Codec including
+ H.264/VP8/VP9 Decode, H.264/VP8 Encode and Image Processor (scale/rotate/color
+ convert).
+
+properties:
+ compatible:
+ const: mediatek,mt8173-vpu
+
+ reg:
+ maxItems: 2
+
+ reg-names:
+ items:
+ - const: tcm
+ - const: cfg_reg
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: main
+
+ memory-region:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - clocks
+ - clock-names
+ - memory-region
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt8173-clk.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ vpu: vpu@10020000 {
+ compatible = "mediatek,mt8173-vpu";
+ reg = <0 0x10020000 0 0x30000>,
+ <0 0x10050000 0 0x100>;
+ reg-names = "tcm", "cfg_reg";
+ interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&topckgen CLK_TOP_SCP_SEL>;
+ clock-names = "main";
+ memory-region = <&vpu_dma_reserved>;
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml
new file mode 100644
index 000000000000..e5448c60e3eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegdec.yaml
@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mt8195-jpegdec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek JPEG Decoder
+
+maintainers:
+ - kyrie wu <kyrie.wu@mediatek.corp-partner.google.com>
+
+description:
+ MediaTek JPEG Decoder is the JPEG decode hardware present in MediaTek SoCs
+
+properties:
+ compatible:
+ const: mediatek,mt8195-jpgdec
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 6
+ description:
+ Points to the respective IOMMU block with master port as argument, see
+ Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details.
+ Ports are according to the HW.
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 2
+
+ ranges: true
+
+# Required child node:
+patternProperties:
+ "^jpgdec@[0-9a-f]+$":
+ type: object
+ description:
+ The jpeg decoder hardware device node which should be added as subnodes to
+ the main jpeg node.
+
+ properties:
+ compatible:
+ const: mediatek,mt8195-jpgdec-hw
+
+ reg:
+ maxItems: 1
+
+ iommus:
+ minItems: 1
+ maxItems: 32
+ description:
+ List of the hardware port in respective IOMMU block for current Socs.
+ Refer to bindings/iommu/mediatek,iommu.yaml.
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: jpgdec
+
+ power-domains:
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+ - iommus
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - power-domains
+ - iommus
+ - ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/memory/mt8195-memory-port.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/power/mt8195-power.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ jpgdec-master {
+ compatible = "mediatek,mt8195-jpgdec";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VDEC1>;
+ iommus = <&iommu_vpp M4U_PORT_L19_JPGDEC_WDMA0>,
+ <&iommu_vpp M4U_PORT_L19_JPGDEC_BSDMA0>,
+ <&iommu_vpp M4U_PORT_L19_JPGDEC_WDMA1>,
+ <&iommu_vpp M4U_PORT_L19_JPGDEC_BSDMA1>,
+ <&iommu_vpp M4U_PORT_L19_JPGDEC_BUFF_OFFSET1>,
+ <&iommu_vpp M4U_PORT_L19_JPGDEC_BUFF_OFFSET0>;
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges;
+
+ jpgdec@1a040000 {
+ compatible = "mediatek,mt8195-jpgdec-hw";
+ reg = <0 0x1a040000 0 0x10000>;/* JPGDEC_C0 */
+ iommus = <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA0>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA0>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA1>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA1>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET1>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET0>;
+ interrupts = <GIC_SPI 343 IRQ_TYPE_LEVEL_HIGH 0>;
+ clocks = <&vencsys CLK_VENC_JPGDEC>;
+ clock-names = "jpgdec";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VDEC0>;
+ };
+
+ jpgdec@1a050000 {
+ compatible = "mediatek,mt8195-jpgdec-hw";
+ reg = <0 0x1a050000 0 0x10000>;/* JPGDEC_C1 */
+ iommus = <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA0>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA0>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_WDMA1>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BSDMA1>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET1>,
+ <&iommu_vdo M4U_PORT_L19_JPGDEC_BUFF_OFFSET0>;
+ interrupts = <GIC_SPI 344 IRQ_TYPE_LEVEL_HIGH 0>;
+ clocks = <&vencsys CLK_VENC_JPGDEC_C1>;
+ clock-names = "jpgdec";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VDEC1>;
+ };
+
+ jpgdec@1b040000 {
+ compatible = "mediatek,mt8195-jpgdec-hw";
+ reg = <0 0x1b040000 0 0x10000>;/* JPGDEC_C2 */
+ iommus = <&iommu_vpp M4U_PORT_L20_JPGDEC_WDMA0>,
+ <&iommu_vpp M4U_PORT_L20_JPGDEC_BSDMA0>,
+ <&iommu_vpp M4U_PORT_L20_JPGDEC_WDMA1>,
+ <&iommu_vpp M4U_PORT_L20_JPGDEC_BSDMA1>,
+ <&iommu_vpp M4U_PORT_L20_JPGDEC_BUFF_OFFSET1>,
+ <&iommu_vpp M4U_PORT_L20_JPGDEC_BUFF_OFFSET0>;
+ interrupts = <GIC_SPI 348 IRQ_TYPE_LEVEL_HIGH 0>;
+ clocks = <&vencsys_core1 CLK_VENC_CORE1_JPGDEC>;
+ clock-names = "jpgdec";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VDEC2>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml
new file mode 100644
index 000000000000..596186497b68
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,mt8195-jpegenc.yaml
@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,mt8195-jpegenc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek JPEG Encoder
+
+maintainers:
+ - kyrie wu <kyrie.wu@mediatek.corp-partner.google.com>
+
+description:
+ MediaTek JPEG Encoder is the JPEG encode hardware present in MediaTek SoCs
+
+properties:
+ compatible:
+ const: mediatek,mt8195-jpgenc
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 4
+ description:
+ Points to the respective IOMMU block with master port as argument, see
+ Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details.
+ Ports are according to the HW.
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 2
+
+ ranges: true
+
+# Required child node:
+patternProperties:
+ "^jpgenc@[0-9a-f]+$":
+ type: object
+ description:
+ The jpeg encoder hardware device node which should be added as subnodes to
+ the main jpeg node.
+
+ properties:
+ compatible:
+ const: mediatek,mt8195-jpgenc-hw
+
+ reg:
+ maxItems: 1
+
+ iommus:
+ minItems: 1
+ maxItems: 32
+ description:
+ List of the hardware port in respective IOMMU block for current Socs.
+ Refer to bindings/iommu/mediatek,iommu.yaml.
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: jpgenc
+
+ power-domains:
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+ - iommus
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - power-domains
+ - iommus
+ - ranges
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/memory/mt8195-memory-port.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/mt8195-clk.h>
+ #include <dt-bindings/power/mt8195-power.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ jpgenc-master {
+ compatible = "mediatek,mt8195-jpgenc";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VENC_CORE1>;
+ iommus = <&iommu_vpp M4U_PORT_L20_JPGENC_Y_RDMA>,
+ <&iommu_vpp M4U_PORT_L20_JPGENC_C_RDMA>,
+ <&iommu_vpp M4U_PORT_L20_JPGENC_Q_TABLE>,
+ <&iommu_vpp M4U_PORT_L20_JPGENC_BSDMA>;
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges;
+
+ jpgenc@1a030000 {
+ compatible = "mediatek,mt8195-jpgenc-hw";
+ reg = <0 0x1a030000 0 0x10000>;
+ iommus = <&iommu_vdo M4U_PORT_L19_JPGENC_Y_RDMA>,
+ <&iommu_vdo M4U_PORT_L19_JPGENC_C_RDMA>,
+ <&iommu_vdo M4U_PORT_L19_JPGENC_Q_TABLE>,
+ <&iommu_vdo M4U_PORT_L19_JPGENC_BSDMA>;
+ interrupts = <GIC_SPI 342 IRQ_TYPE_LEVEL_HIGH 0>;
+ clocks = <&vencsys CLK_VENC_JPGENC>;
+ clock-names = "jpgenc";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VENC>;
+ };
+
+ jpgenc@1b030000 {
+ compatible = "mediatek,mt8195-jpgenc-hw";
+ reg = <0 0x1b030000 0 0x10000>;
+ iommus = <&iommu_vpp M4U_PORT_L20_JPGENC_Y_RDMA>,
+ <&iommu_vpp M4U_PORT_L20_JPGENC_C_RDMA>,
+ <&iommu_vpp M4U_PORT_L20_JPGENC_Q_TABLE>,
+ <&iommu_vpp M4U_PORT_L20_JPGENC_BSDMA>;
+ interrupts = <GIC_SPI 347 IRQ_TYPE_LEVEL_HIGH 0>;
+ clocks = <&vencsys_core1 CLK_VENC_CORE1_JPGENC>;
+ clock-names = "jpgenc";
+ power-domains = <&spm MT8195_POWER_DOMAIN_VENC_CORE1>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml
new file mode 100644
index 000000000000..d726d141a434
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-decoder.yaml
@@ -0,0 +1,198 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,vcodec-decoder.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek Video Decode Accelerator
+
+maintainers:
+ - Yunfei Dong <yunfei.dong@mediatek.com>
+
+description: |+
+ Mediatek Video Decode is the video decode hardware present in Mediatek
+ SoCs which supports high resolution decoding functionalities.
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt8173-vcodec-dec
+ - mediatek,mt8183-vcodec-dec
+
+ reg:
+ minItems: 11
+ maxItems: 11
+
+ reg-names:
+ items:
+ - const: misc
+ - const: ld
+ - const: top
+ - const: cm
+ - const: ad
+ - const: av
+ - const: pp
+ - const: hwd
+ - const: hwq
+ - const: hwb
+ - const: hwg
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 8
+
+ clock-names:
+ minItems: 1
+ maxItems: 8
+
+ assigned-clocks: true
+
+ assigned-clock-parents: true
+
+ assigned-clock-rates: true
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ minItems: 1
+ maxItems: 32
+ description: |
+ List of the hardware port in respective IOMMU block for current Socs.
+ Refer to bindings/iommu/mediatek,iommu.yaml.
+
+ mediatek,vpu:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Describes point to vpu.
+
+ mediatek,scp:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Describes point to scp.
+
+ mediatek,vdecsys:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: Phandle to the vdecsys syscon node.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - iommus
+ - mediatek,vdecsys
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8183-vcodec-dec
+
+ then:
+ required:
+ - mediatek,scp
+
+ properties:
+ clocks:
+ minItems: 1
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: vdec
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8173-vcodec-dec
+
+ then:
+ required:
+ - mediatek,vpu
+
+ properties:
+ clocks:
+ minItems: 8
+ maxItems: 8
+
+ clock-names:
+ items:
+ - const: vcodecpll
+ - const: univpll_d2
+ - const: clk_cci400_sel
+ - const: vdec_sel
+ - const: vdecpll
+ - const: vencpll
+ - const: venc_lt_sel
+ - const: vdec_bus_clk_src
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/mt8173-clk.h>
+ #include <dt-bindings/memory/mt8173-larb-port.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/power/mt8173-power.h>
+
+ vcodec_dec: vcodec@16020000 {
+ compatible = "mediatek,mt8173-vcodec-dec";
+ reg = <0x16020000 0x1000>, /*VDEC_MISC*/
+ <0x16021000 0x800>, /*VDEC_LD*/
+ <0x16021800 0x800>, /*VDEC_TOP*/
+ <0x16022000 0x1000>, /*VDEC_CM*/
+ <0x16023000 0x1000>, /*VDEC_AD*/
+ <0x16024000 0x1000>, /*VDEC_AV*/
+ <0x16025000 0x1000>, /*VDEC_PP*/
+ <0x16026800 0x800>, /*VP8_VD*/
+ <0x16027000 0x800>, /*VP6_VD*/
+ <0x16027800 0x800>, /*VP8_VL*/
+ <0x16028400 0x400>; /*VP9_VD*/
+ interrupts = <GIC_SPI 204 IRQ_TYPE_LEVEL_LOW>;
+ iommus = <&iommu M4U_PORT_HW_VDEC_MC_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_PP_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_AVC_MV_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_PRED_RD_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_PRED_WR_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_UFO_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_VLD_EXT>,
+ <&iommu M4U_PORT_HW_VDEC_VLD2_EXT>;
+ mediatek,vpu = <&vpu>;
+ mediatek,vdecsys = <&vdecsys>;
+ power-domains = <&scpsys MT8173_POWER_DOMAIN_VDEC>;
+ clocks = <&apmixedsys CLK_APMIXED_VCODECPLL>,
+ <&topckgen CLK_TOP_UNIVPLL_D2>,
+ <&topckgen CLK_TOP_CCI400_SEL>,
+ <&topckgen CLK_TOP_VDEC_SEL>,
+ <&topckgen CLK_TOP_VCODECPLL>,
+ <&apmixedsys CLK_APMIXED_VENCPLL>,
+ <&topckgen CLK_TOP_VENC_LT_SEL>,
+ <&topckgen CLK_TOP_VCODECPLL_370P5>;
+ clock-names = "vcodecpll",
+ "univpll_d2",
+ "clk_cci400_sel",
+ "vdec_sel",
+ "vdecpll",
+ "vencpll",
+ "venc_lt_sel",
+ "vdec_bus_clk_src";
+ assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>,
+ <&topckgen CLK_TOP_CCI400_SEL>,
+ <&topckgen CLK_TOP_VDEC_SEL>,
+ <&apmixedsys CLK_APMIXED_VCODECPLL>,
+ <&apmixedsys CLK_APMIXED_VENCPLL>;
+ assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>,
+ <&topckgen CLK_TOP_UNIVPLL_D2>,
+ <&topckgen CLK_TOP_VCODECPLL>;
+ assigned-clock-rates = <0>, <0>, <0>, <1482000000>, <800000000>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml
new file mode 100644
index 000000000000..ebc615584f92
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,vcodec-encoder.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Mediatek Video Encode Accelerator
+
+maintainers:
+ - Yunfei Dong <yunfei.dong@mediatek.com>
+
+description: |+
+ Mediatek Video Encode is the video encode hardware present in Mediatek
+ SoCs which supports high resolution encoding functionalities.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - mediatek,mt8173-vcodec-enc-vp8
+ - mediatek,mt8173-vcodec-enc
+ - mediatek,mt8183-vcodec-enc
+ - mediatek,mt8188-vcodec-enc
+ - mediatek,mt8192-vcodec-enc
+ - mediatek,mt8195-vcodec-enc
+ - items:
+ - const: mediatek,mt8186-vcodec-enc
+ - const: mediatek,mt8183-vcodec-enc
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 5
+
+ clock-names:
+ minItems: 1
+ maxItems: 5
+
+ iommus:
+ minItems: 1
+ maxItems: 32
+ description: |
+ List of the hardware port in respective IOMMU block for current Socs.
+ Refer to bindings/iommu/mediatek,iommu.yaml.
+
+ mediatek,vpu:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Describes point to vpu.
+
+ mediatek,scp:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Describes point to scp.
+
+ power-domains:
+ maxItems: 1
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 2
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - iommus
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8183-vcodec-enc
+ - mediatek,mt8188-vcodec-enc
+ - mediatek,mt8192-vcodec-enc
+ - mediatek,mt8195-vcodec-enc
+
+ then:
+ required:
+ - mediatek,scp
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8173-vcodec-enc-vp8
+ - mediatek,mt8173-vcodec-enc
+
+ then:
+ required:
+ - mediatek,vpu
+
+ - if:
+ properties:
+ compatible:
+ enum:
+ - mediatek,mt8173-vcodec-enc-vp8
+
+ then:
+ properties:
+ clock:
+ items:
+ minItems: 1
+ maxItems: 1
+ clock-names:
+ items:
+ - const: venc_lt_sel
+ else:
+ properties:
+ clock:
+ items:
+ minItems: 1
+ maxItems: 1
+ clock-names:
+ items:
+ - const: venc_sel
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/mt8173-clk.h>
+ #include <dt-bindings/memory/mt8173-larb-port.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ vcodec_enc_avc: vcodec@18002000 {
+ compatible = "mediatek,mt8173-vcodec-enc";
+ reg = <0x18002000 0x1000>;
+ interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>;
+ iommus = <&iommu M4U_PORT_VENC_RCPU>,
+ <&iommu M4U_PORT_VENC_REC>,
+ <&iommu M4U_PORT_VENC_BSDMA>,
+ <&iommu M4U_PORT_VENC_SV_COMV>,
+ <&iommu M4U_PORT_VENC_RD_COMV>,
+ <&iommu M4U_PORT_VENC_CUR_LUMA>,
+ <&iommu M4U_PORT_VENC_CUR_CHROMA>,
+ <&iommu M4U_PORT_VENC_REF_LUMA>,
+ <&iommu M4U_PORT_VENC_REF_CHROMA>,
+ <&iommu M4U_PORT_VENC_NBM_RDMA>,
+ <&iommu M4U_PORT_VENC_NBM_WDMA>;
+ mediatek,vpu = <&vpu>;
+ clocks = <&topckgen CLK_TOP_VENC_SEL>;
+ clock-names = "venc_sel";
+ assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>;
+ assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL>;
+ };
+
+ vcodec_enc_vp8: vcodec@19002000 {
+ compatible = "mediatek,mt8173-vcodec-enc-vp8";
+ reg = <0x19002000 0x1000>; /* VENC_LT_SYS */
+ interrupts = <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>;
+ iommus = <&iommu M4U_PORT_VENC_RCPU_SET2>,
+ <&iommu M4U_PORT_VENC_REC_FRM_SET2>,
+ <&iommu M4U_PORT_VENC_BSDMA_SET2>,
+ <&iommu M4U_PORT_VENC_SV_COMA_SET2>,
+ <&iommu M4U_PORT_VENC_RD_COMA_SET2>,
+ <&iommu M4U_PORT_VENC_CUR_LUMA_SET2>,
+ <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>,
+ <&iommu M4U_PORT_VENC_REF_LUMA_SET2>,
+ <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>;
+ mediatek,vpu = <&vpu>;
+ clocks = <&topckgen CLK_TOP_VENC_LT_SEL>;
+ clock-names = "venc_lt_sel";
+ assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>;
+ assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml
new file mode 100644
index 000000000000..bf8082d87ac0
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-subdev-decoder.yaml
@@ -0,0 +1,285 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek,vcodec-subdev-decoder.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek Video Decode Accelerator With Multi Hardware
+
+maintainers:
+ - Yunfei Dong <yunfei.dong@mediatek.com>
+
+description: |
+ MediaTek Video Decode Accelerator is the video decoding hardware present in
+ MediaTek SoCs that supports high-resolution decoding functionalities.
+ It consists of parent and child nodes.
+
+ The decoder hardware block diagram is shown below:
+
+ +------------------------------------------------+------------------------------+
+ | | |
+ | input -> LAT-SoC HW -> LAT HW -> LAT buffer --|--> Core HW -> output buffer |
+ | || || | || |
+ +--------------||-----------||-------------------+-------||---------------------+
+ LAT Workqueue | Core Workqueue <parent>
+ ---------------||-----------||-------------------|-------||----------------------
+ ||<----------||---------HW index--------->|| <child>
+ \/ \/ \/
+ +-------------------------------------------------------------+
+ | enable/disable |
+ | clk power irq iommu |
+ | (lat/lat-soc/core0/core1) |
+ +-------------------------------------------------------------+
+
+ The child nodes represent the individual hardware blocks within the decoding
+ pipeline, such as LAT-SoC, LAT and Core.
+ Each child node is responsible for managing the dedicated resources of the
+ hardware, such as clocks, power domains, interrupts and IOMMUs.
+
+ The parent node is a central point of control for the child nodes.
+ It identifies the specific video decoding pipeline architecture used by the
+ SoC, manages the shared resources like workqueues and platform data, and
+ handles V4L2 API calls on behalf of the underlying hardware.
+
+ The parent utilizes two workqueues to manage the decoding process.
+ 1. LAT Workqueue, for LAT-SoC and LAT decoder:
+ Its workers take input bitstream and LAT buffer, enable the hardware for
+ decoding tasks, write the result to LAT buffer, and disable the hardware
+ after the LAT decoding is done.
+ 2. Core Workqueue, for Core decoder:
+ Its workers take LAT buffer and output buffer, enable the hardware for
+ decoding tasks, write the result to output buffer, and disable the hardware
+ after the Core decoding is done.
+
+ These hardware decode each frame cyclically.
+
+ The hardware might be associated with different SMI-common devices.
+ To prevent IOMMU faults during DRAM access in such cases, each hardware with
+ the unique SMI-common device must be placed under a separate parent node in
+ the device tree.
+
+ LAT-SoC refers to another hardware block that connected to additional LARB
+ (local arbiter) ports, such as RDMA and UFO.
+ It requires independent power and clock control to work with LAT decoder, and
+ it doesn't have a dedicated interrupt.
+
+ The used video decoding pipeline architecture across various Mediatek SoC:
+ MT8195: LAT-SoC + LAT + Core
+ MT8192: LAT + Core
+ MT8188: LAT + Core
+ MT8186: Core
+
+properties:
+ compatible:
+ enum:
+ - mediatek,mt8192-vcodec-dec
+ - mediatek,mt8186-vcodec-dec
+ - mediatek,mt8188-vcodec-dec
+ - mediatek,mt8195-vcodec-dec
+
+ reg:
+ minItems: 1
+ items:
+ - description: VDEC_SYS register space
+ - description: VDEC_RACING_CTRL register space
+
+ iommus:
+ minItems: 1
+ maxItems: 32
+ description: |
+ List of the hardware port in respective IOMMU block for current Socs.
+ Refer to bindings/iommu/mediatek,iommu.yaml.
+
+ mediatek,scp:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: |
+ The node of system control processor (SCP), using
+ the remoteproc & rpmsg framework.
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 2
+
+ ranges: true
+
+# Required child node:
+patternProperties:
+ '^video-codec@[0-9a-f]+$':
+ type: object
+
+ properties:
+ compatible:
+ enum:
+ - mediatek,mtk-vcodec-core
+ - mediatek,mtk-vcodec-lat
+ - mediatek,mtk-vcodec-lat-soc
+
+ reg:
+ maxItems: 1
+ description: VDEC_MISC register space
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ minItems: 1
+ maxItems: 32
+ description: |
+ List of the hardware port in respective IOMMU block for current Socs.
+ Refer to bindings/iommu/mediatek,iommu.yaml.
+
+ clocks:
+ minItems: 4
+ maxItems: 5
+
+ clock-names:
+ minItems: 4
+ maxItems: 5
+
+ assigned-clocks:
+ maxItems: 1
+
+ assigned-clock-parents:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ required:
+ - compatible
+ - reg
+ - iommus
+ - clocks
+ - clock-names
+ - assigned-clocks
+ - assigned-clock-parents
+ - power-domains
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - iommus
+ - mediatek,scp
+ - ranges
+
+if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mtk-vcodec-core
+ - mediatek,mtk-vcodec-lat
+
+then:
+ required:
+ - interrupts
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8192-vcodec-dec
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: sel
+ - const: soc-vdec
+ - const: soc-lat
+ - const: vdec
+ - const: top
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - mediatek,mt8195-vcodec-dec
+ then:
+ properties:
+ clock-names:
+ items:
+ - const: sel
+ - const: vdec
+ - const: lat
+ - const: top
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/memory/mt8192-larb-port.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/clock/mt8192-clk.h>
+ #include <dt-bindings/power/mt8192-power.h>
+
+ bus@16000000 {
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges = <0 0x16000000 0x16000000 0 0x40000>;
+
+ video-codec@16000000 {
+ compatible = "mediatek,mt8192-vcodec-dec";
+ mediatek,scp = <&scp>;
+ iommus = <&iommu0 M4U_PORT_L4_VDEC_MC_EXT>;
+ #address-cells = <2>;
+ #size-cells = <2>;
+ ranges = <0 0 0 0x16000000 0 0x40000>;
+ reg = <0 0x16000000 0 0x1000>; /* VDEC_SYS */
+ video-codec@10000 {
+ compatible = "mediatek,mtk-vcodec-lat";
+ reg = <0 0x10000 0 0x800>;
+ interrupts = <GIC_SPI 426 IRQ_TYPE_LEVEL_HIGH 0>;
+ iommus = <&iommu0 M4U_PORT_L5_VDEC_LAT0_VLD_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_LAT0_VLD2_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_LAT0_AVC_MV_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_LAT0_PRED_RD_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_LAT0_TILE_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_LAT0_WDMA_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_LAT0_RG_CTRL_DMA_EXT>,
+ <&iommu0 M4U_PORT_L5_VDEC_UFO_ENC_EXT>;
+ clocks = <&topckgen CLK_TOP_VDEC_SEL>,
+ <&vdecsys_soc CLK_VDEC_SOC_VDEC>,
+ <&vdecsys_soc CLK_VDEC_SOC_LAT>,
+ <&vdecsys_soc CLK_VDEC_SOC_LARB1>,
+ <&topckgen CLK_TOP_MAINPLL_D4>;
+ clock-names = "sel", "soc-vdec", "soc-lat", "vdec", "top";
+ assigned-clocks = <&topckgen CLK_TOP_VDEC_SEL>;
+ assigned-clock-parents = <&topckgen CLK_TOP_MAINPLL_D4>;
+ power-domains = <&spm MT8192_POWER_DOMAIN_VDEC>;
+ };
+
+ video-codec@25000 {
+ compatible = "mediatek,mtk-vcodec-core";
+ reg = <0 0x25000 0 0x1000>;
+ interrupts = <GIC_SPI 425 IRQ_TYPE_LEVEL_HIGH 0>;
+ iommus = <&iommu0 M4U_PORT_L4_VDEC_MC_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_UFO_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_PP_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_PRED_RD_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_PRED_WR_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_PPWRAP_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_TILE_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_VLD_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_VLD2_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_AVC_MV_EXT>,
+ <&iommu0 M4U_PORT_L4_VDEC_RG_CTRL_DMA_EXT>;
+ clocks = <&topckgen CLK_TOP_VDEC_SEL>,
+ <&vdecsys CLK_VDEC_VDEC>,
+ <&vdecsys CLK_VDEC_LAT>,
+ <&vdecsys CLK_VDEC_LARB1>,
+ <&topckgen CLK_TOP_MAINPLL_D4>;
+ clock-names = "sel", "soc-vdec", "soc-lat", "vdec", "top";
+ assigned-clocks = <&topckgen CLK_TOP_VDEC_SEL>;
+ assigned-clock-parents = <&topckgen CLK_TOP_MAINPLL_D4>;
+ power-domains = <&spm MT8192_POWER_DOMAIN_VDEC2>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt
deleted file mode 100644
index 39c1028b2dfb..000000000000
--- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-* Mediatek JPEG Decoder
-
-Mediatek JPEG Decoder is the JPEG decode hardware present in Mediatek SoCs
-
-Required properties:
-- compatible : must be one of the following string:
- "mediatek,mt8173-jpgdec"
- "mediatek,mt7623-jpgdec", "mediatek,mt2701-jpgdec"
- "mediatek,mt2701-jpgdec"
-- reg : physical base address of the jpeg decoder registers and length of
- memory mapped region.
-- interrupts : interrupt number to the interrupt controller.
-- clocks: device clocks, see
- Documentation/devicetree/bindings/clock/clock-bindings.txt for details.
-- clock-names: must contain "jpgdec-smi" and "jpgdec".
-- power-domains: a phandle to the power domain, see
- Documentation/devicetree/bindings/power/power_domain.txt for details.
-- mediatek,larb: must contain the local arbiters in the current Socs, see
- Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml
- for details.
-- iommus: should point to the respective IOMMU block with master port as
- argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
- for details.
-
-Example:
- jpegdec: jpegdec@15004000 {
- compatible = "mediatek,mt2701-jpgdec";
- reg = <0 0x15004000 0 0x1000>;
- interrupts = <GIC_SPI 143 IRQ_TYPE_LEVEL_LOW>;
- clocks = <&imgsys CLK_IMG_JPGDEC_SMI>,
- <&imgsys CLK_IMG_JPGDEC>;
- clock-names = "jpgdec-smi",
- "jpgdec";
- power-domains = <&scpsys MT2701_POWER_DOMAIN_ISP>;
- mediatek,larb = <&larb2>;
- iommus = <&iommu MT2701_M4U_PORT_JPGDEC_WDMA>,
- <&iommu MT2701_M4U_PORT_JPGDEC_BSDMA>;
- };
diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
new file mode 100644
index 000000000000..a4aacd3eb189
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.yaml
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek-jpeg-decoder.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek JPEG Decoder
+
+maintainers:
+ - Xia Jiang <xia.jiang@mediatek.com>
+
+description: |-
+ Mediatek JPEG Decoder is the JPEG decode hardware present in Mediatek SoCs
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - mediatek,mt8173-jpgdec
+ - mediatek,mt2701-jpgdec
+ - items:
+ - enum:
+ - mediatek,mt7623-jpgdec
+ - mediatek,mt8188-jpgdec
+ - const: mediatek,mt2701-jpgdec
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+ minItems: 2
+
+ clock-names:
+ items:
+ - const: jpgdec-smi
+ - const: jpgdec
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ minItems: 2
+ maxItems: 32
+ description: |
+ Points to the respective IOMMU block with master port as argument, see
+ Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details.
+ Ports are according to the HW.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - iommus
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt2701-clk.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/memory/mt2701-larb-port.h>
+ #include <dt-bindings/power/mt2701-power.h>
+ jpegdec: jpegdec@15004000 {
+ compatible = "mediatek,mt2701-jpgdec";
+ reg = <0x15004000 0x1000>;
+ interrupts = <GIC_SPI 143 IRQ_TYPE_LEVEL_LOW>;
+ clocks = <&imgsys CLK_IMG_JPGDEC_SMI>,
+ <&imgsys CLK_IMG_JPGDEC>;
+ clock-names = "jpgdec-smi",
+ "jpgdec";
+ power-domains = <&scpsys MT2701_POWER_DOMAIN_ISP>;
+ iommus = <&iommu MT2701_M4U_PORT_JPGDEC_WDMA>,
+ <&iommu MT2701_M4U_PORT_JPGDEC_BSDMA>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt
deleted file mode 100644
index 5e53c6ab52d0..000000000000
--- a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-* MediaTek JPEG Encoder
-
-MediaTek JPEG Encoder is the JPEG encode hardware present in MediaTek SoCs
-
-Required properties:
-- compatible : "mediatek,mt2701-jpgenc"
- followed by "mediatek,mtk-jpgenc"
-- reg : physical base address of the JPEG encoder registers and length of
- memory mapped region.
-- interrupts : interrupt number to the interrupt controller.
-- clocks: device clocks, see
- Documentation/devicetree/bindings/clock/clock-bindings.txt for details.
-- clock-names: must contain "jpgenc". It is the clock of JPEG encoder.
-- power-domains: a phandle to the power domain, see
- Documentation/devicetree/bindings/power/power_domain.txt for details.
-- mediatek,larb: must contain the local arbiters in the current SoCs, see
- Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml
- for details.
-- iommus: should point to the respective IOMMU block with master port as
- argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
- for details.
-
-Example:
- jpegenc: jpegenc@1500a000 {
- compatible = "mediatek,mt2701-jpgenc",
- "mediatek,mtk-jpgenc";
- reg = <0 0x1500a000 0 0x1000>;
- interrupts = <GIC_SPI 141 IRQ_TYPE_LEVEL_LOW>;
- clocks = <&imgsys CLK_IMG_VENC>;
- clock-names = "jpgenc";
- power-domains = <&scpsys MT2701_POWER_DOMAIN_ISP>;
- mediatek,larb = <&larb2>;
- iommus = <&iommu MT2701_M4U_PORT_JPGENC_RDMA>,
- <&iommu MT2701_M4U_PORT_JPGENC_BSDMA>;
- };
diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml
new file mode 100644
index 000000000000..5b15f8977f67
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/mediatek-jpeg-encoder.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MediaTek JPEG Encoder
+
+maintainers:
+ - Xia Jiang <xia.jiang@mediatek.com>
+
+description: |-
+ MediaTek JPEG Encoder is the JPEG encode hardware present in MediaTek SoCs
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - mediatek,mt2701-jpgenc
+ - mediatek,mt8183-jpgenc
+ - mediatek,mt8186-jpgenc
+ - mediatek,mt8188-jpgenc
+ - const: mediatek,mtk-jpgenc
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: jpgenc
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ minItems: 2
+ maxItems: 32
+ description: |
+ Points to the respective IOMMU block with master port as argument, see
+ Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details.
+ Ports are according to the HW.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - iommus
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/mt2701-clk.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/memory/mt2701-larb-port.h>
+ #include <dt-bindings/power/mt2701-power.h>
+ jpegenc: jpegenc@1500a000 {
+ compatible = "mediatek,mt2701-jpgenc",
+ "mediatek,mtk-jpgenc";
+ reg = <0x1500a000 0x1000>;
+ interrupts = <GIC_SPI 141 IRQ_TYPE_LEVEL_LOW>;
+ clocks = <&imgsys CLK_IMG_VENC>;
+ clock-names = "jpgenc";
+ power-domains = <&scpsys MT2701_POWER_DOMAIN_ISP>;
+ iommus = <&iommu MT2701_M4U_PORT_JPGENC_RDMA>,
+ <&iommu MT2701_M4U_PORT_JPGENC_BSDMA>;
+ };
diff --git a/Documentation/devicetree/bindings/media/mediatek-mdp.txt b/Documentation/devicetree/bindings/media/mediatek-mdp.txt
deleted file mode 100644
index caa24943da33..000000000000
--- a/Documentation/devicetree/bindings/media/mediatek-mdp.txt
+++ /dev/null
@@ -1,103 +0,0 @@
-* Mediatek Media Data Path
-
-Media Data Path is used for scaling and color space conversion.
-
-Required properties (controller node):
-- compatible: "mediatek,mt8173-mdp"
-- mediatek,vpu: the node of video processor unit, see
- Documentation/devicetree/bindings/media/mediatek-vpu.txt for details.
-
-Required properties (all function blocks, child node):
-- compatible: Should be one of
- "mediatek,mt8173-mdp-rdma" - read DMA
- "mediatek,mt8173-mdp-rsz" - resizer
- "mediatek,mt8173-mdp-wdma" - write DMA
- "mediatek,mt8173-mdp-wrot" - write DMA with rotation
-- reg: Physical base address and length of the function block register space
-- clocks: device clocks, see
- Documentation/devicetree/bindings/clock/clock-bindings.txt for details.
-- power-domains: a phandle to the power domain, see
- Documentation/devicetree/bindings/power/power_domain.txt for details.
-
-Required properties (DMA function blocks, child node):
-- compatible: Should be one of
- "mediatek,mt8173-mdp-rdma"
- "mediatek,mt8173-mdp-wdma"
- "mediatek,mt8173-mdp-wrot"
-- iommus: should point to the respective IOMMU block with master port as
- argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
- for details.
-- mediatek,larb: must contain the local arbiters in the current Socs, see
- Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml
- for details.
-
-Example:
- mdp_rdma0: rdma@14001000 {
- compatible = "mediatek,mt8173-mdp-rdma";
- "mediatek,mt8173-mdp";
- reg = <0 0x14001000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_RDMA0>,
- <&mmsys CLK_MM_MUTEX_32K>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- iommus = <&iommu M4U_PORT_MDP_RDMA0>;
- mediatek,larb = <&larb0>;
- mediatek,vpu = <&vpu>;
- };
-
- mdp_rdma1: rdma@14002000 {
- compatible = "mediatek,mt8173-mdp-rdma";
- reg = <0 0x14002000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_RDMA1>,
- <&mmsys CLK_MM_MUTEX_32K>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- iommus = <&iommu M4U_PORT_MDP_RDMA1>;
- mediatek,larb = <&larb4>;
- };
-
- mdp_rsz0: rsz@14003000 {
- compatible = "mediatek,mt8173-mdp-rsz";
- reg = <0 0x14003000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_RSZ0>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- };
-
- mdp_rsz1: rsz@14004000 {
- compatible = "mediatek,mt8173-mdp-rsz";
- reg = <0 0x14004000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_RSZ1>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- };
-
- mdp_rsz2: rsz@14005000 {
- compatible = "mediatek,mt8173-mdp-rsz";
- reg = <0 0x14005000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_RSZ2>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- };
-
- mdp_wdma0: wdma@14006000 {
- compatible = "mediatek,mt8173-mdp-wdma";
- reg = <0 0x14006000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_WDMA>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- iommus = <&iommu M4U_PORT_MDP_WDMA>;
- mediatek,larb = <&larb0>;
- };
-
- mdp_wrot0: wrot@14007000 {
- compatible = "mediatek,mt8173-mdp-wrot";
- reg = <0 0x14007000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_WROT0>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- iommus = <&iommu M4U_PORT_MDP_WROT0>;
- mediatek,larb = <&larb0>;
- };
-
- mdp_wrot1: wrot@14008000 {
- compatible = "mediatek,mt8173-mdp-wrot";
- reg = <0 0x14008000 0 0x1000>;
- clocks = <&mmsys CLK_MM_MDP_WROT1>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>;
- iommus = <&iommu M4U_PORT_MDP_WROT1>;
- mediatek,larb = <&larb4>;
- };
diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt
deleted file mode 100644
index ad1321e5a22d..000000000000
--- a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt
+++ /dev/null
@@ -1,129 +0,0 @@
-Mediatek Video Codec
-
-Mediatek Video Codec is the video codec hw present in Mediatek SoCs which
-supports high resolution encoding and decoding functionalities.
-
-Required properties:
-- compatible : must be one of the following string:
- "mediatek,mt8173-vcodec-enc-vp8" for mt8173 vp8 encoder.
- "mediatek,mt8173-vcodec-enc" for mt8173 avc encoder.
- "mediatek,mt8183-vcodec-enc" for MT8183 encoder.
- "mediatek,mt8173-vcodec-dec" for MT8173 decoder.
- "mediatek,mt8192-vcodec-enc" for MT8192 encoder.
-- reg : Physical base address of the video codec registers and length of
- memory mapped region.
-- interrupts : interrupt number to the cpu.
-- mediatek,larb : must contain the local arbiters in the current Socs.
-- clocks : list of clock specifiers, corresponding to entries in
- the clock-names property.
-- clock-names: avc encoder must contain "venc_sel", vp8 encoder must
- contain "venc_lt_sel", decoder must contain "vcodecpll", "univpll_d2",
- "clk_cci400_sel", "vdec_sel", "vdecpll", "vencpll", "venc_lt_sel",
- "vdec_bus_clk_src".
-- iommus : should point to the respective IOMMU block with master port as
- argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml
- for details.
-- dma-ranges : describes the dma address range space that the codec hw access.
-One of the two following nodes:
-- mediatek,vpu : the node of the video processor unit, if using VPU.
-- mediatek,scp : the node of the SCP unit, if using SCP.
-
-
-Example:
-
-vcodec_dec: vcodec@16000000 {
- compatible = "mediatek,mt8173-vcodec-dec";
- reg = <0 0x16000000 0 0x100>, /*VDEC_SYS*/
- <0 0x16020000 0 0x1000>, /*VDEC_MISC*/
- <0 0x16021000 0 0x800>, /*VDEC_LD*/
- <0 0x16021800 0 0x800>, /*VDEC_TOP*/
- <0 0x16022000 0 0x1000>, /*VDEC_CM*/
- <0 0x16023000 0 0x1000>, /*VDEC_AD*/
- <0 0x16024000 0 0x1000>, /*VDEC_AV*/
- <0 0x16025000 0 0x1000>, /*VDEC_PP*/
- <0 0x16026800 0 0x800>, /*VP8_VD*/
- <0 0x16027000 0 0x800>, /*VP6_VD*/
- <0 0x16027800 0 0x800>, /*VP8_VL*/
- <0 0x16028400 0 0x400>; /*VP9_VD*/
- interrupts = <GIC_SPI 204 IRQ_TYPE_LEVEL_LOW>;
- mediatek,larb = <&larb1>;
- iommus = <&iommu M4U_PORT_HW_VDEC_MC_EXT>,
- <&iommu M4U_PORT_HW_VDEC_PP_EXT>,
- <&iommu M4U_PORT_HW_VDEC_AVC_MV_EXT>,
- <&iommu M4U_PORT_HW_VDEC_PRED_RD_EXT>,
- <&iommu M4U_PORT_HW_VDEC_PRED_WR_EXT>,
- <&iommu M4U_PORT_HW_VDEC_UFO_EXT>,
- <&iommu M4U_PORT_HW_VDEC_VLD_EXT>,
- <&iommu M4U_PORT_HW_VDEC_VLD2_EXT>;
- mediatek,vpu = <&vpu>;
- power-domains = <&scpsys MT8173_POWER_DOMAIN_VDEC>;
- clocks = <&apmixedsys CLK_APMIXED_VCODECPLL>,
- <&topckgen CLK_TOP_UNIVPLL_D2>,
- <&topckgen CLK_TOP_CCI400_SEL>,
- <&topckgen CLK_TOP_VDEC_SEL>,
- <&topckgen CLK_TOP_VCODECPLL>,
- <&apmixedsys CLK_APMIXED_VENCPLL>,
- <&topckgen CLK_TOP_VENC_LT_SEL>,
- <&topckgen CLK_TOP_VCODECPLL_370P5>;
- clock-names = "vcodecpll",
- "univpll_d2",
- "clk_cci400_sel",
- "vdec_sel",
- "vdecpll",
- "vencpll",
- "venc_lt_sel",
- "vdec_bus_clk_src";
- assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>,
- <&topckgen CLK_TOP_CCI400_SEL>,
- <&topckgen CLK_TOP_VDEC_SEL>,
- <&apmixedsys CLK_APMIXED_VCODECPLL>,
- <&apmixedsys CLK_APMIXED_VENCPLL>;
- assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>,
- <&topckgen CLK_TOP_UNIVPLL_D2>,
- <&topckgen CLK_TOP_VCODECPLL>;
- assigned-clock-rates = <0>, <0>, <0>, <1482000000>, <800000000>;
- };
-
-vcodec_enc_avc: vcodec@18002000 {
- compatible = "mediatek,mt8173-vcodec-enc";
- reg = <0 0x18002000 0 0x1000>;
- interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>;
- iommus = <&iommu M4U_PORT_VENC_RCPU>,
- <&iommu M4U_PORT_VENC_REC>,
- <&iommu M4U_PORT_VENC_BSDMA>,
- <&iommu M4U_PORT_VENC_SV_COMV>,
- <&iommu M4U_PORT_VENC_RD_COMV>,
- <&iommu M4U_PORT_VENC_CUR_LUMA>,
- <&iommu M4U_PORT_VENC_CUR_CHROMA>,
- <&iommu M4U_PORT_VENC_REF_LUMA>,
- <&iommu M4U_PORT_VENC_REF_CHROMA>,
- <&iommu M4U_PORT_VENC_NBM_RDMA>,
- <&iommu M4U_PORT_VENC_NBM_WDMA>;
- mediatek,larb = <&larb3>;
- mediatek,vpu = <&vpu>;
- clocks = <&topckgen CLK_TOP_VENC_SEL>;
- clock-names = "venc_sel";
- assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>;
- assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL>;
- };
-
-vcodec_enc_vp8: vcodec@19002000 {
- compatible = "mediatek,mt8173-vcodec-enc-vp8";
- reg = <0 0x19002000 0 0x1000>; /* VENC_LT_SYS */
- interrupts = <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>;
- iommus = <&iommu M4U_PORT_VENC_RCPU_SET2>,
- <&iommu M4U_PORT_VENC_REC_FRM_SET2>,
- <&iommu M4U_PORT_VENC_BSDMA_SET2>,
- <&iommu M4U_PORT_VENC_SV_COMA_SET2>,
- <&iommu M4U_PORT_VENC_RD_COMA_SET2>,
- <&iommu M4U_PORT_VENC_CUR_LUMA_SET2>,
- <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>,
- <&iommu M4U_PORT_VENC_REF_LUMA_SET2>,
- <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>;
- mediatek,larb = <&larb5>;
- mediatek,vpu = <&vpu>;
- clocks = <&topckgen CLK_TOP_VENC_LT_SEL>;
- clock-names = "venc_lt_sel";
- assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>;
- assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>;
- };
diff --git a/Documentation/devicetree/bindings/media/mediatek-vpu.txt b/Documentation/devicetree/bindings/media/mediatek-vpu.txt
deleted file mode 100644
index 2a5bac37f9a2..000000000000
--- a/Documentation/devicetree/bindings/media/mediatek-vpu.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-* Mediatek Video Processor Unit
-
-Video Processor Unit is a HW video controller. It controls HW Codec including
-H.264/VP8/VP9 Decode, H.264/VP8 Encode and Image Processor (scale/rotate/color convert).
-
-Required properties:
- - compatible: "mediatek,mt8173-vpu"
- - reg: Must contain an entry for each entry in reg-names.
- - reg-names: Must include the following entries:
- "tcm": tcm base
- "cfg_reg": Main configuration registers base
- - interrupts: interrupt number to the cpu.
- - clocks : clock name from clock manager
- - clock-names: must be main. It is the main clock of VPU
-
-Optional properties:
- - memory-region: phandle to a node describing memory (see
- Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt)
- to be used for VPU extended memory; if not present, VPU may be located
- anywhere in the memory
-
-Example:
- vpu: vpu@10020000 {
- compatible = "mediatek,mt8173-vpu";
- reg = <0 0x10020000 0 0x30000>,
- <0 0x10050000 0 0x100>;
- reg-names = "tcm", "cfg_reg";
- interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&topckgen TOP_SCP_SEL>;
- clock-names = "main";
- };
diff --git a/Documentation/devicetree/bindings/media/meson-ir.txt b/Documentation/devicetree/bindings/media/meson-ir.txt
deleted file mode 100644
index efd9d29a8f10..000000000000
--- a/Documentation/devicetree/bindings/media/meson-ir.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-* Amlogic Meson IR remote control receiver
-
-Required properties:
- - compatible : depending on the platform this should be one of:
- - "amlogic,meson6-ir"
- - "amlogic,meson8b-ir"
- - "amlogic,meson-gxbb-ir"
- - reg : physical base address and length of the device registers
- - interrupts : a single specifier for the interrupt from the device
-
-Optional properties:
- - linux,rc-map-name: see rc.txt file in the same directory.
-
-Example:
-
- ir-receiver@c8100480 {
- compatible= "amlogic,meson6-ir";
- reg = <0xc8100480 0x20>;
- interrupts = <0 15 1>;
- };
diff --git a/Documentation/devicetree/bindings/media/microchip,csi2dc.yaml b/Documentation/devicetree/bindings/media/microchip,csi2dc.yaml
new file mode 100644
index 000000000000..b3a345fc6464
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/microchip,csi2dc.yaml
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/microchip,csi2dc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip CSI2 Demux Controller (CSI2DC)
+
+maintainers:
+ - Eugen Hristev <eugen.hristev@microchip.com>
+
+description:
+ CSI2DC - Camera Serial Interface 2 Demux Controller
+
+ CSI2DC is a hardware block that receives incoming data from either from an
+ IDI interface or from a parallel bus interface.
+ It filters IDI packets based on their data type and virtual channel
+ identifier, then converts the byte stream to a pixel stream into a cross
+ clock domain towards a parallel interface that can be read by a sensor
+ controller.
+ IDI interface is Synopsys proprietary.
+ CSI2DC can act a simple bypass bridge if the incoming data is coming from
+ a parallel interface.
+
+ CSI2DC provides two pipes, one video pipe and one data pipe. Video pipe
+ is connected at the output to a sensor controller and the data pipe is
+ accessible as a DMA slave port to a DMA controller.
+
+ CSI2DC supports a single 'port' node as a sink port with either Synopsys
+ 32-bit IDI interface or a parallel interface.
+
+ CSI2DC supports one 'port' node as source port with parallel interface.
+ This is called video pipe.
+ This port has an 'endpoint' that can be connected to a sink port of another
+ controller (next in pipeline).
+
+ CSI2DC also supports direct access to the data through AHB, via DMA channel,
+ called data pipe.
+ For data pipe to be available, a dma controller and a dma channel must be
+ referenced.
+
+properties:
+ compatible:
+ const: microchip,sama7g5-csi2dc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 2
+ maxItems: 2
+
+ clock-names:
+ description:
+ CSI2DC must have two clocks to function correctly. One clock is the
+ peripheral clock for the inside functionality of the hardware block.
+ This is named 'pclk'. The second clock must be the cross domain clock,
+ in which CSI2DC will perform clock crossing. This clock must be fed
+ by the next controller in pipeline, which usually is a sensor controller.
+ Normally this clock should be given by this sensor controller who
+ is also a clock source. This clock is named 'scck', sensor controller clock.
+ items:
+ - const: pclk
+ - const: scck
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ const: rx
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing the input port.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+ description: Endpoint connected to input device
+
+ properties:
+ bus-type:
+ enum: [4, 5, 6]
+ default: 4
+
+ bus-width:
+ enum: [8, 9, 10, 11, 12, 13, 14]
+ default: 14
+
+ clock-noncontinuous:
+ type: boolean
+ description:
+ Presence of this boolean property decides whether clock is
+ continuous or noncontinuous.
+
+ remote-endpoint: true
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Output port node, single endpoint describing the output port.
+
+ properties:
+ endpoint:
+ unevaluatedProperties: false
+ $ref: video-interfaces.yaml#
+ description: Endpoint connected to output device
+
+ properties:
+ bus-type:
+ enum: [5, 6]
+ default: 5
+
+ bus-width:
+ enum: [8, 9, 10, 11, 12, 13, 14]
+ default: 14
+
+ remote-endpoint: true
+
+ required:
+ - port@0
+ - port@1
+
+additionalProperties: false
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - ports
+
+examples:
+ # Example for connecting to a parallel sensor controller block (video pipe)
+ # and the input is received from Synopsys IDI interface
+ - |
+ csi2dc@e1404000 {
+ compatible = "microchip,sama7g5-csi2dc";
+ reg = <0xe1404000 0x500>;
+ clocks = <&pclk>, <&scck>;
+ clock-names = "pclk", "scck";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ port@0 {
+ reg = <0>; /* must be 0, first child port */
+ csi2dc_in: endpoint { /* input from IDI interface */
+ bus-type = <4>; /* MIPI CSI2 D-PHY */
+ remote-endpoint = <&csi2host_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>; /* must be 1, second child port */
+ csi2dc_out: endpoint {
+ remote-endpoint = <&xisc_in>; /* output to sensor controller */
+ };
+ };
+ };
+ };
+
+ # Example for connecting to a DMA master as an AHB slave
+ # and the input is received from Synopsys IDI interface
+ - |
+ #include <dt-bindings/dma/at91.h>
+ csi2dc@e1404000 {
+ compatible = "microchip,sama7g5-csi2dc";
+ reg = <0xe1404000 0x500>;
+ clocks = <&pclk>, <&scck>;
+ clock-names = "pclk", "scck";
+ dmas = <&dma0 AT91_XDMAC_DT_PERID(34)>;
+ dma-names = "rx";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ port@0 {
+ reg = <0>; /* must be 0, first child port */
+ csi2dc_input: endpoint { /* input from IDI interface */
+ remote-endpoint = <&csi2host_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/microchip,sama5d4-vdec.yaml b/Documentation/devicetree/bindings/media/microchip,sama5d4-vdec.yaml
index 4b77103ca913..ede086d55add 100644
--- a/Documentation/devicetree/bindings/media/microchip,sama5d4-vdec.yaml
+++ b/Documentation/devicetree/bindings/media/microchip,sama5d4-vdec.yaml
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/microchip,sama5d4-vdec.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/microchip,sama5d4-vdec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Hantro G1 VPU codec implemented on Microchip SAMA5D4 SoCs
@@ -36,12 +35,12 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/clock/at91.h>
- #include <dt-bindings/interrupt-controller/irq.h>
-
- vdec0: vdec@300000 {
- compatible = "microchip,sama5d4-vdec";
- reg = <0x00300000 0x100000>;
- interrupts = <19 IRQ_TYPE_LEVEL_HIGH 4>;
- clocks = <&pmc PMC_TYPE_PERIPHERAL 19>;
- };
+ #include <dt-bindings/clock/at91.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ vdec@300000 {
+ compatible = "microchip,sama5d4-vdec";
+ reg = <0x00300000 0x100000>;
+ interrupts = <19 IRQ_TYPE_LEVEL_HIGH 4>;
+ clocks = <&pmc PMC_TYPE_PERIPHERAL 19>;
+ };
diff --git a/Documentation/devicetree/bindings/media/microchip,xisc.yaml b/Documentation/devicetree/bindings/media/microchip,xisc.yaml
index 41afe2e5f133..25f5f79d40ce 100644
--- a/Documentation/devicetree/bindings/media/microchip,xisc.yaml
+++ b/Documentation/devicetree/bindings/media/microchip,xisc.yaml
@@ -52,7 +52,7 @@ properties:
of the data and clock lines.
port:
- $ref: /schemas/graph.yaml#/properties/port
+ $ref: /schemas/graph.yaml#/$defs/port-base
description:
Input port node, single endpoint describing the input pad.
@@ -67,7 +67,7 @@ properties:
remote-endpoint: true
bus-width:
- enum: [8, 9, 10, 11, 12]
+ enum: [8, 9, 10, 11, 12, 14]
default: 12
hsync-active:
@@ -106,6 +106,7 @@ examples:
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/clock/at91.h>
#include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/media/video-interfaces.h>
xisc: xisc@e1408000 {
compatible = "microchip,sama7g5-isc";
@@ -118,7 +119,7 @@ examples:
port {
xisc_in: endpoint {
- bus-type = <5>; /* Parallel */
+ bus-type = <MEDIA_BUS_TYPE_PARALLEL>;
remote-endpoint = <&csi2dc_out>;
hsync-active = <1>;
vsync-active = <1>;
@@ -126,4 +127,3 @@ examples:
};
};
};
-
diff --git a/Documentation/devicetree/bindings/media/mtk-cir.txt b/Documentation/devicetree/bindings/media/mtk-cir.txt
deleted file mode 100644
index 5e18087ce11f..000000000000
--- a/Documentation/devicetree/bindings/media/mtk-cir.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-Device-Tree bindings for Mediatek consumer IR controller
-found in Mediatek SoC family
-
-Required properties:
-- compatible : Should be
- "mediatek,mt7623-cir": for MT7623 SoC
- "mediatek,mt7622-cir": for MT7622 SoC
-- clocks : list of clock specifiers, corresponding to
- entries in clock-names property;
-- clock-names : should contain
- - "clk" entries: for MT7623 SoC
- - "clk", "bus" entries: for MT7622 SoC
-- interrupts : should contain IR IRQ number;
-- reg : should contain IO map address for IR.
-
-Optional properties:
-- linux,rc-map-name : see rc.txt file in the same directory.
-
-Example:
-
-cir: cir@10013000 {
- compatible = "mediatek,mt7623-cir";
- reg = <0 0x10013000 0 0x1000>;
- interrupts = <GIC_SPI 87 IRQ_TYPE_LEVEL_LOW>;
- clocks = <&infracfg CLK_INFRA_IRRX>;
- clock-names = "clk";
- linux,rc-map-name = "rc-rc6-mce";
-};
diff --git a/Documentation/devicetree/bindings/media/nokia,n900-ir b/Documentation/devicetree/bindings/media/nokia,n900-ir
deleted file mode 100644
index 13a18ce37dd1..000000000000
--- a/Documentation/devicetree/bindings/media/nokia,n900-ir
+++ /dev/null
@@ -1,20 +0,0 @@
-Device-Tree bindings for LIRC TX driver for Nokia N900(RX51)
-
-Required properties:
- - compatible: should be "nokia,n900-ir".
- - pwms: specifies PWM used for IR signal transmission.
-
-Example node:
-
- pwm9: dmtimer-pwm@9 {
- compatible = "ti,omap-dmtimer-pwm";
- ti,timers = <&timer9>;
- ti,clock-source = <0x00>; /* timer_sys_ck */
- #pwm-cells = <3>;
- };
-
- ir: n900-ir {
- compatible = "nokia,n900-ir";
-
- pwms = <&pwm9 0 26316 0>; /* 38000 Hz */
- };
diff --git a/Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml b/Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml
new file mode 100644
index 000000000000..b47468e54504
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nuvoton,npcm-ece.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton NPCM Encoding Compression Engine
+
+maintainers:
+ - Joseph Liu <kwliu@nuvoton.com>
+ - Marvin Lin <kflin@nuvoton.com>
+
+description: |
+ Video Encoding Compression Engine (ECE) present on Nuvoton NPCM SoCs.
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,npcm750-ece
+ - nuvoton,npcm845-ece
+
+ reg:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/reset/nuvoton,npcm7xx-reset.h>
+
+ ece: video-codec@f0820000 {
+ compatible = "nuvoton,npcm750-ece";
+ reg = <0xf0820000 0x2000>;
+ resets = <&rstc NPCM7XX_RESET_IPSRST2 NPCM7XX_RESET_ECE>;
+ };
diff --git a/Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml b/Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml
new file mode 100644
index 000000000000..c885f559d2e5
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nuvoton,npcm-vcd.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Nuvoton NPCM Video Capture/Differentiation Engine
+
+maintainers:
+ - Joseph Liu <kwliu@nuvoton.com>
+ - Marvin Lin <kflin@nuvoton.com>
+
+description: |
+ Video Capture/Differentiation Engine (VCD) present on Nuvoton NPCM SoCs.
+
+properties:
+ compatible:
+ enum:
+ - nuvoton,npcm750-vcd
+ - nuvoton,npcm845-vcd
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+ nuvoton,sysgcr:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to access GCR (Global Control Register) registers.
+
+ nuvoton,sysgfxi:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to access GFXI (Graphics Core Information) registers.
+
+ nuvoton,ece:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: phandle to access ECE (Encoding Compression Engine) registers.
+
+ memory-region:
+ maxItems: 1
+ description:
+ CMA pool to use for buffers allocation instead of the default CMA pool.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - resets
+ - nuvoton,sysgcr
+ - nuvoton,sysgfxi
+ - nuvoton,ece
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/reset/nuvoton,npcm7xx-reset.h>
+
+ vcd: vcd@f0810000 {
+ compatible = "nuvoton,npcm750-vcd";
+ reg = <0xf0810000 0x10000>;
+ interrupts = <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>;
+ resets = <&rstc NPCM7XX_RESET_IPSRST2 NPCM7XX_RESET_VCD>;
+ nuvoton,sysgcr = <&gcr>;
+ nuvoton,sysgfxi = <&gfxi>;
+ nuvoton,ece = <&ece>;
+ };
diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt
deleted file mode 100644
index 602169b8aa19..000000000000
--- a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt
+++ /dev/null
@@ -1,64 +0,0 @@
-NVIDIA Tegra Video Decoder Engine
-
-Required properties:
-- compatible : Must contain one of the following values:
- - "nvidia,tegra20-vde"
- - "nvidia,tegra30-vde"
- - "nvidia,tegra114-vde"
- - "nvidia,tegra124-vde"
- - "nvidia,tegra132-vde"
-- reg : Must contain an entry for each entry in reg-names.
-- reg-names : Must include the following entries:
- - sxe
- - bsev
- - mbe
- - ppe
- - mce
- - tfe
- - ppb
- - vdma
- - frameid
-- iram : Must contain phandle to the mmio-sram device node that represents
- IRAM region used by VDE.
-- interrupts : Must contain an entry for each entry in interrupt-names.
-- interrupt-names : Must include the following entries:
- - sync-token
- - bsev
- - sxe
-- clocks : Must include the following entries:
- - vde
-- resets : Must contain an entry for each entry in reset-names.
-- reset-names : Should include the following entries:
- - vde
-
-Optional properties:
-- resets : Must contain an entry for each entry in reset-names.
-- reset-names : Must include the following entries:
- - mc
-- iommus: Must contain phandle to the IOMMU device node.
-
-Example:
-
-video-codec@6001a000 {
- compatible = "nvidia,tegra20-vde";
- reg = <0x6001a000 0x1000 /* Syntax Engine */
- 0x6001b000 0x1000 /* Video Bitstream Engine */
- 0x6001c000 0x100 /* Macroblock Engine */
- 0x6001c200 0x100 /* Post-processing Engine */
- 0x6001c400 0x100 /* Motion Compensation Engine */
- 0x6001c600 0x100 /* Transform Engine */
- 0x6001c800 0x100 /* Pixel prediction block */
- 0x6001ca00 0x100 /* Video DMA */
- 0x6001d800 0x300 /* Video frame controls */>;
- reg-names = "sxe", "bsev", "mbe", "ppe", "mce",
- "tfe", "ppb", "vdma", "frameid";
- iram = <&vde_pool>; /* IRAM region */
- interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, /* Sync token interrupt */
- <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>, /* BSE-V interrupt */
- <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; /* SXE interrupt */
- interrupt-names = "sync-token", "bsev", "sxe";
- clocks = <&tegra_car TEGRA20_CLK_VDE>;
- reset-names = "vde", "mc";
- resets = <&tegra_car 61>, <&mc TEGRA20_MC_RESET_VDE>;
- iommus = <&mc TEGRA_SWGROUP_VDE>;
-};
diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml
new file mode 100644
index 000000000000..4ecdee1be37e
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.yaml
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nvidia,tegra-vde.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra Video Decoder Engine
+
+maintainers:
+ - Dmitry Osipenko <digetx@gmail.com>
+ - Jon Hunter <jonathanh@nvidia.com>
+ - Thierry Reding <thierry.reding@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - nvidia,tegra132-vde
+ - nvidia,tegra124-vde
+ - nvidia,tegra114-vde
+ - items:
+ - const: nvidia,tegra30-vde
+ - const: nvidia,tegra20-vde
+ - items:
+ - const: nvidia,tegra20-vde
+
+ reg:
+ maxItems: 9
+
+ reg-names:
+ items:
+ - const: sxe
+ - const: bsev
+ - const: mbe
+ - const: ppe
+ - const: mce
+ - const: tfe
+ - const: ppb
+ - const: vdma
+ - const: frameid
+
+ clocks:
+ maxItems: 1
+
+ resets:
+ maxItems: 2
+
+ reset-names:
+ items:
+ - const: vde
+ - const: mc
+
+ interrupts:
+ maxItems: 3
+
+ interrupt-names:
+ items:
+ - const: sync-token
+ - const: bsev
+ - const: sxe
+
+ iommus:
+ maxItems: 1
+
+ iram:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Phandle of the SRAM MMIO node.
+
+ operating-points-v2:
+ description:
+ Should contain freqs and voltages and opp-supported-hw property,
+ which is a bitfield indicating SoC speedo or process ID mask.
+
+ power-domains:
+ maxItems: 1
+ description:
+ Phandle to the SoC core power domain.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - resets
+ - reset-names
+ - interrupts
+ - interrupt-names
+
+additionalProperties: false
+
+examples:
+ - |
+ video-codec@6001a000 {
+ compatible = "nvidia,tegra20-vde";
+ reg = <0x6001a000 0x1000>, /* Syntax Engine */
+ <0x6001b000 0x1000>, /* Video Bitstream Engine */
+ <0x6001c000 0x100>, /* Macroblock Engine */
+ <0x6001c200 0x100>, /* Post-processing Engine */
+ <0x6001c400 0x100>, /* Motion Compensation Engine */
+ <0x6001c600 0x100>, /* Transform Engine */
+ <0x6001c800 0x100>, /* Pixel prediction block */
+ <0x6001ca00 0x100>, /* Video DMA */
+ <0x6001d800 0x300>; /* Video frame controls */
+ reg-names = "sxe", "bsev", "mbe", "ppe", "mce",
+ "tfe", "ppb", "vdma", "frameid";
+ iram = <&iram>; /* IRAM MMIO region */
+ interrupts = <0 9 4>, /* Sync token */
+ <0 10 4>, /* BSE-V */
+ <0 12 4>; /* SXE */
+ interrupt-names = "sync-token", "bsev", "sxe";
+ clocks = <&clk 61>;
+ reset-names = "vde", "mc";
+ resets = <&rst 61>, <&mem 13>;
+ iommus = <&mem 15>;
+ operating-points-v2 = <&dvfs_opp_table>;
+ power-domains = <&domain>;
+ };
diff --git a/Documentation/devicetree/bindings/media/nxp,dw100.yaml b/Documentation/devicetree/bindings/media/nxp,dw100.yaml
new file mode 100644
index 000000000000..21910ff0e1c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nxp,dw100.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nxp,dw100.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX8MP DW100 Dewarper core
+
+maintainers:
+ - Xavier Roumegue <xavier.roumegue@oss.nxp.com>
+
+description: |-
+ The Dewarp Engine provides high-performance dewarp processing for the
+ correction of the distortion that is introduced in images produced by fisheye
+ and wide angle lenses. It is implemented with a line/tile-cache based
+ architecture. With configurable address mapping look up tables and per tile
+ processing, it successfully generates a corrected output image.
+ The engine can be used to perform scaling, cropping and pixel format
+ conversion.
+
+properties:
+ compatible:
+ enum:
+ - nxp,imx8mp-dw100
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: The AXI clock
+ - description: The AHB clock
+
+ clock-names:
+ items:
+ - const: axi
+ - const: ahb
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx8mp-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/imx8mp-power.h>
+
+ dewarp: dwe@32e30000 {
+ compatible = "nxp,imx8mp-dw100";
+ reg = <0x32e30000 0x10000>;
+ interrupts = <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX8MP_CLK_MEDIA_AXI_ROOT>,
+ <&clk IMX8MP_CLK_MEDIA_APB_ROOT>;
+ clock-names = "axi", "ahb";
+ power-domains = <&media_blk_ctrl IMX8MP_MEDIABLK_PD_DWE>;
+ };
diff --git a/Documentation/devicetree/bindings/media/nxp,imx-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx-mipi-csi2.yaml
new file mode 100644
index 000000000000..41ad5b84eaeb
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nxp,imx-mipi-csi2.yaml
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nxp,imx-mipi-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX7 and i.MX8 MIPI CSI-2 receiver
+
+maintainers:
+ - Rui Miguel Silva <rmfrfs@gmail.com>
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |-
+ The NXP i.MX7 and i.MX8 families contain SoCs that include a MIPI CSI-2
+ receiver IP core named CSIS. The IP core originates from Samsung, and may be
+ compatible with some of the Exynos4 and S5P SoCs. i.MX7 SoCs use CSIS version
+ 3.3, and i.MX8 SoCs use CSIS version 3.6.3.
+
+ While the CSI-2 receiver is separate from the MIPI D-PHY IP core, the PHY is
+ completely wrapped by the CSIS and doesn't expose a control interface of its
+ own. This binding thus covers both IP cores.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - fsl,imx7-mipi-csi2
+ - fsl,imx8mm-mipi-csi2
+ - items:
+ - enum:
+ - fsl,imx8mp-mipi-csi2
+ - const: fsl,imx8mm-mipi-csi2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ minItems: 3
+ items:
+ - description: The peripheral clock (a.k.a. APB clock)
+ - description: The external clock (optionally used as the pixel clock)
+ - description: The MIPI D-PHY clock
+ - description: The AXI clock
+
+ clock-names:
+ minItems: 3
+ items:
+ - const: pclk
+ - const: wrap
+ - const: phy
+ - const: axi
+
+ power-domains:
+ maxItems: 1
+
+ phy-supply:
+ description: The MIPI D-PHY digital power supply
+
+ resets:
+ items:
+ - description: MIPI D-PHY slave reset
+
+ clock-frequency:
+ description: The desired external clock ("wrap") frequency, in Hz
+ default: 166000000
+ deprecated: true
+
+ fsl,num-channels:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Number of output channels
+ minimum: 1
+ maximum: 4
+ default: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ description:
+ Note that 'fsl,imx7-mipi-csi2' only supports up to 2 data lines.
+ minItems: 1
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Output port node
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - ports
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: fsl,imx7-mipi-csi2
+ then:
+ required:
+ - phy-supply
+ - resets
+ else:
+ properties:
+ clocks:
+ minItems: 4
+ clock-names:
+ minItems: 4
+ phy-supply: false
+ resets: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx7d-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/reset/imx7-reset.h>
+
+ mipi-csi@30750000 {
+ compatible = "fsl,imx7-mipi-csi2";
+ reg = <0x30750000 0x10000>;
+ interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>;
+
+ clocks = <&clks IMX7D_IPG_ROOT_CLK>,
+ <&clks IMX7D_MIPI_CSI_ROOT_CLK>,
+ <&clks IMX7D_MIPI_DPHY_ROOT_CLK>;
+ clock-names = "pclk", "wrap", "phy";
+
+ assigned-clocks = <&clks IMX7D_MIPI_CSI_ROOT_CLK>;
+ assigned-clock-rates = <166000000>;
+
+ power-domains = <&pgc_mipi_phy>;
+ phy-supply = <&reg_1p0d>;
+ resets = <&src IMX7_RESET_MIPI_PHY_MRST>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ mipi_from_sensor: endpoint {
+ remote-endpoint = <&ov2680_to_mipi>;
+ data-lanes = <1>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ mipi_vc0_to_csi_mux: endpoint {
+ remote-endpoint = <&csi_mux_from_mipi_vc0>;
+ };
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/clock/imx8mm-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ mipi-csi@32e30000 {
+ compatible = "fsl,imx8mm-mipi-csi2";
+ reg = <0x32e30000 0x1000>;
+ interrupts = <GIC_SPI 17 IRQ_TYPE_LEVEL_HIGH>;
+
+ clocks = <&clk IMX8MM_CLK_DISP_APB_ROOT>,
+ <&clk IMX8MM_CLK_CSI1_ROOT>,
+ <&clk IMX8MM_CLK_CSI1_PHY_REF>,
+ <&clk IMX8MM_CLK_DISP_AXI_ROOT>;
+ clock-names = "pclk", "wrap", "phy", "axi";
+
+ assigned-clocks = <&clk IMX8MM_CLK_CSI1_ROOT>;
+ assigned-clock-rates = <250000000>;
+
+ power-domains = <&mipi_pd>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ imx8mm_mipi_csi_in: endpoint {
+ remote-endpoint = <&imx477_out>;
+ data-lanes = <1 2 3 4>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ imx8mm_mipi_csi_out: endpoint {
+ remote-endpoint = <&csi_in>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml
index d91575b8ebb9..326284e151f6 100644
--- a/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml
+++ b/Documentation/devicetree/bindings/media/nxp,imx7-csi.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/nxp,imx7-csi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: i.MX7 CMOS Sensor Interface
+title: i.MX7 and i.MX8 CSI bridge (CMOS Sensor Interface)
maintainers:
- Rui Miguel Silva <rmfrfs@gmail.com>
@@ -15,9 +15,14 @@ description: |
properties:
compatible:
- enum:
- - fsl,imx7-csi
- - fsl,imx6ul-csi
+ oneOf:
+ - enum:
+ - fsl,imx8mq-csi
+ - fsl,imx7-csi
+ - fsl,imx6ul-csi
+ - items:
+ - const: fsl,imx8mm-csi
+ - const: fsl,imx7-csi
reg:
maxItems: 1
@@ -32,6 +37,9 @@ properties:
items:
- const: mclk
+ power-domains:
+ maxItems: 1
+
port:
$ref: /schemas/graph.yaml#/properties/port
@@ -45,6 +53,17 @@ required:
additionalProperties: false
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8mm-csi
+ then:
+ required:
+ - power-domains
+
examples:
- |
#include <dt-bindings/clock/imx7d-clock.h>
diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml
deleted file mode 100644
index 7c09eec78ce5..000000000000
--- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml
+++ /dev/null
@@ -1,228 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/media/nxp,imx7-mipi-csi2.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: NXP i.MX7 and i.MX8 MIPI CSI-2 receiver
-
-maintainers:
- - Rui Miguel Silva <rmfrfs@gmail.com>
- - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
-
-description: |-
- The NXP i.MX7 and i.MX8 families contain SoCs that include a MIPI CSI-2
- receiver IP core named CSIS. The IP core originates from Samsung, and may be
- compatible with some of the Exynos4 and S5P SoCs. i.MX7 SoCs use CSIS version
- 3.3, and i.MX8 SoCs use CSIS version 3.6.3.
-
- While the CSI-2 receiver is separate from the MIPI D-PHY IP core, the PHY is
- completely wrapped by the CSIS and doesn't expose a control interface of its
- own. This binding thus covers both IP cores.
-
-properties:
- compatible:
- enum:
- - fsl,imx7-mipi-csi2
- - fsl,imx8mm-mipi-csi2
-
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
- clocks:
- minItems: 3
- items:
- - description: The peripheral clock (a.k.a. APB clock)
- - description: The external clock (optionally used as the pixel clock)
- - description: The MIPI D-PHY clock
- - description: The AXI clock
-
- clock-names:
- minItems: 3
- items:
- - const: pclk
- - const: wrap
- - const: phy
- - const: axi
-
- power-domains:
- maxItems: 1
-
- phy-supply:
- description: The MIPI D-PHY digital power supply
-
- resets:
- items:
- - description: MIPI D-PHY slave reset
-
- clock-frequency:
- description: The desired external clock ("wrap") frequency, in Hz
- default: 166000000
-
- ports:
- $ref: /schemas/graph.yaml#/properties/ports
-
- properties:
- port@0:
- $ref: /schemas/graph.yaml#/$defs/port-base
- unevaluatedProperties: false
- description:
- Input port node, single endpoint describing the CSI-2 transmitter.
-
- properties:
- endpoint:
- $ref: video-interfaces.yaml#
- unevaluatedProperties: false
-
- properties:
- data-lanes:
- items:
- minItems: 1
- maxItems: 4
- items:
- - const: 1
- - const: 2
- - const: 3
- - const: 4
-
- required:
- - data-lanes
-
- allOf:
- - if:
- properties:
- compatible:
- contains:
- const: fsl,imx7-mipi-csi2
- then:
- properties:
- data-lanes:
- items:
- maxItems: 2
-
- port@1:
- $ref: /schemas/graph.yaml#/properties/port
- description:
- Output port node
-
-required:
- - compatible
- - reg
- - interrupts
- - clocks
- - clock-names
- - power-domains
- - ports
-
-additionalProperties: false
-
-allOf:
- - if:
- properties:
- compatible:
- contains:
- const: fsl,imx7-mipi-csi2
- then:
- required:
- - phy-supply
- - resets
- else:
- properties:
- clocks:
- minItems: 4
- clock-names:
- minItems: 4
- phy-supply: false
- resets: false
-
-examples:
- - |
- #include <dt-bindings/clock/imx7d-clock.h>
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/interrupt-controller/irq.h>
- #include <dt-bindings/reset/imx7-reset.h>
-
- mipi-csi@30750000 {
- compatible = "fsl,imx7-mipi-csi2";
- reg = <0x30750000 0x10000>;
- interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>;
-
- clocks = <&clks IMX7D_IPG_ROOT_CLK>,
- <&clks IMX7D_MIPI_CSI_ROOT_CLK>,
- <&clks IMX7D_MIPI_DPHY_ROOT_CLK>;
- clock-names = "pclk", "wrap", "phy";
- clock-frequency = <166000000>;
-
- power-domains = <&pgc_mipi_phy>;
- phy-supply = <&reg_1p0d>;
- resets = <&src IMX7_RESET_MIPI_PHY_MRST>;
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
-
- mipi_from_sensor: endpoint {
- remote-endpoint = <&ov2680_to_mipi>;
- data-lanes = <1>;
- };
- };
-
- port@1 {
- reg = <1>;
-
- mipi_vc0_to_csi_mux: endpoint {
- remote-endpoint = <&csi_mux_from_mipi_vc0>;
- };
- };
- };
- };
-
- - |
- #include <dt-bindings/clock/imx8mm-clock.h>
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/interrupt-controller/irq.h>
-
- mipi-csi@32e30000 {
- compatible = "fsl,imx8mm-mipi-csi2";
- reg = <0x32e30000 0x1000>;
- interrupts = <GIC_SPI 17 IRQ_TYPE_LEVEL_HIGH>;
- clock-frequency = <333000000>;
- clocks = <&clk IMX8MM_CLK_DISP_APB_ROOT>,
- <&clk IMX8MM_CLK_CSI1_ROOT>,
- <&clk IMX8MM_CLK_CSI1_PHY_REF>,
- <&clk IMX8MM_CLK_DISP_AXI_ROOT>;
- clock-names = "pclk", "wrap", "phy", "axi";
- power-domains = <&mipi_pd>;
-
- status = "disabled";
-
- ports {
- #address-cells = <1>;
- #size-cells = <0>;
-
- port@0 {
- reg = <0>;
-
- imx8mm_mipi_csi_in: endpoint {
- remote-endpoint = <&imx477_out>;
- data-lanes = <1 2 3 4>;
- };
- };
-
- port@1 {
- reg = <1>;
-
- imx8mm_mipi_csi_out: endpoint {
- remote-endpoint = <&csi_in>;
- };
- };
- };
- };
-
-...
diff --git a/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml b/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml
new file mode 100644
index 000000000000..001a0d9b71e0
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nxp,imx8-isi.yaml
@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nxp,imx8-isi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: i.MX8 Image Sensing Interface
+
+maintainers:
+ - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |
+ The Image Sensing Interface (ISI) combines image processing pipelines with
+ DMA engines to process and capture frames originating from a variety of
+ sources. The inputs to the ISI go through Pixel Link interfaces, and their
+ number and nature is SoC-dependent. They cover both capture interfaces (MIPI
+ CSI-2 RX, HDMI RX, ...) and display engine outputs for writeback support.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx8mn-isi
+ - fsl,imx8mp-isi
+ - fsl,imx8ulp-isi
+ - fsl,imx91-isi
+ - fsl,imx93-isi
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: The AXI clock
+ - description: The APB clock
+ # TODO: Check if the per-channel ipg_proc_clk clocks need to be specified
+ # as well, in case some SoCs have the ability to control them separately.
+ # This may be the case of the i.MX8[DQ]X(P)
+
+ clock-names:
+ items:
+ - const: axi
+ - const: apb
+
+ fsl,blk-ctrl:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ A phandle referencing the block control that contains the CSIS to ISI
+ gasket.
+
+ interrupts:
+ description: Processing pipeline interrupts, one per pipeline
+ minItems: 1
+ maxItems: 2
+
+ power-domains:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ description: |
+ Ports represent the Pixel Link inputs to the ISI. Their number and
+ assignment are model-dependent. Each port shall have a single endpoint.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - ports
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8mn-isi
+ - fsl,imx8ulp-isi
+ - fsl,imx91-isi
+ - fsl,imx93-isi
+ then:
+ properties:
+ interrupts:
+ maxItems: 1
+ ports:
+ properties:
+ port@0:
+ description: MIPI CSI-2 RX
+ port@1: false
+ required:
+ - port@0
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: fsl,imx8mp-isi
+ then:
+ properties:
+ interrupts:
+ maxItems: 2
+ ports:
+ properties:
+ port@0:
+ description: MIPI CSI-2 RX 0
+ port@1:
+ description: MIPI CSI-2 RX 1
+ required:
+ - port@0
+ - port@1
+
+ - if:
+ properties:
+ compatible:
+ not:
+ contains:
+ const: fsl,imx91-isi
+ then:
+ required:
+ - fsl,blk-ctrl
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx8mn-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/power/imx8mn-power.h>
+
+ isi@32e20000 {
+ compatible = "fsl,imx8mn-isi";
+ reg = <0x32e20000 0x100>;
+ interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX8MN_CLK_DISP_AXI_ROOT>,
+ <&clk IMX8MN_CLK_DISP_APB_ROOT>;
+ clock-names = "axi", "apb";
+ fsl,blk-ctrl = <&disp_blk_ctrl>;
+ power-domains = <&disp_blk_ctrl IMX8MN_DISPBLK_PD_ISI>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ isi_in: endpoint {
+ remote-endpoint = <&mipi_csi_out>;
+ };
+ };
+ };
+ };
+
+ - |
+ #include <dt-bindings/clock/imx8mp-clock.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ isi@32e00000 {
+ compatible = "fsl,imx8mp-isi";
+ reg = <0x32e00000 0x4000>;
+ interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX8MP_CLK_MEDIA_AXI_ROOT>,
+ <&clk IMX8MP_CLK_MEDIA_APB_ROOT>;
+ clock-names = "axi", "apb";
+ fsl,blk-ctrl = <&media_blk_ctrl>;
+ power-domains = <&mediamix_pd>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ isi_in_0: endpoint {
+ remote-endpoint = <&mipi_csi_0_out>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ isi_in_1: endpoint {
+ remote-endpoint = <&mipi_csi_1_out>;
+ };
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml
index 5d13cbb5251b..b5aca3d2cc5c 100644
--- a/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml
+++ b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/nxp,imx8-jpeg.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: i.MX8QXP/QM JPEG decoder/encoder Device Tree Bindings
+title: i.MX8QXP/QM JPEG decoder/encoder
maintainers:
- Mirela Rabulea <mirela.rabulea@nxp.com>
@@ -16,16 +16,30 @@ description: |-
properties:
compatible:
- items:
- - enum:
- # JPEG decoder
- - nxp,imx8qxp-jpgdec
- # JPEG encoder
- - nxp,imx8qxp-jpgenc
+ oneOf:
+ - items:
+ enum:
+ - nxp,imx8qxp-jpgdec
+ - nxp,imx8qxp-jpgenc
+ - items:
+ - enum:
+ - nxp,imx8qm-jpgdec
+ - nxp,imx95-jpgdec
+ - const: nxp,imx8qxp-jpgdec
+ - items:
+ - enum:
+ - nxp,imx8qm-jpgenc
+ - nxp,imx95-jpgenc
+ - const: nxp,imx8qxp-jpgenc
reg:
maxItems: 1
+ clocks:
+ items:
+ - description: AXI DMA engine clock for fetching JPEG bitstream from memory (per)
+ - description: IP bus clock for register access (ipg)
+
interrupts:
description: |
There are 4 slots available in the IP, which the driver may use
@@ -38,25 +52,46 @@ properties:
description:
List of phandle and PM domain specifier as documented in
Documentation/devicetree/bindings/power/power_domain.txt
- minItems: 2 # Wrapper and 1 slot
+ minItems: 1 # Wrapper and all slots
maxItems: 5 # Wrapper and 4 slots
required:
- compatible
- reg
+ - clocks
- interrupts
- power-domains
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - nxp,imx95-jpgenc
+ - nxp,imx95-jpgdec
+ then:
+ properties:
+ power-domains:
+ maxItems: 1
+ else:
+ properties:
+ power-domains:
+ minItems: 2 # Wrapper and 1 slot
+
additionalProperties: false
examples:
- |
+ #include <dt-bindings/clock/imx8-lpcg.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/firmware/imx/rsrc.h>
jpegdec: jpegdec@58400000 {
compatible = "nxp,imx8qxp-jpgdec";
reg = <0x58400000 0x00050000 >;
+ clocks = <&img_jpeg_dec_lpcg IMX_LPCG_CLK_0>,
+ <&img_jpeg_dec_lpcg IMX_LPCG_CLK_4>;
interrupts = <GIC_SPI 309 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 310 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 311 IRQ_TYPE_LEVEL_HIGH>,
@@ -69,8 +104,10 @@ examples:
};
jpegenc: jpegenc@58450000 {
- compatible = "nxp,imx8qxp-jpgenc";
+ compatible = "nxp,imx8qm-jpgenc", "nxp,imx8qxp-jpgenc";
reg = <0x58450000 0x00050000 >;
+ clocks = <&img_jpeg_enc_lpcg IMX_LPCG_CLK_0>,
+ <&img_jpeg__lpcg IMX_LPCG_CLK_4>;
interrupts = <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 306 IRQ_TYPE_LEVEL_HIGH>,
<GIC_SPI 307 IRQ_TYPE_LEVEL_HIGH>,
diff --git a/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml
new file mode 100644
index 000000000000..3389bab266a9
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/nxp,imx8mq-mipi-csi2.yaml
@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/nxp,imx8mq-mipi-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX8MQ MIPI CSI-2 receiver
+
+maintainers:
+ - Martin Kepplinger <martin.kepplinger@puri.sm>
+
+description: |-
+ This binding covers the CSI-2 RX PHY and host controller included in the
+ NXP i.MX8MQ SoC. It handles the sensor/image input and process for all the
+ input imaging devices.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - fsl,imx8mq-mipi-csi2
+ - fsl,imx8qxp-mipi-csi2
+ - items:
+ - const: fsl,imx8qm-mipi-csi2
+ - const: fsl,imx8qxp-mipi-csi2
+
+ reg:
+ items:
+ - description: MIPI CSI-2 RX host controller register.
+ - description: MIPI CSI-2 control and status register (csr).
+ minItems: 1
+
+ clocks:
+ items:
+ - description: core is the RX Controller Core Clock input. This clock
+ must be exactly equal to or faster than the receive
+ byteclock from the RX DPHY.
+ - description: esc is the Rx Escape Clock. This must be the same escape
+ clock that the RX DPHY receives.
+ - description: ui is the pixel clock (phy_ref up to 333Mhz).
+ See the reference manual for details.
+
+ clock-names:
+ items:
+ - const: core
+ - const: esc
+ - const: ui
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ items:
+ - description: CORE_RESET reset register bit definition
+ - description: PHY_REF_RESET reset register bit definition
+ - description: ESC_RESET reset register bit definition
+ minItems: 1
+
+ fsl,mipi-phy-gpr:
+ description: |
+ The phandle to the imx8mq syscon iomux-gpr with the register
+ for setting RX_ENABLE for the mipi receiver.
+
+ The format should be as follows:
+ <gpr req_gpr>
+ gpr is the phandle to general purpose register node.
+ req_gpr is the gpr register offset of RX_ENABLE for the mipi phy.
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: The 'gpr' is the phandle to general purpose register node.
+ - description: The 'req_gpr' is the gpr register offset containing
+ CSI2_1_RX_ENABLE or CSI2_2_RX_ENABLE respectively.
+ maximum: 0xff
+
+ interconnects:
+ maxItems: 1
+
+ interconnect-names:
+ const: dram
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Output port node
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+ - ports
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - fsl,imx8qxp-mipi-csi2
+ then:
+ properties:
+ reg:
+ minItems: 2
+ resets:
+ maxItems: 1
+ else:
+ properties:
+ reg:
+ maxItems: 1
+ resets:
+ minItems: 3
+ required:
+ - fsl,mipi-phy-gpr
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/imx8mq-clock.h>
+ #include <dt-bindings/interconnect/imx8mq.h>
+ #include <dt-bindings/reset/imx8mq-reset.h>
+
+ csi@30a70000 {
+ compatible = "fsl,imx8mq-mipi-csi2";
+ reg = <0x30a70000 0x1000>;
+ clocks = <&clk IMX8MQ_CLK_CSI1_CORE>,
+ <&clk IMX8MQ_CLK_CSI1_ESC>,
+ <&clk IMX8MQ_CLK_CSI1_PHY_REF>;
+ clock-names = "core", "esc", "ui";
+ assigned-clocks = <&clk IMX8MQ_CLK_CSI1_CORE>,
+ <&clk IMX8MQ_CLK_CSI1_PHY_REF>,
+ <&clk IMX8MQ_CLK_CSI1_ESC>;
+ assigned-clock-rates = <266000000>, <200000000>, <66000000>;
+ assigned-clock-parents = <&clk IMX8MQ_SYS1_PLL_266M>,
+ <&clk IMX8MQ_SYS2_PLL_1000M>,
+ <&clk IMX8MQ_SYS1_PLL_800M>;
+ power-domains = <&pgc_mipi_csi1>;
+ resets = <&src IMX8MQ_RESET_MIPI_CSI1_CORE_RESET>,
+ <&src IMX8MQ_RESET_MIPI_CSI1_PHY_REF_RESET>,
+ <&src IMX8MQ_RESET_MIPI_CSI1_ESC_RESET>;
+ fsl,mipi-phy-gpr = <&iomuxc_gpr 0x88>;
+ interconnects = <&noc IMX8MQ_ICM_CSI1 &noc IMX8MQ_ICS_DRAM>;
+ interconnect-names = "dram";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ imx8mm_mipi_csi_in: endpoint {
+ remote-endpoint = <&imx477_out>;
+ data-lanes = <1 2 3 4>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+
+ imx8mm_mipi_csi_out: endpoint {
+ remote-endpoint = <&csi_in>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/nxp,imx8mq-vpu.yaml b/Documentation/devicetree/bindings/media/nxp,imx8mq-vpu.yaml
index 762be3f96ce9..19528262810a 100644
--- a/Documentation/devicetree/bindings/media/nxp,imx8mq-vpu.yaml
+++ b/Documentation/devicetree/bindings/media/nxp,imx8mq-vpu.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/nxp,imx8mq-vpu.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/nxp,imx8mq-vpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Hantro G1/G2 VPU codecs implemented on i.MX8MQ SoCs
+title: Hantro G1/G2 VPU codecs implemented on i.MX8M SoCs
maintainers:
- Philipp Zabel <p.zabel@pengutronix.de>
@@ -15,33 +14,21 @@ description:
properties:
compatible:
- const: nxp,imx8mq-vpu
+ oneOf:
+ - const: nxp,imx8mq-vpu
+ deprecated: true
+ - const: nxp,imx8mq-vpu-g1
+ - const: nxp,imx8mq-vpu-g2
+ - const: nxp,imx8mm-vpu-g1
reg:
- maxItems: 3
-
- reg-names:
- items:
- - const: g1
- - const: g2
- - const: ctrl
+ maxItems: 1
interrupts:
- maxItems: 2
-
- interrupt-names:
- items:
- - const: g1
- - const: g2
+ maxItems: 1
clocks:
- maxItems: 3
-
- clock-names:
- items:
- - const: g1
- - const: g2
- - const: bus
+ maxItems: 1
power-domains:
maxItems: 1
@@ -49,31 +36,33 @@ properties:
required:
- compatible
- reg
- - reg-names
- interrupts
- - interrupt-names
- clocks
- - clock-names
additionalProperties: false
examples:
- |
- #include <dt-bindings/clock/imx8mq-clock.h>
- #include <dt-bindings/interrupt-controller/arm-gic.h>
-
- vpu: video-codec@38300000 {
- compatible = "nxp,imx8mq-vpu";
- reg = <0x38300000 0x10000>,
- <0x38310000 0x10000>,
- <0x38320000 0x10000>;
- reg-names = "g1", "g2", "ctrl";
- interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "g1", "g2";
- clocks = <&clk IMX8MQ_CLK_VPU_G1_ROOT>,
- <&clk IMX8MQ_CLK_VPU_G2_ROOT>,
- <&clk IMX8MQ_CLK_VPU_DEC_ROOT>;
- clock-names = "g1", "g2", "bus";
- power-domains = <&pgc_vpu>;
- };
+ #include <dt-bindings/clock/imx8mq-clock.h>
+ #include <dt-bindings/power/imx8mq-power.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ video-codec@38300000 {
+ compatible = "nxp,imx8mq-vpu-g1";
+ reg = <0x38300000 0x10000>;
+ interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX8MQ_CLK_VPU_G1_ROOT>;
+ power-domains = <&vpu_blk_ctrl IMX8MQ_VPUBLK_PD_G1>;
+ };
+ - |
+ #include <dt-bindings/clock/imx8mq-clock.h>
+ #include <dt-bindings/power/imx8mq-power.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ video-codec@38300000 {
+ compatible = "nxp,imx8mq-vpu-g2";
+ reg = <0x38310000 0x10000>;
+ interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clk IMX8MQ_CLK_VPU_G2_ROOT>;
+ power-domains = <&vpu_blk_ctrl IMX8MQ_VPUBLK_PD_G2>;
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml
index 304908072d72..7c8e0a905d89 100644
--- a/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,msm8916-camss.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,msm8916-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm CAMSS ISP
@@ -83,10 +82,6 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 1
-
data-lanes:
description:
An array of physical data lanes indexes.
@@ -98,8 +93,11 @@ properties:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@1:
@@ -114,16 +112,15 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 1
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
reg:
@@ -165,7 +162,7 @@ examples:
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/clock/qcom,gcc-msm8916.h>
- camss: camss@1b00000 {
+ camss: camss@1b0ac00 {
compatible = "qcom,msm8916-camss";
clocks = <&gcc GCC_CAMSS_TOP_AHB_CLK>,
diff --git a/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml b/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml
index 59ab16ad12f1..da140c2e3d3f 100644
--- a/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,msm8916-venus.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,msm8916-venus.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,msm8916-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm Venus video encode and decode accelerators
+title: Qualcomm MSM8916 Venus video encode and decode accelerators
maintainers:
- Stanimir Varbanov <stanimir.varbanov@linaro.org>
@@ -14,16 +13,13 @@ description: |
The Venus IP is a video encode and decode accelerator present
on Qualcomm platforms
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
properties:
compatible:
const: qcom,msm8916-venus
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
power-domains:
maxItems: 1
@@ -39,19 +35,17 @@ properties:
iommus:
maxItems: 1
- memory-region:
- maxItems: 1
-
video-decoder:
type: object
properties:
compatible:
- const: "venus-decoder"
+ const: venus-decoder
required:
- compatible
+ deprecated: true
additionalProperties: false
video-encoder:
@@ -59,63 +53,34 @@ properties:
properties:
compatible:
- const: "venus-encoder"
+ const: venus-encoder
required:
- compatible
+ deprecated: true
additionalProperties: false
- video-firmware:
- type: object
-
- description: |
- Firmware subnode is needed when the platform does not
- have TrustZone.
-
- properties:
- iommus:
- maxItems: 1
-
- required:
- - iommus
-
required:
- compatible
- - reg
- - interrupts
- - power-domains
- - clocks
- - clock-names
- iommus
- - memory-region
- - video-decoder
- - video-encoder
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/qcom,gcc-msm8916.h>
-
- video-codec@1d00000 {
- compatible = "qcom,msm8916-venus";
- reg = <0x01d00000 0xff000>;
- interrupts = <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&gcc GCC_VENUS0_VCODEC0_CLK>,
- <&gcc GCC_VENUS0_AHB_CLK>,
- <&gcc GCC_VENUS0_AXI_CLK>;
- clock-names = "core", "iface", "bus";
- power-domains = <&gcc VENUS_GDSC>;
- iommus = <&apps_iommu 5>;
- memory-region = <&venus_mem>;
-
- video-decoder {
- compatible = "venus-decoder";
- };
-
- video-encoder {
- compatible = "venus-encoder";
- };
- };
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,gcc-msm8916.h>
+
+ video-codec@1d00000 {
+ compatible = "qcom,msm8916-venus";
+ reg = <0x01d00000 0xff000>;
+ interrupts = <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&gcc GCC_VENUS0_VCODEC0_CLK>,
+ <&gcc GCC_VENUS0_AHB_CLK>,
+ <&gcc GCC_VENUS0_AXI_CLK>;
+ clock-names = "core", "iface", "bus";
+ power-domains = <&gcc VENUS_GDSC>;
+ iommus = <&apps_iommu 5>;
+ memory-region = <&venus_mem>;
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,msm8939-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8939-camss.yaml
new file mode 100644
index 000000000000..77b389d76a43
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,msm8939-camss.yaml
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,msm8939-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm MSM8939 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Vincent Knecht <vincent.knecht@mailoo.org>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms
+
+properties:
+ compatible:
+ const: qcom,msm8939-camss
+
+ reg:
+ maxItems: 11
+
+ reg-names:
+ items:
+ - const: csiphy0
+ - const: csiphy0_clk_mux
+ - const: csiphy1
+ - const: csiphy1_clk_mux
+ - const: csid0
+ - const: csid1
+ - const: ispif
+ - const: csi_clk_mux
+ - const: vfe0
+ - const: csid2
+ - const: vfe0_vbif
+
+ clocks:
+ maxItems: 24
+
+ clock-names:
+ items:
+ - const: top_ahb
+ - const: ispif_ahb
+ - const: csiphy0_timer
+ - const: csiphy1_timer
+ - const: csi0_ahb
+ - const: csi0
+ - const: csi0_phy
+ - const: csi0_pix
+ - const: csi0_rdi
+ - const: csi1_ahb
+ - const: csi1
+ - const: csi1_phy
+ - const: csi1_pix
+ - const: csi1_rdi
+ - const: ahb
+ - const: vfe0
+ - const: csi_vfe0
+ - const: vfe_ahb
+ - const: vfe_axi
+ - const: csi2_ahb
+ - const: csi2
+ - const: csi2_phy
+ - const: csi2_pix
+ - const: csi2_rdi
+
+ interrupts:
+ maxItems: 7
+
+ interrupt-names:
+ items:
+ - const: csiphy0
+ - const: csiphy1
+ - const: csid0
+ - const: csid1
+ - const: ispif
+ - const: vfe0
+ - const: csid2
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: VFE GDSC - Video Front End, Global Distributed Switch
+ Controller.
+
+ vdda-supply:
+ description:
+ Definition of the regulator used as 1.2V analog power supply.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ patternProperties:
+ "^port@[0-1]$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - iommus
+ - power-domains
+ - vdda-supply
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,gcc-msm8939.h>
+
+ isp@1b0ac00 {
+ compatible = "qcom,msm8939-camss";
+
+ reg = <0x01b0ac00 0x200>,
+ <0x01b00030 0x4>,
+ <0x01b0b000 0x200>,
+ <0x01b00038 0x4>,
+ <0x01b08000 0x100>,
+ <0x01b08400 0x100>,
+ <0x01b0a000 0x500>,
+ <0x01b00020 0x10>,
+ <0x01b10000 0x1000>,
+ <0x01b08800 0x100>,
+ <0x01b40000 0x200>;
+
+ reg-names = "csiphy0",
+ "csiphy0_clk_mux",
+ "csiphy1",
+ "csiphy1_clk_mux",
+ "csid0",
+ "csid1",
+ "ispif",
+ "csi_clk_mux",
+ "vfe0",
+ "csid2",
+ "vfe0_vbif";
+
+ clocks = <&gcc GCC_CAMSS_TOP_AHB_CLK>,
+ <&gcc GCC_CAMSS_ISPIF_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_CSI0_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI0_CLK>,
+ <&gcc GCC_CAMSS_CSI0PHY_CLK>,
+ <&gcc GCC_CAMSS_CSI0PIX_CLK>,
+ <&gcc GCC_CAMSS_CSI0RDI_CLK>,
+ <&gcc GCC_CAMSS_CSI1_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI1_CLK>,
+ <&gcc GCC_CAMSS_CSI1PHY_CLK>,
+ <&gcc GCC_CAMSS_CSI1PIX_CLK>,
+ <&gcc GCC_CAMSS_CSI1RDI_CLK>,
+ <&gcc GCC_CAMSS_AHB_CLK>,
+ <&gcc GCC_CAMSS_VFE0_CLK>,
+ <&gcc GCC_CAMSS_CSI_VFE0_CLK>,
+ <&gcc GCC_CAMSS_VFE_AHB_CLK>,
+ <&gcc GCC_CAMSS_VFE_AXI_CLK>,
+ <&gcc GCC_CAMSS_CSI2_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI2_CLK>,
+ <&gcc GCC_CAMSS_CSI2PHY_CLK>,
+ <&gcc GCC_CAMSS_CSI2PIX_CLK>,
+ <&gcc GCC_CAMSS_CSI2RDI_CLK>;
+
+ clock-names = "top_ahb",
+ "ispif_ahb",
+ "csiphy0_timer",
+ "csiphy1_timer",
+ "csi0_ahb",
+ "csi0",
+ "csi0_phy",
+ "csi0_pix",
+ "csi0_rdi",
+ "csi1_ahb",
+ "csi1",
+ "csi1_phy",
+ "csi1_pix",
+ "csi1_rdi",
+ "ahb",
+ "vfe0",
+ "csi_vfe0",
+ "vfe_ahb",
+ "vfe_axi",
+ "csi2_ahb",
+ "csi2",
+ "csi2_phy",
+ "csi2_pix",
+ "csi2_rdi";
+
+ interrupts = <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 51 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 52 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 55 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 57 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 153 IRQ_TYPE_EDGE_RISING>;
+
+ interrupt-names = "csiphy0",
+ "csiphy1",
+ "csid0",
+ "csid1",
+ "ispif",
+ "vfe0",
+ "csid2";
+
+ iommus = <&apps_iommu 3>;
+
+ power-domains = <&gcc VFE_GDSC>;
+
+ vdda-supply = <&reg_1v2>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@1 {
+ reg = <1>;
+
+ csiphy1_ep: endpoint {
+ data-lanes = <0 2>;
+ remote-endpoint = <&sensor_ep>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,msm8953-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8953-camss.yaml
new file mode 100644
index 000000000000..6d776b0ca711
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,msm8953-camss.yaml
@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,msm8953-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm MSM8953 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Barnabas Czeman <barnabas.czeman@mainlining.org>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms
+
+properties:
+ compatible:
+ const: qcom,msm8953-camss
+
+ clocks:
+ minItems: 30
+ maxItems: 30
+
+ clock-names:
+ items:
+ - const: ahb
+ - const: csi0
+ - const: csi0_ahb
+ - const: csi0_phy
+ - const: csi0_pix
+ - const: csi0_rdi
+ - const: csi1
+ - const: csi1_ahb
+ - const: csi1_phy
+ - const: csi1_pix
+ - const: csi1_rdi
+ - const: csi2
+ - const: csi2_ahb
+ - const: csi2_phy
+ - const: csi2_pix
+ - const: csi2_rdi
+ - const: csi_vfe0
+ - const: csi_vfe1
+ - const: csiphy0_timer
+ - const: csiphy1_timer
+ - const: csiphy2_timer
+ - const: ispif_ahb
+ - const: micro_ahb
+ - const: top_ahb
+ - const: vfe0
+ - const: vfe0_ahb
+ - const: vfe0_axi
+ - const: vfe1
+ - const: vfe1_ahb
+ - const: vfe1_axi
+
+ interrupts:
+ minItems: 9
+ maxItems: 9
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: ispif
+ - const: vfe0
+ - const: vfe1
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: VFE0 GDSC - Video Front End, Global Distributed Switch Controller.
+ - description: VFE1 GDSC - Video Front End, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: vfe0
+ - const: vfe1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ description:
+ An array of physical data lanes indexes.
+ Position of an entry determines the logical
+ lane number, while the value of an entry
+ indicates physical lane index. Lane swapping
+ is supported. Physical lane indexes;
+ 0, 2, 3, 4.
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+
+ reg:
+ minItems: 13
+ maxItems: 13
+
+ reg-names:
+ items:
+ - const: csi_clk_mux
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csiphy0
+ - const: csiphy0_clk_mux
+ - const: csiphy1
+ - const: csiphy1_clk_mux
+ - const: csiphy2
+ - const: csiphy2_clk_mux
+ - const: ispif
+ - const: vfe0
+ - const: vfe1
+
+ vdda-supply:
+ description:
+ Definition of the regulator used as analog power supply.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - vdda-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,gcc-msm8953.h>
+
+ camss: camss@1b00020 {
+ compatible = "qcom,msm8953-camss";
+
+ reg = <0x1b00020 0x10>,
+ <0x1b30000 0x100>,
+ <0x1b30400 0x100>,
+ <0x1b30800 0x100>,
+ <0x1b34000 0x1000>,
+ <0x1b00030 0x4>,
+ <0x1b35000 0x1000>,
+ <0x1b00038 0x4>,
+ <0x1b36000 0x1000>,
+ <0x1b00040 0x4>,
+ <0x1b31000 0x500>,
+ <0x1b10000 0x1000>,
+ <0x1b14000 0x1000>;
+ reg-names = "csi_clk_mux",
+ "csid0",
+ "csid1",
+ "csid2",
+ "csiphy0",
+ "csiphy0_clk_mux",
+ "csiphy1",
+ "csiphy1_clk_mux",
+ "csiphy2",
+ "csiphy2_clk_mux",
+ "ispif",
+ "vfe0",
+ "vfe1";
+
+ clocks = <&gcc GCC_CAMSS_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI0_CLK>,
+ <&gcc GCC_CAMSS_CSI0_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI0PHY_CLK>,
+ <&gcc GCC_CAMSS_CSI0PIX_CLK>,
+ <&gcc GCC_CAMSS_CSI0RDI_CLK>,
+ <&gcc GCC_CAMSS_CSI1_CLK>,
+ <&gcc GCC_CAMSS_CSI1_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI1PHY_CLK>,
+ <&gcc GCC_CAMSS_CSI1PIX_CLK>,
+ <&gcc GCC_CAMSS_CSI1RDI_CLK>,
+ <&gcc GCC_CAMSS_CSI2_CLK>,
+ <&gcc GCC_CAMSS_CSI2_AHB_CLK>,
+ <&gcc GCC_CAMSS_CSI2PHY_CLK>,
+ <&gcc GCC_CAMSS_CSI2PIX_CLK>,
+ <&gcc GCC_CAMSS_CSI2RDI_CLK>,
+ <&gcc GCC_CAMSS_CSI_VFE0_CLK>,
+ <&gcc GCC_CAMSS_CSI_VFE1_CLK>,
+ <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_CSI2PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_ISPIF_AHB_CLK>,
+ <&gcc GCC_CAMSS_MICRO_AHB_CLK>,
+ <&gcc GCC_CAMSS_TOP_AHB_CLK>,
+ <&gcc GCC_CAMSS_VFE0_CLK>,
+ <&gcc GCC_CAMSS_VFE0_AHB_CLK>,
+ <&gcc GCC_CAMSS_VFE0_AXI_CLK>,
+ <&gcc GCC_CAMSS_VFE1_CLK>,
+ <&gcc GCC_CAMSS_VFE1_AHB_CLK>,
+ <&gcc GCC_CAMSS_VFE1_AXI_CLK>;
+ clock-names = "ahb",
+ "csi0",
+ "csi0_ahb",
+ "csi0_phy",
+ "csi0_pix",
+ "csi0_rdi",
+ "csi1",
+ "csi1_ahb",
+ "csi1_phy",
+ "csi1_pix",
+ "csi1_rdi",
+ "csi2",
+ "csi2_ahb",
+ "csi2_phy",
+ "csi2_pix",
+ "csi2_rdi",
+ "csi_vfe0",
+ "csi_vfe1",
+ "csiphy0_timer",
+ "csiphy1_timer",
+ "csiphy2_timer",
+ "ispif_ahb",
+ "micro_ahb",
+ "top_ahb",
+ "vfe0",
+ "vfe0_ahb",
+ "vfe0_axi",
+ "vfe1",
+ "vfe1_ahb",
+ "vfe1_axi";
+
+ interrupts = <GIC_SPI 51 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 52 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 153 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 315 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 55 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 57 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 29 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid2",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "ispif",
+ "vfe0",
+ "vfe1";
+
+ iommus = <&apps_iommu 0x14>;
+
+ power-domains = <&gcc VFE0_GDSC>,
+ <&gcc VFE1_GDSC>;
+ power-domain-names = "vfe0", "vfe1";
+
+ vdda-supply = <&reg_2v8>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml
index 38be41e932f0..a2025952fe95 100644
--- a/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,msm8996-camss.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,msm8996-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm CAMSS ISP
@@ -105,10 +104,6 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
description:
An array of physical data lanes indexes.
@@ -120,8 +115,12 @@ properties:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@1:
@@ -136,16 +135,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@2:
@@ -160,16 +159,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@3:
@@ -184,16 +183,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
reg:
@@ -241,7 +240,7 @@ examples:
#include <dt-bindings/clock/qcom,gcc-msm8996.h>
#include <dt-bindings/clock/qcom,mmcc-msm8996.h>
- camss: camss@a00000 {
+ camss: camss@a34000 {
compatible = "qcom,msm8996-camss";
clocks = <&mmcc CAMSS_TOP_AHB_CLK>,
diff --git a/Documentation/devicetree/bindings/media/qcom,msm8996-venus.yaml b/Documentation/devicetree/bindings/media/qcom,msm8996-venus.yaml
index 199f45217b4a..56c16458e3bb 100644
--- a/Documentation/devicetree/bindings/media/qcom,msm8996-venus.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,msm8996-venus.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,msm8996-venus.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,msm8996-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm Venus video encode and decode accelerators
+title: Qualcomm MSM8996 Venus video encode and decode accelerators
maintainers:
- Stanimir Varbanov <stanimir.varbanov@linaro.org>
@@ -14,15 +13,14 @@ description: |
The Venus IP is a video encode and decode accelerator present
on Qualcomm platforms
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
properties:
compatible:
- const: qcom,msm8996-venus
-
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
+ enum:
+ - qcom,msm8996-venus
+ - qcom,msm8998-venus
power-domains:
maxItems: 1
@@ -37,12 +35,17 @@ properties:
- const: bus
- const: mbus
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: video-mem
+ - const: cpu-cfg
+
iommus:
maxItems: 20
- memory-region:
- maxItems: 1
-
video-decoder:
type: object
@@ -93,82 +96,62 @@ properties:
additionalProperties: false
- video-firmware:
- type: object
-
- description: |
- Firmware subnode is needed when the platform does not
- have TrustZone.
-
- properties:
- iommus:
- maxItems: 1
-
- required:
- - iommus
-
required:
- compatible
- - reg
- - interrupts
- - power-domains
- - clocks
- - clock-names
- iommus
- - memory-region
- video-decoder
- video-encoder
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/qcom,mmcc-msm8996.h>
-
- video-codec@c00000 {
- compatible = "qcom,msm8996-venus";
- reg = <0x00c00000 0xff000>;
- interrupts = <GIC_SPI 287 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&mmcc VIDEO_CORE_CLK>,
- <&mmcc VIDEO_AHB_CLK>,
- <&mmcc VIDEO_AXI_CLK>,
- <&mmcc VIDEO_MAXI_CLK>;
- clock-names = "core", "iface", "bus", "mbus";
- power-domains = <&mmcc VENUS_GDSC>;
- iommus = <&venus_smmu 0x00>,
- <&venus_smmu 0x01>,
- <&venus_smmu 0x0a>,
- <&venus_smmu 0x07>,
- <&venus_smmu 0x0e>,
- <&venus_smmu 0x0f>,
- <&venus_smmu 0x08>,
- <&venus_smmu 0x09>,
- <&venus_smmu 0x0b>,
- <&venus_smmu 0x0c>,
- <&venus_smmu 0x0d>,
- <&venus_smmu 0x10>,
- <&venus_smmu 0x11>,
- <&venus_smmu 0x21>,
- <&venus_smmu 0x28>,
- <&venus_smmu 0x29>,
- <&venus_smmu 0x2b>,
- <&venus_smmu 0x2c>,
- <&venus_smmu 0x2d>,
- <&venus_smmu 0x31>;
- memory-region = <&venus_mem>;
-
- video-decoder {
- compatible = "venus-decoder";
- clocks = <&mmcc VIDEO_SUBCORE0_CLK>;
- clock-names = "core";
- power-domains = <&mmcc VENUS_CORE0_GDSC>;
- };
-
- video-encoder {
- compatible = "venus-encoder";
- clocks = <&mmcc VIDEO_SUBCORE1_CLK>;
- clock-names = "core";
- power-domains = <&mmcc VENUS_CORE1_GDSC>;
- };
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,mmcc-msm8996.h>
+
+ video-codec@c00000 {
+ compatible = "qcom,msm8996-venus";
+ reg = <0x00c00000 0xff000>;
+ interrupts = <GIC_SPI 287 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&mmcc VIDEO_CORE_CLK>,
+ <&mmcc VIDEO_AHB_CLK>,
+ <&mmcc VIDEO_AXI_CLK>,
+ <&mmcc VIDEO_MAXI_CLK>;
+ clock-names = "core", "iface", "bus", "mbus";
+ power-domains = <&mmcc VENUS_GDSC>;
+ iommus = <&venus_smmu 0x00>,
+ <&venus_smmu 0x01>,
+ <&venus_smmu 0x0a>,
+ <&venus_smmu 0x07>,
+ <&venus_smmu 0x0e>,
+ <&venus_smmu 0x0f>,
+ <&venus_smmu 0x08>,
+ <&venus_smmu 0x09>,
+ <&venus_smmu 0x0b>,
+ <&venus_smmu 0x0c>,
+ <&venus_smmu 0x0d>,
+ <&venus_smmu 0x10>,
+ <&venus_smmu 0x11>,
+ <&venus_smmu 0x21>,
+ <&venus_smmu 0x28>,
+ <&venus_smmu 0x29>,
+ <&venus_smmu 0x2b>,
+ <&venus_smmu 0x2c>,
+ <&venus_smmu 0x2d>,
+ <&venus_smmu 0x31>;
+ memory-region = <&venus_mem>;
+
+ video-decoder {
+ compatible = "venus-decoder";
+ clocks = <&mmcc VIDEO_SUBCORE0_CLK>;
+ clock-names = "core";
+ power-domains = <&mmcc VENUS_CORE0_GDSC>;
+ };
+
+ video-encoder {
+ compatible = "venus-encoder";
+ clocks = <&mmcc VIDEO_SUBCORE1_CLK>;
+ clock-names = "core";
+ power-domains = <&mmcc VENUS_CORE1_GDSC>;
};
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,qcm2290-camss.yaml b/Documentation/devicetree/bindings/media/qcom,qcm2290-camss.yaml
new file mode 100644
index 000000000000..391d0f6f67ef
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,qcm2290-camss.yaml
@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,qcm2290-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm QCM2290 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Loic Poulain <loic.poulain@oss.qualcomm.com>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,qcm2290-camss
+
+ reg:
+ maxItems: 9
+
+ reg-names:
+ items:
+ - const: top
+ - const: csid0
+ - const: csid1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csitpg0
+ - const: csitpg1
+ - const: vfe0
+ - const: vfe1
+
+ clocks:
+ maxItems: 15
+
+ clock-names:
+ items:
+ - const: ahb
+ - const: axi
+ - const: camnoc_nrt_axi
+ - const: camnoc_rt_axi
+ - const: csi0
+ - const: csi1
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: top_ahb
+ - const: vfe0
+ - const: vfe0_cphy_rx
+ - const: vfe1
+ - const: vfe1_cphy_rx
+
+ interrupts:
+ maxItems: 8
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csitpg0
+ - const: csitpg1
+ - const: vfe0
+ - const: vfe1
+
+ interconnects:
+ maxItems: 3
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_mnoc
+ - const: sf_mnoc
+
+ iommus:
+ maxItems: 4
+
+ power-domains:
+ items:
+ - description: GDSC CAMSS Block, Global Distributed Switch Controller.
+
+ vdd-csiphy-1p2-supply:
+ description:
+ Phandle to a 1.2V regulator supply to CSI PHYs.
+
+ vdd-csiphy-1p8-supply:
+ description:
+ Phandle to 1.8V regulator supply to CSI PHYs pll block.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ patternProperties:
+ "^port@[0-3]+$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ description:
+ Input port for receiving CSI data from a CSIPHY.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domains
+ - vdd-csiphy-1p2-supply
+ - vdd-csiphy-1p8-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-qcm2290.h>
+ #include <dt-bindings/interconnect/qcom,rpm-icc.h>
+ #include <dt-bindings/interconnect/qcom,qcm2290.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ camss: camss@5c6e000 {
+ compatible = "qcom,qcm2290-camss";
+
+ reg = <0x0 0x5c11000 0x0 0x1000>,
+ <0x0 0x5c6e000 0x0 0x1000>,
+ <0x0 0x5c75000 0x0 0x1000>,
+ <0x0 0x5c52000 0x0 0x1000>,
+ <0x0 0x5c53000 0x0 0x1000>,
+ <0x0 0x5c66000 0x0 0x400>,
+ <0x0 0x5c68000 0x0 0x400>,
+ <0x0 0x5c6f000 0x0 0x4000>,
+ <0x0 0x5c76000 0x0 0x4000>;
+ reg-names = "top",
+ "csid0",
+ "csid1",
+ "csiphy0",
+ "csiphy1",
+ "csitpg0",
+ "csitpg1",
+ "vfe0",
+ "vfe1";
+
+ clocks = <&gcc GCC_CAMERA_AHB_CLK>,
+ <&gcc GCC_CAMSS_AXI_CLK>,
+ <&gcc GCC_CAMSS_NRT_AXI_CLK>,
+ <&gcc GCC_CAMSS_RT_AXI_CLK>,
+ <&gcc GCC_CAMSS_TFE_0_CSID_CLK>,
+ <&gcc GCC_CAMSS_TFE_1_CSID_CLK>,
+ <&gcc GCC_CAMSS_CPHY_0_CLK>,
+ <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_CPHY_1_CLK>,
+ <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>,
+ <&gcc GCC_CAMSS_TOP_AHB_CLK>,
+ <&gcc GCC_CAMSS_TFE_0_CLK>,
+ <&gcc GCC_CAMSS_TFE_0_CPHY_RX_CLK>,
+ <&gcc GCC_CAMSS_TFE_1_CLK>,
+ <&gcc GCC_CAMSS_TFE_1_CPHY_RX_CLK>;
+ clock-names = "ahb",
+ "axi",
+ "camnoc_nrt_axi",
+ "camnoc_rt_axi",
+ "csi0",
+ "csi1",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "top_ahb",
+ "vfe0",
+ "vfe0_cphy_rx",
+ "vfe1",
+ "vfe1_cphy_rx";
+
+ interrupts = <GIC_SPI 210 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 212 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 72 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 73 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 309 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 310 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 211 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 213 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csiphy0",
+ "csiphy1",
+ "csitpg0",
+ "csitpg1",
+ "vfe0",
+ "vfe1";
+
+ interconnects = <&bimc MASTER_APPSS_PROC RPM_ACTIVE_TAG
+ &config_noc SLAVE_CAMERA_CFG RPM_ACTIVE_TAG>,
+ <&mmrt_virt MASTER_CAMNOC_HF RPM_ALWAYS_TAG
+ &bimc SLAVE_EBI1 RPM_ALWAYS_TAG>,
+ <&mmnrt_virt MASTER_CAMNOC_SF RPM_ALWAYS_TAG
+ &bimc SLAVE_EBI1 RPM_ALWAYS_TAG>;
+ interconnect-names = "ahb",
+ "hf_mnoc",
+ "sf_mnoc";
+
+ iommus = <&apps_smmu 0x400 0x0>,
+ <&apps_smmu 0x800 0x0>,
+ <&apps_smmu 0x820 0x0>,
+ <&apps_smmu 0x840 0x0>;
+
+ power-domains = <&gcc GCC_CAMSS_TOP_GDSC>;
+
+ vdd-csiphy-1p2-supply = <&pm4125_l5>;
+ vdd-csiphy-1p8-supply = <&pm4125_l13>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,qcm2290-venus.yaml b/Documentation/devicetree/bindings/media/qcom,qcm2290-venus.yaml
new file mode 100644
index 000000000000..3f3ee82fc878
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,qcm2290-venus.yaml
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,qcm2290-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm QCM2290 Venus video encode and decode accelerators
+
+maintainers:
+ - Jorge Ramirez-Ortiz <jorge.ramirez@oss.qualcomm.com>
+
+description:
+ The Venus AR50_LITE IP is a video encode and decode accelerator present
+ on Qualcomm platforms.
+
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
+properties:
+ compatible:
+ const: qcom,qcm2290-venus
+
+ power-domains:
+ maxItems: 3
+
+ power-domain-names:
+ items:
+ - const: venus
+ - const: vcodec0
+ - const: cx
+
+ clocks:
+ maxItems: 6
+
+ clock-names:
+ items:
+ - const: core
+ - const: iface
+ - const: bus
+ - const: throttle
+ - const: vcodec0_core
+ - const: vcodec0_bus
+
+ iommus:
+ maxItems: 5
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: video-mem
+ - const: cpu-cfg
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+required:
+ - compatible
+ - power-domain-names
+ - iommus
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,gcc-qcm2290.h>
+ #include <dt-bindings/interconnect/qcom,qcm2290.h>
+ #include <dt-bindings/interconnect/qcom,rpm-icc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ venus: video-codec@5a00000 {
+ compatible = "qcom,qcm2290-venus";
+ reg = <0x5a00000 0xf0000>;
+
+ interrupts = <GIC_SPI 225 IRQ_TYPE_LEVEL_HIGH>;
+
+ power-domains = <&gcc GCC_VENUS_GDSC>,
+ <&gcc GCC_VCODEC0_GDSC>,
+ <&rpmpd QCM2290_VDDCX>;
+ power-domain-names = "venus",
+ "vcodec0",
+ "cx";
+
+ operating-points-v2 = <&venus_opp_table>;
+
+ clocks = <&gcc GCC_VIDEO_VENUS_CTL_CLK>,
+ <&gcc GCC_VIDEO_AHB_CLK>,
+ <&gcc GCC_VENUS_CTL_AXI_CLK>,
+ <&gcc GCC_VIDEO_THROTTLE_CORE_CLK>,
+ <&gcc GCC_VIDEO_VCODEC0_SYS_CLK>,
+ <&gcc GCC_VCODEC0_AXI_CLK>;
+ clock-names = "core",
+ "iface",
+ "bus",
+ "throttle",
+ "vcodec0_core",
+ "vcodec0_bus";
+
+ memory-region = <&pil_video_mem>;
+
+ iommus = <&apps_smmu 0x860 0x0>,
+ <&apps_smmu 0x880 0x0>,
+ <&apps_smmu 0x861 0x04>,
+ <&apps_smmu 0x863 0x0>,
+ <&apps_smmu 0x804 0xe0>;
+
+ interconnects = <&mmnrt_virt MASTER_VIDEO_P0 RPM_ALWAYS_TAG
+ &bimc SLAVE_EBI1 RPM_ALWAYS_TAG>,
+ <&bimc MASTER_APPSS_PROC RPM_ACTIVE_TAG
+ &config_noc SLAVE_VENUS_CFG RPM_ACTIVE_TAG>;
+ interconnect-names = "video-mem",
+ "cpu-cfg";
+
+ venus_opp_table: opp-table {
+ compatible = "operating-points-v2";
+
+ opp-133333333 {
+ opp-hz = /bits/ 64 <133333333>;
+ required-opps = <&rpmpd_opp_low_svs>;
+ };
+
+ opp-240000000 {
+ opp-hz = /bits/ 64 <240000000>;
+ required-opps = <&rpmpd_opp_svs>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,qcs8300-camss.yaml b/Documentation/devicetree/bindings/media/qcom,qcs8300-camss.yaml
new file mode 100644
index 000000000000..80a4540a22dc
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,qcs8300-camss.yaml
@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,qcs8300-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm QCS8300 CAMSS ISP
+
+maintainers:
+ - Vikram Sharma <quic_vikramsa@quicinc.com>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,qcs8300-camss
+
+ reg:
+ maxItems: 21
+
+ reg-names:
+ items:
+ - const: csid_wrapper
+ - const: csid0
+ - const: csid1
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csid_lite2
+ - const: csid_lite3
+ - const: csid_lite4
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: tpg0
+ - const: tpg1
+ - const: tpg2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+ - const: vfe_lite2
+ - const: vfe_lite3
+ - const: vfe_lite4
+
+ clocks:
+ maxItems: 26
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: core_ahb
+ - const: cpas_ahb
+ - const: cpas_fast_ahb_clk
+ - const: cpas_vfe_lite
+ - const: cpas_vfe0
+ - const: cpas_vfe1
+ - const: csid
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy_rx
+ - const: gcc_axi_hf
+ - const: gcc_axi_sf
+ - const: icp_ahb
+ - const: vfe0
+ - const: vfe0_fast_ahb
+ - const: vfe1
+ - const: vfe1_fast_ahb
+ - const: vfe_lite
+ - const: vfe_lite_ahb
+ - const: vfe_lite_cphy_rx
+ - const: vfe_lite_csid
+
+ interrupts:
+ maxItems: 20
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csid_lite2
+ - const: csid_lite3
+ - const: csid_lite4
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: tpg0
+ - const: tpg1
+ - const: tpg2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+ - const: vfe_lite2
+ - const: vfe_lite3
+ - const: vfe_lite4
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_0
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: top
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ patternProperties:
+ "^port@[0-2]+$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 0-2.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,sa8775p-camcc.h>
+ #include <dt-bindings/clock/qcom,sa8775p-gcc.h>
+ #include <dt-bindings/interconnect/qcom,sa8775p-rpmh.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@ac78000 {
+ compatible = "qcom,qcs8300-camss";
+
+ reg = <0x0 0xac78000 0x0 0x1000>,
+ <0x0 0xac7a000 0x0 0x0f00>,
+ <0x0 0xac7c000 0x0 0x0f00>,
+ <0x0 0xac84000 0x0 0x0f00>,
+ <0x0 0xac88000 0x0 0x0f00>,
+ <0x0 0xac8c000 0x0 0x0f00>,
+ <0x0 0xac90000 0x0 0x0f00>,
+ <0x0 0xac94000 0x0 0x0f00>,
+ <0x0 0xac9c000 0x0 0x2000>,
+ <0x0 0xac9e000 0x0 0x2000>,
+ <0x0 0xaca0000 0x0 0x2000>,
+ <0x0 0xacac000 0x0 0x0400>,
+ <0x0 0xacad000 0x0 0x0400>,
+ <0x0 0xacae000 0x0 0x0400>,
+ <0x0 0xac4d000 0x0 0xd000>,
+ <0x0 0xac60000 0x0 0xd000>,
+ <0x0 0xac85000 0x0 0x0d00>,
+ <0x0 0xac89000 0x0 0x0d00>,
+ <0x0 0xac8d000 0x0 0x0d00>,
+ <0x0 0xac91000 0x0 0x0d00>,
+ <0x0 0xac95000 0x0 0x0d00>;
+ reg-names = "csid_wrapper",
+ "csid0",
+ "csid1",
+ "csid_lite0",
+ "csid_lite1",
+ "csid_lite2",
+ "csid_lite3",
+ "csid_lite4",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "tpg0",
+ "tpg1",
+ "tpg2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1",
+ "vfe_lite2",
+ "vfe_lite3",
+ "vfe_lite4";
+
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&camcc CAM_CC_CORE_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_FAST_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_LITE_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_0_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_1_CLK>,
+ <&camcc CAM_CC_CSID_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSID_CSIPHY_RX_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&gcc GCC_CAMERA_SF_AXI_CLK>,
+ <&camcc CAM_CC_ICP_AHB_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>;
+ clock-names = "camnoc_axi",
+ "core_ahb",
+ "cpas_ahb",
+ "cpas_fast_ahb_clk",
+ "cpas_vfe_lite",
+ "cpas_vfe0",
+ "cpas_vfe1",
+ "csid",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy_rx",
+ "gcc_axi_hf",
+ "gcc_axi_sf",
+ "icp_ahb",
+ "vfe0",
+ "vfe0_fast_ahb",
+ "vfe1",
+ "vfe1_fast_ahb",
+ "vfe_lite",
+ "vfe_lite_ahb",
+ "vfe_lite_cphy_rx",
+ "vfe_lite_csid";
+
+ interrupts = <GIC_SPI 565 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 564 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 359 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 759 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 758 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 604 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 545 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 546 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 547 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 360 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 761 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 760 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 605 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid_lite0",
+ "csid_lite1",
+ "csid_lite2",
+ "csid_lite3",
+ "csid_lite4",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "tpg0",
+ "tpg1",
+ "tpg2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1",
+ "vfe_lite2",
+ "vfe_lite3",
+ "vfe_lite4";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY
+ &config_noc SLAVE_CAMERA_CFG QCOM_ICC_TAG_ACTIVE_ONLY>,
+ <&mmss_noc MASTER_CAMNOC_HF QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+ interconnect-names = "ahb",
+ "hf_0";
+
+ iommus = <&apps_smmu 0x2400 0x20>;
+
+ power-domains = <&camcc CAM_CC_TITAN_TOP_GDSC>;
+ power-domain-names = "top";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sa8775p-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sa8775p-camss.yaml
new file mode 100644
index 000000000000..019caa2b09c3
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sa8775p-camss.yaml
@@ -0,0 +1,361 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sa8775p-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SA8775P CAMSS ISP
+
+maintainers:
+ - Vikram Sharma <quic_vikramsa@quicinc.com>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sa8775p-camss
+
+ reg:
+ maxItems: 22
+
+ reg-names:
+ items:
+ - const: csid_wrapper
+ - const: csid0
+ - const: csid1
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csid_lite2
+ - const: csid_lite3
+ - const: csid_lite4
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: tpg0
+ - const: tpg1
+ - const: tpg2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+ - const: vfe_lite2
+ - const: vfe_lite3
+ - const: vfe_lite4
+
+ clocks:
+ maxItems: 28
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: core_ahb
+ - const: cpas_ahb
+ - const: cpas_fast_ahb_clk
+ - const: cpas_vfe_lite
+ - const: cpas_vfe0
+ - const: cpas_vfe1
+ - const: csid
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy3
+ - const: csiphy3_timer
+ - const: csiphy_rx
+ - const: gcc_axi_hf
+ - const: gcc_axi_sf
+ - const: icp_ahb
+ - const: vfe0
+ - const: vfe0_fast_ahb
+ - const: vfe1
+ - const: vfe1_fast_ahb
+ - const: vfe_lite
+ - const: vfe_lite_ahb
+ - const: vfe_lite_cphy_rx
+ - const: vfe_lite_csid
+
+ interrupts:
+ maxItems: 21
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csid_lite2
+ - const: csid_lite3
+ - const: csid_lite4
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: tpg0
+ - const: tpg1
+ - const: tpg2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+ - const: vfe_lite2
+ - const: vfe_lite3
+ - const: vfe_lite4
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_0
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: top
+
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
+ description:
+ Phandle to 1.8V regulator supply to PHY refclk pll block.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ patternProperties:
+ "^port@[0-3]+$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 0-3.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - vdda-phy-supply
+ - vdda-pll-supply
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,sa8775p-camcc.h>
+ #include <dt-bindings/clock/qcom,sa8775p-gcc.h>
+ #include <dt-bindings/interconnect/qcom,sa8775p-rpmh.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@ac78000 {
+ compatible = "qcom,sa8775p-camss";
+
+ reg = <0x0 0xac78000 0x0 0x1000>,
+ <0x0 0xac7a000 0x0 0x0f00>,
+ <0x0 0xac7c000 0x0 0x0f00>,
+ <0x0 0xac84000 0x0 0x0f00>,
+ <0x0 0xac88000 0x0 0x0f00>,
+ <0x0 0xac8c000 0x0 0x0f00>,
+ <0x0 0xac90000 0x0 0x0f00>,
+ <0x0 0xac94000 0x0 0x0f00>,
+ <0x0 0xac9c000 0x0 0x2000>,
+ <0x0 0xac9e000 0x0 0x2000>,
+ <0x0 0xaca0000 0x0 0x2000>,
+ <0x0 0xaca2000 0x0 0x2000>,
+ <0x0 0xacac000 0x0 0x0400>,
+ <0x0 0xacad000 0x0 0x0400>,
+ <0x0 0xacae000 0x0 0x0400>,
+ <0x0 0xac4d000 0x0 0xd000>,
+ <0x0 0xac5a000 0x0 0xd000>,
+ <0x0 0xac85000 0x0 0x0d00>,
+ <0x0 0xac89000 0x0 0x0d00>,
+ <0x0 0xac8d000 0x0 0x0d00>,
+ <0x0 0xac91000 0x0 0x0d00>,
+ <0x0 0xac95000 0x0 0x0d00>;
+ reg-names = "csid_wrapper",
+ "csid0",
+ "csid1",
+ "csid_lite0",
+ "csid_lite1",
+ "csid_lite2",
+ "csid_lite3",
+ "csid_lite4",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "tpg0",
+ "tpg1",
+ "tpg2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1",
+ "vfe_lite2",
+ "vfe_lite3",
+ "vfe_lite4";
+
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&camcc CAM_CC_CORE_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_FAST_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_LITE_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_0_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_1_CLK>,
+ <&camcc CAM_CC_CSID_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY3_CLK>,
+ <&camcc CAM_CC_CSI3PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSID_CSIPHY_RX_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&gcc GCC_CAMERA_SF_AXI_CLK>,
+ <&camcc CAM_CC_ICP_AHB_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>;
+ clock-names = "camnoc_axi",
+ "core_ahb",
+ "cpas_ahb",
+ "cpas_fast_ahb_clk",
+ "cpas_vfe_lite",
+ "cpas_vfe0",
+ "cpas_vfe1",
+ "csid",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy3",
+ "csiphy3_timer",
+ "csiphy_rx",
+ "gcc_axi_hf",
+ "gcc_axi_sf",
+ "icp_ahb",
+ "vfe0",
+ "vfe0_fast_ahb",
+ "vfe1",
+ "vfe1_fast_ahb",
+ "vfe_lite",
+ "vfe_lite_ahb",
+ "vfe_lite_cphy_rx",
+ "vfe_lite_csid";
+
+ interrupts = <GIC_SPI 565 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 564 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 359 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 759 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 758 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 604 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 545 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 546 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 547 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 360 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 761 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 760 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 605 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid_lite0",
+ "csid_lite1",
+ "csid_lite2",
+ "csid_lite3",
+ "csid_lite4",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "tpg0",
+ "tpg1",
+ "tpg2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1",
+ "vfe_lite2",
+ "vfe_lite3",
+ "vfe_lite4";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY
+ &config_noc SLAVE_CAMERA_CFG QCOM_ICC_TAG_ACTIVE_ONLY>,
+ <&mmss_noc MASTER_CAMNOC_HF QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+ interconnect-names = "ahb",
+ "hf_0";
+
+ iommus = <&apps_smmu 0x3400 0x20>;
+
+ power-domains = <&camcc CAM_CC_TITAN_TOP_GDSC>;
+ power-domain-names = "top";
+
+ vdda-phy-supply = <&vreg_l4a_0p88>;
+ vdda-pll-supply = <&vreg_l1c_1p2>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sc7180-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sc7180-venus.yaml
index 90b4af2c9724..bfd8b1ad4731 100644
--- a/Documentation/devicetree/bindings/media/qcom,sc7180-venus.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,sc7180-venus.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,sc7180-venus.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,sc7180-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm Venus video encode and decode accelerators
+title: Qualcomm SC7180 Venus video encode and decode accelerators
maintainers:
- Stanimir Varbanov <stanimir.varbanov@linaro.org>
@@ -14,15 +13,17 @@ description: |
The Venus IP is a video encode and decode accelerator present
on Qualcomm platforms
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
properties:
compatible:
- const: qcom,sc7180-venus
-
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
+ oneOf:
+ - items:
+ - enum:
+ - qcom,qcs615-venus
+ - const: qcom,sc7180-venus
+ - const: qcom,sc7180-venus
power-domains:
minItems: 2
@@ -60,6 +61,10 @@ properties:
- const: video-mem
- const: cpu-cfg
+ operating-points-v2: true
+ opp-table:
+ type: object
+
video-decoder:
type: object
@@ -70,6 +75,7 @@ properties:
required:
- compatible
+ deprecated: true
additionalProperties: false
video-encoder:
@@ -82,64 +88,35 @@ properties:
required:
- compatible
+ deprecated: true
additionalProperties: false
- video-firmware:
- type: object
-
- description: |
- Firmware subnode is needed when the platform does not
- have TrustZone.
-
- properties:
- iommus:
- maxItems: 1
-
- required:
- - iommus
-
required:
- compatible
- - reg
- - interrupts
- - power-domains
- power-domain-names
- - clocks
- - clock-names
- iommus
- - memory-region
- - video-decoder
- - video-encoder
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/qcom,videocc-sc7180.h>
-
- venus: video-codec@aa00000 {
- compatible = "qcom,sc7180-venus";
- reg = <0x0aa00000 0xff000>;
- interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
- power-domains = <&videocc VENUS_GDSC>,
- <&videocc VCODEC0_GDSC>;
- power-domain-names = "venus", "vcodec0";
- clocks = <&videocc VIDEO_CC_VENUS_CTL_CORE_CLK>,
- <&videocc VIDEO_CC_VENUS_AHB_CLK>,
- <&videocc VIDEO_CC_VENUS_CTL_AXI_CLK>,
- <&videocc VIDEO_CC_VCODEC0_CORE_CLK>,
- <&videocc VIDEO_CC_VCODEC0_AXI_CLK>;
- clock-names = "core", "iface", "bus",
- "vcodec0_core", "vcodec0_bus";
- iommus = <&apps_smmu 0x0c00 0x60>;
- memory-region = <&venus_mem>;
-
- video-decoder {
- compatible = "venus-decoder";
- };
-
- video-encoder {
- compatible = "venus-encoder";
- };
- };
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,videocc-sc7180.h>
+
+ venus: video-codec@aa00000 {
+ compatible = "qcom,sc7180-venus";
+ reg = <0x0aa00000 0xff000>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&videocc VENUS_GDSC>,
+ <&videocc VCODEC0_GDSC>;
+ power-domain-names = "venus", "vcodec0";
+ clocks = <&videocc VIDEO_CC_VENUS_CTL_CORE_CLK>,
+ <&videocc VIDEO_CC_VENUS_AHB_CLK>,
+ <&videocc VIDEO_CC_VENUS_CTL_AXI_CLK>,
+ <&videocc VIDEO_CC_VCODEC0_CORE_CLK>,
+ <&videocc VIDEO_CC_VCODEC0_AXI_CLK>;
+ clock-names = "core", "iface", "bus",
+ "vcodec0_core", "vcodec0_bus";
+ iommus = <&apps_smmu 0x0c00 0x60>;
+ memory-region = <&venus_mem>;
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sc7280-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sc7280-camss.yaml
new file mode 100644
index 000000000000..ee35e3bc97ff
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sc7280-camss.yaml
@@ -0,0 +1,425 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sc7280-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SC7280 CAMSS ISP
+
+maintainers:
+ - Azam Sadiq Pasha Kapatrala Syed <akapatra@quicinc.com>
+ - Hariram Purushothaman <hariramp@quicinc.com>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sc7280-camss
+
+ reg:
+ maxItems: 15
+
+ reg-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: vfe0
+ - const: vfe1
+ - const: vfe2
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ clocks:
+ maxItems: 33
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: cpas_ahb
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy3
+ - const: csiphy3_timer
+ - const: csiphy4
+ - const: csiphy4_timer
+ - const: gcc_axi_hf
+ - const: gcc_axi_sf
+ - const: icp_ahb
+ - const: vfe0
+ - const: vfe0_axi
+ - const: vfe0_cphy_rx
+ - const: vfe0_csid
+ - const: vfe1
+ - const: vfe1_axi
+ - const: vfe1_cphy_rx
+ - const: vfe1_csid
+ - const: vfe2
+ - const: vfe2_axi
+ - const: vfe2_cphy_rx
+ - const: vfe2_csid
+ - const: vfe_lite0
+ - const: vfe_lite0_cphy_rx
+ - const: vfe_lite0_csid
+ - const: vfe_lite1
+ - const: vfe_lite1_cphy_rx
+ - const: vfe_lite1_csid
+
+ interrupts:
+ maxItems: 15
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: vfe0
+ - const: vfe1
+ - const: vfe2
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_0
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE2 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: ife0
+ - const: ife1
+ - const: ife2
+ - const: top
+
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
+ description:
+ Phandle to 1.8V regulator supply to PHY refclk pll block.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 0.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 1.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 2.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ port@3:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 3.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+ port@4:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSIPHY 4.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - vdda-phy-supply
+ - vdda-pll-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,camcc-sc7280.h>
+ #include <dt-bindings/clock/qcom,gcc-sc7280.h>
+ #include <dt-bindings/interconnect/qcom,sc7280.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@acb3000 {
+ compatible = "qcom,sc7280-camss";
+
+ reg = <0x0 0x0acb3000 0x0 0x1000>,
+ <0x0 0x0acba000 0x0 0x1000>,
+ <0x0 0x0acc1000 0x0 0x1000>,
+ <0x0 0x0acc8000 0x0 0x1000>,
+ <0x0 0x0accf000 0x0 0x1000>,
+ <0x0 0x0ace0000 0x0 0x2000>,
+ <0x0 0x0ace2000 0x0 0x2000>,
+ <0x0 0x0ace4000 0x0 0x2000>,
+ <0x0 0x0ace6000 0x0 0x2000>,
+ <0x0 0x0ace8000 0x0 0x2000>,
+ <0x0 0x0acaf000 0x0 0x4000>,
+ <0x0 0x0acb6000 0x0 0x4000>,
+ <0x0 0x0acbd000 0x0 0x4000>,
+ <0x0 0x0acc4000 0x0 0x4000>,
+ <0x0 0x0accb000 0x0 0x4000>;
+ reg-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "vfe0",
+ "vfe1",
+ "vfe2",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY3_CLK>,
+ <&camcc CAM_CC_CSI3PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY4_CLK>,
+ <&camcc CAM_CC_CSI4PHYTIMER_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&gcc GCC_CAMERA_SF_AXI_CLK>,
+ <&camcc CAM_CC_ICP_AHB_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_AXI_CLK>,
+ <&camcc CAM_CC_IFE_0_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_0_CSID_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_AXI_CLK>,
+ <&camcc CAM_CC_IFE_1_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_1_CSID_CLK>,
+ <&camcc CAM_CC_IFE_2_CLK>,
+ <&camcc CAM_CC_IFE_2_AXI_CLK>,
+ <&camcc CAM_CC_IFE_2_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_2_CSID_CLK>,
+ <&camcc CAM_CC_IFE_LITE_0_CLK>,
+ <&camcc CAM_CC_IFE_LITE_0_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_0_CSID_CLK>,
+ <&camcc CAM_CC_IFE_LITE_1_CLK>,
+ <&camcc CAM_CC_IFE_LITE_1_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_1_CSID_CLK>;
+ clock-names = "camnoc_axi",
+ "cpas_ahb",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy3",
+ "csiphy3_timer",
+ "csiphy4",
+ "csiphy4_timer",
+ "gcc_axi_hf",
+ "gcc_axi_sf",
+ "icp_ahb",
+ "vfe0",
+ "vfe0_axi",
+ "vfe0_cphy_rx",
+ "vfe0_csid",
+ "vfe1",
+ "vfe1_axi",
+ "vfe1_cphy_rx",
+ "vfe1_csid",
+ "vfe2",
+ "vfe2_axi",
+ "vfe2_cphy_rx",
+ "vfe2_csid",
+ "vfe_lite0",
+ "vfe_lite0_cphy_rx",
+ "vfe_lite0_csid",
+ "vfe_lite1",
+ "vfe_lite1_cphy_rx",
+ "vfe_lite1_csid";
+
+ interrupts = <GIC_SPI 464 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 466 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 640 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 359 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 122 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 641 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 360 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "vfe0",
+ "vfe1",
+ "vfe2",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY
+ &cnoc2 SLAVE_CAMERA_CFG QCOM_ICC_TAG_ACTIVE_ONLY>,
+ <&mmss_noc MASTER_CAMNOC_HF QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+ interconnect-names = "ahb",
+ "hf_0";
+
+ iommus = <&apps_smmu 0x800 0x4e0>;
+
+ power-domains = <&camcc CAM_CC_IFE_0_GDSC>,
+ <&camcc CAM_CC_IFE_1_GDSC>,
+ <&camcc CAM_CC_IFE_2_GDSC>,
+ <&camcc CAM_CC_TITAN_TOP_GDSC>;
+ power-domain-names = "ife0",
+ "ife1",
+ "ife2",
+ "top";
+
+ vdda-phy-supply = <&vreg_l10c_0p88>;
+ vdda-pll-supply = <&vreg_l6b_1p2>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sc7280-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sc7280-venus.yaml
new file mode 100644
index 000000000000..413c5b4ee650
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sc7280-venus.yaml
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sc7280-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SC7280 Venus video encode and decode accelerators
+
+maintainers:
+ - Stanimir Varbanov <stanimir.varbanov@linaro.org>
+
+description: |
+ The Venus Iris2 IP is a video encode and decode accelerator present
+ on Qualcomm platforms
+
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
+properties:
+ compatible:
+ const: qcom,sc7280-venus
+
+ power-domains:
+ minItems: 2
+ maxItems: 3
+
+ power-domain-names:
+ minItems: 2
+ items:
+ - const: venus
+ - const: vcodec0
+ - const: cx
+
+ clocks:
+ maxItems: 5
+
+ clock-names:
+ items:
+ - const: core
+ - const: bus
+ - const: iface
+ - const: vcodec_core
+ - const: vcodec_bus
+
+ iommus:
+ minItems: 1
+ maxItems: 2
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: cpu-cfg
+ - const: video-mem
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+ video-decoder:
+ type: object
+
+ properties:
+ compatible:
+ const: venus-decoder
+
+ required:
+ - compatible
+
+ deprecated: true
+ additionalProperties: false
+
+ video-encoder:
+ type: object
+
+ properties:
+ compatible:
+ const: venus-encoder
+
+ required:
+ - compatible
+
+ deprecated: true
+ additionalProperties: false
+
+required:
+ - compatible
+ - power-domain-names
+ - iommus
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,videocc-sc7280.h>
+ #include <dt-bindings/interconnect/qcom,sc7280.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ venus: video-codec@aa00000 {
+ compatible = "qcom,sc7280-venus";
+ reg = <0x0aa00000 0xd0600>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+
+ clocks = <&videocc VIDEO_CC_MVSC_CORE_CLK>,
+ <&videocc VIDEO_CC_MVSC_CTL_AXI_CLK>,
+ <&videocc VIDEO_CC_VENUS_AHB_CLK>,
+ <&videocc VIDEO_CC_MVS0_CORE_CLK>,
+ <&videocc VIDEO_CC_MVS0_AXI_CLK>;
+ clock-names = "core", "bus", "iface",
+ "vcodec_core", "vcodec_bus";
+
+ power-domains = <&videocc MVSC_GDSC>,
+ <&videocc MVS0_GDSC>,
+ <&rpmhpd SC7280_CX>;
+ power-domain-names = "venus", "vcodec0", "cx";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC 0 &cnoc2 SLAVE_VENUS_CFG 0>,
+ <&mmss_noc MASTER_VIDEO_P0 0 &mc_virt SLAVE_EBI1 0>;
+ interconnect-names = "cpu-cfg", "video-mem";
+
+ iommus = <&apps_smmu 0x2180 0x20>,
+ <&apps_smmu 0x2184 0x20>;
+
+ memory-region = <&video_mem>;
+
+ video-firmware {
+ iommus = <&apps_smmu 0x21a2 0x0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sc8280xp-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sc8280xp-camss.yaml
new file mode 100644
index 000000000000..c99fe4106eee
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sc8280xp-camss.yaml
@@ -0,0 +1,531 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sc8280xp-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SC8280XP Camera Subsystem (CAMSS)
+
+maintainers:
+ - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
+
+description: |
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sc8280xp-camss
+
+ clocks:
+ maxItems: 40
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: cpas_ahb
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy3
+ - const: csiphy3_timer
+ - const: vfe0_axi
+ - const: vfe0
+ - const: vfe0_cphy_rx
+ - const: vfe0_csid
+ - const: vfe1_axi
+ - const: vfe1
+ - const: vfe1_cphy_rx
+ - const: vfe1_csid
+ - const: vfe2_axi
+ - const: vfe2
+ - const: vfe2_cphy_rx
+ - const: vfe2_csid
+ - const: vfe3_axi
+ - const: vfe3
+ - const: vfe3_cphy_rx
+ - const: vfe3_csid
+ - const: vfe_lite0
+ - const: vfe_lite0_cphy_rx
+ - const: vfe_lite0_csid
+ - const: vfe_lite1
+ - const: vfe_lite1_cphy_rx
+ - const: vfe_lite1_csid
+ - const: vfe_lite2
+ - const: vfe_lite2_cphy_rx
+ - const: vfe_lite2_csid
+ - const: vfe_lite3
+ - const: vfe_lite3_cphy_rx
+ - const: vfe_lite3_csid
+ - const: gcc_axi_hf
+ - const: gcc_axi_sf
+
+ interrupts:
+ maxItems: 20
+
+ interrupt-names:
+ items:
+ - const: csid1_lite
+ - const: vfe_lite1
+ - const: csiphy3
+ - const: csid0
+ - const: vfe0
+ - const: csid1
+ - const: vfe1
+ - const: csid0_lite
+ - const: vfe_lite0
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csid2
+ - const: vfe2
+ - const: csid3_lite
+ - const: csid2_lite
+ - const: vfe_lite3
+ - const: vfe_lite2
+ - const: csid3
+ - const: vfe3
+
+ iommus:
+ maxItems: 16
+
+ interconnects:
+ maxItems: 4
+
+ interconnect-names:
+ items:
+ - const: cam_ahb
+ - const: cam_hf_mnoc
+ - const: cam_sf_mnoc
+ - const: cam_sf_icp_mnoc
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE2 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE3 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan Top GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: ife0
+ - const: ife1
+ - const: ife2
+ - const: ife3
+ - const: top
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY0.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY1.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY2.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@3:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY3.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ reg:
+ maxItems: 20
+
+ reg-names:
+ items:
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy0
+ - const: csiphy1
+ - const: vfe0
+ - const: csid0
+ - const: vfe1
+ - const: csid1
+ - const: vfe2
+ - const: csid2
+ - const: vfe_lite0
+ - const: csid0_lite
+ - const: vfe_lite1
+ - const: csid1_lite
+ - const: vfe_lite2
+ - const: csid2_lite
+ - const: vfe_lite3
+ - const: csid3_lite
+ - const: vfe3
+ - const: csid3
+
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
+ description:
+ Phandle to 1.8V regulator supply to PHY refclk pll block.
+
+required:
+ - clock-names
+ - clocks
+ - compatible
+ - interconnects
+ - interconnect-names
+ - interrupts
+ - interrupt-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - reg
+ - reg-names
+ - vdda-phy-supply
+ - vdda-pll-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,gcc-sc8280xp.h>
+ #include <dt-bindings/clock/qcom,sc8280xp-camcc.h>
+ #include <dt-bindings/interconnect/qcom,sc8280xp.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ camss: camss@ac5a000 {
+ compatible = "qcom,sc8280xp-camss";
+
+ reg = <0 0x0ac5a000 0 0x2000>,
+ <0 0x0ac5c000 0 0x2000>,
+ <0 0x0ac65000 0 0x2000>,
+ <0 0x0ac67000 0 0x2000>,
+ <0 0x0acaf000 0 0x4000>,
+ <0 0x0acb3000 0 0x1000>,
+ <0 0x0acb6000 0 0x4000>,
+ <0 0x0acba000 0 0x1000>,
+ <0 0x0acbd000 0 0x4000>,
+ <0 0x0acc1000 0 0x1000>,
+ <0 0x0acc4000 0 0x4000>,
+ <0 0x0acc8000 0 0x1000>,
+ <0 0x0accb000 0 0x4000>,
+ <0 0x0accf000 0 0x1000>,
+ <0 0x0acd2000 0 0x4000>,
+ <0 0x0acd6000 0 0x1000>,
+ <0 0x0acd9000 0 0x4000>,
+ <0 0x0acdd000 0 0x1000>,
+ <0 0x0ace0000 0 0x4000>,
+ <0 0x0ace4000 0 0x1000>;
+
+ reg-names = "csiphy2",
+ "csiphy3",
+ "csiphy0",
+ "csiphy1",
+ "vfe0",
+ "csid0",
+ "vfe1",
+ "csid1",
+ "vfe2",
+ "csid2",
+ "vfe_lite0",
+ "csid0_lite",
+ "vfe_lite1",
+ "csid1_lite",
+ "vfe_lite2",
+ "csid2_lite",
+ "vfe_lite3",
+ "csid3_lite",
+ "vfe3",
+ "csid3";
+
+ vdda-phy-supply = <&vreg_l6d>;
+ vdda-pll-supply = <&vreg_l4d>;
+
+ interrupts = <GIC_SPI 359 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 360 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 464 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 466 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 640 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 641 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 758 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 759 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 760 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 761 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 762 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 764 IRQ_TYPE_EDGE_RISING>;
+
+ interrupt-names = "csid1_lite",
+ "vfe_lite1",
+ "csiphy3",
+ "csid0",
+ "vfe0",
+ "csid1",
+ "vfe1",
+ "csid0_lite",
+ "vfe_lite0",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csid2",
+ "vfe2",
+ "csid3_lite",
+ "csid2_lite",
+ "vfe_lite3",
+ "vfe_lite2",
+ "csid3",
+ "vfe3";
+
+ power-domains = <&camcc IFE_0_GDSC>,
+ <&camcc IFE_1_GDSC>,
+ <&camcc IFE_2_GDSC>,
+ <&camcc IFE_3_GDSC>,
+ <&camcc TITAN_TOP_GDSC>;
+
+ power-domain-names = "ife0",
+ "ife1",
+ "ife2",
+ "ife3",
+ "top";
+
+ clocks = <&camcc CAMCC_CAMNOC_AXI_CLK>,
+ <&camcc CAMCC_CPAS_AHB_CLK>,
+ <&camcc CAMCC_CSIPHY0_CLK>,
+ <&camcc CAMCC_CSI0PHYTIMER_CLK>,
+ <&camcc CAMCC_CSIPHY1_CLK>,
+ <&camcc CAMCC_CSI1PHYTIMER_CLK>,
+ <&camcc CAMCC_CSIPHY2_CLK>,
+ <&camcc CAMCC_CSI2PHYTIMER_CLK>,
+ <&camcc CAMCC_CSIPHY3_CLK>,
+ <&camcc CAMCC_CSI3PHYTIMER_CLK>,
+ <&camcc CAMCC_IFE_0_AXI_CLK>,
+ <&camcc CAMCC_IFE_0_CLK>,
+ <&camcc CAMCC_IFE_0_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_0_CSID_CLK>,
+ <&camcc CAMCC_IFE_1_AXI_CLK>,
+ <&camcc CAMCC_IFE_1_CLK>,
+ <&camcc CAMCC_IFE_1_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_1_CSID_CLK>,
+ <&camcc CAMCC_IFE_2_AXI_CLK>,
+ <&camcc CAMCC_IFE_2_CLK>,
+ <&camcc CAMCC_IFE_2_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_2_CSID_CLK>,
+ <&camcc CAMCC_IFE_3_AXI_CLK>,
+ <&camcc CAMCC_IFE_3_CLK>,
+ <&camcc CAMCC_IFE_3_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_3_CSID_CLK>,
+ <&camcc CAMCC_IFE_LITE_0_CLK>,
+ <&camcc CAMCC_IFE_LITE_0_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_LITE_0_CSID_CLK>,
+ <&camcc CAMCC_IFE_LITE_1_CLK>,
+ <&camcc CAMCC_IFE_LITE_1_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_LITE_1_CSID_CLK>,
+ <&camcc CAMCC_IFE_LITE_2_CLK>,
+ <&camcc CAMCC_IFE_LITE_2_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_LITE_2_CSID_CLK>,
+ <&camcc CAMCC_IFE_LITE_3_CLK>,
+ <&camcc CAMCC_IFE_LITE_3_CPHY_RX_CLK>,
+ <&camcc CAMCC_IFE_LITE_3_CSID_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&gcc GCC_CAMERA_SF_AXI_CLK>;
+
+ clock-names = "camnoc_axi",
+ "cpas_ahb",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy3",
+ "csiphy3_timer",
+ "vfe0_axi",
+ "vfe0",
+ "vfe0_cphy_rx",
+ "vfe0_csid",
+ "vfe1_axi",
+ "vfe1",
+ "vfe1_cphy_rx",
+ "vfe1_csid",
+ "vfe2_axi",
+ "vfe2",
+ "vfe2_cphy_rx",
+ "vfe2_csid",
+ "vfe3_axi",
+ "vfe3",
+ "vfe3_cphy_rx",
+ "vfe3_csid",
+ "vfe_lite0",
+ "vfe_lite0_cphy_rx",
+ "vfe_lite0_csid",
+ "vfe_lite1",
+ "vfe_lite1_cphy_rx",
+ "vfe_lite1_csid",
+ "vfe_lite2",
+ "vfe_lite2_cphy_rx",
+ "vfe_lite2_csid",
+ "vfe_lite3",
+ "vfe_lite3_cphy_rx",
+ "vfe_lite3_csid",
+ "gcc_axi_hf",
+ "gcc_axi_sf";
+
+ iommus = <&apps_smmu 0x2000 0x4e0>,
+ <&apps_smmu 0x2020 0x4e0>,
+ <&apps_smmu 0x2040 0x4e0>,
+ <&apps_smmu 0x2060 0x4e0>,
+ <&apps_smmu 0x2080 0x4e0>,
+ <&apps_smmu 0x20e0 0x4e0>,
+ <&apps_smmu 0x20c0 0x4e0>,
+ <&apps_smmu 0x20a0 0x4e0>,
+ <&apps_smmu 0x2400 0x4e0>,
+ <&apps_smmu 0x2420 0x4e0>,
+ <&apps_smmu 0x2440 0x4e0>,
+ <&apps_smmu 0x2460 0x4e0>,
+ <&apps_smmu 0x2480 0x4e0>,
+ <&apps_smmu 0x24e0 0x4e0>,
+ <&apps_smmu 0x24c0 0x4e0>,
+ <&apps_smmu 0x24a0 0x4e0>;
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_CAMERA_CFG 0>,
+ <&mmss_noc MASTER_CAMNOC_HF 0 &mc_virt SLAVE_EBI1 0>,
+ <&mmss_noc MASTER_CAMNOC_SF 0 &mc_virt SLAVE_EBI1 0>,
+ <&mmss_noc MASTER_CAMNOC_ICP 0 &mc_virt SLAVE_EBI1 0>;
+ interconnect-names = "cam_ahb",
+ "cam_hf_mnoc",
+ "cam_sf_mnoc",
+ "cam_sf_icp_mnoc";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ csiphy_ep0: endpoint@0 {
+ reg = <0>;
+ clock-lanes = <7>;
+ data-lanes = <0 1>;
+ remote-endpoint = <&sensor_ep>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml
index 841a1aafdd13..6e6ad8390e44 100644
--- a/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,sdm660-camss.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,sdm660-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm CAMSS ISP
@@ -84,6 +83,13 @@ properties:
- const: vfe0
- const: vfe1
+ interconnects:
+ maxItems: 1
+
+ interconnect-names:
+ items:
+ - const: vfe-mem
+
iommus:
maxItems: 4
@@ -111,16 +117,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@1:
@@ -135,16 +141,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@2:
@@ -159,16 +165,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@3:
@@ -183,16 +189,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
reg:
@@ -240,7 +246,7 @@ examples:
#include <dt-bindings/clock/qcom,gcc-sdm660.h>
#include <dt-bindings/clock/qcom,mmcc-sdm660.h>
- camss: camss@ca00000 {
+ camss: camss@ca00020 {
compatible = "qcom,sdm660-camss";
clocks = <&mmcc CAMSS_AHB_CLK>,
diff --git a/Documentation/devicetree/bindings/media/qcom,sdm660-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sdm660-venus.yaml
new file mode 100644
index 000000000000..a51835b22045
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sdm660-venus.yaml
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sdm660-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SDM660 Venus video encode and decode accelerators
+
+maintainers:
+ - Stanimir Varbanov <stanimir.varbanov@linaro.org>
+ - AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
+
+description: |
+ The Venus IP is a video encode and decode accelerator present
+ on Qualcomm platforms
+
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
+properties:
+ compatible:
+ const: qcom,sdm660-venus
+
+ clocks:
+ maxItems: 4
+
+ clock-names:
+ items:
+ - const: core
+ - const: iface
+ - const: bus
+ - const: bus_throttle
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: cpu-cfg
+ - const: video-mem
+
+ iommus:
+ maxItems: 20
+
+ power-domains:
+ maxItems: 1
+
+ video-decoder:
+ type: object
+
+ properties:
+ compatible:
+ const: venus-decoder
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: vcodec0_core
+
+ power-domains:
+ maxItems: 1
+
+ required:
+ - compatible
+ - clocks
+ - clock-names
+ - power-domains
+
+ additionalProperties: false
+
+ video-encoder:
+ type: object
+
+ properties:
+ compatible:
+ const: venus-encoder
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: vcodec0_core
+
+ power-domains:
+ maxItems: 1
+
+ required:
+ - compatible
+ - clocks
+ - clock-names
+ - power-domains
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - iommus
+ - video-decoder
+ - video-encoder
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,mmcc-sdm660.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ video-codec@cc00000 {
+ compatible = "qcom,sdm660-venus";
+ reg = <0x0cc00000 0xff000>;
+ clocks = <&mmcc VIDEO_CORE_CLK>,
+ <&mmcc VIDEO_AHB_CLK>,
+ <&mmcc VIDEO_AXI_CLK>,
+ <&mmcc THROTTLE_VIDEO_AXI_CLK>;
+ clock-names = "core", "iface", "bus", "bus_throttle";
+ interconnects = <&gnoc 0 &mnoc 13>,
+ <&mnoc 4 &bimc 5>;
+ interconnect-names = "cpu-cfg", "video-mem";
+ interrupts = <GIC_SPI 287 IRQ_TYPE_LEVEL_HIGH>;
+ iommus = <&mmss_smmu 0x400>,
+ <&mmss_smmu 0x401>,
+ <&mmss_smmu 0x40a>,
+ <&mmss_smmu 0x407>,
+ <&mmss_smmu 0x40e>,
+ <&mmss_smmu 0x40f>,
+ <&mmss_smmu 0x408>,
+ <&mmss_smmu 0x409>,
+ <&mmss_smmu 0x40b>,
+ <&mmss_smmu 0x40c>,
+ <&mmss_smmu 0x40d>,
+ <&mmss_smmu 0x410>,
+ <&mmss_smmu 0x421>,
+ <&mmss_smmu 0x428>,
+ <&mmss_smmu 0x429>,
+ <&mmss_smmu 0x42b>,
+ <&mmss_smmu 0x42c>,
+ <&mmss_smmu 0x42d>,
+ <&mmss_smmu 0x411>,
+ <&mmss_smmu 0x431>;
+ memory-region = <&venus_region>;
+ power-domains = <&mmcc VENUS_GDSC>;
+
+ video-decoder {
+ compatible = "venus-decoder";
+ clocks = <&mmcc VIDEO_SUBCORE0_CLK>;
+ clock-names = "vcodec0_core";
+ power-domains = <&mmcc VENUS_CORE0_GDSC>;
+ };
+
+ video-encoder {
+ compatible = "venus-encoder";
+ clocks = <&mmcc VIDEO_SUBCORE0_CLK>;
+ clock-names = "vcodec0_core";
+ power-domains = <&mmcc VENUS_CORE0_GDSC>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sdm670-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm670-camss.yaml
new file mode 100644
index 000000000000..35c40fe22376
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sdm670-camss.yaml
@@ -0,0 +1,318 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sdm670-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SDM670 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Richard Acayan <mailingradian@gmail.com>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sdm670-camss
+
+ reg:
+ maxItems: 9
+
+ reg-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite
+
+ interrupts:
+ maxItems: 9
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite
+
+ clocks:
+ maxItems: 22
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: cpas_ahb
+ - const: csi0
+ - const: csi1
+ - const: csi2
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: gcc_camera_ahb
+ - const: gcc_camera_axi
+ - const: soc_ahb
+ - const: vfe0
+ - const: vfe0_axi
+ - const: vfe0_cphy_rx
+ - const: vfe1
+ - const: vfe1_axi
+ - const: vfe1_cphy_rx
+ - const: vfe_lite
+ - const: vfe_lite_cphy_rx
+
+ iommus:
+ maxItems: 4
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan Top GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: ife0
+ - const: ife1
+ - const: top
+
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
+ description:
+ Phandle to 1.8V regulator supply to PHY refclk pll block.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY0.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY1.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data from CSIPHY2.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - vdda-phy-supply
+ - vdda-pll-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,camcc-sdm845.h>
+ #include <dt-bindings/clock/qcom,gcc-sdm845.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@acb3000 {
+ compatible = "qcom,sdm670-camss";
+
+ reg = <0 0x0acb3000 0 0x1000>,
+ <0 0x0acba000 0 0x1000>,
+ <0 0x0acc8000 0 0x1000>,
+ <0 0x0ac65000 0 0x1000>,
+ <0 0x0ac66000 0 0x1000>,
+ <0 0x0ac67000 0 0x1000>,
+ <0 0x0acaf000 0 0x4000>,
+ <0 0x0acb6000 0 0x4000>,
+ <0 0x0acc4000 0 0x4000>;
+ reg-names = "csid0",
+ "csid1",
+ "csid2",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite";
+
+ interrupts = <GIC_SPI 464 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 466 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid2",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite";
+
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_IFE_0_CSID_CLK>,
+ <&camcc CAM_CC_IFE_1_CSID_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&gcc GCC_CAMERA_AHB_CLK>,
+ <&gcc GCC_CAMERA_AXI_CLK>,
+ <&camcc CAM_CC_SOC_AHB_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_AXI_CLK>,
+ <&camcc CAM_CC_IFE_0_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_AXI_CLK>,
+ <&camcc CAM_CC_IFE_1_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>;
+ clock-names = "camnoc_axi",
+ "cpas_ahb",
+ "csi0",
+ "csi1",
+ "csi2",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "gcc_camera_ahb",
+ "gcc_camera_axi",
+ "soc_ahb",
+ "vfe0",
+ "vfe0_axi",
+ "vfe0_cphy_rx",
+ "vfe1",
+ "vfe1_axi",
+ "vfe1_cphy_rx",
+ "vfe_lite",
+ "vfe_lite_cphy_rx";
+
+ iommus = <&apps_smmu 0x808 0x0>,
+ <&apps_smmu 0x810 0x8>,
+ <&apps_smmu 0xc08 0x0>,
+ <&apps_smmu 0xc10 0x8>;
+
+ power-domains = <&camcc IFE_0_GDSC>,
+ <&camcc IFE_1_GDSC>,
+ <&camcc TITAN_TOP_GDSC>;
+ power-domain-names = "ife0",
+ "ife1",
+ "top";
+
+ vdda-phy-supply = <&vreg_l1a_1p225>;
+ vdda-pll-supply = <&vreg_l8a_1p8>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ csiphy_ep0: endpoint {
+ clock-lanes = <7>;
+ data-lanes = <0 1 2 3>;
+ remote-endpoint = <&front_sensor_ep>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml
index 9ca5dfa7f226..82bf4689d330 100644
--- a/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,sdm845-camss.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,sdm845-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm CAMSS ISP
@@ -105,15 +104,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- maxItems: 1
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@1:
@@ -128,16 +128,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- items:
- - const: 7
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@2:
@@ -152,15 +152,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- maxItems: 1
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
port@3:
@@ -175,15 +176,16 @@ properties:
unevaluatedProperties: false
properties:
- clock-lanes:
- maxItems: 1
-
data-lanes:
minItems: 1
maxItems: 4
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
required:
- - clock-lanes
- data-lanes
reg:
@@ -203,9 +205,13 @@ properties:
- const: vfe1
- const: vfe_lite
- vdda-supply:
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
description:
- Definition of the regulator used as analog power supply.
+ Phandle to 1.8V regulator supply to PHY refclk pll block.
required:
- clock-names
@@ -217,7 +223,8 @@ required:
- power-domains
- reg
- reg-names
- - vdda-supply
+ - vdda-phy-supply
+ - vdda-pll-supply
additionalProperties: false
@@ -231,7 +238,7 @@ examples:
#address-cells = <2>;
#size-cells = <2>;
- camss: camss@a00000 {
+ camss: camss@acb3000 {
compatible = "qcom,sdm845-camss";
clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>,
@@ -308,16 +315,16 @@ examples:
"vfe_lite_cphy_rx",
"vfe_lite_src";
- interrupts = <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 477 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 478 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 479 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>;
+ interrupts = <GIC_SPI 464 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 466 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>;
interrupt-names = "csid0",
"csid1",
@@ -361,7 +368,8 @@ examples:
"vfe1",
"vfe_lite";
- vdda-supply = <&reg_2v8>;
+ vdda-phy-supply = <&vreg_l1a_0p875>;
+ vdda-pll-supply = <&vreg_l26a_1p2>;
ports {
#address-cells = <1>;
diff --git a/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml b/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml
index 177bf81544b1..c839cb1ebc09 100644
--- a/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,sdm845-venus-v2.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,sdm845-venus-v2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm Venus video encode and decode accelerators
+title: Qualcomm SDM845 Venus v2 video encode and decode accelerators
maintainers:
- Stanimir Varbanov <stanimir.varbanov@linaro.org>
@@ -14,16 +13,13 @@ description: |
The Venus IP is a video encode and decode accelerator present
on Qualcomm platforms
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
properties:
compatible:
const: qcom,sdm845-venus-v2
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
power-domains:
minItems: 3
maxItems: 4
@@ -52,8 +48,17 @@ properties:
iommus:
maxItems: 2
- memory-region:
- maxItems: 1
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: video-mem
+ - const: cpu-cfg
+
+ operating-points-v2: true
+ opp-table:
+ type: object
video-core0:
type: object
@@ -65,6 +70,7 @@ properties:
required:
- compatible
+ deprecated: true
additionalProperties: false
video-core1:
@@ -77,69 +83,40 @@ properties:
required:
- compatible
+ deprecated: true
additionalProperties: false
- video-firmware:
- type: object
-
- description: |
- Firmware subnode is needed when the platform does not
- have TrustZone.
-
- properties:
- iommus:
- maxItems: 1
-
- required:
- - iommus
-
required:
- compatible
- - reg
- - interrupts
- - power-domains
- power-domain-names
- - clocks
- - clock-names
- iommus
- - memory-region
- - video-core0
- - video-core1
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/qcom,videocc-sdm845.h>
-
- video-codec@aa00000 {
- compatible = "qcom,sdm845-venus-v2";
- reg = <0x0aa00000 0xff000>;
- interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&videocc VIDEO_CC_VENUS_CTL_CORE_CLK>,
- <&videocc VIDEO_CC_VENUS_AHB_CLK>,
- <&videocc VIDEO_CC_VENUS_CTL_AXI_CLK>,
- <&videocc VIDEO_CC_VCODEC0_CORE_CLK>,
- <&videocc VIDEO_CC_VCODEC0_AXI_CLK>,
- <&videocc VIDEO_CC_VCODEC1_CORE_CLK>,
- <&videocc VIDEO_CC_VCODEC1_AXI_CLK>;
- clock-names = "core", "iface", "bus",
- "vcodec0_core", "vcodec0_bus",
- "vcodec1_core", "vcodec1_bus";
- power-domains = <&videocc VENUS_GDSC>,
- <&videocc VCODEC0_GDSC>,
- <&videocc VCODEC1_GDSC>;
- power-domain-names = "venus", "vcodec0", "vcodec1";
- iommus = <&apps_smmu 0x10a0 0x8>,
- <&apps_smmu 0x10b0 0x0>;
- memory-region = <&venus_mem>;
-
- video-core0 {
- compatible = "venus-decoder";
- };
-
- video-core1 {
- compatible = "venus-encoder";
- };
- };
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,videocc-sdm845.h>
+
+ video-codec@aa00000 {
+ compatible = "qcom,sdm845-venus-v2";
+ reg = <0x0aa00000 0xff000>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&videocc VIDEO_CC_VENUS_CTL_CORE_CLK>,
+ <&videocc VIDEO_CC_VENUS_AHB_CLK>,
+ <&videocc VIDEO_CC_VENUS_CTL_AXI_CLK>,
+ <&videocc VIDEO_CC_VCODEC0_CORE_CLK>,
+ <&videocc VIDEO_CC_VCODEC0_AXI_CLK>,
+ <&videocc VIDEO_CC_VCODEC1_CORE_CLK>,
+ <&videocc VIDEO_CC_VCODEC1_AXI_CLK>;
+ clock-names = "core", "iface", "bus",
+ "vcodec0_core", "vcodec0_bus",
+ "vcodec1_core", "vcodec1_bus";
+ power-domains = <&videocc VENUS_GDSC>,
+ <&videocc VCODEC0_GDSC>,
+ <&videocc VCODEC1_GDSC>;
+ power-domain-names = "venus", "vcodec0", "vcodec1";
+ iommus = <&apps_smmu 0x10a0 0x8>,
+ <&apps_smmu 0x10b0 0x0>;
+ memory-region = <&venus_mem>;
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sdm845-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sdm845-venus.yaml
index 680f37726fdf..eabc0957b241 100644
--- a/Documentation/devicetree/bindings/media/qcom,sdm845-venus.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,sdm845-venus.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,sdm845-venus.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,sdm845-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm Venus video encode and decode accelerators
+title: Qualcomm SDM845 Venus video encode and decode accelerators
maintainers:
- Stanimir Varbanov <stanimir.varbanov@linaro.org>
@@ -14,16 +13,13 @@ description: |
The Venus IP is a video encode and decode accelerator present
on Qualcomm platforms
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
properties:
compatible:
const: qcom,sdm845-venus
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
power-domains:
maxItems: 1
@@ -39,9 +35,6 @@ properties:
iommus:
maxItems: 2
- memory-region:
- maxItems: 1
-
video-core0:
type: object
@@ -94,65 +87,45 @@ properties:
additionalProperties: false
- video-firmware:
- type: object
-
- description: |
- Firmware subnode is needed when the platform does not
- have TrustZone.
-
- properties:
- iommus:
- maxItems: 1
-
- required:
- - iommus
-
required:
- compatible
- - reg
- - interrupts
- - power-domains
- - clocks
- - clock-names
- iommus
- - memory-region
- video-core0
- video-core1
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/qcom,videocc-sdm845.h>
-
- video-codec@aa00000 {
- compatible = "qcom,sdm845-venus";
- reg = <0x0aa00000 0xff000>;
- interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&videocc VIDEO_CC_VENUS_CTL_CORE_CLK>,
- <&videocc VIDEO_CC_VENUS_AHB_CLK>,
- <&videocc VIDEO_CC_VENUS_CTL_AXI_CLK>;
- clock-names = "core", "iface", "bus";
- power-domains = <&videocc VENUS_GDSC>;
- iommus = <&apps_smmu 0x10a0 0x8>,
- <&apps_smmu 0x10b0 0x0>;
- memory-region = <&venus_mem>;
-
- video-core0 {
- compatible = "venus-decoder";
- clocks = <&videocc VIDEO_CC_VCODEC0_CORE_CLK>,
- <&videocc VIDEO_CC_VCODEC0_AXI_CLK>;
- clock-names = "core", "bus";
- power-domains = <&videocc VCODEC0_GDSC>;
- };
-
- video-core1 {
- compatible = "venus-encoder";
- clocks = <&videocc VIDEO_CC_VCODEC1_CORE_CLK>,
- <&videocc VIDEO_CC_VCODEC1_AXI_CLK>;
- clock-names = "core", "bus";
- power-domains = <&videocc VCODEC1_GDSC>;
- };
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,videocc-sdm845.h>
+
+ video-codec@aa00000 {
+ compatible = "qcom,sdm845-venus";
+ reg = <0x0aa00000 0xff000>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&videocc VIDEO_CC_VENUS_CTL_CORE_CLK>,
+ <&videocc VIDEO_CC_VENUS_AHB_CLK>,
+ <&videocc VIDEO_CC_VENUS_CTL_AXI_CLK>;
+ clock-names = "core", "iface", "bus";
+ power-domains = <&videocc VENUS_GDSC>;
+ iommus = <&apps_smmu 0x10a0 0x8>,
+ <&apps_smmu 0x10b0 0x0>;
+ memory-region = <&venus_mem>;
+
+ video-core0 {
+ compatible = "venus-decoder";
+ clocks = <&videocc VIDEO_CC_VCODEC0_CORE_CLK>,
+ <&videocc VIDEO_CC_VCODEC0_AXI_CLK>;
+ clock-names = "core", "bus";
+ power-domains = <&videocc VCODEC0_GDSC>;
+ };
+
+ video-core1 {
+ compatible = "venus-encoder";
+ clocks = <&videocc VIDEO_CC_VCODEC1_CORE_CLK>,
+ <&videocc VIDEO_CC_VCODEC1_AXI_CLK>;
+ clock-names = "core", "bus";
+ power-domains = <&videocc VCODEC1_GDSC>;
};
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sm8250-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sm8250-camss.yaml
new file mode 100644
index 000000000000..ebf68ff4ab96
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sm8250-camss.yaml
@@ -0,0 +1,492 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sm8250-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm CAMSS ISP
+
+maintainers:
+ - Robert Foss <robert.foss@linaro.org>
+
+description: |
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sm8250-camss
+
+ clocks:
+ minItems: 37
+ maxItems: 37
+
+ clock-names:
+ items:
+ - const: cam_ahb_clk
+ - const: cam_hf_axi
+ - const: cam_sf_axi
+ - const: camnoc_axi
+ - const: camnoc_axi_src
+ - const: core_ahb
+ - const: cpas_ahb
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy3
+ - const: csiphy3_timer
+ - const: csiphy4
+ - const: csiphy4_timer
+ - const: csiphy5
+ - const: csiphy5_timer
+ - const: slow_ahb_src
+ - const: vfe0_ahb
+ - const: vfe0_axi
+ - const: vfe0
+ - const: vfe0_cphy_rx
+ - const: vfe0_csid
+ - const: vfe0_areg
+ - const: vfe1_ahb
+ - const: vfe1_axi
+ - const: vfe1
+ - const: vfe1_cphy_rx
+ - const: vfe1_csid
+ - const: vfe1_areg
+ - const: vfe_lite_ahb
+ - const: vfe_lite_axi
+ - const: vfe_lite
+ - const: vfe_lite_cphy_rx
+ - const: vfe_lite_csid
+
+ interrupts:
+ minItems: 14
+ maxItems: 14
+
+ interrupt-names:
+ items:
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: csiphy5
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid3
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ iommus:
+ minItems: 8
+ maxItems: 8
+
+ interconnects:
+ minItems: 4
+ maxItems: 4
+
+ interconnect-names:
+ items:
+ - const: cam_ahb
+ - const: cam_hf_0_mnoc
+ - const: cam_sf_0_mnoc
+ - const: cam_sf_icp_mnoc
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@3:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@4:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@5:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ reg:
+ minItems: 10
+ maxItems: 10
+
+ reg-names:
+ items:
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: csiphy5
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
+ description:
+ Phandle to 1.8V regulator supply to PHY refclk pll block.
+
+required:
+ - clock-names
+ - clocks
+ - compatible
+ - interconnects
+ - interconnect-names
+ - interrupts
+ - interrupt-names
+ - iommus
+ - power-domains
+ - reg
+ - reg-names
+ - vdda-phy-supply
+ - vdda-pll-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,camcc-sm8250.h>
+ #include <dt-bindings/interconnect/qcom,sm8250.h>
+ #include <dt-bindings/clock/qcom,gcc-sm8250.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ camss: camss@ac6a000 {
+ compatible = "qcom,sm8250-camss";
+
+ reg = <0 0xac6a000 0 0x2000>,
+ <0 0xac6c000 0 0x2000>,
+ <0 0xac6e000 0 0x1000>,
+ <0 0xac70000 0 0x1000>,
+ <0 0xac72000 0 0x1000>,
+ <0 0xac74000 0 0x1000>,
+ <0 0xacb4000 0 0xd000>,
+ <0 0xacc3000 0 0xd000>,
+ <0 0xacd9000 0 0x2200>,
+ <0 0xacdb200 0 0x2200>;
+ reg-names = "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "csiphy5",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ vdda-phy-supply = <&vreg_l5a_0p88>;
+ vdda-pll-supply = <&vreg_l9a_1p2>;
+
+ interrupts = <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 86 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 89 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 464 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 466 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 359 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 360 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "csiphy5",
+ "csid0",
+ "csid1",
+ "csid2",
+ "csid3",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ power-domains = <&camcc IFE_0_GDSC>,
+ <&camcc IFE_1_GDSC>,
+ <&camcc TITAN_TOP_GDSC>;
+
+ clocks = <&gcc GCC_CAMERA_AHB_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&gcc GCC_CAMERA_SF_AXI_CLK>,
+ <&camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&camcc CAM_CC_CAMNOC_AXI_CLK_SRC>,
+ <&camcc CAM_CC_CORE_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY3_CLK>,
+ <&camcc CAM_CC_CSI3PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY4_CLK>,
+ <&camcc CAM_CC_CSI4PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY5_CLK>,
+ <&camcc CAM_CC_CSI5PHYTIMER_CLK>,
+ <&camcc CAM_CC_SLOW_AHB_CLK_SRC>,
+ <&camcc CAM_CC_IFE_0_AHB_CLK>,
+ <&camcc CAM_CC_IFE_0_AXI_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_0_CSID_CLK>,
+ <&camcc CAM_CC_IFE_0_AREG_CLK>,
+ <&camcc CAM_CC_IFE_1_AHB_CLK>,
+ <&camcc CAM_CC_IFE_1_AXI_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_1_CSID_CLK>,
+ <&camcc CAM_CC_IFE_1_AREG_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AXI_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>;
+ clock-names = "cam_ahb_clk",
+ "cam_hf_axi",
+ "cam_sf_axi",
+ "camnoc_axi",
+ "camnoc_axi_src",
+ "core_ahb",
+ "cpas_ahb",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy3",
+ "csiphy3_timer",
+ "csiphy4",
+ "csiphy4_timer",
+ "csiphy5",
+ "csiphy5_timer",
+ "slow_ahb_src",
+ "vfe0_ahb",
+ "vfe0_axi",
+ "vfe0",
+ "vfe0_cphy_rx",
+ "vfe0_csid",
+ "vfe0_areg",
+ "vfe1_ahb",
+ "vfe1_axi",
+ "vfe1",
+ "vfe1_cphy_rx",
+ "vfe1_csid",
+ "vfe1_areg",
+ "vfe_lite_ahb",
+ "vfe_lite_axi",
+ "vfe_lite",
+ "vfe_lite_cphy_rx",
+ "vfe_lite_csid";
+
+ iommus = <&apps_smmu 0x800 0x400>,
+ <&apps_smmu 0x801 0x400>,
+ <&apps_smmu 0x840 0x400>,
+ <&apps_smmu 0x841 0x400>,
+ <&apps_smmu 0xC00 0x400>,
+ <&apps_smmu 0xC01 0x400>,
+ <&apps_smmu 0xC40 0x400>,
+ <&apps_smmu 0xC41 0x400>;
+
+ interconnects = <&gem_noc MASTER_AMPSS_M0 &config_noc SLAVE_CAMERA_CFG>,
+ <&mmss_noc MASTER_CAMNOC_HF &mc_virt SLAVE_EBI_CH0>,
+ <&mmss_noc MASTER_CAMNOC_SF &mc_virt SLAVE_EBI_CH0>,
+ <&mmss_noc MASTER_CAMNOC_ICP &mc_virt SLAVE_EBI_CH0>;
+ interconnect-names = "cam_ahb",
+ "cam_hf_0_mnoc",
+ "cam_sf_0_mnoc",
+ "cam_sf_icp_mnoc";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml b/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml
index ebf8f3d866a5..da54493220c9 100644
--- a/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml
+++ b/Documentation/devicetree/bindings/media/qcom,sm8250-venus.yaml
@@ -1,11 +1,10 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/qcom,sm8250-venus.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/qcom,sm8250-venus.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Qualcomm Venus video encode and decode accelerators
+title: Qualcomm SM8250 Venus video encode and decode accelerators
maintainers:
- Stanimir Varbanov <stanimir.varbanov@linaro.org>
@@ -14,16 +13,13 @@ description: |
The Venus IP is a video encode and decode accelerator present
on Qualcomm platforms
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
properties:
compatible:
const: qcom,sm8250-venus
- reg:
- maxItems: 1
-
- interrupts:
- maxItems: 1
-
power-domains:
minItems: 2
maxItems: 3
@@ -47,9 +43,6 @@ properties:
iommus:
maxItems: 1
- memory-region:
- maxItems: 1
-
interconnects:
maxItems: 2
@@ -58,6 +51,10 @@ properties:
- const: cpu-cfg
- const: video-mem
+ operating-points-v2: true
+ opp-table:
+ type: object
+
resets:
maxItems: 2
@@ -76,6 +73,7 @@ properties:
required:
- compatible
+ deprecated: true
additionalProperties: false
video-encoder:
@@ -88,79 +86,50 @@ properties:
required:
- compatible
+ deprecated: true
additionalProperties: false
- video-firmware:
- type: object
-
- description: |
- Firmware subnode is needed when the platform does not
- have TrustZone.
-
- properties:
- iommus:
- maxItems: 1
-
- required:
- - iommus
-
required:
- compatible
- - reg
- - interrupts
- - power-domains
- power-domain-names
- - clocks
- - clock-names
- interconnects
- interconnect-names
- iommus
- - memory-region
- resets
- reset-names
- - video-decoder
- - video-encoder
-additionalProperties: false
+unevaluatedProperties: false
examples:
- |
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/clock/qcom,videocc-sm8250.h>
- #include <dt-bindings/interconnect/qcom,sm8250.h>
- #include <dt-bindings/clock/qcom,gcc-sm8250.h>
- #include <dt-bindings/power/qcom-rpmpd.h>
-
- venus: video-codec@aa00000 {
- compatible = "qcom,sm8250-venus";
- reg = <0x0aa00000 0xff000>;
- interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
- power-domains = <&videocc MVS0C_GDSC>,
- <&videocc MVS0_GDSC>,
- <&rpmhpd SM8250_MX>;
- power-domain-names = "venus", "vcodec0", "mx";
-
- clocks = <&gcc GCC_VIDEO_AXI0_CLK>,
- <&videocc VIDEO_CC_MVS0C_CLK>,
- <&videocc VIDEO_CC_MVS0_CLK>;
- clock-names = "iface", "core", "vcodec0_core";
-
- interconnects = <&gem_noc MASTER_AMPSS_M0 &config_noc SLAVE_VENUS_CFG>,
- <&mmss_noc MASTER_VIDEO_P0 &mc_virt SLAVE_EBI_CH0>;
- interconnect-names = "cpu-cfg", "video-mem";
-
- iommus = <&apps_smmu 0x2100 0x0400>;
- memory-region = <&video_mem>;
-
- resets = <&gcc GCC_VIDEO_AXI0_CLK_ARES>,
- <&videocc VIDEO_CC_MVS0C_CLK_ARES>;
- reset-names = "bus", "core";
-
- video-decoder {
- compatible = "venus-decoder";
- };
-
- video-encoder {
- compatible = "venus-encoder";
- };
- };
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,videocc-sm8250.h>
+ #include <dt-bindings/interconnect/qcom,sm8250.h>
+ #include <dt-bindings/clock/qcom,gcc-sm8250.h>
+ #include <dt-bindings/power/qcom,rpmhpd.h>
+
+ venus: video-codec@aa00000 {
+ compatible = "qcom,sm8250-venus";
+ reg = <0x0aa00000 0xff000>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&videocc MVS0C_GDSC>,
+ <&videocc MVS0_GDSC>,
+ <&rpmhpd RPMHPD_MX>;
+ power-domain-names = "venus", "vcodec0", "mx";
+
+ clocks = <&gcc GCC_VIDEO_AXI0_CLK>,
+ <&videocc VIDEO_CC_MVS0C_CLK>,
+ <&videocc VIDEO_CC_MVS0_CLK>;
+ clock-names = "iface", "core", "vcodec0_core";
+
+ interconnects = <&gem_noc MASTER_AMPSS_M0 &config_noc SLAVE_VENUS_CFG>,
+ <&mmss_noc MASTER_VIDEO_P0 &mc_virt SLAVE_EBI_CH0>;
+ interconnect-names = "cpu-cfg", "video-mem";
+
+ iommus = <&apps_smmu 0x2100 0x0400>;
+ memory-region = <&video_mem>;
+
+ resets = <&gcc GCC_VIDEO_AXI0_CLK_ARES>,
+ <&videocc VIDEO_CC_MVS0C_CLK_ARES>;
+ reset-names = "bus", "core";
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sm8550-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sm8550-camss.yaml
new file mode 100644
index 000000000000..cd34f14916b4
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sm8550-camss.yaml
@@ -0,0 +1,597 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sm8550-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SM8550 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Depeng Shao <quic_depengs@quicinc.com>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sm8550-camss
+
+ reg:
+ maxItems: 19
+
+ reg-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csid_wrapper
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: csiphy5
+ - const: csiphy6
+ - const: csiphy7
+ - const: vfe0
+ - const: vfe1
+ - const: vfe2
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ clocks:
+ maxItems: 36
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: cpas_ahb
+ - const: cpas_fast_ahb_clk
+ - const: cpas_ife_lite
+ - const: cpas_vfe0
+ - const: cpas_vfe1
+ - const: cpas_vfe2
+ - const: csid
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy3
+ - const: csiphy3_timer
+ - const: csiphy4
+ - const: csiphy4_timer
+ - const: csiphy5
+ - const: csiphy5_timer
+ - const: csiphy6
+ - const: csiphy6_timer
+ - const: csiphy7
+ - const: csiphy7_timer
+ - const: csiphy_rx
+ - const: gcc_axi_hf
+ - const: vfe0
+ - const: vfe0_fast_ahb
+ - const: vfe1
+ - const: vfe1_fast_ahb
+ - const: vfe2
+ - const: vfe2_fast_ahb
+ - const: vfe_lite
+ - const: vfe_lite_ahb
+ - const: vfe_lite_cphy_rx
+ - const: vfe_lite_csid
+
+ interrupts:
+ maxItems: 18
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: csiphy5
+ - const: csiphy6
+ - const: csiphy7
+ - const: vfe0
+ - const: vfe1
+ - const: vfe2
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_0_mnoc
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE2 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: ife0
+ - const: ife1
+ - const: ife2
+ - const: top
+
+ vdda-phy-supply:
+ description:
+ Phandle to a regulator supply to PHY core block.
+
+ vdda-pll-supply:
+ description:
+ Phandle to 1.2V regulator supply to PHY refclk pll block.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI0.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI1.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@2:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI2.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@3:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI3.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@4:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI4.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@5:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI5.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@6:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI6.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@7:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port for receiving CSI data on CSI7.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ clock-lanes:
+ maxItems: 1
+
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - vdda-phy-supply
+ - vdda-pll-supply
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/clock/qcom,sm8550-camcc.h>
+ #include <dt-bindings/clock/qcom,sm8550-gcc.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interconnect/qcom,sm8550-rpmh.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@acb7000 {
+ compatible = "qcom,sm8550-camss";
+
+ reg = <0 0x0acb7000 0 0xd00>,
+ <0 0x0acb9000 0 0xd00>,
+ <0 0x0acbb000 0 0xd00>,
+ <0 0x0acca000 0 0xa00>,
+ <0 0x0acce000 0 0xa00>,
+ <0 0x0acb6000 0 0x1000>,
+ <0 0x0ace4000 0 0x2000>,
+ <0 0x0ace6000 0 0x2000>,
+ <0 0x0ace8000 0 0x2000>,
+ <0 0x0acea000 0 0x2000>,
+ <0 0x0acec000 0 0x2000>,
+ <0 0x0acee000 0 0x2000>,
+ <0 0x0acf0000 0 0x2000>,
+ <0 0x0acf2000 0 0x2000>,
+ <0 0x0ac62000 0 0xf000>,
+ <0 0x0ac71000 0 0xf000>,
+ <0 0x0ac80000 0 0xf000>,
+ <0 0x0accb000 0 0x1800>,
+ <0 0x0accf000 0 0x1800>;
+ reg-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csid_wrapper",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "csiphy5",
+ "csiphy6",
+ "csiphy7",
+ "vfe0",
+ "vfe1",
+ "vfe2",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_FAST_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_LITE_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_0_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_1_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_2_CLK>,
+ <&camcc CAM_CC_CSID_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY3_CLK>,
+ <&camcc CAM_CC_CSI3PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY4_CLK>,
+ <&camcc CAM_CC_CSI4PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY5_CLK>,
+ <&camcc CAM_CC_CSI5PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY6_CLK>,
+ <&camcc CAM_CC_CSI6PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY7_CLK>,
+ <&camcc CAM_CC_CSI7PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSID_CSIPHY_RX_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_2_CLK>,
+ <&camcc CAM_CC_IFE_2_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>;
+ clock-names = "camnoc_axi",
+ "cpas_ahb",
+ "cpas_fast_ahb_clk",
+ "cpas_ife_lite",
+ "cpas_vfe0",
+ "cpas_vfe1",
+ "cpas_vfe2",
+ "csid",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy3",
+ "csiphy3_timer",
+ "csiphy4",
+ "csiphy4_timer",
+ "csiphy5",
+ "csiphy5_timer",
+ "csiphy6",
+ "csiphy6_timer",
+ "csiphy7",
+ "csiphy7_timer",
+ "csiphy_rx",
+ "gcc_axi_hf",
+ "vfe0",
+ "vfe0_fast_ahb",
+ "vfe1",
+ "vfe1_fast_ahb",
+ "vfe2",
+ "vfe2_fast_ahb",
+ "vfe_lite",
+ "vfe_lite_ahb",
+ "vfe_lite_cphy_rx",
+ "vfe_lite_csid";
+
+ interrupts = <GIC_SPI 601 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 603 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 431 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 605 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 376 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 122 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 89 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 278 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 277 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 602 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 604 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 688 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 606 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 377 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "csiphy5",
+ "csiphy6",
+ "csiphy7",
+ "vfe0",
+ "vfe1",
+ "vfe2",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY
+ &config_noc SLAVE_CAMERA_CFG QCOM_ICC_TAG_ACTIVE_ONLY>,
+ <&mmss_noc MASTER_CAMNOC_HF QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+ interconnect-names = "ahb",
+ "hf_0_mnoc";
+
+ iommus = <&apps_smmu 0x800 0x20>;
+
+ power-domains = <&camcc CAM_CC_IFE_0_GDSC>,
+ <&camcc CAM_CC_IFE_1_GDSC>,
+ <&camcc CAM_CC_IFE_2_GDSC>,
+ <&camcc CAM_CC_TITAN_TOP_GDSC>;
+ power-domain-names = "ife0",
+ "ife1",
+ "ife2",
+ "top";
+
+ vdda-phy-supply = <&vreg_l1e_0p88>;
+ vdda-pll-supply = <&vreg_l3e_1p2>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ csiphy_ep0: endpoint@0 {
+ reg = <0>;
+ clock-lanes = <7>;
+ data-lanes = <0 1>;
+ remote-endpoint = <&sensor_ep>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sm8550-iris.yaml b/Documentation/devicetree/bindings/media/qcom,sm8550-iris.yaml
new file mode 100644
index 000000000000..9c4b760508b5
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sm8550-iris.yaml
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sm8550-iris.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm iris video encode and decode accelerators
+
+maintainers:
+ - Vikash Garodia <quic_vgarodia@quicinc.com>
+ - Dikshita Agarwal <dikshita.agarwal@oss.qualcomm.com>
+
+description:
+ The iris video processing unit is a video encode and decode accelerator
+ present on Qualcomm platforms.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - qcom,sa8775p-iris
+ - qcom,x1e80100-iris
+ - const: qcom,sm8550-iris
+ - enum:
+ - qcom,qcs8300-iris
+ - qcom,sm8550-iris
+ - qcom,sm8650-iris
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 4
+
+ power-domain-names:
+ items:
+ - const: venus
+ - const: vcodec0
+ - const: mxc
+ - const: mmcx
+
+ clocks:
+ maxItems: 3
+
+ clock-names:
+ items:
+ - const: iface
+ - const: core
+ - const: vcodec0_core
+
+ firmware-name:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: cpu-cfg
+ - const: video-mem
+
+ resets:
+ minItems: 1
+ maxItems: 3
+
+ reset-names:
+ minItems: 1
+ items:
+ - const: bus
+ - const: xo
+ - const: core
+
+ iommus:
+ maxItems: 2
+
+ dma-coherent: true
+
+ memory-region:
+ maxItems: 1
+
+ operating-points-v2: true
+
+ opp-table:
+ type: object
+
+required:
+ - compatible
+ - power-domain-names
+ - interconnects
+ - interconnect-names
+ - resets
+ - reset-names
+ - iommus
+ - dma-coherent
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ enum:
+ - qcom,sm8650-iris
+ then:
+ properties:
+ resets:
+ minItems: 3
+ reset-names:
+ minItems: 3
+ else:
+ properties:
+ resets:
+ maxItems: 1
+ reset-names:
+ maxItems: 1
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/clock/qcom,sm8550-gcc.h>
+ #include <dt-bindings/clock/qcom,sm8450-videocc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interconnect/qcom,sm8550-rpmh.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+ #include <dt-bindings/power/qcom,rpmhpd.h>
+
+ video-codec@aa00000 {
+ compatible = "qcom,sm8550-iris";
+ reg = <0x0aa00000 0xf0000>;
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+
+ power-domains = <&videocc VIDEO_CC_MVS0C_GDSC>,
+ <&videocc VIDEO_CC_MVS0_GDSC>,
+ <&rpmhpd RPMHPD_MXC>,
+ <&rpmhpd RPMHPD_MMCX>;
+ power-domain-names = "venus", "vcodec0", "mxc", "mmcx";
+
+ clocks = <&gcc GCC_VIDEO_AXI0_CLK>,
+ <&videocc VIDEO_CC_MVS0C_CLK>,
+ <&videocc VIDEO_CC_MVS0_CLK>;
+ clock-names = "iface", "core", "vcodec0_core";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ALWAYS
+ &config_noc SLAVE_VENUS_CFG QCOM_ICC_TAG_ALWAYS>,
+ <&mmss_noc MASTER_VIDEO QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+ interconnect-names = "cpu-cfg", "video-mem";
+
+ memory-region = <&video_mem>;
+
+ resets = <&gcc GCC_VIDEO_AXI0_CLK_ARES>;
+ reset-names = "bus";
+
+ iommus = <&apps_smmu 0x1940 0x0000>,
+ <&apps_smmu 0x1947 0x0000>;
+ dma-coherent;
+
+ operating-points-v2 = <&iris_opp_table>;
+
+ iris_opp_table: opp-table {
+ compatible = "operating-points-v2";
+
+ opp-240000000 {
+ opp-hz = /bits/ 64 <240000000>;
+ required-opps = <&rpmhpd_opp_svs>,
+ <&rpmhpd_opp_low_svs>;
+ };
+
+ opp-338000000 {
+ opp-hz = /bits/ 64 <338000000>;
+ required-opps = <&rpmhpd_opp_svs>,
+ <&rpmhpd_opp_svs>;
+ };
+
+ opp-366000000 {
+ opp-hz = /bits/ 64 <366000000>;
+ required-opps = <&rpmhpd_opp_svs_l1>,
+ <&rpmhpd_opp_svs_l1>;
+ };
+
+ opp-444000000 {
+ opp-hz = /bits/ 64 <444000000>;
+ required-opps = <&rpmhpd_opp_turbo>,
+ <&rpmhpd_opp_turbo>;
+ };
+
+ opp-533333334 {
+ opp-hz = /bits/ 64 <533333334>;
+ required-opps = <&rpmhpd_opp_turbo_l1>,
+ <&rpmhpd_opp_turbo_l1>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/qcom,sm8650-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sm8650-camss.yaml
new file mode 100644
index 000000000000..9c8de722601e
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sm8650-camss.yaml
@@ -0,0 +1,375 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sm8650-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SM8650 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Vladimir Zapolskiy <vladimir.zapolskiy@linaro.org>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,sm8650-camss
+
+ reg:
+ maxItems: 17
+
+ reg-names:
+ items:
+ - const: csid_wrapper
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: csiphy5
+ - const: vfe0
+ - const: vfe1
+ - const: vfe2
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ clocks:
+ maxItems: 33
+
+ clock-names:
+ items:
+ - const: camnoc_axi
+ - const: cpas_ahb
+ - const: cpas_fast_ahb
+ - const: cpas_vfe0
+ - const: cpas_vfe1
+ - const: cpas_vfe2
+ - const: cpas_vfe_lite
+ - const: csid
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy3
+ - const: csiphy3_timer
+ - const: csiphy4
+ - const: csiphy4_timer
+ - const: csiphy5
+ - const: csiphy5_timer
+ - const: csiphy_rx
+ - const: gcc_axi_hf
+ - const: qdss_debug_xo
+ - const: vfe0
+ - const: vfe0_fast_ahb
+ - const: vfe1
+ - const: vfe1_fast_ahb
+ - const: vfe2
+ - const: vfe2_fast_ahb
+ - const: vfe_lite
+ - const: vfe_lite_ahb
+ - const: vfe_lite_cphy_rx
+ - const: vfe_lite_csid
+
+ interrupts:
+ maxItems: 16
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy3
+ - const: csiphy4
+ - const: csiphy5
+ - const: vfe0
+ - const: vfe1
+ - const: vfe2
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_mnoc
+
+ iommus:
+ maxItems: 3
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE2 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: ife0
+ - const: ife1
+ - const: ife2
+ - const: top
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ patternProperties:
+ "^port@[0-5]$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ description:
+ Input port for receiving CSI data from a CSIPHY.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+
+ vdd-csiphy01-0p9-supply:
+ description:
+ Phandle to a 0.9V regulator supply to CSIPHY0 and CSIPHY1 IP blocks.
+
+ vdd-csiphy01-1p2-supply:
+ description:
+ Phandle to a 1.2V regulator supply to CSIPHY0 and CSIPHY1 IP blocks.
+
+ vdd-csiphy24-0p9-supply:
+ description:
+ Phandle to a 0.9V regulator supply to CSIPHY2 and CSIPHY4 IP blocks.
+
+ vdd-csiphy24-1p2-supply:
+ description:
+ Phandle to a 1.2V regulator supply to CSIPHY2 and CSIPHY4 IP blocks.
+
+ vdd-csiphy35-0p9-supply:
+ description:
+ Phandle to a 0.9V regulator supply to CSIPHY3 and CSIPHY5 IP blocks.
+
+ vdd-csiphy35-1p2-supply:
+ description:
+ Phandle to a 1.2V regulator supply to CSIPHY3 and CSIPHY5 IP blocks.
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interconnects
+ - interconnect-names
+ - interrupts
+ - interrupt-names
+ - iommus
+ - power-domains
+ - power-domain-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,sm8650-camcc.h>
+ #include <dt-bindings/clock/qcom,sm8650-gcc.h>
+ #include <dt-bindings/interconnect/qcom,sm8650-rpmh.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@acb6000 {
+ compatible = "qcom,sm8650-camss";
+ reg = <0 0x0acb6000 0 0x1000>,
+ <0 0x0acb8000 0 0x1000>,
+ <0 0x0acba000 0 0x1000>,
+ <0 0x0acbc000 0 0x1000>,
+ <0 0x0accb000 0 0x1000>,
+ <0 0x0acd0000 0 0x1000>,
+ <0 0x0ace4000 0 0x2000>,
+ <0 0x0ace6000 0 0x2000>,
+ <0 0x0ace8000 0 0x2000>,
+ <0 0x0acea000 0 0x2000>,
+ <0 0x0acec000 0 0x2000>,
+ <0 0x0acee000 0 0x2000>,
+ <0 0x0ac62000 0 0xf000>,
+ <0 0x0ac71000 0 0xf000>,
+ <0 0x0ac80000 0 0xf000>,
+ <0 0x0accc000 0 0x2000>,
+ <0 0x0acd1000 0 0x2000>;
+ reg-names = "csid_wrapper",
+ "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "csiphy5",
+ "vfe0",
+ "vfe1",
+ "vfe2",
+ "vfe_lite0",
+ "vfe_lite1";
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_RT_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_FAST_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_0_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_1_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_2_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_LITE_CLK>,
+ <&camcc CAM_CC_CSID_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI3PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY3_CLK>,
+ <&camcc CAM_CC_CSI4PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY4_CLK>,
+ <&camcc CAM_CC_CSI5PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY5_CLK>,
+ <&camcc CAM_CC_CSID_CSIPHY_RX_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&camcc CAM_CC_QDSS_DEBUG_XO_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_2_CLK>,
+ <&camcc CAM_CC_IFE_2_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>;
+ clock-names = "camnoc_axi",
+ "cpas_ahb",
+ "cpas_fast_ahb",
+ "cpas_vfe0",
+ "cpas_vfe1",
+ "cpas_vfe2",
+ "cpas_vfe_lite",
+ "csid",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy3",
+ "csiphy3_timer",
+ "csiphy4",
+ "csiphy4_timer",
+ "csiphy5",
+ "csiphy5_timer",
+ "csiphy_rx",
+ "gcc_axi_hf",
+ "qdss_debug_xo",
+ "vfe0",
+ "vfe0_fast_ahb",
+ "vfe1",
+ "vfe1_fast_ahb",
+ "vfe2",
+ "vfe2_fast_ahb",
+ "vfe_lite",
+ "vfe_lite_ahb",
+ "vfe_lite_cphy_rx",
+ "vfe_lite_csid";
+ interrupts = <GIC_SPI 601 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 603 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 431 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 605 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 376 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 448 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 122 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 89 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 602 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 604 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 688 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 606 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 377 IRQ_TYPE_EDGE_RISING>;
+ interrupt-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy3",
+ "csiphy4",
+ "csiphy5",
+ "vfe0",
+ "vfe1",
+ "vfe2",
+ "vfe_lite0",
+ "vfe_lite1";
+ interconnects = <&gem_noc MASTER_APPSS_PROC 0
+ &config_noc SLAVE_CAMERA_CFG 0>,
+ <&mmss_noc MASTER_CAMNOC_HF 0
+ &mc_virt SLAVE_EBI1 0>;
+ interconnect-names = "ahb", "hf_mnoc";
+ iommus = <&apps_smmu 0x800 0x20>,
+ <&apps_smmu 0x18a0 0x40>,
+ <&apps_smmu 0x1860 0x00>;
+ power-domains = <&camcc CAM_CC_IFE_0_GDSC>,
+ <&camcc CAM_CC_IFE_1_GDSC>,
+ <&camcc CAM_CC_IFE_2_GDSC>,
+ <&camcc CAM_CC_TITAN_TOP_GDSC>;
+ power-domain-names = "ife0", "ife1", "ife2", "top";
+ vdd-csiphy01-0p9-supply = <&vreg_0p9>;
+ vdd-csiphy01-1p2-supply = <&vreg_1p2>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@1 {
+ reg = <1>;
+
+ csiphy1_ep: endpoint {
+ data-lanes = <0 1>;
+ remote-endpoint = <&camera_sensor>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,sm8750-iris.yaml b/Documentation/devicetree/bindings/media/qcom,sm8750-iris.yaml
new file mode 100644
index 000000000000..c42d3470bdac
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,sm8750-iris.yaml
@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,sm8750-iris.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SM8750 SoC Iris video encoder and decoder
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+description:
+ The Iris video processing unit on Qualcomm SM8750 SoC is a video encode and
+ decode accelerator.
+
+properties:
+ compatible:
+ enum:
+ - qcom,sm8750-iris
+
+ clocks:
+ maxItems: 6
+
+ clock-names:
+ items:
+ - const: iface # AXI0
+ - const: core
+ - const: vcodec0_core
+ - const: iface1 # AXI1
+ - const: core_freerun
+ - const: vcodec0_core_freerun
+
+ dma-coherent: true
+
+ interconnects:
+ maxItems: 2
+
+ interconnect-names:
+ items:
+ - const: cpu-cfg
+ - const: video-mem
+
+ iommus:
+ maxItems: 2
+
+ operating-points-v2: true
+ opp-table:
+ type: object
+
+ power-domains:
+ maxItems: 4
+
+ power-domain-names:
+ items:
+ - const: venus
+ - const: vcodec0
+ - const: mxc
+ - const: mmcx
+
+ resets:
+ maxItems: 4
+
+ reset-names:
+ items:
+ - const: bus0
+ - const: bus1
+ - const: core
+ - const: vcodec0_core
+
+required:
+ - compatible
+ - dma-coherent
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domain-names
+ - resets
+ - reset-names
+
+allOf:
+ - $ref: qcom,venus-common.yaml#
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/qcom,rpmh.h>
+ #include <dt-bindings/clock/qcom,sm8750-gcc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interconnect/qcom,sm8750-rpmh.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+ #include <dt-bindings/power/qcom,rpmhpd.h>
+
+ video-codec@aa00000 {
+ compatible = "qcom,sm8750-iris";
+ reg = <0x0aa00000 0xf0000>;
+
+ clocks = <&gcc GCC_VIDEO_AXI0_CLK>,
+ <&videocc_mvs0c_clk>,
+ <&videocc_mvs0_clk>,
+ <&gcc GCC_VIDEO_AXI1_CLK>,
+ <&videocc_mvs0c_freerun_clk>,
+ <&videocc_mvs0_freerun_clk>;
+ clock-names = "iface",
+ "core",
+ "vcodec0_core",
+ "iface1",
+ "core_freerun",
+ "vcodec0_core_freerun";
+
+ dma-coherent;
+ iommus = <&apps_smmu 0x1940 0>,
+ <&apps_smmu 0x1947 0>;
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY
+ &config_noc SLAVE_VENUS_CFG QCOM_ICC_TAG_ACTIVE_ONLY>,
+ <&mmss_noc MASTER_VIDEO_MVP QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+ interconnect-names = "cpu-cfg",
+ "video-mem";
+
+ interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>;
+
+ operating-points-v2 = <&iris_opp_table>;
+
+ memory-region = <&video_mem>;
+
+ power-domains = <&videocc_mvs0c_gdsc>,
+ <&videocc_mvs0_gdsc>,
+ <&rpmhpd RPMHPD_MXC>,
+ <&rpmhpd RPMHPD_MMCX>;
+ power-domain-names = "venus",
+ "vcodec0",
+ "mxc",
+ "mmcx";
+
+ resets = <&gcc GCC_VIDEO_AXI0_CLK_ARES>,
+ <&gcc GCC_VIDEO_AXI1_CLK_ARES>,
+ <&videocc_mvs0c_freerun_clk_ares>,
+ <&videocc_mvs0_freerun_clk_ares>;
+ reset-names = "bus0",
+ "bus1",
+ "core",
+ "vcodec0_core";
+
+ iris_opp_table: opp-table {
+ compatible = "operating-points-v2";
+
+ opp-240000000 {
+ opp-hz = /bits/ 64 <240000000>;
+ required-opps = <&rpmhpd_opp_low_svs_d1>,
+ <&rpmhpd_opp_low_svs_d1>;
+ };
+
+ opp-338000000 {
+ opp-hz = /bits/ 64 <338000000>;
+ required-opps = <&rpmhpd_opp_low_svs>,
+ <&rpmhpd_opp_low_svs>;
+ };
+
+ opp-420000000 {
+ opp-hz = /bits/ 64 <420000000>;
+ required-opps = <&rpmhpd_opp_svs>,
+ <&rpmhpd_opp_svs>;
+ };
+
+ opp-444000000 {
+ opp-hz = /bits/ 64 <444000000>;
+ required-opps = <&rpmhpd_opp_svs_l1>,
+ <&rpmhpd_opp_svs_l1>;
+ };
+
+ opp-533333334 {
+ opp-hz = /bits/ 64 <533333334>;
+ required-opps = <&rpmhpd_opp_nom>,
+ <&rpmhpd_opp_nom>;
+ };
+
+ opp-630000000 {
+ opp-hz = /bits/ 64 <630000000>;
+ required-opps = <&rpmhpd_opp_turbo>,
+ <&rpmhpd_opp_turbo>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/qcom,venus-common.yaml b/Documentation/devicetree/bindings/media/qcom,venus-common.yaml
new file mode 100644
index 000000000000..3153d91f9d18
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,venus-common.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,venus-common.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SoC Venus Video Encode and Decode Accelerators Common Properties
+
+maintainers:
+ - Stanimir Varbanov <stanimir.k.varbanov@gmail.com>
+ - Vikash Garodia <quic_vgarodia@quicinc.com>
+
+description: |
+ The Venus IP is a video encode and decode accelerator present
+ on Qualcomm platforms
+
+properties:
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 3
+ maxItems: 7
+
+ clock-names:
+ minItems: 3
+ maxItems: 7
+
+ firmware-name:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ minItems: 1
+ maxItems: 20
+
+ memory-region:
+ maxItems: 1
+
+ power-domains:
+ minItems: 1
+ maxItems: 4
+
+ power-domain-names:
+ minItems: 1
+ maxItems: 4
+
+ video-firmware:
+ type: object
+ additionalProperties: false
+
+ description: |
+ Firmware subnode is needed when the platform does not
+ have TrustZone.
+
+ properties:
+ iommus:
+ maxItems: 1
+
+ required:
+ - iommus
+
+required:
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+ - memory-region
+ - power-domains
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/media/qcom,x1e80100-camss.yaml b/Documentation/devicetree/bindings/media/qcom,x1e80100-camss.yaml
new file mode 100644
index 000000000000..b87a13479a4b
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/qcom,x1e80100-camss.yaml
@@ -0,0 +1,367 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/qcom,x1e80100-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm X1E80100 Camera Subsystem (CAMSS)
+
+maintainers:
+ - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
+
+description:
+ The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms.
+
+properties:
+ compatible:
+ const: qcom,x1e80100-camss
+
+ reg:
+ maxItems: 17
+
+ reg-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csid_wrapper
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy4
+ - const: csitpg0
+ - const: csitpg1
+ - const: csitpg2
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ clocks:
+ maxItems: 29
+
+ clock-names:
+ items:
+ - const: camnoc_nrt_axi
+ - const: camnoc_rt_axi
+ - const: core_ahb
+ - const: cpas_ahb
+ - const: cpas_fast_ahb
+ - const: cpas_vfe0
+ - const: cpas_vfe1
+ - const: cpas_vfe_lite
+ - const: cphy_rx_clk_src
+ - const: csid
+ - const: csid_csiphy_rx
+ - const: csiphy0
+ - const: csiphy0_timer
+ - const: csiphy1
+ - const: csiphy1_timer
+ - const: csiphy2
+ - const: csiphy2_timer
+ - const: csiphy4
+ - const: csiphy4_timer
+ - const: gcc_axi_hf
+ - const: gcc_axi_sf
+ - const: vfe0
+ - const: vfe0_fast_ahb
+ - const: vfe1
+ - const: vfe1_fast_ahb
+ - const: vfe_lite
+ - const: vfe_lite_ahb
+ - const: vfe_lite_cphy_rx
+ - const: vfe_lite_csid
+
+ interrupts:
+ maxItems: 13
+
+ interrupt-names:
+ items:
+ - const: csid0
+ - const: csid1
+ - const: csid2
+ - const: csid_lite0
+ - const: csid_lite1
+ - const: csiphy0
+ - const: csiphy1
+ - const: csiphy2
+ - const: csiphy4
+ - const: vfe0
+ - const: vfe1
+ - const: vfe_lite0
+ - const: vfe_lite1
+
+ interconnects:
+ maxItems: 4
+
+ interconnect-names:
+ items:
+ - const: ahb
+ - const: hf_mnoc
+ - const: sf_mnoc
+ - const: sf_icp_mnoc
+
+ iommus:
+ maxItems: 8
+
+ power-domains:
+ items:
+ - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller.
+ - description: Titan Top GDSC - Titan ISP Block, Global Distributed Switch Controller.
+
+ power-domain-names:
+ items:
+ - const: ife0
+ - const: ife1
+ - const: top
+
+ vdd-csiphy-0p8-supply:
+ description:
+ Phandle to a 0.8V regulator supply to a PHY.
+
+ vdd-csiphy-1p2-supply:
+ description:
+ Phandle to 1.2V regulator supply to a PHY.
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ description:
+ CSI input ports.
+
+ patternProperties:
+ "^port@[0-3]$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+
+ description:
+ Input port for receiving CSI data from a CSIPHY.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ bus-type:
+ enum:
+ - 1 # MEDIA_BUS_TYPE_CSI2_CPHY
+ - 4 # MEDIA_BUS_TYPE_CSI2_DPHY
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - interrupts
+ - interrupt-names
+ - interconnects
+ - interconnect-names
+ - iommus
+ - power-domains
+ - power-domain-names
+ - vdd-csiphy-0p8-supply
+ - vdd-csiphy-1p2-supply
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/qcom,x1e80100-gcc.h>
+ #include <dt-bindings/clock/qcom,x1e80100-camcc.h>
+ #include <dt-bindings/interconnect/qcom,icc.h>
+ #include <dt-bindings/interconnect/qcom,x1e80100-rpmh.h>
+ #include <dt-bindings/power/qcom-rpmpd.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ camss: isp@acb7000 {
+ compatible = "qcom,x1e80100-camss";
+
+ reg = <0 0x0acb7000 0 0x2000>,
+ <0 0x0acb9000 0 0x2000>,
+ <0 0x0acbb000 0 0x2000>,
+ <0 0x0acc6000 0 0x1000>,
+ <0 0x0acca000 0 0x1000>,
+ <0 0x0acb6000 0 0x1000>,
+ <0 0x0ace4000 0 0x1000>,
+ <0 0x0ace6000 0 0x1000>,
+ <0 0x0ace8000 0 0x1000>,
+ <0 0x0acec000 0 0x4000>,
+ <0 0x0acf6000 0 0x1000>,
+ <0 0x0acf7000 0 0x1000>,
+ <0 0x0acf8000 0 0x1000>,
+ <0 0x0ac62000 0 0x4000>,
+ <0 0x0ac71000 0 0x4000>,
+ <0 0x0acc7000 0 0x2000>,
+ <0 0x0accb000 0 0x2000>;
+
+ reg-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csid_wrapper",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy4",
+ "csitpg0",
+ "csitpg1",
+ "csitpg2",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ clocks = <&camcc CAM_CC_CAMNOC_AXI_NRT_CLK>,
+ <&camcc CAM_CC_CAMNOC_AXI_RT_CLK>,
+ <&camcc CAM_CC_CORE_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_FAST_AHB_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_0_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_1_CLK>,
+ <&camcc CAM_CC_CPAS_IFE_LITE_CLK>,
+ <&camcc CAM_CC_CPHY_RX_CLK_SRC>,
+ <&camcc CAM_CC_CSID_CLK>,
+ <&camcc CAM_CC_CSID_CSIPHY_RX_CLK>,
+ <&camcc CAM_CC_CSIPHY0_CLK>,
+ <&camcc CAM_CC_CSI0PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY1_CLK>,
+ <&camcc CAM_CC_CSI1PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY2_CLK>,
+ <&camcc CAM_CC_CSI2PHYTIMER_CLK>,
+ <&camcc CAM_CC_CSIPHY4_CLK>,
+ <&camcc CAM_CC_CSI4PHYTIMER_CLK>,
+ <&gcc GCC_CAMERA_HF_AXI_CLK>,
+ <&gcc GCC_CAMERA_SF_AXI_CLK>,
+ <&camcc CAM_CC_IFE_0_CLK>,
+ <&camcc CAM_CC_IFE_0_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_1_CLK>,
+ <&camcc CAM_CC_IFE_1_FAST_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CLK>,
+ <&camcc CAM_CC_IFE_LITE_AHB_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>,
+ <&camcc CAM_CC_IFE_LITE_CSID_CLK>;
+
+ clock-names = "camnoc_nrt_axi",
+ "camnoc_rt_axi",
+ "core_ahb",
+ "cpas_ahb",
+ "cpas_fast_ahb",
+ "cpas_vfe0",
+ "cpas_vfe1",
+ "cpas_vfe_lite",
+ "cphy_rx_clk_src",
+ "csid",
+ "csid_csiphy_rx",
+ "csiphy0",
+ "csiphy0_timer",
+ "csiphy1",
+ "csiphy1_timer",
+ "csiphy2",
+ "csiphy2_timer",
+ "csiphy4",
+ "csiphy4_timer",
+ "gcc_axi_hf",
+ "gcc_axi_sf",
+ "vfe0",
+ "vfe0_fast_ahb",
+ "vfe1",
+ "vfe1_fast_ahb",
+ "vfe_lite",
+ "vfe_lite_ahb",
+ "vfe_lite_cphy_rx",
+ "vfe_lite_csid";
+
+ interrupts = <GIC_SPI 464 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 466 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 431 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 468 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 359 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 477 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 478 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 479 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 122 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 465 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 467 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 469 IRQ_TYPE_EDGE_RISING>,
+ <GIC_SPI 360 IRQ_TYPE_EDGE_RISING>;
+
+ interrupt-names = "csid0",
+ "csid1",
+ "csid2",
+ "csid_lite0",
+ "csid_lite1",
+ "csiphy0",
+ "csiphy1",
+ "csiphy2",
+ "csiphy4",
+ "vfe0",
+ "vfe1",
+ "vfe_lite0",
+ "vfe_lite1";
+
+ interconnects = <&gem_noc MASTER_APPSS_PROC QCOM_ICC_TAG_ACTIVE_ONLY
+ &config_noc SLAVE_CAMERA_CFG QCOM_ICC_TAG_ACTIVE_ONLY>,
+ <&mmss_noc MASTER_CAMNOC_HF QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>,
+ <&mmss_noc MASTER_CAMNOC_SF QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>,
+ <&mmss_noc MASTER_CAMNOC_ICP QCOM_ICC_TAG_ALWAYS
+ &mc_virt SLAVE_EBI1 QCOM_ICC_TAG_ALWAYS>;
+
+ interconnect-names = "ahb",
+ "hf_mnoc",
+ "sf_mnoc",
+ "sf_icp_mnoc";
+
+ iommus = <&apps_smmu 0x800 0x60>,
+ <&apps_smmu 0x860 0x60>,
+ <&apps_smmu 0x1800 0x60>,
+ <&apps_smmu 0x1860 0x60>,
+ <&apps_smmu 0x18e0 0x00>,
+ <&apps_smmu 0x1980 0x20>,
+ <&apps_smmu 0x1900 0x00>,
+ <&apps_smmu 0x19a0 0x20>;
+
+ power-domains = <&camcc CAM_CC_IFE_0_GDSC>,
+ <&camcc CAM_CC_IFE_1_GDSC>,
+ <&camcc CAM_CC_TITAN_TOP_GDSC>;
+
+ power-domain-names = "ife0",
+ "ife1",
+ "top";
+
+ vdd-csiphy-0p8-supply = <&csiphy_0p8_supply>;
+ vdd-csiphy-1p2-supply = <&csiphy_1p2_supply>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ csiphy_ep0: endpoint {
+ data-lanes = <0 1>;
+ remote-endpoint = <&sensor_ep>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/raspberrypi,pispbe.yaml b/Documentation/devicetree/bindings/media/raspberrypi,pispbe.yaml
new file mode 100644
index 000000000000..1fc62a1d8eda
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/raspberrypi,pispbe.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/raspberrypi,pispbe.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Raspberry Pi PiSP Image Signal Processor (ISP) Back End
+
+maintainers:
+ - Raspberry Pi Kernel Maintenance <kernel-list@raspberrypi.com>
+ - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+
+description: |
+ The Raspberry Pi PiSP Image Signal Processor (ISP) Back End is an image
+ processor that fetches images in Bayer or Grayscale format from DRAM memory
+ in tiles and produces images consumable by applications.
+
+ The full ISP documentation is available at
+ https://datasheets.raspberrypi.com/camera/raspberry-pi-image-signal-processor-specification.pdf
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm2712-pispbe
+ - const: raspberrypi,pispbe
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp@880000 {
+ compatible = "brcm,bcm2712-pispbe", "raspberrypi,pispbe";
+ reg = <0x10 0x00880000 0x0 0x4000>;
+ interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&firmware_clocks 7>;
+ iommus = <&iommu2>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/raspberrypi,rp1-cfe.yaml b/Documentation/devicetree/bindings/media/raspberrypi,rp1-cfe.yaml
new file mode 100644
index 000000000000..eba5394719b9
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/raspberrypi,rp1-cfe.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/raspberrypi,rp1-cfe.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Raspberry Pi PiSP Camera Front End
+
+maintainers:
+ - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+ - Raspberry Pi Kernel Maintenance <kernel-list@raspberrypi.com>
+
+description: |
+ The Raspberry Pi PiSP Camera Front End is a module in Raspberrypi 5's RP1 I/O
+ controller, that contains:
+ - MIPI D-PHY
+ - MIPI CSI-2 receiver
+ - Simple image processor (called PiSP Front End, or FE)
+
+ The FE documentation is available at:
+ https://datasheets.raspberrypi.com/camera/raspberry-pi-image-signal-processor-specification.pdf
+
+ The PHY and CSI-2 receiver part have no public documentation.
+
+properties:
+ compatible:
+ items:
+ - const: raspberrypi,rp1-cfe
+
+ reg:
+ items:
+ - description: CSI-2 registers
+ - description: D-PHY registers
+ - description: MIPI CFG (a simple top-level mux) registers
+ - description: FE registers
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+ description: CSI-2 RX Port
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ required:
+ - data-lanes
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ rp1 {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ csi@110000 {
+ compatible = "raspberrypi,rp1-cfe";
+ reg = <0xc0 0x40110000 0x0 0x100>,
+ <0xc0 0x40114000 0x0 0x100>,
+ <0xc0 0x40120000 0x0 0x100>,
+ <0xc0 0x40124000 0x0 0x1000>;
+
+ interrupts = <42>;
+
+ clocks = <&rp1_clocks>;
+
+ port {
+ csi_ep: endpoint {
+ remote-endpoint = <&cam_endpoint>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml
index d4c541c4b164..dedc5a4b81ec 100644
--- a/Documentation/devicetree/bindings/media/rc.yaml
+++ b/Documentation/devicetree/bindings/media/rc.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/rc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Generic Infrared Remote Controller Device Tree Bindings
+title: Generic Infrared Remote Controller
maintainers:
- Mauro Carvalho Chehab <mchehab@kernel.org>
@@ -12,13 +12,13 @@ maintainers:
properties:
$nodename:
- pattern: "^ir(@[a-f0-9]+)?$"
+ pattern: "^ir(-receiver)?(@[a-f0-9]+)?$"
linux,rc-map-name:
description:
Specifies the scancode/key mapping table defined in-kernel for
the remote controller.
- $ref: '/schemas/types.yaml#/definitions/string'
+ $ref: /schemas/types.yaml#/definitions/string
enum:
- rc-adstech-dvb-t-pci
- rc-alink-dtu-m
@@ -39,6 +39,7 @@ properties:
- rc-avertv-303
- rc-azurewave-ad-tu700
- rc-beelink-gs1
+ - rc-beelink-mxiii
- rc-behold
- rc-behold-columbus
- rc-budget-ci-old
@@ -55,6 +56,7 @@ properties:
- rc-dm1105-nec
- rc-dntv-live-dvb-t
- rc-dntv-live-dvbt-pro
+ - rc-dreambox
- rc-dtt200u
- rc-dvbsky
- rc-dvico-mce
@@ -101,6 +103,7 @@ properties:
- rc-msi-digivox-iii
- rc-msi-tvanywhere
- rc-msi-tvanywhere-plus
+ - rc-mygica-utv3
- rc-nebula
- rc-nec-terratec-cinergy-xs
- rc-norwood
diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.yaml b/Documentation/devicetree/bindings/media/renesas,ceu.yaml
index 50e0740af15a..d527fc42c3fd 100644
--- a/Documentation/devicetree/bindings/media/renesas,ceu.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,ceu.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/renesas,ceu.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Renesas Capture Engine Unit (CEU) Bindings
+title: Renesas Capture Engine Unit (CEU)
maintainers:
- Jacopo Mondi <jacopo+renesas@jmondi.org>
diff --git a/Documentation/devicetree/bindings/media/renesas,csi2.yaml b/Documentation/devicetree/bindings/media/renesas,csi2.yaml
index 23703b767f5b..80b77875874d 100644
--- a/Documentation/devicetree/bindings/media/renesas,csi2.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,csi2.yaml
@@ -30,6 +30,9 @@ properties:
- renesas,r8a77970-csi2 # R-Car V3M
- renesas,r8a77980-csi2 # R-Car V3H
- renesas,r8a77990-csi2 # R-Car E3
+ - renesas,r8a779a0-csi2 # R-Car V3U
+ - renesas,r8a779g0-csi2 # R-Car V4H
+ - renesas,r8a779h0-csi2 # R-Car V4M
reg:
maxItems: 1
@@ -66,7 +69,10 @@ properties:
maxItems: 1
data-lanes:
- maxItems: 1
+ minItems: 1
+ maxItems: 4
+ items:
+ maximum: 4
required:
- clock-lanes
diff --git a/Documentation/devicetree/bindings/media/renesas,drif.yaml b/Documentation/devicetree/bindings/media/renesas,drif.yaml
index 817a6d566738..9403b235e976 100644
--- a/Documentation/devicetree/bindings/media/renesas,drif.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,drif.yaml
@@ -96,7 +96,7 @@ properties:
Indicates that the channel acts as primary among the bonded channels.
port:
- $ref: /schemas/graph.yaml#/properties/port
+ $ref: /schemas/graph.yaml#/$defs/port-base
unevaluatedProperties: false
description:
Child port node corresponding to the data input. The port node must
@@ -242,7 +242,6 @@ examples:
power-domains = <&sysc R8A7795_PD_ALWAYS_ON>;
resets = <&cpg 513>;
renesas,bonding = <&drif11>;
- status = "disabled";
};
drif11: rif@e6f70000 {
diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.yaml b/Documentation/devicetree/bindings/media/renesas,fcp.yaml
index 43f2fed8cd33..cf92dfe69637 100644
--- a/Documentation/devicetree/bindings/media/renesas,fcp.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,fcp.yaml
@@ -21,15 +21,34 @@ description: |
properties:
compatible:
- enum:
- - renesas,fcpv # FCP for VSP
- - renesas,fcpf # FCP for FDP
+ oneOf:
+ - enum:
+ - renesas,fcpv # FCP for VSP
+ - renesas,fcpf # FCP for FDP
+ - items:
+ - enum:
+ - renesas,r9a07g043u-fcpvd # RZ/G2UL
+ - renesas,r9a07g044-fcpvd # RZ/G2{L,LC}
+ - renesas,r9a07g054-fcpvd # RZ/V2L
+ - renesas,r9a09g056-fcpvd # RZ/V2N
+ - renesas,r9a09g057-fcpvd # RZ/V2H(P)
+ - const: renesas,fcpv # Generic FCP for VSP fallback
reg:
maxItems: 1
clocks:
- maxItems: 1
+ minItems: 1
+ items:
+ - description: Main clock
+ - description: Register access clock
+ - description: Video clock
+
+ clock-names:
+ items:
+ - const: aclk
+ - const: pclk
+ - const: vclk
iommus:
maxItems: 1
@@ -49,6 +68,28 @@ required:
additionalProperties: false
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r9a07g043u-fcpvd
+ - renesas,r9a07g044-fcpvd
+ - renesas,r9a07g054-fcpvd
+ - renesas,r9a09g057-fcpvd
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ required:
+ - clock-names
+ else:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names: false
+
examples:
# R8A7795 (R-Car H3) FCP for VSP-D1
- |
diff --git a/Documentation/devicetree/bindings/media/renesas,imr.txt b/Documentation/devicetree/bindings/media/renesas,imr.txt
deleted file mode 100644
index b0614153ed36..000000000000
--- a/Documentation/devicetree/bindings/media/renesas,imr.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-Renesas R-Car Image Renderer (Distortion Correction Engine)
------------------------------------------------------------
-
-The image renderer, or the distortion correction engine, is a drawing processor
-with a simple instruction system capable of referencing video capture data or
-data in an external memory as 2D texture data and performing texture mapping
-and drawing with respect to any shape that is split into triangular objects.
-
-Required properties:
-
-- compatible: "renesas,<soctype>-imr-lx4", "renesas,imr-lx4" as a fallback for
- the image renderer light extended 4 (IMR-LX4) found in the R-Car gen3 SoCs,
- where the examples with <soctype> are:
- - "renesas,r8a7795-imr-lx4" for R-Car H3,
- - "renesas,r8a7796-imr-lx4" for R-Car M3-W.
-- reg: offset and length of the register block;
-- interrupts: single interrupt specifier;
-- clocks: single clock phandle/specifier pair;
-- power-domains: power domain phandle/specifier pair;
-- resets: reset phandle/specifier pair.
-
-Example:
-
- imr-lx4@fe860000 {
- compatible = "renesas,r8a7795-imr-lx4", "renesas,imr-lx4";
- reg = <0 0xfe860000 0 0x2000>;
- interrupts = <GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 823>;
- power-domains = <&sysc R8A7795_PD_A3VC>;
- resets = <&cpg 823>;
- };
diff --git a/Documentation/devicetree/bindings/media/renesas,imr.yaml b/Documentation/devicetree/bindings/media/renesas,imr.yaml
new file mode 100644
index 000000000000..512f57417fd8
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,imr.yaml
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,imr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas R-Car Image Renderer (Distortion Correction Engine)
+
+maintainers:
+ - Sergei Shtylyov <sergei.shtylyov@gmail.com>
+
+description: |
+ The image renderer, or the distortion correction engine, is a drawing
+ processor with a simple instruction system capable of referencing video
+ capture data or data in an external memory as 2D texture data and performing
+ texture mapping and drawing with respect to any shape that is split into
+ triangular objects.
+
+ The image renderer light extended 4 (IMR-LX4) is found in R-Car Gen3 SoCs.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - renesas,r8a7795-imr-lx4 # R-Car H3
+ - renesas,r8a7796-imr-lx4 # R-Car M3-W
+ - const: renesas,imr-lx4 # R-Car Gen3
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - power-domains
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r8a7795-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7795-sysc.h>
+
+ imr-lx4@fe860000 {
+ compatible = "renesas,r8a7795-imr-lx4", "renesas,imr-lx4";
+ reg = <0xfe860000 0x2000>;
+ interrupts = <GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 823>;
+ power-domains = <&sysc R8A7795_PD_A3VC>;
+ resets = <&cpg 823>;
+ };
diff --git a/Documentation/devicetree/bindings/media/renesas,isp.yaml b/Documentation/devicetree/bindings/media/renesas,isp.yaml
index 514857d36f6b..d25e020f5e5e 100644
--- a/Documentation/devicetree/bindings/media/renesas,isp.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,isp.yaml
@@ -21,20 +21,59 @@ properties:
items:
- enum:
- renesas,r8a779a0-isp # V3U
+ - renesas,r8a779g0-isp # V4H
+ - renesas,r8a779h0-isp # V4M
+ - const: renesas,rcar-gen4-isp # Generic R-Car Gen4
reg:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ reg-names:
+ minItems: 1
+ items:
+ - const: cs
+ - const: core
interrupts:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ interrupt-names:
+ minItems: 1
+ items:
+ - const: cs
+ - const: core
clocks:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: cs
+ - const: core
power-domains:
maxItems: 1
resets:
- maxItems: 1
+ minItems: 1
+ maxItems: 2
+
+ reset-names:
+ minItems: 1
+ items:
+ - const: cs
+ - const: core
+
+ renesas,vspx:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ A phandle to the companion VSPX responsible for the Streaming Bridge
+ functionality. The Streaming Bridge is responsible for feeding image
+ and configuration data to the ISP when operating in memory-to-memory
+ mode.
ports:
$ref: /schemas/graph.yaml#/properties/ports
@@ -100,10 +139,14 @@ properties:
required:
- compatible
- reg
+ - reg-names
- interrupts
+ - interrupt-names
- clocks
+ - clock-names
- power-domains
- resets
+ - reset-names
- ports
additionalProperties: false
@@ -115,12 +158,19 @@ examples:
#include <dt-bindings/power/r8a779a0-sysc.h>
isp1: isp@fed20000 {
- compatible = "renesas,r8a779a0-isp";
- reg = <0xfed20000 0x10000>;
- interrupts = <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&cpg CPG_MOD 613>;
+ compatible = "renesas,r8a779a0-isp", "renesas,rcar-gen4-isp";
+ reg = <0xfed20000 0x10000>, <0xfee00000 0x100000>;
+ reg-names = "cs", "core";
+ interrupts = <GIC_SPI 154 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "cs", "core";
+ clocks = <&cpg CPG_MOD 613>, <&cpg CPG_MOD 17>;
+ clock-names = "cs", "core";
power-domains = <&sysc R8A779A0_PD_A3ISP01>;
- resets = <&cpg 613>;
+ resets = <&cpg 613>, <&cpg 17>;
+ reset-names = "cs", "core";
+
+ renesas,vspx = <&vspx1>;
ports {
#address-cells = <1>;
diff --git a/Documentation/devicetree/bindings/media/renesas,jpu.txt b/Documentation/devicetree/bindings/media/renesas,jpu.txt
deleted file mode 100644
index d3436e5190f9..000000000000
--- a/Documentation/devicetree/bindings/media/renesas,jpu.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-* Renesas JPEG Processing Unit
-
-The JPEG processing unit (JPU) incorporates the JPEG codec with an encoding
-and decoding function conforming to the JPEG baseline process, so that the JPU
-can encode image data and decode JPEG data quickly.
-
-Required properties:
-- compatible: "renesas,jpu-<soctype>", "renesas,rcar-gen2-jpu" as fallback.
- Examples with soctypes are:
- - "renesas,jpu-r8a7790" for R-Car H2
- - "renesas,jpu-r8a7791" for R-Car M2-W
- - "renesas,jpu-r8a7792" for R-Car V2H
- - "renesas,jpu-r8a7793" for R-Car M2-N
-
- - reg: Base address and length of the registers block for the JPU.
- - interrupts: JPU interrupt specifier.
- - clocks: A phandle + clock-specifier pair for the JPU functional clock.
-
-Example: R8A7790 (R-Car H2) JPU node
- jpeg-codec@fe980000 {
- compatible = "renesas,jpu-r8a7790", "renesas,rcar-gen2-jpu";
- reg = <0 0xfe980000 0 0x10300>;
- interrupts = <0 272 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&mstp1_clks R8A7790_CLK_JPU>;
- };
diff --git a/Documentation/devicetree/bindings/media/renesas,jpu.yaml b/Documentation/devicetree/bindings/media/renesas,jpu.yaml
new file mode 100644
index 000000000000..2f55968e864f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,jpu.yaml
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,jpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas JPEG Processing Unit
+
+maintainers:
+ - Mikhail Ulyanov <mikhail.ulyanov@cogentembedded.com>
+
+description:
+ The JPEG processing unit (JPU) incorporates the JPEG codec with an encoding
+ and decoding function conforming to the JPEG baseline process, so that the
+ JPU can encode image data and decode JPEG data quickly.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - renesas,jpu-r8a7790 # R-Car H2
+ - renesas,jpu-r8a7791 # R-Car M2-W
+ - renesas,jpu-r8a7792 # R-Car V2H
+ - renesas,jpu-r8a7793 # R-Car M2-N
+ - const: renesas,rcar-gen2-jpu # R-Car Gen2
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - power-domains
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r8a7790-cpg-mssr.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/r8a7790-sysc.h>
+
+ jpeg-codec@fe980000 {
+ compatible = "renesas,jpu-r8a7790", "renesas,rcar-gen2-jpu";
+ reg = <0xfe980000 0x10300>;
+ interrupts = <GIC_SPI 272 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD 106>;
+ power-domains = <&sysc R8A7790_PD_ALWAYS_ON>;
+ resets = <&cpg 106>;
+ };
diff --git a/Documentation/devicetree/bindings/media/renesas,r9a09g057-ivc.yaml b/Documentation/devicetree/bindings/media/renesas,r9a09g057-ivc.yaml
new file mode 100644
index 000000000000..c09cbd8c9e35
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,r9a09g057-ivc.yaml
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,r9a09g057-ivc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/V2H(P) Input Video Control Block
+
+maintainers:
+ - Daniel Scally <dan.scally@ideasonboard.com>
+
+description:
+ The IVC block is a module that takes video frames from memory and feeds them
+ to the Image Signal Processor for processing.
+
+properties:
+ compatible:
+ const: renesas,r9a09g057-ivc # RZ/V2H(P)
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: Input Video Control block register access clock
+ - description: Video input data AXI bus clock
+ - description: ISP system clock
+
+ clock-names:
+ items:
+ - const: reg
+ - const: axi
+ - const: isp
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ items:
+ - description: Input Video Control block register access reset
+ - description: Video input data AXI bus reset
+ - description: ISP core reset
+
+ reset-names:
+ items:
+ - const: reg
+ - const: axi
+ - const: isp
+
+ port:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Output parallel video bus
+
+ properties:
+ endpoint:
+ $ref: /schemas/graph.yaml#/properties/endpoint
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+ - reset-names
+ - port
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/renesas,r9a09g057-cpg.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ isp-input@16040000 {
+ compatible = "renesas,r9a09g057-ivc";
+ reg = <0x16040000 0x230>;
+
+ clocks = <&cpg CPG_MOD 0xe3>,
+ <&cpg CPG_MOD 0xe4>,
+ <&cpg CPG_MOD 0xe5>;
+ clock-names = "reg", "axi", "isp";
+
+ power-domains = <&cpg>;
+
+ resets = <&cpg 0xd4>,
+ <&cpg 0xd1>,
+ <&cpg 0xd3>;
+ reset-names = "reg", "axi", "isp";
+
+ interrupts = <GIC_SPI 861 IRQ_TYPE_EDGE_RISING>;
+
+ port {
+ ivc_out: endpoint {
+ remote-endpoint = <&isp_in>;
+ };
+ };
+ };
+...
diff --git a/Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml b/Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml
new file mode 100644
index 000000000000..47e18690fa57
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,rzg2l-cru.yaml
@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (C) 2022 Renesas Electronics Corp.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,rzg2l-cru.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/G2L (and alike SoC's) Camera Data Receiving Unit (CRU) Image processing
+
+maintainers:
+ - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
+
+description:
+ The CRU image processing module is a data conversion module equipped with pixel
+ color space conversion, LUT, pixel format conversion, etc. An MIPI CSI-2 input and
+ parallel (including ITU-R BT.656) input are provided as the image sensor interface.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,r9a07g043-cru # RZ/G2UL
+ - renesas,r9a07g044-cru # RZ/G2{L,LC}
+ - renesas,r9a07g054-cru # RZ/V2L
+ - const: renesas,rzg2l-cru
+ - const: renesas,r9a09g047-cru # RZ/G3E
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ oneOf:
+ - items:
+ - description: CRU Interrupt for image_conv
+ - description: CRU Interrupt for image_conv_err
+ - description: CRU AXI master error interrupt
+ - items:
+ - description: CRU Interrupt for image_conv
+ - description: CRU AXI master error interrupt
+ - description: CRU Video Data AXI Master Address 0 Write End interrupt
+ - description: CRU Statistics data AXI master addr 0 write end interrupt
+ - description: CRU Video statistics data AXI master addr 0 write end interrupt
+
+ interrupt-names:
+ oneOf:
+ - items:
+ - const: image_conv
+ - const: image_conv_err
+ - const: axi_mst_err
+ - items:
+ - const: image_conv
+ - const: axi_mst_err
+ - const: vd_addr_wend
+ - const: sd_addr_wend
+ - const: vsd_addr_wend
+
+ clocks:
+ items:
+ - description: CRU Main clock
+ - description: CRU Register access clock
+ - description: CRU image transfer clock
+
+ clock-names:
+ items:
+ - const: video
+ - const: apb
+ - const: axi
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ items:
+ - description: CRU_PRESETN reset terminal
+ - description: CRU_ARESETN reset terminal
+
+ reset-names:
+ items:
+ - const: presetn
+ - const: aresetn
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing a parallel input source.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ hsync-active: true
+ vsync-active: true
+ bus-width: true
+ data-shift: true
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Input port node, describing the Image Processing module connected to the
+ CSI-2 receiver.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - power-domains
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r9a07g044-cru
+ - renesas,r9a07g054-cru
+ then:
+ properties:
+ interrupts:
+ maxItems: 3
+ interrupt-names:
+ maxItems: 3
+ ports:
+ required:
+ - port@0
+ - port@1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - renesas,r9a07g043-cru
+ then:
+ properties:
+ interrupts:
+ maxItems: 3
+ interrupt-names:
+ maxItems: 3
+ ports:
+ properties:
+ port@0: false
+ required:
+ - port@1
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a09g047-cru
+ then:
+ properties:
+ interrupts:
+ minItems: 5
+ interrupt-names:
+ minItems: 5
+ ports:
+ properties:
+ port@0: false
+ required:
+ - port@1
+
+additionalProperties: false
+
+examples:
+ # Device node example with CSI-2
+ - |
+ #include <dt-bindings/clock/r9a07g044-cpg.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ cru: video@10830000 {
+ compatible = "renesas,r9a07g044-cru", "renesas,rzg2l-cru";
+ reg = <0x10830000 0x400>;
+ interrupts = <GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 169 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "image_conv", "image_conv_err", "axi_mst_err";
+ clocks = <&cpg CPG_MOD R9A07G044_CRU_VCLK>,
+ <&cpg CPG_MOD R9A07G044_CRU_PCLK>,
+ <&cpg CPG_MOD R9A07G044_CRU_ACLK>;
+ clock-names = "video", "apb", "axi";
+ power-domains = <&cpg>;
+ resets = <&cpg R9A07G044_CRU_PRESETN>,
+ <&cpg R9A07G044_CRU_ARESETN>;
+ reset-names = "presetn", "aresetn";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <0>;
+
+ cru_parallel_in: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&ov5642>;
+ hsync-active = <1>;
+ vsync-active = <1>;
+ };
+ };
+
+ port@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ reg = <1>;
+
+ cru_csi_in: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&csi_cru_in>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml b/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml
new file mode 100644
index 000000000000..c5c511c9f0db
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml
@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright (C) 2022 Renesas Electronics Corp.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/renesas,rzg2l-csi2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/G2L (and alike SoC's) MIPI CSI-2 receiver
+
+maintainers:
+ - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
+
+description:
+ The CSI-2 receiver device provides MIPI CSI-2 capabilities for the Renesas RZ/G2L
+ (and alike SoCs). MIPI CSI-2 is part of the CRU block which is used in conjunction
+ with the Image Processing module, which provides the video capture capabilities.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - renesas,r9a07g043-csi2 # RZ/G2UL
+ - renesas,r9a07g044-csi2 # RZ/G2{L,LC}
+ - renesas,r9a07g054-csi2 # RZ/V2L
+ - const: renesas,rzg2l-csi2
+ - items:
+ - const: renesas,r9a09g047-csi2 # RZ/G3E
+ - const: renesas,r9a09g057-csi2
+ - const: renesas,r9a09g057-csi2 # RZ/V2H(P)
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ oneOf:
+ - items:
+ - description: Internal clock for connecting CRU and MIPI
+ - description: CRU Main clock
+ - description: CRU Register access clock
+ - items:
+ - description: CRU Main clock
+ - description: CRU Register access clock
+
+ clock-names:
+ oneOf:
+ - items:
+ - const: system
+ - const: video
+ - const: apb
+ - items:
+ - const: video
+ - const: apb
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ items:
+ - description: CRU_PRESETN reset terminal
+ - description: D-PHY reset (CRU_CMN_RSTB or CRU_n_S_RESETN)
+
+ reset-names:
+ items:
+ - const: presetn
+ - const: cmn-rstb
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node, single endpoint describing the CSI-2 transmitter.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+ items:
+ maximum: 4
+
+ required:
+ - clock-lanes
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Output port node, Image Processing block connected to the CSI-2 receiver.
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+ - reset-names
+ - ports
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a09g057-csi2
+ then:
+ properties:
+ clocks:
+ maxItems: 2
+ clock-names:
+ maxItems: 2
+ else:
+ properties:
+ clocks:
+ minItems: 3
+ clock-names:
+ minItems: 3
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/r9a07g044-cpg.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ csi: csi@10830400 {
+ compatible = "renesas,r9a07g044-csi2", "renesas,rzg2l-csi2";
+ reg = <0x10830400 0xfc00>;
+ interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cpg CPG_MOD R9A07G044_CRU_SYSCLK>,
+ <&cpg CPG_MOD R9A07G044_CRU_VCLK>,
+ <&cpg CPG_MOD R9A07G044_CRU_PCLK>;
+ clock-names = "system", "video", "apb";
+ power-domains = <&cpg>;
+ resets = <&cpg R9A07G044_CRU_PRESETN>,
+ <&cpg R9A07G044_CRU_CMN_RSTB>;
+ reset-names = "presetn", "cmn-rstb";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ csi2_in: endpoint {
+ clock-lanes = <0>;
+ data-lanes = <1 2>;
+ remote-endpoint = <&ov5645_ep>;
+ };
+ };
+
+ port@1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ reg = <1>;
+
+ csi2cru: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&crucsi2>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/renesas,vin.yaml b/Documentation/devicetree/bindings/media/renesas,vin.yaml
index c0442e79cbb4..cf54176f4fbd 100644
--- a/Documentation/devicetree/bindings/media/renesas,vin.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,vin.yaml
@@ -52,7 +52,12 @@ properties:
- renesas,vin-r8a77980 # R-Car V3H
- renesas,vin-r8a77990 # R-Car E3
- renesas,vin-r8a77995 # R-Car D3
+ - items:
+ - enum:
- renesas,vin-r8a779a0 # R-Car V3U
+ - renesas,vin-r8a779g0 # R-Car V4H
+ - renesas,vin-r8a779h0 # R-Car V4M
+ - const: renesas,rcar-gen4-vin # Generic R-Car Gen4
reg:
maxItems: 1
@@ -69,7 +74,7 @@ properties:
resets:
maxItems: 1
- #The per-board settings for Gen2 and RZ/G1 platforms:
+ # The per-board settings for Gen2 and RZ/G1 platforms:
port:
$ref: /schemas/graph.yaml#/$defs/port-base
unevaluatedProperties: false
@@ -94,7 +99,7 @@ properties:
synchronization is selected.
default: 1
- field-active-even: true
+ field-even-active: true
bus-width: true
@@ -108,7 +113,7 @@ properties:
data-active: true
- #The per-board settings for Gen3 and RZ/G2 platforms:
+ # The per-board settings for Gen3 and RZ/G2 platforms:
renesas,id:
description: VIN channel number
$ref: /schemas/types.yaml#/definitions/uint32
@@ -143,7 +148,7 @@ properties:
synchronization is selected.
default: 1
- field-active-even: true
+ field-even-active: true
bus-width: true
@@ -302,11 +307,11 @@ examples:
vin0csi20: endpoint@0 {
reg = <0>;
- remote-endpoint= <&csi20vin0>;
+ remote-endpoint = <&csi20vin0>;
};
vin0csi40: endpoint@2 {
reg = <2>;
- remote-endpoint= <&csi40vin0>;
+ remote-endpoint = <&csi40vin0>;
};
};
};
diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.yaml b/Documentation/devicetree/bindings/media/renesas,vsp1.yaml
index 990e9c1dbc43..07a97dd87a5b 100644
--- a/Documentation/devicetree/bindings/media/renesas,vsp1.yaml
+++ b/Documentation/devicetree/bindings/media/renesas,vsp1.yaml
@@ -16,9 +16,18 @@ description:
properties:
compatible:
- enum:
- - renesas,vsp1 # R-Car Gen2 and RZ/G1
- - renesas,vsp2 # R-Car Gen3 and RZ/G2
+ oneOf:
+ - enum:
+ - renesas,r9a07g044-vsp2 # RZ/G2L
+ - renesas,vsp1 # R-Car Gen2 and RZ/G1
+ - renesas,vsp2 # R-Car Gen3 and RZ/G2
+ - items:
+ - enum:
+ - renesas,r9a07g043u-vsp2 # RZ/G2UL
+ - renesas,r9a07g054-vsp2 # RZ/V2L
+ - renesas,r9a09g056-vsp2 # RZ/V2N
+ - renesas,r9a09g057-vsp2 # RZ/V2H(P)
+ - const: renesas,r9a07g044-vsp2 # RZ/G2L fallback
reg:
maxItems: 1
@@ -27,7 +36,17 @@ properties:
maxItems: 1
clocks:
- maxItems: 1
+ minItems: 1
+ items:
+ - description: Main clock
+ - description: Register access clock
+ - description: Video clock
+
+ clock-names:
+ items:
+ - const: aclk
+ - const: pclk
+ - const: vclk
power-domains:
maxItems: 1
@@ -50,17 +69,35 @@ required:
additionalProperties: false
-if:
- properties:
- compatible:
- items:
- - const: renesas,vsp1
-then:
- properties:
- renesas,fcp: false
-else:
- required:
- - renesas,fcp
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,vsp1
+ then:
+ properties:
+ renesas,fcp: false
+ else:
+ required:
+ - renesas,fcp
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: renesas,r9a07g044-vsp2
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ required:
+ - clock-names
+ else:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names: false
examples:
# R8A7790 (R-Car H2) VSP1-S
diff --git a/Documentation/devicetree/bindings/media/rockchip,px30-vip.yaml b/Documentation/devicetree/bindings/media/rockchip,px30-vip.yaml
new file mode 100644
index 000000000000..cc08ce94bef7
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/rockchip,px30-vip.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/rockchip,px30-vip.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rockchip PX30 Video Input Processor (VIP)
+
+maintainers:
+ - Mehdi Djait <mehdi.djait@linux.intel.com>
+ - Michael Riesch <michael.riesch@collabora.com>
+
+description:
+ The Rockchip PX30 Video Input Processor (VIP) receives the data from a camera
+ sensor or CCIR656 encoder and transfers it into system main memory by AXI bus.
+
+properties:
+ compatible:
+ const: rockchip,px30-vip
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: ACLK
+ - description: HCLK
+ - description: PCLK
+
+ clock-names:
+ items:
+ - const: aclk
+ - const: hclk
+ - const: pclk
+
+ resets:
+ items:
+ - description: AXI
+ - description: AHB
+ - description: PCLK IN
+
+ reset-names:
+ items:
+ - const: axi
+ - const: ahb
+ - const: pclkin
+
+ power-domains:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: input port on the parallel interface
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ enum:
+ - 5 # MEDIA_BUS_TYPE_PARALLEL
+ - 6 # MEDIA_BUS_TYPE_BT656
+
+ required:
+ - bus-type
+
+ required:
+ - port@0
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/px30-cru.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/media/video-interfaces.h>
+ #include <dt-bindings/power/px30-power.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ video-capture@ff490000 {
+ compatible = "rockchip,px30-vip";
+ reg = <0x0 0xff490000 0x0 0x200>;
+ interrupts = <GIC_SPI 69 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cru ACLK_CIF>, <&cru HCLK_CIF>, <&cru PCLK_CIF>;
+ clock-names = "aclk", "hclk", "pclk";
+ power-domains = <&power PX30_PD_VI>;
+ resets = <&cru SRST_CIF_A>, <&cru SRST_CIF_H>, <&cru SRST_CIF_PCLKIN>;
+ reset-names = "axi", "ahb", "pclkin";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+
+ cif_in: endpoint {
+ remote-endpoint = <&tw9900_out>;
+ bus-type = <MEDIA_BUS_TYPE_BT656>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/rockchip,rk3568-vepu.yaml b/Documentation/devicetree/bindings/media/rockchip,rk3568-vepu.yaml
new file mode 100644
index 000000000000..d246f5d38427
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/rockchip,rk3568-vepu.yaml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/rockchip,rk3568-vepu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Hantro G1 VPU encoders implemented on Rockchip SoCs
+
+maintainers:
+ - Nicolas Frattaroli <frattaroli.nicolas@gmail.com>
+
+description:
+ Hantro G1 video encode-only accelerators present on Rockchip SoCs.
+
+properties:
+ compatible:
+ enum:
+ - rockchip,rk3568-vepu
+ - rockchip,rk3588-vepu121
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: aclk
+ - const: hclk
+
+ power-domains:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/rk3568-cru.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/rk3568-power.h>
+
+ bus {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ vepu: video-codec@fdee0000 {
+ compatible = "rockchip,rk3568-vepu";
+ reg = <0x0 0xfdee0000 0x0 0x800>;
+ interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cru ACLK_JENC>, <&cru HCLK_JENC>;
+ clock-names = "aclk", "hclk";
+ iommus = <&vepu_mmu>;
+ power-domains = <&power RK3568_PD_RGA>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/rockchip,rk3568-vicap.yaml b/Documentation/devicetree/bindings/media/rockchip,rk3568-vicap.yaml
new file mode 100644
index 000000000000..18cd0a5a5318
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/rockchip,rk3568-vicap.yaml
@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/rockchip,rk3568-vicap.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Rockchip RK3568 Video Capture (VICAP)
+
+maintainers:
+ - Michael Riesch <michael.riesch@collabora.com>
+
+description:
+ The Rockchip RK3568 Video Capture (VICAP) block features a digital video
+ port (DVP, a parallel video interface) and a MIPI CSI-2 port. It receives
+ the data from camera sensors, video decoders, or other companion ICs and
+ transfers it into system main memory by AXI bus.
+
+properties:
+ compatible:
+ const: rockchip,rk3568-vicap
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: ACLK
+ - description: HCLK
+ - description: DCLK
+ - description: ICLK
+
+ clock-names:
+ items:
+ - const: aclk
+ - const: hclk
+ - const: dclk
+ - const: iclk
+
+ iommus:
+ maxItems: 1
+
+ resets:
+ items:
+ - description: ARST
+ - description: HRST
+ - description: DRST
+ - description: PRST
+ - description: IRST
+
+ reset-names:
+ items:
+ - const: arst
+ - const: hrst
+ - const: drst
+ - const: prst
+ - const: irst
+
+ rockchip,grf:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: Phandle to general register file used for video input block control.
+
+ power-domains:
+ maxItems: 1
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: The digital video port (DVP, a parallel video interface).
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ enum:
+ - 5 # MEDIA_BUS_TYPE_PARALLEL
+ - 6 # MEDIA_BUS_TYPE_BT656
+
+ rockchip,dvp-clk-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+ minimum: 0
+ maximum: 127
+ description:
+ Delay the DVP path clock input to align the sampling phase,
+ only valid in dual edge sampling mode. Delay is zero by
+ default and can be adjusted optionally.
+
+ required:
+ - bus-type
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Port connected to the MIPI CSI-2 receiver output.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/rk3568-cru.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/power/rk3568-power.h>
+ #include <dt-bindings/media/video-interfaces.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ vicap: video-capture@fdfe0000 {
+ compatible = "rockchip,rk3568-vicap";
+ reg = <0x0 0xfdfe0000 0x0 0x200>;
+ interrupts = <GIC_SPI 146 IRQ_TYPE_LEVEL_HIGH>;
+ assigned-clocks = <&cru DCLK_VICAP>;
+ assigned-clock-rates = <300000000>;
+ clocks = <&cru ACLK_VICAP>, <&cru HCLK_VICAP>,
+ <&cru DCLK_VICAP>, <&cru ICLK_VICAP_G>;
+ clock-names = "aclk", "hclk", "dclk", "iclk";
+ iommus = <&vicap_mmu>;
+ power-domains = <&power RK3568_PD_VI>;
+ resets = <&cru SRST_A_VICAP>, <&cru SRST_H_VICAP>,
+ <&cru SRST_D_VICAP>, <&cru SRST_P_VICAP>,
+ <&cru SRST_I_VICAP>;
+ reset-names = "arst", "hrst", "drst", "prst", "irst";
+ rockchip,grf = <&grf>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vicap_dvp: port@0 {
+ reg = <0>;
+
+ vicap_dvp_input: endpoint {
+ bus-type = <MEDIA_BUS_TYPE_BT656>;
+ bus-width = <16>;
+ pclk-sample = <MEDIA_PCLK_SAMPLE_DUAL_EDGE>;
+ remote-endpoint = <&it6801_output>;
+ };
+ };
+
+ vicap_mipi: port@1 {
+ reg = <1>;
+
+ vicap_mipi_input: endpoint {
+ remote-endpoint = <&csi_output>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/rockchip,vdec.yaml b/Documentation/devicetree/bindings/media/rockchip,vdec.yaml
index 089f11d21b25..809fda45b3bd 100644
--- a/Documentation/devicetree/bindings/media/rockchip,vdec.yaml
+++ b/Documentation/devicetree/bindings/media/rockchip,vdec.yaml
@@ -4,53 +4,95 @@
$id: http://devicetree.org/schemas/media/rockchip,vdec.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Rockchip Video Decoder (VDec) Device Tree Bindings
+title: Rockchip Video Decoder (VDec)
maintainers:
- Heiko Stuebner <heiko@sntech.de>
description: |-
- The Rockchip rk3399 has a stateless Video Decoder that can decodes H.264,
- HEVC an VP9 streams.
+ Rockchip SoCs have variants of the same stateless Video Decoder that can
+ decodes H.264, HEVC, VP9 and AV1 streams, depending on the variant.
properties:
compatible:
oneOf:
+ - const: rockchip,rk3288-vdec
- const: rockchip,rk3399-vdec
+ - const: rockchip,rk3576-vdec
+ - const: rockchip,rk3588-vdec
- items:
- - const: rockchip,rk3228-vdec
+ - enum:
+ - rockchip,rk3228-vdec
+ - rockchip,rk3328-vdec
- const: rockchip,rk3399-vdec
reg:
- maxItems: 1
+ minItems: 1
+ items:
+ - description: The function configuration registers base
+ - description: The link table configuration registers base
+ - description: The cache configuration registers base
+
+ reg-names:
+ items:
+ - const: function
+ - const: link
+ - const: cache
interrupts:
maxItems: 1
clocks:
+ minItems: 4
items:
- description: The Video Decoder AXI interface clock
- description: The Video Decoder AHB interface clock
- description: The Video Decoded CABAC clock
- description: The Video Decoder core clock
+ - description: The Video decoder HEVC CABAC clock
clock-names:
+ minItems: 4
items:
- const: axi
- const: ahb
- const: cabac
- const: core
+ - const: hevc_cabac
assigned-clocks: true
assigned-clock-rates: true
+ resets:
+ items:
+ - description: The Video Decoder AXI interface reset
+ - description: The Video Decoder AHB interface reset
+ - description: The Video Decoded CABAC reset
+ - description: The Video Decoder core reset
+ - description: The Video decoder HEVC CABAC reset
+
+ reset-names:
+ items:
+ - const: axi
+ - const: ahb
+ - const: cabac
+ - const: core
+ - const: hevc_cabac
+
power-domains:
maxItems: 1
iommus:
maxItems: 1
+ sram:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description: |
+ phandle to a reserved on-chip SRAM regions.
+ Some SoCs, like rk3588 provide on-chip SRAM to store temporary
+ buffers during decoding.
+
required:
- compatible
- reg
@@ -59,6 +101,41 @@ required:
- clock-names
- power-domains
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - rockchip,rk3576-vdec
+ - rockchip,rk3588-vdec
+ then:
+ properties:
+ reg:
+ minItems: 3
+ reg-names:
+ minItems: 3
+ clocks:
+ minItems: 5
+ clock-names:
+ minItems: 5
+ resets:
+ minItems: 5
+ reset-names:
+ minItems: 5
+ else:
+ properties:
+ reg:
+ maxItems: 1
+ reg-names: false
+ clocks:
+ maxItems: 4
+ clock-names:
+ maxItems: 4
+ resets: false
+ reset-names: false
+ sram: false
+
additionalProperties: false
examples:
diff --git a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml
index a6b1eff879ed..477c21417e75 100644
--- a/Documentation/devicetree/bindings/media/rockchip-isp1.yaml
+++ b/Documentation/devicetree/bindings/media/rockchip-isp1.yaml
@@ -15,21 +15,31 @@ description: |
properties:
compatible:
- const: rockchip,rk3399-cif-isp
+ enum:
+ - fsl,imx8mp-isp
+ - rockchip,px30-cif-isp
+ - rockchip,rk3399-cif-isp
reg:
maxItems: 1
interrupts:
- maxItems: 1
+ minItems: 1
+ maxItems: 3
+
+ interrupt-names:
+ items:
+ - const: isp
+ - const: mi
+ - const: mipi
clocks:
minItems: 3
items:
# isp0 and isp1
- - description: ISP clock
- - description: ISP AXI clock
- - description: ISP AHB clock
+ - description: ISP clock (for imx8mp, clk)
+ - description: ISP AXI clock (for imx8mp, m_hclk)
+ - description: ISP AHB clock (for imx8mp, hclk)
# only for isp1
- description: ISP Pixel clock
@@ -41,7 +51,14 @@ properties:
- const: aclk
- const: hclk
# only for isp1
- - const: pclk_isp
+ - const: pclk
+
+ fsl,blk-ctrl:
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ maxItems: 1
+ description:
+ A phandle to the media block control for the ISP, followed by a cell
+ containing the index of the gasket.
iommus:
maxItems: 1
@@ -54,7 +71,16 @@ properties:
const: dphy
power-domains:
- maxItems: 1
+ minItems: 1
+ items:
+ - description: ISP power domain
+ - description: MIPI CSI-2 power domain
+
+ power-domain-names:
+ minItems: 1
+ items:
+ - const: isp
+ - const: csi2
ports:
$ref: /schemas/graph.yaml#/properties/ports
@@ -75,8 +101,28 @@ properties:
minItems: 1
maxItems: 4
- required:
- - port@0
+ port@1:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: connection point for input on the parallel interface
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ enum: [5, 6]
+
+ required:
+ - bus-type
+
+ anyOf:
+ - required:
+ - port@0
+ - required:
+ - port@1
required:
- compatible
@@ -84,25 +130,64 @@ required:
- interrupts
- clocks
- clock-names
- - iommus
- - phys
- - phy-names
- power-domains
- ports
-if:
- properties:
- compatible:
- contains:
- const: rockchip,rk3399-cif-isp
-then:
- properties:
- clocks:
- minItems: 3
- maxItems: 4
- clock-names:
- minItems: 3
- maxItems: 4
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: rockchip,rk3399-cif-isp
+ then:
+ properties:
+ clocks:
+ minItems: 3
+ maxItems: 4
+ clock-names:
+ minItems: 3
+ maxItems: 4
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: rockchip,px30-cif-isp
+ then:
+ required:
+ - interrupt-names
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: fsl,imx8mp-isp
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ clock-names:
+ minItems: 4
+ iommus: false
+ phys: false
+ phy-names: false
+ power-domains:
+ minItems: 2
+ power-domain-names:
+ minItems: 2
+ required:
+ - fsl,blk-ctrl
+ - power-domain-names
+ else:
+ properties:
+ fsl,blk-ctrl: false
+ power-domains:
+ maxItems: 1
+ power-domain-names: false
+ required:
+ - iommus
+ - phys
+ - phy-names
additionalProperties: false
@@ -161,6 +246,7 @@ examples:
wcam: camera@36 {
compatible = "ovti,ov5695";
reg = <0x36>;
+ clocks = <&cru SCLK_TESTCLKOUT1>;
port {
wcam_out: endpoint {
@@ -174,12 +260,82 @@ examples:
compatible = "ovti,ov2685";
reg = <0x3c>;
- port {
- ucam_out: endpoint {
- remote-endpoint = <&mipi_in_ucam>;
- data-lanes = <1>;
- };
- };
+ clocks = <&cru SCLK_TESTCLKOUT1>;
+ clock-names = "xvclk";
+
+ avdd-supply = <&pp2800_cam>;
+ dovdd-supply = <&pp1800>;
+ dvdd-supply = <&pp1800>;
+
+ port {
+ ucam_out: endpoint {
+ remote-endpoint = <&mipi_in_ucam>;
+ data-lanes = <1>;
+ };
+ };
+ };
+ };
+ };
+
+ - |
+
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/px30-power.h>
+
+ parent1: parent {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ isp: isp@ff4a0000 {
+ compatible = "rockchip,px30-cif-isp";
+ reg = <0x0 0xff4a0000 0x0 0x8000>;
+ interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "isp", "mi", "mipi";
+ clocks = <&cru SCLK_ISP0>,
+ <&cru ACLK_ISP0_WRAPPER>,
+ <&cru HCLK_ISP0_WRAPPER>,
+ <&cru PCLK_ISP1_WRAPPER>;
+ clock-names = "isp", "aclk", "hclk", "pclk";
+ iommus = <&isp_mmu>;
+ phys = <&csi_dphy>;
+ phy-names = "dphy";
+ power-domains = <&power PX30_PD_VI>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ port@0 {
+ reg = <0>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ mipi_in_ucam1: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&ucam1_out>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+ };
+
+ i2c2: i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ov5695: camera@36 {
+ compatible = "ovti,ov5647";
+ reg = <0x36>;
+ clocks = <&cru SCLK_CIF_OUT>;
+
+ port {
+ ucam1_out: endpoint {
+ remote-endpoint = <&mipi_in_ucam1>;
+ data-lanes = <1 2>;
+ };
+ };
};
};
};
diff --git a/Documentation/devicetree/bindings/media/rockchip-rga.yaml b/Documentation/devicetree/bindings/media/rockchip-rga.yaml
index dd645ddccb07..ac17cda65191 100644
--- a/Documentation/devicetree/bindings/media/rockchip-rga.yaml
+++ b/Documentation/devicetree/bindings/media/rockchip-rga.yaml
@@ -21,7 +21,10 @@ properties:
- const: rockchip,rk3288-rga
- const: rockchip,rk3399-rga
- items:
- - const: rockchip,rk3228-rga
+ - enum:
+ - rockchip,rk3228-rga
+ - rockchip,rk3568-rga
+ - rockchip,rk3588-rga
- const: rockchip,rk3288-rga
reg:
diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml
index b88172a59de7..8c2501634080 100644
--- a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml
+++ b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml
@@ -1,9 +1,8 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
-
%YAML 1.2
---
-$id: "http://devicetree.org/schemas/media/rockchip-vpu.yaml#"
-$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+$id: http://devicetree.org/schemas/media/rockchip-vpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Hantro G1 VPU codecs implemented on Rockchip SoCs
@@ -22,12 +21,20 @@ properties:
- rockchip,rk3288-vpu
- rockchip,rk3328-vpu
- rockchip,rk3399-vpu
+ - rockchip,px30-vpu
+ - rockchip,rk3568-vpu
+ - rockchip,rk3588-av1-vpu
- items:
- - const: rockchip,rk3188-vpu
+ - enum:
+ - rockchip,rk3128-vpu
+ - rockchip,rk3188-vpu
- const: rockchip,rk3066-vpu
- items:
- const: rockchip,rk3228-vpu
- const: rockchip,rk3399-vpu
+ - items:
+ - const: rockchip,rk3588-vpu121
+ - const: rockchip,rk3568-vpu
reg:
maxItems: 1
@@ -65,6 +72,13 @@ properties:
iommus:
maxItems: 1
+ resets:
+ items:
+ - description: AXI reset line
+ - description: AXI bus interface unit reset line
+ - description: APB reset line
+ - description: APB bus interface unit reset line
+
required:
- compatible
- reg
@@ -77,18 +91,18 @@ additionalProperties: false
examples:
- |
- #include <dt-bindings/clock/rk3288-cru.h>
- #include <dt-bindings/interrupt-controller/arm-gic.h>
- #include <dt-bindings/power/rk3288-power.h>
-
- vpu: video-codec@ff9a0000 {
- compatible = "rockchip,rk3288-vpu";
- reg = <0xff9a0000 0x800>;
- interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>,
- <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>;
- interrupt-names = "vepu", "vdpu";
- clocks = <&cru ACLK_VCODEC>, <&cru HCLK_VCODEC>;
- clock-names = "aclk", "hclk";
- power-domains = <&power RK3288_PD_VIDEO>;
- iommus = <&vpu_mmu>;
- };
+ #include <dt-bindings/clock/rk3288-cru.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/power/rk3288-power.h>
+
+ video-codec@ff9a0000 {
+ compatible = "rockchip,rk3288-vpu";
+ reg = <0xff9a0000 0x800>;
+ interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>;
+ interrupt-names = "vepu", "vdpu";
+ clocks = <&cru ACLK_VCODEC>, <&cru HCLK_VCODEC>;
+ clock-names = "aclk", "hclk";
+ power-domains = <&power RK3288_PD_VIDEO>;
+ iommus = <&vpu_mmu>;
+ };
diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt
deleted file mode 100644
index e847291d4aff..000000000000
--- a/Documentation/devicetree/bindings/media/s5p-cec.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-* Samsung HDMI CEC driver
-
-The HDMI CEC module is present is Samsung SoCs and its purpose is to
-handle communication between HDMI connected devices over the CEC bus.
-
-Required properties:
- - compatible : value should be following
- "samsung,s5p-cec"
-
- - reg : Physical base address of the IP registers and length of memory
- mapped region.
-
- - interrupts : HDMI CEC interrupt number to the CPU.
- - clocks : from common clock binding: handle to HDMI CEC clock.
- - clock-names : from common clock binding: must contain "hdmicec",
- corresponding to entry in the clocks property.
- - samsung,syscon-phandle - phandle to the PMU system controller
- - hdmi-phandle - phandle to the HDMI controller, see also cec.txt.
-
-Optional:
- - needs-hpd : if present the CEC support is only available when the HPD
- is high. See cec.txt for more details.
-
-Example:
-
-hdmicec: cec@100b0000 {
- compatible = "samsung,s5p-cec";
- reg = <0x100B0000 0x200>;
- interrupts = <0 114 0>;
- clocks = <&clock CLK_HDMI_CEC>;
- clock-names = "hdmicec";
- samsung,syscon-phandle = <&pmu_system_controller>;
- hdmi-phandle = <&hdmi>;
- pinctrl-names = "default";
- pinctrl-0 = <&hdmi_cec>;
-};
diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt
deleted file mode 100644
index aa54c8159d9f..000000000000
--- a/Documentation/devicetree/bindings/media/s5p-mfc.txt
+++ /dev/null
@@ -1,76 +0,0 @@
-* Samsung Multi Format Codec (MFC)
-
-Multi Format Codec (MFC) is the IP present in Samsung SoCs which
-supports high resolution decoding and encoding functionalities.
-The MFC device driver is a v4l2 driver which can encode/decode
-video raw/elementary streams and has support for all popular
-video codecs.
-
-Required properties:
- - compatible : value should be either one among the following
- (a) "samsung,mfc-v5" for MFC v5 present in Exynos4 SoCs
- (b) "samsung,mfc-v6" for MFC v6 present in Exynos5 SoCs
- (c) "samsung,mfc-v7" for MFC v7 present in Exynos5420 SoC
- (d) "samsung,mfc-v8" for MFC v8 present in Exynos5800 SoC
- (e) "samsung,exynos5433-mfc" for MFC v8 present in Exynos5433 SoC
- (f) "samsung,mfc-v10" for MFC v10 present in Exynos7880 SoC
-
- - reg : Physical base address of the IP registers and length of memory
- mapped region.
-
- - interrupts : MFC interrupt number to the CPU.
- - clocks : from common clock binding: handle to mfc clock.
- - clock-names : from common clock binding: must contain "mfc",
- corresponding to entry in the clocks property.
-
-Optional properties:
- - power-domains : power-domain property defined with a phandle
- to respective power domain.
- - memory-region : from reserved memory binding: phandles to two reserved
- memory regions, first is for "left" mfc memory bus interfaces,
- second if for the "right" mfc memory bus, used when no SYSMMU
- support is available; used only by MFC v5 present in Exynos4 SoCs
-
-Obsolete properties:
- - samsung,mfc-r, samsung,mfc-l : support removed, please use memory-region
- property instead
-
-
-Example:
-SoC specific DT entry:
-
-mfc: codec@13400000 {
- compatible = "samsung,mfc-v5";
- reg = <0x13400000 0x10000>;
- interrupts = <0 94 0>;
- power-domains = <&pd_mfc>;
- clocks = <&clock 273>;
- clock-names = "mfc";
-};
-
-Reserved memory specific DT entry for given board (see reserved memory binding
-for more information):
-
-reserved-memory {
- #address-cells = <1>;
- #size-cells = <1>;
- ranges;
-
- mfc_left: region@51000000 {
- compatible = "shared-dma-pool";
- no-map;
- reg = <0x51000000 0x800000>;
- };
-
- mfc_right: region@43000000 {
- compatible = "shared-dma-pool";
- no-map;
- reg = <0x43000000 0x800000>;
- };
-};
-
-Board specific DT entry:
-
-codec@13400000 {
- memory-region = <&mfc_left>, <&mfc_right>;
-};
diff --git a/Documentation/devicetree/bindings/media/samsung,exynos4210-csis.yaml b/Documentation/devicetree/bindings/media/samsung,exynos4210-csis.yaml
new file mode 100644
index 000000000000..2ddca4167b0b
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,exynos4210-csis.yaml
@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,exynos4210-csis.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5P/Exynos SoC series MIPI CSI-2 receiver (MIPI CSIS)
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+properties:
+ compatible:
+ enum:
+ - samsung,s5pv210-csis
+ - samsung,exynos4210-csis
+ - samsung,exynos4212-csis
+ - samsung,exynos5250-csis
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 0
+
+ bus-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [2, 4]
+ description:
+ Number of data lines supported.
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: csis
+ - const: sclk_csis
+
+ clock-frequency:
+ default: 166000000
+ description:
+ The IP's main (system bus) clock frequency in Hz.
+
+ interrupts:
+ maxItems: 1
+
+ phys:
+ maxItems: 1
+
+ phy-names:
+ items:
+ - const: csis
+
+ power-domains:
+ maxItems: 1
+
+ vddio-supply:
+ description: MIPI CSIS I/O and PLL voltage supply (e.g. 1.8V).
+
+ vddcore-supply:
+ description: MIPI CSIS Core voltage supply (e.g. 1.1V).
+
+patternProperties:
+ "^port@[34]$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+ description:
+ Camera input port.
+
+ properties:
+ reg:
+ enum: [3, 4]
+
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ maxItems: 4
+
+ samsung,csis-hs-settle:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: Differential receiver (HS-RX) settle time.
+
+ samsung,csis-wclk:
+ type: boolean
+ description:
+ CSI-2 wrapper clock selection. If this property is present external clock
+ from CMU will be used, or the bus clock if it's not specified.
+
+ required:
+ - data-lanes
+
+ required:
+ - reg
+
+required:
+ - compatible
+ - reg
+ - bus-width
+ - clocks
+ - clock-names
+ - interrupts
+ - vddio-supply
+ - vddcore-supply
+
+anyOf:
+ - required:
+ - port@3
+ - required:
+ - port@4
+
+allOf:
+ - if:
+ required:
+ - samsung,isp-wb
+ then:
+ required:
+ - samsung,sysreg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ csis@11890000 {
+ compatible = "samsung,exynos4210-csis";
+ reg = <0x11890000 0x4000>;
+ clocks = <&clock CLK_CSIS1>,
+ <&clock CLK_SCLK_CSIS1>;
+ clock-names = "csis", "sclk_csis";
+ assigned-clocks = <&clock CLK_MOUT_CSIS1>,
+ <&clock CLK_SCLK_CSIS1>;
+ assigned-clock-parents = <&clock CLK_MOUT_MPLL_USER_T>;
+ assigned-clock-rates = <0>, <176000000>;
+
+ interrupts = <GIC_SPI 80 IRQ_TYPE_LEVEL_HIGH>;
+
+ bus-width = <2>;
+ power-domains = <&pd_cam>;
+ phys = <&mipi_phy 2>;
+ phy-names = "csis";
+
+ vddcore-supply = <&ldo8_reg>;
+ vddio-supply = <&ldo10_reg>;
+
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ /* Camera D (4) MIPI CSI-2 (CSIS1) */
+ port@4 {
+ reg = <4>;
+
+ endpoint {
+ remote-endpoint = <&is_s5k6a3_ep>;
+ data-lanes = <1>;
+ samsung,csis-hs-settle = <18>;
+ samsung,csis-wclk;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,exynos4210-fimc.yaml b/Documentation/devicetree/bindings/media/samsung,exynos4210-fimc.yaml
new file mode 100644
index 000000000000..17ece4eb300c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,exynos4210-fimc.yaml
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,exynos4210-fimc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5P/Exynos SoC Fully Integrated Mobile Camera
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+description:
+ Each FIMC device should have an alias in the aliases node, in the form of
+ fimc<n>, where <n> is an integer specifying the IP block instance.
+
+properties:
+ compatible:
+ enum:
+ - samsung,exynos4210-fimc
+ - samsung,exynos4212-fimc
+ - samsung,s5pv210-fimc
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: fimc
+ - const: sclk_fimc
+
+ clock-frequency:
+ description:
+ Maximum FIMC local clock (LCLK) frequency.
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ samsung,cam-if:
+ type: boolean
+ description:
+ The FIMC IP block includes the camera input interface.
+
+ samsung,isp-wb:
+ type: boolean
+ description: |
+ The FIMC IP block has the ISP writeback input.
+
+ samsung,lcd-wb:
+ type: boolean
+ description: |
+ The FIMC IP block has the LCD writeback input.
+
+ samsung,mainscaler-ext:
+ type: boolean
+ description:
+ FIMC IP supports extended image size and has CIEXTEN register.
+
+ samsung,min-pix-alignment:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ items:
+ - description: Minimum supported image height alignment.
+ - description: Horizontal image offset.
+ description:
+ The values are in pixels and default is <2 1>.
+
+ samsung,min-pix-sizes:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 2
+ description: |
+ An array specifying minimum image size in pixels at the FIMC input and
+ output DMA, in the first and second cell respectively. Default value
+ is <16 16>.
+
+ samsung,pix-limits:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ maxItems: 4
+ description: |
+ An array of maximum supported image sizes in pixels, for details refer to
+ Table 2-1 in the S5PV210 SoC User Manual. The meaning of each cell is as
+ follows:
+ 0 - scaler input horizontal size
+ 1 - input horizontal size for the scaler bypassed
+ 2 - REAL_WIDTH without input rotation
+ 3 - REAL_HEIGHT with input rotation
+
+ samsung,rotators:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0x11
+ description: |
+ A bitmask specifying whether this IP has the input and the output
+ rotator. Bits 4 and 0 correspond to input and output rotator
+ respectively. If a rotator is present its corresponding bit should be
+ set.
+
+ samsung,sysreg:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ System Registers (SYSREG) node.
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - samsung,pix-limits
+
+allOf:
+ - if:
+ required:
+ - samsung,isp-wb
+ then:
+ required:
+ - samsung,sysreg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ fimc@11800000 {
+ compatible = "samsung,exynos4212-fimc";
+ reg = <0x11800000 0x1000>;
+ clocks = <&clock CLK_FIMC0>,
+ <&clock CLK_SCLK_FIMC0>;
+ clock-names = "fimc", "sclk_fimc";
+ interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>;
+ iommus = <&sysmmu_fimc0>;
+ power-domains = <&pd_cam>;
+ samsung,sysreg = <&sys_reg>;
+
+ samsung,pix-limits = <4224 8192 1920 4224>;
+ samsung,mainscaler-ext;
+ samsung,isp-wb;
+ samsung,cam-if;
+
+ assigned-clocks = <&clock CLK_MOUT_FIMC0>,
+ <&clock CLK_SCLK_FIMC0>;
+ assigned-clock-parents = <&clock CLK_MOUT_MPLL_USER_T>;
+ assigned-clock-rates = <0>, <176000000>;
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml b/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml
new file mode 100644
index 000000000000..c8894358c46c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml
@@ -0,0 +1,225 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,exynos4212-fimc-is.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos4212/4412 SoC Imaging Subsystem (FIMC-IS)
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+description:
+ The FIMC-IS is a subsystem for processing image signal from an image sensor.
+ The Exynos4x12 SoC series FIMC-IS V1.5 comprises of a dedicated ARM Cortex-A5
+ processor, ISP, DRC and FD IP blocks and peripheral devices such as UART, I2C
+ and SPI bus controllers, PWM and ADC.
+
+properties:
+ compatible:
+ enum:
+ - samsung,exynos4212-fimc-is
+
+ reg:
+ maxItems: 1
+
+ ranges: true
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ clocks:
+ maxItems: 21
+
+ clock-names:
+ items:
+ - const: lite0
+ - const: lite1
+ - const: ppmuispx
+ - const: ppmuispmx
+ - const: isp
+ - const: drc
+ - const: fd
+ - const: mcuisp
+ - const: gicisp
+ - const: mcuctl_isp
+ - const: pwm_isp
+ - const: ispdiv0
+ - const: ispdiv1
+ - const: mcuispdiv0
+ - const: mcuispdiv1
+ - const: mpll
+ - const: aclk200
+ - const: aclk400mcuisp
+ - const: div_aclk200
+ - const: div_aclk400mcuisp
+ - const: uart
+
+ interrupts:
+ maxItems: 2
+
+ iommus:
+ maxItems: 4
+
+ iommu-names:
+ items:
+ - const: isp
+ - const: drc
+ - const: fd
+ - const: mcuctl
+
+ power-domains:
+ maxItems: 1
+
+ samsung,pmu-syscon:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Power Management Unit (PMU) system controller interface, used to
+ power/start the ISP.
+
+patternProperties:
+ "^pmu@[0-9a-f]+$":
+ type: object
+ additionalProperties: false
+ deprecated: true
+ description:
+ Node representing the SoC's Power Management Unit (duplicated with the
+ correct PMU node in the SoC). Deprecated, use samsung,pmu-syscon.
+
+ properties:
+ reg:
+ maxItems: 1
+
+ required:
+ - reg
+
+ "^i2c-isp@[0-9a-f]+$":
+ type: object
+ $ref: /schemas/i2c/i2c-controller.yaml#
+ unevaluatedProperties: false
+ description:
+ ISP I2C bus controller
+
+ properties:
+ compatible:
+ const: samsung,exynos4212-i2c-isp
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: i2c_isp
+
+ pinctrl-0: true
+ pinctrl-names:
+ items:
+ - const: default
+
+ required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+
+required:
+ - compatible
+ - reg
+ - '#address-cells'
+ - clocks
+ - clock-names
+ - interrupts
+ - ranges
+ - samsung,pmu-syscon
+ - '#size-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ fimc-is@12000000 {
+ compatible = "samsung,exynos4212-fimc-is";
+ reg = <0x12000000 0x260000>;
+ interrupts = <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&isp_clock CLK_ISP_FIMC_LITE0>,
+ <&isp_clock CLK_ISP_FIMC_LITE1>,
+ <&isp_clock CLK_ISP_PPMUISPX>,
+ <&isp_clock CLK_ISP_PPMUISPMX>,
+ <&isp_clock CLK_ISP_FIMC_ISP>,
+ <&isp_clock CLK_ISP_FIMC_DRC>,
+ <&isp_clock CLK_ISP_FIMC_FD>,
+ <&isp_clock CLK_ISP_MCUISP>,
+ <&isp_clock CLK_ISP_GICISP>,
+ <&isp_clock CLK_ISP_MCUCTL_ISP>,
+ <&isp_clock CLK_ISP_PWM_ISP>,
+ <&isp_clock CLK_ISP_DIV_ISP0>,
+ <&isp_clock CLK_ISP_DIV_ISP1>,
+ <&isp_clock CLK_ISP_DIV_MCUISP0>,
+ <&isp_clock CLK_ISP_DIV_MCUISP1>,
+ <&clock CLK_MOUT_MPLL_USER_T>,
+ <&clock CLK_ACLK200>,
+ <&clock CLK_ACLK400_MCUISP>,
+ <&clock CLK_DIV_ACLK200>,
+ <&clock CLK_DIV_ACLK400_MCUISP>,
+ <&clock CLK_UART_ISP_SCLK>;
+ clock-names = "lite0", "lite1", "ppmuispx",
+ "ppmuispmx", "isp",
+ "drc", "fd", "mcuisp",
+ "gicisp", "mcuctl_isp", "pwm_isp",
+ "ispdiv0", "ispdiv1", "mcuispdiv0",
+ "mcuispdiv1", "mpll", "aclk200",
+ "aclk400mcuisp", "div_aclk200",
+ "div_aclk400mcuisp", "uart";
+ iommus = <&sysmmu_fimc_isp>, <&sysmmu_fimc_drc>,
+ <&sysmmu_fimc_fd>, <&sysmmu_fimc_mcuctl>;
+ iommu-names = "isp", "drc", "fd", "mcuctl";
+ power-domains = <&pd_isp>;
+ samsung,pmu-syscon = <&pmu_system_controller>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ i2c-isp@12140000 {
+ compatible = "samsung,exynos4212-i2c-isp";
+ reg = <0x12140000 0x100>;
+ clocks = <&isp_clock CLK_ISP_I2C1_ISP>;
+ clock-names = "i2c_isp";
+ pinctrl-0 = <&fimc_is_i2c1>;
+ pinctrl-names = "default";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ image-sensor@10 {
+ compatible = "samsung,s5k6a3";
+ reg = <0x10>;
+ svdda-supply = <&cam_io_reg>;
+ svddio-supply = <&ldo19_reg>;
+ afvdd-supply = <&ldo19_reg>;
+ clocks = <&camera 1>;
+ clock-names = "extclk";
+ assigned-clocks = <&camera 1>;
+ assigned-clock-rates = <24000000>;
+ gpios = <&gpm1 6 GPIO_ACTIVE_LOW>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&csis1_ep>;
+ data-lanes = <1>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-lite.yaml b/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-lite.yaml
new file mode 100644
index 000000000000..bda724897293
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-lite.yaml
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,exynos4212-fimc-lite.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos SoC series camera host interface (FIMC-LITE)
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+description:
+ Each FIMC device should have an alias in the aliases node, in the form of
+ fimc-lite<n>, where <n> is an integer specifying the IP block instance.
+
+properties:
+ compatible:
+ enum:
+ - samsung,exynos4212-fimc-lite
+ - samsung,exynos5250-fimc-lite
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: flite
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ fimc-lite@12390000 {
+ compatible = "samsung,exynos4212-fimc-lite";
+ reg = <0x12390000 0x1000>;
+ clocks = <&isp_clock CLK_ISP_FIMC_LITE0>;
+ clock-names = "flite";
+ interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&pd_isp>;
+ iommus = <&sysmmu_fimc_lite0>;
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,exynos5250-gsc.yaml b/Documentation/devicetree/bindings/media/samsung,exynos5250-gsc.yaml
new file mode 100644
index 000000000000..878397830a4d
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,exynos5250-gsc.yaml
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,exynos5250-gsc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos SoC G-Scaler
+
+maintainers:
+ - Inki Dae <inki.dae@samsung.com>
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Seung-Woo Kim <sw0312.kim@samsung.com
+
+description:
+ G-Scaler is used for scaling and color space conversion on Samsung Exynos
+ SoCs.
+
+ Each G-Scaler node should have a numbered alias in the aliases node, in the
+ form of gscN, N = 0...3.
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - samsung,exynos5250-gsc
+ - samsung,exynos5420-gsc
+ - const: samsung,exynos5-gsc
+ - enum:
+ - samsung,exynos5433-gsc
+ - const: samsung,exynos5-gsc
+ deprecated: True
+
+ clocks:
+ minItems: 1
+ maxItems: 5
+
+ clock-names:
+ minItems: 1
+ maxItems: 5
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+ samsung,sysreg:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ Syscon used to control the system registers to set writeback input and destination.
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - interrupts
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,exynos5-gsc
+ - samsung,exynos5250-gsc
+ - samsung,exynos5420-gsc
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ items:
+ - const: gscl
+ else:
+ properties:
+ clocks:
+ minItems: 5
+ clock-names:
+ items:
+ - const: pclk
+ - const: aclk
+ - const: aclk_xiu
+ - const: aclk_gsclbend
+ - const: gsd
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos5250.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ video-scaler@13e00000 {
+ compatible = "samsung,exynos5250-gsc", "samsung,exynos5-gsc";
+ reg = <0x13e00000 0x1000>;
+ interrupts = <GIC_SPI 85 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&pd_gsc>;
+ clocks = <&clock CLK_GSCL0>;
+ clock-names = "gscl";
+ iommus = <&sysmmu_gsc0>;
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,fimc.yaml b/Documentation/devicetree/bindings/media/samsung,fimc.yaml
new file mode 100644
index 000000000000..1bfba84f8854
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,fimc.yaml
@@ -0,0 +1,278 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,fimc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5P/Exynos SoC Camera Subsystem (FIMC)
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+description: |
+ The S5P/Exynos SoC Camera subsystem comprises of multiple sub-devices
+ represented by separate device tree nodes. Currently this includes: Fully
+ Integrated Mobile Camera (FIMC, in the S5P SoCs series known as CAMIF), MIPI
+ CSIS, FIMC-LITE and FIMC-IS (ISP).
+
+properties:
+ compatible:
+ const: samsung,fimc
+
+ ranges: true
+
+ '#address-cells':
+ const: 1
+
+ '#size-cells':
+ const: 1
+
+ '#clock-cells':
+ const: 1
+ description: |
+ The clock specifier cell stores an index of a clock: 0, 1 for
+ CAM_A_CLKOUT, CAM_B_CLKOUT clocks respectively.
+
+ clocks:
+ minItems: 2
+ maxItems: 4
+
+ clock-names:
+ minItems: 2
+ items:
+ - const: sclk_cam0
+ - const: sclk_cam1
+ - const: pxl_async0
+ - const: pxl_async1
+
+ clock-output-names:
+ maxItems: 2
+
+ parallel-ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+ description:
+ Active parallel video input ports.
+
+ patternProperties:
+ "^port@[01]$":
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Camera A and camera B inputs.
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ pinctrl-names:
+ minItems: 1
+ items:
+ - const: default
+ - const: idle
+ - const: active_a
+ - const: active_b
+
+patternProperties:
+ "^csis@[0-9a-f]+$":
+ type: object
+ $ref: samsung,exynos4210-csis.yaml#
+ description: MIPI CSI-2 receiver.
+
+ "^fimc@[0-9a-f]+$":
+ type: object
+ $ref: samsung,exynos4210-fimc.yaml#
+ description: Fully Integrated Mobile Camera.
+
+ "^fimc-is@[0-9a-f]+$":
+ type: object
+ $ref: samsung,exynos4212-fimc-is.yaml#
+ description: Imaging Subsystem (FIMC-IS).
+
+ "^fimc-lite@[0-9a-f]+$":
+ type: object
+ $ref: samsung,exynos4212-fimc-lite.yaml#
+ description: Camera host interface (FIMC-LITE).
+
+required:
+ - compatible
+ - '#address-cells'
+ - '#clock-cells'
+ - clocks
+ - clock-names
+ - clock-output-names
+ - ranges
+ - '#size-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ camera@11800000 {
+ compatible = "samsung,fimc";
+ #clock-cells = <1>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges = <0x0 0x0 0xba1000>;
+
+ clocks = <&clock CLK_SCLK_CAM0>, <&clock CLK_SCLK_CAM1>,
+ <&clock CLK_PIXELASYNCM0>, <&clock CLK_PIXELASYNCM1>;
+ clock-names = "sclk_cam0", "sclk_cam1", "pxl_async0", "pxl_async1";
+ clock-output-names = "cam_a_clkout", "cam_b_clkout";
+
+ assigned-clocks = <&clock CLK_MOUT_CAM0>,
+ <&clock CLK_MOUT_CAM1>;
+ assigned-clock-parents = <&clock CLK_XUSBXTI>,
+ <&clock CLK_XUSBXTI>;
+
+ pinctrl-0 = <&cam_port_a_clk_active &cam_port_b_clk_active>;
+ pinctrl-names = "default";
+
+ fimc@0 {
+ compatible = "samsung,exynos4212-fimc";
+ reg = <0x00000000 0x1000>;
+ interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clock CLK_FIMC0>,
+ <&clock CLK_SCLK_FIMC0>;
+ clock-names = "fimc", "sclk_fimc";
+ power-domains = <&pd_cam>;
+ samsung,sysreg = <&sys_reg>;
+ iommus = <&sysmmu_fimc0>;
+
+ samsung,pix-limits = <4224 8192 1920 4224>;
+ samsung,mainscaler-ext;
+ samsung,isp-wb;
+ samsung,cam-if;
+ };
+
+ /* ... FIMC 1-3 */
+
+ csis@80000 {
+ compatible = "samsung,exynos4210-csis";
+ reg = <0x00080000 0x4000>;
+ interrupts = <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&clock CLK_CSIS0>,
+ <&clock CLK_SCLK_CSIS0>;
+ clock-names = "csis", "sclk_csis";
+ assigned-clocks = <&clock CLK_MOUT_CSIS0>,
+ <&clock CLK_SCLK_CSIS0>;
+ assigned-clock-parents = <&clock CLK_MOUT_MPLL_USER_T>;
+ assigned-clock-rates = <0>, <176000000>;
+
+ bus-width = <4>;
+ power-domains = <&pd_cam>;
+ phys = <&mipi_phy 0>;
+ phy-names = "csis";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ vddcore-supply = <&ldo8_reg>;
+ vddio-supply = <&ldo10_reg>;
+
+ /* Camera C (3) MIPI CSI-2 (CSIS0) */
+ port@3 {
+ reg = <3>;
+ endpoint {
+ remote-endpoint = <&s5c73m3_ep>;
+ data-lanes = <1 2 3 4>;
+ samsung,csis-hs-settle = <12>;
+ };
+ };
+ };
+
+ /* ... CSIS 1 */
+
+ fimc-lite@b90000 {
+ compatible = "samsung,exynos4212-fimc-lite";
+ reg = <0xb90000 0x1000>;
+ interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&pd_isp>;
+ clocks = <&isp_clock CLK_ISP_FIMC_LITE0>;
+ clock-names = "flite";
+ iommus = <&sysmmu_fimc_lite0>;
+ };
+
+ /* ... FIMC-LITE 1 */
+
+ fimc-is@800000 {
+ compatible = "samsung,exynos4212-fimc-is";
+ reg = <0x00800000 0x260000>;
+ interrupts = <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>,
+ <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&isp_clock CLK_ISP_FIMC_LITE0>,
+ <&isp_clock CLK_ISP_FIMC_LITE1>,
+ <&isp_clock CLK_ISP_PPMUISPX>,
+ <&isp_clock CLK_ISP_PPMUISPMX>,
+ <&isp_clock CLK_ISP_FIMC_ISP>,
+ <&isp_clock CLK_ISP_FIMC_DRC>,
+ <&isp_clock CLK_ISP_FIMC_FD>,
+ <&isp_clock CLK_ISP_MCUISP>,
+ <&isp_clock CLK_ISP_GICISP>,
+ <&isp_clock CLK_ISP_MCUCTL_ISP>,
+ <&isp_clock CLK_ISP_PWM_ISP>,
+ <&isp_clock CLK_ISP_DIV_ISP0>,
+ <&isp_clock CLK_ISP_DIV_ISP1>,
+ <&isp_clock CLK_ISP_DIV_MCUISP0>,
+ <&isp_clock CLK_ISP_DIV_MCUISP1>,
+ <&clock CLK_MOUT_MPLL_USER_T>,
+ <&clock CLK_ACLK200>,
+ <&clock CLK_ACLK400_MCUISP>,
+ <&clock CLK_DIV_ACLK200>,
+ <&clock CLK_DIV_ACLK400_MCUISP>,
+ <&clock CLK_UART_ISP_SCLK>;
+ clock-names = "lite0", "lite1", "ppmuispx",
+ "ppmuispmx", "isp",
+ "drc", "fd", "mcuisp",
+ "gicisp", "mcuctl_isp", "pwm_isp",
+ "ispdiv0", "ispdiv1", "mcuispdiv0",
+ "mcuispdiv1", "mpll", "aclk200",
+ "aclk400mcuisp", "div_aclk200",
+ "div_aclk400mcuisp", "uart";
+ iommus = <&sysmmu_fimc_isp>, <&sysmmu_fimc_drc>,
+ <&sysmmu_fimc_fd>, <&sysmmu_fimc_mcuctl>;
+ iommu-names = "isp", "drc", "fd", "mcuctl";
+ power-domains = <&pd_isp>;
+ samsung,pmu-syscon = <&pmu_system_controller>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ i2c-isp@940000 {
+ compatible = "samsung,exynos4212-i2c-isp";
+ reg = <0x00940000 0x100>;
+ clocks = <&isp_clock CLK_ISP_I2C1_ISP>;
+ clock-names = "i2c_isp";
+ pinctrl-0 = <&fimc_is_i2c1>;
+ pinctrl-names = "default";
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ image-sensor@10 {
+ compatible = "samsung,s5k6a3";
+ reg = <0x10>;
+ svdda-supply = <&cam_io_reg>;
+ svddio-supply = <&ldo19_reg>;
+ afvdd-supply = <&ldo19_reg>;
+ /* CAM_B_CLKOUT */
+ clocks = <&camera 1>;
+ clock-names = "extclk";
+ assigned-clocks = <&camera 1>;
+ assigned-clock-rates = <24000000>;
+ gpios = <&gpm1 6 GPIO_ACTIVE_LOW>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&csis1_ep>;
+ data-lanes = <1>;
+ };
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,s5c73m3.yaml b/Documentation/devicetree/bindings/media/samsung,s5c73m3.yaml
new file mode 100644
index 000000000000..1af5d7ac382c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,s5c73m3.yaml
@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,s5c73m3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5C73M3 8Mp camera ISP
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+
+description:
+ The S5C73M3 camera ISP supports MIPI CSI-2 and parallel (ITU-R BT.656)
+ video data busses. The I2C bus is the main control bus and additionally the
+ SPI bus is used, mostly for transferring the firmware to and from the
+ device. Two slave device nodes corresponding to these control bus
+ interfaces are required and should be placed under respective bus
+ controller nodes.
+
+properties:
+ compatible:
+ const: samsung,s5c73m3
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: cis_extclk
+
+ clock-frequency:
+ default: 24000000
+ description: cis_extclk clock frequency.
+
+ standby-gpios:
+ maxItems: 1
+ description: STANDBY pin.
+
+ vdda-supply:
+ description: Analog power supply (1.2V).
+
+ vdd-af-supply:
+ description: lens power supply (2.8V).
+
+ vddio-cis-supply:
+ description: CIS I/O power supply (1.2V to 1.8V).
+
+ vddio-host-supply:
+ description: Host I/O power supply (1.8V to 2.8V).
+
+ vdd-int-supply:
+ description: Digital power supply (1.2V).
+
+ vdd-reg-supply:
+ description: Regulator input power supply (2.8V).
+
+ xshutdown-gpios:
+ maxItems: 1
+ description: XSHUTDOWN pin.
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ additionalProperties: false
+
+ properties:
+ endpoint:
+ $ref: /schemas/media/video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ items:
+ - const: 1
+ - const: 2
+ - const: 3
+ - const: 4
+
+required:
+ - compatible
+ - reg
+
+allOf:
+ - $ref: /schemas/spi/spi-peripheral-props.yaml#
+ - if:
+ required:
+ - spi-max-frequency
+ then:
+ properties:
+ # The SPI node is simplified firmware-transfer interface only
+ clocks: false
+ clock-names: false
+ standby-gpios: false
+ vdda-supply: false
+ vdd-af-supply: false
+ vddio-cis-supply: false
+ vddio-host-supply: false
+ vdd-int-supply: false
+ vdd-reg-supply: false
+ xshutdown-gpios: false
+ port: false
+ else:
+ required:
+ - clocks
+ - clock-names
+ - standby-gpios
+ - vdda-supply
+ - vdd-af-supply
+ - vddio-cis-supply
+ - vddio-host-supply
+ - vdd-int-supply
+ - vdd-reg-supply
+ - xshutdown-gpios
+ - port
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ image-sensor@3c {
+ compatible = "samsung,s5c73m3";
+ reg = <0x3c>;
+ clock-frequency = <24000000>;
+ clocks = <&camera 0>;
+ clock-names = "cis_extclk";
+ standby-gpios = <&gpm0 6 GPIO_ACTIVE_LOW>;
+ vdda-supply = <&cam_vdda_reg>;
+ vdd-af-supply = <&cam_af_reg>;
+ vddio-cis-supply = <&ldo9_reg>;
+ vddio-host-supply = <&ldo18_reg>;
+ vdd-int-supply = <&buck9_reg>;
+ vdd-reg-supply = <&cam_io_reg>;
+ xshutdown-gpios = <&gpf1 3 GPIO_ACTIVE_LOW>; /* ISP_RESET */
+
+ port {
+ s5c73m3_ep: endpoint {
+ remote-endpoint = <&csis0_ep>;
+ data-lanes = <1 2 3 4>;
+ };
+ };
+ };
+ };
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ image-sensor@0 {
+ compatible = "samsung,s5c73m3";
+ reg = <0>;
+ spi-max-frequency = <50000000>;
+ controller-data {
+ samsung,spi-feedback-delay = <2>;
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,s5p-mfc.yaml b/Documentation/devicetree/bindings/media/samsung,s5p-mfc.yaml
new file mode 100644
index 000000000000..b46cc780703c
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,s5p-mfc.yaml
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,s5p-mfc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung Exynos Multi Format Codec (MFC)
+
+maintainers:
+ - Marek Szyprowski <m.szyprowski@samsung.com>
+ - Aakarsh Jain <aakarsh.jain@samsung.com>
+
+description:
+ Multi Format Codec (MFC) is the IP present in Samsung SoCs which
+ supports high resolution decoding and encoding functionalities.
+
+properties:
+ compatible:
+ oneOf:
+ - enum:
+ - samsung,exynos5433-mfc # Exynos5433
+ - samsung,mfc-v5 # Exynos4
+ - samsung,mfc-v6 # Exynos5
+ - samsung,mfc-v7 # Exynos5420
+ - samsung,mfc-v8 # Exynos5800
+ - samsung,mfc-v10 # Exynos7880
+ - tesla,fsd-mfc # Tesla FSD
+ - items:
+ - enum:
+ - samsung,exynos3250-mfc # Exynos3250
+ - const: samsung,mfc-v7 # Fall back for Exynos3250
+
+ reg:
+ maxItems: 1
+
+ clocks:
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ minItems: 1
+ maxItems: 3
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ minItems: 1
+ maxItems: 2
+
+ iommu-names:
+ minItems: 1
+ items:
+ - const: left
+ - const: right
+
+ power-domains:
+ maxItems: 1
+
+ memory-region:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+ - reg
+ - clocks
+ - clock-names
+ - interrupts
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,exynos3250-mfc
+ then:
+ properties:
+ clocks:
+ maxItems: 2
+ clock-names:
+ items:
+ - const: mfc
+ - const: sclk_mfc
+ iommus:
+ maxItems: 1
+ iommu-names: false
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,exynos5433-mfc
+ then:
+ properties:
+ clocks:
+ maxItems: 3
+ clock-names:
+ items:
+ - const: pclk
+ - const: aclk
+ - const: aclk_xiu
+ iommus:
+ minItems: 2
+ iommu-names:
+ minItems: 2
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,mfc-v5
+ then:
+ properties:
+ clocks:
+ maxItems: 2
+ clock-names:
+ items:
+ - const: mfc
+ - const: sclk_mfc
+ iommus:
+ minItems: 2
+ iommu-names:
+ minItems: 2
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,mfc-v6
+ - samsung,mfc-v8
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ items:
+ - const: mfc
+ iommus:
+ minItems: 2
+ iommu-names:
+ minItems: 2
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,mfc-v7
+ then:
+ properties:
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - tesla,fsd-mfc
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ items:
+ - const: mfc
+ iommus:
+ maxItems: 2
+ iommus-names: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos4.h>
+ #include <dt-bindings/clock/exynos-audss-clk.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ codec@13400000 {
+ compatible = "samsung,mfc-v5";
+ reg = <0x13400000 0x10000>;
+ interrupts = <GIC_SPI 94 IRQ_TYPE_LEVEL_HIGH>;
+ power-domains = <&pd_mfc>;
+ clocks = <&clock CLK_MFC>, <&clock CLK_SCLK_MFC>;
+ clock-names = "mfc", "sclk_mfc";
+ iommus = <&sysmmu_mfc_l>, <&sysmmu_mfc_r>;
+ iommu-names = "left", "right";
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung,s5pv210-jpeg.yaml b/Documentation/devicetree/bindings/media/samsung,s5pv210-jpeg.yaml
new file mode 100644
index 000000000000..5c969e764d4f
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/samsung,s5pv210-jpeg.yaml
@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/samsung,s5pv210-jpeg.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Samsung S5PV210 and Exynos SoC JPEG codec
+
+maintainers:
+ - Jacek Anaszewski <jacek.anaszewski@gmail.com>
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Sylwester Nawrocki <s.nawrocki@samsung.com>
+ - Andrzej Pietrasiewicz <andrzejtp2010@gmail.com>
+
+properties:
+ compatible:
+ enum:
+ - samsung,s5pv210-jpeg
+ - samsung,exynos3250-jpeg
+ - samsung,exynos4210-jpeg
+ - samsung,exynos4212-jpeg
+ - samsung,exynos5420-jpeg
+ - samsung,exynos5433-jpeg
+
+ clocks:
+ minItems: 1
+ maxItems: 4
+
+ clock-names:
+ minItems: 1
+ maxItems: 4
+
+ interrupts:
+ maxItems: 1
+
+ iommus:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ reg:
+ maxItems: 1
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+ - interrupts
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,s5pv210-jpeg
+ - samsung,exynos4210-jpeg
+ - samsung,exynos4212-jpeg
+ - samsung,exynos5420-jpeg
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+ clock-names:
+ items:
+ - const: jpeg
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,exynos3250-jpeg
+ then:
+ properties:
+ clocks:
+ minItems: 2
+ maxItems: 2
+ clock-names:
+ items:
+ - const: jpeg
+ - const: sclk
+
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - samsung,exynos5433-jpeg
+ then:
+ properties:
+ clocks:
+ minItems: 4
+ maxItems: 4
+ clock-names:
+ items:
+ - const: pclk
+ - const: aclk
+ - const: aclk_xiu
+ - const: sclk
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/exynos5433.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+ codec@15020000 {
+ compatible = "samsung,exynos5433-jpeg";
+ reg = <0x15020000 0x10000>;
+ interrupts = <GIC_SPI 411 IRQ_TYPE_LEVEL_HIGH>;
+ clock-names = "pclk", "aclk", "aclk_xiu", "sclk";
+ clocks = <&cmu_mscl CLK_PCLK_JPEG>,
+ <&cmu_mscl CLK_ACLK_JPEG>,
+ <&cmu_mscl CLK_ACLK_XIU_MSCLX>,
+ <&cmu_mscl CLK_SCLK_JPEG>;
+ iommus = <&sysmmu_jpeg>;
+ power-domains = <&pd_mscl>;
+ };
diff --git a/Documentation/devicetree/bindings/media/samsung-fimc.txt b/Documentation/devicetree/bindings/media/samsung-fimc.txt
deleted file mode 100644
index 20447529c985..000000000000
--- a/Documentation/devicetree/bindings/media/samsung-fimc.txt
+++ /dev/null
@@ -1,209 +0,0 @@
-Samsung S5P/Exynos SoC Camera Subsystem (FIMC)
-----------------------------------------------
-
-The S5P/Exynos SoC Camera subsystem comprises of multiple sub-devices
-represented by separate device tree nodes. Currently this includes: FIMC (in
-the S5P SoCs series known as CAMIF), MIPI CSIS, FIMC-LITE and FIMC-IS (ISP).
-
-The sub-subdevices are defined as child nodes of the common 'camera' node which
-also includes common properties of the whole subsystem not really specific to
-any single sub-device, like common camera port pins or the CAMCLK clock outputs
-for external image sensors attached to an SoC.
-
-Common 'camera' node
---------------------
-
-Required properties:
-
-- compatible: must be "samsung,fimc", "simple-bus"
-- clocks: list of clock specifiers, corresponding to entries in
- the clock-names property;
-- clock-names : must contain "sclk_cam0", "sclk_cam1", "pxl_async0",
- "pxl_async1" entries, matching entries in the clocks property.
-
-- #clock-cells: from the common clock bindings (../clock/clock-bindings.txt),
- must be 1. A clock provider is associated with the 'camera' node and it should
- be referenced by external sensors that use clocks provided by the SoC on
- CAM_*_CLKOUT pins. The clock specifier cell stores an index of a clock.
- The indices are 0, 1 for CAM_A_CLKOUT, CAM_B_CLKOUT clocks respectively.
-
-- clock-output-names: from the common clock bindings, should contain names of
- clocks registered by the camera subsystem corresponding to CAM_A_CLKOUT,
- CAM_B_CLKOUT output clocks respectively.
-
-The pinctrl bindings defined in ../pinctrl/pinctrl-bindings.txt must be used
-to define a required pinctrl state named "default" and optional pinctrl states:
-"idle", "active-a", active-b". These optional states can be used to switch the
-camera port pinmux at runtime. The "idle" state should configure both the camera
-ports A and B into high impedance state, especially the CAMCLK clock output
-should be inactive. For the "active-a" state the camera port A must be activated
-and the port B deactivated and for the state "active-b" it should be the other
-way around.
-
-The 'camera' node must include at least one 'fimc' child node.
-
-
-'fimc' device nodes
--------------------
-
-Required properties:
-
-- compatible: "samsung,s5pv210-fimc" for S5PV210, "samsung,exynos4210-fimc"
- for Exynos4210 and "samsung,exynos4212-fimc" for Exynos4x12 SoCs;
-- reg: physical base address and length of the registers set for the device;
-- interrupts: should contain FIMC interrupt;
-- clocks: list of clock specifiers, must contain an entry for each required
- entry in clock-names;
-- clock-names: must contain "fimc", "sclk_fimc" entries.
-- samsung,pix-limits: an array of maximum supported image sizes in pixels, for
- details refer to Table 2-1 in the S5PV210 SoC User Manual; The meaning of
- each cell is as follows:
- 0 - scaler input horizontal size,
- 1 - input horizontal size for the scaler bypassed,
- 2 - REAL_WIDTH without input rotation,
- 3 - REAL_HEIGHT with input rotation,
-- samsung,sysreg: a phandle to the SYSREG node.
-
-Each FIMC device should have an alias in the aliases node, in the form of
-fimc<n>, where <n> is an integer specifying the IP block instance.
-
-Optional properties:
-
-- clock-frequency: maximum FIMC local clock (LCLK) frequency;
-- samsung,min-pix-sizes: an array specyfing minimum image size in pixels at
- the FIMC input and output DMA, in the first and second cell respectively.
- Default value when this property is not present is <16 16>;
-- samsung,min-pix-alignment: minimum supported image height alignment (first
- cell) and the horizontal image offset (second cell). The values are in pixels
- and default to <2 1> when this property is not present;
-- samsung,mainscaler-ext: a boolean property indicating whether the FIMC IP
- supports extended image size and has CIEXTEN register;
-- samsung,rotators: a bitmask specifying whether this IP has the input and
- the output rotator. Bits 4 and 0 correspond to input and output rotator
- respectively. If a rotator is present its corresponding bit should be set.
- Default value when this property is not specified is 0x11.
-- samsung,cam-if: a bolean property indicating whether the IP block includes
- the camera input interface.
-- samsung,isp-wb: this property must be present if the IP block has the ISP
- writeback input.
-- samsung,lcd-wb: this property must be present if the IP block has the LCD
- writeback input.
-
-
-'parallel-ports' node
----------------------
-
-This node should contain child 'port' nodes specifying active parallel video
-input ports. It includes camera A and camera B inputs. 'reg' property in the
-port nodes specifies data input - 1, 2 indicates input A, B respectively.
-
-Optional properties
-
-- samsung,camclk-out (deprecated) : specifies clock output for remote sensor,
- 0 - CAM_A_CLKOUT, 1 - CAM_B_CLKOUT;
-
-Image sensor nodes
-------------------
-
-The sensor device nodes should be added to their control bus controller (e.g.
-I2C0) nodes and linked to a port node in the csis or the parallel-ports node,
-using the common video interfaces bindings, defined in video-interfaces.txt.
-
-Example:
-
- aliases {
- fimc0 = &fimc_0;
- };
-
- /* Parallel bus IF sensor */
- i2c_0: i2c@13860000 {
- s5k6aa: sensor@3c {
- compatible = "samsung,s5k6aafx";
- reg = <0x3c>;
- vddio-supply = <...>;
-
- clock-frequency = <24000000>;
- clocks = <&camera 1>;
- clock-names = "mclk";
-
- port {
- s5k6aa_ep: endpoint {
- remote-endpoint = <&fimc0_ep>;
- bus-width = <8>;
- hsync-active = <0>;
- vsync-active = <1>;
- pclk-sample = <1>;
- };
- };
- };
-
- /* MIPI CSI-2 bus IF sensor */
- s5c73m3: sensor@1a {
- compatible = "samsung,s5c73m3";
- reg = <0x1a>;
- vddio-supply = <...>;
-
- clock-frequency = <24000000>;
- clocks = <&camera 0>;
- clock-names = "mclk";
-
- port {
- s5c73m3_1: endpoint {
- data-lanes = <1 2 3 4>;
- remote-endpoint = <&csis0_ep>;
- };
- };
- };
- };
-
- camera {
- compatible = "samsung,fimc", "simple-bus";
- clocks = <&clock 132>, <&clock 133>, <&clock 351>,
- <&clock 352>;
- clock-names = "sclk_cam0", "sclk_cam1", "pxl_async0",
- "pxl_async1";
- #clock-cells = <1>;
- clock-output-names = "cam_a_clkout", "cam_b_clkout";
- pinctrl-names = "default";
- pinctrl-0 = <&cam_port_a_clk_active>;
- #address-cells = <1>;
- #size-cells = <1>;
-
- /* parallel camera ports */
- parallel-ports {
- /* camera A input */
- port@1 {
- reg = <1>;
- fimc0_ep: endpoint {
- remote-endpoint = <&s5k6aa_ep>;
- bus-width = <8>;
- hsync-active = <0>;
- vsync-active = <1>;
- pclk-sample = <1>;
- };
- };
- };
-
- fimc_0: fimc@11800000 {
- compatible = "samsung,exynos4210-fimc";
- reg = <0x11800000 0x1000>;
- interrupts = <0 85 0>;
- };
-
- csis_0: csis@11880000 {
- compatible = "samsung,exynos4210-csis";
- reg = <0x11880000 0x1000>;
- interrupts = <0 78 0>;
- /* camera C input */
- port@3 {
- reg = <3>;
- csis0_ep: endpoint {
- remote-endpoint = <&s5c73m3_ep>;
- data-lanes = <1 2 3 4>;
- samsung,csis-hs-settle = <12>;
- };
- };
- };
- };
-
-The MIPI-CSIS device binding is defined in samsung-mipi-csis.txt.
diff --git a/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt b/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt
deleted file mode 100644
index a4149c9434ea..000000000000
--- a/Documentation/devicetree/bindings/media/samsung-mipi-csis.txt
+++ /dev/null
@@ -1,81 +0,0 @@
-Samsung S5P/Exynos SoC series MIPI CSI-2 receiver (MIPI CSIS)
--------------------------------------------------------------
-
-Required properties:
-
-- compatible : "samsung,s5pv210-csis" for S5PV210 (S5PC110),
- "samsung,exynos4210-csis" for Exynos4210 (S5PC210),
- "samsung,exynos4212-csis" for Exynos4212/Exynos4412,
- "samsung,exynos5250-csis" for Exynos5250;
-- reg : offset and length of the register set for the device;
-- interrupts : should contain MIPI CSIS interrupt; the format of the
- interrupt specifier depends on the interrupt controller;
-- bus-width : maximum number of data lanes supported (SoC specific);
-- vddio-supply : MIPI CSIS I/O and PLL voltage supply (e.g. 1.8V);
-- vddcore-supply : MIPI CSIS Core voltage supply (e.g. 1.1V);
-- clocks : list of clock specifiers, corresponding to entries in
- clock-names property;
-- clock-names : must contain "csis", "sclk_csis" entries, matching entries
- in the clocks property.
-
-Optional properties:
-
-- clock-frequency : The IP's main (system bus) clock frequency in Hz, default
- value when this property is not specified is 166 MHz;
-- samsung,csis-wclk : CSI-2 wrapper clock selection. If this property is present
- external clock from CMU will be used, or the bus clock if
- if it's not specified.
-
-The device node should contain one 'port' child node with one child 'endpoint'
-node, according to the bindings defined in Documentation/devicetree/bindings/
-media/video-interfaces.txt. The following are properties specific to those nodes.
-
-port node
----------
-
-- reg : (required) must be 3 for camera C input (CSIS0) or 4 for
- camera D input (CSIS1);
-
-endpoint node
--------------
-
-- data-lanes : (required) an array specifying active physical MIPI-CSI2
- data input lanes and their mapping to logical lanes; the
- array's content is unused, only its length is meaningful;
-
-- samsung,csis-hs-settle : (optional) differential receiver (HS-RX) settle time;
-
-
-Example:
-
- reg0: regulator@0 {
- };
-
- reg1: regulator@1 {
- };
-
-/* SoC properties */
-
- csis_0: csis@11880000 {
- compatible = "samsung,exynos4210-csis";
- reg = <0x11880000 0x1000>;
- interrupts = <0 78 0>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
-
-/* Board properties */
-
- csis_0: csis@11880000 {
- clock-frequency = <166000000>;
- vddio-supply = <&reg0>;
- vddcore-supply = <&reg1>;
- port {
- reg = <3>; /* 3 - CSIS0, 4 - CSIS1 */
- csis0_ep: endpoint {
- remote-endpoint = <...>;
- data-lanes = <1>, <2>;
- samsung,csis-hs-settle = <12>;
- };
- };
- };
diff --git a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt
deleted file mode 100644
index 21f31fdf5543..000000000000
--- a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt
+++ /dev/null
@@ -1,97 +0,0 @@
-Samsung S5C73M3 8Mp camera ISP
-------------------------------
-
-The S5C73M3 camera ISP supports MIPI CSI-2 and parallel (ITU-R BT.656) video
-data busses. The I2C bus is the main control bus and additionally the SPI bus
-is used, mostly for transferring the firmware to and from the device. Two
-slave device nodes corresponding to these control bus interfaces are required
-and should be placed under respective bus controller nodes.
-
-I2C slave device node
----------------------
-
-Required properties:
-
-- compatible : "samsung,s5c73m3";
-- reg : I2C slave address of the sensor;
-- vdd-int-supply : digital power supply (1.2V);
-- vdda-supply : analog power supply (1.2V);
-- vdd-reg-supply : regulator input power supply (2.8V);
-- vddio-host-supply : host I/O power supply (1.8V to 2.8V);
-- vddio-cis-supply : CIS I/O power supply (1.2V to 1.8V);
-- vdd-af-supply : lens power supply (2.8V);
-- xshutdown-gpios : specifier of GPIO connected to the XSHUTDOWN pin;
-- standby-gpios : specifier of GPIO connected to the STANDBY pin;
-- clocks : should contain list of phandle and clock specifier pairs
- according to common clock bindings for the clocks described
- in the clock-names property;
-- clock-names : should contain "cis_extclk" entry for the CIS_EXTCLK clock;
-
-Optional properties:
-
-- clock-frequency : the frequency at which the "cis_extclk" clock should be
- configured to operate, in Hz; if this property is not
- specified default 24 MHz value will be used.
-
-The common video interfaces bindings (see video-interfaces.txt) should be used
-to specify link from the S5C73M3 to an external image data receiver. The S5C73M3
-device node should contain one 'port' child node with an 'endpoint' subnode for
-this purpose. The data link from a raw image sensor to the S5C73M3 can be
-similarly specified, but it is optional since the S5C73M3 ISP and a raw image
-sensor are usually inseparable and form a hybrid module.
-
-Following properties are valid for the endpoint node(s):
-
-endpoint subnode
-----------------
-
-- data-lanes : (optional) specifies MIPI CSI-2 data lanes as covered in
- video-interfaces.txt. This sensor doesn't support data lane remapping
- and physical lane indexes in subsequent elements of the array should
- be only consecutive ascending values.
-
-SPI device node
----------------
-
-Required properties:
-
-- compatible : "samsung,s5c73m3";
-
-For more details see description of the SPI busses bindings
-(../spi/spi-bus.txt) and bindings of a specific bus controller.
-
-Example:
-
-i2c@138a000000 {
- ...
- s5c73m3@3c {
- compatible = "samsung,s5c73m3";
- reg = <0x3c>;
- vdd-int-supply = <&buck9_reg>;
- vdda-supply = <&ldo17_reg>;
- vdd-reg-supply = <&cam_io_reg>;
- vddio-host-supply = <&ldo18_reg>;
- vddio-cis-supply = <&ldo9_reg>;
- vdd-af-supply = <&cam_af_reg>;
- clock-frequency = <24000000>;
- clocks = <&clk 0>;
- clock-names = "cis_extclk";
- reset-gpios = <&gpf1 3 1>;
- standby-gpios = <&gpm0 1 1>;
- port {
- s5c73m3_ep: endpoint {
- remote-endpoint = <&csis0_ep>;
- data-lanes = <1 2 3 4>;
- };
- };
- };
-};
-
-spi@1392000 {
- ...
- s5c73m3_spi: s5c73m3@0 {
- compatible = "samsung,s5c73m3";
- reg = <0>;
- ...
- };
-};
diff --git a/Documentation/devicetree/bindings/media/samsung-s5k5baf.txt b/Documentation/devicetree/bindings/media/samsung-s5k5baf.txt
deleted file mode 100644
index 1f51e0439c96..000000000000
--- a/Documentation/devicetree/bindings/media/samsung-s5k5baf.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-Samsung S5K5BAF UXGA 1/5" 2M CMOS Image Sensor with embedded SoC ISP
---------------------------------------------------------------------
-
-Required properties:
-
-- compatible : "samsung,s5k5baf";
-- reg : I2C slave address of the sensor;
-- vdda-supply : analog power supply 2.8V (2.6V to 3.0V);
-- vddreg-supply : regulator input power supply 1.8V (1.7V to 1.9V)
- or 2.8V (2.6V to 3.0);
-- vddio-supply : I/O power supply 1.8V (1.65V to 1.95V)
- or 2.8V (2.5V to 3.1V);
-- stbyn-gpios : GPIO connected to STDBYN pin;
-- rstn-gpios : GPIO connected to RSTN pin;
-- clocks : list of phandle and clock specifier pairs
- according to common clock bindings for the
- clocks described in clock-names;
-- clock-names : should include "mclk" for the sensor's master clock;
-
-Optional properties:
-
-- clock-frequency : the frequency at which the "mclk" clock should be
- configured to operate, in Hz; if this property is not
- specified default 24 MHz value will be used.
-
-The device node should contain one 'port' child node with one child 'endpoint'
-node, according to the bindings defined in Documentation/devicetree/bindings/
-media/video-interfaces.txt. The following are properties specific to those
-nodes.
-
-endpoint node
--------------
-
-- data-lanes : (optional) specifies MIPI CSI-2 data lanes as covered in
- video-interfaces.txt. If present it should be <1> - the device
- supports only one data lane without re-mapping.
-
-Example:
-
-s5k5bafx@2d {
- compatible = "samsung,s5k5baf";
- reg = <0x2d>;
- vdda-supply = <&cam_io_en_reg>;
- vddreg-supply = <&vt_core_15v_reg>;
- vddio-supply = <&vtcam_reg>;
- stbyn-gpios = <&gpl2 0 1>;
- rstn-gpios = <&gpl2 1 1>;
- clock-names = "mclk";
- clocks = <&clock_cam 0>;
- clock-frequency = <24000000>;
-
- port {
- s5k5bafx_ep: endpoint {
- remote-endpoint = <&csis1_ep>;
- data-lanes = <1>;
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/media/samsung-s5k6a3.txt b/Documentation/devicetree/bindings/media/samsung-s5k6a3.txt
deleted file mode 100644
index cce01e82f3e3..000000000000
--- a/Documentation/devicetree/bindings/media/samsung-s5k6a3.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-Samsung S5K6A3(YX) raw image sensor
----------------------------------
-
-S5K6A3(YX) is a raw image sensor with MIPI CSI-2 and CCP2 image data interfaces
-and CCI (I2C compatible) control bus.
-
-Required properties:
-
-- compatible : "samsung,s5k6a3";
-- reg : I2C slave address of the sensor;
-- svdda-supply : core voltage supply;
-- svddio-supply : I/O voltage supply;
-- afvdd-supply : AF (actuator) voltage supply;
-- gpios : specifier of a GPIO connected to the RESET pin;
-- clocks : should contain list of phandle and clock specifier pairs
- according to common clock bindings for the clocks described
- in the clock-names property;
-- clock-names : should contain "extclk" entry for the sensor's EXTCLK clock;
-
-Optional properties:
-
-- clock-frequency : the frequency at which the "extclk" clock should be
- configured to operate, in Hz; if this property is not
- specified default 24 MHz value will be used.
-
-The common video interfaces bindings (see video-interfaces.txt) should be
-used to specify link to the image data receiver. The S5K6A3(YX) device
-node should contain one 'port' child node with an 'endpoint' subnode.
-
-Following properties are valid for the endpoint node:
-
-- data-lanes : (optional) specifies MIPI CSI-2 data lanes as covered in
- video-interfaces.txt. The sensor supports only one data lane.
diff --git a/Documentation/devicetree/bindings/media/si470x.txt b/Documentation/devicetree/bindings/media/si470x.txt
deleted file mode 100644
index a9403558362e..000000000000
--- a/Documentation/devicetree/bindings/media/si470x.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-* Silicon Labs FM Radio receiver
-
-The Silicon Labs Si470x is family of FM radio receivers with receive power scan
-supporting 76-108 MHz, programmable through an I2C interface.
-Some of them includes an RDS encoder.
-
-Required Properties:
-- compatible: Should contain "silabs,si470x"
-- reg: the I2C address of the device
-
-Optional Properties:
-- interrupts : The interrupt number
-- reset-gpios: GPIO specifier for the chips reset line
-
-Example:
-
-&i2c2 {
- si470x@63 {
- compatible = "silabs,si470x";
- reg = <0x63>;
-
- interrupt-parent = <&gpj2>;
- interrupts = <4 IRQ_TYPE_EDGE_FALLING>;
- reset-gpios = <&gpj2 5 GPIO_ACTIVE_HIGH>;
- };
-};
diff --git a/Documentation/devicetree/bindings/media/silabs,si470x.yaml b/Documentation/devicetree/bindings/media/silabs,si470x.yaml
new file mode 100644
index 000000000000..db22b88fc5bb
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/silabs,si470x.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/silabs,si470x.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Silicon Labs Si470x FM Radio Receiver
+
+maintainers:
+ - Hans Verkuil <hverkuil@kernel.org>
+ - Paweł Chmiel <pawel.mikolaj.chmiel@gmail.com>
+
+properties:
+ compatible:
+ const: silabs,si470x
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ reset-gpios:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ i2c {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ fmradio@10 {
+ compatible = "silabs,si470x";
+ reg = <0x10>;
+ interrupt-parent = <&gpj2>;
+ interrupts = <4 IRQ_TYPE_EDGE_FALLING>;
+ reset-gpios = <&gpj2 5 GPIO_ACTIVE_HIGH>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/snps,dw-hdmi-rx.yaml b/Documentation/devicetree/bindings/media/snps,dw-hdmi-rx.yaml
new file mode 100644
index 000000000000..b7f6c87d0e06
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/snps,dw-hdmi-rx.yaml
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Device Tree bindings for Synopsys DesignWare HDMI RX Controller
+
+---
+$id: http://devicetree.org/schemas/media/snps,dw-hdmi-rx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Synopsys DesignWare HDMI RX Controller
+
+maintainers:
+ - Dmitry Osipenko <dmitry.osipenko@collabora.com>
+
+description:
+ Synopsys DesignWare HDMI Input Controller preset on RK3588 SoCs
+ allowing devices to receive and decode high-resolution video streams
+ from external sources like media players, cameras, laptops, etc.
+
+properties:
+ compatible:
+ items:
+ - const: rockchip,rk3588-hdmirx-ctrler
+ - const: snps,dw-hdmi-rx
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 3
+
+ interrupt-names:
+ items:
+ - const: cec
+ - const: hdmi
+ - const: dma
+
+ clocks:
+ maxItems: 7
+
+ clock-names:
+ items:
+ - const: aclk
+ - const: audio
+ - const: cr_para
+ - const: pclk
+ - const: ref
+ - const: hclk_s_hdmirx
+ - const: hclk_vo1
+
+ power-domains:
+ maxItems: 1
+
+ resets:
+ maxItems: 4
+
+ reset-names:
+ items:
+ - const: axi
+ - const: apb
+ - const: ref
+ - const: biu
+
+ memory-region:
+ maxItems: 1
+
+ hpd-gpios:
+ description: GPIO specifier for HPD.
+ maxItems: 1
+
+ rockchip,grf:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ The phandle of the syscon node for the general register file
+ containing HDMIRX PHY status bits.
+
+ rockchip,vo1-grf:
+ $ref: /schemas/types.yaml#/definitions/phandle
+ description:
+ The phandle of the syscon node for the Video Output GRF register
+ to enable EDID transfer through SDAIN and SCLIN.
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - clocks
+ - clock-names
+ - power-domains
+ - resets
+ - pinctrl-0
+ - hpd-gpios
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/rockchip,rk3588-cru.h>
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+ #include <dt-bindings/power/rk3588-power.h>
+ #include <dt-bindings/reset/rockchip,rk3588-cru.h>
+ hdmi_receiver: hdmi-receiver@fdee0000 {
+ compatible = "rockchip,rk3588-hdmirx-ctrler", "snps,dw-hdmi-rx";
+ reg = <0xfdee0000 0x6000>;
+ interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 178 IRQ_TYPE_LEVEL_HIGH 0>,
+ <GIC_SPI 179 IRQ_TYPE_LEVEL_HIGH 0>;
+ interrupt-names = "cec", "hdmi", "dma";
+ clocks = <&cru ACLK_HDMIRX>,
+ <&cru CLK_HDMIRX_AUD>,
+ <&cru CLK_CR_PARA>,
+ <&cru PCLK_HDMIRX>,
+ <&cru CLK_HDMIRX_REF>,
+ <&cru PCLK_S_HDMIRX>,
+ <&cru HCLK_VO1>;
+ clock-names = "aclk",
+ "audio",
+ "cr_para",
+ "pclk",
+ "ref",
+ "hclk_s_hdmirx",
+ "hclk_vo1";
+ power-domains = <&power RK3588_PD_VO1>;
+ resets = <&cru SRST_A_HDMIRX>, <&cru SRST_P_HDMIRX>,
+ <&cru SRST_HDMIRX_REF>, <&cru SRST_A_HDMIRX_BIU>;
+ reset-names = "axi", "apb", "ref", "biu";
+ memory-region = <&hdmi_receiver_cma>;
+ pinctrl-0 = <&hdmim1_rx_cec &hdmim1_rx_hpdin &hdmim1_rx_scl &hdmim1_rx_sda &hdmirx_5v_detection>;
+ pinctrl-names = "default";
+ hpd-gpios = <&gpio1 22 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml
index 41e1d0cd80e5..34147127192f 100644
--- a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml
+++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml
@@ -4,10 +4,10 @@
$id: http://devicetree.org/schemas/media/st,stm32-dcmi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: STMicroelectronics STM32 Digital Camera Memory Interface (DCMI) binding
+title: STMicroelectronics STM32 Digital Camera Memory Interface (DCMI)
maintainers:
- - Hugues Fruchet <hugues.fruchet@st.com>
+ - Hugues Fruchet <hugues.fruchet@foss.st.com>
properties:
compatible:
@@ -36,6 +36,10 @@ properties:
resets:
maxItems: 1
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
port:
$ref: /schemas/graph.yaml#/$defs/port-base
unevaluatedProperties: false
@@ -90,7 +94,9 @@ examples:
- |
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/clock/stm32mp1-clks.h>
+ #include <dt-bindings/media/video-interfaces.h>
#include <dt-bindings/reset/stm32mp1-resets.h>
+
dcmi: dcmi@4c006000 {
compatible = "st,stm32-dcmi";
reg = <0x4c006000 0x400>;
@@ -104,7 +110,7 @@ examples:
port {
dcmi_0: endpoint {
remote-endpoint = <&ov5640_0>;
- bus-type = <5>;
+ bus-type = <MEDIA_BUS_TYPE_PARALLEL>;
bus-width = <8>;
hsync-active = <0>;
vsync-active = <0>;
diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmipp.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmipp.yaml
new file mode 100644
index 000000000000..7b03a77adbce
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/st,stm32-dcmipp.yaml
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/st,stm32-dcmipp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STM32 DCMIPP Digital Camera Memory Interface Pixel Processor
+
+maintainers:
+ - Hugues Fruchet <hugues.fruchet@foss.st.com>
+ - Alain Volmat <alain.volmat@foss.st.com>
+
+properties:
+ compatible:
+ enum:
+ - st,stm32mp13-dcmipp
+ - st,stm32mp25-dcmipp
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ items:
+ - description: bus clock
+ - description: csi clock
+ minItems: 1
+
+ clock-names:
+ items:
+ - const: kclk
+ - const: mclk
+ minItems: 1
+
+ resets:
+ maxItems: 1
+
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
+ port:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ DCMIPP supports a single port node with parallel bus.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ enum: [4, 5, 6]
+ default: 5
+
+ bus-width:
+ enum: [8, 10, 12, 14]
+ default: 8
+
+ pclk-sample: true
+ hsync-active: true
+ vsync-active: true
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - resets
+ - port
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - st,stm32mp13-dcmipp
+ then:
+ properties:
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ maxItems: 1
+
+ port:
+ properties:
+ endpoint:
+ properties:
+ bus-type:
+ enum: [5, 6]
+ else:
+ properties:
+ clocks:
+ minItems: 2
+
+ clock-names:
+ minItems: 2
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/stm32mp13-clks.h>
+ #include <dt-bindings/reset/stm32mp13-resets.h>
+ dcmipp@5a000000 {
+ compatible = "st,stm32mp13-dcmipp";
+ reg = <0x5a000000 0x400>;
+ interrupts = <GIC_SPI 79 IRQ_TYPE_LEVEL_HIGH>;
+ resets = <&rcc DCMIPP_R>;
+ clocks = <&rcc DCMIPP_K>;
+
+ port {
+ endpoint {
+ remote-endpoint = <&mipid02_2>;
+ bus-width = <8>;
+ hsync-active = <0>;
+ vsync-active = <0>;
+ pclk-sample = <0>;
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml b/Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml
new file mode 100644
index 000000000000..b9f7d84f38c2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/st,stm32-dma2d.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/st,stm32-dma2d.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STM32 Chrom-Art Accelerator DMA2D
+
+description:
+ Chrom-ART Accelerator(DMA2D), graphical hardware accelerator
+ enabling enhanced graphical user interface with minimum CPU load
+
+ It can perform the following operations.
+
+ - Filling a part or the whole of a destination image with a specific color.
+ - Copying a part or the whole of a source image into a part or the whole of
+ a destination image.
+ - Copying a part or the whole of a source image into a part or the whole of
+ a destination image with a pixel format conversion.
+ - Blending a part and/or two complete source images with different pixel
+ format and copy the result into a part or the whole of a destination image
+ with a different color format. (TODO)
+
+maintainers:
+ - Dillon Min <dillon.minfei@gmail.com>
+
+properties:
+ compatible:
+ const: st,stm32-dma2d
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ clock-names:
+ items:
+ - const: dma2d
+
+ resets:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/stm32fx-clock.h>
+ #include <dt-bindings/mfd/stm32f4-rcc.h>
+ dma2d: dma2d@4002b000 {
+ compatible = "st,stm32-dma2d";
+ reg = <0x4002b000 0xc00>;
+ interrupts = <90>;
+ resets = <&rcc STM32F4_AHB1_RESET(DMA2D)>;
+ clocks = <&rcc 0 STM32F4_AHB1_CLOCK(DMA2D)>;
+ clock-names = "dma2d";
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/st,stm32mp25-csi.yaml b/Documentation/devicetree/bindings/media/st,stm32mp25-csi.yaml
new file mode 100644
index 000000000000..e9fa3cfea5d2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/st,stm32mp25-csi.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/st,stm32mp25-csi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STM32 CSI controller
+
+description:
+ The STM32 CSI controller, coupled with a D-PHY allows connecting a CSI-2
+ based camera to the DCMIPP camera pipeline.
+
+maintainers:
+ - Alain Volmat <alain.volmat@foss.st.com>
+
+properties:
+ compatible:
+ enum:
+ - st,stm32mp25-csi
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 3
+
+ clock-names:
+ items:
+ - const: pclk
+ - const: txesc
+ - const: csi2phy
+
+ resets:
+ maxItems: 1
+
+ vdd-supply:
+ description: Digital core power supply (0.91V)
+
+ vdda18-supply:
+ description: System analog power supply (1.8V)
+
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description:
+ Input port node
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ data-lanes:
+ minItems: 1
+ items:
+ - const: 1
+ - const: 2
+
+ required:
+ - data-lanes
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description:
+ Output port node
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+ - clock-names
+ - resets
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/st,stm32mp25-rcc.h>
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/media/video-interfaces.h>
+ #include <dt-bindings/reset/st,stm32mp25-rcc.h>
+ csi@48020000 {
+ compatible = "st,stm32mp25-csi";
+ reg = <0x48020000 0x2000>;
+ interrupts = <GIC_SPI 142 IRQ_TYPE_LEVEL_HIGH>;
+ resets = <&rcc CSI_R>;
+ clocks = <&rcc CK_KER_CSI>, <&rcc CK_KER_CSITXESC>, <&rcc CK_KER_CSIPHY>;
+ clock-names = "pclk", "txesc", "csi2phy";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ port@0 {
+ reg = <0>;
+ endpoint {
+ remote-endpoint = <&imx335_ep>;
+ data-lanes = <1 2>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ endpoint {
+ remote-endpoint = <&dcmipp_0>;
+ };
+ };
+ };
+ };
+
+...
diff --git a/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml b/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml
new file mode 100644
index 000000000000..73726c65cfb9
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/st,stm32mp25-video-codec.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: STMicroelectronics STM32MP25 VDEC video decoder & VENC video encoder
+
+maintainers:
+ - Hugues Fruchet <hugues.fruchet@foss.st.com>
+
+description:
+ The STMicroelectronics STM32MP25 SOCs embeds a VDEC video hardware
+ decoder peripheral based on Verisilicon VC8000NanoD IP (former Hantro G1)
+ and a VENC video hardware encoder peripheral based on Verisilicon
+ VC8000NanoE IP (former Hantro H1).
+
+properties:
+ compatible:
+ enum:
+ - st,stm32mp25-vdec
+ - st,stm32mp25-venc
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ clocks:
+ maxItems: 1
+
+ access-controllers:
+ minItems: 1
+ maxItems: 2
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - clocks
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ video-codec@580d0000 {
+ compatible = "st,stm32mp25-vdec";
+ reg = <0x580d0000 0x3c8>;
+ interrupts = <GIC_SPI 117 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&ck_icn_p_vdec>;
+ };
diff --git a/Documentation/devicetree/bindings/media/starfive,jh7110-camss.yaml b/Documentation/devicetree/bindings/media/starfive,jh7110-camss.yaml
new file mode 100644
index 000000000000..c66586d90fa2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/starfive,jh7110-camss.yaml
@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/starfive,jh7110-camss.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Starfive SoC CAMSS ISP
+
+maintainers:
+ - Jack Zhu <jack.zhu@starfivetech.com>
+ - Changhuang Liang <changhuang.liang@starfivetech.com>
+
+description:
+ The Starfive CAMSS ISP is a Camera interface for Starfive JH7110 SoC. It
+ consists of a VIN controller (Video In Controller, a top-level control unit)
+ and an ISP.
+
+properties:
+ compatible:
+ const: starfive,jh7110-camss
+
+ reg:
+ maxItems: 2
+
+ reg-names:
+ items:
+ - const: syscon
+ - const: isp
+
+ clocks:
+ maxItems: 7
+
+ clock-names:
+ items:
+ - const: apb_func
+ - const: wrapper_clk_c
+ - const: dvp_inv
+ - const: axiwr
+ - const: mipi_rx0_pxl
+ - const: ispcore_2x
+ - const: isp_axi
+
+ resets:
+ maxItems: 6
+
+ reset-names:
+ items:
+ - const: wrapper_p
+ - const: wrapper_c
+ - const: axird
+ - const: axiwr
+ - const: isp_top_n
+ - const: isp_top_axi
+
+ power-domains:
+ items:
+ - description: JH7110 ISP Power Domain Switch Controller.
+
+ interrupts:
+ maxItems: 4
+
+ ports:
+ $ref: /schemas/graph.yaml#/properties/ports
+
+ properties:
+ port@0:
+ $ref: /schemas/graph.yaml#/$defs/port-base
+ unevaluatedProperties: false
+ description: Input port for receiving DVP data.
+
+ properties:
+ endpoint:
+ $ref: video-interfaces.yaml#
+ unevaluatedProperties: false
+
+ properties:
+ bus-type:
+ enum: [5, 6]
+
+ bus-width:
+ enum: [8, 10, 12]
+
+ data-shift:
+ enum: [0, 2]
+ default: 0
+
+ hsync-active:
+ enum: [0, 1]
+ default: 1
+
+ vsync-active:
+ enum: [0, 1]
+ default: 1
+
+ required:
+ - bus-type
+ - bus-width
+
+ port@1:
+ $ref: /schemas/graph.yaml#/properties/port
+ description: Input port for receiving CSI data.
+
+ required:
+ - port@0
+ - port@1
+
+required:
+ - compatible
+ - reg
+ - reg-names
+ - clocks
+ - clock-names
+ - resets
+ - reset-names
+ - power-domains
+ - interrupts
+ - ports
+
+additionalProperties: false
+
+examples:
+ - |
+ isp@19840000 {
+ compatible = "starfive,jh7110-camss";
+ reg = <0x19840000 0x10000>,
+ <0x19870000 0x30000>;
+ reg-names = "syscon", "isp";
+ clocks = <&ispcrg 0>,
+ <&ispcrg 13>,
+ <&ispcrg 2>,
+ <&ispcrg 12>,
+ <&ispcrg 1>,
+ <&syscrg 51>,
+ <&syscrg 52>;
+ clock-names = "apb_func",
+ "wrapper_clk_c",
+ "dvp_inv",
+ "axiwr",
+ "mipi_rx0_pxl",
+ "ispcore_2x",
+ "isp_axi";
+ resets = <&ispcrg 0>,
+ <&ispcrg 1>,
+ <&ispcrg 10>,
+ <&ispcrg 11>,
+ <&syscrg 41>,
+ <&syscrg 42>;
+ reset-names = "wrapper_p",
+ "wrapper_c",
+ "axird",
+ "axiwr",
+ "isp_top_n",
+ "isp_top_axi";
+ power-domains = <&pwrc 5>;
+ interrupts = <92>, <87>, <88>, <90>;
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ port@0 {
+ reg = <0>;
+ vin_from_sc2235: endpoint {
+ remote-endpoint = <&sc2235_to_vin>;
+ bus-type = <5>;
+ bus-width = <8>;
+ data-shift = <2>;
+ hsync-active = <1>;
+ vsync-active = <0>;
+ pclk-sample = <1>;
+ };
+ };
+
+ port@1 {
+ reg = <1>;
+ vin_from_csi2rx: endpoint {
+ remote-endpoint = <&csi2rx_to_vin>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/stih-cec.txt b/Documentation/devicetree/bindings/media/stih-cec.txt
deleted file mode 100644
index ece0832fdeaf..000000000000
--- a/Documentation/devicetree/bindings/media/stih-cec.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-STMicroelectronics STIH4xx HDMI CEC driver
-
-Required properties:
- - compatible : value should be "st,stih-cec"
- - reg : Physical base address of the IP registers and length of memory
- mapped region.
- - clocks : from common clock binding: handle to HDMI CEC clock
- - interrupts : HDMI CEC interrupt number to the CPU.
- - pinctrl-names: Contains only one value - "default"
- - pinctrl-0: Specifies the pin control groups used for CEC hardware.
- - resets: Reference to a reset controller
- - hdmi-phandle: Phandle to the HDMI controller, see also cec.txt.
-
-Example for STIH407:
-
-sti-cec@94a087c {
- compatible = "st,stih-cec";
- reg = <0x94a087c 0x64>;
- clocks = <&clk_sysin>;
- clock-names = "cec-clk";
- interrupts = <GIC_SPI 140 IRQ_TYPE_NONE>;
- interrupt-names = "cec-irq";
- pinctrl-names = "default";
- pinctrl-0 = <&pinctrl_cec0_default>;
- resets = <&softreset STIH407_LPM_SOFTRESET>;
- hdmi-phandle = <&hdmi>;
-};
diff --git a/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt b/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt
deleted file mode 100644
index 880d4d70c9fd..000000000000
--- a/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-STMicroelectronics STi c8sectpfe binding
-============================================
-
-This document describes the c8sectpfe device bindings that is used to get transport
-stream data into the SoC on the TS pins, and into DDR for further processing.
-
-It is typically used in conjunction with one or more demodulator and tuner devices
-which converts from the RF to digital domain. Demodulators and tuners are usually
-located on an external DVB frontend card connected to SoC TS input pins.
-
-Currently 7 TS input (tsin) channels are supported on the stih407 family SoC.
-
-Required properties (controller (parent) node):
-- compatible : Should be "stih407-c8sectpfe"
-
-- reg : Address and length of register sets for each device in
- "reg-names"
-
-- reg-names : The names of the register addresses corresponding to the
- registers filled in "reg":
- - c8sectpfe: c8sectpfe registers
- - c8sectpfe-ram: c8sectpfe internal sram
-
-- clocks : phandle list of c8sectpfe clocks
-- clock-names : should be "c8sectpfe"
-See: Documentation/devicetree/bindings/clock/clock-bindings.txt
-
-- pinctrl-names : a pinctrl state named tsin%d-serial or tsin%d-parallel (where %d is tsin-num)
- must be defined for each tsin child node.
-- pinctrl-0 : phandle referencing pin configuration for this tsin configuration
-See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
-
-
-Required properties (tsin (child) node):
-
-- tsin-num : tsin id of the InputBlock (must be between 0 to 6)
-- i2c-bus : phandle to the I2C bus DT node which the demodulators & tuners on this tsin channel are connected.
-- reset-gpios : reset gpio for this tsin channel.
-
-Optional properties (tsin (child) node):
-
-- invert-ts-clk : Bool property to control sense of ts input clock (data stored on falling edge of clk).
-- serial-not-parallel : Bool property to configure input bus width (serial on ts_data<7>).
-- async-not-sync : Bool property to control if data is received in asynchronous mode
- (all bits/bytes with ts_valid or ts_packet asserted are valid).
-
-- dvb-card : Describes the NIM card connected to this tsin channel.
-
-Example:
-
-/* stih410 SoC b2120 + b2004a + stv0367-pll(NIMB) + stv0367-tda18212 (NIMA) DT example) */
-
- c8sectpfe@8a20000 {
- compatible = "st,stih407-c8sectpfe";
- reg = <0x08a20000 0x10000>, <0x08a00000 0x4000>;
- reg-names = "stfe", "stfe-ram";
- interrupts = <GIC_SPI 34 IRQ_TYPE_NONE>, <GIC_SPI 35 IRQ_TYPE_NONE>;
- interrupt-names = "stfe-error-irq", "stfe-idle-irq";
- pinctrl-0 = <&pinctrl_tsin0_serial>;
- pinctrl-1 = <&pinctrl_tsin0_parallel>;
- pinctrl-2 = <&pinctrl_tsin3_serial>;
- pinctrl-3 = <&pinctrl_tsin4_serial_alt3>;
- pinctrl-4 = <&pinctrl_tsin5_serial_alt1>;
- pinctrl-names = "tsin0-serial",
- "tsin0-parallel",
- "tsin3-serial",
- "tsin4-serial",
- "tsin5-serial";
- clocks = <&clk_s_c0_flexgen CLK_PROC_STFE>;
- clock-names = "c8sectpfe";
-
- /* tsin0 is TSA on NIMA */
- tsin0: port@0 {
- tsin-num = <0>;
- serial-not-parallel;
- i2c-bus = <&ssc2>;
- reset-gpios = <&pio15 4 GPIO_ACTIVE_HIGH>;
- dvb-card = <STV0367_TDA18212_NIMA_1>;
- };
-
- tsin3: port@3 {
- tsin-num = <3>;
- serial-not-parallel;
- i2c-bus = <&ssc3>;
- reset-gpios = <&pio15 7 GPIO_ACTIVE_HIGH>;
- dvb-card = <STV0367_TDA18212_NIMB_1>;
- };
- };
diff --git a/Documentation/devicetree/bindings/media/tegra-cec.txt b/Documentation/devicetree/bindings/media/tegra-cec.txt
deleted file mode 100644
index c503f06f3b84..000000000000
--- a/Documentation/devicetree/bindings/media/tegra-cec.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-* Tegra HDMI CEC hardware
-
-The HDMI CEC module is present in Tegra SoCs and its purpose is to
-handle communication between HDMI connected devices over the CEC bus.
-
-Required properties:
- - compatible : value should be one of the following:
- "nvidia,tegra114-cec"
- "nvidia,tegra124-cec"
- "nvidia,tegra210-cec"
- - reg : Physical base address of the IP registers and length of memory
- mapped region.
- - interrupts : HDMI CEC interrupt number to the CPU.
- - clocks : from common clock binding: handle to HDMI CEC clock.
- - clock-names : from common clock binding: must contain "cec",
- corresponding to the entry in the clocks property.
- - hdmi-phandle : phandle to the HDMI controller, see also cec.txt.
-
-Example:
-
-cec@70015000 {
- compatible = "nvidia,tegra124-cec";
- reg = <0x0 0x70015000 0x0 0x00001000>;
- interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&tegra_car TEGRA124_CLK_CEC>;
- clock-names = "cec";
-};
diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
index 65177cd69514..f1a940a110d2 100644
--- a/Documentation/devicetree/bindings/media/ti,cal.yaml
+++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/ti,cal.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
+title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL)
maintainers:
- Benoit Parrot <bparrot@ti.com>
@@ -47,7 +47,11 @@ properties:
maxItems: 1
ti,camerrx-control:
- $ref: "/schemas/types.yaml#/definitions/phandle-array"
+ $ref: /schemas/types.yaml#/definitions/phandle-array
+ items:
+ - items:
+ - description: phandle to device control module
+ - description: offset to the control_camerarx_core register
description:
phandle to the device control module and offset to the
control_camerarx_core register
@@ -71,7 +75,7 @@ properties:
port@0:
$ref: /schemas/graph.yaml#/$defs/port-base
unevaluatedProperties: false
- description: CSI2 Port #0
+ description: 'CSI2 Port #0'
properties:
endpoint:
@@ -89,7 +93,7 @@ properties:
port@1:
$ref: /schemas/graph.yaml#/$defs/port-base
unevaluatedProperties: false
- description: CSI2 Port #1
+ description: 'CSI2 Port #1'
properties:
endpoint:
@@ -154,7 +158,9 @@ examples:
camera-sensor@3c {
compatible = "ovti,ov5640";
reg = <0x3c>;
-
+ AVDD-supply = <&reg_2p8v>;
+ DOVDD-supply = <&reg_1p8v>;
+ DVDD-supply = <&reg_1p5v>;
clocks = <&clk_ov5640_fixed>;
clock-names = "xclk";
diff --git a/Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml b/Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml
new file mode 100644
index 000000000000..b9f033f2f3ce
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/ti,j721e-csi2rx-shim.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI J721E CSI2RX Shim
+
+description: |
+ The TI J721E CSI2RX Shim is a wrapper around Cadence CSI2RX bridge that
+ enables sending captured frames to memory over PSI-L DMA. In the J721E
+ Technical Reference Manual (SPRUIL1B) it is referred to as "SHIM" under the
+ CSI_RX_IF section.
+
+maintainers:
+ - Jai Luthra <jai.luthra@linux.dev>
+
+properties:
+ compatible:
+ const: ti,j721e-csi2rx-shim
+
+ dmas:
+ maxItems: 1
+
+ dma-names:
+ items:
+ - const: rx0
+
+ reg:
+ maxItems: 1
+
+ power-domains:
+ maxItems: 1
+
+ ranges: true
+
+ "#address-cells": true
+
+ "#size-cells": true
+
+patternProperties:
+ "^csi-bridge@":
+ type: object
+ description: CSI2 bridge node.
+ $ref: cdns,csi2rx.yaml#
+
+required:
+ - compatible
+ - reg
+ - dmas
+ - dma-names
+ - power-domains
+ - ranges
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/soc/ti,sci_pm_domain.h>
+
+ ti_csi2rx0: ticsi2rx@4500000 {
+ compatible = "ti,j721e-csi2rx-shim";
+ dmas = <&main_udmap 0x4940>;
+ dma-names = "rx0";
+ reg = <0x4500000 0x1000>;
+ power-domains = <&k3_pds 26 TI_SCI_PD_EXCLUSIVE>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ ranges;
+
+ cdns_csi2rx: csi-bridge@4504000 {
+ compatible = "ti,j721e-csi2rx", "cdns,csi2rx";
+ reg = <0x4504000 0x1000>;
+ clocks = <&k3_clks 26 2>, <&k3_clks 26 0>, <&k3_clks 26 2>,
+ <&k3_clks 26 2>, <&k3_clks 26 3>, <&k3_clks 26 3>;
+ clock-names = "sys_clk", "p_clk", "pixel_if0_clk",
+ "pixel_if1_clk", "pixel_if2_clk", "pixel_if3_clk";
+ phys = <&dphy0>;
+ phy-names = "dphy";
+
+ ports {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ csi2_0: port@0 {
+
+ reg = <0>;
+
+ csi2rx0_in_sensor: endpoint {
+ remote-endpoint = <&csi2_cam0>;
+ bus-type = <4>; /* CSI2 DPHY. */
+ clock-lanes = <0>;
+ data-lanes = <1 2>;
+ };
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/media/ti,vpe.yaml b/Documentation/devicetree/bindings/media/ti,vpe.yaml
index ef473f287399..7fa8a367ed22 100644
--- a/Documentation/devicetree/bindings/media/ti,vpe.yaml
+++ b/Documentation/devicetree/bindings/media/ti,vpe.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/ti,vpe.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Texas Instruments DRA7x Video Processing Engine (VPE) Device Tree Bindings
+title: Texas Instruments DRA7x Video Processing Engine (VPE)
maintainers:
- Benoit Parrot <bparrot@ti.com>
diff --git a/Documentation/devicetree/bindings/media/video-interface-devices.yaml b/Documentation/devicetree/bindings/media/video-interface-devices.yaml
index 4527f56a5a6e..a81d2a155fe6 100644
--- a/Documentation/devicetree/bindings/media/video-interface-devices.yaml
+++ b/Documentation/devicetree/bindings/media/video-interface-devices.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/video-interface-devices.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Common bindings for video receiver and transmitter devices
+title: Common Properties for Video Receiver and Transmitter Devices
maintainers:
- Jacopo Mondi <jacopo@jmondi.org>
@@ -17,6 +17,14 @@ properties:
An array of phandles, each referring to a flash LED, a sub-node of the LED
driver device node.
+ leds:
+ minItems: 1
+ maxItems: 1
+
+ led-names:
+ enum:
+ - privacy
+
lens-focus:
$ref: /schemas/types.yaml#/definitions/phandle
description:
@@ -120,7 +128,6 @@ properties:
0 degrees camera rotation:
-
Y-Rp
^
Y-Rc !
@@ -137,7 +144,6 @@ properties:
0 +------------------------------------->
0 X-Rc
-
X-Rc 0
<------------------------------------+ 0
X-Rp 0 !
@@ -220,7 +226,6 @@ properties:
V
X-Rc
-
Example one - Webcam
A camera module installed on the user facing part of a laptop screen
@@ -265,7 +270,6 @@ properties:
optical inversion, the two reference systems will not be aligned, with
'Rp' being rotated 180 degrees relatively to 'Rc':
-
X-Rc 0
<------------------------------------+ 0
!
diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml
index 4391dce2caee..6ed4695cacf7 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.yaml
+++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/media/video-interfaces.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Common bindings for video receiver and transmitter interface endpoints
+title: Common Properties for Video Receiver and Transmitter Interface Endpoints
maintainers:
- Sakari Ailus <sakari.ailus@linux.intel.com>
@@ -93,8 +93,9 @@ properties:
- 4 # MIPI CSI-2 D-PHY
- 5 # Parallel
- 6 # BT.656
+ - 7 # DPI
description:
- Data bus type.
+ Data bus type. See include/dt-bindings/media/video-interfaces.h.
bus-width:
$ref: /schemas/types.yaml#/definitions/uint32
@@ -144,9 +145,10 @@ properties:
pclk-sample:
$ref: /schemas/types.yaml#/definitions/uint32
- enum: [ 0, 1 ]
+ enum: [ 0, 1, 2 ]
description:
- Sample data on rising (1) or falling (0) edge of the pixel clock signal.
+ Sample data on falling (0), rising (1) or both (2) edges of the pixel
+ clock signal.
sync-on-green-active:
$ref: /schemas/types.yaml#/definitions/uint32
@@ -158,6 +160,7 @@ properties:
$ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 1
maxItems: 8
+ uniqueItems: true
items:
# Assume up to 9 physical lane indices
maximum: 8
@@ -207,6 +210,27 @@ properties:
lane-polarities property is omitted, the value must be interpreted as 0
(normal). This property is valid for serial busses only.
+ line-orders:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 1
+ maxItems: 8
+ items:
+ enum:
+ - 0 # ABC
+ - 1 # ACB
+ - 2 # BAC
+ - 3 # BCA
+ - 4 # CAB
+ - 5 # CBA
+ description:
+ An array of line orders of the CSI-2 C-PHY data lanes. The order of the
+ lanes are the same as in data-lanes property. Valid values are 0-5 as
+ defined in the MIPI Discovery and Configuration (DisCo) Specification for
+ Imaging. The length of the array must be the same length as the
+ data-lanes property. If the line-orders property is omitted, the value
+ shall be interpreted as 0 (ABC). This property is valid for CSI-2 C-PHY
+ busses only. See include/dt-bindings/media/video-interfaces.h.
+
strobe:
$ref: /schemas/types.yaml#/definitions/uint32
enum: [ 0, 1 ]
diff --git a/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml
index 7d77823dbb7a..43daf837fc9f 100644
--- a/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml
+++ b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml
@@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
title: Xilinx MIPI CSI-2 Receiver Subsystem
maintainers:
- - Vishal Sagar <vishal.sagar@xilinx.com>
+ - Vishal Sagar <vishal.sagar@amd.com>
description: |
The Xilinx MIPI CSI-2 Receiver Subsystem is used to capture MIPI CSI-2
diff --git a/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt b/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt
deleted file mode 100644
index 22b77ee02f58..000000000000
--- a/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt
+++ /dev/null
@@ -1,127 +0,0 @@
-* Device tree bindings for ARM PL172/PL175/PL176 MultiPort Memory Controller
-
-Required properties:
-
-- compatible: Must be "arm,primecell" and exactly one from
- "arm,pl172", "arm,pl175" or "arm,pl176".
-
-- reg: Must contains offset/length value for controller.
-
-- #address-cells: Must be 2. The partition number has to be encoded in the
- first address cell and it may accept values 0..N-1
- (N - total number of partitions). The second cell is the
- offset into the partition.
-
-- #size-cells: Must be set to 1.
-
-- ranges: Must contain one or more chip select memory regions.
-
-- clocks: Must contain references to controller clocks.
-
-- clock-names: Must contain "mpmcclk" and "apb_pclk".
-
-- clock-ranges: Empty property indicating that child nodes can inherit
- named clocks. Required only if clock tree data present
- in device tree.
- See clock-bindings.txt
-
-Child chip-select (cs) nodes contain the memory devices nodes connected to
-such as NOR (e.g. cfi-flash) and NAND.
-
-Required child cs node properties:
-
-- #address-cells: Must be 2.
-
-- #size-cells: Must be 1.
-
-- ranges: Empty property indicating that child nodes can inherit
- memory layout.
-
-- clock-ranges: Empty property indicating that child nodes can inherit
- named clocks. Required only if clock tree data present
- in device tree.
-
-- mpmc,cs: Chip select number. Indicates to the pl0172 driver
- which chipselect is used for accessing the memory.
-
-- mpmc,memory-width: Width of the chip select memory. Must be equal to
- either 8, 16 or 32.
-
-Optional child cs node config properties:
-
-- mpmc,async-page-mode: Enable asynchronous page mode.
-
-- mpmc,cs-active-high: Set chip select polarity to active high.
-
-- mpmc,byte-lane-low: Set byte lane state to low.
-
-- mpmc,extended-wait: Enable extended wait.
-
-- mpmc,buffer-enable: Enable write buffer, option is not supported by
- PL175 and PL176 controllers.
-
-- mpmc,write-protect: Enable write protect.
-
-Optional child cs node timing properties:
-
-- mpmc,write-enable-delay: Delay from chip select assertion to write
- enable (WE signal) in nano seconds.
-
-- mpmc,output-enable-delay: Delay from chip select assertion to output
- enable (OE signal) in nano seconds.
-
-- mpmc,write-access-delay: Delay from chip select assertion to write
- access in nano seconds.
-
-- mpmc,read-access-delay: Delay from chip select assertion to read
- access in nano seconds.
-
-- mpmc,page-mode-read-delay: Delay for asynchronous page mode sequential
- accesses in nano seconds.
-
-- mpmc,turn-round-delay: Delay between access to memory banks in nano
- seconds.
-
-If any of the above timing parameters are absent, current parameter value will
-be taken from the corresponding HW reg.
-
-Example for pl172 with nor flash on chip select 0 shown below.
-
-emc: memory-controller@40005000 {
- compatible = "arm,pl172", "arm,primecell";
- reg = <0x40005000 0x1000>;
- clocks = <&ccu1 CLK_CPU_EMCDIV>, <&ccu1 CLK_CPU_EMC>;
- clock-names = "mpmcclk", "apb_pclk";
- #address-cells = <2>;
- #size-cells = <1>;
- ranges = <0 0 0x1c000000 0x1000000
- 1 0 0x1d000000 0x1000000
- 2 0 0x1e000000 0x1000000
- 3 0 0x1f000000 0x1000000>;
-
- cs0 {
- #address-cells = <2>;
- #size-cells = <1>;
- ranges;
-
- mpmc,cs = <0>;
- mpmc,memory-width = <16>;
- mpmc,byte-lane-low;
- mpmc,write-enable-delay = <0>;
- mpmc,output-enable-delay = <0>;
- mpmc,read-enable-delay = <70>;
- mpmc,page-mode-read-delay = <70>;
-
- flash@0,0 {
- compatible = "sst,sst39vf320", "cfi-flash";
- reg = <0 0 0x400000>;
- bank-width = <2>;
- #address-cells = <1>;
- #size-cells = <1>;
- partition@0 {
- label = "data";
- reg = <0 0x400000>;
- };
- };
- };
-};
diff --git a/Documentation/devicetree/bindings/memory-controllers/arm,pl172.yaml b/Documentation/devicetree/bindings/memory-controllers/arm,pl172.yaml
new file mode 100644
index 000000000000..c1b702669bd9
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/arm,pl172.yaml
@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/arm,pl172.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM PL172/PL175/PL176 MultiPort Memory Controller
+
+maintainers:
+ - Frank Li <Frank.Li@nxp.com>
+
+# We need a select here so we don't match all nodes with 'arm,primecell'
+select:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - arm,pl172
+ - arm,pl175
+ - arm,pl176
+ required:
+ - compatible
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - arm,pl172
+ - arm,pl175
+ - arm,pl176
+ - const: arm,primecell
+
+ reg:
+ maxItems: 1
+
+ '#address-cells':
+ const: 2
+
+ '#size-cells':
+ const: 1
+
+ ranges: true
+
+ clocks:
+ maxItems: 2
+
+ clock-names:
+ items:
+ - const: mpmcclk
+ - const: apb_pclk
+
+ clock-ranges: true
+
+ resets:
+ maxItems: 1
+
+patternProperties:
+ "^cs[0-9]$":
+ type: object
+ additionalProperties: false
+ patternProperties:
+ "^flash@[0-9],[0-9a-f]+$":
+ type: object
+ $ref: /schemas/mtd/mtd-physmap.yaml#
+ unevaluatedProperties: false
+
+ "^(gpio|sram)@[0-9],[0-9a-f]+$":
+ type: object
+ additionalProperties: true
+
+ properties:
+ '#address-cells':
+ const: 2
+
+ '#size-cells':
+ const: 1
+
+ ranges: true
+
+ clocks:
+ maxItems: 2
+
+ clock-ranges: true
+
+ mpmc,cs:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Chip select number. Indicates to the pl0172 driver
+ which chipselect is used for accessing the memory.
+
+ mpmc,memory-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ enum: [8, 16, 32]
+ description:
+ Width of the chip select memory. Must be equal to either 8, 16 or 32.
+
+ mpmc,async-page-mode:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable asynchronous page mode.
+
+ mpmc,cs-active-high:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Set chip select polarity to active high.
+
+ mpmc,byte-lane-low:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Set byte lane state to low.
+
+ mpmc,extended-wait:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable extended wait.
+
+ mpmc,buffer-enable:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable write buffer, option is not supported by
+ PL175 and PL176 controllers.
+
+ mpmc,write-protect:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description:
+ Enable write protect.
+
+ mpmc,read-enable-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay from chip select assertion to read
+ enable (RE signal) in nano seconds.
+
+ mpmc,write-enable-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay from chip select assertion to write
+ enable (WE signal) in nano seconds.
+
+ mpmc,output-enable-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay from chip select assertion to output
+ enable (OE signal) in nano seconds.
+
+ mpmc,write-access-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay from chip select assertion to write
+ access in nano seconds.
+
+ mpmc,read-access-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay from chip select assertion to read
+ access in nano seconds.
+
+ mpmc,page-mode-read-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay for asynchronous page mode sequential
+ accesses in nano seconds.
+
+ mpmc,turn-round-delay:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Delay between access to memory banks in nano
+ seconds.
+
+required:
+ - compatible
+ - reg
+ - '#address-cells'
+ - '#size-cells'
+ - ranges
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/lpc18xx-ccu.h>
+
+ memory-controller@40005000 {
+ compatible = "arm,pl172", "arm,primecell";
+ reg = <0x40005000 0x1000>;
+ clocks = <&ccu1 CLK_CPU_EMCDIV>, <&ccu1 CLK_CPU_EMC>;
+ clock-names = "mpmcclk", "apb_pclk";
+ #address-cells = <2>;
+ #size-cells = <1>;
+ ranges = <0 0 0x1c000000 0x1000000
+ 1 0 0x1d000000 0x1000000
+ 2 0 0x1e000000 0x1000000
+ 3 0 0x1f000000 0x1000000>;
+
+ cs0 {
+ #address-cells = <2>;
+ #size-cells = <1>;
+ ranges;
+
+ mpmc,cs = <0>;
+ mpmc,memory-width = <16>;
+ mpmc,byte-lane-low;
+ mpmc,write-enable-delay = <0>;
+ mpmc,output-enable-delay = <0>;
+ mpmc,read-enable-delay = <70>;
+ mpmc,page-mode-read-delay = <70>;
+
+ flash@0,0 {
+ compatible = "sst,sst39vf320", "cfi-flash";
+ reg = <0 0 0x400000>;
+ bank-width = <2>;
+ #address-cells = <1>;
+ #size-cells = <1>;
+ partition@0 {
+ label = "data";
+ reg = <0 0x400000>;
+ };
+ };
+ };
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/arm,pl353-smc.yaml b/Documentation/devicetree/bindings/memory-controllers/arm,pl353-smc.yaml
deleted file mode 100644
index 7a63c85ef8c5..000000000000
--- a/Documentation/devicetree/bindings/memory-controllers/arm,pl353-smc.yaml
+++ /dev/null
@@ -1,131 +0,0 @@
-# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-%YAML 1.2
----
-$id: http://devicetree.org/schemas/memory-controllers/arm,pl353-smc.yaml#
-$schema: http://devicetree.org/meta-schemas/core.yaml#
-
-title: ARM PL353 Static Memory Controller (SMC) device-tree bindings
-
-maintainers:
- - Miquel Raynal <miquel.raynal@bootlin.com>
- - Naga Sureshkumar Relli <naga.sureshkumar.relli@xilinx.com>
-
-description:
- The PL353 Static Memory Controller is a bus where you can connect two kinds
- of memory interfaces, which are NAND and memory mapped interfaces (such as
- SRAM or NOR).
-
-# We need a select here so we don't match all nodes with 'arm,primecell'
-select:
- properties:
- compatible:
- contains:
- const: arm,pl353-smc-r2p1
- required:
- - compatible
-
-properties:
- $nodename:
- pattern: "^memory-controller@[0-9a-f]+$"
-
- compatible:
- items:
- - const: arm,pl353-smc-r2p1
- - const: arm,primecell
-
- "#address-cells":
- const: 2
-
- "#size-cells":
- const: 1
-
- reg:
- items:
- - description:
- Configuration registers for the host and sub-controllers.
- The three chip select regions are defined in 'ranges'.
-
- clocks:
- items:
- - description: clock for the memory device bus
- - description: main clock of the SMC
-
- clock-names:
- items:
- - const: memclk
- - const: apb_pclk
-
- ranges:
- minItems: 1
- maxItems: 3
- description: |
- Memory bus areas for interacting with the devices. Reflects
- the memory layout with four integer values following:
- <cs-number> 0 <offset> <size>
- items:
- - description: NAND bank 0
- - description: NOR/SRAM bank 0
- - description: NOR/SRAM bank 1
-
- interrupts: true
-
-patternProperties:
- "@[0-3],[a-f0-9]+$":
- type: object
- description: |
- The child device node represents the controller connected to the SMC
- bus. The controller can be a NAND controller or a pair of any memory
- mapped controllers such as NOR and SRAM controllers.
-
- properties:
- compatible:
- description:
- Compatible of memory controller.
-
- reg:
- items:
- - items:
- - description: |
- Chip-select ID, as in the parent range property.
- minimum: 0
- maximum: 2
- - description: |
- Offset of the memory region requested by the device.
- - description: |
- Length of the memory region requested by the device.
-
- required:
- - compatible
- - reg
-
-required:
- - compatible
- - reg
- - clock-names
- - clocks
- - "#address-cells"
- - "#size-cells"
- - ranges
-
-additionalProperties: false
-
-examples:
- - |
- smcc: memory-controller@e000e000 {
- compatible = "arm,pl353-smc-r2p1", "arm,primecell";
- reg = <0xe000e000 0x0001000>;
- clock-names = "memclk", "apb_pclk";
- clocks = <&clkc 11>, <&clkc 44>;
- ranges = <0x0 0x0 0xe1000000 0x1000000 /* Nand CS region */
- 0x1 0x0 0xe2000000 0x2000000 /* SRAM/NOR CS0 region */
- 0x2 0x0 0xe4000000 0x2000000>; /* SRAM/NOR CS1 region */
- #address-cells = <2>;
- #size-cells = <1>;
-
- nfc0: nand-controller@0,0 {
- compatible = "arm,pl353-nand-r2p1";
- reg = <0 0 0x1000000>;
- #address-cells = <1>;
- #size-cells = <0>;
- };
- };
diff --git a/Documentation/devicetree/bindings/memory-controllers/arm,pl35x-smc.yaml b/Documentation/devicetree/bindings/memory-controllers/arm,pl35x-smc.yaml
new file mode 100644
index 000000000000..05dd6b3a1a3c
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/arm,pl35x-smc.yaml
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/arm,pl35x-smc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Arm PL35x Series Static Memory Controller (SMC)
+
+maintainers:
+ - Miquel Raynal <miquel.raynal@bootlin.com>
+
+description: |
+ The PL35x Static Memory Controller is a bus where you can connect two kinds
+ of memory interfaces, which are NAND and memory mapped interfaces (such as
+ SRAM or NOR) depending on the specific configuration.
+
+ The TRM is available here:
+ https://documentation-service.arm.com/static/5e8e2524fd977155116a58aa
+
+# We need a select here so we don't match all nodes with 'arm,primecell'
+select:
+ properties:
+ compatible:
+ contains:
+ enum:
+ - arm,pl353-smc-r2p1
+ - arm,pl354
+ required:
+ - compatible
+
+properties:
+ $nodename:
+ pattern: "^memory-controller@[0-9a-f]+$"
+
+ compatible:
+ items:
+ - enum:
+ - arm,pl353-smc-r2p1
+ - arm,pl354
+ - const: arm,primecell
+
+ "#address-cells":
+ const: 2
+
+ "#size-cells":
+ const: 1
+
+ reg:
+ items:
+ - description:
+ Configuration registers for the host and sub-controllers.
+ The three chip select regions are defined in 'ranges'.
+
+ clocks:
+ minItems: 1
+ maxItems: 2
+
+ clock-names:
+ minItems: 1
+ maxItems: 2
+
+ ranges:
+ minItems: 1
+ maxItems: 8
+
+ interrupts:
+ minItems: 1
+ items:
+ - description: Combined or Memory interface 0 IRQ
+ - description: Memory interface 1 IRQ
+
+patternProperties:
+ "@[0-7],[a-f0-9]+$":
+ type: object
+ additionalProperties: true
+ description: |
+ The child device node represents the controller connected to the SMC
+ bus. The controller can be a NAND controller or a pair of any memory
+ mapped controllers such as NOR and SRAM controllers.
+
+ properties:
+ compatible:
+ description:
+ Compatible of memory controller.
+
+ reg:
+ items:
+ - items:
+ - description: |
+ Chip-select ID, as in the parent range property.
+ minimum: 0
+ maximum: 7
+ - description: |
+ Offset of the memory region requested by the device.
+ - description: |
+ Length of the memory region requested by the device.
+
+ required:
+ - compatible
+ - reg
+
+required:
+ - compatible
+ - reg
+ - clock-names
+ - clocks
+
+additionalProperties: false
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: arm,pl354
+ then:
+ properties:
+ clocks:
+ # According to TRM, really should be 3 clocks
+ maxItems: 1
+
+ clock-names:
+ const: apb_pclk
+
+ else:
+ properties:
+ clocks:
+ items:
+ - description: clock for the memory device bus
+ - description: main clock of the SMC
+
+ clock-names:
+ items:
+ - const: memclk
+ - const: apb_pclk
+
+examples:
+ - |
+ smcc: memory-controller@e000e000 {
+ compatible = "arm,pl353-smc-r2p1", "arm,primecell";
+ reg = <0xe000e000 0x0001000>;
+ clock-names = "memclk", "apb_pclk";
+ clocks = <&clkc 11>, <&clkc 44>;
+ ranges = <0x0 0x0 0xe1000000 0x1000000 /* Nand CS region */
+ 0x1 0x0 0xe2000000 0x2000000 /* SRAM/NOR CS0 region */
+ 0x2 0x0 0xe4000000 0x2000000>; /* SRAM/NOR CS1 region */
+ #address-cells = <2>;
+ #size-cells = <1>;
+
+ nfc0: nand-controller@0,0 {
+ compatible = "arm,pl353-nand-r2p1";
+ reg = <0 0 0x1000000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt b/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt
deleted file mode 100644
index c81af75bcd88..000000000000
--- a/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-Binding for Qualcomm Atheros AR7xxx/AR9xxx DDR controller
-
-The DDR controller of the AR7xxx and AR9xxx families provides an interface
-to flush the FIFO between various devices and the DDR. This is mainly used
-by the IRQ controller to flush the FIFO before running the interrupt handler
-of such devices.
-
-Required properties:
-
-- compatible: has to be "qca,<soc-type>-ddr-controller",
- "qca,[ar7100|ar7240]-ddr-controller" as fallback.
- On SoC with PCI support "qca,ar7100-ddr-controller" should be used as
- fallback, otherwise "qca,ar7240-ddr-controller" should be used.
-- reg: Base address and size of the controller's memory area
-- #qca,ddr-wb-channel-cells: Specifies the number of cells needed to encode
- the write buffer channel index, should be 1.
-
-Example:
-
- ddr_ctrl: memory-controller@18000000 {
- compatible = "qca,ar9132-ddr-controller",
- "qca,ar7240-ddr-controller";
- reg = <0x18000000 0x100>;
-
- #qca,ddr-wb-channel-cells = <1>;
- };
-
- ...
-
- interrupt-controller {
- ...
- qca,ddr-wb-channel-interrupts = <2>, <3>, <4>, <5>;
- qca,ddr-wb-channels = <&ddr_ctrl 3>, <&ddr_ctrl 2>,
- <&ddr_ctrl 0>, <&ddr_ctrl 1>;
- };
diff --git a/Documentation/devicetree/bindings/memory-controllers/brcm,brcmstb-memc-ddr.yaml b/Documentation/devicetree/bindings/memory-controllers/brcm,brcmstb-memc-ddr.yaml
new file mode 100644
index 000000000000..3328c8df8190
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/brcm,brcmstb-memc-ddr.yaml
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/brcm,brcmstb-memc-ddr.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Memory controller (MEMC) for Broadcom STB
+
+maintainers:
+ - Florian Fainelli <f.fainelli@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - description: Revision > 2.1 controllers
+ items:
+ - enum:
+ - brcm,brcmstb-memc-ddr-rev-b.2.2
+ - brcm,brcmstb-memc-ddr-rev-b.2.3
+ - brcm,brcmstb-memc-ddr-rev-b.2.5
+ - brcm,brcmstb-memc-ddr-rev-b.2.6
+ - brcm,brcmstb-memc-ddr-rev-b.2.7
+ - brcm,brcmstb-memc-ddr-rev-b.2.8
+ - brcm,brcmstb-memc-ddr-rev-b.3.0
+ - brcm,brcmstb-memc-ddr-rev-b.3.1
+ - brcm,brcmstb-memc-ddr-rev-c.1.0
+ - brcm,brcmstb-memc-ddr-rev-c.1.1
+ - brcm,brcmstb-memc-ddr-rev-c.1.2
+ - brcm,brcmstb-memc-ddr-rev-c.1.3
+ - brcm,brcmstb-memc-ddr-rev-c.1.4
+ - const: brcm,brcmstb-memc-ddr-rev-b.2.1
+ - const: brcm,brcmstb-memc-ddr
+ - description: Revision 2.1 controllers
+ items:
+ - const: brcm,brcmstb-memc-ddr-rev-b.2.1
+ - const: brcm,brcmstb-memc-ddr
+ - description: Revision 2.0 controllers
+ items:
+ - const: brcm,brcmstb-memc-ddr-rev-b.2.0
+ - const: brcm,brcmstb-memc-ddr
+ - description: Revision 1.x controllers
+ items:
+ - const: brcm,brcmstb-memc-ddr-rev-b.1.x
+ - const: brcm,brcmstb-memc-ddr
+ - description: Revision 0.x controllers
+ items:
+ - const: brcm,brcmstb-memc-ddr-rev-a.0.0
+ - const: brcm,brcmstb-memc-ddr
+
+ reg:
+ maxItems: 1
+
+ clock-frequency:
+ description: DDR PHY frequency in Hz
+
+required:
+ - compatible
+ - reg
+
+additionalProperties: false
+
+examples:
+ - |
+ memory-controller@9902000 {
+ compatible = "brcm,brcmstb-memc-ddr-rev-c.1.1",
+ "brcm,brcmstb-memc-ddr-rev-b.2.1",
+ "brcm,brcmstb-memc-ddr";
+ reg = <0x9902000 0x600>;
+ clock-frequency = <2133000000>;
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.txt b/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.txt
deleted file mode 100644
index 82d923ef413f..000000000000
--- a/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-DDR PHY Front End (DPFE) for Broadcom STB
-=========================================
-
-DPFE and the DPFE firmware provide an interface for the host CPU to
-communicate with the DCPU, which resides inside the DDR PHY.
-
-There are three memory regions for interacting with the DCPU. These are
-specified in a single reg property.
-
-Required properties:
- - compatible: must be "brcm,bcm7271-dpfe-cpu", "brcm,bcm7268-dpfe-cpu"
- or "brcm,dpfe-cpu"
- - reg: must reference three register ranges
- - start address and length of the DCPU register space
- - start address and length of the DCPU data memory space
- - start address and length of the DCPU instruction memory space
- - reg-names: must contain "dpfe-cpu", "dpfe-dmem", and "dpfe-imem";
- they must be in the same order as the register declarations
-
-Example:
- dpfe_cpu0: dpfe-cpu@f1132000 {
- compatible = "brcm,bcm7271-dpfe-cpu", "brcm,dpfe-cpu";
- reg = <0xf1132000 0x180
- 0xf1134000 0x1000
- 0xf1138000 0x4000>;
- reg-names = "dpfe-cpu", "dpfe-dmem", "dpfe-imem";
- };
diff --git a/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml b/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml
new file mode 100644
index 000000000000..08cbdcddfead
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/brcm,dpfe-cpu.yaml
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/brcm,dpfe-cpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DDR PHY Front End (DPFE) for Broadcom STB
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+ - Markus Mayer <mmayer@broadcom.com>
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - brcm,bcm7271-dpfe-cpu
+ - brcm,bcm7268-dpfe-cpu
+ - const: brcm,dpfe-cpu
+
+ reg:
+ items:
+ - description: DCPU register space
+ - description: DCPU data memory space
+ - description: DCPU instruction memory space
+
+ reg-names:
+ items:
+ - const: dpfe-cpu
+ - const: dpfe-dmem
+ - const: dpfe-imem
+
+required:
+ - compatible
+ - reg
+ - reg-names
+
+additionalProperties: false
+
+examples:
+ - |
+ dpfe-cpu@f1132000 {
+ compatible = "brcm,bcm7271-dpfe-cpu", "brcm,dpfe-cpu";
+ reg = <0xf1132000 0x180>,
+ <0xf1134000 0x1000>,
+ <0xf1138000 0x4000>;
+ reg-names = "dpfe-cpu", "dpfe-dmem", "dpfe-imem";
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.yaml b/Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.yaml
index 96d563fd61f5..e42aa488704d 100644
--- a/Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.yaml
+++ b/Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.yaml
@@ -4,7 +4,7 @@
$id: http://devicetree.org/schemas/memory-controllers/calxeda-ddr-ctrlr.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
-title: Calxeda DDR memory controller binding
+title: Calxeda DDR memory controller
description: |
The Calxeda DDR memory controller is initialised and programmed by the
diff --git a/Documentation/devicetree/bindings/memory-controllers/canaan,k210-sram.yaml b/Documentation/devicetree/bindings/memory-controllers/canaan,k210-sram.yaml
new file mode 100644
index 000000000000..f81fb866e319
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/canaan,k210-sram.yaml
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/canaan,k210-sram.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Canaan K210 SRAM memory controller
+
+description:
+ The Canaan K210 SRAM memory controller is responsible for the system's 8 MiB
+ of SRAM. The controller is initialised by the bootloader, which configures
+ its clocks, before OS bringup.
+
+maintainers:
+ - Conor Dooley <conor@kernel.org>
+
+properties:
+ compatible:
+ enum:
+ - canaan,k210-sram
+
+ clocks:
+ minItems: 1
+ items:
+ - description: sram0 clock
+ - description: sram1 clock
+ - description: aisram clock
+
+ clock-names:
+ minItems: 1
+ items:
+ - const: sram0
+ - const: sram1
+ - const: aisram
+
+required:
+ - compatible
+ - clocks
+ - clock-names
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/clock/k210-clk.h>
+ memory-controller {
+ compatible = "canaan,k210-sram";
+ clocks = <&sysclk K210_CLK_SRAM0>,
+ <&sysclk K210_CLK_SRAM1>,
+ <&sysclk K210_CLK_AI>;
+ clock-names = "sram0", "sram1", "aisram";
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml
new file mode 100644
index 000000000000..34b5bd153f63
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-channel.yaml
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr-channel.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LPDDR channel with chip/rank topology description
+
+description:
+ An LPDDR channel is a completely independent set of LPDDR pins (DQ, CA, CS,
+ CK, etc.) that connect one or more LPDDR chips to a host system. The main
+ purpose of this node is to overall LPDDR topology of the system, including the
+ amount of individual LPDDR chips and the ranks per chip.
+
+maintainers:
+ - Julius Werner <jwerner@chromium.org>
+
+properties:
+ compatible:
+ enum:
+ - jedec,lpddr2-channel
+ - jedec,lpddr3-channel
+ - jedec,lpddr4-channel
+ - jedec,lpddr5-channel
+
+ io-width:
+ description:
+ The number of DQ pins in the channel. If this number is different
+ from (a multiple of) the io-width of the LPDDR chip, that means that
+ multiple instances of that type of chip are wired in parallel on this
+ channel (with the channel's DQ pins split up between the different
+ chips, and the CA, CS, etc. pins of the different chips all shorted
+ together). This means that the total physical memory controlled by a
+ channel is equal to the sum of the densities of each rank on the
+ connected LPDDR chip, times the io-width of the channel divided by
+ the io-width of the LPDDR chip.
+ enum:
+ - 8
+ - 16
+ - 32
+ - 64
+ - 128
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 0
+
+patternProperties:
+ "^rank@[0-9]+$":
+ type: object
+ description:
+ Each physical LPDDR chip may have one or more ranks. Ranks are
+ internal but fully independent sub-units of the chip. Each LPDDR bus
+ transaction on the channel targets exactly one rank, based on the
+ state of the CS pins. Different ranks may have different densities and
+ timing requirements.
+ required:
+ - reg
+
+allOf:
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: jedec,lpddr2-channel
+ then:
+ patternProperties:
+ "^rank@[0-9]+$":
+ $ref: /schemas/memory-controllers/ddr/jedec,lpddr2.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: jedec,lpddr3-channel
+ then:
+ patternProperties:
+ "^rank@[0-9]+$":
+ $ref: /schemas/memory-controllers/ddr/jedec,lpddr3.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: jedec,lpddr4-channel
+ then:
+ patternProperties:
+ "^rank@[0-9]+$":
+ $ref: /schemas/memory-controllers/ddr/jedec,lpddr4.yaml#
+ - if:
+ properties:
+ compatible:
+ contains:
+ const: jedec,lpddr5-channel
+ then:
+ patternProperties:
+ "^rank@[0-9]+$":
+ $ref: /schemas/memory-controllers/ddr/jedec,lpddr5.yaml#
+
+required:
+ - compatible
+ - io-width
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ lpddr-channel0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "jedec,lpddr3-channel";
+ io-width = <32>;
+
+ rank@0 {
+ compatible = "lpddr3-ff,0100", "jedec,lpddr3";
+ reg = <0>;
+ density = <8192>;
+ io-width = <16>;
+ revision-id = <1 0>;
+ };
+ };
+
+ lpddr-channel1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ compatible = "jedec,lpddr4-channel";
+ io-width = <32>;
+
+ rank@0 {
+ compatible = "lpddr4-05,0301", "jedec,lpddr4";
+ reg = <0>;
+ density = <4096>;
+ io-width = <32>;
+ revision-id = <3 1>;
+ };
+
+ rank@1 {
+ compatible = "lpddr4-05,0301", "jedec,lpddr4";
+ reg = <1>;
+ density = <2048>;
+ io-width = <32>;
+ revision-id = <3 1>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml
new file mode 100644
index 000000000000..30267ce70124
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr-props.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr-props.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common properties for LPDDR types
+
+description:
+ Different LPDDR types generally use the same properties and only differ in the
+ range of legal values for each. This file defines the common parts that can be
+ reused for each type. Nodes using this schema should generally be nested under
+ an LPDDR channel node.
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ description:
+ Compatible strings can be either explicit vendor names and part numbers
+ (e.g. elpida,ECB240ABACN), or generated strings of the form
+ lpddrX-YY,ZZZZ where X is the LPDDR version, YY is the manufacturer ID
+ (from MR5) and ZZZZ is the revision ID (from MR6 and MR7). Both IDs are
+ formatted in lower case hexadecimal representation with leading zeroes.
+ The latter form can be useful when LPDDR nodes are created at runtime by
+ boot firmware that doesn't have access to static part number information.
+
+ reg:
+ description:
+ The rank number of this LPDDR rank when used as a subnode to an LPDDR
+ channel.
+ minimum: 0
+ maximum: 3
+
+ revision-id:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ description:
+ Revision IDs read from Mode Register 6 and 7. One byte per uint32 cell (i.e. <MR6 MR7>).
+ maxItems: 2
+ items:
+ minimum: 0
+ maximum: 255
+
+ density:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Density in megabits of SDRAM chip. Decoded from Mode Register 8.
+ enum:
+ - 64
+ - 128
+ - 256
+ - 512
+ - 1024
+ - 2048
+ - 3072
+ - 4096
+ - 6144
+ - 8192
+ - 12288
+ - 16384
+ - 24576
+ - 32768
+
+ io-width:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ IO bus width in bits of SDRAM chip. Decoded from Mode Register 8.
+ enum:
+ - 8
+ - 16
+ - 32
+
+additionalProperties: true
diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2-timings.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2-timings.yaml
new file mode 100644
index 000000000000..1daa66592477
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2-timings.yaml
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr2-timings.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LPDDR2 SDRAM AC timing parameters for a given speed-bin
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+properties:
+ compatible:
+ const: jedec,lpddr2-timings
+
+ max-freq:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Maximum DDR clock frequency for the speed-bin, in Hz.
+
+ min-freq:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Minimum DDR clock frequency for the speed-bin, in Hz.
+
+ tCKESR:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ CKE minimum pulse width during SELF REFRESH (low pulse width during
+ SELF REFRESH) in pico seconds.
+
+ tDQSCK-max:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ DQS output data access time from CK_t/CK_c in pico seconds.
+
+ tDQSCK-max-derated:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ DQS output data access time from CK_t/CK_c, temperature de-rated, in pico
+ seconds.
+
+ tFAW:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Four-bank activate window in pico seconds.
+
+ tRAS-max-ns:
+ description: |
+ Row active time in nano seconds.
+
+ tRAS-min:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Row active time in pico seconds.
+
+ tRCD:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ RAS-to-CAS delay in pico seconds.
+
+ tRPab:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Row precharge time (all banks) in pico seconds.
+
+ tRRD:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Active bank A to active bank B in pico seconds.
+
+ tRTP:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Internal READ to PRECHARGE command delay in pico seconds.
+
+ tWR:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ WRITE recovery time in pico seconds.
+
+ tWTR:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Internal WRITE-to-READ command delay in pico seconds.
+
+ tXP:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Exit power-down to next valid command delay in pico seconds.
+
+ tZQCL:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Long calibration time in pico seconds.
+
+ tZQCS:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Short calibration time in pico seconds.
+
+ tZQinit:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ Initialization calibration time in pico seconds.
+
+required:
+ - compatible
+ - min-freq
+ - max-freq
+
+additionalProperties: false
+
+examples:
+ - |
+ timings {
+ compatible = "jedec,lpddr2-timings";
+ min-freq = <10000000>;
+ max-freq = <400000000>;
+ tCKESR = <15000>;
+ tDQSCK-max = <5500>;
+ tFAW = <50000>;
+ tRAS-max-ns = <70000>;
+ tRAS-min = <42000>;
+ tRPab = <21000>;
+ tRCD = <18000>;
+ tRRD = <10000>;
+ tRTP = <7500>;
+ tWR = <15000>;
+ tWTR = <7500>;
+ tXP = <7500>;
+ tZQCL = <360000>;
+ tZQCS = <90000>;
+ tZQinit = <1000000>;
+ };
diff --git a/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml
new file mode 100644
index 000000000000..a237bc259273
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/ddr/jedec,lpddr2.yaml
@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/memory-controllers/ddr/jedec,lpddr2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: LPDDR2 SDRAM compliant to JEDEC JESD209-2
+
+maintainers:
+ - Krzysztof Kozlowski <krzk@kernel.org>
+
+allOf:
+ - $ref: jedec,lpddr-props.yaml#
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - elpida,ECB240ABACN
+ - elpida,B8132B2PB-6D-F
+ - enum:
+ - jedec,lpddr2-nvm
+ - jedec,lpddr2-s2
+ - jedec,lpddr2-s4
+ - items:
+ - pattern: "^lpddr2-[0-9a-f]{2},[0-9a-f]{4}$"
+ - enum:
+ - jedec,lpddr2-nvm
+ - jedec,lpddr2-s2
+ - jedec,lpddr2-s4
+
+ revision-id1:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 255
+ description: |
+ Revision 1 value of SDRAM chip. Obtained from device datasheet.
+ Property is deprecated, use revision-id instead.
+ deprecated: true
+
+ revision-id2:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 255
+ description: |
+ Revision 2 value of SDRAM chip. Obtained from device datasheet.
+ Property is deprecated, use revision-id instead.
+ deprecated: true
+
+ tRRD-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ Active bank a to active bank b in terms of number of clock cycles.
+ Obtained from device datasheet.
+
+ tWTR-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ Internal WRITE-to-READ command delay in terms of number of clock cycles.
+ Obtained from device datasheet.
+
+ tXP-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ Exit power-down to next valid command delay in terms of number of clock
+ cycles. Obtained from device datasheet.
+
+ tRTP-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ Internal READ to PRECHARGE command delay in terms of number of clock
+ cycles. Obtained from device datasheet.
+
+ tCKE-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ CKE minimum pulse width (HIGH and LOW pulse width) in terms of number
+ of clock cycles. Obtained from device datasheet.
+
+ tRPab-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ Row precharge time (all banks) in terms of number of clock cycles.
+ Obtained from device datasheet.
+
+ tRCD-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ RAS-to-CAS delay in terms of number of clock cycles. Obtained from
+ device datasheet.
+
+ tWR-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ WRITE recovery time in terms of number of clock cycles. Obtained from
+ device datasheet.
+
+ tRASmin-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ Row active time in terms of number of clock cycles. Obtained from device
+ datasheet.
+
+ tCKESR-min-tck:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 16
+ description: |
+ CKE minimum pulse width during SELF REFRESH (low pulse width during
+ SELF REFRESH) in terms of number of clock cycles. Obtained from device